MoonTusCore

MoonTusCore is an original MoonBit implementation of the decision layer for tus 1.0. It validates HTTP-shaped values and turns them into bounded, atomic upload-state transitions without owning sockets, a web framework, authentication, or a persistence technology.

Version 0.1 implements Core, Creation and Creation-Defer-Length. It includes a compare-and-swap storage contract, an in-memory reference store, deterministic scenario reports, executable conformance vectors, a Native CLI, and a library example.

For the current patch’s verification, see 2026-10-01 verification.

Why a protocol core?

Resumable upload bugs usually live between the HTTP adapter and storage: duplicate headers get collapsed, stale offsets overwrite bytes, deferred lengths become inconsistent, or a rejected request mutates state. MoonTusCore makes those decisions explicit and testable. Framework adapters translate a request into TusRequest; storage adapters commit only a validated AppendPlan.

Features

• Strict Tus-Resumable 1.0.0 negotiation and duplicate-preserving headers.
• Core X-HTTP-Method-Override interpretation before request routing.
• OPTIONS, collection POST, resource HEAD, and offset-checked PATCH.
• Known and deferred upload lengths with overflow-safe integer parsing.
• Strict RFC 4648 decoding for ordered, duplicate-free Upload-Metadata.
• Checked outbound Upload-Metadata serialization for adapters that construct headers from application values; it re-encodes bytes and enforces wire limits.
• HEAD reporting of offset, length/deferred state, and creation metadata.
• Configurable upload, patch, header, path, and metadata resource budgets.
• Revision plus offset compare-and-swap semantics; rejection never mutates.
• Structured stable error codes and protocol decision traces.
• Text/JSON scenario reports and ten built-in conformance vectors.
• No runtime dependencies in the published library.

Install

Install the current release:

moon add JSJ222/tus-core@0.1.1

The source repository is public at https://github.com/JSJ222/MoonTusCore. The package page is https://mooncakes.io/docs/JSJ222/tus-core.

Quick start

let engine = @tus.TusEngine::new().unwrap()
let create = @tus.request(
  "POST",
  "/files",
  headers=@tus.Headers::empty()
    .add("Tus-Resumable", "1.0.0")
    .add("Upload-Length", "5"),
)
let created = engine.handle(create)
let location = created.headers.first("location").unwrap()
let patch = @tus.request(
  "PATCH",
  location,
  headers=@tus.Headers::empty()
    .add("Tus-Resumable", "1.0.0")
    .add("Upload-Offset", "0")
    .add("Content-Type", "application/offset+octet-stream")
    .add("Content-Length", "5"),
  body=b"hello",
)
let uploaded = engine.handle(patch)
assert_eq!(uploaded.status, 204)

The in-memory TusEngine is a runnable reference. A persistent adapter uses plan_creation, plan_append, validate_record, and AppendPlan to preserve the same validation-before-mutation and compare-and-swap rules.

When constructing an outgoing metadata header, use serialize_upload_metadata_checked(entries, limits) and handle its error instead of using the unbounded convenience serializer.

Run

moon check --target all --deny-warn --warn-list=-implicit_impl_as_method-test_unqualified_package
moon test --target all --deny-warn --warn-list=-implicit_impl_as_method-test_unqualified_package
moon build --target all --deny-warn --warn-list=-implicit_impl_as_method-test_unqualified_package
moon run cmd/moontus --target native -- demo success
moon run cmd/moontus --target native -- demo deferred --json
moon run examples/library-demo --target native

The conflict and limits demos intentionally include a rejected request but exit successfully after showing that the stored bytes remain correct.

Response model

TusResponse contains the recommended HTTP status, ordered response headers, an optional stable TusError, and decision traces naming the protocol section. Adapters remain responsible for writing HTTP responses and enforcing authentication or application policy before calling the core.

Supported scope

Capability	v0.1
tus Core 1.0	Yes
Creation	Yes
Creation-Defer-Length	Yes
In-memory reference storage	Yes
Persistent storage contract	Documented planners/CAS seam
Creation-With-Upload	No
Checksum, Expiration, Termination	No
Concatenation	No
HTTP server/client	No

Unsupported extensions are excluded deliberately rather than silently approximated. See protocol scope.

Architecture and safety

• Architecture
• Persistent adapter guide
• Protocol scope
• Security and resource limits
• Conformance strategy
• Release procedure
• Domain context

Project status

The v0.1.1 implementation is buildable and tested, and its GitHub repository and Mooncakes package are public. Gitlink mirroring was not part of this release.

License

Apache-2.0. Protocol attribution and dependency status are recorded in THIRD_PARTY_NOTICES.md.