### Setup and Run Python gRPC Hook Server

Source: https://github.com/tus/tusd/blob/main/examples/hooks/grpc/README.md

Follow these commands to set up a Python virtual environment, install dependencies, build gRPC code, and run the gRPC server. Ensure you have Python 3 and pip installed.

```sh
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
```

```sh
make -B hook_pb2.py
```

```sh
python3 server.py
```

```sh
tusd -hooks-grpc localhost:8000
```

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

### Start tusd with Plugin Hooks (Bash)

Source: https://context7.com/tus/tusd/llms.txt

This bash command demonstrates how to start the tusd server with hook handlers loaded as Go plugins from a specified directory.

```bash
# Start tusd with plugin hooks
tusd -hooks-plugin ./hook_handler -upload-dir=./data
```

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

### Start Azurite Local Storage Emulator

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Launch the Azurite emulator to emulate Azure Blob Storage locally for testing tusd. Ensure Azurite and the Azure CLI are installed before running this command.

```sh
$ azurite --location ./azurite-data
```

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

### Install tusd on Kubernetes with Helm

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/installation.md

Add the Helm repository and install the chart to a Kubernetes cluster.

```bash
helm repo add skm https://charts.sagikazarmark.dev
helm install --generate-name --wait skm/tusd
```

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

### Start MinIO Server

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Initializes a local MinIO server instance with specific root credentials for development or testing.

```sh
$ MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY minio server ./minio-data
```

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

### Start tusd with MinIO

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Launches the tusd server configured to use the local MinIO instance as the storage backend.

```sh
$ AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY tusd -s3-bucket mybucket -s3-endpoint http://localhost:9000
```

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

### Starting the tusd Server

Source: https://context7.com/tus/tusd/llms.txt

Run the tusd binary from the command line with various configuration flags to define storage, networking, and security settings.

```bash
# Start with local disk storage
tusd -upload-dir=./data

# Start with custom host and port
tusd -host 127.0.0.1 -port 1337 -upload-dir=./data

# Start with custom base path
tusd -base-path /api/uploads -upload-dir=./data

# Start with maximum upload size limit (1GB)
tusd -max-size 1000000000 -upload-dir=./data

# Start behind a reverse proxy
tusd -behind-proxy -upload-dir=./data

# Start with HTTPS/TLS
tusd -tls-certificate=server.pem -tls-key=server.key -port 8443 -upload-dir=./data
```

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

### Load a Plugin Hook

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Start the tusd binary while specifying the path to the compiled plugin binary.

```bash
$ tusd -hooks-plugin ./hook_handler
```

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

### File Hook Script Example (pre-create)

Source: https://context7.com/tus/tusd/llms.txt

An example shell script for a 'pre-create' file hook. It reads hook data from stdin and checks if the 'filename' metadata is present.

```bash
#!/bin/sh
# hooks/pre-create - Validate uploads before creation

# Read hook request from stdin
hasFilename="$(cat /dev/stdin | jq '.Event.Upload.MetaData | has("filename")')"

```

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

### Start tusd server

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/usage.md

Command to launch the tusd server with a specified upload directory.

```bash
$ tusd -upload-dir=./data
Using '/Users/marius/workspace/tus/tusd/data' as directory storage.
Using 0.00MB as maximum size.
Supported tus extensions: creation,creation-with-upload,termination,concatenation,creation-defer-length
Using 0.0.0.0:8080 as address to listen.
Using /files/ as the base path.
Using /metrics as the metrics path.
You can now upload files to: http://[::]:8080/files/
```

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

### Start tusd with gRPC Hooks (Bash)

Source: https://context7.com/tus/tusd/llms.txt

These bash commands show how to start the tusd server with gRPC hooks enabled, connecting to a specified address. The second command includes custom retry and backoff settings.

```bash
# Start tusd with gRPC hooks
tusd -hooks-grpc localhost:8081 -upload-dir=./data

# With custom retry settings
tusd -hooks-grpc localhost:8081 -hooks-grpc-retry 5 -hooks-grpc-backoff 2
```

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

### Start tusd with HTTPS Enabled

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Starts the tusd server with HTTPS enabled, using a specified certificate and private key. It configures the upload directory, host, port, and base path for file uploads.

