82 lines
5.5 KiB
Markdown
82 lines
5.5 KiB
Markdown
# live-conformance/steering — energy-aware content steering
|
|
|
|
The corpus of [`extensions/energy-steering.md`](../../extensions/energy-steering.md) §11: a
|
|
room and its key log, steering policies (`WSP1`), the per-hop session records (`WMH1`,
|
|
[live-metering](../../extensions/live-metering.md) §3) of the pathways' hops, steering
|
|
requests with the report each gives, and vectors, each a steering decision (`WSD1`) with the
|
|
records and the manifest given with it, and the outcome a verifier gives it.
|
|
|
|
It sits beside [`metering/`](../metering/) because its evidence is live-metering's per-hop
|
|
records, read by that corpus's second implementation, `live_metering_verify.py`.
|
|
|
|
**Steering equivalence.** For each request, a conforming reader given the policy, the
|
|
protocol, the `target` and the `cmcd_header` reaches the `report` it states (§4). For each
|
|
vector, a conforming verifier given the room (`descriptor` and `key_log_head`), the vector's
|
|
`policy` (by name), its `decision`, the records it lists (by digest, from `records`) and its
|
|
`manifest` (or none, when `null`) reaches the outcome the vector states (§9.3):
|
|
|
|
- `refuse`: the `reason` and where, `at`: `["room"]`, `["policy"]`, `["decision"]`,
|
|
`["evidence", p, k]` for the record `k` named under pathway `p`, `["pathway", p]`,
|
|
`["output"]` or `["manifest"]`;
|
|
- `accept`: the decision's `digest`; the `priority` by pathway ID; the `ttl`; `why` the first
|
|
pathway is first; each pathway's `status`, `class`, `joules` and `delivery` (decimal
|
|
strings) and `limits` (the bits of §7.1); the `steering_manifest`; and the record's `uri`.
|
|
|
|
Every vector also states the decision's `inputs` as it reads (its instant, session, protocol,
|
|
report and loads), and a vector whose report came from a request states the `request`, which
|
|
gives that report. Each policy that reads states its `hls_tag` and `dash_element` (§8.2,
|
|
§8.3). A verifier that reaches another outcome, reason, place, fact or byte does not
|
|
conform.
|
|
|
|
**Provenance.** Generated here: `wai_energy_steering_vectors gen` writes `vectors.json` from
|
|
figures written in code, from fixed seeds: each key is SHA-256 of the corpus's fixed label and
|
|
the principal's index, each session SHA-256 of another fixed label and an index, every time is
|
|
a constant (the room's `t0` is 2026-10-16T00:00:00Z; the hops cut their records on a 10 s
|
|
period, and the decisions fall at 62 s and 72 s of room clock), and Ed25519 signing is
|
|
deterministic (RFC 8032), so the file is the same bytes on every machine. The per-hop records'
|
|
joule figures, bytes and subscriber time are synthetic constants, chosen to exercise the rule,
|
|
and were measured by nothing: the corpus computes which pathway the rule places first and
|
|
claims nothing about the energy any deployment spends or saves. The key-log head is sealed by
|
|
the reference's key log under a fixed root; the origin and the URIs are `.example` names (RFC
|
|
2606). The generator asserts that each vector reaches the outcome it was written to have
|
|
before it writes it.
|
|
|
|
## Layout
|
|
|
|
One file, `vectors.json`:
|
|
|
|
- `principals`: the keys, by name (informative).
|
|
- `room`: its `id`, `descriptor` (`WRD1`, hexadecimal) and `key_log_head` (a key-log revision,
|
|
JSON text), which lists the room authority, the steering key `live/steer` with every energy
|
|
authority, a revoked steering key, and each hop with `live/relay` and every energy
|
|
authority, one of them revoked. One hop key, `unlisted_edge`, is in no entry.
|
|
- `policies`: by name, each `policy` (hexadecimal) with its `hls_tag` and `dash_element`, or
|
|
`null` for a policy the rules refuse. `three` has three pathways (`edge-a`, `edge-b` and the
|
|
relay tree `tree`, each an edge hop and an interior hop); `explore` adds the unmetered
|
|
`origin` path with a 10% minimum share; `cloned` adds `edge-a2`, a clone of `edge-a`
|
|
through another host with its own edge hop; `latency` puts the tree past the latency
|
|
ceiling, `seconds` uses the per-second basis, `strict` has a ceiling no pathway meets;
|
|
`unlisted` and `revoked` give the tree an edge hop the key log does not list or has revoked;
|
|
`shares_over`, `clone_later` and `stranger_signed` are refused.
|
|
- `records`: every per-hop record a vector lists, by its digest. The hops sign them in four
|
|
worlds: every hop counter-metered; one class per pathway (calibrated, counter, estimate);
|
|
`edge-b`'s interior hop unmetered; `edge-a`'s hops of two classes.
|
|
- `requests`: steering requests over HLS and DASH, with CMCD in the query and in the
|
|
`CMCD-Request` header, and malformed values the reader leaves absent.
|
|
- `vectors`: accepted, three pathways with figures of one class, mixed classes, an unmetered
|
|
hop, hops of two classes, stale evidence, a client at its floor, a short buffer, hysteresis
|
|
holding and a period later moving a client, clones, a session placed by its band and one
|
|
outside it, capacity, latency, the per-second basis, DASH, and no pathway within the limits;
|
|
refused, each reason of §10 and the codes it reuses (`classes_summed`, `hop_not_authorised`,
|
|
`hop_revoked`, `record_missing`, `signer_not_authorised`, `signer_revoked`,
|
|
`bad_signature`), each a control of one defect.
|
|
|
|
## Regenerate and verify
|
|
|
|
```
|
|
cd wai/wai-rs
|
|
cargo run --no-default-features --features energy_steering --bin wai_energy_steering_vectors -- gen ../live-conformance/steering
|
|
cargo run --no-default-features --features energy_steering --bin wai_energy_steering_vectors -- verify ../live-conformance/steering
|
|
cargo test --no-default-features --features energy_steering --test energy_steering
|
|
python3 -I ../live-conformance/energy_steering_verify.py ../live-conformance/steering
|
|
```
|