merge(app): land verified socket transport foundation

This commit is contained in:
2026-10-21 13:29:07 +01:00
7 changed files with 666 additions and 0 deletions
@@ -0,0 +1,27 @@
enum ConnectionKind { idle, connecting, connected, disconnected }
class ConnectionState {
const ConnectionState(
this.kind, {
this.attempt = 0,
this.reason = '',
this.retrying = false,
});
final ConnectionKind kind;
final int attempt;
final String reason;
final bool retrying;
}
class ProtocolError implements Exception {
const ProtocolError(this.message);
final String message;
@override
String toString() => message;
}
class NotConnectedError implements Exception {
const NotConnectedError();
@override
String toString() => 'Not connected to the Pipelines server';
}
@@ -0,0 +1,246 @@
import 'dart:async';
import 'dart:convert';
import 'package:web_socket_channel/web_socket_channel.dart';
import '../api_gateway.dart';
import 'connection_state.dart';
import 'server_url.dart';
export 'connection_state.dart';
typedef ChannelFactory = WebSocketChannel Function(Uri uri);
/// One correlated websocket transport shared by all feature gateways.
class PipelinesClient implements ApiGateway {
PipelinesClient({
ChannelFactory? channelFactory,
this.requestTimeout = const Duration(seconds: 30),
this.backoffBase = const Duration(seconds: 1),
this.backoffMax = const Duration(seconds: 30),
}) : _factory = channelFactory ?? WebSocketChannel.connect;
final ChannelFactory _factory;
final Duration requestTimeout, backoffBase, backoffMax;
final _frames = StreamController<JsonMap>.broadcast();
final _states = StreamController<ConnectionState>.broadcast();
final Map<String, Completer<JsonMap>> _pending = {};
WebSocketChannel? _channel;
StreamSubscription<dynamic>? _subscription;
Uri? _endpoint;
Timer? _reconnect;
int _generation = 0, _sequence = 0, _attempt = 0;
bool _manual = true, _disposed = false;
ConnectionState _state = const ConnectionState(ConnectionKind.idle);
Future<void> _queue = Future.value();
@override
Stream<JsonMap> get frames => _frames.stream;
Stream<ConnectionState> get states => _states.stream;
ConnectionState get state => _state;
Future<void> connect(Uri uri) async {
if (_disposed) throw StateError('Client has been disposed');
final endpoint = ServerUrl.validate(uri.toString());
_endpoint = Uri.parse(endpoint.wsUrl);
_manual = false;
_attempt = 0;
_reconnect?.cancel();
await _open();
}
Future<void> _open() async {
final endpoint = _endpoint;
if (endpoint == null || _disposed) return;
final generation = ++_generation;
_setState(ConnectionState(ConnectionKind.connecting, attempt: ++_attempt));
final old = _channel;
_channel = null;
_failPending('Connection replaced');
if (old != null) unawaited(old.sink.close());
final subscription = _subscription;
_subscription = null;
await subscription?.cancel();
if (generation != _generation || _manual || _disposed) return;
try {
final channel = _factory(endpoint);
_channel = channel;
_subscription = channel.stream.listen(
(data) {
if (generation == _generation) _onMessage(data);
},
onError: (Object error) {
if (generation == _generation) _closed(error.toString());
},
onDone: () {
if (generation == _generation) _closed('Connection closed');
},
);
await channel.ready;
if (generation != _generation) return;
_attempt = 0;
_setState(const ConnectionState(ConnectionKind.connected));
} catch (error) {
if (generation == _generation) _closed(error.toString());
}
}
void _setState(ConnectionState value) {
_state = value;
if (!_states.isClosed) _states.add(value);
}
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) {
final completer = Completer<JsonMap>();
final generation = _generation;
final snapshot = Map<String, dynamic>.of(fields);
final run = _queue.then(
(_) => _sendCall(type, snapshot, completer, generation),
);
_queue = run.catchError((_) {});
return completer.future;
}
Future<void> _sendCall(
String type,
JsonMap fields,
Completer<JsonMap> result,
int generation,
) async {
if (generation != _generation) {
result.completeError(StateError('Connection replaced'));
return;
}
final channel = _channel;
if (channel == null || _state.kind != ConnectionKind.connected) {
result.completeError(const NotConnectedError());
return;
}
final id = 'flutter-${++_sequence}';
_pending[id] = result;
final timer = Timer(requestTimeout, () {
if (_pending.remove(id) != null) {
result.completeError(
TimeoutException(
'request timed out after ${requestTimeout.inMilliseconds}ms',
),
);
}
});
result.future.then<void>(
(_) => timer.cancel(),
onError: (Object error, StackTrace stack) => timer.cancel(),
);
try {
channel.sink.add(jsonEncode({...fields, 'type': type, 'id': id}));
} catch (error) {
timer.cancel();
if (_pending.remove(id) != null) result.completeError(error);
}
// Match the existing client's serialized request semantics, even on errors.
try {
await result.future;
} catch (_) {
/* The caller receives the error. */
}
}
String sendOnly(String type, [JsonMap fields = const {}]) {
final channel = _channel;
if (channel == null || _state.kind != ConnectionKind.connected) {
throw const NotConnectedError();
}
final id = 'flutter-${++_sequence}';
channel.sink.add(jsonEncode({...fields, 'type': type, 'id': id}));
return id;
}
void _onMessage(dynamic data) {
if (data is! String) return;
final Object? decoded;
try {
decoded = jsonDecode(data);
} on FormatException {
return;
}
if (decoded is! Map<String, dynamic>) return;
final message = decoded;
final id = message['id'];
final pending = id is String ? _pending.remove(id) : null;
if (pending != null) {
if (message['type'] == 'error') {
final reason = '${message['error'] ?? ''}'.trim();
pending.completeError(
ProtocolError(reason.isEmpty ? 'server error' : reason),
);
} else {
pending.complete(message);
}
} else if (!_frames.isClosed) {
_frames.add(message);
}
}
void _failPending(String reason) {
final values = _pending.values.toList();
_pending.clear();
for (final item in values) {
if (!item.isCompleted) item.completeError(StateError(reason));
}
}
void _closed(String reason) {
_generation++;
final channel = _channel;
final subscription = _subscription;
_channel = null;
_subscription = null;
if (subscription != null) unawaited(subscription.cancel());
if (channel != null) unawaited(channel.sink.close().catchError((_) {}));
_failPending(reason);
if (_manual || _disposed) {
_setState(const ConnectionState(ConnectionKind.idle));
return;
}
_setState(
ConnectionState(
ConnectionKind.disconnected,
attempt: _attempt,
reason: reason,
retrying: true,
),
);
final shift = (_attempt - 1).clamp(0, 6);
final delay = backoffBase * (1 << shift);
_reconnect?.cancel();
_reconnect = Timer(
delay > backoffMax ? backoffMax : delay,
() => unawaited(_open()),
);
}
Future<void> disconnect() async {
_manual = true;
_reconnect?.cancel();
final generation = ++_generation;
final channel = _channel;
_channel = null;
final subscription = _subscription;
_subscription = null;
_failPending('Disconnected');
await subscription?.cancel();
if (channel != null) await channel.sink.close();
if (generation == _generation) {
_setState(const ConnectionState(ConnectionKind.idle));
}
}
Future<void> dispose() async {
if (_disposed) return;
_disposed = true;
await disconnect();
await _frames.close();
await _states.close();
}
}
+90
View File
@@ -0,0 +1,90 @@
/// Validation result for a configured Pipelines websocket endpoint.
class ServerUrl {
const ServerUrl._({
required this.wsUrl,
required this.httpUrl,
required this.host,
required this.port,
required this.secure,
});
final String wsUrl;
final String httpUrl;
final String host;
final int port;
final bool secure;
static ServerUrl validate(String raw) {
final value = raw.trim();
if (value.isEmpty) {
throw const FormatException(
'Enter the Pipelines server URL, for example ws://192.168.1.20:8081/connect',
);
}
final uri = Uri.tryParse(value);
if (uri == null || !uri.hasScheme) {
throw const FormatException('That is not a valid URL.');
}
final scheme = uri.scheme.toLowerCase();
if (scheme != 'ws' && scheme != 'wss') {
throw FormatException(
'Unsupported scheme "$scheme"; use ws:// (trusted LAN/VPN) or wss://',
);
}
if (uri.userInfo.isNotEmpty) {
throw const FormatException(
'Credentials are not supported; the server has no authentication. Remove userinfo from the URL',
);
}
if (uri.hasFragment) {
throw const FormatException(
'Remove the # fragment; it is not part of the server endpoint',
);
}
if (uri.host.isEmpty) {
throw const FormatException(
'The URL is missing a host, for example ws://192.168.1.20:8081/connect',
);
}
if (!uri.hasAuthority ||
(uri.hasPort && (uri.port < 1 || uri.port > 65535))) {
throw const FormatException(
'That is not a valid server authority or port.',
);
}
final secure = scheme == 'wss';
final port = uri.hasPort
? uri.port
: secure
? 443
: 80;
final path = uri.path.isEmpty || uri.path == '/' ? '/connect' : uri.path;
final normalized = uri.replace(scheme: scheme, path: path);
return ServerUrl._(
wsUrl: normalized.toString(),
httpUrl: normalized.replace(scheme: secure ? 'https' : 'http').toString(),
host: uri.host,
port: port,
secure: secure,
);
}
static Uri? resolveArtifactUrl(String configured, String artifactUrl) {
final path = artifactUrl.trim();
if (path.isEmpty) return null;
final parsed = Uri.tryParse(path);
if (parsed != null &&
(parsed.scheme == 'http' || parsed.scheme == 'https')) {
return parsed;
}
try {
final endpoint = validate(configured);
final origin = Uri.parse(
endpoint.httpUrl,
).replace(path: '/', query: null);
return origin.resolve(path.replaceFirst(RegExp(r'^/+'), ''));
} on FormatException {
return null;
}
}
}
+21
View File
@@ -0,0 +1,21 @@
# F1 transport
`PipelinesClient` implements the shared `ApiGateway` contract using one
`web_socket_channel` connection, correlated JSON replies, timeout handling,
unsolicited envelope broadcast, and reconnect with capped exponential backoff.
The URL helper validates ws/wss endpoints and resolves artifact URLs.
Manager integration import: `package:pipelines_app/core/transport/pipelines_client.dart`;
endpoint helper: `package:pipelines_app/core/transport/server_url.dart`.
The client accepts an injected `ChannelFactory` for deterministic tests. No live
server was used. Browser and mobile target verification should be reported
separately from these unit tests.
## Manager verification
Expanded to 12 focused tests, including serialized requests, queue recovery
after protocol errors/timeouts, late replies, replacement of queued requests,
send-only subscriptions, concurrent connects, reconnect and disposal. Corrected
generation races and socket cleanup; URI construction now retains bracketed
IPv6 hosts and encoded artifact query strings. Analyze passes after formatting.
These are unit checks, not browser/live-server acceptance or mobile verification.
@@ -0,0 +1,144 @@
import 'dart:async';
import 'dart:convert';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/transport/pipelines_client.dart';
import 'pipelines_client_test.dart' show FakeChannel;
Future<void> flush() => Future<void>.delayed(Duration.zero);
Map<String, dynamic> sent(FakeChannel channel, [int index = 0]) =>
jsonDecode(channel.outgoing[index] as String) as Map<String, dynamic>;
void reply(FakeChannel channel, {int index = 0, String type = 'pong'}) =>
channel.incoming.add(
jsonEncode({'id': sent(channel, index)['id'], 'type': type}),
);
void main() {
test(
'requests serialize through replies, errors do not poison queue',
() async {
final channel = FakeChannel()..readyCompleter.complete();
final client = PipelinesClient(channelFactory: (_) => channel);
await client.connect(Uri.parse('ws://example.test'));
final first = client.call('ping');
final firstError = expectLater(first, throwsA(isA<ProtocolError>()));
final second = client.call('list_runs');
await flush();
expect(channel.outgoing, hasLength(1));
channel.incoming.add(
jsonEncode({
'id': sent(channel)['id'],
'type': 'error',
'error': 'refused',
}),
);
await firstError;
await flush();
expect(channel.outgoing, hasLength(2));
reply(channel, index: 1, type: 'runs');
expect((await second)['type'], 'runs');
await client.dispose();
},
);
test(
'timeout releases queue and late response is an unsolicited frame',
() async {
final channel = FakeChannel()..readyCompleter.complete();
final client = PipelinesClient(
channelFactory: (_) => channel,
requestTimeout: const Duration(milliseconds: 10),
);
await client.connect(Uri.parse('ws://example.test'));
await expectLater(client.call('ping'), throwsA(isA<TimeoutException>()));
final late = client.frames.first;
reply(channel);
expect((await late)['type'], 'pong');
await client.dispose();
},
);
test(
'replacement fails queued calls rather than sending on new socket',
() async {
final channels = [
FakeChannel()..readyCompleter.complete(),
FakeChannel()..readyCompleter.complete(),
];
var index = 0;
final client = PipelinesClient(channelFactory: (_) => channels[index++]);
await client.connect(Uri.parse('ws://old.test'));
final firstError = expectLater(client.call('ping'), throwsStateError);
final queuedError = expectLater(
client.call('list_runs'),
throwsStateError,
);
await flush();
await client.connect(Uri.parse('ws://new.test'));
await Future.wait([firstError, queuedError]);
expect(channels.last.outgoing, isEmpty);
expect(client.state.kind, ConnectionKind.connected);
await client.dispose();
},
);
test('sendOnly never blocks correlated requests', () async {
final channel = FakeChannel()..readyCompleter.complete();
final client = PipelinesClient(channelFactory: (_) => channel);
await client.connect(Uri.parse('ws://example.test'));
client.sendOnly('subscribe', {'workspace': ''});
final ping = client.call('ping');
await flush();
expect(sent(channel)['type'], 'subscribe');
reply(channel, index: 1);
expect((await ping)['type'], 'pong');
await client.dispose();
});
test('overlapping connect cannot create a superseded socket', () async {
var factories = 0;
final channel = FakeChannel()..readyCompleter.complete();
final client = PipelinesClient(
channelFactory: (_) {
factories++;
return channel;
},
);
await Future.wait([
client.connect(Uri.parse('ws://old.test')),
client.connect(Uri.parse('ws://new.test')),
]);
expect(factories, 1);
expect(client.state.kind, ConnectionKind.connected);
await client.dispose();
await expectLater(
client.connect(Uri.parse('ws://new.test')),
throwsStateError,
);
});
test('socket failure reconnects, disconnect cancels retry', () async {
final first = FakeChannel()..readyCompleter.complete();
final next = FakeChannel()..readyCompleter.complete();
var factories = 0;
final client = PipelinesClient(
channelFactory: (_) => factories++ == 0 ? first : next,
backoffBase: const Duration(milliseconds: 5),
);
await client.connect(Uri.parse('ws://example.test'));
final connectedAgain = client.states.firstWhere(
(s) => s.kind == ConnectionKind.connected,
);
first.incoming.addError(StateError('network drop'));
await connectedAgain.timeout(const Duration(seconds: 2));
expect(factories, 2);
await client.disconnect();
expect(client.state.retrying, isFalse);
expect(
() => client.sendOnly('subscribe'),
throwsA(isA<NotConnectedError>()),
);
await client.dispose();
});
}
@@ -0,0 +1,87 @@
import 'dart:async';
import 'dart:convert';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/transport/pipelines_client.dart';
import 'package:web_socket_channel/web_socket_channel.dart';
class FakeChannel implements WebSocketChannel {
final incoming = StreamController<dynamic>();
final outgoing = <dynamic>[];
final readyCompleter = Completer<void>();
@override
Stream<dynamic> get stream => incoming.stream;
@override
WebSocketSink get sink => FakeSink(outgoing, incoming);
@override
Future<void> get ready => readyCompleter.future;
@override
String? get protocol => null;
@override
int? get closeCode => null;
@override
String? get closeReason => null;
@override
noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
}
class FakeSink implements WebSocketSink {
FakeSink(this.outgoing, this.incoming);
final List<dynamic> outgoing;
final StreamController<dynamic> incoming;
@override
void add(dynamic event) => outgoing.add(event);
@override
void addError(Object error, [StackTrace? stackTrace]) => throw error;
@override
Future<void> addStream(Stream<dynamic> stream) async {
await for (final item in stream) {
add(item);
}
}
@override
Future<void> close([int? closeCode, String? closeReason]) async {
await incoming.close();
}
@override
Future<void> get done async {}
@override
noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
}
void main() {
test('correlates replies and broadcasts unclaimed frames', () async {
final channel = FakeChannel();
final client = PipelinesClient(channelFactory: (_) => channel);
final frames = <Map<String, dynamic>>[];
client.frames.listen(frames.add);
final connecting = client.connect(Uri.parse('ws://example.test'));
channel.readyCompleter.complete();
await connecting;
final request = client.call('ping', {'value': 1});
await Future<void>.delayed(Duration.zero);
final sent =
jsonDecode(channel.outgoing.single as String) as Map<String, dynamic>;
channel.incoming.add(jsonEncode({'id': sent['id'], 'type': 'pong'}));
expect((await request)['type'], 'pong');
channel.incoming.add(jsonEncode({'type': 'run_event'}));
await Future<void>.delayed(Duration.zero);
expect(frames.single['type'], 'run_event');
await client.dispose();
});
test('disconnect fails pending requests', () async {
final channel = FakeChannel();
final client = PipelinesClient(channelFactory: (_) => channel);
final connecting = client.connect(Uri.parse('ws://example.test'));
channel.readyCompleter.complete();
await connecting;
final pending = client.call('ping');
await Future<void>.delayed(Duration.zero);
await client.disconnect();
await expectLater(pending, throwsA(isA<StateError>()));
await client.dispose();
});
}
@@ -0,0 +1,51 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/transport/server_url.dart';
void main() {
test('IPv6 authorities and encoded artifact queries stay intact', () {
expect(
ServerUrl.validate('ws://[::1]:8081').wsUrl,
'ws://[::1]:8081/connect',
);
expect(
ServerUrl.resolveArtifactUrl(
'ws://[::1]:8081/connect',
'/artifacts/a%20b?download=1',
).toString(),
'http://[::1]:8081/artifacts/a%20b?download=1',
);
expect(() => ServerUrl.validate('ws://host:70000'), throwsFormatException);
});
test('validates and normalizes endpoint with path and query', () {
final value = ServerUrl.validate(' wss://example.test:8443/?token=x ');
expect(value.wsUrl, 'wss://example.test:8443/connect?token=x');
expect(value.httpUrl, 'https://example.test:8443/connect?token=x');
expect(value.secure, isTrue);
});
test('rejects unsupported schemes and credentials', () {
expect(
() => ServerUrl.validate('https://example.test'),
throwsFormatException,
);
expect(
() => ServerUrl.validate('ws://user:pass@example.test'),
throwsFormatException,
);
});
test('resolves relative artifacts at the server origin', () {
expect(
ServerUrl.resolveArtifactUrl(
'ws://example.test:8081/connect',
'/artifacts/a',
)!.toString(),
'http://example.test:8081/artifacts/a',
);
expect(ServerUrl.resolveArtifactUrl('', '/artifacts/a'), isNull);
expect(
ServerUrl.resolveArtifactUrl('', 'https://cdn.test/a')!.toString(),
'https://cdn.test/a',
);
});
}