HTTP contract

This is the public interface. Changes to anything marked stable require a new catalog major version and a changelog entry; the old behaviour keeps working.

1. URL scheme (stable)

https://loremfile.dev/{format}/{name}

• format: ^[a-z0-9]+$, one of the formats in 05-fixture-catalog.md (e.g. pdf, mp4, bin, edge, hls).
• name: ^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+)+$ — lowercase kebab-case descriptor followed by one or more extensions. Examples: a4-3pages.pdf, 3-text-files.tar.gz, people-1000.parquet.
• HLS is the one nested case and has its own grammar: hls/{variant}/(index|master)\.m3u8 and hls/{variant}/seg-[0-9]{3}\.ts where variant matches the descriptor grammar (720p-10s, multi-bitrate). The catalog validator applies this exception; filename in Content-Disposition and ext in the manifest are derived from the last path segment.
• No uppercase, no spaces, no underscores, no query parameters needed. Query strings are ignored by the origin and excluded from the edge cache key, so ?v=1 is harmless (ADR-013).
• Names stay put. A fixture is not renamed, and is removed only for a legal takedown (13-legal-and-policy.md §7); the manifest then keeps a tombstone.

Descriptor grammar

Descriptors are ordered tokens separated by -:

[variant]-[dimension|duration|count|size]-[qualifiers]

2. Methods (stable)

3. Status codes (stable)

4. Response headers

4.1 On every fixture (stable)

4.2 Additionally on active-content fixtures (.html, .htm, .xhtml, .svg, .xml) (stable)

The sandbox CSP is deliberately not applied to PDFs or media: browsers' built-in PDF viewers have failed to render PDFs served with a restrictive CSP (Chromium issue 40328564, Mozilla bug 1582115), so PDFs carry no CSP at all.

4.3 On site pages (extensionless paths) (may evolve)

Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none', X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, X-Content-Type-Options: nosniff, Permissions-Policy: camera=(), microphone=(), geolocation=(), Link: </llms.txt>; rel="describedby", </.well-known/api-catalog>; rel="api-catalog" (04 §11; also on /.well-known/api-catalog itself, whose HEAD must carry it — RFC 9727 §2).

Additionally on /legal/imprint and /legal/privacy, and on their trailing-slash forms: X-Robots-Tag: noindex, nofollow, nosnippet (header rule legal_pages_noindex, 08 §5.3), and the same directive as <meta name="robots"> in the HTML (ADR-016 amendment, ADR-028). No other site page carries an X-Robots-Tag.

5. CORS (stable)

Bucket CORS policy (S3 syntax). It is applied once by the owner with an admin token (08 §2 step 7 and §7) because bucket configuration needs the R2 admin permission that neither CI token has; infra audit verifies the live behaviour:

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["Content-Length", "Content-Range", "Content-Type", "Content-Disposition", "ETag", "Accept-Ranges", "Last-Modified"],
    "MaxAgeSeconds": 86400
  }
]

Consequences: fetch() from any origin works; <video>, <audio>, <img crossorigin> work; Range requests from browsers work (the Range request header is covered by AllowedHeaders: *); sites using Cross-Origin-Embedder-Policy: require-corp can embed fixtures because of Cross-Origin-Resource-Policy: cross-origin.

6. Caching semantics

• Fixtures are immutable: clients and intermediaries may cache for a year. Bust nothing; the URL is the version.
• Site and discovery files: 5-minute TTL. Deploys purge them explicitly.
• Query strings: the cache rule excludes the query string from the cache key (08 §5.4), so ?v=1 and ?v=2 share one cache entry and cost no extra R2 read. Query strings do not change behaviour.
• Origin header: Cloudflare's default cache key also includes the request's Origin header, so a fixture fetched from three different web origins occupies three cache entries and costs three R2 reads on first use. This is normal CORS behaviour and is accounted for in the cost model (19 §2).
• Vary: not used.
• Compression: fixtures are served byte-exact (no-transform). Site HTML/CSS/JS may be gzip/brotli-encoded by the edge; their Content-Length may then differ from the stored size.

7. Immutability policy (stable)

1. A fixture path, once published to R2, is not rewritten or reused. The rule is about fixtures and nothing else: probe --down deletes everything under _probe/, upload --site overwrites the site keys on every deploy, and _locktest/probe exists precisely to be written once and then refused. None of those is a fixture, none is covered by this promise, and the bucket lock rules draw the same line at the storage layer — every format prefix is locked, _probe/ and the site keys are not. Entry into manifest.json on main is not the boundary either — the promise ADR-005 makes is to embedded URLs and to hashed fixtures in other people's tests, and both require the bytes to have been served. An entry that never reached the bucket has no consumer and breaks no promise, so it may be removed outright rather than tombstoned; a tombstone means "was published, now removed" and would be a lie on the format page. This is not a relaxation: R2 bucket locks already implement exactly this boundary at the storage layer (ADR-023), and the wording above claimed something stricter than the system has ever enforced. Amended in M3.6, when five entries described bytes that had never been published and could not be regenerated.
2. Its bytes, sha256, bytes, mime are frozen from publication onward. CI enforces the manifest half (lock check); R2 bucket locks enforce the storage half.
3. To fix a defective fixture, add a new fixture (e.g. a4-3pages-v2.pdf), set supersededBy on the old entry, mark it deprecated: true, keep serving it.
4. Only a legal takedown may remove an object; the manifest entry then becomes {"status": "removed", "reason": "…", "removed_at": …} and the site marks it.
5. The manifest.json document itself, sha256sums.txt, the site and index.json files are mutable.

8. Client guidance (published on the site)

• Verify downloads with sha256sum -c sha256sums.txt --ignore-missing, or shasum -a 256 -c sha256sums.txt --ignore-missing on macOS, which ships no sha256sum.
• Prefer HEAD for size checks (Content-Length equals manifest.bytes).
• Do not rely on ETag equalling MD5.
• Query strings are ignored; they neither bust the cache nor change the response.
• Rate limit: keep below 30 requests/second per IP; CI jobs that need more should download once and cache locally.
• Bandwidth is free for us; still, please do not use fixtures as a general-purpose CDN speed test in a loop.

9. Examples

# 10 MiB + 1 byte, to test a "10 MiB max" upload limit
curl -fsSLO https://loremfile.dev/bin/10mib-plus-1.bin

# HEAD for size
curl -sI https://loremfile.dev/pdf/a4-3pages.pdf | grep -i content-length

# Range
curl -s -r 0-99 -o part.bin -D - https://loremfile.dev/mp4/720p-5s.mp4 | grep -i content-range

# Verify
curl -fsSL https://loremfile.dev/sha256sums.txt | grep 'pdf/a4-3pages.pdf' | sha256sum -c