diff --git a/packages/jaspr/CHANGELOG.md b/packages/jaspr/CHANGELOG.md index e9c2ce9c6..fb4c498a2 100644 --- a/packages/jaspr/CHANGELOG.md +++ b/packages/jaspr/CHANGELOG.md @@ -4,6 +4,7 @@ - Fixed a server built with `dart build cli` on Linux with Dart 3.14 or later not finding its `web` directory and failing with "Could not resolve project directory containing pubspec.yaml" when no `pubspec.yaml` is above it. Since Dart 3.14 such a bundle keeps the snapshot in `lib/libdartaot.so`, which `Platform.script` points at. - Fixed `jaspr serve` with Flutter embedding or plugins failing on Flutter 3.50, which moved the precompiled DDC SDK to `kernel/ddc/canary` and `kernel/ddc/stable`. +- Fixed a browser that `jaspr serve` skipped because it didn't respond in time (e.g. a tab in the background) showing outdated content until the next change. It now catches up on the reload it missed as soon as it responds again. ## 0.24.0-beta.1 diff --git a/packages/jaspr_cli/lib/src/dev/client_manager.dart b/packages/jaspr_cli/lib/src/dev/client_manager.dart index 83047005c..52771a4a6 100644 --- a/packages/jaspr_cli/lib/src/dev/client_manager.dart +++ b/packages/jaspr_cli/lib/src/dev/client_manager.dart @@ -9,6 +9,7 @@ import 'package:vm_service/vm_service.dart' as vm; import 'package:vm_service/vm_service_io.dart'; import '../logging.dart'; +import '../project.dart'; import 'client_call_guard.dart'; import 'dev_workflow.dart'; @@ -100,6 +101,21 @@ class ClientManager { } } +/// An update the dev workflow applies to the connected clients. +/// +/// The values are ordered by how much of the page they replace, +/// so a later update includes the ones before it. +enum ClientUpdate { + /// A hot reload, which keeps the state of the app. + reload, + + /// A hot restart, which runs the app from the start. + restart, + + /// A full reload of the page. + refresh, +} + class ClientConnection { ClientConnection(this.appConnection, this.dwds, this.manager); @@ -125,18 +141,18 @@ class ClientConnection { tag: .client, level: .warning, ), - onResponsive: () { - manager.workflow.logger.write( - 'Client ${appConnection.request.appId} is responding again, it may show outdated content until the next reload.', - tag: .client, - ); - // Changed stylesheets aren't part of the next reload, so deliver them now. - if (_pendingStylesheets.isNotEmpty && !_isDisposed) { - unawaited(reloadStylesheets(const [])); - } - }, + onResponsive: () => unawaited(_catchUp()), ); + /// The update this client missed while it didn't respond. + ClientUpdate? _missedUpdate; + + /// Whether this client is applying what it missed while it didn't respond. + bool _isCatchingUp = false; + + /// Whether updates skip this client because it doesn't have the previous ones yet. + bool get _isBehind => _callGuard.isUnresponsive || _isCatchingUp; + /// Stylesheets that changed while this client didn't receive them. final Set _pendingStylesheets = {}; @@ -229,19 +245,124 @@ class ClientConnection { } } - Future restart() => _callGuard.run(() async { + /// Applies [update] to this client and returns whether it succeeded. + /// + /// A client that doesn't respond in time is skipped, + /// and catches up on [update] once it responds again. + Future update(ClientUpdate update) async { + if (_isBehind) { + _markMissed(update); + return false; + } + + // Include an update that the catch-up couldn't apply. + _markMissed(update); + final pending = _missedUpdate!; + _missedUpdate = null; + + final succeeded = await _apply(pending, _callGuard.run); + // A refresh that timed out still reloads the page once it gets through, + // so there is nothing left to catch up on. + if (_callGuard.isUnresponsive && pending != .refresh) { + _markMissed(pending); + } + return succeeded; + } + + void _markMissed(ClientUpdate update) { + final missed = _missedUpdate; + if (missed == null || update.index > missed.index) { + _missedUpdate = update; + } + } + + /// Applies what this client missed while it didn't respond. + /// + /// The calls aren't limited by a timeout. A client that responds slowly, + /// such as a background tab throttled by the browser, would otherwise time + /// out again and never get up to date. Updates that arrive in the meantime + /// skip this client and are applied afterwards, so nothing waits for it. + Future _catchUp() async { + final appId = appConnection.request.appId; + final logger = manager.workflow.logger; + logger.write( + switch (_missedUpdate) { + final update? => 'Client $appId is responding again, catching up on the missed ${update.name}.', + null => 'Client $appId is responding again.', + }, + tag: .client, + ); + if (_isCatchingUp) return; + + _isCatchingUp = true; + ClientUpdate? update; + try { + while (!_isDisposed) { + update = _missedUpdate; + if (update != null) { + _missedUpdate = null; + if (!await _apply(update, _unguarded)) break; + update = null; + continue; + } + + // Changed stylesheets aren't part of an update, so deliver them afterwards. + final stylesheets = _pendingStylesheets.toList(); + if (stylesheets.isEmpty) break; + _pendingStylesheets.clear(); + if (await _reloadStylesheets(stylesheets) == null) { + // Keep them for the next stylesheet reload instead of retrying forever. + _pendingStylesheets.addAll(stylesheets); + break; + } + } + } catch (error, stackTrace) { + logger.write('Catching up failed for client $appId: $error', tag: .client, level: .warning); + logger.write(stackTrace.toString(), tag: .client, level: .verbose); + } finally { + // An update that couldn't be applied stays missed and is included in the + // next update, instead of being retried forever. + if (update != null) { + _markMissed(update); + } + _isCatchingUp = false; + } + } + + static Future _unguarded(Future Function() call) => call(); + + /// Runs the calls of [update] through [run] and returns whether it succeeded. + Future _apply(ClientUpdate update, Future Function(Future Function() call) run) async { + switch (update) { + case ClientUpdate.reload: + if (await run(_performHotReload) != true) { + // Skip reassemble and html reload if client hot-reload fails. + return false; + } + await run(_reassemble); + case ClientUpdate.restart: + if (await run(_restart) == null) { + // Skip html reload if client restart fails. + return false; + } + case ClientUpdate.refresh: + return await run(_refreshPage) != null; + } + if (manager.workflow.project.requireMode != JasprMode.client) { + await run(_reloadHtml); + } + return true; + } + + Future restart() => _callGuard.run(_restart); + + Future _restart() async { final restartMethod = _registeredMethodsForService['hotRestart'] ?? 'hotRestart'; final response = await vmService?.callServiceExtension(restartMethod); return response; - }); - - /// Performs a hot reload and returns whether it succeeded. - /// - /// Returns `false` if the client didn't respond in time. - Future performHotReload() async { - return await _callGuard.run(_performHotReload) ?? false; } + /// Performs a hot reload and returns whether it succeeded. Future _performHotReload() async { final vmService = this.vmService; if (vmService == null) { @@ -281,6 +402,9 @@ class ClientConnection { /// Reloads the stylesheets at [urls], together with any stylesheets this client missed before. Future reloadStylesheets(List urls) async { _pendingStylesheets.addAll(urls); + // Delivered at the end of the catch-up. + if (_isCatchingUp) return null; + final pending = _pendingStylesheets.toList(); final response = await _callGuard.run(() => _reloadStylesheets(pending)); if (response != null) { @@ -305,7 +429,9 @@ class ClientConnection { return null; } - Future reassemble() => _callGuard.run(() async { + Future reassemble() => _callGuard.run(_reassemble); + + Future _reassemble() async { final reassembleMethod = _registeredMethodsForService['ext.jaspr.reassemble'] ?? 'ext.jaspr.reassemble'; for (var i = 0; i < 5; i++) { try { @@ -316,9 +442,11 @@ class ClientConnection { } } return null; - }); + } + + Future reloadHtml([String? path]) => _callGuard.run(() => _reloadHtml(path)); - Future reloadHtml([String? path]) => _callGuard.run(() async { + Future _reloadHtml([String? path]) async { final reloadMethod = _registeredMethodsForService['ext.jaspr.reload_html'] ?? 'ext.jaspr.reload_html'; final args = path != null ? {'path': path} : {}; for (var i = 0; i < 5; i++) { @@ -330,9 +458,9 @@ class ClientConnection { } } return null; - }); + } - Future refreshPage() => _callGuard.run(() async { + Future _refreshPage() async { final reloadMethod = _registeredMethodsForService['fullReload'] ?? _registeredMethodsForService['ext.dwds.reload'] ?? 'fullReload'; try { @@ -341,7 +469,7 @@ class ClientConnection { } catch (_) { return null; } - }); + } int? _buildProgressEventId; var _progressEventId = 0; diff --git a/packages/jaspr_cli/lib/src/dev/dev_workflow.dart b/packages/jaspr_cli/lib/src/dev/dev_workflow.dart index 398354c63..a270b21a8 100644 --- a/packages/jaspr_cli/lib/src/dev/dev_workflow.dart +++ b/packages/jaspr_cli/lib/src/dev/dev_workflow.dart @@ -153,14 +153,8 @@ class DevWorkflow { var allReloaded = true; await clients.forEachConnection('Hot reload', (clientConnection) async { - if (!await clientConnection.performHotReload()) { + if (!await clientConnection.update(.reload)) { allReloaded = false; - // Skip reassemble and html reload if client hot-reload fails. - return; - } - await clientConnection.reassemble(); - if (project.requireMode != JasprMode.client) { - await clientConnection.reloadHtml(); } }); if (allReloaded) { @@ -189,13 +183,8 @@ class DevWorkflow { var allRestarted = true; await clients.forEachConnection('Hot restart', (clientConnection) async { - if (await clientConnection.restart() == null) { + if (!await clientConnection.update(.restart)) { allRestarted = false; - // Skip html reload if client restart fails. - return; - } - if (project.requireMode != JasprMode.client) { - await clientConnection.reloadHtml(); } }); if (allRestarted) { @@ -220,7 +209,7 @@ class DevWorkflow { var allRefreshed = true; await clients.forEachConnection('Refresh', (client) async { - if (await client.refreshPage() == null) { + if (!await client.update(.refresh)) { allRefreshed = false; } }); diff --git a/packages/jaspr_cli/test/src/dev/dev_workflow_test.dart b/packages/jaspr_cli/test/src/dev/dev_workflow_test.dart index 84cb952e0..24c2c5df3 100644 --- a/packages/jaspr_cli/test/src/dev/dev_workflow_test.dart +++ b/packages/jaspr_cli/test/src/dev/dev_workflow_test.dart @@ -166,13 +166,19 @@ void main() { expect(hanging.calls, isEmpty); expect(healthy.calls, expectedCalls); - // Once the pending call completes, the browser takes part in updates again. + // Once the pending call completes, the browser catches up on the update it was skipped for. respond.complete(); await pumpEventQueue(); await expectLater( fixture.io.stdout.queue, - emitsWithTimeout(emitsThrough(contains('Client hanging is responding again'))), + emitsWithTimeout( + emitsThrough(contains('Client hanging is responding again, catching up on the missed $action.')), + ), ); + expect(hanging.calls, expectedCalls); + expect(healthy.calls, expectedCalls, reason: 'Other browsers are not updated again.'); + + // Afterwards it takes part in updates again. hanging.beforeRpc = null; hanging.calls.clear(); healthy.calls.clear(); @@ -212,6 +218,188 @@ void main() { }); }); + for (final (action, Future Function(DevWorkflow) runUpdate, hangingRpc, expectedCalls) in [ + ('reload', (DevWorkflow w) => w.reloadClients(), 'reloadSources', [..._reloadCalls, _reloadHtmlCall]), + ('restart', (DevWorkflow w) => w.restartClients(incremental: true), 'hotRestart', ['hotRestart', _reloadHtmlCall]), + ]) { + test('$action is repeated for a browser that responds again after it timed out', () async { + await _withWorkflow(null, mode: JasprMode.server, (fixture) async { + fixture.workflow.clients.callTimeout = const Duration(milliseconds: 100); + final hanging = await fixture.connectBrowser('hanging'); + final respond = Completer(); + hanging.beforeRpc = (method) async { + if (method == hangingRpc) await respond.future; + }; + + // The calls after the one that timed out are skipped. + await runUpdate(fixture.workflow).timeout(const Duration(seconds: 5)); + expect(hanging.calls, expectedCalls.take(expectedCalls.indexOf(hangingRpc) + 1).toList()); + + // No further update is needed for the browser to get them. + hanging.calls.clear(); + respond.complete(); + await pumpEventQueue(); + expect(hanging.calls, expectedCalls); + await expectLater( + fixture.io.stdout.queue, + emitsWithTimeout( + emitsThrough(contains('Client hanging is responding again, catching up on the missed $action.')), + ), + ); + }); + }); + } + + test('refresh is not repeated for a browser that responds again after it timed out', () async { + await _withWorkflow(null, (fixture) async { + fixture.workflow.clients.callTimeout = const Duration(milliseconds: 100); + final hanging = await fixture.connectBrowser('hanging'); + final respond = Completer(); + hanging.beforeRpc = (method) async { + if (method == 'fullReload') await respond.future; + }; + + await fixture.workflow.refreshClients().timeout(const Duration(seconds: 5)); + expect(hanging.calls, ['fullReload']); + + // The page reloads once the pending call gets through. + respond.complete(); + await pumpEventQueue(); + expect(hanging.calls, ['fullReload']); + await expectLater( + fixture.io.stdout.queue, + emitsWithTimeout(emitsThrough(endsWith('Client hanging is responding again.'))), + ); + }); + }); + + test('catches up with the most extensive update a browser missed', () async { + await _withWorkflow(null, (fixture) async { + fixture.workflow.clients.callTimeout = const Duration(milliseconds: 100); + final hanging = await fixture.connectBrowser('hanging'); + final respond = Completer(); + hanging.beforeRpc = (method) async { + if (method == 'reloadSources') await respond.future; + }; + + await fixture.workflow.reloadClients().timeout(const Duration(seconds: 5)); + await fixture.workflow.restartClients(incremental: true).timeout(const Duration(seconds: 5)); + await fixture.workflow.reloadClients().timeout(const Duration(seconds: 5)); + + hanging.calls.clear(); + respond.complete(); + await pumpEventQueue(); + expect(hanging.calls, _restartCalls); + }); + }); + + test('includes an update the catch-up could not apply in the next update', () async { + await _withWorkflow(null, (fixture) async { + fixture.workflow.clients.callTimeout = const Duration(milliseconds: 100); + final hanging = await fixture.connectBrowser('hanging'); + final respond = Completer(); + hanging.beforeRpc = (method) async { + if (method == 'reloadSources') await respond.future; + }; + + await fixture.workflow.reloadClients().timeout(const Duration(seconds: 5)); + await fixture.workflow.restartClients(incremental: true).timeout(const Duration(seconds: 5)); + + // The browser responds again, but the restart it missed fails. + hanging.failingRpc = 'hotRestart'; + hanging.calls.clear(); + respond.complete(); + await pumpEventQueue(); + expect(hanging.calls, _restartCalls); + await expectLater( + fixture.io.stdout.queue, + emitsWithTimeout(emitsThrough(contains('Catching up failed for client hanging'))), + ); + + // The next update is a reload, which must not replace the restart. + hanging.failingRpc = null; + hanging.beforeRpc = null; + hanging.calls.clear(); + await fixture.workflow.reloadClients(); + expect(hanging.calls, _restartCalls); + + // Afterwards updates are applied as usual. + hanging.calls.clear(); + await fixture.workflow.reloadClients(); + expect(hanging.calls, _reloadCalls); + }); + }); + + // A background tab throttled by the browser still answers, but may take + // longer than the timeout for every call. + test('catches up a browser that responds slower than the timeout', () async { + await _withWorkflow(null, mode: JasprMode.server, (fixture) async { + const timeout = Duration(milliseconds: 100); + fixture.workflow.clients.callTimeout = timeout; + final slow = await fixture.connectBrowser('slow'); + slow.beforeRpc = (_) => Future.delayed(timeout * 1.5); + + await fixture.workflow.reloadClients().timeout(const Duration(seconds: 5)); + expect(slow.calls, ['getVM']); + await expectLater( + fixture.io.stdout.queue, + emitsWithTimeout(emitsThrough(contains('Client slow did not respond'))), + ); + + // The hot reload that timed out finishes first, then the whole reload is repeated. + const caughtUpCalls = ['getVM', 'reloadSources', ..._reloadCalls, _reloadHtmlCall]; + await slow.completedRpcs.stream.firstWhere((method) => method == _reloadHtmlCall); + expect(slow.calls, caughtUpCalls); + + // It is up to date now, so it isn't updated or reported as unresponsive again. + await Future.delayed(timeout * 3); + expect(slow.calls, caughtUpCalls); + slow.beforeRpc = null; + slow.calls.clear(); + await fixture.workflow.reloadClients(); + expect(slow.calls, [..._reloadCalls, _reloadHtmlCall]); + }); + }); + + test('updates skip a browser that is catching up and are applied afterwards', () async { + await _withWorkflow(null, (fixture) async { + fixture.workflow.clients.callTimeout = const Duration(milliseconds: 100); + final hanging = await fixture.connectBrowser('hanging'); + final healthy = await fixture.connectBrowser('healthy'); + final respond = Completer(); + hanging.beforeRpc = (method) async { + if (method == 'reloadSources') await respond.future; + }; + + // Fails instead of hanging when the update waits for the catch-up. + Future update() => fixture.workflow.reloadClients().timeout(const Duration(seconds: 5)); + await update(); + + // The browser responds again, but its catch-up takes a while. + final resume = Completer(); + hanging.beforeRpc = (method) async { + if (method == 'ext.jaspr.reassemble') await resume.future; + }; + hanging.calls.clear(); + healthy.calls.clear(); + respond.complete(); + await pumpEventQueue(); + expect(hanging.calls, _reloadCalls); + + await update(); + expect(healthy.calls, _reloadCalls); + expect(hanging.calls, _reloadCalls, reason: 'The update should not overlap with the catch-up.'); + final connection = fixture.workflow.clients.getConnection('hanging')!; + expect(await connection.reloadStylesheets(['main.css']), isNull, reason: 'The browser is skipped.'); + + hanging.beforeRpc = null; + hanging.calls.clear(); + resume.complete(); + await pumpEventQueue(); + expect(hanging.calls, [..._reloadCalls, 'ext.jaspr.reload_stylesheets']); + }); + }); + for (final (action, Future Function(DevWorkflow) runUpdate, expectedCalls) in [ ('reload', (DevWorkflow w) => w.reloadClients(), [..._reloadCalls, _reloadHtmlCall]), ('restart', (DevWorkflow w) => w.restartClients(), [..._restartCalls, _reloadHtmlCall]),