```bash
# Start tusd
$ tusd -upload-dir=./data -host=127.0.0.1 -port=8443 -tls-certificate=localhost.pem -tls-key=localhost.key
[tusd] Using './data' as directory storage.
[tusd] Using 0.00MB as maximum size.
[tusd] Using 127.0.0.1:8443 as address to listen.
[tusd] Using /files/ as the base path.
[tusd] Using /metrics as the metrics path.
[tusd] Supported tus extensions: creation,creation-with-upload,termination,concatenation,creation-defer-length
[tusd] You can now upload files to: https://127.0.0.1:8443/files/

# tusd is now accessible via HTTPS

```

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

### Downloading Files via GET

Source: https://context7.com/tus/tusd/llms.txt

Retrieve a completed upload by sending a GET request to the upload URL.

```bash
# Download the uploaded file
curl -X GET http://localhost:8080/files/1881febb4343e9b806cad2e676989c0d \
  -o downloaded_file.txt
```

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

### Enable gRPC Hooks

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Start the tusd binary with the gRPC hook endpoint enabled.

```bash
$ tusd -hooks-grpc localhost:8081

[tusd] Using 'localhost:8081' as the endpoint for gRPC hooks
[tusd] Using './data' as directory storage.
...
```

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

### Configure AWS S3 Backend

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Set required environment variables and start tusd with the target bucket name.

```bash
$ export AWS_ACCESS_KEY_ID=xxxxx
$ export AWS_SECRET_ACCESS_KEY=xxxxx
$ export AWS_REGION=eu-west-1
$ tusd -s3-bucket=my-test-bucket.com
[tusd] 2019/09/29 21:11:23 Using 's3://my-test-bucket.com' as S3 bucket for storage.
...
```

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

### Annotated Hook Request Example (JSON)

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

This example shows the structure of a hook request, including upload details and HTTP request information. It is used by user-defined hooks to understand the current upload context.

```js
{
     // Hook that is executed, e.g. pre-create, post-create etc.
    "Type": "post-finish",

    "Event": {
        // Information about the associated upload.
        "Upload": {
            // Upload ID will be null for pre-create hook.
            "ID": "5d892c228ec8d0451dfec588697e8930",
            // Upload size in bytes can also be null if Upload-Defer-Lenth is used.
            "Size": 432724,
            // True if Upload-Defer-Length is used.
            "SizeIsDeferred": false,
            // Upload offset in bytes.
            "Offset": 432724,
            // Client-defined meta data. The values will always be strings. The values here
            // are just examples and will only be available if the tus client sets them.
            "MetaData": {
                "filename": "Screenshot 2023-08-17 at 09.00.40 1.png",
                "filetype": "image/png"
            },
            // IsPartial, IsFinal, PartialUploads indicate of the upload is part of a concatenated
            // upload using Upload-Concat.
            "IsPartial": false,
            "IsFinal": false,
            "PartialUploads": null,
            // Storage contains information about where the upload is stored. The exact values
            // depend on the storage that is used and are not available in the pre-create hook.
            "Storage": {
                 // For example, the filestore supplies the absolute file paths where the upload data
                 // (Path) and the associated info file (InfoPath) are stored:
                 "Type": "filestore",
                 "Path": "/my/upload/directory/14b1c4c77771671a8479bc0444bbc5ce",
                 "InfoPath": "/my/upload/directory/14b1c4c77771671a8479bc0444bbc5ce.info",

                 // The S3Store and GCSStore supply the bucket name and object key:
                 "Type": "s3store",
                 "Bucket": "my-upload-bucket",
                 "Key": "my-prefix/14b1c4c77771671a8479bc0444bbc5ce"
            }
        },

        // Information about the current, incoming HTTP request.
        "HTTPRequest": {
            "Method": "PATCH",
            "URI": "/files/5d892c228ec8d0451dfec588697e8930",
            // Client address that is connected to tusd. This might be the end-user or a
            // proxy depending on your setup.
            "RemoteAddr": "127.0.0.1:59395",
            // All headers that were included in the request. The values are arrays of strings because
            // headers can be included multiple times, e.g. Cookies.
            // The field names are canonicalized according to Go's rules: https://pkg.go.dev/net/http#CanonicalHeaderKey
            "Header": {
                "Host": [
                    "localhost:8080"
                ],
                "Tus-Resumable": [
                    "1.0.0"
                ],
                "User-Agent": [
                    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/116.0"
                ]
                // and more ...
            }
        }
    }
}
```

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

### Annotated Hook Response Example (JSON)

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

This example demonstrates the structure of a hook response, which can be used to influence the HTTP response sent back to the client. It is applicable to pre-create, pre-finish, and post-receive hooks.

