Quarkus TUS

A Quarkus extension implementing the TUS resumable upload protocol (v1.0.0).

Features

• Full TUS v1.0.0 protocol implementation (creation, termination, checksum, expiration, concatenation, creation-with-upload, creation-defer-length)
• Pluggable storage backends via SPI (UploadStore interface)
• CDI lifecycle events for upload created, chunk received, upload completed, upload terminated, and concatenation completed
• Optional SSE (Server-Sent Events) for real-time upload progress
• Optional authentication filter
• Checksum validation (SHA-1, MD5, SHA-256)
• Automatic expiration of incomplete uploads

Getting Started

Installation

Add the extension to your Quarkus application:

Gradle

implementation("org.sitenetsoft:quarkus-tus:1.0.0-SNAPSHOT")

Maven

<dependency>
    <groupId>org.sitenetsoft</groupId>
    <artifactId>quarkus-tus</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Minimal Configuration

The extension works out of the box with sensible defaults. Add to application.properties to customize:

# Max upload size (default: 100 GB)
quarkus.tus.max-size=1073741824

# Upload storage directory (default: ${java.io.tmpdir}/quarkus-tus-uploads)
quarkus.tus.store.local.upload-dir=/var/uploads

# Expiration for incomplete uploads in hours (default: 24)
quarkus.tus.expiration-hours=48

TUS Endpoints

The extension registers the following endpoints at the configured path (default /tus):

Method	Path	Description
OPTIONS	/tus	TUS capability discovery (protocol version, extensions, max size, checksum algorithms)
POST	/tus	Create a new upload (supports creation-with-upload and concatenation)
HEAD	/tus/{id}	Query upload status (offset, length, expiration)
PATCH	/tus/{id}	Upload a chunk of data (resumable)
DELETE	/tus/{id}	Terminate and delete an upload

Quick Example: Observing Upload Events

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import org.sitenetsoft.quarkus.tus.runtime.event.*;

@ApplicationScoped
public class UploadEventHandler {

    void onCreated(@Observes TusUploadCreatedEvent event) {
        Log.infof("Upload started: %s (%d bytes)", event.uploadId(), event.totalSize());
    }

    void onCompleted(@Observes TusUploadCompletedEvent event) {
        Log.infof("Upload finished: %s", event.uploadId());
        // Process the completed file...
    }
}

Building from Source

Requires Java 25 and Gradle 9.3.1 (wrapper included).

# Build all modules
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build

# Run @QuarkusTest integration tests only
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew :integration-tests:test

# Run @QuarkusIntegrationTest tests against the packaged JAR
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew :integration-tests:integrationTest

Documentation

Read the full documentation for detailed guides on:

• Configuration Reference
• CDI Lifecycle Events
• Custom Storage Backends
• SSE Upload Progress
• Authentication
• Testing

Compatibility

Extension Version	Quarkus Version	Java Version
1.0.0-SNAPSHOT	3.31.4	25

License

This project is licensed under the Apache License 2.0.