### Install and Run tusd with Nix

Source: https://tus.io/blog/2025/05/20/tusd-nixpkgs

Use this command to install tusd in your current environment. This makes the tusd binary available for immediate use.

```bash
nix-shell -p tusd --run 'tusd --help'
```

--------------------------------

### OPTIONS Request and Response Example

Source: https://tus.io/protocols/resumable-upload.html

This example shows a typical OPTIONS request and its response, indicating server capabilities like Tus version, maximum upload size, and supported extensions.

```http
OPTIONS /files HTTP/1.1
Host: tus.example.org
```

```http
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Tus-Version: 1.0.0,0.2.2,0.2.1
Tus-Max-Size: 1073741824
Tus-Extension: creation,expiration
```

--------------------------------

### Install tusd Globally with Nix

Source: https://tus.io/blog/2025/05/20/tusd-nixpkgs

Install tusd into your user profile using Nix. This makes tusd available system-wide for your user.

```bash
nix-env -iA nixpkgs.tusd
```

--------------------------------

### Run tus Server Standalone

Source: https://tus.io/blog/2025/03/25/tus-node-server-v200

Run the tus server as a standalone Node.js application. This example configures the host, port, and file store, then starts the server.

```javascript
import { Server } from '@tus/server'
import { FileStore } from '@tus/file-store'

const host = '127.0.0.1'
const port = 1080

const tus = new Server({
  path: '/files',
  datastore: new FileStore({ directory: './files' }),
})
tus.listen({ host, port })
```

--------------------------------

### tus 1.0 Client-Server Communication Example

Source: https://tus.io/blog/2015/11/16/tus10

Demonstrates a basic HTTP request-response flow for initiating and patching a file upload using the tus 1.0 protocol. This example illustrates the initial POST request to create a file resource and a subsequent PATCH request to upload data chunks.

```http
# Client:
> POST /files HTTP/1.1
> Host: tus.example.org
> Tus-Resumable: 1.0.0
> Content-Length: 0
> Upload-Length: 100
> Upload-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
< Tus-Resumable: 1.0.0
> Content-Type: application/offset+octet-stream
> Content-Length: 30
> Upload-Offset: 0
> 
> [first 30 bytes]

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

--------------------------------

### Run tus Server with Bun using handleWeb

Source: https://tus.io/blog/2025/03/25/tus-node-server-v200

Use the `handleWeb()` method for Request-based handlers in environments like Bun. Ensure `@tus/file-store` is installed if using file storage.

```javascript
import { Server } from '@tus/server'
import { FileStore } from '@tus/file-store'

const tus = new Server({
  path: '/files',
  datastore: new FileStore({ directory: './files' }),
})

Bun.serve({
  routes: {
    '/files/*': (req) => tus.handleWeb(req),
  },
})
```

--------------------------------

### Starting tusd with HTTP Hooks

Source: https://tus.io/blog/2023/09/20/tusd-200

Configure tusd to send HTTP hooks to a specified endpoint. Ensure the hook server is running before starting tusd.

```bash
$ tusd -hooks-http http://localhost:8000
```

--------------------------------

### Integrate tus Server with Fastify using handle

Source: https://tus.io/blog/2025/03/25/tus-node-server-v200

Use the `handle()` method for integrating into traditional Node.js frameworks like Fastify. This example shows how to set up Fastify and the tus server, including parsing the offset+octet-stream content type.

```javascript
import fastify from 'fastify'
import { Server } from '@tus/server'
import { FileStore } from '@tus/file-store'

const app = fastify()
const tus = new Server({
  path: '/files',
  datastore: new FileStore({ directory: './files' }),
})
app.addContentTypeParser(
  'application/offset+octet-stream',
  // Leave body untouched
  (request, payload, done) => done(null),
)
app.all('/files', (req, res) => tus.handle(req.raw, res.raw))
app.all('/files/*', (req, res) => tus.handle(req.raw, res.raw))
app.listen(3000)
```

--------------------------------

### POST Request for Upload Creation

Source: https://tus.io/protocols/resumable-upload.html

This example demonstrates how to create a new upload resource using a POST request. The Upload-Length header specifies the total size of the upload, and Upload-Metadata provides additional information.

```http
POST /files HTTP/1.1
Host: tus.example.org
Content-Length: 0
Upload-Length: 100
Tus-Resumable: 1.0.0
Upload-Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==,is_confidential
```

```http
HTTP/1.1 201 Created
Location: https://tus.example.org/files/24e533e02ec3bc40c387f1a0e460e216
Tus-Resumable: 1.0.0
```

--------------------------------

### Resuming an Upload

Source: https://tus.io/protocols/resumable-upload.html

This example demonstrates how a client can continue an unfinished upload by sending a PATCH request with the remaining data and the current offset.

```APIDOC
## PATCH /files/{id}

