diff --git a/app/lib/core/transport/pipelines_client.dart b/app/lib/core/transport/pipelines_client.dart new file mode 100644 index 00000000..923b66f3 --- /dev/null +++ b/app/lib/core/transport/pipelines_client.dart @@ -0,0 +1,183 @@ +import 'dart:async'; +import 'dart:convert'; + +import 'package:web_socket_channel/web_socket_channel.dart'; + +import '../api_gateway.dart'; +import 'server_url.dart'; + +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'; +} + +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.broadcast(); + final _states = StreamController.broadcast(); + final Map> _pending = {}; + WebSocketChannel? _channel; + StreamSubscription? _subscription; + Uri? _endpoint; + Timer? _reconnect; + int _generation = 0, _sequence = 0, _attempt = 0; + bool _manual = true, _disposed = false; + ConnectionState _state = const ConnectionState(ConnectionKind.idle); + Future _queue = Future.value(); + + @override + Stream get frames => _frames.stream; + Stream get states => _states.stream; + ConnectionState get state => _state; + + Future 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 _open() async { + final endpoint = _endpoint; + if (endpoint == null || _disposed) return; + final generation = ++_generation; + _setState(ConnectionState(ConnectionKind.connecting, attempt: ++_attempt)); + final old = _channel; + _channel = null; + await _subscription?.cancel(); + _failPending('Connection replaced'); + if (old != null) unawaited(old.sink.close()); + 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 call(String type, [JsonMap fields = const {}]) { + final completer = Completer(); + final run = _queue.then((_) => _sendCall(type, fields, completer)); + _queue = run.catchError((_) {}); + return completer.future; + } + + Future _sendCall(String type, JsonMap fields, Completer result) async { + 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((_) => 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); + } + } + + 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) 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'] as String? ?? '').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++; + _channel = null; + _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 disconnect() async { + _manual = true; _reconnect?.cancel(); _generation++; + final channel = _channel; _channel = null; + await _subscription?.cancel(); _subscription = null; + _failPending('Disconnected'); + if (channel != null) await channel.sink.close(); + _setState(const ConnectionState(ConnectionKind.idle)); + } + + Future dispose() async { + if (_disposed) return; + await disconnect(); _disposed = true; + await _frames.close(); await _states.close(); + } +} diff --git a/app/lib/core/transport/server_url.dart b/app/lib/core/transport/server_url.dart new file mode 100644 index 00000000..7f2eb59b --- /dev/null +++ b/app/lib/core/transport/server_url.dart @@ -0,0 +1,47 @@ +/// 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'); + final secure = scheme == 'wss'; + final port = uri.hasPort ? uri.port : secure ? 443 : 80; + final path = uri.path.isEmpty || uri.path == '/' ? '/connect' : uri.path; + final authority = uri.hasPort ? '${uri.host}:$port' : uri.host; + final suffix = uri.hasQuery ? '?${uri.query}' : ''; + return ServerUrl._(wsUrl: '$scheme://$authority$path$suffix', + httpUrl: '${secure ? 'https' : 'http'}://$authority$path$suffix', + 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 portPart = endpoint.port != (endpoint.secure ? 443 : 80) ? ':${endpoint.port}' : ''; + return Uri.parse('${endpoint.secure ? 'https' : 'http'}://${endpoint.host}$portPart/${path.replaceFirst(RegExp(r'^/+'), '')}'); + } on FormatException { + return null; + } + } +} diff --git a/app/notes/F1.md b/app/notes/F1.md new file mode 100644 index 00000000..269e2685 --- /dev/null +++ b/app/notes/F1.md @@ -0,0 +1,13 @@ +# 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. diff --git a/app/test/core/transport/pipelines_client_test.dart b/app/test/core/transport/pipelines_client_test.dart new file mode 100644 index 00000000..01840d05 --- /dev/null +++ b/app/test/core/transport/pipelines_client_test.dart @@ -0,0 +1,78 @@ +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(); + final outgoing = []; + final readyCompleter = Completer(); + @override + Stream get stream => incoming.stream; + @override + WebSocketSink get sink => FakeSink(outgoing, incoming); + @override + Future 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 outgoing; + final StreamController incoming; + @override + void add(dynamic event) => outgoing.add(event); + @override + void addError(Object error, [StackTrace? stackTrace]) => throw error; + @override + Future addStream(Stream stream) async { await for (final item in stream) { add(item); } } + @override + Future close([int? closeCode, String? closeReason]) async { await incoming.close(); } + @override + Future 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 = >[]; + 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.delayed(Duration.zero); + final sent = jsonDecode(channel.outgoing.single as String) as Map; + channel.incoming.add(jsonEncode({'id': sent['id'], 'type': 'pong'})); + expect((await request)['type'], 'pong'); + channel.incoming.add(jsonEncode({'type': 'run_event'})); + await Future.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.delayed(Duration.zero); + await client.disconnect(); + await expectLater(pending, throwsA(isA())); + await client.dispose(); + }); +} diff --git a/app/test/core/transport/server_url_test.dart b/app/test/core/transport/server_url_test.dart new file mode 100644 index 00000000..b7773d31 --- /dev/null +++ b/app/test/core/transport/server_url_test.dart @@ -0,0 +1,23 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/transport/server_url.dart'; + +void main() { + 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'); + }); +}