From eb4bd147541d8421b1ec9017cddf4afd0ae20f89 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Tue, 17 Nov 2026 21:48:34 +0100 Subject: [PATCH] crdt_sync_flutter 0.9.0: app error + slow-wait reporter Co-Authored-By: Claude Opus 5.5 --- crdt_sync_flutter/README.md | 27 + crdt_sync_flutter/lib/crdt_sync_flutter.dart | 9 + .../lib/src/errors/app_errors.dart | 112 +++++ .../lib/src/errors/app_errors_config.dart | 33 ++ .../lib/src/errors/error_entry.dart | 84 ++++ .../lib/src/errors/error_queue.dart | 77 +++ .../lib/src/errors/error_reporter.dart | 94 ++++ .../lib/src/errors/error_upload.dart | 121 +++++ .../lib/src/errors/report_redact.dart | 30 ++ .../lib/src/errors/slow_wait.dart | 132 +++++ .../lib/src/errors/wait_watch.dart | 67 +++ crdt_sync_flutter/pubspec.yaml | 2 +- crdt_sync_flutter/test/app_errors_test.dart | 460 ++++++++++++++++++ 13 files changed, 1247 insertions(+), 1 deletion(-) create mode 100644 crdt_sync_flutter/lib/src/errors/app_errors.dart create mode 100644 crdt_sync_flutter/lib/src/errors/app_errors_config.dart create mode 100644 crdt_sync_flutter/lib/src/errors/error_entry.dart create mode 100644 crdt_sync_flutter/lib/src/errors/error_queue.dart create mode 100644 crdt_sync_flutter/lib/src/errors/error_reporter.dart create mode 100644 crdt_sync_flutter/lib/src/errors/error_upload.dart create mode 100644 crdt_sync_flutter/lib/src/errors/report_redact.dart create mode 100644 crdt_sync_flutter/lib/src/errors/slow_wait.dart create mode 100644 crdt_sync_flutter/lib/src/errors/wait_watch.dart create mode 100644 crdt_sync_flutter/test/app_errors_test.dart diff --git a/crdt_sync_flutter/README.md b/crdt_sync_flutter/README.md index f202e76..d2da0bf 100644 --- a/crdt_sync_flutter/README.md +++ b/crdt_sync_flutter/README.md @@ -185,6 +185,33 @@ what Android does in practice, since `Uri.base` there is `file:///`. Nothing in this package reads `~/.config/crdt-sync/` directly. That is the desktop/Python half, reached over the wrapper's HTTP routes. +## Error and slow-wait reporting + +Every error, and every wait the user sees over 1 s, goes to the PC's +`app-errors` ingest (utils `DOCS-app-errors.md`). The board turns each one into +a self-fixing ticket. Generalised from kartka. + +```dart +final errors = await installAppErrors(const AppErrorsConfig( + app: 'todo', repo: 'kuhyx/todo', + build: int.fromEnvironment('APP_BUILD'), // versionCode + version: String.fromEnvironment('APP_VERSION'), +)); +errors.connect( + sink: () async => (await openFirebase())?.patchValues, // null = signed out + deviceId: () async => repository.nodeId, +); +// MaterialApp(navigatorObservers: [AppErrorsRouteObserver(errors)], ...) +// Wrap every loader: WaitWatch.centered('list.load') +``` + +`installAppErrors` chains `FlutterError.onError` and `PlatformDispatcher.onError`. +Reports are deduplicated on the device (30 s window, 20 a minute), redacted, +queued in `SharedPreferences` (so offline reports survive), and uploaded to +RTDB `//errors//` with `repo`, `build` and `version`. A spinner +inside `WaitWatch` that stays over 1 s becomes `perf.slow`. Nothing shows on +screen. + ## Testing The keystore fake ships with the package, so a consuming app does not rebuild diff --git a/crdt_sync_flutter/lib/crdt_sync_flutter.dart b/crdt_sync_flutter/lib/crdt_sync_flutter.dart index 9f0667f..87ec40d 100644 --- a/crdt_sync_flutter/lib/crdt_sync_flutter.dart +++ b/crdt_sync_flutter/lib/crdt_sync_flutter.dart @@ -16,6 +16,15 @@ export 'src/bootstrap.dart'; export 'src/device_id.dart'; export 'src/e2e_bootstrap.dart'; export 'src/e2e_passphrase_button.dart'; +export 'src/errors/app_errors.dart'; +export 'src/errors/app_errors_config.dart'; +export 'src/errors/error_entry.dart'; +export 'src/errors/error_queue.dart'; +export 'src/errors/error_reporter.dart'; +export 'src/errors/error_upload.dart'; +export 'src/errors/report_redact.dart'; +export 'src/errors/slow_wait.dart'; +export 'src/errors/wait_watch.dart'; export 'src/google_any_sign_in.dart'; export 'src/google_desktop_sign_in.dart'; export 'src/google_pkce.dart'; diff --git a/crdt_sync_flutter/lib/src/errors/app_errors.dart b/crdt_sync_flutter/lib/src/errors/app_errors.dart new file mode 100644 index 0000000..da8c5d7 --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/app_errors.dart @@ -0,0 +1,112 @@ +/// App-wide error and slow-wait reporting, in one call (generalised from +/// kartka's `error_hooks.dart`): the PC's `app-errors` ingest turns every +/// report into a self-fixing ticket on kuhy's board. +library; + +import 'dart:async'; + +import 'package:crdt_sync_flutter/src/errors/app_errors_config.dart'; +import 'package:crdt_sync_flutter/src/errors/error_queue.dart'; +import 'package:crdt_sync_flutter/src/errors/error_reporter.dart'; +import 'package:crdt_sync_flutter/src/errors/error_upload.dart'; +import 'package:crdt_sync_flutter/src/errors/slow_wait.dart'; +import 'package:flutter/foundation.dart'; +import 'package:flutter/widgets.dart'; +import 'package:shared_preferences/shared_preferences.dart'; + +/// The installed reporting: [reporter] for errors, [waits] for slow waits, +/// both into [queue], which [connect] uploads. +class AppErrors { + /// Reporting for [config] into [queue] (tests; apps call + /// [installAppErrors]). + AppErrors.forTest(this.config, this.queue, {DateTime Function()? now}) + : reporter = ErrorReporter(queue, config: config, now: now) { + waits = SlowWaitReporter(queue, now: now, route: () => reporter.route); + } + + /// The installed instance ([WaitWatch] reads it); null before install. + static AppErrors? instance; + + /// The app reported for. + final AppErrorsConfig config; + + /// Reports not yet uploaded. + final ErrorQueue queue; + + /// Records errors. + final ErrorReporter reporter; + + /// Times waits. + late final SlowWaitReporter waits; + + /// Starts uploading to RTDB through [sink] (null while signed out) as + /// [deviceId]; flushes the backlog after [startDelay]. + ErrorUploader connect({ + required Future Function() sink, + required Future Function() deviceId, + Duration startDelay = const Duration(seconds: 20), + }) => ErrorUploader(queue, config: config, sink: sink, deviceId: deviceId) + ..start() + ..schedule(startDelay); +} + +/// Installs app-wide reporting for [config] once, from `main` after +/// `WidgetsFlutterBinding.ensureInitialized`: uncaught framework errors +/// (`uncaught.flutter`) and async errors (`uncaught.async`) are queued, then +/// handed to the handlers installed before. Shows nothing on screen. +Future installAppErrors( + AppErrorsConfig config, { + SharedPreferences? preferences, +}) async { + final queue = await ErrorQueue.open( + preferences ?? await SharedPreferences.getInstance(), + ); + final errors = AppErrors.instance = AppErrors.forTest(config, queue); + final reporter = errors.reporter; + final framework = FlutterError.onError; + FlutterError.onError = (details) { + if (!details.silent) { + reporter.report( + 'uncaught.flutter', + details.exception, + stack: details.stack, + ); + } + framework?.call(details); + }; + final dispatcher = PlatformDispatcher.instance; + final async = dispatcher.onError; + dispatcher.onError = (error, stack) { + reporter.report('uncaught.async', error, stack: stack); + return async?.call(error, stack) ?? false; + }; + return errors; +} + +/// Keeps the reporter's route current, so every report names its screen. +/// Add it to the app's `navigatorObservers`. Route names only: give routes +/// patterns (`/list/:id`), never ids or titles. +class AppErrorsRouteObserver extends NavigatorObserver { + /// Stamps routes into [errors]. + AppErrorsRouteObserver(this.errors); + + /// The reporting stamped. + final AppErrors errors; + + void _set(Route? route) { + final name = route?.settings.name; + if (name != null) errors.reporter.route = name; + } + + @override + void didPush(Route route, Route? previousRoute) => + _set(route); + + @override + void didPop(Route route, Route? previousRoute) => + _set(previousRoute); + + @override + void didReplace({Route? newRoute, Route? oldRoute}) => + _set(newRoute); +} diff --git a/crdt_sync_flutter/lib/src/errors/app_errors_config.dart b/crdt_sync_flutter/lib/src/errors/app_errors_config.dart new file mode 100644 index 0000000..bf4f14e --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/app_errors_config.dart @@ -0,0 +1,33 @@ +/// Which app reports, and which build it is. +library; + +/// The app's identity in its reports. +class AppErrorsConfig { + /// The app [app] (as the board shows it), fixed in [repo] (`owner/name`). + const AppErrorsConfig({ + required this.app, + required this.repo, + this.package, + this.build = 0, + this.version, + }); + + /// The app name: the RTDB root key and the board's `app` + /// (`^[a-z0-9][a-z0-9_-]*$`). + final String app; + + /// The repo that holds the fix (`kuhyx/todo`). + final String repo; + + /// The Dart package name, when it is not [app] with `-` as `_`. + final String? package; + + /// The build number (Android versionCode); 0 when unknown. + final int build; + + /// The version name (`1.2.3`). + final String? version; + + /// What marks the app's own stack frames (`package:todo/`). + String get mark => 'package:${package ?? app.replaceAll('-', '_')}/'; +} diff --git a/crdt_sync_flutter/lib/src/errors/error_entry.dart b/crdt_sync_flutter/lib/src/errors/error_entry.dart new file mode 100644 index 0000000..f68e6a9 --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/error_entry.dart @@ -0,0 +1,84 @@ +/// One error or slow-wait report, in the shape every reporter (Dart, Python, +/// GDScript) writes and utils `app_errors` ingests (its README, "Entry"). +library; + +/// The kind of a user-visible wait that lasted over a second. +const perfSlowKind = 'perf.slow'; + +/// One report, before the uploader adds the app's repo, mark and build. +class ErrorEntry { + /// A report of [kind] at [at]. + const ErrorEntry({ + required this.at, + required this.kind, + required this.error, + this.stack = const [], + this.route, + this.operation, + this.durationMs, + this.waitId, + this.still, + }); + + /// Decodes [toJson]'s shape; throws on a wrong one ([tryFromJson] does not). + factory ErrorEntry.fromJson(Map json) => ErrorEntry( + at: DateTime.parse(json['at']! as String), + kind: json['kind']! as String, + error: json['error']! as String, + stack: [for (final f in json['stack'] as List? ?? []) '$f'], + route: json['route'] as String?, + operation: json['operation'] as String?, + durationMs: json['durationMs'] as int?, + waitId: json['waitId'] as String?, + still: json['still'] as bool?, + ); + + /// [ErrorEntry.fromJson], or null when [json] is not an entry. + static ErrorEntry? tryFromJson(Object? json) { + try { + return ErrorEntry.fromJson(json! as Map); + } on Object { + return null; + } + } + + /// When it happened (UTC). + final DateTime at; + + /// `uncaught.flutter`, `uncaught.async`, `perf.slow`, ... + final String kind; + + /// The error's text (a slow wait: ` waited ms`). + final String error; + + /// The innermost frames, then the app's own. + final List stack; + + /// The route on top when it happened (a pattern, never an id). + final String? route; + + /// What a slow wait waited for (`list.load`). + final String? operation; + + /// How long a slow wait took. + final int? durationMs; + + /// Names one slow wait across its still-going and final reports. + final String? waitId; + + /// True for the report of a wait that has not ended yet. + final bool? still; + + /// The JSON shape (absent fields are left out). + Map toJson() => { + 'at': at.toUtc().toIso8601String(), + 'kind': kind, + 'error': error, + 'stack': stack, + 'route': ?route, + 'operation': ?operation, + 'durationMs': ?durationMs, + 'waitId': ?waitId, + 'still': ?still, + }; +} diff --git a/crdt_sync_flutter/lib/src/errors/error_queue.dart b/crdt_sync_flutter/lib/src/errors/error_queue.dart new file mode 100644 index 0000000..1dcf4cc --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/error_queue.dart @@ -0,0 +1,77 @@ +/// The on-device queue of reports not yet uploaded. +library; + +import 'dart:async'; +import 'dart:convert'; + +import 'package:crdt_sync_flutter/src/errors/error_entry.dart'; +import 'package:crypto/crypto.dart'; +import 'package:shared_preferences/shared_preferences.dart'; + +/// Reports waiting for upload, persisted in `SharedPreferences` (so web +/// builds keep them too): a crash, a lost connection or a signed-out device +/// loses nothing. Keeps the newest [maxEntries]. +class ErrorQueue { + ErrorQueue._(this._prefs, this._entries); + + /// The queue stored in [prefs]; a corrupt store opens empty. + static Future open(SharedPreferences prefs) async { + final entries = []; + try { + for (final raw in jsonDecode(prefs.getString(key) ?? '[]') as List) { + final entry = ErrorEntry.tryFromJson(raw); + if (entry != null) entries.add(entry); + } + } on FormatException { + // A corrupt queue is dropped: reporting must never stop the app. + } + return ErrorQueue._(prefs, entries); + } + + /// Preferences key of the queue. + static const key = 'app_errors.queue'; + + /// Most reports kept. + static const maxEntries = 300; + + final SharedPreferences _prefs; + final List _entries; + final _added = StreamController.broadcast(); + Future _tail = Future.value(); + + /// The id of [entry]: a hash of its JSON, so a re-sent upload is a no-op. + static String idOf(ErrorEntry entry) => sha1 + .convert(utf8.encode(jsonEncode(entry.toJson()))) + .toString() + .substring(0, 20); + + /// What is queued, oldest first. + List get entries => List.unmodifiable(_entries); + + /// Fires after each [add]. + Stream get added => _added.stream; + + /// Completes when every change so far is stored. + Future get saved => _tail; + + /// Queues [entry] and stores the queue. + void add(ErrorEntry entry) { + _entries.add(entry); + if (_entries.length > maxEntries) { + _entries.removeRange(0, _entries.length - maxEntries); + } + _save(); + _added.add(entry); + } + + /// Drops the entries whose ids are in [ids] and stores the queue. + void remove(Set ids) { + _entries.removeWhere((e) => ids.contains(idOf(e))); + _save(); + } + + void _save() { + final text = jsonEncode([for (final e in _entries) e.toJson()]); + _tail = _tail.then((_) => _prefs.setString(key, text)); + } +} diff --git a/crdt_sync_flutter/lib/src/errors/error_reporter.dart b/crdt_sync_flutter/lib/src/errors/error_reporter.dart new file mode 100644 index 0000000..a329e6f --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/error_reporter.dart @@ -0,0 +1,94 @@ +/// Records errors the user saw (or that escaped) in the [ErrorQueue]. +library; + +import 'package:crdt_sync_flutter/src/errors/app_errors_config.dart'; +import 'package:crdt_sync_flutter/src/errors/error_entry.dart'; +import 'package:crdt_sync_flutter/src/errors/error_queue.dart'; + +/// The one door for the app-wide hooks (from kartka's `ErrorReporter`). +/// +/// It guards the queue against error loops: an identical `kind` + message +/// inside [window] is dropped, and at most [maxPerMinute] reports are kept a +/// minute. It never throws and never reports from inside a report. +class ErrorReporter { + /// A reporter into [queue] for [config]'s app, reading time from [now]. + ErrorReporter(this.queue, {required this.config, DateTime Function()? now}) + : _now = now ?? DateTime.now; + + /// How long an identical error stays suppressed. + static const window = Duration(seconds: 30); + + /// Most reports kept in one minute. + static const maxPerMinute = 20; + + /// Innermost frames always kept; the rest are the app's own frames. + static const _innerFrames = 2; + + /// Where reports go. + final ErrorQueue queue; + + /// The app reported for. + final AppErrorsConfig config; + + /// The route on top now (an [AppErrorsRouteObserver] keeps it current). + String? route; + + final DateTime Function() _now; + final _lastSeen = {}; + DateTime? _minute; + int _inMinute = 0; + bool _busy = false; + + /// Records [error] (with [stack]) as a [kind] report, unless suppressed. + void report(String kind, Object? error, {StackTrace? stack}) { + if (_busy) return; + _busy = true; + try { + final at = _now().toUtc(); + final text = '${error ?? 'unknown error'}'; + if (_allowed('$kind|$text', at)) { + queue.add( + ErrorEntry( + at: at, + kind: kind, + error: text, + stack: _focus(stack), + route: route, + ), + ); + } + } on Object { + // An error whose toString throws: nothing sensible to record. + } finally { + _busy = false; + } + } + + bool _allowed(String key, DateTime at) { + _lastSeen.removeWhere((_, seen) => at.difference(seen) >= window); + if (_lastSeen.containsKey(key)) return false; + final minute = _minute; + if (minute == null || at.difference(minute) >= const Duration(minutes: 1)) { + _minute = at; + _inMinute = 0; + } + if (_inMinute >= maxPerMinute) return false; + _inMinute++; + _lastSeen[key] = at; + return true; + } + + /// The innermost frames, then the app's own frames, so a framework-deep + /// stack still names the app code that triggered it. + List _focus(StackTrace? stack) { + if (stack == null) return const []; + final frames = [ + for (final line in '$stack'.split('\n')) + if (line.trim().isNotEmpty) line.trim(), + ]; + return [ + ...frames.take(_innerFrames), + ...frames.skip(_innerFrames).where((f) => f.contains(config.mark)), + ]; + } +} diff --git a/crdt_sync_flutter/lib/src/errors/error_upload.dart b/crdt_sync_flutter/lib/src/errors/error_upload.dart new file mode 100644 index 0000000..3ba23b8 --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/error_upload.dart @@ -0,0 +1,121 @@ +/// Uploads queued reports to RTDB `//errors//`, where the +/// PC's `app-errors` ingest collects them (from kartka's `error_upload.dart`). +library; + +import 'dart:async'; +import 'dart:math' as math; + +import 'package:crdt_sync_flutter/src/errors/app_errors_config.dart'; +import 'package:crdt_sync_flutter/src/errors/error_entry.dart'; +import 'package:crdt_sync_flutter/src/errors/error_queue.dart'; +import 'package:crdt_sync_flutter/src/errors/report_redact.dart'; + +/// Characters an RTDB key cannot hold. +final _unsafeKey = RegExp(r'[.#$\[\]/]'); + +/// A multi-path RTDB update of `path` (`FirebaseRestClient.patchValues`). +typedef ErrorSink = + Future Function(String path, Map values); + +/// Pushes the [ErrorQueue] to RTDB and drops what was sent. +/// +/// Writes go straight to the RTDB client, never through the sync engine, so +/// they bump no `revs/` and no peer fetches them. A retried push is +/// idempotent (the id is a hash of the entry). Best-effort: debounced after +/// appends, backing off on failure, never throws. +class ErrorUploader { + /// An uploader of [queue] for [config]'s app; [sink] is null while signed + /// out. + ErrorUploader( + this.queue, { + required this.config, + required this.sink, + required this.deviceId, + this.debounce = const Duration(seconds: 5), + }); + + /// Entries per RTDB write. + static const batch = 50; + + /// First retry delay after a failed push; doubles up to [maxBackoff]. + static const minBackoff = Duration(seconds: 30); + + /// Longest retry delay. + static const maxBackoff = Duration(minutes: 15); + + /// The reports waiting. + final ErrorQueue queue; + + /// The app's identity, stamped on every upload. + final AppErrorsConfig config; + + /// The RTDB writer, or null while signed out. + final Future Function() sink; + + /// This install's device id. + final Future Function() deviceId; + + /// Quiet time after an append before a flush. + final Duration debounce; + + StreamSubscription? _sub; + Timer? _timer; + Duration _backoff = minBackoff; + Future _tail = Future.value(true); + + /// Flushes [debounce] after each append. + void start() => _sub ??= queue.added.listen((_) => schedule()); + + /// Flushes after [delay] (default [debounce]), replacing a pending one. + void schedule([Duration? delay]) { + _timer?.cancel(); + _timer = Timer(delay ?? debounce, () => unawaited(flush())); + } + + /// Stops listening and cancels a pending flush. + void dispose() { + unawaited(_sub?.cancel()); + _sub = null; + _timer?.cancel(); + } + + /// Pushes what is queued; true when nothing is left. Flushes run one at a + /// time; a failure schedules a retry with backoff. + Future flush() => _tail = _tail.then((_) => _flushOnce()); + + Future _flushOnce() async { + final pending = queue.entries; + if (pending.isEmpty) return true; + try { + final write = await sink(); + if (write == null) throw StateError('signed out'); + final device = (await deviceId()).replaceAll(_unsafeKey, '_'); + for (var i = 0; i < pending.length; i += batch) { + final chunk = pending.sublist(i, math.min(i + batch, pending.length)); + await write('${config.app}/errors', { + for (final e in chunk) '$device/${ErrorQueue.idOf(e)}': _payload(e), + }); + queue.remove({for (final e in chunk) ErrorQueue.idOf(e)}); + } + _backoff = minBackoff; + return true; + } on Object { + schedule(_backoff); + _backoff = _backoff * 2 > maxBackoff ? maxBackoff : _backoff * 2; + return false; + } + } + + Map _payload(ErrorEntry e) => { + for (final MapEntry(:key, :value) in e.toJson().entries) + key: switch (value) { + final String s => redactForReport(s), + final List l => [for (final f in l) redactForReport('$f')], + _ => value, + }, + 'repo': config.repo, + 'mark': config.mark, + 'build': config.build, + 'version': ?config.version, + }; +} diff --git a/crdt_sync_flutter/lib/src/errors/report_redact.dart b/crdt_sync_flutter/lib/src/errors/report_redact.dart new file mode 100644 index 0000000..37d344e --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/report_redact.dart @@ -0,0 +1,30 @@ +/// The redaction applied before a report leaves the device (from kartka's +/// `report_redact.dart`). +library; + +final _urlTail = RegExp( + r'''(https?://[^\s?#"'<>]*)([?#])(?!)[^\s"'<>]*''', +); +final _userInfo = RegExp(r'''(https?://)[^\s/?#"'<>@]*@'''); +final _email = RegExp(r'[\w.+-]+@[\w-]+(\.[\w-]+)+'); +final _bearer = RegExp(r'\b(Bearer|Basic)\s+[^\s,;]+', caseSensitive: false); +final _jwt = RegExp(r'eyJ[\w-]+\.[\w-]+\.[\w-]*'); +final _named = RegExp( + r'\b(cookie|set-cookie|authorization|password|passwd|token|secret|' + r'api[_-]?key|session)\b(\s*[:=]\s*)[^\s,]+', + caseSensitive: false, +); +final _home = RegExp(r'/(home|Users)/[^/\s]+/'); + +/// [text] with URL queries and user info, emails, bearer and basic +/// credentials, JWTs, `name=value` secrets and the user name in home paths +/// replaced. Over-redaction is the cheap mistake: a report that loses a word +/// is still fixable, one that leaks a token is not. +String redactForReport(String text) => text + .replaceAllMapped(_urlTail, (m) => '${m[1]}${m[2]}') + .replaceAllMapped(_userInfo, (m) => '${m[1]}@') + .replaceAll(_jwt, '') + .replaceAllMapped(_bearer, (m) => '${m[1]} ') + .replaceAllMapped(_named, (m) => '${m[1]}${m[2]}') + .replaceAll(_email, '') + .replaceAll(_home, '~/'); diff --git a/crdt_sync_flutter/lib/src/errors/slow_wait.dart b/crdt_sync_flutter/lib/src/errors/slow_wait.dart new file mode 100644 index 0000000..53d77c4 --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/slow_wait.dart @@ -0,0 +1,132 @@ +/// Reports user-visible waits over a second (from kartka's `slow_wait.dart`). +library; + +import 'dart:async'; + +import 'package:crdt_sync_flutter/src/errors/error_entry.dart'; +import 'package:crdt_sync_flutter/src/errors/error_queue.dart'; + +/// Writes every wait that outlasts [threshold] as one `perf.slow` report +/// (route when it began, operation, milliseconds). +/// +/// A wait that ends within [threshold] writes nothing. One still going after +/// [stillWaiting] is written at once (a hung load never ends), and its end +/// writes a second report with the same wait id. The PC groups by route + +/// operation only, so every slow wait of one operation is one ticket. At most +/// [maxPerMinute] reports a minute. Never throws. +class SlowWaitReporter { + /// A reporter into [queue]; [route] reads the route on top. + SlowWaitReporter( + this.queue, { + DateTime Function()? now, + String? Function()? route, + this.threshold = const Duration(seconds: 1), + this.stillWaiting = const Duration(seconds: 5), + }) : _now = now ?? DateTime.now, + _route = route ?? _noRoute; + + static String? _noRoute() => null; + + /// Most reports kept in one minute. + static const maxPerMinute = 30; + + /// Where reports go. + final ErrorQueue queue; + + /// A wait must last longer than this to be reported. + final Duration threshold; + + /// A wait this long is reported before it ends. + final Duration stillWaiting; + + final DateTime Function() _now; + final String? Function() _route; + DateTime? _minute; + int _inMinute = 0; + int _serial = 0; + + /// Starts timing a wait on [operation] (`list.load`); call + /// [SlowWait.end] when it is over. + SlowWait begin(String operation) { + final at = _now(); + return SlowWait._( + this, + operation: operation, + route: _route(), + started: at, + id: '${at.microsecondsSinceEpoch.toRadixString(36)}-${_serial++}', + ); + } + + void _write(SlowWait w, Duration took, {required bool still}) { + final at = _now().toUtc(); + final minute = _minute; + if (minute == null || at.difference(minute) >= const Duration(minutes: 1)) { + _minute = at; + _inMinute = 0; + } + if (_inMinute >= maxPerMinute) return; + _inMinute++; + final ms = took.inMilliseconds; + queue.add( + ErrorEntry( + at: at, + kind: perfSlowKind, + error: '${w.operation} waited $ms ms', + route: w.route, + operation: w.operation, + durationMs: ms, + waitId: w.id, + still: still, + ), + ); + } +} + +/// One timed wait of a [SlowWaitReporter]. +class SlowWait { + SlowWait._( + this._reporter, { + required this.operation, + required this.route, + required this.started, + required this.id, + }) { + _timer = Timer(_reporter.stillWaiting, _stillGoing); + } + + final SlowWaitReporter _reporter; + + /// What is awaited. + final String operation; + + /// The route on top when the wait began. + final String? route; + + /// When it began. + final DateTime started; + + /// Names this wait across its reports. + final String id; + + late final Timer _timer; + bool _reportedStill = false; + bool _ended = false; + + void _stillGoing() { + _reportedStill = true; + _reporter._write(this, _reporter._now().difference(started), still: true); + } + + /// Ends the wait; writes it when it lasted over the threshold. Repeat + /// calls do nothing. + void end() { + if (_ended) return; + _ended = true; + _timer.cancel(); + final took = _reporter._now().difference(started); + if (_reportedStill || took > _reporter.threshold) { + _reporter._write(this, took, still: false); + } + } +} diff --git a/crdt_sync_flutter/lib/src/errors/wait_watch.dart b/crdt_sync_flutter/lib/src/errors/wait_watch.dart new file mode 100644 index 0000000..8b4c219 --- /dev/null +++ b/crdt_sync_flutter/lib/src/errors/wait_watch.dart @@ -0,0 +1,67 @@ +/// Times a loader on screen (from kartka's `wait_watch.dart`). +library; + +import 'package:crdt_sync_flutter/src/errors/app_errors.dart'; +import 'package:crdt_sync_flutter/src/errors/slow_wait.dart'; +import 'package:material_ui/material_ui.dart'; + +/// Times how long its [child] (a loader or spinner) stays on screen and +/// reports a wait over a second as `perf.slow` for [operation], so the PC +/// files a ticket to cut it. +/// +/// The one shared hook for every loader: wrap the spinner instead of timing +/// the future at each call site. Without [AppErrors.instance] (a bare widget +/// test) it only shows [child]. +class WaitWatch extends StatefulWidget { + /// Watches [child] as a wait on [operation]. + const WaitWatch({required this.operation, required this.child, super.key}); + + /// Watches a centred spinner, the usual full-page loader. + const WaitWatch.centered(this.operation, {super.key}) + : child = const Center(child: CircularProgressIndicator()); + + /// What the user waits for, dotted by area (`list.load`). Never an id. + final String operation; + + /// The loader shown while waiting. + final Widget child; + + @override + State createState() => _WaitWatchState(); +} + +class _WaitWatchState extends State with WidgetsBindingObserver { + SlowWaitReporter? _reporter; + SlowWait? _wait; + + @override + void initState() { + super.initState(); + final reporter = _reporter = AppErrors.instance?.waits; + if (reporter == null) return; + _wait = reporter.begin(widget.operation); + WidgetsBinding.instance.addObserver(this); + } + + /// A backgrounded app is not a wait the user sees: the wait ends when the + /// app leaves the foreground and a new one starts when it returns. + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + if (state == AppLifecycleState.resumed) { + _wait ??= _reporter?.begin(widget.operation); + } else { + _wait?.end(); + _wait = null; + } + } + + @override + void dispose() { + WidgetsBinding.instance.removeObserver(this); + _wait?.end(); + super.dispose(); + } + + @override + Widget build(BuildContext context) => widget.child; +} diff --git a/crdt_sync_flutter/pubspec.yaml b/crdt_sync_flutter/pubspec.yaml index c007ca9..e05b7ac 100644 --- a/crdt_sync_flutter/pubspec.yaml +++ b/crdt_sync_flutter/pubspec.yaml @@ -4,7 +4,7 @@ description: >- persisted per-install device id, and a one-call bootstrap. Removes the ~150 lines of firebase_backend.dart every consuming app was copying. publish_to: 'none' -version: 0.8.3 +version: 0.9.0 environment: sdk: ^3.12.2 diff --git a/crdt_sync_flutter/test/app_errors_test.dart b/crdt_sync_flutter/test/app_errors_test.dart new file mode 100644 index 0000000..65b3641 --- /dev/null +++ b/crdt_sync_flutter/test/app_errors_test.dart @@ -0,0 +1,460 @@ +import 'dart:async'; +import 'dart:ui' show ErrorCallback, PlatformDispatcher; + +import 'package:crdt_sync_flutter/crdt_sync_flutter.dart'; +import 'package:flutter/foundation.dart'; +import 'package:material_ui/material_ui.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:shared_preferences/shared_preferences.dart'; + +/// A sink recording every patch; [fail] makes the next ones throw. +class FakeSink { + final patches = >{}; + bool fail = false; + + Future call(String path, Map values) async { + if (fail) throw StateError('offline'); + (patches[path] ??= {}).addAll(values); + } + + List> get entries => [ + for (final v in patches.values.expand((m) => m.values)) + v! as Map, + ]; +} + +const config = AppErrorsConfig( + app: 'todo', + repo: 'kuhyx/todo', + build: 42, + version: '1.2.3', +); + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + late DateTime clock; + late ErrorQueue queue; + + setUp(() async { + SharedPreferences.setMockInitialValues({}); + clock = DateTime.utc(2026, 11, 17, 10); + queue = await ErrorQueue.open(await SharedPreferences.getInstance()); + }); + + ErrorReporter reporter() => + ErrorReporter(queue, config: config, now: () => clock); + + group('ErrorReporter', () { + test('records an error with its app frames', () { + reporter().report( + 'uncaught.flutter', + StateError('boom'), + stack: StackTrace.fromString( + '#0 a (package:flutter/x.dart:1:1)\n' + '#1 b (dart:async/y.dart:2:2)\n' + '#2 c (package:flutter/z.dart:3:3)\n' + '#3 Home.build (package:todo/home.dart:4:4)', + ), + ); + final e = queue.entries.single; + expect(e.kind, 'uncaught.flutter'); + expect(e.error, 'Bad state: boom'); + expect(e.stack, [ + '#0 a (package:flutter/x.dart:1:1)', + '#1 b (dart:async/y.dart:2:2)', + '#3 Home.build (package:todo/home.dart:4:4)', + ]); + }); + + test('drops identical errors inside the window', () { + final r = reporter(); + for (var i = 0; i < 10; i++) { + r.report('k', 'same'); + } + expect(queue.entries, hasLength(1)); + clock = clock.add(ErrorReporter.window); + r.report('k', 'same'); + expect(queue.entries, hasLength(2)); + }); + + test('keeps at most maxPerMinute a minute', () { + final r = reporter(); + for (var i = 0; i < ErrorReporter.maxPerMinute + 5; i++) { + r.report('k', 'e$i'); + } + expect(queue.entries, hasLength(ErrorReporter.maxPerMinute)); + clock = clock.add(const Duration(minutes: 1)); + r.report('k', 'later'); + expect(queue.entries, hasLength(ErrorReporter.maxPerMinute + 1)); + }); + + test('never throws on an error whose toString throws', () { + reporter().report('k', _Throws()); + expect(queue.entries, isEmpty); + }); + + test('stamps the route', () { + final r = reporter()..route = '/list'; + r.report('k', 'x'); + expect(queue.entries.single.route, '/list'); + }); + }); + + group('SlowWaitReporter', () { + SlowWaitReporter waits() => + SlowWaitReporter(queue, now: () => clock, route: () => '/home'); + + test('a wait over a second is one perf.slow entry', () { + final w = waits().begin('list.load'); + clock = clock.add(const Duration(seconds: 2)); + w + ..end() + ..end(); + final e = queue.entries.single; + expect(e.kind, perfSlowKind); + expect(e.operation, 'list.load'); + expect(e.durationMs, 2000); + expect(e.route, '/home'); + expect(e.error, 'list.load waited 2000 ms'); + expect(e.still, isFalse); + }); + + test('a wait under a second writes nothing', () { + final w = waits().begin('quick'); + clock = clock.add(const Duration(milliseconds: 900)); + w.end(); + expect(queue.entries, isEmpty); + }); + + test('a hung wait is written while still going, then at its end', () async { + final r = SlowWaitReporter( + queue, + now: () => clock, + stillWaiting: const Duration(milliseconds: 5), + ); + final w = r.begin('hung'); + clock = clock.add(const Duration(seconds: 6)); + await Future.delayed(const Duration(milliseconds: 30)); + w.end(); + expect(queue.entries.map((e) => e.still), [true, false]); + expect(queue.entries.first.waitId, queue.entries.last.waitId); + }); + + test('caps slow entries per minute', () { + final r = waits(); + for (var i = 0; i < SlowWaitReporter.maxPerMinute + 3; i++) { + final w = r.begin('op'); + clock = clock.add(const Duration(milliseconds: 1500)); + w.end(); + } + expect(queue.entries, hasLength(SlowWaitReporter.maxPerMinute)); + }); + }); + + group('ErrorQueue', () { + test('survives a restart (offline reports are not lost)', () async { + reporter().report('k', 'offline'); + await queue.saved; + final again = await ErrorQueue.open( + await SharedPreferences.getInstance(), + ); + expect(again.entries.single.error, 'offline'); + }); + + test('keeps the newest maxEntries', () { + final r = ErrorReporter(queue, config: config, now: () => clock); + for (var i = 0; i < ErrorQueue.maxEntries + 3; i++) { + clock = clock.add(const Duration(minutes: 1)); + r.report('k', 'e$i'); + } + expect(queue.entries, hasLength(ErrorQueue.maxEntries)); + expect(queue.entries.last.error, 'e${ErrorQueue.maxEntries + 2}'); + }); + + test('a corrupt store opens empty', () async { + SharedPreferences.setMockInitialValues({ErrorQueue.key: 'not json'}); + final q = await ErrorQueue.open(await SharedPreferences.getInstance()); + expect(q.entries, isEmpty); + }); + }); + + group('ErrorUploader', () { + test('uploads to //errors// with the build', () async { + final sink = FakeSink(); + reporter().report('k', 'Bad state: token=abc123 me@x.org'); + final up = ErrorUploader( + queue, + config: config, + sink: () async => sink.call, + deviceId: () async => 'dev-1', + ); + expect(await up.flush(), isTrue); + expect(sink.patches.keys.single, 'todo/errors'); + final key = sink.patches['todo/errors']!.keys.single; + expect(key, startsWith('dev-1/')); + final e = sink.entries.single; + expect(e['build'], 42); + expect(e['version'], '1.2.3'); + expect(e['repo'], 'kuhyx/todo'); + expect(e['mark'], 'package:todo/'); + expect(e['error'], 'Bad state: token= '); + expect(queue.entries, isEmpty); + }); + + test('offline keeps the queue; back online sends it', () async { + final sink = FakeSink()..fail = true; + reporter().report('k', 'x'); + final up = ErrorUploader( + queue, + config: config, + sink: () async => sink.call, + deviceId: () async => 'd', + ); + expect(await up.flush(), isFalse); + expect(queue.entries, hasLength(1)); + sink.fail = false; + expect(await up.flush(), isTrue); + expect(sink.entries, hasLength(1)); + up.dispose(); + }); + + test('signed out (no sink) keeps the queue', () async { + reporter().report('k', 'x'); + final up = ErrorUploader( + queue, + config: config, + sink: () async => null, + deviceId: () async => 'd', + ); + expect(await up.flush(), isFalse); + expect(queue.entries, hasLength(1)); + up.dispose(); + }); + + test('nothing pending is a no-op', () async { + final up = ErrorUploader( + queue, + config: config, + sink: () async => throw StateError('never called'), + deviceId: () async => 'd', + ); + expect(await up.flush(), isTrue); + }); + + test('an append schedules a debounced flush', () async { + final sink = FakeSink(); + final up = ErrorUploader( + queue, + config: config, + sink: () async => sink.call, + deviceId: () async => 'd', + debounce: Duration.zero, + )..start(); + reporter().report('k', 'x'); + await Future.delayed(const Duration(milliseconds: 20)); + expect(sink.entries, hasLength(1)); + up.dispose(); + }); + }); + + group('installAppErrors', () { + late FlutterExceptionHandler? savedFlutter; + late ErrorCallback? savedAsync; + + setUp(() { + savedFlutter = FlutterError.onError; + savedAsync = PlatformDispatcher.instance.onError; + }); + + tearDown(() { + FlutterError.onError = savedFlutter; + PlatformDispatcher.instance.onError = savedAsync; + AppErrors.instance = null; + }); + + test('chains the framework and async hooks', () async { + final seen = []; + FlutterError.onError = (d) => seen.add(d.exception); + PlatformDispatcher.instance.onError = (e, s) { + seen.add(e); + return true; + }; + final errors = await installAppErrors( + config, + preferences: await SharedPreferences.getInstance(), + ); + expect(AppErrors.instance, same(errors)); + FlutterError.onError!( + FlutterErrorDetails(exception: StateError('framework')), + ); + FlutterError.onError!( + FlutterErrorDetails(exception: StateError('quiet'), silent: true), + ); + expect( + PlatformDispatcher.instance.onError!( + StateError('async'), + StackTrace.empty, + ), + isTrue, + ); + expect(seen, hasLength(3)); + expect(errors.queue.entries.map((e) => e.kind), [ + 'uncaught.flutter', + 'uncaught.async', + ]); + }); + + test('without prior hooks the async error is not handled', () async { + FlutterError.onError = null; + PlatformDispatcher.instance.onError = null; + final errors = await installAppErrors( + config, + preferences: await SharedPreferences.getInstance(), + ); + FlutterError.onError!(FlutterErrorDetails(exception: StateError('f'))); + expect( + PlatformDispatcher.instance.onError!('a', StackTrace.empty), + isFalse, + ); + expect(errors.queue.entries, hasLength(2)); + }); + + test('connect starts uploads; the route observer stamps routes', () async { + final errors = await installAppErrors( + config, + preferences: await SharedPreferences.getInstance(), + ); + final sink = FakeSink(); + final up = errors.connect( + sink: () async => sink.call, + deviceId: () async => 'd', + startDelay: Duration.zero, + ); + AppErrorsRouteObserver(errors).didPush( + MaterialPageRoute( + builder: (_) => const SizedBox(), + settings: const RouteSettings(name: '/settings'), + ), + null, + ); + errors.reporter.report('k', 'x'); + await Future.delayed(const Duration(milliseconds: 20)); + await up.flush(); + expect(sink.entries.single['route'], '/settings'); + up.dispose(); + }); + }); + + group('WaitWatch', () { + tearDown(() => AppErrors.instance = null); + + testWidgets('without AppErrors it only shows the child', (tester) async { + await tester.pumpWidget(const WaitWatch.centered('x')); + expect(find.byType(CircularProgressIndicator), findsOneWidget); + await tester.pumpWidget(const SizedBox()); + }); + + testWidgets('a spinner shown 2 s is a perf.slow entry', (tester) async { + var now = DateTime.utc(2026); + final errors = AppErrors.forTest(config, queue, now: () => now); + AppErrors.instance = errors; + await tester.pumpWidget( + const WaitWatch(operation: 'list.load', child: SizedBox()), + ); + now = now.add(const Duration(seconds: 2)); + await tester.pumpWidget(const SizedBox()); + expect(queue.entries.single.operation, 'list.load'); + }); + + testWidgets('backgrounding ends the wait, resuming starts one', ( + tester, + ) async { + var now = DateTime.utc(2026); + final errors = AppErrors.forTest(config, queue, now: () => now); + AppErrors.instance = errors; + await tester.pumpWidget( + const WaitWatch(operation: 'op', child: SizedBox()), + ); + tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.paused); + now = now.add(const Duration(seconds: 30)); + tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed); + now = now.add(const Duration(milliseconds: 100)); + await tester.pumpWidget(const SizedBox()); + expect(queue.entries, isEmpty, reason: 'background time is no wait'); + }); + }); + + test('install reads the default preferences', () async { + final saved = (FlutterError.onError, PlatformDispatcher.instance.onError); + final errors = await installAppErrors(config); + expect(errors.config.mark, 'package:todo/'); + FlutterError.onError = saved.$1; + PlatformDispatcher.instance.onError = saved.$2; + AppErrors.instance = null; + }); + + test('config mark uses the package name, else the app', () { + // ignore: prefer_const_constructors -- a runtime instance for coverage + final named = AppErrorsConfig(app: 'a-b', repo: 'o/a', package: 'pkg'); + expect(named.mark, 'package:pkg/'); + // ignore: prefer_const_constructors + expect(AppErrorsConfig(app: 'a-b', repo: 'o/a').mark, 'package:a_b/'); + }); + + test('route observer follows pop and replace', () { + final errors = AppErrors.forTest(config, queue); + final observer = AppErrorsRouteObserver(errors); + Route named(String name) => MaterialPageRoute( + builder: (_) => const SizedBox(), + settings: RouteSettings(name: name), + ); + observer.didPop(named('/b'), named('/a')); + expect(errors.reporter.route, '/a'); + observer.didReplace(newRoute: named('/c')); + expect(errors.reporter.route, '/c'); + observer.didPop(named('/c'), null); + expect(errors.reporter.route, '/c', reason: 'no name keeps the last'); + }); + + testWidgets('WaitWatch built at runtime', (tester) async { + // ignore: prefer_const_constructors + await tester.pumpWidget(WaitWatch.centered('x')); + // ignore: prefer_const_constructors + await tester.pumpWidget(WaitWatch(operation: 'y', child: SizedBox())); + expect(find.byType(SizedBox), findsOneWidget); + }); + + test('redactForReport masks secrets', () { + expect( + redactForReport( + 'GET https://u:p@x.io/a?key=1 Bearer abc eyJa.eyJb.c ' + 'password: hunter2 /home/kuhy/file', + ), + 'GET https://@x.io/a? Bearer ' + 'password: ~/file', + ); + }); + + test('ErrorEntry round-trips through JSON', () { + final e = ErrorEntry( + at: DateTime.utc(2026), + kind: perfSlowKind, + error: 'x', + stack: const ['a'], + route: '/r', + operation: 'op', + durationMs: 5, + waitId: 'w', + still: true, + ); + final back = ErrorEntry.fromJson(e.toJson()); + expect(back.toJson(), e.toJson()); + expect(ErrorEntry.tryFromJson('nope'), isNull); + }); +} + +class _Throws { + @override + String toString() => throw StateError('no'); +}