[arnonate]

Jira: RAD-17289, follow-up to RAD-16862

On Android, at most 4 requests transmit at once across the library. Small JSON requests wait for the same 4 slots as file parts, first come, first served. Each chunked upload can keep 3 parts waiting. So with a large backlog, a session's small create request can wait behind hundreds of parts. Support sees about 10 cases a month of captures whose session never reached the server. Some of those may be this.

This adds priority: 'high' | 'normal' to the request descriptor. Normal requests now use at most 3 of the 4 slots. The fourth is kept for high-priority requests, which can also use any free slot.

Before: a session create waits in line behind every file part ahead of it.
After: a high-priority request takes the reserved slot without waiting behind file parts. It can still wait when other high-priority requests hold every slot.

iOS accepts the field and ignores it for now. Its version needs a second background URLSession and is a separate change.

What to look at

• TransferGate in UploadTransport.kt: a normal request takes a lane permit, then a slot. A high-priority request takes a slot only.

Decisions and trade-offs

• Normal uploads lose one slot even when no high-priority work is waiting. File uploads drop from 4 to 3 concurrent requests. A gate that lends the reserved slot to normal requests would need preemption or a priority queue. This is simpler and can't starve either side.
• A reserved slot, not a second queue. Requests only compete for slots at transmit time. Separate WorkManager work or a second store would add cost and no benefit.
• Two semaphores, not a priority queue. Both kinds wait in FIFO order for a slot. If high-priority requests fill all 4 slots, normal requests already waiting go first. Session requests are small and few, so this should be rare.
• Entries saved before this change read as normal. Gson leaves the new boolean false.

Test Plan

• ./gradlew :react-native-background-upload:testDebugUnitTest: 316 tests, 0 failures. New tests cover the 3-slot cap for normal requests, the reserved slot for a high-priority one, priority parsing, a re-enqueue that changes priority, and the flag reaching the transport.
• yarn typecheck, yarn test (192 pass) and yarn lint:ci pass.
• Not measured: the throughput cost of 3 slots instead of 4 on a real network.

🤖 Generated with Claude Code

[elliottkember]

This sounds like a great idea and probably simpler than multiple queues!!