TUS Protocol

Tus is an open protocol for resumable file uploads built on HTTP. Built as a layer on top of the popular HTTP protocol, tus can easily be integrated into applications using existing libraries, proxies and firewalls, and can be used directly from any website.

Tus specification defines a set of headers and methods that allow server and clients to upload files in chunks, and resume the upload operation after a network interruption or other transmission failure. The specification only requires a very small set of features to be implemented by clients and servers. In addition, tus defines a set of extensions that can be used to enhance the protocol with additional features. And most importantly, tus is open source and free to use!

Since Tus is just a protocol, you can implement it in any programming language. There are some implementations available already and you can check them out at tus.io/implementations. However, on the following lessons we will be implementing the slightly modified Tus protocol from scratch using Go (our favorite language :p). We are not going to use any web framework, only Go standard library such as net/http and io package, gorilla/mux for routing, and few others.

Now let’s start with the basics of the Tus protocol, which is the core protocol and its extensions.

Core protocol

The core protocol describes how to resume an interrupted upload. The specification defines two important HTTP methods: HEAD and PATCH along with its HTTP header.

  • The OPTIONS method is used to retrieve the server’s capabilities. The client can query the server to determine which extensions are supported by the server.

  • The HEAD method is used to retrieve the current status of an upload. The client can query the server to determine the current status of the upload so that it knows where to resume the upload.

  • The PATCH method is used to upload a chunk of data. The server is responsible for keeping track of the upload status and the uploaded data. Hence, the client can upload the data in chunks and resume the upload operation if it is interrupted.

Core protocol does not define anything about the URL structure, so it is up to the implementation to decide how to structure the URL. Thus, on the following lessons, we define the URL structure that we are going to use for our Tus implementation.

Extensions

Tus protocol also defines a set of extensions that can be used to enhance the protocol with additional features. Some of them is optional and you may decide whether you want to use it or not. If you use an extension, there will be mechanism defined on how to tell the client that the server supports the extension.

Some of the extensions include:

  • Creation: Allows the client to create a new upload resource on the server.

  • Creation with Upload: Allows the client to create a new upload resource and upload the first chunk in a single request.

  • Checksum: Allows the client to send a checksum of the file to the server to verify the integrity of the file.

  • Expiration: Allows the server to set an expiration time for the upload resource.

  • Termination: Allows the client to terminate an upload operation.

  • Concatenation: Allows the client to concatenate multiple uploads into a single file to increase the parallelism of the upload.

On the next lesson, let’s see notes taken from my simple implementation of Tus protocol. The next lesson will be covered the use case, the URL structure, file metadata and the storage interface. Keep going!