diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index ba46a26e..86fe2f31 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -301,6 +301,12 @@ + + + + + + + diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt index 2a5a2b36..0661c415 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt @@ -1,8 +1,10 @@ package de.jeanlucmakiola.calendula import android.app.Application +import androidx.work.Configuration import dagger.hilt.android.EntryPointAccessors import dagger.hilt.android.HiltAndroidApp +import de.jeanlucmakiola.calendula.data.backup.BackupChangeJob import de.jeanlucmakiola.calendula.data.backup.BackupScheduler import de.jeanlucmakiola.calendula.data.calendar.CalendarVisibilityReconciler import de.jeanlucmakiola.calendula.data.backup.BackupWorker @@ -27,7 +29,11 @@ import kotlinx.coroutines.launch * in AndroidManifest.xml. Hilt initializes its component graph here. */ @HiltAndroidApp -class CalendulaApp : Application() { +class CalendulaApp : Application(), Configuration.Provider { + + /** Keeps WorkManager's JobScheduler ids clear of [BackupChangeJob]'s. */ + override val workManagerConfiguration: Configuration = + Configuration.Builder().setJobSchedulerJobIdRange(0, BackupChangeJob.JOB_ID - 1).build() override fun onCreate() { super.onCreate() @@ -110,12 +116,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, - ) + 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 fcb2ce0a..51875c6f 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 @@ -11,13 +11,17 @@ import android.util.Log import androidx.core.app.NotificationCompat import androidx.core.app.NotificationManagerCompat import androidx.core.net.toUri +import androidx.work.Constraints import androidx.work.CoroutineWorker import androidx.work.ExistingPeriodicWorkPolicy import androidx.work.ExistingWorkPolicy import androidx.work.OneTimeWorkRequestBuilder import androidx.work.PeriodicWorkRequestBuilder +import androidx.work.WorkInfo import androidx.work.WorkManager import androidx.work.WorkerParameters +import androidx.work.await +import androidx.work.workDataOf import dagger.hilt.EntryPoint import dagger.hilt.InstallIn import dagger.hilt.android.EntryPointAccessors @@ -26,14 +30,22 @@ 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.BackupTarget +import de.jeanlucmakiola.calendula.domain.backup.backupFingerprint import de.jeanlucmakiola.calendula.domain.backup.backupTargets -import de.jeanlucmakiola.calendula.domain.backup.planBackupFiles +import de.jeanlucmakiola.calendula.domain.backup.inBackupOrder import de.jeanlucmakiola.calendula.domain.backup.latestHeldElsewhere +import de.jeanlucmakiola.calendula.domain.backup.latestFileName import de.jeanlucmakiola.calendula.domain.backup.latestLedgerKey +import de.jeanlucmakiola.calendula.domain.backup.needsRefresh +import de.jeanlucmakiola.calendula.domain.backup.planBackupFiles import de.jeanlucmakiola.calendula.domain.backup.replacedLatestCopies +import de.jeanlucmakiola.calendula.domain.backup.withFingerprint import de.jeanlucmakiola.calendula.domain.backup.withLedgerEntry import de.jeanlucmakiola.calendula.domain.ics.IcsWriter import de.jeanlucmakiola.floret.android.hasPermission +import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.NonCancellable import kotlinx.coroutines.flow.first import kotlinx.coroutines.sync.Mutex @@ -54,26 +66,51 @@ object BackupScheduler { private const val WORK_NAME = "auto-backup" private const val WORK_NAME_NOW = "auto-backup-now" + private const val WORK_NAME_CHANGE = "auto-backup-change" + internal const val KEY_CHANGE_RUN = "change_run" + + private val reconcileLock = Mutex() + + /** A watch that fired while the option was off: still pending until it finishes, but not re-armed. */ + private var watchDropped = false /** - * 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. + * [runNow] with a near-identical copy. With backing up after changes on + * (#516), the change watch ([BackupChangeJob]) is armed unless it already + * waits; it doesn't survive a reboot, and this runs on every process start. + * Serialised and not cancellable, so quick toggles settle on the last one. */ - fun apply(context: Context, enabled: Boolean, intervalMinutes: Long, hasFolder: Boolean) { + suspend fun reconcile(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable + Dispatchers.IO) { + reconcileLock.withLock { + try { + apply(context, prefs) + } catch (e: Exception) { + Log.w(TAG, "Scheduling the automatic backup failed", e) + } + } + } + + private suspend fun apply(context: Context, prefs: SettingsPrefs) { val workManager = WorkManager.getInstance(context) - if (!enabled || !hasFolder) { + fun stopWatching() { + BackupChangeJob.cancel(context) + workManager.cancelUniqueWork(WORK_NAME_CHANGE) + } + 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) + stopWatching() return } // WorkManager's own floor is 15 min; the UI floors the user choice at 30. - val interval = intervalMinutes.coerceAtLeast(15L) + val interval = prefs.autoBackupIntervalMinutes.first().coerceAtLeast(15L) val request = PeriodicWorkRequestBuilder(interval, TimeUnit.MINUTES) .setInitialDelay(interval, TimeUnit.MINUTES) .build() @@ -82,6 +119,44 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) + if (!prefs.autoBackupOnChange.first()) { + stopWatching() + } else if (watchDropped || !BackupChangeJob.isPending(context)) { + // Replacing a waiting watch would drop the changes it has seen. + BackupChangeJob.schedule(context) + watchDropped = false + } + } + + /** + * The watch fired: queue a change run and arm the next watch, unless the + * option went off meanwhile. Under [reconcileLock], so it can't re-arm + * after a switch-off. + */ + internal suspend fun changed(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { + reconcileLock.withLock { + // Re-armed even when queueing the run fails: a trigger fires only once. + var wanted = true + try { + wanted = prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && + prefs.autoBackupOnChange.first() + if (wanted) queueChangeRun(context) + } finally { + if (wanted) BackupChangeJob.schedule(context) + watchDropped = !wanted + } + } + } + + private suspend fun queueChangeRun(context: Context) { + val workManager = WorkManager.getInstance(context) + val states = workManager.getWorkInfosForUniqueWorkFlow(WORK_NAME_CHANGE).first().map { it.state } + val policy = changeRunPolicy(states) ?: return + val run = OneTimeWorkRequestBuilder() + .setConstraints(Constraints.Builder().setRequiresBatteryNotLow(true).build()) + .setInputData(workDataOf(KEY_CHANGE_RUN to true)) + .build() + workManager.enqueueUniqueWork(WORK_NAME_CHANGE, policy, run).await() } /** @@ -96,6 +171,19 @@ object BackupScheduler { OneTimeWorkRequestBuilder().build(), ) } + + private const val TAG = "BackupScheduler" +} + +/** + * How a fired change watch queues its run (#516), from the change runs' work + * [states]: a run that hasn't started yet will see the change anyway (null); + * one already going may have read too early, so the new one queues behind it. + */ +internal fun changeRunPolicy(states: List): ExistingWorkPolicy? = when { + states.any { it == WorkInfo.State.ENQUEUED || it == WorkInfo.State.BLOCKED } -> null + WorkInfo.State.RUNNING in states -> ExistingWorkPolicy.APPEND_OR_REPLACE + else -> ExistingWorkPolicy.REPLACE } /** @@ -121,51 +209,108 @@ class BackupWorker( override suspend fun doWork(): Result { val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java) - val prefs = deps.settingsPrefs() - val now = System.currentTimeMillis() - // The periodic and the immediate run are separate unique works; one at - // a time, or each would overwrite the other's ledger. + val changeRun = inputData.getBoolean(BackupScheduler.KEY_CHANGE_RUN, false) + if (!changeRun) return backUp(deps, deps.settingsPrefs(), changeRun = false) + // A failed change run would fail the one queued behind it too. + try { + backUp(deps, deps.settingsPrefs(), changeRun = true) + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Backup after a change failed", e) + } + return Result.success() + } + + /** + * One run under the shared lock, recorded for the status line. A change + * run (#516) refreshes only the stable copies and never retries. The + * failure notification comes once per failure streak, when it reaches + * [FAILURE_NOTIFY_THRESHOLD], and goes with the next success of any run. + */ + private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { + // One run at a time, or each would overwrite the other's ledger. val outcome = runLock.withLock { - // Respect the toggle even for already-queued work, so a lingering + val now = System.currentTimeMillis() + // Respect the toggles even for already-queued work, so a lingering // run can't revive itself. if (!prefs.autoBackupEnabled.first()) return Result.success() + if (changeRun && !prefs.autoBackupOnChange.first()) return Result.success() val folder = prefs.autoBackupFolderUri.first() ?: return Result.failure() - try { - runBackup(deps, prefs, folder.toUri()) + val outcome = try { + runBackup(deps, prefs, folder.toUri(), latestOnly = changeRun) } catch (e: CancellationException) { throw e } catch (e: Exception) { Log.w(TAG, "Automatic backup failed", e) RunOutcome.Failed } - } - if (outcome == RunOutcome.NothingSelected) return Result.success() - val success = outcome == RunOutcome.Written - prefs.recordAutoBackupRun(success = success, atMillis = now) - if (!success && prefs.autoBackupStatus.first().consecutiveFailures >= FAILURE_NOTIFY_THRESHOLD) { - notifyFailure(applicationContext) + if (outcome != RunOutcome.NothingToDo) { + withContext(NonCancellable) { + prefs.recordAutoBackupRun(success = outcome == RunOutcome.Written, atMillis = now) + when { + outcome == RunOutcome.Written -> clearFailureNotification(applicationContext) + prefs.autoBackupStatus.first().consecutiveFailures == FAILURE_NOTIFY_THRESHOLD -> + notifyFailure(applicationContext) + } + } + } + outcome } // Only a run that wrote nothing retries: a retry rewrites every series. - return if (outcome == RunOutcome.Failed) Result.retry() else Result.success() + return if (outcome == RunOutcome.Failed && !changeRun) Result.retry() else Result.success() } - private enum class RunOutcome { Written, PartlyFailed, Failed, NothingSelected } + private enum class RunOutcome { Written, PartlyFailed, Failed, NothingToDo } - /** Writes each series and prunes it only once its new file has landed. */ - private suspend fun runBackup(deps: Deps, prefs: SettingsPrefs, folder: Uri): RunOutcome { + /** How a stable copy's write went: under its own name, under one the provider picked, or not at all. */ + private enum class LatestWrite { Landed, Renamed, Failed } + + /** + * Writes each series and prunes it only once its new file has landed. A + * [latestOnly] run (#516) leaves the dated files and their retention to the + * schedule and rewrites only the stable copies whose calendars changed. + */ + private suspend fun runBackup(deps: Deps, prefs: SettingsPrefs, folder: Uri, latestOnly: Boolean): RunOutcome { val repository = deps.repository() val exporter = deps.exporter() if (!applicationContext.hasPermission(Manifest.permission.READ_CALENDAR)) return RunOutcome.Failed val all = repository.calendars().first() val selection = prefs.autoBackupSelection.first() val combined = prefs.autoBackupCombined.first() - if (all.none(selection::selects)) return RunOutcome.NothingSelected + if (all.none(selection::selects)) return RunOutcome.NothingToDo prefs.adoptLegacyBackupFile() val listing = exporter.listFolder(folder) val ledger = prefs.autoBackupLedger.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() val targets = backupTargets(all.filter(selection::selects), combined, ledger, existing) + if (targets.isEmpty()) return RunOutcome.NothingToDo + val stamp = Clock.System.now() + val fingerprints = prefs.autoBackupFingerprints.first() + suspend fun export(target: BackupTarget): String? = try { + val events = repository.exportEvents(target.calendarIds).inBackupOrder() + IcsWriter().writeCalendar(events, stamp, target.calendarName) + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Reading one series failed", e) + null + } + fun fingerprintOf(target: BackupTarget, text: String) = + backupFingerprint(text, latestFileName(target.baseName)) + // Hashes only serve change runs; without them a stale one could pass later. + val trackHashes = prefs.autoBackupOnChange.first() + if (!trackHashes && fingerprints.isNotEmpty()) prefs.updateAutoBackupFingerprints(folder.toString()) { emptyMap() } + // A change run hashes first (null: unreadable) and leaves the folder alone when nothing moved. + val preHashes: Map = if (latestOnly) { + targets.associate { target -> target.key to export(target)?.let { fingerprintOf(target, it) } } + } else { + emptyMap() + } + if (latestOnly && targets.all { preHashes[it.key].let { hash -> hash != null && hash == fingerprints[it.key] } }) { + return RunOutcome.NothingToDo + } val plans = planBackupFiles( targets = targets, ledger = ledger, @@ -173,59 +318,100 @@ class BackupWorker( at = LocalDateTime.now(), keep = prefs.autoBackupKeep.first(), ) - val stamp = Clock.System.now() val liveKeys = all.map { it.id.toString() }.toSet() suspend fun record(key: String, files: List) = prefs.updateAutoBackupLedger(folder.toString()) { withLedgerEntry(it, key, files, liveKeys) } - var written = 0 - val landedLatest = mutableSetOf() - for (plan in plans) { + + 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 + } + + // An old copy goes only once the new one has landed. + suspend fun writeLatest(plan: BackupFilePlan, bytes: ByteArray, fingerprint: String): LatestWrite { val target = plan.target - val bytes = try { - IcsWriter() - .writeCalendar(repository.exportEvents(target.calendarIds), stamp, target.calendarName) - .toByteArray(Charsets.UTF_8) - } catch (e: CancellationException) { - throw e - } catch (e: Exception) { - Log.w(TAG, "Reading one series failed", e) - continue - } - // Not cancellable once a file exists: it must reach the ledger, or - // nothing would ever prune it. - withContext(NonCancellable) { - 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) + val latest = checkNotNull(plan.latestName) + var landed: String? = null + try { + val latestKey = latestLedgerKey(target.key) + if (trackHashes && target.key in fingerprints) { + prefs.updateAutoBackupFingerprints(folder.toString()) { it - target.key } } - // Best-effort: 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) - // 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()) { + 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, landedFingerprint: String? = null) = + prefs.updateAutoBackupLedger( + folder.toString(), + fingerprints = landedFingerprint?.let { hash -> + { old -> withFingerprint(old, target.key, hash, liveKeys) } + }, + ) { val pending = plan.handOff - it.latestHeldElsewhere(target.key) withLedgerEntry(it, latestKey, stale + pending + current, liveKeys) } - recordLatest(plan.staleLatest) - if (landed == latest) landedLatest += target.key - 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) + recordLatest(plan.staleLatest, fingerprint.takeIf { trackHashes }) + 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) + } + return when (landed) { + null -> LatestWrite.Failed + latest -> LatestWrite.Landed + else -> LatestWrite.Renamed + } + } + + // A copy blocked by a file of the user's keeps its hash, so a later change run can stop early. + suspend fun rememberBlocked(plan: BackupFilePlan, hash: String) { + val key = plan.target.key + if (plan.latestName == null && trackHashes && fingerprints[key] != hash) { + prefs.updateAutoBackupFingerprints(folder.toString()) { withFingerprint(it, key, hash, liveKeys) } + } + } + + var written = 0 + var failed = 0 + val landedLatest = mutableSetOf() + for (plan in plans) { + val target = plan.target + if (latestOnly) { + val hash = preHashes[target.key] ?: run { + failed++ + continue } + rememberBlocked(plan, hash) + if (!plan.needsRefresh(hash, fingerprints, listing.files.keys, listing.complete)) { + if (plan.latestName in listing.files) landedLatest += target.key + continue + } + } + // Read again rather than held since the pre-pass: one series' text in memory at a time. + val text = export(target) ?: run { + failed++ + continue + } + val fingerprint = fingerprintOf(target, text) + if (!latestOnly) rememberBlocked(plan, fingerprint) + val bytes = text.toByteArray(Charsets.UTF_8) + // Not cancellable once a file exists: it must reach the ledger. + withContext(NonCancellable) { + val dated = if (latestOnly) null else writeDated(plan, bytes) + val latest = plan.latestName?.let { writeLatest(plan, bytes, fingerprint) } + if (latest == LatestWrite.Landed) landedLatest += target.key + // A full run's status follows its dated file; the stable copy is best-effort there. + val ok = dated ?: (latest != LatestWrite.Failed) + if (ok) written++ else failed++ } } // A layout switch retires the other layout's copies once every new one is there. @@ -234,16 +420,23 @@ class BackupWorker( withContext(NonCancellable) { val left = exporter.deleteFromFolder(listing, names) record(latestLedgerKey(key), names.filter { it in left }) + // Its copy is gone, so its hash mustn't let a change run stop early. + prefs.updateAutoBackupFingerprints(folder.toString()) { it - key } } } } - return when (written) { - plans.size -> RunOutcome.Written - 0 -> RunOutcome.Failed + return when { + failed == 0 && written == 0 -> RunOutcome.NothingToDo + failed == 0 -> RunOutcome.Written + written == 0 -> RunOutcome.Failed else -> RunOutcome.PartlyFailed } } + private fun clearFailureNotification(context: Context) { + NotificationManagerCompat.from(context).cancel(NOTIFICATION_ID) + } + private fun notifyFailure(context: Context) { val canPost = Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU || context.hasPermission(Manifest.permission.POST_NOTIFICATIONS) diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt new file mode 100644 index 00000000..3b56b30d --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt @@ -0,0 +1,87 @@ +package de.jeanlucmakiola.calendula.data.backup + +import android.app.job.JobInfo +import android.app.job.JobParameters +import android.app.job.JobScheduler +import android.app.job.JobService +import android.content.ComponentName +import android.content.Context +import android.provider.CalendarContract +import android.util.Log +import dagger.hilt.android.EntryPointAccessors +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.SupervisorJob +import kotlinx.coroutines.cancel +import kotlinx.coroutines.launch +import java.util.concurrent.TimeUnit + +/** + * The watch behind "Also back up after changes" (#516): a JobScheduler job + * with a content trigger on the provider's root URI, where it reports every + * change, whoever made it (this app, a sync adapter or another app). It waits + * for [SETTLE_MINUTES] of quiet, at most [MAX_WAIT_MINUTES], so a burst makes + * one run. A trigger fires once; each firing queues a change run and schedules + * the next watch under the same id before finishing, which hands over the + * changes seen meanwhile, so exactly one watch exists and none are lost. + */ +class BackupChangeJob : JobService() { + + private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) + + override fun onStartJob(params: JobParameters): Boolean { + scope.launch { + // Retried when it failed early, so the watch isn't lost; once re-armed, the retry is moot. + val failed = try { + val deps = EntryPointAccessors.fromApplication(applicationContext, BackupWorker.Deps::class.java) + BackupScheduler.changed(applicationContext, deps.settingsPrefs()) + false + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Queueing a backup after a change failed", e) + true + } + jobFinished(params, failed) + } + return true + } + + /** Stopped before it could re-arm: run again rather than leave the provider unwatched. */ + override fun onStopJob(params: JobParameters): Boolean = true + + override fun onDestroy() { + scope.cancel() + super.onDestroy() + } + + companion object { + /** Above the range WorkManager is given (see CalendulaApp). */ + const val JOB_ID = 0x0516_0001 + private const val SETTLE_MINUTES = 2L + private const val MAX_WAIT_MINUTES = 15L + private const val TAG = "BackupChangeJob" + + fun schedule(context: Context) { + val job = JobInfo.Builder(JOB_ID, ComponentName(context, BackupChangeJob::class.java)) + .addTriggerContentUri( + JobInfo.TriggerContentUri( + CalendarContract.CONTENT_URI, + JobInfo.TriggerContentUri.FLAG_NOTIFY_FOR_DESCENDANTS, + ), + ) + .setTriggerContentUpdateDelay(TimeUnit.MINUTES.toMillis(SETTLE_MINUTES)) + .setTriggerContentMaxDelay(TimeUnit.MINUTES.toMillis(MAX_WAIT_MINUTES)) + .build() + if (context.getSystemService(JobScheduler::class.java).schedule(job) != JobScheduler.RESULT_SUCCESS) { + Log.w(TAG, "The change watch could not be scheduled") + } + } + + fun isPending(context: Context): Boolean = + context.getSystemService(JobScheduler::class.java).getPendingJob(JOB_ID) != null + + fun cancel(context: Context) = context.getSystemService(JobScheduler::class.java).cancel(JOB_ID) + } +} 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 0ca2f272..d2f9027c 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 @@ -15,6 +15,9 @@ import de.jeanlucmakiola.calendula.domain.backup.normalizeBackupKeep import de.jeanlucmakiola.calendula.domain.backup.BackupLedger import de.jeanlucmakiola.calendula.domain.backup.parseBackupLedger import de.jeanlucmakiola.calendula.domain.backup.persistBackupLedger +import de.jeanlucmakiola.calendula.domain.backup.BackupFingerprints +import de.jeanlucmakiola.calendula.domain.backup.parseBackupFingerprints +import de.jeanlucmakiola.calendula.domain.backup.persistBackupFingerprints import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType import de.jeanlucmakiola.calendula.domain.reminders.ReminderAlertStyle import de.jeanlucmakiola.calendula.domain.reminders.parseAlertStyles @@ -221,6 +224,8 @@ class SettingsPrefs @Inject constructor( val autoBackupCombined: Flow = prefs.snapshot { it.autoBackupCombined } val autoBackupKeep: Flow = prefs.flow(SettingsKeys.autoBackupKeep) val autoBackupLedger: Flow = prefs.flow(SettingsKeys.autoBackupLedger) + val autoBackupOnChange: Flow = prefs.flow(SettingsKeys.autoBackupOnChange) + val autoBackupFingerprints: Flow = prefs.flow(SettingsKeys.autoBackupFingerprints) val specialDatesEnabled: Flow = prefs.flow(SettingsKeys.specialDatesEnabled) val specialDatesTypes: Flow> = prefs.snapshot { it.specialDatesTypes } val specialDatesCalendars: Flow> = prefs.snapshot { it.specialDatesCalendars } @@ -474,7 +479,10 @@ class SettingsPrefs @Inject constructor( it.pinBackupLayout() // The ledger says which files in the old folder are ours; in a new // one a file of the same name may be the user's. - if (it[SettingsKeys.autoBackupFolderUri] != uri) it[SettingsKeys.autoBackupLedger] = emptyMap() + if (it[SettingsKeys.autoBackupFolderUri] != uri) { + it[SettingsKeys.autoBackupLedger] = emptyMap() + it[SettingsKeys.autoBackupFingerprints] = emptyMap() + } it[SettingsKeys.autoBackupFolderUri] = uri } } @@ -488,15 +496,34 @@ class SettingsPrefs @Inject constructor( suspend fun setAutoBackupKeep(keep: Int) = prefs.set(SettingsKeys.autoBackupKeep, keep) + suspend fun setAutoBackupOnChange(enabled: Boolean) = prefs.set(SettingsKeys.autoBackupOnChange, enabled) + /** * 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)? = null, + transform: (BackupLedger) -> BackupLedger, + ) { prefs.edit { if (it[SettingsKeys.autoBackupFolderUri] == folder) { it[SettingsKeys.autoBackupLedger] = transform(it[SettingsKeys.autoBackupLedger]) + if (fingerprints != null) { + it[SettingsKeys.autoBackupFingerprints] = fingerprints(it[SettingsKeys.autoBackupFingerprints]) + } + } + } + } + + /** Like [updateAutoBackupLedger], for the series' hashes (#516) alone. */ + suspend fun updateAutoBackupFingerprints(folder: String, transform: (BackupFingerprints) -> BackupFingerprints) { + prefs.edit { + if (it[SettingsKeys.autoBackupFolderUri] == folder) { + it[SettingsKeys.autoBackupFingerprints] = transform(it[SettingsKeys.autoBackupFingerprints]) } } } @@ -973,6 +1000,13 @@ object SettingsKeys { val autoBackupLedger: Pref = nullableStringPref("auto_backup_files").map(::parseBackupLedger, ::persistBackupLedger) + /** Whether a change to a backed-up calendar also refreshes the stable copies (#516). Opt-in. */ + val autoBackupOnChange: Pref = booleanPref("auto_backup_on_change", false) + + /** Content hash of each series' stable copy, so a change run skips untouched ones (#516). */ + val autoBackupFingerprints: Pref = + nullableStringPref("auto_backup_fingerprints").map(::parseBackupFingerprints, ::persistBackupFingerprints) + /** Master switch for the contact special-dates mirror (issue #15). Opt-in. */ val specialDatesEnabled: Pref = booleanPref("special_dates_enabled", false) 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 b8998bbf..d47101e3 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 @@ -1,8 +1,11 @@ package de.jeanlucmakiola.calendula.domain.backup import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.ics.IcsEvent +import de.jeanlucmakiola.calendula.domain.ics.flattenOverrides import de.jeanlucmakiola.calendula.domain.isNotSynced import de.jeanlucmakiola.floret.android.safeFileName +import java.security.MessageDigest import java.time.LocalDateTime import java.time.format.DateTimeFormatter @@ -311,3 +314,89 @@ fun parseBackupLedger(stored: String?): BackupLedger = /** Closest offered retention count to [stored], so a stray value still shows a row. */ fun normalizeBackupKeep(stored: Int): Int = BACKUP_KEEP_OPTIONS.minBy { kotlin.math.abs(it - stored) } + +/** + * Content hash of a series' file, per series key (#516), so a run started by a + * change can tell whether the calendars it covers changed at all. + */ +typealias BackupFingerprints = Map + +/** + * Hash of a series' file, leaving out the run's `DTSTAMP`s so equal events give + * an equal hash, and bound to the stable copy's [fileName], so a copy under + * another name never passes as current. + */ +fun backupFingerprint(ics: String, fileName: String): String { + val digest = MessageDigest.getInstance("SHA-256") + digest.update(fileName.toByteArray(Charsets.UTF_8)) + digest.update(LINE_BREAK) + 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( + previous: BackupFingerprints, + key: String, + fingerprint: String, + liveKeys: Set, +): BackupFingerprints = + 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? = + fingerprints.takeIf { it.isNotEmpty() } + ?.entries?.sortedBy { it.key } + ?.joinToString(LEDGER_ENTRY_SEP) { (key, hash) -> "$key$FINGERPRINT_SEP$hash" } + +fun parseBackupFingerprints(stored: String?): BackupFingerprints = + stored?.split(LEDGER_ENTRY_SEP).orEmpty().mapNotNull { entry -> + val key = entry.substringBefore(FINGERPRINT_SEP, "") + val hash = entry.substringAfter(FINGERPRINT_SEP, "") + if (key.isEmpty() || hash.isEmpty()) null else key to hash + }.toMap() + +/** + * Whether a run started by a change (#516) rewrites this series' stable copy: + * only when its content moved on from what the copy holds (a rename changes + * the name written into it), or the copy is missing. 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, + listed: Set, + complete: Boolean, +): Boolean { + val latest = latestName ?: return false + if (latest !in listed) return complete + return stored[target.key] != fingerprint +} + +/** + * The events in a fixed order, their lists sorted, so the same content always + * writes the same file and hashes the same, however the provider returned it. + * Standalone occurrences stay first, as [flattenOverrides] puts them. + */ +fun List.inBackupOrder(): List = + map { + it.copy( + reminderMinutes = it.reminderMinutes.sorted(), + exDates = it.exDates.sorted(), + recurrenceDates = it.recurrenceDates.sorted(), + ) + }.sortedWith( + compareBy( + { it.overrideOf == null }, { it.start }, { it.uid }, { it.overrideAt }, { it.calendarName }, + { it.toString() }, + ), + ) diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt index 67f31445..b722c024 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt @@ -352,6 +352,13 @@ private fun BackupContent( position = Position.Middle, onClick = onEditInterval, ) + GroupedSwitchRow( + title = stringResource(R.string.calendars_auto_backup_on_change), + summary = stringResource(R.string.calendars_auto_backup_on_change_summary), + checked = autoBackup.onChange, + onCheckedChange = viewModel::setAutoBackupOnChange, + position = Position.Middle, + ) val selectedCount = exportable.count(autoBackup.selection::selects) GroupedRow( title = stringResource(R.string.calendars_auto_backup_calendars), 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 5ebad9b6..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 @@ -88,8 +88,9 @@ class CalendarsViewModel @Inject constructor( settingsPrefs.autoBackupSelection, settingsPrefs.autoBackupCombined, settingsPrefs.autoBackupKeep, - ) { base, selection, combined, keep -> - base.copy(selection = selection, combined = combined, keep = keep) + settingsPrefs.autoBackupOnChange, + ) { base, selection, combined, keep, onChange -> + base.copy(selection = selection, combined = combined, keep = keep, onChange = onChange) } .flowOn(io) .stateWhileSubscribed( @@ -234,6 +235,13 @@ class CalendarsViewModel @Inject constructor( } } + fun setAutoBackupOnChange(enabled: Boolean) { + viewModelScope.launch { + settingsPrefs.setAutoBackupOnChange(enabled) + reschedule() + } + } + fun setAutoBackupKeep(keep: Int) { viewModelScope.launch { if (settingsPrefs.autoBackupKeep.first() == keep) return@launch @@ -263,12 +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, - ) + BackupScheduler.reconcile(context, settingsPrefs) } private inline fun write(crossinline block: suspend () -> Unit) { @@ -293,6 +296,7 @@ data class AutoBackupUiState( val selection: BackupSelection = BackupSelection(), val combined: Boolean = false, val keep: Int = DEFAULT_BACKUP_KEEP, + val onChange: Boolean = false, ) /** Outcome of a whole-calendar backup, surfaced once to the screen. */ 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 3c7c24cd..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,12 +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, - ) + 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/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index 51178f8d..0f435bcc 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -995,6 +995,8 @@ Interval Every %1$s Minimum 30 minutes. + Also back up after changes + Updates the undated copy a few minutes after events change. Dated backups stay on the interval. Calendars %d calendar diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeRunPolicyTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeRunPolicyTest.kt new file mode 100644 index 00000000..523608c7 --- /dev/null +++ b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeRunPolicyTest.kt @@ -0,0 +1,30 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.work.ExistingWorkPolicy +import androidx.work.WorkInfo.State.BLOCKED +import androidx.work.WorkInfo.State.CANCELLED +import androidx.work.WorkInfo.State.ENQUEUED +import androidx.work.WorkInfo.State.RUNNING +import androidx.work.WorkInfo.State.SUCCEEDED +import com.google.common.truth.Truth.assertThat +import org.junit.jupiter.api.Test + +class ChangeRunPolicyTest { + + @Test + fun `a run that hasn't started yet covers the change`() { + assertThat(changeRunPolicy(listOf(ENQUEUED))).isNull() + assertThat(changeRunPolicy(listOf(RUNNING, BLOCKED))).isNull() + } + + @Test + fun `a run already going gets the next one queued behind it`() { + assertThat(changeRunPolicy(listOf(RUNNING))).isEqualTo(ExistingWorkPolicy.APPEND_OR_REPLACE) + } + + @Test + fun `with nothing pending a fresh run starts`() { + assertThat(changeRunPolicy(emptyList())).isEqualTo(ExistingWorkPolicy.REPLACE) + assertThat(changeRunPolicy(listOf(SUCCEEDED, CANCELLED))).isEqualTo(ExistingWorkPolicy.REPLACE) + } +} 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 6ad9c967..408a69db 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 { @@ -325,4 +328,78 @@ class BackupPlanTest { assertThat(ledger.latestHeldElsewhere("1")).containsExactly("Work.ics") assertThat(ledger.latestHeldElsewhere("2")).containsExactly("Job.ics") } + + @Test + fun `fingerprints survive storage and drop deleted calendars`() { + val stored = persistBackupFingerprints(mapOf("1" to "ab", COMBINED_SERIES to "cd")) + assertThat(parseBackupFingerprints(stored)).containsExactly("1", "ab", COMBINED_SERIES, "cd") + assertThat(persistBackupFingerprints(emptyMap())).isNull() + assertThat(parseBackupFingerprints(null)).isEmpty() + val next = withFingerprint(mapOf("1" to "ab", "9" to "ef", COMBINED_SERIES to "cd"), "2", "gh", setOf("1", "2")) + assertThat(next).containsExactly("1", "ab", COMBINED_SERIES, "cd", "2", "gh") + } + + @Test + fun `a fingerprint follows the content`() { + val first = "BEGIN:VEVENT\r\nDTSTAMP:20261113T143005Z\r\nSUMMARY:A\r\nEND:VEVENT\r\n" + val later = first.replace("20261113T143005Z", "20261114T090000Z") + assertThat(backupFingerprint(later, "Work.ics")).isEqualTo(backupFingerprint(first, "Work.ics")) + assertThat(backupFingerprint(first.replace("SUMMARY:A", "SUMMARY:B"), "Work.ics")).isNotEqualTo(backupFingerprint(first, "Work.ics")) + assertThat(backupFingerprint(first, "Work.ics")).hasLength(32) + assertThat(backupFingerprint(first, "Job.ics")).isNotEqualTo(backupFingerprint(first, "Work.ics")) + } + + @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, "Work.ics")).isEqualTo(backupFingerprint(early, "Work.ics")) + } + + @Test + fun `a change run refreshes only a changed or missing 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") + 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() + } + + @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 + fun `a change run never writes over a file of the user's`() { + 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"), complete = true)).isFalse() + } + + @Test + fun `backup order doesn't depend on the provider's`() { + fun event(uid: String, reminders: List) = IcsEvent( + uid = uid, summary = uid, start = Instant.fromEpochSeconds(0), end = Instant.fromEpochSeconds(3600), + isAllDay = false, zoneId = "UTC", reminderMinutes = reminders, + ) + val one = listOf(event("b", listOf(15, 10)), event("a", listOf(5))) + val other = listOf(event("a", listOf(5)), event("b", listOf(10, 15))) + assertThat(one.inBackupOrder()).isEqualTo(other.inBackupOrder()) + assertThat(one.inBackupOrder().map { it.uid }).containsExactly("a", "b").inOrder() + } } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 851535ed..4bfdf9ee 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -586,6 +586,30 @@ of the backup keeps its last one. The pre-#411 fixed `calendula-backup.ics` is the combined series' stable copy for the install that wrote it, and an install that already had a folder stays on the combined layout. +**Backing up after a change (#516)** is opt-in. `BackupChangeJob` is a +JobScheduler job with a content 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. A trigger fires +once, so each firing queues a change run (a unique `BackupWorker`, battery not +low, queued behind one already running) and schedules the next watch under the +same id before it finishes, which carries over the changes seen meanwhile. Such +a job can't be persisted; `BackupScheduler.reconcile` re-arms it on every +process start (the boot receivers start one), without replacing a waiting watch. +Runs share the scheduled backup's lock. A change run only rewrites the stable +copies and never retries: the dated files and their retention stay on the +interval, so a day of edits can't rotate the history out. Every run that writes +something is recorded on the status line; the failure notification comes once +per failure streak, as it reaches the threshold, and the next success of any run +clears it. Since the trigger fires for any provider change (reminders, other +calendars, sync bookkeeping), each series' file (events in a fixed order) is +hashed without its `DTSTAMP`s (`auto_backup_fingerprints`, reset with the folder +and kept only while the option is on) and a change run skips the series whose +hash (bound to the copy's name) and stable copy are unchanged, without even +listing the folder when no hash moved; the hash is dropped before a copy is +rewritten. A copy that went missing is restored by the next run that lists the +folder; one a still-loading 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 the master row and is part of `EventExportProjection`; `IcsWriter` marks an all-day series' exclusions `VALUE=DATE`, because RFC 5545 ties `EXDATE`'s value