From 8c3d3c10415a3877a290156845e9f613f735f9fe Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 22:12:04 -0700 Subject: [PATCH 01/20] quest(m1): claim compress/core From 837b3122d55d6e4b1b68590177640f72807e5517 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 22:48:10 -0700 Subject: [PATCH 02/20] moq-net: compress tracks with per-group DEFLATE Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + rs/moq-net/Cargo.toml | 3 + rs/moq-net/src/fuzz.rs | 18 +- rs/moq-net/src/ietf/subscriber.rs | 8 +- rs/moq-net/src/lite/datagram.rs | 87 ++++++-- rs/moq-net/src/lite/publisher.rs | 80 +++++--- rs/moq-net/src/lite/subscriber.rs | 63 ++++-- rs/moq-net/src/lite/track.rs | 67 +++++++ rs/moq-net/src/lite/version.rs | 12 ++ rs/moq-net/src/model/cache.rs | 41 ++++ rs/moq-net/src/model/datagram.rs | 10 +- rs/moq-net/src/model/flate.rs | 206 +++++++++++++++++++ rs/moq-net/src/model/frame.rs | 27 ++- rs/moq-net/src/model/group.rs | 319 ++++++++++++++++++++++++++++-- rs/moq-net/src/model/mod.rs | 2 + rs/moq-net/src/model/resume.rs | 30 ++- rs/moq-net/src/model/track.rs | 89 ++++++++- rs/moq-net/src/test_interop.rs | 6 +- 18 files changed, 973 insertions(+), 96 deletions(-) create mode 100644 rs/moq-net/src/model/flate.rs diff --git a/Cargo.lock b/Cargo.lock index bda50e444a2..896f156be36 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4952,6 +4952,7 @@ dependencies = [ "arrayvec", "bytes", "criterion", + "flate2", "futures", "getrandom 0.4.3", "kio 0.6.2", diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index cb2a5a3cf0e..f4b25d9e476 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 } kio = { workspace = true } moq-clock = { version = "0.11.0", path = "../moq-clock", default-features = false } diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index be45262c4c6..1d66b04e786 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -49,6 +49,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(); @@ -146,10 +147,12 @@ 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, so try both readings. + // The body doesn't say whether it carries a timestamp or an inflated size, so try + // every reading. let mut any = false; - for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, |_| timed) else { + for (timed, compressed) in [(true, false), (false, false), (true, true), (false, true)] { + let format = lite::Format { timed, compressed }; + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, |_| format) else { continue; }; any = true; @@ -158,7 +161,7 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { continue; }; - let echo = lite::Datagram::decode(first, version, |_| timed).expect("could not decode our own encoding"); + let echo = lite::Datagram::decode(first, version, |_| format).expect("could not decode our own encoding"); assert_eq!(echo, decoded, "datagram did not survive a round trip"); } any @@ -431,6 +434,7 @@ impl LiteSample { subscribe: 3, sequence: 1_234, timestamp: Some(1_234_567_890), + inflated: None, payload: bytes::Bytes::new(), } .encode(w, version) @@ -463,7 +467,10 @@ 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, |_| true) + Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, |_| lite::Format { + timed: true, + compressed: false, + }) .map(|_| 1) .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), @@ -627,6 +634,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/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 43ce2d39ce1..d72ddc562df 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3904,6 +3904,7 @@ where status, properties: decoded.properties, })), + deflated: None, })?; Ok(()) } @@ -4608,6 +4609,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 { @@ -5337,7 +5339,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 e573d9e99be..9e15c93568d 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 bytes::Bytes; @@ -22,10 +23,23 @@ 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, } +/// 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 track carries a timestamp. + pub timed: bool, + /// 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() { @@ -37,11 +51,18 @@ 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(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); @@ -52,9 +73,8 @@ impl Encode for Datagram { impl Datagram { /// Decode a whole datagram body. The payload shares `buf` rather than copying it. /// - /// `timed` reports whether the track of the given subscribe ID carries a timestamp, - /// which the body itself does not say. - pub fn decode(buf: Bytes, version: Version, timed: impl FnOnce(u64) -> bool) -> Result { + /// `format` reports what the track of the given subscribe ID carries. + pub fn decode(buf: Bytes, version: Version, format: impl FnOnce(u64) -> Format) -> Result { if !version.has_datagrams() { return Err(DecodeError::Version); } @@ -62,7 +82,12 @@ impl Datagram { let mut r = Decoder::new(&buf, version.into()); let subscribe = r.varint()?; let sequence = r.varint()?; - let timestamp = if timed(subscribe) { Some(r.varint()?) } else { None }; + let format = format(subscribe); + let timestamp = if format.timed { Some(r.varint()?) } else { None }; + let inflated = match format.compressed && version.has_compression() { + true => Some(r.varint()?), + false => None, + }; // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); @@ -71,6 +96,7 @@ impl Datagram { subscribe, sequence, timestamp, + inflated, payload, }) } @@ -80,16 +106,48 @@ impl Datagram { mod test { use super::*; + const TIMED: Format = Format { + timed: true, + compressed: false, + }; + + /// 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"), + }; + let buf = dg.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(&buf[..4], [1, 2, 3, 40]); + let format = Format { + timed: true, + compressed: true, + }; + assert_eq!(Datagram::decode(buf, Version::Lite07, |_| format).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"), }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, |_| TIMED).unwrap(); assert_eq!(decoded, original, "payload has no trailing length prefix"); } @@ -99,10 +157,11 @@ mod test { subscribe: 0, sequence: 0, timestamp: Some(0), + inflated: None, payload: Bytes::new(), }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, |_| TIMED).unwrap(); assert_eq!(decoded, original); } @@ -114,6 +173,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: Some(3), + inflated: None, payload: Bytes::from_static(b"world"), }; let buf = dg.encode_bytes(Version::Lite05).unwrap(); @@ -128,6 +188,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: None, + inflated: None, payload: Bytes::from_static(b"world"), }; let buf = dg.encode_bytes(Version::Lite07).unwrap(); @@ -135,7 +196,7 @@ mod test { assert_eq!(&buf[2..], b"world"); let decoded = Datagram::decode(buf, Version::Lite07, |id| { assert_eq!(id, 1); - false + Format::default() }) .unwrap(); assert_eq!(decoded, dg); @@ -147,6 +208,7 @@ mod test { subscribe: 1, sequence: 2, timestamp: None, + inflated: None, payload: Bytes::from_static(b"world"), }; for version in [Version::Lite05, Version::Lite06] { @@ -163,12 +225,13 @@ mod test { subscribe: 1, sequence: 2, timestamp: Some(3), + inflated: None, payload: Bytes::from_static(b"x"), }; assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, |_| true), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, |_| TIMED), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 3695ea33c8b..763f6fa3542 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1872,7 +1872,7 @@ impl Request for TrackInfoServe { fn poll( &mut self, - _: &Shared, + shared: &Shared, writer: &mut Writer, waiter: &kio::Waiter, ) -> Poll, Error>> { @@ -1883,6 +1883,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(), })?; Poll::Ready(Ok(ControlFlow::Break(()))) } @@ -2087,7 +2089,7 @@ enum FetchServe { prev_ts: u64, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, }, } @@ -2154,6 +2156,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(); + } *self = Self::Serve { group, @@ -2161,7 +2167,7 @@ impl Request for FetchServe { prev_ts: 0, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, }; } @@ -2188,23 +2194,24 @@ impl Request for FetchServe { None => *frame = None, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; + let batched = &mut batch[*batch_pos]; 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, )?; - let payload = std::mem::take(&mut batched.payload); + let payload = std::mem::take(&mut batched.frame.payload); if !payload.is_empty() { *chunk = Some(payload); } *batch_pos += 1; group.keep_alive(); } else { - match group.poll_read_frames(waiter, batch) { + match group.poll_read_objects(waiter, batch) { Poll::Ready(Ok(count)) if count > 0 => { *batch_pos = 0; return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -2218,6 +2225,7 @@ impl Request for FetchServe { buffer_frame_info( writer, next.timestamp, + next.inflated, next.size, *timescale, prev_ts, @@ -2961,6 +2969,7 @@ mod announce_test { fn buffer_frame_info( writer: &mut Writer, timestamp: Option, + inflated: Option, size: u64, timescale: Option, prev_ts: &mut u64, @@ -2969,6 +2978,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(()) } @@ -3007,6 +3020,9 @@ fn buffer_zigzag_delta( Ok(()) } +/// A batch of frames read for egress, each with what the wire needs beside it. +type Objects = arrayvec::ArrayVec; + /// What [`recv_next`] pulled from the one subscriber: the next group to serve, the next /// best-effort datagram to forward, the track declaring its exclusive final sequence, or /// the track finishing (the live edge having reached that boundary). @@ -3016,7 +3032,7 @@ fn buffer_zigzag_delta( #[allow(clippy::large_enum_variant)] enum Recv { Group(group::Consumer), - Datagram(crate::Datagram), + Datagram(crate::model::datagram::Stored), Boundary(u64), Finished, } @@ -3055,7 +3071,7 @@ fn poll_recv_next( Poll::Pending => {} } if datagrams { - match track.poll_recv_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) => {} @@ -3236,7 +3252,7 @@ impl Subscription { /// The datagram is dropped (there is no group fallback) if the encoded body doesn't fit the /// transport's datagram limit or the send fails (congestion / no capacity right now). /// Returns whether it was handed to the transport. - fn serve_datagram(&mut self, datagram: crate::Datagram) -> bool { + fn serve_datagram(&mut self, datagram: crate::model::datagram::Stored) -> bool { let Ok(timestamp) = self .timescale .map(|timescale| wire_timestamp(datagram.timestamp, timescale, &self.runtime)) @@ -3244,11 +3260,20 @@ impl Subscription { else { return false; }; + let sequence = datagram.sequence; + // A lite-07 peer takes a compressed track's datagram as stored, others inflated. + let (payload, inflated) = match datagram.deflated { + Some(deflated) if self.version.has_compression() => { + (deflated, Some(datagram.datagram.payload.len() as u64)) + } + _ => (datagram.datagram.payload, None), + }; let body = lite::Datagram { subscribe: self.id, - sequence: datagram.sequence, + sequence, timestamp, - payload: datagram.payload, + inflated, + payload, }; // has_datagrams is checked before this runs, and the timescale is set wherever the // version needs a timestamp, so encoding never hits a version guard. @@ -3259,7 +3284,7 @@ impl Subscription { let max = self.session.max_datagram_size(); if body.len() > max { tracing::debug!( - sequence = datagram.sequence, + sequence, size = body.len(), max, "dropping datagram larger than the transport limit" @@ -3268,7 +3293,7 @@ impl Subscription { } // The run loop may not have served a group since the last SUBSCRIBE_UPDATE. - let priority = crate::priority::in_group(datagram.sequence, 0, self.steer_current().order); + let priority = crate::priority::in_group(sequence, 0, self.steer_current().order); let options = SendOptions { group: self.group.as_ref(), priority, @@ -3499,7 +3524,7 @@ impl TrackRun { Poll::Pending => { self.first = Some(group); if self.datagrams - && let Poll::Ready(Some(datagram)) = self.track.poll_recv_datagram(waiter)? + && let Poll::Ready(Some(datagram)) = self.track.poll_recv_stored_datagram(waiter)? { self.serve_datagram(datagram); return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -3622,7 +3647,7 @@ impl TrackRun { } /// Send a datagram, recording its sequence once it went out. - fn serve_datagram(&mut self, datagram: crate::Datagram) { + fn serve_datagram(&mut self, datagram: crate::model::datagram::Stored) { let sequence = datagram.sequence; if self.ctx.serve_datagram(datagram) { self.mark_served(sequence); @@ -3791,7 +3816,7 @@ enum GroupState { writer: Writer, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a @@ -3811,6 +3836,11 @@ impl GroupServe { group: group::Consumer, ) -> Self { ctx.opens.pending.fetch_add(1, Ordering::Relaxed); + // 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, @@ -3919,7 +3949,7 @@ impl GroupServe { writer, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, }; } @@ -3980,11 +4010,12 @@ impl GroupServe { Poll::Pending => return Poll::Pending, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; + let batched = &mut batch[*batch_pos]; let buffered = 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, @@ -3992,14 +4023,14 @@ impl GroupServe { if let Err(err) = buffered { break 'serve Err(err); } - let payload = std::mem::take(&mut batched.payload); + let payload = std::mem::take(&mut batched.frame.payload); if !payload.is_empty() { *chunk = Some(payload); } *batch_pos += 1; self.group.keep_alive(); } else { - match self.group.poll_read_frames(waiter, batch) { + match self.group.poll_read_objects(waiter, batch) { Poll::Ready(Ok(count)) if count > 0 => { *batch_pos = 0; continue; @@ -4014,6 +4045,7 @@ impl GroupServe { let buffered = 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 828082fa9ea..05d44345826 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -506,8 +506,12 @@ impl Subscriber { // The group path already writes to a producer under this lock. 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, |id| { - subscribes.get(&id).is_some_and(|entry| entry.timescale.is_some()) + let dg = lite::Datagram::decode(payload, self.version, |id| match subscribes.get(&id) { + Some(entry) => lite::Format { + timed: entry.timescale.is_some(), + 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. @@ -528,7 +532,12 @@ 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(); - entry.producer.insert_datagram(dg.sequence, timestamp, dg.payload)?; + match dg.inflated { + Some(size) => entry + .producer + .insert_deflated_datagram(dg.sequence, timestamp, dg.payload, size)?, + None => entry.producer.insert_datagram(dg.sequence, timestamp, dg.payload)?, + } if !live { entry.producer.set_live(Some(Position::group(dg.sequence))); } @@ -1014,9 +1023,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 }, } @@ -1045,7 +1060,7 @@ impl FrameIngest { match &mut self.phase { 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. @@ -1058,11 +1073,29 @@ 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!(reader.poll_varint_maybe(&mut cx))? else { + return Poll::Ready(Ok(())); + }; + self.phase = IngestPhase::Size { + timestamp, + inflated: Some(inflated), + }; + } + IngestPhase::Size { timestamp, inflated } => { let Some(size) = ready!(reader.poll_varint_maybe(&mut cx))? else { return Poll::Ready(Ok(())); }; @@ -1070,10 +1103,16 @@ 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::Info { - size, - timestamp: *timestamp, + frame::Header { + info: frame::Info { + size, + timestamp: *timestamp, + }, + fields: None, + inflated: *inflated, }, &self.budget, )?; @@ -2666,6 +2705,7 @@ mod tests { sequence, timestamp: Some(sequence), payload: bytes::Bytes::from_static(b"x"), + inflated: None, } .encode_bytes(VERSION) .unwrap() @@ -5662,7 +5702,8 @@ impl TrackInfoFetch { let model = track::Info::default() .with_timescale(info.timescale) .with_max_age(info.max_age) - .with_priority(info.priority); + .with_priority(info.priority) + .with_compress(info.compress); 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 bb8d5d4c706..d4e83a9527d 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -68,6 +68,9 @@ 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. + /// Lite07+ only: an earlier peer is served the frames inflated, so it is never set. + pub compress: bool, } impl Message for TrackInfo { @@ -88,11 +91,20 @@ impl Message for TrackInfo { 0 if !matches!(version, Version::Lite05 | Version::Lite06) => None, scale => Some(Timescale::new(scale).map_err(|_| DecodeError::InvalidValue)?), }; + let compress = match version.has_compression() { + true => match r.u8()? { + 0 => false, + 1 => true, + _ => return Err(DecodeError::InvalidValue), + }, + false => false, + }; Ok(Self { priority, max_age, timescale, + compress, }) } @@ -111,6 +123,12 @@ impl Message for TrackInfo { }; w.varint(encoded)?; w.varint(version.wire_timescale(self.timescale).map_or(0, u64::from))?; + if version.has_compression() { + w.u8(self.compress.into()); + } else if self.compress { + // The frames would arrive compressed with nothing saying so. + return Err(EncodeError::Version); + } Ok(()) } } @@ -124,6 +142,7 @@ mod test { priority: 7, max_age: Some(Duration::from_millis(2000)), timescale: Some(Timescale::MICRO), + compress: false, } } @@ -212,6 +231,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) @@ -263,6 +283,50 @@ mod test { } } + #[test] + fn lite07_carries_the_compression_flag() { + 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); + } + + let mut buf = TrackInfo { + compress: true, + ..info_sample() + } + .encode_bytes(Version::Lite07) + .unwrap() + .to_vec(); + *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(); @@ -279,6 +343,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); @@ -292,6 +357,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)); @@ -304,6 +370,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/version.rs b/rs/moq-net/src/lite/version.rs index 9749b2ea0aa..d033f36b32f 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 ceedefb22d0..fcc72795756 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1024,6 +1024,14 @@ impl Charge { self.access.clone() } + /// A [`Bill`] against this charge's account, detached when the charge is. + pub(super) fn bill(&self) -> Bill { + Bill { + track: self.track.clone(), + bytes: 0, + } + } + /// Tick of the group's last cache access. pub(super) fn accessed(&self) -> u64 { self.access.get() @@ -1097,6 +1105,39 @@ 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. Released on [`Self::clear`] or drop. +#[derive(Default)] +pub(super) struct Bill { + track: Option>, + bytes: u64, +} + +impl Bill { + /// Bill `n` more bytes. + pub(super) fn add(&mut self, n: u64) { + if let Some(track) = &self.track { + track.pool.add(n); + track.written.fetch_add(n, Ordering::Relaxed); + self.bytes += n; + } + } + + /// Release every billed byte. + pub(super) fn clear(&mut self) { + if let Some(track) = &self.track { + track.pool.sub(std::mem::take(&mut self.bytes)); + } + } +} + +impl Drop for Bill { + 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..e71ad7632dc 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -57,11 +57,19 @@ 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 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..d014d3dd7b9 --- /dev/null +++ b/rs/moq-net/src/model/flate.rs @@ -0,0 +1,206 @@ +//! 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; + +/// 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. + 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)?; + 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 matches!(status, Status::StreamEnd) || (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))); + } + + #[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 fa92cfaeefd..9a38fddc107 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, + } } } @@ -722,6 +732,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, @@ -751,6 +766,7 @@ impl Consumer { state, info: header.info, fields: header.fields, + inflated: header.inflated, source, read_idx: 0, stats: stats::Meter::default(), @@ -794,7 +810,7 @@ impl Consumer { if self.state.read().sparse() { return Poll::Ready(Err(Error::Unsupported)); } - let mut replacement = match recover.poll(*index, failed.as_ref(), waiter) { + let mut replacement = match recover.poll(*index..*index, failed.as_ref(), waiter) { Poll::Ready(Ok(group)) => group, Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => return Poll::Pending, @@ -804,6 +820,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)), @@ -821,7 +842,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 96a887e9c29..97fcc8479a7 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -14,13 +14,15 @@ //! bounds group sequences. //! //! The stream is closed with [Error] when all writers or readers are dropped. +use super::flate; +use bytes::Bytes; use crate::cache; use crate::frame::{self, Frame, FrameBuf}; use crate::{Cap, Timescale, stats, track}; use std::collections::VecDeque; use std::mem::MaybeUninit; use std::ops::{Bound, RangeBounds}; -use std::sync::Arc; +use std::sync::{Arc, Mutex, PoisonError}; use std::sync::atomic::{AtomicBool, Ordering}; use std::task::{Poll, ready}; @@ -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, @@ -202,6 +212,99 @@ 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. Behind its own + // lock because readers build it, and they only hold the group's read guard. + plain: Mutex, +} + +struct Plain { + // 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 first failure, sticky: every later frame builds on the one that failed. + err: Option, + bill: cache::Bill, +} + +impl Flate { + fn new(bill: cache::Bill) -> Self { + Self { + sizes: VecDeque::new(), + inflated: 0, + encoder: None, + plain: Mutex::new(Plain { + decoder: None, + frames: VecDeque::new(), + err: None, + bill, + }), + } + } + + /// 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 { + self.encoder.get_or_insert_with(flate::Encoder::new).frame(payload) + } + + /// The inflated frame at local index `local`, inflating the stored slices up to it. + /// + /// `stored` holds the completed slices from the group's frame 0. `fin` is the local + /// frame count once the group finished, so the decoder can go after the last frame. + fn plain(&self, stored: &VecDeque, local: usize, fin: Option) -> Result { + let mut plain = self.plain.lock().unwrap_or_else(PoisonError::into_inner); + if let Some(err) = &plain.err { + return Err(err.clone()); + } + while plain.frames.len() <= local { + let index = plain.frames.len(); + let size = usize::try_from(self.sizes[index]).map_err(|_| Error::FrameTooLarge)?; + let decoder = plain.decoder.get_or_insert_with(flate::Decoder::new); + match decoder.frame(&stored[index].payload, size) { + Ok(frame) => { + plain.bill.add(frame.len() as u64); + plain.frames.push_back(frame); + } + Err(err) => { + plain.err = Some(err.clone()); + plain.decoder = None; + return Err(err); + } + } + } + if fin == Some(plain.frames.len()) { + plain.decoder = None; + } + Ok(plain.frames[local].clone()) + } + + /// Drop everything but how the group is read. + fn release(&mut self) { + self.sizes = VecDeque::new(); + self.encoder = None; + let plain = self.plain.get_mut().unwrap_or_else(PoisonError::into_inner); + plain.decoder = None; + plain.frames = VecDeque::new(); + plain.bill.clear(); + } +} + /// The IETF header state that cannot be inferred from a plain frame list. #[cfg_attr(not(feature = "async"), allow(dead_code))] #[derive(Clone, Debug)] @@ -312,9 +415,32 @@ 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 inflated frame at local index `local` of a compressed group, from the copy + /// every plain reader shares. + /// + /// [`Error::Lagged`] when the group started past frame 0: its first slice builds on + /// frames it never held. + fn plain(&self, flate: &Flate, local: usize) -> Result { + if self.offset != 0 { + return Err(Error::Lagged); + } + flate.plain(&self.frames, local, self.fin) + } + /// 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 and + /// inflates, and a `raw` one the stored slice, streaming one that is still arriving. + fn poll_frame_source(&self, index: usize, raw: bool) -> Poll>> { if index < self.offset { return Poll::Ready(Err(Error::Lagged)); } @@ -323,20 +449,28 @@ 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 (payload, inflated) = match &self.flate { + Some(flate) if raw => (f.payload.clone(), Some(flate.sizes[local])), + Some(flate) => (self.plain(flate, local)?, None), + None => (f.payload.clone(), None), + }; let info = frame::Info { - size: f.payload.len() as u64, + size: payload.len() as u64, timestamp: f.timestamp, }; return Poll::Ready(Ok(Some(( frame::Header { info, fields: self.fields(local), + inflated, }, - frame::Source::Complete(f.payload.clone()), + frame::Source::Complete(payload), )))); } if local == self.frames.len() && let Some(p) = &self.partial + && !p.scratch + && (raw || self.flate.is_none()) { self.charge.refresh(); let info = frame::Info { @@ -347,6 +481,7 @@ impl GroupState { frame::Header { info, fields: p.fields.clone(), + inflated: p.inflated, }, frame::Source::Partial(p.buf.clone()), )))); @@ -478,6 +613,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) @@ -499,6 +636,9 @@ impl GroupState { self.partial = None; self.cache = 0; self.charge.clear(); + if let Some(flate) = &mut self.flate { + flate.release(); + } // The header state and terminal object outlive the frames. if let Some(relay) = &mut self.relay { relay.objects = VecDeque::new(); @@ -703,7 +843,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.bill()))); + } + state.charge = charge; + } let alive = Arc::new(Alive { info, state: state.clone(), @@ -741,6 +887,14 @@ impl Producer { self.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.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 @@ -815,14 +969,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); @@ -893,15 +1055,29 @@ 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.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(); @@ -982,9 +1158,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.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.track.compress { + return Err(Error::ProtocolViolation); + } + let scratch = self.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()); @@ -1005,15 +1188,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; @@ -1081,8 +1269,26 @@ 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); + } 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; @@ -1150,6 +1356,10 @@ impl Producer { return Err(Error::FrameOpen); } state.fin = Some(state.next_index); + // No frame follows to compress. + if let Some(flate) = &mut state.flate { + flate.encoder = None; + } // A finished group can no longer raise the track's largest, which may end its stream. self.cache.finish_largest(self.sequence); Ok(()) @@ -1378,6 +1588,7 @@ impl Producer { index: 0, end: None, prefetch: Prefetch::default(), + raw: false, cache: self.cache.clone(), access: self.alive.access.clone(), refreshed: self.cache.pool().now(), @@ -1553,6 +1764,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, } @@ -1560,6 +1773,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 { @@ -1578,13 +1796,44 @@ 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 inflated frames, or with `raw` its stored slices and their + /// inflated sizes. A frame that fails to inflate ends the batch, failing it if first. + 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)) { - self.frames[self.len].write(frame.clone()); - self.len += 1; + let frames = state.frames.range(local..).take(budget.min(Self::CAP)); + match &state.flate { + Some(flate) if !raw => { + for frame in frames { + let payload = match state.plain(flate, local + self.len) { + Ok(payload) => payload, + Err(err) if self.len == 0 => return Err(err), + Err(_) => break, + }; + self.frames[self.len].write(Frame { + timestamp: frame.timestamp, + payload, + }); + self.len += 1; + } + } + _ => { + for frame in frames { + 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() { @@ -1595,6 +1844,7 @@ impl Prefetch { } else if let Some(fields) = &mut self.fields { fields.fill(None); } + Ok(()) } /// `(frame count, total payload bytes)` of the buffered, not-yet-taken frames. @@ -1614,6 +1864,7 @@ impl Default for Prefetch { Self { frames: [const { MaybeUninit::uninit() }; Self::CAP], fields: None, + inflated: None, pos: 0, len: 0, } @@ -1693,6 +1944,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, @@ -1708,6 +1962,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, @@ -1759,6 +2014,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`]). #[cfg(feature = "async")] // private: passthrough @@ -1864,19 +2130,26 @@ impl Consumer { if self.cursor.state.read().sparse() { return Poll::Ready(Err(Error::Unsupported)); } - let replacement = match recover.poll(self.cursor.index as u64, failed.as_ref(), waiter) { + // A plain read of a compressed group inflates from frame 0. + let index = self.cursor.index as u64; + let start = match !self.cursor.raw && self.cursor.state.read().flate.is_some() { + true => 0, + false => index, + }; + let replacement = match recover.poll(start..index, failed.as_ref(), waiter) { Poll::Ready(Ok(group)) => group, Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => return Poll::Pending, }; // 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; } } @@ -2100,6 +2373,7 @@ impl Consumer { Poll::Ready(Ok(frame.map(|frame| frame::Object { frame, fields: self.cursor.prefetch.take_fields(), + inflated: self.cursor.prefetch.take_inflated(), }))) } @@ -2314,6 +2588,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 { @@ -2322,8 +2597,8 @@ 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((info, source)) = ready!(self.poll(waiter, |state| state.poll_frame_source(index, raw))?) else { return Poll::Ready(Ok(None)); }; @@ -2357,6 +2632,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)); @@ -2366,7 +2642,7 @@ 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); + 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. @@ -2497,6 +2773,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(); diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 04e7d797958..638bf6ed608 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 c958c4b7641..fa69e3759f2 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -924,13 +924,14 @@ impl Recover { } } - /// Poll for the serving route's copy of the group, positioned at frame `index`. + /// Poll for the serving route's copy of the group, holding `frames` and positioned at + /// their end. A reader that inflates a compressed group needs it from frame 0. /// /// `failed` is the error the current copy ended with, if it did; a stall is `None`. /// Returns the copy's error when nothing can continue the group. pub(super) fn poll( &mut self, - index: u64, + frames: std::ops::Range, failed: Option<&Error>, waiter: &kio::Waiter, ) -> Poll> { @@ -967,7 +968,7 @@ impl Recover { if generation == self.generation && failed.is_none() { return Poll::Pending; } - let res = self.poll_serving(generation, &serving, index, failed, waiter); + let res = self.poll_serving(generation, &serving, frames.clone(), failed, waiter); // The serving route failed too, and no front is left to replace it. if let (Poll::Pending, Some(err)) = (&res, failed) && (closed || end.is_some()) @@ -993,16 +994,24 @@ impl Recover { &mut self, generation: u64, serving: &track::Consumer, - index: u64, + frames: std::ops::Range, failed: Option<&Error>, waiter: &kio::Waiter, ) -> Poll> { // A newer copy's subscription delivered it: continue from there. The copy that // failed delivered it already, so its subscription will not again. let same = generation == self.generation; - if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) { + // The failed copy released the frames before the reader's, so a reader that inflates + // takes them from the replacement. + let std::ops::Range { start, end: index } = frames; + let continues = |group: &mut group::Consumer| { + group.start_at(start); + let held = group.index() == start; group.start_at(index); - if group.index() == index { + held && group.index() == index + }; + if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) { + if continues(&mut group) { return Poll::Ready(Ok(Replacement { group, generation, @@ -1015,7 +1024,7 @@ impl Recover { if self.fetch.as_ref().is_none_or(|(asked, _)| *asked != generation) { let options = group::Fetch { max_delay: self.max_delay, - frame_start: index, + frame_start: start, ..Default::default() }; self.fetch = Some((generation, Fetch::Pending(serving.fetch_group(self.sequence, options)))); @@ -1029,8 +1038,7 @@ impl Recover { Fetch::Refused(err) => err.clone(), Fetch::Pending(pending) => match ready!(kio::Task::poll(&mut **pending, waiter)) { Ok(mut group) => { - group.start_at(index); - if group.index() == index { + if continues(&mut group) { return Poll::Ready(Ok(Replacement { group, generation, @@ -1872,6 +1880,7 @@ mod test { status: None, properties: Default::default(), })), + deflated: None, }; let routes = Producer::new(); let front = logical(&routes); @@ -2258,6 +2267,7 @@ mod test { id: 6, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) @@ -2280,6 +2290,7 @@ mod test { id: 8, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) @@ -2327,6 +2338,7 @@ mod test { id, properties: Default::default(), })), + inflated: None, }, &crate::frame::Budget::default(), ) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 75dfa3981ed..869609f3c58 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, /// Whether the original publisher starts a group on a moq-transport NEW_GROUP_REQUEST /// (DYNAMIC_GROUPS), as learned from an upstream moq-transport session. /// @@ -153,6 +162,7 @@ impl Default for Info { timescale: None, max_age: None, priority: DEFAULT_PRIORITY, + compress: false, dynamic_groups: false, } } @@ -180,6 +190,12 @@ impl Info { self.priority = priority; 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 + } } #[cfg(test)] @@ -2318,14 +2334,17 @@ impl Producer { state.advance(sequence); 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)); + state.push_datagram(super::datagram::Stored { + datagram: Datagram { sequence, timestamp, payload, - } - .into(), - ); + }, + wire: None, + deflated, + }); let cache = state.cache.clone(); drop(state); cache.settle(None); @@ -2360,7 +2379,12 @@ impl Producer { } let meter = self.stats.meter(); let mut state = self.modify()?; - let timescale = state.info.as_ref().unwrap().timescale; + let info = state.info.as_ref().unwrap(); + let timescale = info.timescale; + if info.compress && datagram.deflated.is_none() { + // A datagram is its own group, so it compresses alone. + datagram.deflated = Some(super::flate::Encoder::new().frame(&datagram.payload)); + } if !datagram .wire .as_ref() @@ -2381,6 +2405,38 @@ impl Producer { Ok(()) } + /// Insert a received datagram of a compressed track: `deflated` is its payload as its + /// own DEFLATE stream, which 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, + sequence: u64, + timestamp: Option, + deflated: bytes::Bytes, + 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(&deflated, size)?; + self.insert_wire_datagram(super::datagram::Stored { + datagram: Datagram { + sequence, + timestamp, + payload, + }, + wire: None, + deflated: Some(deflated), + }) + } + /// 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 @@ -5294,6 +5350,18 @@ impl Subscriber { /// `Poll::Ready(Ok(None))` when the track is finished, `Poll::Ready(Err(e))` when the track /// is aborted, or `Poll::Pending` when none is buffered yet. pub fn poll_recv_datagram(&mut self, waiter: &kio::Waiter) -> Poll>> { + self.poll_recv_stored_datagram(waiter) + .map(|res| res.map(|datagram| datagram.map(|datagram| datagram.datagram))) + } + + /// [`Self::poll_recv_datagram`], keeping what is stored beside the payload: a compressed + /// track's DEFLATE slice. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: passthrough + pub(crate) fn poll_recv_stored_datagram( + &mut self, + waiter: &kio::Waiter, + ) -> Poll>> { loop { let Some(datagram) = ready!(self.poll_recv_wire_datagram(waiter))? else { return Poll::Ready(Ok(None)); @@ -5305,7 +5373,7 @@ impl Subscriber { { continue; } - return Poll::Ready(Ok(Some(datagram.datagram))); + return Poll::Ready(Ok(Some(datagram))); } } @@ -6758,12 +6826,17 @@ mod test { sequence: d.sequence, timestamp: Some(d.timestamp.unwrap().value()), payload: d.payload.clone(), + inflated: None, } .encode_bytes(version) .unwrap(); // Subscriber decodes the body and writes it downstream, preserving the sequence. - let wire = lite::Datagram::decode(body, version, |_| true).unwrap(); + let wire = lite::Datagram::decode(body, version, |_| lite::Format { + timed: true, + compressed: false, + }) + .unwrap(); let mut downstream = track_producer("test", Info::timed()); let mut downstream_dg = downstream.subscribe(None); downstream diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index a7474e17a27..86bc4173aeb 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, } .encode_bytes(version) .unwrap(); @@ -156,6 +157,7 @@ fn lite_varint_interop() { sequence: 1 << 30, timestamp: None, payload: bytes::Bytes::from_static(b"untimed"), + inflated: None, } .encode_bytes(version); let untimed_datagram = match untimed { @@ -166,11 +168,13 @@ 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 { priority: 1, max_age: None, timescale: None, + compress: version.has_compression(), } .encode_bytes(version) .unwrap(); From b80bc741875d62ef5401c86fa813cb87b69238d2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 22:59:53 -0700 Subject: [PATCH 03/20] moq-net: test compressed groups, resume, and relaying Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/group.rs | 126 ++++++++++++++++++++ rs/moq-net/src/model/resume.rs | 36 ++++++ rs/moq-net/tests/integration/compress.rs | 140 +++++++++++++++++++++++ rs/moq-net/tests/integration/main.rs | 1 + 4 files changed, 303 insertions(+) create mode 100644 rs/moq-net/tests/integration/compress.rs diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 97fcc8479a7..6176a2270c0 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -3902,4 +3902,130 @@ mod test { third.write(Bytes::from_static(b"x")).unwrap(); 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] + 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 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 mut 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(); + 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))); + } } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index fa69e3759f2..ead9cd49ab7 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1319,6 +1319,42 @@ mod test { ); } + /// A plain reader of a compressed group inflates the replacement's frames from frame 0, + /// since the failed copy released the ones it read. + #[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])); + + let b = compressed(); + let mut whole = b.create_group(group::Info { sequence: 0 }).unwrap(); + for (ms, frame) in frames.iter().enumerate() { + whole.write_frame(ts(ms as u64), frame.clone()).unwrap(); + } + whole.finish().unwrap(); + routes.serve(b.consume()); + open.abort(Error::Cancel).unwrap(); + + assert_eq!(read(&mut reading).as_ref(), Some(&frames[2])); + assert_eq!(read(&mut reading), None); + } + #[test] #[cfg(feature = "async")] fn a_half_read_frame_continues_from_the_replacement() { diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs new file mode 100644 index 00000000000..2179a6f911f --- /dev/null +++ b/rs/moq-net/tests/integration/compress.rs @@ -0,0 +1,140 @@ +#![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")); + } +} diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 458ccd8e1c9..c08cdbc6610 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -11,6 +11,7 @@ mod announce_to_serve; mod auth; mod broadcast_close; mod catalog_acquisition; +mod compress; mod datagram; mod dial_split_horizon; mod drained_claim; From 97148378f2d481a5caf15d607e6e3eccd2a626bc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:16:31 -0700 Subject: [PATCH 04/20] compress: carry the flag across js/net, bindings, drafts, and docs Co-Authored-By: Claude Opus 5.5 --- dart/moq_ffi/lib/src/moq.dart | 14 +++++++++ doc/concept/moq-lite.md | 8 +++++ drafts/draft-lcurley-moq-flate.md | 19 +++++++----- drafts/draft-lcurley-moq-lite.md | 27 ++++++++++++++++ go/wrapper/records.go | 14 +++++++-- js/net/src/lite/subscriber.ts | 2 ++ js/net/src/lite/track.test.ts | 17 ++++++++++- js/net/src/lite/track.ts | 17 +++++++++-- js/net/src/lite/version.ts | 19 ++++++++++++ py/moq-rs/moq/_records.py | 5 +++ rs/moq-c/MIGRATE.md | 4 +++ rs/moq-c/src/api.rs | 6 +++- rs/moq-c/src/test.rs | 3 ++ rs/moq-ffi/MIGRATE.md | 4 +++ rs/moq-ffi/src/bench.rs | 1 + rs/moq-ffi/src/producer.rs | 8 ++++- rs/moq-ffi/src/test.rs | 5 +++ rs/moq-net/benches/group.rs | 51 ++++++++++++++++++++++++++++++- 18 files changed, 207 insertions(+), 17 deletions(-) diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 3f990238d98..0785793c234 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -2637,10 +2637,12 @@ class MoqTrackInfo { final int priority; final int? maxAgeUs; final int? timescale; + final bool compress; MoqTrackInfo({ this.priority = 127, this.maxAgeUs = null, this.timescale = null, + this.compress = false, }); } @@ -2666,11 +2668,17 @@ 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, timescale: timescale, + compress: compress, ), new_offset - buf.offsetInBytes, ); @@ -2681,6 +2689,7 @@ class FfiConverterMoqTrackInfo { FfiConverterUInt8.allocationSize(value.priority) + FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + + FfiConverterBool.allocationSize(value.compress) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -2701,6 +2710,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; } @@ -2708,6 +2721,7 @@ class FfiConverterMoqTrackInfo { return FfiConverterUInt8.allocationSize(value.priority) + FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + + FfiConverterBool.allocationSize(value.compress) + 0; } } diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 4a207f14975..3cab6b6f1d9 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -247,6 +247,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/drafts/draft-lcurley-moq-flate.md b/drafts/draft-lcurley-moq-flate.md index 48dc994c94e..6ae2ca4413f 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. @@ -75,12 +75,15 @@ 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 flag 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,14 +92,14 @@ 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 diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 4320d28fdd8..889acba473c 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 @@ -743,6 +751,7 @@ DATAGRAM Body { Subscribe ID (i) Group Sequence (i) [Timestamp (i)] + [Inflated Size (i)] Payload (b) } ~~~ @@ -758,6 +767,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 on a compressed Track, whose datagram payload is 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. @@ -1238,6 +1251,7 @@ TRACK_INFO Message { Publisher Priority (8) Publisher Max Age (i) Timescale (i) + [Compressed (8)] } ~~~ @@ -1270,6 +1284,12 @@ The number of timestamp units per second for frame timestamps on this Track, or lite-05 and lite-06 have no untimed encoding: there it MUST be non-zero, and a subscriber that receives 0 MUST reset the stream with a protocol violation. Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` (audio sample rate), and `90000` (RTP video clock). +**Compressed**: +Present from lite-07. +`1` if each Group of this Track is one DEFLATE stream as specified by {{moqflate}}, its FRAME messages and datagrams carrying an `Inflated Size`, or `0` if not. +Any other value is a protocol violation. +A publisher that cannot send this field, on lite-06 and earlier, MUST send the Track's frames inflated instead; a relay inflates each Group once for every such subscriber. + ## SUBSCRIBE_OK {#subscribe-ok} A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position. It is the first message the publisher sends on the Subscribe Stream, once the start position is known. @@ -1560,6 +1580,7 @@ The FRAME message is a payload within a group. ~~~ FRAME Message { [Timestamp Delta (i)] + [Inflated Size (i)] Message Length (i) Payload (b) } @@ -1576,6 +1597,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 on a compressed Track, whose payload is the next slice of the Group's DEFLATE 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. @@ -1585,6 +1611,7 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 +- Added `Compressed` to TRACK_INFO and `Inflated Size` to FRAME and datagrams on a compressed Track, whose Groups are DEFLATE streams per draft-lcurley-moq-flate. Earlier versions receive the Track inflated. - 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. - Added the reliable ordered RTCDataChannel binding, with one Qmux Record per binary message and no datagrams. diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 803415176eb..ed0df6f9050 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -111,11 +111,14 @@ func subscriptionFFI(s *Subscription) (*ffi.MoqSubscription, error) { // TrackInfo holds publisher-side track properties: priority, how long a // non-latest group is cached (nil for no limit), 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. +// the least urgent; set 127 for the 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 Timescale *uint64 + Compress bool } func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { @@ -123,11 +126,16 @@ func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { return nil, nil } maxAge, err := optMicros("max age", info.MaxAge) - return &ffi.MoqTrackInfo{Priority: info.Priority, MaxAgeUs: maxAge, Timescale: info.Timescale}, err + return &ffi.MoqTrackInfo{Priority: info.Priority, MaxAgeUs: maxAge, Timescale: info.Timescale, Compress: info.Compress}, err } func trackInfoFromFFI(info ffi.MoqTrackInfo) TrackInfo { - return TrackInfo{Priority: info.Priority, MaxAge: optFromMicros(info.MaxAgeUs), Timescale: info.Timescale} + return TrackInfo{ + Priority: info.Priority, + MaxAge: optFromMicros(info.MaxAgeUs), + 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 292af1ef8bc..7613c3c486f 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -903,6 +903,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 096ad5dad9b..bdc5fdfb2c3 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -59,7 +59,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 flag. + 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 +75,20 @@ test("TrackInfo carries an untimed track as zero on lite-07 and milliseconds bef } }); +test("TrackInfo carries the compression flag 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 0 or 1 is malformed. + lite07[lite07.length - 1] = 2; + await expect(TrackInfo.decode(new Reader(undefined, lite07, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); + + 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 a787c203942..ad8a572cd0e 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -4,7 +4,7 @@ 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, Version, wireTimescale } from "./version.ts"; +import { hasCompression, hasGroupOrder, Version, wireTimescale } from "./version.ts"; // The Track Stream (0x6) is draft-05+ only. function guardTrack(version: Version) { @@ -78,15 +78,22 @@ 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, + compress = false, }: { priority?: number; maxAge?: number; timescale?: number; + compress?: boolean; }) { if (!Number.isInteger(priority) || priority < 0 || priority > 255) { throw new RangeError(`priority must be an integer in 0..=255: ${priority}`); @@ -97,6 +104,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) { @@ -107,6 +115,7 @@ export class TrackInfo { const age = this.maxAge === undefined ? undefined : BigInt(this.maxAge); await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); + if (hasCompression(version)) await w.bool(this.compress); } static async #decode(r: Reader, version: Version): Promise { @@ -127,7 +136,8 @@ export class TrackInfo { // Lite-05/06 have no untimed encoding, so zero is malformed there. const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); - return new TrackInfo({ priority, maxAge, timescale }); + const compress = hasCompression(version) ? await r.bool() : false; + return new TrackInfo({ priority, maxAge, timescale, compress }); } async encode(w: Writer, version: Version): Promise { @@ -141,6 +151,9 @@ export class TrackInfo { throw new RangeError(`maxAge must be a safe non-negative integer: ${this.maxAge}`); } 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 f70c8e5c624..437db619237 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -358,6 +358,25 @@ export function hasEpoch(version: Version): boolean { } } +/** + * Whether TRACK_INFO carries the compression flag, 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 861430b86c5..cad34cad5ed 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -123,17 +123,21 @@ class TrackInfo: ``priority`` defaults to 127, the middle of the range. ``max_age`` is how long the publisher caches a non-latest group, ``None`` for no limit. ``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 timescale: int | None = None + compress: bool = False def _ffi(self) -> MoqTrackInfo: return MoqTrackInfo( priority=self.priority, max_age_us=_opt_us(self.max_age, "max_age"), timescale=self.timescale, + compress=self.compress, ) @staticmethod @@ -142,6 +146,7 @@ def _from_ffi(info: MoqTrackInfo) -> TrackInfo: priority=info.priority, max_age=None if info.max_age_us is None else _from_us(info.max_age_us), timescale=info.timescale, + compress=info.compress, ) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 3168e31494e..7ca784d0baf 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` + +The new trailing field changes its ABI. A zero-initialized struct leaves it false, as before. + ### Subscriptions carry group ranges (#5732) `moq_subscription`'s `group_start`, `group_end`, and their `_present` flags are replaced by `ranges` and `ranges_len`, an array of `moq_range` whose ends are `moq_anchor`s, and `order` (`moq_order`), which changes its ABI. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 80890cd5231..4e89e6fd332 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -519,6 +519,10 @@ pub struct moq_track_info { /// Whether `timescale` is set. When false, the default microsecond timescale /// applies, matching the `timestamp_us` units used everywhere else in this ABI. pub timescale_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 { @@ -536,7 +540,7 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { if info.timescale_present { out = out.with_timescale(moq_net::Timescale::new(info.timescale)?); } - 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 ac8de2aea69..165bc170c6c 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1406,6 +1406,7 @@ fn publish_track_invalid_broadcast() { max_age_present: false, timescale: 0, timescale_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); @@ -1435,6 +1436,7 @@ fn publish_track_with_info_rejects_invalid_timescale() { max_age_present: false, timescale: 0, timescale_present: true, + compress: false, }; assert!(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) } < 0); @@ -1709,6 +1711,7 @@ fn raw_track_subscription_options_and_update() { max_age_present: true, timescale: 1_000_000, timescale_present: true, + compress: false, }; let track = id(unsafe { moq_publish_track(broadcast, track_name.as_ptr() as *const c_char, track_name.len(), &info) }); diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index e75eb72a719..7174a2ad6b3 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` + +It defaults to `false` in every generated binding; a Rust struct literal adds `compress: false`. + ### Subscriptions carry group ranges (#5732) `MoqSubscription::group_start` and `group_end` are replaced by `ranges`, a list of `MoqRange { start, end }` whose ends are `MoqAnchor::Absolute { group, frame }` or `MoqAnchor::Relative { groups }`, and an optional `order`. diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 3c4d3910d95..2e7b2d6a294 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -243,6 +243,7 @@ async fn rust_ffi() { priority: 127, max_age_us: 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 9e30534e81a..1a289301b2b 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -26,6 +26,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 { @@ -42,7 +46,7 @@ impl TryFrom for moq_net::track::Info { })?; out = out.with_timescale(scale); } - Ok(out) + Ok(out.with_compress(info.compress)) } } @@ -67,6 +71,7 @@ impl TryFrom<&moq_net::track::Info> for MoqTrackInfo { priority: info.priority, max_age_us, timescale: info.timescale.map(|timescale| timescale.as_u64()), + compress: info.compress, }) } } @@ -699,6 +704,7 @@ mod metadata_tests { priority: 0, max_age_us, 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 001a0c66161..0a48344681b 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -34,6 +34,7 @@ fn timed_info() -> MoqTrackInfo { priority: 127, max_age_us: None, timescale: Some(1_000_000), + compress: false, } } @@ -860,6 +861,7 @@ async fn raw_track_datagram_roundtrip() { priority: 0, max_age_us: None, timescale: Some(1_000_000), + compress: false, }), ) .unwrap(); @@ -890,6 +892,7 @@ async fn raw_track_info_reports_publisher_properties() { priority: 7, max_age_us: Some(2_500_000), timescale: Some(90_000), + compress: true, }; let track = broadcast.publish_track("status".into(), Some(info)).unwrap(); let consumer = track.consume(None).unwrap(); @@ -898,6 +901,7 @@ async fn raw_track_info_reports_publisher_properties() { assert_eq!(got.priority, 7); assert_eq!(got.max_age_us, Some(2_500_000)); assert_eq!(got.timescale, Some(90_000)); + assert!(got.compress); } #[tokio::test] @@ -961,6 +965,7 @@ async fn data_writes_preserve_optional_timestamps() { priority: 127, max_age_us: None, timescale: timestamp_us.map(|_| 1_000_000), + compress: false, }), ) .unwrap(); 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); From 265b6439a340600e5220094934b80cd2846c6db1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:44:16 -0700 Subject: [PATCH 05/20] compress: format, gate the raw-read test on async, and quiet clippy Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/fuzz.rs | 4 ++-- rs/moq-net/src/ietf/publisher.rs | 2 ++ rs/moq-net/src/lite/track.rs | 5 ++++- rs/moq-net/src/model/group.rs | 17 ++++++++++++---- rs/moq-net/src/model/resume.rs | 25 +++++++++++++----------- rs/moq-net/src/model/track.rs | 7 ++++++- rs/moq-net/tests/integration/compress.rs | 8 ++++++-- 7 files changed, 47 insertions(+), 21 deletions(-) diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 1d66b04e786..df542473a15 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -471,8 +471,8 @@ impl LiteSample { timed: true, compressed: false, }) - .map(|_| 1) - .unwrap(), + .map(|_| 1) + .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), } } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index a1cbb283cc6..ed9cfe27fab 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -74,6 +74,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/lite/track.rs b/rs/moq-net/src/lite/track.rs index d4e83a9527d..3c119eaf219 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -318,7 +318,10 @@ mod test { ..info_sample() }; for version in [Version::Lite05, Version::Lite06] { - assert!(matches!(info.encode_bytes(version), Err(EncodeError::Version)), "{version}"); + assert!( + matches!(info.encode_bytes(version), Err(EncodeError::Version)), + "{version}" + ); let plain = TrackInfo { compress: false, ..info_sample() diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 6176a2270c0..256bc39d2d9 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -15,15 +15,15 @@ //! //! The stream is closed with [Error] when all writers or readers are dropped. use super::flate; -use bytes::Bytes; 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::{Arc, Mutex, PoisonError}; use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex, PoisonError}; use std::task::{Poll, ready}; use crate::{Error, IntoBytes, Result, Timestamp}; @@ -3930,6 +3930,7 @@ mod test { /// 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); @@ -3964,12 +3965,20 @@ mod test { 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}"); + 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!( + 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()); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index ead9cd49ab7..ae20b646b9b 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1010,14 +1010,15 @@ impl Recover { group.start_at(index); held && group.index() == index }; - if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) { - if continues(&mut group) { - return Poll::Ready(Ok(Replacement { - group, - generation, - copy: serving.clone(), - })); - } + if !same + && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) + && continues(&mut group) + { + return Poll::Ready(Ok(Replacement { + group, + generation, + copy: serving.clone(), + })); } // Otherwise ask for the rest. The subscription may still deliver it first. @@ -1333,7 +1334,9 @@ mod test { 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 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(); @@ -2760,7 +2763,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> { @@ -2809,7 +2812,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 869609f3c58..c888af82f0f 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2335,7 +2335,12 @@ impl Producer { state.cache.finish_largest(sequence); meter.datagram(payload.len() as u64); // 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 deflated = state + .info + .as_ref() + .unwrap() + .compress + .then(|| super::flate::Encoder::new().frame(&payload)); state.push_datagram(super::datagram::Stored { datagram: Datagram { sequence, diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs index 2179a6f911f..b83b7d50018 100644 --- a/rs/moq-net/tests/integration/compress.rs +++ b/rs/moq-net/tests/integration/compress.rs @@ -92,8 +92,12 @@ async fn relay_serves_every_version() { ); 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(); + 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 From 0e2acb0051a42576622164fd241246924e7a8369 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:49:35 -0700 Subject: [PATCH 06/20] quest(m1): finish compress/core Co-Authored-By: Claude Opus 5.5 --- quest/m1/compress/README.md | 3 +- quest/m1/compress/core.md | 66 ------------------------------------ quest/m1/compress/ietf.md | 6 +--- quest/m1/compress/js.md | 6 +--- quest/m1/compress/migrate.md | 1 - quest/m1/lite07-finalize.md | 1 - 6 files changed, 3 insertions(+), 80 deletions(-) delete mode 100644 quest/m1/compress/core.md diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 21433416164..4b2e175b2b6 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -46,7 +46,7 @@ Every interview prompt and the selected answer (โœ…) are in the planning PR. 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 + 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 981ac7db9b8..081910c480d 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 cbe866cd333..4310ee383c1 100644 --- a/quest/m1/compress/migrate.md +++ b/quest/m1/compress/migrate.md @@ -48,6 +48,5 @@ 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` - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - in review on the same flate and binary consumers this deletes; one owner at a time diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index cafd9f22258..0768802c2ba 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -86,7 +86,6 @@ is published; older versions are unchanged. - [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 - [Refresh on the lite wire](/quest/m1/refresh/lite.md) - TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE the wanted group -- [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 - [SUBSCRIBE_ALL](/quest/m1/archive/subscribe-all.md) - lite-07 carries the prefix-scoped request for every track of every broadcast under a path From 57b9d0c207045c58d6caa11d6bad90010f05fd5a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:50:18 -0700 Subject: [PATCH 07/20] compress: link the MIGRATE entries to the PR Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/MIGRATE.md | 2 +- rs/moq-ffi/MIGRATE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 7ca784d0baf..d962bfdbde7 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### `moq_track_info` gains `compress` +### `moq_track_info` gains `compress` (#5928) The new trailing field changes its ABI. A zero-initialized struct leaves it false, as before. diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 7174a2ad6b3..5a78d54ce41 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,7 +5,7 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased -### `MoqTrackInfo` gains `compress` +### `MoqTrackInfo` gains `compress` (#5928) It defaults to `false` in every generated binding; a Rust struct literal adds `compress: false`. From 811f50f58b61ad4ef17311bcf2b90b24a1c1976b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 10:07:02 -0700 Subject: [PATCH 08/20] compress: codec id on the wire, inflate outside the group guard, bill and count inflation - TRACK_INFO carries a Compression codec varint (0 none, 1 DEFLATE, else a protocol violation) instead of a boolean, in Rust, js/net, and the drafts. - Plain readers take the slices they need under the group's guard and inflate under the shared copy's own lock; a reader that took the same slices skips what another inflated, and a release fails a late inflater instead of billing past it. - The inflated copy counts toward the group's eviction size once built, and a new `inflated` traffic counter reports it once per group. - doc/lib pages mention `compress`. Co-Authored-By: Claude Opus 5.5 --- doc/concept/stats.md | 2 + doc/lib/c/index.md | 1 + doc/lib/cpp/index.md | 4 + doc/lib/dart/index.md | 1 + doc/lib/go/index.md | 1 + doc/lib/kt/index.md | 1 + doc/lib/py/index.md | 1 + doc/lib/swift/index.md | 1 + drafts/draft-lcurley-moq-flate.md | 2 +- drafts/draft-lcurley-moq-lite.md | 15 +- js/net/src/lite/track.test.ts | 11 +- js/net/src/lite/track.ts | 21 +- js/net/src/lite/version.ts | 2 +- quest/m1/compress/README.md | 2 +- rs/moq-net/src/lite/track.rs | 24 +- rs/moq-net/src/model/cache.rs | 20 +- rs/moq-net/src/model/group.rs | 398 ++++++++++++++++++++++-------- rs/moq-net/src/stats.rs | 25 ++ rs/moq-stats/src/aggregate.rs | 1 + 19 files changed, 406 insertions(+), 127 deletions(-) diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 52a82d2e233..e4c69f5c4f3 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -211,6 +211,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, @@ -228,6 +229,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. 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 f228d34c458..3744018e37c 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. - **Decoded frames hold decoder buffers.** Free each frame id with `moq_decode_video_frame_free` promptly, or the decoder stalls. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 3447337708c..b0562a1bc03 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 Obtain a dynamic track requestโ€™s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index c797e547eaa..10f08c1be36 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -20,6 +20,7 @@ and sections; it holds the broadcast weakly and fails after the broadcast closes `package:moq/flate.dart` exposes opaque `SnapshotProducer` / `StreamProducer` with an optional `timestampUs`. A missing data timestamp stays untimed; the library never substitutes zero or now. 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 ed9ba32e6f3..a39cf855797 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). Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 581c0f5a6a3..7afd7739409 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -19,6 +19,7 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). `dev.moq.flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. A missing data timestamp stays untimed; the library never substitutes zero or now. 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 fb21d81ace4..def9d27cb8e 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -24,6 +24,7 @@ and does not keep it open. `MediaFrame.timestamp`, media writes, and `flush` use `datetime.timedelta`. A missing data timestamp stays untimed; the library never substitutes zero or now. 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 cba77507d7d..f48d5239afb 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -20,6 +20,7 @@ Its writes fail after closing or releasing the broadcast. `Flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. 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. +`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 6ae2ca4413f..3a15129f10f 100644 --- a/drafts/draft-lcurley-moq-flate.md +++ b/drafts/draft-lcurley-moq-flate.md @@ -76,7 +76,7 @@ The compression level is a publisher's choice; any conformant stream decodes. # Declaring Compression {#declare} 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 flag in TRACK_INFO, and an Inflated Size on each FRAME and datagram. +{{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. A consumer MUST treat an object that inflates to more or less than its declared size as malformed, and abandon the subgroup. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 889acba473c..3d7d99f55a9 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -769,7 +769,7 @@ Present only on a timed Track, which the receiver learns from the subscription n **Inflated Size**: The size of the payload once inflated. -Present only on a compressed Track, whose datagram payload is compressed alone, as a stream of its own. +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. @@ -1251,7 +1251,7 @@ TRACK_INFO Message { Publisher Priority (8) Publisher Max Age (i) Timescale (i) - [Compressed (8)] + [Compression (i)] } ~~~ @@ -1284,10 +1284,11 @@ The number of timestamp units per second for frame timestamps on this Track, or lite-05 and lite-06 have no untimed encoding: there it MUST be non-zero, and a subscriber that receives 0 MUST reset the stream with a protocol violation. Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` (audio sample rate), and `90000` (RTP video clock). -**Compressed**: +**Compression**: Present from lite-07. -`1` if each Group of this Track is one DEFLATE stream as specified by {{moqflate}}, its FRAME messages and datagrams carrying an `Inflated Size`, or `0` if not. -Any other value is a protocol violation. +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; a relay inflates each Group once for every such subscriber. ## SUBSCRIBE_OK {#subscribe-ok} @@ -1599,7 +1600,7 @@ The first frame of a group is delta-encoded from `0`, so its `Timestamp Delta` i **Inflated Size**: The size of the payload once inflated. -Present only on a compressed Track, whose payload is the next slice of the Group's DEFLATE stream. +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**: @@ -1611,7 +1612,7 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 -- Added `Compressed` to TRACK_INFO and `Inflated Size` to FRAME and datagrams on a compressed Track, whose Groups are DEFLATE streams per draft-lcurley-moq-flate. Earlier versions receive the Track inflated. +- 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. - 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. - Added the reliable ordered RTCDataChannel binding, with one Qmux Record per binary message and no datagrams. diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index bdc5fdfb2c3..a2ccf907a9b 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,7 @@ 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); - // The timescale, then the compression flag. + // 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(); @@ -75,16 +76,18 @@ test("TrackInfo carries an untimed track as zero on lite-07 and milliseconds bef } }); -test("TrackInfo carries the compression flag on lite-07 only", async () => { +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 0 or 1 is malformed. + // 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(); + 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(); }); diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index ad8a572cd0e..f6ace086a98 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -1,4 +1,5 @@ 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"; @@ -6,6 +7,22 @@ import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; import { hasCompression, hasGroupOrder, 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}`); + } +} + // The Track Stream (0x6) is draft-05+ only. function guardTrack(version: Version) { switch (version) { @@ -115,7 +132,7 @@ export class TrackInfo { const age = this.maxAge === undefined ? undefined : BigInt(this.maxAge); await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); - if (hasCompression(version)) await w.bool(this.compress); + if (hasCompression(version)) await w.u53(this.compress ? COMPRESSION_DEFLATE : COMPRESSION_NONE); } static async #decode(r: Reader, version: Version): Promise { @@ -136,7 +153,7 @@ export class TrackInfo { // Lite-05/06 have no untimed encoding, so zero is malformed there. const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); - const compress = hasCompression(version) ? await r.bool() : false; + const compress = hasCompression(version) ? await decodeCompression(r) : false; return new TrackInfo({ priority, maxAge, timescale, compress }); } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 437db619237..76b35d63d29 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -359,7 +359,7 @@ export function hasEpoch(version: Version): boolean { } /** - * Whether TRACK_INFO carries the compression flag, and a compressed track's FRAME and + * 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 { diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 4b2e175b2b6..173f88607ce 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -45,7 +45,7 @@ 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 +- **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 diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 3c119eaf219..5f8d5ce09cc 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -68,11 +68,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. - /// Lite07+ only: an earlier peer is served the frames inflated, so it is never set. + /// 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() { @@ -92,9 +98,9 @@ impl Message for TrackInfo { scale => Some(Timescale::new(scale).map_err(|_| DecodeError::InvalidValue)?), }; let compress = match version.has_compression() { - true => match r.u8()? { - 0 => false, - 1 => true, + true => match r.varint()? { + COMPRESSION_NONE => false, + COMPRESSION_DEFLATE => true, _ => return Err(DecodeError::InvalidValue), }, false => false, @@ -124,7 +130,10 @@ impl Message for TrackInfo { w.varint(encoded)?; w.varint(version.wire_timescale(self.timescale).map_or(0, u64::from))?; if version.has_compression() { - w.u8(self.compress.into()); + 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); @@ -284,7 +293,7 @@ mod test { } #[test] - fn lite07_carries_the_compression_flag() { + fn lite07_carries_the_compression_codec() { for compress in [false, true] { let info = TrackInfo { compress, @@ -302,6 +311,7 @@ mod test { .encode_bytes(Version::Lite07) .unwrap() .to_vec(); + // An unknown codec id, still a one-byte varint. *buf.last_mut().unwrap() = 2; let mut slice = buf.as_slice(); assert!(matches!( diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index fcc72795756..a49ff4b9604 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1028,7 +1028,7 @@ impl Charge { pub(super) fn bill(&self) -> Bill { Bill { track: self.track.clone(), - bytes: 0, + bytes: AtomicU64::new(0), } } @@ -1108,26 +1108,34 @@ 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. 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 Bill { track: Option>, - bytes: u64, + bytes: AtomicU64, } impl Bill { /// Bill `n` more bytes. - pub(super) fn add(&mut self, n: u64) { + 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 += n; + self.bytes.fetch_add(n, Ordering::Relaxed); } } + /// Bytes currently billed. + pub(super) fn size(&self) -> u64 { + self.bytes.load(Ordering::Relaxed) + } + /// Release every billed byte. - pub(super) fn clear(&mut self) { + pub(super) fn clear(&self) { if let Some(track) = &self.track { - track.pool.sub(std::mem::take(&mut self.bytes)); + track.pool.sub(self.bytes.swap(0, Ordering::Relaxed)); } } } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 256bc39d2d9..82629e99be8 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -22,8 +22,8 @@ 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}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use std::task::{Poll, ready}; use crate::{Error, IntoBytes, Result, Timestamp}; @@ -222,19 +222,8 @@ struct Flate { // 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. Behind its own - // lock because readers build it, and they only hold the group's read guard. - plain: Mutex, -} - -struct Plain { - // 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 first failure, sticky: every later frame builds on the one that failed. - err: Option, - bill: cache::Bill, + // The inflated copy every plain reader shares, built on first demand. + plain: Arc, } impl Flate { @@ -243,11 +232,10 @@ impl Flate { sizes: VecDeque::new(), inflated: 0, encoder: None, - plain: Mutex::new(Plain { - decoder: None, - frames: VecDeque::new(), - err: None, + plain: Arc::new(Plain { + len: AtomicUsize::new(0), bill, + state: Mutex::new(PlainState::default()), }), } } @@ -263,48 +251,136 @@ impl Flate { self.encoder.get_or_insert_with(flate::Encoder::new).frame(payload) } - /// The inflated frame at local index `local`, inflating the stored slices up to it. + /// 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, counted toward the group's eviction size once they exist. + // Changed only under `state`. + bill: cache::Bill, + 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 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) + } + + /// 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)), + } + } + + 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)>, + // The group's frame count once finished, so the decoder drops after the last frame. + fin: Option, +} + +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. /// - /// `stored` holds the completed slices from the group's frame 0. `fin` is the local - /// frame count once the group finished, so the decoder can go after the last frame. - fn plain(&self, stored: &VecDeque, local: usize, fin: Option) -> Result { - let mut plain = self.plain.lock().unwrap_or_else(PoisonError::into_inner); - if let Some(err) = &plain.err { - return Err(err.clone()); - } - while plain.frames.len() <= local { - let index = plain.frames.len(); - let size = usize::try_from(self.sizes[index]).map_err(|_| Error::FrameTooLarge)?; - let decoder = plain.decoder.get_or_insert_with(flate::Decoder::new); - match decoder.frame(&stored[index].payload, size) { + /// Locks per frame, so a release waits on at most one frame's inflation. + 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| state.decoder.get_or_insert_with(flate::Decoder::new).frame(slice, size)); + match frame { Ok(frame) => { - plain.bill.add(frame.len() as u64); - plain.frames.push_back(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 self.fin == Some(state.frames.len()) { + state.decoder = None; + } } Err(err) => { - plain.err = Some(err.clone()); - plain.decoder = None; - return Err(err); + state.err = Some(err); + state.decoder = None; + break; } } } - if fin == Some(plain.frames.len()) { - plain.decoder = None; - } - Ok(plain.frames[local].clone()) } - /// Drop everything but how the group is read. - fn release(&mut self) { - self.sizes = VecDeque::new(); - self.encoder = None; - let plain = self.plain.get_mut().unwrap_or_else(PoisonError::into_inner); - plain.decoder = None; - plain.frames = VecDeque::new(); - plain.bill.clear(); + /// 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)] @@ -423,24 +499,32 @@ impl GroupState { .is_some_and(|flate| flate.inflated.saturating_add(extra) > MAX_CACHE_BYTES) } - /// The inflated frame at local index `local` of a compressed group, from the copy - /// every plain reader shares. + /// 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 plain(&self, flate: &Flate, local: usize) -> Result { + fn inflate(&self, flate: &Flate, last: usize) -> Result { if self.offset != 0 { return Err(Error::Lagged); } - flate.plain(&self.frames, local, self.fin) + 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(), + fin: self.fin, + }) } /// Resolve the source for the frame at `index`: a completed frame (whole) or the /// in-flight tail (streamed). Used by [`Consumer::poll_next_frame`]. /// - /// A compressed group hands a plain reader each frame whole once it completes and - /// inflates, and a `raw` one the stored slice, streaming one that is still arriving. - fn poll_frame_source(&self, index: usize, raw: bool) -> 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)); } @@ -449,22 +533,29 @@ 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 (payload, inflated) = match &self.flate { - Some(flate) if raw => (f.payload.clone(), Some(flate.sizes[local])), - Some(flate) => (self.plain(flate, local)?, None), - None => (f.payload.clone(), None), + 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: payload.len() as u64, + 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(payload), + frame::Source::Complete(f.payload.clone()), )))); } if local == self.frames.len() @@ -477,7 +568,7 @@ impl GroupState { 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(), @@ -637,7 +728,7 @@ impl GroupState { self.cache = 0; self.charge.clear(); if let Some(flate) = &mut self.flate { - flate.release(); + 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 { @@ -1533,10 +1624,12 @@ impl Producer { } } - /// 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()) } /// Tick of the group's last cache access, driving eviction protection and age @@ -1797,34 +1890,21 @@ impl Prefetch { /// Refill with up to `budget` of the completed frames from `local` on. Must be /// drained first (`pop` returned `None`). /// - /// A compressed group fills inflated frames, or with `raw` its stored slices and their - /// inflated sizes. A frame that fails to inflate ends the batch, failing it if first. - fn fill(&mut self, state: &GroupState, local: usize, budget: usize, raw: bool) -> Result<()> { + /// 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; - let frames = state.frames.range(local..).take(budget.min(Self::CAP)); - match &state.flate { - Some(flate) if !raw => { - for frame in frames { - let payload = match state.plain(flate, local + self.len) { - Ok(payload) => payload, - Err(err) if self.len == 0 => return Err(err), - Err(_) => break, - }; - self.frames[self.len].write(Frame { - timestamp: frame.timestamp, - payload, - }); - self.len += 1; - } - } - _ => { - for frame in frames { - self.frames[self.len].write(frame.clone()); - self.len += 1; - } - } + 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 => { @@ -1844,6 +1924,27 @@ 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(()) } @@ -2598,9 +2699,32 @@ impl Cursor { } let (index, raw) = (self.index, self.raw); - let Some((info, source)) = ready!(self.poll(waiter, |state| state.poll_frame_source(index, raw))?) else { + 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 @@ -2642,20 +2766,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, raw)?; + 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))), } @@ -4000,6 +4126,82 @@ mod test { assert_eq!(pool.used(), 0, "the inflated copy is released with the group"); } + /// 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.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.cache_size(), pool.used()); + let (first, second) = (take_slices(&group, 2), take_slices(&group, 2)); + first.run(&meter); + assert_eq!( + group.cache_size(), + stored + plain, + "the copy counts toward eviction once built" + ); + assert_eq!(pool.used(), used + plain); + second.run(&meter); + assert_eq!(group.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.clone().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 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() { diff --git a/rs/moq-net/src/stats.rs b/rs/moq-net/src/stats.rs index d494804c29e..2d40418f760 100644 --- a/rs/moq-net/src/stats.rs +++ b/rs/moq-net/src/stats.rs @@ -56,6 +56,11 @@ //! 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. 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 +184,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 +239,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 +254,7 @@ impl Counters { frames, groups, datagrams, + inflated, stale, } } @@ -454,6 +463,10 @@ 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; `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 +513,7 @@ struct TrafficSer { frames: u64, groups: u64, datagrams: u64, + inflated: u64, stale: Content, } @@ -524,6 +538,7 @@ impl From for TrafficSer { frames: t.frames, groups: t.groups, datagrams: t.datagrams, + inflated: t.inflated, stale: t.stale, } } @@ -550,6 +565,7 @@ struct TrafficDe { frames: u64, groups: u64, datagrams: u64, + inflated: u64, stale: Content, } @@ -568,6 +584,7 @@ impl From for Traffic { frames: d.frames, groups: d.groups, datagrams: d.datagrams, + inflated: d.inflated, stale: d.stale, } } @@ -600,6 +617,7 @@ impl Traffic { self.frames += other.frames; self.groups += other.groups; self.datagrams += other.datagrams; + self.inflated += other.inflated; self.stale.add(other.stale); } @@ -1803,6 +1821,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-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index a3bb8a6885a..8062d8605a3 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 From d3aa99b88315e31814f0c5a60070a72ed79d74ac Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 16:47:41 -0700 Subject: [PATCH 09/20] compress: a held copy continues an inflating reader from frame 0 too Main's held-copy fallback (#5836) positioned the group at the reader's frame alone; route it through the same check as the serving copy, so a reader that inflates a compressed group takes the prefix it needs. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/resume.rs | 46 ++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 29b4d024ab5..818c96abb56 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1053,7 +1053,7 @@ impl Recover { // fixes its content. A stall only moves to the serving copy, so two stalled copies // never trade the group back and forth. if failed.is_some() - && let Some(replacement) = self.held(index) + && let Some(replacement) = self.held(frames.clone()) { return Poll::Ready(Ok(replacement)); } @@ -1089,9 +1089,9 @@ impl Recover { } } - /// The group from the newest of the reader's other copies that still holds it unfailed, - /// positioned at frame `index`. - fn held(&self, index: u64) -> Option { + /// The group from the newest of the reader's other copies that still holds `frames` of it + /// unfailed, positioned at their end. + fn held(&self, frames: std::ops::Range) -> Option { let reader = self.reader.as_ref()?.upgrade()?; let reader = reader.lock().unwrap_or_else(PoisonError::into_inner); reader.copies.iter().rev().find_map(|copy| { @@ -1099,9 +1099,7 @@ impl Recover { return None; } let mut group = copy.track.peek_group(self.sequence)?; - lend_head(&self.handoff, self.sequence, ©.track, &group); - group.start_at(index); - (group.index() == index).then(|| Replacement { + continues(&self.handoff, self.sequence, ©.track, &mut group, frames.clone()).then(|| Replacement { group, generation: copy.generation, copy: copy.track.clone(), @@ -1121,20 +1119,9 @@ impl Recover { // A newer copy's subscription delivered it: continue from there. The copy that // failed delivered it already, so its subscription will not again. let same = generation == self.generation; - // The failed copy released the frames before the reader's, so a reader that inflates - // takes them from the replacement. - let std::ops::Range { start, end: index } = frames; - let (handoff, sequence) = (&self.handoff, self.sequence); - let continues = |group: &mut group::Consumer| { - lend_head(handoff, sequence, serving, group); - group.start_at(start); - let held = group.index() == start; - group.start_at(index); - held && group.index() == index - }; if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) - && continues(&mut group) + && continues(&self.handoff, self.sequence, serving, &mut group, frames.clone()) { return Poll::Ready(Ok(Replacement { group, @@ -1147,7 +1134,7 @@ impl Recover { if self.fetch.as_ref().is_none_or(|(asked, _)| *asked != generation) { let options = group::Fetch { max_delay: self.max_delay, - frame_start: start, + frame_start: frames.start, ..Default::default() }; self.fetch = Some((generation, Fetch::Pending(serving.fetch_group(self.sequence, options)))); @@ -1161,7 +1148,7 @@ impl Recover { Fetch::Refused(err) => err.clone(), Fetch::Pending(pending) => match ready!(kio::Task::poll(&mut **pending, waiter)) { Ok(mut group) => { - if continues(&mut group) { + if continues(&self.handoff, self.sequence, serving, &mut group, frames.clone()) { return Poll::Ready(Ok(Replacement { group, generation, @@ -1224,6 +1211,23 @@ impl Recover { } } +/// Whether `copy`'s `group` still holds `frames`, positioning it at their end. The failed +/// copy released the frames before the reader's, so a reader that inflates takes them from +/// the replacement. +fn continues( + handoff: &group::Handoff, + sequence: u64, + copy: &track::Consumer, + group: &mut group::Consumer, + frames: std::ops::Range, +) -> bool { + lend_head(handoff, sequence, copy, group); + group.start_at(frames.start); + let held = group.index() == frames.start; + group.start_at(frames.end); + held && group.index() == frames.end +} + /// Lend the head `handoff` holds to `serving`'s copy of group `sequence`, `group`, when that /// starts later: the fetch for the rest asks only from the reader's frame. fn lend_head(handoff: &group::Handoff, sequence: u64, serving: &track::Consumer, group: &group::Consumer) { From 9047b017fc4b2f746d7a01347ea68efc461218ea Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 10:17:40 -0700 Subject: [PATCH 10/20] fix(net): resume compressed groups through main's head handoff Main's head handoff already lends a failed route's compressed head to the replacement, so drop the fetch-from-frame-0 widening. A plain reader still fails loud when the head was reclaimed instead of spinning on a replacement it cannot inflate. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/frame.rs | 2 +- rs/moq-net/src/model/group.rs | 16 ++-- rs/moq-net/src/model/resume.rs | 133 +++++++++++++++++++++------------ 3 files changed, 96 insertions(+), 55 deletions(-) diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 478bc326079..b0a3a4558dc 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -814,7 +814,7 @@ impl Consumer { if self.state.read().sparse() { return Poll::Ready(Err(Error::Unsupported)); } - let mut replacement = match recover.poll(*index..*index, failed.as_ref(), waiter) { + let mut replacement = match recover.poll(*index, failed.as_ref(), waiter) { Poll::Ready(Ok(group)) => group, Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => return Poll::Pending, diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index cb69eb34b4b..24f49b228fc 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2468,17 +2468,19 @@ impl Consumer { if self.cursor.state.read().sparse() { return Poll::Ready(Err(Error::Unsupported)); } - // A plain read of a compressed group inflates from frame 0. - let index = self.cursor.index as u64; - let start = match !self.cursor.raw && self.cursor.state.read().flate.is_some() { - true => 0, - false => index, - }; - let replacement = match recover.poll(start..index, failed.as_ref(), waiter) { + let replacement = match recover.poll(self.cursor.index as u64, failed.as_ref(), waiter) { Poll::Ready(Ok(group)) => group, 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, raw) = (self.cursor.index, self.cursor.end, self.cursor.raw); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 50eb7cd18d4..9a5b9e432a6 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1244,14 +1244,13 @@ impl Recover { } } - /// Poll for the serving route's copy of the group, holding `frames` and positioned at - /// their end. A reader that inflates a compressed group needs it from frame 0. + /// Poll for the serving route's copy of the group, positioned at frame `index`. /// /// `failed` is the error the current copy ended with, if it did; a stall is `None`. /// Returns the copy's error when nothing can continue the group. pub(super) fn poll( &mut self, - frames: std::ops::Range, + index: u64, failed: Option<&Error>, waiter: &kio::Waiter, ) -> Poll> { @@ -1281,7 +1280,7 @@ impl Recover { // fixes its content. A stall only moves to the serving copy, so two stalled copies // never trade the group back and forth. if failed.is_some() - && let Some(replacement) = self.held(frames.clone()) + && let Some(replacement) = self.held(index) { return Poll::Ready(Ok(replacement)); } @@ -1296,7 +1295,7 @@ impl Recover { if generation == self.generation && failed.is_none() { return Poll::Pending; } - let res = self.poll_serving(generation, &serving, frames.clone(), failed, waiter); + let res = self.poll_serving(generation, &serving, index, failed, waiter); // The serving route failed too, and no front is left to replace it. if let (Poll::Pending, Some(err)) = (&res, failed) && (closed || end.is_some()) @@ -1317,9 +1316,9 @@ impl Recover { } } - /// The group from the newest of the reader's other copies that still holds `frames` of it - /// unfailed, positioned at their end. - fn held(&self, frames: std::ops::Range) -> Option { + /// The group from the newest of the reader's other copies that still holds it unfailed, + /// positioned at frame `index`. + fn held(&self, index: u64) -> Option { let reader = self.reader.as_ref()?.upgrade()?; let reader = reader.lock().unwrap_or_else(PoisonError::into_inner); reader.copies.iter().rev().find_map(|copy| { @@ -1327,7 +1326,9 @@ impl Recover { return None; } let mut group = copy.track.peek_group(self.sequence)?; - continues(&self.handoff, self.sequence, ©.track, &mut group, frames.clone()).then(|| Replacement { + lend_head(&self.handoff, self.sequence, ©.track, &group); + group.start_at(index); + (group.index() == index).then(|| Replacement { group, generation: copy.generation, copy: copy.track.clone(), @@ -1340,29 +1341,30 @@ impl Recover { &mut self, generation: u64, serving: &track::Consumer, - frames: std::ops::Range, + index: u64, failed: Option<&Error>, waiter: &kio::Waiter, ) -> Poll> { // A newer copy's subscription delivered it: continue from there. The copy that // failed delivered it already, so its subscription will not again. let same = generation == self.generation; - if !same - && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) - && continues(&self.handoff, self.sequence, serving, &mut group, frames.clone()) - { - return Poll::Ready(Ok(Replacement { - group, - generation, - copy: serving.clone(), - })); + if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) { + lend_head(&self.handoff, self.sequence, serving, &group); + group.start_at(index); + if group.index() == index { + return Poll::Ready(Ok(Replacement { + group, + generation, + copy: serving.clone(), + })); + } } // Otherwise ask for the rest. The subscription may still deliver it first. if self.fetch.as_ref().is_none_or(|(asked, _)| *asked != generation) { let options = group::Fetch { max_delay: self.max_delay, - frame_start: frames.start, + frame_start: index, ..Default::default() }; self.fetch = Some((generation, Fetch::Pending(serving.fetch_group(self.sequence, options)))); @@ -1376,7 +1378,9 @@ impl Recover { Fetch::Refused(err) => err.clone(), Fetch::Pending(pending) => match ready!(kio::Task::poll(&mut **pending, waiter)) { Ok(mut group) => { - if continues(&self.handoff, self.sequence, serving, &mut group, frames.clone()) { + lend_head(&self.handoff, self.sequence, serving, &group); + group.start_at(index); + if group.index() == index { return Poll::Ready(Ok(Replacement { group, generation, @@ -1439,23 +1443,6 @@ impl Recover { } } -/// Whether `copy`'s `group` still holds `frames`, positioning it at their end. The failed -/// copy released the frames before the reader's, so a reader that inflates takes them from -/// the replacement. -fn continues( - handoff: &group::Handoff, - sequence: u64, - copy: &track::Consumer, - group: &mut group::Consumer, - frames: std::ops::Range, -) -> bool { - lend_head(handoff, sequence, copy, group); - group.start_at(frames.start); - let held = group.index() == frames.start; - group.start_at(frames.end); - held && group.index() == frames.end -} - /// Lend the head `handoff` holds to `serving`'s copy of group `sequence`, `group`, when that /// starts later: the fetch for the rest asks only from the reader's frame. fn lend_head(handoff: &group::Handoff, sequence: u64, serving: &track::Consumer, group: &group::Consumer) { @@ -1692,8 +1679,8 @@ mod test { ); } - /// A plain reader of a compressed group inflates the replacement's frames from frame 0, - /// since the failed copy released the ones it read. + /// 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() { @@ -1716,18 +1703,70 @@ mod test { 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 mut whole = b.create_group(group::Info { sequence: 0 }).unwrap(); - for (ms, frame) in frames.iter().enumerate() { - whole.write_frame(ts(ms as u64), frame.clone()).unwrap(); - } - whole.finish().unwrap(); + let dynamic = b.dynamic(); routes.serve(b.consume()); - open.abort(Error::Cancel).unwrap(); - + 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); + } + + /// 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] From 58eab0d8008c9077efc0237b585c64dde0dbb68b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 10:29:04 -0700 Subject: [PATCH 11/20] fix(net): bill a compressed group's codec state to the cache pool The encoder (about 256 KiB) and each group's shared decoder (about 40 KiB) were unbilled, so a peer opening many compressed groups could make readers hold decoders the pool never saw. Both now count toward the group's eviction size while held, and finishing drops them once nothing needs them. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/cache.rs | 15 ++++++- rs/moq-net/src/model/flate.rs | 10 +++++ rs/moq-net/src/model/group.rs | 81 ++++++++++++++++++++++++++++++++--- 3 files changed, 98 insertions(+), 8 deletions(-) diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 9c24d9eb6b4..61603c591d2 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1209,7 +1209,7 @@ 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. Released on [`Self::clear`] or drop. +/// 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. @@ -1234,6 +1234,19 @@ impl Extra { 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 { diff --git a/rs/moq-net/src/model/flate.rs b/rs/moq-net/src/model/flate.rs index d014d3dd7b9..c124550b3b2 100644 --- a/rs/moq-net/src/model/flate.rs +++ b/rs/moq-net/src/model/flate.rs @@ -23,6 +23,16 @@ 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); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index ed1b9d4f192..8552c272967 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -324,7 +324,24 @@ impl Flate { /// Compress a locally written frame, returning its stored slice. fn deflate(&mut self, payload: &[u8]) -> Bytes { - self.encoder.get_or_insert_with(flate::Encoder::new).frame(payload) + 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: the encoder, and the decoder if its + /// readers already inflated every frame. + fn finish(&mut self) { + if self.encoder.take().is_some() { + self.plain.bill.sub(flate::ENCODER_HEAP); + } + let mut plain = self.plain.lock(); + if plain.frames.len() == self.sizes.len() { + self.plain.drop_decoder(&mut plain); + } } /// Drop everything but how the group is read, failing a late inflater with `err`. @@ -343,8 +360,8 @@ 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, counted toward the group's eviction size once they exist. - // Changed only under `state`. + // 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, } @@ -367,6 +384,13 @@ impl Plain { 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(); @@ -418,7 +442,14 @@ impl Inflate { } let frame = usize::try_from(*size) .map_err(|_| Error::FrameTooLarge) - .and_then(|size| state.decoder.get_or_insert_with(flate::Decoder::new).frame(slice, size)); + .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); @@ -426,12 +457,12 @@ impl Inflate { state.frames.push_back(frame); self.plain.len.store(state.frames.len(), Ordering::Release); if self.fin == Some(state.frames.len()) { - state.decoder = None; + self.plain.drop_decoder(&mut state); } } Err(err) => { state.err = Some(err); - state.decoder = None; + self.plain.drop_decoder(&mut state); break; } } @@ -1551,7 +1582,7 @@ impl Producer { state.fin = Some(state.next_index); // No frame follows to compress. if let Some(flate) = &mut state.flate { - flate.encoder = None; + flate.finish(); } // A finished group can no longer raise the track's largest, which may end its stream. self.handle.cache.finish_largest(self.sequence); @@ -4713,6 +4744,42 @@ mod test { assert_eq!(inflated(), plain); } + /// 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); + } + /// 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] From a197b340816b7e311810739ba4eb756505544ed0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 10:55:35 -0700 Subject: [PATCH 12/20] fix(net): settle debt after inflating, meter compressed writes as stored A plain reader's inflation billed the pool but never settled the track's eviction debt, so a finished compressed track could leave a capacity-only pool over its target for good. Inflation now settles once the plain copy's lock is released. write_frames metered the batch's plain bytes, and a chunked frame metered its plain chunks, where write_frame meters the stored slice. All three now count the stored bytes. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/cache.rs | 7 ++++ rs/moq-net/src/model/group.rs | 66 ++++++++++++++++++++++++++++++++--- rs/moq-net/src/model/track.rs | 41 ++++++++++++++++++++++ 3 files changed, 110 insertions(+), 4 deletions(-) diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 61603c591d2..74c5f73868c 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1229,6 +1229,13 @@ impl Extra { } } + /// 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) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 8552c272967..876f29cbc14 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -430,7 +430,8 @@ 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. + /// 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(); @@ -467,6 +468,9 @@ impl Inflate { } } } + // 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. @@ -1347,7 +1351,7 @@ impl Producer { self.handle.cache.wakes().presented(latest); } self.stats.frames(count as u64); - self.stats.bytes(bytes); + self.stats.bytes(stored); Ok(()) } @@ -1363,7 +1367,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)) } @@ -1381,6 +1385,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 { @@ -1394,10 +1399,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 @@ -1536,6 +1550,7 @@ impl Producer { } 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); @@ -4744,6 +4759,49 @@ mod test { assert_eq!(inflated(), plain); } + /// A compressed group meters `bytes` as stored, whether a frame is written whole, in a + /// batch, or in chunks. + #[test] + 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] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 762ffb9ebdf..4a42f0feca9 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -13218,6 +13218,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 mut 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")] From 1417eaf21c8ca738769d6638f45fea7e113207b8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:15:08 -0700 Subject: [PATCH 13/20] test(net): gate the compressed metering test on async, drop an unused mut Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/group.rs | 1 + rs/moq-net/src/model/track.rs | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 876f29cbc14..f58742d73e1 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -4762,6 +4762,7 @@ mod test { /// 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 = || { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 4a42f0feca9..95e2243a1e2 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -13229,7 +13229,7 @@ mod test { pool: pool.clone(), ..Default::default() }); - let mut producer = Producer::new(broadcast, "test", Info::timed().with_compress(true)); + 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 { From 014c577d235c2965dd0778f7a17306c2b7a4af4b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:27:48 -0700 Subject: [PATCH 14/20] fix(net): meter compressed datagrams in the form the wire carries A relay metered a compressed track's datagrams as their inflated payload on both paths: egress counted it when the subscriber read it, before the session picked the DEFLATE slice for a lite-07 peer, and ingress inflated before counting. Ingress and local producers now meter the stored slice, egress meters what it sends, and only inflated counts the inflated bytes. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 12 ++-- rs/moq-net/src/model/datagram.rs | 16 ++++++ rs/moq-net/src/model/track.rs | 48 ++++++++++------ rs/moq-net/tests/integration/compress.rs | 73 ++++++++++++++++++++++++ 4 files changed, 126 insertions(+), 23 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 2d2346a0ec6..75123f65692 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -3526,18 +3526,13 @@ impl Subscription { }; let sequence = datagram.sequence; // A lite-07 peer takes a compressed track's datagram as stored, others inflated. - let (payload, inflated) = match datagram.deflated { - Some(deflated) if self.version.has_compression() => { - (deflated, Some(datagram.datagram.payload.len() as u64)) - } - _ => (datagram.datagram.payload, None), - }; + let (payload, inflated) = datagram.sent(self.version.has_compression()); let body = lite::Datagram { subscribe: self.id, sequence, timestamp, inflated, - payload, + payload: payload.clone(), }; // has_datagrams is checked before this runs, and the timescale is set wherever the // version needs a timestamp, so encoding never hits a version guard. @@ -3912,6 +3907,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); } diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index e71ad7632dc..ba8ede4cf9e 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -63,6 +63,22 @@ pub(crate) struct Stored { 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. + 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 { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 95e2243a1e2..cec7f15e8a0 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2465,7 +2465,6 @@ impl Producer { } state.advance(sequence, false); state.cache.finish_largest(sequence); - meter.datagram(payload.len() as u64); // A datagram is its own group, so it compresses alone. let deflated = state .info @@ -2473,7 +2472,7 @@ impl Producer { .unwrap() .compress .then(|| super::flate::Encoder::new().frame(&payload)); - state.push_datagram(super::datagram::Stored { + let datagram = super::datagram::Stored { datagram: Datagram { sequence, timestamp, @@ -2481,7 +2480,9 @@ impl Producer { }, wire: None, deflated, - }); + }; + meter.datagram(datagram.stored_len()); + state.push_datagram(datagram); let cache = state.cache.clone(); drop(state); cache.settle(None); @@ -2534,7 +2535,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); @@ -2563,6 +2564,7 @@ impl Producer { .filter(|size| *size <= super::datagram::MAX_DATAGRAM_PAYLOAD) .ok_or(Error::FrameTooLarge)?; let payload = super::flate::Decoder::new().frame(&deflated, size)?; + self.stats.meter().inflated(payload.len() as u64); self.insert_wire_datagram(super::datagram::Stored { datagram: Datagram { sequence, @@ -5936,12 +5938,23 @@ impl Subscriber { /// `Poll::Ready(Ok(None))` when the track is finished, `Poll::Ready(Err(e))` when the track /// is aborted, or `Poll::Pending` when none is buffered yet. pub fn poll_recv_datagram(&mut self, waiter: &kio::Waiter) -> Poll>> { - self.poll_recv_stored_datagram(waiter) - .map(|res| res.map(|datagram| datagram.map(|datagram| datagram.datagram))) + let datagram = ready!(self.poll_recv_stored_datagram(waiter))?; + if let Some(datagram) = &datagram { + self.meter_datagram(datagram.payload.len() as u64); + } + Poll::Ready(Ok(datagram.map(|datagram| 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 meter_datagram(&self, bytes: u64) { + self.stats.meter().datagram(bytes); } /// [`Self::poll_recv_datagram`], keeping what is stored beside the payload: a compressed - /// track's DEFLATE slice. + /// track's DEFLATE slice. Unmetered: the caller meters the form it hands on with + /// [`Self::meter_datagram`]. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: passthrough pub(crate) fn poll_recv_stored_datagram( @@ -5949,7 +5962,7 @@ impl Subscriber { waiter: &kio::Waiter, ) -> Poll>> { loop { - let Some(datagram) = ready!(self.poll_recv_wire_datagram(waiter))? else { + let Some(datagram) = ready!(self.poll_recv_unmetered_datagram(waiter))? else { return Poll::Ready(Ok(None)); }; if datagram @@ -5963,24 +5976,27 @@ impl Subscriber { } } + /// The next datagram with its wire metadata, 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 meter = self.stats.meter(); - let res = 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. + let res = self.poll_recv_unmetered_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 } + fn poll_recv_unmetered_datagram(&mut self, waiter: &kio::Waiter) -> Poll>> { + match &mut self.inner { + Inner::Plain(cursor) => cursor.poll_recv_datagram(waiter), + Inner::Resume(resume, _) => resume.poll_recv_datagram(&self.delivered, waiter), + } + } + /// Receive the next datagram in arrival order. /// /// A best-effort channel parallel to [`Self::recv_group`]; the two share only the sequence diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs index b83b7d50018..e1aa55702d4 100644 --- a/rs/moq-net/tests/integration/compress.rs +++ b/rs/moq-net/tests/integration/compress.rs @@ -142,3 +142,76 @@ async fn datagrams_serve_every_version() { .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")); + } +} From ed5a60a26433c1afe8c2fe4f379b275be1ff787b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:28:46 -0700 Subject: [PATCH 15/20] docs(net): received compressed datagrams count toward inflated Co-Authored-By: Claude Opus 5.5 --- doc/concept/stats.md | 2 +- rs/moq-net/src/stats.rs | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/concept/stats.md b/doc/concept/stats.md index ab26db93ff3..e63e6953066 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -230,7 +230,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. Not part of `bytes`, which counts payload as stored or sent. | +| `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/rs/moq-net/src/stats.rs b/rs/moq-net/src/stats.rs index 30af8d2a197..1d003dd43e9 100644 --- a/rs/moq-net/src/stats.rs +++ b/rs/moq-net/src/stats.rs @@ -59,7 +59,8 @@ //! * `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. Kept separate from +//! 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 @@ -464,8 +465,9 @@ pub struct Traffic { /// `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; `bytes` still - /// counts payload as stored or sent. + /// 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 From f6c90042dde90e8021155e85ac67cb49f5b3e2ca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:38:36 -0700 Subject: [PATCH 16/20] test(lite): decode the TRACK_INFO body, not its length prefix The unknown-codec test decoded the length-prefixed bytes as the body, and only failed for the right reason by accident; Refresh's new varint made the misread succeed. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/track.rs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index e5c3ad5c9b2..6c7f27e8908 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -336,13 +336,14 @@ mod test { assert_eq!(info_roundtrip(Version::Lite07, &info).compress, compress); } - let mut buf = TrackInfo { + // The message body, without its length prefix, ends in the codec id. + let mut buf = Vec::new(); + TrackInfo { compress: true, ..info_sample() } - .encode_bytes(Version::Lite07) - .unwrap() - .to_vec(); + .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(); From 54a28db7737aa784732a2fa112b3cb1116501c5a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:42:37 -0700 Subject: [PATCH 17/20] fix(net): allow Stored::sent without the async feature Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/datagram.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index ba8ede4cf9e..75fbee36e10 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -66,6 +66,7 @@ pub(crate) struct Stored { 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)), From 1698dbc9a8a50d310f2f9d3f48e464c894f11c40 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 13:53:54 -0700 Subject: [PATCH 18/20] fix(net): reject final DEFLATE blocks, stop resuming malformed groups - A slice ending in a final block is malformed, and the flate draft says so. - The decoder drops after the last frame even when the group finishes after a reader took its slices: the finished count lives in the shared plain copy. - A received compressed datagram counts toward `inflated` only once stored. - A plain read of a logical track whose group failed to inflate returns the error instead of resuming from the same copy forever. - Drafts: flate changelog appendix; lite cross-references the shared inflation instead of restating it. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-flate.md | 12 ++++++++- drafts/draft-lcurley-moq-lite.md | 2 +- rs/moq-net/src/model/flate.rs | 25 +++++++++++++++-- rs/moq-net/src/model/group.rs | 45 ++++++++++++++++++++++++------- rs/moq-net/src/model/resume.rs | 39 +++++++++++++++++++++++++++ rs/moq-net/src/model/track.rs | 7 +++-- 6 files changed, 114 insertions(+), 16 deletions(-) diff --git a/drafts/draft-lcurley-moq-flate.md b/drafts/draft-lcurley-moq-flate.md index 3a15129f10f..29828b52e54 100644 --- a/drafts/draft-lcurley-moq-flate.md +++ b/drafts/draft-lcurley-moq-flate.md @@ -68,7 +68,8 @@ 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. @@ -104,6 +105,15 @@ The format lives inside object payloads, and the declaration in the transport th --- 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-lite.md b/drafts/draft-lcurley-moq-lite.md index 195bf8f0e70..37ed3804f48 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1328,7 +1328,7 @@ 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; a relay inflates each Group once for every such subscriber. +A publisher that cannot send this field, on lite-06 and earlier, MUST send the Track's frames inflated instead. ## SUBSCRIBE_OK {#subscribe-ok} A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position. diff --git a/rs/moq-net/src/model/flate.rs b/rs/moq-net/src/model/flate.rs index c124550b3b2..14a139e027f 100644 --- a/rs/moq-net/src/model/flate.rs +++ b/rs/moq-net/src/model/flate.rs @@ -93,7 +93,8 @@ impl Decoder { /// /// 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. + /// 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 { @@ -116,6 +117,10 @@ impl Decoder { .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 { @@ -124,7 +129,7 @@ impl Decoder { out.extend_from_slice(&tmp[..produced]); input = &input[consumed..]; - if matches!(status, Status::StreamEnd) || (input.is_empty() && produced < tmp.len()) { + if input.is_empty() && produced < tmp.len() { break; } // No progress: the marker needed no further output. @@ -206,6 +211,22 @@ mod test { 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!( diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index f58742d73e1..8af272c6eb6 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -332,14 +332,15 @@ impl Flate { encoder.frame(payload) } - /// Drop the codec state once no frame follows: the encoder, and the decoder if its - /// readers already inflated every frame. - fn finish(&mut self) { + /// 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(); - if plain.frames.len() == self.sizes.len() { + plain.fin = Some(fin); + if plain.frames.len() == fin { self.plain.drop_decoder(&mut plain); } } @@ -372,6 +373,9 @@ struct PlainState { 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 @@ -404,6 +408,12 @@ impl Plain { } } + /// 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; @@ -422,8 +432,6 @@ struct Inflate { from: usize, // Each slice with its declared inflated size. slices: Vec<(Bytes, u64)>, - // The group's frame count once finished, so the decoder drops after the last frame. - fin: Option, } impl Inflate { @@ -457,7 +465,7 @@ impl Inflate { meter.inflated(frame.len() as u64); state.frames.push_back(frame); self.plain.len.store(state.frames.len(), Ordering::Release); - if self.fin == Some(state.frames.len()) { + if state.fin == Some(state.frames.len()) { self.plain.drop_decoder(&mut state); } } @@ -550,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() @@ -630,7 +643,6 @@ impl GroupState { slices: (from..=last) .map(|local| (self.frames[local].payload.clone(), flate.sizes[local])) .collect(), - fin: self.fin, }) } @@ -1594,10 +1606,11 @@ 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(); + 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); @@ -2555,6 +2568,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, }; @@ -4837,6 +4852,16 @@ mod test { 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, diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 8f13489569f..5fc2e8f9795 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1719,6 +1719,45 @@ mod test { 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] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index cec7f15e8a0..453604eef4d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2564,7 +2564,7 @@ impl Producer { .filter(|size| *size <= super::datagram::MAX_DATAGRAM_PAYLOAD) .ok_or(Error::FrameTooLarge)?; let payload = super::flate::Decoder::new().frame(&deflated, size)?; - self.stats.meter().inflated(payload.len() as u64); + let inflated = payload.len() as u64; self.insert_wire_datagram(super::datagram::Stored { datagram: Datagram { sequence, @@ -2573,7 +2573,10 @@ impl Producer { }, wire: None, deflated: Some(deflated), - }) + })?; + // 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. From 20613978466ce511fa59550e5b30e268c92532d0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 15:18:34 -0700 Subject: [PATCH 19/20] docs(go): note TrackInfo.Compress in the migration guide Co-Authored-By: Claude Opus 5.5 --- go/wrapper/MIGRATE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index bd15cc49975..acc52be62dc 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. + ### JSON consumers return `*json.Timed` (#5677) `SnapshotConsumer.Next`, `StreamConsumer.Next`, and `All` return `*Timed{Value, Timestamp}` instead of the raw message; `Timestamp` is a `*time.Duration`, nil when untimed. From 66f4655aa5c93780e83b2bf9c262574093e271a0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 15:28:41 -0700 Subject: [PATCH 20/20] style(net): format the merge resolution Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/fuzz.rs | 19 ++++++++++--------- rs/moq-net/src/lite/datagram.rs | 5 ++++- rs/moq-net/src/lite/ietf.rs | 18 ++++++++++++------ 3 files changed, 26 insertions(+), 16 deletions(-) diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 7d0f6288584..a1305df7a61 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -162,7 +162,8 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { for timescale in [Some(crate::Timescale::MILLI), None] { 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 { + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| format) + else { continue; }; any = true; @@ -171,8 +172,8 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { continue; }; - let echo = - lite::Datagram::decode(first, version, ietf, |_| format).expect("could not decode our own encoding"); + 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"); } } @@ -482,14 +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, |_| { - lite::Format { + 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(), + }) + .map(|_| 1) + .unwrap() + } Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), } } diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 49e0cb1b39d..d418cef2a04 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -171,7 +171,10 @@ mod test { }; 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); + assert_eq!( + Datagram::decode(buf, Version::Lite07, false, |_| COMPRESSED).unwrap(), + dg + ); for version in [Version::Lite05, Version::Lite06] { assert!( diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index ac0af9a8510..c5e32a0def9 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -1439,17 +1439,23 @@ mod hop_tests { 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_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(); + 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());