### Description
Resumes an unfinished upload by sending a chunk of data.

### Method
PATCH

### Endpoint
/files/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the upload.

#### Headers
- **Content-Type** (string) - Required - Must be `application/offset+octet-stream`.
- **Content-Length** (integer) - Required - The size of the data chunk being sent.
- **Upload-Offset** (integer) - Required - The current offset of the upload.
- **Tus-Resumable** (string) - Required - The version of the tus protocol being used.

### Request Example
```
PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Content-Type: application/offset+octet-stream
Content-Length: 30
Upload-Offset: 70
Tus-Resumable: 1.0.0

[remaining 30 bytes]
```

### Response
#### Success Response (204 No Content)
- **Upload-Expires** (string) - Optional - The date and time after which the upload will expire.
- **Tus-Resumable** (string) - The version of the tus protocol being used.
- **Upload-Offset** (integer) - The new offset of the upload.

#### Response Example
```
HTTP/1.1 204 No Content
Upload-Expires: Wed, 25 Jun 2014 16:00:00 GMT
Tus-Resumable: 1.0.0
Upload-Offset: 100
```
```

--------------------------------

### Specify Nix Channel for tusd Installation

Source: https://tus.io/blog/2025/05/20/tusd-nixpkgs

If you encounter errors like 'undefined variable 'tusd'', use this command to specify a more recent Nix channel that includes tusd.

```bash
nix-shell -p tusd -I nixpkgs=channel:nixos-25.05 --run 'tusd --help'
```

--------------------------------

### Resuming an Upload with HEAD and PATCH

Source: https://tus.io/protocols/resumable-upload.html

Use a HEAD request to get the current upload offset, then use PATCH to send the remaining data. Ensure the Upload-Offset header matches the current state.

```http
HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Tus-Resumable: 1.0.0
```

```http
HTTP/1.1 200 OK
Upload-Offset: 70
Tus-Resumable: 1.0.0
```

```http
PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Content-Type: application/offset+octet-stream
Content-Length: 30
Upload-Offset: 70
Tus-Resumable: 1.0.0

[remaining 30 bytes]
```

```http
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 100
```

--------------------------------

### Python HTTP Hook Server for tusd v2

Source: https://tus.io/blog/2023/09/20/tusd-200

Implement an HTTP server in Python to handle tusd hooks. This example validates upload metadata, rejects uploads without a filename, and customizes upload IDs and creation time metadata.

```python
from http.server import HTTPServer, BaseHTTPRequestHandler
from io import BytesIO

import json
import time
import uuid

class HTTPHookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        # Read entire body as JSON object
        content_length = int(self.headers['Content-Length'])
        request_body = self.rfile.read(content_length)
        hook_request = json.loads(request_body)

        # Prepare hook response structure
        hook_response = {
            'HTTPResponse': {
                'Headers': {}
            }
        }

        # Use the pre-create hook to check if a filename has been supplied
        # using metadata. If not, the upload is rejected with a custom HTTP response.
        # In addition, a custom upload ID with a choosable prefix is supplied.
        # Metadata is configured, so that it only retains the filename meta data
        # and the creation time.
        if hook_request['Type'] == 'pre-create':
            metaData = hook_request['Event']['Upload']['MetaData']
            isValid = 'filename' in metaData
            if not isValid:
                hook_response['RejectUpload'] = True
                hook_response['HTTPResponse']['StatusCode'] = 400
                hook_response['HTTPResponse']['Body'] = 'no filename provided'
            else:
                hook_response['ChangeFileInfo'] = {}
                hook_response['ChangeFileInfo']['ID'] = f'prefix-{uuid.uuid4()}'
                hook_response['ChangeFileInfo']['MetaData'] = {
                    'filename': metaData['filename'],
                    'creation_time': time.ctime(),
                }

        # Send the data from the hook response as JSON output
        response_body = json.dumps(hook_response)
        self.send_response(200)
        self.end_headers()
        self.wfile.write(response_body.encode())


httpd = HTTPServer(('localhost', 8000), HTTPHookHandler)
httpd.serve_forever()
```

--------------------------------

### Initialize tus-node-server with S3Store

Source: https://tus.io/blog/2023/09/04/tus-node-server-v100

Demonstrates setting up the tus server with the S3 store, including configuration for AWS credentials and defining custom hooks for upload events.

```javascript
const { Server, EVENTS } = require('@tus/server')
const { S3Store } = require('@tus/s3-store')
// ...

