A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:async';
import 'dart:convert';
import 'package:crypto/crypto.dart';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:provider/provider.dart';
import '../l10n/app_localizations.dart';
import '../main.dart' show rootNavigatorKey, applyAppearanceFromPrefs;
import '../providers/library_provider.dart';
import '../widgets/overlay_toast.dart';
import 'backup_service.dart';
import 'player_settings.dart';
import 'scoped_prefs.dart';
import 'user_account_service.dart';
enum SyncStatus {
ok,
notConfigured,
noRemote,
authFailed,
network,
tooLarge,
}
class SyncResult {
final SyncStatus status;
final String? message;
/// The real reason, kept verbatim for the settings screen to show: the HTTP
/// status, or the exception type and text, plus the URL that was actually
/// requested. A generic "could not reach that address" hides whether the
/// server said no, the name did not resolve, or a redirect landed on a
/// certificate the app will not trust.
final String? detail;
const SyncResult(this.status, [this.message, this.detail]);
bool get ok => status == SyncStatus.ok;
}
/// Keeps app settings in step across a user's devices by parking one JSON file
/// on their own WebDAV server (Nextcloud and friends). It reuses the backup
/// payload rather than inventing a second serializer, but only an explicit
/// subset of it travels - see [_syncedKeys].
///
/// WebDAV rather than Drive: it works on the GMS-free F-Droid build, most
/// self-hosters already have one, and a push is a single authenticated PUT
/// with no OAuth dance.
class SettingsSyncService {
static final SettingsSyncService _instance = SettingsSyncService._();
factory SettingsSyncService() => _instance;
SettingsSyncService._();
/// Swapped out in tests so the WebDAV round trip can be exercised without a
/// server. Null in the app, which falls through to the package-level helpers.
@visibleForTesting
static http.Client? testClient;
Future<http.Response> _put(Uri url, Map<String, String> headers, String body) {
final c = testClient;
return c != null
? c.put(url, headers: headers, body: body)
: http.put(url, headers: headers, body: body);
}
Future<http.Response> _getUrl(Uri url, Map<String, String> headers) {
final c = testClient;
return c != null ? c.get(url, headers: headers) : http.get(url, headers: headers);
}
/// The ONLY top-level backup keys that ever leave the device. This is an
/// allowlist and not a denylist on purpose: a key added to the backup later
/// must not start syncing just because someone forgot this file exists.
///
/// Deliberately absent, and why:
/// - pendingSyncs / pendingOfflineListening / offlineListening /
/// bookmarksPending* / pendingEbookProgress: this device's unsent listening
/// ledger. Copy it to a second device and both flush the same entries,
/// which is what produced the 28h phantom session.
/// - accounts / customHeaders: real server tokens. Also, ABS rotates refresh
/// tokens, so a stale one arriving from the file could overwrite a freshly
/// rotated one and strand the session.
/// - rmab: carries an API token, so it is opt-in rather than absent - see
/// [getSyncRmab].
/// - customDownloadPath: a path that is only true on one phone.
/// - offlineMode: a per-device switch.
/// - rollingDownloadSeries: switching auto-download on for a series is a
/// decision about THIS device's storage. Synced, the other phone quietly
/// started pulling the same books down. The global download switches
/// stay home for the same reason - see [_deviceLocalSettings].
/// - ereader: font, size, margins, theme. A phone and a tablet want
/// different ones, and the reading position already travels through the
/// server.
///
/// `podcastBookmarks` is here for the opposite reason: ABS bookmarks carry no
/// episode id, so those never reach the server and this is the only way they
/// reach another device. It is content, not a pending ledger.
///
/// `absorbingOrder` travels so the Absorbing shelf reads the same way on
/// every device. Membership already did (the manual adds and removes); the
/// order is what made a second device look scrambled.
static const _syncedKeys = <String>{
'settings',
'autoRewind',
'autoSleep',
'equalizer',
'bookSpeeds',
'notes',
'savedEbooks',
'upcomingAlwaysScan',
'upcomingNeverScan',
'upcomingIgnoredBooks',
'subscribedPodcasts',
'absorbingManualAdds',
'absorbingFinishedManualAdds',
'absorbingManualRemoves',
'yearHiddenIds',
'homeLayouts',
'librarySettings',
'metadataOverrides',
'ebookAnnotations',
'podcastBookmarks',
'absorbingOrder',
'navHold',
'podcastPrefs',
};
/// Entries inside the settings bucket that never travel, even though
/// `settings` itself does. Stripped in BOTH directions.
///
/// `trustAllCerts` is the one that matters: it feeds the global
/// badCertificateCallback, so accepting it from the remote file would let
/// anyone who can write to that file turn off certificate checking on every
/// device that pulls. A sync file is not allowed to weaken transport
/// security, so this stays a decision made on the device it applies to.
///
/// `loggingEnabled` is here for a duller reason - you turn debug logging on
/// for the device you are debugging, not for all of them.
///
/// The download switches are here because a download is a decision about
/// this device's storage and connection: one phone turning on queue
/// auto-download must not start filling the other.
///
/// The local server address deliberately is NOT here: it travels with
/// everything else, on the basis that a user's devices are usually on the
/// same network as their server.
static const _deviceLocalSettings = <String>{
'loggingEnabled',
'trustAllCerts',
'queueAutoDownload',
'autoDownloadOnStream',
'autoSeriesDownloadDefault',
'rollingDownloadCount',
'rollingDownloadDeleteFinished',
};
/// Refuse to push anything bigger than this. Ebook annotations and per-item
/// metadata overrides are unbounded, and silently shipping a huge blob to
/// someone's Nextcloud every time a setting changes is not a kindness.
static const _maxPayloadBytes = 2 * 1024 * 1024;
static const _pushDebounce = Duration(seconds: 20);
Timer? _debounce;
/// Most settings never fire the change notifier - theme and default speed go
/// through the plain setter, and the absorbing lists write prefs directly -
/// so the debounce above misses nearly everything a user actually changes.
/// Backgrounding is too late to rely on: the push is fire-and-forget and
/// Android can freeze the process before the request lands. So while the app
/// is open, check periodically whether the payload has moved. The check is a
/// local hash and costs nothing when nothing changed.
Timer? _changeCheck;
static const _changeCheckInterval = Duration(seconds: 45);
bool _started = false;
bool _busy = false;
DateTime? _lastPullAt;
/// With the folder unreachable (no signal, a network that blocks it) the
/// change check used to retry every 45 seconds for as long as the app
/// stayed alive. Automatic pushes now wait longer after each failure; the
/// manual Sync button and coming back to the app still try right away.
int _networkFailures = 0;
DateTime? _retryAfter;
static const _maxRetryDelay = Duration(minutes: 30);
void _noteNetworkFailure() {
_networkFailures++;
final minutes = 1 << (_networkFailures - 1).clamp(0, 5);
final delay = Duration(minutes: minutes) < _maxRetryDelay
? Duration(minutes: minutes)
: _maxRetryDelay;
_retryAfter = DateTime.now().add(delay);
debugPrint(
'[SettingsSync] folder unreachable ${_networkFailures}x - next automatic try in ${delay.inMinutes}m',
);
}
void _noteReachable() {
_networkFailures = 0;
_retryAfter = null;
}
/// Applying a remote payload writes every setting locally, which fires the
/// same change notification a user edit does. Left alone that pushes the
/// settings straight back up with a fresh timestamp, the other device pulls
/// them, applies, pushes again, and the two ping-pong forever. Ignore
/// changes for a moment after an import - long enough to cover the import's
/// un-awaited setters settling, short enough that a real edit right after
/// still gets picked up by the next one.
DateTime? _suppressPushUntil;
static const _suppressAfterImport = Duration(seconds: 10);
// Config, scoped per account.
Future<bool> getEnabled() async =>
await ScopedPrefs.getBool('settingsSyncEnabled') ?? false;
Future<void> setEnabled(bool v) async {
await ScopedPrefs.setBool('settingsSyncEnabled', v);
if (v) {
start();
} else {
stop();
}
}
Future<String?> getUrl() => ScopedPrefs.getString('settingsSyncUrl');
Future<void> setUrl(String v) =>
ScopedPrefs.setString('settingsSyncUrl', v.trim());
Future<String?> getUsername() => ScopedPrefs.getString('settingsSyncUser');
Future<void> setUsername(String v) =>
ScopedPrefs.setString('settingsSyncUser', v.trim());
Future<String?> getPassword() => ScopedPrefs.getString('settingsSyncPass');
Future<void> setPassword(String v) =>
ScopedPrefs.setString('settingsSyncPass', v);
/// Extra headers sent with every WebDAV request, for folders that sit behind
/// a proxy wanting its own header (Cloudflare Access and friends). Not an
/// alternative to the username and password - it rides alongside them.
Future<Map<String, String>> getCustomHeaders() async {
final raw = await ScopedPrefs.getString('settingsSyncHeaders');
if (raw == null || raw.trim().isEmpty) return const {};
try {
final decoded = jsonDecode(raw);
if (decoded is Map) {
return decoded.map((k, v) => MapEntry('$k', '$v'));
}
} catch (_) {}
return const {};
}
Future<void> setCustomHeaders(Map<String, String> headers) =>
ScopedPrefs.setString(
'settingsSyncHeaders',
headers.isEmpty ? '' : jsonEncode(headers),
);
/// Parse the settings screen's one-per-line `Name: value` text. Lines
/// without a colon are skipped rather than silently mangled.
static Map<String, String> parseHeaderLines(String text) {
final out = <String, String>{};
for (final line in text.split('\n')) {
final trimmed = line.trim();
if (trimmed.isEmpty) continue;
final idx = trimmed.indexOf(':');
if (idx <= 0) continue;
final name = trimmed.substring(0, idx).trim();
final value = trimmed.substring(idx + 1).trim();
if (name.isEmpty) continue;
out[name] = value;
}
return out;
}
static String headerLines(Map<String, String> headers) =>
headers.entries.map((e) => '${e.key}: ${e.value}').join('\n');
/// Opt-in because the ReadMeABook config carries an API token, and that is
/// the user's decision to make about their own storage rather than a default
/// worth choosing for them.
Future<bool> getSyncRmab() async =>
await ScopedPrefs.getBool('settingsSyncIncludeRmab') ?? false;
Future<void> setSyncRmab(bool v) =>
ScopedPrefs.setBool('settingsSyncIncludeRmab', v);
/// Top-level keys allowed right now, base set plus whatever the user opted
/// into. Resolved fresh on both push and pull, and it is deliberately THIS
/// device's choice that decides on the way in - a remote file cannot opt a
/// device into receiving something it has turned off.
///
/// Server logins are not on offer here at any setting. Beyond the tokens
/// themselves, ABS rotates refresh tokens, so a stale one arriving from the
/// file could overwrite a freshly rotated one and strand the session.
Future<Set<String>> _activeKeys() async => {
..._syncedKeys,
if (await getSyncRmab()) 'rmab',
};
/// Epoch ms of the newest payload this device has either written or applied.
/// Both directions compare against it, so a device never re-imports its own
/// push and never quietly loses a newer copy it has not seen.
Future<int> _lastSeen() async =>
await ScopedPrefs.getInt('settingsSyncLastSeen') ?? 0;
Future<void> _setLastSeen(int v) =>
ScopedPrefs.setInt('settingsSyncLastSeen', v);
/// Fingerprint of the last payload actually written, ignoring its timestamp.
Future<String?> _lastHash() => ScopedPrefs.getString('settingsSyncLastHash');
Future<void> _setLastHash(String v) =>
ScopedPrefs.setString('settingsSyncLastHash', v);
/// Encode with every map's keys sorted, at every depth.
///
/// Several payload buckets - book speeds, home layouts, per-library
/// settings, ebook annotations, podcast prefs - are built by walking
/// `prefs.getKeys()`, which has no defined order. Plain `jsonEncode` then
/// gives two devices different text for identical content, which made every
/// pull report a handful of phantom changes and could push when nothing had
/// actually moved.
static String _canonical(Object? value) {
if (value is Map) {
final keys = value.keys.map((k) => '$k').toList()..sort();
return '{${keys.map((k) => '${jsonEncode(k)}:${_canonical(value[k])}').join(',')}}';
}
if (value is List) {
return '[${value.map(_canonical).join(',')}]';
}
return jsonEncode(value);
}
static String _hash(Map<String, dynamic> payload) {
final copy = Map<String, dynamic>.from(payload)..remove('syncedAt');
return sha256.convert(utf8.encode(_canonical(copy))).toString();
}
Future<DateTime?> getLastSyncTime() async {
final ms = await _lastSeen();
return ms > 0 ? DateTime.fromMillisecondsSinceEpoch(ms) : null;
}
// Lifecycle.
/// Begin watching for settings changes when the user has this turned on.
/// Safe to call repeatedly.
Future<void> startIfEnabled() async {
if (await getEnabled()) start();
}
void start() {
if (_started) return;
_started = true;
PlayerSettings.settingsChanged.addListener(_onSettingsChanged);
_changeCheck?.cancel();
_changeCheck = Timer.periodic(
_changeCheckInterval,
(_) => unawaited(pushIfChanged()),
);
debugPrint(
'[SettingsSync] started - change check every '
'${_changeCheckInterval.inSeconds}s',
);
}
void stop() {
if (!_started) return;
_started = false;
_debounce?.cancel();
_debounce = null;
_changeCheck?.cancel();
_changeCheck = null;
PlayerSettings.settingsChanged.removeListener(_onSettingsChanged);
debugPrint('[SettingsSync] stopped');
}
void _onSettingsChanged() {
final until = _suppressPushUntil;
if (until != null && DateTime.now().isBefore(until)) return;
_debounce?.cancel();
// Through the content check, not straight to push. The notifier fires for
// plenty of things that never reach the payload (and fires repeatedly for
// one user action), and every redundant upload bumps syncedAt, which makes
// the other device wake up and "apply" a file identical to what it has.
_debounce = Timer(_pushDebounce, () => unawaited(pushIfChanged()));
}
/// Nothing pulls while the app sits open, so this is the only chance to
/// notice another device's changes. The guard is only here to collapse the
/// double call at startup (main() and the first foreground) and any lifecycle
/// flapping - it is deliberately short, because a long one would skip the
/// pull for a quick app switch and then leave the settings stale for as long
/// as the app stayed open, which is the very thing this is meant to fix.
static const _foregroundPullGuard = Duration(seconds: 10);
Future<void> onAppForegrounded() async {
if (!await getEnabled()) return;
_changeCheck?.cancel();
_changeCheck = Timer.periodic(
_changeCheckInterval,
(_) => unawaited(pushIfChanged()),
);
final now = DateTime.now();
if (_lastPullAt != null &&
now.difference(_lastPullAt!) < _foregroundPullGuard) {
return;
}
_lastPullAt = now;
// Coming back to the app is a natural moment to try again.
_retryAfter = null;
// Send anything this device is still holding BEFORE taking the remote copy.
// A change made just before the app was swiped away never got its push -
// the process was gone - so it is sitting here unsent. Pulling first would
// overwrite it with the other device's older copy and then upload that,
// losing the change silently. Pushing first stamps our copy as the newest,
// and the pull below then sees its own timestamp and skips.
if (await _hasUnsentChanges()) {
debugPrint('[SettingsSync] unsent local changes - pushing before pulling');
await pushIfChanged();
}
final result = await pull();
// Settings quietly rearranging themselves is unnerving, so say so - but
// only when something actually landed. A pull that found nothing new, or
// could not reach the server, is not worth interrupting anyone for.
if (result.ok && result.message == 'applied') {
_toastApplied(_lastApplyCount);
}
// Catch anything that changed while the app was away without going through
// the settings notifier - see [pushIfChanged].
await pushIfChanged();
}
/// How many entries the last applied pull actually moved. A count rather
/// than a list of names: naming them would need a translated label for every
/// setting, and the first pull on a new device changes everything at once,
/// which no toast can hold. The number answers the question someone actually
/// has when settings shift under them - was that a tweak or a wholesale
/// replace.
int _lastApplyCount = 0;
@visibleForTesting
int get debugLastApplyCount => _lastApplyCount;
/// Entries the incoming payload would actually move. Settings are counted
/// one by one; every other bucket counts as a single thing, since "your home
/// screen layout changed" is one fact to a reader, not fourteen.
///
/// Only keys PRESENT in [after] are considered, because that is exactly what
/// importSettings applies - a key the remote file omits leaves the local
/// value alone, so counting it as a change would report a wholesale replace
/// every time an older or partial payload arrived.
static int _countChanges(
Map<String, dynamic> before,
Map<String, dynamic> after,
) {
const ignored = {'syncedAt', 'version', 'appVersion'};
var changed = 0;
for (final key in after.keys) {
if (ignored.contains(key)) continue;
if (key == 'settings') {
final b = before['settings'] as Map? ?? const {};
final a = after['settings'] as Map? ?? const {};
for (final sk in a.keys) {
if (_canonical(b[sk]) != _canonical(a[sk])) changed++;
}
} else if (_canonical(before[key]) != _canonical(after[key])) {
changed++;
}
}
return changed;
}
/// Importing only rewrites SharedPreferences. Anything already holding those
/// values in memory keeps serving the old ones, and the absorbing lists go
/// further and write their stale copy back over what just arrived. So after
/// an import, tell the live app to re-read.
Future<void> _applyToRunningApp() async {
try {
await applyAppearanceFromPrefs();
} catch (e) {
debugPrint('[SettingsSync] appearance refresh failed: $e');
}
try {
final navigator = rootNavigatorKey.currentState;
final context = navigator?.context;
if (context != null && context.mounted) {
await Provider.of<LibraryProvider>(
context,
listen: false,
).reloadPrefsBackedState();
}
} catch (e) {
debugPrint('[SettingsSync] library reload failed: $e');
}
// Skip amounts, notification labels and the rest of the player's cached
// settings come back through the normal settings-changed path.
PlayerSettings.notifySettingsChanged();
}
void _toastApplied(int count) {
final navigator = rootNavigatorKey.currentState;
if (navigator == null) return;
final l = AppLocalizations.of(navigator.context);
showNavigatorOverlayToast(
navigator,
l?.syncSettingsAppliedCount(count) ??
'$count settings updated from your other device',
icon: Icons.cloud_done_rounded,
);
}
/// A restored backup can carry the sync setup, but its content is a copy of
/// another phone's past, not edits made here - so it must not race the
/// server. Fingerprint the restored state as already-uploaded first (nothing
/// pushes on its own), start syncing, then ask which copy wins: the server's
/// last sync, or this backup - which replaces the file on the server for
/// every synced device. Dismissing the dialog leaves the server as the
/// source: the cleared last-seen stamp means the next pull applies it.
Future<void> resolveSourceAfterRestore() async {
if (!await getEnabled()) return;
try {
await _setLastHash(_hash(await buildPayload()));
} catch (_) {}
start();
final navigator = rootNavigatorKey.currentState;
final context = navigator?.context;
if (context == null || !context.mounted) return;
final l = AppLocalizations.of(context)!;
final useBackup = await showDialog<bool>(
context: context,
builder: (ctx) => AlertDialog(
title: Text(l.syncSourceTitle),
content: Text(l.syncSourceBody),
actions: [
TextButton(
onPressed: () => Navigator.pop(ctx, true),
child: Text(l.syncSourceUseBackup),
),
FilledButton(
onPressed: () => Navigator.pop(ctx, false),
child: Text(l.syncSourceUseServer),
),
],
),
);
if (useBackup == null) return;
if (useBackup) {
final r = await push();
r.ok ? _toastUploaded() : _toastProblem();
return;
}
var r = await pull(force: true);
if (r.status == SyncStatus.noRemote) {
// Nothing on the server to prefer - seed it with what this device has.
r = await push();
r.ok ? _toastUploaded() : _toastProblem();
return;
}
if (r.ok && r.message == 'applied') {
_toastApplied(_lastApplyCount);
} else if (!r.ok) {
_toastProblem();
}
}
void _toastUploaded() {
final navigator = rootNavigatorKey.currentState;
if (navigator == null) return;
final l = AppLocalizations.of(navigator.context);
showNavigatorOverlayToast(
navigator,
l?.syncSettingsUploaded ?? 'Settings uploaded',
icon: Icons.cloud_upload_rounded,
);
}
void _toastProblem() {
final navigator = rootNavigatorKey.currentState;
if (navigator == null) return;
final l = AppLocalizations.of(navigator.context);
showNavigatorOverlayToast(
navigator,
l?.syncSettingsStatusProblem ?? 'Could not reach your server',
icon: Icons.cloud_off_rounded,
);
}
/// Whether this device is holding changes it has not managed to upload.
Future<bool> _hasUnsentChanges() async {
try {
return _hash(await buildPayload()) != await _lastHash();
} catch (_) {
return false;
}
}
/// Nudge from code that writes synced data straight to prefs without going
/// through PlayerSettings - ebook highlights and bookmarks, mainly. Without
/// it those wait for the periodic check, which is up to 45 seconds and does
/// not run at all once the app is backgrounded.
void noteLocalChange() {
if (!_started) return;
final until = _suppressPushUntil;
if (until != null && DateTime.now().isBefore(until)) return;
_debounce?.cancel();
_debounce = Timer(_pushDebounce, () => unawaited(pushIfChanged()));
}
/// Push when the payload's content has actually moved, regardless of whether
/// anything fired the settings notifier.
///
/// Most of what syncs is written straight through ScopedPrefs and never
/// notifies: ebook highlights, home layouts, per-book speeds, subscribed
/// podcasts, the absorbing lists, per-library skip overrides. Hanging uploads
/// solely off PlayerSettings.settingsChanged would leave all of that sitting
/// on the device until some unrelated toggle happened to move. Comparing a
/// hash of the payload catches it without making dozens of setters notify
/// and rebuild the UI for no reason.
Future<SyncResult> pushIfChanged({bool ignoreBackoff = false}) async {
if (!await getEnabled()) return const SyncResult(SyncStatus.notConfigured);
final retryAfter = _retryAfter;
if (!ignoreBackoff &&
retryAfter != null &&
DateTime.now().isBefore(retryAfter)) {
return const SyncResult(SyncStatus.network, 'waiting to retry');
}
try {
final hash = _hash(await buildPayload());
if (hash == await _lastHash()) {
return const SyncResult(SyncStatus.ok, 'unchanged');
}
debugPrint('[SettingsSync] settings moved since last upload - pushing');
} catch (e) {
debugPrint('[SettingsSync] change check failed: $e');
}
return push();
}
/// Called when the app goes to the background, so a session's worth of
/// highlights and layout changes ships without waiting for the next launch.
Future<void> onAppBackgrounded() async {
_debounce?.cancel();
_debounce = null;
_changeCheck?.cancel();
_changeCheck = null;
await pushIfChanged();
}
/// The backup payload, reduced to what may travel.
Future<Map<String, dynamic>> buildPayload() async {
final full = await BackupService.exportSettings(includeAccounts: false);
final allowed = await _activeKeys();
final out = <String, dynamic>{
'version': full['version'],
'appVersion': full['appVersion'],
};
for (final key in allowed) {
if (full.containsKey(key) && full[key] != null) out[key] = full[key];
}
out['settings'] = _stripSettings(out['settings']);
return out;
}
static Map<String, dynamic> _stripSettings(Object? settings) {
if (settings is! Map) return <String, dynamic>{};
final copy = Map<String, dynamic>.from(settings);
copy.removeWhere((k, _) => _deviceLocalSettings.contains(k));
return copy;
}
// Transport.
Uri? _remoteUri(String base) {
final trimmed = base.trim().replaceAll(RegExp(r'/+$'), '');
if (trimmed.isEmpty) return null;
final uri = Uri.tryParse('$trimmed/${_fileName()}');
if (uri == null || !uri.hasScheme || uri.host.isEmpty) return null;
return uri;
}
/// One file per account, named from a hash of the account scope so two
/// accounts pointed at the same folder cannot stomp each other, and so the
/// filename does not leak a server address into the user's file listing.
String _fileName() {
final scope = UserAccountService().activeScopeKey;
final digest = sha256.convert(utf8.encode(scope)).toString();
return 'absorb-settings-${digest.substring(0, 16)}.json';
}
/// Diagnostics for a response the app did not like. `location` matters: a
/// server that redirects plain HTTP to HTTPS is a common reason a URL that
/// works in a browser fails here.
static String _http(http.Response resp, Uri uri, String method) {
final buf = StringBuffer('$method $uri\nHTTP ${resp.statusCode}');
final location = resp.headers['location'];
if (location != null) buf.write('\nredirected to: $location');
final body = resp.body.trim();
if (body.isNotEmpty) {
buf.write('\n${body.substring(0, body.length.clamp(0, 300))}');
}
return buf.toString();
}
/// Diagnostics for a request that never produced a response at all. The
/// exception type is the useful half - a name that does not resolve, a
/// refused connection and a rejected certificate all read the same once
/// they have been flattened to a sentence.
static String _err(Object e, Uri uri, String method) =>
'$method $uri\n${e.runtimeType}: $e';
Future<Map<String, String>?> _authHeaders() async {
final user = await getUsername();
final pass = await getPassword();
if (user == null || user.isEmpty || pass == null || pass.isEmpty) {
return null;
}
final basic = base64Encode(utf8.encode('$user:$pass'));
// Custom headers first so a stray `Authorization` entry can't displace the
// credentials the user actually filled in.
return {...await getCustomHeaders(), 'authorization': 'Basic $basic'};
}
/// Push local settings up. No-op while another sync is mid-flight.
Future<SyncResult> push() async {
if (_busy) {
debugPrint('[SettingsSync] push skipped - another sync in flight');
return const SyncResult(SyncStatus.ok, 'busy');
}
if (!await getEnabled()) {
debugPrint('[SettingsSync] push skipped - sync is off');
return const SyncResult(SyncStatus.notConfigured);
}
final base = await getUrl();
if (base == null || base.isEmpty) {
debugPrint('[SettingsSync] push skipped - no folder address set');
return const SyncResult(SyncStatus.notConfigured);
}
final uri = _remoteUri(base);
final headers = await _authHeaders();
if (uri == null || headers == null) {
debugPrint('[SettingsSync] push skipped - address or sign-in incomplete');
return const SyncResult(SyncStatus.notConfigured);
}
_busy = true;
try {
final payload = await buildPayload();
final stamp = DateTime.now().millisecondsSinceEpoch;
payload['syncedAt'] = stamp;
final body = jsonEncode(payload);
if (body.length > _maxPayloadBytes) {
debugPrint(
'[SettingsSync] payload ${body.length}b over cap - not pushing',
);
return const SyncResult(SyncStatus.tooLarge);
}
final resp = await _put(
uri,
{...headers, 'content-type': 'application/json'},
body,
).timeout(const Duration(seconds: 20));
if (resp.statusCode == 401 || resp.statusCode == 403) {
return SyncResult(SyncStatus.authFailed, null, _http(resp, uri, 'PUT'));
}
if (resp.statusCode >= 200 && resp.statusCode < 300) {
_noteReachable();
await _setLastSeen(stamp);
await _setLastHash(_hash(payload));
debugPrint(
'[SettingsSync] pushed ${body.length}b (HTTP ${resp.statusCode})',
);
return const SyncResult(SyncStatus.ok);
}
debugPrint('[SettingsSync] push rejected - HTTP ${resp.statusCode}');
return SyncResult(SyncStatus.network, null, _http(resp, uri, 'PUT'));
} catch (e) {
debugPrint('[SettingsSync] push failed: ${e.runtimeType} - $e');
_noteNetworkFailure();
return SyncResult(SyncStatus.network, null, _err(e, uri, 'PUT'));
} finally {
_busy = false;
}
}
/// Fetch the remote copy and apply it when it is newer than anything this
/// device has seen. Returns [SyncStatus.noRemote] before any device has
/// pushed for the first time.
Future<SyncResult> pull({bool force = false}) async {
if (_busy) {
debugPrint('[SettingsSync] pull skipped - another sync in flight');
return const SyncResult(SyncStatus.ok, 'busy');
}
if (!await getEnabled()) {
debugPrint('[SettingsSync] pull skipped - sync is off');
return const SyncResult(SyncStatus.notConfigured);
}
final base = await getUrl();
if (base == null || base.isEmpty) {
return const SyncResult(SyncStatus.notConfigured);
}
final uri = _remoteUri(base);
final headers = await _authHeaders();
if (uri == null || headers == null) {
return const SyncResult(SyncStatus.notConfigured);
}
_busy = true;
try {
final resp =
await _getUrl(uri, headers).timeout(const Duration(seconds: 20));
if (resp.statusCode == 401 || resp.statusCode == 403) {
return SyncResult(SyncStatus.authFailed, null, _http(resp, uri, 'GET'));
}
if (resp.statusCode == 404) {
debugPrint('[SettingsSync] nothing on the server yet (404)');
return SyncResult(SyncStatus.noRemote, null, _http(resp, uri, 'GET'));
}
if (resp.statusCode < 200 || resp.statusCode >= 300) {
debugPrint('[SettingsSync] pull rejected - HTTP ${resp.statusCode}');
return SyncResult(SyncStatus.network, null, _http(resp, uri, 'GET'));
}
final decoded = jsonDecode(utf8.decode(resp.bodyBytes));
if (decoded is! Map<String, dynamic>) {
return SyncResult(
SyncStatus.network,
'unexpected file contents',
'GET $uri returned ${resp.statusCode} but the body was not a JSON '
'object. First 200 chars:\n'
'${resp.body.substring(0, resp.body.length.clamp(0, 200))}',
);
}
final remoteAt = (decoded['syncedAt'] as num?)?.toInt() ?? 0;
if (!force && remoteAt <= await _lastSeen()) {
debugPrint('[SettingsSync] remote not newer - nothing to apply');
return const SyncResult(SyncStatus.ok, 'up to date');
}
// Filter on the way in as well as out. The file sits on a server the app
// does not control, so a payload written by a future (or tampered)
// client cannot smuggle in accounts or a pending listening ledger.
final allowed = await _activeKeys();
final safe = <String, dynamic>{'version': decoded['version'] ?? 3};
for (final key in allowed) {
if (decoded.containsKey(key) && decoded[key] != null) {
safe[key] = decoded[key];
}
}
safe['settings'] = _stripSettings(safe['settings']);
// Measure against what this device holds right now, before the import
// overwrites it.
try {
_lastApplyCount = _countChanges(await buildPayload(), safe);
} catch (_) {
_lastApplyCount = 0;
}
_suppressPushUntil = DateTime.now().add(_suppressAfterImport);
await BackupService.importSettings(safe);
await _applyToRunningApp();
await _setLastSeen(remoteAt);
// Fingerprint what we just adopted, so the change check does not read the
// freshly-applied remote state as a local edit and bounce it straight
// back up.
try {
await _setLastHash(_hash(await buildPayload()));
} catch (_) {}
// Anything queued while the import was writing is the import's own echo,
// not a user edit.
_debounce?.cancel();
_debounce = null;
if (_lastApplyCount == 0) {
// The remote file was newer but identical - nothing actually moved, so
// there is nothing to tell the user about.
debugPrint(
'[SettingsSync] remote stamped $remoteAt was newer but identical',
);
return const SyncResult(SyncStatus.ok, 'up to date');
}
debugPrint(
'[SettingsSync] applied $_lastApplyCount change(s) from remote '
'stamped $remoteAt',
);
return const SyncResult(SyncStatus.ok, 'applied');
} catch (e) {
debugPrint('[SettingsSync] pull failed: ${e.runtimeType} - $e');
return SyncResult(SyncStatus.network, null, _err(e, uri, 'GET'));
} finally {
_busy = false;
}
}
/// One-shot check so the settings screen can tell the user whether the
/// address and credentials work, without touching local settings.
Future<SyncResult> testConnection() async {
final base = await getUrl();
if (base == null || base.isEmpty) {
return const SyncResult(SyncStatus.notConfigured);
}
final uri = _remoteUri(base);
final headers = await _authHeaders();
if (uri == null || headers == null) {
return const SyncResult(SyncStatus.notConfigured);
}
try {
final resp =
await _getUrl(uri, headers).timeout(const Duration(seconds: 15));
if (resp.statusCode == 401 || resp.statusCode == 403) {
return SyncResult(SyncStatus.authFailed, null, _http(resp, uri, 'GET'));
}
// A 404 only means nothing has been pushed yet, which is a fine outcome
// for first-time setup - the address and credentials still checked out.
if (resp.statusCode == 404) {
return SyncResult(SyncStatus.noRemote, null, _http(resp, uri, 'GET'));
}
if (resp.statusCode >= 200 && resp.statusCode < 300) {
return SyncResult(SyncStatus.ok, null, _http(resp, uri, 'GET'));
}
return SyncResult(SyncStatus.network, null, _http(resp, uri, 'GET'));
} catch (e) {
return SyncResult(SyncStatus.network, null, _err(e, uri, 'GET'));
}
}
}