```js
// All values are optional and can be left out
{
    // HTTPResponse's fields can be filled to modify the HTTP response.
    // This is only possible for pre-create, pre-finish and post-receive hooks.
    // For other hooks this value is ignored.
    // If multiple hooks modify the HTTP response, a later hook may overwrite the
    // modified values from a previous hook (e.g. if multiple post-receive hooks
    // are executed).
    // Example usages: Send an error to the client if RejectUpload/StopUpload are
    // set in the pre-create/post-receive hook. Send more information to the client
    // in the pre-finish hook.
    "HTTPResponse": {
        // StatusCode is status code, e.g. 200 or 400.
        "StatusCode": 400,
        // Body is the response body.
        "Body": "{\"message\":\"the upload is too big\"}"

```

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

### tusd Hook Response Examples

Source: https://context7.com/tus/tusd/llms.txt

Examples of hook responses for customizing upload behavior, including rejecting uploads, setting custom IDs, and modifying HTTP responses.

```json
// Reject upload with custom error
{
  "RejectUpload": true,
  "HTTPResponse": {
    "StatusCode": 403,
    "Body": "{\"error\":\"unauthorized\",\"message\":\"Invalid API key\"}",
    "Header": {
      "Content-Type": "application/json"
    }
  }
}
```

```json
// Set custom upload ID and metadata
{
  "ChangeFileInfo": {
    "ID": "user-123/project-456/document.pdf",
    "MetaData": {
      "filename": "document.pdf",
      "user_id": "123",
      "uploaded_at": "2024-01-15T10:30:00Z"
    },
    "Storage": {
      "Path": "user-123/project-456/document.pdf"
    }
  }
}
```

```json
// Stop in-progress upload
{
  "StopUpload": true,
  "HTTPResponse": {
    "StatusCode": 410,
    "Body": "Upload cancelled: project deleted"
  }
}
```

```json
// Add custom response headers in pre-finish hook
{
  "HTTPResponse": {
    "Header": {
      "X-Final-Location": "https://cdn.example.com/files/abc123",
      "X-Processing-Status": "queued"
    }
  }
}
```

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

### Python HTTP Hook Handler Example

Source: https://context7.com/tus/tusd/llms.txt

An example Python HTTP server implementing a handler for tusd upload events. It demonstrates validating uploads and processing completed uploads.

```python
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

class HookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        hook_request = json.loads(self.rfile.read(content_length))

        hook_response = {'HTTPResponse': {'Headers': {}}}

        # Validate uploads in pre-create hook
        if hook_request['Type'] == 'pre-create':
            metadata = hook_request['Event']['Upload']['MetaData']
            if 'filename' not in metadata:
                hook_response['RejectUpload'] = True
                hook_response['HTTPResponse']['StatusCode'] = 400
                hook_response['HTTPResponse']['Body'] = 'filename required'

        # Process completed uploads
        if hook_request['Type'] == 'post-finish':
            upload_id = hook_request['Event']['Upload']['ID']
            size = hook_request['Event']['Upload']['Size']
            storage = hook_request['Event']['Upload']['Storage']
            print(f'Upload {upload_id} ({size} bytes) completed')
            print(f'Storage location: {storage}')

        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps(hook_response).encode())

HTTPServer(('localhost', 8000), HookHandler).serve_forever()
```

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

### Docker Deployment of tusd

Source: https://context7.com/tus/tusd/llms.txt

Deploy tusd using Docker containers. Examples show configurations for local storage, S3 storage, and HTTP hooks.

```bash
# Run with local storage
docker run -d \
  -p 8080:8080 \
  -v /data/uploads:/data \
  tusproject/tusd:latest \
  -upload-dir=/data
```

```bash
# Run with S3 storage
docker run -d \
  -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
  -e AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  -e AWS_REGION=us-east-1 \
  tusproject/tusd:latest \
  -s3-bucket=my-upload-bucket
```

```bash
# Run with HTTP hooks
docker run -d \
  -p 8080:8080 \
  -v /data/uploads:/data \
  tusproject/tusd:latest \
  -upload-dir=/data \
  -hooks-http=http://host.docker.internal:8000/hooks
```

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

### Configure AWS S3 Storage for tusd

Source: https://context7.com/tus/tusd/llms.txt

Set AWS credentials and start tusd with S3 bucket configuration. Supports S3 Transfer Acceleration and S3-compatible services like MinIO.

```bash
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=eu-west-1
```

```bash
tusd -s3-bucket=my-upload-bucket
```

```bash
tusd -s3-bucket=my-upload-bucket -s3-object-prefix=uploads/
```

```bash
tusd -s3-bucket=my-upload-bucket -s3-transfer-acceleration
```

