Conformance¶

Failure handling decides whether a storage client works, so the mock server turns every failure mode into a fixture. This page maps every fixture to the invariant it pins and to the test that pins it. The design reasoning behind these guarantees lives in Design, the wire behavior they approximate in the protocol reference.

The mock and the one table¶

crates/mock-nexus is a std-only HTTP/1.1 server implementing exactly enough of the protocol to exercise the transport contract: GET/HEAD/PUT with Content-Length or chunked bodies, resumable GET through Range: bytes=N- (a 206 with Content-Range, a 416 on out-of-range starts), and Basic-auth gating. A scenario selects a failure mode. The scenario list has one home: the Scenario enum in crates/mock-nexus/src/scenario.rs, with each mode's exact behavior in its doc comment. The Rust suites, the mock binary (mock-nexus --print-scenarios) and any external harness all read that one list, so it never forks.

The mock also follows the protocol in its own answers: a status answer that can reach a HEAD (401, 403, 405, 503) carries the body's Content-Length but no body bytes (RFC 9110 §9.3.2), and a request head past the 64 KiB bound is answered with 400 instead of a silent hang-up.

Group repositories are a separate deployment kind, not a scenario: MockNexus::start_group builds one over two or more running members. The group forwards reads to the members in order and relays the first 2xx, so every scenario in the table above keeps applying behind a group. Writes are refused by the group itself with 405 and Allow: GET,HEAD, in the wire shape of the real Nexus group handler. The dispatch is faithful to the real GroupHandler.java (method switch at lines 103-112, the first-2xx member walk at 124-166). Group search is not modeled: the search API reads the metadata database rather than the group dispatch.

The matrix¶

Every scenario, the invariant it pins, and the tests that pin it. The client-facing contract page rendered from the same table: wire invariants. atomic is the control group: it is what the server does when nothing goes wrong, so most semantics tests run against it.

Client coverage¶

The scenario matrix above is the server contract. This one is the client contract: every wire invariant against the implementations that claim it.

via core means the binding calls the Nxr facade and carries no wire logic of its own. Its independent surface is checked by scripts/check-bridge-surface.sh, and the only additional behavior test is diff_reports_the_four_states. Every other row inherits the core suite. n/a means the surface does not exist in that client, not that it is untested.

The named pins behind the rows:

The suites¶

just test                                         # everything: units + conformance
cargo test -p nexus-raw-core --test conformance   # the facade against the mock
cargo test -p nexus-raw --test cli                # the binary against the mock

The core suite drives the facade directly and pins transfer semantics. The CLI suite runs the real nxr binary over HTTP against the same mock and pins the user-visible surface on top: exit codes (0/1/2/3), the hint: line on stderr, down refusing without an enumeration source, --plan writing nothing, NDJSON event shapes, doctor verdicts. Every scenario in the table is driven by the CLI suite at least once, and the table's Pinned by column names the test for every fixture.

The rest of each suite pins semantics that do not belong to one scenario: misuse refusals (an empty scan, a name outside it, a missing enumeration source), replay purity, marker and part hygiene on the local disk, and the golden --json shapes. The full inventory lives where it stays true: crates/nexus-raw-core/tests/conformance.rs and crates/nexus-raw/tests/cli.rs. Names there are written to be read next to their assertions, not out of context.

The second client¶

clients/python is the proof that the protocol stands on its own: a reference client on the Python standard library alone (http.client, hashlib, nothing to install), implementing get, put, head, sha, ls and the channel verbs from the protocol text. Its conformance suite drives the mock-nexus binary over real HTTP, one process per test on a free port, the same matrix the Rust suites drive through the facade:

cargo build -q -p mock-nexus
python3 -m unittest discover clients/python

Because the binary has no in-process handle, the suite reads the store through plain retry-free requests and reads the request log from the client itself, which records every attempt as a (method, path) pair: the marker-ordering assertion is the same, one layer closer. The retry policy is the Rust transport's, shrunk to one file: 4 attempts, 0.5s x 2^n backoff with jitter, a 429's Retry-After honored in place of the backoff, 401/403 failing fast, the per-operation socket timeout as the stall watchdog. Scenarios outside the client's surface are skip-listed in the suite with the reason (doc-drift is a library-only knob, no-service and readonly guard surfaces the client does not have).

The drift rule lives in test_unit_every_scenario_is_classified: the suite fetches the scenario list live from mock-nexus --print-scenarios and requires every listed scenario to have a test method named after it or a row in the skip table, in both directions. A scenario added to crates/mock-nexus/src/scenario.rs fails the Python suite until it is classified, so a second implementation cannot fall behind the table. That is what makes the list the conformance contract rather than a convention: a third client can lift the same mechanism, point it at the same --print-scenarios, and inherit the same stand.

The composition¶

The core suite pins transfer semantics through the facade, the CLI suite pins the user-visible surface through the real binary, the mock carries its own suite pinning the behavior table itself (every scenario plus the group forwarding), and the golden fixtures pin the --json contract byte-exact. The rule that keeps this honest: a scenario added for any client lands in the same PR as the test that needs it, in crates/mock-nexus/src/scenario.rs, so the list never forks.

Driving the mock by hand¶

just mock atomic --port 8080
cargo run -p mock-nexus -- slow --chunk-delay-ms 2000 --port 8080
cargo run -p mock-nexus -- auth-401 --auth ci:secret --port 8080
cargo run -p mock-nexus -- rate-limit --rate-429s 3 --retry-after-secs 5 --port 8080

It prints its address and serves until killed: point any client at it, including ones this project does not know about. To trace a failure from the symptom a consumer sees, start with when it breaks. The error taxonomy is in errors and exit codes.