const host = '127.0.0.1'
const port = 1080
const datastore = new S3Store({
  s3ClientConfig: {
    bucket: process.env.AWS_BUCKET,
    region: process.env.AWS_REGION,
    // Alternative auth methods now also supported
    credentials: new aws.ECSCredentials({
      httpOptions: { timeout: 5000 },
      maxRetries: 10,
    }),
  },
})
const server = new Server({
  path: '/files',
  datastore,
  // New hooks
  async onIncomingRequest(req, res) {
   // we can use this for access control
  },
  async onUploadCreate(req, res, upload) {
  // we can validate metadata here and reject the upload
  },
  async onUploadFinish(req, res, upload) {
  // we can use this to do post-processing or
  // move the upload to a different bucket
  },
})

// New events system
server.on(EVENTS.POST_CREATE, (req, res, upload => {}))
server.on(EVENTS.POST_RECEIVE, (req, res, upload => {}))
server.on(EVENTS.POST_FINISH, (req, res, upload => {}) )
server.on(EVENTS.POST_TERMINATE, (req, res, id => {}) )

server.listen({ host, port })
```

--------------------------------

### Replicate previous `resume` option behavior using async/await

Source: https://tus.io/blog/2020/05/04/tus-js-client-200.html

This snippet demonstrates how to achieve the previous `resume` option's behavior using the Upload Storage API with async/await syntax for cleaner asynchronous code.

```javascript
upload = new tus.Upload(file, options)
const previousUploads = await upload.findPreviousUploads()
if (previousUploads.length > 0) {
  upload.resumeFromPreviousUpload(previousUploads[0])
}
upload.start()
```

--------------------------------

### POST - Create Upload Resource

Source: https://tus.io/protocols/resumable-upload.html

Initiates a new upload resource. Requires either Upload-Length or Upload-Defer-Length header. Can optionally include Upload-Metadata and initial upload data (Creation With Upload extension).

```APIDOC
## POST /files

### Description
Creates a new upload resource. The client must specify the upload size using `Upload-Length` or defer it using `Upload-Defer-Length: 1`. Metadata can be included via `Upload-Metadata`. If the `Upload-Defer-Length` header is used, the client must provide the `Upload-Length` in a subsequent `PATCH` request.

### Method
POST

### Endpoint
/files

### Parameters
#### Headers
- **Upload-Length** (integer) - Required if `Upload-Defer-Length` is not present - The total size of the upload in bytes. Can be 0 for an empty file.
- **Upload-Defer-Length** (integer) - Required if `Upload-Length` is not present - Must be `1` to indicate the size is not known yet.
- **Upload-Metadata** (string) - Optional - Comma-separated key-value pairs (key space value). Keys must be unique, ASCII, and not contain spaces or commas. Values must be Base64 encoded and can be empty.
- **Content-Type** (string) - Required for Creation With Upload - Must be `application/offset+octet-stream` when including upload data in the body.
- **Expect** (string) - Optional for Creation With Upload - `100-continue` for early server feedback.
- **Tus-Resumable** (string) - Required - The version of the Tus protocol used (e.g., `1.0.0`).

### Request Example
```http
POST /files HTTP/1.1
Host: tus.example.org
Content-Length: 5
Upload-Length: 100
Tus-Resumable: 1.0.0
Content-Type: application/offset+octet-stream

hello
```

### Response
#### Success Response (201 Created)
- **Location** (string) - Required - The URL of the created upload resource.
- **Upload-Offset** (integer) - Required if data was included in the request - The offset of the upload after applying the received bytes.
- **Tus-Resumable** (string) - The version of the Tus protocol used.

#### Response Example
```http
HTTP/1.1 201 Created
Location: https://tus.example.org/files/24e533e02ec3bc40c387f1a0e460e216
Tus-Resumable: 1.0.0
Upload-Offset: 5
```

#### Error Responses
- **400 Bad Request** - If `Upload-Defer-Length` has an invalid value.
- **413 Request Entity Too Large** - If the upload size exceeds `Tus-Max-Size`.
```

--------------------------------

### Server Options for Checksum Algorithms

Source: https://tus.io/protocols/resumable-upload.html

An OPTIONS request can be used to discover supported checksum algorithms. The Tus-Checksum-Algorithm header lists the available methods.

```http
OPTIONS /files HTTP/1.1
Host: tus.example.org
```

```http
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Tus-Version: 1.0.0
Tus-Extension: checksum
Tus-Checksum-Algorithm: md5,sha1,crc32
```

--------------------------------

### Rewrite Upload#abort and Upload.terminate to use Promises

Source: https://tus.io/blog/2020/05/04/tus-js-client-200.html

Replace callback-based usage of `abort` and `terminate` with Promise-based syntax. Ensure to add a `.catch()` block to handle potential errors.

```javascript
upload
  .abort(true)
  .then(() => {
    // Handle success
  })
  .catch((err) => {
    // Handle error
  })