```bash
AWS_ACCESS_KEY_ID=minioadmin AWS_SECRET_ACCESS_KEY=minioadmin \
  tusd -s3-bucket=mybucket -s3-endpoint=http://localhost:9000
```

```bash
AWS_ACCESS_KEY_ID=<KEY_ID> AWS_SECRET_ACCESS_KEY=<SECRET_KEY> \
  tusd -s3-bucket=mybucket \
  -s3-endpoint=https://<ACCOUNT_ID>.r2.cloudflarestorage.com \
  -s3-min-part-size=52428800 -s3-part-size=52428800
```

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

### Configure File Hooks for tusd

Source: https://context7.com/tus/tusd/llms.txt

Start tusd with a directory containing local scripts to execute on upload events. Scripts receive hook data via stdin and environment variables.

```bash
tusd -hooks-dir ./hooks -upload-dir=./data
```

```bash
tusd -hooks-dir ./hooks -hooks-enabled-events pre-create,post-finish,post-receive
```

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

### Run tusd with Azurite Local Storage

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Configure and start tusd to use the local Azurite instance for Azure Blob Storage. Set the `AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_KEY` environment variables, and specify the Azure storage container and endpoint.

```sh
$ AZURE_STORAGE_ACCOUNT=devstoreaccount1 AZURE_STORAGE_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw== ./tusd -azure-storage=mycontainer -azure-endpoint=http://127.0.0.1:10000
```

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

### Configure JSON Hook Response

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Example of a JSON-encoded hook response structure used to control upload behavior.

```json
{
    // StopUpload will cause the upload to be stopped during a PATCH request.
    // This value is only respected for post-receive hooks. For other hooks,
    // it is ignored. Use the HTTPResponse field to send details about the stop
    // to the client.
    "StopUpload": true
}
```

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

### Customize Client Response with Pre-Finish Hook

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Use the `pre-finish` hook to modify the HTTP response sent to the client. This example shows how to add a `Link` header and stop the upload.

```json
{
    "HTTPResponse": {
        "Header": {
            "Link": "<https://example.com/files/12345>; rel=\"related\""
        },
    },

    "StopUpload": true,
}
```

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

### Identify NFS lock errors

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/local-disk.md

Example error message encountered when the filesystem does not support hard links required for upload locking.

```text
TemporaryErrors (Lockfile created, but doesn't exist)
```

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

### Start tusd with Cloudflare R2

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Configures tusd for Cloudflare R2 by setting the endpoint and aligning part sizes to meet R2's multipart upload requirements.

```sh
$ AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID> AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY> tusd -s3-bucket <YOUR_BUCKET_NAME> -s3-endpoint https://<ACCOUNT_ID>.r2.cloudflarestorage.com -s3-min-part-size 52428800 -s3-part-size 52428800
```

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

### tusd Prometheus Metrics Configuration

Source: https://context7.com/tus/tusd/llms.txt

Configure tusd to expose metrics in Prometheus format for monitoring. Examples show changing the metrics path and disabling metrics.

```bash
# Default metrics endpoint at /metrics
tusd -upload-dir=./data
```

```bash
# Custom metrics path
tusd -metrics-path /my/metrics -upload-dir=./data
```

```bash
# Disable metrics
tusd -expose-metrics=false -upload-dir=./data
```

```bash
# Scrape metrics
curl http://localhost:8080/metrics
```

```text
# Example output:
tusd_uploads_created_total 42
tusd_uploads_finished_total 38
tusd_uploads_terminated_total 2
tusd_errors_total{type="lock"} 0
tusd_errors_total{type="storage"} 1
```

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

### Embed tusd handler in Go program

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/usage-package.md

This snippet demonstrates how to embed the tusd handler into a Go application. It sets up a file store and a file locker, combines them in a StoreComposer, and then creates a tusd handler with a base path and upload completion notifications. Finally, it starts an HTTP server to listen for uploads.

