diff --git a/.cargo/mutants.toml b/.cargo/mutants.toml index 8d3805a6a43..e7383025a3b 100644 --- a/.cargo/mutants.toml +++ b/.cargo/mutants.toml @@ -13,7 +13,7 @@ additional_cargo_test_args = ["--lib", "--test", "integration"] # only where the same function has another such mutant that tests do catch. exclude_re = [ # Debug output only feeds logs. - '::fmt', + '::fmt', # The rotation's xorshift step only picks which fresh identity comes next, # and the guard after it enforces freshness and range. 'replace (\^= with \|=|<< with >>|>> with <<) in Router::rotate', diff --git a/.claude/skills/verify-failover/SKILL.md b/.claude/skills/verify-failover/SKILL.md index fa0baf0e6c5..46a3f9b1ac1 100644 --- a/.claude/skills/verify-failover/SKILL.md +++ b/.claude/skills/verify-failover/SKILL.md @@ -5,7 +5,7 @@ description: Model-check failover along a chain of relays (`rs/moq-net/verify/fa # Verify failover along a relay chain -`rs/moq-net/verify/failover/FailoverChain.tla` models one track served to a client `C` through relay `E`, which starts on relay `A` and may fail over to relay `B`; both pull from the origin `O`, and with `Mesh` `B` may also route through `A`. Each layer is abstracted to the steps its own model checked, so the state stays small: a route change is one `Switch` (`verify-route`), a switch asks the new copy from where the readers got to and each reader hands a group out once and ends once nothing it replaced may still deliver (`verify-resume`), and a group handed out crosses a hop unless its session dies (`verify-subscribe`, with an hour's budget). What the chain adds is frames: a group whose copy fails or stalls mid-read continues on another copy at the same frame (`Recover`), from a copy its relay holds, from the serving copy, or by fetching the rest from the serving route, which asks its own upstream in turn. +`rs/moq-net/verify/failover/FailoverChain.tla` models one track served to a client `C` through relay `E`, which starts on relay `A` and may fail over to relay `B`; both pull from the origin `O`, and with `Mesh` `B` may also route through `A`. Each layer is abstracted to the steps its own model checked, so the state stays small: a route change is one `Switch`, a switch asks the new copy from where the readers got to and each reader hands a group out once and ends once nothing it replaced may still deliver (`verify-resume`), and a group handed out crosses a hop unless its session dies (`verify-subscribe`, with an hour's budget). What the chain adds is frames: a group whose copy fails or stalls mid-read continues on another copy at the same frame (`Recover`), from a copy its relay holds, from the serving copy, or by fetching the rest from the serving route, which asks its own upstream in turn. ## Rules @@ -49,4 +49,4 @@ Sync commit: `88572c583e2f64c7f5fc9bfa59df90706308497e`. Run `git log 88572c583e ## Not covered -Routing is abstracted to any live upstream winning, so feasibility, ROUTE_END, and announce order are `verify-route`'s; how a reader picks among its copies, bounds replaced copies, and orders groups is `verify-resume`'s; drops, skips, and re-offers on a hop are `verify-subscribe`'s. The client's track fails only through `FrontFail`, so whether one dead relay can end playback is that step's guard, not a rule. Every hop has an hour's budget, so nothing goes stale or expires. No source refuses the track, so a finished track's reroute never concludes (`Action::Conclude`). The origin writes each group whole and never fails, `E` never dies, a dead relay never returns, and a relay's cache is dropped when it parks. A fetched group holds its head from frame 0 (`lend_head`), and compressed groups are left out. A pass covers two groups of two frames, one death, one switch per relay, and one client. +Routing is abstracted to any live upstream winning, so which route wins and announce order are the router's own tests' (`rs/moq-net/src/route/tests`); how a reader picks among its copies, bounds replaced copies, and orders groups is `verify-resume`'s; drops, skips, and re-offers on a hop are `verify-subscribe`'s. The client's track fails only through `FrontFail`, so whether one dead relay can end playback is that step's guard, not a rule. Every hop has an hour's budget, so nothing goes stale or expires. No source refuses the track, so a finished track's reroute never concludes (`Action::Conclude`). The origin writes each group whole and never fails, `E` never dies, a dead relay never returns, and a relay's cache is dropped when it parks. A fetched group holds its head from frame 0 (`lend_head`), and compressed groups are left out. A pass covers two groups of two frames, one death, one switch per relay, and one client. diff --git a/.claude/skills/verify-route-key/SKILL.md b/.claude/skills/verify-route-key/SKILL.md deleted file mode 100644 index 714fc7dfe5c..00000000000 --- a/.claude/skills/verify-route-key/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: verify-route-key -description: Prove lite-07's Route Key Parameter (`rs/moq-net/src/route/proof.rs`, `js/net/src/lite/route_key.ts`) binds a key to its session and side with Tamarin. Use when a change touches what a route key proof signs or how it is checked, a transport binding's `export_keying_material`, TLS early data or resumption, or the draft's Route Key Parameter, or when a replay, reflection, or relaying attack on the proof needs every attacker strategy checked rather than a unit test. ---- - -# Verify the route key proof - -`rs/moq-net/verify/route-key/RouteKey.spthy` models the Route Key Parameter in Tamarin: each endpoint signs the domain, its side, and the session's exported secret, and its peer checks that signature against its own export. The attacker owns the network, makes keys of its own, and runs sessions with every endpoint, including as an intermediary that terminates TLS. Connections are TLS 1.3 full handshakes or resumptions, carrying one raw QUIC session (binding 1) or WebTransport sessions under attacker-chosen IDs (binding 2). Every run records which endpoint is really at its other end, so the lemmas judge a proof against the truth rather than an endpoint's belief. - -## Lemmas - -Every lemma must verify; the harm says why it matters. - -| Lemma | Holds when | Harm if broken | -| --- | --- | --- | -| `executable`, `executable_resumed_webtransport` | Two endpoints can accept each other's keys over raw QUIC, and over WebTransport after resumption. | The other lemmas hold vacuously. | -| `no_relay` | An honest key is never accepted on a session the attacker terminates. | An attacker, or a TLS-terminating intermediary, is filed under an honest relay's key and takes over its routes. | -| `no_reflection` | An endpoint accepts its own key only from itself, as the other side. | The attacker hands a relay its own proof and is filed as that relay. | -| `no_replay` | One signature is accepted on one session only. | A recorded proof claims a key on another connection. | -| `injective_agreement` | An accepted honest key was signed by the session's other end, for that side of that session, and no other session accepts it. | Any of the above. | - -## Variants - -Each variant drops one assumption the draft states and must break exactly the lemmas its `Breaks:` line names, which keeps the model from passing vacuously. - -| Variant | Drops | Breaks | -| --- | --- | --- | -| `NO_SIDE` | The side byte in the signed message. | `no_relay`, `no_reflection`, `injective_agreement` | -| `EARLY` | The main exporter: a resumed client signs over its 0-RTT secret, which a replayed ClientHello reproduces. | `no_replay`, `injective_agreement` | -| `NO_EMS` | A per-session secret: a man in the middle gives its two sessions one, as TLS 1.2 without RFC 7627 allows. | `no_relay`, `no_reflection`, `injective_agreement` | - -## Run - -```sh -quest gate just test route-key-model -quest gate just rs tamarin moq-net/verify/route-key/RouteKey.spthy -D=NO_SIDE -``` - -The first proves the model and checks every variant's `Breaks:` line, in seconds; Nightly runs it. The second proves one variant. To read a counterexample, run `nix shell --inputs-from . nixpkgs#tamarin-prover --command tamarin-prover interactive rs/moq-net/verify/route-key/` and open the falsified lemma. - -## Reading a failure - -A falsified lemma is an attack path, not yet a bug. Check that each rule it fires matches the code: the transport bindings below for the secret, `proof.rs` for the message. If the code cannot take a step, fix the model. If it can, the signed transcript is wrong: fix it in Rust, JS, and the draft together, and keep `a_proof_matches_the_js_transcript` (Rust) and `route_key.test.ts` (JS) agreeing. Do not add a restriction or drop an attacker rule until a lemma verifies. - -## Coverage - -Sync commit: `23898b48f46cb54da19007279504b2b6ecdf80cf`. Run `git log 23898b48f4.. -- rs/moq-net/src/route/proof.rs js/net/src/lite/route_key.ts` and the files below to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function, rerunning `just test route-key-model`. - -| Code | Model | -| --- | --- | -| `rs/moq-net/src/route/proof.rs` `Transcript::message`, `Transcript::prove`, `DOMAIN`, `EXPORTER_LABEL` (and `sign` in `js/net/src/lite/route_key.ts`) | `Prove` | -| `rs/moq-net/src/route/proof.rs` `Transcript::verify` `rs/moq-net/src/lite/setup.rs` `PeerSetupState::set` | `Accept_from_server`, `Accept_from_client` | -| `rs/moq-net/src/lite/session.rs` `start` (and `proveRouteKey` in `js/net/src/lite/route_key.ts`) | `Session_quic`, `Session_webtransport`, `Prove` | -| `rs/moq-tokio/src/quic/web/session.rs` `webtransport_exporter_context` `rs/moq-uring/src/quic/web.rs` `webtransport_exporter_context` | `Session_webtransport` | -| `rs/moq-quic/src/crypto/rustls.rs` `QuicClientConfig::new`, `QuicServerConfig::new` (TLS 1.3 only, early data off) | `Connect`, `Resume`, and the `EARLY` and `NO_EMS` variants | - -## Not covered - -Ed25519 is an ideal signature: a small-order public key that verifies anything is a key no honest endpoint holds, which the attacker could share between its own sessions anyway. TLS is reduced to its exporter: a connection's two ends share a fresh secret, resumption mixes the PSK with fresh randoms, and server authentication plays no part, since the proof must hold even when the client dials the attacker. Out of scope: a compromised route key, and relays sharing one key on purpose, which the draft allows. Bindings 3 to 5 (qmux) export nothing, so they never send or rely on a proof. The memory transport and Firefox's WebTransport exporter, which `route_key.ts` skips for deriving the session ID differently, are not modelled. diff --git a/.claude/skills/verify-route/SKILL.md b/.claude/skills/verify-route/SKILL.md deleted file mode 100644 index f1fa0bb834b..00000000000 --- a/.claude/skills/verify-route/SKILL.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: verify-route -description: Model-check the lite-07 route rule (`rs/moq-net/verify/route/RouteHandoff.tla`, the rule the routes epic's Plan item 27 picked, as `route::path::Router` in `rs/moq-net/src/route/path.rs` runs it) with TLA+. Use when a change touches route paths, the DEAD message for a closed session, holds, the doubt and its timer, forgetting dead hops, routes per prefix and scoped streams, the down-only flag on upstream links, the newest-floor views, what a reader is shown, or where a request goes, or when a routing bug needs every message ordering checked rather than a random sweep. ---- - -# Verify the route rule - -`rs/moq-net/verify/route/RouteHandoff.tla` models one publisher's routes across a mesh, under the rule the routes epic's Plan item 27 picked: a route names every relay it crossed with the session it learned it on, a closed session is named in one DEAD message per neighbour, a relay with no route holds until those that learned it from the relay answer, and only along the path it was built on, so holds never close a cycle, and a closed session casts doubt on its far end until a timer fires, keeping relays off routes through it but not off a route that begins at it, unless that route comes over a relay's own session to it opened since the doubt began. A relay ranks routes by drain, then the lowest link priority on the path, then cost; an offer carries its drain, so no relay ranks a path above what its neighbour did. A relay that hears GOAWAY sends a DRAIN naming the leaving node, the DEAD message's other entry, to each neighbour it sent a route through that node, and each relay doubts that node, so none takes a stale offer through it. A draining path ranks worst but stays usable. A route learned on a link its learner marks upstream, or from a down-only route, is down-only, and no relay sends one over a link it marks upstream (`Upstream`, the links whose higher-numbered end marks them), so no relay carries traffic between two upstreams. It follows `route::path::Router` in `rs/moq-net/src/route/path.rs` with one publisher and a route per prefix (`"root"`, and `"a"` inside it, which relays in `Scoped` start out watching alone), and keeps dead hops until their timer fires. A relay asks each neighbour for the set of prefixes it watches, none inside another; a relay in `Editors` may change that set up to `MaxEdits` times. Each change is an edit, sent as an ask on the FIFO and answered by a marker on the neighbour's FIFO, where both sides rekey the routes between them alike (`Rekey`): a key the new set covers stays, the route at a removed `"a"` moves to an added `"root"` without its floor, and the route at a removed `"root"` carries its floor, presented at `"a"`, to an added `"a"`. A heard route is believed for a prefix only while the relay asked for it at the last marker and in every edit still in flight. Every entry point is one atomic step ending in `Update`; messages share one FIFO per direction. The node timer is `Lift`; each dead hop also expires independently through `Expire`, so repeated failures of one node cannot retain all its old hops. Either may fire at any moment, or with `Patient` only once no message naming a closed session it covers is in flight: no DEAD, and no stale offer sent before the news. Every lite-07 session drives the path router through `route::node::Node` since [the switch](https://github.com/moq-dev/moq/pull/8731), and `route::tests::Sim` drives it under `Rule::PATH` (timer-only doubt). - -## Rules - -Each rule is an INVARIANT; the harm says why it matters. - -| Rule | Holds when | Harm if broken | -| --- | --- | --- | -| `Truthful` | Every view a relay keeps, and every floor it was offered, is the publisher's claims at that revision within its prefix. | A viewer sees a set of broadcasts the publisher never had. | -| `Mirrored` | With nothing in flight from one relay to another, what the first sent is what the second heard: the same routes, on the same paths, held exactly where the second holds them. | An edit rekeys the two sides differently, and they disagree about a route for good. | -| `Seen` | A relay shows a claim exactly while it holds a route covering it and the newest floor a believed covering route gave it has the claim, as that floor says. | A reader sees a claim no route vouches for, or an older one than it learned. | -| `NoRevival` | A reader never sees START for an item it saw END for, unless it forgot it since. | An ended broadcast comes back. | -| `NoFalseEnd` | A reader sees END only once the publisher withdrew that item. | A live broadcast is reported as ended rather than offline. | -| `NoRegression` | A reader never sees an UPDATE to an older item. | A stale announcement replaces a newer one. | -| `Stable` | A step that only changes a route's path, lifts a doubt, or applies an interest edit (its ask, or its marker for the claims both of the edit's sets cover) changes a shown claim only to a newer floor, or lets go of one it held unavailable. | A detour flaps claims, as a seqno advance did under the distance, or an edit that swaps prefixes ends or re-sends a claim both sets cover. | -| `SimplePaths` | Every route held or in flight names a loop-free path from the publisher to its sender. | A relay took back a route that crossed it. | -| `DownOnly` | A route is down-only exactly when its path came down a link its learner marks upstream, no path climbs a link its sender marks upstream after that, and nothing down-only is sent, in flight, or heard over such a link. | A relay carries CDN traffic between two upstreams, or a route loses its down-only flag one LAN hop on. | -| `LoopsAreStale` | A request that loops crosses a relay whose route names a closed session. | Routing loops with every relay up to date. | -| `StaleIsChased` | Every stale route a relay may use has the news that ends it on its way: queued toward the relay, or toward the neighbour it came from, and so on back. | A stale route, and any loop through it, lasts for good. | -| `NoStaleReturn` | No relay may use a route through a hop it once learned had died. | A dead path comes back after a relay forgot it. | -| `QuietIsSettled` | Once nothing is in flight and every timer fired: each relay shows exactly the claims a path of open sessions through relays watching them carries to it, never up a link its sender marks upstream after one its learner does, available, and a request for each reaches the publisher; no relay holds, keeps a stale route, or remembers a dead hop; and both ends of each session agree on what it asks for. | A hold never ends, a claim is shown that no path carries, a relay behind a scoped neighbour never reaches what a farther one offers, or an edit never takes effect. | -| `Budget` | From one quiet point to the next, the messages sent stay within 4 each way over each configured session per prefix and per claim, for each external change. | One change sets off announce spam, or routing never goes quiet. | -| `RequestsLoopFree` | A request never loops. | A request cycles through relays instead of reaching the publisher. | -| `LoopsLostThePublisher` | A request that loops goes round relays whose routes each begin on a closed session of the publisher. | A loop forms while the publisher is still reachable from the relays on it. | -| `Routed` | A relay that knows a route over open sessions, crossing no relay it doubts and not a link to the publisher that came back during its doubt, uses some route. | Doubt about the publisher alone darkens a relay with a way to it, as when one of a dual-homed publisher's links flaps. | - -Every config but `Homes.cfg` checks `RequestsLoopFree`; `Loop.cfg` pins the three-failure regression. `Homes.cfg` checks `LoopsLostThePublisher` instead: doubt spares a route that begins at the doubted node, so a publisher leaving three relays at once can send a request round them until the news arrives. `Flaky` names the links that open and close; `Flap.cfg`, `TwoHomes.cfg`, and `Homes.cfg` narrow it to the publisher's own (`OwnLinks`) or one of them (`FirstLink`). - -No config checks a liveness property: `Spec` has no fairness, so TLC does not show that a hold ends. That one does is an argument over what TLC does check. `Budget` bounds the messages a burst sends, each delivery takes one message off a queue, and a doubt starts only at a close or a delivery, so a burst is a finite number of steps. A delivery is enabled while a queue holds a message and a timer may fire once no news about its node is in flight, so a burst left alone reaches the state with nothing in flight and no doubt. `QuietIsSettled` says no relay holds there. - -What the timer costs, as the configs show it: fired late, it costs only the wait, and every rule holds (`RouteHandoff.cfg`). Fired early, a stale route can return, as with no doubt at all, and nothing else breaks (`Early.cfg`, which passes without `NoStaleReturn` and fails it within seconds with it). Patient means the timer outlasts every message sent before it fired, not only the DEAD: one that fires while an older offer through the closed session is still queued is early, and lets that offer return. Until `Patient` waited for those offers too, `HoldCycle.cfg` broke `NoStaleReturn` under random seeds, and `Twice.cfg` and `Loop.cfg` within seconds; all three check it now. A relay that has not yet heard the news may still use a stale route, and `StaleIsChased` is the bound. - -## Run - -```sh -quest gate just rs tla moq-net/verify/route/RouteHandoff.tla -quest gate just rs tla moq-net/verify/route/RouteHandoff.tla -config rs/moq-net/verify/route/Ring.cfg -``` - -Choose the config affected by the change; do not run the directory locally. -Nightly runs every config through `just test tla`, simulating each with a -`Simulate:` line. The recipe uses four workers. `Loop.cfg` checks the timer-only -doubt regression. When calling `just rs tla` -directly, pass the arguments from that line explicitly. For covering-source -selection, for example: - -```sh -quest gate just rs tla moq-net/verify/route/RouteHandoff.tla -config rs/moq-net/verify/route/Overlap.cfg -simulate num=1000 -depth 500 -``` - -The older exhaustive counts and times below predate independent hop expiry -(`Expire`); they are historical baselines, not validation of the current model. -The Loop row gives its current simulation parameters. Times used four workers. -`Patient` is TRUE unless the table says otherwise. - -`Loop.cfg` used to stop at the first early-collection counterexample. With -timer-only doubt, the attempted exhaustive check was stopped by the user after -76 minutes: 32.1M distinct states, 19.3M still queued at depth 14, and a growing -queue. It did not complete. Routine checks now use its bounded `Simulate:` line, -as they do for the other large configs. This samples the invariants; it is not -an exhaustive proof. Do not rerun the full route spec exhaustively for this -change; faster checkers are separate work. - -| Config | Mesh | Bounds | Previous distinct states | Previous run | -| --- | --- | --- | --- | --- | -| `RouteHandoff.cfg` | The publisher behind relay 1, in a triangle with relays 2 and 3. | 1 claim change, 1 session change | 434,956 | a minute or two | -| `Early.cfg` | The same, with a timer that fires at any moment. | 1 claim change, 1 session change | 14,220,217 | half an hour | -| `Twice.cfg` | The same, where two sessions close, as when relay 1 dies. Simulated: `num` counts behaviours per worker. | 1 claim change, 2 session changes | 40,000 behaviours, 4.0M states | a few minutes | -| `Ring.cfg` | The publisher and three relays in a ring, with a timer that fires at any moment. | 1 claim change, 1 session change | 813,075 | a minute or two | -| `Lag.cfg` | Relay 3 hears the publisher through relays 1 and 2: the lagging neighbour. | 2 claim changes, 1 session change | 1,702,001 | a few minutes | -| `LagWide.cfg` | The same, with relay 1 asking for `"a"` alone. | 2 claim changes, 1 session change | 3,846,369 | a quarter of an hour | -| `Dead.cfg` | Two relays behind a relay whose only uplink asks for `"a"` alone, one with a dear session of its own to the publisher. Simulated. | 3 claim changes, 1 session change | 40,000 behaviours, 4.8M states | ten minutes | -| `Blind.cfg` | A relay whose nearest neighbour asks for `"a"` alone, and a farther one knows everything. Simulated. | 2 claim changes, 1 session change | 40,000 behaviours, 4.8M states | ten minutes | -| `Overlap.cfg` | Five relays, three asking for `"a"`, with overlapping cheap broad and dear narrow paths. Simulated past the message budget. | 1 claim change, no session change | 1,000 behaviours per worker (4,000 on four workers), depth 500 | simulation | -| `Loop.cfg` | The publisher with a session to each of three relays in a triangle, all closing. Samples `RequestsLoopFree` with timer-only doubt. | 3 session changes | 1,000 behaviours per worker, depth 150, seed 1 | simulation | -| `Drain.cfg` | The publisher joined to two relays joined to each other; both hear its GOAWAY. Ranking only a relay's own drain exceeded `Budget`. | 1 claim change, 1 session change, GOAWAY on each session | 575,887 | two minutes | -| `DrainRing.cfg` | The publisher joined to three relays in a ring that is cheap one way round (`Ring`); all hear its GOAWAY. Without the DRAIN news, which ranks every path to the publisher as draining alike, a request looped round the ring with no session closed, breaking `LoopsAreStale`. Simulated. | 1 claim change, GOAWAY on each session | 1,000 behaviours per worker, depth 150, seed 1 | about a minute | -| `Prefer.cfg` | The same triangle, where both relays prefer the link between them. Ranking only a relay's own link priority exceeded `Budget`. | 1 claim change, 1 session change | 15,380 | seconds | -| `Upstream.cfg` | Two uplinks: the publisher on a CDN relay joined by a dear link to another, and a local mesh of two relays, each with an upstream link to one CDN relay. With the CDN link down, the second CDN relay has no route rather than one through the local mesh. The Rust fixture is `two_uplinks_never_carry_cdn_transit`. Without the export check, or with a flag that a LAN hop clears, `QuietIsSettled` and `DownOnly` fail within seconds. | 1 claim change, 1 session change | 76,992 | seconds | -| `UpstreamScoped.cfg` | The same, where the second CDN relay asks for `"a"` alone, so the stream to it over an upstream link picks among covering routes that are all down-only and ends. | 1 claim change, 1 session change | 71,680 | seconds | -| `EditNarrow.cfg` | The publisher with sessions to relays 1 and 2, the one to relay 2 dear; relay 2 watches everything and narrows to `"a"` or drops it once. | 1 claim change, 1 session change, 1 edit | 768,483 | three minutes | -| `EditWiden.cfg` | The same, where relay 2 watches `"a"` and widens to everything or drops it once. | 1 claim change, 1 session change, 1 edit | 3,655,573 | a quarter of an hour | -| `Edit.cfg` | The same with two edits, such as widening then narrowing back, or dropping everything then asking again. Before the rekey kept the route the sender would reflect, a widening then a narrowing crossing the close of relay 2's own session kept a route relay 1 learned through it and took a claim offline, breaking `Stable`. Simulated; an exhaustive pass covered every behaviour to depth 18 (10.6M states) before it was stopped. | 1 claim change, 1 session change, 2 edits | 40,000 behaviours, 4.8M states | four minutes | -| `Flap.cfg` | The publisher on relays 1 and 2, joined to each other, and relay 3 behind both; only the publisher's link to relay 1 opens and closes. Under the replaced rule, where doubt also kept relays off routes beginning at the publisher, `Routed` failed at once. Simulated. | 1 claim change, 4 session changes | 1,000 behaviours per worker, depth 150, seed 1 | about a minute | -| `TwoHomes.cfg` | The same, where both of the publisher's links open and close. Before `Patient` waited for stale offers too, a relay could take an offer naming a hop it had forgotten died and drop a claim it showed, breaking `Stable` within a minute. Simulated. | 1 claim change, 3 session changes | 1,000 behaviours per worker, depth 150, seed 1 | about a minute | -| `Homes.cfg` | The publisher on each of three relays in a ring that is cheap one way round, leaving all three. `RequestsLoopFree` fails within seconds; checks `LoopsLostThePublisher`. Simulated. | 3 session changes | 1,000 behaviours per worker, depth 150, seed 1 | about a minute | -| `HoldCycle.cfg` | The publisher on a hub with two open relays, and two relays asking for `"a"` alone, each joined to both open relays and nearer the other's choice. Before a hold followed only the path it was built on, the publisher's session closing left four holds waiting on each other for good, breaking `QuietIsSettled` within seconds. Simulated. | 1 claim change, 1 session change | 2,000 behaviours per worker, depth 200, a new seed each run | a few minutes | - -Run the affected config last, with at most one TLC process at a time. First run what answers in seconds: the router's tests (`quest gate just rs test -p moq-net --lib -E 'test(/route::tests::(handoff|residual|scope|compare|flap)/)'`, with `MOQ_ROUTE_SCENARIOS` raising the sweeps' count), then TLC's simulation mode with raised bounds in a copy of a config, such as `-simulate num=3000 -depth 150`. - -## Search the router - -`rs/moq-net/src/route/tests/search.rs` searches every order in which `Sim` can deliver, disconnect, connect, collect, fire a timer, and change a claim, on the compiled `path::Router`, depth first with a fingerprint per state. It checks `Truthful` (`Sim::check`), `NoRevival`, `NoFalseEnd`, `NoRegression`, `Stable`, `SimplePaths` (`Sim`'s own assertions on each path sent), `RequestsLoopFree`, `QuietIsSettled`, and `Budget` in every state, and prints a broken rule's path as `Sim` calls. It leaves out `Seen`, `StaleIsChased`, and `NoStaleReturn`, which read state the model names and the router keeps privately. Its timers are the router's own one-second timers, so a doubt raised earlier fires earlier, where the model's `Lift` fires in any order. The gate searches the triangle under `RouteHandoff.cfg`'s bounds; Nightly's `just test route-sweep` searches `RouteHandoff.cfg`'s own mesh, a dear link, nested claims, a scoped relay, a scoped grant, and a six-node mesh. - -```sh -quest gate just rs test -p moq-net --release --run-ignored all -E 'test(/^route::tests::search::/)' -``` - -## Reading a failure - -Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on the router with `Sim::with(Rule::PATH, nodes)` (`deliver`, `disconnect`, `connect`, `announce`, `wait`), one call per step, except a timer. `Lift(n, x)` fires one timer on one relay, where `wait(HOP)` moves every relay's clock by one hop of delay: call it until that doubt lifts, and where another doubt lifted with it, the replay took a different path, which is no defect in the model. - -## Coverage - -Sync commit: `cbb742cecae437ee94fbf25848521ac11b145fbc`, where [moq-dev/moq#8734](https://github.com/moq-dev/moq/pull/8734), which made doubt spare the node a route begins at, took in [the switch](https://github.com/moq-dev/moq/pull/8731). Run `git log cbb742cec.. -- rs/moq-net/src/route/path.rs rs/moq-net/src/route/reader.rs` to see what changed since. Prefix and reader indexes make the router's updates incremental; test-only full recomputation checks their result against the complete view. The model recomputes every prefix atomically and leaves that optimization out. `Rank` orders routes as `Offer::rank` does: drain, carried with each offer or known from a DRAIN (`Drains`), then the lowest link priority on the path (`Preferred`), then cost; `GoAway` marks a neighbour's session draining. `SelectKey` sets a route's down-only flag as `Router::usable_offer` does, and `Want0` ends a live down-only route toward an upstream link. `SrcKey` mirrors the router's preference for the best-ranked covering live path that does not name its receiver, leaving out down-only routes toward an upstream link and falling back to a held one, with the narrower scope breaking ties; `Select` plans live routes and their reflected sources before deciding holds; a held route keeps its last live path, so `SelectKey` holds under a next hop only on the path it was built on and `Want` ends a held stream whose source now has another path; `Advertise1` forwards a newer floor even when the claims did not change. `Asks` keeps one edit in flight per neighbour, as `Router::ask` does, and the marker answering it asks again for what changed meanwhile, as `Router::edited` does. The router keeps doubt until its one-second timer fires (`Lift::Timer`, `Doubt::DEFAULT`); the model's `Collect` leaves it for `Lift`. The comparison-only `Rule::EARLY` lifts doubt once no heard route names its node and is outside this timer-only model; the comparison-only `Rule::ORIGIN` lets doubt block a route that begins at the doubted node too, which `Flap.cfg` fails with `Doubted` defined as it was, and `Rule::SPARED` lets it block none, even a returning link. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. - -| Code | Model | -| --- | --- | -| `rs/moq-net/src/route/path.rs` `Router::run`, `Router::select`, `Router::retain` | `Select` plans live routes and their reflected sources before `SelectKey` decides holds. | -| `rs/moq-net/src/route/path.rs` `Offer::rank`, `Router::goaway`, `Router::drains`, `Router::report_draining`, `Router::dead` (`Dead::Draining`) | `Rank`, `Below`, `PathPrio`, `CostAt`, `GoAway`, `MarkDrain`, `Credited`, `ReportDrain`, `Recv` | -| `rs/moq-net/src/route/path.rs` `Router::pending`, `Router::hopes`, `Router::kept_off`, `Router::doubts_path` | `Pending`, `Hopes`, `Doubted`, `RelayDoubted` (a path's first node does not count), `Returned` | -| `rs/moq-net/src/route/path.rs` `Router::suspect`, `Router::doubt_until` | `Since`: a doubt on the publisher that begins notes the generation of the relay's own session to it. The router shares one generation across a session's streams (`Session::generation`), which the model's one stream per session leaves out. | -| `rs/moq-net/src/route/path.rs` `Router::src` | `SrcKey` | -| `rs/moq-net/src/route/path.rs` `Router::usable_offer`, `Offer` | `SelectKey`'s `Down`, `Want0`'s export check, and `DownOnly`: the down-only flag is set on a route learned over an upstream link or from a down-only one, and never sent over an upstream link. | -| `rs/moq-net/src/route/path.rs` `Router::want`, `Router::stream`, `Router::advertise`, `Router::report` | `Want`, `Want0`, `Streams`, `Advertise`, `Report` | -| `rs/moq-net/src/route/path.rs` `Router::route`, `Router::batch`, `Router::dead`, `Router::fail`, `Router::disconnect`, `Router::connect`, `Router::change` | `Recv`, `Fail`, `Disconnect`, `Connect`, `ChangeClaim` | -| `rs/moq-net/src/route/path.rs` `Router::collect_doubt`, `Router::timeout` | `Collect`, `Lift`, `Expire`: each dead hop's own timer retires it independently of later failures of the same node; reporting an already retained hop again does not restart its expiry. | -| `rs/moq-net/src/route/path.rs` `Router::know`, `Router::believed`, `Router::watched`, `Router::shown_now`, `Router::show` | `Know`, `NewView`, `Believed`, `Watched`, `ShownNow` | -| `rs/moq-net/src/route/path.rs` `Router::watch`, `Router::ask`, `Router::asks`, `Router::edit`, `Router::edited`, `Session::asking`, `rekey` | `Watch`, `Asks`, `Answer`, `Marker`, `Asking`, `Rekey`, `Moved`: the model's relays watch with no scope regions, so their asks are what they watch. | -| `rs/moq-net/src/route/reader.rs` `Reader::apply` | `Events` | -| `rs/moq-net/src/route/tests/mod.rs` `Sim::deliver` | `Deliver` | - -## Not covered - -SYNCED is left out: the router only records it per prefix (`Router::synced`, `Router::is_synced`), and nothing it decides reads it. So are scope regions: a relay asks for what it watches, and `interest.rs`'s `a_scope_with_several_regions_asks_for_each` and the sweeps cover a scope met with the interest. - -One publisher, so routes for several publishers are left out, and so are the copies and copy rank of cache-aware routing, which `rs/moq-net/src/route/tests/cache.rs` sweeps; the DEAD message's per-publisher batching reduces to one route per prefix. Two prefixes, one nested in the other, so an edit adds, removes, widens, or narrows one prefix at a time: no wildcards, swaps of several prefixes for one, stream cancellation, grants, qualified keys, or hidden claims. Leaves out two sessions between one pair of nodes at once, as a GOAWAY migration has: the model keeps one per pair, and among equal routes the router stays on the next hop's node and takes its latest session there (`a_later_session_to_the_next_hop_takes_over_among_equals`). Leaves out restarts, priorities other than 0 and 1, a priority that differs between a link's two ends, costs other than 1 and 2, and the hop limit. Down-only routes appear only where every relay's best route is also its only exportable one, so the model never shows a down-only best route hiding an exportable alternative, a cost the routes epic's contract accepts, and a relay that accepted a request from an upstream link never ends it when its route turns down-only. The hold deadline (`HOLD`), the stalled-writer close, and a scoped session's DEAD (`fail_heard`, which doubts and remembers nothing) are left out: a hold that ends early only lets go sooner, and the model's sessions are all unscoped. So are a session's mount keys: the node files each lite-07 session as one router key for both directions (`route/node.rs`), the model's one neighbour per session, edited in place, and a handle that reads through a mount answers under a further key of that session, which only sends. With no mounts, the model has no route its ROUTE_START marks `exact`, which only a mount at its mount point sends and which `rekey` keeps at its own prefix through a widening; `lite::rekey`'s and `lite::subscriber::routed`'s tests cover it. Messages come only from honest routers: validation of an unrelated DEAD or its far node, and empty or overlong replacement paths, is outside the model's input domain. Rust fixtures cover those guards and exportable covering-source selection, including keeping a covering hold when every live source is unexportable. Interest-edit fixtures also cover a cancelled stream retaining its pending child replies; the model has no stream cancellation. A claims message carries the sender's whole view for its prefix, equal to applying its changes on a FIFO stream. A route is sent on every stream whether or not the publisher has a claim there. The publisher ignores what it hears. `Overlap.cfg` also simulates five relays with every session up. No exhaustive pass has more than four relays or two session changes; `Sim`'s sweeps on the path rule (`sweep_handoff`, `sweep_scoped_handoff`, `sweep_scoped_meshes_show_what_the_rule_says`, and `compare.rs`'s churn) cover larger meshes, grants, qualified keys, interest edits, restarts, and churn. diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index f2272c52e39..c8536235681 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -402,7 +402,6 @@ jobs: # `rs quic-sim` sweeps moq-quic's simulated workloads from a fresh seed; PRs run a fixed 64. # `rs rung-disable` proves FFI simulcast disable and recovery on a shaped BBR3 uplink. # `test resume-model` sweeps resume against its model from a fresh seed; PRs run a fixed 64. - # `test route-key-model` proves the route key proof with Tamarin, and that each variant breaks what it names. # `test route-sweep` checks random lite-07 meshes against the route rules from a fresh seed; PRs run a fixed 8. # It also runs the router's handoff sweeps over 20,000 fixed scenarios; PRs run 150. # It also runs the bandwidth probe's acceptance suite, of which PRs run the short cases. @@ -418,7 +417,7 @@ jobs: # `rs v4l2` streams moq-video's V4L2 capture from the kernel's vivid # virtual camera, a module load no pull request job should make. # `js worklet-matrix` loads `?worklet` output through the bundlers pinned in test/worklet. - recipe: ["gate", "gh test-integration", "rs doctest --workspace", "test drill-sensitivity", "rs uring", "test drain", "test json-properties", "test resume-model", "test route-key-model", "test route-sweep", "rs quic-sim", "rs rung-disable", "test drill impaired", "rs cli-export", "rs hls-conformance", "rs quic-stress", "rs audio-devices", "rs multicast", "rs render-sw", "test qmux", "rs v4l2", "js worklet-matrix"] + recipe: ["gate", "gh test-integration", "rs doctest --workspace", "test drill-sensitivity", "rs uring", "test drain", "test json-properties", "test resume-model", "test route-sweep", "rs quic-sim", "rs rung-disable", "test drill impaired", "rs cli-export", "rs hls-conformance", "rs quic-stress", "rs audio-devices", "rs multicast", "rs render-sw", "test qmux", "rs v4l2", "js worklet-matrix"] include: # Miri interprets kio's and moq-net's in-memory unsafe and moq-sock's and moq-uring's # control-message walks; too slow for the merge gate. @@ -474,25 +473,17 @@ jobs: strategy: fail-fast: false matrix: - # The largest models get a runner each, as do the route model's two - # largest configs (Early about 14M distinct states, LagWide about - # 4.7M) and the warm model (its configs take about an hour together); - # the `route` and `rest` legs take every other config, so a - # new one is checked without editing this list. sh/gh/nightly.test.py - # fails on a path that no longer exists. + # The largest model gets a runner of its own, as does the warm model + # (its configs take about an hour together); the `rest` leg takes + # every other config, so a new one is checked without editing this + # list. sh/gh/nightly.test.py fails on a path that no longer exists. include: - name: resume paths: rs/moq-net/verify/resume - - name: route early - paths: rs/moq-net/verify/route/Early.cfg - - name: route lagwide - paths: rs/moq-net/verify/route/LagWide.cfg - - name: route - paths: "rs/moq-net/verify/route :!rs/moq-net/verify/route/Early.cfg :!rs/moq-net/verify/route/LagWide.cfg" - name: warm paths: rs/moq-net/verify/warm - name: rest - paths: ":!rs/moq-net/verify/resume :!rs/moq-net/verify/route :!rs/moq-net/verify/warm" + paths: ":!rs/moq-net/verify/resume :!rs/moq-net/verify/warm" steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 diff --git a/Cargo.lock b/Cargo.lock index a6aa6c54b4d..981c75e0844 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4429,18 +4429,11 @@ dependencies = [ name = "moq-crypto" version = "0.0.11" dependencies = [ - "data-encoding", - "hex", - "moq-net", "rind", "rind-rustls", "rustls", - "serde", - "serde_json", - "tempfile", "thiserror 2.0.21", "workspace-hack", - "zeroize", ] [[package]] @@ -4674,7 +4667,6 @@ dependencies = [ "tracing", "url", "workspace-hack", - "zeroize", ] [[package]] @@ -4784,7 +4776,6 @@ dependencies = [ "libc", "moq-auth", "moq-congestion", - "moq-crypto", "moq-net", "moq-quic", "moq-shaper", diff --git a/Cargo.toml b/Cargo.toml index f845e934194..ccc9315630d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -105,7 +105,6 @@ clap = { version = "4", features = ["derive"] } # CUDA driver bindings for the NVENC/NVDEC path. dlopen'd at runtime # (`fallback-dynamic-loading`), so nothing links against libcuda at build time. cudarc = { version = "0.19", default-features = false, features = ["driver", "fallback-dynamic-loading", "cuda-12020"] } -data-encoding = "2.11" dispatch2 = "0.3.1" ebml-iterable = "0.7.1" flate2 = { version = "1.1", default-features = false } diff --git a/demo/carla/bridge/Cargo.lock b/demo/carla/bridge/Cargo.lock index ee7790e162d..9c3e151d803 100644 --- a/demo/carla/bridge/Cargo.lock +++ b/demo/carla/bridge/Cargo.lock @@ -1341,7 +1341,6 @@ dependencies = [ "thiserror 2.0.21", "tracing", "url", - "zeroize", ] [[package]] @@ -2823,26 +2822,6 @@ dependencies = [ "synstructure", ] -[[package]] -name = "zeroize" -version = "1.9.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" -dependencies = [ - "zeroize_derive", -] - -[[package]] -name = "zeroize_derive" -version = "1.5.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328" -dependencies = [ - "proc-macro2", - "quote", - "syn 2.0.119", -] - [[package]] name = "zerotrie" version = "0.2.5" diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 8526c6357ae..d3ae9a76f39 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -301,7 +301,9 @@ declares in SETUP on moq-lite-05 and later: a Hop ID added to each route's hop list, or on the opt-in `moq-lite-07-wip` a Node ID naming the route's origin, which it also adds to the hops of each route it forwards. It is random on every start, so a restarted relay is a new node to the rest of the mesh, and there is no setting -to pin it. +to pin it. A Node ID also carries when the relay started, which orders the runs +of an identity kept across restarts; a relay's is new each time, so its clock +stepping back across a restart changes nothing. A relay never dials its own `cluster.node`, so every relay can share one `cluster.connect` list or API response. Peer URLs that differ only in query, diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 756052f816f..d1abcf23fd7 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -271,7 +271,6 @@ See [Authentication](/bin/relay/auth). connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost prices the link, or use {url, cost, egress, token, upstream} objects. node = "https://us-west.example.com/" # This relay's own URL. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. -route_key = "route.key" # Route key; relays sharing the file fail over as one to scoped peers. max_hops = 32 # Legacy: longest hop path on moq-lite-03 to 06 (1 to 32). [cluster.api] diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 336387708f6..c5ede1661b5 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -139,9 +139,9 @@ hidden names work exactly as before. timeline. A relay drops its copy of the old stream, so a new subscriber never sees its cached groups. -The instance, the epoch, and the restart message travel on moq-lite 07, which -is opt-in. `ANNOUNCE_START` and `ANNOUNCE_RESTART` carry the instance and -epoch, and `TRACK`, `TRACKS`, `SUBSCRIBE` and `FETCH` name the instance they +The instance and the epoch travel on moq-lite 07, which +is opt-in. `ANNOUNCE_START` carries the instance and epoch, `ANNOUNCE_UPDATE` +a higher epoch, and `TRACK`, `TRACKS`, `SUBSCRIBE` and `FETCH` name the instance they pin. A restart onto another instance, or a higher epoch of the same one, is advertised before the old one is withdrawn, so the path is never absent. Older moq-lite versions and moq-transport carry no instance, so the receiving session diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 04c3feec678..ec3534af5f0 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -69,12 +69,12 @@ These land with the next breaking release. HLS exporter numbers segments on from the media tracks themselves; Rust publishers and `@moq/publish` declare it. Neither side reads the other's shape, so upgrade HLS exporters and their publishers together. -- **Announce restarts.** moq-lite 07 adds `ANNOUNCE_RESTART` (0x3): another - instance, or a higher epoch of the same one, now serves the prefix. lite-06's - `ANNOUNCE_RESTART` is named `ANNOUNCE_UPDATE`, as it always meant. Elsewhere, - a restart is still an end then a start. +- **Announce restarts.** On moq-lite 07 another instance at a path starts + before the one it replaces ends, and `ANNOUNCE_UPDATE` carries a higher epoch + of the same one. lite-06's `ANNOUNCE_RESTART` is named `ANNOUNCE_UPDATE`, as + it always meant. Elsewhere, a restart is still an end then a start. - **Publisher instances ride the route.** moq-lite 07 carries the instance and - epoch after the path in `ANNOUNCE_START` and `ANNOUNCE_RESTART`, and the + epoch after the path in `ANNOUNCE_START`, and the pinned instance in `TRACK`, `TRACKS`, `SUBSCRIBE`, and `FETCH`. Older wires carry none, so the receiving session mints an instance per announcement: default lite-06 sessions, including cluster GOAWAY redials, lose seamless diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index d4fa2b0046a..966261f0ca4 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -19,7 +19,6 @@ author: normative: moqt: I-D.ietf-moq-transport qmux: I-D.ietf-quic-qmux - webtrans-h3: I-D.ietf-webtrans-http3 qmuxws: title: "QMux over WebSocket" target: https://datatracker.ietf.org/doc/draft-lcurley-qmux-websocket/ @@ -30,14 +29,11 @@ normative: date: false RFC3986: RFC6455: - RFC8032: - RFC8446: RFC9000: RFC9002: informative: I-D.lcurley-moq-cluster: - RFC7627: moqflate: title: "DEFLATE Compressed Tracks for MoQ" target: https://datatracker.ietf.org/doc/draft-lcurley-moq-flate/ @@ -133,7 +129,7 @@ Any broadcasts and subscriptions are transparently proxied by the CDN behind the A Broadcast is a collection of Tracks named by a path. This corresponds to a MoqTransport's "track namespace". A path is a sequence of non-empty segments joined by `/` (0x2F), so it never starts or ends with a separator or contains two in a row; the empty path has no segments and prefixes every path. -A `\` (0x5C) escapes the `\` or `/` that follows it, as a MoqTransport namespace field holding either is spelled; a path with any other `\` is a PROTOCOL_VIOLATION, or in a claim refused (see [Refused Content](#refused-content)). +A `\` (0x5C) escapes the `\` or `/` that follows it, as a MoqTransport namespace field holding either is spelled; a path with any other `\` is a PROTOCOL_VIOLATION. A segment is the text between two `/` that no `\` escapes, so `a\/b` is one segment, one namespace field holding a `/`; every rule that counts, matches, or compares segments reads them this way, and a prefix never ends inside an escape. A continuous stream is named by an Instance, carried on its claims (see [ANNOUNCE_START](#announce-start)): a path and an Instance name one Broadcast, and a publisher MUST NOT serve different content under the same pair. Within one Instance, a Group start never names two different Groups, so claims sharing it serve the same bytes; two Instances are independent streams, never stitched together. @@ -373,34 +369,35 @@ If the stream is closed, potentially with an error, the transaction is terminate Discovery and routing instead share one unidirectional [Announce Stream](#announce) per endpoint. ## Announce Stream {#announce} -Each endpoint MAY open one unidirectional Announce Stream (0x3), on which it sends everything it says about discovery and routing, in order: as a subscriber, the prefixes it wants claims for, and as a publisher, the routes and claims answering the prefixes its peer wants. -A claim is an announcement that paths under its prefix can be served by one origin node; it claims capability, not inventory, so it never asserts that any specific broadcast exists. -A route is how the publisher reaches an origin node for the paths under a prefix, and every claim on the stream travels under a route to its origin covering it (see [Routing](#routing)). +Each endpoint MAY open one unidirectional Announce Stream (0x3), on which it sends everything it says about discovery and routing, in order: as a subscriber, the prefixes it wants claims for, and as a publisher, the claims answering the prefixes its peer wants, and the routes they travel under. +A claim is an announcement that the paths under its prefix can be served; it claims capability, not inventory, so it never asserts that any specific broadcast exists. +A routing node is an endpoint that forwards and sends the [Node ID Parameter](#node-id-parameter); two routing nodes also exchange routes (see [Routing](#routing)), and every other session carries claims alone (see [Claims](#claims)). An endpoint that opens the stream keeps it for the session, so no message it sends about routing overtakes another. An endpoint MUST close the session with a PROTOCOL_VIOLATION if its peer opens a second Announce Stream or resets one. -An endpoint finishes its stream only when it is leaving the session, after a ROUTE_END for each route it sent. +An endpoint finishes its stream only when it is leaving the session, which ends every route and claim it sent. Its peer keeps answering the prefixes the endpoint asked for, which it can no longer edit. A subscriber edits the set of prefixes it wants claims for with ANNOUNCE_REQUEST messages. An edit too large for one message continues over several: every ANNOUNCE_REQUEST of an edit but the last sets `More`, and nothing else comes between them on the stream. The set starts empty and MAY be empty, no prefix in it is at or below another, and encoded as the Adds of one ANNOUNCE_REQUEST it fits the [Message Length](#message-length) limit. -A subscriber starts an edit only once the publisher has answered its last. +A subscriber MUST NOT send an edit before the publisher has answered its last, so a publisher holds at most one unanswered: a subscriber whose interest moves meanwhile sends what it wants by then as its next edit. -A publisher answers each edit with one ANNOUNCE_OK, after the edit's last ANNOUNCE_REQUEST, where the edit takes effect on its stream (see [Edits](#edits)), and sends the matching routes and claims and any future changes: +A publisher answers each edit with one ANNOUNCE_OK, where the edit takes effect on its stream (see [Edits](#edits)), and sends the matching claims and any future changes: -- ANNOUNCE_OK: the peer's last edit takes effect here. -- ROUTE_START: the publisher reaches an origin node for a prefix. -- ROUTE_UPDATE: a route's path, drain, priority, metric, or down-only bit changed. -- ROUTE_HOLD: the publisher has no usable route but holds it while it recovers. +- ANNOUNCE_OK: the peer's unanswered edit takes effect here. +- ANNOUNCE_START: a matching claim. +- ANNOUNCE_UPDATE: a claim changed. +- ANNOUNCE_END: a claim is gone. +- SYNCED: the initial set of one prefix is complete. + +And between routing nodes: + +- ROUTE: the publisher's route to a routing node, new or changed. - ROUTE_END: the publisher let go of a route and every claim under it. -- DEAD: a session on the path of routes the publisher sent closed, or a node on it sent a GOAWAY. -- ANNOUNCE_START: a matching claim of a route's origin node. -- ANNOUNCE_END: the origin withdrew a claim. -- ANNOUNCE_UPDATE: a claim's cost changed. -- ANNOUNCE_RESTART: a claim now serves another Instance, or a higher Epoch of the same one. +- DEAD: a session on the path of routes the publisher sent closed. +- DRAIN: a node on the path of routes the publisher sent sent a GOAWAY. - ANNOUNCE_FLOOR: a batch of a route's claims is complete. -- SYNCED: the initial set of one prefix is complete. The publisher MUST send [SYNCED](#synced) exactly once for each prefix an edit adds, after the ANNOUNCE_OK answering it and the prefix's initial set, unless a later edit removes the prefix first. The subscriber MAY batch a prefix's messages until its SYNCED; subsequent ones are live updates. @@ -409,95 +406,75 @@ The publisher MAY coalesce changes to a claim it has not yet sent, and sends no A retraction of a claim or route already sent MAY precede SYNCED. A prefix outside the subscriber's [scope](#auth-stream) lists nothing and is SYNCED at once. -Each Add of an ANNOUNCE_REQUEST implicitly assigns the next Prefix ID on its sender's stream, each ROUTE_START the next Route ID, and each ANNOUNCE_START the next Announce ID: three counters per stream starting at 0 that increment by 1 per assignment. -No id appears on the wire where it is assigned; both endpoints derive it from the message order on the (reliable, ordered) stream, and other messages reference it instead of repeating the prefix, the origin node and the route's prefix, or the claim's prefix. -A ROUTE_START and a SYNCED name a Prefix ID the peer assigned; every other id a message names is its sender's. +Each Add of an ANNOUNCE_REQUEST implicitly assigns the next Prefix ID on its sender's stream, each ROUTE to a routing node the stream has no live route to the next Route ID, and each ANNOUNCE_START the next Announce ID: three counters per stream starting at 0 that increment by 1 per assignment. +No id appears on the wire where it is assigned; both endpoints derive it from the message order on the (reliable, ordered) stream, and other messages reference it instead of repeating the prefix, the routing node, or the claim's path. +A SYNCED names a Prefix ID the peer assigned; every other id a message names is its sender's. Ids are never reused within a stream. -A ROUTE_END retires its Route ID and the Announce ID of every claim under the route; an ANNOUNCE_END retires one Announce ID, and an edit the Prefix IDs it removes. - -A stream has at most one live route per origin node and prefix, and each route at most one live claim per prefix, at or below the route's prefix. -Another origin claiming the same prefix is another claim, under its own route. -An ANNOUNCE_UPDATE or ANNOUNCE_RESTART atomically replaces a claim while keeping its id live; a claim moves to another route only at an [edit](#edits). +A ROUTE_END retires its Route ID and the Announce ID of every claim under the route; an ANNOUNCE_END retires one Announce ID, and an edit the Prefix IDs it removes and the Announce ID of every claim it drops. An endpoint MUST close the session with a PROTOCOL_VIOLATION if it receives: - a message referencing a Prefix ID, Route ID, or Announce ID that was never assigned or already retired; -- an edit before its last was answered, any other message between the ANNOUNCE_REQUESTs of one edit, or an edit that leaves a prefix of the set at or below another or the set past the limit; -- an ANNOUNCE_OK with no edit unanswered, or between a route's claim message and the ANNOUNCE_FLOOR closing its batch; -- a ROUTE_START for an origin node and prefix that already have a live route on the stream; -- an ANNOUNCE_START for a prefix its route already claims or outside the route's prefix; or -- a second SYNCED for a prefix, or one before the ANNOUNCE_OK answering the edit that added it. +- any other message between the ANNOUNCE_REQUESTs of one edit, or an edit that leaves a prefix of the set at or below another or the set past the limit; +- an ANNOUNCE_OK with no edit unanswered, or an ANNOUNCE_REQUEST starting an edit while one is; +- an edit from a routing neighbour that leaves its set anything but empty or the empty prefix alone; +- any message but ANNOUNCE_OK and ANNOUNCE_REQUEST before the first ANNOUNCE_OK on the stream, which answers nothing yet; +- a second SYNCED for a prefix, or one before the ANNOUNCE_OK answering the edit that added it; +- a ROUTE, ROUTE_END, DEAD, DRAIN, or ANNOUNCE_FLOOR on a session that does not exchange routes; or +- a message that does not decode within its Message Length, a flag this version does not define, or a Node ID of 0. When the session closes, an endpoint MUST assume that every route and claim on the peer's stream is gone. -A broadcast path has at most 32 segments and at most 4,096 bytes; a receiver MUST close the session with a PROTOCOL_VIOLATION on a longer one, except in a claim, which it refuses instead (see [Refused Content](#refused-content)), including one resolved by [Compression](#announce-compression). +A broadcast path has at most 32 segments and at most 4,096 bytes; a receiver MUST close the session with a PROTOCOL_VIOLATION on a longer one, except one resolved by [Compression](#announce-compression) or joined beneath a root of the receiver's own, whose claim it drops: the ANNOUNCE_START still assigns its Announce ID, the messages naming it stay valid, and the receiver SHOULD log and count it. A claim covers a path when its prefix is a leading run of the path's segments; matching is per path segment, so a prefix never matches half a segment, and equality is byte-by-byte within each segment. -A publisher presents, per route, each claim inside the requested prefix the route lies in and only the most specific claim at or above it, at that prefix itself, which is exactly the covered set the subscriber may see. +A publisher presents each claim inside a requested prefix and only the most specific claim at or above it, at that prefix itself, which is exactly the covered set the subscriber may see. A claim presented above its own prefix carries how many segments broader it is than the path it is presented at, its Above, so the subscriber can tell it from a claim exactly at that path. -Every path on the stream is relative to the session, whichever requested prefix it lies in, so carrying a route over to another prefix (see [Edits](#edits)) changes no claim's path. -When that most specific covering claim changes, such as when it is withdrawn and a broader one still covers the prefix, the publisher moves the presented claim to the new one with an ANNOUNCE_UPDATE or ANNOUNCE_RESTART, and ends it only when no claim of the route covers the prefix. +Every path on the stream is relative to the session, whichever requested prefix it lies in. ### Edits {#edits} An edit takes effect on the publisher's stream at the ANNOUNCE_OK answering it. Until then the publisher's messages answer the set before it, so they may still name a prefix the edit removes, and never after. -At the ANNOUNCE_OK both endpoints carry the stream's live routes over to the new set alike, so the publisher sends nothing again that both sets cover. -Each route lies in one prefix of the old set, and in Route ID order: +At the ANNOUNCE_OK both endpoints drop every claim on the stream whose path lies within a prefix the edit removes, retiring its Announce ID, with no ANNOUNCE_END. +The publisher then sends what the added prefixes cover, a claim the removed prefixes also covered included, and a SYNCED for each. +A receiver that could not resolve a claim's path (see [ANNOUNCE_START](#announce-start)) cannot tell whether a removed prefix held it: it keeps the claim's Announce ID valid until the publisher ends it, or until the edit leaves no prefix that was in effect before it, when every earlier claim is dropped. -- It stays when the new set covers its prefix, and the old prefix it lies in is in the new set, the route lies strictly below that old prefix, or its ROUTE_START set `Exact`. -- Otherwise, when an added prefix is above the old prefix it lies in, it widens: it becomes its origin node's route at that added prefix, without the claim at its own prefix, and certifies nothing until its next ANNOUNCE_FLOOR. -- Otherwise, when it lies at the old prefix itself, it narrows: for each added prefix below it, in the order the ANNOUNCE_REQUEST added them, it becomes a route of its origin node at that prefix, with its claims strictly below that prefix and, at that prefix itself, its most specific claim at or above it. Each keeps its last floor. -- Otherwise it ends, as on ROUTE_END. +Routes are not requested by prefix: a publisher sends a routing neighbour routes exactly while the neighbour's set is the empty prefix. +An edit that empties the set drops every route on the stream, and every claim under one, at the ANNOUNCE_OK, retiring their ids with no ROUTE_END; asking for the empty prefix again starts them anew. -A stream still has one route per origin node and prefix. -Of the routes that would share one, the one that remains is the first of: one that is not held, one whose Path does not name the Node ID the subscriber's SETUP declared, the best ranked (see [Routing](#routing)), one that stayed, and the lowest Route ID. -A widened route that remains takes the claims of the widened routes that do not, and every other route that does not remain ends. +### Claims {#claims} +On a session that does not exchange routes, a publisher sends the claims its own requests would resolve, and nothing of how it reaches them. +For each path and Instance its peer's prefixes present, it sends at most one claim: the one it would serve a request there from (see [Resolution](#resolution)), and never one it learned from that peer. +The claim carries the publisher's cost to it, the lowest priority and any drain on the way, and its chain (see [ANNOUNCE_START](#announce-start)). -A route that stays or widens keeps its Route ID, and its claims keep their Announce IDs. -A route that stays keeps its `Exact`, and a widened or narrowed route carries on as one whose `Exact` is 0. -Each narrowed route that remains is assigned the next Route ID, in the order above; its claims keep their Announce IDs, except that its claim at its prefix is assigned the next Announce ID when the claim it comes from lies above it, and that claim's Above grows by the segments its prefix lies below the claim it comes from. -Whether a Route Suffix, a Route Offer, or a claim's path is refused (see [Refused Content](#refused-content)) depends only on what the publisher sent and the requested prefixes, so both endpoints carry the routes over alike and assign the same Route IDs and Announce IDs: a route whose Route Suffix is refused is carried as one at its requested prefix, a refused Route Offer ranks after every other, and a claim whose path is refused is not among its route's claims. -A path the subscriber cannot hold for a limit of its own, such as one it joins beneath a local root, is carried as the stream names it. -The publisher then sends whatever the carried routes lack, and an ANNOUNCE_FLOOR for each widened route. +When the publisher's way to a claim changes, it sends an ANNOUNCE_UPDATE. +While it has no way to a claim it still holds, it sets the claim's `Unavailable` flag rather than withdrawing it, and fails requests for it with UNROUTABLE; it sends an ANNOUNCE_END with `Lost` once it has shown the claim unavailable for 800 milliseconds. +A receiver takes `Unavailable` only as a change to a claim it already holds at that Epoch and Above: it does not hold a claim it is first told unavailable until an ANNOUNCE_UPDATE clears the flag. +Another Instance at a path is another claim: the publisher sends its ANNOUNCE_START before the ANNOUNCE_END of the one it replaces, so the subscriber sees the broadcast restart rather than go. + +A receiver adds the session's link cost (see [Cost Parameter](#cost-parameter)) to the claim's cost, and takes the lower of the claim's priority and its own local priority for the session. +A routing node that receives a claim this way announces it to its routing neighbours as its own (see [Routing](#routing)). +When the sender is itself a routing node, confined to claims by a scoped grant, or the claim arrived over an earlier version, the receiver first appends its own Relay to the claim's chain, and MUST NOT take a claim whose chain names its Relay or would reach 32 Relays. ### Floors {#floors} -Each origin node numbers the changes to its own claims with a Revision, starting at 0 for each Node ID. -A stream carries a route's claims in batches: the ANNOUNCE messages under the route since its last ANNOUNCE_FLOOR, closed by the next one. -The publisher sends a ROUTE_START before any claim under it, and a prefix's SYNCED only once every route it sent in that prefix has a floor. - -A floor names a Revision and certifies that the stream's claims for the route, across the route's whole prefix, are the origin's claims at that Revision as the request presents them (see [Announce](#announce)). -It certifies only what its requested prefix shows: one added without `Hidden` certifies nothing about hidden claims. -A publisher that does not know the route's claims across its whole prefix at one Revision, such as a relay that knows them only beneath part of it, still closes each batch, with a floor that certifies nothing. -A subscriber that may receive claims only beneath some prefixes, because its [scope](#auth-stream) or the publisher's confines it there, SHOULD request those prefixes rather than one above them, so the publisher can certify each, and edits its set when they change. - -The subscriber applies a batch whole, once its floor arrives. -A receiver keeps one view of an origin's claims for each prefix it holds a route to the origin at: the claims of the floor with the highest Revision that a route it believes, at that prefix or one covering it, gave it. -It believes a route while the route is usable, its Path does not name the receiver, and the receiver wants the prefix it lies in, with no edit unanswered that removes it; a held route, or one the receiver refused, certifies nothing. -An older floor never revives a claim whose withdrawal a newer one delivered. -While no route it believes has given a floor that certifies the prefix, the view holds the claims its selected route carries there, uncertified: a floor that certifies nothing proves no claim absent. -The view stays whole while the receiver holds a route covering the prefix, usable or held, and the receiver shows each claim from the view at the narrowest prefix covering it, available while a usable route covers it. -Once the receiver holds no route covering the prefix, the view's claims go offline, which is not an ANNOUNCE_END. +Each routing node numbers the changes to the claims it announces with a Revision, starting at 0 for each Node ID. +Between routing nodes a stream carries a route's claims in batches: the ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_END messages since the last ANNOUNCE_FLOOR all change the claims of the routing node that the route the next ANNOUNCE_FLOOR names leads to. +A batch names each claim at most once, and its floor carries a Revision higher than the last the publisher sent for the route; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise. + +A floor certifies that the publisher's copy of that node's claims, with the batch applied, is complete as of the Revision. +A publisher therefore sends a routing neighbour every claim under a route, and the neighbour asks for the empty prefix or for nothing: it MUST NOT ask for part of the tree. +A receiver keeps each neighbour's copy, and its own view of the node's claims follows the copy with the highest Revision: a batch at or below the Revision of its view changes only the sender's copy, so an older copy never revives a claim whose withdrawal a newer one delivered. +A claim a newer copy lacks is lost, unless the batch says its publisher ended it (see [ANNOUNCE_END](#announce-end)). ### Compression {#announce-compression} An ANNOUNCE_START MAY copy the head of its path from a live claim on the same stream, its base. `Path Base` names it by distance: the base's Announce ID is the next unassigned Announce ID minus `Path Base`, so 1 names the latest ANNOUNCE_START, and 0 names no base. The receiver resolves the base against the claims live when the message arrives, and the result is identical to the literal encoding: a base ending later changes nothing. -The base need not share the new claim's route, nor the requested prefix that route lies in. +The base need not share the new claim's route, nor the requested prefix it lies in. A publisher MAY always send a `Path Base` of 0. The subscriber MUST close the session with a PROTOCOL_VIOLATION if a non-zero `Path Base` names an Announce ID that was never assigned or already retired, or a `Path Keep` is non-zero with a `Path Base` of 0 or exceeds the base's segments. -A resolved path that breaks its own rules, or a base whose path the subscriber refused, refuses the claim (see [Refused Content](#refused-content)). - -### Refused Content {#refused-content} -Route messages carry content the publisher may only have forwarded: a route's Node ID, Route Suffix, and [Route Offer](#route-offer), and a claim's path, Instance, and Lite-06 Chain. -A newer version or release may send such content that an older receiver cannot use, so a receiver that refuses it withdraws only the route or claim it describes and keeps the session, as BGP treats a malformed attribute as a withdrawal ({{?RFC7606}}). -This specification marks each such value "refused"; the receiver skips the rest of the message's body, and SHOULD log and count each refusal so a refused route is never silently missing. - -- A refused ROUTE_START still assigns its Route ID, and a refused ROUTE_UPDATE, one following a [DEAD](#dead) included, keeps it; each leaves the receiver no route, so its claims go offline as on ROUTE_END. The messages naming the Route ID stay valid, and a later ROUTE_UPDATE the receiver can use makes the route usable again, with the claims its last floor certified. A route to Node ID 0, or whose Route Suffix was refused, stays refused. A refused Route Offer's Path still counts, so a later DEAD naming a hop on it applies to the route as to any other. -- A refused ANNOUNCE_START still assigns its Announce ID, and a refused ANNOUNCE_UPDATE or ANNOUNCE_RESTART keeps it; the claim goes offline at its route's next floor, which is not an ANNOUNCE_END. A claim whose path was refused stays refused; any other comes back with a later ANNOUNCE_RESTART the receiver can use. Its origin withdrew nothing, so while a route has a live claim the receiver refused, the receiver takes the route's floors as certifying nothing, and a relay forwards no withdrawal for the claim. - -Only the publisher's own framing and stream state close the session: a message that does not decode within its Message Length, and a message naming an id that was never assigned or already retired, or breaking the stream's order, as above. -A relay never forwards content a peer would refuse for the relay's own part in it: a route that arrives with 32 hops is unusable, so the relay's own hop never takes one past 32. +A resolved path that breaks its own rules, or a base whose claim the subscriber dropped, drops the claim (see [Announce](#announce)). ### Hidden Paths {#hidden} A claim is hidden from a request when a segment of its path below the requested prefix starts with `.` (0x2E). @@ -509,113 +486,72 @@ Hiding is a convenience for discovery, not access control: a publisher MAY treat SUBSCRIBE, FETCH, and TRACK resolve a hidden path exactly as any other. ### Routing {#routing} -Each node selects, per origin node and prefix, one route by its path: the nodes it crossed, each with the session it was learned on. -A node never uses a route whose path names it, and a node that loses a session names that hop to its neighbours, so every route through it is dropped wherever it went. -There is no distance, sequence number, route request, or echo. - -An origin node names itself with a Node ID: a non-zero 64-bit value, fresh for each process restart and shared by every session of that process. -An origin MUST NOT declare a Node ID with the most significant bit set. -That bit marks a qualified Node ID: a relay files every Node ID a peer with a scoped publish grant sends (see [AUTH_OK](#auth-ok)), the peer's own included, under a qualified Node ID of its own derivation, collision-resistant at 64 bits, and translates it back when it forwards a request on that session. -The derivation is keyed by the key the peer proved with the [Route Key Parameter](#route-key-parameter), so peers sharing one key are filed alike and fail over as one, or by a key unique to the session when the peer proved none. -A relay MUST ignore a qualified Node ID received from such a peer, and claims under its qualified Node IDs outside that peer's grant. -A Node ID is otherwise declared, not proven. - -A route covers a prefix: the one its receiver requested, or a narrower one that a node on its path requested. -For each prefix its peer requested, a publisher's stream carries its route to each origin node at every prefix inside it, under that prefix, and at the requested prefix itself the best-ranked usable route covering it. -A node keeps, ranks, and selects its routes per origin node and prefix. - -An origin advertises its own route with a Metric of 0. -A receiver adds the session's link cost (see [Cost Parameter](#cost-parameter)) to the Metric of every route the peer sends; the sum is its metric through that peer. -Each link adds at least 1, so a route's metric strictly increases away from its origin. -A metric that overflows 64 bits makes the route unusable. - -A route carries its Path: one hop per node it crossed, the origin node first and the sender last. -A hop names a node by its Hop ID, and the session the node learned the route on by its Session Number. -A Hop ID is a non-zero 64-bit value a node names itself with for as long as its process runs, such as the Node ID it started with; a rotation of its Node ID does not change it. -A node numbers each session it opens or accepts with a Session Number of its own, unique among its sessions for as long as its process runs, so a restarted process MUST take a new Hop ID. -An origin's own route has a Path of its own hop alone, with Session Number 0, and a node sending a route it learned appends its own hop, naming the session it learned the route on. -A relay forwards the other hops unchanged and never qualifies them. -A route that arrives with 32 hops is unusable, since the receiver's own hop would take it past 32. - -A route is draining when a node on its Path sent a GOAWAY, as the route's draining flag or a [DEAD](#dead) says, or when its session received one. -Its priority is the lowest local priority of a session on its Path: a receiver takes the lower of the priority the route carries and its own local priority for the session, and an origin's own route carries the highest. -A node ranks its usable routes to an origin node at a prefix: one that is not draining first, then the highest priority, then the lowest metric. -Extending a route never clears its drain, never raises its priority, and always raises its metric, so no node ranks a route above how the neighbour it came from ranked it, and selection converges. -A node selects its best-ranked usable route at once. -A route is unusable while its Path names the node, it is held, a hop on its Path is dead, the doubt keeps the node off it (see [Dead Hops](#dead-hops)), it arrived with 32 hops, or its metric overflows. -A node MAY mark a session upstream. -A route is down-only when it arrived on an upstream session or with its down-only flag set; a node sends a down-only route with the flag set, and never on an upstream session. - -A node sends a peer its route to an origin node at a prefix only while the route has a claim the peer's requested prefix presents (see [Announce](#announce)): it sends ROUTE_START before the first such claim, and once the last one is withdrawn, the batch carrying that withdrawal, closed by its floor (which certifies the withdrawal where the node can certify the request), then ROUTE_END. -A subscriber therefore holds no route for an origin node its requests do not meet. -A node that does not forward, such as a client, sends only its own route. -An origin never advertises a Revision of 2^64-1: a change that would reach it instead rotates its Node ID, ending the old route everywhere and announcing its claims again under the new one. - -A SUBSCRIBE, FETCH, TRACK, TRACKS, or DATAGRAMS request names the origin node that serves it, and the Route Depth of the route it follows: how many leading segments of its Broadcast Path make up the route's prefix. -A subscriber that names 0 lets the publisher select one (see [Resolution](#resolution)), and a relay forwarding a request names the origin node and Route Depth of the route it selected or was given. -A relay forwards a request naming an origin node only along the route it sent the requester to that node at that prefix, and resets it with UNROUTABLE when that route is no longer usable or its Path names the requester, so the request never reaches another origin, and loops only briefly after an origin on three or more relays leaves them all at once (see [Dead Hops](#dead-hops)). +Routing nodes route to each other by path vector. +A route leads to a routing node that announces claims, never to a publisher: the claims of an endpoint belong to the routing node it connects to, which announces them under its own Node ID and Revision (see [Floors](#floors)). + +A routing node names itself with a Node ID: a non-zero identifier of the relay and its Start, a number that is higher each time the relay's process starts, such as its start time. +A Node ID is declared, not proven. +Two endpoints exchange routes when both send the [Node ID Parameter](#node-id-parameter); each MUST close the session with UNAUTHORIZED when either's grant (see [AUTH_OK](#auth-ok)) covers less than every path, so a peer confined to part of the tree sends claims alone. + +A route carries its Path: one hop per node it crossed, the node it leads to first and the sender last. +A hop names a node by its Node ID, and the session the node learned the route on by its Session Number: a number of the node's own, unique among its sessions and higher for each one it opens or accepts. +A node offers a route to itself, with a Path of its own hop alone, Session Number 0, and cost 0, from when it first announces a claim until it restarts. +A node sending a route it learned appends its own hop, naming the session it learned the route on, and adds that session's link cost (see [Cost Parameter](#cost-parameter)), which is at least 1. +A Path has at most 32 hops, and a route whose cost would overflow 64 bits is never used. + +A node never uses a route whose Path names its own relay, at any Start. +It sends a neighbour its selected route to each routing node, except back over the session it learned the route on, to a neighbour already on the Path, or, when the route is marked, to a neighbour on a marked session. +A node MAY mark a session, such as one to an upstream it only reads from: a route is marked when it arrived on a marked session or with its marked flag set. + +A route is draining when a node on its Path sent a GOAWAY, as its draining flag or a [DRAIN](#drain) says. +Its priority is the lowest local priority of a session on its Path: a receiver takes the lower of the priority the route carries and its own local priority for the session, and a node's route to itself carries the highest. +A node ranks its routes to a routing node: one that is not draining first, then the highest priority, then the lowest cost. +Extending a route never clears its drain, never raises its priority, and always raises its cost, so no node ranks a route above how the neighbour it came from ranked it, and selection converges. +Among routes of equal rank a node selects one that is not marked, then the one through the neighbour it already uses. +A node selects at once: there is no hold, and no timer between routing nodes. + +A receiver MUST close the session with a PROTOCOL_VIOLATION on a ROUTE whose Path does not begin with a hop of Session Number 0, does not end with the sender's Node ID, names the receiver's relay, or has one hop and a cost other than 0. + +A SUBSCRIBE, FETCH, TRACK, TRACKS, or DATAGRAMS request names the routing node that announces the claim serving it. +A subscriber that names none lets the publisher select one (see [Resolution](#resolution)), and a relay forwarding a request names the node it selected or was given. +A relay forwards a request naming a routing node only along its selected route to that node, or to the endpoint whose claim it announces when the request names the relay itself, and resets it with UNROUTABLE when it has neither. Claims with the same Instance serve the same Broadcast, so a relay MAY move a live subscription between them, including onto a higher Epoch, continuing from the first frame the subscriber lacks, and a route change (a reconnect, a cheaper path, a draining session) is invisible to the subscriber. A relay MUST NOT move a subscription to a claim with a different Instance: it stays on its Instance's claims and ends with the last of them. -When another Broadcast wins the path, subscriptions already open stay on theirs until the subscriber drops them or the claim goes; new requests resolve the winner, and the ANNOUNCE_RESTART tells subscribers to request again. -A receiver of an ANNOUNCE_RESTART (or of the ANNOUNCE_END and ANNOUNCE_START standing in for one) MUST NOT serve a new request under its prefix from anything resolved through the replaced claim. +When another Broadcast wins the path, subscriptions already open stay on theirs until the subscriber drops them or the claim goes; new requests resolve the winner. A version before this one carries no Instance, so a receiver of such a session mints one for each ANNOUNCE_START it receives, with Epoch 0, and forwards it as the claim's Instance with `Minted` set, so a reader can tell it names an announcement rather than the publisher's stream. A minted Instance is new for every announcement, so a publisher reconnecting or re-announcing through such a hop is another stream. -### Dead Hops {#dead-hops} -A node that loses a session names the hop it lost: its own Hop ID and that session's Session Number, with the Hop ID of the node at the far end. -It sends one [DEAD](#dead) for it to each neighbour it sent a route whose Path holds the hop, covering every origin node, and each neighbour passes the hop on in the same way, once per neighbour while it has sent that neighbour a route through it. -The DEAD counts the routes on the stream that moved to another Path, and a ROUTE_UPDATE for each follows it with its new Route Offer; the receiver applies the DEAD and those updates as one. -The sender's other routes on the stream through the hop end if `Gone` is set. -Otherwise each is held, except one the sender ends with a ROUTE_END after the DEAD, and one the sender learned from the receiver itself, which the sender holds only by a ROUTE_HOLD after the DEAD: until then the receiver waits for its answer (see [Holds](#holds)). - -A receiver applies a DEAD only when a route that peer sent it holds the named hop right after a hop of the far node; otherwise it changes nothing. -Then every route through the hop is dead, whoever sent it: the sender's routes carry on as the DEAD says, and every other route through the hop is unusable until its own sender says what became of it. -The receiver remembers the dead hop, so a route through it that arrives late stays unusable. - -A closed session also casts doubt on the node at its far end, since a dead relay is reported one neighbour at a time: a neighbour that has not heard yet may still offer a stale route through it. -A receiver doubts the far node for one second, during which it moves onto no route whose Path names that node after the origin node's hop, and onto no route the doubted node originates whose Path is that node's hop alone, received on a session that opened since the doubt began; the route it already uses stays usable. -Any other route the doubted node originates stays usable, since a route cannot loop through its own origin: an origin on several relays stays reachable through the others while its session to one of them flaps, and a session that reopens waits out the doubt, which damps the flaps. -A node cannot tell an origin leaving from its session to one relay closing, so an origin on three or more relays that leaves them all at once can send a request round them, each relay on a neighbour's route that the neighbour's own close made stale, until that neighbour's DEAD arrives. -Nothing on the wire carries the doubt. -A node that sees a session close doubts its far end in the same way. - -On a session whose peer holds a scoped publish grant (see [AUTH_OK](#auth-ok)), a DEAD applies only to the routes heard on that session, and the receiver neither remembers the hop nor doubts the far node: a peer withdraws only what it sent, and cannot drop routes through a hop it only read in a path. -Such a peer also names itself as it likes, so its GOAWAY ranks only the routes heard on that session draining and is not passed on, and its session closing doubts no node and sends no DEAD: the routes it sent end one by one. - -A node that receives a GOAWAY ranks every route through its peer draining, and doubts the peer as a closed session's far end, so it moves at once only onto routes that avoid it. -It sends a DEAD naming the draining node to each neighbour it sent a route through that node, and each neighbour passes it on in the same way, once per neighbour while it has sent that neighbour such a route. -A receiver applies it only for a node on a route that peer sent it, ranks every route through that node draining, and doubts the node in the same way. -A draining route stays usable. - -### Holds {#holds} -A node with no usable route to an origin node at a prefix holds the route, unavailable, while it may recover, and sends ROUTE_HOLD wherever it sent the route: - -- while the neighbour it learned the route from holds it, on the Path this node's route extended, or has yet to say what became of it after a DEAD; -- while a neighbour offers a route that only the doubt keeps this node from using; or -- until each neighbour that learned the route from this node, whose route back names this node just before itself, has answered: with another route, a ROUTE_HOLD, or a ROUTE_END. - -A neighbour that holds under this node answers with a ROUTE_HOLD rather than waiting on it, so holds never wait on each other in a cycle. -A node holds a route for at most 10 seconds: a neighbour that has not answered by then counts as answering with nothing. -A hold protects a claim's presence, not loop freedom, so ending it early is safe. -A held route's claims stay shown but unavailable until a ROUTE_UPDATE makes it usable again. -Otherwise the node lets go, sending ROUTE_END wherever it sent the route, and its claims go offline. -Neither proves that the origin withdrew its claims. +### Closed Sessions and Drains {#closed-sessions} +A node that loses a session to a routing neighbour names the hop it lost: its own Node ID and that session's Session Number, with the Node ID of the node at the far end. +It sends one [DEAD](#dead) for it to each neighbour it sent a route whose Path holds the hop, and each neighbour passes it on in the same way, once per neighbour. +A DEAD ends every route its sender sent through the hop, which keeps its Route ID until the sender sends a ROUTE for it again or a ROUTE_END. + +For each pair of relays a node remembers the highest session it knows closed, ordering sessions by their node's Start and then their Session Number, and never uses a route whose Path names a session of that pair at or below it. +A route through a closed session that arrives late is therefore unusable, and a relay that restarts takes a higher Start, so its new sessions are not. +A node whose Start repeats or goes back has its new sessions refused. + +A node that sends a GOAWAY is draining. +A node that receives one sends a [DRAIN](#drain) naming the draining node to each neighbour it sent a route through that node, and each neighbour passes it on in the same way, once per neighbour. +Every route through a draining node ranks as draining, and stays usable. + +A receiver MUST close the session with a PROTOCOL_VIOLATION on a DEAD or DRAIN naming a hop or node on no live route that peer sent it, or a DEAD whose far node is not the one before the hop on those routes. + A node closes the session when its Announce Stream has made no progress for 10 seconds with messages left to send, so a peer that stops reading never holds a route. -It MAY also close it when the stream falls behind repeated failures of the routes it carries, such as when DEADs and ANNOUNCE_OKs it has yet to send outnumber the hops on those routes, so a peer that reads too slowly never holds every failure. +It MAY close one whose peer reads more slowly than what it is sent changes, once the messages left to send pass a bound of the node's choosing. ### Resolution {#resolution} -A SUBSCRIBE, FETCH, or TRACK request naming no origin node names a path, and the receiver resolves it against the claims covering that path whose route it selected and is usable. +A SUBSCRIBE, FETCH, or TRACK request naming no routing node names a path, and the receiver resolves it against the claims covering that path. Only the most specific covering claims are consulted: those with the longest prefix, which for a claim shown below its own prefix is the path it is shown at less its Above (see [ANNOUNCE_START](#announce-start)). A claim strictly inside another's paths always ranks above it, and a broadcast's exact path is the most specific claim there is, so a concrete announcement shadows every broader claim covering it at any cost; claims over the same prefix shown at the same path form one tier, and among those shown at different paths the deepest wins (see [Above](#announce-start)). The winning tier is the whole answer: a refusal from it never falls through to a less specific claim, so a service refusing a path does not leak the request to a catch-all, and one unserved path costs one round trip rather than a walk down the candidates. Nor is a refusal retried at another claim of the same prefix. -Within the tier, a claim is ineligible while another claim of the same prefix carries its Instance at a higher Epoch, however cheap it is. -Among the eligible claims, the receiver SHOULD prefer a route that is not draining, then the route with the highest priority, then the lowest cost, the claim's Announce Cost plus its route's metric, then the lowest Rendezvous Hash, and then the most recently received, so a reconnecting publisher is not outranked by the stale session it replaced. -The Rendezvous Hash is the 64-bit FNV-1a hash, with offset basis `0x420C0DECB00B` and the standard FNV-64 prime, of the requested path's UTF-8 bytes followed by the origin's Node ID as 8 little-endian bytes. -Every node that knows the same claims ranks them the same, so equal-cost origins of one prefix share its paths and every relay sends one path to the same origin. +Within the tier, a claim is ineligible while another claim of the same prefix carries its Instance at a higher Epoch, however cheap it is and whether or not a route reaches it, so a request fails with UNROUTABLE while the newest Epoch is unavailable. +Among the eligible claims, the receiver SHOULD prefer one that is not draining, then the highest priority, then the lowest cost, the claim's cost plus the cost of the route to the node announcing it, then the lowest Rendezvous Hash, and then the most recently received, so a reconnecting publisher is not outranked by the stale session it replaced. +The Rendezvous Hash is the 64-bit FNV-1a hash, with the standard offset basis `0xCBF29CE484222325` and prime, of the requested path's UTF-8 bytes followed by the claim's Instance. +Every node that knows the same claims ranks them the same, so equal-cost Instances of one prefix share its paths and every relay sends one path to the same Instance. When choosing which claim to advertise for a prefix, the requested path is the prefix itself. A claim resolved this way serves the request like any other, and the claim is not consumed by it. @@ -993,7 +929,7 @@ moq-lite-07 uses the leading-ones encoding of [moqt]: the number of leading 1 bi Most messages are prefixed with a variable-length integer indicating the number of bytes in the message payload that follows. This length field does not include the length of the varint length itself. -A message on the Setup Stream, an Announce Stream, or any bidirectional stream that fails to decode, such as one whose fields disagree with its Message Length or carry a value this specification forbids, MUST close the session with a PROTOCOL_VIOLATION, except content a route message forwards, which the receiver refuses (see [Refused Content](#refused-content)). +A message on the Setup Stream, an Announce Stream, or any bidirectional stream that fails to decode, such as one whose fields disagree with its Message Length or carry a value this specification forbids, MUST close the session with a PROTOCOL_VIOLATION. Resetting only the stream would let the peer repeat the violation on the next one. A stream that ends or is reset before its message completes only terminates that stream, except on the Setup, Announce, and Auth Streams. A GROUP or FRAME that fails to decode resets only its Group or Fetch Stream, and a STREAM_TYPE the negotiated version does not define resets only its stream (see [STREAM_TYPE](#stream_type)). @@ -1062,16 +998,12 @@ The following Setup Parameters are defined: |------|----------------|-------------| | 0x4 | Cost | Cost (i) | |------|----------------|-------------| -| 0x5 | Node ID | Node ID (i) | +| 0x5 | Node ID | Node ID (..)| |------|----------------|-------------| | 0x6 | Implementation | Tokens (s) | |------|----------------|-------------| | 0x7 | Token | Token (b) | |------|----------------|-------------| -| 0x8 | Route Key | Proof (..) | -|------|----------------|-------------| -| 0x9 | Lite-06 Chain | (empty) | -|------|----------------|-------------| ### Probe Parameter {#probe-parameter} The Probe Parameter advertises the sender's capability level when acting as a publisher on a [Probe Stream](#probe). @@ -1112,23 +1044,37 @@ The role is a hint that only ever narrows the session: a server MUST still enfor Only the client sends it; a client that receives one MUST close the session with a PROTOCOL_VIOLATION. A relay MUST NOT forward it. ### Cost Parameter {#cost-parameter} -The Cost Parameter declares what reaching this endpoint costs: a receiver adds the value the sender declared to the Metric of every route that sender sends (see [Routing](#routing)). +The Cost Parameter declares what reaching this endpoint costs: a receiver adds the value the sender declared to the cost of every route and claim that sender sends (see [Routing](#routing)). -The Parameter Value is a variable-length integer in deployment-chosen units, the same units as the Metric and the Announce Cost. -An absent parameter means the default cost of 1, under which a route's metric is its hop count. -A value of 0 is a PROTOCOL_VIOLATION: a free link would leave a route as cheap as the one it came from, and selection converges only because extending a route raises its metric (see [Routing](#routing)). +The Parameter Value is a variable-length integer in deployment-chosen units, the same units as a route's and a claim's cost. +An absent parameter means the default cost of 1, under which a route's cost is its hop count. +A value of 0 is a PROTOCOL_VIOLATION: a free link would leave a route as cheap as the one it came from, and selection converges only because extending a route raises its cost (see [Routing](#routing)). Both endpoints send it and the two values need not match: the parameter prices the sender's own egress. A relay MUST NOT forward it. A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value of at least 1 instead, so a peer cannot reprice its neighbours by declaring itself cheap. ### Node ID Parameter {#node-id-parameter} -The Node ID Parameter declares the Node ID the sender originates its own routes under (see [Routing](#routing)). -Its value MUST NOT be 0 or have the most significant bit set; a receiver MUST close the session with a PROTOCOL_VIOLATION if it does. +The Node ID Parameter declares that the sender is a routing node, and the Node ID it names itself with (see [Routing](#routing)). + +~~~ +Node ID { + Relay (i), + Start (i), +} +~~~ + +**Relay**: +The relay's identifier, the same across its restarts. +A receiver MUST close the session with a PROTOCOL_VIOLATION if it is 0. + +**Start**: +Which start of the relay's process this is, higher than every earlier one. -A receiver that receives its own Node ID has reached itself, such as a relay dialing an address of its own, and SHOULD close the session. +A Node ID appears in this form wherever a message carries one. +A receiver that receives its own Relay has reached itself, such as a relay dialing an address of its own, and SHOULD close the session. A Node ID in SETUP is declared, not proven, and a receiver MUST NOT authorize on it. -Either endpoint MAY send it, and an endpoint that originates no routes omits it, having no Node ID to declare. A relay MUST NOT forward it. +An endpoint that forwards nothing, such as a client, MUST NOT send it. A relay MUST NOT forward it. ### Implementation Parameter {#implementation-parameter} The Implementation Parameter names the sender's software, so a peer can attribute a session to its build. @@ -1147,44 +1093,12 @@ The URI is fixed before the version is negotiated, so a client that may negotiat Only the client sends it; a client that receives one MUST close the session with a PROTOCOL_VIOLATION. A relay MUST NOT forward it. -### Route Key Parameter {#route-key-parameter} -The Route Key Parameter proves that the sender holds an Ed25519 [RFC8032] key, bound to this session, so a receiver recognizes the sender, and endpoints sharing its key, across sessions. - -~~~ -Route Key Proof { - Public Key (256), - Signature (512), -} -~~~ - -**Public Key**: -The sender's Ed25519 public key. - -**Signature**: -The key's Ed25519 signature over the ASCII bytes `moq-lite route key`, then one byte naming the sender's side of the session (0 for the client, 1 for the server), then 32 bytes of keying material exported from the session with the label `EXPORTER-moq-lite-route-key` and an empty context. - -Binding 1 exports with the TLS exporter (Section 7.5 of [RFC8446]), and binding 2 with the WebTransport session's exporter [webtrans-h3] (see [Transports](#transports)). -The exporter MUST yield material that only the session's two endpoints know and no other session shares. -TLS 1.3's exporter provides this, after resumption too; its early exporter does not, since a replayed 0-RTT ClientHello reproduces it on another connection, nor does TLS 1.2 without the extended master secret [RFC7627], which lets an attacker give two of its sessions one secret. -An endpoint MUST NOT send the parameter on a session that provides no such exporter. -The exported material and the sender's side keep a proof from being replayed on another session, relayed by an attacker or an intermediary that terminates TLS, or reflected back to its sender. - -Either endpoint MAY send it. A receiver MUST close the session with a PROTOCOL_VIOLATION if the value is not 96 bytes. -A receiver that relies on the key MUST verify the signature first, closing the session with a PROTOCOL_VIOLATION if it does not verify; without an exporter on the session, it cannot rely on the key. -A relay MUST NOT forward it. - - -### Lite-06 Chain Parameter {#lite06-chain-parameter} -The Lite-06 Chain Parameter says the sender reads the Lite-06 Chain on ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART (see [ANNOUNCE_START](#announce-start)). -It is a temporary extension for relays that also peer over moq-lite-06, and the next version removes it. -The Parameter Value MUST be empty; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise. - ## ANNOUNCE_REQUEST {#announce-request} -A subscriber sends an ANNOUNCE_REQUEST message on its Announce Stream to edit the set of prefixes it wants claims for, and the routes they travel under: every broadcast with a path that starts with a prefix of the set. +A subscriber sends an ANNOUNCE_REQUEST message on its Announce Stream to edit the set of prefixes it wants claims for: every broadcast with a path that starts with a prefix of the set. ~~~ ANNOUNCE_REQUEST Message { - Type (i) = 0x10 + Type (i) = 0x5 Message Length (i) More (8), Remove Count (i), @@ -1200,7 +1114,7 @@ Add { ~~~ **Type**: -Set to 0x10 to indicate an ANNOUNCE_REQUEST message. +Set to 0x5 to indicate an ANNOUNCE_REQUEST message. **More**: 1 when the next message on the stream is an ANNOUNCE_REQUEST continuing this edit, 0 on an edit's last. @@ -1224,7 +1138,7 @@ Indicate interest for any broadcasts with a path that starts with this prefix. Any other value is a PROTOCOL_VIOLATION. One edit MAY swap prefixes for one above or below them, or re-add a prefix it removes to change its `Hidden`. -The publisher MUST respond to the edit's last ANNOUNCE_REQUEST with an ANNOUNCE_OK on its own Announce Stream, followed by the routes and claims the added prefixes newly match and any future changes, subject to [Routing](#routing). +The publisher MUST respond to the edit's last ANNOUNCE_REQUEST with an ANNOUNCE_OK on its own Announce Stream, followed by the claims the added prefixes match and any future changes. Implementations SHOULD consider reasonable limits on the number of matching claims and routes to prevent resource exhaustion. @@ -1233,15 +1147,13 @@ A publisher sends one ANNOUNCE_OK message on its Announce Stream for each edit i ~~~ ANNOUNCE_OK Message { - Type (i) = 0x11 + Type (i) = 0x6 Message Length (i) = 0 } ~~~ **Type**: -Set to 0x11 to indicate an ANNOUNCE_OK message. - -ANNOUNCE_OK has no body and reserves no fields for a route-key proof. +Set to 0x6 to indicate an ANNOUNCE_OK message. ## SYNCED {#synced} The initial set on a discovery stream has been delivered. @@ -1263,131 +1175,51 @@ A second SYNCED for the same prefix, or on the same Tracks Stream, is a PROTOCOL A Tracks Stream FIN before SYNCED means the Broadcast ended (see [Tracks](#tracks-stream)). -## ROUTE_START {#route-start} -A publisher sends a ROUTE_START message when it reaches an origin node for a prefix (see [Routing](#routing)). -Each ROUTE_START implicitly assigns the next Route ID on the stream, later referenced by ROUTE_UPDATE, ROUTE_HOLD, ROUTE_END, DEAD, ANNOUNCE_FLOOR, and ANNOUNCE_START (see [Announce](#announce)). +## ROUTE {#route} +A publisher sends a ROUTE message when it selects a route to a routing node, or the route it sent changes (see [Routing](#routing)). +The route leads to the node its first Hop names. +A ROUTE to a node the stream has no live route to implicitly assigns the next Route ID on the stream, later referenced by ROUTE_END and ANNOUNCE_FLOOR (see [Announce](#announce)); any other replaces that route, keeping its Route ID and its claims. ~~~ -ROUTE_START Message { - Type (i) = 0x6 +ROUTE Message { + Type (i) = 0x7 Message Length (i) - Node ID (i), - Prefix ID (i), - Route Suffix (s), - Exact (8), - Route Offer (..), -} -~~~ - -**Type**: -Set to 0x6 to indicate a ROUTE_START message. - -**Node ID**: -The origin node, as the publisher names it on this session. -0 is refused (see [Refused Content](#refused-content)). - -**Prefix ID**: -The requested prefix the route lies in: the Prefix ID an Add of the peer's ANNOUNCE_REQUEST assigned. - -**Route Suffix**: -The route's prefix, relative to that requested prefix: the route covers the requested prefix joined with it, and is empty for a route at the requested prefix itself. -A suffix that is not a valid path, or that joins the requested prefix past the limits of a broadcast path, is refused. - -**Exact**: -1 when the publisher keeps the route at its own prefix whatever prefix the request lies at, such as a route a relay presents at a mount point, so an edit that widens the request past it leaves it there (see [Edits](#edits)); 0 when the publisher may present it elsewhere, such as a route covering the requested prefix from a broader prefix of its own, which a widening moves up. -A route strictly below its requested prefix stays through an edit that covers it either way; `Exact` also keeps it at its own prefix through a widening once an edit has made that prefix a requested prefix. -A publisher MAY send 0 for a route it keeps at its own prefix: a widening then moves it up, and the publisher sends whatever the carried routes lack, such as the route again under its own prefix. -Any value other than 0 or 1 is a PROTOCOL_VIOLATION. - -**Route Offer**: -The route, as below. - -### Route Offer {#route-offer} -What a route says: its Path, then its attributes. -ROUTE_START and ROUTE_UPDATE carry it. - -~~~ -Route Offer { Hop Count (i), Hop (..) ..., Flags (8), Priority (8), - Metric (i), + Cost (i), } Hop { - Hop ID (i), + Node ID (..), Session Number (i), } ~~~ +**Type**: +Set to 0x7 to indicate a ROUTE message. + **Hop Count**: -The number of Hops that follow. -0 is a PROTOCOL_VIOLATION, since the publisher names itself last; more than 32 is refused. +The number of Hops that follow, from 1 to 32. **Hop**: -The route's Path (see [Routing](#routing)), in order, the origin node's first and the publisher's own last: each node's Hop ID and the Session Number it learned the route on, 0 for the origin's own. -A Hop ID of 0 is refused. -The Path comes first, so a receiver that refuses the rest of the offer still learns the hops a later [DEAD](#dead) may name. +The route's Path (see [Routing](#routing)), in order, the first being the node the route leads to and the last the publisher's own: each node's [Node ID](#node-id-parameter) and the Session Number it learned the route on, 0 for the first. **Flags**: -A bit field: 0x1 when the route is down-only and 0x2 when the route is draining (see [Routing](#routing)). -Any other bit set is refused, rather than ignored: a later version may give a bit a meaning that changes the route, or a field ahead of the ones defined here. +A bit field: 0x1 when the route is marked and 0x2 when the route is draining (see [Routing](#routing)). **Priority**: The route's priority, the lowest local priority of a session on its Path, as a u8 with 128 as the midpoint; higher ranks first. -**Metric**: -The publisher's metric to the origin node, 0 when it is the origin. - - - -## ROUTE_UPDATE {#route-update} -A publisher sends a ROUTE_UPDATE message when a route it sent changes, referencing its Route ID. - -~~~ -ROUTE_UPDATE Message { - Type (i) = 0x7 - Message Length (i) - Route ID (i), - Route Offer (..), -} -~~~ - -**Type**: -Set to 0x7 to indicate a ROUTE_UPDATE message. - -**Route ID**: -The ordinal implicitly assigned by a prior ROUTE_START on this stream. - -**Route Offer**: -As defined for [ROUTE_START](#route-start), replacing the route's. -A ROUTE_UPDATE for a held route makes it usable again. - - -## ROUTE_HOLD {#route-hold} -A publisher sends a ROUTE_HOLD message when it has no usable route to the origin node but still holds the route and its claims while it recovers (see [Holds](#holds)), referencing its Route ID. -The receiver keeps the route's last Route Offer, and does not use the route until a ROUTE_UPDATE. - -~~~ -ROUTE_HOLD Message { - Type (i) = 0xB - Message Length (i) - Route ID (i) -} -~~~ - -**Type**: -Set to 0xB to indicate a ROUTE_HOLD message. - -**Route ID**: -The ordinal implicitly assigned by a prior ROUTE_START on this stream. +**Cost**: +The publisher's cost to the node the route leads to, 0 when it is that node. ## ROUTE_END {#route-end} A publisher sends a ROUTE_END message when it lets go of a route, referencing its Route ID. It retires the Route ID and every claim under the route, whose ANNOUNCE_END the publisher does not send. -It claims nothing about the origin's claims, which may still be served elsewhere. +It claims nothing about those claims, which may still be served elsewhere. ~~~ ROUTE_END Message { @@ -1401,67 +1233,54 @@ ROUTE_END Message { Set to 0x8 to indicate a ROUTE_END message. **Route ID**: -The ordinal implicitly assigned by a prior ROUTE_START on this stream. +The ordinal implicitly assigned by a prior ROUTE on this stream. ## DEAD {#dead} -A publisher sends a DEAD message when a session on the Path of routes it sent closed, or a node on it sent a GOAWAY (see [Dead Hops](#dead-hops)). -It covers every origin node, and assigns no id. +A publisher sends a DEAD message when a session on the Path of routes it sent closed (see [Closed Sessions and Drains](#closed-sessions)). +It covers every route on the stream through that session, and assigns no id. ~~~ DEAD Message { - Type (i) = 0xF + Type (i) = 0x9 Message Length (i) - Kind (i), - [Closed (..),] - [Drain (..),] -} - -Closed { Hop (..), - Far Hop ID (i), - Gone (8), - Moved Count (i), -} - -Drain { - Hop ID (i), + Far Node ID (..), } ~~~ **Type**: -Set to 0xF to indicate a DEAD message. - -**Kind**: -0 when a session closed, followed by Closed, and 1 when a node sent a GOAWAY, followed by Drain. -Any other value is a PROTOCOL_VIOLATION. +Set to 0x9 to indicate a DEAD message. **Hop**: -The hop that died: the Hop ID of the node that lost the session, and that session's Session Number, as a [Route Offer](#route-offer)'s Path names it. -A Hop ID of 0 is a PROTOCOL_VIOLATION. +The hop that died: the Node ID of the node that lost the session, and that session's Session Number, as a [ROUTE](#route)'s Path names it. -**Far Hop ID**: -The Hop ID of the node at the session's other end, which the receiver doubts. -0 is a PROTOCOL_VIOLATION. +**Far Node ID**: +The Node ID of the node at the session's other end. -**Gone**: -1 when every route on the stream through the hop that did not move has ended, 0 when the rest are held (see [Dead Hops](#dead-hops)). -Any other value is a PROTOCOL_VIOLATION. -**Moved Count**: -The number of routes on the stream through the hop that moved to another Path. -The next Moved Count messages on the stream are [ROUTE_UPDATE](#route-update)s, one for each with its new Route Offer, and the receiver applies the DEAD and all of them as one. -A refused one leaves the receiver no route, as any refused ROUTE_UPDATE does. -Any other message before the last of them, one naming a route that is not live or whose Path does not hold the hop, a second one for the same route, and a count above the stream's routes through the hop are each a PROTOCOL_VIOLATION. +## DRAIN {#drain} +A publisher sends a DRAIN message when a node on the Path of routes it sent sent a GOAWAY (see [Closed Sessions and Drains](#closed-sessions)). +It covers every route on the stream through that node, and assigns no id. + +~~~ +DRAIN Message { + Type (i) = 0xA + Message Length (i) + Node ID (..), +} +~~~ + +**Type**: +Set to 0xA to indicate a DRAIN message. -**Hop ID** (Drain): -The Hop ID of the node that sent the GOAWAY. -0 is a PROTOCOL_VIOLATION. +**Node ID**: +The Node ID of the node that sent the GOAWAY. ## ANNOUNCE_START {#announce-start} -A publisher sends an ANNOUNCE_START message to advertise a claim of a route's origin node: that paths under a prefix can be served. -Each ANNOUNCE_START implicitly assigns the next Announce ID on the stream, later referenced by ANNOUNCE_END, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART (see [Announce](#announce)). +A publisher sends an ANNOUNCE_START message to advertise a claim: that paths under a prefix can be served. +Each ANNOUNCE_START implicitly assigns the next Announce ID on the stream, later referenced by ANNOUNCE_END and ANNOUNCE_UPDATE (see [Announce](#announce)). The claim's prefix is encoded relative to the session. @@ -1472,13 +1291,19 @@ ANNOUNCE_START Message { Path Base (i), Path Keep (i), Claim Prefix Suffix (s), - Route ID (i), Instance (b), Minted (8), Epoch (i), - Announce Cost (i), + Claim (..), +} + +Claim { + Cost (i), Above (i), - [Lite-06 Chain (..)], + Flags (8), + Priority (8), + Chain Count (i), + Relay (i) ..., } ~~~ @@ -1490,16 +1315,12 @@ The claim's prefix begins with the first `Path Keep` segments of the prefix clai **Claim Prefix Suffix**: The remaining segments of the claim's prefix. -A claim covering more than the requested prefix its route lies in presents at that requested prefix (see [Announce](#announce)). - -**Route ID**: -The route the claim travels under: its origin node is the claim's. -A claim never changes its Route ID. +A claim covering more than the requested prefix it lies in presents at that requested prefix (see [Announce](#announce)). **Instance**: The stream the claim serves (see [Broadcast](#broadcast)): non-empty UTF-8 text. -An empty or non-UTF-8 Instance is refused (see [Refused Content](#refused-content)). -A relay forwards the Instance unchanged. +An empty or non-UTF-8 Instance is a PROTOCOL_VIOLATION. +A relay forwards the Instance unchanged, and a claim never changes it. **Minted**: 1 when a receiver minted the Instance for a version that carries none (see [Routing](#routing)), 0 when the publisher named it. @@ -1511,11 +1332,11 @@ An Instance minted and one named with the same text are different Instances. Which incarnation of the Instance the claim serves: a counter the publisher raises within one Instance, 0 unless it keeps an Instance across restarts. A relay forwards the Epoch unchanged. -Only an ANNOUNCE_RESTART changes the Instance or the Epoch; ANNOUNCE_UPDATE never does. - -**Announce Cost**: -The origin's price for this prefix, in the units of the [Cost Parameter](#cost-parameter): 0 for content it already produces, larger for a standby that starts work on demand. -A relay forwards it unchanged; the cost of a path through the claim is the Announce Cost plus the route's metric. +**Cost**: +The sender's cost to the claim, in the units of the [Cost Parameter](#cost-parameter). +Its publisher prices it: 0 for content it already produces, larger for a standby that starts work on demand. +A routing node sends a routing neighbour the cost it learned the claim at, and any other peer that cost plus the cost of its route to the node announcing the claim (see [Claims](#claims)). +A cost saturates at 2^62-1. **Above**: How many segments the claim's own prefix is broader than the path it is shown at (see [Announce](#announce)): 0 for a claim exactly there. @@ -1525,15 +1346,19 @@ A receiver treats a claim as covering its path less its Above, and ranks the cla The claims of one tier are those of the winning prefix shown at the winning depth; claims of the same prefix shown at a shallower depth are not consulted. A relay forwards a claim's Above unchanged, adding the distance when it shows the claim at a narrower prefix than the one it learned it at. -**Lite-06 Chain**: -The moq-lite-06 Hop ID list a claim arrived with where its origin node learned it over moq-lite-06, encoded as that list: a count, then each Hop ID. -A publisher sends it, as the message's last field, only to a peer that sent the [Lite-06 Chain Parameter](#lite06-chain-parameter), and only when the claim has one; a received chain that is empty, or names a Hop ID twice, is refused. -A relay forwards it unchanged, and translating the claim for a moq-lite-06 peer sends it followed by a Hop ID standing for the claim's origin node. -A node MUST NOT serve a claim whose chain names itself, by its own Hop ID or one standing for its Node ID, or whose translated chain would exceed its hop limit. +**Flags**: +A bit field: 0x1 (`Unavailable`) when no route reaches the claim from the sender (see [Claims](#claims)), and 0x2 when a node on the way to the claim is draining. + +**Priority**: +The lowest local priority of a session on the way to the claim's publisher, as a u8 with 128 as the midpoint; a publisher's own claim carries 255. + +**Chain Count** and **Relay**: +The claim's chain: the Relay (see [Node ID Parameter](#node-id-parameter)) of each routing node that announced the claim again across a scoped grant or from an earlier version (see [Claims](#claims)), oldest first, and none for a claim nothing announced again. +More than 31, or a Relay of 0, is a PROTOCOL_VIOLATION: a chain that would reach 32 is never taken (see [Claims](#claims)), so none is sent. ## ANNOUNCE_END {#announce-end} -A publisher sends an ANNOUNCE_END message when the origin withdrew a claim, referencing its Announce ID. +A publisher sends an ANNOUNCE_END message when a claim is gone, referencing its Announce ID. The id is retired and MUST NOT be referenced again. Retraction claims nothing about the content: a broadcast whose publisher stops advertising may remain readable by exact path, serving its stored groups over FETCH. Retraction does not disturb subscriptions already in flight, which conclude normally with SUBSCRIBE_FINISH. @@ -1543,7 +1368,8 @@ How a subscriber learns the path of stored content is out of band, e.g. an appli ANNOUNCE_END Message { Type (i) = 0x1 Message Length (i) - Announce ID (i) + Announce ID (i), + Lost (8), } ~~~ @@ -1554,68 +1380,43 @@ Set to 0x1 to indicate an ANNOUNCE_END message. The ordinal implicitly assigned by a prior ANNOUNCE_START on this stream. A claim that is announced again after an ANNOUNCE_END gets a fresh id from its next ANNOUNCE_START. +**Lost**: +0 when the claim's publisher withdrew it, and 1 when the sender only lost its way to the claim, or its grant to announce it, so the claim may still be served elsewhere. +Any other value is a PROTOCOL_VIOLATION. +A relay forwards which of the two it was. + ## ANNOUNCE_UPDATE {#announce-update} -A publisher sends an ANNOUNCE_UPDATE message when the origin re-prices a claim, referencing its Announce ID. -The claim's prefix and route are unchanged and the id stays live. -An update carries no content claim: in-flight subscriptions under the claim are undisturbed. +A publisher sends an ANNOUNCE_UPDATE message when a claim changes, referencing its Announce ID. +The claim's prefix and Instance are unchanged and the id stays live. +In-flight subscriptions under the claim are undisturbed, and continue onto a higher Epoch. ~~~ ANNOUNCE_UPDATE Message { Type (i) = 0x2 Message Length (i) Announce ID (i), - Announce Cost (i), - Above (i), - [Lite-06 Chain (..)], -} -~~~ - -**Type**: -Set to 0x2 to indicate an ANNOUNCE_UPDATE message. - -**Announce ID**: -As defined for [ANNOUNCE_END](#announce-end). - -**Announce Cost**, **Above**, and **Lite-06 Chain**: -As defined for [ANNOUNCE_START](#announce-start), replacing the claim's; an absent chain replaces it with none. - - -## ANNOUNCE_RESTART {#announce-restart} -A publisher sends an ANNOUNCE_RESTART message when a claim now serves another Instance, or a higher Epoch of the same one (see [Routing](#routing)), referencing its Announce ID. -The claim's prefix and route are unchanged and the id stays live. -Under another Instance, whatever the subscriber resolved under the prefix through the claim is the old stream: in-flight subscriptions on it are undisturbed, and a new request resolves afresh. -Under a higher Epoch of the same Instance the stream continues, and so do its subscriptions. - -~~~ -ANNOUNCE_RESTART Message { - Type (i) = 0x3 - Message Length (i) - Announce ID (i), - Instance (b), - Minted (8), Epoch (i), - Announce Cost (i), - Above (i), - [Lite-06 Chain (..)], + Claim (..), } ~~~ **Type**: -Set to 0x3 to indicate an ANNOUNCE_RESTART message. +Set to 0x2 to indicate an ANNOUNCE_UPDATE message. **Announce ID**: As defined for [ANNOUNCE_END](#announce-end). -**Instance**, **Minted**, **Epoch**, **Announce Cost**, **Above**, and **Lite-06 Chain**: +**Epoch** and **Claim**: As defined for [ANNOUNCE_START](#announce-start), replacing the claim's. + ## ANNOUNCE_FLOOR {#announce-floor} A publisher sends an ANNOUNCE_FLOOR message to close a batch of a route's claims (see [Floors](#floors)). ~~~ ANNOUNCE_FLOOR Message { - Type (i) = 0x9 + Type (i) = 0x3 Message Length (i) Route ID (i), Revision (i), @@ -1623,13 +1424,13 @@ ANNOUNCE_FLOOR Message { ~~~ **Type**: -Set to 0x9 to indicate an ANNOUNCE_FLOOR message. +Set to 0x3 to indicate an ANNOUNCE_FLOOR message. **Route ID**: -The ordinal implicitly assigned by a prior ROUTE_START on this stream. +The route the batch's claims travel under: the ordinal implicitly assigned by a prior ROUTE on this stream. **Revision**: -The origin's Revision at which the floor certifies the stream's claims for the route, plus one, or 0 when it certifies nothing. +The Revision of the node the route leads to as of which the publisher's copy of its claims is complete. ## SUBSCRIBE @@ -1642,8 +1443,7 @@ SUBSCRIBE Message { Broadcast Path (s) Instance (b) Minted (8) - Node ID (i) - Route Depth (i) + Node (..) Track Name (s) Subscriber Priority (8) Group Order (8) @@ -1670,7 +1470,7 @@ Anchor { A unique identifier chosen by the subscriber. A Subscribe ID MUST NOT be reused within the same session, even if the prior subscription has been closed. -**Instance**, **Minted**, **Node ID**, and **Route Depth**: +**Instance**, **Minted**, and **Node**: As in [TRACK](#track). **Subscriber Priority**: @@ -1783,8 +1583,7 @@ TRACK Message { Broadcast Path (s) Instance (b) Minted (8) - Node ID (i) - Route Depth (i) + Node (..) Track Name (s) } ~~~ @@ -1797,14 +1596,17 @@ The stream the subscriber expects, encoded as in [ANNOUNCE_START](#announce-star A publisher MUST refuse a request with UNROUTABLE when no claim of that Instance serves the path, so a request is never answered by a different stream than the one it named. A relay fills in the Instance and Minted of the claim it resolved when forwarding a request upstream; TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS carry them the same way. -**Node ID**: -The origin node that serves the request, as the publisher names it on this session, or 0 for whichever the publisher selects (see [Routing](#routing)). +**Node**: +The routing node that announces the claim serving the request (see [Routing](#routing)): its Relay, followed by its Start unless the Relay is 0, which names none and leaves the publisher to select one. +An endpoint that is no routing node names none, and serves a request itself whichever node it names. TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS carry it the same way. -**Route Depth**: -How many leading segments of the Broadcast Path make up the prefix of the route to the origin node the request follows (see [Routing](#routing)), 0 for a route at the empty prefix. -It MUST be 0 when the Node ID is 0, and at most the Broadcast Path's segments; any other value is a PROTOCOL_VIOLATION. -TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS carry it the same way. +~~~ +Node { + Relay (i), + [Start (i)], +} +~~~ **Track Name**: The name of the track. @@ -1872,15 +1674,14 @@ TRACKS Message { Broadcast Path (s) Instance (b) Minted (8) - Node ID (i) - Route Depth (i) + Node (..) } ~~~ **Broadcast Path**: The path of the Broadcast to list. -**Instance**, **Minted**, **Node ID**, and **Route Depth**: +**Instance**, **Minted**, and **Node**: As in [TRACK](#track). The listing is pinned to the stream that answers it and ends with that stream. @@ -1949,8 +1750,7 @@ DATAGRAMS Message { Broadcast Path (s) Instance (b) Minted (8) - Node ID (i) - Route Depth (i) + Node (..) Track Name (s) Subscriber Priority (8) } @@ -2150,8 +1950,7 @@ FETCH Message { Broadcast Path (s) Instance (b) Minted (8) - Node ID (i) - Route Depth (i) + Node (..) Track Name (s) Subscriber Priority (8) Subscriber Max Age (i) @@ -2164,7 +1963,7 @@ FETCH Message { **Broadcast Path**: The broadcast path of the track to fetch from. -**Instance**, **Minted**, **Node ID**, and **Route Depth**: +**Instance**, **Minted**, and **Node**: As in [TRACK](#track). **Track Name**: @@ -2245,7 +2044,7 @@ An endpoint MUST close the session with a protocol violation if it receives more A peer that reconnects to a provided URI SHOULD keep using that URI for subsequent reconnects rather than reverting to the original, until a connection attempt to it fails; it then SHOULD revert to the original, which may still answer. -Routes that arrived on a session that received a GOAWAY stay usable until the session ends, ranked below every other (see [Routing](#routing)). +Routes through a node that sent a GOAWAY stay usable until its sessions end, ranked below every other (see [Closed Sessions and Drains](#closed-sessions)). ## AUTH {#auth-message} AUTH is the first message on an Auth Stream, presenting a token. @@ -2431,7 +2230,6 @@ A stream that FINs without a GROUP_END carries a closed Group, which may have he - A session without a negotiated subprotocol negotiates the version in a draft-14 CLIENT_SETUP and SERVER_SETUP exchange. - Added the SETUP `Implementation` parameter (0x6): the sender's software as `name/version` product tokens. - Added the client-only Token Setup Parameter (0x7), carrying the connection credential in SETUP instead of only the request URI. -- Added the Route Key Setup Parameter (0x8): an Ed25519 public key and its signature over keying material exported from the session. - A Report-level publisher reads and ignores PROBE targets instead of resetting the Probe Stream. - A GOAWAY recipient MAY keep opening requests on the current session until it has moved to a replacement session; previously it MUST NOT open new streams. The sender SHOULD keep answering them and MAY reset one with GOING_AWAY, which the recipient SHOULD retry on another route. @@ -2460,29 +2258,29 @@ A stream that FINs without a GROUP_END carries a closed Group, which may have he - A `\` in a path escapes only `\` or `/`; any other `\` is a PROTOCOL_VIOLATION rather than a second spelling of the same namespace field. An escaped `/` never splits a segment, so one namespace field is one segment wherever segments are counted or matched. - Hid claims with a `.`-prefixed segment below the requested prefix from announce discovery, and added the ANNOUNCE_REQUEST `Hidden` field to opt in. - Replaced ANNOUNCE_OK Active Count with an ordered SYNCED event (0x4), marking the initial set of the prefix it names without retaining claims that end before delivery. -- Added `Instance` and `Epoch` to ANNOUNCE_START and ANNOUNCE_RESTART, and `Instance` to TRACK, TRACKS, SUBSCRIBE, and FETCH. The Instance is non-empty UTF-8 text naming one continuous stream, and a path and an Instance name one Broadcast; the Epoch is a counter within one Instance. A relay MAY move a subscription between claims with the same Instance, continuing from the first frame the subscriber lacks instead of at a group boundary, and never between claims with different Instances. Within one Instance only its highest Epoch is eligible. A request's Instance is empty when it pins none. Replaces the first-hop identity. -- Added ANNOUNCE_RESTART (0x3): a live advertisement now serves another Instance, or a higher Epoch of the same one. +- Added `Instance` and `Epoch` to ANNOUNCE_START, and `Instance` to TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS. The Instance is non-empty UTF-8 text naming one continuous stream, and a path and an Instance name one Broadcast; the Epoch is a counter within one Instance, which ANNOUNCE_UPDATE may raise. A relay MAY move a subscription between claims with the same Instance, continuing from the first frame the subscriber lacks instead of at a group boundary, and never between claims with different Instances. Within one Instance only its highest Epoch is eligible. A request's Instance is empty when it pins none. Replaces the first-hop identity. +- Another Instance at a path is another claim, started before the one it replaces ends. - An advertiser MAY announce a path it answers through a claim under the claim's Instance, so subscriptions resolved through the claim continue, and a claim still serving that Instance when the announcement ends restarts under a new one. -- A receiver mints an Instance for each announcement a session of an earlier version delivers, and a `Minted` field beside every Instance (ANNOUNCE_START, ANNOUNCE_RESTART, TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS) says whether a receiver minted it, so no Instance text is reserved for minting. +- A receiver mints an Instance for each announcement a session of an earlier version delivers, and a `Minted` field beside every Instance says whether a receiver minted it, so no Instance text is reserved for minting. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live claim's suffix. -- Replaced the bidirectional Announce Stream (0x1) with one unidirectional Announce Stream (0x3) per endpoint, carrying everything it says about discovery and routing in order, so none of it overtakes the rest. A second Announce Stream, or one that is reset, closes the session. -- ANNOUNCE_REQUEST (0x10) edits a set of prefixes, none at or below another, one edit at a time, and ANNOUNCE_OK (0x11) marks where each edit takes effect. An edit too large for one message continues over several ANNOUNCE_REQUESTs, each but the last with `More` set, and takes effect whole. Both endpoints carry the routes and claims that both sets cover over to the new set, so none is sent again. ROUTE_START and SYNCED name the requested prefix by its Prefix ID, and every claim's path is relative to the session rather than to its requested prefix. A finished Announce Stream means its endpoint is leaving. -- Split routing into two layers on the Announce Stream. ROUTE_START (0x6), ROUTE_UPDATE (0x7), and ROUTE_END (0x8) advertise how the publisher reaches an origin node, named by a Node ID, for the paths under a prefix, with an additive metric and a down-only bit. Every ANNOUNCE_START names its route's Route ID in place of the Hop ID list, so a link change sends one ROUTE_UPDATE per origin and prefix rather than an update per claim. Removed the Hop ID list and ANNOUNCE_OK's Hop ID, and replaced the SETUP Hop parameter (0x5) with a [Node ID parameter](#node-id-parameter), so an endpoint that reaches itself detects it at setup. -- ROUTE_START and ROUTE_UPDATE carry a Route Offer that leads with the route's Path: one hop per node the route crossed, each a Hop ID and the Session Number that node learned the route on, at most 32. A node never uses a route whose Path names it. ROUTE_START also carries a Prefix ID and a Route Suffix naming the prefix the route covers, and `Exact`, marking a route its publisher keeps at its own prefix, which an edit widening the request past it leaves in place. The offer carries the route's drain (Flags 0x2) and priority, which rank before its metric. -- Added ROUTE_HOLD (0xB), which holds a route while it may recover, for at most 10 seconds; ROUTE_END lets it go. Neither withdraws the origin's claims. -- Added DEAD (0xF): a node that loses a session names that hop once to each neighbour it sent a route through it, counting the routes that moved, each a ROUTE_UPDATE right behind it, and every node drops every route through the hop and doubts the node at the far end for a second, keeping nodes off routes through it but not off one it originates, except over a session to it opened since; a DRAIN names a node that sent a GOAWAY, whose routes rank draining. The path, the dead hop, holds, and the doubt keep routes free of stale copies, and of loops except briefly when an origin on three or more relays leaves them all at once, with no distance, sequence number, route request, or echo. On a scoped session a DEAD applies only to the routes heard there. +- Replaced the bidirectional Announce Stream (0x1) with one unidirectional Announce Stream (0x3) per endpoint, carrying everything it says about discovery and routing in order, so none of it overtakes the rest. A second Announce Stream, or one that is reset, closes the session. A finished Announce Stream means its endpoint is leaving. +- ANNOUNCE_REQUEST (0x5) edits a set of prefixes, none at or below another, and ANNOUNCE_OK (0x6) marks where each edit takes effect; a subscriber sends one edit at a time. An edit too large for one message continues over several ANNOUNCE_REQUESTs, each but the last with `More` set, and takes effect whole. Both endpoints drop the claims within a removed prefix at the ANNOUNCE_OK. SYNCED names the requested prefix by its Prefix ID, and every claim's path is relative to the session rather than to its requested prefix. +- Replaced the Hop ID list with a claim's Cost, `Above`, flags, priority, and chain on ANNOUNCE_START and ANNOUNCE_UPDATE. The chain names the relays that announced the claim again across a scoped grant or from an earlier version, and a relay takes no claim whose chain names it. The 0x1 flag marks a claim no route reaches, which its sender keeps for 800 milliseconds before ending it, and the 0x2 flag one behind a draining node. +- ANNOUNCE_END carries `Lost`: whether the claim's publisher withdrew it or the sender only lost its way to it. +- Replaced the SETUP Hop parameter (0x5) with a [Node ID parameter](#node-id-parameter), a Relay and its Start, which only a routing node sends. Two routing nodes exchange routes; every other session carries claims alone, one per path and Instance. Removed ANNOUNCE_OK's Hop ID. +- Added ROUTE (0x7) and ROUTE_END (0x8): a routing node's route to another, a path vector of at most 32 hops, each a Node ID and the Session Number that node learned the route on, with a marked bit, a draining bit, a priority, and an additive cost. A node never uses a route whose Path names its relay, and ranks routes by drain, then priority, then cost. +- Added DEAD (0x9): a node that loses a session names that hop once to each neighbour it sent a route through it, which ends those routes. A node never uses a route through a session at or below the highest it knows closed between the same two relays. +- Added DRAIN (0xA): names a node that sent a GOAWAY once per neighbour, and every route through it ranks draining. +- Added ANNOUNCE_FLOOR (0x3), closing each batch of a route's claims with the Revision of the node the route leads to, so a stale copy never revives a claim whose withdrawal a newer one delivered. - A node closes a session whose peer leaves its Announce Stream undrained for 10 seconds. -- Added ANNOUNCE_FLOOR (0x9), closing each batch of a route's claims with the origin Revision at which the stream's claims across the route's prefix are certified plus one, or 0 to certify nothing, so a stale copy never revives a claim whose withdrawal a newer one delivered. A floor certifies only the claims its own request shows. -- A route presents only its most specific claim covering the requested prefix, moved to the next covering claim when it is withdrawn rather than ended. +- A publisher presents only the most specific claim covering the requested prefix. - A subscriber whose scope confines it to some prefixes SHOULD request those, and edit its set when they change. -- A route goes on a stream only while it has a claim the request presents, and ends after the batch withdrawing its last claim. -- Added `Node ID` and `Route Depth` to TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS: the origin node the first hop selected and the prefix of the route it follows, which every later hop follows. -- Replaced Warm and Cold Route Cost with the origin's Announce Cost, unchanged in transit. ANNOUNCE_UPDATE carries only the Announce Cost. +- Added `Node` to TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS: the routing node announcing the claim the first hop selected, which every later hop follows. +- Replaced Warm and Cold Route Cost with one cost, which each link adds to. - The Cost parameter must be at least 1. -- Added `Above` to ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART: how many segments broader than the requested prefix a presented claim is. A claim presented at the requested prefix from above otherwise looked exactly like a claim at the prefix, so a broadcast nested under another's path could lose to the broader claim covering it, depending on the order a relay listed them in. Receivers take a claim to cover its path less its Above. -- Replaced the shortest-path, Hop ID, Instance Hash, and Chain Hash tie-breaks with the route's drain and priority, the Announce Cost plus the route's metric, and a Rendezvous Hash of the requested path and the origin's Node ID. +- Added `Above` to ANNOUNCE_START and ANNOUNCE_UPDATE: how many segments broader than the requested prefix a presented claim is. A claim presented at the requested prefix from above otherwise looked exactly like a claim at the prefix, so a broadcast nested under another's path could lose to the broader claim covering it, depending on the order a relay listed them in. Receivers take a claim to cover its path less its Above. +- Replaced the shortest-path, Hop ID, Instance Hash, and Chain Hash tie-breaks with the claim's drain and priority, its cost, and a Rendezvous Hash of the requested path and the claim's Instance, a standard FNV-1a. - Removed the standby-ordering deployment requirements on Route Cost seeds and bounds. -- Added the temporary Lite-06 Chain Setup Parameter (0x9) and a trailing Lite-06 Chain on ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART: the moq-lite-06 Hop ID list of a claim learned over moq-lite-06, which a node drops when it names that node. ### Tracks {#changelog-07-tracks} @@ -2537,7 +2335,7 @@ A stream that FINs without a GROUP_END carries a closed Group, which may have he - FRAME leads with `Payload Length`, the payload size plus one, in place of the trailing `Message Length`; 0 is malformed. - A publisher SHOULD drop a datagram rather than block when the transport has no room for it, where it previously sent one only if the congestion controller could transmit it immediately. - Added an optional `Subscriber Max Age` to FETCH, encoded as milliseconds plus one with zero meaning absent. It can tighten, but never relax, `Publisher Max Age`. -- A receiver refuses forwarded route content it cannot use, such as an unknown route flag, more than 32 hops on a route's Path, or an invalid claim path or Instance, withdrawing only that route or claim rather than closing the session ([Refused Content](#refused-content)). A refused claim goes offline, and its route's floors certify nothing while it holds one. +- A receiver drops a claim whose resolved path it cannot hold, such as one past the path limits once joined beneath its own root, rather than closing the session ([Announce](#announce)). ## moq-lite-06 @@ -2713,8 +2511,8 @@ A token presented on an Auth Stream is as sensitive as one in the request URI, a GOAWAY carries an optional New Session URI that asks the peer to reconnect elsewhere. A malicious or compromised peer could use this to redirect a client to an attacker-controlled server. A recipient MUST validate the URI against local policy (scheme, authority, and port) before reconnecting, and MUST NOT reconnect if validation fails (see [GOAWAY](#goaway)). Migrated subscriptions carry no implicit trust from the prior session; the new session is authenticated independently. ## Routing Metadata and Privacy -A Node ID (see [Routing](#routing)) is opaque and fresh for each restart: it tells a peer which claims share an origin, and a route's metric how far that origin is, but not the relays in between. -A Node ID is declared, not proven, so a peer can forge another origin's Node ID or advertise a better route than it has. Qualifying the Node IDs of a peer with a scoped publish grant, under the key it proved in SETUP, confines such a forgery to the claims inside that grant; an unscoped peer is trusted with every origin. +A route's Path names every relay it crossed, so a routing node learns the shape of the mesh it routes over; a claim sent to any other peer carries a cost, a priority, and the Relays in its chain, but no Path. +A Node ID is declared, not proven, so a routing node can forge another's Node ID or advertise a better route than it has: endpoints exchange routes only with peers they trust with the whole tree. A peer confined by a scoped grant sends claims alone, which its receiver announces as its own and only inside that grant. ## Resource Exhaustion A peer can open many streams (subscriptions, announcements, fetches), request large announce prefixes, or advertise broad claims. Implementations SHOULD bound the number of concurrent subscriptions, announce matches, routes, and cached groups; an endpoint whose peer goes past its bound on subscriptions or announcements SHOULD close the session with TOO_MANY_REQUESTS, and SHOULD rely on QUIC flow control and stream limits to backpressure a misbehaving peer (see [ANNOUNCE_REQUEST](#announce-request)). Expiration (see [Expiration](#expiration)) bounds how long stale groups consume memory and flow control. A broad claim invites a request for any covered path, each of which may start work: an advertiser SHOULD bound the work it starts, withdrawing its claim before it runs out, and every refusal is terminal, so a flood of requests costs the mesh one round trip each rather than a search (see [Resolution](#resolution)). diff --git a/js/net/src/auth.test.ts b/js/net/src/auth.test.ts index f09eb89dccd..9b71fb2bdd8 100644 --- a/js/net/src/auth.test.ts +++ b/js/net/src/auth.test.ts @@ -412,7 +412,8 @@ describe.each([Lite.ALPN_07_WIP])("%s", (protocol) => { issued[0]?.revoke(SessionCode.Unauthorized, "expired"); const second = await nextRoute(announced); expect(second?.prefix).toBe(Path.from("a/x")); - expect(second?.kind).toBe("end"); + // Its publisher never ended it: the grant stopped covering it, so it is lost. + expect(second?.kind).toBe("offline"); // The union is empty but still a grant, and a new token restores it. const empty = await waitFor(client.auth.grant, (g) => g !== undefined && g.publish.size === 0); diff --git a/js/net/src/connection/forward.test.ts b/js/net/src/connection/forward.test.ts index 8bd23ffe80e..4f617cea7a1 100644 --- a/js/net/src/connection/forward.test.ts +++ b/js/net/src/connection/forward.test.ts @@ -1,7 +1,6 @@ import { afterEach, beforeEach, expect, jest, spyOn, test } from "bun:test"; import { Duration, type Installed } from "@moq/clock"; import { Manual } from "@moq/clock/test"; -import { Signal } from "@moq/signals"; import * as Announce from "../announced.ts"; import { AuthSession } from "../auth_session.ts"; import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "../broadcast.ts"; @@ -70,12 +69,6 @@ class FakeSession { /** Called as the forwarder closes a request, before its stream can wind down. */ onClose?: () => void; - /** Whether a lite-07 claim of `node` at `at` serves `path` beneath it: the session's floors. */ - covering?: (node: bigint, at: Path.Valid, path: Path.Valid) => boolean; - - /** Bumped when what `covering` answers changed with no route reporting it. */ - readonly coverage = new Signal(0); - closed: Promise; #die!: (reason: Error | null) => void; @@ -83,8 +76,6 @@ class FakeSession { constructor({ exclusive = false } = {}) { registerWire(this, { consume: (path, instance) => this.consume(path, instance), - covers: (node, at, path) => this.covering?.(node, at, path) ?? true, - coverage: this.coverage, exclusive, leave: () => {}, auth: new AuthSession({ peerGrant: { publish: new Path.Patterns(), subscribe: new Path.Patterns() } }), @@ -186,10 +177,10 @@ test("a request through a received route consumes that route's instance", async origin.close(); }); -// A lite-07 stream reports each origin node's claim at a path as its own route, so the origin -// holds every candidate: an unpinned request spreads by node as Rust's does, and one pinned to -// the claim that does not win still resolves. -test("the origin holds each origin node's claim at a prefix", async () => { +// A lite-07 stream reports each instance's claim at a path as its own route, so the origin holds +// every candidate: an unpinned request spreads by instance, and one pinned to the claim that +// does not win still resolves. +test("the origin holds each instance's claim at a prefix", async () => { const origin = new OriginProducer(); const session = new FakeSession(); forwardAnnounced(session.session, origin); @@ -198,12 +189,12 @@ test("the origin holds each origin node's claim at a prefix", async () => { const watch = origin.routes(Path.Pattern.subtree(Path.from("pool"))); await settle(); expect(session.requests[0]).toMatchObject({ claims: true }); - start(session.stream("pool/**"), "pool", { ...WireRoute.default, instance: a, node: 0x7an }); - start(session.stream("pool/**"), "pool", { ...WireRoute.default, instance: b, node: 0x8bn }); + start(session.stream("pool/**"), "pool", { ...WireRoute.default, instance: a, claimed: true }); + start(session.stream("pool/**"), "pool", { ...WireRoute.default, instance: b, claimed: true }); session.stream("pool/**").synced(); await settle(); - // 0x8b's rendezvous hash wins `pool/job`; see `lite07_ties_match_js` in rs/moq-net. + // `b`'s rendezvous hash wins `pool/job`; see `lite07_ties_match_js` in rs/moq-net. const job = Path.from("pool/job"); const unpinned = origin.request(job); await settle(); @@ -221,85 +212,6 @@ test("the origin holds each origin node's claim at a prefix", async () => { origin.close(); }); -// Two streams carry a lite-07 node's claims, and the newer floor, on the narrower one, presents -// nothing at live/x: the node's claim at live is older knowledge there. A request for live/x skips -// it, per request, for another node's claim at live of another instance. Mirrors `covering` in -// rs/moq-net. -test("the origin skips a claim above a newer floor's region", async () => { - const origin = new OriginProducer(); - const session = new FakeSession(); - forwardAnnounced(session.session, origin); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - const NODE_A = 0x7an; - const NODE_B = 0x8bn; - const live = origin.routes(Path.Pattern.subtree(Path.from("live"))); - await settle(); - start(session.stream("live/**"), "live", { ...WireRoute.default, instance: a, node: NODE_A }); - start(session.stream("live/**"), "live", { ...WireRoute.default, instance: b, node: NODE_B, cost: 5n }); - session.stream("live/**").synced(); - await settle(); - const x = Path.from("live/x"); - session.covering = (node, at, path) => !(node === NODE_A && at === Path.from("live") && Path.hasPrefix(x, path)); - - const request = origin.request(x); - await settle(); - expect(request.active.peek()).toBeDefined(); - expect(session.pins).toEqual([b]); - // Elsewhere under live the cheaper claim still serves. - const y = origin.request(Path.from("live/y")); - await settle(); - expect(session.pins).toEqual([b, a]); - - request.close(); - y.close(); - live.close(); - session.die(); - origin.close(); -}); - -// A floor moves what a claim covers while both routes stay as they were: the request already -// open beneath it is admitted anew and ends, and the next one resolves through the claim that -// still covers its path. -test("a floor that moves what a claim covers admits the open requests beneath it anew", async () => { - const origin = new OriginProducer(); - const session = new FakeSession(); - forwardAnnounced(session.session, origin); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - const NODE_A = 0x7an; - const NODE_B = 0x8bn; - const live = origin.routes(Path.Pattern.subtree(Path.from("live"))); - await settle(); - start(session.stream("live/**"), "live", { ...WireRoute.default, instance: a, node: NODE_A }); - start(session.stream("live/**"), "live", { ...WireRoute.default, instance: b, node: NODE_B, cost: 5n }); - session.stream("live/**").synced(); - await settle(); - - const x = Path.from("live/x"); - const request = origin.request(x); - await settle(); - expect(request.active.peek()).toBeDefined(); - expect(session.pins).toEqual([a]); - - session.covering = (node, at, path) => !(node === NODE_A && at === Path.from("live") && Path.hasPrefix(x, path)); - session.coverage.update((n) => n + 1); - await settle(); - // The claim it resolved through no longer serves its path, so it ends unroutable. - expect(request.closed.peek()).toBeInstanceOf(Error); - expect(session.pins).toEqual([a]); - const again = origin.request(x); - await settle(); - expect(again.active.peek()).toBeDefined(); - expect(session.pins).toEqual([a, b]); - - request.close(); - again.close(); - live.close(); - session.die(); - origin.close(); -}); - // A route handed to another request's report of another instance restarts, so its requests // consume that instance rather than the one the first report named. test("a route handed over to another instance consumes that instance", async () => { diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index bd26329ecdf..9b5dcd1c53b 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -23,13 +23,13 @@ export const DISCOVERY_REMOVED = const LINGER = Duration.millis(2000); /** - * Names one route a session reports: its prefix, and on lite-07 the origin node whose claim it - * is, since a stream reports each node's claim at a path as its own route. + * Names one route a session reports: its prefix, and on lite-07 the instance whose claim it is, + * since a stream reports each instance's claim at a path as its own route. */ type Key = string; function keyOf(prefix: Path.Valid, route: WireRoute): Key { - return route.node === undefined ? prefix : `${prefix}\u0000${route.node}`; + return route.claimed && route.instance !== undefined ? `${prefix}\u0000${route.instance}` : prefix; } /** One announce request open on the session, and the routes it currently reports. */ @@ -94,13 +94,6 @@ export function forwardAnnounced(conn: Session, origin: OriginProducer): void { const originWire = wireOf(origin); const session = wireOf(conn); const exclusive = session.exclusive; - // A lite-07 claim covers only what its origin node's newest floor on the session still - // certifies beneath it, which the origin asks per request. Mirrors `covering` in rs/moq-net. - const covering = (prefix: Path.Valid, route: WireRoute) => { - const node = route.node; - if (node === undefined || !session.covers) return undefined; - return (path: Path.Valid) => session.covers?.(node, prefix, path) ?? true; - }; // Reassigned on a downgrade, so the origin stops counting this session as discovering. // Called through a closure so the session's death always detaches the current one. let detach = originWire.attach(true); @@ -123,7 +116,7 @@ export function forwardAnnounced(conn: Session, origin: OriginProducer): void { const existing = routes.get(key); if (!existing) { - const handle = originWire.receive(prefix, route, covering(prefix, route)); + const handle = originWire.receive(prefix, route); routes.set(key, { prefix, handle, reporters: new Map([[interest, route]]) }); void drive(handle, conn); return; @@ -147,7 +140,7 @@ export function forwardAnnounced(conn: Session, origin: OriginProducer): void { if (restart || route.instance !== current?.instance || route.epoch !== current?.epoch) { // Inserted before the old one leaves, so local readers see one restart rather than // an end and a start. - const handle = originWire.receive(existing.prefix, route, covering(existing.prefix, route)); + const handle = originWire.receive(existing.prefix, route); existing.handle.close(); existing.handle = handle; void drive(handle, conn); @@ -305,20 +298,9 @@ export function forwardAnnounced(conn: Session, origin: OriginProducer): void { if (want && !covered && !blind) open(prefix); }); - // A floor can move what a claim covers while every route stays as it was, so the open - // requests beneath each claim are admitted anew: advertising a route as it stands reroutes them. - const uncovered = session.coverage?.subscribe(() => { - if (dead) return; - for (const { handle } of routes.values()) { - const wire = wireOf(handle); - if (wire.info?.node !== undefined) wire.update(wire.info); - } - }); - void conn.closed.then(() => { dead = true; unsubscribe(); - uncovered?.(); // End every request the moment the session closes rather than waiting for the wire to // error it, so the retractions land promptly. for (const interest of interests.values()) interest.announced.close(); diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts index c486093c684..81a643ec3f1 100644 --- a/js/net/src/consume.test.ts +++ b/js/net/src/consume.test.ts @@ -196,21 +196,3 @@ test("the newest stream wins a tie at its own prefix", () => { cache.announce(path, older, z, true); expect(cache.instance(path).route.instance).toBe(z.instance); }); - -test("the node serving an instance follows its routes even when another instance wins", () => { - const cache = new BroadcastCache(); - const path = Path.from("room"); - const x = Instance.random(); - const a = {}; - const b = {}; - const c = {}; - cache.announce(path, a, { ...WireRoute.default, instance: x, node: 1n }); - cache.announce(path, b, { ...WireRoute.default, instance: x, node: 2n, cost: 5n }); - expect(cache.node(path, x)).toEqual({ node: 1n, depth: 0 }); - cache.withdraw(path, a); - cache.announce(path, c, { ...WireRoute.default, instance: Instance.random(), node: 3n }); - expect(cache.instance(path).route.node).toBe(3n); - expect(cache.node(path, x)).toEqual({ node: 2n, depth: 0 }); - cache.withdraw(path, b); - expect(cache.node(path, x)).toBeUndefined(); -}); diff --git a/js/net/src/consume.ts b/js/net/src/consume.ts index a47e41c48bf..f5a093a2ae5 100644 --- a/js/net/src/consume.ts +++ b/js/net/src/consume.ts @@ -38,9 +38,9 @@ class Validity { } } -// The route a consume selected: its instance, and the origin node its requests name (lite-07). +// The route a consume selected: its instance, which its requests pin. type Selection = Served & { - readonly route: Pick; + readonly route: Pick; readonly validity?: Validity; }; @@ -50,13 +50,7 @@ class Blind implements Selection { readonly validity = new Validity(); } -/** Which claims above a consumed path may serve it: lite-07's floors. @internal */ -export interface Covering { - /** Whether the claim of origin `node` at `at` may serve a consume of `path` below it. */ - covers(node: bigint, at: Path.Valid, path: Path.Valid): boolean; -} - -type Advertised = { identity: object; route: WireRoute; parked?: boolean }; +type Advertised = { identity: object; route: WireRoute }; /** Consumed broadcasts shared only within the selected serving instance. @internal */ export class BroadcastCache { @@ -68,13 +62,6 @@ export class BroadcastCache { #blind = new Map(); #blindPrefixes = new Map>(); #paths = new Map>(); - readonly #covering?: Covering; - // What to re-check once a batch is applied: the prefixes it changed, or `all` of them. - #deferred?: { prefixes: Set; all: boolean }; - - constructor(covering?: Covering) { - this.#covering = covering; - } /** Record this interest's live advertisement, preserving identity across route updates. */ announce(path: Path.Valid, owner: object, route: WireRoute, restart = false): void { @@ -93,46 +80,6 @@ export class BroadcastCache { this.#update(path); } - /** - * Keep this interest's advertisement in its place among a tie while no consume may select it, - * until it is announced again without a restart: a lite-07 route that cannot be used for now. - */ - park(path: Path.Valid, owner: object): void { - const entry = this.#announced.get(path)?.get(owner); - if (!entry || entry.parked) return; - entry.parked = true; - this.#update(path); - } - - /** - * Apply the changes `apply` makes as one: each consume re-checks its selection once, after all - * of them, so none switches to a route only the middle of the change preferred. - */ - batch(apply: () => void): void { - if (this.#deferred) { - apply(); - return; - } - const deferred = { prefixes: new Set(), all: false }; - this.#deferred = deferred; - try { - apply(); - } finally { - this.#deferred = undefined; - if (deferred.all) this.revalidate(); - else for (const prefix of deferred.prefixes) this.#update(prefix); - } - } - - /** Re-check every consume's selection, once what covers a path changed without an announcement. */ - revalidate(): void { - if (this.#deferred) { - this.#deferred.all = true; - return; - } - for (const path of this.#cache.keys()) this.#check(path); - } - /** Withdraw this interest's advertisement without disturbing another interest's routes. */ withdraw(path: Path.Valid, owner: object): void { const entries = this.#announced.get(path); @@ -145,7 +92,7 @@ export class BroadcastCache { instance(path: Path.Valid): Selection { const best = mostSpecific( path, - (prefix) => bestCandidate(path, prefix, this.#eligible(path, prefix), (entry) => entry.route), + (prefix) => bestCandidate(path, prefix, this.#eligible(prefix), (entry) => entry.route), (entry) => entry.route, ); if (best) { @@ -173,7 +120,7 @@ export class BroadcastCache { const best = mostSpecific( path, (prefix) => { - const entries = this.#eligible(path, prefix).filter((entry) => entry.route.instance === instance); + const entries = this.#eligible(prefix).filter((entry) => entry.route.instance === instance); return bestCandidate(path, prefix, entries, (entry) => entry.route); }, (entry) => entry.route, @@ -181,16 +128,6 @@ export class BroadcastCache { return best ?? { identity: {}, route: { instance } }; } - /** - * The publisher node of the best route now serving `instance` at `path` (lite-07), and the - * depth of that route's prefix, whichever instance wins the path, or undefined when no route - * names one. - */ - node(path: Path.Valid, instance: Instance.Valid): { node: bigint; depth: number } | undefined { - const { node, depth } = this.pinned(path, instance).route; - return node === undefined ? undefined : { node, depth: depth ?? 0 }; - } - /** Clone the live cached consumer only when it serves the selected instance. */ get(path: Path.Valid, instance: Served): broadcast.Consumer | undefined { const cached = this.#cache.get(path)?.get(instance.route.instance ?? instance.identity); @@ -260,24 +197,12 @@ export class BroadcastCache { } } - // The advertisements at `prefix` a consume of `path` may select, oldest first. - #eligible(path: Path.Valid, prefix: Path.Valid): Advertised[] { - const covering = this.#covering; - return [...(this.#announced.get(prefix)?.values() ?? [])].filter( - (entry) => - !entry.parked && - (prefix === path || - entry.route.node === undefined || - !covering || - covering.covers(entry.route.node, prefix, path)), - ); + // The advertisements at `prefix`, oldest first. + #eligible(prefix: Path.Valid): Advertised[] { + return [...(this.#announced.get(prefix)?.values() ?? [])]; } #update(prefix: Path.Valid): void { - if (this.#deferred) { - this.#deferred.prefixes.add(prefix); - return; - } for (const path of this.#paths.get(prefix) ?? []) this.#check(path); } diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 7c12f6b3eaf..c48e2ddf37d 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -167,26 +167,21 @@ export interface WireRoute { /** See {@link RouteInfo.available}; unset means available. */ readonly available?: boolean; /** - * The origin node a lite-07 route reaches, which every request through it names. Unset on a - * route announced here and on every other version. Local: requests name it, readers never - * see it. + * A claim a lite-07 peer sent, one per instance at a path, which a reader asking for every + * claim reports as a route of its own. Unset on a route announced here and on every other + * version. Local: readers never see it. */ - readonly node?: bigint; + readonly claimed?: boolean; /** - * How many leading segments of a requested path make up the prefix of the lite-07 route to - * {@link node}, which every request through it names. Local, as `node` is. - */ - readonly depth?: number; - /** - * The lowest priority of a link on the path of the lite-07 route to {@link node}: higher - * ranks first, after drain and before cost, as routes to one node rank. Unset ranks as 0, the - * priority of a link no one set. Local, as `node` is. + * The lowest priority of a link on the way to a lite-07 claim's publisher: higher ranks + * first, after drain and before cost. Unset ranks as 0, the priority of a link no one set. + * Local, as `claimed` is. */ readonly priority?: number; /** * How many segments broader the lite-07 claim is than the path it is presented at: a claim * exactly at a path outranks every broader one shown there, before anything else. Unset ranks - * as 0. Local, as `node` is. + * as 0. Local, as `claimed` is. */ readonly above?: bigint; } @@ -210,8 +205,7 @@ export const WireRoute = { auth: route.auth, draining: route.draining, available: route.available, - node: route.node, - depth: route.depth, + claimed: route.claimed, priority: route.priority, above: route.above, }; @@ -232,7 +226,7 @@ export function isAnonymous(route: WireRoute): boolean { /** * Whether two routes name the same instance, epoch, hop chain, cost, auth, drain state, - * availability, origin node, route depth, priority, and how far above its path a claim is. + * availability, whether a lite-07 peer claimed it, priority, and how far above its path a claim is. * * @internal */ @@ -246,8 +240,7 @@ export function routesEqual(a: WireRoute | undefined, b: WireRoute | undefined): a.auth === b.auth && (a.draining ?? false) === (b.draining ?? false) && (a.available ?? true) === (b.available ?? true) && - a.node === b.node && - a.depth === b.depth && + (a.claimed ?? false) === (b.claimed ?? false) && (a.priority ?? 0) === (b.priority ?? 0) && (a.above ?? 0n) === (b.above ?? 0n) && a.hops.length === b.hops.length && diff --git a/js/net/src/integers.test.ts b/js/net/src/integers.test.ts index ab324700bda..16fc1990649 100644 --- a/js/net/src/integers.test.ts +++ b/js/net/src/integers.test.ts @@ -158,11 +158,10 @@ for (const version of [Lite.DRAFT_06, Lite.DRAFT_07]) { const body = await Writer.collect(version, async (w) => { await w.string("room"); if (version === Lite.DRAFT_07) { - // No pinned instance: empty and unminted, and no origin node nor route depth. + // No pinned instance: empty and unminted, and no node named. await w.u53(0); await w.bool(false); await w.u62(0n); - await w.u53(0); } await w.string("video"); await w.u8(0); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 9b6c99cc64f..2196603f155 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -1364,10 +1364,13 @@ export const hooks: { }, }; -/** FNV-1a 64 of `path`, then `bytes`. The seed is the draft's Spread Hash offset basis. */ -function fnv(path: string, bytes: Iterable): bigint { +/** The Spread Hash's offset basis, which lite-06 and earlier rank by. */ +const SPREAD_BASIS = 0x420c0decb00bn; + +/** FNV-1a 64 from `basis` of `path`, then `bytes`. */ +function fnv(path: string, bytes: Iterable, basis = SPREAD_BASIS): bigint { const prime = 0x100000001b3n; - let hash = 0x420c0decb00bn; + let hash = basis; for (const byte of new TextEncoder().encode(path)) { hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * prime); } @@ -1388,14 +1391,12 @@ export function spreadHash(path: string, instance: string): bigint { } /** - * The draft's Rendezvous Hash: FNV-1a 64 of `path` then the origin's Node ID as 8 little-endian - * bytes, so every node that knows the same lite-07 claims ranks them alike. Mirrors the node key - * of `route_order` in `rs/moq-net`. + * The draft's Rendezvous Hash: standard FNV-1a 64 of `path` then the instance's UTF-8, which + * spreads a pool's lite-07 claims across paths the same on every node. Mirrors `rendezvous` in + * `rs/moq-net`. */ -export function rendezvousHash(path: string, node: bigint): bigint { - const bytes: number[] = []; - for (let shift = 0n; shift < 64n; shift += 8n) bytes.push(Number((node >> shift) & 0xffn)); - return fnv(path, bytes); +export function rendezvousHash(path: string, instance: string): bigint { + return fnv(path, new TextEncoder().encode(instance), 0xcbf29ce484222325n); } /** @@ -1524,15 +1525,15 @@ export function compareRoutes(a: WireRoute, b: WireRoute): number { return ( last(a) - last(b) || (b.priority ?? 0) - (a.priority ?? 0) || - Number(a.node === undefined && isAnonymous(a)) - Number(b.node === undefined && isAnonymous(b)) || + Number(isAnonymous(a)) - Number(isAnonymous(b)) || (a.cost < b.cost ? -1 : a.cost > b.cost ? 1 : 0) ); } /** * Order eligible routes at `prefix` resolving `path` by preference, hop count, then the spread - * hash of each instance, then, within one instance, the hash of its chain. A lite-07 route counts - * as the one hop to its origin node, and ranks by the rendezvous hash of that node instead. The + * hash of each instance, then, within one instance, the hash of its chain. A lite-07 claim counts + * as one hop, to the peer that sent it, and ranks by the rendezvous hash of its instance. The * hashes only spread a prefix's paths: at the prefix itself a tie is left for the newest to win * (see {@link bestCandidate}), so a publisher that restarts under a new instance takes over from * its lingering session at once, matching `route_order` in rs/moq-net for routes a node did not @@ -1549,21 +1550,15 @@ export function compareRouteCandidates(path: Path.Valid, prefix: Path.Valid, a: return a2 < b2 ? -1 : a2 > b2 ? 1 : 0; } -/** - * The hops a route ranks by: a lite-07 route counts as the one hop to its origin node, since the - * rest of its chain is the lite-06 one it carries only for loop detection. As `route_order` in - * rs/moq-net. - */ +/** The hops a route ranks by: a lite-07 claim counts as the one hop to the peer that sent it. */ export function routeHops(route: WireRoute): number { - return route.node !== undefined ? 1 : route.hops.length; + return route.claimed ? 1 : route.hops.length; } -/** - * The hash pair `route_order` in rs/moq-net ranks a route by beneath its prefix, each route keyed - * on its own: a lite-07 claim by the rendezvous hash of its origin node, any other by the spread - * hash of its instance and then the hash of its chain. - */ +/** The hash pair a route ranks by beneath its prefix, each route keyed on its own: a lite-07 claim + * by the rendezvous hash of its instance, any other by the spread hash of its instance and then + * the hash of its chain. As `route_order` in rs/moq-net. */ function routeKey(path: Path.Valid, route: WireRoute): [bigint, bigint] { - if (route.node !== undefined) return [rendezvousHash(path, route.node), 0n]; + if (route.claimed) return [rendezvousHash(path, route.instance ? Instance.text(route.instance) : ""), 0n]; return [spreadHash(path, route.instance ? Instance.text(route.instance) : ""), chainHash(path, route.hops)]; } diff --git a/js/net/src/lite/announce.test.ts b/js/net/src/lite/announce.test.ts index 2281d82ce6a..54894eb91bb 100644 --- a/js/net/src/lite/announce.test.ts +++ b/js/net/src/lite/announce.test.ts @@ -1,6 +1,6 @@ import { expect, test } from "bun:test"; import { ProtocolViolation } from "../error.ts"; -import { Cost, toHop, UNKNOWN_HOP } from "../hop.ts"; +import { toHop, UNKNOWN_HOP } from "../hop.ts"; import * as Instance from "../instance.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; @@ -9,11 +9,12 @@ import { AnnounceHistory, AnnounceOk, AnnounceRequest, + CHAIN_MAX, + type Claim, decodeAnnounceBroadcast, decodeAnnounceBroadcastMaybe, encodeAnnounceBroadcast, - type Offer, - ROUTE_MAX_HOPS, + ownClaim, requestFits, requestParts, } from "./announce.ts"; @@ -79,28 +80,6 @@ test("AnnounceBroadcast round-trips on draft-06", async () => { expect(gotUpdate).toEqual({ status: "update", id: 3n, hops, cost }); }); -test("AnnounceBroadcast carries a restart only on draft-07", async () => { - const instance = Instance.random(); - for (const msg of [ - { status: "restart" as const, id: 3n, instance, epoch: 0n, cost: 12n, above: 0n }, - { status: "restart" as const, id: 3n, instance, epoch: 7n, cost: 12n, above: 2n }, - ]) { - expect(await roundTrip(msg, Version.DRAFT_07)).toEqual(msg); - } - - // Older versions send an end and a start instead, and skip the type as unknown. - await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 1n }, Version.DRAFT_06), Version.DRAFT_06), - ).rejects.toThrow(); - const encoded = await bytes(async (w) => { - await w.u53(3); - await w.u53(1); - await w.u8(1); - }, Version.DRAFT_06); - const reader = new Reader(undefined, encoded, Version.DRAFT_06); - expect(await decodeAnnounceBroadcast(reader, Version.DRAFT_06)).toEqual({ status: "skipped" }); -}); - test("AnnounceBroadcast skips an unknown type on draft-06", async () => { const encoded = await bytes(async (w) => { await w.u53(4); @@ -111,10 +90,9 @@ test("AnnounceBroadcast skips an unknown type on draft-06", async () => { expect(await decodeAnnounceBroadcast(reader, Version.DRAFT_06)).toEqual({ status: "skipped" }); }); -// Type 5 was a lite-07 message once; the version is unpublished, so it is now unknown there too. -test("AnnounceBroadcast skips type 5 as unknown on draft-07", async () => { +test("AnnounceBroadcast skips an unknown type on draft-07", async () => { const encoded = await bytes(async (w) => { - await w.u53(5); + await w.u53(11); await w.u53(2); await w.u8(0); await w.u8(0); @@ -214,16 +192,16 @@ test("ANNOUNCE_REQUEST edits the requested prefixes on lite-07", async () => { ], }; const wire = await bytes((w) => encodeAnnounceBroadcast(w, msg, v), v); - expect(wire).toEqual(new Uint8Array([16, 13, 1, 2, 1, 2, 2, 4, 0x72, 0x6f, 0x6f, 0x6d, 1, 0, 0])); + expect(wire).toEqual(new Uint8Array([5, 13, 1, 2, 1, 2, 2, 4, 0x72, 0x6f, 0x6f, 0x6d, 1, 0, 0])); expect(await roundTrip(msg, v)).toEqual(msg); const empty: AnnounceBroadcast = { status: "request", more: false, remove: [], add: [] }; - expect(await bytes((w) => encodeAnnounceBroadcast(w, empty, v), v)).toEqual(new Uint8Array([16, 3, 0, 0, 0])); + expect(await bytes((w) => encodeAnnounceBroadcast(w, empty, v), v)).toEqual(new Uint8Array([5, 3, 0, 0, 0])); await expect(roundTrip(msg, Version.DRAFT_06)).rejects.toThrow(); await expect(bytes((w) => new AnnounceRequest(Path.from("room"), UNKNOWN_HOP).encode(w, v), v)).rejects.toThrow(); // A count the body cannot hold, and a More or a Hidden that is no boolean, are malformed. const decode = (body: number[]) => - decodeAnnounceBroadcast(new Reader(undefined, new Uint8Array([16, body.length, ...body]), v), v); + decodeAnnounceBroadcast(new Reader(undefined, new Uint8Array([5, body.length, ...body]), v), v); await expect(decode([0, 3, 1, 0])).rejects.toThrow(); await expect(decode([0, 0, 1, 0, 2])).rejects.toThrow(); await expect(decode([2, 0, 0])).rejects.toThrow(); @@ -363,7 +341,7 @@ function unhex(text: string): Uint8Array { return new Uint8Array(text.match(/../g)?.map((b) => Number.parseInt(b, 16)) ?? []); } -// Resolve every announcement on a lite-07 stream, as the subscriber does. +// Resolve every claim on a lite-07 stream, as the subscriber does. async function resolveStream(data: Uint8Array) { const reader = new Reader(undefined, data, Version.DRAFT_07); const history = new AnnounceHistory(); @@ -372,17 +350,15 @@ async function resolveStream(data: Uint8Array) { const msg = await decodeAnnounceBroadcastMaybe(reader, Version.DRAFT_07); if (!msg) return out; switch (msg.status) { - case "active": { - const { route, instance, epoch, cost } = msg; - out.push({ start: history.start(msg), route, instance, epoch, cost }); + case "start": + out.push({ start: history.start(msg), instance: msg.instance, claim: msg.claim }); break; - } - case "update": + case "change": history.get(msg.id); - out.push({ update: msg.id, cost: msg.cost }); + out.push({ update: msg.id, claim: msg.claim }); break; case "endedId": - out.push({ end: msg.id, suffix: history.end(msg.id) }); + out.push({ end: msg.id, suffix: history.end(msg.id), lost: msg.lost }); break; default: throw new Error(`unexpected ${msg.status}`); @@ -392,18 +368,19 @@ async function resolveStream(data: Uint8Array) { const a = Instance.parse("a"); const b = Instance.parse("b"); -const claim = { route: 0n, instance: a, epoch: 0n, cost: 0n }; +const own = { instance: a, claim: ownClaim(0n) }; const GOLDEN_RESOLVED = [ - { start: Path.from("room/a/cam"), ...claim }, - { start: Path.from("room/a/mic"), ...claim }, - { update: 0n, cost: 0n }, - { end: 1n, suffix: Path.from("room/a/mic") }, - { start: Path.from("room/b"), ...claim }, + { start: Path.from("room/a/cam"), ...own }, + { start: Path.from("room/a/mic"), ...own }, + { update: 0n, claim: ownClaim(0n) }, + { end: 1n, suffix: Path.from("room/a/mic"), lost: false }, + { start: Path.from("room/b"), ...own }, ]; // Rust's compressed output, pinned by `lite::compress::tests::golden_stream_is_pinned`. const GOLDEN = - "001400000a726f6f6d2f612f63616d00016100000000000d0102036d6963000161000000000203000000010101000b0201016200016100000000"; + "001600000a726f6f6d2f612f63616d01610000000000ff00000f0102036d696301610000000000ff0002070000000000ff00" + + "01020100000d0201016201610000000000ff00"; test("AnnounceHistory resolves the Rust encoder's compressed stream", async () => { expect(await resolveStream(unhex(GOLDEN))).toEqual(GOLDEN_RESOLVED); @@ -411,284 +388,106 @@ test("AnnounceHistory resolves the Rust encoder's compressed stream", async () = // JS always encodes literally. Rust's `js_literal_stream_decodes` pins the same bytes. const JS_LITERAL = - "001400000a726f6f6d2f612f63616d00016100000000001400000a726f6f6d2f612f6d69630001610000000002030000000101010" + - "010000006726f6f6d2f6200016100000000"; + "001600000a726f6f6d2f612f63616d01610000000000ff00001600000a726f6f6d2f612f6d696301610000000000ff00" + + "02070000000000ff00010201000012000006726f6f6d2f6201610000000000ff00"; test("the literal draft-07 stream matches what Rust decodes", async () => { const wire = await bytes(async (w) => { const v = Version.DRAFT_07; - const start = (suffix: string): AnnounceBroadcast => ({ - status: "active", - suffix: Path.from(suffix), - route: 0n, - instance: a, - epoch: 0n, - cost: 0n, - }); + const start = (suffix: string): AnnounceBroadcast => ({ status: "start", suffix: Path.from(suffix), ...own }); await encodeAnnounceBroadcast(w, start("room/a/cam"), v); await encodeAnnounceBroadcast(w, start("room/a/mic"), v); - await encodeAnnounceBroadcast(w, { status: "update", id: 0n, cost: 0n }, v); - await encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, v); + await encodeAnnounceBroadcast(w, { status: "change", id: 0n, claim: ownClaim(0n) }, v); + await encodeAnnounceBroadcast(w, { status: "endedId", id: 1n, lost: false }, v); await encodeAnnounceBroadcast(w, start("room/b"), v); }, Version.DRAFT_07); expect(hex(wire)).toBe(JS_LITERAL); expect(await resolveStream(wire)).toEqual(GOLDEN_RESOLVED); }); -// `rs/moq-net/fixtures/lite.json` pins the same bytes on both sides. -test("the route layer round-trips on draft-07", async () => { +// A claim says its cost, how far above its path it is, whether it is unavailable or draining, +// the lowest priority on its way, and the nodes that announced it again. +test("a lite-07 claim round-trips with its exact bytes", async () => { const v = Version.DRAFT_07; - const offer: Offer = { - path: [ - { node: 7n, session: 0n }, - { node: 9n, session: 2n }, - ], - draining: false, - priority: 0, - metric: 5n, - downOnly: true, + const claim: Claim = { + epoch: 7n, + cost: 12n, + above: 2n, + unavailable: true, + draining: true, + priority: -3, + chain: [5n, 9n], }; - const one: Offer = { ...offer, path: [{ node: 7n, session: 0n }], downOnly: false, metric: 0n }; const cases: [AnnounceBroadcast, number[]][] = [ - // The path first, the publisher first, then flags, priority (offset by 128), and metric. - [ - { status: "routeStart", node: 0x1234n, prefix: 3n, suffix: Path.empty(), exact: false, offer }, - [6, 13, 0x92, 0x34, 3, 0, 0, 2, 7, 0, 9, 2, 1, 128, 5], - ], - // Exact: a route at the requested prefix whose own prefix it is. - [ - { status: "routeStart", node: 7n, prefix: 0n, suffix: Path.empty(), exact: true, offer: one }, - [6, 10, 7, 0, 0, 1, 1, 7, 0, 0, 128, 0], - ], - // Flag 0x2: a node on the path drains. - [ - { - status: "routeUpdate", - id: 1n, - offer: { - ...offer, - path: [{ node: 7n, session: 0n }], - draining: true, - priority: -3, - downOnly: false, - }, - }, - [7, 7, 1, 1, 7, 0, 2, 125, 5], - ], - // As many hops as a route may carry. + // Path base, path keep, the suffix, instance "b", unminted, epoch, then the claim: cost, + // above, both flags, the priority with its sign bit flipped, and the chain. [ - { - status: "routeUpdate", - id: 1n, - offer: { - ...one, - path: Array.from({ length: ROUTE_MAX_HOPS }, (_, i) => ({ node: BigInt(i + 1), session: 0n })), - }, - }, - [ - 7, - 5 + 2 * ROUTE_MAX_HOPS, - 1, - ROUTE_MAX_HOPS, - ...Array.from({ length: ROUTE_MAX_HOPS }, (_, i) => [i + 1, 0]).flat(), - 0, - 128, - 0, - ], + { status: "start", suffix: Path.from("x"), instance: b, claim }, + [0, 15, 0, 0, 1, 0x78, 1, 0x62, 0, 7, 12, 2, 3, 0x7d, 2, 5, 9], ], - [{ status: "routeHold", id: 1n }, [0xb, 1, 1]], - [{ status: "routeEnd", id: 1n }, [8, 1, 1]], - [{ status: "dead", dead: { kind: "drain", node: 7n } }, [15, 2, 1, 7]], - // Each moved offer is sized, so a receiver refusing one still reads the next. - [ - { - status: "dead", - dead: { - kind: "closed", - hop: { node: 7n, session: 3n }, - far: 9n, - gone: false, - moved: 1n, - }, - }, - [15, 6, 0, 7, 3, 9, 0, 1], - ], - // The routes it counts follow as ROUTE_UPDATEs of their own. - [{ status: "routeUpdate", id: 1n, offer: one }, [7, 7, 1, 1, 7, 0, 0, 128, 0]], - [ - { - status: "dead", - dead: { kind: "closed", hop: { node: 7n, session: 3n }, far: 9n, gone: true, moved: 0n }, - }, - [15, 6, 0, 7, 3, 9, 1, 0], - ], - // Revision 4 travels as 5: 0 certifies nothing. - [{ status: "floor", id: 1n, revision: 4n }, [9, 2, 1, 5]], - [{ status: "floor", id: 1n, revision: undefined }, [9, 2, 1, 0]], + [{ status: "change", id: 1n, claim }, [2, 9, 1, 7, 12, 2, 3, 0x7d, 2, 5, 9]], + [{ status: "endedId", id: 1n, lost: true }, [1, 2, 1, 1]], + [{ status: "endedId", id: 1n, lost: false }, [1, 2, 1, 0]], ]; for (const [msg, wire] of cases) { - const encoded = await bytes((w) => encodeAnnounceBroadcast(w, msg, v), v); - expect([...encoded]).toEqual(wire); + expect([...(await bytes((w) => encodeAnnounceBroadcast(w, msg, v), v))]).toEqual(wire); expect(await roundTrip(msg, v)).toEqual(msg); - // Older versions have none of it. - await expect( - bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06), Version.DRAFT_06), - ).rejects.toThrow(); } + // An own claim is the bytes every endpoint sends: no cost, the top priority, no chain. + const start = await bytes( + (w) => + encodeAnnounceBroadcast(w, { status: "start", suffix: Path.empty(), instance: b, claim: ownClaim(0n) }, v), + v, + ); + expect([...start]).toEqual([0, 12, 0, 0, 0, 1, 0x62, 0, 0, 0, 0, 0, 0xff, 0]); - // Lite-07 claims name their route and carry no hop chain. - const literal: AnnounceBroadcast = { status: "active", suffix: Path.from("x"), route: 2n, instance: a, epoch: 1n }; - expect(await roundTrip(literal, v)).toEqual({ ...literal, cost: 0n, above: 0n }); - await expect(bytes((w) => encodeAnnounceBroadcast(w, { ...literal, route: undefined }, v), v)).rejects.toThrow(); - await expect(bytes((w) => encodeAnnounceBroadcast(w, { ...literal, hops: [toHop(1n)] }, v), v)).rejects.toThrow(); -}); - -test("the route layer refuses Node ID 0, unknown flags, and too many hops", async () => { - const v = Version.DRAFT_07; - const offer: Offer = { - path: [{ node: 1n, session: 0n }], - draining: false, - priority: 0, - metric: 0n, - downOnly: false, - }; - const encode = (msg: AnnounceBroadcast) => bytes((w) => encodeAnnounceBroadcast(w, msg, v), v); - // No node sends an offer it would refuse. + // Older versions have no claims, and lite-07 has nothing else. + const start06: AnnounceBroadcast = { status: "start", suffix: Path.from("x"), instance: b, claim }; await expect( - encode({ status: "routeStart", node: 0n, prefix: 0n, suffix: Path.empty(), exact: false, offer }), + bytes((w) => encodeAnnounceBroadcast(w, start06, Version.DRAFT_06), Version.DRAFT_06), ).rejects.toThrow(); - await expect(encode({ status: "routeUpdate", id: 0n, offer: { ...offer, path: [] } })).rejects.toThrow(); await expect( - encode({ status: "routeUpdate", id: 0n, offer: { ...offer, path: [{ node: 0n, session: 0n }] } }), + bytes((w) => encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("x"), hops: [] }, v), v), ).rejects.toThrow(); - const crowded = Array.from({ length: ROUTE_MAX_HOPS + 1 }, () => ({ node: 1n, session: 0n })); - await expect(encode({ status: "routeUpdate", id: 0n, offer: { ...offer, path: crowded } })).rejects.toThrow(); await expect( - encode({ - status: "dead", - dead: { - kind: "closed", - hop: { node: 0n, session: 0n }, - far: 2n, - gone: false, - moved: 0n, - }, - }), + bytes((w) => encodeAnnounceBroadcast(w, { status: "update", id: 0n, hops: [] }, v), v), ).rejects.toThrow(); +}); - // Built by hand, as only a nonconforming peer sends them. - const forged = async (type: number, body: (w: Writer) => Promise) => { - const inner = await bytes(body, v); - return bytes(async (w) => { - await w.u53(type); - await w.u53(inner.byteLength); - await w.write(inner); - }, v); - }; - // A ROUTE_START to `node` along `path`, its flags `flags`, and nothing after them. - const start = (node: bigint, path: bigint[], flags: number) => - forged(6, async (w) => { - await w.u62(node); - await w.u62(5n); - await w.u53(0); - // Not exact. - await w.u8(0); - await w.u62(BigInt(path.length)); - for (const hop of path) { - await w.u62(hop); - await w.u62(0n); - } - await w.u8(flags); - await w.u8(128); - await w.u62(0n); - }); - // What the sender only forwarded is refused, the message decoded all the same, so the receiver - // withdraws the route and keeps the stream, with the path a later DEAD may name. - const decode = (wire: Uint8Array) => decodeAnnounceBroadcast(new Reader(undefined, wire, v), v); - const path = [{ node: 1n, session: 0n }]; - expect(await decode(await start(0n, [1n], 0))).toEqual({ - status: "refused", - message: { kind: "routeStart", node: 0n, prefix: 5n, suffix: Path.empty(), exact: false, path }, - reason: "node", +test("a lite-07 claim refuses Node ID 0, unknown flags, and too long a chain", async () => { + const v = Version.DRAFT_07; + const change = (claim: Claim) => + bytes((w) => encodeAnnounceBroadcast(w, { status: "change", id: 0n, claim }, v), v); + const full = Array.from({ length: CHAIN_MAX }, (_, i) => BigInt(i + 1)); + expect(await roundTrip({ status: "change", id: 0n, claim: { ...ownClaim(0n), chain: full } }, v)).toMatchObject({ + claim: { chain: full }, }); - expect(await decode(await start(1n, [0n], 0))).toMatchObject({ status: "refused", reason: "node" }); - // A flag no version defines is refused. - for (const flags of [4, 8]) { - expect(await decode(await start(1n, [1n], flags))).toEqual({ - status: "refused", - message: { kind: "routeStart", node: 1n, prefix: 5n, suffix: Path.empty(), exact: false, path }, - reason: "flags", + await expect(change({ ...ownClaim(0n), chain: [0n] })).rejects.toThrow(); + await expect(change({ ...ownClaim(0n), chain: [...full, 99n] })).rejects.toThrow(); + + // ANNOUNCE_UPDATE: id, epoch, cost, above, flags, priority, then the chain. + const decode = (...claim: number[]) => { + const body = [0, 0, 0, 0, ...claim]; + return decodeAnnounceBroadcast(new Reader(undefined, new Uint8Array([2, body.length, ...body]), v), v); + }; + expect(await decode(0, 0xff, 0)).toEqual({ status: "change", id: 0n, claim: ownClaim(0n) }); + await expect(decode(4, 0xff, 0)).rejects.toThrow(ProtocolViolation); + await expect(decode(0, 0xff, 1, 0)).rejects.toThrow(ProtocolViolation); + await expect(decode(0, 0xff, CHAIN_MAX + 1, ...full.map(Number), 40)).rejects.toThrow(ProtocolViolation); +}); + +// Only two nodes that both declared a Node ID exchange routes, and an endpoint declares none. +test("a route message to an endpoint is a violation on lite-07", async () => { + for (const typ of [3, 7, 8, 9, 10]) { + const wire = new Uint8Array([typ, 1, 0]); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07), + ).rejects.toThrow(ProtocolViolation); + // Earlier versions never defined them, so they skip them as unknown. + expect(await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_06), Version.DRAFT_06)).toEqual({ + status: "skipped", }); } - // More hops than a route may carry. - const over = Array.from({ length: ROUTE_MAX_HOPS + 1 }, () => 1n); - expect(await decode(await start(1n, over, 0))).toMatchObject({ status: "refused", reason: "hops" }); - // Far past the limit, only the hops up to one past it are kept. - const far = Array.from({ length: 4 * (ROUTE_MAX_HOPS + 1) }, () => 1n); - const kept = await decode(await start(1n, far, 0)); - expect(kept).toMatchObject({ status: "refused", reason: "hops" }); - if (kept.status !== "refused" || kept.message.kind !== "routeStart") throw new Error("a refused ROUTE_START"); - expect(kept.message.path).toHaveLength(ROUTE_MAX_HOPS + 1); - // An empty path is the sender's own error: it names itself last. - await expect(decode(await start(1n, [], 0))).rejects.toThrow(ProtocolViolation); - // Exact is a boolean. - const notBoolean = await forged(6, async (w) => { - await w.u62(1n); - await w.u62(0n); - await w.string(""); - await w.u8(2); - await w.u62(1n); - await w.u62(1n); - await w.u62(0n); - await w.u8(0); - await w.u8(128); - await w.u62(0n); - }); - await expect(decode(notBoolean)).rejects.toThrow(); - - // A DEAD counts the ROUTE_UPDATEs that follow, each refused on its own. - const dead = await forged(15, async (w) => { - await w.u62(0n); - await w.u62(1n); - await w.u62(0n); - await w.u62(2n); - await w.u8(0); - await w.u62(2n); - }); - expect(await decode(dead)).toEqual({ - status: "dead", - dead: { kind: "closed", hop: { node: 1n, session: 0n }, far: 2n, gone: false, moved: 2n }, - }); - const update = (flags: number) => - forged(7, async (w) => { - await w.u62(3n); - await w.u62(1n); - await w.u62(1n); - await w.u62(0n); - await w.u8(flags); - await w.u8(128); - await w.u62(0n); - }); - expect(await decode(await update(8))).toEqual({ - status: "refused", - message: { kind: "routeUpdate", id: 3n, path }, - reason: "flags", - }); - expect(await decode(await update(0))).toEqual({ - status: "routeUpdate", - id: 3n, - offer: { path, draining: false, priority: 0, metric: 0n, downOnly: false }, - }); - // A Gone that is no boolean is malformed. - const gone = await forged(15, async (w) => { - await w.u62(0n); - await w.u62(1n); - await w.u62(0n); - await w.u62(2n); - await w.u8(2); - await w.u62(0n); - }); - await expect(decode(gone)).rejects.toThrow(); }); test("AnnounceHistory rejects a base that is not live", () => { @@ -761,80 +560,42 @@ test("a keep without a base is a violation on draft-07", async () => { ).rejects.toThrow(ProtocolViolation); }); -test("draft-06 has no room for a base", async () => { - const msg: AnnounceBroadcast = { - status: "active", - suffix: Path.from("x"), - hops: [], - pathBase: { distance: 1n, keep: 1 }, - }; - await expect(bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); -}); - // Costs saturate at 2^62-1 on every version: a larger one from a lite-07 peer reads as the // ceiling, and one set locally goes out as the ceiling, so a cost always forwards to lite-06. test("route costs saturate at 2^62-1 on every version", async () => { const ceiling = 2n ** 62n - 1n; const huge = 2n ** 64n - 1n; - for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { - const lite07 = version === Version.DRAFT_07; - const msg: AnnounceBroadcast = lite07 - ? { status: "active", suffix: Path.from("x"), route: 0n, instance: a, epoch: 0n, cost: huge } - : { status: "active", suffix: Path.from("x"), hops: [], cost: huge }; - expect(await roundTrip(msg, version)).toMatchObject({ cost: ceiling }); - } + const claimed: AnnounceBroadcast = { + status: "start", + suffix: Path.from("x"), + instance: a, + claim: { ...ownClaim(0n), cost: huge }, + }; + expect(await roundTrip(claimed, Version.DRAFT_07)).toMatchObject({ claim: { cost: ceiling } }); + const active: AnnounceBroadcast = { status: "active", suffix: Path.from("x"), hops: [], cost: huge }; + expect(await roundTrip(active, Version.DRAFT_06)).toMatchObject({ cost: ceiling }); - // ANNOUNCE_START: path base, path keep, empty suffix, route 0, instance "a", unminted, epoch 0, - // then a cost of 2^64-1, which only lite-07's varints can carry, and its above. + // ANNOUNCE_START: path base, path keep, empty suffix, instance "a", unminted, epoch 0, then a + // cost of 2^64-1, which only lite-07's varints can carry, and the rest of an own claim. const wire = await bytes(async (w) => { await w.u53(0); - await w.u53(18); - for (const byte of [0, 0, 0, 0, 1, 0x61, 0, 0]) await w.u8(byte); + await w.u53(20); + for (const byte of [0, 0, 0, 1, 0x61, 0, 0]) await w.u8(byte); await w.u62(huge); - await w.u8(0); + for (const byte of [0, 0, 0xff, 0]) await w.u8(byte); }, Version.DRAFT_07); const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); - expect(got).toMatchObject({ cost: ceiling }); -}); - -test("wip start and update carry one static cost", async () => { - const v = Version.DRAFT_07; - const start = await bytes( - (w) => - encodeAnnounceBroadcast( - w, - { status: "active", suffix: Path.empty(), route: 0n, instance: b, cost: Cost.zero }, - v, - ), - v, - ); - // Path base, path keep, empty suffix, route 0, instance "b", unminted, epoch 0, cost, above. - expect([...start]).toEqual([0, 10, 0, 0, 0, 0, 1, 0x62, 0, 0, 0, 0]); - const update = await bytes((w) => encodeAnnounceBroadcast(w, { status: "update", id: 0n, cost: Cost.zero }, v), v); - expect([...update]).toEqual([2, 3, 0, 0, 0]); + expect(got).toMatchObject({ claim: { cost: ceiling } }); }); -test("a lite-07 claim carries how far above its path it is", async () => { +test("a claim above its path travels only on lite-07", async () => { const v = Version.DRAFT_07; - const start: AnnounceBroadcast = { status: "active", suffix: Path.empty(), route: 0n, instance: b, above: 3n }; - expect(await roundTrip(start, v)).toEqual({ ...start, cost: 0n, epoch: 0n }); - const update: AnnounceBroadcast = { status: "update", id: 0n, cost: Cost.zero, above: 2n }; + const start: AnnounceBroadcast = { status: "start", suffix: Path.empty(), instance: b, claim: ownClaim(1n, 3n) }; + expect(await roundTrip(start, v)).toEqual(start); + const update: AnnounceBroadcast = { status: "change", id: 0n, claim: ownClaim(1n, 2n) }; expect(await roundTrip(update, v)).toEqual(update); - const wire = await bytes((w) => encodeAnnounceBroadcast(w, update, v), v); - expect([...wire]).toEqual([2, 3, 0, 0, 2]); - - // Earlier versions have no such field, so a claim above its path cannot travel on them. - await expect( - bytes( - (w) => - encodeAnnounceBroadcast( - w, - { status: "active", suffix: Path.empty(), hops: [], above: 1n }, - Version.DRAFT_06, - ), - Version.DRAFT_06, - ), - ).rejects.toThrow(); + // Id, epoch, cost, above, flags, priority, chain. + expect([...(await bytes((w) => encodeAnnounceBroadcast(w, update, v), v))]).toEqual([2, 7, 0, 1, 0, 2, 0, 0xff, 0]); }); test("lite06 ignores a legacy cold price and writes its saturation ceiling", async () => { @@ -876,13 +637,13 @@ test("SYNCED names its Prefix ID and belongs only to lite-07", async () => { }); // Lite-07 answers an edit with an empty message on its Announce Stream: SYNCED carries the -// count's role, and the route layer the Hop ID's. +// count's role, and nothing the Hop ID's. test("ANNOUNCE_OK is an empty Announce Stream message on lite-07", async () => { const v = Version.DRAFT_07; const wire = await bytes((w) => new AnnounceOk(toHop(1n), 7).encode(w, Version.DRAFT_06), Version.DRAFT_06); expect(wire).toEqual(new Uint8Array([2, 1, 7])); await expect(bytes((w) => new AnnounceOk(toHop(1n), 7).encode(w, v), v)).rejects.toThrow(); - expect(await bytes((w) => encodeAnnounceBroadcast(w, { status: "ok" }, v), v)).toEqual(new Uint8Array([17, 0])); + expect(await bytes((w) => encodeAnnounceBroadcast(w, { status: "ok" }, v), v)).toEqual(new Uint8Array([6, 0])); expect(await roundTrip({ status: "ok" }, v)).toEqual({ status: "ok" }); await expect(roundTrip({ status: "ok" }, Version.DRAFT_06)).rejects.toThrow(); }); diff --git a/js/net/src/lite/announce.ts b/js/net/src/lite/announce.ts index 71b6e3e9aa3..ee2b5372ea5 100644 --- a/js/net/src/lite/announce.ts +++ b/js/net/src/lite/announce.ts @@ -4,7 +4,7 @@ import type * as Instance from "../instance.ts"; import * as Path from "../path.ts"; import { encodeVarint, type Reader, type Writer } from "../stream.ts"; import { SEGMENT_BYTES } from "../util/limits.ts"; -import { decodeForwarded, decodeRoute, encodeRoute, utf8 } from "./instance.ts"; +import { decodeRoute, encodeRoute } from "./instance.ts"; import * as Message from "./message.ts"; import { MAX_MESSAGE_SIZE } from "./message.ts"; import { fromWire, toWire } from "./priority.ts"; @@ -12,7 +12,6 @@ import { hasAnnounceCompression, hasAnnounceId, hasAnnounceOk, - hasAnnounceRestart, hasExcludeHop, hasRouteCost, hasRoutes, @@ -32,122 +31,102 @@ const STATUS_UPDATE = 2; const ANNOUNCE_START = 0; const ANNOUNCE_END = 1; const ANNOUNCE_UPDATE = 2; -// lite-07: another publisher instance replaces the advertisement. -const ANNOUNCE_RESTART = 3; +// lite-07: what only two nodes that both declared a Node ID exchange. An endpoint declares none, +// so receiving one is a protocol violation. +const ANNOUNCE_FLOOR = 3; const SYNCED = 4; -// lite-07: the route layer. -const ROUTE_START = 6; -const ROUTE_UPDATE = 7; -const ROUTE_END = 8; -const ANNOUNCE_FLOOR = 9; -const ROUTE_HOLD = 11; -const DEAD = 15; // lite-07: an edit of the prefixes the sender wants, and the marker answering one. -const ANNOUNCE_REQUEST = 16; -const ANNOUNCE_OK = 17; - -// DEAD kinds. -const DEAD_CLOSED = 0n; -const DEAD_DRAIN = 1n; - -/** The largest lite-07 varint. No origin advertises it as a Revision: it leaves room for the - * floor's offset. */ -export const ROUTE_MAX = 2n ** 64n - 1n; +const ANNOUNCE_REQUEST = 5; +const ANNOUNCE_OK = 6; +const ROUTE = 7; +const ROUTE_END = 8; +const DEAD = 9; +const DRAIN = 10; /** Lite-07: copy the first `keep` path segments of the live announcement `distance` back from * the stream's next Announce ID, where 1 is the latest ANNOUNCE_START. Resolved by * {@link AnnounceHistory}. */ export type Base = { distance: bigint; keep: number }; -/** One node a lite-07 route crossed: its Node ID, and the session it learned the route on, an - * opaque per-node counter that is 0 for the publisher's own hop. */ -export interface RouteHop { - node: bigint; - session: bigint; -} +/** The most nodes a lite-07 claim's chain may name: one that would reach 32 is never taken. */ +export const CHAIN_MAX = 31; + +// Claim flags. +const UNAVAILABLE = 0x1; +const DRAINING = 0x2; -/** How a lite-07 publisher reaches a publisher node: the `path` it crossed, the publisher first and - * the sender last, whether a node on it sent GOAWAY, the lowest link priority on it, the sender's - * metric to the publisher, and whether it may only travel away from an upstream. Mirrors - * `route::path::Offer` in rs/moq-net. */ -export interface Offer { - path: RouteHop[]; +/** + * What a lite-07 claim says beside its path and instance. Mirrors `route::relay::Claim` in + * rs/moq-net. + */ +export interface Claim { + /** Which incarnation of the instance this is. */ + epoch: bigint; + /** The sender's cost to the claim's publisher. */ + cost: Cost; + /** How many segments broader the claim is than the path it is presented at. */ + above: bigint; + /** No route reaches the claim from the node that told it: requests for it fail until one does. */ + unavailable: boolean; + /** A node on the way to its publisher sent GOAWAY. */ draining: boolean; + /** The lowest link priority on the way to its publisher. */ priority: number; - metric: bigint; - downOnly: boolean; + /** The Node IDs that announced the claim again across a scoped grant or an older version. */ + chain: bigint[]; } -/** A Route Offer this node refuses: the path it still names, which a later DEAD may match, and why. */ -export interface Unusable { - refused: Refusal; - path: RouteHop[]; +/** A claim this origin publishes itself: no cost, at the top priority, announced again by no one. */ +export function ownClaim(epoch: bigint, above = 0n): Claim { + return { epoch, cost: 0n, above, unavailable: false, draining: false, priority: 127, chain: [] }; } -/** News on DEAD about the routes the sender offered. `closed`: the session `hop` names closed, at - * the node `far` at its other end. The next `moved` messages on the stream are ROUTE_UPDATEs, one - * per route on the stream through that hop that continues on another path, and the receiver - * applies the DEAD and all of them as one. The rest end if `gone`, and are held if not, unless the - * receiver is the node just before the sender on the route's path. `drain`: `node` sent GOAWAY, so - * every path through it ranks as draining. */ -export type Dead = - | { kind: "closed"; hop: RouteHop; far: bigint; gone: boolean; moved: bigint } - | { kind: "drain"; node: bigint }; - -/** The most Hops a route may carry. One that arrives with this many is unusable. */ -export const ROUTE_MAX_HOPS = 32; - -// Route Offer flags. -const DOWN_ONLY = 0x1; -const DRAINING = 0x2; +/** Whether two claims say the same. */ +export function claimsEqual(a: Claim, b: Claim): boolean { + return ( + a.epoch === b.epoch && + a.cost === b.cost && + a.above === b.above && + a.unavailable === b.unavailable && + a.draining === b.draining && + a.priority === b.priority && + a.chain.length === b.chain.length && + a.chain.every((node, i) => node === b.chain[i]) + ); +} /** * A message on the Announce Stream. * - * Lite-07 carries everything one side says about routing on its one unidirectional stream: the - * edits of the prefixes it wants (`request`), and the markers (`ok`), routes, and claims answering - * the prefixes its peer wants. - * - * On lite-06+ these are independently-typed messages (`ANNOUNCE_START`, `ANNOUNCE_END`, - * `ANNOUNCE_UPDATE`, and on lite-07 `ANNOUNCE_RESTART`, `SYNCED`, the ROUTE messages, and - * `ANNOUNCE_FLOOR`), each framed as `Type | Length | Body` like the subscribe stream's responses. - * Each `active` (ANNOUNCE_START) implicitly assigns the next announce id (a per-stream ordinal - * starting at 0), and on lite-07 each `routeStart` the next Route ID; the others reference those - * ids. Older versions send a single ANNOUNCE_BROADCAST message that retracts by path (`ended`). + * Lite-07 carries everything one side says about its claims on its one unidirectional stream: + * the edits of the prefixes it wants (`request`), and the markers (`ok`, `synced`) and claims + * answering the prefixes its peer wants. Two nodes that both declared a Node ID also exchange + * routes there, which an endpoint never sends and refuses to receive. * - * Lite-07 names the route a claim travels under (`route`) in place of a hop chain, so `hops` is - * empty there; every earlier version carries the chain and no route. + * On lite-06+ these are independently-typed messages, each framed as `Type | Length | Body` + * like the subscribe stream's responses. Each ANNOUNCE_START implicitly assigns the next + * announce id (a per-stream ordinal starting at 0); the others reference it. Older versions send + * a single ANNOUNCE_BROADCAST message that retracts by path (`ended`). */ export type AnnounceBroadcast = - /** A broadcast is now available, carrying the path suffix, relative to the requested prefix - * before lite-07 and to the session from it, and (lite-06+) the cost. An absent - * cost encodes as zero; it decodes as `undefined` on a wire with no room for one. Before - * lite-07 it carries the hop chain; on lite-07 the Route ID, the instance and epoch, which - * change only with a `restart`, and a `pathBase` the suffix follows. */ - | { - status: "active"; - suffix: Path.Valid; - route?: bigint; - instance?: Instance.Valid; - epoch?: bigint; - hops?: Hop[]; - cost?: Cost; - /** Lite07+: how many segments broader the claim is than the path it is presented at. */ - above?: bigint; - pathBase?: Base; - } + /** Before lite-07: a broadcast is now available, carrying the path suffix relative to the + * requested prefix, the hop chain, and (lite-06) the cost. An absent cost encodes as zero; it + * decodes as `undefined` on a wire with no room for one. */ + | { status: "active"; suffix: Path.Valid; hops?: Hop[]; cost?: Cost } /** Pre-lite-06: a broadcast is no longer available, retracted by path. */ | { status: "ended"; suffix: Path.Valid } - /** Lite06+: a broadcast is no longer available, retracted by announce id. - * The id is retired; referencing it again is a protocol violation. */ - | { status: "endedId"; id: bigint } - /** Lite06+: atomically replace the metadata of the announcement with this id: its cost, and - * before lite-07 its hop chain. The id stays live. */ - | { status: "update"; id: bigint; hops?: Hop[]; cost?: Cost; above?: bigint } - /** Lite07+: the announcement with this id now serves the instance and epoch given. Another - * instance is another stream, so what the receiver resolved under its prefix is stale; a - * higher epoch of the same one continues it. The id stays live. */ - | { status: "restart"; id: bigint; instance?: Instance.Valid; epoch?: bigint; cost?: Cost; above?: bigint } + /** Lite06+: the claim with this announce id is gone, and the id retired; referencing it again + * is a protocol violation. On lite-07 its publisher withdrew it unless `lost`, when the + * sender only lost its way to it. */ + | { status: "endedId"; id: bigint; lost?: boolean } + /** Lite06 only: atomically replace the hop chain and cost of the announcement with this id. + * The id stays live. */ + | { status: "update"; id: bigint; hops?: Hop[]; cost?: Cost } + /** Lite07+ ANNOUNCE_START: a claim of the broadcast at `suffix`, relative to the session, + * serving `instance`, which assigns it the next announce id. */ + | { status: "start"; suffix: Path.Valid; pathBase?: Base; instance: Instance.Valid; claim: Claim } + /** Lite07+ ANNOUNCE_UPDATE: the claim with this id now stands as `claim`. */ + | { status: "change"; id: bigint; claim: Claim } /** An unknown lite-06+ announce type, skipped by length. Does not assign an id. */ | { status: "skipped" } /** Lite07+ SYNCED: the initial set of the prefix the receiver assigned this Prefix ID has been @@ -158,30 +137,8 @@ export type AnnounceBroadcast = * Prefix ID. With `more`, the edit continues in the next message, and takes effect whole with * its last (see `requestParts`). */ | { status: "request"; more: boolean; remove: bigint[]; add: Add[] } - /** Lite07+ ANNOUNCE_OK: the receiver's last edit takes effect here. */ - | { status: "ok" } - /** Lite07+ ROUTE_START: the publisher reaches the publisher node `node` along `offer`, covering - * the prefix the receiver assigned the Prefix ID `prefix` joined with `suffix`, and assigns the - * route the next Route ID. `exact` marks a route the publisher keeps at its own prefix whatever - * prefix the request lies at, so an edit widening the request past it leaves it there. */ - | { status: "routeStart"; node: bigint; prefix: bigint; suffix: Path.Valid; exact: boolean; offer: Offer } - /** Lite07+ ROUTE_UPDATE: the route with this id changed, and is usable. */ - | { status: "routeUpdate"; id: bigint; offer: Offer } - /** Lite07+ ROUTE_HOLD: the publisher has no usable route with this id, but holds it and its - * claims while it recovers. */ - | { status: "routeHold"; id: bigint } - /** Lite07+ ROUTE_END: the publisher let go of the route with this id and every claim under it. */ - | { status: "routeEnd"; id: bigint } - /** Lite07+ DEAD: a session or node on the routes the publisher offered is gone or going. */ - | { status: "dead"; dead: Dead } - /** Lite07+ ANNOUNCE_FLOOR: closes the batch of claims under the route with this id, certifying - * the stream's claims for it across the requested prefix as the origin's at `revision`, or - * nothing when `revision` is undefined. */ - | { status: "floor"; id: bigint; revision?: bigint } - /** Lite07+: a route message whose content, which the sender only forwarded, this node refuses. - * The receiver withdraws what it names and keeps the session. Decoded only as far as keeps the - * stream's ids in step; never sent. */ - | { status: "refused"; message: Refusable; reason: Refusal }; + /** Lite07+ ANNOUNCE_OK: the receiver's oldest unanswered edit takes effect here. */ + | { status: "ok" }; /** A prefix an ANNOUNCE_REQUEST adds, relative to the session, and whether it also wants the * hidden claims beneath it. */ @@ -190,23 +147,6 @@ export interface Add { hidden: boolean; } -/** What a refused route message still tells the receiver, so the ids that follow it resolve. */ -export type Refusable = - /** ROUTE_START: assigns the next Route ID to the publisher `node`, covering the prefix with the - * Prefix ID `prefix` joined with `suffix`, or no prefix when the suffix itself was refused, - * along `path`, at its own prefix when `exact`. */ - | { kind: "routeStart"; node: bigint; prefix: bigint; suffix?: Path.Valid; exact: boolean; path: RouteHop[] } - /** ROUTE_UPDATE of the route with this Route ID, now along `path`. */ - | { kind: "routeUpdate"; id: bigint; path: RouteHop[] } - /** ANNOUNCE_START under Route ID `route`: assigns the next Announce ID, to `path`, or to no path - * when the path itself was refused. */ - | { kind: "start"; route: bigint; path?: { suffix: Path.Valid; pathBase?: Base } } - /** ANNOUNCE_RESTART of the claim with this Announce ID. */ - | { kind: "change"; id: bigint }; - -/** Why a node refuses content a peer forwarded: well framed, but nothing it can use. */ -export type Refusal = "node" | "flags" | "hops" | "path" | "instance"; - // Both wire rules on a hop chain, applied to what we send and to what we receive: a // chain that revisits a hop looped, so neither forwarding it nor subscribing through it // is safe, and a receiver must end the session over one. `UNKNOWN_HOP` identifies @@ -239,11 +179,6 @@ async function encodeHops(w: Writer, version: Version, hops: Hop[] = []) { await w.u53(hops.length); break; default: - // Lite-07 names a route instead, and JS never offers to read the Lite-06 Chain. - if (hasRoutes(version)) { - if (hops.length > 0) throw new Error("lite-07 claims carry no hop chain"); - break; - } // Lite04+: hop count + individual Hop varints. await w.u53(hops.length); for (const origin of hops) { @@ -279,13 +214,6 @@ async function decodeHops(r: Reader, version: Version): Promise { } } -// The hop chain of an ANNOUNCE_START or ANNOUNCE_UPDATE. Lite-07 names a route instead, and -// carries a trailing Lite-06 Chain only to a peer that offered to read it, which JS never does, -// so any bytes left over are malformed. -async function decodeChain(r: Reader, version: Version): Promise<{ hops?: Hop[] }> { - return hasRoutes(version) ? {} : { hops: await decodeHops(r, version) }; -} - async function encodePath(w: Writer, version: Version, suffix: Path.Valid, base: Base | undefined) { if (hasAnnounceCompression(version)) { await w.u62(base?.distance ?? 0n); @@ -318,18 +246,6 @@ async function encodeRouteCost(w: Writer, version: Version, cost: Cost | undefin if (version === Version.DRAFT_06) await w.u62(MAX_COST); } -// Lite07 follows the cost with how many segments broader the claim is than the path it is -// presented at, so a claim exactly at a path outranks every broader one shown there. Older versions -// carry no such field, and a claim they forward is never broader than its own path. -async function encodeAbove(w: Writer, version: Version, above: bigint | undefined) { - if (hasRoutes(version)) await w.u62(above ?? 0n); - else if (above) throw new Error("a claim above its path needs lite-07"); -} - -async function decodeAbove(r: Reader, version: Version): Promise { - return hasRoutes(version) ? await r.u62() : undefined; -} - async function decodeRouteCost(r: Reader, version: Version): Promise { if (!hasRouteCost(version)) return undefined; const cost = saturate(await r.u62()); @@ -337,78 +253,44 @@ async function decodeRouteCost(r: Reader, version: Version): Promise ROUTE_MAX_HOPS || offer.path.some((hop) => hop.node === 0n)) - throw new Error("no node offers that path"); - await w.u62(BigInt(offer.path.length)); - for (const hop of offer.path) { - await w.u62(hop.node); - await w.u62(hop.session); - } - await w.u8((offer.downOnly ? DOWN_ONLY : 0) | (offer.draining ? DRAINING : 0)); - await w.u8(toWire(offer.priority)); - await w.u62(offer.metric); +/** Encode what a lite-07 claim says after its epoch: cost, above, flags, priority, and chain. */ +async function encodeClaim(w: Writer, claim: Claim) { + if (claim.chain.length > CHAIN_MAX || claim.chain.some((node) => node === 0n)) + throw new Error("no node sends that chain"); + await w.u62(saturate(claim.cost)); + await w.u62(claim.above); + await w.u8((claim.unavailable ? UNAVAILABLE : 0) | (claim.draining ? DRAINING : 0)); + await w.u8(toWire(claim.priority)); + await w.u53(claim.chain.length); + for (const node of claim.chain) await w.u62(node); } -/** Decode a Route Offer. Its path comes first, so a node refusing the rest still learns the path a - * later DEAD may name. An empty path is the sender's own error, since it names itself last. Hops - * past the limit, a hop naming Node ID 0, and a flag this node does not know refuse the offer: a - * newer flag may add a field after the ones this node reads, so a refusal skips the rest of the - * body. Every hop a path counts is read, but of a path past the limit only those up to one past - * it are kept: a sender within the limit never sends one, and the whole would hold a body's - * worth for each route. Mirrors rs/moq-net. */ -async function decodeOffer(r: Reader): Promise { - const count = await r.u62(); - if (count === 0n) throw new ProtocolViolation("a route offer with no hops"); - const path: RouteHop[] = []; - for (let i = 0n; i < count; i++) { - const hop = { node: await r.u62(), session: await r.u62() }; - if (path.length <= ROUTE_MAX_HOPS) path.push(hop); - } - const refuse = async (refused: Refusal): Promise => { - await r.readAll(); - return { refused, path }; - }; - if (count > BigInt(ROUTE_MAX_HOPS)) return refuse("hops"); - if (path.some((hop) => hop.node === 0n)) return refuse("node"); +/** Decode a lite-07 claim of `epoch`. A chain past the limit or naming Node ID 0, and a flag this + * version does not define, fail the stream: no sender builds one. Mirrors rs/moq-net. */ +async function decodeClaim(r: Reader, epoch: bigint): Promise { + // Costs saturate at 2^62-1 on every version, so a larger one reads as the ceiling. + const cost = saturate(await r.u62()); + const above = await r.u62(); const flags = await r.u8(); - if (flags & ~(DOWN_ONLY | DRAINING)) return refuse("flags"); + if (flags & ~(UNAVAILABLE | DRAINING)) throw new ProtocolViolation(`unknown claim flags ${flags}`); const priority = fromWire(await r.u8()); - const metric = await r.u62(); - return { path, draining: (flags & DRAINING) !== 0, priority, metric, downOnly: (flags & DOWN_ONLY) !== 0 }; -} - -async function encodeDead(w: Writer, dead: Dead) { - if (dead.kind === "drain") { - if (dead.node === 0n) throw new Error("Node ID 0 names no node"); - await w.u62(DEAD_DRAIN); - await w.u62(dead.node); - return; - } - if (dead.hop.node === 0n || dead.far === 0n) throw new Error("Node ID 0 names no node"); - await w.u62(DEAD_CLOSED); - await w.u62(dead.hop.node); - await w.u62(dead.hop.session); - await w.u62(dead.far); - await w.u8(dead.gone ? 1 : 0); - await w.u62(dead.moved); -} - -async function decodeDead(r: Reader): Promise { - const nonzero = (id: bigint) => { - if (id === 0n) throw new ProtocolViolation("Node ID 0 names no node"); - return id; + const count = await r.u62(); + if (count > BigInt(CHAIN_MAX)) throw new ProtocolViolation(`claim chain of ${count} nodes`); + const chain: bigint[] = []; + for (let i = 0n; i < count; i++) { + const node = await r.u62(); + if (node === 0n) throw new ProtocolViolation("Node ID 0 names no node"); + chain.push(node); + } + return { + epoch, + cost, + above, + unavailable: (flags & UNAVAILABLE) !== 0, + draining: (flags & DRAINING) !== 0, + priority, + chain, }; - const kind = await r.u62(); - if (kind === DEAD_DRAIN) return { kind: "drain", node: nonzero(await r.u62()) }; - if (kind !== DEAD_CLOSED) throw new ProtocolViolation(`unknown DEAD kind ${kind}`); - const hop = { node: nonzero(await r.u62()), session: await r.u62() }; - const far = nonzero(await r.u62()); - const gone = await r.u8(); - if (gone > 1) throw new ProtocolViolation(`DEAD Gone ${gone}`); - return { kind: "closed", hop, far, gone: gone === 1, moved: await r.u62() }; } /** Encode an ANNOUNCE_REQUEST body: `More`, the Prefix IDs to remove, then the prefixes to add, @@ -509,101 +391,37 @@ export function requestParts( return parts.map((part, i) => ({ status: "request", more: i + 1 < parts.length, ...part })); } -/** Decode a lite-07 suffix: its base, which the sender picked, then the path it forwarded, or - * undefined for a path this node refuses. */ -async function decodeForwardedPath(r: Reader): Promise<{ suffix: Path.Valid; pathBase?: Base } | undefined> { - const distance = await r.u62(); - const keep = await r.u53(); - // A distance of 0 names nothing, so a keep without a base is a violation. - if (distance === 0n && keep !== 0) throw new ProtocolViolation("announce keep without a base"); - const text = utf8(await r.read(await r.u53())); - const suffix = text === undefined ? undefined : Path.tryDecode(text); - if (suffix === undefined) return undefined; - return distance === 0n ? { suffix } : { suffix, pathBase: { distance, keep } }; -} - -/** A lite-07 ANNOUNCE_START: its suffix, Route ID, instance and epoch, and cost. */ -async function decodeStart(r: Reader, version: Version): Promise { - const path = await decodeForwardedPath(r); - const route = await r.u62(); - const refused = async (reason: Refusal): Promise => { - await r.readAll(); - return { status: "refused", message: { kind: "start", route, path }, reason }; - }; - if (!path) return refused("path"); - const { instance, epoch } = await decodeForwarded(r); - if (instance === undefined) return refused("instance"); - const cost = await decodeRouteCost(r, version); - return { status: "active", ...path, route, instance, epoch, cost, above: await decodeAbove(r, version) }; -} - -/** A lite-07 ANNOUNCE_RESTART: its Announce ID, instance and epoch, and cost. */ -async function decodeRestart(r: Reader, version: Version): Promise { - const id = await r.u62(); - const { instance, epoch } = await decodeForwarded(r); - if (instance === undefined) { - await r.readAll(); - return { status: "refused", message: { kind: "change", id }, reason: "instance" }; - } - const cost = await decodeRouteCost(r, version); - return { status: "restart", id, instance, epoch, cost, above: await decodeAbove(r, version) }; -} - // lite-06 message body (no discriminator; the type is carried outside the length prefix). async function encodeAnnounce06Body(w: Writer, msg: AnnounceBroadcast, version: Version) { switch (msg.status) { case "active": - await encodePath(w, version, msg.suffix, msg.pathBase); - if (hasRoutes(version)) { - if (msg.route === undefined) throw new Error("a lite-07 claim names its route"); - await w.u62(msg.route); - } else if (msg.route !== undefined) { - throw new Error("routes not supported for this version"); - } - await encodeRoute(w, version, msg.instance, msg.epoch); + if (hasRoutes(version)) throw new Error("a lite-07 claim names its instance"); + await encodePath(w, version, msg.suffix, undefined); + await encodeRoute(w, version, undefined, undefined); await encodeHops(w, version, msg.hops); await encodeRouteCost(w, version, msg.cost); - await encodeAbove(w, version, msg.above); break; case "endedId": await w.u62(msg.id); + if (hasRoutes(version)) await w.bool(msg.lost ?? false); break; case "update": + if (hasRoutes(version)) throw new Error("a lite-07 update carries its claim"); await w.u62(msg.id); await encodeHops(w, version, msg.hops); await encodeRouteCost(w, version, msg.cost); - await encodeAbove(w, version, msg.above); - break; - case "restart": - await w.u62(msg.id); - await encodeRoute(w, version, msg.instance, msg.epoch); - await encodeRouteCost(w, version, msg.cost); - await encodeAbove(w, version, msg.above); - break; - case "routeStart": - if (msg.node === 0n) throw new Error("Node ID 0 names no origin"); - await w.u62(msg.node); - await w.u62(msg.prefix); - await w.string(Path.encode(msg.suffix)); - await w.bool(msg.exact); - await encodeOffer(w, msg.offer); - break; - case "routeUpdate": - await w.u62(msg.id); - await encodeOffer(w, msg.offer); - break; - case "dead": - await encodeDead(w, msg.dead); break; - case "routeHold": - case "routeEnd": - await w.u62(msg.id); + case "start": + if (!hasRoutes(version)) throw new Error("claims not supported for this version"); + await encodePath(w, version, msg.suffix, msg.pathBase); + await encodeRoute(w, version, msg.instance, msg.claim.epoch); + await encodeClaim(w, msg.claim); break; - case "floor": + case "change": + if (!hasRoutes(version)) throw new Error("claims not supported for this version"); await w.u62(msg.id); - // No origin advertises the last revision, so it never needs the offset. - if (msg.revision !== undefined && msg.revision >= ROUTE_MAX) throw new Error("revision out of range"); - await w.u62(msg.revision === undefined ? 0n : msg.revision + 1n); + await w.u62(msg.claim.epoch); + await encodeClaim(w, msg.claim); break; case "synced": await w.u62(msg.prefix); @@ -617,7 +435,6 @@ async function encodeAnnounce06Body(w: Writer, msg: AnnounceBroadcast, version: // The pre-lite-06 path-form retraction has no place on lite-06. throw new Error("ended-by-path not supported for this version"); case "skipped": - case "refused": throw new Error("decode-only announce type cannot be encoded"); } } @@ -626,41 +443,25 @@ async function encodeAnnounce06Body(w: Writer, msg: AnnounceBroadcast, version: function announce06Type(msg: AnnounceBroadcast, version: Version): number { switch (msg.status) { case "active": + case "start": return ANNOUNCE_START; case "endedId": return ANNOUNCE_END; case "update": + case "change": return ANNOUNCE_UPDATE; - case "restart": - // Older versions send an end and a start instead. - if (!hasAnnounceRestart(version)) throw new Error("announce restart not supported for this version"); - return ANNOUNCE_RESTART; case "synced": if (!hasSynced(version)) throw new Error("synced not supported for this version"); return SYNCED; case "request": + if (!hasRoutes(version)) throw new Error("announce edits not supported for this version"); + return ANNOUNCE_REQUEST; case "ok": - case "routeStart": - case "routeUpdate": - case "routeHold": - case "routeEnd": - case "dead": - case "floor": - if (!hasRoutes(version)) throw new Error("routes not supported for this version"); - return { - request: ANNOUNCE_REQUEST, - ok: ANNOUNCE_OK, - routeStart: ROUTE_START, - routeUpdate: ROUTE_UPDATE, - routeHold: ROUTE_HOLD, - routeEnd: ROUTE_END, - dead: DEAD, - floor: ANNOUNCE_FLOOR, - }[msg.status]; + if (!hasRoutes(version)) throw new Error("announce edits not supported for this version"); + return ANNOUNCE_OK; case "ended": throw new Error("ended-by-path not supported for this version"); case "skipped": - case "refused": throw new Error("decode-only announce type cannot be encoded"); } } @@ -668,13 +469,26 @@ function announce06Type(msg: AnnounceBroadcast, version: Version): number { async function decodeAnnounce06Body(r: Reader, typ: number, version: Version): Promise { switch (typ) { case ANNOUNCE_START: { - // Lite-07's claims carry what the sender forwarded, which a receiver may refuse. - if (hasRoutes(version)) return decodeStart(r, version); const path = await decodePath(r, version); - const route = hasRoutes(version) ? { route: await r.u62() } : {}; const served = await decodeRoute(r, version); - const hops = await decodeChain(r, version); - return { status: "active", ...path, ...route, ...served, ...hops, cost: await decodeRouteCost(r, version) }; + if (hasRoutes(version)) { + // Every lite-07 claim names its instance. + if (served.instance === undefined) throw new ProtocolViolation("a claim without an instance"); + const claim = await decodeClaim(r, served.epoch ?? 0n); + return { status: "start", ...path, instance: served.instance, claim }; + } + const hops = await decodeHops(r, version); + return { status: "active", suffix: path.suffix, hops, cost: await decodeRouteCost(r, version) }; + } + case ANNOUNCE_END: { + const id = await r.u62(); + return hasRoutes(version) ? { status: "endedId", id, lost: await r.bool() } : { status: "endedId", id }; + } + case ANNOUNCE_UPDATE: { + const id = await r.u62(); + if (hasRoutes(version)) return { status: "change", id, claim: await decodeClaim(r, await r.u62()) }; + const hops = await decodeHops(r, version); + return { status: "update", id, hops, cost: await decodeRouteCost(r, version) }; } case SYNCED: if (!hasSynced(version)) break; @@ -685,67 +499,14 @@ async function decodeAnnounce06Body(r: Reader, typ: number, version: Version): P case ANNOUNCE_OK: if (!hasRoutes(version)) break; return { status: "ok" }; - case ANNOUNCE_END: - return { status: "endedId", id: await r.u62() }; - case ANNOUNCE_UPDATE: { - const id = await r.u62(); - const hops = await decodeChain(r, version); - const cost = await decodeRouteCost(r, version); - return { status: "update", id, ...hops, cost, above: await decodeAbove(r, version) }; - } - case ANNOUNCE_RESTART: { - // Unknown before lite-07: skipped below like any other. - if (!hasAnnounceRestart(version)) break; - if (hasRoutes(version)) return decodeRestart(r, version); - const id = await r.u62(); - const served = await decodeRoute(r, version); - return { status: "restart", id, ...served, cost: await decodeRouteCost(r, version) }; - } - case ROUTE_START: { - if (!hasRoutes(version)) break; - const node = await r.u62(); - const prefix = await r.u62(); - // The suffix is sized, so the offer's path reads even when it is refused. - const text = utf8(await r.read(await r.u53())); - const suffix = text === undefined ? undefined : Path.tryDecode(text); - const exact = await r.bool(); - const offer = await decodeOffer(r); - if (node !== 0n && suffix !== undefined && !("refused" in offer)) - return { status: "routeStart", node, prefix, suffix, exact, offer }; - const reason = node === 0n ? "node" : suffix === undefined ? "path" : (offer as Unusable).refused; - return { - status: "refused", - message: { kind: "routeStart", node, prefix, suffix, exact, path: offer.path }, - reason, - }; - } - case ROUTE_UPDATE: { - if (!hasRoutes(version)) break; - const id = await r.u62(); - const offer = await decodeOffer(r); - if ("refused" in offer) - return { - status: "refused", - message: { kind: "routeUpdate", id, path: offer.path }, - reason: offer.refused, - }; - return { status: "routeUpdate", id, offer }; - } - case DEAD: - if (!hasRoutes(version)) break; - return { status: "dead", dead: await decodeDead(r) }; - case ROUTE_HOLD: - if (!hasRoutes(version)) break; - return { status: "routeHold", id: await r.u62() }; + case ANNOUNCE_FLOOR: + case ROUTE: case ROUTE_END: + case DEAD: + case DRAIN: if (!hasRoutes(version)) break; - return { status: "routeEnd", id: await r.u62() }; - case ANNOUNCE_FLOOR: { - if (!hasRoutes(version)) break; - const id = await r.u62(); - const revision = await r.u62(); - return revision === 0n ? { status: "floor", id } : { status: "floor", id, revision: revision - 1n }; - } + // Only two nodes that both declared a Node ID exchange routes, and this one declares none. + throw new ProtocolViolation(`route message ${typ} to a node that declared no Node ID`); } // Skip the length-prefixed body so an earlier Lite06 build negotiating // the same ALPN does not kill the announce stream. @@ -757,8 +518,6 @@ async function decodeAnnounce06Body(r: Reader, typ: number, version: Version): P async function encodeLegacyBody(w: Writer, msg: AnnounceBroadcast, version: Version) { switch (msg.status) { case "active": - if (msg.pathBase) throw new Error("announce compression not supported for this version"); - if (msg.route !== undefined) throw new Error("routes not supported for this version"); await w.u8(STATUS_ACTIVE); await w.string(Path.encode(msg.suffix)); await encodeHops(w, version, msg.hops); @@ -819,8 +578,8 @@ export async function decodeAnnounceBroadcastMaybe( } /** - * The live announcements on one lite-06+ announce stream, by Announce ID: what ANNOUNCE_END, - * ANNOUNCE_UPDATE, and ANNOUNCE_RESTART reference, and what a lite-07 base copies from. Every + * The live announcements on one lite-06+ announce stream, by Announce ID: what ANNOUNCE_END + * and ANNOUNCE_UPDATE reference, and what a lite-07 base copies from. Every * violation throws {@link ProtocolViolation}. */ export class AnnounceHistory { @@ -865,21 +624,13 @@ export class AnnounceHistory { return Path.tryDecode(kept.join("/")); } - /** The suffix of the live announcement `id`, which an update or restart references. */ + /** The suffix of the live announcement `id`, which an update references. */ get(id: bigint): Path.Valid { const live = this.#live.get(id); if (live === undefined) throw new ProtocolViolation(`unknown announce id: ${id}`); return live; } - /** Assign the next id to `path` with no ANNOUNCE_START, as an edit does for a claim it presents - * at a prefix below its own. */ - insert(path: Path.Valid): bigint { - const id = this.#next++; - this.#live.set(id, path); - return id; - } - /** An ANNOUNCE_END: retire the id, returning its suffix, or undefined if it was refused. */ end(id: bigint): Path.Valid | undefined { if (this.#refused.delete(id)) return undefined; diff --git a/js/net/src/lite/answer.ts b/js/net/src/lite/answer.ts index 722188f4105..e3b3ecfd7cf 100644 --- a/js/net/src/lite/answer.ts +++ b/js/net/src/lite/answer.ts @@ -1,22 +1,19 @@ // Lite-07: what this session sends on its Announce Stream as a publisher, answering the prefixes -// the peer asks for from this origin's own route. +// the peer asks for from this origin's own claims. // -// A browser forwards nothing, so each requested prefix carries at most one route, this origin's, -// and only while it shows the peer one of its claims. The peer edits its prefixes in place: each -// edit takes effect at the ANNOUNCE_OK answering it, where both ends carry the stream's routes -// over alike (`rekey.plan`), and the answer then sends only what the carried routes lack. Mirrors -// `publisher/routed.rs` in rs/moq-net for a node that does not proxy. +// A browser forwards nothing and declares no Node ID, so it sends claims and never routes: one +// per broadcast the peer is shown, at no cost. The peer edits its prefixes in place: each edit +// takes effect at the ANNOUNCE_OK answering it, where both ends drop every claim within a prefix +// it removed, and the answer then tells what the added prefixes cover. import { type GetPromise, type Getter, race } from "@moq/signals"; import type { Grant } from "../auth.ts"; import { ProtocolViolation } from "../error.ts"; -import { routesEqual, type WireRoute } from "../hop.ts"; import { coveringPrefixes, hiddenBelow, presented } from "../internal.ts"; import * as Path from "../path.ts"; import { type Advertised, type Advertisements, type OriginConsumer, sameInstance } from "../wire.ts"; -import { type Add, type AnnounceBroadcast, type Offer, requestFits } from "./announce.ts"; +import { type Add, type AnnounceBroadcast, type Claim, claimsEqual, ownClaim, requestFits } from "./announce.ts"; import type { AnnounceStream } from "./announce_stream.ts"; -import * as rekey from "./rekey.ts"; import type { Version } from "./version.ts"; /** What the session answers its peer from. */ @@ -24,8 +21,8 @@ export interface Publish { version: Version; /** The origin's claims, or undefined once it closed. */ advertised: Getter; - /** The origin's route identity and scope, when the session publishes one. */ - origin?: Pick; + /** The origin's scope, when the session publishes one. */ + origin?: Pick; /** Our grant: only what it lets us publish is announced. */ grant?: Getter; /** Resolves once the tokens this session presented at setup are answered, so nothing is @@ -42,37 +39,27 @@ interface Prefix { hidden: boolean; } -/** The route the peer holds for a requested prefix: from the first claim shown until the last one goes. */ +/** A claim the peer holds: its Announce ID, the broadcast it serves, and what it was sent. */ interface Sent { id: bigint; - node: bigint; - /** Whether its last floor certified, so a grant change alone floors it again. Undefined until - * its first floor, and once an edit widened it. */ - certified?: boolean; - /** The claims the peer holds, by path. */ - live: Map; + snap: Advertised; + claim: Claim; } -// What the peer decodes for a claim: lite-07 carries its instance, epoch, and cost. -const onWire = (route: WireRoute): WireRoute => ({ ...route, auth: undefined }); -const restarted = (prev: Advertised, next: Advertised): boolean => - !sameInstance(prev, next) || (prev.route.epoch ?? 0n) !== (next.route.epoch ?? 0n); - /** Answers the prefixes a lite-07 peer asks for. @internal */ export class Answer { #publish: Publish; /** The prefixes in effect, by Prefix ID. */ #prefixes = new Map(); #nextPrefix = 0n; - /** The peer's edit not put in effect yet. */ + /** The peer's edit not answered yet. */ #request?: { remove: bigint[]; add: [bigint, Prefix][] }; /** The ANNOUNCE_REQUESTs of an edit that continues: its removes and its adds so far. */ #parts?: { remove: bigint[]; add: Add[] }; - /** The route the peer holds for each requested prefix. */ - #routes = new Map(); - #nextRoute = 0n; + /** The claims the peer holds, by their path from the session's root. */ + #live = new Map(); #nextAnnounce = 0n; - /** The session is leaving: every route was ended, and nothing more is sent. */ + /** The session is leaving: nothing more is sent. */ #withdrawn = false; #closed = false; @@ -104,17 +91,19 @@ export class Answer { request(more: boolean, remove: bigint[], add: Add[]): Promise { this.#running ??= this.#run(); if (this.#withdrawn || this.#closed) return this.#running; - // The peer sends one edit at a time. + // One edit at a time, so a peer that never reads its answers leaves one here beside the + // one being answered. if (this.#request) throw new ProtocolViolation("ANNOUNCE_REQUEST before the last was answered"); if (this.#parts) { remove = [...this.#parts.remove, ...remove]; add = [...this.#parts.add, ...add]; this.#parts = undefined; } + const left = new Map(this.#prefixes); // Parts that could never make a valid edit fail before more of them pile up: their Adds // alone already pass the set's limit, or they remove more than the set holds. if ( - remove.length > this.#prefixes.size || + remove.length > left.size || !requestFits( add.map(({ prefix }) => prefix), this.#publish.version, @@ -125,7 +114,6 @@ export class Answer { this.#parts = { remove, add }; return this.#running; } - const left = new Map(this.#prefixes); for (const id of remove) { if (!left.delete(id)) throw new ProtocolViolation(`ANNOUNCE_REQUEST removes unknown Prefix ID ${id}`); } @@ -157,21 +145,30 @@ export class Answer { } async #run(): Promise { - const { advertised, grant, origin, closing, ready } = this.#publish; - // Woken by the origin's claims, our grant, or the identity they are originated under. - const stops = [advertised, grant, origin?.own.identity].map((source) => source?.subscribe(() => this.#poke())); + const { advertised, grant, closing, ready } = this.#publish; + // Woken by the origin's claims or our grant. + const stops = [advertised, grant].map((source) => source?.subscribe(() => this.#poke())); try { const settled = ready.then(() => "ready" as const); if ((await race([settled, closing])) !== "ready") return; for (;;) { if (this.#closed) return; - if (closing.peek()) return await this.#withdraw(); - if (this.#request) { - await this.#edit(this.#request); + // The session is leaving: finishing the stream ends everything the peer was sent. + if (closing.peek()) { + this.#withdrawn = true; + this.#live.clear(); + return; + } + const request = this.#request; + if (request) { + // Let go before its answer is written: the peer may send its next edit the + // moment it reads the answer, which can be before the write returns here. + this.#request = undefined; + await this.#edit(request); continue; } if (this.#dirty) { - await this.#syncAll(); + await this.#sync(); continue; } const woke = new Promise((resolve) => { @@ -185,203 +182,87 @@ export class Answer { } } - // The session is leaving: end every route, so the peer lets go of them before the stream finishes. - async #withdraw() { - this.#withdrawn = true; - const ids = [...this.#routes.values()].map((sent) => sent.id).sort((a, b) => (a < b ? -1 : 1)); - this.#routes.clear(); - if (ids.length > 0) await this.#publish.stream.send(...ids.map((id) => ({ status: "routeEnd", id }) as const)); - } - - // Put the peer's request in effect: answer it, carry the routes it holds over, send what they - // lack, and close each added prefix's initial set. + // Put the peer's request in effect: answer it, drop what the removed prefixes covered, tell + // what the added ones cover, and close each added prefix's initial set. async #edit(request: { remove: bigint[]; add: [bigint, Prefix][] }) { - const old = new Set(); - for (const prefix of this.#prefixes.values()) old.add(prefix.path); - for (const id of request.remove) this.#prefixes.delete(id); - const added: Path.Valid[] = []; - for (const [id, prefix] of request.add) { - this.#prefixes.set(id, prefix); - added.push(prefix.path); + const removed: Path.Valid[] = []; + for (const id of request.remove) { + const prefix = this.#prefixes.get(id); + if (prefix) removed.push(prefix.path); + this.#prefixes.delete(id); + } + // Both ends drop every claim the removed prefixes covered. + for (const path of [...this.#live.keys()]) { + if (removed.some((prefix) => Path.hasPrefix(prefix, path))) this.#live.delete(path); } - const next = new Set(); - for (const prefix of this.#prefixes.values()) next.add(prefix.path); - this.#rekey(old, next, added); + for (const [id, prefix] of request.add) this.#prefixes.set(id, prefix); - // The peer may send its next edit once this is on its way, and not before. - const answered = this.#publish.stream.send({ status: "ok" }); - this.#request = undefined; - await answered; - await this.#syncAll(); - // Every route the peer holds in an added prefix has its floor by now. + await this.#publish.stream.send({ status: "ok" }); + await this.#sync(); const synced = request.add.map(([prefix]) => ({ status: "synced", prefix }) as const); if (synced.length > 0) await this.#publish.stream.send(...synced); } - // Carry the routes and claims the peer holds over an edit of the prefixes from `old` to - // `next`, as the peer does at the ANNOUNCE_OK. - #rekey(old: Set, next: Set, added: Path.Valid[]) { - const table = new Map(); - const sources = new Map(); - const snaps = new Map(); - // Every route here is this origin's own along one offer, so they rank alike whoever the peer is. - const order = rekey.order(false, this.#offer(), this.#offer().path, 0n); - for (const [prefix, sent] of this.#routes) { - const claims = new Map(); - for (const [path, { id, snap }] of sent.live) { - claims.set(path, id); - snaps.set(id, snap); - } - table.set(sent.id, { node: sent.node, prefix, region: prefix, exact: false, order, claims }); - sources.set(sent.id, sent); - } - const plan = rekey.plan(old, next, added, table, this.#nextRoute, this.#nextAnnounce); - this.#routes = new Map(); - for (const carried of plan.routes) { - const source = sources.get(carried.from); - if (!source) throw new Error("a carried route's source"); - const live = new Map(); - for (const [path, claim] of carried.claims) { - const from = snaps.get(claim.from); - if (!from) throw new Error("a carried claim's state"); - // A claim now covering a narrower prefix from above is that much more above it. - const snap = - claim.lowered > 0n - ? { ...from, route: { ...from.route, above: (from.route.above ?? 0n) + claim.lowered } } - : from; - live.set(path, { id: claim.id, snap }); - } - this.#routes.set(carried.prefix, { - id: carried.id, - node: source.node, - // A widened route certifies nothing until its next floor. - certified: carried.kind === "widens" ? undefined : source.certified, - live, - }); - } - this.#nextRoute = plan.nextRoute; - this.#nextAnnounce = plan.nextClaim; - } - - // The origin's own route: a path of its own hop alone, learned on no session, at the top - // priority and no cost. It forwards no other. Mirrors the origin's offer in rs/moq-net. - #offer(): Offer { - const origin = this.#publish.origin; - return { - path: origin ? [{ node: origin.own.hop, session: 0n }] : [], - draining: false, - priority: 127, - metric: 0n, - downOnly: false, - }; - } - - async #syncAll() { + // Bring the claims the peer holds in line with the origin's. + async #sync() { this.#dirty = false; - const ids = [...this.#prefixes.keys()].sort((a, b) => (a < b ? -1 : 1)); - for (const id of ids) { - const prefix = this.#prefixes.get(id); - if (!prefix) continue; - const msgs = this.#sync(id, prefix); - if (msgs.length > 0) await this.#publish.stream.send(...msgs); - } + const msgs = this.#changes(); + if (msgs.length > 0) await this.#publish.stream.send(...msgs); } - // Bring the peer's view of one requested prefix in line with the origin's: one batch of claim - // changes, closed by its floor, ending the route once it shows nothing. - #sync(id: bigint, prefix: Prefix): AnnounceBroadcast[] { + // How the claims the peer holds differ from what the requested prefixes show it now. + #changes(): AnnounceBroadcast[] { const { advertised, origin } = this.#publish; - const msgs: AnnounceBroadcast[] = []; - // Read together, so the floor certifies exactly the claims it closes. - const table = advertised.peek(); - const identity = origin?.own.identity.peek(); - const revision = origin?.own.revision(); + const table = origin ? advertised.peek() : undefined; const grant = this.#publish.grant?.peek(); - // The claims the peer is shown, by their path from the session's root: the table under the + // The claims the peer is shown, by their path from the session's root: the table under each // prefix, less the hidden ones it did not ask for and whatever our grant does not let us - // publish. + // publish, which is kept apart to tell a claim it no longer covers from one that ended. const latest = new Map(); - if (table && identity) { + const ungranted = new Set(); + const ids = [...this.#prefixes.keys()].sort((a, b) => (a < b ? -1 : 1)); + for (const id of table ? ids : []) { + const prefix = this.#prefixes.get(id); + if (!prefix || !table) continue; const carries = (covered: Path.Valid) => prefix.hidden || !hiddenBelow(prefix.path, covered); // A claim covering the prefix from above keeps how many segments broader than it it is. for (const [suffix, snap] of presented(prefix.path, table, carries, true)) { const path = Path.join(prefix.path, suffix); if (!grant || grant.publish.matches(path)) latest.set(path, snap); + else ungranted.add(path); } } - // Whether a floor may certify the whole requested prefix: nothing the handle's scope or our - // grant leaves out lies beneath it, since the peer cannot tell what was left out from what - // is gone. A hidden claim left out does not count: the peer did not ask to see it. - const certifies = - (!grant || grant.publish.contains(Path.Pattern.subtree(prefix.path))) && - (origin?.covers(prefix.path) ?? true); - // End the route on the wire: it retires every claim under it. - const end = () => { - const sent = this.#routes.get(prefix.path); - if (!sent) return; - this.#routes.delete(prefix.path); - msgs.push({ status: "routeEnd", id: sent.id }); + const msgs: AnnounceBroadcast[] = []; + const end = (path: Path.Valid, sent: Sent, lost: boolean) => { + this.#live.delete(path); + console.debug(`announce: broadcast=${path} active=false lost=${lost}`); + msgs.push({ status: "endedId", id: sent.id, lost }); }; - - // A rotated identity ends the old route with every claim under it. - if (this.#routes.get(prefix.path)?.node !== identity?.node) end(); - if (!identity) return msgs; - - let route = this.#routes.get(prefix.path); - let changed = false; - for (const [path, live] of [...(route?.live ?? [])]) { - if (latest.has(path)) continue; - route?.live.delete(path); - changed = true; - console.debug(`announce: broadcast=${path} active=false`); - msgs.push({ status: "endedId", id: live.id }); + for (const [path, sent] of [...this.#live]) { + // No longer granted, it is lost to the peer: its publisher never ended it. + if (!latest.has(path)) end(path, sent, ungranted.has(path)); } for (const [path, snap] of latest) { - const prev = route?.live.get(path); - if (prev && !restarted(prev.snap, snap) && routesEqual(onWire(prev.snap.route), onWire(snap.route))) { - continue; - } - changed = true; - if (!route) { - route = { id: this.#nextRoute++, node: identity.node, live: new Map() }; - this.#routes.set(prefix.path, route); - // The origin's own route covers every path, so the requested prefix too, from above - // it: not exact. - msgs.push({ - status: "routeStart", - node: identity.node, - prefix: id, - suffix: Path.empty(), - exact: false, - offer: this.#offer(), - }); - } const { instance, epoch, cost } = snap.route; - // How much broader the claim is than the path it is presented at. - const above = snap.route.above ?? 0n; - if (!prev) { - const claim = this.#nextAnnounce++; - route.live.set(path, { id: claim, snap }); + if (instance === undefined) continue; + const claim = { ...ownClaim(epoch ?? 0n, snap.route.above ?? 0n), cost }; + const sent = this.#live.get(path); + if (!sent || !sameInstance(sent.snap, snap)) { + this.#live.set(path, { id: this.#nextAnnounce++, snap, claim }); console.debug(`announce: broadcast=${path} active=true instance=${instance}`); // Every claim's path is relative to the session, whichever prefix it answers. - msgs.push({ status: "active", suffix: path, route: route.id, instance, epoch, cost, above }); - } else if (restarted(prev.snap, snap)) { - route.live.set(path, { id: prev.id, snap }); - console.debug(`announce: broadcast=${path} restart=true instance=${instance} epoch=${epoch}`); - msgs.push({ status: "restart", id: prev.id, instance, epoch, cost, above }); + msgs.push({ status: "start", suffix: path, instance, claim }); + // Another instance is another claim, started before the one it replaces ends, so + // the peer sees the broadcast restart rather than go. + if (sent) msgs.push({ status: "endedId", id: sent.id, lost: false }); + } else if (!claimsEqual(sent.claim, claim)) { + this.#live.set(path, { id: sent.id, snap, claim }); + msgs.push({ status: "change", id: sent.id, claim }); } else { - route.live.set(path, { id: prev.id, snap }); - msgs.push({ status: "update", id: prev.id, cost, above }); + sent.snap = snap; } } - if (!route) return msgs; - if (changed || route.certified !== certifies) { - route.certified = certifies; - msgs.push({ status: "floor", id: route.id, revision: certifies ? revision : undefined }); - } - // A route an edit carried over with nothing to show ends like one whose last claim went. - if (route.live.size === 0) end(); return msgs; } } diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 37685e6d53a..67f8b862251 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -1145,16 +1145,6 @@ for (const [name, violate] of [ }); }, ], - [ - "a DEAD moving a route the stream never started", - async (pair) => { - const { send } = await announceStream(pair); - await send({ - status: "dead", - dead: { kind: "closed", hop: { node: 2n, session: 1n }, far: 3n, gone: false, moved: 1n }, - }); - }, - ], [ "an ANNOUNCE_OK answering no ANNOUNCE_REQUEST", async (pair) => { diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index 65dbdad3d27..49c08ef2ae9 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -8,17 +8,16 @@ import type { Session } from "../connection/session.ts"; import { detect, type Probe, type Stats, statsOf, type TransportStats, transportStats } from "../connection/stats.ts"; import { type Transport, transportOf } from "../connection/transport.ts"; import { closeError, error, fromClose, ProtocolViolation, StreamCode, sessionCause } from "../error.ts"; -import { type Hop, randomHop, toHop } from "../hop.ts"; +import { type Hop, randomHop } from "../hop.ts"; import { IMPLEMENTATION } from "../implementation.ts"; import { hooks } from "../internal.ts"; import { lines } from "../open.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; -import type { Own } from "../route.ts"; import { type Reader, Readers, Stream, Writer } from "../stream.ts"; import { Observed } from "../util/observed.ts"; import { withTimeout } from "../util/timeout.ts"; -import { registerWire, wireOf } from "../wire.ts"; +import { registerWire } from "../wire.ts"; import { type AnnounceBroadcast, AnnounceRequest, decodeAnnounceBroadcastMaybe } from "./announce.ts"; import { AnnounceStream } from "./announce_stream.ts"; import { LiteAuthWire } from "./auth.ts"; @@ -28,7 +27,6 @@ import { Fetch } from "./fetch.ts"; import { Goaway } from "./goaway.ts"; import { Group } from "./group.ts"; import { Publisher } from "./publisher.ts"; -import { proveRouteKey } from "./route_key.ts"; import { SessionInfo } from "./session.ts"; import { hasClientParameters, ProbeLevel, type Role, Setup } from "./setup.ts"; import { DataType, StreamId } from "./stream.ts"; @@ -43,7 +41,6 @@ import { hasGoaway, hasHidden, hasProbeRtt, - hasRouteKey, hasRoutes, hasSetupStream, hasTrackStream, @@ -115,8 +112,6 @@ export class Connection implements Session { // Module for contributing tracks. #publisher: Publisher; - // The lite-07 route identity our published claims are originated under, if we publish. - #own?: Own; // Module for distributing tracks. #subscriber: Subscriber; @@ -219,8 +214,7 @@ export class Connection implements Session { // Opens waiting for credit make room after about this RTT when the transport has none. lines(quic).probe = this.#probe; - this.#own = publish && wireOf(publish).own; - this.hop = hasRoutes(version) && this.#own ? toHop(this.#own.hop) : randomHop(); + this.hop = randomHop(); // What the peer's connection credential earns by default: publishing anything to us, // since we consume on demand, and subscribing to whatever we publish. this.#auth = new AuthSession({ @@ -289,8 +283,6 @@ export class Connection implements Session { if (!hasSetupStream(version)) this.#peerImplementation.resolve(undefined); registerWire(this, { consume: (path, instance) => this.#subscriber.consume(path, instance), - covers: (node, at, path) => this.#subscriber.covers(node, at, path), - coverage: this.#subscriber.coverage, exclusive: false, leave: () => this.#leave(), auth: this.#auth, @@ -458,20 +450,18 @@ export class Connection implements Session { // Role stays Both: the publish origin starts empty and fills later, and consume is // called after this point, so there is nothing to narrow yet. Before lite-07 the hop // declares our session identity so the peer can filter reflected announcements - // (lite-06 removed ANNOUNCE_REQUEST's exclude_hop for it). From lite-07 the parameter - // is the Node ID our published claims originate under, omitted when we publish nothing. + // (lite-06 removed ANNOUNCE_REQUEST's exclude_hop for it). Lite-07 sends none: only a node + // that forwards declares a Node ID. async #sendSetup(): Promise { const writer = await Writer.open(this.#quic, { version: this.#version }); try { await writer.u53(DataType.Setup); const probe = await probeLevel(this.#quic, this.#version); - const routeKey = hasRouteKey(this.#version) ? await proveRouteKey(this.#quic, this.#client) : undefined; await new Setup({ probe, - hop: hasRoutes(this.#version) ? this.#own && toHop(this.#own.node) : this.hop, + hop: this.hop, token: this.#token, implementation: this.#implementation, - routeKey, }).encode(writer, this.#version); writer.close(); } catch (err: unknown) { diff --git a/js/net/src/lite/corpus.test.ts b/js/net/src/lite/corpus.test.ts index 0196bacb115..f73e1686c39 100644 --- a/js/net/src/lite/corpus.test.ts +++ b/js/net/src/lite/corpus.test.ts @@ -20,7 +20,7 @@ interface Case { budget?: number; /** `client_setup`: the one version the server accepts. */ server?: string; - expect: "decoded" | "refused" | "withdrawn"; + expect: "decoded" | "refused"; } const VERSIONS = new Map(Object.values(Version).map((v) => [versionName(v), v])); @@ -32,11 +32,10 @@ function version(name: string): Version { } // Decode `r` the way a session does, returning how to encode what it decoded. -async function decode(c: Case, r: Reader, v: Version): Promise<((w: Writer) => Promise) | "withdrawn"> { +async function decode(c: Case, r: Reader, v: Version): Promise<(w: Writer) => Promise> { switch (c.message) { case "announce": { const msg = await decodeAnnounceBroadcast(r, v); - if (msg.status === "refused") return "withdrawn"; return (w) => encodeAnnounceBroadcast(w, msg, v); } case "announce_init": { @@ -59,7 +58,7 @@ async function decode(c: Case, r: Reader, v: Version): Promise<((w: Writer) => P async function outcome(c: Case): Promise { const v = version(c.version); const r = new Reader(undefined, Buffer.from(c.hex, "hex"), v); - let encode: ((w: Writer) => Promise) | "withdrawn"; + let encode: (w: Writer) => Promise; try { encode = await decode(c, r, v); } catch (err) { @@ -67,7 +66,6 @@ async function outcome(c: Case): Promise { return err instanceof UnexpectedEnd && !isDecodeError(err) ? "short" : "refused"; } if (!(await r.done())) return "left bytes"; - if (encode === "withdrawn") return encode; return Buffer.from(await Writer.collect(v, encode)).toString("hex"); } @@ -77,8 +75,24 @@ test("the corpus has cases", () => { expect(cases.length).toBeGreaterThan(0); }); +// The lite-07 Announce Stream types only two nodes that both declared a Node ID exchange. This +// node declares none, so it refuses them all, where a routing node decodes the well-formed ones. +const ROUTING = new Set([3, 7, 8, 9, 10]); + +function routing(c: Case): boolean { + return ( + c.message === "announce" && + version(c.version) === Version.DRAFT_07 && + ROUTING.has(Number.parseInt(c.hex.slice(0, 2), 16)) + ); +} + for (const c of cases) { test(c.name, async () => { + if (routing(c)) { + expect(await outcome(c)).toBe("refused"); + return; + } expect(await outcome(c)).toBe(c.expect === "decoded" ? c.hex : c.expect); }); } diff --git a/js/net/src/lite/datagram.test.ts b/js/net/src/lite/datagram.test.ts index 0e4313b3d71..eee1f3c22ea 100644 --- a/js/net/src/lite/datagram.test.ts +++ b/js/net/src/lite/datagram.test.ts @@ -59,8 +59,8 @@ test("lite-07 datagram requests match Rust's size-prefixed fields", async () => const { Timescale } = await import("../time.ts"); const request = new Datagrams({ id: 7n, broadcast: Path.from("room/alice"), track: "audio", priority: -3 }); const body = await Writer.collect(Version.DRAFT_07, (writer) => request.encode(writer, Version.DRAFT_07)); - // Id, broadcast, an empty unminted pin, Node ID 0, Route Depth 0, track, priority. - expect([...body]).toEqual([23, 7, 10, ...enc.encode("room/alice"), 0, 0, 0, 0, 5, ...enc.encode("audio"), 125]); + // Id, broadcast, an empty unminted pin, no node named, track, priority. + expect([...body]).toEqual([22, 7, 10, ...enc.encode("room/alice"), 0, 0, 0, 5, ...enc.encode("audio"), 125]); const decoded = await Datagrams.decode(new Reader(undefined, body, Version.DRAFT_07), Version.DRAFT_07); expect(decoded).toEqual(request); for (const timescale of [undefined, Timescale.MILLI]) { diff --git a/js/net/src/lite/datagram.ts b/js/net/src/lite/datagram.ts index 9eb86b57bd3..bfe19b09017 100644 --- a/js/net/src/lite/datagram.ts +++ b/js/net/src/lite/datagram.ts @@ -100,10 +100,6 @@ export class Datagrams { broadcast: Path.Valid; /** The publisher instance the subscriber expects. */ instance?: Instance.Valid; - /** The publisher node that serves the request, 0 for whichever the publisher selects. Lite-07+. */ - node: bigint; - /** How many leading segments of `broadcast` make up the prefix of the route it follows. Lite-07+. */ - depth: number; /** The datagram track's name. */ track: string; /** The subscriber priority, higher first. */ @@ -113,14 +109,10 @@ export class Datagrams { id: bigint; broadcast: Path.Valid; instance?: Instance.Valid; - node?: bigint; - depth?: number; track: string; priority: number; }) { this.instance = properties.instance; - this.node = properties.node ?? 0n; - this.depth = properties.depth ?? 0; this.id = properties.id; this.broadcast = properties.broadcast; this.track = properties.track; @@ -134,7 +126,7 @@ export class Datagrams { await w.u62(this.id); await w.string(Path.encode(this.broadcast)); await encodePin(w, version, this.instance); - await encodeNode(w, version, this.node, this.depth); + await encodeNode(w, version); await w.string(this.track); await w.u8(toWire(this.priority)); }); @@ -147,13 +139,11 @@ export class Datagrams { const id = await r.u62(); const broadcast = Path.decode(await r.string()); const instance = await decodePin(r, version); - const { node, depth } = await decodeNode(r, version, broadcast); + await decodeNode(r, version); return new Datagrams({ id, broadcast, instance, - node, - depth, track: await r.string(), priority: fromWire(await r.u8()), }); diff --git a/js/net/src/lite/fetch.test.ts b/js/net/src/lite/fetch.test.ts index 7ad10d9c6c1..498f6611faa 100644 --- a/js/net/src/lite/fetch.test.ts +++ b/js/net/src/lite/fetch.test.ts @@ -82,8 +82,7 @@ test("Fetch decodes the optional delay offset before converting to milliseconds" await w.string("room/1"); await w.u53(0); // no instance pin: empty and unminted await w.bool(false); - await w.u62(0n); // no origin node - await w.u53(0); // nor route depth + await w.u62(0n); // no node named await w.string("video"); await w.u8(0); await w.u62(delay + 1n); diff --git a/js/net/src/lite/fetch.ts b/js/net/src/lite/fetch.ts index 8d9e223b426..d7fd21f6538 100644 --- a/js/net/src/lite/fetch.ts +++ b/js/net/src/lite/fetch.ts @@ -21,10 +21,6 @@ export class Fetch { broadcast: Path.Valid; /** The publisher instance the subscriber expects. Lite-07+. */ instance?: Instance.Valid; - /** The publisher node that serves the request, 0 for whichever the publisher selects. Lite-07+. */ - node: bigint; - /** How many leading segments of `broadcast` make up the prefix of the route it follows. Lite-07+. */ - depth: number; track: string; priority: number; /** Reader freshness budget in whole milliseconds. Lite-07+ only; omission leaves the publisher's max age as the only bound. */ @@ -43,8 +39,6 @@ export class Fetch { constructor({ broadcast, instance, - node = 0n, - depth = 0, track, priority, maxDelay, @@ -54,8 +48,6 @@ export class Fetch { }: { broadcast: Path.Valid; instance?: Instance.Valid; - node?: bigint; - depth?: number; track: string; priority: number; maxDelay?: number; @@ -65,8 +57,6 @@ export class Fetch { }) { this.broadcast = broadcast; this.instance = instance; - this.node = node; - this.depth = depth; this.track = track; this.priority = priority; this.maxDelay = maxDelay; @@ -78,7 +68,7 @@ export class Fetch { async #encode(w: Writer, version: Version) { await w.string(Path.encode(this.broadcast)); await encodePin(w, version, this.instance); - await encodeNode(w, version, this.node, this.depth); + await encodeNode(w, version); await w.string(this.track); await w.u8(toWire(this.priority)); if (hasFetchMaxDelay(version)) await Duration.encodeOptional(w, this.maxDelay); @@ -97,14 +87,14 @@ export class Fetch { static async #decode(r: Reader, version: Version): Promise { const broadcast = Path.decode(await r.string()); const instance = await decodePin(r, version); - const { node, depth } = await decodeNode(r, version, broadcast); + await decodeNode(r, version); const track = await r.string(); const priority = fromWire(await r.u8()); const maxDelay = hasFetchMaxDelay(version) ? await Duration.decodeOptional(r) : undefined; const group = await r.u62(); if (!hasFrameBounds(version)) { - return new Fetch({ broadcast, instance, node, depth, track, priority, maxDelay, group }); + return new Fetch({ broadcast, instance, track, priority, maxDelay, group }); } const startFrame = await r.u53(); @@ -116,8 +106,6 @@ export class Fetch { return new Fetch({ broadcast, instance, - node, - depth, track, priority, maxDelay, diff --git a/js/net/src/lite/floors.test.ts b/js/net/src/lite/floors.test.ts deleted file mode 100644 index de7dcdff51c..00000000000 --- a/js/net/src/lite/floors.test.ts +++ /dev/null @@ -1,134 +0,0 @@ -import { expect, test } from "bun:test"; -import * as Instance from "../instance.ts"; -import * as Path from "../path.ts"; -import { type Claim, Floors, type View } from "./floors.ts"; - -const NODE = 7n; -const A: Claim = { instance: Instance.parse("a"), epoch: 0n, cost: 0n, above: 0n }; - -function carrier(prefix: string, revision: bigint | undefined, claims: [string, Claim][], hidden = false) { - const view: View = { - prefix: Path.from(prefix), - hidden, - revision, - claims: new Map(claims.map(([path, claim]) => [Path.from(path), claim])), - }; - return { view, reshow: () => {} }; -} - -test("a newer floor decides a claim only where its request certifies it", () => { - const floors = new Floors(); - // Behind, and asking for hidden claims too. - const lagging = carrier( - "", - 0n, - [ - ["live/x", A], - ["live/.h", A], - ], - true, - ); - // Newer, without hidden claims: it withdrew live/x and says nothing of live/.h. - const newer = carrier("", 1n, []); - floors.join(NODE, lagging); - floors.join(NODE, newer); - expect(floors.shows(NODE, lagging.view, Path.from("live/x"))).toBeUndefined(); - expect(floors.shows(NODE, lagging.view, Path.from("live/.h"))).toBeDefined(); -}); - -test("a claim presented at a stream's own prefix matches the newer view's claim above it", () => { - const floors = new Floors(); - // Asking for live/a, it is shown the claim at live there. - const narrow = carrier("live/a", 0n, [["live/a", A]]); - const wide = carrier("", 1n, [["live", A]]); - floors.join(NODE, narrow); - floors.join(NODE, wide); - expect(floors.shows(NODE, narrow.view, Path.from("live/a"))).toBeDefined(); -}); - -test("a covering claim presented at a stream's prefix keeps how far above it is", () => { - const floors = new Floors(); - const narrow = carrier("live/a/b", 0n, [["live/a/b", A]]); - const wide = carrier("", 1n, [["live", A]]); - floors.join(NODE, narrow); - floors.join(NODE, wide); - expect(floors.shows(NODE, narrow.view, Path.from("live/a/b"))?.above).toBe(2n); - // A claim exactly at the prefix is not above it. - const exact = carrier("", 2n, [["live/a/b", A]]); - floors.join(NODE, exact); - expect(floors.shows(NODE, narrow.view, Path.from("live/a/b"))?.above).toBe(0n); -}); - -test("a claim's distance counts segments the way a path splits them, never at an escaped slash", () => { - const floors = new Floors(); - // An escaped slash is content: room, `a\/b`, cam. - const path = Path.from("room/a\\/b/cam"); - const narrow = carrier(path, 0n, [[path, A]]); - const wide = carrier("", 1n, [["room", A]]); - floors.join(NODE, narrow); - floors.join(NODE, wide); - expect(Path.parts(path)).toHaveLength(3); - expect(floors.shows(NODE, narrow.view, path)?.above).toBe(2n); -}); - -test("an uncertified claim stands until a floor certifies its path", () => { - const floors = new Floors(); - const loose = carrier("", undefined, [ - ["live/x", A], - ["other", A], - ]); - const scoped = carrier("live", 3n, []); - floors.join(NODE, loose); - expect(floors.shows(NODE, loose.view, Path.from("live/x"))).toBeDefined(); - floors.join(NODE, scoped); - expect(floors.shows(NODE, loose.view, Path.from("live/x"))).toBeUndefined(); - expect(floors.shows(NODE, loose.view, Path.from("other"))).toBeDefined(); -}); - -test("a shown claim takes the newest certifying view's cost", () => { - const floors = new Floors(); - const lagging = carrier("", 0n, [["live/x", A]]); - const newer = carrier("", 1n, [["live/x", { ...A, cost: 100n }]]); - floors.join(NODE, lagging); - floors.join(NODE, newer); - expect(floors.shows(NODE, lagging.view, Path.from("live/x"))?.cost).toBe(100n); -}); - -test("a regressed route's certified view decides only while a live floor certifies the path", () => { - const floors = new Floors(); - const view = { - prefix: Path.empty(), - hidden: false, - revision: 1n as bigint | undefined, - claims: new Map([[Path.from("live/x"), A]]), - }; - const route = { view, reshow: () => {} }; - floors.join(NODE, route); - // Its next floor certifies nothing and adds live/y: no floor certifies live/y now. - floors.regress(NODE, route); - view.revision = undefined; - view.claims.set(Path.from("live/y"), A); - expect(floors.shows(NODE, route.view, Path.from("live/y"))).toBeDefined(); - // A lagging stream at revision 0 carries live/y too: the kept revision 1 says it does not exist. - const lagging = carrier("", 0n, [["live/y", A]]); - floors.join(NODE, lagging); - expect(floors.shows(NODE, lagging.view, Path.from("live/y"))).toBeUndefined(); -}); - -test("a route that leaves or floors reshows only the routes whose prefix meets its own", () => { - const floors = new Floors(); - const reshown: string[] = []; - const route = (prefix: string) => { - const { view } = carrier(prefix, 1n, [[`${prefix}/x`, A]]); - return { view, reshow: () => reshown.push(prefix) }; - }; - const routes = ["live/a", "live/a/b", "live", "live/c"].map(route); - for (const r of routes) floors.join(NODE, r); - - floors.floor(NODE, routes[0]); - expect(reshown.sort()).toEqual(["live", "live/a/b"]); - - reshown.length = 0; - floors.leave(NODE, routes[3]); - expect(reshown).toEqual(["live"]); -}); diff --git a/js/net/src/lite/floors.ts b/js/net/src/lite/floors.ts deleted file mode 100644 index a54bb01b289..00000000000 --- a/js/net/src/lite/floors.ts +++ /dev/null @@ -1,231 +0,0 @@ -import type { Cost } from "../hop.ts"; -import type * as Instance from "../instance.ts"; -import { coveringPrefixes, hiddenBelow } from "../internal.ts"; -import * as Path from "../path.ts"; - -/** - * A claim as an announce stream carries it: the instance, its epoch, the origin's cost, and how - * many segments broader the claim is than the path it is presented at (`above`), so a claim - * exactly at a path outranks every broader one shown there. @internal - */ -export type Claim = { instance: Instance.Valid; epoch: bigint; cost: Cost; above: bigint }; - -/** - * One announce stream's claims for a route, as its last floor left them. `revision` is the - * origin's revision that floor certified them at, or undefined when it certified nothing. - * @internal - */ -export interface View { - readonly prefix: Path.Valid; - // Whether the request asked for hidden claims: one that did not certifies nothing about them. - readonly hidden: boolean; - readonly revision: bigint | undefined; - readonly claims: ReadonlyMap; -} - -/** A route on one announce stream, whose claims another stream's floor may hide. @internal */ -export interface Carrier { - readonly view: View; - /** Show or hide each of its claims anew, once another stream's floor moved what is current. */ - reshow(): void; -} - -type Node = { carriers: Set; retained: View[] }; - -// Whether `view` certifies whether a claim at `path` exists. -function certifies(view: View, path: Path.Valid): boolean { - return ( - view.revision !== undefined && - Path.hasPrefix(view.prefix, path) && - (view.hidden || !hiddenBelow(view.prefix, path)) - ); -} - -// Whether `view` certifies every path `other` does, at a revision at least as new. -function supersedes(view: View, other: View): boolean { - return ( - view.revision !== undefined && - other.revision !== undefined && - view.revision >= other.revision && - Path.hasPrefix(view.prefix, other.prefix) && - (view.hidden || (!other.hidden && !hiddenBelow(view.prefix, other.prefix))) - ); -} - -// Whether two prefixes overlap: one lies within the other. -function meets(a: Path.Valid, b: Path.Valid): boolean { - return Path.hasPrefix(a, b) || Path.hasPrefix(b, a); -} - -// The claim `view` presents at `path`: exactly there, or with `covering`, at the requesting -// stream's own prefix, the most specific claim at or above it within the view, which keeps how far -// above the path it is. As `covering` in rs/moq-net's `route/view.rs`. -function presented(view: View, path: Path.Valid, covering: boolean): Claim | undefined { - if (!covering) return view.claims.get(path); - let by = 0n; - for (const at of coveringPrefixes(path)) { - if (!Path.hasPrefix(view.prefix, at)) return undefined; - const found = view.claims.get(at); - if (found) return by === 0n ? found : { ...found, above: found.above + by }; - by++; - } - return undefined; -} - -/** - * What a session's announce streams certify of each origin node's claims (lite-07). - * - * Several streams may carry one origin's claims, each answering its own prefix and applying its - * batches at its own floors, so one can lag another. Of the views whose floor certifies a claim, - * the one with the highest revision decides whether it exists, and a claim no floor certifies - * exists while some stream carries it. A route that ends, or whose floor stops certifying or goes - * back, leaves what its last floor certified, so an older floor never revives a claim a newer one - * withdrew; that knowledge counts while a live floor still certifies the path. Mirrors `route/view.rs`'s merge in - * rs/moq-net, held per session since a node that forwards nothing merges only for its own reads. - * @internal - */ -export class Floors { - #nodes = new Map(); - - /** Start tracking a route to `node`. */ - join(node: bigint, carrier: Carrier): void { - let entry = this.#nodes.get(node); - if (!entry) { - entry = { carriers: new Set(), retained: [] }; - this.#nodes.set(node, entry); - } - entry.carriers.add(carrier); - } - - /** - * The route ended or its stream closed. What its floor certified stays while another route to - * the node may still carry a claim it decides; the last route takes the node's state with it. - * Every other route to the node whose prefix meets this one's is shown anew, since a path this - * one alone certified now shows what its streams carry; a route's claims lie within its prefix, - * so no other route's can change, and a session closing many prefixes costs each only its own. - */ - leave(node: bigint, carrier: Carrier): void { - const entry = this.#nodes.get(node); - if (!entry?.carriers.delete(carrier)) return; - if (entry.carriers.size === 0) { - this.#nodes.delete(node); - return; - } - // The route's own state is gone with it, so its claims need no copy. - const { prefix, hidden, revision, claims } = carrier.view; - if (revision !== undefined) entry.retained.push({ prefix, hidden, revision, claims }); - this.#prune(entry); - for (const other of entry.carriers) if (meets(other.view.prefix, prefix)) other.reshow(); - } - - /** - * A route to `node` is about to apply a floor that certifies nothing, or an older revision. - * What its current floor certified stays, as an ended route's does, since no floor withdraws - * what a newer one said. Call it before the batch changes the route's view. - */ - regress(node: bigint, carrier: Carrier): void { - const entry = this.#nodes.get(node); - const { prefix, hidden, revision, claims } = carrier.view; - if (!entry?.carriers.has(carrier) || revision === undefined) return; - entry.retained.push({ prefix, hidden, revision, claims: new Map(claims) }); - } - - /** - * A route to `node` applied a batch at its floor: every other route to it whose prefix meets - * this one's is shown anew, as in `leave`. Returns whether any other view of the node existed, - * in which case the route's own unchanged claims may have changed state too, even if this floor - * pruned it. - */ - floor(node: bigint, carrier: Carrier): boolean { - const entry = this.#nodes.get(node); - if (!entry) return false; - const retained = entry.retained.length; - this.#prune(entry); - if (entry.carriers.size === 1 && retained === 0) return false; - const prefix = carrier.view.prefix; - for (const other of entry.carriers) if (other !== carrier && meets(other.view.prefix, prefix)) other.reshow(); - return true; - } - - /** - * The claim `view` shows at `path`, under a route to `node`: its own when no view certifies the - * path, or else the newest certifying view's, so its cost is current, when that one presents the - * same instance and epoch there. Undefined when the claim does not exist. - */ - shows(node: bigint, view: View, path: Path.Valid): Claim | undefined { - const claim = view.claims.get(path); - if (!claim) return undefined; - const best = this.#newest(node, view, path); - if (best === undefined || best === view) return claim; - const theirs = presented(best, path, path === view.prefix); - if (theirs?.instance !== claim.instance || theirs.epoch !== claim.epoch) return undefined; - return theirs; - } - - /** - * What the newest view certifying `path`, as `shows` picks it for `view`, says of a claim - * there: "absent" when it presents none, "present" when it does, or undefined when none - * certifies the path. - */ - certified(node: bigint, view: View, path: Path.Valid): "absent" | "present" | undefined { - const best = this.#newest(node, view, path); - if (best === undefined) return undefined; - return presented(best, path, path === view.prefix) === undefined ? "absent" : "present"; - } - - // The newest view certifying `path` for `view`, under a route to `node`, or undefined when none does. - #newest(node: bigint, view: View, path: Path.Valid): View | undefined { - const entry = this.#nodes.get(node); - // The view itself wins a tie: one revision presents the same claims on every stream. - let best: View | undefined = certifies(view, path) ? view : undefined; - const consider = (other: View) => { - if (!certifies(other, path)) return; - // biome-ignore lint/style/noNonNullAssertion: certifies() checked both revisions. - if (best === undefined || other.revision! > best.revision!) best = other; - }; - for (const other of entry?.carriers ?? []) consider(other.view); - // What an ended or regressed floor said counts only where a live one still certifies, as - // Rust's router prunes a merged region no certifier certifies any more. - if (best !== undefined) for (const other of entry?.retained ?? []) consider(other); - return best; - } - - /** - * Whether a claim of `node` at `at` may serve a consume of `path` below it. The newest view - * certifying `path`, the most specific of those alike, certifies what covers it there: a claim - * above that view's region is older knowledge, as `covering` in rs/moq-net's `route/view.rs`. - */ - covers(node: bigint, at: Path.Valid, path: Path.Valid): boolean { - const entry = this.#nodes.get(node); - if (!entry || at === path) return true; - let best: View | undefined; - const consider = (view: View) => { - if (!certifies(view, path)) return; - if ( - best === undefined || - // biome-ignore lint/style/noNonNullAssertion: certifies() checked both revisions. - view.revision! > best.revision! || - (view.revision === best.revision && view.prefix.length > best.prefix.length) - ) - best = view; - }; - for (const carrier of entry.carriers) consider(carrier.view); - // As in shows(): a retained view counts only where a live floor still certifies. - if (best !== undefined) for (const view of entry.retained) consider(view); - return best === undefined || Path.hasPrefix(best.prefix, at); - } - - // Drop each retained view that decides no claim a route holds: one another view supersedes, or - // one no certifying route's prefix meets. Of two alike, the later stays, so each prefix the session - // requested keeps at most two: one for the hidden claims, one for the rest. - #prune(entry: Node): void { - const live = [...entry.carriers].map((carrier) => carrier.view); - const retained = entry.retained; - entry.retained = retained.filter( - (view, i) => - live.some((other) => other.revision !== undefined && meets(other.prefix, view.prefix)) && - !live.some((other) => supersedes(other, view)) && - !retained.some((other, j) => j !== i && supersedes(other, view) && (j > i || !supersedes(view, other))), - ); - } -} diff --git a/js/net/src/lite/instance.ts b/js/net/src/lite/instance.ts index f64b03fdcd9..64314d68ada 100644 --- a/js/net/src/lite/instance.ts +++ b/js/net/src/lite/instance.ts @@ -1,7 +1,5 @@ -import { ProtocolViolation } from "../error.ts"; import * as Instance from "../instance.ts"; import * as Mint from "../mint.ts"; -import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import { hasInstance, hasRoutes, type Version } from "./version.ts"; @@ -29,31 +27,18 @@ export async function decodePin(r: Reader, version: Version): Promise { - if (!hasRoutes(version)) return; - // A route needs its publisher. - if (node === 0n && depth !== 0) throw new Error("a route depth without its node"); - await w.u62(node); - await w.u53(depth); +/** Encode the forwarding node a request names. An endpoint knows none, so it always sends Node + * ID 0, which lets the publisher select one. Only lite-07 carries it. Mirrors rs/moq-net. */ +export async function encodeNode(w: Writer, version: Version): Promise { + if (hasRoutes(version)) await w.u62(0n); } -/** Decode the publisher node a request for `broadcast` names, and its route's depth; see - * {@link encodeNode}. A depth past the path's segments names no prefix of it. */ -export async function decodeNode( - r: Reader, - version: Version, - broadcast: Path.Valid, -): Promise<{ node: bigint; depth: number }> { - if (!hasRoutes(version)) return { node: 0n, depth: 0 }; - const node = await r.u62(); - const depth = await r.u53(); - if ((node === 0n && depth !== 0) || depth > Path.parts(broadcast).length) - throw new ProtocolViolation(`route depth ${depth} names no prefix of ${broadcast}`); - return { node, depth }; +/** Decode the forwarding node a request names: a Node ID, and the node's start unless the ID is + * 0. An endpoint forwards nothing, so whichever node the request names, it serves the request + * itself. */ +export async function decodeNode(r: Reader, version: Version): Promise { + if (!hasRoutes(version)) return; + if ((await r.u62()) !== 0n) await r.u62(); } /** Encode the instance, its minted flag, and the epoch an announcement serves. Every route @@ -85,28 +70,6 @@ async function encode(w: Writer, instance: Instance.Valid): Promise { await w.bool(Instance.isMinted(instance)); } -/** Decode lite-07's instance and epoch, with `instance` undefined when they are well framed but - * the instance is not one this node can use, which withdraws only the claim naming it. Mirrors - * rs/moq-net. */ -export async function decodeForwarded(r: Reader): Promise<{ instance?: Instance.Valid; epoch: bigint }> { - const bytes = await r.read(await r.u53()); - const minted = await r.bool(); - const epoch = await r.u62(); - const text = utf8(bytes); - if (text === undefined || text.length === 0 || !text.isWellFormed()) return { epoch }; - const named = Instance.parse(text); - return { instance: minted ? Mint.mint(named) : named, epoch }; -} - -/** `bytes` as UTF-8 text, or undefined when they are not UTF-8. */ -export function utf8(bytes: Uint8Array): string | undefined { - try { - return decoder.decode(bytes); - } catch { - return undefined; - } -} - function decode(bytes: Uint8Array, minted: boolean): Instance.Valid { const named = Instance.parse(decoder.decode(bytes)); return minted ? Mint.mint(named) : named; diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 393e3637b9b..b245fd0c7f2 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -18,7 +18,7 @@ import { Reader, Readers, Stream, Writer, writeBudget } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; import { Subscriber as TrackSubscriber } from "../track.ts"; import { wireOf } from "../wire.ts"; -import { type AnnounceBroadcast, AnnounceRequest, decodeAnnounceBroadcast } from "./announce.ts"; +import { type AnnounceBroadcast, AnnounceRequest, decodeAnnounceBroadcast, ownClaim } from "./announce.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; import { Probe as ProbeMessage } from "./probe.ts"; @@ -3624,10 +3624,8 @@ test("lite-07 SYNCED survives an initial removal and continuous earlier-prefix c events.push(event); if (event.status === "synced") break; } - // The route, its claims, and their floor, then SYNCED. - expect(events[0]).toMatchObject({ status: "routeStart" }); - expect(events).toContainEqual(expect.objectContaining({ status: "active", suffix: "z/retained" })); - expect(events.at(-2)).toMatchObject({ status: "floor", id: 0n }); + // The claim that outlived the removal, then SYNCED. + expect(events).toContainEqual(expect.objectContaining({ status: "start", suffix: "z/retained" })); expect(events.at(-1)).toEqual({ status: "synced", prefix: 0n }); expect(events).not.toContainEqual(expect.objectContaining({ suffix: "z/removed" })); } finally { @@ -3822,8 +3820,6 @@ function routedAnswer(origin: OriginProducer, grant?: Signal, publisher.request(false, [], [{ prefix, hidden: false }]); const next = async () => decodeAnnounceBroadcast(await reader, version); return { - node: wireOf(origin.consume()).own.node, - hop: wireOf(origin.consume()).own.hop, publisher, next, // The next ANNOUNCE_REQUEST, as the session hands the publisher each one the peer sends. @@ -3844,58 +3840,25 @@ function routedAnswer(origin: OriginProducer, grant?: Signal, }; } -test("a lite-07 answer carries this origin's claims under its own route", async () => { +test("a lite-07 answer carries this origin's claims", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("cam")); - const { node, hop, next, ok, close } = routedAnswer(origin); - // The origin's own route covers every path, along its own hop alone, at the top priority. - const offer = { - path: [{ node: hop, session: 0n }], - draining: false, - priority: 127, - metric: 0n, - downOnly: false, - }; + const { next, ok, close } = routedAnswer(origin); try { await ok(); - expect(await next()).toEqual({ - status: "routeStart", - node, - prefix: 0n, - suffix: Path.empty(), - exact: false, - offer, - }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 0n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: 0n }); + // An endpoint sends claims and never a route: each at no cost, at the top priority. + expect(await next()).toMatchObject({ status: "start", suffix: "cam", claim: ownClaim(0n) }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); - // Each change is a batch closed by the next revision. const mic = publish(origin, Path.from("mic")); - expect(await next()).toMatchObject({ status: "active", suffix: "mic", route: 0n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: 1n }); + expect(await next()).toMatchObject({ status: "start", suffix: "mic" }); cam.close(); - expect(await next()).toEqual({ status: "endedId", id: 0n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: 2n }); - - // The last claim withdrawn ends the route after its batch. + expect(await next()).toEqual({ status: "endedId", id: 0n, lost: false }); mic.close(); - expect(await next()).toEqual({ status: "endedId", id: 1n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: 3n }); - expect(await next()).toEqual({ status: "routeEnd", id: 0n }); + expect(await next()).toEqual({ status: "endedId", id: 1n, lost: false }); - // The next claim starts the route again at once, under the next Route ID: no echo waits. const again = publish(origin, Path.from("again")); - expect(await next()).toEqual({ - status: "routeStart", - node, - prefix: 0n, - suffix: Path.empty(), - exact: false, - offer, - }); - expect(await next()).toMatchObject({ status: "active", suffix: "again", route: 1n }); - expect(await next()).toMatchObject({ status: "floor", id: 1n }); + expect(await next()).toMatchObject({ status: "start", suffix: "again" }); again.close(); } finally { close(); @@ -3903,22 +3866,24 @@ test("a lite-07 answer carries this origin's claims under its own route", async } }); -// Another broadcast at the path, without an instance, is another instance: one batch under the -// route, closed by its floor. -test("a lite-07 republish restarts the claim", async () => { +// Another broadcast at the path, without an instance, is another instance, so another claim: +// started before the one it replaces ends, so the peer sees the broadcast restart. +test("a lite-07 republish starts the next claim before ending the last", async () => { const origin = new OriginProducer(); const old = publish(origin, Path.from("cam")); const { next, ok, close } = routedAnswer(origin); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart" }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); + const first = await next(); + expect(first).toMatchObject({ status: "start", suffix: "cam" }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); const republished = publish(origin, Path.from("cam")); - expect(await next()).toMatchObject({ status: "restart", id: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); + const second = await next(); + expect(second).toMatchObject({ status: "start", suffix: "cam" }); + if (first.status !== "start" || second.status !== "start") throw new Error("two claims"); + expect(second.instance).not.toBe(first.instance); + expect(await next()).toEqual({ status: "endedId", id: 0n, lost: false }); republished.close(); } finally { old.close(); @@ -3927,35 +3892,30 @@ test("a lite-07 republish restarts the claim", async () => { } }); -// The peer edits the prefixes it asks for one ANNOUNCE_REQUEST at a time. Each added prefix takes -// the next Prefix ID, its route names it, and its paths are the session's, whatever the prefix. +// The peer edits the prefixes it asks for. Each added prefix takes the next Prefix ID, and its +// claims' paths are the session's, whatever the prefix. test("a lite-07 edit answers each added prefix under its own Prefix ID", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("a/cam")); const mic = publish(origin, Path.from("b/mic")); - const { node, next, ok, request, close } = routedAnswer(origin, undefined, Path.from("a")); + const { next, ok, request, close } = routedAnswer(origin, undefined, Path.from("a")); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart", node, prefix: 0n, suffix: "" }); - expect(await next()).toMatchObject({ status: "active", suffix: "a/cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); + expect(await next()).toMatchObject({ status: "start", suffix: "a/cam" }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); - // Adding `b` leaves the route for `a` as it stands: nothing of it is sent again. + // Adding `b` leaves what `a` covers as it stands: nothing of it is sent again. request([], [Path.from("b")]); await ok(); - expect(await next()).toMatchObject({ status: "routeStart", node, prefix: 1n, suffix: "" }); - expect(await next()).toMatchObject({ status: "active", suffix: "b/mic", route: 1n }); - expect(await next()).toMatchObject({ status: "floor", id: 1n }); + expect(await next()).toMatchObject({ status: "start", suffix: "b/mic" }); expect(await next()).toEqual({ status: "synced", prefix: 1n }); - // Removing `a` ends its route with the answer, which names nothing: both ends drop it there. + // Removing `a` drops its claims with the answer, which names nothing: both ends drop them there. request([0n], []); await ok(); cam.close(); const late = publish(origin, Path.from("b/late")); - expect(await next()).toMatchObject({ status: "active", suffix: "b/late", route: 1n }); - expect(await next()).toMatchObject({ status: "floor", id: 1n }); + expect(await next()).toMatchObject({ status: "start", suffix: "b/late" }); late.close(); } finally { cam.close(); @@ -3965,52 +3925,45 @@ test("a lite-07 edit answers each added prefix under its own Prefix ID", async ( } }); -// An edit swapping two prefixes for the one covering both re-sends nothing both sets cover: the -// routes widen at the answer on both ends, each keeping its Route ID and its claims but the one -// at its own old prefix, and the publisher sends only a floor for each. -test("a lite-07 swap edit re-sends nothing both sets cover", async () => { +// An edit swapping one prefix for another drops every claim within the one it removes, on both +// ends, and tells again what the one it adds covers, under the next Announce IDs. +test("a lite-07 swap edit tells again what the added prefix covers", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("room/a/cam")); const mic = publish(origin, Path.from("room/b/mic")); const { next, ok, request, close } = routedAnswer(origin, undefined, Path.from("room/a")); + const until = async () => { + const msgs: AnnounceBroadcast[] = []; + for (;;) { + const msg = await next(); + msgs.push(msg); + if (msg.status === "synced") return msgs; + } + }; try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart", prefix: 0n }); - expect(await next()).toMatchObject({ status: "active", suffix: "room/a/cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); - expect(await next()).toEqual({ status: "synced", prefix: 0n }); + expect(await until()).toMatchObject([ + { status: "start", suffix: "room/a/cam" }, + { status: "synced", prefix: 0n }, + ]); - // `room` covers `room/a`: the route widens, and only what it lacks follows the answer. request([0n], [Path.from("room")]); await ok(); - const widened: AnnounceBroadcast[] = []; - for (;;) { - const msg = await next(); - widened.push(msg); - if (msg.status === "synced") break; - } - expect(widened).toMatchObject([ - { status: "active", suffix: "room/b/mic", route: 0n }, - { status: "floor", id: 0n }, + expect(await until()).toMatchObject([ + { status: "start", suffix: "room/a/cam" }, + { status: "start", suffix: "room/b/mic" }, { status: "synced", prefix: 1n }, ]); - // Back to `room/a`: the route narrows under the next Route ID, its claim there carried - // over with what its floor certified, and the claim outside it dropped on both ends. request([1n], [Path.from("room/a")]); await ok(); - const narrowed: AnnounceBroadcast[] = []; - for (;;) { - const msg = await next(); - narrowed.push(msg); - if (msg.status === "synced") break; - } - expect(narrowed).toEqual([{ status: "synced", prefix: 2n }]); - // The carried claim kept its Announce ID, under the route's new one. + expect(await until()).toMatchObject([ + { status: "start", suffix: "room/a/cam" }, + { status: "synced", prefix: 2n }, + ]); + // The claim told last holds the fourth Announce ID. cam.close(); - expect(await next()).toEqual({ status: "endedId", id: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 1n }); - expect(await next()).toEqual({ status: "routeEnd", id: 1n }); + expect(await next()).toEqual({ status: "endedId", id: 3n, lost: false }); } finally { cam.close(); mic.close(); @@ -4045,10 +3998,17 @@ test("a lite-07 edit the peer may not send is a violation", async () => { nested.request([0n], [Path.from("a")]); await nested.ok(); expect(await nested.next()).toEqual({ status: "synced", prefix: 1n }); - // A second edit before the first is answered. + // A second edit before the first is answered, whole or the first part of one: a peer + // that never reads its answers leaves one edit here. const early = await answer("a"); early.request([], [Path.from("b")]); expect(() => early.request([], [Path.from("c")])).toThrow(ProtocolViolation); + expect(() => early.publisher.request(true, [], [])).toThrow(ProtocolViolation); + await early.ok(); + expect(await early.next()).toEqual({ status: "synced", prefix: 1n }); + early.request([1n], [Path.from("c")]); + await early.ok(); + expect(await early.next()).toEqual({ status: "synced", prefix: 2n }); // A set past what one message holds. const large = await answer("a"); const long = (i: number) => Path.from(`${String(i).padStart(4, "0")}/${"x".repeat(1000)}`); @@ -4064,51 +4024,22 @@ test("a lite-07 edit the peer may not send is a violation", async () => { } }); -// A rotated identity, which only an exhausted revision space forces, ends the route with every -// claim under it, and starts the new one at once. -test("a lite-07 rotated identity ends the route and starts the next", async () => { - const origin = new OriginProducer(); - const cam = publish(origin, Path.from("cam")); - const { node, next, ok, close } = routedAnswer(origin); - const own = wireOf(origin.consume()).own; - try { - await ok(); - expect(await next()).toMatchObject({ status: "routeStart", node }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); - expect(await next()).toEqual({ status: "synced", prefix: 0n }); - - own.rotate(); - expect(own.node).not.toBe(node); - expect(await next()).toEqual({ status: "routeEnd", id: 0n }); - expect(await next()).toMatchObject({ status: "routeStart", node: own.node }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 1n }); - expect(await next()).toMatchObject({ status: "floor", id: 1n }); - } finally { - cam.close(); - close(); - origin.close(); - } -}); - -// A floor certifies the requested prefix only while the grant covers all of it, so a grant -// change that flips that re-floors the route even when it shows the same claims. -test("a lite-07 grant change alone re-floors the route", async () => { +// A claim our grant no longer lets us publish is lost to the peer, since its publisher never +// ended it, and is told again once the grant covers it. +test("a lite-07 grant change loses and tells again the claims it moves", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("a/x")); const grant = new Signal(grantOf("a/x")); const { next, ok, close } = routedAnswer(origin, grant); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart" }); - expect(await next()).toMatchObject({ status: "active", suffix: "a/x", route: 0n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: undefined }); + expect(await next()).toMatchObject({ status: "start", suffix: "a/x" }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); - grant.set({ ...grantOf("a/x"), publish: new Path.Patterns([Path.Pattern.subtree(Path.empty())]) }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: 0n }); + grant.set(grantOf("b")); + expect(await next()).toEqual({ status: "endedId", id: 0n, lost: true }); grant.set(grantOf("a/x")); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: undefined }); + expect(await next()).toMatchObject({ status: "start", suffix: "a/x" }); } finally { cam.close(); close(); @@ -4116,21 +4047,16 @@ test("a lite-07 grant change alone re-floors the route", async () => { } }); -// A request prefix that fits the wire alone may overflow once joined to the handle's root: -// nothing the scope allows lies there, so the floor certifies nothing rather than failing. The -// claim at room covers more than was asked for, so it is presented at the requested prefix. -test("a lite-07 request beyond the scope's path limits floors uncertified", async () => { +// A claim covering more than was asked for is presented at the requested prefix, that many +// segments above it. +test("a lite-07 claim above the requested prefix is presented at it", async () => { const origin = new OriginProducer(); - const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/**")])); - // The claim at room covers the request, so the answer floors it. - const room = publish(scoped, Path.from("room")); - const prefix = Path.from(["room", ...Array.from({ length: Path.MAX_PARTS - 1 }, () => "a")].join("/")); - const { next, ok, close } = routedAnswer(scoped, undefined, prefix); + const room = publish(origin, Path.from("room")); + const prefix = Path.from("room/a/b"); + const { next, ok, close } = routedAnswer(origin, undefined, prefix); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart" }); - expect(await next()).toMatchObject({ status: "active", suffix: prefix, route: 0n }); - expect(await next()).toEqual({ status: "floor", id: 0n, revision: undefined }); + expect(await next()).toMatchObject({ status: "start", suffix: prefix, claim: ownClaim(0n, 2n) }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); } finally { room.close(); @@ -4139,44 +4065,37 @@ test("a lite-07 request beyond the scope's path limits floors uncertified", asyn } }); -// The publishing origin closing ends its claims and its route. The stream stays: only this side -// leaving the session finishes it. -test("a lite-07 answer ends its route once the publishing origin closes", async () => { +// The publishing origin closing ends its claims. The stream stays: only this side leaving the +// session finishes it. +test("a lite-07 answer ends its claims once the publishing origin closes", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("cam")); const { next, ok, close } = routedAnswer(origin); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart" }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); + expect(await next()).toMatchObject({ status: "start", suffix: "cam" }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); origin.close(); - expect(await next()).toEqual({ status: "endedId", id: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); - expect(await next()).toEqual({ status: "routeEnd", id: 0n }); + expect(await next()).toEqual({ status: "endedId", id: 0n, lost: false }); } finally { cam.close(); close(); } }); -// Leaving the session ends every route and then finishes the Announce Stream, which is how the -// peer learns this side is going. -test("a lite-07 answer ends its routes and finishes the stream as the session leaves", async () => { +// Leaving the session finishes the Announce Stream, which ends everything the peer was sent and +// is how it learns this side is going. +test("a lite-07 answer finishes the stream as the session leaves", async () => { const origin = new OriginProducer(); const cam = publish(origin, Path.from("cam")); const { publisher, next, ok, finished, close } = routedAnswer(origin); try { await ok(); - expect(await next()).toMatchObject({ status: "routeStart" }); - expect(await next()).toMatchObject({ status: "active", suffix: "cam", route: 0n }); - expect(await next()).toMatchObject({ status: "floor", id: 0n }); + expect(await next()).toMatchObject({ status: "start", suffix: "cam" }); expect(await next()).toEqual({ status: "synced", prefix: 0n }); const drained = publisher.drain(); - expect(await next()).toEqual({ status: "routeEnd", id: 0n }); expect(await finished()).toBe(true); await drained; } finally { @@ -4186,29 +4105,25 @@ test("a lite-07 answer ends its routes and finishes the stream as the session le } }); -test("a lite-07 request naming another origin node is unroutable", async () => { - const pair = createMockTransportPair(ALPN_07_WIP); - const origin = new OriginProducer(); - const cam = publish(origin, Path.from("cam")); - const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); - const node = wireOf(origin.consume()).own.node; - const resets = spyOn(Writer.prototype, "reset"); - const stream = () => - new Stream({ - version: Version.DRAFT_07, - readable: new ReadableStream(), - writable: new WritableStream(), - }); - try { - await publisher.runTrackInfo(new TrackMessage(Path.from("cam"), "video", undefined, node + 1n), stream()); - const codes = resets.mock.calls.map(([reason]) => toStreamCode(reason as Error)); - expect(codes).toContain(StreamCode.Unroutable); - } finally { - resets.mockRestore(); - publisher.close(); - cam.close(); - origin.close(); - pair.client.close(); - pair.server.close(); - } +// A request names the forwarding node that should serve it, or none. An endpoint forwards +// nothing, so it serves the request itself whichever the request names. +test("a lite-07 request naming a node is served here", async () => { + const version = Version.DRAFT_07; + const named = await Writer.collect(version, async (w) => { + await w.u53(3); + await w.string("cam"); + // No instance pinned, then Node ID 7 with its start. + await w.u53(0); + await w.bool(false); + await w.u62(7n); + await w.u62(9n); + await w.string("video"); + }); + // The message's own size prefix, then its body. + const sized = await Writer.collect(version, async (w) => { + await w.u53(named.byteLength - 1); + await w.write(named.subarray(1)); + }); + const msg = await TrackMessage.decode(new Reader(undefined, sized, version), version); + expect(msg).toMatchObject({ broadcast: "cam", track: "video", instance: undefined }); }); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 36ad0595d35..e76779766cf 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -874,19 +874,13 @@ export class Publisher { } } - /** - * The broadcast a request names, from this session's origin. A request naming an origin node - * other than this one is not ours to serve: a browser forwards nothing. - */ + /** The broadcast a request names, from this session's origin. */ async #resolve( - msg: { broadcast: Path.Valid; instance?: Instance.Valid; node: bigint }, + msg: { broadcast: Path.Valid; instance?: Instance.Valid }, signal: AbortSignal, ): Promise { const origin = this.#publish && wireOf(this.#publish); if (!origin) return undefined; - if (msg.node !== 0n && msg.node !== origin.own.node) { - throw new StreamError(StreamCode.Unroutable, { message: `origin node ${msg.node} is not this one` }); - } return origin.local(msg.broadcast, msg.instance) ?? (await origin.demand(msg.broadcast, msg.instance, signal)); } diff --git a/js/net/src/lite/rekey.test.ts b/js/net/src/lite/rekey.test.ts deleted file mode 100644 index 739b2d9c3b4..00000000000 --- a/js/net/src/lite/rekey.test.ts +++ /dev/null @@ -1,183 +0,0 @@ -// The same cases as `lite/rekey.rs` in rs/moq-net: both endpoints must carry routes alike. - -import { expect, test } from "bun:test"; -import * as Path from "../path.ts"; -import type { Offer } from "./announce.ts"; -import { compare, type Order, order, type Plan, plan, type Route } from "./rekey.ts"; - -const BEST: Order = { held: false, names: false, draining: false, priority: 0, metric: 1n }; -const HELD: Order = { ...BEST, held: true }; - -const set = (...paths: string[]) => new Set(paths.map((path) => Path.from(path))); - -function route(node: bigint, prefix: string, region: string, rank: Order, claims: [string, bigint][]): Route { - return { - node, - prefix: Path.from(prefix), - region: Path.from(region), - exact: false, - order: rank, - claims: new Map(claims.map(([path, id]) => [Path.from(path), id])), - }; -} - -const ids = (carried: Plan) => carried.routes.map((r) => [r.id, r.from, r.kind, r.prefix as string]); -const claims = (carried: Plan, index: number) => - [...carried.routes[index].claims].map(([path, claim]) => [path as string, claim.id, claim.from]).sort(); - -test("widening merges and keeps ids", () => { - const routes = new Map([ - [ - 0n, - route(7n, "a/b", "a/b", HELD, [ - ["a/b", 0n], - ["a/b/x", 1n], - ]), - ], - [1n, route(7n, "a/c", "a/c", BEST, [["a/c/y", 2n]])], - [2n, route(7n, "a/c/deep", "a/c", BEST, [["a/c/deep/z", 3n]])], - [3n, route(9n, "q", "q", BEST, [["q/k", 4n]])], - ]); - const carried = plan(set("a/b", "a/c", "q"), set("a"), [Path.from("a")], routes, 4n, 5n); - expect(ids(carried)).toEqual([ - [1n, 1n, "widens", "a"], - [2n, 2n, "stays", "a/c/deep"], - ]); - // The claim at the route's own prefix goes; the loser's claims move in. - expect(claims(carried, 0)).toEqual([ - ["a/b/x", 1n, 1n], - ["a/c/y", 2n, 2n], - ]); - expect(carried.routes[1].region).toBe(Path.from("a")); - expect([carried.nextRoute, carried.nextClaim]).toEqual([4n, 5n]); -}); - -test("narrowing presents the covering claim", () => { - const routes = new Map([ - [ - 0n, - route(7n, "a", "a", BEST, [ - ["a", 0n], - ["a/b/x", 1n], - ["a/c", 2n], - ["a/d", 3n], - ]), - ], - [1n, route(7n, "a/c", "a", HELD, [["a/c/y", 4n]])], - ]); - const added = [Path.from("a/c"), Path.from("a/b")]; - const carried = plan(set("a"), set("a/b", "a/c"), added, routes, 2n, 5n); - // The narrowed route is preferred to the held one already at `a/c`. - expect(ids(carried)).toEqual([ - [2n, 0n, "narrows", "a/c"], - [3n, 0n, "narrows", "a/b"], - ]); - expect(claims(carried, 0)).toEqual([["a/c", 2n, 2n]]); - expect(claims(carried, 1)).toEqual([ - ["a/b", 5n, 0n], - ["a/b/x", 1n, 1n], - ]); - // Only the claim now presented below its path is further above it, by the segments between. - const lowered = (index: number) => - [...carried.routes[index].claims].map(([path, claim]) => [path as string, claim.lowered]).sort(); - expect(lowered(0)).toEqual([["a/c", 0n]]); - expect(lowered(1)).toEqual([ - ["a/b", 1n], - ["a/b/x", 0n], - ]); - expect([carried.nextRoute, carried.nextClaim]).toEqual([4n, 6n]); -}); - -test("a staying route keeps its key against an equal", () => { - const routes = new Map([ - [0n, route(7n, "a", "a", BEST, [["a/c/y", 1n]])], - [1n, route(7n, "a/c", "a", BEST, [["a/c/z", 2n]])], - [2n, route(7n, "b", "b", BEST, [])], - ]); - const carried = plan(set("a", "b"), set("a/c", "b"), [Path.from("a/c")], routes, 3n, 3n); - expect(ids(carried)).toEqual([ - [1n, 1n, "stays", "a/c"], - [2n, 2n, "stays", "b"], - ]); -}); - -test("a re-added prefix keeps its routes, and an uncovered one ends", () => { - const routes = new Map([ - [0n, route(7n, "a", "a", BEST, [["a/x", 0n]])], - [1n, route(7n, "b", "b", BEST, [["b/y", 1n]])], - ]); - const carried = plan(set("a", "b"), set("a"), [Path.from("a")], routes, 2n, 2n); - expect(ids(carried)).toEqual([[0n, 0n, "stays", "a"]]); - expect([carried.nextRoute, carried.nextClaim]).toEqual([2n, 2n]); -}); - -test("a route ranks unheld, then off the subscriber's path, then by its offer", () => { - const offer = (extra: Partial): Offer => ({ - path: [{ node: 7n, session: 0n }], - draining: false, - priority: 0, - metric: 1n, - downOnly: false, - ...extra, - }); - const ranked = [ - order(false, offer({ priority: 5, metric: 9n }), [{ node: 7n, session: 0n }], 3n), - order(false, offer({}), [{ node: 7n, session: 0n }], 3n), - order(false, offer({ metric: 2n }), [{ node: 7n, session: 0n }], 3n), - order(false, offer({ draining: true }), [{ node: 7n, session: 0n }], 3n), - // A refused offer ranks behind every usable one. - order(false, undefined, [{ node: 7n, session: 0n }], 3n), - order(false, offer({}), [{ node: 3n, session: 0n }], 3n), - order(true, offer({}), [{ node: 7n, session: 0n }], 3n), - ]; - for (let i = 0; i < ranked.length; i++) { - for (let j = 0; j < ranked.length; j++) { - expect(Math.sign(compare(ranked[i], ranked[j]))).toBe(Math.sign(i - j)); - } - } -}); - -test("an exact route stays at its own prefix", () => { - const exact = (r: Route): Route => ({ ...r, exact: true }); - let routes = new Map([ - [ - 0n, - exact( - route(7n, "a/b", "a/b", BEST, [ - ["a/b", 0n], - ["a/b/x", 1n], - ]), - ), - ], - [ - 1n, - route(8n, "a/b", "a/b", BEST, [ - ["a/b", 2n], - ["a/b/y", 3n], - ]), - ], - ]); - let carried = plan(set("a/b"), set("a"), [Path.from("a")], routes, 2n, 4n); - expect(ids(carried)).toEqual([ - [0n, 0n, "stays", "a/b"], - [1n, 1n, "widens", "a"], - ]); - expect([carried.routes[0].region, carried.routes[0].exact]).toEqual([Path.from("a"), true]); - expect(claims(carried, 0)).toEqual([ - ["a/b", 0n, 0n], - ["a/b/x", 1n, 1n], - ]); - expect(carried.routes[1].exact).toBe(false); - - // Asked at its own prefix again, it lies there exactly once more. - routes = new Map([[0n, exact(route(7n, "a/b", "a", BEST, []))]]); - carried = plan(set("a"), set("a/b"), [Path.from("a/b")], routes, 2n, 4n); - expect(ids(carried)).toEqual([[0n, 0n, "stays", "a/b"]]); - expect([carried.routes[0].region, carried.routes[0].exact]).toEqual([Path.from("a/b"), true]); - - // Narrowed, it covers the narrower prefix from its own. - routes = new Map([[0n, exact(route(7n, "a/b", "a/b", BEST, [["a/b", 0n]]))]]); - carried = plan(set("a/b"), set("a/b/c"), [Path.from("a/b/c")], routes, 1n, 1n); - expect(ids(carried)).toEqual([[1n, 0n, "narrows", "a/b/c"]]); - expect(carried.routes[0].exact).toBe(false); -}); diff --git a/js/net/src/lite/rekey.ts b/js/net/src/lite/rekey.ts deleted file mode 100644 index 5dc6e61ce3e..00000000000 --- a/js/net/src/lite/rekey.ts +++ /dev/null @@ -1,197 +0,0 @@ -// Lite-07: how an Announce Stream's live routes carry over an edit of its requested prefixes, at -// the ANNOUNCE_OK answering it. -// -// Both endpoints run `plan` over what the stream carries, so they agree on which routes and claims -// live on, and under which ids, without a message for any of it. Mirrors `lite/rekey.rs` in -// rs/moq-net. - -import { coveringPrefixes } from "../internal.ts"; -import * as Path from "../path.ts"; -import type { Offer, RouteHop } from "./announce.ts"; - -/** - * How a route ranks among the routes that would share an origin node and prefix: one that is not - * held first, then one whose path does not name the subscriber, then the better rank (not - * draining, the higher priority, the lower metric). - */ -export interface Order { - held: boolean; - names: boolean; - draining: boolean; - priority: number; - metric: bigint; -} - -/** The {@link Order} of a route offering `offer`, or `path` alone for an offer the receiver refused, - * to the subscriber `receiver`. */ -export function order(held: boolean, offer: Offer | undefined, path: RouteHop[], receiver: bigint): Order { - const names = path.some((hop) => hop.node === receiver); - if (offer) return { held, names, draining: offer.draining, priority: offer.priority, metric: offer.metric }; - return { held, names, draining: true, priority: -128, metric: 2n ** 64n - 1n }; -} - -/** Negative when `a` is preferred to `b`, positive when `b` is, and 0 when they rank alike. */ -export function compare(a: Order, b: Order): number { - if (a.held !== b.held) return a.held ? 1 : -1; - if (a.names !== b.names) return a.names ? 1 : -1; - if (a.draining !== b.draining) return a.draining ? 1 : -1; - if (a.priority !== b.priority) return b.priority - a.priority; - return a.metric < b.metric ? -1 : a.metric > b.metric ? 1 : 0; -} - -/** A live route on the stream. */ -export interface Route { - node: bigint; - /** The prefix it covers, or the requested prefix it lies in when its suffix was refused. */ - prefix: Path.Valid; - /** The requested prefix it lies in. */ - region: Path.Valid; - /** Its ROUTE_START said its sender keeps it at its own prefix, so a widening leaves it there - * rather than moving it up. */ - exact: boolean; - order: Order; - /** The Announce ID of each of its live claims with a path. */ - claims: ReadonlyMap; -} - -/** - * What became of a route that lives on. `stays`: unchanged. `widens`: moved to a prefix above the - * one it was requested under, so it certifies nothing until its next floor. `narrows`: carried to - * a prefix below the one it covered, with its floor. - */ -export type Kind = "stays" | "widens" | "narrows"; - -/** A claim of a route that lives on: its Announce ID from here on, and the one it had, the same - * unless it is now presented at a prefix below its path. `lowered` is how many segments below where - * it was presented it is presented now, which its Above grows by: 0 unless it now covers a narrower - * prefix from above. */ -export interface Claim { - id: bigint; - from: bigint; - lowered: bigint; -} - -/** A route that lives on: its Route ID from here on, and the route whose offer and state it keeps. */ -export interface Carried { - id: bigint; - from: bigint; - kind: Kind; - prefix: Path.Valid; - region: Path.Valid; - /** It lies at its own prefix: one that stays keeps it, and one that widens or narrows is - * presented at a prefix that is not its own. */ - exact: boolean; - claims: Map; -} - -/** The routes that live on, by their new Route ID. Every other route ends, and every Announce ID - * no claim here keeps retires. */ -export interface Plan { - routes: Carried[]; - nextRoute: bigint; - nextClaim: bigint; -} - -/** - * Carry `routes` over an edit from the prefixes `old` to `next`, which added `added` in that - * order. `nextRoute` and `nextClaim` are the next unassigned Route ID and Announce ID. - */ -export function plan( - old: ReadonlySet, - next: ReadonlySet, - added: readonly Path.Valid[], - routes: ReadonlyMap, - nextRoute: bigint, - nextClaim: bigint, -): Plan { - const region = (prefix: Path.Valid): Path.Valid | undefined => { - for (const above of coveringPrefixes(prefix)) if (next.has(above)) return above; - return undefined; - }; - const key = (node: bigint, prefix: Path.Valid) => `${node} ${prefix}`; - const ids = [...routes.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)); - const route = (id: bigint): Route => { - const found = routes.get(id); - if (!found) throw new Error(`no route ${id}`); - return found; - }; - - const stays = new Map(); - const widening = new Map(); - const narrowing: { from: bigint; inside: Path.Valid }[] = []; - for (const id of ids) { - const { node, prefix, region: lies, exact } = route(id); - if (!old.has(lies)) throw new Error("a route lies in a requested prefix"); - const covered = region(prefix) !== undefined; - const wider = region(lies); - // A route at its own prefix stays there, as one strictly inside the region does. - if (covered && (next.has(lies) || prefix !== lies || exact)) { - stays.set(key(node, prefix), id); - } else if (wider !== undefined) { - const entry = widening.get(key(node, wider)); - if (entry) entry.sources.push(id); - else widening.set(key(node, wider), { wider, sources: [id] }); - } else if (prefix === lies) { - for (const inside of added) { - if (inside !== lies && Path.hasPrefix(lies, inside)) narrowing.push({ from: id, inside }); - } - } - } - - const carried = new Map(); - const kept = (claims: ReadonlyMap): [Path.Valid, Claim][] => - [...claims].map(([path, id]) => [path, { id, from: id, lowered: 0n }]); - for (const { wider, sources } of widening.values()) { - let winner = sources[0]; - for (const id of sources) if (compare(route(id).order, route(winner).order) < 0) winner = id; - const claims = new Map(); - for (const id of sources) { - const source = route(id); - for (const [path, claim] of kept(source.claims)) if (path !== source.prefix) claims.set(path, claim); - } - carried.set(winner, { - id: winner, - from: winner, - kind: "widens", - prefix: wider, - region: wider, - exact: false, - claims, - }); - } - for (const { from, inside } of narrowing) { - const source = route(from); - const at = key(source.node, inside); - // A route already there stays unless this one would be preferred. - const staying = stays.get(at); - if (staying !== undefined) { - if (compare(route(staying).order, source.order) <= 0) continue; - stays.delete(at); - } - const claims = new Map(); - // Of the claims covering the whole prefix alike, only the most specific shows. - let above: [Path.Valid, bigint] | undefined; - for (const [path, id] of source.claims) { - if (path !== inside && Path.hasPrefix(inside, path)) claims.set(path, { id, from: id, lowered: 0n }); - if (Path.hasPrefix(path, inside) && (!above || path.length > above[0].length)) above = [path, id]; - } - if (above) { - const id = above[0] === inside ? above[1] : nextClaim++; - const lowered = BigInt(Path.parts(inside).length - Path.parts(above[0]).length); - claims.set(inside, { id, from: above[1], lowered }); - } - const id = nextRoute++; - carried.set(id, { id, from, kind: "narrows", prefix: inside, region: inside, exact: false, claims }); - } - for (const id of stays.values()) { - const { prefix, exact, claims } = route(id); - const lies = region(prefix); - if (lies === undefined) throw new Error("a route that stays is covered"); - carried.set(id, { id, from: id, kind: "stays", prefix, region: lies, exact, claims: new Map(kept(claims)) }); - } - return { - routes: [...carried.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)), - nextRoute, - nextClaim, - }; -} diff --git a/js/net/src/lite/route_key.test.ts b/js/net/src/lite/route_key.test.ts deleted file mode 100644 index a03e0b02a8c..00000000000 --- a/js/net/src/lite/route_key.test.ts +++ /dev/null @@ -1,102 +0,0 @@ -import { expect, test } from "bun:test"; -import { proveRouteKey, sign } from "./route_key.ts"; - -// PKCS#8 v1 (RFC 8410) prefix of an Ed25519 key, up to its 32-byte seed. -const PKCS8_SEED_PREFIX = [ - 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, -]; - -// Shared with rs/moq-net/src/route/proof.rs, so both sides sign the same transcript. -const SEED = new Uint8Array(32).fill(1); -const SECRET = new Uint8Array(32).fill(2); -const CLIENT_PROOF = - "8a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c" + - "e7ea4e34a65b8501185b805d09b58a61b5b8495654fcaac0949d4f98aa35002e" + - "6fca096329973e91e1105030dd88fa0eb543c68c00e18394f8300cb0574cf901"; - -async function keyFromSeed(seed: Uint8Array): Promise { - const der = new Uint8Array([...PKCS8_SEED_PREFIX, ...seed]); - const privateKey = await crypto.subtle.importKey("pkcs8", der, { name: "Ed25519" }, true, ["sign"]); - // WebCrypto derives the public key only through a JWK export. - const jwk = await crypto.subtle.exportKey("jwk", privateKey); - const publicKey = await crypto.subtle.importKey( - "jwk", - { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, - { name: "Ed25519" }, - true, - ["verify"], - ); - return { privateKey, publicKey }; -} - -function hex(bytes: Uint8Array): string { - return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); -} - -test("a proof matches the Rust transcript", async () => { - const proof = await sign(await keyFromSeed(SEED), SECRET, true); - expect(hex(proof)).toBe(CLIENT_PROOF); -}); - -test("the prover's side changes the signature", async () => { - const key = await keyFromSeed(SEED); - const client = await sign(key, SECRET, true); - const server = await sign(key, SECRET, false); - expect(client.subarray(0, 32)).toEqual(server.subarray(0, 32)); - expect(client.subarray(32)).not.toEqual(server.subarray(32)); -}); - -test("a transport without an exporter proves nothing", async () => { - expect(await proveRouteKey({} as WebTransport, true)).toBeUndefined(); -}); - -test("a transport with an exporter proves one key per page", async () => { - const labels: string[] = []; - const transport = { - exportKeyingMaterial: async (label: BufferSource, context: BufferSource, length: number) => { - labels.push(new TextDecoder().decode(label)); - expect((context as Uint8Array).byteLength).toBe(0); - return new Uint8Array(length).fill(3); - }, - } as unknown as WebTransport; - const first = await proveRouteKey(transport, true); - const second = await proveRouteKey(transport, false); - expect(first?.byteLength).toBe(96); - expect(first?.subarray(0, 32)).toEqual(second?.subarray(0, 32)); - expect(labels).toEqual(["EXPORTER-moq-lite-route-key", "EXPORTER-moq-lite-route-key"]); -}); - -test("Firefox's exporter proves nothing", async () => { - // neqo derives a secret the draft's peers never match, so a proof would end the session. - const exporter = { exportKeyingMaterial: async () => new Uint8Array(32) } as unknown as WebTransport; - const userAgent = "Mozilla/5.0 (X11; Linux x86_64; rv:157.0) Gecko/20100101 Firefox/157.0"; - const own = Object.getOwnPropertyDescriptor(navigator, "userAgent"); - Object.defineProperty(navigator, "userAgent", { value: userAgent, configurable: true }); - try { - expect(await proveRouteKey(exporter, true)).toBeUndefined(); - } finally { - if (own) Object.defineProperty(navigator, "userAgent", own); - else Reflect.deleteProperty(navigator, "userAgent"); - } -}); - -test("unavailable Ed25519 leaves this page unproven across sessions", () => { - // A child has its own page capability cache, independent of the successful proof tests. - const moduleUrl = new URL("./route_key.ts", import.meta.url).href; - const child = Bun.spawnSync([ - process.execPath, - "-e", - ` - import { strict as assert } from "node:assert"; - import { proveRouteKey } from ${JSON.stringify(moduleUrl)}; - let calls = 0; - crypto.subtle.generateKey = async () => { calls++; throw new Error("unavailable"); }; - const transport = { exportKeyingMaterial: async () => new Uint8Array(32) }; - assert.equal(await proveRouteKey(transport, true), undefined); - assert.equal(await proveRouteKey(transport, true), undefined); - assert.equal(calls, 1); - `, - ]); - expect(child.stderr.toString()).toBe(""); - expect(child.exitCode).toBe(0); -}); diff --git a/js/net/src/lite/route_key.ts b/js/net/src/lite/route_key.ts deleted file mode 100644 index 4effc0dc86d..00000000000 --- a/js/net/src/lite/route_key.ts +++ /dev/null @@ -1,64 +0,0 @@ -/** - * Route key proofs: an endpoint shows its peer that it holds an Ed25519 key, bound to the - * session by keying material both ends export from its handshake. - * - * A tab proves one key per page load, so a peer recognizes it across its sessions. Only a - * transport that exposes `exportKeyingMaterial` with the draft's derivation can bind a proof; - * elsewhere the tab sends none and stays unproven. - * - * @module - */ - -const EXPORTER_LABEL = new TextEncoder().encode("EXPORTER-moq-lite-route-key"); -const DOMAIN = new TextEncoder().encode("moq-lite route key"); -const SECRET_SIZE = 32; - -/** The keying material export a WebTransport may offer; only some browsers ship it. */ -type Exporter = (label: BufferSource, context: BufferSource, outputLength: number) => Promise; - -let pageKey: Promise | undefined; - -/** - * Whether this runtime's exporter derives what draft-ietf-webtrans-http3 section 4.8 specifies. - * - * Firefox (neqo) writes the session ID into the exporter context as a varint, not the draft's 64 - * bits, so its proof never verifies and the peer would end the session. Checked against Firefox - * 157; neqo has no fix yet. Only the user agent tells it apart: the argument count of its - * `exportKeyingMaterial`, which changes in 160, says nothing about the derivation. - */ -function draftExporter(): boolean { - return !/\bFirefox\//.test(globalThis.navigator?.userAgent ?? ""); -} - -/** - * The proof to send in SETUP for `transport`, or `undefined` when it cannot export the draft's - * keying material. `client` is whether this endpoint dialed the session. - */ -export async function proveRouteKey(transport: WebTransport, client: boolean): Promise { - const exporter = (transport as { exportKeyingMaterial?: Exporter }).exportKeyingMaterial; - if (typeof exporter !== "function" || !draftExporter()) return undefined; - const secret = new Uint8Array(await exporter.call(transport, EXPORTER_LABEL, new Uint8Array(), SECRET_SIZE)); - // Select page capability once: unavailable Ed25519 leaves sessions unproven. - pageKey ??= ( - crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]) as Promise - ).catch(() => undefined); - const key = await pageKey; - return key ? sign(key, secret, client) : undefined; -} - -/** Sign the proof for `secret`, the session's exported keying material. Exported for tests. */ -export async function sign(key: CryptoKeyPair, secret: Uint8Array, client: boolean): Promise { - if (secret.byteLength !== SECRET_SIZE) throw new Error("route key secret must be 32 bytes"); - // The domain, then the prover's side of the session (0 dialed, 1 accepted), then the secret. - const message = new Uint8Array(DOMAIN.byteLength + 1 + SECRET_SIZE); - message.set(DOMAIN); - message[DOMAIN.byteLength] = client ? 0 : 1; - message.set(secret, DOMAIN.byteLength + 1); - - const publicKey = new Uint8Array(await crypto.subtle.exportKey("raw", key.publicKey)); - const signature = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key.privateKey, message)); - const proof = new Uint8Array(publicKey.byteLength + signature.byteLength); - proof.set(publicKey); - proof.set(signature, publicKey.byteLength); - return proof; -} diff --git a/js/net/src/lite/routed.ts b/js/net/src/lite/routed.ts index c4b80ce1470..4d7db13478d 100644 --- a/js/net/src/lite/routed.ts +++ b/js/net/src/lite/routed.ts @@ -3,17 +3,20 @@ // // Every `routes()` reader of the session shares the one stream. The session asks the peer only // for the covering set of what its readers want, no prefix at or below another, edited in place -// one ANNOUNCE_REQUEST at a time, and each reader is fed from the routes and claims the stream -// carries, presented under the reader's own prefix as the peer would present them to a request -// for it. Mirrors `subscriber/routed.rs` in rs/moq-net for a node that forwards nothing: an -// endpoint applies the peer's withdrawals and holds, and casts no doubt. +// one ANNOUNCE_REQUEST at a time, and each reader is fed from the claims the stream carries, +// presented under the reader's own prefix as the peer would present them to a request for it. +// +// This node is an endpoint: it declares no Node ID, so the peer sends it claims and never routes. +// Each claim is one instance's at a path, with what the peer's own reader shows of it: its cost, +// how far above the path it was made, and whether a route still reaches it. import { type Dispose, type GetPromise, race } from "@moq/signals"; import type * as announce from "../announced.ts"; import type { Goaway } from "../connection/goaway.ts"; import type { BroadcastCache } from "../consume.ts"; import { error, ProtocolViolation } from "../error.ts"; -import { Cost, type Hop, routesEqual, WireRoute } from "../hop.ts"; +import { routesEqual, WireRoute } from "../hop.ts"; +import type * as Instance from "../instance.ts"; import { bestCandidate, coveringPrefixes, hiddenBelow, scopeCaptures, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import { SlotMap, type Slots } from "../util/limits.ts"; @@ -21,19 +24,10 @@ import { type Add, type AnnounceBroadcast, AnnounceHistory, - type Refusal as AnnounceRefusal, - type Base, - type Dead, - type Offer, - type Refusable, - ROUTE_MAX_HOPS, - type RouteHop, + type Claim, requestFits, requestParts, - type Unusable, } from "./announce.ts"; -import type { Carrier, Claim, Floors } from "./floors.ts"; -import * as rekey from "./rekey.ts"; import type { Version } from "./version.ts"; /** What a `routes()` reader asked for. */ @@ -45,25 +39,20 @@ export interface Request { hidden: boolean; /** Also report claims whose subtree overlaps the scope without matching it. */ covering: boolean; - /** Report each origin node's claim at a path rather than the best one. */ - perNode: boolean; + /** Report each instance's claim at a path rather than the best one. */ + claims: boolean; } /** What the session's route layer is built on. */ export interface Session { quic: WebTransport; version: Version; - /** This node's hop: a route whose path names it came back to its origin. */ - hop: Hop; - floors: Floors; consumes: BroadcastCache; - /** The session's announce cap: one slot per live route and claim. */ + /** The session's announce cap: one slot per live claim. */ slots: Slots; /** Rank a route last once the peer sent GOAWAY. */ drained(route: WireRoute): WireRoute; goaway?: GetPromise; - /** What covers a path changed with no claim reporting it: every selection is checked anew. */ - revalidate(): void; /** Send one message on this session's Announce Stream. */ send(msg: AnnounceBroadcast): Promise; } @@ -71,8 +60,8 @@ export interface Session { /** One reader, and what it was last told of each path. */ interface Reader extends Request { announced: announce.Producer; - /** What each path reports, by origin node with `perNode` and otherwise under `undefined`. */ - reported: Map>; + /** What each path reports, by instance with `claims` and otherwise under `undefined`. */ + reported: Map>; synced: boolean; } @@ -86,78 +75,28 @@ interface Asked { synced: boolean; } -/** One route the peer sent on the stream, by its Route ID. */ -interface Route { - id: bigint; - node: bigint; - /** The requested prefix it lies in. */ - region: Path.Valid; - /** The prefix it covers, or undefined when this node refused the suffix the peer forwarded, - * which leaves the route refused for good. */ - prefix: Path.Valid | undefined; - /** Its ROUTE_START said it lies at its own prefix, so a widening leaves it there. */ - exact: boolean; - /** The path the peer last named, kept while this node refuses the rest, so a DEAD finds it. */ - path: RouteHop[]; - /** Undefined while this node refuses what the peer forwarded: no route at all, its claims - * offline, until an offer it can use. */ - offer: Offer | undefined; - /** A DRAIN named a node on its path since its last offer: it ranks last. */ - drain: boolean; - /** ROUTE_HOLD, or a DEAD that held it: no usable path to the publisher, until its next offer. */ - held: boolean; - /** The Announce ID of each live claim, by path: one per path, checked by lookup. */ - claims: Map; - /** The Announce IDs of its live claims whose path this node refused. */ - unnamed: Set; - /** The Announce IDs of its live claims at a path whose content this node refuses. */ - withheld: Set; - /** How the claims differ from the view's, applied whole at the next floor. */ - pending: Map; - /** The prefixes whose claims an edit that widened the route took from the routes it merged, - * which the view keeps until the route's next floor says what covers each now. */ - stale: Set; - /** The claims as of the last floor, and the revision it certified them at, if any. */ - view: { prefix: Path.Valid; hidden: boolean; revision: bigint | undefined; claims: Map }; - /** The view's claims no other route's newer floor withdrew or replaced, each as the newest - * floor certifying it has it, cost included. */ - shown: Map; - carrier: Carrier; - /** Who the route's claims are filed under in the consume cache, which keeps every route's - * claim so a consume ranks them for its own path. */ +/** One live claim the peer sent, by its Announce ID. */ +interface Live { + /** Relative to the session, or undefined when it resolves to no path this node can hold, + * which the claim then never has. */ + path?: Path.Valid; + instance: Instance.Valid; + claim: Claim; + /** Whether the claim's run, its epoch and how far above its path it is, was ever told + * available. A run first told unavailable is not there: nothing can serve it. */ + taken: boolean; + /** Who the claim is filed under in the consume cache. */ owner: object; } -type Joined = Route & { offer: Offer; prefix: Path.Valid }; - -/** A DEAD whose ROUTE_UPDATEs are still arriving: it applies with its last. */ -interface Moving { - hop: RouteHop; - gone: boolean; - /** How many ROUTE_UPDATEs are still to come. */ - left: bigint; - /** The new offer of each route it moved, by Route ID. */ - offers: Map; -} - -const same = (a: Claim | undefined, b: Claim | undefined) => - a === b || - (!!a && !!b && a.instance === b.instance && a.epoch === b.epoch && a.cost === b.cost && a.above === b.above); - -// The peer's `above` for the claim at `path`, if it can be: a claim is no more than its path's -// segments broader than the path it is shown at. Mirrors rs/moq-net's `Routed::above`. -const aboveOf = (path: Path.Valid | undefined, above: bigint | undefined): bigint => { - const value = above ?? 0n; - if (path === undefined || value === 0n) return value; - if (value > BigInt(Path.parts(path).length)) - throw new ProtocolViolation(`a claim at ${path} cannot be ${value} segments above it`); - return value; +// The most a claim at `path` can be above it: a claim above the session's root covers the whole +// of what the peer shows. Mirrors rs/moq-net. +const checkAbove = (path: Path.Valid, above: bigint) => { + if (above > BigInt(Path.parts(path).length)) + throw new ProtocolViolation(`a claim at ${path} cannot be ${above} segments above it`); }; -const through = (wire: Route, hop: RouteHop) => - wire.path.some((at) => at.node === hop.node && at.session === hop.session); - -/** The route layer a lite-07 session's peer feeds, shared by every reader of the session. */ +/** The claims a lite-07 session's peer sends, shared by every reader of the session. */ export class Routed { #session: Session; #readers = new Set(); @@ -171,35 +110,23 @@ export class Routed { /** This side finished its stream: it asks for nothing more. */ #silent = false; - // Each live route and claim holds one of the session's announce slots. - #routes: SlotMap; - // A claim refused has no `claim` until a restart names all of it, and one refused before its - // path has no `path` either, and never will. - #claims: SlotMap; - // The live route to each publisher node and prefix: at most one each. - #named = new Map(); - // The routes whose committed claims include each path. + // Each live claim holds one of the session's announce slots. + #claims: SlotMap; + // The claims shown at each path, oldest first. #byPath = new Map>(); #history = new AnnounceHistory(); - #nextRoute = 0n; - #moving?: Moving; - // While a DEAD applies: each reader's presented paths it touched, and whether any touch there - // lost a claim, each refreshed once it is done. - #deferred?: Map>; - // Set once the session lets go of its routes, which then show nothing anew. + // Set once the session lets go of its claims, which then show nothing anew. #closing = false; - #closed = Promise.withResolvers(); #stopDrain?: Dispose; constructor(session: Session) { this.#session = session; - this.#routes = new SlotMap(session.slots); this.#claims = new SlotMap(session.slots); - // A draining peer ranks its routes last from the GOAWAY itself. + // A draining peer ranks its claims last from the GOAWAY itself. this.#stopDrain = session.goaway?.changed(() => { if (this.#closing) return; - for (const wire of this.#routes.values()) this.#refreshRoute(wire, false); + for (const [id, live] of this.#claims) this.#serve(id, live, false, false); }); } @@ -213,11 +140,9 @@ export class Routed { this.#readers.add(reader); // What the stream already carries shows before the reader counts as synced. const paths = new Set(); - for (const wire of this.#routes.values()) { - for (const path of wire.view.claims.keys()) { - const at = presentedAt(reader, path); - if (at !== undefined) paths.add(at); - } + for (const path of this.#byPath.keys()) { + const at = presentedAt(reader, path); + if (at !== undefined) paths.add(at); } for (const path of paths) this.#refresh(reader, path, false); this.#ask(); @@ -313,142 +238,127 @@ export class Routed { this.#release(); } - /** The peer finished its stream: it is leaving, its routes go, and it answers nothing more. */ + /** The peer finished its stream: it is leaving, its claims go, and it answers nothing more. */ finish(): void { - if (this.#moving) throw new ProtocolViolation("Announce Stream finished inside a DEAD"); this.#finished = true; - for (const wire of [...this.#routes.values()]) this.#endRoute(wire); + for (const id of [...this.#claims.keys()]) this.#end(id, true); this.#release(); } - /** The session ended: every reader ends with `err`, and every route and claim goes. */ + /** The session ended: every reader ends with `err`, and every claim goes. */ close(err?: Error): void { if (this.#closing) return; this.#closing = true; - this.#closed.resolve(); this.#stopDrain?.(); - for (const wire of this.#routes.values()) { - this.#session.floors.leave(wire.node, wire.carrier); - for (const path of wire.view.claims.keys()) this.#session.consumes.withdraw(path, wire.owner); + for (const live of this.#claims.values()) { + if (live.path !== undefined && live.taken) this.#session.consumes.withdraw(live.path, live.owner); } - if (this.#routes.size > 0) this.#session.revalidate(); this.#claims.clear(); - this.#routes.clear(); - this.#named.clear(); this.#byPath.clear(); const readers = [...this.#readers]; this.#readers.clear(); for (const reader of readers) reader.announced.close(err); } - #route(id: bigint): Route { - const found = this.#routes.get(id); - if (!found) throw new ProtocolViolation(`unknown route ${id}`); - return found; - } - - #claim(id: bigint) { + #claim(id: bigint): Live { const found = this.#claims.get(id); if (!found) throw new ProtocolViolation(`unknown announce id ${id}`); return found; } - // The claim at `path` under `id` is now `claim`, pending the route's next floor. - #change(id: bigint, path: Path.Valid, claim: Claim | undefined) { - const wire = this.#route(id); - if (same(wire.view.claims.get(path), claim) && !wire.stale.has(path)) wire.pending.delete(path); - else wire.pending.set(path, claim); - } - - // Whether this node takes what the peer offers for the route at all: not a refused offer or - // suffix, nor a route to the reserved node. Only such a route joins the node's floors. - #joined(wire: Route): wire is Joined { - return wire.offer !== undefined && wire.prefix !== undefined && wire.node !== 0n; - } - - // The same, without narrowing, to compare a route before and after it changes. - #filed(wire: Route): boolean { - return this.#joined(wire); - } - - // A route is no route at all once it crossed as many nodes as one may, or crossed us: a copy - // of our own route, come back. - #usable(wire: Route): wire is Joined { - return ( - this.#joined(wire) && - wire.offer.path.length < ROUTE_MAX_HOPS && - !wire.offer.path.some((hop) => hop.node === this.#session.hop) - ); - } - - // A claim through this session: its cost plus the route's metric, past this session's link - // cost of 1 as Rust's default, ranked last while a node on its path drains, then by the - // lowest priority on its path, past this link's 0 as Rust's default, and unavailable while - // the route is held. Requests through it name its publisher and its prefix's depth. - #candidate(wire: Joined, claim: Claim): WireRoute { + // A claim through this session: its cost past this session's link cost of 1, as Rust's + // default, ranked last while the peer or a node on its way drains, then by the lowest + // priority on its way, past this link's 0, and unavailable while no route reaches it. + #candidate(live: Live, claim: Claim): WireRoute { return this.#session.drained( WireRoute.normalize({ - instance: claim.instance, + instance: live.instance, epoch: claim.epoch, - cost: claim.cost + wire.offer.metric + 1n, - node: wire.node, - depth: Path.parts(wire.prefix).length, - priority: Math.min(0, wire.offer.priority), + cost: claim.cost + 1n, + claimed: true, + priority: Math.min(0, claim.priority), above: claim.above, - draining: wire.offer.draining || wire.drain || undefined, - available: !wire.held, + draining: claim.draining || undefined, + available: !claim.unavailable, }), ); } - // File the route's claim at `path` in the consume cache, or take it out. Every route's claim - // stays there, so each consume ranks them for its own path and its epochs. `restart` marks - // another instance or epoch, whose consumes subscribe fresh. An unusable route's claim is - // parked, keeping its place in a tie as `byPath` does, unless it just moved to the newest. - #serve(wire: Route, path: Path.Valid, restart: boolean) { + // Whether `live` is shown: at a path this node can hold, on a run that was told available. + #shown(live: Live): live is Live & { path: Path.Valid } { + return live.path !== undefined && live.taken; + } + + // Bring what the session shows of the claim `id` in line with `live`, which `was` shown or + // not before the change. `restart` marks another epoch, whose consumes subscribe fresh, and + // `lost` a claim let go rather than withdrawn. + #serve(id: bigint, live: Live, restart: boolean, lost: boolean, was = this.#shown(live)) { + if (live.path === undefined) return; const consumes = this.#session.consumes; - const claim = wire.shown.get(path); - if (!claim || (!this.#usable(wire) && restart)) consumes.withdraw(path, wire.owner); - else if (!this.#usable(wire)) consumes.park(path, wire.owner); - else consumes.announce(path, wire.owner, this.#candidate(wire, claim), restart); + let ids = this.#byPath.get(live.path); + if (this.#shown(live)) { + if (!ids) { + ids = new Set(); + this.#byPath.set(live.path, ids); + } + // A claim shown anew or restarted iterates last, as the newest; a re-price keeps its + // place, as the consume cache does. See bestCandidate. + if (!was || restart) ids.delete(id); + ids.add(id); + consumes.announce(live.path, live.owner, this.#candidate(live, live.claim), restart); + } else if (was) { + ids?.delete(id); + if (ids?.size === 0) this.#byPath.delete(live.path); + consumes.withdraw(live.path, live.owner); + } else { + return; + } + this.#touch(live.path, lost); } - // The usable claims `reader` is shown at `path`: those at the path itself, and at the - // reader's own prefix each route's most specific claim at or above it, as the peer presents - // a claim covering more than a requested prefix: that many segments more above the path, so a - // claim exactly there still outranks it, as `covering` in rs/moq-net's `route/view.rs`. + // The claim `id` is gone: its publisher withdrew it unless `lost`. + #end(id: bigint, lost: boolean) { + const live = this.#claim(id); + this.#history.end(id); + this.#claims.delete(id); + const was = this.#shown(live); + live.taken = false; + this.#serve(id, live, false, lost, was); + } + + // The claims `reader` is shown at `path`: those at the path itself, and at the reader's own + // prefix each claim at or above it, as the peer presents a claim covering more than a + // requested prefix: that many segments more above the path, so a claim exactly there still + // outranks it. #candidates(reader: Reader, path: Path.Valid): WireRoute[] { const candidates: WireRoute[] = []; - const seen = new Set(); for (const at of path === reader.prefix ? coveringPrefixes(path) : [path]) { const by = BigInt(Path.parts(path).length - Path.parts(at).length); for (const id of this.#byPath.get(at) ?? []) { - const wire = this.#route(id); - const claim = wire.shown.get(at); - if (!claim || seen.has(id)) continue; - seen.add(id); - // A claim above the path covers it only where the newest floor certifying the path - // leaves it, as a consume of the path picks. - if (!this.#session.floors.covers(wire.node, at, path)) continue; - const shown = by === 0n ? claim : { ...claim, above: claim.above + by }; - if (this.#usable(wire)) candidates.push(this.#candidate(wire, shown)); + const live = this.#claim(id); + const shown = by === 0n ? live.claim : { ...live.claim, above: live.claim.above + by }; + candidates.push(this.#candidate(live, shown)); } } return candidates; } - // Report to `reader` the best claim at `path`, or with `perNode` each origin node's, and each - // one's end. `lost` marks the routes leaving as let go rather than withdrawn, so they go + // Report to `reader` the best claim at `path`, or with `claims` each instance's, and each + // one's end. `lost` marks the claims leaving as let go rather than withdrawn, so they go // offline rather than ending. #refresh(reader: Reader, path: Path.Valid, lost: boolean) { const { announced, scope } = reader; if (announced.closed.peek() !== undefined) return; - // Keyed by origin node with `perNode`, and otherwise the one key `undefined`. - const now = new Map(); + // Keyed by instance with `claims`, and otherwise the one key `undefined`. + const now = new Map(); if (visible(reader, path)) { const candidates = this.#candidates(reader, path); - if (reader.perNode) { - for (const next of candidates) now.set(next.node, next); + if (reader.claims) { + // The closest claim of each instance. + for (const next of candidates) { + const held = now.get(next.instance); + if (!held || (next.above ?? 0n) < (held.above ?? 0n)) now.set(next.instance, next); + } } else { // The same pick a consume of `path` makes from the cache. const best = bestCandidate(path, path, candidates, (next) => next); @@ -457,19 +367,19 @@ export class Routed { } const captures = scopeCaptures(scope, path); - const prev = reader.reported.get(path) ?? new Map(); + const prev = reader.reported.get(path) ?? new Map(); // Arrivals first, so a reader sees a claim replaced rather than the path gone between. for (const [key, next] of now) { const was = prev.get(key); if (was && routesEqual(was, next)) continue; const restart = !!was && (was.instance !== next.instance || was.epoch !== next.epoch); const kind = !was ? "start" : restart ? "restart" : "update"; - console.debug(`announced: broadcast=${path} ${kind} instance=${next.instance} node=${next.node}`); + console.debug(`announced: broadcast=${path} ${kind} instance=${next.instance}`); announced.append({ prefix: path, captures, kind, route: next }); } for (const [key, was] of prev) { if (now.has(key)) continue; - console.debug(`announced: broadcast=${path} active=false lost=${lost} node=${was.node}`); + console.debug(`announced: broadcast=${path} active=false lost=${lost}`); announced.append({ prefix: path, captures, kind: lost ? "offline" : "end", route: was }); } if (now.size > 0) reader.reported.set(path, now); @@ -478,596 +388,51 @@ export class Routed { // Report the claims at `path` to every reader it shows under: at the path itself for a reader // above it, and at the reader's own prefix for one below. - // What covers a path changed: every consume picks anew, and each reader is shown again - // what covers its own prefix from above it. - #revalidate() { - this.#session.revalidate(); - for (const reader of this.#readers) this.#touch(reader.prefix, false); - } - #touch(path: Path.Valid, lost: boolean) { for (const reader of this.#readers) { const at = presentedAt(reader, path); - if (at === undefined) continue; - if (!this.#deferred) { - this.#refresh(reader, at, lost); - continue; - } - // A path touched again keeps a loss: a later touch only rechecks it. - const paths = this.#deferred.get(reader) ?? new Map(); - paths.set(at, (paths.get(at) ?? false) || lost); - this.#deferred.set(reader, paths); + if (at !== undefined) this.#refresh(reader, at, lost); } } - // Show or hide the route's claims at `touched`, each marked whether it restarted, or with - // `all` every claim it holds, once another route's floor may have moved what is current. - #show(wire: Route, touched: ReadonlyMap, all: boolean) { - const floors = this.#session.floors; - const paths = all - ? new Set([...touched.keys(), ...wire.shown.keys(), ...wire.view.claims.keys()]) - : touched.keys(); - for (const path of paths) { - const now = floors.shows(wire.node, wire.view, path); - const was = wire.shown.get(path); - const restart = touched.get(path); - if (same(now, was) && restart === undefined) continue; - if (now) wire.shown.set(path, now); - else wire.shown.delete(path); - // A claim shown anew or restarted iterates last, as the newest; a re-price keeps its - // place, as the consume cache does. See bestCandidate. - const ids = this.#byPath.get(path); - if (now && ids && (!was || restart)) { - ids.delete(wire.id); - ids.add(wire.id); - } - this.#serve(wire, path, restart ?? false); - // A claim gone was let go, not withdrawn by its origin, where the newest floor certifying it - // still presents it, or where this node refuses one of the route's claims and no floor - // certifies it gone. An uncertified withdrawal otherwise still ends: a relay certifies - // nothing to a request wider than its scope's region, as this one may be. - const said = now ? undefined : floors.certified(wire.node, wire.view, path); - const refusing = wire.unnamed.size > 0 || wire.withheld.size > 0; - this.#touch(path, !now && (said === "present" || (refusing && said === undefined))); - } - } - - #refreshRoute(wire: Route, lost: boolean) { - for (const path of wire.view.claims.keys()) { - this.#serve(wire, path, false); - this.#touch(path, lost); - } - } - - #key(node: bigint, at: Path.Valid | undefined): string | undefined { - return at === undefined || node === 0n ? undefined : `${node} ${at}`; - } - - // A route with nothing committed, whose claims another route's floor may hide. - #blank( - id: bigint, - from: Pick, - at: { - region: Path.Valid; - prefix: Path.Valid | undefined; - exact: boolean; - hidden: boolean; - revision: bigint | undefined; - }, - ): Route { - const view: Route["view"] = { - prefix: at.prefix ?? at.region, - hidden: at.hidden, - revision: at.revision, - claims: new Map(), - }; - const wire: Route = { - id, - node: from.node, - region: at.region, - prefix: at.prefix, - exact: at.exact, - path: from.path, - offer: from.offer, - drain: from.drain, - held: from.held, - claims: new Map(), - unnamed: new Set(), - withheld: new Set(), - pending: new Map(), - stale: new Set(), - view, - shown: new Map(), - carrier: { - view, - // Another route's floor or end runs this: a closing session is about to let go. - reshow: () => { - if (!this.#closing) this.#show(wire, new Map(), true); - }, - }, - owner: {}, - }; - return wire; - } - - // The peer started a route to `node` with the next Route ID, covering the requested prefix - // with the Prefix ID `asked` joined with `suffix`, at its own prefix when `exact`, along - // `offer`, or along `path` when this node refuses the offer. - #startRoute( - node: bigint, - asked: bigint, - suffix: Path.Valid | undefined, - exact: boolean, - offer: Offer | undefined, - path: RouteHop[], - ) { - // The peer names a prefix in effect on its stream. - const region = this.#asked.get(asked); - if (!region?.live) throw new ProtocolViolation(`unknown Prefix ID ${asked}`); - // Fields valid alone can still join the prefix past the path limits: refused too. - const joined = suffix === undefined ? undefined : Path.join(region.path, suffix); - const at = joined !== undefined && Path.check(joined) === undefined ? joined : undefined; - const named = this.#key(node, at); - // The peer keeps one route per publisher and prefix. - if (named !== undefined && this.#named.has(named)) - throw new ProtocolViolation(`second route to node ${node} at ${at}`); - const id = this.#nextRoute++; - const wire = this.#blank( - id, - { node, path, offer, drain: false, held: false }, - { region: region.path, prefix: at, exact, hidden: region.hidden, revision: undefined }, - ); - this.#routes.set(id, wire); - if (named !== undefined) this.#named.set(named, id); - // A refused route's floors stay its own, as Rust's node never holds the route. - if (this.#joined(wire)) this.#session.floors.join(node, wire.carrier); - } - - // The peer let go of the route and every claim under it: offline, not withdrawn. - #endRoute(wire: Route) { - for (const id of [...wire.claims.values(), ...wire.unnamed]) { - this.#history.end(id); - this.#claims.delete(id); - } - this.#routes.delete(wire.id); - const named = this.#key(wire.node, wire.prefix); - if (named !== undefined && this.#named.get(named) === wire.id) this.#named.delete(named); - this.#drop(wire); - this.#revalidate(); - } - - // Take a route that no longer lives out of what the session shows: offline, not withdrawn. - #drop(wire: Route) { - // Unindexed first: leaving its floors reshows another carrier at once, which refreshes - // these paths and so looks up every route indexed there. - for (const path of wire.view.claims.keys()) this.#unindex(path, wire.id); - // What its last floor certified stays, so no other route's lagging claim revives. - this.#session.floors.leave(wire.node, wire.carrier); - wire.shown.clear(); - this.#refreshRoute(wire, true); - } - - #index(path: Path.Valid, id: bigint) { - let ids = this.#byPath.get(path); - if (!ids) { - ids = new Set(); - this.#byPath.set(path, ids); - } - ids.add(id); - } - - #unindex(path: Path.Valid, id: bigint) { - const ids = this.#byPath.get(path); - ids?.delete(id); - if (ids?.size === 0) this.#byPath.delete(path); - } - - // A claim the peer started under `routeId` with the next Announce ID, at `path` unless this - // node refused it, and `claim` unless it refuses what the peer forwarded. - #startClaim(routeId: bigint, path: { suffix: Path.Valid; pathBase?: Base } | undefined, claim: Claim | undefined) { - const wire = this.#route(routeId); - // Every claim's path is relative to the session, whichever requested prefix it lies in. - const named = this.#history.start(path); - const id = this.#history.next - 1n; - if (claim) claim.above = aboveOf(named, claim.above); - if (named === undefined) { - if (claim) console.warn(`refusing a forwarded claim: route=${routeId} claim=${id} reason=path`); - this.#claims.set(id, { route: routeId }); - wire.unnamed.add(id); - return; - } - if (wire.claims.has(named)) throw new ProtocolViolation(`route ${routeId} claims ${named} twice`); - // A route covers only the claims at or below its prefix. - if (wire.prefix !== undefined && !Path.hasPrefix(wire.prefix, named)) - throw new ProtocolViolation(`route ${routeId} at ${wire.prefix} claims ${named}`); - this.#claims.set(id, { route: routeId, path: named, claim }); - wire.claims.set(named, id); - if (claim) this.#change(routeId, named, claim); - else wire.withheld.add(id); - } - - // The route now reaches its node by `offer`, or along `path` while this node refuses what the - // peer forwarded. Either way the peer no longer holds it, nor drains a node on it but as the - // offer says. A refused route leaves the node's floors, as an ended one does, and joins again - // once usable, with what its last floor certified, as rs/moq-net files it again. - #reach(wire: Route, offer: Offer | undefined, path: RouteHop[]) { - const floors = this.#session.floors; - const was = this.#filed(wire); - wire.offer = offer; - wire.path = path; - wire.held = false; - wire.drain = false; - const now = this.#filed(wire); - if (was && !now) { - floors.leave(wire.node, wire.carrier); - // What its floor certified stays as it was, while the route goes on reading claims. - wire.view.claims = new Map(wire.view.claims); - } - if (was || !now) return; - floors.join(wire.node, wire.carrier); - const others = floors.floor(wire.node, wire.carrier); - this.#show(wire, new Map(), true); - if (others) this.#revalidate(); - } - - // The route moved to `offer`, which this node refuses with its path when it is `Unusable`. - #move(wire: Route, offer: Offer | Unusable) { - const was = this.#filed(wire); - if ("refused" in offer) { - console.warn(`refusing a forwarded route: node=${wire.node} route=${wire.id} reason=${offer.refused}`); - this.#reach(wire, undefined, offer.path); - } else { - this.#reach(wire, offer, offer.path); - } - this.#refreshRoute(wire, !this.#usable(wire)); - // Its floors no longer cover anything, as on ROUTE_END. - if (was && !this.#filed(wire)) this.#revalidate(); - } - - // A DEAD: the stream's routes through the hop it names carry on as it says, once the - // ROUTE_UPDATEs it counts are in. A route this node refuses still follows it, so both ends - // agree on which routes live. An endpoint casts no doubt: it never forwards a route, so no - // detour waits on one. - #dead(news: Dead) { - if (news.kind === "drain") { - for (const wire of this.#routes.values()) { - if (!wire.path.some((hop) => hop.node === news.node)) continue; - wire.drain = true; - this.#refreshRoute(wire, false); - } - return; - } - // It moves only routes through the hop, so what its updates hold stays within the stream's. - let crossing = 0n; - for (const wire of this.#routes.values()) if (through(wire, news.hop)) crossing++; - if (news.moved > crossing) throw new ProtocolViolation(`DEAD moves ${news.moved} of ${crossing} routes`); - const moving = { hop: news.hop, gone: news.gone, left: news.moved, offers: new Map() }; - if (moving.left === 0n) this.#applyDead(moving); - else this.#moving = moving; - } - - // One of the ROUTE_UPDATEs a DEAD counted: it names a live route through the hop, once. - #moved(moving: Moving, msg: AnnounceBroadcast) { - let id: bigint; - let offer: Offer | Unusable; - if (msg.status === "routeUpdate") { - id = msg.id; - offer = msg.offer; - } else if (msg.status === "refused" && msg.message.kind === "routeUpdate") { - id = msg.message.id; - offer = { refused: msg.reason, path: msg.message.path }; - } else { - throw new ProtocolViolation(`${msg.status} inside a DEAD's ROUTE_UPDATEs`); - } - const wire = this.#routes.get(id); - if (!wire || !through(wire, moving.hop)) throw new ProtocolViolation(`DEAD moves route ${id} off its hop`); - if (moving.offers.has(id)) throw new ProtocolViolation(`DEAD moves route ${id} twice`); - moving.offers.set(id, offer); - moving.left -= 1n; - if (moving.left > 0n) return; - this.#moving = undefined; - this.#applyDead(moving); - } - - // Apply a DEAD and the offers its ROUTE_UPDATEs gave as one: readers and consumes see only - // where every route it moves ends up. - #applyDead(moving: Moving) { - const touched = new Map>(); - this.#deferred = touched; - try { - this.#session.consumes.batch(() => this.#deadRoutes(moving)); - } finally { - this.#deferred = undefined; - } - for (const [reader, paths] of touched) { - for (const [at, lost] of paths) this.#refresh(reader, at, lost); - } - } - - #deadRoutes({ hop, gone, offers }: Moving) { - const crossing = [...this.#routes.values()].filter((wire) => through(wire, hop)); - for (const wire of crossing) { - const moved = offers.get(wire.id); - const before = wire.path.at(-2); - if (moved !== undefined) this.#move(wire, moved); - else if (gone) this.#endRoute(wire); - // The peer learned it from this node, which it holds under: unchanged. - else if (before?.node === this.#session.hop) continue; - else { - wire.held = true; - this.#refreshRoute(wire, false); - } - } - } - - // Apply a message whose content, which the peer only forwarded, this node refuses: withdraw - // the route or claim it names, and keep the stream. Mirrors rs/moq-net. - #refused(message: Refusable, reason: AnnounceRefusal) { - switch (message.kind) { - case "routeStart": - console.warn(`refusing a forwarded route: node=${message.node} reason=${reason}`); - return this.#startRoute( - message.node, - message.prefix, - message.suffix, - message.exact, - undefined, - message.path, - ); - case "routeUpdate": - return this.#move(this.#route(message.id), { refused: reason, path: message.path }); - case "start": - console.warn( - `refusing a forwarded claim: route=${message.route} claim=${this.#history.next} reason=${reason}`, - ); - return this.#startClaim(message.route, message.path, undefined); - case "change": { - const live = this.#claim(message.id); - console.warn(`refusing a forwarded claim: route=${live.route} claim=${message.id} reason=${reason}`); - live.claim = undefined; - if (live.path === undefined) return; - this.#route(live.route).withheld.add(message.id); - this.#change(live.route, live.path, undefined); - return; - } - } - } - - // ANNOUNCE_FLOOR: the route's batch applies whole, at the revision its floor certifies: none - // while this node refuses one of the route's claims, which its origin never withdrew. - #floor(id: bigint, floor: bigint | undefined) { - const floors = this.#session.floors; - const wire = this.#route(id); - const revision = wire.unnamed.size === 0 && wire.withheld.size === 0 ? floor : undefined; - // A floor that certifies less keeps what the route's last one certified. - const certified = wire.view.revision; - const filed = this.#filed(wire); - if (filed && certified !== undefined && (revision === undefined || revision < certified)) - floors.regress(wire.node, wire.carrier); - // The floor says what covers the prefix a widening edit took the route's claim from. - for (const path of wire.stale) if (!wire.pending.has(path)) wire.pending.set(path, undefined); - wire.stale.clear(); - const touched = new Map(); - for (const [path, claim] of wire.pending) { - // Another instance or epoch: what was consumed through the claim may be stale. - const was = wire.view.claims.get(path); - const restart = !!was && !!claim && (was.instance !== claim.instance || was.epoch !== claim.epoch); - touched.set(path, restart); - if (claim) { - wire.view.claims.set(path, claim); - this.#index(path, id); - } else { - wire.view.claims.delete(path); - this.#unindex(path, id); - } - } - wire.pending.clear(); - wire.view.revision = revision; - // The floor answers the requested prefix as it stands, hidden claims included or not. - wire.view.hidden = this.#hidden(wire.region); - // Every other route to the node is shown anew first; with one, this route's unchanged - // claims may change state too. - const others = filed && floors.floor(wire.node, wire.carrier); - this.#show(wire, touched, others); - // Another view of the node may now cover a consumed path differently. - if (others) this.#revalidate(); - } - - // Whether the requested prefix `region` asks for hidden claims. - #hidden(region: Path.Valid): boolean { - for (const asked of this.#asked.values()) if (asked.live && asked.path === region) return asked.hidden; - return false; - } - - // ANNOUNCE_OK: the last edit takes effect on the peer's stream. Its live routes carry over as - // `rekey.plan` says, which the peer applies alike, so nothing both sets cover is sent again. + // ANNOUNCE_OK: the last edit takes effect on the peer's stream. Both ends drop every claim + // within a prefix it removed, and the peer tells again what an added prefix covers. #ok() { const editing = this.#editing; if (!editing) throw new ProtocolViolation("ANNOUNCE_OK with no ANNOUNCE_REQUEST unanswered"); - // The marker lies between batches. - for (const wire of this.#routes.values()) { - if (wire.pending.size > 0) throw new ProtocolViolation("ANNOUNCE_OK inside a batch"); - } this.#editing = undefined; - const old = new Set(); - for (const asked of this.#asked.values()) if (asked.live) old.add(asked.path); - for (const id of editing.remove) this.#asked.delete(id); - const added: Path.Valid[] = []; + const removed: Path.Valid[] = []; + for (const id of editing.remove) { + const asked = this.#asked.get(id); + if (asked) removed.push(asked.path); + this.#asked.delete(id); + } + // Whether a prefix in effect before the edit survives it: the peer's claims within one stay. + const survives = [...this.#asked.values()].some((asked) => asked.live); for (const id of editing.add) { const asked = this.#asked.get(id); if (!asked) throw new Error("an added prefix"); asked.live = true; - added.push(asked.path); } - const next = new Set(); - for (const asked of this.#asked.values()) next.add(asked.path); - - const table = new Map(); - for (const [id, wire] of this.#routes) { - table.set(id, { - node: wire.node, - prefix: wire.prefix ?? wire.region, - region: wire.region, - exact: wire.exact, - order: rekey.order(wire.held, wire.offer, wire.path, this.#session.hop), - claims: wire.claims, - }); + if (removed.length > 0) { + for (const [id, live] of [...this.#claims]) { + const { path } = live; + // A claim whose path could not be resolved lies in a prefix this side cannot name. + // The peer may still hold it, and ends it by its id, so it goes only when no earlier + // prefix is left for it to lie in. + const within = path === undefined ? !survives : removed.some((prefix) => Path.hasPrefix(prefix, path)); + // The peer never ended it: it only stopped telling this session. + if (within) this.#end(id, true); + } } - this.#carry(rekey.plan(old, next, added, table, this.#nextRoute, this.#history.next)); - // What the readers want may have moved while the peer answered. this.#ask(); this.#release(); } - // Carry the stream's routes over an edit as `plan` says: a route that stays keeps everything, - // one that widens or narrows is filed again under its new prefix, and every other route ends. - #carry(plan: rekey.Plan) { - const { floors, consumes } = this.#session; - const sources = new Map(this.#routes); - const records = new Map(this.#claims); - // The routes filed again, the ones they replace or the edit ends, and the claims that live on. - const fresh: Route[] = []; - const ended: Route[] = []; - const stays = new Set(); - const placed = new Map(); - // The claims an edit presents below their own path, in the order it assigned their ids. - const inserted: { id: bigint; path: Path.Valid }[] = []; - // The routes the plan carries on, each of which keeps its own claims. - const carriedFrom = new Set(plan.routes.map((carried) => carried.from)); - - for (const carried of plan.routes) { - const source = sources.get(carried.from); - if (!source) throw new Error("a carried route's source"); - if (carried.kind === "stays") { - stays.add(source.id); - for (const id of [...source.claims.values(), ...source.unnamed]) { - const record = records.get(id); - if (record) placed.set(id, record); - } - source.region = carried.region; - // A prefix that no longer asks for hidden claims certifies nothing about them. - if (!this.#hidden(carried.region)) source.view.hidden = false; - continue; - } - const wire = this.#blank(carried.id, source, { - region: carried.region, - prefix: source.prefix === undefined ? undefined : carried.prefix, - exact: carried.exact, - hidden: source.view.hidden && this.#hidden(carried.region), - // A widened route's floors certified only the narrower prefix. - revision: carried.kind === "widens" ? undefined : source.view.revision, - }); - for (const [path, claim] of carried.claims) { - const record = records.get(claim.from); - if (!record) throw new Error("a carried claim's record"); - // A claim now covering a narrower prefix from above is that much more above it. - const held = - record.claim && claim.lowered > 0n - ? { ...record.claim, above: record.claim.above + claim.lowered } - : record.claim; - wire.claims.set(path, claim.id); - if (held) wire.view.claims.set(path, held); - else wire.withheld.add(claim.id); - placed.set(claim.id, { route: wire.id, path, claim: held }); - if (claim.id !== claim.from) inserted.push({ id: claim.id, path }); - } - if (carried.kind === "widens") { - // A claim without a path stays with the route it was sent under. - for (const id of source.unnamed) { - wire.unnamed.add(id); - placed.set(id, { route: wire.id }); - } - // The claim at each merged route's old prefix shows until the next floor says what - // covers it now: the routes the edit merged into this one end without a successor. - const merged = [...sources.values()].filter( - (other) => - other.id === source.id || - (!carriedFrom.has(other.id) && - other.node === source.node && - Path.hasPrefix(carried.region, other.region)), - ); - for (const other of merged) { - const own = other.prefix === undefined ? undefined : other.view.claims.get(other.prefix); - if (!own || other.prefix === undefined || wire.view.claims.has(other.prefix)) continue; - wire.view.claims.set(other.prefix, own); - wire.stale.add(other.prefix); - } - } - fresh.push(wire); - } - - // Let go of what the edit ends before taking the slots of what it starts. - for (const id of [...this.#claims.keys()]) { - if (placed.has(id)) continue; - this.#history.end(id); - this.#claims.delete(id); - } - const replaced = new Set(fresh.map((wire) => wire.id)); - for (const [id, wire] of sources) { - if (stays.has(id)) continue; - ended.push(wire); - if (!replaced.has(id)) this.#routes.delete(id); - } - for (const { id, path } of inserted) { - if (this.#history.insert(path) !== id) throw new Error("the edit assigned another Announce ID"); - } - if (this.#history.next !== plan.nextClaim) throw new Error("the edit assigned other Announce IDs"); - for (const [id, record] of placed) this.#claims.set(id, record); - for (const wire of fresh) this.#routes.set(wire.id, wire); - this.#nextRoute = plan.nextRoute; - this.#named.clear(); - for (const [id, wire] of this.#routes) { - const named = this.#key(wire.node, wire.prefix); - if (named !== undefined) this.#named.set(named, id); - } - - // Every path a reader may be shown differently, once the routes are filed again. - const touched = new Set(); - const shows = (wire: Route) => { - for (const path of wire.view.claims.keys()) { - const claim = floors.shows(wire.node, wire.view, path); - if (claim) wire.shown.set(path, claim); - else wire.shown.delete(path); - } - }; - // The routes filed again show before the ones they replace go, so neither a reader nor a - // consume of a claim both carry finds it gone between. - for (const wire of fresh) { - for (const path of wire.view.claims.keys()) { - this.#index(path, wire.id); - touched.add(path); - } - if (this.#joined(wire)) floors.join(wire.node, wire.carrier); - shows(wire); - } - for (const wire of ended) { - // A widened route keeps its Route ID, and with it the entry of each claim it carried over. - const kept = replaced.has(wire.id) ? this.#routes.get(wire.id) : undefined; - for (const path of wire.view.claims.keys()) { - if (!kept?.view.claims.has(path)) this.#unindex(path, wire.id); - touched.add(path); - } - } - for (const wire of ended) floors.leave(wire.node, wire.carrier); - for (const wire of fresh) { - shows(wire); - for (const path of wire.view.claims.keys()) this.#serve(wire, path, false); - } - for (const wire of ended) { - for (const path of wire.view.claims.keys()) consumes.withdraw(path, wire.owner); - } - if (fresh.length > 0 || ended.length > 0) this.#revalidate(); - // A claim no route carries any more was let go, not withdrawn by its origin. - for (const path of touched) this.#touch(path, true); - } - /** Apply one message the peer sent on its Announce Stream as a publisher. */ async receive(msg: AnnounceBroadcast): Promise { if (this.#closing) return; - // A DEAD's ROUTE_UPDATEs arrive back to back. - if (this.#moving) return this.#moved(this.#moving, msg); - switch (msg.status) { case "ok": this.#ok(); @@ -1081,88 +446,47 @@ export class Routed { break; } case "request": - // The peer's own request is answered by the publisher half: here it only has to - // arrive outside a DEAD's updates. - break; - case "routeStart": - this.#startRoute(msg.node, msg.prefix, msg.suffix, msg.exact, msg.offer, msg.offer.path); - break; - case "routeUpdate": - this.#move(this.#route(msg.id), msg.offer); - break; - case "routeHold": { - const wire = this.#route(msg.id); - wire.held = true; - this.#refreshRoute(wire, false); - break; - } - case "routeEnd": - this.#endRoute(this.#route(msg.id)); - break; - case "dead": - this.#dead(msg.dead); - break; - case "floor": - this.#floor(msg.id, msg.revision); + // The peer's own request is answered by the publisher half. break; - case "active": { - if (msg.route === undefined) throw new ProtocolViolation("lite-07 claim without a route"); - if (msg.instance === undefined) throw new ProtocolViolation("lite-07 claim without an instance"); - const claim = { - instance: msg.instance, - epoch: msg.epoch ?? 0n, - cost: msg.cost ?? Cost.zero, - above: msg.above ?? 0n, - }; - this.#startClaim(msg.route, msg, claim); - break; - } - case "update": { - const live = this.#claim(msg.id); - const above = aboveOf(live.path, msg.above); - // An update names none of what a refused claim lacks. - if (live.claim === undefined || live.path === undefined) break; - live.claim = { ...live.claim, cost: msg.cost ?? Cost.zero, above }; - this.#change(live.route, live.path, live.claim); + case "start": { + // Every claim's path is relative to the session, whichever requested prefix it lies in. + const path = this.#history.start(msg); + const id = this.#history.next - 1n; + if (path === undefined) console.warn(`refusing a claim: claim=${id} reason=path`); + else checkAbove(path, msg.claim.above); + for (const other of path === undefined ? [] : (this.#byPath.get(path) ?? [])) { + if (this.#claim(other).instance === msg.instance) + throw new ProtocolViolation(`${path} claimed twice for one instance`); + } + const live: Live = { path, instance: msg.instance, claim: msg.claim, taken: false, owner: {} }; + this.#claims.set(id, live); + live.taken = !msg.claim.unavailable; + this.#serve(id, live, false, false, false); break; } - case "restart": { + case "change": { const live = this.#claim(msg.id); - if (msg.instance === undefined) throw new ProtocolViolation("lite-07 restart without an instance"); - // A claim without a path stays refused, whatever the peer sends for it. - if (live.path === undefined) break; - live.claim = { - instance: msg.instance, - epoch: msg.epoch ?? 0n, - cost: msg.cost ?? Cost.zero, - above: aboveOf(live.path, msg.above), - }; - this.#route(live.route).withheld.delete(msg.id); - this.#change(live.route, live.path, live.claim); + if (live.path !== undefined) checkAbove(live.path, msg.claim.above); + const was = this.#shown(live); + const run = live.claim.epoch !== msg.claim.epoch || live.claim.above !== msg.claim.above; + const restart = live.claim.epoch !== msg.claim.epoch; + live.claim = msg.claim; + // The bit counts only on a run this node already holds: another run is taken once + // it is told available, and the one held before it is lost. + live.taken = run ? !msg.claim.unavailable : live.taken || !msg.claim.unavailable; + this.#serve(msg.id, live, restart, true, was); break; } - case "refused": - this.#refused(msg.message, msg.reason); + case "endedId": + this.#end(msg.id, msg.lost ?? false); break; - case "endedId": { - const live = this.#claim(msg.id); - this.#history.end(msg.id); - this.#claims.delete(msg.id); - const wire = this.#route(live.route); - if (live.path === undefined) { - wire.unnamed.delete(msg.id); - break; - } - wire.claims.delete(live.path); - wire.withheld.delete(msg.id); - this.#change(live.route, live.path, undefined); - break; - } case "skipped": break; + case "active": + case "update": case "ended": - // Lite-07 ends a claim by its Announce ID only. - throw new ProtocolViolation("ANNOUNCE_END by path on lite-07"); + // Lite-07 names every claim's instance, and ends one by its Announce ID. + throw new ProtocolViolation(`${msg.status} announcement on lite-07`); } } } diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 2111f82702c..7aa2edf75a8 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -149,21 +149,24 @@ test("hop 0 decodes as absent", async () => { expect(got.hop).toBeUndefined(); }); -test("lite-07 Node ID is never 0 or qualified", async () => { - for (const id of [0n, (1n << 63n) | 7n]) { - await expect(decodeParam(PARAM_HOP, encodeVarint(id, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); - } - const qualified = new Setup({ hop: toHop((1n << 63n) | 7n) }); - await expect(bytes((w) => qualified.encode(w, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); +// An endpoint declares no Node ID, so it sends none, and reads a peer's only to check its form: +// a non-zero Node ID, then its Start. +test("lite-07 SETUP sends no Node ID and checks the one it is sent", async () => { + const v = Version.DRAFT_07; + const sent = await roundTrip(new Setup({ hop: toHop(7n) }), v); + expect(sent.hop).toBeUndefined(); + + const node = (id: bigint, start?: bigint) => + concat([encodeVarint(id, v), ...(start === undefined ? [] : [encodeVarint(start, v)])]); + expect((await decodeParam(PARAM_HOP, node(7n, 9n), v)).hop).toBeUndefined(); + await expect(decodeParam(PARAM_HOP, node(0n, 9n), v)).rejects.toThrow(); + await expect(decodeParam(PARAM_HOP, node(7n), v)).rejects.toThrow(); + await expect(decodeParam(PARAM_HOP, concat([node(7n, 9n), new Uint8Array([0])]), v)).rejects.toThrow(); }); test("SETUP with implementation round-trips", async () => { - const got = await roundTrip( - new Setup({ hop: toHop(7n), implementation: "moq-ffi/0.4.12 moq-net-rs/0.3.10" }), - Version.DRAFT_07, - ); + const got = await roundTrip(new Setup({ implementation: "moq-ffi/0.4.12 moq-net-rs/0.3.10" }), Version.DRAFT_07); expect(got.implementation).toBe("moq-ffi/0.4.12 moq-net-rs/0.3.10"); - expect(got.hop).toBe(toHop(7n)); }); test("an empty implementation is omitted rather than encoded", async () => { @@ -239,20 +242,16 @@ test("SETUP refuses an empty token", async () => { await expect(Setup.decode(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); }); -test("SETUP route key round-trips on lite-07 only, at exactly 96 bytes", async () => { - const proof = new Uint8Array(96).fill(7); - const msg = new Setup({ routeKey: proof }); - const wire = await bytes((w) => msg.encode(w, Version.DRAFT_07), Version.DRAFT_07); - const got = await Setup.decode(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); - expect(got.routeKey).toEqual(proof); - - await expect(bytes((w) => msg.encode(w, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); - // An older version ignores the parameter like any unknown one. - expect((await decodeParam(0x8n, proof, Version.DRAFT_06)).routeKey).toBeUndefined(); - - const short = new Setup({ routeKey: new Uint8Array(95) }); - await expect(bytes((w) => short.encode(w, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); - await expect(decodeParam(0x8n, new Uint8Array(95), Version.DRAFT_07)).rejects.toThrow(); +test("SETUP carries no Hop ID on lite-07, and reads past a peer's Node ID", async () => { + const msg = new Setup({ hop: toHop(7n) }); + // An endpoint forwards nothing, so it declares no Node ID. + expect([...(await bytes((w) => msg.encode(w, Version.DRAFT_07), Version.DRAFT_07))]).toEqual([0x01, 0x00]); + // A forwarding peer's Node ID and start. + expect((await decodeParam(0x5n, new Uint8Array([7, 3]), Version.DRAFT_07)).hop).toBeUndefined(); + // A Node ID of 0 names nobody, a start must follow it, and nothing may follow that. + for (const value of [[0, 3], [7], [7, 3, 1]]) { + await expect(decodeParam(0x5n, new Uint8Array(value), Version.DRAFT_07)).rejects.toThrow(); + } }); test("older SETUP versions ignore the unknown Implementation parameter before parsing it", async () => { diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index 63c665e77ed..77edc28ae35 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -9,7 +9,7 @@ import { type Hop, toHop, wireHop } from "../hop.ts"; import { encodeVarint, Reader, type Writer } from "../stream.ts"; import { decodeUtf8 } from "../util/utf8.ts"; import * as Message from "./message.ts"; -import { hasAuth, hasImplementation, hasRouteKey, hasRoutes, hasSetupStream, type Version } from "./version.ts"; +import { hasAuth, hasImplementation, hasRoutes, hasSetupStream, type Version } from "./version.ts"; const clientParameters = new WeakSet(); @@ -24,18 +24,20 @@ const PARAM_PROBE = 0x1n; const PARAM_PATH = 0x2n; /** Setup Parameter id for the client's intended {@link Role} (client-only). */ const PARAM_ROLE = 0x3n; -/** Setup Parameter id for the endpoint's Hop ID, or from lite-07 its Node ID. */ +/** Setup Parameter id for the endpoint's Hop ID, or from lite-07 a forwarding node's Node ID. */ const PARAM_HOP = 0x5n; -/** The top bit, which marks a Node ID a relay qualified; an endpoint never declares one. */ -const QUALIFIED = 1n << 63n; /** Setup Parameter id for the endpoint's implementation name and version. */ const PARAM_IMPLEMENTATION = 0x6n; /** Setup Parameter id for the client's connection credential (client-only, lite-07+). */ const PARAM_TOKEN = 0x7n; -/** Setup Parameter id for the sender's route key proof (lite-07+). */ -const PARAM_ROUTE_KEY = 0x8n; -/** A route key proof's size: an Ed25519 public key, then its signature. */ -const ROUTE_KEY_PROOF_SIZE = 96; + +/** Check a lite-07 Node ID parameter: a non-zero id, the node's start, and nothing after. */ +async function checkNode(value: Uint8Array, version: Version): Promise { + const r = new Reader(undefined, value, version); + const relay = await r.u62(); + await r.u62(); + if (relay === 0n || !(await r.done())) throw new Error("setup Node ID is malformed"); +} /** SETUP only carries negotiation parameters, so it gets a far smaller cap than other messages. */ const MAX_SETUP_SIZE = 0xffff; @@ -185,8 +187,6 @@ export interface SetupProps { token?: Uint8Array; /** See {@link Setup.implementation}. Omitted by default. */ implementation?: string; - /** See {@link Setup.routeKey}. Omitted by default. */ - routeKey?: Uint8Array; } /** @@ -220,9 +220,9 @@ export class Setup { * This endpoint's Hop ID. The peer uses it to filter announcements and * subscriptions whose route flows through this endpoint (lite-06 removed the * per-stream `exclude_hop` in its favor). `undefined` when the endpoint declares - * no identity; a wire value of 0 decodes the same way. From lite-07 it is the - * endpoint's Node ID instead, never 0 or with the top bit set, so a peer that - * receives its own has reached itself. + * no identity; a wire value of 0 decodes the same way. Lite-07 carries none: the + * parameter is a forwarding node's Node ID there, which an endpoint never declares + * and reads past. */ hop?: Hop; @@ -238,20 +238,13 @@ export class Setup { */ implementation?: string; - /** - * Proof that the sender holds its route key, bound to this session (lite-07+): the - * Ed25519 public key, then its signature over keying material exported from the session. - */ - routeKey?: Uint8Array; - - constructor({ probe, path, role, hop, token, implementation, routeKey }: SetupProps = {}) { + constructor({ probe, path, role, hop, token, implementation }: SetupProps = {}) { this.probe = probe ?? ProbeLevel.None; this.path = path; this.role = role ?? Role.Both; this.hop = hop; this.token = token; this.implementation = implementation; - this.routeKey = routeKey; } static #guard(version: Version) { @@ -273,8 +266,8 @@ export class Setup { if (this.role !== Role.Both) { params.setVarint(PARAM_ROLE, this.role, version); } - if (this.hop !== undefined && this.hop !== 0n) { - if (hasRoutes(version) && this.hop >= QUALIFIED) throw new Error("setup Node ID cannot be qualified"); + // An endpoint forwards nothing, so on lite-07 it declares no Node ID. + if (this.hop !== undefined && this.hop !== 0n && !hasRoutes(version)) { params.setVarint(PARAM_HOP, wireHop(this.hop, version), version); } if (this.implementation) { @@ -285,11 +278,6 @@ export class Setup { if (this.token.byteLength === 0) throw new Error("setup token cannot be empty"); params.setBytes(PARAM_TOKEN, this.token); } - if (this.routeKey !== undefined) { - if (!hasRouteKey(version)) throw new Error("setup route key not supported for this version"); - if (this.routeKey.byteLength !== ROUTE_KEY_PROOF_SIZE) throw new Error("setup route key must be 96 bytes"); - params.setBytes(PARAM_ROUTE_KEY, this.routeKey); - } await params.encode(w); } @@ -308,12 +296,16 @@ export class Setup { const role = roleCode === undefined ? Role.Both : roleFromCode(roleCode); // Before lite-07, 0 carries no identity (it cannot be excluded), so it decodes as - // absent. A lite-07 Node ID is never 0 or qualified. - const hopRaw = await params.getVarint(PARAM_HOP, version); - if (hopRaw !== undefined && hasRoutes(version) && (hopRaw === 0n || hopRaw >= QUALIFIED)) { - throw new Error("setup Node ID must be non-zero and unqualified"); + // absent. A lite-07 Node ID is a non-zero id and the node's start, and nothing an + // endpoint uses: a peer that declares one still sends this node claims alone. + let hop: Hop | undefined; + if (hasRoutes(version)) { + const node = params.getBytes(PARAM_HOP); + if (node !== undefined) await checkNode(node, version); + } else { + const hopRaw = await params.getVarint(PARAM_HOP, version); + hop = hopRaw === undefined || hopRaw === 0n ? undefined : toHop(hopRaw); } - const hop = hopRaw === undefined || hopRaw === 0n ? undefined : toHop(hopRaw); // An older version does not know the token parameter, so it ignores it like any other. const token = hasAuth(version) ? params.getBytes(PARAM_TOKEN) : undefined; @@ -322,13 +314,7 @@ export class Setup { const implementationBytes = hasImplementation(version) ? params.getBytes(PARAM_IMPLEMENTATION) : undefined; const implementation = implementationBytes === undefined ? undefined : decodeUtf8(implementationBytes); - // Kept but not verified: nothing here files routes under the sender's key. - const routeKey = hasRouteKey(version) ? params.getBytes(PARAM_ROUTE_KEY) : undefined; - if (routeKey !== undefined && routeKey.byteLength !== ROUTE_KEY_PROOF_SIZE) { - throw new Error("setup route key must be 96 bytes"); - } - - const setup = new Setup({ probe, path, role, hop, token, implementation, routeKey }); + const setup = new Setup({ probe, path, role, hop, token, implementation }); if (pathBytes !== undefined || roleCode !== undefined || token !== undefined) clientParameters.add(setup); return setup; } diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index cd88422cc10..30dd482ffe0 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -761,10 +761,6 @@ export class Subscribe { broadcast: Path.Valid; /** The publisher instance the subscriber expects. Lite-07+. */ instance?: Instance.Valid; - /** The publisher node that serves the request, 0 for whichever the publisher selects. Lite-07+. */ - node: bigint; - /** How many leading segments of `broadcast` make up the prefix of the route it follows. Lite-07+. */ - depth: number; track: string; priority: number; /** @@ -809,8 +805,6 @@ export class Subscribe { id: bigint; broadcast: Path.Valid; instance?: Instance.Valid; - node?: bigint; - depth?: number; track: string; priority: number; order?: Order; @@ -825,8 +819,6 @@ export class Subscribe { this.id = props.id; this.broadcast = props.broadcast; this.instance = props.instance; - this.node = props.node ?? 0n; - this.depth = props.depth ?? 0; this.track = props.track; this.priority = props.priority; this.order = props.order ?? "descending"; @@ -843,7 +835,7 @@ export class Subscribe { await w.u62(this.id); await w.string(Path.encode(this.broadcast)); await encodePin(w, version, this.instance); - await encodeNode(w, version, this.node, this.depth); + await encodeNode(w, version); await w.string(this.track); await w.u8(toWire(this.priority)); @@ -864,7 +856,7 @@ export class Subscribe { const id = await r.u62(); const broadcast = Path.decode(await r.string()); const instance = await decodePin(r, version); - const { node, depth } = await decodeNode(r, version, broadcast); + await decodeNode(r, version); const track = await r.string(); const priority = fromWire(await r.u8()); @@ -881,8 +873,6 @@ export class Subscribe { id, broadcast, instance, - node, - depth, track, priority, order, diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 732be7edb80..e24e010dbe6 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -23,9 +23,8 @@ import { import type { Consumer as GroupConsumer } from "../group.ts"; import { type Hop, isAnonymous, MAX_HOPS, toHop, UNKNOWN_HOP, WireRoute } from "../hop.ts"; import * as Instance from "../instance.ts"; -import { hooks, rendezvousHash } from "../internal.ts"; +import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; -import * as Mint from "../mint.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; @@ -38,11 +37,11 @@ import { type AnnounceBroadcast, AnnounceInit, AnnounceOk, + type Claim, decodeAnnounceBroadcast, decodeAnnounceBroadcastMaybe, encodeAnnounceBroadcast, - type Offer, - ROUTE_MAX_HOPS, + ownClaim, } from "./announce.ts"; import { closeViolation } from "./error.ts"; import { Group } from "./group.ts"; @@ -212,51 +211,18 @@ const PUBLISHER_B = toHop(8n); const PUBLISHER_C = toHop(9n); const PEER = toHop(2n); -// Lite-07 origin nodes, and the route a peer advertises to each. -const NODE_A = 0x7an; -const NODE_B = 0x8bn; -// The peer's hop on a route's path, which it learned on a session of its own per publisher node. -const PEER_NODE = 2n; - -/** The Route Offer a peer sends for its route to `node`: the publisher, then the peer, at 20ms. */ -function offer(node: bigint, extra: Partial = {}): Offer { - return { - path: [ - { node, session: 0n }, - { node: PEER_NODE, session: node }, - ], - draining: false, - priority: 0, - metric: 0n, - downOnly: false, - ...extra, - }; -} - /** * Write a claim the way `version` carries it: before lite-07 with its hop chain, and on lite-07 - * under a route of its own to `node`, closed by its floor. Route IDs count from 0 per stream, so - * one helper serves one stream. + * naming its instance, at no cost. */ function claimer(version: Version) { - let routes = 0n; - return async ( - w: Writer, - suffix: Path.Valid, - { instance, hops, node }: { instance?: Instance.Valid; hops: Hop[]; node: bigint }, - ) => { + return async (w: Writer, suffix: Path.Valid, { instance, hops }: { instance?: Instance.Valid; hops: Hop[] }) => { if (version !== Version.DRAFT_07) { - await encodeAnnounceBroadcast(w, { status: "active", suffix, instance, hops }, version); + await encodeAnnounceBroadcast(w, { status: "active", suffix, hops }, version); return; } - const route = routes++; - await encodeAnnounceBroadcast( - w, - { status: "routeStart", node, prefix: 0n, suffix: Path.empty(), exact: false, offer: offer(node) }, - version, - ); - await encodeAnnounceBroadcast(w, { status: "active", suffix, route, instance }, version); - await encodeAnnounceBroadcast(w, { status: "floor", id: route }, version); + if (!instance) throw new Error("a lite-07 claim names its instance"); + await encodeAnnounceBroadcast(w, { status: "start", suffix, instance, claim: ownClaim(0n) }, version); }; } @@ -444,18 +410,22 @@ test("a lite-07 restart replaces the instance, and the next consume subscribes f const v = Version.DRAFT_07; await ok(); const first = Instance.random(); - await send((w) => claimer(v)(w, room, { instance: first, hops: [], node: NODE_A })); + await send((w) => claimer(v)(w, room, { instance: first, hops: [] })); expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { instance: first } }); const held = subscriber.consume(room); - // Another instance: a restart, and the handle already out stays. + // Another instance is another claim, started before the one it replaces ends: a restart, and + // the handle already out stays. + let last = 0n; for (const instance of [Instance.random(), Instance.random()]) { + const ended = last++; await send(async (w) => { - await encodeAnnounceBroadcast(w, { status: "restart", id: 0n, instance, cost: 3n }, v); - await encodeAnnounceBroadcast(w, { status: "floor", id: 0n }, v); + const claim = { ...ownClaim(0n), cost: 3n }; + await encodeAnnounceBroadcast(w, { status: "start", suffix: room, instance, claim }, v); + await encodeAnnounceBroadcast(w, { status: "endedId", id: ended }, v); }); const restarted = await announced.next(); - // Priced past the route's metric and this session's link. + // Priced past the claim's cost and this session's link. expect(restarted).toMatchObject({ prefix: room, kind: "restart", route: { cost: 4n } }); expect(restarted?.route.instance).toBe(instance); const fresh = subscriber.consume(room); @@ -464,10 +434,7 @@ test("a lite-07 restart replaces the instance, and the next consume subscribes f fresh.close(); } - await send(async (w) => { - await encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, v); - await encodeAnnounceBroadcast(w, { status: "floor", id: 0n }, v); - }); + await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: last }, v)); expect(await announced.next()).toMatchObject({ prefix: room, kind: "end" }); held.close(); @@ -475,6 +442,45 @@ test("a lite-07 restart replaces the instance, and the next consume subscribes f subscriber.close(); }); +// A claim whose path cannot be resolved lies in a prefix this side cannot name, so removing +// another prefix leaves it for the peer to end by its id. +test("a lite-07 unresolved claim outlives another prefix's removal", async () => { + const v = Version.DRAFT_07; + const { subscriber, send, ok, settle, sessionEnded } = announceHarness(v); + const a = subscriber.routes(Path.Pattern.subtree(Path.from("a"))); + await settle(); + await ok(); + const b = subscriber.routes(Path.Pattern.subtree(Path.from("b"))); + await settle(); + await ok(); + + // A base and a rest that each fit a path, and together do not. + const long = "x".repeat(Path.MAX_BYTES - 8); + const start = (suffix: Path.Valid, pathBase?: { distance: bigint; keep: number }) => + send((w) => + encodeAnnounceBroadcast( + w, + { status: "start", suffix, pathBase, instance: Instance.random(), claim: ownClaim(0n) }, + v, + ), + ); + await start(Path.from(`a/${long}`)); + await start(Path.from(long), { distance: 1n, keep: 2 }); + + b.close(); + await settle(); + await ok(); + const end = () => send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n, lost: false }, v)); + await end(); + expect(a.closed.peek()).toBeUndefined(); + // That retired the id, so naming it again is the violation. + await end(); + expect((await sessionEnded())?.closeCode).toBe(SessionCode.ProtocolViolation); + + a.close(); + subscriber.close(); +}); + // A replaced prefix served everything consumed beneath it, so those paths subscribe fresh too, // whether the replacement arrives as a lite-07 restart or as an end then a start. test.each([ @@ -488,14 +494,14 @@ test.each([ const job = Path.from("pool/job"); await ok(); - await send((w) => claimer(version)(w, pool, { instance: named(version, "a"), hops: [PUBLISHER_A], node: NODE_A })); + await send((w) => claimer(version)(w, pool, { instance: named(version, "a"), hops: [PUBLISHER_A] })); expect(await announced.next()).toMatchObject({ prefix: pool, kind: "start" }); const held = subscriber.consume(job); if (version === Version.DRAFT_07) { await send(async (w) => { - await encodeAnnounceBroadcast(w, { status: "restart", id: 0n, instance: named(version, "b") }, version); - await encodeAnnounceBroadcast(w, { status: "floor", id: 0n }, version); + await claimer(version)(w, pool, { instance: named(version, "b"), hops: [] }); + await encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, version); }); expect(await announced.next()).toMatchObject({ prefix: pool, kind: "restart" }); } else { @@ -2169,11 +2175,7 @@ async function unpinnedPool(version: Version, streams: FakeStream[], announced: const path = Path.from("pool"); await send((writer) => new AnnounceOk(PEER, 0).encode(writer, version)); await send((writer) => - encodeAnnounceBroadcast( - writer, - { status: "active", suffix: path, hops: [PUBLISHER_A], instance: named(version, "a") }, - version, - ), + encodeAnnounceBroadcast(writer, { status: "active", suffix: path, hops: [PUBLISHER_A] }, version), ); await announced.next(); const withdraw = async () => { @@ -2188,11 +2190,7 @@ async function unpinnedPool(version: Version, streams: FakeStream[], announced: }; const announce = async () => { await send((writer) => - encodeAnnounceBroadcast( - writer, - { status: "active", suffix: path, hops: [PUBLISHER_B], instance: named(version, "b") }, - version, - ), + encodeAnnounceBroadcast(writer, { status: "active", suffix: path, hops: [PUBLISHER_B] }, version), ); await announced.next(); }; @@ -2404,16 +2402,7 @@ test("consumes resolve the serving prefix and pin its instance", async () => { const pool = Path.from("pool"); const job = Path.from("pool/job"); const instance = Instance.random(); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: pool, route: 0n, instance }); - await send({ status: "floor", id: 0n }); + await send({ status: "start", suffix: pool, instance, claim: ownClaim(0n) }); await announced.next(); const held = subscriber.consume(job); const info = held @@ -2424,20 +2413,11 @@ test("consumes resolve the serving prefix and pin its instance", async () => { await first.reading; const reader = new Reader(undefined, new Uint8Array(Buffer.concat(first.written)), version); expect(await reader.u53()).toBe(StreamId.Track); - expect(await Track.decode(reader, version)).toMatchObject({ instance, node: NODE_A }); + expect(await Track.decode(reader, version)).toMatchObject({ instance }); // The more specific source's instance shadows the covering source's. const other = Instance.random(); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: job, route: 1n, instance: other }); - await send({ status: "floor", id: 1n }); + await send({ status: "start", suffix: job, instance: other, claim: ownClaim(0n) }); await announced.next(); const fresh = subscriber.consume(job); expect(fresh.closed).not.toBe(held.closed); @@ -2450,10 +2430,9 @@ test("consumes resolve the serving prefix and pin its instance", async () => { await second.reading; const freshReader = new Reader(undefined, new Uint8Array(Buffer.concat(second.written)), version); await freshReader.u53(); - expect(await Track.decode(freshReader, version)).toMatchObject({ instance: other, node: NODE_B }); + expect(await Track.decode(freshReader, version)).toMatchObject({ instance: other }); await send({ status: "endedId", id: 1n }); - await send({ status: "floor", id: 1n }); await announced.next(); const fallback = subscriber.consume(job); expect(fallback.closed).toBe(held.closed); @@ -2476,10 +2455,10 @@ test.each([Version.DRAFT_06, Version.DRAFT_07])( const pool = Path.from("pool"); const job = Path.from("pool/job"); const claim = claimer(version); - await send((w) => claim(w, pool, { instance: named(version, "a"), hops: [PUBLISHER_A], node: NODE_A })); + await send((w) => claim(w, pool, { instance: named(version, "a"), hops: [PUBLISHER_A] })); await announced.next(); const held = subscriber.consume(job); - await send((w) => claim(w, job, { instance: named(version, "b"), hops: [PUBLISHER_B], node: NODE_B })); + await send((w) => claim(w, job, { instance: named(version, "b"), hops: [PUBLISHER_B] })); await announced.next(); const fresh = subscriber.consume(job); expect(fresh.closed).not.toBe(held.closed); @@ -2509,11 +2488,7 @@ test.each([Version.DRAFT_05, Version.DRAFT_06])( await new AnnounceOk(PEER, 0).encode(peer, version); const pool = Path.from("pool"); const job = Path.from("pool/job"); - await encodeAnnounceBroadcast( - peer, - { status: "active", suffix: pool, instance: named(version, "a"), hops: [PUBLISHER_A] }, - version, - ); + await encodeAnnounceBroadcast(peer, { status: "active", suffix: pool, hops: [PUBLISHER_A] }, version); await announced.next(); const held = subscriber.consume(job); const pending = held @@ -2522,11 +2497,7 @@ test.each([Version.DRAFT_05, Version.DRAFT_06])( .catch((err: unknown) => err); await opened(1); await streams[1].reading; - await encodeAnnounceBroadcast( - peer, - { status: "active", suffix: job, instance: named(version, "b"), hops: [PUBLISHER_B] }, - version, - ); + await encodeAnnounceBroadcast(peer, { status: "active", suffix: job, hops: [PUBLISHER_B] }, version); await announced.next(); expect(await pending).toBeInstanceOf(Error); await streams[1].aborted; @@ -3912,1101 +3883,143 @@ async function routedStream(options?: RouteOptions, scope?: Path.Pattern) { return { subscriber, announced, send, raw, edits, settled, closes, version, trackRequest, another, opened }; } -// A route or claim whose forwarded content this subscriber refuses is withdrawn alone: the session, -// the peer's other route, and its claims stay, and the ids after it line up. Mirrors rs/moq-net. -test("a lite-07 refused route or claim withdraws only itself", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const [a, b, c, d] = ["live/a", "live/b", "live/c", "live/d"].map((path) => Path.from(path)); - const instance = Instance.parse("i"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: a, route: 0n, instance }); - await send({ status: "active", suffix: b, route: 1n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "start" }); - expect(await announced.next()).toMatchObject({ prefix: b, kind: "start" }); - - // ROUTE_UPDATE of Route ID 0 with a flag no version defines, and the field it might announce. - raw([7, 8, 0, 1, 5, 0, 0x80, 128, 0, 42]); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "offline" }); - - // Announce ID 2: an ANNOUNCE_START under Route ID 1 whose path has an empty segment. - raw([0, 13, 0, 0, 4, ...new TextEncoder().encode("x//y"), 1, 1, 0x69, 0, 0, 0]); - await send({ status: "endedId", id: 2n }); - await send({ status: "active", suffix: c, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: c, kind: "start" }); - - // Forwarded usably again, the route's claims come back. - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A) }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "start" }); - - // ROUTE_START to the reserved node, not exact, takes Route ID 2, and its claims never show. - raw([6, 10, 0, 0, 0, 0, 1, 5, 0, 0, 128, 0]); - await send({ status: "active", suffix: d, route: 2n, instance }); - await send({ status: "floor", id: 2n, revision: 0n }); - await send({ status: "endedId", id: 3n }); - await send({ status: "floor", id: 1n, revision: 2n }); - expect(await announced.next()).toMatchObject({ prefix: c, kind: "end" }); - - announced.close(); - subscriber.close(); -}); - -// A claim this subscriber refuses was not withdrawn by its origin: it goes offline, and while its -// route holds one, the route's floors certify nothing, so another claim's end there goes offline -// too. Mirrors rs/moq-net. -test("a lite-07 refused claim goes offline, its route certifying nothing meanwhile", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const [a, b, e] = ["live/a", "live/b", "live/e"].map((path) => Path.from(path)); - const instance = Instance.parse("i"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: a, route: 0n, instance }); - await send({ status: "active", suffix: b, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "start" }); - expect(await announced.next()).toMatchObject({ prefix: b, kind: "start" }); - - // ANNOUNCE_RESTART of Announce ID 0 to an empty instance. JS reads no Lite-06 Chain, so an - // ANNOUNCE_UPDATE has nothing it could refuse. - const refuse = () => raw([3, 5, 0, 0, 0, 0, 0]); - refuse(); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "offline" }); - await send({ status: "endedId", id: 1n }); - await send({ status: "floor", id: 0n, revision: 2n }); - expect(await announced.next()).toMatchObject({ prefix: b, kind: "offline" }); - - // A usable restart brings it back, and refusing the next takes it offline again. - await send({ status: "restart", id: 0n, instance: Instance.parse("j") }); - await send({ status: "floor", id: 0n, revision: 3n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "start" }); - refuse(); - await send({ status: "floor", id: 0n, revision: 4n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "offline" }); - - // Once it ends, the route's floors certify again. - await send({ status: "endedId", id: 0n }); - await send({ status: "active", suffix: e, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 5n }); - expect(await announced.next()).toMatchObject({ prefix: e, kind: "start" }); - await send({ status: "endedId", id: 2n }); - await send({ status: "floor", id: 0n, revision: 6n }); - expect(await announced.next()).toMatchObject({ prefix: e, kind: "end" }); - - announced.close(); - subscriber.close(); -}); - -// A peer may carry one origin's claims on two routes, each at a prefix of its own. A claim this -// node refuses on one of them is not withdrawn, and the other still certifies it: it stays shown. -test("a lite-07 refused claim another route still certifies stays shown", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const live = Path.from("live"); - const x = Path.from("live/x"); - const instance = Instance.parse("i"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start" }); - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 0n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 1 } }); - - // ANNOUNCE_RESTART of Announce ID 0 to an empty instance. - await raw([3, 5, 0, 0, 0, 0, 0]); - await send({ status: "floor", id: 0n, revision: 1n }); - // Another node's claim marks the refusal as applied: live/x neither went offline nor ended. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: Path.from("live/z"), route: 2n, instance }); - await send({ status: "floor", id: 2n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/z"), kind: "start" }); - - // Once the other route lets it go too, nothing certifies its withdrawal: it goes offline. - await send({ status: "routeEnd", id: 1n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "offline" }); - - announced.close(); - subscriber.close(); -}); - -// What the refusing route's last floor certified still counts against an older floor of another -// route: a lagging route that never had the claim proves no withdrawal of it. -test("a lite-07 refused claim a lagging route never had goes offline", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const live = Path.from("live"); - const x = Path.from("live/x"); - const y = Path.from("live/y"); - const instance = Instance.parse("i"); +const claimOf = (extra: Partial = {}): Claim => ({ ...ownClaim(0n), ...extra }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 7n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start" }); - // The second route lags at revision 5, before live/x existed. - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: y, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 5n }); - // The first route's newer floor has no live/y, so the lagging copy of it stays held back. - - // ANNOUNCE_RESTART of Announce ID 0 to an empty instance. - await raw([3, 5, 0, 0, 0, 0, 0]); - await send({ status: "floor", id: 0n, revision: 8n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "offline" }); - - announced.close(); - subscriber.close(); -}); - -// A claim at the session root has the empty path, which is a path all the same: its updates, -// restarts, and end apply as any other's. +// A claim starts, changes, and ends by its Announce ID, and its path is free once it ends. test("a lite-07 claim at the root updates and ends", async () => { const { subscriber, announced, send } = await routedStream(); const root = Path.empty(); + const i = Instance.parse("i"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: root, route: 0n, instance: Instance.parse("i") }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: root, kind: "start" }); + await send({ status: "start", suffix: root, instance: i, claim: claimOf() }); + // Priced past this session's link. + expect(await announced.next()).toMatchObject({ prefix: root, kind: "start", route: { instance: i, cost: 1n } }); + + await send({ status: "change", id: 0n, claim: claimOf({ cost: 4n }) }); + expect(await announced.next()).toMatchObject({ prefix: root, kind: "update", route: { cost: 5n } }); - await send({ status: "restart", id: 0n, instance: Instance.parse("j") }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: root, kind: "restart" }); + // Another epoch of the instance restarts what was read through it. + await send({ status: "change", id: 0n, claim: claimOf({ epoch: 1n, cost: 4n }) }); + expect(await announced.next()).toMatchObject({ prefix: root, kind: "restart", route: { epoch: 1n } }); - await send({ status: "endedId", id: 0n }); - await send({ status: "floor", id: 0n, revision: 2n }); + await send({ status: "endedId", id: 0n, lost: false }); expect(await announced.next()).toMatchObject({ prefix: root, kind: "end" }); // Its path is free again, so starting it anew is no duplicate. - await send({ status: "active", suffix: root, route: 0n, instance: Instance.parse("k") }); - await send({ status: "floor", id: 0n, revision: 3n }); + await send({ status: "start", suffix: root, instance: i, claim: claimOf() }); expect(await announced.next()).toMatchObject({ prefix: root, kind: "start" }); announced.close(); subscriber.close(); }); -// A route this subscriber refused is no view of its node: a newer floor on it hides nothing -// another route carries, as rs/moq-net's node never holds the route. -test("a lite-07 refused route's floors hide no other route's claims", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const instance = Instance.parse("i"); - // One varint byte, so the raw message below spells it. - const node = 7n; - - await send({ - status: "routeStart", - prefix: 0n, - node: node, - suffix: Path.empty(), - exact: false, - offer: offer(node), - }); - await send({ status: "active", suffix: Path.from("live/x"), route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/x"), kind: "start" }); - - // ROUTE_START to the node at live under Prefix ID 0, not exact, with a flag no version defines, - // then a newer floor without live/x. - await raw([6, 15, 7, 0, 4, ...new TextEncoder().encode("live"), 0, 1, 7, 0, 0x80, 128, 0, 42]); - await send({ status: "floor", id: 1n, revision: 5n }); - - // What shows next is the first route's own new claim, not live/x withdrawn. - await send({ status: "active", suffix: Path.from("live/y"), route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/y"), kind: "start" }); - - announced.close(); - subscriber.close(); -}); - -// A route refused once live leaves what its last floor certified, as an ended one does: the claims -// it reads afterwards never rewrite that. -test("a lite-07 route refused once live leaves its last floor as it was", async () => { - const { subscriber, announced, send, raw } = await routedStream(); - const live = Path.from("live"); - const instance = Instance.parse("i"); - const node = 7n; - const x = Path.from("live/x"); - - // Both routes carry live/x, the first at revision 5 and the second lagging at 3. - await send({ - status: "routeStart", - prefix: 0n, - node: node, - suffix: Path.empty(), - exact: false, - offer: offer(node), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 5n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start" }); - await send({ status: "routeStart", prefix: 0n, node: node, suffix: live, exact: false, offer: offer(node) }); - await send({ status: "active", suffix: x, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 3n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 1 } }); - - // The first route is refused, then ends live/x at a floor no view takes. - await raw([7, 8, 0, 1, 5, 0, 0x80, 128, 0, 42]); - await send({ status: "endedId", id: 0n }); - await send({ status: "floor", id: 0n, revision: 6n }); - - // The second route's next floor still has live/x, as revision 5 did: what shows next is - // another node's claim, not live/x withdrawn. - await send({ status: "floor", id: 1n, revision: 4n }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: Path.from("live/z"), route: 2n, instance }); - await send({ status: "floor", id: 2n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/z"), kind: "start" }); - - announced.close(); - subscriber.close(); -}); - -// Two routes carry one origin's claims, and a withdrawal reaches one first. Of the floors that -// certify a claim, the newest decides whether it exists, so the lagging route's copy is held back -// rather than selected and refused: also once the newer route ends. -test("a lite-07 claim another route's newer floor withdrew is not selected", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const live = Path.from("live"); - const x = Path.from("live/x"); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - const y = Instance.parse("y"); - - // NODE_A claims live/x and live/y, cheaply, on both routes at revision 0. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "active", suffix: Path.from("live/y"), route: 0n, instance: y }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/y"), kind: "start" }); - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "active", suffix: Path.from("live/y"), route: 1n, instance: y }); - await send({ status: "floor", id: 1n, revision: 0n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 1 } }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/y"), kind: "update", route: { depth: 1 } }); - // A dearer NODE_B claims live/x. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: x, route: 2n, instance: b }); - await send({ status: "floor", id: 2n, revision: 0n }); - - // NODE_A withdraws live/x at revision 1, which only the first route has delivered: the - // lagging route's copy is held back, so the path moves to NODE_B. - await send({ status: "endedId", id: 0n }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "restart", route: { node: NODE_B } }); - const first = await trackRequest(x, 0); - expect(first.request).toMatchObject({ instance: b, node: NODE_B }); - - // The first route goes, and a third, as far behind, then lands its copy: what the ended - // route's floor certified still holds, so a fresh pick of live/x still passes over the cheaper - // copy. - await send({ status: "routeEnd", id: 0n }); - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: x, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 3n, instance: a }); - await send({ status: "floor", id: 3n, revision: 0n }); - const second = await trackRequest(x, 1); - expect(second.request).toMatchObject({ instance: b, node: NODE_B }); - - // The lagging route catches up, and nothing more shows for live/x. - await send({ status: "endedId", id: 2n }); - await send({ status: "floor", id: 1n, revision: 1n }); - await send({ status: "active", suffix: Path.from("live/z"), route: 1n, instance: y }); - await send({ status: "floor", id: 1n, revision: 2n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/z"), kind: "start" }); - - first.consumed.close(); - second.consumed.close(); - announced.close(); - subscriber.close(); - await Promise.all([first.info, second.info]); -}); - -// A floor that certifies nothing withdraws no knowledge: the revision its route's last floor -// certified still decides, so the lagging route's withdrawn copy stays held back. -test("a lite-07 floor that certifies nothing keeps the withdrawal its route certified", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const live = Path.from("live"); - const x = Path.from("live/x"); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - - // NODE_A claims live/x cheaply on both routes at revision 0, and a dearer NODE_B claims it too. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 1 } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: x, route: 2n, instance: b }); - await send({ status: "floor", id: 2n, revision: 0n }); - - // NODE_A withdraws live/x at revision 1 on the first route, whose next floor certifies nothing. - await send({ status: "endedId", id: 0n }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "restart", route: { node: NODE_B } }); - await send({ status: "floor", id: 0n }); - // Another node's claim marks the uncertified floor as applied. - const w = Path.from("live/w"); - await send({ status: "active", suffix: w, route: 2n, instance: b }); - await send({ status: "floor", id: 2n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: w, kind: "start" }); - - const pick = await trackRequest(x, 0); - expect(pick.request).toMatchObject({ instance: b, node: NODE_B }); - - pick.consumed.close(); - announced.close(); - subscriber.close(); - await pick.info; -}); - -// A kept floor decides only while a live one certifies the path: once the last certifying route -// ends, a claim another route carries uncertified shows again. -test("a lite-07 uncertified claim shows once its last certifier ends", async () => { +// The peer only lost its way to a claim it ends as lost, which its publisher never withdrew. +test("a lite-07 claim the peer lost goes offline", async () => { const { subscriber, announced, send } = await routedStream(); - const live = Path.from("live"); - const x = Path.from("live/x"); - const y = Path.from("live/y"); - const a = Instance.parse("a"); - - // The first route certifies NODE_A's claims at revision 1, without live/x. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: y, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: y, kind: "start" }); - // The second carries live/x under a floor that certifies nothing: held back. - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "active", suffix: y, route: 1n, instance: a }); - await send({ status: "floor", id: 1n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: y, kind: "update", route: { depth: 1 } }); - - await send({ status: "routeEnd", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - + const room = Path.from("room"); + await send({ status: "start", suffix: room, instance: Instance.parse("i"), claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start" }); + await send({ status: "endedId", id: 0n, lost: true }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "offline" }); announced.close(); subscriber.close(); }); -// A route's kept floor that a later one prunes re-shows the claims it held back, though the -// pruning floor carries no batch. -test("a lite-07 claim a pruned floor held back shows without a batch", async () => { +// The peer finishing its stream is leaving: what it claimed was never withdrawn. +test("a lite-07 peer finishing its stream takes its claims offline", async () => { const { subscriber, announced, send } = await routedStream(); - const x = Path.from("live/x"); - const y = Path.from("live/y"); - const w = Path.from("live/w"); - const a = Instance.parse("a"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: y, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: y, kind: "start" }); - // An older revision adds live/x: the kept revision 1 holds it back. - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - // A floor that certifies nothing leaves no floor to decide live/x, so it shows. - await send({ status: "floor", id: 0n }); - // Another node's claim marks the floors as applied. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: w, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - - announced.close(); - subscriber.close(); -}); - -// A claim above a newer floor's region is older knowledge there: a consume below that region does -// not select it, as Rust's `covering` presents no claim above the newest certifier. -test("a lite-07 consume skips a claim above a newer floor's region", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const root = Path.from("live"); - const below = Path.from("live/x"); - const a = Instance.parse("a"); - - // NODE_A claims live at revision 0; a dearer NODE_B claims it too. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: root, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: root, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: root, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - // NODE_A's route at live/x presents only live/x/m there at revision 1: it withdrew live. - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: below, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: Path.from("live/x/m"), route: 2n, instance: a }); - await send({ status: "floor", id: 2n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/x/m"), kind: "start" }); - - const pick = await trackRequest(below, 0); - expect(pick.request).toMatchObject({ instance: a, node: NODE_B }); - - pick.consumed.close(); - announced.close(); - subscriber.close(); - await pick.info; -}); - -// A DEAD whose far end is gone takes a reader's only claim offline, not withdrawn: the publisher -// may still hold it, whatever the coverage the route took with it. -test("a lite-07 DEAD takes a reader's claim offline at its own prefix", async () => { - const below = Path.from("live/x"); - const { subscriber, announced, send } = await routedStream(undefined, Path.Pattern.subtree(below)); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: below, route: 0n, instance: Instance.parse("a") }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: below, kind: "start" }); - - const hop = { node: PEER_NODE, session: NODE_A }; - await send({ status: "dead", dead: { kind: "closed", hop, far: NODE_A, gone: true, moved: 0n } }); - expect(await announced.next()).toMatchObject({ prefix: below, kind: "offline" }); - - announced.close(); - subscriber.close(); -}); - -// A DEAD ending several routes through its hop shows each reader its loss once, at the path it -// presents, whichever route went first: a broader reader's recheck does not withdraw it first. -test("a lite-07 DEAD takes a narrower reader's claim offline beside a broader reader", async () => { - const below = Path.from("live/x"); - const { subscriber, announced, send, another } = await routedStream(); - const hop = { node: PEER_NODE, session: NODE_A }; - // An unrelated route through the same hop goes first. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { path: [{ node: NODE_B, session: 0n }, { node: NODE_A, session: 1n }, hop] }), - }); - await send({ status: "active", suffix: Path.from("other"), route: 0n, instance: Instance.parse("b") }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: below, route: 1n, instance: Instance.parse("a") }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("other"), kind: "start" }); - expect(await announced.next()).toMatchObject({ prefix: below, kind: "start" }); - const { announced: under } = await another(Path.Pattern.subtree(below)); - expect(await under.next()).toMatchObject({ prefix: below, kind: "start" }); - - await send({ status: "dead", dead: { kind: "closed", hop, far: NODE_A, gone: true, moved: 0n } }); - expect(await under.next()).toMatchObject({ prefix: below, kind: "offline" }); - - under.close(); - announced.close(); - subscriber.close(); -}); - -// A reader below a newer floor's region is not shown a claim above it, as a consume there skips -// it: the covering claim it sees at its own prefix is the one that floor leaves current. -test("a lite-07 reader skips a claim above a newer floor's region", async () => { - const { subscriber, announced, send, another } = await routedStream(); - const root = Path.from("live"); - const below = Path.from("live/x"); - const a = Instance.parse("a"); - - // NODE_A claims live at revision 0; a dearer NODE_B claims it too. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: root, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: root, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: root, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - // NODE_A's route at live/x presents only live/x/m there at revision 1: it withdrew live. - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: below, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: Path.from("live/x/m"), route: 2n, instance: a }); - await send({ status: "floor", id: 2n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/x/m"), kind: "start" }); - - const { announced: under } = await another(Path.Pattern.subtree(below)); - const shown = [await under.next(), await under.next()]; - expect(shown).toContainEqual( - expect.objectContaining({ prefix: below, route: expect.objectContaining({ node: NODE_B }) }), - ); - expect(shown).not.toContainEqual( - expect.objectContaining({ prefix: below, route: expect.objectContaining({ node: NODE_A }) }), - ); - - under.close(); - announced.close(); - subscriber.close(); -}); - -// A route refused once live stops covering, as an ended one does: a held consume a narrower floor -// of it took off a broader claim is routable again once that floor is gone. -test("a lite-07 route refused once live gives a held consume back its broader claim", async () => { - const { subscriber, announced, send, raw, trackRequest, opened } = await routedStream(); - const live = Path.from("live"); - const below = Path.from("live/x"); - const y = Path.from("live/x/y"); - const minted = Mint.fresh(); - - // NODE_A claims live under a floor that certifies nothing, and a consume of live/x/y takes it. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: live, route: 0n, instance: minted }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: live, kind: "start" }); - const held = await trackRequest(y, 0); - expect(held.request).toMatchObject({ node: NODE_A }); - - // NODE_A's route at live/x presents only live/x/m there at revision 1, so live no longer - // covers live/x/y. - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: below, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: Path.from("live/x/m"), route: 1n, instance: minted }); - await send({ status: "floor", id: 1n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/x/m"), kind: "start" }); - await held.info; - - // That route is refused: nothing certifies live/x/y any more, so live covers it again. - await raw([7, 8, 1, 1, 5, 0, 0x80, 128, 0, 42]); - expect(await announced.next()).toMatchObject({ prefix: Path.from("live/x/m"), kind: "offline" }); - const info = held.consumed - .track("audio") - .info() - .then( - () => "answered", - () => "refused", - ); - expect(await Promise.race([opened(1).then(() => "opened"), info])).toBe("opened"); - - held.consumed.close(); - announced.close(); - subscriber.close(); - await info; -}); - -// A route that cannot be used for a while keeps its claims' place in a tie, so the announcements -// and the consumes still agree once it recovers, as a Rust entry keeps its id. -test("a lite-07 tie keeps its winner across a route's unusable spell", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const x = Path.from("live/x"); - const a = Instance.parse("a"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { node: NODE_B } }); - // NODE_A's route crosses this session, then recovers. - const crossing = [ - { node: NODE_A, session: 0n }, - { node: subscriber.hop, session: 1n }, - ...offer(NODE_A).path.slice(1), - ]; - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A, { path: crossing }) }); - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A) }); - // Another claim marks the updates as applied. - const w = Path.from("live/w"); - await send({ status: "active", suffix: w, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: w, kind: "start" }); - - const pick = await trackRequest(x, 0); - expect(pick.request).toMatchObject({ instance: a, node: NODE_B }); - - pick.consumed.close(); - announced.close(); - subscriber.close(); - await pick.info; -}); - -// Lite-07 carries a minted instance, as a relay forwards a legacy publisher's claim, so a consume -// pinned to one asks for it rather than for whichever instance wins the path. -test("a lite-07 consume pinned to a minted instance asks for it", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const x = Path.from("live/x"); - const a = Instance.parse("a"); - const minted = Mint.fresh(); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - // A dearer route carries the minted instance. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: x, route: 1n, instance: minted }); - await send({ status: "floor", id: 1n, revision: 0n }); - // Another claim marks the floor as applied. - const w = Path.from("live/w"); - await send({ status: "active", suffix: w, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: w, kind: "start" }); - - const pick = await trackRequest(x, 0, minted); - expect(pick.request).toMatchObject({ instance: minted, node: NODE_B }); - - pick.consumed.close(); + const room = Path.from("room"); + await send({ status: "start", suffix: room, instance: Instance.parse("i"), claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start" }); + subscriber.announceFinished(); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "offline" }); announced.close(); subscriber.close(); - await pick.info; }); -// A lagging route's copy of a claim takes the cost the newest certifying floor gives it, so a -// re-priced origin does not keep winning on the cost it had. -test("a lite-07 lagging copy carries the cost a newer floor certified", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream({ claims: true }); - const live = Path.from("live"); - const x = Path.from("live/x"); - const a = Instance.parse("a"); - const b = Instance.parse("b"); +// The unavailable bit counts only on a run this node already holds: a claim first told +// unavailable is not there, and one it held turns unavailable and stays. +test("a lite-07 claim is taken once it is told available, and held while unavailable", async () => { + const { subscriber, announced, send, settled } = await routedStream(); + const [held, late] = [Path.from("held"), Path.from("late")]; + const i = Instance.parse("i"); + + await send({ status: "start", suffix: late, instance: i, claim: claimOf({ unavailable: true }) }); + await send({ status: "start", suffix: held, instance: i, claim: claimOf() }); + // Nothing can serve the claim told unavailable first, so only the other shows. + expect(await announced.next()).toMatchObject({ prefix: held, kind: "start", route: { available: true } }); + + await send({ status: "change", id: 1n, claim: claimOf({ unavailable: true }) }); + expect(await announced.next()).toMatchObject({ prefix: held, kind: "update", route: { available: false } }); + await send({ status: "change", id: 1n, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: held, kind: "update", route: { available: true } }); + + await send({ status: "change", id: 0n, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: late, kind: "start", route: { available: true } }); + + // Another run told unavailable is not taken, and the one held before it is lost. + await send({ status: "change", id: 0n, claim: claimOf({ epoch: 1n, unavailable: true }) }); + expect(await announced.next()).toMatchObject({ prefix: late, kind: "offline" }); + // Ending a claim that was never taken reports nothing. + await send({ status: "endedId", id: 0n, lost: true }); + await send({ status: "endedId", id: 1n, lost: false }); + await settled(); + expect(await announced.next()).toMatchObject({ prefix: held, kind: "end" }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A, cost: 1n } }); - await send({ status: "routeStart", prefix: 0n, node: NODE_A, suffix: live, exact: false, offer: offer(NODE_A) }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - // The more specific route to the node now carries the claim, which a request names by its depth. - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 1, node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: x, route: 2n, instance: b }); - await send({ status: "floor", id: 2n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_B } }); - - // NODE_A raises its cost to 100 at revision 1, which only the first route has delivered: its - // claim is reported at that cost, whichever route carries it. - await send({ status: "update", id: 0n, cost: 100n }); - await send({ status: "floor", id: 0n, revision: 1n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "update", route: { node: NODE_A, cost: 101n } }); - // The first route goes, and the lagging copy still carries the newer cost. - await send({ status: "routeEnd", id: 0n }); - - const pick = await trackRequest(x, 0); - expect(pick.request).toMatchObject({ instance: b, node: NODE_B }); - - pick.consumed.close(); announced.close(); subscriber.close(); - await pick.info; }); -test("a lite-07 consume names the node now serving its instance", async () => { +// The peer sends each instance's claim at a path, and the reader is shown the best: the cheaper +// one, then the other once it ends. +test("a lite-07 path claimed by two instances fails over when the cheaper one ends", async () => { const { subscriber, announced, send, trackRequest } = await routedStream(); const room = Path.from("room"); - const a = Instance.parse("a"); + const [a, b] = [Instance.parse("a"), Instance.parse("b")]; - // Two origin nodes reach one instance; the cheaper serves. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A, { metric: 5n }), - }); - await send({ status: "active", suffix: room, route: 0n, instance: a }); - await send({ status: "floor", id: 0n }); - await announced.next(); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: room, route: 1n, instance: a }); - await send({ status: "floor", id: 1n }); - await announced.next(); + await send({ status: "start", suffix: room, instance: a, claim: claimOf({ cost: 5n }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { instance: a } }); + await send({ status: "start", suffix: room, instance: b, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: b } }); const first = await trackRequest(room, 0); - expect(first.request).toMatchObject({ instance: a, node: NODE_B }); + expect(first.request).toMatchObject({ instance: b }); - // The cheaper one goes: the same instance's consume now names the other. - await send({ status: "routeEnd", id: 1n }); - await announced.next(); + await send({ status: "endedId", id: 1n, lost: true }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: a } }); const second = await trackRequest(room, 1); - expect(second.consumed.closed).toBe(first.consumed.closed); - expect(second.request).toMatchObject({ instance: a, node: NODE_A }); + expect(second.request).toMatchObject({ instance: a }); first.consumed.close(); second.consumed.close(); - subscriber.close(); - await Promise.all([first.info, second.info]); -}); - -// A route that ends unindexes itself before its floors reshow another route to the node, which -// refreshes every route at the paths it shows: the ended one must not be among them. -test("a lite-07 certified route ending shows another route's copy of its claim", async () => { - const { subscriber, announced, send } = await routedStream(); - const x = Path.from("live/x"); - const next = async () => { - const event = await announced.next(); - return `${event?.kind} ${event?.prefix} ${String(event?.route.instance)}`; - }; - - // A narrow route's floor certifies nothing, so it shows x at b while it carries it. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.from("live"), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: Instance.parse("b") }); - await send({ status: "floor", id: 0n }); - expect(await next()).toBe("start live/x b"); - - // A wide route's floor certifies x at a, which then decides it. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 1n, instance: Instance.parse("a") }); - await send({ status: "floor", id: 1n, revision: 1n }); - let seen = await next(); - while (seen !== "start live/x a") seen = await next(); - - // With no live floor left, the narrow route's copy shows again. - await send({ status: "routeEnd", id: 1n }); - expect(await next()).toBe("restart live/x b"); - - announced.close(); - subscriber.close(); -}); - -test("a lite-07 path ranks only an instance's newest epoch", async () => { - const { subscriber, announced, send } = await routedStream(); - const room = Path.from("room"); - const a = Instance.parse("a"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: room, route: 0n, instance: a, epoch: 0n }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, route: { epoch: 0n } }); - - // Dearer, but newer: it takes over. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 9n }), - }); - await send({ status: "active", suffix: room, route: 1n, instance: a, epoch: 1n }); - await send({ status: "floor", id: 1n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { epoch: 1n, node: NODE_B } }); - announced.close(); subscriber.close(); + await Promise.all([first.info, second.info]); }); -// Each consume ranks every route's claim at its covering prefix for its own path, so two equal -// origins of a prefix spread its children by rendezvous hash, whichever announced first. -test("lite-07 children of a prefix two origins claim spread by node", async () => { - for (const order of [ - [NODE_A, NODE_B], - [NODE_B, NODE_A], - ]) { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const pool = Path.from("pool"); - for (const [route, node] of order.entries()) { - await send({ - status: "routeStart", - prefix: 0n, - node, - suffix: Path.empty(), - exact: false, - offer: offer(node), - }); - await send({ status: "active", suffix: pool, route: BigInt(route), instance: Instance.parse(`i${node}`) }); - await send({ status: "floor", id: BigInt(route) }); - await announced.next(); - } - const job = Path.from("pool/job"); - // Pinned to `lite07_ties_match_js` in rs/moq-net, which picks NODE_B too. - expect(rendezvousHash(job, NODE_A)).toBe(0xc376be7bf47aebbfn); - expect(rendezvousHash(job, NODE_B)).toBe(0x5813213b6508aaeen); - const { request, consumed, info } = await trackRequest(job, 0); - expect(request.node).toBe(NODE_B); - consumed.close(); - subscriber.close(); - await info; - } -}); - -// A full tie at a claim's own path goes to the newest claim, as `lite07_ties_match_js` in -// rs/moq-net pins: a re-price into the tie leaves it in place, a restart makes it the newest. -// The announcements and the consumes pick alike. +// A full tie goes to the newest claim, and a re-price keeps a claim's place. test("a lite-07 tie at a claim's path goes to the newest claim, a re-price keeping its place", async () => { const { subscriber, announced, send, trackRequest } = await routedStream(); const room = Path.from("room"); const other = Path.from("other"); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - const c = Instance.parse("c"); + const [a, b] = [Instance.parse("a"), Instance.parse("b")]; - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: room, route: 0n, instance: a, cost: 4n }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: room, route: 1n, instance: b }); - await send({ status: "floor", id: 1n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { node: NODE_B } }); + await send({ status: "start", suffix: room, instance: a, claim: claimOf({ cost: 4n }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { instance: a } }); + await send({ status: "start", suffix: room, instance: b, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: b } }); // The older claim re-prices into a tie: the newer keeps the path, so nothing is reported. - await send({ status: "update", id: 0n, cost: 0n }); - await send({ status: "floor", id: 0n }); - await send({ status: "active", suffix: other, route: 1n, instance: b }); - await send({ status: "floor", id: 1n }); + await send({ status: "change", id: 0n, claim: claimOf() }); + await send({ status: "start", suffix: other, instance: b, claim: claimOf() }); expect(await announced.next()).toMatchObject({ prefix: other, kind: "start" }); const kept = await trackRequest(room, 0); - expect(kept.request).toMatchObject({ instance: b, node: NODE_B }); + expect(kept.request).toMatchObject({ instance: b }); - // A restart at the tie is the newest claim: both pick it. - await send({ status: "restart", id: 0n, instance: c }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ - prefix: room, - kind: "restart", - route: { instance: c, node: NODE_A }, - }); + // Another epoch at the tie is the newest claim: both pick it. + await send({ status: "change", id: 0n, claim: claimOf({ epoch: 1n }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: a, epoch: 1n } }); const restarted = await trackRequest(room, 1); - expect(restarted.request).toMatchObject({ instance: c, node: NODE_A }); + expect(restarted.request).toMatchObject({ instance: a }); kept.consumed.close(); restarted.consumed.close(); @@ -5015,827 +4028,136 @@ test("a lite-07 tie at a claim's path goes to the newest claim, a re-price keepi await Promise.all([kept.info, restarted.info]); }); -// A consume pinned to an instance takes that instance's route, whichever the hash ranks first. -test("a lite-07 consume pinned to an instance names its route's node", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const pool = Path.from("pool"); - const a = Instance.parse("a"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: pool, route: 0n, instance: a }); - await send({ status: "floor", id: 0n }); - await announced.next(); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: pool, route: 1n, instance: Instance.parse("b") }); - await send({ status: "floor", id: 1n }); - await announced.next(); - // NODE_B wins `pool/job` unpinned; see the spread test above. - const { request, consumed, info } = await trackRequest(Path.from("pool/job"), 0, a); - expect(request).toMatchObject({ instance: a, node: NODE_A }); - consumed.close(); - announced.close(); - subscriber.close(); - await info; -}); - -// Forwarding code asks for each origin node's claim at a path as its own route. -test("a lite-07 stream reports each node's claim with claims", async () => { +test("a lite-07 stream reports each instance's claim with claims", async () => { const { subscriber, announced, send } = await routedStream({ claims: true }); const pool = Path.from("pool"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: pool, route: 0n, instance: Instance.parse("a") }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: pool, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: pool, route: 1n, instance: Instance.parse("b") }); - await send({ status: "floor", id: 1n }); - expect(await announced.next()).toMatchObject({ prefix: pool, kind: "start", route: { node: NODE_B } }); - - // The route ending takes only its own claim. - await send({ status: "routeEnd", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: pool, kind: "offline", route: { node: NODE_A } }); - await send({ status: "update", id: 1n, cost: 3n }); - await send({ status: "floor", id: 1n }); - expect(await announced.next()).toMatchObject({ prefix: pool, kind: "update", route: { node: NODE_B } }); - - announced.close(); - subscriber.close(); -}); - -test("a lite-07 batch applies at its floor, and a held route turns unavailable", async () => { - const { subscriber, announced, send } = await routedStream(); - const room = Path.from("room"); - const other = Path.from("other"); - const a = Instance.parse("a"); - - // Nothing under a route shows before its floor, even while another route's batch lands. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: room, route: 0n, instance: a, cost: 2n }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: other, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: other, kind: "start" }); - await send({ status: "synced", prefix: 0n }); - await send({ status: "floor", id: 0n, revision: 0n }); - // The claim's cost, the route's metric, and this session's link. - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { cost: 3n, node: NODE_A } }); - - // A held route keeps its claims, unavailable, until an update makes it usable again. - await send({ status: "routeHold", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "update", route: { available: false } }); - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A, { metric: 5n }) }); - expect(await announced.next()).toMatchObject({ - prefix: room, - kind: "update", - route: { available: true, cost: 8n }, - }); - // Nothing ranks by its path, so a change to it alone reports nothing, until the route crossed - // as many nodes as one may, or crossed us: then it is no route at all, until it is usable again. - const longer = [{ node: NODE_A, session: 0n }, { node: 3n, session: 1n }, ...offer(NODE_A).path.slice(1)]; - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A, { metric: 5n, path: longer }) }); - const full = Array.from({ length: ROUTE_MAX_HOPS }, (_, i) => ({ node: BigInt(i + 1), session: 0n })); - const crossing = [ - { node: NODE_A, session: 0n }, - { node: subscriber.hop, session: 1n }, - ...offer(NODE_A).path.slice(1), - ]; - for (const path of [full, crossing]) { - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A, { metric: 5n, path }) }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "offline" }); - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A, { metric: 5n }) }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { cost: 8n } }); - } - - // A route the peer lets go takes its claims offline. - await send({ status: "routeEnd", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "offline" }); - // Its Announce IDs went with it. - await send({ status: "endedId", id: 0n }); - await expect(announced.next()).rejects.toThrow(ProtocolViolation); - - subscriber.close(); -}); - -test("a lite-07 path served by two routes fails over when the cheaper one ends", async () => { - const { subscriber, announced, send } = await routedStream(); - const room = Path.from("room"); - const a = Instance.parse("a"); - const b = Instance.parse("b"); - - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A, { metric: 5n }), - }); - await send({ status: "active", suffix: room, route: 0n, instance: a }); - await send({ status: "floor", id: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { instance: a, node: NODE_A } }); - - // Another origin claims the path more cheaply: it takes over, as another instance. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B), - }); - await send({ status: "active", suffix: room, route: 1n, instance: b }); - await send({ status: "floor", id: 1n }); - expect(await announced.next()).toMatchObject({ - prefix: room, - kind: "restart", - route: { instance: b, node: NODE_B }, - }); - const consumed = subscriber.consume(room); - - // Its route ending falls back to the other, and the next consume names that origin. - await send({ status: "routeEnd", id: 1n }); - expect(await announced.next()).toMatchObject({ - prefix: room, - kind: "restart", - route: { instance: a, node: NODE_A }, - }); - expect(subscriber.consume(room).closed).not.toBe(consumed.closed); - - consumed.close(); - announced.close(); - subscriber.close(); -}); - -// A DEAD names a closed session on the peer's paths: each route through it moves to the offer it -// names, ends when the far end is gone, and is held otherwise. Routes off that hop, and a hop no -// route crosses, change nothing. Mirrors rs/moq-net. -test("a lite-07 DEAD moves, ends, or holds the routes through its hop", async () => { - const { subscriber, announced, send } = await routedStream(); - const [a, b, c] = ["a", "b", "c"].map((path) => Path.from(path)); - const instance = Instance.parse("i"); - const NODE_C = 0x9cn; - for (const [id, node, path] of [ - [0n, NODE_A, a], - [1n, NODE_B, b], - [2n, NODE_C, c], - ] as const) { - await send({ status: "routeStart", prefix: 0n, node, suffix: Path.empty(), exact: false, offer: offer(node) }); - await send({ status: "active", suffix: path, route: id, instance }); - await send({ status: "floor", id, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: { cost: 1n } }); - } - // The peer's session to a publisher, as each route's path names it, closed: the DEAD, then - // the ROUTE_UPDATE of each route it moved. - const closed = async ( - to: (msg: AnnounceBroadcast) => Promise, - node: bigint, - gone: boolean, - moved: { id: bigint; offer: Offer }[] = [], - ) => { - const hop = { node: PEER_NODE, session: node }; - await to({ status: "dead", dead: { kind: "closed", hop, far: node, gone, moved: BigInt(moved.length) } }); - for (const { id, offer } of moved) await to({ status: "routeUpdate", id, offer }); - }; - - // A hop no route crosses changes nothing: the next thing shown is the move below. - await send({ - status: "dead", - dead: { kind: "closed", hop: { node: 0x55n, session: 4n }, far: 0x56n, gone: true, moved: 0n }, - }); - // Route 0 moved to a costlier path through another of the peer's sessions. - const detour = [ - { node: NODE_A, session: 0n }, - { node: 3n, session: 1n }, - { node: PEER_NODE, session: 3n }, - ]; - await closed(send, NODE_A, false, [{ id: 0n, offer: offer(NODE_A, { metric: 4n, path: detour }) }]); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "update", route: { cost: 5n, available: true } }); - // Its old hop names it no more: a DEAD of that hop leaves it alone. - await closed(send, NODE_A, true); - // Route 1's far end is gone: it ends with its claims. - await closed(send, NODE_B, true); - expect(await announced.next()).toMatchObject({ prefix: b, kind: "offline" }); - await send({ status: "endedId", id: 1n }); - await expect(announced.next()).rejects.toThrow(ProtocolViolation); - subscriber.close(); - - // Held, a route stays unavailable until its next offer. - const held = await routedStream(); - await held.send({ - status: "routeStart", - prefix: 0n, - node: NODE_C, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_C), - }); - await held.send({ status: "active", suffix: c, route: 0n, instance }); - await held.send({ status: "floor", id: 0n, revision: 0n }); - expect(await held.announced.next()).toMatchObject({ prefix: c, kind: "start" }); - await closed(held.send, NODE_C, false); - expect(await held.announced.next()).toMatchObject({ prefix: c, kind: "update", route: { available: false } }); - await held.send({ status: "routeUpdate", id: 0n, offer: offer(NODE_C) }); - expect(await held.announced.next()).toMatchObject({ prefix: c, kind: "update", route: { available: true } }); - // Moved to an offer this node refuses, it goes offline, and a later usable offer brings it back. - // DEAD: the session NODE_C (two varint bytes) closed, moving one route, then the ROUTE_UPDATE - // of route 0 to an offer with an unknown flag. - await held.raw([15, 8, 0, 2, 0x80, 0x9c, 0x80, 0x9c, 0, 1]); - await held.raw([7, 7, 0, 1, 7, 0, 0x80, 128, 0]); - expect(await held.announced.next()).toMatchObject({ prefix: c, kind: "offline" }); - await held.send({ status: "routeUpdate", id: 0n, offer: offer(NODE_C) }); - expect(await held.announced.next()).toMatchObject({ prefix: c, kind: "start" }); - held.announced.close(); - held.subscriber.close(); -}); - -// A DEAD and the ROUTE_UPDATEs it counts apply as one step: nothing shows before the last of -// them, a route one of them moved is not ended by the gone hop, and the route none of them -// names ends with it. Mirrors rs/moq-net. -test("a lite-07 DEAD and its ROUTE_UPDATEs apply as one", async () => { - const { subscriber, announced, send, raw, settled } = await routedStream(); - const [a, b, c] = ["a", "b", "c"].map((path) => Path.from(path)); - const instance = Instance.parse("i"); - // One varint byte, so the raw message below spells it. - const NODE_C = 0x9n; - // Every route reaches the peer over its session to NODE_A. - const hop = { node: PEER_NODE, session: NODE_A }; - const through = (node: bigint) => [ - { node, session: 0n }, - ...(node === NODE_A ? [] : [{ node: NODE_A, session: 1n }]), - hop, - ]; - const NODE_D = 0x9dn; - const d = Path.from("d"); - for (const [id, node, path] of [ - [0n, NODE_A, a], - [1n, NODE_B, b], - [2n, NODE_C, c], - [3n, NODE_D, d], - ] as const) { - await send({ - status: "routeStart", - prefix: 0n, - node, - suffix: Path.empty(), - exact: false, - offer: offer(node, { path: through(node) }), - }); - await send({ status: "active", suffix: path, route: id, instance }); - await send({ status: "floor", id, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: path, kind: "start" }); - } - const detour = (node: bigint) => - offer(node, { metric: 4n, path: [...through(node).slice(0, -1), { node: PEER_NODE, session: 9n }] }); - - // Whatever shows before the last ROUTE_UPDATE is one applied alone. - const shown: unknown[] = []; - const reading = (async () => { - for (;;) { - const event = await announced.next(); - if (!event) break; - shown.push(event); - } - })(); - await send({ status: "dead", dead: { kind: "closed", hop, far: NODE_A, gone: true, moved: 3n } }); - await settled(); - expect(shown).toEqual([]); - await send({ status: "routeUpdate", id: 0n, offer: detour(NODE_A) }); - await settled(); - expect(shown).toEqual([]); - // ROUTE_UPDATE of Route ID 2 with a flag no version defines: refused, and counted all the same. - await raw([7, 9, 2, 2, 9, 0, 2, 9, 0x80, 128, 0]); - await settled(); - expect(shown).toEqual([]); - await send({ status: "routeUpdate", id: 1n, offer: detour(NODE_B) }); - await settled(); - // The moved routes carry on along their new paths, the one moved to a refused offer goes - // offline, and the one no update named ends with the gone hop. - expect(shown).toMatchObject([ - { prefix: a, kind: "update", route: { cost: 5n } }, - { prefix: b, kind: "update", route: { cost: 5n } }, - { prefix: c, kind: "offline" }, - { prefix: d, kind: "offline" }, - ]); - // The ended route's ids went with it, and the moved ones are live. - await send({ status: "routeHold", id: 0n }); - await settled(); - expect(shown.at(-1)).toMatchObject({ prefix: a, kind: "update", route: { available: false } }); - - announced.close(); - await reading; - subscriber.close(); -}); - -// A reader sees only where a DEAD leaves every route it moves, never a route only the middle of -// it preferred: the publisher wins before and after, so its fallback never shows. -test("a lite-07 DEAD shows readers only its end", async () => { - const { subscriber, announced, send, settled } = await routedStream(); - const x = Path.from("live/x"); const [a, b] = [Instance.parse("a"), Instance.parse("b")]; - // Two routes to NODE_A over the peer's session to it, the second held, and NODE_B dearer. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance: a }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.from("live"), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 1n, instance: a }); - await send({ status: "floor", id: 1n, revision: 0n }); - await send({ status: "routeHold", id: 1n }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 9n }), - }); - await send({ status: "active", suffix: x, route: 2n, instance: b }); - await send({ status: "floor", id: 2n, revision: 0n }); - await settled(); - - const shown: { route: { node?: bigint } }[] = []; - const reading = (async () => { - for (;;) { - const event = await announced.next(); - if (!event) break; - shown.push(event); - } - })(); - // The session to NODE_A closed for good: the first route ends, and the held one moves to a - // usable path. - const detour = [ - { node: NODE_A, session: 0n }, - { node: 3n, session: 1n }, - { node: PEER_NODE, session: 3n }, - ]; - const hop = { node: PEER_NODE, session: NODE_A }; - await send({ status: "dead", dead: { kind: "closed", hop, far: NODE_A, gone: true, moved: 1n } }); - await send({ status: "routeUpdate", id: 1n, offer: offer(NODE_A, { metric: 4n, path: detour }) }); - await settled(); - expect(shown.length).toBeGreaterThan(0); - for (const event of shown) expect(event).toMatchObject({ prefix: x, route: { node: NODE_A } }); - - announced.close(); - await reading; - subscriber.close(); -}); - -// A reader of a wider prefix widens the route in place: the claim it carried stays shown to -// both readers, and only what the wider prefix adds arrives. -test("a lite-07 edit to a wider prefix keeps the claims the route carried", async () => { - const half = Path.from("a"); - const { subscriber, announced, send, edits, settled, another } = await routedStream( - undefined, - Path.Pattern.subtree(half), - ); - const [x, y] = [Path.from("a/x"), Path.from("b/y")]; - const instance = Instance.parse("i"); - expect(edits).toMatchObject([{ remove: [], add: [{ prefix: half }] }]); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ status: "synced", prefix: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start" }); - - // The root takes the place of the narrower prefix in one edit, which the harness answers. - const wide = await another(); - expect(edits).toMatchObject([{}, { remove: [0n], add: [{ prefix: Path.empty() }] }]); - expect(await wide.announced.next()).toMatchObject({ prefix: x, kind: "start" }); - // The route now lies at the root, which a request through the claim names by its depth. - for (const reader of [announced, wide.announced]) { - expect(await reader.next()).toMatchObject({ prefix: x, kind: "update", route: { depth: 0, available: true } }); - } + await send({ status: "start", suffix: pool, instance: a, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: pool, kind: "start", route: { instance: a } }); + await send({ status: "start", suffix: pool, instance: b, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: pool, kind: "start", route: { instance: b } }); - // The publisher sends what the widened route lacks, then its floor. - await send({ status: "active", suffix: y, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 1n }); - await send({ status: "synced", prefix: 1n }); - expect(await wide.announced.next()).toMatchObject({ prefix: y, kind: "start" }); - - // The claim both prefixes cover never left: its end is the next thing either reader sees. - await send({ status: "endedId", id: 0n }); - await send({ status: "floor", id: 0n, revision: 2n }); - await settled(); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "end" }); - expect(await wide.announced.next()).toMatchObject({ prefix: x, kind: "end" }); - - wide.announced.close(); - announced.close(); - subscriber.close(); -}); - -// A route its ROUTE_START marked exact lies at its own prefix: a wider request leaves it there, so -// its claims keep their route's depth and the publisher keeps sending under it. Mirrors rs/moq-net. -test("a lite-07 edit to a wider prefix leaves an exact route at its own prefix", async () => { - const half = Path.from("a"); - const { subscriber, announced, send, edits, settled, another } = await routedStream( - undefined, - Path.Pattern.subtree(half), - ); - const [x, z] = [Path.from("a/x"), Path.from("a/z")]; - const instance = Instance.parse("i"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: true, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ status: "synced", prefix: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start", route: { depth: 1 } }); - - const wide = await another(); - expect(edits).toMatchObject([{}, { remove: [0n], add: [{ prefix: Path.empty() }] }]); - expect(await wide.announced.next()).toMatchObject({ prefix: x, kind: "start", route: { depth: 1 } }); - await send({ status: "synced", prefix: 1n }); - - // Nothing moved, so the first reader's next event is the new claim under the same route. - await send({ status: "active", suffix: z, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 1n }); - await settled(); - expect(await announced.next()).toMatchObject({ prefix: z, kind: "start", route: { depth: 1 } }); - expect(await wide.announced.next()).toMatchObject({ prefix: z, kind: "start", route: { depth: 1 } }); + // One ending takes only its own claim. + await send({ status: "endedId", id: 0n, lost: true }); + expect(await announced.next()).toMatchObject({ prefix: pool, kind: "offline", route: { instance: a } }); + await send({ status: "change", id: 1n, claim: claimOf({ cost: 3n }) }); + expect(await announced.next()).toMatchObject({ prefix: pool, kind: "update", route: { instance: b, cost: 4n } }); - wide.announced.close(); announced.close(); subscriber.close(); }); -// A reader below the shared request is shown a broader claim at its own prefix as that much above -// it, so a claim exactly there outranks the broader one however cheaper that is, as a consume of -// the path picks. test("a lite-07 reader below the request ranks a broader claim as above its prefix", async () => { const { subscriber, announced, send, edits, settled, another } = await routedStream(); const [x, xa] = [Path.from("x"), Path.from("x/a")]; const narrow = await another(Path.Pattern.subtree(xa)); // The root covers the narrow reader, so its request is the root's alone. expect(edits).toHaveLength(1); - const instance = Instance.parse("i"); - for (const [id, node, path, cost] of [ - [0n, NODE_A, x, 0n], - [1n, NODE_B, xa, 10n], - ] as const) { - await send({ status: "routeStart", prefix: 0n, node, suffix: Path.empty(), exact: false, offer: offer(node) }); - await send({ status: "active", suffix: path, route: id, instance, cost }); - await send({ status: "floor", id, revision: 0n }); - } + const [broad, exact] = [Instance.parse("broad"), Instance.parse("exact")]; + await send({ status: "start", suffix: x, instance: broad, claim: claimOf() }); + await send({ status: "start", suffix: xa, instance: exact, claim: claimOf({ cost: 10n }) }); await settled(); - // The root's claim shows first, one segment above the reader's prefix, until the exact one - // arrives. + // The broader claim shows first, one segment above the reader's prefix, until the exact one + // arrives, which outranks it whatever it costs. expect(await narrow.announced.next()).toMatchObject({ prefix: xa, kind: "start", - route: { node: NODE_A, above: 1n }, + route: { instance: broad, above: 1n }, }); - expect(await narrow.announced.next()).toMatchObject({ prefix: xa, route: { node: NODE_B, above: 0n } }); + expect(await narrow.announced.next()).toMatchObject({ prefix: xa, route: { instance: exact, above: 0n } }); narrow.announced.close(); announced.close(); subscriber.close(); }); -// Two routes of one node, each showing its covering claim at its own prefix, merge when a reader -// widens the request past both: each claim stays shown until the merged route's next floor. -test("a lite-07 edit merging two routes keeps each one's covering claim", async () => { - const [a, b] = [Path.from("a"), Path.from("b")]; - const { subscriber, announced, send, edits, settled, another } = await routedStream( - undefined, - Path.Pattern.subtree(a), - ); - const instance = Instance.parse("i"); - const other = await another(Path.Pattern.subtree(b)); - expect(edits).toMatchObject([{ add: [{ prefix: a }] }, { add: [{ prefix: b }] }]); - // NODE_A claims the root, which each route presents at its requested prefix. - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: a, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ - status: "routeStart", - prefix: 1n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: b, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: a, kind: "start" }); - expect(await other.announced.next()).toMatchObject({ prefix: b, kind: "start" }); +test("a lite-07 claim ranks by its priority before its cost, and last while it drains", async () => { + const { subscriber, announced, send } = await routedStream(); + const room = Path.from("room"); + const [a, b] = [Instance.parse("a"), Instance.parse("b")]; + await send({ status: "start", suffix: room, instance: a, claim: claimOf({ priority: -10 }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { instance: a } }); + await send({ status: "start", suffix: room, instance: b, claim: claimOf({ cost: 5n }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: b } }); - // A reader of everything widens the request to the root, which the harness answers. - const wide = await another(); - await settled(); - expect(edits.at(-1)).toMatchObject({ remove: [0n, 1n], add: [{ prefix: Path.empty() }] }); - const seen: { kind: string }[] = []; - const reading = (async () => { - for (const reader of [announced, other.announced]) { - const event = await Promise.race([reader.next(), settled().then(() => undefined)]); - if (event) seen.push(event); - } - })(); - await reading; - expect(seen.filter((event) => event.kind === "end")).toEqual([]); + // A node on the way to the dearer one sent GOAWAY: it ranks last, whatever its priority. + await send({ status: "change", id: 1n, claim: claimOf({ cost: 5n, draining: true }) }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "restart", route: { instance: a } }); - wide.announced.close(); - other.announced.close(); announced.close(); subscriber.close(); }); -// DRAIN: a node on a route's path sent GOAWAY, so it ranks below every route without one, until -// its next offer. -test("a lite-07 DRAIN ranks the routes through its node last", async () => { - const { subscriber, announced, send } = await routedStream(); - const room = Path.from("room"); - const instance = Instance.parse("i"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: room, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: room, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 0n }); +// At the ANNOUNCE_OK answering an edit, both ends drop every claim within a prefix it removed: +// the peer never ended them, so they go offline, and it tells again what the added prefix covers. +test("a lite-07 edit drops the claims within a prefix it removed", async () => { + const { subscriber, announced, send, edits, settled } = await routedStream(undefined, Path.Pattern.subtree("a/b")); + const [ab, abc] = [Path.from("a/b"), Path.from("a/b/c")]; + expect(edits).toEqual([{ remove: [], add: [{ prefix: ab, hidden: false }] }]); + const i = Instance.parse("i"); + await send({ status: "start", suffix: abc, instance: i, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: abc, kind: "start" }); + + // A wider reader moves the request up, which removes the narrower prefix. + const wide = subscriber.routes(Path.Pattern.subtree("a")); + await settled(); + expect(edits[1]).toEqual({ remove: [0n], add: [{ prefix: Path.from("a"), hidden: false }] }); + expect(await announced.next()).toMatchObject({ prefix: abc, kind: "offline" }); - await send({ status: "dead", dead: { kind: "drain", node: NODE_A } }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "update", route: { node: NODE_B } }); - // Its next offer says whether it still drains. - await send({ status: "routeUpdate", id: 0n, offer: offer(NODE_A) }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "update", route: { node: NODE_A } }); + // The Announce ID the dropped claim held is retired on both ends. + await send({ status: "start", suffix: abc, instance: i, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: abc, kind: "start" }); + expect(await wide.next()).toMatchObject({ prefix: abc, kind: "start" }); + await send({ status: "endedId", id: 1n, lost: false }); + expect(await announced.next()).toMatchObject({ prefix: abc, kind: "end" }); + wide.close(); announced.close(); subscriber.close(); }); -// A claim ranks by the lowest priority of a link on its route's path before its cost, as routes to -// one node do, so a cheaper claim behind a demoted link loses to a dearer one. Mirrors rs/moq-net. -test("a lite-07 claim ranks by its path's priority before its cost", async () => { +// A path that resolves to none this node can hold is refused alone: its Announce ID still counts. +test("a lite-07 claim at a path too deep to hold is refused alone", async () => { const { subscriber, announced, send } = await routedStream(); - const room = Path.from("room"); - const instance = Instance.parse("i"); + const deep = Path.from(Array.from({ length: 32 }, () => "a").join("/")); + const i = Instance.parse("i"); + await send({ status: "start", suffix: deep, instance: i, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: deep, kind: "start" }); + // The whole of the base, and a segment more. await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A, { priority: -10 }), + status: "start", + suffix: Path.from("b"), + pathBase: { distance: 1n, keep: 32 }, + instance: i, + claim: claimOf(), }); - await send({ status: "active", suffix: room, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "start", route: { node: NODE_A } }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_B, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_B, { metric: 5n }), - }); - await send({ status: "active", suffix: room, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "update", route: { node: NODE_B } }); - - announced.close(); - subscriber.close(); -}); + const room = Path.from("room"); + await send({ status: "start", suffix: room, instance: i, claim: claimOf() }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "start" }); + await send({ status: "endedId", id: 1n, lost: false }); + await send({ status: "endedId", id: 2n, lost: false }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "end" }); -// A route covers the requested prefix joined with its suffix: one origin node may have a route -// per prefix, and a request through one names how many segments of its path that prefix spans. -test("a lite-07 request names its route's prefix depth", async () => { - const { subscriber, announced, send, trackRequest } = await routedStream(); - const x = Path.from("live/room/x"); - const y = Path.from("y"); - const instance = Instance.parse("i"); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.from("live/room"), - exact: false, - offer: offer(NODE_A), - }); - await send({ - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }); - await send({ status: "active", suffix: x, route: 0n, instance }); - await send({ status: "floor", id: 0n, revision: 0n }); - await send({ status: "active", suffix: y, route: 1n, instance }); - await send({ status: "floor", id: 1n, revision: 0n }); - expect(await announced.next()).toMatchObject({ prefix: x, kind: "start" }); - expect(await announced.next()).toMatchObject({ prefix: y, kind: "start" }); - - const deep = await trackRequest(x, 0); - expect(deep.request).toMatchObject({ node: NODE_A, depth: 2 }); - const shallow = await trackRequest(y, 1); - expect(shallow.request).toMatchObject({ node: NODE_A, depth: 0 }); - - for (const pick of [deep, shallow]) pick.consumed.close(); announced.close(); subscriber.close(); - for (const pick of [deep, shallow]) await pick.info; -}); - -// The routes a DEAD violation is checked against: NODE_A's and NODE_B's, each over the peer's -// session to its node, and NODE_C's behind NODE_A's. -const DEAD_HOP = { node: PEER_NODE, session: NODE_A }; -const DEAD_ROUTES: AnnounceBroadcast[] = [ - { status: "routeStart", prefix: 0n, node: NODE_A, suffix: Path.empty(), exact: false, offer: offer(NODE_A) }, - { status: "routeStart", prefix: 0n, node: NODE_B, suffix: Path.empty(), exact: false, offer: offer(NODE_B) }, - { - status: "routeStart", - prefix: 0n, - node: 0x9cn, - suffix: Path.empty(), - exact: false, - offer: offer(0x9cn, { path: [{ node: 0x9cn, session: 0n }, { node: NODE_A, session: 1n }, DEAD_HOP] }), - }, -]; -const deadMoving = (moved: bigint): AnnounceBroadcast => ({ - status: "dead", - dead: { kind: "closed", hop: DEAD_HOP, far: NODE_A, gone: false, moved }, }); // Each closes the session: a violation on the peer's Announce Stream is the peer breaking it. test.each([ [ - "a second route to one origin node at one prefix", + "one instance claiming a path twice", [ - { - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }, - { - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }, + { status: "start", suffix: Path.from("room"), instance: Instance.parse("a"), claim: ownClaim(0n) }, + { status: "start", suffix: Path.from("room"), instance: Instance.parse("a"), claim: ownClaim(0n) }, ], ], [ - "a route under a Prefix ID never asked for", - [{ status: "routeStart", prefix: 1n, node: NODE_A, suffix: Path.empty(), exact: false, offer: offer(NODE_A) }], + "a claim further above its path than the path is deep", + [{ status: "start", suffix: Path.from("room"), instance: Instance.parse("a"), claim: ownClaim(0n, 2n) }], ], - [ - "a claim outside its route's prefix", - [ - { - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.from("live"), - exact: false, - offer: offer(NODE_A), - }, - { status: "active", suffix: Path.from("other"), route: 0n, instance: Instance.parse("a") }, - ], - ], - // A DEAD and the ROUTE_UPDATEs it counts are one step, so nothing else lies between them. - [ - "a DEAD followed by another message than its ROUTE_UPDATEs", - [...DEAD_ROUTES, deadMoving(1n), { status: "floor", id: 0n }], - ], - [ - "a DEAD followed by an ANNOUNCE_REQUEST before its ROUTE_UPDATEs", - [...DEAD_ROUTES, deadMoving(1n), { status: "request", remove: [], add: [] }], - ], - ["a DEAD followed by another DEAD before its ROUTE_UPDATEs", [...DEAD_ROUTES, deadMoving(1n), deadMoving(0n)]], - [ - "a DEAD moving a route that is not live", - [...DEAD_ROUTES, deadMoving(1n), { status: "routeUpdate", id: 7n, offer: offer(NODE_A) }], - ], - [ - "a DEAD moving a route that does not cross its hop", - [...DEAD_ROUTES, deadMoving(1n), { status: "routeUpdate", id: 1n, offer: offer(NODE_B) }], - ], - [ - "a DEAD moving one route twice", - [ - ...DEAD_ROUTES, - deadMoving(2n), - { status: "routeUpdate", id: 0n, offer: offer(NODE_A) }, - { status: "routeUpdate", id: 0n, offer: offer(NODE_A) }, - ], - ], - ["a DEAD moving more routes than cross its hop", [...DEAD_ROUTES, deadMoving(3n)]], - ["a DEAD moving a route of a stream with none", [deadMoving(1n)]], - [ - "a route claiming one path twice", - [ - { - status: "routeStart", - prefix: 0n, - node: NODE_A, - suffix: Path.empty(), - exact: false, - offer: offer(NODE_A), - }, - { status: "active", suffix: Path.from("room"), route: 0n, instance: Instance.parse("a") }, - { status: "active", suffix: Path.from("room"), route: 0n, instance: Instance.parse("b") }, - ], - ], - [ - "a claim under an unknown route", - [{ status: "active", suffix: Path.from("room"), route: 0n, instance: Instance.parse("a") }], - ], - ["a floor for an unknown route", [{ status: "floor", id: 0n }]], + ["an update of an unknown claim", [{ status: "change", id: 0n, claim: ownClaim(0n) }]], + ["an end of an unknown claim", [{ status: "endedId", id: 0n, lost: false }]], + ["a claim without an instance", [{ status: "active", suffix: Path.from("room") }]], ["a SYNCED for a Prefix ID never asked for", [{ status: "synced", prefix: 1n }]], [ "a second SYNCED for one Prefix ID", @@ -5846,26 +4168,30 @@ test.each([ ], ["an ANNOUNCE_OK answering no ANNOUNCE_REQUEST", [{ status: "ok" }]], ] as [string, AnnounceBroadcast[]][])("lite-07 %s is a violation", async (_, messages) => { - const { subscriber, announced, send, closes } = await routedStream(); + const { subscriber, announced, closes } = await routedStream(); expect(closes).toEqual([]); // Every message before the last is one the peer may send. - for (const msg of messages.slice(0, -1)) await send(msg); + for (const msg of messages.slice(0, -1)) await subscriber.announce(msg); expect(closes).toEqual([]); - await send(messages[messages.length - 1]); - await expect(announced.next()).rejects.toThrow(ProtocolViolation); - expect(closes).toHaveLength(1); - expect(closes[0]?.closeCode).toBe(SessionCode.ProtocolViolation); + const last = messages[messages.length - 1]; + await expect(subscriber.announce(last)).rejects.toThrow(ProtocolViolation); announced.close(); subscriber.close(); }); -// The peer finishing its Announce Stream between a DEAD and the ROUTE_UPDATEs it counted leaves -// the step half said. -test("lite-07 an Announce Stream finished inside a DEAD is a violation", async () => { - const { subscriber, announced, send } = await routedStream(); - for (const msg of DEAD_ROUTES) await send(msg); - await send(deadMoving(1n)); - expect(() => subscriber.announceFinished()).toThrow(ProtocolViolation); +// Only two nodes that both declared a Node ID exchange routes, and this one declares none. +test.each([ + ["ANNOUNCE_FLOOR", [3, 2, 0, 0]], + ["ROUTE", [7, 7, 1, 5, 9, 0, 0, 0x80, 1]], + ["ROUTE_END", [8, 1, 0]], + ["DEAD", [9, 5, 5, 9, 0, 6, 9]], + ["DRAIN", [10, 2, 5, 9]], +])("lite-07 %s to a node that declared no Node ID is a violation", async (_, bytes) => { + const { subscriber, announced, raw, closes } = await routedStream(); + await raw(bytes); + await expect(announced.next()).rejects.toThrow(ProtocolViolation); + expect(closes).toHaveLength(1); + expect(closes[0]?.closeCode).toBe(SessionCode.ProtocolViolation); announced.close(); subscriber.close(); }); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index c5afcf6aad9..10d754f41e6 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -73,7 +73,6 @@ import { Datagram as DatagramMessage, Datagrams, DatagramsInfo, DatagramsUpdate import { closeViolation } from "./error.ts"; import { Fetch as FetchMessage } from "./fetch.ts"; import { dropped, passing, RangeFills, type RecoveryHandle, type Refusal, type Refused, refuseRun } from "./fills.ts"; -import { Floors } from "./floors.ts"; import { type Group as GroupMessage, readFrames } from "./group.ts"; import { Probe } from "./probe.ts"; import { Routed } from "./routed.ts"; @@ -151,10 +150,6 @@ interface SubscribeSetup { */ interface Consumed { readonly instance?: Instance.Valid; - // The publisher node every request names (lite-07): the one the route selected at consume - // reaches, or 0 to leave the choice to the publisher, and the depth of that route's prefix. - readonly node?: bigint; - readonly depth?: number; readonly id?: number; readonly valid?: AbortSignal; // Aborted once another stream takes the path, which may answer a request without an instance @@ -355,19 +350,10 @@ export class Subscriber { #pending = new Map>(); #subscribeNext = 0n; - // Lite-07: what this session's Announce Stream certifies of each origin node's claims. - #floors = new Floors(); - /** - * Lite-07: changes whenever what {@link covers} answers may have changed with no route - * reporting it. - * - * @internal - */ - readonly coverage = new Signal(0); - // Lite-07: the routes and claims the peer sends, shared by every `routes()` reader. + // Lite-07: the claims the peer sends, shared by every `routes()` reader. #routed?: Routed; // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. - #consumes = new BroadcastCache(this.#floors); + #consumes = new BroadcastCache(); #consumeNext = 0; // Dedup in-flight one-shot fetches, keyed by [consume, broadcast, instance, track, sequence]. @@ -432,15 +418,9 @@ export class Subscriber { this.#routed = new Routed({ quic, version, - hop, - floors: this.#floors, consumes: this.#consumes, slots: this.#announces, drained: (route) => this.#drained(route), - revalidate: () => { - this.#consumes.revalidate(); - this.coverage.update((n) => n + 1); - }, goaway, send: (msg) => stream.send(msg), }); @@ -479,7 +459,7 @@ export class Subscriber { * * Only routes whose literal name matches `scope` are reported, unless `options.covering` * also asks for those whose subtree overlaps it. A lite-07 stream reports the best claim at - * each path, or each origin node's with `options.claims`. + * each path, or each instance's with `options.claims`. */ routes(scope: Path.Pattern = Path.Pattern.all(), options?: announce.RouteOptions): announce.Routes { const announced = new announce.Producer(); @@ -492,7 +472,7 @@ export class Subscriber { const covering = options?.covering ?? false; if (this.#routed) { // Lite-07: every reader shares the session's one Announce Stream. - this.#routed.attach(announced, { prefix, scope, hidden, covering, perNode: options?.claims ?? false }); + this.#routed.attach(announced, { prefix, scope, hidden, covering, claims: options?.claims ?? false }); } else { void this.#runAnnounced(announced, prefix, scope, hidden, covering); } @@ -721,8 +701,6 @@ export class Subscriber { active = true; hops = announce.hops ?? []; cost = announce.cost; - instance = announce.instance; - epoch = announce.epoch; break; } case "ended": @@ -937,16 +915,6 @@ export class Subscriber { this.#routed?.silence(); } - /** - * Whether the session's claim of origin `node` at `at` may serve a request for `path` beneath - * it: what the node's newest floor certifies there. See `Floors.covers`. - * - * @internal - */ - covers(node: bigint, at: Path.Valid, path: Path.Valid): boolean { - return this.#floors.covers(node, at, path); - } - /** * Consumes a broadcast from the connection. * @@ -968,23 +936,8 @@ export class Subscriber { } #createConsume(path: Path.Valid, instance: ReturnType): broadcast.Consumer { - const consumes = this.#consumes; - const pinned = - instance.route.node === undefined - ? undefined - : { node: instance.route.node, depth: instance.route.depth ?? 0 }; - // The best route now serving the instance, which moves with failover even once another - // instance wins the path; the one it first resolved through once none does. - const target = (instance: Instance.Valid | undefined) => - (instance !== undefined ? consumes.node(path, instance) : undefined) ?? pinned; const consumed = { instance: instance.route.instance, - get node() { - return target(this.instance)?.node; - }, - get depth() { - return target(this.instance)?.depth; - }, id: this.#consumeNext++, get valid() { return instance.validity?.signal; @@ -1081,8 +1034,6 @@ export class Subscriber { id, broadcast: path, instance: consumed.instance, - node: consumed.node, - depth: consumed.depth, track: request.name, priority, }).encode(opened.writer, this.version); @@ -1244,10 +1195,7 @@ export class Subscriber { // Gave up, perhaps handed a stream as it did: the catch below hands back any stream. if (!stream || cut.aborted) throw cut.reason; await stream.writer.u53(StreamId.Tracks); - await new TracksMessage(broadcast, consumed.instance, consumed.node, consumed.depth).encode( - stream.writer, - this.version, - ); + await new TracksMessage(broadcast, consumed.instance).encode(stream.writer, this.version); let synced = false; const answering = consumed.answering; let unanswered = answering ? AbortSignal.any([stop, answering]) : stop; @@ -1462,8 +1410,6 @@ export class Subscriber { id, broadcast, instance: consumed.instance, - node: consumed.node, - depth: consumed.depth, track: name, priority: subscription.priority ?? 0, order: subscription.order, @@ -1789,7 +1735,7 @@ export class Subscriber { // stays open, as interest in the track, until the caller closes it. async #trackInfo( broadcast: Path.Valid, - { instance, node, depth }: Pin, + { instance }: Pin, track: string, signal: AbortSignal | undefined, deadline: Deadline, @@ -1798,7 +1744,7 @@ export class Subscriber { { version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Track); - await new TrackMessage(broadcast, track, instance, node, depth).encode(stream.writer, this.version); + await new TrackMessage(broadcast, track, instance).encode(stream.writer, this.version); const info = await TrackInfo.decode(stream.reader, this.version); return { info, stream }; }, @@ -2006,7 +1952,7 @@ export class Subscriber { deadline: Deadline, maxDelay?: Duration, ): Promise<{ stream: Stream; info: TrackInfo }> { - const { instance, node, depth, valid } = consumed; + const { instance, valid } = consumed; const cancel = new AbortController(); void group.closed.then((err) => cancel.abort(err ?? new StreamError(StreamCode.Cancel))); const signal = valid ? AbortSignal.any([valid, cancel.signal]) : cancel.signal; @@ -2025,8 +1971,6 @@ export class Subscriber { await new FetchMessage({ broadcast, instance, - node, - depth, track, priority, maxDelay: @@ -2475,8 +2419,6 @@ export class Subscriber { await new FetchMessage({ broadcast, instance: consumed.instance, - node: consumed.node, - depth: consumed.depth, track: name, priority, maxDelay, diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index 980695c4b27..fd94fde83f7 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -37,32 +37,26 @@ export class Track { track: string; /** The publisher instance the subscriber expects. Lite-07+. */ instance?: Instance.Valid; - /** The publisher node that serves the request, 0 for whichever the publisher selects. Lite-07+. */ - node: bigint; - /** How many leading segments of `broadcast` make up the prefix of the route it follows. Lite-07+. */ - depth: number; - constructor(broadcast: Path.Valid, track: string, instance?: Instance.Valid, node = 0n, depth = 0) { + constructor(broadcast: Path.Valid, track: string, instance?: Instance.Valid) { this.broadcast = broadcast; this.track = track; this.instance = instance; - this.node = node; - this.depth = depth; } async #encode(w: Writer, version: Version) { await w.string(Path.encode(this.broadcast)); await encodePin(w, version, this.instance); - await encodeNode(w, version, this.node, this.depth); + await encodeNode(w, version); await w.string(this.track); } static async #decode(r: Reader, version: Version): Promise { const broadcast = Path.decode(await r.string()); const instance = await decodePin(r, version); - const { node, depth } = await decodeNode(r, version, broadcast); + await decodeNode(r, version); const track = await r.string(); - return new Track(broadcast, track, instance, node, depth); + return new Track(broadcast, track, instance); } async encode(w: Writer, version: Version): Promise { diff --git a/js/net/src/lite/tracks.ts b/js/net/src/lite/tracks.ts index 761d1a48008..c9d7aefa399 100644 --- a/js/net/src/lite/tracks.ts +++ b/js/net/src/lite/tracks.ts @@ -30,16 +30,10 @@ export class Tracks { broadcast: Path.Valid; /** The publisher instance the subscriber expects. */ instance?: Instance.Valid; - /** The publisher node that serves the request, 0 for whichever the publisher selects. Lite-07+. */ - node: bigint; - /** How many leading segments of `broadcast` make up the prefix of the route it follows. Lite-07+. */ - depth: number; - constructor(broadcast: Path.Valid, instance?: Instance.Valid, node = 0n, depth = 0) { + constructor(broadcast: Path.Valid, instance?: Instance.Valid) { this.broadcast = broadcast; this.instance = instance; - this.node = node; - this.depth = depth; } async encode(w: Writer, version: Version): Promise { @@ -47,7 +41,7 @@ export class Tracks { return Message.encode(w, async (w) => { await w.string(Path.encode(this.broadcast)); await encodePin(w, version, this.instance); - await encodeNode(w, version, this.node, this.depth); + await encodeNode(w, version); }); } @@ -56,8 +50,8 @@ export class Tracks { return Message.decode(r, async (r) => { const broadcast = Path.decode(await r.string()); const instance = await decodePin(r, version); - const { node, depth } = await decodeNode(r, version, broadcast); - return new Tracks(broadcast, instance, node, depth); + await decodeNode(r, version); + return new Tracks(broadcast, instance); }); } } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 683001cf0ed..89d501ac05d 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -435,24 +435,6 @@ export function keepsSubscribeOpen(version: Version): boolean { return hasRanges(version); } -/** Whether the announce stream has ANNOUNCE_RESTART: another publisher instance replacing an - * advertisement in place. Added in lite-07. Older versions send an ANNOUNCE_END then an - * ANNOUNCE_START. */ -export function hasAnnounceRestart(version: Version): boolean { - // Explicitly list older versions so future versions keep the lite-07+ behavior. - switch (version) { - case Version.DRAFT_01: - case Version.DRAFT_02: - case Version.DRAFT_03: - case Version.DRAFT_04: - case Version.DRAFT_05: - case Version.DRAFT_06: - return false; - default: - return true; - } -} - /** Whether announcements carry their instance and epoch, and TRACK, TRACKS, SUBSCRIBE, and FETCH * the instance they pin. Added in lite-07. Older versions carry nothing, so the receiving session * mints an instance for each announcement. */ @@ -729,22 +711,6 @@ export function hasRoutes(version: Version): boolean { } } -/** Whether SETUP may carry a route key proof, added in lite-07. */ -export function hasRouteKey(version: Version): boolean { - // Explicitly list older versions so future versions default to carrying it. - switch (version) { - case Version.DRAFT_01: - case Version.DRAFT_02: - case Version.DRAFT_03: - case Version.DRAFT_04: - case Version.DRAFT_05: - case Version.DRAFT_06: - return false; - default: - return true; - } -} - /** Whether SETUP recognizes the Implementation parameter, added in lite-07. */ export function hasImplementation(version: Version): boolean { switch (version) { diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 26eeb2d5f6b..532a4684222 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -12,7 +12,6 @@ import { compareRouteCandidates, mostSpecific, presented, - rendezvousHash, spreadHash, superseded, } from "./internal.ts"; @@ -2211,25 +2210,12 @@ test("announced filters before rooting and retains lifecycle, routing and watch expect(wireOf(reader).advertised.peek()).toBeUndefined(); }); -// Rust keys each candidate on its own, a lite-07 claim by its node and any other by its instance -// and chain, as `lite07_ties_match_js` in rs/moq-net pins: here the claim wins. -test("a lite-07 and a lite-06 route beneath one prefix rank by each one's own key", () => { - const job = Path.from("pool/job"); - const pool = Path.from("pool"); - const claim = { ...WireRoute.default, instance: Instance.parse("a"), node: 0x7an, cost: 1n }; - const legacy = { ...WireRoute.default, instance: Instance.parse("b"), hops: [toHop(11n)], cost: 1n }; - expect(rendezvousHash(job, 0x7an)).toBe(0xc376be7bf47aebbfn); - expect(spreadHash(job, "b")).toBe(0xd16a3821c67a2d25n); - expect(compareRouteCandidates(job, pool, claim, legacy)).toBeLessThan(0); - expect(compareRouteCandidates(job, pool, legacy, claim)).toBeGreaterThan(0); -}); - // A claim exactly at the path outranks one that only covers it, whatever else ranks them, as the // Rust router's `above` does: the covering one is cheaper and ahead on priority here. test("a claim nearer its path outranks a broader one", () => { const path = Path.from("src/derived"); - const exact = { ...WireRoute.default, instance: Instance.parse("a"), node: 1n, cost: 9n, priority: -5 }; - const broad = { ...WireRoute.default, instance: Instance.parse("b"), node: 2n, cost: 1n, above: 1n }; + const exact = { ...WireRoute.default, instance: Instance.parse("a"), claimed: true, cost: 9n, priority: -5 }; + const broad = { ...WireRoute.default, instance: Instance.parse("b"), claimed: true, cost: 1n, above: 1n }; expect(compareRouteCandidates(path, path, exact, broad)).toBeLessThan(0); expect(compareRouteCandidates(path, path, broad, exact)).toBeGreaterThan(0); expect(compareRouteCandidates(path, path, exact, { ...broad, above: 0n })).toBeGreaterThan(0); @@ -2239,8 +2225,8 @@ test("a claim nearer its path outranks a broader one", () => { // so a broad claim shown deep never beats the more specific claim filed shallower. test("the most specific claim wins whichever prefix shows it", () => { const path = Path.from("src/a/b/c"); - const broad = { ...WireRoute.default, node: 1n, above: 2n }; - const exact = { ...WireRoute.default, node: 2n }; + const broad = { ...WireRoute.default, claimed: true, above: 2n }; + const exact = { ...WireRoute.default, claimed: true }; const at = new Map([ [Path.from("src/a/b"), broad], [Path.from("src/a"), exact], @@ -2249,7 +2235,7 @@ test("the most specific claim wins whichever prefix shows it", () => { expect(mostSpecific(path, pick, (route) => route)).toBe(exact); // Claims as specific as each other go to the deepest prefix. const same = new Map([ - [Path.from("src/a/b"), { ...WireRoute.default, node: 3n, above: 1n }], + [Path.from("src/a/b"), { ...WireRoute.default, claimed: true, above: 1n }], [Path.from("src/a"), exact], ]); expect( @@ -2257,8 +2243,8 @@ test("the most specific claim wins whichever prefix shows it", () => { path, (prefix) => same.get(prefix), (route) => route, - )?.node, - ).toBe(3n); + )?.above, + ).toBe(1n); }); // An instance's epoch supersedes only within one claim, as Rust's `Epochs` keys by prefix and Above: @@ -2266,8 +2252,8 @@ test("the most specific claim wins whichever prefix shows it", () => { test("a broader claim at a higher epoch does not supersede the exact one", () => { const path = Path.from("src/a"); const instance = Instance.parse("i"); - const exact = { ...WireRoute.default, instance, node: 1n, epoch: 0n }; - const broad = { ...WireRoute.default, instance, node: 2n, epoch: 1n, above: 1n }; + const exact = { ...WireRoute.default, instance, claimed: true, epoch: 0n }; + const broad = { ...WireRoute.default, instance, claimed: true, epoch: 1n, above: 1n }; expect(bestCandidate(path, path, [exact, broad], (route) => route)).toBe(exact); expect(bestCandidate(path, path, [broad, exact], (route) => route)).toBe(exact); // The same claim at a higher epoch still supersedes its older one. @@ -2277,13 +2263,13 @@ test("a broader claim at a higher epoch does not supersede the exact one", () => expect(superseded(exact, [exact, broad])).toBe(false); }); -// A lite-07 claim ranks as the one hop to its origin node in what the origin announces, as in +// A lite-07 claim ranks as the one hop to the peer that sent it in what the origin announces, as in // what a request resolves: tied with a newer one-hop route, the newer wins both. test("an announcement counts a lite-07 claim as one hop", async () => { const origin = new Producer(); const room = Path.from("room"); const b = Instance.parse("b"); - const older = wireOf(origin).receive(room, { ...WireRoute.default, instance: Instance.parse("a"), node: 0x7an }); + const older = wireOf(origin).receive(room, { ...WireRoute.default, instance: Instance.parse("a"), claimed: true }); const newer = wireOf(origin).receive(room, { ...WireRoute.default, instance: b, hops: [PEER] }); const announced = origin.consume().routes(); expect(await announced.next()).toMatchObject({ prefix: room, route: { instance: b } }); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index c9762cb6bdb..a7b9bff8f44 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -35,7 +35,6 @@ import { } from "./internal.ts"; import * as Path from "./path.ts"; import { Front } from "./resume.ts"; -import { Own } from "./route.ts"; import { closeUnwanted } from "./util/announce.ts"; import { type Advertised, @@ -309,12 +308,6 @@ interface RouteEntry { readonly route: Signal; readonly originated: boolean; readonly server?: ServeState; - /** - * Whether the entry may serve a request for `path` strictly beneath its prefix, asked per - * request; unset when it serves its whole subtree. A lite-07 claim covers only what its origin - * node's newest floor still certifies there, which its announcement cannot say. - */ - readonly covers?: (path: Path.Valid) => boolean; /** * Set as a received route leaves because its session lost it, rather than its announcer * ending it: readers then see it go offline, not end. @@ -322,9 +315,9 @@ interface RouteEntry { lost: boolean; } -/** Whether `entry`, at `prefix`, may serve a request for `path`. */ -function admits(entry: RouteEntry, prefix: Path.Valid, path: Path.Valid): boolean { - return entry.scope.matches(path) && (prefix === path || entry.covers === undefined || entry.covers(path)); +/** Whether `entry` may serve a request for `path`. */ +function admits(entry: RouteEntry, path: Path.Valid): boolean { + return entry.scope.matches(path); } /** One advertisement at a prefix. `exact` marks an announced local broadcast, which is only its own path. */ @@ -651,9 +644,6 @@ class OriginState { // Undefined once the origin closes, which ends the sessions publishing it. originated = new Signal(new Map()); - // The lite-07 route identity every session originates these advertisements under. - own = new Own(() => this.originated.peek()); - // Every open prefix route's server, advertised or not, so the origin's close ends each // handler loop even for a route that is hidden or withdrawn. servers = new Set(); @@ -1006,7 +996,7 @@ class OriginState { for (const [prefix, entries] of this.routes.peek()) { if (!Path.hasPrefix(prefix, path)) continue; for (const entry of entries) { - if (!entry.server || !admits(entry, prefix, path) || entry.route.peek().instance !== instance) continue; + if (!entry.server || !admits(entry, path) || entry.route.peek().instance !== instance) continue; if (matches(entry.identity)) return true; } } @@ -1181,7 +1171,7 @@ class OriginState { path, prefix, entries, - (candidate) => !admits(candidate, prefix, path) || (skip?.(candidate) ?? false), + (candidate) => !admits(candidate, path) || (skip?.(candidate) ?? false), prefix === path && local ? [local] : [], ); }, @@ -1408,7 +1398,7 @@ export class Producer implements Table { constructor() { const thisProducer = this; registerWire(this, { - receive: (prefix, route, covers) => this.#receive(prefix, route, covers), + receive: (prefix, route) => this.#receive(prefix, route), interests: (listener) => { if (this.#borrowed?.closed) return () => {}; // What the listener currently wants, so a derived handle's close can retract it @@ -1668,28 +1658,13 @@ export class Producer implements Table { /** * Land a route a peer announced, taken as given. Not originated, so a session never announces it - * back. `covers` asks, per request, whether it serves a path beneath `prefix`, both as the - * session names them. + * back. */ - #receive(prefix: Path.Valid, route?: Partial, covers?: (path: Path.Valid) => boolean): Claim { - const at = this.#scope.prefix(prefix); - const below = - covers && - ((path: Path.Valid) => { - const suffix = Path.stripPrefix(at, path); - return suffix === null || covers(Path.join(prefix, suffix)); - }); - return this.#serving(prefix, WireRoute.normalize(route), false, false, true, below); + #receive(prefix: Path.Valid, route?: Partial): Claim { + return this.#serving(prefix, WireRoute.normalize(route), false, false, true); } - #serving( - prefix: Path.Valid, - route: WireRoute, - originated: boolean, - publishes: boolean, - visible: boolean, - covers?: (path: Path.Valid) => boolean, - ): Claim { + #serving(prefix: Path.Valid, route: WireRoute, originated: boolean, publishes: boolean, visible: boolean): Claim { prefix = this.#scope.prefix(prefix); // A route that names no instance serves one of its own, and a claim hands that one to its jobs. const minted = route.instance === undefined; @@ -1704,7 +1679,6 @@ export class Producer implements Table { route: new Signal(route), originated, server, - covers, lost: false, }; server.onReject = (path, err) => this.#state.refuse(path, entry, err); @@ -2224,7 +2198,6 @@ export class Consumer implements Reader { : new Derived([state.originated], (routes) => scope.projectRoutes(routes)), local: (path, instance) => this.#local(scope.path(path), instance), demand: (path, instance, signal) => this.#demand(scope.path(path), instance, signal), - own: state.own, covers: (prefix: Path.Valid) => scope.covers(prefix), }); } diff --git a/js/net/src/route.ts b/js/net/src/route.ts deleted file mode 100644 index 16724c938cf..00000000000 --- a/js/net/src/route.ts +++ /dev/null @@ -1,76 +0,0 @@ -/** - * The lite-07 route identity an origin originates its own claims under. - * - * @module - */ -import { Signal } from "@moq/signals"; - -/** The largest lite-07 varint, which no origin advertises as a Revision. */ -const MAX = 2n ** 64n - 1n; - -/** A fresh Node ID: random, non-zero, and with the most significant bit clear, which marks a qualified one. */ -function fresh(): bigint { - const buf = new BigUint64Array(1); - crypto.getRandomValues(buf); - const id = buf[0] & ((1n << 63n) - 1n); - return id === 0n ? 1n : id; -} - -/** The publisher node an origin's claims name. */ -export interface Identity { - readonly node: bigint; -} - -/** - * One origin's own route: the Node ID every session publishing it declares, and the revision - * numbering the changes to its claims. A browser forwards nothing, so this is the only route it - * originates, along a path of its own hop alone. Mirrors the declared identity of - * `route::path::Router` in rs/moq-net. - * - * @internal - */ -export class Own { - /** The current identity; a rotation replaces the node. */ - readonly identity = new Signal({ node: fresh() }); - - /** How the origin names itself in a route's Hops: the Node ID it started with, which a rotation keeps. */ - readonly hop = this.identity.peek().node; - - #table: () => object | undefined; - #seen?: object; - #revision = 0n; - - /** `table` reads the origin's claims, which a new value marks as the next revision. */ - constructor(table: () => object | undefined) { - this.#table = table; - } - - /** The Node ID the origin declares. */ - get node(): bigint { - return this.identity.peek().node; - } - - /** - * The revision of the origin's claims as `table` reads now. Read in the same task as the claims - * it certifies, so the two always agree. - */ - revision(): bigint { - const table = this.#table(); - if (table !== this.#seen) { - if (this.#seen !== undefined) { - // A change that would reach the last revision rotates the identity instead. - if (this.#revision + 1n >= MAX) this.rotate(); - else this.#revision += 1n; - } - this.#seen = table; - } - return this.#revision; - } - - /** Take a fresh identity, with a fresh revision space, ending the old one everywhere. */ - rotate(): void { - this.identity.set({ node: fresh() }); - this.#revision = 0n; - this.#seen = this.#table(); - } -} diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index 1eb630740fe..f794b0ad159 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -16,7 +16,6 @@ import type * as Instance from "./instance.ts"; import type { Lister, Tracks } from "./listing.ts"; import type * as origin from "./origin.ts"; import type * as Path from "./path.ts"; -import type { Own } from "./route.ts"; import type * as track from "./track.ts"; /** The protocol-facing operations behind a broadcast handle. */ @@ -63,11 +62,8 @@ export interface OriginProducer { interests(listener: InterestListener): Dispose; /** Whether an advertised prefix overlaps the handle's allowed paths. */ accepts(prefix: Path.Valid): boolean; - /** - * Land a route a peer announced, taken as given and never forwarded back to a peer. `covers`, - * when set, says per request whether it serves a path strictly beneath `prefix`. - */ - receive(prefix: Path.Valid, route?: Partial, covers?: (path: Path.Valid) => boolean): origin.Claim; + /** Land a route a peer announced, taken as given and never forwarded back to a peer. */ + receive(prefix: Path.Valid, route?: Partial): origin.Claim; attach(discovery: boolean): Dispose; /** * Hold the origin's announcement streams overlapping `prefix` unsynced until @@ -109,8 +105,6 @@ export interface OriginConsumer { local(path: Path.Valid, instance?: Instance.Valid): broadcast.Consumer | undefined; /** Resolve `path` for serving; throws `Unroutable` when the route serves another `instance`. */ demand(path: Path.Valid, instance?: Instance.Valid, signal?: AbortSignal): Promise; - /** The lite-07 route identity the advertisements are originated under. */ - readonly own: Own; /** Whether the handle's scope admits everything beneath the root-relative `prefix`. */ covers(prefix: Path.Valid): boolean; } @@ -168,16 +162,6 @@ export interface Established { * keeps serving. */ leave(): void; - /** - * Whether the session's claim of origin `node` at `at` may serve a request for `path` beneath - * it: lite-07's floors. Unset where every claim covers its subtree. - */ - covers?(node: bigint, at: Path.Valid, path: Path.Valid): boolean; - /** - * Changes whenever what {@link covers} answers may have changed with no route reporting it: - * a floor moving what another claim of its origin node covers. - */ - readonly coverage?: Getter; // private: plumbing /** * This session's side of its auth handle. diff --git a/nix/Cargo.nix b/nix/Cargo.nix index 256244d679e..8f588314a47 100644 --- a/nix/Cargo.nix +++ b/nix/Cargo.nix @@ -19025,15 +19025,6 @@ rec { "Luke Curley " ]; dependencies = [ - { - name = "data-encoding"; - packageId = "data-encoding"; - } - { - name = "moq-net"; - packageId = "moq-net"; - optional = true; - } { name = "rind"; packageId = "rind"; @@ -19052,36 +19043,12 @@ rec { usesDefaultFeatures = false; features = [ "std" ]; } - { - name = "serde"; - packageId = "serde"; - optional = true; - features = [ "derive" ]; - } { name = "thiserror"; packageId = "thiserror 2.0.21"; } - { - name = "zeroize"; - packageId = "zeroize"; - optional = true; - features = [ "derive" ]; - } ]; devDependencies = [ - { - name = "hex"; - packageId = "hex"; - } - { - name = "serde_json"; - packageId = "serde_json"; - } - { - name = "tempfile"; - packageId = "tempfile"; - } { name = "workspace-hack"; packageId = "workspace-hack"; @@ -19089,25 +19056,15 @@ rec { ]; features = { "cpu" = [ "dep:rind" ]; - "default" = [ "endpoint" ]; - "endpoint" = [ - "dep:moq-net" - "dep:rind" - "dep:zeroize" - ]; "provider" = [ "cpu" "dep:rind-rustls" "dep:rustls" ]; - "serde" = [ "dep:serde" ]; }; resolvedDefaultFeatures = [ "cpu" - "default" - "endpoint" "provider" - "serde" ]; }; "moq-e2ee" = rec { @@ -20204,11 +20161,6 @@ rec { name = "url"; packageId = "url"; } - { - name = "zeroize"; - packageId = "zeroize"; - features = [ "derive" ]; - } ]; devDependencies = [ { @@ -20844,12 +20796,6 @@ rec { "client" ]; } - { - name = "moq-crypto"; - packageId = "moq-crypto"; - usesDefaultFeatures = false; - features = [ "endpoint" ]; - } { name = "moq-net"; packageId = "moq-net"; @@ -59531,37 +59477,6 @@ rec { name = "getrandom"; packageId = "getrandom 0.4.3"; usesDefaultFeatures = false; - target = { target, features }: (target.name == "aarch64-apple-darwin"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "aarch64-unknown-linux-gnu"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "x86_64-pc-windows-msvc"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "x86_64-unknown-linux-gnu"); features = [ "std" "sys_rng" @@ -61014,37 +60929,6 @@ rec { name = "getrandom"; packageId = "getrandom 0.4.3"; usesDefaultFeatures = false; - target = { target, features }: (target.name == "aarch64-apple-darwin"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "aarch64-unknown-linux-gnu"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "x86_64-pc-windows-msvc"); - features = [ - "std" - "sys_rng" - ]; - } - { - name = "getrandom"; - packageId = "getrandom 0.4.3"; - usesDefaultFeatures = false; - target = { target, features }: (target.name == "x86_64-unknown-linux-gnu"); features = [ "std" "sys_rng" diff --git a/quest/m0/test-flakes-3/interop-finish-unroutable.md b/quest/m0/test-flakes-3/interop-finish-unroutable.md new file mode 100644 index 00000000000..b2a0fce22ec --- /dev/null +++ b/quest/m0/test-flakes-3/interop-finish-unroutable.md @@ -0,0 +1,47 @@ +# [M] A request right after its announcement is not refused unroutable + +## Goal + +`just test interop --all` passes its `finish` lane under load. A relay never +answers UNROUTABLE to a request for a claim it announced milliseconds +earlier, and a deterministic test (a kio simulation or a relay integration +test) fails without the fix. + +## Plan + +Seen 2026-11-17 on +[moq-dev/moq#8987](https://github.com/moq-dev/moq/pull/8987): 3 of about 30 +runs of the lane, all while the machine was loaded by other builds, and none +in 19 runs once the load fell or under 8 busy loops. Whether `main` before +that PR does the same was not checked. + +The lane's publisher ends its broadcast when the linger runs out and +announces `.health` on the same lite-07 session. Every reader +waits for the first to go and subscribes to `live` on the second the moment +it is announced. In each failing run the relay logged, in order: its session +with the publisher announcing the health route +(`lite::subscriber::routed: announce`), then about 5 ms later +`subscribed error ... err=unroutable` for the first three or four readers, +then about 8 ms later `source closed` for the ended broadcast on the +publisher's session, then the upstream subscribe starting for the readers +that asked after that, which all pass. The readers refused never retry, so +they pass their deadline. + +Ruled out with tracing: `route::node::State::forward` returned no refusal in +a failing run, so the node found the claim's slot serving and the refusal +came from the origin beneath it. The sites left are the ones answering +`Error::Unroutable` in `rs/moq-net/src/model/origin.rs` (`Requesting::poll_ok` +when its lookup fails while discovery is synced, the lookup's own +`best_route` under the node filter, and the pinned instance check) and the +validity checks in `rs/moq-net/src/model/broadcast.rs`. Tracing them did not +catch a failure, since it stopped reproducing. + +Do not fix it in the test with a retry: a viewer that subscribes as a +broadcast appears would see the same refusal. + +Public API: none. Wire: none expected. + +## Related + +- [The lite-07 route hang](/quest/m0/nightly/lite07-route-hang.md) - another timing fault on the lite-07 route path, with a bench that reproduces +- [What the route switch left](/quest/m2/multicast/switch.md) - the PR that saw it diff --git a/quest/m1/playwright-pin.md b/quest/m1/playwright-pin.md index 13caccd8974..b53cf4601f6 100644 --- a/quest/m1/playwright-pin.md +++ b/quest/m1/playwright-pin.md @@ -7,9 +7,11 @@ or later, the first build whose `exportKeyingMaterial` follows draft-ietf-webtrans-http3, so the route key lane (`test/interop/clients/js/route-key.ts`) proves the Chromium tab. The lane already requires a proof from Chromium 158 on, so the bump changes no -expectation. Firefox's exporter departs from the draft in every build so far; -[its own quest](/quest/m5/routes-browser-proof.md) carries -that bump. +expectation. Firefox's exporter departs from the draft in every build so far. + +[moq-dev/moq#8987](https://github.com/moq-dev/moq/pull/8987) removed the route key and its lane, so nothing +waits on this bump any more: [the switch's leftovers](/quest/m2/multicast/switch.md) +list restating or deleting this quest. The root flake's `pkgs.playwright-driver` supplies `PLAYWRIGHT_BROWSERS_PATH` and `PLAYWRIGHT_VERSION` (`flake.nix`), and the npm pins diff --git a/quest/m2/README.md b/quest/m2/README.md index 0f156eb979f..b8af48cb2bb 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -89,7 +89,7 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): - ✅ Left m2, so the cut stops waiting on them: the [probe epic](/quest/m3/probe/README.md) to m3 and the routes - [browser proof](/quest/m5/routes-browser-proof.md) to m5 (each waits on a + browser proof to m5, since deleted with the route key (each waits on a browser release and breaks nothing); the docs-only and additive quests and outbound federation to [m1](/quest/m1/README.md); and [unbounded groups](/quest/m3/unbounded-groups/README.md) to m3, whose byte diff --git a/quest/m2/cluster-routes/acceptance.md b/quest/m2/cluster-routes/acceptance.md index 899a661edc1..14c7dc6257b 100644 --- a/quest/m2/cluster-routes/acceptance.md +++ b/quest/m2/cluster-routes/acceptance.md @@ -61,11 +61,8 @@ What remains: ## Required - [The switch](/quest/m2/multicast/switch.md) - the rule whose fixtures replace the mitigations, once the new route layer is on the wire -- [Held after close](/quest/m2/cluster-routes/held-after-close.md) - a relay whose own session closed shows its held claims unavailable, not offline -- [Doubt holds](/quest/m2/cluster-routes/doubt-holds.md) - a relay keeps holding while doubt alone keeps it off its routes - [Route fan-out](/quest/m2/cluster-routes/route-fanout.md) - a route change costs only the streams and broadcasts it touches ## Related - [Routes and announces](/quest/m2/cluster-routes/README.md) - the contract and its fixtures -- [Doubt and keep-alive](/quest/m2/cluster-routes/doubt-keepalive.md) - whether the doubt timer follows the keep-alive diff --git a/quest/m2/cluster-routes/doubt-holds.md b/quest/m2/cluster-routes/doubt-holds.md deleted file mode 100644 index 3957ee5207e..00000000000 --- a/quest/m2/cluster-routes/doubt-holds.md +++ /dev/null @@ -1,52 +0,0 @@ -# [M] Doubt holds - -## Goal - -A relay whose only routes left are kept off by doubt holds its claims, -unavailable, until the doubt lifts and it moves onto one, instead of letting -go while its neighbours answer that they have nothing. - -## Plan - -Reordered 2026-11-15 (maintainer, /quest-plan on [cache-aware -multicast](/quest/m2/multicast/README.md)): this waits on the -[bake-off](https://github.com/moq-dev/moq/pull/8880). The new rule has neither holds nor -doubt, so nothing would be left for this to fix. If the new rule goes ahead, -[the switch](/quest/m2/multicast/switch.md) deletes this quest with the -fixtures that pin it; if it does not, this starts as written. - -Kept 2026-11-15 (maintainer, /quest-complete on -[moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)): ✅ keep it in -m2 (rejected: drop; moving it to m3). - -Found by [acceptance](/quest/m2/cluster-routes/acceptance.md): -`route::tests::flap::residual_a_relay_kept_off_by_doubt_lets_go_before_it_lifts` -pins it on the router. The publisher sits behind a transit relay that loses -most of its links, leaving only routes through it, which every relay that -heard a link die doubts for the timer. A relay with no usable route holds, -its neighbours are in the same state and answer that they have nothing, and -it lets go a hop after the cut: the claim goes Unavailable, then gone, then -back once the doubt lifts. - -`route_failover::live_mesh_link_failure_keeps_presence` measured it on a -34-relay mesh before [moq-dev/moq#8734](https://github.com/moq-dev/moq/pull/8734): -over 5 publishers, 98 readers lost their subscription. That fixture publishes -on the relay itself, so since #8734 doubt no longer blocks its routes, and it -loses 6. A real-session fixture for this quest needs the publisher behind the -relay whose links close. - -The contract already says a node holds "while a neighbour offers a route that -only the doubt keeps it off". Find why the answers end the hold first: a -neighbour that holds only because of doubt should answer with ROUTE_HOLD, not -nothing. Check the rule in `RouteHandoff.tla` with the `verify-route` skill -before changing `rs/moq-net/src/route/path.rs`. - -## Required - -- [The switch](/quest/m2/multicast/switch.md) - deletes this with the old rule, unless the maintainer keeps today's rule on [moq-dev/moq#8880](https://github.com/moq-dev/moq/pull/8880) - - -## Related - -- [Routes and announces](/quest/m2/cluster-routes/README.md) - Plan item 27 and the hold rule -- [Held after close](/quest/m2/cluster-routes/held-after-close.md) - the same symptom at the relay whose own session closed diff --git a/quest/m2/cluster-routes/doubt-keepalive.md b/quest/m2/cluster-routes/doubt-keepalive.md deleted file mode 100644 index 8f2305d7ef6..00000000000 --- a/quest/m2/cluster-routes/doubt-keepalive.md +++ /dev/null @@ -1,45 +0,0 @@ -# [S] Doubt and keep-alive - -## Goal - -No relay moves onto a route through a relay that died silently, however far -apart its neighbours notice the death within the keep-alive. - -## Plan - -Reordered 2026-11-15 (maintainer, /quest-plan on [cache-aware -multicast](/quest/m2/multicast/README.md)): this waits on the -[bake-off](https://github.com/moq-dev/moq/pull/8880). The maintainer deferred how the -doubt covers a silent death on 2026-11-15, "not yet sure about the doubt -design", and decided the same day that evidence replaces the doubt. If the new -rule goes ahead, [the switch](/quest/m2/multicast/switch.md) deletes this -quest with the fixtures that pin it; if it does not, this starts as written. - -If the doubt stays, the decision returns to the maintainer: (a) the doubt -lasts at least the configured idle timeout, so it covers the spread (the -recommendation: no wire change, and a relay already knows its idle timeout); -(b) relay keep-alives shorten below the doubt, which costs traffic on every -relay link; (c) accept the window and keep the test pinning it. - -Kept 2026-11-15 (maintainer, /quest-complete on -[moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)): ✅ keep it in -m2 (rejected: drop; moving it to m3). - -Found by [acceptance](/quest/m2/cluster-routes/acceptance.md) (epic Plan -item 30's first prior-art fixture): -`route_acceptance::a_vanished_relay_is_noticed_a_keep_alive_apart` kills -`X` silently, and its neighbours `R1`, `R2`, `R3` notice at 0 s, 1.5 s, and -3 s. With the 1 s doubt, `R1` moves onto a neighbour's route through the -dead `X` at 1 s, holds again at 1.5 s, and moves onto `R3`'s route through -`X` at 2.5 s; `R2` does the same at 2.5 s. All three go offline exactly once, -at 3 s. Readers see each move as available for a moment, and a request in -that window goes to a dead relay. A 1 s doubt does not cover a 3 s spread. - -## Required - -- [The switch](/quest/m2/multicast/switch.md) - deletes this with the old rule, unless the maintainer keeps today's rule on [moq-dev/moq#8880](https://github.com/moq-dev/moq/pull/8880) - - -## Related - -- [Routes and announces](/quest/m2/cluster-routes/README.md) - Plan item 27's doubt and item 30 diff --git a/quest/m2/cluster-routes/held-after-close.md b/quest/m2/cluster-routes/held-after-close.md deleted file mode 100644 index bc00d135ca9..00000000000 --- a/quest/m2/cluster-routes/held-after-close.md +++ /dev/null @@ -1,50 +0,0 @@ -# [M] Held after close - -## Goal - -A relay whose own session to its next hop closes, leaving it no usable -route, shows its claims held and unavailable to its own readers, as its -neighbours already do, instead of offline followed by a fresh Start once the -route recovers. - -## Plan - -Reordered 2026-11-15 (maintainer, /quest-plan on [cache-aware -multicast](/quest/m2/multicast/README.md)): this waits on the -[bake-off](https://github.com/moq-dev/moq/pull/8880). The new rule has no hold: a reader -debounces unavailable to offline locally, which answers the same symptom. If -the new rule goes ahead, [the switch](/quest/m2/multicast/switch.md) deletes -this quest with the fixtures that pin it; if it does not, this starts as -written. - -Kept 2026-11-15 (maintainer, /quest-complete on -[moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)): ✅ keep it in -m2 (rejected: drop; moving it to m3). - -Found by [acceptance](/quest/m2/cluster-routes/acceptance.md) on real -lite-07 sessions, three times over: -`route_acceptance::a_ring_waits_out_the_doubt_for_a_backup_through_the_far_end`, -`route_acceptance::a_primary_that_fails_and_returns_takes_every_relay_back`, -and `route_cluster::a_partitioned_lan_reaches_itself_through_the_cdn_and_heals` -pin it. The router holds the route correctly; the relay's readers see -Offline at the cut, then Start about 2 s later, after the origin's -retraction quarantine. Subscriptions end and a fresh one reads on. - -The cause is in `rs/moq-net/src/route/node.rs` (`Node::close` and -`State::close`): a held claim's only slot in the origin was on the closed -session's stream, and closing the stream withdraws everything it served, so -nothing is left to show the claim unavailable. - -Recommended: when a held claim loses its last slot to a closing stream, -move it, unavailable, onto a stream that still hears the held route, or show -it through the node itself, before the closing stream withdraws it. Turn the -three pinned fixtures into the contract's held-then-available sequence. - -## Required - -- [The switch](/quest/m2/multicast/switch.md) - deletes this with the old rule, unless the maintainer keeps today's rule on [moq-dev/moq#8880](https://github.com/moq-dev/moq/pull/8880) - - -## Related - -- [Routes and announces](/quest/m2/cluster-routes/README.md) - the hold rule and "Presence and availability are separate" diff --git a/quest/m2/multicast/switch.md b/quest/m2/multicast/switch.md index a7bf44e79c4..169180934f8 100644 --- a/quest/m2/multicast/switch.md +++ b/quest/m2/multicast/switch.md @@ -1,151 +1,100 @@ -# [XL] lite-07 sessions run the new route rule +# [L] What the route switch left ## Goal -Every lite-07 session in Rust drives the -new router (`route::relay::Router`, from -[moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901)) on one announce stream per side, -the draft specifies it, and the old rule is gone: ROUTE_HOLD, the doubt, -DEAD's moved list, the Route Key Parameter with its proof and symbolic model, -qualified Node IDs, routes per prefix with their Route Suffix and Route -Depth, `path::Router`, and `RouteHandoff.tla`. The draft's routing text is -shorter than today's and the announce stream carries fewer message types. +The release cut publishes no route API that only tests call, the moq-cluster +draft and its moq-transport binding are gone, the route proof binds to the +router that ships, and no quest still describes the old route rule. -`js/net` implements the endpoint half only: it picks among the routes it -receives and sends claims, and it holds no router and declares no Node ID. - -The cut then publishes no route API or config that the old rule needed or -that nothing calls, and the moq-cluster draft, which specifies a routing -rule this one abandons, is retired with its moq-transport binding. +[moq-dev/moq#8987](https://github.com/moq-dev/moq/pull/8987) put every +lite-07 session on `route::relay::Router`, rewrote the draft, made `js/net` +an endpoint, and deleted the old rule with its route key. It left the items +below, each decided there or in the plan it came from. ## Plan -Decided 2026-11-15 (maintainer, /quest-plan): lite-07 carries the new rule -and the cut waits for it ([epic](/quest/m2/multicast/README.md) item 2). -lite-07 is `-wip`, so relays pinned to `main` roll together, as each earlier -lite-07 wire change did. - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ The plan stands ([epic](/quest/m2/multicast/README.md) item 13; - rejected: the route exchange as a separately versioned SETUP extension; - the plan with a written fallback). -- ✅ `js/net` is an endpoint (rejected: porting the router to JS). The wire - below already says an endpoint that never forwards declares no Node ID - and sends claims, not routes; the Goal used to say every JS session - "drives the new router". This is where JS's dedicated route code - shrinks, about 2,270 lines by the audit's count - (`js/net/src/lite/floors.ts`, `route_key.ts`, and the announce handling - around them). -- ✅ The public route API and config the old rule needed are removed here, - and the route items nothing outside moq-net calls become crate-private, - listed under "Public surface" below (rejected: `#[doc(hidden)]` until - later; shipping them and breaking again). The cut freezes whatever this - PR leaves public. -- ✅ `moq_crypto::endpoint` goes with the Route Key, its only caller. -- ✅ The moq-cluster draft is retired with this PR (rejected: reconciling - the draft; an "out of date" note). If a third-party moq-transport relay - turns out to negotiate the extension, rewrite the draft to what ships - instead and say who. - -Recommended wire, for the implementer to confirm or improve; each departure -is a decision to list in the PR: - -- A route is started, updated, and ended, and a closed session is named in - one fixed-size message. Nothing answers a hold, and no message lists moved - routes: the updates follow in order on the same stream. -- A claim carries its chain as a field of its own, replacing the temporary - Lite-06 Chain and its Setup Parameter: the nodes that announced it again - across a scoped grant or an older version. -- A request keeps its Instance and the origin node its first hop chose, and - loses Route Depth. That ends the second subscription a move from a claim's - route to its answer's opens on one link, which - `route_failover::residual_two_depths_of_one_claim_subscribe_twice` pins - ([moq-dev/moq#8881](https://github.com/moq-dev/moq/pull/8881)): flip it to - one subscription. -- An endpoint that never forwards declares no Node ID. A peer holding a - scoped publish grant sends claims and no routes, and the relay announces - them under its own Node ID. Peers that trust each other with the whole - tree exchange routes. -- The link mark stays as `upstream`. moq-net's per-link `proxy` switch, which - the relay hard-wires on, goes if nothing else needs it; that is a public - API change to report. -- Recommended by the audit, not decided: one identity per node. Once - qualified Node IDs are gone, a Node ID and a Hop ID differ only when a - Node ID rotates, which the draft requires when an origin's Revision would - reach 2^64 - 1 (`drafts/draft-lcurley-moq-lite.md:518`, `:536`). No origin - makes 2^64 changes. Drop the rotation rule and the Hop ID with it; - ROUTE_START's Node ID is then the first hop of its path and can go too. -- Recommended, not decided: the Rendezvous Hash is normative FNV-1a with a - private offset basis, `0x420C0DECB00B` (`draft:602`, - `rs/moq-net/src/model/origin.rs:796`). Every node must rank alike, and an - implementer who reaches for a stock FNV-1a will not. Use the standard - basis, or add a sentence saying the basis is deliberate. -- Recommended, not decided: number the Announce Stream's message types - densely when the set shrinks. `-wip` peers refuse each other by ALPN - anyway, and the holes freeze otherwise. - -Measured 2026-11-15 by the [bake-off](https://github.com/moq-dev/moq/pull/8880), -and decided 2026-11-16 -([maintainer](https://github.com/moq-dev/moq/pull/8880#issuecomment-6911055514)), -for the wire: - -- The closed-session message names the session and the node at its far end, - and ends every route its sender offered through it, so no end follows per - route. -- A draining node gets a fixed-size message of its own, sent once per - neighbour: flagging each route cost 158,462 route messages for one GOAWAY on - 32 relays, against 1,454 with it and 116 today. -- A claim's end carries one bit, ended or lost, and a claim carries the lowest - link priority to its publisher and a draining bit beside its cost and chain. -- A claims message with no change still carries its floor. -- Among routes of equal rank a node takes one with no upstream-marked link on - its path before staying on its next hop, or a neighbour behind its own - upstream link is reachable by arrival order (decided by the coordinator on - 2026-11-16 and confirmed by the maintainer's merge pick of - [moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901)). -- A claim carries an unavailable bit beside its draining bit. An endpoint or - scoped neighbour is told what the node's own reader shows: the closest claim - while a route reaches one, and while none does, the claim of the best - precedence marked unavailable, withdrawn only when the reader's debounce - runs out. A scoped neighbour's adopter announces the claim again with the - bit, so its domain keeps the claim and fails requests closed, a request - reaching that adopter included, instead of withdrawing and starting it - again. The debounce runs from when a reader first showed the claim - unavailable, so the domain past a grant lets the claim go about when the - near one does, not a debounce later. The route exchange between routing - nodes keeps no timer (decided by the coordinator on 2026-11-16 and confirmed by the maintainer's merge pick of - [moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901)). -- The unavailable bit counts only as a change to a run the receiver already - holds from that sender, a run being the claim's distance and epoch. A sender - still tells a new asker what its reader shows, the bit included, but a - receiver never takes a run it is first told unavailable, which nothing can - serve: that run is not there until it is told available, and then is taken - as usual. A sender that moves to such a run no longer gives the one it gave, - which the receiver drops as lost. A gateway whose session opens while a - claim is unavailable therefore announces nothing and starts no route, a - claim that comes back unavailable across a second grant starts none either, - and an unreachable newer run never fences an older one another neighbour - still serves (decided by the coordinator on 2026-11-16 and confirmed by the maintainer's merge pick of - [moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901); - per run rather than per claim by the implementer, on review). -- A message names each claim once, and a receiver refuses one that names a - claim twice, so no order within a message decides what it says (decided by - the implementer on 2026-11-16 and confirmed by the maintainer's merge pick of - [moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901)). -- A node offers a route to itself only once it announces a claim, so a relay - that has never announced a claim and only forwards or only serves viewers - has no route on the wire. -- A scoped neighbour is sent the node's closest claim per broadcast, and never - one that came from that neighbour. -- Today's rule cost 300,100 route messages when a publisher left two meshes - joined by two grants; the chain cost none. Keep that shape in the acceptance - fixtures. +Decided 2026-11-17 (maintainer, on +[that PR](https://github.com/moq-dev/moq/pull/8987#issuecomment-6958210502)): + +- ✅ The switch merged without the moq-cluster retirement and the + crate-private route items, which land here before the cut (rejected: + holding the switch for them). +- ✅ This quest is kept. +- ✅ The adopted-claim gap is closed before the cut, not left to the + implementer; how is still a recommendation. + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit), and still +to do. The cut freezes the public API and the wire, so these land before it: + +- ✅ The moq-cluster draft is retired with its moq-transport binding + (rejected: reconciling the draft; an "out of date" note). If a third-party + moq-transport relay turns out to negotiate the extension, rewrite the draft + to what ships instead and say who. It is `drafts/draft-lcurley-moq-cluster.md`, + `rs/moq-net/src/ietf/cluster.rs`, `js/net/src/ietf/cluster.ts`, its four + code points (`rs/moq-net/src/ietf/mod.rs`), and its uses in `ietf/peer.rs`, + `ietf/parameters.rs`, `ietf/publish_namespace.rs`, + `ietf/subscribe_namespace.rs`, `ietf/session.rs`, `ietf/publisher.rs`, and + `ietf/subscriber.rs`, about 300 sites in Rust and 240 in JS, most of them + tests of hop paths between moq-transport peers. A moq-transport session + then carries no hop path: it is an endpoint. Drop the extension from + `doc/concept/standard.md`, `doc/bin/relay/cluster.md`, and the `max_hops` + docs (`cluster::Config::max_hops`, `origin::Config::max_hops`, + `doc/bin/relay/config.md`), which then bound lite-03 to lite-06 only. Run + `just test interop --all`. +- ✅ The route items nothing outside moq-net calls become crate-private + (rejected: `#[doc(hidden)]` until later; shipping them and breaking + again). All in `rs/moq-net/src/model/origin.rs`: `Config::update_hold`, + `Source`, `RouteInfo::source()`, and `Consumer::local()`. Kixel and moq.pro + call none of them (checked 2026-11-17). Their callers are tests and benches + outside the crate, which need another way in first: + `rs/moq-net/tests/integration/mesh_withdraw.rs` and + `benches/origin.rs` and `benches/auth.rs` set `update_hold`, + `rs/moq-cli/src/play/media.rs` sleeps for it, + `rs/moq-net/tests/integration/dial_split_horizon.rs`, + `rs/moq-relay/tests/integration/auth_lifetime.rs`, and the tests of + `rs/moq-relay/src/cluster.rs` read `source()` and `local()`. `Source::Peer(0)` + means "named none", a special case inside a value, which AGENTS.md forbids + in public API. + +- ✅ A claim adopted over a marked link that does not route never reaches an + upstream through a peer. Today such a claim is withheld from a marked + routing neighbour, but still floods to unmarked routing neighbours, who may + forward it over their own marked links. It matters at a rollout: with two + releases side by side a relay's upstream speaks an older version and does + not route, so the relay adopts what it learns there, and a pair of edges + could carry a broadcast from one core to another. Recommended, not decided: + a second, marked identity and route for what a node adopts across a marked + link, so the route rule's own mark carries it. Test it with an upstream on + lite-06 between two cores, as `rs/moq-relay/tests/integration/upstream_links.rs` + does on lite-07. + +Left by the switch, for the implementer to decide and list in the PR: + +- The announce-churn mitigations (`DEFAULT_UPDATE_HOLD` and + `RETRACT_QUARANTINE` in `rs/moq-net/src/model/origin.rs`, and the same-clock + dedup) sit in the announce cursor every version shares and carry no marker + saying they are temporary. Gate what + [acceptance](/quest/m2/cluster-routes/acceptance.md) does not retire on the + lite-06 session path under one named marker. +- The path-rule benches (drain, repath, follow) left `benches/routes.rs` with + the old router and have no equivalent on the new one. Add them, swept over + both axes. +- Costs the switch measured and left: re-offering a route sends its node's + claims again; a non-routing peer is told one ANNOUNCE_UPDATE per broadcast + when a route's cost changes; an edit swapping one prefix for another tells + again the claims both cover; a relay whose only route closes ends its + subscriptions while the claim stays shown. + +- `poll::Session::export_keying_material` has no caller now that the Route + Key proof is gone, and no release ever had it. Remove it from moq-net, + moq-quic, moq-tokio, and moq-uring. Recommended before the cut, which + would otherwise freeze it; the cut also drops the `## Unreleased` note + that describes it and the Route Key (`rs/moq-net/MIGRATE.md` "Origins + prove a route key"), since `sh/migrate.sh` refuses a `MIGRATE.md` edit + outside a cut. Found 2026-11-16 by [the proof](https://github.com/moq-dev/moq/pull/8904) -against the prototype, and moved here when -[moq-dev/moq#8901](https://github.com/moq-dev/moq/pull/8901) finished the -router quest that listed them: +against the prototype: - Order equal routes by the neighbour's Node ID, or give the proof's binding the key the router orders them by: the proof orders them by the neighbour, @@ -155,116 +104,35 @@ router quest that listed them: then each grant's exporter and adopter, so a node refuses a claim naming it in the role it would take. The prototype and the router record only the adopters, so they refuse fewer echoes than the proof assumes. -- Move the binding to the router before this PR changes it: point - `route/tests/algebra.rs` and `route/tests/sticky.rs` at the router's own - functions for a node's own route, sending a route on, taking one in, - ordering candidates, and listing them, regenerate `Vectors.agda`, and run - `just test route-proof`. The claim instance first needs the router's - precedence as its leading keys: a claim exactly at its path before a - broader one shown there, then the newest epoch, decided over every claim - of the Instance at that path whether or not a route reaches it, and only - then the route joined with the claim's drain, priority, and cost. Neither - the mechanized instance nor its Rust vectors cover precedence yet. - -Delete with the old rule: - -- `rs/moq-net/src/route/proof.rs`, `js/net/src/lite/route_key.ts`, - `rs/moq-net/verify/route-key/`, the `verify-route-key` skill, and the - interop route key lane (`test/interop/clients/js/route-key.ts`). -- The Route Key's public pieces, which the list above does not reach: - `origin::RouteKey` (`rs/moq-net/src/route/mod.rs:35`), - `origin::Config::route_key` (`rs/moq-net/src/model/origin.rs:112`), and - the relay's `cluster.route_key` with `--cluster-route-key` and - `MOQ_CLUSTER_ROUTE_KEY` (`rs/moq-relay/src/cluster.rs:741-748`, read at - `:1471`). The key is new since release, so it needs no refusal. -- `moq_crypto::endpoint` (the persistent Ed25519 node key, its z-base-32 - ID, the `serde` feature, and `just rs crypto-key`): its one caller is the - Route Key load at `rs/moq-relay/src/cluster.rs:1472`. A public key type - for Kixel's trust layer is Kixel's to add. -- The moq-cluster extension: `drafts/draft-lcurley-moq-cluster.md` (361 - lines), `rs/moq-net/src/ietf/cluster.rs` (536), `js/net/src/ietf/cluster.ts` - (263), its four code points (`rs/moq-net/src/ietf/mod.rs:99-114`), its - uses in `ietf/peer.rs`, `ietf/parameters.rs`, and `publish_namespace`, - and its mentions in `doc/concept/standard.md:53` and - `doc/bin/relay/cluster.md`. The draft still tells a relay to advertise a - lower cost for a namespace it already carries (line 52), the warm - discount that formed pull cycles here, and lets a link cost 0 (line 88), - which `route::Error::ZeroCost` refuses. The code implements neither, and - item 10 of the epic makes a moq-transport session an endpoint, which has - no path to carry. `cluster.max_hops` then bounds lite-03 to lite-06 only: - drop the MoQ Cluster extension from its docs (`cluster::Config::max_hops`, - `origin::Config::max_hops`, `doc/bin/relay/cluster.md`, and - `doc/bin/relay/config.md`). -- `rs/moq-net/verify/route/` and the `verify-route` skill, or rewrite the - skill for the exhaustive search. -- [Firefox tabs prove their route key](/quest/m5/routes-browser-proof.md), - and the release cut's reason to wait on - [the Playwright bump](/quest/m1/playwright-pin.md). -- [Doubt holds](/quest/m2/cluster-routes/doubt-holds.md), - [doubt and keep-alive](/quest/m2/cluster-routes/doubt-keepalive.md), - [held after close](/quest/m2/cluster-routes/held-after-close.md), and - whatever of [route fan-out](/quest/m2/cluster-routes/route-fanout.md) the - new router answers, with the fixtures that pin them. - -Public surface, to settle in this PR because the cut freezes it by -omission. All in `rs/moq-net/src/model/origin.rs`: - -- `Config::update_hold` (`:155`): no reader or writer outside moq-net - except one test sleep (`rs/moq-cli/src/play/media.rs:2478`). Crate-private - now; [acceptance](/quest/m2/cluster-routes/acceptance.md) retires the - hold itself. -- `Producer::with_proxy` (`:2404`): one caller, - `rs/moq-relay/src/cluster.rs`, always `true`. Remove it or make it - crate-private, as the wire bullet above says. -- `Source` (`:588`), `RouteInfo::source()` (`:704`), and - `Consumer::local()` (`:7701`): called only under `#[cfg(test)]` in - moq-relay. `Source::Peer(0)` means "named none", a special case inside a - value, which AGENTS.md forbids in public API. Crate-private. -- Before hiding each, grep Kixel and moq.pro for a caller (the maintainer's - condition for every unused-API removal) and keep what one uses. -- `Config::hop` is now `node` and `with_preference` is `with_priority`; - this PR must not reintroduce the old names. The Route Offer's priority - byte stays on the wire: the relay has no key to set it yet, and - [outbound federation](/quest/m3/cluster-routing/federation.md) adds one. -- moq-ffi exposes only a route's `cost` and `available` - (`rs/moq-ffi/src/origin.rs`), so no binding changes. - -The announce-churn mitigations (`DEFAULT_UPDATE_HOLD` 300 ms at `:159`, -`RETRACT_QUARANTINE` 2 s at `:164`, and the same-clock dedup) sit in the -announce cursor every version shares and carry no marker saying they are -temporary. Whatever [acceptance](/quest/m2/cluster-routes/acceptance.md) -does not retire, this PR gates on the lite-06 session path under one named -marker, as the Lite-06 Chain is marked -(`rs/moq-net/src/lite/setup.rs:24-25`). The claim chain replaces the -Lite-06 Chain here, so update or delete that marker too: today it promises -a deletion at lite-08 that this plan makes permanent in another form. - -The route plan says what an endpoint sends. Say in the draft what an -endpoint that never forwards must parse of routes, dead hops, and floors, -and what it may ignore: a third-party client implements that list. - -Rewrite the assertions of the acceptance fixtures -(`tests/integration/route_acceptance.rs`, `route_failover.rs`, -`route_cluster.rs`) for the new rule, keeping their topologies. - -Quests written against the old wire, to retarget or delete in this PR: +- Move the binding to the router: point `route/tests/algebra.rs` and + `route/tests/sticky.rs` at the router's own functions for a node's own + route, sending a route on, taking one in, ordering candidates, and listing + them, regenerate `Vectors.agda`, and run `just test route-proof`. The claim + instance first needs the router's precedence as its leading keys: a claim + exactly at its path before a broader one shown there, then the newest + epoch, decided over every claim of the Instance at that path whether or not + a route reaches it, and only then the route joined with the claim's drain, + priority, and cost. Neither the mechanized instance nor its Rust vectors + cover precedence yet. + +Quests written against the old wire, to retarget or delete: [outbound federation](/quest/m3/cluster-routing/federation.md), [the routing guide](/quest/m3/routing-guide.md), [route wakes](/quest/m4/route-wakes.md), [handoff routes](/quest/m4/relay-handoff-routes.md), [regrant recheck](/quest/m4/regrant-route-recheck.md), [announce interest memory](/quest/m4/announce-interest-memory.md), -[the mesh condition](/quest/m5/lite07-mesh.md), and -[route memory](/quest/m9/perf/cluster-route-memory.md). +[the mesh condition](/quest/m5/lite07-mesh.md), +[route memory](/quest/m9/perf/cluster-route-memory.md), +[route fan-out](/quest/m2/cluster-routes/route-fanout.md), and +[the Playwright bump](/quest/m1/playwright-pin.md), whose only reason was the +route key lane. + +Public API: breaking. `Config::update_hold`, `Source`, `RouteInfo::source()`, +and `Consumer::local()` leave the public API. Wire: the moq-cluster extension +on moq-transport is no longer sent or read. -Update the draft's Announce, Floors, Routing, Dead Hops, and Resolution -sections, the message sections, the Setup Parameters, and the lite-07 -changelog, and `doc/bin/relay/cluster.md`. Run `just check`, -`just test interop --all`, and `just drafts check`. +## Related -Public API: breaking. `origin::RouteKey`, `Config::route_key`, and -`moq_crypto::endpoint` are removed; `Config::update_hold`, -`Producer::with_proxy`, `Source`, `RouteInfo::source()`, and -`Consumer::local()` leave the public API. Config and CLI: `cluster.route_key` -is removed (never released). Wire: lite-07-wip only; the moq-cluster -extension on moq-transport is no longer sent or read. +- [Cache-aware multicast](/quest/m2/multicast/README.md) - the epic +- [Acceptance](/quest/m2/cluster-routes/acceptance.md) - retires the update hold itself diff --git a/quest/m5/routes-browser-proof.md b/quest/m5/routes-browser-proof.md deleted file mode 100644 index ef5f9d4b532..00000000000 --- a/quest/m5/routes-browser-proof.md +++ /dev/null @@ -1,69 +0,0 @@ -# [S] Firefox tabs prove their route key to the relay - -## Goal - -Once a Firefox release follows the draft's exporter, a lite-07 session from -it connects to `moq-relay` with its route-key proof verified, as a current -Chromium tab's does, and the nightly route key lane keeps both that way. - -The lane (`test/interop/clients/js/route-key.ts`, in `test/interop` nightly -and the release gate) dials the relay from each browser on lite-07 and reads -the relay's log for the tab's verified proof. Each build either must prove or -must send no proof. One that must send none either holds the lite-07 cut, -skipping or failing under `CI_STRICT` (which release PRs set), or connects -unproven by design and passes. Chromium 158 and later must prove, which the -[Playwright bump](/quest/m1/playwright-pin.md) -reaches. Every Firefox build connects unproven, so the lite-07 cut does not -wait on Firefox. - -Firefox's exporter departs from draft-ietf-webtrans-http3 section 4.8: neqo -writes the session ID into the exporter context as a varint -(`neqo-http3/src/webtransport.rs`, since -[mozilla/neqo#3464](https://github.com/mozilla/neqo/pull/3464)), where the -draft has used a 64-bit field since the exporter was defined (draft-10). The -relay and Chromium follow the draft. Checked 2026-11-06 against Firefox 157, -whose export matches the relay's derivation with a varint session ID and no -other. Firefox 160 changes only the arguments -([bug 2079306](https://bugzilla.mozilla.org/show_bug.cgi?id=2079306)), and -neqo's `main` still writes the varint. So `@moq/net` sends no proof from any -Firefox (`js/net/src/lite/route_key.ts`, keyed on the user agent, since the -exporter's arity cannot tell the derivation apart), and a Firefox tab -connects unproven rather than being refused. - -## Plan - -Moved to m5 2026-11-12 (maintainer, /quest-audit): it waits on a Firefox release and the lite-07 cut ships Firefox unproven (2026-11-07, below), so it no longer gates lite-07 through the routes epic. - -Decided 2026-11-06 (maintainer, /quest-complete while queueing -[moq-dev/moq#8022](https://github.com/moq-dev/moq/pull/8022)): cover Firefox -and Chromium, and never send a proof the relay will reject. - -Decided 2026-11-07 (maintainer, /quest-unblock): ✅ cut lite-07 with Firefox -unproven (rejected: the cut waits for a Firefox that proves; the relay also -accepting neqo's varint derivation, refused because it departs from the draft -and tries a second path at runtime; the relay picking the derivation from the -CONNECT's User-Agent, which is server-side UA sniffing). This replaces -2026-11-06's "a mismatch blocks the cut". An unproven tab is a supported -state, the neqo fix is one line, and the lane still fails loud if the relay -refuses a Firefox tab. - -Reported upstream on 2026-11-07 as -[mozilla/neqo#4319](https://github.com/mozilla/neqo/issues/4319), with the -one-line fix (approved by the maintainer in /quest-unblock). - -Once a Firefox release carries neqo's fix, gate `route_key.ts` on Firefox -majors before it, set the lane's table (`uncovered` in `route-key.ts`) to -require a proof from it on and to pass older majors unproven, and bump -Playwright to a release bundling it, the way the -[Playwright bump](/quest/m1/playwright-pin.md) does for -Chromium. Verify the fixed build against the relay the way the -2026-11-06 check did: its export must match the relay's for the same session. - -## Waiting - -- Firefox: a release vendors the neqo fix for - [mozilla/neqo#4319](https://github.com/mozilla/neqo/issues/4319), which - writes the exporter context's session ID as 64 bits. neqo merged it on - 2026-11-09 in [mozilla/neqo#4323](https://github.com/mozilla/neqo/pull/4323), - after neqo v0.34.0; Firefox main still vendored v0.34.0 that day. Check the - neqo version in Firefox's `Cargo.lock` for each release. diff --git a/rs/justfile b/rs/justfile index 995d4749849..d3d0b77e467 100644 --- a/rs/justfile +++ b/rs/justfile @@ -18,18 +18,13 @@ no_fuzz := "--exclude moq-net-fuzz --exclude moq-quic-fuzz --exclude moq-mux-fuz default: just check -# Model-check a TLA+ spec with TLC, e.g. `just rs tla moq-net/verify/route/RouteHandoff.tla`. +# Model-check a TLA+ spec with TLC, e.g. `just rs tla moq-net/verify/failover/FailoverChain.tla`. # Pass `-config rs/.cfg` for a config not named after the spec, and # `../.tla` for a spec outside `rs/`, such as a generated one in `.tmp/`. # sh/tlc.py says how a run shares the host. tla spec *args: python3 sh/tlc.py rs/{{ spec }} {{ args }} -# Prove a Tamarin model's lemmas, e.g. `just rs tamarin moq-net/verify/route-key/RouteKey.spthy`. -# Pass `-D=` for a variant the model defines. -tamarin spec *args: - nix shell --inputs-from . nixpkgs#tamarin-prover --command tamarin-prover --prove {{ args }} rs/{{ spec }} - # Default features for the selected packages; `features` covers the feature # matrix nightly and on release PRs. No `cargo check` pass: clippy is a # superset of it, and the two use different rustc wrappers, so running both @@ -256,7 +251,6 @@ features: run just rs net-features --all run just rs coroutines run just rs quic-features --all - run just rs crypto-key run just rs media-features --all run bash sh/local.sh cargo check --locked --workspace {{ no_fuzz }} --all-targets --no-default-features run bash sh/local.sh cargo check --locked -p moq-cli --no-default-features @@ -293,31 +287,13 @@ coroutines: run env RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p moq-hls --no-deps --no-default-features run bash sh/rs/coroutines.sh moq-stats -- --no-default-features run env RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p moq-stats --no-deps --no-default-features - run bash sh/rs/coroutines.sh moq-crypto -- --no-default-features --features endpoint,provider,serde - run env RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p moq-crypto --no-deps --no-default-features --features endpoint,provider,serde + run bash sh/rs/coroutines.sh moq-crypto -- --no-default-features --features provider + run env RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p moq-crypto --no-deps --no-default-features --features provider run bash sh/rs/coroutines.sh moq-e2ee run env RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p moq-e2ee --no-deps run bash sh/rs/coroutines.sh rs/moq-auth/Cargo.toml -- --no-default-features finish -# Prove moq-crypto's key-only build, which moq-auth depends on, leaves out the transport, then lint and test it alone; a workspace build unifies the default features back in. -crypto-key: - #!/usr/bin/env bash - set -euo pipefail - source sh/checks.sh - key_only_dependencies() { - graph=$(cargo tree --locked -p moq-crypto --no-default-features --features serde -e normal --prefix none) || return - if grep -E '^moq-net ' <<<"$graph"; then - echo "moq-crypto without endpoint must not depend on moq-net" >&2 - return 1 - fi - } - run key_only_dependencies - run bash sh/local.sh cargo clippy --locked -p moq-crypto --no-default-features --all-targets -- -D warnings - run bash sh/local.sh cargo clippy --locked -p moq-crypto --no-default-features --features serde --all-targets -- -D warnings - run bash sh/rs/nextest.sh cargo nextest run --locked -p moq-crypto --no-default-features --features serde - finish - # Prove moq-quic leaves kio's dev-only clock runtime to its consumers, and lints without its default features; a workspace build unifies both back in. [positional-arguments] quic-features *args: diff --git a/rs/moq-crypto/Cargo.toml b/rs/moq-crypto/Cargo.toml index 52c55469513..04edc91ebfe 100644 --- a/rs/moq-crypto/Cargo.toml +++ b/rs/moq-crypto/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "moq-crypto" -description = "Cryptography the MoQ crates share: the endpoint key, the rind provider, and the CPU check." +description = "Cryptography the MoQ crates share: the rind provider and the CPU check." authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" @@ -9,39 +9,25 @@ version = "0.0.11" edition = "2024" rust-version.workspace = true -keywords = ["quic", "webtransport", "tls", "ed25519", "live"] +keywords = ["quic", "webtransport", "tls", "live"] categories = ["cryptography", "multimedia", "network-programming"] [package.metadata.docs.rs] all-features = true [features] -# Without `endpoint`, the crate holds only `endpoint::PublicKey`, the endpoint ID, and its -# z-base-32 text: no `moq-net` and no rind, for crates that only name endpoints. -default = ["endpoint"] -# The persistent `endpoint::SecretKey`, which converts to `moq_net::origin::RouteKey`. -endpoint = ["dep:moq-net", "dep:rind", "dep:zeroize"] # CPU support and its shared error need only rind. cpu = ["dep:rind"] # The rustls provider adds TLS without needing `moq-net`. provider = ["cpu", "dep:rind-rustls", "dep:rustls"] -# `endpoint::PublicKey` serializes as its canonical z-base-32 text. -serde = ["dep:serde"] [dependencies] -data-encoding = { workspace = true } -moq-net = { workspace = true, optional = true } rind = { workspace = true, optional = true } rind-rustls = { workspace = true, optional = true } rustls = { version = "0.23", default-features = false, features = ["std"], optional = true } -serde = { workspace = true, optional = true } thiserror = { workspace = true } -zeroize = { workspace = true, optional = true } [dev-dependencies] -hex = { workspace = true } -serde_json = { workspace = true } -tempfile = { workspace = true } workspace-hack = { path = "../workspace-hack" } [lints] diff --git a/rs/moq-crypto/README.md b/rs/moq-crypto/README.md index 69db100c1f0..b909aad8225 100644 --- a/rs/moq-crypto/README.md +++ b/rs/moq-crypto/README.md @@ -2,19 +2,14 @@ # moq-crypto -Cryptography the [Media over QUIC](https://moq.dev) crates share: the `endpoint` module holds -the key that names an endpoint, the `provider` module is the +Cryptography the [Media over QUIC](https://moq.dev) crates share: the `provider` module is the [rind](https://github.com/kixel-ai/rind) rustls provider, and `cpu` holds the CPU check and its error. ## Features -`endpoint`, the default, enables that module's secret key. With default features off, the crate is -only `endpoint::PublicKey`, the endpoint ID, with its canonical z-base-32 text: it builds without -`moq-net` or rind, for crates that only name endpoints. -`serde` adds the key's string serialization. `cpu`, enabled by `provider`, adds -only rind. `provider`, off by default, adds the rustls integration without `moq-net`, so -transport crates can use it without a dependency cycle. +Both are off by default. `cpu` adds only rind. `provider` enables it and adds the rustls +integration, so transport crates can use it without a dependency cycle. ## Provider @@ -31,10 +26,3 @@ runs rind's slower paths rather than being refused: moq-auth, moq-hls, moq-e2ee, moq-rtmp, and the transports report the same `cpu::UnsupportedCpu`, and `moq_tokio::crypto` re-exports this module's API. - -## Endpoint key - -An endpoint's `endpoint::SecretKey` is an Ed25519 key that `SecretKey::load_or_generate(path)` keeps -for the life of a host, as 52 z-base-32 characters in a `0600` file it never replaces implicitly. -`moq-relay` loads it for `--cluster-route-key`, where it converts into `moq_net::origin::RouteKey`. -Its `endpoint::PublicKey` is the endpoint ID, displayed as those 52 characters (a DNS label). diff --git a/rs/moq-crypto/src/endpoint/key.rs b/rs/moq-crypto/src/endpoint/key.rs deleted file mode 100644 index 236ef63be2a..00000000000 --- a/rs/moq-crypto/src/endpoint/key.rs +++ /dev/null @@ -1,153 +0,0 @@ -//! The Ed25519 public key that names an endpoint, and its z-base-32 text. -//! -//! This builds without the `endpoint` feature, so a crate that only names endpoints shares the one -//! codec without `moq-net` or rind. - -use std::fmt; -use std::str::FromStr; - -/// Ed25519 key length in bytes, for both the secret seed and the public key. -pub(crate) const KEY_LEN: usize = 32; - -/// z-base-32: most significant bit first, no padding, trailing bits must be zero. -pub(crate) static ZBASE32: std::sync::LazyLock = std::sync::LazyLock::new(|| { - let mut spec = data_encoding::Specification::new(); - spec.symbols.push_str("ybndrfg8ejkmcpqxot1uwisza345h769"); - spec.encoding().expect("a valid z-base-32 specification") -}); - -/// An endpoint's Ed25519 public key, which is also its endpoint ID. -/// -/// Its text form is the 52-character [z-base-32] of the key, the form pkarr and iroh's DNS -/// discovery use, which is also a valid DNS label. Parsing accepts only that form (lowercase, -/// zero trailing bits), so one key has exactly one ID to name a path by. -/// -/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt -#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] -pub struct PublicKey([u8; KEY_LEN]); - -impl PublicKey { - /// The ID of the raw 32-byte Ed25519 public key. - pub fn from_bytes(bytes: [u8; KEY_LEN]) -> Self { - Self(bytes) - } - - /// The raw 32-byte Ed25519 public key. - pub fn as_bytes(&self) -> &[u8; KEY_LEN] { - &self.0 - } -} - -/// The text is not the 52-character z-base-32 of a 32-byte key. -#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] -#[error("invalid key: expected 52 z-base-32 characters")] -#[non_exhaustive] -pub struct InvalidKey; - -impl FromStr for PublicKey { - type Err = InvalidKey; - - fn from_str(text: &str) -> Result { - Ok(Self(decode(text)?)) - } -} - -impl fmt::Display for PublicKey { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&ZBASE32.encode(&self.0)) - } -} - -impl fmt::Debug for PublicKey { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("PublicKey").field(&format_args!("{self}")).finish() - } -} - -#[cfg(feature = "serde")] -impl serde::Serialize for PublicKey { - fn serialize(&self, serializer: S) -> Result { - serializer.collect_str(self) - } -} - -#[cfg(feature = "serde")] -impl<'de> serde::Deserialize<'de> for PublicKey { - fn deserialize>(deserializer: D) -> Result { - let text = ::deserialize(deserializer)?; - text.parse().map_err(serde::de::Error::custom) - } -} - -/// Decode exactly 52 z-base-32 characters. The alphabet is lowercase-only and nonzero trailing -/// bits are refused, so a key has one text form. -pub(crate) fn decode(text: &str) -> Result<[u8; KEY_LEN], InvalidKey> { - let mut out = [0u8; KEY_LEN]; - match ZBASE32.decode_len(text.len()) { - Ok(KEY_LEN) => ZBASE32.decode_mut(text.as_bytes(), &mut out).map_err(|_| InvalidKey)?, - _ => return Err(InvalidKey), - }; - Ok(out) -} - -#[cfg(test)] -mod tests { - use super::PublicKey; - - /// Public key bytes (hex) and their endpoint ID. The first is RFC 8032's test 1. - const KEYS: [(&str, &str); 3] = [ - ( - "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a", - "47pjoycnsrfmxikm95jh13y88e8qnhzu5kungjpxyepgt7a8krpy", - ), - ( - "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", - "999999999999999999999999999999999999999999999999999o", - ), - ( - "0000000000000000000000000000000000000000000000000000000000000000", - "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", - ), - ]; - - /// Text that is not the one canonical form of any key. - const INVALID: [&str; 11] = [ - "EYAMFTWCF3SCK8RS5M1MEUGF8ODWQG78473T7P3ST9WXOB9CSZ8Y", - "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8", - "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8yy", - "0yamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", - "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8b", - "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", - "", - "9999999999999999999999999999999999999999999999999999", - "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y====", - " eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", - "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y\n", - ]; - - #[test] - fn keys_round_trip_their_text() { - for (public, endpoint) in KEYS { - let bytes: [u8; 32] = hex::decode(public).unwrap().try_into().unwrap(); - let key: PublicKey = endpoint.parse().unwrap(); - assert_eq!(key, PublicKey::from_bytes(bytes), "{endpoint}"); - assert_eq!(key.as_bytes(), &bytes, "{endpoint}"); - assert_eq!(key.to_string(), endpoint); - #[cfg(feature = "serde")] - { - let text = serde_json::Value::from(endpoint); - assert_eq!(serde_json::to_value(key).unwrap(), text, "{endpoint}"); - assert_eq!(serde_json::from_value::(text).unwrap(), key, "{endpoint}"); - } - } - } - - #[test] - fn invalid_text_is_refused() { - for text in INVALID { - assert!(text.parse::().is_err(), "{text:?}"); - #[cfg(feature = "serde")] - assert!(serde_json::from_value::(text.into()).is_err(), "{text:?}"); - } - } -} diff --git a/rs/moq-crypto/src/endpoint/mod.rs b/rs/moq-crypto/src/endpoint/mod.rs deleted file mode 100644 index b85403f481a..00000000000 --- a/rs/moq-crypto/src/endpoint/mod.rs +++ /dev/null @@ -1,19 +0,0 @@ -//! The Ed25519 key that names an endpoint. -//! -//! An endpoint's [`SecretKey`] persists in a file and is the key a relay proves to its peers (the -//! cluster route key); its [`PublicKey`] is the endpoint ID, shown as 52 z-base-32 characters. -//! -//! Without the `endpoint` feature, this module holds only [`PublicKey`] and its text codec. - -#![warn(missing_docs)] - -mod key; -#[cfg(feature = "endpoint")] -mod secret; - -pub use key::{InvalidKey, PublicKey}; -#[cfg(feature = "endpoint")] -pub use secret::SecretKey; - -#[cfg(all(test, feature = "endpoint"))] -mod tests; diff --git a/rs/moq-crypto/src/endpoint/secret.rs b/rs/moq-crypto/src/endpoint/secret.rs deleted file mode 100644 index 359d0cd0d0c..00000000000 --- a/rs/moq-crypto/src/endpoint/secret.rs +++ /dev/null @@ -1,133 +0,0 @@ -//! An endpoint's persistent Ed25519 secret key. - -use std::fmt; -use std::io::{self, Write}; -use std::sync::Arc; - -use rind::signature::Ed25519KeyPair; -use zeroize::Zeroizing; - -use crate::endpoint::key::{KEY_LEN, PublicKey, ZBASE32, decode}; - -/// The PKCS#8 v1 (RFC 8410) encoding of an Ed25519 key, up to its 32-byte seed. rind loads a seed -/// alone only this way, and the key file stores the seed alone. -const PKCS8_SEED_PREFIX: [u8; 16] = [ - 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, -]; - -struct Inner { - pair: Ed25519KeyPair, - public: PublicKey, -} - -/// An endpoint's Ed25519 secret key: cheap to clone, redacted from `Debug`. -#[derive(Clone)] -pub struct SecretKey(Arc); - -impl SecretKey { - /// Generate a fresh key from the system's secure random source. - pub fn generate() -> Self { - Self::new(Ed25519KeyPair::generate().expect("system randomness")) - } - - pub(crate) fn from_seed(seed: &[u8; KEY_LEN]) -> Self { - let mut der = Zeroizing::new([0u8; PKCS8_SEED_PREFIX.len() + KEY_LEN]); - der[..PKCS8_SEED_PREFIX.len()].copy_from_slice(&PKCS8_SEED_PREFIX); - der[PKCS8_SEED_PREFIX.len()..].copy_from_slice(seed); - Self::new(Ed25519KeyPair::from_pkcs8(der.as_ref()).expect("a PKCS#8 v1 Ed25519 key")) - } - - fn new(pair: Ed25519KeyPair) -> Self { - let public = PublicKey::from_bytes( - pair.public_key() - .as_ref() - .try_into() - .expect("a 32-byte Ed25519 public key"), - ); - Self(Arc::new(Inner { pair, public })) - } - - /// The public key, which is this endpoint's ID. - pub fn public(&self) -> PublicKey { - self.0.public - } - - /// Load the key stored at `path`, or generate one and store it there if the file is missing. - /// - /// The file holds the seed as 52 z-base-32 characters and a newline, created with mode - /// `0600`. A key is never replaced implicitly: an existing file that does not parse, or that - /// other users can read, is an error rather than a reason to generate a new identity. - /// - /// # Errors - /// - /// [`io::ErrorKind::InvalidData`] for a malformed or exposed file, or the I/O error reading or - /// creating it. - pub fn load_or_generate(path: impl AsRef) -> io::Result { - let path = path.as_ref(); - match Self::load(path) { - Err(err) if err.kind() == io::ErrorKind::NotFound => {} - other => return other, - } - - let key = Self::generate(); - let mut options = std::fs::OpenOptions::new(); - options.write(true).create_new(true); - #[cfg(unix)] - std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600); - let mut file = match options.open(path) { - Ok(file) => file, - // Another process created it first; its key wins. - Err(err) if err.kind() == io::ErrorKind::AlreadyExists => return Self::load(path), - Err(err) => return Err(err), - }; - // Sized up front, so appending the newline never leaves an unzeroized copy behind. - let mut text = Zeroizing::new(String::with_capacity(ZBASE32.encode_len(KEY_LEN) + 1)); - ZBASE32.encode_append(key.0.pair.to_seed().as_ref(), &mut text); - text.push('\n'); - file.write_all(text.as_bytes())?; - file.sync_all()?; - Ok(key) - } - - fn load(path: &std::path::Path) -> io::Result { - let file = std::fs::File::open(path)?; - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt; - if file.metadata()?.permissions().mode() & 0o077 != 0 { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - format!("key file {} is accessible by other users", path.display()), - )); - } - } - let mut text = Zeroizing::new(String::new()); - io::Read::read_to_string(&mut &file, &mut text)?; - let encoded = text.strip_suffix('\n').unwrap_or(&text); - let seed = Zeroizing::new(decode(encoded).map_err(|_| { - io::Error::new( - io::ErrorKind::InvalidData, - format!("key file {} is not 52 z-base-32 characters", path.display()), - ) - })?); - Ok(Self::from_seed(&seed)) - } -} - -impl From<&SecretKey> for moq_net::origin::RouteKey { - /// The same key, for an origin to prove to its peers. - fn from(key: &SecretKey) -> Self { - let seed = key.0.pair.to_seed(); - let seed: Zeroizing<[u8; KEY_LEN]> = Zeroizing::new(seed.as_ref().try_into().expect("a 32-byte Ed25519 seed")); - Self::from_seed(&seed) - } -} - -impl fmt::Debug for SecretKey { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SecretKey") - .field("public", &self.0.public) - .field("seed", &"") - .finish() - } -} diff --git a/rs/moq-crypto/src/endpoint/tests.rs b/rs/moq-crypto/src/endpoint/tests.rs deleted file mode 100644 index 662b3c88cbf..00000000000 --- a/rs/moq-crypto/src/endpoint/tests.rs +++ /dev/null @@ -1,92 +0,0 @@ -use zeroize::Zeroizing; - -use crate::endpoint::SecretKey; - -/// RFC 8032's test 1 seed and the endpoint ID of its public key. -const SEED: &str = "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60"; -const ENDPOINT: &str = "47pjoycnsrfmxikm95jh13y88e8qnhzu5kungjpxyepgt7a8krpy"; - -fn seed() -> Zeroizing<[u8; 32]> { - Zeroizing::new(hex::decode(SEED).unwrap().try_into().unwrap()) -} - -#[test] -fn seed_derives_its_endpoint_id() { - assert_eq!(SecretKey::from_seed(&seed()).public().to_string(), ENDPOINT); -} - -#[cfg(unix)] -#[test] -fn key_file_loads_its_seed() { - use std::os::unix::fs::PermissionsExt; - - use crate::endpoint::key::ZBASE32; - let dir = tempfile::tempdir().unwrap(); - let path = dir.path().join("endpoint.key"); - std::fs::write(&path, format!("{}\n", ZBASE32.encode(seed().as_ref()))).unwrap(); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap(); - assert_eq!( - SecretKey::load_or_generate(&path).unwrap().public().to_string(), - ENDPOINT - ); -} - -#[test] -fn key_file_persists_and_never_rotates() { - let dir = tempfile::tempdir().unwrap(); - let path = dir.path().join("endpoint.key"); - - let created = SecretKey::load_or_generate(&path).unwrap(); - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt; - assert_eq!(std::fs::metadata(&path).unwrap().permissions().mode() & 0o777, 0o600); - } - let loaded = SecretKey::load_or_generate(&path).unwrap(); - assert_eq!(created.public(), loaded.public()); - // The seed as 52 z-base-32 characters and a newline. - let text = std::fs::read_to_string(&path).unwrap(); - let encoded = text.strip_suffix('\n').unwrap(); - assert_eq!(encoded.len(), 52); - assert!( - encoded - .bytes() - .all(|b| b"ybndrfg8ejkmcpqxot1uwisza345h769".contains(&b)), - "{text}" - ); - - // A damaged file is an error, never a reason to mint a new identity. - std::fs::write(&path, "not a key\n").unwrap(); - let err = SecretKey::load_or_generate(&path).unwrap_err(); - assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); - assert_eq!(std::fs::read_to_string(&path).unwrap(), "not a key\n"); -} - -#[cfg(unix)] -#[test] -fn key_file_readable_by_others_is_refused() { - use std::os::unix::fs::PermissionsExt; - let dir = tempfile::tempdir().unwrap(); - let path = dir.path().join("endpoint.key"); - SecretKey::load_or_generate(&path).unwrap(); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o640)).unwrap(); - let err = SecretKey::load_or_generate(&path).unwrap_err(); - assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); -} - -#[test] -fn debug_redacts_the_seed() { - let key = SecretKey::from_seed(&[0x42; 32]); - let debug = format!("{key:?}"); - assert!(!debug.contains(&"42".repeat(32)), "{debug}"); - assert!(debug.contains(""), "{debug}"); - assert!(debug.contains(&key.public().to_string())); -} - -#[test] -fn route_key_is_the_same_key() { - let key = SecretKey::from_seed(&seed()); - let route = moq_net::origin::RouteKey::from(&key); - let expected = moq_net::origin::RouteKey::from_seed(&seed()); - assert_eq!(format!("{route:?}"), format!("{expected:?}")); -} diff --git a/rs/moq-crypto/src/lib.rs b/rs/moq-crypto/src/lib.rs index 12a0a999f48..a2645b81424 100644 --- a/rs/moq-crypto/src/lib.rs +++ b/rs/moq-crypto/src/lib.rs @@ -1,19 +1,14 @@ -//! Cryptography the MoQ crates share: endpoint keys, the provider, and the CPU check. +//! Cryptography the MoQ crates share: the provider and the CPU check. //! -//! [`endpoint`] holds the Ed25519 key that names an endpoint, which a relay proves to its peers -//! as its cluster route key. //! [`provider`] is rind's rustls provider; [`cpu`] holds the CPU check and [`cpu::UnsupportedCpu`] //! error that moq-quic, moq-tokio, and the other transport crates report. //! -//! The `endpoint` feature, the default, gates the secret key; `provider`, off by default, gates -//! the rustls provider and enables `cpu`, which needs only rind. Without any of these features -//! the crate holds only [`endpoint::PublicKey`], the endpoint ID, and its canonical z-base-32 -//! text, with no `moq-net` or crypto backend; `serde` adds its string serialization. +//! Both are off by default: `provider` gates the rustls provider and enables `cpu`, which needs +//! only rind. #![warn(missing_docs)] #[cfg(feature = "cpu")] pub mod cpu; -pub mod endpoint; #[cfg(feature = "provider")] pub mod provider; diff --git a/rs/moq-net-tests/tests/integration/restart.rs b/rs/moq-net-tests/tests/integration/restart.rs index d708ebfa846..a521f34b203 100644 --- a/rs/moq-net-tests/tests/integration/restart.rs +++ b/rs/moq-net-tests/tests/integration/restart.rs @@ -903,3 +903,40 @@ priority_update_tests! { priority_update_ietf18: "moq-transport-18", priority_update_ietf22: "moq-transport-22", } + +/// An endpoint replacing its own broadcast ends the old instance for its reader: the +/// broadcast handed out first has closed by the time its replacement is handed out, as +/// one a publisher ended, not one held in case its route returns. +#[kio::test] +async fn an_endpoint_replacing_its_broadcast_ends_the_old_one() { + let version: Version = "moq-lite-07-wip".parse().unwrap(); + let endpoint = || { + let (producer, driver) = origin::Producer::new(origin::Config::default()); + support::harness::spawn(driver); + producer + }; + let publisher = endpoint(); + let viewer = endpoint(); + let _session = link(version, &publisher, &viewer).await; + let old = publisher.route("live", origin::RouteOptions::default()).unwrap(); + let old_track = old.broadcast().create_track("video", timed()).unwrap(); + let mut following = viewer.consume().follow("live", None).unwrap(); + let held = following.available().await.unwrap().expect("the first instance"); + let mut subscription = held.track("video").unwrap().subscribe(None).await.unwrap(); + write(&old_track, "old:0"); + assert_eq!(read(&mut subscription).await, "old:0"); + settle().await; + + let _replacement = publisher.route("live", origin::RouteOptions::default()).unwrap(); + let next = kio::clock::timeout(Duration::from_secs(10), following.available()) + .await + .expect("the takeover hung") + .unwrap() + .expect("the replacement"); + assert!(!next.is_clone(&held)); + assert!(held.is_closed(), "the replaced broadcast is still open"); + + // The subscription already on it stays. + write(&old_track, "old:1"); + assert_eq!(read(&mut subscription).await, "old:1"); +} diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index d444cb4e785..1141e1a032e 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -57,7 +57,6 @@ slab = { workspace = true } thiserror = { workspace = true } tracing = { workspace = true } url = { workspace = true } -zeroize = { workspace = true } [dev-dependencies] criterion = { package = "bench-harness", path = "../bench-harness" } diff --git a/rs/moq-net/benches/routes.rs b/rs/moq-net/benches/routes.rs index d9a37857d44..a5cd9435f80 100644 --- a/rs/moq-net/benches/routes.rs +++ b/rs/moq-net/benches/routes.rs @@ -23,17 +23,6 @@ //! - refollow: the same node closes one prefix's stream and opens it again. The claims //! axis is expected to grow, since the stream hears its prefix's claims again; the //! prefixes axis no faster than the prefixes held. -//! - path/watched, path/unwatched, path/received: the same fan-out grids on the path rule. -//! - path/follow, path/teardown, path/refollow: the prefix-by-claim grid on the path -//! router, including initial following and timer work with a virtual clock. -//! - path/drain: a relay hears a node it reaches over many sessions send GOAWAY, with -//! a route per session sent to each stream it answers. Swept over the leaving -//! node's sessions and the streams: both axes are expected to grow, since each -//! stream is re-sent each route ranked draining, and no faster than their product. -//! - path/repath: a relay hears one publisher's route move onto another path, and -//! answers streams the route misses. Swept over the claims behind the route and those -//! streams: neither axis is expected to grow, though the streams axis does today -//! (`route::tests::cost::residual_a_route_change_visits_every_unrelated_stream`). //! //! The route layer is crate-private, so this reaches it through the `fuzz` module. //! @@ -54,13 +43,6 @@ const HELD: [(usize, usize); 4] = [(10, 10), (10_000, 10), (10, 100), (10_000, 1 /// `(prefixes, claims)` shapes for a node following one origin per prefix. const FOLLOWED: [(usize, usize); 4] = [(16, 1), (1_024, 1), (16, 16), (1_024, 16)]; -/// `(sessions, streams)` shapes for a relay hearing a node it reaches over many -/// sessions drain. -const DRAINING: [(usize, usize); 4] = [(4, 4), (128, 4), (4, 128), (128, 128)]; - -/// `(claims, streams)` shapes for one route's change, with streams it misses. -const REPATH: [(usize, usize); 4] = [(1, 10), (10_000, 10), (1, 1_000), (10_000, 1_000)]; - /// `(claims, lag)` shapes for a relay hearing a stream that lags another. const LAGGING: [(usize, usize); 4] = [(100, 1), (10_000, 1), (100, 100), (10_000, 10_000)]; @@ -168,121 +150,6 @@ fn bench_refollow(c: &mut Criterion) { group.finish(); } -fn bench_path_teardown(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/teardown"); - for (prefixes, claims) in FOLLOWED { - let id = BenchmarkId::from_parameter(format!("{prefixes}p_{claims}c")); - group.bench_function(id, |b| { - b.iter_batched( - || fuzz::PathRouteFollower::new(prefixes, claims), - fuzz::PathRouteFollower::teardown, - BatchSize::PerIteration, - ); - }); - } - group.finish(); -} - -fn bench_path_follow(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/follow"); - for (prefixes, claims) in FOLLOWED { - let id = BenchmarkId::from_parameter(format!("{prefixes}p_{claims}c")); - group.bench_function(id, |b| { - b.iter_batched( - || (), - |()| fuzz::PathRouteFollower::new(prefixes, claims), - BatchSize::PerIteration, - ); - }); - } - group.finish(); -} - -fn bench_path(c: &mut Criterion, name: &str, interest: fn(usize) -> String, sent: usize) { - let mut group = c.benchmark_group(format!("routes/path/{name}")); - for (claims, streams) in SHAPES { - let id = BenchmarkId::from_parameter(format!("{claims}c_{streams}s")); - let mut fixture = None; - group.bench_function(id, |b| { - let node = fixture.get_or_insert_with(|| { - let interests: Vec = (0..streams).map(interest).collect(); - let interests: Vec<&str> = interests.iter().map(String::as_str).collect(); - fuzz::PathRouteNode::new(claims, &interests) - }); - b.iter(|| { - node.own("live/extra", true); - assert_eq!(node.drain(), sent * streams); - node.own("live/extra", false); - assert_eq!(node.drain(), sent * streams); - }); - }); - } - group.finish(); -} - -fn bench_path_watched(c: &mut Criterion) { - bench_path(c, "watched", |_| String::new(), 1); -} - -fn bench_path_unwatched(c: &mut Criterion) { - bench_path(c, "unwatched", |i| format!("other/{i}"), 0); -} - -fn bench_path_received(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/received"); - for (claims, changes) in RECEIVED { - let id = BenchmarkId::from_parameter(format!("{claims}c_{changes}d")); - let mut fixture = None; - group.bench_function(id, |b| { - let relay = fixture.get_or_insert_with(|| fuzz::PathRouteRelay::new(claims)); - b.iter(|| assert_eq!(relay.change(changes), (1, changes))); - }); - } - group.finish(); -} - -fn bench_path_refollow(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/refollow"); - for (prefixes, claims) in FOLLOWED { - let id = BenchmarkId::from_parameter(format!("{prefixes}p_{claims}c")); - let mut fixture = None; - group.bench_function(id, |b| { - let follower = fixture.get_or_insert_with(|| fuzz::PathRouteFollower::new(prefixes, claims)); - b.iter(|| follower.refollow()); - }); - } - group.finish(); -} - -fn bench_path_drain(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/drain"); - for (sessions, streams) in DRAINING { - let id = BenchmarkId::from_parameter(format!("{sessions}n_{streams}s")); - group.bench_function(id, |b| { - // Borrowed, so dropping the fixture stays out of the sample. - b.iter_batched_ref( - || fuzz::PathRouteDrain::new(sessions, streams), - |node| node.drain(), - BatchSize::PerIteration, - ); - }); - } - group.finish(); -} - -fn bench_path_repath(c: &mut Criterion) { - let mut group = c.benchmark_group("routes/path/repath"); - for (claims, streams) in REPATH { - let id = BenchmarkId::from_parameter(format!("{claims}c_{streams}s")); - let mut fixture = None; - group.bench_function(id, |b| { - let node = fixture.get_or_insert_with(|| fuzz::PathRouteChange::new(claims, streams)); - b.iter(|| node.repath()); - }); - } - group.finish(); -} - criterion_group!( benches, bench_watched, @@ -292,13 +159,5 @@ criterion_group!( bench_confirmed, bench_teardown, bench_refollow, - bench_path_follow, - bench_path_watched, - bench_path_unwatched, - bench_path_received, - bench_path_teardown, - bench_path_refollow, - bench_path_drain, - bench_path_repath ); criterion_main!(benches); diff --git a/rs/moq-net/fixtures/lite.json b/rs/moq-net/fixtures/lite.json index 4e8a981d3c0..5a6763dd577 100644 --- a/rs/moq-net/fixtures/lite.json +++ b/rs/moq-net/fixtures/lite.json @@ -42,248 +42,220 @@ "expect": "refused" }, { - "name": "a Route Offer counting more hops than its body holds is malformed, though a count past the hop limit is otherwise refused as content", + "name": "a ROUTE carries a path of hops, each a Node ID, its Start, and a session, then flags, priority, and cost", "version": "moq-lite-07-wip", "message": "announce", - "hex": "064b0700000083e80100020003000400050006000700080009000a000b000c000d000e000f0010001100120013001400150016001700180019001a001b001c001d001e001f0020002100008001", - "expect": "refused" - }, - { - "name": "a ROUTE_START names its publisher, Prefix ID, suffix, whether the route is exact, and offer: a path of node and session hops, then flags, priority, and metric", - "version": "moq-lite-07-wip", - "message": "announce", - "hex": "060d92340000000207000903018005", + "hex": "070a02070100090203018005", "expect": "decoded" }, { - "name": "a ROUTE_START's suffix extends the requested prefix", + "name": "a ROUTE's 0x2 flag marks a path through a draining node", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060c92340001610001090000ff00", + "hex": "070701090100027f03", "expect": "decoded" }, { - "name": "a ROUTE_START's Exact marks a route its sender keeps at its own prefix", + "name": "a ROUTE flag no version defines is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060d92340000010207000903018005", - "expect": "decoded" + "hex": "070701090100088003", + "expect": "refused" }, { - "name": "a ROUTE_START's Exact marks a route below the requested prefix too", + "name": "a ROUTE with more than 32 hops is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060c92340001610101090000ff00", - "expect": "decoded" + "hex": "0767210101000201000301000401000501000601000701000801000901000a01000b01000c01000d01000e01000f01001001001101001201001301001401001501001601001701001801001901001a01001b01001c01001d01001e01001f0100200100210100008001", + "expect": "refused" }, { - "name": "a ROUTE_START's Exact other than 0 or 1 is malformed", + "name": "a ROUTE with no hops is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060d92340000020207000903018005", + "hex": "070400008001", "expect": "refused" }, { - "name": "a Route Offer's 0x2 flag marks a path through a draining node", + "name": "a ROUTE missing a hop it counts is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060b9234000000010900027f03", - "expect": "decoded" + "hex": "070703070100008003", + "expect": "refused" }, { - "name": "a Route Offer flag no version defines is withdrawn, with whatever field it adds", + "name": "a ROUTE hop naming Node ID 0 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060c92340000000109000880032a", - "expect": "withdrawn" + "hex": "070701000100008001", + "expect": "refused" }, { - "name": "a Route Offer with more than 32 hops is withdrawn", + "name": "a ROUTE_END references its Route ID", "version": "moq-lite-07-wip", "message": "announce", - "hex": "064b9234000000210100020003000400050006000700080009000a000b000c000d000e000f0010001100120013001400150016001700180019001a001b001c001d001e001f0020002100008001", - "expect": "withdrawn" + "hex": "080101", + "expect": "decoded" }, { - "name": "a Route Offer with no hops is refused", + "name": "a DEAD names the hop whose session closed and the node at its far end", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0609923400000000008001", - "expect": "refused" + "hex": "09050701020901", + "expect": "decoded" }, { - "name": "a Route Offer missing a hop it counts is refused", + "name": "a DEAD naming Far Node ID 0 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060b9234000000030700008003", + "hex": "09050701020001", "expect": "refused" }, { - "name": "a ROUTE_START naming Node ID 0 is withdrawn", + "name": "a DRAIN names the node that sent GOAWAY", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060a00000000010700008001", - "expect": "withdrawn" + "hex": "0a020701", + "expect": "decoded" }, { - "name": "a Route Offer hop naming Node ID 0 is withdrawn", + "name": "a DRAIN naming Node ID 0 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060b9234000000010000008001", - "expect": "withdrawn" + "hex": "0a020001", + "expect": "refused" }, { - "name": "a ROUTE_START suffix no path spells is withdrawn", + "name": "an ANNOUNCE_REQUEST continues its edit, removes Prefix IDs, and adds prefixes, each with its Hidden", "version": "moq-lite-07-wip", "message": "announce", - "hex": "060e923400032f2f7800010700008001", - "expect": "withdrawn" + "hex": "050d010200070204726f6f6d010000", + "expect": "decoded" }, { - "name": "a ROUTE_UPDATE references its Route ID", + "name": "an ANNOUNCE_REQUEST ending its edit may be empty", "version": "moq-lite-07-wip", "message": "announce", - "hex": "070701010500008003", + "hex": "0503000000", "expect": "decoded" }, { - "name": "a ROUTE_UPDATE flag no version defines is withdrawn", + "name": "an ANNOUNCE_REQUEST whose More is neither 0 nor 1 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0708010105008080032a", - "expect": "withdrawn" + "hex": "0503020000", + "expect": "refused" }, { - "name": "a ROUTE_HOLD references its Route ID", + "name": "an ANNOUNCE_REQUEST whose Hidden is neither 0 nor 1 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0b0101", - "expect": "decoded" + "hex": "05050000010002", + "expect": "refused" }, { - "name": "a ROUTE_END references its Route ID", + "name": "an ANNOUNCE_OK is empty", "version": "moq-lite-07-wip", "message": "announce", - "hex": "080101", + "hex": "0600", "expect": "decoded" }, { - "name": "a DEAD CLOSED names the hop, the far node, Gone, and how many ROUTE_UPDATEs follow", + "name": "a SYNCED names its Prefix ID", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0f06000702090102", + "hex": "040103", "expect": "decoded" }, { - "name": "a DEAD DRAIN names the node that sent GOAWAY", + "name": "an ANNOUNCE_FLOOR names its Route ID and the Revision its batch is complete as of", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0f020107", + "hex": "03020105", "expect": "decoded" }, { - "name": "a DEAD of a kind no version defines is refused", + "name": "a lite-07 ANNOUNCE_START names its instance, epoch, cost, how far above it was claimed, flags, priority, and the relays it crossed", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0f020207", - "expect": "refused" + "hex": "000f000001780161000103000080020709", + "expect": "decoded" }, { - "name": "a DEAD whose Gone is neither 0 nor 1 is refused", + "name": "a claim's 0x1 flag says no route reaches it, and its 0x2 flag that a node on the way is draining", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0f06000702090200", - "expect": "refused" + "hex": "000d00000178016100010300038000", + "expect": "decoded" }, { - "name": "a DEAD naming Far Node ID 0 is refused", + "name": "a claim flag no version defines is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "0f06000702000000", + "hex": "000d00000178016100010300048000", "expect": "refused" }, { - "name": "an ANNOUNCE_REQUEST continues its edit, removes Prefix IDs, and adds prefixes, each with its Hidden", + "name": "a claim whose chain names Node ID 0 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "100d010200070204726f6f6d010000", - "expect": "decoded" - }, - { - "name": "an ANNOUNCE_REQUEST ending its edit may be empty", - "version": "moq-lite-07-wip", - "message": "announce", - "hex": "1003000000", - "expect": "decoded" + "hex": "000e0000017801610001030000800100", + "expect": "refused" }, { - "name": "an ANNOUNCE_REQUEST whose More is neither 0 nor 1 is refused", + "name": "a claim whose chain names more than 32 relays is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "1003020000", + "hex": "002e00000178016100010300008021070707070707070707070707070707070707070707070707070707070707070707", "expect": "refused" }, { - "name": "an ANNOUNCE_REQUEST whose Hidden is neither 0 nor 1 is refused", + "name": "a lite-07 ANNOUNCE_START with an invalid path is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "10050000010002", + "hex": "000f0000032f2f78016100010300008000", "expect": "refused" }, { - "name": "an ANNOUNCE_OK is empty", + "name": "a lite-07 ANNOUNCE_START with an invalid instance is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "1100", - "expect": "decoded" + "hex": "000c000001780000010300008000", + "expect": "refused" }, { - "name": "a SYNCED names its Prefix ID", + "name": "a lite-07 ANNOUNCE_START cut short is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "040103", - "expect": "decoded" + "hex": "0003000003", + "expect": "refused" }, { - "name": "an ANNOUNCE_FLOOR carries its Revision plus one", + "name": "a lite-07 ANNOUNCE_UPDATE references its announce id and carries the claim as it now stands", "version": "moq-lite-07-wip", "message": "announce", - "hex": "09020105", + "hex": "020701020500018000", "expect": "decoded" }, { - "name": "an ANNOUNCE_FLOOR of 0 certifies nothing", + "name": "a lite-07 ANNOUNCE_END says its publisher withdrew the claim", "version": "moq-lite-07-wip", "message": "announce", - "hex": "09020100", + "hex": "01020100", "expect": "decoded" }, { - "name": "a lite-07 ANNOUNCE_START names its Route ID in place of a hop chain", + "name": "a lite-07 ANNOUNCE_END with Lost says only the sender's way to the claim is gone", "version": "moq-lite-07-wip", "message": "announce", - "hex": "000b0000017802016100010000", + "hex": "01020101", "expect": "decoded" }, { - "name": "a lite-07 ANNOUNCE_START with an invalid path is withdrawn", + "name": "a lite-07 ANNOUNCE_END whose Lost is neither 0 nor 1 is refused", "version": "moq-lite-07-wip", "message": "announce", - "hex": "000d0000032f2f7802016100010000", - "expect": "withdrawn" - }, - { - "name": "a lite-07 ANNOUNCE_START with an invalid instance is withdrawn", - "version": "moq-lite-07-wip", - "message": "announce", - "hex": "0009000001780200000100", - "expect": "withdrawn" - }, - { - "name": "a lite-07 ANNOUNCE_START cut short is refused", - "version": "moq-lite-07-wip", - "message": "announce", - "hex": "0003000003", + "hex": "01020102", "expect": "refused" }, { diff --git a/rs/moq-net/src/auth.rs b/rs/moq-net/src/auth.rs index 49f224b806b..135229acc9c 100644 --- a/rs/moq-net/src/auth.rs +++ b/rs/moq-net/src/auth.rs @@ -596,30 +596,6 @@ impl Permit { covers(&self.granted) && covers(&self.limit) } - /// Whether the limit alone allows every path at or beneath `prefix`, judged - /// pattern by pattern, so a `false` may be spurious but a `true` never is. - #[cfg(feature = "async")] - pub(crate) fn within_limit_subtree(&self, prefix: &str) -> bool { - let Ok(subtree) = moq_pattern::Pattern::subtree(prefix) else { - return false; - }; - self.limit.as_ref().is_none_or(|limit| limit.contains(&subtree)) - } - - /// The prefixes this confines the peer to, or `None` when it confines nothing: the - /// heads of the scope's patterns, which grants this side issued. What the peer - /// granted this side limits only what this side does, so a client never scopes the - /// relay that answered its token. - #[cfg(feature = "async")] - pub(crate) fn regions(&self) -> Option> { - let limit = self.limit.as_ref()?; - let everything = moq_pattern::Pattern::subtree("").ok()?; - if limit.contains(&everything) { - return None; - } - Some(crate::model::interest_prefixes(limit)) - } - /// The prefixes the peer's grant confines this direction to, or `None` while it /// grants everything: asking for one of them, rather than a prefix above it, is a /// request the peer's floors can certify. @@ -633,12 +609,6 @@ impl Permit { Some(crate::model::interest_prefixes(granted)) } - /// The limit this side set on the peer, or `None` while unrestricted. - #[cfg(feature = "async")] - pub(crate) fn limit(&self) -> Option<&Patterns> { - self.limit.as_ref() - } - /// Whether both set the same limit on the peer, whatever either was granted. #[cfg(feature = "async")] pub(crate) fn same_limit(&self, other: &Self) -> bool { @@ -3062,30 +3032,6 @@ mod tests { } } - /// Only a grant this side issued confines the peer's claims: a client scoped by the - /// relay that answered its token leaves the relay's own routes unscoped. - #[cfg(feature = "async")] - #[test] - fn regions_come_from_the_issued_scope_alone() { - let earned = Permit { - granted: Some(patterns(&[".socket"])), - limit: None, - }; - assert_eq!(earned.regions(), None, "the peer's grant to us scoped the peer"); - - let issued = Permit { - granted: None, - limit: Some(patterns(&[".socket/bob"])), - }; - assert_eq!(issued.regions(), Some(vec![crate::Path::from_static(".socket/bob")])); - - let everything = Permit { - granted: Some(patterns(&[".socket"])), - limit: Some(patterns(&[""])), - }; - assert_eq!(everything.regions(), None, "a root grant confines nothing"); - } - /// What the peer granted confines the prefixes asked of it, whatever the limit is. #[cfg(feature = "async")] #[test] diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 8636161f20b..a5851c93fe5 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -343,10 +343,6 @@ impl Client { token: self.setup_token.clone().filter(|_| version.has_auth()), ietf: self.extensions.ietf && version.has_ietf(), implementation: self.implementation(), - // Filled by `lite::start` from the attached origin handles. - route_key: None, - // Filled by `lite::start` from the version. - lite06_chain: false, } } else { lite::Setup::default() diff --git a/rs/moq-net/src/coding/writer.rs b/rs/moq-net/src/coding/writer.rs index fe75fea5c76..4765f3b29c0 100644 --- a/rs/moq-net/src/coding/writer.rs +++ b/rs/moq-net/src/coding/writer.rs @@ -889,8 +889,7 @@ mod tests { .buffer(&lite::Track { broadcast: crate::Path::from_static("test"), instance: None, - node: 0, - depth: 0, + node: None, track: "video".into(), }) .unwrap(); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index f7525c9d4c0..a739ba9ebce 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -443,8 +443,7 @@ fn hop_chain(ids: impl IntoIterator) -> Hops { /// One announcement on an announce stream, resolved: what the application sees. /// -/// The hop chain is lite-06's, and lite-07's trailing Lite-06 Chain: a lite-07 claim -/// names its route instead, and carries a chain only when it was learned over lite-06. +/// The hop ids are lite-06's hop chain, and the relays a lite-07 claim's chain names. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Announced { /// ANNOUNCE_START: a route's suffix and wire hop ids, taking the next id. @@ -455,6 +454,18 @@ pub enum Announced { End(u64), } +/// A lite-07 claim whose chain names the relays `chain`. +fn announce_claim(chain: &[u64]) -> crate::route::node::Claim { + crate::route::relay::Claim { + item: crate::route::node::Attr { epoch: 0, above: 0 }, + cost: 0, + priority: i8::MAX, + draining: false, + unavailable: false, + chain: chain.to_vec(), + } +} + fn announce_version(compress: bool) -> lite::Version { match compress { true => lite::Version::Lite07, @@ -481,29 +492,39 @@ impl AnnounceWriter { /// Append one announcement to `data`. An update or end must name a live id. pub fn write(&mut self, announced: &Announced, data: &mut Vec) { + let routes = self.version.has_routes(); let msg = match announced { Announced::Start(suffix, hops) => { let (_, suffix) = self.encoder.start(suffix.clone()); - // A fixed instance, so the bytes stay pinned and match what `js/net` writes. - lite::AnnounceBroadcast::Active { - route: 0, - instance: self.version.has_instance().then(|| "a".parse().unwrap()), - epoch: 0, - suffix, - hops: hop_chain(hops.iter().copied()), - cost: Default::default(), - above: 0, + match routes { + // A fixed instance, so the bytes stay pinned and match what `js/net` writes. + true => lite::AnnounceBroadcast::Start { + suffix, + instance: "a".parse().unwrap(), + claim: announce_claim(hops), + }, + false => lite::AnnounceBroadcast::Active { + suffix, + hops: hop_chain(hops.iter().copied()), + cost: Default::default(), + }, } } + Announced::Update(id, hops) if routes => lite::AnnounceBroadcast::Change { + id: *id, + claim: announce_claim(hops), + }, Announced::Update(id, hops) => lite::AnnounceBroadcast::Update { id: *id, hops: hop_chain(hops.iter().copied()), cost: Default::default(), - above: 0, }, Announced::End(id) => { self.encoder.end(*id); - lite::AnnounceBroadcast::EndedId { id: *id } + match routes { + true => lite::AnnounceBroadcast::End { id: *id, lost: false }, + false => lite::AnnounceBroadcast::EndedId { id: *id }, + } } }; msg.encode(&mut Encoder::new(data, self.version.into()), self.version) @@ -582,22 +603,56 @@ fn route_clock() -> kio::clock::Deadlines { kio::clock::Deadlines::new(kio::clock::Instant::now()) } -/// The session `tag` to the node `node`. -fn route_peer(tag: u64, node: u64) -> crate::route::node::Peer { - crate::route::node::Peer { tag, node } +/// The forwarding node of the relay `relay`. +fn route_id(relay: u64) -> crate::route::NodeId { + crate::route::NodeId { relay, start: 1 } } -/// The route the publisher `node` sends about itself. -fn route_offer(node: u64) -> crate::route::path::Offer { - crate::route::path::Offer { - path: [crate::route::path::Hop { node, session: 0 }].into(), - draining: false, +/// A link to a neighbour in `role`. +fn route_port(role: crate::route::relay::Role) -> crate::route::relay::Port { + crate::route::relay::Port { + cost: 1, + priority: 0, + upstream: false, + role, + } +} + +/// A neighbour that forwards nothing, asked for nothing yet. +fn route_leaf() -> crate::route::relay::Port { + route_port(crate::route::relay::Role::Scoped(Vec::new())) +} + +/// A claim at `epoch`, `cost` from its publisher. +fn route_claim(epoch: u64, cost: u64) -> crate::route::node::Claim { + crate::route::relay::Claim { + item: crate::route::node::Attr { epoch, above: 0 }, + cost, priority: i8::MAX, - metric: 0, - down_only: false, + draining: false, + unavailable: false, + chain: Vec::new(), } } +/// A peer's request for `prefix` alone. +fn route_ask(prefix: Path) -> crate::route::node::Msg { + crate::route::node::Msg::Ask(crate::route::relay::Edit { + remove: Vec::new(), + add: vec![prefix], + }) +} + +/// Take everything queued on `streams`, returning how many messages and serve changes +/// there were. +fn route_drain<'a>(streams: impl IntoIterator) -> usize { + (streams.into_iter()) + .map(|stream| { + std::iter::from_fn(|| stream.try_wire()).count() + std::iter::from_fn(|| stream.try_serve()).count() + }) + .sum() +} + /// One origin's lite-07 route node answering announce streams, for the routes bench. pub struct RouteNode { node: crate::route::Node, @@ -607,19 +662,20 @@ pub struct RouteNode { impl RouteNode { /// A node holding `claims` claims of its own under `live/`, answering one session - /// per prefix in `streams`, each already sent its snapshot. + /// per prefix in `streams`, each already sent its initial set. pub fn new(claims: usize, streams: &[&str]) -> Self { - let node = crate::route::Node::new(1, 1, route_clock()); + let node = crate::route::Node::new(route_id(1), route_clock()); let instance = crate::Instance::random(); for i in 0..claims { - node.own(Path::new(&format!("live/{i}")).unwrap(), Some(Self::claim(&instance))); + let path = Path::new(&format!("live/{i}")).unwrap(); + let live = crate::route::relay::Change::Live(route_claim(0, 0)); + node.own(false, (path, instance.clone()), live); } let streams = (streams.iter().enumerate()) .map(|(i, prefix)| { - let link = crate::route::Link::default(); - let peer = route_peer(i as u64 + 1, i as u64 + 2); - let stream = node.connect(peer, link).unwrap(); - stream.edit(route_ask(Path::new(prefix).unwrap())).unwrap(); + let stream = node.connect(i as u64 + 1, route_leaf()).unwrap(); + stream.recv(route_ask(Path::new(prefix).unwrap())).unwrap(); + stream.flush(); stream }) .collect(); @@ -632,34 +688,24 @@ impl RouteNode { node } - fn claim(instance: &crate::Instance) -> crate::route::node::Claim { - crate::route::node::Claim { - instance: instance.clone(), - epoch: 0, - cost: 0, - upstream: false, - learned: false, - above: 0, - chain: crate::Hops::new(), - } - } - /// Start or withdraw the node's own claim at `path`. pub fn own(&self, path: &str, start: bool) { - let claim = start.then(|| Self::claim(&self.instance)); - self.node.own(Path::new(path).unwrap(), claim); + let change = match start { + true => crate::route::relay::Change::Live(route_claim(0, 0)), + false => crate::route::relay::Change::Ended, + }; + let broadcast = (Path::new(path).unwrap(), self.instance.clone()); + self.node.own(false, broadcast, change); } /// Take every output queued on the streams, returning how many there were. pub fn drain(&self) -> usize { - (self.streams.iter()) - .map(|stream| std::iter::from_fn(|| stream.try_output()).count()) - .sum() + route_drain(&self.streams) } } -/// A relay's lite-07 route node hearing one origin's claims on streams it asked for, -/// and forwarding them on streams it answers, for the routes bench. +/// A relay's lite-07 route node hearing one origin's claims on the sessions to it, and +/// telling them to the sessions that ask, for the routes bench. pub struct RouteRelay { // Dropped first: a stream disconnects from its node on drop. receive: Vec, @@ -668,9 +714,9 @@ pub struct RouteRelay { node: crate::route::Node, instance: crate::Instance, claims: usize, - /// The origin's revision as the first stream last heard it. + /// The origin's revision as the first session last heard it. rev: u64, - /// The one-claim batches the first stream heard that the second has yet to: each + /// The one-claim changes the first session heard that the second has yet to: each /// revision and the claim it changed. behind: std::collections::VecDeque<(u64, usize)>, } @@ -680,31 +726,44 @@ impl RouteRelay { const ORIGIN: u64 = 1; /// A relay that already heard the origin's `claims` claims under `live/` on each of - /// `streams` streams, and forwarded them on each of `answers` streams. + /// `streams` sessions, and told them to each of `answers` sessions. fn new(claims: usize, streams: usize, answers: usize) -> Self { - let node = crate::route::Node::new(2, 2, route_clock()); + let node = crate::route::Node::new(route_id(2), route_clock()); let answer = (0..answers as u64) .map(|i| { - let peer = route_peer(i + 1, i + 3); - let stream = node.connect(peer, crate::route::Link::default()).unwrap(); - stream.edit(route_ask(Path::empty())).unwrap(); + let stream = node.connect(i + 1, route_leaf()).unwrap(); + stream.recv(route_ask(Path::empty())).unwrap(); + stream.flush(); stream }) .collect(); let instance = crate::Instance::random(); let rev = claims as u64; + let origin = route_id(Self::ORIGIN); let receive = (0..streams as u64) .map(|i| { - let peer = route_peer(answers as u64 + i + 1, Self::ORIGIN); - let receive = node.connect(peer, crate::route::Link::default()).unwrap(); + let port = route_port(crate::route::relay::Role::Routing(origin)); + let receive = node.connect(answers as u64 + i + 1, port).unwrap(); // The peer answered what the node asks it for. - receive.edited(Default::default()); - let reach = crate::route::path::Reach::Finite(route_offer(Self::ORIGIN)); - receive.route(Self::ORIGIN, Path::empty(), Some(reach)); - let snapshot = (0..claims) - .map(|i| (Self::path(i), Some(Self::claim(&instance, 0)))) - .collect(); - receive.batch(Self::ORIGIN, Path::empty(), snapshot, Some(rev)); + receive.recv(crate::route::node::Msg::Edited).unwrap(); + let offer = crate::route::relay::Offer { + path: [crate::route::relay::Hop { + node: origin, + session: 0, + }] + .into(), + draining: false, + priority: i8::MAX, + cost: 0, + marked: false, + }; + let route = crate::route::node::Msg::Route { + origin, + offer: Some(offer), + }; + receive.recv(route).unwrap(); + let changes = (0..claims).map(|i| (i, route_claim(0, 0))).collect(); + Self::hear(&receive, &instance, changes, rev); receive }) .collect(); @@ -721,20 +780,19 @@ impl RouteRelay { relay } - /// A relay hearing the origin's `claims` claims on one stream. + /// A relay hearing the origin's `claims` claims on one session. pub fn heard(claims: usize) -> Self { Self::new(claims, 1, 1) } - /// A relay hearing the origin's `claims` claims on one stream and answering - /// `answers` streams, holding every claim back from them since none is confirmed - /// served. + /// A relay hearing the origin's `claims` claims on one session and answering + /// `answers` sessions. pub fn held(claims: usize, answers: usize) -> Self { Self::new(claims, 1, answers) } - /// A relay hearing the origin's `claims` claims on two streams, the second `lag` - /// one-claim batches behind the first. + /// A relay hearing the origin's `claims` claims on two sessions, the second `lag` + /// one-claim changes behind the first. pub fn lagging(claims: usize, lag: usize) -> Self { let mut relay = Self::new(claims, 2, 1); for _ in 0..lag { @@ -744,29 +802,34 @@ impl RouteRelay { relay } - fn path(i: usize) -> Path { - Path::new(&format!("live/{i}")).unwrap() - } - - fn claim(instance: &crate::Instance, cost: u64) -> crate::route::node::Claim { - crate::route::node::Claim { - instance: instance.clone(), - epoch: 0, - cost, - upstream: false, - learned: false, - above: 0, - chain: crate::Hops::new(), - } + /// `stream` hears the origin change the claims `changes` names, up to `rev`. + fn hear( + stream: &crate::route::node::Stream, + instance: &crate::Instance, + changes: Vec<(usize, crate::route::node::Claim)>, + rev: u64, + ) { + let changes = (changes.into_iter()) + .map(|(i, claim)| { + let path = Path::new(&format!("live/{i}")).unwrap(); + ((path, instance.clone()), crate::route::relay::Change::Live(claim)) + }) + .collect(); + let claims = crate::route::node::Msg::Claims { + origin: route_id(Self::ORIGIN), + changes, + floor: rev, + }; + stream.recv(claims).unwrap(); + stream.flush(); } - /// Hear one batch updating the first `changes` claims, returning how many outputs - /// the relay queued: what it serves into its origin, and what it forwards. + /// Hear the first `changes` claims change at once, returning how many outputs the + /// relay queued: what it serves into its origin, and what it tells its sessions. pub fn change(&mut self, changes: usize) -> usize { self.rev += 1; - let claim = Self::claim(&self.instance, self.rev); - let batch = (0..changes).map(|i| (Self::path(i), Some(claim.clone()))).collect(); - self.receive[0].batch(Self::ORIGIN, Path::empty(), batch, Some(self.rev)); + let changes = (0..changes).map(|i| (i, route_claim(0, self.rev))).collect(); + Self::hear(&self.receive[0], &self.instance, changes, self.rev); self.drain() } @@ -779,518 +842,130 @@ impl RouteRelay { /// The first claim changes to `epoch`, and the relay confirms serving it. fn confirm(&mut self, epoch: u64) -> usize { self.rev += 1; - let claim = crate::route::node::Claim { - epoch, - ..Self::claim(&self.instance, 0) - }; - let batch = vec![(Self::path(0), Some(claim))]; - self.receive[0].batch(Self::ORIGIN, Path::empty(), batch, Some(self.rev)); - let serves: Vec<_> = std::iter::from_fn(|| self.receive[0].try_output()).collect(); + Self::hear( + &self.receive[0], + &self.instance, + vec![(0, route_claim(epoch, 0))], + self.rev, + ); + let serves: Vec<_> = std::iter::from_fn(|| self.receive[0].try_serve()).collect(); for serve in &serves { if let crate::route::node::Output::Serve { - id, - claim, - prefix, - served, - .. + origin, path, instance, .. } = serve { - self.receive[0].serving(*id, claim, prefix, &served.claim); + self.receive[0].serving(*origin, &(path.clone(), instance.clone()), true); } } serves.len() + self.drain() } - /// The first stream hears the origin's next revision, which changes one claim. + /// The first session hears the origin's next revision, which changes one claim. fn advance(&mut self) { self.rev += 1; let i = self.rev as usize % self.claims; - let batch = vec![(Self::path(i), Some(Self::claim(&self.instance, self.rev)))]; - self.receive[0].batch(Self::ORIGIN, Path::empty(), batch, Some(self.rev)); + let changes = vec![(i, route_claim(0, self.rev))]; + Self::hear(&self.receive[0], &self.instance, changes, self.rev); self.behind.push_back((self.rev, i)); } - /// Each stream hears its next one-claim batch, the second still lagging, returning + /// Each session hears its next one-claim change, the second still lagging, returning /// how many outputs the relay queued. pub fn step(&mut self) -> usize { self.advance(); - let (rev, i) = self.behind.pop_front().expect("the second stream lags"); - let batch = vec![(Self::path(i), Some(Self::claim(&self.instance, rev)))]; - self.receive[1].batch(Self::ORIGIN, Path::empty(), batch, Some(rev)); + let (rev, i) = self.behind.pop_front().expect("the second session lags"); + Self::hear(&self.receive[1], &self.instance, vec![(i, route_claim(0, rev))], rev); self.drain() } fn drain(&self) -> usize { - (self.receive.iter().chain(&self.answer)) - .map(|stream| std::iter::from_fn(|| stream.try_output()).count()) - .sum() + route_drain(self.receive.iter().chain(&self.answer)) } } -/// A lite-07 route node following one origin on a stream per prefix, as a viewer -/// session holding many announce prefixes does, for the routes bench. +/// A lite-07 route node asking one peer for many prefixes, as a viewer session holding +/// many announce prefixes does, for the routes bench. pub struct RouteFollower { + #[allow(dead_code, reason = "held so the stream keeps a node to talk to")] node: crate::route::Node, - /// Each prefix's stream, `None` only while [`Self::refollow`] replaces it. - streams: Vec>, + stream: crate::route::node::Stream, instance: crate::Instance, + prefixes: usize, claims: usize, - /// The next stream [`Self::refollow`] replaces. + /// The next prefix [`Self::refollow`] replaces. next: usize, } impl RouteFollower { - /// The origin's identity and revision as the node hears them. - const ORIGIN: u64 = 1; - const REV: u64 = 1; - /// The viewer session every stream belongs to. - const TAG: u64 = 1; - - /// A node following `prefixes` prefixes `live/{k}`, each holding `claims` claims. + /// A node asking for `prefixes` prefixes `live/{k}`, each holding `claims` claims. pub fn new(prefixes: usize, claims: usize) -> Self { - let mut follower = Self { - node: crate::route::Node::new(2, 2, route_clock()), - streams: Vec::new(), + let node = crate::route::Node::new(route_id(2), route_clock()); + let stream = node.connect(1, route_leaf()).unwrap(); + let follower = Self { + node, + stream, instance: crate::Instance::random(), + prefixes, claims, next: 0, }; - follower.streams = (0..prefixes).map(|k| Some(follower.follow(k))).collect(); + for k in 0..prefixes { + follower.follow(k); + } follower.drain(); follower } - /// Open the session for prefix `k`, which hears the origin's route and snapshot. - fn follow(&self, k: usize) -> crate::route::node::Stream { - let prefix = Path::new(&format!("live/{k}")).unwrap(); - let peer = route_peer(Self::TAG + k as u64, Self::ORIGIN); - let link = crate::route::Link { - interest: [prefix.clone()].into(), - ..Default::default() - }; - let stream = self.node.connect(peer, link).unwrap(); - // The peer answered what the node asks it for. - stream.edited(Default::default()); - let reach = crate::route::path::Reach::Finite(route_offer(Self::ORIGIN)); - stream.route(Self::ORIGIN, prefix.clone(), Some(reach)); - let claim = crate::route::node::Claim { - instance: self.instance.clone(), - epoch: 0, - cost: 0, - upstream: false, - learned: false, - above: 0, - chain: crate::Hops::new(), + fn prefix(k: usize) -> Path { + Path::new(&format!("live/{k}")).unwrap() + } + + /// Ask for prefix `k`, which the peer answers with its initial set. + fn follow(&self, k: usize) { + let prefix = Self::prefix(k); + let edit = crate::route::relay::Edit { + remove: Vec::new(), + add: vec![prefix.clone()], }; - let snapshot = (0..self.claims) - .map(|j| (Path::new(&format!("live/{k}/{j}")).unwrap(), Some(claim.clone()))) + self.stream.ask(edit).unwrap(); + self.stream.recv(crate::route::node::Msg::Edited).unwrap(); + let changes = (0..self.claims) + .map(|j| { + let path = Path::new(&format!("live/{k}/{j}")).unwrap(); + let live = crate::route::relay::Change::Live(route_claim(0, 0)); + ((path, self.instance.clone()), live) + }) .collect(); - stream.batch(Self::ORIGIN, prefix, snapshot, Some(Self::REV)); - stream + let announce = crate::route::node::Msg::Announce { changes }; + self.stream.recv(announce).unwrap(); + self.stream.recv(crate::route::node::Msg::Synced(prefix)).unwrap(); + self.stream.flush(); } - /// Close one prefix's session and open it again, returning how many outputs the + /// Stop asking for one prefix and ask for it again, returning how many outputs the /// node queued. pub fn refollow(&mut self) -> usize { - let k = self.next % self.streams.len(); + let k = self.next % self.prefixes; self.next += 1; - // Closed first, so the node lets go of the prefix before hearing it again. - drop(self.streams[k].take()); - self.streams[k] = Some(self.follow(k)); + let edit = crate::route::relay::Edit { + remove: vec![Self::prefix(k)], + add: Vec::new(), + }; + self.stream.ask(edit).unwrap(); + // Answered first, so the node lets go of the prefix before hearing it again. + self.stream.recv(crate::route::node::Msg::Edited).unwrap(); + self.stream.flush(); + self.follow(k); self.drain() } - /// Close every session. + /// Close the session. pub fn teardown(self) { - drop(self.streams); + drop(self.stream); } fn drain(&self) -> usize { - (self.streams.iter().flatten()) - .map(|stream| std::iter::from_fn(|| stream.try_output()).count()) - .sum() - } -} - -/// A peer's request for `prefix` alone. -fn route_ask(prefix: Path) -> crate::route::path::Edit { - crate::route::path::Edit { - remove: Vec::new(), - add: vec![prefix], - } -} - -/// The path router originating claims and answering streams, for the routes bench. -pub struct PathRouteNode(crate::route::path::Router); - -impl PathRouteNode { - /// An origin with `claims` claims, answering the given interests. - pub fn new(claims: usize, interests: &[&str]) -> Self { - let mut node = Self(crate::route::path::Router::new(1, 1, Default::default())); - node.0.originate(1); - for i in 0..claims { - node.own(&format!("live/{i}"), true); - } - for (peer, prefix) in interests.iter().enumerate() { - node.0.connect(peer, peer as u64 + 2, Default::default()).unwrap(); - let add = vec![Path::new(prefix).unwrap().to_owned()]; - node.0 - .edit( - peer, - crate::route::path::Edit { - remove: Vec::new(), - add, - }, - ) - .unwrap(); - } - node.drain(); - node - } - - /// Start or withdraw a claim. - pub fn own(&mut self, claim: &str, start: bool) { - let claim = Path::new(claim).unwrap(); - if start { - self.0.announce(claim, ()).unwrap(); - } else { - self.0.unannounce(claim).unwrap(); - } - } - - /// Consume messages and reader notifications, returning the messages sent. - pub fn drain(&mut self) -> usize { - let sent = self.0.drain().len(); - self.0.events(); - self.0.changed(); - sent - } -} - -/// A path router receiving one publisher and forwarding its claims to a reader. -pub struct PathRouteRelay { - router: crate::route::path::Router, - revision: u64, -} - -impl PathRouteRelay { - /// Hear `claims` claims and answer one stream watching the root. - pub fn new(claims: usize) -> Self { - use crate::route::path::{Hop, Offer, Reach}; - let mut relay = Self { - router: crate::route::path::Router::new(2, 2, Default::default()), - revision: 1, - }; - relay.router.connect(0, 1, Default::default()).unwrap(); - relay.router.edited(0); - relay.router.route( - 0, - 1, - Path::empty(), - Some(Reach::Finite(Offer { - path: [Hop { node: 1, session: 0 }].into(), - draining: false, - priority: i8::MAX, - metric: 0, - down_only: false, - })), - ); - let snapshot = (0..claims) - .map(|i| (Path::new(&format!("live/{i}")).unwrap(), Some(1))) - .collect(); - relay.router.batch(0, 1, Path::empty(), snapshot, Some(1)); - relay.router.connect(1, 3, Default::default()).unwrap(); - let add = vec![Path::empty()]; - relay - .router - .edit( - 1, - crate::route::path::Edit { - remove: Vec::new(), - add, - }, - ) - .unwrap(); - relay.drain(); - relay - } - - /// Receive one batch and return its forwarded messages and reader changes. - pub fn change(&mut self, claims: usize) -> (usize, usize) { - self.revision += 1; - let changes = (0..claims) - .map(|i| (Path::new(&format!("live/{i}")).unwrap(), Some(self.revision))) - .collect(); - self.router.batch(0, 1, Path::empty(), changes, Some(self.revision)); - self.drain() - } - - fn drain(&mut self) -> (usize, usize) { - let sent = self.router.drain().len(); - let events = self.router.events().len(); - self.router.changed(); - (sent, events) - } -} - -/// The path router following one publisher on a session per prefix, for the routes bench. -pub struct PathRouteFollower { - router: crate::route::path::Router, - prefixes: Vec, - claims: usize, - next: usize, - now: kio::clock::Instant, -} - -impl PathRouteFollower { - /// A route for each `live/{k}`, each carrying `claims` claims. - pub fn new(prefixes: usize, claims: usize) -> Self { - let mut follower = Self { - router: crate::route::path::Router::new(2, 2, crate::route::path::Doubt::default()), - prefixes: (0..prefixes) - .map(|k| Path::new(&format!("live/{k}")).unwrap()) - .collect(), - claims, - next: 0, - now: kio::clock::Instant::now(), - }; - for k in 0..prefixes { - follower.follow(k); - } - follower.drain(); - assert_eq!(follower.router.shown().len(), prefixes * claims); - follower - } - - fn follow(&mut self, k: usize) { - use crate::route::path::{Hop, Offer, Reach}; - let prefix = self.prefixes[k].clone(); - self.router.connect(k, 1, crate::route::Link::default()).unwrap(); - self.router.edited(k); - self.router.route( - k, - 1, - prefix.clone(), - Some(Reach::Finite(Offer { - path: [Hop { node: 1, session: 0 }].into(), - draining: false, - priority: i8::MAX, - metric: 0, - down_only: false, - })), - ); - let changes = (0..self.claims) - .map(|j| (Path::new(&format!("live/{k}/{j}")).unwrap(), Some(()))) - .collect(); - self.router.batch(k, 1, prefix, changes, Some(1)); - } - - /// Close every session in one call, including the resulting timer work. - pub fn teardown(mut self) { - self.router.disconnect(0..self.prefixes.len(), self.now); - self.expire(); - assert!(self.router.shown().is_empty()); - self.drain(); - } - - /// Replace one prefix's session and snapshot, including the resulting timer work. - pub fn refollow(&mut self) { - let k = self.next % self.prefixes.len(); - self.next += 1; - self.router.disconnect([k], self.now); - self.follow(k); - self.expire(); - assert_eq!(self.router.shown().len(), self.prefixes.len() * self.claims); - self.drain(); - } - - fn expire(&mut self) { - // Advance the mocked input clock rather than waiting a real doubt interval. - self.now = self.now.saturating_add(crate::route::path::Doubt::default().timer); - self.router.timeout(self.now); - } - - fn drain(&mut self) { - self.router.drain(); - self.router.events(); - self.router.changed(); - } -} - -/// A path router hearing one publisher through `sessions` sessions of a node that -/// then sends GOAWAY, a route per session, and answering `recipients` streams that -/// watch the root, for the routes bench. -pub struct PathRouteDrain { - router: crate::route::path::Router, - recipients: usize, -} - -impl PathRouteDrain { - const LEAVING: u64 = 500; - - /// Hear a route over each of `sessions` sessions of the leaving node, and answer - /// `recipients` streams watching the root. - pub fn new(sessions: usize, recipients: usize) -> Self { - use crate::route::path::{Hop, Offer, Reach}; - let mut router = crate::route::path::Router::new(2, 2, crate::route::path::Doubt::default()); - for i in 0..sessions { - let prefix = Path::new(&format!("live/{i}")).unwrap(); - let via = 1_000 + i as u64; - router.connect(i, via, crate::route::Link::default()).unwrap(); - router.edited(i); - let path = [ - Hop { node: 1, session: 0 }, - Hop { - node: Self::LEAVING, - session: i as u64 + 1, - }, - Hop { node: via, session: 1 }, - ]; - router.route( - i, - 1, - prefix.clone(), - Some(Reach::Finite(Offer { - path: path.into(), - draining: false, - priority: i8::MAX, - metric: 1, - down_only: false, - })), - ); - let claim = Path::new(&format!("live/{i}/x")).unwrap(); - router.batch(i, 1, prefix, vec![(claim, Some(()))], Some(1)); - } - for r in 0..recipients { - let peer = sessions + r; - router - .connect(peer, 5_000 + r as u64, crate::route::Link::default()) - .unwrap(); - let add = vec![Path::empty()]; - router - .edit( - peer, - crate::route::path::Edit { - remove: Vec::new(), - add, - }, - ) - .unwrap(); - } - let mut node = Self { router, recipients }; - node.flush(); - node - } - - /// Hear the leaving node drain, returning the messages sent: each recipient's - /// DRAIN, then each route it was sent, now ranked draining. - pub fn drain(&mut self) -> usize { - use crate::route::path::{Dead, Out}; - let now = kio::clock::Instant::now(); - self.router.dead(0, Dead::Draining { node: Self::LEAVING }, now); - let out = self.router.drain(); - let told = (out.iter()) - .filter(|out| { - matches!( - out, - Out::Dead { - dead: Dead::Draining { .. }, - .. - } - ) - }) - .count(); - assert_eq!(told, self.recipients, "each recipient hears the drain once"); - self.router.events(); - self.router.changed(); - out.len() - } - - fn flush(&mut self) -> usize { - let sent = self.router.drain().len(); - self.router.events(); - self.router.changed(); - sent - } -} - -/// A path router hearing one publisher from a neighbour, under a prefix of its own with -/// `claims` claims, and answering `streams` streams that each watch a prefix it does not -/// claim under, for the routes bench. -pub struct PathRouteChange { - router: crate::route::path::Router, - far: u64, -} - -impl PathRouteChange { - const UP: u64 = 1_000; - - fn reach(id: u64, far: u64) -> crate::route::path::Reach { - use crate::route::path::{Hop, Offer, Reach}; - let path = [ - Hop { node: id, session: 0 }, - Hop { node: far, session: 1 }, - Hop { - node: Self::UP, - session: 1, - }, - ]; - Reach::Finite(Offer { - path: path.into(), - draining: false, - priority: i8::MAX, - metric: 1, - down_only: false, - }) - } - - /// Hear one publisher with `claims` claims, and answer `streams` streams its route - /// misses. - pub fn new(claims: usize, streams: usize) -> Self { - let mut router = crate::route::path::Router::new(2, 2, crate::route::path::Doubt::default()); - router.connect(0, Self::UP, crate::route::Link::default()).unwrap(); - router.edited(0); - let prefix = Path::new("o0").unwrap(); - router.route(0, 1, prefix.clone(), Some(Self::reach(1, 500))); - let changes = (0..claims) - .map(|c| (Path::new(&format!("o0/{c}")).unwrap(), Some(()))) - .collect(); - router.batch(0, 1, prefix, changes, Some(1)); - for s in 0..streams { - let peer = 1 + s; - router - .connect(peer, 5_000 + s as u64, crate::route::Link::default()) - .unwrap(); - let add = vec![Path::new(&format!("x{s}")).unwrap().to_owned()]; - router - .edit( - peer, - crate::route::path::Edit { - remove: Vec::new(), - add, - }, - ) - .unwrap(); - } - let mut node = Self { router, far: 500 }; - node.flush(); - node - } - - /// The neighbour moves the publisher's route onto another path, which no stream - /// watches. - pub fn repath(&mut self) { - self.far = if self.far == 500 { 501 } else { 500 }; - self.router - .route(0, 1, Path::new("o0").unwrap(), Some(Self::reach(1, self.far))); - assert_eq!(self.flush(), 0); - } - - fn flush(&mut self) -> usize { - let sent = self.router.drain().len(); - self.router.events(); - self.router.changed(); - sent + route_drain([&self.stream]) } } @@ -1397,8 +1072,14 @@ pub fn decode_announces(data: &[u8], compress: bool) -> Vec { .start(Some(suffix)) .and_then(|suffix| suffix.ok_or(crate::Error::ProtocolViolation)) .map(|suffix| Announced::Start(suffix, hops.into_ids())), - // A refused message assigns ids this harness does not model. - lite::AnnounceBroadcast::Refused { .. } => break, + lite::AnnounceBroadcast::Start { suffix, claim, .. } => decoder + .start(Some(suffix)) + .and_then(|suffix| suffix.ok_or(crate::Error::ProtocolViolation)) + .map(|suffix| Announced::Start(suffix, claim.chain)), + lite::AnnounceBroadcast::Change { id, claim } => { + decoder.get(id).map(|_| Announced::Update(id, claim.chain)) + } + lite::AnnounceBroadcast::End { id, .. } => decoder.end(id).map(|_| Announced::End(id)), lite::AnnounceBroadcast::Update { id, hops, .. } => { decoder.get(id).map(|_| Announced::Update(id, hops.into_ids())) } @@ -1505,8 +1186,7 @@ impl LiteSample { Self::Subscribe => lite::Subscribe { order: crate::track::Order::Descending, instance: None, - node: 0, - depth: 0, + node: None, id: 3, broadcast: Path::from_static("room/alice"), track: "video".into(), @@ -1705,8 +1385,7 @@ impl Default for Messages { lite_subscribe: lite::Subscribe { order: crate::track::Order::Descending, instance: None, - node: 0, - depth: 0, + node: None, id: 7, broadcast: Path::from_static("room/alice"), track: "video".into(), @@ -1889,8 +1568,7 @@ pub fn encode_subscribe(broadcast: &Path, track: &str, ietf: bool, out: &mut Vec id: 0, broadcast: broadcast.clone(), instance: None, - node: 0, - depth: 0, + node: None, track: track.into(), priority: 0, max_delay: Some(std::time::Duration::ZERO), @@ -2137,25 +1815,22 @@ pub fn pattern(data: &[u8]) -> bool { } /// Lite seeds whose envelope bytes the uniform sweep never forms, on the newest -/// version: a typed empty TRACKS_SYNCED, an AUTH_OK reply, every route message, -/// both kinds of DEAD, and an ANNOUNCE_REQUEST and its ANNOUNCE_OK (the sweep sets -/// ROUTE_START's type byte but fills its size byte with the body pattern, so none -/// decodes whole), and a DATAGRAMS request, whose eight fields outgrow the sweep's -/// longest body. +/// version: a typed empty TRACKS_SYNCED, an AUTH_OK reply, every route message, and +/// an ANNOUNCE_REQUEST and its ANNOUNCE_OK (the sweep sets ROUTE's type byte but +/// fills its size byte with the body pattern, so none decodes whole), and a DATAGRAMS +/// request, whose seven fields outgrow the sweep's longest body. const TYPED_LITE_SEEDS: &[(u8, &[u8])] = &[ (23, &[4, 0]), - (30, &[8, 0, 0, 0, 0, 0, 0, 0, 0]), + (30, &[7, 0, 0, 0, 0, 0, 0, 0]), (27, &[0, 3, 0, 0, 0]), - (5, &[6, 9, 1, 0, 0, 1, 1, 0, 0, 0x80, 1]), - (5, &[7, 7, 0, 1, 1, 0, 0, 0x80, 1]), + // ROUTE, ROUTE_END, DEAD, DRAIN, ANNOUNCE_FLOOR, ANNOUNCE_REQUEST, ANNOUNCE_OK. + (5, &[7, 7, 1, 7, 1, 0, 0, 0x80, 1]), (5, &[8, 1, 0]), - (5, &[9, 2, 0, 1]), - (5, &[11, 1, 0]), - (5, &[15, 6, 0, 1, 1, 2, 0, 0]), - (5, &[15, 6, 0, 1, 1, 2, 1, 2]), - (5, &[15, 2, 1, 1]), - (5, &[16, 4, 0, 1, 0, 0]), - (5, &[17, 0]), + (5, &[9, 5, 7, 1, 2, 9, 1]), + (5, &[10, 2, 7, 1]), + (5, &[3, 2, 0, 1]), + (5, &[5, 4, 0, 1, 0, 0]), + (5, &[6, 0]), ]; /// The inputs the fuzzer starts from: every (version, type) pair the dispatch knows, diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index 18b8d9b14a3..3b4a02f5b24 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -1,12 +1,14 @@ -use std::sync::Arc; - use num_enum::{IntoPrimitive, TryFromPrimitive}; use crate::{ Hop, Hops, Instance, Path, coding::*, origin::Cost, - route::{self, path::Offer}, + route::{ + self, + node::{Attr, Claim}, + relay::{Hop as RouteHop, NodeId, Offer}, + }, }; use super::{ @@ -20,27 +22,17 @@ use super::{ const ANNOUNCE_START: u64 = 0; const ANNOUNCE_END: u64 = 1; const ANNOUNCE_UPDATE: u64 = 2; -// lite-07: the advertisement serves another instance, or a newer epoch of its own. -const ANNOUNCE_RESTART: u64 = 3; +// lite-07: one claims message per change on a routing neighbour's stream is closed by a floor. +const ANNOUNCE_FLOOR: u64 = 3; const SYNCED: u64 = 4; -// lite-07: the route layer. 10 was ROUTE_REQUEST, which the path rule retired. -const ROUTE_START: u64 = 6; -const ROUTE_UPDATE: u64 = 7; -const ROUTE_END: u64 = 8; -const ANNOUNCE_FLOOR: u64 = 9; -const ROUTE_HOLD: u64 = 11; -// 12 to 14 were WARM_START, WARM_UPDATE, and WARM_END, which return in a later wip version -// with an implementation that picks a source per broadcast. -// lite-07: news of a closed session or a draining node on the routes the sender offered. -const DEAD: u64 = 15; // lite-07: an edit of the prefixes the sender wants, and the marker answering one. -const ANNOUNCE_REQUEST: u64 = 16; -const ANNOUNCE_OK: u64 = 17; - -/// DEAD kind: a session on the routes' paths closed. -const DEAD_CLOSED: u64 = 0; -/// DEAD kind: a node on the routes' paths sent GOAWAY. -const DEAD_DRAIN: u64 = 1; +const ANNOUNCE_REQUEST: u64 = 5; +const ANNOUNCE_OK: u64 = 6; +// lite-07: the routes between forwarding nodes. +const ROUTE: u64 = 7; +const ROUTE_END: u64 = 8; +const DEAD: u64 = 9; +const DRAIN: u64 = 10; /// Whether the negotiated version can update a live advertisement's metadata. On lite-05 an /// update travels as a duplicate ANNOUNCE (a second `active` for an already-announced path); on @@ -58,66 +50,43 @@ pub fn update_supported(version: Version) -> bool { /// A message on the Announce Stream, advertising or retracting a broadcast. /// /// Lite-07 carries everything one side says about routing on its one unidirectional -/// stream: the edits of the prefixes it wants (`Request`), and the markers (`Ok`), -/// routes, and claims answering the prefixes its peer wants. +/// stream: the edits of the prefixes it wants (`Request`), and the markers (`Ok`, +/// `Synced`), routes, and claims answering the prefixes its peer wants. /// -/// On lite-06+ these are independently-typed messages (`ANNOUNCE_START`, -/// `ANNOUNCE_END`, `ANNOUNCE_UPDATE`, and on lite-07 `ANNOUNCE_RESTART`), each -/// framed as `Type | Length | Body` like the subscribe stream's responses. Each -/// `Active` (ANNOUNCE_START) implicitly assigns the next announce id (a -/// per-stream ordinal starting at 0); the others reference that id instead of -/// repeating the path. Older versions send a single `ANNOUNCE_BROADCAST` -/// message that retracts by path (`Ended`). +/// On lite-06+ these are independently-typed messages, each framed as +/// `Type | Length | Body` like the subscribe stream's responses. Each ANNOUNCE_START +/// implicitly assigns the next announce id (a per-stream ordinal starting at 0); the +/// others reference that id instead of repeating the path. Older versions send a single +/// `ANNOUNCE_BROADCAST` message that retracts by path (`Ended`). /// /// The path is as it appears on the wire: on lite-07 it may name a base announcement, /// resolved against the stream's history by [`AnnounceDecoder`](super::AnnounceDecoder). -/// -/// Lite-07 names the route each claim travels under in place of a hop chain, and `route` -/// must be 0 on every earlier version. There `hops` is the Lite-06 Chain instead: the -/// chain of a claim learned over moq-lite-06, empty for every other claim, and sent only -/// to a peer that offered the Lite-06 Chain Setup Parameter. #[derive(Clone, Debug, PartialEq, Eq)] pub enum AnnounceBroadcast { /// ANNOUNCE_START (lite-06) / active (older): a broadcast is now available. - /// Carries the path suffix, (lite-07+) the Route ID and the instance and epoch it - /// serves, (before lite-07) the hop chain, and (lite-06+) the cost, and assigns the - /// next announce id. The instance and epoch change only with a `Restart`. On lite-07, - /// `above` is how many segments the claim's own prefix lacks of the one its suffix names, - /// 0 for a claim exactly there; it is 0 on every earlier version. - Active { - suffix: PathRef, - route: u64, - instance: Option, - epoch: u64, - hops: Hops, - cost: Cost, - above: u64, - }, + /// Carries the path suffix, the hop chain, and (lite-06) the cost, and assigns the + /// next announce id. + Active { suffix: PathRef, hops: Hops, cost: Cost }, /// Pre-lite-06: a broadcast is no longer available, retracted by path. Ended { suffix: Path, hops: Hops }, - /// ANNOUNCE_END (lite-06+): a broadcast is no longer available, retracted by + /// ANNOUNCE_END (lite-06): a broadcast is no longer available, retracted by /// announce id. The id is retired; referencing it again is a protocol violation. EndedId { id: u64 }, - /// ANNOUNCE_UPDATE (lite-06+): atomically replace the metadata of the announcement - /// with this id: its cost, and before lite-07 its hop chain. The id stays live. - Update { - id: u64, - hops: Hops, - cost: Cost, - above: u64, - }, - /// ANNOUNCE_RESTART (lite-07+): the announcement with this id now serves the - /// instance and epoch given. Another instance is another stream, so whatever the - /// receiver resolved under its prefix is stale; a higher epoch of the same one - /// continues it. The id stays live. - Restart { - id: u64, - instance: Option, - epoch: u64, - cost: Cost, - hops: Hops, - above: u64, + /// ANNOUNCE_UPDATE (lite-06): atomically replace the hop chain and cost of the + /// announcement with this id. The id stays live. + Update { id: u64, hops: Hops, cost: Cost }, + /// ANNOUNCE_START (lite-07): a claim of the broadcast at `suffix` serving + /// `instance`, which assigns it the next announce id. + Start { + suffix: PathRef, + instance: Instance, + claim: Claim, }, + /// ANNOUNCE_UPDATE (lite-07): the claim with this id now stands as `claim`. + Change { id: u64, claim: Claim }, + /// ANNOUNCE_END (lite-07): the claim with this id is gone, and the id retired. Its + /// publisher withdrew it unless `lost`, when the sender only lost its way to it. + End { id: u64, lost: bool }, /// An unknown lite-06+ announce type. The length-prefixed body was skipped so /// the stream stays up; it does not assign an announce id. Skipped, @@ -134,289 +103,164 @@ pub enum AnnounceBroadcast { remove: Vec, add: Vec<(Path, bool)>, }, - /// ANNOUNCE_OK (lite-07+): the receiver's last edit takes effect here. + /// ANNOUNCE_OK (lite-07+): the receiver's oldest unanswered edit takes effect here. Ok, - /// ROUTE_START (lite-07+): the sender has a route to the publisher `node` covering - /// the prefix the receiver assigned the Prefix ID `prefix` joined with `suffix`, and - /// assigns it the next Route ID. `exact` marks a route the sender keeps at its own - /// prefix whatever prefix the request lies at, so an edit widening the request past - /// it leaves it there. - RouteStart { - node: route::Id, - prefix: u64, - suffix: Path, - exact: bool, - offer: Offer, - }, - /// ROUTE_UPDATE (lite-07+): the route with this id changed, and is usable. - RouteUpdate { id: u64, offer: Offer }, - /// ROUTE_HOLD (lite-07+): the sender has no usable route with this id, but still - /// holds its advertisements while it recovers. - RouteHold { id: u64 }, + /// ROUTE (lite-07+): the sender's route to the forwarding node its path begins + /// with, replacing the one it sent before, or else assigned the next Route ID. + Route { offer: Offer }, /// ROUTE_END (lite-07+): the sender let go of the route with this id, and of every - /// advertisement under it. + /// claim under it. RouteEnd { id: u64 }, - /// DEAD (lite-07+): a session or node on the routes the sender offered is gone or - /// going. - Dead(Dead), - /// ANNOUNCE_FLOOR (lite-07+): closes the batch of advertisements under the route - /// with this id, certifying them across the whole requested prefix at the origin's - /// revision, or certifying nothing (`None`). - Floor { id: u64, revision: Option }, - /// A route message (lite-07+) whose content, which the sender only forwarded, this - /// node refuses. The receiver withdraws what it names and keeps the session. Decoded - /// only as far as keeps the stream's ids in step; never sent. - Refused { message: Refusable, reason: Refusal }, -} - -/// What a refused route message still tells the receiver, so the ids that follow it -/// resolve. -#[derive(Clone, Debug, PartialEq, Eq)] -pub(crate) enum Refusable { - /// ROUTE_START: assigns the next Route ID to the publisher `node`, covering the - /// prefix with the Prefix ID `prefix` joined with `suffix`, or no prefix when the - /// suffix itself was refused, along `path`, at its own prefix when `exact`. - RouteStart { - node: route::Id, - prefix: u64, - suffix: Option, - exact: bool, - path: Arc<[route::path::Hop]>, - }, - /// ROUTE_UPDATE of the route with this Route ID, now along `path`. - RouteUpdate { id: u64, path: Arc<[route::path::Hop]> }, - /// ANNOUNCE_START under the route with Route ID `route`: assigns the next Announce - /// ID, to `suffix`, or to no path when the path itself was refused. - Start { route: u64, suffix: Option }, - /// ANNOUNCE_UPDATE or ANNOUNCE_RESTART of the claim with this Announce ID. - Change { id: u64 }, -} + /// DEAD (lite-07+): the session `hop` names closed, at the node `far` at its other + /// end, which ends every route the sender offered through it. + Dead { hop: RouteHop, far: NodeId }, + /// DRAIN (lite-07+): `node` sent GOAWAY, so every route through it ranks last. + Drain { node: NodeId }, + /// ANNOUNCE_FLOOR (lite-07+): closes the batch of claim messages since the last + /// one, which change the claims of the node the route with this id leads to, and + /// are complete as of that node's `revision`. + Floor { id: u64, revision: route::Rev }, +} + +/// Route flag: a marked link is on the path, so it is never sent over another. +const MARKED: u8 = 0x1; +/// Route and claim flag: a node on the way sent GOAWAY. +const DRAINING: u8 = 0x2; +/// Claim flag: no route reaches the claim from the node that told it. +const UNAVAILABLE: u8 = 0x1; -/// Why a node refuses content a peer forwarded: well framed, but nothing it can use. -#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)] -pub(crate) enum Refusal { - #[error("the reserved node")] - Node, - #[error("unknown flags {0:#04x}")] - Flags(u8), - #[error("{0} hops, past the limit")] - Hops(u64), - #[error("an invalid path")] - Path, - #[error("an invalid instance")] - Instance, - #[error("an invalid lite-06 chain")] - Chain, +fn encode_node(w: &mut Encoder<'_>, node: NodeId) -> Result<(), EncodeError> { + // No node names itself 0. + if node.relay == 0 { + return Err(EncodeError::InvalidState); + } + w.varint(node.relay)?; + w.varint(node.start) } -/// Content a peer forwarded: `Ok(Err(..))` when it is well framed but refused. -type Content = Result, DecodeError>; - -/// Refuse the content at `r`, skipping the rest of its message's body: the refused field -/// is always the body's last, or leaves what follows unreadable. -fn refuse(r: &mut Decoder<'_>, reason: Refusal) -> Content { - r.rest(); - Ok(Err(reason)) +fn decode_node(r: &mut Decoder<'_>) -> Result { + let relay = match r.varint()? { + 0 => return Err(DecodeError::InvalidValue), + relay => relay, + }; + let start = r.varint()?; + Ok(NodeId { relay, start }) } -/// Route Offer flag: an upstream link is on the path, so the route is down-only. -const DOWN_ONLY: u8 = 0x1; -/// Route Offer flag: a node on the path sent GOAWAY. -const DRAINING: u8 = 0x2; - -/// News on DEAD about the routes the sender offered. -#[derive(Clone, Debug, PartialEq, Eq)] -pub(crate) enum Dead { - /// CLOSED: the session `hop` names closed, at the node `far` at its other end, which - /// the receiver doubts. The next `moved` messages on the stream are ROUTE_UPDATEs, - /// one per route on the stream through that hop that continues on another path, and - /// the receiver applies the DEAD and all of them as one. The rest end if `gone`, and - /// are held if not, unless the receiver is the node just before the sender on the - /// route's path. - Closed { - hop: route::path::Hop, - far: route::Id, - gone: bool, - moved: u64, - }, - /// DRAIN: `node` sent GOAWAY, so every path through it ranks as draining. - Drain { node: route::Id }, +fn encode_hop(w: &mut Encoder<'_>, hop: RouteHop) -> Result<(), EncodeError> { + encode_node(w, hop.node)?; + w.varint(hop.session) } -/// A Route Offer off the wire: usable, or refused with the path it still names. -pub(crate) type Heard = Result; - -/// A Route Offer this node refuses: the path it names, which a later DEAD may match, and -/// why. The offer is the route's, so refusing it refuses the route, not the session. -#[derive(Clone, Debug, PartialEq, Eq)] -pub(crate) struct Unusable { - pub path: Arc<[route::path::Hop]>, - pub reason: Refusal, +fn decode_hop(r: &mut Decoder<'_>) -> Result { + Ok(RouteHop { + node: decode_node(r)?, + session: r.varint()?, + }) } -/// Encode a Route Offer: the path, then flags, priority, and metric. No node offers an -/// empty path or one past the hop limit, nor names Node ID 0 in one. +/// Encode a route: the path, then flags, priority, and cost. No node offers an empty +/// path or one past the hop limit. fn encode_offer(w: &mut Encoder<'_>, offer: &Offer) -> Result<(), EncodeError> { - if offer.path.is_empty() || offer.path.len() > route::MAX_HOPS || offer.path.iter().any(|hop| hop.node == 0) { + if offer.path.is_empty() || offer.path.len() > route::MAX_HOPS { return Err(EncodeError::InvalidState); } w.varint(offer.path.len() as u64)?; for hop in offer.path.iter() { - w.varint(hop.node)?; - w.varint(hop.session)?; + encode_hop(w, *hop)?; } let mut flags = 0; - if offer.down_only { - flags |= DOWN_ONLY; + if offer.marked { + flags |= MARKED; } if offer.draining { flags |= DRAINING; } w.u8(flags); w.u8(super::priority::to_wire(offer.priority)); - w.varint(offer.metric)?; - Ok(()) + w.varint(offer.cost) } -/// Decode a Route Offer. Its path comes first, so a node refusing the rest still learns -/// the path a later DEAD may name. An empty path is the sender's own error, since it -/// names itself last. Hops past the limit, a hop naming Node ID 0, and a flag this node -/// does not know refuse the offer: a newer flag may change what the route means, or add -/// a field after the ones this node reads, so a refusal skips the rest of `r`. Every hop -/// a path counts is read, but of a path past the limit only those up to one past it are -/// kept: a sender within the limit never sends one, and the whole would hold a body's -/// worth for each route. -fn decode_offer(r: &mut Decoder<'_>) -> Result { +/// Decode a route. A sender within the limit never sends an empty path, one past the +/// hop limit, or a flag this version does not define, so each fails the stream. +fn decode_offer(r: &mut Decoder<'_>) -> Result { let count = r.varint()?; if count == 0 { return Err(DecodeError::InvalidValue); } - // Each hop takes at least two bytes, so the body bounds the count. - if count > (r.remaining() / 2) as u64 { - return Err(DecodeError::TooMany); - } - let mut path = Vec::with_capacity(count.min(route::MAX_HOPS as u64 + 1) as usize); - for index in 0..count { - let hop = route::path::Hop { - node: r.varint()?, - session: r.varint()?, - }; - if index <= route::MAX_HOPS as u64 { - path.push(hop); - } - } - let path: Arc<[route::path::Hop]> = path.into(); - let refuse = |r: &mut Decoder<'_>, reason| { - r.rest(); - Ok(Err(Unusable { - path: path.clone(), - reason, - })) - }; if count > route::MAX_HOPS as u64 { - return refuse(r, Refusal::Hops(count)); - } - if path.iter().any(|hop| hop.node == 0) { - return refuse(r, Refusal::Node); + return Err(DecodeError::TooMany); } + let path = (0..count).map(|_| decode_hop(r)).collect::, _>>()?; let flags = r.u8()?; - if flags & !(DOWN_ONLY | DRAINING) != 0 { - return refuse(r, Refusal::Flags(flags)); + if flags & !(MARKED | DRAINING) != 0 { + return Err(DecodeError::InvalidValue); } let priority = super::priority::from_wire(r.u8()?); - let metric = r.varint()?; - Ok(Ok(Offer { - path, + let cost = r.varint()?; + Ok(Offer { + path: path.into(), draining: flags & DRAINING != 0, priority, - metric, - down_only: flags & DOWN_ONLY != 0, - })) + cost, + marked: flags & MARKED != 0, + }) } -fn encode_dead(w: &mut Encoder<'_>, dead: &Dead) -> Result<(), EncodeError> { - match dead { - Dead::Closed { hop, far, gone, moved } => { - if hop.node == 0 || *far == 0 { - return Err(EncodeError::InvalidState); - } - w.varint(DEAD_CLOSED)?; - w.varint(hop.node)?; - w.varint(hop.session)?; - w.varint(*far)?; - w.u8(u8::from(*gone)); - w.varint(*moved)?; - } - Dead::Drain { node } => { - if *node == 0 { - return Err(EncodeError::InvalidState); - } - w.varint(DEAD_DRAIN)?; - w.varint(*node)?; - } +/// Encode what a claim says after its epoch: cost, above, flags, priority, and chain. +fn encode_claim(w: &mut Encoder<'_>, claim: &Claim) -> Result<(), EncodeError> { + if claim.chain.len() >= route::MAX_HOPS || claim.chain.contains(&0) { + return Err(EncodeError::InvalidState); + } + w.varint(claim.cost)?; + w.varint(claim.item.above)?; + let mut flags = 0; + if claim.unavailable { + flags |= UNAVAILABLE; + } + if claim.draining { + flags |= DRAINING; + } + w.u8(flags); + w.u8(super::priority::to_wire(claim.priority)); + w.varint(claim.chain.len() as u64)?; + for relay in &claim.chain { + w.varint(*relay)?; } Ok(()) } -fn decode_dead(r: &mut Decoder<'_>) -> Result { - let nonzero = |id: u64| match id { - 0 => Err(DecodeError::InvalidValue), - id => Ok(id), - }; - Ok(match r.varint()? { - DEAD_CLOSED => { - let hop = route::path::Hop { - node: nonzero(r.varint()?)?, - session: r.varint()?, - }; - let far = nonzero(r.varint()?)?; - let gone = match r.u8()? { - 0 => false, - 1 => true, - _ => return Err(DecodeError::InvalidValue), - }; - let moved = r.varint()?; - Dead::Closed { hop, far, gone, moved } - } - DEAD_DRAIN => Dead::Drain { - node: nonzero(r.varint()?)?, - }, - _ => return Err(DecodeError::InvalidValue), - }) -} - -/// Decode a path a peer forwarded, refusing one this node cannot hold. -fn decode_path(r: &mut Decoder<'_>) -> Content { - let bytes = r.bytes()?; - let path = std::str::from_utf8(bytes).ok().and_then(|path| Path::new(path).ok()); - Ok(path.filter(|path| path.depth() <= Path::MAX_PARTS).ok_or(Refusal::Path)) -} - -/// Decode a lite-07 suffix: its base, which the sender picked, then the path it forwarded. -fn decode_suffix(r: &mut Decoder<'_>) -> Content { - let base = r.varint()?; - let keep = r.varint()?; - if base == 0 && keep != 0 { +/// Decode a claim of `epoch`. A chain at the hop limit, or naming Node ID 0, and a +/// flag this version does not define fail the stream: no sender builds one. +fn decode_claim(r: &mut Decoder<'_>, epoch: u64) -> Result { + let cost = r.varint()?; + let above = r.varint()?; + let flags = r.u8()?; + if flags & !(UNAVAILABLE | DRAINING) != 0 { return Err(DecodeError::InvalidValue); } - Ok(decode_path(r)?.map(|rest| PathRef { base, keep, rest })) -} - -/// Encode an ANNOUNCE_FLOOR body: the revision plus one, or 0 to certify nothing. -fn encode_floor(w: &mut Encoder<'_>, id: u64, revision: Option) -> Result<(), EncodeError> { - w.varint(id)?; - match revision { - // No origin advertises the last revision, so it never needs the offset. - Some(route::MAX) => Err(EncodeError::InvalidState), - Some(rev) => w.varint(rev + 1), - None => w.varint(0), + let priority = super::priority::from_wire(r.u8()?); + let count = r.varint()?; + // A chain reaches the hop limit only with the Relay of a node that then does not take + // the claim, so none that long is sent. + if count >= route::MAX_HOPS as u64 { + return Err(DecodeError::TooMany); } -} - -fn decode_floor(r: &mut Decoder<'_>) -> Result { - let id = r.varint()?; - let revision = r.varint()?.checked_sub(1); - Ok(AnnounceBroadcast::Floor { id, revision }) + let mut chain = Vec::with_capacity(count as usize); + for _ in 0..count { + match r.varint()? { + 0 => return Err(DecodeError::InvalidValue), + relay => chain.push(relay), + } + } + Ok(Claim { + item: Attr { epoch, above }, + cost, + priority, + draining: flags & DRAINING != 0, + unavailable: flags & UNAVAILABLE != 0, + chain, + }) } /// Encode an ANNOUNCE_REQUEST body: the Prefix IDs to remove, then the prefixes to add, @@ -584,150 +428,6 @@ impl<'a> Decode<'a, Version> for PathRef { } } -/// Encode the Route ID a claim travels under, which only lite-07 carries. -fn encode_route_id(w: &mut Encoder<'_>, version: Version, route: u64) -> Result<(), EncodeError> { - match version.has_routes() { - true => w.varint(route), - false if route != 0 => Err(EncodeError::InvalidState), - false => Ok(()), - } -} - -/// Encode a lite-06 announcement's hop chain, which lite-07 replaces with its Route ID. -fn encode_chain(w: &mut Encoder<'_>, version: Version, hops: &Hops) -> Result<(), EncodeError> { - match version.has_routes() { - true => Ok(()), - false => hops.encode(w, version), - } -} - -/// Decode a lite-06 announcement's hop chain, empty on lite-07. -fn decode_chain(r: &mut Decoder<'_>, version: Version) -> Result { - match version.has_routes() { - true => Ok(Hops::default()), - false => Hops::decode(r, version), - } -} - -/// Encode lite-07's Above, which no earlier version has: a claim there is only ever at the -/// path it names. -fn encode_above(w: &mut Encoder<'_>, version: Version, above: u64) -> Result<(), EncodeError> { - if version.has_routes() { - return w.varint(above); - } - match above { - 0 => Ok(()), - _ => Err(EncodeError::InvalidState), - } -} - -/// Encode lite-07's trailing Lite-06 Chain, omitted when empty. A lite-06 compatibility -/// field: the lite-07 to lite-08 migration deletes it. -fn encode_lite06_chain(w: &mut Encoder<'_>, version: Version, hops: &Hops) -> Result<(), EncodeError> { - match version.has_routes() && !hops.is_empty() { - true => hops.encode(w, version), - false => Ok(()), - } -} - -/// A lite-07 ANNOUNCE_START: its suffix, Route ID, instance and epoch, cost, and -/// Lite-06 Chain. -fn decode_start(r: &mut Decoder<'_>, version: Version) -> Result { - let suffix = decode_suffix(r)?; - let route = r.varint()?; - let refused = |r: &mut Decoder<'_>, suffix, reason| { - r.rest(); - AnnounceBroadcast::Refused { - message: Refusable::Start { route, suffix }, - reason, - } - }; - let suffix = match suffix { - Ok(suffix) => suffix, - Err(reason) => return Ok(refused(r, None, reason)), - }; - let Some((instance, epoch)) = super::instance::decode_forwarded(r)? else { - return Ok(refused(r, Some(suffix), Refusal::Instance)); - }; - let cost = Cost::decode(r, version)?; - let above = r.varint()?; - Ok(match decode_lite06_chain(r)? { - Ok(hops) => AnnounceBroadcast::Active { - suffix, - route, - instance: Some(instance), - epoch, - hops, - cost, - above, - }, - Err(reason) => refused(r, Some(suffix), reason), - }) -} - -/// A lite-07 ANNOUNCE_UPDATE: its Announce ID, cost, and Lite-06 Chain. -fn decode_update(r: &mut Decoder<'_>, version: Version) -> Result { - let id = r.varint()?; - let cost = Cost::decode(r, version)?; - let above = r.varint()?; - Ok(match decode_lite06_chain(r)? { - Ok(hops) => AnnounceBroadcast::Update { id, hops, cost, above }, - Err(reason) => AnnounceBroadcast::Refused { - message: Refusable::Change { id }, - reason, - }, - }) -} - -/// A lite-07 ANNOUNCE_RESTART: its Announce ID, instance and epoch, cost, and Lite-06 -/// Chain. -fn decode_restart(r: &mut Decoder<'_>, version: Version) -> Result { - let id = r.varint()?; - let refused = |r: &mut Decoder<'_>, reason| { - r.rest(); - AnnounceBroadcast::Refused { - message: Refusable::Change { id }, - reason, - } - }; - let Some((instance, epoch)) = super::instance::decode_forwarded(r)? else { - return Ok(refused(r, Refusal::Instance)); - }; - let cost = Cost::decode(r, version)?; - let above = r.varint()?; - Ok(match decode_lite06_chain(r)? { - Ok(hops) => AnnounceBroadcast::Restart { - id, - instance: Some(instance), - epoch, - cost, - hops, - above, - }, - Err(reason) => refused(r, reason), - }) -} - -/// Decode lite-07's trailing Lite-06 Chain: present only when bytes remain, and never -/// empty, so an empty chain has one spelling. A chain no lite-06 relay would send, empty, -/// too long, or revisiting a hop, is refused. -fn decode_lite06_chain(r: &mut Decoder<'_>) -> Content { - if r.is_empty() { - return Ok(Ok(Hops::default())); - } - let count = r.varint()?; - if count == 0 { - return refuse(r, Refusal::Chain); - } - let mut hops = Hops::new(); - for _ in 0..count { - if hops.push(Hop::decode(r, ())?).is_err() { - return refuse(r, Refusal::Chain); - } - } - Ok(Ok(hops)) -} - impl Encode for Cost { fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { if !version.has_route_cost() { @@ -764,104 +464,76 @@ impl Encode for AnnounceBroadcast { if version.has_announce_id() { // Lite06+: outer type discriminator, then a size-prefixed body (like the // subscribe stream). The body varies by type. + let routes = version.has_routes(); let typ = match self { - Self::Active { .. } => ANNOUNCE_START, - Self::Synced { .. } if version.has_synced() => SYNCED, - Self::Request { .. } if version.has_routes() => ANNOUNCE_REQUEST, - Self::Ok if version.has_routes() => ANNOUNCE_OK, - Self::Synced { .. } | Self::Request { .. } | Self::Ok => return Err(EncodeError::Version), - Self::EndedId { .. } => ANNOUNCE_END, - Self::Update { .. } => ANNOUNCE_UPDATE, - Self::Restart { .. } if version.has_announce_restart() => ANNOUNCE_RESTART, - // Older versions send an end and a start instead. - Self::Restart { .. } => return Err(EncodeError::Version), - Self::RouteStart { .. } if version.has_routes() => ROUTE_START, - Self::RouteUpdate { .. } if version.has_routes() => ROUTE_UPDATE, - Self::RouteHold { .. } if version.has_routes() => ROUTE_HOLD, - Self::RouteEnd { .. } if version.has_routes() => ROUTE_END, - Self::Dead(_) if version.has_routes() => DEAD, - Self::Floor { .. } if version.has_routes() => ANNOUNCE_FLOOR, - Self::RouteStart { .. } - | Self::RouteUpdate { .. } - | Self::RouteHold { .. } - | Self::RouteEnd { .. } - | Self::Dead(_) - | Self::Floor { .. } => return Err(EncodeError::Version), + // Each version has its own form of a claim. + Self::Active { .. } if !routes => ANNOUNCE_START, + Self::EndedId { .. } if !routes => ANNOUNCE_END, + Self::Update { .. } if !routes => ANNOUNCE_UPDATE, + Self::Start { .. } if routes => ANNOUNCE_START, + Self::End { .. } if routes => ANNOUNCE_END, + Self::Change { .. } if routes => ANNOUNCE_UPDATE, + Self::Synced { .. } if routes => SYNCED, + Self::Request { .. } if routes => ANNOUNCE_REQUEST, + Self::Ok if routes => ANNOUNCE_OK, + Self::Route { .. } if routes => ROUTE, + Self::RouteEnd { .. } if routes => ROUTE_END, + Self::Dead { .. } if routes => DEAD, + Self::Drain { .. } if routes => DRAIN, + Self::Floor { .. } if routes => ANNOUNCE_FLOOR, + // Decode-only: an unknown type is never sent. + Self::Skipped => return Err(EncodeError::Unsupported), // The pre-lite-06 path-form retraction has no place on lite-06. - Self::Ended { .. } => return Err(EncodeError::Version), - // Decode-only: an unknown type or refused content is never sent. - Self::Skipped | Self::Refused { .. } => return Err(EncodeError::Unsupported), + _ => return Err(EncodeError::Version), }; w.varint(typ)?; let prefix = w.prefix_varint(); match self { - Self::Active { - suffix, - route, - instance, - epoch, - hops, - cost, - above, - } => { + Self::Active { suffix, hops, cost } => { suffix.encode(w, version)?; - encode_route_id(w, version, *route)?; - super::instance::encode_route(w, version, instance.as_ref(), *epoch)?; - encode_chain(w, version, hops)?; + hops.encode(w, version)?; cost.encode(w, version)?; - encode_above(w, version, *above)?; - encode_lite06_chain(w, version, hops)?; } Self::EndedId { id } => w.varint(*id)?, - Self::Update { id, hops, cost, above } => { + Self::Update { id, hops, cost } => { w.varint(*id)?; - encode_chain(w, version, hops)?; + hops.encode(w, version)?; cost.encode(w, version)?; - encode_above(w, version, *above)?; - encode_lite06_chain(w, version, hops)?; } - Self::Restart { - id, + Self::Start { + suffix, instance, - epoch, - cost, - hops, - above, + claim, } => { + suffix.encode(w, version)?; + super::instance::encode_route(w, version, Some(instance), claim.item.epoch)?; + encode_claim(w, claim)?; + } + Self::Change { id, claim } => { w.varint(*id)?; - super::instance::encode_route(w, version, instance.as_ref(), *epoch)?; - cost.encode(w, version)?; - encode_above(w, version, *above)?; - encode_lite06_chain(w, version, hops)?; + w.varint(claim.item.epoch)?; + encode_claim(w, claim)?; + } + Self::End { id, lost } => { + w.varint(*id)?; + w.bool(*lost); } Self::Synced { prefix } => w.varint(*prefix)?, Self::Request { more, remove, add } => encode_request(w, version, *more, remove, add)?, Self::Ok => {} - Self::RouteStart { - node, - prefix, - suffix, - exact, - offer, - } => { - if *node == 0 { - return Err(EncodeError::InvalidState); - } - w.varint(*node)?; - w.varint(*prefix)?; - suffix.encode(w, version)?; - w.bool(*exact); - encode_offer(w, offer)?; + Self::Route { offer } => encode_offer(w, offer)?, + Self::RouteEnd { id } => w.varint(*id)?, + Self::Dead { hop, far } => { + encode_hop(w, *hop)?; + encode_node(w, *far)?; } - Self::RouteUpdate { id, offer } => { + Self::Drain { node } => encode_node(w, *node)?, + Self::Floor { id, revision } => { w.varint(*id)?; - encode_offer(w, offer)?; + w.varint(*revision)?; } - Self::RouteHold { id } | Self::RouteEnd { id } => w.varint(*id)?, - Self::Dead(dead) => encode_dead(w, dead)?, - Self::Floor { id, revision } => encode_floor(w, *id, *revision)?, - Self::Ended { .. } | Self::Skipped | Self::Refused { .. } => unreachable!("refused above"), + Self::Ended { .. } | Self::Skipped => unreachable!("refused above"), } if w.since(&prefix) > MAX_MESSAGE_SIZE { w.discard(prefix); @@ -875,16 +547,11 @@ impl Encode for AnnounceBroadcast { let prefix = w.prefix_varint(); match self { // The cost is a lite-06 addition, so it is simply not on the wire here. - Self::Active { - suffix, route, hops, .. - } => { + Self::Active { suffix, hops, .. } => { // Bases are a lite-07 addition; PathRef refuses one here. if suffix.base != 0 { return Err(EncodeError::Version); } - if *route != 0 { - return Err(EncodeError::InvalidState); - } AnnounceStatus::Active.encode(w, version)?; suffix.rest.encode(w, version)?; encode_hops(w, version, hops)?; @@ -894,23 +561,8 @@ impl Encode for AnnounceBroadcast { suffix.encode(w, version)?; encode_hops(w, version, hops)?; } - // The id-referencing forms only exist on lite-06+. - Self::EndedId { .. } - | Self::Update { .. } - | Self::Restart { .. } - | Self::Skipped - | Self::Refused { .. } - | Self::Synced { .. } - | Self::Request { .. } - | Self::Ok - | Self::RouteStart { .. } - | Self::RouteUpdate { .. } - | Self::RouteHold { .. } - | Self::RouteEnd { .. } - | Self::Dead(_) - | Self::Floor { .. } => { - return Err(EncodeError::Version); - } + // Everything else only exists on lite-06+. + _ => return Err(EncodeError::Version), } if w.since(&prefix) > MAX_MESSAGE_SIZE { w.discard(prefix); @@ -930,89 +582,61 @@ impl<'a> Decode<'a, Version> for AnnounceBroadcast { let mut body = buf.sub(size)?; let msg = (|| { Ok(match typ { - // Lite-07's claims and routes carry what the sender forwarded, which - // a receiver may refuse without failing the stream. - ANNOUNCE_START if version.has_routes() => decode_start(&mut body, version)?, - ANNOUNCE_UPDATE if version.has_routes() => decode_update(&mut body, version)?, - ANNOUNCE_RESTART if version.has_announce_restart() => decode_restart(&mut body, version)?, - ANNOUNCE_START => { + ANNOUNCE_START if version.has_routes() => { let suffix = PathRef::decode(&mut body, version)?; - let hops = decode_chain(&mut body, version)?; - let cost = Cost::decode(&mut body, version)?; - Self::Active { + // Every lite-07 claim names its instance. + let (instance, epoch) = + super::instance::decode_forwarded(&mut body)?.ok_or(DecodeError::InvalidValue)?; + let claim = decode_claim(&mut body, epoch)?; + Self::Start { suffix, - route: 0, - instance: None, - epoch: 0, - hops, - cost, - above: 0, + instance, + claim, } } - SYNCED if version.has_synced() => Self::Synced { prefix: body.varint()? }, - ANNOUNCE_REQUEST if version.has_routes() => decode_request(&mut body, version)?, - ANNOUNCE_OK if version.has_routes() => Self::Ok, - ANNOUNCE_END => Self::EndedId { id: body.varint()? }, - ANNOUNCE_UPDATE => { + ANNOUNCE_UPDATE if version.has_routes() => { let id = body.varint()?; - let hops = decode_chain(&mut body, version)?; - let cost = Cost::decode(&mut body, version)?; - Self::Update { + let epoch = body.varint()?; + Self::Change { id, - hops, - cost, - above: 0, + claim: decode_claim(&mut body, epoch)?, } } - ROUTE_START if version.has_routes() => { - let node = body.varint()?; - let prefix = body.varint()?; - // The suffix is sized, so the offer's path reads even when it is refused. - let suffix = decode_path(&mut body)?; - let exact = body.bool()?; - let heard = decode_offer(&mut body)?; - match (node, suffix, heard) { - (1.., Ok(suffix), Ok(offer)) => Self::RouteStart { - node, - prefix, - suffix, - exact, - offer, - }, - (node, suffix, heard) => { - let reason = match (node, &suffix, &heard) { - (0, _, _) => Refusal::Node, - (_, Err(reason), _) => *reason, - (_, _, Err(unusable)) => unusable.reason, - _ => unreachable!("matched above"), - }; - Self::Refused { - message: Refusable::RouteStart { - node, - prefix, - suffix: suffix.ok(), - exact, - path: heard.map_or_else(|unusable| unusable.path, |offer| offer.path), - }, - reason, - } - } - } + ANNOUNCE_END if version.has_routes() => Self::End { + id: body.varint()?, + lost: body.bool()?, + }, + ANNOUNCE_START => { + let suffix = PathRef::decode(&mut body, version)?; + let hops = Hops::decode(&mut body, version)?; + let cost = Cost::decode(&mut body, version)?; + Self::Active { suffix, hops, cost } } - ROUTE_UPDATE if version.has_routes() => { + ANNOUNCE_END => Self::EndedId { id: body.varint()? }, + ANNOUNCE_UPDATE => { let id = body.varint()?; - match decode_offer(&mut body)? { - Ok(offer) => Self::RouteUpdate { id, offer }, - Err(Unusable { path, reason }) => Self::Refused { - message: Refusable::RouteUpdate { id, path }, - reason, - }, - } + let hops = Hops::decode(&mut body, version)?; + let cost = Cost::decode(&mut body, version)?; + Self::Update { id, hops, cost } } - DEAD if version.has_routes() => Self::Dead(decode_dead(&mut body)?), - ROUTE_HOLD if version.has_routes() => Self::RouteHold { id: body.varint()? }, + SYNCED if version.has_routes() => Self::Synced { prefix: body.varint()? }, + ANNOUNCE_REQUEST if version.has_routes() => decode_request(&mut body, version)?, + ANNOUNCE_OK if version.has_routes() => Self::Ok, + ROUTE if version.has_routes() => Self::Route { + offer: decode_offer(&mut body)?, + }, ROUTE_END if version.has_routes() => Self::RouteEnd { id: body.varint()? }, - ANNOUNCE_FLOOR if version.has_routes() => decode_floor(&mut body)?, + DEAD if version.has_routes() => Self::Dead { + hop: decode_hop(&mut body)?, + far: decode_node(&mut body)?, + }, + DRAIN if version.has_routes() => Self::Drain { + node: decode_node(&mut body)?, + }, + ANNOUNCE_FLOOR if version.has_routes() => Self::Floor { + id: body.varint()?, + revision: body.varint()?, + }, // Unknown types are skipped by length so an earlier Lite06 build // negotiating the same ALPN does not kill the announce stream. _ => { @@ -1063,12 +687,8 @@ impl AnnounceBroadcast { Ok(match status { AnnounceStatus::Active => Self::Active { suffix: PathRef::literal(suffix), - route: 0, - instance: None, - epoch: 0, hops, cost: Cost::UNKNOWN, - above: 0, }, AnnounceStatus::Ended => Self::Ended { suffix, hops }, // On lite-05 an update travels as a duplicate ANNOUNCE (a second `Active`), so accept @@ -1078,12 +698,8 @@ impl AnnounceBroadcast { // invalid value there. AnnounceStatus::Update if update_supported(version) => Self::Active { suffix: PathRef::literal(suffix), - route: 0, - instance: None, - epoch: 0, hops, cost: Cost::UNKNOWN, - above: 0, }, AnnounceStatus::Update => return Err(DecodeError::InvalidValue), }) @@ -1277,1291 +893,38 @@ impl<'a> Message<'a> for AnnounceOk { } } -#[cfg(test)] -mod tests { +#[cfg(all(test, feature = "async"))] +mod chain_tests { use super::*; - use bytes::Buf; - - /// A legacy initial set is held to the announce budget before any suffix decodes, so - /// a body of one-byte suffixes cannot become a list many times its size. - #[test] - fn announce_init_is_bounded_by_the_budget() { - let version = Version::Lite02; - let mut wire = Vec::new(); - AnnounceInit { - suffixes: vec![Path::from_static("a"), Path::from_static(""), Path::from_static("b")], - } - .encode(&mut Encoder::new(&mut wire, version.into()), version) - .unwrap(); - let decode = - |wire: &[u8], budget| AnnounceInit::decode_within(&mut Decoder::new(wire, version.into()), version, budget); - - assert_eq!(decode(&wire, 3).unwrap().suffixes.len(), 3); - assert!(matches!(decode(&wire, 2), Err(DecodeError::TooMany))); - - // A count the body cannot hold is malformed whatever the budget, before any allocation. - let mut wire = Vec::new(); - let mut w = Encoder::new(&mut wire, version.into()); - w.varint(8).unwrap(); - w.varint(u32::MAX.into()).unwrap(); - assert!(matches!(decode(&wire, usize::MAX), Err(DecodeError::InvalidValue))); - } - - /// Lite-06's ANNOUNCE_OK opens the stream with a Hop ID and a count. Lite-07's is a - /// message of the Announce Stream instead: SYNCED replaces the count, and routes - /// the Hop ID. - #[test] - fn announce_ok_opens_only_a_lite06_stream() { - let ok = AnnounceOk { - origin: Hop::new(1).unwrap(), - active: 7, - }; - let mut bytes = Vec::new(); - ok.encode(&mut Encoder::new(&mut bytes, Version::Lite06.into()), Version::Lite06) - .unwrap(); - assert_eq!(bytes, [2, 1, 7]); - let res = ok.encode( - &mut Encoder::new(&mut Vec::new(), Version::Lite07.into()), - Version::Lite07, - ); - assert!(matches!(res, Err(EncodeError::Version))); - assert!(crate::coding::decode_buf(&mut &[0u8][..], Version::Lite07, |r, v| AnnounceOk::decode(r, v)).is_err()); - } - - #[test] - fn synced_marks_lite07s_initial_set() { - let mut bytes = Vec::new(); - AnnounceBroadcast::Synced { prefix: 3 } - .encode(&mut Encoder::new(&mut bytes, Version::Lite07.into()), Version::Lite07) - .unwrap(); - assert_eq!(bytes, vec![4, 1, 3]); - assert!(matches!( - AnnounceBroadcast::Synced { prefix: 3 }.encode( - &mut Encoder::new(&mut Vec::new(), Version::Lite06.into()), - Version::Lite06 - ), - Err(EncodeError::Version) - )); - } - - // Forge an ANNOUNCE_BROADCAST with the draft's explicit `restart` status (2) for the given version. - fn encode_forged_restart(version: Version) -> bytes::Bytes { - // Encode a normal Active, then flip its status byte (1 -> 2). - let mut buf = Vec::new(); - AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("foo/bar")), - hops: Hops::default(), - cost: Cost::default(), - above: 0, - } - .encode(&mut Encoder::new(&mut buf, version.into()), version) - .expect("encode"); - - // Layout: <...>. The message is small, so the size is one byte and - // the status byte sits at index 1. - assert_eq!( - buf[1], - u8::from(AnnounceStatus::Active), - "expected an Active status byte" - ); - buf[1] = u8::from(AnnounceStatus::Update); - bytes::Bytes::from(buf) - } - - // On lite-05+ the explicit `restart` status is accepted and surfaced as an `Active` (the - // subscriber retires an already-announced path before republishing it). - #[test] - fn decodes_explicit_restart_status_as_active_on_lite05() { - let version = Version::Lite05; - let mut slice = encode_forged_restart(version); - let decoded = crate::coding::decode_buf(&mut slice, version, |r, v| AnnounceBroadcast::decode(r, v)) - .expect("explicit restart must decode"); - assert!(!slice.has_remaining(), "trailing bytes after decode"); - assert!( - matches!(decoded, AnnounceBroadcast::Active { .. }), - "restart should decode as Active" - ); - } - - // Older versions never defined the restart status, so it's an invalid value there. - #[test] - fn rejects_explicit_restart_status_before_lite05() { - let version = Version::Lite04; - let mut slice = encode_forged_restart(version); - assert!( - matches!( - crate::coding::decode_buf(&mut slice, version, |r, v| AnnounceBroadcast::decode(r, v)), - Err(DecodeError::InvalidValue) - ), - "restart status must be rejected before lite-05" - ); - } - - fn round_trip(msg: &AnnounceOk) -> AnnounceOk { - let mut buf = Vec::new(); - msg.encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05) - .unwrap(); - let mut slice = &buf[..]; - let got = crate::coding::decode_buf(&mut slice, Version::Lite05, |r, v| AnnounceOk::decode(r, v)).unwrap(); - assert!(slice.is_empty(), "trailing bytes after decode"); - got - } - - #[test] - fn announce_ok_round_trip() { - let msg = AnnounceOk { - origin: Hop::new(42).unwrap(), - active: 3, - }; - assert_eq!(round_trip(&msg), msg); - } - - #[test] - fn announce_ok_zero_active() { - let msg = AnnounceOk { - origin: Hop::new(7).unwrap(), - active: 0, - }; - assert_eq!(round_trip(&msg), msg); - } - - fn broadcast_round_trip(msg: &AnnounceBroadcast, version: Version) -> AnnounceBroadcast { - let mut buf = Vec::new(); - msg.encode(&mut Encoder::new(&mut buf, version.into()), version) - .unwrap(); - let mut slice = &buf[..]; - let got = crate::coding::decode_buf(&mut slice, version, |r, v| AnnounceBroadcast::decode(r, v)).unwrap(); - assert!(slice.is_empty(), "trailing bytes after decode"); - got - } - - #[test] - fn announce_broadcast_round_trip_on_lite05() { - let mut hops = Hops::new(); - hops.push(Hop::new(7).unwrap()).unwrap(); - let msg = AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("room/cam")), - hops: hops.clone(), - cost: Cost::UNKNOWN, - above: 0, - }; - assert_eq!(broadcast_round_trip(&msg, Version::Lite05), msg); - - let ended = AnnounceBroadcast::Ended { - suffix: Path::from_static("room/cam"), - hops: Hops::new(), - }; - assert_eq!(broadcast_round_trip(&ended, Version::Lite05), ended); - } - - #[test] - fn announce_broadcast_round_trip_on_lite06() { - let mut hops = Hops::new(); - hops.push(Hop::new(7).unwrap()).unwrap(); - - // A priced start and update preserve the same static value. - let cost = Cost::new(12); - - let active = AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("room/cam")), - hops: hops.clone(), - cost, - above: 0, - }; - assert_eq!(broadcast_round_trip(&active, Version::Lite06), active); - - let ended = AnnounceBroadcast::EndedId { id: 3 }; - assert_eq!(broadcast_round_trip(&ended, Version::Lite06), ended); - - let update = AnnounceBroadcast::Update { - id: 3, - hops, - cost, - above: 0, - }; - assert_eq!(broadcast_round_trip(&update, Version::Lite06), update); - } - - // Lite07 carries the path base as it travels, and the route in place of a hop chain; - // the codec resolves nothing. - #[test] - fn announce_broadcast_round_trip_on_lite07() { - let cost = Cost::new(12); - - let active = AnnounceBroadcast::Active { - route: 4, - instance: Some("a".parse().unwrap()), - epoch: 5, - suffix: PathRef { - base: 2, - keep: 3, - rest: Path::from_static("cam"), - }, - hops: Hops::default(), - cost, - above: 0, - }; - assert_eq!(broadcast_round_trip(&active, Version::Lite07), active); - - let update = AnnounceBroadcast::Update { - id: 3, - hops: Hops::default(), - cost, - above: 0, - }; - assert_eq!(broadcast_round_trip(&update, Version::Lite07), update); - - for epoch in [0, 9] { - let restart = AnnounceBroadcast::Restart { - id: 3, - instance: Some(Instance::random()), - epoch, - cost, - hops: Hops::default(), - above: 0, - }; - assert_eq!(broadcast_round_trip(&restart, Version::Lite07), restart); - } - } - - /// The draft's field order, byte for byte: ANNOUNCE_START is the path base, keep, and - /// rest, the Route ID, the instance, its minted flag, the epoch, and the cost; - /// ANNOUNCE_UPDATE is the Announce ID and the cost. - #[test] - fn lite07_announce_layout() { - let encode = |msg: AnnounceBroadcast| { - let mut buf = Vec::new(); - msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) - .unwrap(); - buf - }; - let suffix = PathRef { - base: 1, - keep: 2, - rest: Path::from_static("c"), - }; - assert_eq!( - encode(AnnounceBroadcast::Active { - suffix: suffix.clone(), - route: 3, - instance: Some("a".parse().unwrap()), - epoch: 5, - hops: Hops::default(), - cost: Cost::new(6), - above: 0, - }), - [0, 11, 1, 2, 1, b'c', 3, 1, b'a', 0, 5, 6, 0] - ); - assert_eq!( - encode(AnnounceBroadcast::Update { - id: 7, - hops: Hops::default(), - cost: Cost::new(6), - above: 0, - }), - [2, 3, 7, 6, 0] - ); - assert_eq!( - encode(AnnounceBroadcast::Restart { - id: 7, - instance: Some("a".parse().unwrap()), - epoch: 5, - cost: Cost::new(6), - hops: Hops::default(), - above: 0, - }), - [3, 7, 7, 1, b'a', 0, 5, 6, 0] - ); - } - - /// Lite-07 carries a lite-06 chain after the cost, only when it is not empty, so an - /// explicitly empty one is refused. - #[test] - fn lite07_carries_a_trailing_lite06_chain() { - let mut hops = Hops::new(); - hops.push(Hop::new(7).unwrap()).unwrap(); - hops.push(Hop::new(9).unwrap()).unwrap(); - let encode = |msg: &AnnounceBroadcast| { - let mut buf = Vec::new(); - msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) - .unwrap(); - buf - }; - let msgs = [ - AnnounceBroadcast::Active { - route: 3, - instance: Some("a".parse().unwrap()), - epoch: 5, - suffix: PathRef::literal(Path::from_static("c")), - hops: hops.clone(), - cost: Cost::new(6), - above: 0, - }, - AnnounceBroadcast::Update { - id: 7, - hops: hops.clone(), - cost: Cost::new(6), - above: 0, - }, - AnnounceBroadcast::Restart { - id: 7, - instance: Some("a".parse().unwrap()), - epoch: 5, - cost: Cost::new(6), - hops, - above: 0, - }, - ]; - let layouts: [&[u8]; 3] = [ - &[0, 14, 0, 0, 1, b'c', 3, 1, b'a', 0, 5, 6, 0, 2, 7, 9], - &[2, 6, 7, 6, 0, 2, 7, 9], - &[3, 10, 7, 1, b'a', 0, 5, 6, 0, 2, 7, 9], - ]; - for (msg, layout) in msgs.iter().zip(layouts) { - assert_eq!(encode(msg), layout, "{msg:?}"); - assert_eq!(broadcast_round_trip(msg, Version::Lite07), *msg); - } - - // A chain present but empty, or revisiting a hop, is refused, as is the claim it - // came with. - let decode = |mut wire: &[u8]| { - crate::coding::decode_buf(&mut wire, Version::Lite07, |r, v| AnnounceBroadcast::decode(r, v)).unwrap() - }; - let refused = AnnounceBroadcast::Refused { - message: Refusable::Change { id: 7 }, - reason: Refusal::Chain, - }; - assert_eq!(decode(&[2, 4, 7, 6, 0, 0]), refused); - assert_eq!(decode(&[2, 6, 7, 6, 0, 2, 9, 9]), refused); - assert_eq!(decode(&[3, 10, 7, 1, b'a', 0, 5, 6, 0, 2, 9, 9]), refused); - assert_eq!( - decode(&[0, 14, 0, 0, 1, b'c', 3, 1, b'a', 0, 5, 6, 0, 2, 9, 9]), - AnnounceBroadcast::Refused { - message: Refusable::Start { - route: 3, - suffix: Some(PathRef::literal(Path::from_static("c"))), - }, - reason: Refusal::Chain, - } - ); - } - - /// A claim presented above its path keeps how far above on every message that carries - /// it, and no earlier version can say it. - #[test] - fn an_above_survives_the_wire() { - let msgs = [ - AnnounceBroadcast::Active { - route: 1, - instance: Some("a".parse().unwrap()), - epoch: 0, - suffix: PathRef::literal(Path::empty()), - hops: Hops::default(), - cost: Cost::default(), - above: 2, - }, - AnnounceBroadcast::Update { - id: 1, - hops: Hops::default(), - cost: Cost::default(), - above: 2, - }, - AnnounceBroadcast::Restart { - id: 1, - instance: Some("a".parse().unwrap()), - epoch: 0, - cost: Cost::default(), - hops: Hops::default(), - above: 2, - }, - ]; - for msg in &msgs { - assert_eq!(broadcast_round_trip(msg, Version::Lite07), *msg); - } - let msg = AnnounceBroadcast::Update { - id: 1, - hops: Hops::default(), - cost: Cost::default(), - above: 1, - }; - let mut buf = Vec::new(); - let res = msg.encode(&mut Encoder::new(&mut buf, Version::Lite06.into()), Version::Lite06); - assert!(matches!(res, Err(EncodeError::InvalidState))); - } - - /// Only lite-07 carries a Route ID: a non-zero one has nowhere to go earlier, and an - /// earlier start decodes as route 0. - #[test] - fn a_route_id_needs_lite07() { - let msg = AnnounceBroadcast::Active { - route: 1, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("cam")), - hops: Hops::default(), - cost: Cost::default(), - above: 0, - }; - for version in [Version::Lite05, Version::Lite06] { - let mut buf = Vec::new(); - let res = msg.encode(&mut Encoder::new(&mut buf, version.into()), version); - assert!(matches!(res, Err(EncodeError::InvalidState)), "{version:?}"); - } - } - - // Only lite-07 carries ANNOUNCE_RESTART: older versions send an end and a start, and an - // older receiver skips the unknown type. - #[test] - fn announce_restart_needs_lite07() { - let restart = AnnounceBroadcast::Restart { - id: 1, - instance: Some("a".parse().unwrap()), - epoch: 0, - cost: Cost::default(), - hops: Hops::default(), - above: 0, - }; - let mut buf = Vec::new(); - assert!(matches!( - restart.encode(&mut Encoder::new(&mut buf, Version::Lite06.into()), Version::Lite06), - Err(EncodeError::Version) - )); - - let mut buf = Vec::new(); - restart - .encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) - .unwrap(); - // The same bytes, read as lite-06: an unknown type, skipped by length. - let mut legacy = Vec::new(); - let mut encoder = Encoder::new(&mut legacy, Version::Lite06.into()); - encoder.varint(ANNOUNCE_RESTART).unwrap(); - encoder.varint(1).unwrap(); - encoder.varint(1).unwrap(); - assert_eq!( - crate::coding::decode_buf(&mut &legacy[..], Version::Lite06, |r, v| AnnounceBroadcast::decode( - r, v - )) - .unwrap(), - AnnounceBroadcast::Skipped - ); - } - - // A keep copies from a base, so one without a base is malformed. - #[test] - fn a_keep_without_a_base_is_rejected() { - // Path base, path keep, empty rest, route, instance "a", epoch, cost. - let body = [0, 1, 0, 0, 1, b'a', 0, 0]; - let mut buf = vec![ANNOUNCE_START as u8, body.len() as u8]; - buf.extend_from_slice(&body); - assert!(matches!( - crate::coding::decode_buf(&mut &buf[..], Version::Lite07, |r, v| AnnounceBroadcast::decode(r, v)), - Err(DecodeError::InvalidValue) - )); - } - - // Only lite-07 has room for a base. - #[test] - fn a_base_needs_lite07() { - let msg = AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef { - base: 1, - keep: 1, - rest: Path::from_static("cam"), - }, - hops: Hops::default(), - cost: Cost::default(), - above: 0, - }; - for version in [Version::Lite05, Version::Lite06] { - let mut buf = Vec::new(); - assert!(matches!( - msg.encode(&mut Encoder::new(&mut buf, version.into()), version), - Err(EncodeError::Version) - )); - } - } - - // The id-referencing forms don't exist before lite-06, and the path form is gone on lite-06. - #[test] - fn announce_broadcast_rejects_cross_version_forms() { - let mut buf = Vec::new(); - assert!(matches!( - AnnounceBroadcast::EndedId { id: 1 } - .encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05), - Err(EncodeError::Version) - )); - assert!(matches!( - AnnounceBroadcast::Update { - id: 1, - hops: Hops::default(), - cost: Cost::default(), - above: 0, - } - .encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05), - Err(EncodeError::Version) - )); - assert!(matches!( - AnnounceBroadcast::Ended { - suffix: Path::from_static("room/cam"), - hops: Hops::new() - } - .encode(&mut Encoder::new(&mut buf, Version::Lite06.into()), Version::Lite06), - Err(EncodeError::Version) - )); - } - - // Pre-lite-06 has no room for a cost on the wire, so one set locally is simply - // not sent and the peer decodes [`Cost::UNKNOWN`]: free to reach, which keeps a - // mixed-version mesh ranking those routes on hop count exactly as it did before, - // with only the arriving link price contributing to route selection. - #[test] - fn route_cost_is_dropped_before_lite06() { - let msg = AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("room/cam")), - hops: Hops::default(), - cost: Cost::new(9), - above: 0, - }; - let got = broadcast_round_trip(&msg, Version::Lite05); - assert_eq!( - got, - AnnounceBroadcast::Active { - route: 0, - instance: None, - epoch: 0, - suffix: PathRef::literal(Path::from_static("room/cam")), - hops: Hops::default(), - cost: Cost::UNKNOWN, - above: 0, - } - ); - } - - // Costs saturate at 2^62-1 on every version, lite-07's 64-bit varints included, so - // charging a link on top of the ceiling still re-encodes for a peer on any version. - #[test] - fn charged_cost_stays_encodable() { - let cost = Cost::new(u64::MAX).charged(1); - assert_eq!(cost, Cost::new((1 << 62) - 1)); - assert_eq!(Cost::MAX.charged(1), cost); - for version in [Version::Lite06, Version::Lite07] { - let buf = cost.encode_bytes(version).expect("a charged cost must stay encodable"); - assert_eq!(Cost::decode_slice(&buf, version).unwrap().0, cost, "{version}"); - } - } - - #[test] - fn unknown_announce_type_is_skipped() { - let mut body = Vec::new(); - Path::from_static("room/cam") - .encode(&mut Encoder::new(&mut body, Version::Lite06.into()), Version::Lite06) - .unwrap(); - Hops::new() - .encode(&mut Encoder::new(&mut body, Version::Lite06.into()), Version::Lite06) - .unwrap(); - Cost::default() - .encode(&mut Encoder::new(&mut body, Version::Lite06.into()), Version::Lite06) - .unwrap(); - - let mut buf = Vec::new(); - Encoder::new(&mut buf, Version::Lite06.into()).varint(4u64).unwrap(); - Encoder::new(&mut buf, Version::Lite06.into()) - .varint(body.len() as u64) - .unwrap(); - buf.extend_from_slice(&body); - - let mut slice = &buf[..]; - let got = crate::coding::decode_buf(&mut slice, Version::Lite06, |r, v| AnnounceBroadcast::decode(r, v)) - .expect("unknown type must not kill the stream"); - assert!(slice.is_empty()); - assert_eq!(got, AnnounceBroadcast::Skipped); - } - - // An ANNOUNCE_END message on lite-06 is tiny: type byte, size prefix, id varint. - #[test] - fn ended_by_id_is_three_bytes() { - let mut buf = Vec::new(); - AnnounceBroadcast::EndedId { id: 42 } - .encode(&mut Encoder::new(&mut buf, Version::Lite06.into()), Version::Lite06) - .unwrap(); - assert_eq!(buf.len(), 3); - } - - /// An edit too large for one message goes in as many as it takes, each fitting one, - /// every one but the last continuing it, and together holding the whole edit in order. - #[test] - fn an_edit_too_large_for_one_message_goes_in_parts() { - const VERSION: Version = Version::Lite07; - // Prefix IDs from 2^28 take five bytes. - let remove: Vec = (0..20_000).map(|i| (1 << 28) + i).collect(); - let add: Vec<(Path, bool)> = (0..3_000) - .map(|i| (Path::new(&format!("{i:0>20}")).unwrap(), i % 2 == 0)) - .collect(); - let parts = request_parts(remove.clone(), add.clone(), VERSION); - assert!(parts.len() > 2, "{}", parts.len()); - let (mut removed, mut added) = (Vec::new(), Vec::new()); - for (i, part) in parts.iter().enumerate() { - let mut bytes = Vec::new(); - part.encode(&mut Encoder::new(&mut bytes, VERSION.into()), VERSION) - .unwrap(); - assert_eq!(broadcast_round_trip(part, VERSION), *part); - let AnnounceBroadcast::Request { more, remove, add } = part else { - panic!("{part:?}"); - }; - assert_eq!(*more, i + 1 < parts.len()); - // The type and the length take at most 4 bytes. - assert!( - bytes.len() <= super::super::message::MAX_MESSAGE_SIZE + 4, - "{}", - bytes.len() - ); - removed.extend(remove.iter().copied()); - added.extend(add.iter().cloned()); - } - assert_eq!((removed, added), (remove, add)); - - // An edit that fits goes whole, and one with nothing in it still goes. - let small = request_parts(vec![1], vec![(Path::from_static("a"), false)], VERSION); - assert!(matches!( - small.as_slice(), - [AnnounceBroadcast::Request { more: false, .. }] - )); - let empty = request_parts(Vec::new(), Vec::new(), VERSION); - assert!(matches!( - empty.as_slice(), - [AnnounceBroadcast::Request { more: false, .. }] - )); - } - - fn request_round_trip(msg: &AnnounceRequest, version: Version) -> AnnounceRequest { - let mut buf = Vec::new(); - msg.encode(&mut Encoder::new(&mut buf, version.into()), version) - .unwrap(); - let mut slice = &buf[..]; - let got = crate::coding::decode_buf(&mut slice, version, |r, v| AnnounceRequest::decode(r, v)).unwrap(); - assert!(slice.is_empty(), "trailing bytes after decode"); - AnnounceRequest { - prefix: got.prefix.clone(), - exclude_hop: got.exclude_hop, - } - } - - // Lite-07 edits a set of prefixes on its one stream instead of opening a stream per - // prefix. - #[test] - fn announce_request_edits_a_set_on_lite07() { - let msg = AnnounceRequest { - prefix: Path::from_static("room"), - exclude_hop: Hop::UNKNOWN, - }; - let res = msg.encode( - &mut Encoder::new(&mut Vec::new(), Version::Lite07.into()), - Version::Lite07, - ); - assert!(matches!(res, Err(EncodeError::Version))); - - let edit = AnnounceBroadcast::Request { - more: true, - remove: vec![0, 7], - add: vec![(Path::from_static("room"), true), (Path::empty(), false)], - }; - assert_eq!(broadcast_round_trip(&edit, Version::Lite07), edit); - let mut bytes = Vec::new(); - edit.encode(&mut Encoder::new(&mut bytes, Version::Lite07.into()), Version::Lite07) - .unwrap(); - // Type, length, More, the removed Prefix IDs, then each added prefix with its Hidden. - assert_eq!(bytes, [&[16, 13, 1, 2, 0, 7, 2, 4][..], b"room", &[1, 0, 0]].concat()); - assert_eq!( - broadcast_round_trip(&AnnounceBroadcast::Ok, Version::Lite07), - AnnounceBroadcast::Ok - ); - for msg in [edit, AnnounceBroadcast::Ok] { - let res = msg.encode( - &mut Encoder::new(&mut Vec::new(), Version::Lite06.into()), - Version::Lite06, - ); - assert!(matches!(res, Err(EncodeError::Version)), "{msg:?}"); - } - } - - // A flag byte other than 0 or 1 is malformed, not a future extension, and a count - // the body cannot hold is refused before anything is allocated for it. - #[test] - fn announce_request_rejects_a_bad_body() { - let bad_flag = forge(ANNOUNCE_REQUEST, |w| { - w.varint(0u64).unwrap(); - w.varint(1u64).unwrap(); - Path::from_static("room").encode(w, Version::Lite07).unwrap(); - w.u8(2); - }); - assert!(decode_broadcast(&bad_flag, Version::Lite07).is_err()); - let overcount = forge(ANNOUNCE_REQUEST, |w| { - w.varint(u64::MAX >> 2).unwrap(); - }); - assert!(decode_broadcast(&overcount, Version::Lite07).is_err()); - } - - // The whole set has to fit the Adds of one message. - #[test] - fn a_request_set_fits_one_message() { - let long = Path::new(&"a".repeat(1000)).unwrap(); - let fits: Vec = vec![long.clone(); 65]; - assert!(request_fits(fits.iter(), Version::Lite07)); - let over: Vec = vec![long; 66]; - assert!(!request_fits(over.iter(), Version::Lite07)); - } - - // Lite04/05 carry the subscriber's origin id so the publisher can skip reflected - // announces before they hit the wire. - #[test] - fn announce_request_carries_exclude_hop_on_lite05() { - let msg = AnnounceRequest { - prefix: Path::from_static("room"), - exclude_hop: Hop::new(42).unwrap(), - }; - assert_eq!(request_round_trip(&msg, Version::Lite05).exclude_hop.id(), 42); - } - - // Lite06 dropped the field: the receiver's reflected-announce check catches the same - // loops, so a value set locally is simply not sent and decodes as zero. - #[test] - fn announce_request_drops_exclude_hop_on_lite06() { - let msg = AnnounceRequest { - prefix: Path::from_static("room"), - exclude_hop: Hop::new(42).unwrap(), - }; - assert_eq!(request_round_trip(&msg, Version::Lite06).exclude_hop, Hop::UNKNOWN); - - // And it costs nothing on the wire: the body is just the prefix. - let mut with = Vec::new(); - msg.encode(&mut Encoder::new(&mut with, Version::Lite05.into()), Version::Lite05) - .unwrap(); - let mut without = Vec::new(); - msg.encode(&mut Encoder::new(&mut without, Version::Lite06.into()), Version::Lite06) - .unwrap(); - assert!( - without.len() < with.len(), - "lite06 must not encode the exclude_hop varint" - ); - } + /// A claim's chain names at most 31 relays: one more would be the Relay of a node that + /// does not take the claim, so the codec refuses it in both directions. #[test] - fn announce_ok_rejects_old_versions() { - let msg = AnnounceOk { - origin: Hop::new(1).unwrap(), - active: 0, - }; - let mut buf = Vec::new(); - assert!(matches!( - msg.encode(&mut Encoder::new(&mut buf, Version::Lite04.into()), Version::Lite04), - Err(EncodeError::Version) - )); - } - - #[test] - fn announce_ok_accepts_zero_origin() { - // Encode a well-formed message then patch the origin to 0 on the wire. - let mut buf = Vec::new(); - AnnounceOk { - origin: Hop::new(1).unwrap(), - active: 0, - } - .encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05) - .unwrap(); - // origin id 1 sits right after the size prefix; rewrite it to 0. - let bytes = &buf[..]; - let mut patched = bytes.to_vec(); - // size(1 byte) | origin varint(1 byte = 0x01) | active varint(1 byte) - patched[1] = 0x00; - let mut slice = &patched[..]; - let got = crate::coding::decode_buf(&mut slice, Version::Lite05, |r, v| AnnounceOk::decode(r, v)).unwrap(); - assert_eq!(got.origin.id(), 0); - assert_eq!(got.active, 0); - } - - #[test] - fn wip_cost_has_one_field_and_lite06_keeps_two() { - let mut wire = Vec::new(); - Cost::new(12) - .encode(&mut Encoder::new(&mut wire, Version::Lite07.into()), Version::Lite07) - .unwrap(); - assert_eq!(wire, [12]); - - wire.clear(); - Cost::new(12) - .encode(&mut Encoder::new(&mut wire, Version::Lite06.into()), Version::Lite06) - .unwrap(); - let mut input = Decoder::new(&wire, Version::Lite06.into()); - assert_eq!(input.varint().unwrap(), 12); - assert_eq!(input.varint().unwrap(), Cost::MAX.value()); - assert!(input.is_empty()); - - for cold in [0, 3, Cost::MAX.value()] { - wire.clear(); - let mut w = Encoder::new(&mut wire, Version::Lite06.into()); - w.varint(12).unwrap(); - w.varint(cold).unwrap(); - let mut input = Decoder::new(&wire, Version::Lite06.into()); - assert_eq!(Cost::decode(&mut input, Version::Lite06).unwrap(), Cost::new(12)); - assert!(input.is_empty()); - } - } - - /// An offer over `path`, each hop `(node, session)`, the publisher first. - fn offer(path: &[(u64, u64)], metric: u64, down_only: bool) -> Offer { - Offer { - path: path - .iter() - .map(|&(node, session)| route::path::Hop { node, session }) - .collect(), + fn a_claim_chain_at_the_hop_limit_is_refused() { + let form = Version::Lite07.into(); + let claim = |relays: u64| Claim { + item: route::node::Attr { epoch: 0, above: 0 }, + cost: 0, + priority: i8::MAX, draining: false, - priority: 0, - metric, - down_only, - } - } - - /// Encode a typed lite-07 announce message from its raw body, bypassing the encoder's checks. - fn forge(typ: u64, body: impl FnOnce(&mut Encoder<'_>)) -> Vec { - let version = Version::Lite07; - let mut inner = Vec::new(); - body(&mut Encoder::new(&mut inner, version.into())); - let mut buf = Vec::new(); - let mut w = Encoder::new(&mut buf, version.into()); - w.varint(typ).unwrap(); - w.varint(inner.len() as u64).unwrap(); - buf.extend_from_slice(&inner); - buf - } - - fn decode_broadcast(buf: &[u8], version: Version) -> Result { - let mut slice = buf; - crate::coding::decode_buf(&mut slice, version, |r, v| AnnounceBroadcast::decode(r, v)) - } - - #[test] - fn route_messages_round_trip_on_lite07() { - let long: Vec<(u64, u64)> = (1..=route::MAX_HOPS as u64).map(|node| (node, node * 3)).collect(); - for msg in [ - AnnounceBroadcast::RouteStart { - node: 0x7a3f, - prefix: 0, - suffix: Path::empty(), - exact: true, - offer: offer(&[(0x7a3f, 0)], 0, false), - }, - AnnounceBroadcast::RouteStart { - node: route::QUALIFIED | 9, - prefix: 0, - suffix: Path::from_static("room/a"), - exact: false, - offer: offer(&[(9, 0), (4, u64::MAX >> 2)], route::MAX, true), - }, - AnnounceBroadcast::RouteUpdate { - id: 0, - offer: Offer { - draining: true, - priority: i8::MIN, - ..offer(&[(5, 0), (6, 1)], 2, false) - }, - }, - AnnounceBroadcast::RouteStart { - node: 0x7a40, - prefix: 0, - suffix: Path::empty(), - exact: false, - offer: Offer { - priority: i8::MAX, - ..offer(&[(5, 0), (route::MAX, 7), (9, 2)], 0, false) - }, - }, - AnnounceBroadcast::RouteUpdate { - id: 1, - offer: offer(&long, 3, true), - }, - AnnounceBroadcast::RouteHold { id: 3 }, - AnnounceBroadcast::RouteEnd { id: 0 }, - AnnounceBroadcast::Dead(Dead::Closed { - hop: route::path::Hop { node: 4, session: 2 }, - far: 9, - gone: false, - moved: 0, - }), - AnnounceBroadcast::Dead(Dead::Closed { - hop: route::path::Hop { node: 4, session: 0 }, - far: route::MAX, - gone: true, - moved: 2, - }), - AnnounceBroadcast::Dead(Dead::Drain { node: 4 }), - AnnounceBroadcast::Floor { - id: 0, - revision: Some(0), - }, - AnnounceBroadcast::Floor { - id: 1, - revision: Some(route::MAX - 1), - }, - AnnounceBroadcast::Floor { id: 2, revision: None }, - ] { - assert_eq!(broadcast_round_trip(&msg, Version::Lite07), msg); - } - } - - /// The priority travels as the moq-lite priority byte, ordered as the model's i8. - #[test] - fn an_offer_carries_the_priority_byte() { - let mut buf = Vec::new(); - let msg = AnnounceBroadcast::RouteUpdate { - id: 0, - offer: Offer { - priority: -1, - ..offer(&[(1, 0)], 0, false) - }, + unavailable: false, + chain: (1..=relays).collect(), }; - msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) - .unwrap(); - // Type, length, Route ID, the one hop's count, node, and session, flags, then the - // priority byte. - assert_eq!(buf[7], 0x7f); - } - - /// A floor is a marker: the Route ID and the revision plus one, 0 when it certifies - /// nothing. - #[test] - fn a_floor_is_its_route_and_revision() { - let encode = |revision| { - let mut buf = Vec::new(); - AnnounceBroadcast::Floor { id: 0, revision } - .encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) - .unwrap(); - buf - }; - assert_eq!(encode(Some(0)), vec![9, 2, 0, 1]); - assert_eq!(encode(Some(7)), vec![9, 2, 0, 8]); - assert_eq!(encode(None), vec![9, 2, 0, 0]); - } - - #[test] - fn route_messages_need_lite07() { - for msg in [ - AnnounceBroadcast::RouteStart { - node: 1, - prefix: 0, - suffix: Path::empty(), - exact: false, - offer: offer(&[(1, 0)], 0, false), - }, - AnnounceBroadcast::RouteUpdate { - id: 0, - offer: offer(&[(1, 0)], 0, false), - }, - AnnounceBroadcast::RouteHold { id: 0 }, - AnnounceBroadcast::RouteEnd { id: 0 }, - AnnounceBroadcast::Dead(Dead::Drain { node: 1 }), - AnnounceBroadcast::Floor { id: 0, revision: None }, - ] { - for version in [Version::Lite05, Version::Lite06] { - let mut buf = Vec::new(); - let res = msg.encode(&mut Encoder::new(&mut buf, version.into()), version); - assert!(matches!(res, Err(EncodeError::Version)), "{msg:?} on {version:?}"); - } - } - // A lite-06 receiver skips the type like any other it does not know. - let wire = forge(ROUTE_END, |w| w.varint(0u64).unwrap()); - assert_eq!( - decode_broadcast(&wire, Version::Lite06).unwrap(), - AnnounceBroadcast::Skipped - ); - } - - /// What no node offers is refused on both ends: node 0, an empty path or one past the - /// hop limit, and the last revision. - #[test] - fn route_messages_refuse_what_no_node_offers() { - let over: Vec<(u64, u64)> = (1..=route::MAX_HOPS as u64 + 1).map(|node| (node, 0)).collect(); - let refused = [ - AnnounceBroadcast::RouteStart { - node: 0, - prefix: 0, - suffix: Path::empty(), - exact: false, - offer: offer(&[(1, 0)], 1, false), - }, - AnnounceBroadcast::RouteStart { - node: 1, - prefix: 0, - suffix: Path::empty(), - exact: false, - offer: offer(&[], 1, false), - }, - AnnounceBroadcast::RouteUpdate { - id: 0, - offer: offer(&over, 1, false), - }, - AnnounceBroadcast::RouteUpdate { - id: 0, - offer: offer(&[(1, 0), (0, 1)], 1, false), - }, - AnnounceBroadcast::Dead(Dead::Drain { node: 0 }), - AnnounceBroadcast::Dead(Dead::Closed { - hop: route::path::Hop { node: 1, session: 1 }, - far: 0, - gone: false, - moved: 0, - }), - // The last revision has no room for the offset. - AnnounceBroadcast::Floor { - id: 0, - revision: Some(route::MAX), - }, - ]; - for msg in refused { + let encode = |relays: u64| { let mut buf = Vec::new(); - let res = msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07); - assert!(matches!(res, Err(EncodeError::InvalidState)), "{msg:?}"); - } - - // An offer whose path counts `count` hops and names `named` of them, from Node ID - // `first` up, each on session 0, then these flags, the default priority, and a - // metric of 1. - let path = |flags: u8, count: u64, named: u64, first: u64| { - move |w: &mut Encoder<'_>| { - w.varint(count).unwrap(); - for hop in 0..named { - w.varint(first + hop).unwrap(); - w.varint(0u64).unwrap(); - } - w.u8(flags); - w.u8(0x80); - w.varint(1u64).unwrap(); - } - }; - let start = |node: u64, offer: Box)>| { - forge(ROUTE_START, move |w| { - w.varint(node).unwrap(); - // Prefix ID 0, an empty suffix, and not exact. - w.varint(0u64).unwrap(); - w.varint(0u64).unwrap(); - w.u8(0); - offer(w); - }) + encode_claim(&mut Encoder::new(&mut buf, form), &claim(relays)).map(|()| buf) }; - let hops = |count: u64, first: u64| -> Arc<[route::path::Hop]> { - (first..first + count) - .map(|node| route::path::Hop { node, session: 0 }) - .collect() - }; - let named = |node, path| Refusable::RouteStart { - node, - prefix: 0, - suffix: Some(Path::empty()), - exact: false, - path, - }; - let over = route::MAX_HOPS as u64 + 1; - // What the sender only forwarded is refused, the message decoded all the same and - // its path with it, so the receiver withdraws the route and keeps the stream. - let refused = [ - ( - start(1, Box::new(path(0, over, over, 1))), - named(1, hops(over, 1)), - Refusal::Hops(over), - ), - // Far past the limit: only the hops up to one past it are kept. - ( - start(1, Box::new(path(0, 4 * over, 4 * over, 1))), - named(1, hops(over, 1)), - Refusal::Hops(4 * over), - ), - ( - start(1, Box::new(path(0, 1, 1, 0))), - named(1, hops(1, 0)), - Refusal::Node, - ), - ( - start(0, Box::new(path(0, 1, 1, 1))), - named(0, hops(1, 1)), - Refusal::Node, - ), - // A flag no version defines, which may change what follows it. - ( - start(1, Box::new(path(8, 1, 1, 1))), - named(1, hops(1, 1)), - Refusal::Flags(8), - ), - ( - start(1, Box::new(path(0x86, 1, 1, 1))), - named(1, hops(1, 1)), - Refusal::Flags(0x86), - ), - // A suffix no path spells. - ( - forge(ROUTE_START, |w| { - w.varint(1u64).unwrap(); - w.varint(5u64).unwrap(); - w.bytes(b"x//y").unwrap(); - w.u8(0); - path(0, 1, 1, 1)(w); - }), - Refusable::RouteStart { - node: 1, - prefix: 5, - suffix: None, - exact: false, - path: hops(1, 1), - }, - Refusal::Path, - ), - ( - forge(ROUTE_UPDATE, |w| { - w.varint(0u64).unwrap(); - path(8, 1, 1, 1)(w); - }), - Refusable::RouteUpdate { - id: 0, - path: hops(1, 1), - }, - Refusal::Flags(8), - ), - ]; - for (wire, message, reason) in refused { - assert_eq!( - decode_broadcast(&wire, Version::Lite07).unwrap(), - AnnounceBroadcast::Refused { message, reason }, - "{wire:?}" - ); - } + let longest = route::MAX_HOPS as u64 - 1; - // Exact is a boolean. - let wire = forge(ROUTE_START, |w| { - w.varint(1u64).unwrap(); - w.varint(0u64).unwrap(); - w.varint(0u64).unwrap(); - w.u8(2); - path(0, 1, 1, 1)(w); - }); - let res = decode_broadcast(&wire, Version::Lite07); - assert!(matches!(res, Err(DecodeError::InvalidValue)), "{res:?}"); - - // A DEAD has a fixed size: it counts the ROUTE_UPDATEs following it. - let wire = forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 2] { - w.varint(field).unwrap(); - } - w.u8(1); - w.varint(2u64).unwrap(); - }); - assert_eq!( - decode_broadcast(&wire, Version::Lite07).unwrap(), - AnnounceBroadcast::Dead(Dead::Closed { - hop: route::path::Hop { node: 1, session: 1 }, - far: 2, - gone: true, - moved: 2, - }) - ); + let buf = encode(longest).expect("the longest chain"); + let decoded = decode_claim(&mut Decoder::new(&buf, form), 0).expect("the longest chain"); + assert_eq!(decoded.chain.len() as u64, longest); + assert!(encode(longest + 1).is_err()); - let malformed = [ - // No hops at all, and fewer than it counts. - start(1, Box::new(path(0, 0, 0, 1))), - start(1, Box::new(path(0, 3, 1, 1))), - // A byte past a usable offer. - forge(ROUTE_UPDATE, |w| { - w.varint(0u64).unwrap(); - path(0, 1, 1, 1)(w); - w.u8(0); - }), - // A moved offer short of its size. - forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 2] { - w.varint(field).unwrap(); - } - w.u8(1); - w.varint(1u64).unwrap(); - w.varint(4u64).unwrap(); - let prefix = w.prefix_varint(); - path(0, 1, 1, 3)(w); - w.u8(0); - w.fill(prefix).unwrap(); - }), - // A hold carries only its Route ID. - forge(ROUTE_HOLD, |w| { - w.varint(0u64).unwrap(); - w.varint(0u64).unwrap(); - }), - // A DEAD of a kind no version defines, naming Node ID 0, or Gone or More past 1. - forge(DEAD, |w| { - w.varint(2u64).unwrap(); - w.varint(1u64).unwrap(); - }), - forge(DEAD, |w| { - w.varint(DEAD_DRAIN).unwrap(); - w.varint(0u64).unwrap(); - }), - forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 0] { - w.varint(field).unwrap(); - } - w.u8(0); - w.u8(0); - w.varint(0u64).unwrap(); - }), - forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 2] { - w.varint(field).unwrap(); - } - w.u8(2); - w.u8(0); - w.varint(0u64).unwrap(); - }), - forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 2] { - w.varint(field).unwrap(); - } - w.u8(0); - w.u8(2); - w.varint(0u64).unwrap(); - }), - // More moved entries than the body could hold. - forge(DEAD, |w| { - for field in [DEAD_CLOSED, 1, 1, 2] { - w.varint(field).unwrap(); - } - w.u8(1); - w.u8(0); - w.varint(1u64 << 40).unwrap(); - }), - // A floor without its revision, and one with trailing bytes. - forge(ANNOUNCE_FLOOR, |w| w.varint(0u64).unwrap()), - forge(ANNOUNCE_FLOOR, |w| { - w.varint(0u64).unwrap(); - w.varint(1u64).unwrap(); - w.u8(0); - }), - // Trailing bytes after a complete body. - forge(ROUTE_END, |w| { - w.varint(0u64).unwrap(); - w.u8(0); - }), - ]; - for wire in malformed { - assert!(decode_broadcast(&wire, Version::Lite07).is_err(), "{wire:?}"); - } + // One relay more, as only a peer outside the rule sends: every field is one byte. + let mut buf = vec![0, 0, 0, 0, route::MAX_HOPS as u8]; + buf.extend(1..=route::MAX_HOPS as u8); + let refused = decode_claim(&mut Decoder::new(&buf, form), 0); + assert!(matches!(refused, Err(DecodeError::TooMany)), "{refused:?}"); } } diff --git a/rs/moq-net/src/lite/compress.rs b/rs/moq-net/src/lite/compress.rs index 34befc00960..8e6fee3bc09 100644 --- a/rs/moq-net/src/lite/compress.rs +++ b/rs/moq-net/src/lite/compress.rs @@ -120,27 +120,12 @@ impl AnnounceDecoder { Ok(suffix) } - /// The next unassigned id. - pub fn next(&self) -> u64 { - self.live.next - } - - /// Assign the next id to a claim at `path` that no ANNOUNCE_START carries: an edit of - /// the stream's prefixes presents a live claim there. - pub fn insert(&mut self, path: Path) -> u64 { - let id = self.live.next; - self.live.next += 1; - self.live.suffixes.insert(id, path); - id - } - /// The id the last start assigned. pub fn last(&self) -> u64 { self.live.next.saturating_sub(1) } - /// The suffix of the live id an ANNOUNCE_UPDATE or ANNOUNCE_RESTART names, which - /// stays live. An id whose path was refused has none. + /// The suffix of the live id an ANNOUNCE_UPDATE names, which stays live. An id whose path was refused has none. pub fn get(&self, id: u64) -> Result { self.live.suffix(id).cloned() } @@ -264,21 +249,6 @@ impl AnnounceEncoder { (Some(id), path) } - /// The next unassigned id. - pub fn next(&self) -> u64 { - self.live.next - } - - /// Assign the next id to a claim at `path` without an ANNOUNCE_START: an edit of the - /// stream's prefixes presents a live claim there. - pub fn insert(&mut self, path: Path) -> u64 { - let id = self.live.next; - self.live.next += 1; - self.heads.insert(raw_parts(&path), id); - self.live.suffixes.insert(id, path); - id - } - /// An ANNOUNCE_END for a live `id`. pub fn end(&mut self, id: u64) { if !self.version.has_announce_compression() { @@ -497,12 +467,6 @@ mod tests { // A head ending inside an escape that nothing completes is refused, its id assigned. assert_eq!(decoder.start(Some(path(3, 2, ""))).unwrap(), None); assert_eq!(decoder.last(), 3); - - // A claim an edit inserts is indexed the same way, so its end leaves nothing behind. - let mut encoder = AnnounceEncoder::new(VERSION); - let id = encoder.insert(Path::from_static(r"a\/b")); - encoder.end(id); - assert!(encoder.heads.children.is_empty()); } #[test] @@ -527,12 +491,12 @@ mod tests { /// A compressed stream pinned byte for byte. `js/net/src/lite/announce.test.ts` decodes /// this hex too. - const GOLDEN: &str = "001400000a726f6f6d2f612f63616d00016100000000000d0102036d6963000161000000000203000000010101000b0201016200016100000000"; + const GOLDEN: &str = "001600000a726f6f6d2f612f63616d01610000000000ff00000f0102036d696301610000000000ff0002070000000000ff0001020100000d0201016201610000000000ff00"; #[cfg(feature = "async")] fn golden() -> Vec { use crate::fuzz::Announced; - // Lite-07 names a route instead of a hop chain, so none travels. + // No relay announced these again, so their chains are empty. vec![ Announced::Start(Path::from_static("room/a/cam"), vec![]), Announced::Start(Path::from_static("room/a/mic"), vec![]), @@ -553,7 +517,7 @@ mod tests { /// The literal lite-07 stream `js/net` writes for the same announcements, never picking a /// base; `js/net/src/lite/announce.test.ts` pins its encoder to it. - const JS_LITERAL: &str = "001400000a726f6f6d2f612f63616d00016100000000001400000a726f6f6d2f612f6d69630001610000000002030000000101010010000006726f6f6d2f6200016100000000"; + const JS_LITERAL: &str = "001600000a726f6f6d2f612f63616d01610000000000ff00001600000a726f6f6d2f612f6d696301610000000000ff0002070000000000ff00010201000012000006726f6f6d2f6201610000000000ff00"; #[test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/lite/corpus.rs b/rs/moq-net/src/lite/corpus.rs index 09ac67dd103..0d21effa508 100644 --- a/rs/moq-net/src/lite/corpus.rs +++ b/rs/moq-net/src/lite/corpus.rs @@ -4,10 +4,8 @@ //! //! Each case is one complete wire input at a negotiated `version` (its handshake name), with //! the outcome both must reach: `decoded`, where our own encoding of the decoded value must -//! equal the input, so a case also pins the value, `refused`, where the input is rejected -//! without asking for more bytes, or `withdrawn`, where a lite-07 route message decodes but its -//! forwarded content is refused, so the receiver withdraws the route or claim and keeps the -//! session (for a DEAD, any route a moved offer names). A fuzz crash on a single moq-lite message belongs here +//! equal the input, so a case also pins the value, or `refused`, where the input is rejected +//! without asking for more bytes. A fuzz crash on a single moq-lite message belongs here //! rather than in `fuzz/regressions/`, so JS replays it too. use crate::coding::{Decode, DecodeError, Decoder, Encode, Form}; @@ -44,7 +42,6 @@ enum Message { enum Expect { Decoded, Refused, - Withdrawn, } /// What a decode came to: our own encoding of what it decoded, as hex, or why it did not. @@ -72,10 +69,7 @@ fn run(case: &Case, data: &[u8]) -> String { }; let decoder = || Decoder::new(data, version.into()); match case.message { - Message::Announce => match super::AnnounceBroadcast::decode_slice(data, version) { - Ok((super::AnnounceBroadcast::Refused { .. }, used)) if used == data.len() => "withdrawn".to_string(), - decoded => outcome(data, version, decoded), - }, + Message::Announce => outcome(data, version, super::AnnounceBroadcast::decode_slice(data, version)), Message::AnnounceInit => { let mut r = decoder(); let decoded = super::AnnounceInit::decode_within(&mut r, version, case.budget.unwrap_or(usize::MAX)); @@ -116,7 +110,6 @@ fn corpus() { let want = match case.expect { Expect::Decoded => case.hex.clone(), Expect::Refused => "refused".to_string(), - Expect::Withdrawn => "withdrawn".to_string(), }; let got = run(case, &unhex(&case.hex)); if got != want { diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 0c67be0ef61..f8f6bd07ec0 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -98,12 +98,9 @@ pub struct Datagrams<'a> { pub broadcast: Path, /// The instance the subscriber expects; see [`crate::origin::Route::instance`]. pub instance: Option, - /// The Node ID of the origin that serves the request, or 0 for whichever the - /// publisher selects. - pub node: u64, - /// How many leading segments of the broadcast path make up the prefix of the route - /// the request follows (lite-07); 0 with no node named. - pub depth: u64, + /// The forwarding node whose claim the request follows, or `None` for whichever the + /// publisher selects. Lite07+ only. + pub node: Option, pub track: Cow<'a, str>, /// The subscriber's priority. pub priority: i8, @@ -117,7 +114,6 @@ impl Datagrams<'_> { broadcast: self.broadcast, instance: self.instance, node: self.node, - depth: self.depth, track: Cow::Owned(self.track.into_owned()), priority: self.priority, } @@ -134,7 +130,7 @@ impl<'a> Message<'a> for Datagrams<'a> { let id = r.varint()?; let broadcast = Path::decode(r, version)?; let instance = super::instance::decode_pin(r, version)?; - let (node, depth) = super::instance::decode_node(r, version, &broadcast)?; + let node = super::instance::decode_node(r, version)?; let track = Cow::Borrowed(r.str()?); let priority = super::priority::from_wire(r.u8()?); Ok(Self { @@ -142,7 +138,6 @@ impl<'a> Message<'a> for Datagrams<'a> { broadcast, instance, node, - depth, track, priority, }) @@ -155,7 +150,7 @@ impl<'a> Message<'a> for Datagrams<'a> { w.varint(self.id)?; self.broadcast.encode(w, version)?; super::instance::encode_pin(w, version, self.instance.as_ref())?; - super::instance::encode_node(w, version, self.node, self.depth)?; + super::instance::encode_node(w, version, self.node)?; w.string(&self.track)?; w.u8(super::priority::to_wire(self.priority)); Ok(()) @@ -327,8 +322,10 @@ mod test { id: 7, broadcast: Path::from_static("room/alice"), instance: None, - node: 0x7a3f, - depth: 0, + node: Some(crate::route::NodeId { + relay: 0x7a3f, + start: 9, + }), track: "audio".into(), priority: -3, }; @@ -336,7 +333,13 @@ mod test { let (decoded, _) = Datagrams::decode_slice(&buf, Version::Lite07).unwrap(); assert_eq!(decoded.id, 7); assert_eq!(decoded.broadcast, request.broadcast); - assert_eq!(decoded.node, 0x7a3f); + assert_eq!( + decoded.node, + Some(crate::route::NodeId { + relay: 0x7a3f, + start: 9 + }) + ); assert_eq!(decoded.track, "audio"); assert_eq!(decoded.priority, -3); assert!(matches!( diff --git a/rs/moq-net/src/lite/fetch.rs b/rs/moq-net/src/lite/fetch.rs index 0ef400e8d5d..b5fa9c1d103 100644 --- a/rs/moq-net/src/lite/fetch.rs +++ b/rs/moq-net/src/lite/fetch.rs @@ -16,12 +16,9 @@ pub struct Fetch<'a> { /// The instance the subscriber expects; see [`crate::origin::RouteInfo::instance`]. /// Lite07+ only. pub instance: Option, - /// The Node ID of the origin that serves the request, or 0 for whichever the + /// The forwarding node whose claim the request follows, or `None` for whichever the /// publisher selects. Lite07+ only. - pub node: u64, - /// How many leading segments of the broadcast path make up the prefix of the route - /// the request follows (lite-07); 0 with no node named. - pub depth: u64, + pub node: Option, pub track: Cow<'a, str>, pub priority: i8, /// Reader freshness budget. Lite07+ only; omission uses the publisher's max age alone. @@ -41,7 +38,6 @@ impl Fetch<'_> { broadcast: self.broadcast, instance: self.instance, node: self.node, - depth: self.depth, track: Cow::Owned(self.track.into_owned()), priority: self.priority, max_delay: self.max_delay, @@ -64,7 +60,7 @@ impl<'a> Message<'a> for Fetch<'a> { let broadcast = Path::decode(r, version)?; let instance = super::instance::decode_pin(r, version)?; - let (node, depth) = super::instance::decode_node(r, version, &broadcast)?; + let node = super::instance::decode_node(r, version)?; let track = Cow::Borrowed(r.str()?); let priority = super::priority::from_wire(r.u8()?); let max_delay = match version.has_fetch_max_delay() { @@ -86,7 +82,6 @@ impl<'a> Message<'a> for Fetch<'a> { broadcast, instance, node, - depth, track, priority, max_delay, @@ -106,7 +101,7 @@ impl<'a> Message<'a> for Fetch<'a> { self.broadcast.encode(w, version)?; super::instance::encode_pin(w, version, self.instance.as_ref())?; - super::instance::encode_node(w, version, self.node, self.depth)?; + super::instance::encode_node(w, version, self.node)?; w.string(&self.track)?; w.u8(super::priority::to_wire(self.priority)); match version.has_fetch_max_delay() { @@ -140,8 +135,7 @@ mod test { fn fetch_sample() -> Fetch<'static> { Fetch { instance: None, - node: 0, - depth: 0, + node: None, broadcast: Path::from_static("room"), track: Cow::Borrowed("video"), priority: 3, @@ -190,9 +184,18 @@ mod test { #[test] fn fetch_node_roundtrips_only_on_lite07() { let mut msg = fetch_sample(); - msg.node = 0x7a3f; - assert_eq!(fetch_roundtrip(Version::Lite07, &msg).node, 0x7a3f); - assert_eq!(fetch_roundtrip(Version::Lite06, &msg).node, 0); + msg.node = Some(crate::route::NodeId { + relay: 0x7a3f, + start: 9, + }); + assert_eq!( + fetch_roundtrip(Version::Lite07, &msg).node, + Some(crate::route::NodeId { + relay: 0x7a3f, + start: 9 + }) + ); + assert_eq!(fetch_roundtrip(Version::Lite06, &msg).node, None); } #[test] diff --git a/rs/moq-net/src/lite/instance.rs b/rs/moq-net/src/lite/instance.rs index 4bc7d9dbe7a..21c4c666b55 100644 --- a/rs/moq-net/src/lite/instance.rs +++ b/rs/moq-net/src/lite/instance.rs @@ -1,6 +1,7 @@ use crate::{ - Instance, Path, + Instance, coding::{DecodeError, Decoder, EncodeError, Encoder}, + route::NodeId, }; use super::Version; @@ -38,33 +39,36 @@ pub(super) fn decode_pin(r: &mut Decoder<'_>, version: Version) -> Result