crdt_sync_flutter 0.9.0: app error + slow-wait reporter

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-17 21:48:34 +01:00
parent 8ca05a6764
commit eb4bd14754
13 changed files with 1247 additions and 1 deletions

View File

@ -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 `/<app>/errors/<device>/<id>` 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

View File

@ -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';

View File

@ -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<ErrorSink?> Function() sink,
required Future<String> 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<AppErrors> 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<dynamic>? route) {
final name = route?.settings.name;
if (name != null) errors.reporter.route = name;
}
@override
void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) =>
_set(route);
@override
void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) =>
_set(previousRoute);
@override
void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) =>
_set(newRoute);
}

View File

@ -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('-', '_')}/';
}

View File

@ -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<String, Object?> 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<Object?>? ?? []) '$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<String, Object?>);
} 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: `<operation> waited <ms> ms`).
final String error;
/// The innermost frames, then the app's own.
final List<String> 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<String, Object?> toJson() => {
'at': at.toUtc().toIso8601String(),
'kind': kind,
'error': error,
'stack': stack,
'route': ?route,
'operation': ?operation,
'durationMs': ?durationMs,
'waitId': ?waitId,
'still': ?still,
};
}

View File

@ -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<ErrorQueue> open(SharedPreferences prefs) async {
final entries = <ErrorEntry>[];
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<ErrorEntry> _entries;
final _added = StreamController<ErrorEntry>.broadcast();
Future<void> _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<ErrorEntry> get entries => List.unmodifiable(_entries);
/// Fires after each [add].
Stream<ErrorEntry> get added => _added.stream;
/// Completes when every change so far is stored.
Future<void> 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<String> 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));
}
}

View File

@ -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 = <String, DateTime>{};
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<String> _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)),
];
}
}

View File

@ -0,0 +1,121 @@
/// Uploads queued reports to RTDB `/<app>/errors/<device>/<id>`, 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<void> Function(String path, Map<String, Object?> 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<ErrorSink?> Function() sink;
/// This install's device id.
final Future<String> Function() deviceId;
/// Quiet time after an append before a flush.
final Duration debounce;
StreamSubscription<ErrorEntry>? _sub;
Timer? _timer;
Duration _backoff = minBackoff;
Future<bool> _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<bool> flush() => _tail = _tail.then((_) => _flushOnce());
Future<bool> _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<String, Object?> _payload(ErrorEntry e) => {
for (final MapEntry(:key, :value) in e.toJson().entries)
key: switch (value) {
final String s => redactForReport(s),
final List<Object?> l => [for (final f in l) redactForReport('$f')],
_ => value,
},
'repo': config.repo,
'mark': config.mark,
'build': config.build,
'version': ?config.version,
};
}

View File

@ -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?#"'<>]*)([?#])(?!<redacted>)[^\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]}<redacted>')
.replaceAllMapped(_userInfo, (m) => '${m[1]}<redacted>@')
.replaceAll(_jwt, '<jwt>')
.replaceAllMapped(_bearer, (m) => '${m[1]} <redacted>')
.replaceAllMapped(_named, (m) => '${m[1]}${m[2]}<redacted>')
.replaceAll(_email, '<email>')
.replaceAll(_home, '~/');

View File

@ -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);
}
}
}

View File

@ -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<WaitWatch> createState() => _WaitWatchState();
}
class _WaitWatchState extends State<WaitWatch> 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;
}

View File

@ -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

View File

@ -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 = <String, Map<String, Object?>>{};
bool fail = false;
Future<void> call(String path, Map<String, Object?> values) async {
if (fail) throw StateError('offline');
(patches[path] ??= {}).addAll(values);
}
List<Map<String, Object?>> get entries => [
for (final v in patches.values.expand((m) => m.values))
v! as Map<String, Object?>,
];
}
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<void>.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 /<app>/errors/<device>/<id> 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=<redacted> <email>');
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<void>.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 = <Object>[];
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<void>(
builder: (_) => const SizedBox(),
settings: const RouteSettings(name: '/settings'),
),
null,
);
errors.reporter.report('k', 'x');
await Future<void>.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<void> named(String name) => MaterialPageRoute<void>(
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://<redacted>@x.io/a?<redacted> Bearer <redacted> <jwt> '
'password: <redacted> ~/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');
}