diff --git a/doc/.vitepress/config.ts b/doc/.vitepress/config.ts index dc6a49fba92..7a723c2fb8c 100644 --- a/doc/.vitepress/config.ts +++ b/doc/.vitepress/config.ts @@ -119,6 +119,7 @@ export default defineConfig({ { text: "moq-lite", link: "/concept/moq-lite" }, { text: "hang", link: "/concept/hang" }, { text: "Audio jitter", link: "/concept/audio-jitter" }, + { text: "Compressed tracks", link: "/concept/compression" }, { text: "Stats", link: "/concept/stats" }, { text: "Standards", link: "/concept/standard" }, { diff --git a/doc/bin/relay/http.md b/doc/bin/relay/http.md index 110933dad63..ccf467005e8 100644 --- a/doc/bin/relay/http.md +++ b/doc/bin/relay/http.md @@ -45,8 +45,14 @@ listen = "127.0.0.1:9101" Prometheus text: payload bytes, frames, groups, announces, subscriptions, and viewers split by `tier` and `role`; requests and sessions by `tier`; and accept-loop counters per TCP listener. Payload counters accumulate for the -node's lifetime and leave out the stats feed's own traffic. Host CPU and memory -belong to a node exporter. +node's lifetime and leave out the stats feed's own traffic. Every counter fed by +sessions and requests, through the wire and control bytes below, counts only +while [stats](/bin/relay/config#stats) are enabled. Host CPU and memory belong +to a node exporter. + +`moq_relay_inflated_bytes_total` counts the bytes the relay inflated from +[compressed tracks](/concept/compression) for readers that cannot carry +compression, once per group however many share the copy. `moq_relay_wire_tx_bytes_total` and `moq_relay_wire_rx_bytes_total` sum the per-session [transport counters](/concept/stats#sessions) by `tier`, including diff --git a/doc/concept/compression.md b/doc/concept/compression.md new file mode 100644 index 00000000000..b1b887bdf74 --- /dev/null +++ b/doc/concept/compression.md @@ -0,0 +1,65 @@ +--- +title: Compressed tracks +description: When to compress a track, what each protocol version receives, and what it costs a relay +--- + +# Compressed tracks + +A publisher can mark a track compressed. Each group then travels as one DEFLATE +stream ([moq-flate](/draft/moq-flate)): every frame compresses against the +earlier frames of its group, and the next group starts a fresh window. +Applications still write and read plain frames. A reader whose session cannot +carry compression gets an inflated copy from the relay. + +```rust +let info = moq_net::track::Info::default().with_compress(true); +``` + +```ts +const track = broadcast.createTrack("state.json", { compress: true }); +``` + +## When to set it + +Set it on small, repetitive data whose frames repeat each other within a group: +JSON state, catalogs, logs. hang's `catalog.json` and a relay's +[stats](/concept/stats) tracks already set it, and a [JSON track](/lib/rs/moq-json) +should too. + +Leave it off for encoded media and anything else already compressed or +encrypted. DEFLATE cannot shrink those, and a relay would still inflate them for +every group a plain reader asks for. + +## What each session receives + +| Session | Receives | +| --- | --- | +| moq-lite 07 (`moq-lite-07-wip`) | The compressed bytes and the flag | +| moq-transport, when both peers offer the [Flate extension](/draft/moq-flate) | The compressed bytes and the flag | +| moq-lite 01 through 06, and moq-transport without the extension | The inflated frames, without the flag | + +moq-lite 07 is still opt-in, so compressed bytes cross a hop only where both +ends list `moq-lite-07-wip`. Sessions on the default versions, and relay links +among them, carry the inflated frames. Only Rust offers the moq-transport +extension, so a JavaScript or third-party moq-transport peer reads the +inflated copy. A received track's `compress` flag says which form arrived. A +datagram compresses alone, with a fresh window. + +## Cost on the relay + +A relay never compresses. It stores a compressed group as received, forwards +those bytes to sessions that carry the flag, and inflates the group once, on +the first plain read. Every later plain reader of that group, on any session +and any version, shares that copy, so a thousand moq-lite 06 viewers cost one +inflate. The copy counts against the relay's [cache](/bin/relay/config#cache) +like the stored bytes and is dropped with its group. + +Each compressed frame declares its inflated size, which meets the same group +and cache limits as a plain frame's before any inflate starts. Output that +does not match the declared size fails the group. With +[stats](/bin/relay/config#stats) enabled, `moq_relay_inflated_bytes_total` on +[`/metrics`](/bin/relay/http#get-metrics) and the `inflated` +[counter](/concept/stats) report the bytes the relay inflated. + +The publisher pays for compression, holding a DEFLATE encoder of about +256 KiB while a compressed group is open. diff --git a/doc/concept/hang.md b/doc/concept/hang.md index c1c73d076b0..f0c4cdacc3e 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -20,7 +20,7 @@ payloads follow [moq-e2ee](/draft/moq-e2ee). See [Encryption](#encryption). `catalog.json` is a JSON track listing the renditions of each media kind and the decoder config for each. It updates live as tracks come and go, and is a -[compressed track](/concept/moq-lite#subscriptions), so a reader sees plain JSON +[compressed track](/concept/compression), so a reader sees plain JSON whether or not its session carries the compression. ```json diff --git a/doc/concept/index.md b/doc/concept/index.md index 4fbb73aee35..8c63cb0bf6b 100644 --- a/doc/concept/index.md +++ b/doc/concept/index.md @@ -37,6 +37,7 @@ watched at 100 ms by one viewer and 10 s by another. - [moq-lite](/concept/moq-lite): the pub/sub protocol, discovery, path patterns, subscriptions, and congestion behavior. - [hang](/concept/hang): the media catalog, containers, encryption, and how to extend both. - [Audio jitter](/concept/audio-jitter): how a receiver sizes its audio playout target from arrival timing. +- [Compressed tracks](/concept/compression): when to compress a track, what each protocol version receives, and the relay's cost. - [Stats](/concept/stats): the traffic counters a relay publishes as broadcasts, and how to read them. - [Standards](/concept/standard): how this relates to the IETF moq-transport, MSF, LOC, and this project's own drafts, including [e2ee](/draft/moq-e2ee). - [Use cases](/concept/use-case/): MoQ compared with HLS/DASH, RTMP/SRT, WebRTC, and used for AI. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index c5c36bf35a1..ccdd5ed442c 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -340,15 +340,11 @@ are not checked. Rust relays preserve them across moq-lite 07 when both peers negotiate the [ietf extension](/draft/moq-ietf), which carries their origin and keeps them unchecked. A moq-lite peer without it receives that track untimed. -A publisher may compress a track, which pays off for repetitive data such as -JSON and not for media. Each group's frames become one DEFLATE stream -([moq-flate](/draft/moq-flate)), and a datagram -compresses alone. Only the work-in-progress moq-lite 07 carries the compressed -bytes. A relay forwards them as received and inflates each group once for every -other subscriber, moq-transport included, so readers always see the original -frames. Rust and JavaScript publish compressed tracks by setting `compress: true` -on the track's info. Application writes stay synchronous and readers receive plain -payloads; compression is useful for repetitive data, not already compressed media. +A publisher may [compress](/concept/compression) a track, which pays off for +repetitive data such as JSON and not for media. Each group's frames become one +DEFLATE stream, which only the work-in-progress moq-lite 07 carries. A relay +forwards it as received and inflates each group once for every other +subscriber, moq-transport included, so readers always see the original frames. A relay cancels its upstream subscription once nobody subscribes, but keeps its copy of the track for 30 seconds after the last reader leaves, so a returning diff --git a/doc/concept/stats.md b/doc/concept/stats.md index ff368f6ca52..bd1c35b8373 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -487,7 +487,7 @@ defaults a missing field to zero, so it can read an older relay. ## Encoding Every stats track is a [moq-json](/lib/rs/moq-json) snapshot track that sets -the track's [compressed](/concept/moq-lite#subscriptions) flag, so a session +the track's [compressed](/concept/compression) flag, so a session that can signal compression carries it DEFLATEd and every other reads an inflated copy. Stats frames change little between ticks, so the deltas and compression together cost a fraction of the full objects' bytes. diff --git a/quest/m1/README.md b/quest/m1/README.md index a4da03dde8d..4b517e225dd 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -143,7 +143,6 @@ removed). - [Aborted copies don't hold an end open](/quest/m1/settled-abort.md) - a track's declared end settles when a fetched copy finishes a group whose live copy was cut or evicted - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for a per-rendition `hls` field - [HLS recorder target](/quest/m1/hls-record-target.md) - the moq-cli HLS recorder takes its target duration from the declared `hls` duration -- [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure - [Smoke token subject](/quest/m1/smoke-token-subject.md) - condition: grant subject ships; then the release smoke test signs with `--subject` diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index feb7890423f..bc0254a9327 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -11,7 +11,7 @@ to migrate. Non-goals: redesigning surfaces that already have their own quest ([subscribe ranges](/quest/m1/subscribe-ranges/README.md), [archives](/quest/m1/archive/README.md), -[compressed tracks](/quest/m1/compress/README.md), +[compressed tracks](/doc/concept/compression.md), [A/V clock](/quest/m1/av-clock.md)), and inherited debt that a later quest already reshapes. @@ -42,7 +42,7 @@ Rules every child follows: bullet says how to migrate. The binary-to-flate fold was followed by flate's removal in the -[compression migration](/quest/m1/compress/README.md), so moq-flate, `@moq/flate`, and +[compression migration](https://github.com/moq-dev/moq/pull/7046), so moq-flate, `@moq/flate`, and `moq-mux::binary` have no API left to audit. hang's `Archive::replay_epoch` went with the root `archive` section in catalog HLS. diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md deleted file mode 100644 index 26606334617..00000000000 --- a/quest/m1/compress/README.md +++ /dev/null @@ -1,84 +0,0 @@ -# [S] Compressed tracks in moq-net - -## Goal - -A publisher sets `compress: true` on a track and moq-net DEFLATEs each group -with the moq-flate format. Relays cache and forward the compressed bytes, and -serve one shared inflated copy, built on demand, to any peer whose protocol -cannot signal compression. One `catalog.json` track replaces `catalog.json` -plus `catalog.json.z`, and the same holds for moq-stats and timelines. - -Boundaries: - -- Only the original publisher compresses, by opting in. A relay never - compresses; it only inflates for egress that cannot carry the flag. -- Non-goals: other codecs, per-frame compression opt-out, and compression of - control messages. - -## Plan - -Decided with the maintainer on 2026-10-17. This reverses the earlier rule -that compression stays invisible to moq-net -([#1962](https://github.com/moq-dev/moq/pull/1962) removed a per-frame -`compress` flag to follow a spec change; the deleted m2 flate bindings quest kept it -out). The difference now is the group-scoped window: frames compress against -earlier frames of their group, which is where catalogs and stats gain, and -built-in signaling avoids doubling every compressed track's name. - -Every interview prompt and the selected answer (✅) are in the planning PR. - -- **API:** `compress: bool` on `track::Info` (Rust) and `Info` (JS). One - codec, no enum; another algorithm would be a breaking change, and none is - planned. -- **Format:** moq-flate as it is today: raw DEFLATE per group, a sync flush - per frame with the `00 00 ff ff` marker dropped, a fresh window per group. -- **Uncompressed size on the wire.** Each compressed frame declares its - inflated size, so `frame::Info.size` stays the size applications see and a - relay can write an IETF payload length before inflating. Inflated output - that differs from the declared size is an error. A zip bomb then costs no more than a plain frame - of the declared size, so there is no separate inflate cap constant: the - declared size meets the same group and pool limits as a plain frame's - before any inflate starts, and inflating is incremental, billed as output - is produced, never preallocated from the declaration. -- **One stored form.** The model stores what arrived, or what the local - producer compressed. A plain reader (an in-process consumer, or egress to a - peer that cannot signal compression) reads one inflated copy per group, - built on first demand, shared across readers, billed to the cache pool, and - dropped with its group. A thousand old-lite viewers cost one inflate. -- **Signaling:** lite-07 TrackInfo carries the codec id and the frame header the - size; IETF carries them only - after both peers advertise a setup parameter, because unknown track - properties are discarded. Lite-01..06 and IETF peers without the - parameter get the inflated copy, with no flag. A sealed compression - declaration is preserved, so delivery is refused when plain fallback would - remove it. -- **Ranges.** Compressed tracks are not special: every subscription, new or - resumed, starts at the beginning of a group, and one resuming from another - route may take the group's start from that route's cached prefix - (maintainer, on [moq-dev/moq#6465](https://github.com/moq-dev/moq/pull/6465)). Application - ranges and fetches name whole groups, so a compressed group always - inflates from a prefix its requester holds. -- **Specs:** draft-lcurley-moq-flate keeps the codec and becomes the IETF - extension; draft-lcurley-moq-lite specifies the lite-07 field and size and - references it for the codec. -- **moq-flate and @moq/flate fold into moq-net and js/net.** The snapshot and - stream track modes go away: a compressed track replaces them. moq-json and - `@moq/json` drop `Config::compression` (the track flag replaces it, on by - default for JSON tracks), and - `moq-mux::binary` is deleted: opaque bytes are a plain track. Decided on - review of the planning PR. -- **Datagrams** compress alone with a fresh window, never against another - datagram; lite allows one datagram per group for this reason. -- Compression gates the lite-07 cut, so lite-07 ships with it. - -This README owns the end-to-end proof and the guide once every child lands: - -- A Rust publisher's compressed `catalog.json` reaches a JS player over - lite-07 compressed, and a lite-06 and a plain IETF subscriber through - moq-relay inflated, from one inflate on the relay. -- A short guide under `doc/` on when to set `compress`, what each protocol - version receives, and the cost on the relay. - -## Related - -- [Front eviction](/quest/m1/unbounded-groups/front-eviction.md) - a compressed group's evicted prefix must refill before a reader can inflate past it diff --git a/quest/m1/release-audit/README.md b/quest/m1/release-audit/README.md index 040306f9d8e..dedbe4dcd53 100644 --- a/quest/m1/release-audit/README.md +++ b/quest/m1/release-audit/README.md @@ -92,7 +92,6 @@ work, because obs-moq ships on its own schedule. - [JS subscription ranges](/quest/m1/subscribe-ranges/js.md) - range lists and frame offsets build on the bounds fixed here - [OBS video source](/quest/m2/obs-moq-video/source.md) - the decoder replacement keeps the timing and EOF behavior fixed here -- [Compressed tracks](/quest/m1/compress/README.md) - application migration has an existing owner - [Measured release performance](/quest/m1/release-perf/README.md) - existing paired benchmark regressions and their confirmation runs - [Transport performance audit](/quest/m2/audit-perf.md) - congestion-control coverage remains outstanding - [Binding timestamps](/quest/m1/binding-timestamps.md) - exact timestamps across language APIs diff --git a/quest/m1/unbounded-groups/README.md b/quest/m1/unbounded-groups/README.md index 01fa7bbf9af..eaa85e35bb4 100644 --- a/quest/m1/unbounded-groups/README.md +++ b/quest/m1/unbounded-groups/README.md @@ -99,7 +99,7 @@ Decided 2026-10-16 (maintainer interview): - JS is a separate quest. Docs change inline: the lite draft, `doc/concept`, the relay cache docs, the JSON and moq-net compression docs, and the e2ee draft's 32 MiB interop cap. The - [m1 compression migration](/quest/m1/compress/README.md) deleted the flate packages. There is no new page. + [m1 compression migration](https://github.com/moq-dev/moq/pull/7046) deleted the flate packages. There is no new page. The refill API is the `track::Requests` fill (`track::Fill`). A handler serves a range by writing into a group producer bounded to that range, the same API as a live write, so an diff --git a/quest/m1/unbounded-groups/front-eviction.md b/quest/m1/unbounded-groups/front-eviction.md index bf7b76e4b8b..0c586219955 100644 --- a/quest/m1/unbounded-groups/front-eviction.md +++ b/quest/m1/unbounded-groups/front-eviction.md @@ -84,11 +84,11 @@ See the [epic](/quest/m1/unbounded-groups/README.md) for the decisions. object is `Evicted`. - Downstream encoders that roll groups by the removed constants (moq-json, moq-mux TS, moq-stats) keep their own local roll triggers if they still - need one. The [m1 compression migration](/quest/m1/compress/README.md) + need one. The [m1 compression migration](https://github.com/moq-dev/moq/pull/7046) deleted moq-flate; recheck the surviving JSON stream budget and track compression paths instead of retaining a deleted helper's cap. - Compressed groups keep the existing prefix-before-inflate contract - ([compressed tracks](/quest/m1/compress/README.md)). Today + ([compressed tracks](/doc/concept/compression.md)). Today `GroupState::inflate` refuses a nonzero cached offset. Front eviction must refill the needed compressed prefix before inflation or retain equivalent decoder state, with compressed storage, the shared inflated copy, and diff --git a/quest/m1/unbounded-groups/js.md b/quest/m1/unbounded-groups/js.md index 73ed12c8075..8aec7a5ab35 100644 --- a/quest/m1/unbounded-groups/js.md +++ b/quest/m1/unbounded-groups/js.md @@ -28,7 +28,7 @@ holes. The chunked frame read and the byte-offset wire mirror moved to `Evicted`. - Update `js/json` and its tests, which lean on the removed constants, and the compression paths now in `js/net`. The - [m1 compression migration](/quest/m1/compress/README.md) deleted `js/flate`. + [m1 compression migration](https://github.com/moq-dev/moq/pull/7046) deleted `js/flate`. - If [Rust-backed @moq/net](/quest/m2/rs2ts/README.md) is adopted first, Rust's caps and eviction apply and this quest is done. diff --git a/quest/m2/e2ee/rust-publish.md b/quest/m2/e2ee/rust-publish.md index 13e6442f52c..c6448d21378 100644 --- a/quest/m2/e2ee/rust-publish.md +++ b/quest/m2/e2ee/rust-publish.md @@ -27,7 +27,7 @@ in advance, so it does not wait on logical role, then put media roles, codecs, quality, timelines, and custom-track mappings only inside the encrypted catalog. - Encrypt the single Hang `catalog.json` left by the - [m1 compression migration](/quest/m1/compress/README.md), and encrypt or + [m1 compression migration](https://github.com/moq-dev/moq/pull/7046), and encrypt or suppress the MSF catalog. Set logical `compress` on protected catalog tracks; the [e2ee wrapper](/quest/m2/net-wrap/e2ee.md) compresses before encryption. Retain ordinary plaintext publication unchanged outside E2EE mode. diff --git a/quest/m2/net-wrap/README.md b/quest/m2/net-wrap/README.md index 36260ba5259..2e3a36846a2 100644 --- a/quest/m2/net-wrap/README.md +++ b/quest/m2/net-wrap/README.md @@ -11,7 +11,7 @@ and the CLI can be handed an encrypted broadcast or track and publish or consume it unchanged. Rust and JS use the same names. Compression is not a wrapper: it moves into moq-net as a track flag -([Compressed tracks](/quest/m1/compress/README.md)), which deletes +([Compressed tracks](/doc/concept/compression.md)), which deletes moq-flate, so moq-flate is out of scope. Non-goals: @@ -77,4 +77,3 @@ above. ## Related - [E2EE](/quest/m2/e2ee/README.md) - the first wrapper, which publishes and consumes through these traits -- [Compressed tracks](/quest/m1/compress/README.md) - compression moves into moq-net as a track flag, so it is not a wrapper diff --git a/quest/m2/net-wrap/e2ee.md b/quest/m2/net-wrap/e2ee.md index c11a6b5071c..50a50dbc0f1 100644 --- a/quest/m2/net-wrap/e2ee.md +++ b/quest/m2/net-wrap/e2ee.md @@ -30,7 +30,7 @@ the reverse (decided 2026-10-20, maintainer): - `track::Info.compress` is logical. Ciphertext doesn't compress, so the wrapper compresses each group, and each datagram alone with a fresh window, with moq-net's - [track compression](/quest/m1/compress/README.md) before AEAD, creates the + [track compression](/doc/concept/compression.md) before AEAD, creates the physical track uncompressed, and inflates after decryption. Sessions drop a sealed datagram past the transport's datagram size as they drop an oversized plaintext one, so document that the AEAD tag and any compression @@ -53,7 +53,7 @@ the reverse (decided 2026-10-20, maintainer): catalog track is itself compressed, so a subscriber would need the flag before it could inflate the catalog that carries it. The [E2EE epic](/quest/m2/e2ee/README.md) also keeps catalog formats out of - moq-e2ee, and the [compression migration](/quest/m1/compress/README.md) dropped hang's + moq-e2ee, and the [compression migration](https://github.com/moq-dev/moq/pull/7046) dropped hang's `compression` field. The subscriber needs the flag before inflating, without changing moq-net's `track(name)`; propose the encoding in the PR. Record it in `draft-lcurley-moq-e2ee.md`, replacing the Catalogs section's @@ -91,7 +91,3 @@ and each compressed object's authenticated inflated size. ## Required - [moq-net traits](/quest/m2/net-wrap/traits.md) - the traits this implements - -## Related - -- [Compressed tracks](/quest/m1/compress/README.md) - the per-group compression the wrapper applies before AEAD diff --git a/quest/m2/net-wrap/mux.md b/quest/m2/net-wrap/mux.md index b84f9298b47..b2a950c381d 100644 --- a/quest/m2/net-wrap/mux.md +++ b/quest/m2/net-wrap/mux.md @@ -17,7 +17,7 @@ exporter reads one, without knowing. `import/`), `catalog/`, `timeline.rs`, `json.rs`, `source.rs`, and the TS exporter under `container/ts`. About 250 type references across these modules. -- The [m1 compression migration](/quest/m1/compress/README.md) deleted +- The [m1 compression migration](https://github.com/moq-dev/moq/pull/7046) deleted `moq-mux::binary`; opaque bytes use plain tracks, so there is no binary helper to convert here. - Capture: `moq_video::encode::Producer::new` takes a concrete diff --git a/quest/m2/release/migrate-audit.md b/quest/m2/release/migrate-audit.md index cd78823366f..0b977ffa70d 100644 --- a/quest/m2/release/migrate-audit.md +++ b/quest/m2/release/migrate-audit.md @@ -27,7 +27,7 @@ m1 quest on 2026-10-22. `MIGRATE.md`. Known gaps: breaking releases cut after the 2026-09-23 train have no transition section yet (moq-json 0.4 -> 0.5 and possibly moq-audio and moq-video), because their breaks predate the - backfill's merge base. The [compression migration](/quest/m1/compress/README.md) + backfill's merge base. The [compression migration](https://github.com/moq-dev/moq/pull/7046) deleted moq-flate before this cut: audit the migration from its published API to ordinary tracks with `compress`, rather than promising a new moq-flate transition release. diff --git a/quest/m2/stats/README.md b/quest/m2/stats/README.md index 5ee7840c6be..98046d562b1 100644 --- a/quest/m2/stats/README.md +++ b/quest/m2/stats/README.md @@ -85,7 +85,7 @@ kind. [#2733](https://github.com/moq-dev/moq/issues/2733)-style counters land. - **Encoding**: cumulative counters about once a second through `moq_json::snapshot` on one track with `compress: true`, produced whenever - stats are enabled. The [m1 compression migration](/quest/m1/compress/README.md) + stats are enabled. The [m1 compression migration](https://github.com/moq-dev/moq/pull/7046) removed the `.z` siblings and kept merge-patch deltas on the single track. An unsubscribed stats track never leaves the process. Gauges are carried but never summed. - **On main.** Every change is additive: optional sections on diff --git a/quest/m2/stats/js.md b/quest/m2/stats/js.md index fb37c330526..bea3cad59d3 100644 --- a/quest/m2/stats/js.md +++ b/quest/m2/stats/js.md @@ -14,7 +14,7 @@ echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. `bytes`, `keyframes`). Add drops and the target bitrate. - Fold them into the stats snapshot keyed by rendition ID, and write it through the `@moq/json` snapshot producer on one track with - `compress: true`, matching the [m1 compression migration](/quest/m1/compress/README.md). + `compress: true`, matching the [m1 compression migration](https://github.com/moq-dev/moq/pull/7046). A `stats` attribute enables it. - `transport` carries PROBE rtt only, because `WebTransport.getStats()` returns nothing useful in Chromium or Firefox today. diff --git a/quest/m3/ladder/fetch.md b/quest/m3/ladder/fetch.md index 7d80f143ec5..fdd9e90adb3 100644 --- a/quest/m3/ladder/fetch.md +++ b/quest/m3/ladder/fetch.md @@ -21,7 +21,7 @@ manually fetchable, and cache hits are untouched. Catalog mutations publish full snapshots (`rs/moq-mux/src/catalog/producer.rs`). The -[compression migration](/quest/m1/compress/README.md) removed the HANGZ +[compression migration](https://github.com/moq-dev/moq/pull/7046) removed the HANGZ sibling; coalesce every rung state change from one controller iteration into a single publication of each supported catalog, and make a later source catalog snapshot compose with current generated-rung state diff --git a/quest/m3/teleop-mavlink.md b/quest/m3/teleop-mavlink.md index e1d76e2638c..2ba206ede85 100644 --- a/quest/m3/teleop-mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -75,7 +75,7 @@ in one ordered group. Note the scope in recoverable after a lag or a reconnect, so these MAVLink services keep relying on their own retransmission across a link drop. -The [compression migration](/quest/m1/compress/README.md) deleted the +The [compression migration](https://github.com/moq-dev/moq/pull/7046) deleted the moq-flate snapshot and stream helpers. Keep these framing rules on plain tracks, setting `compress` when useful, rather than depending on those helpers. diff --git a/quest/m3/teleop-robot.md b/quest/m3/teleop-robot.md index 607fb36b02c..164ff10a63a 100644 --- a/quest/m3/teleop-robot.md +++ b/quest/m3/teleop-robot.md @@ -83,7 +83,7 @@ The framing is where the guarantee lives, not the subscription flags: - The two delivery classes with the group structure and `Info::max_age` each one needs: `moq-json`'s snapshot and stream modes for JSON; plain tracks for opaque bytes, one group per latest value or one bounded ordered group - for the append-log. The [compression migration](/quest/m1/compress/README.md) + for the append-log. The [compression migration](https://github.com/moq-dev/moq/pull/7046) deleted moq-flate's snapshot/stream helpers, so use the track's `compress` flag when compression is useful, not those helpers. - Per-stage timestamp instrumentation, generalised from moq-boy's `status` diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 700a8f74b6f..516d1820468 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -177,6 +177,10 @@ harness = false name = "interop-tail" path = "../../test/interop/clients/rust/tail.rs" +[[example]] +name = "interop-catalog" +path = "../../test/interop/clients/rust/catalog.rs" + [[example]] name = "interop-goaway" path = "../../test/interop/clients/rust/goaway.rs" diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index a188743142a..cc470defdc5 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -458,6 +458,12 @@ fn render_metrics( "Single-frame groups carried over unreliable QUIC datagrams; a subset of groups.", |c| c.datagrams, ); + counter( + &mut out, + "moq_relay_inflated_bytes_total", + "Payload bytes inflated from compressed groups for peers that cannot carry compression, once per group.", + |c| c.inflated, + ); counter( &mut out, "moq_relay_stale_bytes_total", @@ -1432,4 +1438,46 @@ mod tests { "session presence:\n{body}" ); } + + /// Two plain egress sessions reading one compressed group share a single inflate. + #[tokio::test(start_paused = true)] + async fn metrics_count_one_inflate_per_group() { + use moq_net::Timestamp; + use moq_net::stats::{Registry, Tier}; + + let stats = Registry::new(Default::default()); + let origin = moq_tokio::origin::spawn(); + let source = origin.create_broadcast("demo/x").unwrap(); + source.announce(Default::default()).unwrap(); + let track = source + .create_track("catalog.json", timed().with_compress(true)) + .unwrap(); + let payload = format!("{{\"pad\":\"{}\"}}", "abc".repeat(300)); + + let mut readers = Vec::new(); + for session in ["a", "b"] { + let ctx = stats + .tier(Tier::default()) + .session(moq_net::Path::new(session).unwrap()); + let egress = origin.consume().with_stats(ctx); + let bc = egress.request("demo/x", None).await.unwrap(); + readers.push(bc.track("catalog.json").unwrap().subscribe(None).await.unwrap()); + } + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, payload.clone()).unwrap(); + group.finish().unwrap(); + for reader in &mut readers { + let mut group = reader.recv_group().await.unwrap().unwrap(); + assert_eq!(group.read_frame().await.unwrap().unwrap().payload, payload.as_bytes()); + } + + let body = render_metrics(&stats.snapshot(), &[], &[]); + assert!( + body.contains(&format!( + "moq_relay_inflated_bytes_total{{tier=\"\",role=\"publisher\"}} {}", + payload.len() + )), + "one inflated copy:\n{body}" + ); + } } diff --git a/test/interop/README.md b/test/interop/README.md index 21be1f8e3ef..a528116a77c 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -503,6 +503,7 @@ varint.ts the JS side of the varint check, driven by moq-net's tes clients/ rust/audio.rs the Rust subscriber's audio decode via rs/moq-audio (`interop-audio`) rust/tail.rs the finite raw-track client (`interop-tail`) + rust/catalog.rs the compressed-catalog publisher (`interop-catalog`) python/interop.py publish/subscribe via py/moq-rs (import moq) go/main.go publish/subscribe via go/wrapper (import moq-go/moq) cpp/main.cpp publish/subscribe via cpp/moq (find_package(moq-cpp)) @@ -518,6 +519,7 @@ clients/ src/instrument.ts live counts of the platform resources the page holds src/close.ts the refused session, read off `WebTransport.closed` js-native/subscribe.ts subscribe via @moq/net + @moq/hang + the WebTransport polyfill + js-native/catalog.ts the compressed-catalog reader, pinned to one version c/subscribe.c subscribe via rs/moq-c ``` @@ -595,3 +597,9 @@ subscriber reads them. The finite-tail matrix also publishes compressed tracks from Rust and native JS through the relay, in both directions on lite-07 and lite-06. It checks multiple frames in each DEFLATE window, empty frames, the plain fallback and the received track's codec flag. + +The compressed-catalog lane then fans one Rust hang catalog out to three native JS +readers at once, each pinned to lite-07, lite-06, or moq-transport-22 and reading it as +`@moq/watch` does. Only the lite-07 reader sees the flag; the other two share the relay's +inflated copy, so `moq_relay_inflated_bytes_total` must grow by exactly the catalog's +inflated size. The harness enables the relay's `[stats]` and `[internal]` listener for it. diff --git a/test/interop/clients/js-native/catalog.ts b/test/interop/clients/js-native/catalog.ts new file mode 100644 index 00000000000..23a09ba5105 --- /dev/null +++ b/test/interop/clients/js-native/catalog.ts @@ -0,0 +1,57 @@ +/** + * Compressed-catalog interop reader: offer one version, read a hang catalog the way `@moq/watch` + * does, and report whether the track arrived compressed. Only moq-lite-07 carries the flag; every + * other version receives the relay's inflated copy. + * + * node --import tsx catalog.ts URL BROADCAST VERSION + * + * @module + */ +import { strict as assert } from "node:assert"; +import * as Catalog from "@moq/hang/catalog"; +import * as Json from "@moq/json"; +import * as Moq from "@moq/net"; +import { install } from "@moq/web-transport"; + +install(); +console.debug = console.error; +console.info = console.error; +const [url, path, version] = process.argv.slice(2); +if (!url || !path || !version) throw new Error("usage: catalog.ts URL BROADCAST VERSION"); + +const origin = new Moq.Origin.Producer(); +const connection = await Moq.Connection.connect({ + url: new URL(url), + websocket: { enabled: false }, + versions: [version], + consume: origin, +}); +try { + const request = origin.follow(Moq.Path.from(path)); + try { + let broadcast = request.active.peek(); + while (!broadcast) { + await request.active.changed(); + broadcast = request.active.peek(); + } + const track = broadcast.track(Catalog.TRACK).subscribe({ priority: Catalog.PRIORITY.catalog }); + try { + const { compress } = await track.info(); + assert.equal(compress, version === "moq-lite-07-wip", "wrong compression metadata"); + const consumer = new Json.Snapshot.Consumer({ track, schema: Catalog.RootSchema }); + const root = (await consumer.latest())?.value; + assert(root, "catalog ended before a snapshot"); + const video = Object.keys(root.video?.renditions ?? {}).sort(); + const audio = Object.keys(root.audio?.renditions ?? {}).sort(); + console.error(`catalog compress=${compress} video=${video.join(",")} audio=${audio.join(",")}`); + } finally { + track.close(); + } + } finally { + request.close(); + } +} finally { + connection.close(); + origin.close(); +} +process.exit(0); diff --git a/test/interop/clients/rust/catalog.rs b/test/interop/clients/rust/catalog.rs new file mode 100644 index 00000000000..d98f2eeed48 --- /dev/null +++ b/test/interop/clients/rust/catalog.rs @@ -0,0 +1,68 @@ +//! Compressed-catalog interop publisher. The harness acknowledges every reader on stdin. +//! +//! Publishes one hang catalog on `catalog.json`, compressed as every hang publisher does, over +//! moq-lite-07 alone so the relay receives and stores the DEFLATE slices. Prints the catalog +//! group's inflated size, which is what a relay serving plain readers must inflate exactly once. +use anyhow::{Context, ensure}; +use moq_tokio::moq_net; +use tokio::io::AsyncBufReadExt; + +/// Renditions enough for the catalog to compress, and for readers to check what they decoded. +const CATALOG: &str = r#"{ + "video": {"renditions": { + "hd": {"codec": "avc1.64001f", "codedWidth": 1280, "codedHeight": 720, "container": {"kind": "legacy"}}, + "sd": {"codec": "avc1.64001e", "codedWidth": 640, "codedHeight": 360, "container": {"kind": "legacy"}} + }}, + "audio": {"renditions": { + "en": {"codec": "opus", "sampleRate": 48000, "numberOfChannels": 2, "container": {"kind": "legacy"}}, + "fr": {"codec": "opus", "sampleRate": 48000, "numberOfChannels": 2, "container": {"kind": "legacy"}} + }} +}"#; + +#[tokio::main(flavor = "current_thread")] +async fn main() -> anyhow::Result<()> { + let args: Vec<_> = std::env::args().collect(); + ensure!(args.len() == 3, "usage: interop-catalog URL BROADCAST"); + let url: url::Url = args[1].parse()?; + let mut config = moq_tokio::connect::Config::default(); + config + .version + .push("moq-lite-07-wip".parse().map_err(anyhow::Error::msg)?); + config.websocket.enabled = Some(false); + let client = config.init(Default::default())?.with_reconnect(false); + let origin = moq_tokio::origin::spawn(); + + let broadcast = origin.create_broadcast(&args[2])?; + let track = broadcast.create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info())?; + ensure!(track.info().compress, "hang catalogs are compressed"); + let mut catalog = moq_json::snapshot::Producer::::new(track, Default::default()); + let value = hang::Catalog::from_slice(CATALOG.as_bytes())?; + catalog.update(moq_net::Timed::from(&value).at(moq_net::Timestamp::ZERO))?; + broadcast.announce(Default::default())?; + + // A local reader sees the inflated snapshot, as a plain peer of the relay does. The group + // stays open for deltas, and this catalog never writes one. + let mut local = catalog.consume(); + let mut group = local.recv_group().await?.context("no catalog group")?; + let bytes = group.read_frame().await?.context("no catalog snapshot")?.payload.len(); + + let session = client + .clone() + .with_publisher(&origin) + .connect(url) + .established() + .await?; + println!("catalog bytes={bytes}"); + + // Keep the broadcast up until every reader has checked the catalog. + let mut commands = tokio::io::BufReader::new(tokio::io::stdin()).lines(); + ensure!( + commands.next_line().await?.as_deref() == Some("clean end"), + "readers did not acknowledge the catalog" + ); + catalog.finish()?; + broadcast.close(); + session.close().await?; + eprintln!("catalog acknowledged"); + Ok(()) +} diff --git a/test/interop/interop.sh b/test/interop/interop.sh index d2ef73bf28b..234b57ed5c1 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -68,7 +68,8 @@ SIZE="${INTEROP_SIZE:-320x240}" # Empty means "any reserved port"; INTEROP_PORT pins one instead. PORT="${INTEROP_PORT:-}" URL="" -KEY="" # the HMAC key every cell's token is signed with (set once the relay's auth server starts) +KEY="" # the HMAC key every cell's token is signed with (set once the relay's auth server starts) +METRICS_URL="" # the relay's internal /metrics, served only by an in-tree run's relay NEGATIVE=0 MEDIA=0 MEDIA_CASES="" @@ -323,6 +324,9 @@ SUITE=interop DROP_VERSIONS=(moq-lite-05 moq-lite-06 moq-lite-07-wip) # The lite drafts the compressed-track lanes cross: lite-07 carries the flag, lite-06 gets inflated bytes. COMPRESS_VERSIONS=(moq-lite-07-wip moq-lite-06) +# The compressed catalog's concurrent readers: lite-07 carries the flag, and lite-06 and a +# moq-transport reader that does not offer FLATE share the relay's one inflated copy. +CATALOG_VERSIONS=(moq-lite-07-wip moq-lite-06 moq-transport-22) # Every publisher in this checkout sends a tone per audio channel, and every subscriber decodes # AUDIO_MS of it for tone.py (the browser: its page) to check against the publisher's list. This @@ -473,6 +477,7 @@ plan_pass() { record "not run" case=compress publisher=rust subscriber="$runtime" version="$version" record "not run" case=compress publisher="$runtime" subscriber=rust version="$version" done + record "not run" case="compressed catalog" publisher=rust subscriber="$runtime" done needs js-native-node || return 0 for version in "${DROP_VERSIONS[@]}"; do @@ -550,7 +555,7 @@ build_relay_cli() { exit 1 } if [[ "$MEDIA" -eq 0 ]]; then - (cd "$WORKSPACE" && cargo build --locked ${flag[@]+"${flag[@]}"} -p moq-cli --example interop-tail --example interop-audio --example interop-control --example interop-goaway --example interop-goaway-client --example interop-finish) + (cd "$WORKSPACE" && cargo build --locked ${flag[@]+"${flag[@]}"} -p moq-cli --example interop-tail --example interop-catalog --example interop-audio --example interop-control --example interop-goaway --example interop-goaway-client --example interop-finish) fi [[ -n "$RELAY" ]] || RELAY="$TARGET_BASE/$PROFILE/moq-relay" # The `moq-cli` crate ships its binary as `moq` (a `[[bin]]` override). @@ -858,6 +863,11 @@ if [[ "$COMPAT" -eq 1 ]]; then else sed -e "s|:4443\"|:${PORT}\"|g" -e "s|http://127.0.0.1:4440/|${AUTH_URL}|" \ "$INTEROP_DIR/interop.toml" >"$HARNESS_RUN/relay.toml" + # The compressed-catalog lane reads the relay's inflate counter from /metrics, which counts + # only while stats are enabled. + harness_port metrics + METRICS_URL="http://127.0.0.1:${HARNESS_PORT}/metrics" + printf '\n[internal]\nlisten = "127.0.0.1:%s"\n\n[stats]\nenabled = true\n' "$HARNESS_PORT" >>"$HARNESS_RUN/relay.toml" fi # Connection spans and clean closes must survive an inherited warn-only filter. harness_spawn relay "$HARNESS_RUN/relay.log" env \ @@ -2192,6 +2202,86 @@ run_control_case() { fi } +# The bytes the relay has inflated for plain readers, summed over every tier and role. +relay_inflated() { + curl -sf --max-time 5 "$METRICS_URL" | awk '/^moq_relay_inflated_bytes_total\{/ { sum += $2 } END { print sum + 0 }' +} + +# shellcheck disable=SC2329 # invoked indirectly via harness_spawn +run_catalog_publisher() { + local fifo="$1" + shift + timeout -k 3 $((TIMEOUT * 2)) "$TARGET_BASE/$PROFILE/examples/interop-catalog" "$@" <"$fifo" 9>&- +} + +# shellcheck disable=SC2329 # invoked indirectly via harness_spawn +run_catalog_reader() { + local runtime="$1" + shift + case "$runtime" in + js-native-node) (cd "$CLIENTS/js-native" && timeout -k 3 "$TIMEOUT" node --import tsx catalog.ts "$@") ;; + js-native-bun) (cd "$CLIENTS/js-native" && timeout -k 3 "$TIMEOUT" bun catalog.ts "$@") ;; + esac +} + +# A Rust publisher's compressed catalog reaches a native JS reader on each of CATALOG_VERSIONS at +# once through the relay, which must inflate the stored DEFLATE group exactly once for the plain +# readers: its inflate counter grows by the catalog's inflated size, not a multiple of it. +run_catalog_fanout() { + local runtime="$1" started=$SECONDS pid reader version before after bytes from got want readers=() why="" + local name="catalog-$1" fifo="$LOGS/catalog-ack" broadcast="catalog-$1-$$-$RANDOM" + local cell=(case="compressed catalog" publisher=rust subscriber="$runtime" log="$LOGS/$name-pub.log") + if is_broken "$runtime"; then + echo " FAIL compressed catalog rust -> $runtime (client unavailable)" + record fail "${cell[@]}" detail="client unavailable" + overall=1 + return + fi + mkfifo "$fifo" + exec 9<>"$fifo" + from=$(relay_next_line) + before=$(relay_inflated) || why="relay metrics unavailable" + # Subtree grants, which moq-transport's AUTH extension can carry too. + harness_spawn "$name-pub" "$LOGS/$name-pub.log" run_catalog_publisher "$fifo" "$(token_url --publish "$broadcast/**")" "$broadcast" + pid="$HARNESS_PID" + for version in "${CATALOG_VERSIONS[@]}"; do + harness_spawn "$name-$version" "$LOGS/$name-$version.log" run_catalog_reader "$runtime" "$(token_url --subscribe "$broadcast/**")" "$broadcast" "$version" + readers+=("$HARNESS_PID") + done + for reader in "${readers[@]}"; do harness_wait "$reader" || true; done + for version in "${CATALOG_VERSIONS[@]}"; do + want="catalog compress=false video=hd,sd audio=en,fr" + [[ "$version" != moq-lite-07-wip ]] || want="catalog compress=true video=hd,sd audio=en,fr" + # Like run_native, a verified result survives the NAPI addon's exit crash. + grep -qx "$want" "$LOGS/$name-$version.log" || why="${why:-$version reader did not report: $want}" + done + printf 'clean end\n' >&9 + harness_wait "$pid" || true + after=$(relay_inflated) || why="${why:-relay metrics unavailable}" + bytes=$(sed -n 's/^catalog bytes=\([0-9]*\)$/\1/p' "$LOGS/$name-pub.log") + got=$(relay_log_since "$from" | sed -n 's/.*conn{id=[0-9]* .*negotiated version=\([^ ]*\).*/\1/p' | sort | tr '\n' ' ') + if [[ -z "$why" ]] && ! grep -qx 'catalog acknowledged' "$LOGS/$name-pub.log"; then + why="publisher did not acknowledge" + elif [[ -z "$why" && "$got" != "moq-lite-06 moq-lite-07-wip moq-lite-07-wip moq-transport-22 " ]]; then + why="relay connections negotiated ${got:-nothing}" + elif [[ -z "$why" && "$((after - before))" != "$bytes" ]]; then + why="relay inflated $((after - before)) bytes, not the catalog's ${bytes:-?} once" + fi + if [[ -z "$why" ]]; then + echo " PASS compressed catalog rust -> $runtime (${CATALOG_VERSIONS[*]}; one ${bytes}-byte inflate)" + record pass "${cell[@]}" seconds=$((SECONDS - started)) + else + echo " FAIL compressed catalog rust -> $runtime ($why)" + record fail "${cell[@]}" seconds=$((SECONDS - started)) detail="$why" + overall=1 + for version in "${CATALOG_VERSIONS[@]}"; do cat "$LOGS/$name-$version.log"; done + cat "$LOGS/$name-pub.log" + harness_reap "$pid" + fi + exec 9>&- + rm "$fifo" +} + # This checkout's CLI FETCH and finite track tails in this pass, then the lite drop lanes. run_tails() { local runtime version @@ -2224,7 +2314,7 @@ run_tails() { fi fi done - # The compress and drop lanes pin their own lite versions. + # The compress, compressed catalog, and drop lanes pin their own versions. [[ "$VERSION" == auto ]] || return 0 for runtime in js-native-node js-native-bun; do needs "$runtime" || continue @@ -2232,6 +2322,7 @@ run_tails() { run_tail_pair rust "$runtime" compress "$version" run_tail_pair "$runtime" rust compress "$version" done + run_catalog_fanout "$runtime" done if needs js-native-node; then for version in "${DROP_VERSIONS[@]}"; do