3fac029a71
Each *-conformance/README.md now has a line that begins **Provenance.**: the generator that writes the corpus and its input, and for an input not generated here its source and licence. OER/2's corpus is settled and left as it is. byte-exact-conformance and quantum-ops-conformance get a README. wai-rs/tests/vectors/README.md gives a row per vector directory. Where the staged-delivery, staged-measurement and telemetry READMEs called their content "synthetic", that sentence is now their provenance line. Two vectors are recorded as not generated, from the provenance audit: int_video's video_real (a pan over a third-party picture) and neural-conformance's photo (a third-party picture, with a decoder trained on unrecorded images). Their lines say so and that they are to be replaced; the photo bullet no longer names the picture's source product. tests/corpus_provenance.rs requires the line in every corpus and a row for every vector directory; CI runs it with the carriage tests. CONTRIBUTING states the rule: corpus content is generated here, or recorded with a licence that permits redistribution, and a word like "synthetic" is not a provenance line. Co-Authored-By: Claude Opus 5.5 <[email protected]>
49 lines
2.9 KiB
Markdown
49 lines
2.9 KiB
Markdown
# 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.
|