From 0a52b90324fd3614098efc8d92ba3d752e51c9c2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 21:39:10 -0700 Subject: [PATCH 01/25] quest: claim m1/ietf-extension/lite Co-Authored-By: Claude Opus 5.5 From c09f61d204942b55b35353a6fd017b803c3b02f2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:08:19 -0700 Subject: [PATCH 02/25] wip(lite): ietf extension carries moq-transport state across lite-07 Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/client.rs | 4 +- rs/moq-net/src/fuzz.rs | 7 +- rs/moq-net/src/ietf/mod.rs | 2 +- rs/moq-net/src/ietf/object.rs | 85 +++-- rs/moq-net/src/lite/datagram.rs | 57 ++- rs/moq-net/src/lite/ietf.rs | 603 ++++++++++++++++++++++++++++++ rs/moq-net/src/lite/mod.rs | 1 + rs/moq-net/src/lite/publisher.rs | 222 ++++++++--- rs/moq-net/src/lite/session.rs | 2 +- rs/moq-net/src/lite/setup.rs | 49 +++ rs/moq-net/src/lite/subscriber.rs | 193 +++++++++- rs/moq-net/src/lite/version.rs | 12 + rs/moq-net/src/model/track.rs | 3 +- rs/moq-net/src/server.rs | 5 +- rs/moq-net/src/setup.rs | 8 +- rs/moq-net/src/test_interop.rs | 2 + 16 files changed, 1143 insertions(+), 112 deletions(-) create mode 100644 rs/moq-net/src/lite/ietf.rs diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 77ac0a8c617..fa06045ed8b 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -95,7 +95,8 @@ impl Client { self } - /// Choose which moq-transport extensions to offer in SETUP. Defaults to all of them. + /// Choose which extensions to offer in SETUP. Defaults to every moq-transport one, and + /// not [`ietf`](setup::Extensions::ietf), which only relays turn on. pub fn with_extensions(mut self, extensions: setup::Extensions) -> Self { self.extensions = extensions; self @@ -200,6 +201,7 @@ impl Client { cost: self.cost, // Filled by `lite::start` from the attached origin handles. hop: None, + ietf: self.extensions.ietf && version.has_ietf(), } } else { lite::Setup::default() diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 442fead6fed..d4f70613ef2 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -149,7 +149,7 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { // The body doesn't say whether it carries a timestamp, so try both readings. let mut any = false; for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, |_| timed) else { + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, false, |_| timed) else { continue; }; any = true; @@ -158,7 +158,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, false, |_| timed).expect("could not decode our own encoding"); assert_eq!(echo, decoded, "datagram did not survive a round trip"); } any @@ -432,6 +432,7 @@ impl LiteSample { sequence: 1_234, timestamp: Some(1_234_567_890), payload: bytes::Bytes::new(), + ietf: None, } .encode(w, version) .unwrap(), @@ -463,7 +464,7 @@ 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, false, |_| true) .map(|_| 1) .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index fb9b4ecdef0..a934582f0df 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -28,7 +28,7 @@ mod location; pub(crate) mod max_age; pub mod message; mod namespace; -mod object; +pub(crate) mod object; pub mod peer; mod priority; mod properties; diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 748951d0811..cd41857f385 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -125,52 +125,77 @@ pub(super) fn read(data: &Bytes, version: Version, timescale: Option) }) } -/// Serialize relayed properties for `version`, with Timestamps in the `timescale` the -/// egress declares, if any. -pub(super) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { - if properties - .immutable - .is_some_and(|original| original != encoding(version)) - { - return Err(Error::Unsupported); - } - // An untimed ingress forwards its Timestamps as is. A timed one to an egress that - // declares no units drops them, as a plain frame there carries none. +/// The mutable Timestamp `properties` carries, in the `timescale` an egress declares. +/// +/// An untimed ingress forwards its Timestamps as is. A timed one to an egress that +/// declares no units drops them, as a plain frame there carries none. Rewriting or +/// dropping an immutable Timestamp would break it, so that is refused. +pub(crate) fn egress_time(properties: &Properties, timescale: Option) -> Result, Error> { let unstamped = properties.timescale.is_some() && timescale.is_none(); let convert = match (properties.timescale, timescale) { (Some(from), Some(to)) if from != to => Some((from, to)), _ => None, }; - let time = |value: u64| -> Result { - Ok(Value::Int(match convert { + if properties.sealed_time && (convert.is_some() || unstamped) { + return Err(Error::Unsupported); + } + properties + .timestamp + .filter(|_| !unstamped) + .map(|value| match convert { Some((from, to)) => Timestamp::new(value, from) .and_then(|timestamp| timestamp.convert(to)) - .map_err(|_| Error::Unsupported)? - .value(), - None => value, - })) + .map(|timestamp| timestamp.value()) + .map_err(|_| Error::Unsupported), + None => Ok(value), + }) + .transpose() +} + +/// What an Immutable Properties block in the `encoding` family seals. +pub(crate) struct Sealed { + /// It holds a Timestamp. + pub time: bool, + /// Its Prior Object ID Gap, if any. + pub gap: Option, +} + +/// Parse an Immutable Properties block (0x0b) serialized in the `encoding` family. +pub(crate) fn sealed(bytes: &Bytes, encoding: Encoding) -> Result { + // Any draft in the family parses its keys and integers the same way. + let version = match encoding { + Encoding::Absolute => Version::Draft14, + Encoding::DeltaQuic => Version::Draft16, + Encoding::Delta { seven: false } => Version::Draft17, + Encoding::Delta { seven: true } => Version::Draft18, }; - // Rewriting or dropping an immutable Timestamp would break it; forwarding it would - // change its meaning. - if properties.sealed_time && (convert.is_some() || unstamped) { + let nested = list(bytes, version, true).map_err(|_| Error::MalformedTrack)?; + Ok(Sealed { + time: nested.time.is_some(), + gap: nested.gap, + }) +} + +/// Serialize relayed properties for `version`, with Timestamps in the `timescale` the +/// egress declares, if any. +pub(super) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { + if properties + .immutable + .is_some_and(|original| original != encoding(version)) + { return Err(Error::Unsupported); } + let timestamp = egress_time(properties, timescale)?; // Across draft-19, forwarding 0x06 would give it a different meaning. // A mutable one is dropped; a sealed one is refused. let flipped = properties.delivery_timeout != has_delivery_timeout(version); if flipped && sealed_key(properties, version, 0x06)? { return Err(Error::Unsupported); } - let timestamp = properties - .timestamp - .filter(|_| !unstamped) - .map(|value| { - Ok::<_, Error>(Property { - id: 0x10, - value: time(value)?, - }) - }) - .transpose()?; + let timestamp = timestamp.map(|value| Property { + id: 0x10, + value: Value::Int(value), + }); let mut sorted: Vec<_> = properties .values .iter() diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index e573d9e99be..9abb3310a0a 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -24,6 +24,9 @@ pub struct Datagram { pub timestamp: Option, /// The frame payload, delimited by the datagram boundary. pub payload: Bytes, + /// With the `ietf` extension negotiated, the moq-transport state a relay preserves, or + /// `Some(None)` for a plain datagram. `None` without the extension. + pub ietf: Option>, } impl Encode for Datagram { @@ -39,6 +42,17 @@ impl Encode for Datagram { w.varint(self.subscribe)?; w.varint(self.sequence)?; + if let Some(wire) = &self.ietf { + if !version.has_ietf() { + return Err(EncodeError::Version); + } + // A status carries no payload and no time. + let status = wire.as_ref().is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); + if status && (self.timestamp.is_some() || !self.payload.is_empty()) { + return Err(EncodeError::InvalidState); + } + super::ietf::encode_datagram(w, wire.as_ref(), version)?; + } if let Some(timestamp) = self.timestamp { w.varint(timestamp)?; } @@ -52,26 +66,45 @@ 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 { - if !version.has_datagrams() { + /// `ietf` says whether the session negotiated the extension, and `timed` 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, + ietf: bool, + timed: impl FnOnce(u64) -> bool, + ) -> Result { + if !version.has_datagrams() || (ietf && !version.has_ietf()) { return Err(DecodeError::Version); } 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 ietf = ietf.then(|| super::ietf::decode_datagram(&mut r, version)).transpose()?; + // A status carries no payload and no time. + let status = ietf + .as_ref() + .and_then(|wire| wire.as_ref()) + .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); + let timestamp = if timed(subscribe) && !status { + Some(r.varint()?) + } else { + None + }; // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); + if status && !payload.is_empty() { + return Err(DecodeError::InvalidValue); + } Ok(Self { subscribe, sequence, timestamp, payload, + ietf, }) } } @@ -87,9 +120,10 @@ mod test { sequence: 42, timestamp: Some(1_000), payload: Bytes::from_static(b"hello"), + ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| true).unwrap(); assert_eq!(decoded, original, "payload has no trailing length prefix"); } @@ -100,9 +134,10 @@ mod test { sequence: 0, timestamp: Some(0), payload: Bytes::new(), + ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| true).unwrap(); assert_eq!(decoded, original); } @@ -115,6 +150,7 @@ mod test { sequence: 2, timestamp: Some(3), payload: Bytes::from_static(b"world"), + ietf: None, }; let buf = dg.encode_bytes(Version::Lite05).unwrap(); // 1 + 1 + 1 (single-byte varints) + 5 payload = 8 bytes, no length byte. @@ -129,11 +165,12 @@ mod test { sequence: 2, timestamp: None, payload: Bytes::from_static(b"world"), + ietf: None, }; let buf = dg.encode_bytes(Version::Lite07).unwrap(); assert_eq!(buf.len(), 7); assert_eq!(&buf[2..], b"world"); - let decoded = Datagram::decode(buf, Version::Lite07, |id| { + let decoded = Datagram::decode(buf, Version::Lite07, false, |id| { assert_eq!(id, 1); false }) @@ -148,6 +185,7 @@ mod test { sequence: 2, timestamp: None, payload: Bytes::from_static(b"world"), + ietf: None, }; for version in [Version::Lite05, Version::Lite06] { assert!( @@ -164,11 +202,12 @@ mod test { sequence: 2, timestamp: Some(3), payload: Bytes::from_static(b"x"), + ietf: None, }; assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, |_| true), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| true), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs new file mode 100644 index 00000000000..a8bf9f45878 --- /dev/null +++ b/rs/moq-net/src/lite/ietf.rs @@ -0,0 +1,603 @@ +//! The `ietf` extension (draft-lcurley-moq-ietf): the moq-transport object state a relay +//! preserves, carried across a lite-07 hop when both SETUPs offer it. +//! +//! Every field here is crate-private relay metadata (see `model::object`). Plain readers +//! never see it, and a session without the extension sends none of it. + +use std::sync::Arc; + +use bytes::Bytes; + +use crate::{ + Error, Timescale, + coding::{DecodeError, Decoder, EncodeError, Encoder, Writer}, + group, + model::object::{Encoding, Fields, Properties, Property, Value}, +}; + +use super::{Message, Version}; + +/// The largest properties block a peer may make us buffer, as for a moq-transport object. +pub(crate) const MAX_PROPERTIES: usize = 64 * 1024; + +// Group State bits. +const RELAYED: u64 = 0x1; +const FIRST_OBJECT: u64 = 0x2; +const EXTENSIONS: u64 = 0x4; +const END_OF_GROUP: u64 = 0x8; + +// Datagram State bits, after RELAYED. +const OBJECT_ID: u64 = 0x2; +const PRIORITY: u64 = 0x4; +const DATAGRAM_END: u64 = 0x8; +const STATUS: u64 = 0x10; + +// Properties Flags: the low bit, then the Immutable Properties encoding above it. +const DELIVERY_TIMEOUT: u64 = 0x1; + +/// Property IDs the model reads. +const TIMESTAMP: u64 = 0x10; +const IMMUTABLE: u64 = 0x0b; +const GAP: u64 = 0x3e; + +/// The Group State a stream sends for its group's `wire` state. +/// +/// `whole` when the stream starts at the copy's first frame, so FIRST_OBJECT still holds, +/// and `capped` when it stops before the group may end, so its FIN cannot end the group. +pub(crate) fn encode_state(wire: Option<&group::Wire>, whole: bool, capped: bool) -> u64 { + let Some(wire) = wire else { + return 0; + }; + let mut state = RELAYED; + if wire.first_object && whole { + state |= FIRST_OBJECT; + } + if wire.extensions { + state |= EXTENSIONS; + } + if wire.has_end && !capped { + state |= END_OF_GROUP; + } + state +} + +/// The relay state a received Group State describes, or `None` for a plain group. +/// +/// The first object's ID is learned from the first record, so it starts at `frame_start`. +pub(crate) fn decode_state(state: u64, frame_start: u64) -> Result, Error> { + if state == 0 { + return Ok(None); + } + if state & RELAYED == 0 || state & !(RELAYED | FIRST_OBJECT | EXTENSIONS | END_OF_GROUP) != 0 { + return Err(Error::ProtocolViolation); + } + Ok(Some(group::Wire { + sparse: false, + first_object: state & FIRST_OBJECT != 0, + first_id: frame_start, + extensions: state & EXTENSIONS != 0, + has_end: state & END_OF_GROUP != 0, + fetchable: true, + last: None, + })) +} + +/// The first varint of an object record: the Object ID delta from `prior`, or the absolute +/// ID for the first record, with the END_OF_GROUP status in the low bit. +pub(crate) fn encode_object(prior: Option, id: u64, end: bool) -> Result { + let delta = match prior { + None => id, + Some(prior) => id + .checked_sub(prior) + .and_then(|step| step.checked_sub(1)) + .ok_or(Error::MalformedTrack)?, + }; + if delta > u64::MAX >> 1 { + return Err(Error::BoundsExceeded(crate::coding::BoundsExceeded)); + } + Ok(delta << 1 | u64::from(end)) +} + +/// The Object ID and END_OF_GROUP status an object record's first varint names. +pub(crate) fn decode_object(prior: Option, code: u64) -> Result<(u64, bool), Error> { + let delta = code >> 1; + let id = match prior { + None => Some(delta), + Some(prior) => prior.checked_add(1).and_then(|next| next.checked_add(delta)), + }; + Ok((id.ok_or(Error::ProtocolViolation)?, code & 1 != 0)) +} + +fn encoding_code(encoding: Option) -> u64 { + match encoding { + None => 0, + Some(Encoding::Absolute) => 1, + Some(Encoding::DeltaQuic) => 2, + Some(Encoding::Delta { seven: false }) => 3, + Some(Encoding::Delta { seven: true }) => 4, + } +} + +fn encode_flags(delivery_timeout: bool, immutable: Option) -> u64 { + u64::from(delivery_timeout) | encoding_code(immutable) << 1 +} + +fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { + let encoding = match flags >> 1 { + 0 => None, + 1 => Some(Encoding::Absolute), + 2 => Some(Encoding::DeltaQuic), + 3 => Some(Encoding::Delta { seven: false }), + 4 => Some(Encoding::Delta { seven: true }), + _ => return Err(DecodeError::InvalidValue), + }; + Ok((flags & DELIVERY_TIMEOUT != 0, encoding)) +} + +/// Encode each property, with absolute IDs: an even ID has an integer value, an odd one bytes. +fn encode_list<'a>(w: &mut Encoder<'_>, values: impl IntoIterator) -> Result<(), EncodeError> { + for property in values { + w.varint(property.id)?; + match (&property.value, property.id % 2) { + (Value::Int(value), 0) => w.varint(*value)?, + (Value::Bytes(value), 1) => w.bytes(value)?, + _ => return Err(EncodeError::InvalidState), + } + } + Ok(()) +} + +/// Decode properties to the end of `r`, in the order they arrived. +fn decode_list(r: &mut Decoder<'_>) -> Result, DecodeError> { + let mut values = Vec::new(); + while !r.is_empty() { + let id = r.varint()?; + let value = match id % 2 { + 0 => Value::Int(r.varint()?), + // A small cached property must not pin the reader's larger receive buffer. + _ => Value::Bytes(Bytes::copy_from_slice(r.bytes()?)), + }; + values.push(Property { id, value }); + } + Ok(values) +} + +/// Check the one Immutable Properties block against the encoding the flags declare. +fn immutable<'a>(values: &'a [Property], encoding: Option) -> Result, DecodeError> { + let mut sealed = values.iter().filter(|property| property.id == IMMUTABLE); + let block = match sealed.next().map(|property| &property.value) { + Some(Value::Bytes(bytes)) => Some(bytes), + Some(Value::Int(_)) => unreachable!("odd IDs decode as bytes"), + None => None, + }; + if sealed.next().is_some() || block.is_some() != encoding.is_some() { + return Err(DecodeError::InvalidValue); + } + Ok(block) +} + +/// Encode an object's properties as a block body, empty when it has none. +/// +/// `timestamp` replaces its mutable Timestamp, already in the units the receiver's track +/// declares (see [`crate::ietf::object::egress_time`]). +pub(crate) fn encode_properties( + properties: &Properties, + timestamp: Option, + version: Version, +) -> Result, EncodeError> { + let mut out = Vec::new(); + if timestamp.is_none() && properties.values.is_empty() { + return Ok(out); + } + let w = &mut Encoder::new(&mut out, version.into()); + w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; + let timestamp = timestamp.map(|value| Property { + id: TIMESTAMP, + value: Value::Int(value), + }); + encode_list(w, timestamp.iter().chain(&properties.values))?; + Ok(out) +} + +/// An object's decoded properties and the Prior Object ID Gap they mark, if any. +pub(crate) struct Decoded { + pub properties: Properties, + pub gap: Option, +} + +/// Decode an object's properties block body, whose Timestamps are in `timescale`, the +/// units the track declares. +pub(crate) fn decode_properties( + block: &[u8], + timescale: Option, + version: Version, +) -> Result { + let mut properties = Properties::default(); + if block.is_empty() { + return Ok(Decoded { properties, gap: None }); + } + let r = &mut Decoder::new(block, version.into()); + (properties.delivery_timeout, properties.immutable) = decode_flags(r.varint()?)?; + let mut values = decode_list(r)?; + + let mut timestamps = values.iter().filter(|property| property.id == TIMESTAMP); + properties.timestamp = match timestamps.next() { + Some(Property { + value: Value::Int(value), + .. + }) => Some(*value), + Some(_) => unreachable!("even IDs decode as integers"), + None => None, + }; + if timestamps.next().is_some() { + return Err(DecodeError::Duplicate); + } + values.retain(|property| property.id != TIMESTAMP); + + let mut gaps = values.iter().filter_map(|property| match property { + Property { + id: GAP, + value: Value::Int(gap), + } => Some(*gap), + _ => None, + }); + let mut gap = gaps.next(); + if gaps.next().is_some() { + return Err(DecodeError::Duplicate); + } + if let (Some(block), Some(encoding)) = (immutable(&values, properties.immutable)?, properties.immutable) { + let sealed = crate::ietf::object::sealed(block, encoding).map_err(|_| DecodeError::InvalidValue)?; + properties.sealed_time = sealed.time; + if let Some(sealed) = sealed.gap + && gap.replace(sealed).is_some() + { + return Err(DecodeError::Duplicate); + } + } + properties.values = values; + stamp(&mut properties, timescale); + Ok(Decoded { properties, gap }) +} + +/// Record that `properties` carry their Timestamps in `timescale`, the units the track +/// declares, when they carry any. +pub(crate) fn stamp(properties: &mut Properties, timescale: Option) { + properties.timescale = timescale.filter(|_| properties.timestamp.is_some() || properties.sealed_time); +} + +/// A group stream's object records on egress, sent before each frame of a relayed group. +pub(crate) struct Records { + /// The previous record's Object ID, `None` before the first. + prior: Option, + /// The units the track declares, which mutable Timestamps convert to. + timescale: Option, + version: Version, +} + +impl Records { + /// Buffer the Group State for a stream serving `group` from its current index, and + /// return the records its frames need, `None` for a plain group. + /// + /// `capped` when the stream stops before the group may end. Writes nothing unless + /// the session negotiated the extension. + pub fn start( + writer: &mut Writer, + ietf: bool, + group: &group::Consumer, + capped: bool, + timescale: Option, + version: Version, + ) -> Result, Error> { + if !ietf { + return Ok(None); + } + let wire = group.wire(); + let whole = group.index() <= group.first_frame(); + writer.buffer_varint(encode_state(wire.as_ref(), whole, capped))?; + Ok(wire.map(|_| Self { + prior: None, + timescale, + version, + })) + } + + /// Buffer the record for the frame at `index`, ahead of its timestamp and size. + pub fn frame( + &mut self, + writer: &mut Writer, + index: u64, + fields: Option<&Fields>, + ) -> Result<(), Error> { + self.record(writer, fields.map_or(index, |fields| fields.id), fields, false) + } + + /// Buffer the END_OF_GROUP record once every frame is written, if the group has one. + pub fn end( + &mut self, + writer: &mut Writer, + group: &group::Consumer, + ) -> Result<(), Error> { + // A stream capped short of the last frame stops before the end. + if group.index() < group.frame_count() as u64 { + return Ok(()); + } + match group.end_object() { + Some(end) => self.record(writer, end.id, Some(&end), true), + None => Ok(()), + } + } + + fn record( + &mut self, + writer: &mut Writer, + id: u64, + fields: Option<&Fields>, + end: bool, + ) -> Result<(), Error> { + writer.buffer_varint(encode_object(self.prior, id, end)?)?; + self.prior = Some(id); + let block = match fields { + Some(fields) => { + let timestamp = crate::ietf::object::egress_time(&fields.properties, self.timescale)?; + encode_properties(&fields.properties, timestamp, self.version)? + } + None => Vec::new(), + }; + writer.buffer_varint(block.len() as u64)?; + writer.buffer_raw(&block); + Ok(()) + } +} + +/// The moq-transport Track Properties a relay forwards, sent on the Track Stream right +/// after TRACK_INFO when the extension is negotiated. +#[derive(Clone, Debug, Default)] +pub struct TrackProperties(pub Option>); + +impl Message for TrackProperties { + fn encode_msg(&self, w: &mut Encoder<'_>, _: Version) -> Result<(), EncodeError> { + let Some(properties) = &self.0 else { + w.varint(0)?; + return w.varint(0); + }; + w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; + w.varint(properties.sealed.len() as u64)?; + for id in &properties.sealed { + w.varint(*id)?; + } + encode_list(w, &properties.values) + } + + fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { + let (delivery_timeout, encoding) = decode_flags(r.varint()?)?; + let count = r.varint()?; + // Every ID takes at least a byte, so this bounds the allocation by the message. + if count > r.remaining() as u64 { + return Err(DecodeError::Short); + } + let sealed = (0..count).map(|_| r.varint()).collect::, _>>()?; + let values = decode_list(r)?; + if immutable(&values, encoding)?.is_none() && !sealed.is_empty() { + return Err(DecodeError::InvalidValue); + } + if values.is_empty() { + return Ok(Self(None)); + } + Ok(Self(Some(Arc::new(crate::model::object::TrackProperties { + values, + immutable: encoding, + sealed, + delivery_timeout, + })))) + } +} + +/// Encode a datagram's relay state after its Group Sequence, or a plain one's as 0. +pub(crate) fn encode_datagram( + w: &mut Encoder<'_>, + wire: Option<&crate::model::datagram::Wire>, + version: Version, +) -> Result<(), EncodeError> { + let Some(wire) = wire else { + return w.varint(0); + }; + let mut state = RELAYED; + for (set, bit) in [ + (wire.object_id.is_some(), OBJECT_ID), + (wire.priority.is_some(), PRIORITY), + (wire.end_of_group, DATAGRAM_END), + (wire.status.is_some(), STATUS), + ] { + if set { + state |= bit; + } + } + w.varint(state)?; + if let Some(id) = wire.object_id { + w.varint(id)?; + } + if let Some(priority) = wire.priority { + w.u8(priority); + } + if let Some(status) = wire.status { + w.varint(status)?; + } + w.bytes(&encode_properties(&wire.properties, wire.properties.timestamp, version)?) +} + +/// Decode a datagram's relay state. Its properties' units are the track's, which the +/// caller [`stamp`]s. +pub(crate) fn decode_datagram( + r: &mut Decoder<'_>, + version: Version, +) -> Result, DecodeError> { + let state = r.varint()?; + if state == 0 { + return Ok(None); + } + if state & RELAYED == 0 || state & !(RELAYED | OBJECT_ID | PRIORITY | DATAGRAM_END | STATUS) != 0 { + return Err(DecodeError::InvalidValue); + } + let object_id = (state & OBJECT_ID != 0).then(|| r.varint()).transpose()?; + let priority = (state & PRIORITY != 0).then(|| r.u8()).transpose()?; + let status = (state & STATUS != 0).then(|| r.varint()).transpose()?; + let block = r.bytes()?; + let properties = decode_properties(block, None, version)?.properties; + Ok(Some(crate::model::datagram::Wire { + object_id, + priority, + end_of_group: state & DATAGRAM_END != 0, + status, + properties, + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + const V: Version = Version::Lite07; + + #[test] + fn object_codes_round_trip() { + for (prior, id, end) in [(None, 0, false), (None, 7, true), (Some(3), 4, false), (Some(3), 9, true)] { + let code = encode_object(prior, id, end).unwrap(); + assert_eq!(decode_object(prior, code).unwrap(), (id, end)); + } + // A plain frame after its predecessor costs one byte. + assert_eq!(encode_object(Some(4), 5, false).unwrap(), 0); + assert!(matches!(encode_object(Some(4), 4, false), Err(Error::MalformedTrack))); + assert!(decode_object(Some(u64::MAX), 0).is_err()); + } + + #[test] + fn group_state_round_trips() { + let wire = group::Wire { + sparse: true, + first_object: true, + first_id: 9, + extensions: true, + has_end: true, + fetchable: false, + last: Some(12), + }; + let state = encode_state(Some(&wire), true, false); + let decoded = decode_state(state, 2).unwrap().unwrap(); + assert!(decoded.first_object && decoded.extensions && decoded.has_end); + assert_eq!(decoded.first_id, 2); + assert!(decoded.fetchable && !decoded.sparse); + + let partial = decode_state(encode_state(Some(&wire), false, true), 0).unwrap().unwrap(); + assert!(!partial.first_object && !partial.has_end); + + assert_eq!(encode_state(None, true, false), 0); + assert!(decode_state(0, 0).unwrap().is_none()); + assert!(decode_state(FIRST_OBJECT, 0).is_err(), "state without RELAYED"); + assert!(decode_state(RELAYED | 0x10, 0).is_err(), "unknown bit"); + } + + #[test] + fn properties_round_trip_with_their_provenance() { + // An immutable block in the draft-16 family holding a gap of 2 (0x3e) and a timestamp. + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft16.into()); + for value in [0x10u64, 77, 0x3e - 0x10, 2] { + e.varint(value).unwrap(); + } + let properties = Properties { + timestamp: Some(1_000), + values: vec![ + Property { + id: 0x06, + value: Value::Int(5), + }, + Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }, + ], + immutable: Some(Encoding::DeltaQuic), + timescale: Some(Timescale::MILLI), + sealed_time: true, + delivery_timeout: true, + }; + let block = encode_properties(&properties, properties.timestamp, V).unwrap(); + let decoded = decode_properties(&block, Some(Timescale::MILLI), V).unwrap(); + assert_eq!(decoded.properties, properties); + assert_eq!(decoded.gap, Some(2)); + + // None at all is an empty block. + assert!(encode_properties(&Properties::default(), None, V).unwrap().is_empty()); + let empty = decode_properties(&[], Some(Timescale::MILLI), V).unwrap(); + assert_eq!(empty.properties, Properties::default()); + } + + #[test] + fn properties_refuse_a_mismatched_immutable_encoding() { + let properties = Properties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(Bytes::new()), + }], + ..Default::default() + }; + let block = encode_properties(&properties, None, V).unwrap(); + assert!(decode_properties(&block, None, V).is_err(), "no encoding declared"); + + let declared = Properties { + immutable: Some(Encoding::Absolute), + ..Default::default() + }; + let block = encode_properties(&declared, Some(1), V).unwrap(); + assert!(decode_properties(&block, None, V).is_err(), "encoding without a block"); + } + + #[test] + fn track_properties_round_trip() { + let properties = crate::model::object::TrackProperties { + values: vec![ + Property { + id: 0x41, + value: Value::Bytes(Bytes::from_static(b"opaque")), + }, + Property { + id: IMMUTABLE, + value: Value::Bytes(Bytes::from_static(&[0x02, 0x01])), + }, + ], + immutable: Some(Encoding::Delta { seven: true }), + sealed: vec![0x02], + delivery_timeout: true, + }; + let msg = TrackProperties(Some(Arc::new(properties.clone()))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = >::decode(&mut Decoder::new(&buf, V.into()), V) + .unwrap(); + assert_eq!(decoded.0.as_deref(), Some(&properties)); + + let none = crate::coding::Encode::encode_bytes(&TrackProperties(None), V).unwrap(); + let decoded = + >::decode(&mut Decoder::new(&none, V.into()), V).unwrap(); + assert!(decoded.0.is_none()); + } + + #[test] + fn datagram_state_round_trips() { + let wire = crate::model::datagram::Wire { + object_id: Some(3), + priority: Some(9), + end_of_group: true, + status: Some(3), + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), V).unwrap(); + assert_eq!(decoded, Some(wire)); + + let mut plain = Vec::new(); + encode_datagram(&mut Encoder::new(&mut plain, V.into()), None, V).unwrap(); + assert_eq!(plain, [0]); + assert_eq!(decode_datagram(&mut Decoder::new(&plain, V.into()), V).unwrap(), None); + } +} diff --git a/rs/moq-net/src/lite/mod.rs b/rs/moq-net/src/lite/mod.rs index 656338a4e66..d80b29e8c73 100644 --- a/rs/moq-net/src/lite/mod.rs +++ b/rs/moq-net/src/lite/mod.rs @@ -16,6 +16,7 @@ pub(crate) mod error; mod fetch; mod goaway; mod group; +pub(crate) mod ietf; mod info; pub mod message; mod parameters; diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 0e1ba4f002c..c7e35dc5c74 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1875,10 +1875,11 @@ impl Request for TrackInfoServe { fn poll( &mut self, - _: &Shared, + shared: &Shared, writer: &mut Writer, waiter: &kio::Waiter, ) -> Poll, Error>> { + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let info = ready!(self.querying.poll_ok(waiter))?; // TRACK_INFO only flows on Lite05+ (the encode errors otherwise). @@ -1887,6 +1888,9 @@ impl Request for TrackInfoServe { max_age: info.max_age, timescale: info.timescale, })?; + if ietf { + writer.buffer(&lite::ietf::TrackProperties(info.properties.clone()))?; + } Poll::Ready(Ok(ControlFlow::Break(()))) } } @@ -1973,6 +1977,7 @@ impl Request for SubscribeServe { loop { match self { Self::Confirm { subscribing, .. } => { + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let mut track = ready!(subscribing.poll_ok(waiter))?; let Self::Confirm { msg, latest, update, .. @@ -2030,6 +2035,7 @@ impl Request for SubscribeServe { timescale, runtime: shared.runtime.clone(), outcomes: Default::default(), + ietf, }; let bounds = Bounds::from(msg.as_ref()); @@ -2090,11 +2096,16 @@ enum FetchServe { prev_ts: u64, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, + /// The `ietf` extension's object records, for a relayed group. + records: Option, }, } +/// A batch of frames with their relay metadata, which the `ietf` extension forwards. +type Objects = arrayvec::ArrayVec; + impl Request for FetchServe { const KIND: &'static str = "fetch"; const FETCH: bool = true; @@ -2141,6 +2152,8 @@ impl Request for FetchServe { loop { match self { Self::Fetch { msg, fetching } => { + // Before the group: a fetched group polled while this waited would be lost. + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let mut group = ready!(kio::Task::poll(fetching, waiter))?; // The response carries no header, so a short run is indistinguishable @@ -2157,6 +2170,9 @@ impl Request for FetchServe { // Matches the timescale TRACK_INFO declared for the track. let timescale = shared.version.wire_timescale(group.timescale()); + let capped = msg.end_frame.is_some(); + let records = + lite::ietf::Records::start(writer, ietf, &group, capped, timescale, shared.version)?; *self = Self::Serve { group, @@ -2164,8 +2180,9 @@ impl Request for FetchServe { prev_ts: 0, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, + records, }; } Self::Serve { @@ -2176,6 +2193,7 @@ impl Request for FetchServe { chunk, batch, batch_pos, + records, } => { let mut cx = waiter.context(); loop { @@ -2191,7 +2209,11 @@ impl Request for FetchServe { None => *frame = None, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; + let index = group.index() - batch.len() as u64 + *batch_pos as u64; + let batched = &mut batch[*batch_pos]; + if let Some(records) = records { + records.frame(writer, index, batched.fields.as_deref())?; + } buffer_frame_info( writer, batched.timestamp, @@ -2200,24 +2222,32 @@ impl Request for FetchServe { 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(()))); } - Poll::Ready(Ok(_)) => return Poll::Ready(Ok(ControlFlow::Break(()))), + Poll::Ready(Ok(_)) => { + if let Some(records) = records { + records.end(writer, group)?; + } + return Poll::Ready(Ok(ControlFlow::Break(()))); + } Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => {} } match ready!(group.poll_next_frame(waiter))? { Some(next) => { + if let Some(records) = records { + records.frame(writer, group.index() - 1, next.fields.as_deref())?; + } buffer_frame_info( writer, next.timestamp, @@ -2229,7 +2259,12 @@ impl Request for FetchServe { *frame = Some(next); return Poll::Ready(Ok(ControlFlow::Continue(()))); } - None => return Poll::Ready(Ok(ControlFlow::Break(()))), + None => { + if let Some(records) = records { + records.end(writer, group)?; + } + return Poll::Ready(Ok(ControlFlow::Break(()))); + } } } } @@ -3009,7 +3044,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, } @@ -3048,7 +3083,7 @@ fn poll_recv_next( Poll::Pending => {} } if datagrams { - match track.poll_recv_datagram(waiter)? { + match track.poll_recv_wire_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) => {} @@ -3204,6 +3239,8 @@ struct Subscription { runtime: crate::time::Deadlines, /// Outcomes shared by the subscription and every group it serves. outcomes: Arc, + /// Whether the session negotiated the `ietf` extension, so streams carry relay state. + ietf: bool, } /// Group outcomes the subscription must report even if no header reached the peer. @@ -3223,19 +3260,42 @@ 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 { + // Only the `ietf` extension can say a datagram is a status rather than a payload. + let status = datagram + .wire + .as_ref() + .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); + if status && !self.ietf { + return false; + } let Ok(timestamp) = self .timescale + .filter(|_| !status) .map(|timescale| wire_timestamp(datagram.timestamp, timescale, &self.runtime)) .transpose() else { return false; }; + let ietf = match (self.ietf, &datagram.wire) { + (false, _) => None, + (true, None) => Some(None), + (true, Some(wire)) => { + let mut wire = wire.as_ref().clone(); + let Ok(timestamp) = crate::ietf::object::egress_time(&wire.properties, self.timescale) else { + return false; + }; + wire.properties.timestamp = timestamp; + Some(Some(wire)) + } + }; + let sequence = datagram.sequence; let body = lite::Datagram { subscribe: self.id, - sequence: datagram.sequence, + sequence, timestamp, - payload: datagram.payload, + payload: datagram.datagram.payload, + ietf, }; // 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. @@ -3246,7 +3306,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" @@ -3255,7 +3315,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, @@ -3299,6 +3359,7 @@ impl Subscription { self, sequence, frame_start, + false, Rank::Queue(priority), group, )); @@ -3489,7 +3550,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_wire_datagram(waiter)? { self.serve_datagram(datagram); return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -3602,7 +3663,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); @@ -3715,6 +3776,8 @@ impl TrackRun { fn serve(&mut self, group: group::Consumer) { let sequence = group.sequence; let frame_start = group.index(); + // The stream stops at the end frame, before the group may end. + let capped = self.end_frame.is_some_and(|(end, _)| end == sequence); self.mark_served(sequence); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "serving group"); @@ -3732,7 +3795,7 @@ impl TrackRun { ), }; self.children - .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, rank, group)); + .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, capped, rank, group)); } } @@ -3752,6 +3815,8 @@ struct GroupServe { group: group::Consumer, sequence: u64, frame_start: u64, + /// The stream stops at a subscription's end frame, so its FIN cannot end the group. + capped: bool, // Lite05+ delta-encodes per-frame timestamps within the group. The first // frame's delta is absolute (against an implicit prev value of 0), every // subsequent delta is signed against the previous frame. @@ -3773,8 +3838,10 @@ enum GroupState { writer: Writer, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, + /// The `ietf` extension's object records, for a relayed group. + records: Option, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a /// late cancel or expiry can still reset the stream. @@ -3789,6 +3856,7 @@ impl GroupServe { ctx: Subscription, sequence: u64, frame_start: u64, + capped: bool, rank: Rank>, group: group::Consumer, ) -> Self { @@ -3798,6 +3866,7 @@ impl GroupServe { group, sequence, frame_start, + capped, prev_ts: 0, state: GroupState::Open, budget: kio::coop::Budget::new(32), @@ -3887,21 +3956,36 @@ impl GroupServe { sequence: self.sequence, frame_start: self.frame_start, }; - if let Err(err) = writer.buffer(&lite::DataType::Group).and_then(|()| writer.buffer(&msg)) { - // The header wrote nothing, so the group-stream reset has nothing to pin - // it to this subscription. The run loop reads the slot and resets the - // subscribe stream instead. - self.ctx.note_unencodable(&err); - self.state = GroupState::Done; - writer.abort(&err); - return Poll::Ready(Err(err)); - } + let header = writer.buffer(&lite::DataType::Group).and_then(|()| writer.buffer(&msg)); + let records = header.and_then(|()| { + lite::ietf::Records::start( + &mut writer, + self.ctx.ietf, + &self.group, + self.capped, + self.ctx.timescale, + self.ctx.version, + ) + }); + let records = match records { + Ok(records) => records, + Err(err) => { + // The header wrote nothing, so the group-stream reset has nothing to pin + // it to this subscription. The run loop reads the slot and resets the + // subscribe stream instead. + self.ctx.note_unencodable(&err); + self.state = GroupState::Done; + writer.abort(&err); + return Poll::Ready(Err(err)); + } + }; self.state = GroupState::Serve { writer, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, + records, }; } GroupState::Serve { @@ -3910,6 +3994,7 @@ impl GroupServe { chunk, batch, batch_pos, + records, } => { let mut cx = waiter.context(); @@ -3961,51 +4046,78 @@ impl GroupServe { Poll::Pending => return Poll::Pending, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; - let buffered = buffer_frame_info( - writer, - batched.timestamp, - batched.payload.len() as u64, - self.ctx.timescale, - &mut self.prev_ts, - &self.ctx.runtime, - ); + let index = self.group.index() - batch.len() as u64 + *batch_pos as u64; + let batched = &mut batch[*batch_pos]; + let buffered = records + .as_mut() + .map_or(Ok(()), |records| { + records.frame(writer, index, batched.fields.as_deref()) + }) + .and_then(|()| { + buffer_frame_info( + writer, + batched.timestamp, + batched.payload.len() as u64, + self.ctx.timescale, + &mut self.prev_ts, + &self.ctx.runtime, + ) + }); 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; } - Poll::Ready(Ok(_)) => break 'serve Ok(()), + // Taken, so the next pass finishes once the record flushed. + Poll::Ready(Ok(_)) => match records.take() { + Some(mut records) => match records.end(writer, &self.group) { + Ok(()) => continue, + Err(err) => break 'serve Err(err), + }, + None => break 'serve Ok(()), + }, Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => {} } match self.group.poll_next_frame(waiter) { Poll::Ready(Ok(Some(next))) => { - let buffered = buffer_frame_info( - writer, - next.timestamp, - next.size, - self.ctx.timescale, - &mut self.prev_ts, - &self.ctx.runtime, - ); + let index = self.group.index() - 1; + let buffered = records + .as_mut() + .map_or(Ok(()), |records| records.frame(writer, index, next.fields.as_deref())) + .and_then(|()| { + buffer_frame_info( + writer, + next.timestamp, + next.size, + self.ctx.timescale, + &mut self.prev_ts, + &self.ctx.runtime, + ) + }); if let Err(err) = buffered { break 'serve Err(err); } *frame = Some(next); } - Poll::Ready(Ok(None)) => break 'serve Ok(()), + Poll::Ready(Ok(None)) => match records.take() { + Some(mut records) => match records.end(writer, &self.group) { + Ok(()) => continue, + Err(err) => break 'serve Err(err), + }, + None => break 'serve Ok(()), + }, Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => return Poll::Pending, } @@ -4224,6 +4336,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4269,6 +4382,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4318,6 +4432,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4367,6 +4482,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4434,6 +4550,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4510,6 +4627,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4558,6 +4676,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4605,6 +4724,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4664,6 +4784,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let bounds = Bounds { start_group: Some(0), @@ -5536,6 +5657,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: outcomes.clone(), + ietf: false, }; let bounds = Bounds { start_group: Some(start_group), diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index 25e6e7eb1a0..3e671e20999 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -269,7 +269,7 @@ where // reads the peer's Setup stream; capability-gated streams (PROBE) wait on it. // When the caller already read it (a gated server accept), seed the slot so the // Setup stream isn't expected on the wire again. - let peer_setup_slot = PeerSetup::new(client, session.binding()); + let peer_setup_slot = PeerSetup::new(client, session.binding()).offer_ietf(our_setup.ietf); let early = if let Some(accepted) = peer_setup { peer_setup_slot.set(accepted.setup); accepted.early diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index df7fd821a4d..4d54ba67ad7 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -15,6 +15,8 @@ const PARAM_ROLE: u64 = 0x3; const PARAM_COST: u64 = 0x4; /// Setup Parameter id for the endpoint's Hop ID. const PARAM_HOP: u64 = 0x5; +/// Setup Parameter id offering the `ietf` extension (draft-lcurley-moq-ietf): "IETF" in ASCII. +const PARAM_IETF: u64 = 0x4945_5446; /// The cost of crossing a link that neither end priced. /// @@ -182,6 +184,9 @@ pub struct Setup { /// applies). `None` when the endpoint has no meaningful identity (a /// leaf that never forwards); a wire value of 0 decodes as `None`. pub hop: Option, + /// Whether this endpoint offers the `ietf` extension (lite-07+). Negotiated only when + /// both endpoints offer it. + pub ietf: bool, } impl Message for Setup { @@ -215,6 +220,13 @@ impl Message for Setup { if let Some(hop) = self.hop { params.set_varint(PARAM_HOP, hop.id(), version)?; } + if self.ietf { + // The framing it changes is unpublished, so a published version cannot offer it. + if !version.has_ietf() { + return Err(EncodeError::Version); + } + params.set_bytes(PARAM_IETF, Vec::new()); + } params.encode(w, version) } @@ -256,6 +268,14 @@ impl Message for ReceivedSetup { let hop = params .get_varint(PARAM_HOP, version)? .and_then(|id| crate::Hop::new(id).ok()); + // An older version does not know the parameter, so it ignores it like any other. + let ietf = match params.get_bytes(PARAM_IETF) { + Some(value) if version.has_ietf() => match value.is_empty() { + true => true, + false => return Err(DecodeError::InvalidValue), + }, + _ => false, + }; Ok(Self { role_present: role_code.is_some(), @@ -265,6 +285,7 @@ impl Message for ReceivedSetup { role, cost, hop, + ietf, }, }) } @@ -285,6 +306,8 @@ pub(crate) struct PeerSetup(kio::Shared); struct PeerSetupState { client: bool, binding: crate::transport::Binding, + /// Whether our own SETUP offers the `ietf` extension. + ietf: bool, seen: bool, setup: Option, } @@ -294,6 +317,7 @@ impl PeerSetup { Self(kio::Shared::new(PeerSetupState { client, binding, + ietf: false, seen: false, setup: None, })) @@ -311,6 +335,31 @@ impl PeerSetup { Ok(()) } + /// Note whether our own SETUP offers the `ietf` extension, before any stream depends on it. + pub fn offer_ietf(self, ietf: bool) -> Self { + self.0.lock().ietf = ietf; + self + } + + /// Poll whether the `ietf` extension is negotiated: both SETUPs offer it. + /// + /// Resolves at once when we did not offer it, and otherwise once the peer's SETUP arrives. + pub fn poll_ietf(&self, waiter: &kio::Waiter) -> std::task::Poll { + if !self.0.lock().ietf { + return std::task::Poll::Ready(false); + } + self.poll_get(waiter, |setup| setup.ietf) + } + + /// Whether the `ietf` extension is negotiated, or `None` before the peer's SETUP arrives. + pub fn ietf(&self) -> Option { + let state = self.0.lock(); + match state.ietf { + false => Some(false), + true => state.setup.as_ref().map(|setup| setup.ietf), + } + } + /// Record the peer's SETUP. pub fn set(&self, setup: Setup) { let mut state = self.0.lock(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index c67271c38a0..9511b5b74da 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -504,9 +504,14 @@ impl Subscriber { // is a handful of atomic bumps on every datagram, and a producer held past its // removal would keep the track (its cached groups, its stats subscription) alive. // The group path already writes to a producer under this lock. + // Its framing is unknown until the peer's SETUP says whether the `ietf` extension is + // negotiated, and a best-effort datagram is not worth waiting for. + let Some(ietf) = self.peer_setup.ietf() else { + return Ok(()); + }; 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| { + let dg = lite::Datagram::decode(payload, self.version, ietf, |id| { subscribes.get(&id).is_some_and(|entry| entry.timescale.is_some()) })?; let Some(entry) = subscribes.get_mut(&dg.subscribe) else { @@ -528,7 +533,18 @@ 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)?; + let wire = dg.ietf.flatten().map(|mut wire| { + lite::ietf::stamp(&mut wire.properties, entry.timescale); + Arc::new(wire) + }); + entry.producer.insert_wire_datagram(crate::model::datagram::Stored { + datagram: crate::Datagram { + sequence: dg.sequence, + timestamp, + payload: dg.payload, + }, + wire, + })?; if !live { entry.producer.set_live(Some(Position::group(dg.sequence))); } @@ -864,6 +880,8 @@ impl GroupRecv { loop { match &mut self.state { GroupRecvState::Header => { + // Before the header, which a wait after it would lose. + let ietf = ready!(self.subscriber.peer_setup.poll_ietf(waiter)); let mut cx = waiter.context(); let hdr = ready!(self.reader.poll_decode::(&mut cx))?; @@ -924,7 +942,7 @@ impl GroupRecv { self.state = GroupRecvState::Serve { group: crate::recv::Group::new(group), track, - ingest: FrameIngest::new(&self.subscriber, timescale), + ingest: FrameIngest::new(&self.subscriber, timescale, ietf, hdr.frame_start), shown: false, _reading: reading, }; @@ -1008,9 +1026,33 @@ struct FrameIngest { prev_ts: u64, phase: IngestPhase, budget: frame::Budget, + version: Version, + /// Where the stream's frames start, the first Object ID until a record names it. + frame_start: u64, + /// `Some` for a group relayed under the `ietf` extension: every frame follows an + /// object record. + records: Option, +} + +/// A relayed group's object records on ingest. +#[derive(Default)] +struct RecordIngest { + /// The previous record's Object ID, `None` before the first. + prior: Option, + /// The record of the frame being read: its Object ID, properties, and Prior Object ID Gap. + pending: Option<(u64, crate::model::object::Properties, Option)>, } enum IngestPhase { + /// Reading the `ietf` extension's Group State. + State, + /// Reading a relayed group's next object record. Stream end here means the group + /// has no more objects. + Object, + /// Reading the record's properties block, whose size comes first. + Properties { id: u64, end: bool, size: Option }, + /// The END_OF_GROUP record arrived, so only the stream end may follow. + Ended, /// Reading the timestamp delta (skipped without a timescale). Stream end here /// means the group has no more frames. Timing, @@ -1022,12 +1064,44 @@ enum IngestPhase { } impl FrameIngest { - fn new(subscriber: &Subscriber, timescale: Option) -> Self { + /// `ietf` when the session negotiated the extension, so the stream starts with a Group State. + fn new( + subscriber: &Subscriber, + timescale: Option, + ietf: bool, + frame_start: u64, + ) -> Self { Self { timescale, prev_ts: 0, - phase: IngestPhase::Timing, + phase: match ietf { + true => IngestPhase::State, + false => IngestPhase::Timing, + }, budget: subscriber.frames.clone(), + version: subscriber.version, + frame_start, + records: None, + } + } + + /// The phase that starts the next frame. + fn next_frame(&self) -> IngestPhase { + match self.records { + Some(_) => IngestPhase::Object, + None => IngestPhase::Timing, + } + } + + /// Read a frame header varint. Only a plain group may end in its place. + fn poll_header_varint( + &self, + reader: &mut Reader, + cx: &mut std::task::Context<'_>, + ) -> Poll, Error>> { + match self.records { + Some(_) => reader.poll_varint(cx).map_ok(Some), + None => reader.poll_varint_maybe(cx), } } @@ -1043,13 +1117,72 @@ impl FrameIngest { let mut cx = waiter.context(); loop { match &mut self.phase { + IngestPhase::State => { + let state = ready!(reader.poll_varint(&mut cx))?; + match lite::ietf::decode_state(state, self.frame_start)? { + Some(wire) => { + group.set_wire(wire)?; + self.records = Some(RecordIngest::default()); + self.phase = IngestPhase::Object; + } + None => self.phase = IngestPhase::Timing, + } + } + IngestPhase::Object => { + let Some(code) = ready!(reader.poll_varint_maybe(&mut cx))? else { + return Poll::Ready(Ok(())); + }; + let records = self.records.as_mut().expect("only a relayed group has records"); + let (id, end) = lite::ietf::decode_object(records.prior, code)?; + if records.prior.is_none() + && let Some(mut wire) = group.wire() + { + wire.first_id = id; + group.set_wire(wire)?; + } + records.prior = Some(id); + self.phase = IngestPhase::Properties { id, end, size: None }; + } + IngestPhase::Properties { id, end, size } => { + let len = match size { + Some(len) => *len, + None => { + let len = ready!(reader.poll_varint(&mut cx))?; + if len > lite::ietf::MAX_PROPERTIES as u64 { + return Poll::Ready(Err(Error::BoundsExceeded(crate::coding::BoundsExceeded))); + } + *size.insert(len as usize) + } + }; + let block = ready!(reader.poll_read_exact(&mut cx, len))?; + let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; + let (id, end) = (*id, *end); + if end { + group.mark_gap(id, decoded.gap)?; + group.set_end_object(crate::model::object::Fields { + id, + properties: decoded.properties, + })?; + self.phase = IngestPhase::Ended; + } else { + let records = self.records.as_mut().expect("only a relayed group has records"); + records.pending = Some((id, decoded.properties, decoded.gap)); + self.phase = IngestPhase::Timing; + } + } + IngestPhase::Ended => { + if ready!(reader.poll_has_more(&mut cx))? { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + return Poll::Ready(Ok(())); + } IngestPhase::Timing => { let Some(scale) = self.timescale else { self.phase = IngestPhase::Size { timestamp: None }; continue; }; // The timestamp delta doubles as the per-frame sentinel. - let Some(zz) = ready!(reader.poll_varint_maybe(&mut cx))? else { + let Some(zz) = ready!(self.poll_header_varint(reader, &mut cx))? else { return Poll::Ready(Ok(())); }; let next: u64 = (self.prev_ts as i128 + crate::coding::varint::unzigzag(zz) as i128) @@ -1063,17 +1196,29 @@ impl FrameIngest { }; } IngestPhase::Size { timestamp } => { - let Some(size) = ready!(reader.poll_varint_maybe(&mut cx))? else { + let timestamp = *timestamp; + let Some(size) = ready!(self.poll_header_varint(reader, &mut cx))? else { return Poll::Ready(Ok(())); }; + // A frame that says nothing a plain frame would not keeps no fields. + let fields = match self.records.as_mut().and_then(|records| records.pending.take()) { + Some((id, properties, gap)) => { + group.mark_gap(id, gap)?; + let plain = id == group.frame_count() as u64 + && properties.is_plain() + && properties.timestamp == timestamp.map(|time| time.value()); + (!plain).then(|| Arc::new(crate::model::object::Fields { id, properties })) + } + None => None, + }; // `create_frame_owned` is the allocation chokepoint: it rejects an // 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. let frame = group.create_frame_owned( - frame::Info { - size, - timestamp: *timestamp, + frame::Header { + info: frame::Info { size, timestamp }, + fields, }, &self.budget, )?; @@ -1082,7 +1227,8 @@ impl FrameIngest { IngestPhase::Payload { frame } => { let failed = ready!(reader.poll_read_frame(&mut cx, frame)).err(); - let IngestPhase::Payload { frame } = std::mem::replace(&mut self.phase, IngestPhase::Timing) else { + let next = self.next_frame(); + let IngestPhase::Payload { frame } = std::mem::replace(&mut self.phase, next) else { unreachable!() }; match failed { @@ -2670,6 +2816,7 @@ mod tests { sequence, timestamp: Some(sequence), payload: bytes::Bytes::from_static(b"x"), + ietf: None, } .encode_bytes(VERSION) .unwrap() @@ -5681,6 +5828,8 @@ enum TrackInfoState { Open, Send { stream: Stream }, Read { stream: Stream }, + /// Reading the TRACK_PROPERTIES the `ietf` extension sends after TRACK_INFO. + Properties { stream: Stream, info: track::Info }, } impl TrackInfoFetch { @@ -5732,6 +5881,7 @@ impl TrackInfoFetch { if let Poll::Ready(err) = self.closed.poll_closed(&mut cx) { return Poll::Ready(Err(crate::lite::error::from_transport(err))); } + let ietf = ready!(serve.subscriber.peer_setup.poll_ietf(waiter)); let info = ready!(stream.reader.poll_decode::(&mut cx))?; let TrackInfoState::Read { stream } = std::mem::replace(&mut self.state, TrackInfoState::Open) else { @@ -5746,7 +5896,23 @@ impl TrackInfoFetch { .with_timescale(info.timescale) .with_max_age(info.max_age) .with_priority(info.priority); - return Poll::Ready(Ok((model, HeldTrack(stream)))); + if !ietf { + return Poll::Ready(Ok((model, HeldTrack(stream)))); + } + self.state = TrackInfoState::Properties { stream, info: model }; + } + TrackInfoState::Properties { stream, .. } => { + if let Poll::Ready(err) = self.closed.poll_closed(&mut cx) { + return Poll::Ready(Err(crate::lite::error::from_transport(err))); + } + let properties = ready!(stream.reader.poll_decode::(&mut cx))?; + let TrackInfoState::Properties { stream, mut info } = + std::mem::replace(&mut self.state, TrackInfoState::Open) + else { + unreachable!() + }; + info.properties = properties.0; + return Poll::Ready(Ok((info, HeldTrack(stream)))); } } } @@ -6511,6 +6677,7 @@ impl kio::Task for FetchServeRun { }; } FetchRunState::Answer { stream, .. } => { + let ietf = ready!(self.serve.subscriber.peer_setup.poll_ietf(waiter)); // Lite has no FETCH_OK: a publisher without the group resets the // stream instead. Accepting before the first byte (or a FIN, for an // empty group) would resolve every joined `fetch_group` to a group @@ -6562,7 +6729,7 @@ impl kio::Task for FetchServeRun { stream, producer, joined, - ingest: Box::new(FrameIngest::new(&self.serve.subscriber, self.timescale)), + ingest: Box::new(FrameIngest::new(&self.serve.subscriber, self.timescale, ietf, frame_start)), }; } FetchRunState::Ingest { diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 1aab80781be..a7ac647c1ab 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -273,6 +273,18 @@ impl Version { } } + /// Whether a session may negotiate the `ietf` extension (draft-lcurley-moq-ietf), which + /// carries moq-transport object state between relays. Added on lite-07; published + /// versions get no framing changes. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_ietf(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 announce stream has ANNOUNCE_RESTART: another publisher instance /// replacing an advertisement in place. Added in lite-07. Older versions send an /// ANNOUNCE_END then an ANNOUNCE_START. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c8858d0b38c..64814343650 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -6858,12 +6858,13 @@ mod test { sequence: d.sequence, timestamp: Some(d.timestamp.unwrap().value()), payload: d.payload.clone(), + ietf: 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, false, |_| true).unwrap(); let mut downstream = track_producer("test", Info::timed()); let mut downstream_dg = downstream.subscribe(None); downstream diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index d338b256de5..27f5c9fc705 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -121,7 +121,8 @@ impl Server { self } - /// Choose which moq-transport extensions to offer in SETUP. Defaults to all of them. + /// Choose which extensions to offer in SETUP. Defaults to every moq-transport one, and + /// not [`ietf`](setup::Extensions::ietf), which only relays turn on. pub fn with_extensions(mut self, extensions: setup::Extensions) -> Self { self.extensions = extensions; self @@ -167,6 +168,7 @@ impl Server { cost: None, // Filled by `lite::start` from the attached origin handles. hop: None, + ietf: self.extensions.ietf && version.has_ietf(), } } else { lite::Setup::default() @@ -1184,6 +1186,7 @@ mod tests { role, cost: None, hop, + ietf: false, } .encode(&mut crate::coding::Encoder::new(&mut buf, v.into()), v) .unwrap(); diff --git a/rs/moq-net/src/setup.rs b/rs/moq-net/src/setup.rs index cb33a75f0b5..1e8eb5dcfd9 100644 --- a/rs/moq-net/src/setup.rs +++ b/rs/moq-net/src/setup.rs @@ -25,10 +25,10 @@ const SERVER_SETUP: u8 = 0x21; #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(crate) const SETUP_V17: u64 = 0x2F00; -/// The moq-transport Setup Options this side offers, each on by default. +/// The SETUP extensions this side offers. /// /// Turning one off connects as a peer that does not speak that extension. moq-lite carries -/// them in its core, so this only changes moq-transport sessions. +/// auth, solicit, and epoch in its core, so those only change moq-transport sessions. #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[serde(default, deny_unknown_fields)] #[non_exhaustive] @@ -41,6 +41,9 @@ pub struct Extensions { /// The MoQ Epoch extension: announcements and requests carry the publisher's /// [`Epoch`](crate::Epoch), as moq-lite 07 does (draft-17+). pub epoch: bool, + /// The MoQ IETF extension, off by default: a moq-lite 07 hop between relays carries the + /// moq-transport object state a relay preserves, such as Object IDs and properties. + pub ietf: bool, } impl Default for Extensions { @@ -49,6 +52,7 @@ impl Default for Extensions { auth: true, solicit: true, epoch: true, + ietf: false, } } } diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 0911b3be94a..52aa0ddf4ae 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"), + ietf: 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"), + ietf: None, } .encode_bytes(version); let untimed_datagram = match untimed { From 5027bc93324bca1504803c75fc00e333f58fdfc7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:27:10 -0700 Subject: [PATCH 03/25] wip(lite): ietf extension carries moq-transport state across lite-07 Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/publisher.rs | 6 +- rs/moq-net/src/ietf/subscriber.rs | 68 +++++++- rs/moq-net/src/lite/ietf.rs | 272 +++++++++++++++++++++++++++++- rs/moq-net/src/lite/publisher.rs | 4 +- rs/moq-net/src/lite/setup.rs | 27 +++ rs/moq-net/src/lite/subscriber.rs | 140 +++++++++++++-- rs/moq-relay/src/relay.rs | 4 + rs/moq-tokio/src/connect.rs | 4 +- rs/moq-tokio/src/listen.rs | 2 +- 9 files changed, 490 insertions(+), 37 deletions(-) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index c61417cff5e..e1d31420dd4 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -184,10 +184,12 @@ async fn read_fetch( } // Relayed Object IDs need not match frame ordinals, so a relayed group is read from // its first frame and filtered by ID. Its marked gaps cover the IDs between where it - // starts and its first object; a start below that misses to the upstream. + // starts and its first object; a start below that misses to the upstream. A miss may + // be relayed too, which only the upstream knows, so it fetches the whole group. let frame_start = match (&wire, &cached) { (Some(_), Some(group)) => skip.min(group.first_frame()), - _ => skip, + (None, Some(_)) => skip, + (_, None) => 0, }; let mut group = track .fetch_group( diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index c9c69322147..b319b5d6b18 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -12162,12 +12162,49 @@ mod stitch_tests { /// Relay `script` through a track the ingress times in `timescale`, which the cache /// normalizes to microseconds like [`accepted_info`]. + /// + /// Also relays it through a second relay behind a moq-lite hop with the `ietf` + /// extension, which must not change a byte. async fn relay_passthrough_timed( script: Vec, ingress: Version, egress: Version, fetch: Option<(u64, u64)>, timescale: Option, + ) -> (Vec, crate::lite::test_transport::Log) { + let direct = relay_passthrough_via(script.clone(), ingress, egress, fetch, timescale, false).await; + let hopped = relay_passthrough_via(script, ingress, egress, fetch, timescale, true).await; + let fetch_ok = |bytes: &[u8]| { + let mut decoder = Decoder::new(bytes, egress.into()); + (decoder.varint().ok()? == ietf::FetchOk::ID).then_some(())?; + let ok = ietf::FetchOk::decode(&mut decoder, egress).ok()?; + Some((ok, bytes[bytes.len() - decoder.remaining()..].to_vec())) + }; + match (fetch_ok(&direct.0), fetch_ok(&hopped.0)) { + // A moq-lite FETCH says nothing of the track, so only a subscription tells the + // second relay that the track ended. Everything else must match. + (Some((direct_ok, direct_rest)), Some((hopped_ok, hopped_rest))) + if direct_ok.end_of_track && !hopped_ok.end_of_track => + { + assert_eq!(hopped_ok.properties, direct_ok.properties, "{ingress} -> {egress}"); + assert_eq!(hopped_rest, direct_rest, "{ingress} -> {egress}: the hop changed the objects"); + } + _ => assert_eq!( + hopped.0, direct.0, + "{ingress} -> {egress}: the moq-lite hop changed the relayed objects" + ), + } + direct + } + + /// [`relay_passthrough_timed`] through one relay, or two joined by a moq-lite `hop`. + async fn relay_passthrough_via( + script: Vec, + ingress: Version, + egress: Version, + fetch: Option<(u64, u64)>, + timescale: Option, + hop: bool, ) -> (Vec, crate::lite::test_transport::Log) { use crate::lite::test_transport::Sent; let origin = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); @@ -12187,6 +12224,13 @@ mod stitch_tests { let mut stream = h.stream().await.with_version(ingress); h.subscriber.clone().recv_group(&mut stream).await.unwrap(); track.finish().unwrap(); + let (served, _sessions) = match hop { + true => { + let (served, sessions) = crate::lite::ietf::test_hop(&origin, "room", [true, true]).await; + (served, Some(sessions)) + } + false => (origin, None), + }; let mut downstream = ScriptedSession::per_stream(vec![vec![]]); let peer = peer::PeerSetup::default(); @@ -12194,7 +12238,7 @@ mod stitch_tests { let publisher = crate::ietf::Publisher::new( crate::time::sim(), downstream.clone(), - origin.consume(), + served.consume(), Control::new(None, false), None, peer, @@ -12732,10 +12776,13 @@ mod stitch_tests { #[moq_clock::test] async fn passthrough_preserves_datagram_objects_through_dispatch() { - for version in [Version::Draft15, Version::Draft22] { - for ranged in [false, true] - .into_iter() - .filter(|ranged| !*ranged || version == Version::Draft22) + // Also through a second relay behind a moq-lite hop with the `ietf` extension. + for (version, ranged, hop) in [Version::Draft15, Version::Draft22] + .into_iter() + .flat_map(|version| [(version, false), (version, true)]) + .filter(|(version, ranged)| !*ranged || *version == Version::Draft22) + .flat_map(|(version, ranged)| [(version, ranged, false), (version, ranged, true)]) + { { let origin = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); let broadcast = origin.publish("room", crate::origin::Route::default()).unwrap(); @@ -12771,13 +12818,20 @@ mod stitch_tests { original.push(datagram); } track.finish().unwrap(); + let (served, _sessions) = match hop { + true => { + let (served, sessions) = crate::lite::ietf::test_hop(&origin, "room", [true, true]).await; + (served, Some(sessions)) + } + false => (origin, None), + }; let mut downstream = ScriptedSession::per_stream(vec![vec![]]).with_datagrams(65535); let peer = peer::PeerSetup::default(); peer.set(peer::Peer::default()); let publisher = crate::ietf::Publisher::new( crate::time::sim(), downstream.clone(), - origin.consume(), + served.consume(), Control::new(None, false), None, peer, @@ -12824,7 +12878,7 @@ mod stitch_tests { .await; let sent = downstream.log.datagrams.lock().unwrap(); original.retain(|datagram| !ranged || datagram.object_id == Some(7)); - assert_eq!(sent.len(), original.len()); + assert_eq!(sent.len(), original.len(), "{version} ranged={ranged} hop={hop}"); let inherited = super::super::priority::to_wire(track.publisher_priority()); for (bytes, mut expected) in sent.iter().zip(original) { expected.track_alias = 3; diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index a8bf9f45878..531dd7dcf29 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -265,7 +265,8 @@ pub(crate) fn stamp(properties: &mut Properties, timescale: Option) { properties.timescale = timescale.filter(|_| properties.timestamp.is_some() || properties.sealed_time); } -/// A group stream's object records on egress, sent before each frame of a relayed group. +/// A group stream's object records on egress, sent before each frame once the extension +/// is negotiated. pub(crate) struct Records { /// The previous record's Object ID, `None` before the first. prior: Option, @@ -276,10 +277,10 @@ pub(crate) struct Records { impl Records { /// Buffer the Group State for a stream serving `group` from its current index, and - /// return the records its frames need, `None` for a plain group. + /// return the records its frames need. /// - /// `capped` when the stream stops before the group may end. Writes nothing unless - /// the session negotiated the extension. + /// `capped` when the stream stops before the group may end. Writes nothing and returns + /// `None` unless the session negotiated the extension. pub fn start( writer: &mut Writer, ietf: bool, @@ -294,7 +295,7 @@ impl Records { let wire = group.wire(); let whole = group.index() <= group.first_frame(); writer.buffer_varint(encode_state(wire.as_ref(), whole, capped))?; - Ok(wire.map(|_| Self { + Ok(Some(Self { prior: None, timescale, version, @@ -601,3 +602,264 @@ mod tests { assert_eq!(decode_datagram(&mut Decoder::new(&plain, V.into()), V).unwrap(), None); } } + +/// Peer a relay behind `upstream` over moq-lite 07, the way a cluster does. The client +/// (downstream) and server (upstream) each offer the `ietf` extension per `offer`. +/// Returns the downstream origin once it learned of `broadcast`, and the sessions to hold. +#[cfg(test)] +pub(crate) async fn test_hop( + upstream: &crate::origin::Producer, + broadcast: &str, + offer: [bool; 2], +) -> (crate::origin::Producer, [crate::Session; 2]) { + use crate::model::ProduceTest; + let version = crate::Version::Lite(Version::Lite07); + let downstream = crate::origin::Config::new(crate::Hop::new(3).unwrap()).produce(); + let (client, server) = crate::transport::memory::pair(crate::transport::memory::Config { + protocol: Some(version.alpn().to_string()), + ..Default::default() + }); + let extensions = |ietf| { + let mut extensions = crate::setup::Extensions::default(); + extensions.ietf = ietf; + extensions + }; + let dial = crate::Client::new() + .with_versions(version.into()) + .with_extensions(extensions(offer[0])) + .with_subscriber(downstream.clone()); + let serve = crate::Server::new() + .with_versions(version.into()) + .with_extensions(extensions(offer[1])) + .with_publisher(&upstream.consume()); + let (client, server) = futures::join!( + async { + let (session, driver) = dial.connect(moq_clock::now(), client).await.unwrap(); + drop(moq_clock::sim::spawn(crate::time::run(driver))); + session + }, + async { + let (session, driver) = serve.accept(moq_clock::now(), server).await.unwrap(); + drop(moq_clock::sim::spawn(crate::time::run(driver))); + session + }, + ); + downstream + .consume() + .routed(broadcast) + .await + .expect("the hop announced the broadcast"); + (downstream, [client, server]) +} + +#[cfg(test)] +mod hop_tests { + use super::*; + use crate::{Timestamp, frame, model::ProduceTest, track}; + use std::time::Duration; + + const TIMEOUT: Duration = Duration::from_secs(5); + + fn ts(millis: u64) -> Timestamp { + Timestamp::new(millis, Timescale::MILLI).unwrap() + } + + fn property(id: u64, value: u64) -> Property { + Property { + id, + value: Value::Int(value), + } + } + + /// Write a frame carrying relay `fields`, as moq-transport ingress does. + fn write(group: &mut group::Producer, millis: u64, fields: Option, payload: &[u8]) { + let mut frame = group + .create_frame_owned( + frame::Header { + info: frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(millis)), + }, + fields: fields.map(Arc::new), + }, + &frame::Budget::default(), + ) + .unwrap(); + frame.write(Bytes::copy_from_slice(payload)).unwrap(); + frame.finish().unwrap(); + } + + /// A frame's Object ID and properties, when it keeps any. + fn fields(frame: &frame::Object) -> Option<(u64, Properties)> { + frame.fields.as_ref().map(|fields| (fields.id, fields.properties.clone())) + } + + async fn next(group: &mut group::Consumer) -> Option { + moq_clock::timeout(TIMEOUT, kio::wait(|waiter| group.poll_read_object(waiter))) + .await + .expect("no frame") + .unwrap() + } + + async fn subscribe(origin: &crate::origin::Producer) -> (track::Consumer, track::Subscriber) { + let broadcast = moq_clock::timeout(TIMEOUT, origin.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + let track = broadcast.track("video").unwrap(); + let subscriber = moq_clock::timeout(TIMEOUT, track.subscribe(None)) + .await + .expect("no subscription") + .unwrap(); + (track, subscriber) + } + + async fn recv(subscriber: &mut track::Subscriber) -> group::Consumer { + moq_clock::timeout(TIMEOUT, subscriber.recv_group()) + .await + .expect("no group") + .unwrap() + .expect("track finished") + } + + /// A relayed group crosses the hop frame by frame while it is still open, with its + /// Object IDs, properties, and END_OF_GROUP position, and its track's properties. + /// A side that does not offer the extension gets the plain frames alone. + #[moq_clock::test] + async fn relayed_state_crosses_while_the_group_is_open() { + for offer in [[true, true], [true, false], [false, true]] { + let negotiated = offer == [true, true]; + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + let track_properties = crate::model::object::TrackProperties { + values: vec![property(0x40, 3)], + ..Default::default() + }; + info.properties = Some(Arc::new(track_properties.clone())); + let track = broadcast.create_track("video", info).unwrap(); + + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group + .set_wire(group::Wire { + sparse: false, + first_object: true, + first_id: 6, + extensions: true, + has_end: true, + fetchable: true, + last: None, + }) + .unwrap(); + let first = crate::model::object::Fields { + id: 6, + properties: Properties { + timestamp: Some(0), + values: vec![property(0x20, 1), property(GAP, 6)], + timescale: Some(Timescale::MILLI), + ..Default::default() + }, + }; + group.mark_gap(6, Some(6)).unwrap(); + write(&mut group, 0, Some(first.clone()), b"a"); + + let (downstream, _sessions) = test_hop(&upstream, "room", offer).await; + let (copy, mut subscriber) = subscribe(&downstream).await; + let mut received = recv(&mut subscriber).await; + + // The upstream group is still open. + let frame = next(&mut received).await.unwrap(); + assert_eq!(&frame.payload[..], b"a"); + assert_eq!(frame.timestamp, Some(ts(0))); + match negotiated { + true => { + assert_eq!(fields(&frame), Some((first.id, first.properties.clone())), "{offer:?}"); + let wire = received.wire().expect("relay state"); + assert!(wire.first_object && wire.extensions && wire.has_end); + assert_eq!(wire.first_id, 6); + } + false => { + assert!(frame.fields.is_none(), "{offer:?}"); + assert!(received.wire().is_none(), "{offer:?}"); + } + } + + // Object 9 marks the two it skipped, then the group ends at Object 10. + let second = crate::model::object::Fields { + id: 9, + properties: Properties { + timestamp: Some(1), + values: vec![property(GAP, 2)], + timescale: Some(Timescale::MILLI), + ..Default::default() + }, + }; + group.mark_gap(9, Some(2)).unwrap(); + write(&mut group, 1, Some(second.clone()), b"b"); + group.mark_gap(10, None).unwrap(); + group + .set_end_object(crate::model::object::Fields { + id: 10, + properties: Properties::default(), + }) + .unwrap(); + group.finish().unwrap(); + + let frame = next(&mut received).await.unwrap(); + assert_eq!(&frame.payload[..], b"b"); + assert!(next(&mut received).await.is_none()); + let info = moq_clock::timeout(TIMEOUT, copy.query()).await.unwrap().unwrap(); + match negotiated { + true => { + assert_eq!(fields(&frame), Some((second.id, second.properties.clone()))); + assert_eq!(received.end_object().map(|end| end.id), Some(10)); + assert!(received.wire().unwrap().fetchable, "every jump was marked"); + assert_eq!(info.properties.as_deref(), Some(&track_properties)); + } + false => { + assert!(frame.fields.is_none()); + assert!(received.end_object().is_none()); + assert!(info.properties.is_none()); + } + } + } + } + + /// Groups and datagrams from a moq-lite publisher cross a negotiated hop as plain as + /// they left: no relay state appears on the way. + #[moq_clock::test] + async fn plain_media_crosses_unchanged() { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut track = broadcast + .create_track("video", track::Info::timed().with_timescale(Timescale::MILLI)) + .unwrap(); + let (downstream, sessions) = test_hop(&upstream, "room", [true, true]).await; + let (_copy, mut subscriber) = subscribe(&downstream).await; + + let mut group = track.append_group().unwrap(); + group.write_frame(ts(5), b"key".to_vec()).unwrap(); + let mut received = recv(&mut subscriber).await; + let frame = next(&mut received).await.unwrap(); + assert_eq!((frame.timestamp, &frame.payload[..]), (Some(ts(5)), &b"key"[..])); + assert!(frame.fields.is_none() && received.wire().is_none()); + group.write_frame(ts(6), b"delta".to_vec()).unwrap(); + group.finish().unwrap(); + let frame = next(&mut received).await.unwrap(); + assert_eq!((frame.timestamp, &frame.payload[..]), (Some(ts(6)), &b"delta"[..])); + assert!(frame.fields.is_none()); + assert!(next(&mut received).await.is_none()); + assert!(received.end_object().is_none()); + + track.insert_datagram(7, ts(9), b"datagram".to_vec()).unwrap(); + let datagram = moq_clock::timeout(TIMEOUT, kio::wait(|waiter| subscriber.poll_recv_wire_datagram(waiter))) + .await + .expect("no datagram") + .unwrap() + .unwrap(); + assert_eq!((datagram.sequence, datagram.timestamp), (7, Some(ts(9)))); + assert_eq!(&datagram.payload[..], b"datagram"); + assert!(datagram.wire.is_none()); + drop(sessions); + } +} diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index c7e35dc5c74..59e7769fa6c 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2098,7 +2098,7 @@ enum FetchServe { chunk: Option, batch: Box, batch_pos: usize, - /// The `ietf` extension's object records, for a relayed group. + /// The `ietf` extension's object records, when negotiated. records: Option, }, } @@ -3840,7 +3840,7 @@ enum GroupState { chunk: Option, batch: Box, batch_pos: usize, - /// The `ietf` extension's object records, for a relayed group. + /// The `ietf` extension's object records, when negotiated. records: Option, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 4d54ba67ad7..52254dd4360 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -504,6 +504,33 @@ mod tests { } } + /// The `ietf` offer is an empty parameter that only a version with the extension sends, + /// and an older one ignores like any unknown parameter. + #[test] + fn ietf_offer_is_lite07_only() { + let msg = Setup { + ietf: true, + ..Default::default() + }; + let buf = msg.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(Setup::decode_slice(&buf, Version::Lite07).unwrap().0, msg); + assert!(msg.encode_bytes(Version::Lite06).is_err()); + + // Length, one parameter, its 8-byte QUIC varint ID, and an empty value. + let older = [0x0a, 0x01, 0xc0, 0, 0, 0, 0x49, 0x45, 0x54, 0x46, 0x00]; + assert_eq!( + Setup::decode_slice(&older, Version::Lite06).unwrap().0, + Setup::default() + ); + + // A value it does not define is refused. + let mut valued = buf.to_vec(); + assert_eq!(valued.pop(), Some(0), "the offer ends in its empty value"); + valued.extend([1, 7]); + valued[0] += 1; + assert!(Setup::decode_slice(&valued, Version::Lite07).is_err()); + } + /// Never emit a SETUP our own receiver would refuse. #[test] fn encode_enforces_the_setup_limit() { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 9511b5b74da..d066fbce32e 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1029,14 +1029,16 @@ struct FrameIngest { version: Version, /// Where the stream's frames start, the first Object ID until a record names it. frame_start: u64, - /// `Some` for a group relayed under the `ietf` extension: every frame follows an + /// `Some` once the Group State of the `ietf` extension arrived: every frame follows an /// object record. records: Option, } -/// A relayed group's object records on ingest. -#[derive(Default)] +/// A group's object records on ingest, under the `ietf` extension. struct RecordIngest { + /// The Group State carried relay state. Otherwise every record is plain: its Object ID + /// is the frame's index, with no properties and no END_OF_GROUP. + relayed: bool, /// The previous record's Object ID, `None` before the first. prior: Option, /// The record of the frame being read: its Object ID, properties, and Prior Object ID Gap. @@ -1046,8 +1048,7 @@ struct RecordIngest { enum IngestPhase { /// Reading the `ietf` extension's Group State. State, - /// Reading a relayed group's next object record. Stream end here means the group - /// has no more objects. + /// Reading the next object record. Stream end here means the group has no more objects. Object, /// Reading the record's properties block, whose size comes first. Properties { id: u64, end: bool, size: Option }, @@ -1119,20 +1120,23 @@ impl FrameIngest { match &mut self.phase { IngestPhase::State => { let state = ready!(reader.poll_varint(&mut cx))?; - match lite::ietf::decode_state(state, self.frame_start)? { - Some(wire) => { - group.set_wire(wire)?; - self.records = Some(RecordIngest::default()); - self.phase = IngestPhase::Object; - } - None => self.phase = IngestPhase::Timing, + let wire = lite::ietf::decode_state(state, self.frame_start)?; + let relayed = wire.is_some(); + if let Some(wire) = wire { + group.set_wire(wire)?; } + self.records = Some(RecordIngest { + relayed, + prior: None, + pending: None, + }); + self.phase = IngestPhase::Object; } IngestPhase::Object => { let Some(code) = ready!(reader.poll_varint_maybe(&mut cx))? else { return Poll::Ready(Ok(())); }; - let records = self.records.as_mut().expect("only a relayed group has records"); + let records = self.records.as_mut().expect("the Group State came first"); let (id, end) = lite::ietf::decode_object(records.prior, code)?; if records.prior.is_none() && let Some(mut wire) = group.wire() @@ -1155,8 +1159,12 @@ impl FrameIngest { } }; let block = ready!(reader.poll_read_exact(&mut cx, len))?; - let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; let (id, end) = (*id, *end); + let records = self.records.as_mut().expect("the Group State came first"); + if !records.relayed && (end || !block.is_empty()) { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; if end { group.mark_gap(id, decoded.gap)?; group.set_end_object(crate::model::object::Fields { @@ -1165,7 +1173,6 @@ impl FrameIngest { })?; self.phase = IngestPhase::Ended; } else { - let records = self.records.as_mut().expect("only a relayed group has records"); records.pending = Some((id, decoded.properties, decoded.gap)); self.phase = IngestPhase::Timing; } @@ -1201,12 +1208,19 @@ impl FrameIngest { return Poll::Ready(Ok(())); }; // A frame that says nothing a plain frame would not keeps no fields. - let fields = match self.records.as_mut().and_then(|records| records.pending.take()) { - Some((id, properties, gap)) => { + let fields = match &mut self.records { + Some(records) => { + let (id, properties, gap) = records.pending.take().expect("a record precedes each frame"); group.mark_gap(id, gap)?; + // The frame header already carries the time, so a record may omit it. let plain = id == group.frame_count() as u64 && properties.is_plain() - && properties.timestamp == timestamp.map(|time| time.value()); + && properties + .timestamp + .is_none_or(|time| Some(time) == timestamp.map(|time| time.value())); + if !plain && !records.relayed { + return Poll::Ready(Err(Error::ProtocolViolation)); + } (!plain).then(|| Arc::new(crate::model::object::Fields { id, properties })) } None => None, @@ -2411,6 +2425,96 @@ mod tests { } } + /// Receive group 0 of an untimed track over a lite-07 session that negotiated the + /// `ietf` extension, its stream holding `body` after the GROUP header. + async fn receive_ietf(body: &[u64]) -> (Result<(), Error>, track::Producer) { + use crate::transport::poll::Session as _; + + let version = Version::Lite07; + let mut script = Vec::new(); + let mut encoder = crate::coding::Encoder::new(&mut script, version.into()); + lite::Group { + subscribe: 7, + sequence: 0, + frame_start: 0, + } + .encode(&mut encoder, version) + .unwrap(); + for value in body { + encoder.varint(*value).unwrap(); + } + let mut session = crate::lite::test_transport::ScriptedSession::eof(script); + let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Binding::InBand).offer_ietf(true); + peer_setup.set(lite::Setup { + ietf: true, + ..Default::default() + }); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::sim(), + session: session.clone(), + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup, + peer_hop: None, + cost: None, + going_away: Default::default(), + auth: crate::auth::Handle::new(false), + }); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + crate::track::Info::default().with_timescale(None), + ); + subscriber.subscribes.lock().insert( + 7, + TrackEntry { + producer: track.clone(), + timescale: None, + tail: Default::default(), + }, + ); + + let (_, recv) = session.open_bi(Default::default()).await.unwrap(); + let mut group = GroupRecv::new(subscriber, Reader::new(recv, version)); + let res = kio::wait(|waiter| group.poll_serve(waiter)).await; + (res, track) + } + + /// Object records: `(Skip << 1) | END`, the properties block's length, then the frame. + #[moq_clock::test] + async fn ietf_records_frame_a_group() { + // A plain group: Group State 0, then frame 0 with an empty record. + let (res, track) = receive_ietf(&[0, 0, 0, 1, u64::from(b'x')]).await; + res.unwrap(); + let mut group = track.consume().peek_group(0).unwrap(); + assert_eq!(group.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, b"x"[..]); + + // A relayed group starting at Object 4, then END_OF_GROUP at Object 6. + let (res, track) = receive_ietf(&[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; + res.unwrap(); + let group = track.consume().peek_group(0).unwrap(); + assert_eq!(group.end_object().map(|end| end.id), Some(6)); + assert_eq!(group.wire().map(|wire| wire.first_id), Some(4)); + } + + /// A record the Group State does not allow, or bytes past END_OF_GROUP, are refused. + #[moq_clock::test] + async fn ietf_records_refuse_what_their_group_cannot_hold() { + for (body, reason) in [ + (&[0x20][..], "an unknown Group State bit"), + (&[0x2][..], "relay state without RELAYED"), + (&[0, 1 << 1, 0, 1, 0], "a plain group skipping an Object ID"), + (&[0, 1, 0], "a plain group with END_OF_GROUP"), + (&[0, 0, 2, 0x10, 0], "a plain group with properties"), + (&[0x1, 1, 0, 0], "a byte after END_OF_GROUP"), + (&[0x1, 0, 0], "a stream ending inside a frame"), + ] { + let (res, _) = receive_ietf(body).await; + assert!(res.is_err(), "accepted {reason}"); + } + } + /// Receive group 5 starting at 500ms over `version`, on a received timed track whose /// group 4 starts at 1000ms, returning the stream's result and the track. async fn receive_rewind(version: Version) -> (Result<(), Error>, track::Producer) { diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index d65e405fb3c..34e2674b852 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -123,6 +123,10 @@ impl Relay { async fn load_inner(mut config: Config) -> anyhow::Result { config.resolve()?; + // A relay keeps the moq-transport object state it forwards across a moq-lite hop to + // another relay. Only negotiated when both sides offer it, so other peers never see it. + config.listen.extensions.ietf = true; + config.connect.extensions.ietf = true; // Every TLS listener serves the ACME certificate, so install it before any is built. let acme = config.acme.init(&config.listen.tls, &config.web.https)?; if let Some(acme) = &acme { diff --git a/rs/moq-tokio/src/connect.rs b/rs/moq-tokio/src/connect.rs index cd67fa66785..7fb61e282be 100644 --- a/rs/moq-tokio/src/connect.rs +++ b/rs/moq-tokio/src/connect.rs @@ -479,7 +479,7 @@ failover_delay = "1s" } } -/// Whether `extensions` offers every extension, the default a config leaves out. +/// Whether `extensions` is the default a config leaves out. pub(crate) fn all_extensions(extensions: &moq_net::setup::Extensions) -> bool { *extensions == moq_net::setup::Extensions::default() } @@ -641,7 +641,7 @@ pub struct Config { )] pub version: Vec, - /// The moq-transport extensions to offer in SETUP, all by default. + /// The extensions to offer in SETUP, every moq-transport one by default. #[serde(default, skip_serializing_if = "crate::connect::all_extensions")] #[usage(skip)] pub extensions: moq_net::setup::Extensions, diff --git a/rs/moq-tokio/src/listen.rs b/rs/moq-tokio/src/listen.rs index 0acf2667450..cccb9ed4585 100644 --- a/rs/moq-tokio/src/listen.rs +++ b/rs/moq-tokio/src/listen.rs @@ -146,7 +146,7 @@ pub struct Config { )] pub version: Vec, - /// The moq-transport extensions to offer in SETUP, all by default. + /// The extensions to offer in SETUP, every moq-transport one by default. #[serde(default, skip_serializing_if = "crate::connect::all_extensions")] #[usage(skip)] pub extensions: moq_net::setup::Extensions, From eda446c4a268beebb1dac8c0cfd693454c965286 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:29:50 -0700 Subject: [PATCH 04/25] wip(lite): ietf extension carries moq-transport state across lite-07 Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 6 + doc/bin/relay/config.md | 1 + doc/concept/standard.md | 5 +- drafts/draft-lcurley-moq-ietf.md | 239 +++++++++++++++++++++++++++++++ 4 files changed, 250 insertions(+), 1 deletion(-) create mode 100644 drafts/draft-lcurley-moq-ietf.md diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 1e7a95eb933..6b440cd75f7 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -21,6 +21,12 @@ namespace prefix is illegal before draft 16), so a link to a peer without the MoQ Solicit extension, such as moxygen, learns only what that peer announces unasked. moxygen announces nothing unasked on draft 14. +A track from a moq-transport publisher keeps its Object IDs, object properties, +and END\_OF\_GROUP status objects across a moq-lite-07 link, since relays +always offer the [ietf extension](/draft/moq-ietf) that carries them. Over an +older moq-lite link they are lost: a moq-transport subscriber behind it sees +consecutive objects with no properties. + When a moq-lite-04 or later peer withdraws a broadcast, the routes relayed through it go with it at once. A change of best route is announced after 300 ms, so stale paths are retracted once instead of advertised in turn; diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index b6c863dafce..f7cfa051330 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -35,6 +35,7 @@ bind = "/run/moq/internal.sock" allow.uid = [1001] [listen.extensions] # moq-transport SETUP extensions to offer, each on by default. + # The relay always offers ietf, for moq-lite-07 relay links. auth = false # Decline MoQ Auth (draft 17+). solicit = false # Decline MoQ Solicit, so peers may announce unasked. epoch = false # Decline MoQ Epoch, so routes over moq-transport carry no epoch (draft 17+). diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 46a1f5d1cec..e06b879cd86 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -31,7 +31,7 @@ subset drops. What a peer actually observes against this implementation: - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. -- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. +- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. - **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. @@ -51,6 +51,9 @@ its `peek()` or `changed()` methods; session statistics do not request PROBE. Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side's `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. +[ietf](/draft/moq-ietf) goes the other way: it extends moq-lite-07 to carry this +object state between relays. Only Rust offers it, when `extensions.ietf` is set, +and `moq-relay` always does. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts application payloads, so relays still forward named tracks they cannot read. See [Encryption](/concept/hang#encryption). diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md new file mode 100644 index 00000000000..13dde28f731 --- /dev/null +++ b/drafts/draft-lcurley-moq-ietf.md @@ -0,0 +1,239 @@ +--- +title: "MoQ IETF Extension" +abbrev: "moq-ietf" +category: info + +docname: draft-lcurley-moq-ietf-latest +submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" +number: +date: +v: 3 +area: wit +workgroup: moq + +author: + - + fullname: Luke Curley + email: kixelated@gmail.com + +normative: + moql: I-D.lcurley-moq-lite + moqt: I-D.ietf-moq-transport + +informative: + +--- abstract + +This document defines an extension for moq-lite {{moql}} that carries the object state of MoQ Transport {{moqt}} across a moq-lite session between two relays. +A track a MoQ Transport publisher sends through relay A, then over moq-lite to relay B, reaches a MoQ Transport subscriber of relay B as it would through one relay: with its Object IDs, gaps, properties, and END_OF_GROUP status. + +--- note_Note_to_Readers + +This document was generated by an AI model from the implementation at [github.com/moq-dev/moq](https://github.com/moq-dev/moq) and is maintained alongside it. +Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.com/moq-dev/moq/pulls) if this spec sucks and you want to fix anything. + +--- middle + +# Conventions and Definitions +{::boilerplate bcp14-tagged} + +A **relayed** group or datagram arrived from a MoQ Transport publisher, so it has object state that moq-lite cannot express. +A **plain** one has none: its Object IDs are its frame indices, it has no properties, and its group ends where its last frame does. + + +# Introduction +moq-lite numbers the frames of a group consecutively from 0 and carries nothing else about them. +{{moqt}} objects carry more: Object IDs that may skip, properties, and an END_OF_GROUP status object at its own Object ID. +A relay preserves this state between MoQ Transport peers, but loses it on a moq-lite hop, so a track crossing two relays arrives changed. + +This extension carries that state across the hop. +It is meant for relays: an endpoint that does not relay MoQ Transport content would receive state it can only discard. + + +# Setup Negotiation +An endpoint offers the extension with the following Setup Parameter ({{moql}} SETUP): + +|------------|------|-------------| +| ID | Name | Value | +|-----------:|:-----|:------------| +| 0x49455446 | IETF | (empty) | +|------------|------|-------------| + +The value MUST be empty; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise. +The extension is negotiated only when both endpoints offer it, and only on moq-lite-07 and later. +An endpoint MUST NOT send any field this document defines unless the extension is negotiated, and MUST NOT parse a Group Stream, FETCH response, Track Stream, or datagram from the peer until it has the peer's SETUP and so knows whether it was. +An endpoint MAY drop a datagram that arrives before then. + + +# Group Streams {#group} +When the extension is negotiated, a Group Stream carries a Group State after the GROUP message, and an Object Record before each FRAME. +A FETCH response carries the same, with the Group State first. + +~~~ +Group Stream { + GROUP Message + Group State (i) + Object (..) ... +} + +Object { + Object Record + [FRAME Message] +} +~~~ + +## Group State +A bit field describing the group's relay state, or 0 for a plain group: + +- `0x1` **RELAYED**: The group is relayed. Every other bit requires it. +- `0x2` **FIRST_OBJECT**: The first record is the group's first object, as the FIRST_OBJECT state of a {{moqt}} subgroup. +- `0x4` **EXTENSIONS**: The {{moqt}} subgroup header said its objects carry properties. +- `0x8` **END_OF_GROUP**: The stream's end ends the group, as a {{moqt}} subgroup that contains the end of its group. + +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, or a bit without RELAYED. +A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream stops before the end of the group, such as at a subscription's end frame. + +Only subgroup 0 of a {{moqt}} group is carried. + +## Object Record + +~~~ +Object Record { + Object (i) + Properties Length (i) + Properties (..) +} +~~~ + +**Object**: +`(Skip << 1) | End`. +`Skip` is the Object ID for the first record on the stream, and the number of Object IDs skipped since the previous record afterwards. +`End` is 1 for the END_OF_GROUP record, which has no FRAME and is the last record on the stream: a receiver MUST reset the stream with a PROTOCOL_VIOLATION if anything follows it. + +**Properties**: +The object's [properties](#properties), in a block of `Properties Length` bytes. +A receiver MUST reset the stream if the length exceeds 65,536. + +In a plain group, every record has a `Skip` of 0 after the first, whose Object ID is the index of its frame, no properties, and `End` of 0. +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other record in a plain group. + +A frame index stays the position of a FRAME in the group, as in {{moql}}. +The Object ID is relay state beside it, so a plain subscriber still reads consecutive frames. + + +# Properties {#properties} +A block of an object's properties. +An empty block means the object has none. + +~~~ +Properties { + Flags (i) + Property (..) ... +} + +Property { + ID (i) + [Value (i)] + [Length (i), Value (..)] +} +~~~ + +**Flags**: +Bit `0x1` is set when the publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. +`Flags >> 1` names how the publisher serialized its Immutable Properties (0x0b): 0 for none, 1 for drafts 14 and 15, 2 for draft 16, 3 for draft 17, and 4 for draft 18 and later. +A receiver MUST treat any other value as malformed. +These let a relay refuse to forward a property to a draft that would read it differently. + +**Property**: +Properties are listed in arrival order, each with its absolute ID. +An even ID has an integer Value, and an odd ID a length-prefixed one. +Immutable Properties (0x0b) are forwarded as the publisher's bytes. +A block MUST contain exactly one when `Flags >> 1` is not 0, and none otherwise. + +The Timestamp property (0x10) carries the object's timestamp in the track's Timescale ({{moql}} TRACK_INFO), whatever units the publisher used. +A record MAY omit it when it equals the frame's timestamp. +Other properties are opaque to this extension. + + +# Track Stream {#track} +When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message after TRACK_INFO. + +~~~ +TRACK_PROPERTIES Message { + Message Length (i) + Flags (i) + Sealed Count (i) + Sealed ID (i) ... + Property (..) ... +} +~~~ + +**Flags** and **Property**: +As in [Properties](#properties), for the {{moqt}} Track Properties a relay forwards without interpreting. + +**Sealed ID**: +The IDs of the properties inside the Immutable Properties, which a relay MUST NOT restate as mutable. +A message MUST NOT list any without an Immutable Properties property. + + +# Datagrams {#datagrams} +When the extension is negotiated, a DATAGRAM carries a Datagram State after its Group Sequence. + +~~~ +DATAGRAM Body { + Subscribe ID (i) + Group Sequence (i) + Datagram State (i) + [Object ID (i)] + [Publisher Priority (8)] + [Status (i)] + [Properties Length (i), Properties (..)] + [Timestamp (i)] + Payload (b) +} +~~~ + +**Datagram State**: +A bit field, or 0 for a plain datagram, which has none of the optional fields before the Timestamp: + +- `0x1` **RELAYED**: The datagram is relayed, so its Properties follow. Every other bit requires it. +- `0x2` **OBJECT_ID**: The Object ID follows. +- `0x4` **PRIORITY**: The {{moqt}} Publisher Priority follows. +- `0x8` **END_OF_GROUP**: The object ends its group. +- `0x10` **STATUS**: The {{moqt}} Object Status follows. + +A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. + +A datagram with a non-zero Status carries no object: it has no Timestamp, even on a timed track, and its Payload MUST be empty. + + +# Security Considerations +A peer sets how much state a receiver holds for each object, up to 65,536 bytes of properties. +A receiver SHOULD charge it to the group's cache budget like a payload. + +The extension adds no authority. +A relay applies the same authorization to a relayed group as to a plain one. + + +# IANA Considerations + +This document requests one registration in the moq-lite Setup Parameters registry, if one is established. +A high, distinctive value is used to avoid collisions with the low values {{moql}} assigns. + +| Value | Name | Reference | +|:-----------|:-----|:--------------| +| 0x49455446 | IETF | This Document | + + +--- back + +# Changelog + +## Since draft-lcurley-moq-ietf-00 (in progress) + +- Initial version. + +# Acknowledgments +{:numbered="false"} + +This document was drafted with the assistance of Claude, an AI assistant by Anthropic. From de33aa7e584ffecfdb90b8659366cf4ae6297054 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 23:15:21 -0700 Subject: [PATCH 05/25] feat(lite): ietf extension carries moq-transport state between relays A new moq-lite-07 SETUP extension (draft-lcurley-moq-ietf), negotiated when both sides offer it, carries the object state a relay keeps for a moq-transport track across a lite hop: Object IDs and gaps, object properties, FIRST_OBJECT, END_OF_GROUP status objects, track properties, and the datagram object status. A track crossing two relays now reaches a moq-transport subscriber as it would through one. - setup::Extensions::ietf (default off); moq-relay always offers it. - Group streams and FETCH responses gain a Group State and per-frame Object Records; TRACK_PROPERTIES follows TRACK_INFO; DATAGRAM gains a Datagram State. - A moq-transport FETCH that misses the cache now fetches the whole group upstream, since the upstream may hold relayed Object IDs. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 5 ++- rs/moq-net/src/lite/datagram.rs | 8 +++-- rs/moq-net/src/lite/ietf.rs | 53 ++++++++++++++++++++----------- rs/moq-net/src/lite/publisher.rs | 17 +++++++--- rs/moq-net/src/lite/subscriber.rs | 32 +++++++++++++------ 5 files changed, 79 insertions(+), 36 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index b319b5d6b18..ffa9e846335 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -12187,7 +12187,10 @@ mod stitch_tests { if direct_ok.end_of_track && !hopped_ok.end_of_track => { assert_eq!(hopped_ok.properties, direct_ok.properties, "{ingress} -> {egress}"); - assert_eq!(hopped_rest, direct_rest, "{ingress} -> {egress}: the hop changed the objects"); + assert_eq!( + hopped_rest, direct_rest, + "{ingress} -> {egress}: the hop changed the objects" + ); } _ => assert_eq!( hopped.0, direct.0, diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 9abb3310a0a..711ebc87164 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -47,7 +47,9 @@ impl Encode for Datagram { return Err(EncodeError::Version); } // A status carries no payload and no time. - let status = wire.as_ref().is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); + let status = wire + .as_ref() + .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); if status && (self.timestamp.is_some() || !self.payload.is_empty()) { return Err(EncodeError::InvalidState); } @@ -81,7 +83,9 @@ impl Datagram { let mut r = Decoder::new(&buf, version.into()); let subscribe = r.varint()?; let sequence = r.varint()?; - let ietf = ietf.then(|| super::ietf::decode_datagram(&mut r, version)).transpose()?; + let ietf = ietf + .then(|| super::ietf::decode_datagram(&mut r, version)) + .transpose()?; // A status carries no payload and no time. let status = ietf .as_ref() diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 531dd7dcf29..4be62cde478 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -10,7 +10,7 @@ use bytes::Bytes; use crate::{ Error, Timescale, - coding::{DecodeError, Decoder, EncodeError, Encoder, Writer}, + coding::{DecodeError, Decoder, EncodeError, Encoder}, group, model::object::{Encoding, Fields, Properties, Property, Value}, }; @@ -163,7 +163,7 @@ fn decode_list(r: &mut Decoder<'_>) -> Result, DecodeError> { } /// Check the one Immutable Properties block against the encoding the flags declare. -fn immutable<'a>(values: &'a [Property], encoding: Option) -> Result, DecodeError> { +fn immutable(values: &[Property], encoding: Option) -> Result, DecodeError> { let mut sealed = values.iter().filter(|property| property.id == IMMUTABLE); let block = match sealed.next().map(|property| &property.value) { Some(Value::Bytes(bytes)) => Some(bytes), @@ -267,6 +267,7 @@ pub(crate) fn stamp(properties: &mut Properties, timescale: Option) { /// A group stream's object records on egress, sent before each frame once the extension /// is negotiated. +#[cfg(feature = "async")] pub(crate) struct Records { /// The previous record's Object ID, `None` before the first. prior: Option, @@ -275,6 +276,7 @@ pub(crate) struct Records { version: Version, } +#[cfg(feature = "async")] impl Records { /// Buffer the Group State for a stream serving `group` from its current index, and /// return the records its frames need. @@ -282,7 +284,7 @@ impl Records { /// `capped` when the stream stops before the group may end. Writes nothing and returns /// `None` unless the session negotiated the extension. pub fn start( - writer: &mut Writer, + writer: &mut crate::coding::Writer, ietf: bool, group: &group::Consumer, capped: bool, @@ -305,7 +307,7 @@ impl Records { /// Buffer the record for the frame at `index`, ahead of its timestamp and size. pub fn frame( &mut self, - writer: &mut Writer, + writer: &mut crate::coding::Writer, index: u64, fields: Option<&Fields>, ) -> Result<(), Error> { @@ -315,7 +317,7 @@ impl Records { /// Buffer the END_OF_GROUP record once every frame is written, if the group has one. pub fn end( &mut self, - writer: &mut Writer, + writer: &mut crate::coding::Writer, group: &group::Consumer, ) -> Result<(), Error> { // A stream capped short of the last frame stops before the end. @@ -330,7 +332,7 @@ impl Records { fn record( &mut self, - writer: &mut Writer, + writer: &mut crate::coding::Writer, id: u64, fields: Option<&Fields>, end: bool, @@ -423,7 +425,11 @@ pub(crate) fn encode_datagram( if let Some(status) = wire.status { w.varint(status)?; } - w.bytes(&encode_properties(&wire.properties, wire.properties.timestamp, version)?) + w.bytes(&encode_properties( + &wire.properties, + wire.properties.timestamp, + version, + )?) } /// Decode a datagram's relay state. Its properties' units are the track's, which the @@ -461,7 +467,12 @@ mod tests { #[test] fn object_codes_round_trip() { - for (prior, id, end) in [(None, 0, false), (None, 7, true), (Some(3), 4, false), (Some(3), 9, true)] { + for (prior, id, end) in [ + (None, 0, false), + (None, 7, true), + (Some(3), 4, false), + (Some(3), 9, true), + ] { let code = encode_object(prior, id, end).unwrap(); assert_eq!(decode_object(prior, code).unwrap(), (id, end)); } @@ -488,7 +499,9 @@ mod tests { assert_eq!(decoded.first_id, 2); assert!(decoded.fetchable && !decoded.sparse); - let partial = decode_state(encode_state(Some(&wire), false, true), 0).unwrap().unwrap(); + let partial = decode_state(encode_state(Some(&wire), false, true), 0) + .unwrap() + .unwrap(); assert!(!partial.first_object && !partial.has_end); assert_eq!(encode_state(None, true, false), 0); @@ -572,8 +585,8 @@ mod tests { }; let msg = TrackProperties(Some(Arc::new(properties.clone()))); let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); - let decoded = >::decode(&mut Decoder::new(&buf, V.into()), V) - .unwrap(); + let decoded = + >::decode(&mut Decoder::new(&buf, V.into()), V).unwrap(); assert_eq!(decoded.0.as_deref(), Some(&properties)); let none = crate::coding::Encode::encode_bytes(&TrackProperties(None), V).unwrap(); @@ -606,7 +619,7 @@ mod tests { /// Peer a relay behind `upstream` over moq-lite 07, the way a cluster does. The client /// (downstream) and server (upstream) each offer the `ietf` extension per `offer`. /// Returns the downstream origin once it learned of `broadcast`, and the sessions to hold. -#[cfg(test)] +#[cfg(all(test, feature = "async"))] pub(crate) async fn test_hop( upstream: &crate::origin::Producer, broadcast: &str, @@ -619,10 +632,9 @@ pub(crate) async fn test_hop( protocol: Some(version.alpn().to_string()), ..Default::default() }); - let extensions = |ietf| { - let mut extensions = crate::setup::Extensions::default(); - extensions.ietf = ietf; - extensions + let extensions = |ietf| crate::setup::Extensions { + ietf, + ..Default::default() }; let dial = crate::Client::new() .with_versions(version.into()) @@ -631,7 +643,7 @@ pub(crate) async fn test_hop( let serve = crate::Server::new() .with_versions(version.into()) .with_extensions(extensions(offer[1])) - .with_publisher(&upstream.consume()); + .with_publisher(upstream.consume()); let (client, server) = futures::join!( async { let (session, driver) = dial.connect(moq_clock::now(), client).await.unwrap(); @@ -652,7 +664,7 @@ pub(crate) async fn test_hop( (downstream, [client, server]) } -#[cfg(test)] +#[cfg(all(test, feature = "async"))] mod hop_tests { use super::*; use crate::{Timestamp, frame, model::ProduceTest, track}; @@ -691,7 +703,10 @@ mod hop_tests { /// A frame's Object ID and properties, when it keeps any. fn fields(frame: &frame::Object) -> Option<(u64, Properties)> { - frame.fields.as_ref().map(|fields| (fields.id, fields.properties.clone())) + frame + .fields + .as_ref() + .map(|fields| (fields.id, fields.properties.clone())) } async fn next(group: &mut group::Consumer) -> Option { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 59e7769fa6c..c7667482f2a 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2171,8 +2171,7 @@ impl Request for FetchServe { // Matches the timescale TRACK_INFO declared for the track. let timescale = shared.version.wire_timescale(group.timescale()); let capped = msg.end_frame.is_some(); - let records = - lite::ietf::Records::start(writer, ietf, &group, capped, timescale, shared.version)?; + let records = lite::ietf::Records::start(writer, ietf, &group, capped, timescale, shared.version)?; *self = Self::Serve { group, @@ -3794,8 +3793,14 @@ impl TrackRun { .insert(Priority::new(steer.priority, self.ctx.id, sequence).with_order(steer.order)), ), }; - self.children - .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, capped, rank, group)); + self.children.push(GroupServe::new( + self.ctx.clone(), + sequence, + frame_start, + capped, + rank, + group, + )); } } @@ -4095,7 +4100,9 @@ impl GroupServe { let index = self.group.index() - 1; let buffered = records .as_mut() - .map_or(Ok(()), |records| records.frame(writer, index, next.fields.as_deref())) + .map_or(Ok(()), |records| { + records.frame(writer, index, next.fields.as_deref()) + }) .and_then(|()| { buffer_frame_info( writer, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d066fbce32e..cca24dc4ea0 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1214,10 +1214,9 @@ impl FrameIngest { group.mark_gap(id, gap)?; // The frame header already carries the time, so a record may omit it. let plain = id == group.frame_count() as u64 - && properties.is_plain() - && properties - .timestamp - .is_none_or(|time| Some(time) == timestamp.map(|time| time.value())); + && properties.is_plain() && properties + .timestamp + .is_none_or(|time| Some(time) == timestamp.map(|time| time.value())); if !plain && !records.relayed { return Poll::Ready(Err(Error::ProtocolViolation)); } @@ -2488,7 +2487,10 @@ mod tests { let (res, track) = receive_ietf(&[0, 0, 0, 1, u64::from(b'x')]).await; res.unwrap(); let mut group = track.consume().peek_group(0).unwrap(); - assert_eq!(group.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, b"x"[..]); + assert_eq!( + group.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, + b"x"[..] + ); // A relayed group starting at Object 4, then END_OF_GROUP at Object 6. let (res, track) = receive_ietf(&[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; @@ -5930,10 +5932,17 @@ struct TrackInfoFetch { enum TrackInfoState { Open, - Send { stream: Stream }, - Read { stream: Stream }, + Send { + stream: Stream, + }, + Read { + stream: Stream, + }, /// Reading the TRACK_PROPERTIES the `ietf` extension sends after TRACK_INFO. - Properties { stream: Stream, info: track::Info }, + Properties { + stream: Stream, + info: track::Info, + }, } impl TrackInfoFetch { @@ -6833,7 +6842,12 @@ impl kio::Task for FetchServeRun { stream, producer, joined, - ingest: Box::new(FrameIngest::new(&self.serve.subscriber, self.timescale, ietf, frame_start)), + ingest: Box::new(FrameIngest::new( + &self.serve.subscriber, + self.timescale, + ietf, + frame_start, + )), }; } FetchRunState::Ingest { From 07ae45b7b9974c38444e683b9f0d475f1afe85e1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 23:16:12 -0700 Subject: [PATCH 06/25] quest: retire ietf-extension/lite with its PR The epic keeps its own nightly moxygen work, so it now carries a size. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ietf-extension/README.md | 6 +-- quest/m1/ietf-extension/lite.md | 61 ------------------------------- quest/m1/lite07-finalize.md | 1 - quest/m1/refresh/lite.md | 6 +-- 4 files changed, 3 insertions(+), 71 deletions(-) delete mode 100644 quest/m1/ietf-extension/lite.md diff --git a/quest/m1/ietf-extension/README.md b/quest/m1/ietf-extension/README.md index 2131bf38583..3f8dcb6c59a 100644 --- a/quest/m1/ietf-extension/README.md +++ b/quest/m1/ietf-extension/README.md @@ -1,4 +1,4 @@ -# moq-transport passthrough +# [M] moq-transport passthrough ## Goal @@ -81,10 +81,6 @@ Work owned by this README, after the children land: - FETCH cases are skipped upstream. Section 8 stays out while PUBLISH is declined. -## Required - -- [Relay hops](/quest/m1/ietf-extension/lite.md) - the `ietf` SETUP extension carries every crate-private field across a lite-07 hop between relays - ## Related - [#4926](https://github.com/moq-dev/moq/issues/4926) - the declined request for an object-level API; this carries the fields for relays only diff --git a/quest/m1/ietf-extension/lite.md b/quest/m1/ietf-extension/lite.md deleted file mode 100644 index 7abbe62a543..00000000000 --- a/quest/m1/ietf-extension/lite.md +++ /dev/null @@ -1,61 +0,0 @@ -# [M] The ietf extension carries moq-transport fields between relays - -## Goal - -Two relays that negotiate the `ietf` SETUP extension carry every -crate-private moq-transport field across a lite-07 hop. A track forwarded -moq-transport publisher -> relay A -> relay B -> moq-transport subscriber -arrives as it would through one relay. A session without the extension is -unchanged. - -## Plan - -Decided 2026-10-13 (see the [epic](/quest/m1/ietf-extension/README.md)). - -- Negotiate with a SETUP extension, like auth and solicit, not a separate - ALPN. That avoids a Version variant per lite version and leaves the lite-07 - finalize rename alone. -- Add a documented `pub ietf: bool` field on `setup::Extensions`, default - `false`. moq-relay sets it. Both sides must offer it. -- Target the current wip version. If lite-07 has finalized before this - lands, use the next wip/version. Published versions get no incompatible - framing changes. -- When negotiated, the fields are always present, with no flag bits: - - The Group message gains the explicit FIRST_OBJECT state. The first - object ID alone cannot recover the FIRST_OBJECT bit. Subgroups other - than 0 are not carried (see the [epic](/quest/m1/ietf-extension/README.md)). - - Every frame gains a `skip` varint and a length-prefixed properties block, - 2 bytes per frame when empty. - - A terminal record after the frames carries the END_OF_GROUP status - position. It is not known when a live group's opening header is sent; - frames must flow before the publisher ends the group. - - Datagrams gain their object ID, properties, and status. - - Track info gains the unknown track properties: `track::Info::properties` - (`model::object::TrackProperties`), with its sealed keys. - - Immutable properties carry their ingress encoding family alongside the - unchanged inner bytes, so downstream IETF egress can refuse incompatible - encodings. -- Dynamic-group requests are not this extension's job. Native lite-07 - carries them as [refresh](/quest/m1/refresh/lite.md), decided 2026-10-16. -- Write `drafts/draft-lcurley-moq-ietf.md` for the extension and pass - `just drafts check`. List it with the other project drafts in - `doc/concept/standard.md`, and note in `doc/bin/relay/` that relays enable - it. -- js/net does not implement it and never offers it. - -Tests: per-feature cases through a two-relay cluster. Cover a cluster peer -without the extension (no properties), and run -`just test interop --all`. -Prove that frames arrive through both relays while the upstream group is -still open, then preserve its terminal status position. Cover FIRST_OBJECT -both set and clear with the same nonzero starting object ID, immutable -encoding provenance. - -Public API: `setup::Extensions::ietf`. Wire: a new lite-07 SETUP extension -and the framing above, only when negotiated. - -## Related - -- [Refresh on the lite wire](/quest/m1/refresh/lite.md) - carries dynamic-group requests between relays instead of this extension - -- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - the extension targets the wip version and does not gate the cut diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 9def8517eeb..a4fbea4123f 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -95,5 +95,4 @@ is published; older versions are unchanged. ## Related -- [Relay hops](/quest/m1/ietf-extension/lite.md) - the `ietf` SETUP extension targets lite-07 wip and does not gate the cut - [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment condition that follows this diff --git a/quest/m1/refresh/lite.md b/quest/m1/refresh/lite.md index 8ed29cc630e..f1cbfabf981 100644 --- a/quest/m1/refresh/lite.md +++ b/quest/m1/refresh/lite.md @@ -31,10 +31,8 @@ Decided 2026-10-16 (see the [epic](/quest/m1/refresh/README.md)). join. - **Drafts.** Update `drafts/draft-lcurley-moq-lite.md` (TRACK_INFO, SUBSCRIBE_UPDATE, the lite-07 changelog) and pass `just drafts check`. -- **The ietf extension.** Cluster hops no longer need it to carry - dynamic-group requests; native lite does. This quest removes that duty - from the [relay extension](/quest/m1/ietf-extension/lite.md) if that quest - has not landed yet, or deletes its request path if it has. +- **The ietf extension.** Cluster hops carry dynamic-group requests on + native lite; the [ietf extension](/drafts/draft-lcurley-moq-ietf.md) has no request path. Tests: codec round trips on lite-07 and an older version without the fields. A two-relay cluster test checks that a join over the ratio at the far From 4574e366f9c13356dc9b8d301cf1506470d43ba3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 23:46:27 -0700 Subject: [PATCH 07/25] fix(lite): bound ietf records and TRACK_PROPERTIES by what moq-transport ingress keeps A record's properties block stays encoded until its frame is created, so the cache charges its decoded form at once instead of a stalled stream holding it. TRACK_PROPERTIES drops its Sealed IDs: the receiver parses them from the Immutable Properties block rather than trusting a list that could disagree. It carries at most 64 properties, the moq-transport ingress limit, and none that TRACK_INFO carries. The draft now requires a record's Timestamp whenever the object has one, since an omitted one is relayed as absent. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 17 ++++--- rs/moq-net/src/ietf/mod.rs | 2 +- rs/moq-net/src/ietf/object.rs | 16 ++++--- rs/moq-net/src/ietf/properties.rs | 27 ++++++++++- rs/moq-net/src/lite/ietf.rs | 78 ++++++++++++++++++++++++------- rs/moq-net/src/lite/subscriber.rs | 56 ++++++++++++++++------ 6 files changed, 152 insertions(+), 44 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 13dde28f731..efc477b94ce 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -151,7 +151,7 @@ Immutable Properties (0x0b) are forwarded as the publisher's bytes. A block MUST contain exactly one when `Flags >> 1` is not 0, and none otherwise. The Timestamp property (0x10) carries the object's timestamp in the track's Timescale ({{moql}} TRACK_INFO), whatever units the publisher used. -A record MAY omit it when it equals the frame's timestamp. +It MUST be present whenever the object has one, since an absent Timestamp is relayed as absent. Other properties are opaque to this extension. @@ -162,18 +162,20 @@ When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message TRACK_PROPERTIES Message { Message Length (i) Flags (i) - Sealed Count (i) - Sealed ID (i) ... Property (..) ... } ~~~ **Flags** and **Property**: As in [Properties](#properties), for the {{moqt}} Track Properties a relay forwards without interpreting. +An empty message is a Flags of 0 and no properties. -**Sealed ID**: -The IDs of the properties inside the Immutable Properties, which a relay MUST NOT restate as mutable. -A message MUST NOT list any without an Immutable Properties property. +A message MUST NOT carry more than 64 properties, nor any a relay interprets rather than forwards: MAX_CACHE_DURATION (0x04), TIMESCALE (0x08), DEFAULT_PUBLISHER_PRIORITY (0x0e), DEFAULT_PUBLISHER_GROUP_ORDER (0x22), and DYNAMIC_GROUPS (0x30). +TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. +A message that breaks either rule is malformed. + +The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable. +Track Properties never use the Immutable Properties family of drafts 14 and 15, so a `Flags >> 1` of 1 is malformed here. # Datagrams {#datagrams} @@ -209,7 +211,8 @@ A datagram with a non-zero Status carries no object: it has no Timestamp, even o # Security Considerations A peer sets how much state a receiver holds for each object, up to 65,536 bytes of properties. -A receiver SHOULD charge it to the group's cache budget like a payload. +A receiver SHOULD charge it to the group's cache budget like a payload, including any overhead of its decoded form. +A TRACK_PROPERTIES message is bounded by its Message Length and the 64-property limit, and is held once per track. The extension adds no authority. A relay applies the same authorization to a relayed group as to a plain one. diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index a934582f0df..6b08cb6ea84 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -31,7 +31,7 @@ mod namespace; pub(crate) mod object; pub mod peer; mod priority; -mod properties; +pub(crate) mod properties; mod publish; mod publish_namespace; #[cfg(feature = "async")] diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index cd41857f385..91169672450 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -160,16 +160,20 @@ pub(crate) struct Sealed { pub gap: Option, } -/// Parse an Immutable Properties block (0x0b) serialized in the `encoding` family. -pub(crate) fn sealed(bytes: &Bytes, encoding: Encoding) -> Result { - // Any draft in the family parses its keys and integers the same way. - let version = match encoding { +/// A draft that serializes properties in the `encoding` family. Any draft in the family +/// parses its keys and integers the same way. +pub(super) fn family(encoding: Encoding) -> Version { + match encoding { Encoding::Absolute => Version::Draft14, Encoding::DeltaQuic => Version::Draft16, Encoding::Delta { seven: false } => Version::Draft17, Encoding::Delta { seven: true } => Version::Draft18, - }; - let nested = list(bytes, version, true).map_err(|_| Error::MalformedTrack)?; + } +} + +/// Parse an Immutable Properties block (0x0b) serialized in the `encoding` family. +pub(crate) fn sealed(bytes: &Bytes, encoding: Encoding) -> Result { + let nested = list(bytes, family(encoding), true).map_err(|_| Error::MalformedTrack)?; Ok(Sealed { time: nested.time.is_some(), gap: nested.gap, diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index 8befea3a33b..ee3dfb3e691 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -19,7 +19,8 @@ use crate::model::object::{Property, TrackProperties, Value}; use super::{GroupOrder, Version}; -const MAX_PROPERTIES: u64 = 64; +/// The most Track Properties a message may carry, which also bounds what a relay forwards. +pub(crate) const MAX_PROPERTIES: u64 = 64; /// Maximum byte value length per spec Section 1.4.3. const MAX_KVP_VALUE_LEN: usize = (1 << 16) - 1; @@ -265,6 +266,30 @@ impl Properties { } } +/// Whether moq-net applies the Track Property `id` itself, so a relay restates it from the +/// track's info rather than forwarding the publisher's. +pub(crate) fn understood(id: u64) -> bool { + matches!( + id, + MAX_CACHE_DURATION | TIMESCALE | DEFAULT_PUBLISHER_PRIORITY | DEFAULT_PUBLISHER_GROUP_ORDER | DYNAMIC_GROUPS + ) +} + +/// The keys a Track Properties' Immutable Properties `block` seals, serialized in the +/// `encoding` family, checking the ones we understand as [`Properties::decode`] does. +pub(crate) fn sealed_ids(block: &[u8], encoding: crate::model::object::Encoding) -> Result, DecodeError> { + // Track Properties start at draft-16, whose families all delta-encode their keys. + if encoding == crate::model::object::Encoding::Absolute { + return Err(DecodeError::InvalidValue); + } + let version = super::object::family(encoding); + sealed( + &mut Decoder::new(block, version.into()), + &mut Properties::default(), + &mut Vec::new(), + ) +} + /// A DYNAMIC_GROUPS value, which is a boolean: anything but 0 or 1 is malformed. pub(super) fn dynamic_groups(value: u64) -> Result { match value { diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 4be62cde478..37481e8a9d4 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -147,10 +147,13 @@ fn encode_list<'a>(w: &mut Encoder<'_>, values: impl IntoIterator) -> Result, DecodeError> { +/// Decode up to `max` properties to the end of `r`, in the order they arrived. +fn decode_list(r: &mut Decoder<'_>, max: usize) -> Result, DecodeError> { let mut values = Vec::new(); while !r.is_empty() { + if values.len() >= max { + return Err(DecodeError::TooMany); + } let id = r.varint()?; let value = match id % 2 { 0 => Value::Int(r.varint()?), @@ -218,7 +221,8 @@ pub(crate) fn decode_properties( } let r = &mut Decoder::new(block, version.into()); (properties.delivery_timeout, properties.immutable) = decode_flags(r.varint()?)?; - let mut values = decode_list(r)?; + // The block's length bounds them, as for a moq-transport object. + let mut values = decode_list(r, usize::MAX)?; let mut timestamps = values.iter().filter(|property| property.id == TIMESTAMP); properties.timestamp = match timestamps.next() { @@ -360,29 +364,28 @@ pub struct TrackProperties(pub Option impl Message for TrackProperties { fn encode_msg(&self, w: &mut Encoder<'_>, _: Version) -> Result<(), EncodeError> { let Some(properties) = &self.0 else { - w.varint(0)?; return w.varint(0); }; w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; - w.varint(properties.sealed.len() as u64)?; - for id in &properties.sealed { - w.varint(*id)?; - } encode_list(w, &properties.values) } fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { let (delivery_timeout, encoding) = decode_flags(r.varint()?)?; - let count = r.varint()?; - // Every ID takes at least a byte, so this bounds the allocation by the message. - if count > r.remaining() as u64 { - return Err(DecodeError::Short); - } - let sealed = (0..count).map(|_| r.varint()).collect::, _>>()?; - let values = decode_list(r)?; - if immutable(&values, encoding)?.is_none() && !sealed.is_empty() { + // No more than moq-transport ingress keeps, which is all a relay forwards. + let values = decode_list(r, crate::ietf::properties::MAX_PROPERTIES as usize)?; + // TRACK_INFO carries these, so a second copy could only contradict it. + if values + .iter() + .any(|property| crate::ietf::properties::understood(property.id)) + { return Err(DecodeError::InvalidValue); } + // The sealed keys are the block's own, so they are parsed rather than trusted. + let sealed = match (immutable(&values, encoding)?, encoding) { + (Some(block), Some(encoding)) => crate::ietf::properties::sealed_ids(block, encoding)?, + _ => Vec::new(), + }; if values.is_empty() { return Ok(Self(None)); } @@ -595,6 +598,49 @@ mod tests { assert!(decoded.0.is_none()); } + /// A peer cannot make a relay hold or forward more than moq-transport ingress would, + /// restate what TRACK_INFO carries, or claim sealed keys its block does not hold. + #[test] + fn track_properties_refuse_what_ingress_would_not_keep() { + let decode = |values: Vec, immutable: Option| { + let msg = TrackProperties(Some(Arc::new(crate::model::object::TrackProperties { + values, + immutable, + ..Default::default() + }))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + >::decode(&mut Decoder::new(&buf, V.into()), V) + }; + let opaque = |id| Property { + id, + value: Value::Int(1), + }; + + let max = crate::ietf::properties::MAX_PROPERTIES; + assert!(decode((0..max).map(|i| opaque(0x40 + 2 * i)).collect(), None).is_ok()); + assert!( + decode((0..=max).map(|i| opaque(0x40 + 2 * i)).collect(), None).is_err(), + "more than ingress keeps" + ); + // TIMESCALE belongs to TRACK_INFO. + assert!(decode(vec![opaque(0x08)], None).is_err(), "an understood property"); + + // The sealed keys come from the block, never the sender. + let sealed = Property { + id: IMMUTABLE, + value: Value::Bytes(Bytes::from_static(&[0x20, 0x01, 0x04, 0x05])), + }; + let decoded = decode(vec![sealed.clone()], Some(Encoding::Delta { seven: true })) + .unwrap() + .0 + .unwrap(); + assert_eq!(decoded.sealed, [0x20, 0x24]); + assert!( + decode(vec![sealed], Some(Encoding::Absolute)).is_err(), + "track properties never use absolute keys" + ); + } + #[test] fn datagram_state_round_trips() { let wire = crate::model::datagram::Wire { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index cca24dc4ea0..4886e4615f3 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1041,8 +1041,11 @@ struct RecordIngest { relayed: bool, /// The previous record's Object ID, `None` before the first. prior: Option, - /// The record of the frame being read: its Object ID, properties, and Prior Object ID Gap. - pending: Option<(u64, crate::model::object::Properties, Option)>, + /// The record of the frame being read: its Object ID and properties block. + /// + /// The block stays encoded until the frame is created, so the cache charges its decoded + /// form at once rather than a stalled stream holding it uncharged. + pending: Option<(u64, bytes::Bytes)>, } enum IngestPhase { @@ -1164,8 +1167,8 @@ impl FrameIngest { if !records.relayed && (end || !block.is_empty()) { return Poll::Ready(Err(Error::ProtocolViolation)); } - let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; if end { + let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; group.mark_gap(id, decoded.gap)?; group.set_end_object(crate::model::object::Fields { id, @@ -1173,7 +1176,7 @@ impl FrameIngest { })?; self.phase = IngestPhase::Ended; } else { - records.pending = Some((id, decoded.properties, decoded.gap)); + records.pending = Some((id, block)); self.phase = IngestPhase::Timing; } } @@ -1210,9 +1213,11 @@ impl FrameIngest { // A frame that says nothing a plain frame would not keeps no fields. let fields = match &mut self.records { Some(records) => { - let (id, properties, gap) = records.pending.take().expect("a record precedes each frame"); + let (id, block) = records.pending.take().expect("a record precedes each frame"); + let lite::ietf::Decoded { properties, gap } = + lite::ietf::decode_properties(&block, self.timescale, self.version)?; group.mark_gap(id, gap)?; - // The frame header already carries the time, so a record may omit it. + // Time alone, which the frame header carries already, is plain. let plain = id == group.frame_count() as u64 && properties.is_plain() && properties .timestamp @@ -2425,8 +2430,9 @@ mod tests { } /// Receive group 0 of an untimed track over a lite-07 session that negotiated the - /// `ietf` extension, its stream holding `body` after the GROUP header. - async fn receive_ietf(body: &[u64]) -> (Result<(), Error>, track::Producer) { + /// `ietf` extension, its stream holding `body` after the GROUP header. Also returns the + /// cache pool the track charges. + async fn receive_ietf(body: &[u64]) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { use crate::transport::poll::Session as _; let version = Version::Lite07; @@ -2460,8 +2466,12 @@ mod tests { going_away: Default::default(), auth: crate::auth::Handle::new(false), }); + let pool = crate::cache::Pool::unbounded(); let track = track::Producer::new( - std::sync::Arc::new(crate::broadcast::Info::default()), + std::sync::Arc::new(crate::broadcast::Info { + pool: pool.clone(), + ..Default::default() + }), "video", crate::track::Info::default().with_timescale(None), ); @@ -2477,14 +2487,14 @@ mod tests { let (_, recv) = session.open_bi(Default::default()).await.unwrap(); let mut group = GroupRecv::new(subscriber, Reader::new(recv, version)); let res = kio::wait(|waiter| group.poll_serve(waiter)).await; - (res, track) + (res, track, pool) } /// Object records: `(Skip << 1) | END`, the properties block's length, then the frame. #[moq_clock::test] async fn ietf_records_frame_a_group() { // A plain group: Group State 0, then frame 0 with an empty record. - let (res, track) = receive_ietf(&[0, 0, 0, 1, u64::from(b'x')]).await; + let (res, track, _) = receive_ietf(&[0, 0, 0, 1, u64::from(b'x')]).await; res.unwrap(); let mut group = track.consume().peek_group(0).unwrap(); assert_eq!( @@ -2493,7 +2503,7 @@ mod tests { ); // A relayed group starting at Object 4, then END_OF_GROUP at Object 6. - let (res, track) = receive_ietf(&[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; + let (res, track, _) = receive_ietf(&[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; res.unwrap(); let group = track.consume().peek_group(0).unwrap(); assert_eq!(group.end_object().map(|end| end.id), Some(6)); @@ -2512,11 +2522,31 @@ mod tests { (&[0x1, 1, 0, 0], "a byte after END_OF_GROUP"), (&[0x1, 0, 0], "a stream ending inside a frame"), ] { - let (res, _) = receive_ietf(body).await; + let (res, ..) = receive_ietf(body).await; assert!(res.is_err(), "accepted {reason}"); } } + /// A properties block decodes to more heap than its wire bytes, so its decoded form is + /// what the cache charges, as the frame it describes is created. + #[moq_clock::test] + async fn ietf_records_charge_their_decoded_properties() { + const COUNT: u64 = 1000; + // A relayed group's Object 0, whose block holds COUNT two-byte properties (0x20 = 1) + // after its Flags, then an empty frame. + let mut body = vec![0x1, 0, 1 + 2 * COUNT, 0]; + for _ in 0..COUNT { + body.extend([0x20, 1]); + } + body.push(0); + let (res, track, pool) = receive_ietf(&body).await; + res.unwrap(); + let group = track.consume().peek_group(0).unwrap(); + assert_eq!(group.frame_count(), 1); + let decoded = COUNT * size_of::() as u64; + assert!(pool.used() >= decoded, "{} cached for {decoded} decoded", pool.used()); + } + /// Receive group 5 starting at 500ms over `version`, on a received timed track whose /// group 4 starts at 1000ms, returning the stream's result and the track. async fn receive_rewind(version: Version) -> (Result<(), Error>, track::Producer) { From b0c3bae5709ecaeb6968cc59e63813c53f16bff5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 00:22:25 -0700 Subject: [PATCH 08/25] fix(net): carry relayed object properties as their encoded block A relayed object's properties other than its mutable Timestamp are now held as one encoded block, in the encoding of the moq-transport draft they arrived on, instead of a decoded list. The cache charges the block's bytes, so a peer cannot make a relay hold many times what it sent, for groups or datagrams. The ietf extension forwards the block unchanged: Flags name its encoding, and the Timestamp travels beside it. Re-encoding never grows it, so every list moq-transport admits crosses the hop and leaves byte for byte. Egress decodes the block only to re-encode it for another draft. Records and TRACK_PROPERTIES decode only their canonical form, and the lite fuzz target now covers ietf datagrams and TRACK_PROPERTIES. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 66 +++++--- rs/moq-net/src/fuzz.rs | 46 +++-- rs/moq-net/src/ietf/group.rs | 2 +- rs/moq-net/src/ietf/object.rs | 213 +++++++++++++++-------- rs/moq-net/src/ietf/subscriber.rs | 11 +- rs/moq-net/src/lite/ietf.rs | 269 +++++++++++++++++++----------- rs/moq-net/src/lite/subscriber.rs | 27 +-- rs/moq-net/src/model/object.rs | 40 +++-- 8 files changed, 427 insertions(+), 247 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index efc477b94ce..e24737c06bf 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -111,8 +111,9 @@ Object Record { `End` is 1 for the END_OF_GROUP record, which has no FRAME and is the last record on the stream: a receiver MUST reset the stream with a PROTOCOL_VIOLATION if anything follows it. **Properties**: -The object's [properties](#properties), in a block of `Properties Length` bytes. -A receiver MUST reset the stream if the length exceeds 65,536. +The object's [properties](#properties), in `Properties Length` bytes. +An empty one means the object has none. +A receiver MUST reset the stream if the length exceeds 65,546, the largest Property Block beside a Flags byte and a Timestamp. In a plain group, every record has a `Skip` of 0 after the first, whose Object ID is the index of its frame, no properties, and `End` of 0. A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other record in a plain group. @@ -122,36 +123,35 @@ The Object ID is relay state beside it, so a plain subscriber still reads consec # Properties {#properties} -A block of an object's properties. -An empty block means the object has none. +An object's properties: its mutable Timestamp, and every other property as one block in the encoding of the {{moqt}} draft it arrived on. +A relay forwards the block to a peer of that encoding unchanged, so the block never grows on a hop, and holds it as received rather than as a decoded list many times its size. ~~~ Properties { Flags (i) - Property (..) ... -} - -Property { - ID (i) - [Value (i)] - [Length (i), Value (..)] + [Timestamp (i)] + Property Block (..) } ~~~ **Flags**: -Bit `0x1` is set when the publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. -`Flags >> 1` names how the publisher serialized its Immutable Properties (0x0b): 0 for none, 1 for drafts 14 and 15, 2 for draft 16, 3 for draft 17, and 4 for draft 18 and later. -A receiver MUST treat any other value as malformed. -These let a relay refuse to forward a property to a draft that would read it differently. -**Property**: -Properties are listed in arrival order, each with its absolute ID. -An even ID has an integer Value, and an odd ID a length-prefixed one. -Immutable Properties (0x0b) are forwarded as the publisher's bytes. -A block MUST contain exactly one when `Flags >> 1` is not 0, and none otherwise. +- `0x1` **DELIVERY_TIMEOUT**: The publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. It requires a Property Block. +- `0x2` **TIMESTAMP**: The Timestamp follows. +- `Flags >> 2` names the Property Block's encoding: 0 for no block, 1 for drafts 14 and 15 (absolute IDs and QUIC varints), 2 for draft 16 (delta IDs and QUIC varints), 3 for draft 17, and 4 for draft 18 and later. + +A receiver MUST treat any other value as malformed, as it MUST a Flags of 0, which an empty Properties says instead. +DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that would read it differently. -The Timestamp property (0x10) carries the object's timestamp in the track's Timescale ({{moql}} TRACK_INFO), whatever units the publisher used. +**Timestamp**: +The object's mutable Timestamp property (0x10), in the track's Timescale ({{moql}} TRACK_INFO). It MUST be present whenever the object has one, since an absent Timestamp is relayed as absent. + +**Property Block**: +The rest of the Properties: every other property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. +Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. +It MUST be present exactly when `Flags >> 2` is not 0, MUST NOT be longer than 65,536 bytes, and MUST NOT contain a mutable Timestamp. +A receiver MUST treat a block its encoding's drafts would refuse as malformed. Other properties are opaque to this extension. @@ -166,9 +166,23 @@ TRACK_PROPERTIES Message { } ~~~ -**Flags** and **Property**: -As in [Properties](#properties), for the {{moqt}} Track Properties a relay forwards without interpreting. -An empty message is a Flags of 0 and no properties. +**Flags**: +Bit `0x1` is DELIVERY_TIMEOUT, as in [Properties](#properties). +`Flags >> 1` names how the publisher serialized its Immutable Properties (0x0b), with the codes of [Properties](#properties), or 0 for none. +A message without properties MUST have a Flags of 0. + +**Property**: +The {{moqt}} Track Properties a relay forwards without interpreting, in arrival order, each with its absolute ID. +An even ID has an integer Value, and an odd ID a length-prefixed one. +Immutable Properties are forwarded as the publisher's bytes, and there MUST be exactly one when `Flags >> 1` is not 0, and none otherwise. + +~~~ +Property { + ID (i) + [Value (i)] + [Length (i), Value (..)] +} +~~~ A message MUST NOT carry more than 64 properties, nor any a relay interprets rather than forwards: MAX_CACHE_DURATION (0x04), TIMESCALE (0x08), DEFAULT_PUBLISHER_PRIORITY (0x0e), DEFAULT_PUBLISHER_GROUP_ORDER (0x22), and DYNAMIC_GROUPS (0x30). TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. @@ -210,8 +224,8 @@ A datagram with a non-zero Status carries no object: it has no Timestamp, even o # Security Considerations -A peer sets how much state a receiver holds for each object, up to 65,536 bytes of properties. -A receiver SHOULD charge it to the group's cache budget like a payload, including any overhead of its decoded form. +A peer sets how much state a receiver holds for each object, up to a 65,536-byte Property Block. +A receiver SHOULD hold the block as received, not decoded, and charge it to the group's cache budget like a payload. A TRACK_PROPERTIES message is bounded by its Message Length and the 64-property limit, and is held once per track. The extension adds no authority. diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index d4f70613ef2..47cb8d0a814 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -35,10 +35,15 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr std::sync::Arc::new(crate::model::object::Fields { id: id as u64, properties: crate::model::object::Properties { - values: vec![crate::model::object::Property { - id: 0x80, - value: crate::model::object::Value::Int(96_000), - }], + block: crate::ietf::object::block( + &[crate::model::object::Property { + id: 0x80, + value: crate::model::object::Value::Int(96_000), + }], + crate::model::object::Encoding::Delta { seven: true }, + true, + ) + .unwrap(), ..Default::default() }, }) @@ -99,7 +104,7 @@ const IETF_VERSIONS: &[ietf::Version] = &[ ]; /// How many types [`lite_wire`] dispatches over. -const LITE_KINDS: u8 = 21; +const LITE_KINDS: u8 = 22; /// How many types [`ietf_wire`] dispatches over. const IETF_KINDS: u8 = 40; @@ -146,20 +151,28 @@ 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 whether the session + // negotiated the `ietf` extension, so try every reading. + let ietf: &[bool] = match version.has_ietf() { + true => &[false, true], + false => &[false], + }; let mut any = false; - for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, false, |_| timed) else { - continue; - }; - any = true; + for &ietf in ietf { + for timed in [true, false] { + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| timed) else { + continue; + }; + any = true; - let Ok(first) = decoded.encode_bytes(version) else { - continue; - }; + let Ok(first) = decoded.encode_bytes(version) else { + continue; + }; - let echo = lite::Datagram::decode(first, version, false, |_| timed).expect("could not decode our own encoding"); - assert_eq!(echo, decoded, "datagram did not survive a round trip"); + let echo = + lite::Datagram::decode(first, version, ietf, |_| timed).expect("could not decode our own encoding"); + assert_eq!(echo, decoded, "datagram did not survive a round trip"); + } } any } @@ -197,6 +210,7 @@ pub fn lite_wire(data: &[u8]) -> bool { 18 => roundtrip::(rest, version), 19 => datagram(rest, version), 20 => roundtrip::(rest, version), + 21 => roundtrip::(rest, version), _ => unreachable!("kind is taken modulo LITE_KINDS"), } } diff --git a/rs/moq-net/src/ietf/group.rs b/rs/moq-net/src/ietf/group.rs index 74c504afda7..5e27e089b33 100644 --- a/rs/moq-net/src/ietf/group.rs +++ b/rs/moq-net/src/ietf/group.rs @@ -15,7 +15,7 @@ const PROP_TIMESTAMP: u64 = 0x10; /// Implementation limit for an object's extension (property) block, independent of the /// IETF draft. Checked at the length prefix, before the block is buffered. -pub(super) const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; +pub(crate) const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; /// The length prefix of an object's extension block, refused past [`MAX_OBJECT_EXTENSIONS`]. #[derive(Debug)] diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 91169672450..4340fb8eed7 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -39,27 +39,35 @@ pub(super) fn check_status(version: Version, properties: &Properties) -> Result< } } -pub(super) struct Decoded { +pub(crate) struct Decoded { pub properties: Properties, pub timestamp: Option, pub gap: Option, } +/// The largest properties block an object may carry, which a relay forwards unchanged. +pub(crate) const MAX_BLOCK: usize = super::group::MAX_OBJECT_EXTENSIONS; + struct List { - properties: Properties, + /// In arrival order, without the mutable Timestamp. Values borrow the input. + values: Vec, + timestamp: Option, time: Option, gap: Option, sealed_time: bool, + immutable: bool, } fn list(data: &Bytes, version: Version, immutable: bool) -> Result { let keys = encoding(version); let mut decoder = Decoder::new(data, version.into()); let mut result = List { - properties: Properties::default(), + values: Vec::new(), + timestamp: None, time: None, gap: None, sealed_time: false, + immutable: false, }; let mut previous = 0u64; while !decoder.is_empty() { @@ -76,7 +84,7 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result } if id == 0x10 { result.time = Some(value); - if result.properties.timestamp.replace(value).is_some() { + if result.timestamp.replace(value).is_some() { return Err(Error::MalformedTrack); } continue; @@ -87,10 +95,9 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result if bytes.len() > u16::MAX as usize { return Err(Error::MalformedTrack); } - // A small cached property must not pin the reader's larger receive buffer. - let bytes = Bytes::copy_from_slice(bytes); + let bytes = data.slice_ref(bytes); if id == 0x0b { - if immutable || result.properties.immutable.replace(keys).is_some() { + if immutable || std::mem::replace(&mut result.immutable, true) { return Err(Error::MalformedTrack); } let nested = list(&bytes, version, true).map_err(|_| Error::MalformedTrack)?; @@ -104,22 +111,107 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result } Value::Bytes(bytes) }; - result.properties.values.push(Property { id, value }); + result.values.push(Property { id, value }); } Ok(result) } -pub(super) fn read(data: &Bytes, version: Version, timescale: Option) -> Result { - let mut parsed = list(data, version, false)?; - parsed.properties.timescale = timescale.filter(|_| parsed.time.is_some()); - parsed.properties.sealed_time = parsed.sealed_time; - parsed.properties.delivery_timeout = has_delivery_timeout(version); +/// Serialize `values` as `encoding` does, in ascending ID order. Equal IDs keep their order. +fn serialize<'a>(values: impl IntoIterator, encoding: Encoding) -> Result, Error> { + let mut sorted: Vec<_> = values.into_iter().collect(); + sorted.sort_by_key(|property| property.id); + let mut out = Vec::new(); + let mut encoder = Encoder::new(&mut out, family(encoding).into()); + let mut previous = 0; + for property in sorted { + encoder.varint(match encoding { + Encoding::Absolute => property.id, + Encoding::Delta { .. } | Encoding::DeltaQuic => property.id - previous, + })?; + previous = property.id; + match &property.value { + Value::Int(value) => encoder.varint(*value)?, + Value::Bytes(value) => encoder.bytes(value)?, + } + } + Ok(out) +} + +/// Encode `values` as the block of an object whose properties arrived as `encoding`, or +/// `None` without any. +/// +/// Sorting a delta-encoded list, which arrives ascending, and dropping its Timestamp +/// never grows it, so the block fits wherever the publisher's list did. +pub(crate) fn block( + values: &[Property], + encoding: Encoding, + delivery_timeout: bool, +) -> Result, Error> { + if values.is_empty() { + return Ok(None); + } + Ok(Some(crate::model::object::Block { + bytes: serialize(values, encoding)?.into(), + encoding, + immutable: values.iter().any(|property| property.id == 0x0b), + delivery_timeout, + })) +} + +/// What a received [`Block`](crate::model::object::Block) holds beside its bytes. +pub(crate) struct Checked { + pub immutable: bool, + pub sealed_time: bool, + pub gap: Option, +} + +/// Validate a block received as `encoding`, as moq-transport ingress validates a list. +/// +/// Its mutable Timestamp travels beside it, so one inside is malformed, as is an empty +/// block, which is sent as none. +pub(crate) fn check(bytes: &Bytes, encoding: Encoding) -> Result { + if bytes.is_empty() || bytes.len() > MAX_BLOCK { + return Err(Error::MalformedTrack); + } + let parsed = list(bytes, family(encoding), false)?; + if parsed.timestamp.is_some() { + return Err(Error::MalformedTrack); + } + Ok(Checked { + immutable: parsed.immutable, + sealed_time: parsed.sealed_time, + gap: parsed.gap, + }) +} + +/// Every property but the mutable Timestamp, decoded, for tests to inspect. +#[cfg(test)] +pub(crate) fn listed(properties: &Properties) -> Vec { + properties + .block + .as_ref() + .map_or_else(Vec::new, |block| values(block).unwrap()) +} + +/// Decode a block's properties, whose values borrow its bytes. +pub(crate) fn values(block: &crate::model::object::Block) -> Result, Error> { + Ok(list(&block.bytes, family(block.encoding), false)?.values) +} + +pub(crate) fn read(data: &Bytes, version: Version, timescale: Option) -> Result { + let parsed = list(data, version, false)?; + let properties = Properties { + timestamp: parsed.timestamp, + timescale: timescale.filter(|_| parsed.time.is_some()), + sealed_time: parsed.sealed_time, + block: block(&parsed.values, encoding(version), has_delivery_timeout(version))?, + }; let timestamp = match (parsed.time, timescale) { (Some(value), Some(timescale)) => Some(Timestamp::new(value, timescale).map_err(|_| Error::MalformedTrack)?), _ => None, }; Ok(Decoded { - properties: parsed.properties, + properties, timestamp, gap: parsed.gap, }) @@ -152,14 +244,6 @@ pub(crate) fn egress_time(properties: &Properties, timescale: Option) .transpose() } -/// What an Immutable Properties block in the `encoding` family seals. -pub(crate) struct Sealed { - /// It holds a Timestamp. - pub time: bool, - /// Its Prior Object ID Gap, if any. - pub gap: Option, -} - /// A draft that serializes properties in the `encoding` family. Any draft in the family /// parses its keys and integers the same way. pub(super) fn family(encoding: Encoding) -> Version { @@ -171,70 +255,51 @@ pub(super) fn family(encoding: Encoding) -> Version { } } -/// Parse an Immutable Properties block (0x0b) serialized in the `encoding` family. -pub(crate) fn sealed(bytes: &Bytes, encoding: Encoding) -> Result { - let nested = list(bytes, family(encoding), true).map_err(|_| Error::MalformedTrack)?; - Ok(Sealed { - time: nested.time.is_some(), - gap: nested.gap, - }) -} - /// Serialize relayed properties for `version`, with Timestamps in the `timescale` the /// egress declares, if any. -pub(super) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { - if properties - .immutable - .is_some_and(|original| original != encoding(version)) - { - return Err(Error::Unsupported); - } +pub(crate) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { + let target = encoding(version); let timestamp = egress_time(properties, timescale)?; - // Across draft-19, forwarding 0x06 would give it a different meaning. - // A mutable one is dropped; a sealed one is refused. - let flipped = properties.delivery_timeout != has_delivery_timeout(version); - if flipped && sealed_key(properties, version, 0x06)? { - return Err(Error::Unsupported); - } let timestamp = timestamp.map(|value| Property { id: 0x10, value: Value::Int(value), }); - let mut sorted: Vec<_> = properties - .values - .iter() - .filter(|property| property.id != 0x06 || !flipped) - .chain(timestamp.as_ref()) - .collect(); - // Delta keys require ascending order. Equal keys retain the publisher's order. - sorted.sort_by_key(|property| property.id); - let mut out = Vec::new(); - let mut encoder = Encoder::new(&mut out, version.into()); - let mut previous = 0; - for property in sorted { - encoder.varint(match encoding(version) { - Encoding::Absolute => property.id, - Encoding::Delta { .. } | Encoding::DeltaQuic => property.id - previous, - })?; - previous = property.id; - match &property.value { - Value::Int(value) => encoder.varint(*value)?, - Value::Bytes(value) => encoder.bytes(value)?, - } + let Some(block) = &properties.block else { + return serialize(×tamp, target); + }; + if block.immutable && block.encoding != target { + return Err(Error::Unsupported); } - Ok(out) + // Across draft-19, forwarding 0x06 would give it a different meaning. + // A mutable one is dropped; a sealed one is refused. + let flipped = block.delivery_timeout != has_delivery_timeout(version); + // The common case: the block is already what this draft would send. + if timestamp.is_none() && !flipped && block.encoding == target { + return Ok(block.bytes.to_vec()); + } + let values = values(block)?; + if flipped && sealed_key(&values, version, 0x06)? { + return Err(Error::Unsupported); + } + serialize( + values + .iter() + .filter(|property| property.id != 0x06 || !flipped) + .chain(×tamp), + target, + ) } -/// Whether the immutable block holds a property with `id`. -fn sealed_key(properties: &Properties, version: Version, id: u64) -> Result { - let Some(sealed) = properties.values.iter().find(|property| property.id == 0x0b) else { +/// Whether the immutable block among `values` holds a property with `id`. +fn sealed_key(values: &[Property], version: Version, id: u64) -> Result { + let Some(sealed) = values.iter().find(|property| property.id == 0x0b) else { return Ok(false); }; let Value::Bytes(bytes) = &sealed.value else { return Err(Error::MalformedTrack); }; let nested = list(bytes, version, true)?; - Ok(nested.properties.values.iter().any(|property| property.id == id)) + Ok(nested.values.iter().any(|property| property.id == id)) } #[cfg(test)] @@ -304,7 +369,7 @@ mod tests { drop(received); assert!(dropped.load(Ordering::Relaxed)); assert_eq!( - decoded.properties.values[0].value, + listed(&decoded.properties)[0].value, Value::Bytes(Bytes::from_static(&[42])) ); } @@ -344,14 +409,14 @@ mod tests { let again = read(&Bytes::from(written), version, Some(Timescale::MICRO)).unwrap(); let micros = Timestamp::new(42_000, Timescale::MICRO).unwrap(); assert_eq!(again.timestamp, Some(micros), "{version}"); - assert_eq!(again.properties.values.last().unwrap().value, Value::Int(7)); + assert_eq!(listed(&again.properties).last().unwrap().value, Value::Int(7)); // An egress that declares no units drops it, as a plain frame there has none. let written = write(&decoded.properties, version, None).unwrap(); let again = read(&Bytes::from(written), version, None).unwrap(); assert_eq!(again.properties.timestamp, None, "{version}"); - assert_eq!(again.properties.values.len(), 1, "{version}"); - assert_eq!(again.properties.values[0].value, Value::Int(7)); + assert_eq!(listed(&again.properties).len(), 1, "{version}"); + assert_eq!(listed(&again.properties)[0].value, Value::Int(7)); // An untimed ingress forwards it untouched. let untimed = read(&bytes, version, None).unwrap(); assert_eq!(write(&untimed.properties, version, None).unwrap(), bytes); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index ffa9e846335..58b918fdf8b 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -12399,7 +12399,7 @@ mod stitch_tests { let relayed = bytes::Bytes::copy_from_slice(decoder.bytes().unwrap()); let decoded = super::super::object::read(&relayed, version, Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded.timestamp, Some(Timestamp::new(42, Timescale::MILLI).unwrap())); - assert_eq!(decoded.properties.values.len(), 1); + assert_eq!(super::super::object::listed(&decoded.properties).len(), 1); } fn object_stream(version: Version, first: bool, objects: &[(u64, &[u8], Option)]) -> Vec { @@ -12553,7 +12553,9 @@ mod stitch_tests { ); if let Some(end) = end_object { assert_eq!( - end.properties.values.first().map(|property| property.id), + super::super::object::listed(&end.properties) + .first() + .map(|property| property.id), legacy.then_some(0x3e) ); } @@ -12670,7 +12672,10 @@ mod stitch_tests { .unwrap() .unwrap(); assert_eq!(frame.fields.as_ref().unwrap().id, id); - assert_eq!(frame.fields.as_ref().unwrap().properties.values[0].id, 0x3e); + assert_eq!( + super::super::object::listed(&frame.fields.as_ref().unwrap().properties)[0].id, + 0x3e + ); } let tail = object_stream(version, false, &[(9, &[], None)]); diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 37481e8a9d4..2319b85208d 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -17,8 +17,9 @@ use crate::{ use super::{Message, Version}; -/// The largest properties block a peer may make us buffer, as for a moq-transport object. -pub(crate) const MAX_PROPERTIES: usize = 64 * 1024; +/// The largest record body a peer may make us buffer: the largest block moq-transport +/// admits, beside a Flags byte and a Timestamp of at most 9 bytes. +pub(crate) const MAX_PROPERTIES: usize = crate::ietf::object::MAX_BLOCK + 10; // Group State bits. const RELAYED: u64 = 0x1; @@ -32,13 +33,11 @@ const PRIORITY: u64 = 0x4; const DATAGRAM_END: u64 = 0x8; const STATUS: u64 = 0x10; -// Properties Flags: the low bit, then the Immutable Properties encoding above it. +// Flags of a block and of TRACK_PROPERTIES: property 0x06 means SUBGROUP_DELIVERY_TIMEOUT. const DELIVERY_TIMEOUT: u64 = 0x1; -/// Property IDs the model reads. -const TIMESTAMP: u64 = 0x10; +/// Immutable Properties, whose keys TRACK_PROPERTIES derives its sealed list from. const IMMUTABLE: u64 = 0x0b; -const GAP: u64 = 0x3e; /// The Group State a stream sends for its group's `wire` state. /// @@ -122,16 +121,19 @@ fn encode_flags(delivery_timeout: bool, immutable: Option) -> u64 { u64::from(delivery_timeout) | encoding_code(immutable) << 1 } -fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { - let encoding = match flags >> 1 { +fn decode_encoding(code: u64) -> Result, DecodeError> { + Ok(match code { 0 => None, 1 => Some(Encoding::Absolute), 2 => Some(Encoding::DeltaQuic), 3 => Some(Encoding::Delta { seven: false }), 4 => Some(Encoding::Delta { seven: true }), _ => return Err(DecodeError::InvalidValue), - }; - Ok((flags & DELIVERY_TIMEOUT != 0, encoding)) + }) +} + +fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { + Ok((flags & DELIVERY_TIMEOUT != 0, decode_encoding(flags >> 1)?)) } /// Encode each property, with absolute IDs: an even ID has an integer value, an odd one bytes. @@ -147,11 +149,13 @@ fn encode_list<'a>(w: &mut Encoder<'_>, values: impl IntoIterator, max: usize) -> Result, DecodeError> { +/// Decode Track Properties to the end of `r`, in the order they arrived. +/// +/// No more than moq-transport ingress keeps, which is all a relay forwards. +fn decode_list(r: &mut Decoder<'_>) -> Result, DecodeError> { let mut values = Vec::new(); while !r.is_empty() { - if values.len() >= max { + if values.len() as u64 >= crate::ietf::properties::MAX_PROPERTIES { return Err(DecodeError::TooMany); } let id = r.varint()?; @@ -179,26 +183,38 @@ fn immutable(values: &[Property], encoding: Option) -> Result, version: Version, ) -> Result, EncodeError> { let mut out = Vec::new(); - if timestamp.is_none() && properties.values.is_empty() { + let block = properties.block.as_ref(); + if timestamp.is_none() && block.is_none() { return Ok(out); } let w = &mut Encoder::new(&mut out, version.into()); - w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; - let timestamp = timestamp.map(|value| Property { - id: TIMESTAMP, - value: Value::Int(value), + let mut flags = block.map_or(0, |block| { + u64::from(block.delivery_timeout) | encoding_code(Some(block.encoding)) << 2 }); - encode_list(w, timestamp.iter().chain(&properties.values))?; + if timestamp.is_some() { + flags |= TIMESTAMPED; + } + w.varint(flags)?; + if let Some(timestamp) = timestamp { + w.varint(timestamp)?; + } + if let Some(block) = block { + w.slice(&block.bytes); + } Ok(out) } @@ -208,57 +224,46 @@ pub(crate) struct Decoded { pub gap: Option, } -/// Decode an object's properties block body, whose Timestamps are in `timescale`, the -/// units the track declares. +/// Decode an object's record body, whose Timestamps are in `timescale`, the units the +/// track declares. +/// +/// Only the canonical form is accepted, so what decodes re-encodes to the same bytes. pub(crate) fn decode_properties( - block: &[u8], + body: &[u8], timescale: Option, version: Version, ) -> Result { let mut properties = Properties::default(); - if block.is_empty() { + if body.is_empty() { return Ok(Decoded { properties, gap: None }); } - let r = &mut Decoder::new(block, version.into()); - (properties.delivery_timeout, properties.immutable) = decode_flags(r.varint()?)?; - // The block's length bounds them, as for a moq-transport object. - let mut values = decode_list(r, usize::MAX)?; - - let mut timestamps = values.iter().filter(|property| property.id == TIMESTAMP); - properties.timestamp = match timestamps.next() { - Some(Property { - value: Value::Int(value), - .. - }) => Some(*value), - Some(_) => unreachable!("even IDs decode as integers"), - None => None, - }; - if timestamps.next().is_some() { - return Err(DecodeError::Duplicate); + let r = &mut Decoder::new(body, version.into()); + let flags = r.varint()?; + let encoding = decode_encoding(flags >> 2)?; + if flags & TIMESTAMPED != 0 { + properties.timestamp = Some(r.varint()?); } - values.retain(|property| property.id != TIMESTAMP); - - let mut gaps = values.iter().filter_map(|property| match property { - Property { - id: GAP, - value: Value::Int(gap), - } => Some(*gap), - _ => None, - }); - let mut gap = gaps.next(); - if gaps.next().is_some() { - return Err(DecodeError::Duplicate); - } - if let (Some(block), Some(encoding)) = (immutable(&values, properties.immutable)?, properties.immutable) { - let sealed = crate::ietf::object::sealed(block, encoding).map_err(|_| DecodeError::InvalidValue)?; - properties.sealed_time = sealed.time; - if let Some(sealed) = sealed.gap - && gap.replace(sealed).is_some() - { - return Err(DecodeError::Duplicate); + let bytes = &body[body.len() - r.remaining()..]; + let mut gap = None; + match encoding { + Some(encoding) => { + // A small cached block must not pin the reader's larger receive buffer. + let bytes = Bytes::copy_from_slice(bytes); + let checked = crate::ietf::object::check(&bytes, encoding).map_err(|_| DecodeError::InvalidValue)?; + properties.sealed_time = checked.sealed_time; + gap = checked.gap; + properties.block = Some(crate::model::object::Block { + bytes, + encoding, + immutable: checked.immutable, + delivery_timeout: flags & DELIVERY_TIMEOUT != 0, + }); } + // Nothing but a Timestamp: DELIVERY_TIMEOUT describes a block, and an empty body + // is how nothing at all is sent. + None if !bytes.is_empty() || flags != TIMESTAMPED => return Err(DecodeError::InvalidValue), + None => {} } - properties.values = values; stamp(&mut properties, timescale); Ok(Decoded { properties, gap }) } @@ -363,7 +368,8 @@ pub struct TrackProperties(pub Option impl Message for TrackProperties { fn encode_msg(&self, w: &mut Encoder<'_>, _: Version) -> Result<(), EncodeError> { - let Some(properties) = &self.0 else { + // Flags only ever describe values, so none at all is a lone 0. + let Some(properties) = self.0.as_ref().filter(|properties| !properties.values.is_empty()) else { return w.varint(0); }; w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; @@ -371,9 +377,9 @@ impl Message for TrackProperties { } fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { - let (delivery_timeout, encoding) = decode_flags(r.varint()?)?; - // No more than moq-transport ingress keeps, which is all a relay forwards. - let values = decode_list(r, crate::ietf::properties::MAX_PROPERTIES as usize)?; + let flags = r.varint()?; + let (delivery_timeout, encoding) = decode_flags(flags)?; + let values = decode_list(r)?; // TRACK_INFO carries these, so a second copy could only contradict it. if values .iter() @@ -387,7 +393,11 @@ impl Message for TrackProperties { _ => Vec::new(), }; if values.is_empty() { - return Ok(Self(None)); + // Only the canonical form, so what decodes re-encodes to the same bytes. + return match flags { + 0 => Ok(Self(None)), + _ => Err(DecodeError::InvalidValue), + }; } Ok(Self(Some(Arc::new(crate::model::object::TrackProperties { values, @@ -521,52 +531,84 @@ mod tests { for value in [0x10u64, 77, 0x3e - 0x10, 2] { e.varint(value).unwrap(); } + let values = [ + Property { + id: 0x06, + value: Value::Int(5), + }, + Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }, + ]; let properties = Properties { timestamp: Some(1_000), - values: vec![ - Property { - id: 0x06, - value: Value::Int(5), - }, - Property { - id: IMMUTABLE, - value: Value::Bytes(sealed.into()), - }, - ], - immutable: Some(Encoding::DeltaQuic), timescale: Some(Timescale::MILLI), sealed_time: true, - delivery_timeout: true, + block: crate::ietf::object::block(&values, Encoding::DeltaQuic, true).unwrap(), }; - let block = encode_properties(&properties, properties.timestamp, V).unwrap(); - let decoded = decode_properties(&block, Some(Timescale::MILLI), V).unwrap(); + let body = encode_properties(&properties, properties.timestamp, V).unwrap(); + let decoded = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); assert_eq!(decoded.properties, properties); assert_eq!(decoded.gap, Some(2)); - // None at all is an empty block. + // None at all is an empty body, and a Timestamp alone needs no block. assert!(encode_properties(&Properties::default(), None, V).unwrap().is_empty()); let empty = decode_properties(&[], Some(Timescale::MILLI), V).unwrap(); assert_eq!(empty.properties, Properties::default()); + let timed = decode_properties(&[TIMESTAMPED as u8, 7], None, V).unwrap(); + assert_eq!(timed.properties.timestamp, Some(7)); + assert_eq!( + encode_properties(&timed.properties, Some(7), V).unwrap(), + [TIMESTAMPED as u8, 7] + ); } + /// Only the canonical form decodes, so whatever decodes re-encodes to the same bytes. #[test] - fn properties_refuse_a_mismatched_immutable_encoding() { - let properties = Properties { - values: vec![Property { - id: IMMUTABLE, - value: Value::Bytes(Bytes::new()), - }], - ..Default::default() - }; - let block = encode_properties(&properties, None, V).unwrap(); - assert!(decode_properties(&block, None, V).is_err(), "no encoding declared"); + fn properties_refuse_what_is_not_canonical() { + let delta = 4 << 2; + for (body, reason) in [ + (&[0][..], "flags saying nothing"), + (&[DELIVERY_TIMEOUT as u8][..], "DELIVERY_TIMEOUT without a block"), + (&[delta][..], "an encoding with an empty block"), + (&[5 << 2, 0x20, 1][..], "an unknown encoding"), + (&[delta, 0x10, 5][..], "a mutable Timestamp inside the block"), + (&[0, 0x20, 1][..], "a block without an encoding"), + (&[delta, 0x0b, 2, 0x0b, 0][..], "a nested Immutable Properties"), + ] { + assert!(decode_properties(body, None, V).is_err(), "accepted {reason}"); + } + } - let declared = Properties { - immutable: Some(Encoding::Absolute), - ..Default::default() - }; - let block = encode_properties(&declared, Some(1), V).unwrap(); - assert!(decode_properties(&block, None, V).is_err(), "encoding without a block"); + /// The worst case for re-encoding, a full moq-transport list of zero-delta properties + /// after a large first ID, crosses the hop byte for byte and is held at its wire size. + #[test] + fn a_full_block_crosses_at_its_wire_size() { + for version in [crate::ietf::Version::Draft16, crate::ietf::Version::Draft22] { + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + // A Timestamp, then IDs from 2^40 on, each repeated as a two-byte zero delta. + for value in [0x10, 77, (1 << 40) - 0x10, 1] { + e.varint(value).unwrap(); + } + while list.len() + 2 <= crate::ietf::object::MAX_BLOCK { + list.extend([0, 1]); + } + let list = Bytes::from(list); + let decoded = crate::ietf::object::read(&list, version, Some(Timescale::MILLI)).unwrap(); + let properties = decoded.properties; + let block = properties.block.as_ref().unwrap(); + assert!(block.bytes.len() < list.len(), "{version}"); + assert_eq!(properties.heap(), block.bytes.len() as u64, "{version}: decoded state"); + + let body = encode_properties(&properties, properties.timestamp, V).unwrap(); + assert!(body.len() <= MAX_PROPERTIES, "{version}: {} bytes", body.len()); + let received = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); + assert_eq!(received.properties, properties, "{version}"); + let written = crate::ietf::object::write(&received.properties, version, Some(Timescale::MILLI)).unwrap(); + assert_eq!(written, list, "{version}: the hop changed the list"); + } } #[test] @@ -660,6 +702,26 @@ mod tests { assert_eq!(plain, [0]); assert_eq!(decode_datagram(&mut Decoder::new(&plain, V.into()), V).unwrap(), None); } + + /// A retained datagram holds its properties as the bytes they arrived as, not a decoded + /// list many times their size. + #[test] + fn datagram_properties_are_held_at_their_wire_size() { + const COUNT: usize = 500; + let mut block = vec![0x20, 1]; + for _ in 1..COUNT { + block.extend([0, 1]); + } + let mut body = vec![4 << 2]; + body.extend(&block); + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(RELAYED).unwrap(); + w.bytes(&body).unwrap(); + let wire = decode_datagram(&mut Decoder::new(&buf, V.into()), V).unwrap().unwrap(); + assert_eq!(wire.properties.heap(), block.len() as u64); + assert!(wire.properties.heap() < (COUNT * size_of::()) as u64 / 10); + } } /// Peer a relay behind `upstream` over moq-lite 07, the way a cluster does. The client @@ -717,6 +779,8 @@ mod hop_tests { use std::time::Duration; const TIMEOUT: Duration = Duration::from_secs(5); + /// Prior Object ID Gap. + const GAP: u64 = 0x3e; fn ts(millis: u64) -> Timestamp { Timestamp::new(millis, Timescale::MILLI).unwrap() @@ -729,6 +793,11 @@ mod hop_tests { } } + /// The block a draft-22 publisher's `values` arrive as. + fn block(values: &[Property]) -> Option { + crate::ietf::object::block(values, Encoding::Delta { seven: true }, true).unwrap() + } + /// Write a frame carrying relay `fields`, as moq-transport ingress does. fn write(group: &mut group::Producer, millis: u64, fields: Option, payload: &[u8]) { let mut frame = group @@ -816,7 +885,7 @@ mod hop_tests { id: 6, properties: Properties { timestamp: Some(0), - values: vec![property(0x20, 1), property(GAP, 6)], + block: block(&[property(0x20, 1), property(GAP, 6)]), timescale: Some(Timescale::MILLI), ..Default::default() }, @@ -850,7 +919,7 @@ mod hop_tests { id: 9, properties: Properties { timestamp: Some(1), - values: vec![property(GAP, 2)], + block: block(&[property(GAP, 2)]), timescale: Some(Timescale::MILLI), ..Default::default() }, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 4886e4615f3..d5e6824acc9 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1043,8 +1043,8 @@ struct RecordIngest { prior: Option, /// The record of the frame being read: its Object ID and properties block. /// - /// The block stays encoded until the frame is created, so the cache charges its decoded - /// form at once rather than a stalled stream holding it uncharged. + /// It is checked when the frame is created, which charges it to the cache, so a stalled + /// stream holds only the bytes it read. pending: Option<(u64, bytes::Bytes)>, } @@ -2527,16 +2527,16 @@ mod tests { } } - /// A properties block decodes to more heap than its wire bytes, so its decoded form is - /// what the cache charges, as the frame it describes is created. + /// A record's properties stay the bytes they arrived as, which the cache charges, rather + /// than a decoded list costing many times as much. #[moq_clock::test] - async fn ietf_records_charge_their_decoded_properties() { + async fn ietf_records_hold_properties_at_their_wire_size() { const COUNT: u64 = 1000; - // A relayed group's Object 0, whose block holds COUNT two-byte properties (0x20 = 1) - // after its Flags, then an empty frame. - let mut body = vec![0x1, 0, 1 + 2 * COUNT, 0]; - for _ in 0..COUNT { - body.extend([0x20, 1]); + // A relayed group's Object 0, whose draft-18 block holds COUNT two-byte properties + // (0x20 = 1, then zero deltas), then an empty frame. + let mut body = vec![0x1, 0, 1 + 2 * COUNT, 4 << 2, 0x20, 1]; + for _ in 1..COUNT { + body.extend([0, 1]); } body.push(0); let (res, track, pool) = receive_ietf(&body).await; @@ -2544,7 +2544,12 @@ mod tests { let group = track.consume().peek_group(0).unwrap(); assert_eq!(group.frame_count(), 1); let decoded = COUNT * size_of::() as u64; - assert!(pool.used() >= decoded, "{} cached for {decoded} decoded", pool.used()); + assert!( + (2 * COUNT..decoded / 2).contains(&pool.used()), + "{} cached for a {}-byte block", + pool.used(), + 2 * COUNT + ); } /// Receive group 5 starting at 500ms over `version`, on a received timed track whose diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index fa7a9dae0ea..2dffdccae6a 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -26,18 +26,34 @@ pub(crate) struct Property { pub value: Value, } -/// The common timestamp needs no vector allocation; all other properties stay opaque. +/// An object's relay properties. The common Timestamp is a field; every other property +/// stays in its encoded [`Block`]. #[derive(Clone, Debug, Default, PartialEq, Eq)] // private: passthrough pub(crate) struct Properties { pub timestamp: Option, - pub values: Vec, - pub immutable: Option, - /// The units of the Timestamps above, when the track declared any. The cache keeps the - /// track in its own units, so egress converts mutable ones to the units it declares. + /// The units of the Timestamps, when the track declared any. The cache keeps the track + /// in its own units, so egress converts mutable ones to the units it declares. pub timescale: Option, /// The immutable block holds a Timestamp, which keeps its ingress units. pub sealed_time: bool, + /// Every property but the mutable Timestamp, if there are any. + pub block: Option, +} + +/// An object's properties other than its mutable Timestamp, as one encoded list. +/// +/// Kept encoded because a decoded list costs many times its wire size, and a relay holds +/// one per cached object. Egress decodes it only to re-encode for another draft. +#[derive(Clone, Debug, PartialEq, Eq)] +// private: passthrough +pub(crate) struct Block { + /// The properties in ascending ID order, serialized as `encoding` does. Never empty. + pub bytes: Bytes, + /// How `bytes` is serialized: its key and integer encoding. + pub encoding: Encoding, + /// `bytes` holds Immutable Properties (0x0b), serialized as `encoding` does. + pub immutable: bool, /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. pub delivery_timeout: bool, } @@ -45,24 +61,16 @@ pub(crate) struct Properties { impl Properties { #[cfg(feature = "async")] pub fn is_plain(&self) -> bool { - self.values.is_empty() + self.block.is_none() } #[cfg(feature = "async")] pub fn is_empty(&self) -> bool { - self.timestamp.is_none() && self.values.is_empty() + self.timestamp.is_none() && self.block.is_none() } pub fn heap(&self) -> u64 { - (self.values.capacity() * size_of::()) as u64 - + self - .values - .iter() - .map(|property| match &property.value { - Value::Bytes(bytes) => bytes.len() as u64, - Value::Int(_) => 0, - }) - .sum::() + self.block.as_ref().map_or(0, |block| block.bytes.len() as u64) } } From 5fbe5d39079b93ba883ec50f0d445500033f7d4f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 00:24:18 -0700 Subject: [PATCH 09/25] test(ietf): compare every FETCH_OK field across the lite hop Only End of Track and the End Location it sets may differ when a FETCH crosses a moq-lite hop with no live subscription. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 58b918fdf8b..72d3e99e16e 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -12186,7 +12186,22 @@ mod stitch_tests { (Some((direct_ok, direct_rest)), Some((hopped_ok, hopped_rest))) if direct_ok.end_of_track && !hopped_ok.end_of_track => { - assert_eq!(hopped_ok.properties, direct_ok.properties, "{ingress} -> {egress}"); + // Without End of Track, the End Location is the requested end rather than the + // track's, which can only reach further. + assert!( + (hopped_ok.end_location.group, hopped_ok.end_location.object) + >= (direct_ok.end_location.group, direct_ok.end_location.object), + "{ingress} -> {egress}" + ); + assert_eq!( + hopped_ok, + ietf::FetchOk { + end_of_track: false, + end_location: hopped_ok.end_location, + ..direct_ok + }, + "{ingress} -> {egress}: only End of Track and its End Location may differ" + ); assert_eq!( hopped_rest, direct_rest, "{ingress} -> {egress}: the hop changed the objects" From 2426c90ef05eae8d5ac92f4aa4b5bbae4f9fd897 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 00:50:08 -0700 Subject: [PATCH 10/25] fix(lite): relayed records agree with their frame and their Group State A relayed record on a timed track must hold its FRAME's Timestamp as its time, mutable or else sealed, and a relayed datagram its own Timestamp: lite egress sends one and moq-transport egress the other, so a peer could otherwise make them disagree. A record with properties in a group whose Group State clears EXTENSIONS is a protocol violation, as the subgroup it mirrors could carry none. Track Properties no longer hold the sealed keys beside the Immutable Properties block. Egress reads them from the block when needed, so a peer cannot make a relay hold a list several times the block's size. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 9 +++- rs/moq-net/src/ietf/object.rs | 14 +++--- rs/moq-net/src/ietf/properties.rs | 61 ++++++++++++++++++++------ rs/moq-net/src/ietf/publisher.rs | 2 +- rs/moq-net/src/lite/datagram.rs | 33 ++++++++++++++ rs/moq-net/src/lite/ietf.rs | 61 +++++++++++++++++++++----- rs/moq-net/src/lite/subscriber.rs | 72 ++++++++++++++++++++++++++----- rs/moq-net/src/model/object.rs | 25 +++++------ 8 files changed, 218 insertions(+), 59 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index e24737c06bf..081c70e137d 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -87,10 +87,10 @@ A bit field describing the group's relay state, or 0 for a plain group: - `0x1` **RELAYED**: The group is relayed. Every other bit requires it. - `0x2` **FIRST_OBJECT**: The first record is the group's first object, as the FIRST_OBJECT state of a {{moqt}} subgroup. -- `0x4` **EXTENSIONS**: The {{moqt}} subgroup header said its objects carry properties. +- `0x4` **EXTENSIONS**: The {{moqt}} subgroup header said its objects carry properties. Without it, every record's Properties are empty. - `0x8` **END_OF_GROUP**: The stream's end ends the group, as a {{moqt}} subgroup that contains the end of its group. -A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, or a bit without RELAYED. +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, a bit without RELAYED, or a record with Properties when EXTENSIONS is clear. A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream stops before the end of the group, such as at a subscription's end frame. Only subgroup 0 of a {{moqt}} group is carried. @@ -147,6 +147,10 @@ DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that wo The object's mutable Timestamp property (0x10), in the track's Timescale ({{moql}} TRACK_INFO). It MUST be present whenever the object has one, since an absent Timestamp is relayed as absent. +On a timed track, an object's time is its mutable Timestamp, or else the one inside its Immutable Properties. +Non-empty Properties MUST hold the FRAME's Timestamp as that time, or the datagram's for a datagram, since a {{moql}} subscriber reads one and a {{moqt}} subscriber the other. +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on a record that breaks this, and drop such a datagram. + **Property Block**: The rest of the Properties: every other property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. @@ -189,6 +193,7 @@ TRACK_INFO carries what a relay keeps of them, so a second copy could only contr A message that breaks either rule is malformed. The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable. +It SHOULD read them from the value when needed rather than hold them beside it, as a list of IDs can cost several times the value. Track Properties never use the Immutable Properties family of drafts 14 and 15, so a `Flags >> 1` of 1 is malformed here. diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 4340fb8eed7..b2e018883eb 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -54,7 +54,7 @@ struct List { timestamp: Option, time: Option, gap: Option, - sealed_time: bool, + sealed_time: Option, immutable: bool, } @@ -66,7 +66,7 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result timestamp: None, time: None, gap: None, - sealed_time: false, + sealed_time: None, immutable: false, }; let mut previous = 0u64; @@ -101,7 +101,7 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result return Err(Error::MalformedTrack); } let nested = list(&bytes, version, true).map_err(|_| Error::MalformedTrack)?; - result.sealed_time = nested.time.is_some(); + result.sealed_time = nested.time; result.time = result.time.or(nested.time); if let Some(gap) = nested.gap && result.gap.replace(gap).is_some() @@ -161,7 +161,7 @@ pub(crate) fn block( /// What a received [`Block`](crate::model::object::Block) holds beside its bytes. pub(crate) struct Checked { pub immutable: bool, - pub sealed_time: bool, + pub sealed_time: Option, pub gap: Option, } @@ -228,7 +228,7 @@ pub(crate) fn egress_time(properties: &Properties, timescale: Option) (Some(from), Some(to)) if from != to => Some((from, to)), _ => None, }; - if properties.sealed_time && (convert.is_some() || unstamped) { + if properties.sealed_time.is_some() && (convert.is_some() || unstamped) { return Err(Error::Unsupported); } properties @@ -325,7 +325,7 @@ mod tests { ] { let decoded = read(&bytes, version, Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded.timestamp, None, "{version}"); - assert!(!decoded.properties.sealed_time, "{version}"); + assert_eq!(decoded.properties.sealed_time, None, "{version}"); for timescale in [Some(Timescale::MICRO), None] { assert_eq!( write(&decoded.properties, version, timescale).unwrap(), @@ -443,7 +443,7 @@ mod tests { // A sealed one is refused. let sealed = Bytes::from_static(&[0x0b, 2, 0x06, 42]); let decoded = read(&sealed, Version::Draft22, milli).unwrap(); - assert!(!decoded.properties.sealed_time); + assert_eq!(decoded.properties.sealed_time, None); assert_eq!(write(&decoded.properties, Version::Draft22, None).unwrap(), sealed); assert!(matches!( write(&decoded.properties, Version::Draft18, milli), diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index ee3dfb3e691..b055464bbc0 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -132,7 +132,7 @@ impl Properties { let mut properties: Vec<_> = known .iter() - .filter(|property| !self.unknown.sealed.contains(&property.id)) + .filter(|property| !self.unknown.sealed().any(|id| id == property.id)) .chain(&self.unknown.values) .collect(); // Delta types require ascending order. Equal types keep the publisher's order. @@ -215,8 +215,7 @@ impl Properties { { return Err(DecodeError::InvalidValue); } - let sealed = sealed(&mut Decoder::new(value, version.into()), &mut properties, &mut seen)?; - properties.unknown.sealed = sealed; + sealed(&mut Decoder::new(value, version.into()), &mut properties, &mut seen)?; } // A small kept property must not pin the message's larger buffer. properties.unknown.values.push(Property { @@ -275,9 +274,9 @@ pub(crate) fn understood(id: u64) -> bool { ) } -/// The keys a Track Properties' Immutable Properties `block` seals, serialized in the -/// `encoding` family, checking the ones we understand as [`Properties::decode`] does. -pub(crate) fn sealed_ids(block: &[u8], encoding: crate::model::object::Encoding) -> Result, DecodeError> { +/// Check a Track Properties' Immutable Properties `block`, serialized in the `encoding` +/// family, as [`Properties::decode`] does. +pub(crate) fn check_immutable(block: &[u8], encoding: crate::model::object::Encoding) -> Result<(), DecodeError> { // Track Properties start at draft-16, whose families all delta-encode their keys. if encoding == crate::model::object::Encoding::Absolute { return Err(DecodeError::InvalidValue); @@ -290,6 +289,44 @@ pub(crate) fn sealed_ids(block: &[u8], encoding: crate::model::object::Encoding) ) } +impl TrackProperties { + /// The keys inside Immutable Properties, which egress must not restate as mutable. + /// + /// Read from the block each time rather than held as a list, which could be many times + /// its size. Ingress checked the block, so a malformed key cannot occur and ends it. + pub(crate) fn sealed(&self) -> impl Iterator + '_ { + let block = self + .values + .iter() + .find_map(|property| match (property.id, &property.value) { + (IMMUTABLE, Value::Bytes(block)) => Some(block), + _ => None, + }); + let mut r = block + .zip(self.immutable) + .map(|(block, encoding)| Decoder::new(block, super::object::family(encoding).into())); + let mut id: u64 = 0; + std::iter::from_fn(move || { + let r = r.as_mut().filter(|r| !r.is_empty())?; + id = id.checked_add(r.varint().ok()?)?; + match id.is_multiple_of(2) { + true => r.varint().ok().map(drop)?, + false => r.bytes().ok().map(drop)?, + } + Some(id) + }) + } + + /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is + /// one moq-net does not understand: the track must be neither processed nor forwarded. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + pub(crate) fn mandatory(&self) -> bool { + const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; + self.values.iter().any(|property| MANDATORY.contains(&property.id)) + || self.sealed().any(|id| MANDATORY.contains(&id)) + } +} + /// A DYNAMIC_GROUPS value, which is a boolean: anything but 0 or 1 is malformed. pub(super) fn dynamic_groups(value: u64) -> Result { match value { @@ -299,11 +336,10 @@ pub(super) fn dynamic_groups(value: u64) -> Result { } } -/// The keys inside an Immutable Properties value, applying the ones we understand, which -/// the draft makes a processor search too. Its pairs are delta-encoded like the outer +/// Check the keys inside an Immutable Properties value, applying the ones we understand, +/// which the draft makes a processor search too. Its pairs are delta-encoded like the outer /// list, and nesting another Immutable Properties makes the track malformed. -fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) -> Result, DecodeError> { - let mut ids = Vec::new(); +fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) -> Result<(), DecodeError> { let mut id: u64 = 0; while !r.is_empty() { id = id.checked_add(r.varint()?).ok_or(DecodeError::BoundsExceeded)?; @@ -315,9 +351,8 @@ fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) } r.bytes()?; } - ids.push(id); } - Ok(ids) + Ok(()) } #[cfg(test)] @@ -591,7 +626,7 @@ mod tests { let (properties, written) = round_trip(version, &block); assert_eq!(written, block, "{version}"); assert_eq!(properties.unknown.values.len(), 3, "{version}"); - assert_eq!(properties.unknown.sealed, [0x02], "{version}"); + assert!(properties.unknown.sealed().eq([0x02]), "{version}"); assert_eq!( properties.unknown.immutable, Some(super::super::object::encoding(version)), diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index e1d31420dd4..8afd7a2ffbe 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -66,7 +66,7 @@ fn track_properties(info: &track::Info, wanted: bool, version: Version) -> Resul // Across draft-19, forwarding 0x06 would give it a different meaning, as for object // properties. A mutable one is dropped; a sealed one is refused. if !unknown.values.is_empty() && unknown.delivery_timeout != super::object::has_delivery_timeout(version) { - if block && unknown.sealed.contains(&0x06) { + if block && unknown.sealed().any(|id| id == 0x06) { return Err(Error::Unsupported); } unknown.values.retain(|property| property.id != 0x06); diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 711ebc87164..747894a4467 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -96,6 +96,11 @@ impl Datagram { } else { None }; + if let Some(Some(wire)) = &ietf + && !super::ietf::agrees(&wire.properties, timestamp) + { + return Err(DecodeError::InvalidValue); + } // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); @@ -199,6 +204,34 @@ mod test { } } + /// A relayed datagram's properties must hold the Timestamp it carries on a timed track, + /// so lite and moq-transport egress cannot send different times for it. + #[test] + fn relayed_time_must_be_the_datagram_time() { + let dg = |timestamp: u64| Datagram { + subscribe: 1, + sequence: 2, + timestamp: Some(500), + payload: Bytes::from_static(b"x"), + ietf: Some(Some(crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: None, + properties: crate::model::object::Properties { + timestamp: Some(timestamp), + ..Default::default() + }, + })), + }; + let decode = |dg: Datagram| { + let buf = dg.encode_bytes(Version::Lite07).unwrap(); + Datagram::decode(buf, Version::Lite07, true, |_| true) + }; + assert!(decode(dg(500)).is_ok()); + assert!(matches!(decode(dg(499)), Err(DecodeError::InvalidValue))); + } + #[test] fn rejects_old_versions() { let dg = Datagram { diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 2319b85208d..58c9c8cd2b8 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -271,7 +271,15 @@ pub(crate) fn decode_properties( /// Record that `properties` carry their Timestamps in `timescale`, the units the track /// declares, when they carry any. pub(crate) fn stamp(properties: &mut Properties, timescale: Option) { - properties.timescale = timescale.filter(|_| properties.timestamp.is_some() || properties.sealed_time); + properties.timescale = timescale.filter(|_| properties.time().is_some()); +} + +/// Whether relayed `properties` agree with the Timestamp a timed track's `frame` carries. +/// +/// Lite egress sends the frame's and moq-transport egress the properties', so properties +/// that say anything must hold the frame's as their time, mutable or else sealed. +pub(crate) fn agrees(properties: &Properties, frame: Option) -> bool { + frame.is_none() || (properties.block.is_none() && properties.timestamp.is_none()) || properties.time() == frame } /// A group stream's object records on egress, sent before each frame once the extension @@ -387,11 +395,10 @@ impl Message for TrackProperties { { return Err(DecodeError::InvalidValue); } - // The sealed keys are the block's own, so they are parsed rather than trusted. - let sealed = match (immutable(&values, encoding)?, encoding) { - (Some(block), Some(encoding)) => crate::ietf::properties::sealed_ids(block, encoding)?, - _ => Vec::new(), - }; + // Egress reads the sealed keys from the block, so it must be one ingress would keep. + if let (Some(block), Some(encoding)) = (immutable(&values, encoding)?, encoding) { + crate::ietf::properties::check_immutable(block, encoding)?; + } if values.is_empty() { // Only the canonical form, so what decodes re-encodes to the same bytes. return match flags { @@ -402,7 +409,6 @@ impl Message for TrackProperties { Ok(Self(Some(Arc::new(crate::model::object::TrackProperties { values, immutable: encoding, - sealed, delivery_timeout, })))) } @@ -544,7 +550,7 @@ mod tests { let properties = Properties { timestamp: Some(1_000), timescale: Some(Timescale::MILLI), - sealed_time: true, + sealed_time: Some(77), block: crate::ietf::object::block(&values, Encoding::DeltaQuic, true).unwrap(), }; let body = encode_properties(&properties, properties.timestamp, V).unwrap(); @@ -625,7 +631,6 @@ mod tests { }, ], immutable: Some(Encoding::Delta { seven: true }), - sealed: vec![0x02], delivery_timeout: true, }; let msg = TrackProperties(Some(Arc::new(properties.clone()))); @@ -676,13 +681,39 @@ mod tests { .unwrap() .0 .unwrap(); - assert_eq!(decoded.sealed, [0x20, 0x24]); + assert!(decoded.sealed().eq([0x20, 0x24])); assert!( decode(vec![sealed], Some(Encoding::Absolute)).is_err(), "track properties never use absolute keys" ); } + /// Sealed keys are read from the Immutable Properties block, never held beside it as a + /// list that could cost several times the block. + #[test] + fn track_properties_hold_sealed_keys_in_their_block() { + // Nearly as many two-byte keys as a lite message holds: 0x20 = 1, then zero deltas. + let count = 32_000; + let mut sealed = vec![0x20, 1]; + sealed.extend([0, 1].repeat(count - 1)); + let msg = TrackProperties(Some(Arc::new(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + immutable: Some(Encoding::Delta { seven: true }), + delivery_timeout: false, + }))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = >::decode(&mut Decoder::new(&buf, V.into()), V) + .unwrap() + .0 + .unwrap(); + assert_eq!(decoded.values.len(), 1); + assert_eq!(decoded.sealed().count(), count); + assert!(decoded.sealed().all(|id| id == 0x20)); + } + #[test] fn datagram_state_round_trips() { let wire = crate::model::datagram::Wire { @@ -854,7 +885,8 @@ mod hop_tests { /// A relayed group crosses the hop frame by frame while it is still open, with its /// Object IDs, properties, and END_OF_GROUP position, and its track's properties. - /// A side that does not offer the extension gets the plain frames alone. + /// A side that does not offer the extension gets the plain frames alone. The track info + /// moq-transport egress restates as Track Properties crosses either way. #[moq_clock::test] async fn relayed_state_crosses_while_the_group_is_open() { for offer in [[true, true], [true, false], [false, true]] { @@ -862,6 +894,8 @@ mod hop_tests { let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.max_age = Some(Duration::from_secs(7)); + info.priority = 9; let track_properties = crate::model::object::TrackProperties { values: vec![property(0x40, 3)], ..Default::default() @@ -939,6 +973,11 @@ mod hop_tests { assert_eq!(&frame.payload[..], b"b"); assert!(next(&mut received).await.is_none()); let info = moq_clock::timeout(TIMEOUT, copy.query()).await.unwrap().unwrap(); + assert_eq!( + (info.max_age, info.timescale, info.priority), + (Some(Duration::from_secs(7)), Some(Timescale::MILLI), 9), + "{offer:?}" + ); match negotiated { true => { assert_eq!(fields(&frame), Some((second.id, second.properties.clone()))); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d5e6824acc9..ccf5fece7da 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1039,6 +1039,8 @@ struct RecordIngest { /// The Group State carried relay state. Otherwise every record is plain: its Object ID /// is the frame's index, with no properties and no END_OF_GROUP. relayed: bool, + /// The Group State set EXTENSIONS, without which no record has properties. + extensions: bool, /// The previous record's Object ID, `None` before the first. prior: Option, /// The record of the frame being read: its Object ID and properties block. @@ -1125,11 +1127,13 @@ impl FrameIngest { let state = ready!(reader.poll_varint(&mut cx))?; let wire = lite::ietf::decode_state(state, self.frame_start)?; let relayed = wire.is_some(); + let extensions = wire.as_ref().is_some_and(|wire| wire.extensions); if let Some(wire) = wire { group.set_wire(wire)?; } self.records = Some(RecordIngest { relayed, + extensions, prior: None, pending: None, }); @@ -1164,7 +1168,7 @@ impl FrameIngest { let block = ready!(reader.poll_read_exact(&mut cx, len))?; let (id, end) = (*id, *end); let records = self.records.as_mut().expect("the Group State came first"); - if !records.relayed && (end || !block.is_empty()) { + if (end && !records.relayed) || (!block.is_empty() && !records.extensions) { return Poll::Ready(Err(Error::ProtocolViolation)); } if end { @@ -1217,6 +1221,9 @@ impl FrameIngest { let lite::ietf::Decoded { properties, gap } = lite::ietf::decode_properties(&block, self.timescale, self.version)?; group.mark_gap(id, gap)?; + if !lite::ietf::agrees(&properties, timestamp.map(|time| time.value())) { + return Poll::Ready(Err(Error::ProtocolViolation)); + } // Time alone, which the frame header carries already, is plain. let plain = id == group.frame_count() as u64 && properties.is_plain() && properties @@ -2429,10 +2436,13 @@ mod tests { } } - /// Receive group 0 of an untimed track over a lite-07 session that negotiated the + /// Receive group 0 of a track in `timescale` over a lite-07 session that negotiated the /// `ietf` extension, its stream holding `body` after the GROUP header. Also returns the /// cache pool the track charges. - async fn receive_ietf(body: &[u64]) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { + async fn receive_ietf( + timescale: Option, + body: &[u64], + ) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { use crate::transport::poll::Session as _; let version = Version::Lite07; @@ -2473,13 +2483,13 @@ mod tests { ..Default::default() }), "video", - crate::track::Info::default().with_timescale(None), + crate::track::Info::default().with_timescale(timescale), ); subscriber.subscribes.lock().insert( 7, TrackEntry { producer: track.clone(), - timescale: None, + timescale, tail: Default::default(), }, ); @@ -2494,7 +2504,7 @@ mod tests { #[moq_clock::test] async fn ietf_records_frame_a_group() { // A plain group: Group State 0, then frame 0 with an empty record. - let (res, track, _) = receive_ietf(&[0, 0, 0, 1, u64::from(b'x')]).await; + let (res, track, _) = receive_ietf(None, &[0, 0, 0, 1, u64::from(b'x')]).await; res.unwrap(); let mut group = track.consume().peek_group(0).unwrap(); assert_eq!( @@ -2503,7 +2513,7 @@ mod tests { ); // A relayed group starting at Object 4, then END_OF_GROUP at Object 6. - let (res, track, _) = receive_ietf(&[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; + let (res, track, _) = receive_ietf(None, &[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; res.unwrap(); let group = track.consume().peek_group(0).unwrap(); assert_eq!(group.end_object().map(|end| end.id), Some(6)); @@ -2522,11 +2532,53 @@ mod tests { (&[0x1, 1, 0, 0], "a byte after END_OF_GROUP"), (&[0x1, 0, 0], "a stream ending inside a frame"), ] { - let (res, ..) = receive_ietf(body).await; + let (res, ..) = receive_ietf(None, body).await; assert!(res.is_err(), "accepted {reason}"); } } + /// A relayed group's records carry properties only when its Group State sets EXTENSIONS, + /// as the moq-transport subgroup it mirrors could hold none otherwise. + #[moq_clock::test] + async fn ietf_records_need_extensions_for_properties() { + // Object 0 with a draft-18 block holding 0x20 = 1, or with a Timestamp alone. + for record in [&[3, 4 << 2, 0x20, 1][..], &[2, 0x2, 7]] { + for (state, ok) in [(0x1 | 0x4, true), (0x1, false)] { + let mut body = vec![state, 0]; + body.extend(record); + body.push(0); + let (res, ..) = receive_ietf(None, &body).await; + assert_eq!(res.is_ok(), ok, "Group State {state:#x}, record {record:?}"); + } + } + } + + /// On a timed track, a relayed record's time, its mutable Timestamp or else a sealed one, + /// must be its frame's: lite egress sends one and moq-transport egress the other. + #[moq_clock::test] + async fn ietf_records_agree_with_their_frame_time() { + let frame = crate::coding::varint::zigzag(500); + for (record, ok, reason) in [ + (&[0][..], true, "nothing but the frame's"), + (&[3, 0x2, 500], true, "the frame's Timestamp"), + (&[3, 0x2, 499], false, "another Timestamp"), + (&[3, 4 << 2, 0x20, 1], false, "properties without a Timestamp"), + ( + &[5, 0x2 | 4 << 2, 500, 0x20, 1], + true, + "properties and the frame's Timestamp", + ), + (&[6, 4 << 2, 0x0b, 3, 0x10, 500], true, "the frame's Timestamp, sealed"), + (&[6, 4 << 2, 0x0b, 3, 0x10, 499], false, "another Timestamp, sealed"), + ] { + let mut body = vec![0x1 | 0x4, 0]; + body.extend(record); + body.extend([frame, 0]); + let (res, ..) = receive_ietf(Some(Timescale::MILLI), &body).await; + assert_eq!(res.is_ok(), ok, "{reason}: {res:?}"); + } + } + /// A record's properties stay the bytes they arrived as, which the cache charges, rather /// than a decoded list costing many times as much. #[moq_clock::test] @@ -2534,12 +2586,12 @@ mod tests { const COUNT: u64 = 1000; // A relayed group's Object 0, whose draft-18 block holds COUNT two-byte properties // (0x20 = 1, then zero deltas), then an empty frame. - let mut body = vec![0x1, 0, 1 + 2 * COUNT, 4 << 2, 0x20, 1]; + let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4 << 2, 0x20, 1]; for _ in 1..COUNT { body.extend([0, 1]); } body.push(0); - let (res, track, pool) = receive_ietf(&body).await; + let (res, track, pool) = receive_ietf(None, &body).await; res.unwrap(); let group = track.consume().peek_group(0).unwrap(); assert_eq!(group.frame_count(), 1); diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index 2dffdccae6a..a11e0a363fb 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -35,12 +35,20 @@ pub(crate) struct Properties { /// The units of the Timestamps, when the track declared any. The cache keeps the track /// in its own units, so egress converts mutable ones to the units it declares. pub timescale: Option, - /// The immutable block holds a Timestamp, which keeps its ingress units. - pub sealed_time: bool, + /// The Timestamp the immutable block holds, if any, which keeps its ingress units. + pub sealed_time: Option, /// Every property but the mutable Timestamp, if there are any. pub block: Option, } +impl Properties { + /// The object's time as moq-transport ingress takes it: the mutable Timestamp, or else + /// the sealed one. + pub fn time(&self) -> Option { + self.timestamp.or(self.sealed_time) + } +} + /// An object's properties other than its mutable Timestamp, as one encoded list. /// /// Kept encoded because a decoded list costs many times its wire size, and a relay holds @@ -82,23 +90,10 @@ pub(crate) struct TrackProperties { pub values: Vec, /// How the publisher serialized the keys inside Immutable Properties, when present. pub immutable: Option, - /// The keys inside Immutable Properties, which egress must not restate as mutable. - pub sealed: Vec, /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. pub delivery_timeout: bool, } -impl TrackProperties { - /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is - /// one moq-net does not understand: the track must be neither processed nor forwarded. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub fn mandatory(&self) -> bool { - const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; - self.values.iter().any(|property| MANDATORY.contains(&property.id)) - || self.sealed.iter().any(|id| MANDATORY.contains(id)) - } -} - /// Object numbering is separate from the public frame's ordinal in its group. #[derive(Clone, Debug)] // private: passthrough From 8d5d0183d655544b607ffd6b0e20b4b114409aae Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 01:18:36 -0700 Subject: [PATCH 11/25] fix(net): a timed object's time lives only in its frame On a timed track, relayed properties no longer hold the mutable Timestamp. The frame (or datagram) Timestamp is the object's only time, and moq-transport egress restates it as the mutable Timestamp unless the sealed one already says it. This removes the second copy that the lite hop had to keep consistent: the record and datagram Properties lose their TIMESTAMP flag and value, and a mutable Timestamp inside a timed block is malformed. An untimed track has no frame time, so its Timestamp stays in the block as an opaque property. A track whose TRACK_PROPERTIES hold a Mandatory Track Property, mutable or sealed, is refused across the hop with UnsupportedExtension, using the same TrackProperties::mandatory() check as moq-transport ingress. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- drafts/draft-lcurley-moq-ietf.md | 35 ++--- rs/moq-net/src/fuzz.rs | 14 +- rs/moq-net/src/ietf/object.rs | 204 +++++++++++++++++--------- rs/moq-net/src/ietf/properties.rs | 1 - rs/moq-net/src/ietf/publisher.rs | 25 +++- rs/moq-net/src/ietf/subscriber.rs | 8 +- rs/moq-net/src/lite/datagram.rs | 52 ++++--- rs/moq-net/src/lite/ietf.rs | 228 ++++++++++++++++-------------- rs/moq-net/src/lite/publisher.rs | 16 ++- rs/moq-net/src/lite/subscriber.rs | 60 ++++---- rs/moq-net/src/model/object.rs | 36 ++--- rs/moq-net/src/model/track.rs | 2 +- 13 files changed, 386 insertions(+), 297 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index e06b879cd86..00822dc7e91 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -31,7 +31,7 @@ subset drops. What a peer actually observes against this implementation: - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. -- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. +- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. - **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 081c70e137d..491596a1b15 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -113,7 +113,7 @@ Object Record { **Properties**: The object's [properties](#properties), in `Properties Length` bytes. An empty one means the object has none. -A receiver MUST reset the stream if the length exceeds 65,546, the largest Property Block beside a Flags byte and a Timestamp. +A receiver MUST reset the stream if the length exceeds 65,537, the largest Property Block beside a Flags byte. In a plain group, every record has a `Skip` of 0 after the first, whose Object ID is the index of its frame, no properties, and `End` of 0. A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other record in a plain group. @@ -123,41 +123,39 @@ The Object ID is relay state beside it, so a plain subscriber still reads consec # Properties {#properties} -An object's properties: its mutable Timestamp, and every other property as one block in the encoding of the {{moqt}} draft it arrived on. +An object's properties, as one block in the encoding of the {{moqt}} draft it arrived on. A relay forwards the block to a peer of that encoding unchanged, so the block never grows on a hop, and holds it as received rather than as a decoded list many times its size. ~~~ Properties { Flags (i) - [Timestamp (i)] Property Block (..) } ~~~ **Flags**: -- `0x1` **DELIVERY_TIMEOUT**: The publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. It requires a Property Block. -- `0x2` **TIMESTAMP**: The Timestamp follows. -- `Flags >> 2` names the Property Block's encoding: 0 for no block, 1 for drafts 14 and 15 (absolute IDs and QUIC varints), 2 for draft 16 (delta IDs and QUIC varints), 3 for draft 17, and 4 for draft 18 and later. +- `0x1` **DELIVERY_TIMEOUT**: The publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. +- `Flags >> 1` names the Property Block's encoding: 1 for drafts 14 and 15 (absolute IDs and QUIC varints), 2 for draft 16 (delta IDs and QUIC varints), 3 for draft 17, and 4 for draft 18 and later. -A receiver MUST treat any other value as malformed, as it MUST a Flags of 0, which an empty Properties says instead. +A receiver MUST treat any other encoding as malformed, including 0: an empty Properties says the object has none. DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that would read it differently. -**Timestamp**: -The object's mutable Timestamp property (0x10), in the track's Timescale ({{moql}} TRACK_INFO). -It MUST be present whenever the object has one, since an absent Timestamp is relayed as absent. - -On a timed track, an object's time is its mutable Timestamp, or else the one inside its Immutable Properties. -Non-empty Properties MUST hold the FRAME's Timestamp as that time, or the datagram's for a datagram, since a {{moql}} subscriber reads one and a {{moqt}} subscriber the other. -A receiver MUST reset the stream with a PROTOCOL_VIOLATION on a record that breaks this, and drop such a datagram. - **Property Block**: -The rest of the Properties: every other property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. +Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. -It MUST be present exactly when `Flags >> 2` is not 0, MUST NOT be longer than 65,536 bytes, and MUST NOT contain a mutable Timestamp. +It MUST NOT be empty or longer than 65,536 bytes. A receiver MUST treat a block its encoding's drafts would refuse as malformed. Other properties are opaque to this extension. +## Timestamps {#timestamps} +On a timed track, the FRAME's Timestamp, or the datagram's for a datagram, is the object's time, and nothing else carries it. +The Property Block MUST NOT contain a mutable Timestamp (0x10) there; a receiver MUST treat one as malformed. +A relay forwarding the object to {{moqt}} restates the time as the mutable Timestamp, unless a Timestamp inside the Immutable Properties already says it. +A sealed Timestamp is in the track's Timescale ({{moql}} TRACK_INFO), and a relay MUST NOT forward one to a peer of other units, which would change its meaning. + +On an untimed track there is no FRAME Timestamp, so a mutable Timestamp stays in the Property Block as an opaque property. + # Track Stream {#track} When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message after TRACK_INFO. @@ -192,6 +190,9 @@ A message MUST NOT carry more than 64 properties, nor any a relay interprets rat TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. A message that breaks either rule is malformed. +A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. +A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. + The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable. It SHOULD read them from the value when needed rather than hold them beside it, as a list of IDs can cost several times the value. Track Properties never use the Immutable Properties family of drafts 14 and 15, so a `Flags >> 1` of 1 is malformed here. diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 47cb8d0a814..929a8b16452 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -159,8 +159,8 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { }; let mut any = false; for &ietf in ietf { - for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| timed) else { + for timescale in [Some(crate::Timescale::MILLI), None] { + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| timescale) else { continue; }; any = true; @@ -170,7 +170,7 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { }; let echo = - lite::Datagram::decode(first, version, ietf, |_| timed).expect("could not decode our own encoding"); + lite::Datagram::decode(first, version, ietf, |_| timescale).expect("could not decode our own encoding"); assert_eq!(echo, decoded, "datagram did not survive a round trip"); } } @@ -478,9 +478,11 @@ 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, |_| true) - .map(|_| 1) - .unwrap(), + Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, false, |_| { + Some(crate::Timescale::MILLI) + }) + .map(|_| 1) + .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), } } diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index b2e018883eb..c088693ff6d 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -58,7 +58,9 @@ struct List { immutable: bool, } -fn list(data: &Bytes, version: Version, immutable: bool) -> Result { +/// Parse a property list. `lift` takes the mutable Timestamp out of `values`, as a timed +/// track's frame holds it. +fn list(data: &Bytes, version: Version, immutable: bool, lift: bool) -> Result { let keys = encoding(version); let mut decoder = Decoder::new(data, version.into()); let mut result = List { @@ -87,7 +89,9 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result if result.timestamp.replace(value).is_some() { return Err(Error::MalformedTrack); } - continue; + if lift { + continue; + } } Value::Int(value) } else { @@ -100,7 +104,7 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result if immutable || std::mem::replace(&mut result.immutable, true) { return Err(Error::MalformedTrack); } - let nested = list(&bytes, version, true).map_err(|_| Error::MalformedTrack)?; + let nested = list(&bytes, version, true, true).map_err(|_| Error::MalformedTrack)?; result.sealed_time = nested.time; result.time = result.time.or(nested.time); if let Some(gap) = nested.gap @@ -161,30 +165,39 @@ pub(crate) fn block( /// What a received [`Block`](crate::model::object::Block) holds beside its bytes. pub(crate) struct Checked { pub immutable: bool, - pub sealed_time: Option, + pub sealed_time: Option, pub gap: Option, } -/// Validate a block received as `encoding`, as moq-transport ingress validates a list. +/// Validate a block received as `encoding` on a track in `timescale`, as moq-transport +/// ingress validates a list. /// -/// Its mutable Timestamp travels beside it, so one inside is malformed, as is an empty -/// block, which is sent as none. -pub(crate) fn check(bytes: &Bytes, encoding: Encoding) -> Result { +/// A timed track's mutable Timestamp is its frame's, so one inside is malformed, as is an +/// empty block, which is sent as none. +pub(crate) fn check(bytes: &Bytes, encoding: Encoding, timescale: Option) -> Result { if bytes.is_empty() || bytes.len() > MAX_BLOCK { return Err(Error::MalformedTrack); } - let parsed = list(bytes, family(encoding), false)?; - if parsed.timestamp.is_some() { + let parsed = list(bytes, family(encoding), false, timescale.is_some())?; + if timescale.is_some() && parsed.timestamp.is_some() { return Err(Error::MalformedTrack); } Ok(Checked { immutable: parsed.immutable, - sealed_time: parsed.sealed_time, + sealed_time: timed(parsed.sealed_time, timescale)?, gap: parsed.gap, }) } -/// Every property but the mutable Timestamp, decoded, for tests to inspect. +/// A Timestamp `value` in the track's `timescale`, or none on an untimed track. +fn timed(value: Option, timescale: Option) -> Result, Error> { + value + .zip(timescale) + .map(|(value, timescale)| Timestamp::new(value, timescale).map_err(|_| Error::MalformedTrack)) + .transpose() +} + +/// Every property a block holds, decoded, for tests to inspect. #[cfg(test)] pub(crate) fn listed(properties: &Properties) -> Vec { properties @@ -195,51 +208,52 @@ pub(crate) fn listed(properties: &Properties) -> Vec { /// Decode a block's properties, whose values borrow its bytes. pub(crate) fn values(block: &crate::model::object::Block) -> Result, Error> { - Ok(list(&block.bytes, family(block.encoding), false)?.values) + Ok(list(&block.bytes, family(block.encoding), false, false)?.values) } +/// Read an object's property list on a track in `timescale`. A timed track's frame holds +/// the object's time, its mutable Timestamp or else a sealed one, so the block does not. pub(crate) fn read(data: &Bytes, version: Version, timescale: Option) -> Result { - let parsed = list(data, version, false)?; + let parsed = list(data, version, false, timescale.is_some())?; let properties = Properties { - timestamp: parsed.timestamp, - timescale: timescale.filter(|_| parsed.time.is_some()), - sealed_time: parsed.sealed_time, + sealed_time: timed(parsed.sealed_time, timescale)?, block: block(&parsed.values, encoding(version), has_delivery_timeout(version))?, }; - let timestamp = match (parsed.time, timescale) { - (Some(value), Some(timescale)) => Some(Timestamp::new(value, timescale).map_err(|_| Error::MalformedTrack)?), - _ => None, - }; Ok(Decoded { properties, - timestamp, + timestamp: timed(parsed.time, timescale)?, gap: parsed.gap, }) } -/// The mutable Timestamp `properties` carries, in the `timescale` an egress declares. +/// The mutable Timestamp to send for an object whose `frame` holds its time, on a timed +/// track, in the `timescale` an egress declares. /// -/// An untimed ingress forwards its Timestamps as is. A timed one to an egress that -/// declares no units drops them, as a plain frame there carries none. Rewriting or -/// dropping an immutable Timestamp would break it, so that is refused. -pub(crate) fn egress_time(properties: &Properties, timescale: Option) -> Result, Error> { - let unstamped = properties.timescale.is_some() && timescale.is_none(); - let convert = match (properties.timescale, timescale) { - (Some(from), Some(to)) if from != to => Some((from, to)), - _ => None, +/// None when the sealed Timestamp already says it, or when the egress declares no units, +/// as a plain frame there carries none. Rewriting or dropping a sealed Timestamp would +/// break it, so that is refused. +pub(crate) fn egress_time( + properties: &Properties, + frame: Option, + timescale: Option, +) -> Result, Error> { + let Some(frame) = frame else { + return Ok(None); }; - if properties.sealed_time.is_some() && (convert.is_some() || unstamped) { - return Err(Error::Unsupported); + if let Some(sealed) = properties.sealed_time { + if timescale != Some(sealed.scale()) { + return Err(Error::Unsupported); + } + if frame.convert(sealed.scale()).is_ok_and(|frame| frame == sealed) { + return Ok(None); + } } - properties - .timestamp - .filter(|_| !unstamped) - .map(|value| match convert { - Some((from, to)) => Timestamp::new(value, from) - .and_then(|timestamp| timestamp.convert(to)) - .map(|timestamp| timestamp.value()) - .map_err(|_| Error::Unsupported), - None => Ok(value), + timescale + .map(|timescale| { + frame + .convert(timescale) + .map(|time| time.value()) + .map_err(|_| Error::Unsupported) }) .transpose() } @@ -255,11 +269,16 @@ pub(super) fn family(encoding: Encoding) -> Version { } } -/// Serialize relayed properties for `version`, with Timestamps in the `timescale` the -/// egress declares, if any. -pub(crate) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { +/// Serialize relayed properties for `version`, with the `frame`'s time as the mutable +/// Timestamp in the `timescale` the egress declares, if any. +pub(crate) fn write( + properties: &Properties, + frame: Option, + version: Version, + timescale: Option, +) -> Result, Error> { let target = encoding(version); - let timestamp = egress_time(properties, timescale)?; + let timestamp = egress_time(properties, frame, timescale)?; let timestamp = timestamp.map(|value| Property { id: 0x10, value: Value::Int(value), @@ -298,7 +317,7 @@ fn sealed_key(values: &[Property], version: Version, id: u64) -> Result bool { const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; self.values.iter().any(|property| MANDATORY.contains(&property.id)) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 8afd7a2ffbe..2d7d164a7c8 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2079,7 +2079,7 @@ where // timestamp only on drafts that can declare its units. let timescale = timescale.filter(|_| ietf::Properties::sends_timescale(version)); let properties = if let Some(fields) = fields { - let properties = super::object::write(&fields.properties, version, timescale)?; + let properties = super::object::write(&fields.properties, timestamp, version, timescale)?; (!properties.is_empty()).then_some(properties) } else { match timescale { @@ -2466,9 +2466,12 @@ where .info .timescale .filter(|_| ietf::Properties::sends_timescale(self.version)); - let fields = group.frames.iter().filter_map(|frame| frame.fields.as_deref()); - for fields in fields.chain(group.end_object.as_deref()) { - if let Err(err) = super::object::write(&fields.properties, self.version, timescale) { + let frames = group + .frames + .iter() + .filter_map(|frame| Some((frame.fields.as_deref()?, frame.timestamp))); + for (fields, frame) in frames.chain(group.end_object.as_deref().map(|end| (end, None))) { + if let Err(err) = super::object::write(&fields.properties, frame, self.version, timescale) { return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await; } } @@ -4429,7 +4432,12 @@ impl TrackServe { tracing::debug!(sequence, "dropping a datagram status this draft cannot carry"); continue; } - let properties = match super::object::write(&wire.properties, self.version, self.timescale) { + let properties = match super::object::write( + &wire.properties, + datagram.datagram.timestamp, + self.version, + self.timescale, + ) { Ok(properties) => properties, Err(err) => { tracing::debug!(%err, sequence, "dropping a datagram whose properties cannot be forwarded"); @@ -5151,7 +5159,12 @@ fn buffer_object( writer.buffer_varint(object.delta)?; if encoding.extensions { let ext = match object.fields { - Some(fields) => super::object::write(&fields.properties, encoding.version, encoding.timescale)?, + Some(fields) => super::object::write( + &fields.properties, + object.timestamp, + encoding.version, + encoding.timescale, + )?, None => { let mut ext = Vec::new(); if let Some(timescale) = encoding.timescale { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 72d3e99e16e..130cb4ddc17 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4816,9 +4816,7 @@ where return Ok(Fetched::Frame); } let timestamp = object_time(timescale, decoded.timestamp)?; - let plain = id == producer.frame_count() as u64 - && decoded.properties.is_plain() - && decoded.properties.timestamp == timestamp.map(|time| time.value()); + let plain = id == producer.frame_count() as u64 && decoded.properties.is_empty(); let fields = (!plain).then(|| { std::sync::Arc::new(crate::model::object::Fields { id, @@ -5549,9 +5547,7 @@ impl GroupIngest { fn header(&mut self, group: &group::Producer, info: frame::Info) -> Result { let id = self.prior_object.expect("payload follows object ID"); group.mark_gap(self.prior_object.expect("properties follow Object ID"), self.gap)?; - let plain = id == group.frame_count() as u64 - && self.properties.is_plain() - && self.properties.timestamp == info.timestamp.map(|time| time.value()); + let plain = id == group.frame_count() as u64 && self.properties.is_empty(); let fields = (!plain).then(|| { std::sync::Arc::new(crate::model::object::Fields { id, diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 747894a4467..85000547cc9 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -6,6 +6,7 @@ //! the datagram boundary, so unlike a [`super::Message`] there is no inner length prefix. The model //! counterpart is [`crate::Datagram`]. +use crate::Timescale; use bytes::Bytes; use crate::coding::{DecodeError, Decoder, Encode, EncodeError, Encoder}; @@ -68,13 +69,14 @@ impl Encode for Datagram { impl Datagram { /// Decode a whole datagram body. The payload shares `buf` rather than copying it. /// - /// `ietf` says whether the session negotiated the extension, and `timed` whether the - /// track of the given subscribe ID carries a timestamp, which the body itself does not say. + /// `ietf` says whether the session negotiated the extension, and `timescale` gives the + /// units of the track of the given subscribe ID, if it is timed, which the body itself + /// does not say. pub fn decode( buf: Bytes, version: Version, ietf: bool, - timed: impl FnOnce(u64) -> bool, + timescale: impl FnOnce(u64) -> Option, ) -> Result { if !version.has_datagrams() || (ietf && !version.has_ietf()) { return Err(DecodeError::Version); @@ -83,24 +85,20 @@ impl Datagram { let mut r = Decoder::new(&buf, version.into()); let subscribe = r.varint()?; let sequence = r.varint()?; + let timescale = timescale(subscribe); let ietf = ietf - .then(|| super::ietf::decode_datagram(&mut r, version)) + .then(|| super::ietf::decode_datagram(&mut r, timescale, version)) .transpose()?; // A status carries no payload and no time. let status = ietf .as_ref() .and_then(|wire| wire.as_ref()) .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); - let timestamp = if timed(subscribe) && !status { + let timestamp = if timescale.is_some() && !status { Some(r.varint()?) } else { None }; - if let Some(Some(wire)) = &ietf - && !super::ietf::agrees(&wire.properties, timestamp) - { - return Err(DecodeError::InvalidValue); - } // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); @@ -132,7 +130,7 @@ mod test { ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, false, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded, original, "payload has no trailing length prefix"); } @@ -146,7 +144,7 @@ mod test { ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, false, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded, original); } @@ -181,7 +179,7 @@ mod test { assert_eq!(&buf[2..], b"world"); let decoded = Datagram::decode(buf, Version::Lite07, false, |id| { assert_eq!(id, 1); - false + None }) .unwrap(); assert_eq!(decoded, dg); @@ -204,11 +202,11 @@ mod test { } } - /// A relayed datagram's properties must hold the Timestamp it carries on a timed track, - /// so lite and moq-transport egress cannot send different times for it. + /// A timed datagram's Timestamp is its only time: its relayed properties cannot hold a + /// second, mutable one that could disagree. #[test] - fn relayed_time_must_be_the_datagram_time() { - let dg = |timestamp: u64| Datagram { + fn relayed_properties_hold_no_timestamp_on_a_timed_track() { + let dg = |id: u64| Datagram { subscribe: 1, sequence: 2, timestamp: Some(500), @@ -219,17 +217,25 @@ mod test { end_of_group: false, status: None, properties: crate::model::object::Properties { - timestamp: Some(timestamp), + block: crate::ietf::object::block( + &[crate::model::object::Property { + id, + value: crate::model::object::Value::Int(7), + }], + crate::model::object::Encoding::Delta { seven: true }, + true, + ) + .unwrap(), ..Default::default() }, })), }; let decode = |dg: Datagram| { let buf = dg.encode_bytes(Version::Lite07).unwrap(); - Datagram::decode(buf, Version::Lite07, true, |_| true) + Datagram::decode(buf, Version::Lite07, true, |_| Some(Timescale::MILLI)) }; - assert!(decode(dg(500)).is_ok()); - assert!(matches!(decode(dg(499)), Err(DecodeError::InvalidValue))); + assert!(decode(dg(0x20)).is_ok()); + assert!(matches!(decode(dg(0x10)), Err(DecodeError::InvalidValue))); } #[test] @@ -244,7 +250,9 @@ mod test { assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| true), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| Some( + Timescale::MILLI + )), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 58c9c8cd2b8..d0ec5545c0c 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -19,7 +19,7 @@ use super::{Message, Version}; /// The largest record body a peer may make us buffer: the largest block moq-transport /// admits, beside a Flags byte and a Timestamp of at most 9 bytes. -pub(crate) const MAX_PROPERTIES: usize = crate::ietf::object::MAX_BLOCK + 10; +pub(crate) const MAX_PROPERTIES: usize = crate::ietf::object::MAX_BLOCK + 1; // Group State bits. const RELAYED: u64 = 0x1; @@ -183,38 +183,18 @@ fn immutable(values: &[Property], encoding: Option) -> Result, - version: Version, -) -> Result, EncodeError> { +/// The block is sent as it is held. A timed track's mutable Timestamp is the frame's, so +/// it is never sent here. +pub(crate) fn encode_properties(properties: &Properties, version: Version) -> Result, EncodeError> { let mut out = Vec::new(); - let block = properties.block.as_ref(); - if timestamp.is_none() && block.is_none() { + let Some(block) = &properties.block else { return Ok(out); - } + }; let w = &mut Encoder::new(&mut out, version.into()); - let mut flags = block.map_or(0, |block| { - u64::from(block.delivery_timeout) | encoding_code(Some(block.encoding)) << 2 - }); - if timestamp.is_some() { - flags |= TIMESTAMPED; - } - w.varint(flags)?; - if let Some(timestamp) = timestamp { - w.varint(timestamp)?; - } - if let Some(block) = block { - w.slice(&block.bytes); - } + w.varint(encode_flags(block.delivery_timeout, Some(block.encoding)))?; + w.slice(&block.bytes); Ok(out) } @@ -224,8 +204,8 @@ pub(crate) struct Decoded { pub gap: Option, } -/// Decode an object's record body, whose Timestamps are in `timescale`, the units the -/// track declares. +/// Decode an object's record body on a track in `timescale`, the units the track +/// declares, which its sealed Timestamp is in. /// /// Only the canonical form is accepted, so what decodes re-encodes to the same bytes. pub(crate) fn decode_properties( @@ -233,53 +213,31 @@ pub(crate) fn decode_properties( timescale: Option, version: Version, ) -> Result { - let mut properties = Properties::default(); if body.is_empty() { - return Ok(Decoded { properties, gap: None }); + return Ok(Decoded { + properties: Properties::default(), + gap: None, + }); } let r = &mut Decoder::new(body, version.into()); - let flags = r.varint()?; - let encoding = decode_encoding(flags >> 2)?; - if flags & TIMESTAMPED != 0 { - properties.timestamp = Some(r.varint()?); - } - let bytes = &body[body.len() - r.remaining()..]; - let mut gap = None; - match encoding { - Some(encoding) => { - // A small cached block must not pin the reader's larger receive buffer. - let bytes = Bytes::copy_from_slice(bytes); - let checked = crate::ietf::object::check(&bytes, encoding).map_err(|_| DecodeError::InvalidValue)?; - properties.sealed_time = checked.sealed_time; - gap = checked.gap; - properties.block = Some(crate::model::object::Block { + let (delivery_timeout, encoding) = decode_flags(r.varint()?)?; + // An empty body is how nothing at all is sent. + let encoding = encoding.ok_or(DecodeError::InvalidValue)?; + // A small cached block must not pin the reader's larger receive buffer. + let bytes = Bytes::copy_from_slice(&body[body.len() - r.remaining()..]); + let checked = crate::ietf::object::check(&bytes, encoding, timescale).map_err(|_| DecodeError::InvalidValue)?; + Ok(Decoded { + properties: Properties { + sealed_time: checked.sealed_time, + block: Some(crate::model::object::Block { bytes, encoding, immutable: checked.immutable, - delivery_timeout: flags & DELIVERY_TIMEOUT != 0, - }); - } - // Nothing but a Timestamp: DELIVERY_TIMEOUT describes a block, and an empty body - // is how nothing at all is sent. - None if !bytes.is_empty() || flags != TIMESTAMPED => return Err(DecodeError::InvalidValue), - None => {} - } - stamp(&mut properties, timescale); - Ok(Decoded { properties, gap }) -} - -/// Record that `properties` carry their Timestamps in `timescale`, the units the track -/// declares, when they carry any. -pub(crate) fn stamp(properties: &mut Properties, timescale: Option) { - properties.timescale = timescale.filter(|_| properties.time().is_some()); -} - -/// Whether relayed `properties` agree with the Timestamp a timed track's `frame` carries. -/// -/// Lite egress sends the frame's and moq-transport egress the properties', so properties -/// that say anything must hold the frame's as their time, mutable or else sealed. -pub(crate) fn agrees(properties: &Properties, frame: Option) -> bool { - frame.is_none() || (properties.block.is_none() && properties.timestamp.is_none()) || properties.time() == frame + delivery_timeout, + }), + }, + gap: checked.gap, + }) } /// A group stream's object records on egress, sent before each frame once the extension @@ -288,7 +246,7 @@ pub(crate) fn agrees(properties: &Properties, frame: Option) -> bool { pub(crate) struct Records { /// The previous record's Object ID, `None` before the first. prior: Option, - /// The units the track declares, which mutable Timestamps convert to. + /// The units the track declares, which a sealed Timestamp must already be in. timescale: Option, version: Version, } @@ -358,8 +316,15 @@ impl Records { self.prior = Some(id); let block = match fields { Some(fields) => { - let timestamp = crate::ietf::object::egress_time(&fields.properties, self.timescale)?; - encode_properties(&fields.properties, timestamp, self.version)? + // A sealed Timestamp keeps its units, which the receiver reads as the track's. + if fields + .properties + .sealed_time + .is_some_and(|sealed| self.timescale != Some(sealed.scale())) + { + return Err(Error::Unsupported); + } + encode_properties(&fields.properties, self.version)? } None => Vec::new(), }; @@ -444,17 +409,13 @@ pub(crate) fn encode_datagram( if let Some(status) = wire.status { w.varint(status)?; } - w.bytes(&encode_properties( - &wire.properties, - wire.properties.timestamp, - version, - )?) + w.bytes(&encode_properties(&wire.properties, version)?) } -/// Decode a datagram's relay state. Its properties' units are the track's, which the -/// caller [`stamp`]s. +/// Decode a datagram's relay state on a track in `timescale`. pub(crate) fn decode_datagram( r: &mut Decoder<'_>, + timescale: Option, version: Version, ) -> Result, DecodeError> { let state = r.varint()?; @@ -468,7 +429,7 @@ pub(crate) fn decode_datagram( let priority = (state & PRIORITY != 0).then(|| r.u8()).transpose()?; let status = (state & STATUS != 0).then(|| r.varint()).transpose()?; let block = r.bytes()?; - let properties = decode_properties(block, None, version)?.properties; + let properties = decode_properties(block, timescale, version)?.properties; Ok(Some(crate::model::datagram::Wire { object_id, priority, @@ -548,42 +509,45 @@ mod tests { }, ]; let properties = Properties { - timestamp: Some(1_000), - timescale: Some(Timescale::MILLI), - sealed_time: Some(77), + sealed_time: Some(crate::Timestamp::new(77, Timescale::MILLI).unwrap()), block: crate::ietf::object::block(&values, Encoding::DeltaQuic, true).unwrap(), }; - let body = encode_properties(&properties, properties.timestamp, V).unwrap(); + let body = encode_properties(&properties, V).unwrap(); let decoded = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); assert_eq!(decoded.properties, properties); assert_eq!(decoded.gap, Some(2)); - // None at all is an empty body, and a Timestamp alone needs no block. - assert!(encode_properties(&Properties::default(), None, V).unwrap().is_empty()); + // None at all is an empty body. + assert!(encode_properties(&Properties::default(), V).unwrap().is_empty()); let empty = decode_properties(&[], Some(Timescale::MILLI), V).unwrap(); assert_eq!(empty.properties, Properties::default()); - let timed = decode_properties(&[TIMESTAMPED as u8, 7], None, V).unwrap(); - assert_eq!(timed.properties.timestamp, Some(7)); - assert_eq!( - encode_properties(&timed.properties, Some(7), V).unwrap(), - [TIMESTAMPED as u8, 7] - ); + + // An untimed track's Timestamp has no frame to hold it, so it stays in the block. + let untimed = [4 << 1, 0x10, 7]; + let decoded = decode_properties(&untimed, None, V).unwrap(); + assert_eq!(encode_properties(&decoded.properties, V).unwrap(), untimed); } /// Only the canonical form decodes, so whatever decodes re-encodes to the same bytes. #[test] fn properties_refuse_what_is_not_canonical() { - let delta = 4 << 2; + let delta = 4 << 1; for (body, reason) in [ (&[0][..], "flags saying nothing"), (&[DELIVERY_TIMEOUT as u8][..], "DELIVERY_TIMEOUT without a block"), (&[delta][..], "an encoding with an empty block"), - (&[5 << 2, 0x20, 1][..], "an unknown encoding"), - (&[delta, 0x10, 5][..], "a mutable Timestamp inside the block"), + (&[5 << 1, 0x20, 1][..], "an unknown encoding"), + ( + &[delta, 0x10, 5][..], + "a timed track's mutable Timestamp, which its frame holds", + ), (&[0, 0x20, 1][..], "a block without an encoding"), (&[delta, 0x0b, 2, 0x0b, 0][..], "a nested Immutable Properties"), ] { - assert!(decode_properties(body, None, V).is_err(), "accepted {reason}"); + assert!( + decode_properties(body, Some(Timescale::MILLI), V).is_err(), + "accepted {reason}" + ); } } @@ -603,16 +567,18 @@ mod tests { } let list = Bytes::from(list); let decoded = crate::ietf::object::read(&list, version, Some(Timescale::MILLI)).unwrap(); + let frame = decoded.timestamp; let properties = decoded.properties; let block = properties.block.as_ref().unwrap(); assert!(block.bytes.len() < list.len(), "{version}"); assert_eq!(properties.heap(), block.bytes.len() as u64, "{version}: decoded state"); - let body = encode_properties(&properties, properties.timestamp, V).unwrap(); + let body = encode_properties(&properties, V).unwrap(); assert!(body.len() <= MAX_PROPERTIES, "{version}: {} bytes", body.len()); let received = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); assert_eq!(received.properties, properties, "{version}"); - let written = crate::ietf::object::write(&received.properties, version, Some(Timescale::MILLI)).unwrap(); + let written = + crate::ietf::object::write(&received.properties, frame, version, Some(Timescale::MILLI)).unwrap(); assert_eq!(written, list, "{version}: the hop changed the list"); } } @@ -725,13 +691,16 @@ mod tests { }; let mut buf = Vec::new(); encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); - let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).unwrap(); assert_eq!(decoded, Some(wire)); let mut plain = Vec::new(); encode_datagram(&mut Encoder::new(&mut plain, V.into()), None, V).unwrap(); assert_eq!(plain, [0]); - assert_eq!(decode_datagram(&mut Decoder::new(&plain, V.into()), V).unwrap(), None); + assert_eq!( + decode_datagram(&mut Decoder::new(&plain, V.into()), None, V).unwrap(), + None + ); } /// A retained datagram holds its properties as the bytes they arrived as, not a decoded @@ -743,13 +712,15 @@ mod tests { for _ in 1..COUNT { block.extend([0, 1]); } - let mut body = vec![4 << 2]; + let mut body = vec![4 << 1]; body.extend(&block); let mut buf = Vec::new(); let w = &mut Encoder::new(&mut buf, V.into()); w.varint(RELAYED).unwrap(); w.bytes(&body).unwrap(); - let wire = decode_datagram(&mut Decoder::new(&buf, V.into()), V).unwrap().unwrap(); + let wire = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V) + .unwrap() + .unwrap(); assert_eq!(wire.properties.heap(), block.len() as u64); assert!(wire.properties.heap() < (COUNT * size_of::()) as u64 / 10); } @@ -918,9 +889,7 @@ mod hop_tests { let first = crate::model::object::Fields { id: 6, properties: Properties { - timestamp: Some(0), block: block(&[property(0x20, 1), property(GAP, 6)]), - timescale: Some(Timescale::MILLI), ..Default::default() }, }; @@ -952,9 +921,7 @@ mod hop_tests { let second = crate::model::object::Fields { id: 9, properties: Properties { - timestamp: Some(1), block: block(&[property(GAP, 2)]), - timescale: Some(Timescale::MILLI), ..Default::default() }, }; @@ -994,6 +961,51 @@ mod hop_tests { } } + /// A track with a Mandatory Track Property, mutable or sealed, is refused across the hop + /// as moq-transport ingress refuses it: one we do not understand is neither processed + /// nor forwarded. + #[moq_clock::test] + async fn mandatory_track_properties_are_refused() { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x4000).unwrap(); + e.varint(1).unwrap(); + for (values, immutable) in [ + (vec![property(0x4000, 1)], None), + ( + vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + Some(Encoding::Delta { seven: true }), + ), + ] { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.properties = Some(Arc::new(crate::model::object::TrackProperties { + values, + immutable, + ..Default::default() + })); + let _track = broadcast.create_track("video", info).unwrap(); + + let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; + let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + let res = moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(None)) + .await + .expect("no answer"); + assert!( + matches!(res, Err(crate::Error::UnsupportedExtension)), + "{immutable:?}: {:?}", + res.err() + ); + } + } + /// Groups and datagrams from a moq-lite publisher cross a negotiated hop as plain as /// they left: no relay state appears on the way. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index c7667482f2a..7fa2fe3de7c 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -3279,14 +3279,16 @@ impl Subscription { let ietf = match (self.ietf, &datagram.wire) { (false, _) => None, (true, None) => Some(None), - (true, Some(wire)) => { - let mut wire = wire.as_ref().clone(); - let Ok(timestamp) = crate::ietf::object::egress_time(&wire.properties, self.timescale) else { - return false; - }; - wire.properties.timestamp = timestamp; - Some(Some(wire)) + // A sealed Timestamp keeps its units, which the receiver reads as the track's. + (true, Some(wire)) + if wire + .properties + .sealed_time + .is_some_and(|sealed| self.timescale != Some(sealed.scale())) => + { + return false; } + (true, Some(wire)) => Some(Some(wire.as_ref().clone())), }; let sequence = datagram.sequence; let body = lite::Datagram { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index ccf5fece7da..febf3adb5c4 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -512,7 +512,7 @@ impl Subscriber { let mut subscribes = self.subscribes.lock(); // An unknown subscription's datagram is dropped below, however it parses. let dg = lite::Datagram::decode(payload, self.version, ietf, |id| { - subscribes.get(&id).is_some_and(|entry| entry.timescale.is_some()) + subscribes.get(&id).and_then(|entry| entry.timescale) })?; let Some(entry) = subscribes.get_mut(&dg.subscribe) else { // Unknown or already-closed subscription: drop the datagram. @@ -533,10 +533,7 @@ impl Subscriber { // A datagram says where the live feed is as well as a group does. Inserted first, so // the copy goes live with it already showing. let live = entry.producer.is_live(); - let wire = dg.ietf.flatten().map(|mut wire| { - lite::ietf::stamp(&mut wire.properties, entry.timescale); - Arc::new(wire) - }); + let wire = dg.ietf.flatten().map(Arc::new); entry.producer.insert_wire_datagram(crate::model::datagram::Stored { datagram: crate::Datagram { sequence: dg.sequence, @@ -1221,14 +1218,7 @@ impl FrameIngest { let lite::ietf::Decoded { properties, gap } = lite::ietf::decode_properties(&block, self.timescale, self.version)?; group.mark_gap(id, gap)?; - if !lite::ietf::agrees(&properties, timestamp.map(|time| time.value())) { - return Poll::Ready(Err(Error::ProtocolViolation)); - } - // Time alone, which the frame header carries already, is plain. - let plain = id == group.frame_count() as u64 - && properties.is_plain() && properties - .timestamp - .is_none_or(|time| Some(time) == timestamp.map(|time| time.value())); + let plain = id == group.frame_count() as u64 && properties.is_empty(); if !plain && !records.relayed { return Poll::Ready(Err(Error::ProtocolViolation)); } @@ -2541,8 +2531,8 @@ mod tests { /// as the moq-transport subgroup it mirrors could hold none otherwise. #[moq_clock::test] async fn ietf_records_need_extensions_for_properties() { - // Object 0 with a draft-18 block holding 0x20 = 1, or with a Timestamp alone. - for record in [&[3, 4 << 2, 0x20, 1][..], &[2, 0x2, 7]] { + // Object 0 with a draft-18 block holding 0x20 = 1, or an untimed Timestamp. + for record in [&[3, 4 << 1, 0x20, 1][..], &[3, 4 << 1, 0x10, 7]] { for (state, ok) in [(0x1 | 0x4, true), (0x1, false)] { let mut body = vec![state, 0]; body.extend(record); @@ -2553,29 +2543,30 @@ mod tests { } } - /// On a timed track, a relayed record's time, its mutable Timestamp or else a sealed one, - /// must be its frame's: lite egress sends one and moq-transport egress the other. + /// On a timed track, the frame holds an object's time, so a record cannot carry a second, + /// mutable Timestamp that could disagree with it. Records that say nothing of time, or + /// seal a Timestamp moq-transport egress cannot rewrite, cross beside the frame's. #[moq_clock::test] - async fn ietf_records_agree_with_their_frame_time() { + async fn ietf_records_leave_time_to_their_frame() { let frame = crate::coding::varint::zigzag(500); + // Each record after its Object code: Object 0 unless it says otherwise. for (record, ok, reason) in [ - (&[0][..], true, "nothing but the frame's"), - (&[3, 0x2, 500], true, "the frame's Timestamp"), - (&[3, 0x2, 499], false, "another Timestamp"), - (&[3, 4 << 2, 0x20, 1], false, "properties without a Timestamp"), - ( - &[5, 0x2 | 4 << 2, 500, 0x20, 1], - true, - "properties and the frame's Timestamp", - ), - (&[6, 4 << 2, 0x0b, 3, 0x10, 500], true, "the frame's Timestamp, sealed"), - (&[6, 4 << 2, 0x0b, 3, 0x10, 499], false, "another Timestamp, sealed"), + (&[0, 0][..], true, "nothing at all"), + (&[0, 4, 4 << 1, 0x10, 500], false, "a mutable Timestamp"), + (&[0, 3, 4 << 1, 0x20, 1], true, "properties without a Timestamp"), + (&[0, 6, 4 << 1, 0x0b, 3, 0x10, 499], true, "a sealed Timestamp"), + (&[1 << 1, 0], true, "Object 1 without properties"), ] { - let mut body = vec![0x1 | 0x4, 0]; + let mut body = vec![0x1 | 0x4]; body.extend(record); body.extend([frame, 0]); - let (res, ..) = receive_ietf(Some(Timescale::MILLI), &body).await; + let (res, track, _) = receive_ietf(Some(Timescale::MILLI), &body).await; assert_eq!(res.is_ok(), ok, "{reason}: {res:?}"); + if ok { + let mut group = track.consume().peek_group(0).unwrap(); + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.timestamp, Some(Timestamp::from_millis(500).unwrap()), "{reason}"); + } } } @@ -2586,7 +2577,7 @@ mod tests { const COUNT: u64 = 1000; // A relayed group's Object 0, whose draft-18 block holds COUNT two-byte properties // (0x20 = 1, then zero deltas), then an empty frame. - let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4 << 2, 0x20, 1]; + let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4 << 1, 0x20, 1]; for _ in 1..COUNT { body.extend([0, 1]); } @@ -6106,6 +6097,11 @@ impl TrackInfoFetch { return Poll::Ready(Err(crate::lite::error::from_transport(err))); } let properties = ready!(stream.reader.poll_decode::(&mut cx))?; + // Refused as moq-transport ingress refuses it: a track that needs a property + // we do not understand is neither processed nor forwarded. + if properties.0.as_ref().is_some_and(|properties| properties.mandatory()) { + return Poll::Ready(Err(Error::UnsupportedExtension)); + } let TrackInfoState::Properties { stream, mut info } = std::mem::replace(&mut self.state, TrackInfoState::Open) else { diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index a11e0a363fb..fba091a4bdf 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -1,7 +1,7 @@ //! Private relay metadata; public readers see only the frame or datagram payload. use bytes::Bytes; -use crate::Timescale; +use crate::Timestamp; /// How the publisher serialized the keys inside immutable properties. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -26,30 +26,21 @@ pub(crate) struct Property { pub value: Value, } -/// An object's relay properties. The common Timestamp is a field; every other property -/// stays in its encoded [`Block`]. +/// An object's relay properties, held as one encoded [`Block`]. +/// +/// On a timed track, the mutable Timestamp is never held: it is the frame's, which egress +/// restates. On an untimed one it has no units, so it stays in the block like any other. #[derive(Clone, Debug, Default, PartialEq, Eq)] // private: passthrough pub(crate) struct Properties { - pub timestamp: Option, - /// The units of the Timestamps, when the track declared any. The cache keeps the track - /// in its own units, so egress converts mutable ones to the units it declares. - pub timescale: Option, - /// The Timestamp the immutable block holds, if any, which keeps its ingress units. - pub sealed_time: Option, - /// Every property but the mutable Timestamp, if there are any. + /// The Timestamp the block's Immutable Properties hold on a timed track, which keeps + /// its ingress units. + pub sealed_time: Option, + /// The properties, if there are any. pub block: Option, } -impl Properties { - /// The object's time as moq-transport ingress takes it: the mutable Timestamp, or else - /// the sealed one. - pub fn time(&self) -> Option { - self.timestamp.or(self.sealed_time) - } -} - -/// An object's properties other than its mutable Timestamp, as one encoded list. +/// An object's properties, but for a timed track's mutable Timestamp, as one encoded list. /// /// Kept encoded because a decoded list costs many times its wire size, and a relay holds /// one per cached object. Egress decodes it only to re-encode for another draft. @@ -67,14 +58,9 @@ pub(crate) struct Block { } impl Properties { - #[cfg(feature = "async")] - pub fn is_plain(&self) -> bool { - self.block.is_none() - } - #[cfg(feature = "async")] pub fn is_empty(&self) -> bool { - self.timestamp.is_none() && self.block.is_none() + self.block.is_none() } pub fn heap(&self) -> u64 { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c2050314c7b..02395669b36 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7189,7 +7189,7 @@ mod test { .unwrap(); // Subscriber decodes the body and writes it downstream, preserving the sequence. - let wire = lite::Datagram::decode(body, version, false, |_| true).unwrap(); + let wire = lite::Datagram::decode(body, version, false, |_| Some(crate::Timescale::MICRO)).unwrap(); let mut downstream = track_producer("test", Info::timed()); let mut downstream_dg = downstream.subscribe(None); downstream From 69c9fd794868815cc933a8893019f8ffe8144cda Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 01:38:36 -0700 Subject: [PATCH 12/25] fix(net): reserve egress headroom at ingress for relayed properties A relay adds to what it forwards: the five Track Properties it restates from the track's info, and on a timed track the frame's Timestamp. Both ingress paths, moq-transport and the lite hop, now refuse what would overflow once egress adds them, instead of sending something the receiver rejects. TrackProperties::refused() is the one check every ingress runs: a Mandatory Track Property, or more than MAX_FORWARDED (59) properties, refuses the track. A timed object's block is bounded by object::max_block(), which leaves room for the largest Timestamp any draft encodes. A block re-encoded for a draft with wider varints that no longer fits is refused at egress. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 4 ++ rs/moq-net/src/ietf/object.rs | 83 +++++++++++++++++++++++++++++-- rs/moq-net/src/ietf/properties.rs | 73 ++++++++++++++++++++++++--- rs/moq-net/src/ietf/subscriber.rs | 14 ++++-- rs/moq-net/src/lite/ietf.rs | 63 ++++++++++++++++------- rs/moq-net/src/lite/subscriber.rs | 7 ++- 6 files changed, 206 insertions(+), 38 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 491596a1b15..913f688b83c 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -145,6 +145,8 @@ DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that wo Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. It MUST NOT be empty or longer than 65,536 bytes. +On a timed track it MUST NOT be longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. +A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits. A receiver MUST treat a block its encoding's drafts would refuse as malformed. Other properties are opaque to this extension. @@ -190,6 +192,8 @@ A message MUST NOT carry more than 64 properties, nor any a relay interprets rat TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. A message that breaks either rule is malformed. +A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 properties, and it refuses a track with more, from a {{moqt}} publisher or over this extension, as unsupported. + A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index c088693ff6d..3594aea6659 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -48,6 +48,28 @@ pub(crate) struct Decoded { /// The largest properties block an object may carry, which a relay forwards unchanged. pub(crate) const MAX_BLOCK: usize = super::group::MAX_OBJECT_EXTENSIONS; +/// The largest block a relay holds for an object on a track in `timescale`. +/// +/// On a timed track, egress adds the frame's Timestamp to the block, so the block leaves +/// room for the largest one any draft encodes. Refusing a larger block on ingress keeps +/// every egress within [`MAX_BLOCK`]. +pub(crate) fn max_block(timescale: Option) -> usize { + if timescale.is_none() { + return MAX_BLOCK; + } + // A Timestamp's value is a QUIC varint at most, and its key, a delta of at most 0x10, + // only shrinks the key of the property after it. + let largest = [Version::Draft14, Version::Draft16, Version::Draft17, Version::Draft18] + .into_iter() + .map(|version| { + let form = version.into(); + crate::coding::varint::size(0x10, form).unwrap() + crate::coding::varint::size((1 << 62) - 1, form).unwrap() + }) + .max() + .unwrap(); + MAX_BLOCK - largest +} + struct List { /// In arrival order, without the mutable Timestamp. Values borrow the input. values: Vec, @@ -175,7 +197,7 @@ pub(crate) struct Checked { /// A timed track's mutable Timestamp is its frame's, so one inside is malformed, as is an /// empty block, which is sent as none. pub(crate) fn check(bytes: &Bytes, encoding: Encoding, timescale: Option) -> Result { - if bytes.is_empty() || bytes.len() > MAX_BLOCK { + if bytes.is_empty() || bytes.len() > max_block(timescale) { return Err(Error::MalformedTrack); } let parsed = list(bytes, family(encoding), false, timescale.is_some())?; @@ -219,6 +241,10 @@ pub(crate) fn read(data: &Bytes, version: Version, timescale: Option) sealed_time: timed(parsed.sealed_time, timescale)?, block: block(&parsed.values, encoding(version), has_delivery_timeout(version))?, }; + // A list at the limit with a small Timestamp cannot take back a larger one on egress. + if properties.heap() > max_block(timescale) as u64 { + return Err(Error::Unsupported); + } Ok(Decoded { properties, timestamp: timed(parsed.time, timescale)?, @@ -300,13 +326,19 @@ pub(crate) fn write( if flipped && sealed_key(&values, version, 0x06)? { return Err(Error::Unsupported); } - serialize( + let out = serialize( values .iter() .filter(|property| property.id != 0x06 || !flipped) .chain(×tamp), target, - ) + )?; + // Ingress leaves room for the Timestamp, but another draft's varints can be wider, so a + // block re-encoded for it may not fit: refused, as the receiver would refuse it. + if out.len() > MAX_BLOCK { + return Err(Error::Unsupported); + } + Ok(out) } /// Whether the immutable block among `values` holds a property with `id`. @@ -482,6 +514,51 @@ mod tests { ); } + /// A timed block leaves room for the Timestamp egress restates from the frame, so even + /// the largest one leaves within [`MAX_BLOCK`]. A byte more is refused at ingress. + #[test] + fn a_timed_block_leaves_room_for_its_timestamp() { + let milli = Some(Timescale::MILLI); + let limit = max_block(milli); + assert_eq!(limit, MAX_BLOCK - 10, "a one-byte key and a nine-byte value"); + // A draft-22 block of `len` bytes: 0x20 = 1 and zero deltas, one value taking two + // bytes for an odd length. Its list adds a Timestamp in front. + let block = |len: usize| { + let mut block = vec![0x20, 1]; + if len % 2 == 1 { + block.extend([0, 0x80, 0xc8]); + } + while block.len() < len { + block.extend([0, 1]); + } + assert_eq!(block.len(), len); + Bytes::from(block) + }; + let list = |len: usize| { + let mut list = vec![0x10, 1, 0x10]; + list.extend(&block(len)[1..]); + Bytes::from(list) + }; + let decoded = read(&list(limit), Version::Draft22, milli).unwrap(); + assert_eq!(decoded.properties.heap(), limit as u64); + let latest = Timestamp::new((1 << 62) - 1, Timescale::MILLI).unwrap(); + let written = write(&decoded.properties, Some(latest), Version::Draft22, milli).unwrap(); + assert_eq!(written.len(), MAX_BLOCK); + + assert!(matches!( + read(&list(limit + 1), Version::Draft22, milli), + Err(Error::Unsupported) + )); + // An untimed track has no Timestamp to restate, so its block may fill the limit. + assert!(read(&list(MAX_BLOCK - 2), Version::Draft22, None).is_ok()); + + // The same bound on a block arriving over the lite hop. + let encoding = Encoding::Delta { seven: true }; + assert!(check(&block(limit), encoding, milli).is_ok()); + assert!(check(&block(limit + 1), encoding, milli).is_err()); + assert!(check(&block(limit + 1), encoding, None).is_ok()); + } + /// Draft-19 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so it cannot cross that boundary. #[test] fn key_six_follows_its_draft() { diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index ac327d17503..bbe7df7da76 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -265,15 +265,25 @@ impl Properties { } } -/// Whether moq-net applies the Track Property `id` itself, so a relay restates it from the -/// track's info rather than forwarding the publisher's. +/// The Track Properties moq-net applies itself, which a relay restates from the track's +/// info rather than forwarding the publisher's. +const UNDERSTOOD: [u64; 5] = [ + MAX_CACHE_DURATION, + TIMESCALE, + DEFAULT_PUBLISHER_PRIORITY, + DEFAULT_PUBLISHER_GROUP_ORDER, + DYNAMIC_GROUPS, +]; + +/// Whether moq-net applies the Track Property `id` itself. pub(crate) fn understood(id: u64) -> bool { - matches!( - id, - MAX_CACHE_DURATION | TIMESCALE | DEFAULT_PUBLISHER_PRIORITY | DEFAULT_PUBLISHER_GROUP_ORDER | DYNAMIC_GROUPS - ) + UNDERSTOOD.contains(&id) } +/// The most Track Properties a relay forwards, leaving room for every one it restates +/// within the [`MAX_PROPERTIES`] a message may carry. +pub(crate) const MAX_FORWARDED: usize = MAX_PROPERTIES as usize - UNDERSTOOD.len(); + /// Check a Track Properties' Immutable Properties `block`, serialized in the `encoding` /// family, as [`Properties::decode`] does. pub(crate) fn check_immutable(block: &[u8], encoding: crate::model::object::Encoding) -> Result<(), DecodeError> { @@ -317,9 +327,22 @@ impl TrackProperties { }) } + /// Why a track carrying these is neither processed nor forwarded, if it is not: every + /// ingress, moq-transport or a relay hop, refuses it here. + pub(crate) fn refused(&self) -> Option { + if self.mandatory() { + return Some(crate::Error::UnsupportedExtension); + } + // Egress could not restate the track's info beside them without overflowing. + if self.values.len() > MAX_FORWARDED { + return Some(crate::Error::Unsupported); + } + None + } + /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is /// one moq-net does not understand: the track must be neither processed nor forwarded. - pub(crate) fn mandatory(&self) -> bool { + fn mandatory(&self) -> bool { const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; self.values.iter().any(|property| MANDATORY.contains(&property.id)) || self.sealed().any(|id| MANDATORY.contains(&id)) @@ -688,6 +711,42 @@ mod tests { )); } + /// A relay forwards only as many properties as leave room for every one it restates, so + /// what it sends always decodes. One more is refused at ingress. + #[test] + fn forwarded_properties_leave_room_for_the_restated() { + let unknown = |count: usize| TrackProperties { + values: (0..count as u64) + .map(|i| Property { + id: 0x40 + 2 * i, + value: Value::Int(1), + }) + .collect(), + immutable: None, + // Draft-22 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT. + delivery_timeout: true, + }; + let properties = Properties { + max_cache_duration: Some(Duration::from_secs(1)), + timescale: Some(Timescale::MILLI), + priority: Some(1), + group_order: Some(GroupOrder::Descending), + dynamic_groups: true, + unknown: unknown(MAX_FORWARDED), + }; + assert!(properties.unknown.refused().is_none()); + let mut buf = Vec::new(); + properties + .encode(&mut Encoder::new(&mut buf, Version::Draft22.into()), Version::Draft22) + .unwrap(); + assert_eq!(decode_draft22(&buf).unwrap(), properties); + + assert!(matches!( + unknown(MAX_FORWARDED + 1).refused(), + Some(crate::Error::Unsupported) + )); + } + /// 0x4000-0x7FFF are Mandatory Track Properties, mutable or sealed. #[test] fn mandatory_properties_are_found() { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 130cb4ddc17..e3816a744f3 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2946,10 +2946,11 @@ where // SUBSCRIBE_OK commits the model's immutable metadata before the alias releases // any data stream that arrived ahead of this control response. let accepted = match response { - // A track that needs a property we do not understand is neither processed nor - // forwarded: the subscription is cancelled and the subscribers refused. - Ok(Some(accepted)) if accepted.properties.unknown.mandatory() => { - let err = Error::UnsupportedExtension; + // A track that needs a property we do not understand, or carries more than we + // could forward, is neither processed nor forwarded: the subscription is + // cancelled and the subscribers refused. + Ok(Some(accepted)) if accepted.properties.unknown.refused().is_some() => { + let err = accepted.properties.unknown.refused().expect("checked by the guard"); tracing::debug!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, %err, "subscribe refused"); // Refuse before waiting on the peer to acknowledge the cancellation. if let Some(pending) = self.take_pending(request_id) { @@ -3847,7 +3848,10 @@ where let _ = stream.writer.finish(); let ok = match response { // A track that needs a property we do not understand is not forwarded. - Ok(ok) if ok.properties.unknown.mandatory() => Err(Error::UnsupportedExtension), + Ok(ok) => match ok.properties.unknown.refused() { + Some(err) => Err(err), + None => Ok(ok), + }, res => res, }; let ok = match ok { diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index d0ec5545c0c..9d2eb26975c 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -18,7 +18,7 @@ use crate::{ use super::{Message, Version}; /// The largest record body a peer may make us buffer: the largest block moq-transport -/// admits, beside a Flags byte and a Timestamp of at most 9 bytes. +/// admits, beside a Flags byte. pub(crate) const MAX_PROPERTIES: usize = crate::ietf::object::MAX_BLOCK + 1; // Group State bits. @@ -562,7 +562,8 @@ mod tests { for value in [0x10, 77, (1 << 40) - 0x10, 1] { e.varint(value).unwrap(); } - while list.len() + 2 <= crate::ietf::object::MAX_BLOCK { + // The largest a timed track's block may be, once its Timestamp leaves it. + while list.len() <= crate::ietf::object::max_block(Some(Timescale::MILLI)) { list.extend([0, 1]); } let list = Bytes::from(list); @@ -961,6 +962,25 @@ mod hop_tests { } } + /// Subscribe across a negotiated hop to a track carrying `properties`. + async fn subscribe_across(properties: crate::model::object::TrackProperties) -> Result<(), crate::Error> { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.properties = Some(Arc::new(properties)); + let _track = broadcast.create_track("video", info).unwrap(); + + let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; + let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(None)) + .await + .expect("no answer") + .map(drop) + } + /// A track with a Mandatory Track Property, mutable or sealed, is refused across the hop /// as moq-transport ingress refuses it: one we do not understand is neither processed /// nor forwarded. @@ -980,32 +1000,37 @@ mod hop_tests { Some(Encoding::Delta { seven: true }), ), ] { - let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); - let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); - let mut info = track::Info::timed().with_timescale(Timescale::MILLI); - info.properties = Some(Arc::new(crate::model::object::TrackProperties { + let res = subscribe_across(crate::model::object::TrackProperties { values, immutable, ..Default::default() - })); - let _track = broadcast.create_track("video", info).unwrap(); - - let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; - let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) - .await - .expect("no broadcast") - .unwrap(); - let res = moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(None)) - .await - .expect("no answer"); + }) + .await; assert!( matches!(res, Err(crate::Error::UnsupportedExtension)), - "{immutable:?}: {:?}", - res.err() + "{immutable:?}: {res:?}" ); } } + /// A relay forwards only as many Track Properties as leave room for the ones it + /// restates from TRACK_INFO, so one more is refused across the hop. + #[moq_clock::test] + async fn forwarded_track_properties_leave_room_for_track_info() { + let max = crate::ietf::properties::MAX_FORWARDED; + for (count, ok) in [(max, true), (max + 1, false)] { + let res = subscribe_across(crate::model::object::TrackProperties { + values: (0..count as u64).map(|i| property(0x40 + 2 * i, 1)).collect(), + ..Default::default() + }) + .await; + match ok { + true => assert!(res.is_ok(), "{count}: {res:?}"), + false => assert!(matches!(res, Err(crate::Error::Unsupported)), "{count}: {res:?}"), + } + } + } + /// Groups and datagrams from a moq-lite publisher cross a negotiated hop as plain as /// they left: no relay state appears on the way. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index febf3adb5c4..d524b9ad38f 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6097,10 +6097,9 @@ impl TrackInfoFetch { return Poll::Ready(Err(crate::lite::error::from_transport(err))); } let properties = ready!(stream.reader.poll_decode::(&mut cx))?; - // Refused as moq-transport ingress refuses it: a track that needs a property - // we do not understand is neither processed nor forwarded. - if properties.0.as_ref().is_some_and(|properties| properties.mandatory()) { - return Poll::Ready(Err(Error::UnsupportedExtension)); + // Refused as moq-transport ingress refuses it. + if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused()) { + return Poll::Ready(Err(err)); } let TrackInfoState::Properties { stream, mut info } = std::mem::replace(&mut self.state, TrackInfoState::Open) From d3d62971d24dd18dfb36857f2a106e8df4ddb57b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 02:05:11 -0700 Subject: [PATCH 13/25] fix(lite): track properties cross in the encoding they arrived in TRACK_PROPERTIES wrote every ID absolutely, so a moq-transport list of repeated large IDs (one-byte zero deltas) grew by up to eight bytes per property and could overflow a lite message, aborting the TRACK stream. The list now crosses delta-encoded in the publisher's family, which Flags names, so a hop never widens it. The model holds that family for the whole list, not only the Immutable block. Dropping the understood properties can still widen the delta that spans them by a byte or two, so ingress refuses a list that would not fit, failing early. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 25 +-- rs/moq-net/src/ietf/object.rs | 2 +- rs/moq-net/src/ietf/properties.rs | 44 ++--- rs/moq-net/src/ietf/publisher.rs | 6 +- rs/moq-net/src/ietf/subscriber.rs | 2 +- rs/moq-net/src/lite/ietf.rs | 267 +++++++++++++++++++++--------- rs/moq-net/src/model/object.rs | 10 +- 7 files changed, 232 insertions(+), 124 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 913f688b83c..e696301a3c8 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -166,40 +166,33 @@ When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message TRACK_PROPERTIES Message { Message Length (i) Flags (i) - Property (..) ... + Property List (..) } ~~~ **Flags**: Bit `0x1` is DELIVERY_TIMEOUT, as in [Properties](#properties). -`Flags >> 1` names how the publisher serialized its Immutable Properties (0x0b), with the codes of [Properties](#properties), or 0 for none. -A message without properties MUST have a Flags of 0. +`Flags >> 1` names the Property List's encoding, with the codes of [Properties](#properties). +A message without properties MUST have a Flags of 0 and an empty Property List. +Track Properties start at draft 16, so any other message with an encoding of 0 or 1 is malformed. -**Property**: -The {{moqt}} Track Properties a relay forwards without interpreting, in arrival order, each with its absolute ID. -An even ID has an integer Value, and an odd ID a length-prefixed one. -Immutable Properties are forwarded as the publisher's bytes, and there MUST be exactly one when `Flags >> 1` is not 0, and none otherwise. - -~~~ -Property { - ID (i) - [Value (i)] - [Length (i), Value (..)] -} -~~~ +**Property List**: +The {{moqt}} Track Properties a relay forwards without interpreting, serialized as the publisher's draft serializes them: in ascending ID order, with delta-encoded IDs and the varints of that encoding. +A relay keeps the publisher's encoding, so a repeated ID still costs a one-byte delta and the list never grows on a hop. +Immutable Properties (0x0b), at most one, are forwarded as the publisher's bytes, in the same encoding. A message MUST NOT carry more than 64 properties, nor any a relay interprets rather than forwards: MAX_CACHE_DURATION (0x04), TIMESCALE (0x08), DEFAULT_PUBLISHER_PRIORITY (0x0e), DEFAULT_PUBLISHER_GROUP_ORDER (0x22), and DYNAMIC_GROUPS (0x30). TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. A message that breaks either rule is malformed. A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 properties, and it refuses a track with more, from a {{moqt}} publisher or over this extension, as unsupported. +Dropping those five can widen the delta that spans them, so a relay also refuses a {{moqt}} track whose remaining list would not fit a TRACK_PROPERTIES message, as unsupported. A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable. It SHOULD read them from the value when needed rather than hold them beside it, as a list of IDs can cost several times the value. -Track Properties never use the Immutable Properties family of drafts 14 and 15, so a `Flags >> 1` of 1 is malformed here. # Datagrams {#datagrams} diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 3594aea6659..d57661bcd11 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -286,7 +286,7 @@ pub(crate) fn egress_time( /// A draft that serializes properties in the `encoding` family. Any draft in the family /// parses its keys and integers the same way. -pub(super) fn family(encoding: Encoding) -> Version { +pub(crate) fn family(encoding: Encoding) -> Version { match encoding { Encoding::Absolute => Version::Draft14, Encoding::DeltaQuic => Version::Draft16, diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index bbe7df7da76..f62b94229ae 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -207,12 +207,7 @@ impl Properties { let value = r.slice(len)?; if abs == IMMUTABLE { // A second block would leave the sealed list ambiguous. - if properties - .unknown - .immutable - .replace(super::object::encoding(version)) - .is_some() - { + if properties.unknown.immutable().is_some() { return Err(DecodeError::InvalidValue); } sealed(&mut Decoder::new(value, version.into()), &mut properties, &mut seen)?; @@ -225,9 +220,10 @@ impl Properties { } } - // Recorded only beside a value it describes, so a set with nothing to forward stays empty. - properties.unknown.delivery_timeout = - !properties.unknown.values.is_empty() && super::object::has_delivery_timeout(version); + // Recorded only beside a value they describe, so a set with nothing to forward stays empty. + let forwarded = !properties.unknown.values.is_empty(); + properties.unknown.encoding = forwarded.then(|| super::object::encoding(version)); + properties.unknown.delivery_timeout = forwarded && super::object::has_delivery_timeout(version); Ok(properties) } @@ -300,20 +296,24 @@ pub(crate) fn check_immutable(block: &[u8], encoding: crate::model::object::Enco } impl TrackProperties { + /// The Immutable Properties block, serialized as [`Self::encoding`] says. + pub(crate) fn immutable(&self) -> Option<&Bytes> { + self.values + .iter() + .find_map(|property| match (property.id, &property.value) { + (IMMUTABLE, Value::Bytes(block)) => Some(block), + _ => None, + }) + } + /// The keys inside Immutable Properties, which egress must not restate as mutable. /// /// Read from the block each time rather than held as a list, which could be many times /// its size. Ingress checked the block, so a malformed key cannot occur and ends it. pub(crate) fn sealed(&self) -> impl Iterator + '_ { - let block = self - .values - .iter() - .find_map(|property| match (property.id, &property.value) { - (IMMUTABLE, Value::Bytes(block)) => Some(block), - _ => None, - }); - let mut r = block - .zip(self.immutable) + let mut r = self + .immutable() + .zip(self.encoding) .map(|(block, encoding)| Decoder::new(block, super::object::family(encoding).into())); let mut id: u64 = 0; std::iter::from_fn(move || { @@ -337,6 +337,10 @@ impl TrackProperties { if self.values.len() > MAX_FORWARDED { return Some(crate::Error::Unsupported); } + // Nor could a relay hop carry them in one message. + if !crate::lite::ietf::fits(self) { + return Some(crate::Error::Unsupported); + } None } @@ -650,7 +654,7 @@ mod tests { assert_eq!(properties.unknown.values.len(), 3, "{version}"); assert!(properties.unknown.sealed().eq([0x02]), "{version}"); assert_eq!( - properties.unknown.immutable, + properties.unknown.encoding, Some(super::super::object::encoding(version)), "{version}" ); @@ -722,7 +726,7 @@ mod tests { value: Value::Int(1), }) .collect(), - immutable: None, + encoding: Some(crate::model::object::Encoding::Delta { seven: true }), // Draft-22 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT. delivery_timeout: true, }; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 2d7d164a7c8..543ef0fed63 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -56,11 +56,7 @@ fn track_properties(info: &track::Info, wanted: bool, version: Version) -> Resul } let mut unknown = info.properties.as_deref().cloned().unwrap_or_default(); let block = !matches!(version, Version::Draft14 | Version::Draft15); - if block - && unknown - .immutable - .is_some_and(|ingress| ingress != super::object::encoding(version)) - { + if block && unknown.immutable().is_some() && unknown.encoding != Some(super::object::encoding(version)) { return Err(Error::Unsupported); } // Across draft-19, forwarding 0x06 would give it a different meaning, as for object diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index e3816a744f3..a0f4395fd8a 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -15937,7 +15937,7 @@ mod track_property_tests { .clone() .expect("the properties were dropped"); assert_eq!(properties.values, unknown, "{version}"); - assert_eq!(properties.immutable, None, "{version}"); + assert!(properties.immutable().is_none(), "{version}"); } } diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 9d2eb26975c..ef11a867897 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -136,29 +136,54 @@ fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { Ok((flags & DELIVERY_TIMEOUT != 0, decode_encoding(flags >> 1)?)) } -/// Encode each property, with absolute IDs: an even ID has an integer value, an odd one bytes. -fn encode_list<'a>(w: &mut Encoder<'_>, values: impl IntoIterator) -> Result<(), EncodeError> { - for property in values { - w.varint(property.id)?; +/// Track Properties delta-encoded in the family they arrived in, as moq-transport sent +/// them less the properties TRACK_INFO carries, so the list is never wider than it arrived. +/// +/// An even ID has an integer value, an odd one bytes. +fn encode_list(properties: &crate::model::object::TrackProperties) -> Result, EncodeError> { + let mut out = Vec::new(); + let Some(encoding) = properties.encoding else { + return match properties.values.is_empty() { + true => Ok(out), + false => Err(EncodeError::InvalidState), + }; + }; + let w = &mut Encoder::new(&mut out, crate::ietf::object::family(encoding).into()); + let mut prior = 0; + for property in &properties.values { + w.varint(property.id.checked_sub(prior).ok_or(EncodeError::InvalidState)?)?; + prior = property.id; match (&property.value, property.id % 2) { (Value::Int(value), 0) => w.varint(*value)?, (Value::Bytes(value), 1) => w.bytes(value)?, _ => return Err(EncodeError::InvalidState), } } - Ok(()) + Ok(out) } -/// Decode Track Properties to the end of `r`, in the order they arrived. +/// Whether TRACK_PROPERTIES can carry `properties` across a hop. +/// +/// Dropping the understood properties can widen the delta that spans them, so a list that +/// fit its moq-transport message may still not fit, though only by a byte or two. +pub(crate) fn fits(properties: &crate::model::object::TrackProperties) -> bool { + // The Flags beside it are one byte. + encode_list(properties).is_ok_and(|list| list.len() < super::message::MAX_MESSAGE_SIZE) +} + +/// Decode Track Properties to the end of `r`, delta-encoded in the `encoding` family. /// /// No more than moq-transport ingress keeps, which is all a relay forwards. -fn decode_list(r: &mut Decoder<'_>) -> Result, DecodeError> { - let mut values = Vec::new(); +fn decode_list(r: &mut Decoder<'_>, encoding: Encoding) -> Result, DecodeError> { + let r = &mut Decoder::new(r.rest(), crate::ietf::object::family(encoding).into()); + let mut values: Vec = Vec::new(); + let mut prior = 0u64; while !r.is_empty() { if values.len() as u64 >= crate::ietf::properties::MAX_PROPERTIES { return Err(DecodeError::TooMany); } - let id = r.varint()?; + let id = prior.checked_add(r.varint()?).ok_or(DecodeError::BoundsExceeded)?; + prior = id; let value = match id % 2 { 0 => Value::Int(r.varint()?), // A small cached property must not pin the reader's larger receive buffer. @@ -169,20 +194,6 @@ fn decode_list(r: &mut Decoder<'_>) -> Result, DecodeError> { Ok(values) } -/// Check the one Immutable Properties block against the encoding the flags declare. -fn immutable(values: &[Property], encoding: Option) -> Result, DecodeError> { - let mut sealed = values.iter().filter(|property| property.id == IMMUTABLE); - let block = match sealed.next().map(|property| &property.value) { - Some(Value::Bytes(bytes)) => Some(bytes), - Some(Value::Int(_)) => unreachable!("odd IDs decode as bytes"), - None => None, - }; - if sealed.next().is_some() || block.is_some() != encoding.is_some() { - return Err(DecodeError::InvalidValue); - } - Ok(block) -} - /// Encode an object's properties as a record body, empty when it has none. /// /// The block is sent as it is held. A timed track's mutable Timestamp is the frame's, so @@ -345,37 +356,51 @@ impl Message for TrackProperties { let Some(properties) = self.0.as_ref().filter(|properties| !properties.values.is_empty()) else { return w.varint(0); }; - w.varint(encode_flags(properties.delivery_timeout, properties.immutable))?; - encode_list(w, &properties.values) + w.varint(encode_flags(properties.delivery_timeout, properties.encoding))?; + w.slice(&encode_list(properties)?); + Ok(()) } fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { let flags = r.varint()?; + if r.is_empty() { + // Only the canonical form, so what decodes re-encodes to the same bytes. + return match flags { + 0 => Ok(Self(None)), + _ => Err(DecodeError::InvalidValue), + }; + } let (delivery_timeout, encoding) = decode_flags(flags)?; - let values = decode_list(r)?; + // Track Properties start at draft-16, whose families all delta-encode their keys. + let encoding = encoding + .filter(|encoding| *encoding != Encoding::Absolute) + .ok_or(DecodeError::InvalidValue)?; + let properties = crate::model::object::TrackProperties { + values: decode_list(r, encoding)?, + encoding: Some(encoding), + delivery_timeout, + }; // TRACK_INFO carries these, so a second copy could only contradict it. - if values + if properties + .values .iter() .any(|property| crate::ietf::properties::understood(property.id)) { return Err(DecodeError::InvalidValue); } - // Egress reads the sealed keys from the block, so it must be one ingress would keep. - if let (Some(block), Some(encoding)) = (immutable(&values, encoding)?, encoding) { - crate::ietf::properties::check_immutable(block, encoding)?; + // Egress reads the sealed keys from the block, so it must be the one ingress would keep. + if properties + .values + .iter() + .filter(|property| property.id == IMMUTABLE) + .count() > 1 + { + return Err(DecodeError::InvalidValue); } - if values.is_empty() { - // Only the canonical form, so what decodes re-encodes to the same bytes. - return match flags { - 0 => Ok(Self(None)), - _ => Err(DecodeError::InvalidValue), - }; + if let Some(block) = properties.immutable() { + crate::ietf::properties::check_immutable(block, encoding)?; } - Ok(Self(Some(Arc::new(crate::model::object::TrackProperties { - values, - immutable: encoding, - delivery_timeout, - })))) + Ok(Self(Some(Arc::new(properties)))) } } @@ -588,16 +613,16 @@ mod tests { fn track_properties_round_trip() { let properties = crate::model::object::TrackProperties { values: vec![ - Property { - id: 0x41, - value: Value::Bytes(Bytes::from_static(b"opaque")), - }, Property { id: IMMUTABLE, value: Value::Bytes(Bytes::from_static(&[0x02, 0x01])), }, + Property { + id: 0x41, + value: Value::Bytes(Bytes::from_static(b"opaque")), + }, ], - immutable: Some(Encoding::Delta { seven: true }), + encoding: Some(Encoding::Delta { seven: true }), delivery_timeout: true, }; let msg = TrackProperties(Some(Arc::new(properties.clone()))); @@ -616,42 +641,48 @@ mod tests { /// restate what TRACK_INFO carries, or claim sealed keys its block does not hold. #[test] fn track_properties_refuse_what_ingress_would_not_keep() { - let decode = |values: Vec, immutable: Option| { - let msg = TrackProperties(Some(Arc::new(crate::model::object::TrackProperties { - values, - immutable, + let wire = |values: &[Property], code: u64| { + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(code << 1).unwrap(); + let list = encode_list(&crate::model::object::TrackProperties { + values: values.to_vec(), + encoding: Some(Encoding::Delta { seven: true }), ..Default::default() - }))); - let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); - >::decode(&mut Decoder::new(&buf, V.into()), V) + }) + .unwrap(); + w.slice(&list); + buf }; + let decode = |buf: &[u8]| TrackProperties::decode_msg(&mut Decoder::new(buf, V.into()), V); let opaque = |id| Property { id, value: Value::Int(1), }; let max = crate::ietf::properties::MAX_PROPERTIES; - assert!(decode((0..max).map(|i| opaque(0x40 + 2 * i)).collect(), None).is_ok()); + let list: Vec<_> = (0..=max).map(|i| opaque(0x40 + 2 * i)).collect(); + assert!(decode(&wire(&list[..max as usize], 4)).is_ok()); + assert!(decode(&wire(&list, 4)).is_err(), "more than ingress keeps"); + // TIMESCALE belongs to TRACK_INFO. + assert!(decode(&wire(&[opaque(0x08)], 4)).is_err(), "an understood property"); + assert!(decode(&wire(&[opaque(0x40)], 0)).is_err(), "a list needs its encoding"); + assert!(decode(&[1 << 1]).is_err(), "flags without a list"); assert!( - decode((0..=max).map(|i| opaque(0x40 + 2 * i)).collect(), None).is_err(), - "more than ingress keeps" + decode(&wire(&[opaque(0x40)], 1)).is_err(), + "track properties never use absolute keys" ); - // TIMESCALE belongs to TRACK_INFO. - assert!(decode(vec![opaque(0x08)], None).is_err(), "an understood property"); // The sealed keys come from the block, never the sender. let sealed = Property { id: IMMUTABLE, value: Value::Bytes(Bytes::from_static(&[0x20, 0x01, 0x04, 0x05])), }; - let decoded = decode(vec![sealed.clone()], Some(Encoding::Delta { seven: true })) - .unwrap() - .0 - .unwrap(); + let decoded = decode(&wire(std::slice::from_ref(&sealed), 4)).unwrap().0.unwrap(); assert!(decoded.sealed().eq([0x20, 0x24])); assert!( - decode(vec![sealed], Some(Encoding::Absolute)).is_err(), - "track properties never use absolute keys" + decode(&wire(&[sealed.clone(), sealed], 4)).is_err(), + "a second block leaves the sealed keys ambiguous" ); } @@ -668,7 +699,7 @@ mod tests { id: IMMUTABLE, value: Value::Bytes(sealed.into()), }], - immutable: Some(Encoding::Delta { seven: true }), + encoding: Some(Encoding::Delta { seven: true }), delivery_timeout: false, }))); let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); @@ -681,6 +712,89 @@ mod tests { assert!(decoded.sealed().all(|id| id == 0x20)); } + /// Track Properties cross in the delta encoding moq-transport sent, where a repeated ID + /// is a one-byte zero. Written with absolute IDs, a list that filled its moq-transport + /// message would no longer fit a lite one. + #[test] + fn track_properties_cross_at_their_wire_size() { + for version in [ + crate::ietf::Version::Draft16, + crate::ietf::Version::Draft17, + crate::ietf::Version::Draft22, + ] { + // As many repeats of an ID from 2^60 as moq-transport forwards, then one value + // that fills the rest of a lite message beside its Flags. + let id = (1 << 60) + 1; + let repeats = crate::ietf::properties::MAX_FORWARDED - 1; + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + e.varint(id).unwrap(); + e.bytes(&[]).unwrap(); + for _ in 1..repeats { + e.varint(0).unwrap(); + e.bytes(&[]).unwrap(); + } + let rest = super::super::message::MAX_MESSAGE_SIZE - 1 - list.len() - 1; + let fill = (1..=8) + .map(|prefix| rest - prefix) + .find(|fill| { + crate::coding::varint::size(*fill as u64, version.into()).is_ok_and(|size| size == rest - fill) + }) + .unwrap(); + let e = &mut Encoder::new(&mut list, version.into()); + e.varint(0).unwrap(); + e.bytes(&vec![0; fill]).unwrap(); + assert_eq!(list.len(), super::super::message::MAX_MESSAGE_SIZE - 1, "{version}"); + + let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); + assert_eq!(ingress.unknown.values.len(), repeats + 1, "{version}"); + assert!(ingress.unknown.refused().is_none(), "{version}"); + + let msg = TrackProperties(Some(Arc::new(ingress.unknown.clone()))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = + >::decode(&mut Decoder::new(&buf, V.into()), V) + .unwrap(); + assert_eq!(decoded.0.as_deref(), Some(&ingress.unknown), "{version}"); + + let mut written = Vec::new(); + let egress = crate::ietf::Properties { + unknown: decoded.0.unwrap().as_ref().clone(), + ..Default::default() + }; + egress + .encode(&mut Encoder::new(&mut written, version.into()), version) + .unwrap(); + assert_eq!(written, list, "{version}: the hop changed the list"); + } + } + + /// Dropping an understood property can widen the delta that spans it, so a list that + /// could not cross is refused where it arrives rather than where it would be sent. + #[test] + fn track_properties_that_cannot_cross_are_refused_at_ingress() { + let version = crate::ietf::Version::Draft16; + // The most a draft-16 answer holds beside a Request ID and an empty parameter count. + let size = super::super::message::MAX_MESSAGE_SIZE - 2; + // DYNAMIC_GROUPS, then the last ID whose delta from it fits four bytes. + let id = 0x30 + (1 << 30) - 1; + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + for value in [0x30, 1, id - 0x30] { + e.varint(value).unwrap(); + } + let fill = size - list.len() - 4; + let e = &mut Encoder::new(&mut list, version.into()); + e.bytes(&vec![0; fill]).unwrap(); + assert_eq!(list.len(), size); + + // The delta from zero takes eight bytes once DYNAMIC_GROUPS leaves the list. + let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); + assert!(ingress.dynamic_groups); + assert!(!fits(&ingress.unknown)); + assert!(matches!(ingress.unknown.refused(), Some(crate::Error::Unsupported))); + } + #[test] fn datagram_state_round_trips() { let wire = crate::model::datagram::Wire { @@ -870,6 +984,7 @@ mod hop_tests { info.priority = 9; let track_properties = crate::model::object::TrackProperties { values: vec![property(0x40, 3)], + encoding: Some(Encoding::Delta { seven: true }), ..Default::default() }; info.properties = Some(Arc::new(track_properties.clone())); @@ -990,25 +1105,22 @@ mod hop_tests { let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); e.varint(0x4000).unwrap(); e.varint(1).unwrap(); - for (values, immutable) in [ - (vec![property(0x4000, 1)], None), - ( - vec![Property { - id: IMMUTABLE, - value: Value::Bytes(sealed.into()), - }], - Some(Encoding::Delta { seven: true }), - ), + for values in [ + vec![property(0x4000, 1)], + vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], ] { let res = subscribe_across(crate::model::object::TrackProperties { - values, - immutable, + values: values.clone(), + encoding: Some(Encoding::Delta { seven: true }), ..Default::default() }) .await; assert!( matches!(res, Err(crate::Error::UnsupportedExtension)), - "{immutable:?}: {res:?}" + "{values:?}: {res:?}" ); } } @@ -1021,6 +1133,7 @@ mod hop_tests { for (count, ok) in [(max, true), (max + 1, false)] { let res = subscribe_across(crate::model::object::TrackProperties { values: (0..count as u64).map(|i| property(0x40 + 2 * i, 1)).collect(), + encoding: Some(Encoding::Delta { seven: true }), ..Default::default() }) .await; diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index fba091a4bdf..97a2da0eeb6 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -3,7 +3,7 @@ use bytes::Bytes; use crate::Timestamp; -/// How the publisher serialized the keys inside immutable properties. +/// How the publisher serialized a list of properties: its key and integer encoding. #[derive(Clone, Copy, Debug, PartialEq, Eq)] // private: passthrough pub(crate) enum Encoding { @@ -72,10 +72,12 @@ impl Properties { #[derive(Clone, Debug, Default, PartialEq, Eq)] // private: passthrough pub(crate) struct TrackProperties { - /// In arrival order, with Immutable Properties (0x0b) as its serialized bytes. + /// In arrival order, which is ascending, with Immutable Properties (0x0b) as its + /// serialized bytes. pub values: Vec, - /// How the publisher serialized the keys inside Immutable Properties, when present. - pub immutable: Option, + /// How the publisher serialized the list and the keys inside Immutable Properties. + /// Set beside any values, and never [`Encoding::Absolute`], which predates the list. + pub encoding: Option, /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. pub delivery_timeout: bool, } From aba8f9ba923de1f41247cc40e8ed2893a56e202a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 02:19:32 -0700 Subject: [PATCH 14/25] fix(net): a sealed understood property must match the track info Egress forwards a property sealed inside Immutable Properties in place of restating the track info the relay acts on, so a sealed TIMESCALE (or any of the five understood properties) that disagreed would reach downstream subscribers while the relay timed frames by another value. The shared TrackProperties::refused() now takes the track info and refuses a track whose sealed understood value differs from what the relay restates, at moq-transport ingress and across a lite hop alike. The restated values come from one Properties::restated(), which egress uses too, so the check and the restatement cannot drift. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 4 + rs/moq-net/src/ietf/properties.rs | 137 ++++++++++++++++++++++++++++-- rs/moq-net/src/ietf/publisher.rs | 10 +-- rs/moq-net/src/ietf/subscriber.rs | 39 ++++++++- rs/moq-net/src/lite/ietf.rs | 35 +++++++- rs/moq-net/src/lite/subscriber.rs | 4 +- 6 files changed, 209 insertions(+), 20 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index e696301a3c8..db07632889e 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -188,6 +188,10 @@ A message that breaks either rule is malformed. A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 properties, and it refuses a track with more, from a {{moqt}} publisher or over this extension, as unsupported. Dropping those five can widen the delta that spans them, so a relay also refuses a {{moqt}} track whose remaining list would not fit a TRACK_PROPERTIES message, as unsupported. +The Immutable Properties may still hold one of those five, which a relay forwards in place of the one it would restate. +A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, DEFAULT_PUBLISHER_GROUP_ORDER descending, the order a relay serves, and DYNAMIC_GROUPS whether the track takes a new group request. +A relay refuses a track whose sealed value differs, from a {{moqt}} publisher or over this extension, as unsupported. + A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index f62b94229ae..277482103fc 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -88,6 +88,21 @@ impl Properties { !matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) } + /// The properties a relay states for a track it serves, from the `info` it acts on. + /// + /// We serve the newest group first by default, matching moq-lite. + pub(crate) fn restated(info: &crate::track::Info) -> Self { + Self { + max_cache_duration: info.max_age, + timescale: info.timescale, + priority: Some(super::priority::to_wire(info.priority)), + group_order: Some(GroupOrder::Descending), + // A track opted in to refresh answers a NEW_GROUP_REQUEST as a join. + dynamic_groups: info.refresh.is_some(), + unknown: TrackProperties::default(), + } + } + /// Write the block, which is the final field of the message: no count and no length, /// so the caller must not append anything after it. /// @@ -327,12 +342,16 @@ impl TrackProperties { }) } - /// Why a track carrying these is neither processed nor forwarded, if it is not: every - /// ingress, moq-transport or a relay hop, refuses it here. - pub(crate) fn refused(&self) -> Option { + /// Why a track carrying these beside `info` is neither processed nor forwarded, if it + /// is not: every ingress, moq-transport or a relay hop, refuses it here. + pub(crate) fn refused(&self, info: &crate::track::Info) -> Option { if self.mandatory() { return Some(crate::Error::UnsupportedExtension); } + // Egress forwards a sealed value in place of restating `info`, so the two must agree. + if self.contradicts(&Properties::restated(info)) { + return Some(crate::Error::Unsupported); + } // Egress could not restate the track's info beside them without overflowing. if self.values.len() > MAX_FORWARDED { return Some(crate::Error::Unsupported); @@ -344,6 +363,29 @@ impl TrackProperties { None } + /// Whether Immutable Properties seal a property we understand at another value than + /// the `restated` one the relay acts on. + fn contradicts(&self, restated: &Properties) -> bool { + let Some((block, encoding)) = self.immutable().zip(self.encoding) else { + return false; + }; + let mut sealed = Properties::default(); + let mut seen = Vec::new(); + let r = &mut Decoder::new(block, super::object::family(encoding).into()); + // Ingress checked the block, so a malformed one cannot occur and is refused. + if self::sealed(r, &mut sealed, &mut seen).is_err() { + return true; + } + seen.into_iter().any(|id| match id { + MAX_CACHE_DURATION => sealed.max_cache_duration != restated.max_cache_duration, + TIMESCALE => sealed.timescale != restated.timescale, + DEFAULT_PUBLISHER_PRIORITY => sealed.priority != restated.priority, + DEFAULT_PUBLISHER_GROUP_ORDER => sealed.group_order != restated.group_order, + DYNAMIC_GROUPS => sealed.dynamic_groups != restated.dynamic_groups, + _ => unreachable!("only the understood properties are seen"), + }) + } + /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is /// one moq-net does not understand: the track must be neither processed nor forwarded. fn mandatory(&self) -> bool { @@ -738,7 +780,7 @@ mod tests { dynamic_groups: true, unknown: unknown(MAX_FORWARDED), }; - assert!(properties.unknown.refused().is_none()); + assert!(properties.unknown.refused(&crate::track::Info::default()).is_none()); let mut buf = Vec::new(); properties .encode(&mut Encoder::new(&mut buf, Version::Draft22.into()), Version::Draft22) @@ -746,11 +788,96 @@ mod tests { assert_eq!(decode_draft22(&buf).unwrap(), properties); assert!(matches!( - unknown(MAX_FORWARDED + 1).refused(), + unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default()), + Some(crate::Error::Unsupported) + )); + } + + /// Why a track whose publisher sealed `value` as the understood property `id` is + /// refused beside an info that restates 7s, 1000 Hz, priority 9, Descending, and + /// DYNAMIC_GROUPS. + fn seal(id: u64, value: u64) -> Option { + let version = Version::Draft22; + let mut block = Vec::new(); + let w = &mut Encoder::new(&mut block, version.into()); + w.varint(id).unwrap(); + w.varint(value).unwrap(); + let unknown = TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(block.into()), + }], + encoding: Some(super::super::object::encoding(version)), + delivery_timeout: true, + }; + let info = crate::track::Info::default() + .with_max_age(Duration::from_secs(7)) + .with_timescale(Timescale::MILLI) + .with_priority(9) + .with_refresh(0); + unknown.refused(&info) + } + + /// A sealed value of a property the relay restates must be the one it acts on, since + /// egress forwards the sealed one in its place. + #[test] + fn a_sealed_max_cache_duration_matches_the_track() { + assert!(seal(MAX_CACHE_DURATION, 7000).is_none()); + assert!(matches!( + seal(MAX_CACHE_DURATION, 7001), Some(crate::Error::Unsupported) )); } + #[test] + fn a_sealed_timescale_matches_the_track() { + assert!(seal(TIMESCALE, 1000).is_none()); + assert!(matches!(seal(TIMESCALE, 900), Some(crate::Error::Unsupported))); + // Zero declares no timeline, which contradicts one. + assert!(matches!(seal(TIMESCALE, 0), Some(crate::Error::Unsupported))); + } + + #[test] + fn a_sealed_priority_matches_the_track() { + let wire = u64::from(super::super::priority::to_wire(9)); + assert!(seal(DEFAULT_PUBLISHER_PRIORITY, wire).is_none()); + assert!(matches!( + seal(DEFAULT_PUBLISHER_PRIORITY, wire + 1), + Some(crate::Error::Unsupported) + )); + } + + #[test] + fn a_sealed_group_order_matches_the_track() { + assert!(seal(DEFAULT_PUBLISHER_GROUP_ORDER, 2).is_none()); + // The relay serves the newest group first, so it cannot forward Ascending. + assert!(matches!( + seal(DEFAULT_PUBLISHER_GROUP_ORDER, 1), + Some(crate::Error::Unsupported) + )); + } + + #[test] + fn sealed_dynamic_groups_match_the_track() { + assert!(seal(DYNAMIC_GROUPS, 1).is_none()); + assert!(matches!(seal(DYNAMIC_GROUPS, 0), Some(crate::Error::Unsupported))); + } + + /// Every property the relay restates has a sealed check above. + #[test] + fn every_understood_property_is_checked_when_sealed() { + assert_eq!( + UNDERSTOOD, + [ + MAX_CACHE_DURATION, + TIMESCALE, + DEFAULT_PUBLISHER_PRIORITY, + DEFAULT_PUBLISHER_GROUP_ORDER, + DYNAMIC_GROUPS + ] + ); + } + /// 0x4000-0x7FFF are Mandatory Track Properties, mutable or sealed. #[test] fn mandatory_properties_are_found() { diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 543ef0fed63..0d94a143d03 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -44,8 +44,7 @@ fn serving_subscription(subscriber_priority: u8) -> Subscription { /// INCLUDE_PROPERTIES=0, which keeps the block present but empty. /// /// Declaring the timescale is what opts the track into timestamps; every object Timestamp -/// is in these units. We serve the newest group first by default, matching moq-lite. A draft -/// without room for a property drops it on encode. +/// is in these units. A draft without room for a property drops it on encode. /// /// Fails with [`Error::Unsupported`] for Immutable Properties the draft cannot carry: /// rewriting them for its encoding would break them, and forwarding them unchanged would @@ -68,13 +67,8 @@ fn track_properties(info: &track::Info, wanted: bool, version: Version) -> Resul unknown.values.retain(|property| property.id != 0x06); } Ok(ietf::Properties { - max_cache_duration: info.max_age, - timescale: info.timescale, - priority: Some(super::priority::to_wire(info.priority)), - group_order: Some(GroupOrder::Descending), - // A track opted in to refresh answers a NEW_GROUP_REQUEST as a join. - dynamic_groups: info.refresh.is_some(), unknown, + ..ietf::Properties::restated(info) }) } diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index a0f4395fd8a..a5e50b7e43b 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -480,6 +480,11 @@ fn accepted_info(properties: &ietf::Properties) -> track::Info { info } +/// Why a track answered with `properties` is neither processed nor forwarded, if it is not. +fn refused(properties: &ietf::Properties) -> Option { + properties.unknown.refused(&accepted_info(properties)) +} + /// The Largest Group a subscription knows: its SUBSCRIBE_OK's, or a newer one since. fn largest_group(track: &track::Producer, answer: Option) -> Option { answer.map(|largest| largest.group).max(track.latest_sequence()) @@ -2949,8 +2954,8 @@ where // A track that needs a property we do not understand, or carries more than we // could forward, is neither processed nor forwarded: the subscription is // cancelled and the subscribers refused. - Ok(Some(accepted)) if accepted.properties.unknown.refused().is_some() => { - let err = accepted.properties.unknown.refused().expect("checked by the guard"); + Ok(Some(accepted)) if refused(&accepted.properties).is_some() => { + let err = refused(&accepted.properties).expect("checked by the guard"); tracing::debug!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, %err, "subscribe refused"); // Refuse before waiting on the peer to acknowledge the cancellation. if let Some(pending) = self.take_pending(request_id) { @@ -3848,7 +3853,7 @@ where let _ = stream.writer.finish(); let ok = match response { // A track that needs a property we do not understand is not forwarded. - Ok(ok) => match ok.properties.unknown.refused() { + Ok(ok) => match refused(&ok.properties) { Some(err) => Err(err), None => Ok(ok), }, @@ -15969,6 +15974,34 @@ mod track_property_tests { } } + /// A sealed DEFAULT_PUBLISHER_GROUP_ORDER the relay does not serve refuses the track: + /// egress would forward it in place of the order the relay restates. + #[moq_clock::test] + async fn a_sealed_group_order_the_relay_does_not_serve_refuses_the_track() { + for version in VERSIONS { + for (order, ok) in [(2, true), (1, false)] { + let sealed = Property { + id: 0x0b, + value: Value::Bytes( + block( + version, + &[Property { + id: 0x22, + value: Value::Int(order), + }], + ) + .into(), + ), + }; + let (subscribed, _probe) = subscribe(version, &block(version, &[sealed])).await; + match ok { + true => assert!(subscribed.is_ok(), "{version}: {order}"), + false => assert!(matches!(subscribed, Err(Error::Unsupported)), "{version}: {order}"), + } + } + } + } + /// A TIMESCALE keeps the publisher's units, mutable or sealed: a sealed one travels /// downstream unchanged, and a mutable one matches a copy that arrived over another route. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index ef11a867897..39688cb57a7 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -748,7 +748,10 @@ mod tests { let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); assert_eq!(ingress.unknown.values.len(), repeats + 1, "{version}"); - assert!(ingress.unknown.refused().is_none(), "{version}"); + assert!( + ingress.unknown.refused(&crate::track::Info::default()).is_none(), + "{version}" + ); let msg = TrackProperties(Some(Arc::new(ingress.unknown.clone()))); let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); @@ -792,7 +795,10 @@ mod tests { let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); assert!(ingress.dynamic_groups); assert!(!fits(&ingress.unknown)); - assert!(matches!(ingress.unknown.refused(), Some(crate::Error::Unsupported))); + assert!(matches!( + ingress.unknown.refused(&crate::track::Info::default()), + Some(crate::Error::Unsupported) + )); } #[test] @@ -1125,6 +1131,31 @@ mod hop_tests { } } + /// A sealed TIMESCALE that contradicts TRACK_INFO is refused across the hop: the relay + /// times frames by TRACK_INFO, while egress would forward the sealed one. + #[moq_clock::test] + async fn a_sealed_property_must_match_track_info() { + for (timescale, ok) in [(1000, true), (900, false), (0, false)] { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x08).unwrap(); + e.varint(timescale).unwrap(); + let res = subscribe_across(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + encoding: Some(Encoding::Delta { seven: true }), + ..Default::default() + }) + .await; + match ok { + true => assert!(res.is_ok(), "{timescale}: {res:?}"), + false => assert!(matches!(res, Err(crate::Error::Unsupported)), "{timescale}: {res:?}"), + } + } + } + /// A relay forwards only as many Track Properties as leave room for the ones it /// restates from TRACK_INFO, so one more is refused across the hop. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d524b9ad38f..1395474169c 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6092,13 +6092,13 @@ impl TrackInfoFetch { } self.state = TrackInfoState::Properties { stream, info: model }; } - TrackInfoState::Properties { stream, .. } => { + TrackInfoState::Properties { stream, info } => { if let Poll::Ready(err) = self.closed.poll_closed(&mut cx) { return Poll::Ready(Err(crate::lite::error::from_transport(err))); } let properties = ready!(stream.reader.poll_decode::(&mut cx))?; // Refused as moq-transport ingress refuses it. - if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused()) { + if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused(info)) { return Poll::Ready(Err(err)); } let TrackInfoState::Properties { stream, mut info } = From 2ad4ae271d0b5d500459731026713945cc617d5e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 02:27:35 -0700 Subject: [PATCH 15/25] fix(lite): refuse undefined datagram statuses and the END record past a cap A relayed datagram's Status is held and forwarded, so a lite peer could send one no moq-transport draft defines (such as 2) and have it close the downstream moq-transport session. Lite ingress now drops such a datagram, using the same status set the moq-transport decoder accepts, now defined once in ietf::object. A stream capped at a group's last frame cleared END_OF_GROUP in its Group State but still sent the END_OF_GROUP record past the cap. Records now remembers the cap and sends no END record on a capped stream. The concept doc says moq-lite-07 is opt-in where it documents the extension. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 6 ++- drafts/draft-lcurley-moq-ietf.md | 4 +- rs/moq-net/src/ietf/object.rs | 14 +++++ rs/moq-net/src/ietf/publisher.rs | 8 +-- rs/moq-net/src/ietf/subscriber.rs | 16 +++--- rs/moq-net/src/lite/ietf.rs | 86 ++++++++++++++++++++++++++++++- 6 files changed, 116 insertions(+), 18 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 00822dc7e91..b8c7be404df 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -52,8 +52,10 @@ Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. [ietf](/draft/moq-ietf) goes the other way: it extends moq-lite-07 to carry this -object state between relays. Only Rust offers it, when `extensions.ietf` is set, -and `moq-relay` always does. +object state between relays. moq-lite-07 is still a work in progress +(`moq-lite-07-wip`), negotiated only when both sides enable it, so the default +settings do not carry this state. Only Rust offers the extension, when +`extensions.ietf` is set, and `moq-relay` always does on moq-lite-07. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts application payloads, so relays still forward named tracks they cannot read. See [Encryption](/concept/hang#encryption). diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index db07632889e..a6677edf146 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -91,7 +91,8 @@ A bit field describing the group's relay state, or 0 for a plain group: - `0x8` **END_OF_GROUP**: The stream's end ends the group, as a {{moqt}} subgroup that contains the end of its group. A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, a bit without RELAYED, or a record with Properties when EXTENSIONS is clear. -A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream stops before the end of the group, such as at a subscription's end frame. +A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream may stop before the end of the group, such as at a subscription's end frame. +A stream that stops at an end frame carries no END_OF_GROUP record, even when that frame is the group's last. Only subgroup 0 of a {{moqt}} group is carried. @@ -228,6 +229,7 @@ A bit field, or 0 for a plain datagram, which has none of the optional fields be A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. A datagram with a non-zero Status carries no object: it has no Timestamp, even on a timed track, and its Payload MUST be empty. +A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. # Security Considerations diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index d57661bcd11..3d619832b5d 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -24,6 +24,20 @@ pub(super) fn has_delivery_timeout(version: Version) -> bool { ) } +/// Object status: the object does not exist, defined by drafts 14 and 15 only. +pub(crate) const DOES_NOT_EXIST: u64 = 0x1; +/// Object status: no object at or past this location in the group exists. +pub(crate) const END_OF_GROUP: u64 = 0x3; +/// Object status: no object at or past this location exists (every implemented draft). +pub(crate) const END_OF_TRACK: u64 = 0x4; + +/// Whether any implemented draft defines the Object Status `status`, 0 being Normal. +/// +/// Egress drops a DOES_NOT_EXIST for a draft without it, so a relay may hold one. +pub(crate) fn status_defined(status: u64) -> bool { + matches!(status, 0 | DOES_NOT_EXIST | END_OF_GROUP | END_OF_TRACK) +} + /// Only draft-14 lets a status object, such as END_OF_GROUP, carry properties. #[cfg(feature = "async")] pub(super) fn status_has_properties(version: Version) -> bool { diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 0d94a143d03..7b3dc1c98fe 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -4418,7 +4418,9 @@ impl TrackServe { Some(wire) => { // A datagram this draft cannot carry is dropped like an oversized one: it // is best-effort, and the track's groups do not depend on it. - if wire.status == Some(1) && !matches!(self.version, Version::Draft14 | Version::Draft15) { + if wire.status == Some(DOES_NOT_EXIST) + && !matches!(self.version, Version::Draft14 | Version::Draft15) + { tracing::debug!(sequence, "dropping a datagram status this draft cannot carry"); continue; } @@ -5098,9 +5100,7 @@ impl GroupServe { } } -/// Object status: no object at or past this location exists. -const END_OF_GROUP: u64 = 0x3; -const END_OF_TRACK: u64 = 0x4; +use super::object::{DOES_NOT_EXIST, END_OF_GROUP, END_OF_TRACK}; /// An object's header, with private relay fields when it came from an IETF peer. struct Object<'a> { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index a5e50b7e43b..41f2df63b4b 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4092,11 +4092,13 @@ where let (payload, status) = match datagram.body { ietf::DatagramBody::Payload(payload) => (payload, None), - ietf::DatagramBody::Status(status @ (0 | END_OF_GROUP | END_OF_TRACK)) => { - (bytes::Bytes::new(), Some(status)) + ietf::DatagramBody::Status(DOES_NOT_EXIST) + if !matches!(self.version, Version::Draft14 | Version::Draft15) => + { + return Err(Error::Session(SessionError::ProtocolViolation)); } - ietf::DatagramBody::Status(1) if matches!(self.version, Version::Draft14 | Version::Draft15) => { - (bytes::Bytes::new(), Some(1)) + ietf::DatagramBody::Status(status) if super::object::status_defined(status) => { + (bytes::Bytes::new(), Some(status)) } ietf::DatagramBody::Status(_) => return Err(Error::Session(SessionError::ProtocolViolation)), }; @@ -4180,11 +4182,7 @@ enum Ended { Track { object: u64, properties: bool }, } -/// Object status: no object at or past this location in the group exists (draft-14, 15). -const END_OF_GROUP: u64 = 0x3; - -/// Object status: no object at or past this location exists (every implemented draft). -const END_OF_TRACK: u64 = 0x4; +use super::object::{DOES_NOT_EXIST, END_OF_GROUP, END_OF_TRACK}; /// The start of a subgroup stream's first object, peeked before its group is created. #[derive(Debug, Clone, Copy)] diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 39688cb57a7..4e55f740add 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -257,6 +257,8 @@ pub(crate) fn decode_properties( pub(crate) struct Records { /// The previous record's Object ID, `None` before the first. prior: Option, + /// The stream stops at a frame cap, so its Group State promised no END_OF_GROUP. + capped: bool, /// The units the track declares, which a sealed Timestamp must already be in. timescale: Option, version: Version, @@ -285,6 +287,7 @@ impl Records { writer.buffer_varint(encode_state(wire.as_ref(), whole, capped))?; Ok(Some(Self { prior: None, + capped, timescale, version, })) @@ -306,8 +309,9 @@ impl Records { writer: &mut crate::coding::Writer, group: &group::Consumer, ) -> Result<(), Error> { - // A stream capped short of the last frame stops before the end. - if group.index() < group.frame_count() as u64 { + // A capped stream stops at its cap even when that is the last frame, and one capped + // short of the last frame stops before the end. + if self.capped || group.index() < group.frame_count() as u64 { return Ok(()); } match group.end_object() { @@ -453,6 +457,10 @@ pub(crate) fn decode_datagram( let object_id = (state & OBJECT_ID != 0).then(|| r.varint()).transpose()?; let priority = (state & PRIORITY != 0).then(|| r.u8()).transpose()?; let status = (state & STATUS != 0).then(|| r.varint()).transpose()?; + // A relay holds and forwards it, so it must be one moq-transport ingress would accept. + if status.is_some_and(|status| !crate::ietf::object::status_defined(status)) { + return Err(DecodeError::InvalidValue); + } let block = r.bytes()?; let properties = decode_properties(block, timescale, version)?.properties; Ok(Some(crate::model::datagram::Wire { @@ -801,6 +809,25 @@ mod tests { )); } + /// A relay holds and forwards a datagram's Status, so one moq-transport does not define + /// would close the session it reached: it is refused where it arrives. + #[test] + fn datagram_statuses_are_ones_moq_transport_defines() { + for (status, ok) in [(0, true), (1, true), (2, false), (3, true), (4, true), (5, false)] { + let wire = crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: Some(status), + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V); + assert_eq!(decoded.is_ok(), ok, "{status}"); + } + } + #[test] fn datagram_state_round_trips() { let wire = crate::model::datagram::Wire { @@ -1083,6 +1110,61 @@ mod hop_tests { } } + /// A subscription capped at a group's last frame stops there: its Group State promises + /// no END_OF_GROUP, so the END_OF_GROUP record past the cap is not sent either. + #[moq_clock::test] + async fn a_capped_stream_carries_no_end_record() { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let track = broadcast + .create_track("video", track::Info::timed().with_timescale(Timescale::MILLI)) + .unwrap(); + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group + .set_wire(group::Wire { + sparse: false, + first_object: true, + first_id: 0, + extensions: false, + has_end: true, + fetchable: true, + last: None, + }) + .unwrap(); + for (index, payload) in [b"a", b"b"].into_iter().enumerate() { + let fields = crate::model::object::Fields { + id: index as u64, + properties: Properties::default(), + }; + write(&mut group, index as u64, Some(fields), payload); + } + group.mark_gap(2, None).unwrap(); + group + .set_end_object(crate::model::object::Fields { + id: 2, + properties: Properties::default(), + }) + .unwrap(); + group.finish().unwrap(); + + let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; + let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + let capped = track::Subscription::default().with_end(track::Position::after(0, 1)); + let mut subscriber = moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(capped)) + .await + .expect("no subscription") + .unwrap(); + let mut received = recv(&mut subscriber).await; + assert_eq!(&next(&mut received).await.unwrap().payload[..], b"a"); + assert_eq!(&next(&mut received).await.unwrap().payload[..], b"b"); + assert!(next(&mut received).await.is_none()); + assert!(!received.wire().expect("relay state").has_end); + assert!(received.end_object().is_none(), "an END_OF_GROUP past the cap"); + } + /// Subscribe across a negotiated hop to a track carrying `properties`. async fn subscribe_across(properties: crate::model::object::TrackProperties) -> Result<(), crate::Error> { let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); From 7f8369ceda667aee3c7507a5be7f18b12c673f9b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 02:48:56 -0700 Subject: [PATCH 16/25] fix(net): a status object keeps its timestamp; datagram shapes match moq-transport A draft-14 status object (such as END_OF_GROUP) on a timed track had its mutable Timestamp lifted out like a frame's, but it has no frame to hold it, so the time was lost on every egress. Ingress now re-reads a status object's list without lifting (object::unframed), on subgroups, FETCH, and datagrams, and the lite hop accepts that Timestamp in an END record or a status datagram's block. check_status now sees the full list too. A lite datagram with both STATUS and END_OF_GROUP was accepted on the hop although no moq-transport draft defines that Type. Lite decode now asks ObjectDatagram's own Type validity whether any draft could carry the datagram, so the two cannot drift. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- drafts/draft-lcurley-moq-ietf.md | 4 +- rs/moq-net/src/ietf/datagram.rs | 41 ++++++++++- rs/moq-net/src/ietf/object.rs | 59 ++++++++++++--- rs/moq-net/src/ietf/subscriber.rs | 117 +++++++++++++++++++++++------- rs/moq-net/src/lite/ietf.rs | 58 ++++++++++----- rs/moq-net/src/lite/subscriber.rs | 4 +- 7 files changed, 224 insertions(+), 61 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index b8c7be404df..4f543c710ad 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -31,7 +31,7 @@ subset drops. What a peer actually observes against this implementation: - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. -- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. +- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated; a status object has no frame, so it keeps its Timestamp among its properties. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. - **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index a6677edf146..da664398be8 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -146,7 +146,7 @@ DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that wo Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. It MUST NOT be empty or longer than 65,536 bytes. -On a timed track it MUST NOT be longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. +On a timed track an object with a FRAME, or a datagram without a Status, MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits. A receiver MUST treat a block its encoding's drafts would refuse as malformed. Other properties are opaque to this extension. @@ -158,6 +158,7 @@ A relay forwarding the object to {{moqt}} restates the time as the mutable Times A sealed Timestamp is in the track's Timescale ({{moql}} TRACK_INFO), and a relay MUST NOT forward one to a peer of other units, which would change its meaning. On an untimed track there is no FRAME Timestamp, so a mutable Timestamp stays in the Property Block as an opaque property. +Likewise, an object without a FRAME, such as the END_OF_GROUP record or a datagram with a non-zero Status, has no time of its own beside the block, so its mutable Timestamp stays there on any track. # Track Stream {#track} @@ -230,6 +231,7 @@ A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. A datagram with a non-zero Status carries no object: it has no Timestamp, even on a timed track, and its Payload MUST be empty. A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. +It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. # Security Considerations diff --git a/rs/moq-net/src/ietf/datagram.rs b/rs/moq-net/src/ietf/datagram.rs index 008d7e931f4..16b91226275 100644 --- a/rs/moq-net/src/ietf/datagram.rs +++ b/rs/moq-net/src/ietf/datagram.rs @@ -56,10 +56,18 @@ impl ObjectDatagram { _ => kind & !flag::ALL == 0 && !(kind & flag::STATUS != 0 && kind & flag::END_OF_GROUP != 0), } } -} -impl Encode for ObjectDatagram { - fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { + /// Whether any implemented draft defines this datagram's Type: draft-14 and every + /// later draft each define one set. + fn defined(&self) -> bool { + let kind = self.kind(); + [Version::Draft14, Version::Draft15] + .into_iter() + .any(|version| Self::valid(kind, version)) + } + + /// The Type bits this datagram's fields set. + fn kind(&self) -> u64 { let mut kind = 0; if self.properties.is_some() { kind |= flag::PROPERTIES; @@ -76,6 +84,33 @@ impl Encode for ObjectDatagram { if matches!(self.body, DatagramBody::Status(_)) { kind |= flag::STATUS; } + kind + } +} + +impl crate::model::datagram::Wire { + /// Whether moq-transport defines a datagram of this shape on some draft, as its ingress + /// checks one. Egress resolves the Object ID and priority each draft needs. + pub(crate) fn defined(&self) -> bool { + let shape = ObjectDatagram { + track_alias: 0, + group_id: 0, + object_id: self.object_id, + publisher_priority: self.priority, + end_of_group: self.end_of_group, + properties: self.properties.block.is_some().then(Vec::new), + body: match self.status { + Some(status) => DatagramBody::Status(status), + None => DatagramBody::Payload(Bytes::new()), + }, + }; + shape.defined() && self.status.is_none_or(super::object::status_defined) + } +} + +impl Encode for ObjectDatagram { + fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { + let kind = self.kind(); if !Self::valid(kind, version) { return Err(EncodeError::InvalidState); } diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 3d619832b5d..eeb3c6ffe68 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -206,16 +206,22 @@ pub(crate) struct Checked { } /// Validate a block received as `encoding` on a track in `timescale`, as moq-transport -/// ingress validates a list. +/// ingress validates a list, for an object that is `framed` or a frameless status. /// -/// A timed track's mutable Timestamp is its frame's, so one inside is malformed, as is an -/// empty block, which is sent as none. -pub(crate) fn check(bytes: &Bytes, encoding: Encoding, timescale: Option) -> Result { - if bytes.is_empty() || bytes.len() > max_block(timescale) { +/// A framed object's mutable Timestamp on a timed track is its frame's, so one inside is +/// malformed, as is an empty block, which is sent as none. +pub(crate) fn check( + bytes: &Bytes, + encoding: Encoding, + timescale: Option, + framed: bool, +) -> Result { + let lifted = timescale.filter(|_| framed); + if bytes.is_empty() || bytes.len() > max_block(lifted) { return Err(Error::MalformedTrack); } - let parsed = list(bytes, family(encoding), false, timescale.is_some())?; - if timescale.is_some() && parsed.timestamp.is_some() { + let parsed = list(bytes, family(encoding), false, lifted.is_some())?; + if lifted.is_some() && parsed.timestamp.is_some() { return Err(Error::MalformedTrack); } Ok(Checked { @@ -250,13 +256,25 @@ pub(crate) fn values(block: &crate::model::object::Block) -> Result) -> Result { - let parsed = list(data, version, false, timescale.is_some())?; + decode(data, version, timescale, true) +} + +/// Read the property list of an object without a frame, such as an END_OF_GROUP status, +/// on a track in `timescale`. No frame holds its time, so a mutable Timestamp stays in the +/// block, as on an untimed track. +pub(crate) fn unframed(data: &Bytes, version: Version, timescale: Option) -> Result { + Ok(decode(data, version, timescale, false)?.properties) +} + +fn decode(data: &Bytes, version: Version, timescale: Option, framed: bool) -> Result { + let lifted = timescale.filter(|_| framed); + let parsed = list(data, version, false, lifted.is_some())?; let properties = Properties { sealed_time: timed(parsed.sealed_time, timescale)?, block: block(&parsed.values, encoding(version), has_delivery_timeout(version))?, }; // A list at the limit with a small Timestamp cannot take back a larger one on egress. - if properties.heap() > max_block(timescale) as u64 { + if properties.heap() > max_block(lifted) as u64 { return Err(Error::Unsupported); } Ok(Decoded { @@ -568,9 +586,26 @@ mod tests { // The same bound on a block arriving over the lite hop. let encoding = Encoding::Delta { seven: true }; - assert!(check(&block(limit), encoding, milli).is_ok()); - assert!(check(&block(limit + 1), encoding, milli).is_err()); - assert!(check(&block(limit + 1), encoding, None).is_ok()); + assert!(check(&block(limit), encoding, milli, true).is_ok()); + assert!(check(&block(limit + 1), encoding, milli, true).is_err()); + assert!(check(&block(limit + 1), encoding, None, true).is_ok()); + } + + /// A status object has no frame to hold its time, so its mutable Timestamp stays in the + /// block on a timed track, where a framed object's is lifted out. + #[test] + fn a_status_object_keeps_its_timestamp() { + let milli = Some(Timescale::MILLI); + let list = Bytes::from_static(&[0x10, 7, 0x3e, 1]); + let framed = read(&list, Version::Draft14, milli).unwrap(); + assert_eq!(framed.timestamp, Some(Timestamp::new(7, Timescale::MILLI).unwrap())); + let status = unframed(&list, Version::Draft14, milli).unwrap(); + assert_eq!(write(&status, None, Version::Draft14, None).unwrap(), list.to_vec()); + + // Over the lite hop, only a status block may hold it. + let block = status.block.unwrap().bytes; + assert!(check(&block, Encoding::Absolute, milli, false).is_ok()); + assert!(check(&block, Encoding::Absolute, milli, true).is_err()); } /// Draft-19 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so it cannot cross that boundary. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 41f2df63b4b..94f3b2d63d8 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4118,14 +4118,24 @@ where // Like a subgroup object: a track that declared no timescale is untimed. One on a // timed track without a Timestamp is refused by the model. let properties = bytes::Bytes::from(datagram.properties.unwrap_or_default()); - let decoded = super::object::read(&properties, self.version, track.timescale)?; + // A status object has no frame to hold its time, so its block keeps it. + let (timestamp, properties) = match status.is_some_and(|status| status != 0) { + true => ( + None, + super::object::unframed(&properties, self.version, track.timescale)?, + ), + false => { + let decoded = super::object::read(&properties, self.version, track.timescale)?; + (decoded.timestamp, decoded.properties) + } + }; let Some(producer) = track.producer.as_mut() else { return Ok(()); }; producer.insert_wire_datagram(crate::model::datagram::Stored { datagram: crate::Datagram { sequence, - timestamp: decoded.timestamp, + timestamp, payload, }, wire: Some(std::sync::Arc::new(crate::model::datagram::Wire { @@ -4133,7 +4143,7 @@ where priority: datagram.publisher_priority, end_of_group: datagram.end_of_group, status, - properties: decoded.properties, + properties, })), })?; Ok(()) @@ -4413,6 +4423,8 @@ struct GroupIngest { prior_object: Option, start: Option, properties: crate::model::object::Properties, + /// The property list `properties` was read from, for a status object, which has no frame. + raw: bytes::Bytes, gap: Option, /// The object being read is one the group started past, so it is read and dropped. dropping: bool, @@ -4453,6 +4465,7 @@ impl GroupIngest { prior_object: None, start, properties: Default::default(), + raw: bytes::Bytes::new(), gap: None, dropping: false, phase: IngestPhase::Delta, @@ -4703,11 +4716,8 @@ where continue; } - let decoded = super::object::read( - &bytes::Bytes::from(object.properties.unwrap_or_default()), - self.version, - timescale, - )?; + let raw = bytes::Bytes::from(object.properties.unwrap_or_default()); + let decoded = super::object::read(&raw, self.version, timescale)?; let expected = head .as_ref() .filter(|(sequence, _, _)| group.is_none_or(|group| group == *sequence)) @@ -4762,6 +4772,7 @@ where producer, FetchPayload { decoded, + raw, timescale, keep, id, @@ -4787,6 +4798,7 @@ where ) -> Result { let FetchPayload { decoded, + raw, timescale, keep, id, @@ -4797,23 +4809,26 @@ where let size = stream.varint().await?; if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { let status = stream.varint().await?; - if status != 0 { - super::object::check_status(self.version, &decoded.properties)?; - } - match status { - 0 => {} - END_OF_GROUP => { + // A status object has no frame to hold its time, so its block keeps it. + let unframed = match status { + 0 => None, + _ => { + let properties = super::object::unframed(&raw, self.version, timescale)?; + super::object::check_status(self.version, &properties)?; + Some(properties) + } + }; + match (status, unframed) { + (0, _) => {} + (END_OF_GROUP, Some(properties)) => { if keep { - producer.set_end_object(crate::model::object::Fields { - id, - properties: decoded.properties, - })?; + producer.set_end_object(crate::model::object::Fields { id, properties })?; } return Ok(Fetched::EndOfGroup); } // END_OF_TRACK is track-level, so there is nowhere to keep its properties. - END_OF_TRACK if !decoded.properties.is_empty() => return Err(Error::Unsupported), - END_OF_TRACK => return Ok(Fetched::EndOfTrack), + (END_OF_TRACK, Some(properties)) if !properties.is_empty() => return Err(Error::Unsupported), + (END_OF_TRACK, _) => return Ok(Fetched::EndOfTrack), _ => return Err(Error::Unsupported), } } @@ -5277,11 +5292,8 @@ where if group.is_some_and(|group| group != sequence) || id < next { return Err(Error::ProtocolViolation); } - let decoded = super::object::read( - &bytes::Bytes::from(object.properties.unwrap_or_default()), - self.version, - timescale, - )?; + let raw = bytes::Bytes::from(object.properties.unwrap_or_default()); + let decoded = super::object::read(&raw, self.version, timescale)?; if id > next && decoded.gap.is_none_or(|gap| gap < id - next) { return Err(Error::Unsupported); } @@ -5291,6 +5303,7 @@ where producer, FetchPayload { decoded, + raw, timescale, keep: true, id, @@ -5341,6 +5354,8 @@ enum Fetched { struct FetchPayload { decoded: super::object::Decoded, + /// The property list `decoded` was read from, for a status object, which has no frame. + raw: bytes::Bytes, timescale: Option, keep: bool, id: u64, @@ -5583,6 +5598,7 @@ impl GroupIngest { let id = next_object_id(self.prior_object, id_delta, self.start)?; self.prior_object = Some(id); self.properties = Default::default(); + self.raw = bytes::Bytes::new(); self.gap = None; self.dropping = self.start.is_some() && id < group.frame_count() as u64; self.phase = match self.has_extensions { @@ -5599,6 +5615,7 @@ impl GroupIngest { let decoded = super::object::read(&ext, self.version, self.timescale)?; let timestamp = decoded.timestamp; self.properties = decoded.properties; + self.raw = ext; self.gap = decoded.gap; self.phase = IngestPhase::Size { timestamp }; } @@ -5633,6 +5650,8 @@ impl GroupIngest { self.phase = IngestPhase::Delta; continue; } + // A status object has no frame to hold its time, so its block keeps it. + self.properties = super::object::unframed(&self.raw, self.version, self.timescale)?; super::object::check_status(self.version, &self.properties)?; if status == END_OF_GROUP { group.mark_gap(self.prior_object.expect("properties follow Object ID"), self.gap)?; @@ -12641,6 +12660,54 @@ mod stitch_tests { assert!(decoder.is_empty()); } + /// Draft-14 lets a status object carry properties, and it has no frame to hold its + /// time, so a mutable Timestamp stays in its block on a timed track: through a subgroup + /// and a FETCH, and out again as it arrived. + #[moq_clock::test] + async fn a_status_object_keeps_its_timestamp() { + use futures::FutureExt; + + let version = Version::Draft14; + let status = [0x10, 7]; + let leaves = |properties: &crate::model::object::Properties| { + super::super::object::write(properties, None, version, None).unwrap() + }; + + let script = object_stream( + version, + true, + &[(0, &[0x10, 5], None), (1, &status, Some(END_OF_GROUP))], + ); + let mut h = Harness::with_timescale(Fill::Done, vec![script], Some(Timescale::MILLI)); + h.subscriber.version = version; + let mut consumer = h.track.subscribe(None); + let mut stream = h.stream().await.with_version(version); + h.subscriber.clone().recv_group(&mut stream).await.unwrap(); + let group = consumer.recv_group().now_or_never().unwrap().unwrap().unwrap(); + let end = group.end_object().expect("the END_OF_GROUP object"); + assert_eq!(leaves(&end.properties), status, "subgroup"); + + // A draft-14 FETCH object: Group, Subgroup, Object, priority, then its properties, + // an empty payload, and the status. + let mut objects = Vec::new(); + let w = &mut Encoder::new(&mut objects, version.into()); + for value in [SEQUENCE, 0, 0] { + w.varint(value).unwrap(); + } + w.u8(128); + w.bytes(&status).unwrap(); + w.varint(0u64).unwrap(); + w.varint(END_OF_GROUP).unwrap(); + let mut run = GroupFetchRun::new(version, objects).await; + let mut producer = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + run.subscriber + .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(1), Some(Timescale::MILLI)) + .await + .unwrap(); + let end = producer.consume().end_object().expect("the END_OF_GROUP object"); + assert_eq!(leaves(&end.properties), status, "fetch"); + } + #[moq_clock::test] async fn passthrough_refuses_contradictory_gap_properties() { for properties in [vec![0x3e, 2], vec![0x3e, 3], vec![0x3e, 1, 0, 1]] { diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 4e55f740add..ae47c3d3d25 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -216,12 +216,14 @@ pub(crate) struct Decoded { } /// Decode an object's record body on a track in `timescale`, the units the track -/// declares, which its sealed Timestamp is in. +/// declares, which its sealed Timestamp is in. A `framed` object's frame holds its time; +/// a status object's block holds it. /// /// Only the canonical form is accepted, so what decodes re-encodes to the same bytes. pub(crate) fn decode_properties( body: &[u8], timescale: Option, + framed: bool, version: Version, ) -> Result { if body.is_empty() { @@ -236,7 +238,8 @@ pub(crate) fn decode_properties( let encoding = encoding.ok_or(DecodeError::InvalidValue)?; // A small cached block must not pin the reader's larger receive buffer. let bytes = Bytes::copy_from_slice(&body[body.len() - r.remaining()..]); - let checked = crate::ietf::object::check(&bytes, encoding, timescale).map_err(|_| DecodeError::InvalidValue)?; + let checked = + crate::ietf::object::check(&bytes, encoding, timescale, framed).map_err(|_| DecodeError::InvalidValue)?; Ok(Decoded { properties: Properties { sealed_time: checked.sealed_time, @@ -457,19 +460,22 @@ pub(crate) fn decode_datagram( let object_id = (state & OBJECT_ID != 0).then(|| r.varint()).transpose()?; let priority = (state & PRIORITY != 0).then(|| r.u8()).transpose()?; let status = (state & STATUS != 0).then(|| r.varint()).transpose()?; - // A relay holds and forwards it, so it must be one moq-transport ingress would accept. - if status.is_some_and(|status| !crate::ietf::object::status_defined(status)) { - return Err(DecodeError::InvalidValue); - } + // A status object has no frame to hold its time. + let framed = status.is_none_or(|status| status == 0); let block = r.bytes()?; - let properties = decode_properties(block, timescale, version)?.properties; - Ok(Some(crate::model::datagram::Wire { + let properties = decode_properties(block, timescale, framed, version)?.properties; + let wire = crate::model::datagram::Wire { object_id, priority, end_of_group: state & DATAGRAM_END != 0, status, properties, - })) + }; + // A relay holds and forwards it, so it must be one moq-transport ingress would accept. + if !wire.defined() { + return Err(DecodeError::InvalidValue); + } + Ok(Some(wire)) } #[cfg(test)] @@ -546,18 +552,18 @@ mod tests { block: crate::ietf::object::block(&values, Encoding::DeltaQuic, true).unwrap(), }; let body = encode_properties(&properties, V).unwrap(); - let decoded = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); + let decoded = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); assert_eq!(decoded.properties, properties); assert_eq!(decoded.gap, Some(2)); // None at all is an empty body. assert!(encode_properties(&Properties::default(), V).unwrap().is_empty()); - let empty = decode_properties(&[], Some(Timescale::MILLI), V).unwrap(); + let empty = decode_properties(&[], Some(Timescale::MILLI), true, V).unwrap(); assert_eq!(empty.properties, Properties::default()); // An untimed track's Timestamp has no frame to hold it, so it stays in the block. let untimed = [4 << 1, 0x10, 7]; - let decoded = decode_properties(&untimed, None, V).unwrap(); + let decoded = decode_properties(&untimed, None, true, V).unwrap(); assert_eq!(encode_properties(&decoded.properties, V).unwrap(), untimed); } @@ -578,7 +584,7 @@ mod tests { (&[delta, 0x0b, 2, 0x0b, 0][..], "a nested Immutable Properties"), ] { assert!( - decode_properties(body, Some(Timescale::MILLI), V).is_err(), + decode_properties(body, Some(Timescale::MILLI), true, V).is_err(), "accepted {reason}" ); } @@ -609,7 +615,7 @@ mod tests { let body = encode_properties(&properties, V).unwrap(); assert!(body.len() <= MAX_PROPERTIES, "{version}: {} bytes", body.len()); - let received = decode_properties(&body, Some(Timescale::MILLI), V).unwrap(); + let received = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); assert_eq!(received.properties, properties, "{version}"); let written = crate::ietf::object::write(&received.properties, frame, version, Some(Timescale::MILLI)).unwrap(); @@ -828,8 +834,10 @@ mod tests { } } + /// No moq-transport draft defines a status datagram that also ends the group, so one + /// is refused where it arrives, by the check moq-transport ingress applies. #[test] - fn datagram_state_round_trips() { + fn a_status_datagram_cannot_end_the_group() { let wire = crate::model::datagram::Wire { object_id: Some(3), priority: Some(9), @@ -839,8 +847,24 @@ mod tests { }; let mut buf = Vec::new(); encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); - let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).unwrap(); - assert_eq!(decoded, Some(wire)); + assert!(decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).is_err()); + } + + #[test] + fn datagram_state_round_trips() { + for (end_of_group, status) in [(false, Some(3)), (true, None)] { + let wire = crate::model::datagram::Wire { + object_id: Some(3), + priority: Some(9), + end_of_group, + status, + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).unwrap(); + assert_eq!(decoded, Some(wire)); + } let mut plain = Vec::new(); encode_datagram(&mut Encoder::new(&mut plain, V.into()), None, V).unwrap(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 1395474169c..3c26c42cb9a 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1169,7 +1169,7 @@ impl FrameIngest { return Poll::Ready(Err(Error::ProtocolViolation)); } if end { - let decoded = lite::ietf::decode_properties(&block, self.timescale, self.version)?; + let decoded = lite::ietf::decode_properties(&block, self.timescale, false, self.version)?; group.mark_gap(id, decoded.gap)?; group.set_end_object(crate::model::object::Fields { id, @@ -1216,7 +1216,7 @@ impl FrameIngest { Some(records) => { let (id, block) = records.pending.take().expect("a record precedes each frame"); let lite::ietf::Decoded { properties, gap } = - lite::ietf::decode_properties(&block, self.timescale, self.version)?; + lite::ietf::decode_properties(&block, self.timescale, true, self.version)?; group.mark_gap(id, gap)?; let plain = id == group.frame_count() as u64 && properties.is_empty(); if !plain && !records.relayed { From 8d172318d6c5e8eb19f404c2df3c7d635dcf0a94 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 03:00:56 -0700 Subject: [PATCH 17/25] fix(lite): a datagram with a STATUS field carries no payload A relayed datagram with STATUS present at 0 (Normal) and a payload was accepted, since only a non-zero status refused one, and moq-transport egress then sent it as a status body without its payload. The payload rule now keys on the field being present; the timestamp rule still keys on a non-zero status, as a Normal status is an empty object with a time. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 3 +- rs/moq-net/src/lite/datagram.rs | 60 +++++++++++++++++++++++++++----- 2 files changed, 53 insertions(+), 10 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index da664398be8..6bbfa77f7d8 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -229,7 +229,8 @@ A bit field, or 0 for a plain datagram, which has none of the optional fields be A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. -A datagram with a non-zero Status carries no object: it has no Timestamp, even on a timed track, and its Payload MUST be empty. +A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payload beside one; a Normal (0) Status is an empty object. +A non-zero Status carries no object: it has no Timestamp, even on a timed track. A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 85000547cc9..6b54c8fa80e 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -47,11 +47,12 @@ impl Encode for Datagram { if !version.has_ietf() { return Err(EncodeError::Version); } - // A status carries no payload and no time. - let status = wire - .as_ref() - .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); - if status && (self.timestamp.is_some() || !self.payload.is_empty()) { + // Any status object carries no payload, which moq-transport could not send beside + // it, and a non-zero one carries no object and so no time either. + let status = wire.as_ref().and_then(|wire| wire.status); + if status.is_some() && !self.payload.is_empty() + || status.is_some_and(|status| status != 0) && self.timestamp.is_some() + { return Err(EncodeError::InvalidState); } super::ietf::encode_datagram(w, wire.as_ref(), version)?; @@ -89,12 +90,13 @@ impl Datagram { let ietf = ietf .then(|| super::ietf::decode_datagram(&mut r, timescale, version)) .transpose()?; - // A status carries no payload and no time. + // Any status object carries no payload, which moq-transport could not send beside + // it, and a non-zero one carries no object and so no time either. let status = ietf .as_ref() .and_then(|wire| wire.as_ref()) - .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); - let timestamp = if timescale.is_some() && !status { + .and_then(|wire| wire.status); + let timestamp = if timescale.is_some() && status.is_none_or(|status| status == 0) { Some(r.varint()?) } else { None @@ -102,7 +104,7 @@ impl Datagram { // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); - if status && !payload.is_empty() { + if status.is_some() && !payload.is_empty() { return Err(DecodeError::InvalidValue); } @@ -238,6 +240,46 @@ mod test { assert!(matches!(decode(dg(0x10)), Err(DecodeError::InvalidValue))); } + /// A Normal status (0) is an empty object, which moq-transport sends as a status with + /// no payload, so a STATUS field beside a payload is refused whatever its value. + #[test] + fn a_status_carries_no_payload() { + for status in [0, 3] { + let dg = |payload: &'static [u8]| Datagram { + subscribe: 1, + sequence: 2, + timestamp: (status == 0).then_some(500), + payload: Bytes::from_static(payload), + ietf: Some(Some(crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: Some(status), + properties: Default::default(), + })), + }; + assert!( + matches!(dg(b"x").encode_bytes(Version::Lite07), Err(EncodeError::InvalidState)), + "{status}" + ); + let empty = dg(b""); + let mut buf = empty.encode_bytes(Version::Lite07).unwrap().to_vec(); + let decoded = Datagram::decode(Bytes::from(buf.clone()), Version::Lite07, true, |_| { + Some(Timescale::MILLI) + }) + .unwrap(); + assert_eq!(decoded, empty, "{status}"); + buf.push(b'x'); + assert!( + matches!( + Datagram::decode(Bytes::from(buf), Version::Lite07, true, |_| Some(Timescale::MILLI)), + Err(DecodeError::InvalidValue) + ), + "{status}" + ); + } + } + #[test] fn rejects_old_versions() { let dg = Datagram { From 5048ea2eeb9c21b352bc79be4e4fc610099511d0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 08:56:15 -0700 Subject: [PATCH 18/25] fix(net): a sealed group order is advisory A moq-transport publisher that seals DEFAULT_PUBLISHER_GROUP_ORDER is accepted whatever order it names: the relay serves its own order and forwards the sealed block unchanged. Every other sealed value that contradicts the track info is still refused. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 3 ++- rs/moq-net/src/ietf/properties.rs | 41 +++++++++++++++++++++++++------ rs/moq-net/src/ietf/subscriber.rs | 21 +++++++++------- 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 6bbfa77f7d8..433c1f87a8d 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -191,7 +191,8 @@ A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 Dropping those five can widen the delta that spans them, so a relay also refuses a {{moqt}} track whose remaining list would not fit a TRACK_PROPERTIES message, as unsupported. The Immutable Properties may still hold one of those five, which a relay forwards in place of the one it would restate. -A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, DEFAULT_PUBLISHER_GROUP_ORDER descending, the order a relay serves, and DYNAMIC_GROUPS whether the track takes a new group request. +A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, and DYNAMIC_GROUPS whether the track takes a new group request. +A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: a relay serves its own order and forwards the sealed value unchanged, whatever it says. A relay refuses a track whose sealed value differs, from a {{moqt}} publisher or over this extension, as unsupported. A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index 277482103fc..d7f6867f890 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -380,7 +380,8 @@ impl TrackProperties { MAX_CACHE_DURATION => sealed.max_cache_duration != restated.max_cache_duration, TIMESCALE => sealed.timescale != restated.timescale, DEFAULT_PUBLISHER_PRIORITY => sealed.priority != restated.priority, - DEFAULT_PUBLISHER_GROUP_ORDER => sealed.group_order != restated.group_order, + // Advisory: a relay serves its own order and forwards the publisher's preference. + DEFAULT_PUBLISHER_GROUP_ORDER => false, DYNAMIC_GROUPS => sealed.dynamic_groups != restated.dynamic_groups, _ => unreachable!("only the understood properties are seen"), }) @@ -848,13 +849,37 @@ mod tests { } #[test] - fn a_sealed_group_order_matches_the_track() { - assert!(seal(DEFAULT_PUBLISHER_GROUP_ORDER, 2).is_none()); - // The relay serves the newest group first, so it cannot forward Ascending. - assert!(matches!( - seal(DEFAULT_PUBLISHER_GROUP_ORDER, 1), - Some(crate::Error::Unsupported) - )); + fn a_sealed_group_order_is_advisory() { + // The relay serves the newest group first, but forwards the publisher's preference. + for order in [1, 2] { + assert!(seal(DEFAULT_PUBLISHER_GROUP_ORDER, order).is_none(), "{order}"); + } + + // Egress forwards the sealed block unchanged and restates no mutable order beside it. + let version = Version::Draft22; + let mut sealed = Vec::new(); + let w = &mut Encoder::new(&mut sealed, version.into()); + w.varint(DEFAULT_PUBLISHER_GROUP_ORDER).unwrap(); + w.varint(1).unwrap(); + let unknown = TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.clone().into()), + }], + encoding: Some(super::super::object::encoding(version)), + delivery_timeout: true, + }; + let egress = Properties { + unknown: unknown.clone(), + ..Properties::restated(&crate::track::Info::default()) + }; + let mut buf = Vec::new(); + egress + .encode(&mut Encoder::new(&mut buf, version.into()), version) + .unwrap(); + let decoded = decode_draft22(&buf).unwrap(); + assert_eq!(decoded.group_order, Some(GroupOrder::Ascending)); + assert_eq!(decoded.unknown, unknown); } #[test] diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 94f3b2d63d8..18bef38df0a 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -16039,12 +16039,12 @@ mod track_property_tests { } } - /// A sealed DEFAULT_PUBLISHER_GROUP_ORDER the relay does not serve refuses the track: - /// egress would forward it in place of the order the relay restates. + /// A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: the relay accepts the track, serves + /// its own order, and keeps the sealed block to forward unchanged. #[moq_clock::test] - async fn a_sealed_group_order_the_relay_does_not_serve_refuses_the_track() { + async fn a_sealed_group_order_the_relay_does_not_serve_is_accepted() { for version in VERSIONS { - for (order, ok) in [(2, true), (1, false)] { + for order in [2, 1] { let sealed = Property { id: 0x0b, value: Value::Bytes( @@ -16058,11 +16058,14 @@ mod track_property_tests { .into(), ), }; - let (subscribed, _probe) = subscribe(version, &block(version, &[sealed])).await; - match ok { - true => assert!(subscribed.is_ok(), "{version}: {order}"), - false => assert!(matches!(subscribed, Err(Error::Unsupported)), "{version}: {order}"), - } + let (subscribed, _probe) = subscribe(version, &block(version, std::slice::from_ref(&sealed))).await; + let subscriber = subscribed.unwrap_or_else(|err| panic!("{version}: {order}: {err}")); + let properties = subscriber + .info() + .properties + .clone() + .expect("the sealed block was dropped"); + assert_eq!(properties.values, [sealed], "{version}: {order}"); } } } From 4bbadbc049b055eda6558bc49acf59b1d4b66266 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 09:20:11 -0700 Subject: [PATCH 19/25] fix(lite): a block must claim a draft that could send it A Property Block's encoding names the moq-transport drafts it came from, so ingress now refuses state none of them could produce, derived from the codec's per-draft tables: - DELIVERY_TIMEOUT unless a draft of the encoding assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT (encoding 4), on objects and TRACK_PROPERTIES. - A block on the END_OF_GROUP record unless a draft of the encoding lets a status object carry properties (encoding 1). - A datagram with a block unless a draft of the encoding defines its Type, its Status, and properties beside that Status. status_defined is now per draft, which the moq-transport datagram ingress and egress share in place of their own DOES_NOT_EXIST checks. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 4 ++ rs/moq-net/src/ietf/datagram.rs | 41 ++++++++------- rs/moq-net/src/ietf/object.rs | 26 +++++++--- rs/moq-net/src/ietf/publisher.rs | 7 +-- rs/moq-net/src/ietf/subscriber.rs | 9 +--- rs/moq-net/src/ietf/version.rs | 15 ++++++ rs/moq-net/src/lite/ietf.rs | 85 ++++++++++++++++++++++++++++++- rs/moq-net/src/lite/subscriber.rs | 2 +- 8 files changed, 150 insertions(+), 39 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 433c1f87a8d..f478fcf89ed 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -141,6 +141,7 @@ Properties { A receiver MUST treat any other encoding as malformed, including 0: an empty Properties says the object has none. DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that would read it differently. +Only drafts 19 and later assign it, so a receiver MUST treat DELIVERY_TIMEOUT with any encoding but 4 as malformed. **Property Block**: Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. @@ -149,6 +150,8 @@ It MUST NOT be empty or longer than 65,536 bytes. On a timed track an object with a FRAME, or a datagram without a Status, MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits. A receiver MUST treat a block its encoding's drafts would refuse as malformed. +The encoding names the drafts the object came from, so a receiver MUST also treat a block as malformed on an object none of them could send with properties. +Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record MUST have encoding 1, and a datagram with a block MUST have fields an OBJECT_DATAGRAM Type of those drafts carries ([Datagrams](#datagrams)). Other properties are opaque to this extension. ## Timestamps {#timestamps} @@ -234,6 +237,7 @@ A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payloa A non-zero Status carries no object: it has no Timestamp, even on a timed track. A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. +With Properties, only the drafts of their encoding count: from draft 17 on a non-zero Status carries no properties, so one needs encoding 1 or 2, and DOES_NOT_EXIST needs encoding 1. # Security Considerations diff --git a/rs/moq-net/src/ietf/datagram.rs b/rs/moq-net/src/ietf/datagram.rs index 16b91226275..803cf33a1d9 100644 --- a/rs/moq-net/src/ietf/datagram.rs +++ b/rs/moq-net/src/ietf/datagram.rs @@ -57,15 +57,6 @@ impl ObjectDatagram { } } - /// Whether any implemented draft defines this datagram's Type: draft-14 and every - /// later draft each define one set. - fn defined(&self) -> bool { - let kind = self.kind(); - [Version::Draft14, Version::Draft15] - .into_iter() - .any(|version| Self::valid(kind, version)) - } - /// The Type bits this datagram's fields set. fn kind(&self) -> u64 { let mut kind = 0; @@ -89,8 +80,9 @@ impl ObjectDatagram { } impl crate::model::datagram::Wire { - /// Whether moq-transport defines a datagram of this shape on some draft, as its ingress - /// checks one. Egress resolves the Object ID and priority each draft needs. + /// Whether a moq-transport draft defines a datagram of this shape, as its ingress checks + /// one, and a draft of its block's encoding when it has one: that draft sent it. Egress + /// resolves the Object ID and priority each draft needs. pub(crate) fn defined(&self) -> bool { let shape = ObjectDatagram { track_alias: 0, @@ -104,10 +96,27 @@ impl crate::model::datagram::Wire { None => DatagramBody::Payload(Bytes::new()), }, }; - shape.defined() && self.status.is_none_or(super::object::status_defined) + let kind = shape.kind(); + let family = self.properties.block.as_ref().map(|block| block.encoding); + Version::ALL + .into_iter() + .filter(|version| family.is_none_or(|family| super::object::encoding(*version) == family)) + .any(|version| { + ObjectDatagram::valid(kind, version) + && self.status.is_none_or(|status| { + super::object::status_defined(status, version) + && (family.is_none() || carries_properties(status, version)) + }) + }) } } +/// Whether `version` lets a datagram of Object Status `status` carry properties: from +/// draft-17 on, only a Normal Object may. +fn carries_properties(status: u64, version: Version) -> bool { + status == 0 || matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) +} + impl Encode for ObjectDatagram { fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { let kind = self.kind(); @@ -134,9 +143,7 @@ impl Encode for ObjectDatagram { match &self.body { DatagramBody::Status(status) => { - // Draft-17 on: only a Normal Object may carry Properties. - let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); - if !legacy && *status != 0 && self.properties.is_some() { + if self.properties.is_some() && !carries_properties(*status, version) { return Err(EncodeError::InvalidState); } w.varint(*status)? @@ -181,9 +188,7 @@ impl Decode for ObjectDatagram { let body = match kind & flag::STATUS != 0 { true => { let status = r.varint()?; - // Draft-17 on: only a Normal Object may carry Properties. - let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); - if !legacy && status != 0 && properties.is_some() { + if properties.is_some() && !carries_properties(status, version) { return Err(DecodeError::InvalidValue); } if !r.is_empty() { diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index eeb3c6ffe68..9b42ffcb330 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -7,7 +7,7 @@ use crate::{ model::object::{Encoding, Properties, Property, Value}, }; -pub(super) fn encoding(version: Version) -> Encoding { +pub(crate) fn encoding(version: Version) -> Encoding { match version { Version::Draft14 | Version::Draft15 => Encoding::Absolute, Version::Draft16 => Encoding::DeltaQuic, @@ -16,8 +16,16 @@ pub(super) fn encoding(version: Version) -> Encoding { } } +/// The drafts that serialize properties in the `family` encoding, one of which sent any +/// block claiming it. +pub(crate) fn drafts(family: Encoding) -> impl Iterator { + Version::ALL + .into_iter() + .filter(move |version| encoding(*version) == family) +} + /// Draft-19 assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. -pub(super) fn has_delivery_timeout(version: Version) -> bool { +pub(crate) fn has_delivery_timeout(version: Version) -> bool { !matches!( version, Version::Draft14 | Version::Draft15 | Version::Draft16 | Version::Draft17 | Version::Draft18 @@ -31,16 +39,18 @@ pub(crate) const END_OF_GROUP: u64 = 0x3; /// Object status: no object at or past this location exists (every implemented draft). pub(crate) const END_OF_TRACK: u64 = 0x4; -/// Whether any implemented draft defines the Object Status `status`, 0 being Normal. -/// -/// Egress drops a DOES_NOT_EXIST for a draft without it, so a relay may hold one. -pub(crate) fn status_defined(status: u64) -> bool { - matches!(status, 0 | DOES_NOT_EXIST | END_OF_GROUP | END_OF_TRACK) +/// Whether `version` defines the Object Status `status`, 0 being Normal. +pub(crate) fn status_defined(status: u64, version: Version) -> bool { + match status { + 0 | END_OF_GROUP | END_OF_TRACK => true, + DOES_NOT_EXIST => matches!(version, Version::Draft14 | Version::Draft15), + _ => false, + } } /// Only draft-14 lets a status object, such as END_OF_GROUP, carry properties. #[cfg(feature = "async")] -pub(super) fn status_has_properties(version: Version) -> bool { +pub(crate) fn status_has_properties(version: Version) -> bool { version == Version::Draft14 } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 7b3dc1c98fe..5353a244b5e 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -4418,8 +4418,9 @@ impl TrackServe { Some(wire) => { // A datagram this draft cannot carry is dropped like an oversized one: it // is best-effort, and the track's groups do not depend on it. - if wire.status == Some(DOES_NOT_EXIST) - && !matches!(self.version, Version::Draft14 | Version::Draft15) + if wire + .status + .is_some_and(|status| !super::object::status_defined(status, self.version)) { tracing::debug!(sequence, "dropping a datagram status this draft cannot carry"); continue; @@ -5100,7 +5101,7 @@ impl GroupServe { } } -use super::object::{DOES_NOT_EXIST, END_OF_GROUP, END_OF_TRACK}; +use super::object::{END_OF_GROUP, END_OF_TRACK}; /// An object's header, with private relay fields when it came from an IETF peer. struct Object<'a> { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 18bef38df0a..59c53127779 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4092,12 +4092,7 @@ where let (payload, status) = match datagram.body { ietf::DatagramBody::Payload(payload) => (payload, None), - ietf::DatagramBody::Status(DOES_NOT_EXIST) - if !matches!(self.version, Version::Draft14 | Version::Draft15) => - { - return Err(Error::Session(SessionError::ProtocolViolation)); - } - ietf::DatagramBody::Status(status) if super::object::status_defined(status) => { + ietf::DatagramBody::Status(status) if super::object::status_defined(status, self.version) => { (bytes::Bytes::new(), Some(status)) } ietf::DatagramBody::Status(_) => return Err(Error::Session(SessionError::ProtocolViolation)), @@ -4192,7 +4187,7 @@ enum Ended { Track { object: u64, properties: bool }, } -use super::object::{DOES_NOT_EXIST, END_OF_GROUP, END_OF_TRACK}; +use super::object::{END_OF_GROUP, END_OF_TRACK}; /// The start of a subgroup stream's first object, peeked before its group is created. #[derive(Debug, Clone, Copy)] diff --git a/rs/moq-net/src/ietf/version.rs b/rs/moq-net/src/ietf/version.rs index 0e29f184548..3eddd2be5a8 100644 --- a/rs/moq-net/src/ietf/version.rs +++ b/rs/moq-net/src/ietf/version.rs @@ -15,6 +15,21 @@ pub enum Version { Draft22, } +impl Version { + /// Every implemented draft, oldest first. + pub(crate) const ALL: [Self; 9] = [ + Self::Draft14, + Self::Draft15, + Self::Draft16, + Self::Draft17, + Self::Draft18, + Self::Draft19, + Self::Draft20, + Self::Draft21, + Self::Draft22, + ]; +} + impl fmt::Display for Version { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index ae47c3d3d25..b1e8b08e8e1 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -133,7 +133,16 @@ fn decode_encoding(code: u64) -> Result, DecodeError> { } fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { - Ok((flags & DELIVERY_TIMEOUT != 0, decode_encoding(flags >> 1)?)) + let delivery_timeout = flags & DELIVERY_TIMEOUT != 0; + let encoding = decode_encoding(flags >> 1)?; + // Only a draft that assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT sets it. + if delivery_timeout + && !encoding.is_some_and(|encoding| { + crate::ietf::object::drafts(encoding).any(crate::ietf::object::has_delivery_timeout) + }) { + return Err(DecodeError::InvalidValue); + } + Ok((delivery_timeout, encoding)) } /// Track Properties delta-encoded in the family they arrived in, as moq-transport sent @@ -254,6 +263,19 @@ pub(crate) fn decode_properties( }) } +/// Decode the END_OF_GROUP record's body on a track in `timescale`. It is a status +/// object, so a block must claim a draft that lets one carry properties. +#[cfg(feature = "async")] +pub(crate) fn decode_end(body: &[u8], timescale: Option, version: Version) -> Result { + let decoded = decode_properties(body, timescale, false, version)?; + if let Some(block) = &decoded.properties.block + && !crate::ietf::object::drafts(block.encoding).any(crate::ietf::object::status_has_properties) + { + return Err(DecodeError::InvalidValue); + } + Ok(decoded) +} + /// A group stream's object records on egress, sent before each frame once the extension /// is negotiated. #[cfg(feature = "async")] @@ -549,7 +571,7 @@ mod tests { ]; let properties = Properties { sealed_time: Some(crate::Timestamp::new(77, Timescale::MILLI).unwrap()), - block: crate::ietf::object::block(&values, Encoding::DeltaQuic, true).unwrap(), + block: crate::ietf::object::block(&values, Encoding::DeltaQuic, false).unwrap(), }; let body = encode_properties(&properties, V).unwrap(); let decoded = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); @@ -896,6 +918,65 @@ mod tests { assert_eq!(wire.properties.heap(), block.len() as u64); assert!(wire.properties.heap() < (COUNT * size_of::()) as u64 / 10); } + + /// A body holding property 0x20 = 1, which every family serializes alike, claiming the + /// encoding `code`. + fn claiming(code: u8, delivery_timeout: bool) -> [u8; 3] { + [code << 1 | u8::from(delivery_timeout), 0x20, 1] + } + + /// DELIVERY_TIMEOUT names the draft-19 meaning of 0x06, so only a block or list claiming + /// the draft-18-and-later encoding may set it. + #[test] + fn delivery_timeout_claims_a_draft_that_assigns_it() { + for code in 1..=4 { + let ok = code == 4; + assert_eq!( + decode_properties(&claiming(code, true), None, true, V).is_ok(), + ok, + "{code}" + ); + assert!( + decode_properties(&claiming(code, false), None, true, V).is_ok(), + "{code}" + ); + let list = |delivery_timeout| { + TrackProperties::decode_msg(&mut Decoder::new(&claiming(code, delivery_timeout), V.into()), V).is_ok() + }; + assert_eq!(list(true), ok, "{code}"); + // Track Properties start at draft-16. + assert_eq!(list(false), code != 1, "{code}"); + } + } + + /// Only draft-14 lets a status object carry properties, so the END_OF_GROUP record's + /// block must claim the drafts 14 and 15 encoding. + #[cfg(feature = "async")] + #[test] + fn an_end_record_block_claims_a_draft_that_carries_one() { + for code in 1..=4 { + assert_eq!(decode_end(&claiming(code, false), None, V).is_ok(), code == 1, "{code}"); + } + assert!(decode_end(&[], None, V).is_ok()); + } + + /// A datagram's block names its family, so one of those drafts must define the whole + /// datagram: from draft-17 on a non-zero Status carries no properties, and only drafts + /// 14 and 15 define DOES_NOT_EXIST. + #[test] + fn a_datagram_block_claims_a_draft_that_sends_its_shape() { + for (status, codes) in [(0, &[1, 2, 3, 4][..]), (1, &[1]), (3, &[1, 2]), (4, &[1, 2])] { + for code in 1..=4 { + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(RELAYED | STATUS).unwrap(); + w.varint(status).unwrap(); + w.bytes(&claiming(code, false)).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V); + assert_eq!(decoded.is_ok(), codes.contains(&code), "{status}: {code}"); + } + } + } } /// Peer a relay behind `upstream` over moq-lite 07, the way a cluster does. The client diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 3c26c42cb9a..742411fcbd0 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1169,7 +1169,7 @@ impl FrameIngest { return Poll::Ready(Err(Error::ProtocolViolation)); } if end { - let decoded = lite::ietf::decode_properties(&block, self.timescale, false, self.version)?; + let decoded = lite::ietf::decode_end(&block, self.timescale, self.version)?; group.mark_gap(id, decoded.gap)?; group.set_end_object(crate::model::object::Fields { id, From a5f85e62fa8ac83664396be533fe02e84f8cb542 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 09:36:04 -0700 Subject: [PATCH 20/25] feat(lite): name each property encoding by its drafts, without flags A Property Block and TRACK_PROPERTIES now lead with one Encoding code, 1 to 5, with draft 18 (4) apart from drafts 19 and later (5). Whether property 0x06 means SUBGROUP_DELIVERY_TIMEOUT follows from the code, so the DELIVERY_TIMEOUT flag bit and the check refusing it beside codes 1 to 3 are gone: the impossible pairing has no encoding. The model's Encoding names the same five families. Codes 4 and 5 serialize alike, so egress compares them with same_bytes where it asks whether a block can cross unchanged. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 38 ++++---- rs/moq-net/src/fuzz.rs | 3 +- rs/moq-net/src/ietf/object.rs | 60 +++++++----- rs/moq-net/src/ietf/properties.rs | 9 +- rs/moq-net/src/ietf/publisher.rs | 11 ++- rs/moq-net/src/ietf/subscriber.rs | 3 +- rs/moq-net/src/lite/datagram.rs | 3 +- rs/moq-net/src/lite/ietf.rs | 152 ++++++++++++------------------ rs/moq-net/src/lite/subscriber.rs | 10 +- rs/moq-net/src/model/object.rs | 22 +++-- 10 files changed, 149 insertions(+), 162 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index f478fcf89ed..d5167d41e32 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -114,7 +114,7 @@ Object Record { **Properties**: The object's [properties](#properties), in `Properties Length` bytes. An empty one means the object has none. -A receiver MUST reset the stream if the length exceeds 65,537, the largest Property Block beside a Flags byte. +A receiver MUST reset the stream if the length exceeds 65,537, the largest Property Block beside an Encoding byte. In a plain group, every record has a `Skip` of 0 after the first, whose Object ID is the index of its frame, no properties, and `End` of 0. A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other record in a plain group. @@ -129,19 +129,24 @@ A relay forwards the block to a peer of that encoding unchanged, so the block ne ~~~ Properties { - Flags (i) + Encoding (i) Property Block (..) } ~~~ -**Flags**: +**Encoding**: +The {{moqt}} drafts the Property Block came from, which serialize it alike and give each property the same meaning: -- `0x1` **DELIVERY_TIMEOUT**: The publisher's {{moqt}} draft assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. -- `Flags >> 1` names the Property Block's encoding: 1 for drafts 14 and 15 (absolute IDs and QUIC varints), 2 for draft 16 (delta IDs and QUIC varints), 3 for draft 17, and 4 for draft 18 and later. +| Code | Drafts | IDs | Varints | +|-----:|:-------|:----|:--------| +| 1 | 14 and 15 | absolute | QUIC | +| 2 | 16 | delta | QUIC | +| 3 | 17 | delta | draft 17 | +| 4 | 18 | delta | draft 18 | +| 5 | 19 and later | delta | draft 18 | -A receiver MUST treat any other encoding as malformed, including 0: an empty Properties says the object has none. -DELIVERY_TIMEOUT lets a relay refuse to forward property 0x06 to a draft that would read it differently. -Only drafts 19 and later assign it, so a receiver MUST treat DELIVERY_TIMEOUT with any encoding but 4 as malformed. +A receiver MUST treat any other code as malformed, including 0: an empty Properties says the object has none. +Codes 4 and 5 serialize alike, but only drafts 19 and later assign property 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so a relay knows not to forward 0x06 to a draft that would read it differently. **Property Block**: Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. @@ -150,8 +155,8 @@ It MUST NOT be empty or longer than 65,536 bytes. On a timed track an object with a FRAME, or a datagram without a Status, MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits. A receiver MUST treat a block its encoding's drafts would refuse as malformed. -The encoding names the drafts the object came from, so a receiver MUST also treat a block as malformed on an object none of them could send with properties. -Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record MUST have encoding 1, and a datagram with a block MUST have fields an OBJECT_DATAGRAM Type of those drafts carries ([Datagrams](#datagrams)). +The Encoding names the drafts the object came from, so a receiver MUST also treat a block as malformed on an object none of them could send with properties. +Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record MUST have Encoding 1, and a datagram with a block MUST have fields an OBJECT_DATAGRAM Type of those drafts carries ([Datagrams](#datagrams)). Other properties are opaque to this extension. ## Timestamps {#timestamps} @@ -170,16 +175,15 @@ When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message ~~~ TRACK_PROPERTIES Message { Message Length (i) - Flags (i) + Encoding (i) Property List (..) } ~~~ -**Flags**: -Bit `0x1` is DELIVERY_TIMEOUT, as in [Properties](#properties). -`Flags >> 1` names the Property List's encoding, with the codes of [Properties](#properties). -A message without properties MUST have a Flags of 0 and an empty Property List. -Track Properties start at draft 16, so any other message with an encoding of 0 or 1 is malformed. +**Encoding**: +The drafts the Property List came from, with the codes of [Properties](#properties). +A message without properties MUST have an Encoding of 0 and an empty Property List. +Track Properties start at draft 16, so any other message with an Encoding of 0 or 1 is malformed. **Property List**: The {{moqt}} Track Properties a relay forwards without interpreting, serialized as the publisher's draft serializes them: in ascending ID order, with delta-encoded IDs and the varints of that encoding. @@ -237,7 +241,7 @@ A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payloa A non-zero Status carries no object: it has no Timestamp, even on a timed track. A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. -With Properties, only the drafts of their encoding count: from draft 17 on a non-zero Status carries no properties, so one needs encoding 1 or 2, and DOES_NOT_EXIST needs encoding 1. +With Properties, only the drafts of their Encoding count: from draft 17 on a non-zero Status carries no properties, so one needs Encoding 1 or 2, and DOES_NOT_EXIST needs Encoding 1. # Security Considerations diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 929a8b16452..928b9971f6a 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -40,8 +40,7 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr id: 0x80, value: crate::model::object::Value::Int(96_000), }], - crate::model::object::Encoding::Delta { seven: true }, - true, + crate::model::object::Encoding::Draft19, ) .unwrap(), ..Default::default() diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 9b42ffcb330..63d0e7b42e1 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -3,19 +3,31 @@ use bytes::Bytes; use super::Version; use crate::{ Error, Timescale, Timestamp, - coding::{Decoder, Encoder}, + coding::{Decoder, Encoder, Form}, model::object::{Encoding, Properties, Property, Value}, }; pub(crate) fn encoding(version: Version) -> Encoding { match version { - Version::Draft14 | Version::Draft15 => Encoding::Absolute, - Version::Draft16 => Encoding::DeltaQuic, - Version::Draft17 => Encoding::Delta { seven: false }, - _ => Encoding::Delta { seven: true }, + Version::Draft14 | Version::Draft15 => Encoding::Draft14, + Version::Draft16 => Encoding::Draft16, + Version::Draft17 => Encoding::Draft17, + Version::Draft18 => Encoding::Draft18, + _ => Encoding::Draft19, } } +/// Whether lists in encodings `a` and `b` are the same bytes: the same keys and varints. +pub(crate) fn same_bytes(a: Encoding, b: Encoding) -> bool { + let form = |encoding| (encoding == Encoding::Draft14, Form::from(family(encoding))); + form(a) == form(b) +} + +/// Whether property 0x06 means SUBGROUP_DELIVERY_TIMEOUT in a list from `encoding`. +pub(crate) fn delivery_timeout(encoding: Encoding) -> bool { + has_delivery_timeout(family(encoding)) +} + /// The drafts that serialize properties in the `family` encoding, one of which sent any /// block claiming it. pub(crate) fn drafts(family: Encoding) -> impl Iterator { @@ -121,8 +133,8 @@ fn list(data: &Bytes, version: Version, immutable: bool, lift: bool) -> Result key, - Encoding::Delta { .. } | Encoding::DeltaQuic => previous.checked_add(key).ok_or(Error::MalformedTrack)?, + Encoding::Draft14 => key, + _ => previous.checked_add(key).ok_or(Error::MalformedTrack)?, }; previous = id; let value = if id % 2 == 0 { @@ -175,8 +187,8 @@ fn serialize<'a>(values: impl IntoIterator, encoding: Encod let mut previous = 0; for property in sorted { encoder.varint(match encoding { - Encoding::Absolute => property.id, - Encoding::Delta { .. } | Encoding::DeltaQuic => property.id - previous, + Encoding::Draft14 => property.id, + _ => property.id - previous, })?; previous = property.id; match &property.value { @@ -192,11 +204,7 @@ fn serialize<'a>(values: impl IntoIterator, encoding: Encod /// /// Sorting a delta-encoded list, which arrives ascending, and dropping its Timestamp /// never grows it, so the block fits wherever the publisher's list did. -pub(crate) fn block( - values: &[Property], - encoding: Encoding, - delivery_timeout: bool, -) -> Result, Error> { +pub(crate) fn block(values: &[Property], encoding: Encoding) -> Result, Error> { if values.is_empty() { return Ok(None); } @@ -204,7 +212,6 @@ pub(crate) fn block( bytes: serialize(values, encoding)?.into(), encoding, immutable: values.iter().any(|property| property.id == 0x0b), - delivery_timeout, })) } @@ -281,7 +288,7 @@ fn decode(data: &Bytes, version: Version, timescale: Option, framed: let parsed = list(data, version, false, lifted.is_some())?; let properties = Properties { sealed_time: timed(parsed.sealed_time, timescale)?, - block: block(&parsed.values, encoding(version), has_delivery_timeout(version))?, + block: block(&parsed.values, encoding(version))?, }; // A list at the limit with a small Timestamp cannot take back a larger one on egress. if properties.heap() > max_block(lifted) as u64 { @@ -330,10 +337,11 @@ pub(crate) fn egress_time( /// parses its keys and integers the same way. pub(crate) fn family(encoding: Encoding) -> Version { match encoding { - Encoding::Absolute => Version::Draft14, - Encoding::DeltaQuic => Version::Draft16, - Encoding::Delta { seven: false } => Version::Draft17, - Encoding::Delta { seven: true } => Version::Draft18, + Encoding::Draft14 => Version::Draft14, + Encoding::Draft16 => Version::Draft16, + Encoding::Draft17 => Version::Draft17, + Encoding::Draft18 => Version::Draft18, + Encoding::Draft19 => Version::Draft19, } } @@ -354,14 +362,14 @@ pub(crate) fn write( let Some(block) = &properties.block else { return serialize(×tamp, target); }; - if block.immutable && block.encoding != target { + if block.immutable && !same_bytes(block.encoding, target) { return Err(Error::Unsupported); } // Across draft-19, forwarding 0x06 would give it a different meaning. // A mutable one is dropped; a sealed one is refused. - let flipped = block.delivery_timeout != has_delivery_timeout(version); + let flipped = delivery_timeout(block.encoding) != has_delivery_timeout(version); // The common case: the block is already what this draft would send. - if timestamp.is_none() && !flipped && block.encoding == target { + if timestamp.is_none() && !flipped && same_bytes(block.encoding, target) { return Ok(block.bytes.to_vec()); } let values = values(block)?; @@ -595,7 +603,7 @@ mod tests { assert!(read(&list(MAX_BLOCK - 2), Version::Draft22, None).is_ok()); // The same bound on a block arriving over the lite hop. - let encoding = Encoding::Delta { seven: true }; + let encoding = Encoding::Draft19; assert!(check(&block(limit), encoding, milli, true).is_ok()); assert!(check(&block(limit + 1), encoding, milli, true).is_err()); assert!(check(&block(limit + 1), encoding, None, true).is_ok()); @@ -614,8 +622,8 @@ mod tests { // Over the lite hop, only a status block may hold it. let block = status.block.unwrap().bytes; - assert!(check(&block, Encoding::Absolute, milli, false).is_ok()); - assert!(check(&block, Encoding::Absolute, milli, true).is_err()); + assert!(check(&block, Encoding::Draft14, milli, false).is_ok()); + assert!(check(&block, Encoding::Draft14, milli, true).is_err()); } /// Draft-19 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so it cannot cross that boundary. diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index d7f6867f890..bbdf0442a9d 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -238,7 +238,6 @@ impl Properties { // Recorded only beside a value they describe, so a set with nothing to forward stays empty. let forwarded = !properties.unknown.values.is_empty(); properties.unknown.encoding = forwarded.then(|| super::object::encoding(version)); - properties.unknown.delivery_timeout = forwarded && super::object::has_delivery_timeout(version); Ok(properties) } @@ -299,7 +298,7 @@ pub(crate) const MAX_FORWARDED: usize = MAX_PROPERTIES as usize - UNDERSTOOD.len /// family, as [`Properties::decode`] does. pub(crate) fn check_immutable(block: &[u8], encoding: crate::model::object::Encoding) -> Result<(), DecodeError> { // Track Properties start at draft-16, whose families all delta-encode their keys. - if encoding == crate::model::object::Encoding::Absolute { + if encoding == crate::model::object::Encoding::Draft14 { return Err(DecodeError::InvalidValue); } let version = super::object::family(encoding); @@ -769,9 +768,7 @@ mod tests { value: Value::Int(1), }) .collect(), - encoding: Some(crate::model::object::Encoding::Delta { seven: true }), - // Draft-22 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT. - delivery_timeout: true, + encoding: Some(crate::model::object::Encoding::Draft19), }; let properties = Properties { max_cache_duration: Some(Duration::from_secs(1)), @@ -809,7 +806,6 @@ mod tests { value: Value::Bytes(block.into()), }], encoding: Some(super::super::object::encoding(version)), - delivery_timeout: true, }; let info = crate::track::Info::default() .with_max_age(Duration::from_secs(7)) @@ -867,7 +863,6 @@ mod tests { value: Value::Bytes(sealed.clone().into()), }], encoding: Some(super::super::object::encoding(version)), - delivery_timeout: true, }; let egress = Properties { unknown: unknown.clone(), diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 5353a244b5e..93a9f877b49 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -55,12 +55,19 @@ fn track_properties(info: &track::Info, wanted: bool, version: Version) -> Resul } let mut unknown = info.properties.as_deref().cloned().unwrap_or_default(); let block = !matches!(version, Version::Draft14 | Version::Draft15); - if block && unknown.immutable().is_some() && unknown.encoding != Some(super::object::encoding(version)) { + if block + && unknown.immutable().is_some() + && !unknown + .encoding + .is_some_and(|encoding| super::object::same_bytes(encoding, super::object::encoding(version))) + { return Err(Error::Unsupported); } // Across draft-19, forwarding 0x06 would give it a different meaning, as for object // properties. A mutable one is dropped; a sealed one is refused. - if !unknown.values.is_empty() && unknown.delivery_timeout != super::object::has_delivery_timeout(version) { + if unknown.encoding.is_some_and(|encoding| { + super::object::delivery_timeout(encoding) != super::object::has_delivery_timeout(version) + }) { if block && unknown.sealed().any(|id| id == 0x06) { return Err(Error::Unsupported); } diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 59c53127779..9b4fdf777bc 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -12849,7 +12849,8 @@ mod stitch_tests { ] { let script = object_stream(ingress, true, &[(0, &properties, None)]); let (bytes, log) = relay_passthrough_stream(script, ingress, egress).await; - if super::super::object::encoding(ingress) != super::super::object::encoding(egress) { + let encoding = super::super::object::encoding; + if !super::super::object::same_bytes(encoding(ingress), encoding(egress)) { assert!(!log.resets().is_empty(), "incompatible immutable bytes must be refused"); continue; } diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 6b54c8fa80e..3b243b0f4fd 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -224,8 +224,7 @@ mod test { id, value: crate::model::object::Value::Int(7), }], - crate::model::object::Encoding::Delta { seven: true }, - true, + crate::model::object::Encoding::Draft19, ) .unwrap(), ..Default::default() diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index b1e8b08e8e1..70096b4865f 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -33,9 +33,6 @@ const PRIORITY: u64 = 0x4; const DATAGRAM_END: u64 = 0x8; const STATUS: u64 = 0x10; -// Flags of a block and of TRACK_PROPERTIES: property 0x06 means SUBGROUP_DELIVERY_TIMEOUT. -const DELIVERY_TIMEOUT: u64 = 0x1; - /// Immutable Properties, whose keys TRACK_PROPERTIES derives its sealed list from. const IMMUTABLE: u64 = 0x0b; @@ -107,44 +104,29 @@ pub(crate) fn decode_object(prior: Option, code: u64) -> Result<(u64, bool) Ok((id.ok_or(Error::ProtocolViolation)?, code & 1 != 0)) } -fn encoding_code(encoding: Option) -> u64 { +fn encode_encoding(encoding: Option) -> u64 { match encoding { None => 0, - Some(Encoding::Absolute) => 1, - Some(Encoding::DeltaQuic) => 2, - Some(Encoding::Delta { seven: false }) => 3, - Some(Encoding::Delta { seven: true }) => 4, + Some(Encoding::Draft14) => 1, + Some(Encoding::Draft16) => 2, + Some(Encoding::Draft17) => 3, + Some(Encoding::Draft18) => 4, + Some(Encoding::Draft19) => 5, } } -fn encode_flags(delivery_timeout: bool, immutable: Option) -> u64 { - u64::from(delivery_timeout) | encoding_code(immutable) << 1 -} - fn decode_encoding(code: u64) -> Result, DecodeError> { Ok(match code { 0 => None, - 1 => Some(Encoding::Absolute), - 2 => Some(Encoding::DeltaQuic), - 3 => Some(Encoding::Delta { seven: false }), - 4 => Some(Encoding::Delta { seven: true }), + 1 => Some(Encoding::Draft14), + 2 => Some(Encoding::Draft16), + 3 => Some(Encoding::Draft17), + 4 => Some(Encoding::Draft18), + 5 => Some(Encoding::Draft19), _ => return Err(DecodeError::InvalidValue), }) } -fn decode_flags(flags: u64) -> Result<(bool, Option), DecodeError> { - let delivery_timeout = flags & DELIVERY_TIMEOUT != 0; - let encoding = decode_encoding(flags >> 1)?; - // Only a draft that assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT sets it. - if delivery_timeout - && !encoding.is_some_and(|encoding| { - crate::ietf::object::drafts(encoding).any(crate::ietf::object::has_delivery_timeout) - }) { - return Err(DecodeError::InvalidValue); - } - Ok((delivery_timeout, encoding)) -} - /// Track Properties delta-encoded in the family they arrived in, as moq-transport sent /// them less the properties TRACK_INFO carries, so the list is never wider than it arrived. /// @@ -213,7 +195,7 @@ pub(crate) fn encode_properties(properties: &Properties, version: Version) -> Re return Ok(out); }; let w = &mut Encoder::new(&mut out, version.into()); - w.varint(encode_flags(block.delivery_timeout, Some(block.encoding)))?; + w.varint(encode_encoding(Some(block.encoding)))?; w.slice(&block.bytes); Ok(out) } @@ -242,9 +224,8 @@ pub(crate) fn decode_properties( }); } let r = &mut Decoder::new(body, version.into()); - let (delivery_timeout, encoding) = decode_flags(r.varint()?)?; // An empty body is how nothing at all is sent. - let encoding = encoding.ok_or(DecodeError::InvalidValue)?; + let encoding = decode_encoding(r.varint()?)?.ok_or(DecodeError::InvalidValue)?; // A small cached block must not pin the reader's larger receive buffer. let bytes = Bytes::copy_from_slice(&body[body.len() - r.remaining()..]); let checked = @@ -256,7 +237,6 @@ pub(crate) fn decode_properties( bytes, encoding, immutable: checked.immutable, - delivery_timeout, }), }, gap: checked.gap, @@ -381,33 +361,31 @@ pub struct TrackProperties(pub Option impl Message for TrackProperties { fn encode_msg(&self, w: &mut Encoder<'_>, _: Version) -> Result<(), EncodeError> { - // Flags only ever describe values, so none at all is a lone 0. + // An encoding only ever describes values, so none at all is a lone 0. let Some(properties) = self.0.as_ref().filter(|properties| !properties.values.is_empty()) else { return w.varint(0); }; - w.varint(encode_flags(properties.delivery_timeout, properties.encoding))?; + w.varint(encode_encoding(properties.encoding))?; w.slice(&encode_list(properties)?); Ok(()) } fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { - let flags = r.varint()?; + let code = r.varint()?; if r.is_empty() { // Only the canonical form, so what decodes re-encodes to the same bytes. - return match flags { + return match code { 0 => Ok(Self(None)), _ => Err(DecodeError::InvalidValue), }; } - let (delivery_timeout, encoding) = decode_flags(flags)?; // Track Properties start at draft-16, whose families all delta-encode their keys. - let encoding = encoding - .filter(|encoding| *encoding != Encoding::Absolute) + let encoding = decode_encoding(code)? + .filter(|encoding| *encoding != Encoding::Draft14) .ok_or(DecodeError::InvalidValue)?; let properties = crate::model::object::TrackProperties { values: decode_list(r, encoding)?, encoding: Some(encoding), - delivery_timeout, }; // TRACK_INFO carries these, so a second copy could only contradict it. if properties @@ -571,7 +549,7 @@ mod tests { ]; let properties = Properties { sealed_time: Some(crate::Timestamp::new(77, Timescale::MILLI).unwrap()), - block: crate::ietf::object::block(&values, Encoding::DeltaQuic, false).unwrap(), + block: crate::ietf::object::block(&values, Encoding::Draft16).unwrap(), }; let body = encode_properties(&properties, V).unwrap(); let decoded = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); @@ -584,7 +562,7 @@ mod tests { assert_eq!(empty.properties, Properties::default()); // An untimed track's Timestamp has no frame to hold it, so it stays in the block. - let untimed = [4 << 1, 0x10, 7]; + let untimed = [4, 0x10, 7]; let decoded = decode_properties(&untimed, None, true, V).unwrap(); assert_eq!(encode_properties(&decoded.properties, V).unwrap(), untimed); } @@ -592,12 +570,11 @@ mod tests { /// Only the canonical form decodes, so whatever decodes re-encodes to the same bytes. #[test] fn properties_refuse_what_is_not_canonical() { - let delta = 4 << 1; + let delta = 4; for (body, reason) in [ - (&[0][..], "flags saying nothing"), - (&[DELIVERY_TIMEOUT as u8][..], "DELIVERY_TIMEOUT without a block"), + (&[0][..], "an encoding saying nothing"), (&[delta][..], "an encoding with an empty block"), - (&[5 << 1, 0x20, 1][..], "an unknown encoding"), + (&[6, 0x20, 1][..], "an unknown encoding"), ( &[delta, 0x10, 5][..], "a timed track's mutable Timestamp, which its frame holds", @@ -658,8 +635,7 @@ mod tests { value: Value::Bytes(Bytes::from_static(b"opaque")), }, ], - encoding: Some(Encoding::Delta { seven: true }), - delivery_timeout: true, + encoding: Some(Encoding::Draft19), }; let msg = TrackProperties(Some(Arc::new(properties.clone()))); let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); @@ -680,11 +656,10 @@ mod tests { let wire = |values: &[Property], code: u64| { let mut buf = Vec::new(); let w = &mut Encoder::new(&mut buf, V.into()); - w.varint(code << 1).unwrap(); + w.varint(code).unwrap(); let list = encode_list(&crate::model::object::TrackProperties { values: values.to_vec(), - encoding: Some(Encoding::Delta { seven: true }), - ..Default::default() + encoding: Some(Encoding::Draft18), }) .unwrap(); w.slice(&list); @@ -703,7 +678,7 @@ mod tests { // TIMESCALE belongs to TRACK_INFO. assert!(decode(&wire(&[opaque(0x08)], 4)).is_err(), "an understood property"); assert!(decode(&wire(&[opaque(0x40)], 0)).is_err(), "a list needs its encoding"); - assert!(decode(&[1 << 1]).is_err(), "flags without a list"); + assert!(decode(&[2]).is_err(), "an encoding without a list"); assert!( decode(&wire(&[opaque(0x40)], 1)).is_err(), "track properties never use absolute keys" @@ -735,8 +710,7 @@ mod tests { id: IMMUTABLE, value: Value::Bytes(sealed.into()), }], - encoding: Some(Encoding::Delta { seven: true }), - delivery_timeout: false, + encoding: Some(Encoding::Draft18), }))); let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); let decoded = >::decode(&mut Decoder::new(&buf, V.into()), V) @@ -906,7 +880,7 @@ mod tests { for _ in 1..COUNT { block.extend([0, 1]); } - let mut body = vec![4 << 1]; + let mut body = vec![4]; body.extend(&block); let mut buf = Vec::new(); let w = &mut Encoder::new(&mut buf, V.into()); @@ -921,31 +895,31 @@ mod tests { /// A body holding property 0x20 = 1, which every family serializes alike, claiming the /// encoding `code`. - fn claiming(code: u8, delivery_timeout: bool) -> [u8; 3] { - [code << 1 | u8::from(delivery_timeout), 0x20, 1] + fn claiming(code: u8) -> [u8; 3] { + [code, 0x20, 1] } - /// DELIVERY_TIMEOUT names the draft-19 meaning of 0x06, so only a block or list claiming - /// the draft-18-and-later encoding may set it. + /// Each code names the drafts a block came from, so whether 0x06 means + /// SUBGROUP_DELIVERY_TIMEOUT follows from it: only for code 5, drafts 19 and later. #[test] - fn delivery_timeout_claims_a_draft_that_assigns_it() { - for code in 1..=4 { - let ok = code == 4; - assert_eq!( - decode_properties(&claiming(code, true), None, true, V).is_ok(), - ok, - "{code}" - ); - assert!( - decode_properties(&claiming(code, false), None, true, V).is_ok(), - "{code}" - ); - let list = |delivery_timeout| { - TrackProperties::decode_msg(&mut Decoder::new(&claiming(code, delivery_timeout), V.into()), V).is_ok() - }; - assert_eq!(list(true), ok, "{code}"); + fn encoding_codes_name_their_drafts() { + for code in 1..=5 { + let decoded = decode_properties(&claiming(code), None, true, V).unwrap(); + let encoding = decoded.properties.block.unwrap().encoding; + assert_eq!(encode_encoding(Some(encoding)), u64::from(code)); + assert_eq!(crate::ietf::object::delivery_timeout(encoding), code == 5, "{code}"); + let list = TrackProperties::decode_msg(&mut Decoder::new(&claiming(code), V.into()), V); // Track Properties start at draft-16. - assert_eq!(list(false), code != 1, "{code}"); + assert_eq!(list.is_ok(), code != 1, "{code}"); + } + assert!(decode_properties(&claiming(6), None, true, V).is_err()); + + // A draft-18 0x06 is dropped on its way to draft-19, where it would mean a timeout. + for (code, kept) in [(4, false), (5, true)] { + let decoded = decode_properties(&[code, 0x06, 42], None, true, V).unwrap(); + let written = + crate::ietf::object::write(&decoded.properties, None, crate::ietf::Version::Draft19, None).unwrap(); + assert_eq!(!written.is_empty(), kept, "{code}"); } } @@ -954,8 +928,8 @@ mod tests { #[cfg(feature = "async")] #[test] fn an_end_record_block_claims_a_draft_that_carries_one() { - for code in 1..=4 { - assert_eq!(decode_end(&claiming(code, false), None, V).is_ok(), code == 1, "{code}"); + for code in 1..=5 { + assert_eq!(decode_end(&claiming(code), None, V).is_ok(), code == 1, "{code}"); } assert!(decode_end(&[], None, V).is_ok()); } @@ -965,13 +939,13 @@ mod tests { /// 14 and 15 define DOES_NOT_EXIST. #[test] fn a_datagram_block_claims_a_draft_that_sends_its_shape() { - for (status, codes) in [(0, &[1, 2, 3, 4][..]), (1, &[1]), (3, &[1, 2]), (4, &[1, 2])] { - for code in 1..=4 { + for (status, codes) in [(0, &[1, 2, 3, 4, 5][..]), (1, &[1]), (3, &[1, 2]), (4, &[1, 2])] { + for code in 1..=5 { let mut buf = Vec::new(); let w = &mut Encoder::new(&mut buf, V.into()); w.varint(RELAYED | STATUS).unwrap(); w.varint(status).unwrap(); - w.bytes(&claiming(code, false)).unwrap(); + w.bytes(&claiming(code)).unwrap(); let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V); assert_eq!(decoded.is_ok(), codes.contains(&code), "{status}: {code}"); } @@ -1050,7 +1024,7 @@ mod hop_tests { /// The block a draft-22 publisher's `values` arrive as. fn block(values: &[Property]) -> Option { - crate::ietf::object::block(values, Encoding::Delta { seven: true }, true).unwrap() + crate::ietf::object::block(values, Encoding::Draft19).unwrap() } /// Write a frame carrying relay `fields`, as moq-transport ingress does. @@ -1122,8 +1096,7 @@ mod hop_tests { info.priority = 9; let track_properties = crate::model::object::TrackProperties { values: vec![property(0x40, 3)], - encoding: Some(Encoding::Delta { seven: true }), - ..Default::default() + encoding: Some(Encoding::Draft19), }; info.properties = Some(Arc::new(track_properties.clone())); let track = broadcast.create_track("video", info).unwrap(); @@ -1307,8 +1280,7 @@ mod hop_tests { ] { let res = subscribe_across(crate::model::object::TrackProperties { values: values.clone(), - encoding: Some(Encoding::Delta { seven: true }), - ..Default::default() + encoding: Some(Encoding::Draft19), }) .await; assert!( @@ -1332,8 +1304,7 @@ mod hop_tests { id: IMMUTABLE, value: Value::Bytes(sealed.into()), }], - encoding: Some(Encoding::Delta { seven: true }), - ..Default::default() + encoding: Some(Encoding::Draft19), }) .await; match ok { @@ -1351,8 +1322,7 @@ mod hop_tests { for (count, ok) in [(max, true), (max + 1, false)] { let res = subscribe_across(crate::model::object::TrackProperties { values: (0..count as u64).map(|i| property(0x40 + 2 * i, 1)).collect(), - encoding: Some(Encoding::Delta { seven: true }), - ..Default::default() + encoding: Some(Encoding::Draft19), }) .await; match ok { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 742411fcbd0..6fc1c51f1d9 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -2532,7 +2532,7 @@ mod tests { #[moq_clock::test] async fn ietf_records_need_extensions_for_properties() { // Object 0 with a draft-18 block holding 0x20 = 1, or an untimed Timestamp. - for record in [&[3, 4 << 1, 0x20, 1][..], &[3, 4 << 1, 0x10, 7]] { + for record in [&[3, 4, 0x20, 1][..], &[3, 4, 0x10, 7]] { for (state, ok) in [(0x1 | 0x4, true), (0x1, false)] { let mut body = vec![state, 0]; body.extend(record); @@ -2552,9 +2552,9 @@ mod tests { // Each record after its Object code: Object 0 unless it says otherwise. for (record, ok, reason) in [ (&[0, 0][..], true, "nothing at all"), - (&[0, 4, 4 << 1, 0x10, 500], false, "a mutable Timestamp"), - (&[0, 3, 4 << 1, 0x20, 1], true, "properties without a Timestamp"), - (&[0, 6, 4 << 1, 0x0b, 3, 0x10, 499], true, "a sealed Timestamp"), + (&[0, 4, 4, 0x10, 500], false, "a mutable Timestamp"), + (&[0, 3, 4, 0x20, 1], true, "properties without a Timestamp"), + (&[0, 6, 4, 0x0b, 3, 0x10, 499], true, "a sealed Timestamp"), (&[1 << 1, 0], true, "Object 1 without properties"), ] { let mut body = vec![0x1 | 0x4]; @@ -2577,7 +2577,7 @@ mod tests { const COUNT: u64 = 1000; // A relayed group's Object 0, whose draft-18 block holds COUNT two-byte properties // (0x20 = 1, then zero deltas), then an empty frame. - let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4 << 1, 0x20, 1]; + let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4, 0x20, 1]; for _ in 1..COUNT { body.extend([0, 1]); } diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index 97a2da0eeb6..1d5dcd8f3a6 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -3,13 +3,21 @@ use bytes::Bytes; use crate::Timestamp; -/// How the publisher serialized a list of properties: its key and integer encoding. +/// The moq-transport drafts a list of properties came from, which share its key and +/// integer encoding and what each property means. #[derive(Clone, Copy, Debug, PartialEq, Eq)] // private: passthrough pub(crate) enum Encoding { - Absolute, - DeltaQuic, - Delta { seven: bool }, + /// Drafts 14 and 15: absolute keys and QUIC varints. + Draft14, + /// Draft 16: delta keys and QUIC varints. + Draft16, + /// Draft 17: delta keys and leading-ones varints without the seven-byte form. + Draft17, + /// Draft 18: delta keys and leading-ones varints. + Draft18, + /// Draft 19 and later: as draft 18, with property 0x06 as SUBGROUP_DELIVERY_TIMEOUT. + Draft19, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -53,8 +61,6 @@ pub(crate) struct Block { pub encoding: Encoding, /// `bytes` holds Immutable Properties (0x0b), serialized as `encoding` does. pub immutable: bool, - /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. - pub delivery_timeout: bool, } impl Properties { @@ -76,10 +82,8 @@ pub(crate) struct TrackProperties { /// serialized bytes. pub values: Vec, /// How the publisher serialized the list and the keys inside Immutable Properties. - /// Set beside any values, and never [`Encoding::Absolute`], which predates the list. + /// Set beside any values, and never [`Encoding::Draft14`], which predates the list. pub encoding: Option, - /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. - pub delivery_timeout: bool, } /// Object numbering is separate from the public frame's ordinal in its group. From 3d8398a31ec5c93703516e164e142c2d1e2c1e72 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 09:50:31 -0700 Subject: [PATCH 21/25] fix(net): bound a block's Timestamp headroom once it has a frame A draft-14 subgroup or FETCH object's properties arrive before its size and status, so ingress read them as a framed object's and refused a legal END_OF_GROUP block of 65,527 to 65,536 bytes on a timed track. The headroom for the Timestamp egress restates is now check_frame, applied where a frame is created: a subgroup or FETCH object with a payload or a Normal status, and a datagram without a status. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/object.rs | 26 +++++++--- rs/moq-net/src/ietf/subscriber.rs | 81 +++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 7 deletions(-) diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 63d0e7b42e1..391193ec708 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -60,6 +60,16 @@ pub(crate) fn status_defined(status: u64, version: Version) -> bool { } } +/// Refuse the properties of an object with a frame on a track in `timescale` if they +/// leave no room for the Timestamp egress restates. +pub(crate) fn check_frame(properties: &Properties, timescale: Option) -> Result<(), Error> { + // A list at the limit with a small Timestamp cannot take back a larger one on egress. + match properties.heap() > max_block(timescale) as u64 { + true => Err(Error::Unsupported), + false => Ok(()), + } +} + /// Only draft-14 lets a status object, such as END_OF_GROUP, carry properties. #[cfg(feature = "async")] pub(crate) fn status_has_properties(version: Version) -> bool { @@ -272,6 +282,9 @@ pub(crate) fn values(block: &crate::model::object::Block) -> Result) -> Result { decode(data, version, timescale, true) } @@ -290,8 +303,7 @@ fn decode(data: &Bytes, version: Version, timescale: Option, framed: sealed_time: timed(parsed.sealed_time, timescale)?, block: block(&parsed.values, encoding(version))?, }; - // A list at the limit with a small Timestamp cannot take back a larger one on egress. - if properties.heap() > max_block(lifted) as u64 { + if properties.heap() > MAX_BLOCK as u64 { return Err(Error::Unsupported); } Ok(Decoded { @@ -591,16 +603,16 @@ mod tests { }; let decoded = read(&list(limit), Version::Draft22, milli).unwrap(); assert_eq!(decoded.properties.heap(), limit as u64); + assert!(check_frame(&decoded.properties, milli).is_ok()); let latest = Timestamp::new((1 << 62) - 1, Timescale::MILLI).unwrap(); let written = write(&decoded.properties, Some(latest), Version::Draft22, milli).unwrap(); assert_eq!(written.len(), MAX_BLOCK); - assert!(matches!( - read(&list(limit + 1), Version::Draft22, milli), - Err(Error::Unsupported) - )); + let over = read(&list(limit + 1), Version::Draft22, milli).unwrap(); + assert!(matches!(check_frame(&over.properties, milli), Err(Error::Unsupported))); // An untimed track has no Timestamp to restate, so its block may fill the limit. - assert!(read(&list(MAX_BLOCK - 2), Version::Draft22, None).is_ok()); + let untimed = read(&list(MAX_BLOCK - 2), Version::Draft22, None).unwrap(); + assert!(check_frame(&untimed.properties, None).is_ok()); // The same bound on a block arriving over the lite hop. let encoding = Encoding::Draft19; diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 9b4fdf777bc..803b6539e70 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4121,6 +4121,7 @@ where ), false => { let decoded = super::object::read(&properties, self.version, track.timescale)?; + super::object::check_frame(&decoded.properties, track.timescale)?; (decoded.timestamp, decoded.properties) } }; @@ -4832,6 +4833,7 @@ where std::future::poll_fn(|cx| stream.poll_skip(cx, &mut remaining)).await?; return Ok(Fetched::Frame); } + super::object::check_frame(&decoded.properties, timescale)?; let timestamp = object_time(timescale, decoded.timestamp)?; let plain = id == producer.frame_count() as u64 && decoded.properties.is_empty(); let fields = (!plain).then(|| { @@ -5562,6 +5564,7 @@ fn object_time( impl GroupIngest { fn header(&mut self, group: &group::Producer, info: frame::Info) -> Result { + super::object::check_frame(&self.properties, self.timescale)?; let id = self.prior_object.expect("payload follows object ID"); group.mark_gap(self.prior_object.expect("properties follow Object ID"), self.gap)?; let plain = id == group.frame_count() as u64 && self.properties.is_empty(); @@ -12703,6 +12706,84 @@ mod stitch_tests { assert_eq!(leaves(&end.properties), status, "fetch"); } + /// A draft-14 status object has no frame, so its block may fill the whole limit on a + /// timed track, though its list arrives before the status says so. A framed object's + /// block leaves room for the Timestamp egress restates. + #[moq_clock::test] + async fn a_status_object_fills_the_whole_block() { + let version = Version::Draft14; + let milli = Some(Timescale::MILLI); + // A block of `size` held bytes: one opaque property, its key, a four-byte length, + // then bytes. A framed object's list adds its Timestamp, which the frame holds. + let block = |size: usize, framed: bool| { + let mut block = Vec::new(); + let w = &mut Encoder::new(&mut block, version.into()); + if framed { + w.varint(0x10u64).unwrap(); + w.varint(5u64).unwrap(); + } + w.varint(0x21u64).unwrap(); + w.bytes(&vec![7; size - 5]).unwrap(); + block + }; + let full = block(super::super::object::MAX_BLOCK, false); + let limit = super::super::object::max_block(milli); + + for (properties, status, ok) in [ + (&full, Some(END_OF_GROUP), true), + (&block(limit + 1, true), None, false), + (&block(limit, true), None, true), + ] { + let script = object_stream(version, true, &[(0, properties, status)]); + let mut h = Harness::with_timescale(Fill::Done, vec![script], milli); + h.subscriber.version = version; + let mut stream = h.stream().await.with_version(version); + let result = h.subscriber.clone().recv_group(&mut stream).await; + match ok { + true => assert!(result.is_ok(), "subgroup {}: {result:?}", properties.len()), + false => assert!(matches!(result, Err(Error::Unsupported)), "subgroup: {result:?}"), + } + + // The fetch harness's track is untimed, so a framed object it keeps cannot be timed. + if ok && status.is_none() { + continue; + } + // A draft-14 FETCH object: Group, Subgroup, Object, priority, then its properties, + // and an empty payload with its status or a one-byte payload. + let mut objects = Vec::new(); + let w = &mut Encoder::new(&mut objects, version.into()); + for value in [SEQUENCE, 0, 0] { + w.varint(value).unwrap(); + } + w.u8(128); + w.bytes(properties).unwrap(); + match status { + Some(status) => { + w.varint(0u64).unwrap(); + w.varint(status).unwrap(); + } + None => { + w.varint(1u64).unwrap(); + w.u8(99); + } + } + let mut run = GroupFetchRun::new(version, objects).await; + let mut producer = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + let result = run + .subscriber + .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(1), milli) + .await; + match ok { + true => assert!(result.is_ok(), "fetch {}: {result:?}", properties.len()), + false => assert!(matches!(result, Err(Error::Unsupported)), "fetch: {result:?}"), + } + if status.is_some() { + let end = producer.consume().end_object().expect("the END_OF_GROUP object"); + assert_eq!(end.properties.heap(), full.len() as u64); + } + } + } + #[moq_clock::test] async fn passthrough_refuses_contradictory_gap_properties() { for properties in [vec![0x3e, 2], vec![0x3e, 3], vec![0x3e, 1, 0, 1]] { From d07c3ffe7c0ca1a51804bfedfbf58d733abdbd7c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:29:34 -0700 Subject: [PATCH 22/25] fix(lite): forward a sealed DYNAMIC_GROUPS across the hop Lite TRACK_INFO has no refresh yet, so the hop compared a sealed DYNAMIC_GROUPS with false and refused real moq-transport tracks crossing a cluster. The hop now forwards it as it arrived; direct moq-transport ingress still compares it. moq-dev/moq#6030 restores the check. The concept doc no longer claims default settings never carry the extension's state: moq-relay offers it on moq-lite-07. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 4 ++-- drafts/draft-lcurley-moq-ietf.md | 1 + rs/moq-net/src/ietf/properties.rs | 34 +++++++++++++++++++++++-------- rs/moq-net/src/ietf/subscriber.rs | 2 +- rs/moq-net/src/lite/ietf.rs | 25 +++++++++++++++++++++-- rs/moq-net/src/lite/subscriber.rs | 6 +++++- 6 files changed, 57 insertions(+), 15 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index a8f9788208f..8abf2e09a35 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -53,8 +53,8 @@ Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side speak that extension. The pooled JavaScript `Connection` has no such setting yet. [ietf](/draft/moq-ietf) goes the other way: it extends moq-lite-07 to carry this object state between relays. moq-lite-07 is still a work in progress -(`moq-lite-07-wip`), negotiated only when both sides enable it, so the default -settings do not carry this state. Only Rust offers the extension, when +(`moq-lite-07-wip`), negotiated only when both sides enable it, so a peer that +does not offer it does not carry this state. Only Rust offers the extension, when `extensions.ietf` is set, and `moq-relay` always does on moq-lite-07. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts application payloads, so relays still forward named tracks they cannot read. diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index d5167d41e32..75256cf6c01 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -201,6 +201,7 @@ The Immutable Properties may still hold one of those five, which a relay forward A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, and DYNAMIC_GROUPS whether the track takes a new group request. A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: a relay serves its own order and forwards the sealed value unchanged, whatever it says. A relay refuses a track whose sealed value differs, from a {{moqt}} publisher or over this extension, as unsupported. +TRACK_INFO does not yet say whether a track takes a new group request, so a relay receiving a track over this extension forwards a sealed DYNAMIC_GROUPS unchanged rather than comparing it. A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index bbdf0442a9d..4596375a210 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -342,13 +342,13 @@ impl TrackProperties { } /// Why a track carrying these beside `info` is neither processed nor forwarded, if it - /// is not: every ingress, moq-transport or a relay hop, refuses it here. - pub(crate) fn refused(&self, info: &crate::track::Info) -> Option { + /// is not: every ingress, moq-transport or a relay `hop`, refuses it here. + pub(crate) fn refused(&self, info: &crate::track::Info, hop: bool) -> Option { if self.mandatory() { return Some(crate::Error::UnsupportedExtension); } // Egress forwards a sealed value in place of restating `info`, so the two must agree. - if self.contradicts(&Properties::restated(info)) { + if self.contradicts(&Properties::restated(info), hop) { return Some(crate::Error::Unsupported); } // Egress could not restate the track's info beside them without overflowing. @@ -363,8 +363,8 @@ impl TrackProperties { } /// Whether Immutable Properties seal a property we understand at another value than - /// the `restated` one the relay acts on. - fn contradicts(&self, restated: &Properties) -> bool { + /// the `restated` one the relay acts on, which a relay `hop` received over moq-lite. + fn contradicts(&self, restated: &Properties, hop: bool) -> bool { let Some((block, encoding)) = self.immutable().zip(self.encoding) else { return false; }; @@ -381,7 +381,9 @@ impl TrackProperties { DEFAULT_PUBLISHER_PRIORITY => sealed.priority != restated.priority, // Advisory: a relay serves its own order and forwards the publisher's preference. DEFAULT_PUBLISHER_GROUP_ORDER => false, - DYNAMIC_GROUPS => sealed.dynamic_groups != restated.dynamic_groups, + // Lite TRACK_INFO has no refresh to compare until moq-dev/moq#6030 carries it, so + // the hop forwards the sealed value as it arrived. + DYNAMIC_GROUPS => !hop && sealed.dynamic_groups != restated.dynamic_groups, _ => unreachable!("only the understood properties are seen"), }) } @@ -778,7 +780,12 @@ mod tests { dynamic_groups: true, unknown: unknown(MAX_FORWARDED), }; - assert!(properties.unknown.refused(&crate::track::Info::default()).is_none()); + assert!( + properties + .unknown + .refused(&crate::track::Info::default(), false) + .is_none() + ); let mut buf = Vec::new(); properties .encode(&mut Encoder::new(&mut buf, Version::Draft22.into()), Version::Draft22) @@ -786,7 +793,7 @@ mod tests { assert_eq!(decode_draft22(&buf).unwrap(), properties); assert!(matches!( - unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default()), + unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default(), false), Some(crate::Error::Unsupported) )); } @@ -795,6 +802,11 @@ mod tests { /// refused beside an info that restates 7s, 1000 Hz, priority 9, Descending, and /// DYNAMIC_GROUPS. fn seal(id: u64, value: u64) -> Option { + seal_at(id, value, false) + } + + /// As [`seal`], received on a relay `hop`. + fn seal_at(id: u64, value: u64, hop: bool) -> Option { let version = Version::Draft22; let mut block = Vec::new(); let w = &mut Encoder::new(&mut block, version.into()); @@ -812,7 +824,7 @@ mod tests { .with_timescale(Timescale::MILLI) .with_priority(9) .with_refresh(0); - unknown.refused(&info) + unknown.refused(&info, hop) } /// A sealed value of a property the relay restates must be the one it acts on, since @@ -881,6 +893,10 @@ mod tests { fn sealed_dynamic_groups_match_the_track() { assert!(seal(DYNAMIC_GROUPS, 1).is_none()); assert!(matches!(seal(DYNAMIC_GROUPS, 0), Some(crate::Error::Unsupported))); + // A relay hop has no refresh to compare it with, so it forwards either. + for value in [0, 1] { + assert!(seal_at(DYNAMIC_GROUPS, value, true).is_none(), "{value}"); + } } /// Every property the relay restates has a sealed check above. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index d590a411019..b33e1dd4ab9 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -482,7 +482,7 @@ fn accepted_info(properties: &ietf::Properties) -> track::Info { /// Why a track answered with `properties` is neither processed nor forwarded, if it is not. fn refused(properties: &ietf::Properties) -> Option { - properties.unknown.refused(&accepted_info(properties)) + properties.unknown.refused(&accepted_info(properties), false) } /// The Largest Group a subscription knows: its SUBSCRIBE_OK's, or a newer one since. diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 4e4a543a15b..79597ce5d47 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -759,7 +759,7 @@ mod tests { let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); assert_eq!(ingress.unknown.values.len(), repeats + 1, "{version}"); assert!( - ingress.unknown.refused(&crate::track::Info::default()).is_none(), + ingress.unknown.refused(&crate::track::Info::default(), false).is_none(), "{version}" ); @@ -806,7 +806,7 @@ mod tests { assert!(ingress.dynamic_groups); assert!(!fits(&ingress.unknown)); assert!(matches!( - ingress.unknown.refused(&crate::track::Info::default()), + ingress.unknown.refused(&crate::track::Info::default(), false), Some(crate::Error::Unsupported) )); } @@ -1320,6 +1320,27 @@ mod hop_tests { } } + /// A sealed DYNAMIC_GROUPS crosses the hop as it arrived, whatever it says: lite + /// TRACK_INFO has no refresh to compare it with until moq-dev/moq#6030. + #[moq_clock::test] + async fn a_sealed_dynamic_groups_crosses_the_hop() { + for value in [0, 1] { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x30).unwrap(); + e.varint(value).unwrap(); + let res = subscribe_across(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + encoding: Some(Encoding::Draft19), + }) + .await; + assert!(res.is_ok(), "{value}: {res:?}"); + } + } + /// A relay forwards only as many Track Properties as leave room for the ones it /// restates from TRACK_INFO, so one more is refused across the hop. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 4ab2521de91..5a172073913 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6115,7 +6115,11 @@ impl TrackInfoFetch { } let properties = ready!(stream.reader.poll_decode::(&mut cx))?; // Refused as moq-transport ingress refuses it. - if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused(info)) { + if let Some(err) = properties + .0 + .as_ref() + .and_then(|properties| properties.refused(info, true)) + { return Poll::Ready(Err(err)); } let TrackInfoState::Properties { stream, mut info } = From 940862691777b2b3b83cb0e9649b6bf1c268c962 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 12:25:03 -0700 Subject: [PATCH 23/25] fix(lite): refuse a draft-14 block whose IDs descend A block crossing the hop may leave byte for byte to a draft-14 peer, so it must be the canonical ascending list moq-transport ingress produces. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/object.rs | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 391193ec708..e95fab140fa 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -236,7 +236,9 @@ pub(crate) struct Checked { /// ingress validates a list, for an object that is `framed` or a frameless status. /// /// A framed object's mutable Timestamp on a timed track is its frame's, so one inside is -/// malformed, as is an empty block, which is sent as none. +/// malformed, as is an empty block, which is sent as none. Absolute IDs must ascend, as +/// delta ones do, since egress may forward the block unchanged; Immutable Properties stay +/// as the publisher sent them. pub(crate) fn check( bytes: &Bytes, encoding: Encoding, @@ -251,6 +253,9 @@ pub(crate) fn check( if lifted.is_some() && parsed.timestamp.is_some() { return Err(Error::MalformedTrack); } + if !parsed.values.is_sorted_by_key(|property| property.id) { + return Err(Error::MalformedTrack); + } Ok(Checked { immutable: parsed.immutable, sealed_time: timed(parsed.sealed_time, timescale)?, @@ -638,6 +643,18 @@ mod tests { assert!(check(&block, Encoding::Draft14, milli, true).is_err()); } + /// A draft-14 block crosses the lite hop in ascending order, as ingress sorts it, so + /// one whose absolute IDs descend is malformed. Its Immutable Properties may not ascend. + #[test] + fn a_draft14_block_ascends() { + let milli = Some(Timescale::MILLI); + assert!(check(&Bytes::from_static(&[0x02, 1, 0x20, 1]), Encoding::Draft14, milli, true).is_ok()); + assert!(check(&Bytes::from_static(&[0x02, 1, 0x02, 2]), Encoding::Draft14, milli, true).is_ok()); + assert!(check(&Bytes::from_static(&[0x20, 1, 0x02, 1]), Encoding::Draft14, milli, true).is_err()); + let sealed = Bytes::from_static(&[0x02, 1, 0x0b, 4, 0x20, 1, 0x02, 1]); + assert!(check(&sealed, Encoding::Draft14, milli, true).is_ok()); + } + /// Draft-19 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so it cannot cross that boundary. #[test] fn key_six_follows_its_draft() { From 5aea682c6bc374aa5abc1d74872f72f151f0340c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 12:25:03 -0700 Subject: [PATCH 24/25] fix(lite): compare a sealed DYNAMIC_GROUPS across the hop Lite TRACK_INFO now carries Refresh (#6030), so the hop restates DYNAMIC_GROUPS like the other understood properties and drops its exception. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-ietf.md | 3 +- rs/moq-net/src/ietf/properties.rs | 34 ++++++--------------- rs/moq-net/src/ietf/subscriber.rs | 2 +- rs/moq-net/src/lite/ietf.rs | 49 +++++++++++++++++++++---------- rs/moq-net/src/lite/subscriber.rs | 6 +--- 5 files changed, 46 insertions(+), 48 deletions(-) diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md index 75256cf6c01..bfab6d046f1 100644 --- a/drafts/draft-lcurley-moq-ietf.md +++ b/drafts/draft-lcurley-moq-ietf.md @@ -198,10 +198,9 @@ A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 Dropping those five can widen the delta that spans them, so a relay also refuses a {{moqt}} track whose remaining list would not fit a TRACK_PROPERTIES message, as unsupported. The Immutable Properties may still hold one of those five, which a relay forwards in place of the one it would restate. -A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, and DYNAMIC_GROUPS whether the track takes a new group request. +A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, and DYNAMIC_GROUPS whether its Refresh is nonzero. A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: a relay serves its own order and forwards the sealed value unchanged, whatever it says. A relay refuses a track whose sealed value differs, from a {{moqt}} publisher or over this extension, as unsupported. -TRACK_INFO does not yet say whether a track takes a new group request, so a relay receiving a track over this extension forwards a sealed DYNAMIC_GROUPS unchanged rather than comparing it. A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index 4596375a210..bbdf0442a9d 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -342,13 +342,13 @@ impl TrackProperties { } /// Why a track carrying these beside `info` is neither processed nor forwarded, if it - /// is not: every ingress, moq-transport or a relay `hop`, refuses it here. - pub(crate) fn refused(&self, info: &crate::track::Info, hop: bool) -> Option { + /// is not: every ingress, moq-transport or a relay hop, refuses it here. + pub(crate) fn refused(&self, info: &crate::track::Info) -> Option { if self.mandatory() { return Some(crate::Error::UnsupportedExtension); } // Egress forwards a sealed value in place of restating `info`, so the two must agree. - if self.contradicts(&Properties::restated(info), hop) { + if self.contradicts(&Properties::restated(info)) { return Some(crate::Error::Unsupported); } // Egress could not restate the track's info beside them without overflowing. @@ -363,8 +363,8 @@ impl TrackProperties { } /// Whether Immutable Properties seal a property we understand at another value than - /// the `restated` one the relay acts on, which a relay `hop` received over moq-lite. - fn contradicts(&self, restated: &Properties, hop: bool) -> bool { + /// the `restated` one the relay acts on. + fn contradicts(&self, restated: &Properties) -> bool { let Some((block, encoding)) = self.immutable().zip(self.encoding) else { return false; }; @@ -381,9 +381,7 @@ impl TrackProperties { DEFAULT_PUBLISHER_PRIORITY => sealed.priority != restated.priority, // Advisory: a relay serves its own order and forwards the publisher's preference. DEFAULT_PUBLISHER_GROUP_ORDER => false, - // Lite TRACK_INFO has no refresh to compare until moq-dev/moq#6030 carries it, so - // the hop forwards the sealed value as it arrived. - DYNAMIC_GROUPS => !hop && sealed.dynamic_groups != restated.dynamic_groups, + DYNAMIC_GROUPS => sealed.dynamic_groups != restated.dynamic_groups, _ => unreachable!("only the understood properties are seen"), }) } @@ -780,12 +778,7 @@ mod tests { dynamic_groups: true, unknown: unknown(MAX_FORWARDED), }; - assert!( - properties - .unknown - .refused(&crate::track::Info::default(), false) - .is_none() - ); + assert!(properties.unknown.refused(&crate::track::Info::default()).is_none()); let mut buf = Vec::new(); properties .encode(&mut Encoder::new(&mut buf, Version::Draft22.into()), Version::Draft22) @@ -793,7 +786,7 @@ mod tests { assert_eq!(decode_draft22(&buf).unwrap(), properties); assert!(matches!( - unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default(), false), + unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default()), Some(crate::Error::Unsupported) )); } @@ -802,11 +795,6 @@ mod tests { /// refused beside an info that restates 7s, 1000 Hz, priority 9, Descending, and /// DYNAMIC_GROUPS. fn seal(id: u64, value: u64) -> Option { - seal_at(id, value, false) - } - - /// As [`seal`], received on a relay `hop`. - fn seal_at(id: u64, value: u64, hop: bool) -> Option { let version = Version::Draft22; let mut block = Vec::new(); let w = &mut Encoder::new(&mut block, version.into()); @@ -824,7 +812,7 @@ mod tests { .with_timescale(Timescale::MILLI) .with_priority(9) .with_refresh(0); - unknown.refused(&info, hop) + unknown.refused(&info) } /// A sealed value of a property the relay restates must be the one it acts on, since @@ -893,10 +881,6 @@ mod tests { fn sealed_dynamic_groups_match_the_track() { assert!(seal(DYNAMIC_GROUPS, 1).is_none()); assert!(matches!(seal(DYNAMIC_GROUPS, 0), Some(crate::Error::Unsupported))); - // A relay hop has no refresh to compare it with, so it forwards either. - for value in [0, 1] { - assert!(seal_at(DYNAMIC_GROUPS, value, true).is_none(), "{value}"); - } } /// Every property the relay restates has a sealed check above. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index b33e1dd4ab9..d590a411019 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -482,7 +482,7 @@ fn accepted_info(properties: &ietf::Properties) -> track::Info { /// Why a track answered with `properties` is neither processed nor forwarded, if it is not. fn refused(properties: &ietf::Properties) -> Option { - properties.unknown.refused(&accepted_info(properties), false) + properties.unknown.refused(&accepted_info(properties)) } /// The Largest Group a subscription knows: its SUBSCRIBE_OK's, or a newer one since. diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 79597ce5d47..e52389bb764 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -759,7 +759,7 @@ mod tests { let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); assert_eq!(ingress.unknown.values.len(), repeats + 1, "{version}"); assert!( - ingress.unknown.refused(&crate::track::Info::default(), false).is_none(), + ingress.unknown.refused(&crate::track::Info::default()).is_none(), "{version}" ); @@ -806,7 +806,7 @@ mod tests { assert!(ingress.dynamic_groups); assert!(!fits(&ingress.unknown)); assert!(matches!( - ingress.unknown.refused(&crate::track::Info::default(), false), + ingress.unknown.refused(&crate::track::Info::default()), Some(crate::Error::Unsupported) )); } @@ -1100,6 +1100,7 @@ mod hop_tests { let mut info = track::Info::timed().with_timescale(Timescale::MILLI); info.max_age = Some(Duration::from_secs(7)); info.priority = 9; + info.refresh = Some(0); let track_properties = crate::model::object::TrackProperties { values: vec![property(0x40, 3)], encoding: Some(Encoding::Draft19), @@ -1174,8 +1175,8 @@ mod hop_tests { assert!(next(&mut received).await.is_none()); let info = moq_clock::timeout(TIMEOUT, copy.query()).await.unwrap().unwrap(); assert_eq!( - (info.max_age, info.timescale, info.priority), - (Some(Duration::from_secs(7)), Some(Timescale::MILLI), 9), + (info.max_age, info.timescale, info.priority, info.refresh), + (Some(Duration::from_secs(7)), Some(Timescale::MILLI), 9, Some(0)), "{offer:?}" ); match negotiated { @@ -1249,12 +1250,17 @@ mod hop_tests { assert!(received.end_object().is_none(), "an END_OF_GROUP past the cap"); } - /// Subscribe across a negotiated hop to a track carrying `properties`. + /// Subscribe across a negotiated hop to a timed track carrying `properties`. async fn subscribe_across(properties: crate::model::object::TrackProperties) -> Result<(), crate::Error> { - let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); - let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); let mut info = track::Info::timed().with_timescale(Timescale::MILLI); info.properties = Some(Arc::new(properties)); + subscribe_across_info(info).await + } + + /// Subscribe across a negotiated hop to a track with `info`. + async fn subscribe_across_info(info: track::Info) -> Result<(), crate::Error> { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); let _track = broadcast.create_track("video", info).unwrap(); let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; @@ -1320,24 +1326,37 @@ mod hop_tests { } } - /// A sealed DYNAMIC_GROUPS crosses the hop as it arrived, whatever it says: lite - /// TRACK_INFO has no refresh to compare it with until moq-dev/moq#6030. + /// A sealed DYNAMIC_GROUPS must match the refresh TRACK_INFO carries across the hop, + /// which moq-transport egress restates as DYNAMIC_GROUPS. #[moq_clock::test] - async fn a_sealed_dynamic_groups_crosses_the_hop() { - for value in [0, 1] { + async fn a_sealed_dynamic_groups_must_match_track_info() { + for (refresh, value, ok) in [ + (Some(0), 1, true), + (None, 0, true), + (Some(0), 0, false), + (None, 1, false), + ] { let mut sealed = Vec::new(); let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); e.varint(0x30).unwrap(); e.varint(value).unwrap(); - let res = subscribe_across(crate::model::object::TrackProperties { + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.refresh = refresh; + info.properties = Some(Arc::new(crate::model::object::TrackProperties { values: vec![Property { id: IMMUTABLE, value: Value::Bytes(sealed.into()), }], encoding: Some(Encoding::Draft19), - }) - .await; - assert!(res.is_ok(), "{value}: {res:?}"); + })); + let res = subscribe_across_info(info).await; + match ok { + true => assert!(res.is_ok(), "{refresh:?} {value}: {res:?}"), + false => assert!( + matches!(res, Err(crate::Error::Unsupported)), + "{refresh:?} {value}: {res:?}" + ), + } } } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index b15d775c878..5cd894cff5d 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6175,11 +6175,7 @@ impl TrackInfoFetch { } let properties = ready!(stream.reader.poll_decode::(&mut cx))?; // Refused as moq-transport ingress refuses it. - if let Some(err) = properties - .0 - .as_ref() - .and_then(|properties| properties.refused(info, true)) - { + if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused(info)) { return Poll::Ready(Err(err)); } let TrackInfoState::Properties { stream, mut info } = From d6942e6a8c985cfdf3e9bbd7e449e559056c3f99 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 13:20:30 -0700 Subject: [PATCH 25/25] quest(m1): keep the ietf hop quest for ingress-version provenance moq-dev/moq#6072 decided a track carries its ingress moq-transport version once; this PR landed per-block Encoding codes. The quest now holds that remaining work and gates the lite-07 cut. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ietf-extension/README.md | 6 +++- quest/m1/ietf-extension/lite.md | 56 +++++++++++++++++++++++++++++++ quest/m1/lite07-finalize.md | 1 + 3 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 quest/m1/ietf-extension/lite.md diff --git a/quest/m1/ietf-extension/README.md b/quest/m1/ietf-extension/README.md index 3f8dcb6c59a..d31d0303840 100644 --- a/quest/m1/ietf-extension/README.md +++ b/quest/m1/ietf-extension/README.md @@ -1,4 +1,4 @@ -# [M] moq-transport passthrough +# moq-transport passthrough ## Goal @@ -81,6 +81,10 @@ Work owned by this README, after the children land: - FETCH cases are skipped upstream. Section 8 stays out while PUBLISH is declined. +## Required + +- [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - a track crossing a lite-07 hop carries its moq-transport ingress version once, replacing per-block Encoding codes + ## Related - [#4926](https://github.com/moq-dev/moq/issues/4926) - the declined request for an object-level API; this carries the fields for relays only diff --git a/quest/m1/ietf-extension/lite.md b/quest/m1/ietf-extension/lite.md new file mode 100644 index 00000000000..b70fe90fcb9 --- /dev/null +++ b/quest/m1/ietf-extension/lite.md @@ -0,0 +1,56 @@ +# [M] The ietf extension records provenance as the ingress version + +## Goal + +A track crossing a lite-07 hop with the `ietf` SETUP extension carries its +ingress moq-transport version once, instead of an Encoding code on every +Property Block and on TRACK_PROPERTIES. A track published over moq-lite +carries none, and a peer cannot attach moq-transport state to it. Behavior +across the hop is otherwise unchanged from +[moq-dev/moq#6058](https://github.com/moq-dev/moq/pull/6058), which landed +the extension with per-block codes. + +## Plan + +Decided 2026-10-20 in +[moq-dev/moq#6072](https://github.com/moq-dev/moq/pull/6072). + +- In the model, the track's optional ingress `ietf::Version` replaces + `object::Encoding` on `object::Block` and `TrackProperties`, which already + derives 0x06's meaning from the draft instead of a flag. One + version per track suffices because each publisher is its own stream; a + different ingress is a new instance. +- On the wire, track info carries the ingress version once, or none for a + track published over moq-lite, which has no IETF provenance and no + properties to derive rules for. Records and datagrams drop their Encoding + code. Update `drafts/draft-lcurley-moq-ietf.md` and pass + `just drafts check`. +- Lite ingress refuses a track with no version that carries any IETF field + (track, object, or datagram properties, or object IDs), including on a + later object. +- Immutable properties keep their unchanged inner bytes. Downstream IETF + egress applies today's single-relay rules from that version: refuse an + incompatible immutable encoding (drafts 14/15 carry no immutable track + block, so egress there skips that check), and across draft 19, where 0x06 + becomes SUBGROUP_DELIVERY_TIMEOUT, drop a mutable 0x06 and refuse a sealed + one. +- Rejected 2026-10-20: a generic crate-private `unknown` KVP block on route, + track, group, frame, and datagram, tagged by source version, that would + also tunnel future lite fields through a lite-07 hop. A relay cannot act on + fields it forwards blindly, and most lite additions (routes, refresh, + ranges, auth) change relay behavior. With no must-understand marker, only + relay-ignorable end-to-end hints could tunnel safely. + +Tests: 0x06 provenance across the hop: a draft-18 publisher's object and +track properties exit draft 19 with a mutable 0x06 dropped and a sealed one +refused. Both drafts share an encoding family, so only the carried version +distinguishes them. Cover a lite-published track crossing the same hop with +no ingress version, and a malformed peer that sends properties on a +versionless track, at track info and on a later frame and datagram. Run +`just test interop --all`. + +Wire: lite-07-wip only, when the extension is negotiated. + +## Related + +- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - this changes the lite-07 wire, so it lands before the cut diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 66ac15b2a86..2c0e9fed356 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -90,6 +90,7 @@ is published; older versions are unchanged. - [Compressed tracks in Rust](/quest/m1/compress/core.md) - TRACK_INFO carries the compress flag and the frame header each compressed frame's inflated size - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS](/quest/m1/archive/tracks.md) - lite-07 carries the request listing a broadcast's tracks as they appear +- [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - the `ietf` extension carries a track's ingress version once instead of a code per block ## Related