[elliottkember]

Summary

Android uploads can stop for good. A request that gets a 401 parks, and the library schedules a wake at its expiry. Diana's requests expire in 10 years. A fresh token unparks the request, but the wake stays.

Each delayed WorkManager row holds one of the app's 20 JobScheduler slots until it runs. WorkManager's in-process scheduler reads only the 200 oldest enqueued rows. Enough stale wakes fill both, and then no queued work starts. This matches RAD-16862: 534 entries, all queued, with no activity for hours on a working network.

Before: a parked entry always gets a wake at its expiry, and the wake stays after the entry unparks.

After: a parked entry gets a wake only when it expires within 24 hours. When an entry is scheduled again, the library cancels any wake it no longer needs. The boot sweep does this too, so phones that are stuck now recover on the first launch after the update.

Evidence from the stuck phone

• The queue export shows all 352 session rows moving to queued at the same millisecond. That was Oct 21, 09:29:04.333 UTC. After that, no row was attempted again. Rows added the next day were never attempted at all.
• Sentry shows a 401 on the user-data call 4 seconds earlier. The app then tried a token refresh.
• The app process had run since 05:54 that day, so the boot sweep did not make that change. In a running process, only updateHeaders() moves rows that are not paused back to queued with one timestamp. It does that only to parked rows. So the rows were parked on a 401, each with a wake 10 years ahead.
• No log records a 401 on an upload request itself. The queue's attempt log on the phone was empty.

What to look at

• QueueController.scheduleRun(): the two places that cancel a stale wake.
• WorkManagerScheduler.cancelWake(): it checks for an unfinished wake before it cancels.

Decisions and trade-offs

• 24-hour horizon. A parked entry with a far expiry has no wake. It settles expired at the first launch after its expiry, not exactly on time.
• No cancel while the entry's worker runs. That worker can be the wake itself.
• cancelWake() reads WorkManager first. A WorkManager cancel reschedules all pending work even when the name has no rows. The boot sweep calls this for every queued entry.
• Backoff wakes from release() are unchanged. They run within 2 hours, so they slow the queue but do not stop it.

Test Plan

• ./gradlew :react-native-background-upload:testDebugUnitTest from example/RNBGUExample/android: 311 tests, 0 failures.
• Four of the new tests fail when the source changes are removed. They cover the sweep cleanup, the cancel on unpark, and park with a far expiry. A fifth test checks that a running worker's wake stays.
• Pre-commit hooks: tsc and jest (190 tests) pass.

What's required for testing (prerequisites)?

An Android phone on 11.0.1 with a few hundred queued uploads that parked on a 401.

What are the steps to reproduce (after prerequisites)?

1. Refresh the auth token so the entries unpark.
2. Expected on 11.0.1: the queue does not start.
3. Install this branch and launch the app. Expected: the queue drains.

Compatibility

OS	Implemented
iOS	❌
Android	✅

iOS uses URLSession, not WorkManager, so this problem does not apply there.

Checklist

• I have tested this on a device and a simulator
• I added the documentation in README.md
• I updated the typed files (TS and Flow)
• I've added Detox End-to-End Test(s)
• I've created a snack to demonstrate the changes: LINK HERE

🤖 Generated with Claude Code

[arnonate]

😵