From 6c7fdedb96aca71268c35de9a109773021a8cfbc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 01:50:41 -0700 Subject: [PATCH 1/2] feat!: store field-less trun runs as a count --- src/moof/traf/trun.rs | 344 +++++++++++++++++++++++++++++++++++------- src/test/av1.rs | 10 +- src/test/bbb.rs | 13 +- src/test/esds.rs | 8 +- 4 files changed, 307 insertions(+), 68 deletions(-) diff --git a/src/moof/traf/trun.rs b/src/moof/traf/trun.rs index 6445d892..293607e9 100644 --- a/src/moof/traf/trun.rs +++ b/src/moof/traf/trun.rs @@ -17,7 +17,125 @@ ext! { #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct Trun { pub data_offset: Option, - pub entries: Vec, + pub samples: TrunSamples, +} + +/// The samples of a trun box. +/// +/// A run without any per-sample field is stored as a count, so decoding never +/// allocates in proportion to an untrusted `sample_count`. +/// Use [TrunSamples::iter] to visit every sample's [TrunEntry] in either form. +#[derive(Debug, Clone, PartialEq, Eq)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub enum TrunSamples { + /// Every sample inherits its duration, size, flags, and composition offset + /// from tfhd/trex, except that the first sample may override its flags. + Inherited { + count: u32, + first_flags: Option, + }, + + /// Per-sample entries, used when the run carries at least one per-sample field. + Explicit(Vec), +} + +impl TrunSamples { + /// The number of samples in the run. + pub fn len(&self) -> usize { + match self { + Self::Inherited { count, .. } => *count as usize, + Self::Explicit(entries) => entries.len(), + } + } + + pub fn is_empty(&self) -> bool { + self.len() == 0 + } + + /// Each sample's entry in order, without allocating. + pub fn iter(&self) -> TrunSamplesIter<'_> { + match self { + Self::Inherited { count, first_flags } => TrunSamplesIter::Inherited { + remaining: *count, + first_flags: *first_flags, + }, + Self::Explicit(entries) => TrunSamplesIter::Explicit(entries.iter()), + } + } +} + +impl Default for TrunSamples { + fn default() -> Self { + Self::Inherited { + count: 0, + first_flags: None, + } + } +} + +impl From> for TrunSamples { + fn from(entries: Vec) -> Self { + Self::Explicit(entries) + } +} + +impl<'a> IntoIterator for &'a TrunSamples { + type Item = TrunEntry; + type IntoIter = TrunSamplesIter<'a>; + + fn into_iter(self) -> Self::IntoIter { + self.iter() + } +} + +/// An iterator over the entries of [TrunSamples]. +#[derive(Debug, Clone)] +pub enum TrunSamplesIter<'a> { + Inherited { + remaining: u32, + first_flags: Option, + }, + Explicit(std::slice::Iter<'a, TrunEntry>), +} + +impl Iterator for TrunSamplesIter<'_> { + type Item = TrunEntry; + + fn next(&mut self) -> Option { + match self { + Self::Inherited { + remaining, + first_flags, + } => { + *remaining = remaining.checked_sub(1)?; + Some(TrunEntry { + flags: first_flags.take(), + ..Default::default() + }) + } + Self::Explicit(entries) => entries.next().copied(), + } + } + + fn size_hint(&self) -> (usize, Option) { + let len = match self { + Self::Inherited { remaining, .. } => *remaining as usize, + Self::Explicit(entries) => entries.len(), + }; + (len, Some(len)) + } +} + +impl ExactSizeIterator for TrunSamplesIter<'_> {} + +impl Default for TrunSamplesIter<'_> { + /// An empty iterator. + fn default() -> Self { + Self::Inherited { + remaining: 0, + first_flags: None, + } + } } /// A single sample entry in a trun box. @@ -27,7 +145,7 @@ pub struct Trun { /// (`default_sample_duration`, `default_sample_size`, `default_sample_flags`) /// before using the values. The encoder backfills unresolved `None` with `0` /// as a last resort to avoid silently dropping fields that other entries set. -#[derive(Debug, Clone, PartialEq, Eq, Default)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct TrunEntry { pub duration: Option, @@ -53,19 +171,31 @@ impl AtomExt for Trun { false => None, }; - // Avoid a memory exhaustion attack. - // If none of the flags are set, then the trun entry has zero size, then we'll allocate `sample_count` entries. - // Rather than make the API worse, we just limit the number of (useless?) identical entries to 4096. - if !(ext.sample_duration - || ext.sample_size - || ext.sample_flags - || ext.sample_cts - || sample_count <= 4096) - { - return Err(Error::OutOfMemory); + let fields = [ + ext.sample_duration, + ext.sample_size, + ext.sample_flags, + ext.sample_cts, + ] + .into_iter() + .filter(|&field| field) + .count(); + + // A run without per-sample fields has zero bytes per sample, so store it as a count + // instead of allocating from the untrusted sample_count. + if fields == 0 { + return Ok(Trun { + data_offset, + samples: TrunSamples::Inherited { + count: sample_count, + first_flags: first_sample_flags, + }, + }); } - let mut entries = Vec::with_capacity(sample_count.min(4096) as _); + // Otherwise every sample takes at least 4 bytes, so the remaining bytes bound the allocation. + let capacity = (sample_count as usize).min(buf.remaining() / (4 * fields)); + let mut entries = Vec::with_capacity(capacity); for _ in 0..sample_count { let duration = match ext.sample_duration { @@ -98,15 +228,33 @@ impl AtomExt for Trun { Ok(Trun { data_offset, - entries, + samples: TrunSamples::Explicit(entries), }) } fn encode_body_ext(&self, buf: &mut B) -> Result { - let any_flags = self.entries.iter().any(|s| s.flags.is_some()); + let entries = match &self.samples { + TrunSamples::Inherited { count, first_flags } => { + let ext = TrunExt { + version: TrunVersion::V1, + data_offset: self.data_offset.is_some(), + first_sample_flags: first_flags.is_some(), + ..Default::default() + }; + + count.encode(buf)?; + self.data_offset.encode(buf)?; + first_flags.encode(buf)?; + + return Ok(ext); + } + TrunSamples::Explicit(entries) => entries, + }; + + let any_flags = entries.iter().any(|s| s.flags.is_some()); let first_only_flags = any_flags - && self.entries.first().is_some_and(|s| s.flags.is_some()) - && self.entries.iter().skip(1).all(|s| s.flags.is_none()); + && entries.first().is_some_and(|s| s.flags.is_some()) + && entries.iter().skip(1).all(|s| s.flags.is_none()); // Use per-sample flags when any entry has flags and it's not the first-only pattern. // None entries are backfilled with 0 to avoid silently dropping flags. @@ -121,20 +269,20 @@ impl AtomExt for Trun { // with 0 during encoding to avoid silently dropping fields on // decode→encode roundtrips (entries that inherited defaults from tfhd // have None after decode). - sample_duration: self.entries.iter().any(|s| s.duration.is_some()), - sample_size: self.entries.iter().any(|s| s.size.is_some()), + sample_duration: entries.iter().any(|s| s.duration.is_some()), + sample_size: entries.iter().any(|s| s.size.is_some()), sample_flags, - sample_cts: self.entries.iter().any(|s| s.cts.is_some()), + sample_cts: entries.iter().any(|s| s.cts.is_some()), }; - (self.entries.len() as u32).encode(buf)?; + (entries.len() as u32).encode(buf)?; self.data_offset.encode(buf)?; if ext.first_sample_flags { - self.entries[0].flags.unwrap().encode(buf)?; + entries[0].flags.unwrap().encode(buf)?; } - for entry in &self.entries { + for entry in entries { if ext.sample_duration { Some(Some(entry.duration.unwrap_or(0))).encode(buf)?; } @@ -167,7 +315,7 @@ mod test { fn first_sample_flags_roundtrip() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: Some(512), size: Some(1000), @@ -186,21 +334,22 @@ mod test { flags: None, cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + assert_eq!(decoded.data_offset, Some(100)); + let decoded: Vec<_> = decoded.samples.iter().collect(); // entry[0] must have the keyframe flags from first_sample_flags - assert_eq!(decoded.entries[0].flags, Some(0x02000000)); + assert_eq!(decoded[0].flags, Some(0x02000000)); // entries[1..N] must have None (they use default_sample_flags from tfhd) - assert_eq!(decoded.entries[1].flags, None); - assert_eq!(decoded.entries[2].flags, None); - assert_eq!(decoded.data_offset, Some(100)); - assert_eq!(decoded.entries.len(), 3); + assert_eq!(decoded[1].flags, None); + assert_eq!(decoded[2].flags, None); + assert_eq!(decoded.len(), 3); } /// When multiple entries have explicit flags (not just the first), @@ -209,7 +358,7 @@ mod test { fn mixed_flags_uses_per_sample() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: Some(512), size: Some(1000), @@ -228,18 +377,19 @@ mod test { flags: None, // no flags cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + let decoded: Vec<_> = decoded.samples.iter().collect(); // Mixed Some/None: encoder backfills None with 0 and emits per-sample flags. - assert_eq!(decoded.entries[0].flags, Some(0x02000000)); - assert_eq!(decoded.entries[1].flags, Some(0x01010000)); - assert_eq!(decoded.entries[2].flags, Some(0)); // was None, backfilled to 0 + assert_eq!(decoded[0].flags, Some(0x02000000)); + assert_eq!(decoded[1].flags, Some(0x01010000)); + assert_eq!(decoded[2].flags, Some(0)); // was None, backfilled to 0 } /// When all entries have explicit flags, per-sample flags are used. @@ -247,7 +397,7 @@ mod test { fn all_flags_roundtrip() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: Some(512), size: Some(1000), @@ -260,16 +410,17 @@ mod test { flags: Some(0x01010000), cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + let decoded: Vec<_> = decoded.samples.iter().collect(); - assert_eq!(decoded.entries[0].flags, Some(0x02000000)); - assert_eq!(decoded.entries[1].flags, Some(0x01010000)); + assert_eq!(decoded[0].flags, Some(0x02000000)); + assert_eq!(decoded[1].flags, Some(0x01010000)); } /// Entries with None duration (inherited from tfhd default_sample_duration) @@ -278,7 +429,7 @@ mod test { fn duration_backfill_roundtrip() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: Some(512), size: Some(1000), @@ -291,17 +442,18 @@ mod test { flags: None, cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + let decoded: Vec<_> = decoded.samples.iter().collect(); - assert_eq!(decoded.entries[0].duration, Some(512)); + assert_eq!(decoded[0].duration, Some(512)); // None backfilled to 0 during encode - assert_eq!(decoded.entries[1].duration, Some(0)); + assert_eq!(decoded[1].duration, Some(0)); } /// Entries with None size (inherited from tfhd default_sample_size) @@ -310,7 +462,7 @@ mod test { fn size_backfill_roundtrip() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: Some(512), size: Some(1000), @@ -323,17 +475,18 @@ mod test { flags: None, cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + let decoded: Vec<_> = decoded.samples.iter().collect(); - assert_eq!(decoded.entries[0].size, Some(1000)); + assert_eq!(decoded[0].size, Some(1000)); // None backfilled to 0 during encode - assert_eq!(decoded.entries[1].size, Some(0)); + assert_eq!(decoded[1].size, Some(0)); } /// When all entries have None for a field, the flag is not set and @@ -342,7 +495,7 @@ mod test { fn all_none_fields_omitted() { let trun = Trun { data_offset: Some(100), - entries: vec![ + samples: TrunSamples::Explicit(vec![ TrunEntry { duration: None, size: None, @@ -355,17 +508,102 @@ mod test { flags: None, cts: None, }, - ], + ]), }; let mut buf = Vec::new(); trun.encode(&mut buf).expect("encode"); let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + let decoded: Vec<_> = decoded.samples.iter().collect(); + + assert_eq!(decoded[0].duration, None); + assert_eq!(decoded[0].size, None); + assert_eq!(decoded[0].flags, None); + assert_eq!(decoded[0].cts, None); + } + + /// A run without per-sample fields decodes as a count, not one entry per sample. + #[test] + fn inherited_roundtrip() { + for first_flags in [None, Some(0x02000000)] { + let trun = Trun { + data_offset: Some(100), + samples: TrunSamples::Inherited { + count: u32::MAX, + first_flags, + }, + }; + + let mut buf = Vec::new(); + trun.encode(&mut buf).expect("encode"); + + // size, fourcc, version/flags, sample_count, data_offset, and the optional first flags. + let expected = 20 + first_flags.map_or(0, |_| 4); + assert_eq!(buf.len(), expected); + + let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + assert_eq!(decoded, trun); + assert_eq!(decoded.samples.len(), u32::MAX as usize); + + let mut entries = decoded.samples.iter(); + assert_eq!(entries.len(), u32::MAX as usize); + assert_eq!( + entries.next(), + Some(TrunEntry { + flags: first_flags, + ..Default::default() + }) + ); + assert_eq!(entries.next(), Some(TrunEntry::default())); + assert_eq!(entries.len(), u32::MAX as usize - 2); + } + } + + /// Explicit entries without any field encode as an inherited run. + #[test] + fn explicit_without_fields_decodes_inherited() { + let trun = Trun { + data_offset: None, + samples: TrunSamples::Explicit(vec![ + TrunEntry { + flags: Some(0x02000000), + ..Default::default() + }, + TrunEntry::default(), + ]), + }; + + let mut buf = Vec::new(); + trun.encode(&mut buf).expect("encode"); + + let decoded = Trun::decode(&mut &buf[..]).expect("decode"); + assert_eq!( + decoded.samples, + TrunSamples::Inherited { + count: 2, + first_flags: Some(0x02000000), + } + ); + assert!(decoded.samples.iter().eq(trun.samples.iter())); + } + + /// A sample_count larger than the per-sample data fails without reserving for it. + #[test] + fn explicit_truncated() { + let mut buf = Vec::new(); + Trun { + data_offset: None, + samples: TrunSamples::Explicit(vec![TrunEntry { + size: Some(1), + ..Default::default() + }]), + } + .encode(&mut buf) + .expect("encode"); - assert_eq!(decoded.entries[0].duration, None); - assert_eq!(decoded.entries[0].size, None); - assert_eq!(decoded.entries[0].flags, None); - assert_eq!(decoded.entries[0].cts, None); + // Claim u32::MAX samples while carrying one. + buf[12..16].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(Trun::decode(&mut &buf[..]).is_err()); } } diff --git a/src/test/av1.rs b/src/test/av1.rs index 599e5c18..9508cb5d 100644 --- a/src/test/av1.rs +++ b/src/test/av1.rs @@ -213,12 +213,10 @@ fn av1() { }), trun: vec![Trun { data_offset: Some(116), - entries: vec![TrunEntry { - duration: None, - size: None, - flags: Some(33554432), - cts: None - }] + samples: TrunSamples::Inherited { + count: 1, + first_flags: Some(33554432), + } }], sbgp: vec![], sgpd: vec![], diff --git a/src/test/bbb.rs b/src/test/bbb.rs index 18fa2b22..b2c18ec5 100644 --- a/src/test/bbb.rs +++ b/src/test/bbb.rs @@ -238,10 +238,10 @@ fn bbb() { }), trun: vec![Trun { data_offset: 116.into(), - entries: vec![TrunEntry { - flags: Some(33554432), - ..Default::default() - }], + samples: TrunSamples::Inherited { + count: 1, + first_flags: Some(33554432), + }, }], sbgp: vec![], sgpd: vec![], @@ -300,7 +300,10 @@ fn bbb() { }), trun: vec![Trun { data_offset: 112.into(), - entries: vec![Default::default()], + samples: TrunSamples::Inherited { + count: 1, + first_flags: None, + }, }], sbgp: vec![], sgpd: vec![], diff --git a/src/test/esds.rs b/src/test/esds.rs index e3e8cd25..eca5345a 100644 --- a/src/test/esds.rs +++ b/src/test/esds.rs @@ -231,10 +231,10 @@ fn esds() { }), trun: vec![Trun { data_offset: 116.into(), - entries: vec![TrunEntry { - flags: Some(33554432), - ..Default::default() - }], + samples: TrunSamples::Inherited { + count: 1, + first_flags: Some(33554432), + }, }], sbgp: vec![], sgpd: vec![], From 4bdee72d1ea552e0d180a9310b174163a331c98c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 12:21:41 -0700 Subject: [PATCH 2/2] trun: add TrunSamples::get and a constant-time nth Indexing replaces the old entries[n], and skipping into an inherited run no longer steps through every sample. Co-Authored-By: Claude Opus 5.5 --- src/moof/traf/trun.rs | 69 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/src/moof/traf/trun.rs b/src/moof/traf/trun.rs index 293607e9..275d483c 100644 --- a/src/moof/traf/trun.rs +++ b/src/moof/traf/trun.rs @@ -52,6 +52,19 @@ impl TrunSamples { self.len() == 0 } + /// The entry of the sample at `index`, or `None` if it is out of range. + pub fn get(&self, index: usize) -> Option { + match self { + Self::Inherited { count, first_flags } => { + (index < *count as usize).then(|| TrunEntry { + flags: if index == 0 { *first_flags } else { None }, + ..Default::default() + }) + } + Self::Explicit(entries) => entries.get(index).copied(), + } + } + /// Each sample's entry in order, without allocating. pub fn iter(&self) -> TrunSamplesIter<'_> { match self { @@ -117,6 +130,23 @@ impl Iterator for TrunSamplesIter<'_> { } } + fn nth(&mut self, n: usize) -> Option { + match self { + Self::Inherited { + remaining, + first_flags, + } => { + // Every sample after the first is identical, so skip without stepping through them. + if n > 0 { + *first_flags = None; + *remaining = remaining.saturating_sub(n.try_into().unwrap_or(u32::MAX)); + } + } + Self::Explicit(entries) => return entries.nth(n).copied(), + } + self.next() + } + fn size_hint(&self) -> (usize, Option) { let len = match self { Self::Inherited { remaining, .. } => *remaining as usize, @@ -557,6 +587,18 @@ mod test { ); assert_eq!(entries.next(), Some(TrunEntry::default())); assert_eq!(entries.len(), u32::MAX as usize - 2); + + // Skipping into the run takes constant time. + assert_eq!( + entries.nth(u32::MAX as usize - 3), + Some(TrunEntry::default()) + ); + assert_eq!(entries.next(), None); + + let last = u32::MAX as usize - 1; + assert_eq!(decoded.samples.get(0), decoded.samples.iter().next()); + assert_eq!(decoded.samples.get(last), Some(TrunEntry::default())); + assert_eq!(decoded.samples.get(last + 1), None); } } @@ -588,6 +630,33 @@ mod test { assert!(decoded.samples.iter().eq(trun.samples.iter())); } + /// `get` and `nth` agree with stepping through the run in both forms. + #[test] + fn random_access() { + let inherited = TrunSamples::Inherited { + count: 3, + first_flags: Some(0x02000000), + }; + let explicit = TrunSamples::Explicit(vec![ + TrunEntry { + size: Some(1), + ..Default::default() + }, + TrunEntry { + size: Some(2), + ..Default::default() + }, + ]); + + for samples in [inherited, explicit] { + let all: Vec<_> = samples.iter().collect(); + for n in 0..=all.len() { + assert_eq!(samples.get(n), all.get(n).copied()); + assert_eq!(samples.iter().nth(n), all.get(n).copied()); + } + } + } + /// A sample_count larger than the per-sample data fails without reserving for it. #[test] fn explicit_truncated() {