ADR 0006: A proxy is a byte pass-through

• Status: accepted
• Date: 2026-09-23

Context

Cloning an upstream API with a generator tempts you to re-model the upstream: parse its types, re-emit its routes as first-class endpoints. That is a second system of record for someone else's API, and it breaks silently every time the upstream changes.

Decision

kind: proxy tesserae declare upstream endpoints and forward them byte-for-byte: method, path, query, headers, and body go through unchanged (hop-by-hop headers stripped), status and body come back unchanged, plus two response headers (x-proxied-by, x-cache). Middleware is a closed vocabulary (v0: cache — in-memory, TTL, GET-only by default, keyed by method+path+query). mosaic import openapi turns an existing OpenAPI 3 document into a proxy tessera so cloning an API is a command, not a project.

Consequences

• The proxy can never misrepresent the upstream's semantics in v0.
• Enrichment and transformation are out of scope by design; they are a later ADR with its own vocabulary.
• The cache is visible (x-cache: HIT|MISS) and bounded by TTL.

Proof

cargo test -p mosaic-conformance → examples_match_goldens, which pins the full rendering of examples/proxy (proxy tessera with cache middleware) under examples/proxy/golden/.