Recipe: Resumable & chunked uploads

Overview

The client splits a file into fixed-size chunks (default 8 MiB), uploads each chunk with a sequence index and SHA-256 hash, and asks the server which chunks it already has on reconnect. The server reassembles the file once all chunks arrive.

Client flow

1. Hash the full file to obtain a content fingerprint.
2. POST /api/uploads/init with filename, total size, chunk size, and fingerprint.
3. For each chunk, PUT /api/uploads/chunk with index, hash, and binary body.
4. On interruption, GET /api/uploads/status to retrieve the set of completed chunk indices and resume from the first missing chunk.
5. After the final chunk, POST /api/uploads/complete to trigger reassembly and final integrity verification.

Server guarantees

• Chunks are written to temporary storage keyed by upload ID.
• Duplicate chunk uploads are idempotent — the server silently discards re-sent chunks whose hash matches the stored copy.
• Reassembly validates the concatenated file against the original fingerprint before promoting it to permanent storage.
• Incomplete uploads expire after 24 hours; a background job purges orphaned chunks.

Recommended chunk size

8 MiB balances parallelism (up to 4 concurrent chunks) against per-chunk overhead. For connections with high packet loss, drop to 2 MiB and reduce concurrency to 2.