Background task scheduling for Kotlin Multiplatform — including the parts iOS makes hard.

Installation

// build.gradle.kts
commonMain.dependencies {
    implementation("dev.brewkits:kmpworkmanager:3.5.0")          // core engine (no Ktor)
    // Optional — only if you use the built-in HTTP workers (Http*/ParallelHttp*).
    implementation("dev.brewkits:kmpworkmanager-http:3.5.0")     // Ktor 3 HTTP workers
}

Ktor 3 required only for kmpworkmanager-http (since v3.0.0). The core artifact no longer depends on Ktor at all. The HTTP workers live in kmpworkmanager-http, which needs Ktor 3.1.x. Because Ktor 2 and Ktor 3 share the same Maven coordinates and are binary-incompatible, an app still on Ktor 2 cannot mix them — if your project is not yet on Ktor 3, pin dev.brewkits:kmpworkmanager:2.5.1 until you migrate. See docs/MIGRATION_V3.0.0.md.

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        KmpWorkManager.initialize(
            context = this,
            workerFactory = AppWorkerFactory() // Must implement AndroidWorkerFactory
        )
    }
}

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    override init() {
        super.init()
        // Expose these from Kotlin, e.g. in a Setup.kt:
        //   fun initKmpWorkManager() =
        //       KmpWorkManager.initialize(workerFactory = IosWorkerFactoryGenerated())
        //   fun kmpChainExecutor() = KmpWorkManager.getInstance().chainExecutor
        SetupKt.initKmpWorkManager()
    }

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        BGTaskScheduler.shared.register(
            forTaskWithIdentifier: "kmp_chain_executor_task",
            using: nil
        ) { task in
            IosBackgroundTaskHandler.shared.handleChainExecutorTask(
                task: task,
                chainExecutor: SetupKt.kmpChainExecutor()
            )
        }
        return true
    }
}

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>kmp_chain_executor_task</string>
    <!-- Add other worker bgTaskIds here -->
</array>

Quick start

Schedule a task

// One-time — runs as soon as constraints are met
scheduler.enqueue(
    id              = "nightly-sync",
    trigger         = TaskTrigger.OneTime(initialDelayMs = 0),
    workerClassName = "SyncWorker",
    constraints     = Constraints(requiresNetwork = true)
)

// Periodic — every 15 minutes
scheduler.enqueue(
    id              = "heartbeat",
    trigger         = TaskTrigger.Periodic(intervalMs = 15 * 60 * 1000L),
    workerClassName = "SyncWorker"
)

Define a worker

You can implement background logic in your commonMain code, but KMP WorkManager expects platform-specific factory registration. We recommend using kmpworker-ksp to auto-generate this boilerplate.

// commonMain — shared logic
class SyncWorker : Worker {
    override suspend fun doWork(input: String?, env: WorkerEnvironment): WorkerResult {
        val items = api.fetchPendingItems()
        database.upsert(items)
        return WorkerResult.Success("Synced ${items.size} items")
    }
}

// androidMain
import dev.brewkits.kmpworkmanager.annotations.Worker

@Worker(name = "SyncWorker")
class SyncWorkerAndroid : AndroidWorker {
    override suspend fun doWork(input: String?, env: WorkerEnvironment) =
        SyncWorker().doWork(input, env)
}

// iosMain
import dev.brewkits.kmpworkmanager.annotations.Worker

@Worker(name = "SyncWorker", bgTaskId = "sync_task")
class SyncWorkerIos : IosWorker {
    override suspend fun doWork(input: String?, env: WorkerEnvironment) =
        SyncWorker().doWork(input, env)
}

The name argument must match the workerClassName you pass to scheduler.enqueue(...) ("SyncWorker" above). Set it explicitly so ProGuard/R8 rename of the wrapper class doesn't break factory lookup.

Note: Use AndroidWorkerFactoryGenerated() and IosWorkerFactoryGenerated() in your DI/Initialization if you use KSP. Otherwise, manually implement AndroidWorkerFactory and IosWorkerFactory.

Chain tasks

// Multi-step workflows that survive process death.
// If step 47 of 100 was running when iOS killed the app —
// the next BGTask invocation resumes at step 47, not step 0. scheduler.beginWith(TaskRequest("DownloadWorker", inputJson = """{"url":"$fileUrl"}"""))
    .then(TaskRequest("ValidateWorker"))
    .then(TaskRequest("TranscodeWorker"))
    .then(TaskRequest("UploadWorker", inputJson = """{"bucket":"processed"}"""))
    .withId("transcode-pipeline", policy = ExistingPolicy.KEEP)
    .enqueue()

Pass data between chain steps

Set mergeOutputFromPreviousStep = true and a step receives the previous step's WorkerResult.Success.data merged into its own inputJson — no external store needed. On a key collision the previous step's value wins, matching WorkManager's default OverwritingInputMerger. Both platforms behave identically.

