Repository navigation
feat(relay): count inflated bytes and prove compressed catalog fan-out end to end #7162
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
e5a7c2b
e763628
52112d1
78978e2
d0a046e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
Comment on lines
+41
to
+42
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Include negotiated moq-transport hops. Compressed bytes can also cross a moq-transport hop when both peers negotiate Flate. The integration test covers a moq-transport-18 to moq-transport-22 relay path without lite-07. Correct this sentence and the same claim in
|
||
| 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 | ||
|
Comment on lines
+58
to
+59
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Clarify when the relay checks inflated size. The relay checks the output size when it inflates a frame. A compressed reader can receive the stored slice without that check, and a failed plain read does not abort the stored group. Do not imply that the relay rejects the group for every reader. (raw.githubusercontent.com)
|
||
| [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. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
Comment on lines
+346
to
+347
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Describe inflation as shared across subscribers. The relay inflates each group once for all plain subscribers, not once per subscriber. The current wording overstates relay CPU costs as subscriber count grows. (raw.githubusercontent.com)
|
||
|
|
||
| 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 | ||
|
|
||
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Include received compressed datagrams in the metric definition.
The counter also includes compressed datagrams inflated on ingress, even when the downstream session carries compression. The
datagrams_meter_the_bytes_on_the_wiretest checks this case. Update this description and the Prometheus HELP text inrs/moq-relay/src/internal.rsso operators can interpret the counter correctly. (raw.githubusercontent.com)