diff --git a/Cargo.lock b/Cargo.lock index 7c703cac3a9..80aba1367c5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4988,6 +4988,7 @@ dependencies = [ "arrayvec", "bytes", "criterion", + "flate2", "futures", "getrandom 0.4.3", "hashlink", diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index a8739d693a7..0d3342eb586 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -2640,11 +2640,13 @@ class MoqTrackInfo { final int? maxAgeUs; final int? refresh; final int? timescale; + final bool compress; MoqTrackInfo({ this.priority = 127, this.maxAgeUs = null, this.refresh = null, this.timescale = null, + this.compress = false, }); } @@ -2675,12 +2677,18 @@ class FfiConverterMoqTrackInfo { ); final timescale = timescale_lifted.value; new_offset += timescale_lifted.bytesRead; + final compress_lifted = FfiConverterBool.read( + Uint8List.view(buf.buffer, new_offset), + ); + final compress = compress_lifted.value; + new_offset += compress_lifted.bytesRead; return LiftRetVal( MoqTrackInfo( priority: priority, maxAgeUs: maxAgeUs, refresh: refresh, timescale: timescale, + compress: compress, ), new_offset - buf.offsetInBytes, ); @@ -2692,6 +2700,7 @@ class FfiConverterMoqTrackInfo { FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + + FfiConverterBool.allocationSize(value.compress) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -2716,6 +2725,10 @@ class FfiConverterMoqTrackInfo { value.timescale, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterBool.write( + value.compress, + Uint8List.view(buf.buffer, new_offset), + ); return new_offset - buf.offsetInBytes; } @@ -2724,6 +2737,7 @@ class FfiConverterMoqTrackInfo { FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + + FfiConverterBool.allocationSize(value.compress) + 0; } } diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index d7a9f893ca2..8a75ddf05c5 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -280,6 +280,14 @@ untimed. moq-lite 05 and 06 cannot declare an untimed track, so there its frames go out stamped with their send time; the work-in-progress 07 carries it 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 publishes and relays compressed tracks; js/net refuses them for now. + 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 reader or the next fetch finds it. That copy is not live meanwhile: readers get diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 55006d49901..c86e8ab3385 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -215,6 +215,7 @@ stale. "subscriptions_started": 6, "subscriptions_ended": 2, "fetches": 0, "bytes": 1048576, "frames": 900, "groups": 30, "datagrams": 0, + "inflated": 0, "stale": { "bytes": 0, "frames": 0, "groups": 0, "datagrams": 0 }, "announced": 1, "announced_closed": 0, "broadcasts": 3, "broadcasts_closed": 1, @@ -232,6 +233,7 @@ stale. | `fetches` | One-shot group fetches requested, including ones that found nothing. Their payload counts in `bytes`, `frames`, and `groups`. | | `bytes` / `frames` / `groups` | Payload delivered. | | `datagrams` | Groups delivered as an unreliable datagram. A subset of `groups`. | +| `inflated` | Bytes inflated from compressed groups for plain readers, counted once per group however many share the copy, plus received compressed datagrams, which inflate on arrival. Not part of `bytes`, which counts payload as stored or sent. | | `stale` | Payload skipped because it aged past a subscriber's latency budget, with the same four fields. Disjoint from the top-level payload counters. | The last six fields are legacy spellings of the `*_started` and `*_ended` diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 07eb92bc5cd..0eb9fbaa143 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -62,6 +62,7 @@ inside. The header is the reference: each function carries a doc comment. - **Errors.** Negative return codes are named by `MOQ_ERROR_*`, and `moq_error()` gives the reason on the calling thread. Auth rejections have their own codes so you don't retry them. For the peer's protocol code use `moq_error_protocol()`; do not parse `moq_error()`. A panic in a binding background task reports `MOQ_ERROR_PANIC` through its terminal callback; unrelated objects keep running. A session closed because its credential expired has kind `MOQ_PROTOCOL_KIND_EXPIRED`, and a request refused for an expired token returns `MOQ_ERROR_EXPIRED`; refresh the token before retrying. A catalog that needs a newer moq-hang draft than this build reads returns `MOQ_ERROR_UNSUPPORTED_CATALOG`; upgrade the library to read it. A request-cap closure has kind `MOQ_PROTOCOL_KIND_TOO_MANY_REQUESTS`; reduce the workload or adjust the relay's [session limits](/bin/relay/config#session-and-peer) before reconnecting. - **Threading.** Call any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Zeroed config is the default.** A zeroed `moq_client_config` means the default for every field, so new fields don't break callers. A field whose default isn't zero has a `has_*` flag: `backoff_timeout_us = 0` means "retry forever" only with `has_backoff_timeout = true`. +- **Compressed tracks.** `moq_track_info.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `moq_publish_media_flush` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 876392fbd12..0a77280d0e1 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -190,6 +190,10 @@ Audio and video convenience decoders reject a catalog configuration with `enable Hold the owned `BandwidthConsumer` returned by `session->recv_bandwidth()` to receive bandwidth estimates. `peek()` reads the current estimate in bits per second and `changed()` waits for a new one. Releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +## Compressed tracks + +`moq::TrackInfo::compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. + ## Track demand `demand()->wanted()` is the group subscribers want, or `std::nullopt` while nobody subscribes, and `wanted_changed()` waits for it to move: start a new group once it passes your largest. Set `TrackInfo::refresh` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 73bdd8968c3..659b3e2e731 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -22,6 +22,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no `package:moq/json.dart` consumers return `Value` (`value`, `timestampUs`) from `next()`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. Raw tracks with a `null` timescale are untimed on both publish and receive. +`MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index debf9f3bf99..ab775825e9c 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -19,6 +19,7 @@ and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast we catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps use `time.Duration`. A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. +`TrackInfo.Compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. `moq.dev/moq/flate` publishes opaque snapshot and stream payloads; its `Update` / `Append` and the JSON producers take a final `*time.Duration` timestamp argument (`nil` for untimed). JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest` diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 4c8b59e9c2c..0bf9ea0e960 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -21,6 +21,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. Raw tracks with a `null` timescale are untimed on both publish and receive. +`MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index fd702699d9d..0dca8b01adb 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -26,6 +26,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order, and `await consumer.latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. Raw tracks with a `None` timescale are untimed on both publish and receive. +`TrackInfo(compress=True)` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. `moq.flate.SnapshotProducer` / `StreamProducer` publish opaque payloads; their `update` / `append` and the JSON producers accept `timestamp=timedelta(...)` (`None` for untimed). Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index e55f0029f41..9581bf012ff 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -22,6 +22,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no `Json` consumers yield `Json.Timed` (`value`, `timestampUs`); a snapshot consumer yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. Raw tracks with a `nil` timescale are untimed on both publish and receive. +`MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `Media.CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/drafts/draft-lcurley-moq-flate.md b/drafts/draft-lcurley-moq-flate.md index 48dc994c94e..29828b52e54 100644 --- a/drafts/draft-lcurley-moq-flate.md +++ b/drafts/draft-lcurley-moq-flate.md @@ -29,7 +29,7 @@ informative: This document specifies how a MoQ Transport {{moqt}} track carries DEFLATE-compressed payloads. Each subgroup is one raw DEFLATE stream, sync flushed at each object boundary, so every object stays self-delimited while later objects compress against the earlier ones in the subgroup. Small repetitive payloads compress several times better than they do alone, and a dropped group costs nothing beyond itself because the window never spans one. -Nothing is added to the wire: the application declares the track compressed, and a relay forwards it unchanged. +The transport declares a track compressed and carries each object's inflated size, so a relay forwards the compressed bytes to a peer that understands them and inflates them for one that does not. --- middle @@ -53,7 +53,7 @@ Each subgroup is a separate DEFLATE stream: its object payloads share one window The application decides which subgroups a track uses; a consumer knows which to expect and decodes each one's objects in order. -A publisher MUST NOT send a compressed track in datagrams, which are neither ordered nor reliable. +A datagram carries a group of one object, so it is a stream of its own: compressed alone, starting cold. An object with no payload is skipped, neither advancing nor resetting the window. @@ -68,19 +68,23 @@ A publisher MUST omit it from each object and a consumer MUST append it before d A zero-length payload is neither compressed nor decompressed. -The stream is never terminated: no object ends in a final block, so a consumer decompresses incrementally and MUST NOT treat the absent end of stream as truncation. +The stream is never terminated: a publisher MUST NOT emit a final block, and a consumer MUST treat one as malformed and abandon the subgroup. +A consumer decompresses incrementally and MUST NOT treat the absent end of stream as truncation. A consumer missing an object MUST abandon the rest of the subgroup, which it can no longer decompress. The compression level is a publisher's choice; any conformant stream decodes. # Declaring Compression {#declare} -The application declares a track compressed, conventionally with a `.z` suffix on the track name, or in its catalog. +The transport declares a track compressed, and gives each object's inflated size beside its compressed one. +{{moql}} does both from moq-lite-07: a Compression codec id in TRACK_INFO, and an Inflated Size on each FRAME and datagram. A consumer MUST NOT infer compression from the payload: raw DEFLATE has no magic number, so a wrong guess yields plausible garbage. -There is deliberately no transport signal. -A relay drops objects and re-frames what it forwards, so a transport that knew about the window would make the relay responsible for emitting a stream that still decodes, which means carrying a DEFLATE implementation. -Instead a relay forwards opaque bytes, and an endpoint that has never heard of this document never asks for a compressed track. +A consumer MUST treat an object that inflates to more or less than its declared size as malformed, and abandon the subgroup. + +A relay forwards the compressed objects as received to a peer whose transport declares compression. +For any other peer it inflates them, once per subgroup however many such peers it serves, and sends the original objects without the declaration. +A peer is never sent compressed bytes it was not told about. # Security Considerations @@ -89,18 +93,27 @@ The compressed size of one payload reveals how much it has in common with the pa A publisher MUST NOT compress a secret and attacker-influenced data in the same subgroup. Encryption does not mitigate this, since the sizes are visible to anyone on the path. -A few bytes can inflate to gigabytes, so a consumer MUST bound the decompressed size of each object and abandon the subgroup once that bound is exceeded. +A few bytes can inflate to gigabytes, so a consumer MUST check each declared inflated size against its limits before decompressing, and never inflate past it. Each open subgroup also holds a window of up to 32 KiB, so a consumer SHOULD bound how many it decompresses at once. # IANA Considerations This document requests no registrations. -The format lives inside object payloads, which {{moqt}} treats as opaque. +The format lives inside object payloads, and the declaration in the transport that carries them. --- back +# Changelog + +## Since draft-lcurley-moq-flate-00 (in progress) + +- Compression is declared by the transport instead of the application: {{moql}} carries a Compression codec in TRACK_INFO and each object's Inflated Size on FRAME and datagrams. +- A relay inflates for a peer whose transport does not declare compression. +- A datagram is compressed alone, as a stream of its own. +- A consumer rejects an object that inflates to other than its declared size, or that ends in a final block. + # Acknowledgments {:numbered="false"} diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index e814eba4e64..a1a9a7401f5 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -224,6 +224,7 @@ DATAGRAM Body { [Status (i)] [Properties Length (i), Properties (..)] [Timestamp (i)] + [Inflated Size (i)] Payload (b) } ~~~ @@ -240,6 +241,7 @@ A bit field, or 0 for a plain datagram, which has none of the optional fields be A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payload beside one; a Normal (0) Status is an empty object. +It has no Inflated Size ({{moql}} DATAGRAM), even on a compressed track, as there is no payload to inflate. A non-zero Status carries no object: it has no Timestamp, even on a timed track. A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 3ecfd1154dd..122a16e41a7 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -36,6 +36,14 @@ normative: informative: I-D.lcurley-moq-cluster: + moqflate: + title: "DEFLATE Compressed Tracks for MoQ" + target: https://datatracker.ietf.org/doc/draft-lcurley-moq-flate/ + author: + - + ins: L. Curley + name: Luke Curley + date: false --- abstract @@ -793,6 +801,7 @@ DATAGRAM Body { Subscribe ID (i) Group Sequence (i) [Timestamp (i)] + [Inflated Size (i)] Payload (b) } ~~~ @@ -808,6 +817,10 @@ The absolute sequence number of the group carried by this datagram. The absolute timestamp of the single frame in the group, expressed in the Track's `Timescale`. Present only on a timed Track, which the receiver learns from the subscription named by `Subscribe ID`. +**Inflated Size**: +The size of the payload once inflated. +Present only when the Track's Compression is not none; the datagram payload is then compressed alone, as a stream of its own. + **Payload**: The frame payload, extending to the end of the datagram. The total datagram body MUST NOT exceed 1200 bytes, ensuring it fits within the minimum QUIC path MTU without IP-layer fragmentation; a publisher MUST NOT send a larger one and a receiver MUST silently drop it. @@ -1306,6 +1319,7 @@ TRACK_INFO Message { Publisher Max Age (i) Timescale (i) Refresh (i) + [Compression (i)] } ~~~ @@ -1345,6 +1359,13 @@ Joins coalesce until the requested group arrives. A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE. Versions before lite-07 omit Refresh and Wanted Group; a Track received on those versions never refreshes. +**Compression**: +Present from lite-07. +How each Group of this Track is compressed: none (0x0), or DEFLATE (0x1), each Group one DEFLATE stream as specified by {{moqflate}}. +Any other value is a PROTOCOL_VIOLATION. +When Compression is not none, FRAME messages and datagrams carry an `Inflated Size`. +A publisher that cannot send this field, on lite-06 and earlier, MUST send the Track's frames inflated instead. + ## TRACKS {#tracks} TRACKS is sent by a subscriber to list a Broadcast's Tracks. It is the first message on a Tracks Stream (0x8). @@ -1701,6 +1722,7 @@ The FRAME message is a payload within a group. ~~~ FRAME Message { [Timestamp Delta (i)] + [Inflated Size (i)] Message Length (i) Payload (b) } @@ -1717,6 +1739,11 @@ Encoded as a zigzag-mapped variable-length integer: Zigzag interleaves non-negative and negative values so small magnitudes of either sign fit in a 1-byte varint. The first frame of a group is delta-encoded from `0`, so its `Timestamp Delta` is the zigzag encoding of the absolute timestamp. +**Inflated Size**: +The size of the payload once inflated. +Present only when the Track's Compression is not none; the payload is then the next slice of the Group's compressed stream. +A receiver MUST check it against its limits before inflating, and MUST treat a payload that inflates to any other size as malformed. + **Payload**: An application-specific payload. The `Message Length` describes the payload size on the wire. @@ -1729,6 +1756,8 @@ The `Message Length` describes the payload size on the wire. - Added the Tracks Stream (0x8) with TRACKS, TRACKS_ADD, TRACKS_REMOVE, and SYNCED: a subscriber lists one Broadcast's Tracks, each with its TRACK_INFO, then SUBSCRIBEs to those it wants. A relay answers at once with what it holds. Older versions reset the stream type. - Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Group`, carrying ratio-based refresh demand through relays. +- Added `Compression` to TRACK_INFO: none (0x0) or DEFLATE (0x1), whose Groups are DEFLATE streams per draft-lcurley-moq-flate. FRAME and datagrams carry an `Inflated Size` when it is not none. Earlier versions receive the Track inflated. + - Replaced ANNOUNCE_OK Active Count with an ordered, empty SYNCED event (0x4), marking the initial set without retaining routes that end before delivery. - A publisher must not start a timed Group's frame 0 earlier than a lower-sequence Group's. Receivers do not check it, since a received timestamp may be a send time. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index b5bfc663b1d..0331ac824cd 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `TrackInfo` gains `Compress` (#5928) + +A positional `TrackInfo{...}` literal adds a trailing `false`; keyed literals need no change. + ### Anchors can name a time (#6074) `AnchorTime` names the group containing a presentation time, and type switches over `Anchor` need a case for it. diff --git a/go/wrapper/records.go b/go/wrapper/records.go index b6a5e827e71..175e446ea7c 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -96,12 +96,14 @@ func subscriptionFFI(s *Subscription) (*ffi.MoqSubscription, error) { // a group's later bytes may grow before a joining subscriber asks for a new group // (nil never asks), and the timescale in ticks per second (nil means untimed on // both publish and receive). A zero Priority is the least urgent; set 127 for the -// midpoint a nil TrackInfo uses. +// midpoint a nil TrackInfo uses. Compress DEFLATEs each group on the wire to peers +// that support it; readers always see the original frames. type TrackInfo struct { Priority uint8 MaxAge *time.Duration Refresh *uint32 Timescale *uint64 + Compress bool } func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { @@ -109,11 +111,23 @@ func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { return nil, nil } maxAge, err := bridge.OptionalDuration(info.MaxAge, "max age") - return &ffi.MoqTrackInfo{Priority: info.Priority, MaxAgeUs: maxAge, Refresh: info.Refresh, Timescale: info.Timescale}, err + return &ffi.MoqTrackInfo{ + Priority: info.Priority, + MaxAgeUs: maxAge, + Refresh: info.Refresh, + Timescale: info.Timescale, + Compress: info.Compress, + }, err } func trackInfoFromFFI(info ffi.MoqTrackInfo) TrackInfo { - return TrackInfo{Priority: info.Priority, MaxAge: optFromMicros(info.MaxAgeUs), Refresh: info.Refresh, Timescale: info.Timescale} + return TrackInfo{ + Priority: info.Priority, + MaxAge: optFromMicros(info.MaxAgeUs), + Refresh: info.Refresh, + Timescale: info.Timescale, + Compress: info.Compress, + } } // ConnectionStats holds transport metrics for a session (RTT, bandwidth, byte diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 4a1cacc8009..892a613bede 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -914,6 +914,8 @@ export class Subscriber { await stream.writer.u53(StreamId.Track); await new TrackMessage(broadcast, track, epoch).encode(stream.writer, this.version); const info = await TrackInfo.decode(stream.reader, this.version); + // Until js/net inflates, a compressed track is refused rather than read as garbage. + if (info.compress) throw new Error("compressed tracks are not supported"); return { info, stream }; }, signal, diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index e0c776bf829..9663d6c5360 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -1,5 +1,6 @@ import { expect, test } from "bun:test"; import { Milli } from "@moq/clock"; +import { ProtocolViolation } from "../error.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; @@ -59,7 +60,8 @@ test("TrackInfo for Rust's default Info matches cross-language wire bytes", asyn test("TrackInfo carries an untimed track as zero on lite-07 and milliseconds before", async () => { const info = new TrackInfo({ priority: 1 }); const lite07 = await bytes((w) => info.encode(w, Version.DRAFT_07), Version.DRAFT_07); - expect(lite07.at(-1)).toBe(0); + // The timescale, then the compression codec. + expect(lite07.at(-2)).toBe(0); const got = await TrackInfo.decode(new Reader(undefined, lite07, Version.DRAFT_07), Version.DRAFT_07); expect(got.timescale).toBeUndefined(); @@ -74,6 +76,22 @@ test("TrackInfo carries an untimed track as zero on lite-07 and milliseconds bef } }); +test("TrackInfo carries the compression codec on lite-07 only", async () => { + const info = new TrackInfo({ priority: 1, compress: true }); + const lite07 = await bytes((w) => info.encode(w, Version.DRAFT_07), Version.DRAFT_07); + expect(lite07.at(-1)).toBe(1); + const got = await TrackInfo.decode(new Reader(undefined, lite07, Version.DRAFT_07), Version.DRAFT_07); + expect(got.compress).toBe(true); + + // Anything but none (0) or DEFLATE (1) is a protocol violation. + lite07[lite07.length - 1] = 2; + await expect(TrackInfo.decode(new Reader(undefined, lite07, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow( + ProtocolViolation, + ); + + await expect(bytes((w) => info.encode(w, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); +}); + test("Track request round-trips on draft-05", async () => { const msg = new Track(Path.from("room"), "video"); const reader = new Reader( diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index e68210b4565..177cd337136 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -1,10 +1,27 @@ import type * as Epoch from "../epoch.ts"; +import { ProtocolViolation } from "../error.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasGroupOrder, hasRefresh, hasTrackStream, Version, wireTimescale } from "./version.ts"; +import { hasCompression, hasGroupOrder, hasRefresh, hasTrackStream, Version, wireTimescale } from "./version.ts"; + +// TRACK_INFO `Compression` codec ids: none, or per-group DEFLATE (draft-lcurley-moq-flate). +const COMPRESSION_NONE = 0; +const COMPRESSION_DEFLATE = 1; + +async function decodeCompression(r: Reader): Promise { + const codec = await r.u53(); + switch (codec) { + case COMPRESSION_NONE: + return false; + case COMPRESSION_DEFLATE: + return true; + default: + throw new ProtocolViolation(`unknown compression: ${codec}`); + } +} function guardTrack(version: Version) { if (!hasTrackStream(version)) throw new Error("track stream not supported for this version"); @@ -71,17 +88,24 @@ export class TrackInfo { * out as milliseconds (see {@link wireTimescale}). */ timescale?: Timescale; + /** + * Whether each group's frames are DEFLATE slices of one stream (draft-lcurley-moq-flate), + * each FRAME carrying its inflated size. Lite-07 only. + */ + compress: boolean; constructor({ priority = 0, maxAge, timescale, refresh, + compress = false, }: { priority?: number; maxAge?: number; timescale?: number; refresh?: number; + compress?: boolean; }) { if (!Number.isInteger(priority) || priority < 0 || priority > 255) { throw new RangeError(`priority must be an integer in 0..=255: ${priority}`); @@ -95,6 +119,7 @@ export class TrackInfo { this.priority = priority; this.maxAge = maxAge; this.timescale = timescale === undefined ? undefined : Timescale(timescale); + this.compress = compress; } async #encode(w: Writer, version: Version) { @@ -106,6 +131,7 @@ export class TrackInfo { await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); if (hasRefresh(version)) await w.u53(this.refresh === undefined ? 0 : this.refresh + 1); + if (hasCompression(version)) await w.u53(this.compress ? COMPRESSION_DEFLATE : COMPRESSION_NONE); } static async #decode(r: Reader, version: Version): Promise { @@ -127,7 +153,14 @@ export class TrackInfo { const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); const refresh = hasRefresh(version) ? (await r.u53()) - 1 : undefined; - return new TrackInfo({ priority, maxAge, timescale, refresh: refresh === -1 ? undefined : refresh }); + const compress = hasCompression(version) ? await decodeCompression(r) : false; + return new TrackInfo({ + priority, + maxAge, + timescale, + refresh: refresh === -1 ? undefined : refresh, + compress, + }); } async encode(w: Writer, version: Version): Promise { @@ -146,6 +179,9 @@ export class TrackInfo { ) throw new RangeError("refresh exceeds u32"); if (this.timescale !== undefined) Timescale(this.timescale); + if (this.compress && !hasCompression(version)) { + throw new Error("a compressed track needs lite-07"); + } return Message.encode(w, (w) => this.#encode(w, version)); } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 7ad0208cba6..4e0d5ba3d28 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -371,6 +371,25 @@ export function hasEpoch(version: Version): boolean { } } +/** + * Whether TRACK_INFO carries the compression codec, and a compressed track's FRAME and + * datagram its inflated size. Added in lite-07. + */ +export function hasCompression(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 ANNOUNCE_START and ANNOUNCE_UPDATE may copy a path head or hop-chain tail from a live announcement. Added in lite-07. */ export function hasAnnounceCompression(version: Version): boolean { // Explicitly list older versions so future versions keep the lite-07+ behavior. diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index a065d3f7255..2b22b3a03f5 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -125,12 +125,15 @@ class TrackInfo: times its first frame a group's later bytes may grow before a joining subscriber asks for a new group, ``None`` to never ask. ``timescale`` is ticks per second: ``None`` means the track is untimed, on both publish and receive. + ``compress`` DEFLATEs each group on the wire to peers that support it; readers + always see the original frames. """ priority: int = 127 max_age: timedelta | None = None refresh: int | None = None timescale: int | None = None + compress: bool = False def _ffi(self) -> MoqTrackInfo: return MoqTrackInfo( @@ -138,6 +141,7 @@ def _ffi(self) -> MoqTrackInfo: max_age_us=_opt_us(self.max_age, "max_age"), refresh=self.refresh, timescale=self.timescale, + compress=self.compress, ) @staticmethod @@ -147,6 +151,7 @@ def _from_ffi(info: MoqTrackInfo) -> TrackInfo: max_age=None if info.max_age_us is None else _from_us(info.max_age_us), refresh=info.refresh, timescale=info.timescale, + compress=info.compress, ) diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 21433416164..173f88607ce 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -45,8 +45,8 @@ Every interview prompt and the selected answer (✅) are in the planning PR. 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 flag and the frame header the - size ([Core](/quest/m1/compress/core.md)); IETF draft-16+ carries them only +- **Signaling:** lite-07 TrackInfo carries the codec id and the frame header the + size; IETF draft-16+ carries them only after both peers advertise a setup parameter ([IETF](/quest/m1/compress/ietf.md)), because unknown track properties are discarded. Lite-01..06, IETF draft-14/15, and IETF peers without the @@ -80,7 +80,6 @@ This README owns the end-to-end proof and the guide once every child lands: ## Required -- [Core](/quest/m1/compress/core.md) - Rust moq-net compresses opted-in tracks, carries them on lite-07, and serves a shared inflated copy to everything else - [IETF extension](/quest/m1/compress/ietf.md) - moq-transport draft-16+ peers that negotiate the extension exchange compressed tracks - [JavaScript](/quest/m1/compress/js.md) - js/net publishes and consumes compressed tracks on lite-07 - [Migrate](/quest/m1/compress/migrate.md) - catalogs, stats, and timelines publish one compressed track; moq-flate, @moq/flate, and every `.z` name are gone diff --git a/quest/m1/compress/core.md b/quest/m1/compress/core.md deleted file mode 100644 index 0ecf753bade..00000000000 --- a/quest/m1/compress/core.md +++ /dev/null @@ -1,66 +0,0 @@ -# [L] Compressed tracks in Rust moq-net - -## Goal - -A Rust publisher sets `track::Info::compress` and moq-net DEFLATEs each -group. A lite-07-wip peer receives the compressed bytes with the flag set; -every other session (lite-01..06, every IETF draft) receives the same frames -inflated, with no flag, from one inflated copy per group shared across all -plain readers. In-process consumers read plain frames. js/net parses the new -lite-07 fields and refuses a compressed track until -[JavaScript](/quest/m1/compress/js.md) lands. - -## Plan - -See the [epic](/quest/m1/compress/README.md) for the decisions. - -- Move the codec from `rs/moq-flate/src/lib.rs` into a crate-private - `rs/moq-net` module. The crate itself is deleted in - [Migrate](/quest/m1/compress/migrate.md), with its last users. -- `track::Info` gains a documented `pub compress: bool`, default `false`. -- Producer: writing a frame on a compressed track compresses it through the - group's encoder and records the plain size on `frame::Info.size`. A group - keeps one encoder from its first frame to its finish. A frame written in - chunks (`create_frame`) buffers until it finishes, since the wire needs - its compressed size first; ingress already knows both sizes from the - header, so it streams. -- Storage: the model stores the compressed slices. Ingress from a session - stores what arrived, never recompressing. The shared inflated copy hangs - off the group, is built on first plain read, is billed to `cache::Pool`, - and drops with the group. The declared size is checked against the same - limits as a plain frame's before inflating. A frame whose inflated output differs from its - declared size, larger or smaller, fails the group, since IETF egress has - already written that size as the payload length. -- Egress: a lite-07 session writes the compressed slices with the flag in - TrackInfo and the declared size in the frame header. Any other session - writes the inflated copy without the flag. A compressed track never - reaches a peer as compressed bytes it was not told about. -- Wire (lite-07-wip): TrackInfo gains the flag. The frame header gains an - uncompressed-size varint, present only on compressed tracks. A datagram - is its own one-frame group (lite allows one datagram per group), so it - compresses with a fresh window and no delta, and carries the same size - varint. Update - `drafts/draft-lcurley-moq-lite.md` and reference - `draft-lcurley-moq-flate` for the codec; drop that draft's ".z suffix" and - "no transport signal" text. -- Ranges: a range from frame N of a compressed group is served from N; the - requester inflates from the 0..N-1 it holds. Refresh's ratio counts the - stored, compressed bytes. -- js/net: encode and decode the new lite-07 fields so lite-07 interop keeps - working, and refuse a compressed track with an error. Nothing sets - `compress` until Migrate, so no first-party track hits the refusal. -- moq-ffi: `MoqTrackInfo` gains `compress`, with the wrappers and - `doc/lib/*` per the cross-package sync table. -- Docs inline: `doc/concept` sections on track info and moq-lite. - -Tests: a compressed track round-trips through a relay to a lite-07 and a -lite-06 subscriber; N plain readers of one group inflate once; a frame that -inflates to more or less than its declared size fails; a compressed -datagram round-trips; an oversized declaration is refused before -inflating; a chunked frame on a compressed track publishes whole; a range from frame N decodes against -a cached prefix. Run `just test interop --all`. Add a bench swept over plain -readers and compressed groups so the inflate cost stays per group, not per -reader. - -Public API: `track::Info::compress`, `MoqTrackInfo::compress`. Wire: -lite-07-wip TrackInfo and frame header. diff --git a/quest/m1/compress/ietf.md b/quest/m1/compress/ietf.md index 6f562a85496..8fdff029543 100644 --- a/quest/m1/compress/ietf.md +++ b/quest/m1/compress/ietf.md @@ -6,7 +6,7 @@ Two moq-transport draft-16+ peers that both advertise the compression setup parameter exchange a compressed track as compressed bytes, with a track property flagging it and an object extension declaring each object's inflated size. An IETF peer without the parameter, and draft-14/15, get the -inflated copy as today after [Core](/quest/m1/compress/core.md). moq-relay +inflated copy as today. moq-relay accepts a compressed track from a negotiated IETF publisher and forwards it compressed on lite-07. @@ -31,7 +31,3 @@ reads plain. Run `just test interop --all`. Public API: none beyond Core. Wire: a new setup parameter, track property, and object extension on draft-16+. - -## Required - -- [Core](/quest/m1/compress/core.md) - the model stores compressed groups and serves the shared inflated copy diff --git a/quest/m1/compress/js.md b/quest/m1/compress/js.md index e347ef3eb00..f78f9ff5319 100644 --- a/quest/m1/compress/js.md +++ b/quest/m1/compress/js.md @@ -5,7 +5,7 @@ A JS publisher sets `compress` on a track's `Info` and js/net DEFLATEs each group on lite-07, and a JS consumer reads a compressed lite-07 track as plain frames. On any other session a JS publisher sends plain frames without the -flag, and the refusal [Core](/quest/m1/compress/core.md) added is gone. +flag, and the refusal Core added is gone. ## Plan @@ -21,7 +21,3 @@ Tests: Rust and JS publish compressed tracks to each other over lite-07 through moq-relay; a JS publisher on lite-06 sends plain frames. Public API: `Info.compress` in `@moq/net`. Wire: none beyond Core. - -## Required - -- [Core](/quest/m1/compress/core.md) - fixes the lite-07 wire and the Rust model this mirrors diff --git a/quest/m1/compress/migrate.md b/quest/m1/compress/migrate.md index 7258fc9012f..0f69d2576fb 100644 --- a/quest/m1/compress/migrate.md +++ b/quest/m1/compress/migrate.md @@ -48,5 +48,4 @@ Public API: removals listed above. Wire: the hang catalog loses ## Required -- [Core](/quest/m1/compress/core.md) - Rust compresses opted-in tracks - [JavaScript](/quest/m1/compress/js.md) - js/publish and js/watch need the JS side before they drop `.z` diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 4c35225c53d..764dc7066fa 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -87,7 +87,6 @@ is published; older versions are unchanged. - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - settles what lite-07's DROP Error Code means - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route -- [Compressed tracks in Rust](/quest/m1/compress/core.md) - TRACK_INFO carries the compress flag and the frame header each compressed frame's inflated size - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS in js/net](/quest/m1/archive/tracks-js.md) - JS speaks lite-07's Tracks Stream, which Rust already does - [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - the `ietf` extension carries a track's ingress version once instead of a code per block diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 6ce1689b31f..16e3b1374b1 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `moq_track_info` gains `compress` (#5928) + +The new trailing field changes its ABI. A zero-initialized struct leaves it false, as before. + ### Anchors can name a time (#6074) `moq_anchor` gains `timestamp_us`, read with the new `MOQ_ANCHOR_TIME` kind, which changes its ABI. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 74c55fa2952..c0004025181 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -533,6 +533,10 @@ pub struct moq_track_info { pub refresh: u32, /// Whether `refresh` is set. When false, a joining subscriber never asks for a new group. pub refresh_present: bool, + + /// Whether each group is DEFLATE-compressed on the wire to peers that support it. + /// Readers always see the original frames. + pub compress: bool, } impl TryFrom<&moq_track_info> for moq_net::track::Info { @@ -553,7 +557,7 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { if info.refresh_present { out = out.with_refresh(info.refresh); } - Ok(out) + Ok(out.with_compress(info.compress)) } } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index b270deb4f76..a05be7a1db8 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1408,6 +1408,7 @@ fn publish_track_invalid_broadcast() { timescale_present: false, refresh: 0, refresh_present: false, + compress: false, }; assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), &info) } < 0); assert!(moq_publish_track_group(9999) < 0); @@ -1439,6 +1440,7 @@ fn publish_track_with_info_rejects_invalid_timescale() { timescale_present: true, refresh: 0, refresh_present: false, + compress: false, }; assert!(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) } < 0); @@ -1715,6 +1717,7 @@ fn raw_track_subscription_options_and_update() { timescale_present: true, refresh: 0, refresh_present: false, + compress: false, }; let track = id(unsafe { moq_publish_track(broadcast, track_name.as_ptr() as *const c_char, track_name.len(), &info) }); @@ -1828,6 +1831,7 @@ fn raw_track_time_anchor() { timescale_present: true, refresh: 0, refresh_present: false, + compress: false, }; let track = id(unsafe { moq_publish_track(broadcast, track_name.as_ptr() as *const c_char, track_name.len(), &info) }); @@ -2781,6 +2785,7 @@ fn track_demand_reports_the_wanted_group() { timescale_present: false, refresh: 0, refresh_present: true, + compress: false, }; let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index eca047ebf96..d12b0488b5f 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,10 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### `MoqTrackInfo` gains `compress` (#5928) + +It defaults to `false` in every generated binding; a Rust struct literal adds `compress: false`. + ### Anchors can name a time (#6074) `MoqAnchor` gains `Time { timestamp_us }`, the group containing that presentation time, so exhaustive matches need an arm for it. diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 86b0d8e58c0..adf13710738 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -244,6 +244,7 @@ async fn rust_ffi() { max_age_us: None, refresh: None, timescale: Some(1_000_000), + compress: false, }; let tracks: Vec<_> = (0..case.publishers) .map(|p| broadcast.publish_track(p.to_string(), Some(timed.clone())).unwrap()) diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 5c032c16dce..97b2c3ec24e 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -31,6 +31,10 @@ pub struct MoqTrackInfo { /// Per-frame timescale in ticks per second, or null for an untimed track. #[uniffi(default = None)] pub timescale: Option, + /// Whether each group is DEFLATE-compressed on the wire to peers that support it. + /// Readers always see the original frames. + #[uniffi(default = false)] + pub compress: bool, } impl TryFrom for moq_net::track::Info { @@ -49,7 +53,7 @@ impl TryFrom for moq_net::track::Info { })?; out = out.with_timescale(scale); } - Ok(out) + Ok(out.with_compress(info.compress)) } } @@ -75,6 +79,7 @@ impl TryFrom<&moq_net::track::Info> for MoqTrackInfo { max_age_us, refresh: info.refresh, timescale: info.timescale.map(|timescale| timescale.as_u64()), + compress: info.compress, }) } } @@ -725,6 +730,7 @@ mod metadata_tests { max_age_us, refresh: None, timescale: None, + compress: false, }; let model = moq_net::track::Info::try_from(info).unwrap(); assert_eq!(model.max_age, max_age_us.map(std::time::Duration::from_micros)); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index ed8ccdd37e9..8794ac9cb84 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -35,6 +35,7 @@ fn timed_info() -> MoqTrackInfo { max_age_us: None, refresh: None, timescale: Some(1_000_000), + compress: false, } } @@ -862,6 +863,7 @@ async fn raw_track_datagram_roundtrip() { max_age_us: None, refresh: None, timescale: Some(1_000_000), + compress: false, }), ) .unwrap(); @@ -893,6 +895,7 @@ async fn raw_track_info_reports_publisher_properties() { max_age_us: Some(2_500_000), refresh: Some(2), timescale: Some(90_000), + compress: true, }; let track = broadcast.publish_track("status".into(), Some(info)).unwrap(); let consumer = track.consume(None).unwrap(); @@ -902,6 +905,7 @@ async fn raw_track_info_reports_publisher_properties() { assert_eq!(got.max_age_us, Some(2_500_000)); assert_eq!(got.refresh, Some(2)); assert_eq!(got.timescale, Some(90_000)); + assert!(got.compress); } #[tokio::test] @@ -968,6 +972,7 @@ async fn data_writes_preserve_optional_timestamps() { max_age_us: None, refresh: None, timescale: timestamp_us.map(|_| 1_000_000), + compress: false, }), ) .unwrap(); @@ -1109,6 +1114,7 @@ async fn json_snapshot_roundtrip() { max_age_us: None, timescale: Some(1_000_000), refresh: None, + compress: false, }; let track = broadcast.publish_track("meta".into(), Some(info)).unwrap(); let producer = MoqJsonSnapshotProducer::new(&broadcast, &track, config.clone()).unwrap(); diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index 0f1809f8aee..be78db3798c 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -28,6 +28,9 @@ fuzz = ["async"] [dependencies] arrayvec = "0.7" bytes = { workspace = true } +# zlib-rs, not the default miniz_oxide: miniz_oxide 0.9.1 can return from a sync flush with output +# space left but the flush unfinished, silently truncating the frame. +flate2 = { workspace = true, features = ["zlib-rs", "runtime_detection"] } futures = { workspace = true, optional = true } hashlink = { workspace = true } kio = { workspace = true } diff --git a/rs/moq-net/benches/group.rs b/rs/moq-net/benches/group.rs index 54b1b22ca3d..223cc21a7fd 100644 --- a/rs/moq-net/benches/group.rs +++ b/rs/moq-net/benches/group.rs @@ -413,6 +413,54 @@ fn bench_stamp(c: &mut Criterion) { g.finish(); } +/// Read every frame of fresh compressed groups with N plain readers each. +/// +/// The group inflates once into a copy every plain reader shares, so the cost should +/// slope with the groups and stay nearly flat in the readers; a per-reader inflate +/// shows up as a slope over the readers. +fn bench_inflate(c: &mut Criterion) { + const FRAMES: usize = 32; + let payloads: Vec = (0..FRAMES) + .map(|index| Bytes::from(format!("{{\"frame\":{index},\"status\":\"{}\"}}", "ok".repeat(100)))) + .collect(); + let mut g = c.benchmark_group("group_inflate"); + for groups in [1usize, 16] { + for readers in [1usize, 8, 64] { + g.throughput(Throughput::Elements((groups * readers * FRAMES) as u64)); + let id = BenchmarkId::new(format!("groups{groups}"), readers); + g.bench_with_input(id, &readers, |b, &readers| { + b.iter_batched( + || { + let broadcast = broadcast::Producer::new(broadcast::Info::default()); + let track = broadcast.create_track("bench", timed().with_compress(true)).unwrap(); + let consumers: Vec = (0..groups) + .flat_map(|_| { + let mut group = track.append_group().unwrap(); + for payload in &payloads { + group.write_frame(Timestamp::ZERO, payload.clone()).unwrap(); + } + group.finish().unwrap(); + (0..readers).map(move |_| group.consume()).collect::>() + }) + .collect(); + (broadcast, track, consumers) + }, + |(broadcast, track, mut consumers)| { + for consumer in &mut consumers { + while let Some(frame) = consumer.read_frame().now_or_never().unwrap().unwrap() { + black_box(frame); + } + } + (broadcast, track, consumers) + }, + BatchSize::SmallInput, + ); + }); + } + } + g.finish(); +} + criterion_group!( benches, bench_write, @@ -420,6 +468,7 @@ criterion_group!( bench_roundtrip, bench_track_recv, bench_stamp, - bench_relay_frames + bench_relay_frames, + bench_inflate ); criterion_main!(benches); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 29abae75ae5..a1305df7a61 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -53,6 +53,7 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr timestamp: None, }, fields, + inflated: None, }; let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); frame.write(payload.clone()).unwrap(); @@ -150,8 +151,8 @@ where /// [`roundtrip`] for a datagram body, which runs to the end of its buffer. fn datagram(data: &[u8], version: lite::Version) -> bool { - // The body doesn't say whether it carries a timestamp, or whether the session - // negotiated the `ietf` extension, so try every reading. + // The body doesn't say whether it carries a timestamp or an inflated size, or whether + // the session negotiated the `ietf` extension, so try every reading. let ietf: &[bool] = match version.has_ietf() { true => &[false, true], false => &[false], @@ -159,18 +160,22 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { let mut any = false; for &ietf in ietf { for timescale in [Some(crate::Timescale::MILLI), None] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| timescale) else { - continue; - }; - any = true; + for compressed in [false, true] { + let format = lite::Format { timescale, compressed }; + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| format) + else { + continue; + }; + any = true; - let Ok(first) = decoded.encode_bytes(version) else { - continue; - }; + let Ok(first) = decoded.encode_bytes(version) else { + continue; + }; - let echo = - lite::Datagram::decode(first, version, ietf, |_| timescale).expect("could not decode our own encoding"); - assert_eq!(echo, decoded, "datagram did not survive a round trip"); + let echo = lite::Datagram::decode(first, version, ietf, |_| format) + .expect("could not decode our own encoding"); + assert_eq!(echo, decoded, "datagram did not survive a round trip"); + } } } any @@ -444,6 +449,7 @@ impl LiteSample { subscribe: 3, sequence: 1_234, timestamp: Some(1_234_567_890), + inflated: None, payload: bytes::Bytes::new(), ietf: None, } @@ -477,11 +483,14 @@ impl LiteSample { } Self::Group => lite::Group::decode(r, version).map(|_| 1).unwrap(), Self::Subscribe => lite::Subscribe::decode(r, version).map(|_| 1).unwrap(), - Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, false, |_| { - Some(crate::Timescale::MILLI) - }) - .map(|_| 1) - .unwrap(), + Self::Datagram => { + lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, false, |_| lite::Format { + timescale: Some(crate::Timescale::MILLI), + compressed: false, + }) + .map(|_| 1) + .unwrap() + } Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), } } @@ -645,6 +654,7 @@ impl Default for Messages { priority: 1, max_age: Some(Duration::from_secs(10)), timescale: Some(crate::Timescale::MICRO), + compress: false, }, lite_group: lite::Group { subscribe: 7, diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 4e7d6e9ef59..b38dc760571 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -90,6 +90,8 @@ fn rendezvous_error(error: Error, requested: bool, resolved: bool) -> Error { if requested && missing { Error::Timeout } else { error } } +// Returned from one poll and matched at once, so its size never sits in a task. +#[allow(clippy::large_enum_variant)] enum FillStep { Batch, Partial(frame::Consumer), diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index d590a411019..6bec992b6f9 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4138,6 +4138,7 @@ where status, properties, })), + deflated: None, })?; Ok(()) } @@ -4842,6 +4843,7 @@ where let header = frame::Header { info: frame::Info { size, timestamp }, fields, + inflated: None, }; let mut frame = producer.create_frame_owned(header, &self.frames)?; if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { @@ -5575,7 +5577,11 @@ impl GroupIngest { properties: std::mem::take(&mut self.properties), }) }); - Ok(frame::Header { info, fields }) + Ok(frame::Header { + info, + fields, + inflated: None, + }) } /// `Ready(Ok(_))` once the stream FINs on an object boundary, or an explicit diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 3b243b0f4fd..d418cef2a04 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -1,10 +1,11 @@ //! Wire-level QUIC datagram body for moq-lite-05 (§6.4). //! //! One datagram carries a single-frame group routed over an existing subscription. The body is -//! `subscribe (i) | sequence (i) | [timestamp (i)] | payload (b)`, with the timestamp present only -//! when the subscription's track carries one (see [`Version::wire_timescale`]). The payload runs to -//! the datagram boundary, so unlike a [`super::Message`] there is no inner length prefix. The model -//! counterpart is [`crate::Datagram`]. +//! `subscribe (i) | sequence (i) | [timestamp (i)] | [inflated size (i)] | payload (b)`, with the +//! timestamp present only when the subscription's track carries one (see +//! [`Version::wire_timescale`]) and the inflated size only when it is compressed (lite-07). The +//! payload runs to the datagram boundary, so unlike a [`super::Message`] there is no inner length +//! prefix. The model counterpart is [`crate::Datagram`]. use crate::Timescale; use bytes::Bytes; @@ -23,6 +24,9 @@ pub struct Datagram { /// Absolute presentation timestamp in the track's wire timescale, or `None` on a track /// that carries no timestamps. pub timestamp: Option, + /// On a compressed track, the payload's inflated size; the payload is then its own + /// DEFLATE stream. + pub inflated: Option, /// The frame payload, delimited by the datagram boundary. pub payload: Bytes, /// With the `ietf` extension negotiated, the moq-transport state a relay preserves, or @@ -30,6 +34,16 @@ pub struct Datagram { pub ietf: Option>, } +/// What a datagram body carries beyond its payload, which the subscription's track decides +/// and the body itself does not say. +#[derive(Clone, Copy, Debug, Default)] +pub struct Format { + /// The units of the track's timestamps, or `None` when it carries none. + pub timescale: Option, + /// The track is compressed, so the payload's inflated size precedes it. + pub compressed: bool, +} + impl Encode for Datagram { fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { if !version.has_datagrams() { @@ -41,6 +55,10 @@ impl Encode for Datagram { return Err(EncodeError::Version); } + if self.inflated.is_some() && !version.has_compression() { + return Err(EncodeError::Version); + } + w.varint(self.subscribe)?; w.varint(self.sequence)?; if let Some(wire) = &self.ietf { @@ -50,7 +68,7 @@ impl Encode for Datagram { // Any status object carries no payload, which moq-transport could not send beside // it, and a non-zero one carries no object and so no time either. let status = wire.as_ref().and_then(|wire| wire.status); - if status.is_some() && !self.payload.is_empty() + if status.is_some() && (!self.payload.is_empty() || self.inflated.is_some()) || status.is_some_and(|status| status != 0) && self.timestamp.is_some() { return Err(EncodeError::InvalidState); @@ -60,6 +78,9 @@ impl Encode for Datagram { if let Some(timestamp) = self.timestamp { w.varint(timestamp)?; } + if let Some(inflated) = self.inflated { + w.varint(inflated)?; + } // Payload runs to the datagram boundary: written raw, no length prefix. w.slice(&self.payload); @@ -70,14 +91,13 @@ impl Encode for Datagram { impl Datagram { /// Decode a whole datagram body. The payload shares `buf` rather than copying it. /// - /// `ietf` says whether the session negotiated the extension, and `timescale` gives the - /// units of the track of the given subscribe ID, if it is timed, which the body itself - /// does not say. + /// `ietf` says whether the session negotiated the extension, and `format` what the track + /// of the given subscribe ID carries, which the body itself does not say. pub fn decode( buf: Bytes, version: Version, ietf: bool, - timescale: impl FnOnce(u64) -> Option, + format: impl FnOnce(u64) -> Format, ) -> Result { if !version.has_datagrams() || (ietf && !version.has_ietf()) { return Err(DecodeError::Version); @@ -86,7 +106,7 @@ impl Datagram { let mut r = Decoder::new(&buf, version.into()); let subscribe = r.varint()?; let sequence = r.varint()?; - let timescale = timescale(subscribe); + let Format { timescale, compressed } = format(subscribe); let ietf = ietf .then(|| super::ietf::decode_datagram(&mut r, timescale, version)) .transpose()?; @@ -101,6 +121,11 @@ impl Datagram { } else { None }; + // A status has no payload to inflate. + let inflated = match compressed && version.has_compression() && status.is_none() { + true => Some(r.varint()?), + false => None, + }; // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); @@ -112,6 +137,7 @@ impl Datagram { subscribe, sequence, timestamp, + inflated, payload, ietf, }) @@ -122,17 +148,54 @@ impl Datagram { mod test { use super::*; + const TIMED: Format = Format { + timescale: Some(Timescale::MILLI), + compressed: false, + }; + + const COMPRESSED: Format = Format { + timescale: Some(Timescale::MILLI), + compressed: true, + }; + + /// A compressed track's inflated size sits between the timestamp and the payload. + #[test] + fn compressed_carries_the_inflated_size() { + let dg = Datagram { + subscribe: 1, + sequence: 2, + timestamp: Some(3), + inflated: Some(40), + payload: Bytes::from_static(b"slice"), + ietf: None, + }; + let buf = dg.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(&buf[..4], [1, 2, 3, 40]); + assert_eq!( + Datagram::decode(buf, Version::Lite07, false, |_| COMPRESSED).unwrap(), + dg + ); + + for version in [Version::Lite05, Version::Lite06] { + assert!( + matches!(dg.encode_bytes(version), Err(EncodeError::Version)), + "{version}" + ); + } + } + #[test] fn roundtrip() { let original = Datagram { subscribe: 7, sequence: 42, timestamp: Some(1_000), + inflated: None, payload: Bytes::from_static(b"hello"), ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| TIMED).unwrap(); assert_eq!(decoded, original, "payload has no trailing length prefix"); } @@ -142,11 +205,12 @@ mod test { subscribe: 0, sequence: 0, timestamp: Some(0), + inflated: None, payload: Bytes::new(), ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| TIMED).unwrap(); assert_eq!(decoded, original); } @@ -158,6 +222,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: Some(3), + inflated: None, payload: Bytes::from_static(b"world"), ietf: None, }; @@ -173,6 +238,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: None, + inflated: None, payload: Bytes::from_static(b"world"), ietf: None, }; @@ -181,7 +247,7 @@ mod test { assert_eq!(&buf[2..], b"world"); let decoded = Datagram::decode(buf, Version::Lite07, false, |id| { assert_eq!(id, 1); - None + Format::default() }) .unwrap(); assert_eq!(decoded, dg); @@ -193,6 +259,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: None, + inflated: None, payload: Bytes::from_static(b"world"), ietf: None, }; @@ -212,6 +279,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: Some(500), + inflated: None, payload: Bytes::from_static(b"x"), ietf: Some(Some(crate::model::datagram::Wire { object_id: None, @@ -233,14 +301,15 @@ mod test { }; let decode = |dg: Datagram| { let buf = dg.encode_bytes(Version::Lite07).unwrap(); - Datagram::decode(buf, Version::Lite07, true, |_| Some(Timescale::MILLI)) + Datagram::decode(buf, Version::Lite07, true, |_| TIMED) }; assert!(decode(dg(0x20)).is_ok()); assert!(matches!(decode(dg(0x10)), Err(DecodeError::InvalidValue))); } /// A Normal status (0) is an empty object, which moq-transport sends as a status with - /// no payload, so a STATUS field beside a payload is refused whatever its value. + /// no payload, so a STATUS field beside a payload, or its inflated size, is refused + /// whatever its value. #[test] fn a_status_carries_no_payload() { for status in [0, 3] { @@ -248,6 +317,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: (status == 0).then_some(500), + inflated: None, payload: Bytes::from_static(payload), ietf: Some(Some(crate::model::datagram::Wire { object_id: None, @@ -262,16 +332,23 @@ mod test { "{status}" ); let empty = dg(b""); + let sized = Datagram { + inflated: Some(0), + ..empty.clone() + }; + assert!( + matches!(sized.encode_bytes(Version::Lite07), Err(EncodeError::InvalidState)), + "{status}" + ); let mut buf = empty.encode_bytes(Version::Lite07).unwrap().to_vec(); - let decoded = Datagram::decode(Bytes::from(buf.clone()), Version::Lite07, true, |_| { - Some(Timescale::MILLI) - }) - .unwrap(); - assert_eq!(decoded, empty, "{status}"); + for format in [TIMED, COMPRESSED] { + let decoded = Datagram::decode(Bytes::from(buf.clone()), Version::Lite07, true, |_| format).unwrap(); + assert_eq!(decoded, empty, "{status}"); + } buf.push(b'x'); assert!( matches!( - Datagram::decode(Bytes::from(buf), Version::Lite07, true, |_| Some(Timescale::MILLI)), + Datagram::decode(Bytes::from(buf), Version::Lite07, true, |_| TIMED), Err(DecodeError::InvalidValue) ), "{status}" @@ -285,15 +362,14 @@ mod test { subscribe: 1, sequence: 2, timestamp: Some(3), + inflated: None, payload: Bytes::from_static(b"x"), ietf: None, }; assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| Some( - Timescale::MILLI - )), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| TIMED), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index e52389bb764..c5e32a0def9 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -1043,6 +1043,7 @@ mod hop_tests { timestamp: Some(ts(millis)), }, fields: fields.map(Arc::new), + inflated: None, }, &frame::Budget::default(), ) @@ -1415,4 +1416,49 @@ mod hop_tests { assert!(datagram.wire.is_none()); drop(sessions); } + + /// A compressed track crosses a negotiated hop as stored: each frame's Inflated Size + /// follows its Object Record, and a datagram's follows its Datagram State. + #[moq_clock::test] + async fn compressed_media_crosses_a_negotiated_hop() { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let info = track::Info::timed() + .with_timescale(Timescale::MILLI) + .with_compress(true); + let mut track = broadcast.create_track("video", info).unwrap(); + let (downstream, sessions) = test_hop(&upstream, "room", [true, true]).await; + let (_copy, mut subscriber) = subscribe(&downstream).await; + assert!(subscriber.info().compress); + + let payload = |n: u8| vec![n; 300]; + let mut group = track.append_group().unwrap(); + group.write_frame(ts(5), payload(1)).unwrap(); + group.write_frame(ts(6), payload(2)).unwrap(); + group.finish().unwrap(); + let mut received = recv(&mut subscriber).await; + for (millis, n) in [(5, 1), (6, 2)] { + let frame = next(&mut received).await.unwrap(); + assert_eq!( + (frame.timestamp, &frame.payload[..]), + (Some(ts(millis)), &payload(n)[..]) + ); + assert!(frame.fields.is_none()); + } + assert!(next(&mut received).await.is_none()); + + track.insert_datagram(7, ts(9), payload(3)).unwrap(); + let datagram = moq_clock::timeout( + TIMEOUT, + kio::wait(|waiter| subscriber.poll_recv_stored_datagram(waiter)), + ) + .await + .expect("no datagram") + .unwrap() + .unwrap(); + assert_eq!((datagram.sequence, datagram.timestamp), (7, Some(ts(9)))); + assert_eq!(&datagram.payload[..], &payload(3)[..]); + assert!(datagram.deflated.is_some() && datagram.wire.is_none()); + drop(sessions); + } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 63504585370..1200012429b 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1962,6 +1962,8 @@ impl Request for TrackInfoServe { priority: info.priority, max_age: info.max_age, timescale: info.timescale, + // An older peer is served the frames inflated. + compress: info.compress && shared.version.has_compression(), })?; if ietf { writer.buffer(&lite::ietf::TrackProperties(info.properties.clone()))?; @@ -2009,7 +2011,7 @@ impl Request for TracksServe { fn poll( &mut self, - _: &Shared, + shared: &Shared, writer: &mut Writer, waiter: &kio::Waiter, ) -> Poll, Error>> { @@ -2024,6 +2026,8 @@ impl Request for TracksServe { priority: info.priority, max_age: info.max_age, timescale: info.timescale, + // An older peer is served the frames inflated. + compress: info.compress && shared.version.has_compression(), }, }, Some(crate::broadcast::TracksEvent::Removed { name }) => lite::TracksEvent::Removed { @@ -2245,7 +2249,7 @@ enum FetchServe { }, } -/// A batch of frames with their relay metadata, which the `ietf` extension forwards. +/// A batch of frames read for egress, each with what the wire needs beside it. type Objects = arrayvec::ArrayVec; impl Request for FetchServe { @@ -2312,6 +2316,10 @@ impl Request for FetchServe { // Matches the timescale TRACK_INFO declared for the track. let timescale = shared.version.wire_timescale(group.timescale()); + // And its compression, which a lite-07 peer receives as stored. + if shared.version.has_compression() { + group = group.compressed(); + } let capped = msg.end_frame.is_some(); let records = lite::ietf::Records::start(writer, ietf, &group, capped, timescale, shared.version)?; @@ -2357,8 +2365,9 @@ impl Request for FetchServe { } buffer_frame_info( writer, - batched.timestamp, - batched.payload.len() as u64, + batched.frame.timestamp, + batched.inflated, + batched.frame.payload.len() as u64, *timescale, prev_ts, &shared.runtime, @@ -2392,6 +2401,7 @@ impl Request for FetchServe { buffer_frame_info( writer, next.timestamp, + next.inflated, next.size, *timescale, prev_ts, @@ -3349,6 +3359,7 @@ mod announce_test { fn buffer_frame_info( writer: &mut Writer, timestamp: Option, + inflated: Option, size: u64, timescale: Option, prev_ts: &mut u64, @@ -3357,6 +3368,10 @@ fn buffer_frame_info( if let Some(timescale) = timescale { buffer_zigzag_delta(writer, wire_timestamp(timestamp, timescale, runtime)?, prev_ts)?; } + // Only a compressed group read in its stored form has one, and only on lite-07. + if let Some(inflated) = inflated { + writer.buffer_varint(inflated)?; + } writer.buffer_varint(size)?; Ok(()) } @@ -3443,7 +3458,7 @@ fn poll_recv_next( Poll::Pending => {} } if datagrams { - match track.poll_recv_wire_datagram(waiter)? { + match track.poll_recv_stored_datagram(waiter)? { Poll::Ready(Some(datagram)) => return Poll::Ready(Ok(Recv::Datagram(datagram))), // Datagram side finished but groups are still paused/pending: keep waiting on groups. Poll::Ready(None) => {} @@ -3652,11 +3667,14 @@ impl Subscription { (true, Some(wire)) => Some(Some(wire.as_ref().clone())), }; let sequence = datagram.sequence; + // A lite-07 peer takes a compressed track's datagram as stored, others inflated. + let (payload, inflated) = datagram.sent(self.version.has_compression()); let body = lite::Datagram { subscribe: self.id, sequence, timestamp, - payload: datagram.datagram.payload, + inflated, + payload: payload.clone(), ietf, }; // has_datagrams is checked before this runs, and the timescale is set wherever the @@ -3920,7 +3938,7 @@ impl TrackRun { Poll::Pending => { self.first = Some(group); if self.datagrams - && let Poll::Ready(Some(datagram)) = self.track.poll_recv_wire_datagram(waiter)? + && let Poll::Ready(Some(datagram)) = self.track.poll_recv_stored_datagram(waiter)? { self.serve_datagram(datagram); return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -4041,6 +4059,9 @@ impl TrackRun { /// Send a datagram, recording its sequence once it went out. fn serve_datagram(&mut self, datagram: crate::model::datagram::Stored) { let sequence = datagram.sequence; + // Metered in the form the wire carries. + let (payload, _) = datagram.sent(self.ctx.version.has_compression()); + self.track.meter_datagram(payload.len() as u64); if self.ctx.serve_datagram(datagram) { self.mark_served(sequence); } @@ -4247,6 +4268,11 @@ impl GroupServe { rank: Rank>, group: group::Consumer, ) -> Self { + // A lite-07 peer receives a compressed group as stored, others inflated. + let group = match ctx.version.has_compression() { + true => group.compressed(), + false => group, + }; Self { ctx, rank, @@ -4443,8 +4469,9 @@ impl GroupServe { .and_then(|()| { buffer_frame_info( writer, - batched.timestamp, - batched.payload.len() as u64, + batched.frame.timestamp, + batched.inflated, + batched.frame.payload.len() as u64, self.ctx.timescale, &mut self.prev_ts, &self.ctx.runtime, @@ -4489,6 +4516,7 @@ impl GroupServe { buffer_frame_info( writer, next.timestamp, + next.inflated, next.size, self.ctx.timescale, &mut self.prev_ts, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 2254f3c7014..4b882f0f2fa 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -511,8 +511,12 @@ impl Subscriber { }; let mut subscribes = self.subscribes.lock(); // An unknown subscription's datagram is dropped below, however it parses. - let dg = lite::Datagram::decode(payload, self.version, ietf, |id| { - subscribes.get(&id).and_then(|entry| entry.timescale) + let dg = lite::Datagram::decode(payload, self.version, ietf, |id| match subscribes.get(&id) { + Some(entry) => lite::Format { + timescale: entry.timescale, + compressed: entry.producer.info().compress, + }, + None => lite::Format::default(), })?; let Some(entry) = subscribes.get_mut(&dg.subscribe) else { // Unknown or already-closed subscription: drop the datagram. @@ -533,15 +537,19 @@ impl Subscriber { // A datagram says where the live feed is as well as a group does. Inserted first, so // the copy goes live with it already showing. let live = entry.producer.is_live(); - let wire = dg.ietf.flatten().map(Arc::new); - entry.producer.insert_wire_datagram(crate::model::datagram::Stored { + let datagram = crate::model::datagram::Stored { datagram: crate::Datagram { sequence: dg.sequence, timestamp, payload: dg.payload, }, - wire, - })?; + wire: dg.ietf.flatten().map(Arc::new), + deflated: None, + }; + match dg.inflated { + Some(size) => entry.producer.insert_deflated_datagram(datagram, size)?, + None => entry.producer.insert_wire_datagram(datagram)?, + } if !live { entry.producer.set_live(Some(Position::group(dg.sequence))); } @@ -1059,9 +1067,15 @@ enum IngestPhase { /// Reading the timestamp delta (skipped without a timescale). Stream end here /// means the group has no more frames. Timing, + /// Reading a compressed Track's inflated size (lite-07), or skipped. Stream end here + /// also ends the group on an untimed Track, where nothing precedes it. + Inflated { timestamp: Option }, /// Reading the frame size. Stream end here also ends the group (pre-lite-05, /// where there is no timing prefix to act as the sentinel). - Size { timestamp: Option }, + Size { + timestamp: Option, + inflated: Option, + }, /// Streaming the frame payload. Payload { frame: frame::ProducerOwned }, } @@ -1189,7 +1203,7 @@ impl FrameIngest { } IngestPhase::Timing => { let Some(scale) = self.timescale else { - self.phase = IngestPhase::Size { timestamp: None }; + self.phase = IngestPhase::Inflated { timestamp: None }; continue; }; // The timestamp delta doubles as the per-frame sentinel. @@ -1202,12 +1216,30 @@ impl FrameIngest { self.prev_ts = next; let timestamp = Timestamp::new(next, scale) .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?; - self.phase = IngestPhase::Size { + self.phase = IngestPhase::Inflated { timestamp: Some(timestamp), }; } - IngestPhase::Size { timestamp } => { + IngestPhase::Inflated { timestamp } => { let timestamp = *timestamp; + // Only a compressed Track carries it, and only lite-07 can mark one. + if !group.compressed() { + self.phase = IngestPhase::Size { + timestamp, + inflated: None, + }; + continue; + } + let Some(inflated) = ready!(self.poll_header_varint(reader, &mut cx))? else { + return Poll::Ready(Ok(())); + }; + self.phase = IngestPhase::Size { + timestamp, + inflated: Some(inflated), + }; + } + IngestPhase::Size { timestamp, inflated } => { + let (timestamp, inflated) = (*timestamp, *inflated); let Some(size) = ready!(self.poll_header_varint(reader, &mut cx))? else { return Poll::Ready(Ok(())); }; @@ -1230,10 +1262,13 @@ impl FrameIngest { // oversized `size` and allocates up front only within the budget, so // no pre-check is needed. No wire timestamp (pre-lite-05) means an // untimed frame. + // A compressed frame stores the slice as it arrives, its inflated size + // checked against the same limits before anything inflates. let frame = group.create_frame_owned( frame::Header { info: frame::Info { size, timestamp }, fields, + inflated, }, &self.budget, )?; @@ -1784,7 +1819,8 @@ impl TracksRecv { .with_timescale(info.timescale) .with_max_age(info.max_age) .with_priority(info.priority) - .with_refresh(info.refresh); + .with_refresh(info.refresh) + .with_compress(info.compress); source.lister.add(name.clone(), info)?; self.listed.insert(name, slot); } @@ -3232,6 +3268,7 @@ mod tests { sequence, timestamp: Some(sequence), payload: bytes::Bytes::from_static(b"x"), + inflated: None, ietf: None, } .encode_bytes(VERSION) @@ -6399,7 +6436,8 @@ impl TrackInfoFetch { .with_timescale(info.timescale) .with_max_age(info.max_age) .with_priority(info.priority) - .with_refresh(info.refresh); + .with_refresh(info.refresh) + .with_compress(info.compress); if !ietf { return Poll::Ready(Ok((model, HeldTrack(stream)))); } diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index a2a5f5ca5f1..6c7f27e8908 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -70,8 +70,17 @@ pub struct TrackInfo { /// Lite07 encodes `None` as zero; Lite05/06 have no untimed encoding, so `None` /// goes out as milliseconds (see [`Version::wire_timescale`]). pub timescale: Option, + /// Whether FRAME payloads and datagrams are DEFLATE compressed per group, the only codec + /// the wire's `Compression` id names. Lite07+ only: an earlier peer is served the frames + /// inflated, so it is never set. + pub compress: bool, } +/// TRACK_INFO `Compression`: no codec. +const COMPRESSION_NONE: u64 = 0; +/// TRACK_INFO `Compression`: per-group DEFLATE (draft-lcurley-moq-flate). +const COMPRESSION_DEFLATE: u64 = 1; + impl Message for TrackInfo { fn decode_msg(r: &mut Decoder<'_>, version: Version) -> Result { if !version.has_track_stream() { @@ -100,12 +109,21 @@ impl Message for TrackInfo { .map_err(|_| DecodeError::InvalidValue)?, false => None, }; + let compress = match version.has_compression() { + true => match r.varint()? { + COMPRESSION_NONE => false, + COMPRESSION_DEFLATE => true, + _ => return Err(DecodeError::InvalidValue), + }, + false => false, + }; Ok(Self { priority, refresh, max_age, timescale, + compress, }) } @@ -127,6 +145,15 @@ impl Message for TrackInfo { if version.has_refresh() { w.varint(self.refresh.map_or(0, |ratio| u64::from(ratio) + 1))?; } + if version.has_compression() { + w.varint(match self.compress { + true => COMPRESSION_DEFLATE, + false => COMPRESSION_NONE, + })?; + } else if self.compress { + // The frames would arrive compressed with nothing saying so. + return Err(EncodeError::Version); + } Ok(()) } } @@ -141,6 +168,7 @@ mod test { priority: 7, max_age: Some(Duration::from_millis(2000)), timescale: Some(Timescale::MICRO), + compress: false, } } @@ -244,6 +272,7 @@ mod test { max_age: info.max_age, // The default track is untimed, which lite-05 declares as milliseconds. timescale: info.timescale, + compress: false, }; let mut buf = Vec::new(); info.encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05) @@ -295,6 +324,55 @@ mod test { } } + #[test] + fn lite07_carries_the_compression_codec() { + for compress in [false, true] { + let info = TrackInfo { + compress, + ..info_sample() + }; + let buf = info.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(buf.last(), Some(&u8::from(compress))); + assert_eq!(info_roundtrip(Version::Lite07, &info).compress, compress); + } + + // The message body, without its length prefix, ends in the codec id. + let mut buf = Vec::new(); + TrackInfo { + compress: true, + ..info_sample() + } + .encode_msg(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) + .unwrap(); + // An unknown codec id, still a one-byte varint. + *buf.last_mut().unwrap() = 2; + let mut slice = buf.as_slice(); + assert!(matches!( + crate::coding::decode_buf(&mut slice, Version::Lite07, TrackInfo::decode_msg), + Err(DecodeError::InvalidValue) + )); + } + + /// An older peer cannot be told, so a compressed track is never described to one. + #[test] + fn compression_needs_lite07() { + let info = TrackInfo { + compress: true, + ..info_sample() + }; + for version in [Version::Lite05, Version::Lite06] { + assert!( + matches!(info.encode_bytes(version), Err(EncodeError::Version)), + "{version}" + ); + let plain = TrackInfo { + compress: false, + ..info_sample() + }; + assert!(!info_roundtrip(version, &plain).compress); + } + } + #[test] fn track_info_errors_before_lite05() { let mut buf = Vec::new(); @@ -312,6 +390,7 @@ mod test { priority: 255, max_age: None, timescale: Some(Timescale::new((1u64 << 62) - 1).unwrap()), + compress: false, }; let got = info_roundtrip(Version::Lite05, &info); assert_eq!(got.priority, 255); @@ -326,6 +405,7 @@ mod test { priority: 0, max_age: Some(Duration::from_nanos(999_999)), timescale: Some(Timescale::MILLI), + compress: false, }; let got = info_roundtrip(Version::Lite05, &info); assert_eq!(got.max_age, Some(Duration::ZERO)); @@ -339,6 +419,7 @@ mod test { priority: 7, max_age: Some(Duration::from_millis(u64::MAX)), timescale: Some(Timescale::MILLI), + compress: false, }; // The partial bytes are the Writer's to drop; see `a_failed_encode_leaves_no_partial_bytes`. assert!(matches!( diff --git a/rs/moq-net/src/lite/tracks.rs b/rs/moq-net/src/lite/tracks.rs index c39fdeb40cb..5528b29a837 100644 --- a/rs/moq-net/src/lite/tracks.rs +++ b/rs/moq-net/src/lite/tracks.rs @@ -131,6 +131,7 @@ mod test { priority: 3, max_age: Some(Duration::from_secs(2)), timescale: Some(Timescale::MICRO), + compress: true, }; let TracksEvent::Added { name, info: got } = roundtrip(&TracksEvent::Added { name: "video".into(), @@ -143,6 +144,7 @@ mod test { assert_eq!(got.priority, 3); assert_eq!(got.max_age, Some(Duration::from_secs(2))); assert_eq!(got.timescale, Some(Timescale::MICRO)); + assert!(got.compress); let TracksEvent::Removed { name } = roundtrip(&TracksEvent::Removed { name: "video".into() }) else { panic!("expected a removal"); diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 543028c8419..eaa4fa71586 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -260,6 +260,18 @@ impl Version { } } + /// Whether TRACK_INFO carries the compression flag, and a compressed Track's FRAME + /// and datagram its inflated size. Added in lite-07; an earlier peer receives the + /// frames inflated. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_compression(self) -> bool { + // Match form so future versions default forward (AGENTS.md convention). + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 => false, + _ => true, + } + } + /// Whether the stream error table has NOT_FETCHABLE, for a FETCH that reached a /// datagram. Added in lite-07; earlier versions say NOT_FOUND instead. #[allow(clippy::match_like_matches_macro)] diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 13d42ee35c8..74c5f73868c 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1121,6 +1121,14 @@ impl Charge { self.access.clone() } + /// An [`Extra`] against this charge's account, detached when the charge is. + pub(super) fn extra(&self) -> Extra { + Extra { + track: self.track.clone(), + bytes: AtomicU64::new(0), + } + } + /// Tick of the group's last cache access. pub(super) fn accessed(&self) -> u64 { self.access.get() @@ -1199,6 +1207,67 @@ impl Drop for Charge { } } +/// Bytes a group keeps beside its cached frames, billed to the same pool and account as +/// its [`Charge`] but reachable outside the group's write lock: a compressed group's +/// inflated copy, which its readers build, and its codec state. Released on [`Self::clear`] or drop. +/// +/// Its owner serializes the changes; the count is atomic so the eviction walk can size +/// the group without that owner's lock. +#[derive(Default)] +pub(super) struct Extra { + track: Option>, + bytes: AtomicU64, +} + +impl Extra { + /// Bill `n` more bytes. + pub(super) fn add(&self, n: u64) { + if let Some(track) = &self.track { + track.pool.add(n); + track.written.fetch_add(n, Ordering::Relaxed); + self.bytes.fetch_add(n, Ordering::Relaxed); + } + } + + /// Settle the track's eviction debt, taking its lock: call with no group lock held. + pub(super) fn settle(&self) { + if let Some(track) = &self.track { + track.settle(None); + } + } + + /// Bytes currently billed. + pub(super) fn size(&self) -> u64 { + self.bytes.load(Ordering::Relaxed) + } + + /// Release `n` billed bytes. + pub(super) fn sub(&self, n: u64) { + if let Some(track) = &self.track { + let prior = self + .bytes + .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |bytes| { + Some(bytes.saturating_sub(n)) + }) + .expect("always updates"); + track.pool.sub(prior.min(n)); + } + } + + /// Release every billed byte. + pub(super) fn clear(&self) { + if let Some(track) = &self.track { + track.pool.sub(self.bytes.swap(0, Ordering::Relaxed)); + } + } +} + +impl Drop for Extra { + fn drop(&mut self) { + self.clear(); + } +} + #[cfg(test)] mod test { use super::*; diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index 479dfb510c8..75fbee36e10 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -57,11 +57,36 @@ pub(crate) struct Wire { pub(crate) struct Stored { pub datagram: Datagram, pub wire: Option>, + /// On a compressed track, the payload as its own DEFLATE stream: a datagram is a + /// one-frame group, so it compresses with a fresh window. Kept beside the inflated + /// `datagram.payload`, since both are small and short-lived. + pub deflated: Option, +} + +impl Stored { + /// The payload a session sends, with its inflated size when that is the DEFLATE slice: + /// only a session that carries `compression` takes a compressed track's stored form. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + pub fn sent(&self, compression: bool) -> (&Bytes, Option) { + match &self.deflated { + Some(deflated) if compression => (deflated, Some(self.datagram.payload.len() as u64)), + _ => (&self.datagram.payload, None), + } + } + + /// The bytes the track stores and meters: the DEFLATE slice when it has one. + pub fn stored_len(&self) -> u64 { + self.deflated.as_ref().unwrap_or(&self.datagram.payload).len() as u64 + } } impl From for Stored { fn from(datagram: Datagram) -> Self { - Self { datagram, wire: None } + Self { + datagram, + wire: None, + deflated: None, + } } } diff --git a/rs/moq-net/src/model/flate.rs b/rs/moq-net/src/model/flate.rs new file mode 100644 index 00000000000..14a139e027f --- /dev/null +++ b/rs/moq-net/src/model/flate.rs @@ -0,0 +1,237 @@ +//! The DEFLATE codec behind compressed tracks ([`crate::track::Info::compress`]). +//! +//! Each group is one raw DEFLATE stream ([RFC 1951]) with a sync flush after every frame, so +//! each frame's slice is self-delimited while later frames compress against earlier ones. +//! A sync flush always ends in the marker `00 00 ff ff`, which [`Encoder::frame`] drops and +//! [`Decoder::frame`] re-appends, the same trick as [RFC 7692]. The format is +//! draft-lcurley-moq-flate. +//! +//! [RFC 1951]: https://www.rfc-editor.org/rfc/rfc1951.html +//! [RFC 7692]: https://www.rfc-editor.org/rfc/rfc7692.html#section-7.2.1 + +use bytes::Bytes; +use flate2::{Compress, Decompress, FlushCompress, FlushDecompress, Status}; + +use crate::{Error, Result}; + +/// zlib's default level: a good size/speed balance for small, repetitive payloads. +const LEVEL: u32 = 6; + +/// The trailing bytes of a DEFLATE sync flush, stripped on the wire and re-appended to decode. +const SYNC_FLUSH_TAIL: [u8; 4] = [0x00, 0x00, 0xff, 0xff]; + +/// Scratch buffer size for the streaming (de)compress loops. +const CHUNK: usize = 8 * 1024; + +/// The DEFLATE window, 2^15 bytes for raw DEFLATE at the default `windowBits`. +const WINDOW: u64 = 1 << 15; + +/// Heap an [`Encoder`] holds, as zlib sizes it at the default `memLevel` of 8: the doubled +/// window, its `prev` chain and hash `head` tables, and the pending buffer, 64 KiB each. +pub(super) const ENCODER_HEAP: u64 = 8 * WINDOW; + +/// Heap a [`Decoder`] holds: the window, plus its inflate state rounded up to 8 KiB. +pub(super) const DECODER_HEAP: u64 = WINDOW + 8 * 1024; + +/// Compresses a group's frames into one shared window, one slice per frame. +// Boxed: zlib-rs keeps its stream header inline, which would bloat the group state. +pub(super) struct Encoder(Box); + +impl Encoder { + /// A fresh encoder with a cold window. + pub(super) fn new() -> Self { + // `false`: raw DEFLATE, no zlib header/trailer, matching `deflate-raw` in browsers. + Self(Box::new(Compress::new(flate2::Compression::new(LEVEL), false))) + } + + /// Compress the next frame, returning its slice minus the sync-flush marker. Empty in + /// yields empty out, leaving the window untouched. + pub(super) fn frame(&mut self, payload: &[u8]) -> Bytes { + if payload.is_empty() { + return Bytes::new(); + } + + let mut out = Vec::with_capacity(payload.len() / 2 + 16); + let mut tmp = [0u8; CHUNK]; + let mut input = payload; + + // Keep going while the output buffer fills up: the classic zlib loop. + loop { + let before_in = self.0.total_in(); + let before_out = self.0.total_out(); + self.0.compress(input, &mut tmp, FlushCompress::Sync).expect("deflate"); + let consumed = (self.0.total_in() - before_in) as usize; + let produced = (self.0.total_out() - before_out) as usize; + out.extend_from_slice(&tmp[..produced]); + input = &input[consumed..]; + if produced < tmp.len() { + break; + } + } + + // A missing marker means the backend returned before finishing the flush; panic + // rather than emit a truncated frame. + assert!( + out.ends_with(&SYNC_FLUSH_TAIL), + "a sync flush must end in the deflate marker" + ); + out.truncate(out.len() - SYNC_FLUSH_TAIL.len()); + Bytes::from(out) + } +} + +/// Inflates a group's slices back into frames, in order. +pub(super) struct Decoder(Box); + +impl Decoder { + /// A fresh decoder with a cold window. + pub(super) fn new() -> Self { + Self(Box::new(Decompress::new(false))) + } + + /// Inflate the next frame's `slice`, which must produce exactly `size` bytes. + /// + /// Output grows as it is produced and stops at `size`, so a slice that inflates past + /// its declaration costs no more than the declaration. [`Error::WrongSize`] if the + /// output differs from `size`, [`Error::MalformedTrack`] if the slice is not DEFLATE or + /// ends the stream, which a group never does. + pub(super) fn frame(&mut self, slice: &[u8], size: usize) -> Result { + if slice.is_empty() { + return match size { + 0 => Ok(Bytes::new()), + _ => Err(Error::WrongSize), + }; + } + + let mut out = Vec::new(); + let mut tmp = [0u8; CHUNK]; + + // Feed the slice followed by the re-appended marker, which ends the frame and + // flushes its last bytes out of the inflate buffer. + for segment in [slice, &SYNC_FLUSH_TAIL] { + let mut input = segment; + loop { + let before_in = self.0.total_in(); + let before_out = self.0.total_out(); + let status = self + .0 + .decompress(input, &mut tmp, FlushDecompress::Sync) + .map_err(|_| Error::MalformedTrack)?; + // A final block would let trailing bytes and every later frame go unread. + if matches!(status, Status::StreamEnd) { + return Err(Error::MalformedTrack); + } + let consumed = (self.0.total_in() - before_in) as usize; + let produced = (self.0.total_out() - before_out) as usize; + if out.len() + produced > size { + return Err(Error::WrongSize); + } + out.extend_from_slice(&tmp[..produced]); + input = &input[consumed..]; + + if input.is_empty() && produced < tmp.len() { + break; + } + // No progress: the marker needed no further output. + if consumed == 0 && produced == 0 { + break; + } + } + } + + if out.len() != size { + return Err(Error::WrongSize); + } + Ok(Bytes::from(out)) + } +} + +#[cfg(test)] +mod test { + use super::*; + + /// Deterministic high-entropy bytes: they barely compress, so slices outgrow `CHUNK`. + fn noise(len: usize) -> Vec { + let mut state: u64 = 0x9E37_79B9_7F4A_7C15; + (0..len) + .map(|_| { + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + (state >> 56) as u8 + }) + .collect() + } + + #[test] + fn frames_roundtrip_against_a_shared_window() { + let frames: &[&[u8]] = &[b"the quick brown fox", b"", b"the quick brown dog", b"the lazy fox"]; + let mut enc = Encoder::new(); + let slices: Vec = frames.iter().map(|f| enc.frame(f)).collect(); + let mut dec = Decoder::new(); + for (frame, slice) in frames.iter().zip(&slices) { + assert_eq!(dec.frame(slice, frame.len()).unwrap(), *frame); + } + } + + #[test] + fn a_repeat_frame_reuses_the_window() { + let payload = b"Media over QUIC delivers real-time latency at massive scale.".repeat(6); + let mut enc = Encoder::new(); + let first = enc.frame(&payload); + let second = enc.frame(&payload); + assert!(second.len() < first.len()); + } + + /// High-entropy frames straddling a block boundary still round-trip byte for byte, and + /// their slices outgrow the scratch buffer so both loops iterate. + #[test] + fn incompressible_frames_roundtrip() { + let lens: Vec = (31 * 1024..32 * 1024 + 256).step_by(64).collect(); + let noise = noise(lens.iter().sum()); + let mut enc = Encoder::new(); + let mut dec = Decoder::new(); + let mut rest = noise.as_slice(); + for len in lens { + let (frame, next) = rest.split_at(len); + rest = next; + let slice = enc.frame(frame); + assert!(slice.len() > CHUNK); + assert!(dec.frame(&slice, len).unwrap() == frame, "{len} byte frame corrupted"); + } + } + + /// The declared size bounds the output both ways. + #[test] + fn the_declared_size_must_match() { + let payload = vec![0u8; 1024]; + let slice = Encoder::new().frame(&payload); + assert!(matches!(Decoder::new().frame(&slice, 512), Err(Error::WrongSize))); + assert!(matches!(Decoder::new().frame(&slice, 2048), Err(Error::WrongSize))); + assert!(matches!(Decoder::new().frame(b"", 1), Err(Error::WrongSize))); + } + + /// A final block is malformed even when it inflates to the declared size. + #[test] + fn a_final_block_is_malformed() { + let payload = b"the quick brown fox"; + let mut compress = Compress::new(flate2::Compression::new(LEVEL), false); + let mut slice = Vec::with_capacity(64); + let status = compress + .compress_vec(payload, &mut slice, FlushCompress::Finish) + .unwrap(); + assert!(matches!(status, Status::StreamEnd)); + assert!(matches!( + Decoder::new().frame(&slice, payload.len()), + Err(Error::MalformedTrack) + )); + } + + #[test] + fn garbage_is_malformed() { + assert!(matches!( + Decoder::new().frame(b"not a deflate stream at all", 64), + Err(Error::MalformedTrack) + )); + } +} diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 0846c7ff098..2080c7e2968 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -55,6 +55,9 @@ pub struct Frame { pub(crate) struct Object { pub frame: Frame, pub fields: Option>, + /// The inflated size of a compressed frame read in its stored form (see + /// [`group::Consumer::compressed`]), whose `payload` is then the DEFLATE slice. + pub inflated: Option, } #[cfg(feature = "async")] @@ -70,11 +73,18 @@ impl std::ops::Deref for Object { pub(crate) struct Header { pub info: Info, pub fields: Option>, + /// A received compressed frame's inflated size: `info.size` is then its DEFLATE + /// slice's. `None` for a plain frame, or one a local producer compresses itself. + pub inflated: Option, } impl From for Header { fn from(info: Info) -> Self { - Self { info, fields: None } + Self { + info, + fields: None, + inflated: None, + } } } @@ -750,6 +760,11 @@ pub struct Consumer { #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: passthrough pub(crate) fields: Option>, + /// The inflated size of a compressed frame read in its stored form (see + /// [`group::Consumer::compressed`]), whose payload is then the DEFLATE slice. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: passthrough + pub(crate) inflated: Option, source: Source, // Byte offset consumed so far. read_idx: usize, @@ -779,6 +794,7 @@ impl Consumer { state, info: header.info, fields: header.fields, + inflated: header.inflated, source, read_idx: 0, stats: stats::Meter::default(), @@ -836,6 +852,11 @@ impl Consumer { if let Some(expiry) = &mut self.expiry { expiry.policy = expiry.policy.for_track(&replacement.copy); } + // A stored compressed frame continues from the replacement's stored form, where + // the byte offset means the same thing. + if self.inflated.is_some() { + replacement.group = replacement.group.compressed(); + } let frame = match replacement.group.poll_next_frame(waiter) { Poll::Ready(Ok(Some(frame))) => frame, Poll::Ready(Ok(None)) => return Poll::Ready(Err(Error::WrongSize)), @@ -853,7 +874,7 @@ impl Consumer { return Poll::Ready(Err(Error::Unsupported)); } // Same name, same content: a different size is the routes disagreeing. - if frame.info.size != self.info.size { + if frame.info.size != self.info.size || frame.inflated != self.inflated { return Poll::Ready(Err(Error::ProtocolViolation)); } recover.adopt(&replacement); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index a6737f39043..6b9f12c909d 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -14,14 +14,16 @@ //! bounds group sequences. //! //! The stream is closed with [Error] when all writers or readers are dropped. +use super::flate; use crate::cache; use crate::frame::{self, Frame, FrameBuf}; use crate::{Cap, Timescale, stats, track}; +use bytes::Bytes; use std::collections::VecDeque; use std::mem::MaybeUninit; use std::ops::{Bound, RangeBounds}; -use std::sync::atomic::{AtomicBool, Ordering}; -use std::sync::{Arc, Mutex, PoisonError, Weak}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError, Weak}; use std::task::{Poll, ready}; use crate::{Error, IntoBytes, Result, Timestamp}; @@ -130,6 +132,11 @@ pub(super) struct Partial { buf: FrameBuf, // How much of `buf` has been charged to the cache so far. charged: u64, + // A received DEFLATE slice's inflated size, on a compressed group. + inflated: Option, + // Plain bytes a local producer streams into a compressed group: compressed when the + // frame commits, so no reader sees them, and uncharged until then. + scratch: bool, } /// Shared group state. Model-visible so [`frame`] handles can observe the abort flag @@ -137,10 +144,13 @@ pub(super) struct Partial { #[derive(Default)] pub(super) struct GroupState { // Completed frames, each a contiguous payload. `offset` is the first frame this - // handle holds, raised by [`Producer::start_at`]. + // handle holds, raised by [`Producer::start_at`]. A compressed group stores DEFLATE + // slices here. pub(super) frames: VecDeque, // IETF relay state, boxed so a group that never carries any pays one pointer. relay: Option>, + // Compressed-track state, boxed so a plain group pays one pointer. + flate: Option>, // The single in-flight frame, if one is open. pub(super) partial: Option, @@ -206,6 +216,9 @@ pub(super) struct Head { frames: Vec, // Relay metadata for `frames`, at the same index; frames past its end carry none. objects: Vec>>, + // A compressed group's inflated sizes for `frames`, at the same index; `None` for a + // plain group. + sizes: Option>, } /// A copy's [`Head`], shared by every reader that could resume its group elsewhere. @@ -256,7 +269,8 @@ impl Head { let payload: u64 = self.frames.iter().map(|frame| frame.payload.len() as u64).sum(); let fields: u64 = self.objects.iter().flatten().map(|fields| fields.heap()).sum(); let slots = self.frames.len() * size_of::() - + self.objects.len() * size_of::>>(); + + self.objects.len() * size_of::>>() + + self.sizes.as_ref().map_or(0, |sizes| sizes.len() * size_of::()); payload + fields + slots as u64 } } @@ -274,6 +288,218 @@ struct Relay { bytes: u64, } +/// What a compressed group keeps beside its stored DEFLATE slices. +struct Flate { + // Each completed frame's inflated size, at the same local index as `frames`. + sizes: VecDeque, + // The inflated size of every frame admitted so far, held to the budget a plain + // group's bytes are, so a declaration is refused before anything inflates. + inflated: u64, + // Compresses a local producer's frames, created by its first write. A received group + // stores what arrived and never recompresses. + encoder: Option, + // The inflated copy every plain reader shares, built on first demand. + plain: Arc, +} + +impl Flate { + fn new(bill: cache::Extra) -> Self { + Self { + sizes: VecDeque::new(), + inflated: 0, + encoder: None, + plain: Arc::new(Plain { + len: AtomicUsize::new(0), + bill, + state: Mutex::new(PlainState::default()), + }), + } + } + + /// Record a completed local frame's inflated size. + fn push(&mut self, size: u64) { + self.sizes.push_back(size); + self.inflated += size; + } + + /// Compress a locally written frame, returning its stored slice. + fn deflate(&mut self, payload: &[u8]) -> Bytes { + let plain = &self.plain; + let encoder = self.encoder.get_or_insert_with(|| { + plain.bill.add(flate::ENCODER_HEAP); + flate::Encoder::new() + }); + encoder.frame(payload) + } + + /// Drop the codec state once no frame follows at `fin`: the encoder, and the decoder if + /// its readers already inflated every frame. + fn finish(&mut self, fin: usize) { + if self.encoder.take().is_some() { + self.plain.bill.sub(flate::ENCODER_HEAP); + } + let mut plain = self.plain.lock(); + plain.fin = Some(fin); + if plain.frames.len() == fin { + self.plain.drop_decoder(&mut plain); + } + } + + /// Drop everything but how the group is read, failing a late inflater with `err`. + fn release(&mut self, err: Error) { + self.sizes = VecDeque::new(); + self.encoder = None; + self.plain.release(err); + } +} + +/// A compressed group's inflated copy, shared by its plain readers. +/// +/// A reader takes the slices it needs under the group's guard and inflates them under +/// only this lock ([`Inflate`]), so a cold read never holds up the group's writer. +struct Plain { + // Frames inflated so far, so a reader under the group's guard takes only the slices + // past it without waiting on an inflater. + len: AtomicUsize, + // The inflated bytes and the group's codec state, counted toward its eviction size + // once they exist. Changed only under `state`, or the group's lock for the encoder. + bill: cache::Extra, + state: Mutex, +} + +#[derive(Default)] +struct PlainState { + // Inflates the stored slices in order. Dropped once a finished group is fully inflated. + decoder: Option, + // Inflated frames, from the group's first. + frames: VecDeque, + // The group's frame count once finished, so the decoder drops after the last frame. + // Kept here rather than taken with the slices, which may predate the finish. + fin: Option, + // The first failure, sticky: every later frame builds on the one that failed. + err: Option, + // Why the group released its frames, failing a late inflater rather than billing past + // the release. + released: Option, +} + +impl Plain { + fn lock(&self) -> MutexGuard<'_, PlainState> { + self.state.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// Drop `state`'s decoder, which no frame needs any more. + fn drop_decoder(&self, state: &mut PlainState) { + if state.decoder.take().is_some() { + self.bill.sub(flate::DECODER_HEAP); + } + } + + /// Inflated local frame `local`, or why it is not. + fn get(&self, local: usize) -> Result { + let state = self.lock(); + match state.frames.get(local) { + Some(frame) => Ok(frame.clone()), + None => Err(state + .released + .clone() + .or_else(|| state.err.clone()) + .unwrap_or(Error::Dropped)), + } + } + + /// Whether inflating failed on the group's content, rather than its release. + fn malformed(&self) -> bool { + let state = self.lock(); + state.released.is_none() && state.err.is_some() + } + + fn release(&self, err: Error) { + let mut state = self.lock(); + state.decoder = None; + state.frames = VecDeque::new(); + state.released = Some(err); + self.len.store(0, Ordering::Release); + self.bill.clear(); + } +} + +/// The stored slices a plain read of a compressed group inflates once the group's guard +/// is released. +struct Inflate { + plain: Arc, + // Local index of the first slice: the copy's inflated length when the read took them. + from: usize, + // Each slice with its declared inflated size. + slices: Vec<(Bytes, u64)>, +} + +impl Inflate { + /// Inflate the slices, skipping any a concurrent reader already did, then read local + /// frames back with [`Self::get`]. `meter` counts the bytes this read inflated. + /// + /// Locks per frame, so a release waits on at most one frame's inflation. Call with no + /// lock held, since settling the debt takes the track's. + fn run(&self, meter: &stats::Meter) { + for (index, (slice, size)) in (self.from..).zip(&self.slices) { + let mut state = self.plain.lock(); + if state.released.is_some() || state.err.is_some() { + break; + } + if state.frames.len() > index { + continue; + } + let frame = usize::try_from(*size) + .map_err(|_| Error::FrameTooLarge) + .and_then(|size| { + let bill = &self.plain.bill; + let decoder = state.decoder.get_or_insert_with(|| { + bill.add(flate::DECODER_HEAP); + flate::Decoder::new() + }); + decoder.frame(slice, size) + }); + match frame { + Ok(frame) => { + self.plain.bill.add(frame.len() as u64); + meter.inflated(frame.len() as u64); + state.frames.push_back(frame); + self.plain.len.store(state.frames.len(), Ordering::Release); + if state.fin == Some(state.frames.len()) { + self.plain.drop_decoder(&mut state); + } + } + Err(err) => { + state.err = Some(err); + self.plain.drop_decoder(&mut state); + break; + } + } + } + // The inflated bytes are written like a producer's, so they pay the pool's debt the + // same way: a finished track has no writer left to settle it. + self.plain.bill.settle(); + } + + /// Inflated local frame `local`, or why it is not. + fn get(&self, local: usize) -> Result { + self.plain.get(local) + } +} + +/// A frame resolved under the group's guard, by [`GroupState::poll_frame_source`]. +enum Source { + /// Ready to hand out. + Ready(frame::Header, frame::Source), + /// A plain read of a compressed group: local frame `local` once `job` inflates it. + Inflate { + job: Inflate, + local: usize, + timestamp: Option, + fields: Option>, + }, +} + /// The IETF header state that cannot be inferred from a plain frame list. #[cfg_attr(not(feature = "async"), allow(dead_code))] #[derive(Clone, Debug)] @@ -332,6 +558,11 @@ impl GroupState { } } + /// Whether a compressed group's content failed to inflate. + fn malformed(&self) -> bool { + self.flate.as_ref().is_some_and(|flate| flate.plain.malformed()) + } + /// Whether the first frame opened, or the group ended without one. fn started(&self) -> bool { !matches!(self.timeline, Timeline::Empty) || self.fin.is_some() || self.abort.is_some() @@ -388,9 +619,39 @@ impl GroupState { } } + /// Refuse admitting `extra` more inflated bytes past the group budget, on a compressed + /// group. The declaration is checked like a plain frame's size, before anything inflates. + fn inflated_overflow(&self, extra: u64) -> bool { + self.flate + .as_ref() + .is_some_and(|flate| flate.inflated.saturating_add(extra) > MAX_CACHE_BYTES) + } + + /// The slices a plain read of a compressed group still needs inflated to reach local + /// frame `last`, to inflate once the guard is released. + /// + /// [`Error::Lagged`] when the group started past frame 0: its first slice builds on + /// frames it never held. + fn inflate(&self, flate: &Flate, last: usize) -> Result { + if self.offset != 0 { + return Err(Error::Lagged); + } + let from = flate.plain.len.load(Ordering::Acquire).min(last + 1); + Ok(Inflate { + plain: flate.plain.clone(), + from, + slices: (from..=last) + .map(|local| (self.frames[local].payload.clone(), flate.sizes[local])) + .collect(), + }) + } + /// Resolve the source for the frame at `index`: a completed frame (whole) or the /// in-flight tail (streamed). Used by [`Consumer::poll_next_frame`]. - fn poll_frame_source(&self, index: usize) -> Poll>> { + /// + /// A compressed group hands a plain reader each frame whole once it completes, as the + /// slices to inflate, and a `raw` one the stored slice, streaming one still arriving. + fn poll_frame_source(&self, index: usize, raw: bool) -> Poll>> { if index < self.offset { return Poll::Ready(Err(Error::Lagged)); } @@ -399,30 +660,46 @@ impl GroupState { // A frame read is a cache access: stamp it so expiry and the eviction // walk spare a group a consumer is actively draining. self.charge.refresh(); + let inflated = match &self.flate { + Some(flate) if !raw => { + return Poll::Ready(Ok(Some(Source::Inflate { + job: self.inflate(flate, local)?, + local, + timestamp: f.timestamp, + fields: self.fields(local), + }))); + } + Some(flate) => Some(flate.sizes[local]), + None => None, + }; let info = frame::Info { size: f.payload.len() as u64, timestamp: f.timestamp, }; - return Poll::Ready(Ok(Some(( + return Poll::Ready(Ok(Some(Source::Ready( frame::Header { info, fields: self.fields(local), + inflated, }, frame::Source::Complete(f.payload.clone()), )))); } if local == self.frames.len() && let Some(p) = &self.partial + && !p.scratch + && (raw || self.flate.is_none()) { self.charge.refresh(); let info = frame::Info { size: p.buf.size() as u64, timestamp: p.timestamp, }; - return Poll::Ready(Ok(Some(( + return Poll::Ready(Ok(Some(Source::Ready( frame::Header { info, fields: p.fields.clone(), + inflated: p.inflated, }, frame::Source::Partial(p.buf.clone()), )))); @@ -554,6 +831,8 @@ impl GroupState { /// Returns the coarse tick it stamped, like [`cache::Charge::add`]. fn charge_partial(&mut self) -> Option { let written = match &mut self.partial { + // Scratch is charged as the slice it commits as. + Some(partial) if partial.scratch => 0, Some(partial) => { let written = partial.buf.written(Ordering::Acquire) as u64; written - std::mem::replace(&mut partial.charged, written) @@ -588,6 +867,7 @@ impl GroupState { .relay .as_ref() .map_or_else(Vec::new, |relay| relay.objects.iter().cloned().collect()), + sizes: self.flate.as_ref().map(|flate| flate.sizes.iter().copied().collect()), }) } @@ -608,11 +888,15 @@ impl GroupState { .relay .as_mut() .map_or_else(Vec::new, |relay| std::mem::take(&mut relay.objects).into()), + sizes: self.flate.as_mut().map(|flate| std::mem::take(&mut flate.sizes).into()), }); self.frames = VecDeque::new(); self.partial = None; self.cache = 0; self.charge.clear(); + if let Some(flate) = &mut self.flate { + flate.release(self.abort.clone().unwrap_or(Error::Dropped)); + } // The header state and terminal object outlive the frames. if let Some(relay) = &mut self.relay { relay.objects = VecDeque::new(); @@ -818,7 +1102,13 @@ impl Producer { let state = kio::Producer::::default(); let charge = cache.charge(); let access = charge.access(); - state.write().ok().expect("a new group is open").charge = charge; + { + let mut state = state.write().ok().expect("a new group is open"); + if track.compress { + state.flate = Some(Box::new(Flate::new(charge.extra()))); + } + state.charge = charge; + } let alive = Arc::new(Alive { aborted: AtomicBool::new(false), checked: AtomicBool::new(false), @@ -856,6 +1146,14 @@ impl Producer { self.handle.track.timescale } + /// Whether the parent track compresses, so a received frame arrives as a stored slice + /// with its inflated size ([`frame::Header::inflated`]). + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // pending: /quest/m1/public-model/ingest.md + pub(crate) fn compressed(&self) -> bool { + self.handle.track.compress + } + /// The track to check this group's start against, while frame 0 may still be unwritten. /// /// The caller holds its lock until the frame is recorded, so the check and the stamp are @@ -930,14 +1228,22 @@ impl Producer { state.admit(next_index)?; let origin = state.check_start(neighbors.as_ref(), timestamp)?; debug_assert!(state.partial.is_none(), "a frame is already open"); + let inflated = payload.len() as u64; + let payload = match &mut state.flate { + Some(flate) => flate.deflate(&payload), + None => payload, + }; let size = payload.len() as u64; - if state.would_overflow(1, size) { + if state.would_overflow(1, size) || state.inflated_overflow(inflated) { return Err(self.abort_too_large(state)); } state.cache += size; let slots = state.reserve_frame(); let now = state.charge.add(size + slots); state.frames.push_back(Frame { timestamp, payload }); + if let Some(flate) = &mut state.flate { + flate.push(inflated); + } state.next_index = next_index; state.committed = state.next_index; state.stamp(timestamp); @@ -1006,16 +1312,30 @@ impl Producer { )?, None => state.origin, }; - if state.would_overflow(count, bytes) { + // A compressed group stores slices, compressed aside so a refused batch is untouched. + let mut deflated = arrayvec::ArrayVec::::new(); + if let Some(flate) = &mut state.flate { + deflated.extend(frames.filled().iter().map(|frame| flate.deflate(&frame.payload))); + } + let stored = match state.flate.is_some() { + true => deflated.iter().map(|slice| slice.len() as u64).sum(), + false => bytes, + }; + if state.would_overflow(count, stored) || state.inflated_overflow(bytes) { return Err(self.abort_too_large(state)); } // The last frame's tick, reused below so settling does not re-read the clock. let mut now = None; let mut latest = None; + let mut deflated = deflated.into_iter(); for mut frame in frames.drain() { frame.timestamp = on_track(frame.timestamp, self.handle.track.timescale).expect("timestamp scale checked above"); + if let Some(flate) = &mut state.flate { + flate.push(frame.payload.len() as u64); + frame.payload = deflated.next().expect("one slice per frame"); + } let size = frame.payload.len() as u64; state.cache += size; let slots = state.reserve_frame(); @@ -1043,7 +1363,7 @@ impl Producer { self.handle.cache.wakes().presented(latest); } self.stats.frames(count as u64); - self.stats.bytes(bytes); + self.stats.bytes(stored); Ok(()) } @@ -1059,7 +1379,7 @@ impl Producer { // The buffer allocates on its first write, so refusing the frame costs nothing. let buf = FrameBuf::new(frame.size as usize); let info = self.open_frame(frame.into(), &buf)?; - let meter = self.stats.clone(); + let meter = self.chunk_meter(None); Ok(frame::Producer::new(self, buf, info).with_meter(meter)) } @@ -1077,6 +1397,7 @@ impl Producer { budget: &frame::Budget, ) -> Result { let frame = frame.into(); + let meter = self.chunk_meter(frame.inflated); let size = frame.info.size as usize; let reserved = budget.reserve(size); let buf = match reserved { @@ -1090,10 +1411,19 @@ impl Producer { return Err(err); } }; - let meter = self.stats.clone(); Ok(frame::ProducerOwned::new(self, buf, info, reserved).with_meter(meter)) } + /// The meter a streamed frame's chunks bump: none for a plain frame a compressed group + /// compresses on commit, which counts its stored slice then, as `bytes` counts payload + /// as stored. + fn chunk_meter(&self, inflated: Option) -> stats::Meter { + match self.handle.track.compress && inflated.is_none() { + true => stats::Meter::default(), + false => self.stats.clone(), + } + } + /// Open `buf` as the in-flight frame, returning its header in the track's timescale. /// /// Its bytes are charged to the cache as they are written, not here: the declared @@ -1101,9 +1431,16 @@ impl Producer { fn open_frame(&mut self, header: frame::Header, buf: &FrameBuf) -> Result { let frame = header.info; let timestamp = on_track(frame.timestamp, self.handle.track.timescale)?; - if frame.size > MAX_CACHE_BYTES { + if frame.size > MAX_CACHE_BYTES || header.inflated.is_some_and(|inflated| inflated > MAX_CACHE_BYTES) { return Err(Error::FrameTooLarge); } + // Only a compressed group takes a stored slice, and every frame a local producer + // streams into one is plain until it commits. + if header.inflated.is_some() && !self.handle.track.compress { + return Err(Error::ProtocolViolation); + } + let scratch = self.handle.track.compress && header.inflated.is_none(); + let inflated = header.inflated.unwrap_or(frame.size); let track = self.first_frame_track(); let track = track.as_ref().map(|track| track.read()); @@ -1124,15 +1461,20 @@ impl Producer { // Only one frame is ever in flight, so the declared size is the most the cache // can grow by before the next check. let metadata_bytes = header.fields.as_ref().map_or(0, |fields| fields.heap()); - if state.would_overflow(1, frame.size.saturating_add(metadata_bytes)) { + if state.would_overflow(1, frame.size.saturating_add(metadata_bytes)) || state.inflated_overflow(inflated) { return Err(self.abort_too_large(state)); } + if let (Some(flate), Some(inflated)) = (&mut state.flate, header.inflated) { + flate.inflated += inflated; + } let now = state.charge.record_write(); state.partial = Some(Partial { timestamp, fields: header.fields, buf: buf.clone(), charged: 0, + inflated: header.inflated, + scratch, }); if metadata_bytes > 0 { state.relay().bytes += metadata_bytes; @@ -1205,8 +1547,27 @@ impl Producer { // that arrives and completes in one turn never reaches [`Self::frame_notify`]. // Without this, a group whose payload streamed in across an idle gap would expire // the instant it finished. - let now = state.charge_partial(); - if let Some(fields) = state.partial.take().and_then(|partial| partial.fields) { + let mut now = state.charge_partial(); + let partial = state.partial.take(); + let mut frame = frame; + if partial.as_ref().is_some_and(|partial| partial.scratch) { + let flate = state.flate.as_mut().expect("scratch only opens on a compressed group"); + let inflated = frame.payload.len() as u64; + frame.payload = flate.deflate(&frame.payload); + flate.push(inflated); + let size = frame.payload.len() as u64; + // The frame already counts against the group's frames. + if state.would_overflow(0, size) { + return Err(self.abort_too_large(state)); + } + state.cache += size; + now = state.charge.add(size); + self.stats.bytes(size); + } else if let (Some(flate), Some(inflated)) = (&mut state.flate, partial.as_ref().and_then(|p| p.inflated)) { + // Admitted against the budget when it opened. + flate.sizes.push_back(inflated); + } + if let Some(fields) = partial.and_then(|partial| partial.fields) { // The slot was reserved and charged by `charge_partial` above. let len = state.frames.len(); let objects = &mut state.relay().objects; @@ -1245,7 +1606,12 @@ impl Producer { pub fn finish(&mut self) -> Result<()> { let mut state = modify(&self.handle.state)?; debug_assert!(state.partial.is_none(), "a frame is already open"); - state.fin = Some(state.next_index); + let fin = state.next_index; + state.fin = Some(fin); + // No frame follows to compress. + if let Some(flate) = &mut state.flate { + flate.finish(fin); + } // A finished group can no longer raise the track's largest, which may end its stream. self.handle.cache.finish_largest(self.sequence); Ok(()) @@ -1348,15 +1714,16 @@ impl Handle { /// /// A no-op unless `head` starts below this copy and reaches it, and the frames fit the /// group's budget. Readers keep their positions, since frames keep their indices. A - /// group whose frames build on earlier ones (a compressed group) primes its decoder - /// from the adopted frames here. + /// compressed group adopts only a compressed head, taking its inflated sizes beside the + /// slices, so its plain readers inflate from the adopted frames. pub(super) fn adopt_head(&self, head: &Head) { let Ok(mut state) = self.state.write() else { return; }; let offset = state.offset; let reaches = head.start.saturating_add(head.frames.len()) >= offset; - if state.abort.is_some() || state.sparse() || head.start >= offset || !reaches { + let same_form = head.sizes.is_some() == state.flate.is_some(); + if state.abort.is_some() || state.sparse() || !same_form || head.start >= offset || !reaches { return; } let count = offset - head.start; @@ -1364,11 +1731,19 @@ impl Handle { let fields = || head.objects.iter().take(count).flatten(); let payload: u64 = frames.iter().map(|frame| frame.payload.len() as u64).sum(); let metadata: u64 = fields().map(|fields| fields.heap()).sum(); + let sizes = head.sizes.as_ref().map(|sizes| &sizes[..count]); + let inflated: u64 = sizes.into_iter().flatten().sum(); // The in-flight frame's remainder was admitted at its open and is charged as it // streams in, without another check. - if state.would_overflow(count, payload + metadata + state.unwritten()) { + if state.would_overflow(count, payload + metadata + state.unwritten()) || state.inflated_overflow(inflated) { return; } + if let (Some(flate), Some(sizes)) = (&mut state.flate, sizes) { + for size in sizes.iter().rev() { + flate.sizes.push_front(*size); + } + flate.inflated += inflated; + } let before = state.frames.capacity().saturating_sub(FRAME_SLOTS); state.frames.reserve(count); @@ -1593,10 +1968,12 @@ impl Handle { } } - /// The group's full cached footprint (payload plus fixed overhead), used by the - /// track to size this group as an eviction victim. + /// The group's full cached footprint (payload plus fixed overhead, and a compressed + /// group's inflated copy as far as it is built), used by the track to size this group + /// as an eviction victim. pub(super) fn cache_size(&self) -> u64 { - self.state.read().charge.size() + let state = self.state.read(); + state.charge.size() + state.flate.as_ref().map_or(0, |flate| flate.plain.bill.size()) } /// Whether the payload cached after the first frame exceeds `ratio` times the first @@ -1665,6 +2042,7 @@ impl Handle { index: 0, end: None, prefetch: Prefetch::default(), + raw: false, cache: self.cache.clone(), access: self.alive.access.clone(), refreshed: self.cache.pool().now(), @@ -1824,6 +2202,8 @@ struct Prefetch { frames: [MaybeUninit; Self::CAP], // Relay metadata for `frames`, allocated by the first batch that carries any. fields: Option>; Self::CAP]>>, + // Inflated sizes for `frames`, filled only by a batch of a compressed group's stored slices. + inflated: Option>, pos: usize, len: usize, } @@ -1831,6 +2211,11 @@ struct Prefetch { impl Prefetch { const CAP: usize = 8; + /// The inflated size of the stored slice [`Self::pop`] just returned. + fn take_inflated(&self) -> Option { + self.inflated.as_ref()?.get(self.pos.checked_sub(1)?).copied() + } + /// Take the next buffered frame, or `None` if the batch is drained. fn pop(&mut self) -> Option { if self.pos == self.len { @@ -1849,14 +2234,32 @@ impl Prefetch { /// Refill with up to `budget` of the completed frames from `local` on. Must be /// drained first (`pop` returned `None`). - fn fill(&mut self, state: &GroupState, local: usize, budget: usize) { + /// + /// A compressed group fills its stored slices, with `raw` their inflated sizes beside + /// them, and otherwise returns the job [`Self::inflate`] runs once the guard is released. + fn fill(&mut self, state: &GroupState, local: usize, budget: usize, raw: bool) -> Result> { debug_assert_eq!(self.pos, self.len, "fill on a non-empty batch would leak frames"); self.pos = 0; self.len = 0; - for frame in state.frames.range(local..).take(budget.min(Self::CAP)) { + let count = state.frames.len().saturating_sub(local).min(budget).min(Self::CAP); + // Taken before any slot is written, so a refusal leaves the batch empty. + let job = match &state.flate { + Some(flate) if !raw && count > 0 => Some(state.inflate(flate, local + count - 1)?), + _ => None, + }; + for frame in state.frames.range(local..local + count) { self.frames[self.len].write(frame.clone()); self.len += 1; } + match &state.flate { + Some(flate) if raw => { + let inflated = self.inflated.get_or_insert_default(); + for (slot, size) in inflated.iter_mut().zip(flate.sizes.range(local..local + self.len)) { + *slot = *size; + } + } + _ => self.inflated = None, + } // Plain frames never reach the metadata table, so they skip this entirely. if local < state.objects() { let fields = self.fields.get_or_insert_default(); @@ -1866,6 +2269,28 @@ impl Prefetch { } else if let Some(fields) = &mut self.fields { fields.fill(None); } + Ok(job) + } + + /// Replace a filled batch's stored slices, from local frame `local`, with their inflated + /// frames. A frame that fails to inflate ends the batch, failing it if first. + fn inflate(&mut self, job: &Inflate, local: usize, meter: &stats::Meter) -> Result<()> { + job.run(meter); + for i in self.pos..self.len { + match job.get(local + i) { + // SAFETY: slots in `pos..len` are initialized (written by `fill`, not yet popped). + Ok(payload) => unsafe { self.frames[i].assume_init_mut() }.payload = payload, + Err(err) => { + for slot in &mut self.frames[i..self.len] { + // SAFETY: as above, and `len` drops below them right after. + unsafe { slot.assume_init_drop() }; + } + self.len = i; + return if i == self.pos { Err(err) } else { Ok(()) }; + } + } + } + Ok(()) } /// `(frame count, total payload bytes)` of the buffered, not-yet-taken frames. @@ -1885,6 +2310,7 @@ impl Default for Prefetch { Self { frames: [const { MaybeUninit::uninit() }; Self::CAP], fields: None, + inflated: None, pos: 0, len: 0, } @@ -1959,6 +2385,9 @@ struct Cursor { // A batch of completed frames drained ahead under one lock (whole-frame reads only). prefetch: Prefetch, + // Read a compressed group's stored slices rather than its inflated copy. + raw: bool, + // Record prefetched reads without entering the group's state on every frame. cache: Arc, access: Arc, @@ -1974,6 +2403,7 @@ impl Clone for Cursor { index: self.index, end: self.end, prefetch: Prefetch::default(), + raw: self.raw, cache: self.cache.clone(), access: self.access.clone(), refreshed: self.refreshed, @@ -2024,6 +2454,17 @@ impl Consumer { self.cursor.state.read().wire().cloned() } + /// Read a compressed group's stored DEFLATE slices instead of plain frames, with each + /// frame's inflated size beside it ([`frame::Object::inflated`], + /// [`frame::Consumer::inflated`]), for egress that carries compression. A no-op on a + /// plain group. + // private: passthrough + pub(crate) fn compressed(mut self) -> Self { + self.cursor.raw = true; + self.cursor.prefetch = Prefetch::default(); + self + } + /// The index of the first frame the group holds (see [`Producer::start_at`]). // private: passthrough pub(crate) fn first_frame(&self) -> u64 { @@ -2134,6 +2575,8 @@ impl Consumer { self.recover = None; return res; } + // Content that failed to inflate is the group's under its name, so no copy fixes it. + Poll::Ready(Err(_)) if !self.cursor.raw && self.cursor.state.read().malformed() => return res, Poll::Ready(Err(err)) => Some(err.clone()), Poll::Pending => None, }; @@ -2149,14 +2592,23 @@ impl Consumer { Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => return Poll::Pending, }; + // A plain read inflates from frame 0, which a replacement starting later lacks + // when the failed route's head was not lent to it. + if !self.cursor.raw + && replacement.group.first_frame() > 0 + && replacement.group.cursor.state.read().flate.is_some() + { + return Poll::Ready(Err(failed.unwrap_or(Error::Lagged))); + } // Same frames by index, so only the channel changes; read progress and the // cap stay this cursor's. - let (index, end) = (self.cursor.index, self.cursor.end); + let (index, end, raw) = (self.cursor.index, self.cursor.end, self.cursor.raw); recover.adopt(&replacement); self.expiry = self.expiry.as_ref().map(|expiry| expiry.for_track(&replacement.copy)); self.cursor = replacement.group.cursor; self.cursor.index = index; self.cursor.end = end; + self.cursor.raw = raw; self.adopted = true; } } @@ -2343,6 +2795,7 @@ impl Consumer { Poll::Ready(Ok(frame.map(|frame| frame::Object { frame, fields: self.cursor.prefetch.take_fields(), + inflated: self.cursor.prefetch.take_inflated(), }))) } @@ -2542,6 +2995,7 @@ impl Cursor { let header = frame::Header { info, fields: self.prefetch.take_fields(), + inflated: self.prefetch.take_inflated(), }; let frame = frame::Consumer::new(self.state.clone(), header, source); return Poll::Ready(Ok(Some(match expiry { @@ -2550,10 +3004,33 @@ impl Cursor { }))); } - let index = self.index; - let Some((info, source)) = ready!(self.poll(waiter, |state| state.poll_frame_source(index))?) else { + let (index, raw) = (self.index, self.raw); + let Some(source) = ready!(self.poll(waiter, |state| state.poll_frame_source(index, raw))?) else { return Poll::Ready(Ok(None)); }; + // Inflated with the group's guard released. + let (info, source) = match source { + Source::Ready(info, source) => (info, source), + Source::Inflate { + job, + local, + timestamp, + fields, + } => { + job.run(stats); + let payload = job.get(local)?; + let info = frame::Info { + size: payload.len() as u64, + timestamp, + }; + let header = frame::Header { + info, + fields, + inflated: None, + }; + (header, frame::Source::Complete(payload)) + } + }; self.index += 1; // A direct read (not prefetched): count the frame here; the frame::Consumer @@ -2585,6 +3062,7 @@ impl Cursor { // come from the shared state then, not from a batch drained under the old cap. let budget = self.end.map_or(usize::MAX, |end| end.saturating_sub(index)); let prefetch = &mut self.prefetch; + let raw = self.raw; let res = self.state.poll(waiter, |state| { if index < state.offset { return Poll::Ready(Err(Error::Lagged)); @@ -2594,20 +3072,22 @@ impl Cursor { // out-of-bounds start. `fill` always resets the batch, so an empty range // leaves `len == 0` and the terminal checks below resolve abort/fin/pending. let local = (index - state.offset).min(state.frames.len()); - prefetch.fill(state, local, budget); + let job = prefetch.fill(state, local, budget, raw)?; if prefetch.len > 0 { // One stamp covers the whole batch: frames popped from the prefetch // don't re-stamp until the next refill, which `CAP` bounds. state.charge.refresh(); - return Poll::Ready(Ok(())); + return Poll::Ready(Ok(job)); } // Nothing completed at `index`: an in-flight tail waits, otherwise resolve // the terminal state (whole-frame reads never stream the partial). - state.poll_terminal(index) + state.poll_terminal(index).map_ok(|()| None) }); match ready!(res) { - Ok(Ok(())) => {} + // Inflated with the group's guard released. Only a group from frame 0 inflates. + Ok(Ok(Some(job))) => self.prefetch.inflate(&job, index, stats)?, + Ok(Ok(None)) => {} Ok(Err(err)) => return Poll::Ready(Err(err)), Err(state) => return Poll::Ready(Err(state.abort.clone().unwrap_or(Error::Dropped))), } @@ -2725,6 +3205,7 @@ mod test { id: id * 10, properties: Default::default(), })), + inflated: None, }; let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); frame.write(Bytes::from_static(b"f")).unwrap(); @@ -3251,6 +3732,7 @@ mod test { payload: Bytes::from_static(b"ab"), }], objects: Vec::new(), + sizes: None, }; adopter.adopt_head(&head); assert_eq!( @@ -3285,6 +3767,7 @@ mod test { }, ], objects: vec![None, fields(1)], + sizes: None, }; let wire = Wire { sparse: false, @@ -4093,6 +4576,355 @@ mod test { assert_eq!(third.allocated(), 1024, "the finished frame did not return its share"); } + /// A repetitive frame DEFLATE shrinks, distinct per index. + fn verbose(index: usize) -> Bytes { + Bytes::from(format!("{index}:{}", "moq".repeat(300))) + } + + fn untimed(size: usize) -> frame::Info { + frame::Info { + size: size as u64, + timestamp: None, + } + } + + fn compressed_group(pool: &cache::Pool) -> Producer { + let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + Producer::new(Info::from(0u64), track::Info::default().with_compress(true), cache) + } + + fn read_plain(consumer: &mut Consumer) -> Result> { + match consumer.poll_read_frame(&kio::Waiter::noop()) { + Poll::Ready(res) => res.map(|frame| frame.map(|frame| frame.payload)), + Poll::Pending => panic!("the frame is ready"), + } + } + + /// A compressed group stores DEFLATE slices, hands plain readers the frames as written + /// from one shared inflated copy, and hands egress the slices with their sizes. + #[test] + #[cfg(feature = "async")] + fn compressed_group_stores_slices_and_inflates_once() { + let pool = cache::Pool::unbounded(); + let mut group = compressed_group(&pool); + group.write_frame(None, verbose(0)).unwrap(); + // A chunked frame is invisible until its last chunk, then compressed whole. + let mut frame = group.create_frame(untimed(verbose(1).len())).unwrap(); + for chunk in verbose(1).chunks(100) { + frame.write(Bytes::copy_from_slice(chunk)).unwrap(); + } + frame.finish().unwrap(); + group.write_frame(None, verbose(2)).unwrap(); + group.finish().unwrap(); + + let plain: usize = (0..3).map(|index| verbose(index).len()).sum(); + let stored = pool.used(); + let uncompressed = cache::Pool::unbounded(); + let mut reference = Producer::new( + Info::from(0u64), + track::Info::default(), + cache::Track::new(uncompressed.clone(), kio::Weak::new()), + ); + for index in 0..3 { + reference.write_frame(None, verbose(index)).unwrap(); + } + reference.finish().unwrap(); + assert!( + stored + (plain as u64) / 2 < uncompressed.used(), + "slices are stored: {stored} against {}", + uncompressed.used() + ); + + let mut first = group.consume(); + let mut second = group.consume(); + for index in 0..3 { + assert_eq!( + read_plain(&mut first).unwrap().unwrap(), + verbose(index), + "frame {index}" + ); + } + let inflated = pool.used(); + assert!(inflated >= stored + plain as u64, "the inflated copy is billed"); + for index in 0..3 { + assert_eq!( + read_plain(&mut second).unwrap().unwrap(), + verbose(index), + "frame {index}" + ); + } + assert_eq!(pool.used(), inflated, "a second reader shares the inflated copy"); + assert!(read_plain(&mut first).unwrap().is_none()); + + let mut raw = group.consume().compressed(); + let mut decoder = flate::Decoder::new(); + for index in 0..3 { + let Poll::Ready(Ok(Some(object))) = raw.poll_read_object(&kio::Waiter::noop()) else { + panic!("frame {index} is ready"); + }; + let size = object.inflated.expect("a stored slice carries its size"); + assert_eq!(size, verbose(index).len() as u64); + let frame = decoder.frame(&object.frame.payload, size as usize).unwrap(); + assert_eq!(frame, verbose(index), "slice {index}"); + } + + drop((first, second, raw)); + drop(group); + assert_eq!(pool.used(), 0, "the inflated copy is released with the group"); + } + + /// A compressed successor adopts a failed compressed copy's slices with their inflated + /// sizes, so its plain readers inflate the group from its first frame; a plain head is + /// not its form and stays out. + #[test] + #[cfg(feature = "async")] + fn a_compressed_group_adopts_a_compressed_head() { + let pool = cache::Pool::unbounded(); + let fail = |group: &mut Producer| { + group.write_frame(None, verbose(0)).unwrap(); + group.write_frame(None, verbose(1)).unwrap(); + let handoff = group.consume().handoff(); + group.handle().abort(Error::Cancel).unwrap(); + handoff.head().expect("held for its resumers") + }; + let successor = || { + let mut group = compressed_group(&pool); + group.start_at(2).unwrap(); + group + }; + + let plain = fail(&mut Producer::new( + Info::from(0u64), + track::Info::default(), + cache::Track::new(pool.clone(), kio::Weak::new()), + )); + let refused = successor(); + refused.handle.adopt_head(&plain); + assert_eq!(refused.handle.state.read().offset, 2, "a plain head stays out"); + + let head = fail(&mut compressed_group(&pool)); + let mut group = successor(); + group.handle.adopt_head(&head); + group.finish().unwrap(); + let mut reader = group.consume(); + for index in 0..2 { + assert_eq!( + read_plain(&mut reader).unwrap().unwrap(), + verbose(index), + "frame {index}" + ); + } + assert!(read_plain(&mut reader).unwrap().is_none()); + } + + /// The slices a plain read up to local frame `last` takes under the group's guard. + #[cfg(feature = "async")] + fn take_slices(group: &Producer, last: usize) -> Inflate { + let state = group.handle.state.read(); + state.inflate(state.flate.as_ref().unwrap(), last).unwrap() + } + + /// Plain readers inflate with the group's guard released, into one shared copy: a reader + /// that took the same slices skips what another inflated, the bytes count toward the + /// group's eviction size and the inflating reader's stats once, and a reader that took + /// its slices before a release bills nothing after it. + #[test] + #[cfg(feature = "async")] + fn inflation_is_shared_and_stops_at_release() { + let registry = stats::Registry::new(stats::Config::new()); + let meter = registry.publisher_meter("demo", &stats::Tier::default()); + let inflated = || { + registry + .snapshot() + .traffic() + .into_iter() + .find(|(_, role, _)| *role == stats::Role::Publisher) + .map_or(0, |(_, _, traffic)| traffic.inflated) + }; + let plain: u64 = (0..3).map(|index| verbose(index).len() as u64).sum(); + let pool = cache::Pool::unbounded(); + let write = || { + let mut group = compressed_group(&pool); + for index in 0..3 { + group.write_frame(None, verbose(index)).unwrap(); + } + group.finish().unwrap(); + group + }; + + let group = write(); + let (stored, used) = (group.handle.cache_size(), pool.used()); + let (first, second) = (take_slices(&group, 2), take_slices(&group, 2)); + first.run(&meter); + assert_eq!( + group.handle.cache_size(), + stored + plain, + "the copy counts toward eviction once built" + ); + assert_eq!(pool.used(), used + plain); + second.run(&meter); + assert_eq!( + group.handle.cache_size(), + stored + plain, + "the second reader inflates nothing" + ); + assert_eq!(second.get(1).unwrap(), verbose(1)); + assert_eq!(inflated(), plain, "each inflated byte counts once"); + + let group = write(); + let late = take_slices(&group, 1); + group.handle().abort(Error::Evicted).unwrap(); + let used = pool.used(); + late.run(&meter); + assert!(matches!(late.get(0), Err(Error::Evicted))); + assert_eq!(pool.used(), used, "a late inflater bills nothing past the release"); + assert_eq!(inflated(), plain); + } + + /// A compressed group meters `bytes` as stored, whether a frame is written whole, in a + /// batch, or in chunks. + #[test] + #[cfg(feature = "async")] + fn compressed_writes_meter_the_stored_bytes() { + let registry = stats::Registry::new(stats::Config::new()); + let metered = || { + registry + .snapshot() + .traffic() + .into_iter() + .find(|(_, role, _)| *role == stats::Role::Publisher) + .map_or(0, |(_, _, traffic)| traffic.bytes) + }; + let pool = cache::Pool::unbounded(); + let meter = registry.publisher_meter("demo", &stats::Tier::default()); + let mut group = compressed_group(&pool).with_meter(meter); + + group.write_frame(None, verbose(0)).unwrap(); + let mut batch = frame::Buffer::<2>::new(); + for index in 1..3 { + batch + .push(Frame { + timestamp: None, + payload: verbose(index), + }) + .unwrap(); + } + group.write_frames(&mut batch).unwrap(); + let mut frame = group.create_frame(untimed(verbose(3).len())).unwrap(); + for chunk in verbose(3).chunks(100) { + frame.write(Bytes::copy_from_slice(chunk)).unwrap(); + } + frame.finish().unwrap(); + group.finish().unwrap(); + + let stored: u64 = (group.handle.state.read().frames.iter()) + .map(|frame| frame.payload.len() as u64) + .sum(); + let plain: u64 = (0..4).map(|index| verbose(index).len() as u64).sum(); + assert!(stored < plain, "the frames compressed"); + assert_eq!(metered(), stored); + } + + /// The codec state counts toward the pool while it lives: the encoder until the group + /// finishes, and a reader's decoder until the last frame inflates. + #[test] + #[cfg(feature = "async")] + fn codec_state_is_billed_while_held() { + let pool = cache::Pool::unbounded(); + let mut group = compressed_group(&pool); + group.write_frame(None, verbose(0)).unwrap(); + let stored = group.handle.state.read().charge.size(); + assert_eq!(group.handle.cache_size(), stored + flate::ENCODER_HEAP); + group.write_frame(None, verbose(1)).unwrap(); + + // The read inflates both frames ahead, but the open group may still get a third. + let mut reader = group.consume(); + assert_eq!(read_plain(&mut reader).unwrap().unwrap(), verbose(0)); + let inflated = (verbose(0).len() + verbose(1).len()) as u64; + let stored = group.handle.state.read().charge.size(); + let held = stored + flate::ENCODER_HEAP + flate::DECODER_HEAP + inflated; + assert_eq!(group.handle.cache_size(), held, "an open group keeps both"); + + group.finish().unwrap(); + assert_eq!(group.handle.cache_size(), stored + inflated, "finishing drops both"); + assert_eq!(read_plain(&mut reader).unwrap().unwrap(), verbose(1)); + + // A finished group's decoder goes with the last frame it inflates. + let mut group = compressed_group(&pool); + group.write_frame(None, verbose(0)).unwrap(); + let mut reader = group.consume(); + assert_eq!(read_plain(&mut reader).unwrap().unwrap(), verbose(0)); + group.write_frame(None, verbose(1)).unwrap(); + group.finish().unwrap(); + let stored = group.handle.state.read().charge.size(); + assert_eq!(read_plain(&mut reader).unwrap().unwrap(), verbose(1)); + assert_eq!(group.handle.cache_size(), stored + inflated); + + // So does one whose reader took the last slice before the group finished. + let mut group = compressed_group(&pool); + group.write_frame(None, verbose(0)).unwrap(); + group.write_frame(None, verbose(1)).unwrap(); + let job = take_slices(&group, 1); + group.finish().unwrap(); + job.run(&stats::Meter::default()); + let stored = group.handle.state.read().charge.size(); + assert_eq!(group.handle.cache_size(), stored + inflated, "the decoder is dropped"); + } + + /// A plain read of a compressed group that started past frame 0 lags on every read, + /// never handing out the stored slices it cannot inflate. + #[test] + fn a_plain_read_past_frame_zero_lags() { + let pool = cache::Pool::unbounded(); + let mut group = compressed_group(&pool); + group.start_at(1).unwrap(); + group.write_frame(None, verbose(1)).unwrap(); + group.finish().unwrap(); + + let mut consumer = group.consume(); + consumer.set_frames(1..); + assert!(matches!(read_plain(&mut consumer), Err(Error::Lagged))); + assert!(matches!(read_plain(&mut consumer), Err(Error::Lagged))); + } + + /// A received slice that inflates to other than its declared size fails the read. + #[test] + fn a_received_size_mismatch_fails_the_read() { + let pool = cache::Pool::unbounded(); + let group = compressed_group(&pool); + let slice = flate::Encoder::new().frame(&verbose(0)); + let header = frame::Header { + info: untimed(slice.len()), + fields: None, + inflated: Some(verbose(0).len() as u64 + 1), + }; + let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + frame.write(slice).unwrap(); + let mut group = frame.finish().unwrap(); + group.finish().unwrap(); + + assert!(matches!(read_plain(&mut group.consume()), Err(Error::WrongSize))); + } + + /// A declared inflated size past the cache budget is refused before anything inflates, + /// and only a compressed track takes one. + #[test] + fn an_inflated_size_is_checked_on_open() { + let header = |inflated| frame::Header { + info: untimed(1), + fields: None, + inflated: Some(inflated), + }; + let pool = cache::Pool::unbounded(); + let res = compressed_group(&pool).create_frame_owned(header(MAX_CACHE_BYTES + 1), &frame::Budget::default()); + assert!(matches!(res, Err(Error::FrameTooLarge))); + + let res = Info::from(1u64) + .produce_untimed() + .create_frame_owned(header(1), &frame::Budget::default()); + assert!(matches!(res, Err(Error::ProtocolViolation))); + } + /// A budget that gives up exactly when the test says so. struct Switch(Arc); diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 6d8fcd85ef8..cd8b5235df3 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -23,6 +23,8 @@ mod clock; pub(crate) mod datagram; mod delivered; mod expiry; +// The DEFLATE codec behind compressed tracks. +mod flate; // pending: /quest/m1/public-model/ingest.md pub(crate) mod ledger; // private: passthrough diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index a5c9232e0c4..8bcd8ea805f 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1732,6 +1732,135 @@ mod test { ); } + /// A plain reader of a compressed group inflates from frame 0, so the replacement that + /// fetches only the rest adopts the failed route's compressed head. + #[test] + #[cfg(feature = "async")] + fn a_failed_compressed_group_continues_from_the_replacement() { + let info = crate::track::Info::timed().with_compress(true); + let compressed = || track::Producer::new(Arc::new(broadcast::Info::default()), "video", info.clone()); + let routes = Producer::new(); + let logical = track::Request::new(Arc::new(broadcast::Info::default()), "video") + .routes(routes.consume()) + .accept(info.clone()); + let a = compressed(); + routes.serve(a.consume()); + let mut sub = subscribe(&logical, Duration::from_secs(10)); + let frames: Vec> = (0..3) + .map(|index| format!("{index}{}", "z".repeat(64)).into()) + .collect(); + + let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + open.write_frame(ts(0), frames[0].clone()).unwrap(); + open.write_frame(ts(1), frames[1].clone()).unwrap(); + let mut reading = recv(&mut sub); + assert_eq!(read(&mut reading).as_ref(), Some(&frames[0])); + assert_eq!(read(&mut reading).as_ref(), Some(&frames[1])); + open.abort(Error::Dropped).unwrap(); + + let b = compressed(); + let dynamic = b.dynamic(); + routes.serve(b.consume()); + assert!(reading.read_frame().now_or_never().is_none()); + let request = dynamic.requested_group().now_or_never().unwrap().unwrap(); + assert_eq!((request.sequence(), request.frame_start()), (0, 2)); + let mut rest = request.accept(None).unwrap(); + rest.write_frame(ts(2), frames[2].clone()).unwrap(); + rest.finish().unwrap(); + assert_eq!(read(&mut reading).as_ref(), Some(&frames[2])); + assert_eq!(read(&mut reading), None); + assert_eq!(read_cached(&b.consume(), 0), frames); + } + + /// A slice that inflates to other than its declared size fails a plain read of the + /// logical track, instead of resuming it from the copy that failed, forever. + #[test] + #[cfg(feature = "async")] + fn a_malformed_compressed_frame_fails_the_read() { + let info = crate::track::Info::timed().with_compress(true); + let routes = Producer::new(); + let logical = track::Request::new(Arc::new(broadcast::Info::default()), "video") + .routes(routes.consume()) + .accept(info.clone()); + let a = track::Producer::new(Arc::new(broadcast::Info::default()), "video", info); + routes.serve(a.consume()); + let mut sub = subscribe(&logical, Duration::from_secs(10)); + let frame = || bytes::Bytes::from("z".repeat(64)); + + let mut group = a.create_group(group::Info { sequence: 0 }).unwrap(); + group.write_frame(ts(0), frame()).unwrap(); + let slice = super::super::flate::Encoder::new().frame(&frame()); + let header = crate::model::frame::Header { + info: crate::model::frame::Info { + size: slice.len() as u64, + timestamp: Some(ts(1)), + }, + fields: None, + inflated: Some(frame().len() as u64 + 1), + }; + let mut corrupt = group + .create_frame_owned(header, &crate::model::frame::Budget::default()) + .unwrap(); + corrupt.write(slice).unwrap(); + let mut group = corrupt.finish().unwrap(); + group.finish().unwrap(); + + let mut reading = recv(&mut sub); + assert_eq!(read(&mut reading), Some(frame().to_vec())); + let res = reading.read_frame().now_or_never().expect("a result"); + assert!(matches!(res, Err(Error::WrongSize)), "{res:?}"); + } + + /// Once the failed route's compressed head is reclaimed, a replacement holding only the + /// rest cannot be inflated, so the plain read fails with the route's error. + #[test] + #[cfg(feature = "async")] + fn a_compressed_group_without_its_head_fails_the_read() { + let pool = crate::cache::Pool::new(crate::cache::Config::default().with_capacity(1 << 40)); + let broadcast = Arc::new(broadcast::Info { + pool: pool.clone(), + ..Default::default() + }); + let info = crate::track::Info::timed().with_compress(true); + let routes = Producer::new(); + let logical = track::Request::new(broadcast.clone(), "video") + .routes(routes.consume()) + .accept(info.clone()); + let a = track::Producer::new(broadcast.clone(), "video", info.clone()); + routes.serve(a.consume()); + let mut sub = subscribe(&logical, Duration::from_secs(10)); + let frame = || bytes::Bytes::from("z".repeat(64)); + + let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + open.write_frame(ts(0), frame()).unwrap(); + let mut reading = recv(&mut sub); + assert_eq!(read(&mut reading), Some(frame().to_vec())); + let handoff = open.consume().handoff(); + open.abort(Error::Dropped).unwrap(); + drop(a); + + let b = track::Producer::new(broadcast.clone(), "video", info.clone()); + let dynamic = b.dynamic(); + routes.serve(b.consume()); + assert!(reading.read_frame().now_or_never().is_none()); + let request = dynamic.requested_group().now_or_never().unwrap().unwrap(); + assert_eq!(request.frame_start(), 1); + + // Shrink the pool so the next write reclaims the held head. + let other = track::Producer::new(broadcast, "other", crate::track::Info::timed()); + pool.resize(pool.used().saturating_sub(1)); + let mut filler = other.append_group().unwrap(); + filler.write_frame(ts(0), frame()).unwrap(); + filler.finish().unwrap(); + assert!(handoff.head().is_none(), "the shrink reclaimed the head"); + + let mut rest = request.accept(None).unwrap(); + rest.write_frame(ts(1), frame()).unwrap(); + rest.finish().unwrap(); + let res = reading.read_frame().now_or_never().expect("fails instead of spinning"); + assert!(matches!(res, Err(Error::Dropped)), "{res:?}"); + } + #[test] #[cfg(feature = "async")] fn a_half_read_frame_continues_from_the_replacement() { @@ -2913,6 +3042,7 @@ mod test { status: None, properties: Default::default(), })), + deflated: None, }; let routes = Producer::new(); let front = logical(&routes); @@ -3301,6 +3431,7 @@ mod test { id: 6, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) @@ -3323,6 +3454,7 @@ mod test { id: 8, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) @@ -3370,6 +3502,7 @@ mod test { id, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) @@ -3930,7 +4063,7 @@ mod test { fn held_read_preferences_follow_the_reader() { enum Read { Group(Box), - Frame(crate::frame::Consumer), + Frame(Box), } impl Read { fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { @@ -3979,7 +4112,7 @@ mod test { let mut frame = group.next_frame().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(&frame.read_chunk().now_or_never().unwrap().unwrap().unwrap()[..], b"ab"); drop(group); - Read::Frame(frame) + Read::Frame(Box::new(frame)) } else { Read::Group(Box::new(group)) }; diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 435d44158b4..a5f49256587 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -137,6 +137,15 @@ pub struct Info { /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, + /// Whether frames are DEFLATE compressed per group, so later frames compress against + /// earlier ones in the same group. Defaults to `false`. + /// + /// Writers and readers see plain frames either way: the producer compresses each + /// frame as it is written and the cache stores the compressed form. A moq-lite-07 peer + /// receives the compressed bytes and the flag; every other session receives the + /// frames inflated, from one inflated copy per group shared by every plain reader. + /// Worth it for small, repetitive payloads like JSON; wasted on media. + pub compress: bool, /// The ratio of a group's bytes after its first frame to the first frame past which a /// joining subscriber asks for a new group, or `None` (the default) to never ask. /// @@ -165,6 +174,7 @@ impl Default for Info { timescale: None, max_age: None, priority: DEFAULT_PRIORITY, + compress: false, refresh: None, properties: None, } @@ -194,6 +204,12 @@ impl Info { self } + /// Set whether frames are DEFLATE compressed per group, returning `self` for chaining. + pub fn with_compress(mut self, compress: bool) -> Self { + self.compress = compress; + self + } + /// Set the [`refresh`](Self::refresh) ratio, returning `self` for chaining. pub fn with_refresh(mut self, refresh: impl Into>) -> Self { self.refresh = refresh.into(); @@ -2597,15 +2613,24 @@ impl Producer { } state.advance(sequence, false); state.cache.finish_largest(sequence); - meter.datagram(payload.len() as u64); - state.push_datagram( - Datagram { + // A datagram is its own group, so it compresses alone. + let deflated = state + .info + .as_ref() + .unwrap() + .compress + .then(|| super::flate::Encoder::new().frame(&payload)); + let datagram = super::datagram::Stored { + datagram: Datagram { sequence, timestamp, payload, - } - .into(), - ); + }, + wire: None, + deflated, + }; + meter.datagram(datagram.stored_len()); + state.push_datagram(datagram); let cache = state.cache.clone(); drop(state); cache.settle(None); @@ -2640,12 +2665,14 @@ impl Producer { } let meter = self.stats.meter(); let mut state = self.modify()?; - let timescale = state.info.as_ref().unwrap().timescale; - if !datagram - .wire - .as_ref() - .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)) - { + let info = state.info.as_ref().unwrap(); + let timescale = info.timescale; + let status = datagram.wire.as_ref().and_then(|wire| wire.status); + // A datagram is its own group, so it compresses alone. A status has no payload. + if info.compress && datagram.deflated.is_none() && status.is_none() { + datagram.deflated = Some(super::flate::Encoder::new().frame(&datagram.payload)); + } + if status.is_none_or(|status| status == 0) { datagram.datagram.timestamp = group::on_track(datagram.timestamp, timescale)?; } if state.final_sequence().is_some_and(|fin| datagram.sequence >= fin) { @@ -2653,7 +2680,7 @@ impl Producer { } state.advance(datagram.sequence, false); state.cache.finish_largest(datagram.sequence); - meter.datagram(datagram.payload.len() as u64); + meter.datagram(datagram.stored_len()); state.push_datagram(datagram); let cache = state.cache.clone(); drop(state); @@ -2661,6 +2688,29 @@ impl Producer { Ok(()) } + /// Insert a received datagram of a compressed track, whose payload is its own DEFLATE + /// stream that must inflate to exactly `size` bytes. Kept as it arrived, beside the + /// inflated payload. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: passthrough + pub(crate) fn insert_deflated_datagram(&mut self, mut datagram: super::datagram::Stored, size: u64) -> Result<()> { + if !self.info.compress { + return Err(Error::ProtocolViolation); + } + // Refused before inflating, like an oversized plain payload. + let size = usize::try_from(size) + .ok() + .filter(|size| *size <= super::datagram::MAX_DATAGRAM_PAYLOAD) + .ok_or(Error::FrameTooLarge)?; + let payload = super::flate::Decoder::new().frame(&datagram.payload, size)?; + let inflated = payload.len() as u64; + datagram.deflated = Some(std::mem::replace(&mut datagram.datagram.payload, payload)); + self.insert_wire_datagram(datagram)?; + // Only once stored, so a refused datagram counts toward nothing. + self.stats.meter().inflated(inflated); + Ok(()) + } + /// Create a group with a single frame, at the given presentation timestamp. /// /// The timestamp is converted into the track's timescale. Pass `None` on an untimed @@ -6216,9 +6266,10 @@ impl Subscriber { /// is aborted, or `Poll::Pending` when none is buffered yet. pub fn poll_recv_datagram(&mut self, waiter: &kio::Waiter) -> Poll>> { loop { - let Some(datagram) = ready!(self.poll_recv_wire_datagram(waiter))? else { + let Some(datagram) = ready!(self.poll_recv_stored_datagram(waiter))? else { return Poll::Ready(Ok(None)); }; + // A moq-transport status is no datagram an application can read. if datagram .wire .as_ref() @@ -6226,24 +6277,42 @@ impl Subscriber { { continue; } + self.meter_datagram(datagram.payload.len() as u64); return Poll::Ready(Ok(Some(datagram.datagram))); } } + /// Count a datagram handed on as `bytes` of payload, the single-frame group it stands in + /// for. Unlike a group (metered lazily as its frames are read), a datagram goes whole. // private: passthrough - pub(crate) fn poll_recv_wire_datagram( + pub(crate) fn meter_datagram(&self, bytes: u64) { + self.stats.meter().datagram(bytes); + } + + /// The next datagram as the track stores it: its wire metadata, any status, and a + /// compressed track's DEFLATE slice. Unmetered: the caller meters the form it hands on + /// with [`Self::meter_datagram`]. + // private: passthrough + pub(crate) fn poll_recv_stored_datagram( &mut self, waiter: &kio::Waiter, ) -> Poll>> { - let meter = self.stats.meter(); - let res = match &mut self.inner { + match &mut self.inner { Inner::Plain(cursor) => cursor.poll_recv_datagram(waiter), Inner::Resume(resume, _) => resume.poll_recv_datagram(&self.delivered, waiter), - }; - // Unlike a group (metered lazily as its frames are read), a datagram is - // delivered whole here, so count it as the single-frame group it stands in for. + } + } + + /// [`Self::poll_recv_stored_datagram`], metered as its plain payload: for a session that + /// never carries compression. + // private: passthrough + pub(crate) fn poll_recv_wire_datagram( + &mut self, + waiter: &kio::Waiter, + ) -> Poll>> { + let res = self.poll_recv_stored_datagram(waiter); if let Poll::Ready(Ok(Some(datagram))) = &res { - meter.datagram(datagram.payload.len() as u64); + self.meter_datagram(datagram.payload.len() as u64); } res } @@ -8126,13 +8195,18 @@ mod test { sequence: d.sequence, timestamp: Some(d.timestamp.unwrap().value()), payload: d.payload.clone(), + inflated: None, ietf: None, } .encode_bytes(version) .unwrap(); // Subscriber decodes the body and writes it downstream, preserving the sequence. - let wire = lite::Datagram::decode(body, version, false, |_| Some(crate::Timescale::MICRO)).unwrap(); + let wire = lite::Datagram::decode(body, version, false, |_| lite::Format { + timescale: Some(crate::Timescale::MICRO), + compressed: false, + }) + .unwrap(); let mut downstream = track_producer("test", Info::timed()); let mut downstream_dg = downstream.subscribe(None); downstream @@ -13564,6 +13638,47 @@ mod test { assert!(subscriber.assert_group().sequence > 0, "evicted group is not delivered"); } + /// A plain reader inflating a finished compressed track pays the debt its inflated copies + /// add, though no writer is left to: the pool returns to its capacity. + #[test] + #[cfg(feature = "async")] + fn inflating_settles_the_pool_debt() { + let capacity = 1 << 20; + let pool = cache::Pool::new(cache::Config::default().with_capacity(capacity)); + let broadcast = Arc::new(broadcast::Info { + pool: pool.clone(), + ..Default::default() + }); + let producer = Producer::new(broadcast, "test", Info::timed().with_compress(true)); + let frame = bytes::Bytes::from(vec![0u8; 256 * 1024]); + let groups = 16; + for _ in 0..groups { + let mut group = producer.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, frame.clone()).unwrap(); + group.finish().unwrap(); + } + assert!(pool.used() < capacity, "the slices fit: {}", pool.used()); + + let consumer = producer.consume(); + for sequence in 0..groups { + let Some(mut group) = consumer.peek_group(sequence) else { + continue; + }; + match group.read_frame().now_or_never().expect("cached") { + Ok(Some(read)) => assert_eq!(read.payload.len(), frame.len()), + Ok(None) => panic!("group {sequence} ended without its frame"), + Err(err) => assert!(matches!(err, Error::Evicted), "group {sequence}: {err}"), + } + } + // The live edge and the group being read stay, whatever the budget. + let slack = 2 * (frame.len() as u64 + cache::ENTRY_OVERHEAD); + assert!( + pool.used() <= capacity + slack, + "inflated copies left the pool over capacity: {}", + pool.used() + ); + } + /// The latest group is never in the eviction order, so it survives any budget. #[moq_clock::test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/stats.rs b/rs/moq-net/src/stats.rs index 7a53f7b8430..1d003dd43e9 100644 --- a/rs/moq-net/src/stats.rs +++ b/rs/moq-net/src/stats.rs @@ -56,6 +56,12 @@ //! datagrams. A datagram is metered as the group it stands in for, so it also //! bumps `groups`, `frames`, and `bytes`; this counter breaks out how many of //! those took the datagram path. +//! * `inflated`: cumulative bytes inflated from compressed groups for plain +//! readers (in-process consumers, and egress that cannot carry compression). +//! Every plain reader of a group shares one inflated copy, so each byte counts +//! once, on the side of the reader whose read inflated it. A received compressed +//! datagram inflates on arrival, counted on the receiving side. Kept separate from +//! `bytes`, which counts payload as stored or sent. //! * `requests` ([`Presence`]): cumulative request/response admissions under the //! label and tier at admission. [`Handle::request`] meters their traffic //! without starting or ending a connected session. @@ -179,6 +185,8 @@ pub(crate) struct Counters { groups: AtomicU64, // Subset of `groups` carried over an unreliable QUIC datagram. datagrams: AtomicU64, + // Bytes inflated from compressed groups for plain readers, once per group. + inflated: AtomicU64, // Content the drift budget gave up on before delivery. Disjoint from the // top-level payload counters, which count only what was handed over. stale: ContentCounters, @@ -232,6 +240,7 @@ impl Counters { let frames = self.frames.load(Ordering::Relaxed); let groups = self.groups.load(Ordering::Relaxed); let datagrams = self.datagrams.load(Ordering::Relaxed); + let inflated = self.inflated.load(Ordering::Relaxed); let stale = self.stale.snapshot(); Traffic { announces_started, @@ -246,6 +255,7 @@ impl Counters { frames, groups, datagrams, + inflated, stale, } } @@ -454,6 +464,11 @@ pub struct Traffic { /// A subset of `groups`: each one also counts there and its payload in /// `frames` / `bytes`. pub datagrams: u64, + /// Cumulative bytes inflated from compressed groups for plain readers. Every plain + /// reader shares one inflated copy per group, so each byte counts once. A received + /// compressed datagram counts here as it inflates on arrival. `bytes` still counts + /// payload as stored or sent. + pub inflated: u64, /// Content skipped because it fell behind a subscriber's /// [`max_delay`](crate::track::Subscription::max_delay) budget. Disjoint from the top-level payload /// counters: skipped content is never handed over. A steady rate here means @@ -500,6 +515,7 @@ struct TrafficSer { frames: u64, groups: u64, datagrams: u64, + inflated: u64, stale: Content, } @@ -524,6 +540,7 @@ impl From for TrafficSer { frames: t.frames, groups: t.groups, datagrams: t.datagrams, + inflated: t.inflated, stale: t.stale, } } @@ -550,6 +567,7 @@ struct TrafficDe { frames: u64, groups: u64, datagrams: u64, + inflated: u64, stale: Content, } @@ -568,6 +586,7 @@ impl From for Traffic { frames: d.frames, groups: d.groups, datagrams: d.datagrams, + inflated: d.inflated, stale: d.stale, } } @@ -600,6 +619,7 @@ impl Traffic { self.frames += other.frames; self.groups += other.groups; self.datagrams += other.datagrams; + self.inflated += other.inflated; self.stale.add(other.stale); } @@ -1807,6 +1827,13 @@ impl Meter { self.counters.is_some() } + /// Bump `inflated` by `n`, bytes a plain read inflated from a compressed group. + pub(crate) fn inflated(&self, n: u64) { + if let Some(counters) = self.counters() { + counters.inflated.fetch_add(n, Ordering::Relaxed); + } + } + /// Record content skipped before delivery by the drift budget. pub(crate) fn stale(&self, content: Content) { if let Some(counters) = self.counters() { diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index a72b0dd1480..232f6cdfd13 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -143,6 +143,7 @@ fn lite_varint_interop() { sequence: 300, timestamp: Some((1 << 50) + 5), payload: bytes::Bytes::from_static(b"x"), + inflated: None, ietf: None, } .encode_bytes(version) @@ -157,6 +158,7 @@ fn lite_varint_interop() { sequence: 1 << 30, timestamp: None, payload: bytes::Bytes::from_static(b"untimed"), + inflated: None, ietf: None, } .encode_bytes(version); @@ -168,12 +170,14 @@ fn lite_varint_interop() { } }; - // An untimed track: zero on lite-07, milliseconds before it. + // An untimed track: zero on lite-07, milliseconds before it. Compressed where the + // version can say so. let track_info = lite::TrackInfo { refresh: None, priority: 1, max_age: None, timescale: None, + compress: version.has_compression(), } .encode_bytes(version) .unwrap(); diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs new file mode 100644 index 00000000000..e1aa55702d4 --- /dev/null +++ b/rs/moq-net/tests/integration/compress.rs @@ -0,0 +1,217 @@ +#![cfg(feature = "async")] + +//! A compressed track crosses a relay to every kind of subscriber. +//! +//! The publisher hop always speaks moq-lite 07, so the relay caches the DEFLATE slices as +//! received. A moq-lite 07 subscriber gets them as stored and inflates them itself; every +//! other version gets the plain frames the relay inflates once for all of them. + +use crate::support; + +use std::time::Duration; + +use moq_net::{Hop, Timestamp, Version}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +/// Every downstream wire: one that carries compression, and ones that do not. +const VERSIONS: &[&str] = &["moq-lite-07-wip", "moq-lite-06", "moq-lite-03", "moq-transport-17"]; + +fn compressed() -> moq_net::track::Info { + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_compress(true) +} + +fn produce_origin(hop: u64) -> moq_net::origin::Producer { + let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +/// A repetitive payload, which DEFLATE shrinks, distinct per frame. +fn payload(frame: u64) -> Vec { + format!("{{\"frame\":{frame},\"pad\":\"{}\"}}", "abc".repeat(200)).into_bytes() +} + +struct Fixture { + track: moq_net::track::Producer, + subscriber: moq_net::track::Subscriber, + _broadcast: moq_net::broadcast::Producer, + _hops: Vec, + _origins: Vec, +} + +/// A compressed track published over moq-lite 07 to a relay, and subscribed from the relay +/// over `downstream`. +async fn connect(downstream: &str) -> Fixture { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast.create_track("data", compressed()).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let relay = produce_origin(2); + let mut options = MockConnectOptions::new("moq-lite-07-wip".parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(relay.clone()); + let upstream = connect_mock(options).await; + + let origin = produce_origin(3); + let mut options = MockConnectOptions::new(downstream.parse::().unwrap()); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(origin.clone()); + let downstream = connect_mock(options).await; + + let consumer = origin.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast", None).await.unwrap(); + let subscriber = remote.track("data").unwrap().subscribe(None).await.unwrap(); + support::harness::subscribed(&track).await; + + Fixture { + track, + subscriber, + _broadcast: broadcast, + _hops: vec![upstream, downstream], + _origins: vec![publisher, relay, origin], + } +} + +/// Whole and chunked frames on a compressed track read back as written on every version, +/// and only a moq-lite 07 subscriber learns the track is compressed. +#[moq_clock::test] +async fn relay_serves_every_version() { + for &version in VERSIONS { + moq_clock::timeout(TIMEOUT, async { + let mut fixture = connect(version).await; + assert_eq!( + fixture.subscriber.info().compress, + version == "moq-lite-07-wip", + "{version}: compression declared" + ); + + let mut group = fixture.track.append_group().unwrap(); + group + .write_frame(Timestamp::from_millis(0).unwrap(), payload(0)) + .unwrap(); + group + .write_frame(Timestamp::from_millis(1).unwrap(), payload(1)) + .unwrap(); + // A chunked frame is compressed whole once its last chunk lands. + let chunked = payload(2); + let mut frame = group + .create_frame(moq_net::frame::Info { + size: chunked.len() as u64, + timestamp: Some(Timestamp::from_millis(2).unwrap()), + }) + .unwrap(); + for chunk in chunked.chunks(100) { + frame.write(bytes::Bytes::copy_from_slice(chunk)).unwrap(); + } + frame.finish().unwrap(); + group.finish().unwrap(); + + let mut group = fixture.subscriber.recv_group().await.unwrap().expect("group"); + for index in 0..3 { + let frame = group.read_frame().await.unwrap().expect("frame"); + assert_eq!(&frame.payload[..], &payload(index)[..], "{version}: frame {index}"); + } + assert!(group.read_frame().await.unwrap().is_none(), "{version}: extra frame"); + }) + .await + .unwrap_or_else(|_| panic!("{version}: timed out")); + } +} + +/// A compressed track's datagrams read back as written, whether the subscriber takes them +/// compressed or inflated. +#[moq_clock::test] +async fn datagrams_serve_every_version() { + for &version in &["moq-lite-07-wip", "moq-lite-06"] { + moq_clock::timeout(TIMEOUT, async { + let mut fixture = connect(version).await; + fixture + .track + .insert_datagram(0, Timestamp::from_millis(0).unwrap(), payload(0)) + .unwrap(); + let datagram = fixture.subscriber.recv_datagram().await.unwrap().expect("datagram"); + assert_eq!(&datagram.payload[..], &payload(0)[..], "{version}"); + }) + .await + .unwrap_or_else(|_| panic!("{version}: timed out")); + } +} + +/// What the sessions under `registry` metered as `role`. +fn traffic(registry: &moq_net::stats::Registry, role: moq_net::stats::Role) -> moq_net::stats::Traffic { + registry + .snapshot() + .traffic() + .into_iter() + .find(|(_, row, _)| *row == role) + .map(|(_, _, traffic)| traffic) + .unwrap_or_default() +} + +/// A relay meters a compressed track's datagram in the form each wire carries: compressed +/// on ingress and on moq-lite 07 egress, inflated to an older subscriber. Only `inflated` +/// counts the bytes the relay inflated. +#[moq_clock::test] +async fn datagrams_meter_the_bytes_on_the_wire() { + for &version in &["moq-lite-07-wip", "moq-lite-06"] { + moq_clock::timeout(TIMEOUT, async { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let mut track = broadcast.create_track("data", compressed()).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + // The relay accepts both hops, so its sessions are the ones metered. + let relay = produce_origin(2); + let ingress = moq_net::stats::Registry::new(Default::default()); + let mut options = MockConnectOptions::new("moq-lite-07-wip".parse::().unwrap()); + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(relay.clone()); + options.server_stats = ingress.tier(Default::default()).session("ingress"); + let upstream = connect_mock(options).await; + + let origin = produce_origin(3); + let egress = moq_net::stats::Registry::new(Default::default()); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(origin.clone()); + options.server_stats = egress.tier(Default::default()).session("egress"); + let downstream = connect_mock(options).await; + + let consumer = origin.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast", None).await.unwrap(); + let mut subscriber = remote.track("data").unwrap().subscribe(None).await.unwrap(); + support::harness::subscribed(&track).await; + + track + .insert_datagram(0, Timestamp::from_millis(0).unwrap(), payload(0)) + .unwrap(); + let datagram = subscriber.recv_datagram().await.unwrap().expect("datagram"); + assert_eq!(&datagram.payload[..], &payload(0)[..], "{version}"); + + let plain = payload(0).len() as u64; + let received = traffic(&ingress, moq_net::stats::Role::Subscriber); + assert_eq!(received.datagrams, 1, "{version}: ingress"); + assert!(received.bytes < plain, "{version}: ingress metered {}", received.bytes); + assert_eq!(received.inflated, plain, "{version}: the relay inflated it once"); + + let sent = traffic(&egress, moq_net::stats::Role::Publisher); + assert_eq!(sent.datagrams, 1, "{version}: egress"); + let expected = match version { + "moq-lite-07-wip" => received.bytes, + _ => plain, + }; + assert_eq!(sent.bytes, expected, "{version}: egress metered as sent"); + assert_eq!(sent.inflated, 0, "{version}: egress inflated nothing"); + drop((upstream, downstream, publisher, relay, origin)); + }) + .await + .unwrap_or_else(|_| panic!("{version}: timed out")); + } +} diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 5a838d8a608..834f5eeaff3 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -13,6 +13,7 @@ mod broadcast_close; mod catalog_acquisition; mod catalog_churn; mod catalog_handover; +mod compress; mod datagram; mod dial_split_horizon; mod drained_claim; diff --git a/rs/moq-net/tests/integration/tracks.rs b/rs/moq-net/tests/integration/tracks.rs index 5cecf69a7dc..2ff2d724315 100644 --- a/rs/moq-net/tests/integration/tracks.rs +++ b/rs/moq-net/tests/integration/tracks.rs @@ -95,7 +95,8 @@ async fn a_listing_carries_track_info() { .with_timescale(moq_net::Timescale::MILLI) .with_max_age(Duration::from_secs(3)) .with_priority(9) - .with_refresh(4); + .with_refresh(4) + .with_compress(true); let _a = broadcast.create_track("a", info).unwrap(); broadcast.announce(Default::default()).unwrap(); @@ -114,6 +115,7 @@ async fn a_listing_carries_track_info() { assert_eq!(info.max_age, Some(Duration::from_secs(3))); assert_eq!(info.priority, 9); assert_eq!(info.refresh, Some(4)); + assert!(info.compress); } /// A listed track is a track like any other: a SUBSCRIBE from the listing reads the diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 51adae0e929..efe5baa5bc3 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -354,6 +354,7 @@ impl Mergeable for Traffic { || self.frames < prev.frames || self.groups < prev.groups || self.datagrams < prev.datagrams + || self.inflated < prev.inflated || self.stale.bytes < prev.stale.bytes || self.stale.frames < prev.stale.frames || self.stale.groups < prev.stale.groups