feat(app): reconnect on foreground and keep the protocol warning

This commit is contained in:
2026-10-22 15:48:07 +01:00
parent 6b021f1483
commit 8b9a298dd1
6 changed files with 262 additions and 1 deletions
+27 -1
View File
@@ -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<PipelinesApp> createState() => _PipelinesAppState();
}
class _PipelinesAppState extends State<PipelinesApp> {
class _PipelinesAppState extends State<PipelinesApp>
with WidgetsBindingObserver {
late final AppSession _session;
late final AppRouterDelegate _delegate;
late final RouteInformationProvider _provider;
@@ -74,6 +84,7 @@ class _PipelinesAppState extends State<PipelinesApp> {
@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<PipelinesApp> {
@override
void dispose() {
WidgetsBinding.instance.removeObserver(this);
_notifications.dispose();
_delegate.dispose();
if (_ownsProvider) {
@@ -125,6 +137,20 @@ class _PipelinesAppState extends State<PipelinesApp> {
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);
@@ -11,6 +11,21 @@ import 'settings_store.dart';
/// the shared client's own `ping` request; tests inject a recorded callback.
typedef PingCallback = Future<Map<String, dynamic>> 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) {
@@ -77,6 +77,18 @@ class SettingsConnectionSection extends StatelessWidget {
SettingsStatusCard(controller: controller),
const SizedBox(height: settingsTitleGap),
const SettingsTrustWarning(),
if (controller.protocolWarning case final warning?) ...<Widget>[
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),
),
),
],
],
);
}
@@ -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<void> 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<void> resume(WidgetTester tester) async {
tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive);
tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed);
await tester.pump();
await tester.pump();
}
List<String> types(FakeChannel channel) => <String>[
for (final frame in channel.outgoing)
(jsonDecode(frame as String) as Map<String, dynamic>)['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();
});
}
@@ -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();
@@ -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(<String, dynamic>{
'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 {