From f18ae694a7229fff923c67d2fe938dfbc98be665 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 03:47:47 +0100 Subject: [PATCH] fix(#516): review round 1 - two watch slots so changes during a run count, change runs stay off the status line, one serialisation per series --- .../calendula/data/backup/AutoBackup.kt | 183 ++++++++++-------- .../calendula/domain/backup/BackupPlan.kt | 17 +- .../calendula/domain/backup/BackupPlanTest.kt | 8 +- docs/ARCHITECTURE.md | 19 +- 4 files changed, 132 insertions(+), 95 deletions(-) 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 c9d3e150..07c154c7 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 @@ -29,6 +29,7 @@ import de.jeanlucmakiola.calendula.R import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository import de.jeanlucmakiola.calendula.data.ics.IcsExporter import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs +import de.jeanlucmakiola.calendula.domain.backup.BackupFilePlan import de.jeanlucmakiola.calendula.domain.backup.backupFingerprint import de.jeanlucmakiola.calendula.domain.backup.backupTargets import de.jeanlucmakiola.calendula.domain.backup.needsRefresh @@ -49,7 +50,6 @@ import java.time.LocalDateTime import java.util.concurrent.TimeUnit import kotlin.coroutines.cancellation.CancellationException import kotlin.time.Clock -import kotlin.time.Instant /** * Schedules and runs the automatic periodic `.ics` backup (issue #8) of the @@ -61,8 +61,8 @@ object BackupScheduler { private const val WORK_NAME = "auto-backup" private const val WORK_NAME_NOW = "auto-backup-now" - private const val WORK_NAME_CHANGES = "auto-backup-changes" - internal const val KEY_CHANGE_RUN = "change_run" + private val CHANGE_SLOTS = listOf("auto-backup-changes-a", "auto-backup-changes-b") + internal const val KEY_CHANGE_SLOT = "change_slot" /** Quiet time after the last provider change before a change run starts, so a burst makes one run. */ private const val CHANGE_SETTLE_MINUTES = 2L @@ -77,16 +77,16 @@ object BackupScheduler { * * 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). + * trigger (#516), unless one is already waiting. */ - fun apply(context: Context, enabled: Boolean, intervalMinutes: Long, hasFolder: Boolean, onChange: Boolean) { + 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) - workManager.cancelUniqueWork(WORK_NAME_CHANGES) + CHANGE_SLOTS.forEach(workManager::cancelUniqueWork) return } // WorkManager's own floor is 15 min; the UI floors the user choice at 30. @@ -99,11 +99,14 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) - if (onChange) { - watchChanges(context, ExistingWorkPolicy.KEEP) - } else { - workManager.cancelUniqueWork(WORK_NAME_CHANGES) + 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) } /** @@ -120,13 +123,15 @@ object BackupScheduler { } /** - * Arm a one-off run on the next change in the calendar provider (#516). A - * content trigger fires once, so each change run arms the next one, queued - * behind itself ([ExistingWorkPolicy.APPEND_OR_REPLACE]). The provider - * reports every change on its root URI, whoever made it — this app, a sync - * adapter or another app — so that is the URI watched. + * Arm a one-off run on the next change in the calendar provider (#516) in + * one of two [slot]s. The provider reports every change on its root URI, + * whoever made it (this app, a sync adapter or another app), so that is the + * 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. */ - internal fun watchChanges(context: Context, policy: ExistingWorkPolicy) { + internal fun watchChanges(context: Context, slot: Int) { val constraints = Constraints.Builder() .addContentUriTrigger(CalendarContract.CONTENT_URI, true) .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) @@ -135,9 +140,9 @@ object BackupScheduler { .build() val request = OneTimeWorkRequestBuilder() .setConstraints(constraints) - .setInputData(workDataOf(KEY_CHANGE_RUN to true)) + .setInputData(workDataOf(KEY_CHANGE_SLOT to slot)) .build() - WorkManager.getInstance(context).enqueueUniqueWork(WORK_NAME_CHANGES, policy, request) + WorkManager.getInstance(context).enqueueUniqueWork(CHANGE_SLOTS[slot], ExistingWorkPolicy.KEEP, request) } } @@ -165,19 +170,36 @@ class BackupWorker( override suspend fun doWork(): Result { val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java) val prefs = deps.settingsPrefs() - if (!inputData.getBoolean(BackupScheduler.KEY_CHANGE_RUN, false)) return backUp(deps, prefs, changeRun = false) - // A change run neither fails nor retries: the next one is queued behind - // it, and a retry would only wait for another change anyway. - backUp(deps, prefs, changeRun = true) - val stillOn = prefs.autoBackupEnabled.first() && prefs.autoBackupOnChange.first() && - prefs.autoBackupFolderUri.first() != null - if (stillOn) BackupScheduler.watchChanges(applicationContext, ExistingWorkPolicy.APPEND_OR_REPLACE) + val slot = inputData.getInt(BackupScheduler.KEY_CHANGE_SLOT, -1) + if (slot < 0) return backUp(deps, prefs, changeRun = false) + suspend fun watchNext() { + val wanted = prefs.autoBackupEnabled.first() && prefs.autoBackupOnChange.first() && + 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. + try { + backUp(deps, prefs, changeRun = true) + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Backup after a change failed", e) + } finally { + withContext(NonCancellable) { runCatching { watchNext() } } + } return Result.success() } + /** + * 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. + */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { val now = System.currentTimeMillis() - // The periodic, the immediate and the change run are separate unique + // The periodic, the immediate and the change runs are separate unique // works; one at a time, or each would overwrite the other's ledger. val outcome = runLock.withLock { // Respect the toggles even for already-queued work, so a lingering @@ -194,7 +216,7 @@ class BackupWorker( RunOutcome.Failed } } - if (outcome == RunOutcome.NothingToDo) return Result.success() + if (changeRun || outcome == RunOutcome.NothingToDo) return Result.success() val success = outcome == RunOutcome.Written prefs.recordAutoBackupRun(success = success, atMillis = now) if (!success && prefs.autoBackupStatus.first().consecutiveFailures >= FAILURE_NOTIFY_THRESHOLD) { @@ -225,6 +247,8 @@ 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, @@ -236,17 +260,56 @@ class BackupWorker( val liveKeys = all.map { it.id.toString() }.toSet() suspend fun record(key: String, files: List) = prefs.updateAutoBackupLedger(folder.toString()) { withLedgerEntry(it, key, files, liveKeys) } + + suspend fun writeDated(plan: BackupFilePlan, bytes: ByteArray): Boolean = try { + val name = exporter.writeToFolder(folder, listing, plan.fileName, bytes) + record(plan.target.key, plan.prune + plan.keep + name) + val undeleted = exporter.deleteFromFolder(listing, plan.prune) + record(plan.target.key, plan.prune.filter { it in undeleted } + plan.keep + name) + true + } catch (e: Exception) { + Log.w(TAG, "Backup of one series failed", e) + false + } + + // Whether the stable copy landed under its own name. An old copy goes + // only once the new one has landed, so a series is never left without one. + suspend fun writeLatest(plan: BackupFilePlan, bytes: ByteArray, fingerprint: String): Boolean = try { + val target = plan.target + val latest = checkNotNull(plan.latestName) + val latestKey = latestLedgerKey(target.key) + val landed = exporter.writeToFolder(folder, listing, latest, bytes) + // A provider that renamed it leaves a copy to clean up next + // run; the intended name stays ours only if it already was. + 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) + } + } + 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) + false + } + var written = 0 var failed = 0 val landedLatest = mutableSetOf() for (plan in plans) { val target = plan.target if (latestOnly && plan.latestName == null) continue - val (bytes, fingerprint) = try { - val events = repository.exportEvents(target.calendarIds) - val writer = IcsWriter() - writer.writeCalendar(events, stamp, target.calendarName).toByteArray(Charsets.UTF_8) to - backupFingerprint(writer.writeCalendar(events, FINGERPRINT_STAMP, target.calendarName)) + val text = try { + IcsWriter().writeCalendar(repository.exportEvents(target.calendarIds), stamp, target.calendarName) } catch (e: CancellationException) { throw e } catch (e: Exception) { @@ -254,56 +317,21 @@ class BackupWorker( failed++ continue } - if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, existing)) { + val fingerprint = backupFingerprint(text) + if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listed)) { landedLatest += target.key continue } + val bytes = text.toByteArray(Charsets.UTF_8) // Not cancellable once a file exists: it must reach the ledger, or // nothing would ever prune it. withContext(NonCancellable) { - if (!latestOnly) { - try { - val name = exporter.writeToFolder(folder, listing, plan.fileName, bytes) - record(target.key, plan.prune + plan.keep + name) - val undeleted = exporter.deleteFromFolder(listing, plan.prune) - record(target.key, plan.prune.filter { it in undeleted } + plan.keep + name) - written++ - } catch (e: Exception) { - Log.w(TAG, "Backup of one series failed", e) - failed++ - } - } - // Best-effort in a full run: the stable copy never holds up the - // dated backup, its pruning or the run's status. An old copy goes - // only once the new one has landed, so a series is never left - // without one. - try { - val latest = plan.latestName ?: return@withContext - val latestKey = latestLedgerKey(target.key) - val landed = exporter.writeToFolder(folder, listing, latest, bytes) - if (latestOnly) written++ - // A provider that renamed it leaves a copy to clean up next - // run; the intended name stays ours only if it already was. - 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) { - landedLatest += target.key - prefs.updateAutoBackupFingerprints(folder.toString()) { - withFingerprint(it, target.key, fingerprint, liveKeys) - } - } - val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) - recordLatest(plan.staleLatest.filter { it in staleLeft }) - } catch (e: Exception) { - Log.w(TAG, "Stable copy of one series failed", e) - if (latestOnly) failed++ - } + 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. + val latest = plan.latestName != null && writeLatest(plan, bytes, fingerprint) + if (latest) landedLatest += target.key + if (if (latestOnly) latest else dated) written++ else failed++ } } // A layout switch retires the other layout's copies once every new one is there. @@ -363,8 +391,5 @@ class BackupWorker( private const val NOTIFICATION_ID = 2 private const val TAG = "BackupWorker" private val runLock = Mutex() - - // Fixed, so the hash follows the events and not the time of the run. - private val FINGERPRINT_STAMP = Instant.fromEpochMilliseconds(0) } } 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 e862872a..917af288 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 @@ -285,11 +285,16 @@ fun normalizeBackupKeep(stored: Int): Int = */ typealias BackupFingerprints = Map -/** Hash of [text], a series' file written with a fixed stamp so equal events give an equal hash. */ -fun backupFingerprint(text: String): String = - MessageDigest.getInstance("SHA-256").digest(text.toByteArray(Charsets.UTF_8)) - .take(FINGERPRINT_BYTES) - .joinToString("") { "%02x".format(it) } +/** Hash of a series' file, leaving out the run's `DTSTAMP`s so equal events give an equal hash. */ +fun backupFingerprint(ics: String): String { + val digest = MessageDigest.getInstance("SHA-256") + ics.lineSequence().filterNot { it.startsWith(DTSTAMP_PREFIX) } + .forEach { + digest.update(it.toByteArray(Charsets.UTF_8)) + digest.update(LINE_BREAK) + } + return digest.digest().take(FINGERPRINT_BYTES).joinToString("") { "%02x".format(it) } +} /** [previous] with [key] set to [fingerprint]; entries of deleted calendars go, as in [withLedgerEntry]. */ fun withFingerprint( @@ -301,6 +306,8 @@ fun withFingerprint( previous.filterKeys { it in liveKeys || it == COMBINED_SERIES } + (key to fingerprint) private const val FINGERPRINT_BYTES = 16 +private const val DTSTAMP_PREFIX = "DTSTAMP:" +private val LINE_BREAK = byteArrayOf('\n'.code.toByte()) private const val FINGERPRINT_SEP = "=" fun persistBackupFingerprints(fingerprints: BackupFingerprints): String? = 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 bf878d78..6df950c4 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 @@ -297,9 +297,11 @@ class BackupPlanTest { @Test fun `a fingerprint follows the content`() { - assertThat(backupFingerprint("a")).isEqualTo(backupFingerprint("a")) - assertThat(backupFingerprint("a")).isNotEqualTo(backupFingerprint("b")) - assertThat(backupFingerprint("a")).hasLength(32) + val first = "BEGIN:VEVENT\r\nDTSTAMP:20261113T143005Z\r\nSUMMARY:A\r\nEND:VEVENT\r\n" + val later = first.replace("20261113T143005Z", "20261114T090000Z") + assertThat(backupFingerprint(later)).isEqualTo(backupFingerprint(first)) + assertThat(backupFingerprint(first.replace("SUMMARY:A", "SUMMARY:B"))).isNotEqualTo(backupFingerprint(first)) + assertThat(backupFingerprint(first)).hasLength(32) } @Test diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b42e9bf0..21fdb90b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -489,14 +489,17 @@ install that already had a folder stays on the combined layout. arms a one-off `BackupWorker` with a WorkManager content-URI trigger on the provider's root URI (the provider notifies every change there, whoever made it: 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, so each change run arms the -next one behind itself (`APPEND_OR_REPLACE`); it shares the run lock with the -scheduled run. A change run only rewrites the stable copies: 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 with a fixed stamp -(`auto_backup_fingerprints`, reset with the folder) and a change run skips the -series whose hash, stable copy and name are unchanged. +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, +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 +scheduled run. **A backup carries the series' deleted and moved occurrences.** `EXDATE` lives on the master row and is part of `EventExportProjection`; `IcsWriter` marks an