/// Whether this device is actually publishing, and when it last managed to. /// /// Exists because the failure it reports was invisible for days: the phone /// held meals nobody else could see, the PC's gate kept locking for slots that /// *were* logged, and every screen looked completely normal. A sync that /// silently stops must not be indistinguishable from a sync with nothing to /// say, so the outcome of every tick is recorded here and surfaced by /// [SyncHealthBanner] on the log screen. /// /// This is the *only* signal that reaches the user on a release build. The /// `log()` calls at each failure site go to `dart:developer`, which surfaces /// through the VM service and **not** logcat on a release APK -- verified on /// device: zero Dart-side lines appear under `adb logcat` even from paths that /// definitely ran. So the logging is for a debug session; the banner is what /// makes a stalled sync noticeable in real use. Do not "simplify" this away in /// favour of logging alone. /// /// Backed by SharedPreferences rather than a [DocumentStore] because a /// WorkManager background isolate writes it too: prefs need no per-isolate /// init, and a lost health stamp is cosmetic, never user data. library; import 'package:shared_preferences/shared_preferences.dart'; /// How stale the last success may get before the banner appears. /// /// Comfortably longer than the ~15 min periodic tick, so one missed or /// battery-deferred tick stays quiet and only a real stall shows up. const Duration kSyncStaleAfter = Duration(hours: 6); /// Why the last tick did not publish, or null when it did. enum SyncFailureKind { /// No backend at all: neither a Firebase account nor a GitHub token. unconfigured, /// A backend is configured but the attempt threw (offline, auth, remote). failed, } /// Records and reports the outcome of sync attempts. abstract final class SyncHealth { static const _kLastSuccess = 'sync.health.lastSuccessMs'; static const _kFailureKind = 'sync.health.failureKind'; /// Marks a tick that actually reached the remote. static Future recordSuccess() => _withPrefs((prefs) async { await prefs.setInt(_kLastSuccess, DateTime.now().millisecondsSinceEpoch); await prefs.remove(_kFailureKind); }); /// Marks a tick that could not publish because nothing is set up. static Future recordUnconfigured() => _recordFailure(SyncFailureKind.unconfigured); /// Marks a tick that had a backend but failed to publish. static Future recordFailure() => _recordFailure(SyncFailureKind.failed); static Future _recordFailure(SyncFailureKind kind) => _withPrefs((prefs) => prefs.setString(_kFailureKind, kind.name)); /// The current health, for the banner. /// /// Reports "healthy" when prefs are unreachable: a banner that cannot read /// its own state must not accuse a working device of being stalled. static Future read({DateTime? now}) async { final at = now ?? DateTime.now(); SharedPreferences prefs; try { prefs = await SharedPreferences.getInstance(); } on Object { return SyncHealthStatus(lastSuccess: null, failureKind: null, now: at); } final millis = prefs.getInt(_kLastSuccess); final stored = prefs.getString(_kFailureKind); return SyncHealthStatus( lastSuccess: millis == null ? null : DateTime.fromMillisecondsSinceEpoch(millis), failureKind: SyncFailureKind.values .where((value) => value.name == stored) .firstOrNull, now: at, ); } /// Forgets all recorded health. Test-only. static Future resetForTest() => _withPrefs((prefs) async { await prefs.remove(_kLastSuccess); await prefs.remove(_kFailureKind); }); /// Runs [action] against prefs, ignoring an unreachable platform channel. /// /// Health is diagnostics about syncing, never user data, so it must never /// take down the caller. Under `flutter test` the shared_preferences channel /// is unmocked by default and throws [MissingPluginException] -- the same /// reason [runSync]'s callers treat that as equivalent to being offline. static Future _withPrefs( Future Function(SharedPreferences prefs) action, ) async { try { await action(await SharedPreferences.getInstance()); } on Object { // Losing a health stamp costs a banner, never a meal. } } } /// A snapshot of whether this device is publishing. class SyncHealthStatus { /// Creates a snapshot evaluated as of [now]. const SyncHealthStatus({ required this.lastSuccess, required this.failureKind, required this.now, }); /// When this device last published successfully, or null if it never has. final DateTime? lastSuccess; /// Why the most recent attempt did not publish, or null when it did. final SyncFailureKind? failureKind; /// The moment this snapshot was evaluated against. final DateTime now; /// True when the user should be told that syncing has stopped. /// /// A device that has never synced is *not* flagged: a fresh install with no /// account yet is a normal state, and nagging there would train the banner /// to be ignored. Only a device that used to work, or one that explicitly /// failed, is worth interrupting for. bool get isStalled { if (failureKind == SyncFailureKind.failed) return true; final last = lastSuccess; if (last == null) return false; return now.difference(last) > kSyncStaleAfter; } /// One line explaining the state, or null when there is nothing to say. String? get message { if (!isStalled) return null; if (failureKind == SyncFailureKind.unconfigured) { return 'Not syncing: no account connected. Meals stay on this device.'; } final since = lastSuccess == null ? null : now.difference(lastSuccess!); // An elapsed time is only worth showing once it has actually elapsed. // A sync that failed moments after a success rendered "Not syncing since // 0h ago", which reads like a bug in the banner rather than a report // about the sync. if (since == null || since < const Duration(hours: 1)) { return 'Not syncing. Meals stay on this device.'; } return 'Not syncing since ${_ago(since)}. Meals stay on this device.'; } static String _ago(Duration since) { if (since.inDays >= 1) { return '${since.inDays}d ago'; } return '${since.inHours}h ago'; } }