TUS Client

UploadSource abstracts where upload bytes come from. Two are built in:

A custom UploadSource (database blob, another network stream, etc.) is free to report replayable() == true if slice(offset) genuinely produces correct, independent data on every call and from any offset — that’s what unlocks the features below.

Setting checksumAlgorithm (per-request or via quarkus.tus.client.checksum-algorithm) makes the client digest each chunk and send it as Upload-Checksum on the PATCH that carries it, so the server can reject a corrupted chunk before it’s persisted.

Because the TUS checksum extension puts the digest in a request header rather than a trailer, the digest has to be known before the PATCH is sent. The client collects each chunk into one Buffer bounded at chunkSize before digesting and sending it — a deliberate, bounded buffer (one chunk’s worth, never the whole upload), not accidental whole-upload buffering. Keep chunkSize sized accordingly if checksum is enabled for very large uploads.

When the total size isn’t known up front (e.g. streaming from a process whose output length is unknown until it ends), leave the source’s length() at -1. The client issues a creation-defer-length POST, uploads chunks without a declared total, and once the upstream source signals completion sends one final, empty-bodied PATCH that declares the confirmed Upload-Length.

Defer-length and parallelism > 1 are mutually exclusive: parallel upload needs a known length up front to split into ranges, so requesting both fails eagerly with a TusClientException.

Setting parallelism > 1 (per-request or via quarkus.tus.client.parallelism) splits a replayable, known-length source into that many byte ranges, uploads each as its own partial upload concurrently, and merges them with a final concatenation POST once every partial has arrived — transparent to the caller, who still just gets back one TusUploadResult.

This requires the target server to advertise the concatenation extension; if it doesn’t, the client fails with a TusCapabilityException naming concatenation as the missing extension rather than attempting partial uploads the server can’t merge. See Parallel Uploads for how the protocol itself works.

TusRequestCustomizer is a hook to add or override headers on every outgoing request — the usual use is attaching an Authorization header.

Only one TusRequestCustomizer bean may be present when using CDI injection; a second one makes the injected TusClient an unavailable shim (see above) rather than picking one arbitrarily. Building TusClientOptions programmatically sidesteps that ambiguity entirely, since the customizer is passed explicitly.

TusRequestCustomizer only touches headers. Anything that lives on the underlying Vert.x HttpClient — trusting a private CA, going through an egress proxy, sizing the connection pool — goes through TusHttpClientCustomizer, which is handed the HttpClientOptions the client is built from, once, at client creation.

Programmatically: TusClientOptions.builder(url).httpClientOptions(options → …​). The configured connect-timeout is applied before the hook runs, so the hook can override it. As with TusRequestCustomizer, exactly one bean may be present under CDI.

Failures surface as subclasses of TusClientException, mapped from the server’s status:

A failure that isn’t a TusClientException at all (a reset connection, a timeout) is treated as I/O-level and retried too. A missing capability is a TusCapabilityException naming the extension, thrown before any upload request goes out.

A retry waits min(retry-backoff × 2^n, retry-backoff-max), re-reads the server’s offset with a HEAD, and resumes from there. The HEAD is under the same budget: if it fails retryably as well, that counts as one more consecutive failure and is backed off and re-issued. max-retries bounds consecutive failures — a successful chunk resets the count — so a long upload that hits an occasional transient error keeps going. Retry needs a replayable source; see One-shot Degradation.

Cancelling the returned Uni stops the loop: no further PATCH is issued and the source is released. The PATCH already on the wire is not aborted — a cancelled Mutiny Uni over the Vert.x client only stops listening for the response — so the server may still apply that one chunk. The upload URL is left for the server’s expiration to reclaim (or tusClient.protocol().terminate(url) to remove now).

All client configuration is under the quarkus.tus.client prefix, and every property is a runtime property (overridable via application.properties, environment variables, or system properties). Every one of them has a counterpart on TusClientOptions for programmatic construction; only chunk-size, checksum-algorithm and parallelism can additionally be overridden per request on TusUploadRequest.

Memory: one chunk is held in memory per in-flight PATCH — the checksum path collects it to digest it, and the plain path holds at most that much in the request pipeline — so the heap footprint of an upload is roughly parallelism × chunk-size. A 10 MB chunk with parallelism=4 is about 40 MB.