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

Installation

// build.gradle.kts
commonMain.dependencies {
    implementation("dev.brewkits:kmpworkmanager:3.2.0")          // core engine (no Ktor)
    // Optional — only if you use the built-in HTTP workers (Http*/ParallelHttp*).
    implementation("dev.brewkits:kmpworkmanager-http:3.2.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()
        // IOSModuleKt.iosModule calls kmpWorkerModule(workerFactory = IosWorkerFactoryGenerated())
        KoinInitializerKt.doInitKoin(platformModule: IOSModuleKt.iosModule)
    }

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let koin = KoinIOS()
        
        BGTaskScheduler.shared.register(
            forTaskWithIdentifier: "kmp_chain_executor_task",
            using: nil
        ) { task in
            IosBackgroundTaskHandler.shared.handleChainExecutorTask(
                task: task,
                chainExecutor: koin.getChainExecutor()
            )
        }
        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()

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.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.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

600+ tests across commonTest, iosTest, androidInstrumentedTest

• 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

Documentation

Migration: v3.1.x → v3.2.0 · v2.5.x → v3.0.0 · v2.4.x → v2.5.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.