```go
package main

import (
	"log"
	"net/http"

	"github.com/tus/tusd/v2/pkg/filelocker"
	"github.com/tus/tusd/v2/pkg/filestore"
	tusd "github.com/tus/tusd/v2/pkg/handler"
)

func main() {
	// Create a new FileStore instance which is responsible for
	// storing the uploaded file on disk in the specified directory.
	// This path _must_ exist before tusd will store uploads in it.
	// If you want to save them on a different medium, for example
	// a remote FTP server, you can implement your own storage backend
	// by implementing the tusd.DataStore interface.
	store := filestore.New("./uploads")

	// A locking mechanism helps preventing data loss or corruption from
	// parallel requests to a upload resource. A good match for the disk-based
	// storage is the filelocker package which uses disk-based file lock for
	// coordinating access.
	// More information is available at https://tus.github.io/tusd/advanced-topics/locks/.
	locker := filelocker.New("./uploads")

	// A storage backend for tusd may consist of multiple different parts which
	// handle upload creation, locking, termination and so on. The composer is a
	// place where all those separated pieces are joined together. In this example
	// we only use the file store but you may plug in multiple.
	composer := tusd.NewStoreComposer()
	store.UseIn(composer)
	locker.UseIn(composer)

	// Create a new HTTP handler for the tusd server by providing a configuration.
	// The StoreComposer property must be set to allow the handler to function.
	handler, err := tusd.NewHandler(tusd.Config{
		BasePath:              "/files/",
		StoreComposer:         composer,
		NotifyCompleteUploads: true,
	})
	if err != nil {
		log.Fatalf("unable to create handler: %s", err)
	}

	// Start another goroutine for receiving events from the handler whenever
	// an upload is completed. The event will contains details about the upload
	// itself and the relevant HTTP request.
	go func() {
		for {
			event := <-handler.CompleteUploads
			log.Printf("Upload %s finished\n", event.Upload.ID)
		}
	}()

	// Right now, nothing has happened since we need to start the HTTP server on
	// our own. In the end, tusd will start listening on and accept request at
	// http://localhost:8080/files
	http.Handle("/files/", http.StripPrefix("/files/", handler))
	http.Handle("/files", http.StripPrefix("/files", handler))
	err = http.ListenAndServe(":8080", nil)
	if err != nil {
		log.Fatalf("unable to listen: %s", err)
	}
}

```

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

### Configure MinIO Client and Create Bucket

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Sets up the MinIO client alias and creates a new bucket named 'mybucket'.

```sh
$ mc alias set myminio http://localhost:9000 AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ mc mb myminio/mybucket
```

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

### Compile tusd from source

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/installation.md

Clone the repository and build the binary using the Go toolchain.

```bash
git clone https://github.com/tus/tusd.git
cd tusd

go build -o tusd cmd/tusd/main.go
# The binary is saved in ./tusd
```

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

### Configure tus-java-client

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/usage.md

Set the upload creation URL using the TusClient#setUploadCreationURL method.

```java
TusClient client = new TusClient();

// Replace this with tusd's upload creation URL
client.setUploadCreationURL(new URL("http://localhost:8080/files/"));

File file = new File("./cute_kitten.png");
final TusUpload upload = new TusUpload(file);
```

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

### Configure Azure Blob Storage Backend

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Sets the required environment variables and launches tusd with the specified Azure container.

```bash
$ export AZURE_STORAGE_ACCOUNT=xxxxx
$ export AZURE_STORAGE_KEY=xxxxx # for key-based authentication
$ tusd -azure-storage=my-test-container
[tusd] 2024/02/23 11:34:03.411021 Using Azure endpoint https://xxxxx.blob.core.windows.net.
...
```

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

### Configure TUSKit

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/usage.md

Pass the upload creation URL to the TUSClient initializer.

```swift
final class MyClass {
  let tusClient: TUSClient
  
  init() {
    tusClient = TUSClient(
      // Replace this with tusd's upload creation URL
      server: URL(string: "http://localhost:8080/files/")!,
      sessionIdentifier: "TUS DEMO",
      storageDirectory: URL(string: "TUS")!
    )
    tusClient.delegate = self
  }
}
```

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

### Downloading Uploaded Files (GET)

Source: https://context7.com/tus/tusd/llms.txt

Allows retrieval of a completed upload. This functionality can be disabled server-side.

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

### Description
Retrieve a completed upload by sending a GET request to the upload URL. This feature can be disabled with the `-disable-download` flag.

### Method
GET

### Endpoint
/files/{id}

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

### Response
#### Success Response (200 OK)
- **Content-Length** (string) - The total size of the file in bytes.
- **Content-Type** (string) - The MIME type of the file.

#### Response Example
```
HTTP/1.1 200 OK
Content-Length: 1048576
Content-Type: application/octet-stream
```
```

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

### Disable file downloads

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Prevents users from retrieving uploaded files via HTTP GET requests.

```bash
$ tusd -disable-download
```

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

### Creating an Upload via POST

Source: https://context7.com/tus/tusd/llms.txt

Initiate a new upload by sending a POST request to the server. You can specify the total file size or use deferred length for unknown sizes.

```bash
# Create a new upload with size and metadata
curl -X POST http://localhost:8080/files/ \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 1048576" \
  -H "Upload-Metadata: filename d29ybGQudHh0,filetype dGV4dC9wbGFpbg==" \
  -i

