The HTTP working group is currently discussing a draft for resumable uploads over HTTP: draft-ietf-httpbis-resumable-upload. Its latest iteration can be found at the httpwg/http-extensions repository. This repository contains information about known client and server implementations of the draft, including instructions and examples on how to use them.
Apple added support for resumable uploads (draft version 01) in URLSession on iOS 17+ and macOS 14+. This API can be used from Swift and Object-C. A detailed introduction into resumable downloads and uploads as well as links to the API documentation can be found in Apple's WWDC23. This repository contains a small iOS application demonstrating the use of resumable uploads in clients/ios.
Tus-js-client is a client implementing the tus resumable upload protocol for various JavaScript environment, including browsers, Node.js, React Native etc. In recent versions, it also provides experimental support for the resumable upload draft. A browser-based example can be found in clients/tus-js.
A simple resumable upload client written in Go can be found in clients/go. Its purpose is to demonstrate the basic logic of a resumable upload client and serve as inspiration for new client implementations.
Apple published an example implementation of a resumable upload server built using SwiftNIO. It is based on the NIOResumableUpload package, which was published from Apple's WWDC23 and provides transparently translates resumable uploads into non-resumable uploads for easy server-side handling. An example can be found in servers/swift-nio.
Tusd is a server originally developed for the tus resumable upload protocol, but recent versions also provide experimental support for the draft of Resumable Upload For HTTP. Its authors intend to support all draft versions and serve as a testing ground for new and existing upload clients. Tusd is a feature-rich upload server written in Go and supports storing data on various cloud providers and notifying applications about upload progress. A quick guide on getting tusd up and running can be found in servers/tusd.
Tusdotnet is a feature-rich .NET server implementation of the tus resumable upload protocol, which also includes experimental support for the draft of Resumable Upload For HTTP. Details on how to use tusdotnet with the draft can be found at https://github.com/tusdotnet/tusdotnet/tree/POC/tus2.
A simple resumable upload server written in Go can be found in servers/go. Its purpose is to demonstrate the basic logic of a resumable upload server and serve as inspiration for new server implementations.
Caddy is an HTTP proxy with support for custom modules. caddy-rufh is such a module and transparently translated resumable uploads into traditional, non-resumable uploads, so that backends don't have to take care of handling resumable uploads on their own. The proxy will take care of this.
https://github.com/Murderlon/caddy-rufh
At the IETF 118's hackathon, a conformity tester was developed to verify whether a server correctly implements the draft. This tool should help to validate server-side setups and assist in creating interoperable implementations. Its source code and instructions for use can be found at https://github.com/tus/ietf-hackathon/tree/main/tests.
A simple load testing tool for concurrent, resumable uploads can be found at github.com/tus/load-tester. It can be used to measure the upload duration and throughput under various scenarios by simulating multiple, parallel users.
The draft is currently still in a developing state, where it is actively discussed and modified based on the gathered feedback. This can also result in changes in the protocol mechanism that will make existing implementations of earlier draft version incompatible with newer versions. To indicate such breaking changes, each draft version specifies an interoperability version (interop version), which is incremented when a new draft version includes a breaking change over the previous versions. This interop version is included in requests and responses, allowing client and server implementations to detect when incompatible draft versions are used by the respective parties.
The following table provides an overview of which draft version is supported by which client or server implementation. A client or server can support multiple versions by adjusting to the request of the user or client. If you want to pair a client with a server for uploading data, please ensure that both implement at least one shared draft version.
| Draft version | -01 | -02 | -03 | -04 | -05 |
|---|---|---|---|---|---|
| Interop version | 3 | 4 | 5 | 6 | 61 |
| Clients | |||||
| URLSession | ✅2 | ✅3 | ✅4 | ✅4 | |
| tus-js-client | ✅ | ✅ | ✅ | ||
| Go example | ✅ | ✅ | |||
| Servers | |||||
| tusd | ✅ | ✅ | ✅ | ✅ | ✅ |
| tusdotnet | ✅ | ✅ | ✅ | ✅ | |
| SwiftNIO | ✅ | ||||
| Go example | ✅ | ✅ | |||
| Caddy module | ✅ | ||||
| Tools | |||||
| Conformity tester | ✅ | ||||
| Load tester | ✅ |
The goal is to have interoperable implementations for testing purposes. Below shows a table of the interoperability between various client and server implementations.
| Clients | |||
|---|---|---|---|
| URLSession (iOS, macOS) | Tus-js-client (Web, Node.js) | Go demo client | |
| Servers | |||
| Tusd | ✅ | ✅ | ✅ |
| Tusdotnet | ✅ | ✅ | ✅ |
| Go demo example | ✅ | ✅ | ✅ |
| SwiftNIO | ?5 | ?5 | ?5 |
When running a client and server locally, the data transfer can be too fast to usefully test the pause/resume capabilities of resumable uploads. Throttling the network speed is a handy way to simulate more realistic scenarios. Browsers natively provide a setting for this in their developer tools (e.g. Firefox and Chrome.
When working outside of browsers, a proxy like toxiproxy can be placed in front of the upload server and control the transfer speed. It is also capable of simulating other kinds of network interruptions.
# Start toxiproxy control server in a separate tab
toxiproxy-server
# In a new tab, setup a throttled connection to your server.
# The upload server should listen at localhost:8080 and the throttled server
# listens at localhost:8081. The bandwidth is limited to 2048kb/s (2mb/s).
# Adjust these values to your needs
toxiproxy-cli create --listen localhost:8081 --upstream localhost:8080 upload-server
toxiproxy-cli toxic add --type bandwidth --toxicName bandwidth-limit-1 --downstream --attribute rate=2048 upload-server
toxiproxy-cli toxic add --type bandwidth --toxicName bandwidth-limit-2 --upstream --attribute rate=2048 upload-server