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

This commit is contained in:
makiolaj committed 2026-11-14 03:47:47 +01:00
1 parent b2498d362b
commit f18ae694a7
4 files changed
+132 -95

No files matched your search

@@ -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<BackupWorker>()
.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<String>) =
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<String>) = 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<String>()
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<String>) = 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)
}
}
@@ -285,11 +285,16 @@ fun normalizeBackupKeep(stored: Int): Int =
*/
typealias BackupFingerprints = Map<String, String>
/** 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? =
@@ -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
+11 -8
View File
@@ -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