Skip to content

ADR-0012: storage/tus dependency choice

  • Status: Accepted
  • Date: 2026-06-19
  • Deciders: @lusoris
  • Tags: storage, uploads, tus

Context

The storage/tus module needs a dependency. Per principles.md §2 the choice must favour a maintained, server-appropriate library with a lean footprint, justified against ecosystem alternatives.

Decision

Use github.com/tus/tusd/v2/pkg/handler (v2.10.1). tusd v2 is the maintained reference tus 1.0 server in Go. The catalog hint does not mean the tusd binary: we import only github.com/tus/tusd/v2/pkg/handler, the embeddable protocol engine, and back it with a thin DataStore adapter over our existing storage.Bucket. Fit for a server framework: slogbridge.go adapts tusd's x/exp/slog logger into the framework's stdlib log/slog sink, NewUnroutedHandler exposes per-method handlers that map 1:1 onto chi (no StripPrefix, app middleware preserved), and it is storage-agnostic so we avoid tusd's filestore/s3store/gcsstore (which would duplicate storage/ and drag in their own SDKs). Footprint is small (stdlib + x/* + tusd internals); MIT, same as our tree. Hand-writing the full tus protocol + extensions is hundreds of lines of security-sensitive parsing best owned by an audited reference implementation.

Alternatives considered

Option Pros Cons Why not chosen
Hand-rolled tus handler — Large security-critical HTTP surface (offset races, version negotiation, base64 metadata, multiple extensions); high int not chosen
tusd full server pkg/filestore+s3store / cmd — Heavy and redundant: ships its own FS/S3/GCS/Azure stores + lockers that duplicate our storage.Bucket and pull extra clo not chosen
eventials/go-tus — Client-only and abandoned; no server http.Handler. not chosen
bdragon300/tusgo — Modern but client-only; useful as a test client, not as the server dependency. not chosen
vimeo/tusd fork — Downstream fork, less current than upstream tus/tusd v2; no reason to prefer over the canonical actively-released upstre not chosen

Consequences

See storage/tus/AGENTS.md for the resulting API + config surface. The dependency is pinned and tracked by Renovate; revisit if it goes unmaintained or a better-fit library appears.