# Create upload with deferred length (size unknown)
curl -X POST http://localhost:8080/files/ \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Defer-Length: 1" \
  -i
```

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

### Initiate tus upload with metadata

Source: https://github.com/tus/tusd/wiki/Uploading-to-Transloadit-using-tus

Use this HTTP POST request to initialize a tus upload. Ensure the Upload-Metadata header includes base64-encoded assembly_url, filename, and fieldname.

```http
POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 24213
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzLzE0YjFiNDkwNDQ3ZDExZTZhYmE0NzU2YjNlOWQzYTBk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==
```

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

### Create Docker secrets for credentials

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/installation.md

Use printf to create secrets for services like Minio in Docker Swarm mode.

```bash
printf "minio" | docker secret create minio-username -
printf "miniosecret" | docker secret create minio-password -
```

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

### tusd CORS Configuration

Source: https://context7.com/tus/tusd/llms.txt

Configure Cross-Origin Resource Sharing (CORS) for tusd. Examples demonstrate restricting origins, allowing credentials, and disabling CORS.

```bash
# Restrict allowed origins
tusd -cors-allow-origin 'https://example.com' -upload-dir=./data
```

```bash
# Allow credentials in cross-origin requests
tusd -cors-allow-credentials -cors-allow-origin 'https://example.com'
```

```bash
# Add custom headers to CORS configuration
tusd -cors-allow-headers X-Auth-Token \
  -cors-expose-headers X-Upload-Location \
  -cors-max-age 3600
```

```bash
# Disable CORS handling (handle in reverse proxy)
tusd -disable-cors
```

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

### Create Azure Container with Azure CLI

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Use the Azure CLI to create a container named 'mycontainer' for testing with Azurite. This command requires the well-known storage account name and key, and the Azurite blob endpoint.

```sh
$ az storage container create --name mycontainer --connection-string "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
```

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

### Creating an Upload (POST)

Source: https://context7.com/tus/tusd/llms.txt

Initiates a new upload process. Clients specify the total file size and optional metadata. The server responds with a unique upload URL.

```APIDOC
## POST /files/

### Description
Create a new upload by sending a POST request to the upload creation endpoint. The client specifies the total file size and optional metadata.

### Method
POST

### Endpoint
/files/

### Parameters
#### Request Body
- **Upload-Length** (integer) - Required - The total size of the file in bytes.
- **Upload-Defer-Length** (integer) - Optional - Set to `1` if the file size is not known at the time of creation.
- **Upload-Metadata** (string) - Optional - Key-value pairs of metadata, base64 encoded.

### Request Example
```bash
curl -X POST http://localhost:8080/files/ \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 1048576" \
  -H "Upload-Metadata: filename d29ybGQudHh0,filetype dGV4dC9wbGFpbg==" \
  -i
```

### Response
#### Success Response (201 Created)
- **Location** (string) - The URL for the newly created upload.
- **Upload-Defer-Length** (string) - Indicates if deferred length was used.
- **Upload-Offset** (string) - The current offset of the upload, typically `0` for new uploads.

#### Response Example
```
HTTP/1.1 201 Created
Location: http://localhost:8080/files/1881febb4343e9b806cad2e676989c0d
Tus-Resumable: 1.0.0
Upload-Offset: 0
```
```

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

### Configure Alternative S3 Endpoints

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Use the -s3-endpoint flag to connect to S3-compatible services like Minio. The endpoint must include the protocol prefix.

```bash
$ tusd -s3-bucket=my-test-bucket.com -s3-endpoint https://mystoreage.example.com
2024/02/20 15:33:45.474497 Using 'https://mystoreage.example.com/my-test-bucket.com' as S3 endpoint and bucket for storage.
...
```

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

### Configure HTTP Hooks for tusd

Source: https://context7.com/tus/tusd/llms.txt

Start tusd with an HTTP hook endpoint to receive upload event notifications. Supports custom timeouts, retries, backoff, and forwarding headers.

```bash
tusd -hooks-http http://localhost:8000/hooks -upload-dir=./data
```

```bash
tusd -hooks-http http://localhost:8000/hooks \
  -hooks-http-timeout 30000 \
  -hooks-http-retry 5 \
  -hooks-http-backoff 2
```

```bash
tusd -hooks-http http://localhost:8000/hooks \
  -hooks-http-forward-headers Cookie,Authorization
