Resumable Uploads with tus

WEDA uses tus, an open protocol for resumable uploads over HTTP, to transfer AI model files. The client can query how much of a file the server has stored and continue an existing upload from that byte offset.

Why Resumable Uploads Matter

AI model files can be large, and a connection can fail before a transfer finishes. Restarting the whole file consumes time and bandwidth that a resumable upload can save.

With tus, the client checks the server's stored progress before continuing. Resuming an existing upload and starting a replacement upload are different actions: a replacement starts the transfer again.

The tus protocol specification defines the HTTP exchange. WEDA's API reference defines model registration, authentication and upload lifecycle rules for its implementation.

Upload Sessions and Offsets

An upload session provides a resource URL and tracks the file's progress:

Concept	Meaning in WEDA's upload flow
Upload URL	The resource URL returned in the tus creation response's Location header. Use it to transfer bytes, query the offset or terminate that upload.
Upload-Length	The total file size in bytes. It must match the size declared when registering the model edition.
Upload-Offset	The number of bytes the server has stored. The next transfer starts at this offset.
Chunk	A contiguous range of the file's bytes sent in one request.
Tus-Resumable	The protocol-version header. Use 1.0.0 for WEDA's tus requests.
Upload-Metadata	At session creation, carries the registered ID as uploadId <Base64-encoded uploadId>.

Keep the registration uploadId and the Upload URL together. WEDA uses the registered ID for upload status and retry rules; the Location URL identifies the tus resource used for byte transfer. Use the returned URL rather than guessing it from the identifier.

WEDA's upload operations are:

Operation	Method and target	Expected successful response
Create a tus session	POST to the returned tusEndpoint	201, with the Upload URL in Location.
Read stored progress	HEAD on the Upload URL	200, with Upload-Offset and Upload-Length.
Transfer a chunk	PATCH on the Upload URL	204, with the updated Upload-Offset.
Terminate the transfer	DELETE on the Upload URL	204.

How Resuming Works

If a request is interrupted, the client may not know how many bytes reached the server. Read the server's offset before sending more data, and continue with the corresponding bytes from the same file.

This 1,000-byte example illustrates an upload whose server has retained 600 bytes:

The client continues from the server's confirmed offset. A successful PATCH returns the new offset, which the client uses for the next chunk.

WEDA's Upload a File Chunk API requires Content-Type: application/offset+octet-stream and the matching Upload-Offset. If the supplied offset differs from the server's, WEDA returns 409. Query Get Current Upload Offset again before retrying. A 404 means the upload resource was not found, so that URL cannot currently be used to resume.

Check the result: Upload-Offset reaches Upload-Length, confirming that the file bytes have been transferred. WEDA's integrity verification is a separate result, described below.

How WEDA Uses tus

WEDA separates model registration, byte transfer and verification:

1. Register the edition and file. Register New Edition accepts fileName, fileSize and the file's SHA-256 fileHash, then returns the uploadId and tusEndpoint needed for transfer. Use the returned maxFileSize to check the allowed size. An edition registered without file information has no upload session.
2. Create the tus resource and transfer bytes. Create a Resumable Upload requires the matching Upload-Length and the registered uploadId in Upload-Metadata. Keep the returned Location URL and use it for PATCH and, after an interruption, HEAD.
3. Check verification. After the transfer completes, WEDA computes SHA-256 and compares it with the hash supplied at registration. Use Get Upload Status to follow the outcome. Verifying means the integrity check is in progress; Uploaded means the file passed verification and is ready for deployment. UploadFailed and VerifyFailed require investigation and a retry as appropriate. No separate client finalize request is needed.

Note: Resume or restart

Resume with HEAD and PATCH while the tus upload resource remains available. For a terminated or failed transfer, WEDA allows a new tus session using the same registration uploadId. A fresh in-progress session blocks replacement until its uploadExpiresAt passes; creating a replacement then discards the stalled transfer's bytes and starts over. An already uploaded edition does not accept another tus session. Follow the Create a Resumable Upload API's retry rules rather than re-registering the edition.

The tus project lists client implementations for different languages. Configure a client for WEDA's endpoint, metadata and authentication requirements; the library does not replace edition registration or the final verification check.

For model preparation and edition management, see Upload an AI Model.