π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
[mobile] Add native background manager plugin
laurenspriemc8ed89ec33c9
diff --git a/mobile/apps/photos/plugins/ente_background_manager/README.md b/mobile/apps/photos/plugins/ente_background_manager/README.mdnew file mode 100644index 0000000000..6f642a7f2d--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/README.md@@ -0,0 +1,49 @@+# Ente background manager++A Flutter plugin for native background scheduling and headless task execution. Android uses Jetpack WorkManager; iOS uses Background Tasks. The consumer owns task logic, credentials, progress, domain locks, and cleanup.++## Integration status++The package is part of the mobile workspace. Photos does not depend on or initialize it yet; app integration is a separate change.++## Consumer interface++- `BackgroundManager.configure` supplies a retained top-level dispatcher, task configurations, scheduling enablement, and an outcome handler. Repeated configuration reconciles persistent schedules.+- `BackgroundManager.executeTask` runs the callback inside the dispatcher and handles readiness, stop delivery, errors, and completion.+- `BackgroundTask` exposes its identifier, elapsed time, optional remaining budget, and a latched stop signal. The callback stops admitting work, drains cleanup, and returns a `BackgroundTaskResult`.+- `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.++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.++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.++## Native lifecycle++Each platform has one process-local runtime. Admission checks backend eligibility, the active execution slot, and native foreground visibility before creating an engine. Busy or foreground deliveries finish as skips. Every admitted run captures its configuration and dispatcher binding and creates a fresh engine.++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. 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.++Consumers log their task activity. Skips, stops, forced teardown, and failures are forwarded to an available outcome handler; otherwise the plugin writes one native log line (`EnteBackgroundManager` on Android, `io.ente.background` on iOS).++## Native installation++The plugin requires Android API 26 or later and iOS 15.1 or later. iOS uses CocoaPods integration.++On Android, call `BackgroundManagerPlugin.install` from the host application's `onCreate`, supplying the application and an eligibility callback. Call `BackgroundManagerPlugin.onForeground` before `super.onCreate` in the foreground activity so an existing background run receives the stop signal before foreground engine creation. The plugin also observes activity lifecycle callbacks.++On iOS, call `BackgroundManagerPlugin.install` in `AppDelegate` with an eligibility callback and the generated plugin registrant. Register each task identifier with `BackgroundManagerPlugin.registerTask` before launch completes, declare the identifiers in `BGTaskSchedulerPermittedIdentifiers`, and enable the corresponding background modes.++## Validation++The Android test runs the real worker, scheduler configuration, method-channel encoding, and lifecycle/timer logic with mocked Flutter engines. It covers foreground and busy admission, ownership during teardown, startup stops, cooperative completion, foreground grace, configuration changes during a run, stale events, bootstrap failure, and preservation of recurring scheduling after active-run stopping.++Use a temporary Flutter host with a path dependency on this package to run native checks. Match Photos' Android build-tool versions and set the host's minimum SDK to 26. From its `android` directory:++```sh+./gradlew :ente_background_manager:testDebugUnitTest :ente_background_manager:lintDebug+```++Once the consumer is integrated, device checks remain necessary for OS-delivered refresh/processing opportunities, cold launch, system expiration, foreground handoff during real work, and release-mode callback retention.diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/build.gradle b/mobile/apps/photos/plugins/ente_background_manager/android/build.gradlenew file mode 100644index 0000000000..17b71edcf7--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/build.gradle@@ -0,0 +1,47 @@+group 'io.ente.background'+version '1.0'++buildscript {+ ext.kotlin_version = '2.1.10'+ repositories {+ google()+ mavenCentral()+ }+ dependencies {+ classpath 'com.android.tools.build:gradle:8.10.1'+ classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"+ }+}++apply plugin: 'com.android.library'+apply plugin: 'kotlin-android'++android {+ namespace 'io.ente.background'+ compileSdk 36+ defaultConfig {+ minSdkVersion 26+ }+ compileOptions {+ sourceCompatibility JavaVersion.VERSION_1_8+ targetCompatibility JavaVersion.VERSION_1_8+ }+ kotlinOptions {+ jvmTarget = '1.8'+ }+ sourceSets {+ main.java.srcDirs += 'src/main/kotlin'+ }+ testOptions {+ unitTests.includeAndroidResources = true+ }+}++dependencies {+ implementation 'androidx.work:work-runtime:2.10.2'+ implementation 'androidx.concurrent:concurrent-futures:1.2.0'+ testImplementation 'junit:junit:4.13.2'+ testImplementation 'org.robolectric:robolectric:4.16'+ testImplementation 'org.mockito:mockito-core:5.18.0'+ testImplementation 'androidx.work:work-testing:2.10.2'+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/main/AndroidManifest.xml b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/AndroidManifest.xmlnew file mode 100644index 0000000000..d7546021b5--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/AndroidManifest.xml@@ -0,0 +1,3 @@+<manifest xmlns:android="http://schemas.android.com/apk/res/android">+ <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />+</manifest>diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundManagerPlugin.kt b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundManagerPlugin.ktnew file mode 100644index 0000000000..98fa97aa97--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundManagerPlugin.kt@@ -0,0 +1,88 @@+package io.ente.background++import android.app.Application+import io.flutter.embedding.engine.plugins.FlutterPlugin+import io.flutter.embedding.engine.plugins.activity.ActivityAware+import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding+import io.flutter.plugin.common.MethodCall+import io.flutter.plugin.common.MethodChannel++class BackgroundManagerPlugin : FlutterPlugin, MethodChannel.MethodCallHandler, ActivityAware {+ private var channel: MethodChannel? = null+ internal var observesOutcomes = false+ private set++ override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {+ channel =+ MethodChannel(binding.binaryMessenger, CONTROL_CHANNEL).also {+ it.setMethodCallHandler(this)+ }+ BackgroundRuntime.attach(this)+ }++ override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {+ observesOutcomes = false+ BackgroundRuntime.detach(this)+ channel?.setMethodCallHandler(null)+ channel = null+ }++ override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {+ when (call.method) {+ "configure" -> {+ observesOutcomes = true+ BackgroundRuntime.configure(call.arguments as? Map<*, *>, result)+ }+ "stopActiveRun" -> {+ BackgroundRuntime.requestStop(result)+ }+ "scheduledTasks" -> BackgroundRuntime.scheduledTasks(result)+ else -> result.notImplemented()+ }+ }++ internal fun report(event: Map<String, Any?>, fallback: () -> Unit) {+ val current = channel+ if (!observesOutcomes || current == null) {+ fallback()+ return+ }+ current.invokeMethod(+ "outcome",+ event,+ object : MethodChannel.Result {+ override fun success(result: Any?) {+ if (result != true) fallback()+ }++ override fun error(code: String, message: String?, details: Any?) = fallback()++ override fun notImplemented() = fallback()+ },+ )+ }++ override fun onAttachedToActivity(binding: ActivityPluginBinding) {+ BackgroundRuntime.foreground()+ }++ override fun onReattachedToActivityForConfigChanges(binding: ActivityPluginBinding) {+ BackgroundRuntime.foreground()+ }++ override fun onDetachedFromActivityForConfigChanges() = Unit++ override fun onDetachedFromActivity() = Unit++ companion object {+ internal const val CONTROL_CHANNEL = "io.ente.background/control"++ fun install(application: Application, isEnabled: () -> Boolean) {+ BackgroundRuntime.install(application, isEnabled)+ }++ fun onForeground() {+ BackgroundRuntime.foreground()+ }+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundRuntime.kt b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundRuntime.ktnew file mode 100644index 0000000000..27435add7f--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundRuntime.kt@@ -0,0 +1,536 @@+package io.ente.background++import android.app.Activity+import android.app.Application+import android.content.Context+import android.os.Build+import android.os.Bundle+import android.os.Handler+import android.os.Looper+import android.os.SystemClock+import android.util.Log+import androidx.work.Constraints+import androidx.work.Data+import androidx.work.ExistingPeriodicWorkPolicy+import androidx.work.NetworkType+import androidx.work.PeriodicWorkRequest+import androidx.work.WorkInfo+import androidx.work.WorkManager+import io.flutter.FlutterInjector+import io.flutter.embedding.engine.FlutterEngine+import io.flutter.embedding.engine.dart.DartExecutor+import io.flutter.plugin.common.MethodChannel+import io.flutter.view.FlutterCallbackInformation+import java.util.UUID+import java.util.concurrent.Executors+import java.util.concurrent.TimeUnit+import org.json.JSONArray+import org.json.JSONObject++internal object BackgroundRuntime {+ private const val TAG = "EnteBackgroundManager"+ private const val PREFERENCES = "ente_background_manager"+ private const val CONFIGURATION = "configuration"+ private const val TASK_DATA = "task"+ private val main = Handler(Looper.getMainLooper())+ private val scheduler = Executors.newSingleThreadExecutor()+ private val observers = LinkedHashSet<BackgroundManagerPlugin>()+ private val startedActivities = HashSet<Activity>()+ private val startingActivities = HashSet<Activity>()+ private var application: Application? = null+ private var isAllowed: () -> Boolean = { false }+ private var isForeground = false+ private var active: Run? = null+ var createEngine: (Context) -> FlutterEngine = { FlutterEngine(it) }+ var findCallback: (Long) -> FlutterCallbackInformation? =+ FlutterCallbackInformation::lookupCallbackInformation++ private class Run(+ val worker: BackgroundWorker,+ val configuration: TaskConfiguration,+ val startedAt: Long,+ val completion: (Boolean) -> Unit,+ ) {+ val invocation = UUID.randomUUID().toString()+ var engine: FlutterEngine? = null+ var channel: MethodChannel? = null+ var ready = false+ var retiring = false+ var stopReason: String? = null+ var budgetTimer: Runnable? = null+ var foregroundTimer: Runnable? = null+ val stopResults = ArrayList<MethodChannel.Result>()+ }++ fun install(app: Application, allowed: () -> Boolean) {+ isAllowed = allowed+ if (application != null) return+ application = app+ app.registerActivityLifecycleCallbacks(+ object : Application.ActivityLifecycleCallbacks {+ override fun onActivityPreCreated(activity: Activity, savedInstanceState: Bundle?) {+ startingActivities.add(activity)+ foreground()+ }++ override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {+ startingActivities.add(activity)+ foreground()+ }++ override fun onActivityStarted(activity: Activity) {+ startingActivities.remove(activity)+ startedActivities.add(activity)+ foreground()+ }++ override fun onActivityResumed(activity: Activity) = foreground()++ override fun onActivityStopped(activity: Activity) {+ startedActivities.remove(activity)+ if (startedActivities.isEmpty() && startingActivities.isEmpty())+ isForeground = false+ }++ override fun onActivityDestroyed(activity: Activity) {+ startedActivities.remove(activity)+ startingActivities.remove(activity)+ if (startedActivities.isEmpty() && startingActivities.isEmpty())+ isForeground = false+ }++ override fun onActivityPaused(activity: Activity) = Unit++ override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) =+ Unit+ }+ )+ }++ fun attach(plugin: BackgroundManagerPlugin) {+ observers.add(plugin)+ }++ fun detach(plugin: BackgroundManagerPlugin) {+ observers.remove(plugin)+ }++ fun foreground() {+ isForeground = true+ active?.let { stop(it, "foreground") }+ }++ fun requestStop(result: MethodChannel.Result? = null) {+ val run = active+ if (run == null) {+ result?.success(null)+ return+ }+ if (result != null) run.stopResults.add(result)+ stop(run, "requested")+ }++ fun configure(arguments: Map<*, *>?, result: MethodChannel.Result) {+ val app = application+ if (app == null || arguments == null) {+ result.error("configuration", "Background manager was not installed at launch", null)+ return+ }+ val configurations: List<TaskConfiguration>+ val enabled: Boolean+ try {+ val callback = (arguments["callbackHandle"] as Number).toLong()+ configurations =+ (arguments["tasks"] as List<*>).map {+ TaskConfiguration.decode(JSONObject(it as Map<*, *>), callback)+ }+ require(configurations.map { it.identifier }.toSet().size == configurations.size)+ enabled = arguments["enabled"] as Boolean+ } catch (exception: Exception) {+ result.error("configuration", exception.message, null)+ return+ }+ if (!enabled) requestStop()+ val activeIdentifier = active?.configuration?.identifier+ scheduler.execute {+ try {+ val preferences = app.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)+ val previous = preferences.getString(CONFIGURATION, null)?.let(::JSONObject)+ val previousTasks = previous?.optJSONArray("tasks") ?: JSONArray()+ val json =+ JSONObject()+ .put("enabled", enabled)+ .put(+ "tasks",+ JSONArray(configurations.map { JSONObject(it.encode()) }),+ )+ check(preferences.edit().putString(CONFIGURATION, json.toString()).commit())+ val manager = WorkManager.getInstance(app)+ val selected =+ if (enabled) configurations.map { it.identifier }.toSet() else emptySet()+ for (index in 0 until previousTasks.length()) {+ val identifier = previousTasks.getJSONObject(index).getString("identifier")+ if (identifier !in selected && identifier != activeIdentifier) {+ manager.cancelUniqueWork(identifier).result.get()+ }+ }+ if (enabled) {+ for (configuration in configurations) {+ val builder =+ configuration.flexMs?.let {+ PeriodicWorkRequest.Builder(+ BackgroundWorker::class.java,+ configuration.frequencyMs,+ TimeUnit.MILLISECONDS,+ it,+ TimeUnit.MILLISECONDS,+ )+ }+ ?: PeriodicWorkRequest.Builder(+ BackgroundWorker::class.java,+ configuration.frequencyMs,+ TimeUnit.MILLISECONDS,+ )+ val request =+ builder+ .setInitialDelay(+ configuration.initialDelayMs,+ TimeUnit.MILLISECONDS,+ )+ .setInputData(+ Data.Builder()+ .putString(TASK_DATA, configuration.encode())+ .build()+ )+ .setConstraints(+ Constraints.Builder()+ .setRequiredNetworkType(+ if (configuration.requiresNetwork) NetworkType.CONNECTED+ else NetworkType.NOT_REQUIRED+ )+ .setRequiresCharging(configuration.requiresCharging)+ .setRequiresDeviceIdle(configuration.requiresDeviceIdle)+ .build()+ )+ .build()+ manager+ .enqueueUniquePeriodicWork(+ configuration.identifier,+ ExistingPeriodicWorkPolicy.UPDATE,+ request,+ )+ .result+ .get()+ }+ }+ main.post { result.success(null) }+ } catch (exception: Exception) {+ main.post { result.error("schedule", exception.message, null) }+ }+ }+ }++ fun scheduledTasks(result: MethodChannel.Result) {+ val app =+ application+ ?: run {+ result.error(+ "configuration",+ "Background manager was not installed at launch",+ null,+ )+ return+ }+ scheduler.execute {+ try {+ val json =+ app.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)+ .getString(CONFIGURATION, null)+ ?.let(::JSONObject)+ val tasks = json?.optJSONArray("tasks") ?: JSONArray()+ val manager = WorkManager.getInstance(app)+ val states =+ (0 until tasks.length()).associate { index ->+ val identifier = tasks.getJSONObject(index).getString("identifier")+ identifier to+ manager.getWorkInfosForUniqueWork(identifier).get().any {+ !it.state.isFinished+ }+ }+ main.post { result.success(states) }+ } catch (exception: Exception) {+ main.post { result.error("schedule", exception.message, null) }+ }+ }+ }++ fun start(worker: BackgroundWorker, startedAt: Long, completion: (Boolean) -> Unit) {+ onMain {+ if (worker.isStopped) return@onMain+ val configuration =+ try {+ TaskConfiguration.decode(+ JSONObject(requireNotNull(worker.inputData.getString(TASK_DATA)))+ )+ } catch (exception: Exception) {+ report("unknown", "failed", "configuration", exception.message)+ completion(false)+ return@onMain+ }+ val enabled =+ try {+ val saved =+ application+ ?.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)+ ?.getString(CONFIGURATION, null)+ ?.let(::JSONObject)+ val tasks = saved?.optJSONArray("tasks") ?: JSONArray()+ saved?.optBoolean("enabled") == true &&+ isAllowed() &&+ (0 until tasks.length()).any {+ tasks.getJSONObject(it).getString("identifier") ==+ configuration.identifier+ }+ } catch (exception: Exception) {+ report(configuration.identifier, "failed", "configuration", exception.message)+ completion(false)+ return@onMain+ }+ val skip =+ when {+ !enabled -> "disabled"+ active != null -> "busy"+ isForeground -> "foreground"+ else -> null+ }+ if (skip != null) {+ report(configuration.identifier, "skipped", skip)+ if (skip == "disabled") {+ retireUnselectedSchedule(configuration.identifier)+ }+ completion(true)+ return@onMain+ }+ val run = Run(worker, configuration, startedAt, completion)+ active = run+ configuration.runBudgetMs?.let { budget ->+ run.budgetTimer =+ Runnable { if (active === run) stop(run, "budget") }+ .also {+ main.postDelayed(it, (budget - elapsed(run)).coerceAtLeast(0))+ }+ }+ try {+ val loader = FlutterInjector.instance().flutterLoader()+ loader.startInitialization(worker.applicationContext)+ loader.ensureInitializationCompleteAsync(worker.applicationContext, null, main) {+ if (active !== run || run.retiring) return@ensureInitializationCompleteAsync+ if (run.worker.isStopped) {+ retire(run, "stopped", "system")+ return@ensureInitializationCompleteAsync+ }+ try {+ val callback =+ requireNotNull(findCallback(configuration.callbackHandle)) {+ "Background dispatcher is unavailable"+ }+ val engine = createEngine(worker.applicationContext)+ run.engine = engine+ val channel =+ MethodChannel(+ engine.dartExecutor.binaryMessenger,+ "io.ente.background/worker",+ )+ run.channel = channel+ channel.setMethodCallHandler { call, result ->+ if (active !== run || run.retiring) {+ result.success(null)+ } else+ when (call.method) {+ "ready" -> {+ if (run.ready) {+ result.error(+ "bootstrap",+ "Dispatcher already started",+ null,+ )+ } else {+ run.ready = true+ result.success(+ mapOf(+ "invocation" to run.invocation,+ "identifier" to configuration.identifier,+ "elapsedMs" to elapsed(run),+ "runBudgetMs" to configuration.runBudgetMs,+ "stopReason" to run.stopReason,+ )+ )+ }+ }+ "complete" -> {+ val data = call.arguments as? Map<*, *>+ if (data?.get("invocation") != run.invocation) {+ result.error(+ "invocation",+ "Stale background completion",+ null,+ )+ } else {+ val outcome = data["outcome"] as? String+ if (+ outcome !in+ setOf(+ "completed",+ "skipped",+ "stopped",+ "failed",+ )+ ) {+ result.error(+ "outcome",+ "Unknown task outcome",+ null,+ )+ } else {+ result.success(null)+ retire(+ run,+ outcome!!,+ run.stopReason,+ data["error"] as? String,+ )+ }+ }+ }+ else -> result.notImplemented()+ }+ }+ engine.dartExecutor.executeDartCallback(+ DartExecutor.DartCallback(+ worker.applicationContext.assets,+ loader.findAppBundlePath(),+ callback,+ )+ )+ } catch (exception: Exception) {+ retire(run, "failed", "bootstrap", exception.message)+ }+ }+ } catch (exception: Exception) {+ retire(run, "failed", "bootstrap", exception.message)+ }+ }+ }++ private fun onMain(action: () -> Unit) {+ if (Looper.myLooper() == main.looper) action() else main.post { action() }+ }++ fun nativeStop(worker: BackgroundWorker) {+ main.post {+ active+ ?.takeIf { it.worker === worker }+ ?.let {+ stop(it, "system")+ val reason =+ if (+ Build.VERSION.SDK_INT >= 31 &&+ worker.stopReason != WorkInfo.STOP_REASON_UNKNOWN+ ) {+ "system:${worker.stopReason}"+ } else "system"+ retire(it, "stopped", reason)+ }+ }+ }++ private fun elapsed(run: Run): Long =+ (SystemClock.elapsedRealtime() - run.startedAt).coerceAtLeast(0)++ private fun stop(run: Run, reason: String) {+ if (active !== run || run.retiring) return+ if (run.stopReason == null) {+ run.stopReason = reason+ if (run.ready)+ run.channel?.invokeMethod(+ "stop",+ mapOf("invocation" to run.invocation, "reason" to reason),+ )+ }+ if (reason == "foreground" && run.foregroundTimer == null) {+ run.configuration.foregroundStopTimeoutMs?.let { grace ->+ run.foregroundTimer =+ Runnable {+ if (active === run) retire(run, "forcedTeardown", "foreground")+ }+ .also { main.postDelayed(it, grace) }+ }+ }+ }++ private fun retire(run: Run, outcome: String, reason: String? = null, error: String? = null) {+ if (active !== run || run.retiring) return+ run.retiring = true+ run.budgetTimer?.let(main::removeCallbacks)+ run.foregroundTimer?.let(main::removeCallbacks)+ val terminal = if (outcome == "completed" && run.stopReason != null) "stopped" else outcome+ try {+ run.channel?.setMethodCallHandler(null)+ run.engine?.destroy()+ } catch (exception: Exception) {+ report(run.configuration.identifier, "failed", "teardown", exception.message)+ run.stopResults.forEach { it.error("teardown", exception.message, null) }+ run.stopResults.clear()+ run.completion(false)+ return+ }+ active = null+ retireUnselectedSchedule(run.configuration.identifier)+ if (terminal != "completed") report(run.configuration.identifier, terminal, reason, error)+ run.completion(terminal != "failed" && terminal != "forcedTeardown")+ run.stopResults.forEach { it.success(null) }+ run.stopResults.clear()+ }++ private fun retireUnselectedSchedule(identifier: String) {+ val app = application ?: return+ scheduler.execute {+ try {+ val saved =+ app.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)+ .getString(CONFIGURATION, null)+ ?.let(::JSONObject)+ val tasks = saved?.optJSONArray("tasks") ?: JSONArray()+ val selected =+ saved?.optBoolean("enabled") == true &&+ (0 until tasks.length()).any {+ tasks.getJSONObject(it).getString("identifier") == identifier+ }+ if (!selected)+ WorkManager.getInstance(app).cancelUniqueWork(identifier).result.get()+ } catch (exception: Exception) {+ main.post { report(identifier, "failed", "schedule", exception.message) }+ }+ }+ }++ private fun report(+ identifier: String,+ outcome: String,+ reason: String? = null,+ error: String? = null,+ ) {+ val event =+ mapOf(+ "identifier" to identifier,+ "outcome" to outcome,+ "reason" to reason,+ "error" to error,+ )+ val fallback = {+ Log.w(TAG, "$identifier: $outcome (${reason ?: "task"})${error?.let { ": $it" } ?: ""}")+ Unit+ }+ observers.lastOrNull { it.observesOutcomes }?.report(event, fallback) ?: fallback()+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundWorker.kt b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundWorker.ktnew file mode 100644index 0000000000..dbda63a0a8--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/BackgroundWorker.kt@@ -0,0 +1,27 @@+package io.ente.background++import android.content.Context+import android.os.SystemClock+import androidx.concurrent.futures.CallbackToFutureAdapter+import androidx.work.ListenableWorker+import androidx.work.WorkerParameters+import com.google.common.util.concurrent.ListenableFuture++class BackgroundWorker(context: Context, parameters: WorkerParameters) :+ ListenableWorker(context, parameters) {+ override fun startWork(): ListenableFuture<Result> {+ val startedAt = SystemClock.elapsedRealtime()+ return CallbackToFutureAdapter.getFuture { completer ->+ BackgroundRuntime.start(this, startedAt) { successful ->+ if (!isStopped) {+ completer.set(if (successful) Result.success() else Result.failure())+ }+ }+ id.toString()+ }+ }++ override fun onStopped() {+ BackgroundRuntime.nativeStop(this)+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/TaskConfiguration.kt b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/TaskConfiguration.ktnew file mode 100644index 0000000000..0c8927985d--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/main/kotlin/io/ente/background/TaskConfiguration.kt@@ -0,0 +1,68 @@+package io.ente.background++import org.json.JSONObject++internal data class TaskConfiguration(+ val identifier: String,+ val kind: String,+ val frequencyMs: Long,+ val initialDelayMs: Long,+ val flexMs: Long?,+ val requiresNetwork: Boolean,+ val requiresCharging: Boolean,+ val requiresDeviceIdle: Boolean,+ val runBudgetMs: Long?,+ val foregroundStopTimeoutMs: Long?,+ val callbackHandle: Long,+) {+ fun encode(): String =+ JSONObject(+ mapOf(+ "identifier" to identifier,+ "kind" to kind,+ "frequencyMs" to frequencyMs,+ "initialDelayMs" to initialDelayMs,+ "flexMs" to flexMs,+ "requiresNetwork" to requiresNetwork,+ "requiresCharging" to requiresCharging,+ "requiresDeviceIdle" to requiresDeviceIdle,+ "runBudgetMs" to runBudgetMs,+ "foregroundStopTimeoutMs" to foregroundStopTimeoutMs,+ "callbackHandle" to callbackHandle,+ )+ )+ .toString()++ companion object {+ fun decode(+ json: JSONObject,+ callbackHandle: Long = json.getLong("callbackHandle"),+ ): TaskConfiguration {+ fun duration(key: String): Long? =+ if (json.isNull(key)) null else json.getLong(key).also { require(it >= 0) }++ val identifier = json.getString("identifier")+ val kind = json.getString("kind")+ val frequency = json.getLong("frequencyMs")+ val flex = duration("flexMs")+ require(identifier.isNotBlank())+ require(kind == "refresh" || kind == "processing")+ require(frequency >= 15 * 60 * 1000L)+ require(flex == null || flex in 5 * 60 * 1000L..frequency)+ require(callbackHandle != 0L)+ return TaskConfiguration(+ identifier,+ kind,+ frequency,+ duration("initialDelayMs") ?: 0,+ flex,+ json.optBoolean("requiresNetwork"),+ json.optBoolean("requiresCharging"),+ json.optBoolean("requiresDeviceIdle"),+ duration("runBudgetMs"),+ duration("foregroundStopTimeoutMs"),+ callbackHandle,+ )+ }+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/android/src/test/kotlin/io/ente/background/BackgroundRuntimeTest.kt b/mobile/apps/photos/plugins/ente_background_manager/android/src/test/kotlin/io/ente/background/BackgroundRuntimeTest.ktnew file mode 100644index 0000000000..f4d07a7556--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/android/src/test/kotlin/io/ente/background/BackgroundRuntimeTest.kt@@ -0,0 +1,332 @@+package io.ente.background++import android.app.Activity+import android.app.Application+import android.os.Looper+import androidx.work.Configuration+import androidx.work.Data+import androidx.work.ListenableWorker+import androidx.work.testing.TestListenableWorkerBuilder+import androidx.work.testing.WorkManagerTestInitHelper+import io.flutter.FlutterInjector+import io.flutter.embedding.engine.FlutterEngine+import io.flutter.embedding.engine.dart.DartExecutor+import io.flutter.embedding.engine.loader.FlutterLoader+import io.flutter.plugin.common.BinaryMessenger+import io.flutter.plugin.common.MethodCall+import io.flutter.plugin.common.MethodChannel+import io.flutter.plugin.common.StandardMethodCodec+import io.flutter.view.FlutterCallbackInformation+import java.nio.ByteBuffer+import java.time.Duration+import org.junit.Assert.*+import org.junit.Test+import org.junit.runner.RunWith+import org.mockito.ArgumentMatchers.*+import org.mockito.Mockito.*+import org.robolectric.Robolectric+import org.robolectric.RobolectricTestRunner+import org.robolectric.RuntimeEnvironment+import org.robolectric.Shadows.shadowOf+import org.robolectric.annotation.Config+import org.robolectric.annotation.LooperMode++@RunWith(RobolectricTestRunner::class)+@Config(sdk = [28])+@LooperMode(LooperMode.Mode.PAUSED)+class BackgroundRuntimeTest {+ private val app: Application+ get() = RuntimeEnvironment.getApplication()++ private val startups = ArrayDeque<Runnable>()+ private val engines = ArrayList<Pair<FlutterEngine, Messenger>>()+ private val main+ get() = shadowOf(Looper.getMainLooper())++ private fun policy(budget: Long? = null, grace: Long? = null) =+ TaskConfiguration(+ "test.refresh",+ "refresh",+ 900_000,+ 86_400_000,+ null,+ false,+ false,+ false,+ budget,+ grace,+ 1,+ )++ private fun configure(policy: TaskConfiguration, enabled: Boolean = true) {+ val data = org.json.JSONObject(policy.encode())+ val result = Reply()+ BackgroundRuntime.configure(+ mapOf(+ "enabled" to enabled,+ "callbackHandle" to 1L,+ "tasks" to+ listOf(+ data.keys().asSequence().associateWith { key ->+ data.get(key).takeUnless { it === org.json.JSONObject.NULL }+ }+ ),+ ),+ result,+ )+ val deadline = System.nanoTime() + 10_000_000_000L+ while (!result.done && System.nanoTime() < deadline) {+ main.idle()+ Thread.sleep(5)+ }+ assertTrue("Configuration did not finish", result.done)+ assertNull(result.error)+ }++ private fun worker(policy: TaskConfiguration): BackgroundWorker =+ TestListenableWorkerBuilder<BackgroundWorker>(app)+ .setInputData(Data.Builder().putString("task", policy.encode()).build())+ .build()++ private fun bootstrap(): Messenger {+ startups.removeFirst().run()+ return engines.last().second+ }++ private fun complete(messenger: Messenger, ready: Map<*, *>, outcome: String = "completed") {+ messenger.call("complete", mapOf("invocation" to ready["invocation"], "outcome" to outcome))+ }++ @Test+ fun lifecycleThroughNativeWorkerAndDartChannel() {+ WorkManagerTestInitHelper.initializeTestWorkManager(app, Configuration.Builder().build())+ BackgroundRuntime.install(app) { true }+ val loader = mock(FlutterLoader::class.java)+ doAnswer { invocation ->+ startups.add(invocation.getArgument(3))+ null+ }+ .`when`(loader)+ .ensureInitializationCompleteAsync(any(), isNull(), any(), any())+ `when`(loader.findAppBundlePath()).thenReturn("flutter_assets")+ FlutterInjector.setInstance(FlutterInjector.Builder().setFlutterLoader(loader).build())+ BackgroundRuntime.findCallback = { mock(FlutterCallbackInformation::class.java) }+ BackgroundRuntime.createEngine = {+ val engine = mock(FlutterEngine::class.java)+ val executor = mock(DartExecutor::class.java)+ val messenger = Messenger()+ `when`(engine.dartExecutor).thenReturn(executor)+ `when`(executor.binaryMessenger).thenReturn(messenger)+ engines.add(engine to messenger)+ engine+ }++ val cooperative = policy()+ configure(cooperative)+ val activity = Robolectric.buildActivity(Activity::class.java).create().start().resume()+ assertEquals(ListenableWorker.Result.success(), worker(cooperative).startWork().get())+ assertTrue(startups.isEmpty())+ assertTrue(engines.isEmpty())+ activity.pause().stop().destroy()++ val first = worker(cooperative).startWork()+ assertFalse(first.isDone)+ assertEquals(ListenableWorker.Result.success(), worker(cooperative).startWork().get())+ assertEquals(1, startups.size)+ val firstChannel = bootstrap()+ val firstReady = firstChannel.call("ready") as Map<*, *>+ assertNull(firstReady["stopReason"])+ doAnswer {+ assertEquals(+ ListenableWorker.Result.success(),+ worker(cooperative).startWork().get(),+ )+ null+ }+ .`when`(engines[0].first)+ .destroy()+ val stop = Reply()+ BackgroundRuntime.requestStop(stop)+ assertFalse(stop.done)+ assertEquals("requested", (firstChannel.sent.single().arguments as Map<*, *>)["reason"])+ assertEquals(ListenableWorker.Result.success(), worker(cooperative).startWork().get())+ assertFalse(stop.done)+ complete(firstChannel, firstReady)+ assertTrue(stop.done)+ assertEquals(ListenableWorker.Result.success(), first.get())+ verify(engines[0].first).destroy()+ val noRun = Reply()+ BackgroundRuntime.requestStop(noRun)+ assertTrue(noRun.done)+ val schedule = Reply()+ BackgroundRuntime.scheduledTasks(schedule)+ val scheduleDeadline = System.nanoTime() + 10_000_000_000L+ while (!schedule.done && System.nanoTime() < scheduleDeadline) {+ main.idle()+ Thread.sleep(5)+ }+ assertEquals(mapOf("test.refresh" to true), schedule.value)++ val budgetPolicy = policy(budget = 100)+ configure(budgetPolicy)+ val budgetRun = worker(budgetPolicy).startWork()+ main.idleFor(Duration.ofMillis(150))+ val budgetChannel = bootstrap()+ val budgetReady = budgetChannel.call("ready") as Map<*, *>+ assertEquals("budget", budgetReady["stopReason"])+ assertTrue((budgetReady["elapsedMs"] as Long) >= 150)+ assertFalse(budgetRun.isDone)+ main.idleFor(Duration.ofSeconds(1))+ verify(engines.last().first, never()).destroy()+ complete(budgetChannel, budgetReady)+ assertTrue(budgetRun.isDone)++ configure(cooperative)+ val stoppingDuringStartup = worker(cooperative).startWork()+ val foreground = Robolectric.buildActivity(Activity::class.java).create().start().resume()+ val stoppedChannel = bootstrap()+ val stoppedReady = stoppedChannel.call("ready") as Map<*, *>+ assertEquals("foreground", stoppedReady["stopReason"])+ foreground.pause().stop().destroy()+ main.idleFor(Duration.ofSeconds(2))+ assertFalse(stoppingDuringStartup.isDone)+ complete(stoppedChannel, stoppedReady)+ assertTrue(stoppingDuringStartup.isDone)++ val original = policy(grace = 500)+ configure(original)+ val forced = worker(original).startWork()+ val forcedChannel = bootstrap()+ val forcedReady = forcedChannel.call("ready") as Map<*, *>+ val foregroundAgain =+ Robolectric.buildActivity(Activity::class.java).create().start().resume()+ configure(policy(grace = 1))+ main.idleFor(Duration.ofMillis(200))+ assertFalse(forced.isDone)+ foregroundAgain.pause().stop().start().resume()+ main.idleFor(Duration.ofMillis(300))+ assertEquals(ListenableWorker.Result.failure(), forced.get())+ verify(engines.last().first).destroy()+ foregroundAgain.pause().stop().destroy()++ val updated = worker(policy(grace = 1)).startWork()+ val updatedChannel = bootstrap()+ val updatedReady = updatedChannel.call("ready") as Map<*, *>+ assertNotEquals(forcedReady["invocation"], updatedReady["invocation"])+ assertNull(+ forcedChannel.call(+ "complete",+ mapOf("invocation" to forcedReady["invocation"], "outcome" to "completed"),+ )+ )+ assertFalse(updated.isDone)+ BackgroundRuntime.foreground()+ main.idleFor(Duration.ofMillis(1))+ assertEquals(ListenableWorker.Result.failure(), updated.get())+ val clearForeground =+ Robolectric.buildActivity(Activity::class.java).create().start().resume()+ clearForeground.pause().stop().destroy()++ configure(cooperative)+ val interruptedWorker = worker(cooperative)+ val interrupted = interruptedWorker.startWork()+ val staleStartup = startups.removeFirst()+ interruptedWorker.onStopped()+ main.idle()+ assertTrue(interrupted.isDone)+ val replacement = worker(cooperative).startWork()+ val count = engines.size+ staleStartup.run()+ assertEquals(count, engines.size)+ val replacementChannel = bootstrap()+ val replacementReady = replacementChannel.call("ready") as Map<*, *>+ complete(replacementChannel, replacementReady)+ assertTrue(replacement.isDone)++ val immediatePolicy = policy(budget = 0, grace = 0)+ configure(immediatePolicy)+ val immediate = worker(immediatePolicy).startWork()+ main.idle()+ val immediateChannel = bootstrap()+ val immediateReady = immediateChannel.call("ready") as Map<*, *>+ assertEquals("budget", immediateReady["stopReason"])+ assertFalse(immediate.isDone)+ val immediateForeground =+ Robolectric.buildActivity(Activity::class.java).create().start().resume()+ main.idle()+ assertEquals(ListenableWorker.Result.failure(), immediate.get())+ immediateForeground.pause().stop().destroy()++ configure(cooperative)+ BackgroundRuntime.findCallback = { null }+ val failed = worker(cooperative).startWork()+ startups.removeFirst().run()+ assertEquals(ListenableWorker.Result.failure(), failed.get())+ BackgroundRuntime.findCallback = { mock(FlutterCallbackInformation::class.java) }+ val last = worker(cooperative).startWork()+ val lastChannel = bootstrap()+ val lastReady = lastChannel.call("ready") as Map<*, *>+ configure(cooperative, enabled = false)+ assertFalse(last.isDone)+ assertEquals("requested", (lastChannel.sent.single().arguments as Map<*, *>)["reason"])+ complete(lastChannel, lastReady)+ assertTrue(last.isDone)+ }++ private class Reply : MethodChannel.Result {+ var done = false+ var error: String? = null+ var value: Any? = null++ override fun success(result: Any?) {+ value = result+ done = true+ }++ override fun error(code: String, message: String?, details: Any?) {+ error = "$code: $message"+ done = true+ }++ override fun notImplemented() {+ error = "notImplemented"+ done = true+ }+ }++ private class Messenger : BinaryMessenger {+ private val codec = StandardMethodCodec.INSTANCE+ private var handler: BinaryMessenger.BinaryMessageHandler? = null+ val sent = ArrayList<MethodCall>()++ override fun send(channel: String, message: ByteBuffer?) = send(channel, message, null)++ override fun send(+ channel: String,+ message: ByteBuffer?,+ callback: BinaryMessenger.BinaryReply?,+ ) {+ message?.flip()+ sent.add(codec.decodeMethodCall(requireNotNull(message)))+ callback?.reply(codec.encodeSuccessEnvelope(null).also { it.flip() })+ }++ override fun setMessageHandler(+ channel: String,+ handler: BinaryMessenger.BinaryMessageHandler?,+ ) {+ this.handler = handler+ }++ fun call(method: String, arguments: Any? = null): Any? {+ var reply: Any? = null+ handler?.onMessage(+ codec.encodeMethodCall(MethodCall(method, arguments)).also { it.flip() }+ ) { encoded ->+ encoded?.flip()+ reply = codec.decodeEnvelope(requireNotNull(encoded))+ }+ return reply+ }+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundManagerPlugin.swift b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundManagerPlugin.swiftnew file mode 100644index 0000000000..329d93656b--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundManagerPlugin.swift@@ -0,0 +1,67 @@+@preconcurrency import Flutter+import UIKit++@MainActor+public final class BackgroundManagerPlugin: NSObject, @preconcurrency FlutterPlugin {+ private let channel: FlutterMethodChannel+ private var observesOutcomes = false++ private init(registrar: FlutterPluginRegistrar) {+ channel = FlutterMethodChannel(+ name: "io.ente.background/control",+ binaryMessenger: registrar.messenger()+ )+ super.init()+ }++ public static func register(with registrar: FlutterPluginRegistrar) {+ let instance = BackgroundManagerPlugin(registrar: registrar)+ registrar.addMethodCallDelegate(instance, channel: instance.channel)+ registrar.publish(instance)+ BackgroundRuntime.shared.attach(instance)+ }++ public func detachFromEngine(for registrar: FlutterPluginRegistrar) {+ observesOutcomes = false+ BackgroundRuntime.shared.detach(self)+ channel.setMethodCallHandler(nil)+ }++ public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {+ switch call.method {+ case "configure":+ observesOutcomes = true+ BackgroundRuntime.shared.configure(call.arguments as? [String: Any], result: result)+ case "stopActiveRun":+ BackgroundRuntime.shared.requestStop(result: result)+ case "scheduledTasks":+ BackgroundRuntime.shared.scheduledTasks(result)+ default:+ result(FlutterMethodNotImplemented)+ }+ }++ var canReport: Bool { observesOutcomes }++ func report(_ event: [String: Any], fallback: @escaping () -> Void) {+ guard observesOutcomes else {+ fallback()+ return+ }+ channel.invokeMethod("outcome", arguments: event) { response in+ if (response as? Bool) != true { fallback() }+ }+ }++ public static func install(+ isEnabled: @escaping () -> Bool,+ registrant: @escaping (FlutterPluginRegistry) -> Void+ ) {+ BackgroundRuntime.shared.install(isEnabled: isEnabled, registrant: registrant)+ }++ @discardableResult+ public static func registerTask(identifier: String, processing: Bool) -> Bool {+ BackgroundRuntime.shared.register(identifier: identifier, processing: processing)+ }+}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.swiftnew file mode 100644index 0000000000..d6db889ff2--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/BackgroundRuntime.swift@@ -0,0 +1,382 @@+import BackgroundTasks+@preconcurrency import Flutter+import Foundation+import UIKit+import os++@MainActor+final class BackgroundRuntime: NSObject {+ static let shared = BackgroundRuntime()+ private static let logger = Logger(subsystem: "io.ente.background", category: "BackgroundManager")+ private var configuration = StoredConfiguration.load()+ private var isAllowed: () -> Bool = { false }+ private var registrant: ((FlutterPluginRegistry) -> Void)?+ private let observers = NSHashTable<BackgroundManagerPlugin>.weakObjects()+ private var registrations: [String: Bool] = [:]+ private var active: Run?+ private var isForeground = false+ private var installed = false+ private var reconciling = false+ private var needsRearm = Set<String>()+ private var changedTasks = Set<String>()+ private var configurationResults: [FlutterResult] = []++ private final class Run {+ let task: BGTask+ let configuration: TaskConfiguration+ let startedAt: TimeInterval+ let invocation = UUID().uuidString+ var engine: FlutterEngine?+ var channel: FlutterMethodChannel?+ var ready = false+ var retiring = false+ var stopReason: String?+ var budgetTimer: DispatchWorkItem?+ var foregroundTimer: DispatchWorkItem?+ var stopResults: [FlutterResult] = []++ init(task: BGTask, configuration: TaskConfiguration, startedAt: TimeInterval) {+ self.task = task+ self.configuration = configuration+ self.startedAt = startedAt+ }+ }++ func install(+ isEnabled: @escaping () -> Bool,+ registrant: @escaping (FlutterPluginRegistry) -> Void+ ) {+ isAllowed = isEnabled+ self.registrant = registrant+ guard !installed else { return }+ installed = true+ isForeground = UIApplication.shared.applicationState == .active+ let center = NotificationCenter.default+ center.addObserver(+ self, selector: #selector(foreground), name: UIApplication.willEnterForegroundNotification,+ object: nil)+ center.addObserver(+ self, selector: #selector(foreground), name: UIApplication.didBecomeActiveNotification,+ object: nil)+ center.addObserver(+ self, selector: #selector(background), name: UIApplication.didEnterBackgroundNotification,+ object: nil)+ }++ func register(identifier: String, processing: Bool) -> Bool {+ if let existing = registrations[identifier] { return existing == processing }+ let registered = BGTaskScheduler.shared.register(+ forTaskWithIdentifier: identifier, using: .main+ ) { task in+ let startedAt = ProcessInfo.processInfo.systemUptime+ MainActor.assumeIsolated {+ self.deliver(task, startedAt: startedAt)+ }+ }+ if registered {+ registrations[identifier] = processing+ } else {+ report(identifier: identifier, outcome: "failed", reason: "registration")+ }+ return registered+ }++ func attach(_ plugin: BackgroundManagerPlugin) {+ observers.add(plugin)+ }++ func detach(_ plugin: BackgroundManagerPlugin) {+ observers.remove(plugin)+ }++ @objc private func foreground() {+ isForeground = true+ if let run = active { stop(run, reason: "foreground") }+ }++ @objc private func background() {+ isForeground = false+ }++ func requestStop(result: FlutterResult? = nil) {+ guard let run = active else {+ result?(nil)+ return+ }+ if let result { run.stopResults.append(result) }+ stop(run, reason: "requested")+ }++ func configure(_ data: [String: Any]?, result: @escaping FlutterResult) {+ guard let data, let callback = data["callbackHandle"] as? NSNumber,+ let tasks = data["tasks"] as? [[String: Any]], let enabled = data["enabled"] as? Bool,+ installed+ else {+ result(+ FlutterError(+ code: "configuration", message: "Background manager was not installed at launch",+ details: nil))+ return+ }+ do {+ let parsed = try tasks.map { try TaskConfiguration($0, callbackHandle: callback.int64Value) }+ guard Set(parsed.map(\.identifier)).count == parsed.count else {+ throw TaskConfiguration.ConfigurationError.duplicateIdentifier+ }+ for task in parsed {+ guard registrations[task.identifier] == (task.kind == "processing") else {+ throw TaskConfiguration.ConfigurationError.unregisteredIdentifier+ }+ if !configuration.tasks.contains(task) { changedTasks.insert(task.identifier) }+ }+ let next = StoredConfiguration(enabled: enabled, tasks: parsed)+ try next.save()+ configuration = next+ if !enabled { requestStop() }+ configurationResults.append(result)+ reconcile()+ } catch {+ result(FlutterError(code: "configuration", message: String(describing: error), details: nil))+ }+ }++ private func reconcile() {+ guard !reconciling else { return }+ reconciling = true+ BGTaskScheduler.shared.getPendingTaskRequests { requests in+ DispatchQueue.main.async {+ let pending = Dictionary(+ requests.map { ($0.identifier, $0) }, uniquingKeysWith: { first, _ in first })+ let enabled = self.configuration.enabled && self.isAllowed()+ let desired = enabled ? self.configuration.tasks : []+ let identifiers = Set(desired.map(\.identifier))+ for identifier in self.registrations.keys where !identifiers.contains(identifier) {+ BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: identifier)+ }+ var failure: Error?+ for task in desired {+ let rearming = self.needsRearm.contains(task.identifier)+ if pending[task.identifier] != nil && !rearming+ && !self.changedTasks.contains(task.identifier)+ {+ continue+ }+ let request: BGTaskRequest+ if task.kind == "processing" {+ let processing = BGProcessingTaskRequest(identifier: task.identifier)+ processing.requiresNetworkConnectivity = task.requiresNetwork+ processing.requiresExternalPower = task.requiresCharging+ request = processing+ } else {+ request = BGAppRefreshTaskRequest(identifier: task.identifier)+ }+ let delay = rearming ? task.frequencyMs : task.initialDelayMs+ request.earliestBeginDate = Date(timeIntervalSinceNow: Double(delay) / 1000)+ do {+ try BGTaskScheduler.shared.submit(request)+ } catch {+ failure = error+ self.report(+ identifier: task.identifier, outcome: "failed", reason: "schedule",+ error: String(describing: error))+ }+ }+ self.changedTasks.removeAll()+ self.needsRearm.removeAll()+ self.reconciling = false+ let results = self.configurationResults+ self.configurationResults.removeAll()+ for result in results {+ if let failure {+ result(+ FlutterError(code: "schedule", message: String(describing: failure), details: nil))+ } else {+ result(nil)+ }+ }+ }+ }+ }++ func scheduledTasks(_ result: @escaping FlutterResult) {+ BGTaskScheduler.shared.getPendingTaskRequests { requests in+ DispatchQueue.main.async {+ let pending = Set(requests.map(\.identifier))+ result(+ Dictionary(+ uniqueKeysWithValues: self.configuration.tasks.map {+ ($0.identifier, pending.contains($0.identifier))+ }))+ }+ }+ }++ private func deliver(_ task: BGTask, startedAt: TimeInterval) {+ guard configuration.enabled, isAllowed(),+ let policy = configuration.tasks.first(where: { $0.identifier == task.identifier })+ else {+ BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: task.identifier)+ report(identifier: task.identifier, outcome: "skipped", reason: "disabled")+ task.setTaskCompleted(success: true)+ return+ }+ needsRearm.insert(task.identifier)+ reconcile()+ let skip: String?+ if active != nil {+ skip = "busy"+ } else if isForeground || UIApplication.shared.applicationState != .background {+ skip = "foreground"+ } else {+ skip = nil+ }+ if let skip {+ report(identifier: task.identifier, outcome: "skipped", reason: skip)+ task.setTaskCompleted(success: true)+ return+ }+ let run = Run(task: task, configuration: policy, startedAt: startedAt)+ active = run+ task.expirationHandler = { [weak run] in+ DispatchQueue.main.async {+ guard let run, self.active === run else { return }+ self.stop(run, reason: "system")+ self.retire(run, outcome: "stopped", reason: "expired", success: false)+ }+ }+ if let budget = policy.runBudgetMs {+ let timer = DispatchWorkItem { [weak run] in+ guard let run, self.active === run else { return }+ self.stop(run, reason: "budget")+ }+ run.budgetTimer = timer+ DispatchQueue.main.asyncAfter(+ deadline: .now() + Double(max(0, budget - elapsed(run))) / 1000, execute: timer)+ }+ guard let callback = FlutterCallbackCache.lookupCallbackInformation(policy.callbackHandle),+ let registrant+ else {+ retire(+ run, outcome: "failed", reason: "bootstrap", error: "Background dispatcher is unavailable")+ return+ }+ let engine = FlutterEngine(+ name: "ente-background-\(run.invocation)", project: nil, allowHeadlessExecution: true)+ run.engine = engine+ let channel = FlutterMethodChannel(+ name: "io.ente.background/worker", binaryMessenger: engine.binaryMessenger)+ run.channel = channel+ channel.setMethodCallHandler { [weak run] call, result in+ guard let run, self.active === run, !run.retiring else {+ result(nil)+ return+ }+ switch call.method {+ case "ready":+ guard !run.ready else {+ result(+ FlutterError(code: "bootstrap", message: "Dispatcher already started", details: nil))+ return+ }+ run.ready = true+ var data: [String: Any] = [+ "identifier": policy.identifier,+ "invocation": run.invocation,+ "elapsedMs": self.elapsed(run),+ ]+ if let budget = policy.runBudgetMs { data["runBudgetMs"] = budget }+ if let reason = run.stopReason { data["stopReason"] = reason }+ result(data)+ case "complete":+ guard let data = call.arguments as? [String: Any],+ data["invocation"] as? String == run.invocation,+ let outcome = data["outcome"] as? String,+ ["completed", "skipped", "stopped", "failed"].contains(outcome)+ else {+ result(+ FlutterError(code: "completion", message: "Invalid background completion", details: nil)+ )+ return+ }+ result(nil)+ self.retire(run, outcome: outcome, reason: run.stopReason, error: data["error"] as? String)+ default:+ result(FlutterMethodNotImplemented)+ }+ }+ guard+ engine.run(withEntrypoint: callback.callbackName, libraryURI: callback.callbackLibraryPath)+ else {+ retire(run, outcome: "failed", reason: "bootstrap", error: "Flutter engine failed to start")+ return+ }+ registrant(engine)+ }++ private func elapsed(_ run: Run) -> Int64 {+ Int64(max(0, ProcessInfo.processInfo.systemUptime - run.startedAt) * 1000)+ }++ private func stop(_ run: Run, reason: String) {+ guard active === run, !run.retiring else { return }+ if run.stopReason == nil {+ run.stopReason = reason+ if run.ready {+ run.channel?.invokeMethod(+ "stop", arguments: ["invocation": run.invocation, "reason": reason])+ }+ }+ if reason == "foreground", run.foregroundTimer == nil,+ let grace = run.configuration.foregroundStopTimeoutMs+ {+ let timer = DispatchWorkItem { [weak run] in+ guard let run, self.active === run else { return }+ self.retire(run, outcome: "forcedTeardown", reason: "foreground")+ }+ run.foregroundTimer = timer+ DispatchQueue.main.asyncAfter(deadline: .now() + Double(grace) / 1000, execute: timer)+ }+ }++ private func retire(+ _ run: Run, outcome: String, reason: String? = nil, error: String? = nil, success: Bool? = nil+ ) {+ guard active === run, !run.retiring else { return }+ run.retiring = true+ run.budgetTimer?.cancel()+ run.foregroundTimer?.cancel()+ run.task.expirationHandler = nil+ let terminal = outcome == "completed" && run.stopReason != nil ? "stopped" : outcome+ run.channel?.setMethodCallHandler(nil)+ run.engine?.destroyContext()+ run.channel = nil+ run.engine = nil+ run.task.setTaskCompleted(+ success: success ?? (terminal != "failed" && terminal != "forcedTeardown"))+ active = nil+ if terminal != "completed" {+ report(+ identifier: run.configuration.identifier, outcome: terminal, reason: reason, error: error)+ }+ for result in run.stopResults { result(nil) }+ run.stopResults.removeAll()+ }++ private func report(+ identifier: String, outcome: String, reason: String? = nil, error: String? = nil+ ) {+ var event: [String: Any] = ["identifier": identifier, "outcome": outcome]+ if let reason { event["reason"] = reason }+ if let error { event["error"] = error }+ let fallback = {+ Self.logger.warning(+ "\(identifier, privacy: .public): \(outcome, privacy: .public) (\(reason ?? "task", privacy: .public)) \(error ?? "", privacy: .public)"+ )+ }+ if let observer = observers.allObjects.last(where: \.canReport) {+ observer.report(event, fallback: fallback)+ } else {+ fallback()+ }+ }+}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.swiftnew file mode 100644index 0000000000..34f583b14a--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/Classes/TaskConfiguration.swift@@ -0,0 +1,73 @@+import Foundation++struct TaskConfiguration: Codable, Equatable {+ let identifier: String+ let kind: String+ let frequencyMs: Int64+ let initialDelayMs: Int64+ let flexMs: Int64?+ let requiresNetwork: Bool+ let requiresCharging: Bool+ let requiresDeviceIdle: Bool+ let runBudgetMs: Int64?+ let foregroundStopTimeoutMs: Int64?+ let callbackHandle: Int64++ 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),+ let frequency = data["frequencyMs"] as? NSNumber, frequency.int64Value > 0,+ callbackHandle != 0+ else {+ throw ConfigurationError.invalidTask+ }+ self.identifier = identifier+ self.kind = kind+ self.frequencyMs = frequency.int64Value+ self.initialDelayMs = (data["initialDelayMs"] as? NSNumber)?.int64Value ?? 0+ self.flexMs = (data["flexMs"] as? NSNumber)?.int64Value+ self.requiresNetwork = data["requiresNetwork"] as? Bool ?? false+ self.requiresCharging = data["requiresCharging"] as? Bool ?? false+ self.requiresDeviceIdle = data["requiresDeviceIdle"] as? Bool ?? false+ self.runBudgetMs = (data["runBudgetMs"] as? NSNumber)?.int64Value+ self.foregroundStopTimeoutMs = (data["foregroundStopTimeoutMs"] as? NSNumber)?.int64Value+ self.callbackHandle = callbackHandle+ guard+ [initialDelayMs, flexMs, runBudgetMs, foregroundStopTimeoutMs]+ .compactMap({ $0 }).allSatisfy({ $0 >= 0 })+ else {+ throw ConfigurationError.invalidDuration+ }+ guard flexMs == nil, !requiresDeviceIdle,+ kind == "processing" || (!requiresNetwork && !requiresCharging)+ else {+ throw ConfigurationError.unsupportedConstraint+ }+ }++ enum ConfigurationError: Error {+ case invalidTask+ case invalidDuration+ case unsupportedConstraint+ case unregisteredIdentifier+ case duplicateIdentifier+ }+}++struct StoredConfiguration: Codable {+ var enabled: Bool+ var tasks: [TaskConfiguration]++ static func load() -> StoredConfiguration {+ guard let data = UserDefaults.standard.data(forKey: "ente_background_manager"),+ let value = try? JSONDecoder().decode(StoredConfiguration.self, from: data)+ else {+ return StoredConfiguration(enabled: false, tasks: [])+ }+ return value+ }++ func save() throws {+ UserDefaults.standard.set(try JSONEncoder().encode(self), forKey: "ente_background_manager")+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/ios/ente_background_manager.podspec b/mobile/apps/photos/plugins/ente_background_manager/ios/ente_background_manager.podspecnew file mode 100644index 0000000000..3fda673506--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/ios/ente_background_manager.podspec@@ -0,0 +1,15 @@+Pod::Spec.new do |s|+ s.name = 'ente_background_manager'+ s.version = '0.0.1'+ s.summary = 'Native background scheduling and headless task lifecycle.'+ s.homepage = 'https://ente.com'+ s.license = { :type => 'AGPL-3.0-only' }+ s.author = { 'Ente' => '[email protected]' }+ s.source = { :path => '.' }+ s.source_files = 'Classes/**/*'+ s.dependency 'Flutter'+ s.platform = :ios, '15.1'+ s.swift_version = '5.0'+ s.frameworks = 'BackgroundTasks'+ s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }+enddiff --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.dartnew file mode 100644index 0000000000..69cadc55e3--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/lib/ente_background_manager.dart@@ -0,0 +1,215 @@+import "dart:async";+import "dart:ui";++import "package:flutter/services.dart";+import "package:flutter/widgets.dart";++enum BackgroundTaskKind { refresh, processing }++enum BackgroundStopReason { foreground, budget, requested, system }++enum BackgroundTaskResult { completed, skipped, stopped, failed }++class BackgroundTaskConfig {+ const BackgroundTaskConfig({+ required this.identifier,+ required this.kind,+ required this.frequency,+ this.initialDelay = Duration.zero,+ this.flexInterval,+ this.requiresNetwork = false,+ this.requiresCharging = false,+ this.requiresDeviceIdle = false,+ this.runBudget,+ this.foregroundStopTimeout,+ });++ final String identifier;+ final BackgroundTaskKind kind;+ final Duration frequency;+ final Duration initialDelay;+ final Duration? flexInterval;+ final bool requiresNetwork;+ final bool requiresCharging;+ final bool requiresDeviceIdle;+ final Duration? runBudget;+ final Duration? foregroundStopTimeout;++ Map<String, Object> _encode() {+ if (identifier.isEmpty || frequency <= Duration.zero) {+ throw ArgumentError("A task needs an identifier and positive frequency");+ }+ for (final duration in [+ initialDelay,+ flexInterval,+ runBudget,+ foregroundStopTimeout,+ ]) {+ if (duration != null && duration.isNegative) {+ throw ArgumentError("Task durations cannot be negative");+ }+ }+ return {+ "identifier": identifier,+ "kind": kind.name,+ "frequencyMs": frequency.inMilliseconds,+ "initialDelayMs": initialDelay.inMilliseconds,+ "requiresNetwork": requiresNetwork,+ "requiresCharging": requiresCharging,+ "requiresDeviceIdle": requiresDeviceIdle,+ if (flexInterval != null) "flexMs": flexInterval!.inMilliseconds,+ if (runBudget != null) "runBudgetMs": runBudget!.inMilliseconds,+ if (foregroundStopTimeout != null)+ "foregroundStopTimeoutMs": foregroundStopTimeout!.inMilliseconds,+ };+ }+}++class BackgroundTask {+ BackgroundTask._(Map<Object?, Object?> data)+ : identifier = data["identifier"]! as String,+ _invocation = data["invocation"]! as String,+ _startupElapsed = Duration(milliseconds: data["elapsedMs"]! as int),+ runBudget = data["runBudgetMs"] == null+ ? null+ : Duration(milliseconds: data["runBudgetMs"]! as int) {+ final reason = data["stopReason"] as String?;+ if (reason != null) _stop(reason);+ }++ final String identifier;+ final Duration? runBudget;+ final String _invocation;+ final Duration _startupElapsed;+ final Stopwatch _clock = Stopwatch()..start();+ final Completer<BackgroundStopReason> _stopped = Completer();+ BackgroundStopReason? _stopReason;++ Duration get elapsed => _startupElapsed + _clock.elapsed;+ Duration? get remainingBudget {+ final budget = runBudget;+ if (budget == null) return null;+ final remaining = budget - elapsed;+ return remaining.isNegative ? Duration.zero : remaining;+ }++ bool get isStopping => _stopReason != null;+ BackgroundStopReason? get stopReason => _stopReason;+ Future<BackgroundStopReason> get stopped => _stopped.future;++ void throwIfStopping() {+ if (isStopping) throw const BackgroundTaskStopped();+ }++ void _stop(String reason) {+ if (isStopping) return;+ _stopReason = BackgroundStopReason.values.byName(reason);+ _stopped.complete(_stopReason);+ }+}++class BackgroundTaskStopped implements Exception {+ const BackgroundTaskStopped();+}++class BackgroundTaskOutcome {+ BackgroundTaskOutcome._(Map<Object?, Object?> data)+ : identifier = data["identifier"]! as String,+ outcome = data["outcome"]! as String,+ reason = data["reason"] as String?,+ error = data["error"] as String?;++ final String identifier;+ final String outcome;+ final String? reason;+ final String? error;+}++class BackgroundManager {+ static const _control = MethodChannel("io.ente.background/control");+ static const _worker = MethodChannel("io.ente.background/worker");++ static Future<void> configure({+ required void Function() dispatcher,+ required List<BackgroundTaskConfig> tasks,+ required bool enabled,+ required FutureOr<void> Function(BackgroundTaskOutcome) onOutcome,+ }) async {+ final callback = PluginUtilities.getCallbackHandle(dispatcher);+ if (callback == null) {+ throw ArgumentError(+ "The dispatcher must be a retained top-level function",+ );+ }+ final identifiers = tasks.map((task) => task.identifier).toSet();+ if (identifiers.length != tasks.length) {+ throw ArgumentError("Task identifiers must be unique");+ }+ final encoded = tasks.map((task) => task._encode()).toList();+ _control.setMethodCallHandler((call) async {+ if (call.method != "outcome") throw MissingPluginException();+ await onOutcome(+ BackgroundTaskOutcome._(call.arguments as Map<Object?, Object?>),+ );+ return true;+ });+ await _control.invokeMethod<void>("configure", {+ "callbackHandle": callback.toRawHandle(),+ "tasks": encoded,+ "enabled": enabled,+ });+ }++ static Future<void> stopActiveRun() =>+ _control.invokeMethod<void>("stopActiveRun");++ static Future<Map<String, bool>> scheduledTasks() async {+ final result = await _control.invokeMapMethod<String, bool>(+ "scheduledTasks",+ );+ return result ?? {};+ }++ static Future<void> executeTask(+ Future<BackgroundTaskResult> Function(BackgroundTask) executor,+ ) async {+ WidgetsFlutterBinding.ensureInitialized();+ BackgroundTask? task;+ final pendingStops = <String, String>{};+ _worker.setMethodCallHandler((call) async {+ if (call.method != "stop") throw MissingPluginException();+ final data = call.arguments as Map<Object?, Object?>;+ final invocation = data["invocation"]! as String;+ final reason = data["reason"]! as String;+ final current = task;+ if (current == null) {+ pendingStops.putIfAbsent(invocation, () => reason);+ } else if (current._invocation == invocation) {+ current._stop(reason);+ }+ });+ final data = await _worker.invokeMapMethod<Object?, Object?>("ready");+ if (data == null) return;+ final current = BackgroundTask._(data);+ task = current;+ final pendingStop = pendingStops[current._invocation];+ if (pendingStop != null) current._stop(pendingStop);+ pendingStops.clear();+ var result = BackgroundTaskResult.stopped;+ String? error;+ try {+ current.throwIfStopping();+ result = await executor(current);+ } on BackgroundTaskStopped {+ result = BackgroundTaskResult.stopped;+ } catch (exception) {+ result = BackgroundTaskResult.failed;+ error = exception.runtimeType.toString();+ }+ await _worker.invokeMethod<void>("complete", {+ "invocation": current._invocation,+ "outcome": result.name,+ "error": ?error,+ });+ }+}diff --git a/mobile/apps/photos/plugins/ente_background_manager/pubspec.yaml b/mobile/apps/photos/plugins/ente_background_manager/pubspec.yamlnew file mode 100644index 0000000000..fb1fa4f4f8--- /dev/null+++ b/mobile/apps/photos/plugins/ente_background_manager/pubspec.yaml@@ -0,0 +1,27 @@+name: ente_background_manager+description: Native scheduling and headless task lifecycle for Ente Photos.+version: 0.0.1+publish_to: none+resolution: workspace++environment:+ sdk: ">=3.10.0 <4.0.0"+ flutter: ">=3.38.0"++dependencies:+ flutter:+ sdk: flutter++dev_dependencies:+ flutter_test:+ sdk: flutter+ flutter_lints: 6.0.0++flutter:+ plugin:+ platforms:+ android:+ package: io.ente.background+ pluginClass: BackgroundManagerPlugin+ ios:+ pluginClass: BackgroundManagerPlugindiff --git a/mobile/pubspec.yaml b/mobile/pubspec.yamlindex 4e02bc9c72..0e507063f7 100644--- a/mobile/pubspec.yaml+++ b/mobile/pubspec.yaml@@ -16,6 +16,7 @@ workspace:- apps/auth- apps/locker- apps/photos+ - apps/photos/plugins/ente_background_manager- apps/photos/plugins/ente_cast- apps/photos/plugins/ente_crypto- apps/photos/plugins/ente_panorama_viewer