```

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

### Authenticate with Storage Account Key

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Uses the storage account key for authentication, granting full access to all containers in the account.

```bash
$ export AZURE_STORAGE_ACCOUNT=xxxxx
$ export AZURE_STORAGE_KEY=xxxxx # mandatory for key-based authentication
$ tusd -azure-storage=my-test-container
[tusd] 2024/02/23 11:34:03.411021 Using Azure endpoint https://xxxxx.blob.core.windows.net.
...
```

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

### Enable proxy support

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Informs the server that it is running behind a reverse proxy and should respect forwarded headers.

```bash
$ tusd -behind-proxy
```

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

### Configure network host and port

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Sets the interface and port for the tusd server to listen on.

```bash
$ tusd -host 127.0.0.1 -port 1337
```

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

### Enable File Hooks

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Command to enable the file hook system by specifying the directory containing executable hook files.

```bash
$ tusd -hooks-dir ./path/to/hooks/

[tusd] Using './path/to/hooks/' for hooks
[tusd] Using './data' as directory storage.
...
```

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

### Configure GCS with Service Account

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/google-cloud-storage.md

Use a service account file for authentication by setting the GCS_SERVICE_ACCOUNT_FILE environment variable. This is an alternative to Application Default Credentials.

```bash
$ export GCS_SERVICE_ACCOUNT_FILE=./account.json
$ tusd -gcs-bucket=my-test-bucket.com
[tusd] Using 'gcs://my-test-bucket.com' as GCS bucket for storage.
...
```

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

### Configure Uppy

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/usage.md

Pass the upload creation URL to the Tus plugin endpoint option.

```js
new Uppy()
  .use(Dashboard, { inline: true, target: 'body' })
  // Replace this with tusd's upload creation URL
  .use(Tus, { endpoint: 'http://localhost:8080/files/' });
```

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

### Configure base path

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Customizes the URL path prefix for upload creation endpoints.

```bash
# Upload creation at http://localhost:8080/api/uploads/
$ tusd -base-path /api/uploads
# Upload creation at http://localhost:8080/
$ tusd -base-path /
```

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

### Run tusd with Docker

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/installation.md

Pull the latest image and execute the container with optional CLI flags.

```bash
docker pull tusproject/tusd:latest
docker run tusproject/tusd:latest # append CLI flags for tusd here, for example:
# docker run tusproject/tusd:latest -s3-bucket=my-bucket
```

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

### Configure Google Cloud Storage Backend for tusd

Source: https://context7.com/tus/tusd/llms.txt

Use tusd with Google Cloud Storage by specifying the bucket name. Supports Application Default Credentials or a service account file.

```bash
tusd -gcs-bucket=my-gcs-bucket
```

```bash
export GCS_SERVICE_ACCOUNT_FILE=./service-account.json
tusd -gcs-bucket=my-gcs-bucket
```

```bash
tusd -gcs-bucket=my-gcs-bucket -gcs-object-prefix=uploads/
```

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

### Create Resumable Assembly Request

Source: https://github.com/tus/tusd/wiki/Uploading-to-Transloadit-using-tus

Send a POST request to the /assemblies endpoint with multipart-encoded parameters, including 'params' for authentication and instructions, and 'num_expected_upload_files' to specify the number of tus uploads.

```http
POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03

------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"

{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"

2
------WebKitFormBoundaryIAWBI8vxocZzsG03--
```

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

### Configure tus-js-client

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/usage.md

Pass the upload creation URL to the endpoint option in the tus.Upload constructor.

```js
const upload = new tus.Upload(file, {
  // Replace this with tusd's upload creation URL
  endpoint: 'http://localhost:8080/files/',

  onError: function (error) {
    console.log('Failed because: ' + error)
  },
  onSuccess: function () {
    console.log('Download %s from %s', upload.file.name, upload.url)
  },
})

upload.start()
```

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

### Enable S3 Transfer Acceleration

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/aws-s3.md

Use the -s3-transfer-acceleration flag to utilize AWS S3 Transfer Acceleration endpoints.

```bash
$ tusd -s3-bucket=my-test-bucket.com -s3-transfer-acceleration
[tusd] 2019/09/29 21:11:23 Using 's3://my-test-bucket.com' as S3 bucket for storage with AWS S3 Transfer Acceleration enabled.
...
```

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

### JavaScript Client Integration with tus-js-client

Source: https://context7.com/tus/tusd/llms.txt

This JavaScript snippet demonstrates how to use the tus-js-client library to upload a file. It includes configuration for the endpoint, retry delays, metadata, and event handlers for progress, errors, and success. It also shows how to find and resume previous uploads.

```javascript
import * as tus from 'tus-js-client'

const file = document.querySelector('input[type=file]').files[0]

const upload = new tus.Upload(file, {
  endpoint: 'http://localhost:8080/files/',
  retryDelays: [0, 3000, 5000, 10000, 20000],
  metadata: {
    filename: file.name,
    filetype: file.type
  },
  onError: function(error) {
    console.log('Upload failed:', error)
  },
  onProgress: function(bytesUploaded, bytesTotal) {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2)
    console.log(`Progress: ${percentage}%`)
  },
  onSuccess: function() {
    console.log('Upload complete!')
    console.log('Download URL:', upload.url)
  }
})

