tus 1.0-prerelease

3 minute read

It's been a while since I've mentioned tus, but there have been some cool developments so we'd like to refresh your memory.

So Yeah, Uploading is Broken

At Transloadit we care about providing a reliable upload service. Sometimes however, it could happen that our servers misbehave, that a mobile user switches connections, or that your end user has flaky WiFi.

We're doing what we can to limit cases like these, but also have to face the brisk reality that sometimes, an upload needs to be retried from the start.

A bad user experience, especially if in the middle of a 2 GB upload on a poor connection. What's worse, the longer an upload takes, the longer it is exposed to this poor connection.

With media getting bigger and networks staying fragile, we need a better way to handle these outages and hiccups.

Resumable Uploads

Any decent network library implements retries, but ideally, a retry picks up where the user left off, and starts uploading only the remaining bytes when the end user for instance clears a tunnel.

If that happens under the hood, the user might not even notice he had an interrupted connection as the total upload time is barely impacted.

What's more, if we could redesign this in such a way that we could send multiple file parts simultaneously, the upload might even become faster.

For all of this to work, we need resumable uploads.

There are many pieces of software / implementations that already offer resumable uploads, but they're not as thorough or interoperable as we'd like. They all speak a different dialect.

Imagine every web browser having it's own incompatible HTTP dialect. It's all just not very open web like.

A thousand incompatible one week projects that barely work, when all we need is one real project, done right.

And that's what tus is.


tus is an open protocol that's been in development for over a year, with high-level contributions from all over the world and from different companies besides Transloadit - such as Vimeo.

Here's how a simple back & forth between a client and server that can speak tus 1.0 would look like:

# Client:
> POST /files HTTP/1.1
> Host: tus.example.org
> Content-Length: 0
> Entity-Length: 100
> TUS-Resumable: 1.0.0
> Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==

# Server:
< HTTP/1.1 201 Created
< Location: http://tus.example.org/files/24e533e02ec3bc40c387f1a0e460e216
< TUS-Resumable: 1.0.0

# Client:
> PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
> Host: tus.example.org
> Content-Type: application/offset+octet-stream
> Content-Length: 30
> Offset: 0
> TUS-Resumable: 1.0.0
> [first 30 bytes]

# Server:
< HTTP/1.1 204 No Content
< TUS-Resumable: 1.0.0

Besides a lightweight but well documented protocol, tus also provides two example implementations:

Additionally there are many community provided implementations in languages like iOS, Android, Ruby, Node.js, Python, PHP, etc. Since we're building on top of plain HTTP, it's straightforward to build implementations in your favorite language. If you fully implement the protocol and license it MIT, we might adopt your project.

Nearing 1.0 - Last Call for Feedback

The news today is that we're really close to releasing a 1.0 stable version of the protocol and our reference implementations, and are calling for one last round of feedback over at our 1.0 pull request on GitHub.

Please don't be shy and leave your comments and recommendations if you still want to impact tus 1.0.

Finally, we encourage everybody who deals with uploads (yes, competitors too) to have have a look at tus and consider using it for your next release. tus is Transloadit started and funded, but community owned, and this will not change.

At Transloadit we'll be looking to implement tus in our upload & encoding service this year.

Leave a Comment Right Here