From b2498d362b86566da72b99e44e51a7917e237c3b Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 03:39:16 +0100 Subject: [PATCH 01/15] feat(#516): back up after changes, refreshing the stable copies --- .../jeanlucmakiola/calendula/CalendulaApp.kt | 1 + .../calendula/data/backup/AutoBackup.kt | 143 ++++++++++++++---- .../calendula/data/prefs/SettingsPrefs.kt | 28 +++- .../calendula/domain/backup/BackupPlan.kt | 52 +++++++ .../calendula/ui/calendars/BackupScreen.kt | 7 + .../ui/calendars/CalendarsViewModel.kt | 14 +- .../ui/onboarding/OnboardingViewModel.kt | 1 + app/src/main/res/values/strings.xml | 2 + .../calendula/domain/backup/BackupPlanTest.kt | 38 +++++ docs/ARCHITECTURE.md | 13 ++ 10 files changed, 266 insertions(+), 33 deletions(-) diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt index 2a5a2b36..8310c571 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt @@ -115,6 +115,7 @@ class CalendulaApp : Application() { enabled = prefs.autoBackupEnabled.first(), intervalMinutes = prefs.autoBackupIntervalMinutes.first(), hasFolder = prefs.autoBackupFolderUri.first() != null, + onChange = prefs.autoBackupOnChange.first(), ) } } 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 02977e18..c9d3e150 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 @@ -7,10 +7,12 @@ import android.app.PendingIntent import android.content.Context import android.net.Uri import android.os.Build +import android.provider.CalendarContract 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 @@ -18,6 +20,7 @@ import androidx.work.OneTimeWorkRequestBuilder import androidx.work.PeriodicWorkRequestBuilder import androidx.work.WorkManager import androidx.work.WorkerParameters +import androidx.work.workDataOf import dagger.hilt.EntryPoint import dagger.hilt.InstallIn import dagger.hilt.android.EntryPointAccessors @@ -26,7 +29,10 @@ 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.backupFingerprint import de.jeanlucmakiola.calendula.domain.backup.backupTargets +import de.jeanlucmakiola.calendula.domain.backup.needsRefresh +import de.jeanlucmakiola.calendula.domain.backup.withFingerprint import de.jeanlucmakiola.calendula.domain.backup.planBackupFiles import de.jeanlucmakiola.calendula.domain.backup.latestHeldElsewhere import de.jeanlucmakiola.calendula.domain.backup.latestLedgerKey @@ -43,6 +49,7 @@ 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 @@ -54,6 +61,14 @@ 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" + + /** 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 + + /** Longest a change run waits on a provider that never goes quiet (a long sync). */ + private const val CHANGE_MAX_WAIT_MINUTES = 15L /** * Reconcile the scheduled work with the current settings: enqueue a unique @@ -61,15 +76,17 @@ object BackupScheduler { * 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. [onChange] also arms the change + * trigger (#516). */ - fun apply(context: Context, enabled: Boolean, intervalMinutes: Long, hasFolder: Boolean) { + 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) return } // WorkManager's own floor is 15 min; the UI floors the user choice at 30. @@ -82,6 +99,11 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) + if (onChange) { + watchChanges(context, ExistingWorkPolicy.KEEP) + } else { + workManager.cancelUniqueWork(WORK_NAME_CHANGES) + } } /** @@ -96,6 +118,27 @@ object BackupScheduler { OneTimeWorkRequestBuilder().build(), ) } + + /** + * 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. + */ + internal fun watchChanges(context: Context, policy: ExistingWorkPolicy) { + val constraints = Constraints.Builder() + .addContentUriTrigger(CalendarContract.CONTENT_URI, true) + .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) + .setTriggerContentMaxDelay(CHANGE_MAX_WAIT_MINUTES, TimeUnit.MINUTES) + .setRequiresBatteryNotLow(true) + .build() + val request = OneTimeWorkRequestBuilder() + .setConstraints(constraints) + .setInputData(workDataOf(KEY_CHANGE_RUN to true)) + .build() + WorkManager.getInstance(context).enqueueUniqueWork(WORK_NAME_CHANGES, policy, request) + } } /** @@ -122,16 +165,28 @@ 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) + return Result.success() + } + + private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { 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. + // The periodic, the immediate and the change run are separate unique + // works; one 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 + // 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()) + runBackup(deps, prefs, folder.toUri(), latestOnly = changeRun) } catch (e: CancellationException) { throw e } catch (e: Exception) { @@ -139,7 +194,7 @@ class BackupWorker( RunOutcome.Failed } } - if (outcome == RunOutcome.NothingSelected) return Result.success() + if (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) { @@ -149,20 +204,25 @@ class BackupWorker( return if (outcome == RunOutcome.Failed) 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 { + /** + * 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 targets = backupTargets(all.filter(selection::selects), combined = prefs.autoBackupCombined.first()) - if (targets.isEmpty()) return RunOutcome.NothingSelected + if (targets.isEmpty()) return RunOutcome.NothingToDo prefs.adoptLegacyBackupFile() val listing = exporter.listFolder(folder) val ledger = prefs.autoBackupLedger.first() + 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() val plans = planBackupFiles( @@ -177,38 +237,51 @@ class BackupWorker( suspend fun record(key: String, files: List) = prefs.updateAutoBackupLedger(folder.toString()) { withLedgerEntry(it, key, files, liveKeys) } var written = 0 + var failed = 0 val landedLatest = mutableSetOf() for (plan in plans) { val target = plan.target - val bytes = try { - IcsWriter() - .writeCalendar(repository.exportEvents(target.calendarIds), stamp, target.calendarName) - .toByteArray(Charsets.UTF_8) + 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)) } catch (e: CancellationException) { throw e } catch (e: Exception) { Log.w(TAG, "Reading one series failed", e) + failed++ + continue + } + if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, existing)) { + landedLatest += target.key 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) + 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: 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. + // 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() @@ -219,11 +292,17 @@ class BackupWorker( withLedgerEntry(it, latestKey, stale + pending + current, liveKeys) } recordLatest(plan.staleLatest) - if (landed == latest) landedLatest += target.key + 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++ } } } @@ -236,9 +315,10 @@ class BackupWorker( } } } - 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 } } @@ -283,5 +363,8 @@ 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/data/prefs/SettingsPrefs.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt index eaeb8cf5..35ba184e 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.ui.agenda.AgendaRange import de.jeanlucmakiola.calendula.ui.agenda.parseAgendaRange @@ -196,6 +199,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 } @@ -355,7 +360,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 } } @@ -369,6 +377,17 @@ class SettingsPrefs @Inject constructor( suspend fun setAutoBackupKeep(keep: Int) = prefs.set(SettingsKeys.autoBackupKeep, keep) + 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 @@ -786,6 +805,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 cb1085a5..e862872a 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 @@ -3,6 +3,7 @@ package de.jeanlucmakiola.calendula.domain.backup import de.jeanlucmakiola.calendula.domain.CalendarSource 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 @@ -277,3 +278,54 @@ 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 [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) } + +/** [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 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, or the copy is + * missing or mid-rename. Never when the name belongs to a file of the user's. + */ +fun BackupFilePlan.needsRefresh( + fingerprint: String, + stored: BackupFingerprints, + existing: Set, +): Boolean { + val latest = latestName ?: return false + return stored[target.key] != fingerprint || latest !in existing || + staleLatest.isNotEmpty() || handOff.isNotEmpty() +} 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 4dd5401a..46d99577 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 @@ -351,6 +351,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..26720517 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 @@ -268,6 +276,7 @@ class CalendarsViewModel @Inject constructor( enabled = settingsPrefs.autoBackupEnabled.first(), intervalMinutes = settingsPrefs.autoBackupIntervalMinutes.first(), hasFolder = settingsPrefs.autoBackupFolderUri.first() != null, + onChange = settingsPrefs.autoBackupOnChange.first(), ) } @@ -293,6 +302,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..cee0856c 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 @@ -345,6 +345,7 @@ class OnboardingViewModel @Inject constructor( enabled = true, intervalMinutes = prefs.autoBackupIntervalMinutes.first(), hasFolder = true, + onChange = prefs.autoBackupOnChange.first(), ) // Immediate feedback: the first backup lands while onboarding runs. BackupScheduler.runNow(context) diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index 791612c5..8dbd4fe9 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -920,6 +920,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/domain/backup/BackupPlanTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/domain/backup/BackupPlanTest.kt index ee9be52e..bf878d78 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 @@ -284,4 +284,42 @@ 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`() { + assertThat(backupFingerprint("a")).isEqualTo(backupFingerprint("a")) + assertThat(backupFingerprint("a")).isNotEqualTo(backupFingerprint("b")) + assertThat(backupFingerprint("a")).hasLength(32) + } + + @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() + } + + @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"))).isFalse() + } } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9c649bac..b42e9bf0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -485,6 +485,19 @@ 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. `BackupScheduler.watchChanges` +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. + **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 From f18ae694a7229fff923c67d2fe938dfbc98be665 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 03:47:47 +0100 Subject: [PATCH 02/15] 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 From 93b795ed72fd75418cd94f54a5d66569f15c87f1 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 04:01:14 +0100 Subject: [PATCH 03/15] 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 From dca98bbb2d921add7570a67cd28cd5fca73e4b6f Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 04:09:05 +0100 Subject: [PATCH 04/15] fix(#516): review round 3 - change runs stay off the status, unlisted copies don't retire the old layout, stable export order for the hash --- .../calendula/data/backup/AutoBackup.kt | 32 +++++++++---------- .../calendula/data/prefs/SettingsPrefs.kt | 9 ++++++ .../calendula/domain/backup/BackupPlan.kt | 15 +++++++-- .../calendula/domain/backup/BackupPlanTest.kt | 13 +++++++- docs/ARCHITECTURE.md | 4 +-- 5 files changed, 51 insertions(+), 22 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 5589f480..5a5188d5 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 @@ -32,6 +32,7 @@ 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.inBackupOrder import de.jeanlucmakiola.calendula.domain.backup.needsRefresh import de.jeanlucmakiola.calendula.domain.backup.withFingerprint import de.jeanlucmakiola.calendula.domain.backup.planBackupFiles @@ -185,9 +186,9 @@ class BackupWorker( prefs.autoBackupFolderUri.first() != null if (wanted) BackupScheduler.watchChanges(applicationContext, slot = 1 - slot) } + runCatching { watchNext() }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } // Never fails or retries: a retry would only wait for another change. try { - watchNext() backUp(deps, prefs, changeRun = true) } catch (e: CancellationException) { throw e @@ -201,8 +202,8 @@ class BackupWorker( /** * One run under the shared lock. A change run (#516) refreshes only the - * stable copies; it reports a failure, but a success stays off the status - * line, which dates the last dated backup. + * stable copies and stays off the status line and the failure count, which + * report on the scheduled backup; a broken folder fails that one too. */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { val now = System.currentTimeMillis() @@ -223,9 +224,8 @@ class BackupWorker( RunOutcome.Failed } } - if (outcome == RunOutcome.NothingToDo) return Result.success() + if (changeRun || 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) @@ -239,7 +239,8 @@ class BackupWorker( /** * 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. + * schedule and rewrites only the stable copies whose calendars changed; + * its outcome isn't reported. */ private suspend fun runBackup(deps: Deps, prefs: SettingsPrefs, folder: Uri, latestOnly: Boolean): RunOutcome { val repository = deps.repository() @@ -307,9 +308,7 @@ class BackupWorker( } 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 } - } + runCatching { prefs.dropAutoBackupFingerprint(folder.toString(), plan.target.key) } false } @@ -320,7 +319,8 @@ class BackupWorker( val target = plan.target if (latestOnly && plan.latestName == null) continue val text = try { - IcsWriter().writeCalendar(repository.exportEvents(target.calendarIds), stamp, target.calendarName) + val events = repository.exportEvents(target.calendarIds).inBackupOrder() + IcsWriter().writeCalendar(events, stamp, target.calendarName) } catch (e: CancellationException) { throw e } catch (e: Exception) { @@ -330,18 +330,18 @@ class BackupWorker( } val fingerprint = backupFingerprint(text) if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listing.files.keys, listing.complete)) { - landedLatest += target.key + if (plan.latestName in listing.files) 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) { - val dated = latestOnly || writeDated(plan, bytes) - // 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++ + if (!latestOnly) { + if (writeDated(plan, bytes)) written++ else failed++ + } + // Best-effort in a full run: it never holds up the run's status. + if (plan.latestName != null && writeLatest(plan, bytes, fingerprint)) landedLatest += target.key } } // A layout switch retires the other layout's copies once every new one is there. 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 e039b9fe..c09bad53 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 @@ -399,6 +399,15 @@ class SettingsPrefs @Inject constructor( } } + /** Forget [key]'s hash (#516), so the next change run rewrites its stable copy. */ + suspend fun dropAutoBackupFingerprint(folder: String, key: String) { + prefs.edit { + if (it[SettingsKeys.autoBackupFolderUri] == folder) { + it[SettingsKeys.autoBackupFingerprints] = it[SettingsKeys.autoBackupFingerprints] - key + } + } + } + /** Record a pre-#411 install's old file as its combined series' stable copy (see [pinBackupLayout]). */ suspend fun adoptLegacyBackupFile() { prefs.edit { if (it.autoBackupLegacyInstall) it.adoptLegacyBackupFile() } 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 fd73b1fd..5bb2f9b7 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,6 +1,7 @@ package de.jeanlucmakiola.calendula.domain.backup import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.ics.IcsEvent import de.jeanlucmakiola.calendula.domain.isNotSynced import de.jeanlucmakiola.floret.android.safeFileName import java.security.MessageDigest @@ -324,8 +325,8 @@ 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, + * 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. */ @@ -337,5 +338,13 @@ fun BackupFilePlan.needsRefresh( ): Boolean { val latest = latestName ?: return false if (latest !in listed) return complete - return stored[target.key] != fingerprint || staleLatest.isNotEmpty() || handOff.isNotEmpty() + return stored[target.key] != fingerprint } + +/** + * The events in a fixed order, reminders sorted, so the same content always + * writes the same file and hashes the same, however the provider returned it. + */ +fun List.inBackupOrder(): List = + sortedWith(compareBy({ it.start }, { it.uid }, { it.overrideAt })) + .map { it.copy(reminderMinutes = it.reminderMinutes.sorted()) } 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 602a24f3..81046f11 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 @@ -330,7 +330,6 @@ class BackupPlanTest { 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 @@ -349,4 +348,16 @@ class BackupPlanTest { 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 3c3be32b..bce7cc14 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -492,8 +492,8 @@ 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 shows -on the status line only when it fails: the dated files and their retention stay on the interval, +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 From 70f72d03db69399ef6e078c9131bb7e74bcb8471 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 04:17:57 +0100 Subject: [PATCH 05/15] fix(#516): review round 4 - hash dropped before a stable copy is rewritten, overrides stay first in the backup order --- .../calendula/data/backup/AutoBackup.kt | 65 ++++++++++--------- .../calendula/data/prefs/SettingsPrefs.kt | 1 - .../calendula/domain/backup/BackupPlan.kt | 8 ++- .../calendula/domain/backup/BackupPlanTest.kt | 2 +- 4 files changed, 42 insertions(+), 34 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 5a5188d5..33970053 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 @@ -20,6 +20,7 @@ import androidx.work.OneTimeWorkRequestBuilder import androidx.work.PeriodicWorkRequestBuilder import androidx.work.WorkManager import androidx.work.WorkerParameters +import androidx.work.await import androidx.work.workDataOf import dagger.hilt.EntryPoint import dagger.hilt.InstallIn @@ -33,17 +34,16 @@ 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.inBackupOrder -import de.jeanlucmakiola.calendula.domain.backup.needsRefresh -import de.jeanlucmakiola.calendula.domain.backup.withFingerprint -import de.jeanlucmakiola.calendula.domain.backup.planBackupFiles import de.jeanlucmakiola.calendula.domain.backup.latestHeldElsewhere 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.NonCancellable -import androidx.work.await import kotlinx.coroutines.flow.first import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.withLock @@ -281,35 +281,38 @@ class BackupWorker( // 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 { + suspend fun writeLatest(plan: BackupFilePlan, bytes: ByteArray, fingerprint: String): Boolean { 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, 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.dropAutoBackupFingerprint(folder.toString(), plan.target.key) } - false + var landed: String? = null + return try { + val latestKey = latestLedgerKey(target.key) + // A write cut short leaves a partial copy that must not pass as current. + if (target.key in fingerprints) prefs.dropAutoBackupFingerprint(folder.toString(), target.key) + 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 = { 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) + landed == latest + } } var written = 0 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 c09bad53..e6d6cba7 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,7 +379,6 @@ class SettingsPrefs @Inject constructor( 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 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 5bb2f9b7..fad63680 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 @@ -2,6 +2,7 @@ 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 @@ -344,7 +345,12 @@ fun BackupFilePlan.needsRefresh( /** * The events in a fixed order, reminders 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 = - sortedWith(compareBy({ it.start }, { it.uid }, { it.overrideAt })) + sortedWith( + compareBy( + { it.overrideOf == null }, { it.start }, { it.uid }, { it.overrideAt }, { it.calendarName }, + ), + ) .map { it.copy(reminderMinutes = it.reminderMinutes.sorted()) } 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 81046f11..44ce2d97 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 @@ -320,7 +320,7 @@ class BackupPlanTest { } @Test - fun `a change run refreshes only a changed, missing or moving stable copy`() { + 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() From 6758b7fada9869eedc0dcf68e0b2e7be31f15cda Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 11:53:08 +0100 Subject: [PATCH 06/15] feat(#516): change runs report on the status line, failure notified once per streak --- .../calendula/data/backup/AutoBackup.kt | 53 ++++++++++++------- docs/ARCHITECTURE.md | 20 +++---- 2 files changed, 46 insertions(+), 27 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 33970053..6cbf620b 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 @@ -201,21 +201,25 @@ class BackupWorker( } /** - * One run under the shared lock. A change run (#516) refreshes only the - * stable copies and stays off the status line and the failure count, which - * report on the scheduled backup; a broken folder fails that one too. + * 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 { val now = System.currentTimeMillis() // The periodic, the immediate and the change runs are separate unique // works; one at a time, or each would overwrite the other's ledger. + // The record is made under the lock too, so each streak reaches the + // threshold in exactly one run. + var failures = 0 val outcome = runLock.withLock { // 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 { + val outcome = try { runBackup(deps, prefs, folder.toUri(), latestOnly = changeRun) } catch (e: CancellationException) { throw e @@ -223,24 +227,29 @@ class BackupWorker( Log.w(TAG, "Automatic backup failed", e) RunOutcome.Failed } + if (outcome != RunOutcome.NothingToDo) { + prefs.recordAutoBackupRun(success = outcome == RunOutcome.Written, atMillis = now) + failures = prefs.autoBackupStatus.first().consecutiveFailures + } + outcome } - 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) { - notifyFailure(applicationContext) + when { + outcome == RunOutcome.Written -> clearFailureNotification(applicationContext) + failures == FAILURE_NOTIFY_THRESHOLD -> notifyFailure(applicationContext) } // 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, NothingToDo } + /** A stable copy's write: whether it [landed] under its own name, or [failed] before it was written. */ + private data class LatestWrite(val landed: Boolean, val failed: Boolean) + /** * 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; - * its outcome isn't reported. + * 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() @@ -279,9 +288,9 @@ class BackupWorker( 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 { + // 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): LatestWrite { val target = plan.target val latest = checkNotNull(plan.latestName) var landed: String? = null @@ -308,10 +317,10 @@ class BackupWorker( recordLatest(plan.staleLatest, fingerprint.takeIf { landed == latest }) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) - landed == latest + LatestWrite(landed = landed == latest, failed = false) } catch (e: Exception) { Log.w(TAG, "Stable copy of one series failed", e) - landed == latest + LatestWrite(landed = landed == latest, failed = landed == null) } } @@ -344,7 +353,11 @@ class BackupWorker( if (writeDated(plan, bytes)) written++ else failed++ } // Best-effort in a full run: it never holds up the run's status. - if (plan.latestName != null && writeLatest(plan, bytes, fingerprint)) landedLatest += target.key + val latest = plan.latestName?.let { writeLatest(plan, bytes, fingerprint) } + if (latest?.landed == true) landedLatest += target.key + if (latestOnly && latest != null) { + if (latest.failed) failed++ else written++ + } } } // A layout switch retires the other layout's copies once every new one is there. @@ -364,6 +377,10 @@ class BackupWorker( } } + 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/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bce7cc14..055b2c91 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -492,15 +492,17 @@ 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, -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 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. +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 a change run +skips the series whose hash and stable copy are unchanged; the hash is dropped +before a copy is rewritten. 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 the master row and is part of `EventExportProjection`; `IcsWriter` marks an From 34cd75e9a34a9743cae60123e305eab11a6b896e Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:03:23 +0100 Subject: [PATCH 07/15] fix(#516): review round 5 - hash bound to the copy's name, folder untouched when nothing moved, re-arm under the reconcile lock --- .../calendula/data/backup/AutoBackup.kt | 97 +++++++++++-------- .../calendula/domain/backup/BackupPlan.kt | 20 +++- .../calendula/domain/backup/BackupPlanTest.kt | 9 +- docs/ARCHITECTURE.md | 8 +- 4 files changed, 83 insertions(+), 51 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 6cbf620b..104b66ab 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 @@ -31,10 +31,12 @@ 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.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 @@ -106,7 +108,7 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) - if (!prefs.autoBackupOnChange.first()) { + if (!watchWanted(prefs)) { cancelWatch() return@withLock } @@ -117,6 +119,14 @@ object BackupScheduler { } } + /** Arm [slot] for a running change run, under the same lock as [reconcile] so it can't outlast a switch-off. */ + internal suspend fun watchNext(context: Context, prefs: SettingsPrefs, slot: Int) = withContext(NonCancellable) { + reconcileLock.withLock { if (watchWanted(prefs)) watchChanges(context, slot) } + } + + private suspend fun watchWanted(prefs: SettingsPrefs): Boolean = + prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && prefs.autoBackupOnChange.first() + /** * Run one export immediately (e.g. right after enabling or changing the * folder) for instant feedback. Unique + REPLACE so rapid taps coalesce into @@ -181,11 +191,7 @@ class BackupWorker( val prefs = deps.settingsPrefs() 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) - } + suspend fun watchNext() = BackupScheduler.watchNext(applicationContext, prefs, slot = 1 - slot) runCatching { watchNext() }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } // Never fails or retries: a retry would only wait for another change. try { @@ -195,7 +201,7 @@ class BackupWorker( } catch (e: Exception) { Log.w(TAG, "Backup after a change failed", e) } finally { - withContext(NonCancellable) { runCatching { watchNext() } } + runCatching { watchNext() } } return Result.success() } @@ -208,10 +214,7 @@ class BackupWorker( */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { val now = System.currentTimeMillis() - // The periodic, the immediate and the change runs are separate unique - // works; one at a time, or each would overwrite the other's ledger. - // The record is made under the lock too, so each streak reaches the - // threshold in exactly one run. + // One run at a time, or each would overwrite the other's ledger. var failures = 0 val outcome = runLock.withLock { // Respect the toggles even for already-queued work, so a lingering @@ -228,8 +231,10 @@ class BackupWorker( RunOutcome.Failed } if (outcome != RunOutcome.NothingToDo) { - prefs.recordAutoBackupRun(success = outcome == RunOutcome.Written, atMillis = now) - failures = prefs.autoBackupStatus.first().consecutiveFailures + withContext(NonCancellable) { + prefs.recordAutoBackupRun(success = outcome == RunOutcome.Written, atMillis = now) + failures = prefs.autoBackupStatus.first().consecutiveFailures + } } outcome } @@ -243,8 +248,8 @@ class BackupWorker( private enum class RunOutcome { Written, PartlyFailed, Failed, NothingToDo } - /** A stable copy's write: whether it [landed] under its own name, or [failed] before it was written. */ - private data class LatestWrite(val landed: Boolean, val failed: Boolean) + /** 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 @@ -259,10 +264,31 @@ class BackupWorker( val selection = prefs.autoBackupSelection.first() val targets = backupTargets(all.filter(selection::selects), combined = prefs.autoBackupCombined.first()) 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)) + // A change run reads first and leaves the folder alone when nothing moved. + val texts = HashMap() + if (latestOnly) { + targets.forEach { texts[it.key] = export(it) } + val unchanged = targets.all { target -> + texts[target.key]?.let { fingerprintOf(target, it) }.let { it != null && it == fingerprints[target.key] } + } + if (unchanged) return RunOutcome.NothingToDo + } prefs.adoptLegacyBackupFile() val listing = exporter.listFolder(folder) val ledger = prefs.autoBackupLedger.first() - 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() val plans = planBackupFiles( @@ -272,7 +298,6 @@ 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) } @@ -288,15 +313,13 @@ class BackupWorker( false } - // An old copy goes only once the new one has landed, so a series is - // never left without one. + // 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 latest = checkNotNull(plan.latestName) var landed: String? = null return try { val latestKey = latestLedgerKey(target.key) - // A write cut short leaves a partial copy that must not pass as current. if (target.key in fingerprints) prefs.dropAutoBackupFingerprint(folder.toString(), target.key) landed = exporter.writeToFolder(folder, listing, latest, bytes) // A provider that renamed it leaves a copy to clean up next @@ -317,10 +340,14 @@ class BackupWorker( recordLatest(plan.staleLatest, fingerprint.takeIf { landed == latest }) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) - LatestWrite(landed = landed == latest, failed = false) + if (landed == latest) LatestWrite.Landed else LatestWrite.Renamed } catch (e: Exception) { Log.w(TAG, "Stable copy of one series failed", e) - LatestWrite(landed = landed == latest, failed = landed == null) + when (landed) { + null -> LatestWrite.Failed + latest -> LatestWrite.Landed + else -> LatestWrite.Renamed + } } } @@ -330,34 +357,24 @@ class BackupWorker( for (plan in plans) { val target = plan.target if (latestOnly && plan.latestName == null) continue - val text = 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) + val text = (if (target.key in texts) texts.remove(target.key) else export(target)) ?: run { failed++ continue } - val fingerprint = backupFingerprint(text) + val fingerprint = fingerprintOf(target, text) if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listing.files.keys, listing.complete)) { if (plan.latestName in listing.files) 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. + // Not cancellable once a file exists: it must reach the ledger. withContext(NonCancellable) { - if (!latestOnly) { - if (writeDated(plan, bytes)) written++ else failed++ - } - // Best-effort in a full run: it never holds up the run's status. + val dated = if (latestOnly) null else writeDated(plan, bytes) val latest = plan.latestName?.let { writeLatest(plan, bytes, fingerprint) } - if (latest?.landed == true) landedLatest += target.key - if (latestOnly && latest != null) { - if (latest.failed) failed++ else written++ - } + 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. 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 fad63680..f3512582 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 @@ -287,9 +287,15 @@ fun normalizeBackupKeep(stored: Int): Int = */ typealias BackupFingerprints = Map -/** Hash of a series' file, leaving out the run's `DTSTAMP`s so equal events give an equal hash. */ -fun backupFingerprint(ics: String): String { +/** + * 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)) @@ -343,7 +349,7 @@ fun BackupFilePlan.needsRefresh( } /** - * The events in a fixed order, reminders sorted, so the same content always + * 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. */ @@ -353,4 +359,10 @@ fun List.inBackupOrder(): List = { it.overrideOf == null }, { it.start }, { it.uid }, { it.overrideAt }, { it.calendarName }, ), ) - .map { it.copy(reminderMinutes = it.reminderMinutes.sorted()) } + .map { + it.copy( + reminderMinutes = it.reminderMinutes.sorted(), + exDates = it.exDates.sorted(), + recurrenceDates = it.recurrenceDates.sorted(), + ) + } 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 44ce2d97..f9350169 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 @@ -302,9 +302,10 @@ class BackupPlanTest { 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)).isEqualTo(backupFingerprint(first)) - assertThat(backupFingerprint(first.replace("SUMMARY:A", "SUMMARY:B"))).isNotEqualTo(backupFingerprint(first)) - assertThat(backupFingerprint(first)).hasLength(32) + 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 @@ -316,7 +317,7 @@ class BackupPlanTest { 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)) + assertThat(backupFingerprint(late, "Work.ics")).isEqualTo(backupFingerprint(early, "Work.ics")) } @Test diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 055b2c91..99698d00 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -500,9 +500,11 @@ 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 a change run -skips the series whose hash and stable copy are unchanged; the hash is dropped -before a copy is rewritten. 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. +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 meanwhile, one 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 the master row and is part of `EventExportProjection`; `IcsWriter` marks an From fb178a779e82a2084b14142f2544b26bc54e31cc Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:11:19 +0100 Subject: [PATCH 08/15] fix(#516): review round 6 - early exit holds for blocked and renamed copies, only changed texts kept, run time taken under the lock --- .../calendula/data/backup/AutoBackup.kt | 45 ++++++++++++++----- .../calendula/data/prefs/SettingsPrefs.kt | 6 +-- .../calendula/domain/backup/BackupPlan.kt | 1 + docs/ARCHITECTURE.md | 6 +-- 4 files changed, 40 insertions(+), 18 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 104b66ab..2a0d26dc 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 @@ -213,10 +213,10 @@ class BackupWorker( * [FAILURE_NOTIFY_THRESHOLD], and goes with the next success of any run. */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { - val now = System.currentTimeMillis() // One run at a time, or each would overwrite the other's ledger. var failures = 0 val outcome = runLock.withLock { + 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() @@ -278,13 +278,20 @@ class BackupWorker( fun fingerprintOf(target: BackupTarget, text: String) = backupFingerprint(text, latestFileName(target.baseName)) // A change run reads first and leaves the folder alone when nothing moved. - val texts = HashMap() + // It keeps the text of a changed (or unreadable, null) series only. + val unchangedHashes = HashMap() + val changedTexts = HashMap() if (latestOnly) { - targets.forEach { texts[it.key] = export(it) } - val unchanged = targets.all { target -> - texts[target.key]?.let { fingerprintOf(target, it) }.let { it != null && it == fingerprints[target.key] } + for (target in targets) { + val text = export(target) + val hash = text?.let { fingerprintOf(target, it) } + if (hash != null && hash == fingerprints[target.key]) { + unchangedHashes[target.key] = hash + } else { + changedTexts[target.key] = text + } } - if (unchanged) return RunOutcome.NothingToDo + if (changedTexts.isEmpty()) return RunOutcome.NothingToDo } prefs.adoptLegacyBackupFile() val listing = exporter.listFolder(folder) @@ -320,7 +327,7 @@ class BackupWorker( var landed: String? = null return try { val latestKey = latestLedgerKey(target.key) - if (target.key in fingerprints) prefs.dropAutoBackupFingerprint(folder.toString(), target.key) + if (target.key in fingerprints) prefs.updateAutoBackupFingerprints(folder.toString()) { it - target.key } 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. @@ -337,7 +344,7 @@ class BackupWorker( val pending = plan.handOff - it.latestHeldElsewhere(target.key) withLedgerEntry(it, latestKey, stale + pending + current, liveKeys) } - recordLatest(plan.staleLatest, fingerprint.takeIf { landed == latest }) + recordLatest(plan.staleLatest, fingerprint) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) if (landed == latest) LatestWrite.Landed else LatestWrite.Renamed @@ -356,17 +363,31 @@ class BackupWorker( val landedLatest = mutableSetOf() for (plan in plans) { val target = plan.target - if (latestOnly && plan.latestName == null) continue - val text = (if (target.key in texts) texts.remove(target.key) else export(target)) ?: run { + var text: String? = null + val fingerprint = unchangedHashes[target.key] ?: run { + text = (if (target.key in changedTexts) changedTexts.remove(target.key) else export(target)) + text?.let { fingerprintOf(target, it) } + } ?: run { failed++ continue } - val fingerprint = fingerprintOf(target, text) + if (plan.latestName == null) { + // Nothing to refresh until the content moves, so a later change run can stop early. + if (fingerprints[target.key] != fingerprint) { + prefs.updateAutoBackupFingerprints(folder.toString()) { + withFingerprint(it, target.key, fingerprint, liveKeys) + } + } + if (latestOnly) continue + } if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listing.files.keys, listing.complete)) { if (plan.latestName in listing.files) landedLatest += target.key continue } - val bytes = text.toByteArray(Charsets.UTF_8) + val bytes = (text ?: export(target) ?: run { + failed++ + continue + }).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) 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 e6d6cba7..3101b74e 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 @@ -398,11 +398,11 @@ class SettingsPrefs @Inject constructor( } } - /** Forget [key]'s hash (#516), so the next change run rewrites its stable copy. */ - suspend fun dropAutoBackupFingerprint(folder: String, key: String) { + /** 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] = it[SettingsKeys.autoBackupFingerprints] - key + it[SettingsKeys.autoBackupFingerprints] = transform(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 f3512582..1b536785 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 @@ -357,6 +357,7 @@ fun List.inBackupOrder(): List = sortedWith( compareBy( { it.overrideOf == null }, { it.start }, { it.uid }, { it.overrideAt }, { it.calendarName }, + { it.end }, { it.summary }, { it.description }, { it.location }, ), ) .map { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 99698d00..b8e5577a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -502,9 +502,9 @@ bookkeeping), each series' file (events in a fixed order) is hashed without its `DTSTAMP`s (`auto_backup_fingerprints`, reset with the folder) 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 meanwhile, one a -still-loading folder listing doesn't show, or one edited in place outside the -app, is left to the next scheduled run. +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 From 09c20ee90f66dfe2227e27d65ef44955e2eb37d1 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:19:24 +0100 Subject: [PATCH 09/15] fix(#516): review round 7 - re-arm queues behind a running slot, hashes only while the option is on, one series in memory at a time --- .../calendula/data/backup/AutoBackup.kt | 96 ++++++++++--------- .../calendula/data/prefs/SettingsPrefs.kt | 6 +- .../calendula/domain/backup/BackupPlan.kt | 2 +- docs/ARCHITECTURE.md | 6 +- 4 files changed, 61 insertions(+), 49 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 2a0d26dc..c529e15a 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 @@ -18,6 +18,7 @@ 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 @@ -146,11 +147,12 @@ object BackupScheduler { * 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, so while two - * change runs overlap nothing watches until the second one ends. + * changes made during the run, and again as it ends. A slot already + * waiting is kept; one still running gets the new watch queued behind it, + * so the watch can't be lost to a run that is just finishing. While two + * change runs overlap, nothing watches until the first one ends. */ - internal fun watchChanges(context: Context, slot: Int) { + internal suspend fun watchChanges(context: Context, slot: Int) { val constraints = Constraints.Builder() .addContentUriTrigger(CalendarContract.CONTENT_URI, true) .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) @@ -161,7 +163,15 @@ object BackupScheduler { .setConstraints(constraints) .setInputData(workDataOf(KEY_CHANGE_SLOT to slot)) .build() - WorkManager.getInstance(context).enqueueUniqueWork(CHANGE_SLOTS[slot], ExistingWorkPolicy.KEEP, request) + val workManager = WorkManager.getInstance(context) + val pending = workManager.getWorkInfosForUniqueWorkFlow(CHANGE_SLOTS[slot]).first() + .filterNot { it.state.isFinished } + val policy = if (pending.isNotEmpty() && pending.all { it.state == WorkInfo.State.RUNNING }) { + ExistingWorkPolicy.APPEND_OR_REPLACE + } else { + ExistingWorkPolicy.KEEP + } + workManager.enqueueUniqueWork(CHANGE_SLOTS[slot], policy, request) } } @@ -277,21 +287,17 @@ class BackupWorker( } fun fingerprintOf(target: BackupTarget, text: String) = backupFingerprint(text, latestFileName(target.baseName)) - // A change run reads first and leaves the folder alone when nothing moved. - // It keeps the text of a changed (or unreadable, null) series only. - val unchangedHashes = HashMap() - val changedTexts = HashMap() - if (latestOnly) { - for (target in targets) { - val text = export(target) - val hash = text?.let { fingerprintOf(target, it) } - if (hash != null && hash == fingerprints[target.key]) { - unchangedHashes[target.key] = hash - } else { - changedTexts[target.key] = text - } - } - if (changedTexts.isEmpty()) return RunOutcome.NothingToDo + // Hashes only serve change runs; without them a stale one could pass later. + val trackHashes = latestOnly || 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 } prefs.adoptLegacyBackupFile() val listing = exporter.listFolder(folder) @@ -327,7 +333,9 @@ class BackupWorker( var landed: String? = null return try { val latestKey = latestLedgerKey(target.key) - if (target.key in fingerprints) prefs.updateAutoBackupFingerprints(folder.toString()) { it - target.key } + if (trackHashes && target.key in fingerprints) { + prefs.updateAutoBackupFingerprints(folder.toString()) { it - target.key } + } 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. @@ -337,14 +345,14 @@ class BackupWorker( suspend fun recordLatest(stale: List, landedFingerprint: String? = null) = prefs.updateAutoBackupLedger( folder.toString(), - fingerprints = { old -> - landedFingerprint?.let { withFingerprint(old, target.key, it, liveKeys) } ?: old + 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, fingerprint) + recordLatest(plan.staleLatest, fingerprint.takeIf { trackHashes }) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) if (landed == latest) LatestWrite.Landed else LatestWrite.Renamed @@ -363,31 +371,31 @@ class BackupWorker( val landedLatest = mutableSetOf() for (plan in plans) { val target = plan.target - var text: String? = null - val fingerprint = unchangedHashes[target.key] ?: run { - text = (if (target.key in changedTexts) changedTexts.remove(target.key) else export(target)) - text?.let { fingerprintOf(target, it) } - } ?: run { - failed++ - continue - } - if (plan.latestName == null) { - // Nothing to refresh until the content moves, so a later change run can stop early. - if (fingerprints[target.key] != fingerprint) { - prefs.updateAutoBackupFingerprints(folder.toString()) { - withFingerprint(it, target.key, fingerprint, liveKeys) - } + // A copy blocked by a file of the user's keeps its hash, so a later change run can stop early. + suspend fun rememberBlocked(hash: String) { + if (plan.latestName == null && trackHashes && fingerprints[target.key] != hash) { + prefs.updateAutoBackupFingerprints(folder.toString()) { withFingerprint(it, target.key, hash, liveKeys) } } - if (latestOnly) continue } - if (latestOnly && !plan.needsRefresh(fingerprint, fingerprints, listing.files.keys, listing.complete)) { - if (plan.latestName in listing.files) landedLatest += target.key - continue + if (latestOnly) { + val hash = preHashes[target.key] ?: run { + failed++ + continue + } + rememberBlocked(hash) + if (!plan.needsRefresh(hash, fingerprints, listing.files.keys, listing.complete)) { + if (plan.latestName in listing.files) landedLatest += target.key + continue + } } - val bytes = (text ?: export(target) ?: run { + // Read again rather than held since the pre-pass: one series' text in memory at a time. + val text = export(target) ?: run { failed++ continue - }).toByteArray(Charsets.UTF_8) + } + val fingerprint = fingerprintOf(target, text) + rememberBlocked(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) 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 3101b74e..74b0bce4 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 @@ -387,13 +387,15 @@ class SettingsPrefs @Inject constructor( */ suspend fun updateAutoBackupLedger( folder: String, - fingerprints: (BackupFingerprints) -> BackupFingerprints = { it }, + fingerprints: ((BackupFingerprints) -> BackupFingerprints)? = null, transform: (BackupLedger) -> BackupLedger, ) { prefs.edit { if (it[SettingsKeys.autoBackupFolderUri] == folder) { it[SettingsKeys.autoBackupLedger] = transform(it[SettingsKeys.autoBackupLedger]) - it[SettingsKeys.autoBackupFingerprints] = fingerprints(it[SettingsKeys.autoBackupFingerprints]) + if (fingerprints != null) { + 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 1b536785..76a6f269 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 @@ -357,7 +357,7 @@ fun List.inBackupOrder(): List = sortedWith( compareBy( { it.overrideOf == null }, { it.start }, { it.uid }, { it.overrideAt }, { it.calendarName }, - { it.end }, { it.summary }, { it.description }, { it.location }, + { it.toString() }, ), ) .map { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b8e5577a..7070d602 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -491,7 +491,8 @@ 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 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 +(catching changes made during the run) and again as it ends, queued behind +that slot's run if it is still running. 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 @@ -499,7 +500,8 @@ 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 a change run +`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 From 783916e3a77046c729567b5171c85aca9a2d2fe9 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:31:41 +0100 Subject: [PATCH 10/15] fix(#516): review round 8 - one watch stays armed after runs fire together, notification decided under the lock, lists sorted before ordering --- .../calendula/data/backup/AutoBackup.kt | 114 ++++++++++++------ .../calendula/domain/backup/BackupPlan.kt | 15 ++- .../calendula/data/backup/ChangeArmTest.kt | 32 +++++ docs/ARCHITECTURE.md | 5 +- 4 files changed, 116 insertions(+), 50 deletions(-) create mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt 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 c529e15a..b6aa2100 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 @@ -109,21 +109,33 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) - if (!watchWanted(prefs)) { + 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) + val watching = CHANGE_SLOTS.indices.any { slot -> slotStates(workManager, slot).any { !it.isFinished } } + if (!watching) watchChanges(context, slot = 0, ChangeArm.Enqueue) } } - /** Arm [slot] for a running change run, under the same lock as [reconcile] so it can't outlast a switch-off. */ - internal suspend fun watchNext(context: Context, prefs: SettingsPrefs, slot: Int) = withContext(NonCancellable) { - reconcileLock.withLock { if (watchWanted(prefs)) watchChanges(context, slot) } - } + /** + * Arm the slot after the change run in [self] as it starts or ends (see + * [changeArm]), under the same lock as [reconcile] so it can't outlast a + * switch-off. + */ + internal suspend fun watchNext(context: Context, prefs: SettingsPrefs, self: Int, atStart: Boolean) = + withContext(NonCancellable) { + reconcileLock.withLock { + if (!watchWanted(prefs)) return@withLock + val workManager = WorkManager.getInstance(context) + val other = 1 - self + changeArm(self, slotStates(workManager, self), slotStates(workManager, other), atStart) + ?.let { watchChanges(context, other, it) } + } + } + + private suspend fun slotStates(workManager: WorkManager, slot: Int): List = + workManager.getWorkInfosForUniqueWorkFlow(CHANGE_SLOTS[slot]).first().map { it.state } private suspend fun watchWanted(prefs: SettingsPrefs): Boolean = prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && prefs.autoBackupOnChange.first() @@ -146,13 +158,10 @@ object BackupScheduler { * 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. A slot already - * waiting is kept; one still running gets the new watch queued behind it, - * so the watch can't be lost to a run that is just finishing. While two - * change runs overlap, nothing watches until the first one ends. + * job waits, so each change run arms the other slot ([watchNext]); [arm] + * says whether the request is queued behind that slot's running run. */ - internal suspend fun watchChanges(context: Context, slot: Int) { + private fun watchChanges(context: Context, slot: Int, arm: ChangeArm) { val constraints = Constraints.Builder() .addContentUriTrigger(CalendarContract.CONTENT_URI, true) .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) @@ -163,15 +172,37 @@ object BackupScheduler { .setConstraints(constraints) .setInputData(workDataOf(KEY_CHANGE_SLOT to slot)) .build() - val workManager = WorkManager.getInstance(context) - val pending = workManager.getWorkInfosForUniqueWorkFlow(CHANGE_SLOTS[slot]).first() - .filterNot { it.state.isFinished } - val policy = if (pending.isNotEmpty() && pending.all { it.state == WorkInfo.State.RUNNING }) { - ExistingWorkPolicy.APPEND_OR_REPLACE - } else { - ExistingWorkPolicy.KEEP + val policy = when (arm) { + ChangeArm.Enqueue -> ExistingWorkPolicy.KEEP + ChangeArm.Append -> ExistingWorkPolicy.APPEND_OR_REPLACE } - workManager.enqueueUniqueWork(CHANGE_SLOTS[slot], policy, request) + WorkManager.getInstance(context).enqueueUniqueWork(CHANGE_SLOTS[slot], policy, request) + } +} + +internal enum class ChangeArm { Enqueue, Append } + +/** + * How the change run in slot [self] arms the other slot (#516), given both + * slots' work states, so exactly one watch stays armed. At the start it arms + * only an idle slot, catching changes made during the run. At the end nothing + * is armed when a watch is already queued behind this run or waits in the + * other slot; a run still going in the other slot gets the watch queued behind + * it, by slot 0 only, so two runs that fired together leave one watch. + */ +internal fun changeArm( + self: Int, + own: List, + other: List, + atStart: Boolean, +): ChangeArm? { + val otherBusy = other.filterNot { it.isFinished } + return when { + otherBusy.isEmpty() -> if (atStart || WorkInfo.State.BLOCKED !in own) ChangeArm.Enqueue else null + atStart || WorkInfo.State.BLOCKED in own -> null + otherBusy.any { it != WorkInfo.State.RUNNING } -> null + self == 0 -> ChangeArm.Append + else -> null } } @@ -201,8 +232,10 @@ class BackupWorker( val prefs = deps.settingsPrefs() val slot = inputData.getInt(BackupScheduler.KEY_CHANGE_SLOT, -1) if (slot < 0) return backUp(deps, prefs, changeRun = false) - suspend fun watchNext() = BackupScheduler.watchNext(applicationContext, prefs, slot = 1 - slot) - runCatching { watchNext() }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } + suspend fun watchNext(atStart: Boolean) = runCatching { + BackupScheduler.watchNext(applicationContext, prefs, slot, atStart) + }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } + watchNext(atStart = true) // Never fails or retries: a retry would only wait for another change. try { backUp(deps, prefs, changeRun = true) @@ -211,7 +244,7 @@ class BackupWorker( } catch (e: Exception) { Log.w(TAG, "Backup after a change failed", e) } finally { - runCatching { watchNext() } + watchNext(atStart = false) } return Result.success() } @@ -224,7 +257,6 @@ class BackupWorker( */ private suspend fun backUp(deps: Deps, prefs: SettingsPrefs, changeRun: Boolean): Result { // One run at a time, or each would overwrite the other's ledger. - var failures = 0 val outcome = runLock.withLock { val now = System.currentTimeMillis() // Respect the toggles even for already-queued work, so a lingering @@ -243,15 +275,15 @@ class BackupWorker( if (outcome != RunOutcome.NothingToDo) { withContext(NonCancellable) { prefs.recordAutoBackupRun(success = outcome == RunOutcome.Written, atMillis = now) - failures = prefs.autoBackupStatus.first().consecutiveFailures + when { + outcome == RunOutcome.Written -> clearFailureNotification(applicationContext) + prefs.autoBackupStatus.first().consecutiveFailures == FAILURE_NOTIFY_THRESHOLD -> + notifyFailure(applicationContext) + } } } outcome } - when { - outcome == RunOutcome.Written -> clearFailureNotification(applicationContext) - failures == FAILURE_NOTIFY_THRESHOLD -> notifyFailure(applicationContext) - } // Only a run that wrote nothing retries: a retry rewrites every series. return if (outcome == RunOutcome.Failed && !changeRun) Result.retry() else Result.success() } @@ -366,23 +398,25 @@ class BackupWorker( } } + // 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 - // A copy blocked by a file of the user's keeps its hash, so a later change run can stop early. - suspend fun rememberBlocked(hash: String) { - if (plan.latestName == null && trackHashes && fingerprints[target.key] != hash) { - prefs.updateAutoBackupFingerprints(folder.toString()) { withFingerprint(it, target.key, hash, liveKeys) } - } - } if (latestOnly) { val hash = preHashes[target.key] ?: run { failed++ continue } - rememberBlocked(hash) + rememberBlocked(plan, hash) if (!plan.needsRefresh(hash, fingerprints, listing.files.keys, listing.complete)) { if (plan.latestName in listing.files) landedLatest += target.key continue @@ -394,7 +428,7 @@ class BackupWorker( continue } val fingerprint = fingerprintOf(target, text) - rememberBlocked(fingerprint) + 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) { 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 76a6f269..c180241d 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 @@ -354,16 +354,15 @@ fun BackupFilePlan.needsRefresh( * Standalone occurrences stay first, as [flattenOverrides] puts them. */ fun List.inBackupOrder(): List = - sortedWith( + 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() }, ), ) - .map { - it.copy( - reminderMinutes = it.reminderMinutes.sorted(), - exDates = it.exDates.sorted(), - recurrenceDates = it.recurrenceDates.sorted(), - ) - } diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt new file mode 100644 index 00000000..e9e737a4 --- /dev/null +++ b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt @@ -0,0 +1,32 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.work.WorkInfo.State.BLOCKED +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 ChangeArmTest { + + @Test + fun `a lone run arms the idle slot as it starts and leaves it at the end`() { + assertThat(changeArm(0, listOf(RUNNING), listOf(SUCCEEDED), atStart = true)).isEqualTo(ChangeArm.Enqueue) + assertThat(changeArm(0, listOf(RUNNING), listOf(ENQUEUED), atStart = false)).isNull() + } + + @Test + fun `an idle other slot is armed at the end unless a watch is queued behind this run`() { + assertThat(changeArm(1, listOf(RUNNING), emptyList(), atStart = false)).isEqualTo(ChangeArm.Enqueue) + assertThat(changeArm(1, listOf(RUNNING, BLOCKED), listOf(SUCCEEDED), atStart = false)).isNull() + } + + @Test + fun `two runs that fired together leave one watch`() { + assertThat(changeArm(0, listOf(RUNNING), listOf(RUNNING), atStart = true)).isNull() + assertThat(changeArm(1, listOf(RUNNING), listOf(RUNNING), atStart = true)).isNull() + assertThat(changeArm(0, listOf(RUNNING), listOf(RUNNING), atStart = false)).isEqualTo(ChangeArm.Append) + assertThat(changeArm(1, listOf(RUNNING, BLOCKED), listOf(RUNNING), atStart = false)).isNull() + assertThat(changeArm(1, listOf(RUNNING), listOf(RUNNING), atStart = false)).isNull() + } +} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7070d602..24b24545 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -491,8 +491,9 @@ 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 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, queued behind -that slot's run if it is still running. Runs share the +(catching changes made during the run) or as it ends, queued behind that +slot's run if it is still running; `changeArm` decides, so exactly one watch +stays armed even after two runs fired together. 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 From a902f5f86254b6a5c69201ac84fb0cdf62bf9202 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:42:26 +0100 Subject: [PATCH 11/15] fix(#516): review round 9 - one rule keeps exactly one watch waiting, retired copies lose their hash --- .../calendula/data/backup/AutoBackup.kt | 105 ++++++++++-------- .../calendula/data/backup/ChangeArmTest.kt | 32 ------ .../calendula/data/backup/WatchStepTest.kt | 41 +++++++ docs/ARCHITECTURE.md | 6 +- 4 files changed, 100 insertions(+), 84 deletions(-) delete mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt create mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt 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 b6aa2100..e3d82cbd 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 @@ -90,7 +90,9 @@ object BackupScheduler { 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() } + suspend fun cancelWatch() = CHANGE_SLOTS.indices + .filter { slot -> slotStates(workManager, slot).any { !it.isFinished } } + .forEach { workManager.cancelUniqueWork(CHANGE_SLOTS[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 @@ -113,27 +115,30 @@ object BackupScheduler { cancelWatch() return@withLock } - val watching = CHANGE_SLOTS.indices.any { slot -> slotStates(workManager, slot).any { !it.isFinished } } - if (!watching) watchChanges(context, slot = 0, ChangeArm.Enqueue) + takeWatchStep(context, workManager, self = null) } } /** - * Arm the slot after the change run in [self] as it starts or ends (see - * [changeArm]), under the same lock as [reconcile] so it can't outlast a + * Keep one change watch armed around the change run in [self] (see + * [watchStep]), under the same lock as [reconcile] so it can't outlast a * switch-off. */ - internal suspend fun watchNext(context: Context, prefs: SettingsPrefs, self: Int, atStart: Boolean) = + internal suspend fun watchNext(context: Context, prefs: SettingsPrefs, self: Int) = withContext(NonCancellable) { reconcileLock.withLock { - if (!watchWanted(prefs)) return@withLock - val workManager = WorkManager.getInstance(context) - val other = 1 - self - changeArm(self, slotStates(workManager, self), slotStates(workManager, other), atStart) - ?.let { watchChanges(context, other, it) } + if (watchWanted(prefs)) takeWatchStep(context, WorkManager.getInstance(context), self) } } + private suspend fun takeWatchStep(context: Context, workManager: WorkManager, self: Int?) { + when (val step = watchStep(self, CHANGE_SLOTS.indices.map { slotStates(workManager, it) })) { + WatchStep.None -> Unit + is WatchStep.Cancel -> workManager.cancelUniqueWork(CHANGE_SLOTS[step.slot]).await() + is WatchStep.Arm -> watchChanges(context, step.slot, step.append) + } + } + private suspend fun slotStates(workManager: WorkManager, slot: Int): List = workManager.getWorkInfosForUniqueWorkFlow(CHANGE_SLOTS[slot]).first().map { it.state } @@ -158,10 +163,10 @@ object BackupScheduler { * 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 each change run arms the other slot ([watchNext]); [arm] - * says whether the request is queued behind that slot's running run. + * job waits, so each change run arms the other slot ([watchNext]); [append] + * queues the request behind that slot's running run. */ - private fun watchChanges(context: Context, slot: Int, arm: ChangeArm) { + private fun watchChanges(context: Context, slot: Int, append: Boolean) { val constraints = Constraints.Builder() .addContentUriTrigger(CalendarContract.CONTENT_URI, true) .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) @@ -172,37 +177,38 @@ object BackupScheduler { .setConstraints(constraints) .setInputData(workDataOf(KEY_CHANGE_SLOT to slot)) .build() - val policy = when (arm) { - ChangeArm.Enqueue -> ExistingWorkPolicy.KEEP - ChangeArm.Append -> ExistingWorkPolicy.APPEND_OR_REPLACE - } + val policy = if (append) ExistingWorkPolicy.APPEND_OR_REPLACE else ExistingWorkPolicy.KEEP WorkManager.getInstance(context).enqueueUniqueWork(CHANGE_SLOTS[slot], policy, request) } } -internal enum class ChangeArm { Enqueue, Append } +/** What keeps exactly one change watch armed (#516): nothing, a new watch in [slot], or cancelling the extra one there. */ +internal sealed interface WatchStep { + data object None : WatchStep + + /** [append]: queued behind the run still going in [slot], so it starts watching once that ends. */ + data class Arm(val slot: Int, val append: Boolean) : WatchStep + + data class Cancel(val slot: Int) : WatchStep +} /** - * How the change run in slot [self] arms the other slot (#516), given both - * slots' work states, so exactly one watch stays armed. At the start it arms - * only an idle slot, catching changes made during the run. At the end nothing - * is armed when a watch is already queued behind this run or waits in the - * other slot; a run still going in the other slot gets the watch queued behind - * it, by slot 0 only, so two runs that fired together leave one watch. + * The step that leaves exactly one watch waiting, from both slots' work + * [states], taken by the change run in [self] as it starts and ends, or by + * [BackupScheduler.reconcile] (null). A waiting watch is enough; two are one + * too many. With none, the other slot is armed, queued behind its run if one + * still shows as running, so a run whose end isn't recorded yet can't leave + * the provider unwatched. */ -internal fun changeArm( - self: Int, - own: List, - other: List, - atStart: Boolean, -): ChangeArm? { - val otherBusy = other.filterNot { it.isFinished } +internal fun watchStep(self: Int?, states: List>): WatchStep { + fun waiting(slot: Int) = states[slot].any { it == WorkInfo.State.ENQUEUED || it == WorkInfo.State.BLOCKED } + val keep = self ?: 0 + val other = 1 - keep + val target = if (self == null) keep else other return when { - otherBusy.isEmpty() -> if (atStart || WorkInfo.State.BLOCKED !in own) ChangeArm.Enqueue else null - atStart || WorkInfo.State.BLOCKED in own -> null - otherBusy.any { it != WorkInfo.State.RUNNING } -> null - self == 0 -> ChangeArm.Append - else -> null + waiting(keep) && waiting(other) -> WatchStep.Cancel(other) + waiting(keep) || waiting(other) -> WatchStep.None + else -> WatchStep.Arm(target, append = WorkInfo.State.RUNNING in states[target]) } } @@ -232,10 +238,10 @@ class BackupWorker( val prefs = deps.settingsPrefs() val slot = inputData.getInt(BackupScheduler.KEY_CHANGE_SLOT, -1) if (slot < 0) return backUp(deps, prefs, changeRun = false) - suspend fun watchNext(atStart: Boolean) = runCatching { - BackupScheduler.watchNext(applicationContext, prefs, slot, atStart) + suspend fun watchNext() = runCatching { + BackupScheduler.watchNext(applicationContext, prefs, slot) }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } - watchNext(atStart = true) + watchNext() // Never fails or retries: a retry would only wait for another change. try { backUp(deps, prefs, changeRun = true) @@ -244,7 +250,7 @@ class BackupWorker( } catch (e: Exception) { Log.w(TAG, "Backup after a change failed", e) } finally { - watchNext(atStart = false) + watchNext() } return Result.success() } @@ -320,7 +326,7 @@ class BackupWorker( 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 = latestOnly || prefs.autoBackupOnChange.first() + 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) { @@ -363,7 +369,7 @@ class BackupWorker( val target = plan.target val latest = checkNotNull(plan.latestName) var landed: String? = null - return try { + try { val latestKey = latestLedgerKey(target.key) if (trackHashes && target.key in fingerprints) { prefs.updateAutoBackupFingerprints(folder.toString()) { it - target.key } @@ -387,14 +393,13 @@ class BackupWorker( recordLatest(plan.staleLatest, fingerprint.takeIf { trackHashes }) val staleLeft = exporter.deleteFromFolder(listing, plan.staleLatest) recordLatest(plan.staleLatest.filter { it in staleLeft }) - if (landed == latest) LatestWrite.Landed else LatestWrite.Renamed } catch (e: Exception) { Log.w(TAG, "Stable copy of one series failed", e) - when (landed) { - null -> LatestWrite.Failed - latest -> LatestWrite.Landed - else -> LatestWrite.Renamed - } + } + return when (landed) { + null -> LatestWrite.Failed + latest -> LatestWrite.Landed + else -> LatestWrite.Renamed } } @@ -446,6 +451,8 @@ 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 } } } } diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt deleted file mode 100644 index e9e737a4..00000000 --- a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeArmTest.kt +++ /dev/null @@ -1,32 +0,0 @@ -package de.jeanlucmakiola.calendula.data.backup - -import androidx.work.WorkInfo.State.BLOCKED -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 ChangeArmTest { - - @Test - fun `a lone run arms the idle slot as it starts and leaves it at the end`() { - assertThat(changeArm(0, listOf(RUNNING), listOf(SUCCEEDED), atStart = true)).isEqualTo(ChangeArm.Enqueue) - assertThat(changeArm(0, listOf(RUNNING), listOf(ENQUEUED), atStart = false)).isNull() - } - - @Test - fun `an idle other slot is armed at the end unless a watch is queued behind this run`() { - assertThat(changeArm(1, listOf(RUNNING), emptyList(), atStart = false)).isEqualTo(ChangeArm.Enqueue) - assertThat(changeArm(1, listOf(RUNNING, BLOCKED), listOf(SUCCEEDED), atStart = false)).isNull() - } - - @Test - fun `two runs that fired together leave one watch`() { - assertThat(changeArm(0, listOf(RUNNING), listOf(RUNNING), atStart = true)).isNull() - assertThat(changeArm(1, listOf(RUNNING), listOf(RUNNING), atStart = true)).isNull() - assertThat(changeArm(0, listOf(RUNNING), listOf(RUNNING), atStart = false)).isEqualTo(ChangeArm.Append) - assertThat(changeArm(1, listOf(RUNNING, BLOCKED), listOf(RUNNING), atStart = false)).isNull() - assertThat(changeArm(1, listOf(RUNNING), listOf(RUNNING), atStart = false)).isNull() - } -} diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt new file mode 100644 index 00000000..108b4b0d --- /dev/null +++ b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt @@ -0,0 +1,41 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.work.WorkInfo.State.BLOCKED +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 WatchStepTest { + + @Test + fun `a lone run arms the idle slot and leaves a waiting one`() { + assertThat(watchStep(0, listOf(listOf(RUNNING), listOf(SUCCEEDED)))).isEqualTo(WatchStep.Arm(1, append = false)) + assertThat(watchStep(0, listOf(listOf(RUNNING), listOf(ENQUEUED)))).isEqualTo(WatchStep.None) + } + + @Test + fun `a run that still shows as running gets the watch queued behind it`() { + assertThat(watchStep(1, listOf(listOf(RUNNING), listOf(RUNNING)))).isEqualTo(WatchStep.Arm(0, append = true)) + } + + @Test + fun `runs that fired together end with one watch`() { + val afterFirst = listOf(listOf(RUNNING), listOf(RUNNING, BLOCKED)) + assertThat(watchStep(1, afterFirst)).isEqualTo(WatchStep.None) + assertThat(watchStep(0, afterFirst)).isEqualTo(WatchStep.None) + } + + @Test + fun `a second waiting watch is cancelled`() { + assertThat(watchStep(0, listOf(listOf(ENQUEUED), listOf(ENQUEUED)))).isEqualTo(WatchStep.Cancel(1)) + assertThat(watchStep(null, listOf(listOf(ENQUEUED), listOf(ENQUEUED)))).isEqualTo(WatchStep.Cancel(1)) + } + + @Test + fun `reconcile arms slot 0 only when nothing waits`() { + assertThat(watchStep(null, listOf(emptyList(), emptyList()))).isEqualTo(WatchStep.Arm(0, append = false)) + assertThat(watchStep(null, listOf(emptyList(), listOf(ENQUEUED)))).isEqualTo(WatchStep.None) + } +} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 24b24545..25e2b206 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -491,9 +491,9 @@ 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 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) or as it ends, queued behind that -slot's run if it is still running; `changeArm` decides, so exactly one watch -stays armed even after two runs fired together. Runs share the +(catching changes made during the run) and checks again as it ends; +`watchStep` keeps exactly one watch waiting, queueing a new one behind a run +that still shows as running and cancelling a second one. 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 From ad5f0f46622542ddf2cd016bc250d9733ef79e76 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:53:58 +0100 Subject: [PATCH 12/15] fix(#516): review round 10 - the change watch is one JobScheduler job that re-arms itself, startup reconcile can't crash the app --- app/src/main/AndroidManifest.xml | 5 + .../calendula/data/backup/AutoBackup.kt | 186 ++++++------------ .../calendula/data/backup/BackupChangeJob.kt | 81 ++++++++ .../data/backup/ChangeRunPolicyTest.kt | 30 +++ .../calendula/data/backup/WatchStepTest.kt | 41 ---- docs/ARCHITECTURE.md | 46 ++--- 6 files changed, 203 insertions(+), 186 deletions(-) create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt create mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/ChangeRunPolicyTest.kt delete mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index b272d8e9..175dab02 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -304,6 +304,11 @@ wipe pending alarms, and a clock or timezone change moves every reminder relative to the one that is armed. Exported: the system broadcasts arrive from outside the app. --> + + 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 e3d82cbd..8b1e9d93 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 @@ -7,7 +7,6 @@ import android.app.PendingIntent import android.content.Context import android.net.Uri import android.os.Build -import android.provider.CalendarContract import android.util.Log import androidx.core.app.NotificationCompat import androidx.core.app.NotificationManagerCompat @@ -66,14 +65,8 @@ object BackupScheduler { private const val WORK_NAME = "auto-backup" private const val WORK_NAME_NOW = "auto-backup-now" - 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 - - /** Longest a change run waits on a provider that never goes quiet (a long sync). */ - private const val CHANGE_MAX_WAIT_MINUTES = 15L + private const val WORK_NAME_CHANGE = "auto-backup-change" + internal const val KEY_CHANGE_RUN = "change_run" private val reconcileLock = Mutex() @@ -84,67 +77,70 @@ object BackupScheduler { * * The first run is delayed by one interval so it doesn't follow an immediate * [runNow] with a near-identical copy. With backing up after changes on - * (#516), the change trigger is armed unless a slot is already waiting. + * (#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. */ suspend fun reconcile(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { reconcileLock.withLock { - val workManager = WorkManager.getInstance(context) - suspend fun cancelWatch() = CHANGE_SLOTS.indices - .filter { slot -> slotStates(workManager, slot).any { !it.isFinished } } - .forEach { workManager.cancelUniqueWork(CHANGE_SLOTS[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 + try { + apply(context, prefs) + } catch (e: Exception) { + Log.w(TAG, "Scheduling the automatic backup failed", e) } - // 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 - } - takeWatchStep(context, workManager, self = null) } } + private suspend fun apply(context: Context, prefs: SettingsPrefs) { + val workManager = WorkManager.getInstance(context) + 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 = 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()) BackupChangeJob.scheduleIfIdle(context) else stopWatching() + } + /** - * Keep one change watch armed around the change run in [self] (see - * [watchStep]), under the same lock as [reconcile] so it can't outlast a - * switch-off. + * 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 watchNext(context: Context, prefs: SettingsPrefs, self: Int) = - withContext(NonCancellable) { - reconcileLock.withLock { - if (watchWanted(prefs)) takeWatchStep(context, WorkManager.getInstance(context), self) + internal suspend fun changed(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { + reconcileLock.withLock { + val wanted = prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && + prefs.autoBackupOnChange.first() + if (!wanted) return@withLock + val workManager = WorkManager.getInstance(context) + val states = workManager.getWorkInfosForUniqueWorkFlow(WORK_NAME_CHANGE).first().map { it.state } + changeRunPolicy(states)?.let { policy -> + 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() } - } - - private suspend fun takeWatchStep(context: Context, workManager: WorkManager, self: Int?) { - when (val step = watchStep(self, CHANGE_SLOTS.indices.map { slotStates(workManager, it) })) { - WatchStep.None -> Unit - is WatchStep.Cancel -> workManager.cancelUniqueWork(CHANGE_SLOTS[step.slot]).await() - is WatchStep.Arm -> watchChanges(context, step.slot, step.append) + BackupChangeJob.schedule(context) } } - private suspend fun slotStates(workManager: WorkManager, slot: Int): List = - workManager.getWorkInfosForUniqueWorkFlow(CHANGE_SLOTS[slot]).first().map { it.state } - - private suspend fun watchWanted(prefs: SettingsPrefs): Boolean = - prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && prefs.autoBackupOnChange.first() - /** * Run one export immediately (e.g. right after enabling or changing the * folder) for instant feedback. Unique + REPLACE so rapid taps coalesce into @@ -158,58 +154,18 @@ object BackupScheduler { ) } - /** - * 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 each change run arms the other slot ([watchNext]); [append] - * queues the request behind that slot's running run. - */ - private fun watchChanges(context: Context, slot: Int, append: Boolean) { - val constraints = Constraints.Builder() - .addContentUriTrigger(CalendarContract.CONTENT_URI, true) - .setTriggerContentUpdateDelay(CHANGE_SETTLE_MINUTES, TimeUnit.MINUTES) - .setTriggerContentMaxDelay(CHANGE_MAX_WAIT_MINUTES, TimeUnit.MINUTES) - .setRequiresBatteryNotLow(true) - .build() - val request = OneTimeWorkRequestBuilder() - .setConstraints(constraints) - .setInputData(workDataOf(KEY_CHANGE_SLOT to slot)) - .build() - val policy = if (append) ExistingWorkPolicy.APPEND_OR_REPLACE else ExistingWorkPolicy.KEEP - WorkManager.getInstance(context).enqueueUniqueWork(CHANGE_SLOTS[slot], policy, request) - } -} - -/** What keeps exactly one change watch armed (#516): nothing, a new watch in [slot], or cancelling the extra one there. */ -internal sealed interface WatchStep { - data object None : WatchStep - - /** [append]: queued behind the run still going in [slot], so it starts watching once that ends. */ - data class Arm(val slot: Int, val append: Boolean) : WatchStep - - data class Cancel(val slot: Int) : WatchStep + private const val TAG = "BackupScheduler" } /** - * The step that leaves exactly one watch waiting, from both slots' work - * [states], taken by the change run in [self] as it starts and ends, or by - * [BackupScheduler.reconcile] (null). A waiting watch is enough; two are one - * too many. With none, the other slot is armed, queued behind its run if one - * still shows as running, so a run whose end isn't recorded yet can't leave - * the provider unwatched. + * 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 watchStep(self: Int?, states: List>): WatchStep { - fun waiting(slot: Int) = states[slot].any { it == WorkInfo.State.ENQUEUED || it == WorkInfo.State.BLOCKED } - val keep = self ?: 0 - val other = 1 - keep - val target = if (self == null) keep else other - return when { - waiting(keep) && waiting(other) -> WatchStep.Cancel(other) - waiting(keep) || waiting(other) -> WatchStep.None - else -> WatchStep.Arm(target, append = WorkInfo.State.RUNNING in states[target]) - } +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 } /** @@ -235,24 +191,10 @@ class BackupWorker( override suspend fun doWork(): Result { val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java) - val prefs = deps.settingsPrefs() - val slot = inputData.getInt(BackupScheduler.KEY_CHANGE_SLOT, -1) - if (slot < 0) return backUp(deps, prefs, changeRun = false) - suspend fun watchNext() = runCatching { - BackupScheduler.watchNext(applicationContext, prefs, slot) - }.onFailure { Log.w(TAG, "Arming the next change run failed", it) } - watchNext() - // Never fails or retries: a retry would only wait for another change. - try { - backUp(deps, prefs, changeRun = true) - } catch (e: CancellationException) { - throw e - } catch (e: Exception) { - Log.w(TAG, "Backup after a change failed", e) - } finally { - watchNext() - } - return Result.success() + val changeRun = inputData.getBoolean(BackupScheduler.KEY_CHANGE_RUN, false) + val result = backUp(deps, deps.settingsPrefs(), changeRun) + // A failed change run would fail the one queued behind it too. + return if (changeRun) Result.success() else result } /** 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..a2dbe12b --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt @@ -0,0 +1,81 @@ +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.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 { + try { + val deps = EntryPointAccessors.fromApplication(applicationContext, BackupWorker.Deps::class.java) + BackupScheduler.changed(applicationContext, deps.settingsPrefs()) + } catch (e: Exception) { + Log.w(TAG, "Queueing a backup after a change failed", e) + } finally { + jobFinished(params, false) + } + } + return true + } + + override fun onStopJob(params: JobParameters): Boolean = false + + override fun onDestroy() { + scope.cancel() + super.onDestroy() + } + + companion object { + /** Clear of WorkManager's ids, which count up from 0. */ + private 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() + context.getSystemService(JobScheduler::class.java).schedule(job) + } + + /** Arm the watch unless it already waits; replacing it would drop the changes it has seen. */ + fun scheduleIfIdle(context: Context) { + if (context.getSystemService(JobScheduler::class.java).getPendingJob(JOB_ID) == null) schedule(context) + } + + fun cancel(context: Context) = context.getSystemService(JobScheduler::class.java).cancel(JOB_ID) + } +} 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/data/backup/WatchStepTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt deleted file mode 100644 index 108b4b0d..00000000 --- a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/WatchStepTest.kt +++ /dev/null @@ -1,41 +0,0 @@ -package de.jeanlucmakiola.calendula.data.backup - -import androidx.work.WorkInfo.State.BLOCKED -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 WatchStepTest { - - @Test - fun `a lone run arms the idle slot and leaves a waiting one`() { - assertThat(watchStep(0, listOf(listOf(RUNNING), listOf(SUCCEEDED)))).isEqualTo(WatchStep.Arm(1, append = false)) - assertThat(watchStep(0, listOf(listOf(RUNNING), listOf(ENQUEUED)))).isEqualTo(WatchStep.None) - } - - @Test - fun `a run that still shows as running gets the watch queued behind it`() { - assertThat(watchStep(1, listOf(listOf(RUNNING), listOf(RUNNING)))).isEqualTo(WatchStep.Arm(0, append = true)) - } - - @Test - fun `runs that fired together end with one watch`() { - val afterFirst = listOf(listOf(RUNNING), listOf(RUNNING, BLOCKED)) - assertThat(watchStep(1, afterFirst)).isEqualTo(WatchStep.None) - assertThat(watchStep(0, afterFirst)).isEqualTo(WatchStep.None) - } - - @Test - fun `a second waiting watch is cancelled`() { - assertThat(watchStep(0, listOf(listOf(ENQUEUED), listOf(ENQUEUED)))).isEqualTo(WatchStep.Cancel(1)) - assertThat(watchStep(null, listOf(listOf(ENQUEUED), listOf(ENQUEUED)))).isEqualTo(WatchStep.Cancel(1)) - } - - @Test - fun `reconcile arms slot 0 only when nothing waits`() { - assertThat(watchStep(null, listOf(emptyList(), emptyList()))).isEqualTo(WatchStep.Arm(0, append = false)) - assertThat(watchStep(null, listOf(emptyList(), listOf(ENQUEUED)))).isEqualTo(WatchStep.None) - } -} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 25e2b206..d5c5b5a6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -485,29 +485,29 @@ 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. `BackupScheduler.watchChanges` -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 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 checks again as it ends; -`watchStep` keeps exactly one watch waiting, queueing a new one behind a run -that still shows as running and cancelling a second one. 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. +**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 From 281d511402c273c08e65342c971d8c119f083f77 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 12:55:49 +0100 Subject: [PATCH 13/15] fix(#516): WorkManager's JobScheduler ids kept below the change watch's --- app/src/main/AndroidManifest.xml | 12 ++++++++++++ .../java/de/jeanlucmakiola/calendula/CalendulaApp.kt | 8 +++++++- .../calendula/data/backup/BackupChangeJob.kt | 4 ++-- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 175dab02..fbf7b9d0 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -485,6 +485,18 @@ + + + + + diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt b/app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt index 6404f97b..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() 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 index a2dbe12b..cb99ff00 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt @@ -51,8 +51,8 @@ class BackupChangeJob : JobService() { } companion object { - /** Clear of WorkManager's ids, which count up from 0. */ - private const val JOB_ID = 0x0516_0001 + /** 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" From 07a2bb632f3d559741e5cbf66e0af75c8584302c Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 13:05:20 +0100 Subject: [PATCH 14/15] fix(#516): review round 11 - watch re-armed even when queueing fails or the job is stopped, reconcile off the main thread --- app/src/main/AndroidManifest.xml | 11 ++-- .../calendula/data/backup/AutoBackup.kt | 57 +++++++++++++------ .../calendula/data/backup/BackupChangeJob.kt | 13 +++-- 3 files changed, 54 insertions(+), 27 deletions(-) diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index fbf7b9d0..6e29286b 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -296,6 +296,12 @@ + + + - - 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 8b1e9d93..043c2965 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 @@ -45,6 +45,7 @@ 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 @@ -70,6 +71,9 @@ object BackupScheduler { 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 saved settings: enqueue a unique * periodic request when backup is on and a folder is set, otherwise cancel @@ -81,7 +85,7 @@ object BackupScheduler { * 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. */ - suspend fun reconcile(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { + suspend fun reconcile(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable + Dispatchers.IO) { reconcileLock.withLock { try { apply(context, prefs) @@ -115,7 +119,13 @@ object BackupScheduler { ExistingPeriodicWorkPolicy.UPDATE, request, ) - if (prefs.autoBackupOnChange.first()) BackupChangeJob.scheduleIfIdle(context) else stopWatching() + 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 + } } /** @@ -125,22 +135,30 @@ object BackupScheduler { */ internal suspend fun changed(context: Context, prefs: SettingsPrefs) = withContext(NonCancellable) { reconcileLock.withLock { - val wanted = prefs.autoBackupEnabled.first() && prefs.autoBackupFolderUri.first() != null && - prefs.autoBackupOnChange.first() - if (!wanted) return@withLock - val workManager = WorkManager.getInstance(context) - val states = workManager.getWorkInfosForUniqueWorkFlow(WORK_NAME_CHANGE).first().map { it.state } - changeRunPolicy(states)?.let { policy -> - 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() + // 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 } - BackupChangeJob.schedule(context) } } + 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() + } + /** * Run one export immediately (e.g. right after enabling or changing the * folder) for instant feedback. Unique + REPLACE so rapid taps coalesce into @@ -192,9 +210,16 @@ class BackupWorker( override suspend fun doWork(): Result { val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java) val changeRun = inputData.getBoolean(BackupScheduler.KEY_CHANGE_RUN, false) - val result = backUp(deps, deps.settingsPrefs(), changeRun) + if (!changeRun) return backUp(deps, deps.settingsPrefs(), changeRun = false) // A failed change run would fail the one queued behind it too. - return if (changeRun) Result.success() else result + 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() } /** 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 index cb99ff00..74a69210 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt @@ -43,7 +43,8 @@ class BackupChangeJob : JobService() { return true } - override fun onStopJob(params: JobParameters): Boolean = false + /** 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() @@ -68,13 +69,13 @@ class BackupChangeJob : JobService() { .setTriggerContentUpdateDelay(TimeUnit.MINUTES.toMillis(SETTLE_MINUTES)) .setTriggerContentMaxDelay(TimeUnit.MINUTES.toMillis(MAX_WAIT_MINUTES)) .build() - context.getSystemService(JobScheduler::class.java).schedule(job) + if (context.getSystemService(JobScheduler::class.java).schedule(job) != JobScheduler.RESULT_SUCCESS) { + Log.w(TAG, "The change watch could not be scheduled") + } } - /** Arm the watch unless it already waits; replacing it would drop the changes it has seen. */ - fun scheduleIfIdle(context: Context) { - if (context.getSystemService(JobScheduler::class.java).getPendingJob(JOB_ID) == null) schedule(context) - } + 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) } From 00a8040efed2f3cacb4eefc2265815b44fb380a9 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 14 Nov 2026 13:17:13 +0100 Subject: [PATCH 15/15] fix(#516): review round 12 - a watch that fails early is retried --- .../calendula/data/backup/BackupChangeJob.kt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) 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 index 74a69210..3b56b30d 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/BackupChangeJob.kt @@ -9,6 +9,7 @@ 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 @@ -31,14 +32,18 @@ class BackupChangeJob : JobService() { override fun onStartJob(params: JobParameters): Boolean { scope.launch { - try { + // 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) - } finally { - jobFinished(params, false) + true } + jobFinished(params, failed) } return true }