Resumable uploads are a state machine, not an endpoint

The protocol is small enough to read in an afternoon and easy to implement wrongly, because the hard part is not HTTP. It is agreeing on who owns the offset.

Three facts that changed the design

• A client that resumes is a client that already lied to you once about how much it sent.
• The storage layer, not the API, is the authority on the offset.
• Every upload is eventually abandoned; the cleanup job is part of the feature.

The pipeline behind it

Completion is an event, not a response. The upload endpoint publishes to RabbitMQ, and the transcoding workers pick up the job — so an upload finishing at 3am does not depend on the API process staying alive.

Chunk size ended up at 8 MB: large enough that the per-request overhead disappears, small enough that a dropped connection on a mobile network never costs more than a few seconds of progress.