v0.0.5

v0.0.5 — TUS Extensions, ASGI, Locks, Metrics, CLI

Adds four TUS protocol extensions, ASGI/CLI entrypoints, distributed-friendly locking, and first-class observability.

✨ Highlights

TUS protocol extensions

• Concatenation extension — Upload-Concat: partial / final. Split uploads and merge server-side across all backends (SQLite, S3, GCS, Azure).
• Upload-Defer-Length extension — create with Upload-Defer-Length: 1 and supply the length on a later PATCH.
• Multi-algorithm checksum — Upload-Checksum now accepts sha1, sha256, md5, and crc32.
• X-HTTP-Method-Override — allow PATCH/DELETE tunneled through POST for restrictive proxies.

New interfaces

• TusASGIApp — mount directly into FastAPI / Starlette / uvicorn stacks.
• CLI — resumable-upload serve to launch a server in one command.

Scale-out & concurrency

• LockBackend — pluggable locking with InMemory (default) and Redis backends, making concurrent PATCH safe across multiple workers.
• Parallel uploads — TusClient(parallel_uploads=N) splits a file into N partial uploads transferred concurrently, then concatenates into the final upload.

Observability

• Prometheus metrics — /metrics endpoint with upload counters and histograms.
• Client hooks — retry and progress callbacks for instrumentation.

Storage & fingerprinting

• PartialMD5 fingerprint plus support for arbitrary Callable fingerprints — much faster resume on large files.
• URLStorage backends — InMemoryURLStorage and SQLiteURLStorage enable cross-session resume on the client.

🐛 Fixes

• fix(server): apply Upload-Expires to concatenated final uploads (31eeebf).
• fix(server): preserve legacy Storage subclass compatibility (0e4a673).

🧰 Chores

• Scope ty type checking to the resumable_upload package (1f904da).
• Examples reorganized into examples/server/ and examples/client/, with new demos for error handling and success messaging.

📦 Install

pip install -U resumable-upload

# Cloud backends:
pip install -U "resumable-upload[s3]"      # boto3
pip install -U "resumable-upload[gcs]"     # google-cloud-storage
pip install -U "resumable-upload[azure]"   # azure-storage-blob

# Redis lock backend:
pip install -U "resumable-upload[redis]"

Full Changelog: v0.0.4...v0.0.5

v0.0.4

New Features

• Server Hooks: Added event hook system for request interception and upload lifecycle
  • on_incoming_request: Gate requests before processing (e.g., auth, rate limiting). Raise TusHookError to reject.
  • on_upload_create: Validate or replace metadata before upload creation. Raise TusHookError to reject.
  • on_upload_complete: React after upload finishes (e.g., post-processing, notifications). Exceptions logged only.
  • on_upload_terminate: React after upload deletion (e.g., cleanup). Exceptions logged only.
  • New TusHookError(status_code, body) exception for rejecting requests with custom status codes
• S3 Storage Backend: Added S3Storage using S3 multipart upload API with buffer-and-flush strategy
  • Install with pip install resumable-upload[s3]
• GCS Storage Backend: Added GCSStorage using Google Cloud Storage compose API with hierarchical composition for large uploads
  • Install with pip install resumable-upload[gcs]
• Azure Storage Backend: Added AzureBlobStorage using Azure Block Blobs with staged blocks
  • Install with pip install resumable-upload[azure]
• All three cloud backends implement the Storage ABC as drop-in replacements for SQLiteStorage
• Install all cloud backends at once with pip install resumable-upload[all-storage]

Documentation

• Added cloud storage backends documentation with parameters, usage examples, and installation instructions
• Added server hooks documentation with hook table and code examples
• Added TusHookError to exceptions reference

CI

• Split docs workflow into separate build and deploy jobs

Full Changelog: v0.0.3...v0.0.4

v0.0.3

Bug Fixes

