Merge feat/516-backup-on-change into release/2.25.0

# Conflicts:
#	app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt
This commit is contained in:
makiolaj committed 2026-11-18 16:16:18 +01:00
commit 55dfb08aa3
13 files changed
+655 -94

No files matched your search

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