scheduler.beginWith(TaskRequest("DownloadWorker", inputJson = """{"url":"$fileUrl"}"""))
    // DownloadWorker returns Success(data = {"filePath": "/tmp/x.zip"})
    .then(TaskRequest("ValidateWorker", mergeOutputFromPreviousStep = true))  // sees filePath
    .then(TaskRequest("UploadWorker", mergeOutputFromPreviousStep = true))    // sees filePath
    .enqueue()

Cancel a group of tasks

Tags are business-context labels, independent of worker class — one call cancels a mixed set of workers. Works for standalone tasks and chain steps alike.

scheduler.enqueue(
    id = "sync-profile",
    trigger = TaskTrigger.OneTime(),
    workerClassName = "SyncWorker",
    tags = setOf("user-123"),
)
scheduler.beginWith(TaskRequest("UploadWorker", tags = setOf("user-123"))).enqueue()

// Cancels both, whatever worker they use:
scheduler.cancelByTag("user-123")

// Or cancel every task of one worker type:
scheduler.cancelByWorkerClass("SyncWorker")

cancelByTag does not cover TaskTrigger.Exact on Android — exact alarms run through AlarmManager, which is not tag-indexed. Cancel those by id.

Skip work that has gone stale

deadlineMs marks the point after which running the task is worse than not running it. A task that has not started by then is skipped (recorded as ExecutionStatus.SKIPPED) and never retried — retrying cannot un-miss a deadline. A skipped step does not abort the rest of its chain.

scheduler.enqueue(
    id = "pre-flight-sync",
    trigger = TaskTrigger.OneTime(),
    workerClassName = "SyncWorker",
    deadlineMs = departureTimeMs,  // pointless to sync after the flight leaves
)

This is what finally makes TaskTrigger.Windowed(earliest, latest) enforceable on iOS: latest is now honoured as a deadline at execution time, where BGTaskScheduler itself offers no ceiling.

Why KMP WorkManager?

Most KMP libraries wrap the happy path — iOS BGTaskScheduler is not just "a different API." It has a credit system that punishes apps overrunning their time budget, an opaque scheduling policy, and no recovery mechanism for incomplete work. Getting it wrong means your tasks silently stop running.

Triggers

What's new in v3.4.0

