Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 17 Packages Wiki Activity Actions 213
open-standards/wai/cache-conformance
History
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Transaction Science 39d9894e73 wai: cache conformance (public part), the wai-http workflow, and the CI wiring 
W3-7, public part. cache-conformance/: tests.json (C1–C13, R1–R5 as MUST
tests of §9 and the sidecar rules, S1–S2 informative), driver.py (stages the
corpus behind an origin and runs the tests against a cache; standard library
and _blake3.py only), mutators.py (flip, gzip, truncate, vary: one §9 defect
each), run.sh (the reference origin must pass every MUST test; each control
must be caught by the tests named for it; labelled caches run where an
environment provides /opt/wai-cache, and the summary says when none did) and
a README. Reports name a cache by label, package version and configuration
digest only. The private harness image is not in this repository.

The reference origin gains what the tests need of it: If-Range by strong
comparison, a live-edge prefix served with a shorter max-age, §8.4's
Cache-Control for the key log and grants, and a request counter
(--count-hits) for the informative tests.

.github/workflows/wai-http.yml: the falsify job (every patch caught, every
Python mutation caught, the differential) and the cache-conformance job
(reports uploaded as an artifact). wai-conformance.yml: `http` joins the
build, the library tests, the corpus loop (wai_http_vectors), the
feature-alone and wasm32 checks; http_verify.py joins the independent
verifiers. wai_http_vectors verify now names a case whose evaluation panics.

http-delivery.md writes byte spans in words where a half-open interval read
as link text to the section-reference check.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-05 08:02:11 -04:00
..
driver.py wai: cache conformance (public part), the wai-http workflow, and the CI wiring 2026-10-05 08:02:11 -04:00
mutators.py wai: cache conformance (public part), the wai-http workflow, and the CI wiring 2026-10-05 08:02:11 -04:00
README.md wai: cache conformance (public part), the wai-http workflow, and the CI wiring 2026-10-05 08:02:11 -04:00
run.sh wai: cache conformance (public part), the wai-http workflow, and the CI wiring 2026-10-05 08:02:11 -04:00
tests.json wai: cache conformance (public part), the wai-http workflow, and the CI wiring 2026-10-05 08:02:11 -04:00

README.md

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

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

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.