diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 321be5a9..90e66d8c 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -24,6 +24,15 @@ import 'search_destination.dart'; import 'server_endpoint.dart'; import 'templates_destination.dart'; +/// The application's return-to-foreground policy for the shared socket. +/// +/// Only a socket the client dropped (disconnected) is reopened. Idle is a +/// deliberate Disconnect the operator made, so returning never undoes it, and +/// connected/connecting already have their own answer — foregrounding neither +/// churns a live socket nor restarts an attempt already in flight. +bool shouldReconnectOnForeground(ConnectionKind kind) => + kind == ConnectionKind.disconnected; + /// Composes the live application around one [AppSession] and one [Router]. /// /// Tests may inject the client and route-information provider; the session @@ -48,7 +57,8 @@ class PipelinesApp extends StatefulWidget { State createState() => _PipelinesAppState(); } -class _PipelinesAppState extends State { +class _PipelinesAppState extends State + with WidgetsBindingObserver { late final AppSession _session; late final AppRouterDelegate _delegate; late final RouteInformationProvider _provider; @@ -74,6 +84,7 @@ class _PipelinesAppState extends State { @override void initState() { super.initState(); + WidgetsBinding.instance.addObserver(this); _session = AppSession(endpoint: widget.server.uri, client: widget.client); _ownsProvider = widget.routeInformationProvider == null; _provider = @@ -116,6 +127,7 @@ class _PipelinesAppState extends State { @override void dispose() { + WidgetsBinding.instance.removeObserver(this); _notifications.dispose(); _delegate.dispose(); if (_ownsProvider) { @@ -125,6 +137,20 @@ class _PipelinesAppState extends State { super.dispose(); } + /// Returning to the foreground recovers a socket the client dropped while + /// the app was hidden. A deliberate Disconnect reaches idle and is left + /// alone, and a connected or connecting socket is not churned: only the + /// disconnected state reopens the validated endpoint now, cancelling the + /// pending backoff delay. The session's connected transition then re-sends + /// the send-only run watch (and Settings re-pings for its build/protocol + /// facts), so no screen re-subscribes on its own. + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + if (state != AppLifecycleState.resumed) return; + if (!shouldReconnectOnForeground(_session.connection.kind)) return; + unawaited(_session.retry()); + } + @override Widget build(BuildContext context) => MyApp.router(cupertino: _cupertino, routerConfig: _config); diff --git a/app/lib/features/settings/settings_controller.dart b/app/lib/features/settings/settings_controller.dart index 8d8bc715..bc834706 100644 --- a/app/lib/features/settings/settings_controller.dart +++ b/app/lib/features/settings/settings_controller.dart @@ -11,6 +11,21 @@ import 'settings_store.dart'; /// the shared client's own `ping` request; tests inject a recorded callback. typedef PingCallback = Future> Function(); +/// The integer wire protocol this app speaks. Mirrors `PROTOCOL_VERSION` in +/// `web/src/protocol.js` and `ProtocolVersion` in `internal/protocol/identity.go`. +const int clientProtocolVersion = 1; + +/// The warning naming both values when the last `pong` reported a different +/// protocol. A server that omits the field (an older build) is never flagged, +/// and the values are compared as numbers, never as strings — the web's +/// `protocolMismatch` rule. +String? protocolMismatchWarning(num? serverProtocol) { + if (serverProtocol == null) return null; + if (serverProtocol == clientProtocolVersion) return null; + return 'Protocol mismatch: this page speaks protocol ' + '$clientProtocolVersion, the server reports $serverProtocol.'; +} + /// Owns the Settings screen's draft text, validation and the actions that drive /// the shared [transport.PipelinesClient]. /// @@ -55,6 +70,7 @@ class SettingsController extends ChangeNotifier { String _buildVersion = ''; String _buildCommit = ''; String _serverTime = ''; + num? _serverProtocol; String _pingError = ''; bool _pingInFlight = false; bool _pingRequestedForConnected = false; @@ -76,6 +92,12 @@ class SettingsController extends ChangeNotifier { String get buildVersion => _buildVersion; String get buildCommit => _buildCommit; String get serverTime => _serverTime; + + /// The warning for a last `pong` whose protocol differs from this app's. + /// The last reported value is kept across a drop (as the web Settings page + /// keeps `serverProtocol`), so a foreground reconnect cannot hide a known + /// mismatch while the new socket is still connecting. + String? get protocolWarning => protocolMismatchWarning(_serverProtocol); String get pingError => _pingError; bool get pingInFlight => _pingInFlight; @@ -236,6 +258,7 @@ class SettingsController extends ChangeNotifier { : '${build ?? ''}'.trim(); _buildCommit = build is Map ? '${build['commit'] ?? ''}'.trim() : ''; _serverTime = '${reply['time'] ?? ''}'.trim(); + _serverProtocol = _reportedProtocol(reply['protocol']); _pingError = ''; } catch (error) { if (!_isCurrentPing(token)) return; @@ -251,6 +274,16 @@ class SettingsController extends ChangeNotifier { bool _isCurrentPing(int token) => !_disposed && token == _pingToken && _pingRequestedForConnected; + /// The `pong.protocol` value as the number the comparison needs. A missing, + /// blank or non-numeric value is absent — never coerced to zero, which would + /// invent a mismatch. + num? _reportedProtocol(Object? value) { + if (value is num) return value; + final text = '${value ?? ''}'.trim(); + if (text.isEmpty) return null; + return num.tryParse(text); + } + void _clearPingDetails() { _pingRequestedForConnected = false; _pingInFlight = false; @@ -258,6 +291,9 @@ class SettingsController extends ChangeNotifier { _buildVersion = ''; _buildCommit = ''; _serverTime = ''; + // _serverProtocol is deliberately retained: it belongs to the server the + // last pong described, and its warning must stay visible through the + // reconnect the app performs when it returns to the foreground. } String _describe(Object error) { diff --git a/app/lib/features/settings/settings_sections.dart b/app/lib/features/settings/settings_sections.dart index 4bf9581f..35c112e8 100644 --- a/app/lib/features/settings/settings_sections.dart +++ b/app/lib/features/settings/settings_sections.dart @@ -77,6 +77,18 @@ class SettingsConnectionSection extends StatelessWidget { SettingsStatusCard(controller: controller), const SizedBox(height: settingsTitleGap), const SettingsTrustWarning(), + if (controller.protocolWarning case final warning?) ...[ + const SizedBox(height: settingsTitleGap), + // The web page appends the same alert after the trust card. A live + // region announces a mismatch the operator did not ask to reveal. + Semantics( + liveRegion: true, + child: Text( + warning, + style: settingsTextStyle(context, error: true), + ), + ), + ], ], ); } diff --git a/app/test/application/app_lifecycle_reconnect_test.dart b/app/test/application/app_lifecycle_reconnect_test.dart new file mode 100644 index 00000000..e2fff246 --- /dev/null +++ b/app/test/application/app_lifecycle_reconnect_test.dart @@ -0,0 +1,123 @@ +import 'dart:convert'; + +import 'package:flutter/widgets.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/application/pipelines_app.dart'; +import 'package:pipelines_app/core/transport/pipelines_client.dart'; + +import '../core/transport/pipelines_client_test.dart' show FakeChannel; +import '../features/pipelines/fixtures.dart'; +import 'pipelines_app_test.dart' show webServer; +import 'pipelines_replies.dart'; + +Future pumpApp( + WidgetTester tester, { + required PlatformRouteInformationProvider provider, + required PipelinesClient client, +}) async { + await tester.pumpWidget( + PipelinesApp( + server: webServer(), + client: client, + cupertino: false, + routeInformationProvider: provider, + ), + ); + await tester.pump(); +} + +PlatformRouteInformationProvider routeProvider() { + final provider = PlatformRouteInformationProvider( + initialRouteInformation: RouteInformation(uri: Uri.parse('/pipelines')), + ); + addTearDown(provider.dispose); + return provider; +} + +/// The app receives a real return-to-foreground as the engine's lifecycle +/// transition does: backgrounded, then resumed. +Future resume(WidgetTester tester) async { + tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive); + tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed); + await tester.pump(); + await tester.pump(); +} + +List types(FakeChannel channel) => [ + for (final frame in channel.outgoing) + (jsonDecode(frame as String) as Map)['type'] as String, +]; + +void main() { + tearDown(() { + WidgetsBinding.instance.handleAppLifecycleStateChanged( + AppLifecycleState.resumed, + ); + }); + + test('only a dropped socket is reopened on foreground', () { + expect( + shouldReconnectOnForeground(ConnectionKind.disconnected), + isTrue, + ); + // A deliberate Disconnect reaches idle and must stay disconnected. + expect(shouldReconnectOnForeground(ConnectionKind.idle), isFalse); + // These states already have their own answer; foregrounding does not churn + // a live socket or restart an attempt that is already in flight. + expect(shouldReconnectOnForeground(ConnectionKind.connected), isFalse); + expect(shouldReconnectOnForeground(ConnectionKind.connecting), isFalse); + }); + + testWidgets( + 'foreground resume reopens a dropped socket and re-watches it once', + (tester) async { + final first = FakeChannel()..readyCompleter.complete(); + final second = FakeChannel()..readyCompleter.complete(); + var sockets = 0; + final client = PipelinesClient( + channelFactory: (_) => sockets++ == 0 ? first : second, + // Keep the client's own backoff retry far away, so the new socket can + // only come from the foreground transition under test. + backoffBase: const Duration(minutes: 1), + ); + await pumpApp(tester, provider: routeProvider(), client: client); + await replyPipelines(tester, first, PipelineFixture()); + expect(sockets, 1); + expect(types(first), contains('subscribe')); + expect(client.state.kind, ConnectionKind.connected); + + first.incoming.addError(StateError('network drop')); + await tester.pump(); + await tester.pump(); + expect(client.state.kind, ConnectionKind.disconnected); + expect(sockets, 1, reason: 'the backoff retry is still pending'); + + await resume(tester); + + expect(sockets, 2); + expect(types(second), contains('subscribe')); + expect(client.state.kind, ConnectionKind.connected); + + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pump(); + }, + ); + + testWidgets('foreground resume does not churn a still-connected socket', ( + tester, + ) async { + final channel = FakeChannel()..readyCompleter.complete(); + final client = PipelinesClient(channelFactory: (_) => channel); + await pumpApp(tester, provider: routeProvider(), client: client); + await replyPipelines(tester, channel, PipelineFixture()); + expect(types(channel).where((type) => type == 'subscribe'), hasLength(1)); + + await resume(tester); + + expect(types(channel).where((type) => type == 'subscribe'), hasLength(1)); + expect(client.state.kind, ConnectionKind.connected); + + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pump(); + }); +} diff --git a/app/test/application/settings_registration_test.dart b/app/test/application/settings_registration_test.dart index d54304be..2172f144 100644 --- a/app/test/application/settings_registration_test.dart +++ b/app/test/application/settings_registration_test.dart @@ -76,11 +76,20 @@ void main() { 'type': 'pong', 'build': {'version': 'settings-fixture'}, 'time': 'fixture time', + 'protocol': 2, }), ); await tester.pump(); await tester.pump(); expect(find.textContaining('settings-fixture'), findsOneWidget); + expect( + find.text( + 'Protocol mismatch: this page speaks protocol 1, ' + 'the server reports 2.', + ), + findsOneWidget, + reason: 'a mismatched server must stay visibly flagged in Settings', + ); expect(tester.takeException(), isNull); await tester.pumpWidget(const SizedBox.shrink()); await tester.pump(); diff --git a/app/test/features/settings/settings_controller_test.dart b/app/test/features/settings/settings_controller_test.dart index bf03672e..50479e86 100644 --- a/app/test/features/settings/settings_controller_test.dart +++ b/app/test/features/settings/settings_controller_test.dart @@ -406,6 +406,61 @@ void main() { await client.dispose(); }); + test( + 'a mismatched protocol warns and the warning survives a drop', + () async { + final factory = FakeChannelFactory(); + final client = transport.PipelinesClient(channelFactory: factory.call); + final controller = SettingsController( + client: client, + store: MemorySettingsStore(), + ); + await controller.initialize(); + controller.updateServerUrl('ws://example.test:8123'); + final connecting = controller.connect(); + await settle(); + factory.last.markReady(); + await connecting; + await settle(); + expect(controller.protocolWarning, isNull); + + factory.last.reply({ + 'id': factory.last.decodedOutgoing.single['id'], + 'type': 'pong', + // The server sends an integer, but the comparison is numeric, like the + // web page's Number() rule. + 'protocol': '2', + }); + await settle(); + expect( + controller.protocolWarning, + 'Protocol mismatch: this page speaks protocol 1, ' + 'the server reports 2.', + ); + + factory.last.fail('socket gone'); + await settle(); + expect(controller.connection.kind, transport.ConnectionKind.disconnected); + expect( + controller.protocolWarning, + isNotNull, + reason: 'a known mismatch stays visible while the socket reconnects', + ); + + // Cancel the client's scheduled retry before the test ends. + await client.disconnect(); + controller.dispose(); + await client.dispose(); + }, + ); + + test('protocolMismatchWarning ignores matching and absent protocols', () { + expect(protocolMismatchWarning(null), isNull); + expect(protocolMismatchWarning(1), isNull); + expect(protocolMismatchWarning(1.0), isNull); + expect(protocolMismatchWarning(2), contains('the server reports 2')); + }); + test( 'workspace save persists only an absolute path and reports failures', () async {