# cache-conformance — HTTP caches under http-delivery §9

Checks the cache rules of [http-delivery](../extensions/http-delivery.md) §9 against
an HTTP cache that fronts an origin serving the objects of
[`http-conformance/`](../http-conformance/), and reports, per cache label and version,
whether the configuration meets each rule.

**Provenance.** Written here: the tests, the driver and the controls are the code in this directory, and the objects a run fetches are `http-conformance`'s (see its provenance). No media of its own.

| file | what |
|---|---|
| `tests.json` | the tests: id, rule, level (MUST or informative) and what each checks |
| `driver.py` | stages the origin's files and runs the tests against a cache; standard library only, with `../claim-conformance/_blake3.py` to check each object against its content hash |
| `mutators.py` | four proxies that each break §9 in one way: the negative controls |
| `run.sh` | stages, starts `wai http origin`, and runs the driver against the origin, each control and each labelled cache |

## What runs

1. **The origin, directly** (`origin-direct`): the reference origin
   (`wai http origin`) must pass every MUST test. It answers byte ranges and `If-Range`,
   serves a live-edge alias with a shorter `max-age`, sends §8.4's `Cache-Control` for
   the key log, and counts the requests it receives (`--count-hits`) so the informative
   tests can tell whether a cache answered from its store.
2. **The negative controls** (`control-flip`, `control-gzip`, `control-truncate`,
   `control-vary`): the driver must fail, and must name the tests each defect reaches —
   `flip` C1, C3 and C11; `gzip` C7; `truncate` C1 and C2; `vary` C13. A control the
   driver passes is a defect in the driver.
3. **Labelled caches.** An environment that provides them lists their labels in
   `/opt/wai-cache/labels`; each `/opt/wai-cache/<label>/` holds `start.sh <port>
   <origin URL>`, which starts the cache in front of the origin, a `version` file and the
   `config` it runs with. This repository holds no cache configuration: the labels are
   opaque, and a report names a cache only by its label, its package version and the
   SHA-256 of its configuration. Where the directory is absent, only 1 and 2 run, and the
   summary says so.

## Reports

`run.sh <out-dir>` writes, under `<out-dir>/reports/`, `report-<label>.json`
(`{cache_label, package_version, config_sha256, results}`), `requirements-<label>.md`
(the same as a table, with whether the configuration meets §9), the driver's log per run,
and `summary.md`, which CI also writes to the job summary. The CI job uploads the
reports as an artifact.

## Running it

    cd wai/wai-rs && cargo build --release --no-default-features --features http --bin wai
    cd ../.. && WAI=wai/wai-rs/target/release/wai bash wai/cache-conformance/run.sh /tmp/cache-run

Python 3 with the standard library is all the driver and the controls need.