```

--------------------------------

### Replicate previous `resume` option behavior using Upload Storage API

Source: https://tus.io/blog/2020/05/04/tus-js-client-200.html

If you previously relied on the default `resume` behavior, use `findPreviousUploads` and `resumeFromPreviousUpload` to manually resume uploads. This snippet shows the Promise-based approach.

```javascript
upload = new tus.Upload(file, options)
upload.findPreviousUploads().then((previousUploads) => {
  if (previousUploads.length > 0) {
    upload.resumeFromPreviousUpload(previousUploads[0])
  }

  upload.start()
})
```

--------------------------------

### OPTIONS Request

Source: https://tus.io/protocols/resumable-upload.html

The OPTIONS request is used to discover the server's capabilities, including supported Tus versions, extensions, and maximum upload size.

```APIDOC
## OPTIONS

### Description
Retrieves information about the server's configuration and capabilities.

### Method
OPTIONS

### Endpoint
/files

### Response
#### Success Response (200 or 204)
- **Tus-Resumable** (string) - The supported Tus protocol version.
- **Tus-Version** (string) - A comma-separated list of supported Tus protocol versions.
- **Tus-Extension** (string) - Optional. A comma-separated list of supported extensions (e.g., creation, expiration).
- **Tus-Max-Size** (integer) - Optional. The maximum allowed upload size in bytes.

#### Example
```http
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Tus-Version: 1.0.0,0.2.2,0.2.1
Tus-Max-Size: 1073741824
Tus-Extension: creation,expiration
```
```

--------------------------------

### POST Request for Upload Creation with Data

Source: https://tus.io/protocols/resumable-upload.html

Use this POST request to create a new upload resource and include initial upload data. The Upload-Offset header in the response indicates how much data has been accepted.

```http
POST /files HTTP/1.1
Host: tus.example.org
Content-Length: 5
Upload-Length: 100
Tus-Resumable: 1.0.0
Content-Type: application/offset+octet-stream

hello
```

```http
HTTP/1.1 201 Created
Location: https://tus.example.org/files/24e533e02ec3bc40c387f1a0e460e216
Tus-Resumable: 1.0.0
Upload-Offset: 5
```

--------------------------------

### Enable Experimental IETF Protocol in tusd

Source: https://tus.io/blog/2023/09/20/tusd-200

Use this flag to enable preliminary support for the experimental IETF resumable upload protocol alongside traditional tus uploads. Note that neither the specification nor its implementation are ready for production use yet.

```bash
$ tusd -enable-experimental-protocol
```

--------------------------------

### Create Partial Upload

Source: https://tus.io/protocols/resumable-upload.html

Create a partial upload by setting the Upload-Concat header to 'partial'. The Upload-Length header specifies the size of the chunk.

```http
POST /files HTTP/1.1
Upload-Concat: partial
Upload-Length: 5

HTTP/1.1 201 Created
Location: https://tus.example.org/files/a
```

```http
POST /files HTTP/1.1
Upload-Concat: partial
Upload-Length: 6

HTTP/1.1 201 Created
Location: https://tus.example.org/files/b
```

--------------------------------

### POST Request (Creation)

Source: https://tus.io/protocols/resumable-upload.html

The POST request is used to create a new upload resource. It requires the Upload-Length header to specify the total size of the upload.

```APIDOC
## POST (Creation)

### Description
Creates a new upload resource.

### Method
POST

### Endpoint
/files

### Parameters
#### Headers
- **Upload-Length** (integer) - Required. The total size of the upload in bytes.
- **Upload-Metadata** (string) - Optional. Metadata for the upload (e.g., filename).
- **Tus-Resumable** (string) - The Tus protocol version.

### Request Example
```http
POST /files HTTP/1.1
Host: tus.example.org
Content-Length: 0
Upload-Length: 100
Tus-Resumable: 1.0.0
Upload-Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==,is_confidential
```

### Response
#### Success Response (201)
- **Location** (string) - The URL of the newly created upload resource.
- **Tus-Resumable** (string) - The Tus protocol version.
```

--------------------------------

### Parallel Uploads for fs.ReadStream

Source: https://tus.io/blog/2022/08/03/tus-js-client-300

Demonstrates how to configure tus-js-client to upload an fs.ReadStream in parallel. Ensure the 'parallelUploads' option is set to a positive integer.

```javascript
const path = 'my/file.txt'
const file = fs.createReadStream(path)