• Storage: Fixed DB connection leaks on exception via try/finally
• Storage: Atomized offset update with a single SQL statement — prevents race condition under concurrent requests
• Storage: Added per-upload file lock (threading.Lock + fcntl.flock) — safe chunk writes in multi-threaded and multi-process environments
• Client: Fixed missing URLError handling (timeouts, connection drops) in all network calls
• Client: Added timeout parameter to all urlopen() calls (default 30s)
• Client: On 409 Conflict, client now re-syncs offset via HEAD request before retrying the chunk
• Uploader: stop_at is now clamped to file size automatically
• Fingerprint: Replaced MD5 with SHA-256 for full-file hashing — fixes incorrect fingerprint when files differ only after the first 64 KB
• URL Storage: Added threading.Lock to set_url() / remove_url() — prevents URL entry loss under concurrent access
• Server: Strengthened request validation
  • Upload-Metadata larger than 4 KB returns 400 (DoS protection)
  • Invalid base64 in metadata returns 400
  • Negative Content-Length returns 400
  • Socket timeout applied in TusHTTPRequestHandler (Slowloris protection, default 30s)
  • Fixed concurrency bug in expired upload cleanup scheduler

New Features

• Uploader: Added stop_event parameter — pass a threading.Event to cancel an upload cleanly from another thread
• Server: Added TUS extensions: expiration, creation-with-upload
• Examples: Configurable port for server examples

Documentation

• Built a documentation site with MkDocs (Material theme) → https://sts07142.github.io/resumable-upload/
  • Sections: Advanced Usage, Web Frameworks, API Reference, TUS Compliance
• Updated TUS protocol compliance document
• Synced Korean README with English

⚠️ Breaking Change

The fingerprint algorithm has changed from MD5 to SHA-256. Any upload URLs previously saved in .tus_urls.json (when using store_url=True) will no longer match and must be re-uploaded. Delete the file to start fresh.

Full Changelog: v0.0.2...v0.0.3

v0.0.2

Summary

This release includes code quality improvements, enhanced error handling, and documentation updates.

Key Changes

Code Quality

• Moved imports to top of files (time, base64, binascii, URLError)
• Improved error handling with specific exception types
• Added safe handling for edge cases in retry logic

Statistics Tracking

• Centralized stats calculation logic
• Improved consistency of chunk completion tracking

Documentation

• Updated README examples to match current API
• Fixed progress_callback signature documentation (now uses UploadStats)
• Added missing method documentation

Testing

• Improved tox configuration for better compatibility
• Fixed pytest execution in tox environments

Migration Guide

If migrating from development versions:

1. Progress callbacks now receive UploadStats object:

   # Update your callback
   def progress(stats: UploadStats):
       print(f"{stats.progress_percent:.1f}%")

2. Retry functionality is now built into TusClient:

   client = TusClient(url, max_retries=3)  # retry enabled by default

Full Changelog: v0.0.1...v0.0.2

v0.0.1

Initial Release

A Python implementation of the TUS resumable upload protocol v1.0.0 for server and client, with zero runtime dependencies.

✨ Features

• 🚀 Zero Dependencies: Built using Python standard library only (no external dependencies for core functionality)
• 📦 Server & Client: Complete implementation of both sides
• 🔄 Resume Capability: Automatically resume interrupted uploads
• ✅ Data Integrity: Optional SHA1 checksum verification
• 🔁 Retry Logic: Built-in automatic retry with exponential backoff
• 📊 Progress Tracking: Detailed upload progress callbacks with stats
• 🌐 Web Framework Support: Integration examples for Flask, FastAPI, and Django
• 🐍 Python 3.9+: Supports Python 3.9 through 3.14
• 🏪 Storage Backend: SQLite-based storage (extensible to other backends)
• 🔐 TLS Support: Certificate verification control and mTLS authentication
• 📝 URL Storage: Persist upload URLs across sessions
• 🎯 TUS Protocol Compliant: Implements TUS v1.0.0 core protocol with creation, termination, and checksum extensions