v10 slice 2: Android queue store, executor, and events

[dmurphy5]

Summary

This PR makes the Android side real. After it, a request that the app queues with mutate() is sent by Android, retried by Android, and reported back by Android, whether or not the app is open.

Before (v9): Android was a courier. JavaScript handed it one upload and listened for the result. Android did not know what a request was for, could not retry an HTTP failure, and could not answer "what is in the queue" after a restart.

After (v10): Android owns the queue. Each request is a small folder on disk with the request, its body, and its status. A background worker takes requests from that folder, sends them, and writes the result to a journal. JavaScript reads the journal at startup and gets every result it missed.

How a request moves through Android

flowchart LR
    A[mutate from JS] --> B[Write the request to disk]
    B --> C[Start a background worker]
    C --> D[Send the HTTP request]
    D --> E{Response?}
    E -- 2xx --> F[Write result to journal]
    E -- network error or 5xx --> G[Wait, then retry]
    G --> D
    E -- 401 or 403 --> H[Park until the app gives a new token]
    H --> D
    E -- other 4xx or deadline passed --> F
    F --> I[Tell JS]
    I --> J[JS acknowledges]
    J --> K[Delete the request and its files]

Loading

What each step guarantees:

1. Write first. The request is on disk before the worker starts. A crash cannot lose it.
2. Retry with backoff. Network errors and server errors retry with a growing wait, up to the request's deadline (14 days by default). The app does nothing.
3. Auth parking. A 401 or 403 stops the request without retrying. When the app has a new token, it calls updateHeaders(), and every parked request continues.
4. Journal before telling JS. The result is on disk before JavaScript hears about it. If the app is closed, the result waits.
5. Exactly one result. A crash between "write result" and "delete request" cannot send the request twice. The worker checks the journal before it sends.

Status of a request

stateDiagram-v2
    [*] --> queued
    queued --> running
    running --> queued: retry after a wait
    running --> awaiting_auth: 401 or 403
    awaiting_auth --> queued: updateHeaders
    queued --> paused: pause()
    paused --> queued: resume()
    running --> completed
    running --> error: 4xx, missing file, or deadline
    running --> cancelled: cancel()
    completed --> [*]: after JS acknowledges
    cancelled --> [*]: after JS acknowledges
    error --> [*]: cancel() or a new mutate() with the same id

Loading

The app sees these states through getRequests() and the state event feed, so a screen can show a list of uploads with progress.

Things to know

1. Upgrade from v9. At the first launch after the upgrade, results that v9 left in its journal become read-only rows so the app can see them. Unfinished v9 uploads are cancelled; the app re-sends them.
2. Large files. A chunked upload sends a big file as parts, and parts that the server accepted are kept across restarts. The v9 chunked engine is reused.
3. Ten-minute limit. When Android starts a worker in the background, the worker gets about ten minutes. A single large body that does not finish in that time restarts later. Large bodies should use parts. This is documented in the README.
4. Backups. The queue holds auth headers. The host app must set allowBackup="false". Diana does.

What to look at

1. The retry table in RetryClassifier.kt: does each HTTP status go where you expect?
2. WorkerOps.kt, function settle: journal first, then tell JS.
3. QueueStoreTest.kt: the crash-in-the-middle tests.

Test Plan

What's required for testing (prerequisites)?

JDK 17. For a device run, the example app in example/RNBGUExample; its README has a step-by-step script.

What are the steps to reproduce (after prerequisites)?

cd example/RNBGUExample/android
./gradlew :react-native-background-upload:testDebugUnitTest   # 307 tests, 0 failures

Nothing has run on a device yet. That is the next step.

Compatibility

OS	Implemented
iOS	❌ see the iOS PR
Android	✅

Checklist

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

🤖 Generated with Claude Code