const upload = new tus.Upload(file, {
  endpoint: 'https://tusd.tusdemo.net/files/',
  parallelUploads: 3,
})
```

--------------------------------

### Manually Specify Upload Size for fs.ReadStream

Source: https://tus.io/blog/2022/08/03/tus-js-client-300

Shows the previous method of manually specifying the upload size when uploading an fs.ReadStream. This is now optional.

```javascript
const path = 'my/file.txt'
const file = fs.createReadStream(path)
const { size } = fs.statSync(path)

const upload = new tus.Upload(file, {
  endpoint: 'https://tusd.tusdemo.net/files/',
  uploadSize: size,
})
```

--------------------------------

### Set `withCredentials` using request callbacks

Source: https://tus.io/blog/2020/05/04/tus-js-client-200.html

To enable cross-origin requests with credentials, use the `onBeforeRequest` callback to set the `withCredentials` property on the underlying XMLHttpRequest object.

```javascript
upload = new tus.Upload(file, {
  endpoint: '....',
  onBeforeRequest: (req) => {
    const xhr = req.getUnderlyingObject()
    xhr.withCredentials = true
  },
  ....
})
```

--------------------------------

### Create Final Upload by Concatenation

Source: https://tus.io/protocols/resumable-upload.html

Create the final upload by concatenating previously created partial uploads. The Upload-Concat header lists the URLs of the partial uploads in the desired order. The Upload-Length header is not included in this request.

```http
POST /files HTTP/1.1
Upload-Concat: final;/files/a /files/b

HTTP/1.1 201 Created
Location: https://tus.example.org/files/ab
```

--------------------------------

### Checksum Verification

Source: https://tus.io/protocols/resumable-upload.html

This section details how to use checksums to verify the integrity of uploaded data during a resumable upload.

```APIDOC
## Checksum Extension

### Description
Allows clients and servers to verify data integrity of each `PATCH` request using checksums.

### Headers
#### Tus-Checksum-Algorithm (Response Header)
- **Value**: Comma-separated list of supported checksum algorithms (e.g., `md5,sha1,crc32`).

#### Upload-Checksum (Request Header)
- **Format**: `algorithm base64_checksum` (e.g., `sha1 Kq5sNclPz7QV2+lfQIuc6R7oRu0=`)
- **Purpose**: Contains the checksum of the current body payload.

### Requests
#### OPTIONS /files

##### Description
Used to discover supported checksum algorithms.

##### Response Example
```
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Tus-Version: 1.0.0
Tus-Extension: checksum
Tus-Checksum-Algorithm: md5,sha1,crc32
```

#### PATCH /files/{id}

##### Description
Sends a data chunk with an associated checksum for verification.

##### Request Example
```
PATCH /files/17f44dbe1c4bace0e18ab850cf2b3a83 HTTP/1.1
Content-Length: 11
Upload-Offset: 0
Tus-Resumable: 1.0.0
Upload-Checksum: sha1 Kq5sNclPz7QV2+lfQIuc6R7oRu0=

hello world
```

##### Response
- **204 No Content**: Checksums match and processing succeeded.
- **400 Bad Request**: Checksum algorithm not supported.
- **460 Checksum Mismatch**: Checksums do not match.

##### Response Example (Success)
```
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 11
```
```

--------------------------------

### Uploading a Chunk with Checksum Verification

Source: https://tus.io/protocols/resumable-upload.html

Include the Upload-Checksum header in a PATCH request to verify the integrity of the uploaded chunk. The server responds with 204 No Content on success.

```http
PATCH /files/17f44dbe1c4bace0e18ab850cf2b3a83 HTTP/1.1
Content-Length: 11
Upload-Offset: 0
Tus-Resumable: 1.0.0
Upload-Checksum: sha1 Kq5sNclPz7QV2+lfQIuc6R7oRu0=

hello world
```

```http
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 11
```

--------------------------------

### Terminating an Upload

Source: https://tus.io/protocols/resumable-upload.html

This section explains how clients can terminate uploads, allowing servers to free up resources.

```APIDOC
## Termination Extension

### Description
Provides a mechanism for clients to terminate uploads, freeing server resources.

### Requests
#### DELETE /files/{id}

##### Description
Terminates an upload, freeing associated resources.

##### Endpoint
/files/{id}

##### Method
DELETE

##### Request Example
```
DELETE /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Content-Length: 0
Tus-Resumable: 1.0.0
```

##### Response
- **204 No Content**: Upload terminated successfully.

##### Response Example
```
HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
```
```