Jetpack WorkManager parity. Four features native WorkManager users expect, now on both platforms: task tags + group cancellation (cancelByTag / cancelByWorkerClass), per-task deadlines (deadlineMs — skip rather than run stale work), the chain InputMerger (mergeOutputFromPreviousStep — pass a step's output into the next step's input), and ExistingPolicy.UPDATE (change a periodic task's constraints without resetting its interval timer). See the sections above for usage.

Adding cancelByTag/cancelByWorkerClass to BackgroundTaskScheduler is source-compatible — both ship with no-op default implementations so existing custom schedulers and test doubles keep compiling. Classes that override enqueue() must add the new tags and deadlineMs parameters.

Second Android/iOS constraint-parity pass. Six gaps closed, all previously just unwired rather than platform-impossible: requiresUnmeteredNetwork/requiresCharging now enforced for standalone iOS tasks (not just chain steps), backoffPolicy/backoffDelayMs now affect real iOS retry timing, SystemConstraint.REQUIRE_BATTERY_NOT_LOW/ALLOW_LOW_BATTERY implemented on iOS, and Android's setExpedited() now actually respects TaskPriority as documented (a real behavior change for NORMAL/LOW tasks — see CHANGELOG.md).

Two WorkQuery-style batch APIs, matching androidx.work.WorkQuery's own AND-across-axes/OR-within-axis semantics: observeTaskState(id): Flow<TaskState> for a live state stream (Enqueued/Running/Succeeded/Failed/Cancelled/Unknown), and queryTasks(tags, workerClassNames, states): List<QueriedTask> for a batch read filtered by any combination of those three. Both ship with no-op defaults for source compatibility.

Extends two "Ultra" iOS features shipped in earlier releases: IosBackgroundUploadWorker (upload counterpart to the download-only IosBackgroundDownloadWorker), sharedContainerIdentifier on both background-transfer configs (App Group transport sharing), and a new KmpWorkManager.initialize(appGroupIdentifier = ...) for read-only cross-process task visibility — see docs/IOS_APP_GROUP_STORAGE.md.

Closes out Flutter parity Group 2: maxBytesPerSecond bandwidth throttling on all four HTTP download/upload configs (kmpworkmanager-http), a token-bucket rate limiter shared across every concurrent chunk/file in the parallel variants.

Documentation accuracy sweep: TaskTrigger.Exact on iOS corrected to reflect its real best-effort behavior (it does not guarantee code execution — see docs/iOS-EXACT-ALARM-GUIDE.md), and a pre-refactor Constraints/ExistingPolicy shape that had drifted into several docs (networkType, requiresBatteryNotLow, expedited as a Constraints field, a fictional APPEND/ APPEND_OR_REPLACE on ExistingPolicy) corrected throughout.

What's new in v3.2.0

Opt-In Permissions Architecture (Android). To comply with strict Play Store guidelines and prevent unwarranted app rejections, KMP WorkManager no longer automatically merges FOREGROUND_SERVICE and FOREGROUND_SERVICE_DATA_SYNC permissions into your app's manifest. If your app only uses standard background tasks, this update ensures you won't be blocked during app review.

Breaking Change for Heavy Worker Users: If you use KmpHeavyWorker, you must now manually declare the required FGS permissions in your AndroidManifest.xml. See the v3.2.0 Migration Guide.

Previous releases

See the changelog for the full history, and the per-version upgrade guides: v3.5.0 · v3.3.0 · v3.2.0 · v3.1.0 · v3.0.0 · v2.5.0 · v2.4.0.

Built-in workers

Camera / media-app advisory. For burst upload (50 photos at once), use ParallelHttpUploadWorker instead of one chain step per file. For RAW / video downloads over cellular, prefer IosBackgroundDownloadWorker on iOS so the transfer survives swipe-to-quit. HttpUploadWorker is the only stable worker without resumable/chunked semantics — pin those uploads to Wi-Fi (Constraints(requiresUnmeteredNetwork = true)) until v2.6.

Security

SSRF protection — all built-in worker HTTP calls are validated before dispatch. Blocked:

169.254.169.254   AWS/GCP/Azure IMDS
fd00:ec2::254     AWS EC2 (IPv6)
100.100.100.200   Alibaba Cloud metadata
localhost, 0.0.0.0/8, [::1], 10.x, 172.16–31.x, 192.168.x
100.64.0.0/10     CGNAT (Tailscale, carrier-grade NAT)
fc00::/7, fe80::/10

RFC 3986 UserInfo bypass and multi-@ authority attacks are both handled. DNS rebinding is a known limitation — use certificate pinning or an egress proxy for high-trust environments.

Input size validation — inputs exceeding WorkManager's 10 KB Data limit throw IllegalArgumentException at enqueue time.

Testing

1,505 tests across 8 source sets

Nine of the 76 instrumented tests are diagnostics, not verification. ChineseROMCompatibilityTest inspects the device it runs on — manufacturer, battery-optimisation state, whether an OEM settings Intent resolves — and prints what it finds. It contains no assertions and cannot fail. Run it to learn about a device before shipping to that market; do not read it as coverage. The class KDoc says the same.

Every test in the table runs. Nothing is @Ignored: as of v3.5.0 the KSP compile-testing suite (23 tests that had been skipped since it was written) executes, and the two load-sensitive iOS stress tests are behind an opt-in flag that reports itself when it skips rather than disappearing — KMP_RUN_STRESS_TESTS=1 ./gradlew :kmpworker:iosSimulatorArm64Test.

On coverage numbers: koverVerify gates the JVM/Android side only — Kover cannot instrument Kotlin/Native, so the iOS half of the library has no line-coverage figure despite carrying the most tests. See docs/COVERAGE.md for what is and is not measured.

• QA_PersistenceResilienceTest — 100-step chain killed at step 50, resumes at exactly step 50
• V236ChainExecutorTest — time budget, shutdown propagation, batch loop correctness
• IosExecutionHistoryStoreTest — save/get/clear, auto-pruning, all status variants
• AppendOnlyQueueTest — CRC32 corruption detection, truncation recovery, concurrent access
• SecurityValidatorTest — SSRF, IPv6 compressed loopback, multi-@ UserInfo bypass

Testing your own code

Unit-test code that calls BackgroundTaskScheduler without touching real WorkManager or BGTaskScheduler by depending on kmpworker-testing and using FakeBackgroundTaskScheduler:

Ships starting with 3.5.0. kmpworker-testing is new since the 3.4.1 release — it is not published under 3.4.1 or any earlier version.

commonTest.dependencies {
    implementation("dev.brewkits:kmpworker-testing:3.5.0")
}

val fakeScheduler = FakeBackgroundTaskScheduler()

myViewModel.scheduleSync(fakeScheduler)

assertEquals(1, fakeScheduler.enqueuedTasks.size)
assertEquals("SyncWorker", fakeScheduler.enqueuedTasks.first().workerClassName)
assertTrue(fakeScheduler.cancelledIds.isEmpty())

Documentation

Migration: v3.4.x → v3.5.0 · v3.2.x → v3.3.0 · v3.1.x → v3.2.0 · v2.5.x → v3.0.0

Requirements

Contributing

./gradlew :kmpworker:allTests   # all platforms must pass before opening a PR

Commit messages follow Conventional Commits.

License

Apache 2.0. See LICENSE.