From 93b795ed72fd75418cd94f54a5d66569f15c87f1 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 04:01:14 +0100 Subject: [PATCH] fix(#516): review round 2 - serialised reconcile, change runs skip copies a loading listing hides, failed copies lose their hash, change-run failures reported --- .../jeanlucmakiola/calendula/CalendulaApp.kt | 8 +- .../calendula/data/backup/AutoBackup.kt | 112 ++++++++++-------- .../calendula/data/prefs/SettingsPrefs.kt | 16 ++- .../calendula/domain/backup/BackupPlan.kt | 11 +- .../ui/calendars/CalendarsViewModel.kt | 8 +- .../ui/onboarding/OnboardingViewModel.kt | 8 +- .../calendula/domain/backup/BackupPlanTest.kt | 37 +++++- docs/ARCHITECTURE.md | 7 +- 8 files changed, 113 insertions(+), 94 deletions(-) diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt index 8310c571..6404f97b 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt @@ -110,13 +110,7 @@ class CalendulaApp : Application() { val deps = EntryPointAccessors.fromApplication(this, BackupWorker.Deps::class.java) CoroutineScope(SupervisorJob() + Dispatchers.Default).launch { val prefs = deps.settingsPrefs() - BackupScheduler.apply( - context = this@CalendulaApp, - enabled = prefs.autoBackupEnabled.first(), - intervalMinutes = prefs.autoBackupIntervalMinutes.first(), - hasFolder = prefs.autoBackupFolderUri.first() != null, - onChange = prefs.autoBackupOnChange.first(), - ) + BackupScheduler.reconcile(this@CalendulaApp, prefs) } } diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt index 07c154c7..5589f480 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt @@ -42,6 +42,7 @@ import de.jeanlucmakiola.calendula.domain.backup.withLedgerEntry import de.jeanlucmakiola.calendula.domain.ics.IcsWriter import de.jeanlucmakiola.floret.android.hasPermission import kotlinx.coroutines.NonCancellable +import androidx.work.await import kotlinx.coroutines.flow.first import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.withLock @@ -70,43 +71,49 @@ object BackupScheduler { /** Longest a change run waits on a provider that never goes quiet (a long sync). */ private const val CHANGE_MAX_WAIT_MINUTES = 15L + private val reconcileLock = Mutex() + /** - * Reconcile the scheduled work with the current settings: enqueue a unique + * Reconcile the scheduled work with the saved settings: enqueue a unique * periodic request when backup is on and a folder is set, otherwise cancel * it. WorkManager persists the request across reboots on its own. * * The first run is delayed by one interval so it doesn't follow an immediate - * [runNow] with a near-identical copy. [onChange] also arms the change - * trigger (#516), unless one is already waiting. + * [runNow] with a near-identical copy. With backing up after changes on + * (#516), the change trigger is armed unless a slot is already waiting. + * Serialised and not cancellable, so quick toggles settle on the last one. */ - suspend fun apply(context: Context, enabled: Boolean, intervalMinutes: Long, hasFolder: Boolean, onChange: Boolean) { - val workManager = WorkManager.getInstance(context) - if (!enabled || !hasFolder) { - workManager.cancelUniqueWork(WORK_NAME) - // Also cancel any pending immediate run — otherwise a failing run-now - // keeps retrying after the user has turned backup off. - workManager.cancelUniqueWork(WORK_NAME_NOW) - CHANGE_SLOTS.forEach(workManager::cancelUniqueWork) - return + suspend fun reconcile(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { + reconcileLock.withLock { + val workManager = WorkManager.getInstance(context) + suspend fun cancelWatch() = CHANGE_SLOTS.forEach { workManager.cancelUniqueWork(it).await() } + if (!prefs.autoBackupEnabled.first() || prefs.autoBackupFolderUri.first() == null) { + workManager.cancelUniqueWork(WORK_NAME) + // Also cancel any pending immediate run — otherwise a failing run-now + // keeps retrying after the user has turned backup off. + workManager.cancelUniqueWork(WORK_NAME_NOW) + cancelWatch() + return@withLock + } + // WorkManager's own floor is 15 min; the UI floors the user choice at 30. + val interval = prefs.autoBackupIntervalMinutes.first().coerceAtLeast(15L) + val request = PeriodicWorkRequestBuilder(interval, TimeUnit.MINUTES) + .setInitialDelay(interval, TimeUnit.MINUTES) + .build() + workManager.enqueueUniquePeriodicWork( + WORK_NAME, + ExistingPeriodicWorkPolicy.UPDATE, + request, + ) + if (!prefs.autoBackupOnChange.first()) { + cancelWatch() + return@withLock + } + val watching = CHANGE_SLOTS.any { name -> + workManager.getWorkInfosForUniqueWorkFlow(name).first().any { !it.state.isFinished } + } + if (!watching) watchChanges(context, slot = 0) } - // WorkManager's own floor is 15 min; the UI floors the user choice at 30. - val interval = intervalMinutes.coerceAtLeast(15L) - val request = PeriodicWorkRequestBuilder(interval, TimeUnit.MINUTES) - .setInitialDelay(interval, TimeUnit.MINUTES) - .build() - workManager.enqueueUniquePeriodicWork( - WORK_NAME, - ExistingPeriodicWorkPolicy.UPDATE, - request, - ) - if (!onChange) { - CHANGE_SLOTS.forEach(workManager::cancelUniqueWork) - return - } - val watching = CHANGE_SLOTS.any { name -> - workManager.getWorkInfosForUniqueWorkFlow(name).first().any { !it.state.isFinished } - } - if (!watching) watchChanges(context, slot = 0) } /** @@ -129,7 +136,8 @@ object BackupScheduler { * URI watched. A content trigger fires once and observes only while its * job waits, so a change run arms the other slot as it starts, catching * changes made during the run, and again as it ends in case that slot was - * still busy. A slot already waiting or running is kept. + * still busy. A slot already waiting or running is kept, so while two + * change runs overlap nothing watches until the second one ends. */ internal fun watchChanges(context: Context, slot: Int) { val constraints = Constraints.Builder() @@ -177,10 +185,9 @@ class BackupWorker( prefs.autoBackupFolderUri.first() != null if (wanted) BackupScheduler.watchChanges(applicationContext, slot = 1 - slot) } - watchNext() - // A change run neither fails nor retries: a retry would only wait for - // another change, and the other slot is already waiting for that. + // Never fails or retries: a retry would only wait for another change. try { + watchNext() backUp(deps, prefs, changeRun = true) } catch (e: CancellationException) { throw e @@ -194,8 +201,8 @@ class BackupWorker( /** * One run under the shared lock. A change run (#516) refreshes only the - * stable copies and leaves the status line to the scheduled backup, whose - * dated files it reports on. + * stable copies; it reports a failure, but a success stays off the status + * line, which dates the last dated backup. */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { val now = System.currentTimeMillis() @@ -216,8 +223,9 @@ class BackupWorker( RunOutcome.Failed } } - if (changeRun || outcome == RunOutcome.NothingToDo) return Result.success() + if (outcome == RunOutcome.NothingToDo) return Result.success() val success = outcome == RunOutcome.Written + if (changeRun && success) return Result.success() prefs.recordAutoBackupRun(success = success, atMillis = now) if (!success && prefs.autoBackupStatus.first().consecutiveFailures >= FAILURE_NOTIFY_THRESHOLD) { notifyFailure(applicationContext) @@ -247,8 +255,6 @@ class BackupWorker( val fingerprints = prefs.autoBackupFingerprints.first() // A listing still loading can't tell a gone file from a late one. val existing = if (listing.complete) listing.files.keys else listing.files.keys + ledger.values.flatten() - // Nor can it show that a stable copy is still there, so a change run rewrites it. - val listed = if (listing.complete) listing.files.keys else emptySet() val plans = planBackupFiles( targets = targets, ledger = ledger, @@ -284,21 +290,26 @@ class BackupWorker( val ownsLatest = landed == latest || latest in ledger[latestKey].orEmpty() val current = listOfNotNull(landed, latest.takeIf { ownsLatest }) // A hand-off stays on record only until its new owner claimed it. - suspend fun recordLatest(stale: List) = prefs.updateAutoBackupLedger(folder.toString()) { - val pending = plan.handOff - it.latestHeldElsewhere(target.key) - withLedgerEntry(it, latestKey, stale + pending + current, liveKeys) - } - recordLatest(plan.staleLatest) - if (landed == latest) { - prefs.updateAutoBackupFingerprints(folder.toString()) { - withFingerprint(it, target.key, fingerprint, liveKeys) + suspend fun recordLatest(stale: List, landedFingerprint: String? = null) = + prefs.updateAutoBackupLedger( + folder.toString(), + fingerprints = { old -> + landedFingerprint?.let { withFingerprint(old, target.key, it, liveKeys) } ?: old + }, + ) { + val pending = plan.handOff - it.latestHeldElsewhere(target.key) + withLedgerEntry(it, latestKey, stale + pending + current, liveKeys) } - } + recordLatest(plan.staleLatest, fingerprint.takeIf { landed == latest }) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) landed == latest } catch (e: Exception) { Log.w(TAG, "Stable copy of one series failed", e) + // The copy may be half-written now: the next change run must not take it as current. + runCatching { + prefs.updateAutoBackupLedger(folder.toString(), fingerprints = { it - plan.target.key }) { it } + } false } @@ -318,7 +329,7 @@ class BackupWorker( continue } val fingerprint = backupFingerprint(text) - if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listed)) { + if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listing.files.keys, listing.complete)) { landedLatest += target.key continue } @@ -327,8 +338,7 @@ class BackupWorker( // nothing would ever prune it. withContext(NonCancellable) { val dated = latestOnly || writeDated(plan, bytes) - // In a full run the stable copy is best-effort: it never holds up - // the dated backup, its pruning or the run's status. + // A full run's stable copy is best-effort and never holds up its status. val latest = plan.latestName != null && writeLatest(plan, bytes, fingerprint) if (latest) landedLatest += target.key if (if (latestOnly) latest else dated) written++ else failed++ diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt index 35ba184e..e039b9fe 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt @@ -379,24 +379,22 @@ class SettingsPrefs @Inject constructor( suspend fun setAutoBackupOnChange(enabled: Boolean) = prefs.set(SettingsKeys.autoBackupOnChange, enabled) - /** Like [updateAutoBackupLedger]: dropped once the folder is no longer [folder]. */ - suspend fun updateAutoBackupFingerprints(folder: String, transform: (BackupFingerprints) -> BackupFingerprints) { - prefs.edit { - if (it[SettingsKeys.autoBackupFolderUri] == folder) { - it[SettingsKeys.autoBackupFingerprints] = transform(it[SettingsKeys.autoBackupFingerprints]) - } - } - } /** * Atomic, so a run's ledger writes never undo one made meanwhile (pinning * the layout). Dropped when the folder is no longer [folder]: a run still * finishing must not carry the old folder's names into the new one's ledger. + * [fingerprints] updates the series' hashes (#516) in the same edit. */ - suspend fun updateAutoBackupLedger(folder: String, transform: (BackupLedger) -> BackupLedger) { + suspend fun updateAutoBackupLedger( + folder: String, + fingerprints: (BackupFingerprints) -> BackupFingerprints = { it }, + transform: (BackupLedger) -> BackupLedger, + ) { prefs.edit { if (it[SettingsKeys.autoBackupFolderUri] == folder) { it[SettingsKeys.autoBackupLedger] = transform(it[SettingsKeys.autoBackupLedger]) + it[SettingsKeys.autoBackupFingerprints] = fingerprints(it[SettingsKeys.autoBackupFingerprints]) } } } diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlan.kt b/app/src/main/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlan.kt index 917af288..fd73b1fd 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlan.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlan.kt @@ -325,14 +325,17 @@ fun parseBackupFingerprints(stored: String?): BackupFingerprints = /** * Whether a run started by a change (#516) rewrites this series' stable copy: * only when its content moved on from what the copy holds, or the copy is - * missing or mid-rename. Never when the name belongs to a file of the user's. + * missing or mid-rename. Never when the name belongs to a file of the user's, + * nor when a [complete]-less listing doesn't show the copy: writing then would + * add a duplicate beside it, so that is left to the scheduled run. */ fun BackupFilePlan.needsRefresh( fingerprint: String, stored: BackupFingerprints, - existing: Set, + listed: Set, + complete: Boolean, ): Boolean { val latest = latestName ?: return false - return stored[target.key] != fingerprint || latest !in existing || - staleLatest.isNotEmpty() || handOff.isNotEmpty() + if (latest !in listed) return complete + return stored[target.key] != fingerprint || staleLatest.isNotEmpty() || handOff.isNotEmpty() } diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarsViewModel.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarsViewModel.kt index 26720517..1480cd91 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarsViewModel.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarsViewModel.kt @@ -271,13 +271,7 @@ class CalendarsViewModel @Inject constructor( } private suspend fun reschedule() { - BackupScheduler.apply( - context = context, - enabled = settingsPrefs.autoBackupEnabled.first(), - intervalMinutes = settingsPrefs.autoBackupIntervalMinutes.first(), - hasFolder = settingsPrefs.autoBackupFolderUri.first() != null, - onChange = settingsPrefs.autoBackupOnChange.first(), - ) + BackupScheduler.reconcile(context, settingsPrefs) } private inline fun write(crossinline block: suspend () -> Unit) { diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingViewModel.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingViewModel.kt index cee0856c..7a8709f2 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingViewModel.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingViewModel.kt @@ -340,13 +340,7 @@ class OnboardingViewModel @Inject constructor( } prefs.setAutoBackupFolderUri(folder.toString()) prefs.setAutoBackupEnabled(true) - BackupScheduler.apply( - context = context, - enabled = true, - intervalMinutes = prefs.autoBackupIntervalMinutes.first(), - hasFolder = true, - onChange = prefs.autoBackupOnChange.first(), - ) + BackupScheduler.reconcile(context, prefs) // Immediate feedback: the first backup lands while onboarding runs. BackupScheduler.runNow(context) prefs.setOnboardingDone(OnboardingStep.Backup) diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlanTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlanTest.kt index 6df950c4..602a24f3 100644 --- a/app/src/test/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlanTest.kt +++ b/app/src/test/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlanTest.kt @@ -2,8 +2,11 @@ package de.jeanlucmakiola.calendula.domain.backup import com.google.common.truth.Truth.assertThat import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.ics.IcsEvent +import de.jeanlucmakiola.calendula.domain.ics.IcsWriter import org.junit.jupiter.api.Test import java.time.LocalDateTime +import kotlin.time.Instant class BackupPlanTest { @@ -304,17 +307,39 @@ class BackupPlanTest { assertThat(backupFingerprint(first)).hasLength(32) } + @Test + fun `the writer's output hashes the same at any stamp`() { + val event = IcsEvent( + uid = "u1", summary = "A", start = Instant.fromEpochSeconds(0), end = Instant.fromEpochSeconds(3600), + isAllDay = false, zoneId = "UTC", + ) + val early = IcsWriter().writeCalendar(listOf(event), Instant.fromEpochSeconds(0), "Work") + val late = IcsWriter().writeCalendar(listOf(event), Instant.fromEpochSeconds(1_800_000_000), "Work") + assertThat(early).isNotEqualTo(late) + assertThat(backupFingerprint(late)).isEqualTo(backupFingerprint(early)) + } + @Test fun `a change run refreshes only a changed, missing or moving stable copy`() { val target = backupTargets(listOf(cal(1L, "Work")), combined = false).single() val ledger = mapOf(latestLedgerKey("1") to listOf("Work.ics")) val plan = planBackupFiles(listOf(target), ledger, setOf("Work.ics"), at, keep = 3).single() val stored = mapOf("1" to "h1") - assertThat(plan.needsRefresh("h1", stored, setOf("Work.ics"))).isFalse() - assertThat(plan.needsRefresh("h2", stored, setOf("Work.ics"))).isTrue() - assertThat(plan.needsRefresh("h1", emptyMap(), setOf("Work.ics"))).isTrue() - assertThat(plan.needsRefresh("h1", stored, emptySet())).isTrue() - assertThat(plan.copy(staleLatest = listOf("Job.ics")).needsRefresh("h1", stored, setOf("Work.ics"))).isTrue() + val listed = setOf("Work.ics") + assertThat(plan.needsRefresh("h1", stored, listed, complete = true)).isFalse() + assertThat(plan.needsRefresh("h2", stored, listed, complete = true)).isTrue() + assertThat(plan.needsRefresh("h1", emptyMap(), listed, complete = true)).isTrue() + assertThat(plan.needsRefresh("h1", stored, emptySet(), complete = true)).isTrue() + assertThat(plan.copy(staleLatest = listOf("Job.ics")).needsRefresh("h1", stored, listed, complete = true)).isTrue() + } + + @Test + fun `a change run leaves a copy a loading listing doesn't show to the schedule`() { + val target = backupTargets(listOf(cal(1L, "Work")), combined = false).single() + val ledger = mapOf(latestLedgerKey("1") to listOf("Work.ics")) + val plan = planBackupFiles(listOf(target), ledger, setOf("Work.ics"), at, keep = 3).single() + assertThat(plan.needsRefresh("h2", mapOf("1" to "h1"), emptySet(), complete = false)).isFalse() + assertThat(plan.needsRefresh("h2", mapOf("1" to "h1"), setOf("Work.ics"), complete = false)).isTrue() } @Test @@ -322,6 +347,6 @@ class BackupPlanTest { val target = backupTargets(listOf(cal(1L, "Work")), combined = false).single() val plan = planBackupFiles(listOf(target), emptyMap(), setOf("Work.ics"), at, keep = 3).single() assertThat(plan.latestName).isNull() - assertThat(plan.needsRefresh("h1", emptyMap(), setOf("Work.ics"))).isFalse() + assertThat(plan.needsRefresh("h1", emptyMap(), setOf("Work.ics"), complete = true)).isFalse() } } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 21fdb90b..3c3be32b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -492,13 +492,14 @@ this app, a sync adapter or another app), a 2-minute settle delay capped at 15 minutes, and battery-not-low. A trigger fires once and observes only while its job waits, so there are two slots: a change run arms the other one as it starts (catching changes made during the run) and again as it ends. Runs share the -scheduled backup's lock. A change run only rewrites the stable copies and stays -off the status line: the dated files and their retention stay on the interval, +scheduled backup's lock. A change run only rewrites the stable copies and shows +on the status line only when it fails: the dated files and their retention stay on the interval, so a day of edits can't rotate the history out. Since the trigger fires for any provider change (reminders, other calendars, sync bookkeeping), each series' file is hashed without its `DTSTAMP`s (`auto_backup_fingerprints`, reset with the folder) and a change run skips the series whose hash and stable copy are -unchanged. A copy edited in place outside the app is put right by the next +unchanged; a failed write drops the hash. A copy a still-loading folder listing +doesn't show, or one edited in place outside the app, is left to the next scheduled run. **A backup carries the series' deleted and moved occurrences.** `EXDATE` lives on