fix(#516): review round 2 - serialised reconcile, change runs skip copies a loading listing hides, failed copies lose their hash, change-run failures reported

This commit is contained in:
makiolaj committed 2026-11-14 04:01:14 +01:00
1 parent f18ae694a7
commit 93b795ed72
8 files changed
+113 -94

No files matched your search

@@ -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)
}
}
@@ -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<BackupWorker>(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<BackupWorker>(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<String>) = prefs.updateAutoBackupLedger(folder.toString()) {
val pending = plan.handOff - it.latestHeldElsewhere(target.key)
withLedgerEntry(it, latestKey, stale + pending + current, liveKeys)
}
recordLatest(plan.staleLatest)
if (landed == latest) {
prefs.updateAutoBackupFingerprints(folder.toString()) {
withFingerprint(it, target.key, fingerprint, liveKeys)
suspend fun recordLatest(stale: List<String>, 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++
@@ -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])
}
}
}
@@ -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<String>,
listed: Set<String>,
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()
}
@@ -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) {
@@ -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)
@@ -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()
}
}
+4 -3
View File
@@ -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