// Check for previous uploads and resume if found
upload.findPreviousUploads().then(function(previousUploads) {
  if (previousUploads.length) {
    upload.resumeFromPreviousUpload(previousUploads[0])
  }
  upload.start()
})
```

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

### Configure custom Azure endpoint

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/azure-blob-storage.md

Uses the -azure-endpoint flag to point tusd to a custom storage service, such as Azurite for local development.

```bash
$ tusd -azure-storage=my-test-container -azure-endpoint=https://my-custom-endpoint.com
[tusd] 2023/02/13 16:15:18.641937 Using Azure endpoint https://my-custom-endpoint.com.
...
```

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

### Enable HTTP(S) Hooks

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Command to enable HTTP(S) hooks by providing the endpoint URL for POST requests.

```bash
$ tusd -hooks-http http://localhost:8081/write

[tusd] Using 'http://localhost:8081/write' as the endpoint for hooks
[tusd] Using './data' as directory storage.
...
```

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

### Configure local upload directory

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/local-disk.md

Specifies the directory for file storage using the -upload-dir flag.

```sh
$ tusd -upload-dir=./uploads
```

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

### Customize storage paths via pre-create hook

Source: https://github.com/tus/tusd/blob/main/docs/_storage-backends/local-disk.md

Defines custom paths for upload IDs and storage files using a JSON hook response.

```json
{
    "ChangeFileInfo": {
        "ID": "project-123/abc",
        "Storage": {
            "Path": "project-123/abc/presentation.pdf"
        }
    },
}
```

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

### Generate Self-Signed Certificate with OpenSSL

Source: https://github.com/tus/tusd/blob/main/docs/_getting-started/configuration.md

Generates a self-signed certificate and private key for localhost, suitable for development and testing purposes. This certificate is not recommended for production environments.

```bash
# Generate self-signed certificate
$ openssl req -x509 -new -newkey rsa:4096 -nodes -sha256 -days 3650 -keyout localhost.key -out localhost.pem -subj "/CN=localhost"
Generating a 4096 bit RSA private key
........................++
..........................................++
writing new private key to 'localhost.key'

```

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

### Reject Upload via pre-create Hook

Source: https://github.com/tus/tusd/blob/main/docs/_advanced-topics/hooks.md

Use this response structure in a pre-create hook to reject an upload due to invalid metadata or authentication failure.

```json
{
    "HTTPResponse": {
        "StatusCode": 400,
        "Body": "{\"message\":\"no project with ID 1234 found\"}",
        "Header": {
            "Content-Type": "application/json"
        },
    },

    "RejectUpload": true,
}
```

```json
{
    "HTTPResponse": {
        "StatusCode": 403,
        "Body": "{\"message\":\"authentication failed\"}",
        "Header": {
            "Content-Type": "application/json"
        },
    },

    "RejectUpload": true,
}
```

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

### Configure Azure Blob Storage Backend for tusd

Source: https://context7.com/tus/tusd/llms.txt

Set up tusd to store uploads in Azure Blob Storage. Supports storage account keys, Entra ID authentication, custom endpoints, and storage tiers.

```bash
export AZURE_STORAGE_ACCOUNT=mystorageaccount
export AZURE_STORAGE_KEY=myaccountkey
tusd -azure-storage=my-container
```

```bash
az login
export AZURE_STORAGE_ACCOUNT=mystorageaccount
export AZURE_STORAGE_KEY=""
tusd -azure-storage=my-container
```

```bash
AZURE_STORAGE_ACCOUNT=devstoreaccount1 \
AZURE_STORAGE_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw== \
  tusd -azure-storage=mycontainer -azure-endpoint=http://127.0.0.1:10000
```

```bash
tusd -azure-storage=my-container -azure-blob-access-tier=cool
```