Appearance
TUS Resumable Upload
Overview
ODP supports the TUS resumable upload protocol for large file uploads. TUS allows uploads to be paused and resumed, making it reliable for large files or slow connections.
The TUS endpoint is at /tus and is implemented using the @tus/server library backed by a custom TusDataStore that integrates with ODP's file system.
Protocol Summary
TUS uses a series of HTTP requests to upload a file in chunks:
- POST /tus — Create upload: sends metadata, gets back upload URL
- HEAD /tus/:id — Check upload offset (resume from last position)
- PATCH /tus/:id — Upload chunk(s) of the file
- DELETE /tus/:id — Cancel an in-progress upload
Authentication
All TUS endpoints require the caller to have either app_access or admin_access.
Authorization: Bearer <access_token>Unauthenticated requests receive 403 Forbidden.
POST /tus is authorized like POST /files (create permission on odp_files, field and validation rules) before any byte is stored, so a rejected upload leaves nothing on storage. HEAD, PATCH and DELETE /tus/:id are allowed only for the user who created the upload, or an admin. Anyone else gets 404 Upload not found, the same answer as for a missing upload.
Endpoints
OPTIONS /tus
Preflight/discovery. Returns TUS server capabilities.
Response Headers:
Tus-Resumable: 1.0.0Tus-Version: 1.0.0Tus-Max-Size: <FILES_MAX_UPLOAD_SIZE in bytes>Tus-Extension: creation,termination
POST /tus
Create a new upload.
Request Headers:
Authorization: Bearer <access_token>
Content-Length: 0
Upload-Length: 10485760
Upload-Metadata: filename d29ya2Zsb3cucGRm,type YXBwbGljYXRpb24vcGRm| Header | Description |
|---|---|
Upload-Length | Total file size in bytes |
Upload-Metadata | Base64-encoded key-value pairs (filename, type, filetype, etc.) |
Upload-Metadata Keys:
| Key | Description |
|---|---|
filename | Base64-encoded original filename |
type / filetype | MIME type of the file |
title | Base64-encoded display title |
description | Base64-encoded description |
folder | Base64-encoded folder UUID |
storage | Base64-encoded storage name. Omitted = the default storage. An unknown or inactive storage returns 400 (see Storage Providers) |
MIME Type Validation: If FILES_MIME_TYPE_ALLOW_LIST is set (not *), the type that is stored is checked against the allow list: the type resolved from the filename extension, or the declared type / filetype when the extension gives none. Rejected types return 400 Bad Request.
Response:
HTTP/1.1 201 Created
Location: https://api.example.com/api/tus/upload-uuid
Tus-Resumable: 1.0.0The Location header contains the URL for subsequent PATCH requests.
HEAD /tus/:id
Check the current upload offset (for resuming).
Request Headers:
Authorization: Bearer <access_token>
Tus-Resumable: 1.0.0Response:
HTTP/1.1 200 OK
Upload-Offset: 5242880
Upload-Length: 10485760
Tus-Resumable: 1.0.0PATCH /tus/:id
Upload a chunk of the file.
Request Headers:
Authorization: Bearer <access_token>
Content-Type: application/offset+octet-stream
Upload-Offset: 0
Content-Length: 5242880Request Body: Raw binary chunk starting at Upload-Offset.
Response (chunk accepted):
HTTP/1.1 204 No Content
Upload-Offset: 5242880
Tus-Resumable: 1.0.0Response (upload complete):
HTTP/1.1 204 No Content
Upload-Offset: 10485760
X-File-Id: <odp-file-uuid>
Tus-Resumable: 1.0.0The odp_files record is created at POST /tus (with tus_id set and filesize 0), from Upload-Metadata. When Upload-Offset == Upload-Length, the upload is finalized:
- The
TusDataStorecompletes the file on the configured storage driver - The record's
tus_id/tus_dataare cleared and its final size (and image dimensions) are written - The response carries the
X-File-Idheader
DELETE /tus/:id
Cancel an in-progress upload.
Response: 204 No Content
Cleans up partial upload data. The corresponding odp_files record (if partially created) is also cleaned up.
Complete Upload Flow
Upload Expiration
Incomplete uploads that have not been updated within TUS_UPLOAD_EXPIRATION are automatically cleaned up by a scheduled job (cron schedule: TUS_CLEANUP_SCHEDULE).
Configuration
| Variable | Default | Description |
|---|---|---|
FILES_MAX_UPLOAD_SIZE | 10mb | Maximum file size per upload |
FILES_MIME_TYPE_ALLOW_LIST | * | Comma-separated allowed MIME types, or * for all |
FILES_MAX_UPLOAD_CONCURRENCY | 5 | Maximum concurrent uploads |
TUS_UPLOAD_EXPIRATION | 10m | Incomplete upload TTL |
TUS_CLEANUP_SCHEDULE | 0 */6 * * * | Cron schedule for cleanup job (every 6 hours) |
STORAGE_LOCAL_ROOT | ./uploads | Local storage root directory |
Example: JavaScript TUS Client
javascript
import * as tus from 'tus-js-client';
const upload = new tus.Upload(file, {
endpoint: 'https://api.example.com/api/tus',
headers: {
Authorization: 'Bearer ' + accessToken,
},
metadata: {
filename: file.name,
type: file.type,
folder: 'folder-uuid',
},
chunkSize: 5 * 1024 * 1024, // 5MB chunks
retryDelays: [0, 1000, 3000, 5000],
onSuccess: () => {
// Get file UUID from response header
const fileId = upload.url.split('/').pop();
console.log('Upload complete, file ID:', fileId);
},
onError: (error) => console.error('Upload failed:', error),
onProgress: (uploaded, total) => {
console.log(`${Math.round(uploaded / total * 100)}%`);
},
});
upload.start();