Upload a resumable file chunk

Linux with /usr/bin/python3 only. Send raw chunks of at most 8 MiB in order. Each request body must arrive within two minutes, with no 60-second idle gap; use smaller chunks on slow links. Use the same path, upload_id, size and overwrite on each request. Total size is at most 2 GiB. The first chunk at offset 0 creates a private sibling staging directory. The final chunk publishes the complete file atomically; partial uploads never replace the destination. An empty chunk at offset=size retries publication. With overwrite=false an occupied destination returns 409 reason: exists. Offset or metadata conflicts return 409: read status before retrying. After a lost reply or partial write, GET status and resume from the returned offset. Never reuse an ID for different contents. Keep the source unchanged throughout. DELETE removes staging and the completion receipt without deleting the destination. Staging consumes guest disk until deleted; there is no automatic expiry. Completed data is retained as a hardlink, not a second copy, until the destination is replaced or deleted: from then on the receipt alone holds the old bytes, so DELETE it to free that space. Older hosts return 404; never fall back to ordinary PUT for a chunk.

A chunk whose length differs from its Content-Length, or that runs past size from its offset, is a 400, and so is an empty chunk at any offset other than size. A Windows computer is a 400. A guest-side failure to write the chunk, such as a full guest disk or a directory the upload cannot write to, is a 400 naming the likely causes: fix it, then read status before retrying.

A 503 can mean the host’s upload buffers are all in use by other uploads just then: nothing was staged, so read status and resend from its offset after a short pause. A computer suspended as the chunk arrived answers 409 with resume_required and reason: contention: read status, then resend from the returned offset.

Requires the member role or higher.