Resumable Uploads with tus
Overview
WEDA provides object storage for hosting uploaded AI models for easier management. It accepts model files up to 50 GiB.
AI model artifacts can be quite large: a single ONNX or TensorRT engine file can easily be several
gigabytes in size. Transferring files of this size over a conventional HTTP POST is fragile: a
dropped connection, a proxy timeout, or a client restart at 90% completion forces the entire
transfer to begin again.
WEDA solves this by implementing the tus resumable upload protocol for all model file transfers. An interrupted upload resumes from the exact byte where it stopped, and no already-transferred data is retransmitted.
This article explains what tus is, the concepts you need to work with it, and the end-to-end flow for uploading a model file to WEDA.
What Is tus?
tus is an open protocol for reliable, resumable file uploads over HTTP, published at tus.io under an MIT license. It is not a proprietary Advantech mechanism — it is a widely adopted standard used in production by Vimeo, Cloudflare, and Supabase.
Three properties make it suitable for model distribution:
- Built on plain HTTP. tus adds no new transport. It uses standard methods (
POST,PATCH,HEAD,DELETE) and custom headers, so it traverses existing proxies, load balancers, and corporate firewalls without special configuration. - Deliberately small. The core specification defines only a handful of operations, which keeps client implementations light and predictable.
- Broadly supported. Mature open-source client libraries exist for JavaScript, Python, C#, Go, Java, Swift, and Kotlin. In most cases you integrate a library rather than implement the protocol yourself.
WEDA implements tus protocol version 1.0.0.
Core Concepts
| Concept | Description |
|---|---|
| Upload URL | A unique URL created for each upload session. Every subsequent operation for that file — transferring data, querying progress, cancelling — targets this URL. It is returned in the Location header when the upload is created. |
| Upload-Length | The total size of the file in bytes. Declared once when the upload is created and immutable thereafter. |
| Upload-Offset | The number of bytes the server has durably received so far. This is the single source of truth for resumption: the client's next data transfer must begin at exactly this offset. |
| Chunk | A contiguous segment of the file sent in one request. A file is uploaded as a sequence of chunks; the client controls how large each one is. |
| Tus-Resumable | The protocol version header. WEDA defaults it to 1.0.0 when omitted; if you do send it, the value must be 1.0.0. |
| Upload-Metadata | Carries the uploadId you received when registering the edition, base64-encoded, in the form uploadId <base64>. Required when creating the upload session — the request is rejected without it. |
The protocol's central idea is that the server always knows the current offset, and the client can always ask for it. Resumption is therefore not a special recovery mode — it is the same operation the client performs on every chunk.
The Four Operations
All model upload traffic uses one base path, derived from the model and edition being uploaded:
/api/v1/orgs/{orgId}/ai-models/{modelId}/editions/{edition}/uploads
| Operation | Method | Target | Purpose |
|---|---|---|---|
| Creation | POST | Base path | Open an upload session and obtain its Upload URL. |
| Transfer | PATCH | Upload URL | Send a chunk of file data at the current offset. |
| Resume | HEAD | Upload URL | Query the current offset after an interruption. |
| Termination | DELETE | Upload URL | Cancel the upload and release server-side storage. |
There is no "complete" or "finalize" call. When the received offset reaches the declared length, WEDA finalizes the file automatically.
Upload Flow
Uploading a model file takes two phases: first register the upload to obtain an uploadId and
the tus endpoint, then transfer the file to that endpoint using the tus protocol. After the
last chunk arrives, WEDA automatically verifies the file against the SHA-256 hash you supplied at
registration before publishing the model edition.
Key points to take away:
- Registration comes first. The tus transfer cannot start without the
tusEndpointand upload session created in step 1. - Completion is automatic. When the final chunk brings the offset to the declared length, WEDA finalizes the file and starts verification — you send no "finish" call.
- Success means verified. The upload status reaches
Uploadedonly after WEDA's hash check matches the one supplied at registration; a mismatch ends inVerifyFailedand the file is discarded.
Client Libraries
Implementing the protocol directly is rarely necessary. The following libraries handle offset tracking, chunking, and retry logic.
| Language / Platform | Library |
|---|---|
| JavaScript / TypeScript | tus-js-client |
| Python | tus-py-client |
| Java | tus-java-client |
| C# / .NET | tus-dotnet-client |
The full, current list — including server-side implementations — is maintained at tus.io/implementations.
Configure the library with the tusEndpoint returned during registration, the total file size, and
an Authorization: Bearer header.
Key Benefits
- Interruption tolerance. Network loss, client restarts, and device reboots cost only the current chunk, not the whole transfer.
- Bandwidth efficiency. No byte is transmitted twice, which is material for multi-gigabyte artifacts and metered or field connections.
- End-to-end integrity. Every file is verified against a client-supplied SHA-256 hash before it is published, so corrupted transfers never become deployable model editions.
- Standard tooling. Because tus is an open protocol, you integrate a maintained community library rather than a vendor-specific SDK.
Related
- tus Resumable Upload Protocol v1.0.0 — the full protocol specification
- tus.io — protocol home and client library directory
- Apply this to model uploads end-to-end: AI Model Management — Upload and Deploy