π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
[mobile] Preserve iOS timing and type background outcomes
laurenspriem7fb6d723d08c
diff --git a/mobile/apps/photos/plugins/ente_background_manager/README.md b/mobile/apps/photos/plugins/ente_background_manager/README.mdindex c59e8e6c42..73f7472712 100644--- a/mobile/apps/photos/plugins/ente_background_manager/README.md+++ b/mobile/apps/photos/plugins/ente_background_manager/README.md@@ -14,11 +14,15 @@ The package is part of the mobile workspace. Photos does not depend on or initia- `BackgroundManager.stopActiveRun` requests stopping of the current invocation and completes after retirement. It preserves future registrations and is an immediate no-op when idle. Use it from the foreground; a background callback should return after cleanup instead of awaiting its own retirement.- `BackgroundManager.scheduledTasks` queries native registrations. A pending registration is not a guarantee that the OS will run it.+`BackgroundTaskOutcome.outcome` is a `BackgroundOutcome`: `skipped`, `stopped`, `failed`, or `forcedTeardown`. Its `reason` is a native diagnostic string; Android system stops may include a WorkManager stop-reason code as `system:N`, while the task receives `BackgroundStopReason.system`. Errors from the Dart executor contain the exception type name; native failures may include a platform error message.+Task configuration supports refresh/processing kind, frequency, initial delay, supported native constraints, and two optional durations. `runBudget` requests cooperative stopping from native entry, including engine startup. `foregroundStopTimeout` starts force teardown after the first foreground arrival. Omission disables the corresponding timer; zero acts immediately and negative durations are rejected. Android supports periodic flex and device-idle constraints. iOS supports network/power constraints only for processing tasks; unsupported combinations are rejected.iOS configurations accept at most one refresh task and ten processing tasks, including when scheduling is disabled. Configurations exceeding these limits fail before changing stored settings, pending schedules, or active work. [Apple limits each app to one pending refresh request and ten pending processing requests](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler/submit(_:)).-Before supplying `foregroundStopTimeout`, validate the lifetime of the consumer's native/FFI operations. Destroying a Flutter engine does not establish that those operations have stopped.+A scheduling failure rejects the `configure` future. iOS also emits a `failed` outcome with reason `schedule` for each task that failed scheduling; Android stops at the first error and reports it through the future.++Before supplying `foregroundStopTimeout`, validate the lifetime of the consumer's native/FFI operations. Destroying a Flutter engine does not establish that those operations have stopped. Teardown can block the main thread while synchronous Dart/FFI work finishes. The timeout starts teardown; it does not bound how long teardown takes.## Native lifecycle@@ -26,6 +30,8 @@ Each platform has one process-local runtime. Admission checks backend eligibilitThe native eligibility callback controls whether work may run; it preserves future schedules when eligibility is temporarily false. Scheduling follows the configured enablement and task identifiers. iOS stores the last successfully submitted policy for each task, so a later configuration call or normal delivery can apply unfinished updates after a process restart. Older stored configurations without this submission record are reconciled once. When reconfigured, iOS cancels this plugin's removed identifiers before replacing their saved configuration, including identifiers the app no longer registers after an update. Android tags its native requests so later configuration calls can find and cancel removed tasks even if an earlier cancellation was interrupted. Neither platform retries automatically.+Changing only the budget, foreground grace, or dispatcher preserves a pending iOS request's timing. Changes to frequency, initial delay, task kind, or supported scheduling constraints still replace the pending request.+The slot remains occupied during startup, execution, cleanup, and teardown. Native callbacks and timers are tied to a unique invocation. Foreground entry always requests stopping, including during startup. Stops remain latched; repeated visibility changes cannot revive a task or extend its grace. A callback returning `completed` after a stop request is reported as `stopped`. Configuration updates affect later runs only.Normal completion, startup failure, system interruption, and configured forced teardown share one retirement path. Retirement invalidates timers, detaches the task channel, destroys the background engine, and completes the native invocation once. iOS re-arms normal future opportunities independently of Dart. No plugin retry loop, work queue, engine pool, or persistent event history is used.diff --git a/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundRuntime.swift b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundRuntime.swiftindex 9059591ed9..d17fdff380 100644--- a/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundRuntime.swift+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundRuntime.swift@@ -174,9 +174,11 @@ final class BackgroundRuntime: NSObject {let pending = Dictionary(requests.map { ($0.identifier, $0) }, uniquingKeysWith: { first, _ in first })let desired = self.configuration.enabled ? self.configuration.tasks : []+ let submitted = self.configuration.submitted ?? []var failure: Error?for task in desired {- if pending[task.identifier] != nil && (self.configuration.submitted ?? []).contains(task)+ if pending[task.identifier] != nil,+ submitted.contains(where: { $0.hasSameSchedule(as: task) }){continue}diff --git a/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/TaskConfiguration.swift b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/TaskConfiguration.swiftindex 6e217ea66a..37d28b133d 100644--- a/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/TaskConfiguration.swift+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/TaskConfiguration.swift@@ -13,6 +13,12 @@ struct TaskConfiguration: Codable, Equatable {let foregroundStopTimeoutMs: Int64?let callbackHandle: Int64+ func hasSameSchedule(as other: TaskConfiguration) -> Bool {+ identifier == other.identifier && kind == other.kind && frequencyMs == other.frequencyMs+ && initialDelayMs == other.initialDelayMs && requiresNetwork == other.requiresNetwork+ && requiresCharging == other.requiresCharging+ }+init(_ data: [String: Any], callbackHandle: Int64) throws {guard let identifier = data["identifier"] as? String, !identifier.isEmpty,let kind = data["kind"] as? String, ["refresh", "processing"].contains(kind),diff --git a/mobile/apps/photos/plugins/ente_background_manager/lib/ente_background_manager.dart b/mobile/apps/photos/plugins/ente_background_manager/lib/ente_background_manager.dartindex 69cadc55e3..73d4fc5b70 100644--- a/mobile/apps/photos/plugins/ente_background_manager/lib/ente_background_manager.dart+++ b/mobile/apps/photos/plugins/ente_background_manager/lib/ente_background_manager.dart@@ -10,6 +10,8 @@ enum BackgroundStopReason { foreground, budget, requested, system }enum BackgroundTaskResult { completed, skipped, stopped, failed }+enum BackgroundOutcome { skipped, stopped, failed, forcedTeardown }+class BackgroundTaskConfig {const BackgroundTaskConfig({required this.identifier,@@ -115,12 +117,12 @@ class BackgroundTaskStopped implements Exception {class BackgroundTaskOutcome {BackgroundTaskOutcome._(Map<Object?, Object?> data): identifier = data["identifier"]! as String,- outcome = data["outcome"]! as String,+ outcome = BackgroundOutcome.values.byName(data["outcome"]! as String),reason = data["reason"] as String?,error = data["error"] as String?;final String identifier;- final String outcome;+ final BackgroundOutcome outcome;final String? reason;final String? error;}