From 3382b9662ab452cffea66a69a00a400288f6f6b4 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 01:10:43 +0100 Subject: [PATCH 01/97] craft-audio: native Vorbis I decoder (#1547) --- crates/audio/Cargo.toml | 14 + crates/audio/README.md | 1 + crates/audio/src/lib.rs | 3 +- crates/audio/src/vorbis/decoder/bits.rs | 96 ++++ crates/audio/src/vorbis/decoder/codebook.rs | 360 ++++++++++++ crates/audio/src/vorbis/decoder/floor.rs | 385 +++++++++++++ crates/audio/src/vorbis/decoder/mdct.rs | 165 ++++++ crates/audio/src/vorbis/decoder/mod.rs | 524 ++++++++++++++++++ crates/audio/src/vorbis/decoder/residue.rs | 150 +++++ crates/audio/src/vorbis/decoder/tables.rs | 263 +++++++++ crates/audio/src/vorbis/mod.rs | 7 +- crates/audio/tests/vorbis_decode_hostile.rs | 230 ++++++++ crates/audio/tests/vorbis_decode_oracle.rs | 203 +++++++ crates/audio/tests/vorbis_decode_synthetic.rs | 375 +++++++++++++ 14 files changed, 2773 insertions(+), 3 deletions(-) create mode 100644 crates/audio/src/vorbis/decoder/bits.rs create mode 100644 crates/audio/src/vorbis/decoder/codebook.rs create mode 100644 crates/audio/src/vorbis/decoder/floor.rs create mode 100644 crates/audio/src/vorbis/decoder/mdct.rs create mode 100644 crates/audio/src/vorbis/decoder/mod.rs create mode 100644 crates/audio/src/vorbis/decoder/residue.rs create mode 100644 crates/audio/src/vorbis/decoder/tables.rs create mode 100644 crates/audio/tests/vorbis_decode_hostile.rs create mode 100644 crates/audio/tests/vorbis_decode_oracle.rs create mode 100644 crates/audio/tests/vorbis_decode_synthetic.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index fe28cec3f..f7d819bee 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -36,6 +36,8 @@ flac-encode = ["craft-media/bitstream"] # The pure-Rust Vorbis encoder (`vorbis::encoder`) and Ogg Vorbis files through `encode` and # `encode_ogg_vorbis`. vorbis-encode = ["craft-media/ogg"] +# The pure-Rust Vorbis decoder (`vorbis::decoder`), packets and whole Ogg Vorbis files. +vorbis-decode = ["craft-media/ogg"] # Codec modules on their own, for packet-level use. aac-decode = ["craft-media/bitstream"] # The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`. @@ -92,6 +94,18 @@ required-features = ["decode", "encode"] name = "flac_decode" required-features = ["flac-decode", "flac-encode"] +[[test]] +name = "vorbis_decode_oracle" +required-features = ["vorbis-decode", "vorbis-encode", "decode"] + +[[test]] +name = "vorbis_decode_hostile" +required-features = ["vorbis-decode", "vorbis-encode"] + +[[test]] +name = "vorbis_decode_synthetic" +required-features = ["vorbis-decode"] + [[test]] name = "qoa_oracle" required-features = ["qoa"] diff --git a/crates/audio/README.md b/crates/audio/README.md index 7469a9401..49a610f51 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -39,6 +39,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` | | `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none | | `vorbis-encode` | `vorbis::encoder::Encoder` (pure Rust); `encode_ogg_vorbis`, `encode_ogg` and `encode` for Ogg Vorbis files (whole buffer; not `FileEncoder`) | craft-media `ogg` | +| `vorbis-decode` | `vorbis::decoder::Decoder` (packets), `vorbis::decoder::decode_ogg` (whole Ogg Vorbis files); native Vorbis I: floors 0 and 1, residues 0 to 2, channel coupling, both block sizes. `decode` still reads Vorbis files through symphonia | craft-media `ogg` | | `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` | | `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` | | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index c7382a973..ffc6945d5 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -13,6 +13,7 @@ //! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through //! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the //! same without symphonia. +//! - [`vorbis::decoder`] (feature `vorbis-decode`): the pure-Rust Vorbis I decoder, packets and Ogg files. //! - [`encode_ogg_vorbis`] and [`vorbis::encoder`] (feature `vorbis-encode`): Ogg Vorbis files //! and Vorbis packets from a pure-Rust encoder, 1 to 8 channels, quality -1 to 10, with tags. //! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar @@ -58,7 +59,7 @@ pub mod qoa; mod read; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] mod track; -#[cfg(feature = "vorbis-encode")] +#[cfg(any(feature = "vorbis-decode", feature = "vorbis-encode"))] pub mod vorbis; #[cfg(any(feature = "decode-native", feature = "pcm-encode"))] mod wav; diff --git a/crates/audio/src/vorbis/decoder/bits.rs b/crates/audio/src/vorbis/decoder/bits.rs new file mode 100644 index 000000000..6735d3d3d --- /dev/null +++ b/crates/audio/src/vorbis/decoder/bits.rs @@ -0,0 +1,96 @@ +//! The Vorbis bit reader (Vorbis I §2): bits are taken least significant first from each byte. + +/// Reading past the end of the packet ("end-of-packet", §2.1.8). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct Eop; + +pub(super) struct BitReader<'a> { + data: &'a [u8], + /// The position of the next bit. + pos: usize, +} + +impl<'a> BitReader<'a> { + pub(super) fn new(data: &'a [u8]) -> Self { + Self { data, pos: 0 } + } + + /// The bits not yet read. + pub(super) fn remaining(&self) -> usize { + (self.data.len() * 8).saturating_sub(self.pos) + } + + /// Read `n` (at most 32) bits as an unsigned integer. A read that does not fit takes nothing. + pub(super) fn read(&mut self, n: u32) -> Result { + if n == 0 { + return Ok(0); + } + if (n as usize) > self.remaining() { + self.pos = self.data.len() * 8; + return Err(Eop); + } + let mut value = 0u64; + let mut got = 0u32; + while got < n { + let byte = u64::from(self.data[self.pos / 8]); + let shift = (self.pos % 8) as u32; + let take = (8 - shift).min(n - got); + value |= ((byte >> shift) & ((1 << take) - 1)) << got; + got += take; + self.pos += take as usize; + } + Ok(value as u32) + } + + pub(super) fn bit(&mut self) -> Result { + Ok(self.read(1)? == 1) + } +} + +/// `ilog(x)` (§9.2.1): the position of the highest set bit, 0 for values below 1. +pub(super) fn ilog(x: i64) -> u32 { + if x <= 0 { 0 } else { 64 - (x as u64).leading_zeros() } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_least_significant_bit_first() { + // Fields come out of each byte from its least significant bit. + let mut r = BitReader::new(&[0xFC, 0x08]); + assert_eq!(r.read(4), Ok(0xC)); + assert_eq!(r.read(4), Ok(0xF)); + assert_eq!(r.read(1), Ok(0)); + assert_eq!(r.read(3), Ok(4)); + assert_eq!(r.read(4), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn wide_reads_span_bytes_and_zero_bits_are_free() { + let mut r = BitReader::new(&[0x01, 0x02, 0x03, 0x04, 0x05]); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(32), Ok(0x0403_0201)); + assert_eq!(r.read(8), Ok(5)); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + assert_eq!(r.remaining(), 0); + } + + #[test] + fn a_failed_read_consumes_the_rest() { + let mut r = BitReader::new(&[0xFF]); + assert_eq!(r.read(3), Ok(7)); + assert_eq!(r.read(6), Err(Eop)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn ilog_matches_the_specification_examples() { + for (x, want) in [(0, 0), (1, 1), (2, 2), (3, 2), (4, 3), (7, 3), (-5, 0), (255, 8), (256, 9)] { + assert_eq!(ilog(x), want, "ilog({x})"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/codebook.rs b/crates/audio/src/vorbis/decoder/codebook.rs new file mode 100644 index 000000000..f892ff1bf --- /dev/null +++ b/crates/audio/src/vorbis/decoder/codebook.rs @@ -0,0 +1,360 @@ +//! Codebooks (Vorbis I §3): a Huffman code over entry numbers and an optional table of vectors. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; + +const NONE: u32 = u32::MAX; +const LEAF: u32 = 1 << 31; +/// Entries a codebook may declare. +const MAX_ENTRIES: u32 = 1 << 20; +/// Nodes of one codeword tree. +const MAX_NODES: usize = 1 << 22; + +#[derive(Clone, Copy)] +struct Node { + child: [u32; 2], + full: bool, +} + +pub(super) struct Codebook { + pub(super) dimensions: usize, + pub(super) entries: usize, + tree: Vec, + /// The only used entry of a single-entry book. + single: Option, + /// `entries * dimensions` values when the book has a lookup table. + vectors: Vec, +} + +/// `float32_unpack` (§9.2.2). +fn float32_unpack(x: u32) -> f64 { + let mantissa = f64::from(x & 0x001F_FFFF); + let exponent = ((x & 0x7FE0_0000) >> 21) as i32; + let m = if x & 0x8000_0000 != 0 { -mantissa } else { mantissa }; + m * 2f64.powi(exponent - 788) +} + +/// `lookup1_values` (§9.2.3): the greatest `v` with `v^dimensions <= entries`. +fn lookup1_values(entries: u32, dimensions: u32) -> u32 { + let mut v = 1u32; + loop { + let next = u128::from(v) + 1; + let mut p = 1u128; + for _ in 0..dimensions { + p *= next; + if p > u128::from(entries) { + return v; + } + } + v += 1; + } +} + +fn insert(tree: &mut Vec, at: usize, depth: u32, len: u32, entry: u32) -> bool { + for b in 0..2 { + let child = tree[at].child[b]; + if depth + 1 == len { + if child == NONE { + tree[at].child[b] = LEAF | entry; + refresh(tree, at); + return true; + } + continue; + } + if child == NONE { + if tree.len() >= MAX_NODES { + return false; + } + tree.push(Node { child: [NONE; 2], full: false }); + let new = tree.len() - 1; + tree[at].child[b] = new as u32; + if insert(tree, new, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + return false; + } + if child & LEAF != 0 || tree[child as usize].full { + continue; + } + if insert(tree, child as usize, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + } + false +} + +fn refresh(tree: &mut [Node], at: usize) { + let done = |c: u32, t: &[Node]| c != NONE && (c & LEAF != 0 || t[c as usize].full); + let full = done(tree[at].child[0], tree) && done(tree[at].child[1], tree); + tree[at].full = full; +} + +impl Codebook { + /// Read one codebook from a setup header. `budget` is the bytes the setup's codebooks may + /// still take in all. + pub(super) fn read(r: &mut BitReader<'_>, budget: &mut usize) -> Result { + let bad = |m: &'static str| Error::Setup(m); + let eop = |_: Eop| Error::Setup("setup header ends inside a codebook"); + if r.read(24).map_err(eop)? != 0x0056_4342 { + return Err(bad("codebook sync pattern missing")); + } + let dimensions = r.read(16).map_err(eop)?; + let entries = r.read(24).map_err(eop)?; + if dimensions == 0 || entries == 0 || entries > MAX_ENTRIES { + return Err(bad("codebook with no dimensions, no entries or too many")); + } + let mut lengths: Vec = Vec::with_capacity(entries as usize); + if r.bit().map_err(eop)? { + // Ordered: the number of codewords of each length. + let mut current = 0u32; + let mut len = r.read(5).map_err(eop)? + 1; + while current < entries { + let number = r.read(ilog(i64::from(entries - current))).map_err(eop)?; + if number > entries - current || len > 32 { + return Err(bad("ordered codebook lengths overrun the entries")); + } + lengths.extend(std::iter::repeat_n(len as u8, number as usize)); + current += number; + len += 1; + } + } else { + let sparse = r.bit().map_err(eop)?; + for _ in 0..entries { + if sparse && !r.bit().map_err(eop)? { + lengths.push(0); + } else { + lengths.push((r.read(5).map_err(eop)? + 1) as u8); + } + } + } + + // The codeword tree. + let used = lengths.iter().filter(|&&l| l != 0).count(); + let mut tree = vec![Node { child: [NONE; 2], full: false }]; + let mut single = None; + if used == 1 { + let entry = lengths.iter().position(|&l| l != 0).unwrap_or(0); + if lengths[entry] != 1 { + return Err(bad("a codebook with one used entry must give it length 1")); + } + single = Some(entry as u32); + } else if used > 1 { + for (entry, &len) in lengths.iter().enumerate() { + if len != 0 && !insert(&mut tree, 0, 0, u32::from(len), entry as u32) { + return Err(bad("overspecified codebook")); + } + } + if !tree[0].full { + return Err(bad("underspecified codebook")); + } + } + let tree_bytes = tree.len() * std::mem::size_of::(); + if tree_bytes > *budget { + return Err(Error::Limit("the codebooks are too large")); + } + *budget -= tree_bytes; + + // The lookup table. + let lookup_type = r.read(4).map_err(eop)?; + let mut vectors = Vec::new(); + if lookup_type > 2 { + return Err(bad("reserved codebook lookup type")); + } + if lookup_type != 0 { + let minimum = float32_unpack(r.read(32).map_err(eop)?); + let delta = float32_unpack(r.read(32).map_err(eop)?); + let value_bits = r.read(4).map_err(eop)? + 1; + let sequence = r.bit().map_err(eop)?; + let values = if lookup_type == 1 { lookup1_values(entries, dimensions) as usize } else { entries as usize * dimensions as usize }; + if !minimum.is_finite() || !delta.is_finite() || values > r.remaining() / value_bits as usize { + return Err(bad("codebook lookup table is damaged or truncated")); + } + let multiplicands: Vec = (0..values).map(|_| r.read(value_bits).unwrap_or(0)).collect(); + let total = entries as usize * dimensions as usize; + if total.saturating_mul(4) > *budget { + return Err(Error::Limit("the codebooks' vector tables are too large")); + } + *budget -= total * 4; + vectors = vec![0f32; total]; + for e in 0..entries as usize { + let out = &mut vectors[e * dimensions as usize..(e + 1) * dimensions as usize]; + let mut last = 0f64; + let mut divisor = 1usize; + for (i, slot) in out.iter_mut().enumerate() { + let m = if lookup_type == 1 { + let at = (e / divisor) % values; + divisor = divisor.saturating_mul(values); + multiplicands[at] + } else { + multiplicands[e * dimensions as usize + i] + }; + let v = f64::from(m) * delta + minimum + last; + if sequence { + last = v; + } + *slot = v as f32; + } + } + } + Ok(Self { dimensions: dimensions as usize, entries: entries as usize, tree, single, vectors }) + } + + /// Whether the book has a lookup table. + pub(super) fn has_vectors(&self) -> bool { + !self.vectors.is_empty() + } + + /// Read a codeword; the entry number (scalar context). + pub(super) fn scalar(&self, r: &mut BitReader<'_>) -> Result { + if let Some(e) = self.single { + r.read(1)?; + return Ok(e); + } + let mut at = 0usize; + loop { + let c = self.tree[at].child[usize::from(r.bit()?)]; + if c == NONE { + return Err(Eop); + } + if c & LEAF != 0 { + return Ok(c & !LEAF); + } + at = c as usize; + } + } + + /// Read a codeword and return its vector (VQ context); `None` for a book without a table. + pub(super) fn vector(&self, r: &mut BitReader<'_>) -> Result, Eop> { + let e = self.scalar(r)? as usize; + Ok(self.vectors.get(e * self.dimensions..(e + 1) * self.dimensions)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Pack fields least significant bit first. + struct W(Vec, usize); + impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } + } + + fn book_bytes(lengths: &[u32], lookup: Option<(u32, u32, &[u32])>) -> Vec { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(lengths.len() as u64, 24); + w.put(0, 1); // not ordered + w.put(0, 1); // not sparse + for &l in lengths { + w.put(u64::from(l - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(0, 32); // minimum: 0.0 + w.put(0, 32); + w.put(u64::from(bits - 1), 4); + w.put(0, 1); + for &m in mult { + w.put(u64::from(m), bits); + } + } + } + w.0 + } + + #[test] + fn the_specification_example_assigns_its_codewords() { + // §3.2.1: lengths 2 4 4 4 4 2 3 3 -> 00, 0100, 0101, 0110, 0111, 10, 110, 111. + let bytes = book_bytes(&[2, 4, 4, 4, 4, 2, 3, 3], None); + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + let code = |bits: &[u8]| { + let mut w = W(Vec::new(), 0); + for &b in bits { + w.put(u64::from(b), 1); + } + let mut r = BitReader::new(&w.0); + book.scalar(&mut r).expect("entry") + }; + assert_eq!(code(&[0, 0]), 0); + assert_eq!(code(&[0, 1, 0, 0]), 1); + assert_eq!(code(&[0, 1, 1, 1]), 4); + assert_eq!(code(&[1, 0]), 5); + assert_eq!(code(&[1, 1, 0]), 6); + assert_eq!(code(&[1, 1, 1]), 7); + } + + #[test] + fn over_and_underspecified_books_are_errors() { + let mut budget = 1 << 26; + let over = book_bytes(&[1, 1, 1], None); + assert!(Codebook::read(&mut BitReader::new(&over), &mut budget).is_err()); + let under = book_bytes(&[2, 2, 2], None); + assert!(Codebook::read(&mut BitReader::new(&under), &mut budget).is_err()); + } + + #[test] + fn a_single_entry_book_sinks_one_bit_of_either_value() { + let mut budget = 1 << 26; + let bytes = book_bytes(&[1], None); + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + for byte in [0u8, 1] { + let data = [byte]; + let mut r = BitReader::new(&data); + assert_eq!(book.scalar(&mut r), Ok(0)); + assert_eq!(r.remaining(), 7); + } + let bad = book_bytes(&[2], None); + assert!(Codebook::read(&mut BitReader::new(&bad), &mut budget).is_err()); + } + + #[test] + fn lookup_type_one_builds_a_lattice() { + // 4 entries, 2 dimensions, 2 values per dimension: minimum 0 and delta 1 in the packed + // float format are written below by hand (mantissa 1, exponent 788 -> 1.0). + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(4, 24); + w.put(0, 1); + w.put(0, 1); + for _ in 0..4 { + w.put(1, 5); // length 2 each + } + w.put(1, 4); // lookup type 1 + w.put(0, 32); // minimum 0 + w.put((788u64 << 21) | 1, 32); // delta 1.0 + w.put(0, 4); // 1 bit per value + w.put(0, 1); + w.put(0b10, 2); // multiplicands 0, 1 + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&w.0), &mut budget).expect("book"); + assert_eq!(lookup1_values(4, 2), 2); + // Entry e is (m[e % 2], m[(e / 2) % 2]). + assert_eq!(book.vectors, vec![0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0]); + } + + #[test] + fn helper_functions() { + assert_eq!(float32_unpack((788u32 << 21) | 5), 5.0); + assert_eq!(float32_unpack(0x8000_0000 | (789u32 << 21) | 3), -6.0); + for (entries, dims, want) in [(8, 3, 2), (9, 2, 3), (1, 5, 1), (10, 1, 10), (1000, 3, 10), (4_000_000, 2, 2000)] { + assert_eq!(lookup1_values(entries, dims), want, "{entries} entries, {dims} dims"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/floor.rs b/crates/audio/src/vorbis/decoder/floor.rs new file mode 100644 index 000000000..bc6ce4e36 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/floor.rs @@ -0,0 +1,385 @@ +//! Floors (Vorbis I §6 and §7): the spectral envelope each channel's residue is multiplied by. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; +use super::codebook::Codebook; +use super::tables::INVERSE_DB; + +/// Why a floor could not be decoded from a packet. +pub(super) enum Fail { + /// The packet ended (a nominal event: the channel is silent). + Eop, + /// The packet names a codebook that does not exist: it cannot be decoded (§6.2.2). + Invalid, +} + +impl From for Fail { + fn from(_: Eop) -> Self { + Fail::Eop + } +} + +/// What a decoded floor gives to synthesis. +pub(super) enum FloorData { + One { y: Vec, step2: Vec }, + Zero { amplitude: u32, coefficients: Vec }, +} + +pub(super) struct Floor0 { + order: usize, + rate: u32, + bark_map_size: u32, + amplitude_bits: u32, + amplitude_offset: u32, + books: Vec, +} + +pub(super) struct Floor1 { + partition_class: Vec, + class_dimensions: Vec, + class_subclasses: Vec, + class_masterbook: Vec, + subclass_books: Vec>, + multiplier: i32, + range: i32, + xlist: Vec, + /// `(low, high)` neighbour positions of each X from index 2 on. + neighbours: Vec<(usize, usize)>, + /// Indices of `xlist` in ascending X order. + sorted: Vec, +} + +pub(super) enum Floor { + Zero(Floor0), + One(Floor1), +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a floor") +} + +impl Floor { + pub(super) fn read(floor_type: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + match floor_type { + 0 => { + let order = r.read(8).map_err(eop)? as usize; + let rate = r.read(16).map_err(eop)?; + let bark_map_size = r.read(16).map_err(eop)?; + let amplitude_bits = r.read(6).map_err(eop)?; + let amplitude_offset = r.read(8).map_err(eop)?; + let count = r.read(4).map_err(eop)? as usize + 1; + let mut list = Vec::with_capacity(count); + for _ in 0..count { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => list.push(b), + _ => return Err(Error::Setup("floor 0 names a missing codebook or one without vectors")), + } + } + if order == 0 || rate == 0 || bark_map_size == 0 || amplitude_bits > 32 { + return Err(Error::Setup("floor 0 with a zero order, rate or map size, or more than 32 amplitude bits")); + } + Ok(Self::Zero(Floor0 { order, rate, bark_map_size, amplitude_bits, amplitude_offset, books: list })) + } + 1 => { + let partitions = r.read(5).map_err(eop)? as usize; + let mut partition_class = Vec::with_capacity(partitions); + for _ in 0..partitions { + partition_class.push(r.read(4).map_err(eop)? as usize); + } + let classes = partition_class.iter().max().map_or(0, |m| m + 1); + let (mut class_dimensions, mut class_subclasses, mut class_masterbook, mut subclass_books) = (vec![], vec![], vec![], vec![]); + for _ in 0..classes { + class_dimensions.push(r.read(3).map_err(eop)? as usize + 1); + let subs = r.read(2).map_err(eop)?; + class_subclasses.push(subs); + let master = if subs != 0 { r.read(8).map_err(eop)? as usize } else { 0 }; + if subs != 0 && master >= books.len() { + return Err(Error::Setup("floor 1 master book out of range")); + } + class_masterbook.push(master); + let mut list = Vec::new(); + for _ in 0..(1u32 << subs) { + let b = r.read(8).map_err(eop)? as i32 - 1; + if b >= books.len() as i32 { + return Err(Error::Setup("floor 1 subclass book out of range")); + } + list.push(b); + } + subclass_books.push(list); + } + let multiplier = r.read(2).map_err(eop)? as i32 + 1; + let rangebits = r.read(4).map_err(eop)?; + let mut xlist = vec![0, 1i32 << rangebits]; + for &c in &partition_class { + for _ in 0..class_dimensions[c] { + xlist.push(r.read(rangebits).map_err(eop)? as i32); + } + } + if xlist.len() > 65 { + return Err(Error::Setup("floor 1 has more than 65 points")); + } + let mut seen = xlist.clone(); + seen.sort_unstable(); + if seen.windows(2).any(|w| w[0] == w[1]) { + return Err(Error::Setup("floor 1 repeats an X position")); + } + // Low and high neighbours (§9.2.4, §9.2.5) of each point, among those before it. + let mut neighbours = Vec::new(); + for i in 2..xlist.len() { + let (mut lo, mut hi) = (0usize, 1usize); + for j in 0..i { + if xlist[j] < xlist[i] && xlist[j] > xlist[lo] { + lo = j; + } + if xlist[j] > xlist[i] && xlist[j] < xlist[hi] { + hi = j; + } + } + neighbours.push((lo, hi)); + } + let mut sorted: Vec = (0..xlist.len()).collect(); + sorted.sort_by_key(|&i| xlist[i]); + let range = [256, 128, 86, 64][multiplier as usize - 1]; + Ok(Self::One(Floor1 { + partition_class, + class_dimensions, + class_subclasses, + class_masterbook, + subclass_books, + multiplier, + range, + xlist, + neighbours, + sorted, + })) + } + _ => Err(Error::Setup("unknown floor type")), + } + } + + /// Decode one channel's floor from a packet: `None` when the channel is unused this block. + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + match self { + Self::One(f) => Ok(f.decode(r, books)?), + Self::Zero(f) => f.decode(r, books), + } + } + + /// The floor curve over `n` bins (`n` is half the block size). + pub(super) fn curve(&self, data: &FloorData, n: usize) -> Vec { + match (self, data) { + (Self::One(f), FloorData::One { y, step2 }) => f.curve(y, step2, n), + (Self::Zero(f), FloorData::Zero { amplitude, coefficients }) => f.curve(*amplitude, coefficients, n), + _ => vec![0.0; n], + } + } +} + +/// `render_point` (§9.2.6). +fn render_point(x0: i32, y0: i32, x1: i32, y1: i32, x: i32) -> i32 { + let dy = i64::from(y1 - y0); + let adx = i64::from(x1 - x0); + let err = dy.abs() * i64::from(x - x0); + let off = (err / adx) as i32; + if dy < 0 { y0 - off } else { y0 + off } +} + +/// `render_line` (§9.2.7), writing the bins that fall inside `v`. +fn render_line(x0: i32, y0: i32, x1: i32, y1: i32, v: &mut [i32]) { + let dy = y1 - y0; + let adx = x1 - x0; + let base = dy / adx; + let ady = dy.abs() - base.abs() * adx; + let sy = if dy < 0 { base - 1 } else { base + 1 }; + let (mut y, mut err) = (y0, 0); + if let Some(slot) = usize::try_from(x0).ok().and_then(|x| v.get_mut(x)) { + *slot = y; + } + for x in x0 + 1..x1 { + err += ady; + if err >= adx { + err -= adx; + y += sy; + } else { + y += base; + } + match usize::try_from(x).ok().and_then(|x| v.get_mut(x)) { + Some(slot) => *slot = y, + None => break, + } + } +} + +impl Floor1 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Eop> { + if !r.bit()? { + return Ok(None); + } + let bits = ilog(i64::from(self.range) - 1); + let mut y = vec![0i32; self.xlist.len()]; + y[0] = r.read(bits)? as i32; + y[1] = r.read(bits)? as i32; + let mut offset = 2usize; + for &class in &self.partition_class { + let cdim = self.class_dimensions[class]; + let cbits = self.class_subclasses[class]; + let csub = (1u32 << cbits) - 1; + let mut cval = 0u32; + if cbits > 0 { + cval = books[self.class_masterbook[class]].scalar(r)?; + } + for j in 0..cdim { + let book = self.subclass_books[class][(cval & csub) as usize]; + cval >>= cbits; + y[offset + j] = if book >= 0 { books[book as usize].scalar(r)? as i32 } else { 0 }; + } + offset += cdim; + } + + // Step 1: amplitude synthesis (§7.2.4). + let mut step2 = vec![false; self.xlist.len()]; + step2[0] = true; + step2[1] = true; + let mut fin = y.clone(); + for i in 2..self.xlist.len() { + let (lo, hi) = self.neighbours[i - 2]; + let predicted = render_point(self.xlist[lo], fin[lo], self.xlist[hi], fin[hi], self.xlist[i]); + let val = y[i]; + let highroom = self.range - predicted; + let lowroom = predicted; + let room = if highroom < lowroom { highroom * 2 } else { lowroom * 2 }; + if val != 0 { + step2[lo] = true; + step2[hi] = true; + step2[i] = true; + fin[i] = if val >= room { + if highroom > lowroom { val - lowroom + predicted } else { predicted - val + highroom - 1 } + } else if val % 2 == 1 { + predicted - (val + 1) / 2 + } else { + predicted + val / 2 + }; + } else { + fin[i] = predicted; + } + // Valid setups never leave the range; a damaged one must not carry out-of-range values on. + fin[i] = fin[i].clamp(0, self.range - 1); + } + Ok(Some(FloorData::One { y: fin, step2 })) + } + + fn curve(&self, fin: &[i32], step2: &[bool], n: usize) -> Vec { + let mut floor = vec![0i32; n]; + let (mut hx, mut hy) = (0i32, 0i32); + let (mut lx, mut ly) = (0i32, fin[self.sorted[0]] * self.multiplier); + for &i in &self.sorted[1..] { + if step2[i] { + hy = fin[i] * self.multiplier; + hx = self.xlist[i]; + render_line(lx, ly, hx, hy, &mut floor); + lx = hx; + ly = hy; + } + } + if (hx as usize) < n { + render_line(hx, hy, n as i32, hy, &mut floor); + } + floor.iter().map(|&v| INVERSE_DB[v.clamp(0, 255) as usize]).collect() + } +} + +impl Floor0 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + let amplitude = r.read(self.amplitude_bits)?; + if amplitude == 0 { + return Ok(None); + } + let book = r.read(ilog(self.books.len() as i64))? as usize; + let Some(&book) = self.books.get(book) else { return Err(Fail::Invalid) }; + let book = &books[book]; + let mut coefficients: Vec = Vec::with_capacity(self.order + book.dimensions); + let mut last = 0f32; + while coefficients.len() < self.order { + let Some(v) = book.vector(r)? else { return Err(Fail::Invalid) }; + coefficients.extend(v.iter().map(|&x| x + last)); + last = coefficients[coefficients.len() - 1]; + } + Ok(Some(FloorData::Zero { amplitude, coefficients })) + } + + fn curve(&self, amplitude: u32, coefficients: &[f32], n: usize) -> Vec { + let bark = |x: f64| 13.1 * (0.00074 * x).atan() + 2.24 * (0.000_000_018_5 * x * x).atan() + 0.0001 * x; + let scale = f64::from(self.bark_map_size) / bark(0.5 * f64::from(self.rate)); + let map: Vec = (0..n) + .map(|i| { + let foobar = (bark(f64::from(self.rate) * i as f64 / (2.0 * n as f64)) * scale).floor() as i64; + foobar.min(i64::from(self.bark_map_size) - 1) + }) + .collect(); + let cos_c: Vec = coefficients.iter().take(self.order).map(|&c| f64::from(c).cos()).collect(); + let amp = f64::from(amplitude); + let offset = f64::from(self.amplitude_offset); + let top = (2f64).powi(self.amplitude_bits as i32) - 1.0; + let mut out = vec![0f32; n]; + let mut i = 0usize; + while i < n { + let omega = std::f64::consts::PI * map[i] as f64 / f64::from(self.bark_map_size); + let cw = omega.cos(); + let (p, q); + if self.order % 2 == 1 { + let mut pp = 1.0 - cw * cw; + for j in 0..(self.order - 1) / 2 { + let d = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d * d; + } + let mut qq = 0.25; + for j in 0..=(self.order - 1) / 2 { + let d = cos_c[2 * j] - cw; + qq *= 4.0 * d * d; + } + p = pp; + q = qq; + } else { + let mut pp = (1.0 - cw) / 2.0; + let mut qq = (1.0 + cw) / 2.0; + for j in 0..self.order / 2 { + let d1 = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d1 * d1; + let d0 = cos_c[2 * j] - cw; + qq *= 4.0 * d0 * d0; + } + p = pp; + q = qq; + } + let linear = (0.115_129_25 * (amp * offset / (top * (p + q).sqrt()) - offset)).exp() as f32; + let key = map[i]; + while i < n && map[i] == key { + out[i] = linear; + i += 1; + } + } + out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn render_line_matches_a_bresenham_walk() { + let mut v = vec![0i32; 16]; + render_line(0, 0, 8, 4, &mut v); + assert_eq!(&v[..8], &[0, 0, 1, 1, 2, 2, 3, 3]); + let mut v = vec![0i32; 16]; + render_line(2, 10, 6, 2, &mut v); + assert_eq!(&v[2..6], &[10, 8, 6, 4]); + // Lines running past the vector stop at its end. + let mut v = vec![0i32; 4]; + render_line(0, 0, 100, 100, &mut v); + assert_eq!(v, vec![0, 1, 2, 3]); + assert_eq!(render_point(0, 0, 10, 10, 5), 5); + assert_eq!(render_point(0, 10, 10, 0, 5), 5); + } +} diff --git a/crates/audio/src/vorbis/decoder/mdct.rs b/crates/audio/src/vorbis/decoder/mdct.rs new file mode 100644 index 000000000..5f4579e62 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mdct.rs @@ -0,0 +1,165 @@ +//! The inverse MDCT of a block (Vorbis I §4.3.7) and the window slopes. +//! +//! `y[j] = sum_k X[k] cos(2*pi/n * (j + 1/2 + n/4) * (k + 1/2))` for `n/2` coefficients and `n` +//! samples, computed as a DCT-IV of the coefficients through an `n/8`-point complex FFT, then +//! unfolded. + +use std::f64::consts::PI; + +#[derive(Clone, Copy, Default)] +struct Cpx { + re: f64, + im: f64, +} + +impl Cpx { + fn mul(self, o: Cpx) -> Cpx { + Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re } + } +} + +fn cis(t: f64) -> Cpx { + Cpx { re: t.cos(), im: t.sin() } +} + +pub(super) struct Imdct { + n: usize, + twiddle: Vec, + post: Vec, + fft_tw: Vec, + rev: Vec, +} + +impl Imdct { + /// For blocks of `n` samples, a power of two of at least 16. + pub(super) fn new(n: usize) -> Self { + let m = n / 2; + let h = m / 2; + let twiddle = (0..h).map(|j| cis(-PI * (4.0 * j as f64 + 1.0) / (4.0 * m as f64))).collect(); + let post = (0..h).map(|k| cis(-PI * k as f64 / m as f64)).collect(); + let fft_tw = (0..h / 2).map(|j| cis(-2.0 * PI * j as f64 / h as f64)).collect(); + let bits = h.trailing_zeros(); + let rev = (0..h).map(|i| if bits == 0 { 0 } else { i.reverse_bits() >> (usize::BITS - bits) }).collect(); + Self { n, twiddle, post, fft_tw, rev } + } + + /// `x`: `n/2` coefficients; `out`: `n` samples. + pub(super) fn inverse(&self, x: &[f32], out: &mut [f32]) { + let m = self.n / 2; + let q = self.n / 4; + let h = m / 2; + let mut z: Vec = (0..h).map(|j| Cpx { re: f64::from(x[2 * j]), im: f64::from(x[m - 1 - 2 * j]) }.mul(self.twiddle[j])).collect(); + self.fft(&mut z); + let mut v = vec![0f64; m]; + for (k, c) in z.iter().enumerate() { + let d = c.mul(self.post[k]); + v[2 * k] = d.re; + v[m - 1 - 2 * k] = -d.im; + } + // Unfold the DCT-IV output to the block. + for i in 0..q { + out[3 * q - 1 - i] = (-v[i]) as f32; + out[3 * q + i] = (-v[i]) as f32; + } + for i in q..2 * q { + out[i - q] = v[i] as f32; + out[3 * q - 1 - i] = (-v[i]) as f32; + } + } + + fn fft(&self, a: &mut [Cpx]) { + let h = a.len(); + for i in 0..h { + let j = self.rev[i]; + if i < j { + a.swap(i, j); + } + } + let mut len = 2; + while len <= h { + let step = h / len; + for start in (0..h).step_by(len) { + for k in 0..len / 2 { + let w = self.fft_tw[k * step]; + let u = a[start + k]; + let t = a[start + k + len / 2].mul(w); + a[start + k] = Cpx { re: u.re + t.re, im: u.im + t.im }; + a[start + k + len / 2] = Cpx { re: u.re - t.re, im: u.im - t.im }; + } + } + len *= 2; + } + } +} + +/// The rising half of the Vorbis window over `len` samples (§4.3.1): +/// `sin(pi/2 * sin^2((i + 0.5) / len * pi/2))`. +pub(super) fn slope(len: usize) -> Vec { + (0..len) + .map(|i| { + let s = (PI / 2.0 * (i as f64 + 0.5) / len as f64).sin(); + (PI / 2.0 * s * s).sin() as f32 + }) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn matches_the_direct_formula() { + for n in [16usize, 64, 256, 2048] { + let x: Vec = (0..n / 2).map(|i| ((i * 7919 % 211) as f32 - 105.0) / 50.0).collect(); + let mut fast = vec![0f32; n]; + Imdct::new(n).inverse(&x, &mut fast); + for j in [0usize, 1, 2, n / 4, n / 2, n - 1] { + let direct: f64 = + (0..n / 2).map(|k| f64::from(x[k]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos()).sum(); + assert!((direct - f64::from(fast[j])).abs() < 1e-3 * (1.0 + direct.abs()), "n={n} j={j}: {direct} vs {}", fast[j]); + } + } + } + + #[test] + fn windowed_overlap_add_reconstructs_the_signal() { + // Forward MDCT by the definition with the 2/M scale an encoder uses, then this inverse. + let n = 64usize; + let m = n / 2; + let signal: Vec = (0..n * 6).map(|i| ((i * 37 % 101) as f64 - 50.0) / 50.0).collect(); + let w: Vec = slope(m).into_iter().chain(slope(m).into_iter().rev()).collect(); + let imdct = Imdct::new(n); + let mut out = vec![0f64; signal.len()]; + let mut start = 0; + while start + n <= signal.len() { + let coeffs: Vec = (0..m) + .map(|k| { + let s: f64 = (0..n) + .map(|j| { + signal[start + j] * f64::from(w[j]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos() + }) + .sum(); + (s * 2.0 / m as f64) as f32 + }) + .collect(); + let mut y = vec![0f32; n]; + imdct.inverse(&coeffs, &mut y); + for j in 0..n { + out[start + j] += f64::from(y[j]) * f64::from(w[j]); + } + start += m; + } + for i in m..signal.len() - m { + assert!((out[i] - signal[i]).abs() < 1e-4, "sample {i}: {} vs {}", out[i], signal[i]); + } + } + + #[test] + fn the_slope_is_power_complementary() { + let s = slope(1024); + for i in 0..1024 { + let sum = s[i] * s[i] + s[1023 - i] * s[1023 - i]; + assert!((sum - 1.0).abs() < 1e-5, "{i}: {sum}"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/mod.rs b/crates/audio/src/vorbis/decoder/mod.rs new file mode 100644 index 000000000..8defd8aa3 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mod.rs @@ -0,0 +1,524 @@ +//! A clean-room Vorbis I decoder (feature `vorbis-decode`), written from the Vorbis I +//! specification (Xiph.Org, 2020). +//! +//! [`Decoder`] works on packets: build it from the three header packets (identification, comment +//! and setup), then give it audio packets in order. Each call returns the PCM the packet +//! completes, planar `f32` in the nominal range -1.0 to 1.0 (not clipped), channels in the order of +//! the stream. The first packet only primes the overlap and returns nothing. [`decode_ogg`] reads a +//! whole Ogg Vorbis file. +//! +//! Codebooks, floors 0 and 1, residues 0, 1 and 2, channel coupling and both block sizes with their +//! hybrid windows are implemented. Damaged input is an error, never a panic: setup sizes are +//! bounded before anything is allocated, and the codeword trees are checked for completeness. + +mod bits; +mod codebook; +mod floor; +mod mdct; +mod residue; +mod tables; + +use bits::{BitReader, Eop, ilog}; +use codebook::Codebook; +use floor::{Fail, Floor, FloorData}; +use mdct::{Imdct, slope}; +use residue::Residue; + +/// Errors of the Vorbis decoder. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The identification or comment header is not valid Vorbis. + #[error("invalid Vorbis header: {0}")] + Header(&'static str), + /// The setup header is damaged or uses something Vorbis I does not allow. + #[error("invalid Vorbis setup: {0}")] + Setup(&'static str), + /// The stream's setup asks for more memory than the decoder allows. + #[error("Vorbis setup above the limits: {0}")] + Limit(&'static str), + /// The packet is not an audio packet (a header, or a packet with its first bit set). + #[error("not an audio packet")] + NotAudio, + /// The packet is damaged: it ends before its mode and window flags are read, or names a mode + /// that does not exist. + #[error("damaged audio packet: {0}")] + Packet(&'static str), + /// An Ogg file with no Vorbis stream, or one that cannot be read. + #[error("Ogg Vorbis file: {0}")] + Ogg(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The identification header (§4.2.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Identification { + /// The channel count, at least 1. + pub channels: u8, + /// Samples per second per channel. + pub sample_rate: u32, + /// The maximum bit rate in bits per second, 0 or negative when not set. + pub bitrate_maximum: i32, + /// The nominal bit rate in bits per second, 0 or negative when not set. + pub bitrate_nominal: i32, + /// The minimum bit rate in bits per second, 0 or negative when not set. + pub bitrate_minimum: i32, + /// The short block size in samples. + pub blocksize_0: u32, + /// The long block size in samples. + pub blocksize_1: u32, +} + +/// The comment header (§5): a vendor string and `NAME=value` comments. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Comments { + /// The vendor string of the encoder. + pub vendor: String, + /// The user comments, each `NAME=value`. + pub comments: Vec, +} + +impl Comments { + /// The first comment named `name` (case-insensitive), its value. + #[must_use] + pub fn get(&self, name: &str) -> Option<&str> { + self.comments.iter().find_map(|c| { + let (k, v) = c.split_once('=')?; + k.eq_ignore_ascii_case(name).then_some(v) + }) + } +} + +fn header_start(packet: &[u8], kind: u8) -> Result> { + if packet.len() < 7 || packet[0] != kind || &packet[1..7] != b"vorbis" { + return Err(Error::Header("wrong packet type or missing \"vorbis\" tag")); + } + let mut r = BitReader::new(packet); + let _ = r.read(8); + for _ in 0..6 { + let _ = r.read(8); + } + Ok(r) +} + +fn read_identification(packet: &[u8]) -> Result { + let mut r = header_start(packet, 1)?; + let eop = |_: Eop| Error::Header("identification header is truncated"); + if r.read(32).map_err(eop)? != 0 { + return Err(Error::Header("unsupported Vorbis version")); + } + let channels = r.read(8).map_err(eop)? as u8; + let sample_rate = r.read(32).map_err(eop)?; + let bitrate_maximum = r.read(32).map_err(eop)? as i32; + let bitrate_nominal = r.read(32).map_err(eop)? as i32; + let bitrate_minimum = r.read(32).map_err(eop)? as i32; + let e0 = r.read(4).map_err(eop)?; + let e1 = r.read(4).map_err(eop)?; + if !r.bit().map_err(eop)? { + return Err(Error::Header("identification header framing bit is not set")); + } + if channels == 0 || sample_rate == 0 { + return Err(Error::Header("no channels or a zero sample rate")); + } + if !(6..=13).contains(&e0) || !(6..=13).contains(&e1) || e0 > e1 { + return Err(Error::Header("block sizes must be powers of two from 64 to 8192, the short one not above the long one")); + } + Ok(Identification { channels, sample_rate, bitrate_maximum, bitrate_nominal, bitrate_minimum, blocksize_0: 1 << e0, blocksize_1: 1 << e1 }) +} + +/// Comments are best effort: damage here is not fatal (§4.2.1). +fn read_comments(packet: &[u8]) -> Result { + header_start(packet, 3)?; + let mut at = 7usize; + let mut take = |n: usize| -> Option<&[u8]> { + let s = packet.get(at..at.checked_add(n)?)?; + at += n; + Some(s) + }; + let word = |b: &[u8]| u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize; + let mut out = Comments::default(); + let Some(n) = take(4).map(word) else { return Ok(out) }; + let Some(vendor) = take(n) else { return Ok(out) }; + out.vendor = String::from_utf8_lossy(vendor).into_owned(); + let Some(count) = take(4).map(word) else { return Ok(out) }; + for _ in 0..count { + let Some(n) = take(4).map(word) else { break }; + let Some(c) = take(n) else { break }; + out.comments.push(String::from_utf8_lossy(c).into_owned()); + } + Ok(out) +} + +struct Mapping { + coupling: Vec<(usize, usize)>, + mux: Vec, + /// `(floor, residue)` of each submap. + submaps: Vec<(usize, usize)>, +} + +struct Mode { + long: bool, + mapping: usize, +} + +struct Setup { + books: Vec, + floors: Vec, + residues: Vec, + mappings: Vec, + modes: Vec, +} + +/// Bytes the codebooks of a setup may take in all (codeword trees and vector tables). +const CODEBOOK_BUDGET: usize = 256 << 20; + +fn read_setup(packet: &[u8], channels: usize) -> Result { + let mut r = header_start(packet, 5)?; + let eop = |_: Eop| Error::Setup("setup header is truncated"); + let count = r.read(8).map_err(eop)? as usize + 1; + let mut budget = CODEBOOK_BUDGET; + let mut books = Vec::with_capacity(count); + for _ in 0..count { + books.push(Codebook::read(&mut r, &mut budget)?); + } + // Time domain transforms: placeholders. + for _ in 0..r.read(6).map_err(eop)? + 1 { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("a time domain transform is not zero")); + } + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut floors = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + floors.push(Floor::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut residues = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + if kind > 2 { + return Err(Error::Setup("unknown residue type")); + } + residues.push(Residue::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut mappings = Vec::with_capacity(count); + for _ in 0..count { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("unknown mapping type")); + } + let submaps = if r.bit().map_err(eop)? { r.read(4).map_err(eop)? as usize + 1 } else { 1 }; + let mut coupling = Vec::new(); + if r.bit().map_err(eop)? { + let steps = r.read(8).map_err(eop)? as usize + 1; + let bits = ilog(channels as i64 - 1); + for _ in 0..steps { + let magnitude = r.read(bits).map_err(eop)? as usize; + let angle = r.read(bits).map_err(eop)? as usize; + if magnitude == angle || magnitude >= channels || angle >= channels { + return Err(Error::Setup("channel coupling names an invalid channel pair")); + } + coupling.push((magnitude, angle)); + } + } + if r.read(2).map_err(eop)? != 0 { + return Err(Error::Setup("reserved mapping bits are set")); + } + let mut mux = vec![0usize; channels]; + if submaps > 1 { + for m in &mut mux { + *m = r.read(4).map_err(eop)? as usize; + if *m >= submaps { + return Err(Error::Setup("channel multiplexed to a submap that does not exist")); + } + } + } + let mut list = Vec::with_capacity(submaps); + for _ in 0..submaps { + r.read(8).map_err(eop)?; + let floor = r.read(8).map_err(eop)? as usize; + let residue = r.read(8).map_err(eop)? as usize; + if floor >= floors.len() || residue >= residues.len() { + return Err(Error::Setup("submap names a floor or residue that does not exist")); + } + list.push((floor, residue)); + } + mappings.push(Mapping { coupling, mux, submaps: list }); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut modes = Vec::with_capacity(count); + for _ in 0..count { + let long = r.bit().map_err(eop)?; + let window = r.read(16).map_err(eop)?; + let transform = r.read(16).map_err(eop)?; + let mapping = r.read(8).map_err(eop)? as usize; + if window != 0 || transform != 0 || mapping >= mappings.len() { + return Err(Error::Setup("a mode has a nonzero window or transform type or an unknown mapping")); + } + modes.push(Mode { long, mapping }); + } + if !r.bit().map_err(eop)? { + return Err(Error::Setup("setup header framing bit is not set")); + } + Ok(Setup { books, floors, residues, mappings, modes }) +} + +/// The previous block, windowed, kept for overlap-add. +struct Previous { + n: usize, + data: Vec>, +} + +/// A Vorbis I packet decoder. +pub struct Decoder { + id: Identification, + comments: Comments, + setup: Setup, + imdct: [Imdct; 2], + slopes: [Vec; 2], + previous: Option, +} + +impl Decoder { + /// A decoder from the three header packets, in order. A damaged comment header is tolerated + /// (its comments are then empty); the other two must be valid. + pub fn new(identification: &[u8], comment: &[u8], setup: &[u8]) -> Result { + let id = read_identification(identification)?; + let comments = read_comments(comment)?; + let setup = read_setup(setup, usize::from(id.channels))?; + let (b0, b1) = (id.blocksize_0 as usize, id.blocksize_1 as usize); + Ok(Self { id, comments, setup, imdct: [Imdct::new(b0), Imdct::new(b1)], slopes: [slope(b0 / 2), slope(b1 / 2)], previous: None }) + } + + /// The identification header. + #[must_use] + pub fn identification(&self) -> &Identification { + &self.id + } + + /// The comment header. + #[must_use] + pub fn comments(&self) -> &Comments { + &self.comments + } + + /// Forget the previous block, as after a seek: the next packet only primes the overlap again. + pub fn reset(&mut self) { + self.previous = None; + } + + /// The window of a block (§4.3.1). + fn window(&self, n: usize, long: bool, prev_long: bool, next_long: bool) -> Vec { + let half = n / 2; + let b0 = self.id.blocksize_0 as usize; + let mut w = vec![0f32; n]; + // Left half. + if long && !prev_long { + let (start, end) = (n / 4 - b0 / 4, n / 4 + b0 / 4); + w[start..end].copy_from_slice(&self.slopes[0]); + w[end..half].fill(1.0); + } else { + w[..half].copy_from_slice(&self.slopes[usize::from(long)]); + } + // Right half. + if long && !next_long { + let start = 3 * n / 4 - b0 / 4; + w[half..start].fill(1.0); + for (i, s) in self.slopes[0].iter().rev().enumerate() { + w[start + i] = *s; + } + } else { + for (i, s) in self.slopes[usize::from(long)].iter().rev().enumerate() { + w[half + i] = *s; + } + } + w + } + + /// Decode one audio packet. The result holds one `Vec` per channel, all of the same length: + /// the samples this packet completes (none for the first packet after a start or reset). + pub fn decode_packet(&mut self, packet: &[u8]) -> Result>> { + let channels = usize::from(self.id.channels); + let mut r = BitReader::new(packet); + match r.bit() { + Ok(false) => {} + Ok(true) => return Err(Error::NotAudio), + Err(_) => return Err(Error::Packet("empty packet")), + } + let mode_bits = ilog(self.setup.modes.len() as i64 - 1); + let mode_number = r.read(mode_bits).map_err(|_| Error::Packet("packet ends inside the mode number"))? as usize; + let Some(mode) = self.setup.modes.get(mode_number) else { return Err(Error::Packet("mode number out of range")) }; + let long = mode.long; + let n = if long { self.id.blocksize_1 } else { self.id.blocksize_0 } as usize; + let (mut prev_long, mut next_long) = (true, true); + if long { + prev_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + next_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + } + let window = self.window(n, long, prev_long, next_long); + let half = n / 2; + let mapping = &self.setup.mappings[mode.mapping]; + + let spectrum = self.spectrum(&mut r, mapping, half, channels)?; + // Inverse transform and window. + let which = usize::from(long); + let mut blocks: Vec> = Vec::with_capacity(channels); + for s in &spectrum { + let mut y = vec![0f32; n]; + self.imdct[which].inverse(s, &mut y); + for (v, w) in y.iter_mut().zip(&window) { + *v *= *w; + } + blocks.push(y); + } + + // Overlap-add with the previous block (§4.3.8). + let out = match &self.previous { + None => vec![Vec::new(); channels], + Some(prev) => { + let count = prev.n / 4 + n / 4; + blocks + .iter() + .zip(&prev.data) + .map(|(cur, old)| { + (0..count) + .map(|k| { + let a = old.get(prev.n / 2 + k).copied().unwrap_or(0.0); + let b = (n / 4 + k).checked_sub(prev.n / 4).and_then(|i| cur.get(i)).copied().unwrap_or(0.0); + a + b + }) + .collect() + }) + .collect() + } + }; + self.previous = Some(Previous { n, data: blocks }); + Ok(out) + } + + /// Floors, residues, coupling and the dot product: the spectrum of each channel (§4.3.2 to 4.3.6). + fn spectrum(&self, r: &mut BitReader<'_>, mapping: &Mapping, half: usize, channels: usize) -> Result>> { + let zero = || vec![vec![0f32; half]; channels]; + let setup = &self.setup; + // Floors, in channel order. + let mut floors: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + match setup.floors[floor].decode(r, &setup.books) { + Ok(f) => floors.push(f), + Err(Fail::Eop) => return Ok(zero()), + Err(Fail::Invalid) => return Err(Error::Packet("a floor names a codebook that does not exist")), + } + } + let mut no_residue: Vec = floors.iter().map(Option::is_none).collect(); + for &(m, a) in &mapping.coupling { + if !no_residue[m] || !no_residue[a] { + no_residue[m] = false; + no_residue[a] = false; + } + } + // Residues, in submap order. + let mut residue = zero(); + for (i, &(_, res)) in mapping.submaps.iter().enumerate() { + let members: Vec = (0..channels).filter(|&c| mapping.mux[c] == i).collect(); + if members.is_empty() { + continue; + } + let skip: Vec = members.iter().map(|&c| no_residue[c]).collect(); + let mut vectors = vec![vec![0f32; half]; members.len()]; + setup.residues[res].decode(r, &setup.books, half, &skip, &mut vectors); + for (v, &c) in vectors.into_iter().zip(&members) { + residue[c] = v; + } + } + // Inverse channel coupling (§4.3.5), last step first. + for &(m, a) in mapping.coupling.iter().rev() { + let mut mag = std::mem::take(&mut residue[m]); + let mut ang = std::mem::take(&mut residue[a]); + for (mv, av) in mag.iter_mut().zip(ang.iter_mut()) { + let (big, small) = (*mv, *av); + let (new_m, new_a); + if big > 0.0 { + if small > 0.0 { + new_m = big; + new_a = big - small; + } else { + new_a = big; + new_m = big + small; + } + } else if small > 0.0 { + new_m = big; + new_a = big + small; + } else { + new_a = big; + new_m = big - small; + } + *mv = new_m; + *av = new_a; + } + residue[m] = mag; + residue[a] = ang; + } + // The floor times the residue. + for ch in 0..channels { + match &floors[ch] { + Some(data) => { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + let curve = setup.floors[floor].curve(data, half); + for (v, c) in residue[ch].iter_mut().zip(curve) { + *v *= c; + } + } + None => residue[ch].fill(0.0), + } + } + Ok(residue) + } +} + +/// A decoded Ogg Vorbis file. +#[derive(Debug, Clone, PartialEq)] +pub struct Decoded { + /// Samples per second per channel. + pub sample_rate: u32, + /// One `Vec` of samples per channel. + pub channels: Vec>, + /// The stream's comment header. + pub comments: Comments, + /// Audio packets that could not be decoded and were skipped. + pub damaged_packets: usize, +} + +/// Decode the first Vorbis stream of an Ogg file. The result is trimmed to the stream's final +/// granule position, so an encoder's padding at the end is dropped. Damaged packets are skipped +/// and counted, not fatal. +pub fn decode_ogg(data: &[u8]) -> Result { + let ogg = craft_media::ogg::open(data).map_err(|e| Error::Ogg(e.to_string()))?; + let index = ogg.stream_of(craft_media::ogg::Codec::Vorbis).ok_or_else(|| Error::Ogg("no Vorbis stream".into()))?; + let stream = &ogg.streams[index]; + let [id, comment, setup, ..] = stream.headers.as_slice() else { return Err(Error::Ogg("the stream has fewer than three header packets".into())) }; + let mut decoder = Decoder::new(id, comment, setup)?; + let channel_count = usize::from(decoder.id.channels); + let mut channels = vec![Vec::new(); channel_count]; + let mut damaged = 0; + for i in 0..stream.packets.len() { + let packet = ogg.read_packet(data, index, i).map_err(|e| Error::Ogg(e.to_string()))?; + match decoder.decode_packet(&packet) { + Ok(pcm) => { + for (all, new) in channels.iter_mut().zip(pcm) { + all.extend(new); + } + } + Err(_) => damaged += 1, + } + } + if let Some(total) = stream.last_granule.and_then(|g| usize::try_from(g).ok()) { + for c in &mut channels { + c.truncate(total); + } + } + Ok(Decoded { sample_rate: decoder.id.sample_rate, channels, comments: decoder.comments.clone(), damaged_packets: damaged }) +} diff --git a/crates/audio/src/vorbis/decoder/residue.rs b/crates/audio/src/vorbis/decoder/residue.rs new file mode 100644 index 000000000..48beb354b --- /dev/null +++ b/crates/audio/src/vorbis/decoder/residue.rs @@ -0,0 +1,150 @@ +//! Residues (Vorbis I §8): the fine detail of the spectrum, coded as vectors in passes. + +use super::Error; +use super::bits::{BitReader, Eop}; +use super::codebook::Codebook; + +pub(super) struct Residue { + kind: u32, + begin: usize, + end: usize, + partition_size: usize, + classifications: usize, + classbook: usize, + /// `books[class][pass]`. + books: Vec<[Option; 8]>, +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a residue") +} + +impl Residue { + pub(super) fn read(kind: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + let begin = r.read(24).map_err(eop)? as usize; + let end = r.read(24).map_err(eop)? as usize; + let partition_size = r.read(24).map_err(eop)? as usize + 1; + let classifications = r.read(6).map_err(eop)? as usize + 1; + let classbook = r.read(8).map_err(eop)? as usize; + let Some(cb) = books.get(classbook) else { return Err(Error::Setup("residue class book out of range")) }; + // classifications ^ dimensions must not exceed the book's entries. + let mut reach = 1u128; + for _ in 0..cb.dimensions { + reach = reach.saturating_mul(classifications as u128); + if reach > cb.entries as u128 { + return Err(Error::Setup("residue class book has too few entries for its classifications")); + } + } + let mut cascade = Vec::with_capacity(classifications); + for _ in 0..classifications { + let low = r.read(3).map_err(eop)?; + let high = if r.bit().map_err(eop)? { r.read(5).map_err(eop)? } else { 0 }; + cascade.push(high * 8 + low); + } + let mut list = Vec::with_capacity(classifications); + for &c in &cascade { + let mut row = [None; 8]; + for (j, slot) in row.iter_mut().enumerate() { + if c & (1 << j) != 0 { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => *slot = Some(b), + _ => return Err(Error::Setup("residue names a missing codebook or one without vectors")), + } + } + } + list.push(row); + } + Ok(Self { kind, begin, end, partition_size, classifications, classbook, books: list }) + } + + /// Decode a bundle of vectors, each `n` long (half the block size), into `out`; a vector marked + /// in `skip` is left zero. End of packet ends decoding where it is (a nominal event). + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook], n: usize, skip: &[bool], out: &mut [Vec]) { + let ch = out.len(); + if self.kind == 2 { + if skip.iter().all(|&s| s) { + return; + } + let mut flat = vec![vec![0f32; n * ch]]; + let _ = self.decode_vectors(r, books, n * ch, &[false], &mut flat); + for i in 0..n { + for (j, v) in out.iter_mut().enumerate() { + v[i] = flat[0][i * ch + j]; + } + } + } else { + let _ = self.decode_vectors(r, books, n, skip, out); + } + } + + fn decode_vectors(&self, r: &mut BitReader<'_>, books: &[Codebook], actual: usize, skip: &[bool], out: &mut [Vec]) -> Result<(), Eop> { + let ch = out.len(); + let begin = self.begin.min(actual); + let end = self.end.min(actual); + if end <= begin { + return Ok(()); + } + let classbook = &books[self.classbook]; + let cpw = classbook.dimensions; + let partitions = (end - begin) / self.partition_size; + let mut classes = vec![vec![0usize; partitions + cpw]; ch]; + for pass in 0..8 { + let mut count = 0usize; + while count < partitions { + if pass == 0 { + for j in 0..ch { + if skip[j] { + continue; + } + let mut temp = classbook.scalar(r)? as usize; + for i in (0..cpw).rev() { + classes[j][i + count] = temp % self.classifications; + temp /= self.classifications; + } + } + } + let mut i = 0; + while i < cpw && count < partitions { + for j in 0..ch { + if skip[j] { + continue; + } + let Some(book) = self.books[classes[j][count]][pass] else { continue }; + let book = &books[book]; + let offset = begin + count * self.partition_size; + self.partition(r, book, &mut out[j][offset..offset + self.partition_size])?; + } + count += 1; + i += 1; + } + } + } + Ok(()) + } + + /// One partition into `v` (the slice of the vector it covers). + fn partition(&self, r: &mut BitReader<'_>, book: &Codebook, v: &mut [f32]) -> Result<(), Eop> { + let n = v.len(); + let dims = book.dimensions; + let step = n / dims; + if self.kind == 0 { + for i in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for (j, &e) in entry.iter().enumerate() { + v[i + j * step] += e; + } + } + } else { + let mut i = 0; + for _ in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for &e in entry { + v[i] += e; + i += 1; + } + } + } + Ok(()) + } +} diff --git a/crates/audio/src/vorbis/decoder/tables.rs b/crates/audio/src/vorbis/decoder/tables.rs new file mode 100644 index 000000000..49e5b97b9 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/tables.rs @@ -0,0 +1,263 @@ +//! `floor1_inverse_dB_table` (Vorbis I §10.1): the 256 linear amplitudes of the floor 1 integer values. + +// The values are printed to the digits the specification gives them. +#![allow(clippy::excessive_precision)] + +pub(super) const INVERSE_DB: [f32; 256] = [ + 1.0649863e-07, + 1.1341951e-07, + 1.2079015e-07, + 1.2863978e-07, + 1.3699951e-07, + 1.4590251e-07, + 1.5538408e-07, + 1.6548181e-07, + 1.7623575e-07, + 1.8768855e-07, + 1.9988561e-07, + 2.1287530e-07, + 2.2670913e-07, + 2.4144197e-07, + 2.5713223e-07, + 2.7384213e-07, + 2.9163793e-07, + 3.1059021e-07, + 3.3077411e-07, + 3.5226968e-07, + 3.7516214e-07, + 3.9954229e-07, + 4.2550680e-07, + 4.5315863e-07, + 4.8260743e-07, + 5.1396998e-07, + 5.4737065e-07, + 5.8294187e-07, + 6.2082472e-07, + 6.6116941e-07, + 7.0413592e-07, + 7.4989464e-07, + 7.9862701e-07, + 8.5052630e-07, + 9.0579828e-07, + 9.6466216e-07, + 1.0273513e-06, + 1.0941144e-06, + 1.1652161e-06, + 1.2409384e-06, + 1.3215816e-06, + 1.4074654e-06, + 1.4989305e-06, + 1.5963394e-06, + 1.7000785e-06, + 1.8105592e-06, + 1.9282195e-06, + 2.0535261e-06, + 2.1869758e-06, + 2.3290978e-06, + 2.4804557e-06, + 2.6416497e-06, + 2.8133190e-06, + 2.9961443e-06, + 3.1908506e-06, + 3.3982101e-06, + 3.6190449e-06, + 3.8542308e-06, + 4.1047004e-06, + 4.3714470e-06, + 4.6555282e-06, + 4.9580707e-06, + 5.2802740e-06, + 5.6234160e-06, + 5.9888572e-06, + 6.3780469e-06, + 6.7925283e-06, + 7.2339451e-06, + 7.7040476e-06, + 8.2047000e-06, + 8.7378876e-06, + 9.3057248e-06, + 9.9104632e-06, + 1.0554501e-05, + 1.1240392e-05, + 1.1970856e-05, + 1.2748789e-05, + 1.3577278e-05, + 1.4459606e-05, + 1.5399272e-05, + 1.6400004e-05, + 1.7465768e-05, + 1.8600792e-05, + 1.9809576e-05, + 2.1096914e-05, + 2.2467911e-05, + 2.3928002e-05, + 2.5482978e-05, + 2.7139006e-05, + 2.8902651e-05, + 3.0780908e-05, + 3.2781225e-05, + 3.4911534e-05, + 3.7180282e-05, + 3.9596466e-05, + 4.2169667e-05, + 4.4910090e-05, + 4.7828601e-05, + 5.0936773e-05, + 5.4246931e-05, + 5.7772202e-05, + 6.1526565e-05, + 6.5524908e-05, + 6.9783085e-05, + 7.4317983e-05, + 7.9147585e-05, + 8.4291040e-05, + 8.9768747e-05, + 9.5602426e-05, + 0.00010181521, + 0.00010843174, + 0.00011547824, + 0.00012298267, + 0.00013097477, + 0.00013948625, + 0.00014855085, + 0.00015820453, + 0.00016848555, + 0.00017943469, + 0.00019109536, + 0.00020351382, + 0.00021673929, + 0.00023082423, + 0.00024582449, + 0.00026179955, + 0.00027881276, + 0.00029693158, + 0.00031622787, + 0.00033677814, + 0.00035866388, + 0.00038197188, + 0.00040679456, + 0.00043323036, + 0.00046138411, + 0.00049136745, + 0.00052329927, + 0.00055730621, + 0.00059352311, + 0.00063209358, + 0.00067317058, + 0.00071691700, + 0.00076350630, + 0.00081312324, + 0.00086596457, + 0.00092223983, + 0.00098217216, + 0.0010459992, + 0.0011139742, + 0.0011863665, + 0.0012634633, + 0.0013455702, + 0.0014330129, + 0.0015261382, + 0.0016253153, + 0.0017309374, + 0.0018434235, + 0.0019632195, + 0.0020908006, + 0.0022266726, + 0.0023713743, + 0.0025254795, + 0.0026895994, + 0.0028643847, + 0.0030505286, + 0.0032487691, + 0.0034598925, + 0.0036847358, + 0.0039241906, + 0.0041792066, + 0.0044507950, + 0.0047400328, + 0.0050480668, + 0.0053761186, + 0.0057254891, + 0.0060975636, + 0.0064938176, + 0.0069158225, + 0.0073652516, + 0.0078438871, + 0.0083536271, + 0.0088964928, + 0.009474637, + 0.010090352, + 0.010746080, + 0.011444421, + 0.012188144, + 0.012980198, + 0.013823725, + 0.014722068, + 0.015678791, + 0.016697687, + 0.017782797, + 0.018938423, + 0.020169149, + 0.021479854, + 0.022875735, + 0.024362330, + 0.025945531, + 0.027631618, + 0.029427276, + 0.031339626, + 0.033376252, + 0.035545228, + 0.037855157, + 0.040315199, + 0.042935108, + 0.045725273, + 0.048696758, + 0.051861348, + 0.055231591, + 0.058820850, + 0.062643361, + 0.066714279, + 0.071049749, + 0.075666962, + 0.080584227, + 0.085821044, + 0.091398179, + 0.097337747, + 0.10366330, + 0.11039993, + 0.11757434, + 0.12521498, + 0.13335215, + 0.14201813, + 0.15124727, + 0.16107617, + 0.17154380, + 0.18269168, + 0.19456402, + 0.20720788, + 0.22067342, + 0.23501402, + 0.25028656, + 0.26655159, + 0.28387361, + 0.30232132, + 0.32196786, + 0.34289114, + 0.36517414, + 0.38890521, + 0.41417847, + 0.44109412, + 0.46975890, + 0.50028648, + 0.53279791, + 0.56742212, + 0.60429640, + 0.64356699, + 0.68538959, + 0.72993007, + 0.77736504, + 0.82788260, + 0.88168307, + 0.9389798, + 1.0, +]; diff --git a/crates/audio/src/vorbis/mod.rs b/crates/audio/src/vorbis/mod.rs index 29c423f1d..15b81bb26 100644 --- a/crates/audio/src/vorbis/mod.rs +++ b/crates/audio/src/vorbis/mod.rs @@ -1,4 +1,7 @@ -//! Vorbis I (feature `vorbis-encode`): the pure-Rust [`encoder`]. Decoding Vorbis goes through -//! [`crate::decode`]. +//! Vorbis I: the pure-Rust [`decoder`] (feature `vorbis-decode`) and [`encoder`] (feature +//! `vorbis-encode`). `craft_audio::decode` still reads Vorbis files through symphonia. +#[cfg(feature = "vorbis-decode")] +pub mod decoder; +#[cfg(feature = "vorbis-encode")] pub mod encoder; diff --git a/crates/audio/tests/vorbis_decode_hostile.rs b/crates/audio/tests/vorbis_decode_hostile.rs new file mode 100644 index 000000000..fba004e10 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_hostile.rs @@ -0,0 +1,230 @@ +//! Hostile input to the Vorbis decoder: damaged headers and packets, truncations, and headers that +//! ask for absurd sizes. Every case is an error or a result, never a panic or a large allocation. + +use craft_audio::vorbis::decoder::{Decoder, Error, decode_ogg}; +use craft_audio::{AudioBuffer, OggVorbisOptions, encode_ogg_vorbis}; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +struct Parts { + ogg: Vec, + headers: Vec>, + packets: Vec>, +} + +fn parts(channels: usize) -> Parts { + let signal: Vec> = (0..channels) + .map(|c| (0..20_000).map(|i| ((i as f32 * (0.03 + 0.01 * c as f32)).sin() * 0.4) + ((i * 7 % 13) as f32 - 6.0) / 60.0).collect()) + .collect(); + let ogg = + encode_ogg_vorbis(&AudioBuffer { sample_rate: 44_100, channels: signal }, &OggVorbisOptions::default().with_quality(4.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[0]; + let packets = (0..s.packets.len()).map(|i| file.read_packet(ogg.as_slice(), 0, i).expect("packet")).collect(); + Parts { headers: s.headers.clone(), packets, ogg } +} + +fn decoder(p: &Parts) -> Decoder { + Decoder::new(&p.headers[0], &p.headers[1], &p.headers[2]).expect("valid headers") +} + +#[test] +fn every_truncated_header_is_an_error() { + let p = parts(2); + for which in [0usize, 2] { + for n in 0..p.headers[which].len() { + let mut h = p.headers.clone(); + h[which].truncate(n); + assert!(Decoder::new(&h[0], &h[1], &h[2]).is_err(), "header {which} cut to {n} bytes"); + } + } + // A damaged comment header is not fatal. + let mut h = p.headers.clone(); + h[1].truncate(12); + let d = Decoder::new(&h[0], &h[1], &h[2]).expect("comments are best effort"); + assert!(d.comments().comments.is_empty()); + assert!(Decoder::new(&p.headers[0], &[], &p.headers[2]).is_err(), "the comment header still needs its tag"); +} + +#[test] +fn damaged_headers_never_panic() { + let p = parts(2); + let mut seed = 99u32; + for which in [0usize, 2] { + let len = p.headers[which].len(); + for _ in 0..800 { + let mut h = p.headers.clone(); + for _ in 0..1 + xorshift(&mut seed) % 3 { + let at = xorshift(&mut seed) as usize % len; + h[which][at] = xorshift(&mut seed) as u8; + } + if let Ok(mut d) = Decoder::new(&h[0], &h[1], &h[2]) { + // A setup that survives must also survive audio packets. + for pk in p.packets.iter().take(6) { + let _ = d.decode_packet(pk); + } + } + } + } +} + +#[test] +fn damaged_packets_never_panic() { + let p = parts(2); + let mut seed = 7u32; + let mut d = decoder(&p); + for pk in &p.packets { + for _ in 0..6 { + let mut bad = pk.clone(); + match xorshift(&mut seed) % 3 { + 0 => bad.truncate(xorshift(&mut seed) as usize % (bad.len() + 1)), + 1 => { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + _ => bad = (0..xorshift(&mut seed) % 300).map(|_| xorshift(&mut seed) as u8).collect(), + } + let _ = d.decode_packet(&bad); + } + } + // The decoder still decodes good packets after all that. + d.reset(); + assert!(d.decode_packet(&p.packets[3]).is_ok()); +} + +#[test] +fn header_packets_and_empty_packets_are_not_audio() { + let p = parts(1); + let mut d = decoder(&p); + assert_eq!(d.decode_packet(&p.headers[0]), Err(Error::NotAudio)); + assert_eq!(d.decode_packet(&p.headers[2]), Err(Error::NotAudio)); + assert!(matches!(d.decode_packet(&[]), Err(Error::Packet(_)))); +} + +#[test] +fn damaged_files_never_panic() { + let p = parts(2); + let mut seed = 31u32; + for _ in 0..120 { + let mut bad = p.ogg.clone(); + for _ in 0..1 + xorshift(&mut seed) % 4 { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + let _ = decode_ogg(&bad); + bad.truncate(xorshift(&mut seed) as usize % bad.len()); + let _ = decode_ogg(&bad); + } + assert!(matches!(decode_ogg(b"not an ogg file"), Err(Error::Ogg(_)))); + assert!(matches!(decode_ogg(&[]), Err(Error::Ogg(_)))); +} + +/// A bit writer for hand-built setups. +#[derive(Default)] +struct W(Vec, usize); +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } +} + +fn setup_with_first_book(book: impl FnOnce(&mut W)) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 8); // one book + book(&mut w); + w.0 +} + +#[test] +fn absurd_codebook_sizes_are_refused_before_allocating() { + let p = parts(1); + let try_setup = |setup: Vec| Decoder::new(&p.headers[0], &p.headers[1], &setup); + // 2^24 - 1 entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(0xFF_FFFF, 24); + w.put(1, 1); // ordered + w.put(0, 5); + })) + .is_err() + ); + // An ordered book whose lengths overrun its entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(8, 24); + w.put(1, 1); + w.put(0, 5); + w.put(0xFF, 4); // asks for more codewords of length 1 than there are entries + })) + .is_err() + ); + // A lookup table of 65535 dimensions over a million entries: 69 billion values. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(0xFFFF, 16); + w.put(1 << 20, 24); + w.put(1, 1); // ordered + w.put(19, 5); // length 20 + w.put(1 << 20, 21); // all the entries + w.put(2, 4); // lookup type 2 + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + })) + .is_err() + ); + // A million-entry book with a legitimate tree but a lookup table that is not in the packet. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(4, 16); + w.put(1 << 20, 24); + w.put(1, 1); + w.put(19, 5); + w.put(1 << 20, 21); + w.put(1, 4); // lookup type 1 + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + })) + .is_err() + ); +} + +#[test] +fn identification_header_limits() { + let p = parts(1); + let mut h = p.headers[0].clone(); + let setup = &p.headers[2]; + h[11] = 0; // no channels + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[28] = 0x95; // a short block size of 2^5 is below the 64 Vorbis allows + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[7] = 1; // version 1 + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); +} diff --git a/crates/audio/tests/vorbis_decode_oracle.rs b/crates/audio/tests/vorbis_decode_oracle.rs new file mode 100644 index 000000000..c455c9df0 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_oracle.rs @@ -0,0 +1,203 @@ +//! The Vorbis decoder against ffmpeg's as the reference (oracle; skipped when ffmpeg is absent, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). Streams come from two encoders, this crate's and +//! ffmpeg's own, so the setups differ: different floors, residues, block sizes, channel counts and +//! coupling. Both decoders must return the same samples. + +use craft_audio::AudioBuffer; +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_audio::{OggVorbisOptions, encode_ogg_vorbis}; +use std::path::Path; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A signal with tones, noise bursts, clicks and silence, different in every channel. +fn signal(rate: u32, channels: usize, frames: usize) -> Vec> { + let mut seed = 0x1234_5678u32; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + let t = i as f64 / f64::from(rate); + let tone = + (t * (220.0 + 110.0 * c as f64) * std::f64::consts::TAU).sin() * 0.3 + (t * 3100.0 * std::f64::consts::TAU).sin() * 0.05; + let noise = (f64::from(xorshift(&mut seed) % 2000) - 1000.0) / 6000.0; + let s = match (i / (rate as usize / 4)) % 6 { + 0 | 1 => tone, + 2 => noise, + 3 => 0.0, + 4 => tone + if i % 3000 < 8 { 0.6 } else { 0.0 }, + _ => tone * (t * 4.0).sin(), + }; + s as f32 + }) + .collect() + }) + .collect() +} + +fn ffmpeg_decode(ffmpeg: &Path, ogg: &Path, channels: usize) -> Vec> { + let out = Command::new(ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(ogg) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", ogg.display(), String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + (0..channels).map(|c| all.iter().skip(c).step_by(channels).copied().collect()).collect() +} + +/// Each of our channels matches a different one of theirs (ffmpeg reorders the channels of surround +/// streams), to within float rounding. +fn assert_same(name: &str, ours: &[Vec], theirs: &[Vec]) { + assert_prefix(name, ours, theirs, true); +} + +/// As [`assert_same`], but with `exact` unset ffmpeg may return more samples than we do (it does +/// not always trim a stream to its last granule position); the common part must agree. +fn assert_prefix(name: &str, ours: &[Vec], theirs: &[Vec], exact: bool) { + assert_eq!(ours.len(), theirs.len(), "{name}: channel count"); + let mut used = vec![false; theirs.len()]; + for (c, o) in ours.iter().enumerate() { + let mut best: Option<(usize, f32)> = None; + for (k, t) in theirs.iter().enumerate() { + if used[k] { + continue; + } + if exact { + assert_eq!(o.len(), t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } else { + assert!(o.len() <= t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } + let worst = o.iter().zip(t).map(|(a, b)| (a - b).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w)| worst < w) { + best = Some((k, worst)); + } + } + let (k, worst) = best.expect("a free channel"); + used[k] = true; + assert!(worst < 2e-4, "{name}: channel {c} differs from ffmpeg's channel {k} by up to {worst}"); + } +} + +#[test] +fn ffmpeg_decodes_our_encoders_streams_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, channels, quality) in + [(44_100u32, 2usize, 6.0f32), (44_100, 1, 3.0), (48_000, 2, -1.0), (22_050, 1, 10.0), (44_100, 6, 5.0), (32_000, 8, 4.0)] + { + let buf = AudioBuffer { sample_rate: rate, channels: signal(rate, channels, rate as usize * 2 + 777) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(quality)).expect("encode"); + let file = dir.join(format!("ours_{rate}_{channels}_{quality}.ogg")); + std::fs::write(&file, &ogg).expect("write fixture"); + let decoded = decode_ogg(&ogg).expect("decode"); + assert_eq!(decoded.damaged_packets, 0); + assert_eq!(decoded.sample_rate, rate); + assert_same(&format!("our stream {rate} Hz {channels} ch q{quality}"), &decoded.channels, &ffmpeg_decode(&ffmpeg, &file, channels)); + } +} + +/// ffmpeg's own Vorbis encoder (stereo only) writes setups ours does not: coupled channels, residue +/// type 2, floor classes with subclasses and master books, two block sizes. The reference is +/// Symphonia, an independent decoder. ffmpeg's decoder agrees on the first channel but not on the +/// second of these streams, where it differs from both Symphonia and this decoder; the stream does +/// not show which reading it means (the channel comes back poorly, about 3 dB SNR, in all three), +/// so ffmpeg is compared on the first channel only. The setups ffmpeg's decoder does read the same +/// way as we do are covered, on both channels, in `vorbis_decode_synthetic.rs`. +#[test] +fn we_decode_ffmpegs_encoder_streams_like_symphonia() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, bitrate) in [(44_100u32, "128k"), (48_000, "96k"), (22_050, "48k"), (32_000, "64k")] { + let channels = 2usize; + let pcm: Vec = { + let s = signal(rate, channels, rate as usize * 2 + 301); + (0..s[0].len()).flat_map(|i| s.iter().map(move |c| c[i])).collect() + }; + let raw = dir.join(format!("src_{rate}_{channels}.f32")); + std::fs::write(&raw, pcm.iter().flat_map(|v| v.to_le_bytes()).collect::>()).expect("write source"); + let file = dir.join(format!("ffmpeg_{rate}_{channels}_{bitrate}.ogg")); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-y", "-f", "f32le", "-ar"]) + .arg(rate.to_string()) + .arg("-ac") + .arg(channels.to_string()) + .arg("-i") + .arg(&raw) + .args(["-c:a", "vorbis", "-strict", "-2", "-b:a", bitrate]) + .arg(&file) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg could not encode {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); + let ogg = std::fs::read(&file).expect("read"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!(ours.damaged_packets, 0, "{}", file.display()); + let (_, symphonia) = craft_audio::decode(&ogg, Some("ogg")).expect("symphonia"); + let name = format!("ffmpeg-encoded {rate} Hz {bitrate}"); + assert_prefix(&name, &ours.channels, &symphonia.channels, false); + // The first channel also agrees with ffmpeg's decoder. + let theirs = ffmpeg_decode(&ffmpeg, &file, channels); + assert_prefix(&format!("{name} (channel 0 against ffmpeg)"), &ours.channels[..1], &theirs[..1], true); + } +} + +#[test] +fn packets_decode_one_at_a_time_to_the_file_result() { + let buf = AudioBuffer { sample_rate: 44_100, channels: signal(44_100, 2, 30_000) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(5.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[file.stream_of(craft_media::ogg::Codec::Vorbis).expect("vorbis")]; + let mut dec = Decoder::new(&s.headers[0], &s.headers[1], &s.headers[2]).expect("decoder"); + assert_eq!((dec.identification().channels, dec.identification().sample_rate), (2, 44_100)); + let mut got: Vec> = vec![Vec::new(); 2]; + for i in 0..s.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + for (a, b) in got.iter_mut().zip(dec.decode_packet(&p).expect("packet decodes")) { + a.extend(b); + } + } + let whole = decode_ogg(&ogg).expect("file"); + for (a, b) in got.iter().zip(&whole.channels) { + assert!(a.len() >= b.len() && a[..b.len()] == b[..]); + } + // After a reset the next packet only primes the overlap again. + dec.reset(); + let p = file.read_packet(ogg.as_slice(), 0, 5).expect("packet"); + assert!(dec.decode_packet(&p).expect("decodes").iter().all(Vec::is_empty)); +} + +#[test] +fn the_round_trip_through_our_encoder_is_faithful() { + let src = signal(44_100, 2, 44_100); + let buf = AudioBuffer { sample_rate: 44_100, channels: src.clone() }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(8.0)).expect("encode"); + let out = decode_ogg(&ogg).expect("decode"); + assert_eq!(out.channels[0].len(), src[0].len()); + let (mut sig, mut err) = (0f64, 0f64); + for (a, b) in src[0].iter().zip(&out.channels[0]) { + sig += f64::from(*a) * f64::from(*a); + err += f64::from(a - b) * f64::from(a - b); + } + assert!(10.0 * (sig / err).log10() > 15.0, "SNR {:.1} dB", 10.0 * (sig / err).log10()); +} + +/// A stream from libvorbis itself (the repository's `tone.ogg` fixture, made with ffmpeg's libvorbis +/// wrapper): mono, 8 kHz, the lowest quality. +#[test] +fn a_libvorbis_stream_decodes_like_ffmpeg() { + let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/tone.ogg"); + let ogg = std::fs::read(&path).expect("fixture"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!((ours.sample_rate, ours.channels.len(), ours.damaged_packets), (8000, 1, 0)); + assert!(ours.comments.vendor.contains("Lavf") || ours.comments.vendor.contains("libVorbis"), "vendor {:?}", ours.comments.vendor); + assert!(ours.channels[0].iter().any(|s| s.abs() > 0.1), "the fixture is a tone"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + assert_prefix("libvorbis tone.ogg", &ours.channels, &ffmpeg_decode(&ffmpeg, &path, 1), false); +} diff --git a/crates/audio/tests/vorbis_decode_synthetic.rs b/crates/audio/tests/vorbis_decode_synthetic.rs new file mode 100644 index 000000000..b15572006 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_synthetic.rs @@ -0,0 +1,375 @@ +//! Differential tests on streams built by hand: a setup header written here, with floor 0 and +//! floor 1 side by side, residues 0, 1 and 2, several submaps and channel coupling, followed by +//! random audio packets. Every packet of random bits is decodable, so the two decoders (ours and +//! ffmpeg's, the oracle; skipped when ffmpeg is absent, a failure with +//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`) must return the same samples, and no encoder's habits narrow +//! what is exercised. Floor 0, residue 0 and multi-submap mappings are the parts no encoder here +//! writes. + +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_media::ogg::{PageWriter, vorbis_comment}; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A least-significant-bit-first bit writer. +#[derive(Default)] +struct W { + bytes: Vec, + bits: usize, +} + +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.bits.is_multiple_of(8) { + self.bytes.push(0); + } + let last = self.bytes.len() - 1; + self.bytes[last] |= (((v >> i) & 1) as u8) << (self.bits % 8); + self.bits += 1; + } + } + fn flag(&mut self, b: bool) { + self.put(u64::from(b), 1); + } +} + +fn float_bits(v: f64) -> u64 { + // The Vorbis float32 packing: sign, 10-bit exponent biased by 788, 21-bit mantissa. + if v == 0.0 { + return 0; + } + let (sign, a) = if v < 0.0 { (1u64 << 31, -v) } else { (0, v) }; + let mut exp = 0i32; + let mut m = a; + while m >= (1 << 21) as f64 { + m /= 2.0; + exp += 1; + } + while m < (1 << 20) as f64 { + m *= 2.0; + exp -= 1; + } + sign | (((exp + 788) as u64) << 21) | (m.round() as u64 & 0x1F_FFFF) +} + +/// A complete codebook: `entries` codewords all of length `len` (`entries == 2^len`), optionally +/// with a lookup table: `(type, minimum, delta, value_bits, multiplicands)`. +fn book(w: &mut W, dims: u32, entries: u32, len: u32, lookup: Option<(u32, f64, f64, u32, Vec)>) { + w.put(0x56_4342, 24); + w.put(u64::from(dims), 16); + w.put(u64::from(entries), 24); + w.flag(false); // not ordered + w.flag(false); // not sparse + for _ in 0..entries { + w.put(u64::from(len - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, min, delta, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(float_bits(min), 32); + w.put(float_bits(delta), 32); + w.put(u64::from(bits - 1), 4); + w.flag(ty == 1); // sequence_p: cumulative for the floor 0 book + for m in mult { + w.put(u64::from(m), bits); + } + } + } +} + +struct Layout { + channels: u8, + /// The residue type of each of the two residues. + residue_types: [u32; 2], + /// The submap of each channel (0 or 1): submap 0 uses floor 0 and residue 0, submap 1 uses + /// floor 1 and residue 1. + mux: Vec, + coupling: Vec<(u8, u8)>, +} + +fn identification(channels: u8) -> Vec { + let mut w = W::default(); + w.put(1, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 32); + w.put(u64::from(channels), 8); + w.put(16_000, 32); + w.put(0, 32); + w.put(0, 32); + w.put(0, 32); + w.put(8, 4); // short blocks: 256 + w.put(10, 4); // long blocks: 1024 + w.flag(true); + w.bytes +} + +fn setup(l: &Layout) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + // Books: 0 floor 0 vectors, 1 class book, 2 and 3 residue vectors, 4 floor 1 values. + w.put(4, 8); // five books + book(&mut w, 4, 16, 4, Some((1, 0.7, 0.2, 1, vec![0, 1]))); // lookup1_values(16, 4) = 2 + book(&mut w, 1, 4, 2, None); + book(&mut w, 2, 16, 4, Some((1, -0.4, 0.25, 2, vec![0, 1, 2, 3]))); // lookup1_values(16, 2) = 4 + book(&mut w, 4, 16, 4, Some((1, -0.3, 0.6, 1, vec![0, 1]))); + book(&mut w, 1, 128, 7, None); + // One time domain placeholder. + w.put(0, 6); + w.put(0, 16); + // Floors: 0 and 1. + w.put(1, 6); // two floors + w.put(0, 16); + w.put(8, 8); // order + w.put(16_000, 16); // rate + w.put(64, 16); // bark map size + w.put(8, 6); // amplitude bits + w.put(2, 8); // amplitude offset + w.put(0, 4); // one book + w.put(0, 8); + w.put(1, 16); + w.put(1, 5); // one partition + w.put(0, 4); // class 0 + w.put(2, 3); // dimension 3 + w.put(0, 2); // no subclasses + w.put(4 + 1, 8); // subclass book: book 4 (stored plus one) + w.put(1, 2); // multiplier 2 + w.put(8, 4); // rangebits + for x in [10, 40, 130] { + w.put(x, 8); + } + // Residues. + w.put(1, 6); // two residues + for ty in l.residue_types { + w.put(u64::from(ty), 16); + w.put(0, 24); // begin + w.put(if ty == 2 { 96 } else { 48 }, 24); // end + w.put(7, 24); // partition size 8 + w.put(3, 6); // four classifications + w.put(1, 8); // class book + for _ in 0..4 { + w.put(0b011, 3); // passes 0 and 1 + w.flag(false); + } + for class in 0..4 { + w.put(2 + (class % 2), 8); // pass 0 uses book 2 or 3 + w.put(3 - (class % 2), 8); // pass 1 uses book 3 or 2 + } + } + // One mapping, two submaps. + w.put(0, 6); + w.put(0, 16); + w.flag(true); + w.put(1, 4); // two submaps + w.flag(!l.coupling.is_empty()); + if !l.coupling.is_empty() { + w.put(l.coupling.len() as u64 - 1, 8); + let bits = if l.channels <= 1 { 0 } else { 8 - (l.channels - 1).leading_zeros() }; + for &(m, a) in &l.coupling { + w.put(u64::from(m), bits); + w.put(u64::from(a), bits); + } + } + w.put(0, 2); + for &m in &l.mux { + w.put(u64::from(m), 4); + } + for sub in 0..2u64 { + w.put(0, 8); + w.put(sub, 8); // floor + w.put(sub, 8); // residue + } + // Two modes over the one mapping. + w.put(1, 6); + for long in [false, true] { + w.flag(long); + w.put(0, 16); + w.put(0, 16); + w.put(0, 8); + } + w.flag(true); + w.bytes +} + +fn stream(l: &Layout, packets: usize, seed: &mut u32) -> Vec { + let mut pages = PageWriter::new(7); + let mut out = pages.header(&identification(l.channels)); + out.extend(pages.header(&vorbis_comment("synthetic", &[("TITLE", "hand built")]))); + out.extend(pages.header(&setup(l))); + // The window flags of a long block say whether its neighbours are long, so choose the block + // sizes first. + let longs: Vec = (0..packets).map(|_| !xorshift(seed).is_multiple_of(3)).collect(); + let mut granule = 0i64; + for i in 0..packets { + let long = longs[i]; + // Packet type 0, the mode bit, and for a long block the two neighbour flags. + let prev = i == 0 || longs[i - 1]; + let next = i + 1 >= packets || longs[i + 1]; + let mut w = W::default(); + w.flag(false); + w.flag(long); + if long { + w.flag(prev); + w.flag(next); + } + // Floor 0 needs a codebook number that exists, which random bits would not give, so the + // channels that use it (the first ones) are written properly: an amplitude, book 0 and two + // codewords of its vectors (a full tree of 4-bit codes: the code is the entry number). + for _ in 0..l.mux.iter().take_while(|&&m| m == 0).count() { + w.put(1 + u64::from(xorshift(seed)) % 24, 8); + w.put(0, 1); + for _ in 0..2 { + let entry = xorshift(seed) % 16; + for bit in (0..4).rev() { + w.put(u64::from(entry >> bit) & 1, 1); + } + } + } + // The rest is random bits, enough that no residue runs out of packet. + let mut p = w.bytes; + let fixed = p.len(); + p.extend((0..200 + xorshift(seed) as usize % 200).map(|_| xorshift(seed) as u8)); + let _ = fixed; + // The bits after the fixed fields start mid-byte: the last fixed byte keeps its own bits and + // takes random ones above them. + let used = w.bits % 8; + if used != 0 { + let last = fixed - 1; + p[last] |= (xorshift(seed) as u8) << used; + } + if i > 0 { + let size = |long: bool| if long { 1024 } else { 256 }; + granule += (size(longs[i - 1]) / 4 + size(long) / 4) as i64; + } + out.extend(pages.packet(&p, granule)); + } + out.extend(pages.finish(None)); + out +} + +/// `tolerance`: the largest difference from ffmpeg, as a fraction of the peak output. A floor 0 +/// curve is an exponential of a quotient that random coefficients can make very large, so where +/// two floors meet in one stream (ffmpeg computes in single precision, we in double) the results +/// agree only to about a thousandth of the peak. +fn run(name: &str, l: &Layout, seed: u32, tolerance: f32) { + let mut s = seed; + let ogg = stream(l, 40, &mut s); + // Packet by packet our decoder must accept every one. + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("setup decodes"); + let mut total = vec![Vec::new(); usize::from(l.channels)]; + for i in 0..st.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + let pcm = dec.decode_packet(&p).unwrap_or_else(|e| panic!("{name}: packet {i}: {e}")); + for (t, c) in total.iter_mut().zip(pcm) { + t.extend(c); + } + } + assert!(total[0].iter().all(|v| v.is_finite()), "{name}: non-finite output"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_synthetic"); + let path = dir.join(format!("{name}.ogg")); + std::fs::write(&path, &ogg).expect("write fixture"); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(&path) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "{name}: ffmpeg failed: {}", String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + let ch = usize::from(l.channels); + let theirs: Vec> = (0..ch).map(|c| all.iter().skip(c).step_by(ch).copied().collect()).collect(); + let _ = decode_ogg(&ogg).expect("whole file"); + // ffmpeg puts the channels of surround streams in its own order, so each of ours is matched + // with the channel of theirs it agrees with best, and every one of theirs is used once. + let mut used = vec![false; ch]; + #[allow(clippy::needless_range_loop)] + for c in 0..ch { + let mut best: Option<(usize, f32, f32)> = None; + for (k, t) in theirs.iter().enumerate().filter(|(k, _)| !used[*k]) { + let n = total[c].len().min(t.len()); + assert!(n > 1000, "{name}: only {n} samples to compare"); + let scale = total[c][..n].iter().fold(1e-3f32, |m, v| m.max(v.abs())); + let worst = (0..n).map(|i| (total[c][i] - t[i]).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w, sc)| worst / scale < w / sc) { + best = Some((k, worst, scale)); + } + } + let (k, worst, scale) = best.expect("a free channel"); + used[k] = true; + assert!(worst <= tolerance * scale + 1e-5, "{name}: channel {c} differs from ffmpeg's channel {k} by {worst} (peak {scale})"); + } +} + +#[test] +fn mono_floor_zero_and_residue_zero() { + run("mono_f0_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![0], coupling: vec![] }, 11, 1e-4); +} + +#[test] +fn mono_floor_one_and_residue_one() { + run("mono_f1_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![1], coupling: vec![] }, 12, 1e-4); +} + +#[test] +fn two_submaps_floor_zero_and_one() { + run("stereo_mixed", &Layout { channels: 2, residue_types: [0, 1], mux: vec![0, 1], coupling: vec![] }, 13, 3e-3); +} + +#[test] +fn coupled_stereo_residue_two() { + run("stereo_coupled_r2", &Layout { channels: 2, residue_types: [2, 2], mux: vec![1, 1], coupling: vec![(0, 1)] }, 14, 1e-4); +} + +#[test] +fn six_channels_with_coupling_and_submaps() { + let l = Layout { channels: 6, residue_types: [1, 2], mux: vec![0, 0, 0, 1, 1, 1], coupling: vec![(0, 3), (1, 2), (4, 5)] }; + run("six", &l, 15, 3e-3); +} + +#[test] +fn mono_floor_one_and_residue_zero() { + run("mono_f1_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![1], coupling: vec![] }, 16, 1e-4); +} + +#[test] +fn mono_floor_zero_and_residue_one() { + run("mono_f0_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }, 17, 1e-4); +} + +/// A packet that names a floor 0 codebook that does not exist cannot be decoded (§6.2.2); the +/// decoder says so and the stream goes on with the next packet. +#[test] +fn a_floor_zero_codebook_that_does_not_exist_is_a_packet_error() { + let l = Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }; + let mut seed = 5u32; + let ogg = stream(&l, 6, &mut seed); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("decoder"); + let good = file.read_packet(ogg.as_slice(), 0, 0).expect("packet"); + assert!(dec.decode_packet(&good).is_ok()); + // A short block: type 0, mode 0, then the 8 amplitude bits, then book number 1 (only 0 exists). + let mut w = W::default(); + w.flag(false); + w.flag(false); + w.put(9, 8); + w.put(1, 1); + w.put(0, 64); + assert!(matches!(dec.decode_packet(&w.bytes), Err(craft_audio::vorbis::decoder::Error::Packet(_)))); + assert!(dec.decode_packet(&good).is_ok(), "the decoder carries on"); +} From 8334fd3c838f212ee55a3618ef0db7f4725afaa8 Mon Sep 17 00:00:00 2001 From: William Dunn Date: Wed, 4 Nov 2026 09:35:49 -0500 Subject: [PATCH 02/97] craft-cloud: cut-down contract plus ui pages --- Cargo.toml | 2 + crates/cloud-local/Cargo.toml | 19 + crates/cloud-local/src/lib.rs | 256 +++++ crates/cloud-local/tests/backend.rs | 241 +++++ crates/cloud/Cargo.toml | 15 + crates/cloud/src/error.rs | 68 ++ crates/cloud/src/lib.rs | 189 ++++ crates/cloud/src/types.rs | 216 ++++ crates/ui/Cargo.toml | 11 + crates/ui/README.md | 60 ++ crates/ui/src/account.rs | 449 ++++++++ crates/ui/src/buttons/mod.rs | 15 + crates/ui/src/cloud/app.rs | 255 +++++ crates/ui/src/cloud/backend.rs | 195 ++++ crates/ui/src/cloud/mod.rs | 852 ++++++++++++++++ crates/ui/src/cloud/pages.rs | 511 ++++++++++ crates/ui/src/cloud/tests.rs | 573 +++++++++++ crates/ui/src/cloud/title.rs | 173 ++++ crates/ui/src/lib.rs | 8 + crates/ui/src/menu.rs | 222 ++++ crates/ui/src/presence.rs | 424 ++++++++ crates/ui/src/share/backend.rs | 170 ++++ crates/ui/src/share/mod.rs | 1465 +++++++++++++++++++++++++++ crates/ui/src/share/tests.rs | 527 ++++++++++ crates/ui/tests/renders.rs | 343 +++++++ crates/ui/tests/share_dialog.rs | 589 +++++++++++ 26 files changed, 7848 insertions(+) create mode 100644 crates/cloud-local/Cargo.toml create mode 100644 crates/cloud-local/src/lib.rs create mode 100644 crates/cloud-local/tests/backend.rs create mode 100644 crates/cloud/Cargo.toml create mode 100644 crates/cloud/src/error.rs create mode 100644 crates/cloud/src/lib.rs create mode 100644 crates/cloud/src/types.rs create mode 100644 crates/ui/src/account.rs create mode 100644 crates/ui/src/cloud/app.rs create mode 100644 crates/ui/src/cloud/backend.rs create mode 100644 crates/ui/src/cloud/mod.rs create mode 100644 crates/ui/src/cloud/pages.rs create mode 100644 crates/ui/src/cloud/tests.rs create mode 100644 crates/ui/src/cloud/title.rs create mode 100644 crates/ui/src/menu.rs create mode 100644 crates/ui/src/presence.rs create mode 100644 crates/ui/src/share/backend.rs create mode 100644 crates/ui/src/share/mod.rs create mode 100644 crates/ui/src/share/tests.rs create mode 100644 crates/ui/tests/renders.rs create mode 100644 crates/ui/tests/share_dialog.rs diff --git a/Cargo.toml b/Cargo.toml index 2c0f4dfea..8b0f0eb21 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -55,6 +55,8 @@ craft-captions = { path = "crates/captions" } craft-cfb = { path = "crates/cfb" } craft-codepage = { path = "crates/codepage" } craft-cms = { path = "crates/cms" } +craft-cloud = { path = "crates/cloud" } +craft-cloud-local = { path = "crates/cloud-local" } craft-color = { path = "crates/color" } craft-frame = { path = "crates/frame" } craft-crs = { path = "crates/crs" } diff --git a/crates/cloud-local/Cargo.toml b/crates/cloud-local/Cargo.toml new file mode 100644 index 000000000..6b58b2bfd --- /dev/null +++ b/crates/cloud-local/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "craft-cloud-local" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "A reference CloudBackend over a local folder, proving the contract needs no specific provider" + +[lints] +workspace = true + +[dependencies] +craft-cloud = { workspace = true } +craft-ui = { workspace = true, features = ["cloud"] } + +[dev-dependencies] +tempfile = "3" +egui = { workspace = true } diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs new file mode 100644 index 000000000..c9c11c015 --- /dev/null +++ b/crates/cloud-local/src/lib.rs @@ -0,0 +1,256 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! A reference [`CloudBackend`] that treats one folder on disk as the cloud. +//! +//! [`craft_ui::cloud::CloudBackend`] names a contract and nothing about who +//! answers it. This crate is the proof: a working implementation that reaches +//! no service, a vendor, or a personal repo anybody else has to trust. An app +//! wires [`LocalBackend`] the same way it would wire a provider's own client, +//! by calling [`craft_ui::cloud::CloudFiles::connect`]. Swapping one for the +//! other is the whole point; nothing above the [`CloudBackend`] seam can tell +//! the difference. +//! +//! What this is not: a sync engine, a sharing service, or a place to keep a +//! credential. A folder has no concept of another account, so +//! [`Job::SharedWithMe`] answers empty and [`Job::Conversation`] answers with +//! a [`Fault`], and [`Account::capabilities`] claims neither. Reporting a +//! capability this backend cannot honour would be the broken window the +//! contract's own docs warn about. +//! +//! Every job answers on its own [`std::thread`]. [`CloudBackend::submit`] +//! must return before the file is opened, let alone read, or a twenty +//! megabyte document would freeze the window that called it. + +use std::fs; +use std::path::{Path, PathBuf}; + +use craft_cloud::{Capability, Entry, EntryKind}; +use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; + +/// Where "the cloud" lives for this backend: one directory on disk. +/// +/// `Entry::id` and `Entry::path` are the same slash-separated path relative to +/// `root`, always starting with `/` below the root itself (the root's own +/// path is the empty string, matching [`Job::List`]'s contract). Neither is +/// an OS path; both go through [`resolve`] before anything touches a +/// filesystem, so a name containing `..` can never walk out of `root`. +pub struct LocalBackend { + root: PathBuf, + /// Shown in the account badge. Nothing else reads it. + display: String, +} + +impl LocalBackend { + /// Treat `root` as the cloud. The directory is not created here; a + /// listing of a root that does not exist yet answers with a [`Fault`] + /// the same way a real provider's missing folder would. + pub fn new(root: PathBuf) -> LocalBackend { + LocalBackend { root, display: "Local disk".to_owned() } + } + + /// Name shown in the account badge, in place of the default "Local disk". + pub fn named(mut self, display: impl Into) -> LocalBackend { + self.display = display.into(); + self + } +} + +impl CloudBackend for LocalBackend { + fn submit(&self, job: Job, post: Post) { + let root = self.root.clone(); + match job { + // Nothing is saved between runs and nothing was ever signed into, + // so there is nothing to forget. The trait states no answer for + // this job; CloudFiles::sign_out clears its own state regardless + // of whether anything ever arrives. + Job::SignOut => {} + Job::Account | Job::SignIn => { + let display = self.display.clone(); + std::thread::spawn(move || post.send(Event::Account(Ok(account(display))))); + } + // There is no browser round trip: a local folder is already + // "linked" the moment it exists. Reporting that immediately, + // rather than inventing a URL nobody needs to visit, is what the + // contract calls honest. + Job::LinkStart | Job::LinkPoll(_) => { + std::thread::spawn(move || post.send(Event::Linked(Ok(true)))); + } + Job::List(path) => { + std::thread::spawn(move || post.send(Event::Listed { entries: list(&root, &path), path })); + } + Job::SharedWithMe => { + std::thread::spawn(move || post.send(Event::Shared(Ok(Vec::new())))); + } + Job::Read { entry, into } => { + std::thread::spawn(move || { + let bytes = read(&root, &entry); + post.send(Event::Read { entry, into, bytes }); + }); + } + Job::Write { uid, entry, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: write(&root, &entry, &bytes) })); + } + Job::Create { uid, folder, name, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: create(&root, &folder, &name, &bytes) })); + } + // No sharing, no accounts beyond this one, and so nowhere for a + // conversation to live. A reference backend that invented one + // would be lying about what a folder on disk can do. + Job::Conversation(_) => { + std::thread::spawn(move || { + post.send(Event::Conversation(Err(Fault::Refused("this reference backend has no shared workspace to converse in".to_owned())))) + }); + } + } + } +} + +fn account(display: String) -> Account { + Account { display, capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +/// Turns a [`Job`]'s slash-separated path into a real filesystem path under +/// `root`, refusing anything that would walk back out of it. +/// +/// `..` is the only way out, so `..` is the only segment refused. `.` and +/// repeated or leading slashes are just an empty segment and are skipped, +/// the same way a browser's address bar collapses them. +fn resolve(root: &Path, path: &str) -> Result { + let mut real = root.to_path_buf(); + for segment in path.split('/') { + if segment.is_empty() || segment == "." { + continue; + } + if segment == ".." { + return Err(Fault::Refused(format!("{path} reaches outside this folder"))); + } + real.push(segment); + } + Ok(real) +} + +/// The path a listed child gets, given the folder it was found in. +fn child_path(folder: &str, name: &str) -> String { + format!("{}/{name}", folder.trim_end_matches('/')) +} + +/// An opaque version token for a file's current bytes. +/// +/// Not a timestamp for a person to read (that would go through `chrono`, per +/// this workspace's rule); just enough to tell "the file I read" from "the +/// file as it is now" apart, which is all a conditional write needs. +fn etag_of(meta: &fs::Metadata) -> String { + let stamp = meta.modified().ok().and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0); + format!("{}-{stamp}", meta.len()) +} + +fn io_fault(error: &std::io::Error) -> Fault { + use std::io::ErrorKind; + match error.kind() { + ErrorKind::NotFound => Fault::Refused("no such file or folder".to_owned()), + ErrorKind::PermissionDenied => Fault::Refused("permission denied".to_owned()), + _ => Fault::Unreachable(error.to_string()), + } +} + +fn list(root: &Path, path: &str) -> Result, Fault> { + let dir = resolve(root, path)?; + let read = fs::read_dir(&dir).map_err(|error| io_fault(&error))?; + let mut entries = Vec::new(); + for item in read { + let item = item.map_err(|error| io_fault(&error))?; + let meta = item.metadata().map_err(|error| io_fault(&error))?; + let name = item.file_name().to_string_lossy().into_owned(); + let id = child_path(path, &name); + entries.push(Entry { + room: format!("local:{id}"), + name, + kind: if meta.is_dir() { EntryKind::Folder } else { EntryKind::File }, + size: if meta.is_dir() { None } else { Some(meta.len()) }, + modified: None, + mime: None, + etag: if meta.is_dir() { None } else { Some(etag_of(&meta)) }, + writable: true, + shared_by: None, + path: id.clone(), + id, + }); + } + entries.sort_by(|a, b| (a.kind != EntryKind::Folder, &a.name).cmp(&(b.kind != EntryKind::Folder, &b.name))); + Ok(entries) +} + +fn read(root: &Path, entry: &Entry) -> Result, Fault> { + let file = resolve(root, &entry.id)?; + fs::read(&file).map_err(|error| io_fault(&error)) +} + +/// Saves back over `entry`, refusing the write when the file moved on since +/// `entry.etag` was read. A file that no longer exists has nothing to +/// conflict with, the same way a provider treats a deleted document. +fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { + let file = resolve(root, &entry.id)?; + if let Ok(meta) = fs::metadata(&file) { + if Some(etag_of(&meta)) != entry.etag { + return Err(Fault::Conflict); + } + } + if let Some(parent) = file.parent() { + fs::create_dir_all(parent).map_err(|error| io_fault(&error))?; + } + fs::write(&file, bytes).map_err(|error| io_fault(&error))?; + let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; + Ok(Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }) +} + +fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result { + let dir = resolve(root, folder)?; + fs::create_dir_all(&dir).map_err(|error| io_fault(&error))?; + let file = dir.join(name); + if file.exists() { + return Err(Fault::Refused(format!("{name} already exists"))); + } + fs::write(&file, bytes).map_err(|error| io_fault(&error))?; + let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; + let id = child_path(folder, name); + Ok(Entry { + room: format!("local:{id}"), + name: name.to_owned(), + kind: EntryKind::File, + size: Some(meta.len()), + modified: None, + mime: None, + etag: Some(etag_of(&meta)), + writable: true, + shared_by: None, + path: id.clone(), + id, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_parent_segment_cannot_walk_out_of_root() { + let root = PathBuf::from("/cloud/root"); + assert!(resolve(&root, "../secrets").is_err()); + assert!(resolve(&root, "Archive/../../../etc/passwd").is_err()); + } + + #[test] + fn repeated_and_trailing_slashes_collapse_like_a_browser_address_bar() { + let root = PathBuf::from("/cloud/root"); + assert_eq!(resolve(&root, "//Archive//2026/").unwrap(), root.join("Archive").join("2026")); + assert_eq!(resolve(&root, "").unwrap(), root); + } + + #[test] + fn a_folder_announces_no_capability_this_backend_cannot_honour() { + let reported = account("Local disk".to_owned()).capabilities; + for absent in [Capability::SharedWithMe, Capability::Sharing, Capability::Conversation, Capability::Contacts] { + assert!(!reported.contains(&absent), "a folder has no {absent:?}"); + } + } +} diff --git a/crates/cloud-local/tests/backend.rs b/crates/cloud-local/tests/backend.rs new file mode 100644 index 000000000..4176672f1 --- /dev/null +++ b/crates/cloud-local/tests/backend.rs @@ -0,0 +1,241 @@ +//! Drives [`craft_cloud_local::LocalBackend`] the way an app does: through +//! `craft_ui::cloud`'s own public functions, never by calling the backend +//! directly. That is the seam this crate exists to prove, so the tests stay +//! on the application's side of it. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, Account, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// The least a [`CloudApp`] can be. What it was told to open is recorded, so a +/// round trip can be checked by content and not only by the entry metadata +/// `craft_ui` itself remembers. +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: Arc)>>>, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTE + } + + fn active(&self) -> Option { + None + } + + fn title(&self, _uid: u64) -> String { + String::new() + } + + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + + fn close(&mut self, _uid: u64) {} + + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, _url: &str) {} + + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: std::path::PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until +/// `done` says the state the test is waiting for arrived or five seconds pass. +/// Five seconds is far more than a thread doing local file IO ever needs; it +/// only guards against a real bug leaving the test to hang forever. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +#[test] +fn account_and_sign_in_report_the_same_fixed_identity_with_no_browser_round_trip() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::start(&mut app); + settle(&mut app, &ctx, |app| app.cloud().account.is_some()); + + assert_eq!( + app.cloud().account, + Some(Account { + display: "Local disk".to_owned(), + capabilities: vec![craft_cloud::Capability::Files, craft_cloud::Capability::Etags], + provider_linked: true + }) + ); + // There was never an account to link, so nothing was ever offered. + assert!(app.cloud().link.is_none()); +} + +#[test] +fn creating_a_document_writes_real_bytes_a_read_gets_back() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"first draft".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + + let entry = app.cloud().origins.get(&1).unwrap().entry.clone(); + assert_eq!(entry.name, "Minutes.txt"); + assert_eq!(entry.id, "/Minutes.txt"); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"first draft"); + + cloud::submit(&app, Job::Read { entry, into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + + let opened = app.opened.lock().unwrap().clone(); + assert_eq!(opened, vec![("Minutes.txt".to_owned(), b"first draft".to_vec())], "the read got back exactly what the create wrote"); +} + +#[test] +fn a_write_under_a_stale_version_is_refused_and_never_overwrites_the_newer_file() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"v1".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + let stale = app.cloud().origins.get(&1).unwrap().entry.clone(); + + // Somebody else saves first, changing the file's etag without going + // through this window at all. + std::fs::write(dir.path().join("Minutes.txt"), b"somebody else's edit").unwrap(); + + cloud::submit(&app, Job::Write { uid: 1, entry: stale, bytes: b"this window's edit".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().conflict.is_some()); + + assert_eq!(app.cloud().conflict.as_ref().unwrap().uid, 1); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"somebody else's edit", "the refused write never touched the file"); +} + +#[test] +fn listing_the_root_reflects_a_file_nobody_went_through_this_backend_to_write() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write(dir.path().join("Agenda.txt"), b"1. roll call").unwrap(); + std::fs::create_dir(dir.path().join("Archive")).unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::browse(&mut app, ""); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + let names: Vec<_> = app.cloud().mine.entries.iter().map(|entry| entry.name.clone()).collect(); + assert_eq!(names, vec!["Archive".to_owned(), "Agenda.txt".to_owned()], "folders first, then files, each alphabetised"); + let folder = app.cloud().mine.entries.iter().find(|entry| entry.name == "Archive").unwrap(); + assert_eq!(folder.kind, EntryKind::Folder); + assert!(folder.size.is_none()); +} + +#[test] +fn nobody_has_shared_anything_with_a_folder() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::load_shared(&mut app); + settle(&mut app, &ctx, |app| app.cloud().shared.loaded); + + assert_eq!(app.cloud().shared.entries, Vec::new()); + assert!(app.cloud().shared.error.is_none(), "an empty share list is not a failure"); +} + +#[test] +fn a_conversation_is_a_fault_this_backend_is_honest_about() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Conversation("/Minutes.txt".to_owned())); + settle(&mut app, &ctx, |app| app.cloud().status.is_some()); + + assert_eq!(app.cloud().status, Some("this reference backend has no shared workspace to converse in".to_owned())); +} + +#[test] +fn a_read_of_a_document_that_is_not_there_is_put_to_the_user_not_silently_dropped() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + let ghost = Entry { + id: "/ghost.txt".to_owned(), + room: "local:/ghost.txt".to_owned(), + name: "ghost.txt".to_owned(), + path: "/ghost.txt".to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + }; + cloud::submit(&app, Job::Read { entry: ghost, into: None }); + settle(&mut app, &ctx, |app| !app.said.lock().unwrap().is_empty()); + + assert!(app.said.lock().unwrap()[0].contains("ghost.txt"), "the message names the document, not just that something failed"); +} + +fn fs_read(root: &std::path::Path, name: &str) -> Vec { + std::fs::read(root.join(name)).unwrap() +} diff --git a/crates/cloud/Cargo.toml b/crates/cloud/Cargo.toml new file mode 100644 index 000000000..055feff39 --- /dev/null +++ b/crates/cloud/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-cloud" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "What a cloud provider offers the Craft apps: files, sharing, contacts, notifications and mail as contracts, with no vendor and no IO" + +[lints] +workspace = true + +[dependencies] +serde = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/cloud/src/error.rs b/crates/cloud/src/error.rs new file mode 100644 index 000000000..ede71ac0c --- /dev/null +++ b/crates/cloud/src/error.rs @@ -0,0 +1,68 @@ +//! One error type for every contract. +//! +//! The cases are the ones a caller acts on differently. A UI shows a different +//! thing for "you may not" than for "the server is unreachable", and a save +//! retries on a conflict where it would not on a refusal. + +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum Error { + /// The provider could not be reached. Worth retrying. + #[error("the provider could not be reached: {0}")] + Unreachable(String), + + /// The credential was rejected. The user has to sign in again. + #[error("the provider rejected the credential")] + Unauthenticated, + + /// Authenticated, and not allowed to do this. Signing in again will not + /// help, so a UI must not offer it. + #[error("not permitted: {0}")] + Forbidden(String), + + /// No such document, folder or share. + #[error("{what} not found: {id}")] + NotFound { what: &'static str, id: String }, + + /// The document changed since the caller last read it. A save that would + /// have overwritten somebody else's work lands here. + #[error("{0} changed since you opened it")] + Conflict(String), + + /// The provider does not offer this at all. + /// + /// Distinct from [`Error::Forbidden`]: there is nothing to grant. A UI + /// hides the feature rather than explaining it. + #[error("this provider does not support {0}")] + Unsupported(&'static str), + + /// The answer did not match the protocol. + #[error("malformed {what}: {detail}")] + Malformed { what: &'static str, detail: String }, + + /// A name or path could not be used safely. Carried, never panicked. + #[error("invalid {what}: {detail}")] + Invalid { what: &'static str, detail: String }, +} + +impl Error { + pub fn not_found(what: &'static str, id: impl Into) -> Error { + Error::NotFound { what, id: id.into() } + } + + pub fn malformed(what: &'static str, detail: impl Into) -> Error { + Error::Malformed { what, detail: detail.into() } + } + + pub fn invalid(what: &'static str, detail: impl Into) -> Error { + Error::Invalid { what, detail: detail.into() } + } + + /// Whether trying again could succeed without the user doing anything. + pub fn is_transient(&self) -> bool { + matches!(self, Error::Unreachable(_)) + } +} + +pub type Result = std::result::Result; diff --git a/crates/cloud/src/lib.rs b/crates/cloud/src/lib.rs new file mode 100644 index 000000000..7f02dd468 --- /dev/null +++ b/crates/cloud/src/lib.rs @@ -0,0 +1,189 @@ +//! What a cloud provider has to offer the Craft apps, and nothing about who +//! provides it. +//! +//! Every capability here is an RFC or an ordinary HTTP API that many systems +//! implement. Files are WebDAV. Contacts are CardDAV. Calendars are CalDAV. +//! Sharing and notification are the only genuinely vendor-shaped parts, and +//! they are small. So there is no reason for an app to know which server it is +//! talking to, and no reason to write the same logic again for the next one. +//! +//! Nothing in this crate opens a socket. Each trait is implemented by a +//! provider crate that brings its own transport, which keeps this testable +//! with no server and keeps the contracts honest about what they need. +//! +//! No type here names a vendor. If a field only makes sense for one product, +//! it belongs in that provider's crate. +//! +//! Nothing here says where an implementation runs. A local adapter may +//! implement these traits against a provider directly, and an application may +//! consume them that way. The contracts do not care. +//! +//! CollabCraft chooses otherwise for its own apps. They reach one service, and +//! that service is the single place a provider is configured, a credential is +//! held and a permission is decided. A desktop binary carrying a provider +//! credential leaks one the moment somebody copies the file, which is what +//! that arrangement exists to prevent. It is a deployment policy, and this +//! crate imposes it on nobody. + +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +mod error; +mod types; + +pub use error::{Error, Result}; +pub use types::{ + Capability, Contact, Conversation, Entry, EntryKind, Identity, MailMessage, Notification, Permission, Share, ShareOptions, ShareTarget, +}; + +/// Reading and writing documents. +/// +/// `list` and `shared_with_me` are separate because they answer different +/// questions. One is a folder's contents, the other is everything another +/// person has given this user access to, which has no single parent folder. +pub trait Files { + /// One folder's contents. An empty path means the user's root. + fn list(&self, path: &str) -> Result>; + + /// Everything shared with this user, wherever it lives. + /// + /// A provider with no concept of this returns an empty list rather than an + /// error, because "nobody has shared anything with you" and "this server + /// cannot tell you" look the same to a file picker. + fn shared_with_me(&self) -> Result>; + + /// One document's bytes. + fn read(&self, id: &str) -> Result>; + + /// A byte range of one document. + /// + /// Defaulted to a full [`read`] and a slice, so providers that have no + /// ranged GET still satisfy the trait. A provider with real range support + /// overrides this. + fn read_range(&self, id: &str, offset: u64, length: u64) -> Result> { + let bytes = self.read(id)?; + let start = usize::try_from(offset).unwrap_or(usize::MAX); + if start >= bytes.len() { + return Ok(Vec::new()); + } + let take = usize::try_from(length).unwrap_or(usize::MAX); + let end = start.saturating_add(take).min(bytes.len()); + Ok(bytes[start..end].to_vec()) + } + + /// Replace one document's bytes. + /// + /// `if_match` carries the etag the caller last saw. A provider that + /// supports conditional writes uses it to refuse a save that would + /// overwrite somebody else's, returning [`Error::Conflict`]. Passing + /// `None` means "write regardless", which is what a Save As does. + fn write(&self, id: &str, bytes: &[u8], if_match: Option<&str>) -> Result; + + /// Create a document and return it. + fn create(&self, folder: &str, name: &str, bytes: &[u8]) -> Result; + + /// One document's metadata, without its bytes. + fn stat(&self, id: &str) -> Result; +} + +/// Giving other people access to a document. +/// +/// Persisting a share through the provider matters more than it looks. A share +/// recorded only by the caller would be invisible in the provider's own file +/// manager, so the two would disagree about who can open what. The provider +/// stays the authority. +pub trait Sharing { + /// Share a document. + /// + /// A link share has no recipient, so [`ShareTarget::Link`] is how a caller + /// asks for one. The returned [`Share::url`] is what to hand out. + fn share(&self, id: &str, with: &ShareTarget, permission: Permission, options: &ShareOptions) -> Result; + + /// Who currently has access. + fn shares(&self, id: &str) -> Result>; + + /// Withdraw one share. + fn unshare(&self, share_id: &str) -> Result<()>; +} + +/// Looking people up, for a share dialog's autocomplete. +/// +/// This is the only thing the share dialog needs, so it is the only thing the +/// contract exposes. A full address book API would be a bigger surface for no +/// gain. +pub trait Contacts { + /// People matching a partial name or address. + /// + /// `limit` exists because this runs on every keystroke. A provider is free + /// to return fewer. + fn search(&self, query: &str, limit: usize) -> Result>; +} + +/// Telling somebody something happened. +/// +/// Separate from [`Mail`] on purpose. An in-app notification is cheap, arrives +/// instantly and is read in context. An email is none of those and is the +/// right choice for somebody who is not currently in the app. A share usually +/// wants both. +pub trait Notifications { + fn notify(&self, user: &str, notification: &Notification) -> Result<()>; +} + +/// Sending mail as the provider. +pub trait Mail { + fn send(&self, message: &MailMessage) -> Result<()>; +} + +/// Who the caller is, according to the provider. +pub trait Accounts { + /// Resolve the signed-in user. + fn me(&self) -> Result; +} + +/// Working together on a document, through whatever the provider calls it. +/// +/// Defaulted throughout. A provider without the feature writes an empty +/// `impl` and reports [`Capability::Conversation`] as absent. The caller +/// then draws no control at all. +pub trait Conversations { + /// What this provider calls the feature. `None` where it has none. + /// + /// Separate from the capability on purpose. The name is a property of + /// the provider. Whether it is available is a property of the + /// instance, and an administrator decides that one. + fn conversation_name(&self) -> Option { + None + } + + /// Start a conversation about a document, or join the one already there. + /// + /// Two people pressing the same control have to arrive in the same + /// place, so this is expected to be idempotent for a given document. + /// + /// `id` is the provider's own handle and means nothing outside the + /// account it came from. A conversation is therefore keyed on the + /// provider, the account and the document together, and `self` carries + /// the first two. A document copied into another account is a different + /// document to its provider, so it gets a conversation of its own. + /// Nothing here can attach one account's thread to another's. + fn conversation(&self, _id: &str, _title: &str) -> Result { + Err(Error::Unsupported("conversations")) + } +} + +/// Everything one provider can do. +/// +/// A provider implements the capabilities it has and reports the rest as +/// absent, so a caller can hide a share button on a server with no sharing +/// rather than offering a feature that will fail. +pub trait Provider: Files + Sharing + Contacts + Notifications + Mail + Accounts + Conversations { + /// A stable identifier, such as `nextcloud`. Used in configuration and + /// logs, never shown to a user. + fn id(&self) -> &str; + + /// What this provider actually supports. + fn capabilities(&self) -> Vec; + + fn supports(&self, capability: Capability) -> bool { + self.capabilities().contains(&capability) + } +} diff --git a/crates/cloud/src/types.rs b/crates/cloud/src/types.rs new file mode 100644 index 000000000..ab8c005a1 --- /dev/null +++ b/crates/cloud/src/types.rs @@ -0,0 +1,216 @@ +//! The data the contracts pass around. +//! +//! Every type here is plain and vendor-neutral. A field that only means +//! something to one product belongs in that provider's crate. + +use serde::{Deserialize, Serialize}; + +/// What a provider can do. +/// +/// Reported rather than assumed, so a caller hides a share button on a +/// server without sharing instead of offering a feature that fails on use. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Capability { + Files, + SharedWithMe, + Sharing, + Contacts, + Notifications, + Mail, + /// Conditional writes, so a save can refuse to clobber a newer version. + Etags, + /// Public links. Absent on a server that forbids them, and the dialog then + /// offers no Copy link rather than a button that fails. + LinkShares, + /// A key on a public link. This is what most places mean when they talk + /// about sharing with somebody who has no account. + LinkPassword, + /// The server requires that key, so a link cannot be made without one. + LinkPasswordRequired, + /// An expiry date on a share. + ShareExpiry, + /// The provider can tell a recipient that something was shared with them. + /// + /// Distinct from [`Capability::Mail`], which is about sending arbitrary + /// mail. A provider commonly has this and not that: it will notify the + /// person a share names without offering any way to send mail in general. + ShareNotify, + /// A conversation about a document, such as a call or a chat room. + /// + /// Every provider that has this calls it something else, so the name + /// comes from [`crate::Conversations::conversation_name`]. Reported + /// separately from that name: a provider knows what it would call the + /// feature whether or not an administrator installed it. + Conversation, +} + +/// A file or folder. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Entry { + /// An opaque handle for reading, writing and sharing this entry. + /// + /// Only the provider that issued it may interpret it. A caller passes it + /// back and never parses it. + pub id: String, + /// The stable identity used for a collaboration room. + /// + /// Separate from `id` on purpose. A provider's read and write handle is + /// often a path, and a path changes when somebody renames or moves the + /// file. A room keyed on that would silently split in two mid-session, + /// with each half seeing only its own edits. This one survives a rename. + pub room: String, + /// What to show the user. + pub name: String, + /// Where it sits, for a breadcrumb. Never a handle. + pub path: String, + pub kind: EntryKind, + /// Bytes, absent for a folder. + pub size: Option, + /// RFC 3339. Absent when the provider does not say. + pub modified: Option, + /// For matching a document to the app that opens it. + pub mime: Option, + /// The version the caller last saw, for a conditional write. + pub etag: Option, + /// Whether this user may change it. A read-only share still lists. + pub writable: bool, + /// Who shared it, when it came from somebody else. + pub shared_by: Option, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EntryKind { + File, + Folder, +} + +/// A person, as a share dialog needs them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Contact { + /// What the provider wants back when sharing with this person. + pub id: String, + /// How to share with them, decided by the provider and never guessed. + /// + /// The distinction is not cosmetic. A contact with an account is a user + /// share. One known only by address is an email share. Sharing an address + /// as though it were a user id fails with "not found", because no such + /// user exists, and nothing in `id` alone says which case this is. + pub target: ShareTarget, + /// What to show. A display name where there is one. + pub name: String, + pub email: Option, + /// An avatar, as a URL the client may fetch. Never image bytes: a search + /// returning ten people would otherwise carry ten pictures nobody asked + /// for yet. + pub avatar: Option, + /// A group rather than a person. Shown differently and shared differently. + pub is_group: bool, +} + +/// Who to share with. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case", tag = "kind", content = "id")] +pub enum ShareTarget { + User(String), + Group(String), + /// Somebody with no account, reached by address. + Email(String), + /// Anybody holding the link. + Link, +} + +/// What a share allows. +/// +/// Deliberately coarse. Providers disagree on the fine detail, and a dialog +/// offering a distinction the server cannot keep is worse than one that does +/// not. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Permission { + /// Open and read. No edits reach the document. + View, + /// Open and edit. + Edit, +} + +/// Everything optional about a share. +/// +/// A struct rather than more positional arguments. The list grew past the +/// point where a call site reads correctly, and a provider that cannot honour +/// one of these needs to see which it was given. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct ShareOptions { + /// Shown to the recipient. + pub note: Option, + /// Send mail where the provider can. + pub notify: bool, + /// A key the recipient must present. Only meaningful for a link, and + /// refused by a server that does not allow one. + pub password: Option, + /// `YYYY-MM-DD`. After this the share stops working. + pub expires: Option, +} + +/// Where to go to work together on a document. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Conversation { + /// Where to join. Handed to a browser, or to the provider's own app. + pub url: String, + /// What the provider calls the feature, for the control's wording. A + /// menu item reading "Work together in Talk" is built from this. + pub name: String, +} + +/// A share that exists. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Share { + pub id: String, + pub target: ShareTarget, + /// What to call the recipient, where the provider says. + /// + /// A share carries the handle the server wants back, which for a user is + /// an account id. People are not known to each other by account id. A + /// provider that knows the difference says so here. + pub display: Option, + pub permission: Permission, + /// Present for a link share, absent otherwise. + pub url: Option, + pub note: Option, + /// RFC 3339. + pub created: Option, +} + +/// Something worth telling a user about, in the app. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Notification { + /// A short machine-readable kind, such as `document_shared`. Lets a client + /// decide how to render without parsing prose. + pub kind: String, + pub subject: String, + pub body: Option, + /// Where to go when it is clicked. + pub link: Option, +} + +/// An email to send. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct MailMessage { + pub to: Vec, + pub subject: String, + pub body: String, + /// Whether `body` is HTML. Plain text otherwise. + pub html: bool, +} + +/// The signed-in user, as the provider sees them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Identity { + /// The provider's identifier for this account. + pub id: String, + /// What to show. Never an identity: two people can share a display name. + pub display: String, + pub email: Option, + pub avatar: Option, +} diff --git a/crates/ui/Cargo.toml b/crates/ui/Cargo.toml index 29d7f29f2..ac5085cd9 100644 --- a/crates/ui/Cargo.toml +++ b/crates/ui/Cargo.toml @@ -19,6 +19,12 @@ log = "0.4" serde = { version = "1", features = ["derive"], optional = true } # Same version as epaint's, for reading a face's character map. skrifa = { version = "0.44", default-features = false, features = ["std"] } +# The vendor-neutral vocabulary the share dialog speaks. No IO and no +# vendor, so this stays buildable for the web. +craft-cloud = { workspace = true, optional = true } +# The control channel's report of the cloud state. One serialiser here +# rather than one per application. No IO and no vendor. +serde_json = { workspace = true, optional = true } [target.'cfg(not(target_arch = "wasm32"))'.dependencies] # Screenshot and input tests of an app's screens (the screen-testing feature). @@ -54,6 +60,11 @@ testing = [] # craft_ui::testing: per-language screenshot tests, IME smoke tests, input steps and review # screenshots with egui_kittest (desktop only). screen-testing = ["dep:egui_kittest"] +# The share dialog and the backend contract it states its work through. +share = ["dep:craft-cloud"] +# Open and Save against cloud storage. Needs the share dialog, which a +# document's overflow menu and the Share split button both open. +cloud = ["share", "dep:serde_json"] [dev-dependencies] # serde: the IME tests read events that only the suite's egui fork has from JSON. diff --git a/crates/ui/README.md b/crates/ui/README.md index a48e49476..1ad05ad54 100644 --- a/crates/ui/README.md +++ b/crates/ui/README.md @@ -705,6 +705,66 @@ verify the actual pixels as well as callback routing. `text::align_galley_rows` positions already shaped rows inside a fixed-width reading area without changing glyphs or logical text. Supply a per-row alignment, for example the paragraph direction from the application shaper. The helper uses stock egui APIs and keeps cached glyph meshes shared. Its logical rectangle is the requested width; ink may overflow, so clip the painter when drawing cards. Use it for read-only painting, keeping the original galley for editable hit testing. +## Sharing + +`share::ShareDialog` is a whole dialog. It holds a recipient picker with autocomplete and +removable chips. It offers a view-or-edit choice, a note and a notify-by-email box. Under those it +lists who already has access, with a withdrawal beside each entry. Every Craft app gets the same +dialog. An application's own part comes to three lines. + +```rust +// Once, at startup. The host supplies the half that reaches the service. +app.share.connect(my_backend); + +// Every frame, open or shut. This is also where answers are collected. +app.share.show(ctx); + +// From the app's Share control, drawn only while `available()` is true. +if app.share.available() && share_button.clicked() { + app.share.open(entry.id.clone(), entry.name.clone()); +} +``` + +The dialog opens no socket, names no provider and holds no credential. It states each piece of +work as a `share::Request` and hands it to a `share::ShareBackend`. That backend answers through a +`share::Replier` whenever it is ready. Nothing in this crate implements that trait. A host writes +the half that opens a socket, and this crate never learns what it reaches. The interface half +therefore builds for the web, and every flow is testable with no server running. + +Autocomplete waits `share::DEBOUNCE` after the last keystroke before it asks anything. An answer +to a query the user has already typed past is dropped before it reaches the list. A list that +flickers back to stale matches is worse than one that arrives late. + +Partial success is rendered as partial success. A share aimed at five people with one wrong +address reaches four. The dialog names the fifth with the reason the service gave. It keeps that +one recipient in the picker. A correction then takes one edit. `outcome()` hands back both halves. + +Capability is reported and never assumed. `available()` stays false until the service says the +provider supports sharing and an account is linked. `open` does nothing while it is false. An +application draws no Share control in that state. A hidden feature beats a button that fails on +use. Contacts and mail are reported separately. A server with no address book accepts typed +addresses only. A server that cannot send mail disables the notify box and says why. +`ShareLabels` holds every string the dialog shows. The defaults are English. A localized +application replaces them without touching this crate. + +A contact's `avatar` is a URL. The dialog asks for the bytes through the same backend, as the row +that needs the picture is painted and only while that row is on screen. A search answering with +ten people costs no pictures until somebody looks at them. Each URL is asked about once. A refusal +is remembered, with initials painted in its place. The host decides whether a picture may be +fetched at all. A backend that refuses `share::Request::Avatar` gets initials painted instead, and +a host that would rather not have an application reach a provider's avatar URL directly can say +so by refusing it. A host that relays pictures answers it. Nothing else changes. + +### The account + +`account::AccountMenu` is the badge every suite puts in the top right. It shows who is signed in, +where they are signed in, and whether storage is linked. It holds no credential. It asks the +service who the caller is, through the application. It reports what the user asked for through +`take_action`. The application owns what signing in means. + +Without linked storage, Open and Save have nowhere to go. The menu says so at rest. A failure at +the moment of saving arrives too late to be useful. + ## Compatibility and checks The crate uses egui 0.37 and Rust 1.95 or later. Its production dependency disables egui's default diff --git a/crates/ui/src/account.rs b/crates/ui/src/account.rs new file mode 100644 index 000000000..d83214500 --- /dev/null +++ b/crates/ui/src/account.rs @@ -0,0 +1,449 @@ +//! Who is signed in, which account is in use, and how to stop being signed in. +//! +//! Every office suite puts this in the same place, for the same reason. A +//! document is about to be saved somewhere and shared with somebody. The +//! account decides both the destination and the identity. An application that +//! never shows it leaves the user guessing which of their identities is in +//! play. +//! +//! A person commonly holds more than one. A work account and a personal one +//! are two different places to save, with two different sets of colleagues to +//! share with, and confusing them is the expensive mistake this control exists +//! to prevent. So the control holds a list and marks which one is in use. +//! +//! This holds no credential. It asks the service who the caller is and shows +//! the answer. A sign-out makes the service forget the session. + +use std::sync::mpsc::{Receiver, Sender, channel}; + +use egui::{Align, Context, Layout, RichText, Ui}; + +/// One account the user is signed in to. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + /// How the service names this account. Never shown. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + pub email: Option, + /// Where they are signed in, such as the service's host. Shown because + /// somebody with accounts on two deployments needs to tell them apart. + pub service: String, + /// Whether storage is linked. Without it Open and Save have nowhere to go, + /// and saying so here is kinder than a failure at the moment of saving. + pub linked: bool, +} + +impl Account { + pub fn new(id: impl Into, display: impl Into) -> Account { + Account { id: id.into(), display: display.into(), ..Account::default() } + } + + /// The letter on the badge. The first character of the display name, which + /// is what every suite uses and what people recognise at that size. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } +} + +/// What the menu asks the application to do. +/// +/// Each one names the account it is about. A control that said only "sign out" +/// would be ambiguous the moment somebody held two. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum AccountAction { + /// Begin a sign-in with nobody signed in yet. + SignIn, + /// Add another account alongside the ones already here. + AddAccount, + /// Work as this account from now on. + Use(String), + /// End this account's session, at the service and here. + SignOut(String), + /// Connect storage for an account that has none. + Link(String), + /// Open the service's own page for this account. + Manage(String), +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct AccountLabels { + pub signed_out: String, + pub sign_in: String, + pub sign_out: String, + pub add_account: String, + pub other_accounts: String, + pub link: String, + pub linked: String, + pub not_linked: String, + pub manage: String, + pub working: String, + /// The badge's accessible name. `{name}` is replaced. + /// + /// A button announcing only a person's name says nothing about what + /// pressing it does, and collides with every other place that name is + /// written. + pub badge: String, + /// Shown when accounts are signed in and none is in use. + pub choose: String, + /// Why that happened, since a person who did not sign out needs telling. + pub choose_why: String, +} + +impl Default for AccountLabels { + fn default() -> AccountLabels { + AccountLabels { + signed_out: "Not signed in".into(), + sign_in: "Sign in".into(), + sign_out: "Sign out".into(), + add_account: "Add an account".into(), + other_accounts: "Other accounts".into(), + link: "Connect storage".into(), + linked: "Storage connected".into(), + not_linked: "No storage connected".into(), + manage: "Account settings".into(), + working: "Working\u{2026}".into(), + badge: "Account, {name}".into(), + choose: "Choose an account".into(), + choose_why: "The account you were using is no longer signed in.".into(), + } + } +} + +/// The account badge and its menu. +pub struct AccountMenu { + accounts: Vec, + /// Which account the application is working as. Held by id rather than by + /// index, since the list is replaced wholesale whenever the service answers. + active: Option, + labels: AccountLabels, + /// Set while a sign-in or sign-out is in flight, so the control says so + /// rather than looking unresponsive. + busy: bool, + /// Whether the host can hold more than one account at once. + /// + /// Off until a host says otherwise. An application that keeps one + /// session would otherwise draw an Add an account that signs the user + /// in again as the account they are already using, which reads as a + /// button that does nothing. + more_allowed: bool, + actions: (Sender, Receiver), +} + +impl Default for AccountMenu { + fn default() -> AccountMenu { + AccountMenu::new() + } +} + +impl AccountMenu { + pub fn new() -> AccountMenu { + AccountMenu { accounts: Vec::new(), active: None, labels: AccountLabels::default(), busy: false, more_allowed: false, actions: channel() } + } + + pub fn with_labels(mut self, labels: AccountLabels) -> AccountMenu { + self.labels = labels; + self + } + + /// Say that this host can hold more than one account at once. + /// + /// Until a host says so, the menu offers no way to add one. Signing in + /// again as the account already in use is not an action worth drawing. + pub fn allowing_more(mut self) -> AccountMenu { + self.more_allowed = true; + self + } + + /// Replace the whole set of accounts. + /// + /// Wholesale rather than one at a time. A session that missed a sign-out + /// elsewhere would otherwise keep offering an account that is gone. + /// + /// The account in use is kept when it is still in the list. + /// + /// When it has gone, nothing takes its place. A work session that expires + /// would otherwise hand the next save, share and open to a personal + /// account without saying so, and sending a document to the wrong tenant + /// is not a mistake a person can take back. The control asks instead. + /// + /// The first account is chosen only when none was in use at all, which is + /// the first sign-in. + pub fn set(&mut self, accounts: Vec) { + let chose_before = self.active.is_some(); + let kept = self.active.take().filter(|id| accounts.iter().any(|a| a.id == *id)); + self.active = match kept { + Some(id) => Some(id), + None if chose_before => None, + None => accounts.first().map(|a| a.id.clone()), + }; + self.accounts = accounts; + self.busy = false; + } + + /// Work as this account. Ignored for an account that is not here. + pub fn set_active(&mut self, id: &str) { + if self.accounts.iter().any(|a| a.id == id) { + self.active = Some(id.to_owned()); + } + } + + pub fn active(&self) -> Option<&Account> { + let id = self.active.as_deref()?; + self.accounts.iter().find(|a| a.id == id) + } + + pub fn accounts(&self) -> &[Account] { + &self.accounts + } + + pub fn is_signed_in(&self) -> bool { + !self.accounts.is_empty() + } + + /// Mark something as in flight. Cleared by the next [`AccountMenu::set`]. + pub fn working(&mut self) { + self.busy = true; + } + + /// What the user asked for since the last call, if anything. + /// + /// Drained rather than handed a callback, so the application acts on its + /// own thread and this stays free of any notion of what signing in means. + pub fn take_action(&mut self) -> Option { + self.actions.1.try_recv().ok() + } + + /// Draw the badge. Put it where the window's own controls are. + pub fn show(&mut self, ui: &mut Ui) { + let tx = self.actions.0.clone(); + let labels = self.labels.clone(); + let busy = self.busy; + + let Some(account) = self.active().cloned() else { + // Nobody signed in, or signed in with the account that was in use + // now gone. The two read differently. One offers a sign-in. The + // other has accounts to offer and must say so, since saving has + // nowhere to go until somebody picks one. + if self.accounts.is_empty() { + let label = if busy { labels.working.as_str() } else { labels.sign_in.as_str() }; + if ui.add_enabled(!busy, egui::Button::new(label).small()).clicked() { + let _ = tx.send(AccountAction::SignIn); + } + return; + } + let waiting = self.accounts.clone(); + let hit = ui.add_enabled(!busy, egui::Button::new(labels.choose.as_str()).small()); + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(240.0); + ui.label(RichText::new(labels.choose_why.as_str()).small().color(ui.visuals().warn_fg_color)); + ui.separator(); + for one in &waiting { + let label = format!("{}\n{}", one.display, one.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = one.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(one.id.clone())); + ui.close(); + } + } + ui.add_space(4.0); + if ui.button(labels.sign_in.as_str()).clicked() { + let _ = tx.send(AccountAction::SignIn); + ui.close(); + } + }); + return; + }; + + let others: Vec = self.accounts.iter().filter(|a| a.id != account.id).cloned().collect(); + let more_allowed = self.more_allowed; + let badge = egui::Button::new(RichText::new(account.initial()).strong()).min_size(egui::vec2(26.0, 26.0)).corner_radius(13.0); + let hit = ui.add(badge); + let spoken = labels.badge.replace("{name}", &account.display); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, spoken.as_str())); + let hit = hit.on_hover_text(account.display.as_str()); + + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(260.0); + // The deployment first, because somebody with an account on two of + // them needs to know which one this is before reading anything + // else. + ui.horizontal(|ui| { + ui.label(RichText::new(account.service.as_str()).small().color(ui.visuals().weak_text_color())); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + if ui.small_button(labels.sign_out.as_str()).clicked() { + let _ = tx.send(AccountAction::SignOut(account.id.clone())); + ui.close(); + } + }); + }); + ui.separator(); + + ui.horizontal(|ui| { + ui.label(RichText::new(account.initial()).size(26.0).strong()); + ui.vertical(|ui| { + ui.label(RichText::new(account.display.as_str()).strong().size(15.0)); + if let Some(email) = &account.email { + ui.label(RichText::new(email.as_str()).small().color(ui.visuals().weak_text_color())); + } + }); + }); + + ui.add_space(6.0); + + // Storage, which is the thing that actually stops working when it + // is missing. Said here rather than discovered at the moment of + // saving. + if account.linked { + ui.label(RichText::new(labels.linked.as_str()).small().color(ui.visuals().weak_text_color())); + } else { + ui.label(RichText::new(labels.not_linked.as_str()).small().color(ui.visuals().warn_fg_color)); + if ui.button(labels.link.as_str()).clicked() { + let _ = tx.send(AccountAction::Link(account.id.clone())); + ui.close(); + } + } + + if !others.is_empty() { + ui.add_space(6.0); + ui.separator(); + ui.label(RichText::new(labels.other_accounts.as_str()).small().color(ui.visuals().weak_text_color())); + for other in &others { + // Both lines in one control. A name above a subtitle, where + // only the name answers a press, makes half the row look + // broken to anybody who aims at the wrong half. The + // deployment is on the second line because two accounts + // both reading "Will Dunn" tell nobody which is the work + // one. + let label = format!("{}\n{}", other.display, other.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = other.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(other.id.clone())); + ui.close(); + } + } + } + + if more_allowed { + ui.add_space(6.0); + if ui.button(labels.add_account.as_str()).clicked() { + let _ = tx.send(AccountAction::AddAccount); + ui.close(); + } + } + + ui.add_space(4.0); + if ui.link(labels.manage.as_str()).clicked() { + let _ = tx.send(AccountAction::Manage(account.id.clone())); + ui.close(); + } + }); + } + + /// Draw the badge in a context that has no `Ui` to hand. + pub fn show_in_ctx(&mut self, ctx: &Context) { + egui::Area::new(egui::Id::new("craft-ui/account")).anchor(egui::Align2::RIGHT_TOP, egui::vec2(-8.0, 8.0)).show(ctx, |ui| { + self.show(ui); + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn account(id: &str, display: &str) -> Account { + Account { id: id.into(), display: display.into(), service: "one.example.com".into(), ..Account::default() } + } + + #[test] + fn nobody_signed_in_has_no_active_account() { + let menu = AccountMenu::new(); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn the_first_account_becomes_the_active_one() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn replacing_the_list_keeps_the_account_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work"), account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b"), "an unrelated refresh must not switch accounts"); + } + + #[test] + fn an_account_that_signed_out_elsewhere_leaves_nobody_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + // Not account a. A work session that expires must not hand the next + // save to a personal account without anybody saying so. + assert_eq!(menu.active(), None, "the one that is gone cannot be replaced in silence"); + assert!(menu.is_signed_in(), "there is still an account here to choose"); + } + + #[test] + fn choosing_again_after_one_disappeared_works() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + menu.set_active("a"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn a_refresh_that_keeps_the_account_keeps_it_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b")); + } + + #[test] + fn the_last_account_leaving_signs_everybody_out() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set(Vec::new()); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn switching_to_an_account_that_is_not_here_changes_nothing() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set_active("nobody"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn the_badge_says_what_it_is_as_well_as_who() { + let labels = AccountLabels::default(); + let spoken = labels.badge.replace("{name}", "Ada Lovelace"); + assert_eq!(spoken, "Account, Ada Lovelace"); + assert_ne!(spoken, "Ada Lovelace", "a bare name collides with every other place it is written"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(account("1", "ann").initial(), "A"); + assert_eq!(account("1", "").initial(), "?"); + assert_eq!(account("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/ui/src/buttons/mod.rs b/crates/ui/src/buttons/mod.rs index 6865daa82..1405f6943 100644 --- a/crates/ui/src/buttons/mod.rs +++ b/crates/ui/src/buttons/mod.rs @@ -120,3 +120,18 @@ fn bounded_stroke(stroke: Stroke, rect: Rect) -> Stroke { #[cfg(test)] mod tests; + +/// A downward triangle at the right-hand end of a control. +/// +/// Painted rather than typed. The chevron character is absent from the default +/// font set, where it renders as a missing-glyph box. A caller leaves room for +/// it by padding the label, then paints it over the response. +pub fn chevron(ui: &Ui, rect: egui::Rect, colour: egui::Color32) { + let middle = rect.right_center() - egui::vec2(9.0, 0.0); + let half = 3.5; + ui.painter().add(egui::Shape::convex_polygon( + vec![middle + egui::vec2(-half, -half * 0.6), middle + egui::vec2(half, -half * 0.6), middle + egui::vec2(0.0, half * 0.9)], + colour, + egui::Stroke::NONE, + )); +} diff --git a/crates/ui/src/cloud/app.rs b/crates/ui/src/cloud/app.rs new file mode 100644 index 000000000..b98e91ba5 --- /dev/null +++ b/crates/ui/src/cloud/app.rs @@ -0,0 +1,255 @@ +//! What this module needs from the application around it. +//! +//! Two operations here belong to the application alone. One turns bytes into an +//! open document. The other turns an open document into bytes. Both need the +//! application's own mutable state. That state is what holds the +//! [`CloudFiles`](crate::cloud::CloudFiles) this module keeps its own state in. +//! The pages are therefore free functions over this trait. An application +//! reaches its cloud state back through [`CloudApp::cloud_mut`]. +//! +//! Every method here is something only the application can answer. The ones +//! with a body are the ones a plain application can leave alone. + +use egui::{Color32, FontFamily, Painter, Rect, Ui}; + +use craft_cloud::EntryKind; + +/// What one of the application's documents is, as a file list needs to know. +/// +/// Four pieces of static data, usually one `const` in the application. These +/// four are the whole of what an application has to say about its own +/// documents. They are data because every one of them as a trait method would +/// have been a pure function of nothing. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct DocumentKind { + /// Extensions this application opens, lower case and without a dot. The + /// same set its desktop file picker offers. + pub extensions: &'static [&'static str], + /// Content types it opens, matched against the start of what the provider + /// said. The match is a prefix. A provider commonly appends a profile to a + /// type it is otherwise right about. + pub mimes: &'static [&'static str], + /// What one is called in a sentence a user reads. "workbook", "document", + /// "drawing". + pub noun: &'static str, + /// The extension a typed name without a known one gets. + pub default_extension: &'static str, +} + +/// The colours and faces these pages draw in. +/// +/// The Open and Save pages sit inside the application's own Backstage view and +/// have to match the surface around them. `ui.visuals()` alone cannot say what +/// that surface is. An application with a palette of its own passes it in. One +/// without takes [`CloudStyle::from_visuals`] and writes nothing. +#[derive(Clone, Debug)] +pub struct CloudStyle { + /// Behind a bordered column. + pub surface: Color32, + pub border: Color32, + pub text: Color32, + /// Second lines, hints and the status line. + pub dim: Color32, + /// Behind a file row the pointer is over. + pub hover: Color32, + /// Behind the panel that offers to link an account. Tinted and never + /// alarming. No account yet is a state with an obvious next step. + pub soft: Color32, + pub family: FontFamily, + pub bold: FontFamily, +} + +impl CloudStyle { + /// Colours from egui's own visuals, for an application with no palette. + pub fn from_visuals(visuals: &egui::Visuals) -> CloudStyle { + CloudStyle { + surface: visuals.faint_bg_color, + border: visuals.widgets.noninteractive.bg_stroke.color, + text: visuals.text_color(), + dim: visuals.weak_text_color(), + hover: visuals.widgets.hovered.bg_fill, + soft: visuals.faint_bg_color, + family: FontFamily::Proportional, + bold: FontFamily::Proportional, + } + } +} + +/// One of the application's own Save a Copy formats, for the second half of +/// the Share menu. +/// +/// The application's own. What a spreadsheet exports and what a page layout +/// application exports have nothing in common. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CopyFormat { + /// Handed back untouched when this one is chosen. + pub id: String, + pub label: String, +} + +impl CopyFormat { + pub fn new(id: impl Into, label: impl Into) -> CopyFormat { + CopyFormat { id: id.into(), label: label.into() } + } +} + +/// An application that opens and saves documents in cloud storage. +/// Where a save is going. +/// +/// Carried as a pair because neither half is reliable alone. A provider hands +/// back `application/octet-stream` for a perfectly good document, and a file +/// exported by a web application often has a correct content type and no +/// extension at all. The same reasoning as [`DocumentKind`], which reads both +/// when deciding whether a document opens. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Destination<'a> { + /// The file name the bytes are going to. + pub name: &'a str, + /// What the provider says is already there, where it says anything. Absent + /// for a document that does not exist yet. + pub mime: Option<&'a str>, +} + +impl<'a> Destination<'a> { + pub fn new(name: &'a str) -> Destination<'a> { + Destination { name, mime: None } + } + + /// The extension the name carries, lower cased, when it carries one. + /// + /// Empty for a bare name. A caller that gets nothing here has the content + /// type left to read. + pub fn extension(&self) -> String { + self.name.rsplit_once('.').map(|(_, ext)| ext.to_ascii_lowercase()).filter(|ext| !ext.is_empty()).unwrap_or_default() + } +} + +pub trait CloudApp { + // ---- the state these pages keep ------------------------------------- + + fn cloud(&self) -> &crate::cloud::CloudFiles; + fn cloud_mut(&mut self) -> &mut crate::cloud::CloudFiles; + + // ---- its documents --------------------------------------------------- + + fn kind(&self) -> DocumentKind; + + /// The document in this window, when there is one. + fn active(&self) -> Option; + + /// What to call one, for the Save As name field. + fn title(&self, uid: u64) -> String; + + /// Turn bytes into an open document, answering with the one it opened as. + /// + /// `Ok(None)` when the application took the bytes somewhere else, such as + /// a prompt for a password. Nothing is said about them yet. `Err` is put + /// to the user. + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String>; + + /// Turn one open document into the bytes to save, for `into`. + /// + /// [`Destination`] is where the bytes are going. A document opened from + /// the cloud as `figures.csv` has to go back as a CSV. Encoding it in the + /// application's own format under that name hands the user a file no other + /// application can read, and nothing tells them it happened. + /// + /// The name is the first answer. A provider that issued no extension at + /// all still says what the thing is, so the content type is the second. + /// Both appear often: a file exported by a web application commonly has a + /// correct content type and a bare name. + /// + /// An application that cannot write what the destination asks for should + /// refuse and say which formats it can write. A refusal a person can act + /// on beats a file that silently is not what it claims. + /// + /// Takes `&mut self` so the application can record which version of the + /// document these bytes were. A save that lands clears the dirty flag for + /// exactly that version. An edit made while the bytes were on the wire + /// stays unsaved. [`CloudApp::mark_saved`] and [`CloudApp::drop_pending`] + /// say which happened. + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String>; + + /// Close a document a reload replaced. Called only once the replacement is + /// open. A read that failed leaves the user's work where it was. + fn close(&mut self, uid: u64); + + /// The bytes [`CloudApp::encode`] made reached the service. + fn mark_saved(&mut self, _uid: u64) {} + + /// They did not. Forget the version it recorded. + fn drop_pending(&mut self, _uid: u64) {} + + /// Finish whatever the user is still typing. False stops the save. + fn ready_to_save(&mut self) -> bool { + true + } + + // ---- the window around them ------------------------------------------ + + /// The share dialog this window holds. Opened from a document's overflow + /// menu and from the Share button. Refreshed when who is signed in + /// changes. + fn sharing(&mut self) -> &mut crate::share::ShareDialog; + + /// Who else is in the document. Drawn beside the account badge. + fn presence(&mut self) -> &mut crate::presence::PresenceBar; + + /// Paint the icon for one row of a file list. Every application already + /// owns an icon set. None of them agree on how it is reached. + fn paint_icon(&self, painter: &Painter, rect: Rect, kind: EntryKind, colour: Color32); + + /// Open a URL in the user's browser. A browser is the application's + /// business. This crate opens nothing. + fn open_url(&self, url: &str); + + /// Open the provider's conversation for this document. + /// + /// Desktop hosts may hand this to the operating system so a registered + /// chat application can claim it. Browser hosts may navigate the current + /// tab, which remains reliable after an asynchronous provider lookup. + fn open_conversation(&self, url: &str) { + self.open_url(url); + } + + /// Say something that needs the user's attention, in the application's own + /// message box. + fn say(&mut self, text: String); + + /// Say something that does not, in passing. + fn toast(&mut self, _text: String) {} + + /// Take the user to the application's own Save As page, with the name + /// [`CloudFiles::save_name`](crate::cloud::CloudFiles::save_name) now + /// holding. Called when a refused save is answered with Save as a copy. + fn go_to_save_as(&mut self) {} + + // ---- its words ------------------------------------------------------- + + /// What the application is called, for the one sentence that names it. + fn app_name(&self) -> &str; + + /// Translate one English string. The default leaves it alone. An + /// application with no translation table writes nothing. + fn tr(&self, text: &str) -> String { + text.to_owned() + } + + /// The host part of the service address, for the account menu's first + /// line. Somebody with an account on two deployments needs to know which + /// one a document is about to land in. + fn service(&self) -> String { + String::new() + } + + /// A line under the Save page's name field, about the format this + /// application saves in. + fn save_note(&self) -> Option { + None + } + + /// The colours and faces to draw in. + fn style(&self, ui: &Ui) -> CloudStyle { + CloudStyle::from_visuals(ui.visuals()) + } +} diff --git a/crates/ui/src/cloud/backend.rs b/crates/ui/src/cloud/backend.rs new file mode 100644 index 000000000..b6da57960 --- /dev/null +++ b/crates/ui/src/cloud/backend.rs @@ -0,0 +1,195 @@ +//! Where Open and Save do their waiting. It is never on the frame. +//! +//! Every call a cloud provider needs is blocking. A blocking read of a twenty +//! megabyte document inside `update()` freezes the window for seconds. So this +//! module states a [`Job`] and reads an [`Event`]. Something behind +//! [`CloudBackend`] does the waiting. +//! +//! Nothing here opens a socket. That keeps the pages buildable for the web and +//! testable with no service running. A host supplies the half that does. This +//! crate never learns what it reaches. + +use std::sync::mpsc::Sender; + +use craft_cloud::{Capability, Conversation, Entry}; + +/// Work for a host's worker. Each one answers with one or more [`Event`]. +pub enum Job { + /// Who is signed in, and what the provider behind the service can do. + Account, + /// Begin signing in to the service through the browser or device flow. + SignIn, + /// Begin linking a cloud account. The answer carries a URL to open. + LinkStart, + /// Whether the user has finished in the browser yet. + LinkPoll(String), + /// One folder's contents. An empty path is the user's root. + List(String), + /// Everything other people have shared with this user. + SharedWithMe, + /// A document's bytes. `into` names the open document a reload replaces. + Read { entry: Entry, into: Option }, + /// Save back over `entry`, refusing to overwrite a newer version. + Write { uid: u64, entry: Entry, bytes: Vec }, + /// Save under a new name in `folder`. + Create { uid: u64, folder: String, name: String, bytes: Vec }, + /// End the session and forget the saved token. + SignOut, + /// Where to go to work together on a document. + Conversation(String), +} + +/// What a worker reports back. +pub enum Event { + /// Where to go to work together, or why there is nowhere. + Conversation(Result), + Account(Result), + /// A link or a sign-in needs the user's browser. `handle` is polled until + /// they are done, when the service gave one. + Browser { + url: String, + handle: Option, + }, + /// `Ok(true)` means the account is linked now. + Linked(Result), + Listed { + path: String, + entries: Result, Fault>, + }, + Shared(Result, Fault>), + Read { + entry: Entry, + into: Option, + bytes: Result, Fault>, + }, + Saved { + uid: u64, + entry: Result, + }, +} + +/// Where a worker's answers go. +/// +/// Handed to [`CloudBackend::submit`] with the job it belongs to. A worker is +/// free to keep it and send later, or to send several times. That is how a +/// sign-in reports the URL it wants a browser pointed at and then reports that +/// the user finished there. A send after the window closed is not a failure. +pub struct Post { + tx: Sender, +} + +impl Post { + pub(crate) fn new(tx: Sender) -> Post { + Post { tx } + } + + /// Another handle to the same place, for a worker that answers more than + /// once or hands the job on. + pub fn dup(&self) -> Post { + Post { tx: self.tx.clone() } + } + + pub fn send(&self, event: Event) { + let _ = self.tx.send(event); + } +} + +impl std::fmt::Debug for Post { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Post").finish() + } +} + +/// Somewhere a [`Job`] can run without blocking a frame. +/// +/// `submit` must return immediately. Answers arrive through `post` whenever +/// they are ready, or never. The pages survive either. +pub trait CloudBackend { + fn submit(&self, job: Job, post: Post); +} + +/// What the service said about the signed-in user. +/// +/// Capabilities are reported by the service and never assumed here. A provider +/// without incoming shares hides that side of the Open page. An empty list +/// where a feature should be reads to a user as a broken window. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + pub display: String, + pub capabilities: Vec, + /// Until this is true, Open and Save have nowhere to go. + pub provider_linked: bool, +} + +impl Account { + pub fn can(&self, capability: Capability) -> bool { + self.capabilities.contains(&capability) + } +} + +/// A call that did not succeed, in the shapes the pages act on differently. +/// +/// One case is worth telling apart from every other refusal. A conditional +/// write the server refused means somebody else's work is in the stored copy. +/// That one must never be retried and must never be forced. That is why +/// [`Fault::Conflict`] has a shape of its own. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Fault { + /// No cloud account is linked yet. This is a state with an obvious next + /// step. It is never drawn as an error. + NotLinked, + /// Somebody else saved while this user was editing. The save was refused + /// and their work is intact. + Conflict, + /// The session expired. The user signs in again. + Unauthenticated, + Unreachable(String), + Refused(String), +} + +impl Fault { + /// One sentence for a person to read. `noun` is what the application calls + /// one of its documents, from [`crate::cloud::DocumentKind::noun`]. + pub fn text(&self, noun: &str) -> String { + match self { + Fault::NotLinked => "No cloud account is linked yet.".to_owned(), + Fault::Conflict => format!("Somebody else saved this {noun} while you were editing it."), + Fault::Unauthenticated => "Your cloud session has expired. Sign in again.".to_owned(), + Fault::Unreachable(detail) => format!("The cloud service could not be reached. {detail}"), + Fault::Refused(detail) => detail.clone(), + } + } + + /// A short machine-readable name, for a control channel. + pub fn code(&self) -> &'static str { + match self { + Fault::NotLinked => "not_linked", + Fault::Conflict => "conflict", + Fault::Unauthenticated => "unauthenticated", + Fault::Unreachable(_) => "unreachable", + Fault::Refused(_) => "refused", + } + } +} + +/// The contract's own error, in the shapes the pages act on. +/// +/// For a host that reaches a provider through [`craft_cloud`] directly. A host +/// that reaches a service through its own client crate maps that crate's error +/// instead, since only it knows which code that service answers a refused +/// conditional write with. +/// +/// [`craft_cloud::Error::Conflict`] is the one case worth telling apart. It +/// means somebody else's work is in the stored copy. The save must never be +/// retried and never be forced. +impl From for Fault { + fn from(error: craft_cloud::Error) -> Fault { + use craft_cloud::Error; + match error { + Error::Unreachable(detail) => Fault::Unreachable(detail), + Error::Unauthenticated => Fault::Unauthenticated, + Error::Conflict(_) => Fault::Conflict, + other => Fault::Refused(other.to_string()), + } + } +} diff --git a/crates/ui/src/cloud/mod.rs b/crates/ui/src/cloud/mod.rs new file mode 100644 index 000000000..220afc04e --- /dev/null +++ b/crates/ui/src/cloud/mod.rs @@ -0,0 +1,852 @@ +//! Open and Save against cloud storage, the same pages in every Craft app. +//! +//! What this offers is what a person asks for when they say "open the one in +//! my cloud": a Backstage page with their own files on one side and what other +//! people shared with them on the other, folders to walk into, an account badge +//! that says whose storage this is, a Save As page that picks a folder and +//! names a file, and a save that refuses to overwrite somebody else's work. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`CloudBackend`]. A +//! host writes that half. This module never learns what it reaches. That keeps +//! it buildable for the web and testable with no service running. +//! +//! Nothing here blocks. A job goes to a worker, the answer arrives on a +//! channel, and [`pump`] drains it on a later frame. A blocking read of a +//! twenty megabyte document inside a frame would freeze the window for seconds. +//! +//! Nothing here is assumed about the provider. Every side of the Open page is +//! drawn only where the service reported the capability behind it. An empty +//! list under a heading reads to a user as a broken window. A feature the +//! provider does not have is therefore absent, heading and all. +//! +//! The application supplies [`CloudApp`]. That is what it alone can answer. +//! What its documents are, how bytes become one and back, and the words it +//! shows them in. + +use std::collections::HashMap; +use std::sync::mpsc::{Receiver, Sender, channel}; +use std::time::Duration; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{Align2, Rect, RichText, Sense, Stroke, Ui, pos2, vec2}; +use serde_json::{Value as Json, json}; + +mod app; +mod backend; +mod pages; +#[cfg(test)] +mod tests; +mod title; + +pub use app::{CloudApp, CloudStyle, CopyFormat, Destination, DocumentKind}; +pub use backend::{Account, CloudBackend, Event, Fault, Job, Post}; +pub use pages::{conflict_modal, open_page, progress, save_page}; +pub use title::{destination_name, prefers_cloud, share_button, shares, who}; + +/// How long to wait between asking whether the user has finished linking an +/// account in their browser. +const LINK_POLL: f64 = 1.5; + +/// What a command says when no cloud service is configured. Not a failure of +/// the service: there is no service to fail. +pub const UNAVAILABLE: &str = "no cloud service is configured"; + +// ---------------------------------------------------------------- state + +/// One folder, as it is being browsed. +#[derive(Clone, Debug, Default)] +pub struct Folder { + pub path: String, + pub entries: Vec, + pub loading: bool, + pub error: Option, + /// Answered at least once. An empty folder then reads as empty. Without + /// this it would read as still loading. + pub loaded: bool, +} + +impl Folder { + fn begin(&mut self, path: &str) { + self.path = path.to_owned(); + self.entries.clear(); + self.loading = true; + self.loaded = false; + self.error = None; + } + + fn fill(&mut self, answer: Result, Fault>) { + self.loading = false; + self.loaded = true; + match answer { + Ok(entries) => { + self.entries = entries; + self.error = None; + } + Err(fault) => { + self.entries.clear(); + self.error = Some(fault); + } + } + } +} + +/// Where the document in this window came from, and the version it came at. +/// +/// `entry.id` is the opaque handle a save passes back. `entry.etag` is the +/// version the conditional write is made against. `entry.room` is neither of +/// those. It is the collaboration identity, and it survives a rename. +#[derive(Clone, Debug)] +pub struct Origin { + pub entry: Entry, +} + +/// What the pages are waiting for. Drawn as progress while they wait. +#[derive(Clone, Debug)] +pub enum Busy { + Opening { name: String }, + Saving { name: String, bytes: usize }, +} + +impl Busy { + pub fn text(&self) -> String { + match self { + Busy::Opening { name } => format!("Opening {name}…"), + Busy::Saving { name, bytes } => format!("Saving {name} ({})…", size_text(Some(*bytes as u64))), + } + } +} + +/// A save that was refused because the stored copy had moved on. +#[derive(Clone, Debug)] +pub struct Conflict { + /// The document that could not be saved. + pub uid: u64, + pub entry: Entry, +} + +/// Linking a cloud account, which takes a browser round trip. +#[derive(Clone, Debug)] +pub enum Link { + /// Offered and not started. Never drawn as an error. + Offered, + Starting, + /// The browser is open. `handle` is polled until the user is done. + Waiting { + url: String, + handle: Option, + next_poll: f64, + }, + Failed(Fault), +} + +/// Which side of the Open page a selection came from. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Source { + #[default] + Mine, + Shared, +} + +/// Who a document was shared with, when nobody is signed in. +/// +/// Somebody who followed a keyed link has no account at the service and none +/// at the provider behind it. So there is nothing to sign out of, no second +/// account to switch to and no storage to connect. An account menu offered to +/// them would be a menu whose every item fails. +/// +/// This is what a title bar says instead. It names the address the link was +/// sent to, because that is the only identity a recipient has here, and it +/// offers nothing. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Guest { + /// The address the link was sent to. + pub recipient: String, + /// Whether the share opens the document for reading only. + pub read_only: bool, +} + +/// Everything these pages keep about cloud storage. +/// +/// One per window. The application declares a field of this type, hands it +/// back through [`CloudApp::cloud_mut`], and connects a backend once one +/// exists. +pub struct CloudFiles { + backend: Option>, + events: (Sender, Receiver), + /// The badge and its menu. Signing in is the only way into any of this. + /// The badge is the only control that offers it. It lives here. An + /// application declares no field for it. + accounts: crate::account::AccountMenu, + /// Frame time, in seconds, as of the last [`pump`]. Kept because a link + /// poll is scheduled from an answer that arrives with no frame in hand. + clock: f64, + pub account: Option, + pub account_fault: Option, + /// The account is asked for once per run. A frame never asks again. + asked_account: bool, + /// The folder being browsed. Shared by the Open and Save As pages, which + /// are never on screen together. + pub mine: Folder, + pub shared: Folder, + pub source: Source, + pub busy: Option, + pub link: Option, + pub conflict: Option, + /// Save As: the file name being typed. + pub save_name: String, + /// Documents that came from the cloud, by document uid. + pub origins: HashMap, + /// The last thing that happened, for the line under the page title. + pub status: Option, + /// Whether the transfer in flight was started by the share dialog, which + /// is waiting to be told how it went. + pub sharing_save: bool, + /// Set when this window belongs to somebody who followed a shared link + /// rather than to somebody signed in. + guest: Option, + /// Set when the account menu starts sign-in. Browser builds open a login + /// popup from this gesture instead of inferring it from `status`, which can + /// stay set after a failed sign-in. + sign_in_from_menu: bool, +} + +impl Default for CloudFiles { + fn default() -> CloudFiles { + CloudFiles::new() + } +} + +impl CloudFiles { + pub fn new() -> CloudFiles { + CloudFiles { + backend: None, + events: channel(), + accounts: crate::account::AccountMenu::new(), + clock: 0.0, + account: None, + account_fault: None, + asked_account: false, + mine: Folder::default(), + shared: Folder::default(), + source: Source::default(), + busy: None, + link: None, + conflict: None, + save_name: String::new(), + origins: HashMap::new(), + status: None, + sharing_save: false, + guest: None, + sign_in_from_menu: false, + } + } + + /// Whether the account menu just asked to sign in. Consumed by browser hosts + /// that need a user-gesture signal to open a login popup. + pub fn take_sign_in_from_menu(&mut self) -> bool { + std::mem::take(&mut self.sign_in_from_menu) + } + + /// Attach the thing that does the waiting. + /// + /// Until this is called nothing cloud-shaped is offered anywhere. That is + /// what a build with no service configured wants. + pub fn connect(&mut self, backend: impl CloudBackend + 'static) { + self.backend = Some(Box::new(backend)); + } + + /// Whether a service is wired at all. + pub fn available(&self) -> bool { + self.backend.is_some() + } + + /// Say that this window belongs to somebody who followed a shared link. + /// + /// Called once, before anything is drawn, by whatever landed them here. + /// It changes what the title bar says and nothing else: a recipient has no + /// file list and no account, so none of the pages here were ever offered + /// to them. + /// + /// An address of only spaces leaves no guest. A badge with nothing on it + /// reads as a fault, and saying nothing is better than that. + pub fn as_guest(&mut self, recipient: impl Into, read_only: bool) { + let recipient = recipient.into().trim().to_owned(); + self.guest = if recipient.is_empty() { None } else { Some(Guest { recipient, read_only }) }; + } + + /// Who this window's document was shared with, when nobody is signed in. + pub fn guest(&self) -> Option<&Guest> { + self.guest.as_ref() + } + + /// The account badge's own strings, for a localized application that + /// would rather translate them itself than through + /// [`CloudApp::tr`](crate::cloud::CloudApp::tr). + pub fn account_menu_mut(&mut self) -> &mut crate::account::AccountMenu { + &mut self.accounts + } + + /// Whether the provider offers somewhere to talk about a document. + pub fn can_converse(&self) -> bool { + self.can(Capability::Conversation) + } + + fn can(&self, capability: Capability) -> bool { + self.account.as_ref().is_some_and(|a| a.can(capability)) + } +} + +// ---------------------------------------------------------------- asking + +/// Whether the host wired a cloud service. When it did not, nothing +/// cloud-shaped is offered anywhere in the interface. +pub fn available(app: &A) -> bool { + app.cloud().available() +} + +/// Whether the provider offers somewhere to talk about a document. +pub fn can_converse(app: &A) -> bool { + app.cloud().can_converse() +} + +/// Hands a job to the host's worker. +pub fn submit(app: &A, job: Job) { + let cloud = app.cloud(); + if let Some(backend) = &cloud.backend { + backend.submit(job, Post::new(cloud.events.0.clone())); + } +} + +/// Asks who is signed in, once per run, and lists the root folder. +pub fn start(app: &mut A) { + if !available(app) { + return; + } + if !app.cloud().asked_account { + app.cloud_mut().asked_account = true; + submit(app, Job::Account); + } + if !app.cloud().mine.loaded && !app.cloud().mine.loading { + browse(app, ""); + } +} + +/// Begins signing in to the service. +/// +/// [`Job::SignIn`] is its own job so [`Job::Account`] can stay read-only on +/// cold start. The badge says it is working, because the worker then blocks +/// until the user finishes in the browser and a button that looks idle for a +/// minute reads as broken. +pub fn sign_in(app: &mut A) { + if !available(app) { + return; + } + let working = app.tr("Finish signing in, in your browser"); + let cloud = app.cloud_mut(); + cloud.accounts.working(); + cloud.account_fault = None; + // Cleared first. A sign-in that failed leaves this set, and a second press + // would then be swallowed by the guard that stops a frame asking twice. A + // button that does nothing the second time reads as a broken button. + cloud.asked_account = true; + cloud.link = None; + cloud.status = Some(working); + submit(app, Job::SignIn); +} + +/// Ends the session, here and at the service. +/// +/// The saved token goes too. Forgetting the account on screen while leaving the +/// token on disk would sign the user back in on the next run. +pub fn sign_out(app: &mut A) { + let signed_out = app.tr("Signed out"); + let cloud = app.cloud_mut(); + cloud.account = None; + cloud.account_fault = None; + cloud.asked_account = false; + cloud.link = None; + cloud.mine = Folder::default(); + cloud.shared = Folder::default(); + cloud.origins.clear(); + cloud.status = Some(signed_out); + submit(app, Job::SignOut); +} + +/// Lists one folder. An empty path is the user's root. +pub fn browse(app: &mut A, path: &str) { + if !available(app) { + return; + } + app.cloud_mut().mine.begin(path); + submit(app, Job::List(path.to_owned())); +} + +/// Lists what other people have shared with this user. +pub fn load_shared(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().shared.begin(""); + submit(app, Job::SharedWithMe); +} + +/// Begins linking a cloud account. +pub fn link(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().link = Some(Link::Starting); + submit(app, Job::LinkStart); +} + +/// Asks where to work together on the open document, then opens it. +/// +/// Only offered where the provider reports it. A document that has never been +/// in the cloud has no handle to key a room on, so there is nothing to ask +/// about either. +pub fn work_together(app: &mut A) { + if !available(app) { + return; + } + let Some(id) = origin(app).map(|o| o.entry.id.clone()) else { + let noun = app.kind().noun; + app.cloud_mut().status = Some(app.tr(&format!("Save this {noun} to the cloud first"))); + return; + }; + converse(app, id); +} + +/// Asks the provider where to work together on one document. +fn converse(app: &mut A, id: String) { + let opening = app.tr("Opening a conversation"); + app.cloud_mut().status = Some(opening); + submit(app, Job::Conversation(id)); +} + +/// The parent of a path. `None` at the root. +pub fn parent_of(path: &str) -> Option { + let trimmed = path.trim_end_matches('/'); + if trimmed.is_empty() { + return None; + } + match trimmed.rfind('/') { + Some(0) | None => Some(String::new()), + Some(cut) => Some(trimmed[..cut].to_owned()), + } +} + +/// Whether this application can open an entry, judged by its extension and by +/// what the provider says it is. +/// +/// Both signals are read because neither is reliable alone. A WebDAV server +/// hands back `application/octet-stream` for a perfectly good spreadsheet. A +/// file exported by a web application often has a correct content type and no +/// extension at all. +pub fn opens(entry: &Entry, kind: DocumentKind) -> bool { + if entry.kind == EntryKind::Folder { + return false; + } + let extension = entry.name.rsplit_once('.').map(|(_, e)| e.to_ascii_lowercase()); + let by_name = extension.is_some_and(|e| kind.extensions.contains(&e.as_str())); + by_name || entry.mime.as_deref().is_some_and(|mime| mime_opens(mime, kind)) +} + +fn mime_opens(mime: &str, kind: DocumentKind) -> bool { + let mime = mime.split(';').next().unwrap_or("").trim().to_ascii_lowercase(); + kind.mimes.iter().any(|known| mime.starts_with(known)) +} + +/// A typed name as a document file name. Any folder separators are dropped and +/// a missing or unknown extension becomes the application's own. +pub fn document_name(typed: &str, kind: DocumentKind) -> String { + let base = typed.rsplit(['/', '\\']).next().unwrap_or("").trim(); + if base.is_empty() { + return String::new(); + } + let known = base.rsplit_once('.').is_some_and(|(stem, ext)| !stem.is_empty() && kind.extensions.contains(&ext.to_ascii_lowercase().as_str())); + if known { base.to_owned() } else { format!("{base}.{}", kind.default_extension) } +} + +/// One sentence with a value in it, translated whole. +/// +/// The template reaches [`CloudApp::tr`] with its `{}` intact. A translator +/// sees the whole sentence and can put the value where their own language +/// wants it. A sentence assembled from translated fragments cannot be made to +/// read correctly in a language that orders them differently. +fn fill(app: &A, template: &str, value: &str) -> String { + app.tr(template).replacen("{}", value, 1) +} + +/// A file name without its extension. +fn stem_of(name: &str) -> String { + match name.rsplit_once('.') { + Some((stem, _)) if !stem.is_empty() => stem.to_owned(), + _ => name.to_owned(), + } +} + +// ---------------------------------------------------------------- opening + +/// Reads a document and opens it. `into` names an open document the bytes +/// replace, which is how a reload after a conflict works. +pub fn open_entry(app: &mut A, entry: Entry, into: Option) { + if !available(app) || app.cloud().busy.is_some() { + return; + } + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Opening { name: entry.name.clone() }); + submit(app, Job::Read { entry, into }); +} + +/// Reads the active document's stored copy again. Local edits are discarded. +pub fn reload_active(app: &mut A) -> Result { + let noun = app.kind().noun; + let Some(uid) = app.active() else { return Err(format!("no {noun} open")) }; + let Some(origin) = app.cloud().origins.get(&uid).cloned() else { return Err(format!("this {noun} did not come from the cloud")) }; + app.cloud_mut().conflict = None; + let name = origin.entry.name.clone(); + open_entry(app, origin.entry, Some(uid)); + Ok(json!({"reloading": name})) +} + +// ---------------------------------------------------------------- saving + +/// The cloud document the active one came from, when it came from one. +pub fn origin(app: &A) -> Option<&Origin> { + let uid = app.active()?; + app.cloud().origins.get(&uid) +} + +/// Whether Save has somewhere to go without asking. A Backstage view uses this +/// to choose between Save and the Save As page. +pub fn has_target(app: &A) -> bool { + origin(app).is_some_and(|o| o.entry.writable) +} + +/// Save: writes back over the entry this document came from. +/// +/// The etag the document was read at goes out as the condition. A server whose +/// copy has moved on refuses the write. That arrives as [`Fault::Conflict`] and +/// is put to the user. It is never retried. +pub fn save(app: &mut A) -> Result { + let noun = app.kind().noun; + let uid = app.active().ok_or(format!("no {noun} open"))?; + let origin = app.cloud().origins.get(&uid).cloned().ok_or(format!("this {noun} did not come from the cloud"))?; + if !origin.entry.writable { + return Err("this document was shared with you for reading only. Save As keeps a copy of your own.".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + let bytes = app.encode(uid, Destination { name: &origin.entry.name, mime: origin.entry.mime.as_deref() })?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: origin.entry.name.clone(), bytes: size }); + let answer = json!({"saving": origin.entry.name, "bytes": size, "ifMatch": origin.entry.etag}); + submit(app, Job::Write { uid, entry: origin.entry, bytes }); + Ok(answer) +} + +/// Save As: writes a new document into `folder` under `name`. +pub fn save_as(app: &mut A, folder: &str, name: &str) -> Result { + let kind = app.kind(); + let uid = app.active().ok_or(format!("no {} open", kind.noun))?; + let name = document_name(name, kind); + if name.is_empty() { + return Err("type a file name".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + // A document that does not exist yet has no content type to read. The + // name a person just typed is the whole of what was asked for. + let bytes = app.encode(uid, Destination::new(&name))?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: name.clone(), bytes: size }); + let answer = json!({"saving": name, "folder": folder, "bytes": size}); + submit(app, Job::Create { uid, folder: folder.to_owned(), name, bytes }); + Ok(answer) +} + +// ---------------------------------------------------------------- reading the answers + +/// Drains the host's answers and keeps a link or a transfer moving. Called +/// once a frame, before anything is drawn. +pub fn pump(app: &mut A, ctx: &egui::Context) { + if !available(app) { + return; + } + app.cloud_mut().clock = ctx.input(|i| i.time); + // Taken in one pass, then applied. An answer that arrives because of a job + // this frame sent belongs to the next frame. A worker on its own thread + // would have delivered it that way anyway. + let mut arrived = Vec::new(); + while let Ok(event) = app.cloud().events.1.try_recv() { + arrived.push(event); + } + for event in arrived { + apply(app, event); + } + poll_link(app); + // A worker answering is not a local event. Without this the progress line + // would sit frozen until the user moved the mouse. + if app.cloud().busy.is_some() || matches!(app.cloud().link, Some(Link::Starting | Link::Waiting { .. })) { + ctx.request_repaint_after(Duration::from_millis(120)); + } +} + +fn apply(app: &mut A, event: Event) { + let noun = app.kind().noun; + match event { + Event::Account(Ok(account)) => { + let linked = account.provider_linked; + // Who is signed in has changed, so what the provider can do may + // have changed with it. The dialog keeps its first answer, and on a + // cold start that answer is "nobody is signed in". + app.sharing().refresh(); + let cloud = app.cloud_mut(); + cloud.account = Some(account); + cloud.account_fault = None; + if linked { + cloud.link = None; + } else if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + // No account linked yet is a state with an obvious next step. It is an + // offer to link, and never an error message. + Event::Account(Err(Fault::NotLinked)) => { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + Event::Account(Err(fault)) => app.cloud_mut().account_fault = Some(fault), + Event::Conversation(Ok(conversation)) => { + let said = fill(app, "Opened in {}", &conversation.name); + app.cloud_mut().status = Some(said); + app.open_conversation(&conversation.url); + } + Event::Conversation(Err(fault)) => { + let text = fault.text(noun); + app.cloud_mut().status = Some(text); + } + Event::Browser { url, handle } => { + app.open_url(&url); + let next_poll = app.cloud().clock + LINK_POLL; + app.cloud_mut().link = Some(Link::Waiting { url, handle, next_poll }); + } + Event::Linked(Ok(true)) => { + // Storage just arrived, so ask what it can do. + app.sharing().refresh(); + let linked = app.tr("Cloud account linked."); + let cloud = app.cloud_mut(); + cloud.link = None; + cloud.status = Some(linked); + cloud.asked_account = false; + submit(app, Job::Account); + browse(app, ""); + app.cloud_mut().shared.loaded = false; + } + // The ordinary answer while the user is still in the browser. + Event::Linked(Ok(false)) | Event::Linked(Err(Fault::NotLinked)) => {} + Event::Linked(Err(fault)) => app.cloud_mut().link = Some(Link::Failed(fault)), + Event::Listed { path, entries } => { + let cloud = app.cloud_mut(); + if path == cloud.mine.path { + cloud.mine.fill(entries); + } + } + Event::Shared(entries) => app.cloud_mut().shared.fill(entries), + Event::Read { entry, into, bytes } => { + app.cloud_mut().busy = None; + match bytes { + Ok(bytes) => opened(app, entry, into, bytes), + Err(Fault::NotLinked) => app.cloud_mut().link = Some(Link::Offered), + Err(fault) => { + let text = format!("{}. {}", fill(app, "{} could not be opened", &entry.name), fault.text(noun)); + app.say(text); + } + } + } + Event::Saved { uid, entry } => { + app.cloud_mut().busy = None; + match entry { + Ok(entry) => { + app.mark_saved(uid); + stored(app, uid, entry); + } + // The one failure that must never be retried and never forced. + Err(Fault::Conflict) => { + app.drop_pending(uid); + match app.cloud().origins.get(&uid).cloned() { + Some(origin) => app.cloud_mut().conflict = Some(Conflict { uid, entry: origin.entry }), + None => app.say(Fault::Conflict.text(noun)), + } + } + Err(Fault::NotLinked) => { + app.drop_pending(uid); + app.cloud_mut().link = Some(Link::Offered); + } + Err(fault) => { + app.drop_pending(uid); + let text = format!("{} {}", app.tr(&format!("The {noun} was not saved.")), fault.text(noun)); + app.say(text); + } + } + } + } +} + +/// Bytes arrived. The application opens them. The document then remembers +/// where they came from. +fn opened(app: &mut A, entry: Entry, into: Option, bytes: Vec) { + let name = entry.name.clone(); + match app.open_bytes(&name, bytes) { + Ok(now) => { + if let Some(uid) = now { + app.cloud_mut().origins.insert(uid, Origin { entry }); + } + // A reload closes the document it replaced only once the new one is + // open. A read that fails leaves the user's work where it was. + if let (Some(old), Some(new)) = (into, now) + && old != new + { + let cloud = app.cloud_mut(); + cloud.origins.remove(&old); + app.drop_pending(old); + app.close(old); + } + if now.is_some() { + let said = fill(app, "Opened {} from the cloud.", &name); + app.cloud_mut().status = Some(said); + } + } + Err(reason) => app.say(reason), + } +} + +/// A save landed. The document now belongs to the entry the server returned, at +/// the version it returned. +fn stored(app: &mut A, uid: u64, entry: Entry) { + let name = entry.name.clone(); + let line = fill(app, "Saved {} to the cloud.", &name); + app.toast(fill(app, "Saved {} to the cloud", &name)); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.status = Some(line); + cloud.origins.insert(uid, Origin { entry }); +} + +/// Keeps asking whether the user has finished linking in their browser. +fn poll_link(app: &mut A) { + let now = app.cloud().clock; + let handle = { + let Some(Link::Waiting { handle: Some(handle), next_poll, .. }) = &mut app.cloud_mut().link else { return }; + if now < *next_poll { + return; + } + *next_poll = now + LINK_POLL; + handle.clone() + }; + submit(app, Job::LinkPoll(handle)); +} + +// ---------------------------------------------------------------- reporting + +/// The whole of the cloud state, for a control channel and for tests. +pub fn report(app: &A) -> Json { + let kind = app.kind(); + let cloud = app.cloud(); + let account = cloud.account.as_ref().map(|a| { + json!({ + "display": a.display, + "providerLinked": a.provider_linked, + "capabilities": a.capabilities.iter().map(|c| serde_json::to_value(c).unwrap_or_default()).collect::>(), + }) + }); + let came_from = origin(app) + .map(|o| json!({"id": o.entry.id, "room": o.entry.room, "name": o.entry.name, "etag": o.entry.etag, "writable": o.entry.writable})); + json!({ + "available": cloud.available(), + "account": account, + "accountError": cloud.account_fault.as_ref().map(Fault::code), + "folder": cloud.mine.path, + "entries": cloud.mine.entries.iter().map(|e| e.name.clone()).collect::>(), + "openable": cloud.mine.entries.iter().filter(|e| opens(e, kind)).map(|e| e.name.clone()).collect::>(), + "shared": cloud.shared.entries.iter().map(|e| json!({"name": e.name, "sharedBy": e.shared_by, "writable": e.writable, "openable": opens(e, kind)})).collect::>(), + "busy": cloud.busy.as_ref().map(Busy::text), + "link": match &cloud.link { + None => Json::Null, + Some(Link::Offered) => json!("offered"), + Some(Link::Starting) => json!("starting"), + Some(Link::Waiting { url, .. }) => json!({"waiting": url}), + Some(Link::Failed(fault)) => json!({"failed": fault.code()}), + }, + "conflict": cloud.conflict.as_ref().map(|c| json!({"name": c.entry.name})), + "origin": came_from, + "status": cloud.status, + "guest": cloud.guest.as_ref().map(|g| json!({"recipient": g.recipient, "readOnly": g.read_only})), + }) +} + +// ---------------------------------------------------------------- shared drawing + +/// Bytes as a person reads them. +pub fn size_text(bytes: Option) -> String { + let Some(bytes) = bytes else { return String::new() }; + const UNITS: [&str; 4] = ["bytes", "KB", "MB", "GB"]; + let mut size = bytes as f64; + let mut unit = 0; + while size >= 1024.0 && unit + 1 < UNITS.len() { + size /= 1024.0; + unit += 1; + } + match UNITS.get(unit) { + Some(name) if unit > 0 => format!("{size:.1} {name}"), + _ => format!("{bytes} bytes"), + } +} + +fn dim(ui: &mut Ui, style: &CloudStyle, text: &str) { + ui.label(RichText::new(text).font(egui::FontId::new(12.5, style.family.clone())).color(style.dim)); +} + +/// A bordered column with a heading. This is how the two Open sources sit side +/// by side. +fn column(ui: &mut Ui, style: &CloudStyle, heading: &str, body: impl FnOnce(&mut Ui)) { + egui::Frame::NONE.fill(style.surface).stroke(Stroke::new(1.0, style.border)).corner_radius(6.0).inner_margin(10).show(ui, |ui| { + ui.label(RichText::new(heading).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.add_space(6.0); + egui::ScrollArea::vertical().id_salt(heading.to_owned()).max_height(300.0).auto_shrink([false, false]).show(ui, body); + }); +} + +/// One row in a file list, with a second line for the detail that matters on +/// that side of the page (a size for your own files, who shared it for +/// somebody else's). +fn entry_row(app: &A, ui: &mut Ui, entry: &Entry, detail: &str, reserve: f32) -> egui::Response { + let style = app.style(ui); + let width = (ui.available_width() - reserve).max(60.0); + let (rect, resp) = ui.allocate_exact_size(vec2(width, 40.0), Sense::click()); + let label = entry.name.clone(); + resp.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, &label)); + let p = ui.painter(); + if resp.hovered() { + p.rect_filled(rect, 4.0, style.hover); + } + app.paint_icon(p, Rect::from_center_size(pos2(rect.left() + 18.0, rect.center().y), vec2(18.0, 18.0)), entry.kind, style.text); + let (name_y, detail_y) = if detail.is_empty() { (rect.center().y, rect.center().y) } else { (rect.center().y - 8.0, rect.center().y + 9.0) }; + p.text(pos2(rect.left() + 38.0, name_y), Align2::LEFT_CENTER, &entry.name, egui::FontId::new(13.0, style.family.clone()), style.text); + if !detail.is_empty() { + p.text(pos2(rect.left() + 38.0, detail_y), Align2::LEFT_CENTER, detail, egui::FontId::new(11.0, style.family.clone()), style.dim); + } + resp +} diff --git a/crates/ui/src/cloud/pages.rs b/crates/ui/src/cloud/pages.rs new file mode 100644 index 000000000..fa1ead8be --- /dev/null +++ b/crates/ui/src/cloud/pages.rs @@ -0,0 +1,511 @@ +//! The Backstage pages: File › Open and File › Save As, and the modal a +//! refused save puts up. +//! +//! Every side of a page is drawn only where the service reported the +//! capability behind it. A list under a heading the provider cannot fill reads +//! to a user as a broken window, so the heading goes too. + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{RichText, Ui}; + +use super::{ + CloudApp, Link, Source, browse, column, converse, dim, document_name, entry_row, fill, link, load_shared, open_entry, opens, parent_of, + reload_active, save_as, size_text, start, stem_of, +}; + +/// The character a label ends with when choosing it opens a dialog. +const ELLIPSIS: &str = "\u{2026}"; + +/// What an overflow menu asked for, deferred until the list is no longer being +/// drawn. Opening a dialog while borrowing the list is not possible. +enum Act { + Share(Entry), + Talk(Entry), +} + +/// The account line, or the reason there is nothing to show yet. +fn header(app: &mut A, ui: &mut Ui) { + let style = app.style(ui); + let mut retry = false; + match (&app.cloud().account, &app.cloud().account_fault) { + (_, Some(fault)) => { + let text = fault.text(app.kind().noun); + let again = app.tr("Try again"); + ui.horizontal(|ui| { + dim(ui, &style, &text); + if ui.button(again).clicked() { + retry = true; + } + }); + } + (Some(account), None) => { + let line = if account.display.is_empty() { app.tr("Signed in") } else { account.display.clone() }; + dim(ui, &style, &line); + } + (None, None) => { + let waiting = app.tr("Connecting to your cloud account…"); + dim(ui, &style, &waiting); + } + } + if retry { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + cloud.asked_account = false; + start(app); + } +} + +/// The offer to link an account, and the wait while the browser is open. +/// Returns true when it drew, because there is nothing else to show until an +/// account exists. +/// +/// None of this is an error. The whole state means one thing: there is no +/// account yet, and linking one is a button away. +fn link_panel(app: &mut A, ui: &mut Ui) -> bool { + let Some(state) = app.cloud().link.clone() else { return false }; + let style = app.style(ui); + let noun = app.kind().noun; + let mut begin = false; + let mut cancel = false; + let mut browse_to: Option = None; + let words = LinkWords { + none_yet: app.tr("No cloud account is linked yet."), + why: app.tr(&format!("Link one to open and save {noun}s in your cloud storage.")), + link_one: app.tr("Link a cloud account"), + starting: app.tr("Starting…"), + finish: app.tr("Finish linking in your browser."), + waiting: app.tr("Waiting for your browser…"), + open_in_browser: app.tr("Open in browser"), + copy_link: app.tr("Copy link"), + cancel: app.tr("Cancel"), + again: app.tr("Try again"), + }; + egui::Frame::NONE.fill(style.soft).corner_radius(6.0).inner_margin(12).show(ui, |ui| match state { + Link::Offered => { + ui.label(RichText::new(&words.none_yet).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + dim(ui, &style, &words.why); + ui.add_space(8.0); + begin = ui.button(&words.link_one).clicked(); + } + Link::Starting => { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.starting); + }); + } + Link::Waiting { url, .. } => { + ui.label(RichText::new(&words.finish).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.waiting); + }); + ui.add_space(6.0); + // A link alone is not enough. When the browser cannot be opened, + // or opens the wrong thing, the only way out is carrying the + // address across by hand, and a label cannot be selected. + ui.horizontal(|ui| { + if ui.button(&words.open_in_browser).clicked() { + browse_to = Some(url.clone()); + } + if ui.button(&words.copy_link).clicked() { + ui.ctx().copy_text(url.clone()); + } + }); + ui.add_space(4.0); + if ui.link(&url).clicked() { + browse_to = Some(url.clone()); + } + ui.add_space(8.0); + cancel = ui.button(&words.cancel).clicked(); + } + Link::Failed(fault) => { + ui.label(RichText::new(fault.text(noun)).font(egui::FontId::new(13.0, style.family.clone())).color(style.text)); + ui.add_space(8.0); + begin = ui.button(&words.again).clicked(); + } + }); + if let Some(url) = browse_to { + app.open_url(&url); + } + if begin { + link(app); + } else if cancel { + app.cloud_mut().link = Some(Link::Offered); + } + true +} + +/// The panel's strings, read before it is drawn. The application is borrowed +/// mutably inside the frame, so nothing can be asked of it there. +struct LinkWords { + none_yet: String, + why: String, + link_one: String, + starting: String, + finish: String, + waiting: String, + open_in_browser: String, + copy_link: String, + cancel: String, + again: String, +} + +/// The progress line for a read or a write in flight. +pub fn progress(app: &A, ui: &mut Ui) { + let Some(busy) = app.cloud().busy.clone() else { return }; + let style = app.style(ui); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(15.0)); + ui.label(RichText::new(busy.text()).font(egui::FontId::new(12.5, style.family.clone())).color(style.text)); + }); +} + +/// The `…` beside a document, and what a person chose from it. +/// +/// Only the actions the provider actually offers appear. A greyed-out item says +/// the action exists and is not possible right now. An absent one says this +/// provider does not do that at all, and those are different facts. +fn row_actions(app: &A, ui: &mut Ui, entry: &Entry) -> Option { + let can = |c: Capability| app.cloud().account.as_ref().is_some_and(|a| a.can(c)); + let mut items = vec![crate::menu::MenuItem::new("open", app.tr("Open"))]; + if can(Capability::Sharing) { + items.push( + crate::menu::MenuItem::new("share", format!("{}{}", app.tr("Share"), ELLIPSIS)) + .detail(app.tr("See who this is shared with, and invite somebody")) + .separated(), + ); + } + if can(Capability::Conversation) { + items.push(crate::menu::MenuItem::new("talk", app.tr("Work together")).detail(app.tr("Open a conversation about this document"))); + } + let labels = crate::menu::MenuLabels { more: app.tr("More options"), ..Default::default() }; + // Salted by the handle. Two rows drawing the same control need two menus, + // and the handle is the one thing that differs between them. + ui.push_id(entry.id.clone(), |ui| crate::menu::overflow(ui, &items, &labels)).inner +} + +/// File › Open, the cloud part. Your own files sit on one side and what other +/// people shared with you sits on the other. +pub fn open_page(app: &mut A, ui: &mut Ui) { + start(app); + header(app, ui); + ui.add_space(8.0); + if link_panel(app, ui) { + return; + } + progress(app, ui); + // Hidden where the provider has no incoming shares at all. An empty list + // under that heading would read as a broken feature. + let shared_offered = app.cloud().account.as_ref().is_some_and(|a| a.can(Capability::SharedWithMe)); + if shared_offered && !app.cloud().shared.loaded && !app.cloud().shared.loading { + load_shared(app); + } + let mut pick: Option<(Entry, Source)> = None; + let mut go: Option = None; + let mut act: Option = None; + if shared_offered { + ui.columns(2, |columns| { + if let Some(ui) = columns.get_mut(0) { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + if let Some(ui) = columns.get_mut(1) { + shared_files(app, ui, &mut pick, &mut act); + } + }); + } else { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + match act { + // Sharing a document in the list, which is not the one that happens to + // be open. The dialog is told which. + Some(Act::Share(entry)) => app.sharing().open(entry.id.clone(), entry.name.clone()), + Some(Act::Talk(entry)) => converse(app, entry.id.clone()), + None => {} + } + if let Some(path) = go { + browse(app, &path); + } else if let Some((entry, source)) = pick { + app.cloud_mut().source = source; + open_entry(app, entry, None); + } + if let Some(status) = app.cloud().status.clone() { + let style = app.style(ui); + ui.add_space(10.0); + dim(ui, &style, &status); + } +} + +/// Your own files: where you are, a way up, then the folders and the documents +/// this application can open. +fn my_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, go: &mut Option, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let folder = app.cloud().mine.clone(); + let heading = app.tr("My files"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let nothing = app.tr(&format!("Nothing here that {} can open.", app.app_name())); + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + *go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in &folder.entries { + let is_folder = entry.kind == EntryKind::Folder; + if !is_folder && !opens(entry, kind) { + continue; + } + shown += 1; + let detail = if is_folder { String::new() } else { size_text(entry.size) }; + // A folder has nothing behind an ellipsis. Opening it is the only + // thing to do with one here. + let reserve = if is_folder { 0.0 } else { 26.0 }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, reserve).clicked(); + let chose = if is_folder { None } else { row_actions(app, ui, entry) }; + (row, chose) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + Some("open") => *pick = Some((entry.clone(), Source::Mine)), + _ if row => { + if is_folder { + *go = Some(entry.path.clone()); + } else { + *pick = Some((entry.clone(), Source::Mine)); + } + } + _ => {} + } + } + if shown == 0 && folder.loaded { + dim(ui, &style, ¬hing); + } + }); +} + +/// What other people shared with you. One flat list, because an incoming share +/// has no folder of yours to sit in. Each row says who shared it. +fn shared_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let shared = app.cloud().shared.clone(); + let heading = app.tr("Shared with me"); + let (loading, with_you, read_only) = (app.tr("Loading…"), app.tr("Shared with you"), app.tr("read-only")); + let nobody = app.tr(&format!("Nobody has shared a {} with you.", kind.noun)); + column(ui, &style, &heading, |ui| { + if shared.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &shared.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in shared.entries.iter().filter(|e| opens(e, kind)) { + shown += 1; + let who = entry.shared_by.clone().unwrap_or_else(|| with_you.clone()); + let detail = if entry.writable { who } else { format!("{who} ({read_only})") }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, 26.0).clicked(); + (row, row_actions(app, ui, entry)) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + _ if row || chose.is_some() => *pick = Some((entry.clone(), Source::Shared)), + _ => {} + } + } + if shown == 0 && shared.loaded { + dim(ui, &style, &nobody); + } + }); +} + +/// File › Save As, the cloud destination. Pick a folder, name the file, save. +/// Returns true when a save started, so a Backstage view can return to the +/// document. +pub fn save_page(app: &mut A, ui: &mut Ui) -> bool { + let style = app.style(ui); + let kind = app.kind(); + start(app); + // The destination above already names the account. This line is here to + // say when something is wrong with it. + if app.cloud().account.is_none() || app.cloud().account_fault.is_some() { + header(app, ui); + ui.add_space(8.0); + } + if link_panel(app, ui) { + return false; + } + progress(app, ui); + if app.cloud().save_name.is_empty() { + let suggested = app.active().map(|uid| app.title(uid)).unwrap_or_default(); + app.cloud_mut().save_name = document_name(&suggested, kind); + } + let folder = app.cloud().mine.clone(); + let heading = app.tr("Folder"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let only_folder = app.tr(&format!("No folders here. The {} saves in this one.", kind.noun)); + let mut go: Option = None; + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut folders = 0; + for entry in folder.entries.iter().filter(|e| e.kind == EntryKind::Folder) { + folders += 1; + if entry_row(app, ui, entry, "", 0.0).clicked() { + go = Some(entry.path.clone()); + } + } + if folders == 0 && folder.loaded { + dim(ui, &style, &only_folder); + } + }); + if let Some(path) = go { + browse(app, &path); + } + ui.add_space(12.0); + let (file_name, save_label) = (app.tr("File name"), app.tr("Save to the cloud")); + let mut asked = false; + ui.horizontal(|ui| { + ui.label(file_name); + let typing = ui.add(egui::TextEdit::singleline(&mut app.cloud_mut().save_name).desired_width(280.0)); + asked = typing.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)); + }); + ui.add_space(10.0); + let ready = app.cloud().busy.is_none() && !document_name(&app.cloud().save_name, kind).is_empty(); + if ui.add_enabled(ready, egui::Button::new(save_label)).clicked() { + asked = true; + } + if let Some(note) = app.save_note() { + ui.add_space(8.0); + dim(ui, &style, ¬e); + } + // A provider with no conditional writes cannot refuse one, so a save here + // can land on top of somebody else's. Said plainly, because the user is the + // only one who can decide whether that matters. + if app.cloud().account.as_ref().is_some_and(|a| !a.can(Capability::Etags)) { + let warning = app.tr("This cloud account cannot detect a save that would overwrite somebody else's changes."); + ui.add_space(4.0); + dim(ui, &style, &warning); + } + if asked && ready && app.ready_to_save() { + let (folder, name) = (app.cloud().mine.path.clone(), app.cloud().save_name.clone()); + match save_as(app, &folder, &name) { + Ok(_) => return true, + Err(error) => app.say(error), + } + } + false +} + +/// A save refused because the stored copy had moved on. +/// +/// Three ways out, and none of them throws anything away without saying so. +/// Reloading is the one a user usually wants, so it comes first. The text says +/// plainly that it discards their edits. +pub fn conflict_modal(app: &mut A, ctx: &egui::Context) { + let Some(conflict) = app.cloud().conflict.clone() else { return }; + let noun = app.kind().noun; + let words = ConflictWords { + title: app.tr(&format!("This {noun} was not saved")), + what: fill( + app, + "Somebody else saved {} while you were editing it. Nothing was written: saving now would overwrite their work.", + &conflict.entry.name, + ), + yours: app.tr("Your own changes are still open here. Reloading replaces them with the stored copy."), + reload: app.tr("Reload from the cloud"), + copy: app.tr(&format!("Save as a copy{ELLIPSIS}")), + keep: app.tr("Keep editing"), + }; + let mut reload = false; + let mut copy = false; + let mut dismiss = false; + egui::Modal::new(egui::Id::new("craft-ui/cloud/conflict")).show(ctx, |ui| { + let style = app.style(ui); + ui.set_width(430.0); + ui.label(RichText::new(&words.title).font(egui::FontId::new(15.0, style.bold.clone()))); + ui.add_space(8.0); + ui.add(egui::Label::new(&words.what).wrap()); + ui.add_space(6.0); + ui.add(egui::Label::new(&words.yours).wrap()); + ui.add_space(12.0); + ui.horizontal(|ui| { + reload = ui.button(&words.reload).clicked(); + copy = ui.button(&words.copy).clicked(); + dismiss = ui.button(&words.keep).clicked(); + }); + }); + if reload { + app.cloud_mut().conflict = None; + if let Err(error) = reload_active(app) { + app.say(error); + } + } else if copy { + let name = document_name(&format!("{} (copy)", stem_of(&conflict.entry.name)), app.kind()); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.save_name = name; + app.go_to_save_as(); + } else if dismiss { + app.cloud_mut().conflict = None; + } +} + +/// The modal's strings, read before it is drawn. +struct ConflictWords { + title: String, + what: String, + yours: String, + reload: String, + copy: String, + keep: String, +} diff --git a/crates/ui/src/cloud/tests.rs b/crates/ui/src/cloud/tests.rs new file mode 100644 index 000000000..875612144 --- /dev/null +++ b/crates/ui/src/cloud/tests.rs @@ -0,0 +1,573 @@ +//! The pages driven by an application that holds no documents. +//! +//! The point of these is the seam. A fake application answers every question +//! [`CloudApp`] asks and records what it was told to do, so what crosses the +//! boundary is visible without a spreadsheet, a service or a window. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; + +use super::*; + +/// Everything the fake application was asked to do. +#[derive(Default)] +struct Did { + opened: Vec, + closed: Vec, + encoded: Vec, + /// The name each encode was asked for, which is where the bytes go. + encoded_as: Vec, + /// The content type beside it, where the provider gave one. + encoded_mime: Vec>, + marked_saved: Vec, + dropped: Vec, + said: Vec, + toasted: Vec, + urls: Vec, + conversations: Vec, + went_to_save_as: usize, +} + +const NOTES: DocumentKind = + DocumentKind { extensions: &["note", "txt"], mimes: &["text/plain", "application/x-note"], noun: "note", default_extension: "note" }; + +struct Notebook { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + /// The document in the window, and what it is called. + open: Option<(u64, String)>, + /// What the next `open_bytes` answers with. + opens_as: Result, String>, + did: Arc>, +} + +impl Notebook { + fn new() -> Notebook { + Notebook { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + open: Some((1, "Untitled")).map(|(uid, name)| (uid, name.to_owned())), + opens_as: Ok(Some(1)), + did: Arc::new(Mutex::new(Did::default())), + } + } + + fn did(&self) -> std::sync::MutexGuard<'_, Did> { + self.did.lock().unwrap() + } +} + +impl CloudApp for Notebook { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTES + } + + fn active(&self) -> Option { + self.open.as_ref().map(|(uid, _)| *uid) + } + + fn title(&self, _uid: u64) -> String { + self.open.as_ref().map(|(_, name)| name.clone()).unwrap_or_default() + } + + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.did().opened.push(name.to_owned()); + self.opens_as.clone() + } + + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String> { + self.did().encoded.push(uid); + self.did().encoded_as.push(into.name.to_owned()); + self.did().encoded_mime.push(into.mime.map(str::to_owned)); + Ok(b"a note".to_vec()) + } + + fn close(&mut self, uid: u64) { + self.did().closed.push(uid); + } + + fn mark_saved(&mut self, uid: u64) { + self.did().marked_saved.push(uid); + } + + fn drop_pending(&mut self, uid: u64) { + self.did().dropped.push(uid); + } + + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, url: &str) { + self.did.lock().unwrap().urls.push(url.to_owned()); + } + + fn open_conversation(&self, url: &str) { + self.did.lock().unwrap().conversations.push(url.to_owned()); + } + + fn say(&mut self, text: String) { + self.did().said.push(text); + } + + fn toast(&mut self, text: String) { + self.did().toasted.push(text); + } + + fn go_to_save_as(&mut self) { + self.did().went_to_save_as += 1; + } + + fn app_name(&self) -> &str { + "Notes" + } +} + +/// A service that answers on the calling thread, so a job submitted during a +/// test is answered before the next line. +struct Service(Arc>>); + +impl CloudBackend for Service { + fn submit(&self, job: Job, post: Post) { + let answer = match &job { + Job::Account | Job::SignIn => Some(Event::Account(Ok(Account { + display: "Ada Lovelace".to_owned(), + capabilities: vec![Capability::Files, Capability::Etags], + provider_linked: true, + }))), + Job::List(path) => Some(Event::Listed { path: path.clone(), entries: Ok(vec![file("/Minutes.note"), folder("/Archive")]) }), + Job::Read { entry, into } => Some(Event::Read { entry: entry.clone(), into: *into, bytes: Ok(b"a note".to_vec()) }), + Job::Write { uid, entry, .. } => { + let mut stored = entry.clone(); + stored.etag = Some("v2".to_owned()); + Some(Event::Saved { uid: *uid, entry: Ok(stored) }) + } + _ => None, + }; + self.0.lock().unwrap().push(job); + if let Some(event) = answer { + post.send(event); + } + } +} + +fn file(path: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.rsplit('/').next().unwrap_or(path).to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(2048), + modified: None, + mime: None, + etag: Some("v1".to_owned()), + writable: true, + shared_by: None, + } +} + +fn folder(path: &str) -> Entry { + Entry { kind: EntryKind::Folder, size: None, etag: None, ..file(path) } +} + +/// One frame's worth of draining, with no window. +fn pumped(app: &mut Notebook, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + // Nothing is painted here, so the pass's textures go nowhere. egui insists + // they are accounted for rather than dropped on the floor. + ctx.end_pass().textures_delta.clear(); +} + +fn wired() -> (Notebook, Arc>>, egui::Context) { + let mut app = Notebook::new(); + let jobs = Arc::new(Mutex::new(Vec::new())); + app.cloud.connect(Service(jobs.clone())); + (app, jobs, egui::Context::default()) +} + +#[test] +fn nothing_is_offered_until_a_service_is_wired() { + let app = Notebook::new(); + assert!(!available(&app), "a build with no service offers nothing cloud-shaped"); + assert_eq!(report(&app)["available"], false); +} + +#[test] +fn the_account_is_asked_for_once_per_run() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + start(&mut app); + let asked = jobs.lock().unwrap().iter().filter(|j| matches!(j, Job::Account)).count(); + assert_eq!(asked, 1, "a frame that asks again would ask on every frame"); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["account"]["display"], "Ada Lovelace"); +} + +#[test] +fn only_the_documents_this_application_opens_are_offered() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let listing = report(&app); + assert_eq!(listing["entries"], serde_json::json!(["Minutes.note", "Archive"])); + assert_eq!(listing["openable"], serde_json::json!(["Minutes.note"]), "a folder is not something to open"); +} + +#[test] +fn a_content_type_opens_a_document_with_no_extension() { + let mut exported = file("/exported"); + exported.mime = Some("text/plain; charset=utf-8".to_owned()); + assert!(opens(&exported, NOTES), "a provider that gives no extension still says what the bytes are"); + let mut picture = file("/holiday"); + picture.mime = Some("image/png".to_owned()); + assert!(!opens(&picture, NOTES)); + assert!(!opens(&folder("/Archive"), NOTES), "a folder opens nothing"); +} + +#[test] +fn a_typed_name_becomes_a_file_name_of_this_applications_own_kind() { + assert_eq!(document_name(" Minutes ", NOTES), "Minutes.note"); + assert_eq!(document_name("Minutes.txt", NOTES), "Minutes.txt", "an extension this application opens is kept"); + assert_eq!(document_name("Minutes.v2", NOTES), "Minutes.v2.note", "an unknown suffix is part of the name"); + assert_eq!(document_name("/a/b/Minutes", NOTES), "Minutes.note", "a pasted path cannot become a folder"); + assert_eq!(document_name(" ", NOTES), ""); +} + +#[test] +fn walking_up_from_the_root_has_nowhere_to_go() { + assert_eq!(parent_of(""), None); + assert_eq!(parent_of("/Archive"), Some(String::new())); + assert_eq!(parent_of("/Archive/2026"), Some("/Archive".to_owned())); +} + +#[test] +fn opening_hands_the_bytes_to_the_application_and_remembers_the_entry() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(app.did().opened, vec!["Minutes.note".to_owned()], "the application alone turns bytes into a document"); + let origin = report(&app)["origin"].clone(); + assert_eq!(origin["id"], "/Minutes.note", "the opaque handle is kept for the save"); + assert_eq!(origin["etag"], "v1", "so is the version it was read at"); + assert_eq!(origin["room"], "room:/Minutes.note", "and the collaboration identity, which is not the handle"); +} + +#[test] +fn a_reload_closes_the_document_it_replaced_only_once_the_new_one_is_open() { + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Ok(Some(2)); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert_eq!(app.did().closed, vec![1], "the one it replaced is gone"); + assert_eq!(app.did().dropped, vec![1], "and so is whatever was recorded about saving it"); + + // A read the application could not use leaves the user's work where it was. + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Err("these bytes are not a note".to_owned()); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert!(app.did().closed.is_empty(), "nothing was closed, because nothing opened"); + assert_eq!(app.did().said, vec!["these bytes are not a note".to_owned()]); +} + +#[test] +fn a_document_the_application_took_elsewhere_is_not_announced() { + let (mut app, _jobs, ctx) = wired(); + // What an application answers while it prompts for a password. + app.opens_as = Ok(None); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["status"], serde_json::Value::Null); + assert_eq!(report(&app)["origin"], serde_json::Value::Null, "nothing came from the cloud yet"); +} + +#[test] +fn a_save_goes_out_under_the_version_the_document_was_read_at() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded, vec![1], "the application alone turns a document into bytes"); + assert_eq!(app.did().encoded_as, vec!["Minutes.note".to_owned()], "the bytes are asked for under the name they are going to"); + let condition = jobs.lock().unwrap().iter().find_map(|j| match j { + Job::Write { entry, .. } => Some(entry.etag.clone()), + _ => None, + }); + assert_eq!(condition, Some(Some("v1".to_owned())), "the etag it was read at is the condition"); + pumped(&mut app, &ctx); + assert_eq!(app.did().marked_saved, vec![1], "the version that reached the service is the saved one"); + assert_eq!(report(&app)["origin"]["etag"], "v2", "and the document moves on to the version the service returned"); +} + +#[test] +fn a_read_only_share_is_never_saved_over() { + let (mut app, _jobs, ctx) = wired(); + let mut theirs = file("/Team.note"); + theirs.writable = false; + open_entry(&mut app, theirs, None); + pumped(&mut app, &ctx); + assert!(!has_target(&app), "Save has nowhere of its own to go"); + let refused = save(&mut app).unwrap_err(); + assert!(refused.contains("reading only"), "and saying why names the fix: {refused}"); +} + +#[test] +fn a_refused_save_is_put_to_the_user_and_never_retried() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + jobs.lock().unwrap().clear(); + // What a service answers when somebody else saved first. + app.cloud.events.0.send(Event::Saved { uid: 1, entry: Err(Fault::Conflict) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["conflict"]["name"], "Minutes.note", "the user is told, and asked what to do"); + assert_eq!(app.did().dropped, vec![1], "the version that did not land is forgotten"); + assert!(jobs.lock().unwrap().is_empty(), "nothing went out again on its own"); +} + +#[test] +fn no_account_yet_is_an_offer_to_link_and_never_an_error() { + let (mut app, _jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Account(Err(Fault::NotLinked))).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["link"], "offered"); + assert_eq!(report(&app)["accountError"], serde_json::Value::Null, "not having linked an account yet is not a failure"); + assert!(app.did().said.is_empty()); +} + +#[test] +fn a_browser_round_trip_is_polled_until_the_user_is_done() { + let (mut app, jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Browser { url: "https://cloud.example/link/abc".to_owned(), handle: Some("abc".to_owned()) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(app.did().urls, vec!["https://cloud.example/link/abc".to_owned()], "the browser is opened for them"); + assert_eq!(report(&app)["link"]["waiting"], "https://cloud.example/link/abc"); + + // The wait is not polled again until it is due. + jobs.lock().unwrap().clear(); + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::LinkPoll(_))), "a poll every frame would be a poll every sixteen milliseconds"); + + if let Some(Link::Waiting { next_poll, .. }) = &mut app.cloud.link { + *next_poll = 0.0; + } + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::LinkPoll(_)))); +} + +#[test] +fn what_a_person_reads_is_about_their_own_kind_of_document() { + let app = Notebook::new(); + assert_eq!(Fault::Conflict.text(app.kind().noun), "Somebody else saved this note while you were editing it."); + assert_eq!(Fault::Conflict.code(), "conflict", "and the control channel reads the same fact as a word"); +} + +#[test] +fn working_together_needs_somewhere_for_the_room_to_be_keyed_on() { + let (mut app, jobs, ctx) = wired(); + app.cloud.account = Some(Account { display: "Ada".to_owned(), capabilities: vec![Capability::Conversation], provider_linked: true }); + assert!(can_converse(&app)); + // A document that has never been in the cloud has no handle. + work_together(&mut app); + assert_eq!(report(&app)["status"], "Save this note to the cloud first"); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::Conversation(_)))); + + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + work_together(&mut app); + let asked = jobs.lock().unwrap().iter().any(|j| matches!(j, Job::Conversation(id) if id == "/Minutes.note")); + assert!(asked, "the provider is asked about the handle it issued"); +} + +#[test] +fn a_conversation_uses_the_hosts_chat_opener() { + let (mut app, _, ctx) = wired(); + app.cloud + .events + .0 + .send(Event::Conversation(Ok(craft_cloud::Conversation { url: "https://cloud.example.net/call/room".to_owned(), name: "Talk".to_owned() }))) + .unwrap(); + + pumped(&mut app, &ctx); + + assert_eq!(app.did().conversations, ["https://cloud.example.net/call/room"]); + assert!(app.did().urls.is_empty(), "ordinary browser links and conversations remain separate host decisions"); +} + +#[test] +fn signing_out_forgets_everything_this_window_knew() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + sign_out(&mut app); + let state = report(&app); + assert_eq!(state["account"], serde_json::Value::Null); + assert_eq!(state["origin"], serde_json::Value::Null); + assert_eq!(state["entries"], serde_json::json!([])); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::SignOut)), "the service is told, so the saved token goes too"); +} + +#[test] +fn bytes_are_said_the_way_a_person_reads_them() { + assert_eq!(size_text(None), ""); + assert_eq!(size_text(Some(512)), "512 bytes"); + assert_eq!(size_text(Some(2048)), "2.0 KB"); + assert_eq!(size_text(Some(5 * 1024 * 1024)), "5.0 MB"); +} + +#[test] +fn a_destination_is_named_after_the_account_it_belongs_to() { + let mut app = Notebook::new(); + assert_eq!(destination_name(&app), "Cloud storage", "two entries reading the same tell nobody which account this is"); + app.cloud.account = Some(Account { display: "Ada Lovelace".to_owned(), capabilities: Vec::new(), provider_linked: true }); + assert_eq!(destination_name(&app), "Ada Lovelace"); +} + +#[test] +fn the_contracts_own_conflict_is_the_one_a_save_must_not_retry() { + assert_eq!(Fault::from(craft_cloud::Error::Conflict("Minutes.note".to_owned())), Fault::Conflict); + assert_eq!(Fault::from(craft_cloud::Error::Unauthenticated), Fault::Unauthenticated); + assert!(matches!(Fault::from(craft_cloud::Error::Unsupported("sharing")), Fault::Refused(_))); +} + +#[test] +fn a_save_asks_for_the_bytes_under_the_name_they_are_going_to() { + // A document opened as one format and saved in the application's own would + // hand the user a file no other application reads, under a name that says + // it is readable. The application cannot avoid that without being told + // where the bytes are going. + let (mut app, _jobs, ctx) = wired(); + let mut sheet = file("/figures.csv"); + sheet.mime = Some("text/csv".to_owned()); + open_entry(&mut app, sheet, None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded_as, vec!["figures.csv".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![Some("text/csv".to_owned())], "the provider's own word for it comes too"); + + // And Save As, where the name is the one just typed rather than the one + // the document arrived under. + let (mut app, _jobs, ctx) = wired(); + open_entry(&mut app, file("/figures.csv"), None); + pumped(&mut app, &ctx); + save_as(&mut app, "", "a copy.note").unwrap(); + assert_eq!(app.did().encoded_as, vec!["a copy.note".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![None], "nothing is there yet, so nothing says what it is"); +} + +#[test] +fn a_destination_reads_its_own_extension() { + assert_eq!(Destination::new("figures.csv").extension(), "csv"); + assert_eq!(Destination::new("FIGURES.CSV").extension(), "csv", "a shouted name is the same name"); + assert_eq!(Destination::new("report.2026.xlsx").extension(), "xlsx", "the last one wins"); + // A bare name, which is what a web application's export commonly has. + // Everything an application can learn is in the content type instead. + assert_eq!(Destination::new("exported").extension(), ""); + assert_eq!(Destination::new("trailing.").extension(), ""); +} + +// ---- somebody who followed a shared link ---------------------------------- + +/// One frame of the title bar's right-hand end, as the accessibility tree +/// reported it. +/// +/// Read off the tree rather than out of the state, because the question is +/// what a recipient can reach. A field saying "no menu" proves nothing about +/// what was drawn. +fn title_bar(app: &mut Notebook) -> Vec<(egui::accesskit::Role, String)> { + let ctx = egui::Context::default(); + ctx.enable_accesskit(); + let raw = egui::RawInput { screen_rect: Some(egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(400.0, 48.0))), ..Default::default() }; + let mut output = ctx.run_ui(raw, |ui| who(app, ui)); + output.textures_delta.clear(); + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| (node.role(), text.to_owned())) + }) + .collect() +} + +fn pressable(seen: &[(egui::accesskit::Role, String)]) -> Vec { + seen.iter().filter(|(role, _)| *role == egui::accesskit::Role::Button).map(|(_, text)| text.clone()).collect() +} + +fn reads(seen: &[(egui::accesskit::Role, String)], fragment: &str) -> bool { + seen.iter().any(|(_, text)| text.contains(fragment)) +} + +#[test] +fn a_recipient_is_named_and_offered_nothing() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", false); + let seen = title_bar(&mut app); + assert!(reads(&seen, "outsider@example.org"), "a recipient has no account, so their own address is the identity to show: {seen:?}"); + // The whole point. Every item an account menu holds is a sign-out, a + // switch or a storage connection, and a recipient has none of those. + assert_eq!(pressable(&seen), Vec::::new(), "nothing here may be pressed: {seen:?}"); + for offer in ["Sign in", "Sign out", "Account", "Connect storage", "Add an account"] { + assert!(!reads(&seen, offer), "a recipient was offered {offer}"); + } +} + +#[test] +fn a_read_only_share_says_so_before_anybody_tries_to_save() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", true); + assert!(reads(&title_bar(&mut app), "Reading only"), "finding out at the moment of saving means doing the work twice"); + + app.cloud.as_guest("outsider@example.org", false); + assert!(!reads(&title_bar(&mut app), "Reading only"), "a share that allows an edit must not say otherwise"); +} + +#[test] +fn an_address_of_only_spaces_leaves_no_badge() { + let mut app = Notebook::new(); + app.cloud.as_guest(" ", false); + assert!(app.cloud.guest().is_none(), "a badge with nothing on it reads as a fault"); + assert_eq!(title_bar(&mut app), Vec::new()); +} + +#[test] +fn a_signed_in_window_still_gets_its_account_badge() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let seen = title_bar(&mut app); + assert!(!pressable(&seen).is_empty(), "somebody with an account still has a menu to reach: {seen:?}"); + assert!(reads(&seen, "Ada Lovelace")); +} + +#[test] +fn the_report_says_who_this_window_is_for() { + let mut app = Notebook::new(); + assert_eq!(report(&app)["guest"], serde_json::Value::Null, "most windows belong to nobody in particular yet"); + app.cloud.as_guest("outsider@example.org", true); + assert_eq!(report(&app)["guest"], serde_json::json!({"recipient": "outsider@example.org", "readOnly": true})); +} diff --git a/crates/ui/src/cloud/title.rs b/crates/ui/src/cloud/title.rs new file mode 100644 index 000000000..2535caf68 --- /dev/null +++ b/crates/ui/src/cloud/title.rs @@ -0,0 +1,173 @@ +//! The right-hand end of a title bar, plus the Save As destination. +//! +//! Who is signed in, who else is here, and Share. Every office suite puts +//! these three in the same corner, in that order. A person coming from one of +//! them looks there first. + +use egui::{RichText, Ui}; + +use super::{CloudApp, CopyFormat, Guest, available, fill, link, origin, sign_in, sign_out, work_together}; + +/// Who this window is for. Who else is in the document, beside them. +/// +/// Three cases, each a different person. Somebody signed in gets the account +/// badge and its menu. Somebody who followed a shared link gets their own +/// address and no menu, having no account to manage. A build with no service +/// configured gets neither. A badge that cannot sign anybody in would be a +/// control that fails on use. +/// +/// Nothing is asked for here. Drawing a badge must not begin a sign-in: a +/// worker signs in before any job it is given, and it then blocks polling the +/// browser for minutes. Starting that from a paint call pops a browser open at +/// launch and leaves every later job queued behind it. Signing in is a gesture, +/// so it waits for a press. +pub fn who(app: &mut A, ui: &mut Ui) { + match app.cloud().guest().cloned() { + Some(guest) => shared_with(app, ui, &guest), + None => account(app, ui), + } + // Who else is here, beside whoever this window belongs to. Nothing is + // drawn while a person is working alone, which keeps a solitary document + // looking like one. + if app.presence().shared() { + ui.add_space(6.0); + app.presence().show(ui); + } +} + +/// Who a shared link was sent to, for somebody with no account anywhere. +/// +/// A label and not a button. Every item an account menu holds is a sign-out, a +/// switch or a storage connection, and a recipient has none of those. A +/// control that opens a menu of failures is worse than no control. +fn shared_with(app: &mut A, ui: &mut Ui, guest: &Guest) { + let explained = fill(app, "This document was shared with {}", &guest.recipient); + let reading = app.tr("Reading only"); + let dim = ui.visuals().weak_text_color(); + if guest.read_only { + // Said where the account would be. Both answer what this window may + // do with the document in it. A recipient who finds out at the moment + // of saving has already done the work twice. + ui.label(RichText::new(reading).small().color(dim)); + ui.add_space(6.0); + } + ui.label(RichText::new(guest.recipient.as_str()).small().color(dim)).on_hover_text(explained); +} + +/// The account badge and its menu, for somebody signed in. +fn account(app: &mut A, ui: &mut Ui) { + if !available(app) { + return; + } + let service = app.service(); + let known = app.cloud().account.as_ref().map(|a| crate::account::Account { + // One account for now. The control already holds a list, so a second + // deployment is a second entry here and nothing else changes. + id: "default".to_owned(), + display: a.display.clone(), + email: None, + service, + linked: a.provider_linked, + }); + let new_accounts: Vec<_> = known.into_iter().collect(); + let cloud = app.cloud_mut(); + if cloud.accounts.accounts() != new_accounts.as_slice() { + cloud.accounts.set(new_accounts); + } + cloud.accounts.show(ui); + + while let Some(action) = app.cloud_mut().accounts.take_action() { + use crate::account::AccountAction as Act; + match action { + // Signing in and connecting storage are two different things. + // Signing in is the device flow against the service, which every + // job already triggers when there is no token. Asking who the + // account is therefore starts it. Linking storage comes after, and + // needs that session to exist first. + Act::SignIn | Act::AddAccount => { + app.cloud_mut().sign_in_from_menu = true; + sign_in(app); + } + Act::Link(_) => link(app), + Act::SignOut(_) => sign_out(app), + // One account, so there is nothing to switch to yet. + Act::Use(_) => {} + Act::Manage(_) => { + let host = app.service(); + if !host.is_empty() { + app.open_url(&format!("https://{host}/account")); + } + } + } + } +} + +/// Whether the Share split button can be drawn. +/// +/// False until the service says the provider supports sharing. An application +/// draws whatever it offered before. A button that fails on use is worse than +/// no button at all. +pub fn shares(app: &mut A) -> bool { + app.sharing().available() +} + +/// Share, as a split button. +/// +/// Pressing the label shares, which is what somebody wants most of the time. +/// The chevron carries the variations, and working together is one of them. +/// `copies` are the application's own Save a Copy formats. Those have nothing +/// in common between one application and the next. +/// +/// Answers with the identifier of a copy format, when that is what was chosen. +/// Everything else is carried out here. +pub fn share_button(app: &mut A, ui: &mut Ui, copies: &[CopyFormat]) -> Option { + let noun = app.kind().noun; + let mut items = Vec::new(); + if app.cloud().can_converse() { + let detail = app.tr(&format!("Open a chat about this {noun}")); + items.push(crate::menu::MenuItem::new("talk", app.tr("Open chat")).detail(detail)); + } + for (at, copy) in copies.iter().enumerate() { + let item = crate::menu::MenuItem::new(copy.id.clone(), copy.label.clone()); + // A rule above the first copy, so sharing and exporting read as two + // groups rather than one long list. + items.push(if at == 0 && !items.is_empty() { item.separated() } else { item }); + } + let labels = crate::menu::MenuLabels::default(); + let primary = app.tr("Share"); + match crate::menu::split(ui, &primary, &items, &labels)? { + crate::menu::SplitHit::Primary => { + // The handle the provider issued, which is what a share is about. + // A document that has never been in the cloud has none, and the + // dialog says so. + let (id, title) = match origin(app) { + Some(origin) => (origin.entry.id.clone(), origin.entry.name.clone()), + None => (String::new(), app.active().map(|uid| app.title(uid)).unwrap_or_default()), + }; + app.sharing().open(id, title); + None + } + crate::menu::SplitHit::Item(what) if what == "talk" => { + work_together(app); + None + } + crate::menu::SplitHit::Item(format) => Some(format), + } +} + +/// What to call the cloud destination on a Save As page. +/// +/// The account's own name. The destination then reads as the user's own +/// storage. Somebody with an account on two deployments needs to know which +/// one a document is about to land in. +pub fn destination_name(app: &A) -> String { + app.cloud().account.as_ref().map(|a| a.display.clone()).filter(|display| !display.is_empty()).unwrap_or_else(|| app.tr("Cloud storage")) +} + +/// Whether the cloud destination is the one to offer first. +/// +/// A document that came from the cloud is saved back there unless the user says +/// otherwise. One that came from this computer is not. +pub fn prefers_cloud(app: &A) -> bool { + available(app) && origin(app).is_some() +} diff --git a/crates/ui/src/lib.rs b/crates/ui/src/lib.rs index bbdd912ac..0c6d42740 100644 --- a/crates/ui/src/lib.rs +++ b/crates/ui/src/lib.rs @@ -5,9 +5,13 @@ //! Applications own their assets, themes, layouts, commands and document semantics. Components //! accept focused style values and return egui responses; no application engine is required. +#[cfg(feature = "share")] +pub mod account; pub mod backdrop; pub mod buttons; pub mod capture; +#[cfg(feature = "cloud")] +pub mod cloud; pub mod combo; pub mod direction; pub mod docking; @@ -17,9 +21,13 @@ pub mod icons; pub mod ime; pub mod layout; pub mod localized; +pub mod menu; pub mod panes; +pub mod presence; pub mod printing; pub mod shapes; +#[cfg(feature = "share")] +pub mod share; pub mod tabs; #[cfg(all(feature = "screen-testing", not(target_arch = "wasm32")))] pub mod testing; diff --git a/crates/ui/src/menu.rs b/crates/ui/src/menu.rs new file mode 100644 index 000000000..2b18340bf --- /dev/null +++ b/crates/ui/src/menu.rs @@ -0,0 +1,222 @@ +//! The two controls that offer more than one action. +//! +//! An overflow menu is the `…` that holds what did not earn a place on the +//! toolbar. A split button is a primary action with a chevron beside it, where +//! the chevron offers the variations. Share is the usual example. Most of the +//! time a person wants to share, and once in a while they want to copy a link +//! or start a call about the document instead. +//! +//! They are one module because they are the same control underneath. Building +//! them twice would mean getting the accessible naming right twice, and an +//! icon-only button that announces itself as an ellipsis character is useless +//! to anybody reading the screen rather than looking at it. +//! +//! Neither control knows what any item does. Each answers with the identifier +//! of the item a person chose. The application holds the meaning. + +use egui::{Response, RichText, Ui}; + +/// One line in a menu. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MenuItem { + /// What the caller recognises this by. Never shown. + pub id: String, + pub label: String, + /// A second line, smaller. Worth having where the label alone leaves a + /// person guessing what the action will do to their document. + pub detail: Option, + /// A leading glyph. Decoration only, so it is never the accessible name. + pub icon: Option, + pub enabled: bool, + /// Draw a rule above this item. A group of related actions reads as a + /// group only when something separates it from the last one. + pub separator_before: bool, +} + +impl MenuItem { + pub fn new(id: impl Into, label: impl Into) -> MenuItem { + MenuItem { id: id.into(), label: label.into(), enabled: true, ..MenuItem::default() } + } + + pub fn detail(mut self, detail: impl Into) -> MenuItem { + self.detail = Some(detail.into()); + self + } + + pub fn icon(mut self, icon: impl Into) -> MenuItem { + self.icon = Some(icon.into()); + self + } + + /// Present but unavailable, with a reason on hover. + /// + /// Greying an item out says the action exists and is not possible now. + /// Removing it says the action does not exist. They are different facts and + /// a person reads them differently. + pub fn disabled(mut self, why: impl Into) -> MenuItem { + self.enabled = false; + self.detail = Some(why.into()); + self + } + + pub fn separated(mut self) -> MenuItem { + self.separator_before = true; + self + } +} + +/// What a person did to a split button. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum SplitHit { + /// They pressed the button itself. + Primary, + /// They chose something from the chevron's menu. + Item(String), +} + +/// The accessible name of the chevron, and of the overflow button. +/// +/// Public so an application can translate them. A glyph is not a name, and +/// these two are the only strings in this module that are not supplied by the +/// caller. +#[derive(Clone, Debug)] +pub struct MenuLabels { + /// The `…` button. + pub more: String, + /// The chevron on a split button. `{action}` is replaced with the primary + /// action's own label, so a screen reader says "more share options" rather + /// than "more options" on a toolbar holding four of them. + pub more_for: String, +} + +impl Default for MenuLabels { + fn default() -> MenuLabels { + MenuLabels { more: "More options".into(), more_for: "More {action} options".into() } + } +} + +/// The `…` button and its menu. +/// +/// Answers with the identifier of the item chosen, if any. +pub fn overflow(ui: &mut Ui, items: &[MenuItem], labels: &MenuLabels) -> Option { + // A horizontal ellipsis, not three periods. Three periods are three + // characters to anything reading the screen aloud. + let button = egui::Button::new(RichText::new("\u{2026}").size(15.0)).frame(false); + let hit = ui.add(button); + let name = labels.more.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + let hit = hit.on_hover_text(labels.more.as_str()); + items_of(&hit, items) +} + +/// A primary action with a chevron beside it. +/// +/// The two halves are two controls. Pressing the label does the thing. Pressing +/// the chevron offers the variations. One control that did both would leave a +/// person guessing which half they had hit. +pub fn split(ui: &mut Ui, primary: &str, items: &[MenuItem], labels: &MenuLabels) -> Option { + let mut hit = None; + ui.horizontal(|ui| { + // The halves touch, so they read as one control with two parts. Square + // off the inside corners as well. Two default radii leave a pair of + // notches at the seam, which reads as two buttons that happen to abut. + ui.spacing_mut().item_spacing.x = 0.0; + let radius = ui.visuals().widgets.inactive.corner_radius; + // A toolbar that fills from its right edge hands this control a + // right-to-left layout, and whatever is added first lands furthest + // right. The label still belongs before the chevron, so the halves are + // added in the order that puts them there. + let backwards = ui.layout().main_dir() == egui::Direction::RightToLeft; + let (outer, inner) = if backwards { + (egui::CornerRadius { nw: 0, sw: 0, ..radius }, egui::CornerRadius { ne: 0, se: 0, ..radius }) + } else { + (egui::CornerRadius { ne: 0, se: 0, ..radius }, egui::CornerRadius { nw: 0, sw: 0, ..radius }) + }; + let label = |ui: &mut Ui, hit: &mut Option| { + if ui.add(egui::Button::new(primary).corner_radius(if backwards { inner } else { outer })).clicked() { + *hit = Some(SplitHit::Primary); + } + }; + let chevron = |ui: &mut Ui, hit: &mut Option| { + // Room for the triangle, which is painted rather than typed. + let more = ui.add(egui::Button::new(" ").corner_radius(if backwards { outer } else { inner })); + crate::buttons::chevron(ui, more.rect, ui.visuals().text_color()); + let name = labels.more_for.replace("{action}", &primary.to_lowercase()); + more.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + let more = more.on_hover_text(name.as_str()); + if let Some(id) = items_of(&more, items) { + *hit = Some(SplitHit::Item(id)); + } + }; + if backwards { + chevron(ui, &mut hit); + label(ui, &mut hit); + } else { + label(ui, &mut hit); + chevron(ui, &mut hit); + } + }); + hit +} + +/// The menu both controls open. +fn items_of(anchor: &Response, items: &[MenuItem]) -> Option { + let mut chosen = None; + egui::Popup::menu(anchor).show(|ui| { + ui.set_min_width(210.0); + let weak = ui.visuals().weak_text_color(); + for item in items { + if item.separator_before { + ui.separator(); + } + let label = match &item.icon { + Some(icon) => format!("{icon} {}", item.label), + None => item.label.clone(), + }; + let row = ui.add_enabled(item.enabled, egui::Button::new(label).frame(false)); + // The icon is decoration. The name is the label alone. + let name = item.label.clone(); + let enabled = item.enabled; + row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, enabled, name.as_str())); + if row.clicked() { + chosen = Some(item.id.clone()); + ui.close(); + } + if let Some(detail) = &item.detail { + ui.label(RichText::new(detail.as_str()).small().color(weak)); + ui.add_space(2.0); + } + } + }); + chosen +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_item_is_enabled_until_it_is_not() { + assert!(MenuItem::new("copy", "Copy link").enabled); + let off = MenuItem::new("copy", "Copy link").disabled("this server forbids public links"); + assert!(!off.enabled); + assert_eq!(off.detail.as_deref(), Some("this server forbids public links")); + } + + #[test] + fn the_chevrons_name_says_which_action_it_belongs_to() { + let labels = MenuLabels::default(); + assert_eq!(labels.more_for.replace("{action}", "share"), "More share options"); + } + + #[test] + fn a_builder_keeps_what_it_was_given() { + let item = MenuItem::new("talk", "Work together").icon("\u{1f4de}").detail("Start a call").separated(); + assert_eq!(item.id, "talk"); + assert_eq!(item.label, "Work together"); + assert_eq!(item.icon.as_deref(), Some("\u{1f4de}")); + assert_eq!(item.detail.as_deref(), Some("Start a call")); + assert!(item.separator_before); + assert!(item.enabled); + } +} diff --git a/crates/ui/src/presence.rs b/crates/ui/src/presence.rs new file mode 100644 index 000000000..1da9327d9 --- /dev/null +++ b/crates/ui/src/presence.rs @@ -0,0 +1,424 @@ +//! Who else is in the document. +//! +//! A person editing alone and a person editing alongside three colleagues are +//! in very different situations. Only one of them has to worry about somebody +//! else changing the cell they are about to type in. An application that shows +//! nothing leaves them to find out by surprise. +//! +//! So this is a row of badges, one per person, with the count folded into a +//! final badge once the row would get long. It is the same control every +//! collaborative editor puts in the same corner, for the same reason. +//! +//! A peer's colour comes from the peer's own identifier. Two things need to +//! agree on it: the badge here, and whatever the document draws at that +//! person's cursor. Deriving it rather than assigning it means they agree with +//! no state passed between them, and the colour survives a reconnection. + +use egui::{Align, Color32, Layout, Response, RichText, Ui}; + +/// How wide a badge is, and how far the next one overlaps it. +const BADGE: f32 = 24.0; +const OVERLAP: f32 = 7.0; + +/// Somebody else in the document right now. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Peer { + /// The session's own identifier, stable for as long as they are connected. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + /// Where they are working, when the document can say. A spreadsheet knows + /// the cell. A word processor knows the page. Shown on hover only. + pub at: Option, +} + +impl Peer { + pub fn new(id: impl Into, display: impl Into) -> Peer { + Peer { id: id.into(), display: display.into(), at: None } + } + + /// Where they are working, for the tooltip. + pub fn at(mut self, at: impl Into) -> Peer { + self.at = Some(at.into()); + self + } + + /// The letter on the badge. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } + + /// This peer's colour. + pub fn colour(&self) -> Color32 { + colour_for(&self.id) + } +} + +/// How many colours the wheel carries. +/// +/// Sixteen, spaced evenly. More than that and neighbouring slots stop being +/// distinguishable, which defeats the point of having them. +pub const SLOTS: usize = 16; + +/// The colour in one slot of the wheel. +pub fn slot(index: usize) -> Color32 { + let step = 360.0 / SLOTS as f32; + // Alternate the lightness as the wheel turns, so two neighbouring hues are + // also two different weights. Hue alone is not enough for anybody who sees + // colour differently from the person who chose it. + let dim = index % 2 == 1; + hsv((index % SLOTS) as f32 * step, if dim { 0.66 } else { 0.52 }, if dim { 0.68 } else { 0.84 }) +} + +/// Which slot an identifier would like. +fn preferred(id: &str) -> usize { + // FNV-1a, which is small and has no dependency. + let mut hash: u32 = 0x811c_9dc5; + for byte in id.as_bytes() { + hash ^= u32::from(*byte); + hash = hash.wrapping_mul(0x0100_0193); + } + // Then an avalanche. FNV alone leaves keys that differ in one byte close + // together, and session ids from one relay run in sequence. + hash ^= hash >> 16; + hash = hash.wrapping_mul(0x7feb_352d); + hash ^= hash >> 15; + hash = hash.wrapping_mul(0x846c_a68b); + hash ^= hash >> 16; + hash as usize % SLOTS +} + +/// A stable colour for one identifier, with nobody else to consider. +/// +/// Public because the badge is not the only thing that needs it. Use +/// [`colours_for`] wherever a whole room is on screen. This one cannot promise +/// anything about the other people in it. +pub fn colour_for(id: &str) -> Color32 { + slot(preferred(id)) +} + +/// Colours for a whole room, every one distinguishable from the others. +/// +/// Each peer prefers the slot its identifier hashes to. A peer whose slot is +/// already taken moves to the next free one, walking the list in a fixed order +/// so the answer does not depend on who connected first. +/// +/// A document drawing remote cursors calls this with the same identifiers and +/// gets the same answer, which is what makes a cursor and the badge above it +/// the same person. That holds on one screen whatever else is happening, +/// since both calls see that client's own list. +/// +/// Two clients mid-transition can disagree for a frame or two. One has seen +/// somebody join and the other has not, so the walk resolves differently +/// until both lists match. It settles by itself, and nobody is comparing two +/// screens while it does. The durable fix is for the relay to hand out slots +/// with the peer list, which takes a protocol change. +/// +/// Beyond [`SLOTS`] peers the wheel repeats, since there is no seventeenth +/// colour anybody could tell from the first sixteen. +pub fn colours_for(ids: &[String]) -> Vec { + let mut order: Vec = (0..ids.len()).collect(); + order.sort_by(|a, b| ids[*a].cmp(&ids[*b])); + + let mut taken = [false; SLOTS]; + let mut out = vec![Color32::BLACK; ids.len()]; + for position in order { + let want = preferred(&ids[position]); + let mut at = want; + for step in 0..SLOTS { + at = (want + step) % SLOTS; + if !taken[at] { + break; + } + } + taken[at] = true; + out[position] = slot(at); + } + out +} + +fn hsv(hue: f32, saturation: f32, value: f32) -> Color32 { + let c = value * saturation; + let h = hue / 60.0; + let x = c * (1.0 - ((h % 2.0) - 1.0).abs()); + let (r, g, b) = match h as u32 { + 0 => (c, x, 0.0), + 1 => (x, c, 0.0), + 2 => (0.0, c, x), + 3 => (0.0, x, c), + 4 => (x, 0.0, c), + _ => (c, 0.0, x), + }; + let m = value - c; + let to_byte = |f: f32| (f.clamp(0.0, 1.0) * 255.0).round() as u8; + Color32::from_rgb(to_byte(r + m), to_byte(g + m), to_byte(b + m)) +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct PresenceLabels { + /// Said when nobody else is here. An application may leave this empty to + /// draw nothing at all in that case. + pub alone: String, + /// With one other person. `{name}` is replaced. + pub with_one: String, + /// With several. `{count}` is replaced. + pub with_many: String, + /// The badge that stands for the people who did not fit. `{count}` is + /// replaced. + pub and_more: String, + /// The accessible name of the whole row. + pub who: String, +} + +impl Default for PresenceLabels { + fn default() -> PresenceLabels { + PresenceLabels { + alone: String::new(), + with_one: "Editing with {name}".into(), + with_many: "Editing with {count} others".into(), + and_more: "{count} more".into(), + who: "Who is here".into(), + } + } +} + +/// The row of badges. +#[derive(Clone)] +pub struct PresenceBar { + peers: Vec, + /// How many badges to draw before folding the rest into a count. Four is + /// what fits beside a title bar without crowding it. + shown: usize, + labels: PresenceLabels, + /// Whether to write the sentence beside the badges. A narrow toolbar wants + /// the badges alone. + summary: bool, +} + +impl Default for PresenceBar { + fn default() -> PresenceBar { + PresenceBar::new() + } +} + +impl PresenceBar { + pub fn new() -> PresenceBar { + PresenceBar { peers: Vec::new(), shown: 4, labels: PresenceLabels::default(), summary: true } + } + + pub fn with_labels(mut self, labels: PresenceLabels) -> PresenceBar { + self.labels = labels; + self + } + + /// How many badges before the row folds into a count. + pub fn with_shown(mut self, shown: usize) -> PresenceBar { + self.shown = shown.max(1); + self + } + + /// Draw the badges only, with no sentence beside them. + pub fn badges_only(mut self) -> PresenceBar { + self.summary = false; + self + } + + /// Replace the set of people in the document. + /// + /// Takes the whole set rather than a change, because a session that missed + /// a departure would otherwise show somebody who left until the next + /// reconnection. + pub fn set(&mut self, peers: Vec) { + self.peers = peers; + } + + pub fn peers(&self) -> &[Peer] { + &self.peers + } + + /// Whether anybody else is here. An application draws nothing when this is + /// false, which keeps a solitary document looking like one. + pub fn shared(&self) -> bool { + !self.peers.is_empty() + } + + /// What the row says in words. Also the accessible summary. + pub fn summary(&self) -> String { + match self.peers.len() { + 0 => self.labels.alone.clone(), + 1 => self.peers.first().map(|p| self.labels.with_one.replace("{name}", &p.display)).unwrap_or_default(), + n => self.labels.with_many.replace("{count}", &n.to_string()), + } + } + + /// Draw it. Answers with the peer a person clicked, when they clicked one. + /// + /// A click is worth answering because a name is where "take me to what + /// they are editing" belongs. The application decides whether it can. + pub fn show(&mut self, ui: &mut Ui) -> Option { + if self.peers.is_empty() { + if !self.labels.alone.is_empty() { + ui.label(RichText::new(self.labels.alone.as_str()).small().color(ui.visuals().weak_text_color())); + } + return None; + } + + let mut clicked = None; + ui.horizontal(|ui| { + // Badges overlap, the way a stack of cards does. Without it four + // circles read as four separate controls instead of one group. + ui.spacing_mut().item_spacing.x = -OVERLAP; + // Right to left, so the first person sits on top of the stack. + // + // Allocated to just the width the badges need. A right-to-left + // layout given the whole container takes it, which pushes the row + // to the far edge of a toolbar and strands the sentence after it. + let shown = self.peers.len().min(self.shown); + let hidden = self.peers.len().saturating_sub(self.shown); + let count = shown + usize::from(hidden > 0); + let width = BADGE + (count.saturating_sub(1) as f32) * (BADGE - OVERLAP); + ui.allocate_ui_with_layout(egui::vec2(width, BADGE), Layout::right_to_left(Align::Center), |ui| { + if hidden > 0 { + let more = self.labels.and_more.replace("{count}", &hidden.to_string()); + let weak = ui.visuals().widgets.inactive.bg_fill; + let badge = badge(ui, &format!("+{hidden}"), weak, ui.visuals().text_color()); + badge.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, more.as_str())); + badge.on_hover_text(self.peers.iter().skip(self.shown).map(|p| p.display.as_str()).collect::>().join("\n")); + } + let ids: Vec = self.peers.iter().map(|p| p.id.clone()).collect(); + let colours = colours_for(&ids); + for (at, peer) in self.peers.iter().enumerate().take(self.shown).rev() { + let ink = colours.get(at).copied().unwrap_or_else(|| peer.colour()); + let hit = badge(ui, &peer.initial(), ink, Color32::WHITE); + let name = peer.display.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + let tip = match &peer.at { + Some(at) => format!("{}\n{at}", peer.display), + None => peer.display.clone(), + }; + if hit.on_hover_text(tip).clicked() { + clicked = Some(peer.id.clone()); + } + } + }); + if self.summary { + ui.spacing_mut().item_spacing.x = 8.0; + ui.label(RichText::new(self.summary()).small().color(ui.visuals().weak_text_color())); + } + }); + clicked + } +} + +/// One round badge. Painted as a button so it is focusable and announces +/// itself, which a bare circle would not. +fn badge(ui: &mut Ui, text: &str, fill: Color32, ink: Color32) -> Response { + let button = egui::Button::new(RichText::new(text).color(ink).size(11.0).strong()) + .fill(fill) + .corner_radius(BADGE / 2.0) + .min_size(egui::vec2(BADGE, BADGE)) + .stroke(egui::Stroke::new(1.5, ui.visuals().panel_fill)); + ui.add(button) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_colour_is_the_same_every_time_for_the_same_peer() { + assert_eq!(colour_for("session-a"), colour_for("session-a")); + } + + /// How far apart two colours are, summed over the channels. Crude, and + /// enough to tell "two different oranges" from "orange and teal". + fn apart(a: Color32, b: Color32) -> i32 { + (i32::from(a.r()) - i32::from(b.r())).abs() + (i32::from(a.g()) - i32::from(b.g())).abs() + (i32::from(a.b()) - i32::from(b.b())).abs() + } + + fn ids(of: &[&str]) -> Vec { + of.iter().map(|s| (*s).to_owned()).collect() + } + + #[test] + fn a_room_of_sequential_ids_is_a_room_of_distinguishable_colours() { + // The shape a relay actually hands out. A colour derived from one id + // alone cannot promise this, which is how six people came out looking + // like two. + let room = ids(&["s1", "s2", "s3", "s4", "s5", "s6"]); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + let distance = apart(*a, *b); + assert!(distance >= 60, "{} and {} are {distance} apart", room[i], room[j]); + } + } + } + + #[test] + fn a_full_wheel_is_still_all_distinct() { + let room: Vec = (0..SLOTS).map(|n| format!("session-{n}")).collect(); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + assert!(apart(*a, *b) > 0, "{} and {} share a colour", room[i], room[j]); + } + } + } + + #[test] + fn the_same_room_always_gets_the_same_colours() { + let room = ids(&["b", "a", "c"]); + assert_eq!(colours_for(&room), colours_for(&room)); + } + + #[test] + fn the_answer_does_not_depend_on_who_connected_first() { + let one = colours_for(&ids(&["a", "b", "c"])); + let other = colours_for(&ids(&["c", "b", "a"])); + // Same people, listed backwards. Each still gets the colour it had. + assert_eq!(one, other.into_iter().rev().collect::>()); + } + + #[test] + fn a_colour_is_dark_enough_to_hold_white_text() { + for id in ["a", "b", "zzz", "session-41", "", "\u{1f600}"] { + let c = colour_for(id); + // Rec. 601 luma, which is what readability of white ink tracks. + let luma = 0.299 * f32::from(c.r()) + 0.587 * f32::from(c.g()) + 0.114 * f32::from(c.b()); + assert!(luma < 200.0, "{id:?} gave a colour too pale for white text, luma {luma}"); + } + } + + #[test] + fn an_empty_room_is_not_shared_and_says_nothing() { + let bar = PresenceBar::new(); + assert!(!bar.shared()); + assert_eq!(bar.summary(), ""); + } + + #[test] + fn one_other_person_is_named_and_several_are_counted() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.summary(), "Editing with Ann Reed"); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + assert_eq!(bar.summary(), "Editing with 2 others"); + } + + #[test] + fn a_departure_leaves_nobody_behind() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.peers().len(), 1, "the whole set replaces the old one"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(Peer::new("1", "ann").initial(), "A"); + assert_eq!(Peer::new("1", "").initial(), "?"); + assert_eq!(Peer::new("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/ui/src/share/backend.rs b/crates/ui/src/share/backend.rs new file mode 100644 index 000000000..5c0981834 --- /dev/null +++ b/crates/ui/src/share/backend.rs @@ -0,0 +1,170 @@ +//! Where the share dialog's work happens, which is never on the frame. +//! +//! Every call a share needs is blocking, and a blocking call inside `update()` +//! freezes the window for as long as the server takes. So the dialog states +//! what it wants and reads answers off a channel, and something behind this +//! trait does the waiting. +//! +//! The dialog itself opens no socket, which keeps it buildable for the web +//! and testable with no server. A host supplies the half that does, and this +//! crate never learns what it reaches. + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; + +/// One thing the dialog needs done. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Request { + /// What the provider behind the service can actually do. + Capabilities, + /// People matching what has been typed so far. + Lookup { query: String, limit: usize }, + /// Who already has access to one document. + Access { id: String }, + /// Give several people access at once. + Grant(Grant), + /// Take one existing share away. + Withdraw { share_id: String }, + /// Where this document could be saved, so it can be shared. + /// + /// Asked for only when there is nothing to share yet. A list rather than a + /// single answer, because more than one provider may be configured and the + /// user picks. + Destinations, + /// Link an account for a destination that is configured but not connected. + Link { destination: String }, + /// One contact's picture, by the URL that contact carried. + /// + /// A separate request because a search answering with ten people must not + /// cost ten pictures before anybody has looked at them. The dialog asks + /// for a picture when it first paints the row that needs it, once per URL. + Avatar { url: String }, +} + +/// A share to create, as the dialog has it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Grant { + /// A key the recipient must present. Only meaningful for a link share, and + /// refused by a server that does not allow one. + pub password: Option, + /// The document, as an opaque handle the app was given. + pub id: String, + pub targets: Vec, + pub permission: Permission, + pub note: Option, + pub notify: bool, +} + +/// What came back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Answer { + Capabilities { + capabilities: Vec, + /// Whether this user has a cloud account attached at all. + linked: bool, + }, + Lookup(Vec), + Access(Vec), + /// Partial success is the ordinary case, so both halves come back. + Granted { + shared: Vec, + failed: Vec, + }, + Withdrawn { + share_id: String, + }, + Destinations(Vec), + /// An account was linked, so the destinations are worth asking for again. + Linked, + Avatar { + url: String, + /// Encoded image bytes, in whatever format the server sent. Decoding + /// is egui's image loaders' job, which the application installs. + bytes: Vec, + }, +} + +/// Somewhere a document could be saved. +/// +/// `account` is what makes this choosable. Two entries reading "Cloud" tell +/// nobody which of their accounts a document is about to land in, which is the +/// one thing somebody needs to know before pressing it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Destination { + /// Opaque to the dialog, handed back with the save. + pub id: String, + /// What to show, such as the service's own name. + pub name: String, + /// Which account, when one is linked. + pub account: Option, + /// False when the destination is configured but has no account yet. The + /// dialog offers a sign-in rather than a save. + pub linked: bool, +} + +/// One recipient a share did not reach. +/// +/// Named rather than counted. Sharing with five people where one address is +/// wrong shares with four and says which one failed. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Failure { + pub target: ShareTarget, + pub code: String, + pub detail: String, +} + +/// Where one answer goes. +/// +/// Carries the sequence number of the request it answers. Autocomplete fires +/// per keystroke, and a service is free to answer the third query before the +/// second, so the dialog keeps the newest sequence it asked for and drops +/// anything older. Without that the list flickers between a stale set of +/// matches and a current one. +pub struct Replier { + seq: u64, + tx: std::sync::mpsc::Sender<(u64, Result)>, +} + +impl Replier { + pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result)>) -> Replier { + Replier { seq, tx } + } + + /// Which request this answers. + pub fn seq(&self) -> u64 { + self.seq + } + + /// Another handle to the same answer slot, for a backend that has to give + /// up after moving the first one into a worker. + pub fn dup(&self) -> Replier { + Replier { seq: self.seq, tx: self.tx.clone() } + } + + pub fn answer(self, answer: Answer) { + self.deliver(Ok(answer)); + } + + /// Say why it could not be done, in words a user can read. + pub fn refuse(self, reason: impl Into) { + self.deliver(Err(reason.into())); + } + + /// A dropped receiver means the dialog closed, which is not a failure. + fn deliver(self, result: Result) { + let _ = self.tx.send((self.seq, result)); + } +} + +impl std::fmt::Debug for Replier { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Replier").field("seq", &self.seq).finish() + } +} + +/// Somewhere a [`Request`] can run without blocking a frame. +/// +/// `submit` must return immediately. The answer arrives through `reply` +/// whenever it is ready, or never, which the dialog survives. +pub trait ShareBackend { + fn submit(&self, request: Request, reply: Replier); +} diff --git a/crates/ui/src/share/mod.rs b/crates/ui/src/share/mod.rs new file mode 100644 index 000000000..5dbcf6c06 --- /dev/null +++ b/crates/ui/src/share/mod.rs @@ -0,0 +1,1465 @@ +//! One share dialog, the same one in every Craft app. +//! +//! What it offers is what a person asks for when they say "share this": pick +//! several people by typing a few letters of a name, choose whether they may +//! look or change, add a note, decide whether an email goes out, and see who +//! already has access so one of them can be taken away again. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`ShareBackend`], and +//! nothing here reaches the network. A host writes the backend, and this +//! module never learns what it talks to. +//! this file. +//! +//! Nothing here blocks. Answers arrive on a channel and are read once per +//! frame. Autocomplete waits [`DEBOUNCE`] after the last keystroke before it +//! asks anything, and an answer to a query the user has already typed past is +//! dropped rather than painted, so the list cannot flicker backwards. +//! +//! Nothing here is assumed about the provider. [`ShareDialog::available`] is +//! false until the service says sharing exists, and an app hides its Share +//! control rather than offering a button that fails. Contacts and mail are +//! reported separately and are hidden the same way. + +use std::collections::HashMap; +use std::sync::mpsc::{Receiver, Sender}; +use std::time::Duration; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use egui::{Align, Align2, Color32, Context, CornerRadius, FontId, Id, Layout, Response, RichText, Sense, Ui, UiBuilder, Vec2}; + +mod backend; +#[cfg(test)] +mod tests; + +pub use backend::{Answer, Destination, Failure, Grant, Replier, Request, ShareBackend}; + +/// How long after the last keystroke the dialog asks for matches. +/// +/// A lookup per keystroke would ask five times for "annie" and paint whichever +/// answer happened to arrive last. +pub const DEBOUNCE: Duration = Duration::from_millis(200); + +/// How many matches one lookup asks for. +const MATCHES: usize = 8; + +/// Shortest query worth asking about. One letter matches most of an address +/// book and tells the user nothing. +const MIN_QUERY: usize = 2; + +/// Contact pictures held at once. Reached only by a long session of searching; +/// the whole cache is dropped rather than evicted one entry at a time. +const AVATARS: usize = 256; + +/// How long before an unanswered capability question is asked again, so one +/// unreachable moment does not hide Share for the rest of the session. +const RETRY: f64 = 20.0; + +const AVATAR: f32 = 20.0; +const AVATAR_RADIUS: u8 = 10; + +/// The id of the recipient field, for an app that wants to focus it. +const QUERY: &str = "craft-ui/share/query"; + +type Inbox = (u64, Result); + +/// Every string the dialog shows, so an application can translate it. +/// +/// The defaults are English. Nothing else in `craft-ui` localizes, and this +/// does not change that: the dialog holds the strings an app gives it and +/// translates nothing itself. +#[derive(Clone, Debug)] +pub struct ShareLabels { + pub title: String, + pub recipients: String, + pub recipient_hint: String, + pub searching: String, + pub no_matches: String, + pub add_address: String, + pub group: String, + pub permission: String, + pub can_view: String, + pub can_edit: String, + pub note: String, + pub notify: String, + pub no_mail: String, + pub share: String, + pub sharing: String, + pub close: String, + pub remove: String, + pub shared_with: String, + pub not_shared_with: String, + pub access: String, + pub access_empty: String, + pub loading: String, + pub withdraw: String, + pub withdrawing: String, + pub copy_link: String, + pub anyone_with_link: String, + pub save_first: String, + /// Shown under "Can edit", the way an office suite explains a permission + /// rather than leaving a bare radio button to carry the meaning. + pub can_edit_detail: String, + pub can_view_detail: String, + pub message_hint: String, + pub send: String, + pub manage_access: String, + pub upload_first: String, + pub name_hint: String, + pub saving: String, + pub save_and_share: String, + pub sign_in: String, + pub attach_instead: String, + pub create_link: String, + pub key_hint: String, + pub key_required_note: String, + pub link_copied: String, +} + +impl Default for ShareLabels { + fn default() -> ShareLabels { + ShareLabels { + title: "Share".into(), + recipients: "Share with".into(), + recipient_hint: "Add a name, group, or email".into(), + searching: "Looking…".into(), + no_matches: "No matches".into(), + add_address: "Press Return to share with this address".into(), + group: "group".into(), + permission: "They may".into(), + can_view: "View".into(), + can_edit: "Edit".into(), + note: "Note (optional)".into(), + notify: "Notify by email".into(), + no_mail: "This server cannot send mail".into(), + share: "Share".into(), + sharing: "Sharing…".into(), + close: "Close".into(), + remove: "Remove".into(), + shared_with: "Shared with".into(), + not_shared_with: "Not shared with".into(), + access: "Who has access".into(), + access_empty: "Nobody else yet".into(), + loading: "Loading…".into(), + withdraw: "Withdraw".into(), + withdrawing: "Withdrawing…".into(), + copy_link: "Copy link".into(), + anyone_with_link: "Anyone with the link".into(), + save_first: "Save this document to the cloud before sharing it.".into(), + can_edit_detail: "Make any changes".into(), + can_view_detail: "Cannot make changes".into(), + message_hint: "Add a message".into(), + send: "Send".into(), + manage_access: "Who has access".into(), + upload_first: "Save this document somewhere to share it.".into(), + name_hint: "Name this document".into(), + saving: "Saving\u{2026}".into(), + save_and_share: "Save and share".into(), + sign_in: "Sign in".into(), + attach_instead: "Attach a copy instead".into(), + create_link: "Get a link".into(), + key_hint: "Key (optional)".into(), + key_required_note: "This server requires a key on a link.".into(), + link_copied: "Link copied".into(), + } + } +} + +/// What the provider behind the service actually does. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct Provider { + sharing: bool, + contacts: bool, + mail: bool, + /// Public links at all. An administrator can forbid them. + links: bool, + /// A key on a link. + key: bool, + /// The server insists on one, so a link cannot be made without it. + key_required: bool, +} + +/// One contact picture, asked for at most once. +#[derive(Clone, Debug, PartialEq, Eq)] +enum Avatar { + /// Asked for under this sequence number; nothing to paint yet. + Pending(u64), + /// Bytes handed to egui under this URI, for the application's image + /// loaders to decode. + Ready(String), + /// Asked once and refused. Initials are painted instead, and it is never + /// asked for again. + Missing, +} + +/// Somebody the user has picked. +#[derive(Clone, Debug, PartialEq, Eq)] +struct Chosen { + target: ShareTarget, + label: String, + detail: Option, + avatar: Option, +} + +/// The dialog's state while it is open on one document. +struct Sheet { + id: String, + title: String, + query: String, + /// When the query last changed, for the debounce. `None` when settled. + typed: Option, + /// The newest lookup asked for. An answer to anything older is dropped. + lookup: Option, + searching: bool, + matches: Vec, + chosen: Vec, + permission: Permission, + note: String, + notify: bool, + /// Who already has access. `None` until the answer arrives. + access: Option>, + access_seq: Option, + /// Withdrawals in flight, as (request, share). + withdrawing: Vec<(u64, String)>, + granting: Option, + /// Where it could be saved. `None` until the answer arrives. + destinations: Option>, + destinations_seq: Option, + link_seq: Option, + /// Which one is selected, by id. + destination: Option, + /// The name typed while the document still has nowhere to live. + save_as: String, + /// The save in flight, if one is. + saving: Option, + save_error: Option, + /// The key to put on a link, while one is being made. + link_key: String, + /// The last share's outcome, kept on screen until the next one. + shared: Vec, + failed: Vec, + /// A refusal that stopped a whole call, as opposed to one recipient. + error: Option, +} + +impl Sheet { + fn new(id: String, title: String) -> Sheet { + Sheet { + destinations: None, + destinations_seq: None, + link_seq: None, + destination: None, + save_as: title.clone(), + saving: None, + save_error: None, + link_key: String::new(), + id, + title, + query: String::new(), + typed: None, + lookup: None, + searching: false, + matches: Vec::new(), + chosen: Vec::new(), + permission: Permission::View, + note: String::new(), + notify: true, + access: None, + access_seq: None, + withdrawing: Vec::new(), + granting: None, + shared: Vec::new(), + failed: Vec::new(), + error: None, + } + } +} + +/// Something the drawing pass decided and the dialog carries out afterwards. +/// +/// Drawing holds the open sheet, so it cannot also reach the request channel. +/// Collecting intentions and acting on them once the frame is painted keeps +/// both honest. +enum Act { + Lookup(String), + /// Save a document that has nowhere to live yet, into one destination. + SaveAs { + destination: String, + name: String, + }, + /// Connect an account for a destination that has none. + Link(String), + Grant(Grant), + Withdraw(String), + Avatar(String), + Close, +} + +/// A save the dialog is waiting on the application to do. +/// +/// Taken once. The application serialises the open document, puts it where +/// `destination` says, and reports back with [`ShareDialog::saved`] or +/// [`ShareDialog::save_failed`]. Prefer [`ShareDialog::saved_if`] / +/// [`ShareDialog::save_failed_if`] with [`SaveRequest::generation`] when the +/// save is asynchronous, so a completion for a closed or replaced sheet is +/// dropped without the application inventing its own epoch. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SaveRequest { + /// Which destination, as the dialog was told by [`Destination::id`]. + pub destination: String, + /// What the user called it. + pub name: String, + /// Open-sheet generation when this request was taken. Pass to + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`]. + pub generation: u64, +} + +/// What the dialog may offer this frame. +#[derive(Clone, Copy)] +struct Allowed { + contacts: bool, + mail: bool, + links: bool, + key: bool, + key_required: bool, +} + +/// A share dialog. +/// +/// Create one per window, call [`ShareDialog::connect`] once a backend exists, +/// call [`ShareDialog::show`] every frame, and open it from a Share control +/// that is drawn only while [`ShareDialog::available`] is true. +pub struct ShareDialog { + backend: Option>, + tx: Sender, + rx: Receiver, + seq: u64, + provider: Option, + /// When the capability question was last asked. + asked: Option, + open: Option, + /// Keyed by the URL the contact carried, so reopening the dialog does not + /// fetch the same faces again. + avatars: HashMap, + /// A save the application has not picked up yet. + wants_save: Option, + /// Bumped on every [`ShareDialog::open`] and [`ShareDialog::close`]. A save + /// completion from an earlier open is ignored when this no longer matches + /// [`ShareDialog::pending_save_generation`]. + sheet_generation: u64, + /// Generation of the open sheet when [`ShareDialog::take_save_request`] + /// last handed a save to the application. + pending_save_generation: Option, + labels: ShareLabels, +} + +impl Default for ShareDialog { + fn default() -> ShareDialog { + ShareDialog::new() + } +} + +impl ShareDialog { + pub fn new() -> ShareDialog { + let (tx, rx) = std::sync::mpsc::channel(); + ShareDialog { + backend: None, + tx, + rx, + seq: 0, + provider: None, + asked: None, + open: None, + avatars: HashMap::new(), + wants_save: None, + sheet_generation: 0, + pending_save_generation: None, + labels: ShareLabels::default(), + } + } + + /// Attach the thing that does the waiting. + /// + /// The first frame after this asks what the provider can do, which is what + /// decides whether sharing is offered at all. + pub fn connect(&mut self, backend: impl ShareBackend + 'static) { + self.backend = Some(Box::new(backend)); + self.provider = None; + self.asked = None; + } + + pub fn connected(&self) -> bool { + self.backend.is_some() + } + + /// Replace the dialog's strings, for a localized application. + pub fn with_labels(mut self, labels: ShareLabels) -> ShareDialog { + self.labels = labels; + self + } + + pub fn labels_mut(&mut self) -> &mut ShareLabels { + &mut self.labels + } + + /// Whether sharing can be offered. + /// + /// False until the service says the provider supports it and an account is + /// linked. An application draws no Share control while this is false: a + /// hidden feature is better than a button that fails on use. + /// Ask the provider again what it can do. + /// + /// The answer is kept once it arrives, so a host that signs somebody + /// in after the first answer has to say so. Without this the dialog + /// keeps the answer it got while nobody was signed in, and Share + /// stays unavailable for the rest of the run. + pub fn refresh(&mut self) { + self.provider = None; + self.asked = None; + } + + pub fn available(&self) -> bool { + self.provider.is_some_and(|p| p.sharing) + } + + /// Open on one document. + /// + /// `id` is the handle the application was given for it, passed back + /// untouched. An empty one means the document has never been saved to the + /// cloud, which the dialog says rather than failing on Share. Does nothing + /// while sharing is unavailable. + pub fn open(&mut self, id: impl Into, title: impl Into) { + if !self.available() { + return; + } + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + let id = id.into(); + self.open = Some(Sheet::new(id.clone(), title.into())); + if id.is_empty() { + // Nothing to share yet, so the dialog opens on the places it could + // go. Asked for here rather than on the first frame, so the list is + // usually there by the time anybody looks. + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + if !id.is_empty() { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// A save the application should perform, if one was asked for. + /// + /// Taken, so it is handled once. Stamps [`SaveRequest::generation`] with + /// the open sheet's generation. Call [`ShareDialog::saved`] / + /// [`ShareDialog::save_failed`] (dialog-side pending guard) or + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`] with that + /// generation when the work finishes; otherwise the dialog waits. + pub fn take_save_request(&mut self) -> Option { + let mut request = self.wants_save.take()?; + request.generation = self.sheet_generation; + self.pending_save_generation = Some(request.generation); + Some(request) + } + + /// The document was saved, and this is the handle the provider issued. + /// + /// Ignored when the dialog has closed, reopened on another document, or + /// taken a newer save since [`ShareDialog::take_save_request`]. + pub fn saved(&mut self, id: impl Into, name: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// Like [`ShareDialog::saved`], but applies only when `generation` matches + /// the open sheet's generation. + pub fn saved_if(&mut self, generation: u64, id: impl Into, name: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// The save did not happen, and this is why. + /// + /// Ignored under the same conditions as [`ShareDialog::saved`]. + pub fn save_failed(&mut self, reason: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Like [`ShareDialog::save_failed`], but applies only when `generation` + /// matches the open sheet's generation. + pub fn save_failed_if(&mut self, generation: u64, reason: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Generation of the sheet currently open, for callers that track their + /// own save epoch. Zero when the dialog is closed. + pub fn sheet_generation(&self) -> u64 { + if self.open.is_some() { self.sheet_generation } else { 0 } + } + + fn save_completion_applies(&self) -> bool { + self.pending_save_generation.is_some_and(|g| g == self.sheet_generation) + } + + fn finish_saved(&mut self, id: impl Into, name: impl Into) { + if self.open.is_none() { + return; + } + let id = id.into(); + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = None; + sheet.id = id.clone(); + sheet.title = name.into(); + } + // The document exists now, so ask who already has access, exactly as + // opening on a saved document would. + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + + pub fn is_open(&self) -> bool { + self.open.is_some() + } + + pub fn close(&mut self) { + self.open = None; + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + } + + /// Who the last share reached, and who it did not. + pub fn outcome(&self) -> (&[Share], &[Failure]) { + match &self.open { + Some(sheet) => (&sheet.shared, &sheet.failed), + None => (&[], &[]), + } + } + + /// The recipient field's id, for an application that wants to focus it. + pub fn query_field_id() -> Id { + Id::new(QUERY) + } + + /// One frame, as a modal over the window. Call this unconditionally: + /// answers are collected here whether the dialog is open or not. + pub fn show(&mut self, ctx: &Context) { + self.collect(ctx); + if self.open.is_none() { + return; + } + let modal = egui::Modal::new(Id::new("craft-ui/share")).show(ctx, |ui| { + ui.set_min_width(440.0); + ui.set_max_width(560.0); + self.contents(ui); + }); + if modal.should_close() { + self.close(); + } + } + + /// One frame's contents without the modal chrome, for an application that + /// hosts the dialog in its own panel. + pub fn show_in(&mut self, ui: &mut Ui) { + self.collect(ui.ctx()); + if self.open.is_some() { + self.contents(ui); + } + } + + fn contents(&mut self, ui: &mut Ui) { + let allowed = match self.provider { + Some(p) => Allowed { contacts: p.contacts, mail: p.mail, links: p.links, key: p.key, key_required: p.key_required }, + None => Allowed { contacts: false, mail: false, links: false, key: false, key_required: false }, + }; + let mut acts = Vec::new(); + { + let Some(sheet) = self.open.as_mut() else { return }; + draw(ui, sheet, &self.avatars, &self.labels, allowed, &mut acts); + } + self.apply(ui.ctx(), acts); + } + + // ---- the channel ------------------------------------------------------ + + fn issue(&mut self, request: Request) -> u64 { + self.seq += 1; + let seq = self.seq; + if let Some(backend) = &self.backend { + backend.submit(request, Replier::new(seq, self.tx.clone())); + } + seq + } + + fn collect(&mut self, ctx: &Context) { + while let Ok((seq, result)) = self.rx.try_recv() { + self.receive(ctx, seq, result); + } + let now = ctx.input(|i| i.time); + if self.backend.is_some() && self.provider.is_none() && self.asked.is_none_or(|at| now - at >= RETRY) { + self.asked = Some(now); + self.issue(Request::Capabilities); + } + } + + fn receive(&mut self, ctx: &Context, seq: u64, result: Result) { + let answer = match result { + Ok(answer) => answer, + Err(reason) => return self.refused(seq, reason), + }; + // Set while an answer leaves something else worth asking for; issued + // once the open sheet is no longer borrowed. + let mut reload = None; + match answer { + Answer::Capabilities { capabilities, linked } => { + self.provider = Some(Provider { + sharing: linked && capabilities.contains(&Capability::Sharing), + contacts: capabilities.contains(&Capability::Contacts), + // ShareNotify, not Mail. Mail means "can send arbitrary + // mail"; this box only asks the provider to tell the + // person being shared with, which is a far smaller claim + // and one most providers can honour. + mail: capabilities.contains(&Capability::ShareNotify), + links: capabilities.contains(&Capability::LinkShares), + key: capabilities.contains(&Capability::LinkPassword), + key_required: capabilities.contains(&Capability::LinkPasswordRequired), + }); + // A provider that cannot share must not leave a dialog up that + // was opened while the answer was still outstanding. + if !self.available() { + self.close(); + } + } + Answer::Lookup(found) => { + if let Some(sheet) = &mut self.open + && sheet.lookup == Some(seq) + { + sheet.matches = found; + sheet.searching = false; + } + } + Answer::Access(list) => { + if let Some(sheet) = &mut self.open + && sheet.access_seq == Some(seq) + { + sheet.access = Some(list); + sheet.access_seq = None; + } + } + Answer::Granted { shared, failed } => { + // A link was asked for in order to be handed out, so it goes + // to the clipboard without a second click. + if let Some(url) = shared.iter().find_map(|s| s.url.clone()) { + ctx.copy_text(url); + } + if let Some(sheet) = &mut self.open + && sheet.granting == Some(seq) + { + sheet.granting = None; + sheet.error = None; + // Recipients that went through leave the picker. The ones + // that did not stay in it, so a corrected retry is one + // press rather than a retyped list. + sheet.chosen.retain(|c| failed.iter().any(|f| f.target == c.target)); + sheet.shared = shared; + sheet.failed = failed; + if !sheet.shared.is_empty() { + reload = Some(sheet.id.clone()); + } + } + } + Answer::Destinations(list) => { + if let Some(sheet) = &mut self.open + && sheet.destinations_seq == Some(seq) + { + // One destination and nothing to choose between: pick it, + // so the only linked account is not a click somebody has + // to make for no reason. + if sheet.destination.is_none() + && let [only] = list.as_slice() + && only.linked + { + sheet.destination = Some(only.id.clone()); + } + sheet.destinations = Some(list); + sheet.destinations_seq = None; + } + } + Answer::Linked => { + // An account arrived, so the list is stale. + if let Some(sheet) = &mut self.open { + sheet.destinations = None; + } + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + Answer::Withdrawn { share_id } => { + if let Some(sheet) = &mut self.open { + sheet.withdrawing.retain(|(_, id)| *id != share_id); + if let Some(access) = &mut sheet.access { + access.retain(|s| s.id != share_id); + } + sheet.shared.retain(|s| s.id != share_id); + } + } + Answer::Avatar { url, bytes } => { + let uri = avatar_uri(&url); + ctx.include_bytes(uri.clone(), bytes); + self.avatars.insert(url, Avatar::Ready(uri)); + } + } + if let Some(id) = reload { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// One request came back with a reason instead of an answer. + fn refused(&mut self, seq: u64, reason: String) { + // A picture nobody can fetch is not worth telling the user about, and + // is never asked for again. + if let Some(url) = self.avatars.iter().find(|(_, a)| **a == Avatar::Pending(seq)).map(|(url, _)| url.clone()) { + self.avatars.insert(url, Avatar::Missing); + return; + } + let Some(sheet) = &mut self.open else { return }; + if sheet.lookup == Some(seq) { + sheet.searching = false; + sheet.matches.clear(); + sheet.error = Some(reason); + } else if sheet.access_seq == Some(seq) { + sheet.access_seq = None; + sheet.access = Some(Vec::new()); + sheet.error = Some(reason); + } else if sheet.granting == Some(seq) { + sheet.granting = None; + sheet.error = Some(reason); + } else if sheet.withdrawing.iter().any(|(s, _)| *s == seq) { + sheet.withdrawing.retain(|(s, _)| *s != seq); + sheet.error = Some(reason); + } else if sheet.destinations_seq == Some(seq) { + sheet.destinations_seq = None; + sheet.destinations = Some(Vec::new()); + sheet.save_error = Some(reason); + } else if sheet.link_seq == Some(seq) { + sheet.link_seq = None; + sheet.save_error = Some(reason); + } + } + + fn apply(&mut self, ctx: &Context, acts: Vec) { + for act in acts { + match act { + Act::Close => self.close(), + Act::Lookup(query) => { + let seq = self.issue(Request::Lookup { query, limit: MATCHES }); + if let Some(sheet) = &mut self.open { + sheet.lookup = Some(seq); + sheet.searching = true; + } + } + Act::Grant(grant) => { + let seq = self.issue(Request::Grant(grant)); + if let Some(sheet) = &mut self.open { + sheet.granting = Some(seq); + sheet.shared.clear(); + sheet.failed.clear(); + sheet.error = None; + } + } + Act::SaveAs { destination, name } => { + // Handed to the application rather than the backend. Only + // it can turn the open document into bytes, and a share + // transport is the wrong place to pass a workbook through. + // `generation` is filled when taken; zero here is a placeholder. + self.wants_save = Some(SaveRequest { destination, name, generation: 0 }); + if let Some(sheet) = &mut self.open { + sheet.saving = Some(0); + sheet.save_error = None; + } + } + Act::Link(destination) => { + // The answer to this is usually a refusal carrying the URL + // to open, because launching a browser is the host + // application's business and not this crate's. + let seq = self.issue(Request::Link { destination }); + if let Some(sheet) = &mut self.open { + sheet.link_seq = Some(seq); + sheet.error = None; + } + } + Act::Withdraw(share_id) => { + let seq = self.issue(Request::Withdraw { share_id: share_id.clone() }); + if let Some(sheet) = &mut self.open { + sheet.withdrawing.push((seq, share_id)); + } + } + Act::Avatar(url) => { + if self.avatars.contains_key(&url) { + continue; + } + if self.avatars.len() >= AVATARS { + for (_, avatar) in self.avatars.drain() { + if let Avatar::Ready(uri) = avatar { + ctx.forget_image(&uri); + } + } + } + let seq = self.issue(Request::Avatar { url: url.clone() }); + self.avatars.insert(url, Avatar::Pending(seq)); + } + } + } + } +} + +// ---- drawing -------------------------------------------------------------- + +fn draw(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + let danger = ui.visuals().error_fg_color; + + // The document is named in the title, in quotes. This dialog gives other + // people access to one specific thing, and sharing the wrong one is the + // mistake it exists to prevent. + ui.horizontal(|ui| { + let heading = if sheet.title.is_empty() { labels.title.clone() } else { format!("{} \u{201c}{}\u{201d}", labels.title, sheet.title) }; + ui.label(RichText::new(heading).strong().size(15.0)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let close = egui::Button::new(RichText::new("\u{00d7}").size(18.0)).frame(false); + if ui.add(close).on_hover_text(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + ui.add_space(8.0); + + // Nothing to share yet. The old build stopped here with a sentence and a + // Close button, naming the obstacle and leaving somebody to deal with it + // elsewhere. Saving is the first step of sharing now. + if sheet.id.is_empty() { + save_first(ui, sheet, labels, acts); + return; + } + + // Who, and what they may do, on one row. The permission applies to these + // recipients, so it belongs beside them. A separate pair of radio buttons + // further down reads as an unrelated setting. + ui.horizontal_top(|ui| { + let width = (ui.available_width() - 104.0).max(160.0); + ui.allocate_ui(egui::vec2(width, 0.0), |ui| { + recipients(ui, sheet, avatars, labels, allowed, acts); + }); + permission_menu(ui, sheet, labels); + }); + // Only once something has actually been asked. "No matches" under an + // untouched field reads as a failure before any search ran. + if sheet.searching || !sheet.matches.is_empty() || sheet.query.trim().chars().count() >= MIN_QUERY { + matches(ui, sheet, avatars, labels, allowed, acts); + } + + ui.add_space(6.0); + + // The message, as a bordered area with its own placeholder. People write a + // sentence here, not a value, and a label above a one-line field invites + // neither. + // TextEdit draws its own border, so no group around it. Wrapping one in a + // Frame::group gives two nested borders. + ui.add( + egui::TextEdit::multiline(&mut sheet.note) + .hint_text(labels.message_hint.as_str()) + .desired_width(f32::INFINITY) + .desired_rows(3) + .char_limit(500), + ); + + ui.add_space(8.0); + + // One primary action, on the right where the eye finishes. Notify sits + // beside it rather than loose in the middle of the form. + // A link, for anybody who has no account. Drawn only where the server + // allows public links, because an administrator can forbid them and a + // button that always fails is worse than no button. + if allowed.links { + ui.horizontal(|ui| { + if allowed.key { + ui.add(egui::TextEdit::singleline(&mut sheet.link_key).hint_text(labels.key_hint.as_str()).password(true).desired_width(150.0)); + } + // A key the server insists on cannot be skipped, so the control + // stays disabled until one is typed. + let keyed = !sheet.link_key.trim().is_empty(); + let ready = keyed || !allowed.key_required; + if ui.add_enabled(ready, egui::Button::new(labels.create_link.as_str())).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + targets: vec![ShareTarget::Link], + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: false, + password: Some(sheet.link_key.trim().to_owned()).filter(|k| !k.is_empty()), + })); + } + if allowed.key_required && !keyed { + ui.label(RichText::new(labels.key_required_note.as_str()).small().color(weak)); + } + }); + ui.add_space(6.0); + } + + ui.horizontal(|ui| { + if allowed.mail { + ui.checkbox(&mut sheet.notify, labels.notify.as_str()); + } else { + // Reported, never assumed. A server with no mail is said to have + // none, instead of being given a box that quietly does nothing. + sheet.notify = false; + ui.add_enabled(false, egui::Checkbox::new(&mut sheet.notify, labels.notify.as_str())).on_disabled_hover_text(labels.no_mail.as_str()); + } + + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.granting.is_some(); + let ready = !sheet.chosen.is_empty() && !busy; + let label = if busy { labels.sharing.clone() } else { labels.send.clone() }; + let send = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(88.0, 26.0)); + if ui.add_enabled(ready, send).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + password: None, + targets: sheet.chosen.iter().map(|c| c.target.clone()).collect(), + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: sheet.notify, + })); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + + outcome(ui, sheet, labels, danger); + + // Who already holds the document, open. Folding it hid the one fact + // a person needs before adding anybody else. It still folds on request. + ui.add_space(4.0); + egui::CollapsingHeader::new(RichText::new(labels.manage_access.as_str()).color(weak)) + .id_salt("craft-ui/share/manage-access") + .default_open(true) + .show(ui, |ui| { + access(ui, sheet, labels, weak, acts); + }); +} + +/// Where to put it, then what to call it. +/// +/// A document with no handle cannot be shared. Rather than saying so and +/// stopping, this offers the places it could go, each naming the account it +/// would land in, with a sign-in for any that is configured without one. +/// +/// A list, because there is rarely only one answer. A second provider is an +/// implementation of the contracts, and this is where it shows up. +fn save_first(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + ui.label(labels.upload_first.as_str()); + ui.add_space(8.0); + + let Some(destinations) = sheet.destinations.clone() else { + ui.horizontal(|ui| { + ui.spinner(); + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + }); + return; + }; + + for destination in &destinations { + let chosen = sheet.destination.as_deref() == Some(destination.id.as_str()); + let stroke = if chosen { ui.visuals().selection.stroke } else { ui.visuals().widgets.noninteractive.bg_stroke }; + let row = egui::Frame::group(ui.style()) + .stroke(stroke) + .show(ui, |ui| { + ui.set_width(ui.available_width()); + ui.horizontal(|ui| { + ui.vertical(|ui| { + ui.label(RichText::new(destination.name.as_str()).strong()); + // The account, because two entries both reading + // "Cloud" tell nobody which one a document is about to + // land in. + let under = if destination.linked { destination.account.clone().unwrap_or_default() } else { labels.sign_in.clone() }; + ui.label(RichText::new(under).small().color(weak)); + }); + }); + }) + .response + .interact(egui::Sense::click()); + if row.clicked() { + if destination.linked { + sheet.destination = Some(destination.id.clone()); + } else { + acts.push(Act::Link(destination.id.clone())); + } + } + ui.add_space(4.0); + } + + if let Some(problem) = &sheet.save_error { + ui.add_space(4.0); + ui.label(RichText::new(problem).color(ui.visuals().error_fg_color)); + } + + let Some(into) = sheet.destination.clone() else { return }; + + ui.add_space(8.0); + let saving = sheet.saving.is_some(); + ui.add_enabled(!saving, egui::TextEdit::singleline(&mut sheet.save_as).hint_text(labels.name_hint.as_str()).desired_width(f32::INFINITY)); + + ui.add_space(8.0); + ui.horizontal(|ui| { + let named = !sheet.save_as.trim().is_empty(); + let label = if saving { labels.saving.clone() } else { labels.save_and_share.clone() }; + let button = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(124.0, 26.0)); + if ui.add_enabled(named && !saving, button).clicked() { + acts.push(Act::SaveAs { destination: into.clone(), name: sheet.save_as.trim().to_owned() }); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); +} + +/// The permission picker, as a menu with a line of explanation under each +/// choice. +/// +/// Two radio buttons reading View and Edit leave the difference to be guessed. +/// Only the permissions the contracts can actually keep are offered: a choice +/// the server cannot honour is worse than one fewer choice. +fn permission_menu(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels) { + let current = match sheet.permission { + Permission::Edit => labels.can_edit.as_str(), + Permission::View => labels.can_view.as_str(), + }; + // A triangle, so it reads as something that opens. Painted rather than + // typed: the character is missing from the default font set, where it + // renders as a box. + let button = ui.button(format!("{current} ")); + crate::buttons::chevron(ui, button.rect, ui.visuals().text_color()); + // The padding makes room for the triangle. It is layout, so it must not + // reach anybody reading the screen aloud. + button.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, current)); + egui::Popup::menu(&button).show(|ui| { + ui.set_min_width(190.0); + for (value, name, detail) in [ + (Permission::Edit, labels.can_edit.as_str(), labels.can_edit_detail.as_str()), + (Permission::View, labels.can_view.as_str(), labels.can_view_detail.as_str()), + ] { + let chosen = sheet.permission == value; + if ui.selectable_label(chosen, RichText::new(name).strong()).clicked() { + sheet.permission = value; + ui.close(); + } + ui.label(RichText::new(detail).small().color(ui.visuals().weak_text_color())); + ui.add_space(2.0); + } + }); +} + +/// The chips, and the field that adds another. +fn recipients(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let now = ui.input(|i| i.time); + egui::Frame::group(ui.style()).show(ui, |ui| { + ui.horizontal_wrapped(|ui| { + let mut remove = None; + for (i, chosen) in sheet.chosen.iter().enumerate() { + if chip(ui, avatars, chosen, labels, acts).clicked() { + remove = Some(i); + } + } + if let Some(i) = remove.filter(|i| *i < sheet.chosen.len()) { + sheet.chosen.remove(i); + } + + let field = ui.add( + egui::TextEdit::singleline(&mut sheet.query) + .id(ShareDialog::query_field_id()) + .hint_text(labels.recipient_hint.as_str()) + // Fills whatever the chips left. A fixed width leaves a + // short field floating in a frame twice as wide. + .desired_width(ui.available_width().max(120.0)), + ); + if field.changed() { + sheet.typed = Some(now); + } + // Backspace on an empty field takes the last chip back, which is + // what every other recipient field does. + if field.has_focus() && sheet.query.is_empty() && ui.input(|i| i.key_pressed(egui::Key::Backspace)) { + sheet.chosen.pop(); + } + if field.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)) { + commit(sheet); + } + }); + }); + + // The debounce. Asking per keystroke asks five times for "annie" and + // paints whichever answer happens to arrive last. + if let Some(at) = sheet.typed { + let wait = DEBOUNCE.as_secs_f64(); + if now - at >= wait { + sheet.typed = None; + let query = sheet.query.trim().to_owned(); + if allowed.contacts && query.chars().count() >= MIN_QUERY { + // Set here rather than when the request is issued, so the + // frame that fires it does not read as "no matches". + sheet.searching = true; + acts.push(Act::Lookup(query)); + } else { + sheet.matches.clear(); + sheet.searching = false; + } + } else { + // Without this the frame that fires the lookup only arrives when + // something else happens to ask for a repaint. + ui.ctx().request_repaint_after(Duration::from_secs_f64((wait - (now - at)).clamp(0.0, wait))); + } + } +} + +/// Take whatever has been typed as a recipient: the first match if there is +/// one, otherwise an address if it looks like one. +fn commit(sheet: &mut Sheet) { + let typed = sheet.query.trim().to_lowercase(); + + // An exact match wins. Somebody who typed a whole address that belongs to + // an account should get the account, because a share to an account appears + // in their files rather than only in their inbox. + if let Some(exact) = sheet + .matches + .iter() + .find(|c| c.id.to_lowercase() == typed || c.email.as_deref().is_some_and(|e| e.to_lowercase() == typed) || c.name.to_lowercase() == typed) + .cloned() + { + choose(sheet, &exact); + return; + } + + // Then whatever was typed, if it is an address. The list is a convenience + // and not the set of permitted answers: taking its first row here would + // share with whoever happened to match the opening characters of an + // address somebody typed out in full. + if let Some(address) = address(&sheet.query) { + add(sheet, ShareTarget::Email(address.clone()), address, None, None); + return; + } + + // Otherwise the best the list has, which is what a partial name means. + if let Some(contact) = sheet.matches.first().cloned() { + choose(sheet, &contact); + } +} + +fn matches(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + // Somebody with no account on this server is reached by address or not at + // all, so the one way to do that is said out loud. A dialog that hides it + // leaves the user guessing which keys work. + if sheet.matches.is_empty() + && address(&sheet.query).is_some() + && !sheet.chosen.iter().any(|c| c.target == ShareTarget::Email(sheet.query.trim().to_owned())) + { + ui.label(RichText::new(labels.add_address.as_str()).color(weak)); + } + if !allowed.contacts { + return; + } + if sheet.searching && sheet.matches.is_empty() { + ui.label(RichText::new(labels.searching.as_str()).color(weak)); + return; + } + if sheet.matches.is_empty() { + if sheet.typed.is_none() && sheet.query.trim().chars().count() >= MIN_QUERY && address(&sheet.query).is_none() { + ui.label(RichText::new(labels.no_matches.as_str()).color(weak)); + } + return; + } + let mut pick = None; + egui::ScrollArea::vertical().max_height(150.0).id_salt("craft-ui/share/matches").show(ui, |ui| { + for (i, contact) in sheet.matches.iter().enumerate() { + if row(ui, avatars, contact, labels, acts).clicked() { + pick = Some(i); + } + } + }); + if let Some(contact) = pick.and_then(|i| sheet.matches.get(i).cloned()) { + choose(sheet, &contact); + } +} + +fn outcome(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, danger: Color32) { + if let Some(error) = &sheet.error { + ui.colored_label(danger, error.as_str()); + } + if !sheet.shared.is_empty() { + let who: Vec = sheet.shared.iter().map(|s| share_label(s, labels)).collect(); + ui.label(format!("{}: {}", labels.shared_with, who.join(", "))); + } + // One line each. Five recipients with one bad address shares with four and + // names the one that failed; collapsing that into a single error would + // hide both halves. + for failure in &sheet.failed { + ui.colored_label(danger, format!("{} {}: {}", labels.not_shared_with, target_label(&failure.target, labels), describe(failure))); + } +} + +fn describe(failure: &Failure) -> String { + if failure.detail.trim().is_empty() { failure.code.clone() } else { failure.detail.clone() } +} + +fn access(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, weak: Color32, acts: &mut Vec) { + // The header above already names this list. Naming it twice reads as + // two headings for one thing. + let Some(list) = &sheet.access else { + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + return; + }; + if list.is_empty() { + ui.label(RichText::new(labels.access_empty.as_str()).color(weak)); + return; + } + egui::ScrollArea::vertical().max_height(160.0).id_salt("craft-ui/share/access").show(ui, |ui| { + for share in list { + ui.horizontal(|ui| { + ui.label(share_label(share, labels)); + let permission = match share.permission { + Permission::View => labels.can_view.as_str(), + Permission::Edit => labels.can_edit.as_str(), + }; + ui.label(RichText::new(permission).color(weak)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.withdrawing.iter().any(|(_, id)| *id == share.id); + // A bin, with the word on hover. The row is already a + // line of text; a second word on it reads as more content + // rather than as the control it is. + let glyph = if busy { "\u{22ef}" } else { "\u{1f5d1}" }; + let bin = egui::Button::new(RichText::new(glyph).size(15.0)).frame(false); + let hint = if busy { labels.withdrawing.as_str() } else { labels.withdraw.as_str() }; + let pressed = ui.add_enabled(!busy, bin); + // A glyph is not a name. Left alone this button announces itself + // to a screen reader as a wastebasket character, so the word goes + // on explicitly. + pressed.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, !busy, hint)); + if pressed.on_hover_text(hint).clicked() { + acts.push(Act::Withdraw(share.id.clone())); + } + if let Some(url) = &share.url + && ui.small_button(labels.copy_link.as_str()).clicked() + { + ui.ctx().copy_text(url.clone()); + } + }); + }); + if let Some(note) = &share.note + && !note.trim().is_empty() + { + ui.label(RichText::new(note.as_str()).color(weak).small()); + } + } + }); +} + +// ---- pieces --------------------------------------------------------------- + +/// One picked recipient. The whole chip is the remove control. +fn chip(ui: &mut Ui, avatars: &HashMap, chosen: &Chosen, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, chosen.avatar.as_deref(), &chosen.label, acts); + ui.label(chosen.label.as_str()); + // The same cross the dialog closes with. U+2715 is absent from + // the default font set, where it renders as a box. + ui.label(RichText::new("×").color(ui.visuals().weak_text_color())); + ui.add_space(1.0); + }); + }); + let response = inner.response; + let fill = if response.hovered() { ui.visuals().widgets.hovered.bg_fill } else { ui.visuals().widgets.inactive.bg_fill }; + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(AVATAR_RADIUS), fill)); + let label = format!("{} {}", labels.remove, chosen.label); + response.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, ui.is_enabled(), label.clone())); + // The address, where there is one. Two colleagues share a display name + // often enough that a chip reading "Ann Reed" is not an identity. + let hint = match &chosen.detail { + Some(detail) if !detail.is_empty() => format!("{} · {detail}", labels.remove), + _ => labels.remove.clone(), + }; + response.on_hover_text(hint) +} + +/// One match in the autocomplete list. +fn row(ui: &mut Ui, avatars: &HashMap, contact: &Contact, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let width = ui.available_width(); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.set_min_width(width); + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, contact.avatar.as_deref(), &contact.name, acts); + ui.label(contact.name.as_str()); + let detail = if contact.is_group { format!("({})", labels.group) } else { contact.email.clone().unwrap_or_default() }; + if !detail.is_empty() { + ui.label(RichText::new(detail).color(ui.visuals().weak_text_color())); + } + }); + }); + let response = inner.response; + if response.hovered() { + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(4), ui.visuals().widgets.hovered.bg_fill)); + } + let label = contact.name.clone(); + response.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, ui.is_enabled(), label.clone())); + response +} + +/// A contact picture, or initials while there is none. +/// +/// A picture is asked for here, as the row that needs it is painted, and only +/// when that row is actually on screen. A search answering with ten people +/// therefore costs no pictures at all until they are looked at, and the ones +/// scrolled past below the fold cost nothing either. `avatars` holds every URL +/// ever asked about, the refusals included, so nothing is asked for twice. +fn picture(ui: &mut Ui, avatars: &HashMap, url: Option<&str>, label: &str, acts: &mut Vec) { + let size = Vec2::splat(AVATAR); + let (rect, _) = ui.allocate_exact_size(size, Sense::hover()); + match url.and_then(|u| avatars.get(u)) { + Some(Avatar::Ready(uri)) => { + let image = egui::Image::from_uri(uri.clone()).fit_to_exact_size(size).corner_radius(CornerRadius::same(AVATAR_RADIUS)); + if image.load_for_size(ui.ctx(), size).is_ok() { + image.paint_at(ui, rect); + return; + } + } + Some(_) => {} + None => { + if let Some(url) = url.filter(|_| ui.is_rect_visible(rect)) { + acts.push(Act::Avatar(url.to_owned())); + } + } + } + ui.painter().circle_filled(rect.center(), AVATAR / 2.0, ui.visuals().widgets.inactive.bg_fill); + ui.painter().text(rect.center(), Align2::CENTER_CENTER, initials(label), FontId::proportional(AVATAR * 0.42), ui.visuals().text_color()); +} + +fn initials(label: &str) -> String { + label.split_whitespace().filter_map(|word| word.chars().next()).take(2).flat_map(|c| c.to_uppercase()).collect() +} + +/// A stable URI for one avatar's bytes. egui caches by URI, so two contacts +/// must never share one. +fn avatar_uri(url: &str) -> String { + use std::hash::{Hash as _, Hasher as _}; + let mut hasher = std::hash::DefaultHasher::new(); + url.hash(&mut hasher); + format!("bytes://craft-ui/share/avatar/{:016x}", hasher.finish()) +} + +fn choose(sheet: &mut Sheet, contact: &Contact) { + // What the provider said, never a guess from the id. A contact with no + // account is reachable only by address, and sharing that address as a user + // id fails with "not found", because no such user exists. + let target = contact.target.clone(); + add(sheet, target, contact.name.clone(), contact.email.clone(), contact.avatar.clone()); +} + +/// Add one recipient, unless it is already there. +fn add(sheet: &mut Sheet, target: ShareTarget, label: String, detail: Option, avatar: Option) { + if !sheet.chosen.iter().any(|c| c.target == target) { + sheet.chosen.push(Chosen { target, label, detail, avatar }); + } + sheet.query.clear(); + sheet.matches.clear(); + sheet.typed = None; + sheet.searching = false; + sheet.lookup = None; +} + +/// What the user typed, when it is an address and not a name. +/// +/// Deliberately shallow. The server decides whether an address exists, and a +/// strict local check would refuse valid addresses it had not heard of. +fn address(typed: &str) -> Option { + let typed = typed.trim(); + if typed.chars().any(char::is_whitespace) { + return None; + } + let (user, host) = typed.split_once('@')?; + if user.is_empty() || host.len() < 3 || !host.contains('.') || host.starts_with('.') || host.ends_with('.') || host.contains('@') { + return None; + } + Some(typed.to_owned()) +} + +/// What to call the person or group a share is with. +/// +/// The handle is the fallback. Showing an account id to somebody who knows +/// that person by name tells them nothing, and two colleagues with similar +/// ids are indistinguishable. +fn share_label(share: &Share, labels: &ShareLabels) -> String { + match share.display.as_deref().filter(|name| !name.trim().is_empty()) { + Some(name) => match share.target { + ShareTarget::Group(_) => format!("{name} ({})", labels.group), + _ => name.to_owned(), + }, + None => target_label(&share.target, labels), + } +} + +fn target_label(target: &ShareTarget, labels: &ShareLabels) -> String { + match target { + ShareTarget::User(id) => id.clone(), + ShareTarget::Group(id) => format!("{id} ({})", labels.group), + ShareTarget::Email(address) => address.clone(), + ShareTarget::Link => labels.anyone_with_link.clone(), + } +} diff --git a/crates/ui/src/share/tests.rs b/crates/ui/src/share/tests.rs new file mode 100644 index 000000000..dfdb3eb1e --- /dev/null +++ b/crates/ui/src/share/tests.rs @@ -0,0 +1,527 @@ +//! The dialog's state machine, with no server and no window. +//! +//! What matters here is what the dialog does with answers: that it offers +//! nothing until the service says sharing exists, that an answer the user has +//! typed past is thrown away rather than painted, that a share reaching four +//! of five people says which one it missed, and that a picture nobody can +//! fetch is asked for once. + +use std::sync::{Arc, Mutex}; + +use super::*; + +/// A backend that records what was asked and answers nothing, so a test +/// decides when each answer arrives and in which order. +#[derive(Clone, Default)] +struct Silent(Arc>>); + +impl Silent { + fn seen(&self) -> Vec { + self.0.lock().map(|seen| seen.clone()).unwrap_or_default() + } +} + +impl ShareBackend for Silent { + fn submit(&self, request: Request, _reply: Replier) { + if let Ok(mut seen) = self.0.lock() { + seen.push(request); + } + } +} + +fn can(capabilities: Vec) -> Answer { + Answer::Capabilities { capabilities, linked: true } +} + +fn everything() -> Answer { + can(vec![Capability::Sharing, Capability::Contacts, Capability::Mail]) +} + +/// A connected dialog that has been told sharing works, open on one document. +fn ready() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("files/budget.xlsx", "Budget"); + (ctx, dialog, backend) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn share(id: &str, target: ShareTarget) -> Share { + Share { id: id.into(), target, display: None, permission: Permission::View, url: None, note: None, created: None } +} + +#[test] +fn a_share_is_labelled_with_the_name_the_provider_gave() { + let labels = ShareLabels::default(); + let mut one = share("s1", ShareTarget::User("adunn".to_owned())); + assert_eq!(super::share_label(&one, &labels), "adunn", "the handle is all there is"); + one.display = Some("Ada Lovelace".to_owned()); + assert_eq!(super::share_label(&one, &labels), "Ada Lovelace"); + // A provider that answers with an empty string has said nothing. + one.display = Some(" ".to_owned()); + assert_eq!(super::share_label(&one, &labels), "adunn"); + + let mut team = share("s2", ShareTarget::Group("eng".to_owned())); + team.display = Some("Engineering".to_owned()); + assert_eq!(super::share_label(&team, &labels), format!("Engineering ({})", labels.group)); + + // A link is not a person and never carries one. + assert_eq!(super::share_label(&share("s3", ShareTarget::Link), &labels), labels.anyone_with_link); +} + +#[test] +fn nothing_is_offered_until_the_service_says_sharing_exists() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + assert!(!dialog.available(), "an unconnected dialog cannot share"); + + dialog.connect(backend.clone()); + assert_eq!(backend.seen(), Vec::new(), "connecting alone asks nothing"); + dialog.collect(&ctx); + assert_eq!(backend.seen(), vec![Request::Capabilities]); + + // Still unanswered: the question is outstanding, so the answer is no. + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open(), "the dialog must not open before the answer"); + + // A provider with files but no sharing hides the feature rather than + // offering a button that fails. + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files, Capability::Contacts]))); + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open()); + + dialog.receive(&ctx, 1, Ok(everything())); + assert!(dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(dialog.is_open()); +} + +#[test] +fn an_unlinked_account_cannot_share_even_where_the_provider_can() { + let ctx = Context::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(Silent::default()); + dialog.receive(&ctx, 1, Ok(Answer::Capabilities { capabilities: vec![Capability::Sharing], linked: false })); + assert!(!dialog.available()); +} + +#[test] +fn losing_sharing_closes_a_dialog_that_was_already_up() { + let (ctx, mut dialog, _) = ready(); + assert!(dialog.is_open()); + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files]))); + assert!(!dialog.is_open(), "a dialog that cannot do anything must not stay up"); +} + +#[test] +fn opening_asks_who_already_has_access() { + let (_ctx, dialog, backend) = ready(); + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Access { id: "files/budget.xlsx".into() }]); + assert!(dialog.is_open()); +} + +#[test] +fn an_unsaved_document_asks_where_it_could_go_and_never_about_a_handle() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + assert!(dialog.is_open()); + // Sharing an unsaved document means saving it first. The dialog therefore + // needs somewhere to offer. It asks nothing about a handle. There is none. + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Destinations]); + assert!(!backend.seen().iter().any(|r| matches!(r, Request::Access { .. })), "there is no handle to ask about"); +} + +#[test] +fn an_answer_the_user_has_typed_past_is_dropped() { + let (ctx, mut dialog, _) = ready(); + let early = dialog.issue(Request::Lookup { query: "an".into(), limit: MATCHES }); + let late = dialog.issue(Request::Lookup { query: "ann".into(), limit: MATCHES }); + if let Some(sheet) = &mut dialog.open { + sheet.lookup = Some(late); + sheet.searching = true; + } + + // The first query answers second, which is what a service under load + // does. Painting it would show matches for "an" under the text "ann". + dialog.receive(&ctx, late, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, early, Ok(Answer::Lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")]))); + + let sheet = dialog.open.as_ref().expect("still open"); + assert_eq!(sheet.matches.len(), 1); + assert_eq!(sheet.matches.first().map(|c| c.name.as_str()), Some("Ann Reed")); + assert!(!sheet.searching); +} + +#[test] +fn several_recipients_can_be_picked_and_each_only_once() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for contact in [person("ann", "Ann Reed"), person("bob", "Bob Vine"), person("ann", "Ann Reed")] { + choose(sheet, &contact); + } + choose( + sheet, + &Contact { + id: "finance".into(), + target: ShareTarget::Group("finance".into()), + name: "Finance".into(), + email: None, + avatar: None, + is_group: true, + }, + ); + + let picked: Vec<&ShareTarget> = sheet.chosen.iter().map(|c| &c.target).collect(); + assert_eq!( + picked, + vec![&ShareTarget::User("ann".into()), &ShareTarget::User("bob".into()), &ShareTarget::Group("finance".into())], + "a group shares as a group, and picking the same person twice adds one chip" + ); + assert!(sheet.query.is_empty(), "picking clears what was typed"); +} + +#[test] +fn a_share_reaching_four_of_five_names_the_fifth() { + let (ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for who in ["ann", "bob", "cal", "dee"] { + choose(sheet, &person(who, who)); + } + add(sheet, ShareTarget::Email("nobody@@".into()), "nobody@@".into(), None, None); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: Vec::new(), + permission: Permission::Edit, + note: None, + notify: true, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + + let shared: Vec = + ["ann", "bob", "cal", "dee"].iter().enumerate().map(|(i, who)| share(&format!("s{i}"), ShareTarget::User((*who).into()))).collect(); + let failed = + vec![Failure { target: ShareTarget::Email("nobody@@".into()), code: "invalid_address".into(), detail: "nobody@@ is not an address".into() }]; + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared, failed })); + + let (shared, failed) = dialog.outcome(); + assert_eq!(shared.len(), 4); + assert_eq!(failed.len(), 1, "a wrong address is named, not folded into one error"); + assert_eq!(failed.first().map(|f| f.detail.as_str()), Some("nobody@@ is not an address")); + + // The four that went through leave the picker; the one that did not stays, + // so correcting it is one edit rather than a retyped list. + let left = dialog.open.as_ref().expect("open"); + assert_eq!(left.chosen.len(), 1); + assert_eq!(left.chosen.first().map(|c| &c.target), Some(&ShareTarget::Email("nobody@@".into()))); +} + +#[test] +fn a_refusal_that_stopped_the_whole_call_is_not_a_failed_recipient() { + let (ctx, mut dialog, _) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Err("sign in again".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.error.as_deref(), Some("sign in again")); + assert!(sheet.failed.is_empty()); + assert!(sheet.granting.is_none(), "the button must come back"); +} + +#[test] +fn a_successful_share_reloads_who_has_access() { + let (ctx, mut dialog, backend) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared: vec![share("s1", ShareTarget::User("ann".into()))], failed: Vec::new() })); + let asked = backend.seen().iter().filter(|r| **r == Request::Access { id: "files/budget.xlsx".into() }).count(); + assert_eq!(asked, 2, "the list is stale the moment a share succeeds"); +} + +#[test] +fn withdrawing_takes_it_off_the_list_and_only_then() { + let (ctx, mut dialog, backend) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive( + &ctx, + access, + Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into())), share("s2", ShareTarget::Group("finance".into()))])), + ); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + + let waiting = dialog.open.as_ref().expect("open"); + assert_eq!(waiting.access.as_ref().map(Vec::len), Some(2), "it stays until the server agrees"); + assert_eq!(waiting.withdrawing.len(), 1); + assert!(backend.seen().contains(&Request::Withdraw { share_id: "s1".into() })); + + let seq = waiting.withdrawing.first().map(|(seq, _)| *seq).expect("in flight"); + dialog.receive(&ctx, seq, Ok(Answer::Withdrawn { share_id: "s1".into() })); + let after = dialog.open.as_ref().expect("open"); + assert_eq!(after.access.as_ref().map(|a| a.iter().map(|s| s.id.as_str()).collect::>()), Some(vec!["s2"])); + assert!(after.withdrawing.is_empty()); +} + +#[test] +fn a_refused_withdrawal_leaves_the_share_and_says_why() { + let (ctx, mut dialog, _) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive(&ctx, access, Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into()))]))); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + let seq = dialog.open.as_ref().and_then(|s| s.withdrawing.first().map(|(seq, _)| *seq)).expect("in flight"); + dialog.receive(&ctx, seq, Err("you do not own this share".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.access.as_ref().map(Vec::len), Some(1)); + assert!(sheet.withdrawing.is_empty(), "the button must come back"); + assert_eq!(sheet.error.as_deref(), Some("you do not own this share")); +} + +#[test] +fn a_picture_is_asked_for_once_and_a_refusal_is_remembered() { + let (ctx, mut dialog, backend) = ready(); + let url = "https://cloud.example.com/avatar/ann/64"; + dialog.apply(&ctx, vec![Act::Avatar(url.into()), Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1, "one row painted twice is one picture"); + + let seq = match dialog.avatars.get(url) { + Some(Avatar::Pending(seq)) => *seq, + other => panic!("expected a pending picture, got {other:?}"), + }; + dialog.receive(&ctx, seq, Err("this build does not fetch contact pictures".into())); + assert_eq!(dialog.avatars.get(url), Some(&Avatar::Missing)); + + // Refused once is refused. Painting the row again must not ask again. + dialog.apply(&ctx, vec![Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1); + + // And a refused picture is the dialog's business, not the user's. + assert_eq!(dialog.open.as_ref().and_then(|s| s.error.clone()), None); +} + +#[test] +fn an_unanswered_capability_question_is_asked_again_later() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 1, "a question already outstanding is not asked every frame"); + + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "one unreachable moment must not hide Share for the session"); + + dialog.receive(&ctx, 2, Ok(everything())); + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "an answered question is not asked again"); +} + +#[test] +fn what_counts_as_an_address() { + for typed in ["ann@example.com", " ann.reed+tag@mail.example.co.uk "] { + assert!(address(typed).is_some(), "{typed} is an address"); + } + for typed in ["ann", "ann@", "@example.com", "ann@example", "ann reed@example.com", "ann@.com", "a@b@c.com", ""] { + assert!(address(typed).is_none(), "{typed} is not an address"); + } + assert_eq!(address(" ann@example.com "), Some("ann@example.com".to_owned()), "the trim is kept"); +} + +#[test] +fn initials_come_from_the_name_and_never_from_an_index() { + assert_eq!(initials("Ann Reed"), "AR"); + assert_eq!(initials("ann"), "A"); + assert_eq!(initials("Ann Marie Reed"), "AM"); + assert_eq!(initials(""), ""); + assert_eq!(initials(" "), ""); + assert_eq!(initials("Ærø Ødegård"), "ÆØ"); + assert_eq!(initials("张 伟"), "张伟"); +} + +#[test] +fn every_kind_of_recipient_reads_as_something() { + let labels = ShareLabels::default(); + assert_eq!(target_label(&ShareTarget::User("ann".into()), &labels), "ann"); + assert_eq!(target_label(&ShareTarget::Group("finance".into()), &labels), "finance (group)"); + assert_eq!(target_label(&ShareTarget::Email("ann@example.com".into()), &labels), "ann@example.com"); + assert_eq!(target_label(&ShareTarget::Link, &labels), "Anyone with the link"); +} + +#[test] +fn a_failure_with_no_detail_still_says_something() { + let bare = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: " ".into() }; + assert_eq!(describe(&bare), "forbidden"); + let told = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: "link shares are off".into() }; + assert_eq!(describe(&told), "link shares are off"); +} + +#[test] +fn two_contacts_never_share_one_picture_cache_entry() { + let one = avatar_uri("https://cloud.example.com/avatar/ann/64"); + let two = avatar_uri("https://cloud.example.com/avatar/anna/64"); + assert_ne!(one, two); + assert_eq!(one, avatar_uri("https://cloud.example.com/avatar/ann/64"), "the same URL is the same entry"); + assert!(one.starts_with("bytes://"), "egui's own loaders have to recognize it"); +} + +fn ready_unsaved() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + (ctx, dialog, backend) +} + +fn start_save(dialog: &mut ShareDialog, ctx: &Context, destination: &str, name: &str) -> u64 { + dialog.apply(ctx, vec![Act::SaveAs { destination: destination.into(), name: name.into() }]); + let request = dialog.take_save_request().expect("save was handed to the application"); + assert_ne!(request.generation, 0, "taken saves carry the open sheet generation"); + request.generation +} + +#[test] +fn a_stale_save_completion_after_close_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + assert!(!dialog.is_open()); + + dialog.saved("files/wrong.xlsx", "Wrong"); + dialog.saved_if(generation, "files/wrong.xlsx", "Wrong"); + assert!(!dialog.is_open()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/wrong.xlsx")), + "a completion after close must not ask about the saved handle" + ); +} + +#[test] +fn a_stale_save_completion_after_reopening_another_document_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + dialog.open("files/other.xlsx", "Other"); + assert_eq!(dialog.open.as_ref().map(|s| s.id.as_str()), Some("files/other.xlsx")); + + dialog.saved("files/budget.xlsx", "Budget"); + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("still open on the other document"); + assert_eq!(sheet.id, "files/other.xlsx"); + assert_eq!(sheet.title, "Other"); + assert!(sheet.saving.is_none()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx")), + "the first document's completion must not rebind the second" + ); +} + +#[test] +fn a_save_completion_on_the_same_open_updates_the_sheet() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.id, "files/budget.xlsx"); + assert_eq!(sheet.title, "Budget"); + assert!(sheet.saving.is_none()); + assert!(backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx"))); +} + +#[test] +fn take_save_request_returns_the_open_sheet_generation() { + let (ctx, mut dialog, _) = ready_unsaved(); + let before = dialog.sheet_generation(); + assert_ne!(before, 0); + dialog.apply(&ctx, vec![Act::SaveAs { destination: "cloud".into(), name: "Budget".into() }]); + let request = dialog.take_save_request().expect("taken"); + assert_eq!(request.generation, before); + assert_eq!(request.destination, "cloud"); + assert_eq!(request.name, "Budget"); +} + +#[test] +fn a_closed_dialog_still_collects_and_reports_nothing() { + let (ctx, mut dialog, _) = ready(); + dialog.close(); + assert!(!dialog.is_open()); + dialog.receive(&ctx, 99, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, 99, Err("gone".into())); + let (shared, failed) = dialog.outcome(); + assert!(shared.is_empty() && failed.is_empty()); +} + +#[test] +fn pressing_return_takes_the_first_match_or_an_address() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + + // With matches on screen, Return takes the one at the top. + sheet.query = "an".into(); + sheet.matches = vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw")]; + commit(sheet); + assert_eq!(sheet.chosen.first().map(|c| &c.target), Some(&ShareTarget::User("ann".into()))); + + // With none, an address is taken as itself. Somebody with no account on + // this server is reached by address or not at all. + sheet.query = "outside@example.com".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.chosen.last().map(|c| &c.target), Some(&ShareTarget::Email("outside@example.com".into()))); + + // A name that matched nothing is not a recipient. + sheet.query = "nobody".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.query, "nobody", "and what was typed is left alone to be corrected"); +} diff --git a/crates/ui/tests/renders.rs b/crates/ui/tests/renders.rs new file mode 100644 index 000000000..9f1f5a37c --- /dev/null +++ b/crates/ui/tests/renders.rs @@ -0,0 +1,343 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! Renders of the shared controls, for review. +//! +//! The other suites read the accessibility tree and never look at pixels. That +//! catches wrong wording and missing names. It cannot show whether a dialog +//! looks like it belongs in an office suite, and these two controls will sit in +//! every Craft app, so somebody has to be able to see them. +//! +//! Writes nothing unless `CRAFT_UI_RENDERS` names a directory. A suite that +//! wrote files on every run would turn a checkout dirty by testing it. +//! +//! ```sh +//! CRAFT_UI_RENDERS=/tmp/renders cargo test -p craft-ui --all-features --test renders +//! ``` + +use std::cell::RefCell; +use std::path::PathBuf; +use std::rc::Rc; +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_ui::account::{Account, AccountMenu}; +use craft_ui::presence::{Peer, PresenceBar}; +use craft_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, PointerButton, Pos2, RawInput, Rect, Theme, Visuals, accesskit, pos2, vec2}; +use egui_kittest::{TestRenderer, wgpu::WgpuTestRenderer}; + +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +/// A backend that answers what a control needs and parks the rest. +#[derive(Clone, Default)] +struct Fake { + capabilities: Vec, + access: Vec, + parked: Arc>>, +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => { + if let Ok(mut parked) = self.parked.lock() { + parked.push((request, reply)); + } + } + } + } +} + +impl Fake { + fn answer(&self, answer: Answer) { + let taken = self.parked.lock().ok().and_then(|mut p| if p.is_empty() { None } else { Some(p.remove(0)) }); + if let Some((_, reply)) = taken { + reply.answer(answer); + } + } +} + +/// One control, driven frame by frame, with the pixels kept. +struct Shot { + ctx: Context, + /// One renderer per context. A renderer shared between two contexts + /// takes a texture id from the first and is then asked by the second + /// to free one it never registered. + renderer: WgpuTestRenderer, + time: f64, + size: [f32; 2], + typing: bool, + /// The ground the control is painted on. Without it the render carries a + /// transparent background, which reads as a rendering fault. + fill: egui::Color32, +} + +impl Shot { + fn new(theme: Theme, size: [f32; 2]) -> Shot { + let ctx = Context::default(); + ctx.enable_accesskit(); + let visuals = if theme == Theme::Dark { Visuals::dark() } else { Visuals::light() }; + let fill = visuals.panel_fill; + ctx.set_visuals(visuals); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + Shot { ctx, renderer: WgpuTestRenderer::new(), time: 0.0, size, typing: false, fill } + } + + fn frame(&mut self, events: Vec, mut draw: impl FnMut(&mut egui::Ui)) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(self.size[0], self.size[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let fill = self.fill; + let size = self.size; + let mut output = ctx.run_ui(raw, |ui| { + let screen = Rect::from_min_size(Pos2::ZERO, vec2(size[0], size[1])); + ui.painter().rect_filled(screen, 0.0, fill); + draw(ui); + }); + // Every frame's delta has to reach the renderer. The font atlas arrives + // on the first frame, and a renderer that saw only the last one paints + // no text at all. + self.renderer.handle_delta(&mut output.textures_delta); + output + } + + /// Write what the last frame drew. + fn save(&mut self, into: &std::path::Path, name: &str, theme: Theme, output: &FullOutput) { + let image = self.renderer.render(&self.ctx, output).expect("an offscreen renderer is required to write renders"); + let suffix = if theme == Theme::Dark { "dark" } else { "light" }; + let path = into.join(format!("{name}-{suffix}.png")); + image.save(&path).expect("the render directory must be writable"); + println!("wrote {}", path.display()); + } + + /// Press the control carrying this exact accessible name. + fn click(&mut self, label: &str, draw: &mut impl FnMut(&mut egui::Ui)) { + let output = self.frame(Vec::new(), &mut *draw); + let Some(at) = control(&output, label) else { panic!("nothing to click named {label:?}; on screen are {:?}", controls(&output)) }; + self.frame(vec![Event::PointerMoved(at)], &mut *draw); + self.frame(vec![press(at, true)], &mut *draw); + self.frame(vec![press(at, false)], &mut *draw); + } +} + +fn press(at: Pos2, down: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: down, modifiers: egui::Modifiers::default() } +} + +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::TextInput | accesskit::Role::CheckBox | accesskit::Role::Link) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(update) = &output.platform_output.accesskit_update else { return Vec::new() }; + update + .nodes + .iter() + .filter_map(|(_, node)| { + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn ordinary() -> Vec { + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::ShareNotify, Capability::LinkShares] +} + +#[test] +fn renders_of_every_state_in_both_themes() { + let Ok(directory) = std::env::var("CRAFT_UI_RENDERS") else { + println!("set CRAFT_UI_RENDERS to a directory to write renders"); + return; + }; + let into = PathBuf::from(directory); + std::fs::create_dir_all(&into).expect("the render directory must be creatable"); + for theme in [Theme::Light, Theme::Dark] { + // ---- the account control ------------------------------------------- + let mut shot = Shot::new(theme, [320.0, 300.0]); + // A fresh menu is a signed-out one, which is the first state. + let mut draw = { + let mut menu = AccountMenu::new(); + move |ui: &mut egui::Ui| menu.show(ui) + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "account-signed-out", theme, &output); + + for (name, linked) in [("account-no-storage", false), ("account-linked", true)] { + let mut shot = Shot::new(theme, [320.0, 300.0]); + let mut draw = { + let mut menu = AccountMenu::new(); + menu.set(vec![ + Account { + id: "work".into(), + display: "Will Dunn".into(), + email: Some("will@example.com".into()), + service: "collabcraft.example.com".into(), + linked, + }, + Account { + id: "personal".into(), + display: "Will at home".into(), + email: Some("will@example.net".into()), + service: "cloud.example.net".into(), + linked: true, + }, + ]); + move |ui: &mut egui::Ui| menu.show(ui) + }; + // The menu is behind the badge, so it takes a press to show. + shot.click("Account, Will Dunn", &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- who else is here ---------------------------------------------- + let mut shot = Shot::new(theme, [420.0, 80.0]); + let mut bar = PresenceBar::new(); + bar.set(vec![ + Peer::new("s1", "Ann Reed").at("editing B4"), + Peer::new("s2", "Bob Vine").at("editing D12"), + Peer::new("s3", "Cal Nye"), + Peer::new("s4", "Dee Shaw"), + Peer::new("s5", "Eve Marsh"), + Peer::new("s6", "Fay Orr"), + ]); + let mut draw = move |ui: &mut egui::Ui| { + ui.add_space(24.0); + bar.show(ui); + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "presence", theme, &output); + + // ---- the share dialog ---------------------------------------------- + let cases: Vec<(&str, Vec, Vec, &str)> = vec![ + ("dialog-fresh", ordinary(), Vec::new(), DOCUMENT), + ( + "dialog-who-has-access", + ordinary(), + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + DOCUMENT, + ), + ("dialog-no-link-shares", vec![Capability::Sharing, Capability::Contacts], Vec::new(), DOCUMENT), + ("dialog-unsaved", ordinary(), Vec::new(), ""), + ]; + + for (name, capabilities, access, id) in cases { + let mut shot = Shot::new(theme, [620.0, 560.0]); + let fake = Fake { capabilities, access, parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + // One frame asks what the provider can do, the next reads the answer. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(id.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- recipients picked, then one of them refused ------------------- + let fake = Fake { capabilities: ordinary(), access: Vec::new(), parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + let mut shot = Shot::new(theme, [620.0, 560.0]); + // One frame asks what the provider can do, the next reads the answer. + // Opening before that answer arrives does nothing, which is the point + // of a control that refuses to appear when it cannot work. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(DOCUMENT.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + shot.typing = true; + shot.frame(vec![Event::Text("an".to_owned())], &mut draw); + shot.time += 0.25; + shot.frame(Vec::new(), &mut draw); + fake.answer(Answer::Lookup(vec![person("ann", "Ann Reed")])); + shot.frame(Vec::new(), &mut draw); + shot.click("Ann Reed", &mut draw); + shot.typing = false; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-recipients", theme, &output); + + shot.click("Send", &mut draw); + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-partial-failure", theme, &output); + } +} diff --git a/crates/ui/tests/share_dialog.rs b/crates/ui/tests/share_dialog.rs new file mode 100644 index 000000000..50dd60df4 --- /dev/null +++ b/crates/ui/tests/share_dialog.rs @@ -0,0 +1,589 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! The share dialog driven through its real widgets, offscreen. +//! +//! Every assertion here reads the accessibility tree the dialog actually +//! produced, or the requests it actually sent, rather than its private state. +//! No window is opened, no GPU is touched and no server is contacted: the +//! backend is a fake that parks each request until a test answers it, which is +//! also how answers are made to arrive late or in the wrong order. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, Modifiers, PointerButton, Pos2, RawInput, Rect, accesskit, pos2, vec2}; + +const SCREEN: [f32; 2] = [620.0, 900.0]; +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +#[derive(Default)] +struct Log { + seen: Vec, + parked: Vec<(Request, Replier)>, +} + +/// A backend that answers what the dialog needs to get going and parks the +/// rest, so a test decides when each answer arrives. +#[derive(Clone)] +struct Fake { + log: Arc>, + capabilities: Vec, + access: Vec, +} + +impl Fake { + fn new(capabilities: Vec, access: Vec) -> Fake { + Fake { log: Arc::new(Mutex::new(Log::default())), capabilities, access } + } + + fn seen(&self) -> Vec { + self.log.lock().map(|log| log.seen.clone()).unwrap_or_default() + } + + fn parked(&self) -> Vec { + self.log.lock().map(|log| log.parked.iter().map(|(r, _)| r.clone()).collect()).unwrap_or_default() + } + + /// Answer the request that has waited longest, which is the ordinary case. + fn answer(&self, answer: Answer) { + self.answer_nth(0, answer); + } + + /// Answer the request parked at `index`, oldest first, so a test can + /// deliver a late answer after a newer one. + fn answer_nth(&self, index: usize, answer: Answer) { + let Some((_, reply)) = self.take(index) else { panic!("nothing is waiting at {index}") }; + reply.answer(answer); + } + + /// Take one parked request back, to refuse it or inspect its contents. + fn take(&self, index: usize) -> Option<(Request, Replier)> { + self.log.lock().ok().and_then(|mut log| if index < log.parked.len() { Some(log.parked.remove(index)) } else { None }) + } +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + let Ok(mut log) = self.log.lock() else { return }; + log.seen.push(request.clone()); + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => log.parked.push((request, reply)), + } + } +} + +struct Harness { + ctx: Context, + dialog: ShareDialog, + time: f64, + typing: bool, +} + +impl Harness { + fn new(capabilities: Vec, access: Vec) -> (Harness, Fake) { + let ctx = Context::default(); + ctx.enable_accesskit(); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + let fake = Fake::new(capabilities, access); + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let mut harness = Harness { ctx, dialog, time: 0.0, typing: false }; + // One frame asks what the provider can do, the next reads the answer. + harness.frame(Vec::new()); + harness.frame(Vec::new()); + (harness, fake) + } + + /// An ordinary deployment: files, sharing, contacts and mail. + fn everything() -> (Harness, Fake) { + Harness::new( + // Everything, which has to include ShareNotify. Notifying a + // recipient of a share is a separate ability from sending + // arbitrary mail, and the box is gated on the former. + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::Mail, Capability::ShareNotify], + Vec::new(), + ) + } + + fn frame(&mut self, events: Vec) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(SCREEN[0], SCREEN[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + // Keeping the recipient field focused is what a user holding the + // caret there does; nothing else in the dialog wants focus. + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let dialog = &mut self.dialog; + let mut output = ctx.run_ui(raw, |ui| dialog.show_in(ui)); + output.textures_delta.clear(); + output + } + + /// Let the clock run, for the debounce. + fn wait(&mut self, seconds: f64) -> FullOutput { + self.time += seconds; + self.frame(Vec::new()) + } + + fn open(&mut self) { + self.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(self.dialog.is_open(), "the dialog should have opened"); + self.frame(Vec::new()); + } + + /// Type into the recipient field, then let the debounce elapse. + fn type_and_settle(&mut self, text: &str) { + self.typing = true; + self.frame(vec![Event::Text(text.to_owned())]); + self.wait(0.25); + } + + fn click(&mut self, label: &str) { + let output = self.frame(Vec::new()); + let Some(at) = control(&output, label) else { + panic!("nothing to click labelled {label:?}; the controls on screen are {:?}", controls(&output)) + }; + self.frame(vec![Event::PointerMoved(at)]); + self.frame(vec![press(at, true)]); + self.frame(vec![press(at, false)]); + self.frame(Vec::new()); + } +} + +fn press(at: Pos2, pressed: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed, modifiers: Modifiers::NONE } +} + +fn key(key: egui::Key) -> Event { + Event::Key { key, physical_key: None, pressed: true, repeat: false, modifiers: Modifiers::NONE } +} + +/// One widget as the accessibility tree reported it. +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + /// Something a pointer can act on, as opposed to a piece of text. + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::RadioButton | accesskit::Role::CheckBox) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +/// Where to click the control carrying this exact label. +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +/// The buttons alone, which is what a chip and a match row are. +fn buttons(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(|s| s.role == accesskit::Role::Button).map(|s| s.label).collect() +} + +/// Every piece of text on screen, for asserting what the user was told. +fn text(output: &FullOutput) -> Vec { + seen(output).into_iter().map(|s| s.label).collect() +} + +/// The primary action, taken from the defaults the dialog actually draws. +/// A literal here drifts the moment the wording changes. +const SEND: &str = "Send"; + +/// The permission dropdown, chevron included. It is a menu, not a toggle. +const PERMISSION: &str = "View"; + +fn says(output: &FullOutput, fragment: &str) -> bool { + text(output).iter().any(|line| line.contains(fragment)) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn group(id: &str, name: &str) -> Contact { + Contact { id: id.into(), target: ShareTarget::Group(id.into()), name: name.into(), email: None, avatar: None, is_group: true } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn lookup(found: Vec) -> Answer { + Answer::Lookup(found) +} + +// ---- the picker ----------------------------------------------------------- + +#[test] +fn typing_a_few_letters_offers_matches_and_picking_them_builds_chips() { + let (mut h, fake) = Harness::everything(); + h.open(); + + h.type_and_settle("an"); + h.frame(Vec::new()); + assert_eq!( + fake.parked(), + vec![Request::Lookup { query: "an".into(), limit: 8 }], + "one lookup for the whole burst of typing, not one per keystroke" + ); + + fake.answer(lookup(vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw"), group("finance", "Finance")])); + let output = h.frame(Vec::new()); + for name in ["Ann Reed", "Andy Shaw", "Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be offered; saw {:?}", buttons(&output)); + } + + // Three recipients, picked one after another. Each lands as a chip whose + // whole body is the control that takes it back again. + h.click("Ann Reed"); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("andy", "Andy Shaw")])); + h.frame(Vec::new()); + h.click("Andy Shaw"); + h.type_and_settle("fin"); + fake.answer(lookup(vec![group("finance", "Finance")])); + h.frame(Vec::new()); + h.click("Finance"); + + let output = h.frame(Vec::new()); + for name in ["Remove Ann Reed", "Remove Andy Shaw", "Remove Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be a chip; saw {:?}", buttons(&output)); + } +} + +#[test] +fn a_chip_takes_one_recipient_back_and_leaves_the_others() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine")), ("ca", person("cal", "Cal Nye"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + + h.click("Remove Bob Vine"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove Ann Reed")); + assert!(buttons(&output).iter().any(|b| b == "Remove Cal Nye")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Bob Vine"), "the removed chip is gone; saw {:?}", buttons(&output)); + + // And the share that follows carries the two that are left. + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::User("ann".into()), ShareTarget::User("cal".into())]); +} + +#[test] +fn an_answer_the_user_has_typed_past_never_reaches_the_list() { + let (mut h, fake) = Harness::everything(); + h.open(); + + // Two bursts of typing, so two lookups are outstanding at once. + h.type_and_settle("an"); + h.frame(Vec::new()); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert_eq!(fake.parked().len(), 2); + + // The newer one answers first and the older one arrives late, which is + // what a service under load does. + fake.answer_nth(1, lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + fake.answer_nth(0, lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")])); + let output = h.frame(Vec::new()); + + assert!(buttons(&output).iter().any(|b| b == "Ann Reed"), "the current answer stays"); + assert!(!says(&output, "Andy Shaw"), "the stale answer must not flicker in"); + assert!(!says(&output, "Anna Beck")); +} + +#[test] +fn one_letter_is_not_worth_asking_about() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("a"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "a single letter matches most of an address book"); + + h.frame(vec![Event::Text("n".to_owned())]); + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "an".into(), limit: 8 }]); +} + +#[test] +fn nothing_is_asked_until_the_typing_stops() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.typing = true; + // Five keystrokes inside the debounce window. + for letter in ["a", "n", "n", "i", "e"] { + h.frame(vec![Event::Text(letter.to_owned())]); + h.wait(0.03); + } + assert!(fake.parked().is_empty(), "nothing asked while the user is still typing"); + + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "annie".into(), limit: 8 }], "one question for the whole word"); +} + +// ---- what a share says ---------------------------------------------------- + +#[test] +fn sharing_with_five_where_one_address_is_wrong_names_the_one_that_failed() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + h.click(SEND); + + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = h.frame(Vec::new()); + + assert!(says(&output, "Shared with"), "the ones that went through are named"); + assert!(says(&output, "ann")); + assert!(says(&output, "Not shared with"), "and so is the one that did not"); + assert!(says(&output, "bob@example.con was rejected"), "with the reason, not a count; saw {:?}", text(&output)); + + // The failed recipient stays in the picker so a correction is one edit. + assert!(buttons(&output).iter().any(|b| b == "Remove Bob Vine")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Ann Reed"), "the one that worked has left"); +} + +#[test] +fn a_refusal_that_stopped_everything_is_shown_as_itself() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let Some((_, reply)) = fake.take(0) else { panic!("expected a share in flight") }; + reply.refuse("sign in again"); + let output = h.frame(Vec::new()); + + assert!(says(&output, "sign in again")); + assert!(!says(&output, "Not shared with"), "a refusal is not a per-recipient failure"); + assert!(control(&output, SEND).is_some(), "the button comes back"); +} + +#[test] +fn a_note_and_a_permission_travel_with_the_share() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + // The permission is a menu now, so it takes opening before choosing. + h.click(PERMISSION); + h.click("Edit"); + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.permission, Permission::Edit); + assert_eq!(grant.id, DOCUMENT, "the handle goes back untouched"); + assert!(grant.notify, "mail works here, and the box is ticked by default"); + assert_eq!(grant.note, None, "an empty note is no note"); +} + +#[test] +fn a_server_that_cannot_send_mail_is_never_promised_a_notification() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing, Capability::Contacts], Vec::new()); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert!(!grant.notify, "a checkbox for mail a server cannot send must not be honoured"); +} + +#[test] +fn a_server_without_contacts_asks_nobody_anything() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing], Vec::new()); + h.open(); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "there is no address book to search"); +} + +// ---- who already has access ---------------------------------------------- + +#[test] +fn who_has_access_is_listed_and_one_can_be_withdrawn() { + let (mut h, fake) = Harness::new( + vec![Capability::Sharing, Capability::Contacts, Capability::Mail], + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + ); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Who has access")); + assert!(says(&output, "ann")); + assert!(says(&output, "finance (group)")); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 2); + + h.click("Withdraw"); + assert!(fake.seen().iter().any(|r| matches!(r, Request::Withdraw { share_id } if share_id == "s1" || share_id == "s2"))); + + // It stays on the list until the server agrees it is gone. + let output = h.frame(Vec::new()); + assert!(says(&output, "Withdrawing…")); + let Some((Request::Withdraw { share_id }, reply)) = fake.take(0) else { panic!("expected a withdrawal in flight") }; + reply.answer(Answer::Withdrawn { share_id: share_id.clone() }); + let output = h.frame(Vec::new()); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 1, "one left"); +} + +#[test] +fn a_document_nobody_has_been_given_says_so() { + let (mut h, _fake) = Harness::everything(); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Nobody else yet")); +} + +// ---- what the dialog refuses to offer ------------------------------------- + +#[test] +fn a_server_without_sharing_draws_no_dialog_at_all() { + let (mut h, fake) = Harness::new(vec![Capability::Files, Capability::Contacts], Vec::new()); + assert!(!h.dialog.available()); + h.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(!h.dialog.is_open(), "a feature the provider lacks is hidden, not offered"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty(), "nothing to click; saw {:?}", buttons(&output)); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. })), "and nothing was asked about the document"); +} + +#[test] +fn an_unsaved_document_is_told_to_save_rather_than_refused_by_the_server() { + let (mut h, fake) = Harness::everything(); + h.dialog.open("", "Book1"); + let output = h.frame(Vec::new()); + assert!(says(&output, "Save this document somewhere to share it.")); + assert!(control(&output, SEND).is_none(), "there is nothing to share yet"); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. }))); +} + +#[test] +fn closing_puts_the_dialog_away() { + let (mut h, _fake) = Harness::everything(); + h.open(); + h.click("Close"); + assert!(!h.dialog.is_open()); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty()); +} + +#[test] +fn a_typed_address_says_how_to_add_it_and_adding_it_works() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("outside@example.com"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "Press Return to share with this address"), "saw {:?}", text(&output)); + assert!(!says(&output, "No matches"), "an address that matched nobody is still a recipient"); + + // Return takes it, and the share carries it as an address. + h.frame(vec![key(egui::Key::Enter)]); + h.frame(Vec::new()); + h.typing = false; + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove outside@example.com"), "saw {:?}", buttons(&output)); + + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::Email("outside@example.com".into())]); +} + +#[test] +fn a_name_that_matched_nobody_is_not_offered_as_an_address() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("nobody"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "No matches")); + assert!(!says(&output, "Press Return")); +} From b1fce2be7483d345e40d5f02e1ee66f3899e5d8e Mon Sep 17 00:00:00 2001 From: William Dunn Date: Wed, 11 Nov 2026 09:52:15 -0500 Subject: [PATCH 03/97] craft-ui cloud pages: move off deprecated egui aliases The current egui pin denies the deprecated egui::WidgetType alias and egui::Id::new. The slice's pages (account, cloud, share, presence, the menu helper) move to egui::Role::Button and egui::Id::unique, the same spellings main's craft-ui already uses. --- crates/ui/src/account.rs | 8 ++++---- crates/ui/src/cloud/mod.rs | 2 +- crates/ui/src/cloud/pages.rs | 2 +- crates/ui/src/menu.rs | 6 +++--- crates/ui/src/presence.rs | 4 ++-- crates/ui/src/share/mod.rs | 12 ++++++------ 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/crates/ui/src/account.rs b/crates/ui/src/account.rs index d83214500..9c8921064 100644 --- a/crates/ui/src/account.rs +++ b/crates/ui/src/account.rs @@ -243,7 +243,7 @@ impl AccountMenu { let label = format!("{}\n{}", one.display, one.service); let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); let name = one.display.clone(); - row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); if row.clicked() { let _ = tx.send(AccountAction::Use(one.id.clone())); ui.close(); @@ -263,7 +263,7 @@ impl AccountMenu { let badge = egui::Button::new(RichText::new(account.initial()).strong()).min_size(egui::vec2(26.0, 26.0)).corner_radius(13.0); let hit = ui.add(badge); let spoken = labels.badge.replace("{name}", &account.display); - hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, spoken.as_str())); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, spoken.as_str())); let hit = hit.on_hover_text(account.display.as_str()); egui::Popup::menu(&hit).show(|ui| { @@ -321,7 +321,7 @@ impl AccountMenu { let label = format!("{}\n{}", other.display, other.service); let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); let name = other.display.clone(); - row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); if row.clicked() { let _ = tx.send(AccountAction::Use(other.id.clone())); ui.close(); @@ -347,7 +347,7 @@ impl AccountMenu { /// Draw the badge in a context that has no `Ui` to hand. pub fn show_in_ctx(&mut self, ctx: &Context) { - egui::Area::new(egui::Id::new("craft-ui/account")).anchor(egui::Align2::RIGHT_TOP, egui::vec2(-8.0, 8.0)).show(ctx, |ui| { + egui::Area::new(egui::Id::unique("craft-ui/account")).anchor(egui::Align2::RIGHT_TOP, egui::vec2(-8.0, 8.0)).show(ctx, |ui| { self.show(ui); }); } diff --git a/crates/ui/src/cloud/mod.rs b/crates/ui/src/cloud/mod.rs index 220afc04e..a8d001a0b 100644 --- a/crates/ui/src/cloud/mod.rs +++ b/crates/ui/src/cloud/mod.rs @@ -837,7 +837,7 @@ fn entry_row(app: &A, ui: &mut Ui, entry: &Entry, detail: &str, res let width = (ui.available_width() - reserve).max(60.0); let (rect, resp) = ui.allocate_exact_size(vec2(width, 40.0), Sense::click()); let label = entry.name.clone(); - resp.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, &label)); + resp.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, &label)); let p = ui.painter(); if resp.hovered() { p.rect_filled(rect, 4.0, style.hover); diff --git a/crates/ui/src/cloud/pages.rs b/crates/ui/src/cloud/pages.rs index fa1ead8be..b8187cf67 100644 --- a/crates/ui/src/cloud/pages.rs +++ b/crates/ui/src/cloud/pages.rs @@ -469,7 +469,7 @@ pub fn conflict_modal(app: &mut A, ctx: &egui::Context) { let mut reload = false; let mut copy = false; let mut dismiss = false; - egui::Modal::new(egui::Id::new("craft-ui/cloud/conflict")).show(ctx, |ui| { + egui::Modal::new(egui::Id::unique("craft-ui/cloud/conflict")).show(ctx, |ui| { let style = app.style(ui); ui.set_width(430.0); ui.label(RichText::new(&words.title).font(egui::FontId::new(15.0, style.bold.clone()))); diff --git a/crates/ui/src/menu.rs b/crates/ui/src/menu.rs index 2b18340bf..70189a56f 100644 --- a/crates/ui/src/menu.rs +++ b/crates/ui/src/menu.rs @@ -104,7 +104,7 @@ pub fn overflow(ui: &mut Ui, items: &[MenuItem], labels: &MenuLabels) -> Option< let button = egui::Button::new(RichText::new("\u{2026}").size(15.0)).frame(false); let hit = ui.add(button); let name = labels.more.clone(); - hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); let hit = hit.on_hover_text(labels.more.as_str()); items_of(&hit, items) } @@ -142,7 +142,7 @@ pub fn split(ui: &mut Ui, primary: &str, items: &[MenuItem], labels: &MenuLabels let more = ui.add(egui::Button::new(" ").corner_radius(if backwards { outer } else { inner })); crate::buttons::chevron(ui, more.rect, ui.visuals().text_color()); let name = labels.more_for.replace("{action}", &primary.to_lowercase()); - more.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + more.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); let more = more.on_hover_text(name.as_str()); if let Some(id) = items_of(&more, items) { *hit = Some(SplitHit::Item(id)); @@ -177,7 +177,7 @@ fn items_of(anchor: &Response, items: &[MenuItem]) -> Option { // The icon is decoration. The name is the label alone. let name = item.label.clone(); let enabled = item.enabled; - row.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, enabled, name.as_str())); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, enabled, name.as_str())); if row.clicked() { chosen = Some(item.id.clone()); ui.close(); diff --git a/crates/ui/src/presence.rs b/crates/ui/src/presence.rs index 1da9327d9..f429691bc 100644 --- a/crates/ui/src/presence.rs +++ b/crates/ui/src/presence.rs @@ -283,7 +283,7 @@ impl PresenceBar { let more = self.labels.and_more.replace("{count}", &hidden.to_string()); let weak = ui.visuals().widgets.inactive.bg_fill; let badge = badge(ui, &format!("+{hidden}"), weak, ui.visuals().text_color()); - badge.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, more.as_str())); + badge.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, more.as_str())); badge.on_hover_text(self.peers.iter().skip(self.shown).map(|p| p.display.as_str()).collect::>().join("\n")); } let ids: Vec = self.peers.iter().map(|p| p.id.clone()).collect(); @@ -292,7 +292,7 @@ impl PresenceBar { let ink = colours.get(at).copied().unwrap_or_else(|| peer.colour()); let hit = badge(ui, &peer.initial(), ink, Color32::WHITE); let name = peer.display.clone(); - hit.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, name.as_str())); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); let tip = match &peer.at { Some(at) => format!("{}\n{at}", peer.display), None => peer.display.clone(), diff --git a/crates/ui/src/share/mod.rs b/crates/ui/src/share/mod.rs index 5dbcf6c06..e38067411 100644 --- a/crates/ui/src/share/mod.rs +++ b/crates/ui/src/share/mod.rs @@ -566,7 +566,7 @@ impl ShareDialog { /// The recipient field's id, for an application that wants to focus it. pub fn query_field_id() -> Id { - Id::new(QUERY) + Id::unique(QUERY) } /// One frame, as a modal over the window. Call this unconditionally: @@ -576,7 +576,7 @@ impl ShareDialog { if self.open.is_none() { return; } - let modal = egui::Modal::new(Id::new("craft-ui/share")).show(ctx, |ui| { + let modal = egui::Modal::new(Id::unique("craft-ui/share")).show(ctx, |ui| { ui.set_min_width(440.0); ui.set_max_width(560.0); self.contents(ui); @@ -1076,7 +1076,7 @@ fn permission_menu(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels) { crate::buttons::chevron(ui, button.rect, ui.visuals().text_color()); // The padding makes room for the triangle. It is layout, so it must not // reach anybody reading the screen aloud. - button.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, true, current)); + button.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, current)); egui::Popup::menu(&button).show(|ui| { ui.set_min_width(190.0); for (value, name, detail) in [ @@ -1277,7 +1277,7 @@ fn access(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, weak: Color32, acts: // A glyph is not a name. Left alone this button announces itself // to a screen reader as a wastebasket character, so the word goes // on explicitly. - pressed.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, !busy, hint)); + pressed.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, !busy, hint)); if pressed.on_hover_text(hint).clicked() { acts.push(Act::Withdraw(share.id.clone())); } @@ -1322,7 +1322,7 @@ fn chip(ui: &mut Ui, avatars: &HashMap, chosen: &Chosen, labels: let fill = if response.hovered() { ui.visuals().widgets.hovered.bg_fill } else { ui.visuals().widgets.inactive.bg_fill }; ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(AVATAR_RADIUS), fill)); let label = format!("{} {}", labels.remove, chosen.label); - response.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, ui.is_enabled(), label.clone())); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); // The address, where there is one. Two colleagues share a display name // often enough that a chip reading "Ann Reed" is not an identity. let hint = match &chosen.detail { @@ -1358,7 +1358,7 @@ fn row(ui: &mut Ui, avatars: &HashMap, contact: &Contact, labels ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(4), ui.visuals().widgets.hovered.bg_fill)); } let label = contact.name.clone(); - response.widget_info(|| egui::WidgetInfo::labeled(egui::WidgetType::Button, ui.is_enabled(), label.clone())); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); response } From 07d2747efcd1860e062bbd7a29f1efec07ab3a11 Mon Sep 17 00:00:00 2001 From: William Dunn Date: Wed, 11 Nov 2026 10:02:58 -0500 Subject: [PATCH 04/97] craft-cloud-local: collapse the etag conflict check into one let chain The current clippy denies collapsible_if here. Behaviour is unchanged. A missing file still has nothing to conflict with. --- crates/cloud-local/src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs index c9c11c015..7f7f56590 100644 --- a/crates/cloud-local/src/lib.rs +++ b/crates/cloud-local/src/lib.rs @@ -190,10 +190,10 @@ fn read(root: &Path, entry: &Entry) -> Result, Fault> { /// conflict with, the same way a provider treats a deleted document. fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { let file = resolve(root, &entry.id)?; - if let Ok(meta) = fs::metadata(&file) { - if Some(etag_of(&meta)) != entry.etag { - return Err(Fault::Conflict); - } + if let Ok(meta) = fs::metadata(&file) + && Some(etag_of(&meta)) != entry.etag + { + return Err(Fault::Conflict); } if let Some(parent) = file.parent() { fs::create_dir_all(parent).map_err(|error| io_fault(&error))?; From a1703412251e11b215a05494feda6f5a4c05cdee Mon Sep 17 00:00:00 2001 From: William Dunn Date: Wed, 11 Nov 2026 10:07:25 -0500 Subject: [PATCH 05/97] craft-cloud-local test: name the opened-documents type The current clippy warns on the inline Arc Mutex tuple type in the test harness. A named OpenedDocs alias carries the same meaning. --- Cargo.lock | 19 +++++++++++++++++++ crates/cloud-local/tests/backend.rs | 5 ++++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index 1ac11475f..5b17106b4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1616,6 +1616,24 @@ dependencies = [ "craft-media-testkit", ] +[[package]] +name = "craft-cloud" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-cloud-local" +version = "0.1.0" +dependencies = [ + "craft-cloud", + "craft-ui", + "egui", + "tempfile", +] + [[package]] name = "craft-cms" version = "0.1.0" @@ -3191,6 +3209,7 @@ dependencies = [ name = "craft-ui" version = "0.1.0" dependencies = [ + "craft-cloud", "craft-fonts-build", "craft-i18n", "eframe", diff --git a/crates/cloud-local/tests/backend.rs b/crates/cloud-local/tests/backend.rs index 4176672f1..d2a9fd4e5 100644 --- a/crates/cloud-local/tests/backend.rs +++ b/crates/cloud-local/tests/backend.rs @@ -12,6 +12,9 @@ use craft_ui::cloud::{self, Account, CloudApp, CloudFiles, Destination, Document const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + /// The least a [`CloudApp`] can be. What it was told to open is recorded, so a /// round trip can be checked by content and not only by the entry metadata /// `craft_ui` itself remembers. @@ -19,7 +22,7 @@ struct Harness { cloud: CloudFiles, share: craft_ui::share::ShareDialog, presence: craft_ui::presence::PresenceBar, - opened: Arc)>>>, + opened: OpenedDocs, said: Arc>>, } From b49ac50ed5fede61562711419189714b4c13d98c Mon Sep 17 00:00:00 2001 From: William Dunn Date: Thu, 12 Nov 2026 23:28:02 -0500 Subject: [PATCH 06/97] craft-ui cloud: fix conflict modal and session identity bugs Reload from the conflict modal now acts on the conflicted document's uid. Save as a copy acts on that same uid too. Neither acts on the active tab anymore. A window with more than one document open keeps them separate. Sign-out bumps an account generation. Sign-in bumps it too. Each clears busy. A job's reply carries the generation it was issued under. A reply from an older generation gets dropped. A stale session cannot restore its account or its files over a newer one. A job that never answers cannot refuse every save afterward. Regression tests for both pairs of findings run through a held backend that answers jobs on the test's own schedule. --- crates/ui/src/cloud/backend.rs | 26 ++- crates/ui/src/cloud/conflict_tests.rs | 236 ++++++++++++++++++++++++++ crates/ui/src/cloud/mod.rs | 38 ++++- crates/ui/src/cloud/pages.rs | 16 +- 4 files changed, 305 insertions(+), 11 deletions(-) create mode 100644 crates/ui/src/cloud/conflict_tests.rs diff --git a/crates/ui/src/cloud/backend.rs b/crates/ui/src/cloud/backend.rs index b6da57960..f92328cef 100644 --- a/crates/ui/src/cloud/backend.rs +++ b/crates/ui/src/cloud/backend.rs @@ -9,6 +9,8 @@ //! testable with no service running. A host supplies the half that does. This //! crate never learns what it reaches. +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::mpsc::Sender; use craft_cloud::{Capability, Conversation, Entry}; @@ -76,20 +78,36 @@ pub enum Event { /// the user finished there. A send after the window closed is not a failure. pub struct Post { tx: Sender, + /// The window's account generation as of the moment the job this answers + /// was issued, beside a handle to what it is now. A sign-out or a new + /// sign-in bumps the live value; a reply that arrives after is for a + /// session that is gone, and must not land on the one that replaced it. + generation: Arc, + issued: u64, } impl Post { - pub(crate) fn new(tx: Sender) -> Post { - Post { tx } + pub(crate) fn new(tx: Sender, generation: Arc) -> Post { + let issued = generation.load(Ordering::Relaxed); + Post { tx, generation, issued } } /// Another handle to the same place, for a worker that answers more than - /// once or hands the job on. + /// once or hands the job on. Carries the same generation: every answer to + /// one job was issued at the same moment, however many of them there are. pub fn dup(&self) -> Post { - Post { tx: self.tx.clone() } + Post { tx: self.tx.clone(), generation: self.generation.clone(), issued: self.issued } } + /// Delivers the event, unless the window has signed out or signed in + /// again since the job this answers was issued. Silently dropping it + /// there, rather than delivering it, is what keeps a late reply from + /// restoring the previous session's account, files or busy state on top + /// of whatever replaced it. pub fn send(&self, event: Event) { + if self.generation.load(Ordering::Relaxed) != self.issued { + return; + } let _ = self.tx.send(event); } } diff --git a/crates/ui/src/cloud/conflict_tests.rs b/crates/ui/src/cloud/conflict_tests.rs new file mode 100644 index 000000000..29a83799d --- /dev/null +++ b/crates/ui/src/cloud/conflict_tests.rs @@ -0,0 +1,236 @@ +//! Two risks a tabbed host runs that a single-document test cannot see: a document other than +//! the one a conflict or a job is about can be active when the answer lands, and a session that +//! ended can still have a job outstanding. +//! +//! `Tabs` is a host with two open documents (a tabbed window) and `Held` is a backend that keeps +//! every job so the test decides when, and with what, the service answers. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui_kittest::Harness; +use egui_kittest::kittest::Queryable; + +use super::*; + +const NOTES: DocumentKind = DocumentKind { extensions: &["note"], mimes: &["text/plain"], noun: "note", default_extension: "note" }; + +#[derive(Default)] +struct Log { + read: Vec, + encoded: Vec, + closed: Vec, + said: Vec, +} + +struct Tabs { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + active: u64, + next_uid: u64, + log: Arc>, +} + +impl CloudApp for Tabs { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTES + } + fn active(&self) -> Option { + Some(self.active) + } + fn title(&self, uid: u64) -> String { + format!("doc {uid}") + } + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.log.lock().unwrap().read.push(name.to_owned()); + self.next_uid += 1; + Ok(Some(self.next_uid)) + } + fn encode(&mut self, uid: u64, _into: Destination<'_>) -> Result, String> { + self.log.lock().unwrap().encoded.push(uid); + Ok(format!("bytes of {uid}").into_bytes()) + } + fn close(&mut self, uid: u64) { + self.log.lock().unwrap().closed.push(uid); + } + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.log.lock().unwrap().said.push(text); + } + fn app_name(&self) -> &str { + "Notes" + } +} + +#[derive(Clone, Default)] +struct Held(Arc>>); + +impl CloudBackend for Held { + fn submit(&self, job: Job, post: Post) { + self.0.lock().unwrap().push((job, post)); + } +} + +impl Held { + fn take(&self, pick: impl Fn(&Job) -> bool) -> Option<(Job, Post)> { + let mut held = self.0.lock().unwrap(); + let i = held.iter().position(|(j, _)| pick(j))?; + Some(held.remove(i)) + } +} + +fn entry(path: &str, etag: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.trim_start_matches('/').to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(10), + modified: None, + mime: None, + etag: Some(etag.to_owned()), + writable: true, + shared_by: None, + } +} + +fn account(name: &str) -> Account { + Account { display: name.to_owned(), capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +fn drain(app: &mut Tabs, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + ctx.end_pass().textures_delta.clear(); +} + +/// Two cloud documents open: uid 1 = A.note, uid 2 = B.note (B has unsaved edits). +fn two_tabs() -> (Tabs, Held, Arc>) { + let held = Held::default(); + let log = Arc::new(Mutex::new(Log::default())); + let mut app = Tabs { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + active: 1, + next_uid: 10, + log: log.clone(), + }; + app.cloud.connect(held.clone()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + app.cloud.origins.insert(2, Origin { entry: entry("/B.note", "b1") }); + (app, held, log) +} + +/// Save A, the user moves to tab B while the write is on the wire, the service refuses A's write +/// (Conflict). Returns the app with the conflict modal pending, active tab = B. +fn conflict_on_a_while_b_is_active() -> (Tabs, Held, Arc>) { + let (mut app, held, log) = two_tabs(); + save(&mut app).unwrap(); + app.active = 2; + let (job, post) = held.take(|j| matches!(j, Job::Write { .. })).unwrap(); + let Job::Write { uid, .. } = job else { unreachable!() }; + post.send(Event::Saved { uid, entry: Err(Fault::Conflict) }); + let ctx = egui::Context::default(); + drain(&mut app, &ctx); + assert_eq!(app.cloud.conflict.as_ref().map(|c| (c.uid, c.entry.name.clone())), Some((1, "A.note".to_owned()))); + (app, held, log) +} + +fn click_in_conflict_modal(app: Tabs, label: &str) -> Tabs { + let mut harness = Harness::new_ui_state(|ui, app: &mut Tabs| conflict_modal(app, &ui.ctx().clone()), app); + harness.run(); + harness.get_by_label(label).click(); + harness.run(); + harness.into_state() +} + +/// The modal says A.note was not saved; clicking "Reload from the cloud" must reload A and +/// replace uid 1, the conflicted document, never whichever tab happens to be active. +#[test] +fn conflict_reload_acts_on_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Reload from the cloud"); + let (job, post) = held.take(|j| matches!(j, Job::Read { .. })).expect("Reload submitted a read"); + let Job::Read { entry: read, into } = job else { unreachable!() }; + let read_name = read.name.clone(); + post.send(Event::Read { entry: read, into, bytes: Ok(b"stored".to_vec()) }); + drain(&mut app, &egui::Context::default()); + let log = log.lock().unwrap(); + assert!( + read_name == "A.note" && into == Some(1) && !log.closed.contains(&2), + "conflict was on uid 1 (A.note); Reload read {read_name:?} into {into:?}, then closed {:?}", + log.closed + ); +} + +/// "Save as a copy" from the conflict modal must encode the conflicted document, A, not +/// whichever tab happens to be active when the Save As page's own button is finally clicked. +#[test] +fn conflict_save_as_copy_encodes_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); // what the Save As page does with that name + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { unreachable!() }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "copy of the conflicted A.note is created as {name:?} from uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A read the backend never answers (the trait allows "or never") must not leave every transfer +/// refused forever. Signing out and back in recovers Save. +#[test] +fn sign_out_recovers_save_after_a_backend_job_never_replies() { + let (mut app, held, _log) = two_tabs(); + open_entry(&mut app, entry("/C.note", "c1"), None); + held.take(|j| matches!(j, Job::Read { .. })).unwrap(); // dropped by the worker + sign_out(&mut app); + sign_in(&mut app); + let (_, post) = held.take(|j| matches!(j, Job::SignIn)).unwrap(); + post.send(Event::Account(Ok(account("Ada")))); + drain(&mut app, &egui::Context::default()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + let saved = save(&mut app); + assert!(saved.is_ok(), "after sign-out and sign-in, Save is still refused: {saved:?}; busy={:?}", app.cloud.busy.as_ref().map(Busy::text)); +} + +/// An account and a listing answer a job issued before sign-out. Landing after it, they must +/// not put the previous session's account and file names on screen with nobody signed in. +#[test] +fn a_late_reply_from_before_sign_out_is_dropped() { + let (mut app, held, _log) = two_tabs(); + start(&mut app); + let (_, account_post) = held.take(|j| matches!(j, Job::Account)).unwrap(); + let (_, list_post) = held.take(|j| matches!(j, Job::List(_))).unwrap(); + sign_out(&mut app); + account_post.send(Event::Account(Ok(account("Previous Person")))); + list_post.send(Event::Listed { path: String::new(), entries: Ok(vec![entry("/Payroll 2026.note", "p1")]) }); + drain(&mut app, &egui::Context::default()); + let r = report(&app); + assert!( + r["account"].is_null() && r["entries"].as_array().is_some_and(Vec::is_empty), + "signed out, yet account={} entries={}", + r["account"], + r["entries"] + ); +} diff --git a/crates/ui/src/cloud/mod.rs b/crates/ui/src/cloud/mod.rs index a8d001a0b..ca261d23d 100644 --- a/crates/ui/src/cloud/mod.rs +++ b/crates/ui/src/cloud/mod.rs @@ -26,6 +26,8 @@ //! shows them in. use std::collections::HashMap; +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::mpsc::{Receiver, Sender, channel}; use std::time::Duration; @@ -35,6 +37,8 @@ use serde_json::{Value as Json, json}; mod app; mod backend; +#[cfg(test)] +mod conflict_tests; mod pages; #[cfg(test)] mod tests; @@ -210,6 +214,16 @@ pub struct CloudFiles { /// popup from this gesture instead of inferring it from `status`, which can /// stay set after a failed sign-in. sign_in_from_menu: bool, + /// Bumped on sign-out and on a new sign-in. Stamped onto every [`Post`] + /// handed out by [`submit`] so a reply to a job issued before the bump is + /// dropped rather than applied to the session that replaced it. + account_generation: Arc, + /// The document Save As must act on, when it is not the active one. + /// + /// Set only by the conflict modal's "Save as a copy", so the copy it asks + /// for is made from the conflicted document even if the user has since + /// switched to another tab. Consumed by the next [`save_as`] call. + save_as_target: Option, } impl Default for CloudFiles { @@ -240,6 +254,8 @@ impl CloudFiles { sharing_save: false, guest: None, sign_in_from_menu: false, + account_generation: Arc::new(AtomicU64::new(0)), + save_as_target: None, } } @@ -315,7 +331,7 @@ pub fn can_converse(app: &A) -> bool { pub fn submit(app: &A, job: Job) { let cloud = app.cloud(); if let Some(backend) = &cloud.backend { - backend.submit(job, Post::new(cloud.events.0.clone())); + backend.submit(job, Post::new(cloud.events.0.clone(), cloud.account_generation.clone())); } } @@ -353,6 +369,12 @@ pub fn sign_in(app: &mut A) { cloud.asked_account = true; cloud.link = None; cloud.status = Some(working); + // A new session. A job the previous one left outstanding may never + // answer, and if it does, that answer is not about this account: see + // `Post::send`. Busy goes with it, or a stuck read from before this + // sign-in would leave Save refused for a session that never asked for it. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; submit(app, Job::SignIn); } @@ -371,6 +393,13 @@ pub fn sign_out(app: &mut A) { cloud.shared = Folder::default(); cloud.origins.clear(); cloud.status = Some(signed_out); + // The session this window had ends here. A job it started may never + // answer, and a reply that does arrive late must not land on whatever + // comes next: see `Post::send`. Busy goes with it, so an open or a save + // that never heard back does not refuse every one after it forever. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; + cloud.save_as_target = None; submit(app, Job::SignOut); } @@ -552,9 +581,14 @@ pub fn save(app: &mut A) -> Result { } /// Save As: writes a new document into `folder` under `name`. +/// +/// Acts on [`CloudFiles::save_as_target`] when the conflict modal's "Save as +/// a copy" set one, so the copy is made from the document that conflicted +/// even if another tab is active by the time this runs. Otherwise, the +/// active document, same as every other ordinary Save As. pub fn save_as(app: &mut A, folder: &str, name: &str) -> Result { let kind = app.kind(); - let uid = app.active().ok_or(format!("no {} open", kind.noun))?; + let uid = app.cloud_mut().save_as_target.take().or_else(|| app.active()).ok_or(format!("no {} open", kind.noun))?; let name = document_name(name, kind); if name.is_empty() { return Err("type a file name".to_owned()); diff --git a/crates/ui/src/cloud/pages.rs b/crates/ui/src/cloud/pages.rs index b8187cf67..665370952 100644 --- a/crates/ui/src/cloud/pages.rs +++ b/crates/ui/src/cloud/pages.rs @@ -9,8 +9,8 @@ use craft_cloud::{Capability, Entry, EntryKind}; use egui::{RichText, Ui}; use super::{ - CloudApp, Link, Source, browse, column, converse, dim, document_name, entry_row, fill, link, load_shared, open_entry, opens, parent_of, - reload_active, save_as, size_text, start, stem_of, + CloudApp, Link, Source, browse, column, converse, dim, document_name, entry_row, fill, link, load_shared, open_entry, opens, parent_of, save_as, + size_text, start, stem_of, }; /// The character a label ends with when choosing it opens a dialog. @@ -485,15 +485,21 @@ pub fn conflict_modal(app: &mut A, ctx: &egui::Context) { }); }); if reload { + // Reads the conflicted document back, never whichever tab happens to + // be active. `reload_active` acts on the active document, which is + // right for a host's own Reload command but wrong here: the window + // that triggered this modal may have moved on to another document + // while the refused save was on the wire. app.cloud_mut().conflict = None; - if let Err(error) = reload_active(app) { - app.say(error); - } + open_entry(app, conflict.entry, Some(conflict.uid)); } else if copy { let name = document_name(&format!("{} (copy)", stem_of(&conflict.entry.name)), app.kind()); let cloud = app.cloud_mut(); cloud.conflict = None; cloud.save_name = name; + // Save As must encode the conflicted document too, not whatever is + // active once the user actually clicks Save on that page. + cloud.save_as_target = Some(conflict.uid); app.go_to_save_as(); } else if dismiss { app.cloud_mut().conflict = None; From c5e9e87309230c989a52a6fcd4f98ebef778969c Mon Sep 17 00:00:00 2001 From: William Dunn Date: Thu, 12 Nov 2026 23:28:15 -0500 Subject: [PATCH 07/97] craft-cloud-local: fix stale etag and racing create Read now stats the file it just read. The returned entry reflects that read. It no longer echoes the etag of the entry passed in. A reload after a conflict used to carry the version that was just refused into the next save, conflicting it again. Create opens the file with exclusive creation. An exists check no longer precedes a separate write. Two creates of the same name can no longer both observe an empty slot and both report success. Regression tests drive both fixes through craft_ui::cloud's public functions against a real folder on disk. --- crates/cloud-local/src/lib.rs | 39 ++++- .../tests/save_path_regressions.rs | 160 ++++++++++++++++++ 2 files changed, 190 insertions(+), 9 deletions(-) create mode 100644 crates/cloud-local/tests/save_path_regressions.rs diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs index 7f7f56590..c974a295e 100644 --- a/crates/cloud-local/src/lib.rs +++ b/crates/cloud-local/src/lib.rs @@ -22,6 +22,7 @@ //! megabyte document would freeze the window that called it. use std::fs; +use std::io::Write as _; use std::path::{Path, PathBuf}; use craft_cloud::{Capability, Entry, EntryKind}; @@ -82,9 +83,9 @@ impl CloudBackend for LocalBackend { std::thread::spawn(move || post.send(Event::Shared(Ok(Vec::new())))); } Job::Read { entry, into } => { - std::thread::spawn(move || { - let bytes = read(&root, &entry); - post.send(Event::Read { entry, into, bytes }); + std::thread::spawn(move || match read(&root, &entry) { + Ok((entry, bytes)) => post.send(Event::Read { entry, into, bytes: Ok(bytes) }), + Err(fault) => post.send(Event::Read { entry, into, bytes: Err(fault) }), }); } Job::Write { uid, entry, bytes } => { @@ -180,9 +181,19 @@ fn list(root: &Path, path: &str) -> Result, Fault> { Ok(entries) } -fn read(root: &Path, entry: &Entry) -> Result, Fault> { +/// Reads a file's bytes together with the entry for the version just read. +/// +/// The entry is built from a fresh [`fs::metadata`] call here, not handed back +/// unchanged from what the caller already believed. A reload after a conflict +/// hands in the stale entry it is trying to get past; echoing that back would +/// carry the old etag into the reloaded document, so the very next save would +/// conflict again on a copy that is actually current. +fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { let file = resolve(root, &entry.id)?; - fs::read(&file).map_err(|error| io_fault(&error)) + let bytes = fs::read(&file).map_err(|error| io_fault(&error))?; + let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; + let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }; + Ok((fresh, bytes)) } /// Saves back over `entry`, refusing the write when the file moved on since @@ -207,10 +218,20 @@ fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result handle, + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => { + return Err(Fault::Refused(format!("{name} already exists"))); + } + Err(error) => return Err(io_fault(&error)), + }; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + drop(handle); let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; let id = child_path(folder, name); Ok(Entry { diff --git a/crates/cloud-local/tests/save_path_regressions.rs b/crates/cloud-local/tests/save_path_regressions.rs new file mode 100644 index 000000000..76cec678a --- /dev/null +++ b/crates/cloud-local/tests/save_path_regressions.rs @@ -0,0 +1,160 @@ +//! Two save-path defects that need a real backend to show: a reload after a conflict carrying a +//! stale etag into the next save, and two creates of the same name racing past an exists check. +//! Driven through craft_ui::cloud's public functions the way an application does. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +struct Window { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + body: Vec, + said: Arc>>, +} + +impl Window { + fn new(root: std::path::PathBuf, body: &[u8]) -> Window { + let mut w = Window { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + body: body.to_vec(), + said: Arc::default(), + }; + w.cloud.connect(LocalBackend::new(root)); + w + } +} + +impl CloudApp for Window { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + Some(1) + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, _name: &str, bytes: Vec) -> Result, String> { + self.body = bytes; + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(self.body.clone()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Review" + } +} + +fn settle(app: &mut Window, ctx: &egui::Context, mut done: impl FnMut(&Window) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out"); + std::thread::sleep(Duration::from_millis(2)); + } +} + +fn listed(app: &mut Window, ctx: &egui::Context, name: &str) -> Entry { + cloud::browse(app, ""); + settle(app, ctx, |a| a.cloud.mine.loaded); + app.cloud.mine.entries.iter().find(|e| e.name == name).cloned().expect("listed") +} + +/// Open v1, another writer stores v2, Save conflicts, the user picks "Reload from the cloud" +/// (`reload_active`, what the modal calls). The window now shows v2's bytes, so the next Save +/// must go through rather than conflict again on the etag the reloaded copy was read at. +#[test] +fn reload_after_a_conflict_carries_the_freshly_read_etag_so_the_next_save_succeeds() { + let root = tempfile::tempdir().unwrap(); + std::fs::write(root.path().join("note.txt"), b"v1").unwrap(); + let ctx = egui::Context::default(); + let mut app = Window::new(root.path().to_owned(), b""); + let v1 = listed(&mut app, &ctx, "note.txt"); + cloud::open_entry(&mut app, v1.clone(), None); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none() && a.body == b"v1"); + + std::thread::sleep(Duration::from_millis(20)); + std::fs::write(root.path().join("note.txt"), b"v2 by someone else").unwrap(); + + app.body = b"my edit".to_vec(); + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert!(app.cloud.conflict.is_some(), "the first save is refused (correct)"); + + cloud::reload_active(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert_eq!(app.body, b"v2 by someone else", "reload shows the stored bytes"); + let origin_etag = cloud::report(&app)["origin"]["etag"].clone(); + + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + let on_disk = std::fs::read(root.path().join("note.txt")).unwrap(); + assert!( + app.cloud.conflict.is_none(), + "after reloading v2 the save conflicted again: origin etag after reload = {origin_etag} \ + (listing etag was {:?}); file on disk = {:?}", + v1.etag, + String::from_utf8_lossy(&on_disk) + ); +} + +/// Two windows Save As the same new name at once. At most one create may succeed; the other +/// must be refused ("already exists") rather than both reporting success while one silently +/// replaces the other on disk. +#[test] +fn concurrent_create_of_one_name_refuses_the_loser() { + let rounds = 300; + let (mut both_ok, mut example) = (0, String::new()); + for round in 0..rounds { + let root = tempfile::tempdir().unwrap(); + let ctx = egui::Context::default(); + let mut a = Window::new(root.path().to_owned(), format!("window A round {round}").as_bytes()); + let mut b = Window::new(root.path().to_owned(), format!("window B round {round}").as_bytes()); + cloud::save_as(&mut a, "", "Report.txt").unwrap(); + cloud::save_as(&mut b, "", "Report.txt").unwrap(); + settle(&mut a, &ctx, |w| w.cloud.busy.is_none()); + settle(&mut b, &ctx, |w| w.cloud.busy.is_none()); + let (a_ok, b_ok) = (cloud::origin(&a).is_some(), cloud::origin(&b).is_some()); + if a_ok && b_ok { + both_ok += 1; + if example.is_empty() { + let disk = std::fs::read_to_string(root.path().join("Report.txt")).unwrap(); + example = format!("round {round}: A status {:?}, B status {:?}, file holds {disk:?}", a.cloud.status, b.cloud.status); + } + } + } + assert_eq!(both_ok, 0, "{both_ok}/{rounds} rounds: both windows were told the new file was created; e.g. {example}"); +} From 658cc01501b09fd4984cd6dea29990f184dceb46 Mon Sep 17 00:00:00 2001 From: William Dunn Date: Thu, 12 Nov 2026 23:32:45 -0500 Subject: [PATCH 08/97] craft-ui cloud: stop using unreachable in the conflict modal tests clippy::unreachable is denied at the crate root with no in-tests carve-out, unlike unwrap, expect and panic. The three let-else fallbacks in conflict_tests.rs now panic with a message instead, matching the pattern used everywhere else in this crate's tests. --- crates/ui/src/cloud/conflict_tests.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/ui/src/cloud/conflict_tests.rs b/crates/ui/src/cloud/conflict_tests.rs index 29a83799d..c8e3d75cf 100644 --- a/crates/ui/src/cloud/conflict_tests.rs +++ b/crates/ui/src/cloud/conflict_tests.rs @@ -144,7 +144,7 @@ fn conflict_on_a_while_b_is_active() -> (Tabs, Held, Arc>) { save(&mut app).unwrap(); app.active = 2; let (job, post) = held.take(|j| matches!(j, Job::Write { .. })).unwrap(); - let Job::Write { uid, .. } = job else { unreachable!() }; + let Job::Write { uid, .. } = job else { panic!("expected Job::Write") }; post.send(Event::Saved { uid, entry: Err(Fault::Conflict) }); let ctx = egui::Context::default(); drain(&mut app, &ctx); @@ -167,7 +167,7 @@ fn conflict_reload_acts_on_the_conflicted_document_even_when_another_tab_is_acti let (app, held, log) = conflict_on_a_while_b_is_active(); let mut app = click_in_conflict_modal(app, "Reload from the cloud"); let (job, post) = held.take(|j| matches!(j, Job::Read { .. })).expect("Reload submitted a read"); - let Job::Read { entry: read, into } = job else { unreachable!() }; + let Job::Read { entry: read, into } = job else { panic!("expected Job::Read") }; let read_name = read.name.clone(); post.send(Event::Read { entry: read, into, bytes: Ok(b"stored".to_vec()) }); drain(&mut app, &egui::Context::default()); @@ -188,7 +188,7 @@ fn conflict_save_as_copy_encodes_the_conflicted_document_even_when_another_tab_i let name = app.cloud.save_name.clone(); save_as(&mut app, "", &name).unwrap(); // what the Save As page does with that name let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); - let Job::Create { uid, name, bytes, .. } = job else { unreachable!() }; + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; assert_eq!( (uid, String::from_utf8_lossy(&bytes).into_owned()), (1, "bytes of 1".to_owned()), From d93b55f7ff2c30cc0722f2c1eb4416f9ce9782c5 Mon Sep 17 00:00:00 2001 From: skylar taylor-barrick Date: Fri, 13 Nov 2026 18:47:51 -0600 Subject: [PATCH 09/97] fix(cloud): retain conflict-copy identity through retries --- crates/ui/src/cloud/app.rs | 3 + crates/ui/src/cloud/conflict_tests.rs | 79 +++++++++++++++++++++++++++ crates/ui/src/cloud/mod.rs | 19 ++++++- crates/ui/src/cloud/pages.rs | 4 +- 4 files changed, 102 insertions(+), 3 deletions(-) diff --git a/crates/ui/src/cloud/app.rs b/crates/ui/src/cloud/app.rs index b98e91ba5..cfb697935 100644 --- a/crates/ui/src/cloud/app.rs +++ b/crates/ui/src/cloud/app.rs @@ -222,6 +222,9 @@ pub trait CloudApp { /// Take the user to the application's own Save As page, with the name /// [`CloudFiles::save_name`](crate::cloud::CloudFiles::save_name) now /// holding. Called when a refused save is answered with Save as a copy. + /// Hosts call [`cancel_save_as`](crate::cloud::cancel_save_as) when leaving + /// that page without submitting, or before opening an ordinary Save As, + /// so the abandoned copy's document and suggested name cannot carry over. fn go_to_save_as(&mut self) {} // ---- its words ------------------------------------------------------- diff --git a/crates/ui/src/cloud/conflict_tests.rs b/crates/ui/src/cloud/conflict_tests.rs index c8e3d75cf..1e22e815f 100644 --- a/crates/ui/src/cloud/conflict_tests.rs +++ b/crates/ui/src/cloud/conflict_tests.rs @@ -234,3 +234,82 @@ fn a_late_reply_from_before_sign_out_is_dropped() { r["entries"] ); } + +/// Save as a copy, then the first click on the Save As page is refused (no name typed yet). The +/// second click, with a name, must still copy the conflicted document A, not the active tab B. +#[test] +fn conflict_copy_survives_a_refused_first_attempt() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let refused = save_as(&mut app, "", ""); + assert!(refused.is_err(), "an empty name is refused: {refused:?}"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "after one refused attempt the copy of A.note encodes uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// Save as a copy, but the user leaves the Save As page without saving. Later, on tab B, an +/// ordinary Save As must save B, not the conflicted A from the abandoned copy. +#[test] +fn cancelled_conflict_copy_does_not_hijack_a_later_save_as() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let app = click_in_conflict_modal(app, "Save as a copy…"); + let mut app = app; + cancel_save_as(&mut app); // the host leaves the Save As page without submitting + assert!(app.cloud.save_name.is_empty()); + assert_eq!(app.active, 2); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (2, "bytes of 2".to_owned()), + "an ordinary Save As of tab B as {name:?} encoded uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A successfully saved conflict copy must not redirect a later ordinary Save As. +#[test] +fn successful_conflict_copy_releases_its_document_target() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + assert_eq!(app.cloud.save_as_target, Some(1)); + post.send(Event::Saved { uid, entry: Ok(entry("/A-copy.note", "a2")) }); + drain(&mut app, &egui::Context::default()); + assert_eq!(app.cloud.save_as_target, None); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (2, b"bytes of 2".to_vec())); +} + +/// A refused create keeps the same document pinned while the user changes its name. +#[test] +fn conflict_copy_survives_a_backend_refusal() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + post.send(Event::Saved { uid, entry: Err(Fault::Refused("exists".to_owned())) }); + drain(&mut app, &egui::Context::default()); + save_as(&mut app, "", "A another copy").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (1, b"bytes of 1".to_vec())); +} diff --git a/crates/ui/src/cloud/mod.rs b/crates/ui/src/cloud/mod.rs index ca261d23d..3844c4f8f 100644 --- a/crates/ui/src/cloud/mod.rs +++ b/crates/ui/src/cloud/mod.rs @@ -222,7 +222,8 @@ pub struct CloudFiles { /// /// Set only by the conflict modal's "Save as a copy", so the copy it asks /// for is made from the conflicted document even if the user has since - /// switched to another tab. Consumed by the next [`save_as`] call. + /// switched to another tab. Cleared after a successful save or by + /// [`cancel_save_as`] when the interaction is abandoned. save_as_target: Option, } @@ -580,6 +581,17 @@ pub fn save(app: &mut A) -> Result { Ok(answer) } +/// Ends an unsubmitted Save As interaction. +/// +/// Hosts call this when leaving the Save As page without saving, and before +/// opening an unrelated Save As. It does not cancel a transfer already sent +/// to the backend. +pub fn cancel_save_as(app: &mut A) { + let cloud = app.cloud_mut(); + cloud.save_as_target = None; + cloud.save_name.clear(); +} + /// Save As: writes a new document into `folder` under `name`. /// /// Acts on [`CloudFiles::save_as_target`] when the conflict modal's "Save as @@ -588,7 +600,7 @@ pub fn save(app: &mut A) -> Result { /// active document, same as every other ordinary Save As. pub fn save_as(app: &mut A, folder: &str, name: &str) -> Result { let kind = app.kind(); - let uid = app.cloud_mut().save_as_target.take().or_else(|| app.active()).ok_or(format!("no {} open", kind.noun))?; + let uid = app.cloud().save_as_target.or_else(|| app.active()).ok_or(format!("no {} open", kind.noun))?; let name = document_name(name, kind); if name.is_empty() { return Err("type a file name".to_owned()); @@ -714,6 +726,9 @@ fn apply(app: &mut A, event: Event) { app.cloud_mut().busy = None; match entry { Ok(entry) => { + if app.cloud().save_as_target == Some(uid) { + app.cloud_mut().save_as_target = None; + } app.mark_saved(uid); stored(app, uid, entry); } diff --git a/crates/ui/src/cloud/pages.rs b/crates/ui/src/cloud/pages.rs index 665370952..86e71d1c8 100644 --- a/crates/ui/src/cloud/pages.rs +++ b/crates/ui/src/cloud/pages.rs @@ -351,7 +351,9 @@ fn shared_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, /// File › Save As, the cloud destination. Pick a folder, name the file, save. /// Returns true when a save started, so a Backstage view can return to the -/// document. +/// document. Hosts call [`super::cancel_save_as`] when leaving without saving, +/// or before opening this page for an ordinary File › Save As, to discard any +/// abandoned conflict-copy target and suggested name. pub fn save_page(app: &mut A, ui: &mut Ui) -> bool { let style = app.style(ui); let kind = app.kind(); From e5e9433413afa0f25c93005b6cfc5c0dd6c659d9 Mon Sep 17 00:00:00 2001 From: William Dunn Date: Mon, 16 Nov 2026 05:16:56 -0500 Subject: [PATCH 10/97] craft-cloud-local: confine list, read, write and create to the configured root FredApps' re-review found that resolve only split on slash and rejected a segment equal to parent-dir, with no constraint on a Windows backslash, a drive letter or UNC prefix, or a filesystem link, and that create joined the Job::Create name onto the resolved folder with no validation of the name at all. Every path segment, and a Create name on its own, now goes through one shared confine_segment check: accepted only when it parses as exactly one Component::Normal equal to the original text, with a backslash or colon refused outright first so a Windows-shaped escape cannot slip past a Linux build's narrower native parser. A second shared check, confine_to_root, canonicalises the nearest existing ancestor of a resolved path and confirms it still sits under the canonicalised root, refusing a symlink or a Windows junction that would otherwise redirect outside it. List, read, write and create all run both checks before touching disk. Regression tests cover the review's own examples (a parent segment, an absolute path, the three Windows-shaped forms) for Create, the same Windows-shaped escape for a List folder path, and a symlink (Unix) or junction (Windows) placed inside the root for list, read and write, each against a sibling sentinel file and directory that must stay untouched. --- crates/cloud-local/README.md | 21 ++ crates/cloud-local/src/lib.rs | 143 ++++++++- .../tests/confinement_regressions.rs | 289 ++++++++++++++++++ 3 files changed, 438 insertions(+), 15 deletions(-) create mode 100644 crates/cloud-local/README.md create mode 100644 crates/cloud-local/tests/confinement_regressions.rs diff --git a/crates/cloud-local/README.md b/crates/cloud-local/README.md new file mode 100644 index 000000000..d8f7cb3a7 --- /dev/null +++ b/crates/cloud-local/README.md @@ -0,0 +1,21 @@ +# craft-cloud-local + +A reference `CloudBackend` over one folder on disk, proving that `craft-cloud`'s contract needs +no specific provider behind it. + +## No-escape policy + +Every path this crate is handed, a `Job::List`/`Read`/`Write` path or a `Job::Create` name, is +confined to the configured root before anything touches a filesystem. + +A path's segments, and a `Create` name on its own, are accepted only when each one parses as a +single `Component::Normal`: no `..`, no `.`, no empty segment, no absolute form, and no Windows +drive letter, UNC path or backslash. That last group is refused on every platform this crate +builds for, not only on Windows, because a name reaches this backend from whatever platform the +UI runs on. + +Once a candidate path is built from nothing but checked names, it is still confirmed against a +symlink or (on Windows) a directory junction placed somewhere under the root: the nearest +ancestor that already exists is canonicalised and must stay under the canonicalised root. A path +that reaches outside the root this way is refused before any read, write, listing or creation +touches it. diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs index c974a295e..c0caf5d45 100644 --- a/crates/cloud-local/src/lib.rs +++ b/crates/cloud-local/src/lib.rs @@ -23,7 +23,7 @@ use std::fs; use std::io::Write as _; -use std::path::{Path, PathBuf}; +use std::path::{Component, Path, PathBuf}; use craft_cloud::{Capability, Entry, EntryKind}; use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; @@ -33,8 +33,16 @@ use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; /// `Entry::id` and `Entry::path` are the same slash-separated path relative to /// `root`, always starting with `/` below the root itself (the root's own /// path is the empty string, matching [`Job::List`]'s contract). Neither is -/// an OS path; both go through [`resolve`] before anything touches a -/// filesystem, so a name containing `..` can never walk out of `root`. +/// an OS path; both go through [`resolve`] and then [`confine_to_root`] +/// before anything touches a filesystem. A [`Job::Create`] name is not a +/// path at all; it goes through the same per-segment check [`resolve`] uses, +/// [`confine_segment`], on its own. Together the two refuse `..`, an +/// absolute form, a Windows drive letter or UNC prefix, and a backslash, +/// regardless of which platform this crate is built for, since a name +/// reaches this backend from whatever platform the UI runs on. No-escape +/// through a symlink or a Windows junction is a separate policy, stated on +/// [`confine_to_root`] itself, and every one of [`list`], [`read`], +/// [`write`] and [`create`] applies it. pub struct LocalBackend { root: PathBuf, /// Shown in the account badge. Nothing else reads it. @@ -111,25 +119,81 @@ fn account(display: String) -> Account { } /// Turns a [`Job`]'s slash-separated path into a real filesystem path under -/// `root`, refusing anything that would walk back out of it. +/// `root`, refusing anything that is not a run of ordinary names. /// -/// `..` is the only way out, so `..` is the only segment refused. `.` and -/// repeated or leading slashes are just an empty segment and are skipped, -/// the same way a browser's address bar collapses them. +/// `.` and repeated or leading slashes are just an empty segment and are +/// skipped, the same way a browser's address bar collapses them. Every other +/// segment goes through [`confine_segment`], which is what actually refuses +/// `..`, an absolute form, a backslash or a drive letter, or anything else +/// that is not one ordinary name. This function never touches disk, so it +/// cannot see a symlink or a junction; [`confine_to_root`] is the other half +/// of the promise, and every caller of `resolve` runs both. fn resolve(root: &Path, path: &str) -> Result { let mut real = root.to_path_buf(); for segment in path.split('/') { if segment.is_empty() || segment == "." { continue; } - if segment == ".." { - return Err(Fault::Refused(format!("{path} reaches outside this folder"))); - } - real.push(segment); + real.push(confine_segment(segment)?); } Ok(real) } +/// Confines one path segment, or a whole [`Job::Create`] name, to a single +/// ordinary file or folder name. +/// +/// Accepted only when `segment` parses as exactly one [`Component::Normal`] +/// equal to `segment` itself: no empty name, no `.` or `..`, no absolute +/// form, and nothing left over for a second component to hide in. A +/// `std::path::Component` parse alone does not catch every one of those on +/// every platform; a Unix build's parser does not know what `C:` or +/// `\\server\share` mean, so it would wave a Windows drive letter or a UNC +/// prefix straight through as one ordinary name. A `:` or a `\` is refused +/// outright first, on every platform, for exactly that reason: a name +/// reaches this backend's public [`CloudBackend::submit`] from whatever +/// platform the UI happens to run on, and a Windows-shaped escape must not +/// slip past a Linux build's narrower native parser, or the reverse. +fn confine_segment(segment: &str) -> Result<&str, Fault> { + if segment.contains('\\') || segment.contains(':') { + return Err(Fault::Refused(format!("{segment} is not a plain file name"))); + } + let mut components = Path::new(segment).components(); + match (components.next(), components.next()) { + (Some(Component::Normal(name)), None) if name == std::ffi::OsStr::new(segment) => Ok(segment), + _ => Err(Fault::Refused(format!("{segment} is not a plain file name"))), + } +} + +/// Confirms a path already built from nothing but [`confine_segment`]-checked +/// names still cannot have reached outside `root` through a symlink or, on +/// Windows, a directory junction. +/// +/// The no-escape policy: `candidate` need not exist yet, since [`write`] and +/// [`create`] both route a path that may still be about to be created +/// through here. Starting at `candidate` and walking up through its +/// ancestors, the first one that does exist is canonicalised and compared +/// against the canonicalised `root`. Nothing below that ancestor exists +/// either, so a link cannot sit on any of the remaining components, and +/// every one of them is already known to be ordinary `Component::Normal` +/// text, never `..` or an absolute form, because [`confine_segment`] is what +/// built them. A canonical path that lands outside `root` is refused; +/// nothing here ever opens, reads or writes through it. +fn confine_to_root(root: &Path, candidate: &Path) -> Result { + let real_root = fs::canonicalize(root).map_err(|error| io_fault(&error))?; + let mut probe = candidate; + loop { + match fs::canonicalize(probe) { + Ok(real) if real == real_root || real.starts_with(&real_root) => return Ok(candidate.to_path_buf()), + Ok(_) => return Err(Fault::Refused("that path leaves this folder".to_owned())), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => match probe.parent() { + Some(parent) => probe = parent, + None => return Err(io_fault(&error)), + }, + Err(error) => return Err(io_fault(&error)), + } + } +} + /// The path a listed child gets, given the folder it was found in. fn child_path(folder: &str, name: &str) -> String { format!("{}/{name}", folder.trim_end_matches('/')) @@ -155,7 +219,7 @@ fn io_fault(error: &std::io::Error) -> Fault { } fn list(root: &Path, path: &str) -> Result, Fault> { - let dir = resolve(root, path)?; + let dir = confine_to_root(root, &resolve(root, path)?)?; let read = fs::read_dir(&dir).map_err(|error| io_fault(&error))?; let mut entries = Vec::new(); for item in read { @@ -189,7 +253,7 @@ fn list(root: &Path, path: &str) -> Result, Fault> { /// carry the old etag into the reloaded document, so the very next save would /// conflict again on a copy that is actually current. fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { - let file = resolve(root, &entry.id)?; + let file = confine_to_root(root, &resolve(root, &entry.id)?)?; let bytes = fs::read(&file).map_err(|error| io_fault(&error))?; let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }; @@ -200,7 +264,7 @@ fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { /// `entry.etag` was read. A file that no longer exists has nothing to /// conflict with, the same way a provider treats a deleted document. fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { - let file = resolve(root, &entry.id)?; + let file = confine_to_root(root, &resolve(root, &entry.id)?)?; if let Ok(meta) = fs::metadata(&file) && Some(etag_of(&meta)) != entry.etag { @@ -215,7 +279,11 @@ fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { } fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result { - let dir = resolve(root, folder)?; + // `name` is never a path: it is one [`Job::Create`] field that names the + // new file, so it goes through `confine_segment` directly rather than + // through `resolve`, which only ever splits and confines a slash path. + let name = confine_segment(name)?; + let dir = confine_to_root(root, &resolve(root, folder)?)?; fs::create_dir_all(&dir).map_err(|error| io_fault(&error))?; let file = dir.join(name); // Exclusive creation, not an `exists` check ahead of a separate write: two @@ -267,6 +335,51 @@ mod tests { assert_eq!(resolve(&root, "").unwrap(), root); } + #[test] + fn confine_segment_accepts_only_a_single_ordinary_name() { + for ordinary in ["Minutes.txt", "Archive", "2026", "a name with spaces.docx"] { + assert!(confine_segment(ordinary).is_ok(), "{ordinary} is an ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_empty_dot_and_dot_dot() { + for bad in ["", ".", ".."] { + assert!(confine_segment(bad).is_err(), "{bad:?} is not a single ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_a_slash_hidden_inside_a_create_name() { + assert!(confine_segment("folder/evil").is_err()); + assert!(confine_segment("../outside.txt").is_err()); + assert!(confine_segment("/outside.txt").is_err()); + } + + #[test] + fn confine_segment_refuses_windows_separators_and_prefixes_on_every_platform() { + for bad in ["..\\outside.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] { + assert!(confine_segment(bad).is_err(), "{bad:?} must be refused on every platform, not only on Windows"); + } + } + + #[test] + fn confine_to_root_accepts_a_path_that_does_not_exist_yet_under_an_existing_root() { + let root = tempfile::tempdir().unwrap(); + let candidate = root.path().join("not-written-yet.txt"); + assert!(confine_to_root(root.path(), &candidate).is_ok()); + } + + #[test] + fn confine_to_root_refuses_a_candidate_that_canonicalises_outside_root() { + let root = tempfile::tempdir().unwrap(); + let elsewhere = tempfile::tempdir().unwrap(); + // Built from a path that never went through `confine_segment` (this + // helper is tested on its own merits), standing in for whatever a + // symlink or junction would otherwise have redirected into `root`. + assert!(confine_to_root(root.path(), elsewhere.path()).is_err()); + } + #[test] fn a_folder_announces_no_capability_this_backend_cannot_honour() { let reported = account("Local disk".to_owned()).capabilities; diff --git a/crates/cloud-local/tests/confinement_regressions.rs b/crates/cloud-local/tests/confinement_regressions.rs new file mode 100644 index 000000000..d4bebd038 --- /dev/null +++ b/crates/cloud-local/tests/confinement_regressions.rs @@ -0,0 +1,289 @@ +//! The P1 from FredApps' re-review of #160: `resolve` only split on `/` and rejected a segment +//! equal to `..`; it did not constrain a Windows backslash, a drive letter or UNC prefix, or a +//! filesystem link, and `create` joined `name` onto the resolved folder with no validation of +//! `name` at all. Driven through `craft_ui::cloud`'s public functions the way an application +//! does, with a sentinel file and directory kept as a sibling of the configured root: every test +//! here must leave both untouched and unread. + +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: OpenedDocs, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + None + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until `done` says the state +/// the test is waiting for arrived or five seconds pass. Five seconds is far more than a thread +/// doing local file IO ever needs; it only guards against a real bug leaving the test to hang. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +fn said(app: &mut Harness, ctx: &egui::Context) -> Vec { + settle(app, ctx, |app| !app.said.lock().unwrap().is_empty()); + app.said.lock().unwrap().clone() +} + +/// A tempdir holding the cloud root, plus a sentinel file and a sentinel directory that sit +/// beside it rather than inside it. Every test below must leave both exactly as they start. +struct Sentinels { + // Kept only so the tempdir outlives every test that borrows the paths below; nothing reads + // it back once the paths it was built from are in hand. + _arena: tempfile::TempDir, + root: PathBuf, + sentinel_file: PathBuf, + sentinel_dir: PathBuf, +} + +fn sentinels() -> Sentinels { + let arena = tempfile::tempdir().unwrap(); + let root = arena.path().join("root"); + std::fs::create_dir(&root).unwrap(); + let sentinel_file = arena.path().join("sentinel.txt"); + std::fs::write(&sentinel_file, b"a sibling file this backend must never read or write").unwrap(); + let sentinel_dir = arena.path().join("sentinel-dir"); + std::fs::create_dir(&sentinel_dir).unwrap(); + std::fs::write(sentinel_dir.join("secret.txt"), b"a sibling directory this backend must never list").unwrap(); + Sentinels { _arena: arena, root, sentinel_file, sentinel_dir } +} + +fn assert_sentinels_untouched(sentinels: &Sentinels) { + assert_eq!( + std::fs::read(&sentinels.sentinel_file).unwrap(), + b"a sibling file this backend must never read or write", + "the sentinel file outside the root was changed" + ); + assert_eq!( + std::fs::read(sentinels.sentinel_dir.join("secret.txt")).unwrap(), + b"a sibling directory this backend must never list", + "the sentinel directory's file outside the root was changed" + ); +} + +/// Every one of these is a [`Job::Create`] `name` that must be refused before any byte reaches +/// disk: the review's own examples (a parent segment, an absolute path, and the three +/// Windows-shaped forms), none of which a Unix build's native parser alone would catch, and a +/// name that already is nothing but a Windows separator or drive prefix on top of that. +fn malicious_create_names() -> Vec<&'static str> { + vec!["../sentinel.txt", "/sentinel.txt", "..\\sentinel.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] +} + +#[test] +fn create_refuses_every_escaping_name_and_the_sentinels_stay_untouched() { + for name in malicious_create_names() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: name.to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "{name:?} must not be reported as created"); + assert!(!messages.is_empty(), "{name:?} must be refused, not silently dropped"); + assert_sentinels_untouched(&sentinels); + } +} + +/// A folder path for `Job::List` can carry the same Windows-shaped escape a `Create` name can; +/// `resolve` must refuse it through the identical [`confine_segment`] check, not a weaker one. +#[test] +fn listing_a_windows_shaped_folder_path_is_refused_on_every_platform() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::browse(&mut app, "..\\sentinel-dir"); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + assert!(app.cloud().mine.error.is_some(), "a backslash-separated folder path must be refused"); + assert!(app.cloud().mine.entries.is_empty()); + assert_sentinels_untouched(&sentinels); +} + +// ------------------------------------------------------------------- link-based escapes +// +// `escape(&sentinels)` places one link named `escape` inside the cloud root, pointing out to +// `sentinels.sentinel_dir`: a symlink on Unix, a directory junction on Windows, which needs no +// elevated privilege, unlike a Windows symlink. The Linux gate runs the symlink half of every +// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/secret.txt` +// is the same sentinel file reached through the link. + +/// Nothing to clean up on Unix: `tempfile`'s own recursive removal of the arena directory +/// removes a plain symlink entry without following it. This exists only so `escape` returns the +/// same shape of RAII handle on every platform, rather than a bare `()` some lint would flag. +#[cfg(unix)] +struct Linked; + +#[cfg(unix)] +fn escape(sentinels: &Sentinels) -> Linked { + std::os::unix::fs::symlink(&sentinels.sentinel_dir, sentinels.root.join("escape")).unwrap(); + Linked +} + +/// A directory junction, removed on drop before the tempdir it sits beside is cleaned up. +#[cfg(windows)] +struct Junction(PathBuf); + +#[cfg(windows)] +impl Drop for Junction { + fn drop(&mut self) { + let _ = std::fs::remove_dir(&self.0); + } +} + +#[cfg(windows)] +fn escape(sentinels: &Sentinels) -> Junction { + use std::os::windows::process::CommandExt as _; + let link = sentinels.root.join("escape"); + let target = &sentinels.sentinel_dir; + assert!(link.is_absolute() && target.is_absolute()); + let output = std::process::Command::new("cmd") + .args(["/C", "mklink", "/J"]) + .arg(&link) + .arg(target) + .creation_flags(0x0800_0000) // CREATE_NO_WINDOW + .output() + .unwrap(); + assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr)); + Junction(link) +} + +#[cfg(any(unix, windows))] +fn leaked_entry() -> Entry { + Entry { + id: "/escape/secret.txt".to_owned(), + room: "local:/escape/secret.txt".to_owned(), + name: "secret.txt".to_owned(), + path: "/escape/secret.txt".to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + } +} + +#[cfg(any(unix, windows))] +#[test] +fn listing_a_linked_folder_cannot_see_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::browse(&mut app, "escape"); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + assert!(app.cloud().mine.error.is_some(), "listing through a symlink or junction out of the root must be refused"); + assert!(app.cloud().mine.entries.is_empty()); + assert_sentinels_untouched(&sentinels); +} + +#[cfg(any(unix, windows))] +#[test] +fn reading_through_a_linked_folder_cannot_return_bytes_from_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Read { entry: leaked_entry(), into: None }); + said(&mut app, &ctx); + + assert!(app.opened.lock().unwrap().is_empty(), "a read through a symlink or junction out of the root must not deliver bytes"); + assert_sentinels_untouched(&sentinels); +} + +#[cfg(any(unix, windows))] +#[test] +fn writing_through_a_linked_folder_cannot_change_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry(), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(app.cloud().conflict.is_none(), "this must be refused outright, not treated as a stale-version conflict"); + assert_sentinels_untouched(&sentinels); +} From aa4647a77778687017c19006e23544d4426abe8d Mon Sep 17 00:00:00 2001 From: William Dunn Date: Tue, 17 Nov 2026 00:49:24 -0500 Subject: [PATCH 11/97] craft-cloud-local: confine every path through a Dir capability, not a path string benandez's re-review reproduced three escapes the first confinement fix still left open. A dangling symlink: canonicalize reported it as missing, so the old confine_to_root walked up to root and accepted it, and write created the symlink's target for real, outside root. A check-then-use race: confine_to_root checked one path string and a later fs::read or fs::write resolved that same string again, a second lookup a concurrently swapped link could land in between. A hard link: write truncated the shared inode in place, with nothing in a canonicalized path to show that another name pointed at the same file outside root. list, read, write and create now resolve every already segment-checked relative path through a cap_std::fs::Dir capability opened on root, instead of joining an absolute OS path and handing it to plain std::fs. cap_std resolves one path component at a time against real, already-open directory handles, so a symlink or a Windows junction cannot walk resolution above root, dangling or not, and there is no separate check with a window for the directory tree to change underneath it: the one resolution is the open. This is the same family of guarantee craft-font-store already depends on through cap-primitives, which cap_std is built on. write no longer truncates its target in place either way: it writes a new sibling file and renames it over the target, so a hard link's directory entry is replaced rather than its shared content being overwritten. Per that review's non-blocking notes: a name that already exists on disk with an ordinary ':' or '\' byte (macOS stores a typed '/' as ':') stays reachable by list and read, since neither character is a path separator on any platform's filesystem; the stricter refusal now applies only to a name being chosen by Create. Create also goes back to bringing a fresh root into existence, matching its behaviour before the first confinement fix. A Windows reserved device name (CON, COM1, CONIN$, with or without an extension) is refused in a chosen name on every platform. Regression tests reproduce all three escapes (dangling symlink, swapped-link race, hard link), plus the previously missing coverage: a link in the folder a Create targets, and a write test that actually reaches disk instead of being refused for an unrelated reason before confinement ever ran. Verified by hand that each of the three new write-path tests fails against the pre-fix pattern (an absolute OS path joined by string concatenation) before trusting them. --- Cargo.lock | 13 + crates/cloud-local/Cargo.toml | 6 + crates/cloud-local/README.md | 40 +- crates/cloud-local/src/lib.rs | 354 ++++++++++++------ .../tests/confinement_regressions.rs | 226 ++++++++--- 5 files changed, 469 insertions(+), 170 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 5b17106b4..275144cc8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1074,6 +1074,18 @@ dependencies = [ "winx", ] +[[package]] +name = "cap-std" +version = "4.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1ec78e242cfa2cfe276807ac2ecc00315a6c97786977414bcd1c3963b6c91b8" +dependencies = [ + "cap-primitives", + "io-extras", + "io-lifetimes 3.0.1", + "rustix 1.1.5", +] + [[package]] name = "cast" version = "0.3.0" @@ -1628,6 +1640,7 @@ dependencies = [ name = "craft-cloud-local" version = "0.1.0" dependencies = [ + "cap-std", "craft-cloud", "craft-ui", "egui", diff --git a/crates/cloud-local/Cargo.toml b/crates/cloud-local/Cargo.toml index 6b58b2bfd..39d6dfa6e 100644 --- a/crates/cloud-local/Cargo.toml +++ b/crates/cloud-local/Cargo.toml @@ -11,6 +11,12 @@ description = "A reference CloudBackend over a local folder, proving the contrac workspace = true [dependencies] +# Resolution-time confinement: every path this crate resolves goes through a `Dir` capability +# opened on the configured root, never through an absolute OS path this crate builds itself. +# `craft-font-store` already depends on the lower-level `cap-primitives` for the same family of +# guarantee; this crate uses the ergonomic `cap-std` built on top of it instead of hand-rolling +# the equivalent `Dir`-style API again. +cap-std = "4" craft-cloud = { workspace = true } craft-ui = { workspace = true, features = ["cloud"] } diff --git a/crates/cloud-local/README.md b/crates/cloud-local/README.md index d8f7cb3a7..a5006c2ca 100644 --- a/crates/cloud-local/README.md +++ b/crates/cloud-local/README.md @@ -6,16 +6,34 @@ no specific provider behind it. ## No-escape policy Every path this crate is handed, a `Job::List`/`Read`/`Write` path or a `Job::Create` name, is -confined to the configured root before anything touches a filesystem. +confined to the configured root before anything touches a filesystem, in two layers. -A path's segments, and a `Create` name on its own, are accepted only when each one parses as a -single `Component::Normal`: no `..`, no `.`, no empty segment, no absolute form, and no Windows -drive letter, UNC path or backslash. That last group is refused on every platform this crate -builds for, not only on Windows, because a name reaches this backend from whatever platform the -UI runs on. +A path's segments are accepted only when each one parses as a single `Component::Normal`: no +`..`, no `.`, no empty segment, and no absolute form. A `Create` name goes through a stricter +check of its own, since it is one chosen name and not a path: it additionally refuses a +backslash, a colon, or a Windows reserved device name (`CON`, `COM1`, `CONIN$`, and so on), on +every platform this crate builds for, not only on Windows, because a chosen name reaches this +backend from whatever platform the UI runs on. An existing name that already has one of those +characters, discovered through `list`, stays reachable: `:` and `\` are not path separators on +any platform's filesystem, so refusing to read a real file back because of a byte in its name +(macOS stores a `/` typed in Finder as `:` on disk) would be a usability bug with no matching +security benefit. -Once a candidate path is built from nothing but checked names, it is still confirmed against a -symlink or (on Windows) a directory junction placed somewhere under the root: the nearest -ancestor that already exists is canonicalised and must stay under the canonicalised root. A path -that reaches outside the root this way is refused before any read, write, listing or creation -touches it. +The second layer is the one that actually keeps resolution inside the root: every already +segment-checked relative path is handed to a [`cap-std`](https://docs.rs/cap-std) `Dir` +capability opened on the root, never joined onto the root as an absolute OS path this crate +builds itself. `cap-std` resolves one path component at a time against real, already-open +directory handles, so a symlink or (on Windows) a directory junction anywhere under the root, +dangling or already pointing outside, cannot walk resolution above the root. There is no separate +"does this still look like it is inside the root" check with a window for the directory tree to +change underneath it between the check and the actual read or write; the one resolution is the +open. + +## Hard links + +A hard link is not a symlink, and this backend does not refuse one: from inside the sandbox the +inode it names is an ordinary file. What it protects instead is the shared inode's content: a +write never truncates its target in place. It writes a new sibling file and renames that sibling +over the target, so the target's directory entry is replaced rather than its bytes being +overwritten. A rename only ever changes one name; it does not reach through to any other name, +inside the root or out, that happens to point at the same inode. diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs index c0caf5d45..b3cf5cbe9 100644 --- a/crates/cloud-local/src/lib.rs +++ b/crates/cloud-local/src/lib.rs @@ -20,29 +20,55 @@ //! Every job answers on its own [`std::thread`]. [`CloudBackend::submit`] //! must return before the file is opened, let alone read, or a twenty //! megabyte document would freeze the window that called it. +//! +//! # The no-escape policy +//! +//! `Entry::id` and `Entry::path` are the same slash-separated path relative to +//! `root`, always starting with `/` below the root itself (the root's own +//! path is the empty string, matching [`Job::List`]'s contract), and a +//! [`Job::Create`] name is one plain file name, not a path at all. Neither is +//! an OS path string handed to `std::fs`. Confinement happens in two layers: +//! +//! 1. [`confine_segment`] (every path segment) and [`confine_name`] (a +//! `Create` name, stricter) reject `..`, `.`, an empty segment, an +//! absolute form, and anything that is not exactly one +//! [`std::path::Component::Normal`]. `confine_name` additionally refuses a +//! backslash, a colon, and a Windows reserved device name +//! (`CON`, `COM1`, `CONIN$`, ...) on every platform this crate builds for, +//! because a chosen name reaches this backend from whatever platform the +//! UI runs on. Browsing an *existing* name is more lenient: a literal `:` +//! or `\` already on disk (macOS stores a `/` typed in Finder as `:`) is +//! not itself a path separator on any platform's filesystem, so +//! `confine_segment` lets `list`, `read` and `write` keep such a name +//! reachable instead of discovering it and then refusing to open it. +//! 2. [`open_root`] opens `root` as a [`cap_std::fs::Dir`] capability once per +//! job. Every [`list`], [`read`], [`write`] and [`create`] routes its +//! already-segment-checked relative path through that one `Dir`, never +//! through an absolute OS path built by this crate. `cap_std` resolves one +//! component at a time against real, already-open directory handles, so a +//! symlink or a Windows junction anywhere under `root`, dangling or not, +//! cannot walk resolution above `root`: there is no separate "is this +//! still inside the root" check with a window for the directory tree to +//! change underneath it, because the one resolution *is* the open. +//! +//! A hard link is not a symlink and `cap_std` does not refuse one; the inode +//! it names is an ordinary file from inside the sandbox. [`write`] protects +//! it a different way: it always writes a sibling temporary file and renames +//! it over the target, rather than truncating the target in place. A rename +//! replaces one name's directory entry; it never reaches through to another +//! name that happens to point at the same inode outside `root`. +use std::ffi::OsStr; use std::fs; -use std::io::Write as _; +use std::io::{Read as _, Write as _}; use std::path::{Component, Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use cap_std::fs::{Dir, OpenOptions}; use craft_cloud::{Capability, Entry, EntryKind}; use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; /// Where "the cloud" lives for this backend: one directory on disk. -/// -/// `Entry::id` and `Entry::path` are the same slash-separated path relative to -/// `root`, always starting with `/` below the root itself (the root's own -/// path is the empty string, matching [`Job::List`]'s contract). Neither is -/// an OS path; both go through [`resolve`] and then [`confine_to_root`] -/// before anything touches a filesystem. A [`Job::Create`] name is not a -/// path at all; it goes through the same per-segment check [`resolve`] uses, -/// [`confine_segment`], on its own. Together the two refuse `..`, an -/// absolute form, a Windows drive letter or UNC prefix, and a backslash, -/// regardless of which platform this crate is built for, since a name -/// reaches this backend from whatever platform the UI runs on. No-escape -/// through a symlink or a Windows junction is a separate policy, stated on -/// [`confine_to_root`] itself, and every one of [`list`], [`read`], -/// [`write`] and [`create`] applies it. pub struct LocalBackend { root: PathBuf, /// Shown in the account badge. Nothing else reads it. @@ -52,7 +78,10 @@ pub struct LocalBackend { impl LocalBackend { /// Treat `root` as the cloud. The directory is not created here; a /// listing of a root that does not exist yet answers with a [`Fault`] - /// the same way a real provider's missing folder would. + /// the same way a real provider's missing folder would. [`Job::Create`] + /// is the one exception, and always has been: it brings a fresh root + /// into existence itself, the same way a first Save As does not require + /// the destination folder to already be there. pub fn new(root: PathBuf) -> LocalBackend { LocalBackend { root, display: "Local disk".to_owned() } } @@ -118,80 +147,84 @@ fn account(display: String) -> Account { Account { display, capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } } -/// Turns a [`Job`]'s slash-separated path into a real filesystem path under -/// `root`, refusing anything that is not a run of ordinary names. +/// Turns a [`Job`]'s slash-separated path into a path relative to `root`, +/// refusing anything that is not a run of ordinary names. The result is +/// never joined onto `root` as an OS path; every caller hands it to a +/// [`cap_std::fs::Dir`] opened on `root` instead, which is the layer that +/// actually keeps resolution from leaving `root`. /// /// `.` and repeated or leading slashes are just an empty segment and are /// skipped, the same way a browser's address bar collapses them. Every other -/// segment goes through [`confine_segment`], which is what actually refuses -/// `..`, an absolute form, a backslash or a drive letter, or anything else -/// that is not one ordinary name. This function never touches disk, so it -/// cannot see a symlink or a junction; [`confine_to_root`] is the other half -/// of the promise, and every caller of `resolve` runs both. -fn resolve(root: &Path, path: &str) -> Result { - let mut real = root.to_path_buf(); +/// segment goes through [`confine_segment`]. +fn relative(path: &str) -> Result { + let mut rel = PathBuf::new(); for segment in path.split('/') { if segment.is_empty() || segment == "." { continue; } - real.push(confine_segment(segment)?); + rel.push(confine_segment(segment)?); } - Ok(real) + Ok(rel) } -/// Confines one path segment, or a whole [`Job::Create`] name, to a single -/// ordinary file or folder name. +/// Confines one path segment to a single ordinary file or folder name. /// /// Accepted only when `segment` parses as exactly one [`Component::Normal`] /// equal to `segment` itself: no empty name, no `.` or `..`, no absolute -/// form, and nothing left over for a second component to hide in. A -/// `std::path::Component` parse alone does not catch every one of those on -/// every platform; a Unix build's parser does not know what `C:` or -/// `\\server\share` mean, so it would wave a Windows drive letter or a UNC -/// prefix straight through as one ordinary name. A `:` or a `\` is refused -/// outright first, on every platform, for exactly that reason: a name -/// reaches this backend's public [`CloudBackend::submit`] from whatever -/// platform the UI happens to run on, and a Windows-shaped escape must not -/// slip past a Linux build's narrower native parser, or the reverse. +/// form, and nothing left over for a second component to hide in. +/// +/// This is deliberately lenient about an ordinary character such as `:` or +/// `\` that is not, on its own, a path separator on any platform's +/// filesystem: `list` discovers real names from disk, and a name containing +/// one of those (macOS stores a `/` typed in Finder as `:` on disk) must stay +/// reachable by a later `read` or `write`, not become visible-but-unopenable. +/// [`confine_name`] is the stricter check for a name being chosen new, where +/// refusing those characters costs nothing and closes a real escape. fn confine_segment(segment: &str) -> Result<&str, Fault> { - if segment.contains('\\') || segment.contains(':') { - return Err(Fault::Refused(format!("{segment} is not a plain file name"))); - } let mut components = Path::new(segment).components(); match (components.next(), components.next()) { - (Some(Component::Normal(name)), None) if name == std::ffi::OsStr::new(segment) => Ok(segment), + (Some(Component::Normal(name)), None) if name == OsStr::new(segment) => Ok(segment), _ => Err(Fault::Refused(format!("{segment} is not a plain file name"))), } } -/// Confirms a path already built from nothing but [`confine_segment`]-checked -/// names still cannot have reached outside `root` through a symlink or, on -/// Windows, a directory junction. +/// Windows device names that name a device rather than a file, with or +/// without a trailing extension (`CON`, `con.txt`, ...). Checked on every +/// platform: a name chosen here can end up read on a Windows client too. +const WINDOWS_RESERVED_NAMES: &[&str] = &[ + "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", + "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", +]; + +fn is_windows_reserved_name(name: &str) -> bool { + let stem = name.split('.').next().unwrap_or(name); + WINDOWS_RESERVED_NAMES.iter().any(|reserved| stem.eq_ignore_ascii_case(reserved)) +} + +/// Confines a [`Job::Create`] `name` to a single ordinary file name that is +/// safe to choose on any platform, not only the one this crate is built for. /// -/// The no-escape policy: `candidate` need not exist yet, since [`write`] and -/// [`create`] both route a path that may still be about to be created -/// through here. Starting at `candidate` and walking up through its -/// ancestors, the first one that does exist is canonicalised and compared -/// against the canonicalised `root`. Nothing below that ancestor exists -/// either, so a link cannot sit on any of the remaining components, and -/// every one of them is already known to be ordinary `Component::Normal` -/// text, never `..` or an absolute form, because [`confine_segment`] is what -/// built them. A canonical path that lands outside `root` is refused; -/// nothing here ever opens, reads or writes through it. -fn confine_to_root(root: &Path, candidate: &Path) -> Result { - let real_root = fs::canonicalize(root).map_err(|error| io_fault(&error))?; - let mut probe = candidate; - loop { - match fs::canonicalize(probe) { - Ok(real) if real == real_root || real.starts_with(&real_root) => return Ok(candidate.to_path_buf()), - Ok(_) => return Err(Fault::Refused("that path leaves this folder".to_owned())), - Err(error) if error.kind() == std::io::ErrorKind::NotFound => match probe.parent() { - Some(parent) => probe = parent, - None => return Err(io_fault(&error)), - }, - Err(error) => return Err(io_fault(&error)), - } +/// Stricter than [`confine_segment`]: a backslash or colon is refused +/// outright first, because a Unix build's [`Component`] parser does not +/// treat either as a separator and would wave a Windows drive letter or UNC +/// prefix (`C:`, `\\server\share`) straight through as one ordinary name. A +/// Windows reserved device name is refused the same way. None of this costs +/// anything here, unlike applying it to a name `list` merely discovered. +fn confine_name(name: &str) -> Result<&str, Fault> { + if name.contains('\\') || name.contains(':') { + return Err(Fault::Refused(format!("{name} is not a plain file name"))); } + if is_windows_reserved_name(name) { + return Err(Fault::Refused(format!("{name} is a reserved device name on Windows"))); + } + confine_segment(name) +} + +/// Opens `root` as the one ambient-authority capability this crate holds. +/// Every other path in this crate is resolved relative to the [`Dir`] this +/// returns, never as an absolute OS path built by string concatenation. +fn open_root(root: &Path) -> Result { + Dir::open_ambient_dir(root, cap_std::ambient_authority()).map_err(|error| io_fault(&error)) } /// The path a listed child gets, given the folder it was found in. @@ -204,8 +237,9 @@ fn child_path(folder: &str, name: &str) -> String { /// Not a timestamp for a person to read (that would go through `chrono`, per /// this workspace's rule); just enough to tell "the file I read" from "the /// file as it is now" apart, which is all a conditional write needs. -fn etag_of(meta: &fs::Metadata) -> String { - let stamp = meta.modified().ok().and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0); +fn etag_of(meta: &cap_std::fs::Metadata) -> String { + let stamp = + meta.modified().ok().and_then(|time| time.duration_since(cap_std::time::SystemClock::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0); format!("{}-{stamp}", meta.len()) } @@ -219,8 +253,10 @@ fn io_fault(error: &std::io::Error) -> Fault { } fn list(root: &Path, path: &str) -> Result, Fault> { - let dir = confine_to_root(root, &resolve(root, path)?)?; - let read = fs::read_dir(&dir).map_err(|error| io_fault(&error))?; + let rel = relative(path)?; + let dir = open_root(root)?; + let read = if rel.as_os_str().is_empty() { dir.entries() } else { dir.read_dir(&rel) }; + let read = read.map_err(|error| io_fault(&error))?; let mut entries = Vec::new(); for item in read { let item = item.map_err(|error| io_fault(&error))?; @@ -247,15 +283,32 @@ fn list(root: &Path, path: &str) -> Result, Fault> { /// Reads a file's bytes together with the entry for the version just read. /// -/// The entry is built from a fresh [`fs::metadata`] call here, not handed back +/// The entry is built from a fresh metadata call here, not handed back /// unchanged from what the caller already believed. A reload after a conflict /// hands in the stale entry it is trying to get past; echoing that back would /// carry the old etag into the reloaded document, so the very next save would /// conflict again on a copy that is actually current. +/// +/// Refuses outright if `entry.id` names a symlink, the same policy `write` +/// uses: this backend never reports the bytes of whatever a link happens to +/// point at, inside `root` or out. fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { - let file = confine_to_root(root, &resolve(root, &entry.id)?)?; - let bytes = fs::read(&file).map_err(|error| io_fault(&error))?; - let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + // Stats without following only the last component; every component + // before it is still resolved, and sandboxed, normally, so a link + // earlier in `rel` is refused by `open_root`'s `Dir` itself when `open` + // below walks it, never silently followed here either way. + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(_) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), + } + let mut file = dir.open(&rel).map_err(|error| io_fault(&error))?; + let mut bytes = Vec::new(); + file.read_to_end(&mut bytes).map_err(|error| io_fault(&error))?; + let meta = file.metadata().map_err(|error| io_fault(&error))?; let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }; Ok((fresh, bytes)) } @@ -263,35 +316,97 @@ fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { /// Saves back over `entry`, refusing the write when the file moved on since /// `entry.etag` was read. A file that no longer exists has nothing to /// conflict with, the same way a provider treats a deleted document. +/// +/// Never truncates `entry.id`'s current bytes in place. [`write_replacing`] +/// writes a sibling temporary file and renames it over the target instead, +/// so a hard link sharing the target's inode keeps its own, unmodified copy: +/// the rename replaces `entry.id`'s directory entry, and never reaches +/// through to any other name pointing at the same inode. fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { - let file = confine_to_root(root, &resolve(root, &entry.id)?)?; - if let Ok(meta) = fs::metadata(&file) - && Some(etag_of(&meta)) != entry.etag - { - return Err(Fault::Conflict); + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(meta) => { + if Some(etag_of(&meta)) != entry.etag { + return Err(Fault::Conflict); + } + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), } - if let Some(parent) = file.parent() { - fs::create_dir_all(parent).map_err(|error| io_fault(&error))?; + if let Some(parent) = rel.parent() { + dir.create_dir_all(parent).map_err(|error| io_fault(&error))?; } - fs::write(&file, bytes).map_err(|error| io_fault(&error))?; - let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?; + write_replacing(&dir, &rel, bytes)?; + let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?; Ok(Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }) } +/// The next in a run of sibling temporary names, unique within this process. +/// Not meant to resist a second process picking the same name; the create +/// this writes with is exclusive (`create_new`), so a collision there is +/// just retried under a new counter value rather than silently overwritten. +static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0); + +/// Writes `bytes` to a new sibling of `rel` inside `dir`, then renames that +/// sibling over `rel`. See the module docs for why: a direct write would +/// truncate whatever `rel` currently names in place, and if that happens to +/// be a hard link to a file outside `root`, the outside copy would be +/// corrupted along with it. A rename only ever replaces `rel`'s own +/// directory entry. +fn write_replacing(dir: &Dir, rel: &Path, bytes: &[u8]) -> Result<(), Fault> { + let name = rel.file_name().ok_or_else(|| Fault::Refused("that path names no file".to_owned()))?; + let mut temp_name = OsStr::new(".").to_os_string(); + temp_name.push(name); + temp_name.push(format!(".tmp-{}-{}", std::process::id(), TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed))); + let temp_rel = match rel.parent() { + Some(parent) if !parent.as_os_str().is_empty() => parent.join(&temp_name), + _ => PathBuf::from(&temp_name), + }; + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + let written = (|| -> Result<(), Fault> { + let mut handle = dir.open_with(&temp_rel, &options).map_err(|error| io_fault(&error))?; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + handle.sync_all().map_err(|error| io_fault(&error)) + })(); + if let Err(fault) = written { + let _ = dir.remove_file(&temp_rel); + return Err(fault); + } + if let Err(error) = dir.rename(&temp_rel, dir, rel) { + let _ = dir.remove_file(&temp_rel); + return Err(io_fault(&error)); + } + Ok(()) +} + fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result { - // `name` is never a path: it is one [`Job::Create`] field that names the - // new file, so it goes through `confine_segment` directly rather than - // through `resolve`, which only ever splits and confines a slash path. - let name = confine_segment(name)?; - let dir = confine_to_root(root, &resolve(root, folder)?)?; - fs::create_dir_all(&dir).map_err(|error| io_fault(&error))?; - let file = dir.join(name); + // `name` is never a path: it is one `Job::Create` field that names the + // new file, so it goes through `confine_name` directly rather than + // through `relative`, which only ever splits and confines a slash path. + let name = confine_name(name)?; + // `root` is the operator-configured boundary, never attacker input, so + // creating it directly with `std::fs` is safe; this is also the one + // place that has always brought a fresh root into existence (see + // `LocalBackend::new`'s docs), and `Dir::open_ambient_dir` below needs it + // to already exist. + fs::create_dir_all(root).map_err(|error| io_fault(&error))?; + let dir = open_root(root)?; + let rel_folder = relative(folder)?; + dir.create_dir_all(&rel_folder).map_err(|error| io_fault(&error))?; + let rel = rel_folder.join(name); // Exclusive creation, not an `exists` check ahead of a separate write: two // creates of the same name racing both see "not there yet" otherwise, and // the second write silently replaces the first with neither ever refused. // `create_new` asks the filesystem to open and create in one step, so the - // loser gets an error instead of a chance to overwrite the winner. - let mut handle = match fs::OpenOptions::new().write(true).create_new(true).open(&file) { + // loser gets an error instead of a chance to overwrite the winner. It also + // refuses outright when `name` already exists as a symlink, dangling or + // not: `O_EXCL` never follows one to decide whether it is "in the way". + let mut create_options = OpenOptions::new(); + create_options.write(true).create_new(true); + let mut handle = match dir.open_with(&rel, &create_options) { Ok(handle) => handle, Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => { return Err(Fault::Refused(format!("{name} already exists"))); @@ -300,7 +415,7 @@ fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result Vec { - settle(app, ctx, |app| !app.said.lock().unwrap().is_empty()); + app.opened.lock().unwrap().clear(); + app.said.lock().unwrap().clear(); + settle(app, ctx, |app| !app.said.lock().unwrap().is_empty() || !app.opened.lock().unwrap().is_empty()); app.said.lock().unwrap().clone() } @@ -117,27 +125,26 @@ struct Sentinels { sentinel_dir: PathBuf, } +const SENTINEL_FILE_BYTES: &[u8] = b"a sibling file this backend must never read or write"; +const SENTINEL_DIR_FILE_BYTES: &[u8] = b"a sibling directory this backend must never list"; + fn sentinels() -> Sentinels { let arena = tempfile::tempdir().unwrap(); let root = arena.path().join("root"); std::fs::create_dir(&root).unwrap(); let sentinel_file = arena.path().join("sentinel.txt"); - std::fs::write(&sentinel_file, b"a sibling file this backend must never read or write").unwrap(); + std::fs::write(&sentinel_file, SENTINEL_FILE_BYTES).unwrap(); let sentinel_dir = arena.path().join("sentinel-dir"); std::fs::create_dir(&sentinel_dir).unwrap(); - std::fs::write(sentinel_dir.join("secret.txt"), b"a sibling directory this backend must never list").unwrap(); + std::fs::write(sentinel_dir.join("secret.txt"), SENTINEL_DIR_FILE_BYTES).unwrap(); Sentinels { _arena: arena, root, sentinel_file, sentinel_dir } } fn assert_sentinels_untouched(sentinels: &Sentinels) { - assert_eq!( - std::fs::read(&sentinels.sentinel_file).unwrap(), - b"a sibling file this backend must never read or write", - "the sentinel file outside the root was changed" - ); + assert_eq!(std::fs::read(&sentinels.sentinel_file).unwrap(), SENTINEL_FILE_BYTES, "the sentinel file outside the root was changed"); assert_eq!( std::fs::read(sentinels.sentinel_dir.join("secret.txt")).unwrap(), - b"a sibling directory this backend must never list", + SENTINEL_DIR_FILE_BYTES, "the sentinel directory's file outside the root was changed" ); } @@ -165,28 +172,13 @@ fn create_refuses_every_escaping_name_and_the_sentinels_stay_untouched() { } } -/// A folder path for `Job::List` can carry the same Windows-shaped escape a `Create` name can; -/// `resolve` must refuse it through the identical [`confine_segment`] check, not a weaker one. -#[test] -fn listing_a_windows_shaped_folder_path_is_refused_on_every_platform() { - let sentinels = sentinels(); - let (mut app, ctx) = wired(sentinels.root.clone()); - - cloud::browse(&mut app, "..\\sentinel-dir"); - settle(&mut app, &ctx, |app| app.cloud().mine.loaded); - - assert!(app.cloud().mine.error.is_some(), "a backslash-separated folder path must be refused"); - assert!(app.cloud().mine.entries.is_empty()); - assert_sentinels_untouched(&sentinels); -} - // ------------------------------------------------------------------- link-based escapes // // `escape(&sentinels)` places one link named `escape` inside the cloud root, pointing out to // `sentinels.sentinel_dir`: a symlink on Unix, a directory junction on Windows, which needs no // elevated privilege, unlike a Windows symlink. The Linux gate runs the symlink half of every -// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/secret.txt` -// is the same sentinel file reached through the link. +// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/...` +// reaches into the sentinel directory through the link. /// Nothing to clean up on Unix: `tempfile`'s own recursive removal of the arena directory /// removes a plain symlink entry without following it. This exists only so `escape` returns the @@ -228,13 +220,14 @@ fn escape(sentinels: &Sentinels) -> Junction { Junction(link) } -#[cfg(any(unix, windows))] -fn leaked_entry() -> Entry { +/// An [`Entry`] stub naming `id`, for a [`Job::Read`] or [`Job::Write`] this file submits +/// directly rather than through an entry the backend itself handed back. +fn leaked_entry(id: &str, name: &str) -> Entry { Entry { - id: "/escape/secret.txt".to_owned(), - room: "local:/escape/secret.txt".to_owned(), - name: "secret.txt".to_owned(), - path: "/escape/secret.txt".to_owned(), + id: id.to_owned(), + room: format!("local:{id}"), + name: name.to_owned(), + path: id.to_owned(), kind: EntryKind::File, size: None, modified: None, @@ -267,23 +260,172 @@ fn reading_through_a_linked_folder_cannot_return_bytes_from_outside_the_root() { let (mut app, ctx) = wired(sentinels.root.clone()); let _escape = escape(&sentinels); - cloud::submit(&app, Job::Read { entry: leaked_entry(), into: None }); + cloud::submit(&app, Job::Read { entry: leaked_entry("/escape/secret.txt", "secret.txt"), into: None }); said(&mut app, &ctx); assert!(app.opened.lock().unwrap().is_empty(), "a read through a symlink or junction out of the root must not deliver bytes"); assert_sentinels_untouched(&sentinels); } +/// benandez's finding 4: the original version of this test targeted the pre-existing +/// `secret.txt`, with `etag: None`. `write` refused that for an unrelated reason, a version +/// mismatch, before confinement ever ran, so the test passed whether or not confinement worked. +/// Targeting a name that does not exist yet under the link reaches the code that actually +/// matters, and the oracle (the file must never be created) is one confinement failing would +/// actually flip. #[cfg(any(unix, windows))] #[test] -fn writing_through_a_linked_folder_cannot_change_a_file_outside_the_root() { +fn writing_through_a_linked_folder_cannot_create_a_file_outside_the_root() { let sentinels = sentinels(); let (mut app, ctx) = wired(sentinels.root.clone()); let _escape = escape(&sentinels); - cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry(), bytes: b"pwned".to_vec() }); + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/escape/not-yet-created.txt", "not-yet-created.txt"), bytes: b"pwned".to_vec() }); said(&mut app, &ctx); - assert!(app.cloud().conflict.is_none(), "this must be refused outright, not treated as a stale-version conflict"); + assert!(!sentinels.sentinel_dir.join("not-yet-created.txt").exists(), "a write through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 5: nothing previously exercised a link in the `folder` a `Create` targets. +#[cfg(any(unix, windows))] +#[test] +fn creating_through_a_linked_folder_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Create { uid: 1, folder: "escape".to_owned(), name: "new.txt".to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "a create into a linked folder must not be reported as created"); + assert!(!messages.is_empty(), "a create into a linked folder must be refused, not silently dropped"); + assert!(!sentinels.sentinel_dir.join("new.txt").exists(), "a create through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +// ------------------------------------------------------------------- Unix-only reproductions +// +// Directory junctions cannot be dangling (`mklink /J` requires the target to exist) and the +// race and hard-link reproductions below are exactly benandez's own repros, run on Linux only, +// as stated in that review. The structural fix (resolving through a `cap_std::fs::Dir`, and +// writing through a temporary file and rename) is the same code on every platform; these three +// just do not have a Windows-shaped equivalent worth a separate repro. + +/// benandez's finding 1, reproduced exactly: `root/doc.txt` is a symlink to a file that does not +/// exist yet, outside the root. The old code's `confine_to_root` canonicalised the dangling link +/// to `NotFound`, walked up to `root`, accepted it, found no file to conflict with, and `write` +/// created the target for real, outside the root. +#[cfg(unix)] +#[test] +fn writing_through_a_dangling_symlink_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let outside_target = sentinels._arena.path().join("outside-planted.txt"); + std::os::unix::fs::symlink(&outside_target, sentinels.root.join("doc.txt")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/doc.txt", "doc.txt"), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(!outside_target.exists(), "a write through a dangling symlink must not create its target outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 3, reproduced exactly: `root/hl` is a hard link sharing an inode with a +/// file outside the root. Reading it through the backend is legitimate (it is, from inside the +/// sandbox, an ordinary file), which is also how this test gets a real, matching etag to write +/// with, the same way a real caller would after opening the document. The old code's `write` +/// truncated the shared inode in place; `write_replacing` must instead replace `hl`'s own +/// directory entry, leaving the sentinel file's inode, and its other name, untouched. +#[cfg(unix)] +#[test] +fn writing_through_a_hard_link_replaces_the_entry_without_touching_the_shared_file() { + let sentinels = sentinels(); + std::fs::hard_link(&sentinels.sentinel_file, sentinels.root.join("hl")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Read { entry: leaked_entry("/hl", "hl"), into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + let real_entry = app.cloud().origins.get(&1).expect("the read registered an origin for uid 1").entry.clone(); + + // A successful write answers through `cloud.status`, not through `said` or `opened`, so it + // needs its own wait condition rather than the `said` helper used everywhere else in this + // file for a refusal. The read above already set `status` once (`Opened hl from the + // cloud.`), so that has to be cleared first or this would observe the read's own status and + // never actually wait for the write to finish. + app.cloud_mut().status = None; + cloud::submit(&app, Job::Write { uid: 1, entry: real_entry, bytes: b"replaced via rename, not truncated in place".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().status.is_some() || app.cloud().conflict.is_some() || !app.said.lock().unwrap().is_empty()); + assert!(app.cloud().conflict.is_none(), "the write through the hard-linked name should succeed, not conflict"); + assert!( + app.said.lock().unwrap().is_empty(), + "the write through the hard-linked name should succeed, not be refused: {:?}", + app.said.lock().unwrap() + ); + + assert_eq!( + std::fs::read(sentinels.root.join("hl")).unwrap(), + b"replaced via rename, not truncated in place", + "the write through the hard-linked name should still succeed" + ); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 2, reproduced at a smaller scale: a background thread swaps `root/d` +/// between a symlink into an inside folder and a symlink to the sentinel directory, as fast as +/// it can, with no coordination with the reads below. The old code's `confine_to_root` checked +/// one path string and then `fs::read` resolved that path again, a second, later lookup a swap +/// could land in between; out of 3000 such reads benandez's own run returned the outside file's +/// bytes 347 times. `cap_std::fs::Dir::open` resolves and opens `d` as one operation with no +/// such second lookup, so this must come back empty every time, not merely most of the time. +#[cfg(unix)] +#[test] +fn reading_through_a_link_being_swapped_never_observes_the_outside_target() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let sentinels = sentinels(); + let inside = sentinels.root.join("inside"); + std::fs::create_dir(&inside).unwrap(); + std::fs::write(inside.join("secret.txt"), b"inside bytes, always safe to read").unwrap(); + let link = sentinels.root.join("d"); + std::os::unix::fs::symlink(&inside, &link).unwrap(); + + let stop = Arc::new(AtomicBool::new(false)); + let swapper = { + let stop = stop.clone(); + let link = link.clone(); + let outside = sentinels.sentinel_dir.clone(); + std::thread::spawn(move || { + let temp = link.with_extension("swap"); + let mut toward_outside = false; + while !stop.load(Ordering::Relaxed) { + let target = if toward_outside { &outside } else { &inside }; + // A stale `temp` from a rename that did not happen (should not occur, but a + // leftover `temp` would otherwise wedge every later iteration's `symlink` call, + // silently stopping the swap rather than failing the test loudly) is cleared + // first so this loop cannot get stuck. + let _ = std::fs::remove_file(&temp); + if std::os::unix::fs::symlink(target, &temp).is_ok() { + let _ = std::fs::rename(&temp, &link); + } + toward_outside = !toward_outside; + } + }) + }; + + let (mut app, ctx) = wired(sentinels.root.clone()); + let mut leaked = false; + for _ in 0..200 { + cloud::submit(&app, Job::Read { entry: leaked_entry("/d/secret.txt", "secret.txt"), into: None }); + said(&mut app, &ctx); + if let Some((_, bytes)) = app.opened.lock().unwrap().first() { + leaked |= bytes.as_slice() == SENTINEL_DIR_FILE_BYTES; + } + } + + stop.store(true, Ordering::Relaxed); + swapper.join().unwrap(); + + assert!(!leaked, "a read observed the outside target's bytes while the link was being swapped underneath it"); assert_sentinels_untouched(&sentinels); } From e52480662119998ca3e7b07792a4eb46759709f8 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 11:25:41 +0100 Subject: [PATCH 12/97] craft-audio: the Vorbis decoder's bit-reversal loop iterates the table --- crates/audio/src/vorbis/decoder/mdct.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/audio/src/vorbis/decoder/mdct.rs b/crates/audio/src/vorbis/decoder/mdct.rs index 5f4579e62..b4eb6c8ec 100644 --- a/crates/audio/src/vorbis/decoder/mdct.rs +++ b/crates/audio/src/vorbis/decoder/mdct.rs @@ -69,8 +69,7 @@ impl Imdct { fn fft(&self, a: &mut [Cpx]) { let h = a.len(); - for i in 0..h { - let j = self.rev[i]; + for (i, &j) in self.rev.iter().enumerate() { if i < j { a.swap(i, j); } From f32b47a1d4799269b7e4b99bb130161dcb7b312a Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:00:14 +0800 Subject: [PATCH 13/97] Add opt-in checked SVG image validation --- Cargo.lock | 4 + crates/svg/Cargo.toml | 13 +- crates/svg/README.md | 55 +++ crates/svg/src/tree.rs | 23 +- crates/svg/src/tree/draw.rs | 8 + crates/svg/src/tree/draw/decoder_edges.rs | 127 ++++++ crates/svg/src/tree/draw/raster.rs | 140 +++++++ crates/svg/src/tree/image_href.rs | 428 +++++++++++++++++++++ crates/svg/src/tree/mime_header_tests.rs | 158 ++++++++ crates/svg/src/tree/validated.rs | 393 +++++++++++++++++++ crates/svg/src/tree/validated/tests.rs | 340 ++++++++++++++++ crates/svg/src/tree/validated/xml_tests.rs | 176 +++++++++ 12 files changed, 1861 insertions(+), 4 deletions(-) create mode 100644 crates/svg/src/tree/draw/decoder_edges.rs create mode 100644 crates/svg/src/tree/draw/raster.rs create mode 100644 crates/svg/src/tree/image_href.rs create mode 100644 crates/svg/src/tree/mime_header_tests.rs create mode 100644 crates/svg/src/tree/validated.rs create mode 100644 crates/svg/src/tree/validated/tests.rs create mode 100644 crates/svg/src/tree/validated/xml_tests.rs diff --git a/Cargo.lock b/Cargo.lock index a9290398b..4da6cf6c9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3092,14 +3092,18 @@ dependencies = [ "craft-xml", "data-url", "flate2", + "gif", + "image-webp", "kurbo 0.13.1", "quick-xml 0.41.0", "resvg 0.48.1", "roxmltree 0.21.2", "thiserror 2.0.21", + "toml", "usvg 0.48.1", "vectorcraft-geom", "vectorcraft-pathops", + "zune-jpeg", ] [[package]] diff --git a/crates/svg/Cargo.toml b/crates/svg/Cargo.toml index b35c4de41..4b7e928a8 100644 --- a/crates/svg/Cargo.toml +++ b/crates/svg/Cargo.toml @@ -31,6 +31,13 @@ usvg = { version = "=0.48.1", default-features = false, optional = true } resvg = { version = "=0.48.1", default-features = false, features = ["text", "raster-images"], optional = true } data-url = { version = "0.3.2", optional = true } +# Renderer-specific validation uses the same resolved backends as resvg0.48.1. +# zune-jpeg is used under its MIT licence option. The locked edge-alignment +# regression must pass when changing this renderer/backend dependency group. +zune-jpeg = { version = "=0.5.15", optional = true } +gif = { version = "=0.14.2", optional = true } +image-webp = { version = "=0.2.4", optional = true } + [features] default = ["paths"] @@ -45,5 +52,9 @@ tree-text = ["tree", "usvg/text"] # The system's fonts in `usvg::fontdb`. tree-system-fonts = ["tree-text", "usvg/system-fonts"] # Bounded rendering of a parsed tree through the matching resvg/tiny-skia versions. -tree-render = ["tree", "dep:resvg"] +tree-render = ["tree", "dep:resvg", "dep:zune-jpeg", "dep:gif", "dep:image-webp"] tree-render-system-fonts = ["tree-render", "resvg/system-fonts"] + +[dev-dependencies] +# Already resolved in the workspace; test-only Cargo.lock edge inspection. +toml = "=1.1.8" diff --git a/crates/svg/README.md b/crates/svg/README.md index 508081367..0810b1217 100644 --- a/crates/svg/README.md +++ b/crates/svg/README.md @@ -16,3 +16,58 @@ The shared adapter adds an aggregate 64 MiB stylesheet-text limit and idempotent ### Transform compatibility `transform_compat::parse_transform` preserves EffectCraft transform-list recovery and exact composition. It retains six numeric arguments per operation; scanning is not time/byte capped and matrix overflow behavior is unchanged. The strict geometry reader is unchanged. Source: Brandon Thomas, EffectCraft94e1c86d89a866771f80ad1610afda9aa12e85d8; bounded safe argument matching by Altynzhan Karybai,4035d181329e847d7a57bf3d059502ea2c91b560. + + +### Opt-in validated embedded images + +With `tree-render`, `tree::ValidatedImageResolver` owns one drawing's immutable +`Limits`, original child-source work, data-URL normalization and renderer-specific +raster validation. Existing `ImageResolver::new`/`resolver` and legacy parse entry +points retain their behavior. Opt in explicitly: + +```rust +# #[cfg(feature = "tree-render")] +# fn example() -> Result<(), craft_svg::tree::Error> { +use craft_svg::tree::{self, Limits, ValidatedImageResolver, usvg}; +let images = ValidatedImageResolver::new(Limits::default()); +let checked = tree::preflight( + "", + &images.limits(), +)?; +let drawing = images.parse_preflight(checked, usvg::Options::default())?; +let usage = images.usage(); +// Importers disclose usage's invalid_* and *_limit_images; strict consumers refuse them. +# let _ = (drawing, usage); +# Ok(()) +# } +``` + +The caller supplies fonts and a sufficient stack/worker for its depth policy. +`parse_preflight` accepts only an opaque preflight made with exactly this context's +limits. It consumes options and installs its own data-only resolver, including for +all children; unrelated callbacks cannot fetch a linked file or bypass admission. +The full expanded root height and each child's expanded height share one depth +allowance. An overlapping root conversion on the same context is refused. + +Unchanged XML converts from its original checked DOM. A modified data URL requires +one checked replacement DOM. Invalid URLs become bounded resolver-visible image +failures; hidden, unused and foreign elements do not acquire omission counts. +Original UTF-8 child bytes are charged before XML conversion or shorter repairs, +with per-document and aggregate bounds. Failed inflation/text work is not refunded; +separate bounded retry-classification work never admits another child. Encoded +raster callbacks spend at most `limits.bytes + limits.embedded_bytes` cumulatively, +without retaining their sources. Pixel work and decoder allocation are admitted +before decoding; attempted failures keep their charge. An oversized unattempted +image does not prevent a later smaller image from fitting. + +`resolve_text` accepts an already-decoded child SVG through the same admission +context, rather than an unchecked DOM or a precharged-budget override. `usage()` +reports omissions and work after conversion. The context is for one drawing, not a +global rendering cache. + +The renderer has no public decoded-pixel or decode-result hook. Validation therefore +still decodes raster pixels before later renderer painting. The shared validator +owns the backend dependencies; locked dependency-edge tests in both the shared +workspace and consumers must keep them aligned with the selected resvg/usvg graph. +This is a fail-fast maintenance check, not automatic access to private renderer +code or a decode-once performance claim. Direct zune-jpeg use selects its MIT option. diff --git a/crates/svg/src/tree.rs b/crates/svg/src/tree.rs index ab04a3002..80feec75d 100644 --- a/crates/svg/src/tree.rs +++ b/crates/svg/src/tree.rs @@ -34,7 +34,13 @@ use crate::{guard, svgz}; pub mod document; pub mod draw; +#[cfg(feature = "tree-render")] +mod image_href; pub mod primitive; +#[cfg(feature = "tree-render")] +mod validated; +#[cfg(feature = "tree-render")] +pub use validated::ValidatedImageResolver; /// What one import may use. The defaults suit a desktop app that parses on a thread with a /// large stack (see the module text). @@ -161,6 +167,7 @@ pub fn root_unitless_size(svg: &str, limits: &Limits) -> Result { + limits: Limits, xml: roxmltree::Document<'s>, depth: usize, /// [`height`]: the nesting usvg converts, references followed. @@ -219,6 +226,8 @@ const UNSUPPORTED: &[&str] = &[ /// Checks already-decoded SVG text once, retaining the parsed XML for both depth policy and tree conversion. pub fn preflight<'s>(svg: &'s str, limits: &Limits) -> Result, Error> { + #[cfg(test)] + PREFLIGHT_PASSES.with(|count| count.set(count.get().saturating_add(1))); let preflight_limits = crate::preflight::Limits { bytes: limits.bytes, depth: limits.depth, @@ -239,7 +248,7 @@ pub fn preflight<'s>(svg: &'s str, limits: &Limits) -> Result, Err let Some(height) = height(&xml, limits.tree_depth)? else { return Err(Error::TooDeep(limits.tree_depth)); }; - Ok(Preflight { xml, depth, height }) + Ok(Preflight { limits: *limits, xml, depth, height }) } /// Dimensions of an SVG viewport in SVG user units. @@ -432,9 +441,12 @@ struct Used { /// What resolving one drawing's embedded images used or refused. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct ImageUsage { - /// Unique decoded raster pixels reserved before decode. + /// Decoded raster pixel work reserved before decode. The legacy resolver + /// shares a charge across repeated data; the validated context charges each + /// attempted decode, including failures. pub raster_pixels: u64, - /// Unpacked SVG bytes consumed by embedded SVG data URLs. + /// Decoded SVG text work charged to embedded data URLs, including the + /// remaining allowance consumed by a failed inflation attempt. pub embedded_svg_bytes: usize, /// Embedded SVG images parsed, including nested images. pub embedded_svg_count: usize, @@ -730,3 +742,8 @@ fn image_resolver_for(limits: Limits, used: Arc) -> usvg::ImageHrefResolve #[cfg(test)] mod tests; + +#[cfg(test)] +thread_local! { + static PREFLIGHT_PASSES: std::cell::Cell = const { std::cell::Cell::new(0) }; +} diff --git a/crates/svg/src/tree/draw.rs b/crates/svg/src/tree/draw.rs index f83653284..8a8bb1a7a 100644 --- a/crates/svg/src/tree/draw.rs +++ b/crates/svg/src/tree/draw.rs @@ -29,6 +29,11 @@ pub use resvg; #[cfg(feature = "tree-render")] pub use resvg::tiny_skia; +#[cfg(feature = "tree-render")] +mod raster; +#[cfg(feature = "tree-render")] +pub use raster::{RasterValidationFailure, validate_raster}; + /// Filter primitives per filter. A result of every primitive is kept; real filters have 1 to 12 /// (Inkscape's drop shadow has 5), and 64 leaves headroom for generated ones. const MAX_PRIMITIVES: usize = 64; @@ -546,3 +551,6 @@ fn deeper(cx: Cx) -> Result<(), Refusal> { } Ok(()) } + +#[cfg(all(test, feature = "tree-render"))] +mod decoder_edges; diff --git a/crates/svg/src/tree/draw/decoder_edges.rs b/crates/svg/src/tree/draw/decoder_edges.rs new file mode 100644 index 000000000..8258b5792 --- /dev/null +++ b/crates/svg/src/tree/draw/decoder_edges.rs @@ -0,0 +1,127 @@ +//! Test-only resolved-edge checks. No Cargo subprocess or global version count. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)] + +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct PackageId { + name: String, + version: String, + source: Option, +} +struct Package { + id: PackageId, + dependencies: Vec, +} +pub(crate) struct LockGraph { + packages: Vec, +} +impl LockGraph { + pub(crate) fn parse(text: &str) -> Self { + let lock: toml::Value = text.parse().unwrap(); + let packages = lock + .get("package") + .unwrap() + .as_array() + .unwrap() + .iter() + .map(|package| { + let string = |key| package.get(key).unwrap().as_str().unwrap().to_owned(); + Package { + id: PackageId { + name: string("name"), + version: string("version"), + source: package.get("source").map(|v| v.as_str().unwrap().to_owned()), + }, + dependencies: package + .get("dependencies") + .map(|d| d.as_array().unwrap().iter().map(|v| v.as_str().unwrap().to_owned()).collect()) + .unwrap_or_default(), + } + }) + .collect(); + Self { packages } + } + pub(crate) fn workspace_package(&self, name: &str) -> PackageId { + let found: Vec<_> = self.packages.iter().filter(|p| p.id.name == name && p.id.source.is_none()).collect(); + assert_eq!(found.len(), 1, "one exact workspace package required: {name}"); + found[0].id.clone() + } + pub(crate) fn dependency(&self, from: &PackageId, name: &str) -> PackageId { + let package = self.packages.iter().find(|p| &p.id == from).unwrap(); + let edges: Vec<_> = package.dependencies.iter().filter(|edge| edge.split_whitespace().next() == Some(name)).collect(); + assert_eq!(edges.len(), 1, "one {name} dependency edge required from {from:?}"); + let fields: Vec<_> = edges[0].split_whitespace().collect(); + let version = fields.get(1).copied(); + let source = fields.get(2).map(|s| s.trim_start_matches('(').trim_end_matches(')')); + let found: Vec<_> = self + .packages + .iter() + .filter(|p| p.id.name == name && version.is_none_or(|v| p.id.version == v) && source.is_none_or(|s| p.id.source.as_deref() == Some(s))) + .collect(); + assert_eq!(found.len(), 1, "ambiguous or absent resolved edge {} from {from:?}", edges[0]); + found[0].id.clone() + } +} + +pub(crate) fn assert_renderer_edges(graph: &LockGraph, svg: &PackageId) { + let renderer = graph.dependency(svg, "resvg"); + assert_eq!(graph.dependency(svg, "usvg"), graph.dependency(&renderer, "usvg"), "shared and renderer trees must be the same resolved package"); + for codec in ["gif", "image-webp", "zune-jpeg"] { + assert_eq!(graph.dependency(svg, codec), graph.dependency(&renderer, codec), "validator and selected renderer differ for {codec}"); + } +} + +#[test] +fn validated_renderer_dependency_edges_are_the_same_resolved_packages() { + let file = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../Cargo.lock"); + let graph = LockGraph::parse(&std::fs::read_to_string(file).unwrap()); + assert_renderer_edges(&graph, &graph.workspace_package("craft-svg")); +} + +#[test] +fn dependency_lookup_follows_the_selected_edge_and_rejects_ambiguity() { + let graph = LockGraph::parse( + r#" +[[package]] +name = "consumer" +version = "1" +dependencies = ["codec 1 (registry+one)"] +[[package]] +name = "codec" +version = "1" +source = "registry+one" +[[package]] +name = "codec" +version = "1" +source = "registry+two" +[[package]] +name = "other" +version = "1" +dependencies = ["codec"] +"#, + ); + let selected = graph.dependency(&graph.workspace_package("consumer"), "codec"); + assert_eq!(selected.source.as_deref(), Some("registry+one")); + assert!(std::panic::catch_unwind(|| graph.dependency(&graph.workspace_package("other"), "codec")).is_err()); +} + +#[test] +fn selected_renderer_graph_rejects_a_split_validator_backend() { + use std::fmt::Write; + let make = |split: bool| { + let mut text = String::from("[[package]]\nname='craft-svg'\nversion='1'\ndependencies=['resvg', 'usvg', 'gif', 'image-webp', '"); + text.push_str(if split { "zune-jpeg 2" } else { "zune-jpeg 1" }); + text.push_str( + "']\n[[package]]\nname='resvg'\nversion='1'\nsource='registry+one'\ndependencies=['usvg', 'gif', 'image-webp', 'zune-jpeg 1']\n", + ); + for name in ["usvg", "gif", "image-webp", "zune-jpeg"] { + write!(&mut text, "[[package]]\nname='{name}'\nversion='1'\nsource='registry+one'\n").unwrap(); + } + // An unrelated second codec version is valid; only the selected edges count. + text.push_str("[[package]]\nname='zune-jpeg'\nversion='2'\nsource='registry+one'\n"); + LockGraph::parse(&text) + }; + let matching = make(false); + assert_renderer_edges(&matching, &matching.workspace_package("craft-svg")); + let split = make(true); + assert!(std::panic::catch_unwind(|| assert_renderer_edges(&split, &split.workspace_package("craft-svg"))).is_err()); +} diff --git a/crates/svg/src/tree/draw/raster.rs b/crates/svg/src/tree/draw/raster.rs new file mode 100644 index 000000000..fe250259d --- /dev/null +++ b/crates/svg/src/tree/draw/raster.rs @@ -0,0 +1,140 @@ +//! Validate optional raster images with the same backends used by the SVG renderer. +//! +//! Header probing alone cannot detect damaged pixel data. Admit dimensions and +//! reserve work before decoding: even a failed decode keeps its charge. + +use std::io::Cursor; +use std::num::NonZeroU64; + +use crate::tree::{draw::tiny_skia, usvg}; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum RasterValidationFailure { + /// The renderer cannot decode the encoded image. + Invalid, + /// Header dimensions, cumulative work or decoder allocation exceed admission. + Limit, +} + +/// Validate the renderer's first frame within per-image and remaining work limits. +/// Failed attempted decodes keep their pixel charge. No decoded pixels are retained. SVG +/// children use the same wrapped resolver and need no second recursive walk. +pub fn validate_raster(kind: &usvg::ImageKind, max_pixels: u64, pixels_left: &mut u64) -> Result<(), RasterValidationFailure> { + let data = match kind { + usvg::ImageKind::PNG(data) | usvg::ImageKind::JPEG(data) | usvg::ImageKind::GIF(data) | usvg::ImageKind::WEBP(data) => data, + usvg::ImageKind::SVG(_) => return Ok(()), + }; + // The allocation probe includes oversized GIF/WebP frames, not merely their + // canvas. Reserve before asking any rendering decoder to allocate pixels. + let (width, height) = craft_image_codecs::probe_allocation_size(data).map_err(|_| RasterValidationFailure::Invalid)?; + let pixels = area(width, height)?; + if pixels > max_pixels { + return Err(RasterValidationFailure::Limit); + } + *pixels_left = pixels_left.checked_sub(pixels).ok_or(RasterValidationFailure::Limit)?; + match kind { + usvg::ImageKind::PNG(data) => { + let decoded = tiny_skia::Pixmap::decode_png(data).map_err(|_| RasterValidationFailure::Invalid)?; + rgba_bytes(decoded.width(), decoded.height(), pixels)?; + Ok(()) + } + usvg::ImageKind::JPEG(data) => jpeg(data, pixels), + usvg::ImageKind::GIF(data) => gif(data, pixels), + usvg::ImageKind::WEBP(data) => webp(data, pixels), + usvg::ImageKind::SVG(_) => Ok(()), + } +} + +fn area(width: u32, height: u32) -> Result { + if width == 0 || height == 0 { + return Err(RasterValidationFailure::Invalid); + } + u64::from(width).checked_mul(u64::from(height)).ok_or(RasterValidationFailure::Limit) +} + +/// Decoder headers must not request more output than the allocation probe paid for. +fn rgba_bytes(width: u32, height: u32, admitted: u64) -> Result { + let pixels = area(width, height)?; + if pixels > admitted { + return Err(RasterValidationFailure::Limit); + } + usize::try_from(pixels.checked_mul(4).ok_or(RasterValidationFailure::Limit)?).map_err(|_| RasterValidationFailure::Limit) +} + +fn buffer(length: usize) -> Result, RasterValidationFailure> { + let mut output = Vec::new(); + output.try_reserve_exact(length).map_err(|_| RasterValidationFailure::Limit)?; + output.resize(length, 0); + Ok(output) +} + +fn jpeg(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { + use zune_jpeg::zune_core::colorspace::ColorSpace; + use zune_jpeg::zune_core::options::DecoderOptions; + + // Preserve the rendering decoder's default limits and RGBA conversion; a + // general photo decoder may accept formats the SVG renderer cannot draw. + let options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA); + let mut decoder = zune_jpeg::JpegDecoder::new_with_options(Cursor::new(data), options); + decoder.decode_headers().map_err(|_| RasterValidationFailure::Invalid)?; + let info = decoder.info().ok_or(RasterValidationFailure::Invalid)?; + let length = rgba_bytes(u32::from(info.width), u32::from(info.height), admitted)?; + if decoder.output_colorspace() != Some(ColorSpace::RGBA) || decoder.output_buffer_size() != Some(length) { + return Err(RasterValidationFailure::Invalid); + } + let mut output = buffer(length)?; + decoder.decode_into(&mut output).map_err(|_| RasterValidationFailure::Invalid) +} + +fn gif(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { + let bytes = admitted.checked_mul(4).ok_or(RasterValidationFailure::Limit)?; + // Do not loosen the renderer's default 50 MB GIF frame limit. Smaller + // imports also keep their own admitted allocation ceiling during decode. + let limit = NonZeroU64::new(bytes.min(50_000_000)).ok_or(RasterValidationFailure::Invalid)?; + let mut options = gif::DecodeOptions::new(); + options.set_color_output(gif::ColorOutput::RGBA); + options.set_memory_limit(gif::MemoryLimit::Bytes(limit)); + let mut decoder = options.read_info(data).map_err(gif_error)?; + let frame = decoder.read_next_frame().map_err(gif_error)?.ok_or(RasterValidationFailure::Invalid)?; + let expected = rgba_bytes(u32::from(frame.width), u32::from(frame.height), admitted)?; + if frame.buffer.len() != expected { + return Err(RasterValidationFailure::Invalid); + } + Ok(()) +} + +fn gif_error(error: gif::DecodingError) -> RasterValidationFailure { + match error { + gif::DecodingError::MemoryLimit | gif::DecodingError::OutOfMemory => RasterValidationFailure::Limit, + _ => RasterValidationFailure::Invalid, + } +} + +fn webp(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { + let mut decoder = image_webp::WebPDecoder::new(Cursor::new(data)).map_err(webp_error)?; + let (width, height) = decoder.dimensions(); + let rgba = rgba_bytes(width, height, admitted)?; + let channels = if decoder.has_alpha() { 4 } else { 3 }; + let expected = usize::try_from(area(width, height)?.checked_mul(channels).ok_or(RasterValidationFailure::Limit)?) + .map_err(|_| RasterValidationFailure::Limit)?; + if expected > rgba { + return Err(RasterValidationFailure::Limit); + } + if decoder.output_buffer_size() != Some(expected) { + return Err(RasterValidationFailure::Invalid); + } + // A small valid image can have a compressed chunk larger than its pixels. + // Bound decoder scratch without rejecting that ordinary encoding overhead. + let admitted_bytes = + usize::try_from(admitted.checked_mul(4).ok_or(RasterValidationFailure::Limit)?).map_err(|_| RasterValidationFailure::Limit)?; + decoder.set_memory_limit(admitted_bytes.max(data.len())); + let mut output = buffer(expected)?; + decoder.read_image(&mut output).map_err(webp_error) +} + +fn webp_error(error: image_webp::DecodingError) -> RasterValidationFailure { + match error { + image_webp::DecodingError::MemoryLimitExceeded | image_webp::DecodingError::ImageTooLarge => RasterValidationFailure::Limit, + _ => RasterValidationFailure::Invalid, + } +} diff --git a/crates/svg/src/tree/image_href.rs b/crates/svg/src/tree/image_href.rs new file mode 100644 index 000000000..d33388846 --- /dev/null +++ b/crates/svg/src/tree/image_href.rs @@ -0,0 +1,428 @@ +//! Bounded data-URL normalization over the shared checked XML document. +//! Only attribute values change; actual usvg callbacks decide image usage. +use super::Error; +#[cfg(test)] +use super::Limits; +use std::borrow::Cow; +use std::ops::Range; + +#[cfg(test)] +const SVG_NS: &str = "http://www.w3.org/2000/svg"; +const XLINK_NS: &str = "http://www.w3.org/1999/xlink"; +const INVALID_IMAGE: &str = "data:image/png,%00"; +const IGNORED_DATA: &str = "data:application/octet-stream,%00"; + +struct Patch { + range: Range, + replacement: Cow<'static, str>, +} + +fn invalid(message: &str) -> Error { + Error::Parse(message.into()) +} + +#[cfg(test)] +fn repair<'a>(text: &'a str, limits: &Limits) -> Result, Error> { + normalize(&super::preflight(text, limits)?) +} + +pub(super) fn normalize<'a>(checked: &super::Preflight<'a>) -> Result, Error> { + let text = checked.xml.input_text(); + let limits = &checked.limits; + let xml = &checked.xml; + if !text.contains("href") { + return Ok(Cow::Borrowed(text)); + } + // Expanded values fit source + entity work. Twelve linear passes cover URL + // scans/streaming decode, full attribute projection and worst-case XML escaping; + // parameter compaction never allocates one record per original parameter. + let mut work = text + .len() + .checked_add(limits.entity_bytes) + .and_then(|n| n.checked_mul(12)) + .ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + let max_patches = (limits.bytes / std::mem::size_of::()).min(usize::try_from(limits.xml_nodes).unwrap_or(usize::MAX)); + let mut patches: Vec = Vec::new(); + for node in xml.descendants().filter(|node| node.is_element()) { + if !matches!(node.tag_name().name(), "image" | "feImage") { + continue; + } + // Shared preflight inspects local image names in every namespace and + // checks XLink before plain href. Normalize both representations, even + // when one is inert or unselected. Only actual resolver callbacks count + // omissions, so this does not turn hidden/unused resources into warnings. + for href in node.attributes().filter(|a| a.name() == "href" && matches!(a.namespace(), None | Some(XLINK_NS))) { + let Some(replacement) = data_url_replacement(href.value(), &mut work)? else { continue }; + let range = verified_value_range(text, node.range(), href.range(), href.name(), &mut work)?; + if patches.len() == patches.capacity() { + if patches.len() >= max_patches { + return Err(invalid("SVG data-URL repair metadata exceeds its limit")); + } + let capacity = patches.capacity().max(8).saturating_mul(2).min(max_patches); + patches + .try_reserve_exact(capacity.saturating_sub(patches.len())) + .map_err(|_| invalid("could not allocate bounded SVG data-URL repairs"))?; + } + patches.push(Patch { range, replacement }); + } + } + if patches.is_empty() { + return Ok(Cow::Borrowed(text)); + } + patches.sort_unstable_by_key(|patch| (patch.range.start, patch.range.end)); + patches.dedup_by_key(|patch| (patch.range.start, patch.range.end)); + let mut end = 0; + let mut length = text.len(); + for patch in &patches { + let range = &patch.range; + if range.start < end { + return Err(invalid("SVG data-URL source ranges overlap")); + } + end = range.end; + length = length + .checked_sub(range.len()) + .and_then(|n| n.checked_add(patch.replacement.len())) + .ok_or_else(|| invalid("SVG data-URL repair size overflows"))?; + } + if length > limits.bytes { + return Err(invalid("repaired SVG exceeds the text byte limit")); + } + let mut result = String::new(); + result.try_reserve_exact(length).map_err(|_| invalid("could not allocate bounded repaired SVG text"))?; + let mut cursor = 0; + for patch in patches { + result.push_str(text.get(cursor..patch.range.start).ok_or_else(|| invalid("invalid SVG data-URL source range"))?); + result.push_str(&patch.replacement); + cursor = patch.range.end; + } + result.push_str(text.get(cursor..).ok_or_else(|| invalid("invalid SVG data-URL source range"))?); + Ok(Cow::Owned(result)) +} + +// The pinned MIME parser searches all earlier parameters for each new name. +// Cap even quoted semicolons before invoking it: source-byte work is already +// charged, so at most this constant times the bounded XML work reaches MIME +// parsing. Bodies can remain large without acquiring MIME parameter records. +const MAX_MIME_SEPARATORS: usize = 64; + +fn mime_header_admitted(value: &str) -> bool { + let trimmed = value.trim_start_matches(|ch| ch <= ' '); + let mut bytes = trimmed.bytes(); + for expected in b"data:" { + let Some(actual) = bytes.by_ref().find(|&byte| !matches!(byte, b'\t' | b'\n' | b'\r')) else { return true }; + if !actual.eq_ignore_ascii_case(expected) { + return true; // Not a data URL: preserve external/fragment handling. + } + } + let mut separators = 0; + for byte in bytes { + if matches!(byte, b',' | b'#') { + break; + } + if byte == b';' { + separators += 1; + if separators > MAX_MIME_SEPARATORS { + return false; + } + } + } + true +} + +/// A long parameter list must not reach the quadratic MIME parser, but its +/// essence, final base64 marker and body still determine the original image. +/// Compact only that header, then use the same parser/streaming decoder. Escape +/// the decoded attribute value once when projecting it back into XML. +fn data_url_replacement(value: &str, work: &mut usize) -> Result>, Error> { + if mime_header_admitted(value) { + return malformed_data_url_replacement(value, work).map(|replacement| replacement.map(Cow::Borrowed)); + } + *work = work.checked_sub(value.len()).ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + let normalized = value.trim_matches(|ch| ch <= ' '); + let delimiter = normalized.find([',', '#']); + let Some(comma) = delimiter.filter(|&at| normalized.as_bytes().get(at) == Some(&b',')) else { + return missing_comma_replacement(value, work).map(|replacement| Some(Cow::Borrowed(replacement))); + }; + let header = normalized.get(..comma).ok_or_else(|| invalid("invalid SVG data-URL header framing"))?; + let essence = header.split_once(';').map_or(header, |(essence, _)| essence); + // Retaining the final parameter lets the pinned parser decide whether its + // suffix is a base64 marker, including its case/ASCII-whitespace rules. + let suffix = header.rfind(';').and_then(|at| header.get(at..)).unwrap_or(""); + let body = normalized.get(comma..).ok_or_else(|| invalid("invalid SVG data-URL body framing"))?; + let length = essence + .len() + .checked_add(suffix.len()) + .and_then(|n| n.checked_add(body.len())) + .ok_or_else(|| invalid("SVG data-URL repair size overflows"))?; + let mut compact = String::new(); + compact.try_reserve_exact(length).map_err(|_| invalid("could not allocate bounded SVG data-URL header"))?; + compact.push_str(essence); + compact.push_str(suffix); + compact.push_str(body); + if let Some(replacement) = malformed_data_url_replacement(&compact, work)? { + return Ok(Some(Cow::Borrowed(replacement))); + } + let escaped_len = compact + .chars() + .try_fold(0usize, |n, ch| { + n.checked_add(match ch { + '&' | '\t' | '\n' | '\r' => 5, + '\'' | '"' => 6, + '<' | '>' => 4, + _ => ch.len_utf8(), + }) + }) + .ok_or_else(|| invalid("SVG data-URL repair size overflows"))?; + *work = work.checked_sub(escaped_len).ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + let mut escaped = String::new(); + escaped.try_reserve_exact(escaped_len).map_err(|_| invalid("could not allocate bounded SVG data-URL repair"))?; + for ch in compact.chars() { + match ch { + '&' => escaped.push_str("&"), + '\'' => escaped.push_str("'"), + '"' => escaped.push_str("""), + '<' => escaped.push_str("<"), + '>' => escaped.push_str(">"), + '\t' => escaped.push_str(" "), + '\n' => escaped.push_str(" "), + '\r' => escaped.push_str(" "), + _ => escaped.push(ch), + } + } + Ok(Some(Cow::Owned(escaped))) +} + +fn malformed_data_url_replacement(value: &str, work: &mut usize) -> Result, Error> { + malformed_data_url_replacement_with(value, work, data_url::DataUrl::process) +} + +fn malformed_data_url_replacement_with<'a>( + value: &'a str, + work: &mut usize, + parse: impl FnOnce(&'a str) -> Result, data_url::DataUrlError>, +) -> Result, Error> { + *work = work.checked_sub(value.len()).ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + if !mime_header_admitted(value) { + // Strip parameters before recovering MIME disposition; no original + // parameter list reaches either our parser or shared whole-DOM preflight. + return missing_comma_replacement(value, work).map(Some); + } + let url = match parse(value) { + Ok(url) => url, + Err(data_url::DataUrlError::NoComma) => return missing_comma_replacement(value, work).map(Some), + Err(data_url::DataUrlError::NotADataUrl) => return Ok(None), + }; + let mut exhausted = false; + let decoded = url.decode(|bytes| { + if let Some(left) = work.checked_sub(bytes.len()) { + *work = left; + Ok(()) + } else { + exhausted = true; + Err(()) + } + }); + if exhausted { + return Err(invalid("SVG data-URL validation work exceeds its limit")); + } + Ok(decoded.is_err().then(|| replacement_for_mime(url.mime_type()))) +} + +/// Preflight must see a valid URL, while the resolver must keep its original +/// disposition. Non-image MIME types are ignored even when their body is bad. +fn replacement_for_mime(mime: &data_url::mime::Mime) -> &'static str { + if mime.type_ == "image" || mime.matches("text", "plain") { INVALID_IMAGE } else { IGNORED_DATA } +} + +fn missing_comma_replacement(value: &str, work: &mut usize) -> Result<&'static str, Error> { + // NoComma does not expose its MIME type. Ask the same parser about a header + // with an empty body rather than guessing MIME defaults, case or parameters. + // Match its URL C0 trimming; fragments and MIME parameters cannot affect + // the image/text-plain essence. Do not allocate parameter bookkeeping for a + // hostile missing-comma header just to recover that disposition. + let normalized = value.trim_matches(|ch| ch <= ' '); + let header = normalized.split_once('#').map_or(normalized, |(header, _)| header); + let essence = header.split_once(';').map_or(header, |(essence, _)| essence); + *work = work.checked_sub(essence.len()).ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + let length = essence.len().checked_add(1).ok_or_else(|| invalid("SVG data-URL repair size overflows"))?; + let mut candidate = String::new(); + candidate.try_reserve_exact(length).map_err(|_| invalid("could not allocate bounded SVG data-URL header"))?; + candidate.push_str(essence); + candidate.push(','); + // This candidate has no MIME parameters, including for oversized original + // lists. Its byte scan/allocation is charged above before the linear parse. + if !mime_header_admitted(&candidate) { + return Err(invalid("SVG data-URL MIME header exceeds its limit")); + } + let url = data_url::DataUrl::process(&candidate).map_err(|_| invalid("invalid SVG data-URL header framing"))?; + Ok(replacement_for_mime(url.mime_type())) +} + +/// Use the complete source range rather than roxmltree's compact QName/equals +/// offsets (u16/u8). Scan only this validated attribute, never a DTD declaration +/// or another node. Charge the extra source scan before examining it. +fn verified_value_range(text: &str, owner: Range, attribute: Range, local_name: &str, work: &mut usize) -> Result, Error> { + let error = || invalid("SVG data-URL attribute source positions cannot be represented safely"); + if attribute.start < owner.start || attribute.end > owner.end { + return Err(error()); + } + *work = work.checked_sub(attribute.len()).ok_or_else(|| invalid("SVG data-URL validation work exceeds its limit"))?; + let source = text.get(attribute.clone()).ok_or_else(error)?; + let name_end = source.find([' ', '\t', '\r', '\n', '=']).ok_or_else(error)?; + let name = source.get(..name_end).ok_or_else(error)?; + if name.rsplit(':').next() != Some(local_name) { + return Err(error()); + } + let after_name = source.get(name_end..).ok_or_else(error)?.trim_start_matches([' ', '\t', '\r', '\n']); + let after_equals = after_name.strip_prefix('=').ok_or_else(error)?.trim_start_matches([' ', '\t', '\r', '\n']); + let quote = after_equals.chars().next().ok_or_else(error)?; + if !matches!(quote, '\'' | '"') || !after_equals.ends_with(quote) || after_equals.len() < 2 { + return Err(error()); + } + let start = attribute.end.checked_sub(after_equals.len()).and_then(|n| n.checked_add(1)).ok_or_else(error)?; + let end = attribute.end.checked_sub(1).ok_or_else(error)?; + if text.get(start..end).is_none_or(|value| value.contains(quote)) { + return Err(error()); + } + Ok(start..end) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn limits() -> Limits { + Limits { bytes: 1 << 20, depth: 32, tree_depth: 32, entity_bytes: 65_536, ..Default::default() } + } + + #[test] + fn malformed_image_urls_are_repaired_in_both_svg_namespaces_and_filter_resources() { + for tag in ["image", "feImage"] { + for text in [ + format!("<{tag} href='data:image/png;base64,A'/>"), + format!("<{tag} href='data:image/png;base64,A'/>"), + format!(""), + ] { + let repaired = repair(&text, &limits()).unwrap(); + assert!(matches!(repaired, Cow::Owned(_))); + assert_eq!(repaired.matches(INVALID_IMAGE).count(), 1); + } + } + } + + #[test] + fn unselected_href_and_foreign_local_image_names_are_normalized_for_shared_preflight() { + for attrs in ["href='data:image/png,%00' x:href='data:image/png;base64,A'", "x:href='data:image/png;base64,A' href='data:image/png,%00'"] { + let text = format!(""); + let repaired = repair(&text, &limits()).unwrap(); + assert!(matches!(repaired, Cow::Owned(_))); + assert_eq!(repaired.matches(INVALID_IMAGE).count(), 2); + assert!(!repaired.contains("base64,A")); + } + let text = format!( + "" + ); + let repaired = repair(&text, &limits()).unwrap(); + assert_eq!(repaired.matches(INVALID_IMAGE).count(), 3); + assert!(repaired.contains("f:href='data:image/png;base64,A'"), "foreign href attributes remain inert and unchanged"); + } + + #[test] + fn both_href_forms_on_hidden_unused_and_foreign_resources_do_not_preflight_as_omissions() { + for tag in ["image", "feImage"] { + let text = format!( + "<{tag} id='unused' href='data:image/png;base64,A' x:href='data:image/png;base64,A'/><{tag} display='none' x:href='data:image/png;base64,A' href='data:image/png;base64,A'/>" + ); + let original = text.clone(); + let repaired = repair(&text, &limits()).unwrap(); + assert_eq!(text, original, "repair never mutates the original source"); + assert_eq!(repaired.matches(INVALID_IMAGE).count(), 6); + let resolver = crate::tree::ImageResolver::new(limits()); + resolver.check_document(&repaired).unwrap(); + let usage = resolver.usage(); + assert_eq!( + (usage.invalid_raster_images, usage.invalid_svg_images), + (0, 0), + "shared whole-document scanning cannot invent omissions before resolution" + ); + assert!(matches!(repair(&repaired, &limits()).unwrap(), Cow::Borrowed(_)), "normalization is idempotent"); + } + } + + #[test] + fn entity_expanded_urls_patch_the_owning_attributes_without_rewriting_the_doctype() { + let text = format!( + "]>" + ); + let repaired = repair(&text, &limits()).unwrap(); + assert!(repaired.contains("")); + assert_eq!(repaired.matches(INVALID_IMAGE).count(), 2); + assert!(!repaired.contains("href='&bad;'")); + assert!(matches!(repair(&repaired, &limits()).unwrap(), Cow::Borrowed(_))); + } + + #[test] + fn valid_data_and_external_urls_are_not_rewritten() { + for value in ["data:image/png;base64,AA==", "data:image/svg+xml,%3Csvg%2F%3E", "file.png", "#local"] { + let text = format!(""); + assert!(matches!(repair(&text, &limits()).unwrap(), Cow::Borrowed(_))); + } + let text = ""; + assert!(repair(text, &limits()).unwrap().contains(INVALID_IMAGE)); + } + + #[test] + fn malformed_non_image_urls_keep_ignored_replacements_even_without_a_comma() { + for value in [ + "data:application/octet-stream;base64,A", + "data:application/octet-stream;base64", + "data:APPLICATION/OCTET-STREAM;BASE64,A", + "data:text/css;base64,A", + "data:audio/ogg;base64,A", + "data:application/octet-stream;base64#fragment,not-the-delimiter", + ] { + let text = format!(""); + let repaired = repair(&text, &limits()).unwrap(); + assert!(repaired.contains(IGNORED_DATA), "{value}: {repaired}"); + assert!(!repaired.contains(INVALID_IMAGE)); + assert!(matches!(repair(&repaired, &limits()).unwrap(), Cow::Borrowed(_))); + let resolver = crate::tree::ImageResolver::new(limits()); + resolver.check_document(&repaired).unwrap(); + assert_eq!(resolver.usage().invalid_raster_images, 0); + } + } + + #[test] + fn image_and_default_plain_mime_failures_remain_disclosed() { + for value in [ + "data:IMAGE/PNG;base64,A", + "data:image/png;base64", + "data:text/plain;base64,A", + "data:;base64,A", + "data:;base64", + "data:not-a-mime;base64", + ] { + let text = format!(""); + assert!(repair(&text, &limits()).unwrap().contains(INVALID_IMAGE), "{value}"); + } + let value = "data:application/octet-stream;base64#fragment"; + let mut insufficient = value.len(); + assert!(malformed_data_url_replacement(value, &mut insufficient).is_err(), "the extra MIME-header parse has its own work charge"); + let mut sufficient = value.len() * 2; + assert_eq!(malformed_data_url_replacement(value, &mut sufficient).unwrap(), Some(IGNORED_DATA)); + } + + #[test] + fn long_equals_spacing_is_repaired_and_output_growth_stays_bounded() { + let text = format!("", " ".repeat(300)); + let repaired = repair(&text, &limits()).unwrap(); + assert!(repaired.contains(INVALID_IMAGE)); + assert!(repaired.contains(&format!("href{}=", " ".repeat(300)))); + let text = ""; + assert!(matches!(repair(text, &Limits { bytes: text.len(), ..limits() }), Err(Error::Parse(message)) if message.contains("byte limit"))); + } +} + +#[cfg(test)] +#[path = "mime_header_tests.rs"] +mod mime_header_tests; diff --git a/crates/svg/src/tree/mime_header_tests.rs b/crates/svg/src/tree/mime_header_tests.rs new file mode 100644 index 000000000..393a01729 --- /dev/null +++ b/crates/svg/src/tree/mime_header_tests.rs @@ -0,0 +1,158 @@ +use super::*; +use std::fmt::Write; + +fn parameters(count: usize) -> String { + let mut text = String::new(); + for index in 0..count { + write!(&mut text, ";p{index}=x").unwrap(); + } + text +} + +#[test] +fn a_hundred_thousand_unique_mime_parameters_are_refused_before_the_original_parser() { + let params = parameters(100_000); + for (essence, expected) in [ + ("image/png", INVALID_IMAGE), + ("text/plain", INVALID_IMAGE), + ("", INVALID_IMAGE), + ("not-a-mime", INVALID_IMAGE), + ("application/octet-stream", IGNORED_DATA), + ("audio/ogg", IGNORED_DATA), + ] { + for delimiter in [",AA==", "#fragment,AA==", ""] { + let value = format!("data:{essence}{params};base64{delimiter}"); + let mut work = value.len() * 2; + assert!(!mime_header_admitted(&value)); + let result = + malformed_data_url_replacement_with(&value, &mut work, |_| panic!("the original parameter flood must not reach DataUrl::process")) + .unwrap(); + assert_eq!(result, Some(expected), "{essence} {delimiter}"); + } + } +} + +#[test] +fn mime_parameter_admission_preserves_the_boundary_and_ignores_body_semicolons() { + let accepted = format!("data:image/png{};base64,AA==", parameters(MAX_MIME_SEPARATORS - 1)); + assert!(mime_header_admitted(&accepted)); + let called = std::cell::Cell::new(false); + let mut work = accepted.len() * 2; + assert_eq!( + malformed_data_url_replacement_with(&accepted, &mut work, |value| { + called.set(true); + data_url::DataUrl::process(value) + }) + .unwrap(), + None + ); + assert!(called.get(), "an admitted original URL still reaches the real parser"); + let refused = format!("data:image/png{};base64,AA==", parameters(MAX_MIME_SEPARATORS)); + assert!(!mime_header_admitted(&refused)); + let mut work = refused.len() * 2; + assert_eq!(malformed_data_url_replacement(&refused, &mut work).unwrap(), Some(INVALID_IMAGE)); + + for value in [format!("data:text/plain,{}", ";".repeat(100_000)), format!("external.png?{}", parameters(100_000))] { + assert!(mime_header_admitted(&value), "payloads/external URLs are not MIME parameters"); + let mut work = value.len() * 2; + assert_eq!(malformed_data_url_replacement(&value, &mut work).unwrap(), None); + } + let value = format!(" \td\ta\nt\ra:image/png{};base64,A", parameters(MAX_MIME_SEPARATORS)); + assert!(!mime_header_admitted(&value), "scheme normalization matches the pinned parser"); + let mut work = value.len() * 2; + assert_eq!(malformed_data_url_replacement(&value, &mut work).unwrap(), Some(INVALID_IMAGE)); +} + +#[test] +fn compacted_parameter_lists_preserve_both_hrefs_and_foreign_resources_without_preflight_warnings() { + let value = format!("data:image/png{};base64,AA==", parameters(MAX_MIME_SEPARATORS)); + let text = format!( + "" + ); + let limits = Limits { bytes: 1 << 20, ..Default::default() }; + let repaired = repair(&text, &limits).unwrap(); + assert_eq!(repaired.matches("data:image/png;base64,AA==").count(), 6); + assert!(!repaired.contains(";p0=")); + let resolver = crate::tree::ImageResolver::new(limits); + resolver.check_document(&repaired).unwrap(); + let usage = resolver.usage(); + assert_eq!((usage.invalid_raster_images, usage.invalid_svg_images), (0, 0)); + assert!(matches!(repair(&repaired, &Limits { bytes: 1 << 20, ..Default::default() }).unwrap(), Cow::Borrowed(_))); +} + +#[test] +fn duplicate_and_quoted_parameters_share_the_same_conservative_boundary() { + for (accepted, refused) in [ + ( + format!("data:image/png{},%00", ";p=x".repeat(MAX_MIME_SEPARATORS)), + format!("data:image/png{},%00", ";p=x".repeat(MAX_MIME_SEPARATORS + 1)), + ), + ( + format!("data:image/png;p=\"{}\",%00", ";".repeat(MAX_MIME_SEPARATORS - 1)), + format!("data:image/png;p=\"{}\",%00", ";".repeat(MAX_MIME_SEPARATORS)), + ), + ] { + assert!(mime_header_admitted(&accepted)); + let mut work = accepted.len() * 2; + assert_eq!(malformed_data_url_replacement(&accepted, &mut work).unwrap(), None); + assert!(!mime_header_admitted(&refused)); + let mut work = refused.len() * 2; + assert_eq!(malformed_data_url_replacement(&refused, &mut work).unwrap(), Some(INVALID_IMAGE)); + } + for value in ["external.png", "#local", "datx:image/png;param=x,body"] { + let mut work = value.len() * 2; + assert_eq!(malformed_data_url_replacement(value, &mut work).unwrap(), None); + } + let value = "data:image/png;base64"; + let mut work = value.len() * 2; + assert_eq!(malformed_data_url_replacement(value, &mut work).unwrap(), Some(INVALID_IMAGE)); +} + +#[test] +fn parameter_flood_scans_and_essence_classification_spend_one_shared_work_ledger() { + let value = format!("data:application/octet-stream{};base64,AA==", parameters(MAX_MIME_SEPARATORS)); + let essence_len = "data:application/octet-stream".len(); + let charge = value.len() + essence_len; + let mut work = charge * 2; + for remaining in [charge, 0] { + assert_eq!(malformed_data_url_replacement_with(&value, &mut work, |_| panic!("not admitted")).unwrap(), Some(IGNORED_DATA)); + assert_eq!(work, remaining, "the original header scan and parameter-free fallback each retain their charge"); + } + assert!(malformed_data_url_replacement_with(&value, &mut work, |_| panic!("no work remains")).is_err()); + assert_eq!(work, 0); + let mut not_enough_for_essence = value.len(); + assert!(malformed_data_url_replacement_with(&value, &mut not_enough_for_essence, |_| panic!("not admitted")).is_err()); + assert_eq!(not_enough_for_essence, 0); +} + +#[test] +fn many_parameter_urls_preserve_bodies_and_base64_disposition() { + let params = parameters(100_000); + for (suffix, body, expected) in [ + (";base64", "AA==", vec![0]), + ("; BASE64 ", "AA==", vec![0]), + (";p=last", "%00%26%27%22", vec![0, b'&', b'\'', b'"']), + (";p=last", "&'" z", b"&\'\"z".to_vec()), + ] { + let text = format!(""); + let repaired = repair(&text, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(); + let xml = checked_xml(&repaired, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(); + let value = xml.descendants().find(|node| node.has_tag_name("image")).unwrap().attribute("href").unwrap(); + assert!(!value.contains(";p0=")); + assert_eq!(data_url::DataUrl::process(value).unwrap().decode_to_vec().unwrap().0, expected); + assert!(matches!(repair(&repaired, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(), Cow::Borrowed(_))); + } + let malformed = format!(""); + assert!(repair(&malformed, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap().contains(INVALID_IMAGE)); +} + +#[test] +fn header_compaction_has_a_shared_nonrefundable_work_charge() { + let value = format!("data:image/png{};base64,AA==", parameters(100)); + let mut work = value.len(); + assert!(data_url_replacement(&value, &mut work).is_err()); + assert_eq!(work, 0, "the original parameter scan stays spent on refusal"); + let mut work = value.len() * 12; + assert!(data_url_replacement(&value, &mut work).unwrap().is_some()); + assert!(work < value.len() * 12 - value.len(), "compact parse, streaming decode and XML projection are charged too"); +} diff --git a/crates/svg/src/tree/validated.rs b/crates/svg/src/tree/validated.rs new file mode 100644 index 000000000..cb1b6e8c3 --- /dev/null +++ b/crates/svg/src/tree/validated.rs @@ -0,0 +1,393 @@ +//! Opt-in complete image validation and checked-DOM normalization. +//! Legacy ImageResolver entry points retain their existing behavior. +use super::{Error, ImageUsage, Limits, Preflight, image_href, preflight, raster_format, usvg}; +use crate::svgz; +use std::sync::{Arc, Mutex, PoisonError}; + +struct State { + document_bytes: usize, + pixel_limit: u64, + pixels_left: u64, + svg_byte_limit: usize, + svg_bytes_left: usize, + svg_failure_exhausted: bool, + classification_bytes_left: usize, + classification_content_left: usize, + classification_text_bytes_left: usize, + encoded_left: usize, + invalid_raster: usize, + invalid_svg: usize, + raster_limits: usize, + svg_limits: usize, + svg_resource_limits: usize, + root_active: bool, + xml_depth: usize, + depth: usize, + svg_count: usize, + svg_depth: usize, +} + +impl State { + fn new(limits: Limits) -> Self { + Self { + document_bytes: limits.bytes, + pixel_limit: limits.embedded_raster_pixels, + pixels_left: limits.embedded_raster_pixels, + svg_byte_limit: limits.embedded_bytes, + svg_bytes_left: limits.embedded_bytes, + svg_failure_exhausted: false, + classification_bytes_left: limits.embedded_bytes, + classification_content_left: limits.embedded_bytes, + classification_text_bytes_left: limits.embedded_bytes, + encoded_left: limits.bytes.saturating_add(limits.embedded_bytes), + invalid_raster: 0, + invalid_svg: 0, + raster_limits: 0, + svg_limits: 0, + svg_resource_limits: 0, + root_active: false, + xml_depth: 0, + depth: 0, + svg_count: 0, + svg_depth: 0, + } + } + + fn usage(&self) -> ImageUsage { + ImageUsage { + raster_pixels: self.pixel_limit.saturating_sub(self.pixels_left), + embedded_svg_bytes: self.svg_byte_limit.saturating_sub(self.svg_bytes_left), + embedded_svg_count: self.svg_count, + embedded_svg_depth: self.svg_depth, + invalid_raster_images: self.invalid_raster, + raster_limit_images: self.raster_limits, + invalid_svg_images: self.invalid_svg, + svg_limit_images: self.svg_limits, + svg_resource_limit_images: self.svg_resource_limits, + } + } + + fn classify_after_svg_failure(&mut self, data: &[u8]) { + if self.svg_resource_limits != 0 { + self.svg_limits = self.svg_limits.saturating_add(1); + self.svg_resource_limits = self.svg_resource_limits.saturating_add(1); + return; + } + let compressed = data.starts_with(&[0x1f, 0x8b]); + let content_left = self.classification_content_left; + let limit = if compressed { content_left.min(self.classification_bytes_left) } else { content_left }.min(self.document_bytes); + if compressed && limit == 0 { + self.svg_limits = self.svg_limits.saturating_add(1); + self.svg_resource_limits = self.svg_resource_limits.saturating_add(1); + return; + } + let resource_refusal = match crate::svgz::inflate(data, limit) { + Ok(bytes) => { + if compressed { + self.classification_bytes_left = self.classification_bytes_left.saturating_sub(bytes.len()); + } + let Some(text_left) = self.classification_text_bytes_left.checked_sub(bytes.len()) else { + self.svg_limits = self.svg_limits.saturating_add(1); + self.svg_resource_limits = self.svg_resource_limits.saturating_add(1); + return; + }; + self.classification_text_bytes_left = text_left; + match crate::svgz::decode(&bytes) { + Ok(text) => text.len() > content_left || text.len() > self.document_bytes, + Err(_) => { + self.invalid_svg = self.invalid_svg.saturating_add(1); + return; + } + } + } + Err(crate::svgz::Error::TooLarge(_)) => { + if compressed { + self.classification_bytes_left = self.classification_bytes_left.saturating_sub(limit); + } + true + } + Err(error) => { + // Nested data was fully inflated before refusal. Other failures + // may have consumed the entire attempted inflation allowance. + if compressed { + let charged = match error { + crate::svgz::Error::Nested(bytes) => bytes, + _ => limit, + }; + self.classification_bytes_left = self.classification_bytes_left.saturating_sub(charged); + } + self.invalid_svg = self.invalid_svg.saturating_add(1); + return; + } + }; + self.svg_limits = self.svg_limits.saturating_add(1); + if resource_refusal { + self.svg_resource_limits = self.svg_resource_limits.saturating_add(1); + } + } + + fn raster(&mut self, kind: &usvg::ImageKind) -> bool { + let encoded = match kind { + usvg::ImageKind::SVG(_) => return true, + usvg::ImageKind::PNG(data) | usvg::ImageKind::JPEG(data) | usvg::ImageKind::GIF(data) | usvg::ImageKind::WEBP(data) => data, + }; + // usvg supplies a fresh Arc for every data-URL resolution, including + // repeated instances. Charge each actual validation, never retain + // encoded buffers in an address-keyed memo that cannot hit this boundary. + let Some(left) = self.encoded_left.checked_sub(encoded.len()) else { + self.raster_limits = self.raster_limits.saturating_add(1); + return false; + }; + self.encoded_left = left; + let result = super::draw::validate_raster(kind, self.pixel_limit, &mut self.pixels_left); + match result { + Ok(()) => true, + Err(super::draw::RasterValidationFailure::Invalid) => { + self.invalid_raster = self.invalid_raster.saturating_add(1); + false + } + Err(super::draw::RasterValidationFailure::Limit) => { + self.raster_limits = self.raster_limits.saturating_add(1); + false + } + } + } +} + +/// One opt-in drawing's image work, normalization and exact rendering validation. +/// +/// Unlike legacy ImageResolver, every attempted raster callback spends encoded +/// and decoded work, even on failure. Rendering still decodes pixels afterwards: +/// resvg does not expose a decoded-pixel injection or decode-result hook. +/// All root and child conversions install this same resolver themselves. +#[derive(Clone)] +pub struct ValidatedImageResolver { + limits: Limits, + state: Arc>, +} + +impl ValidatedImageResolver { + /// Create a separate budget for one drawing. Encoded raster work is bounded + /// by root text bytes plus aggregate child SVG bytes, without retaining data. + pub fn new(limits: Limits) -> Self { + Self { limits, state: Arc::new(Mutex::new(State::new(limits))) } + } + + /// The immutable admission policy captured by this instance. Remaining work + /// never changes these limits; use them for the matching opaque preflight. + pub fn limits(&self) -> Limits { + self.limits + } + + /// Snapshot admitted work and optional-image omissions. + pub fn usage(&self) -> ImageUsage { + self.state.lock().unwrap_or_else(PoisonError::into_inner).usage() + } + + /// Convert exactly the DOM checked under these limits, with this instance's + /// resolver. A caller-supplied image callback cannot bypass image admission. + /// The caller still supplies the stack/worker and font policy. + pub fn parse_preflight(&self, checked: Preflight<'_>, mut options: usvg::Options<'_>) -> Result { + if checked.limits != self.limits { + return Err(Error::Parse("checked SVG limits differ from the validated image resolver".into())); + } + // A shallow source can expand through use/paint references. Reserve the + // full checked converted height before any child callback, not source depth. + let _scope = self.root_scope(checked.height)?; + options.image_href_resolver = self.resolver(); + convert_checked(checked, &options) + } + + /// Resolve an already-decoded child SVG, charging original text before XML + /// parsing or repair. This is not an unchecked/precharged admission hook. + /// As with parse_preflight, unrelated image callbacks are replaced. + pub fn resolve_text(&self, text: &str, mut options: usvg::Options<'_>) -> Result, Error> { + let _scope = self.root_scope(0)?; + options.image_href_resolver = self.resolver(); + Ok(self.embedded_text(text, &options)) + } + + fn root_scope(&self, depth: usize) -> Result { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + if state.root_active { + return Err(Error::Parse("the validated SVG resolver is already converting a drawing".into())); + } + let previous = state.xml_depth; + state.root_active = true; + state.xml_depth = depth; + Ok(Scope { state: Arc::clone(&self.state), previous, child: false }) + } + + fn resolver(&self) -> usvg::ImageHrefResolver<'static> { + let this = self.clone(); + usvg::ImageHrefResolver { + resolve_string: Box::new(|_, _| None), + resolve_data: Box::new(move |mime, data, options| { + let detected = raster_format(&data); + let format = match mime { + "image/jpg" | "image/jpeg" => (detected == Some(craft_image_codecs::Format::Jpeg)).then_some(craft_image_codecs::Format::Jpeg), + "image/png" => (detected == Some(craft_image_codecs::Format::Png)).then_some(craft_image_codecs::Format::Png), + "image/gif" => (detected == Some(craft_image_codecs::Format::Gif)).then_some(craft_image_codecs::Format::Gif), + "image/webp" => (detected == Some(craft_image_codecs::Format::WebP)).then_some(craft_image_codecs::Format::WebP), + "text/plain" => detected, + _ => None, + }; + if let Some(format) = format { + let kind = match format { + craft_image_codecs::Format::Png => usvg::ImageKind::PNG(data), + craft_image_codecs::Format::Jpeg => usvg::ImageKind::JPEG(data), + craft_image_codecs::Format::Gif => usvg::ImageKind::GIF(data), + craft_image_codecs::Format::WebP => usvg::ImageKind::WEBP(data), + _ => return None, + }; + return this.state.lock().unwrap_or_else(PoisonError::into_inner).raster(&kind).then_some(kind); + } + if !matches!(mime, "image/svg+xml" | "text/plain") { + if mime.starts_with("image/") { + let mut state = this.state.lock().unwrap_or_else(PoisonError::into_inner); + state.invalid_raster = state.invalid_raster.saturating_add(1); + } + return None; + } + this.embedded_bytes(&data, options) + }), + } + } + + fn can_start_child(&self) -> bool { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + if state.depth >= self.limits.embedded_depth { + state.svg_limits = state.svg_limits.saturating_add(1); + state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); + return false; + } + true + } + + fn embedded_bytes(&self, data: &[u8], options: &usvg::Options<'_>) -> Option { + if !self.can_start_child() { + return None; + } + let room = { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + if state.svg_failure_exhausted { + state.classify_after_svg_failure(data); + return None; + } + state.svg_bytes_left + }; + let text = match svgz::text(data, room.min(self.limits.bytes)) { + Ok(text) if text.len() <= room => text, + error => { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + state.svg_bytes_left = 0; + if matches!(error, Err(svgz::Error::TooLarge(_))) || error.is_ok() { + state.svg_limits = state.svg_limits.saturating_add(1); + state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); + } else { + state.invalid_svg = state.invalid_svg.saturating_add(1); + state.svg_failure_exhausted = true; + state.classification_content_left = room; + } + return None; + } + }; + self.precharge_and_parse(&text, options) + } + + fn embedded_text(&self, text: &str, options: &usvg::Options<'_>) -> Option { + if !self.can_start_child() { + return None; + } + self.precharge_and_parse(text, options) + } + + fn precharge_and_parse(&self, text: &str, options: &usvg::Options<'_>) -> Option { + { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + let Some(left) = state.svg_bytes_left.checked_sub(text.len()) else { + state.svg_bytes_left = 0; + state.svg_limits = state.svg_limits.saturating_add(1); + state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); + return None; + }; + // Original UTF-8 bytes/work are never refunded when repair shortens + // an attribute or conversion subsequently fails. + state.svg_bytes_left = left; + } + let checked = match preflight(text, &self.limits) { + Ok(checked) => checked, + Err(error) => { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + match error { + Error::TooDeep(_) => state.svg_limits = state.svg_limits.saturating_add(1), + Error::Text(svgz::Error::TooLarge(_)) => { + state.svg_limits = state.svg_limits.saturating_add(1); + state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); + } + _ => state.invalid_svg = state.invalid_svg.saturating_add(1), + } + return None; + } + }; + let scope = { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + let Some(total) = state.xml_depth.checked_add(checked.height).filter(|depth| *depth <= self.limits.tree_depth) else { + state.svg_limits = state.svg_limits.saturating_add(1); + return None; + }; + let previous = state.xml_depth; + state.xml_depth = total; + state.depth = state.depth.saturating_add(1); + state.svg_depth = state.svg_depth.max(state.depth); + Scope { state: Arc::clone(&self.state), previous, child: true } + }; + let result = convert_checked(checked, options); + drop(scope); + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + match result { + Ok(tree) => { + state.svg_count = state.svg_count.saturating_add(1); + Some(usvg::ImageKind::SVG(tree)) + } + Err(_) => { + state.invalid_svg = state.invalid_svg.saturating_add(1); + None + } + } + } +} + +struct Scope { + state: Arc>, + previous: usize, + child: bool, +} +impl Drop for Scope { + fn drop(&mut self) { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + state.xml_depth = self.previous; + if self.child { + state.depth = state.depth.saturating_sub(1); + } else { + state.root_active = false; + } + } +} + +fn convert_checked(checked: Preflight<'_>, options: &usvg::Options<'_>) -> Result { + match image_href::normalize(&checked)? { + std::borrow::Cow::Borrowed(_) => checked.parse(options), + std::borrow::Cow::Owned(text) => { + let limits = checked.limits; + drop(checked); + preflight(&text, &limits)?.parse(options) + } + } +} + +#[cfg(test)] +mod tests; + +#[cfg(test)] +mod xml_tests; diff --git a/crates/svg/src/tree/validated/tests.rs b/crates/svg/src/tree/validated/tests.rs new file mode 100644 index 000000000..c090d7ab6 --- /dev/null +++ b/crates/svg/src/tree/validated/tests.rs @@ -0,0 +1,340 @@ +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)] +use super::*; +use std::io::Write; +const PIXELS: u64 = 24_000_000; +const SVG_BYTES: usize = 16 << 20; + +fn test_limits(pixels: u64) -> Limits { + Limits { + bytes: 1 << 30, + depth: 513, + tree_depth: 513, + embedded_bytes: SVG_BYTES, + embedded_depth: 32, + embedded_raster_pixels: pixels, + ..Default::default() + } +} +fn test_state(pixels: u64) -> State { + State::new(test_limits(pixels)) +} +fn wrapped_options(pixels: u64) -> (usvg::Options<'static>, Arc>, Arc) { + let resolver = Arc::new(ValidatedImageResolver::new(test_limits(pixels))); + let options = usvg::Options { image_href_resolver: resolver.resolver(), ..Default::default() }; + (options, Arc::clone(&resolver.state), resolver) +} +fn on_test_stack(run: impl FnOnce() -> Result + Send) -> Result { + std::thread::scope(|scope| std::thread::Builder::new().stack_size(16 << 20).spawn_scoped(scope, run).unwrap().join().unwrap()) +} +fn png() -> Vec { + let image = craft_image_codecs::Image::from_u8(2, 2, craft_image_codecs::ChannelLayout::Rgb, [17, 83, 149].repeat(4)).unwrap(); + craft_image_codecs::encode(&image, craft_image_codecs::Format::Png, &Default::default()).unwrap() +} +fn data_url(mime: &str, bytes: &[u8]) -> String { + use std::fmt::Write; + let mut result = format!("data:{mime},"); + for byte in bytes { + write!(&mut result, "%{byte:02X}").unwrap(); + } + result +} + +#[test] +fn original_nested_xml_bytes_are_not_refunded_when_malformed_hrefs_shrink() { + on_test_stack(|| { + let (options, state, _resolver) = wrapped_options(PIXELS); + let prefix = ""; + let original_size = 3 << 20; + let source = Arc::new([prefix.as_bytes(), &vec![b'A'; original_size - prefix.len() - suffix.len()], suffix.as_bytes()].concat()); + assert_eq!(source.len(), original_size); + for accepted in 1..=5 { + let kind = (options.image_href_resolver.resolve_data)("image/svg+xml", Arc::clone(&source), &options); + assert!(matches!(kind, Some(usvg::ImageKind::SVG(_))), "source {accepted} fits the original-text allowance"); + drop(kind); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.svg_bytes_left, SVG_BYTES - accepted * original_size); + assert!(!state.svg_failure_exhausted); + assert_eq!(state.classification_bytes_left, SVG_BYTES); + let usage = state.usage(); + assert_eq!(usage.embedded_svg_bytes, accepted * original_size, "the short replacement cannot refund original XML work"); + } + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::clone(&source), &options).is_none()); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.svg_bytes_left, 0); + assert_eq!((state.svg_limits, state.svg_resource_limits), (1, 1)); + assert!(!state.svg_failure_exhausted, "ordinary byte exhaustion cannot enter compatibility classification"); + assert_eq!(state.classification_bytes_left, SVG_BYTES); + assert_eq!(state.usage().svg_resource_limit_images, 1); + Ok(()) + }) + .unwrap(); +} + +#[test] +fn invalid_utf8_gzip_consumes_remaining_svg_work_before_the_next_child() { + on_test_stack(|| { + let (options, state, _resolver) = wrapped_options(PIXELS); + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(&[0xff; 4096]).unwrap(); + let invalid = Arc::new(encoder.finish().unwrap()); + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", invalid, &options).is_none()); + { + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.svg_bytes_left, 0, "a failed decode cannot retry the full work allowance"); + assert_eq!(state.invalid_svg, 1); + assert!(state.svg_failure_exhausted); + assert_eq!(state.svg_resource_limits, 0); + assert_eq!(state.classification_bytes_left, SVG_BYTES); + } + let valid = Arc::new(b"".to_vec()); + let valid_size = valid.len(); + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", valid, &options).is_none()); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!((state.invalid_svg, state.svg_limits, state.svg_resource_limits), (1, 1, 0)); + assert_eq!(state.classification_bytes_left, SVG_BYTES, "plain input does not spend retry inflation work"); + let usage = state.usage(); + assert_eq!(usage.embedded_svg_bytes, SVG_BYTES); + assert_eq!(usage.svg_resource_limit_images, 0, "a later small child is omitted, not a resource error"); + let charged = 2 * SVG_BYTES - state.svg_bytes_left - state.classification_bytes_left; + assert_eq!(charged, SVG_BYTES); + assert!(valid_size < SVG_BYTES); + Ok(()) + }) + .unwrap(); +} + +#[test] +fn post_failure_classification_is_cumulative_and_never_admits_later_children() { + on_test_stack(|| { + let (options, state, _resolver) = wrapped_options(PIXELS); + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(&[0xff; 256]).unwrap(); + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encoder.finish().unwrap()), &options).is_none()); + let text = b""; + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(text).unwrap(); + let valid = Arc::new(encoder.finish().unwrap()); + // Exercise the cumulative inflated-byte boundary with a small injected + // second pool; public tests cover the full 16 MiB allowance. + let classification_limit = text.len() * 2 - 1; + state.lock().unwrap_or_else(PoisonError::into_inner).classification_bytes_left = classification_limit; + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::clone(&valid), &options).is_none()); + { + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_bytes_left, text.len() - 1); + assert_eq!((state.svg_limits, state.svg_resource_limits), (1, 0)); + } + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::clone(&valid), &options).is_none()); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_bytes_left, 0); + assert_eq!((state.svg_limits, state.svg_resource_limits), (2, 1)); + assert_eq!(state.svg_bytes_left, 0, "classification never refunds original failed work"); + assert!(state.svg_failure_exhausted); + let charged = 2 * SVG_BYTES - state.svg_bytes_left - state.classification_bytes_left; + assert_eq!(charged, 2 * SVG_BYTES, "original content plus aggregate retry inflation allowances remain bounded"); + assert_eq!(state.usage().embedded_svg_count, 0, "classified children must never reach the shared parser"); + Ok(()) + }) + .unwrap(); +} + +#[test] +fn retry_inflation_room_and_saved_decoded_content_room_remain_independent() { + on_test_stack(|| { + let mut latin1 = b""); + let decoded_len = crate::svgz::decode(&latin1).unwrap().len(); + assert!(latin1.len() < 256 && decoded_len > 256 && decoded_len < 512); + let gzip = |bytes: &[u8]| { + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(bytes).unwrap(); + Arc::new(encoder.finish().unwrap()) + }; + for (content_room, expected_resource) in [(512usize, false), (256, true)] { + let (options, state, _resolver) = wrapped_options(PIXELS); + // Model preceding genuine content consumption before an unreadable + // stream burns the rest. Classification must save this exact room. + state.lock().unwrap_or_else(PoisonError::into_inner).svg_bytes_left = content_room; + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", gzip(&[0xff; 4]), &options).is_none()); + { + let mut state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_content_left, content_room); + assert_eq!(state.svg_bytes_left, 0); + // Enough compressed retry work for the raw Latin-1 bytes, but + // less than their decoded UTF-8 length, just like main's case. + state.classification_bytes_left = latin1.len() + 1; + } + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", gzip(&latin1), &options).is_none()); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_bytes_left, 1, "retry work charges inflated bytes, not UTF-8 bytes"); + assert_eq!(state.svg_resource_limits, usize::from(expected_resource)); + assert_eq!(state.svg_bytes_left, 0, "classification never restores original content allowance"); + assert_eq!(state.usage().embedded_svg_count, 0, "no classified child is parsed or drawn"); + } + Ok(()) + }) + .unwrap(); +} + +#[test] +fn failed_raster_callbacks_release_sources_and_keep_every_decode_charge() { + let mut broken = png(); + let idat = broken.windows(4).position(|bytes| bytes == b"IDAT").unwrap(); + broken[idat + 4] ^= 1; + assert_eq!(craft_image_codecs::probe_allocation_size(&broken).unwrap(), (2, 2)); + let mut state = test_state(8); + let encoded_before = state.encoded_left; + for attempt in 1..=2 { + // Match usvg's actual callback boundary: each href gets a new Arc. + let encoded = Arc::new(broken.clone()); + let weak = Arc::downgrade(&encoded); + let kind = usvg::ImageKind::PNG(Arc::clone(&encoded)); + assert!(!state.raster(&kind)); + assert_eq!(state.pixels_left, 8 - attempt * 4); + assert_eq!(state.encoded_left, encoded_before - attempt as usize * encoded.len()); + assert_eq!(state.invalid_raster, attempt as usize); + drop(kind); + drop(encoded); + assert!(weak.upgrade().is_none(), "validation must not retain failed callback buffers until parse completion"); + } + assert!(!state.raster(&usvg::ImageKind::PNG(Arc::new(png())))); + assert_eq!((state.invalid_raster, state.raster_limits), (2, 1)); + assert_eq!(state.usage().raster_pixels, 8); +} + +#[test] +fn valid_raster_callbacks_spend_exact_pixel_and_encoded_allowances_per_call() { + let encoded = Arc::new(png()); + let kind = usvg::ImageKind::PNG(Arc::clone(&encoded)); + let mut state = test_state(8); + state.encoded_left = encoded.len() * 2; + assert!(state.raster(&kind)); + assert_eq!((state.pixels_left, state.encoded_left), (4, encoded.len())); + assert!(state.raster(&kind), "even a directly reused Arc is a new actual validation call"); + assert_eq!((state.pixels_left, state.encoded_left), (0, 0)); + assert!(!state.raster(&kind)); + assert_eq!((state.invalid_raster, state.raster_limits), (0, 1)); + let usage = state.usage(); + assert_eq!((usage.raster_pixels, usage.raster_limit_images), (8, 1)); +} + +#[test] +fn raster_callbacks_own_per_call_pixel_charges_and_keep_mime_aliases_separate() { + let png = Arc::new(png()); + let (options, state, resolver) = wrapped_options(4); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::clone(&png), &options).is_some()); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::clone(&png), &options).is_none()); + assert_eq!((resolver.usage().raster_pixels, resolver.usage().invalid_raster_images, resolver.usage().raster_limit_images), (4, 0, 1)); + assert!((options.image_href_resolver.resolve_data)("image/jpeg", png, &options).is_none()); + let usage = state.lock().unwrap().usage(); + assert_eq!((usage.raster_pixels, usage.invalid_raster_images), (4, 1)); +} + +#[test] +fn encoded_raster_refusal_is_per_image_and_does_not_consume_unattempted_work() { + let bytes = png(); + let mut oversized = bytes.clone(); + oversized.extend([0; 32]); + let mut state = test_state(4); + state.encoded_left = bytes.len(); + assert!(!state.raster(&usvg::ImageKind::PNG(Arc::new(oversized)))); + assert_eq!((state.encoded_left, state.pixels_left), (bytes.len(), 4)); + assert!(state.raster(&usvg::ImageKind::PNG(Arc::new(bytes)))); + assert_eq!((state.encoded_left, state.pixels_left), (0, 0)); + let usage = state.usage(); + assert_eq!((usage.raster_pixels, usage.raster_limit_images, usage.invalid_raster_images), (4, 1, 0)); +} + +#[test] +fn encoded_raster_exhaustion_keeps_ordinary_drawing_and_reports_only_omitted_images() { + let bytes = png(); + let href = data_url("image/png", &bytes); + let text = format!( + r##""## + ); + let resolver = ValidatedImageResolver::new(test_limits(8)); + resolver.state.lock().unwrap().encoded_left = bytes.len(); + let tree = resolver.parse_preflight(preflight(&text, &resolver.limits()).unwrap(), usvg::Options::default()).unwrap(); + let usage = resolver.usage(); + assert_eq!((usage.raster_pixels, usage.raster_limit_images, usage.invalid_raster_images), (4, 1, 0)); + let output = super::super::draw::render(&tree, usvg::Transform::identity(), 4, 2, 0, 1 << 20).unwrap(); + let background = output.pixel(3, 1).unwrap().demultiply(); + assert_eq!((background.red(), background.green(), background.blue(), background.alpha()), (0, 255, 0, 255)); + let pixel = output.pixel(0, 0).unwrap().demultiply(); + assert_eq!((pixel.red(), pixel.green(), pixel.blue(), pixel.alpha()), (17, 83, 149, 255)); + assert_eq!(resolver.state.lock().unwrap().encoded_left, 0); +} + +// Preserve upstream's text_rechecked boundary using the integrated real resolver. +// Plain and gzip retries spend source bytes before decoding, independently of +// inflation work and the drawing's genuine decoded-content capacity. +#[test] +fn plain_legacy_encoding_rechecks_have_a_separate_bounded_work_allowance() { + on_test_stack(|| { + let xml = b""; + for compressed in [false, true] { + let (options, state, _resolver) = wrapped_options(PIXELS); + let encode = |bytes: &[u8]| { + if compressed { + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(bytes).unwrap(); + encoder.finish().unwrap() + } else { + bytes.to_vec() + } + }; + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encode(&[0xff])), &options).is_none()); + state.lock().unwrap_or_else(PoisonError::into_inner).classification_text_bytes_left = xml.len(); + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encode(xml)), &options).is_none()); + { + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_text_bytes_left, 0); + assert_eq!(state.svg_resource_limits, 0, "exactly fitting text recheck is permitted"); + assert_eq!(state.classification_bytes_left, SVG_BYTES - usize::from(compressed) * xml.len()); + } + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encode(xml)), &options).is_none()); + let state = state.lock().unwrap_or_else(PoisonError::into_inner); + assert_eq!(state.classification_text_bytes_left, 0); + assert_eq!(state.svg_resource_limits, 1, "the next source cannot repeat text-conversion work"); + assert_eq!(state.invalid_svg, 1, "the original encoding error stays invalid"); + assert_eq!(state.svg_limits, 2); + assert_eq!(state.usage().embedded_svg_count, 0, "rechecked children are never admitted"); + } + Ok(()) + }) + .unwrap(); +} + +#[test] +fn embedded_gzip_obeys_document_bytes_before_aggregate_inflation_room() { + on_test_stack(|| { + let mut text = b"".len(), b' '); + text.extend_from_slice(b"-->"); + assert_eq!(text.len(), 256); + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(&text).unwrap(); + let encoded = Arc::new(encoder.finish().unwrap()); + for bytes in [text.len() - 1, text.len()] { + let limits = Limits { bytes, embedded_bytes: 1024, ..test_limits(4) }; + assert!(limits.embedded_bytes > text.len()); + let resolver = ValidatedImageResolver::new(limits); + let options = usvg::Options { image_href_resolver: resolver.resolver(), ..Default::default() }; + let image = (options.image_href_resolver.resolve_data)("image/svg+xml", Arc::clone(&encoded), &options); + let usage = resolver.usage(); + if bytes == text.len() { + assert!(matches!(image, Some(usvg::ImageKind::SVG(_))), "exact document boundary remains admissible"); + assert_eq!((usage.embedded_svg_count, usage.embedded_svg_bytes), (1, text.len())); + assert_eq!((usage.svg_resource_limit_images, usage.invalid_svg_images), (0, 0)); + } else { + assert!(image.is_none(), "aggregate room must not lift one document's inflate limit"); + assert_eq!((usage.embedded_svg_count, usage.svg_resource_limit_images, usage.invalid_svg_images), (0, 1, 0)); + assert_eq!(usage.embedded_svg_bytes, 1024, "refused work retains its aggregate charge"); + } + } + Ok(()) + }) + .unwrap(); +} diff --git a/crates/svg/src/tree/validated/xml_tests.rs b/crates/svg/src/tree/validated/xml_tests.rs new file mode 100644 index 000000000..b6b594433 --- /dev/null +++ b/crates/svg/src/tree/validated/xml_tests.rs @@ -0,0 +1,176 @@ +//! Public validated-context contracts; private byte/raster accounting lives in tests.rs. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)] +use super::super::{Limits, PREFLIGHT_PASSES, preflight, usvg}; +use super::ValidatedImageResolver; +use std::io::Write; +use std::sync::{ + Arc, + atomic::{AtomicUsize, Ordering}, +}; + +const NS: &str = "http://www.w3.org/2000/svg"; + +fn drawing(contents: &str) -> String { + format!("{contents}") +} + +fn url(bytes: &[u8]) -> String { + use std::fmt::Write; + let mut value = String::from("data:image/svg+xml,"); + for byte in bytes { + write!(&mut value, "%{byte:02X}").unwrap(); + } + value +} + +fn gzip(bytes: &[u8]) -> Vec { + let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(bytes).unwrap(); + encoder.finish().unwrap() +} + +fn image(href: &str) -> String { + format!("") +} + +fn parse_count(text: &str, limits: Limits) -> (super::super::ImageUsage, usize) { + PREFLIGHT_PASSES.with(|count| count.set(0)); + let context = ValidatedImageResolver::new(limits); + let checked = preflight(text, &limits).unwrap(); + let tree = context.parse_preflight(checked, usvg::Options::default()).unwrap(); + assert!(!tree.root().children().is_empty(), "the visible drawing survives validation"); + (context.usage(), PREFLIGHT_PASSES.with(|count| count.get())) +} + +#[test] +fn validated_root_reuses_checked_xml_and_rechecks_only_changed_attributes() { + let ordinary = drawing(""); + let repaired = drawing(""); + let (usage, count) = parse_count(&ordinary, Limits::default()); + assert_eq!(count, 1); + assert_eq!(usage.invalid_raster_images, 0); + let (usage, count) = parse_count(&repaired, Limits::default()); + assert_eq!(count, 2); + assert_eq!(usage.invalid_raster_images, 1); +} + +#[test] +fn validated_plain_and_gzip_children_reuse_their_original_preflight() { + for repaired in [false, true] { + let mut contents = String::from(""); + if repaired { + contents.push_str(""); + } + let child = drawing(&contents); + for compressed in [false, true] { + let encoded = if compressed { gzip(child.as_bytes()) } else { child.as_bytes().to_vec() }; + let root = drawing(&image(&url(&encoded))); + let (usage, count) = parse_count(&root, Limits::default()); + assert_eq!(count, if repaired { 3 } else { 2 }, "compressed={compressed}, repaired={repaired}"); + assert_eq!(usage.embedded_svg_count, 1); + assert_eq!(usage.embedded_svg_bytes, child.len()); + assert_eq!(usage.invalid_raster_images, usize::from(repaired)); + assert_eq!(usage.invalid_svg_images, 0); + } + } +} + +#[test] +fn validated_original_xml_guards_precede_normalization_and_conversion() { + let normal = drawing(""); + let entity = format!("]>{}", drawing("")); + let markup = format!("'>]>{}", drawing("&a;")); + let referenced = drawing(""); + for (text, limits) in [ + (&normal, Limits { bytes: normal.len() - 1, ..Default::default() }), + (&normal, Limits { attributes: 0, ..Default::default() }), + (&normal, Limits { xml_nodes: 1, ..Default::default() }), + (&entity, Limits { entity_bytes: 1, ..Default::default() }), + (&markup, Limits { refuse_entity_markup: true, ..Default::default() }), + (&referenced, Limits { tree_depth: 2, ..Default::default() }), + ] { + assert!(preflight(text, &limits).is_err(), "original source must be refused before normalization: {text}"); + } + let limits = Limits { entity_bytes: 1024, ..Default::default() }; + let context = ValidatedImageResolver::new(limits); + let checked = preflight(&entity, &limits).unwrap(); + context.parse_preflight(checked, usvg::Options::default()).unwrap(); + assert_eq!(context.usage().invalid_raster_images, 1, "admitted entity data reaches omission accounting"); +} + +#[test] +fn validated_context_requires_exact_preflight_limits() { + let text = drawing(""); + let limits = Limits { bytes: 4096, tree_depth: 16, embedded_bytes: 2048, ..Default::default() }; + let context = ValidatedImageResolver::new(limits); + assert_eq!(context.limits(), limits); + for changed in [ + Limits { bytes: 4095, ..limits }, + Limits { bytes: 4097, ..limits }, + Limits { tree_depth: 15, ..limits }, + Limits { embedded_bytes: 2049, ..limits }, + ] { + let checked = preflight(&text, &changed).unwrap(); + assert!(context.parse_preflight(checked, usvg::Options::default()).is_err()); + assert_eq!(context.usage(), Default::default(), "policy mismatch must not start conversion"); + } + context.parse_preflight(preflight(&text, &limits).unwrap(), usvg::Options::default()).unwrap(); +} + +fn hostile_options(calls: &Arc) -> usvg::Options<'static> { + let string_calls = Arc::clone(calls); + let data_calls = Arc::clone(calls); + usvg::Options { + image_href_resolver: usvg::ImageHrefResolver { + resolve_string: Box::new(move |_, _| { + string_calls.fetch_add(1, Ordering::SeqCst); + panic!("ambient string resolver must not run") + }), + resolve_data: Box::new(move |_, _, _| { + data_calls.fetch_add(1, Ordering::SeqCst); + panic!("caller data resolver must not bypass validation") + }), + }, + ..Default::default() + } +} + +#[test] +fn validated_root_and_nested_context_override_untrusted_image_callbacks() { + let calls = Arc::new(AtomicUsize::new(0)); + let child = drawing( + "", + ); + let root = drawing(&format!("{}", image(&url(child.as_bytes())))); + let limits = Limits::default(); + let context = ValidatedImageResolver::new(limits); + context.parse_preflight(preflight(&root, &limits).unwrap(), hostile_options(&calls)).unwrap(); + assert_eq!(calls.load(Ordering::SeqCst), 0); + assert_eq!(context.usage().embedded_svg_count, 1); + assert_eq!(context.usage().invalid_raster_images, 1); + let direct = ValidatedImageResolver::new(limits); + assert!(matches!(direct.resolve_text(&child, hostile_options(&calls)).unwrap(), Some(usvg::ImageKind::SVG(_)))); + assert_eq!(calls.load(Ordering::SeqCst), 0); + assert_eq!(direct.usage().invalid_raster_images, 1); +} + +#[test] +fn expanded_root_references_and_child_share_the_converted_depth_limit() { + let child = drawing(""); // height 3 + let href = url(child.as_bytes()); + let root = drawing(&format!("{}", image(&href))); // height 6 + assert!(preflight(&root, &Limits { tree_depth: 5, ..Default::default() }).is_err()); + assert!(preflight(&root, &Limits { tree_depth: 6, ..Default::default() }).is_ok()); + assert!(preflight(&child, &Limits { tree_depth: 3, ..Default::default() }).is_ok()); + for (depth, admitted) in [(8, false), (9, true)] { + let limits = Limits { tree_depth: depth, ..Default::default() }; + let checked = preflight(&root, &limits).unwrap(); + assert!(checked.depth() < 6, "source nesting is shallower than expanded references"); + let context = ValidatedImageResolver::new(limits); + context.parse_preflight(checked, usvg::Options::default()).unwrap(); + let usage = context.usage(); + assert_eq!(usage.embedded_svg_count, usize::from(admitted)); + assert_eq!(usage.svg_limit_images, usize::from(!admitted)); + assert_eq!(usage.invalid_svg_images, 0); + } +} From ca56374cf1bda5b7660ccd526048ac134fd52d58 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:07:31 +0800 Subject: [PATCH 14/97] Use shared preflight in MIME body regression --- crates/svg/src/tree/mime_header_tests.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/svg/src/tree/mime_header_tests.rs b/crates/svg/src/tree/mime_header_tests.rs index 393a01729..c22ef7d4a 100644 --- a/crates/svg/src/tree/mime_header_tests.rs +++ b/crates/svg/src/tree/mime_header_tests.rs @@ -136,8 +136,8 @@ fn many_parameter_urls_preserve_bodies_and_base64_disposition() { ] { let text = format!(""); let repaired = repair(&text, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(); - let xml = checked_xml(&repaired, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(); - let value = xml.descendants().find(|node| node.has_tag_name("image")).unwrap().attribute("href").unwrap(); + let checked = super::super::preflight(&repaired, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(); + let value = checked.xml.descendants().find(|node| node.has_tag_name("image")).unwrap().attribute("href").unwrap(); assert!(!value.contains(";p0=")); assert_eq!(data_url::DataUrl::process(value).unwrap().decode_to_vec().unwrap().0, expected); assert!(matches!(repair(&repaired, &Limits { bytes: 2 << 20, ..Default::default() }).unwrap(), Cow::Borrowed(_))); From 6d0fa2c26dc05d7d909ec33051d05f4c40a740d5 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:09:27 +0800 Subject: [PATCH 15/97] Parse lockfile dependency graphs as TOML documents --- crates/svg/src/tree/draw/decoder_edges.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/svg/src/tree/draw/decoder_edges.rs b/crates/svg/src/tree/draw/decoder_edges.rs index 8258b5792..7d0c072d6 100644 --- a/crates/svg/src/tree/draw/decoder_edges.rs +++ b/crates/svg/src/tree/draw/decoder_edges.rs @@ -16,7 +16,7 @@ pub(crate) struct LockGraph { } impl LockGraph { pub(crate) fn parse(text: &str) -> Self { - let lock: toml::Value = text.parse().unwrap(); + let lock: toml::Value = toml::from_str(text).unwrap(); let packages = lock .get("package") .unwrap() From 76a27e21d72b9cd70c2d6204f91ad3544c3e8ee9 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:12:08 +0800 Subject: [PATCH 16/97] Keep validated policy storage within the renderer feature --- crates/svg/src/tree.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/svg/src/tree.rs b/crates/svg/src/tree.rs index 80feec75d..690320e82 100644 --- a/crates/svg/src/tree.rs +++ b/crates/svg/src/tree.rs @@ -167,6 +167,7 @@ pub fn root_unitless_size(svg: &str, limits: &Limits) -> Result { + #[cfg(feature = "tree-render")] limits: Limits, xml: roxmltree::Document<'s>, depth: usize, @@ -248,7 +249,13 @@ pub fn preflight<'s>(svg: &'s str, limits: &Limits) -> Result, Err let Some(height) = height(&xml, limits.tree_depth)? else { return Err(Error::TooDeep(limits.tree_depth)); }; - Ok(Preflight { limits: *limits, xml, depth, height }) + Ok(Preflight { + #[cfg(feature = "tree-render")] + limits: *limits, + xml, + depth, + height, + }) } /// Dimensions of an SVG viewport in SVG user units. From 96dd8c4e0996b3d85edf5c98070c261892ac30f3 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:14:47 +0800 Subject: [PATCH 17/97] Disambiguate the SVG writer documentation link --- crates/svg/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/svg/src/lib.rs b/crates/svg/src/lib.rs index ccb2b6837..79a706052 100644 --- a/crates/svg/src/lib.rs +++ b/crates/svg/src/lib.rs @@ -8,7 +8,7 @@ //! - `paths` (feature `paths`, on by default): the geometry of a document as Bézier paths in //! millimetres, for cutters, plotters and CAD import. //! - [`color`]: CSS colours. -//! - [`write`]: a writer for SVG documents, their path data and numbers. +//! - [`mod@write`]: a writer for SVG documents, their path data and numbers. //! - `tree` (feature `tree`): the full parser. usvg at the one version the Craft apps share, //! re-exported, behind an entry point that runs the checks above before it parses. //! From 36e58391b1225a21b749bcf1a53d9be5ec961fbb Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:34:40 +0800 Subject: [PATCH 18/97] Cover renderer backends and canonical Git dependency edges --- crates/svg/src/tree/draw/decoder_edges.rs | 60 +++++++- crates/svg/src/tree/draw/raster.rs | 4 + crates/svg/src/tree/draw/raster_tests.rs | 179 ++++++++++++++++++++++ 3 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 crates/svg/src/tree/draw/raster_tests.rs diff --git a/crates/svg/src/tree/draw/decoder_edges.rs b/crates/svg/src/tree/draw/decoder_edges.rs index 7d0c072d6..ce6543b81 100644 --- a/crates/svg/src/tree/draw/decoder_edges.rs +++ b/crates/svg/src/tree/draw/decoder_edges.rs @@ -14,6 +14,12 @@ struct Package { pub(crate) struct LockGraph { packages: Vec, } +// Cargo dependency edges may omit the resolved Git fragment even though the +// selected package ID always records it. Other source identities stay exact. +fn source_matches(edge: &str, package: Option<&str>) -> bool { + let Some(package) = package else { return false }; + if edge.starts_with("git+") && !edge.contains('#') { package.split_once('#').map_or(package, |(base, _)| base) == edge } else { package == edge } +} impl LockGraph { pub(crate) fn parse(text: &str) -> Self { let lock: toml::Value = toml::from_str(text).unwrap(); @@ -55,7 +61,9 @@ impl LockGraph { let found: Vec<_> = self .packages .iter() - .filter(|p| p.id.name == name && version.is_none_or(|v| p.id.version == v) && source.is_none_or(|s| p.id.source.as_deref() == Some(s))) + .filter(|p| { + p.id.name == name && version.is_none_or(|v| p.id.version == v) && source.is_none_or(|s| source_matches(s, p.id.source.as_deref())) + }) .collect(); assert_eq!(found.len(), 1, "ambiguous or absent resolved edge {} from {from:?}", edges[0]); found[0].id.clone() @@ -125,3 +133,53 @@ fn selected_renderer_graph_rejects_a_split_validator_backend() { let split = make(true); assert!(std::panic::catch_unwind(|| assert_renderer_edges(&split, &split.workspace_package("craft-svg"))).is_err()); } + +#[test] +fn git_edges_resolve_full_package_ids_and_reject_canonical_ambiguity() { + let fixture = |second: bool| { + let mut text = String::from( + r#" +[[package]] +name = "consumer" +version = "1" +dependencies = ["codec 1 (git+https://example.invalid/codecs?rev=chosen)"] +[[package]] +name = "explicit" +version = "1" +dependencies = ["codec 1 (git+https://example.invalid/codecs?rev=chosen#aaaa)"] +[[package]] +name = "wrong" +version = "1" +dependencies = ["codec 1 (git+https://example.invalid/codecs?rev=chosen#cccc)"] +[[package]] +name = "codec" +version = "1" +source = "git+https://example.invalid/codecs?rev=chosen#aaaa" +"#, + ); + if second { + text.push_str( + r#" +[[package]] +name = "codec" +version = "1" +source = "git+https://example.invalid/codecs?rev=chosen#bbbb" +"#, + ); + } + LockGraph::parse(&text) + }; + let unique = fixture(false); + let selected = unique.dependency(&unique.workspace_package("consumer"), "codec"); + assert_eq!(selected.source.as_deref(), Some("git+https://example.invalid/codecs?rev=chosen#aaaa")); + assert_eq!(selected, unique.dependency(&unique.workspace_package("explicit"), "codec")); + assert!(std::panic::catch_unwind(|| unique.dependency(&unique.workspace_package("wrong"), "codec")).is_err()); + let ambiguous = fixture(true); + assert!(std::panic::catch_unwind(|| ambiguous.dependency(&ambiguous.workspace_package("consumer"), "codec")).is_err()); + assert_eq!(selected, ambiguous.dependency(&ambiguous.workspace_package("explicit"), "codec")); + assert!(!source_matches("registry+one", Some("registry+one#aaaa")), "registry sources remain exact"); + assert!( + !source_matches("git+https://example.invalid/codecs?rev=other", selected.source.as_deref()), + "requested Git revision remains part of the identity" + ); +} diff --git a/crates/svg/src/tree/draw/raster.rs b/crates/svg/src/tree/draw/raster.rs index fe250259d..ffeb0d684 100644 --- a/crates/svg/src/tree/draw/raster.rs +++ b/crates/svg/src/tree/draw/raster.rs @@ -138,3 +138,7 @@ fn webp_error(error: image_webp::DecodingError) -> RasterValidationFailure { _ => RasterValidationFailure::Invalid, } } + +#[cfg(test)] +#[path = "raster_tests.rs"] +mod raster_tests; diff --git a/crates/svg/src/tree/draw/raster_tests.rs b/crates/svg/src/tree/draw/raster_tests.rs new file mode 100644 index 000000000..a7783f8c5 --- /dev/null +++ b/crates/svg/src/tree/draw/raster_tests.rs @@ -0,0 +1,179 @@ +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)] +use super::*; +use craft_image_codecs::{ChannelLayout, Format, Image}; +use std::sync::Arc; + +fn kind(format: Format, bytes: Vec) -> usvg::ImageKind { + let bytes = Arc::new(bytes); + match format { + Format::Png => usvg::ImageKind::PNG(bytes), + Format::Jpeg => usvg::ImageKind::JPEG(bytes), + Format::Gif => usvg::ImageKind::GIF(bytes), + Format::WebP => usvg::ImageKind::WEBP(bytes), + _ => panic!("test raster format"), + } +} + +fn encoded(format: Format) -> Vec { + let image = Image::from_u8(2, 2, ChannelLayout::Rgb, [17, 83, 149].repeat(4)).unwrap(); + craft_image_codecs::encode(&image, format, &Default::default()).unwrap() +} + +fn segment(out: &mut Vec, marker: u8, payload: &[u8]) { + out.extend_from_slice(&[0xff, marker]); + out.extend_from_slice(&u16::try_from(payload.len() + 2).unwrap().to_be_bytes()); + out.extend_from_slice(payload); +} + +// ISO/IEC10918-1 framing, one gray 8x8 block. The single one-bit Huffman codes +// encode DC category 0 and AC EOB. No third-party asset or camera data is used. +fn gray_jpeg(bits: u8, entropy: &[u8]) -> Vec { + let mut data = vec![0xff, 0xd8]; + let mut quantization = vec![0]; + quantization.extend_from_slice(&[1; 64]); + segment(&mut data, 0xdb, &quantization); + segment(&mut data, if bits == 8 { 0xc0 } else { 0xc1 }, &[bits, 0, 8, 0, 8, 1, 1, 0x11, 0]); + let mut tables = Vec::new(); + for class in [0x00, 0x10] { + tables.extend_from_slice(&[class, 1]); + tables.extend_from_slice(&[0; 15]); + tables.push(0); + } + segment(&mut data, 0xc4, &tables); + segment(&mut data, 0xda, &[1, 1, 0, 0, 63, 0]); + data.extend_from_slice(entropy); + data.extend_from_slice(&[0xff, 0xd9]); + data +} + +fn crc32(bytes: &[u8]) -> u32 { + let mut value = !0u32; + for byte in bytes { + value ^= u32::from(*byte); + for _ in 0..8 { + value = (value >> 1) ^ (0xedb8_8320 & 0u32.wrapping_sub(value & 1)); + } + } + !value +} + +fn corrupt_png() -> Vec { + let mut data = encoded(Format::Png); + let mut at = 8; + loop { + let length = u32::from_be_bytes(data[at..at + 4].try_into().unwrap()) as usize; + if &data[at + 4..at + 8] == b"IDAT" { + // Keep the complete container and an honest CRC, but destroy the + // zlib header in the pixel stream rather than the dimension header. + assert!(length >= 2); + data[at + 8..at + 10].fill(0); + let crc = crc32(&data[at + 4..at + 8 + length]); + data[at + 8 + length..at + 12 + length].copy_from_slice(&crc.to_be_bytes()); + return data; + } + at += length + 12; + } +} + +fn corrupt_gif() -> Vec { + // Complete 2x2 GIF89a framing and palette, followed by a code7 when only + // codes 0..5 are initially defined by an LZW minimum code size of 2. + let mut data = b"GIF89a".to_vec(); + data.extend_from_slice(&[2, 0, 2, 0, 0x80, 0, 0]); + data.extend_from_slice(&[0, 0, 0, 0, 255, 0]); + data.extend_from_slice(&[0x2c, 0, 0, 0, 0, 2, 0, 2, 0, 0]); + data.extend_from_slice(&[2, 1, 7, 0, 0x3b]); + data +} + +fn corrupt_webp() -> Vec { + // Complete RIFF/VP8L dimensions, with no transform/Huffman/pixel bits. + // Chunk length and odd-byte padding remain internally consistent. + let mut data = b"RIFF".to_vec(); + data.extend_from_slice(&18u32.to_le_bytes()); + data.extend_from_slice(b"WEBPVP8L"); + data.extend_from_slice(&5u32.to_le_bytes()); + data.extend_from_slice(&[0x2f, 1, 0x40, 0, 0, 0]); + data +} + +#[test] +fn renderer_validator_accepts_complete_png_jpeg_gif_and_webp_at_exact_pixel_allowance() { + for format in [Format::Png, Format::Jpeg, Format::Gif, Format::WebP] { + let data = encoded(format); + assert_eq!(craft_image_codecs::probe_allocation_size(&data).unwrap(), (2, 2)); + let mut remaining = 4; + assert_eq!(validate_raster(&kind(format, data), 4, &mut remaining), Ok(()), "{format:?}"); + assert_eq!(remaining, 0, "{format:?}: exact area must be charged"); + } +} + +#[test] +fn renderer_validator_rejects_corrupt_pixels_after_valid_dimensions_without_refunding_work() { + let cases = [ + (Format::Png, corrupt_png(), (2, 2)), + // One-bit tables have no code starting with1. Stuffed all-one bits + // are an invalid entropy code, while SOF/DQT/DHT/SOS remain valid. + (Format::Jpeg, gray_jpeg(8, &[0xff, 0, 0xff, 0, 0xff, 0]), (8, 8)), + (Format::Gif, corrupt_gif(), (2, 2)), + (Format::WebP, corrupt_webp(), (2, 2)), + ]; + for (format, data, dimensions) in cases { + assert_eq!(craft_image_codecs::probe_allocation_size(&data).unwrap(), dimensions, "{format:?}"); + match format { + Format::Jpeg => { + let mut headers = zune_jpeg::JpegDecoder::new(Cursor::new(&data)); + headers.decode_headers().expect("intact JPEG scan headers before corrupt entropy"); + } + Format::Gif => { + gif::DecodeOptions::new().read_info(data.as_slice()).expect("intact GIF headers before corrupt LZW pixels"); + } + Format::WebP => { + image_webp::WebPDecoder::new(Cursor::new(&data)).expect("intact WebP headers before missing pixel bits"); + } + _ => {} + } + let pixels = u64::from(dimensions.0) * u64::from(dimensions.1); + let image = kind(format, data); + let mut remaining = pixels * 2; + for left in [pixels, 0] { + assert_eq!(validate_raster(&image, pixels, &mut remaining), Err(RasterValidationFailure::Invalid), "{format:?}"); + assert_eq!(remaining, left, "{format:?}: failed decode work is nonrefundable"); + } + assert_eq!(validate_raster(&image, pixels, &mut remaining), Err(RasterValidationFailure::Limit), "{format:?}"); + assert_eq!(remaining, 0); + } +} + +#[test] +fn twelve_bit_jpeg_is_valid_for_the_general_codec_but_not_the_svg_renderer() { + for bits in [8, 12] { + // DC=0, EOB=0, then six one-pad bits: a constant mid-gray block. + let data = gray_jpeg(bits, &[0x3f]); + let decoded = craft_image_codecs::decode(&data).unwrap(); + assert_eq!(decoded.dimensions(), (8, 8)); + let mut remaining = 64; + let expected = if bits == 8 { Ok(()) } else { Err(RasterValidationFailure::Invalid) }; + assert_eq!(validate_raster(&kind(Format::Jpeg, data), 64, &mut remaining), expected, "{bits}-bit"); + assert_eq!(remaining, 0, "capability refusal still spends attempted decode work"); + } +} + +#[test] +fn renderer_validator_refuses_unadmitted_headers_and_pixels_without_charging_unattempted_decode() { + for format in [Format::Png, Format::Jpeg, Format::Gif, Format::WebP] { + let image = kind(format, encoded(format)); + let mut remaining = 4; + assert_eq!(validate_raster(&image, 3, &mut remaining), Err(RasterValidationFailure::Limit), "{format:?}: per-image ceiling"); + assert_eq!(remaining, 4); + remaining = 3; + assert_eq!(validate_raster(&image, 4, &mut remaining), Err(RasterValidationFailure::Limit), "{format:?}: cumulative allowance"); + assert_eq!(remaining, 3); + assert_eq!( + validate_raster(&kind(format, b"invalid raster header".to_vec()), 4, &mut remaining), + Err(RasterValidationFailure::Invalid), + "{format:?}" + ); + assert_eq!(remaining, 3, "invalid dimensions cannot reserve an invented area"); + } +} From 8af8f407af4c81c80f05396343df0d238b97626b Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 19:42:04 +0800 Subject: [PATCH 19/97] Use an observed JPEG decode failure fixture --- crates/svg/src/tree/draw/raster_tests.rs | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/crates/svg/src/tree/draw/raster_tests.rs b/crates/svg/src/tree/draw/raster_tests.rs index a7783f8c5..273705744 100644 --- a/crates/svg/src/tree/draw/raster_tests.rs +++ b/crates/svg/src/tree/draw/raster_tests.rs @@ -46,6 +46,18 @@ fn gray_jpeg(bits: u8, entropy: &[u8]) -> Vec { data } +fn corrupt_jpeg() -> Vec { + let mut data = gray_jpeg(8, &[0x3f]); + let scan = data.windows(2).position(|marker| marker == b"\xff\xda").unwrap(); + // Keep the complete scan header and valid entropy, but reference table 1 + // while DHT defines only table 0. The renderer accepts these headers, then + // fails pixel decoding when checking the selected Huffman tables. Random + // all-one entropy is tolerated by its default policy and is not this guard. + assert_eq!(data[scan + 6], 0); + data[scan + 6] = 0x11; + data +} + fn crc32(bytes: &[u8]) -> u32 { let mut value = !0u32; for byte in bytes { @@ -112,9 +124,8 @@ fn renderer_validator_accepts_complete_png_jpeg_gif_and_webp_at_exact_pixel_allo fn renderer_validator_rejects_corrupt_pixels_after_valid_dimensions_without_refunding_work() { let cases = [ (Format::Png, corrupt_png(), (2, 2)), - // One-bit tables have no code starting with1. Stuffed all-one bits - // are an invalid entropy code, while SOF/DQT/DHT/SOS remain valid. - (Format::Jpeg, gray_jpeg(8, &[0xff, 0, 0xff, 0, 0xff, 0]), (8, 8)), + // Header-only admission cannot detect this missing scan-table dependency. + (Format::Jpeg, corrupt_jpeg(), (8, 8)), (Format::Gif, corrupt_gif(), (2, 2)), (Format::WebP, corrupt_webp(), (2, 2)), ]; @@ -123,7 +134,7 @@ fn renderer_validator_rejects_corrupt_pixels_after_valid_dimensions_without_refu match format { Format::Jpeg => { let mut headers = zune_jpeg::JpegDecoder::new(Cursor::new(&data)); - headers.decode_headers().expect("intact JPEG scan headers before corrupt entropy"); + headers.decode_headers().expect("intact JPEG scan headers before unavailable pixel-decode table"); } Format::Gif => { gif::DecodeOptions::new().read_info(data.as_slice()).expect("intact GIF headers before corrupt LZW pixels"); From fcafab33d9fedbefb0992d7776db3b6ae8b918f6 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Tue, 17 Nov 2026 20:09:30 +0800 Subject: [PATCH 20/97] Preserve the exact embedded SVG depth boundary --- crates/svg/README.md | 6 ++++-- crates/svg/src/tree/validated.rs | 7 +++--- crates/svg/src/tree/validated/xml_tests.rs | 25 +++++++++++++++++++++- 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/crates/svg/README.md b/crates/svg/README.md index 0810b1217..519015c1b 100644 --- a/crates/svg/README.md +++ b/crates/svg/README.md @@ -46,8 +46,10 @@ The caller supplies fonts and a sufficient stack/worker for its depth policy. `parse_preflight` accepts only an opaque preflight made with exactly this context's limits. It consumes options and installs its own data-only resolver, including for all children; unrelated callbacks cannot fetch a linked file or bypass admission. -The full expanded root height and each child's expanded height share one depth -allowance. An overlapping root conversion on the same context is refused. +Expanded root ancestor frames (checked height minus the callback leaf) and each +child's complete expanded height share one depth allowance. The callback leaf is +not counted twice; source nesting alone cannot hide expanded reference chains. +An overlapping root conversion on the same context is refused. Unchanged XML converts from its original checked DOM. A modified data URL requires one checked replacement DOM. Invalid URLs become bounded resolver-visible image diff --git a/crates/svg/src/tree/validated.rs b/crates/svg/src/tree/validated.rs index cb1b6e8c3..658b2641f 100644 --- a/crates/svg/src/tree/validated.rs +++ b/crates/svg/src/tree/validated.rs @@ -191,9 +191,10 @@ impl ValidatedImageResolver { if checked.limits != self.limits { return Err(Error::Parse("checked SVG limits differ from the validated image resolver".into())); } - // A shallow source can expand through use/paint references. Reserve the - // full checked converted height before any child callback, not source depth. - let _scope = self.root_scope(checked.height)?; + // A shallow source can expand through use/paint references. Reserve its + // expanded ancestor frames, excluding the callback leaf itself. The child + // contributes its complete checked height, as in legacy child admission. + let _scope = self.root_scope(checked.height.saturating_sub(1))?; options.image_href_resolver = self.resolver(); convert_checked(checked, &options) } diff --git a/crates/svg/src/tree/validated/xml_tests.rs b/crates/svg/src/tree/validated/xml_tests.rs index b6b594433..34e1e604e 100644 --- a/crates/svg/src/tree/validated/xml_tests.rs +++ b/crates/svg/src/tree/validated/xml_tests.rs @@ -162,7 +162,10 @@ fn expanded_root_references_and_child_share_the_converted_depth_limit() { assert!(preflight(&root, &Limits { tree_depth: 5, ..Default::default() }).is_err()); assert!(preflight(&root, &Limits { tree_depth: 6, ..Default::default() }).is_ok()); assert!(preflight(&child, &Limits { tree_depth: 3, ..Default::default() }).is_ok()); - for (depth, admitted) in [(8, false), (9, true)] { + // Expanded root height6 includes the callback leaf: reserve5 ancestors, + // then admit the child's complete height3. Source depth alone would wrongly + // accept the cap7 case, while reserving the leaf twice would reject cap8. + for (depth, admitted) in [(7, false), (8, true)] { let limits = Limits { tree_depth: depth, ..Default::default() }; let checked = preflight(&root, &limits).unwrap(); assert!(checked.depth() < 6, "source nesting is shallower than expanded references"); @@ -174,3 +177,23 @@ fn expanded_root_references_and_child_share_the_converted_depth_limit() { assert_eq!(usage.invalid_svg_images, 0); } } + +#[test] +fn plain_root_callback_leaf_does_not_spend_the_child_boundary_twice() { + let child = drawing(""); // height3 + let root = drawing(&image(&url(child.as_bytes()))); // height2, one ancestor + for (depth, admitted) in [(3, false), (4, true)] { + let limits = Limits { tree_depth: depth, ..Default::default() }; + assert!(preflight(&root, &limits).is_ok()); + assert!(preflight(&child, &limits).is_ok()); + let context = ValidatedImageResolver::new(limits); + let tree = context.parse_preflight(preflight(&root, &limits).unwrap(), usvg::Options::default()).unwrap(); + assert_eq!(context.usage().embedded_svg_count, usize::from(admitted)); + assert_eq!(context.usage().svg_limit_images, usize::from(!admitted)); + assert_eq!(context.usage().invalid_svg_images, 0); + let pixels = super::super::draw::render(&tree, usvg::Transform::identity(), 4, 4, 0, 1 << 20).unwrap(); + let sample = pixels.pixel(1, 1).unwrap(); + assert_eq!((sample.red(), sample.green(), sample.blue()), (0, 0, 0)); + assert_eq!(sample.alpha(), if admitted { 255 } else { 0 }, "exact-boundary child must actually draw"); + } +} From 3ce8b38f88dc02cfb762dfe69817b028e9752f6f Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Tue, 17 Nov 2026 08:37:42 -0500 Subject: [PATCH 21/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything f64ae3bf3c8863a982af1304e06de20653803968. --- crates/pcap/src/lib.rs | 1277 ++++++++++++++++++++++++++++++ crates/pcap/tests/support/mod.rs | 167 ++++ 2 files changed, 1444 insertions(+) create mode 100644 crates/pcap/src/lib.rs create mode 100644 crates/pcap/tests/support/mod.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs new file mode 100644 index 000000000..62698612d --- /dev/null +++ b/crates/pcap/src/lib.rs @@ -0,0 +1,1277 @@ +//! Saved packet captures: classic pcap (microsecond and nanosecond, either byte order) and pcapng +//! (section, interface, enhanced/simple/obsolete packet blocks). Frames are decoded from Ethernet +//! (with VLAN tags), raw IP, Linux cooked (SLL/SLL2) and BSD loopback links into IPv4/IPv6, +//! TCP/UDP/ICMP, and the application facts most people ask about: DNS questions and answers, +//! HTTP/1.x request and status lines with the Host header, and the TLS ClientHello server name +//! (SNI) and ALPN. Each frame is decoded on its own: no TCP reassembly, no decryption. Pure, no I/O, +//! every length checked. + +use crate::FormatError; +use crate::bytes::Reader; +use serde::Serialize; +use std::collections::{BTreeMap, BTreeSet, HashMap}; +use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; + +/// Most frames read from one capture. +pub const MAX_PACKETS: u64 = 5_000_000; +/// Most flows tracked; later flows are counted but get no id. +pub const MAX_FLOWS: usize = 100_000; +/// Most distinct values kept per inventory (endpoints, DNS names, hosts…). +pub const MAX_INVENTORY: usize = 10_000; + +const CLASSIC_US: u32 = 0xa1b2_c3d4; +const CLASSIC_NS: u32 = 0xa1b2_3c4d; +const NG_SHB: u32 = 0x0a0d_0d0a; +const NG_BOM: u32 = 0x1a2b_3c4d; + +/// One capture interface (a pcap file has exactly one). +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Interface { + pub link_type: u32, + pub link_name: &'static str, + pub snaplen: u32, + /// Timestamp units per second, as a power: (base 10 or 2, exponent). + #[serde(skip)] + tsresol: (u8, u8), +} + +/// The plain name of a link-layer type. +pub fn link_name(link: u32) -> &'static str { + match link { + 0 => "BSD loopback", + 1 => "Ethernet", + 12 | 14 | 101 => "raw IP", + 108 => "OpenBSD loopback", + 113 => "Linux cooked (SLL)", + 228 => "raw IPv4", + 229 => "raw IPv6", + 276 => "Linux cooked v2 (SLL2)", + 105 => "IEEE 802.11", + 127 => "802.11 radiotap", + _ => "other", + } +} + +/// One captured frame. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Frame<'a> { + /// 1-based frame number, as capture tools show it. + pub number: u64, + /// Nanoseconds since the Unix epoch, when representable. + pub ts_ns: Option, + pub interface: usize, + pub link_type: u32, + pub original_len: u32, + pub data: &'a [u8], +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Kind { + Classic { le: bool, nanos: bool }, + Ng { le: bool }, +} + +/// Walks the frames of a capture. Malformed data stops the walk with a warning, never a panic. +#[derive(Debug, Clone)] +pub struct Capture<'a> { + data: &'a [u8], + pos: usize, + kind: Kind, + /// Interfaces of the current pcapng section start here in `interfaces`. + section_base: usize, + pub format: &'static str, + pub version: String, + pub interfaces: Vec, + pub warnings: Vec, + /// The walk stopped at `MAX_PACKETS`. + pub truncated: bool, + count: u64, +} + +fn rd_u16(r: &Reader<'_>, le: bool, off: usize) -> Option { + if le { r.u16_le(off) } else { r.u16_be(off) } +} + +fn rd_u32(r: &Reader<'_>, le: bool, off: usize) -> Option { + if le { r.u32_le(off) } else { r.u32_be(off) } +} + +/// True when the bytes start like a pcap or pcapng file. +pub fn is_capture(data: &[u8]) -> bool { + let r = Reader::new(data); + matches!(r.u32_le(0), Some(CLASSIC_US | CLASSIC_NS | NG_SHB)) || matches!(r.u32_be(0), Some(CLASSIC_US | CLASSIC_NS)) +} + +impl<'a> Capture<'a> { + /// Read the file header. + pub fn new(data: &'a [u8]) -> Result { + let r = Reader::new(data); + let magic_le = r.u32_le(0).ok_or_else(|| FormatError::Truncated("no capture header".into()))?; + let magic_be = r.u32_be(0).unwrap_or(0); + let mut cap = Capture { + data, + pos: 0, + kind: Kind::Ng { le: true }, + section_base: 0, + format: "pcapng", + version: String::new(), + interfaces: Vec::new(), + warnings: Vec::new(), + truncated: false, + count: 0, + }; + let classic = |le: bool, nanos: bool| -> Result<(Kind, String, Interface), FormatError> { + let major = rd_u16(&r, le, 4).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; + let minor = rd_u16(&r, le, 6).unwrap_or(0); + let snaplen = rd_u32(&r, le, 16).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; + // The top bits of the link field can carry FCS information; the type is the low 28 bits. + let link = rd_u32(&r, le, 20).ok_or_else(|| FormatError::Truncated("pcap header".into()))? & 0x0fff_ffff; + let res = if nanos { (10, 9) } else { (10, 6) }; + Ok((Kind::Classic { le, nanos }, format!("{major}.{minor}"), Interface { link_type: link, link_name: link_name(link), snaplen, tsresol: res })) + }; + match (magic_le, magic_be) { + (CLASSIC_US, _) | (_, CLASSIC_US) | (CLASSIC_NS, _) | (_, CLASSIC_NS) => { + let le = magic_le == CLASSIC_US || magic_le == CLASSIC_NS; + let nanos = (if le { magic_le } else { magic_be }) == CLASSIC_NS; + let (kind, version, iface) = classic(le, nanos)?; + cap.kind = kind; + cap.format = "pcap"; + cap.version = version; + cap.interfaces.push(iface); + cap.pos = 24; + } + (NG_SHB, _) => { + let le = match r.u32_le(8) { + Some(NG_BOM) => true, + _ if r.u32_be(8) == Some(NG_BOM) => false, + _ => return Err(FormatError::Malformed("pcapng section header without a byte-order mark".into())), + }; + cap.kind = Kind::Ng { le }; + cap.version = format!("{}.{}", rd_u16(&r, le, 12).unwrap_or(0), rd_u16(&r, le, 14).unwrap_or(0)); + } + _ => return Err(FormatError::Unsupported("not a pcap or pcapng capture".into())), + } + Ok(cap) + } + + fn stop(&mut self, why: impl Into) -> Option> { + self.warnings.push(why.into()); + self.pos = self.data.len(); + None + } + + fn ts(&self, iface: usize, units: u64) -> Option { + let (base, exp) = self.interfaces.get(iface).map(|i| i.tsresol).unwrap_or((10, 6)); + let ns = if base == 10 { + if exp <= 9 { u128::from(units) * 10u128.pow(u32::from(9 - exp)) } else { u128::from(units) / 10u128.checked_pow(u32::from(exp - 9))? } + } else { + (u128::from(units) * 1_000_000_000) >> exp.min(127) + }; + u64::try_from(ns).ok() + } + + fn frame(&mut self, iface: usize, ts_units: u64, data: &'a [u8], original_len: u32) -> Frame<'a> { + self.count += 1; + Frame { + number: self.count, + ts_ns: self.ts(iface, ts_units), + interface: iface, + link_type: self.interfaces.get(iface).map(|i| i.link_type).unwrap_or(u32::MAX), + original_len, + data, + } + } + + fn next_classic(&mut self, le: bool, nanos: bool) -> Option> { + let r = Reader::new(self.data); + let p = self.pos; + if p >= self.data.len() { + return None; + } + let (Some(sec), Some(frac), Some(incl), Some(orig)) = (rd_u32(&r, le, p), rd_u32(&r, le, p + 4), rd_u32(&r, le, p + 8), rd_u32(&r, le, p + 12)) else { + return self.stop(format!("record header at offset {p} is cut short")); + }; + let Some(body) = usize::try_from(incl).ok().and_then(|n| r.slice(p + 16, n)) else { + return self.stop(format!("record at offset {p} claims {incl} bytes past the end of the file")); + }; + self.pos = p + 16 + body.len(); + let units = u64::from(sec) * if nanos { 1_000_000_000 } else { 1_000_000 } + u64::from(frac); + Some(self.frame(0, units, body, orig)) + } + + fn next_ng(&mut self, mut le: bool) -> Option> { + loop { + let r = Reader::new(self.data); + let p = self.pos; + if p >= self.data.len() { + return None; + } + let Some(btype) = rd_u32(&r, le, p) else { return self.stop(format!("block header at offset {p} is cut short")) }; + if btype == NG_SHB { + // A new section can switch byte order. + le = match r.u32_le(p + 8) { + Some(NG_BOM) => true, + _ if r.u32_be(p + 8) == Some(NG_BOM) => false, + _ => return self.stop(format!("section header at offset {p} has no byte-order mark")), + }; + self.kind = Kind::Ng { le }; + self.section_base = self.interfaces.len(); + } + let Some(blen) = rd_u32(&r, le, p + 4).and_then(|v| usize::try_from(v).ok()) else { + return self.stop(format!("block at offset {p} is cut short")); + }; + if blen < 12 || blen % 4 != 0 || r.slice(p, blen).is_none() { + return self.stop(format!("block at offset {p} has an impossible length {blen}")); + } + self.pos = p + blen; + let body = p + 8; + let body_end = p + blen - 4; + match btype { + 1 => { + let link = u32::from(rd_u16(&r, le, body).unwrap_or(u16::MAX)); + let snaplen = rd_u32(&r, le, body + 4).unwrap_or(0); + let mut tsresol = (10u8, 6u8); + let mut o = body + 8; + while o + 4 <= body_end { + let (Some(code), Some(len)) = (rd_u16(&r, le, o), rd_u16(&r, le, o + 2)) else { break }; + if code == 0 { + break; + } + if code == 9 + && len == 1 + && let Some(v) = r.u8(o + 4) + { + tsresol = if v & 0x80 == 0 { (10, v) } else { (2, v & 0x7f) }; + } + o += 4 + usize::from(len).div_ceil(4) * 4; + } + self.interfaces.push(Interface { link_type: link, link_name: link_name(link), snaplen, tsresol }); + } + 6 | 2 => { + let (iface, hi, lo, cap, orig) = if btype == 6 { + ( + rd_u32(&r, le, body).map(|v| v as usize), + rd_u32(&r, le, body + 4), + rd_u32(&r, le, body + 8), + rd_u32(&r, le, body + 12), + rd_u32(&r, le, body + 16), + ) + } else { + ( + rd_u16(&r, le, body).map(usize::from), + rd_u32(&r, le, body + 4), + rd_u32(&r, le, body + 8), + rd_u32(&r, le, body + 12), + rd_u32(&r, le, body + 16), + ) + }; + let (Some(iface), Some(hi), Some(lo), Some(cap), Some(orig)) = (iface, hi, lo, cap, orig) else { continue }; + let Some(data) = usize::try_from(cap).ok().filter(|&c| body + 20 + c <= body_end).and_then(|c| r.slice(body + 20, c)) else { + self.warnings.push(format!("packet block at offset {p} claims more bytes than it holds; skipped")); + continue; + }; + let iface = self.section_base + iface; + if iface >= self.interfaces.len() { + self.warnings.push(format!("packet block at offset {p} names an undeclared interface; skipped")); + continue; + } + return Some(self.frame(iface, (u64::from(hi) << 32) | u64::from(lo), data, orig)); + } + 3 => { + let Some(orig) = rd_u32(&r, le, body) else { continue }; + let iface = self.section_base; + let snap = self.interfaces.get(iface).map(|i| i.snaplen).filter(|&s| s > 0).unwrap_or(u32::MAX); + let room = body_end.saturating_sub(body + 4); + let cap = (orig.min(snap) as usize).min(room); + let Some(data) = r.slice(body + 4, cap) else { continue }; + if iface >= self.interfaces.len() { + continue; + } + // Simple packet blocks carry no timestamp. + self.count += 1; + return Some(Frame { + number: self.count, + ts_ns: None, + interface: iface, + link_type: self.interfaces.get(iface).map(|i| i.link_type).unwrap_or(u32::MAX), + original_len: orig, + data, + }); + } + _ => {} + } + } + } +} + +impl<'a> Iterator for Capture<'a> { + type Item = Frame<'a>; + + fn next(&mut self) -> Option> { + if self.count >= MAX_PACKETS { + if !self.truncated && self.pos < self.data.len() { + self.truncated = true; + self.warnings.push(format!("stopped after {MAX_PACKETS} frames")); + } + return None; + } + match self.kind { + Kind::Classic { le, nanos } => self.next_classic(le, nanos), + Kind::Ng { le } => self.next_ng(le), + } + } +} + +// --------------------------------------------------------------------------------------------- +// Decoding + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct IpInfo { + pub version: u8, + pub src: IpAddr, + pub dst: IpAddr, + /// IP protocol number of the payload (6 TCP, 17 UDP, 1 ICMP, 58 ICMPv6…). + pub protocol: u8, + /// TTL or hop limit. + pub ttl: u8, + /// A non-first fragment: the transport header is in another frame. + pub fragment: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Transport { + /// tcp, udp, icmp, icmpv6 or other + pub protocol: &'static str, + #[serde(skip_serializing_if = "Option::is_none")] + pub src_port: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub dst_port: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub tcp_flags: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub seq: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub ack: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub window: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub icmp_type: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub icmp_code: Option, + pub payload_len: usize, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct DnsQuestion { + pub name: String, + pub qtype: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct DnsAnswer { + pub name: String, + pub rtype: String, + pub ttl: u32, + pub value: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Dns { + pub id: u16, + pub response: bool, + pub rcode: u8, + pub questions: Vec, + pub answers: Vec, + /// The message was cut short or malformed part-way. + pub incomplete: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Http { + /// request or response + pub kind: &'static str, + #[serde(skip_serializing_if = "Option::is_none")] + pub method: Option, + /// Request target with any user:password removed. + #[serde(skip_serializing_if = "Option::is_none")] + pub target: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub status: Option, + pub version: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub host: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct TlsHello { + pub record_version: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub sni: Option, + pub alpn: Vec, + pub supported_versions: Vec, + /// The ClientHello continues in a later segment; extensions may be missing. + pub partial: bool, +} + +/// What one frame says. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] +pub struct Decoded { + /// Protocol stack, outermost first: eth, vlan, sll, ipv4, ipv6, arp, tcp, udp, icmp, dns, http, tls… + pub protocols: Vec<&'static str>, + #[serde(skip_serializing_if = "Option::is_none")] + pub ip: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub transport: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub dns: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub http: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub tls: Option, + /// Where decoding stopped early, when it did. + #[serde(skip_serializing_if = "Option::is_none")] + pub note: Option, +} + +impl Decoded { + /// The protocol stack joined with `:`. + pub fn stack(&self) -> String { + self.protocols.join(":") + } + + /// The direction-independent conversation this frame belongs to, and whether it travels a→b. + pub fn flow_key(&self) -> Option<(FlowKey, bool)> { + let ip = self.ip.as_ref()?; + let t = self.transport.as_ref(); + let sp = t.and_then(|t| t.src_port).unwrap_or(0); + let dp = t.and_then(|t| t.dst_port).unwrap_or(0); + let (s, d) = ((ip.src, sp), (ip.dst, dp)); + let forward = s <= d; + let (a, b) = if forward { (s, d) } else { (d, s) }; + Some((FlowKey { protocol: ip.protocol, a, b }, forward)) + } +} + +/// A conversation: IP protocol and the two (address, port) ends in sorted order. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct FlowKey { + pub protocol: u8, + pub a: (IpAddr, u16), + pub b: (IpAddr, u16), +} + +/// Decode one frame from its link layer up. +pub fn decode(link_type: u32, data: &[u8]) -> Decoded { + let mut d = Decoded::default(); + let r = Reader::new(data); + let (ethertype, off) = match link_type { + 1 => { + d.protocols.push("eth"); + let mut et = r.u16_be(12); + let mut off = 14usize; + for _ in 0..2 { + if matches!(et, Some(0x8100 | 0x88a8)) { + d.protocols.push("vlan"); + et = r.u16_be(off + 2); + off += 4; + } + } + (et, off) + } + 113 => { + d.protocols.push("sll"); + (r.u16_be(14), 16) + } + 276 => { + d.protocols.push("sll2"); + (r.u16_be(0), 20) + } + 0 | 108 => { + d.protocols.push("loopback"); + // The family is in the capturing host's byte order (NULL) or big-endian (LOOP). + let fam = if link_type == 108 { r.u32_be(0) } else { r.u32_le(0).filter(|&v| v < 256).or_else(|| r.u32_be(0)) }; + ( + fam.map(|f| { + if f == 2 { + 0x0800 + } else if matches!(f, 24 | 28 | 30) { + 0x86dd + } else { + 0 + } + }), + 4, + ) + } + 12 | 14 | 101 | 228 | 229 => { + d.protocols.push("raw"); + (r.u8(0).map(|b| if b >> 4 == 6 { 0x86dd } else { 0x0800 }), 0) + } + _ => { + d.note = Some(format!("link type {link_type} ({}) is not decoded", link_name(link_type))); + return d; + } + }; + let payload = data.get(off..).unwrap_or(&[]); + match ethertype { + Some(0x0800) => ipv4(payload, &mut d), + Some(0x86dd) => ipv6(payload, &mut d), + Some(0x0806) => d.protocols.push("arp"), + Some(other) => d.note = Some(format!("ethertype {other:#06x} is not decoded")), + None => d.note = Some("frame too short for its link header".into()), + } + d +} + +fn ipv4(p: &[u8], d: &mut Decoded) { + let r = Reader::new(p); + let (Some(vihl), Some(total), Some(frag), Some(ttl), Some(proto)) = (r.u8(0), r.u16_be(2), r.u16_be(6), r.u8(8), r.u8(9)) else { + d.note = Some("IPv4 header cut short".into()); + return; + }; + let ihl = usize::from(vihl & 0x0f) * 4; + let (Some(src), Some(dst)) = (r.slice(12, 4), r.slice(16, 4)) else { return }; + if vihl >> 4 != 4 || ihl < 20 { + d.note = Some("not a valid IPv4 header".into()); + return; + } + d.protocols.push("ipv4"); + let ip4 = |b: &[u8]| { + IpAddr::V4(Ipv4Addr::new( + b.first().copied().unwrap_or(0), + b.get(1).copied().unwrap_or(0), + b.get(2).copied().unwrap_or(0), + b.get(3).copied().unwrap_or(0), + )) + }; + let fragment = frag & 0x1fff != 0; + d.ip = Some(IpInfo { version: 4, src: ip4(src), dst: ip4(dst), protocol: proto, ttl, fragment }); + let end = usize::from(total).clamp(ihl, p.len().max(ihl)); + let body = p.get(ihl..end).unwrap_or(&[]); + if fragment { + d.note = Some("IPv4 fragment (transport header is in the first fragment)".into()); + return; + } + transport(proto, body, d); +} + +fn ipv6(p: &[u8], d: &mut Decoded) { + let r = Reader::new(p); + let (Some(plen), Some(mut next), Some(hops), Some(src), Some(dst)) = (r.u16_be(4), r.u8(6), r.u8(7), r.slice(8, 16), r.slice(24, 16)) else { + d.note = Some("IPv6 header cut short".into()); + return; + }; + d.protocols.push("ipv6"); + let ip6 = |b: &[u8]| IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(b).unwrap_or([0; 16]))); + let end = (40 + usize::from(plen)).min(p.len()); + let mut off = 40usize; + let mut fragment = false; + for _ in 0..8 { + match next { + 0 | 43 | 60 => { + let (Some(n), Some(l)) = (r.u8(off), r.u8(off + 1)) else { break }; + next = n; + off += (usize::from(l) + 1) * 8; + } + 44 => { + let (Some(n), Some(fo)) = (r.u8(off), r.u16_be(off + 2)) else { break }; + next = n; + fragment = fo & 0xfff8 != 0; + off += 8; + } + 51 => { + let (Some(n), Some(l)) = (r.u8(off), r.u8(off + 1)) else { break }; + next = n; + off += (usize::from(l) + 2) * 4; + } + _ => break, + } + } + d.ip = Some(IpInfo { version: 6, src: ip6(src), dst: ip6(dst), protocol: next, ttl: hops, fragment }); + if fragment { + d.note = Some("IPv6 fragment (transport header is in the first fragment)".into()); + return; + } + transport(next, p.get(off..end).unwrap_or(&[]), d); +} + +fn tcp_flags(f: u8) -> String { + let names = [(0x02, "SYN"), (0x10, "ACK"), (0x01, "FIN"), (0x04, "RST"), (0x08, "PSH"), (0x20, "URG")]; + names.iter().filter(|(b, _)| f & b != 0).map(|(_, n)| *n).collect::>().join(",") +} + +fn transport(proto: u8, p: &[u8], d: &mut Decoded) { + let r = Reader::new(p); + let empty = Transport { + protocol: "other", + src_port: None, + dst_port: None, + tcp_flags: None, + seq: None, + ack: None, + window: None, + icmp_type: None, + icmp_code: None, + payload_len: 0, + }; + match proto { + 6 => { + let (Some(sp), Some(dp), Some(seq), Some(ack), Some(off), Some(flags), Some(win)) = + (r.u16_be(0), r.u16_be(2), r.u32_be(4), r.u32_be(8), r.u8(12), r.u8(13), r.u16_be(14)) + else { + d.note = Some("TCP header cut short".into()); + return; + }; + d.protocols.push("tcp"); + let payload = p.get(usize::from(off >> 4) * 4..).unwrap_or(&[]); + d.transport = Some(Transport { + protocol: "tcp", + src_port: Some(sp), + dst_port: Some(dp), + tcp_flags: Some(tcp_flags(flags)), + seq: Some(seq), + ack: Some(ack), + window: Some(win), + payload_len: payload.len(), + ..empty + }); + if (sp == 53 || dp == 53) && payload.len() > 2 { + dns(payload.get(2..).unwrap_or(&[]), d, "dns"); + } else if !payload.is_empty() { + tcp_app(payload, d); + } + } + 17 => { + let (Some(sp), Some(dp)) = (r.u16_be(0), r.u16_be(2)) else { + d.note = Some("UDP header cut short".into()); + return; + }; + d.protocols.push("udp"); + let payload = p.get(8..).unwrap_or(&[]); + d.transport = Some(Transport { protocol: "udp", src_port: Some(sp), dst_port: Some(dp), payload_len: payload.len(), ..empty }); + if sp == 53 || dp == 53 { + dns(payload, d, "dns"); + } else if sp == 5353 || dp == 5353 { + dns(payload, d, "mdns"); + } + } + 1 | 58 => { + let name = if proto == 1 { "icmp" } else { "icmpv6" }; + d.protocols.push(name); + d.transport = Some(Transport { protocol: name, icmp_type: r.u8(0), icmp_code: r.u8(1), payload_len: p.len().saturating_sub(4), ..empty }); + } + _ => d.transport = Some(Transport { protocol: "other", payload_len: p.len(), ..empty }), + } +} + +pub fn qtype_name(t: u16) -> String { + match t { + 1 => "A".into(), + 2 => "NS".into(), + 5 => "CNAME".into(), + 6 => "SOA".into(), + 12 => "PTR".into(), + 15 => "MX".into(), + 16 => "TXT".into(), + 28 => "AAAA".into(), + 33 => "SRV".into(), + 64 => "SVCB".into(), + 65 => "HTTPS".into(), + 255 => "ANY".into(), + n => format!("TYPE{n}"), + } +} + +/// A (possibly compressed) DNS name at `off`; returns the name and the offset after it. +fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize)> { + let mut out = String::new(); + let mut after: Option = None; + for _ in 0..128 { + let len = *msg.get(off)?; + match len { + 0 => return Some((if out.is_empty() { ".".into() } else { out }, after.unwrap_or(off + 1))), + l if l & 0xc0 == 0xc0 => { + let ptr = usize::from(u16::from_be_bytes([l & 0x3f, *msg.get(off + 1)?])); + after.get_or_insert(off + 2); + if ptr >= off { + return None; // only backward pointers, so no loops + } + off = ptr; + } + l if l < 64 => { + let label = msg.get(off + 1..off + 1 + usize::from(l))?; + if !out.is_empty() { + out.push('.'); + } + out.extend(label.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' })); + if out.len() > 255 { + return None; + } + off += 1 + usize::from(l); + } + _ => return None, + } + } + None +} + +fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { + let r = Reader::new(msg); + let (Some(id), Some(flags), Some(qd), Some(an)) = (r.u16_be(0), r.u16_be(2), r.u16_be(4), r.u16_be(6)) else { return }; + // Sanity: opcode 0–6 and no absurd counts, so random payload on port 53 isn't misread. + if (flags >> 11) & 0xf > 6 || qd > 64 || qd == 0 && an == 0 { + return; + } + d.protocols.push(label); + let mut out = Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false }; + let mut off = 12usize; + for _ in 0..qd { + let Some((name, next)) = dns_name(msg, off) else { + out.incomplete = true; + break; + }; + let Some(qt) = r.u16_be(next) else { + out.incomplete = true; + break; + }; + out.questions.push(DnsQuestion { name, qtype: qtype_name(qt) }); + off = next + 4; + } + if !out.incomplete { + for _ in 0..an.min(64) { + let Some((name, next)) = dns_name(msg, off) else { + out.incomplete = true; + break; + }; + let (Some(rt), Some(ttl), Some(rdlen)) = (r.u16_be(next), r.u32_be(next + 4), r.u16_be(next + 8)) else { + out.incomplete = true; + break; + }; + let rd_off = next + 10; + let Some(rd) = r.slice(rd_off, usize::from(rdlen)) else { + out.incomplete = true; + break; + }; + let value = match (rt, rd.len()) { + (1, 4) => Ipv4Addr::new( + rd.first().copied().unwrap_or(0), + rd.get(1).copied().unwrap_or(0), + rd.get(2).copied().unwrap_or(0), + rd.get(3).copied().unwrap_or(0), + ) + .to_string(), + (28, 16) => Ipv6Addr::from(<[u8; 16]>::try_from(rd).unwrap_or([0; 16])).to_string(), + (2 | 5 | 12, _) => dns_name(msg, rd_off).map(|(n, _)| n).unwrap_or_default(), + (15, _) => dns_name(msg, rd_off + 2).map(|(n, _)| n).unwrap_or_default(), + (16, _) => rd + .get(1..) + .map(|t| String::from_utf8_lossy(t.get(..usize::from(rd.first().copied().unwrap_or(0))).unwrap_or(t)).into_owned()) + .unwrap_or_default(), + (_, n) => format!("<{n} bytes>"), + }; + out.answers.push(DnsAnswer { name, rtype: qtype_name(rt), ttl, value }); + off = rd_off + usize::from(rdlen); + } + } + d.dns = Some(out); +} + +const METHODS: &[&str] = &["GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS", "PATCH", "CONNECT", "TRACE"]; + +/// Remove `user:password@` from an absolute request target. +pub fn strip_userinfo(target: &str) -> String { + if let Some((scheme, rest)) = target.split_once("://") { + let auth_end = rest.find(['/', '?', '#']).unwrap_or(rest.len()); + if let Some(at) = rest.get(..auth_end).and_then(|a| a.rfind('@')) { + return format!("{scheme}://{}", rest.get(at + 1..).unwrap_or("")); + } + } + target.to_string() +} + +fn tcp_app(p: &[u8], d: &mut Decoded) { + let head = p.get(..p.len().min(16 << 10)).unwrap_or(p); + let line_end = head.windows(2).position(|w| w == b"\r\n").unwrap_or(head.len().min(2048)); + let line = String::from_utf8_lossy(head.get(..line_end.min(2048)).unwrap_or(&[])).into_owned(); + if let Some(rest) = line.strip_prefix("HTTP/1.") { + let status = rest.split(' ').nth(1).and_then(|s| s.parse().ok()); + d.protocols.push("http"); + d.http = + Some(Http { kind: "response", method: None, target: None, status, version: format!("HTTP/1.{}", rest.chars().next().unwrap_or('?')), host: None }); + return; + } + let mut parts = line.splitn(3, ' '); + if let (Some(m), Some(t), Some(v)) = (parts.next(), parts.next(), parts.next()) + && METHODS.contains(&m) + && v.starts_with("HTTP/1.") + { + let lower = String::from_utf8_lossy(head).to_ascii_lowercase(); + let host = lower.find("\r\nhost:").and_then(|i| { + let start = i + 7; + let raw = String::from_utf8_lossy(head.get(start..)?).into_owned(); + Some(raw.split("\r\n").next().unwrap_or("").trim().to_string()) + }); + d.protocols.push("http"); + d.http = Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host }); + return; + } + tls(p, d); +} + +fn tls(p: &[u8], d: &mut Decoded) { + let r = Reader::new(p); + let (Some(ct), Some(major), Some(minor)) = (r.u8(0), r.u8(1), r.u8(2)) else { return }; + if !(20..=23).contains(&ct) || major != 3 || minor > 4 { + return; + } + d.protocols.push("tls"); + if ct != 22 || r.u8(5) != Some(1) { + return; + } + let ver = |v: u16| match v { + 0x0300 => "SSL 3.0".to_string(), + 0x0301 => "TLS 1.0".into(), + 0x0302 => "TLS 1.1".into(), + 0x0303 => "TLS 1.2".into(), + 0x0304 => "TLS 1.3".into(), + v if v & 0x0f0f == 0x0a0a => "GREASE".into(), + v => format!("{v:#06x}"), + }; + let mut hello = + TlsHello { record_version: ver(u16::from_be_bytes([major, minor])), sni: None, alpn: Vec::new(), supported_versions: Vec::new(), partial: false }; + // Record header (5) + handshake header (4) + client_version (2) + random (32). + let mut off = 5 + 4 + 2 + 32; + let skip8 = |off: usize| r.u8(off).map(|n| off + 1 + usize::from(n)); + let skip16 = |off: usize| r.u16_be(off).map(|n| off + 2 + usize::from(n)); + let Some(o) = skip8(off).and_then(skip16).and_then(skip8) else { + hello.partial = true; + d.tls = Some(hello); + return; + }; + off = o; + let Some(ext_len) = r.u16_be(off) else { + hello.partial = true; + d.tls = Some(hello); + return; + }; + let end = off + 2 + usize::from(ext_len); + hello.partial = end > p.len(); + let mut e = off + 2; + while e + 4 <= end.min(p.len()) { + let (Some(t), Some(l)) = (r.u16_be(e), r.u16_be(e + 2)) else { break }; + let body = e + 4; + let Some(data) = r.slice(body, usize::from(l)) else { + hello.partial = true; + break; + }; + let dr = Reader::new(data); + match t { + 0 => { + if dr.u8(2) == Some(0) + && let Some(n) = dr.u16_be(3).and_then(|n| dr.slice(5, usize::from(n))) + { + hello.sni = Some(n.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' }).collect()); + } + } + 16 => { + let mut a = 2usize; + while let Some(n) = dr.u8(a) { + let Some(proto) = dr.slice(a + 1, usize::from(n)) else { break }; + hello.alpn.push(String::from_utf8_lossy(proto).into_owned()); + a += 1 + usize::from(n); + if hello.alpn.len() >= 16 { + break; + } + } + } + 43 => { + let mut a = 1usize; + while let Some(v) = dr.u16_be(a) { + let name = ver(v); + if name != "GREASE" { + hello.supported_versions.push(name); + } + a += 2; + if hello.supported_versions.len() >= 16 { + break; + } + } + } + _ => {} + } + e = body + usize::from(l); + } + d.tls = Some(hello); +} + +// --------------------------------------------------------------------------------------------- +// Flows and summaries + +/// Assigns stable 1-based flow ids in order of first appearance. +#[derive(Debug, Default)] +pub struct FlowTable { + ids: HashMap, + /// Frames whose flow arrived after `MAX_FLOWS` and got no id. + pub untracked: u64, +} + +impl FlowTable { + /// The id of `key`, creating it when there is room. + pub fn id_for(&mut self, key: FlowKey) -> Option { + if let Some(&id) = self.ids.get(&key) { + return Some(id); + } + if self.ids.len() >= MAX_FLOWS { + self.untracked += 1; + return None; + } + let id = self.ids.len() + 1; + self.ids.insert(key, id); + Some(id) + } +} + +/// "addr:port", with brackets around IPv6 addresses; the port is omitted when zero. +pub fn endpoint((ip, port): (IpAddr, u16)) -> String { + match (ip, port) { + (IpAddr::V6(v6), 0) => v6.to_string(), + (IpAddr::V6(v6), p) => format!("[{v6}]:{p}"), + (v4, 0) => v4.to_string(), + (v4, p) => format!("{v4}:{p}"), + } +} + +pub fn ip_protocol_name(p: u8) -> &'static str { + match p { + 1 => "icmp", + 6 => "tcp", + 17 => "udp", + 58 => "icmpv6", + _ => "other", + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Flow { + pub id: usize, + pub protocol: &'static str, + pub a: String, + pub b: String, + pub packets: u64, + pub bytes: u64, + pub packets_a_to_b: u64, + pub packets_b_to_a: u64, + pub first_frame: u64, + #[serde(skip_serializing_if = "Option::is_none")] + pub first_ts_ns: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub last_ts_ns: Option, + /// Application protocols seen in it (dns, http, tls…). + pub applications: BTreeSet<&'static str>, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Count { + pub value: String, + pub count: u64, +} + +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] +pub struct Summary { + pub format: &'static str, + pub version: String, + pub interfaces: Vec, + pub packets: u64, + pub bytes: u64, + pub first_ts_ns: Option, + pub last_ts_ns: Option, + /// Frames per protocol label. + pub protocols: Vec, + /// Frames per full protocol stack (eth:ipv4:udp:dns). + pub stacks: Vec, + /// Frames per IP address (source and destination each count once per frame). + pub endpoints: Vec, + pub flows: Vec, + pub flows_untracked_frames: u64, + /// "name (TYPE)" asked in DNS queries. + pub dns_queries: Vec, + /// "name TYPE value" from DNS responses. + pub dns_answers: Vec, + /// "METHOD host target" from HTTP/1.x requests. + pub http_requests: Vec, + /// Server names from TLS ClientHellos. + pub tls_sni: Vec, + pub tls_alpn: Vec, + /// Frames whose network layer was not decoded (other link types, ARP, other ethertypes). + pub undecoded_frames: u64, + /// Inventories that hit `MAX_INVENTORY` distinct values. + pub capped_inventories: Vec<&'static str>, + pub truncated: bool, + pub warnings: Vec, +} + +#[derive(Default)] +struct Tally { + map: BTreeMap, + capped: bool, +} + +impl Tally { + fn add(&mut self, k: String) { + if let Some(v) = self.map.get_mut(&k) { + *v += 1; + } else if self.map.len() < MAX_INVENTORY { + self.map.insert(k, 1); + } else { + self.capped = true; + } + } + + fn done(self, name: &'static str, capped: &mut Vec<&'static str>) -> Vec { + if self.capped { + capped.push(name); + } + let mut v: Vec = self.map.into_iter().map(|(value, count)| Count { value, count }).collect(); + v.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.value.cmp(&b.value))); + v + } +} + +/// Read every frame once and summarize the capture. `cancelled` is polled every 4096 frames. +pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result { + let mut cap = Capture::new(data)?; + let mut s = Summary::default(); + let mut flows = FlowTable::default(); + let mut flow_rows: Vec = Vec::new(); + let (mut protocols, mut stacks, mut endpoints) = (Tally::default(), Tally::default(), Tally::default()); + let (mut queries, mut answers, mut http, mut sni, mut alpn) = (Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default()); + for f in cap.by_ref() { + if f.number % 4096 == 0 && cancelled() { + return Err(FormatError::Malformed("cancelled".into())); + } + s.packets += 1; + s.bytes += u64::from(f.original_len); + if let Some(t) = f.ts_ns { + s.first_ts_ns = Some(s.first_ts_ns.map_or(t, |x| x.min(t))); + s.last_ts_ns = Some(s.last_ts_ns.map_or(t, |x| x.max(t))); + } + let d = decode(f.link_type, f.data); + for p in &d.protocols { + protocols.add((*p).to_string()); + } + stacks.add(d.stack()); + let Some(ip) = &d.ip else { + s.undecoded_frames += 1; + continue; + }; + endpoints.add(ip.src.to_string()); + if ip.dst != ip.src { + endpoints.add(ip.dst.to_string()); + } + if let Some((key, forward)) = d.flow_key() + && let Some(id) = flows.id_for(key) + { + if id > flow_rows.len() { + flow_rows.push(Flow { + id, + protocol: ip_protocol_name(key.protocol), + a: endpoint(key.a), + b: endpoint(key.b), + packets: 0, + bytes: 0, + packets_a_to_b: 0, + packets_b_to_a: 0, + first_frame: f.number, + first_ts_ns: f.ts_ns, + last_ts_ns: f.ts_ns, + applications: BTreeSet::new(), + }); + } + if let Some(row) = flow_rows.get_mut(id - 1) { + row.packets += 1; + row.bytes += u64::from(f.original_len); + if forward { + row.packets_a_to_b += 1; + } else { + row.packets_b_to_a += 1; + } + if f.ts_ns.is_some() { + row.last_ts_ns = f.ts_ns; + } + for app in d.protocols.iter().skip_while(|p| !matches!(**p, "tcp" | "udp")).skip(1) { + row.applications.insert(app); + } + } + } + if let Some(dns) = &d.dns { + if !dns.response { + for q in &dns.questions { + queries.add(format!("{} ({})", q.name, q.qtype)); + } + } + for a in &dns.answers { + answers.add(format!("{} {} {}", a.name, a.rtype, a.value)); + } + } + if let Some(h) = &d.http + && h.kind == "request" + { + http.add(format!("{} {} {}", h.method.as_deref().unwrap_or("?"), h.host.as_deref().unwrap_or("-"), h.target.as_deref().unwrap_or(""))); + } + if let Some(t) = &d.tls { + if let Some(n) = &t.sni { + sni.add(n.clone()); + } + for a in &t.alpn { + alpn.add(a.clone()); + } + } + } + let mut capped = Vec::new(); + s.format = cap.format; + s.version = cap.version.clone(); + s.interfaces = cap.interfaces.clone(); + s.protocols = protocols.done("protocols", &mut capped); + s.stacks = stacks.done("stacks", &mut capped); + s.endpoints = endpoints.done("endpoints", &mut capped); + s.dns_queries = queries.done("dns_queries", &mut capped); + s.dns_answers = answers.done("dns_answers", &mut capped); + s.http_requests = http.done("http_requests", &mut capped); + s.tls_sni = sni.done("tls_sni", &mut capped); + s.tls_alpn = alpn.done("tls_alpn", &mut capped); + s.capped_inventories = capped; + s.flows = flow_rows; + s.flows_untracked_frames = flows.untracked; + s.truncated = cap.truncated; + s.warnings = cap.warnings; + Ok(s) +} + +/// `YYYY-MM-DDThh:mm:ss.nnnnnnnnnZ` for nanoseconds since the Unix epoch. +pub fn iso8601(ns: u64) -> String { + let secs = ns / 1_000_000_000; + let (days, rem) = (secs / 86_400, secs % 86_400); + // Civil-from-days (proleptic Gregorian), valid for every u64 day count we can reach. + let z = days as i64 + 719_468; + let era = z.div_euclid(146_097); + let doe = z - era * 146_097; + let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; + let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); + let mp = (5 * doy + 2) / 153; + let day = doy - (153 * mp + 2) / 5 + 1; + let month = if mp < 10 { mp + 3 } else { mp - 9 }; + let year = yoe + era * 400 + i64::from(month <= 2); + format!("{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:09}Z", rem / 3600, rem % 3600 / 60, rem % 60, ns % 1_000_000_000) +} + +#[cfg(test)] +mod tests { + use super::*; + use craft_anything_testkit::pcap::{dns_query, pcap, pcapng, sample_frames, udp}; + + #[test] + fn decodes_dns_tls_http() { + let frames = sample_frames(); + let d = decode(1, &frames[1]); + assert_eq!(d.stack(), "eth:ipv4:udp:dns"); + let dns = d.dns.unwrap(); + assert!(dns.response); + assert_eq!(dns.questions[0].name, "example.com"); + assert_eq!(dns.answers[0].value, "93.184.216.34"); + assert_eq!(dns.answers[0].ttl, 3600); + + let d = decode(1, &frames[4]); + assert_eq!(d.stack(), "eth:ipv4:tcp:tls"); + let t = d.tls.unwrap(); + assert_eq!(t.sni.as_deref(), Some("example.com")); + assert_eq!(t.alpn, vec!["h2", "http/1.1"]); + assert_eq!(t.supported_versions, vec!["TLS 1.3", "TLS 1.2"]); + assert!(!t.partial); + + let d = decode(1, &frames[5]); + let h = d.http.unwrap(); + assert_eq!(h.method.as_deref(), Some("GET")); + assert_eq!(h.host.as_deref(), Some("example.com")); + assert_eq!(h.target.as_deref(), Some("http://example.com/a?b=1")); + assert_eq!(decode(1, &frames[3]).transport.unwrap().tcp_flags.as_deref(), Some("SYN,ACK")); + assert_eq!(decode(1, &frames[6]).stack(), "eth:arp"); + } + + #[test] + fn summarizes_pcap_and_pcapng_alike() { + let frames = sample_frames(); + for data in [pcap(&frames), pcapng(&frames)] { + let s = summarize(&data, &|| false).unwrap(); + assert_eq!(s.packets, 7); + assert_eq!(s.flows.len(), 3, "{:?}", s.flows); + assert_eq!(s.flows[0].protocol, "udp"); + assert_eq!(s.flows[0].packets, 2); + assert_eq!((s.flows[0].packets_a_to_b, s.flows[0].packets_b_to_a), (1, 1)); + assert!(s.flows[1].applications.contains("tls")); + assert_eq!(s.dns_queries[0].value, "example.com (A)"); + assert_eq!(s.dns_answers[0].value, "example.com A 93.184.216.34"); + assert_eq!(s.tls_sni[0].value, "example.com"); + assert_eq!(s.http_requests[0].value, "GET example.com http://example.com/a?b=1"); + assert_eq!(s.undecoded_frames, 1); + assert!(s.warnings.is_empty(), "{:?}", s.warnings); + assert_eq!(s.interfaces[0].link_type, 1); + assert!(s.first_ts_ns.unwrap() >= 1_700_000_000_000_000_000); + } + assert_eq!(summarize(&pcap(&frames), &|| false).unwrap().format, "pcap"); + assert_eq!(iso8601(1_700_000_000_000_000_500), "2023-11-14T22:13:20.000000500Z"); + assert_eq!(iso8601(0), "1970-01-01T00:00:00.000000000Z"); + } + + #[test] + fn ipv6_sll_and_raw_links() { + let mut v6 = vec![0x60, 0, 0, 0]; + let payload = udp(1000, 53, &dns_query()); + v6.extend((payload.len() as u16).to_be_bytes()); + v6.extend([17, 64]); + v6.extend([0x20, 0x01, 0x0d, 0xb8].iter().chain([0u8; 11].iter()).chain([1u8].iter())); + v6.extend([0x20, 0x01, 0x0d, 0xb8].iter().chain([0u8; 11].iter()).chain([2u8].iter())); + v6.extend(&payload); + let d = decode(101, &v6); + assert_eq!(d.stack(), "raw:ipv6:udp:dns"); + assert_eq!(d.ip.unwrap().src.to_string(), "2001:db8::1"); + let mut sll = vec![0u8; 14]; + sll.extend(0x86ddu16.to_be_bytes()); + sll.extend(&v6); + assert_eq!(decode(113, &sll).stack(), "sll:ipv6:udp:dns"); + assert!(decode(105, &v6).note.is_some()); + } + + #[test] + fn hostile_input_never_panics() { + assert!(Capture::new(b"").is_err()); + assert!(Capture::new(b"not a capture at all").is_err()); + let data = pcapng(&sample_frames()); + for cut in [0, 10, 28, 40, 100, data.len() / 2, data.len() - 3] { + let _ = summarize(data.get(..cut).unwrap(), &|| false); + } + let mut bad = pcap(&sample_frames()); + bad[32..36].copy_from_slice(&[0xff; 4]); // incl_len of the first record far past the end + let s = summarize(&bad, &|| false).unwrap(); + assert_eq!(s.packets, 0); + assert!(!s.warnings.is_empty()); + for seed in 0..200u64 { + let mut x = seed.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407); + let noise: Vec = (0..300) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect(); + for link in [0, 1, 101, 113, 276, 228] { + let _ = decode(link, &noise); + } + let mut f = sample_frames(); + f.push(noise); + let _ = summarize(&pcap(&f), &|| false); + } + // DNS compression loops are refused. + assert!(dns_name(&[0xc0, 0x00], 0).is_none()); + } +} diff --git a/crates/pcap/tests/support/mod.rs b/crates/pcap/tests/support/mod.rs new file mode 100644 index 000000000..366433bc3 --- /dev/null +++ b/crates/pcap/tests/support/mod.rs @@ -0,0 +1,167 @@ +//! Packet-capture fixtures: hand-built Ethernet/IPv4 frames (DNS, TCP handshake, TLS +//! ClientHello, HTTP request, ARP) written as classic pcap or pcapng. + +const CLASSIC_US: u32 = 0xa1b2_c3d4; +const NG_SHB: u32 = 0x0a0d_0d0a; +const NG_BOM: u32 = 0x1a2b_3c4d; + +pub fn eth(ethertype: u16, payload: &[u8]) -> Vec { + let mut f = vec![0xaa; 6]; + f.extend([0xbb; 6]); + f.extend(ethertype.to_be_bytes()); + f.extend(payload); + f +} + +pub fn ipv4_pkt(proto: u8, src: [u8; 4], dst: [u8; 4], payload: &[u8]) -> Vec { + let mut p = vec![0x45, 0, 0, 0, 0, 1, 0, 0, 64, proto, 0, 0]; + p.extend(src); + p.extend(dst); + let total = (20 + payload.len()) as u16; + p[2..4].copy_from_slice(&total.to_be_bytes()); + p.extend(payload); + p +} + +pub fn udp(sp: u16, dp: u16, payload: &[u8]) -> Vec { + let mut u = sp.to_be_bytes().to_vec(); + u.extend(dp.to_be_bytes()); + u.extend(((8 + payload.len()) as u16).to_be_bytes()); + u.extend([0, 0]); + u.extend(payload); + u +} + +pub fn tcp(sp: u16, dp: u16, flags: u8, payload: &[u8]) -> Vec { + let mut t = sp.to_be_bytes().to_vec(); + t.extend(dp.to_be_bytes()); + t.extend(1000u32.to_be_bytes()); + t.extend(0u32.to_be_bytes()); + t.extend([0x50, flags, 0xff, 0xff, 0, 0, 0, 0]); + t.extend(payload); + t +} + +/// DNS response for example.com A 93.184.216.34 (name compressed in the answer). +pub fn dns_response() -> Vec { + let mut m = vec![0x12, 0x34, 0x81, 0x80, 0, 1, 0, 1, 0, 0, 0, 0]; + m.extend(b"\x07example\x03com\x00\x00\x01\x00\x01"); + m.extend([0xc0, 12, 0, 1, 0, 1, 0, 0, 0x0e, 0x10, 0, 4, 93, 184, 216, 34]); + m +} + +pub fn dns_query() -> Vec { + let mut m = vec![0x12, 0x34, 0x01, 0x00, 0, 1, 0, 0, 0, 0, 0, 0]; + m.extend(b"\x07example\x03com\x00\x00\x01\x00\x01"); + m +} + +/// A TLS 1.3-style ClientHello naming `host` with ALPN h2 and http/1.1. +pub fn client_hello(host: &str) -> Vec { + let mut ext = Vec::new(); + let mut sni = vec![0u8]; + sni.extend((host.len() as u16).to_be_bytes()); + sni.extend(host.as_bytes()); + let mut sni_list = (sni.len() as u16).to_be_bytes().to_vec(); + sni_list.extend(sni); + ext.extend(0u16.to_be_bytes()); + ext.extend((sni_list.len() as u16).to_be_bytes()); + ext.extend(sni_list); + let alpn_list = b"\x02h2\x08http/1.1"; + ext.extend(16u16.to_be_bytes()); + ext.extend(((alpn_list.len() + 2) as u16).to_be_bytes()); + ext.extend((alpn_list.len() as u16).to_be_bytes()); + ext.extend(alpn_list); + ext.extend(43u16.to_be_bytes()); + ext.extend(5u16.to_be_bytes()); + ext.extend([4, 0x03, 0x04, 0x03, 0x03]); + let mut body = vec![3, 3]; + body.extend([7u8; 32]); + body.push(0); // session id + body.extend([0, 2, 0x13, 0x01]); // one cipher suite + body.extend([1, 0]); // compression + body.extend((ext.len() as u16).to_be_bytes()); + body.extend(ext); + let mut hs = vec![1]; + hs.extend(&(body.len() as u32).to_be_bytes()[1..]); + hs.extend(body); + let mut rec = vec![22, 3, 1]; + rec.extend((hs.len() as u16).to_be_bytes()); + rec.extend(hs); + rec +} + +/// Frames of a small conversation, as (link type 1) Ethernet frames. +pub fn sample_frames() -> Vec> { + let c = [192, 168, 1, 10]; + let dns_srv = [8, 8, 8, 8]; + let web = [93, 184, 216, 34]; + vec![ + eth(0x0800, &ipv4_pkt(17, c, dns_srv, &udp(50000, 53, &dns_query()))), + eth(0x0800, &ipv4_pkt(17, dns_srv, c, &udp(53, 50000, &dns_response()))), + eth(0x0800, &ipv4_pkt(6, c, web, &tcp(50001, 443, 0x02, &[]))), + eth(0x0800, &ipv4_pkt(6, web, c, &tcp(443, 50001, 0x12, &[]))), + eth(0x0800, &ipv4_pkt(6, c, web, &tcp(50001, 443, 0x18, &client_hello("example.com")))), + eth( + 0x0800, + &ipv4_pkt(6, c, web, &tcp(50002, 80, 0x18, b"GET http://user:pw@example.com/a?b=1 HTTP/1.1\r\nHost: example.com\r\nUser-Agent: t\r\n\r\n")), + ), + eth(0x0806, &[0u8; 28]), + ] +} + +/// A classic little-endian microsecond pcap of `frames`. +pub fn pcap(frames: &[Vec]) -> Vec { + let mut out = CLASSIC_US.to_le_bytes().to_vec(); + out.extend(2u16.to_le_bytes()); + out.extend(4u16.to_le_bytes()); + out.extend([0u8; 8]); + out.extend(65535u32.to_le_bytes()); + out.extend(1u32.to_le_bytes()); + for (i, f) in frames.iter().enumerate() { + out.extend((1_700_000_000u32 + i as u32).to_le_bytes()); + out.extend(500u32.to_le_bytes()); + out.extend((f.len() as u32).to_le_bytes()); + out.extend((f.len() as u32).to_le_bytes()); + out.extend(f); + } + out +} + +pub fn block(t: u32, body: &[u8]) -> Vec { + let mut body = body.to_vec(); + while body.len() % 4 != 0 { + body.push(0); + } + let len = (body.len() + 12) as u32; + let mut b = t.to_le_bytes().to_vec(); + b.extend(len.to_le_bytes()); + b.extend(body); + b.extend(len.to_le_bytes()); + b +} + +/// A little-endian pcapng with one Ethernet interface at nanosecond resolution. +pub fn pcapng(frames: &[Vec]) -> Vec { + let mut shb = NG_BOM.to_le_bytes().to_vec(); + shb.extend(1u16.to_le_bytes()); + shb.extend(0u16.to_le_bytes()); + shb.extend((-1i64).to_le_bytes()); + let mut out = block(NG_SHB, &shb); + let mut idb = 1u16.to_le_bytes().to_vec(); + idb.extend([0, 0]); + idb.extend(0u32.to_le_bytes()); + idb.extend([9, 0, 1, 0, 9, 0, 0, 0, 0, 0, 0, 0]); // if_tsresol = 9, end of options + out.extend(block(1, &idb)); + for (i, f) in frames.iter().enumerate() { + let ts: u64 = 1_700_000_000_000_000_000 + i as u64; + let mut epb = 0u32.to_le_bytes().to_vec(); + epb.extend(((ts >> 32) as u32).to_le_bytes()); + epb.extend((ts as u32).to_le_bytes()); + epb.extend((f.len() as u32).to_le_bytes()); + epb.extend((f.len() as u32).to_le_bytes()); + epb.extend(f); + out.extend(block(6, &epb)); + } + out +} From 84df0cd3fb2a65ce46cf966aa9efdc8a6da1ec8e Mon Sep 17 00:00:00 2001 From: phatloi0010 Date: Tue, 17 Nov 2026 08:37:42 -0500 Subject: [PATCH 22/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 34216be702a74e817fd70cad78ecfeaeac49969c. --- crates/pcap/src/lib.rs | 44 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 62698612d..9f637aa31 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -33,6 +33,9 @@ pub struct Interface { /// Timestamp units per second, as a power: (base 10 or 2, exponent). #[serde(skip)] tsresol: (u8, u8), + /// Signed offset in seconds added to timestamps on this interface (`if_tsoffset`). + #[serde(skip)] + tsoffset: i64, } /// The plain name of a link-layer type. @@ -96,6 +99,10 @@ fn rd_u32(r: &Reader<'_>, le: bool, off: usize) -> Option { if le { r.u32_le(off) } else { r.u32_be(off) } } +fn rd_i64(r: &Reader<'_>, le: bool, off: usize) -> Option { + if le { r.u64_le(off) } else { r.u64_be(off) }.map(|v| v as i64) +} + /// True when the bytes start like a pcap or pcapng file. pub fn is_capture(data: &[u8]) -> bool { let r = Reader::new(data); @@ -127,7 +134,8 @@ impl<'a> Capture<'a> { // The top bits of the link field can carry FCS information; the type is the low 28 bits. let link = rd_u32(&r, le, 20).ok_or_else(|| FormatError::Truncated("pcap header".into()))? & 0x0fff_ffff; let res = if nanos { (10, 9) } else { (10, 6) }; - Ok((Kind::Classic { le, nanos }, format!("{major}.{minor}"), Interface { link_type: link, link_name: link_name(link), snaplen, tsresol: res })) + let iface = Interface { link_type: link, link_name: link_name(link), snaplen, tsresol: res, tsoffset: 0 }; + Ok((Kind::Classic { le, nanos }, format!("{major}.{minor}"), iface)) }; match (magic_le, magic_be) { (CLASSIC_US, _) | (_, CLASSIC_US) | (CLASSIC_NS, _) | (_, CLASSIC_NS) => { @@ -162,12 +170,14 @@ impl<'a> Capture<'a> { fn ts(&self, iface: usize, units: u64) -> Option { let (base, exp) = self.interfaces.get(iface).map(|i| i.tsresol).unwrap_or((10, 6)); + let offset_s = self.interfaces.get(iface).map(|i| i.tsoffset).unwrap_or(0); let ns = if base == 10 { if exp <= 9 { u128::from(units) * 10u128.pow(u32::from(9 - exp)) } else { u128::from(units) / 10u128.checked_pow(u32::from(exp - 9))? } } else { (u128::from(units) * 1_000_000_000) >> exp.min(127) }; - u64::try_from(ns).ok() + let adjusted = i128::try_from(ns).ok()?.checked_add(i128::from(offset_s) * 1_000_000_000)?; + u64::try_from(adjusted).ok() } fn frame(&mut self, iface: usize, ts_units: u64, data: &'a [u8], original_len: u32) -> Frame<'a> { @@ -231,6 +241,7 @@ impl<'a> Capture<'a> { let link = u32::from(rd_u16(&r, le, body).unwrap_or(u16::MAX)); let snaplen = rd_u32(&r, le, body + 4).unwrap_or(0); let mut tsresol = (10u8, 6u8); + let mut tsoffset = 0i64; let mut o = body + 8; while o + 4 <= body_end { let (Some(code), Some(len)) = (rd_u16(&r, le, o), rd_u16(&r, le, o + 2)) else { break }; @@ -239,13 +250,20 @@ impl<'a> Capture<'a> { } if code == 9 && len == 1 + && o + 5 <= body_end && let Some(v) = r.u8(o + 4) { tsresol = if v & 0x80 == 0 { (10, v) } else { (2, v & 0x7f) }; + } else if code == 14 + && len == 8 + && o + 12 <= body_end + && let Some(v) = rd_i64(&r, le, o + 4) + { + tsoffset = v; } o += 4 + usize::from(len).div_ceil(4) * 4; } - self.interfaces.push(Interface { link_type: link, link_name: link_name(link), snaplen, tsresol }); + self.interfaces.push(Interface { link_type: link, link_name: link_name(link), snaplen, tsresol, tsoffset }); } 6 | 2 => { let (iface, hi, lo, cap, orig) = if btype == 6 { @@ -1222,6 +1240,26 @@ mod tests { assert_eq!(iso8601(0), "1970-01-01T00:00:00.000000000Z"); } + #[test] + fn pcapng_interface_tsoffset_adjusts_timestamps() { + let base = pcapng(&sample_frames()); + for offset_s in [3600i64, -50i64] { + let mut data = base[..52].to_vec(); + data.extend(14u16.to_le_bytes()); + data.extend(8u16.to_le_bytes()); + data.extend(offset_s.to_le_bytes()); + data.extend(&base[52..]); + data[32..36].copy_from_slice(&44u32.to_le_bytes()); + data[68..72].copy_from_slice(&44u32.to_le_bytes()); + let expected0 = (1_700_000_000_000_000_000i128 + i128::from(offset_s) * 1_000_000_000) as u64; + let frames: Vec<_> = Capture::new(&data).unwrap().collect(); + assert_eq!(frames[0].ts_ns, Some(expected0)); + let s = summarize(&data, &|| false).unwrap(); + assert_eq!((s.first_ts_ns, s.last_ts_ns), (Some(expected0), Some(expected0 + 6))); + assert_eq!((s.flows[0].first_ts_ns, s.flows[0].last_ts_ns), (Some(expected0), Some(expected0 + 1))); + } + } + #[test] fn ipv6_sll_and_raw_links() { let mut v6 = vec![0x60, 0, 0, 0]; From 969444e8d9c763dbb124a7af327d7e6556ee589f Mon Sep 17 00:00:00 2001 From: GGWA <65288322+rech4210@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:43 -0500 Subject: [PATCH 23/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything c217cd6f99616cd87443987a1718828d696b66d4. --- crates/pcap/src/lib.rs | 85 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 2 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 9f637aa31..60404db3e 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -131,8 +131,8 @@ impl<'a> Capture<'a> { let major = rd_u16(&r, le, 4).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; let minor = rd_u16(&r, le, 6).unwrap_or(0); let snaplen = rd_u32(&r, le, 16).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; - // The top bits of the link field can carry FCS information; the type is the low 28 bits. - let link = rd_u32(&r, le, 20).ok_or_else(|| FormatError::Truncated("pcap header".into()))? & 0x0fff_ffff; + // Link type: bits 0–15; reserved: 16–25 and 27; FCS-present: 26; FCS length in 16-bit words: 28–31. + let link = rd_u32(&r, le, 20).ok_or_else(|| FormatError::Truncated("pcap header".into()))? & 0xffff; let res = if nanos { (10, 9) } else { (10, 6) }; let iface = Interface { link_type: link, link_name: link_name(link), snaplen, tsresol: res, tsoffset: 0 }; Ok((Kind::Classic { le, nanos }, format!("{major}.{minor}"), iface)) @@ -1187,6 +1187,87 @@ mod tests { use super::*; use craft_anything_testkit::pcap::{dns_query, pcap, pcapng, sample_frames, udp}; + fn classic_link_word(link_word: u32, le: bool, nanos: bool, trailer: usize) { + let link = link_word & 0xffff; + let mut frame = sample_frames()[1].clone(); + if link == 101 { + frame.drain(..14); + } + frame.extend(vec![0xab; trailer]); + let word = |v: u32| if le { v.to_le_bytes() } else { v.to_be_bytes() }; + let short = |v: u16| if le { v.to_le_bytes() } else { v.to_be_bytes() }; + let mut data = word(if nanos { CLASSIC_NS } else { CLASSIC_US }).to_vec(); + data.extend(short(2)); + data.extend(short(4)); + data.extend([0; 8]); + data.extend(word(65535)); + data.extend(word(link_word)); + data.extend(word(1_700_000_000)); + data.extend(word(500)); + data.extend(word(frame.len() as u32)); + data.extend(word(frame.len() as u32)); + data.extend(&frame); + + let mut cap = Capture::new(&data).unwrap(); + assert_eq!(cap.interfaces[0].link_type, link); + assert_eq!(cap.interfaces[0].link_name, if link == 1 { "Ethernet" } else { "raw IP" }); + let packet = cap.next().unwrap(); + assert_eq!(packet.link_type, link); + assert_eq!(packet.data, frame); + assert_eq!(packet.ts_ns, Some(1_700_000_000_000_000_000 + if nanos { 500 } else { 500_000 })); + let d = decode(packet.link_type, packet.data); + assert_eq!(d.stack(), if link == 1 { "eth:ipv4:udp:dns" } else { "raw:ipv4:udp:dns" }); + let ip = d.ip.unwrap(); + assert_eq!(ip.src.to_string(), "8.8.8.8"); + assert_eq!(ip.dst.to_string(), "192.168.1.10"); + let dns = d.dns.unwrap(); + assert!(dns.response); + assert_eq!(dns.answers[0].value, "93.184.216.34"); + assert!(cap.next().is_none()); + + let s = summarize(&data, &|| false).unwrap(); + assert_eq!(s.packets, 1); + assert_eq!(s.undecoded_frames, 0); + assert_eq!(s.dns_answers[0].value, "example.com A 93.184.216.34"); + assert_eq!(s.flows[0].protocol, "udp"); + assert!(s.warnings.is_empty()); + } + + #[test] + fn fcs_bits_do_not_change_the_ethernet_link_type() { + classic_link_word(0x24000001, true, false, 4); + } + + #[test] + fn fcs_bits_are_masked_in_big_endian_files() { + classic_link_word(0x24000001, false, false, 4); + } + + #[test] + fn fcs_bits_are_masked_in_nanosecond_files() { + classic_link_word(0x24000001, true, true, 4); + } + + #[test] + fn a_one_word_fcs_length_is_masked() { + classic_link_word(0x14000001, true, false, 2); + } + + #[test] + fn fcs_bits_do_not_change_the_raw_ip_link_type() { + classic_link_word(0x24000065, true, false, 4); + } + + #[test] + fn ethernet_without_fcs_bits_still_decodes() { + classic_link_word(1, true, false, 0); + } + + #[test] + fn raw_ip_without_fcs_bits_still_decodes() { + classic_link_word(101, true, false, 0); + } + #[test] fn decodes_dns_tls_http() { let frames = sample_frames(); From f8837751e3d773782e0d93defba67e95cfb67dd6 Mon Sep 17 00:00:00 2001 From: BFlat Date: Tue, 17 Nov 2026 08:37:44 -0500 Subject: [PATCH 24/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything e56379f062cdbfe77c51d379a5825374227c61f7. --- crates/pcap/src/lib.rs | 66 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 60404db3e..c017cfa6e 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -781,10 +781,27 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { (28, 16) => Ipv6Addr::from(<[u8; 16]>::try_from(rd).unwrap_or([0; 16])).to_string(), (2 | 5 | 12, _) => dns_name(msg, rd_off).map(|(n, _)| n).unwrap_or_default(), (15, _) => dns_name(msg, rd_off + 2).map(|(n, _)| n).unwrap_or_default(), - (16, _) => rd - .get(1..) - .map(|t| String::from_utf8_lossy(t.get(..usize::from(rd.first().copied().unwrap_or(0))).unwrap_or(t)).into_owned()) - .unwrap_or_default(), + (16, _) => { + // RFC 1035 §3.3.14: one TXT RDATA holds any number of + // length-prefixed character strings, and a zero-length + // string does not end the record. Consumers join them all + // (RFC 7208 §3.3), so keep every string instead of the + // first one and skip the rest of the RDATA. + let mut txt = String::new(); + let mut pos = 0; + while let Some(&len) = rd.get(pos) { + let len = usize::from(len); + let end = (pos + 1).saturating_add(len).min(rd.len()); + match rd.get(pos + 1..end) { + Some(part) => { + txt.push_str(&String::from_utf8_lossy(part)); + pos = end; + } + None => break, + } + } + txt + } (_, n) => format!("<{n} bytes>"), }; out.answers.push(DnsAnswer { name, rtype: qtype_name(rt), ttl, value }); @@ -1185,7 +1202,46 @@ pub fn iso8601(ns: u64) -> String { #[cfg(test)] mod tests { use super::*; - use craft_anything_testkit::pcap::{dns_query, pcap, pcapng, sample_frames, udp}; + use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp}; + + /// One-answer DNS response for `example.com` with a TXT answer carrying `rdata`. + fn txt_response(rdata: &[u8]) -> Vec { + let mut m = vec![0x12, 0x34, 0x81, 0x80, 0, 1, 0, 1, 0, 0, 0, 0]; + m.extend(b"\x07example\x03com\x00\x00\x01\x00\x01"); + m.extend([0xc0, 12, 0, 16, 0, 1, 0, 0, 0x00, 0x3c]); + m.extend((rdata.len() as u16).to_be_bytes()); + m.extend(rdata); + m + } + + #[test] + fn dns_txt_answer_keeps_every_character_string() { + // RFC 1035 §3.3.14: one TXT RDATA holds any number of length-prefixed + // character strings. Only the first used to survive (issue #330). + let rdata = [ + 5, b'f', b'i', b'r', b's', b't', // "first" + 6, b's', b'e', b'c', b'o', b'n', b'd', // "second" + ]; + let frame = eth(0x0800, &ipv4_pkt(17, [8, 8, 8, 8], [192, 168, 1, 10], &udp(53, 50000, &txt_response(&rdata)))); + let d = decode(1, &frame); + let dns = d.dns.unwrap(); + assert_eq!(dns.answers.len(), 1); + assert_eq!(dns.answers[0].rtype, "TXT"); + assert_eq!(dns.answers[0].value, "firstsecond"); + assert!(!dns.incomplete); + } + + #[test] + fn dns_txt_empty_first_string_keeps_later_content() { + // A zero-length character string does not end the record. + let rdata = [0, 6, b's', b'e', b'c', b'o', b'n', b'd']; + let frame = eth(0x0800, &ipv4_pkt(17, [8, 8, 8, 8], [192, 168, 1, 10], &udp(53, 50000, &txt_response(&rdata)))); + let d = decode(1, &frame); + let dns = d.dns.unwrap(); + assert_eq!(dns.answers.len(), 1); + assert_eq!(dns.answers[0].value, "second"); + assert!(!dns.incomplete); + } fn classic_link_word(link_word: u32, le: bool, nanos: bool, trailer: usize) { let link = link_word & 0xffff; From 013cc27059b42c43286b82166fdf7f349e661f9d Mon Sep 17 00:00:00 2001 From: Afloat <132809511+Afloat16@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:44 -0500 Subject: [PATCH 25/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything e3d95b43000e947e97abb6c4601644dc1e18c388. --- crates/pcap/src/lib.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index c017cfa6e..866f3b013 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1304,6 +1304,18 @@ mod tests { classic_link_word(0x24000001, true, true, 4); } + #[test] + fn fcs_bits_are_masked_in_big_endian_nanosecond_files() { + classic_link_word(0x24000001, false, true, 4); + classic_link_word(1, false, true, 0); + } + + #[test] + fn fcs_bits_do_not_change_big_endian_nanosecond_raw_ip() { + classic_link_word(0x24000065, false, true, 4); + classic_link_word(101, false, true, 0); + } + #[test] fn a_one_word_fcs_length_is_masked() { classic_link_word(0x14000001, true, false, 2); From 98fa4f5dc6fb4d216359efac3825ca26aedfe1af Mon Sep 17 00:00:00 2001 From: NetterSilver <133535268+Silvertree2010@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:45 -0500 Subject: [PATCH 26/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 493c20f414ab7a6860953319eb0225a64ef25932. --- crates/pcap/src/lib.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 866f3b013..9c3e6ae8b 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1091,8 +1091,10 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result Date: Tue, 17 Nov 2026 08:37:45 -0500 Subject: [PATCH 27/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything b0003d7ab2a7c3f3c727cfc2a426fcbd16e65e99. --- crates/pcap/src/lib.rs | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 9c3e6ae8b..5922f6f95 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -634,22 +634,24 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { }; match proto { 6 => { - let (Some(sp), Some(dp), Some(seq), Some(ack), Some(off), Some(flags), Some(win)) = - (r.u16_be(0), r.u16_be(2), r.u32_be(4), r.u32_be(8), r.u8(12), r.u8(13), r.u16_be(14)) - else { + let (Some(sp), Some(dp)) = (r.u16_be(0), r.u16_be(2)) else { d.note = Some("TCP header cut short".into()); return; }; d.protocols.push("tcp"); - let payload = p.get(usize::from(off >> 4) * 4..).unwrap_or(&[]); + let (seq, ack, off, flags, win) = (r.u32_be(4), r.u32_be(8), r.u8(12), r.u8(13), r.u16_be(14)); + if win.is_none() { + d.note = Some("TCP header cut short".into()); + } + let payload = off.map_or(&[][..], |off| p.get(usize::from(off >> 4) * 4..).unwrap_or(&[])); d.transport = Some(Transport { protocol: "tcp", src_port: Some(sp), dst_port: Some(dp), - tcp_flags: Some(tcp_flags(flags)), - seq: Some(seq), - ack: Some(ack), - window: Some(win), + tcp_flags: flags.map(tcp_flags), + seq, + ack, + window: win, payload_len: payload.len(), ..empty }); @@ -1206,6 +1208,24 @@ mod tests { use super::*; use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp}; + #[test] + fn tcp_cut_inside_header_keeps_ports() { + // Ports sit in the first 4 bytes; a cut later in the header must not drop them (as UDP). + let mut tcp = Vec::new(); + tcp.extend(41000u16.to_be_bytes()); + tcp.extend(9000u16.to_be_bytes()); + tcp.extend([0, 0, 0, 1, 0, 0, 0, 0, 0x50, 0x18, 4, 0, 0, 0, 0, 0]); + let mut frame = eth(0x0800, &ipv4_pkt(6, [10, 0, 0, 1], [10, 0, 0, 2], &tcp)); + frame.truncate(14 + 20 + 11); + let d = decode(1, &frame); + let t = d.transport.unwrap(); + assert_eq!((t.src_port, t.dst_port), (Some(41000), Some(9000))); + assert_eq!(t.seq, Some(1)); + assert_eq!(t.ack, None); + assert_eq!(t.window, None); + assert!(d.protocols.contains(&"tcp")); + } + /// One-answer DNS response for `example.com` with a TXT answer carrying `rdata`. fn txt_response(rdata: &[u8]) -> Vec { let mut m = vec![0x12, 0x34, 0x81, 0x80, 0, 1, 0, 1, 0, 0, 0, 0]; From f14c029eb26240886b41d7e1b3f97bf6f978105e Mon Sep 17 00:00:00 2001 From: NetterSilver <133535268+Silvertree2010@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:46 -0500 Subject: [PATCH 28/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything d0c5feefa761ad98317665b4fc547a5921803a36. --- crates/pcap/src/lib.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 5922f6f95..bb5d6ad7b 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1034,6 +1034,9 @@ pub struct Summary { pub dns_queries: Vec, /// "name TYPE value" from DNS responses. pub dns_answers: Vec, + /// "question A|AAAA address" from DNS responses: each address answered, keyed by the response's first + /// question (so CNAME chains end at the name that was asked), as Wireshark's fields report them. + pub dns_addresses: Vec, /// "METHOD host target" from HTTP/1.x requests. pub http_requests: Vec, /// Server names from TLS ClientHellos. @@ -1082,6 +1085,7 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result = Vec::new(); let (mut protocols, mut stacks, mut endpoints) = (Tally::default(), Tally::default(), Tally::default()); let (mut queries, mut answers, mut http, mut sni, mut alpn) = (Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default()); + let mut addresses = Tally::default(); for f in cap.by_ref() { if f.number % 4096 == 0 && cancelled() { return Err(FormatError::Malformed("cancelled".into())); @@ -1151,6 +1155,13 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result().is_ok()) { + addresses.add(format!("{} {} {}", q.name, a.rtype, a.value)); + } + } } if let Some(h) = &d.http && h.kind == "request" @@ -1175,6 +1186,7 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result Date: Tue, 17 Nov 2026 08:37:46 -0500 Subject: [PATCH 29/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 73f9d5a8d35907362c5945b669bda83435712943. --- crates/pcap/src/lib.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index bb5d6ad7b..f36d5ab8a 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -998,6 +998,8 @@ pub struct Flow { pub bytes: u64, pub packets_a_to_b: u64, pub packets_b_to_a: u64, + pub bytes_a_to_b: u64, + pub bytes_b_to_a: u64, pub first_frame: u64, #[serde(skip_serializing_if = "Option::is_none")] pub first_ts_ns: Option, @@ -1124,6 +1126,8 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result bool) -> Result Date: Tue, 17 Nov 2026 08:37:47 -0500 Subject: [PATCH 30/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 5845227f9f760a116a2a4be9059481134c942de3. --- crates/pcap/src/lib.rs | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index f36d5ab8a..5b9aee530 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -582,25 +582,37 @@ fn ipv6(p: &[u8], d: &mut Decoded) { d.protocols.push("ipv6"); let ip6 = |b: &[u8]| IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(b).unwrap_or([0; 16]))); let end = (40 + usize::from(plen)).min(p.len()); + let payload_reader = Reader::new(p.get(..end).unwrap_or(&[])); let mut off = 40usize; let mut fragment = false; for _ in 0..8 { match next { 0 | 43 | 60 => { - let (Some(n), Some(l)) = (r.u8(off), r.u8(off + 1)) else { break }; + let (Some(n), Some(l)) = (payload_reader.u8(off), payload_reader.u8(off + 1)) else { break }; + let len = (usize::from(l) + 1) * 8; + if off.checked_add(len).is_none_or(|next_off| next_off > end) { + break; + } next = n; - off += (usize::from(l) + 1) * 8; + off += len; } 44 => { - let (Some(n), Some(fo)) = (r.u8(off), r.u16_be(off + 2)) else { break }; + if off.checked_add(8).is_none_or(|next_off| next_off > end) { + break; + } + let (Some(n), Some(fo)) = (payload_reader.u8(off), payload_reader.u16_be(off + 2)) else { break }; next = n; fragment = fo & 0xfff8 != 0; off += 8; } 51 => { - let (Some(n), Some(l)) = (r.u8(off), r.u8(off + 1)) else { break }; + let (Some(n), Some(l)) = (payload_reader.u8(off), payload_reader.u8(off + 1)) else { break }; + let len = (usize::from(l) + 2) * 4; + if off.checked_add(len).is_none_or(|next_off| next_off > end) { + break; + } next = n; - off += (usize::from(l) + 2) * 4; + off += len; } _ => break, } @@ -1473,6 +1485,18 @@ mod tests { } } + #[test] + fn ipv6_extension_outside_declared_payload_is_ignored() { + let mut v6 = vec![0x60, 0, 0, 0]; + v6.extend(0u16.to_be_bytes()); + v6.extend([60, 64]); + v6.extend([0u8; 32]); + v6.extend([17, 0, 0, 0, 0, 0, 0, 0]); + + let d = decode(101, &v6); + assert_eq!(d.ip.unwrap().protocol, 60); + } + #[test] fn ipv6_sll_and_raw_links() { let mut v6 = vec![0x60, 0, 0, 0]; From 7a5c99810f0b5f3b07085494fe2d780859a8742e Mon Sep 17 00:00:00 2001 From: BFlat Date: Tue, 17 Nov 2026 08:37:48 -0500 Subject: [PATCH 31/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything b9ca099903aeef5d4b33a7e83e8e7062ab94c65a. --- crates/pcap/src/lib.rs | 202 ++++++++++++++---- .../pcap/tests/regression_pcapng_framing.rs | 66 ++++++ .../pcap/tests/regression_tcp_dns_framing.rs | 67 ++++++ .../tests/regression_tcp_header_length.rs | 52 +++++ crates/pcap/tests/regression_tls_bounds.rs | 102 +++++++++ 5 files changed, 445 insertions(+), 44 deletions(-) create mode 100644 crates/pcap/tests/regression_pcapng_framing.rs create mode 100644 crates/pcap/tests/regression_tcp_dns_framing.rs create mode 100644 crates/pcap/tests/regression_tcp_header_length.rs create mode 100644 crates/pcap/tests/regression_tls_bounds.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 5b9aee530..809908396 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -224,15 +224,27 @@ impl<'a> Capture<'a> { _ if r.u32_be(p + 8) == Some(NG_BOM) => false, _ => return self.stop(format!("section header at offset {p} has no byte-order mark")), }; - self.kind = Kind::Ng { le }; - self.section_base = self.interfaces.len(); } let Some(blen) = rd_u32(&r, le, p + 4).and_then(|v| usize::try_from(v).ok()) else { return self.stop(format!("block at offset {p} is cut short")); }; - if blen < 12 || blen % 4 != 0 || r.slice(p, blen).is_none() { + let minimum = match btype { + NG_SHB => 28, + 1 => 20, + 2 | 6 => 32, + 3 => 16, + _ => 12, + }; + if blen < minimum || blen % 4 != 0 || r.slice(p, blen).is_none() { return self.stop(format!("block at offset {p} has an impossible length {blen}")); } + if rd_u32(&r, le, p + blen - 4).and_then(|n| usize::try_from(n).ok()) != Some(blen) { + return self.stop(format!("block at offset {p} has an inconsistent trailing length")); + } + if btype == NG_SHB { + self.kind = Kind::Ng { le }; + self.section_base = self.interfaces.len(); + } self.pos = p + blen; let body = p + 8; let body_end = p + blen - 4; @@ -652,10 +664,17 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { }; d.protocols.push("tcp"); let (seq, ack, off, flags, win) = (r.u32_be(4), r.u32_be(8), r.u8(12), r.u8(13), r.u16_be(14)); - if win.is_none() { - d.note = Some("TCP header cut short".into()); - } - let payload = off.map_or(&[][..], |off| p.get(usize::from(off >> 4) * 4..).unwrap_or(&[])); + let payload = match off.map(|off| usize::from(off >> 4) * 4) { + Some(length) if length < 20 => { + d.note = Some("TCP data offset is smaller than its header".into()); + &[][..] + } + Some(length) if length <= p.len() => p.get(length..).unwrap_or(&[]), + _ => { + d.note = Some("TCP header cut short".into()); + &[][..] + } + }; d.transport = Some(Transport { protocol: "tcp", src_port: Some(sp), @@ -667,8 +686,19 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { payload_len: payload.len(), ..empty }); - if (sp == 53 || dp == 53) && payload.len() > 2 { - dns(payload.get(2..).unwrap_or(&[]), d, "dns"); + if (sp == 53 || dp == 53) && !payload.is_empty() { + let framed = Reader::new(payload); + match framed.u16_be(0) { + Some(length) if length < 12 => d.note = Some("DNS over TCP length is smaller than its header".into()), + Some(length) => { + if let Some(message) = framed.slice(2, usize::from(length)) { + dns(message, d, "dns"); + } else { + d.note = Some("DNS over TCP message cut short".into()); + } + } + None => d.note = Some("DNS over TCP length prefix cut short".into()), + } } else if !payload.is_empty() { tcp_app(payload, d); } @@ -679,7 +709,19 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { return; }; d.protocols.push("udp"); - let payload = p.get(8..).unwrap_or(&[]); + let length = r.u16_be(4).map(usize::from).unwrap_or(0); + let payload = if p.len() < 8 { + d.note = Some("UDP header cut short".into()); + &[][..] + } else if length < 8 { + d.note = Some("UDP length is smaller than its header".into()); + &[][..] + } else { + if length > p.len() { + d.note = Some("UDP datagram cut short".into()); + } + p.get(8..length.min(p.len())).unwrap_or(&[]) + }; d.transport = Some(Transport { protocol: "udp", src_port: Some(sp), dst_port: Some(dp), payload_len: payload.len(), ..empty }); if sp == 53 || dp == 53 { dns(payload, d, "dns"); @@ -874,7 +916,11 @@ fn tls(p: &[u8], d: &mut Decoded) { return; } d.protocols.push("tls"); - if ct != 22 || r.u8(5) != Some(1) { + let Some(record_len) = r.u16_be(3) else { return }; + let record_end = 5 + usize::from(record_len); + let record_end_available = record_end.min(p.len()); + let record = Reader::new(p.get(..record_end_available).unwrap_or(&[])); + if ct != 22 || record.u8(5) != Some(1) { return; } let ver = |v: u16| match v { @@ -886,70 +932,138 @@ fn tls(p: &[u8], d: &mut Decoded) { v if v & 0x0f0f == 0x0a0a => "GREASE".into(), v => format!("{v:#06x}"), }; - let mut hello = - TlsHello { record_version: ver(u16::from_be_bytes([major, minor])), sni: None, alpn: Vec::new(), supported_versions: Vec::new(), partial: false }; - // Record header (5) + handshake header (4) + client_version (2) + random (32). - let mut off = 5 + 4 + 2 + 32; - let skip8 = |off: usize| r.u8(off).map(|n| off + 1 + usize::from(n)); - let skip16 = |off: usize| r.u16_be(off).map(|n| off + 2 + usize::from(n)); - let Some(o) = skip8(off).and_then(skip16).and_then(skip8) else { + let mut hello = TlsHello { + record_version: ver(u16::from_be_bytes([major, minor])), + sni: None, + alpn: Vec::new(), + supported_versions: Vec::new(), + partial: record_end > p.len(), + }; + let Some(handshake_header) = record.u32_be(5) else { hello.partial = true; d.tls = Some(hello); return; }; - off = o; + let handshake_end = 9 + (handshake_header & 0x00ff_ffff) as usize; + hello.partial |= handshake_end > record_end_available; + let hello_end = handshake_end.min(record_end_available); + let r = Reader::new(p.get(..hello_end).unwrap_or(&[])); + // Every variable-length field must fit inside this handshake, not merely the packet. + let skip8 = |off: usize| { + let n = usize::from(r.u8(off)?); + r.slice(off + 1, n)?; + Some(off + 1 + n) + }; + let skip16 = |off: usize| { + let n = usize::from(r.u16_be(off)?); + r.slice(off + 2, n)?; + Some(off + 2 + n) + }; + // Record header (5) + handshake header (4) + client_version (2) + random (32). + let Some(off) = skip8(5 + 4 + 2 + 32).and_then(skip16).and_then(skip8) else { + hello.partial = true; + d.tls = Some(hello); + return; + }; + // Extensions are optional in a complete ClientHello through TLS 1.2. + if off == handshake_end && hello_end == handshake_end { + d.tls = Some(hello); + return; + } let Some(ext_len) = r.u16_be(off) else { hello.partial = true; d.tls = Some(hello); return; }; - let end = off + 2 + usize::from(ext_len); - hello.partial = end > p.len(); + let declared_end = off + 2 + usize::from(ext_len); + hello.partial |= declared_end != handshake_end; + let end = declared_end.min(hello_end); + let extensions = Reader::new(p.get(..end).unwrap_or(&[])); let mut e = off + 2; - while e + 4 <= end.min(p.len()) { - let (Some(t), Some(l)) = (r.u16_be(e), r.u16_be(e + 2)) else { break }; + while e + 4 <= end { + let (Some(t), Some(l)) = (extensions.u16_be(e), extensions.u16_be(e + 2)) else { break }; let body = e + 4; - let Some(data) = r.slice(body, usize::from(l)) else { + let Some(data) = extensions.slice(body, usize::from(l)) else { hello.partial = true; break; }; let dr = Reader::new(data); match t { 0 => { - if dr.u8(2) == Some(0) - && let Some(n) = dr.u16_be(3).and_then(|n| dr.slice(5, usize::from(n))) - { - hello.sni = Some(n.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' }).collect()); + if let Some(len) = dr.u16_be(0) { + let list_end = 2 + usize::from(len); + hello.partial |= list_end != data.len(); + let names = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); + let mut a = 2; + while a < list_end.min(data.len()) { + let (Some(kind), Some(len)) = (names.u8(a), names.u16_be(a + 1)) else { + hello.partial = true; + break; + }; + let Some(name) = names.slice(a + 3, usize::from(len)) else { + hello.partial = true; + break; + }; + if kind == 0 { + if name.is_empty() { + hello.partial = true; + } else if hello.sni.is_none() { + hello.sni = Some(name.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' }).collect()); + } + } + a += 3 + usize::from(len); + } + } else { + hello.partial = true; } } 16 => { - let mut a = 2usize; - while let Some(n) = dr.u8(a) { - let Some(proto) = dr.slice(a + 1, usize::from(n)) else { break }; - hello.alpn.push(String::from_utf8_lossy(proto).into_owned()); - a += 1 + usize::from(n); - if hello.alpn.len() >= 16 { - break; + if let Some(len) = dr.u16_be(0) { + let list_end = 2 + usize::from(len); + hello.partial |= list_end != data.len(); + let protocols = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); + let mut a = 2usize; + while a < list_end.min(data.len()) && hello.alpn.len() < 16 { + let Some(n) = protocols.u8(a).filter(|&n| n > 0) else { + hello.partial = true; + break; + }; + let Some(proto) = protocols.slice(a + 1, usize::from(n)) else { + hello.partial = true; + break; + }; + hello.alpn.push(String::from_utf8_lossy(proto).into_owned()); + a += 1 + usize::from(n); } + } else { + hello.partial = true; } } 43 => { - let mut a = 1usize; - while let Some(v) = dr.u16_be(a) { - let name = ver(v); - if name != "GREASE" { - hello.supported_versions.push(name); - } - a += 2; - if hello.supported_versions.len() >= 16 { - break; + if let Some(len) = dr.u8(0) { + let list_end = 1 + usize::from(len); + hello.partial |= list_end != data.len() || len % 2 != 0; + let versions = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); + let mut a = 1usize; + while let Some(v) = versions.u16_be(a) { + let name = ver(v); + if name != "GREASE" { + hello.supported_versions.push(name); + } + a += 2; + if hello.supported_versions.len() >= 16 { + break; + } } + } else { + hello.partial = true; } } _ => {} } e = body + usize::from(l); } + hello.partial |= e != end; d.tls = Some(hello); } diff --git a/crates/pcap/tests/regression_pcapng_framing.rs b/crates/pcap/tests/regression_pcapng_framing.rs new file mode 100644 index 000000000..69a58a6b3 --- /dev/null +++ b/crates/pcap/tests/regression_pcapng_framing.rs @@ -0,0 +1,66 @@ +use craft_anything_formats::pcap::summarize; +use craft_anything_testkit::pcap::{block, pcapng, sample_frames}; + +#[test] +fn mismatched_block_footers_stop_the_capture_with_a_warning() { + let original = pcapng(&sample_frames()); + for footer in [24, 56] { + let mut data = original.clone(); + data[footer..footer + 4].copy_from_slice(&12u32.to_le_bytes()); + let result = summarize(&data, &|| false).unwrap(); + assert!(!result.warnings.is_empty(), "footer at {footer}"); + assert_eq!(result.packets, 0); + } +} + +#[test] +fn fixed_block_headers_cannot_borrow_the_next_blocks_bytes() { + let header = pcapng(&[]); + for (kind, short_body) in [(1, vec![]), (2, vec![0; 16]), (6, vec![0; 16]), (3, vec![])] { + let mut data = header[..28].to_vec(); + if kind != 1 { + data.extend(&header[28..]); + } + data.extend(block(kind, &short_body)); + data.extend(&pcapng(&sample_frames())[28..]); + let result = summarize(&data, &|| false).unwrap(); + assert!(!result.warnings.is_empty(), "kind {kind}"); + assert_eq!(result.packets, 0, "kind {kind}"); + assert_eq!(result.interfaces.len(), usize::from(kind != 1), "kind {kind}"); + } +} + +#[test] +fn valid_blocks_and_unknown_blocks_still_work() { + let original = pcapng(&sample_frames()); + let mut data = original[..60].to_vec(); + data.extend(block(0x0000_1234, b"ignored")); + data.extend(&original[60..]); + let result = summarize(&data, &|| false).unwrap(); + assert_eq!(result.packets, 7); + assert!(result.warnings.is_empty()); + assert_eq!(result.interfaces.len(), 1); +} + +#[test] +fn big_endian_block_footers_use_the_sections_byte_order() { + let be_block = |kind: u32, body: &[u8]| { + let size = (body.len() + 12) as u32; + let mut out = kind.to_be_bytes().to_vec(); + out.extend(size.to_be_bytes()); + out.extend(body); + out.extend(size.to_be_bytes()); + out + }; + let mut section = 0x1a2b3c4du32.to_be_bytes().to_vec(); + section.extend([0, 1, 0, 0]); + section.extend((-1i64).to_be_bytes()); + let mut data = be_block(0x0a0d0d0a, §ion); + data.extend(be_block(1, &[0, 1, 0, 0, 0, 0, 0, 0])); + let result = summarize(&data, &|| false).unwrap(); + assert!(result.warnings.is_empty()); + assert_eq!(result.interfaces[0].link_type, 1); + let end = data.len(); + data[end - 4..].copy_from_slice(&20u32.to_le_bytes()); + assert!(!summarize(&data, &|| false).unwrap().warnings.is_empty()); +} diff --git a/crates/pcap/tests/regression_tcp_dns_framing.rs b/crates/pcap/tests/regression_tcp_dns_framing.rs new file mode 100644 index 000000000..4dad459bb --- /dev/null +++ b/crates/pcap/tests/regression_tcp_dns_framing.rs @@ -0,0 +1,67 @@ +use craft_anything_formats::pcap::{Decoded, decode}; +use craft_anything_testkit::pcap::{dns_query, dns_response, ipv4_pkt, tcp}; + +fn decoded(payload: &[u8]) -> Decoded { + decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(53, 51000, 0x18, payload))) +} + +fn framed(message: &[u8], declared: usize) -> Vec { + let mut payload = (declared as u16).to_be_bytes().to_vec(); + payload.extend(message); + payload +} + +#[test] +fn an_unfinished_dns_message_is_not_reported_complete() { + let message = dns_response(); + let result = decoded(&framed(&message, message.len() + 1)); + assert!(result.dns.is_none()); + assert!(result.note.is_some()); + assert_eq!(result.transport.unwrap().src_port, Some(53)); +} + +#[test] +fn dns_records_cannot_borrow_bytes_past_the_message_length() { + let result = decoded(&framed(&dns_response(), 12)); + let dns = result.dns.unwrap(); + assert!(dns.questions.is_empty() && dns.answers.is_empty()); + assert!(dns.incomplete); +} + +#[test] +fn a_length_smaller_than_the_dns_header_is_rejected() { + for length in 0..12 { + let result = decoded(&framed(&dns_response(), length)); + assert!(result.dns.is_none(), "length {length}"); + assert!(result.note.is_some(), "length {length}"); + } +} + +#[test] +fn a_partial_dns_length_prefix_is_reported() { + let result = decoded(&[0]); + assert!(result.dns.is_none()); + assert!(result.note.is_some()); +} + +#[test] +fn an_empty_tcp_ack_does_not_claim_a_missing_dns_message() { + let result = decoded(&[]); + assert!(result.dns.is_none()); + assert!(result.note.is_none()); + assert_eq!(result.transport.unwrap().payload_len, 0); +} + +#[test] +fn the_first_complete_dns_message_is_decoded_without_the_next_one() { + let first = dns_query(); + let second = dns_response(); + let mut payload = framed(&first, first.len()); + payload.extend(framed(&second, second.len())); + let result = decoded(&payload); + let dns = result.dns.unwrap(); + assert!(!dns.response && !dns.incomplete); + assert_eq!(dns.questions[0].name, "example.com"); + assert!(dns.answers.is_empty()); + assert!(result.note.is_none()); +} diff --git a/crates/pcap/tests/regression_tcp_header_length.rs b/crates/pcap/tests/regression_tcp_header_length.rs new file mode 100644 index 000000000..189318116 --- /dev/null +++ b/crates/pcap/tests/regression_tcp_header_length.rs @@ -0,0 +1,52 @@ +use craft_anything_formats::pcap::{Decoded, decode}; +use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; + +fn decoded(segment: &[u8]) -> Decoded { + decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], segment)) +} + +#[test] +fn a_tcp_header_shorter_than_twenty_bytes_is_not_payload() { + for words in 0..5u8 { + let mut segment = tcp(51000, 80, 0x18, b"GET / HTTP/1.1\r\n\r\n"); + segment[12] = words << 4; + let result = decoded(&segment); + let transport = result.transport.unwrap(); + assert_eq!(transport.payload_len, 0, "offset {words}"); + assert_eq!((transport.src_port, transport.dst_port), (Some(51000), Some(80))); + assert!(result.http.is_none() && result.tls.is_none()); + assert!(result.note.is_some()); + } +} + +#[test] +fn a_cut_tcp_header_keeps_ports_but_reports_the_cut() { + let whole = tcp(51000, 80, 0x18, b"request"); + for end in 4..20 { + let result = decoded(&whole[..end]); + let transport = result.transport.unwrap(); + assert_eq!((transport.src_port, transport.dst_port), (Some(51000), Some(80))); + assert_eq!(transport.payload_len, 0); + assert!(result.note.is_some(), "cut at {end}"); + } + for words in 6..=15u8 { + let mut segment = tcp(51000, 80, 0x18, &[]); + segment[12] = words << 4; + let result = decoded(&segment); + assert_eq!(result.transport.unwrap().payload_len, 0); + assert!(result.note.is_some(), "missing options for offset {words}"); + } +} + +#[test] +fn a_valid_tcp_header_with_options_finds_its_payload() { + let mut segment = tcp(51000, 80, 0x18, &[]); + segment[12] = 7 << 4; + segment.extend([1; 8]); + let payload = b"GET /resource HTTP/1.1\r\nHost: example.test\r\n\r\n"; + segment.extend(payload); + let result = decoded(&segment); + assert_eq!(result.transport.unwrap().payload_len, payload.len()); + assert_eq!(result.http.unwrap().target.as_deref(), Some("/resource")); + assert!(result.note.is_none()); +} diff --git a/crates/pcap/tests/regression_tls_bounds.rs b/crates/pcap/tests/regression_tls_bounds.rs new file mode 100644 index 000000000..674ff7942 --- /dev/null +++ b/crates/pcap/tests/regression_tls_bounds.rs @@ -0,0 +1,102 @@ +use craft_anything_formats::pcap::{Decoded, decode}; +use craft_anything_testkit::pcap::{client_hello, ipv4_pkt, tcp}; + +fn decoded(record: &[u8]) -> Decoded { + decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(51000, 443, 0x18, record))) +} + +fn assert_no_complete_sni(record: &[u8]) { + let result = decoded(record); + assert!(result.protocols.contains(&"tls")); + assert!(result.tls.is_none_or(|hello| hello.sni.is_none() && hello.partial)); +} + +#[test] +fn a_client_hello_cannot_read_past_its_tls_record() { + let mut record = client_hello("example.test"); + record[3..5].copy_from_slice(&4u16.to_be_bytes()); + assert_no_complete_sni(&record); +} + +#[test] +fn a_client_hello_cannot_read_past_its_handshake() { + let mut record = client_hello("example.test"); + record[6..9].copy_from_slice(&[0, 0, 34]); + assert_no_complete_sni(&record); +} + +#[test] +fn extensions_cannot_read_past_the_declared_extension_list() { + let mut record = client_hello("example.test"); + record[50..52].copy_from_slice(&4u16.to_be_bytes()); + assert_no_complete_sni(&record); +} + +#[test] +fn a_truncated_record_reports_partial_even_when_the_hello_fields_fit() { + let mut record = client_hello("example.test"); + let larger = (record.len() + 20) as u16; + record[3..5].copy_from_slice(&larger.to_be_bytes()); + assert!(decoded(&record).tls.unwrap().partial); +} + +#[test] +fn server_names_stay_inside_the_name_list() { + let mut record = client_hello("example.test"); + record[56..58].copy_from_slice(&3u16.to_be_bytes()); + assert_no_complete_sni(&record); +} + +#[test] +fn alpn_names_stay_inside_the_protocol_list() { + let mut record = client_hello("example.test"); + let alpn_list = 52 + 4 + 5 + "example.test".len() + 4; + record[alpn_list..alpn_list + 2].copy_from_slice(&3u16.to_be_bytes()); + let hello = decoded(&record).tls.unwrap(); + assert_eq!(hello.alpn, ["h2"]); + assert!(hello.partial); +} + +#[test] +fn supported_versions_stay_inside_the_version_list() { + let mut record = client_hello("example.test"); + let versions = 52 + 4 + 5 + "example.test".len() + 4 + 14 + 4; + record[versions] = 2; + let hello = decoded(&record).tls.unwrap(); + assert_eq!(hello.supported_versions, ["TLS 1.3"]); + assert!(hello.partial); +} + +#[test] +fn a_complete_legacy_hello_can_omit_extensions() { + let mut record = client_hello("example.test"); + record.truncate(50); + record[3..5].copy_from_slice(&45u16.to_be_bytes()); + record[6..9].copy_from_slice(&[0, 0, 41]); + record[46..48].copy_from_slice(&0x002fu16.to_be_bytes()); + let hello = decoded(&record).tls.unwrap(); + assert!(hello.sni.is_none() && hello.alpn.is_empty() && hello.supported_versions.is_empty()); + assert!(!hello.partial); +} + +#[test] +fn a_following_handshake_does_not_extend_the_first_hello() { + let mut record = client_hello("example.test"); + record.extend([14, 0, 0, 0]); + let record_len = (record.len() - 5) as u16; + record[3..5].copy_from_slice(&record_len.to_be_bytes()); + let hello = decoded(&record).tls.unwrap(); + assert_eq!(hello.sni.as_deref(), Some("example.test")); + assert_eq!(hello.alpn, ["h2", "http/1.1"]); + assert!(!hello.partial); +} + +#[test] +fn complete_hello_metadata_is_unchanged() { + let record = client_hello("example.test"); + let hello = decoded(&record).tls.unwrap(); + assert_eq!(hello.sni.as_deref(), Some("example.test")); + assert_eq!(hello.alpn, ["h2", "http/1.1"]); + assert_eq!(hello.supported_versions, ["TLS 1.3", "TLS 1.2"]); + assert!(!hello.partial); +} From 9ecd830f68dea89eee60ba072da9148f6dd2aa79 Mon Sep 17 00:00:00 2001 From: BFlat Date: Tue, 17 Nov 2026 08:37:49 -0500 Subject: [PATCH 32/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 60409b684c805482cfa3965fbc368bcc26de106d. --- crates/pcap/src/lib.rs | 248 +++++++++++++++---- crates/pcap/tests/dns_question_class.rs | 55 ++++ crates/pcap/tests/dns_rdata_names.rs | 184 ++++++++++++++ crates/pcap/tests/pcap_dns_name_limit.rs | 151 +++++++++++ crates/pcap/tests/pcap_dns_txt_lengths.rs | 196 +++++++++++++++ crates/pcap/tests/pcap_flow_time_range.rs | 36 +++ crates/pcap/tests/pcap_http_host_boundary.rs | 24 ++ crates/pcap/tests/pcap_ipv4_lengths.rs | 57 +++++ crates/pcap/tests/pcap_ipv6_fragments.rs | 40 +++ crates/pcap/tests/pcap_ipv6_version.rs | 53 ++++ crates/pcap/tests/pcapng_simple_payload.rs | 62 +++++ 11 files changed, 1061 insertions(+), 45 deletions(-) create mode 100644 crates/pcap/tests/dns_question_class.rs create mode 100644 crates/pcap/tests/dns_rdata_names.rs create mode 100644 crates/pcap/tests/pcap_dns_name_limit.rs create mode 100644 crates/pcap/tests/pcap_dns_txt_lengths.rs create mode 100644 crates/pcap/tests/pcap_flow_time_range.rs create mode 100644 crates/pcap/tests/pcap_http_host_boundary.rs create mode 100644 crates/pcap/tests/pcap_ipv4_lengths.rs create mode 100644 crates/pcap/tests/pcap_ipv6_fragments.rs create mode 100644 crates/pcap/tests/pcap_ipv6_version.rs create mode 100644 crates/pcap/tests/pcapng_simple_payload.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 809908396..d82dc8fea 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -12,7 +12,7 @@ use serde::Serialize; use std::collections::{BTreeMap, BTreeSet, HashMap}; use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; -/// Most frames read from one capture. +/// Most frames and rejected simple packet blocks read from one capture. pub const MAX_PACKETS: u64 = 5_000_000; /// Most flows tracked; later flows are counted but get no id. pub const MAX_FLOWS: usize = 100_000; @@ -89,6 +89,8 @@ pub struct Capture<'a> { /// The walk stopped at `MAX_PACKETS`. pub truncated: bool, count: u64, + rejected_simple_blocks: u64, + rejected_simple_reported: bool, } fn rd_u16(r: &Reader<'_>, le: bool, off: usize) -> Option { @@ -126,6 +128,8 @@ impl<'a> Capture<'a> { warnings: Vec::new(), truncated: false, count: 0, + rejected_simple_blocks: 0, + rejected_simple_reported: false, }; let classic = |le: bool, nanos: bool| -> Result<(Kind, String, Interface), FormatError> { let major = rd_u16(&r, le, 4).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; @@ -168,6 +172,26 @@ impl<'a> Capture<'a> { None } + fn packet_limit_reached(&mut self) -> bool { + if self.count.saturating_add(self.rejected_simple_blocks) < MAX_PACKETS { + return false; + } + if !self.truncated && self.pos < self.data.len() { + self.truncated = true; + self.warnings.push(format!("stopped after {MAX_PACKETS} packet records")); + } + true + } + + fn report_rejected_simple_blocks(&mut self) { + if self.rejected_simple_blocks > 0 && !self.rejected_simple_reported { + let n = self.rejected_simple_blocks; + let suffix = if n == 1 { "" } else { "s" }; + self.warnings.push(format!("skipped {n} simple packet block{suffix} with inconsistent captured lengths")); + self.rejected_simple_reported = true; + } + } + fn ts(&self, iface: usize, units: u64) -> Option { let (base, exp) = self.interfaces.get(iface).map(|i| i.tsresol).unwrap_or((10, 6)); let offset_s = self.interfaces.get(iface).map(|i| i.tsoffset).unwrap_or(0); @@ -211,6 +235,9 @@ impl<'a> Capture<'a> { fn next_ng(&mut self, mut le: bool) -> Option> { loop { + if self.packet_limit_reached() { + return None; + } let r = Reader::new(self.data); let p = self.pos; if p >= self.data.len() { @@ -312,7 +339,11 @@ impl<'a> Capture<'a> { let iface = self.section_base; let snap = self.interfaces.get(iface).map(|i| i.snaplen).filter(|&s| s > 0).unwrap_or(u32::MAX); let room = body_end.saturating_sub(body + 4); - let cap = (orig.min(snap) as usize).min(room); + let cap = orig.min(snap) as usize; + if cap.checked_add(3).map(|n| n & !3) != Some(room) { + self.rejected_simple_blocks += 1; + continue; + } let Some(data) = r.slice(body + 4, cap) else { continue }; if iface >= self.interfaces.len() { continue; @@ -338,17 +369,18 @@ impl<'a> Iterator for Capture<'a> { type Item = Frame<'a>; fn next(&mut self) -> Option> { - if self.count >= MAX_PACKETS { - if !self.truncated && self.pos < self.data.len() { - self.truncated = true; - self.warnings.push(format!("stopped after {MAX_PACKETS} frames")); + let frame = if self.packet_limit_reached() { + None + } else { + match self.kind { + Kind::Classic { le, nanos } => self.next_classic(le, nanos), + Kind::Ng { le } => self.next_ng(le), } - return None; - } - match self.kind { - Kind::Classic { le, nanos } => self.next_classic(le, nanos), - Kind::Ng { le } => self.next_ng(le), + }; + if frame.is_none() { + self.report_rejected_simple_blocks(); } + frame } } @@ -535,7 +567,12 @@ pub fn decode(link_type: u32, data: &[u8]) -> Decoded { } 12 | 14 | 101 | 228 | 229 => { d.protocols.push("raw"); - (r.u8(0).map(|b| if b >> 4 == 6 { 0x86dd } else { 0x0800 }), 0) + let ethertype = match link_type { + 228 => Some(0x0800), + 229 => Some(0x86dd), + _ => r.u8(0).map(|b| if b >> 4 == 6 { 0x86dd } else { 0x0800 }), + }; + (ethertype, 0) } _ => { d.note = Some(format!("link type {link_type} ({}) is not decoded", link_name(link_type))); @@ -560,11 +597,15 @@ fn ipv4(p: &[u8], d: &mut Decoded) { return; }; let ihl = usize::from(vihl & 0x0f) * 4; - let (Some(src), Some(dst)) = (r.slice(12, 4), r.slice(16, 4)) else { return }; - if vihl >> 4 != 4 || ihl < 20 { + if vihl >> 4 != 4 || ihl < 20 || usize::from(total) < ihl { d.note = Some("not a valid IPv4 header".into()); return; } + if r.slice(0, ihl).is_none() { + d.note = Some("IPv4 header cut short".into()); + return; + } + let (Some(src), Some(dst)) = (r.slice(12, 4), r.slice(16, 4)) else { return }; d.protocols.push("ipv4"); let ip4 = |b: &[u8]| { IpAddr::V4(Ipv4Addr::new( @@ -576,7 +617,7 @@ fn ipv4(p: &[u8], d: &mut Decoded) { }; let fragment = frag & 0x1fff != 0; d.ip = Some(IpInfo { version: 4, src: ip4(src), dst: ip4(dst), protocol: proto, ttl, fragment }); - let end = usize::from(total).clamp(ihl, p.len().max(ihl)); + let end = usize::from(total).min(p.len()); let body = p.get(ihl..end).unwrap_or(&[]); if fragment { d.note = Some("IPv4 fragment (transport header is in the first fragment)".into()); @@ -591,6 +632,10 @@ fn ipv6(p: &[u8], d: &mut Decoded) { d.note = Some("IPv6 header cut short".into()); return; }; + if r.u8(0).is_none_or(|version| version >> 4 != 6) { + d.note = Some("not a valid IPv6 header".into()); + return; + } d.protocols.push("ipv6"); let ip6 = |b: &[u8]| IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(b).unwrap_or([0; 16]))); let end = (40 + usize::from(plen)).min(p.len()); @@ -616,6 +661,9 @@ fn ipv6(p: &[u8], d: &mut Decoded) { next = n; fragment = fo & 0xfff8 != 0; off += 8; + if fragment { + break; + } } 51 => { let (Some(n), Some(l)) = (payload_reader.u8(off), payload_reader.u8(off + 1)) else { break }; @@ -756,14 +804,29 @@ pub fn qtype_name(t: u16) -> String { } } -/// A (possibly compressed) DNS name at `off`; returns the name and the offset after it. -fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize)> { +fn dns_sd_service_label(label: &[u8]) -> bool { + let Some(name) = label.strip_prefix(b"_") else { return false }; + // RFC 6763 §7 / RFC 6335 §5.1, excluding the leading underscore. + (1..=15).contains(&name.len()) + && name.first().is_some_and(u8::is_ascii_alphanumeric) + && name.last().is_some_and(u8::is_ascii_alphanumeric) + && name.iter().all(|c| c.is_ascii_alphanumeric() || *c == b'-') + && name.iter().any(u8::is_ascii_alphabetic) + && !name.windows(2).any(|pair| pair == b"--") +} + +/// A DNS name, the offset after it, and whether its wire labels name a DNS-SD instance. +fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize, bool)> { let mut out = String::new(); + // Count the expanded wire name, including label lengths and the terminating root. + let mut wire_len = 1usize; let mut after: Option = None; + let mut labels = 0; + let mut service_instance = false; for _ in 0..128 { let len = *msg.get(off)?; match len { - 0 => return Some((if out.is_empty() { ".".into() } else { out }, after.unwrap_or(off + 1))), + 0 => return Some((if out.is_empty() { ".".into() } else { out }, after.unwrap_or(off + 1), labels >= 4 && service_instance)), l if l & 0xc0 == 0xc0 => { let ptr = usize::from(u16::from_be_bytes([l & 0x3f, *msg.get(off + 1)?])); after.get_or_insert(off + 2); @@ -774,13 +837,22 @@ fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize)> { } l if l < 64 => { let label = msg.get(off + 1..off + 1 + usize::from(l))?; + wire_len += 1 + label.len(); + if wire_len > 255 { + return None; + } + // Match Instance / _service / _tcp|_udp / Domain before rendering: + // a literal dot inside one wire label is not a label boundary. + match labels { + 1 => service_instance = dns_sd_service_label(label), + 2 => service_instance &= label.eq_ignore_ascii_case(b"_tcp") || label.eq_ignore_ascii_case(b"_udp"), + _ => {} + } + labels += 1; if !out.is_empty() { out.push('.'); } out.extend(label.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' })); - if out.len() > 255 { - return None; - } off += 1 + usize::from(l); } _ => return None, @@ -789,22 +861,26 @@ fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize)> { None } +/// Decode a bounded set of DNS questions and answer/prerequisite records from one message. +/// Preserve complete entries before malformed data and mark the message incomplete. fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { let r = Reader::new(msg); let (Some(id), Some(flags), Some(qd), Some(an)) = (r.u16_be(0), r.u16_be(2), r.u16_be(4), r.u16_be(6)) else { return }; + let opcode = (flags >> 11) & 0xf; // Sanity: opcode 0–6 and no absurd counts, so random payload on port 53 isn't misread. - if (flags >> 11) & 0xf > 6 || qd > 64 || qd == 0 && an == 0 { + if opcode > 6 || qd > 64 || qd == 0 && an == 0 { return; } d.protocols.push(label); let mut out = Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false }; let mut off = 12usize; for _ in 0..qd { - let Some((name, next)) = dns_name(msg, off) else { + let Some((name, next, _)) = dns_name(msg, off) else { out.incomplete = true; break; }; - let Some(qt) = r.u16_be(next) else { + // The class is not displayed, but both two-byte fields must be present. + let (Some(qt), Some(_class)) = (r.u16_be(next), r.u16_be(next + 2)) else { out.incomplete = true; break; }; @@ -813,11 +889,11 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { } if !out.incomplete { for _ in 0..an.min(64) { - let Some((name, next)) = dns_name(msg, off) else { + let Some((name, next, service_instance)) = dns_name(msg, off) else { out.incomplete = true; break; }; - let (Some(rt), Some(ttl), Some(rdlen)) = (r.u16_be(next), r.u32_be(next + 4), r.u16_be(next + 8)) else { + let (Some(rt), Some(class), Some(ttl), Some(rdlen)) = (r.u16_be(next), r.u16_be(next + 2), r.u32_be(next + 4), r.u16_be(next + 8)) else { out.incomplete = true; break; }; @@ -835,31 +911,54 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { ) .to_string(), (28, 16) => Ipv6Addr::from(<[u8; 16]>::try_from(rd).unwrap_or([0; 16])).to_string(), - (2 | 5 | 12, _) => dns_name(msg, rd_off).map(|(n, _)| n).unwrap_or_default(), - (15, _) => dns_name(msg, rd_off + 2).map(|(n, _)| n).unwrap_or_default(), + (2 | 5 | 12 | 15, _) => { + // RFC 2136 prerequisites can name an RRset without carrying its value. + if rd.is_empty() && opcode == 5 && matches!(class, 254 | 255) && ttl == 0 { + String::new() + } else { + let end = rd_off + rd.len(); + let start = rd_off + if rt == 15 { 2 } else { 0 }; + // Keep earlier bytes available to compression pointers, but the encoded + // name itself must fit the record and account for all of its RDATA. + let Some((name, _, _)) = dns_name(msg.get(..end).unwrap_or(&[]), start).filter(|(_, after, _)| *after == end) else { + out.incomplete = true; + break; + }; + name + } + } (16, _) => { - // RFC 1035 §3.3.14: one TXT RDATA holds any number of + // RFC 1035 §3.3.14: one TXT RDATA holds one or more // length-prefixed character strings, and a zero-length // string does not end the record. Consumers join them all // (RFC 7208 §3.3), so keep every string instead of the // first one and skip the rest of the RDATA. let mut txt = String::new(); let mut pos = 0; + // UPDATE's answer section holds prerequisites. ANY/NONE + // prerequisites use empty RDATA and zero TTL (RFC 2136 §2.4). + let empty_prerequisite = opcode == 5 && matches!(class, 254 | 255) && ttl == 0; + // DNS-SD receivers treat empty RDATA as an empty string + // (RFC 6763 §6.1), for both multicast and unicast DNS. + let empty_service_txt = opcode == 0 && service_instance; + out.incomplete |= rd.is_empty() && !empty_prerequisite && !empty_service_txt; while let Some(&len) = rd.get(pos) { let len = usize::from(len); - let end = (pos + 1).saturating_add(len).min(rd.len()); - match rd.get(pos + 1..end) { - Some(part) => { - txt.push_str(&String::from_utf8_lossy(part)); - pos = end; - } - None => break, - } + let end = pos + 1 + len; + let Some(part) = rd.get(pos + 1..end) else { + out.incomplete = true; + break; + }; + txt.push_str(&String::from_utf8_lossy(part)); + pos = end; } txt } (_, n) => format!("<{n} bytes>"), }; + if out.incomplete { + break; + } out.answers.push(DnsAnswer { name, rtype: qtype_name(rt), ttl, value }); off = rd_off + usize::from(rdlen); } @@ -896,12 +995,21 @@ fn tcp_app(p: &[u8], d: &mut Decoded) { && METHODS.contains(&m) && v.starts_with("HTTP/1.") { - let lower = String::from_utf8_lossy(head).to_ascii_lowercase(); - let host = lower.find("\r\nhost:").and_then(|i| { - let start = i + 7; - let raw = String::from_utf8_lossy(head.get(start..)?).into_owned(); - Some(raw.split("\r\n").next().unwrap_or("").trim().to_string()) - }); + let mut remaining = head.get(line_end + 2..).unwrap_or(&[]); + let mut host = None; + while let Some(end) = remaining.windows(2).position(|w| w == b"\r\n") { + let field = remaining.get(..end).unwrap_or(&[]); + if field.is_empty() { + break; + } + if let Some(colon) = field.iter().position(|&b| b == b':') + && field.get(..colon).is_some_and(|name| name.eq_ignore_ascii_case(b"host")) + { + host = field.get(colon + 1..).map(|value| String::from_utf8_lossy(value).trim().to_string()); + break; + } + remaining = remaining.get(end + 2..).unwrap_or(&[]); + } d.protocols.push("http"); d.http = Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host }); return; @@ -1270,8 +1378,9 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result Vec { + eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 1], [192, 0, 2, 2], &udp(51000, 53, message))) +} + +/// Neither a missing class nor a one-byte class can complete a DNS question. +#[test] +fn a_question_missing_any_class_byte_is_incomplete() { + let complete = dns_query(); + for missing in [1, 2] { + let message = &complete[..complete.len() - missing]; + let dns = decode(1, &packet(message)).dns.unwrap(); + assert!(dns.incomplete, "missing {missing} class bytes"); + assert!(dns.questions.is_empty(), "a question needs both type and class"); + } +} + +#[test] +fn complete_questions_survive_before_a_truncated_question() { + let mut message = dns_query(); + message[4..6].copy_from_slice(&2u16.to_be_bytes()); + message.extend([0xc0, 12, 0, 28, 0]); // compressed name, AAAA, one class byte + + let dns = decode(1, &packet(&message)).dns.unwrap(); + assert!(dns.incomplete); + assert_eq!(dns.questions.len(), 1); + assert_eq!(dns.questions[0].name, "example.com"); + assert_eq!(dns.questions[0].qtype, "A"); +} + +#[test] +fn incomplete_questions_do_not_enter_the_query_inventory() { + let mut message = dns_query(); + message.pop(); + let summary = summarize(&pcap(&[packet(&message)]), &|| false).unwrap(); + assert_eq!(summary.packets, 1); + assert!(summary.dns_queries.is_empty()); +} + +/// Class validation requires both bytes without restricting valid class values. +#[test] +fn complete_class_fields_are_accepted() { + for class in [1u16, 3, 255] { + let mut message = dns_query(); + message.truncate(message.len() - 2); + message.extend(class.to_be_bytes()); + let dns = decode(1, &packet(&message)).dns.unwrap(); + assert!(!dns.incomplete); + assert_eq!(dns.questions.len(), 1); + assert_eq!(dns.questions[0].name, "example.com"); + assert_eq!(dns.questions[0].qtype, "A"); + } +} diff --git a/crates/pcap/tests/dns_rdata_names.rs b/crates/pcap/tests/dns_rdata_names.rs new file mode 100644 index 000000000..88b7315b7 --- /dev/null +++ b/crates/pcap/tests/dns_rdata_names.rs @@ -0,0 +1,184 @@ +use craft_anything_formats::pcap::{decode, summarize}; +use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, udp}; + +fn response(record_type: u16, rdata: &[u8], declared_length: usize) -> Vec { + let mut message = dns_query(); + message[2..4].copy_from_slice(&0x8180u16.to_be_bytes()); + message[6..8].copy_from_slice(&1u16.to_be_bytes()); + message.extend([0xc0, 12]); // owner points to the question's name + message.extend(record_type.to_be_bytes()); + message.extend(1u16.to_be_bytes()); + message.extend(60u32.to_be_bytes()); + message.extend((declared_length as u16).to_be_bytes()); + message.extend(rdata); + message +} + +fn packet(message: &[u8]) -> Vec { + eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 2], [192, 0, 2, 1], &udp(53, 51000, message))) +} + +/// Truncated literal names and compression pointers must stay inside RDLENGTH. +#[test] +fn answer_names_cannot_borrow_bytes_past_rdata() { + for record_type in [2, 5, 12, 15] { + for name in [b"\x04fake\x07example\x00".as_slice(), &[0xc0, 12]] { + let mut rdata = if record_type == 15 { vec![0, 10] } else { Vec::new() }; + let prefix = rdata.len(); + rdata.extend(name); + for declared in [prefix, prefix + name.len() - 1] { + let dns = decode(1, &packet(&response(record_type, &rdata, declared))).dns.unwrap(); + assert!(dns.incomplete, "type {record_type}, declared length {declared}"); + assert!(dns.answers.is_empty(), "a name must be wholly encoded in its record"); + } + } + } +} + +/// An incomplete pointer is malformed, rather than a successful empty answer. +#[test] +fn malformed_name_rdata_is_not_reported_as_an_empty_answer() { + for record_type in [2, 5, 12, 15] { + let rdata = if record_type == 15 { vec![0, 10, 0xc0] } else { vec![0xc0] }; + let dns = decode(1, &packet(&response(record_type, &rdata, rdata.len()))).dns.unwrap(); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +/// An MX name cannot borrow either of its required preference bytes from trailing data. +#[test] +fn an_mx_exchange_cannot_skip_a_missing_preference() { + for declared in [0, 1] { + let dns = decode(1, &packet(&response(15, &[0, 10, 0xc0, 12], declared))).dns.unwrap(); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +/// A terminator before the declared boundary must not hide unused RDATA bytes. +#[test] +fn a_name_must_account_for_all_of_its_rdata() { + for record_type in [2, 5, 12, 15] { + let rdata = if record_type == 15 { vec![0, 10, 0, 0xaa] } else { vec![0, 0xaa] }; + let dns = decode(1, &packet(&response(record_type, &rdata, rdata.len()))).dns.unwrap(); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +/// Literal, root, backward-pointer and label-plus-pointer names remain valid controls. +#[test] +fn complete_and_compressed_names_remain_supported() { + for record_type in [2, 5, 12, 15] { + for (name, expected) in [ + (b"\x04mail\x07example\x00".as_slice(), "mail.example"), + (&[0xc0, 12], "example.com"), + (b"\x03www\xc0\x0c".as_slice(), "www.example.com"), + (&[0], "."), + ] { + let mut rdata = if record_type == 15 { vec![0, 10] } else { Vec::new() }; + rdata.extend(name); + let dns = decode(1, &packet(&response(record_type, &rdata, rdata.len()))).dns.unwrap(); + assert!(!dns.incomplete, "type {record_type}, name {expected}"); + assert_eq!(dns.answers.len(), 1); + assert_eq!(dns.answers[0].value, expected); + } + } +} + +#[test] +fn names_outside_rdata_do_not_enter_the_answer_inventory() { + let message = response(5, b"\x04fake\x07example\x00", 0); + let summary = summarize(&pcap(&[packet(&message)]), &|| false).unwrap(); + assert_eq!(summary.packets, 1); + assert!(summary.dns_answers.is_empty()); +} + +#[test] +fn earlier_answers_survive_before_a_malformed_name() { + let mut message = response(1, &[192, 0, 2, 3], 4); + message[6..8].copy_from_slice(&2u16.to_be_bytes()); + let malformed = response(5, b"\x04fake\x07example\x00", 0); + message.extend(&malformed[dns_query().len()..]); + + let dns = decode(1, &packet(&message)).dns.unwrap(); + assert!(dns.incomplete); + assert_eq!(dns.answers.len(), 1); + assert_eq!(dns.answers[0].rtype, "A"); + assert_eq!(dns.answers[0].value, "192.0.2.3"); +} + +fn prerequisite_message(flags: u16, record_type: u16, class: u16, ttl: u32, rdata: &[u8]) -> Vec { + let mut message = vec![0, 1]; + message.extend(flags.to_be_bytes()); + message.extend([0, 1, 0, 2, 0, 0, 0, 0]); + message.extend(b"\x07example\x04test\0"); + message.extend([0, 6, 0, 1]); // One Zone record, SOA/IN. + message.extend(b"\x05first\xc0\x0c"); + message.extend(record_type.to_be_bytes()); + message.extend(class.to_be_bytes()); + message.extend(ttl.to_be_bytes()); + message.extend((rdata.len() as u16).to_be_bytes()); + message.extend(rdata); + // A different owner lets this value-dependent prerequisite coexist with CLASS NONE above. + message.extend(b"\x05after\xc0\x0c"); + message.extend([0, 1, 0, 1, 0, 0, 0, 0, 0, 4, 192, 0, 2, 4]); + message +} + +#[test] +fn empty_update_name_prerequisites_preserve_the_following_record() { + for record_type in [2, 5, 12, 15] { + for class in [254, 255] { + let dns = decode(1, &packet(&prerequisite_message(0x2800, record_type, class, 0, &[]))).dns.unwrap(); + assert!(!dns.incomplete, "type {record_type}, class {class}"); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].value, ""); + assert_eq!(dns.answers[1].name, "after.example.test"); + assert_eq!(dns.answers[1].value, "192.0.2.4"); + } + } +} + +#[test] +fn empty_name_rdata_is_rejected_outside_legal_update_prerequisites() { + let cases = [(0x8180, 254, 0), (0x8180, 255, 0), (0x2000, 254, 0), (0x2000, 255, 0), (0x2800, 1, 0), (0x2800, 254, 1), (0x2800, 255, 1)]; + for record_type in [2, 5, 12, 15] { + for (flags, class, ttl) in cases { + let dns = decode(1, &packet(&prerequisite_message(flags, record_type, class, ttl, &[]))).dns.unwrap(); + assert!(dns.incomplete, "type {record_type}, flags {flags:#x}, class {class}, TTL {ttl}"); + assert!(dns.answers.is_empty()); + } + } +} + +#[test] +fn update_name_rdata_still_requires_complete_exact_encoding() { + for record_type in [2, 5, 12, 15] { + for class in [1, 254, 255] { + for name in [&[0xc0][..], &[0, 0xaa]] { + let mut rdata = if record_type == 15 { vec![0, 10] } else { Vec::new() }; + rdata.extend(name); + let dns = decode(1, &packet(&prerequisite_message(0x2800, record_type, class, 0, &rdata))).dns.unwrap(); + assert!(dns.incomplete, "type {record_type}, class {class}, name {name:?}"); + assert!(dns.answers.is_empty()); + } + } + } +} + +#[test] +fn value_dependent_update_name_prerequisites_keep_their_values() { + for record_type in [2, 5, 12, 15] { + for (name, expected) in [(&[0][..], "."), (&[0xc0, 12], "example.test")] { + let mut rdata = if record_type == 15 { vec![0, 0] } else { Vec::new() }; + rdata.extend(name); + let dns = decode(1, &packet(&prerequisite_message(0x2800, record_type, 1, 0, &rdata))).dns.unwrap(); + assert!(!dns.incomplete, "type {record_type}, name {expected}"); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].value, expected); + assert_eq!(dns.answers[1].value, "192.0.2.4"); + } + } +} diff --git a/crates/pcap/tests/pcap_dns_name_limit.rs b/crates/pcap/tests/pcap_dns_name_limit.rs new file mode 100644 index 000000000..f16c89387 --- /dev/null +++ b/crates/pcap/tests/pcap_dns_name_limit.rs @@ -0,0 +1,151 @@ +use craft_anything_formats::pcap::{Dns, decode}; +use craft_anything_testkit::pcap::{ipv4_pkt, udp}; + +fn query(last: usize, compressed: bool) -> Dns { + let mut msg = vec![0, 1, 1, 0, 0, if compressed { 2 } else { 1 }, 0, 0, 0, 0, 0, 0]; + for len in [63, 63, 63, last] { + msg.push(len as u8); + msg.extend(vec![b'a'; len]); + } + msg.extend([0, 0, 1, 0, 1]); + if compressed { + msg.extend([0xc0, 12, 0, 1, 0, 1]); + } + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 53, &msg))).dns.unwrap() +} + +#[test] +fn label_lengths_and_the_root_octet_count_towards_the_dns_limit() { + for last in [62, 63] { + let dns = query(last, false); + assert!(dns.incomplete); + assert!(dns.questions.is_empty()); + } +} + +#[test] +fn a_255_octet_name_is_valid_in_plain_and_compressed_form() { + for compressed in [false, true] { + let dns = query(61, compressed); + assert!(!dns.incomplete); + assert_eq!(dns.questions.len(), if compressed { 2 } else { 1 }); + assert_eq!(dns.questions[0].name.len(), 253); + } +} + +fn prefixed_pointer(last: usize, answer_type: Option) -> Dns { + let mut msg = vec![0, 1, 0x81, 0x80, 0, if answer_type.is_some() { 1 } else { 2 }, 0, u8::from(answer_type.is_some()), 0, 0, 0, 0]; + for len in [63, 63, 63, last] { + msg.push(len as u8); + msg.extend(vec![b'a'; len]); + } + msg.extend([0, 0, 1, 0, 1]); + if let Some(rtype) = answer_type { + msg.extend([0xc0, 12]); + msg.extend(rtype.to_be_bytes()); + msg.extend([0, 1, 0, 0, 0, 0, 0, if rtype == 15 { 6 } else { 4 }]); + if rtype == 15 { + msg.extend([0, 10]); + } + } + msg.extend([1, b'x', 0xc0, 12]); + if answer_type.is_none() { + msg.extend([0, 1, 0, 1]); + } + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 53, &msg))).dns.unwrap() +} + +#[test] +fn a_literal_prefix_and_pointer_cannot_exceed_the_question_name_limit() { + let dns = prefixed_pointer(61, None); + assert!(dns.incomplete); + assert_eq!(dns.questions.len(), 1); +} + +#[test] +fn invalid_name_rdata_is_incomplete_instead_of_an_empty_answer() { + for rtype in [2, 5, 12, 15] { + let dns = prefixed_pointer(61, Some(rtype)); + assert!(dns.incomplete, "record type {rtype}"); + assert_eq!(dns.questions.len(), 1); + assert!(dns.answers.is_empty(), "record type {rtype}"); + } +} + +#[test] +fn a_prefixed_pointer_at_255_octets_remains_valid() { + let dns = prefixed_pointer(59, None); + assert!(!dns.incomplete); + assert_eq!(dns.questions.len(), 2); + for rtype in [2, 5, 12, 15] { + let dns = prefixed_pointer(59, Some(rtype)); + assert!(!dns.incomplete, "record type {rtype}"); + assert_eq!(dns.answers.len(), 1); + assert_eq!(dns.answers[0].value.len(), 253); + } +} + +fn name_rdata_then_a(flags: u16, class: u16, ttl: u32, rtype: u16, rdata: &[u8]) -> Dns { + let mut msg = vec![0, 1]; + msg.extend(flags.to_be_bytes()); + msg.extend([0, 1, 0, 2, 0, 0, 0, 0]); + msg.extend(b"\x07example\x04test\0"); + msg.extend([0, 6, 0, 1]); // Zone: SOA/IN for UPDATE requests. + msg.extend([3, b'o', b'n', b'e', 0xc0, 12]); + msg.extend(rtype.to_be_bytes()); + msg.extend(class.to_be_bytes()); + msg.extend(ttl.to_be_bytes()); + msg.extend((rdata.len() as u16).to_be_bytes()); + msg.extend(rdata); + // A different owner keeps the two UPDATE prerequisites independent. + msg.extend([4, b'n', b'e', b'x', b't', 0xc0, 12, 0, 1, 0, 1, 0, 0, 0, 0, 0, 4, 203, 0, 113, 1]); + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 53, &msg))).dns.unwrap() +} + +#[test] +fn empty_update_name_prerequisites_preserve_the_following_record() { + for rtype in [2, 5, 12, 15] { + for class in [254, 255] { + let dns = name_rdata_then_a(0x2800, class, 0, rtype, &[]); + assert!(!dns.incomplete, "type {rtype}, class {class}"); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].value, ""); + assert_eq!(dns.answers[1].value, "203.0.113.1"); + } + } +} + +#[test] +fn empty_name_rdata_is_rejected_outside_legal_update_prerequisites() { + let cases = [(0x8180, 254, 0), (0x8180, 255, 0), (0x2000, 254, 0), (0x2000, 255, 0), (0x2800, 1, 0), (0x2800, 254, 1), (0x2800, 255, 1)]; + for rtype in [2, 5, 12, 15] { + for (flags, class, ttl) in cases { + let dns = name_rdata_then_a(flags, class, ttl, rtype, &[]); + assert!(dns.incomplete, "type {rtype}, flags {flags:#x}, class {class}, TTL {ttl}"); + assert!(dns.answers.is_empty()); + } + } +} + +#[test] +fn a_cut_rdata_pointer_cannot_borrow_the_following_owner() { + for rtype in [2, 5, 12, 15] { + let mut rdata = if rtype == 15 { vec![0, 10] } else { Vec::new() }; + rdata.push(0xc0); // The next owner's length would complete a pointer to the header's zero byte. + let dns = name_rdata_then_a(0x8180, 1, 0, rtype, &rdata); + assert!(dns.incomplete, "type {rtype}"); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn root_name_rdata_remains_valid() { + for rtype in [2, 5, 12, 15] { + let rdata = if rtype == 15 { vec![0, 0, 0] } else { vec![0] }; + let dns = name_rdata_then_a(0x8180, 1, 0, rtype, &rdata); + assert!(!dns.incomplete, "type {rtype}"); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].value, "."); + assert_eq!(dns.answers[1].value, "203.0.113.1"); + } +} diff --git a/crates/pcap/tests/pcap_dns_txt_lengths.rs b/crates/pcap/tests/pcap_dns_txt_lengths.rs new file mode 100644 index 000000000..a90207b21 --- /dev/null +++ b/crates/pcap/tests/pcap_dns_txt_lengths.rs @@ -0,0 +1,196 @@ +use craft_anything_formats::pcap::{Dns, decode}; +use craft_anything_testkit::pcap::{ipv4_pkt, udp}; + +fn response(data: &[u8]) -> Dns { + let mut msg = vec![0, 1, 0x81, 0x80, 0, 0, 0, 1, 0, 0, 0, 0]; + msg.extend([0, 0, 16, 0, 1, 0, 0, 0, 60]); + msg.extend((data.len() as u16).to_be_bytes()); + msg.extend(data); + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(53, 100, &msg))).dns.unwrap() +} + +fn prerequisites(flags: u16, class: u16, ttl: u32, data: &[u8]) -> Dns { + let mut msg = vec![0, 1]; + msg.extend(flags.to_be_bytes()); + msg.extend([0, 1, 0, 2, 0, 0, 0, 0]); + // UPDATE's zone section has the question layout: example.test, SOA, IN. + msg.extend(b"\x07example\x04test\x00\x00\x06\x00\x01"); + msg.extend([0xc0, 12, 0, 16]); + msg.extend(class.to_be_bytes()); + msg.extend(ttl.to_be_bytes()); + msg.extend((data.len() as u16).to_be_bytes()); + msg.extend(data); + // Different owners let NONE and value-dependent prerequisites hold together. + // The following TXT record must also survive. + msg.extend(b"\x05after"); + msg.extend([0xc0, 12, 0, 16, 0, 1, 0, 0, 0, 0, 0, 3, 2, b'o', b'k']); + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 53, &msg))).dns.unwrap() +} + +fn named_txt(owner: &[&[u8]], data: &[u8], port: u16, flags: u16, class: u16, ttl: u32, compressed: bool) -> Dns { + let mut name = Vec::new(); + for label in owner { + name.push(u8::try_from(label.len()).unwrap()); + name.extend(*label); + } + name.push(0); + let mut msg = vec![0, 1]; + msg.extend(flags.to_be_bytes()); + msg.extend([0, 1, 0, 2, 0, 0, 0, 0]); + msg.extend(&name); + msg.extend([0, 16, 0, 1]); + if compressed { + msg.extend([0xc0, 12]); + } else { + msg.extend(&name); + } + msg.extend([0, 16]); + msg.extend(class.to_be_bytes()); + msg.extend(ttl.to_be_bytes()); + msg.extend(u16::try_from(data.len()).unwrap().to_be_bytes()); + msg.extend(data); + // The next answer must survive an empty DNS-SD TXT record. + msg.extend([0xc0, 12, 0, 1, 0, 1, 0, 0, 0, 60, 0, 4, 127, 0, 0, 1]); + decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(port, 100, &msg))).dns.unwrap() +} + +fn assert_empty_txt_and_following_answer(dns: Dns) { + assert!(!dns.incomplete); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].rtype, "TXT"); + assert_eq!(dns.answers[0].value, ""); + assert_eq!(dns.answers[1].value, "127.0.0.1"); +} + +#[test] +fn empty_dns_sd_txt_preserves_following_answers() { + let multicast: &[&[u8]] = &[b"Printer", b"_ipp", b"_tcp", b"local"]; + let unicast: &[&[u8]] = &[b"Printer", b"_ipp", b"_tcp", b"example", b"test"]; + for (port, owner) in [(5353, multicast), (53, unicast)] { + assert_empty_txt_and_following_answer(named_txt(owner, &[], port, 0x8400, 1, 60, false)); + } +} + +#[test] +fn empty_dns_sd_txt_is_valid_in_mdns_known_answers_and_cache_flush_records() { + let owner: &[&[u8]] = &[b"Printer", b"_ipp", b"_tcp", b"local"]; + // Queries may contain known answers; the cache-flush bit belongs to CLASS. + for (flags, class) in [(0, 1), (0x8400, 0x8001)] { + assert_empty_txt_and_following_answer(named_txt(owner, &[], 5353, flags, class, 60, false)); + } +} + +#[test] +fn dns_sd_owner_preserves_wire_labels_case_and_compression() { + let owner: &[&[u8]] = &[b"Printer.with dots", b"_Ab-12", b"_UdP", b"example", b"test"]; + for compressed in [false, true] { + assert_empty_txt_and_following_answer(named_txt(owner, &[], 53, 0x8180, 1, 60, compressed)); + } +} + +#[test] +fn other_empty_txt_owners_are_not_dns_sd_instances() { + let owners: &[&[&[u8]]] = &[ + &[b"Printer", b"local"], + &[b"Printer._ipp._tcp", b"local"], + &[b"Printer", b"_ipp._tcp", b"_tcp", b"local"], + &[b"_ipp", b"_tcp", b"local"], + &[b"Printer", b"_ipp", b"_tcp"], + &[b"Printer", b"_ipp", b"_other", b"local"], + &[b"Printer", b"_123", b"_tcp", b"local"], + &[b"Printer", b"_bad--name", b"_tcp", b"local"], + ]; + for owner in owners { + let dns = named_txt(owner, &[], 5353, 0x8400, 1, 60, false); + assert!(dns.incomplete, "owner {owner:?}"); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn dns_sd_txt_still_rejects_truncated_nonempty_strings() { + let owner: &[&[u8]] = &[b"Printer", b"_ipp", b"_tcp", b"local"]; + for data in [&b"\x02x"[..], &b"\x00\x04x"[..]] { + let dns = named_txt(owner, data, 5353, 0x8400, 0x8001, 60, true); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn dns_sd_owner_does_not_relax_update_prerequisite_classes() { + let owner: &[&[u8]] = &[b"Printer", b"_ipp", b"_tcp", b"example", b"test"]; + let dns = named_txt(owner, &[], 53, 5 << 11, 1, 0, true); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + for class in [254, 255] { + assert_empty_txt_and_following_answer(named_txt(owner, &[], 53, 5 << 11, class, 0, true)); + } +} + +#[test] +fn empty_update_prerequisites_preserve_following_records() { + for class in [254, 255] { + let dns = prerequisites(5 << 11, class, 0, &[]); + assert!(!dns.incomplete, "class {class}"); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].name, "example.test"); + assert_eq!(dns.answers[0].value, ""); + assert_eq!(dns.answers[1].name, "after.example.test"); + assert_eq!(dns.answers[1].value, "ok"); + } +} + +#[test] +fn empty_txt_rdata_requires_update_and_a_prerequisite_class() { + assert!(response(&[]).incomplete); + for (flags, class, ttl) in [(0x8180, 254, 0), (0x8180, 255, 0), (5 << 11, 1, 0), (5 << 11, 254, 60), (5 << 11, 255, 60)] { + let dns = prerequisites(flags, class, ttl, &[]); + assert!(dns.incomplete, "flags {flags:#x}, class {class}, ttl {ttl}"); + assert!(dns.answers.is_empty()); + } + for opcode in [1, 2, 3, 4, 6] { + for class in [254, 255] { + let dns = prerequisites(opcode << 11, class, 0, &[]); + assert!(dns.incomplete, "opcode {opcode}, class {class}"); + assert!(dns.answers.is_empty()); + } + } +} + +#[test] +fn update_prerequisite_classes_do_not_allow_truncated_strings() { + for class in [254, 255] { + let dns = prerequisites(5 << 11, class, 0, b"\x02x"); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn truncated_txt_strings_are_not_complete_answers() { + for data in [&b"\x05abc"[..], &b"\x02ok\x04x"[..], &b"\x01"[..]] { + let dns = response(data); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn empty_and_multiple_complete_strings_remain_valid() { + for (data, expected) in [(&b"\x00"[..], ""), (&b"\x00\x02ok\x01!"[..], "ok!")] { + let dns = response(data); + assert!(!dns.incomplete); + assert_eq!(dns.answers[0].value, expected); + } +} + +#[test] +fn value_dependent_update_accepts_an_empty_character_string() { + let dns = prerequisites(5 << 11, 1, 0, b"\x00"); + assert!(!dns.incomplete); + assert_eq!(dns.answers.len(), 2); + assert_eq!(dns.answers[0].value, ""); + assert_eq!(dns.answers[1].name, "after.example.test"); + assert_eq!(dns.answers[1].value, "ok"); +} diff --git a/crates/pcap/tests/pcap_flow_time_range.rs b/crates/pcap/tests/pcap_flow_time_range.rs new file mode 100644 index 000000000..96b6c128b --- /dev/null +++ b/crates/pcap/tests/pcap_flow_time_range.rs @@ -0,0 +1,36 @@ +use craft_anything_formats::pcap::summarize; +use craft_anything_testkit::pcap::{block, eth, ipv4_pkt, pcap, pcapng, udp}; + +fn frame() -> Vec { + eth(0x0800, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 200, b"body"))) +} + +#[test] +fn out_of_order_flow_packets_keep_the_earliest_and_latest_timestamps() { + let f = frame(); + let mut capture = pcap(&[f.clone(), f.clone(), f.clone()]); + for (i, seconds) in [30u32, 10, 20].into_iter().enumerate() { + let at = 24 + i * (16 + f.len()); + capture[at..at + 4].copy_from_slice(&seconds.to_le_bytes()); + } + let summary = summarize(&capture, &|| false).unwrap(); + let flow = &summary.flows[0]; + assert_eq!(flow.first_ts_ns, summary.first_ts_ns); + assert_eq!(flow.last_ts_ns, summary.last_ts_ns); + assert_eq!(flow.first_frame, 1); +} + +#[test] +fn a_timestamped_packet_fills_a_flow_started_by_a_simple_packet() { + let f = frame(); + let headers = pcapng(&[]); + let mut simple = (f.len() as u32).to_le_bytes().to_vec(); + simple.extend(&f); + let mut capture = headers.clone(); + capture.extend(block(3, &simple)); + capture.extend(&pcapng(&[f])[headers.len()..]); + let summary = summarize(&capture, &|| false).unwrap(); + assert!(summary.first_ts_ns.is_some()); + assert_eq!(summary.flows[0].first_ts_ns, summary.first_ts_ns); + assert_eq!(summary.flows[0].last_ts_ns, summary.last_ts_ns); +} diff --git a/crates/pcap/tests/pcap_http_host_boundary.rs b/crates/pcap/tests/pcap_http_host_boundary.rs new file mode 100644 index 000000000..13b6955d8 --- /dev/null +++ b/crates/pcap/tests/pcap_http_host_boundary.rs @@ -0,0 +1,24 @@ +use craft_anything_formats::pcap::{Http, decode}; +use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; + +fn request(data: &[u8]) -> Http { + decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, data))).http.unwrap() +} + +#[test] +fn a_host_shaped_line_in_the_body_is_not_a_request_header() { + let http = request(b"POST / HTTP/1.1\r\nContent-Length: 22\r\n\r\nbody\r\nHost: forged.test\r\n"); + assert!(http.host.is_none()); +} + +#[test] +fn invalid_utf8_before_host_does_not_shift_header_byte_offsets() { + let http = request(b"GET / HTTP/1.1\r\nX-Data: \xff\r\nHoSt:\tReal.test \t\r\n\r\n"); + assert_eq!(http.host.as_deref(), Some("Real.test")); +} + +#[test] +fn host_requires_a_complete_header_line_and_keeps_its_spelling() { + assert!(request(b"GET / HTTP/1.1\r\nHost: cut").host.is_none()); + assert_eq!(request(b"GET / HTTP/1.1\r\nHost: Real.test\r\n\r\n").host.as_deref(), Some("Real.test")); +} diff --git a/crates/pcap/tests/pcap_ipv4_lengths.rs b/crates/pcap/tests/pcap_ipv4_lengths.rs new file mode 100644 index 000000000..21f1f6eac --- /dev/null +++ b/crates/pcap/tests/pcap_ipv4_lengths.rs @@ -0,0 +1,57 @@ +use craft_anything_formats::pcap::decode; +use craft_anything_testkit::pcap::{ipv4_pkt, udp}; + +#[test] +fn incomplete_ipv4_base_headers_explain_why_decoding_stopped() { + let packet = ipv4_pkt(17, [1; 4], [2; 4], &[]); + for captured in 10..20 { + let decoded = decode(101, &packet[..captured]); + assert!(decoded.ip.is_none(), "captured {captured} bytes"); + assert!(decoded.transport.is_none(), "captured {captured} bytes"); + assert_eq!(decoded.note.as_deref(), Some("IPv4 header cut short"), "captured {captured} bytes"); + } +} + +#[test] +fn an_ipv4_total_length_cannot_be_shorter_than_its_header() { + for total in [0u16, 19, 23] { + let mut packet = ipv4_pkt(17, [1, 2, 3, 4], [5, 6, 7, 8], &udp(100, 200, b"body")); + packet[0] = 0x46; + packet[2..4].copy_from_slice(&total.to_be_bytes()); + let decoded = decode(101, &packet); + assert!(decoded.ip.is_none()); + assert!(decoded.transport.is_none()); + assert!(decoded.note.is_some()); + } +} + +#[test] +fn missing_ipv4_options_do_not_form_a_complete_ip_header() { + let mut packet = ipv4_pkt(17, [1; 4], [2; 4], &[]); + packet[0] = 0x46; + packet[2..4].copy_from_slice(&24u16.to_be_bytes()); + let decoded = decode(101, &packet); + assert!(decoded.ip.is_none()); + assert!(decoded.note.is_some()); +} + +#[test] +fn complete_options_and_truncated_transport_keep_their_valid_fields() { + let body = udp(100, 200, b"body"); + let mut payload = vec![0; 4]; + payload.extend(body); + let mut packet = ipv4_pkt(17, [1; 4], [2; 4], &payload); + packet[0] = 0x46; + assert_eq!(decode(101, &packet).transport.unwrap().payload_len, 4); + packet.truncate(34); + let decoded = decode(101, &packet); + assert!(decoded.ip.is_some()); + let transport = decoded.transport.unwrap(); + assert_eq!(transport.src_port, Some(100)); + assert_eq!(transport.dst_port, Some(200)); + assert_eq!(transport.payload_len, 2); + packet.truncate(28); + let decoded = decode(101, &packet); + assert!(decoded.ip.is_some()); + assert_eq!(decoded.transport.unwrap().src_port, Some(100)); +} diff --git a/crates/pcap/tests/pcap_ipv6_fragments.rs b/crates/pcap/tests/pcap_ipv6_fragments.rs new file mode 100644 index 000000000..8f82257d1 --- /dev/null +++ b/crates/pcap/tests/pcap_ipv6_fragments.rs @@ -0,0 +1,40 @@ +use craft_anything_formats::pcap::decode; +use craft_anything_testkit::pcap::{eth, udp}; + +fn packet(offset: u16, next: u8, payload: &[u8]) -> Vec { + let mut ip = vec![0u8; 40]; + ip[0] = 0x60; + ip[4..6].copy_from_slice(&((8 + payload.len()) as u16).to_be_bytes()); + ip[6] = 44; + ip.extend([next, 0]); + ip.extend(offset.to_be_bytes()); + ip.extend([0; 4]); + ip.extend(payload); + eth(0x86dd, &ip) +} + +#[test] +fn a_noninitial_fragment_cannot_reset_its_offset_from_payload_bytes() { + let mut payload = vec![17, 0, 0, 0, 0, 0, 0, 0]; + payload.extend(udp(100, 200, b"body")); + let decoded = decode(1, &packet(8, 44, &payload)); + assert!(decoded.ip.unwrap().fragment); + assert!(decoded.transport.is_none()); + assert!(!decoded.protocols.contains(&"udp")); +} + +#[test] +fn noninitial_fragment_bytes_cannot_change_the_recorded_protocol() { + let decoded = decode(1, &packet(8, 60, &[17, 0, 0, 0, 0, 0, 0, 0])); + assert_eq!(decoded.ip.unwrap().protocol, 60); + assert!(decoded.transport.is_none()); +} + +#[test] +fn initial_and_atomic_fragments_still_decode_transport_headers() { + for offset in [0, 1] { + let decoded = decode(1, &packet(offset, 17, &udp(100, 200, b"body"))); + assert!(!decoded.ip.unwrap().fragment); + assert_eq!(decoded.transport.unwrap().payload_len, 4); + } +} diff --git a/crates/pcap/tests/pcap_ipv6_version.rs b/crates/pcap/tests/pcap_ipv6_version.rs new file mode 100644 index 000000000..4e4b25dc3 --- /dev/null +++ b/crates/pcap/tests/pcap_ipv6_version.rs @@ -0,0 +1,53 @@ +use craft_anything_formats::pcap::decode; +use craft_anything_testkit::pcap::{eth, ipv4_pkt}; + +fn raw_packets() -> (Vec, Vec) { + let ipv4 = ipv4_pkt(17, [1; 4], [2; 4], &[0; 20]); + let mut ipv6 = vec![0u8; 40]; + ipv6[0] = 0x60; + ipv6[6] = 59; + (ipv4, ipv6) +} + +#[test] +fn explicit_raw_link_types_reject_the_other_ip_version() { + let (ipv4, ipv6) = raw_packets(); + for (link_type, packet) in [(228, &ipv6), (229, &ipv4)] { + let decoded = decode(link_type, packet); + assert!(decoded.ip.is_none(), "link type {link_type}"); + assert!(decoded.transport.is_none(), "link type {link_type}"); + assert!(decoded.note.is_some(), "link type {link_type}"); + } +} + +#[test] +fn matching_raw_link_types_and_generic_raw_packets_remain_readable() { + let (ipv4, ipv6) = raw_packets(); + assert_eq!(decode(228, &ipv4).ip.unwrap().version, 4); + assert_eq!(decode(229, &ipv6).ip.unwrap().version, 6); + for link_type in [12, 14, 101] { + assert_eq!(decode(link_type, &ipv4).ip.unwrap().version, 4); + assert_eq!(decode(link_type, &ipv6).ip.unwrap().version, 6); + } +} + +#[test] +fn an_ethernet_type_does_not_replace_the_ipv6_version_check() { + for version in [0, 4, 5, 7, 15] { + let mut packet = [0u8; 40]; + packet[0] = version << 4; + packet[6] = 59; + let decoded = decode(1, ð(0x86dd, &packet)); + assert!(decoded.ip.is_none(), "version {version}"); + assert!(decoded.transport.is_none()); + assert!(decoded.note.is_some()); + } +} + +#[test] +fn ipv6_version_keeps_traffic_class_bits() { + let mut packet = [0u8; 40]; + packet[0] = 0x6f; + packet[6] = 59; + assert_eq!(decode(1, ð(0x86dd, &packet)).ip.unwrap().version, 6); +} diff --git a/crates/pcap/tests/pcapng_simple_payload.rs b/crates/pcap/tests/pcapng_simple_payload.rs new file mode 100644 index 000000000..c61f6c70a --- /dev/null +++ b/crates/pcap/tests/pcapng_simple_payload.rs @@ -0,0 +1,62 @@ +use craft_anything_formats::pcap::Capture; +use craft_anything_testkit::pcap::{block, pcapng}; + +fn capture(original: u32, snaplen: u32, payload: &[u8]) -> Vec { + let mut out = pcapng(&[]); + out[40..44].copy_from_slice(&snaplen.to_le_bytes()); + let mut body = original.to_le_bytes().to_vec(); + body.extend(payload); + out.extend(block(3, &body)); + out +} + +#[test] +fn a_simple_packet_cannot_silently_shorten_its_declared_capture() { + let data = capture(10, 0, &[1, 2, 3, 4]); + let mut cap = Capture::new(&data).unwrap(); + assert!(cap.next().is_none()); + assert!(!cap.warnings.is_empty()); +} + +#[test] +fn a_simple_packet_cannot_have_unexplained_extra_payload() { + let data = capture(1, 0, &[1; 8]); + let mut cap = Capture::new(&data).unwrap(); + assert!(cap.next().is_none()); + assert!(!cap.warnings.is_empty()); +} + +#[test] +fn snaplen_truncation_and_alignment_padding_are_preserved() { + for (original, snaplen) in [(3, 0), (10, 3)] { + let data = capture(original, snaplen, &[1, 2, 3]); + let mut cap = Capture::new(&data).unwrap(); + let packet = cap.next().unwrap(); + assert_eq!(packet.data, [1, 2, 3]); + assert_eq!(packet.original_len, original); + assert!(cap.next().is_none()); + assert!(cap.warnings.is_empty()); + } +} + +#[test] +fn rejected_simple_packets_share_one_warning_and_preserve_later_frames() { + let mut data = pcapng(&[]); + let rejected = block(3, &1u32.to_le_bytes()); + for _ in 0..128 { + data.extend(&rejected); + } + let mut valid = 3u32.to_le_bytes().to_vec(); + valid.extend([1, 2, 3]); + data.extend(block(3, &valid)); + let mut cap = Capture::new(&data).unwrap(); + let frame = cap.next().unwrap(); + assert_eq!(frame.number, 1); + assert_eq!(frame.data, [1, 2, 3]); + assert!(cap.next().is_none()); + assert!(!cap.truncated); + assert_eq!(cap.warnings.len(), 1); + assert!(cap.warnings[0].contains("128 simple packet blocks")); + assert!(cap.next().is_none()); + assert_eq!(cap.warnings.len(), 1); +} From f4ddb7234dcb0f5e74b6c5a09a31a48de04060a9 Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:50 -0500 Subject: [PATCH 33/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 6cbc66984c518bf4af7ed261594431eceba54e95. --- crates/pcap/src/lib.rs | 36 +++++++---- crates/pcap/tests/regression_tls_bounds.rs | 71 ++++++++++++++++++++++ 2 files changed, 96 insertions(+), 11 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index d82dc8fea..695256f81 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1037,7 +1037,7 @@ fn tls(p: &[u8], d: &mut Decoded) { 0x0302 => "TLS 1.1".into(), 0x0303 => "TLS 1.2".into(), 0x0304 => "TLS 1.3".into(), - v if v & 0x0f0f == 0x0a0a => "GREASE".into(), + v if v & 0x0f0f == 0x0a0a && v >> 8 == v & 0xff => "GREASE".into(), v => format!("{v:#06x}"), }; let mut hello = TlsHello { @@ -1057,18 +1057,24 @@ fn tls(p: &[u8], d: &mut Decoded) { let hello_end = handshake_end.min(record_end_available); let r = Reader::new(p.get(..hello_end).unwrap_or(&[])); // Every variable-length field must fit inside this handshake, not merely the packet. - let skip8 = |off: usize| { + let skip8 = |off: usize, min: usize, max: usize| { let n = usize::from(r.u8(off)?); + if !(min..=max).contains(&n) { + return None; + } r.slice(off + 1, n)?; Some(off + 1 + n) }; - let skip16 = |off: usize| { + let cipher_suites_end = |off: usize| { let n = usize::from(r.u16_be(off)?); + if n < 2 || n % 2 != 0 { + return None; + } r.slice(off + 2, n)?; Some(off + 2 + n) }; // Record header (5) + handshake header (4) + client_version (2) + random (32). - let Some(off) = skip8(5 + 4 + 2 + 32).and_then(skip16).and_then(skip8) else { + let Some(off) = skip8(5 + 4 + 2 + 32, 0, 32).and_then(cipher_suites_end).and_then(|p| skip8(p, 1, 255)) else { hello.partial = true; d.tls = Some(hello); return; @@ -1087,6 +1093,7 @@ fn tls(p: &[u8], d: &mut Decoded) { hello.partial |= declared_end != handshake_end; let end = declared_end.min(hello_end); let extensions = Reader::new(p.get(..end).unwrap_or(&[])); + let mut seen_extensions = BTreeSet::new(); let mut e = off + 2; while e + 4 <= end { let (Some(t), Some(l)) = (extensions.u16_be(e), extensions.u16_be(e + 2)) else { break }; @@ -1095,12 +1102,17 @@ fn tls(p: &[u8], d: &mut Decoded) { hello.partial = true; break; }; + if !seen_extensions.insert(t) { + hello.partial = true; + e = body + usize::from(l); + continue; + } let dr = Reader::new(data); match t { 0 => { if let Some(len) = dr.u16_be(0) { let list_end = 2 + usize::from(len); - hello.partial |= list_end != data.len(); + hello.partial |= len == 0 || list_end != data.len(); let names = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); let mut a = 2; while a < list_end.min(data.len()) { @@ -1113,9 +1125,9 @@ fn tls(p: &[u8], d: &mut Decoded) { break; }; if kind == 0 { - if name.is_empty() { + if name.is_empty() || hello.sni.is_some() { hello.partial = true; - } else if hello.sni.is_none() { + } else { hello.sni = Some(name.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' }).collect()); } } @@ -1128,10 +1140,10 @@ fn tls(p: &[u8], d: &mut Decoded) { 16 => { if let Some(len) = dr.u16_be(0) { let list_end = 2 + usize::from(len); - hello.partial |= list_end != data.len(); + hello.partial |= len == 0 || list_end != data.len(); let protocols = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); let mut a = 2usize; - while a < list_end.min(data.len()) && hello.alpn.len() < 16 { + while a < list_end.min(data.len()) { let Some(n) = protocols.u8(a).filter(|&n| n > 0) else { hello.partial = true; break; @@ -1140,7 +1152,9 @@ fn tls(p: &[u8], d: &mut Decoded) { hello.partial = true; break; }; - hello.alpn.push(String::from_utf8_lossy(proto).into_owned()); + if hello.alpn.len() < 16 { + hello.alpn.push(String::from_utf8_lossy(proto).into_owned()); + } a += 1 + usize::from(n); } } else { @@ -1150,7 +1164,7 @@ fn tls(p: &[u8], d: &mut Decoded) { 43 => { if let Some(len) = dr.u8(0) { let list_end = 1 + usize::from(len); - hello.partial |= list_end != data.len() || len % 2 != 0; + hello.partial |= len < 2 || list_end != data.len() || len % 2 != 0; let versions = Reader::new(data.get(..list_end.min(data.len())).unwrap_or(&[])); let mut a = 1usize; while let Some(v) = versions.u16_be(a) { diff --git a/crates/pcap/tests/regression_tls_bounds.rs b/crates/pcap/tests/regression_tls_bounds.rs index 674ff7942..b616df155 100644 --- a/crates/pcap/tests/regression_tls_bounds.rs +++ b/crates/pcap/tests/regression_tls_bounds.rs @@ -100,3 +100,74 @@ fn complete_hello_metadata_is_unchanged() { assert_eq!(hello.supported_versions, ["TLS 1.3", "TLS 1.2"]); assert!(!hello.partial); } + +fn hello_with_vectors(session: &[u8], suites: &[u8], compression: &[u8], extensions: &[(u16, &[u8])]) -> craft_anything_formats::pcap::TlsHello { + let mut record = client_hello("unused.test"); + record.truncate(43); + record.push(session.len() as u8); + record.extend(session); + record.extend((suites.len() as u16).to_be_bytes()); + record.extend(suites); + record.push(compression.len() as u8); + record.extend(compression); + let mut ext = Vec::new(); + for (kind, bytes) in extensions { + ext.extend(kind.to_be_bytes()); + ext.extend((bytes.len() as u16).to_be_bytes()); + ext.extend(*bytes); + } + record.extend((ext.len() as u16).to_be_bytes()); + record.extend(ext); + let len = record.len(); + record[3..5].copy_from_slice(&((len - 5) as u16).to_be_bytes()); + record[6..9].copy_from_slice(&((len - 9) as u32).to_be_bytes()[1..]); + decoded(&record).tls.unwrap() +} + +#[test] +fn hello_vectors_must_have_protocol_lengths() { + assert!(!hello_with_vectors(&[0; 32], &[0, 47], &[0], &[]).partial); + assert!(hello_with_vectors(&[0; 33], &[0, 47], &[0], &[]).partial); + for suites in [&[][..], &[0, 47, 0][..]] { + assert!(hello_with_vectors(&[], suites, &[0], &[]).partial); + } + assert!(hello_with_vectors(&[], &[0, 47], &[], &[]).partial); + for (kind, empty) in [(0, &[0, 0][..]), (16, &[0, 0][..]), (43, &[0][..])] { + assert!(hello_with_vectors(&[], &[0, 47], &[0], &[(kind, empty)]).partial); + } +} + +#[test] +fn only_registered_grease_patterns_are_removed() { + let hello = hello_with_vectors(&[], &[0, 47], &[0], &[(43, &[6, 0x1a, 0x2a, 0x4a, 0x4a, 3, 4])]); + assert!(!hello.partial); + assert_eq!(hello.supported_versions, ["0x1a2a", "TLS 1.3"]); +} + +#[test] +fn duplicate_extensions_and_repeated_host_names_are_incomplete() { + let hello = hello_with_vectors(&[], &[0, 47], &[0], &[(43, &[2, 3, 4]), (43, &[2, 3, 3])]); + assert!(hello.partial); + assert_eq!(hello.supported_versions, ["TLS 1.3"]); + let hello = hello_with_vectors(&[], &[0, 47], &[0], &[(0, &[0, 8, 0, 0, 1, b'a', 0, 0, 1, b'b'])]); + assert!(hello.partial); + assert_eq!(hello.sni.as_deref(), Some("a")); +} + +#[test] +fn the_alpn_display_limit_does_not_hide_a_damaged_tail() { + let mut protocols = vec![0, 33]; + for _ in 0..16 { + protocols.extend([1, b'x']); + } + protocols.push(3); + let hello = hello_with_vectors(&[], &[0, 47], &[0], &[(16, &protocols)]); + assert_eq!(hello.alpn.len(), 16); + assert!(hello.partial); + protocols[1] = 34; + protocols.pop(); + protocols.extend([1, b'y']); + let hello = hello_with_vectors(&[], &[0, 47], &[0], &[(16, &protocols)]); + assert_eq!(hello.alpn.len(), 16); + assert!(!hello.partial); +} From 89152c14d8e2fd81d101a18f2b598192e1734edf Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:50 -0500 Subject: [PATCH 34/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything aed326ca6d74bfd119a3d1b191257c8f06fe3c51. --- crates/pcap/src/lib.rs | 120 +++++++++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 17 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 695256f81..53fe2e44e 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -12,7 +12,7 @@ use serde::Serialize; use std::collections::{BTreeMap, BTreeSet, HashMap}; use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; -/// Most frames and rejected simple packet blocks read from one capture. +/// Most accepted and rejected packet records read from one capture. pub const MAX_PACKETS: u64 = 5_000_000; /// Most flows tracked; later flows are counted but get no id. pub const MAX_FLOWS: usize = 100_000; @@ -90,7 +90,10 @@ pub struct Capture<'a> { pub truncated: bool, count: u64, rejected_simple_blocks: u64, - rejected_simple_reported: bool, + rejected_short_blocks: u64, + rejected_interfaces: u64, + invalid_fractions: u64, + warnings_reported: bool, } fn rd_u16(r: &Reader<'_>, le: bool, off: usize) -> Option { @@ -129,7 +132,10 @@ impl<'a> Capture<'a> { truncated: false, count: 0, rejected_simple_blocks: 0, - rejected_simple_reported: false, + rejected_short_blocks: 0, + rejected_interfaces: 0, + invalid_fractions: 0, + warnings_reported: false, }; let classic = |le: bool, nanos: bool| -> Result<(Kind, String, Interface), FormatError> { let major = rd_u16(&r, le, 4).ok_or_else(|| FormatError::Truncated("pcap header".into()))?; @@ -173,7 +179,7 @@ impl<'a> Capture<'a> { } fn packet_limit_reached(&mut self) -> bool { - if self.count.saturating_add(self.rejected_simple_blocks) < MAX_PACKETS { + if self.count + self.rejected_simple_blocks + self.rejected_short_blocks + self.rejected_interfaces < MAX_PACKETS { return false; } if !self.truncated && self.pos < self.data.len() { @@ -183,12 +189,24 @@ impl<'a> Capture<'a> { true } - fn report_rejected_simple_blocks(&mut self) { - if self.rejected_simple_blocks > 0 && !self.rejected_simple_reported { + fn report_packet_warnings(&mut self) { + if self.warnings_reported { + return; + } + self.warnings_reported = true; + if self.rejected_short_blocks > 0 { + self.warnings.push(format!("skipped {} packet block(s) with captured data past the end", self.rejected_short_blocks)); + } + if self.rejected_interfaces > 0 { + self.warnings.push(format!("skipped {} packet block(s) naming an undeclared interface", self.rejected_interfaces)); + } + if self.invalid_fractions > 0 { + self.warnings.push(format!("ignored {} timestamp(s) with a fraction outside its second", self.invalid_fractions)); + } + if self.rejected_simple_blocks > 0 { let n = self.rejected_simple_blocks; let suffix = if n == 1 { "" } else { "s" }; self.warnings.push(format!("skipped {n} simple packet block{suffix} with inconsistent captured lengths")); - self.rejected_simple_reported = true; } } @@ -196,7 +214,11 @@ impl<'a> Capture<'a> { let (base, exp) = self.interfaces.get(iface).map(|i| i.tsresol).unwrap_or((10, 6)); let offset_s = self.interfaces.get(iface).map(|i| i.tsoffset).unwrap_or(0); let ns = if base == 10 { - if exp <= 9 { u128::from(units) * 10u128.pow(u32::from(9 - exp)) } else { u128::from(units) / 10u128.checked_pow(u32::from(exp - 9))? } + if exp <= 9 { + u128::from(units) * 10u128.pow(u32::from(9 - exp)) + } else { + 10u128.checked_pow(u32::from(exp - 9)).map_or(0, |scale| u128::from(units) / scale) + } } else { (u128::from(units) * 1_000_000_000) >> exp.min(127) }; @@ -229,8 +251,14 @@ impl<'a> Capture<'a> { return self.stop(format!("record at offset {p} claims {incl} bytes past the end of the file")); }; self.pos = p + 16 + body.len(); - let units = u64::from(sec) * if nanos { 1_000_000_000 } else { 1_000_000 } + u64::from(frac); - Some(self.frame(0, units, body, orig)) + let per_second = if nanos { 1_000_000_000 } else { 1_000_000 }; + let units = u64::from(sec) * u64::from(per_second) + u64::from(frac); + let mut frame = self.frame(0, units, body, orig); + if frac >= per_second { + self.invalid_fractions += 1; + frame.ts_ns = None; + } + Some(frame) } fn next_ng(&mut self, mut le: bool) -> Option> { @@ -323,15 +351,14 @@ impl<'a> Capture<'a> { ) }; let (Some(iface), Some(hi), Some(lo), Some(cap), Some(orig)) = (iface, hi, lo, cap, orig) else { continue }; - let Some(data) = usize::try_from(cap).ok().filter(|&c| body + 20 + c <= body_end).and_then(|c| r.slice(body + 20, c)) else { - self.warnings.push(format!("packet block at offset {p} claims more bytes than it holds; skipped")); + let Some(data) = usize::try_from(cap).ok().filter(|&c| c <= body_end - (body + 20)).and_then(|c| r.slice(body + 20, c)) else { + self.rejected_short_blocks += 1; continue; }; - let iface = self.section_base + iface; - if iface >= self.interfaces.len() { - self.warnings.push(format!("packet block at offset {p} names an undeclared interface; skipped")); + let Some(iface) = self.section_base.checked_add(iface).filter(|&id| id < self.interfaces.len()) else { + self.rejected_interfaces += 1; continue; - } + }; return Some(self.frame(iface, (u64::from(hi) << 32) | u64::from(lo), data, orig)); } 3 => { @@ -346,6 +373,7 @@ impl<'a> Capture<'a> { } let Some(data) = r.slice(body + 4, cap) else { continue }; if iface >= self.interfaces.len() { + self.rejected_interfaces += 1; continue; } // Simple packet blocks carry no timestamp. @@ -378,7 +406,7 @@ impl<'a> Iterator for Capture<'a> { } }; if frame.is_none() { - self.report_rejected_simple_blocks(); + self.report_packet_warnings(); } frame } @@ -1524,6 +1552,64 @@ mod tests { assert_eq!(cap.pos, data.len() - valid.len()); } + #[test] + fn malformed_packet_blocks_share_the_budget_and_report_each_reason_once() { + use craft_anything_testkit::pcap::block; + let mut data = pcapng(&[]); + for kind in [2, 6] { + let mut body = [0; 20]; + body[12..16].copy_from_slice(&u32::MAX.to_le_bytes()); + data.extend(block(kind, &body)); + } + let mut body = [0; 20]; + body[..4].copy_from_slice(&u32::MAX.to_le_bytes()); + data.extend(block(6, &body)); + let mut shb = pcapng(&[]); + shb.truncate(28); + data.extend(shb); + data.extend(block(3, &[0; 4])); // No interface in this section. + data.extend(block(3, &[0; 4])); + let mut cap = Capture::new(&data).unwrap(); + cap.count = MAX_PACKETS - 4; + assert!(cap.next().is_none()); + assert!(cap.truncated); + assert_eq!(cap.warnings.len(), 3); + assert!(cap.warnings.iter().any(|s| s.contains("2 packet block(s) naming"))); + assert!(cap.warnings.iter().any(|s| s.contains("2 packet block(s) with"))); + assert!(cap.next().is_none()); + assert_eq!(cap.warnings.len(), 3); + } + + #[test] + fn invalid_classic_fractions_do_not_move_the_capture_period() { + for (magic, scale) in [(CLASSIC_US, 1_000_000u32), (CLASSIC_NS, 1_000_000_000)] { + let mut data = pcap(&[vec![], vec![]]); + data[..4].copy_from_slice(&magic.to_le_bytes()); + data[28..32].copy_from_slice(&scale.to_le_bytes()); + data[44..48].copy_from_slice(&(scale - 1).to_le_bytes()); + let mut cap = Capture::new(&data).unwrap(); + assert_eq!(cap.next().unwrap().ts_ns, None); + assert!(cap.next().unwrap().ts_ns.is_some()); + assert!(cap.next().is_none()); + assert_eq!(cap.warnings.len(), 1); + } + } + + #[test] + fn subnanosecond_decimal_resolutions_keep_the_interface_offset() { + use craft_anything_testkit::pcap::block; + let mut data = pcapng(&[]); + data.truncate(28); + let mut idb = vec![1, 0, 0, 0, 0, 0, 0, 0, 9, 0, 1, 0, 127, 0, 0, 0, 14, 0, 8, 0]; + idb.extend(2i64.to_le_bytes()); + data.extend(block(1, &idb)); + let mut epb = [0; 20]; + epb[4..12].fill(0xff); + data.extend(block(6, &epb)); + let frame = Capture::new(&data).unwrap().next().unwrap(); + assert_eq!(frame.ts_ns, Some(2_000_000_000)); + } + #[test] fn tcp_cut_inside_header_keeps_ports() { // Ports sit in the first 4 bytes; a cut later in the header must not drop them (as UDP). From 03e190a52fd6a45a3490ddd12bec9e1e625eb977 Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:51 -0500 Subject: [PATCH 35/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything d8087e70fc2990f3b261d122427d9d4e0cde7e0c. --- crates/pcap/src/lib.rs | 92 +++++++++++++++++++++++----- crates/pcap/tests/dns_rdata_names.rs | 85 +++++++++++++++++++++++++ 2 files changed, 161 insertions(+), 16 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 53fe2e44e..221947261 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -768,7 +768,7 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { Some(length) if length < 12 => d.note = Some("DNS over TCP length is smaller than its header".into()), Some(length) => { if let Some(message) = framed.slice(2, usize::from(length)) { - dns(message, d, "dns"); + dns(message, d, "dns", false); } else { d.note = Some("DNS over TCP message cut short".into()); } @@ -800,9 +800,9 @@ fn transport(proto: u8, p: &[u8], d: &mut Decoded) { }; d.transport = Some(Transport { protocol: "udp", src_port: Some(sp), dst_port: Some(dp), payload_len: payload.len(), ..empty }); if sp == 53 || dp == 53 { - dns(payload, d, "dns"); + dns(payload, d, "dns", false); } else if sp == 5353 || dp == 5353 { - dns(payload, d, "mdns"); + dns(payload, d, "mdns", dp == 5353); } } 1 | 58 => { @@ -827,6 +827,7 @@ pub fn qtype_name(t: u16) -> String { 33 => "SRV".into(), 64 => "SVCB".into(), 65 => "HTTPS".into(), + 257 => "CAA".into(), 255 => "ANY".into(), n => format!("TYPE{n}"), } @@ -844,7 +845,7 @@ fn dns_sd_service_label(label: &[u8]) -> bool { } /// A DNS name, the offset after it, and whether its wire labels name a DNS-SD instance. -fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize, bool)> { +fn dns_name(msg: &[u8], mut off: usize, allow_compression: bool) -> Option<(String, usize, bool)> { let mut out = String::new(); // Count the expanded wire name, including label lengths and the terminating root. let mut wire_len = 1usize; @@ -855,7 +856,7 @@ fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize, bool)> { let len = *msg.get(off)?; match len { 0 => return Some((if out.is_empty() { ".".into() } else { out }, after.unwrap_or(off + 1), labels >= 4 && service_instance)), - l if l & 0xc0 == 0xc0 => { + l if allow_compression && l & 0xc0 == 0xc0 => { let ptr = usize::from(u16::from_be_bytes([l & 0x3f, *msg.get(off + 1)?])); after.get_or_insert(off + 2); if ptr >= off { @@ -891,9 +892,12 @@ fn dns_name(msg: &[u8], mut off: usize) -> Option<(String, usize, bool)> { /// Decode a bounded set of DNS questions and answer/prerequisite records from one message. /// Preserve complete entries before malformed data and mark the message incomplete. -fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { +fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) { let r = Reader::new(msg); let (Some(id), Some(flags), Some(qd), Some(an)) = (r.u16_be(0), r.u16_be(2), r.u16_be(4), r.u16_be(6)) else { return }; + if msg.len() < 12 { + return; + } let opcode = (flags >> 11) & 0xf; // Sanity: opcode 0–6 and no absurd counts, so random payload on port 53 isn't misread. if opcode > 6 || qd > 64 || qd == 0 && an == 0 { @@ -903,7 +907,7 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { let mut out = Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false }; let mut off = 12usize; for _ in 0..qd { - let Some((name, next, _)) = dns_name(msg, off) else { + let Some((name, next, _)) = dns_name(msg, off, true) else { out.incomplete = true; break; }; @@ -917,7 +921,7 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { } if !out.incomplete { for _ in 0..an.min(64) { - let Some((name, next, service_instance)) = dns_name(msg, off) else { + let Some((name, next, service_instance)) = dns_name(msg, off, true) else { out.incomplete = true; break; }; @@ -930,7 +934,13 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { out.incomplete = true; break; }; + let end = rd_off + rd.len(); + let within_record = msg.get(..end).unwrap_or(&[]); + let record_class = if mdns_wire_format { class & 0x7fff } else { class }; + let empty_prerequisite = rd.is_empty() && opcode == 5 && matches!(class, 254 | 255) && ttl == 0; let value = match (rt, rd.len()) { + (1 | 28 | 6 | 33 | 257, 0) if empty_prerequisite => String::new(), + (1 | 28, _) if record_class != 1 => format!("<{} bytes>", rd.len()), (1, 4) => Ipv4Addr::new( rd.first().copied().unwrap_or(0), rd.get(1).copied().unwrap_or(0), @@ -939,16 +949,65 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { ) .to_string(), (28, 16) => Ipv6Addr::from(<[u8; 16]>::try_from(rd).unwrap_or([0; 16])).to_string(), + (1 | 28, _) => { + out.incomplete = true; + break; + } + (33, _) => { + let fields = Reader::new(rd); + let Some((target, _, _)) = dns_name(within_record, rd_off + 6, mdns_wire_format).filter(|(_, after, _)| *after == end) else { + out.incomplete = true; + break; + }; + let (Some(priority), Some(weight), Some(port)) = (fields.u16_be(0), fields.u16_be(2), fields.u16_be(4)) else { + out.incomplete = true; + break; + }; + format!("{priority} {weight} {port} {target}") + } + (6, _) => { + let soa = dns_name(within_record, rd_off, true).and_then(|(primary, pos, _)| { + let (mailbox, pos, _) = dns_name(within_record, pos, true)?; + let (words, tail) = within_record.get(pos..)?.as_chunks::<4>(); + if !tail.is_empty() { + return None; + } + let words: &[[u8; 4]; 5] = words.try_into().ok()?; + let [serial, refresh, retry, expire, minimum] = words.map(u32::from_be_bytes); + Some(format!("{primary} {mailbox} {serial} {refresh} {retry} {expire} {minimum}")) + }); + let Some(soa) = soa else { + out.incomplete = true; + break; + }; + soa + } + (257, _) => { + let Some((&flags, rest)) = rd.split_first() else { + out.incomplete = true; + break; + }; + let caa = rest.split_first().and_then(|(&n, body)| body.split_at_checked(usize::from(n))).and_then(|(tag, value)| { + (!tag.is_empty() && tag.iter().all(u8::is_ascii_alphanumeric)).then(|| { + let value: String = value.iter().flat_map(|&byte| std::ascii::escape_default(byte)).map(char::from).collect(); + format!("{flags} {} {value}", String::from_utf8_lossy(tag)) + }) + }); + let Some(caa) = caa else { + out.incomplete = true; + break; + }; + caa + } (2 | 5 | 12 | 15, _) => { // RFC 2136 prerequisites can name an RRset without carrying its value. if rd.is_empty() && opcode == 5 && matches!(class, 254 | 255) && ttl == 0 { String::new() } else { - let end = rd_off + rd.len(); let start = rd_off + if rt == 15 { 2 } else { 0 }; // Keep earlier bytes available to compression pointers, but the encoded // name itself must fit the record and account for all of its RDATA. - let Some((name, _, _)) = dns_name(msg.get(..end).unwrap_or(&[]), start).filter(|(_, after, _)| *after == end) else { + let Some((name, _, _)) = dns_name(within_record, start, true).filter(|(_, after, _)| *after == end) else { out.incomplete = true; break; }; @@ -991,6 +1050,7 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str) { off = rd_off + usize::from(rdlen); } } + out.incomplete |= flags & 0x0200 != 0; d.dns = Some(out); } @@ -1313,7 +1373,7 @@ pub struct Summary { /// "name TYPE value" from DNS responses. pub dns_answers: Vec, /// "question A|AAAA address" from DNS responses: each address answered, keyed by the response's first - /// question (so CNAME chains end at the name that was asked), as Wireshark's fields report them. + /// question (so CNAME chains end at the name that was asked), or the record owner in a questionless reply. pub dns_addresses: Vec, /// "METHOD host target" from HTTP/1.x requests. pub http_requests: Vec, @@ -1438,11 +1498,11 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result().is_ok()) { - addresses.add(format!("{} {} {}", q.name, a.rtype, a.value)); + // Questionless replies (including unsolicited mDNS) name the address in the answer. + let name = dns.questions.first().map_or(&a.name, |q| &q.name); + addresses.add(format!("{name} {} {}", a.rtype, a.value)); } } } @@ -1919,6 +1979,6 @@ mod tests { let _ = summarize(&pcap(&f), &|| false); } // DNS compression loops are refused. - assert!(dns_name(&[0xc0, 0x00], 0).is_none()); + assert!(dns_name(&[0xc0, 0x00], 0, true).is_none()); } } diff --git a/crates/pcap/tests/dns_rdata_names.rs b/crates/pcap/tests/dns_rdata_names.rs index 88b7315b7..7d7d00644 100644 --- a/crates/pcap/tests/dns_rdata_names.rs +++ b/crates/pcap/tests/dns_rdata_names.rs @@ -182,3 +182,88 @@ fn value_dependent_update_name_prerequisites_keep_their_values() { } } } + +#[test] +fn an_in_address_requires_the_right_wire_size_but_update_prerequisites_may_be_empty() { + for (kind, bad) in [(1, &[1, 2, 3][..]), (28, &[0; 15][..])] { + let mut msg = response(kind, bad, bad.len()); + assert!(decode(1, &packet(&msg)).dns.unwrap().incomplete); + msg = response(kind, &[], 0); + msg[2..4].copy_from_slice(&0x2800u16.to_be_bytes()); + let n = msg.len(); + msg[n - 8..n - 6].copy_from_slice(&255u16.to_be_bytes()); + msg[n - 6..n - 2].fill(0); + let dns = decode(1, &packet(&msg)).dns.unwrap(); + assert!(!dns.incomplete); + assert_eq!(dns.answers[0].value, ""); + } +} + +#[test] +fn questionless_announcements_and_truncated_responses_keep_their_address() { + let mut message = vec![0, 0, 0x86, 0, 0, 0, 0, 1, 0, 0, 0, 0]; + message.extend(b"\x04node\x05local\x00\x00\x01\x80\x01\x00\x00\x00\x3c\x00\x04\xc0\x00\x02\x04"); + let frame = eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 4], [224, 0, 0, 251], &udp(5353, 5353, &message))); + let dns = decode(1, &frame).dns.unwrap(); + assert!(dns.incomplete); + assert_eq!(dns.answers.len(), 1); + assert_eq!(summarize(&pcap(&[frame]), &|| false).unwrap().dns_addresses[0].value, "node.local A 192.0.2.4"); + assert!(decode(1, &packet(&message[..8])).dns.is_none()); +} + +#[test] +fn service_records_report_their_fields_and_refuse_invalid_framing() { + let mut soa = vec![0xc0, 12, 0xc0, 12]; + for n in 1u32..=5 { + soa.extend(n.to_be_bytes()); + } + for (kind, data, expected) in [ + (33, &b"\x00\x01\x00\x02\x01\xbb\x03srv\x00"[..], "1 2 443 srv"), + (6, soa.as_slice(), "example.com example.com 1 2 3 4 5"), + (257, &b"\x80\x05issueca.test"[..], "128 issue ca.test"), + ] { + let dns = decode(1, &packet(&response(kind, data, data.len()))).dns.unwrap(); + assert!(!dns.incomplete); + assert_eq!(dns.answers[0].value, expected); + } + for (kind, bad) in [(33, &b"\x00\x01\x00\x02\x01\xbb\xc0\x0c"[..]), (6, &soa[..soa.len() - 1]), (257, &b"\x00\x06issue"[..])] { + let dns = decode(1, &packet(&response(kind, bad, bad.len()))).dns.unwrap(); + assert!(dns.incomplete); + assert!(dns.answers.is_empty()); + } +} + +#[test] +fn mdns_srv_targets_can_be_compressed_except_in_legacy_replies() { + let data = [0, 1, 0, 2, 1, 187, 0xc0, 12]; + let msg = response(33, &data, data.len()); + for (port, legacy) in [(5353, false), (51000, true)] { + let frame = eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 4], [192, 0, 2, 1], &udp(5353, port, &msg))); + let dns = decode(1, &frame).dns.unwrap(); + assert_eq!(dns.incomplete, legacy); + if !legacy { + assert_eq!(dns.answers[0].value, "1 2 443 example.com"); + } + } +} + +#[test] +fn caa_binary_values_remain_distinct_in_the_inventory() { + for (bytes, display) in [(&b"\xff"[..], r"\xff"), (b"\xfe", r"\xfe"), (br"\xff", r"\\xff")] { + let mut data = b"\x00\x01x".to_vec(); + data.extend(bytes); + let dns = decode(1, &packet(&response(257, &data, data.len()))).dns.unwrap(); + assert_eq!(dns.answers[0].value, format!("0 x {display}")); + } +} + +#[test] +fn only_mdns_masks_the_cache_flush_bit_in_an_address_class() { + let mut msg = response(1, &[192, 0, 2, 1], 4); + let class = msg.len() - 12; + msg[class..class + 2].copy_from_slice(&0x8001u16.to_be_bytes()); + for (port, expected) in [(53, "<4 bytes>"), (5353, "192.0.2.1")] { + let frame = eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 4], [192, 0, 2, 1], &udp(port, port, &msg))); + assert_eq!(decode(1, &frame).dns.unwrap().answers[0].value, expected); + } +} From b9f792d293e02f9abc52be9dd0e835df5eae47fe Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:51 -0500 Subject: [PATCH 36/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything bd279b18f106ae64d1ec701d86d4da7aec219fba. --- crates/pcap/src/lib.rs | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 221947261..e35f016c5 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -554,19 +554,10 @@ pub struct FlowKey { pub fn decode(link_type: u32, data: &[u8]) -> Decoded { let mut d = Decoded::default(); let r = Reader::new(data); - let (ethertype, off) = match link_type { + let (mut ethertype, mut off) = match link_type { 1 => { d.protocols.push("eth"); - let mut et = r.u16_be(12); - let mut off = 14usize; - for _ in 0..2 { - if matches!(et, Some(0x8100 | 0x88a8)) { - d.protocols.push("vlan"); - et = r.u16_be(off + 2); - off += 4; - } - } - (et, off) + (r.u16_be(12), 14usize) } 113 => { d.protocols.push("sll"); @@ -607,6 +598,16 @@ pub fn decode(link_type: u32, data: &[u8]) -> Decoded { return d; } }; + // Both Ethernet and Linux cooked headers carry an EtherType. Each VLAN + // tag supplies another EtherType after its tag-control field. + for _ in 0..2 { + if !matches!(ethertype, Some(0x8100 | 0x88a8)) { + break; + } + d.protocols.push("vlan"); + ethertype = r.u16_be(off + 2); + off += 4; + } let payload = data.get(off..).unwrap_or(&[]); match ethertype { Some(0x0800) => ipv4(payload, &mut d), @@ -1820,6 +1821,21 @@ mod tests { classic_link_word(101, true, false, 0); } + #[test] + fn linux_cooked_vlan_frames_reach_the_network_decoder() { + let ip = ipv4_pkt(17, [10, 0, 0, 1], [10, 0, 0, 2], &udp(123, 456, b"payload")); + for (link, header_len, protocol_at) in [(113, 16, 14), (276, 20, 0)] { + let mut frame = vec![0; header_len]; + frame[protocol_at..protocol_at + 2].copy_from_slice(&0x88a8_u16.to_be_bytes()); + frame.extend_from_slice(&[0, 1, 0x81, 0, 0, 2, 0x08, 0]); + frame.extend_from_slice(&ip); + let decoded = decode(link, &frame); + assert_eq!(decoded.protocols.iter().filter(|&&p| p == "vlan").count(), 2); + assert_eq!(decoded.transport.unwrap().dst_port, Some(456)); + assert!(decode(link, &frame[..header_len + 1]).ip.is_none()); + } + } + #[test] fn decodes_dns_tls_http() { let frames = sample_frames(); From 32ed24dc73b4d1724711f456826826511265e67c Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:52 -0500 Subject: [PATCH 37/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 901f99f8465b3dc26b4c1b047388bcd78579f7f5. --- crates/pcap/src/lib.rs | 111 ++++++++++++++++++++- crates/pcap/tests/dns_discovery_answers.rs | 57 +++++++++++ 2 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 crates/pcap/tests/dns_discovery_answers.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index e35f016c5..bcf634e4d 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -826,6 +826,11 @@ pub fn qtype_name(t: u16) -> String { 16 => "TXT".into(), 28 => "AAAA".into(), 33 => "SRV".into(), + 35 => "NAPTR".into(), + 39 => "DNAME".into(), + 44 => "SSHFP".into(), + 52 => "TLSA".into(), + 256 => "URI".into(), 64 => "SVCB".into(), 65 => "HTTPS".into(), 257 => "CAA".into(), @@ -891,6 +896,103 @@ fn dns_name(msg: &[u8], mut off: usize, allow_compression: bool) -> Option<(Stri None } +/// Decode discovery and authentication records whose domain names prohibit compression. +fn discovery_answer(kind: u16, rd: &[u8]) -> Option { + let r = Reader::new(rd); + let text = |b: &[u8]| b.iter().flat_map(|v| std::ascii::escape_default(*v)).map(char::from).collect::(); + let hex = |b: &[u8]| b.iter().map(|v| format!("{v:02x}")).collect::(); + match kind { + 39 => dns_name(rd, 0, false).filter(|(_, after, _)| *after == rd.len()).map(|(name, _, _)| name), + 44 => { + let (&algorithm, next) = rd.split_first()?; + let (&hash, digest) = next.split_first()?; + if digest.is_empty() || hash == 1 && digest.len() != 20 || hash == 2 && digest.len() != 32 { + return None; + } + Some(format!("{algorithm} {hash} {}", hex(digest))) + } + 52 => { + let [usage, selector, matching, cert @ ..] = rd else { return None }; + if cert.is_empty() || *matching == 1 && cert.len() != 32 || *matching == 2 && cert.len() != 64 { + return None; + } + Some(format!("{usage} {selector} {matching} {}", hex(cert))) + } + 256 => { + let target = rd.get(4..).filter(|s| !s.is_empty())?; + Some(format!("{} {} \"{}\"", r.u16_be(0)?, r.u16_be(2)?, strip_userinfo(&text(target)))) + } + 35 => { + let mut pos = 4; + let mut value = format!("{} {}", r.u16_be(0)?, r.u16_be(2)?); + for _ in 0..3 { + let len = usize::from(r.u8(pos)?); + value.push_str(&format!(" \"{}\"", text(r.slice(pos + 1, len)?))); + pos += 1 + len; + } + let (replacement, _, _) = dns_name(rd, pos, false).filter(|(_, after, _)| *after == rd.len())?; + Some(format!("{value} {replacement}")) + } + 64 | 65 => { + let priority = r.u16_be(0)?; + let (target, mut pos, _) = dns_name(rd, 2, false)?; + let mut value = format!("{priority} {target}"); + let mut previous = None; + while pos < rd.len() { + let key = r.u16_be(pos)?; + let len = usize::from(r.u16_be(pos + 2)?); + if key == u16::MAX || previous.is_some_and(|old| old >= key) { + return None; + } + let param = r.slice(pos + 4, len)?; + // Keep unknown keys lossless; interpreting them as text can fabricate an endpoint. + let field = match key { + 1 if priority != 0 => { + let mut remaining = param; + let mut ids = Vec::new(); + while let Some((&n, rest)) = remaining.split_first() { + if n == 0 { + return None; + } + let (id, tail) = rest.split_at_checked(usize::from(n))?; + ids.push(text(id).replace(',', "\\,")); + remaining = tail; + } + if ids.is_empty() { + return None; + } + format!("alpn={}", ids.join(",")) + } + 3 if priority != 0 => format!("port={}", u16::from_be_bytes(param.try_into().ok()?)), + 4 if priority != 0 => { + let (addresses, tail) = param.as_chunks::<4>(); + if addresses.is_empty() || !tail.is_empty() { + return None; + } + let hints: Vec<_> = addresses.iter().map(|ip| Ipv4Addr::from(*ip).to_string()).collect(); + format!("ipv4hint={}", hints.join(",")) + } + 6 if priority != 0 => { + let (addresses, tail) = param.as_chunks::<16>(); + if addresses.is_empty() || !tail.is_empty() { + return None; + } + let hints: Vec<_> = addresses.iter().map(|ip| Ipv6Addr::from(*ip).to_string()).collect(); + format!("ipv6hint={}", hints.join(",")) + } + _ => format!("key{key}=0x{}", hex(param)), + }; + value.push(' '); + value.push_str(&field); + previous = Some(key); + pos += len + 4; + } + Some(value) + } + _ => None, + } +} + /// Decode a bounded set of DNS questions and answer/prerequisite records from one message. /// Preserve complete entries before malformed data and mark the message incomplete. fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) { @@ -940,7 +1042,7 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) let record_class = if mdns_wire_format { class & 0x7fff } else { class }; let empty_prerequisite = rd.is_empty() && opcode == 5 && matches!(class, 254 | 255) && ttl == 0; let value = match (rt, rd.len()) { - (1 | 28 | 6 | 33 | 257, 0) if empty_prerequisite => String::new(), + (1 | 28 | 6 | 33 | 35 | 39 | 44 | 52 | 64 | 65 | 256 | 257, 0) if empty_prerequisite => String::new(), (1 | 28, _) if record_class != 1 => format!("<{} bytes>", rd.len()), (1, 4) => Ipv4Addr::new( rd.first().copied().unwrap_or(0), @@ -1042,6 +1144,13 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) } txt } + (35 | 39 | 44 | 52 | 64 | 65 | 256, _) if record_class == 1 => { + let Some(value) = discovery_answer(rt, rd) else { + out.incomplete = true; + break; + }; + value + } (_, n) => format!("<{n} bytes>"), }; if out.incomplete { diff --git a/crates/pcap/tests/dns_discovery_answers.rs b/crates/pcap/tests/dns_discovery_answers.rs new file mode 100644 index 000000000..71f4cb0a3 --- /dev/null +++ b/crates/pcap/tests/dns_discovery_answers.rs @@ -0,0 +1,57 @@ +use craft_anything_formats::pcap::{Dns, decode}; +use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, udp}; + +fn answer(kind: u16, rd: &[u8]) -> Dns { + let mut msg = dns_query(); + msg[2..4].copy_from_slice(&0x8180u16.to_be_bytes()); + msg[6..8].copy_from_slice(&1u16.to_be_bytes()); + msg.extend([0xc0, 12]); + msg.extend(kind.to_be_bytes()); + msg.extend([0, 1, 0, 0, 0, 60]); + msg.extend((rd.len() as u16).to_be_bytes()); + msg.extend(rd); + decode(1, ð(0x0800, &ipv4_pkt(17, [192, 0, 2, 2], [192, 0, 2, 1], &udp(53, 51000, &msg)))).dns.unwrap() +} + +#[test] +fn svc_binding_reports_target_and_port() { + for kind in [64, 65] { + let msg = answer(kind, b"\0\x01\x03api\0\0\x03\0\x02\x20\xfb"); + assert_eq!(msg.answers[0].value, "1 api port=8443"); + assert_eq!(answer(kind, b"\0\x01\0\0\x01\0\x03\x02h2\0\x04\0\x04\xc0\0\x02\x01").answers[0].value, "1 . alpn=h2 ipv4hint=192.0.2.1"); + assert!(answer(kind, b"\0\x01\0\0\x01\0\x01\x00").incomplete); + assert!(answer(kind, b"\0\x01\xc0\x0c").incomplete); + assert!(answer(kind, b"\0\x01\0\0\x03\0\x01\x00").incomplete); + } +} +#[test] +fn sshfp_preserves_algorithm_and_complete_digest() { + let mut d = vec![4, 2]; + d.extend([0x5a; 32]); + assert_eq!(answer(44, &d).answers[0].value, format!("4 2 {}", "5a".repeat(32))); + assert!(answer(44, &d[..15]).incomplete); +} +#[test] +fn tlsa_keeps_selector_and_certificate_association() { + let mut d = vec![3, 1, 1]; + d.extend([0xaa; 32]); + assert_eq!(answer(52, &d).answers[0].value, format!("3 1 1 {}", "aa".repeat(32))); + assert!(answer(52, &d[..4]).incomplete); +} +#[test] +fn naptr_keeps_order_preference_strings_and_replacement() { + let rd = b"\0\x0a\0\x02\x01s\x03sip\0\x03srv\0"; + assert_eq!(answer(35, rd).answers[0].value, r#"10 2 "s" "sip" "" srv"#); + assert!(answer(35, &rd[..rd.len() - 1]).incomplete); +} +#[test] +fn uri_keeps_priority_weight_and_target() { + assert_eq!(answer(256, b"\0\x02\0\x05https://x.test/s").answers[0].value, r#"2 5 "https://x.test/s""#); + assert!(answer(256, b"\0\x02\0\x05").incomplete); +} +#[test] +fn dname_only_accepts_a_complete_uncompressed_target() { + assert_eq!(answer(39, b"\x04host\0").answers[0].value, "host"); + assert!(answer(39, b"\xc0\x0c").incomplete); + assert!(answer(39, b"\x04host\0extra").incomplete); +} From 747080c6593db7e35eea920e3667879b9dba4d8b Mon Sep 17 00:00:00 2001 From: Afloat Date: Tue, 17 Nov 2026 08:37:52 -0500 Subject: [PATCH 38/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 34774fd3b3addd9c0537ec7890f2de939261911b. --- crates/pcap/src/lib.rs | 41 +++++++++++++----- crates/pcap/tests/pcap_dns_name_limit.rs | 13 ++++++ crates/pcap/tests/pcap_http_host_boundary.rs | 43 +++++++++++++++++++ .../pcap/tests/regression_pcapng_framing.rs | 11 +++++ 4 files changed, 98 insertions(+), 10 deletions(-) diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index bcf634e4d..f5203f002 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -10,6 +10,7 @@ use crate::FormatError; use crate::bytes::Reader; use serde::Serialize; use std::collections::{BTreeMap, BTreeSet, HashMap}; +use std::fmt::Write as _; use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; /// Most accepted and rejected packet records read from one capture. @@ -887,7 +888,18 @@ fn dns_name(msg: &[u8], mut off: usize, allow_compression: bool) -> Option<(Stri if !out.is_empty() { out.push('.'); } - out.extend(label.iter().map(|&c| if c.is_ascii_graphic() { char::from(c) } else { '?' })); + for &c in label { + match c { + b'.' | b'\\' => { + out.push('\\'); + out.push(char::from(c)); + } + c if c.is_ascii_graphic() => out.push(char::from(c)), + _ => { + let _ = write!(out, "\\{c:03}"); + } + } + } off += 1 + usize::from(l); } _ => return None, @@ -1179,19 +1191,28 @@ pub fn strip_userinfo(target: &str) -> String { fn tcp_app(p: &[u8], d: &mut Decoded) { let head = p.get(..p.len().min(16 << 10)).unwrap_or(p); - let line_end = head.windows(2).position(|w| w == b"\r\n").unwrap_or(head.len().min(2048)); - let line = String::from_utf8_lossy(head.get(..line_end.min(2048)).unwrap_or(&[])).into_owned(); - if let Some(rest) = line.strip_prefix("HTTP/1.") { - let status = rest.split(' ').nth(1).and_then(|s| s.parse().ok()); + let Some(line_end) = head.windows(2).position(|w| w == b"\r\n") else { + tls(p, d); + return; + }; + let line = String::from_utf8_lossy(head.get(..line_end).unwrap_or(&[])); + let version = |v: &str| matches!(v.as_bytes(), [b'H', b'T', b'T', b'P', b'/', b'1', b'.', b'0'..=b'9']); + let mut parts = line.splitn(3, ' '); + let fields = (parts.next(), parts.next(), parts.next()); + if let (Some(v), Some(code), reason) = fields + && version(v) + && matches!(code.as_bytes(), [b'1'..=b'5', b'0'..=b'9', b'0'..=b'9']) + && reason.is_none_or(|text| text.bytes().all(|b| b == b'\t' || !b.is_ascii_control())) + { d.protocols.push("http"); - d.http = - Some(Http { kind: "response", method: None, target: None, status, version: format!("HTTP/1.{}", rest.chars().next().unwrap_or('?')), host: None }); + d.http = Some(Http { kind: "response", method: None, target: None, status: code.parse().ok(), version: v.to_string(), host: None }); return; } - let mut parts = line.splitn(3, ' '); - if let (Some(m), Some(t), Some(v)) = (parts.next(), parts.next(), parts.next()) + if let (Some(m), Some(t), Some(v)) = fields && METHODS.contains(&m) - && v.starts_with("HTTP/1.") + && !t.is_empty() + && !t.bytes().any(|b| b.is_ascii_control()) + && version(v) { let mut remaining = head.get(line_end + 2..).unwrap_or(&[]); let mut host = None; diff --git a/crates/pcap/tests/pcap_dns_name_limit.rs b/crates/pcap/tests/pcap_dns_name_limit.rs index f16c89387..cf2954d70 100644 --- a/crates/pcap/tests/pcap_dns_name_limit.rs +++ b/crates/pcap/tests/pcap_dns_name_limit.rs @@ -149,3 +149,16 @@ fn root_name_rdata_remains_valid() { assert_eq!(dns.answers[1].value, "203.0.113.1"); } } + +#[test] +fn dns_label_escapes_distinguish_wire_names_in_question_and_answer_owners() { + let mut message = vec![0, 1, 0x81, 0x80, 0, 2, 0, 1, 0, 0, 0, 0]; + message.extend(b"\x03a.b\x03\\\x00\xff\x00\x00\x01\x00\x01"); + message.extend(b"\x01a\x01b\x03\\\x00\xff\x00\x00\x01\x00\x01"); + message.extend([0xc0, 12, 0, 1, 0, 1, 0, 0, 0, 0, 0, 4, 1, 2, 3, 4]); + let dns = decode(101, &ipv4_pkt(17, [1; 4], [2; 4], &udp(53, 100, &message))).dns.unwrap(); + assert!(!dns.incomplete); + assert_eq!(dns.questions[0].name, r"a\.b.\\\000\255"); + assert_eq!(dns.questions[1].name, r"a.b.\\\000\255"); + assert_eq!(dns.answers[0].name, dns.questions[0].name); +} diff --git a/crates/pcap/tests/pcap_http_host_boundary.rs b/crates/pcap/tests/pcap_http_host_boundary.rs index 13b6955d8..6937196f6 100644 --- a/crates/pcap/tests/pcap_http_host_boundary.rs +++ b/crates/pcap/tests/pcap_http_host_boundary.rs @@ -22,3 +22,46 @@ fn host_requires_a_complete_header_line_and_keeps_its_spelling() { assert!(request(b"GET / HTTP/1.1\r\nHost: cut").host.is_none()); assert_eq!(request(b"GET / HTTP/1.1\r\nHost: Real.test\r\n\r\n").host.as_deref(), Some("Real.test")); } + +#[test] +fn http_evidence_needs_a_complete_start_line() { + for input in [ + b"GET / HTTP/1.1".as_slice(), + b"GET / HTTP/1.1x\r\n", + b"GET / HTTP/1.1 extra\r\n", + b"GET HTTP/1.0\r\n", + b"GET /bad\tpath HTTP/1.1\r\n", + b"HTTP/1.garbage\r\n", + b"HTTP/1.1 20 OK\r\n", + b"HTTP/1.1 999 OK\r\n", + b"HTTP/1.1 200 OK", + b"HTTP/1.garbage 204\r\n\r\n", + b"HTTP/1.1 20\r\n\r\n", + b"HTTP/1.1 2040\r\n\r\n", + b"HTTP/1.1 999\r\n\r\n", + b"HTTP/1.1 2x4\r\n\r\n", + b"HTTP/1.1 204", + b"HTTP/1.1 204 bad\0reason\r\n\r\n", + ] { + assert!(decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, input))).http.is_none(), "{input:?}"); + } + assert_eq!(request(b"GET / HTTP/1.0\r\n").version, "HTTP/1.0"); + assert_eq!(request(b"HTTP/1.1 204 \r\n").status, Some(204)); + assert_eq!(request(b"HTTP/1.1 403 Access denied\r\n").status, Some(403)); +} + +#[test] +fn responses_with_no_reason_phrase_still_keep_the_status_code() { + for (input, version, code) in + [(b"HTTP/1.1 204\r\n\r\n".as_slice(), "HTTP/1.1", 204), (b"HTTP/1.0 200\r\nContent-Length: 0\r\n\r\n".as_slice(), "HTTP/1.0", 200)] + { + let decoded = decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(80, 100, 0x18, input))); + assert!(decoded.protocols.contains(&"http")); + let http = decoded.http.unwrap(); + assert_eq!(http.kind, "response"); + assert_eq!(http.version, version); + assert_eq!(http.status, Some(code)); + assert!(http.method.is_none()); + assert!(http.target.is_none()); + } +} diff --git a/crates/pcap/tests/regression_pcapng_framing.rs b/crates/pcap/tests/regression_pcapng_framing.rs index 69a58a6b3..1fa8679fb 100644 --- a/crates/pcap/tests/regression_pcapng_framing.rs +++ b/crates/pcap/tests/regression_pcapng_framing.rs @@ -64,3 +64,14 @@ fn big_endian_block_footers_use_the_sections_byte_order() { data[end - 4..].copy_from_slice(&20u32.to_le_bytes()); assert!(!summarize(&data, &|| false).unwrap().warnings.is_empty()); } + +#[test] +fn a_skipped_packet_before_the_first_interface_preserves_later_frames() { + let original = pcapng(&sample_frames()); + let mut data = original[..28].to_vec(); + data.extend(block(3, &[0; 4])); + data.extend(&original[28..]); + let summary = summarize(&data, &|| false).unwrap(); + assert_eq!(summary.packets, 7); + assert!(summary.warnings.iter().any(|w| w.contains("undeclared interface"))); +} From a9acede958c93be3ae2577edcdc508cb6c84f5c2 Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:53 -0500 Subject: [PATCH 39/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything d67583b183e42bdb69a5ab440d2403eea58c7b0d. --- crates/pcap/src/lib.rs | 7 ++++-- crates/pcap/tests/pcap_http_methods.rs | 32 ++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 crates/pcap/tests/pcap_http_methods.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index f5203f002..5ba79249b 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1176,7 +1176,10 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) d.dns = Some(out); } -const METHODS: &[&str] = &["GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS", "PATCH", "CONNECT", "TRACE"]; +/// HTTP method names are case-sensitive tokens, including extension methods. +fn http_method(method: &str) -> bool { + !method.is_empty() && method.bytes().all(|b| b.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&b)) +} /// Remove `user:password@` from an absolute request target. pub fn strip_userinfo(target: &str) -> String { @@ -1209,7 +1212,7 @@ fn tcp_app(p: &[u8], d: &mut Decoded) { return; } if let (Some(m), Some(t), Some(v)) = fields - && METHODS.contains(&m) + && http_method(m) && !t.is_empty() && !t.bytes().any(|b| b.is_ascii_control()) && version(v) diff --git a/crates/pcap/tests/pcap_http_methods.rs b/crates/pcap/tests/pcap_http_methods.rs new file mode 100644 index 000000000..d2bc17062 --- /dev/null +++ b/crates/pcap/tests/pcap_http_methods.rs @@ -0,0 +1,32 @@ +use craft_anything_formats::pcap::decode; +use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; + +/// WebDAV and extension methods retain the same HTTP evidence as core methods. +#[test] +fn extension_methods_are_http_requests() { + for method in ["PROPFIND", "MKCOL", "LOCK", "REPORT", "M-SEARCH", "custom", "X!#$%&'*+-.^_`|~012"] { + let request = format!("{method} /collection/ HTTP/1.1\r\nHost: dav.example\r\n\r\n"); + let decoded = decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, request.as_bytes()))); + let http = decoded.http.unwrap_or_else(|| panic!("missing HTTP: {method}")); + assert_eq!(http.method.as_deref(), Some(method)); + assert_eq!(http.target.as_deref(), Some("/collection/")); + assert_eq!(http.host.as_deref(), Some("dav.example")); + } +} + +/// A method still needs a nonempty ASCII token and a complete valid start line. +#[test] +fn invalid_extension_method_lines_are_not_http() { + for request in [ + " / HTTP/1.1\r\n", + "BAD:METHOD / HTTP/1.1\r\n", + "BAD/METHOD / HTTP/1.1\r\n", + "MÉTHOD / HTTP/1.1\r\n", + "BAD\tMETHOD / HTTP/1.1\r\n", + "PROPFIND / HTTP/1.1", + "PROPFIND / HTTP/no\r\n", + ] { + let decoded = decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, request.as_bytes()))); + assert!(decoded.http.is_none(), "{request:?}"); + } +} From 79a002518c97b57a431fc5639e1364e04988b397 Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:53 -0500 Subject: [PATCH 40/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 43bd04745f42daefd9dea16756b13816fa7485a6. --- crates/pcap/src/lib.rs | 2 +- crates/pcap/tests/pcap_tcp_ecn.rs | 33 +++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 crates/pcap/tests/pcap_tcp_ecn.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 5ba79249b..065663423 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -716,7 +716,7 @@ fn ipv6(p: &[u8], d: &mut Decoded) { } fn tcp_flags(f: u8) -> String { - let names = [(0x02, "SYN"), (0x10, "ACK"), (0x01, "FIN"), (0x04, "RST"), (0x08, "PSH"), (0x20, "URG")]; + let names = [(0x02, "SYN"), (0x10, "ACK"), (0x01, "FIN"), (0x04, "RST"), (0x08, "PSH"), (0x20, "URG"), (0x40, "ECE"), (0x80, "CWR")]; names.iter().filter(|(b, _)| f & b != 0).map(|(_, n)| *n).collect::>().join(",") } diff --git a/crates/pcap/tests/pcap_tcp_ecn.rs b/crates/pcap/tests/pcap_tcp_ecn.rs new file mode 100644 index 000000000..e8668af1d --- /dev/null +++ b/crates/pcap/tests/pcap_tcp_ecn.rs @@ -0,0 +1,33 @@ +use craft_anything_formats::pcap::decode; + +/// Decode a raw IPv4 packet with a TCP header and the specified control bits. +fn flags_on_wire(bits: u8) -> String { + let mut packet = [0u8; 40]; + packet[0] = 0x45; + packet[2..4].copy_from_slice(&40u16.to_be_bytes()); + packet[8] = 64; + packet[9] = 6; + packet[20..24].copy_from_slice(&[0xc0, 0, 0x01, 0xbb]); + packet[32] = 0x50; + packet[33] = bits; + decode(228, &packet).transport.unwrap().tcp_flags.unwrap() +} + +/// An ECN-capable SYN shows both classic ECN flags. +#[test] +fn reports_ecn_setup_on_syn() { + assert_eq!(flags_on_wire(0xc2), "SYN,ECE,CWR"); +} + +/// The receiver and sender can signal ECE and CWR independently on ACKs. +#[test] +fn distinguishes_ecn_echo_and_window_reduction() { + assert_eq!(flags_on_wire(0x50), "ACK,ECE"); + assert_eq!(flags_on_wire(0x90), "ACK,CWR"); +} + +/// Existing non-ECN packets keep their flag strings. +#[test] +fn keeps_ordinary_ack_flags() { + assert_eq!(flags_on_wire(0x12), "SYN,ACK"); +} From eb837704646f851ac47cdc55b0e554b872e7f255 Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:37:53 -0500 Subject: [PATCH 41/97] pcap: preserve capture and protocol source history Port relevant PCAP implementation and regression snapshots from Craft Anything 3836b5bd529de3db647cd433f78715fb6c2ad07f. --- crates/pcap/src/lib.rs | 5 ++- crates/pcap/tests/pcap_ipv6_no_next_header.rs | 40 +++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 crates/pcap/tests/pcap_ipv6_no_next_header.rs diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 065663423..5caa19938 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -712,7 +712,10 @@ fn ipv6(p: &[u8], d: &mut Decoded) { d.note = Some("IPv6 fragment (transport header is in the first fragment)".into()); return; } - transport(next, p.get(off..end).unwrap_or(&[]), d); + // RFC 8200: No Next Header ends the chain even if the packet has trailing bytes. + if next != 59 { + transport(next, p.get(off..end).unwrap_or(&[]), d); + } } fn tcp_flags(f: u8) -> String { diff --git a/crates/pcap/tests/pcap_ipv6_no_next_header.rs b/crates/pcap/tests/pcap_ipv6_no_next_header.rs new file mode 100644 index 000000000..fd698e393 --- /dev/null +++ b/crates/pcap/tests/pcap_ipv6_no_next_header.rs @@ -0,0 +1,40 @@ +use craft_anything_formats::pcap::decode; + +/// Build a raw IPv6 packet with the given payload and Next Header field. +fn packet(next: u8, payload: &[u8]) -> Vec { + let mut packet = vec![0; 40]; + packet[0] = 0x60; + packet[4..6].copy_from_slice(&u16::try_from(payload.len()).unwrap().to_be_bytes()); + packet[6] = next; + packet[7] = 64; + packet.extend_from_slice(payload); + packet +} + +/// Both an empty packet and bytes after No Next Header have no transport record. +#[test] +fn no_next_header_has_no_transport() { + for payload in [b"".as_slice(), b"padding"] { + let decoded = decode(229, &packet(59, payload)); + assert_eq!(decoded.ip.unwrap().protocol, 59); + assert_eq!(decoded.protocols, ["raw", "ipv6"]); + assert!(decoded.transport.is_none()); + } +} + +/// Destination Options can also end the header chain. +#[test] +fn no_next_header_after_an_extension() { + let decoded = decode(229, &packet(60, &[59, 0, 0, 0, 0, 0, 0, 0, 1, 2])); + assert_eq!(decoded.ip.unwrap().protocol, 59); + assert!(decoded.transport.is_none()); +} + +/// UDP after the same extension still yields its transport and payload. +#[test] +fn udp_after_an_extension_still_decodes() { + let decoded = decode(229, &packet(60, &[17, 0, 0, 0, 0, 0, 0, 0, 0, 10, 0, 11, 0, 9, 0, 0, 42])); + let transport = decoded.transport.unwrap(); + assert_eq!(transport.protocol, "udp"); + assert_eq!((transport.src_port, transport.dst_port, transport.payload_len), (Some(10), Some(11), 1)); +} From 33a83bab9b0cd594832aedd68fa7b3ae5c2eaaed Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 08:41:16 -0500 Subject: [PATCH 42/97] Expose shared packet capture and protocol inspection with retained bounds --- ATTRIBUTION.md | 4 + Cargo.lock | 10 ++ Cargo.toml | 1 + crates/pcap/Cargo.toml | 17 ++++ crates/pcap/src/bytes.rs | 49 +++++++++ crates/pcap/src/lib.rs | 99 ++++++++++++++----- crates/pcap/tests/dns_discovery_answers.rs | 7 +- crates/pcap/tests/dns_question_class.rs | 7 +- crates/pcap/tests/dns_rdata_names.rs | 7 +- crates/pcap/tests/pcap_dns_name_limit.rs | 7 +- crates/pcap/tests/pcap_dns_txt_lengths.rs | 7 +- crates/pcap/tests/pcap_flow_time_range.rs | 7 +- crates/pcap/tests/pcap_http_host_boundary.rs | 7 +- crates/pcap/tests/pcap_http_methods.rs | 7 +- crates/pcap/tests/pcap_ipv4_lengths.rs | 7 +- crates/pcap/tests/pcap_ipv6_fragments.rs | 7 +- crates/pcap/tests/pcap_ipv6_no_next_header.rs | 2 +- crates/pcap/tests/pcap_ipv6_version.rs | 7 +- crates/pcap/tests/pcap_tcp_ecn.rs | 2 +- crates/pcap/tests/pcapng_simple_payload.rs | 7 +- .../pcap/tests/regression_pcapng_framing.rs | 7 +- .../pcap/tests/regression_tcp_dns_framing.rs | 7 +- .../tests/regression_tcp_header_length.rs | 7 +- crates/pcap/tests/regression_tls_bounds.rs | 9 +- crates/pcap/tests/support/mod.rs | 8 +- 25 files changed, 244 insertions(+), 62 deletions(-) create mode 100644 crates/pcap/Cargo.toml create mode 100644 crates/pcap/src/bytes.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 4c86afd61..c144ce05f 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -132,3 +132,7 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. ## JSONC span-preserving editing `crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. + +## Packet capture and protocol inspection + +`crates/pcap` extracts Craft Anything `crates/formats/src/pcap.rs`, its checked byte reader primitives and synthetic packet fixtures/regressions at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the implementation, byte reader and fixtures in `f64ae3bf3c8863a982af1304e06de20653803968`. Subsequent fixes by phatloi0010, GGWA, BFlat, Afloat, NetterSilver, Max Mittelstädt and RRFZ retain separate primary-author source-history commits with immutable source revisions. Shared error/API wiring and chrono-based timestamp formatting with exhaustive day-boundary parity tests are subsequent Dylan M. Taylor changes. No packet reassembly, decryption, live capture or app analysis policy is imported. diff --git a/Cargo.lock b/Cargo.lock index 9fa1f4401..c95ed6cb8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2625,6 +2625,16 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-pcap" +version = "0.1.0" +dependencies = [ + "chrono", + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-pdf" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 50ec3c917..e4fc7a980 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-pcap = { path = "crates/pcap" } craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } craft-score = { path = "crates/score" } diff --git a/crates/pcap/Cargo.toml b/crates/pcap/Cargo.toml new file mode 100644 index 000000000..ea644cdf3 --- /dev/null +++ b/crates/pcap/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "craft-pcap" +description = "Read-only PCAP/PCAPNG and per-frame protocol inspection" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde = { workspace = true } +thiserror = { workspace = true } +chrono = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } diff --git a/crates/pcap/src/bytes.rs b/crates/pcap/src/bytes.rs new file mode 100644 index 000000000..238b5b6b8 --- /dev/null +++ b/crates/pcap/src/bytes.rs @@ -0,0 +1,49 @@ +//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range. + +#[derive(Debug, Clone, Copy)] +pub struct Reader<'a> { + data: &'a [u8], +} + +impl<'a> Reader<'a> { + pub fn new(data: &'a [u8]) -> Self { + Reader { data } + } + + pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> { + let end = off.checked_add(len)?; + self.data.get(off..end) + } + + pub fn u8(&self, off: usize) -> Option { + self.data.get(off).copied() + } + + fn arr(&self, off: usize) -> Option<[u8; N]> { + self.slice(off, N)?.try_into().ok() + } + + pub fn u16_le(&self, off: usize) -> Option { + self.arr(off).map(u16::from_le_bytes) + } + + pub fn u32_le(&self, off: usize) -> Option { + self.arr(off).map(u32::from_le_bytes) + } + + pub fn u64_le(&self, off: usize) -> Option { + self.arr(off).map(u64::from_le_bytes) + } + + pub fn u16_be(&self, off: usize) -> Option { + self.arr(off).map(u16::from_be_bytes) + } + + pub fn u32_be(&self, off: usize) -> Option { + self.arr(off).map(u32::from_be_bytes) + } + + pub fn u64_be(&self, off: usize) -> Option { + self.arr(off).map(u64::from_be_bytes) + } +} diff --git a/crates/pcap/src/lib.rs b/crates/pcap/src/lib.rs index 5caa19938..bc05c1f77 100644 --- a/crates/pcap/src/lib.rs +++ b/crates/pcap/src/lib.rs @@ -1,12 +1,32 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + //! Saved packet captures: classic pcap (microsecond and nanosecond, either byte order) and pcapng //! (section, interface, enhanced/simple/obsolete packet blocks). Frames are decoded from Ethernet //! (with VLAN tags), raw IP, Linux cooked (SLL/SLL2) and BSD loopback links into IPv4/IPv6, //! TCP/UDP/ICMP, and the application facts most people ask about: DNS questions and answers, //! HTTP/1.x request and status lines with the Host header, and the TLS ClientHello server name //! (SNI) and ALPN. Each frame is decoded on its own: no TCP reassembly, no decryption. Pure, no I/O, -//! every length checked. +//! every length checked. Input bytes remain caller-owned and must be admitted to a caller budget. +//! Packet, flow and inventory caps below are retained; they are not a total allocator-byte guarantee. -use crate::FormatError; +mod bytes; +#[cfg(test)] +#[path = "../tests/support/mod.rs"] +mod test_support; + +/// Why capture inspection could not start or finish. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum PcapError { + #[error("the file ends early ({0})")] + Truncated(String), + #[error("the file is malformed ({0})")] + Malformed(String), + #[error("not supported: {0}")] + Unsupported(String), +} + +use crate::PcapError as FormatError; use crate::bytes::Reader; use serde::Serialize; use std::collections::{BTreeMap, BTreeSet, HashMap}; @@ -245,7 +265,9 @@ impl<'a> Capture<'a> { if p >= self.data.len() { return None; } - let (Some(sec), Some(frac), Some(incl), Some(orig)) = (rd_u32(&r, le, p), rd_u32(&r, le, p + 4), rd_u32(&r, le, p + 8), rd_u32(&r, le, p + 12)) else { + let (Some(sec), Some(frac), Some(incl), Some(orig)) = + (rd_u32(&r, le, p), rd_u32(&r, le, p + 4), rd_u32(&r, le, p + 8), rd_u32(&r, le, p + 12)) + else { return self.stop(format!("record header at offset {p} is cut short")); }; let Some(body) = usize::try_from(incl).ok().and_then(|n| r.slice(p + 16, n)) else { @@ -1022,7 +1044,8 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool) return; } d.protocols.push(label); - let mut out = Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false }; + let mut out = + Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false }; let mut off = 12usize; for _ in 0..qd { let Some((name, next, _)) = dns_name(msg, off, true) else { @@ -1236,7 +1259,8 @@ fn tcp_app(p: &[u8], d: &mut Decoded) { remaining = remaining.get(end + 2..).unwrap_or(&[]); } d.protocols.push("http"); - d.http = Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host }); + d.http = + Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host }); return; } tls(p, d); @@ -1559,7 +1583,8 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result = Vec::new(); let (mut protocols, mut stacks, mut endpoints) = (Tally::default(), Tally::default(), Tally::default()); - let (mut queries, mut answers, mut http, mut sni, mut alpn) = (Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default()); + let (mut queries, mut answers, mut http, mut sni, mut alpn) = + (Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default()); let mut addresses = Tally::default(); for f in cap.by_ref() { if f.number % 4096 == 0 && cancelled() { @@ -1680,30 +1705,21 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result String { - let secs = ns / 1_000_000_000; - let (days, rem) = (secs / 86_400, secs % 86_400); - // Civil-from-days (proleptic Gregorian), valid for every u64 day count we can reach. - let z = days as i64 + 719_468; - let era = z.div_euclid(146_097); - let doe = z - era * 146_097; - let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; - let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); - let mp = (5 * doy + 2) / 153; - let day = doy - (153 * mp + 2) / 5 + 1; - let month = if mp < 10 { mp + 3 } else { mp - 9 }; - let year = yoe + era * 400 + i64::from(month <= 2); - format!("{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:09}Z", rem / 3600, rem % 3600 / 60, rem % 60, ns % 1_000_000_000) + // u64 nanoseconds span only 1970..2554, entirely within chrono's representable range. + chrono::DateTime::from_timestamp((ns / 1_000_000_000) as i64, (ns % 1_000_000_000) as u32) + .map(|time| time.to_rfc3339_opts(chrono::SecondsFormat::Nanos, true)) + .unwrap_or_default() } #[cfg(test)] mod tests { use super::*; - use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp}; + use crate::test_support::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp}; #[test] fn rejected_simple_packets_count_toward_the_scan_limit() { let mut data = pcapng(&[]); - let rejected = craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes()); + let rejected = crate::test_support::block(3, &1u32.to_le_bytes()); for _ in 0..3 { data.extend(&rejected); } @@ -1722,7 +1738,7 @@ mod tests { #[test] fn rejected_simple_packets_at_eof_do_not_report_a_truncated_scan() { let mut data = pcapng(&[]); - let rejected = craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes()); + let rejected = crate::test_support::block(3, &1u32.to_le_bytes()); for _ in 0..2 { data.extend(&rejected); } @@ -1737,8 +1753,8 @@ mod tests { #[test] fn valid_and_rejected_simple_packets_share_the_scan_limit() { let mut data = pcapng(&[]); - data.extend(craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes())); - let valid = craft_anything_testkit::pcap::block(3, &0u32.to_le_bytes()); + data.extend(crate::test_support::block(3, &1u32.to_le_bytes())); + let valid = crate::test_support::block(3, &0u32.to_le_bytes()); data.extend(&valid); data.extend(&valid); let mut cap = Capture::new(&data).unwrap(); @@ -1751,7 +1767,7 @@ mod tests { #[test] fn malformed_packet_blocks_share_the_budget_and_report_each_reason_once() { - use craft_anything_testkit::pcap::block; + use crate::test_support::block; let mut data = pcapng(&[]); for kind in [2, 6] { let mut body = [0; 20]; @@ -1794,7 +1810,7 @@ mod tests { #[test] fn subnanosecond_decimal_resolutions_keep_the_interface_offset() { - use craft_anything_testkit::pcap::block; + use crate::test_support::block; let mut data = pcapng(&[]); data.truncate(28); let mut idb = vec![1, 0, 0, 0, 0, 0, 0, 0, 9, 0, 1, 0, 127, 0, 0, 0, 14, 0, 8, 0]; @@ -2134,3 +2150,34 @@ mod tests { assert!(dns_name(&[0xc0, 0x00], 0, true).is_none()); } } + +#[cfg(test)] +mod timestamp_parity { + fn legacy_iso8601(ns: u64) -> String { + let secs = ns / 1_000_000_000; + let (days, rem) = (secs / 86_400, secs % 86_400); + // Civil-from-days (proleptic Gregorian), valid for every u64 day count we can reach. + let z = days as i64 + 719_468; + let era = z.div_euclid(146_097); + let doe = z - era * 146_097; + let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; + let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); + let mp = (5 * doy + 2) / 153; + let day = doy - (153 * mp + 2) / 5 + 1; + let month = if mp < 10 { mp + 3 } else { mp - 9 }; + let year = yoe + era * 400 + i64::from(month <= 2); + format!("{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:09}Z", rem / 3600, rem % 3600 / 60, rem % 60, ns % 1_000_000_000) + } + + #[test] + fn every_representable_day_and_boundaries_match_legacy() { + let day = 86_400_000_000_000u64; + for d in 0..=u64::MAX / day { + let ns = d * day; + assert_eq!(super::iso8601(ns), legacy_iso8601(ns)); + } + for ns in [0, 1, 999_999_999, 1_000_000_000, u64::MAX - 1, u64::MAX] { + assert_eq!(super::iso8601(ns), legacy_iso8601(ns)); + } + } +} diff --git a/crates/pcap/tests/dns_discovery_answers.rs b/crates/pcap/tests/dns_discovery_answers.rs index 71f4cb0a3..97d9dc0dc 100644 --- a/crates/pcap/tests/dns_discovery_answers.rs +++ b/crates/pcap/tests/dns_discovery_answers.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Dns, decode}; -use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Dns, decode}; +use support::{dns_query, eth, ipv4_pkt, udp}; fn answer(kind: u16, rd: &[u8]) -> Dns { let mut msg = dns_query(); diff --git a/crates/pcap/tests/dns_question_class.rs b/crates/pcap/tests/dns_question_class.rs index 609fa9af1..b6583f7f3 100644 --- a/crates/pcap/tests/dns_question_class.rs +++ b/crates/pcap/tests/dns_question_class.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{decode, summarize}; -use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{decode, summarize}; +use support::{dns_query, eth, ipv4_pkt, pcap, udp}; fn packet(message: &[u8]) -> Vec { eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 1], [192, 0, 2, 2], &udp(51000, 53, message))) diff --git a/crates/pcap/tests/dns_rdata_names.rs b/crates/pcap/tests/dns_rdata_names.rs index 7d7d00644..7e8542a0a 100644 --- a/crates/pcap/tests/dns_rdata_names.rs +++ b/crates/pcap/tests/dns_rdata_names.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{decode, summarize}; -use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{decode, summarize}; +use support::{dns_query, eth, ipv4_pkt, pcap, udp}; fn response(record_type: u16, rdata: &[u8], declared_length: usize) -> Vec { let mut message = dns_query(); diff --git a/crates/pcap/tests/pcap_dns_name_limit.rs b/crates/pcap/tests/pcap_dns_name_limit.rs index cf2954d70..82fc4e9f0 100644 --- a/crates/pcap/tests/pcap_dns_name_limit.rs +++ b/crates/pcap/tests/pcap_dns_name_limit.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Dns, decode}; -use craft_anything_testkit::pcap::{ipv4_pkt, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Dns, decode}; +use support::{ipv4_pkt, udp}; fn query(last: usize, compressed: bool) -> Dns { let mut msg = vec![0, 1, 1, 0, 0, if compressed { 2 } else { 1 }, 0, 0, 0, 0, 0, 0]; diff --git a/crates/pcap/tests/pcap_dns_txt_lengths.rs b/crates/pcap/tests/pcap_dns_txt_lengths.rs index a90207b21..56312df41 100644 --- a/crates/pcap/tests/pcap_dns_txt_lengths.rs +++ b/crates/pcap/tests/pcap_dns_txt_lengths.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Dns, decode}; -use craft_anything_testkit::pcap::{ipv4_pkt, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Dns, decode}; +use support::{ipv4_pkt, udp}; fn response(data: &[u8]) -> Dns { let mut msg = vec![0, 1, 0x81, 0x80, 0, 0, 0, 1, 0, 0, 0, 0]; diff --git a/crates/pcap/tests/pcap_flow_time_range.rs b/crates/pcap/tests/pcap_flow_time_range.rs index 96b6c128b..722121f4b 100644 --- a/crates/pcap/tests/pcap_flow_time_range.rs +++ b/crates/pcap/tests/pcap_flow_time_range.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::summarize; -use craft_anything_testkit::pcap::{block, eth, ipv4_pkt, pcap, pcapng, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::summarize; +use support::{block, eth, ipv4_pkt, pcap, pcapng, udp}; fn frame() -> Vec { eth(0x0800, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 200, b"body"))) diff --git a/crates/pcap/tests/pcap_http_host_boundary.rs b/crates/pcap/tests/pcap_http_host_boundary.rs index 6937196f6..5baa58fee 100644 --- a/crates/pcap/tests/pcap_http_host_boundary.rs +++ b/crates/pcap/tests/pcap_http_host_boundary.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Http, decode}; -use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Http, decode}; +use support::{ipv4_pkt, tcp}; fn request(data: &[u8]) -> Http { decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, data))).http.unwrap() diff --git a/crates/pcap/tests/pcap_http_methods.rs b/crates/pcap/tests/pcap_http_methods.rs index d2bc17062..57eb4e548 100644 --- a/crates/pcap/tests/pcap_http_methods.rs +++ b/crates/pcap/tests/pcap_http_methods.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::decode; -use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::decode; +use support::{ipv4_pkt, tcp}; /// WebDAV and extension methods retain the same HTTP evidence as core methods. #[test] diff --git a/crates/pcap/tests/pcap_ipv4_lengths.rs b/crates/pcap/tests/pcap_ipv4_lengths.rs index 21f1f6eac..e1ea930a0 100644 --- a/crates/pcap/tests/pcap_ipv4_lengths.rs +++ b/crates/pcap/tests/pcap_ipv4_lengths.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::decode; -use craft_anything_testkit::pcap::{ipv4_pkt, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::decode; +use support::{ipv4_pkt, udp}; #[test] fn incomplete_ipv4_base_headers_explain_why_decoding_stopped() { diff --git a/crates/pcap/tests/pcap_ipv6_fragments.rs b/crates/pcap/tests/pcap_ipv6_fragments.rs index 8f82257d1..1c413f4b3 100644 --- a/crates/pcap/tests/pcap_ipv6_fragments.rs +++ b/crates/pcap/tests/pcap_ipv6_fragments.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::decode; -use craft_anything_testkit::pcap::{eth, udp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::decode; +use support::{eth, udp}; fn packet(offset: u16, next: u8, payload: &[u8]) -> Vec { let mut ip = vec![0u8; 40]; diff --git a/crates/pcap/tests/pcap_ipv6_no_next_header.rs b/crates/pcap/tests/pcap_ipv6_no_next_header.rs index fd698e393..b00848768 100644 --- a/crates/pcap/tests/pcap_ipv6_no_next_header.rs +++ b/crates/pcap/tests/pcap_ipv6_no_next_header.rs @@ -1,4 +1,4 @@ -use craft_anything_formats::pcap::decode; +use craft_pcap::decode; /// Build a raw IPv6 packet with the given payload and Next Header field. fn packet(next: u8, payload: &[u8]) -> Vec { diff --git a/crates/pcap/tests/pcap_ipv6_version.rs b/crates/pcap/tests/pcap_ipv6_version.rs index 4e4b25dc3..f69766321 100644 --- a/crates/pcap/tests/pcap_ipv6_version.rs +++ b/crates/pcap/tests/pcap_ipv6_version.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::decode; -use craft_anything_testkit::pcap::{eth, ipv4_pkt}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::decode; +use support::{eth, ipv4_pkt}; fn raw_packets() -> (Vec, Vec) { let ipv4 = ipv4_pkt(17, [1; 4], [2; 4], &[0; 20]); diff --git a/crates/pcap/tests/pcap_tcp_ecn.rs b/crates/pcap/tests/pcap_tcp_ecn.rs index e8668af1d..278fba8fe 100644 --- a/crates/pcap/tests/pcap_tcp_ecn.rs +++ b/crates/pcap/tests/pcap_tcp_ecn.rs @@ -1,4 +1,4 @@ -use craft_anything_formats::pcap::decode; +use craft_pcap::decode; /// Decode a raw IPv4 packet with a TCP header and the specified control bits. fn flags_on_wire(bits: u8) -> String { diff --git a/crates/pcap/tests/pcapng_simple_payload.rs b/crates/pcap/tests/pcapng_simple_payload.rs index c61f6c70a..ee4743020 100644 --- a/crates/pcap/tests/pcapng_simple_payload.rs +++ b/crates/pcap/tests/pcapng_simple_payload.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::Capture; -use craft_anything_testkit::pcap::{block, pcapng}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::Capture; +use support::{block, pcapng}; fn capture(original: u32, snaplen: u32, payload: &[u8]) -> Vec { let mut out = pcapng(&[]); diff --git a/crates/pcap/tests/regression_pcapng_framing.rs b/crates/pcap/tests/regression_pcapng_framing.rs index 1fa8679fb..1ba8d2878 100644 --- a/crates/pcap/tests/regression_pcapng_framing.rs +++ b/crates/pcap/tests/regression_pcapng_framing.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::summarize; -use craft_anything_testkit::pcap::{block, pcapng, sample_frames}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::summarize; +use support::{block, pcapng, sample_frames}; #[test] fn mismatched_block_footers_stop_the_capture_with_a_warning() { diff --git a/crates/pcap/tests/regression_tcp_dns_framing.rs b/crates/pcap/tests/regression_tcp_dns_framing.rs index 4dad459bb..e85c987aa 100644 --- a/crates/pcap/tests/regression_tcp_dns_framing.rs +++ b/crates/pcap/tests/regression_tcp_dns_framing.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Decoded, decode}; -use craft_anything_testkit::pcap::{dns_query, dns_response, ipv4_pkt, tcp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Decoded, decode}; +use support::{dns_query, dns_response, ipv4_pkt, tcp}; fn decoded(payload: &[u8]) -> Decoded { decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(53, 51000, 0x18, payload))) diff --git a/crates/pcap/tests/regression_tcp_header_length.rs b/crates/pcap/tests/regression_tcp_header_length.rs index 189318116..d931f97b2 100644 --- a/crates/pcap/tests/regression_tcp_header_length.rs +++ b/crates/pcap/tests/regression_tcp_header_length.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Decoded, decode}; -use craft_anything_testkit::pcap::{ipv4_pkt, tcp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Decoded, decode}; +use support::{ipv4_pkt, tcp}; fn decoded(segment: &[u8]) -> Decoded { decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], segment)) diff --git a/crates/pcap/tests/regression_tls_bounds.rs b/crates/pcap/tests/regression_tls_bounds.rs index b616df155..92a710fc4 100644 --- a/crates/pcap/tests/regression_tls_bounds.rs +++ b/crates/pcap/tests/regression_tls_bounds.rs @@ -1,5 +1,8 @@ -use craft_anything_formats::pcap::{Decoded, decode}; -use craft_anything_testkit::pcap::{client_hello, ipv4_pkt, tcp}; +#[path = "support/mod.rs"] +mod support; + +use craft_pcap::{Decoded, decode}; +use support::{client_hello, ipv4_pkt, tcp}; fn decoded(record: &[u8]) -> Decoded { decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(51000, 443, 0x18, record))) @@ -101,7 +104,7 @@ fn complete_hello_metadata_is_unchanged() { assert!(!hello.partial); } -fn hello_with_vectors(session: &[u8], suites: &[u8], compression: &[u8], extensions: &[(u16, &[u8])]) -> craft_anything_formats::pcap::TlsHello { +fn hello_with_vectors(session: &[u8], suites: &[u8], compression: &[u8], extensions: &[(u16, &[u8])]) -> craft_pcap::TlsHello { let mut record = client_hello("unused.test"); record.truncate(43); record.push(session.len() as u8); diff --git a/crates/pcap/tests/support/mod.rs b/crates/pcap/tests/support/mod.rs index 366433bc3..f897b5142 100644 --- a/crates/pcap/tests/support/mod.rs +++ b/crates/pcap/tests/support/mod.rs @@ -1,3 +1,4 @@ +#![allow(dead_code)] //! Packet-capture fixtures: hand-built Ethernet/IPv4 frames (DNS, TCP handshake, TLS //! ClientHello, HTTP request, ARP) written as classic pcap or pcapng. @@ -104,7 +105,12 @@ pub fn sample_frames() -> Vec> { eth(0x0800, &ipv4_pkt(6, c, web, &tcp(50001, 443, 0x18, &client_hello("example.com")))), eth( 0x0800, - &ipv4_pkt(6, c, web, &tcp(50002, 80, 0x18, b"GET http://user:pw@example.com/a?b=1 HTTP/1.1\r\nHost: example.com\r\nUser-Agent: t\r\n\r\n")), + &ipv4_pkt( + 6, + c, + web, + &tcp(50002, 80, 0x18, b"GET http://user:pw@example.com/a?b=1 HTTP/1.1\r\nHost: example.com\r\nUser-Agent: t\r\n\r\n"), + ), ), eth(0x0806, &[0u8; 28]), ] From 363a51967b61e2cbaed25e9c0d6d81f75fe6b813 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 09:07:52 -0500 Subject: [PATCH 43/97] fix(audio): bound Vorbis decode allocations and strengthen oracles --- crates/audio/src/vorbis/decoder/codebook.rs | 61 +++++++++++++++++-- crates/audio/src/vorbis/decoder/mod.rs | 40 ++++++++++-- crates/audio/src/vorbis/decoder/residue.rs | 56 +++++++++++++++-- crates/audio/tests/vorbis_decode_oracle.rs | 13 ++++ crates/audio/tests/vorbis_decode_synthetic.rs | 13 +++- 5 files changed, 164 insertions(+), 19 deletions(-) diff --git a/crates/audio/src/vorbis/decoder/codebook.rs b/crates/audio/src/vorbis/decoder/codebook.rs index f892ff1bf..9d083c9e4 100644 --- a/crates/audio/src/vorbis/decoder/codebook.rs +++ b/crates/audio/src/vorbis/decoder/codebook.rs @@ -167,16 +167,18 @@ impl Codebook { let delta = float32_unpack(r.read(32).map_err(eop)?); let value_bits = r.read(4).map_err(eop)? + 1; let sequence = r.bit().map_err(eop)?; - let values = if lookup_type == 1 { lookup1_values(entries, dimensions) as usize } else { entries as usize * dimensions as usize }; + // Check before multiplying or reading multiplicands: the product can overflow + // usize on 32-bit targets, and a type-2 table otherwise allocates before admission. + let total = (entries as usize) + .checked_mul(dimensions as usize) + .filter(|&n| n <= *budget / std::mem::size_of::()) + .ok_or(Error::Limit("the codebooks' vector tables are too large"))?; + let values = if lookup_type == 1 { lookup1_values(entries, dimensions) as usize } else { total }; if !minimum.is_finite() || !delta.is_finite() || values > r.remaining() / value_bits as usize { return Err(bad("codebook lookup table is damaged or truncated")); } let multiplicands: Vec = (0..values).map(|_| r.read(value_bits).unwrap_or(0)).collect(); - let total = entries as usize * dimensions as usize; - if total.saturating_mul(4) > *budget { - return Err(Error::Limit("the codebooks' vector tables are too large")); - } - *budget -= total * 4; + *budget -= total * std::mem::size_of::(); vectors = vec![0f32; total]; for e in 0..entries as usize { let out = &mut vectors[e * dimensions as usize..(e + 1) * dimensions as usize]; @@ -349,6 +351,53 @@ mod tests { assert_eq!(book.vectors, vec![0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0]); } + #[test] + fn vector_budget_is_checked_before_reading_lookup_values() { + // A valid single-entry tree, but two values exceed the remaining budget. + // No multiplicands follow: admission must reject it before reading them. + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(1, 24); + w.put(0, 1); + w.put(0, 1); + w.put(0, 5); + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + let mut budget = std::mem::size_of::() + 4; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + + #[test] + fn vector_size_that_overflows_32_bits_is_refused() { + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(65535, 16); + w.put(65538, 24); // product is above u32::MAX + w.put(0, 1); // unordered + w.put(1, 1); // sparse: only one entry is used + w.put(1, 1); + w.put(0, 5); // length 1 + for _ in 1..65538 { + w.put(0, 1); + } + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + w.put(0, 1); // lookup type 1's single multiplicand + let mut budget = 256 << 20; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + #[test] fn helper_functions() { assert_eq!(float32_unpack((788u32 << 21) | 5), 5.0); diff --git a/crates/audio/src/vorbis/decoder/mod.rs b/crates/audio/src/vorbis/decoder/mod.rs index 8defd8aa3..7485e34b8 100644 --- a/crates/audio/src/vorbis/decoder/mod.rs +++ b/crates/audio/src/vorbis/decoder/mod.rs @@ -34,8 +34,8 @@ pub enum Error { /// The setup header is damaged or uses something Vorbis I does not allow. #[error("invalid Vorbis setup: {0}")] Setup(&'static str), - /// The stream's setup asks for more memory than the decoder allows. - #[error("Vorbis setup above the limits: {0}")] + /// The setup or decoded PCM asks for more memory than the decoder allows. + #[error("Vorbis decode above the limits: {0}")] Limit(&'static str), /// The packet is not an audio packet (a header, or a packet with its first bit set). #[error("not an audio packet")] @@ -494,7 +494,8 @@ pub struct Decoded { /// Decode the first Vorbis stream of an Ogg file. The result is trimmed to the stream's final /// granule position, so an encoder's padding at the end is dropped. Damaged packets are skipped -/// and counted, not fatal. +/// and counted, not fatal. Collected PCM is limited to 256 MiB; use the packet +/// decoder for longer streams without retaining the entire output. pub fn decode_ogg(data: &[u8]) -> Result { let ogg = craft_media::ogg::open(data).map_err(|e| Error::Ogg(e.to_string()))?; let index = ogg.stream_of(craft_media::ogg::Codec::Vorbis).ok_or_else(|| Error::Ogg("no Vorbis stream".into()))?; @@ -508,9 +509,7 @@ pub fn decode_ogg(data: &[u8]) -> Result { let packet = ogg.read_packet(data, index, i).map_err(|e| Error::Ogg(e.to_string()))?; match decoder.decode_packet(&packet) { Ok(pcm) => { - for (all, new) in channels.iter_mut().zip(pcm) { - all.extend(new); - } + append_pcm(&mut channels, pcm, 256 << 20)?; } Err(_) => damaged += 1, } @@ -522,3 +521,32 @@ pub fn decode_ogg(data: &[u8]) -> Result { } Ok(Decoded { sample_rate: decoder.id.sample_rate, channels, comments: decoder.comments.clone(), damaged_packets: damaged }) } + +// Admit every channel together before extending any of them. Limit retained PCM, +// not the compressed input, setup tables or the decoder's bounded packet scratch. +fn append_pcm(channels: &mut [Vec], pcm: Vec>, budget: usize) -> Result<()> { + let samples = channels.iter().chain(&pcm).try_fold(0usize, |n, c| n.checked_add(c.len())); + if samples.is_none_or(|n| n > budget / std::mem::size_of::()) { + return Err(Error::Limit("decoded PCM exceeds the whole-file budget")); + } + for (all, new) in channels.iter_mut().zip(pcm) { + all.try_reserve_exact(new.len()).map_err(|_| Error::Limit("cannot allocate decoded PCM"))?; + all.extend(new); + } + Ok(()) +} + +#[cfg(test)] +mod budget_tests { + use super::*; + + #[test] + fn pcm_budget_counts_all_channels_before_extending() { + let mut channels = vec![vec![1.0], vec![2.0]]; + append_pcm(&mut channels, vec![vec![3.0], vec![4.0]], 16).expect("exact budget"); + let before = channels.clone(); + assert!(matches!(append_pcm(&mut channels, vec![vec![5.0], vec![6.0]], 23), Err(Error::Limit(_)))); + assert_eq!(channels, before); + append_pcm(&mut channels, vec![Vec::new(), Vec::new()], 16).expect("empty packet"); + } +} diff --git a/crates/audio/src/vorbis/decoder/residue.rs b/crates/audio/src/vorbis/decoder/residue.rs index 48beb354b..99918d379 100644 --- a/crates/audio/src/vorbis/decoder/residue.rs +++ b/crates/audio/src/vorbis/decoder/residue.rs @@ -62,10 +62,10 @@ impl Residue { /// in `skip` is left zero. End of packet ends decoding where it is (a nominal event). pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook], n: usize, skip: &[bool], out: &mut [Vec]) { let ch = out.len(); + if skip.iter().all(|&s| s) { + return; + } if self.kind == 2 { - if skip.iter().all(|&s| s) { - return; - } let mut flat = vec![vec![0f32; n * ch]]; let _ = self.decode_vectors(r, books, n * ch, &[false], &mut flat); for i in 0..n { @@ -88,7 +88,9 @@ impl Residue { let classbook = &books[self.classbook]; let cpw = classbook.dimensions; let partitions = (end - begin) / self.partition_size; - let mut classes = vec![vec![0usize; partitions + cpw]; ch]; + // Classbook dimensions may greatly exceed the actual partition count. + // Retain only digits that this block can use, not padding per channel. + let mut classes = vec![vec![0usize; partitions]; ch]; for pass in 0..8 { let mut count = 0usize; while count < partitions { @@ -99,7 +101,9 @@ impl Residue { } let mut temp = classbook.scalar(r)? as usize; for i in (0..cpw).rev() { - classes[j][i + count] = temp % self.classifications; + if i + count < partitions { + classes[j][i + count] = temp % self.classifications; + } temp /= self.classifications; } } @@ -148,3 +152,45 @@ impl Residue { Ok(()) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn huge_class_dimensions_keep_only_actual_partitions() { + let mut data = Vec::::new(); + let mut bits = 0usize; + let mut put = |value: u32, n: usize| { + for i in 0..n { + if bits.is_multiple_of(8) { + data.push(0); + } + let last = data.len() - 1; + data[last] |= (((value >> i) & 1) as u8) << (bits % 8); + bits += 1; + } + }; + put(0x56_4342, 24); + put(65535, 16); + put(1, 24); + put(0, 1); // unordered, not sparse, one length-1 entry + put(0, 1); + put(0, 5); + put(0, 4); // scalar-only classbook + let book = Codebook::read(&mut BitReader::new(&data), &mut (1 << 20)).expect("classbook"); + let books = [book]; + for kind in [0, 1] { + let residue = Residue { kind, begin: 0, end: 32, partition_size: 1, classifications: 1, classbook: 0, books: vec![[None; 8]] }; + let mut out = vec![vec![0.0; 32]; 255]; + let packet = [0u8; 32]; + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[false; 255], &mut out); + assert_eq!(r.remaining(), 1); // one classword per channel, not 32 + assert!(out.iter().flatten().all(|&x| x == 0.0)); + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[true; 255], &mut out); + assert_eq!(r.remaining(), 256); // skipped channels consume nothing + } + } +} diff --git a/crates/audio/tests/vorbis_decode_oracle.rs b/crates/audio/tests/vorbis_decode_oracle.rs index c455c9df0..a23d2a954 100644 --- a/crates/audio/tests/vorbis_decode_oracle.rs +++ b/crates/audio/tests/vorbis_decode_oracle.rs @@ -63,6 +63,7 @@ fn assert_same(name: &str, ours: &[Vec], theirs: &[Vec]) { /// not always trim a stream to its last granule position); the common part must agree. fn assert_prefix(name: &str, ours: &[Vec], theirs: &[Vec], exact: bool) { assert_eq!(ours.len(), theirs.len(), "{name}: channel count"); + assert!(ours.iter().chain(theirs).flatten().all(|v| v.is_finite()), "{name}: non-finite oracle input or output"); let mut used = vec![false; theirs.len()]; for (c, o) in ours.iter().enumerate() { let mut best: Option<(usize, f32)> = None; @@ -201,3 +202,15 @@ fn a_libvorbis_stream_decodes_like_ffmpeg() { let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; assert_prefix("libvorbis tone.ogg", &ours.channels, &ffmpeg_decode(&ffmpeg, &path, 1), false); } + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_output() { + assert_same("NaN output", &[vec![f32::NAN]], &[vec![0.0]]); +} + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_reference() { + assert_same("NaN reference", &[vec![0.0]], &[vec![f32::NAN]]); +} diff --git a/crates/audio/tests/vorbis_decode_synthetic.rs b/crates/audio/tests/vorbis_decode_synthetic.rs index b15572006..46c48eced 100644 --- a/crates/audio/tests/vorbis_decode_synthetic.rs +++ b/crates/audio/tests/vorbis_decode_synthetic.rs @@ -278,7 +278,13 @@ fn run(name: &str, l: &Layout, seed: u32, tolerance: f32) { t.extend(c); } } - assert!(total[0].iter().all(|v| v.is_finite()), "{name}: non-finite output"); + let expected = usize::try_from(st.last_granule.expect("generated final granule")).expect("nonnegative granule"); + for channel in &total { + assert_eq!(channel.len(), expected, "{name}: decoded sample count"); + assert!(channel.iter().all(|v| v.is_finite()), "{name}: non-finite output"); + } + let whole = decode_ogg(&ogg).expect("whole file"); + assert_eq!(whole.channels, total, "{name}: packet and file decoding differ"); let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; let dir = craft_media_testkit::fixture_subdir("vorbis_synthetic"); let path = dir.join(format!("{name}.ogg")); @@ -293,7 +299,10 @@ fn run(name: &str, l: &Layout, seed: u32, tolerance: f32) { let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); let ch = usize::from(l.channels); let theirs: Vec> = (0..ch).map(|c| all.iter().skip(c).step_by(ch).copied().collect()).collect(); - let _ = decode_ogg(&ogg).expect("whole file"); + assert!(theirs.iter().flatten().all(|v| v.is_finite()), "{name}: non-finite ffmpeg output"); + for channel in &theirs { + assert!(channel.len() >= expected, "{name}: ffmpeg returned fewer than the expected samples"); + } // ffmpeg puts the channels of surround streams in its own order, so each of ours is matched // with the channel of theirs it agrees with best, and every one of theirs is used once. let mut used = vec![false; ch]; From 37bf1f34d7c4d1ddebde63af05bdc5748d0d319a Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Sat, 31 Oct 2026 10:52:14 -0400 Subject: [PATCH 44/97] Port EVM inspection: Craft Anything Source: storytold/craft-anything@f64ae3bf3c8863a982af1304e06de20653803968:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 737 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 737 insertions(+) create mode 100644 crates/evm/src/lib.rs diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs new file mode 100644 index 000000000..ed5c9f56a --- /dev/null +++ b/crates/evm/src/lib.rs @@ -0,0 +1,737 @@ +//! EVM bytecode: the public function selectors a contract's dispatcher compares against, where +//! each one jumps, whether it refuses payments, fallback/receive presence, and the compiler +//! metadata (CBOR) appended to the code. Nothing is executed; this is a linear sweep that +//! respects PUSH data plus pattern matching over the instruction stream. + +use crate::FormatError; +use serde::Serialize; +use serde_json::{Map, Value}; + +/// Largest bytecode we analyse (16 MiB; deployed contracts are at most 24 KiB). +pub const MAX_CODE: usize = 16 << 20; +const MAX_FUNCTIONS: usize = 4096; +const LISTING_CAP: usize = 400; + +/// How input bytes are encoded. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Encoding { + /// Hex when the bytes are all hex digits (with an optional 0x), raw otherwise. + Auto, + Raw, + Hex, +} + +/// Turn input bytes into bytecode. Hex is strict: optional `0x`, even length, only hex digits; +/// surrounding whitespace is ignored. +pub fn decode_input(input: &[u8], enc: Encoding) -> Result<(Vec, &'static str), FormatError> { + let trimmed = input.trim_ascii(); + let body = trimmed.strip_prefix(b"0x").or_else(|| trimmed.strip_prefix(b"0X")).unwrap_or(trimmed); + let looks_hex = !body.is_empty() && body.iter().all(u8::is_ascii_hexdigit); + let hex = match enc { + Encoding::Hex => true, + Encoding::Raw => false, + Encoding::Auto => looks_hex, + }; + if !hex { + if input.len() > MAX_CODE { + return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_CODE}", input.len()))); + } + return Ok((input.to_vec(), "raw")); + } + if body.is_empty() { + return Err(FormatError::Malformed("no hex digits".into())); + } + if let Some(p) = body.iter().position(|b| !b.is_ascii_hexdigit()) { + return Err(FormatError::Malformed(format!("not a hex digit at position {p}"))); + } + if !body.len().is_multiple_of(2) { + return Err(FormatError::Malformed(format!("odd number of hex digits ({})", body.len()))); + } + if body.len() / 2 > MAX_CODE { + return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_CODE}", body.len() / 2))); + } + let nib = |c: u8| -> u8 { + match c { + b'0'..=b'9' => c - b'0', + b'a'..=b'f' => c - b'a' + 10, + _ => c.wrapping_sub(b'A').wrapping_add(10) & 0x0f, + } + }; + Ok((body.chunks(2).map(|p| (nib(p.first().copied().unwrap_or(b'0')) << 4) | nib(p.get(1).copied().unwrap_or(b'0'))).collect(), "hex")) +} + +#[derive(Debug, Clone, Copy)] +struct Ins { + off: usize, + op: u8, + /// Immediate (PUSH data) start and length. + imm: (usize, usize), +} + +fn push_len(op: u8) -> usize { + if (0x60..=0x7f).contains(&op) { usize::from(op - 0x5f) } else { 0 } +} + +/// The mnemonic of an opcode (`UNKNOWN_0x…` for unassigned ones). +pub fn mnemonic(op: u8) -> String { + let s = match op { + 0x00 => "STOP", + 0x01 => "ADD", + 0x02 => "MUL", + 0x03 => "SUB", + 0x04 => "DIV", + 0x05 => "SDIV", + 0x06 => "MOD", + 0x07 => "SMOD", + 0x08 => "ADDMOD", + 0x09 => "MULMOD", + 0x0a => "EXP", + 0x0b => "SIGNEXTEND", + 0x10 => "LT", + 0x11 => "GT", + 0x12 => "SLT", + 0x13 => "SGT", + 0x14 => "EQ", + 0x15 => "ISZERO", + 0x16 => "AND", + 0x17 => "OR", + 0x18 => "XOR", + 0x19 => "NOT", + 0x1a => "BYTE", + 0x1b => "SHL", + 0x1c => "SHR", + 0x1d => "SAR", + 0x20 => "KECCAK256", + 0x30 => "ADDRESS", + 0x31 => "BALANCE", + 0x32 => "ORIGIN", + 0x33 => "CALLER", + 0x34 => "CALLVALUE", + 0x35 => "CALLDATALOAD", + 0x36 => "CALLDATASIZE", + 0x37 => "CALLDATACOPY", + 0x38 => "CODESIZE", + 0x39 => "CODECOPY", + 0x3a => "GASPRICE", + 0x3b => "EXTCODESIZE", + 0x3c => "EXTCODECOPY", + 0x3d => "RETURNDATASIZE", + 0x3e => "RETURNDATACOPY", + 0x3f => "EXTCODEHASH", + 0x40 => "BLOCKHASH", + 0x41 => "COINBASE", + 0x42 => "TIMESTAMP", + 0x43 => "NUMBER", + 0x44 => "PREVRANDAO", + 0x45 => "GASLIMIT", + 0x46 => "CHAINID", + 0x47 => "SELFBALANCE", + 0x48 => "BASEFEE", + 0x49 => "BLOBHASH", + 0x4a => "BLOBBASEFEE", + 0x50 => "POP", + 0x51 => "MLOAD", + 0x52 => "MSTORE", + 0x53 => "MSTORE8", + 0x54 => "SLOAD", + 0x55 => "SSTORE", + 0x56 => "JUMP", + 0x57 => "JUMPI", + 0x58 => "PC", + 0x59 => "MSIZE", + 0x5a => "GAS", + 0x5b => "JUMPDEST", + 0x5c => "TLOAD", + 0x5d => "TSTORE", + 0x5e => "MCOPY", + 0x5f => "PUSH0", + 0x60..=0x7f => return format!("PUSH{}", op - 0x5f), + 0x80..=0x8f => return format!("DUP{}", op - 0x7f), + 0x90..=0x9f => return format!("SWAP{}", op - 0x8f), + 0xa0..=0xa4 => return format!("LOG{}", op - 0xa0), + 0xf0 => "CREATE", + 0xf1 => "CALL", + 0xf2 => "CALLCODE", + 0xf3 => "RETURN", + 0xf4 => "DELEGATECALL", + 0xf5 => "CREATE2", + 0xfa => "STATICCALL", + 0xfd => "REVERT", + 0xfe => "INVALID", + 0xff => "SELFDESTRUCT", + _ => return format!("UNKNOWN_{op:#04x}"), + }; + s.to_string() +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct EvmFunction { + /// `0x` + 8 hex digits. + pub selector: String, + /// Where the dispatcher sends calls with this selector. + pub bytecode_offset: usize, + /// Offset of the comparison in the dispatcher. + pub compare_offset: usize, + pub dispatch: &'static str, + /// `eq-jumpi` (jump on match) or `eq-iszero-fallthrough` (body follows the check). + pub pattern: &'static str, + /// `nonpayable`, `payable` or `unknown` (view/pure cannot be told from the dispatcher). + pub mutability: &'static str, + /// Why the mutability was chosen. + pub mutability_reason: String, + /// False when the destination is not a JUMPDEST (the match is then doubtful). + pub jumpdest_valid: bool, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct EvmMetadata { + pub offset: usize, + pub length: usize, + pub entries: Value, + pub compiler: Option, + pub ipfs: Option, + pub swarm: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct EvmInterface { + pub code_size: usize, + /// Bytes analysed after removing the metadata tail. + pub analysed_size: usize, + pub metadata: Option, + pub instructions: usize, + pub jumpdests: usize, + /// How the selector is pulled from calldata: `shr-224`, `div-2^224`, `and-mask`, or none. + pub selector_extraction: Option<&'static str>, + pub dispatcher_offset: Option, + /// `solc-like`, `vyper-like`, `mixed` or `none`. + pub style: &'static str, + pub functions: Vec, + /// Comparisons that split the selector range (binary-search dispatchers). + pub binary_search_splits: usize, + /// A CALLVALUE check that runs before any selector comparison (all functions non-payable). + pub callvalue_check_before_dispatch: bool, + pub short_calldata_check: bool, + /// `present`, `absent` or `unknown`. + pub fallback: &'static str, + /// `present` or `not-detected`. + pub receive: &'static str, + /// The dispatcher region as text (first instructions only). + pub dispatcher_listing: Vec, + pub warnings: Vec, +} + +fn sweep(code: &[u8]) -> Vec { + let mut out = Vec::with_capacity(code.len().min(1 << 20) / 2); + let mut i = 0usize; + while i < code.len() { + let op = code.get(i).copied().unwrap_or(0); + let n = push_len(op); + out.push(Ins { off: i, op, imm: (i + 1, n) }); + i = i.saturating_add(1).saturating_add(n); + } + out +} + +fn imm<'a>(code: &'a [u8], ins: &Ins) -> &'a [u8] { + // Truncated PUSH data at the end of code reads as zero-padded; we only use what exists. + let (s, n) = ins.imm; + code.get(s..s.saturating_add(n).min(code.len())).unwrap_or(&[]) +} + +fn imm_u64(code: &[u8], ins: &Ins) -> Option { + let b = imm(code, ins); + if ins.imm.1 > 8 || b.len() != ins.imm.1 { + return None; + } + Some(b.iter().fold(0u64, |a, &x| (a << 8) | u64::from(x))) +} + +fn is_push(op: u8) -> bool { + (0x60..=0x7f).contains(&op) +} + +/// Strip and decode a trailing CBOR metadata block. +fn split_metadata(code: &[u8]) -> (usize, Option) { + let n = code.len(); + if n < 4 { + return (n, None); + } + let len = usize::from(u16::from_be_bytes([code.get(n - 2).copied().unwrap_or(0), code.get(n - 1).copied().unwrap_or(0)])); + if len == 0 || len.saturating_add(2) > n { + return (n, None); + } + let start = n - 2 - len; + let Some(cbor) = code.get(start..n - 2) else { return (n, None) }; + if !matches!(cbor.first(), Some(0xa1..=0xb7 | 0xbf)) { + return (n, None); + } + let mut pos = 0usize; + let Some(v) = cbor_item(cbor, &mut pos, 0) else { return (n, None) }; + if pos != cbor.len() { + return (n, None); + } + let Value::Object(map) = &v else { return (n, None) }; + let compiler = map + .get("solc") + .and_then(|s| s.as_str().map(String::from)) + .map(|v| format!("solc {v}")) + .or_else(|| map.get("vyper").and_then(Value::as_str).map(|v| format!("vyper {v}"))); + let ipfs = map.get("ipfs").and_then(Value::as_str).map(String::from); + let swarm = map.get("bzzr1").or_else(|| map.get("bzzr0")).and_then(Value::as_str).map(String::from); + (start, Some(EvmMetadata { offset: start, length: len + 2, entries: v.clone(), compiler, ipfs, swarm })) +} + +fn cbor_arg(b: &[u8], pos: &mut usize, info: u8) -> Option { + let take = |pos: &mut usize, k: usize| -> Option { + let s = b.get(*pos..pos.checked_add(k)?)?; + *pos += k; + Some(s.iter().fold(0u64, |a, &x| (a << 8) | u64::from(x))) + }; + match info { + 0..=23 => Some(u64::from(info)), + 24 => take(pos, 1), + 25 => take(pos, 2), + 26 => take(pos, 4), + 27 => take(pos, 8), + _ => None, + } +} + +fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { + if depth > 4 { + return None; + } + let ib = *b.get(*pos)?; + *pos += 1; + let major = ib >> 5; + let info = ib & 0x1f; + match major { + 0 => cbor_arg(b, pos, info).map(Value::from), + 2 | 3 => { + let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?; + let s = b.get(*pos..pos.checked_add(n)?)?; + *pos += n; + Some(if major == 3 { Value::from(String::from_utf8_lossy(s).into_owned()) } else { Value::from(bytes_value(s)) }) + } + 4 => { + let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?.min(64); + let mut items = Vec::new(); + for _ in 0..n { + items.push(cbor_item(b, pos, depth + 1)?); + } + // A version array like [0, 3, 10] reads as "0.3.10". + if items.len() == 3 && items.iter().all(Value::is_u64) { + return Some(Value::from(items.iter().map(|v| v.to_string()).collect::>().join("."))); + } + Some(Value::Array(items)) + } + 5 => { + let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?.min(32); + let mut m = Map::new(); + for _ in 0..n { + let k = match cbor_item(b, pos, depth + 1)? { + Value::String(s) => s, + other => other.to_string(), + }; + let v = cbor_item(b, pos, depth + 1)?; + let v = match (k.as_str(), &v) { + ("solc", Value::String(s)) if s.starts_with("0x") && s.len() == 8 => { + let d: Vec = (0..3).filter_map(|i| u8::from_str_radix(s.get(2 + 2 * i..4 + 2 * i)?, 16).ok()).collect(); + if let [a, bb, c] = d.as_slice() { Value::from(format!("{a}.{bb}.{c}")) } else { v } + } + ("ipfs", Value::String(s)) if s.starts_with("0x1220") => Value::from(base58(&hex_decode(s.get(2..).unwrap_or("")))), + _ => v, + }; + m.insert(k, v); + } + Some(Value::Object(m)) + } + 7 => match info { + 20 => Some(Value::Bool(false)), + 21 => Some(Value::Bool(true)), + 22 => Some(Value::Null), + _ => None, + }, + _ => None, + } +} + +fn bytes_value(s: &[u8]) -> String { + let mut out = String::with_capacity(2 + s.len() * 2); + out.push_str("0x"); + for b in s { + out.push_str(&format!("{b:02x}")); + } + out +} + +fn hex_decode(s: &str) -> Vec { + (0..s.len() / 2).filter_map(|i| u8::from_str_radix(s.get(2 * i..2 * i + 2)?, 16).ok()).collect() +} + +fn base58(b: &[u8]) -> String { + const A: &[u8; 58] = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"; + let zeros = b.iter().take_while(|&&x| x == 0).count(); + let mut digits: Vec = Vec::new(); + for &byte in b.iter().take(128) { + let mut carry = u32::from(byte); + for d in digits.iter_mut() { + carry += u32::from(*d) << 8; + *d = (carry % 58) as u8; + carry /= 58; + } + while carry > 0 { + digits.push((carry % 58) as u8); + carry /= 58; + } + } + let mut s: String = std::iter::repeat_n('1', zeros).collect(); + s.extend(digits.iter().rev().map(|&d| char::from(*A.get(usize::from(d)).unwrap_or(&b'1')))); + s +} + +/// Analyse bytecode (already decoded from hex if needed). +pub fn analyze(code: &[u8]) -> Result { + if code.is_empty() { + return Err(FormatError::Truncated("no bytecode".into())); + } + if code.len() > MAX_CODE { + return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_CODE}", code.len()))); + } + if code.starts_with(&[0xef, 0x00]) { + return Err(FormatError::Unsupported("EVM Object Format (EOF, 0xEF00) containers are not analysed".into())); + } + let mut warnings = Vec::new(); + let (end, metadata) = split_metadata(code); + let body = code.get(..end).unwrap_or(code); + let ins = sweep(body); + let jumpdests = ins.iter().filter(|i| i.op == 0x5b).count(); + let at = |k: usize| ins.get(k); + let op_at = |k: usize| at(k).map(|i| i.op); + let index_of = |off: usize| ins.binary_search_by_key(&off, |i| i.off).ok(); + + // Selector extraction: CALLDATALOAD followed by SHR 224, DIV 2^224 or a 4-byte mask. + let mut extraction: Option<(&'static str, usize)> = None; + for (k, i) in ins.iter().enumerate() { + if i.op != 0x35 { + continue; + } + for d in 1..=6 { + let Some(n) = at(k + d) else { break }; + let kind = match n.op { + 0x60 if imm(body, n) == [0xe0] && op_at(k + d + 1) == Some(0x1c) => Some("shr-224"), + 0x7c if imm(body, n).first() == Some(&1) && imm(body, n).iter().skip(1).all(|&b| b == 0) => Some("div-2^224"), + 0x63 if imm(body, n) == [0xff, 0xff, 0xff, 0xff] && (op_at(k + d + 1) == Some(0x16) || op_at(k + d + 2) == Some(0x16)) => Some("and-mask"), + _ => None, + }; + if let Some(kind) = kind { + extraction = Some((kind, k)); + break; + } + } + if extraction.is_some() { + break; + } + } + let disp_start = extraction.map(|(_, k)| k).unwrap_or(0); + if extraction.is_none() { + warnings.push("no selector extraction (CALLDATALOAD then SHR/DIV/AND) was seen; matches below are less certain".into()); + } + + // CALLVALUE check before the dispatcher: CALLVALUE DUP1 ISZERO PUSH JUMPI. + let callvalue_before = ins.iter().take(disp_start).any(|i| i.op == 0x34); + + let mut functions: Vec = Vec::new(); + let mut splits = 0usize; + let mut last_jumpi: Option = None; + let mut solc_like = 0usize; + let mut vyper_like = 0usize; + for k in disp_start..ins.len() { + let Some(i) = at(k) else { break }; + let n = push_len(i.op); + if !(1..=4).contains(&n) { + continue; + } + let Some(sel) = imm_u64(body, i) else { continue }; + let found = |dk: usize| -> Option { + let p = at(dk)?; + (is_push(p.op) && p.imm.1 <= 3 && op_at(dk + 1) == Some(0x57)).then_some(dk) + }; + // PUSH sel, [DUP2], EQ, PUSH dest, JUMPI + let eq_k = if op_at(k + 1) == Some(0x14) { + Some(k + 1) + } else if matches!(op_at(k + 1), Some(0x80..=0x8f)) && op_at(k + 2) == Some(0x14) { + Some(k + 2) + } else { + None + }; + let mut hit: Option<(usize, usize, &'static str)> = None; + if let Some(e) = eq_k { + if let Some(pk) = found(e + 1) + && let Some(dest) = at(pk).and_then(|p| imm_u64(body, p)) + { + hit = Some((usize::try_from(dest).unwrap_or(usize::MAX), pk + 1, "eq-jumpi")); + } else if n == 4 && op_at(e + 1) == Some(0x15) && found(e + 2).is_some() { + // Vyper-style: if selector != x jump to the next check; the body follows. + if let Some(next) = at(e + 4) { + hit = Some((next.off, e + 3, "eq-iszero-fallthrough")); + } + } + } else if n == 4 { + // Vyper also loads the selector from memory: PUSH sel, PUSH1 0, MLOAD, EQ, ISZERO … + for d in 1..=3 { + if op_at(k + d) == Some(0x14) && op_at(k + d + 1) == Some(0x15) && found(k + d + 2).is_some() { + if let Some(next) = at(k + d + 4) { + hit = Some((next.off, k + d + 3, "eq-iszero-fallthrough")); + } + break; + } + } + let direct = matches!(op_at(k + 1), Some(0x10 | 0x11)) && found(k + 2).is_some(); + let via_dup = matches!(op_at(k + 1), Some(0x80..=0x8f)) && matches!(op_at(k + 2), Some(0x10 | 0x11)) && found(k + 3).is_some(); + if hit.is_none() && (direct || via_dup) { + splits += 1; + } + } + let Some((dest, jumpi_k, pattern)) = hit else { continue }; + if n < 4 && extraction.is_none() { + continue; + } + let selector = format!("0x{sel:08x}"); + if functions.iter().any(|f| f.selector == selector) { + continue; + } + if pattern == "eq-jumpi" { + solc_like += 1; + } else { + vyper_like += 1; + } + last_jumpi = Some(jumpi_k); + let di = index_of(dest); + let jumpdest_valid = pattern != "eq-jumpi" || di.and_then(at).is_some_and(|x| x.op == 0x5b); + let (mutability, reason) = if callvalue_before { + ("nonpayable", "a CALLVALUE check runs before the dispatcher, so every function refuses payments".to_string()) + } else { + match di { + Some(d) => payability(body, &ins, d, &index_of), + None => ("unknown", "the destination is not an instruction boundary".to_string()), + } + }; + functions.push(EvmFunction { + selector, + bytecode_offset: dest, + compare_offset: i.off, + dispatch: "abi", + pattern, + mutability, + mutability_reason: reason, + jumpdest_valid, + }); + if functions.len() >= MAX_FUNCTIONS { + warnings.push(format!("stopped at {MAX_FUNCTIONS} selectors")); + break; + } + } + if functions.iter().any(|f| !f.jumpdest_valid) { + warnings.push("some destinations are not JUMPDESTs; those matches may be data, not dispatch".into()); + } + + // Short calldata path and receive(). + let mut short_calldata = false; + let mut receive = "not-detected"; + let mut fallback = "unknown"; + for (k, i) in ins.iter().enumerate().take(disp_start.saturating_add(64)) { + if i.op != 0x36 { + continue; + } + if op_at(k + 1) == Some(0x15) && at(k + 2).is_some_and(|p| is_push(p.op)) && op_at(k + 3) == Some(0x57) { + receive = "present"; + } + let lt = (1..=3).find(|d| op_at(k + d) == Some(0x10)); + if let Some(d) = lt + && at(k + d + 1).is_some_and(|p| is_push(p.op)) + && op_at(k + d + 2) == Some(0x57) + { + short_calldata = true; + } + } + if let Some(j) = last_jumpi + && solc_like > 0 + { + fallback = if reverts_soon(body, &ins, j + 1, &index_of) { "absent" } else { "present" }; + } + let style = match (solc_like > 0, vyper_like > 0) { + (true, true) => "mixed", + (true, false) => "solc-like", + (false, true) => "vyper-like", + _ => "none", + }; + let listing_end = last_jumpi.map(|j| j + 8).unwrap_or(LISTING_CAP).min(LISTING_CAP); + let dispatcher_listing = ins + .iter() + .take(listing_end) + .map(|i| { + let d = imm(body, i); + if d.is_empty() && push_len(i.op) == 0 { + format!("{:#06x}: {}", i.off, mnemonic(i.op)) + } else { + format!("{:#06x}: {} {}", i.off, mnemonic(i.op), bytes_value(d)) + } + }) + .collect(); + if functions.is_empty() { + warnings.push( + "no selector dispatcher was recognised (the code may be creation code without runtime, a proxy, a library, or use a jump-table dispatcher)".into(), + ); + } + Ok(EvmInterface { + code_size: code.len(), + analysed_size: body.len(), + metadata, + instructions: ins.len(), + jumpdests, + selector_extraction: extraction.map(|(k, _)| k), + dispatcher_offset: extraction.and_then(|(_, k)| at(k)).map(|i| i.off), + style, + functions, + binary_search_splits: splits, + callvalue_check_before_dispatch: callvalue_before, + short_calldata_check: short_calldata, + fallback, + receive, + dispatcher_listing, + warnings, + }) +} + +/// Follow a function's entry for a few instructions (and up to two unconditional jumps) looking +/// for a CALLVALUE check. +fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) -> Option) -> (&'static str, String) { + let mut k = start; + let mut hops = 0; + for _ in 0..48 { + let Some(i) = ins.get(k) else { break }; + match i.op { + 0x34 => return ("nonpayable", format!("checks CALLVALUE at {:#x}", i.off)), + 0x56 => { + let target = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op)).and_then(|p| imm_u64(code, p)); + match target.and_then(|t| index_of(usize::try_from(t).ok()?)) { + Some(t) if hops < 2 => { + hops += 1; + k = t; + continue; + } + _ => return ("unknown", "jumps somewhere we cannot follow before any CALLVALUE check".into()), + } + } + 0x57 => return ("unknown", "branches before any CALLVALUE check".into()), + 0x00 | 0xf3 | 0xfd | 0xfe | 0xff | 0x35 | 0x37 | 0x54 | 0x55 | 0xf1 | 0xf4 | 0xfa | 0xa0..=0xa4 => { + return ("payable", format!("reaches {} at {:#x} without a CALLVALUE check", mnemonic(i.op), i.off)); + } + _ => {} + } + k += 1; + } + ("unknown", "no CALLVALUE check in the first instructions".into()) +} + +fn reverts_soon(code: &[u8], ins: &[Ins], mut k: usize, index_of: &dyn Fn(usize) -> Option) -> bool { + let mut hops = 0; + for _ in 0..12 { + let Some(i) = ins.get(k) else { return false }; + match i.op { + 0xfd | 0xfe => return true, + 0x56 => { + let target = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op)).and_then(|p| imm_u64(code, p)); + match target.and_then(|t| index_of(usize::try_from(t).ok()?)) { + Some(t) if hops < 2 => { + hops += 1; + k = t; + continue; + } + _ => return false, + } + } + 0x5b | 0x50 | 0x80..=0x9f | 0x5f | 0x60..=0x7f => {} + _ => return false, + } + k += 1; + } + false +} + +#[cfg(test)] +mod tests { + use super::*; + use craft_anything_testkit::formats as fx; + + #[test] + fn dispatcher_selectors_and_metadata() { + let (code, dests) = fx::evm_runtime(); + let r = analyze(&code).unwrap(); + assert_eq!(r.selector_extraction, Some("shr-224")); + assert_eq!(r.style, "solc-like"); + let sels: Vec<_> = r.functions.iter().map(|f| f.selector.clone()).collect(); + assert_eq!(sels, fx::EVM_SELECTORS.iter().map(|s| format!("0x{s:08x}")).collect::>()); + for (f, d) in r.functions.iter().zip(dests) { + assert_eq!(f.bytecode_offset, d); + assert!(f.jumpdest_valid); + } + assert_eq!(r.functions[0].mutability, "nonpayable"); + assert_eq!(r.functions[1].mutability, "nonpayable"); + assert_eq!(r.functions[2].mutability, "payable"); + assert!(r.short_calldata_check); + assert_eq!(r.fallback, "absent"); + let m = r.metadata.unwrap(); + assert_eq!(m.compiler.as_deref(), Some("solc 0.8.19")); + assert!(m.ipfs.unwrap().starts_with("Qm")); + assert_eq!(r.analysed_size + m.length, code.len()); + } + + #[test] + fn hex_input_rules() { + let (code, _) = fx::evm_runtime(); + let hex = fx::to_hex(&code); + assert_eq!(decode_input(format!(" {hex}\n").as_bytes(), Encoding::Auto).unwrap(), (code.clone(), "hex")); + assert_eq!(decode_input(&code, Encoding::Auto).unwrap().1, "raw"); + assert!(decode_input(b"0x123", Encoding::Hex).is_err()); + assert!(decode_input(b"0xzz", Encoding::Hex).is_err()); + assert!(decode_input(b"", Encoding::Hex).is_err()); + assert!(matches!(analyze(&[0xef, 0x00, 0x01]), Err(FormatError::Unsupported(_)))); + assert_eq!(base58(&[0, 0, 1]), "112"); + } + + #[test] + fn vyper_style_fallthrough() { + // PUSH1 0 CALLDATALOAD PUSH1 0xe0 SHR PUSH1 0 MSTORE PUSH4 sel PUSH1 0 MLOAD EQ ISZERO PUSH2 next JUMPI + let mut c = + vec![0x60, 0x00, 0x35, 0x60, 0xe0, 0x1c, 0x60, 0x00, 0x52, 0x63, 0x12, 0x34, 0x56, 0x78, 0x60, 0x00, 0x51, 0x14, 0x15, 0x61, 0x00, 0x20, 0x57]; + let body = c.len(); + c.extend_from_slice(&[0x34, 0x15, 0x00]); + let r = analyze(&c).unwrap(); + assert_eq!(r.style, "vyper-like"); + assert_eq!(r.functions[0].selector, "0x12345678"); + assert_eq!(r.functions[0].bytecode_offset, body); + assert_eq!(r.functions[0].mutability, "nonpayable"); + } + + #[test] + fn hostile_inputs_do_not_panic() { + let (code, _) = fx::evm_runtime(); + for m in craft_anything_testkit::mutations(&code) { + let _ = analyze(&m); + } + for n in 0..code.len() { + let _ = analyze(&code[..n]); + } + for seed in 0..200 { + let n = craft_anything_testkit::noise(seed, 300); + let _ = analyze(&n); + let _ = decode_input(&n, Encoding::Auto); + } + // A metadata length that claims everything, and nested CBOR. + let _ = analyze(&[0xa1, 0xa1, 0xa1, 0xa1, 0xa1, 0xa1, 0xa1, 0x00, 0x07]); + let _ = analyze(&[0x7f; 40]); + } +} From 47b32d58471349e15c0b652cf35db82af0817d48 Mon Sep 17 00:00:00 2001 From: Afloat Date: Mon, 9 Nov 2026 10:39:03 +0800 Subject: [PATCH 45/97] Port EVM inspection: Keep damaged CBOR metadata in the contract bytecode (R3.12) (#1122) Source: storytold/craft-anything@d065d0df84eba1232d8ad5c9185b795610a49b58:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index ed5c9f56a..f3ed730df 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -298,6 +298,7 @@ fn cbor_arg(b: &[u8], pos: &mut usize, info: u8) -> Option { } } +/// Decode one bounded metadata item. An incomplete or unsupported value invalidates the metadata trailer. fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { if depth > 4 { return None; @@ -312,10 +313,13 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?; let s = b.get(*pos..pos.checked_add(n)?)?; *pos += n; - Some(if major == 3 { Value::from(String::from_utf8_lossy(s).into_owned()) } else { Value::from(bytes_value(s)) }) + Some(if major == 3 { Value::from(std::str::from_utf8(s).ok()?) } else { Value::from(bytes_value(s)) }) } 4 => { - let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?.min(64); + let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?; + if n > 64 { + return None; + } let mut items = Vec::new(); for _ in 0..n { items.push(cbor_item(b, pos, depth + 1)?); @@ -327,7 +331,10 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { Some(Value::Array(items)) } 5 => { - let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?.min(32); + let n = usize::try_from(cbor_arg(b, pos, info)?).ok()?; + if n > 32 { + return None; + } let mut m = Map::new(); for _ in 0..n { let k = match cbor_item(b, pos, depth + 1)? { @@ -666,6 +673,26 @@ mod tests { use super::*; use craft_anything_testkit::formats as fx; + /// A plausible trailer length alone must not remove instructions from the analyzed bytecode. + #[test] + fn incomplete_cbor_must_not_shorten_the_analyzed_contract() { + // A nested array declares 65 integers but supplies just 64. The top-level map + // and its length suffix otherwise look complete. + let mut short = vec![0xa1, 0x61, b'x', 0x98, 65]; + short.extend([0; 64]); + let mut short_map = vec![0xa1, 0x61, b'x', 0xb8, 33]; + for key in 0..32 { + short_map.extend([0x18, key, 0]); + } + for cbor in [short, short_map, vec![0xa1, 0x61, b'x', 0x61, 0xff]] { + let mut code = vec![0x00]; + code.extend(&cbor); + code.extend((cbor.len() as u16).to_be_bytes()); + assert!(split_metadata(&code).1.is_none()); + assert_eq!(analyze(&code).unwrap().analysed_size, code.len()); + } + } + #[test] fn dispatcher_selectors_and_metadata() { let (code, dests) = fx::evm_runtime(); From 5624c2a8e4e20f106f7b100fd11e950bd74e4d6b Mon Sep 17 00:00:00 2001 From: Afloat Date: Mon, 9 Nov 2026 20:15:48 +0800 Subject: [PATCH 46/97] Port EVM inspection: Require a rejecting branch before labelling EVM dispatch nonpayable (R3.12) (#1323) Source: storytold/craft-anything@3f7b9a36158f7f732254051c0cc2df7832aec8d3:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 61 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index f3ed730df..94cbf74f1 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -446,8 +446,13 @@ pub fn analyze(code: &[u8]) -> Result { warnings.push("no selector extraction (CALLDATALOAD then SHR/DIV/AND) was seen; matches below are less certain".into()); } - // CALLVALUE check before the dispatcher: CALLVALUE DUP1 ISZERO PUSH JUMPI. - let callvalue_before = ins.iter().take(disp_start).any(|i| i.op == 0x34); + // Only a guard on the straight-line entry path can apply to every selector. + let callvalue_before = ins + .iter() + .take(disp_start) + .enumerate() + .take_while(|(_, i)| !matches!(i.op, 0x00 | 0x56 | 0x57 | 0xf3 | 0xfd | 0xfe | 0xff)) + .any(|(k, i)| i.op == 0x34 && rejects_value(body, &ins, k, &index_of)); let mut functions: Vec = Vec::new(); let mut splits = 0usize; @@ -620,7 +625,7 @@ fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) - for _ in 0..48 { let Some(i) = ins.get(k) else { break }; match i.op { - 0x34 => return ("nonpayable", format!("checks CALLVALUE at {:#x}", i.off)), + 0x34 if rejects_value(code, ins, k, index_of) => return ("nonpayable", format!("rejects nonzero CALLVALUE at {:#x}", i.off)), 0x56 => { let target = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op)).and_then(|p| imm_u64(code, p)); match target.and_then(|t| index_of(usize::try_from(t).ok()?)) { @@ -633,7 +638,8 @@ fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) - } } 0x57 => return ("unknown", "branches before any CALLVALUE check".into()), - 0x00 | 0xf3 | 0xfd | 0xfe | 0xff | 0x35 | 0x37 | 0x54 | 0x55 | 0xf1 | 0xf4 | 0xfa | 0xa0..=0xa4 => { + 0xfd | 0xfe => return ("unknown", "halts with an error before any CALLVALUE check".into()), + 0x00 | 0xf3 | 0xff | 0x35 | 0x37 | 0x54 | 0x55 | 0xf1 | 0xf4 | 0xfa | 0xa0..=0xa4 => { return ("payable", format!("reaches {} at {:#x} without a CALLVALUE check", mnemonic(i.op), i.off)); } _ => {} @@ -643,6 +649,26 @@ fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) - ("unknown", "no CALLVALUE check in the first instructions".into()) } +/// CALLVALUE only reads the payment. Recognize a direct test that sends the nonzero path +/// to a rejection, allowing the common DUP1 that preserves the original value for cleanup. +fn rejects_value(code: &[u8], ins: &[Ins], k: usize, index_of: &dyn Fn(usize) -> Option) -> bool { + let mut next = k + 1; + if ins.get(next).is_some_and(|i| i.op == 0x80) { + next += 1; + } + let jumps_when_zero = ins.get(next).is_some_and(|i| i.op == 0x15); + next += usize::from(jumps_when_zero); + let Some(push) = ins.get(next).filter(|i| is_push(i.op)) else { return false }; + if ins.get(next + 1).is_none_or(|i| i.op != 0x57) { + return false; + } + let Some(target) = imm_u64(code, push).and_then(|v| usize::try_from(v).ok()).and_then(index_of) else { return false }; + if ins.get(target).is_none_or(|i| i.op != 0x5b) { + return false; + } + reverts_soon(code, ins, if jumps_when_zero { next + 2 } else { target }, index_of) +} + fn reverts_soon(code: &[u8], ins: &[Ins], mut k: usize, index_of: &dyn Fn(usize) -> Option) -> bool { let mut hops = 0; for _ in 0..12 { @@ -740,7 +766,32 @@ mod tests { assert_eq!(r.style, "vyper-like"); assert_eq!(r.functions[0].selector, "0x12345678"); assert_eq!(r.functions[0].bytecode_offset, body); - assert_eq!(r.functions[0].mutability, "nonpayable"); + assert_eq!(r.functions[0].mutability, "payable", "ISZERO followed by STOP never rejects payment"); + } + + #[test] + fn nonpayable_needs_a_rejecting_nonzero_branch() { + fn dispatch(prefix: &[u8]) -> EvmInterface { + let mut code = prefix.to_vec(); + code.extend([0x5f, 0x35, 0x60, 0xe0, 0x1c, 0x63, 1, 2, 3, 4, 0x14, 0x60]); + code.extend([(code.len() + 3) as u8, 0x57, 0x00, 0x5b, 0x00]); + analyze(&code).unwrap() + } + let read_only = dispatch(&[0x34, 0x50]); // CALLVALUE POP + assert!(!read_only.callvalue_check_before_dispatch); + assert_eq!(read_only.functions[0].mutability, "payable"); + let guard = dispatch(&[0x34, 0x80, 0x15, 0x60, 9, 0x57, 0x5f, 0x80, 0xfd, 0x5b, 0x50]); + assert!(guard.callvalue_check_before_dispatch); + assert_eq!(guard.functions[0].mutability, "nonpayable"); + // The other common form jumps to REVERT for a nonzero value and otherwise skips it. + let direct = dispatch(&[0x34, 0x60, 7, 0x57, 0x60, 11, 0x56, 0x5b, 0x5f, 0x80, 0xfd, 0x5b]); + assert!(direct.callvalue_check_before_dispatch); + // Reversing that conditional rejects zero-value calls, not payments. + let reversed = dispatch(&[0x34, 0x15, 0x60, 8, 0x57, 0x60, 12, 0x56, 0x5b, 0x5f, 0x80, 0xfd, 0x5b]); + assert!(!reversed.callvalue_check_before_dispatch); + // An unconditional jump bypasses the otherwise valid guard before the dispatcher. + let bypassed = dispatch(&[0x60, 12, 0x56, 0x34, 0x80, 0x15, 0x60, 12, 0x57, 0x5f, 0x80, 0xfd, 0x5b]); + assert!(!bypassed.callvalue_check_before_dispatch); } #[test] From 1e3a26885f3ec1b4ffb58f9a6e142a99d1da7eba Mon Sep 17 00:00:00 2001 From: Afloat Date: Wed, 11 Nov 2026 01:16:26 +0800 Subject: [PATCH 47/97] Port EVM inspection: Avoid repeated selector scans in EVM dispatchers (R3.12) (#1538) Source: storytold/craft-anything@1565bd4278955161e4c704cee37bbae9f22bfb3a:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 94cbf74f1..059252dc4 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -6,6 +6,7 @@ use crate::FormatError; use serde::Serialize; use serde_json::{Map, Value}; +use std::collections::BTreeSet; /// Largest bytecode we analyse (16 MiB; deployed contracts are at most 24 KiB). pub const MAX_CODE: usize = 16 << 20; @@ -455,6 +456,7 @@ pub fn analyze(code: &[u8]) -> Result { .any(|(k, i)| i.op == 0x34 && rejects_value(body, &ins, k, &index_of)); let mut functions: Vec = Vec::new(); + let mut selectors = BTreeSet::new(); let mut splits = 0usize; let mut last_jumpi: Option = None; let mut solc_like = 0usize; @@ -510,10 +512,10 @@ pub fn analyze(code: &[u8]) -> Result { if n < 4 && extraction.is_none() { continue; } - let selector = format!("0x{sel:08x}"); - if functions.iter().any(|f| f.selector == selector) { + if !selectors.insert(sel) { continue; } + let selector = format!("0x{sel:08x}"); if pattern == "eq-jumpi" { solc_like += 1; } else { From ef2997f9eb9b8767305bb905a00abe9da992a17d Mon Sep 17 00:00:00 2001 From: Afloat Date: Wed, 11 Nov 2026 01:34:53 +0800 Subject: [PATCH 48/97] Port EVM inspection: Preserve EVM bytecode when metadata map keys are ambiguous (R3.12) (#1508) Source: storytold/craft-anything@a7e66ab5982afe34d0905bbfe9c65d260f41c455:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 059252dc4..b2a439780 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -338,10 +338,15 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { } let mut m = Map::new(); for _ in 0..n { - let k = match cbor_item(b, pos, depth + 1)? { - Value::String(s) => s, - other => other.to_string(), - }; + // The metadata view uses JSON object keys. Coercing other CBOR key + // types to strings can merge distinct keys and hide bytecode. + if b.get(*pos).map(|byte| byte >> 5) != Some(3) { + return None; + } + let Value::String(k) = cbor_item(b, pos, depth + 1)? else { return None }; + if m.contains_key(&k) { + return None; + } let v = cbor_item(b, pos, depth + 1)?; let v = match (k.as_str(), &v) { ("solc", Value::String(s)) if s.starts_with("0x") && s.len() == 8 => { From 80f6ae251599e8df319aa2d2650cad6104420490 Mon Sep 17 00:00:00 2001 From: Afloat Date: Wed, 11 Nov 2026 18:10:38 +0800 Subject: [PATCH 49/97] Port EVM inspection: Require matching operands before reporting EVM dispatch facts (R3.12) (#1651) Source: storytold/craft-anything@341dd7def502be2925c8f3c111c4d51a0afea39b:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index b2a439780..9769d17e9 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -434,7 +434,14 @@ pub fn analyze(code: &[u8]) -> Result { let Some(n) = at(k + d) else { break }; let kind = match n.op { 0x60 if imm(body, n) == [0xe0] && op_at(k + d + 1) == Some(0x1c) => Some("shr-224"), - 0x7c if imm(body, n).first() == Some(&1) && imm(body, n).iter().skip(1).all(|&b| b == 0) => Some("div-2^224"), + 0x7c if d == 1 + && imm(body, n).first() == Some(&1) + && imm(body, n).iter().skip(1).all(|&b| b == 0) + && op_at(k + d + 1) == Some(0x90) + && op_at(k + d + 2) == Some(0x04) => + { + Some("div-2^224") + } 0x63 if imm(body, n) == [0xff, 0xff, 0xff, 0xff] && (op_at(k + d + 1) == Some(0x16) || op_at(k + d + 2) == Some(0x16)) => Some("and-mask"), _ => None, }; @@ -499,13 +506,15 @@ pub fn analyze(code: &[u8]) -> Result { } } else if n == 4 { // Vyper also loads the selector from memory: PUSH sel, PUSH1 0, MLOAD, EQ, ISZERO … - for d in 1..=3 { - if op_at(k + d) == Some(0x14) && op_at(k + d + 1) == Some(0x15) && found(k + d + 2).is_some() { - if let Some(next) = at(k + d + 4) { - hit = Some((next.off, k + d + 3, "eq-iszero-fallthrough")); - } - break; - } + let load = at(k + 1).is_some_and(|p| (p.op == 0x5f || is_push(p.op)) && imm_u64(body, p) == Some(0)); + if load + && op_at(k + 2) == Some(0x51) + && op_at(k + 3) == Some(0x14) + && op_at(k + 4) == Some(0x15) + && found(k + 5).is_some() + && let Some(next) = at(k + 7) + { + hit = Some((next.off, k + 6, "eq-iszero-fallthrough")); } let direct = matches!(op_at(k + 1), Some(0x10 | 0x11)) && found(k + 2).is_some(); let via_dup = matches!(op_at(k + 1), Some(0x80..=0x8f)) && matches!(op_at(k + 2), Some(0x10 | 0x11)) && found(k + 3).is_some(); @@ -529,7 +538,9 @@ pub fn analyze(code: &[u8]) -> Result { last_jumpi = Some(jumpi_k); let di = index_of(dest); let jumpdest_valid = pattern != "eq-jumpi" || di.and_then(at).is_some_and(|x| x.op == 0x5b); - let (mutability, reason) = if callvalue_before { + let (mutability, reason) = if !jumpdest_valid { + ("unknown", "the destination is not a JUMPDEST".to_owned()) + } else if callvalue_before { ("nonpayable", "a CALLVALUE check runs before the dispatcher, so every function refuses payments".to_string()) } else { match di { @@ -567,10 +578,11 @@ pub fn analyze(code: &[u8]) -> Result { if op_at(k + 1) == Some(0x15) && at(k + 2).is_some_and(|p| is_push(p.op)) && op_at(k + 3) == Some(0x57) { receive = "present"; } - let lt = (1..=3).find(|d| op_at(k + d) == Some(0x10)); - if let Some(d) = lt - && at(k + d + 1).is_some_and(|p| is_push(p.op)) - && op_at(k + d + 2) == Some(0x57) + // LT pops the size first in PUSH 4, CALLDATASIZE, LT. + if k.checked_sub(1).and_then(at).is_some_and(|p| is_push(p.op) && imm_u64(body, p) == Some(4)) + && op_at(k + 1) == Some(0x10) + && at(k + 2).is_some_and(|p| is_push(p.op)) + && op_at(k + 3) == Some(0x57) { short_calldata = true; } From eb27a0d8ed72a41387e2ad233f9d7437ca1eadf1 Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:23:25 -0500 Subject: [PATCH 50/97] Port EVM inspection: Keep ordinary EVM metadata arrays typed (R3.12) (#1732) (#1732) Source: storytold/craft-anything@726fa4d25ba49e2742d88860b3adcb83df46d5c2:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 9769d17e9..da6df0961 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -325,10 +325,6 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { for _ in 0..n { items.push(cbor_item(b, pos, depth + 1)?); } - // A version array like [0, 3, 10] reads as "0.3.10". - if items.len() == 3 && items.iter().all(Value::is_u64) { - return Some(Value::from(items.iter().map(|v| v.to_string()).collect::>().join("."))); - } Some(Value::Array(items)) } 5 => { @@ -349,6 +345,9 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { } let v = cbor_item(b, pos, depth + 1)?; let v = match (k.as_str(), &v) { + ("solc" | "vyper", Value::Array(items)) if items.len() == 3 && items.iter().all(Value::is_u64) => { + Value::from(items.iter().map(|v| v.to_string()).collect::>().join(".")) + } ("solc", Value::String(s)) if s.starts_with("0x") && s.len() == 8 => { let d: Vec = (0..3).filter_map(|i| u8::from_str_radix(s.get(2 + 2 * i..4 + 2 * i)?, 16).ok()).collect(); if let [a, bb, c] = d.as_slice() { Value::from(format!("{a}.{bb}.{c}")) } else { v } From 9d718a87410cb6e30966bd617b25bfd0a3528955 Mon Sep 17 00:00:00 2001 From: NetterSilver <133535268+Silvertree2010@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:58:27 +0100 Subject: [PATCH 51/97] Port EVM inspection: Reject '+' signs in hex of EVM metadata solc and ipfs values (#1971) Source: storytold/craft-anything@86c2dd0227f4ee8b2f953dc8b00a9d1426032e11:crates/formats/src/evm.rs --- crates/evm/src/lib.rs | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index da6df0961..6eb9aace4 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -349,7 +349,7 @@ fn cbor_item(b: &[u8], pos: &mut usize, depth: u32) -> Option { Value::from(items.iter().map(|v| v.to_string()).collect::>().join(".")) } ("solc", Value::String(s)) if s.starts_with("0x") && s.len() == 8 => { - let d: Vec = (0..3).filter_map(|i| u8::from_str_radix(s.get(2 + 2 * i..4 + 2 * i)?, 16).ok()).collect(); + let d: Vec = (0..3).filter_map(|i| hex_byte(s.get(2 + 2 * i..4 + 2 * i)?)).collect(); if let [a, bb, c] = d.as_slice() { Value::from(format!("{a}.{bb}.{c}")) } else { v } } ("ipfs", Value::String(s)) if s.starts_with("0x1220") => Value::from(base58(&hex_decode(s.get(2..).unwrap_or("")))), @@ -378,8 +378,13 @@ fn bytes_value(s: &[u8]) -> String { out } +/// One byte from two hex digits; `from_str_radix` alone would also accept a leading `+`. +fn hex_byte(pair: &str) -> Option { + if pair.bytes().all(|c| c.is_ascii_hexdigit()) { u8::from_str_radix(pair, 16).ok() } else { None } +} + fn hex_decode(s: &str) -> Vec { - (0..s.len() / 2).filter_map(|i| u8::from_str_radix(s.get(2 * i..2 * i + 2)?, 16).ok()).collect() + (0..s.len() / 2).filter_map(|i| hex_byte(s.get(2 * i..2 * i + 2)?)).collect() } fn base58(b: &[u8]) -> String { @@ -717,6 +722,21 @@ mod tests { use super::*; use craft_anything_testkit::formats as fx; + #[test] + fn hex_signs_are_not_hex_digits() { + let solc = |v: &str| { + let mut b = vec![0xa1, 0x64]; + b.extend(b"solc"); + b.push(0x60 + v.len() as u8); + b.extend(v.as_bytes()); + cbor_item(&b, &mut 0, 0).unwrap()["solc"].clone() + }; + assert_eq!(solc("0x+1+2+3"), "0x+1+2+3"); + assert_eq!(solc("0x000008"), "0.0.8"); + assert!(hex_decode("+f").is_empty()); + assert_eq!(hex_decode("0f"), vec![15]); + } + /// A plausible trailer length alone must not remove instructions from the analyzed bytecode. #[test] fn incomplete_cbor_must_not_shorten_the_analyzed_contract() { From 5e1f00b37f2f1f26bd22dac8040425f785db8a09 Mon Sep 17 00:00:00 2001 From: Afloat Date: Wed, 11 Nov 2026 01:34:53 +0800 Subject: [PATCH 52/97] Port EVM regression: Preserve EVM bytecode when metadata map keys are ambiguous (R3.12) (#1508) Source: storytold/craft-anything@a7e66ab5982afe34d0905bbfe9c65d260f41c455:crates/formats/tests/evm_metadata_map_keys.rs --- crates/evm/tests/evm_metadata_map_keys.rs | 68 +++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 crates/evm/tests/evm_metadata_map_keys.rs diff --git a/crates/evm/tests/evm_metadata_map_keys.rs b/crates/evm/tests/evm_metadata_map_keys.rs new file mode 100644 index 000000000..cfd108521 --- /dev/null +++ b/crates/evm/tests/evm_metadata_map_keys.rs @@ -0,0 +1,68 @@ +use craft_anything_formats::evm::analyze; + +fn contract_with_trailer(cbor: &[u8]) -> Vec { + let mut code = vec![0x5b, 0x00]; + code.extend_from_slice(cbor); + code.extend_from_slice(&u16::try_from(cbor.len()).unwrap().to_be_bytes()); + code +} + +fn assert_unrecognized(cbor: &[u8]) { + let code = contract_with_trailer(cbor); + let result = analyze(&code).unwrap(); + assert!(result.metadata.is_none(), "ambiguous map must remain bytecode: {cbor:02x?}"); + assert_eq!(result.analysed_size, code.len()); +} + +#[test] +fn duplicate_compiler_keys_do_not_replace_the_reported_version() { + assert_unrecognized(b"\xa2\x64solc\x43\x00\x08\x13\x64solc\x43\x00\x08\x1a"); +} + +#[test] +fn identical_duplicate_keys_are_also_ambiguous() { + assert_unrecognized(b"\xa2\x64solc\x43\x00\x08\x13\x64solc\x43\x00\x08\x13"); +} + +#[test] +fn numeric_keys_cannot_collide_with_text_keys() { + assert_unrecognized(b"\xa2\x01\x00\x61\x31\x01"); +} + +#[test] +fn metadata_map_keys_must_be_encoded_as_text() { + for key in [vec![0x01], vec![0x41, b'x'], vec![0x83, 0, 1, 2], vec![0xf5], vec![0xf6], vec![0xa0]] { + let mut cbor = vec![0xa1]; + cbor.extend(key); + cbor.push(0); + assert_unrecognized(&cbor); + } +} + +#[test] +fn nested_maps_do_not_silently_overwrite_keys() { + assert_unrecognized(b"\xa1\x65extra\xa2\x61x\x00\x61x\x01"); + assert_unrecognized(b"\xa1\x65extra\xa1\x01\x00"); +} + +#[test] +fn ordinary_compiler_metadata_and_unique_nested_text_keys_still_decode() { + let code = contract_with_trailer(b"\xa2\x64solc\x43\x00\x08\x13\x65extra\xa2\x61x\x00\x61y\x01"); + let result = analyze(&code).unwrap(); + assert_eq!(result.analysed_size, 2); + let metadata = result.metadata.unwrap(); + assert_eq!(metadata.compiler.as_deref(), Some("solc 0.8.19")); + assert_eq!(metadata.entries["extra"]["x"], 0); + assert_eq!(metadata.entries["extra"]["y"], 1); + assert_eq!(metadata.length, code.len() - 2); +} + +#[test] +fn equal_keys_in_separate_maps_are_independent() { + let code = contract_with_trailer(b"\xa2\x61a\xa1\x61x\x00\x61b\xa1\x61x\x01"); + let result = analyze(&code).unwrap(); + assert_eq!(result.analysed_size, 2); + let entries = result.metadata.unwrap().entries; + assert_eq!(entries["a"]["x"], 0); + assert_eq!(entries["b"]["x"], 1); +} From 9acfe9da4ded07f44fba6b289ee5dfbaa1cda5af Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:23:25 -0500 Subject: [PATCH 53/97] Port EVM regression: Keep ordinary EVM metadata arrays typed (R3.12) (#1732) (#1732) Source: storytold/craft-anything@726fa4d25ba49e2742d88860b3adcb83df46d5c2:crates/formats/tests/evm_metadata_arrays.rs --- crates/evm/tests/evm_metadata_arrays.rs | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 crates/evm/tests/evm_metadata_arrays.rs diff --git a/crates/evm/tests/evm_metadata_arrays.rs b/crates/evm/tests/evm_metadata_arrays.rs new file mode 100644 index 000000000..ceeda5c07 --- /dev/null +++ b/crates/evm/tests/evm_metadata_arrays.rs @@ -0,0 +1,39 @@ +use craft_evm as evm; +use serde_json::json; + +/// Unrelated three-integer arrays stay arrays while compiler versions stay readable. +#[test] +fn cbor_arrays_are_not_all_compiler_versions() { + // {"sizes": [1, 2, 3], "vyper": [0, 3, 10]} + for (cbor, compiler) in [ + (b"\xa2\x65sizes\x83\x01\x02\x03\x65vyper\x83\x00\x03\x0a".as_slice(), "vyper 0.3.10"), + (b"\xa2\x65sizes\x83\x01\x02\x03\x64solc\x83\x00\x08\x13".as_slice(), "solc 0.8.19"), + ] { + let mut code = vec![0x00]; + code.extend(cbor); + code.extend((cbor.len() as u16).to_be_bytes()); + let result = evm::analyze(&code).unwrap(); + let meta = result.metadata.unwrap(); + assert_eq!(meta.entries["sizes"], json!([1, 2, 3])); + assert_eq!(meta.compiler.as_deref(), Some(compiler)); + assert_eq!(result.analysed_size, 1); + } +} + +/// A non-version Vyper array stays typed, and a truncated array stays bytecode. +#[test] +fn invalid_version_shapes_are_not_invented_or_silently_consumed() { + let cbor = b"\xa1\x65vyper\x82\x00\x03"; + let mut code = vec![0x00]; + code.extend(cbor); + code.extend((cbor.len() as u16).to_be_bytes()); + let meta = evm::analyze(&code).unwrap().metadata.unwrap(); + assert_eq!(meta.compiler, None); + assert_eq!(meta.entries["vyper"], json!([0, 3])); + + let mut truncated = code; + truncated[8] = 0x83; // Declare three items but keep only two. + let result = evm::analyze(&truncated).unwrap(); + assert!(result.metadata.is_none()); + assert_eq!(result.analysed_size, truncated.len()); +} From 76e8a7607f8b5b602e823d5759f8e4e7fd4ae45f Mon Sep 17 00:00:00 2001 From: Afloat Date: Wed, 11 Nov 2026 01:16:26 +0800 Subject: [PATCH 54/97] Port EVM regression: Avoid repeated selector scans in EVM dispatchers (R3.12) (#1538) Source: storytold/craft-anything@1565bd4278955161e4c704cee37bbae9f22bfb3a:crates/formats/tests/evm_selector_dedup.rs --- crates/evm/tests/evm_selector_dedup.rs | 70 ++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 crates/evm/tests/evm_selector_dedup.rs diff --git a/crates/evm/tests/evm_selector_dedup.rs b/crates/evm/tests/evm_selector_dedup.rs new file mode 100644 index 000000000..8ce4b88a4 --- /dev/null +++ b/crates/evm/tests/evm_selector_dedup.rs @@ -0,0 +1,70 @@ +use craft_evm as evm; + +fn prefix() -> Vec { + vec![0x5b, 0x00, 0x60, 0x00, 0x35, 0x60, 0xe0, 0x1c] +} + +fn comparison(code: &mut Vec, selector: u32, width: usize, destination: u8) { + code.push(0x5f + u8::try_from(width).unwrap()); + code.extend_from_slice(&selector.to_be_bytes()[4 - width..]); + code.extend([0x14, 0x60, destination, 0x57]); +} + +#[test] +fn repeated_comparisons_keep_the_first_destination_and_encounter_order() { + let mut code = prefix(); + comparison(&mut code, 0xfeed0002, 4, 0); + comparison(&mut code, 0xfeed0001, 4, 0); + let expected = evm::analyze(&code).unwrap().functions; + for _ in 0..2000 { + comparison(&mut code, 0xfeed0001, 4, 1); + comparison(&mut code, 0xfeed0002, 4, 1); + } + assert_eq!(evm::analyze(&code).unwrap().functions, expected); +} + +#[test] +fn different_push_widths_share_the_same_numeric_selector() { + let mut code = prefix(); + for width in 1..=4 { + comparison(&mut code, 17, width, if width == 1 { 0 } else { 1 }); + } + let result = evm::analyze(&code).unwrap(); + assert_eq!(result.functions.len(), 1); + assert_eq!(result.functions[0].selector, "0x00000011"); + assert_eq!(result.functions[0].bytecode_offset, 0); +} + +#[test] +fn rejected_candidates_do_not_spend_selector_identity() { + let mut code = vec![0x5b, 0x00]; + // Short comparisons without selector extraction are not considered functions. + comparison(&mut code, 17, 1, 1); + // A selector-shaped immediate without a comparison is not a function either. + code.extend([0x63, 0, 0, 0, 17, 0x50]); + comparison(&mut code, 17, 4, 0); + let result = evm::analyze(&code).unwrap(); + assert_eq!(result.functions.len(), 1); + assert_eq!(result.functions[0].bytecode_offset, 0); + assert!(result.functions[0].jumpdest_valid); +} + +#[test] +fn selector_cap_counts_unique_matches() { + let mut code = prefix(); + for selector in 0..4095 { + comparison(&mut code, selector, 4, 0); + } + for _ in 0..10000 { + comparison(&mut code, 4094, 4, 1); + } + let below = evm::analyze(&code).unwrap(); + assert_eq!(below.functions.len(), 4095); + assert!(!below.warnings.iter().any(|warning| warning.contains("stopped at"))); + comparison(&mut code, 4095, 4, 0); + comparison(&mut code, 4096, 4, 0); + let capped = evm::analyze(&code).unwrap(); + assert_eq!(capped.functions.len(), 4096); + assert_eq!(capped.functions.last().unwrap().selector, "0x00000fff"); + assert!(capped.warnings.iter().any(|warning| warning == "stopped at 4096 selectors")); +} From 5a74c5ef3637a885acdf553817b775a69b71f498 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 12:00:08 -0500 Subject: [PATCH 55/97] Expose shared read-only EVM inspection with retained bounds and regressions --- ATTRIBUTION.md | 4 + Cargo.lock | 23 ++++-- Cargo.toml | 1 + crates/evm/Cargo.toml | 14 ++++ crates/evm/README.md | 7 ++ crates/evm/src/lib.rs | 36 +++++++-- crates/evm/src/test_support.rs | 99 +++++++++++++++++++++++ crates/evm/tests/evm_metadata_map_keys.rs | 2 +- 8 files changed, 171 insertions(+), 15 deletions(-) create mode 100644 crates/evm/Cargo.toml create mode 100644 crates/evm/README.md create mode 100644 crates/evm/src/test_support.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index f772eede2..f62a8130b 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -141,3 +141,7 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. ## HTTP Archive reader `crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned. + +## EVM bytecode inspection + +`crates/evm` extracts Craft Anything `crates/formats/src/evm.rs` at `a31e995858f4312e0f1d59a007112da191ef2d26` (MIT OR Apache-2.0). Eight separate source-history ports preserve Brandon Thomas, Afloat, RRFZ and NetterSilver as primary authors with immutable source references. Synthetic EVM fixtures and deterministic mutation helpers come from the same app source; regression files retain their source provenance. Neutral errors and workspace integration are subsequent changes. No code execution or transaction behavior is imported. diff --git a/Cargo.lock b/Cargo.lock index da0654156..d554ad256 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1881,6 +1881,15 @@ dependencies = [ "zip 9.1.3", ] +[[package]] +name = "craft-evm" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-ews" version = "0.1.0" @@ -2122,13 +2131,6 @@ dependencies = [ "flate2", ] -[[package]] -name = "craft-hdr" -version = "0.1.0" -dependencies = [ - "thiserror 2.0.21", -] - [[package]] name = "craft-har" version = "0.1.0" @@ -2137,6 +2139,13 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-hdr" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + [[package]] name = "craft-heif" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index c8cd94409..b42f0a33d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-evm = { path = "crates/evm" } craft-har = { path = "crates/har" } craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } diff --git a/crates/evm/Cargo.toml b/crates/evm/Cargo.toml new file mode 100644 index 000000000..92d0abae8 --- /dev/null +++ b/crates/evm/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "craft-evm" +description = "Read-only EVM bytecode dispatcher and compiler metadata inspection" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde = { workspace = true } +serde_json = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/evm/README.md b/crates/evm/README.md new file mode 100644 index 000000000..6214c45b4 --- /dev/null +++ b/crates/evm/README.md @@ -0,0 +1,7 @@ +# craft-evm + +Read-only EVM bytecode inspection: strict raw/hex admission, opcode listing, dispatcher selector and jump-pattern facts, and Solidity/Vyper CBOR metadata. No VM execution, RPC, wallet, signing or transaction support. + +Preserves Craft Anything's parser behavior and limits: 16 MiB decoded bytecode, 4,096 reported functions and 400 listing entries, plus existing bounded CBOR recursion/collection parsing. These are not a total allocator-byte guarantee. Dispatcher facts are heuristics, not a full control-flow or semantic proof. EOF containers remain unsupported. + +Application file I/O, evidence policy and selector naming remain outside this crate. diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 6eb9aace4..18104edcf 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -1,9 +1,28 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + //! EVM bytecode: the public function selectors a contract's dispatcher compares against, where //! each one jumps, whether it refuses payments, fallback/receive presence, and the compiler //! metadata (CBOR) appended to the code. Nothing is executed; this is a linear sweep that //! respects PUSH data plus pattern matching over the instruction stream. -use crate::FormatError; +use EvmError as FormatError; + +/// Neutral inspection failure; no code is executed. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum EvmError { + #[error("truncated input: {0}")] + Truncated(String), + #[error("malformed input: {0}")] + Malformed(String), + #[error("unsupported: {0}")] + Unsupported(String), + #[error("input too large: {0}")] + TooLarge(String), +} + +#[cfg(test)] +mod test_support; use serde::Serialize; use serde_json::{Map, Value}; use std::collections::BTreeSet; @@ -446,7 +465,9 @@ pub fn analyze(code: &[u8]) -> Result { { Some("div-2^224") } - 0x63 if imm(body, n) == [0xff, 0xff, 0xff, 0xff] && (op_at(k + d + 1) == Some(0x16) || op_at(k + d + 2) == Some(0x16)) => Some("and-mask"), + 0x63 if imm(body, n) == [0xff, 0xff, 0xff, 0xff] && (op_at(k + d + 1) == Some(0x16) || op_at(k + d + 2) == Some(0x16)) => { + Some("and-mask") + } _ => None, }; if let Some(kind) = kind { @@ -720,7 +741,7 @@ fn reverts_soon(code: &[u8], ins: &[Ins], mut k: usize, index_of: &dyn Fn(usize) #[cfg(test)] mod tests { use super::*; - use craft_anything_testkit::formats as fx; + use crate::test_support::formats as fx; #[test] fn hex_signs_are_not_hex_digits() { @@ -796,8 +817,9 @@ mod tests { #[test] fn vyper_style_fallthrough() { // PUSH1 0 CALLDATALOAD PUSH1 0xe0 SHR PUSH1 0 MSTORE PUSH4 sel PUSH1 0 MLOAD EQ ISZERO PUSH2 next JUMPI - let mut c = - vec![0x60, 0x00, 0x35, 0x60, 0xe0, 0x1c, 0x60, 0x00, 0x52, 0x63, 0x12, 0x34, 0x56, 0x78, 0x60, 0x00, 0x51, 0x14, 0x15, 0x61, 0x00, 0x20, 0x57]; + let mut c = vec![ + 0x60, 0x00, 0x35, 0x60, 0xe0, 0x1c, 0x60, 0x00, 0x52, 0x63, 0x12, 0x34, 0x56, 0x78, 0x60, 0x00, 0x51, 0x14, 0x15, 0x61, 0x00, 0x20, 0x57, + ]; let body = c.len(); c.extend_from_slice(&[0x34, 0x15, 0x00]); let r = analyze(&c).unwrap(); @@ -835,14 +857,14 @@ mod tests { #[test] fn hostile_inputs_do_not_panic() { let (code, _) = fx::evm_runtime(); - for m in craft_anything_testkit::mutations(&code) { + for m in crate::test_support::mutations(&code) { let _ = analyze(&m); } for n in 0..code.len() { let _ = analyze(&code[..n]); } for seed in 0..200 { - let n = craft_anything_testkit::noise(seed, 300); + let n = crate::test_support::noise(seed, 300); let _ = analyze(&n); let _ = decode_input(&n, Encoding::Auto); } diff --git a/crates/evm/src/test_support.rs b/crates/evm/src/test_support.rs new file mode 100644 index 000000000..b31ace0a2 --- /dev/null +++ b/crates/evm/src/test_support.rs @@ -0,0 +1,99 @@ +pub mod formats { + pub const EVM_SELECTORS: [u32; 3] = [0xa905_9cbb, 0x70a0_8231, 0xd0e3_0db0]; + + /// Runtime bytecode with a compiler-style dispatcher, a fallback that reverts, two non-payable + /// functions (CALLVALUE check), one payable function, and a CBOR metadata tail (ipfs + solc 0.8.19). + /// Returns (bytecode, jump destinations of the three functions). + pub fn evm_runtime() -> (Vec, [usize; 3]) { + let mut c: Vec = vec![0x60, 0x80, 0x60, 0x40, 0x52]; + // if calldatasize < 4 goto fallback + c.extend_from_slice(&[0x60, 0x04, 0x36, 0x10, 0x61, 0, 0]); + let fb_patch = c.len() - 2; + c.push(0x57); + c.extend_from_slice(&[0x60, 0x00, 0x35, 0x60, 0xe0, 0x1c]); + let mut patches = Vec::new(); + for sel in EVM_SELECTORS { + c.push(0x80); + c.push(0x63); + c.extend_from_slice(&sel.to_be_bytes()); + c.extend_from_slice(&[0x14, 0x61, 0, 0]); + patches.push(c.len() - 2); + c.push(0x57); + } + let fallback = c.len(); + c.extend_from_slice(&[0x5b, 0x60, 0x00, 0x80, 0xfd]); + let mut dests = [0usize; 3]; + for (i, dest) in dests.iter_mut().enumerate() { + *dest = c.len(); + if i < 2 { + // JUMPDEST CALLVALUE DUP1 ISZERO PUSH2 ok JUMPI PUSH1 0 DUP1 REVERT JUMPDEST POP STOP + c.extend_from_slice(&[0x5b, 0x34, 0x80, 0x15, 0x61, 0, 0]); + let ok_patch = c.len() - 2; + c.extend_from_slice(&[0x57, 0x60, 0x00, 0x80, 0xfd]); + let ok = c.len(); + c.extend_from_slice(&[0x5b, 0x50, 0x00]); + c[ok_patch..ok_patch + 2].copy_from_slice(&(ok as u16).to_be_bytes()); + } else { + c.extend_from_slice(&[0x5b, 0x60, 0x01, 0x60, 0x00, 0x55, 0x00]); + } + } + c[fb_patch..fb_patch + 2].copy_from_slice(&(fallback as u16).to_be_bytes()); + for (p, d) in patches.iter().zip(dests) { + c[*p..*p + 2].copy_from_slice(&(d as u16).to_be_bytes()); + } + c.push(0xfe); + let mut meta = vec![0xa2, 0x64, b'i', b'p', b'f', b's', 0x58, 0x22, 0x12, 0x20]; + meta.extend((0..32u8).map(|i| i.wrapping_mul(7))); + meta.extend_from_slice(&[0x64, b's', b'o', b'l', b'c', 0x43, 0x00, 0x08, 0x13]); + let len = meta.len() as u16; + c.extend_from_slice(&meta); + c.extend_from_slice(&len.to_be_bytes()); + (c, dests) + } + + /// Bytecode as `0x`-prefixed lowercase hex. + pub fn to_hex(b: &[u8]) -> String { + let mut s = String::from("0x"); + for x in b { + s.push_str(&format!("{x:02x}")); + } + s + } +} +pub fn noise(seed: u64, len: usize) -> Vec { + let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; + (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect() +} +pub fn mutations(sample: &[u8]) -> Vec> { + let mut out = Vec::new(); + let n = sample.len(); + let step = (n / 64).max(1); + let mut len = 0; + while len < n { + out.push(sample[..len].to_vec()); + len += step; + } + for (i, seed) in (0..n).step_by(step).zip(1u64..) { + let mut m = sample.to_vec(); + let noise = noise(seed, 8); + for (j, v) in noise.iter().enumerate() { + if let Some(b) = m.get_mut(i + j) { + *b = *v; + } + } + out.push(m); + let mut m = sample.to_vec(); + if let Some(b) = m.get_mut(i) { + *b = 0xff; + } + out.push(m); + } + out +} diff --git a/crates/evm/tests/evm_metadata_map_keys.rs b/crates/evm/tests/evm_metadata_map_keys.rs index cfd108521..eed0fdfbd 100644 --- a/crates/evm/tests/evm_metadata_map_keys.rs +++ b/crates/evm/tests/evm_metadata_map_keys.rs @@ -1,4 +1,4 @@ -use craft_anything_formats::evm::analyze; +use craft_evm::analyze; fn contract_with_trailer(cbor: &[u8]) -> Vec { let mut code = vec![0x5b, 0x00]; From 1aff2841c9ee575eb24f82d578f0e69cef452daa Mon Sep 17 00:00:00 2001 From: FredApps Date: Tue, 17 Nov 2026 18:08:31 +0100 Subject: [PATCH 56/97] svg: exclude nested image callback leaves from depth reservation --- crates/svg/src/tree/validated.rs | 4 +++- crates/svg/src/tree/validated/xml_tests.rs | 21 +++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/crates/svg/src/tree/validated.rs b/crates/svg/src/tree/validated.rs index 658b2641f..a09aa3929 100644 --- a/crates/svg/src/tree/validated.rs +++ b/crates/svg/src/tree/validated.rs @@ -338,7 +338,9 @@ impl ValidatedImageResolver { return None; }; let previous = state.xml_depth; - state.xml_depth = total; + // Admission includes the child's complete height, but recursive + // conversion reserves ancestors only, not its image callback leaf. + state.xml_depth = total.saturating_sub(1); state.depth = state.depth.saturating_add(1); state.svg_depth = state.svg_depth.max(state.depth); Scope { state: Arc::clone(&self.state), previous, child: true } diff --git a/crates/svg/src/tree/validated/xml_tests.rs b/crates/svg/src/tree/validated/xml_tests.rs index 34e1e604e..e0ea41aca 100644 --- a/crates/svg/src/tree/validated/xml_tests.rs +++ b/crates/svg/src/tree/validated/xml_tests.rs @@ -197,3 +197,24 @@ fn plain_root_callback_leaf_does_not_spend_the_child_boundary_twice() { assert_eq!(sample.alpha(), if admitted { 255 } else { 0 }, "exact-boundary child must actually draw"); } } + +#[test] +fn nested_callback_leaves_do_not_spend_the_descendant_boundary_twice() { + let leaf = drawing(""); // height2 + let middle = drawing(&image(&url(leaf.as_bytes()))); // height2 + let root = drawing(&image(&url(middle.as_bytes()))); // height2 + // Root and middle each contribute one ancestor, then the leaf's full + // height2: the visible rectangle fits exactly at depth4, but not depth3. + for (depth, admitted) in [(3, false), (4, true)] { + let limits = Limits { tree_depth: depth, ..Default::default() }; + let context = ValidatedImageResolver::new(limits); + let tree = context.parse_preflight(preflight(&root, &limits).unwrap(), usvg::Options::default()).unwrap(); + let usage = context.usage(); + assert_eq!(usage.embedded_svg_count, if admitted { 2 } else { 1 }); + assert_eq!(usage.svg_limit_images, usize::from(!admitted)); + assert_eq!(usage.invalid_svg_images, 0); + let pixels = super::super::draw::render(&tree, usvg::Transform::identity(), 4, 4, 0, 1 << 20).unwrap(); + let sample = pixels.pixel(1, 1).unwrap(); + assert_eq!(sample.alpha(), if admitted { 255 } else { 0 }, "exact-boundary grandchild must actually draw"); + } +} From 383c52430ed0da0ef3a85ed251013efb8e431487 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 12:14:17 -0500 Subject: [PATCH 57/97] Separate EVM selector and calldata pattern inspection for lint gate --- crates/evm/src/lib.rs | 88 +++++++++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 37 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 18104edcf..e85541eed 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -427,26 +427,9 @@ fn base58(b: &[u8]) -> String { s } -/// Analyse bytecode (already decoded from hex if needed). -pub fn analyze(code: &[u8]) -> Result { - if code.is_empty() { - return Err(FormatError::Truncated("no bytecode".into())); - } - if code.len() > MAX_CODE { - return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_CODE}", code.len()))); - } - if code.starts_with(&[0xef, 0x00]) { - return Err(FormatError::Unsupported("EVM Object Format (EOF, 0xEF00) containers are not analysed".into())); - } - let mut warnings = Vec::new(); - let (end, metadata) = split_metadata(code); - let body = code.get(..end).unwrap_or(code); - let ins = sweep(body); - let jumpdests = ins.iter().filter(|i| i.op == 0x5b).count(); +fn selector_extraction(body: &[u8], ins: &[Ins]) -> Option<(&'static str, usize)> { let at = |k: usize| ins.get(k); let op_at = |k: usize| at(k).map(|i| i.op); - let index_of = |off: usize| ins.binary_search_by_key(&off, |i| i.off).ok(); - // Selector extraction: CALLDATALOAD followed by SHR 224, DIV 2^224 or a 4-byte mask. let mut extraction: Option<(&'static str, usize)> = None; for (k, i) in ins.iter().enumerate() { @@ -479,6 +462,55 @@ pub fn analyze(code: &[u8]) -> Result { break; } } + extraction +} + +fn short_calldata_path(body: &[u8], ins: &[Ins], disp_start: usize) -> (bool, &'static str) { + let at = |k: usize| ins.get(k); + let op_at = |k: usize| at(k).map(|i| i.op); + // Short calldata path and receive(). + let mut short_calldata = false; + let mut receive = "not-detected"; + for (k, i) in ins.iter().enumerate().take(disp_start.saturating_add(64)) { + if i.op != 0x36 { + continue; + } + if op_at(k + 1) == Some(0x15) && at(k + 2).is_some_and(|p| is_push(p.op)) && op_at(k + 3) == Some(0x57) { + receive = "present"; + } + // LT pops the size first in PUSH 4, CALLDATASIZE, LT. + if k.checked_sub(1).and_then(at).is_some_and(|p| is_push(p.op) && imm_u64(body, p) == Some(4)) + && op_at(k + 1) == Some(0x10) + && at(k + 2).is_some_and(|p| is_push(p.op)) + && op_at(k + 3) == Some(0x57) + { + short_calldata = true; + } + } + (short_calldata, receive) +} + +/// Analyse bytecode (already decoded from hex if needed). +pub fn analyze(code: &[u8]) -> Result { + if code.is_empty() { + return Err(FormatError::Truncated("no bytecode".into())); + } + if code.len() > MAX_CODE { + return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_CODE}", code.len()))); + } + if code.starts_with(&[0xef, 0x00]) { + return Err(FormatError::Unsupported("EVM Object Format (EOF, 0xEF00) containers are not analysed".into())); + } + let mut warnings = Vec::new(); + let (end, metadata) = split_metadata(code); + let body = code.get(..end).unwrap_or(code); + let ins = sweep(body); + let jumpdests = ins.iter().filter(|i| i.op == 0x5b).count(); + let at = |k: usize| ins.get(k); + let op_at = |k: usize| at(k).map(|i| i.op); + let index_of = |off: usize| ins.binary_search_by_key(&off, |i| i.off).ok(); + + let extraction = selector_extraction(body, &ins); let disp_start = extraction.map(|(_, k)| k).unwrap_or(0); if extraction.is_none() { warnings.push("no selector extraction (CALLDATALOAD then SHR/DIV/AND) was seen; matches below are less certain".into()); @@ -592,26 +624,8 @@ pub fn analyze(code: &[u8]) -> Result { warnings.push("some destinations are not JUMPDESTs; those matches may be data, not dispatch".into()); } - // Short calldata path and receive(). - let mut short_calldata = false; - let mut receive = "not-detected"; + let (short_calldata, receive) = short_calldata_path(body, &ins, disp_start); let mut fallback = "unknown"; - for (k, i) in ins.iter().enumerate().take(disp_start.saturating_add(64)) { - if i.op != 0x36 { - continue; - } - if op_at(k + 1) == Some(0x15) && at(k + 2).is_some_and(|p| is_push(p.op)) && op_at(k + 3) == Some(0x57) { - receive = "present"; - } - // LT pops the size first in PUSH 4, CALLDATASIZE, LT. - if k.checked_sub(1).and_then(at).is_some_and(|p| is_push(p.op) && imm_u64(body, p) == Some(4)) - && op_at(k + 1) == Some(0x10) - && at(k + 2).is_some_and(|p| is_push(p.op)) - && op_at(k + 3) == Some(0x57) - { - short_calldata = true; - } - } if let Some(j) = last_jumpi && solc_like > 0 { From 309ae75a4ede6113065873f2b87f5bdfe03ea54b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 12:15:24 -0500 Subject: [PATCH 58/97] pcap: let the packet-block helper use is_multiple_of --- crates/pcap/tests/support/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/pcap/tests/support/mod.rs b/crates/pcap/tests/support/mod.rs index f897b5142..708864c83 100644 --- a/crates/pcap/tests/support/mod.rs +++ b/crates/pcap/tests/support/mod.rs @@ -136,7 +136,7 @@ pub fn pcap(frames: &[Vec]) -> Vec { pub fn block(t: u32, body: &[u8]) -> Vec { let mut body = body.to_vec(); - while body.len() % 4 != 0 { + while !body.len().is_multiple_of(4) { body.push(0); } let len = (body.len() + 12) as u32; From 828daafd16b34d08dd62d77b15df7ac9f047bddc Mon Sep 17 00:00:00 2001 From: ljkx Date: Tue, 17 Nov 2026 18:15:48 +0100 Subject: [PATCH 59/97] craft-mesh: triangulate concave faces by ear clipping instead of fanning across their notch (#2026) --- crates/mesh/README.md | 5 +- crates/mesh/src/lib.rs | 24 ++- crates/mesh/src/stl.rs | 2 +- crates/mesh/src/tests.rs | 1 + crates/mesh/src/tests/triangulate.rs | 147 +++++++++++++++++ crates/mesh/src/triangulate.rs | 226 +++++++++++++++++++++++++++ 6 files changed, 397 insertions(+), 8 deletions(-) create mode 100644 crates/mesh/src/tests/triangulate.rs create mode 100644 crates/mesh/src/triangulate.rs diff --git a/crates/mesh/README.md b/crates/mesh/README.md index 8c0cdec00..df32e7a59 100644 --- a/crates/mesh/README.md +++ b/crates/mesh/README.md @@ -24,8 +24,9 @@ USD, Alembic and COLLADA are not here yet. - `Part`: the faces of a mesh that share a group name, a material and a smoothing group. A face is a polygon of three or more `Corner`s; each corner indexes a position and optionally a normal and a UV. Formats with separate indices (OBJ) are kept exactly, and polygons stay whole. - `Part::triangles()` fans them; `Mesh::unified()` gives one vertex per distinct corner as a - triangle list, which is what a renderer wants. + `Part::triangles_in(&mesh.positions)` triangulates them (a fan for a convex face, ear clipping + in the face's plane for a concave one; `Part::triangles()` only fans); `Mesh::unified()` gives + one vertex per distinct corner as a triangle list, which is what a renderer wants. - `Material`: metallic-roughness factors, alpha mode, double-sided, unlit, and five texture slots. A `TextureRef` names an `Image`, a UV set and wrap modes. An `Image` is a URI the caller resolves or the encoded bytes the file embedded; nothing here decodes images. diff --git a/crates/mesh/src/lib.rs b/crates/mesh/src/lib.rs index 6017c8dd2..4808834fa 100644 --- a/crates/mesh/src/lib.rs +++ b/crates/mesh/src/lib.rs @@ -47,6 +47,7 @@ pub mod ply; pub mod stl; #[cfg(feature = "threemf")] pub mod threemf; +mod triangulate; use std::collections::HashMap; use std::fmt; @@ -193,7 +194,8 @@ impl Part { }) } - /// The faces as triangles: a polygon becomes a fan from its first corner. + /// The faces as triangles: a polygon becomes a fan from its first corner, which is right + /// only for a convex face. [`Part::triangles_in`] triangulates concave faces too. pub fn triangles(&self) -> impl Iterator + '_ { self.faces().flat_map(|f| { let first = f.first().copied(); @@ -204,7 +206,19 @@ impl Part { }) } - /// Triangles the faces fan into. + /// The faces as triangles, with `positions` (the mesh's [`Mesh::positions`]) to see their + /// shape. A convex face becomes a fan from its first corner, as in [`Part::triangles`]; a + /// concave one is triangulated by ear clipping in its own plane, so no triangle covers a + /// notch. Each triangle keeps the face's winding. A face with a corner that has no position, + /// or with no area, keeps the fan. What is left of a face when no ear can be found (it + /// crosses itself) or the part's work budget (256 steps per corner) is spent is + /// fanned. Every face gives `corners − 2` triangles, as [`Part::triangle_count`] counts. + pub fn triangles_in<'a>(&'a self, positions: &'a [[f64; 3]]) -> impl Iterator + 'a { + let mut budget = triangulate::WORK_PER_CORNER.saturating_mul(self.corners.len()); + self.faces().flat_map(move |f| triangulate::face(f, positions, &mut budget)) + } + + /// Triangles the faces give: `corners − 2` each. pub fn triangle_count(&self) -> usize { if self.face_sizes.is_empty() { self.corners.len() / 3 } else { self.face_sizes.iter().map(|n| (*n as usize).saturating_sub(2)).sum() } } @@ -291,8 +305,8 @@ impl Mesh { Ok(()) } - /// The mesh as triangles with one vertex per distinct corner. Corners whose indices are out - /// of range are dropped with their triangle. + /// The mesh as triangles ([`Part::triangles_in`]) with one vertex per distinct corner. + /// Corners whose indices are out of range are dropped with their triangle. pub fn unified(&self) -> Unified { let mut out = Unified::default(); let all = |f: &dyn Fn(&Corner) -> bool| self.parts.iter().all(|p| p.corners.iter().all(f)); @@ -302,7 +316,7 @@ impl Mesh { let mut ids: HashMap = HashMap::new(); for part in &self.parts { let mut tris = Vec::with_capacity(part.triangle_count()); - 'tri: for t in part.triangles() { + 'tri: for t in part.triangles_in(&self.positions) { let mut tri = [0u32; 3]; for (slot, c) in tri.iter_mut().zip(t) { let key = Corner { diff --git a/crates/mesh/src/stl.rs b/crates/mesh/src/stl.rs index e60911a7a..444db5f67 100644 --- a/crates/mesh/src/stl.rs +++ b/crates/mesh/src/stl.rs @@ -238,7 +238,7 @@ fn ascii(bytes: &[u8], limits: &Limits) -> Result { fn triangles(scene: &Scene, limits: &Limits, mut each: impl FnMut([f64; 3], [[f64; 3]; 3])) -> Result<()> { for (index, world) in scene.instances(limits)? { let Some(mesh) = scene.meshes.get(index) else { continue }; - for t in mesh.parts.iter().flat_map(Part::triangles) { + for t in mesh.parts.iter().flat_map(|p| p.triangles_in(&mesh.positions)) { let p = t.map(|c| mesh.positions.get(c.position as usize).copied()); let [Some(a), Some(b), Some(c)] = p else { return Err(malformed(KIND, "a corner index is out of range")) }; // A mirrored placement turns the winding; turn it back so the facet faces out. diff --git a/crates/mesh/src/tests.rs b/crates/mesh/src/tests.rs index 160b5b3dc..423732de8 100644 --- a/crates/mesh/src/tests.rs +++ b/crates/mesh/src/tests.rs @@ -14,6 +14,7 @@ mod ply; mod stl; #[cfg(feature = "threemf")] mod threemf; +mod triangulate; /// Every truncation of `good` and two mutations of every byte go through `read`: it may refuse /// them, it must not panic, and what it accepts must be a valid scene. diff --git a/crates/mesh/src/tests/triangulate.rs b/crates/mesh/src/tests/triangulate.rs new file mode 100644 index 000000000..2bb0c3f6c --- /dev/null +++ b/crates/mesh/src/tests/triangulate.rs @@ -0,0 +1,147 @@ +//! Triangulating concave faces ([`Part::triangles_in`]). + +use super::*; + +/// A one-face part over corners `0..n`. +fn polygon(n: usize) -> Part { + Part { face_sizes: vec![n as u32], corners: (0..n as u32).map(Corner::at).collect(), ..Part::default() } +} + +/// Twice the signed area of a 2D triangle or of a closed 2D polygon. +fn area2(p: &[[f64; 2]]) -> f64 { + (0..p.len()).map(|i| p[i][0] * p[(i + 1) % p.len()][1] - p[(i + 1) % p.len()][0] * p[i][1]).sum() +} + +/// Whether `q` is strictly inside the 2D polygon `p`, by the even-odd rule. +fn inside(p: &[[f64; 2]], q: [f64; 2]) -> bool { + let mut odd = false; + for i in 0..p.len() { + let (a, b) = (p[i], p[(i + 1) % p.len()]); + if (a[1] > q[1]) != (b[1] > q[1]) && q[0] < a[0] + (q[1] - a[1]) / (b[1] - a[1]) * (b[0] - a[0]) { + odd = !odd; + } + } + odd +} + +/// Places the 2D outline on a tilted plane in 3D, so the triangulation has to find the plane. +fn lift(outline: &[[f64; 2]]) -> Vec<[f64; 3]> { + // An orthonormal basis of the plane through (1, 2, 3), its normal leaning on every axis. + let (u, v) = ([2.0 / 3.0, 2.0 / 3.0, -1.0 / 3.0], [-1.0 / 3.0, 2.0 / 3.0, 2.0 / 3.0]); + outline.iter().map(|p| [0, 1, 2].map(|k| [1.0, 2.0, 3.0][k] + p[0] * u[k] + p[1] * v[k])).collect() +} + +/// Triangulates `outline` as one face lifted into 3D, and checks the triangles tile it: one +/// fewer than two per corner, each wound as the outline is and lying inside it (three points +/// inside every triangle are inside the outline), and their areas adding up to the outline's. +fn assert_tiles(outline: &[[f64; 2]]) -> Vec<[u32; 3]> { + let positions = lift(outline); + let tris: Vec<[u32; 3]> = polygon(outline.len()).triangles_in(&positions).map(|t| t.map(|c| c.position)).collect(); + assert_eq!(tris.len(), outline.len() - 2, "{tris:?}"); + let whole = area2(outline); + let mut sum = 0.0; + for t in &tris { + let p = t.map(|i| outline[i as usize]); + let a = area2(&p); + assert!(a * whole.signum() > 0.0, "{t:?} is wound against the outline or has no area"); + sum += a.abs(); + for w in [[1.0, 1.0, 1.0], [4.0, 1.0, 1.0], [1.0, 4.0, 1.0], [1.0, 1.0, 4.0]] { + let n: f64 = w.iter().sum(); + let q = [0, 1].map(|k| (0..3).map(|j| p[j][k] * w[j]).sum::() / n); + assert!(inside(outline, q), "{t:?} leaves the outline at {q:?}"); + } + } + assert!((sum - whole.abs()).abs() < 1e-9 * whole.abs(), "areas {sum} and {whole}"); + tris +} + +#[test] +fn concave_faces_are_not_fanned_across_their_notch() { + // The issue's face: a fan from (0, 0) covers the notch between (2, 2), (1, 0.5) and (0, 2). + let notch = [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [1.0, 0.5], [0.0, 2.0]]; + let fan: Vec<[u32; 3]> = polygon(5).triangles().map(|t| t.map(|c| c.position)).collect(); + assert_eq!(fan, [[0, 1, 2], [0, 2, 3], [0, 3, 4]]); + let tris = assert_tiles(¬ch); + assert_ne!(tris, fan); + // The same face wound the other way. + let mut cw = notch; + cw.reverse(); + assert_tiles(&cw); + // An L, a comb with nine teeth, a ten-pointed star and an arrow with straight corners. + assert_tiles(&[[0.0, 0.0], [3.0, 0.0], [3.0, 1.0], [1.0, 1.0], [1.0, 3.0], [0.0, 3.0]]); + let mut comb = vec![[0.0, 0.0], [18.0, 0.0]]; + for k in (0..9).rev() { + let x = 2.0 * k as f64; + comb.extend([[x + 2.0, 5.0], [x + 1.0, 5.0], [x + 1.0, 1.0]]); + } + comb.pop(); + assert_tiles(&comb); + let star: Vec<[f64; 2]> = (0..20) + .map(|k| { + let (r, a) = (if k % 2 == 0 { 3.0 } else { 1.0 }, k as f64 * std::f64::consts::PI / 10.0); + [r * a.cos(), r * a.sin()] + }) + .collect(); + assert_tiles(&star); + assert_tiles(&[[0.0, 1.0], [2.0, 1.0], [4.0, 1.0], [4.0, 0.0], [6.0, 2.0], [4.0, 4.0], [4.0, 3.0], [2.0, 3.0], [0.0, 3.0]]); +} + +#[test] +fn convex_faces_keep_their_fan() { + let hexagon: Vec<[f64; 2]> = (0..6).map(|k| [(k as f64).cos(), (k as f64).sin()]).collect(); + let positions = lift(&hexagon); + let part = polygon(6); + assert_eq!(part.triangles_in(&positions).collect::>(), part.triangles().collect::>()); + // A square with a straight corner on one side is still convex. + let square = lift(&[[0.0, 0.0], [1.0, 0.0], [2.0, 0.0], [2.0, 2.0], [0.0, 2.0]]); + assert_eq!(polygon(5).triangles_in(&square).collect::>(), polygon(5).triangles().collect::>()); +} + +#[test] +fn faces_that_cannot_be_clipped_keep_their_triangle_count() { + // No positions, a face with no area, and a bow tie that crosses itself. + let bow = lift(&[[0.0, 0.0], [2.0, 2.0], [2.0, 0.0], [0.0, 2.0]]); + let flat = lift(&[[0.0, 0.0], [1.0, 0.0], [2.0, 0.0], [3.0, 0.0]]); + for positions in [&[][..], &flat, &bow] { + assert_eq!(polygon(4).triangles_in(positions).count(), 2); + } + // A comb of 4000 teeth: the work stays bounded and every triangle is still given. + let mut comb = vec![[0.0, 0.0], [8000.0, 0.0]]; + for k in (0..4000).rev() { + let x = 2.0 * k as f64; + comb.extend([[x + 2.0, 5.0], [x + 1.0, 5.0], [x + 1.0, 1.0]]); + } + let positions = lift(&comb); + let part = polygon(comb.len()); + assert_eq!(part.triangles_in(&positions).count(), part.triangle_count()); +} + +#[test] +fn unified_and_stl_use_the_clipped_triangles() { + let notch = [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [1.0, 0.5], [0.0, 2.0]]; + let mesh = Mesh { name: "Notch".into(), positions: lift(¬ch), parts: vec![polygon(5)], ..Mesh::default() }; + let expected: Vec<[u32; 3]> = mesh.parts[0].triangles_in(&mesh.positions).map(|t| t.map(|c| c.position)).collect(); + let u = mesh.unified(); + let got: Vec<[u32; 3]> = u.parts[0].iter().map(|t| t.map(|i| u.corners[i as usize].position)).collect(); + assert_eq!(got, expected); + #[cfg(feature = "stl")] + { + let scene = Scene::from_meshes(vec![mesh.clone()], vec![]); + let text = crate::stl::write_ascii(&scene, "n", &Limits::default()).unwrap(); + let back = crate::stl::read(text.as_bytes(), &Limits::default()).unwrap(); + // The facets' area is the face's, 2.5, not the fan's 3.5. + let m = &back.meshes[0]; + let area: f64 = m + .parts + .iter() + .flat_map(Part::triangles) + .map(|t| { + let p = t.map(|c| m.positions[c.position as usize]); + let (a, b) = ([0, 1, 2].map(|k| p[1][k] - p[0][k]), [0, 1, 2].map(|k| p[2][k] - p[0][k])); + let n = [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]; + (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt() / 2.0 + }) + .sum(); + assert!((area - 2.5).abs() < 1e-6, "{area}"); + } +} diff --git a/crates/mesh/src/triangulate.rs b/crates/mesh/src/triangulate.rs new file mode 100644 index 000000000..84e3dd34a --- /dev/null +++ b/crates/mesh/src/triangulate.rs @@ -0,0 +1,226 @@ +//! Triangulating one polygon face: a fan for a convex face, ear clipping for a concave one. +//! +//! The face is projected onto the plane of its two minor axes (dropping the largest component +//! of its Newell normal) and clipped there. Work is charged to a budget the caller shares +//! between the faces of a part, so a crafted face cannot make it quadratic in the file's size; +//! when the budget runs out, or no ear can be found (a self-intersecting face), what is left of +//! the face is fanned. A face always gives `corners − 2` triangles, wound as the face is. + +use crate::Corner; + +/// Steps (ear checks, containment tests, looks for a straight corner) allowed per corner of a +/// part, shared by its faces. +pub(crate) const WORK_PER_CORNER: usize = 256; + +/// Relative tolerance under which a turn counts as straight. +const STRAIGHT: f64 = 1e-12; + +/// The triangles of one face. +pub(crate) enum FaceTriangles<'a> { + /// A fan from the first corner; `next` is the corner the next triangle starts its edge at. + Fan { face: &'a [Corner], next: usize }, + /// Triangles clipped from a concave face. + Ears(std::vec::IntoIter<[Corner; 3]>), +} + +impl Iterator for FaceTriangles<'_> { + type Item = [Corner; 3]; + + fn next(&mut self) -> Option<[Corner; 3]> { + match self { + FaceTriangles::Fan { face, next } => { + let t = [*face.first()?, *face.get(*next)?, *face.get(*next + 1)?]; + *next += 1; + Some(t) + } + FaceTriangles::Ears(it) => it.next(), + } + } +} + +/// Triangulates `face`, whose corners index `positions`, charging its work to `budget`. +pub(crate) fn face<'a>(face: &'a [Corner], positions: &[[f64; 3]], budget: &mut usize) -> FaceTriangles<'a> { + let fan = FaceTriangles::Fan { face, next: 1 }; + if face.len() <= 3 { + return fan; + } + let Some(pts) = project(face, positions) else { return fan }; + let area: f64 = (0..pts.len()).map(|i| cross(pts[i], pts[(i + 1) % pts.len()])).sum(); + if !area.is_finite() || area == 0.0 { + return fan; + } + let ring = Ring::new(pts, area.signum()); + if ring.is_convex() { + return fan; + } + FaceTriangles::Ears(ring.clip(face, budget).into_iter()) +} + +/// The face's corners in 2D, on the plane of the two axes its Newell normal leans on least; +/// `None` when a corner has no position or the face has no finite normal. +fn project(face: &[Corner], positions: &[[f64; 3]]) -> Option> { + let p: Vec<[f64; 3]> = face.iter().map(|c| positions.get(c.position as usize).copied()).collect::>()?; + let mut n = [0.0f64; 3]; + for (i, a) in p.iter().enumerate() { + let b = p[(i + 1) % p.len()]; + n[0] += (a[1] - b[1]) * (a[2] + b[2]); + n[1] += (a[2] - b[2]) * (a[0] + b[0]); + n[2] += (a[0] - b[0]) * (a[1] + b[1]); + } + let n = n.map(f64::abs); + if !n.iter().all(|x| x.is_finite()) { + return None; + } + // Drop the dominant axis, keeping the other two in cyclic order so the winding seen from the + // normal's side is kept; the sign of the projected area decides orientation anyway. + let (u, v) = if n[0] >= n[1] && n[0] >= n[2] { + (1, 2) + } else if n[1] >= n[2] { + (2, 0) + } else { + (0, 1) + }; + Some(p.iter().map(|q| [q[u], q[v]]).collect()) +} + +/// The z component of `a × b`. +fn cross(a: [f64; 2], b: [f64; 2]) -> f64 { + a[0] * b[1] - a[1] * b[0] +} + +/// Twice the signed area of triangle `a b c`. +fn orient(a: [f64; 2], b: [f64; 2], c: [f64; 2]) -> f64 { + (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]) +} + +/// A face's projected corners as a doubly linked ring that ears are clipped from. +struct Ring { + pts: Vec<[f64; 2]>, + /// The sign of the face's projected area: turns of this sign are convex. + sign: f64, + prev: Vec, + next: Vec, +} + +impl Ring { + fn new(pts: Vec<[f64; 2]>, sign: f64) -> Ring { + let n = pts.len(); + Ring { pts, sign, prev: (0..n).map(|i| (i + n - 1) % n).collect(), next: (0..n).map(|i| (i + 1) % n).collect() } + } + + /// The turn at corner `i`, positive when convex; and the tolerance under which it is straight. + fn turn(&self, i: usize) -> (f64, f64) { + let (a, b, c) = (self.pts[self.prev[i]], self.pts[i], self.pts[self.next[i]]); + let (e, f) = ([b[0] - a[0], b[1] - a[1]], [c[0] - b[0], c[1] - b[1]]); + (cross(e, f) * self.sign, STRAIGHT * e[0].hypot(e[1]) * f[0].hypot(f[1])) + } + + /// No corner turns the other way. A face that winds round more than once (a pentagram) + /// counts as convex too and keeps its fan. + fn is_convex(&self) -> bool { + (0..self.pts.len()).all(|i| { + let (t, tol) = self.turn(i); + t >= -tol + }) + } + + /// Whether the triangle at corner `i` is an ear: convex, and no corner that is not convex + /// lies in it or on its edges (corners at the same place as one of its own excepted). + /// `None` when `budget` runs out. + fn is_ear(&self, i: usize, reflex: &[usize], budget: &mut usize) -> Option { + *budget = budget.checked_sub(1)?; + let (t, tol) = self.turn(i); + if t <= tol { + return Some(false); + } + let (a, b, c) = (self.pts[self.prev[i]], self.pts[i], self.pts[self.next[i]]); + for &r in reflex { + *budget = budget.checked_sub(1)?; + let p = self.pts[r]; + let (turn, tol) = self.turn(r); + if p == a || p == b || p == c || turn > tol { + continue; + } + if self.left_of(a, b, p) && self.left_of(b, c, p) && self.left_of(c, a, p) { + return Some(false); + } + } + Some(true) + } + + /// Whether `p` lies on the inner side of edge `a b`, or on it within rounding (a corner on an + /// ear's edge, after the face is projected, may land a hair outside). + fn left_of(&self, a: [f64; 2], b: [f64; 2], p: [f64; 2]) -> bool { + let l1 = |u: [f64; 2], v: [f64; 2]| (v[0] - u[0]).abs() + (v[1] - u[1]).abs(); + orient(a, b, p) * self.sign >= -STRAIGHT * l1(a, b) * l1(a, p) + } + + /// The first straight corner of the `left` corners from `from` on, charging each look to + /// `budget`. + fn straight(&self, from: usize, left: usize, budget: &mut usize) -> Option { + let mut j = from; + for _ in 0..left { + *budget = budget.checked_sub(1)?; + let (t, tol) = self.turn(j); + if t.abs() <= tol { + return Some(j); + } + j = self.next[j]; + } + None + } + + /// Unlinks corner `i`, returning its triangle. + fn cut(&mut self, i: usize, face: &[Corner]) -> [Corner; 3] { + let (a, c) = (self.prev[i], self.next[i]); + self.next[a] = c; + self.prev[c] = a; + [face[a], face[i], face[c]] + } + + /// Clips ears until a triangle is left. When a whole lap finds no ear, a straight corner is + /// cut instead (its triangle has no area); failing that, or when the budget runs out, the + /// rest is fanned. + fn clip(mut self, face: &[Corner], budget: &mut usize) -> Vec<[Corner; 3]> { + let mut out = Vec::with_capacity(face.len() - 2); + let mut removed = vec![false; face.len()]; + let mut reflex: Vec = (0..face.len()).filter(|&i| self.turn(i).0 <= self.turn(i).1).collect(); + let (mut left, mut i, mut stop) = (face.len(), 0, 0); + while left > 3 { + let ear = match self.is_ear(i, &reflex, budget) { + Some(true) => true, + Some(false) => { + i = self.next[i]; + if i != stop { + continue; + } + match self.straight(i, left, budget) { + Some(j) => { + i = j; + true + } + None => false, + } + } + None => false, + }; + if !ear { + break; + } + let c = self.next[i]; + out.push(self.cut(i, face)); + removed[i] = true; + reflex.retain(|&r| !removed[r]); + left -= 1; + (i, stop) = (c, c); + } + // Fan whatever is left from corner `i`. + let first = i; + let mut b = self.next[first]; + while self.next[b] != first { + out.push([face[first], face[b], face[self.next[b]]]); + b = self.next[b]; + } + out + } +} From 0649a07aa11834fa5bd7052c8b97a861db532a22 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 18:15:52 +0100 Subject: [PATCH 60/97] craft-audio: ITU-T G.726 ADPCM speech codec (#1531) (#1792) * craft-audio: ITU-T G.726 ADPCM speech codec (#1531) * fix(audio): mask G726 sample codewords before adaptation --------- Co-authored-by: Dylan M. Taylor --- crates/audio/Cargo.toml | 6 + crates/audio/src/g726.rs | 996 ++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 2 + crates/audio/tests/g726_oracle.rs | 218 +++++++ 4 files changed, 1222 insertions(+) create mode 100644 crates/audio/src/g726.rs create mode 100644 crates/audio/tests/g726_oracle.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 4a873aab5..63eaefdc8 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -51,6 +51,8 @@ qoa-decode = [] qoa-encode = [] # ITU-T G.722 wideband sub-band ADPCM speech codec (64 kbit/s). g722 = [] +# ITU-T G.726 ADPCM speech codec (16/24/32/40 kbit/s). +g726 = [] opus-encode = [] # GSM 06.10 full-rate speech: decoder and encoder in the `gsm` module, each on its own. gsm = ["gsm-decode", "gsm-encode"] @@ -147,6 +149,10 @@ required-features = ["qoa"] name = "g722_oracle" required-features = ["g722"] +[[test]] +name = "g726_oracle" +required-features = ["g726"] + [[test]] name = "sbc_oracle" required-features = ["sbc"] diff --git a/crates/audio/src/g726.rs b/crates/audio/src/g726.rs new file mode 100644 index 000000000..6ac02359d --- /dev/null +++ b/crates/audio/src/g726.rs @@ -0,0 +1,996 @@ +//! ITU-T Recommendation G.726 ADPCM speech codec (16, 24, 32, 40 kbit/s). +//! +//! Clean-room implementation based on ITU-T Recommendation G.726 (12/1990) +//! "40, 32, 24, 16 kbit/s Adaptive Differential Pulse Code Modulation (ADPCM)". +//! +//! Provides encoding from 8 kHz 16-bit linear PCM to G.726 bitstreams, and decoding +//! from G.726 bitstreams to 8 kHz 16-bit linear PCM. +//! +//! Supports both standard big-endian bit packing (network order / RFC 3551) and +//! little-endian bit packing (RIFF WAV / AVID format tag 0x0045 / 0x0014). + +const MAX_CHANNELS: usize = 8; +const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; +const MAX_SAMPLES: usize = 64 * 1024 * 1024; + +/// Bit rate for G.726 ADPCM. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BitRate { + /// 16 kbit/s (2 bits per sample). + Rate16k, + /// 24 kbit/s (3 bits per sample). + Rate24k, + /// 32 kbit/s (4 bits per sample). + Rate32k, + /// 40 kbit/s (5 bits per sample). + Rate40k, +} + +impl BitRate { + /// Number of bits per code (sample). + #[inline] + #[must_use] + pub const fn code_size(self) -> usize { + match self { + Self::Rate16k => 2, + Self::Rate24k => 3, + Self::Rate32k => 4, + Self::Rate40k => 5, + } + } + + /// Bit rate in bits per second. + #[inline] + #[must_use] + pub const fn bit_rate_bps(self) -> u32 { + match self { + Self::Rate16k => 16_000, + Self::Rate24k => 24_000, + Self::Rate32k => 32_000, + Self::Rate40k => 40_000, + } + } +} + +/// Bit packing order within bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum BitPacking { + /// Big-endian packing: MSB to LSB (standard RFC 3551 / network order). + #[default] + BigEndian, + /// Little-endian packing: LSB to MSB (WAV / RIFF order). + LittleEndian, +} + +/// Errors returned by G.726 operations. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// Channel count must be between 1 and 8. + #[error("unsupported channel count: {0} (must be 1..=8)")] + InvalidChannels(usize), + /// Input exceeds safe maximum memory bound. + #[error("input exceeds safe maximum processing limit")] + InputTooLarge, + /// Output buffer allocation failed. + #[error("memory allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// G.726 Tables +// --------------------------------------------------------------------------- + +// Table 11..14 (I -> DQS, DQLN) +static OUT_16: [(u8, u16); 4] = [(0, 116), (0, 365), (1, 365), (1, 116)]; + +static OUT_24: [(u8, u16); 8] = [(0, 2048), (0, 135), (0, 273), (0, 373), (1, 373), (1, 273), (1, 135), (1, 2048)]; + +static OUT_32: [(u8, u16); 16] = [ + (0, 2048), + (0, 4), + (0, 135), + (0, 213), + (0, 273), + (0, 323), + (0, 373), + (0, 425), + (1, 425), + (1, 373), + (1, 323), + (1, 273), + (1, 213), + (1, 135), + (1, 4), + (1, 2048), +]; + +static OUT_40: [(u8, u16); 32] = [ + (0, 2048), + (0, 4030), + (0, 28), + (0, 104), + (0, 169), + (0, 224), + (0, 274), + (0, 318), + (0, 358), + (0, 395), + (0, 429), + (0, 459), + (0, 488), + (0, 514), + (0, 539), + (0, 566), + (1, 566), + (1, 539), + (1, 514), + (1, 488), + (1, 459), + (1, 429), + (1, 395), + (1, 358), + (1, 318), + (1, 274), + (1, 224), + (1, 169), + (1, 104), + (1, 28), + (1, 4030), + (1, 2048), +]; + +// FUNCTW: scale factor multipliers WI +static WI_16: [u16; 2] = [4074, 439]; +static WI_24: [u16; 4] = [4092, 30, 137, 582]; +static WI_32: [u16; 8] = [4084, 18, 41, 64, 112, 198, 355, 1122]; +static WI_40: [u16; 16] = [14, 14, 24, 39, 40, 41, 58, 100, 141, 179, 219, 280, 358, 440, 529, 696]; + +#[inline] +fn get_wi(rate: BitRate, code: u8) -> u16 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { (code & 1) as usize } else { ((3 - code) & 1) as usize }; + WI_16[im] + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { (code & 3) as usize } else { ((7 - code) & 3) as usize }; + WI_24[im] + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { (code & 7) as usize } else { ((15 - code) & 7) as usize }; + WI_32[im] + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { (code & 15) as usize } else { ((31 - code) & 15) as usize }; + WI_40[im] + } + } +} + +#[inline] +fn get_fi(rate: BitRate, code: u8) -> u8 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { code & 1 } else { (3 - code) & 1 }; + if im == 1 { 7 } else { 0 } + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { code & 3 } else { (7 - code) & 3 }; + match im { + 0 => 0, + 1 => 1, + 2 => 2, + _ => 7, + } + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { code & 7 } else { (15 - code) & 7 }; + if im <= 2 { + 0 + } else if im <= 5 { + 1 + } else if im == 6 { + 3 + } else { + 7 + } + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { code & 15 } else { (31 - code) & 15 }; + if im <= 4 { + 0 + } else if im <= 9 { + 1 + } else { + match im { + 10 => 2, + 11 => 3, + 12 => 4, + 13 => 5, + _ => 6, + } + } + } + } +} + +// Quantizer decision intervals (lo, hi, positive_code, negative_code) +static THRESH_16: [(i32, i32, u8, u8); 1] = [(261, 2047, 1, 2)]; + +static THRESH_24: [(i32, i32, u8, u8); 3] = [(331, 2047, 3, 4), (218, 330, 2, 5), (8, 217, 1, 6)]; + +static THRESH_32: [(i32, i32, u8, u8); 8] = [ + (400, 2047, 7, 8), + (349, 399, 6, 9), + (300, 348, 5, 10), + (246, 299, 4, 11), + (178, 245, 3, 12), + (80, 177, 2, 13), + (0, 79, 1, 14), + (3972, 4095, 1, 14), +]; + +static THRESH_40: [(i32, i32, u8, u8); 16] = [ + (553, 2047, 15, 16), + (528, 552, 14, 17), + (502, 527, 13, 18), + (475, 501, 12, 19), + (445, 474, 11, 20), + (413, 444, 10, 21), + (378, 412, 9, 22), + (339, 377, 8, 23), + (298, 338, 7, 24), + (250, 297, 6, 25), + (198, 249, 5, 26), + (139, 197, 4, 27), + (68, 138, 3, 28), + (0, 67, 2, 29), + (4080, 4095, 2, 29), + (3974, 4079, 1, 30), +]; + +#[inline] +fn quantize_16(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_16 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + if ds == 0 { 0 } else { 3 } +} + +#[inline] +fn quantize_24(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_24 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 7 +} + +#[inline] +fn quantize_32(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_32 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 15 +} + +#[inline] +fn quantize_40(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_40 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 31 +} + +// --------------------------------------------------------------------------- +// G.726 Core State +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct Core { + rate: BitRate, + is_40k: bool, + a: [u16; 2], + b: [u16; 6], + dms: i16, + dml: i16, + ap: i16, + yu: i16, + yl: i32, + sr: [u16; 2], + dq: [u16; 6], + pk: [u8; 2], + td: i16, +} + +impl Core { + fn new(rate: BitRate) -> Self { + let is_40k = matches!(rate, BitRate::Rate40k); + let mut core = + Self { rate, is_40k, a: [0; 2], b: [0; 6], dms: 0, dml: 0, ap: 0, yu: 544, yl: 34816, sr: [32, 32], dq: [32; 6], pk: [0; 2], td: 0 }; + core.reset(); + core + } + + fn reset(&mut self) { + self.a = [0; 2]; + self.b = [0; 6]; + self.dms = 0; + self.dml = 0; + self.ap = 0; + self.yu = 544; + self.yl = 34816; + self.sr = [32, 32]; + self.dq = [32; 6]; + self.pk = [0; 2]; + self.td = 0; + } + + #[inline] + fn fmult(an: u16, srn: u16) -> u16 { + let an_s = (an >> 15) & 1; + let an_mag = if an_s == 0 { (an >> 2) & 0x1FFF } else { (16384_u32.wrapping_sub((an >> 2) as u32) & 0x1FFF) as u16 }; + let an_exp = if an_mag > 0 { (16 - an_mag.leading_zeros()).min(13) as u16 } else { 0 }; + let an_mant = if an_mag == 0 { 1 << 5 } else { (((an_mag as u32) << 6) >> an_exp) as u16 & 0x3F }; + + let srn_s = (srn >> 10) & 1; + let srn_exp = (srn >> 6) & 15; + let srn_mant = srn & 63; + + let wan_s = srn_s ^ an_s; + let wan_exp = srn_exp + an_exp; + let wan_mant = (((srn_mant as u32 * an_mant as u32) + 48) >> 4) as u16; + + let wan_mag = + if wan_exp <= 26 { ((wan_mant as u32) << 7) >> (26 - wan_exp) } else { (((wan_mant as u32) << 7) << (wan_exp - 26)) & 0x7FFF } as u16; + + if wan_s == 0 { wan_mag } else { (65536_u32.wrapping_sub(wan_mag as u32) & 0xFFFF) as u16 } + } + + #[inline] + fn quantize(&self, dln: i32, ds: u8) -> u8 { + match self.rate { + BitRate::Rate16k => quantize_16(dln, ds), + BitRate::Rate24k => quantize_24(dln, ds), + BitRate::Rate32k => quantize_32(dln, ds), + BitRate::Rate40k => quantize_40(dln, ds), + } + } + + #[inline] + fn table_lookup(&self, code: u8) -> (u8, u16) { + match self.rate { + BitRate::Rate16k => OUT_16[(code & 3) as usize], + BitRate::Rate24k => OUT_24[(code & 7) as usize], + BitRate::Rate32k => OUT_32[(code & 15) as usize], + BitRate::Rate40k => OUT_40[(code & 31) as usize], + } + } + + #[inline] + fn compute_accum(&self) -> (i16, i16) { + let wa0 = Self::fmult(self.a[0], self.sr[0]); + let wa1 = Self::fmult(self.a[1], self.sr[1]); + let mut sezi: u32 = 0; + for i in 0..6 { + sezi = (sezi + Self::fmult(self.b[i], self.dq[i]) as u32) & 0xFFFF; + } + let sei = (sezi + wa1 as u32 + wa0 as u32) & 0xFFFF; + let sez = (sezi as i16) >> 1; + let se = (sei as i16) >> 1; + (sez, se) + } + + #[inline] + fn compute_mix(&self) -> i32 { + let al = if self.ap >= 256 { 64 } else { self.ap >> 2 } as i32; + let dif = (self.yu as i32 + 16384 - (self.yl >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difm = if difs == 0 { dif } else { (16384 - dif) & 8191 }; + let prodm = (difm * al) >> 6; + let prod = if difs == 0 { prodm } else { (16384 - prodm) & 8191 }; + ((self.yl >> 6) + prod) & 8191 + } + + #[inline] + fn quantize_sample(&self, sample: i16, se: i16, y: i32) -> u8 { + let sl = (sample >> 2) as i32; + let sl_ext = if sl >= 0 { sl } else { 65536 + sl }; + let se_ext = if se >= 0 { se as i32 } else { 65536 + se as i32 }; + let d = ((sl_ext + 65536 - se_ext) & 0xFFFF) as u16; + + let ds = ((d >> 15) & 1) as u8; + let dqm = if ds == 0 { d } else { (65536_u32.wrapping_sub(d as u32) & 0x7FFF) as u16 }; + let exp = if dqm > 1 { (15 - dqm.leading_zeros()).min(14) } else { 0 }; + let mant = (((dqm as u32) << 7) >> exp) & 127; + let dl = ((exp << 7) + mant) as u16; + let dln = (dl as i32 + 4096 - (y >> 2)) & 4095; + self.quantize(dln, ds) + } + + #[inline] + fn step(&mut self, sample: i16, is_encoder: bool, code_in: u8) -> (u8, i16) { + let (sez, se) = self.compute_accum(); + let y = self.compute_mix(); + + let code = if is_encoder { self.quantize_sample(sample, se, y) } else { code_in }; + + // 4. RECONST & ADDA & ANTILOG + let (dqs, dqln) = self.table_lookup(code); + let dql = (dqln as i32 + (y >> 2)) & 4095; + let dex = (dql >> 7) & 15; + let dmn = dql & 127; + let dqt = 128 + dmn; + let dqmag = if (dql >> 11) == 0 { ((dqt << 7) >> (14 - dex)) as u16 } else { 0 }; + let dq = if self.is_40k { ((dqs as u16) << 15) | (dqmag & 0x7FFF) } else { ((dqs as u16) << 14) | (dqmag & 0x3FFF) }; + + // 5. ADDB & ADDC + let dqi = if dqs == 0 { + dq as u32 + } else if self.is_40k { + 65536_u32.wrapping_sub((dq & 0x7FFF) as u32) & 0xFFFF + } else { + 65536_u32.wrapping_sub((dq & 0x3FFF) as u32) & 0xFFFF + }; + let sei_ext = if se >= 0 { se as u32 } else { (65536 + se as i32) as u32 }; + let sr = ((dqi + sei_ext) & 0xFFFF) as u16; + + let sezi_ext = if sez >= 0 { sez as u32 } else { (65536 + sez as i32) as u32 }; + let dqsez = ((dqi + sezi_ext) & 0xFFFF) as u16; + let pk0 = ((dqsez >> 15) & 1) as u8; + let sigpk = if dqsez == 0 { 1 } else { 0 }; + + // 6. FLOATA & FLOATB + let dq_mag = if self.is_40k { dq & 0x7FFF } else { dq & 0x3FFF }; + let (dq_exp, dq_mant) = if dq_mag == 0 { + (0, 32) + } else { + let max_exp = if self.is_40k { 15 } else { 14 }; + let exp = (16 - dq_mag.leading_zeros()).min(max_exp); + let mant = (((dq_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let dq0 = ((dqs as u16) << 10) | (dq_exp << 6) | (dq_mant & 63); + + let sr_s = ((sr >> 15) & 1) as u8; + let sr_mag = if sr_s == 0 { sr } else { (65536_u32.wrapping_sub(sr as u32) & 0x7FFF) as u16 }; + let (sr_exp, sr_mant) = if sr_mag == 0 { + (0, 32) + } else { + let exp = (16 - sr_mag.leading_zeros()).min(15); + let mant = (((sr_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let sr0 = ((sr_s as u16) << 10) | (sr_exp << 6) | (sr_mant & 63); + + self.update_adaptation_and_predictors(code, y, pk0, sigpk, dqs, dq_mag); + + self.sr = [sr0, self.sr[0]]; + self.dq = [dq0, self.dq[0], self.dq[1], self.dq[2], self.dq[3], self.dq[4]]; + self.pk = [pk0, self.pk[0]]; + + let sr_signed = if sr < 32768 { sr as i32 } else { sr as i32 - 65536 }; + let out_pcm = (sr_signed << 2).clamp(-32768, 32767) as i16; + (code, out_pcm) + } + + #[inline] + fn adapt_scale(&mut self, code: u8, y: i32) { + let wi = get_wi(self.rate, code); + let dif = (((wi as i32) << 5) + 131072 - y) & 131071; + let difs = (dif >> 16) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 4096 }; + let yut = (y + difsx) & 8191; + let yup = yut.clamp(544, 5120); + + let dif = (yup + ((1048576 - self.yl) >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difsx = if difs == 0 { dif } else { dif + 507904 }; + self.yu = yup as i16; + self.yl = (self.yl + difsx) & 524287; + } + + #[inline] + fn adapt_speed(&mut self, code: u8, y: i32, dq_mag: u16) -> (i16, i16, u8) { + let fi = get_fi(self.rate, code); + let dif = (((fi as i32) << 9) + 8192 - self.dms as i32) & 8191; + let difs = (dif >> 12) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 3840 }; + let dmsp = ((difsx + self.dms as i32) & 4095) as i16; + + let dif = (((fi as i32) << 11) + 32768 - self.dml as i32) & 32767; + let difs = (dif >> 14) & 1; + let difsx = if difs == 0 { dif >> 7 } else { (dif >> 7) + 16128 }; + let dmlp = ((difsx + self.dml as i32) & 16383) as i16; + + let dif = (((dmsp as i32) << 2) + 32768 - dmlp as i32) & 32767; + let difs = (dif >> 14) & 1; + let difm = if difs == 0 { dif } else { (32768 - dif) & 16383 }; + let dthr = (dmlp as i32) >> 3; + + let tdp = if (32768..53760).contains(&self.a[1]) { 1 } else { 0 }; + let ax = if y >= 1536 && tdp == 0 && difm < dthr { 0 } else { 1 }; + + let dif = ((ax << 9) + 2048 - self.ap as i32) & 2047; + let difs = (dif >> 10) & 1; + let difsx = if difs == 0 { dif >> 4 } else { (dif >> 4) + 1920 }; + let app = ((difsx + self.ap as i32) & 1023) as i16; + + let ylint = (self.yl >> 15) as u32; + let ylfrac = ((self.yl >> 10) & 31) as u32; + let thr1 = (32 + ylfrac) << ylint; + let thr2 = if self.is_40k && ylint > 9 { + 31 << 10 + } else if !self.is_40k && ylint > 8 { + 31 << 9 + } else { + thr1 + }; + let dqthr = (thr2 + (thr2 >> 1)) >> 1; + let tr = if (dq_mag as u32) > dqthr && self.td == 1 { 1 } else { 0 }; + let apr = if tr == 1 { 256 } else { app }; + + self.dms = dmsp; + self.dml = dmlp; + self.ap = apr; + self.td = if tr == 1 { 0 } else { tdp }; + + (apr, tdp, tr) + } + + #[inline] + fn update_predictors(&mut self, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16, tr: u8) { + let pks = pk0 ^ self.pk[0]; + let uga1 = if sigpk == 1 { + 0 + } else if pks == 0 { + 192 + } else { + 65344 + }; + let a1s = (self.a[0] >> 15) & 1; + let ula1 = if a1s == 0 { + (65536_u32.wrapping_sub((self.a[0] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[0] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ua1 = (uga1 as u32 + ula1 as u32) & 0xFFFF; + let a1t = ((self.a[0] as u32 + ua1) & 0xFFFF) as u16; + + let pks1 = pk0 ^ self.pk[0]; + let pks2 = pk0 ^ self.pk[1]; + let uga2a = if pks2 == 0 { 16384_u32 } else { 114688_u32 }; + let a1_u = self.a[0]; + let fa1 = if a1s == 0 { + if a1_u <= 8191 { (a1_u as u32) << 2 } else { 8191 << 2 } + } else if a1_u >= 57345 { + ((a1_u as u32) << 2) & 131071 + } else { + 24577 << 2 + }; + let fa = if pks1 == 1 { fa1 } else { (131072_u32.wrapping_sub(fa1)) & 131071 }; + let uga2b = (uga2a + fa) & 131071; + let uga2s = (uga2b >> 16) & 1; + let uga2 = if sigpk == 1 { + 0 + } else if uga2s == 0 { + uga2b >> 7 + } else { + (uga2b >> 7) + 64512 + } as u16; + let a2s = (self.a[1] >> 15) & 1; + let ula2 = if a2s == 0 { + (65536_u32.wrapping_sub((self.a[1] >> 7) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[1] >> 7) + 65024) as u32) & 0xFFFF) as u16 + }; + let ua2 = (uga2 as u32 + ula2 as u32) & 0xFFFF; + let a2t = ((self.a[1] as u32 + ua2) & 0xFFFF) as u16; + + let a2p = if (32768..=53248).contains(&a2t) { + 53248 + } else if (12288..=32767).contains(&a2t) { + 12288 + } else { + a2t + }; + + let ome = 15360_u32; + let a1ul = ((ome + 65536 - a2p as u32) & 0xFFFF) as u16; + let a1ll = ((a2p as u32 + 65536 - ome) & 0xFFFF) as u16; + let a1p = if a1t >= 32768 && a1t <= a1ll { + a1ll + } else if a1t >= a1ul && a1t <= 32767 { + a1ul + } else { + a1t + }; + + let a1r = if tr == 1 { 0 } else { a1p }; + let a2r = if tr == 1 { 0 } else { a2p }; + + let mut new_b = [0u16; 6]; + for (i, slot) in new_b.iter_mut().enumerate() { + let un = (dqs ^ ((self.dq[i] >> 10) as u8)) & 1; + let ugbn = if dq_mag == 0 { + 0 + } else if un == 0 { + 128 + } else { + 65408 + }; + let bns = (self.b[i] >> 15) & 1; + let ulbn = if self.is_40k { + if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 9) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 9) + 65408) as u32) & 0xFFFF) as u16 + } + } else if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ubn = (ugbn as u32 + ulbn as u32) & 0xFFFF; + let bnp = ((self.b[i] as u32 + ubn) & 0xFFFF) as u16; + *slot = if tr == 1 { 0 } else { bnp }; + } + + self.a[0] = a1r; + self.a[1] = a2r; + self.b = new_b; + } + + #[inline] + fn update_adaptation_and_predictors(&mut self, code: u8, y: i32, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16) { + self.adapt_scale(code, y); + let (_, _, tr) = self.adapt_speed(code, y, dq_mag); + self.update_predictors(pk0, sigpk, dqs, dq_mag, tr); + } +} + +// --------------------------------------------------------------------------- +// Decoder & Encoder structs +// --------------------------------------------------------------------------- + +/// G.726 ADPCM decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Decoder { + /// Create a new G.726 decoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset decoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Decode a single quantized ADPCM code into an 8 kHz 16-bit linear PCM sample. + /// Bits above the configured code width are ignored, as in packed-stream decoding. + #[inline] + pub fn decode_sample(&mut self, code: u8) -> i16 { + // Adaptation must see the same bounded codeword as the reconstruction table; + // otherwise unused high bits can underflow its unsigned inverse-code arithmetic. + let code = code & ((1u8 << self.core.rate.code_size()) - 1); + self.core.step(0, false, code).1 + } + + /// Decode G.726 bitstream bytes into 8 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_samples = (src.len() * 8) / cs; + dst.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &b in src { + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << 8) | (b as u32); + self.num_bits += 8; + while self.num_bits >= cs { + let code = ((self.bit_buf >> (self.num_bits - cs)) & ((1 << cs) - 1)) as u8; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &b in src { + self.bit_buf |= (b as u32) << self.num_bits; + self.num_bits += 8; + while self.num_bits >= cs { + let code = (self.bit_buf & ((1 << cs) - 1)) as u8; + self.bit_buf >>= cs; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + } + } + } + Ok(()) + } +} + +/// G.726 ADPCM encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Encoder { + /// Create a new G.726 encoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset encoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Encode a single 8 kHz 16-bit linear PCM sample into an ADPCM code word. + #[inline] + pub fn encode_sample(&mut self, sample: i16) -> u8 { + self.core.step(sample, true, 0).0 + } + + /// Encode 8 kHz 16-bit linear PCM samples into G.726 bitstream bytes, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_bytes = (src.len() * cs).div_ceil(8); + dst.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << cs) | ((code as u32) & ((1 << cs) - 1)); + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push(((self.bit_buf >> (self.num_bits - 8)) & 0xFF) as u8); + self.num_bits -= 8; + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf |= (code as u32) << self.num_bits; + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push((self.bit_buf & 0xFF) as u8); + self.bit_buf >>= 8; + self.num_bits -= 8; + } + } + } + } + Ok(()) + } + + /// Flush any remaining buffered bits into `dst`, padding with zeroes. + pub fn flush(&mut self, dst: &mut Vec) -> Result<(), Error> { + if self.num_bits > 0 { + dst.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + match self.packing { + BitPacking::BigEndian => { + let b = ((self.bit_buf << (8 - self.num_bits)) & 0xFF) as u8; + dst.push(b); + } + BitPacking::LittleEndian => { + let b = (self.bit_buf & 0xFF) as u8; + dst.push(b); + } + } + self.bit_buf = 0; + self.num_bits = 0; + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono G.726 bitstream into 8 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut decoder = Decoder::new(rate, packing); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 8 kHz 16-bit linear PCM samples into a G.726 bitstream. +pub fn encode(samples: &[i16], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut encoder = Encoder::new(rate, packing); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + encoder.flush(&mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.726 stream into interleaved 8 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes, rate, packing); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_samples = (bytes.len() * 8) / cs; + let mut out = Vec::new(); + out.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + let mut ch_outs: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_outs.push(Vec::new()); + } + + for (i, &b) in bytes.iter().enumerate() { + let ch = i % channels; + decoders[ch].decode(&[b], &mut ch_outs[ch])?; + } + + let min_len = ch_outs.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_len { + for ch_out in ch_outs.iter().take(channels) { + out.push(ch_out[i]); + } + } + + Ok(out) +} + +/// Encode interleaved 8 kHz 16-bit PCM samples into an interleaved multi-channel G.726 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples, rate, packing); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_bytes = (samples.len() * cs).div_ceil(8); + let mut out = Vec::new(); + out.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + let mut ch_samples: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_samples.push(Vec::new()); + } + + for (i, &s) in samples.iter().enumerate() { + let ch = i % channels; + ch_samples[ch].push(s); + } + + let mut ch_bytes: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let mut b = Vec::new(); + encoders[ch].encode(&ch_samples[ch], &mut b)?; + encoders[ch].flush(&mut b)?; + ch_bytes.push(b); + } + + let min_bytes = ch_bytes.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_bytes { + for ch_b in ch_bytes.iter().take(channels) { + out.push(ch_b[i]); + } + } + + Ok(out) +} + +// --------------------------------------------------------------------------- +// Unit tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sample_api_ignores_unused_codeword_bits() { + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + let mask = (1u8 << rate.code_size()) - 1; + let mut actual = Decoder::new(rate, BitPacking::BigEndian); + let mut expected = Decoder::new(rate, BitPacking::BigEndian); + for code in 0..=u8::MAX { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code & mask)); + } + // High bits must not leave a different predictor state for later valid codes. + for code in 0..=mask { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code)); + } + } + } + + #[test] + fn reject_invalid_channels() { + assert!(decode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(decode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + } + + #[test] + fn roundtrip_silence_all_rates() { + let pcm = vec![0i16; 64]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let encoded = encode(&pcm, rate, packing).expect("encode silence"); + let decoded = decode(&encoded, rate, packing).expect("decode silence"); + assert_eq!(decoded.len(), pcm.len()); + for &s in &decoded { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } + } + + #[test] + fn hostile_input_does_not_panic() { + let mut decoder = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xFF; 1024]; + let _ = decoder.decode(&hostile, &mut out); + + let mut decoder = Decoder::new(BitRate::Rate16k, BitPacking::LittleEndian); + let mut out = Vec::new(); + let _ = decoder.decode(&[0x00, 0xAA, 0x55, 0x12, 0x34], &mut out); + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 339ca07dc..3729ab34b 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -49,6 +49,8 @@ pub mod alac; mod buffer; #[cfg(feature = "g722")] pub mod g722; +#[cfg(feature = "g726")] +pub mod g726; #[cfg(any(feature = "gsm-decode", feature = "gsm-encode"))] pub mod gsm; mod layout; diff --git a/crates/audio/tests/g726_oracle.rs b/crates/audio/tests/g726_oracle.rs new file mode 100644 index 000000000..ec875e2c4 --- /dev/null +++ b/crates/audio/tests/g726_oracle.rs @@ -0,0 +1,218 @@ +#![cfg(feature = "g726")] + +use craft_audio::g726::{BitPacking, BitRate, Decoder, Encoder, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn pearson_correlation(x: &[i16], y: &[i16]) -> f64 { + let n = x.len().min(y.len()); + if n == 0 { + return 0.0; + } + let x = &x[..n]; + let y = &y[..n]; + let mean_x = x.iter().map(|&v| v as f64).sum::() / (n as f64); + let mean_y = y.iter().map(|&v| v as f64).sum::() / (n as f64); + let mut num = 0.0; + let mut denom_x = 0.0; + let mut denom_y = 0.0; + for (&a, &b) in x.iter().zip(y) { + let da = (a as f64) - mean_x; + let db = (b as f64) - mean_y; + num += da * db; + denom_x += da * da; + denom_y += db * db; + } + let denom = (denom_x * denom_y).sqrt(); + if denom > 0.0 { num / denom } else { 0.0 } +} + +fn find_ffmpeg() -> Option { + for cmd in ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/bin/ffmpeg"] { + if Command::new(cmd).arg("-version").output().is_ok() { + return Some(cmd.to_string()); + } + } + None +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 80]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode"); + let dec = decode(&enc, rate, packing).expect("decode"); + assert_eq!(dec.len(), pcm.len()); + for &s in &dec { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let sample_rate = 8000.0; + let freq = 300.0; + let num_samples = 160; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate; + let s = (4000.0 * (2.0 * std::f64::consts::PI * freq * t).sin()) as i16; + pcm.push(s); + } + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode sine"); + let dec = decode(&enc, rate, packing).expect("decode sine"); + let corr = pearson_correlation(&pcm, &dec); + assert!(corr > 0.90, "correlation {corr} too low for rate {rate:?} packing {packing:?}"); + } + } +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + + let pcm = vec![1000i16, 2000, 3000, 2000, 1000, 0, -1000, -2000]; + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + enc.flush(&mut out1).expect("flush 1"); + + let mut dec_pcm1 = Vec::new(); + dec.decode(&out1, &mut dec_pcm1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + enc.flush(&mut out2).expect("flush 2"); + + let mut dec_pcm2 = Vec::new(); + dec.decode(&out2, &mut dec_pcm2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec_pcm1, dec_pcm2); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..160 { + let left = (3000.0 * (i as f64 * 0.05).sin()) as i16; + let right = (2000.0 * (i as f64 * 0.03).cos()) as i16; + stereo_pcm.push(left); + stereo_pcm.push(right); + } + + let enc = encode_interleaved(&stereo_pcm, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("encode stereo"); + let dec = decode_interleaved(&enc, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("decode stereo"); + + assert_eq!(dec.len(), stereo_pcm.len()); + let corr = pearson_correlation(&stereo_pcm, &dec); + assert!(corr > 0.90, "stereo correlation {corr} too low"); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xEE; 1000]; + let _ = dec.decode(&hostile, &mut out); + + let mut enc = Encoder::new(BitRate::Rate40k, BitPacking::LittleEndian); + let mut out_enc = Vec::new(); + let hostile_pcm = vec![i16::MIN, i16::MAX, -1, 1, 0]; + let _ = enc.encode(&hostile_pcm, &mut out_enc); + let _ = enc.flush(&mut out_enc); +} + +#[test] +fn test_ffmpeg_g726_oracle_encoder_and_decoder() { + let ff = match find_ffmpeg() { + Some(f) => f, + None => return, + }; + + let sample_rate = 8000; + let num_samples = 240; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate as f64; + let s = (5000.0 * (2.0 * std::f64::consts::PI * 350.0 * t).sin()) as i16; + pcm.push(s); + } + + let dir = std::env::temp_dir().join("craft_g726_oracle"); + let _ = std::fs::create_dir_all(&dir); + let in_pcm_path = dir.join("input.s16le"); + let mut in_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + in_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&in_pcm_path, &in_bytes).expect("write input pcm"); + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for (packing, ff_codec, ff_fmt) in [(BitPacking::BigEndian, "g726", "g726"), (BitPacking::LittleEndian, "g726le", "g726le")] { + let cs = rate.code_size(); + let ff_g726_path = dir.join(format!("ff_{}_{}.g726", cs, ff_codec)); + + // 1. FFmpeg encodes PCM to G.726 + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "8000", "-ac", "1", "-i"]) + .arg(&in_pcm_path) + .args(["-c:a", ff_codec, "-code_size", &cs.to_string(), "-f", ff_fmt]) + .arg(&ff_g726_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g726_bytes = std::fs::read(&ff_g726_path).expect("read ff g726"); + + // 2. FFmpeg decodes its own G.726 stream + let ff_pcm_back_path = dir.join(format!("ff_back_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&ff_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 3. Our decoder decodes FFmpeg's stream + let our_decoded = decode(&ff_g726_bytes, rate, packing).expect("our decode"); + let corr = pearson_correlation(&our_decoded, &ff_back_samples); + assert!(corr > 0.998, "correlation {corr} too low between our decoder and FFmpeg decoder for rate {rate:?} packing {packing:?}"); + + // 4. Our encoder encodes PCM to G.726 + let our_g726_bytes = encode(&pcm, rate, packing).expect("our encode"); + let our_g726_path = dir.join(format!("our_{}_{}.g726", cs, ff_codec)); + std::fs::write(&our_g726_path, &our_g726_bytes).expect("write our g726"); + + // 5. FFmpeg decodes our encoded stream + let our_decoded_by_ff_path = dir.join(format!("our_by_ff_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&our_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + let corr_input = pearson_correlation(&pcm, &our_by_ff_samples); + assert!( + corr_input > 0.90, + "correlation {corr_input} too low for input vs FFmpeg-decoded our stream for rate {rate:?} packing {packing:?}" + ); + } + } +} From 51aadf525f9ac22ba0afbf127f83e17dacb8f8a8 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Tue, 17 Nov 2026 13:06:31 -0500 Subject: [PATCH 61/97] Share deterministic parser damage fixtures without changing their corpus Preserve the fixture helpers originally authored in Craft Anything testkit and extracted by FredApps for TAR. EVM and TAR now reuse craft-testkit with unchanged mutation sequences. Add sequence and stride regressions. Co-authored-by: FredApps <153173854+FredApps@users.noreply.github.com> Co-authored-by: Dylan M. Taylor --- Cargo.lock | 2 + crates/evm/Cargo.toml | 3 ++ crates/evm/src/test_support.rs | 38 +-------------- crates/tar/Cargo.toml | 3 ++ crates/tar/src/testkit.rs | 42 +--------------- crates/testkit/src/lib.rs | 1 + crates/testkit/src/sample_damage.rs | 74 +++++++++++++++++++++++++++++ 7 files changed, 85 insertions(+), 78 deletions(-) create mode 100644 crates/testkit/src/sample_damage.rs diff --git a/Cargo.lock b/Cargo.lock index d554ad256..d90e8532b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1885,6 +1885,7 @@ dependencies = [ name = "craft-evm" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", "serde_json", "thiserror 2.0.21", @@ -3139,6 +3140,7 @@ dependencies = [ name = "craft-tar" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", ] diff --git a/crates/evm/Cargo.toml b/crates/evm/Cargo.toml index 92d0abae8..018f5dff0 100644 --- a/crates/evm/Cargo.toml +++ b/crates/evm/Cargo.toml @@ -12,3 +12,6 @@ workspace = true serde = { workspace = true } serde_json = { workspace = true } thiserror = { workspace = true } + +[dev-dependencies] +craft-testkit = { workspace = true } diff --git a/crates/evm/src/test_support.rs b/crates/evm/src/test_support.rs index b31ace0a2..0dc9861ef 100644 --- a/crates/evm/src/test_support.rs +++ b/crates/evm/src/test_support.rs @@ -60,40 +60,4 @@ pub mod formats { s } } -pub fn noise(seed: u64, len: usize) -> Vec { - let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; - (0..len) - .map(|_| { - x ^= x << 13; - x ^= x >> 7; - x ^= x << 17; - x as u8 - }) - .collect() -} -pub fn mutations(sample: &[u8]) -> Vec> { - let mut out = Vec::new(); - let n = sample.len(); - let step = (n / 64).max(1); - let mut len = 0; - while len < n { - out.push(sample[..len].to_vec()); - len += step; - } - for (i, seed) in (0..n).step_by(step).zip(1u64..) { - let mut m = sample.to_vec(); - let noise = noise(seed, 8); - for (j, v) in noise.iter().enumerate() { - if let Some(b) = m.get_mut(i + j) { - *b = *v; - } - } - out.push(m); - let mut m = sample.to_vec(); - if let Some(b) = m.get_mut(i) { - *b = 0xff; - } - out.push(m); - } - out -} +pub use craft_testkit::sample_damage::{mutations, noise}; diff --git a/crates/tar/Cargo.toml b/crates/tar/Cargo.toml index e0628a35a..e76bb9e4c 100644 --- a/crates/tar/Cargo.toml +++ b/crates/tar/Cargo.toml @@ -16,3 +16,6 @@ serde = { workspace = true, optional = true } [features] serde = ["dep:serde"] + +[dev-dependencies] +craft-testkit = { workspace = true } diff --git a/crates/tar/src/testkit.rs b/crates/tar/src/testkit.rs index 828644a4b..f435b55e5 100644 --- a/crates/tar/src/testkit.rs +++ b/crates/tar/src/testkit.rs @@ -92,44 +92,4 @@ pub fn cpio_newc(files: &[(&str, &[u8], u32)]) -> Vec { out } -/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. -pub fn noise(seed: u64, len: usize) -> Vec { - let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; - (0..len) - .map(|_| { - x ^= x << 13; - x ^= x >> 7; - x ^= x << 17; - x as u8 - }) - .collect() -} - -/// Every way to damage a sample used by robustness tests: truncations at many lengths and -/// single-byte corruptions spread across the file. -pub fn mutations(sample: &[u8]) -> Vec> { - let mut out = Vec::new(); - let n = sample.len(); - let step = (n / 64).max(1); - let mut len = 0; - while len < n { - out.push(sample[..len].to_vec()); - len += step; - } - for (i, seed) in (0..n).step_by(step).zip(1u64..) { - let mut m = sample.to_vec(); - let noise = noise(seed, 8); - for (j, v) in noise.iter().enumerate() { - if let Some(b) = m.get_mut(i + j) { - *b = *v; - } - } - out.push(m); - let mut m = sample.to_vec(); - if let Some(b) = m.get_mut(i) { - *b = 0xff; - } - out.push(m); - } - out -} +pub use craft_testkit::sample_damage::{mutations, noise}; diff --git a/crates/testkit/src/lib.rs b/crates/testkit/src/lib.rs index 020938371..910f25518 100644 --- a/crates/testkit/src/lib.rs +++ b/crates/testkit/src/lib.rs @@ -39,6 +39,7 @@ pub mod deadline; pub mod guards; pub mod hostile; +pub mod sample_damage; #[cfg(not(target_arch = "wasm32"))] pub use deadline::{DeadlineLimit, wait_until, with_deadline}; diff --git a/crates/testkit/src/sample_damage.rs b/crates/testkit/src/sample_damage.rs new file mode 100644 index 000000000..33d9632bf --- /dev/null +++ b/crates/testkit/src/sample_damage.rs @@ -0,0 +1,74 @@ +//! Stable sampled truncations and corruptions for existing parser regression corpora. +//! +//! Unlike `hostile::mutations`, this preserves the historical TAR/EVM fixture sequence. + +/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. +pub fn noise(seed: u64, len: usize) -> Vec { + let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; + (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect() +} + +/// Every way to damage a sample used by robustness tests: truncations at many lengths and +/// single-byte corruptions spread across the file. +pub fn mutations(sample: &[u8]) -> Vec> { + let mut out = Vec::new(); + let n = sample.len(); + let step = (n / 64).max(1); + let mut len = 0; + while len < n { + out.push(sample[..len].to_vec()); + len += step; + } + for (i, seed) in (0..n).step_by(step).zip(1u64..) { + let mut m = sample.to_vec(); + let noise = noise(seed, 8); + for (j, v) in noise.iter().enumerate() { + if let Some(b) = m.get_mut(i + j) { + *b = *v; + } + } + out.push(m); + let mut m = sample.to_vec(); + if let Some(b) = m.get_mut(i) { + *b = 0xff; + } + out.push(m); + } + out +} + +#[cfg(test)] +mod tests { + use super::{mutations, noise}; + + #[test] + fn fixture_sequence_stays_stable() { + assert_eq!(noise(1, 8), [173, 118, 54, 116, 236, 121, 207, 234]); + assert!(noise(1, 0).is_empty()); + assert!(mutations(&[]).is_empty()); + assert_eq!(mutations(&[42]), vec![vec![], vec![173], vec![255]]); + } + + #[test] + fn sampling_stride_preserves_truncation_and_corruption_order() { + let sample = vec![42; 128]; + let cases = mutations(&sample); + assert_eq!(cases.len(), 192); + for (index, prefix) in cases.iter().take(64).enumerate() { + assert_eq!(prefix, &sample[..index * 2]); + } + for (index, pair) in cases[64..].chunks_exact(2).enumerate() { + assert_eq!(pair[0].len(), sample.len()); + let mut expected = sample.clone(); + expected[index * 2] = 255; + assert_eq!(pair[1], expected); + } + } +} From 29fdd49d6d59e15a0e995ff1f16a289d86963b11 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 13:07:57 -0500 Subject: [PATCH 62/97] Use fixed-size chunks in fixture-order regression --- crates/testkit/src/sample_damage.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/testkit/src/sample_damage.rs b/crates/testkit/src/sample_damage.rs index 33d9632bf..f0bdec729 100644 --- a/crates/testkit/src/sample_damage.rs +++ b/crates/testkit/src/sample_damage.rs @@ -64,7 +64,7 @@ mod tests { for (index, prefix) in cases.iter().take(64).enumerate() { assert_eq!(prefix, &sample[..index * 2]); } - for (index, pair) in cases[64..].chunks_exact(2).enumerate() { + for (index, pair) in cases[64..].as_chunks::<2>().0.iter().enumerate() { assert_eq!(pair[0].len(), sample.len()); let mut expected = sample.clone(); expected[index * 2] = 255; From 5490e83d2a6d0e4e5de5aa4c40f4395989be13cb Mon Sep 17 00:00:00 2001 From: FredApps Date: Tue, 17 Nov 2026 19:12:35 +0100 Subject: [PATCH 63/97] test(media): schedule MXF hostile seeds independently --- crates/media/src/mxf/tests/hostile.rs | 42 ++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/crates/media/src/mxf/tests/hostile.rs b/crates/media/src/mxf/tests/hostile.rs index 015413881..6ff89ed15 100644 --- a/crates/media/src/mxf/tests/hostile.rs +++ b/crates/media/src/mxf/tests/hostile.rs @@ -51,27 +51,53 @@ fn sync_before_on_an_empty_track() { } } -#[test] -fn hostile_input_never_panics() { +// Keep each deterministic hammer independent so test runners can schedule the seeds separately. +// The labels, mutation counts, every-truncation coverage and per-case watchdog stay unchanged. +fn hostile_seeds() -> [Vec; 3] { let (to, flags) = ipbb(); - let seeds = [build(7, |i| vec![i as u8; 100 + i], &to, &flags), build(5, prores_like, &to, &flags), build(4, prores_like, &[], &flags)]; - for (i, s) in seeds.iter().enumerate() { - craft_media_testkit::hostile::hammer(&format!("mxf seed {i}"), s, 6_000, exercise); - } - // The metadata sets and index segments, parsed directly. - let seed = &seeds[0]; + [build(7, |i| vec![i as u8; 100 + i], &to, &flags), build(5, prores_like, &to, &flags), build(4, prores_like, &[], &flags)] +} + +#[test] +fn hostile_input_seed_0_never_panics() { + craft_media_testkit::hostile::hammer("mxf seed 0", &hostile_seeds()[0], 6_000, exercise); +} + +#[test] +fn hostile_input_seed_1_never_panics() { + craft_media_testkit::hostile::hammer("mxf seed 1", &hostile_seeds()[1], 6_000, exercise); +} + +#[test] +fn hostile_input_seed_2_never_panics() { + craft_media_testkit::hostile::hammer("mxf seed 2", &hostile_seeds()[2], 6_000, exercise); +} + +#[test] +fn hostile_index_segment_never_panics() { + let seed = &hostile_seeds()[0]; let index_key = [0x06, 0x0E, 0x2B, 0x34, 0x02, 0x53, 0x01, 0x01, 0x0D, 0x01, 0x02, 0x01, 0x01, 0x10, 0x01, 0x00]; if let Some(v) = value_of(seed, &index_key) { craft_media_testkit::hostile::hammer("mxf index segment", v, 30_000, |d| { let _ = IndexSegment::parse(d); }); } +} + +#[test] +fn hostile_primer_never_panics() { + let seed = &hostile_seeds()[0]; let primer_key = [0x06, 0x0E, 0x2B, 0x34, 0x02, 0x05, 0x01, 0x01, 0x0D, 0x01, 0x02, 0x01, 0x01, 0x05, 0x01, 0x00]; if let Some(v) = value_of(seed, &primer_key) { craft_media_testkit::hostile::hammer("mxf primer", v, 5_000, |d| { let _ = Primer::parse(d); }); } +} + +#[test] +fn hostile_set_never_panics() { + let seed = &hostile_seeds()[0]; let set = seed.windows(16).position(|w| w == set_key(0x18)).and_then(|at| value_of(&seed[at..], &set_key(0x18))); if let Some(v) = set { craft_media_testkit::hostile::hammer("mxf set", v, 20_000, |d| { From a97b7948a9379fb614c2a5cc52594f6a00bcf8ff Mon Sep 17 00:00:00 2001 From: FredApps Date: Tue, 17 Nov 2026 17:02:07 +0100 Subject: [PATCH 64/97] ci: pilot resource-grouped Linux nextest with doctests --- .config/nextest.toml | 21 +++++- .github/workflows/workspace.yml | 17 ++++- scripts/test-workspace-tests.py | 114 ++++++++++++++++++++++++++++++++ 3 files changed, 146 insertions(+), 6 deletions(-) create mode 100644 scripts/test-workspace-tests.py diff --git a/.config/nextest.toml b/.config/nextest.toml index 1037b2310..5e02e048d 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -1,7 +1,6 @@ # cargo-nextest (https://nexte.st) runs every test in its own process, in parallel across test -# binaries. The Windows leg of the Workspace gate uses it (.github/workflows/workspace.yml); every -# other leg, and local runs, keep `cargo test`. Nextest does not run doctests, so the Windows leg -# also runs `cargo test --doc`. +# binaries. Linux and Windows in the Workspace gate use it (.github/workflows/workspace.yml). +# macOS and local runs keep `cargo test`. Both nextest legs also run `cargo test --doc`. # # cargo nextest run --workspace --profile ci # cargo test --workspace --doc @@ -22,6 +21,8 @@ video-fixtures = { max-threads = 1 } # craft-print: `PRINT_TICKET_PROVIDER` serializes the Windows PrintTicket provider, and the tests # share the one test print queue the gate installs. print = { max-threads = 1 } +# The Linux pilot serializes video integration tests sharing generated fixture directories. +linux-video-fixtures = { max-threads = 1 } [[profile.default.overrides]] filter = 'package(craft-ui) & (binary(visual_regression) | test(/^combo::tests::|selected_tab_erases_a_baseline_centered_on_its_bottom_edge/))' @@ -42,3 +43,17 @@ test-group = 'print' fail-fast = false slow-timeout = { period = "60s" } failure-output = "immediate-final" + +# Linux-only pilot: keep the established Windows profile unchanged. GPU consumers share one +# process-independent slot; the video integration binaries share fixture directories. This +# deliberately starts conservatively rather than relying on in-process mutexes across binaries. +[profile.ci-linux] +inherits = "ci" + +[[profile.ci-linux.overrides]] +filter = 'package(craft-ui) | package(craft-keymap) | package(craft-update)' +test-group = 'gpu' + +[[profile.ci-linux.overrides]] +filter = 'package(craft-video) & kind(test)' +test-group = 'linux-video-fixtures' diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 4d717fed8..96cc9333e 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -25,7 +25,7 @@ jobs: with: os: '["ubuntu-latest","windows-latest","macos-latest"]' timeout-minutes: 120 - # The Windows leg runs its tests with nextest (.config/nextest.toml). + # Linux and Windows use nextest with explicit doctests (.config/nextest.toml). tools: cargo-nextest@0.9.150 packages: mesa-vulkan-drivers libvulkan1 craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 @@ -49,11 +49,22 @@ jobs: printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" command: | python3 scripts/test-workspace-concurrency.py + python3 scripts/test-workspace-tests.py cargo fmt --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo clippy --workspace --all-targets --all-features --locked -- -D warnings - cargo test --workspace --locked - cargo test --workspace --all-features --locked + if [ "$RUNNER_OS" = Linux ]; then + # Keep example compilation as well as test=true example tests selected by nextest. + cargo build --workspace --examples --locked + cargo nextest run --workspace --locked --profile ci-linux + cargo test --workspace --doc --locked + cargo build --workspace --examples --all-features --locked + cargo nextest run --workspace --all-features --locked --profile ci-linux + cargo test --workspace --doc --all-features --locked + else + cargo test --workspace --locked + cargo test --workspace --all-features --locked + fi windows-command: | powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' cargo fmt --check diff --git a/scripts/test-workspace-tests.py b/scripts/test-workspace-tests.py new file mode 100644 index 000000000..f6e55f968 --- /dev/null +++ b/scripts/test-workspace-tests.py @@ -0,0 +1,114 @@ +#!/usr/bin/env python3 +"""Exercise the native workflow's command selection without compiling Rust.""" +import os +import re +import subprocess +import tomllib +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +WORKFLOW = ROOT / ".github/workflows/workspace.yml" + + +def block(text, name): + match = re.search(r"^ " + re.escape(name) + r": \|\n((?: .*\n|\n)+)", text, re.M) + if match is None: + raise AssertionError(f"missing command block: {name}") + return "\n".join(line[8:] for line in match[1].splitlines()) + + +def commands(os_name, fail=""): + # Functions avoid executing any caller-supplied cargo command or changing the workspace. + # The real bash -euo pipefail semantics still apply, including failures inside a branch. + stub = """ +cargo() { + printf '%s\\n' "$*" + if [ -n "$FAIL" ] && [ "$*" = "$FAIL" ]; then return 17; fi +} +python3() { :; } +""" + return subprocess.run( + ["bash", "-euo", "pipefail", "-c", stub + block(WORKFLOW.read_text(), "command")], + env={**os.environ, "RUNNER_OS": os_name, "FAIL": fail}, + text=True, capture_output=True, check=False, + ) + + +COMMON = [ + "fmt --check", + "clippy --workspace --all-targets --locked -- -D warnings", + "clippy --workspace --all-targets --all-features --locked -- -D warnings", +] +LINUX = [ + "build --workspace --examples --locked", + "nextest run --workspace --locked --profile ci-linux", + "test --workspace --doc --locked", + "build --workspace --examples --all-features --locked", + "nextest run --workspace --all-features --locked --profile ci-linux", + "test --workspace --doc --all-features --locked", +] + + +class WorkspaceTests(unittest.TestCase): + def test_linux_keeps_both_feature_sets_examples_and_doctests(self): + result = commands("Linux") + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.splitlines(), COMMON + LINUX) + + def test_macos_keeps_cargo_test(self): + result = commands("macOS") + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.splitlines(), COMMON + [ + "test --workspace --locked", "test --workspace --all-features --locked"]) + + def test_each_linux_stage_failure_remains_fatal(self): + for index, command in enumerate(COMMON + LINUX): + with self.subTest(command=command): + result = commands("Linux", command) + self.assertEqual(result.returncode, 17, result.stderr) + self.assertEqual(result.stdout.splitlines(), (COMMON + LINUX)[:index + 1]) + + def test_windows_keeps_its_existing_profile_and_doctests(self): + source = block(WORKFLOW.read_text(), "windows-command") + cargo = [line.strip() for line in source.splitlines() if line.strip().startswith("cargo ")] + self.assertEqual(cargo, ["cargo " + command for command in COMMON + [ + "nextest run --workspace --locked --profile ci", + "test --workspace --doc --locked", + "nextest run --workspace --all-features --locked --profile ci", + "test --workspace --doc --all-features --locked", + ]]) + + def test_linux_inherits_no_retries_no_filtering_and_existing_failure_policy(self): + config = tomllib.loads((ROOT / ".config/nextest.toml").read_text()) + self.assertEqual(config["profile"]["ci-linux"]["inherits"], "ci") + self.assertIs(config["profile"]["ci"]["fail-fast"], False) + for profile in config["profile"].values(): + self.assertNotIn("default-filter", profile) + self.assertNotIn("retries", profile) + self.assertEqual(config["profile"]["ci"]["slow-timeout"], {"period": "60s"}) + + def test_linux_resource_groups_are_serial_and_do_not_change_windows(self): + config = tomllib.loads((ROOT / ".config/nextest.toml").read_text()) + overrides = config["profile"]["ci-linux"]["overrides"] + self.assertEqual(overrides, [ + {"filter": "package(craft-ui) | package(craft-keymap) | package(craft-update)", + "test-group": "gpu"}, + {"filter": "package(craft-video) & kind(test)", "test-group": "linux-video-fixtures"}, + ]) + for override in overrides: + self.assertEqual(config["test-groups"][override["test-group"]]["max-threads"], 1) + self.assertNotIn("overrides", config["profile"]["ci"]) + + def test_workflow_stays_shared_and_keeps_platform_gates(self): + source = WORKFLOW.read_text() + self.assertIn("uses: storytold/craft-common-actions/.github/workflows/gate.yml@main", source) + self.assertIn('os: \'["ubuntu-latest","windows-latest","macos-latest"]\'', source) + self.assertIn(" msrv:", source) + self.assertIn(" wasm:", source) + self.assertIn("python3 scripts/test-workspace-tests.py", block(source, "command")) + + +if __name__ == "__main__": + unittest.main() + From ff502fb75f8e91106b38fd2c867a3f6cfc824e8d Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 18:59:57 +0000 Subject: [PATCH 65/97] ci: run a fraction of the fuzz-style tests on pull requests, all of them nightly craft-testkit's hostile hammer reads CRAFT_HOSTILE_DIVISOR=N: the unmodified seed, every N-th truncation and 1/N of the rounds. hostile::divisor() gives the same value to sweeps written without the hammer; craft-image-codecs' TIFF zoo and malformed-header sweeps use it, with a different offset per input so the inputs together still reach every position. Proptests without their own case count read proptest's PROPTEST_CASES. The Workspace gate and the media, audio, video and PDF workflows set CRAFT_HOSTILE_DIVISOR=8 and PROPTEST_CASES=64. The longest of these tests (craft-media's MXF hostile input, 1,310 s on Windows; craft-pdf's crypt proptests, up to 257 s; the image-codecs sweeps, 140-162 s) drop to about an eighth or a quarter. nightly.yml runs the whole workspace on Linux without either variable, so every case still runs once a day. The gate's test-input setup moves to scripts/ci-test-inputs.sh, shared by both workflows; it uses a corpus that is already present. --- .github/workflows/actions.lock | 1 + .github/workflows/audio.yml | 5 ++ .github/workflows/media.yml | 5 ++ .github/workflows/nightly.yml | 31 +++++++ .github/workflows/pdf.yml | 4 + .github/workflows/video.yml | 5 ++ .github/workflows/workspace.yml | 24 ++---- crates/image-codecs/tests/it/malformed.rs | 11 ++- crates/image-codecs/tests/it/tiff_pages.rs | 11 ++- crates/media-testkit/src/hostile.rs | 10 ++- crates/media-testkit/src/lib.rs | 3 +- crates/media-testkit/tests/hostile.rs | 13 +-- crates/testkit/README.md | 10 +++ crates/testkit/src/hostile.rs | 95 +++++++++++++++++++--- scripts/ci-test-inputs.sh | 32 ++++++++ 15 files changed, 215 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/nightly.yml create mode 100755 scripts/ci-test-inputs.sh diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 02cdf71c8..52c8faf77 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -80,6 +80,7 @@ workflows: - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - 'swatinem/rust-cache@v2.9.3' + '.github/workflows/nightly.yml': [] '.github/workflows/pcraft-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index d6a7ff5e2..48c1384b2 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: # Pull requests share one group per branch, so a newer push cancels the older run. Every other # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index 4814e35ca..f397f5cb3 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: # Pull requests share one group per branch, so a newer push cancels the older run. Every other # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml new file mode 100644 index 000000000..2ecc68ecb --- /dev/null +++ b/.github/workflows/nightly.yml @@ -0,0 +1,31 @@ +name: Nightly full tests + +# The tests the Workspace gate shortens, in full, once a day: every hostile-input hammer and sweep +# without CRAFT_HOSTILE_DIVISOR, and every proptest at its own case count (no PROPTEST_CASES). The +# rest of the workspace's tests run with them, on Linux, with the gate's setup. +on: + schedule: + - cron: "37 2 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: nightly-${{ github.ref }} + cancel-in-progress: false + +jobs: + full: + name: Full tests + uses: storytold/craft-common-actions/.github/workflows/gate.yml@main + with: + os: '["ubuntu-latest"]' + timeout-minutes: 120 + tools: cargo-nextest@0.9.150 + packages: mesa-vulkan-drivers libvulkan1 + craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 + linux-env: WGPU_BACKEND=vulkan + env: CRAFT_PRINT_REQUIRE_QUEUE=0 + setup-command: bash scripts/ci-test-inputs.sh + command: cargo nextest run --workspace --all-features --locked --profile ci diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index 09ddfabca..96d6f3faa 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -11,6 +11,10 @@ on: permissions: contents: read +# A fraction of the proptest cases, as in the Workspace gate; nightly.yml runs them in full. +env: + PROPTEST_CASES: "64" + concurrency: # Pull requests share one group per branch, so a newer push cancels the older run. Every other # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml index fa667bdfc..97e7c0d34 100644 --- a/.github/workflows/video.yml +++ b/.github/workflows/video.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: group: shared-video-${{ github.ref }} cancel-in-progress: true diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 96cc9333e..e3295d251 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -31,22 +31,14 @@ jobs: craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 linux-env: WGPU_BACKEND=vulkan windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1 - env: CRAFT_PRINT_REQUIRE_QUEUE=0 - setup-command: | - set -euo pipefail - corpus_fetcher=.test-inputs/photocraft - mkdir -p "$corpus_fetcher" - git -C "$corpus_fetcher" init - git -C "$corpus_fetcher" remote add origin https://github.com/storytold/PhotoCraft.git - git -C "$corpus_fetcher" fetch --quiet --depth=1 origin 74330157cb601573ae4523a95bb9132822fc3918 - git -C "$corpus_fetcher" checkout --quiet --detach FETCH_HEAD - (cd "$corpus_fetcher" && cargo xtask corpus --psd --psd-tools --atn --exr --heif --pngsuite) - mkdir -p corpus - cp -a "$corpus_fetcher/corpus/." corpus/ - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$corpus_fetcher/corpus" >> "$GITHUB_ENV" - printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" + # The fuzz-style tests run a fraction of their cases here: every hostile-input hammer and + # sweep 1/8 (craft-testkit's CRAFT_HOSTILE_DIVISOR), every proptest without its own case + # count 64 cases instead of 256. nightly.yml runs them all in full. + env: | + CRAFT_PRINT_REQUIRE_QUEUE=0 + CRAFT_HOSTILE_DIVISOR=8 + PROPTEST_CASES=64 + setup-command: bash scripts/ci-test-inputs.sh command: | python3 scripts/test-workspace-concurrency.py python3 scripts/test-workspace-tests.py diff --git a/crates/image-codecs/tests/it/malformed.rs b/crates/image-codecs/tests/it/malformed.rs index ec06109e0..b247bdfc6 100644 --- a/crates/image-codecs/tests/it/malformed.rs +++ b/crates/image-codecs/tests/it/malformed.rs @@ -76,9 +76,11 @@ fn truncated_files_mostly_error() { #[test] fn bit_flips_never_panic() { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) runs 1/N of the flips. + let rounds = 150usize.div_ceil(craft_media_testkit::hostile::divisor()); let mut rng = common::Rng::new(42); for (f, bytes) in samples() { - for _ in 0..150 { + for _ in 0..rounds { let mut b = bytes.clone(); let flips = 1 + (rng.next_u64() % 4) as usize; for _ in 0..flips { @@ -92,8 +94,11 @@ fn bit_flips_never_panic() { #[test] fn byte_overwrites_in_header_never_panic() { - for (f, bytes) in samples() { - for i in 0..bytes.len().min(64) { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) overwrites every N-th byte, from a different offset + // for each sample, so the samples together still reach every header position. + let step = craft_media_testkit::hostile::divisor(); + for (k, (f, bytes)) in samples().into_iter().enumerate() { + for i in (0..bytes.len().min(64)).filter(|i| (i + k) % step == 0) { for v in [0x00, 0x7F, 0xFF] { let mut b = bytes.clone(); b[i] = v; diff --git a/crates/image-codecs/tests/it/tiff_pages.rs b/crates/image-codecs/tests/it/tiff_pages.rs index 7501be936..7f6708f88 100644 --- a/crates/image-codecs/tests/it/tiff_pages.rs +++ b/crates/image-codecs/tests/it/tiff_pages.rs @@ -820,15 +820,18 @@ fn poke(bytes: &[u8]) { #[test] fn zoo_decodes_and_never_panics_when_cut_or_corrupted() { - for f in zoo() { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) runs every N-th cut and flip, from a different offset + // for each file, and 1/N of the random rounds. + let step = craft_media_testkit::hostile::divisor(); + for (k, f) in zoo().into_iter().enumerate() { let info = tiff_info(&f).unwrap(); for i in 0..info.pages.len() { decode_tiff_page(&f, i, &DecodeOptions::default()).unwrap(); } - for cut in 0..f.len() { + for cut in (0..f.len()).filter(|cut| (cut + k) % step == 0) { poke(&f[..cut]); } - for i in 0..f.len() { + for i in (0..f.len()).filter(|i| (i + k) % step == 0) { for flip in [0xffu8, 0x80, 0x01] { let mut g = f.clone(); g[i] ^= flip; @@ -836,7 +839,7 @@ fn zoo_decodes_and_never_panics_when_cut_or_corrupted() { } } let mut r = Rng::new(f.len() as u64); - for _ in 0..300 { + for _ in 0..300usize.div_ceil(step) { let mut g = f.clone(); for _ in 0..4 { let i = (r.next_u64() as usize) % g.len(); diff --git a/crates/media-testkit/src/hostile.rs b/crates/media-testkit/src/hostile.rs index f40021986..ddfc55f79 100644 --- a/crates/media-testkit/src/hostile.rs +++ b/crates/media-testkit/src/hostile.rs @@ -3,9 +3,9 @@ //! thread with a time limit for each case. [`Rng`], [`mutations`] and the other names here are //! `craft_testkit`'s. +pub use craft_testkit::hostile::{DIVISOR_VARIABLE, MAX_CASES, Mutation, Mutations, Rng, mutations}; #[cfg(not(target_arch = "wasm32"))] -pub use craft_testkit::hostile::{HammerConfig, HammerError}; -pub use craft_testkit::hostile::{MAX_CASES, Mutation, Mutations, Rng, mutations}; +pub use craft_testkit::hostile::{HammerConfig, HammerError, divisor}; /// The variable that multiplies [`hammer`]'s iterations. #[cfg(not(target_arch = "wasm32"))] @@ -17,8 +17,10 @@ const MULTIPLIER_VARIABLE: &str = "CRAFT_MEDIA_HOSTILE_MULT"; /// Panics on the first case that panics or does not finish, naming `name`, the case, its length and /// the panic's message. /// -/// `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations (soak runs). A value that is not a -/// whole number above zero panics, naming the variable, before `run` is called. +/// `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations (soak runs), and +/// `CRAFT_HOSTILE_DIVISOR=8` every eighth truncation and an eighth of the iterations (pull +/// requests). A value that is not a whole number above zero panics, naming the variable, before +/// `run` is called. #[cfg(not(target_arch = "wasm32"))] #[track_caller] pub fn hammer(name: &str, seed: &[u8], iters: usize, run: impl Fn(&[u8]) + Send + Sync + 'static) { diff --git a/crates/media-testkit/src/lib.rs b/crates/media-testkit/src/lib.rs index 3fa99c54f..db4c844f9 100644 --- a/crates/media-testkit/src/lib.rs +++ b/crates/media-testkit/src/lib.rs @@ -13,7 +13,8 @@ //! //! [`hostile::hammer`] runs a parser over every truncation and mutations of a valid input and fails //! on a panic or a case that does not finish in time; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times -//! the iterations. It and [`with_deadline`] call `craft_testkit`. +//! the iterations and `CRAFT_HOSTILE_DIVISOR=8` an eighth of them. It and [`with_deadline`] call +//! `craft_testkit`. //! [`vmd`] writes Sierra VMD fixtures, which ffmpeg can read but not write. //! //! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable diff --git a/crates/media-testkit/tests/hostile.rs b/crates/media-testkit/tests/hostile.rs index 8e34cd5af..5281f4a41 100644 --- a/crates/media-testkit/tests/hostile.rs +++ b/crates/media-testkit/tests/hostile.rs @@ -5,7 +5,7 @@ use std::process::Command; use std::sync::{Arc, Mutex}; use std::time::Duration; -use craft_media_testkit::hostile::hammer; +use craft_media_testkit::hostile::{divisor, hammer}; /// Set only in the child processes of `run_child`: the value names what `child_hammer` does. const CHILD_VARIABLE: &str = "CRAFT_MEDIA_TESTKIT_HOSTILE_CHILD"; @@ -60,10 +60,11 @@ fn a_bad_multiplier_names_the_variable() { #[test] fn a_panic_keeps_its_message() { - let payload = std::panic::catch_unwind(|| hammer("demo", &[9, 8, 7, 6], 0, |d| assert!(d.len() != 2, "boom at {}", d.len()))).unwrap_err(); + // Truncation to 0 runs under any CRAFT_HOSTILE_DIVISOR. + let payload = std::panic::catch_unwind(|| hammer("demo", &[9, 8, 7, 6], 0, |d| assert!(!d.is_empty(), "boom at {}", d.len()))).unwrap_err(); let message = payload.downcast_ref::().cloned().unwrap_or_default(); - assert!(message.starts_with("demo: truncation to 2 (len 2): the parser panicked: "), "{message}"); - assert!(message.contains("boom at 2"), "{message}"); + assert!(message.starts_with("demo: truncation to 0 (len 0): the parser panicked: "), "{message}"); + assert!(message.contains("boom at 0"), "{message}"); } #[test] @@ -74,8 +75,8 @@ fn every_truncation_of_a_large_seed_runs() { hammer("large", &seed, 0, move |d| { record.lock().unwrap().insert(d.len()); }); - // The seed and its 8,192 truncations. - assert_eq!(lengths.lock().unwrap().len(), 8_193); + // The seed and its 8,192 truncations, every N-th of them under CRAFT_HOSTILE_DIVISOR=N. + assert_eq!(lengths.lock().unwrap().len(), 1 + 8_192usize.div_ceil(divisor())); } #[test] diff --git a/crates/testkit/README.md b/crates/testkit/README.md index 8b8e9b208..1f58a7af9 100644 --- a/crates/testkit/README.md +++ b/crates/testkit/README.md @@ -192,6 +192,16 @@ A product of the iterations and the multiplier that does not fit in a `usize`, a more than `MAX_CASES` (10,000,000) cases in all, and a limit variable that `deadline` would reject also fail the test before `parse` is called. +### Quick runs + +`CRAFT_HOSTILE_DIVISOR=N` runs a fraction of every sweep: the unmodified seed, every N-th truncation +(lengths 0, N, 2N, ...) and the rounds divided by N, rounded up. It takes the same values as the +multiplier. The Workspace gate sets it on every run and the nightly run leaves it unset, so every +case still runs once a day. A sweep written without `hammer` reads it with `hostile::divisor()` and +runs the cases whose index plus an offset is a multiple of it, with a different offset for each input +so that the inputs together still reach every index. A failing case is found again with the same +value. + Changes from `craft-media-testkit`'s `hammer`: - A case that does not finish fails the test after its limit with the case's label. Before, a case diff --git a/crates/testkit/src/hostile.rs b/crates/testkit/src/hostile.rs index 4480d6aaf..2b34819e6 100644 --- a/crates/testkit/src/hostile.rs +++ b/crates/testkit/src/hostile.rs @@ -11,7 +11,10 @@ //! mutations, one case after another on a worker thread, with a time limit for each case. It fails //! the test, naming the case and the input length, when the parser panics or does not finish in //! time. The number of rounds is a count the caller gives, multiplied by a variable the caller -//! names. [`hammer`] and [`HammerConfig`] are not built for `wasm32`. +//! names. [`DIVISOR_VARIABLE`] (`CRAFT_HOSTILE_DIVISOR`) runs a fraction of every sweep for quick +//! runs such as pull requests: every N-th truncation and 1/N of the rounds; [`divisor`] reads it +//! for sweeps written without [`hammer`]. [`hammer`], [`HammerConfig`] and [`divisor`] are not +//! built for `wasm32`. use std::fmt::Write as _; @@ -40,6 +43,12 @@ const WORKER_NAME: &str = "craft-testkit hostile"; /// [`HammerConfig::with_multiplier_variable`] names another. pub const DEFAULT_MULTIPLIER_VARIABLE: &str = "CRAFT_HOSTILE_MULT"; +/// The variable that divides every hostile-input sweep: with `N`, [`hammer`] runs the unmodified +/// seed, every N-th truncation (lengths 0, N, 2N, ...) and 1/N of its rounds, rounded up. Unset, or +/// 1, runs everything. The Workspace gate sets it and the nightly full run leaves it unset; a +/// failing case is found again with the same value. +pub const DIVISOR_VARIABLE: &str = "CRAFT_HOSTILE_DIVISOR"; + /// The default limit for one case of [`hammer`]. The limit's variable, `CRAFT_TEST_TIMEOUT_SECS` /// unless [`HammerConfig::with_timeout`] names another, replaces it. #[cfg(not(target_arch = "wasm32"))] @@ -339,6 +348,36 @@ fn parse_multiplier(value: &str) -> Result { } } +/// The value of [`DIVISOR_VARIABLE`], or 1 when it is not set, for a sweep written without +/// [`hammer`]: run the cases whose index plus an offset is a multiple of it, and give each input of +/// the sweep a different offset so that together they still reach every index. Panics, naming the +/// variable, when the value is not a whole number above zero. +/// +/// ``` +/// let step = craft_testkit::hostile::divisor(); +/// let positions: Vec = (0..64).filter(|i| (i + 3) % step == 0).collect(); +/// assert!(!positions.is_empty()); +/// ``` +// Failing the calling test is what this function is for. +#[cfg(not(target_arch = "wasm32"))] +#[allow(clippy::panic)] +#[track_caller] +pub fn divisor() -> usize { + match divisor_with(read_variable) { + Ok(divisor) => divisor, + Err(error) => panic!("{error}"), + } +} + +/// [`divisor`] with the variable lookup passed in. +#[cfg(not(target_arch = "wasm32"))] +fn divisor_with(lookup: impl FnOnce(&str) -> Option) -> Result { + let Some(raw) = lookup(DIVISOR_VARIABLE) else { return Ok(1) }; + let variable = DIVISOR_VARIABLE.to_owned(); + let value = raw.into_string().map_err(|_| HammerError::NotUnicode { variable: variable.clone() })?; + parse_multiplier(&value).map_err(|reason| HammerError::BadValue { variable, value, reason }) +} + /// Reads the variable `name` from the process environment. #[cfg(not(target_arch = "wasm32"))] fn read_variable(name: &str) -> Option { @@ -388,15 +427,16 @@ where { let label = config.label; let rounds = config.rounds_with(&lookup).map_err(|error| format!("{label}: {error}"))?; - let rounds = if seed.is_empty() { 0 } else { rounds }; - let cases = 1 + seed.len() as u128 + rounds as u128; + let divisor = divisor_with(&lookup).map_err(|error| format!("{label}: {error}"))?; + let rounds = if seed.is_empty() { 0 } else { rounds.div_ceil(divisor) }; + let cases = 1 + seed.len().div_ceil(divisor) as u128 + rounds as u128; if cases > MAX_CASES as u128 { return Err(format!("{label}: {}", HammerError::TooManyCases { cases })); } let start = Instant::now(); let limit = resolve(&config.timeout, &lookup, start).map(Limit::from).map_err(|error| format!("{label}: {error}"))?; let clock: Clock = Arc::new(move || start.elapsed()); - run_cases(label.to_owned(), limit, Arc::from(seed), rounds, parse, clock) + run_cases(label.to_owned(), limit, Arc::from(seed), rounds, divisor, parse, clock) } /// A clock that returns the time since a [`hammer`] call started. @@ -467,7 +507,7 @@ impl Drop for Report { /// Starts the worker that runs every case, then waits for it, failing when a case runs past the /// limit. #[cfg(not(target_arch = "wasm32"))] -fn run_cases(label: String, limit: Limit, seed: Arc<[u8]>, rounds: usize, parse: F, clock: Clock) -> Result<(), String> +fn run_cases(label: String, limit: Limit, seed: Arc<[u8]>, rounds: usize, divisor: usize, parse: F, clock: Clock) -> Result<(), String> where F: Fn(&[u8]) + Send + Sync + 'static, { @@ -480,7 +520,7 @@ where .name(WORKER_NAME.to_owned()) .spawn(move || { let mut report = Report { watch: worker_watch, outcome: Err(format!("{worker_label}: the worker thread stopped without a result")) }; - report.outcome = run_all(&report.watch, &worker_clock, &worker_label, &worker_limit, &seed, rounds, &parse); + report.outcome = run_all(&report.watch, &worker_clock, &worker_label, &worker_limit, &seed, rounds, divisor, &parse); }) .map_err(|error| format!("{label}: could not start the worker thread: {error}"))?; let mut state = watch.lock(); @@ -498,11 +538,21 @@ where } } -/// Runs the unmodified seed, its truncations and its mutations in order, stopping at the first -/// failure. +/// Runs the unmodified seed, every `divisor`-th truncation and its mutations in order, stopping at +/// the first failure. #[cfg(not(target_arch = "wasm32"))] -fn run_all(watch: &Watch, clock: &Clock, label: &str, limit: &Limit, seed: &[u8], rounds: usize, parse: &F) -> Result<(), String> { - for n in std::iter::once(seed.len()).chain(0..seed.len()) { +#[allow(clippy::too_many_arguments)] +fn run_all( + watch: &Watch, + clock: &Clock, + label: &str, + limit: &Limit, + seed: &[u8], + rounds: usize, + divisor: usize, + parse: &F, +) -> Result<(), String> { + for n in std::iter::once(seed.len()).chain((0..seed.len()).step_by(divisor)) { let case = if n == seed.len() { "the unmodified seed".to_owned() } else { format!("truncation to {n}") }; run_one(watch, clock, label, limit, case, seed.get(..n).unwrap_or_default(), parse)?; } @@ -675,7 +725,7 @@ mod tests { Duration::ZERO }); let limit = Limit { limit: Duration::from_secs(5), text: "5s".to_owned() }; - assert_eq!(run_cases("late start".to_owned(), limit, Arc::from(&[1u8][..]), 0, |_: &[u8]| {}, clock), Ok(())); + assert_eq!(run_cases("late start".to_owned(), limit, Arc::from(&[1u8][..]), 0, 1, |_: &[u8]| {}, clock), Ok(())); } #[test] @@ -742,6 +792,29 @@ mod tests { assert_eq!(config.rounds_with(unset), Ok(7)); } + #[test] + fn divisor_runs_every_nth_truncation_and_a_fraction_of_the_rounds() { + let lookup = |name: &str| (name == DIVISOR_VARIABLE).then(|| OsString::from("4")); + let seen = Arc::new(Mutex::new(Vec::new())); + let record = Arc::clone(&seen); + hammer_with(&config("divided", 10), &[0; 10], move |d| record.lock().unwrap().push(d.len()), lookup).unwrap(); + let lengths = seen.lock().unwrap().clone(); + // The seed, truncations to 0, 4 and 8, then 10 / 4 = 3 rounds rounded up. + assert_eq!(lengths.len(), 7, "{lengths:?}"); + assert_eq!(lengths[..4], [10, 0, 4, 8]); + assert_eq!(divisor_with(unset), Ok(1)); + } + + #[test] + fn invalid_divisor_fails_before_any_parse() { + let called = Arc::new(Mutex::new(false)); + let flag = Arc::clone(&called); + let lookup = |name: &str| (name == DIVISOR_VARIABLE).then(|| OsString::from("0")); + let message = hammer_with(&config("bad divisor", 3), &[1, 2], move |_| *flag.lock().unwrap() = true, lookup).unwrap_err(); + assert_eq!(message, r#"bad divisor: CRAFT_HOSTILE_DIVISOR="0" is zero; set it to a whole number above zero"#); + assert!(!*called.lock().unwrap()); + } + #[test] fn invalid_multiplier_names_variable() { for (value, reason) in [ diff --git a/scripts/ci-test-inputs.sh b/scripts/ci-test-inputs.sh new file mode 100755 index 000000000..32af3ea77 --- /dev/null +++ b/scripts/ci-test-inputs.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# The test inputs the Workspace gate and the nightly full run fetch before their tests: the +# PhotoCraft test corpora (PSD, PSD tools, ATN, EXR, HEIF, PngSuite) at a pinned PhotoCraft commit, +# and the licensed PDF test fonts. Exports CRAFT_PSD_CORPUS and CRAFT_PDF_TEST_FONT_DIR through +# $GITHUB_ENV. Run from the repository root. +# +# A corpus already in .test-inputs/photocraft/corpus (restored from the CI cache, which is keyed on +# this file) is used as it is, without the PhotoCraft checkout and its xtask build. +set -euo pipefail + +# The PhotoCraft commit whose `cargo xtask corpus` pins the corpora. Changing it changes this file, +# which starts a new corpus cache entry. +photocraft=74330157cb601573ae4523a95bb9132822fc3918 +fetcher=.test-inputs/photocraft + +if [ -z "$(ls -A "$fetcher/corpus" 2>/dev/null)" ]; then + rm -rf "$fetcher" + mkdir -p "$fetcher" + git -C "$fetcher" init --quiet + git -C "$fetcher" remote add origin https://github.com/storytold/PhotoCraft.git + git -C "$fetcher" fetch --quiet --depth=1 origin "$photocraft" + git -C "$fetcher" checkout --quiet --detach FETCH_HEAD + (cd "$fetcher" && cargo xtask corpus --psd --psd-tools --atn --exr --heif --pngsuite) +fi +mkdir -p corpus +cp -a "$fetcher/corpus/." corpus/ + +python scripts/test-fetch-pdf-test-fonts.py +python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" + +printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$fetcher/corpus" >> "$GITHUB_ENV" +printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" From 6af133786067ad5be087366963aa70af2b486447 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:00:41 +0000 Subject: [PATCH 66/97] ci: nextest on every leg, tests with all features once Every Workspace leg runs nextest with --all-features and the doctests with cargo test --doc. The default-feature test run is gone: it added exactly four tests, all in craft-image-codecs and craft-text (feature-off behaviour), so those two crates run their tests with default features as well. The default-feature compile stays covered by the first clippy run. The resource groups from craft-libs#2058's audit move into the ci profile with platform = 'cfg(unix)', so Linux and macOS share one profile and Windows keeps the groups it already passes with. No separate example build: nextest builds examples as cargo test does, and clippy --all-targets checks them. scripts/test-workspace-tests.py follows the single command set. --- .config/nextest.toml | 26 ++++++++-------- .github/workflows/workspace.yml | 26 ++++++---------- scripts/test-workspace-tests.py | 54 +++++++++++++-------------------- 3 files changed, 44 insertions(+), 62 deletions(-) diff --git a/.config/nextest.toml b/.config/nextest.toml index 5e02e048d..0bc679e47 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -1,6 +1,6 @@ # cargo-nextest (https://nexte.st) runs every test in its own process, in parallel across test -# binaries. Linux and Windows in the Workspace gate use it (.github/workflows/workspace.yml). -# macOS and local runs keep `cargo test`. Both nextest legs also run `cargo test --doc`. +# binaries. Every leg of the Workspace gate uses it (.github/workflows/workspace.yml); local runs may +# keep `cargo test`. Nextest does not run doctests, so the gate also runs `cargo test --doc`. # # cargo nextest run --workspace --profile ci # cargo test --workspace --doc @@ -21,8 +21,9 @@ video-fixtures = { max-threads = 1 } # craft-print: `PRINT_TICKET_PROVIDER` serializes the Windows PrintTicket provider, and the tests # share the one test print queue the gate installs. print = { max-threads = 1 } -# The Linux pilot serializes video integration tests sharing generated fixture directories. -linux-video-fixtures = { max-threads = 1 } +# craft-video integration tests on Linux and macOS: the binaries generate and read the same fixture +# directories (see the `ci` overrides below). +video-integration = { max-threads = 1 } [[profile.default.overrides]] filter = 'package(craft-ui) & (binary(visual_regression) | test(/^combo::tests::|selected_tab_erases_a_baseline_centered_on_its_bottom_edge/))' @@ -44,16 +45,17 @@ fail-fast = false slow-timeout = { period = "60s" } failure-output = "immediate-final" -# Linux-only pilot: keep the established Windows profile unchanged. GPU consumers share one -# process-independent slot; the video integration binaries share fixture directories. This -# deliberately starts conservatively rather than relying on in-process mutexes across binaries. -[profile.ci-linux] -inherits = "ci" -[[profile.ci-linux.overrides]] +# Linux and macOS (the resource audit in craft-libs#2058): every GPU consumer shares the one `gpu` +# slot, and the craft-video integration binaries share their fixture directories. Conservative on +# purpose: the in-process mutexes these tests rely on do not reach across nextest's processes. +# Windows keeps the default groups above, which its leg has passed with since it moved to nextest. +[[profile.ci.overrides]] +platform = 'cfg(unix)' filter = 'package(craft-ui) | package(craft-keymap) | package(craft-update)' test-group = 'gpu' -[[profile.ci-linux.overrides]] +[[profile.ci.overrides]] +platform = 'cfg(unix)' filter = 'package(craft-video) & kind(test)' -test-group = 'linux-video-fixtures' +test-group = 'video-integration' diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index e3295d251..554e645ae 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -25,7 +25,7 @@ jobs: with: os: '["ubuntu-latest","windows-latest","macos-latest"]' timeout-minutes: 120 - # Linux and Windows use nextest with explicit doctests (.config/nextest.toml). + # Every leg runs its tests with nextest, and its doctests with cargo test (.config/nextest.toml). tools: cargo-nextest@0.9.150 packages: mesa-vulkan-drivers libvulkan1 craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 @@ -45,29 +45,21 @@ jobs: cargo fmt --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo clippy --workspace --all-targets --all-features --locked -- -D warnings - if [ "$RUNNER_OS" = Linux ]; then - # Keep example compilation as well as test=true example tests selected by nextest. - cargo build --workspace --examples --locked - cargo nextest run --workspace --locked --profile ci-linux - cargo test --workspace --doc --locked - cargo build --workspace --examples --all-features --locked - cargo nextest run --workspace --all-features --locked --profile ci-linux - cargo test --workspace --doc --all-features --locked - else - cargo test --workspace --locked - cargo test --workspace --all-features --locked - fi + # The tests run once, with every feature, in parallel across test binaries; nextest skips + # doctests, so `cargo test --doc` runs them. The default-feature compile is the first + # clippy run's; the second command runs the crates whose tests check behaviour with a + # feature off, which an all-features build cannot reach. + cargo nextest run --workspace --all-features --locked --profile ci + cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci windows-command: | powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' cargo fmt --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo clippy --workspace --all-targets --all-features --locked -- -D warnings - # The same tests as `cargo test`, run in parallel across test binaries instead of one - # binary at a time; nextest skips doctests, so `cargo test --doc` runs them. - cargo nextest run --workspace --locked --profile ci - cargo test --workspace --doc --locked cargo nextest run --workspace --all-features --locked --profile ci cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci msrv: name: Rust 1.95 diff --git a/scripts/test-workspace-tests.py b/scripts/test-workspace-tests.py index f6e55f968..4da52d701 100644 --- a/scripts/test-workspace-tests.py +++ b/scripts/test-workspace-tests.py @@ -40,65 +40,53 @@ COMMON = [ "clippy --workspace --all-targets --locked -- -D warnings", "clippy --workspace --all-targets --all-features --locked -- -D warnings", ] -LINUX = [ - "build --workspace --examples --locked", - "nextest run --workspace --locked --profile ci-linux", - "test --workspace --doc --locked", - "build --workspace --examples --all-features --locked", - "nextest run --workspace --all-features --locked --profile ci-linux", +TESTS = [ + "nextest run --workspace --all-features --locked --profile ci", "test --workspace --doc --all-features --locked", + "nextest run -p craft-image-codecs -p craft-text --locked --profile ci", ] class WorkspaceTests(unittest.TestCase): - def test_linux_keeps_both_feature_sets_examples_and_doctests(self): - result = commands("Linux") - self.assertEqual(result.returncode, 0, result.stderr) - self.assertEqual(result.stdout.splitlines(), COMMON + LINUX) + def test_linux_and_macos_run_one_feature_set_with_doctests(self): + for os_name in ("Linux", "macOS"): + with self.subTest(os=os_name): + result = commands(os_name) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.splitlines(), COMMON + TESTS) - def test_macos_keeps_cargo_test(self): - result = commands("macOS") - self.assertEqual(result.returncode, 0, result.stderr) - self.assertEqual(result.stdout.splitlines(), COMMON + [ - "test --workspace --locked", "test --workspace --all-features --locked"]) - - def test_each_linux_stage_failure_remains_fatal(self): - for index, command in enumerate(COMMON + LINUX): + def test_each_stage_failure_remains_fatal(self): + for index, command in enumerate(COMMON + TESTS): with self.subTest(command=command): result = commands("Linux", command) self.assertEqual(result.returncode, 17, result.stderr) - self.assertEqual(result.stdout.splitlines(), (COMMON + LINUX)[:index + 1]) + self.assertEqual(result.stdout.splitlines(), (COMMON + TESTS)[:index + 1]) - def test_windows_keeps_its_existing_profile_and_doctests(self): + def test_windows_runs_the_same_cargo_commands(self): source = block(WORKFLOW.read_text(), "windows-command") cargo = [line.strip() for line in source.splitlines() if line.strip().startswith("cargo ")] - self.assertEqual(cargo, ["cargo " + command for command in COMMON + [ - "nextest run --workspace --locked --profile ci", - "test --workspace --doc --locked", - "nextest run --workspace --all-features --locked --profile ci", - "test --workspace --doc --all-features --locked", - ]]) + self.assertEqual(cargo, ["cargo " + command for command in COMMON + TESTS]) - def test_linux_inherits_no_retries_no_filtering_and_existing_failure_policy(self): + def test_ci_profile_keeps_its_failure_policy_without_retries_or_filtering(self): config = tomllib.loads((ROOT / ".config/nextest.toml").read_text()) - self.assertEqual(config["profile"]["ci-linux"]["inherits"], "ci") self.assertIs(config["profile"]["ci"]["fail-fast"], False) for profile in config["profile"].values(): self.assertNotIn("default-filter", profile) self.assertNotIn("retries", profile) self.assertEqual(config["profile"]["ci"]["slow-timeout"], {"period": "60s"}) - def test_linux_resource_groups_are_serial_and_do_not_change_windows(self): + def test_unix_resource_groups_are_serial_and_leave_windows_alone(self): config = tomllib.loads((ROOT / ".config/nextest.toml").read_text()) - overrides = config["profile"]["ci-linux"]["overrides"] + overrides = config["profile"]["ci"]["overrides"] self.assertEqual(overrides, [ - {"filter": "package(craft-ui) | package(craft-keymap) | package(craft-update)", + {"platform": "cfg(unix)", + "filter": "package(craft-ui) | package(craft-keymap) | package(craft-update)", "test-group": "gpu"}, - {"filter": "package(craft-video) & kind(test)", "test-group": "linux-video-fixtures"}, + {"platform": "cfg(unix)", "filter": "package(craft-video) & kind(test)", + "test-group": "video-integration"}, ]) for override in overrides: self.assertEqual(config["test-groups"][override["test-group"]]["max-threads"], 1) - self.assertNotIn("overrides", config["profile"]["ci"]) def test_workflow_stays_shared_and_keeps_platform_gates(self): source = WORKFLOW.read_text() From 7aa03b89cc92a355e56e2ad5d5a96a249eea3b90 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:00:47 +0000 Subject: [PATCH 67/97] ci: no debuginfo on the Windows leg CARGO_PROFILE_DEV_DEBUG=0 on Windows, as PhotoCraft's Windows legs do: writing PDBs for every test binary is a large part of the Windows build. The gate writes windows-env after its dev-debug default, so the Linux and macOS legs keep line-tables-only. --- .github/workflows/workspace.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 554e645ae..7faba8a04 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -30,7 +30,12 @@ jobs: packages: mesa-vulkan-drivers libvulkan1 craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 linux-env: WGPU_BACKEND=vulkan - windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1 + # No debuginfo on Windows: writing PDBs for every test binary is a large part of its link + # time. A panic still names its file and line; only backtrace frames lose theirs, and the + # Linux and macOS legs keep line tables. + windows-env: | + CRAFT_PRINT_REQUIRE_QUEUE=1 + CARGO_PROFILE_DEV_DEBUG=0 # The fuzz-style tests run a fraction of their cases here: every hostile-input hammer and # sweep 1/8 (craft-testkit's CRAFT_HOSTILE_DIVISOR), every proptest without its own case # count 64 cases instead of 256. nightly.yml runs them all in full. From 899d6e0302eb1cf022f8f8d5122b1945467a25a1 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:05:04 +0000 Subject: [PATCH 68/97] ci: per-crate workflows run only what the Workspace gate does not The Workspace gate already runs fmt, both clippy runs and the tests of every crate on Linux, Windows and macOS. The per-crate workflows drop those steps and keep their own checks: wasm32 builds and tests, no-default and single-feature clippy and tests, cross-target clippy, docs, release and sample tests, --ignored tests, ffmpeg oracle tests, the Language-data proofing builds, the PDF Unicode fixtures, read-only contract and vendored backends. All of them run on Linux. docpath.yml, print.yml, i18n.yml and ui.yml had no check of their own and are removed. They also stop caching dependencies: about 25 rust-cache entries no longer compete with the gate's for the repository's 10 GB, which the gate's main run missed on every OS. The data caches (Opus vectors, CRW samples) stay. --- .github/workflows/actions.lock | 28 --------- .github/workflows/ai-core.yml | 13 +---- .github/workflows/atomic.yml | 15 +---- .github/workflows/audio.yml | 38 +----------- .github/workflows/cms.yml | 4 +- .github/workflows/crw.yml | 37 +----------- .github/workflows/dialogs.yml | 3 +- .github/workflows/doc.yml | 15 +---- .github/workflows/docpath.yml | 41 ------------- .github/workflows/ecproj-format.yml | 13 +---- .github/workflows/font-store.yml | 16 +---- .github/workflows/formats.yml | 23 ++------ .github/workflows/i18n.yml | 41 ------------- .github/workflows/jpeg.yml | 11 +--- .github/workflows/keymap.yml | 49 ++-------------- .github/workflows/media.yml | 17 +----- .github/workflows/menu.yml | 11 +--- .github/workflows/pcraft-format.yml | 14 ++--- .github/workflows/pdf.yml | 57 ++---------------- .github/workflows/print.yml | 46 --------------- .github/workflows/proof.yml | 17 ++---- .github/workflows/ui.yml | 74 ------------------------ .github/workflows/update.yml | 16 ++--- .github/workflows/vectorcraft-format.yml | 14 ++--- .github/workflows/video.yml | 25 +++----- .github/workflows/web-api.yml | 6 +- .github/workflows/web-host.yml | 12 +--- .github/workflows/window.yml | 18 ++---- crates/print/README.md | 8 +-- 29 files changed, 85 insertions(+), 597 deletions(-) delete mode 100644 .github/workflows/docpath.yml delete mode 100644 .github/workflows/i18n.yml delete mode 100644 .github/workflows/print.yml delete mode 100644 .github/workflows/ui.yml diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 52c8faf77..46d7b8d3c 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -18,7 +18,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/cms.yml': - 'actions/checkout@v4.4.0' - 'dtolnay/rust-toolchain@stable' @@ -27,7 +26,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/dialogs.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -36,10 +34,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - '.github/workflows/docpath.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/ecproj-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -52,22 +46,15 @@ workflows: - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - 'step-security/harden-runner@v2.22.4' - - 'swatinem/rust-cache@v2.9.3' '.github/workflows/house-rules.yml': [] - '.github/workflows/i18n.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/jpeg.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/keymap.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/lockfile.yml': - 'actions/checkout@v7.0.1' - 'step-security/harden-runner@v2.22.4' @@ -75,11 +62,9 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/menu.yml': - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - - 'swatinem/rust-cache@v2.9.3' '.github/workflows/nightly.yml': [] '.github/workflows/pcraft-format.yml': - 'actions/checkout@v7.0.1' @@ -90,23 +75,12 @@ workflows: - 'actions/setup-python@v7.1.0' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' - '.github/workflows/print.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/proof.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/sonarcloud.yml': [] - '.github/workflows/ui.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/update.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -119,7 +93,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/web-api.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -129,7 +102,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' '.github/workflows/window.yml': - 'actions/checkout@v7.0.1' diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index 5471bf1ec..4de27650e 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -17,15 +17,12 @@ concurrency: group: ai-core-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ai-core: + name: AI model WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,10 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ai-core --all-targets --locked -- -D warnings - - run: cargo test -p craft-ai-core --locked # The model promises to compile for the web. - run: cargo check -p craft-ai-core --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index f72a64f1e..be11c8d89 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -17,15 +17,12 @@ concurrency: group: atomic-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this runs what it does not. jobs: atomic: + name: Atomic inherited Linux ACLs timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,15 +32,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - name: Install ACL tools - if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y acl - - run: cargo fmt --check - - run: cargo clippy -p craft-atomic -p craft-settings --all-targets --locked -- -D warnings - - run: cargo test -p craft-atomic -p craft-settings --locked -- --nocapture - name: Check inherited Linux ACLs - if: runner.os == 'Linux' run: cargo test -p craft-atomic --locked -- --ignored --nocapture wasm: diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index 48c1384b2..d4b2a5202 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -26,7 +26,8 @@ concurrency: jobs: lint: timeout-minutes: 15 - name: Audio lint, feature sets, docs, WASM + # fmt, clippy with all features and the minimum Rust version run in the Workspace gate. + name: Audio feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -39,13 +40,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-audio --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -54,7 +50,6 @@ jobs: cargo clippy -p craft-audio --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-audio --all-targets --locked --all-features -- -D warnings # missing_docs is a warning in the crate; -D warnings makes it (and broken links) fail here. - run: cargo doc -p craft-audio --all-features --no-deps --locked env: @@ -68,25 +63,6 @@ jobs: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-audio --all-features --locked --target wasm32-unknown-unknown - run: cargo check -p craft-audio --no-default-features --features lossless-encode --locked --target wasm32-unknown-unknown - msrv: - timeout-minutes: 10 - name: Audio on the minimum Rust version - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - # The workspace's rust-version. - - run: rustup toolchain install 1.95.0 --profile minimal - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-msrv - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo +1.95.0 check -p craft-audio -p craft-media --all-features --locked features: timeout-minutes: 10 name: Audio tests without symphonia and lossless-encode only @@ -102,10 +78,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-features - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo test -p craft-audio --no-default-features --features lossless-encode --locked - run: cargo test -p craft-audio --no-default-features --features pcm-encode --locked --lib - run: cargo test -p craft-audio --no-default-features --features flac-encode --locked --lib @@ -127,10 +99,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-test - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/cache@v6.1.0 with: path: ${{ runner.temp }}/media-fixtures/opus/vectors diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml index 74ce0815f..2040212c2 100644 --- a/.github/workflows/cms.yml +++ b/.github/workflows/cms.yml @@ -11,6 +11,7 @@ on: permissions: contents: read +# clippy and the debug tests run in the Workspace gate; this runs the release build of the tests. jobs: cms: timeout-minutes: 20 @@ -18,9 +19,6 @@ jobs: steps: - uses: actions/checkout@v4.4.0 - uses: dtolnay/rust-toolchain@stable - with: - components: clippy - - run: cargo clippy -p craft-cms --all-targets --all-features --locked -- -D warnings # Release: the FOGRA39 fit and ink-limit tests take about 35 s in debug and 4 s here. Tests that need # installed system profiles print "skipped:" when none are present. - run: cargo test -p craft-cms --all-features --release --locked -- --nocapture diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml index 54be7ba3b..f5bb91a38 100644 --- a/.github/workflows/crw.yml +++ b/.github/workflows/crw.yml @@ -18,35 +18,8 @@ concurrency: group: shared-crw-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: - native: - timeout-minutes: 20 - name: CRW lint and tests (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, windows-latest] - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-crw --check - - run: cargo clippy -p craft-crw --all-targets --locked -- -D warnings - - run: cargo test -p craft-crw --locked - wasm: timeout-minutes: 10 name: CRW WASM @@ -63,10 +36,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-crw --locked --target wasm32-unknown-unknown samples: @@ -84,10 +53,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-samples - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Cache the CC0 sample files uses: actions/cache@v6.1.0 with: diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml index c8d43d725..151a63e36 100644 --- a/.github/workflows/dialogs.yml +++ b/.github/workflows/dialogs.yml @@ -37,6 +37,5 @@ jobs: components: clippy # The macOS code is linted on Linux: it compiles for the target without the SDK. targets: aarch64-apple-darwin - - run: cargo clippy -p craft-dialogs --all-targets --locked -- -D warnings + # Native clippy and the tests run in the Workspace gate. - run: cargo clippy -p craft-dialogs --target aarch64-apple-darwin --locked -- -D warnings - - run: cargo test -p craft-dialogs --locked diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 6caa4f0ee..394cdbdbe 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -17,15 +17,12 @@ concurrency: group: doc-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: doc: + name: Craft documents WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,11 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-doc --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-doc --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-doc --locked -- --nocapture - - run: cargo test -p craft-doc --all-features --locked -- --nocapture - run: cargo check -p craft-doc --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/docpath.yml b/.github/workflows/docpath.yml deleted file mode 100644 index e0115f6f5..000000000 --- a/.github/workflows/docpath.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Document paths - -on: - workflow_dispatch: - push: - branches: [main] - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - pull_request: - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: docpath-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - docpath: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-docpath --all-targets --locked -- -D warnings - - run: cargo test -p craft-docpath --locked -- --nocapture diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml index 24a3350af..eeacf5801 100644 --- a/.github/workflows/ecproj-format.yml +++ b/.github/workflows/ecproj-format.yml @@ -17,15 +17,12 @@ concurrency: group: ecproj-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ecproj-format: + name: EffectCraft project format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,9 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ecproj-format --all-targets --locked -- -D warnings - - run: cargo test -p craft-ecproj-format --locked -- --nocapture - run: cargo check -p craft-ecproj-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml index 0578f18ec..34c7c09a1 100644 --- a/.github/workflows/font-store.yml +++ b/.github/workflows/font-store.yml @@ -17,15 +17,12 @@ concurrency: group: font-store-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: font-store: + name: Font store WASM timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,13 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-font-store --all-targets --locked -- -D warnings - - run: cargo test -p craft-font-store --locked - - run: cargo clippy -p craft-font-catalog --all-targets --locked -- -D warnings - - run: cargo test -p craft-font-catalog --locked - name: Check the web build - if: runner.os == 'Linux' run: cargo check -p craft-font-store --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml index 84d2c0d7e..769271d84 100644 --- a/.github/workflows/formats.yml +++ b/.github/workflows/formats.yml @@ -68,7 +68,9 @@ jobs: - { crate: craft-tiff, features: "" } - { crate: craft-heif, features: "testdata" } - { crate: craft-cms, features: "" } - name: ${{ matrix.crate }} lint, tests, WASM + # fmt, clippy with default and with all features, and the tests run in the Workspace gate on + # every OS; this lints each feature alone and checks the web build. + name: ${{ matrix.crate }} feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -80,32 +82,19 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: ${{ matrix.crate }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p "$CRATE" --check - env: - CRATE: ${{ matrix.crate }} - - name: Clippy, default features and each feature alone + - name: Clippy, each feature alone + if: matrix.features != '' env: CRATE: ${{ matrix.crate }} FEATURES: ${{ matrix.features }} run: | - cargo clippy -p "$CRATE" --all-targets --locked -- -D warnings for f in $FEATURES; do echo "::group::feature: $f" cargo clippy -p "$CRATE" --all-targets --locked --no-default-features --features "$f" -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p "$CRATE" --all-targets --locked --all-features -- -D warnings - env: - CRATE: ${{ matrix.crate }} - - run: cargo test -p "$CRATE" --all-features --locked - env: - CRATE: ${{ matrix.crate }} - run: cargo check -p "$CRATE" --all-features --locked --target wasm32-unknown-unknown env: CRATE: ${{ matrix.crate }} diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml deleted file mode 100644 index 7e6903188..000000000 --- a/.github/workflows/i18n.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Translations - -on: - workflow_dispatch: - push: - branches: [main] - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - pull_request: - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: i18n-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - i18n: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-i18n --all-targets --features collate --locked -- -D warnings - - run: cargo test -p craft-i18n --features collate --locked -- --nocapture diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index 21db0ab79..325cc0c02 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -21,7 +21,8 @@ concurrency: jobs: check: timeout-minutes: 10 - name: JPEG lint, tests, WASM + # fmt, clippy and the tests run in the Workspace gate on every OS. + name: JPEG WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,13 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-jpeg - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-jpeg --check - - run: cargo clippy -p craft-jpeg --all-targets --locked -- -D warnings - - run: cargo test -p craft-jpeg --locked - run: cargo check -p craft-jpeg --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml index 41fcc0502..f85f84935 100644 --- a/.github/workflows/keymap.yml +++ b/.github/workflows/keymap.yml @@ -21,7 +21,9 @@ concurrency: jobs: linux: timeout-minutes: 15 - name: Keymap (Linux) + # fmt, and clippy and the tests with default and with all features, run in the Workspace gate + # on every OS; this runs the feature subsets. + name: Keymap feature sets runs-on: ubuntu-latest env: CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts @@ -43,12 +45,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-linux - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-keymap --check + components: clippy - run: cargo clippy -p craft-keymap --all-targets --no-default-features --locked -- -D warnings # `snapshot` covers `ui` and `egui` and compiles the dialog screenshots, which need a GPU # to run, so the test steps leave them out. @@ -58,40 +55,6 @@ jobs: run: cargo test -p craft-keymap --no-default-features --lib --tests --locked - name: Test egui dispatch and the shortcuts dialog run: cargo test -p craft-keymap --features ui --locked - native: - timeout-minutes: 15 - name: Keymap (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["macos-latest","windows-latest"]') || fromJSON('["windows-latest"]') }} - runs-on: ${{ matrix.os }} - env: - CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - name: Checkout test fonts - uses: actions/checkout@v7.0.1 - with: - repository: storytold/craft-fonts - ref: b076417b5880bd4154bd22f00695b1d28c6bea83 - path: .test-inputs/craft-fonts - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo test -p craft-keymap --features ui --locked wasm: timeout-minutes: 10 name: Keymap WASM @@ -108,8 +71,4 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-keymap --features ui --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index f397f5cb3..0fbf78b12 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -26,7 +26,8 @@ concurrency: jobs: lint: timeout-minutes: 10 - name: Media lint, feature sets, WASM + # fmt, and clippy with default and with all features, run in the Workspace gate on every OS. + name: Media feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -39,20 +40,12 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-media --check - run: cargo clippy -p craft-media --all-targets --locked --no-default-features -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features bitstream -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features matroska -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features ogg -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked --all-features -- -D warnings - - run: cargo clippy -p craft-media-testkit --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features serde -- -D warnings - run: cargo check -p craft-media --all-features --locked --target wasm32-unknown-unknown test: @@ -70,10 +63,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-test - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Build tests while installing ffmpeg run: | # The man-db index rebuild after dpkg is slow on hosted runners. diff --git a/.github/workflows/menu.yml b/.github/workflows/menu.yml index 8d1058731..b12c8bcc6 100644 --- a/.github/workflows/menu.yml +++ b/.github/workflows/menu.yml @@ -18,7 +18,8 @@ concurrency: jobs: linux: timeout-minutes: 15 - name: Menu (Linux) + # fmt, native clippy and the tests run in the Workspace gate on every OS. + name: Menu macOS and WASM lint runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 @@ -26,14 +27,8 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: aarch64-apple-darwin, wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: craft-menu-linux - - run: cargo fmt -p craft-menu --check - - run: cargo clippy -p craft-menu --all-targets --locked -- -D warnings # The macOS backend type-checks from Linux; it needs no linker or SDK. - run: cargo clippy -p craft-menu --lib --locked --target aarch64-apple-darwin -- -D warnings - run: cargo clippy -p craft-menu --lib --locked --target wasm32-unknown-unknown -- -D warnings - - run: cargo test -p craft-menu --locked diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml index 9c66b5a10..0e82ba888 100644 --- a/.github/workflows/pcraft-format.yml +++ b/.github/workflows/pcraft-format.yml @@ -17,15 +17,13 @@ concurrency: group: pcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: pcraft-format: + name: PhotoCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,9 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-pcraft-format --all-targets --locked -- -D warnings - - run: cargo test -p craft-pcraft-format --locked -- --nocapture - run: cargo check -p craft-pcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index 96d6f3faa..3be70ad99 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -24,13 +24,11 @@ concurrency: jobs: native: - name: PDF (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + # fmt, clippy and the tests run in the Workspace gate on every OS, with the licensed fonts and + # the plate tests; this runs the tests behind craft_pdf_unicode_fixtures and the read-only + # contract, which is its own workspace. + name: PDF Unicode fixtures and read-only contract + runs-on: ubuntu-latest env: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures steps: @@ -42,11 +40,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -56,9 +49,7 @@ jobs: python scripts/test-fetch-pdf-test-fonts.py python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo fmt --check - - run: cargo clippy -p craft-pdf --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-pdf --all-features --locked + - run: cargo test -p craft-pdf --all-features --locked --test unicode_writing --test upstream_compatibility --test upstream_reading - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked backends: name: PDF vendored contracts @@ -72,10 +63,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-backends - save-if: ${{ github.ref == 'refs/heads/main' }} - run: bash scripts/test-pdf-backends.sh wasm: name: PDF WASM runtime @@ -93,10 +80,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -121,31 +104,3 @@ jobs: fallback: cargo-install - run: cargo test -p craft-pdf --all-features --locked --target wasm32-unknown-unknown - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked --target wasm32-unknown-unknown - plate-test: - name: Plate tests and craft-prepress - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-plate-test - save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7.1.0 - with: - python-version: "3.12" - - name: Provision licensed PDF test fonts - shell: bash - run: | - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo clippy -p craft-plate-test -p craft-prepress --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-plate-test -p craft-prepress --all-features --locked diff --git a/.github/workflows/print.yml b/.github/workflows/print.yml deleted file mode 100644 index 8e2108e09..000000000 --- a/.github/workflows/print.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Print spooler -on: - workflow_dispatch: - push: - branches: [main] - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] - pull_request: - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] -permissions: - contents: read -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: print-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} -jobs: - print: - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-print --all-targets -- -D warnings - - name: Prepare the Windows test driver - if: runner.os == 'Windows' - shell: powershell - run: | - Start-Service Spooler - Add-PrinterDriver -Name 'Generic / Text Only' - - run: cargo test -p craft-print --locked -- --nocapture - timeout-minutes: 10 - env: - CRAFT_PRINT_REQUIRE_QUEUE: ${{ runner.os == 'Windows' && '1' || '0' }} diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml index 10365a230..27bf5b32b 100644 --- a/.github/workflows/proof.yml +++ b/.github/workflows/proof.yml @@ -21,7 +21,8 @@ concurrency: jobs: check: timeout-minutes: 20 - name: Proofing lint, tests with and without Language data, WASM + # fmt, and clippy and the tests without Language data, run in the Workspace gate on every OS. + name: Proofing with Language data, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -43,18 +44,10 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-proof - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-proof --check - - name: Without Language data (a fork, docs.rs, offline) - run: | - cargo clippy -p craft-proof --all-targets --locked -- -D warnings - cargo test -p craft-proof --locked - cargo check -p craft-proof --locked --target wasm32-unknown-unknown + - name: The web build without Language data (a fork, docs.rs, offline) + run: cargo check -p craft-proof --locked --target wasm32-unknown-unknown - name: A release without Language data fails run: | if CRAFT_I18N_REQUIRED=1 cargo check -p craft-proof --locked 2>build.log; then diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml deleted file mode 100644 index f15ef6ddc..000000000 --- a/.github/workflows/ui.yml +++ /dev/null @@ -1,74 +0,0 @@ -name: Shared UI - -on: - push: - branches: [main] - paths: ["crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - pull_request: - paths: ["crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - workflow_dispatch: - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-ui-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - native: - timeout-minutes: 30 - name: UI (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - name: Install software Vulkan renderer - if: runner.os == 'Linux' - run: | - sudo apt-get update - sudo apt-get install -y mesa-vulkan-drivers libvulkan1 - echo 'WGPU_BACKEND=vulkan' >> "$GITHUB_ENV" - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt --check - - run: cargo clippy -p craft-ui --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-ui --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-ui --locked - - run: cargo test -p craft-ui --all-features --locked - wasm: - timeout-minutes: 15 - name: UI WASM - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo check -p craft-ui --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index 9a7139026..cfb14ec9a 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -17,15 +17,13 @@ concurrency: group: update-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests with default and with all features run in the Workspace gate on every +# OS; this runs the egui feature alone. jobs: update: + name: Update with egui alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,10 +37,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the egui feature both build and lint cleanly. - - run: cargo clippy -p craft-update --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-update --all-targets --locked --features egui -- -D warnings - - run: cargo test -p craft-update --locked -- --nocapture - run: cargo test -p craft-update --locked --features egui -- --nocapture diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml index 74144f30f..e6cfb7a70 100644 --- a/.github/workflows/vectorcraft-format.yml +++ b/.github/workflows/vectorcraft-format.yml @@ -17,15 +17,13 @@ concurrency: group: vectorcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: vectorcraft-format: + name: VectorCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,9 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-vectorcraft-format --all-targets --locked -- -D warnings - - run: cargo test -p craft-vectorcraft-format --locked -- --nocapture - run: cargo check -p craft-vectorcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml index 97e7c0d34..20afe0d70 100644 --- a/.github/workflows/video.yml +++ b/.github/workflows/video.yml @@ -23,7 +23,8 @@ concurrency: jobs: lint: timeout-minutes: 20 - name: Video lint, feature sets, docs, WASM + # fmt and clippy with all features run in the Workspace gate on every OS. + name: Video feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -36,12 +37,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-lint - - run: cargo fmt -p craft-video --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -50,19 +47,15 @@ jobs: cargo clippy -p craft-video --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-video --all-targets --locked --all-features -- -D warnings - run: cargo doc -p craft-video --all-features --no-deps --locked env: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-video --all-features --locked --target wasm32-unknown-unknown test: timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, windows-latest] - runs-on: ${{ matrix.os }} - name: Video tests (${{ matrix.os }}) + # The Workspace gate runs these tests on every OS without ffmpeg; this runs them with it. + runs-on: ubuntu-latest + name: Video tests with ffmpeg steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -74,11 +67,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-${{ matrix.os }} - - name: Install ffmpeg (Linux) - if: runner.os == 'Linux' + - name: Install ffmpeg run: | sudo rm -f /var/lib/man-db/auto-update sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml index 4bf1a30fe..1c9b2c92f 100644 --- a/.github/workflows/web-api.yml +++ b/.github/workflows/web-api.yml @@ -35,7 +35,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen @@ -50,8 +50,6 @@ jobs: with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install - - run: cargo fmt --check - - run: cargo clippy -p craft-web-api --all-targets --locked -- -D warnings + # fmt, native clippy and the native tests run in the Workspace gate. - run: cargo clippy -p craft-web-api --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - run: cargo test -p craft-web-api --locked - run: cargo test -p craft-web-api --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml index 76e6701e5..28129a542 100644 --- a/.github/workflows/web-host.yml +++ b/.github/workflows/web-host.yml @@ -21,7 +21,8 @@ concurrency: jobs: check: timeout-minutes: 20 - name: Web host lint, tests, WASM tests + # fmt, native clippy and the native tests run in the Workspace gate. + name: Web host WASM lint and tests runs-on: ubuntu-latest env: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner @@ -36,16 +37,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-web-host - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-web-host --check - - run: cargo clippy -p craft-web-host --all-targets --locked -- -D warnings - run: cargo clippy -p craft-web-host --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - run: cargo test -p craft-web-host --locked - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen shell: bash diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml index fdd28e203..bf5f39835 100644 --- a/.github/workflows/window.yml +++ b/.github/workflows/window.yml @@ -17,15 +17,13 @@ concurrency: group: window-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +# fmt, clippy and the tests with default and with all features (egui and restore together) run in +# the Workspace gate on every OS; this runs each feature alone. jobs: window: + name: Window with each feature alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,12 +37,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the egui feature both build and lint cleanly. - - run: cargo clippy -p craft-window --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-window --all-targets --locked --features egui -- -D warnings - - run: cargo test -p craft-window --locked -- --nocapture - run: cargo test -p craft-window --locked --features egui -- --nocapture - run: cargo clippy -p craft-window --all-targets --locked --features restore -- -D warnings - - run: cargo test -p craft-window --locked --features restore,egui -- --nocapture + - run: cargo test -p craft-window --locked --features restore -- --nocapture diff --git a/crates/print/README.md b/crates/print/README.md index eb7af885e..56ba5ed86 100644 --- a/crates/print/README.md +++ b/crates/print/README.md @@ -199,10 +199,10 @@ job) and `an_installed_printer_prints_a_file` (`CRAFT_PRINT_TEST_PRINTER`, `CRAFT_PRINT_TEST_FILE`, optional `CRAFT_PRINT_TEST_SCALING=shrink` and `CRAFT_PRINT_TEST_DUPLEX=long`). Physical printer fidelity remains a hardware check. -The cross-platform GitHub Actions workflow is defined in `.github/workflows/print.yml`. -It runs formatting, Clippy and this crate's own tests on Windows, Linux and macOS when print -code changes, and supports manual runs. The Windows job executes the spooler regression above; -physical printer fidelity still requires hardware verification. +The Workspace gate (`.github/workflows/workspace.yml`) runs formatting, Clippy and this crate's +tests on Windows, Linux and macOS. Its Windows leg installs the test print queue and runs the +spooler regression above with `CRAFT_PRINT_REQUIRE_QUEUE=1`; physical printer fidelity still +requires hardware verification. Windows discovery reports driver duplex support in `Printer::two_sided` (a two-sided option in the driver's PrintCapabilities); CUPS leaves it unknown. Explicit simplex/duplex choices that the driver From 688c5beba2cc540299bd8f5411e88cadfe802fe6 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:05:33 +0000 Subject: [PATCH 69/97] ci: cache the PhotoCraft test corpora The gate restores .test-inputs/photocraft/corpus before its setup, keyed on scripts/ci-test-inputs.sh (which holds the PhotoCraft pin), and the setup uses a restored corpus as it is. A hit skips the PhotoCraft checkout and its xtask build: 2:17 of Windows setup, about 1:00 on Linux and macOS. Uses craft-common-actions' new cache-paths, cache-key and cache-key-files inputs. --- .github/workflows/nightly.yml | 3 +++ .github/workflows/workspace.yml | 5 +++++ 2 files changed, 8 insertions(+) diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 2ecc68ecb..ed9d36127 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -28,4 +28,7 @@ jobs: linux-env: WGPU_BACKEND=vulkan env: CRAFT_PRINT_REQUIRE_QUEUE=0 setup-command: bash scripts/ci-test-inputs.sh + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh command: cargo nextest run --workspace --all-features --locked --profile ci diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 7faba8a04..77020820f 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -44,6 +44,11 @@ jobs: CRAFT_HOSTILE_DIVISOR=8 PROPTEST_CASES=64 setup-command: bash scripts/ci-test-inputs.sh + # The PhotoCraft corpora, keyed on the script that pins them: a hit skips the PhotoCraft + # checkout and its xtask build (1:51 on Windows). + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh command: | python3 scripts/test-workspace-concurrency.py python3 scripts/test-workspace-tests.py From 9bd64169668b8638d9f2822ca40c63f954524852 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:05:59 +0000 Subject: [PATCH 70/97] ci: clippy and fmt on a lint leg beside each test leg workspace.yml moves fmt, both clippy runs and the workflow script checks into the gate's lint-command, so each OS gets a lint () leg running beside its gate () leg. Clippy (about 6 min on Linux and 11 on Windows) no longer runs before the test build. scripts/test-workspace-tests.py checks both blocks. --- .github/workflows/workspace.yml | 17 +++++++++-------- scripts/test-workspace-tests.py | 30 +++++++++++++++++++----------- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 77020820f..86b47d398 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -49,24 +49,25 @@ jobs: cache-paths: .test-inputs/photocraft/corpus cache-key: photocraft-corpus cache-key-files: scripts/ci-test-inputs.sh - command: | - python3 scripts/test-workspace-concurrency.py - python3 scripts/test-workspace-tests.py + # A `lint ()` leg beside each `gate ()` leg, so clippy is off the tests' critical path. + lint-command: | + if [ "$RUNNER_OS" = Linux ]; then + python3 scripts/test-workspace-concurrency.py + python3 scripts/test-workspace-tests.py + fi cargo fmt --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo clippy --workspace --all-targets --all-features --locked -- -D warnings + command: | # The tests run once, with every feature, in parallel across test binaries; nextest skips - # doctests, so `cargo test --doc` runs them. The default-feature compile is the first - # clippy run's; the second command runs the crates whose tests check behaviour with a + # doctests, so `cargo test --doc` runs them. The default-feature compile is the lint leg's + # first clippy run; the last command runs the crates whose tests check behaviour with a # feature off, which an all-features build cannot reach. cargo nextest run --workspace --all-features --locked --profile ci cargo test --workspace --doc --all-features --locked cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci windows-command: | powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' - cargo fmt --check - cargo clippy --workspace --all-targets --locked -- -D warnings - cargo clippy --workspace --all-targets --all-features --locked -- -D warnings cargo nextest run --workspace --all-features --locked --profile ci cargo test --workspace --doc --all-features --locked cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci diff --git a/scripts/test-workspace-tests.py b/scripts/test-workspace-tests.py index 4da52d701..fada6dc9b 100644 --- a/scripts/test-workspace-tests.py +++ b/scripts/test-workspace-tests.py @@ -18,7 +18,7 @@ def block(text, name): return "\n".join(line[8:] for line in match[1].splitlines()) -def commands(os_name, fail=""): +def commands(os_name, fail="", name="command"): # Functions avoid executing any caller-supplied cargo command or changing the workspace. # The real bash -euo pipefail semantics still apply, including failures inside a branch. stub = """ @@ -29,7 +29,7 @@ cargo() { python3() { :; } """ return subprocess.run( - ["bash", "-euo", "pipefail", "-c", stub + block(WORKFLOW.read_text(), "command")], + ["bash", "-euo", "pipefail", "-c", stub + block(WORKFLOW.read_text(), name)], env={**os.environ, "RUNNER_OS": os_name, "FAIL": fail}, text=True, capture_output=True, check=False, ) @@ -48,24 +48,32 @@ TESTS = [ class WorkspaceTests(unittest.TestCase): + def test_every_leg_lints_with_both_feature_sets(self): + for os_name in ("Linux", "macOS", "Windows"): + with self.subTest(os=os_name): + result = commands(os_name, name="lint-command") + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.splitlines(), COMMON) + def test_linux_and_macos_run_one_feature_set_with_doctests(self): for os_name in ("Linux", "macOS"): with self.subTest(os=os_name): result = commands(os_name) self.assertEqual(result.returncode, 0, result.stderr) - self.assertEqual(result.stdout.splitlines(), COMMON + TESTS) + self.assertEqual(result.stdout.splitlines(), TESTS) def test_each_stage_failure_remains_fatal(self): - for index, command in enumerate(COMMON + TESTS): - with self.subTest(command=command): - result = commands("Linux", command) - self.assertEqual(result.returncode, 17, result.stderr) - self.assertEqual(result.stdout.splitlines(), (COMMON + TESTS)[:index + 1]) + for name, stages in (("lint-command", COMMON), ("command", TESTS)): + for index, command in enumerate(stages): + with self.subTest(block=name, command=command): + result = commands("Linux", command, name) + self.assertEqual(result.returncode, 17, result.stderr) + self.assertEqual(result.stdout.splitlines(), stages[:index + 1]) - def test_windows_runs_the_same_cargo_commands(self): + def test_windows_runs_the_same_tests(self): source = block(WORKFLOW.read_text(), "windows-command") cargo = [line.strip() for line in source.splitlines() if line.strip().startswith("cargo ")] - self.assertEqual(cargo, ["cargo " + command for command in COMMON + TESTS]) + self.assertEqual(cargo, ["cargo " + command for command in TESTS]) def test_ci_profile_keeps_its_failure_policy_without_retries_or_filtering(self): config = tomllib.loads((ROOT / ".config/nextest.toml").read_text()) @@ -94,7 +102,7 @@ class WorkspaceTests(unittest.TestCase): self.assertIn('os: \'["ubuntu-latest","windows-latest","macos-latest"]\'', source) self.assertIn(" msrv:", source) self.assertIn(" wasm:", source) - self.assertIn("python3 scripts/test-workspace-tests.py", block(source, "command")) + self.assertIn("python3 scripts/test-workspace-tests.py", block(source, "lint-command")) if __name__ == "__main__": From a1398a3b6168ec2540588a92f7f80983382d054f Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:06:05 +0000 Subject: [PATCH 71/97] ci: macOS and Windows legs on a pull request only when it can change them workspace.yml passes select-os to the gate: a pull request runs the macOS and Windows legs when a changed file is in a crate with platform cfg code or in a crate that depends on one, is part of the build setup (workflows, Cargo.lock, the root Cargo.toml, toolchain, .cargo, .config), or lies outside the crates and is not documentation. 37 of 177 crates have platform code and 57 are affected with their dependents; 39 of the last 80 merged pull requests would have run Linux only, without the macOS queue. The full-ci label runs every leg from the next push or manual run. Pushes to main run every leg. --- .github/workflows/workspace.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 86b47d398..aa2e04fe3 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -24,6 +24,11 @@ jobs: uses: storytold/craft-common-actions/.github/workflows/gate.yml@main with: os: '["ubuntu-latest","windows-latest","macos-latest"]' + # On a pull request, macOS and Windows run only when it can change platform behaviour: a + # crate with platform cfg code or one that depends on it, the build setup, or a file outside + # the crates (craft-common-actions' select-platforms). The full-ci label runs them anyway + # from the next push or manual run; pushes to main always run every leg. + select-os: '["windows-latest","macos-latest"]' timeout-minutes: 120 # Every leg runs its tests with nextest, and its doctests with cargo test (.config/nextest.toml). tools: cargo-nextest@0.9.150 From c0421c7fc6774e5087ea37e7c4fd0882a656b8fc Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 19:08:21 +0000 Subject: [PATCH 72/97] ci: cancel superseded main runs; a scheduled full run saves the caches Pushes to main cancel the Workspace run they supersede, as pull requests already do; the newest push's run tests everything before it. On 16 Nov main had 144 pushes, each a three-OS run that could not be cancelled, which is much of what fills the org's macOS runners. Release tags, manual runs and a new scheduled run every 6 hours keep a group of their own and always finish, and the scheduled run saves the caches (the gate already saves on scheduled runs of the default branch). scripts/test-workspace-concurrency.py checks the new policy. The per-crate workflows, which no longer save caches, cancel superseded runs on every branch, main included. --- .github/workflows/ai-core.yml | 8 ++-- .github/workflows/atomic.yml | 8 ++-- .github/workflows/audio.yml | 9 ++--- .github/workflows/cms.yml | 6 +++ .github/workflows/crw.yml | 9 ++--- .github/workflows/dialogs.yml | 8 ++-- .github/workflows/doc.yml | 8 ++-- .github/workflows/ecproj-format.yml | 8 ++-- .github/workflows/font-store.yml | 8 ++-- .github/workflows/formats.yml | 9 ++--- .github/workflows/jpeg.yml | 9 ++--- .github/workflows/keymap.yml | 9 ++--- .github/workflows/media.yml | 9 ++--- .github/workflows/pcraft-format.yml | 8 ++-- .github/workflows/pdf.yml | 9 ++--- .github/workflows/proof.yml | 9 ++--- .github/workflows/update.yml | 8 ++-- .github/workflows/vectorcraft-format.yml | 8 ++-- .github/workflows/web-api.yml | 8 ++-- .github/workflows/web-host.yml | 9 ++--- .github/workflows/window.yml | 8 ++-- .github/workflows/workspace.yml | 16 +++++--- scripts/test-workspace-concurrency.py | 50 ++++++++++++++++-------- 23 files changed, 129 insertions(+), 112 deletions(-) diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index 4de27650e..2be123b23 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ai-core-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ai-core-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index be11c8d89..23de7f9f4 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: atomic-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: atomic-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this runs what it does not. jobs: diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index d4b2a5202..5fd971c62 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -17,11 +17,10 @@ env: PROPTEST_CASES: "64" concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-audio-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-audio-${{ github.ref }} + cancel-in-progress: true jobs: lint: diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml index 2040212c2..9220d8e09 100644 --- a/.github/workflows/cms.yml +++ b/.github/workflows/cms.yml @@ -11,6 +11,12 @@ on: permissions: contents: read +concurrency: + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: cms-${{ github.ref }} + cancel-in-progress: true + # clippy and the debug tests run in the Workspace gate; this runs the release build of the tests. jobs: cms: diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml index f5bb91a38..466b6c05d 100644 --- a/.github/workflows/crw.yml +++ b/.github/workflows/crw.yml @@ -12,11 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-crw-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-crw-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml index 151a63e36..23def9feb 100644 --- a/.github/workflows/dialogs.yml +++ b/.github/workflows/dialogs.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: dialogs-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: dialogs-${{ github.ref }} + cancel-in-progress: true jobs: dialogs: diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 394cdbdbe..627543381 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: doc-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: doc-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml index eeacf5801..048c897b3 100644 --- a/.github/workflows/ecproj-format.yml +++ b/.github/workflows/ecproj-format.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ecproj-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ecproj-format-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml index 34c7c09a1..e655697b3 100644 --- a/.github/workflows/font-store.yml +++ b/.github/workflows/font-store.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: font-store-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: font-store-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml index 769271d84..12478d2c9 100644 --- a/.github/workflows/formats.yml +++ b/.github/workflows/formats.yml @@ -42,11 +42,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-formats-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-formats-${{ github.ref }} + cancel-in-progress: true jobs: check: diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index 325cc0c02..c49c03581 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -12,11 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-jpeg-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-jpeg-${{ github.ref }} + cancel-in-progress: true jobs: check: diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml index f85f84935..bd4ef280a 100644 --- a/.github/workflows/keymap.yml +++ b/.github/workflows/keymap.yml @@ -12,11 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: keymap-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: keymap-${{ github.ref }} + cancel-in-progress: true jobs: linux: diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index 0fbf78b12..1b5afaebd 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -17,11 +17,10 @@ env: PROPTEST_CASES: "64" concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-media-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-media-${{ github.ref }} + cancel-in-progress: true jobs: lint: diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml index 0e82ba888..0e4feabc9 100644 --- a/.github/workflows/pcraft-format.yml +++ b/.github/workflows/pcraft-format.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: pcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: pcraft-format-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the # workspace on 1.95; this checks the web build on 1.95. diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index 3be70ad99..7b7397757 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -16,11 +16,10 @@ env: PROPTEST_CASES: "64" concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-pdf-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-pdf-${{ github.ref }} + cancel-in-progress: true jobs: native: diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml index 27bf5b32b..ea5edb8a5 100644 --- a/.github/workflows/proof.yml +++ b/.github/workflows/proof.yml @@ -12,11 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: craft-proof-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: craft-proof-${{ github.ref }} + cancel-in-progress: true jobs: check: diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index cfb14ec9a..96ab4d6ad 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: update-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: update-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests with default and with all features run in the Workspace gate on every # OS; this runs the egui feature alone. diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml index e6cfb7a70..cd66615a5 100644 --- a/.github/workflows/vectorcraft-format.yml +++ b/.github/workflows/vectorcraft-format.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: vectorcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: vectorcraft-format-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the # workspace on 1.95; this checks the web build on 1.95. diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml index 1c9b2c92f..f0f8e22da 100644 --- a/.github/workflows/web-api.yml +++ b/.github/workflows/web-api.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: web-api-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: web-api-${{ github.ref }} + cancel-in-progress: true jobs: web-api: diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml index 28129a542..dc0254850 100644 --- a/.github/workflows/web-host.yml +++ b/.github/workflows/web-host.yml @@ -12,11 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-web-host-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-web-host-${{ github.ref }} + cancel-in-progress: true jobs: check: diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml index bf5f39835..c13b1ac3f 100644 --- a/.github/workflows/window.yml +++ b/.github/workflows/window.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: window-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: window-${{ github.ref }} + cancel-in-progress: true # fmt, clippy and the tests with default and with all features (egui and restore together) run in # the Workspace gate on every OS; this runs each feature alone. diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index aa2e04fe3..af7e04769 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -6,17 +6,21 @@ on: tags: ["v*"] pull_request: workflow_dispatch: + # A full run on main every 6 hours that is never cancelled, so the caches are saved while pushes + # to main cancel each other. + schedule: + - cron: "17 */6 * * *" permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (push to main, a release tag, a manual run) gets a group of its own: it is neither - # cancelled nor replaced while queued, so a main run always finishes and saves the dependency - # cache, and a release run is never cancelled. - group: workspace-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # A pull request, and main, each have one group, so a newer push cancels the run it supersedes; + # the newest push's run still tests everything before it. Every other run (a release tag, a + # manual run, the scheduled run) gets a group of its own and is neither cancelled nor replaced + # while queued: a release run always finishes, and the scheduled run saves the caches. + group: workspace-${{ (github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main') && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main' }} jobs: native: diff --git a/scripts/test-workspace-concurrency.py b/scripts/test-workspace-concurrency.py index 96bfae304..db20031e9 100644 --- a/scripts/test-workspace-concurrency.py +++ b/scripts/test-workspace-concurrency.py @@ -1,5 +1,6 @@ #!/usr/bin/env python3 -"""Check the Workspace workflow's pull-request-only cancellation policy. +"""Check the Workspace workflow's cancellation policy: pull requests and pushes to main cancel the +run they supersede; release tags, manual runs and scheduled runs are never cancelled. The policy is the top-level `concurrency` block of .github/workflows/workspace.yml. This script reads those fields, requires the documented expression shapes, and checks which group each event @@ -21,16 +22,28 @@ except ImportError: yaml = None DEFAULT_WORKFLOW = Path(__file__).resolve().parent.parent / ".github" / "workflows" / "workspace.yml" -PULL_REQUEST, PUSH, DISPATCH = "pull_request", "push", "workflow_dispatch" +PULL_REQUEST, PUSH, DISPATCH, SCHEDULE = "pull_request", "push", "workflow_dispatch", "schedule" -# The two shapes this policy may use. GitHub reads `a && b || c` as "b, or c when a is false"; these -# patterns are the whole of that expression language this script understands, so a reworded policy -# has to be reworded here too, on purpose. github.ref, never github.head_ref or github.sha. +# The runs that share a group per ref and cancel the run they supersede. GitHub reads `a || b && c` +# as `a || (b && c)`, and `x && github.ref || github.run_id` as "github.ref, or the run id when x is +# false". This exact condition is the whole of the expression language this script understands, so +# a reworded policy has to be reworded here too, on purpose. github.ref, never github.head_ref or +# github.sha. +SUPERSEDED = "github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main'" GROUP_SHAPE = re.compile( - r"(?P[A-Za-z0-9._-]+)-\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*" + r"(?P[A-Za-z0-9._-]+)-\$\{\{\s*\(\s*(?P[^()]+?)\s*\)\s*" r"&&\s*github\.ref\s*\|\|\s*github\.run_id\s*\}\}" ) -CANCEL_SHAPE = re.compile(r"\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*\}\}") +CANCEL_SHAPE = re.compile(r"\$\{\{\s*(?P[^{}]+?)\s*\}\}") + + +def normal(expression): + return re.sub(r"\s+", " ", expression).strip() + + +def superseded(event_name, ref): + """SUPERSEDED, evaluated.""" + return event_name == PULL_REQUEST or (event_name == PUSH and ref == "refs/heads/main") def read_concurrency(text): @@ -72,22 +85,25 @@ def other_run(event_name, ref, run_id): MAIN, TAG = ("refs/heads/main", "refs/tags/v1.2.3") SAME_GROUP = [ ("a newer commit on the same pull request", pull_request(1316, 43599251877), pull_request(1316, 43600899878)), - ("a rerun of one main run", other_run(PUSH, MAIN, 7001), other_run(PUSH, MAIN, 7001)), + ("two pushes to main", other_run(PUSH, MAIN, 3), other_run(PUSH, MAIN, 4)), ] DIFFERENT_GROUPS = [ ("two pull requests", pull_request(1316, 1), pull_request(1317, 1)), ("the same branch name in two forks", pull_request(1316, 2), pull_request(1400, 2)), - ("two pushes to main", other_run(PUSH, MAIN, 3), other_run(PUSH, MAIN, 4)), ("two release tag runs", other_run(PUSH, TAG, 5), other_run(PUSH, TAG, 6)), ("two manual runs", other_run(DISPATCH, MAIN, 7), other_run(DISPATCH, MAIN, 8)), + ("two scheduled runs", other_run(SCHEDULE, MAIN, 15), other_run(SCHEDULE, MAIN, 16)), + ("a main push and a scheduled run", other_run(PUSH, MAIN, 17), other_run(SCHEDULE, MAIN, 17)), + ("a main push and a manual run of main", other_run(PUSH, MAIN, 18), other_run(DISPATCH, MAIN, 18)), ("a main push and a pull request", other_run(PUSH, MAIN, 9), pull_request(1316, 9)), ("a release tag and a pull request", other_run(PUSH, TAG, 10), pull_request(1316, 10)), ] CANCELLATION = [ ("a push supersedes the previous run of its pull request", pull_request(1316, 11), True), - ("a push to main is never cancelled", other_run(PUSH, MAIN, 12), False), + ("a push to main supersedes the previous main run", other_run(PUSH, MAIN, 12), True), ("a release tag run is never cancelled", other_run(PUSH, TAG, 13), False), ("a manual run is never cancelled", other_run(DISPATCH, MAIN, 14), False), + ("the scheduled run that saves the caches is never cancelled", other_run(SCHEDULE, MAIN, 19), False), ] @@ -103,17 +119,17 @@ class ConcurrencyTests(unittest.TestCase): if not cls.group_shape or not cls.cancel_shape: raise AssertionError(f"the concurrency fields are not the documented shapes: {cls.fields}") - def cancels(self, event_name): - return event_name == self.cancel_shape["event"] + def cancels(self, event_name, ref): + return superseded(event_name, ref) def group(self, event_name, ref, run_id): - return self.group_shape["prefix"] + "-" + (ref if event_name == self.group_shape["event"] else str(run_id)) + return self.group_shape["prefix"] + "-" + (ref if superseded(event_name, ref) else str(run_id)) def test_policy_is_the_two_documented_fields(self): self.assertEqual(sorted(self.fields), ["cancel-in-progress", "group"]) self.assertEqual(self.group_shape["prefix"], "workspace") - self.assertEqual(self.group_shape["event"], PULL_REQUEST) - self.assertEqual(self.cancel_shape["event"], PULL_REQUEST) + self.assertEqual(normal(self.group_shape["condition"]), SUPERSEDED) + self.assertEqual(normal(self.cancel_shape["condition"]), SUPERSEDED) def test_a_scalar_concurrency_value_is_not_read_as_a_mapping(self): cases = { @@ -133,10 +149,10 @@ class ConcurrencyTests(unittest.TestCase): with self.subTest(description): self.assertNotEqual(self.group(*first), self.group(*second), description) - def test_only_a_pull_request_cancels(self): + def test_only_pull_requests_and_main_pushes_cancel(self): for description, context, expected in CANCELLATION: with self.subTest(description): - self.assertEqual(self.cancels(context[0]), expected, description) + self.assertEqual(self.cancels(context[0], context[1]), expected, description) def test_pyyaml_reads_the_same_fields(self): if yaml is None: From 17329ac50a6ff5452e2336d2ad684f94bfed2e82 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 14:09:45 -0500 Subject: [PATCH 73/97] Recognize extended metadata maps and track duplicate selector dispatch --- crates/evm/src/lib.rs | 6 ++++-- crates/evm/tests/evm_metadata_map_keys.rs | 25 +++++++++++++++++++++++ crates/evm/tests/evm_selector_dedup.rs | 14 +++++++++++++ 3 files changed, 43 insertions(+), 2 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index e85541eed..502e451e1 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -283,7 +283,7 @@ fn split_metadata(code: &[u8]) -> (usize, Option) { } let start = n - 2 - len; let Some(cbor) = code.get(start..n - 2) else { return (n, None) }; - if !matches!(cbor.first(), Some(0xa1..=0xb7 | 0xbf)) { + if !matches!(cbor.first(), Some(0xa1..=0xb8 | 0xbf)) { return (n, None); } let mut pos = 0usize; @@ -583,6 +583,9 @@ pub fn analyze(code: &[u8]) -> Result { if n < 4 && extraction.is_none() { continue; } + // Duplicate identities still advance the end of the recognized dispatcher. + // Otherwise the fallback scan starts inside a later comparison, not after it. + last_jumpi = Some(jumpi_k); if !selectors.insert(sel) { continue; } @@ -592,7 +595,6 @@ pub fn analyze(code: &[u8]) -> Result { } else { vyper_like += 1; } - last_jumpi = Some(jumpi_k); let di = index_of(dest); let jumpdest_valid = pattern != "eq-jumpi" || di.and_then(at).is_some_and(|x| x.op == 0x5b); let (mutability, reason) = if !jumpdest_valid { diff --git a/crates/evm/tests/evm_metadata_map_keys.rs b/crates/evm/tests/evm_metadata_map_keys.rs index eed0fdfbd..17ee4822c 100644 --- a/crates/evm/tests/evm_metadata_map_keys.rs +++ b/crates/evm/tests/evm_metadata_map_keys.rs @@ -66,3 +66,28 @@ fn equal_keys_in_separate_maps_are_independent() { assert_eq!(entries["a"]["x"], 0); assert_eq!(entries["b"]["x"], 1); } + +#[test] +fn extended_length_metadata_maps_respect_the_pair_limit() { + let map = |count: u8| { + let mut cbor = vec![0xb8, count]; + for index in 0..count { + let key = format!("k{index:02}"); + cbor.push(0x63); + cbor.extend_from_slice(key.as_bytes()); + cbor.push(0); + } + cbor + }; + for count in [24, 32] { + let code = contract_with_trailer(&map(count)); + let report = analyze(&code).unwrap(); + assert_eq!(report.analysed_size, 2); + assert_eq!(report.metadata.unwrap().entries.as_object().unwrap().len(), usize::from(count)); + } + assert_unrecognized(&map(33)); + assert_unrecognized(&[0xb8]); + let mut truncated = map(24); + truncated.pop(); + assert_unrecognized(&truncated); +} diff --git a/crates/evm/tests/evm_selector_dedup.rs b/crates/evm/tests/evm_selector_dedup.rs index 8ce4b88a4..2761a23d3 100644 --- a/crates/evm/tests/evm_selector_dedup.rs +++ b/crates/evm/tests/evm_selector_dedup.rs @@ -68,3 +68,17 @@ fn selector_cap_counts_unique_matches() { assert_eq!(capped.functions.last().unwrap().selector, "0x00000fff"); assert!(capped.warnings.iter().any(|warning| warning == "stopped at 4096 selectors")); } + +#[test] +fn repeated_comparisons_keep_fallback_scan_after_the_last_dispatch() { + for (ending, expected) in [(&[0x5f, 0x5f, 0xfd][..], "absent"), (&[0x00][..], "present")] { + let mut code = prefix(); + comparison(&mut code, 0xfeed0001, 4, 0); + comparison(&mut code, 0xfeed0001, 4, 1); + code.extend_from_slice(ending); + let report = evm::analyze(&code).unwrap(); + assert_eq!(report.functions.len(), 1); + assert_eq!(report.functions[0].bytecode_offset, 0); + assert_eq!(report.fallback, expected); + } +} From dcda149a8a2583fbb2ce1a581146c81bb21d27c3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 14:13:02 -0500 Subject: [PATCH 74/97] Add bounded Source Map v3 parser and lookup core (#2037) * sourcemap: Craft Anything Port parser/model/lookup core from Craft Anything f64ae3bf3c8863a982af1304e06de20653803968. Annotation and data URL helpers stay app-owned. * sourcemap: Format parsers refuse or flag input they used to half-read (#652) Port parser/model/lookup core from Craft Anything 15de36614b2d1039ed68bffcc36e0e92053b3f12. Annotation and data URL helpers stay app-owned. * sourcemap: Keep source lookups inside their declared index map section (R3.12) (#1130) Port parser/model/lookup core from Craft Anything a205f1d1571cbce001c546f4753943a569d7a7fe. Annotation and data URL helpers stay app-owned. * sourcemap: Decode source map position deltas within the format's 32-bit range (R3.12) (#1133) Port parser/model/lookup core from Craft Anything f5aad102b048cb6f01a8a7b90dcf2d7a7a395567. Annotation and data URL helpers stay app-owned. * sourcemap: Look up source mappings without scanning every segment on a generated line (R3.12) (#1139) Port parser/model/lookup core from Craft Anything 1fab01712915e744ea042154ff81013a19c9bfc5. Annotation and data URL helpers stay app-owned. * sourcemap: Preserve source map URL roots when joining relative sources (R3.12) (#1332) Port parser/model/lookup core from Craft Anything 7fd244005da7a37a6389ac09643fb759420f72a2. Annotation and data URL helpers stay app-owned. * sourcemap: Bound generated source-map lines across inline sections (R3.12) (#1533) Port parser/model/lookup core from Craft Anything 68ba5239a85c7f6e842c2a7a9c0254f125eaa917. Annotation and data URL helpers stay app-owned. * sourcemap: Reject source map mappings with missing source or name entries (R3.12) (#1526) Port parser/model/lookup core from Craft Anything 0ba60eb4e24d1c280db93304ee53a79393f41610. Annotation and data URL helpers stay app-owned. * sourcemap: Apply source map root prefixes before interpreting source paths (R3.12) (#1680) Port parser/model/lookup core from Craft Anything 500a09a217b9a6ce03b2c93035167ce983a83897. Annotation and data URL helpers stay app-owned. * sourcemap: Bound expanded source-map source lists before building them (R3.12) (#1689) Port parser/model/lookup core from Craft Anything 22c44d01d271c49187104802459085f273f855f0. Annotation and data URL helpers stay app-owned. * sourcemap: Refuse source maps with more entries than the parser keeps (R3.12) (#1703) Port parser/model/lookup core from Craft Anything ba83da2bc567611d0c8aef124c2c3d1ba03ade58. Annotation and data URL helpers stay app-owned. * sourcemap: Count source-map sections, check skipped values and keep refused maps' sources uncertain (R3.12) (#1705) Port parser/model/lookup core from Craft Anything ab79ec87a4da58d8965b6d4f95b751464ba6e999. Annotation and data URL helpers stay app-owned. * sourcemap: Keep the sources of a source map refused for bad mappings or section offsets (R3.12) (#1717) Port parser/model/lookup core from Craft Anything 12aad97757d692e8dbc8af03ceb60c6b44f53339. Annotation and data URL helpers stay app-owned. * sourcemap: Mark sources of unread external source-map sections uncertain (R3.12) (#1767) (#1767) Port parser/model/lookup core from Craft Anything d56fa23860f1fd20249fb945e94fdf3fcfc83a2d. Annotation and data URL helpers stay app-owned. * sourcemap: List sources from the section maps of an indexed source map (R3.12) Port parser/model/lookup core from Craft Anything 0b1a643944e119bc4d580de94b287ab257ab91c5. Annotation and data URL helpers stay app-owned. * sourcemap: retain entry_budgets regression coverage Port crates/formats/tests/sourcemap_entry_budgets.rs from Craft Anything, latest source change 12aad97757d692e8dbc8af03ceb60c6b44f53339. Only crate imports adapted. * sourcemap: retain external_sections regression coverage Port crates/formats/tests/sourcemap_external_sections.rs from Craft Anything, latest source change d56fa23860f1fd20249fb945e94fdf3fcfc83a2d. Only crate imports adapted. * sourcemap: retain inventory_budgets regression coverage Port crates/formats/tests/sourcemap_inventory_budgets.rs from Craft Anything, latest source change 22c44d01d271c49187104802459085f273f855f0. Only crate imports adapted. * sourcemap: retain line_budgets regression coverage Port crates/formats/tests/sourcemap_line_budgets.rs from Craft Anything, latest source change 68ba5239a85c7f6e842c2a7a9c0254f125eaa917. Only crate imports adapted. * sourcemap: retain root_prefix regression coverage Port crates/formats/tests/sourcemap_root_prefix.rs from Craft Anything, latest source change 500a09a217b9a6ce03b2c93035167ce983a83897. Only crate imports adapted. * sourcemap: retain section_columns regression coverage Port crates/formats/tests/sourcemap_section_columns.rs from Craft Anything, latest source change 15de36614b2d1039ed68bffcc36e0e92053b3f12. Only crate imports adapted. * Expose bounded Source Map v3 core with retained regression tests --------- Co-authored-by: Brandon Thomas Co-authored-by: BFlat Co-authored-by: Afloat Co-authored-by: RRFZ <247457381+Plastic-time@users.noreply.github.com> Co-authored-by: Nicolas Bohn Co-authored-by: Alex Joaquim Pereira --- ATTRIBUTION.md | 3 + Cargo.lock | 9 + Cargo.toml | 1 + crates/sourcemap/Cargo.toml | 15 + crates/sourcemap/src/lib.rs | 816 ++++++++++++++++++++ crates/sourcemap/src/tests.rs | 122 +++ crates/sourcemap/tests/entry_budgets.rs | 145 ++++ crates/sourcemap/tests/external_sections.rs | 84 ++ crates/sourcemap/tests/inventory_budgets.rs | 104 +++ crates/sourcemap/tests/line_budgets.rs | 72 ++ crates/sourcemap/tests/root_prefix.rs | 80 ++ crates/sourcemap/tests/section_columns.rs | 24 + 12 files changed, 1475 insertions(+) create mode 100644 crates/sourcemap/Cargo.toml create mode 100644 crates/sourcemap/src/lib.rs create mode 100644 crates/sourcemap/src/tests.rs create mode 100644 crates/sourcemap/tests/entry_budgets.rs create mode 100644 crates/sourcemap/tests/external_sections.rs create mode 100644 crates/sourcemap/tests/inventory_budgets.rs create mode 100644 crates/sourcemap/tests/line_budgets.rs create mode 100644 crates/sourcemap/tests/root_prefix.rs create mode 100644 crates/sourcemap/tests/section_columns.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 58d8077e7..546f3e637 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -134,6 +134,9 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `crates/video/src/screen_video.rs` extracts AniCraft `crates/xfl/src/video.rs` codec-3 decoding and its synthetic partial-block fixture, introduced by Tanish Manku in `1f3e603b7ff53a3da364e41ec4da8d43dc83aab0` with pixel-loop cleanup `2b7571363b4b647266df758f95b6e397021cfd4d` (MIT OR Apache-2.0). Import commits preserve Tanish as primary author. Caller-owned bounds and neutral RGBA output separate codec work from the consuming app's FLV first-frame/report policy. Boundary tests and integration are subsequent Dylan M. Taylor changes. +## Source Map v3 parser and lookup + +`crates/sourcemap` extracts the bounded parser, source inventory and generated-position lookup from Craft Anything `crates/formats/src/sourcemap.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). Core-history ports preserve Brandon Thomas, BFlat, Afloat, RRFZ, Nicolas Bohn and Alex Joaquim Pereira as primary authors, with exact source revisions in each commit. Six regression files preserve their source authors; nine core unit tests retain the original tests. App annotation scanning, data URLs, base64 and file I/O are intentionally not imported. Workspace wiring is a subsequent change; existing limits and errors are unchanged. ## JSONC span-preserving editing `crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. diff --git a/Cargo.lock b/Cargo.lock index 6412bd28a..05847f390 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3103,6 +3103,15 @@ dependencies = [ name = "craft-sniff" version = "0.1.0" +[[package]] +name = "craft-sourcemap" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-ssip" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 6dad17db6..5f38bef09 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-sourcemap = { path = "crates/sourcemap" } craft-pcap = { path = "crates/pcap" } craft-har = { path = "crates/har" } craft-jsonc = { path = "crates/jsonc" } diff --git a/crates/sourcemap/Cargo.toml b/crates/sourcemap/Cargo.toml new file mode 100644 index 000000000..b36df0107 --- /dev/null +++ b/crates/sourcemap/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-sourcemap" +description = "Bounded Source Map v3 parser, source inventory and generated-position lookup" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde = { workspace = true } +serde_json = { workspace = true } + +thiserror = { workspace = true } diff --git a/crates/sourcemap/src/lib.rs b/crates/sourcemap/src/lib.rs new file mode 100644 index 000000000..a3c23ffa2 --- /dev/null +++ b/crates/sourcemap/src/lib.rs @@ -0,0 +1,816 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! Source maps (revision 3), including indexed maps with sections. +//! +//! Lookups follow the "original positions for a generated position" rule: on the generated line, +//! take the greatest segment column not after the requested column and return every segment that +//! starts there. Lines are 0-based here (callers add one for display); columns are 0-based UTF-16 +//! code units as the format defines. + +use serde::de::{self, DeserializeSeed, MapAccess, SeqAccess, Visitor}; +use std::cell::Cell; +use std::fmt; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Limits { + /// Biggest map JSON accepted. + pub max_bytes: usize, + /// Most decoded segments across the whole map. + pub max_segments: usize, + /// Most generated lines across the whole map, including empty lines and inline sections. + pub max_lines: usize, + /// Deepest section nesting (the format allows one level; we tolerate a few). + pub max_depth: usize, + /// Most `sources`, `sourcesContent`, `names` and ignore-list entries and index-map sections + /// across the whole map, counted while the JSON is read, so a map of tiny entries is refused + /// before it is kept. An entry a repeated key replaces gives its slot back. + pub max_entries: usize, +} + +impl Default for Limits { + fn default() -> Self { + Limits { max_bytes: 64 * 1024 * 1024, max_segments: 4_000_000, max_lines: 1_000_000, max_depth: 8, max_entries: 4_000_000 } + } +} + +/// Limits on retained source names after applying each map's root. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct InventoryLimits { + pub max_sources: usize, + /// Total UTF-8 bytes in the expanded source paths, across all sections. + pub max_bytes: usize, +} + +impl Default for InventoryLimits { + fn default() -> Self { + Self { max_sources: 1_000_000, max_bytes: 64 * 1024 * 1024 } + } +} + +/// An ordered prefix of the map's source names, with their complete identities. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct SourceInventory { + pub sources: Vec, + /// More names existed than the limits or available allocations could retain. + pub truncated: bool, + /// Index-map sections that pointed at an external map nobody read, so the sources they + /// would add are unknown (not absent). + pub external_sections: usize, +} + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum SourceMapError { + #[error("source map is {0} bytes; the limit is {1}")] + TooLarge(usize, usize), + #[error("source map is not valid JSON: {0}")] + BadJson(String), + #[error("not a version 3 source map")] + BadVersion, + #[error("source map mappings are malformed at segment {0}")] + BadMappings(usize), + #[error("source map index has invalid sections")] + BadSections, + #[error("source map has more than {0} segments")] + TooManySegments(usize), + #[error("source map has more than {0} generated lines")] + TooManyLines(usize), + #[error("could not reserve memory for generated source-map lines")] + LineAllocationFailed, + #[error("source map sections nest deeper than {0}")] + TooDeep(usize), + #[error("source map has more than {0} source, content, name, ignore-list and section entries")] + TooManyEntries(usize), +} + +/// One decoded mapping segment. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Segment { + pub generated_column: u32, + /// (source index, original line, original column, name index) + pub original: Option<(u32, u32, u32, Option)>, +} + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct SourceMap { + pub file: Option, + pub source_root: Option, + pub sources: Vec>, + pub sources_content: Vec>, + pub names: Vec, + pub ignore_list: Vec, + /// Segments per generated line, sorted by column. + pub lines: Vec>, + pub segments: usize, + /// Indexed maps: (line offset, column offset, map). + pub sections: Vec<(u32, u32, SourceMap)>, + /// Index-map sections that point at an external map (`url`), which isn't fetched here: the + /// sources that map would add are unknown, not absent. + pub external_sections: usize, +} + +/// A position in an original source. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct OriginalPosition { + pub source_index: u32, + pub source: Option, + /// 0-based. + pub line: u32, + /// 0-based. + pub column: u32, + pub name: Option, + /// 0-based generated column of the matched segment. + pub generated_column: u32, +} + +impl SourceMap { + /// The source path with `sourceRoot` prefixed before URL interpretation. + pub fn source_path(&self, index: u32) -> Option { + let s = self.sources.get(index as usize)?.as_ref()?; + // Generators commonly emit an empty root to mean no root. Keep those source identities + // unchanged even though the literal ECMA-426 prefix algorithm would prepend a slash. + Some(match self.source_root.as_deref().filter(|root| !root.is_empty()) { + Some(root) => { + let join = if root.ends_with('/') { "" } else { "/" }; + format!("{root}{join}{s}") + } + None => s.clone(), + }) + } + + pub fn source_content(&self, index: u32) -> Option<&str> { + self.sources_content.get(index as usize)?.as_deref() + } + + /// Every original position for a generated (line, column), both 0-based. + pub fn original_positions(&self, line: u32, column: u32) -> Vec { + if !self.sections.is_empty() { + // Last section that starts at or before the position. + let end = self.sections.partition_point(|(l, c, _)| (*l, *c) <= (line, column)); + let Some((l, c, map)) = end.checked_sub(1).and_then(|i| self.sections.get(i)) else { return Vec::new() }; + let rel_line = line.saturating_sub(*l); + let rel_col = if rel_line == 0 { column.saturating_sub(*c) } else { column }; + return map + .original_positions(rel_line, rel_col) + .into_iter() + .filter_map(|mut position| { + if rel_line == 0 { + position.generated_column = position.generated_column.checked_add(*c)?; + } + Some(position) + }) + .collect(); + } + let Some(segs) = self.lines.get(line as usize) else { return Vec::new() }; + // Greatest generated column <= column. + let idx = segs.partition_point(|s| s.generated_column <= column); + let Some(best) = idx.checked_sub(1).and_then(|i| segs.get(i)) else { return Vec::new() }; + let col = best.generated_column; + let first = segs.partition_point(|s| s.generated_column < col); + segs.get(first..idx) + .unwrap_or_default() + .iter() + .filter_map(|s| { + let (src, l, c, n) = s.original?; + Some(OriginalPosition { + source_index: src, + source: self.source_path(src), + line: l, + column: c, + name: n.and_then(|n| self.names.get(n as usize).cloned()), + generated_column: col, + }) + }) + .collect() + } + + /// Sources flattened across sections, within the default inventory limits. + /// Use `source_inventory` to choose limits and observe truncation. + pub fn all_sources(&self) -> Vec { + self.source_inventory(InventoryLimits::default()).sources + } + + /// Retain a bounded prefix, checking expanded lengths before constructing paths. + pub fn source_inventory(&self, limits: InventoryLimits) -> SourceInventory { + let mut sources = Vec::new(); + let mut bytes_left = limits.max_bytes; + let truncated = !self.collect_sources(limits.max_sources, &mut bytes_left, &mut sources); + SourceInventory { sources, truncated, external_sections: self.external_sections_total() } + } + + /// This map's external sections plus those of every map it holds. + fn external_sections_total(&self) -> usize { + self.sections.iter().fold(self.external_sections, |n, (_, _, map)| n.saturating_add(map.external_sections_total())) + } + + /// Append this map and its sections using one shared entry and byte budget. + fn collect_sources(&self, max_sources: usize, bytes_left: &mut usize, out: &mut Vec) -> bool { + let root = self.source_root.as_deref().unwrap_or_default(); + let join = if root.is_empty() || root.ends_with('/') { "" } else { "/" }; + for source in self.sources.iter().flatten() { + let Some(bytes) = root.len().checked_add(join.len()).and_then(|n| n.checked_add(source.len())) else { return false }; + if out.len() >= max_sources || bytes > *bytes_left { + return false; + } + let mut path = String::new(); + if out.try_reserve(1).is_err() || path.try_reserve_exact(bytes).is_err() { + return false; + } + path.push_str(root); + path.push_str(join); + path.push_str(source); + out.push(path); + *bytes_left = bytes_left.saturating_sub(bytes); + } + for (_, _, map) in &self.sections { + if !map.collect_sources(max_sources, bytes_left, out) { + return false; + } + } + true + } +} + +/// Parse a source map. +pub fn parse(json: &[u8], limits: Limits) -> Result { + read(json, limits, true) +} + +/// Read a map's sources, their content, names and ignore list without decoding its mappings or +/// checking its section offsets, so a map [`parse`] refuses for those +/// ([`SourceMapError::BadMappings`] or [`SourceMapError::BadSections`]) can still list its sources. +/// The map has no lines or segments. A map whose mappings, as far as they decode, name a source +/// past the end of its `sources` list is still refused, since the list is known to be short, and so are a section +/// that has neither a map nor a URL, or both, and a `sections` value that isn't an array. +pub fn parse_sources(json: &[u8], limits: Limits) -> Result { + read(json, limits, false) +} + +fn read(json: &[u8], limits: Limits, mappings: bool) -> Result { + if json.len() > limits.max_bytes { + return Err(SourceMapError::TooLarge(json.len(), limits.max_bytes)); + } + // Some servers prefix maps with `)]}'` to defeat XSSI; the format allows skipping that line. + let body = if json.starts_with(b")]}") { json.iter().position(|b| *b == b'\n').and_then(|p| json.get(p + 1..)).unwrap_or(&[]) } else { json }; + let entries = Entries { left: Cell::new(limits.max_entries), exhausted: Cell::new(false) }; + let mut de = serde_json::Deserializer::from_slice(body); + let raw = RawMapSeed(&entries).deserialize(&mut de).and_then(|raw| de.end().map(|()| raw)); + let raw = match raw { + Ok(raw) => raw, + Err(_) if entries.exhausted.get() => return Err(SourceMapError::TooManyEntries(limits.max_entries)), + Err(e) => return Err(SourceMapError::BadJson(e.to_string())), + }; + let mut budget = limits.max_segments; + let mut line_budget = limits.max_lines; + from_raw(raw, 0, limits, &mut budget, &mut line_budget, mappings) +} + +/// `mappings`: decode the mappings and check section offsets, as [`parse`] does. +fn from_raw( + raw: Option, + depth: usize, + limits: Limits, + budget: &mut usize, + line_budget: &mut usize, + mappings: bool, +) -> Result { + if depth > limits.max_depth { + return Err(SourceMapError::TooDeep(limits.max_depth)); + } + let Some(raw) = raw.filter(|raw| raw.version == Some(3)) else { + return Err(SourceMapError::BadVersion); + }; + if let Some(sections) = raw.sections { + // The index has its own file name. Only its section maps describe original sources. + let mut map = SourceMap { file: raw.file, ..Default::default() }; + let sections = sections.ok_or(SourceMapError::BadSections)?; + for section in sections { + let offset = |n: Option| n.and_then(|n| u32::try_from(n).ok()).ok_or(SourceMapError::BadSections); + let (line, col) = section.offset.unwrap_or_default(); + let (line, col) = if mappings { (offset(line)?, offset(col)?) } else { (offset(line).unwrap_or(0), offset(col).unwrap_or(0)) }; + if mappings && map.sections.last().is_some_and(|(l, c, _)| (*l, *c) > (line, col)) { + return Err(SourceMapError::BadSections); + } + let (sub, external) = match (section.map, section.url) { + (Some(m), None) => (from_raw(m.map(|m| *m), depth + 1, limits, budget, line_budget, mappings)?, false), + // External maps are never fetched here. Retain their start so a lookup + // cannot leak through to the previous inline map, and count it so the + // sources it would add are reported unknown rather than absent. + (None, Some(true)) => (SourceMap::default(), true), + _ => return Err(SourceMapError::BadSections), + }; + if external { + map.external_sections = map.external_sections.saturating_add(1); + } + map.segments = map.segments.saturating_add(sub.segments); + map.sections.push((line, col, sub)); + } + return Ok(map); + } + let mut map = SourceMap { + file: raw.file, + source_root: raw.source_root, + sources: raw.sources, + sources_content: raw.sources_content, + names: raw.names.into_iter().map(Option::unwrap_or_default).collect(), + ignore_list: raw + .ignore_list + .or(raw.google_ignore_list) + .unwrap_or_default() + .into_iter() + .filter_map(|n| n.and_then(|n| u32::try_from(n).ok())) + .collect(), + ..Default::default() + }; + let m = raw.mappings.as_deref().unwrap_or_default(); + if mappings { + decode_mappings(m, &mut map, budget, line_budget, limits.max_lines)?; + } else if let Some(count) = past_sources(m, map.sources.len()) { + return Err(SourceMapError::BadMappings(count)); + } + Ok(map) +} + +/// The entry budget shared by every list in a map and its sections while the JSON is read. +struct Entries { + left: Cell, + exhausted: Cell, +} + +impl Entries { + fn take(&self) -> Result<(), E> { + let Some(left) = self.left.get().checked_sub(1) else { + self.exhausted.set(true); + return Err(E::custom("too many source-map entries")); + }; + self.left.set(left); + Ok(()) + } + + /// Return the slots of entries that won't be kept after all. Callers drop those entries + /// first, so a replaced list and its replacement are never held together. + fn give_back(&self, n: usize) { + self.left.set(self.left.get().saturating_add(n)); + } +} + +/// The fields a map is built from, read without keeping anything else. Any JSON value is +/// accepted where the format expects another kind; it reads as absent, as before. +#[derive(Default)] +struct RawMap { + version: Option, + file: Option, + source_root: Option, + sources: Vec>, + sources_content: Vec>, + names: Vec>, + /// Present even when it isn't an array, so `x_google_ignoreList` stays unused then. + ignore_list: Option>>, + google_ignore_list: Option>>, + mappings: Option, + /// `Some(None)`: present but not an array. + sections: Option>>, +} + +impl RawMap { + /// The entry slots this map and its sections hold. + fn held(&self) -> usize { + let lists = |l: &Option>>| l.as_ref().map_or(0, Vec::len); + self.sources.len() + + self.sources_content.len() + + self.names.len() + + lists(&self.ignore_list) + + lists(&self.google_ignore_list) + + held_by(&self.sections) + } +} + +fn held_by(sections: &Option>>) -> usize { + sections.iter().flatten().flatten().map(|s| 1 + s.map.iter().flatten().map(|m| m.held()).sum::()).sum() +} + +#[derive(Default)] +struct RawSection { + offset: Option<(Option, Option)>, + /// `Some(None)`: present but not an object. Boxed, so a section that isn't a map stays small. + map: Option>>, + /// Whether the URL is a string. + url: Option, +} + +/// Visitor methods that read any other kind of value, without keeping it, as the default. +macro_rules! skip { + ($de:lifetime; bool) => { fn visit_bool(self, _: bool) -> Result { Ok(Default::default()) } }; + ($de:lifetime; i64) => { fn visit_i64(self, _: i64) -> Result { Ok(Default::default()) } }; + ($de:lifetime; u64) => { fn visit_u64(self, _: u64) -> Result { Ok(Default::default()) } }; + ($de:lifetime; f64) => { fn visit_f64(self, _: f64) -> Result { Ok(Default::default()) } }; + ($de:lifetime; str) => { fn visit_str(self, _: &str) -> Result { Ok(Default::default()) } }; + ($de:lifetime; unit) => { fn visit_unit(self) -> Result { Ok(Default::default()) } }; + ($de:lifetime; seq) => { + fn visit_seq>(self, mut seq: A) -> Result { + while seq.next_element_seed(Skip)?.is_some() {} + Ok(Default::default()) + } + }; + ($de:lifetime; map) => { + fn visit_map>(self, mut map: A) -> Result { + while map.next_key_seed(Skip)?.is_some() { + map.next_value_seed(Skip)?; + } + Ok(Default::default()) + } + }; + ($de:lifetime; $($kind:ident),+) => { $(skip!($de; $kind);)+ }; +} + +/// Read a value the map doesn't keep, with the checks a full read makes (string escapes and +/// UTF-8, number range, nesting depth), so skipping it can't let a broken map through. +#[derive(Clone, Copy)] +struct Skip; + +impl<'de> DeserializeSeed<'de> for Skip { + type Value = (); + fn deserialize>(self, d: D) -> Result<(), D::Error> { + d.deserialize_any(self) + } +} + +impl<'de> Visitor<'de> for Skip { + type Value = (); + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + skip!('de; bool, i64, u64, f64, str, unit, seq, map); +} + +/// A string, or `None` for any other value. +#[derive(Clone, Copy)] +struct MaybeStr; + +impl<'de> Visitor<'de> for MaybeStr { + type Value = Option; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_str(self, s: &str) -> Result { + Ok(Some(s.to_owned())) + } + fn visit_string(self, s: String) -> Result { + Ok(Some(s)) + } + skip!('de; bool, i64, u64, f64, unit, seq, map); +} + +/// A non-negative integer, or `None` for any other value. +#[derive(Clone, Copy)] +struct MaybeU64; + +impl<'de> Visitor<'de> for MaybeU64 { + type Value = Option; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_u64(self, n: u64) -> Result { + Ok(Some(n)) + } + skip!('de; bool, i64, f64, str, unit, seq, map); +} + +/// One value read through `V`, after taking its slot from the entry budget. +struct Entry<'a, V>(&'a Entries, V); + +impl<'de, V: Visitor<'de>> DeserializeSeed<'de> for Entry<'_, V> { + type Value = V::Value; + fn deserialize>(self, d: D) -> Result { + self.0.take()?; + d.deserialize_any(self.1) + } +} + +/// A list whose entries count against the budget; any other value reads as an empty list. +struct EntryList<'a, V>(&'a Entries, V); + +impl<'de, V: Visitor<'de> + Copy> Visitor<'de> for EntryList<'_, V> { + type Value = Vec; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_seq>(self, mut seq: A) -> Result { + let mut out = Vec::new(); + while let Some(value) = seq.next_element_seed(Entry(self.0, self.1))? { + out.push(value); + } + Ok(out) + } + skip!('de; bool, i64, u64, f64, str, unit, map); +} + +impl<'de, V: Visitor<'de> + Copy> DeserializeSeed<'de> for EntryList<'_, V> { + type Value = Vec; + fn deserialize>(self, d: D) -> Result { + d.deserialize_any(self) + } +} + +/// A map object, or `None` for any other value. +#[derive(Clone, Copy)] +struct RawMapSeed<'a>(&'a Entries); + +impl<'de> Visitor<'de> for RawMapSeed<'_> { + type Value = Option; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_map>(self, mut fields: A) -> Result { + let mut raw = RawMap::default(); + // A repeated key replaces the earlier value, as it did when the whole JSON was read. + while let Some(key) = fields.next_key::()? { + match key { + Field::Version => raw.version = fields.next_value_seed(Any(MaybeU64))?, + Field::File => raw.file = fields.next_value_seed(Any(MaybeStr))?, + Field::SourceRoot => raw.source_root = fields.next_value_seed(Any(MaybeStr))?, + Field::Sources => { + self.0.give_back(std::mem::take(&mut raw.sources).len()); + raw.sources = fields.next_value_seed(EntryList(self.0, MaybeStr))?; + } + Field::SourcesContent => { + self.0.give_back(std::mem::take(&mut raw.sources_content).len()); + raw.sources_content = fields.next_value_seed(EntryList(self.0, MaybeStr))?; + } + Field::Names => { + self.0.give_back(std::mem::take(&mut raw.names).len()); + raw.names = fields.next_value_seed(EntryList(self.0, MaybeStr))?; + } + // `ignoreList` wins over `x_google_ignoreList` wherever either appears. + Field::IgnoreList => { + let unused = raw.ignore_list.take().into_iter().chain(raw.google_ignore_list.take()); + self.0.give_back(unused.map(|l| l.len()).sum()); + raw.ignore_list = Some(fields.next_value_seed(EntryList(self.0, MaybeU64))?); + } + Field::GoogleIgnoreList if raw.ignore_list.is_some() => fields.next_value_seed(Skip)?, + Field::GoogleIgnoreList => { + self.0.give_back(raw.google_ignore_list.take().map_or(0, |l| l.len())); + raw.google_ignore_list = Some(fields.next_value_seed(EntryList(self.0, MaybeU64))?); + } + Field::Mappings => raw.mappings = fields.next_value_seed(Any(MaybeStr))?, + Field::Sections => { + self.0.give_back(held_by(&raw.sections.take())); + raw.sections = Some(fields.next_value_seed(Any(Sections(self.0)))?); + } + Field::Other => fields.next_value_seed(Skip)?, + } + } + Ok(Some(raw)) + } + skip!('de; bool, i64, u64, f64, str, unit, seq); +} + +impl<'de> DeserializeSeed<'de> for RawMapSeed<'_> { + type Value = Option; + fn deserialize>(self, d: D) -> Result { + d.deserialize_any(self) + } +} + +/// Read any JSON value through `V`. +struct Any(V); + +impl<'de, V: Visitor<'de>> DeserializeSeed<'de> for Any { + type Value = V::Value; + fn deserialize>(self, d: D) -> Result { + d.deserialize_any(self.0) + } +} + +#[derive(serde::Deserialize)] +#[serde(field_identifier, rename_all = "camelCase")] +enum Field { + Version, + File, + SourceRoot, + Sources, + SourcesContent, + Names, + IgnoreList, + #[serde(rename = "x_google_ignoreList")] + GoogleIgnoreList, + Mappings, + Sections, + #[serde(other)] + Other, +} + +/// The sections array, or `None` for any other value. +struct Sections<'a>(&'a Entries); + +impl<'de> Visitor<'de> for Sections<'_> { + type Value = Option>; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_seq>(self, mut seq: A) -> Result { + let mut out = Vec::new(); + while let Some(section) = seq.next_element_seed(Entry(self.0, Section(self.0)))? { + out.push(section); + } + Ok(Some(out)) + } + skip!('de; bool, i64, u64, f64, str, unit, map); +} + +/// One section; any value that isn't an object reads as a section without an offset. +struct Section<'a>(&'a Entries); + +impl<'de> Visitor<'de> for Section<'_> { + type Value = RawSection; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_map>(self, mut fields: A) -> Result { + let mut section = RawSection::default(); + while let Some(key) = fields.next_key::()? { + match key { + SectionField::Offset => section.offset = Some(fields.next_value_seed(Any(Offset))?), + SectionField::Map => { + self.0.give_back(section.map.take().flatten().map_or(0, |m| m.held())); + section.map = Some(fields.next_value_seed(RawMapSeed(self.0))?.map(Box::new)); + } + SectionField::Url => section.url = Some(fields.next_value_seed(Any(MaybeStr))?.is_some()), + SectionField::Other => fields.next_value_seed(Skip)?, + } + } + Ok(section) + } + skip!('de; bool, i64, u64, f64, str, unit, seq); +} + +#[derive(serde::Deserialize)] +#[serde(field_identifier, rename_all = "lowercase")] +enum SectionField { + Offset, + Map, + Url, + #[serde(other)] + Other, +} + +/// A section offset's line and column; any value that isn't an object has neither. +struct Offset; + +impl<'de> Visitor<'de> for Offset { + type Value = (Option, Option); + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("any JSON value") + } + fn visit_map>(self, mut fields: A) -> Result { + let (mut line, mut column) = (None, None); + while let Some(key) = fields.next_key::()? { + match key { + OffsetField::Line => line = fields.next_value_seed(Any(MaybeU64))?, + OffsetField::Column => column = fields.next_value_seed(Any(MaybeU64))?, + OffsetField::Other => fields.next_value_seed(Skip)?, + } + } + Ok((line, column)) + } + skip!('de; bool, i64, u64, f64, str, unit, seq); +} + +#[derive(serde::Deserialize)] +#[serde(field_identifier, rename_all = "lowercase")] +enum OffsetField { + Line, + Column, + #[serde(other)] + Other, +} + +fn b64(c: u8) -> Option { + Some(match c { + b'A'..=b'Z' => i64::from(c - b'A'), + b'a'..=b'z' => i64::from(c - b'a') + 26, + b'0'..=b'9' => i64::from(c - b'0') + 52, + b'+' => 62, + b'/' => 63, + _ => return None, + }) +} + +/// Decode one VLQ field from `bytes` at `*pos`. +fn vlq(bytes: &[u8], pos: &mut usize) -> Option { + let mut result = 0u32; + let mut shift = 0u32; + loop { + let d = b64(*bytes.get(*pos)?)? as u32; + *pos += 1; + let bits = d & 31; + if bits != 0 { + if bits > u32::MAX.checked_shr(shift)? { + return None; + } + result |= bits << shift; + } + if d & 32 == 0 { + break; + } + // Redundant zero groups do not change the value. + shift = shift.saturating_add(5); + } + let magnitude = i64::from(result >> 1); + Some(match (result & 1, magnitude) { + (1, 0) => i64::from(i32::MIN), + (1, n) => -n, + _ => magnitude, + }) +} + +/// Decode mapping deltas, rejecting fields that cannot name a declared source or symbol. +fn decode_mappings(m: &str, map: &mut SourceMap, budget: &mut usize, line_budget: &mut usize, line_limit: usize) -> Result<(), SourceMapError> { + let bytes = m.as_bytes(); + let (mut src, mut ol, mut oc, mut name) = (0i64, 0i64, 0i64, 0i64); + let mut pos = 0usize; + let mut line: Vec = Vec::new(); + let mut col = 0i64; + let mut count = 0usize; + let to_u32 = |v: i64, count: usize| u32::try_from(v).map_err(|_| SourceMapError::BadMappings(count)); + while pos <= bytes.len() { + match bytes.get(pos) { + None | Some(b';') => { + if *line_budget == 0 { + return Err(SourceMapError::TooManyLines(line_limit)); + } + *line_budget -= 1; + line.sort_by_key(|s| s.generated_column); + map.lines.try_reserve(1).map_err(|_| SourceMapError::LineAllocationFailed)?; + map.lines.push(std::mem::take(&mut line)); + col = 0; + pos += 1; + continue; + } + Some(b',') => { + pos += 1; + continue; + } + _ => {} + } + if *budget == 0 { + return Err(SourceMapError::TooManySegments(count)); + } + *budget -= 1; + count += 1; + col += vlq(bytes, &mut pos).ok_or(SourceMapError::BadMappings(count))?; + let mut seg = Segment { generated_column: to_u32(col, count)?, original: None }; + if !matches!(bytes.get(pos), None | Some(b',') | Some(b';')) { + src += vlq(bytes, &mut pos).ok_or(SourceMapError::BadMappings(count))?; + ol += vlq(bytes, &mut pos).ok_or(SourceMapError::BadMappings(count))?; + oc += vlq(bytes, &mut pos).ok_or(SourceMapError::BadMappings(count))?; + let mut n = None; + if !matches!(bytes.get(pos), None | Some(b',') | Some(b';')) { + name += vlq(bytes, &mut pos).ok_or(SourceMapError::BadMappings(count))?; + n = Some(to_u32(name, count)?); + } + let source = to_u32(src, count)?; + if source as usize >= map.sources.len() || n.is_some_and(|index| index as usize >= map.names.len()) { + return Err(SourceMapError::BadMappings(count)); + } + seg.original = Some((source, to_u32(ol, count)?, to_u32(oc, count)?, n)); + } + if !matches!(bytes.get(pos), None | Some(b',') | Some(b';')) { + return Err(SourceMapError::BadMappings(count)); + } + line.push(seg); + } + map.segments = count; + Ok(()) +} + +/// The segment, counted as [`decode_mappings`] does, that names a source past the end of a list +/// of `sources`. Mappings that can't be decoded end the search: past them nothing is known. +fn past_sources(m: &str, sources: usize) -> Option { + let bytes = m.as_bytes(); + let (mut pos, mut src, mut count) = (0usize, 0i64, 0usize); + let at_end = |pos: usize| matches!(bytes.get(pos), None | Some(b',') | Some(b';')); + while pos < bytes.len() { + if matches!(bytes[pos], b',' | b';') { + pos += 1; + continue; + } + count += 1; + vlq(bytes, &mut pos)?; + if at_end(pos) { + continue; + } + src += vlq(bytes, &mut pos)?; + // A negative index is wrong too, but the deltas after it still decode. + if usize::try_from(src).is_ok_and(|src| src >= sources) { + return Some(count); + } + while !at_end(pos) { + vlq(bytes, &mut pos)?; + } + } + None +} + +#[cfg(test)] +mod tests; diff --git a/crates/sourcemap/src/tests.rs b/crates/sourcemap/src/tests.rs new file mode 100644 index 000000000..414f3b64c --- /dev/null +++ b/crates/sourcemap/src/tests.rs @@ -0,0 +1,122 @@ +use super::*; +#[test] +fn mapping_indices_must_refer_to_declared_entries() { + for mappings in ["ACAA", "AAAAC"] { + let json = serde_json::json!({"version":3,"sources":["source.js"],"names":["name"],"mappings":mappings}); + assert!(matches!(parse(json.to_string().as_bytes(), Limits::default()), Err(SourceMapError::BadMappings(1)))); + } + let valid = br#"{"version":3,"sources":[null],"names":["name"],"mappings":"AAAAA"}"#; + assert!(parse(valid, Limits::default()).is_ok()); +} + +#[test] +fn lookup_keeps_coincident_mappings_and_stops_at_an_unmapped_segment() { + let map = parse(br#"{"version":3,"sources":["a","b"],"mappings":"EAAA,ACAA,E"}"#, Limits::default()).unwrap(); + assert!(map.original_positions(0, 1).is_empty()); + let matches = map.original_positions(0, 3); + assert_eq!(matches.iter().map(|p| p.source_index).collect::>(), [0, 1]); + assert!(map.original_positions(0, 4).is_empty()); +} + +#[test] +fn relative_sources_keep_the_url_root_delimiter() { + for (root, expected) in [ + ("webpack:///", "webpack:///src/main.js"), + ("file:///", "file:///src/main.js"), + ("https://host/scripts/", "https://host/scripts/src/main.js"), + ("src", "src/src/main.js"), + ] { + let json = serde_json::json!({"version":3,"sourceRoot":root,"sources":["src/main.js"],"mappings":"AAAA"}); + let map = parse(json.to_string().as_bytes(), Limits::default()).unwrap(); + assert_eq!(map.all_sources(), [expected]); + assert_eq!(map.original_positions(0, 0)[0].source.as_deref(), Some(expected)); + } +} + +#[test] +fn decodes_and_looks_up() { + // Generated "a;b" from two lines of src.js. + let m = br#"{"version":3,"sources":["src.js"],"names":["foo"],"mappings":"AAAAA,EAAE;AACA","sourcesContent":["x\ny"]}"#; + let map = parse(m, Limits::default()).unwrap(); + assert_eq!(map.lines.len(), 2); + let p = map.original_positions(0, 1); + assert_eq!(p[0].source.as_deref(), Some("src.js")); + assert_eq!(p[0].name.as_deref(), Some("foo")); + assert_eq!((p[0].line, p[0].column), (0, 0)); + let q = map.original_positions(0, 2); + assert_eq!(q[0].column, 2); + let r = map.original_positions(1, 0); + assert_eq!(r[0].line, 1); + assert!(map.original_positions(5, 0).is_empty()); + assert_eq!(map.source_content(0), Some("x\ny")); +} + +#[test] +fn indexed_maps() { + let m = br#"{"version":3,"sections":[{"offset":{"line":0,"column":0},"map":{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA"}},{"offset":{"line":1,"column":0},"map":{"version":3,"sources":["b.js"],"names":[],"mappings":"AAAA"}}]}"#; + let map = parse(m, Limits::default()).unwrap(); + assert_eq!(map.original_positions(1, 3)[0].source.as_deref(), Some("b.js")); + assert_eq!(map.all_sources(), vec!["a.js", "b.js"]); +} + +#[test] +fn validates_index_map_shape_and_offsets() { + let inline = serde_json::json!({"version":3,"mappings":"A"}); + for sections in [ + serde_json::json!({}), + serde_json::json!([{"map":inline}]), + serde_json::json!([{"offset":{"line":-1,"column":0},"map":inline}]), + serde_json::json!([{"offset":{"line":0,"column":4294967296_u64},"map":inline}]), + serde_json::json!([{"offset":{"line":0,"column":0}}]), + serde_json::json!([{"offset":{"line":0,"column":0},"map":inline,"url":"later.map"}]), + serde_json::json!([{"offset":{"line":0,"column":2},"map":inline},{"offset":{"line":0,"column":1},"map":inline}]), + ] { + let json = serde_json::json!({"version":3,"sections":sections}).to_string(); + assert_eq!(parse(json.as_bytes(), Limits::default()), Err(SourceMapError::BadSections)); + } +} + +#[test] +fn an_external_section_ends_the_previous_inline_mapping() { + let inline = serde_json::json!({"version":3,"sources":["first.js"],"mappings":"AAAA"}); + let sections = serde_json::json!([ + {"offset":{"line":0,"column":0},"map":inline}, + {"offset":{"line":0,"column":4},"url":"external.map"}, + {"offset":{"line":1,"column":0},"map":inline} + ]); + let json = serde_json::json!({"version":3,"sections":sections}).to_string(); + let map = parse(json.as_bytes(), Limits::default()).unwrap(); + assert_eq!(map.original_positions(0, 3)[0].source.as_deref(), Some("first.js")); + assert!(map.original_positions(0, 4).is_empty()); + assert_eq!(map.original_positions(1, 0)[0].generated_column, 0); +} + +#[test] +fn vlq_signed_extremes_and_overflow() { + for (field, value) in [ + ("B", Some(i64::from(i32::MIN))), + ("+/////D", Some(i64::from(i32::MAX))), + ("//////D", Some(-i64::from(i32::MAX))), + ("ggggggE", None), + ("ggggggggggA", Some(0)), + ] { + assert_eq!(vlq(field.as_bytes(), &mut 0), value, "{field}"); + } + let map = parse(br#"{"version":3,"mappings":"+/////D,C,B"}"#, Limits::default()).unwrap(); + assert_eq!(map.lines[0].iter().map(|s| s.generated_column).collect::>(), [0, 2147483647, 2147483648]); + assert!(parse(br#"{"version":3,"mappings":"B"}"#, Limits::default()).is_err()); +} + +#[test] +fn hostile_mappings_do_not_panic() { + for m in ["", ";;;", "A", "gggggggggggggggggggggggggg", "AAAA,", "////", "AAAAAAAAAAAAAAA", "D", "AD,AA", "+", "!!"] { + let j = format!(r#"{{"version":3,"sources":[],"names":[],"mappings":"{m}"}}"#); + if let Ok(map) = parse(j.as_bytes(), Limits::default()) { + let _ = map.original_positions(0, 0); + let _ = map.original_positions(u32::MAX, u32::MAX); + } + } + let tight = Limits { max_segments: 1, ..Limits::default() }; + assert!(parse(br#"{"version":3,"sources":[],"names":[],"mappings":"A,A"}"#, tight).is_err()); + assert!(parse(b"[]", Limits::default()).is_err()); +} diff --git a/crates/sourcemap/tests/entry_budgets.rs b/crates/sourcemap/tests/entry_budgets.rs new file mode 100644 index 000000000..65ae533ba --- /dev/null +++ b/crates/sourcemap/tests/entry_budgets.rs @@ -0,0 +1,145 @@ +use craft_sourcemap::{Limits, SourceMap, SourceMapError, parse}; +use serde_json::json; + +fn with(max_entries: usize) -> Limits { + Limits { max_entries, ..Limits::default() } +} + +fn decode(value: serde_json::Value, max_entries: usize) -> Result { + parse(&serde_json::to_vec(&value).unwrap(), with(max_entries)) +} + +#[test] +fn entries_up_to_the_limit_are_kept() { + let value = json!({"version":3,"sources":["a.js","b.js"],"sourcesContent":["a();",null],"names":["x"],"mappings":"AAAAA,CCAA"}); + let map = decode(value.clone(), 5).unwrap(); + assert_eq!(map.sources, vec![Some("a.js".to_string()), Some("b.js".to_string())]); + assert_eq!(map.sources_content, vec![Some("a();".to_string()), None]); + assert_eq!(map.names, vec!["x".to_string()]); + assert_eq!(decode(value, 4), Err(SourceMapError::TooManyEntries(4))); +} + +#[test] +fn every_kind_of_entry_counts_once() { + for value in [ + json!({"version":3,"sources":["a","b","c"],"mappings":""}), + json!({"version":3,"sourcesContent":["a","b","c"],"mappings":""}), + json!({"version":3,"names":["a","b","c"],"mappings":""}), + json!({"version":3,"ignoreList":[0,1,2],"mappings":""}), + json!({"version":3,"x_google_ignoreList":[0,1,2],"mappings":""}), + // Entries that are not strings still take a slot each. + json!({"version":3,"sources":[null, 1, {"a":[1,2,3]}],"mappings":""}), + ] { + assert_eq!(decode(value.clone(), 2), Err(SourceMapError::TooManyEntries(2)), "{value}"); + assert!(decode(value.clone(), 3).is_ok(), "{value}"); + } +} + +#[test] +fn entries_a_repeated_key_replaces_give_their_slots_back() { + let json = br#"{"version":3,"mappings":"","sources":["a","b"],"sources":["c"],"names":["x"],"names":[]}"#; + let map = parse(json, with(2)).unwrap(); + assert_eq!(map.sources, vec![Some("c".to_string())]); + assert!(map.names.is_empty()); + // `ignoreList` is kept over `x_google_ignoreList`, before or after it. + let first = br#"{"version":3,"mappings":"","x_google_ignoreList":[0,0],"ignoreList":[0]}"#; + assert_eq!(parse(first, with(2)).unwrap().ignore_list, vec![0]); + let after = br#"{"version":3,"mappings":"","ignoreList":[0],"x_google_ignoreList":[0,0,0]}"#; + assert_eq!(parse(after, with(1)).unwrap().ignore_list, vec![0]); + // A replaced sections array gives back its sections and what their maps held: without that, + // the second array would need slots four and five. + let sections = br#"{"version":3,"sections":[{"offset":{"line":0,"column":0},"map":{"version":3,"sources":["a"],"mappings":""}},{"offset":{"line":1,"column":0},"url":"b.map"}],"sections":[{"offset":{"line":0,"column":0},"url":"c.map"}]}"#; + assert_eq!(parse(sections, with(3)).unwrap().sections.len(), 1); + // So does a section's replaced map: one section, then one source instead of two. + let map = br#"{"version":3,"sections":[{"offset":{"line":0,"column":0},"map":{"version":3,"sources":["a","b"],"mappings":""},"map":{"version":3,"sources":["c"],"mappings":""}}]}"#; + assert_eq!(parse(map, with(3)).unwrap().sections[0].2.sources, vec![Some("c".to_string())]); +} + +#[test] +fn sections_and_their_maps_share_the_budget() { + let section = |line: u32, name: &str| json!({"offset":{"line":line,"column":0},"map":{"version":3,"sources":[name],"mappings":"AAAA"}}); + let value = json!({"version":3,"sections":[section(0, "a.js"), section(1, "b.js")]}); + // Two sections and one source in each. + assert_eq!(decode(value.clone(), 4).unwrap().sections.len(), 2); + assert_eq!(decode(value, 3), Err(SourceMapError::TooManyEntries(3))); + // Sections without a map count too, so a long list of them is refused early. + let external = json!({"offset":{"line":0,"column":0},"url":"a.map"}); + let value = json!({"version":3,"sections":[external.clone(), external.clone(), external]}); + assert_eq!(decode(value.clone(), 3).unwrap().sections.len(), 3); + assert_eq!(decode(value, 2), Err(SourceMapError::TooManyEntries(2))); + let not_sections = br#"{"version":3,"sections":[0,0,0]}"#; + assert_eq!(parse(not_sections, with(2)), Err(SourceMapError::TooManyEntries(2))); + assert_eq!(parse(not_sections, with(3)), Err(SourceMapError::BadSections)); +} + +#[test] +fn reading_stops_at_the_limit() { + // Everything after the entry that goes over the limit is never read: the broken tail would + // otherwise be reported as bad JSON. + let json = br#"{"version":3,"sources":["a","b","c","d" this is not JSON"#; + assert_eq!(parse(json, with(2)), Err(SourceMapError::TooManyEntries(2))); + assert!(matches!(parse(json, Limits::default()), Err(SourceMapError::BadJson(_)))); +} + +#[test] +fn unknown_fields_are_skipped_without_counting() { + let value = json!({"version":3,"x_vendor":[1,2,3,4,5,6,7,8],"sources":["a.js"],"mappings":"AAAA"}); + assert_eq!(decode(value, 1).unwrap().sources.len(), 1); +} + +#[test] +fn values_the_map_does_not_keep_are_still_checked() { + let deep = format!("{{\"version\":3,\"mappings\":\"\",\"x\":{}{}}}", "[".repeat(200), "]".repeat(200)); + for json in [ + br#"{"version":3,"mappings":"","x":"\ud800"}"#.as_slice(), + br#"{"version":3,"mappings":"","sources":{"a":"\udc00"}}"#, + br#"{"version":3,"mappings":"","x":1e400}"#, + br#"{"version":3,"mappings":"","sources":[{"a":1e400}]}"#, + b"{\"version\":3,\"mappings\":\"\",\"x\":\"\xff\"}", + br#"{"version":3,"mappings":"","x":[1,]}"#, + deep.as_bytes(), + ] { + let got = parse(json, Limits::default()); + let full = serde_json::from_slice::(json).unwrap_err().to_string(); + assert_eq!(got, Err(SourceMapError::BadJson(full)), "{}", String::from_utf8_lossy(json)); + } +} + +#[test] +fn a_hostile_map_of_empty_names_is_refused_by_default() { + // About 21 million empty strings fit in the 64 MiB a map may have. + let limit = Limits::default().max_entries; + let names = vec!["\"\""; limit + 1].join(","); + let json = format!("{{\"version\":3,\"mappings\":\"\",\"names\":[{names}]}}").into_bytes(); + assert_eq!(parse(&json, Limits::default()), Err(SourceMapError::TooManyEntries(limit))); + // The same map is well formed: with room for every name it reads. + assert_eq!(parse(&json, with(limit + 1)).unwrap().names.len(), limit + 1); +} + +#[test] +fn sources_are_read_from_a_map_with_broken_mappings_or_offsets() { + use craft_sourcemap::parse_sources; + let bad = br#"{"version":3,"sourceRoot":"src","sources":["a.js"],"sourcesContent":["a();"],"names":["x"],"mappings":"!!"}"#; + assert_eq!(parse(bad, Limits::default()), Err(SourceMapError::BadMappings(1))); + let map = parse_sources(bad, Limits::default()).unwrap(); + assert_eq!((map.source_path(0).as_deref(), map.sources_content.len(), map.names.len(), map.lines.len()), (Some("src/a.js"), 1, 1, 0)); + let unordered = br#"{"version":3,"sections":[{"offset":{"line":2,"column":0},"map":{"version":3,"sources":["a.js"],"mappings":"AAAA"}},{"offset":{"line":-1,"column":0},"map":{"version":3,"sources":["b.js"],"mappings":""}},{"offset":{"line":0,"column":0},"map":{"version":3,"sources":["c.js"],"mappings":"!"}}]}"#; + assert_eq!(parse(unordered, Limits::default()), Err(SourceMapError::BadSections)); + let map = parse_sources(unordered, Limits::default()).unwrap(); + assert_eq!(map.source_inventory(Default::default()).sources, vec!["a.js".to_string(), "b.js".to_string(), "c.js".to_string()]); + // Past mappings that can't be decoded, the indices aren't known. + assert_eq!(parse_sources(br#"{"version":3,"sources":["a"],"mappings":"AAAA,!,ACAA"}"#, Limits::default()).unwrap().sources.len(), 1); + // What a section holds must still be known, and the version and limits still apply. + for (json, limit, err) in [ + (br#"{"version":3,"sections":[{"offset":{"line":0,"column":0}}]}"#.as_slice(), 9, SourceMapError::BadSections), + (br#"{"version":3,"sections":{}}"#, 9, SourceMapError::BadSections), + (br#"{"version":3,"sections":[{"offset":{"line":0,"column":0},"map":{"version":2,"sources":["a"]}}]}"#, 9, SourceMapError::BadVersion), + (br#"{"version":3,"sources":["a","b"],"mappings":"!"}"#, 1, SourceMapError::TooManyEntries(1)), + // Mappings that name a source past the end of the list show it is short. + (br#"{"version":3,"mappings":"AAAA"}"#, 9, SourceMapError::BadMappings(1)), + (br#"{"version":3,"sources":["a"],"mappings":"AAAA;ACAA,!"}"#, 9, SourceMapError::BadMappings(2)), + (br#"{"version":3,"sources":["a"],"mappings":"AAAA,ADAA,AEAA"}"#, 9, SourceMapError::BadMappings(3)), + ] { + assert_eq!(parse_sources(json, with(limit)), Err(err), "{}", String::from_utf8_lossy(json)); + } +} diff --git a/crates/sourcemap/tests/external_sections.rs b/crates/sourcemap/tests/external_sections.rs new file mode 100644 index 000000000..643cd52b1 --- /dev/null +++ b/crates/sourcemap/tests/external_sections.rs @@ -0,0 +1,84 @@ +//! An index-map section that points at an external map (`url`) adds no sources here, but its +//! sources are unknown rather than absent: the inventory says how many such sections it saw. + +use craft_sourcemap::{InventoryLimits, Limits, SourceMap, parse, parse_sources}; +use serde_json::{Value, json}; + +fn decode(value: Value) -> SourceMap { + parse(&serde_json::to_vec(&value).unwrap(), Limits::default()).unwrap() +} + +/// An external section adds no sources but is counted, so the inventory can say part of the map +/// was never read. +#[test] +fn an_external_section_is_counted_and_adds_no_sources() { + let map = decode(json!({ + "version": 3, + "sections": [ + {"offset": {"line": 0, "column": 0}, "map": {"version": 3, "sources": ["a.js"], "mappings": ""}}, + {"offset": {"line": 10, "column": 0}, "url": "vendor.js.map"} + ] + })); + assert_eq!(map.all_sources(), ["a.js"]); + assert_eq!(map.external_sections, 1); + let inventory = map.source_inventory(InventoryLimits::default()); + assert_eq!(inventory.sources, ["a.js"]); + assert!(!inventory.truncated); + assert_eq!(inventory.external_sections, 1); +} + +/// The count reaches an external section inside a nested index map. +#[test] +fn external_sections_are_counted_through_nested_index_maps() { + let map = decode(json!({ + "version": 3, + "sections": [ + {"offset": {"line": 0, "column": 0}, "map": {"version": 3, "sections": [ + {"offset": {"line": 0, "column": 0}, "map": {"version": 3, "sources": ["a.js"], "mappings": ""}}, + {"offset": {"line": 4, "column": 0}, "url": "inner.js.map"} + ]}}, + {"offset": {"line": 20, "column": 0}, "url": "outer.js.map"} + ] + })); + assert_eq!(map.all_sources(), ["a.js"]); + assert_eq!(map.source_inventory(InventoryLimits::default()).external_sections, 2); +} + +/// A map with only inline sections reports nothing unread. +#[test] +fn an_inline_only_map_counts_no_external_sections() { + let map = decode(json!({ + "version": 3, + "sections": [{"offset": {"line": 0, "column": 0}, "map": {"version": 3, "sources": ["a.js"], "mappings": ""}}] + })); + assert_eq!(map.source_inventory(InventoryLimits::default()).external_sections, 0); +} + +/// A map read for its sources alone (its mappings are refused) still says an external section +/// left part of the list unread. +#[test] +fn a_sources_only_read_still_counts_external_sections() { + let bytes = serde_json::to_vec(&json!({ + "version": 3, + "sections": [ + {"offset": {"line": 0, "column": 0}, "map": {"version": 3, "sources": ["a.js"]}}, + {"offset": {"line": 8, "column": 0}, "url": "vendor.js.map"} + ] + })) + .unwrap(); + let map = parse_sources(&bytes, Limits::default()).unwrap(); + assert_eq!(map.source_inventory(InventoryLimits::default()).external_sections, 1); +} + +/// The count spends no inventory budget: a map with many external sections still retains its +/// inline sources in full. +#[test] +fn many_external_sections_do_not_spend_the_source_budget() { + let mut sections: Vec = (0..1_000).map(|i| json!({"offset": {"line": i, "column": 0}, "url": format!("{i}.map")})).collect(); + sections.push(json!({"offset": {"line": 1_000, "column": 0}, "map": {"version": 3, "sources": ["a.js", "b.js"], "mappings": ""}})); + let map = decode(json!({"version": 3, "sections": sections})); + let inventory = map.source_inventory(InventoryLimits { max_sources: 2, max_bytes: 16 }); + assert_eq!(inventory.sources, ["a.js", "b.js"]); + assert!(!inventory.truncated); + assert_eq!(inventory.external_sections, 1_000); +} diff --git a/crates/sourcemap/tests/inventory_budgets.rs b/crates/sourcemap/tests/inventory_budgets.rs new file mode 100644 index 000000000..7491108e4 --- /dev/null +++ b/crates/sourcemap/tests/inventory_budgets.rs @@ -0,0 +1,104 @@ +use craft_sourcemap::{InventoryLimits, Limits, SourceMap, parse}; +use serde_json::{Value, json}; + +fn decode(value: Value) -> SourceMap { + parse(&serde_json::to_vec(&value).unwrap(), Limits::default()).unwrap() +} + +#[test] +fn all_sources_bounds_expanded_path_bytes_before_collecting() { + let root = "r".repeat(2 * 1024 * 1024); + let bytes = serde_json::to_vec(&json!({ + "version": 3, "sourceRoot": root, "sources": vec!["/x.js"; 40], "mappings": "" + })) + .unwrap(); + let map = parse(&bytes, Limits::default()).unwrap(); + let sources = map.all_sources(); + assert!(sources.iter().map(String::len).sum::() <= 64 * 1024 * 1024); + assert_eq!(sources.len(), 31); + assert!(sources.iter().all(|source| source.ends_with("//x.js"))); +} + +#[test] +fn repeated_large_roots_stop_before_relative_and_absolute_looking_paths_expand() { + for source in ["x.js", "/x.js", "https://example.test/x.js"] { + let bytes = serde_json::to_vec(&json!({ + "version": 3, "sourceRoot": "r".repeat(1024 * 1024), + "sources": vec![source; 10_000], "mappings": "" + })) + .unwrap(); + assert!(bytes.len() < 2 * 1024 * 1024); + let map = parse(&bytes, Limits::default()).unwrap(); + let inventory = map.source_inventory(InventoryLimits { max_sources: 5000, max_bytes: 2 * 1024 * 1024 }); + assert_eq!(inventory.sources.len(), 1); + assert_eq!(inventory.sources[0].len(), 1024 * 1024 + 1 + source.len()); + assert!(inventory.sources[0].ends_with(source)); + assert!(inventory.truncated); + } +} + +#[test] +fn byte_limits_preserve_complete_utf8_identities_at_the_exact_boundary() { + let map = decode(json!({"version": 3, "sourceRoot": "é/", "sources": ["東京.js", "東京.js", null], "mappings": ""})); + let expected = "é/東京.js"; + let limits = InventoryLimits { max_sources: 2, max_bytes: 2 * expected.len() }; + let exact = map.source_inventory(limits); + assert_eq!(exact.sources, [expected, expected]); + assert!(!exact.truncated); + let short = map.source_inventory(InventoryLimits { max_bytes: limits.max_bytes - 1, ..limits }); + assert_eq!(short.sources, [expected]); + assert!(short.truncated); + let too_small = map.source_inventory(InventoryLimits { max_bytes: expected.len() - 1, ..limits }); + assert!(too_small.sources.is_empty()); + assert!(too_small.truncated); +} + +#[test] +fn entry_limits_count_empty_paths_but_not_null_sources() { + let map = decode(json!({"version": 3, "sourceRoot": "", "sources": [null, "", "", null], "mappings": ""})); + let exact = map.source_inventory(InventoryLimits { max_sources: 2, max_bytes: 0 }); + assert_eq!(exact.sources, ["", ""]); + assert!(!exact.truncated); + let one = map.source_inventory(InventoryLimits { max_sources: 1, max_bytes: 0 }); + assert_eq!(one.sources, [""]); + assert!(one.truncated); + let zero = map.source_inventory(InventoryLimits { max_sources: 0, max_bytes: 0 }); + assert!(zero.sources.is_empty()); + assert!(zero.truncated); + let absent = decode(json!({"version": 3, "sources": [null], "mappings": ""})); + assert!(!absent.source_inventory(InventoryLimits { max_sources: 0, max_bytes: 0 }).truncated); +} + +#[test] +fn indexed_sections_share_entry_and_byte_limits_in_source_order() { + let map = decode(json!({"version": 3, "sourceRoot": "outer", "sections": [ + {"offset": {"line": 0, "column": 0}, "map": { + "version": 3, "sourceRoot": "src", "sources": [null, "/first.js"], "mappings": "" + }}, + {"offset": {"line": 1, "column": 0}, "url": "external.map"}, + {"offset": {"line": 2, "column": 0}, "map": {"version": 3, "sections": [ + {"offset": {"line": 0, "column": 0}, "map": { + "version": 3, "sourceRoot": "file:///", "sources": ["second.js", "third.js"], "mappings": "" + }} + ]}} + ]})); + let expected = ["src//first.js", "file:///second.js", "file:///third.js"]; + let complete = map.source_inventory(InventoryLimits { max_sources: 3, max_bytes: expected.iter().map(|s| s.len()).sum() }); + assert_eq!(complete.sources, expected); + assert!(!complete.truncated); + let bytes = map.source_inventory(InventoryLimits { max_sources: 3, max_bytes: expected[0].len() + expected[1].len() }); + assert_eq!(bytes.sources, expected[..2]); + assert!(bytes.truncated); + let entries = map.source_inventory(InventoryLimits { max_sources: 1, max_bytes: 100 }); + assert_eq!(entries.sources, expected[..1]); + assert!(entries.truncated); +} + +#[test] +fn an_oversized_path_stops_the_prefix_without_shortening_or_skipping_identities() { + let map = decode(json!({"version": 3, "sources": ["a.js", "b".repeat(40), "c.js"], "mappings": ""})); + let inventory = map.source_inventory(InventoryLimits { max_sources: 3, max_bytes: 8 }); + assert_eq!(inventory.sources, ["a.js"]); + assert!(inventory.truncated); + assert_eq!(map.source_path(1).unwrap(), "b".repeat(40)); +} diff --git a/crates/sourcemap/tests/line_budgets.rs b/crates/sourcemap/tests/line_budgets.rs new file mode 100644 index 000000000..f987cd765 --- /dev/null +++ b/crates/sourcemap/tests/line_budgets.rs @@ -0,0 +1,72 @@ +use craft_sourcemap as sourcemap; +use craft_sourcemap::{Limits, SourceMapError}; +use serde_json::{Value, json}; + +fn decode(value: Value, limits: Limits) -> Result { + sourcemap::parse(&serde_json::to_vec(&value).unwrap(), limits) +} + +fn map(mappings: &str) -> Value { + json!({"version":3,"sources":["input.js"],"names":[],"mappings":mappings}) +} + +#[test] +fn empty_lines_spend_the_default_budget_even_with_no_segments() { + let limits = Limits { max_segments: 0, ..Limits::default() }; + assert_eq!(decode(map(&";".repeat(1_000_000)), limits), Err(SourceMapError::TooManyLines(1_000_000))); +} + +#[test] +fn exact_and_zero_line_limits_include_the_final_empty_line() { + let limits = Limits { max_lines: 3, max_segments: 0, ..Limits::default() }; + let parsed = decode(map(";;"), limits).unwrap(); + assert_eq!(parsed.lines.len(), 3); + assert_eq!(parsed.segments, 0); + assert_eq!(decode(map(";;;"), limits), Err(SourceMapError::TooManyLines(3))); + assert_eq!(decode(map(""), Limits { max_lines: 0, ..limits }), Err(SourceMapError::TooManyLines(0))); + assert_eq!(decode(map(""), Limits { max_lines: 1, ..limits }).unwrap().lines.len(), 1); +} + +#[test] +fn nested_sections_share_one_generated_line_budget() { + let value = json!({"version":3,"sections":[ + {"offset":{"line":0,"column":0},"map":map(";")}, + {"offset":{"line":2,"column":0},"map":{"version":3,"sections":[ + {"offset":{"line":0,"column":0},"map":map(";")} + ]}} + ]}); + let limits = Limits { max_lines: 3, max_segments: 0, ..Limits::default() }; + assert_eq!(decode(value.clone(), limits), Err(SourceMapError::TooManyLines(3))); + let parsed = decode(value, Limits { max_lines: 4, ..limits }).unwrap(); + assert_eq!(parsed.sections[0].2.lines.len(), 2); + assert_eq!(parsed.sections[1].2.sections[0].2.lines.len(), 2); +} + +#[test] +fn external_sections_do_not_consume_undecoded_lines() { + let value = json!({"version":3,"sections":[ + {"offset":{"line":0,"column":0},"url":"other.map"}, + {"offset":{"line":2,"column":0},"map":map("")} + ]}); + let parsed = decode(value, Limits { max_lines: 1, max_segments: 0, ..Limits::default() }).unwrap(); + assert!(parsed.sections[0].2.lines.is_empty()); + assert_eq!(parsed.sections[1].2.lines.len(), 1); +} + +#[test] +fn positions_after_empty_lines_keep_their_coordinates() { + let parsed = decode(map("AAAA;;AACA"), Limits { max_lines: 3, max_segments: 2, ..Limits::default() }).unwrap(); + assert_eq!(parsed.lines.len(), 3); + assert!(parsed.original_positions(1, 0).is_empty()); + let position = &parsed.original_positions(2, 0)[0]; + assert_eq!(position.source.as_deref(), Some("input.js")); + assert_eq!((position.line, position.column), (1, 0)); +} + +#[test] +fn line_and_segment_limits_are_independent() { + let limits = Limits { max_lines: 10, max_segments: 1, ..Limits::default() }; + assert!(matches!(decode(map("A,A"), limits), Err(SourceMapError::TooManySegments(_)))); + assert_eq!(decode(map(";"), Limits { max_lines: 1, max_segments: 0, ..limits }), Err(SourceMapError::TooManyLines(1))); + assert_eq!(decode(map(";"), Limits { max_lines: 2, max_segments: 0, ..limits }).unwrap().segments, 0); +} diff --git a/crates/sourcemap/tests/root_prefix.rs b/crates/sourcemap/tests/root_prefix.rs new file mode 100644 index 000000000..fd8a8a814 --- /dev/null +++ b/crates/sourcemap/tests/root_prefix.rs @@ -0,0 +1,80 @@ +use craft_sourcemap::{Limits, SourceMap, parse}; +use serde_json::{Value, json}; + +fn decode(value: Value) -> SourceMap { + parse(&serde_json::to_vec(&value).unwrap(), Limits::default()).unwrap() +} + +#[test] +fn root_prefix_precedes_absolute_looking_sources() { + for (root, source, expected) in [ + ("webpack:///", "/src/main.js", "webpack:////src/main.js"), + ("https://example.test/build", "/src/main.js", "https://example.test/build//src/main.js"), + ("src", "https://example.test/main.js", "src/https://example.test/main.js"), + ("src/", "//example.test/main.js", "src///example.test/main.js"), + ("sources", "node:internal/main", "sources/node:internal/main"), + ] { + let map = decode(json!({"version": 3, "sourceRoot": root, "sources": [source], "mappings": "AAAA"})); + assert_eq!(map.original_positions(0, 0)[0].source.as_deref(), Some(expected), "root {root:?}, source {source:?}"); + assert_eq!(map.all_sources(), [expected]); + } +} + +#[test] +fn empty_root_keeps_the_same_identity_as_an_absent_or_null_root() { + for source in ["src/main.js", "/src/main.js", "https://example.test/main.js"] { + let mut value = json!({"version": 3, "sources": [source], "mappings": "AAAA"}); + assert_eq!(decode(value.clone()).all_sources(), [source]); + value["sourceRoot"] = Value::Null; + assert_eq!(decode(value.clone()).all_sources(), [source]); + value["sourceRoot"] = json!(""); + let map = decode(value); + assert_eq!(map.all_sources(), [source]); + assert_eq!(map.original_positions(0, 0)[0].source.as_deref(), Some(source)); + } +} + +#[test] +fn each_source_keeps_its_index_and_embedded_content() { + let map = decode(json!({ + "version": 3, "sourceRoot": "https://example.test/originals/", + "sources": ["/first.js", null, "https://other.test/third.js"], + "sourcesContent": ["first();", null, "third();"], "mappings": "AAAA,CEAA" + })); + let first = map.original_positions(0, 0); + let third = map.original_positions(0, 1); + assert_eq!(first[0].source_index, 0); + assert_eq!(third[0].source_index, 2); + assert_eq!(first[0].source.as_deref(), Some("https://example.test/originals//first.js")); + assert_eq!(third[0].source.as_deref(), Some("https://example.test/originals/https://other.test/third.js")); + assert_eq!(map.source_content(0), Some("first();")); + assert_eq!(map.source_content(2), Some("third();")); + assert_eq!(map.source_path(1), None); + assert_eq!(map.source_path(3), None); +} + +#[test] +fn indexed_maps_use_each_embedded_maps_own_root() { + let map = decode(json!({ + "version": 3, "sourceRoot": "outer", "sections": [ + {"offset": {"line": 0, "column": 3}, "map": { + "version": 3, "sourceRoot": "file:///", "sources": ["/first.js"], "mappings": "AAAA" + }}, + {"offset": {"line": 1, "column": 0}, "map": { + "version": 3, "sources": ["second.js"], "mappings": "AAAA" + }} + ] + })); + assert_eq!(map.original_positions(0, 3)[0].source.as_deref(), Some("file:////first.js")); + assert_eq!(map.original_positions(1, 0)[0].source.as_deref(), Some("second.js")); + assert_eq!(map.all_sources(), ["file:////first.js", "second.js"]); +} + +#[test] +fn relative_sources_still_preserve_url_root_delimiters() { + for (root, expected) in [("webpack:///", "webpack:///main.js"), ("file:///", "file:///main.js"), ("src", "src/main.js"), ("src/", "src/main.js")] + { + let map = decode(json!({"version": 3, "sourceRoot": root, "sources": ["main.js"], "mappings": "AAAA"})); + assert_eq!(map.all_sources(), [expected]); + } +} diff --git a/crates/sourcemap/tests/section_columns.rs b/crates/sourcemap/tests/section_columns.rs new file mode 100644 index 000000000..d3dff81cd --- /dev/null +++ b/crates/sourcemap/tests/section_columns.rs @@ -0,0 +1,24 @@ +use craft_sourcemap::{Limits, parse}; +use serde_json::json; + +#[test] +fn indexed_lookup_reports_columns_in_the_generated_file() { + let json = json!({"version":3,"sections":[{"offset":{"line":3,"column":11},"map":{"version":3,"sources":["one.js"],"mappings":"IAAA;IACA"}}]}); + let map = parse(json.to_string().as_bytes(), Limits::default()).unwrap(); + assert!(map.original_positions(3, 14).is_empty()); + let first = map.original_positions(3, 17); + assert_eq!(first[0].generated_column, 15); + assert_eq!((first[0].line, first[0].column), (0, 0)); + assert_eq!(map.original_positions(4, 4)[0].generated_column, 4); +} + +#[test] +fn nested_section_columns_are_added_only_on_each_first_line() { + for (inner_line, query_line, query_column) in [(0, 3, 18), (1, 4, 7)] { + let json = json!({"version":3,"sections":[{"offset":{"line":3,"column":11},"map":{"version":3,"sections":[{"offset":{"line":inner_line,"column":3},"map":{"version":3,"sources":["nested.js"],"mappings":"IAAA"}}]}}]}); + let map = parse(json.to_string().as_bytes(), Limits::default()).unwrap(); + let positions = map.original_positions(query_line, query_column); + assert_eq!(positions[0].generated_column, query_column); + assert_eq!(positions[0].source.as_deref(), Some("nested.js")); + } +} From 5039e49ab65a5f21d9988d544302aed98d54f94b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 14:13:51 -0500 Subject: [PATCH 75/97] Add shared WebAssembly inspection and validation reports (#2044) * wasm: Craft Anything Port Craft Anything f64ae3bf3c8863a982af1304e06de20653803968. * wasm: Compare WebAssembly exported tag parameter types (R0.5) (#441) Port Craft Anything fa4aae2e79198ece843a876512172bfb10d902e3. * wasm: Count all local declaration groups in a WebAssembly function (R3.12) (#1125) Port Craft Anything ad4d57d4ae5993e157a280b4237a0aa8a7a7fdb7. * wasm: Read WebAssembly debug URLs as length-prefixed UTF-8 names (R3.12) (#1126) Port Craft Anything 07a5f8686f63bff6d0efe19af56bf129e0fee9f7. * wasm: Compare WebAssembly body counts with all declared functions (R3.12) (#1129) Port Craft Anything 58402ab226ce1a417d250e789dce9a0613158567. * wasm: Bound WebAssembly metadata across repeated custom sections (R3.12) (#1390) Port Craft Anything 37ec5557f07eff39050b0bd448a4a52d155d130e. * wasm: Bound WebAssembly strings expanded through type and name references (R3.12) (#1540) Port Craft Anything ada52c6cce7979c386460e80e69c95cf4b82dbda. * wasm: Report top-level WebAssembly component sections (R3.12) Port Craft Anything 7d60ac9f896fc91cb623bd1666c4424e6ce944f9. * wasm: retain component_layout regression tests Source crates/formats/tests/wasm_component_layout.rs at 7d60ac9f896fc91cb623bd1666c4424e6ce944f9; imports adapted only. * wasm: retain custom_inventory_budget regression tests Source crates/formats/tests/wasm_custom_inventory_budget.rs at 37ec5557f07eff39050b0bd448a4a52d155d130e; imports adapted only. * wasm: retain reference_bytes regression tests Source crates/formats/tests/wasm_reference_bytes.rs at ada52c6cce7979c386460e80e69c95cf4b82dbda; imports adapted only. * Expose shared WebAssembly inspection and retained hostile-input tests * Split WASM section inspection and reuse regression encoders --------- Co-authored-by: Brandon Thomas Co-authored-by: Afloat <132809511+Afloat16@users.noreply.github.com> Co-authored-by: Afloat Co-authored-by: RRFZ <247457381+Plastic-time@users.noreply.github.com> --- ATTRIBUTION.md | 4 + Cargo.lock | 34 +- Cargo.toml | 1 + crates/wasm/Cargo.toml | 15 + crates/wasm/src/bytes.rs | 32 + crates/wasm/src/lib.rs | 973 ++++++++++++++++++ .../wasm/src/regressions/component_layout.rs | 42 + .../regressions/custom_inventory_budget.rs | 115 +++ .../wasm/src/regressions/reference_bytes.rs | 140 +++ crates/wasm/src/test_support.rs | 163 +++ 10 files changed, 1518 insertions(+), 1 deletion(-) create mode 100644 crates/wasm/Cargo.toml create mode 100644 crates/wasm/src/bytes.rs create mode 100644 crates/wasm/src/lib.rs create mode 100644 crates/wasm/src/regressions/component_layout.rs create mode 100644 crates/wasm/src/regressions/custom_inventory_budget.rs create mode 100644 crates/wasm/src/regressions/reference_bytes.rs create mode 100644 crates/wasm/src/test_support.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 546f3e637..13e793afd 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -141,6 +141,10 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. +## WebAssembly inspection + +`crates/wasm` extracts Craft Anything `crates/formats/src/wasm.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2`, with its checked byte-reader subset and original synthetic WASM/testkit fixtures (MIT OR Apache-2.0). Eight core-history ports preserve Brandon Thomas, Afloat and RRFZ as primary authors; component, repeated-custom-section and referenced-string regression imports retain source authors and commit references. Fixtures come from `crates/testkit/src/formats.rs` and deterministic mutation helpers from `crates/testkit/src/lib.rs`; no third-party binaries. Shared error naming and workspace wiring are subsequent changes. Existing inspection limits and report behavior are unchanged; this crate validates/inspects/renders, never executes modules. + ## Packet capture and protocol inspection `crates/pcap` extracts Craft Anything `crates/formats/src/pcap.rs`, its checked byte reader primitives and synthetic packet fixtures/regressions at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the implementation, byte reader and fixtures in `f64ae3bf3c8863a982af1304e06de20653803968`. Subsequent fixes by phatloi0010, GGWA, BFlat, Afloat, NetterSilver, Max Mittelstädt and RRFZ retain separate primary-author source-history commits with immutable source revisions. Shared error/API wiring and chrono-based timestamp formatting with exhaustive day-boundary parity tests are subsequent Dylan M. Taylor changes. No packet reassembly, decryption, live capture or app analysis policy is imported. diff --git a/Cargo.lock b/Cargo.lock index 05847f390..c1eb3006b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3366,6 +3366,16 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-wasm" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", + "wasmparser 0.261.0", + "wasmprinter", +] + [[package]] name = "craft-web-api" version = "0.1.0" @@ -12049,7 +12059,7 @@ dependencies = [ "wasmi_collections", "wasmi_core", "wasmi_ir", - "wasmparser", + "wasmparser 0.228.0", ] [[package]] @@ -12089,6 +12099,28 @@ dependencies = [ "indexmap", ] +[[package]] +name = "wasmparser" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f20f20e44f7e8aeb6744823ea9d869ede51e51be4fdaedede2852282e54d2d8" +dependencies = [ + "bitflags 2.13.2", + "indexmap", + "semver", +] + +[[package]] +name = "wasmprinter" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a21c9e3325655ba02de3e645bc8357a8b3651a2e3ada25b6dbc37560deb9b7" +dependencies = [ + "anyhow", + "termcolor", + "wasmparser 0.261.0", +] + [[package]] name = "wayland-backend" version = "0.3.17" diff --git a/Cargo.toml b/Cargo.toml index 5f38bef09..3468f29f6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -29,6 +29,7 @@ acadrust = "=0.6.6" log = "0.4" # internal: add each crate here as `craft- = { path = "crates/" }` craft-plist = { path = "crates/plist" } +craft-wasm = { path = "crates/wasm" } craft-platform = { path = "crates/platform" } craft-aep = { path = "crates/aep" } craft-affinity = { path = "crates/affinity" } diff --git a/crates/wasm/Cargo.toml b/crates/wasm/Cargo.toml new file mode 100644 index 000000000..c9a1cdcf3 --- /dev/null +++ b/crates/wasm/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-wasm" +description = "Bounded WebAssembly module/component inspection, validation reports and WAT rendering; never executes code" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde = { workspace = true } +thiserror = { workspace = true } +wasmparser = { version = "0.261", default-features = false, features = ["std", "validate", "features", "component-model", "simd"] } +wasmprinter = { version = "0.261", default-features = false, features = ["component-model"] } diff --git a/crates/wasm/src/bytes.rs b/crates/wasm/src/bytes.rs new file mode 100644 index 000000000..22c5758f8 --- /dev/null +++ b/crates/wasm/src/bytes.rs @@ -0,0 +1,32 @@ +// Checked reader subset retained from Craft Anything; MIT OR Apache-2.0. +pub(crate) struct Reader<'a> { + data: &'a [u8], +} +impl<'a> Reader<'a> { + pub fn new(data: &'a [u8]) -> Self { + Self { data } + } + pub fn u8(&self, off: usize) -> Option { + self.data.get(off).copied() + } + pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> { + self.data.get(off..off.checked_add(len)?) + } + /// Unsigned LEB128 at `off`: (value, bytes consumed). At most 10 bytes. + pub fn uleb128(&self, off: usize) -> Option<(u64, usize)> { + let mut result = 0u64; + for i in 0..10usize { + let b = self.u8(off.checked_add(i)?)?; + let payload = u64::from(b & 0x7f); + let shift = 7 * i as u32; + if shift > 0 && payload.checked_shl(shift)? >> shift != payload { + return None; + } + result |= payload << shift; + if b & 0x80 == 0 { + return Some((result, i + 1)); + } + } + None + } +} diff --git a/crates/wasm/src/lib.rs b/crates/wasm/src/lib.rs new file mode 100644 index 000000000..0c552fd21 --- /dev/null +++ b/crates/wasm/src/lib.rs @@ -0,0 +1,973 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! WebAssembly modules: validation, sections, imports, exports, functions with their signatures +//! and names, memories, tables, globals, tags, custom sections (names, producers, target features, +//! source map URL) and a text (WAT) rendering. Built on the pure-Rust `wasmparser` and +//! `wasmprinter` crates; never executes anything. + +use crate::bytes::Reader; +use WasmError as FormatError; +use serde::Serialize; +use std::collections::{BTreeMap, btree_map::Entry}; +use wasmparser::{CompositeInnerType, Encoding, ExternalKind, FuncType, KnownCustom, Name, Parser, Payload, TypeRef, Validator, WasmFeatures}; + +/// Largest module we read (256 MiB). +pub const MAX_INPUT: usize = 256 << 20; +/// Most entries kept per list. +pub const MAX_ITEMS: usize = 100_000; + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmSection { + pub id: u8, + pub name: String, + pub offset: u64, + pub size: u64, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmImport { + pub module: String, + pub name: String, + /// func, table, memory, global or tag. + pub kind: &'static str, + pub type_index: Option, + /// Function signature or a short description of the imported item. + pub signature: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmExport { + pub name: String, + pub kind: &'static str, + pub index: u32, + /// Name of the exported function from the name section, when known. + pub target_name: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmFunction { + /// Index in the function index space (imports first). + pub index: u32, + pub type_index: u32, + pub signature: String, + pub body_offset: u64, + pub body_size: u64, + pub locals: u64, + pub name: Option, + pub exported_as: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmMemory { + pub index: u32, + pub initial: u64, + pub maximum: Option, + pub shared: bool, + pub memory64: bool, + pub imported: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmTable { + pub index: u32, + pub element_type: String, + pub initial: u64, + pub maximum: Option, + pub imported: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmGlobal { + pub index: u32, + pub value_type: String, + pub mutable: bool, + pub imported: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmTag { + /// Index in the tag index space (imports first). + pub index: u32, + pub type_index: u32, + pub signature: String, + pub imported: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmCustom { + pub name: String, + pub offset: u64, + pub size: u64, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct ProducerValue { + pub name: String, + pub version: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct ProducerField { + pub field: String, + pub values: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmValidation { + pub valid: bool, + pub error: Option, + pub offset: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct WasmReport { + /// `module` or `component`. + pub encoding: &'static str, + pub version: u16, + pub size: usize, + pub validation: WasmValidation, + /// Set when the structure could not be read to the end. + pub parse_error: Option, + pub sections: Vec, + pub types: usize, + pub imports: Vec, + pub imported_functions: u32, + pub exports: Vec, + /// Functions defined in the module (imports are listed under `imports`). + pub functions: Vec, + pub memories: Vec, + pub tables: Vec, + pub globals: Vec, + pub tags: Vec, + pub start_function: Option, + pub data_segments: u32, + pub element_segments: u32, + pub data_count: Option, + pub custom_sections: Vec, + pub module_name: Option, + pub producers: Vec, + pub target_features: Vec, + pub source_mapping_url: Option, + pub external_debug_info: Option, + pub truncated: bool, + pub warnings: Vec, +} + +/// True when the bytes start with the WebAssembly magic. +pub fn is_wasm(data: &[u8]) -> bool { + data.starts_with(b"\0asm") +} + +fn sig(f: &FuncType) -> String { + let p: Vec = f.params().iter().map(|v| v.to_string()).collect(); + let r: Vec = f.results().iter().map(|v| v.to_string()).collect(); + format!("({}) -> ({})", p.join(", "), r.join(", ")) +} + +struct ReferencedStrings { + remaining: usize, + exhausted: bool, +} + +impl ReferencedStrings { + fn claim(&mut self, bytes: usize) -> bool { + if self.exhausted || bytes > self.remaining { + self.exhausted = true; + return false; + } + self.remaining -= bytes; + true + } + + fn copy(&mut self, value: &str) -> Option { + self.claim(value.len()).then(|| value.to_owned()) + } +} + +fn type_sig(types: &[Option], t: u32, cache: &mut BTreeMap, strings: &mut ReferencedStrings) -> Option { + if strings.exhausted { + return None; + } + let signature = match cache.entry(t) { + Entry::Occupied(entry) => entry.into_mut(), + Entry::Vacant(entry) => { + let value = match types.get(t as usize) { + Some(Some(f)) => sig(f), + Some(None) => format!("type {t} (not a function type)"), + None => format!("type {t} (missing)"), + }; + if !strings.claim(value.len()) { + return None; + } + entry.insert(value) + } + }; + strings.copy(signature) +} + +fn section_name(id: u8) -> &'static str { + match id { + 0 => "custom", + 1 => "type", + 2 => "import", + 3 => "function", + 4 => "table", + 5 => "memory", + 6 => "global", + 7 => "export", + 8 => "start", + 9 => "element", + 10 => "code", + 11 => "data", + 12 => "datacount", + 13 => "tag", + _ => "unknown", + } +} + +/// Read the outer component layout without interpreting the contents of embedded binaries. +fn component_sections(reader: &mut wasmparser::BinaryReader<'_>, rep: &mut WasmReport) -> Result<(), wasmparser::BinaryReaderError> { + while !reader.eof() { + if rep.sections.len() == MAX_ITEMS { + rep.truncated = true; + break; + } + let id = reader.read_u8()?; + let body = reader.read_reader()?; + let range = body.range(); + let name = match id { + 0 => format!("custom:{}", wasmparser::CustomSectionReader::new(body)?.name()), + 1 => "core module".into(), + 2 => "core instance".into(), + 3 => "core type".into(), + 4 => "component".into(), + 5 => "instance".into(), + 6 => "alias".into(), + 7 => "type".into(), + 8 => "canonical".into(), + 9 => "start".into(), + 10 => "import".into(), + 11 => "export".into(), + _ => "unknown".into(), + }; + rep.sections.push(WasmSection { id, name, offset: range.start, size: range.end.saturating_sub(range.start) }); + } + Ok(()) +} + +fn kind_name(k: ExternalKind) -> &'static str { + match k { + ExternalKind::Func | ExternalKind::FuncExact => "func", + ExternalKind::Table => "table", + ExternalKind::Memory => "memory", + ExternalKind::Global => "global", + ExternalKind::Tag => "tag", + } +} + +/// Validate with every feature enabled; the result never fails the caller. +pub fn validate(data: &[u8]) -> WasmValidation { + match Validator::new_with_features(WasmFeatures::all()).validate_all(data) { + Ok(_) => WasmValidation { valid: true, error: None, offset: None }, + Err(e) => WasmValidation { valid: false, error: Some(e.message().to_string()), offset: Some(e.offset()) }, + } +} + +/// A length-prefixed UTF-8 string at the start of a custom section payload. +fn leading_string(data: &[u8]) -> Option { + // inspect bounds the enclosing module by MAX_INPUT, including any inline source map. + wasmparser::BinaryReader::new(data, 0).read_unlimited_string().ok().map(str::to_owned) +} + +fn target_features(data: &[u8]) -> Vec { + let r = Reader::new(data); + let mut out = Vec::new(); + let Some((n, mut p)) = r.uleb128(0) else { return out }; + for _ in 0..n.min(1024) { + let Some(prefix) = r.u8(p) else { break }; + let Some((len, used)) = r.uleb128(p + 1) else { break }; + let Some(s) = usize::try_from(len).ok().and_then(|l| r.slice(p + 1 + used, l)) else { break }; + out.push(format!("{}{}", char::from(prefix), String::from_utf8_lossy(s))); + p = p + 1 + used + s.len(); + } + out +} + +fn cap(len: usize, truncated: &mut bool) -> bool { + if len >= MAX_ITEMS { + *truncated = true; + false + } else { + true + } +} +fn read_types( + r: wasmparser::TypeSectionReader<'_>, + types: &mut Vec>, + rep: &mut WasmReport, +) -> Result<(), wasmparser::BinaryReaderError> { + for rg in r { + for st in rg?.into_types() { + if types.len() >= MAX_ITEMS { + rep.truncated = true; + break; + } + types.push(match st.composite_type.inner { + CompositeInnerType::Func(f) => Some(f), + _ => None, + }); + } + } + rep.types = types.len(); + + Ok(()) +} +fn read_custom(c: wasmparser::CustomSectionReader<'_>, rep: &mut WasmReport, fn_names: &mut BTreeMap, producer_values: &mut usize) { + if cap(rep.custom_sections.len(), &mut rep.truncated) { + let range = c.range(); + rep.custom_sections.push(WasmCustom { name: c.name().to_string(), offset: range.start, size: range.end.saturating_sub(range.start) }); + } + match c.name() { + "sourceMappingURL" => rep.source_mapping_url = leading_string(c.data()), + "external_debug_info" => rep.external_debug_info = leading_string(c.data()), + "target_features" => rep.target_features = target_features(c.data()), + _ => {} + } + match c.as_known() { + KnownCustom::Name(names) => { + // A damaged name section is reported but does not stop the rest. + for (i, sub) in names.into_iter().take(65).enumerate() { + if i == 64 { + rep.truncated = true; + break; + } + let Ok(sub) = sub else { + rep.warnings.push("the name section is damaged".into()); + break; + }; + match sub { + Name::Module { name, .. } => rep.module_name = Some(name.to_string()), + Name::Function(map) => { + for (i, n) in map.into_iter().take(MAX_ITEMS + 1).enumerate() { + if i == MAX_ITEMS { + rep.truncated = true; + break; + } + match n { + Ok(n) => { + if let Some(name) = fn_names.get_mut(&n.index) { + // Repeated sections may replace an already retained name at the limit. + *name = n.name.to_string(); + } else if cap(fn_names.len(), &mut rep.truncated) { + fn_names.insert(n.index, n.name.to_string()); + } + } + Err(_) => { + rep.warnings.push("a function name entry is damaged".into()); + break; + } + } + } + } + _ => {} + } + } + } + KnownCustom::Producers(p) => { + for (i, f) in p.into_iter().take(65).enumerate() { + if i == 64 || !cap(rep.producers.len(), &mut rep.truncated) { + rep.truncated = true; + break; + } + let Ok(f) = f else { + rep.warnings.push("the producers section is damaged".into()); + break; + }; + let mut values = Vec::new(); + for (i, value) in f.values.into_iter().take(65).enumerate() { + if i == 64 || !cap(*producer_values, &mut rep.truncated) { + rep.truncated = true; + break; + } + if let Ok(value) = value { + values.push(ProducerValue { name: value.name.to_string(), version: value.version.to_string() }); + *producer_values += 1; + } + } + rep.producers.push(ProducerField { field: f.name.to_string(), values }); + } + } + _ => {} + } +} + +fn read_code( + body: wasmparser::FunctionBody<'_>, + types: &[Option], + func_types: &[u32], + code_index: &mut u32, + rep: &mut WasmReport, + type_signatures: &mut BTreeMap, + strings: &mut ReferencedStrings, +) -> Result<(), wasmparser::BinaryReaderError> { + let ti = func_types.get(*code_index as usize).copied(); + let mut locals = 0u64; + let lr = body.get_locals_reader()?; + for l in lr { + let (n, _) = l?; + locals = locals.saturating_add(u64::from(n)); + } + let range = body.range(); + if cap(rep.functions.len(), &mut rep.truncated) { + let signature = match ti { + Some(t) => type_sig(types, t, type_signatures, strings), + None => strings.copy("no matching function section entry"), + }; + if let Some(signature) = signature { + rep.functions.push(WasmFunction { + index: rep.imported_functions.saturating_add(*code_index), + type_index: ti.unwrap_or(u32::MAX), + signature, + body_offset: range.start, + body_size: range.end.saturating_sub(range.start), + locals, + name: None, + exported_as: Vec::new(), + }); + } + } + *code_index = code_index.saturating_add(1); + + Ok(()) +} +fn read_functions( + r: wasmparser::FunctionSectionReader<'_>, + func_types: &mut Vec, + declared_functions: &mut u32, + rep: &mut WasmReport, +) -> Result<(), wasmparser::BinaryReaderError> { + *declared_functions = r.count(); + for t in r { + if func_types.len() >= MAX_ITEMS { + rep.truncated = true; + break; + } + func_types.push(t?); + } + + Ok(()) +} + +/// Read a module. Fails only when the bytes are not WebAssembly at all or too large; structural +/// damage is reported in `parse_error` and `validation`. +pub fn inspect(data: &[u8]) -> Result { + if data.len() > MAX_INPUT { + return Err(FormatError::TooLarge(format!("{} bytes; the limit is {MAX_INPUT}", data.len()))); + } + if !is_wasm(data) { + return Err(FormatError::Malformed("no WebAssembly magic (\\0asm)".into())); + } + let mut rep = WasmReport { + encoding: "module", + version: 0, + size: data.len(), + validation: validate(data), + parse_error: None, + sections: Vec::new(), + types: 0, + imports: Vec::new(), + imported_functions: 0, + exports: Vec::new(), + functions: Vec::new(), + memories: Vec::new(), + tables: Vec::new(), + globals: Vec::new(), + tags: Vec::new(), + start_function: None, + data_segments: 0, + element_segments: 0, + data_count: None, + custom_sections: Vec::new(), + module_name: None, + producers: Vec::new(), + target_features: Vec::new(), + source_mapping_url: None, + external_debug_info: None, + truncated: false, + warnings: Vec::new(), + }; + let mut types: Vec> = Vec::new(); + let mut func_types: Vec = Vec::new(); + let mut fn_names: BTreeMap = BTreeMap::new(); + let mut producer_values = 0usize; + let mut imported_tables = 0u32; + let mut imported_memories = 0u32; + let mut imported_globals = 0u32; + let mut imported_tags = 0u32; + let mut declared_functions = 0; + let mut code_index = 0u32; + // Type and name references can expand a small module into much larger display strings. + // Charge both the signature cache and every retained copy before allocating that copy. + let reference_budget = (64 << 20).max(data.len().saturating_mul(3)); + let mut strings = ReferencedStrings { remaining: reference_budget, exhausted: false }; + let mut type_signatures = BTreeMap::new(); + + let result: Result<(), wasmparser::BinaryReaderError> = (|| { + for payload in Parser::new(0).parse_all(data) { + let payload = payload?; + if let Some((id, range)) = payload.as_section() + && cap(rep.sections.len(), &mut rep.truncated) + { + let name = match &payload { + Payload::CustomSection(c) => format!("custom:{}", c.name()), + _ => section_name(id).to_string(), + }; + rep.sections.push(WasmSection { id, name, offset: range.start, size: range.end.saturating_sub(range.start) }); + } + match payload { + Payload::Version { num, encoding, range } => { + rep.version = num; + if encoding == Encoding::Component { + rep.encoding = "component"; + rep.warnings.push("this is a component, not a core module; only validation and the top-level layout are reported".into()); + if let Some(body) = usize::try_from(range.end).ok().and_then(|end| data.get(end..)) { + component_sections(&mut wasmparser::BinaryReader::new(body, range.end), &mut rep)?; + } + break; + } + } + Payload::TypeSection(r) => { + read_types(r, &mut types, &mut rep)?; + } + Payload::ImportSection(r) => { + for imp in r.into_imports() { + let imp = imp?; + let (kind, type_index, signature) = match imp.ty { + TypeRef::Func(t) | TypeRef::FuncExact(t) => { + rep.imported_functions = rep.imported_functions.saturating_add(1); + let signature = + if rep.imports.len() < MAX_ITEMS { type_sig(&types, t, &mut type_signatures, &mut strings) } else { None }; + ("func", Some(t), signature) + } + TypeRef::Table(t) => { + if cap(rep.tables.len(), &mut rep.truncated) { + rep.tables.push(WasmTable { + index: imported_tables, + element_type: format!("{:?}", t.element_type), + initial: t.initial, + maximum: t.maximum, + imported: true, + }); + } + imported_tables = imported_tables.saturating_add(1); + ("table", None, Some(format!("table {} min {}", format!("{:?}", t.element_type).to_lowercase(), t.initial))) + } + TypeRef::Memory(m) => { + if cap(rep.memories.len(), &mut rep.truncated) { + rep.memories.push(WasmMemory { + index: imported_memories, + initial: m.initial, + maximum: m.maximum, + shared: m.shared, + memory64: m.memory64, + imported: true, + }); + } + imported_memories = imported_memories.saturating_add(1); + ("memory", None, Some(format!("memory min {} pages", m.initial))) + } + TypeRef::Global(g) => { + if cap(rep.globals.len(), &mut rep.truncated) { + rep.globals.push(WasmGlobal { + index: imported_globals, + value_type: g.content_type.to_string(), + mutable: g.mutable, + imported: true, + }); + } + imported_globals = imported_globals.saturating_add(1); + ("global", None, Some(format!("{}{}", if g.mutable { "mut " } else { "" }, g.content_type))) + } + TypeRef::Tag(t) => { + let keep_tag = cap(rep.tags.len(), &mut rep.truncated); + let signature = if rep.imports.len() < MAX_ITEMS { + type_sig(&types, t.func_type_idx, &mut type_signatures, &mut strings) + } else { + None + }; + if keep_tag { + let tag_signature = match &signature { + Some(value) => strings.copy(value), + None => type_sig(&types, t.func_type_idx, &mut type_signatures, &mut strings), + }; + if let Some(signature) = tag_signature { + rep.tags.push(WasmTag { index: imported_tags, type_index: t.func_type_idx, signature, imported: true }); + } + } + // The import list and tag list are capped independently. + imported_tags = imported_tags.saturating_add(1); + ("tag", Some(t.func_type_idx), signature) + } + }; + if cap(rep.imports.len(), &mut rep.truncated) + && let Some(signature) = signature + { + rep.imports.push(WasmImport { module: imp.module.to_string(), name: imp.name.to_string(), kind, type_index, signature }); + } + } + } + Payload::FunctionSection(r) => { + read_functions(r, &mut func_types, &mut declared_functions, &mut rep)?; + } + Payload::TableSection(r) => { + for (i, t) in r.into_iter().enumerate() { + let t = t?; + if !cap(rep.tables.len(), &mut rep.truncated) { + break; + } + rep.tables.push(WasmTable { + index: imported_tables.saturating_add(u32::try_from(i).unwrap_or(u32::MAX)), + element_type: format!("{:?}", t.ty.element_type), + initial: t.ty.initial, + maximum: t.ty.maximum, + imported: false, + }); + } + } + Payload::MemorySection(r) => { + for (i, m) in r.into_iter().enumerate() { + let m = m?; + if !cap(rep.memories.len(), &mut rep.truncated) { + break; + } + rep.memories.push(WasmMemory { + index: imported_memories.saturating_add(u32::try_from(i).unwrap_or(u32::MAX)), + initial: m.initial, + maximum: m.maximum, + shared: m.shared, + memory64: m.memory64, + imported: false, + }); + } + } + Payload::TagSection(r) => { + for (i, t) in r.into_iter().enumerate() { + let t = t?; + if !cap(rep.tags.len(), &mut rep.truncated) { + break; + } + if let Some(signature) = type_sig(&types, t.func_type_idx, &mut type_signatures, &mut strings) { + rep.tags.push(WasmTag { + index: imported_tags.saturating_add(u32::try_from(i).unwrap_or(u32::MAX)), + type_index: t.func_type_idx, + signature, + imported: false, + }); + } + } + } + Payload::GlobalSection(r) => { + for (i, g) in r.into_iter().enumerate() { + let g = g?; + if !cap(rep.globals.len(), &mut rep.truncated) { + break; + } + rep.globals.push(WasmGlobal { + index: imported_globals.saturating_add(u32::try_from(i).unwrap_or(u32::MAX)), + value_type: g.ty.content_type.to_string(), + mutable: g.ty.mutable, + imported: false, + }); + } + } + Payload::ExportSection(r) => { + for e in r { + let e = e?; + if !cap(rep.exports.len(), &mut rep.truncated) { + break; + } + rep.exports.push(WasmExport { name: e.name.to_string(), kind: kind_name(e.kind), index: e.index, target_name: None }); + } + } + Payload::StartSection { func, .. } => rep.start_function = Some(func), + Payload::ElementSection(r) => rep.element_segments = r.count(), + Payload::DataCountSection { count, .. } => rep.data_count = Some(count), + Payload::DataSection(r) => rep.data_segments = r.count(), + Payload::CodeSectionEntry(body) => { + read_code(body, &types, &func_types, &mut code_index, &mut rep, &mut type_signatures, &mut strings)?; + } + Payload::CustomSection(c) => { + read_custom(c, &mut rep, &mut fn_names, &mut producer_values); + } + Payload::End(_) => {} + _ => {} + } + } + Ok(()) + })(); + if let Err(e) = result { + rep.parse_error = Some(format!("{} (at byte {})", e.message(), e.offset())); + } + // Attach names and exports to functions. + let mut exported: BTreeMap> = BTreeMap::new(); + for e in rep.exports.iter_mut() { + if e.kind == "func" { + e.target_name = fn_names.get(&e.index).and_then(|name| strings.copy(name)); + exported.entry(e.index).or_default().push(e.name.clone()); + } + } + for f in rep.functions.iter_mut() { + f.name = fn_names.get(&f.index).and_then(|name| strings.copy(name)); + f.exported_as = exported.remove(&f.index).unwrap_or_default(); + } + if declared_functions != code_index && rep.parse_error.is_none() { + rep.warnings.push(format!("{declared_functions} function declarations but {code_index} bodies")); + } + if strings.exhausted { + rep.truncated = true; + rep.warnings + .push(format!("referenced type signatures and function names exceed the {reference_budget}-byte budget; some metadata is omitted")); + } + Ok(rep) +} + +struct CappedText { + out: String, + cap: usize, + truncated: bool, +} + +impl wasmprinter::Print for CappedText { + fn write_str(&mut self, s: &str) -> std::io::Result<()> { + if self.out.len().saturating_add(s.len()) > self.cap { + let room = self.cap.saturating_sub(self.out.len()); + let mut end = room.min(s.len()); + while end > 0 && !s.is_char_boundary(end) { + end -= 1; + } + self.out.push_str(s.get(..end).unwrap_or("")); + self.truncated = true; + return Err(std::io::Error::other("output cap reached")); + } + self.out.push_str(s); + Ok(()) + } +} + +/// The text format of a module, at most `cap` bytes: (text, truncated). Only call this on +/// modules that passed [`validate`]; damaged modules are not rendered. +pub fn to_wat(data: &[u8], cap: usize) -> Result<(String, bool), String> { + let mut p = CappedText { out: String::new(), cap, truncated: false }; + let mut cfg = wasmprinter::Config::new(); + cfg.name_unnamed(false); + match cfg.print(data, &mut p) { + Ok(()) => Ok((p.out, false)), + Err(_) if p.truncated => Ok((p.out, true)), + Err(e) => Err(e.to_string()), + } +} + +/// What a JavaScript glue file says about the module. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct GlueScan { + /// String literals ending in `.wasm`. + pub wasm_references: Vec, + /// Imports (`module.name`) whose module and field names both appear in the glue. + pub matched_imports: Vec, + pub mentions_instantiate: bool, +} + +/// Scan glue JavaScript for `.wasm` literals and the import names the module expects. +pub fn scan_glue(text: &str, imports: &[WasmImport]) -> GlueScan { + let mut refs = Vec::new(); + let b = text.as_bytes(); + let mut i = 0usize; + while let Some(p) = text.get(i..).and_then(|t| t.find(".wasm")) { + let at = i + p; + let end = at + 5; + if let Some(&q) = b.get(end) + && matches!(q, b'"' | b'\'' | b'`') + { + let start = b.get(..at).and_then(|h| h.iter().rposition(|&c| c == q)).map(|s| s + 1); + if let Some(s) = start + && at - s <= 256 + && let Some(lit) = text.get(s..end) + && !lit.contains(['\n', ' ']) + && !refs.iter().any(|r: &String| r == lit) + && refs.len() < 256 + { + refs.push(lit.to_string()); + } + } + i = end; + } + let matched = imports + .iter() + .filter(|im| text.contains(im.module.as_str()) && text.contains(im.name.as_str())) + .take(MAX_ITEMS) + .map(|im| format!("{}.{}", im.module, im.name)) + .collect(); + GlueScan { wasm_references: refs, matched_imports: matched, mentions_instantiate: text.contains("WebAssembly.instantiate") } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_support::formats as fx; + + /// The output inventory limit applies to retained functions, not the local groups within one retained function. + #[test] + fn local_counts_include_groups_after_ten_thousand() { + // One valid () -> () function containing 10,001 runs of one i32 local. + let mut bytes = b"\0asm\x01\0\0\0\x01\x04\x01\x60\0\0\x03\x02\x01\0".to_vec(); + // section size = 1 + 3 + 20005, body size = 2 + 20002 + 1. + bytes.extend([10, 0xa9, 0x9c, 1, 1, 0xa5, 0x9c, 1, 0x91, 0x4e]); + for _ in 0..10_001 { + bytes.extend([1, 0x7f]); + } + bytes.push(0x0b); + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid, "{:?}", report.validation); + assert_eq!(report.functions[0].locals, 10_001); + } + + #[test] + fn debug_links_need_valid_wasm_names() { + assert_eq!(leading_string(b"\x04test").as_deref(), Some("test")); + assert!(leading_string(&[1, 0xff]).is_none()); + assert!(leading_string(b"\x81\x80\x80\x80\x80\0x").is_none()); + assert!(leading_string(b"\x04abc").is_none()); + } + + #[test] + fn inspect_preserves_long_source_mapping_urls() { + let url = format!("data:application/json;base64,{}", "A".repeat(100_000)); + let report = inspect(&fx::wasm_module_with_source_mapping_url(&url)).unwrap(); + assert_eq!(report.source_mapping_url.as_deref(), Some(url.as_str())); + } + + #[test] + fn large_function_tables_do_not_report_missing_declarations() { + fn leb(mut value: usize) -> Vec { + let mut out = Vec::new(); + while value >= 128 { + out.push((value as u8 & 0x7f) | 0x80); + value >>= 7; + } + out.push(value as u8); + out + } + let count = MAX_ITEMS + 1; + let mut bytes = b"\0asm\x01\0\0\0\x01\x04\x01\x60\0\0".to_vec(); + let mut declarations = leb(count); + declarations.resize(declarations.len() + count, 0); + let mut bodies = leb(count); + for _ in 0..count { + bodies.extend([2, 0, 0x0b]); + } + for (id, section) in [(3, declarations), (10, bodies)] { + bytes.push(id); + bytes.extend(leb(section.len())); + bytes.extend(section); + } + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid && report.truncated); + assert_eq!(report.functions.len(), MAX_ITEMS); + assert!(!report.warnings.iter().any(|s| s.contains("function declarations")), "{:?}", report.warnings); + } + + #[test] + fn reads_the_sample_module() { + let m = fx::wasm_module(); + let r = inspect(&m).unwrap(); + assert!(r.validation.valid, "{:?}", r.validation); + assert!(r.parse_error.is_none()); + assert_eq!(r.types, 3); + assert_eq!(r.imports.len(), 1); + assert_eq!(r.imports[0].signature, "(i32) -> ()"); + assert_eq!(r.imported_functions, 1); + assert_eq!(r.functions.len(), 2); + assert_eq!(r.functions[0].name.as_deref(), Some("add")); + assert_eq!(r.functions[0].signature, "(i32, i32) -> (i32)"); + assert_eq!(r.functions[0].exported_as, vec!["add"]); + assert_eq!(r.exports.len(), 3); + assert_eq!(r.memories.len(), 1); + assert_eq!(r.globals.len(), 1); + assert!(r.globals[0].mutable); + assert_eq!(r.data_segments, 1); + assert_eq!(r.module_name.as_deref(), Some("demo")); + assert_eq!(r.producers.len(), 2); + assert_eq!(r.producers[1].values[0].name, "rustc"); + assert_eq!(r.source_mapping_url.as_deref(), Some("demo.wasm.map")); + assert_eq!(r.target_features, vec!["+mutable-globals"]); + let (wat, trunc) = to_wat(&m, 1 << 20).unwrap(); + assert!(!trunc); + assert!(wat.contains("(module $demo"), "{wat}"); + assert!(wat.contains("i32.add")); + let (short, trunc) = to_wat(&m, 40).unwrap(); + assert!(trunc && short.len() <= 40); + let g = scan_glue(fx::WASM_GLUE, &r.imports); + assert_eq!(g.wasm_references, vec!["./demo.wasm"]); + assert_eq!(g.matched_imports, vec!["env.log"]); + assert!(g.mentions_instantiate); + } + + #[test] + fn damaged_modules_are_reported_not_fatal() { + let m = fx::wasm_module(); + let mut bad = m.clone(); + let len = bad.len(); + bad.truncate(len - 10); + let r = inspect(&bad).unwrap(); + assert!(!r.validation.valid); + assert!(r.parse_error.is_some()); + assert!(inspect(b"not wasm").is_err()); + } + + #[test] + fn hostile_inputs_do_not_panic() { + let m = fx::wasm_module(); + for x in crate::test_support::mutations(&m) { + if let Ok(r) = inspect(&x) + && r.validation.valid + { + let _ = to_wat(&x, 4096); + } + } + for n in 0..m.len() { + let _ = inspect(&m[..n]); + } + for seed in 0..100 { + let mut n = crate::test_support::noise(seed, 256); + n[..8].copy_from_slice(b"\0asm\x01\0\0\0"); + let _ = inspect(&n); + let _ = scan_glue(&String::from_utf8_lossy(&n), &[]); + } + } +} + +mod bytes; +#[cfg(test)] +mod test_support; + +/// Admission errors; structural damage stays in the inspection report. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum WasmError { + #[error("the file is malformed ({0})")] + Malformed(String), + #[error("too large: {0}")] + TooLarge(String), +} + +#[cfg(test)] +#[path = "regressions/component_layout.rs"] +mod component_layout; + +#[cfg(test)] +#[path = "regressions/custom_inventory_budget.rs"] +mod custom_inventory_budget; + +#[cfg(test)] +#[path = "regressions/reference_bytes.rs"] +mod reference_bytes; diff --git a/crates/wasm/src/regressions/component_layout.rs b/crates/wasm/src/regressions/component_layout.rs new file mode 100644 index 000000000..6f2f9532f --- /dev/null +++ b/crates/wasm/src/regressions/component_layout.rs @@ -0,0 +1,42 @@ +use crate::{MAX_ITEMS, inspect}; + +const COMPONENT: &[u8] = b"\0asm\x0d\0\x01\0"; + +/// Only outer sections appear, including sections after embedded binaries. +#[test] +fn lists_component_sections_without_descending_into_embedded_modules() { + let mut bytes = COMPONENT.to_vec(); + bytes.extend(b"\x00\x04\x03one"); + bytes.extend(b"\x01\x0b\0asm\x01\0\0\0\x01\x01\0"); + bytes.extend(b"\x04\x0e\0asm\x0d\0\x01\0\x00\x04\x03two"); + bytes.extend(b"\x00\x06\x05three"); + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid, "{:?}", report.validation); + let layout: Vec<_> = report.sections.iter().map(|s| (s.id, s.name.as_str(), s.offset, s.size)).collect(); + assert_eq!(layout, [(0, "custom:one", 10, 4), (1, "core module", 16, 11), (4, "component", 29, 14), (0, "custom:three", 45, 6)]); + assert!(report.functions.is_empty()); + assert!(report.parse_error.is_none()); +} + +/// A short section reports damage without losing the preceding layout. +#[test] +fn truncated_component_keeps_its_complete_prefix() { + let mut bytes = COMPONENT.to_vec(); + bytes.extend(b"\x00\x04\x03one\x01\x08\0asm"); + let report = inspect(&bytes).unwrap(); + assert_eq!(report.sections.len(), 1); + assert!(report.parse_error.is_some()); +} + +/// Component layouts use the same cap as core module layouts. +#[test] +fn component_section_limit_is_disclosed() { + let mut bytes = COMPONENT.to_vec(); + for _ in 0..=MAX_ITEMS { + bytes.extend(b"\x00\x02\x01x"); + } + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid); + assert_eq!(report.sections.len(), MAX_ITEMS); + assert!(report.truncated); +} diff --git a/crates/wasm/src/regressions/custom_inventory_budget.rs b/crates/wasm/src/regressions/custom_inventory_budget.rs new file mode 100644 index 000000000..d9c92d87e --- /dev/null +++ b/crates/wasm/src/regressions/custom_inventory_budget.rs @@ -0,0 +1,115 @@ +use crate::test_support::formats::wasm_module; +use crate::{MAX_ITEMS, inspect}; + +use crate::test_support::{leb, string}; + +fn custom(module: &mut Vec, name: &str, data: &[u8]) { + let mut body = Vec::new(); + string(&mut body, name); + body.extend(data); + module.push(0); + module.extend(leb(body.len())); + module.extend(body); +} + +fn names(module: &mut Vec, entries: &[(usize, &str)]) { + let mut map = leb(entries.len()); + for (index, name) in entries { + map.extend(leb(*index)); + string(&mut map, name); + } + let mut body = vec![1]; + body.extend(leb(map.len())); + body.extend(map); + custom(module, "name", &body); +} + +fn producers(fields: usize, values: usize) -> Vec { + let mut body = leb(fields); + for _ in 0..fields { + string(&mut body, "language"); + body.extend(leb(values)); + for _ in 0..values { + string(&mut body, "fixture"); + string(&mut body, "1"); + } + } + body +} + +#[test] +fn repeated_name_sections_share_a_limit_but_can_update_retained_functions() { + let mut bytes = b"\0asm\x01\0\0\0\x01\x04\x01\x60\0\0\x03\x02\x01\0\x0a\x04\x01\x02\0\x0b".to_vec(); + let entries: Vec<_> = (0..MAX_ITEMS).map(|index| (index, "kept")).collect(); + names(&mut bytes, &entries); + let complete = inspect(&bytes).unwrap(); + assert!(complete.validation.valid); + assert!(!complete.truncated); + assert_eq!(complete.functions[0].name.as_deref(), Some("kept")); + names(&mut bytes, &[(0, "updated"), (MAX_ITEMS, "omitted")]); + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid); + assert!(report.parse_error.is_none()); + assert!(report.truncated); + assert_eq!(report.functions[0].name.as_deref(), Some("updated")); +} + +#[test] +fn producer_values_are_bounded_across_repeated_sections() { + let mut bytes = b"\0asm\x01\0\0\0".to_vec(); + let section = producers(1, 64); + for _ in 0..MAX_ITEMS / 64 + 1 { + custom(&mut bytes, "producers", §ion); + } + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid); + assert!(report.parse_error.is_none()); + assert!(report.truncated); + assert_eq!(report.producers.iter().map(|field| field.values.len()).sum::(), MAX_ITEMS); + assert_eq!(report.producers[0].values[0].name, "fixture"); +} + +#[test] +fn empty_producer_fields_still_spend_the_global_field_limit() { + let mut bytes = b"\0asm\x01\0\0\0".to_vec(); + let section = producers(64, 0); + for _ in 0..MAX_ITEMS / 64 + 1 { + custom(&mut bytes, "producers", §ion); + } + let report = inspect(&bytes).unwrap(); + assert!(report.validation.valid); + assert_eq!(report.producers.len(), MAX_ITEMS); + assert!(report.truncated); +} + +#[test] +fn existing_per_section_limits_are_reported_as_truncation() { + for (fields, values) in [(65, 0), (1, 65)] { + let mut bytes = b"\0asm\x01\0\0\0".to_vec(); + custom(&mut bytes, "producers", &producers(fields, values)); + let report = inspect(&bytes).unwrap(); + assert!(report.truncated, "{fields} fields with {values} values"); + } + let mut bytes = b"\0asm\x01\0\0\0".to_vec(); + let mut subsections = vec![0, 2, 1, b'm']; + // Name subsection IDs must increase, including unknown extension IDs. + for id in 20..84 { + subsections.extend([id, 0]); + } + custom(&mut bytes, "name", &subsections); + let report = inspect(&bytes).unwrap(); + assert!(report.truncated); + assert_eq!(report.module_name.as_deref(), Some("m")); +} + +#[test] +fn ordinary_names_and_producers_remain_complete() { + let report = inspect(&wasm_module()).unwrap(); + assert!(report.validation.valid); + assert!(!report.truncated); + assert_eq!(report.functions[0].name.as_deref(), Some("add")); + assert_eq!(report.module_name.as_deref(), Some("demo")); + assert_eq!(report.producers.len(), 2); + assert_eq!(report.producers[1].values[0].name, "rustc"); + assert_eq!(report.exports.iter().find(|export| export.name == "add").unwrap().target_name.as_deref(), Some("add")); +} diff --git a/crates/wasm/src/regressions/reference_bytes.rs b/crates/wasm/src/regressions/reference_bytes.rs new file mode 100644 index 000000000..f5ff9a4ba --- /dev/null +++ b/crates/wasm/src/regressions/reference_bytes.rs @@ -0,0 +1,140 @@ +use crate::{WasmReport, inspect}; + +use crate::test_support::{leb, string}; + +fn section(module: &mut Vec, id: u8, body: &[u8]) { + module.push(id); + module.extend(leb(body.len())); + module.extend(body); +} + +fn shared_type(functions: usize, imports: usize, imported_tags: usize, defined_tags: usize, params: usize) -> Vec { + let mut module = b"\0asm\x01\0\0\0".to_vec(); + let mut ty = vec![1, 0x60]; + ty.extend(leb(params)); + ty.extend(std::iter::repeat_n(0x7f, params)); + ty.push(0); + section(&mut module, 1, &ty); + if imports + imported_tags > 0 { + let mut body = leb(imports + imported_tags); + for i in 0..imports + imported_tags { + string(&mut body, "env"); + string(&mut body, "item"); + if i < imports { + body.extend([0, 0]); + } else { + body.extend([4, 0, 0]); + } + } + section(&mut module, 2, &body); + } + if functions > 0 { + let mut body = leb(functions); + body.extend(std::iter::repeat_n(0, functions)); + section(&mut module, 3, &body); + } + if defined_tags > 0 { + let mut body = leb(defined_tags); + for _ in 0..defined_tags { + body.extend([0, 0]); + } + section(&mut module, 13, &body); + } + if functions > 0 { + let mut body = leb(functions); + for _ in 0..functions { + body.extend([2, 0, 0x0b]); + } + section(&mut module, 10, &body); + } + module +} + +fn derived_bytes(report: &WasmReport) -> usize { + report.imports.iter().map(|item| item.signature.len()).sum::() + + report.tags.iter().map(|item| item.signature.len()).sum::() + + report.functions.iter().map(|item| item.signature.len() + item.name.as_ref().map_or(0, String::len)).sum::() + + report.exports.iter().map(|item| item.target_name.as_ref().map_or(0, String::len)).sum::() +} + +fn bounded(module: &[u8]) -> WasmReport { + assert!(module.len() < 1 << 20); + let report = inspect(module).unwrap(); + assert!(report.parse_error.is_none()); + assert!(derived_bytes(&report) <= 64 << 20, "{} input bytes retain {} derived string bytes", module.len(), derived_bytes(&report)); + assert!(report.truncated); + assert!(report.warnings.iter().any(|warning| warning.contains("byte budget")), "{:?}", report.warnings); + report +} + +#[test] +fn repeated_function_signatures_have_a_byte_budget() { + let report = bounded(&shared_type(16_384, 0, 0, 0, 1000)); + assert!(report.validation.valid, "{:?}", report.validation); + assert!(!report.functions.is_empty()); + assert!(report.functions.len() < 16_384); + assert!( + report.functions.iter().enumerate().all(|(index, function)| function.index as usize == index && function.signature.starts_with("(i32, i32")) + ); + assert!(!report.warnings.iter().any(|warning| warning.contains("function declarations"))); +} + +#[test] +fn repeated_import_signatures_stay_bounded_even_when_validation_fails() { + let report = bounded(&shared_type(0, 16_384, 0, 0, 1000)); + assert!(!report.validation.valid); + assert!(report.validation.error.as_deref().unwrap().contains("effective type size")); + assert_eq!(report.imported_functions, 16_384); + assert!(!report.imports.is_empty()); + assert!(report.imports.len() < 16_384); +} + +#[test] +fn imported_and_defined_tags_share_the_same_budget_as_functions() { + for (functions, imports, imported_tags, defined_tags) in [(0, 0, 8192, 0), (0, 0, 0, 16_384), (4096, 4096, 4096, 4096)] { + let report = bounded(&shared_type(functions, imports, imported_tags, defined_tags, 1000)); + assert_eq!(report.imported_functions as usize, imports); + assert!(report.tags.len() < imported_tags + defined_tags); + assert!(report.tags.iter().all(|tag| tag.signature.starts_with("(i32, i32"))); + assert!(report.tags.iter().filter(|tag| !tag.imported).all(|tag| tag.index as usize >= imported_tags)); + } +} + +#[test] +fn exported_function_names_cannot_multiply_a_small_name_section() { + let mut module = shared_type(0, 1, 0, 0, 0); + let name = "λ".repeat(32_768); + let mut exports = leb(1280); + for index in 0..1280 { + string(&mut exports, &format!("export_{index}")); + exports.extend([0, 0]); + } + section(&mut module, 7, &exports); + let mut map = vec![1, 0]; + string(&mut map, &name); + let mut names = vec![4, b'n', b'a', b'm', b'e', 1]; + names.extend(leb(map.len())); + names.extend(map); + section(&mut module, 0, &names); + let report = bounded(&module); + assert!(report.validation.valid, "{:?}", report.validation); + assert_eq!(report.exports.len(), 1280); + assert!(report.exports.iter().any(|export| export.target_name.is_none())); + assert!(report.exports.iter().filter_map(|export| export.target_name.as_deref()).all(|value| value == name)); +} + +#[test] +fn ordinary_shared_signatures_and_names_remain_complete() { + let report = inspect(&shared_type(2, 2, 2, 2, 3)).unwrap(); + assert!(report.validation.valid, "{:?}", report.validation); + assert!(!report.truncated, "{:?}", report.warnings); + assert_eq!(report.imported_functions, 2); + assert_eq!(report.functions.len(), 2); + assert_eq!(report.tags.len(), 4); + assert!(report.imports.iter().all(|item| item.signature == "(i32, i32, i32) -> ()")); + assert!(report.tags.iter().all(|tag| tag.signature == "(i32, i32, i32) -> ()")); + assert_eq!(report.functions.iter().map(|function| function.index).collect::>(), [2, 3]); + assert_eq!(report.tags.iter().map(|tag| tag.index).collect::>(), [0, 1, 2, 3]); + assert!(report.tags[..2].iter().all(|tag| tag.imported)); + assert!(report.tags[2..].iter().all(|tag| !tag.imported)); +} diff --git a/crates/wasm/src/test_support.rs b/crates/wasm/src/test_support.rs new file mode 100644 index 000000000..58e7783a0 --- /dev/null +++ b/crates/wasm/src/test_support.rs @@ -0,0 +1,163 @@ +// Synthetic fixtures and mutations from Craft Anything testkit, same source revision. +/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. +pub fn noise(seed: u64, len: usize) -> Vec { + let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; + (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect() +} + +/// Every way to damage a sample used by robustness tests: truncations at many lengths and +/// single-byte corruptions spread across the file. +pub fn mutations(sample: &[u8]) -> Vec> { + let mut out = Vec::new(); + let n = sample.len(); + let step = (n / 64).max(1); + let mut len = 0; + while len < n { + out.push(sample[..len].to_vec()); + len += step; + } + for (i, seed) in (0..n).step_by(step).zip(1u64..) { + let mut m = sample.to_vec(); + let noise = noise(seed, 8); + for (j, v) in noise.iter().enumerate() { + if let Some(b) = m.get_mut(i + j) { + *b = *v; + } + } + out.push(m); + let mut m = sample.to_vec(); + if let Some(b) = m.get_mut(i) { + *b = 0xff; + } + out.push(m); + } + out +} + +pub mod formats { + fn leb(mut v: u32, out: &mut Vec) { + loop { + let b = (v & 0x7f) as u8; + v >>= 7; + if v == 0 { + out.push(b); + return; + } + out.push(b | 0x80); + } + } + + fn name(s: &str, out: &mut Vec) { + leb(s.len() as u32, out); + out.extend_from_slice(s.as_bytes()); + } + + fn section(id: u8, body: &[u8], out: &mut Vec) { + out.push(id); + leb(body.len() as u32, out); + out.extend_from_slice(body); + } + + fn custom(sname: &str, body: &[u8], out: &mut Vec) { + let mut c = Vec::new(); + name(sname, &mut c); + c.extend_from_slice(body); + section(0, &c, out); + } + + /// A small valid module: imports `env.log(i32)`, defines `add(i32,i32)->i32` and `_start`, + /// one memory, one mutable global, one data segment, exports `add`, `memory` and `_start`, and + /// carries `name`, `producers` and `sourceMappingURL` custom sections. + pub fn wasm_module() -> Vec { + wasm_module_with_source_mapping_url("demo.wasm.map") + } + + /// The sample module with a caller-provided source map URL. + pub fn wasm_module_with_source_mapping_url(url: &str) -> Vec { + let mut m = b"\0asm\x01\0\0\0".to_vec(); + section(1, &[3, 0x60, 2, 0x7f, 0x7f, 1, 0x7f, 0x60, 0, 0, 0x60, 1, 0x7f, 0], &mut m); + let mut imp = vec![1]; + name("env", &mut imp); + name("log", &mut imp); + imp.extend_from_slice(&[0, 2]); + section(2, &imp, &mut m); + section(3, &[2, 0, 1], &mut m); + section(5, &[1, 0, 1], &mut m); + section(6, &[1, 0x7f, 1, 0x41, 42, 0x0b], &mut m); + let mut exp = vec![3]; + name("add", &mut exp); + exp.extend_from_slice(&[0, 1]); + name("memory", &mut exp); + exp.extend_from_slice(&[2, 0]); + name("_start", &mut exp); + exp.extend_from_slice(&[0, 2]); + section(7, &exp, &mut m); + let add = [0u8, 0x20, 0, 0x20, 1, 0x6a, 0x0b]; + let start = [0u8, 0x41, 7, 0x10, 0, 0x0b]; + let mut code = vec![2, add.len() as u8]; + code.extend_from_slice(&add); + code.push(start.len() as u8); + code.extend_from_slice(&start); + section(10, &code, &mut m); + section(11, &[1, 0, 0x41, 0, 0x0b, 2, b'h', b'i'], &mut m); + // name section + let mut n = Vec::new(); + let mut module_name = Vec::new(); + name("demo", &mut module_name); + n.push(0); + leb(module_name.len() as u32, &mut n); + n.extend_from_slice(&module_name); + let mut fnames = vec![3]; + for (i, f) in ["log", "add", "_start"].iter().enumerate() { + leb(i as u32, &mut fnames); + name(f, &mut fnames); + } + n.push(1); + leb(fnames.len() as u32, &mut n); + n.extend_from_slice(&fnames); + custom("name", &n, &mut m); + let mut p = vec![2]; + name("language", &mut p); + p.push(1); + name("Rust", &mut p); + name("", &mut p); + name("processed-by", &mut p); + p.push(1); + name("rustc", &mut p); + name("1.80.0", &mut p); + custom("producers", &p, &mut m); + let mut s = Vec::new(); + name(url, &mut s); + custom("sourceMappingURL", &s, &mut m); + let mut tf = vec![1, b'+']; + name("mutable-globals", &mut tf); + custom("target_features", &tf, &mut m); + m + } + + /// JavaScript glue that loads the module. + pub const WASM_GLUE: &str = + "const imports = { env: { log: (x) => console.log(x) } };\nfetch(\"./demo.wasm\").then(r => WebAssembly.instantiateStreaming(r, imports));\n"; +} + +pub fn leb(mut value: usize) -> Vec { + let mut out = Vec::new(); + while value >= 128 { + out.push((value as u8 & 0x7f) | 0x80); + value >>= 7; + } + out.push(value as u8); + out +} + +pub fn string(out: &mut Vec, value: &str) { + out.extend(leb(value.len())); + out.extend(value.as_bytes()); +} From fb1d7f3681d1f13156ca16f502624c254bb5d564 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 14:14:21 -0500 Subject: [PATCH 76/97] zip: preserve legacy Zstandard method 20 in lenient reads (#2015) * zip: retain legacy Zstandard method compatibility Ported from Craft Anything 29badae7c9280fdf4c24795927bf3a91f51694c6, including the bounded-reader regression. Firmware scanner policy remains app-owned. * Record source of legacy ZIP Zstandard compatibility * Document both ZIP Zstandard method identifiers --------- Co-authored-by: RRFZ <247457381+Plastic-time@users.noreply.github.com> --- ATTRIBUTION.md | 2 ++ crates/zip/Cargo.toml | 2 +- crates/zip/src/lenient.rs | 4 ++-- crates/zip/src/lenient/tests.rs | 37 +++++++++++++++++++++++++++++++++ 4 files changed, 42 insertions(+), 3 deletions(-) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 13e793afd..07e84f37b 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -119,6 +119,7 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper `crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes. +The legacy ZIP Zstandard method-20 mapping and bounded-read regression in `crates/zip/src/lenient` are ported from RRFZ's Craft Anything commit `29badae7c9280fdf4c24795927bf3a91f51694c6` (MIT OR Apache-2.0). RRFZ remains the primary Git author. Firmware scanner detection remains app-owned and is not part of this port. ## TAR/CPIO compatibility updates The old GNU sparse-extension traversal, GNU CRC-symlink compatibility and PAX-size precedence fixes and their regression tests in `crates/tar` are ported from RRFZ's Craft Anything PRs #1973 (`8ea2ec66a1bc80f0420f3695baac877a0cb9b9a5`), #1984 (`b226a475f7dce9710e3af7a069386fe7a9720df7`) and #2007 (`d29465c20b0d570ea4973be512a0cb4e212bb60f`). Source is MIT OR Apache-2.0; RRFZ remains the primary Git author of each port. The PAX update adapts to the shared parser's existing `PaxOverrides` structure without changing the source policy. @@ -130,6 +131,7 @@ The USDZ alignment requirement and compatibility fixture for `Writer::add_stored The raw gradient wire ordering in `craft-lottie::Gradient::flat_values` follows AniCraft's Lottie exporter by Tanish Manku (`63b39355`, `b9258b7b`), MIT OR Apache-2.0. Sanitization, animation fitting and numeric output policy remain caller-owned. + ## Screen Video key frames `crates/video/src/screen_video.rs` extracts AniCraft `crates/xfl/src/video.rs` codec-3 decoding and its synthetic partial-block fixture, introduced by Tanish Manku in `1f3e603b7ff53a3da364e41ec4da8d43dc83aab0` with pixel-loop cleanup `2b7571363b4b647266df758f95b6e397021cfd4d` (MIT OR Apache-2.0). Import commits preserve Tanish as primary author. Caller-owned bounds and neutral RGBA output separate codec work from the consuming app's FLV first-frame/report policy. Boundary tests and integration are subsequent Dylan M. Taylor changes. diff --git a/crates/zip/Cargo.toml b/crates/zip/Cargo.toml index 89cb2d1a7..cfdb333b4 100644 --- a/crates/zip/Cargo.toml +++ b/crates/zip/Cargo.toml @@ -35,7 +35,7 @@ lenient = ["dep:miniz_oxide"] lenient-bzip2 = ["lenient", "dep:bzip2-rs"] # Methods 14 (ZIP LZMA) and 95 (XZ). lenient-lzma = ["lenient", "dep:lzma-rs"] -# Method 93. +# Zstandard methods 20 (legacy) and 93. lenient-zstd = ["lenient", "dep:ruzstd"] serde = ["dep:serde"] diff --git a/crates/zip/src/lenient.rs b/crates/zip/src/lenient.rs index c9bed3764..20da277cd 100644 --- a/crates/zip/src/lenient.rs +++ b/crates/zip/src/lenient.rs @@ -91,7 +91,7 @@ impl ZipEntry { 9 => "deflate64", 12 => "bzip2", 14 => "lzma", - 93 => "zstd", + 20 | 93 => "zstd", 95 => "xz", 99 => "aes", _ => "other", @@ -463,7 +463,7 @@ pub fn read_entry_unverified(data: &[u8], e: &ZipEntry, max_bytes: u64) -> Resul })?, 12 | 95 => decode_bzip2_or_xz(raw, e, max_bytes)?, 14 => decode_lzma(raw, e, max_bytes)?, - 93 => decode_zstd(raw, e, max_bytes)?, + 20 | 93 => decode_zstd(raw, e, max_bytes)?, m => return Err(ZipError::Unsupported(format!("compression method {m} ({}) for {}", e.method_name(), e.name))), }; if out.len() as u64 != e.uncompressed_size { diff --git a/crates/zip/src/lenient/tests.rs b/crates/zip/src/lenient/tests.rs index c2ca97394..ded7c0ecd 100644 --- a/crates/zip/src/lenient/tests.rs +++ b/crates/zip/src/lenient/tests.rs @@ -391,3 +391,40 @@ fn a_method_left_out_of_the_build_is_unsupported() { data[8..10].copy_from_slice(&93u16.to_le_bytes()); assert!(matches!(read_entry_unverified(&data, &entry, 100), Err(ZipError::Unsupported(m)) if m.contains("not built in"))); } + +// RRFZ, Craft Anything 29badae7: deprecated ZIP method 20 is Zstandard. +#[cfg(feature = "lenient-zstd")] +mod legacy_zstandard { + use crate::lenient as zip; + use crate::lenient::testkit::zip_stored; + + const BODY: &[u8] = b"zstandard payload"; + + /// Build a ZIP with one single-segment Zstandard frame containing a raw final block. + fn sample(method: u16) -> Vec { + let size = BODY.len() as u8; + let mut frame = vec![0x28, 0xb5, 0x2f, 0xfd, 0x20, size, (size << 3) | 1, 0, 0]; + frame.extend_from_slice(BODY); + let mut data = zip_stored(&[("a.txt", &frame)]); + let cd = 30 + "a.txt".len() + frame.len(); + data[8..10].copy_from_slice(&method.to_le_bytes()); + data[14..18].copy_from_slice(&zip::crc32(BODY).to_le_bytes()); + data[22..26].copy_from_slice(&u32::from(size).to_le_bytes()); + data[cd + 10..cd + 12].copy_from_slice(&method.to_le_bytes()); + data[cd + 16..cd + 20].copy_from_slice(&zip::crc32(BODY).to_le_bytes()); + data[cd + 24..cd + 28].copy_from_slice(&u32::from(size).to_le_bytes()); + data + } + + /// The deprecated and current method IDs both decode through the bounded ZIP reader. + #[test] + fn reads_zstandard_members_under_both_method_ids() { + for method in [93, 20] { + let data = sample(method); + let entry = zip::parse(&data, 1).unwrap().entries.remove(0); + assert_eq!(entry.method_name(), "zstd", "method {method}"); + assert_eq!(zip::read_entry(&data, &entry, 100).unwrap(), BODY); + assert!(matches!(zip::read_entry(&data, &entry, 2), Err(zip::ZipError::TooLarge(2)))); + } + } +} From 872e001552162a9337c35455792c407a12ec3daf Mon Sep 17 00:00:00 2001 From: Khawar Zamman Wani Date: Wed, 18 Nov 2026 00:44:36 +0530 Subject: [PATCH 77/97] cms: Coated FOGRA39 separates like the reference application (#2028) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * cms: Coated FOGRA39 separates like the reference application Coated FOGRA39 gave a saturated blue about 97 % magenta instead of about 75 %, a mid grey about 30 % black instead of about 20 %, and Saturation reused the Perceptual table. - GamutMapping::Oklab (opt-in, CmykParams::mapping): out-of-gamut colours take the closest colour the printer reaches in Oklab, lightness and hue weighted above chroma and more so the further outside the colour is; black is generated from the clipped colour. Perceptual and saturation map the v4 perceptual reference black onto the device black for neutrals; perceptual compresses Oklab chroma, saturation gets its own table. - CmykParams::gcr_linear: a linear part of the black generation curve. - Legacy (the default) keeps the Photocraft profile's tables: its generator output is byte-identical to main's. - The FOGRA39 built-in is regenerated with the new mapping and curve. For storytold/photocraft#14267. * cms: Oklab round-trip test tolerates the published matrices' precision * cms: FOGRA39 keeps in-gamut round trips within the existing limits The first version broke in_gamut_lab_round_trips (max 7.7 ΔE00): dark colours got too little black to be reached, and clipped nodes next to light tints and dark colours differed from their in-gamut neighbours, so interpolation spoiled colours between them. - Black generation is a curve of points (CmykParams::gcr_curve) instead of a linear term: red, mid grey and dark colours each get the black the reference and the round trip need. - The clip keeps the plain separation when that is closer, tries the separation's black as well, and blends to the separation near paper white (L* 85 to 95). * prepress: follow the Coated FOGRA39 round trip the new profile gives --------- Co-authored-by: Dylan M. Taylor --- crates/cms/profiles/craft-coated-fogra39.icc | Bin 712888 -> 1025028 bytes crates/cms/src/synth.rs | 337 ++++++++++++++++++- crates/cms/src/transform.rs | 2 +- crates/cms/tests/fogra39.rs | 61 +++- crates/prepress/src/output.rs | 10 +- 5 files changed, 389 insertions(+), 21 deletions(-) diff --git a/crates/cms/profiles/craft-coated-fogra39.icc b/crates/cms/profiles/craft-coated-fogra39.icc index 13590238ea3e65e77d69869bc0343e91a337b7e1..1ef3cad1fda97456f7f9495f757f93d0ea00d22a 100644 GIT binary patch literal 1025028 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໋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ȀC@rWq*3^?S@9Ul!LsKSddiCq0zo@2Z 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

3Zq9#&(S+2}ok z#l7Lx>>E_yu-dYkxcRS5KjTIh=D*F87GI=teZOxWcc`ZlaHYCypVj+`BP9ZG?L-GUtdJ?#X8{?*}i2 zg<-zl1J5YvNe;rcB*gE)96ZZy!+RTKPp%^7@n_>%-x~9SdYA)PfcZ{%wMG^5q5<&K zcg%-Yp=U|M{Qh;^d80u!%%SbZd>ZaCJCMmcHL$M~e!qfq;oLj&agAQk1=n5+PJvAl zcrWk)HX;v(q3Jl7Q%*;qR1VTPavxo zc;nbW)b~I)+MFHiJo+B~K)XGvjeCw9uH}U>_bTW|PSQ8n9g4#kwIBLdU`_&d9$1X; z2e||N^YH%SFKmV_Yc4?lB=`ZDvv(Z)&<0I7SIu7N$9bE+LO0G!E6#SpAKlQh1Lqh_ z1Y!3sP3Za;=a>er$2CwtYz!Na21B^Uk=Nj5*qjSCKnt!h1iMb28hrjT2)~cCf)ika1kE$UHs~Czgoe`~u6q)B zG$@UC3}dlM>l!ql!&-@>qwkl_;yU)B&<_o?zT*V^J{Q+IZi>DVZRJ=Ro*A5QPV8sC z2ZXJbi=g`{`~-WC%twCU+=o}=-h*~>s2zDB2>ru2KjLtp6VGU{ZzLUK`J2%1i)Y#* z=%0)^okD2%06#cFKkO<*UhV3G9}Yq{{8%>x-J8(EjzIS|jKI)#hR#5P3^*S9ibB`g zQJ)U{gKIWa&upGKSgU)FC(B6+&UcfOIzM~(2rc;Q~eCR#_ z+b#aZIS>QWOz6Fhu`=vE>VY|wtI!KS%pv{ju^o0Ck%M0li^FT+59H&a{dj+u1pNy(I}iOQ;fG1kQ~^Ky2mOAS3*HF*+UOxw zpnnQR7){U(c0W2EE(-S`Y3q8HKCVbYf0Nc?|^ff{g_U*I8J1Vq|-miE^)dC*D zJGWh69ooPL5ZbRHj;G_1*ZUE7XtW5zIpBvmHPDUo&BnGPIJW_=d&Ca+%9kJ)x*OH-#)}+s+IdE-bod3uI=#+xK zeHbIkf;ku~PX>c9R)_(e!Ji=7mM+eD=m7ll2b_cBtDqm}uviEE$d3ic#Sz%+tO`HC zuU@$3-eL3;Er=oZk2Zi7#2{4{`fcC`3Fv=__uksjkMnHQf$mSZ(?U-_j@gd5_eElx zKJ-Swr+(0v51SF=Zk+eDDJX+@J_TxH-eK0l*haTjN_5?5wV}o~K1;$A5-=Qv04%`8*1>3Ma5QNT|&~gyx)++~b zPGg+&01x_?KIn&y^mj(~d86OF1^t(BABEQ4TA1@#4*f-#;|_p+ zhk$u#wVNe5OY1nzN700_n|5^A$4|y<%XHcADzdiaLTw`xL#uo+9{|e9c zxYo|!_^gW^+W!p9c}GFNE&Kpq4a~(m15d;q_SV5aJw3QjUW9Hjv<=wZ2^&VrpmR0) zzs=AC&6lz7)_utDQcwcx0#@J{{JezkIs~C}55^qGm(O8fBG!vofQbEX*x3fXGOwbcR8#;HP@fArV!s#I4qMgGW)3_X zT~9FrALxBV9w0Z&Zz2!iV|yLM@*LU+a()MV64ng;I8X9S=of+?auD~ccxQy;X#Gk< zA#_7SS2pzifDhZC6UQEd-5oNBKiXrvB-Vp|hMviYGk$MHu78pRZ;k3}Mh=nA#{Wjy z@PFO)pGM1du!FYm?}Yuxjs5>X&rA3k^$Mq<2YThapl>#ZBXtjY`LGTI{yo%z^#R!b z(07#abLbt`iRgpywLIz%&cm}djvv9kn()^?fo0Dp9#t{=W=OToD};NFS-EJdxQRTIv^d^|^Tqb^qvblPy3M+mH`>f*ur0M7l&Cf<9Pr&X({=Q{>2+lTlo zA;OKao2;^{7WX5yH>G zCzyMikMoq`S?ev@1N2Tu>~=}uzJgpCf-d`Cqj~Sw1>MjSdlYeg!zsua$I)!N#ko<5 zp<2r~E`Mt!$EC@iE3m_rQ$V_7ST_N~wJe4{N-+t(ryN+-rMoqDUK33i7~TQk(Ou`xUA4f%o40Ea1?tDo?9O+j`w|h z+`Y(a8N_r{FW#or{&vt ziW+AL+h^_KxmDLGe79m9ui&QjBC2iocojB06PdPqChxe)IuXS)J-lPfokR}ZKg_$Z zI7`&@^>%?N1s^50eHq~ITh}AK{#P@9$J!&ZJMcc@Z0-sX>-Y zVYSehhhRkZys`FRepdWgeBN82W6xoHMh5-vzPwTUce(H$px=fBMEQw*Y0~f#+Uwyl zgTyY5;$&i{ozi&5VI`aa+fB!zcSZZYIQsWg`m>}0u(;5)=eSt2_*vc;9imd2YF&K4 z8c)c)HO}I{RFgJF(CLamY*o_OT_GX@ugVPMpQc#|&MWFu*jzkcFn#@Ag-^}ef*bN@ zDBK&KC0LgGOrhnZz2K^xO^V{T{}J4rJ$anli$KAjnKzU?KPd_~r~gsu|M5)NGHvCA zls|uk)mL<=;`=UywNsQ-?LhP7v8s5lCv2azNOb^Ql31(yFBqQiZsK?_W!L}p56l&M zN;WW!KBq*Rvwlze9p5YZ zFypFv&)N-QBB`Dl;b*3A4aEHN<@M3h z@jVx}3~?s_<&54C%X;SMFzU=f%g31LiLn7UhZDcf$S6+gB;P+-d9(ee&KLPFnO}d{ z_>D|Ytc*d4%UxOR$T^0B;TEzbVTOh?SKgPs9MowTQSn&zdqAgQ`Boj-7k-ls^Y{D7 z?()8E=y@?mcEu6{!`Y84WCOe=7*2fCBkQ#IsX^7}cXG2lbq&RTCd%r1#u&Q)>6R(? zoNtJAk}}g5A2v9Tbuup(CmO5;_b=8lm3b8kN3k>mMe*QZ>(@f!yH27f_cQ8Jevk$ma5%2 zVrrA!Mxi#IwJ~38ud74~tquOVaOJG2Qe~c@^KM!XDy?^Gw_54DQt6@7R;$`1jzw2d&mLNhwdVeq-goLs#j`ydCqtpZcz}W$wm#A$MLW8P8ob_u%ti$akxwT0!>zm^J1t=URVB|b)>}{aIqu z?_`~2J|E<-4x5O(65{zq9lbZkavC!)5ex3>TN3ks8ZrOmd76n(Ip^tIX<~MP^$X(4 zpEd);3`>VpVrsfP}8 zbV7YhuAZ?6_m=z^UcCj2Hb0#q_f4R($>m`m~OK$m$<^hp7||F-}x++tt(*Nyh(YneGl@&2 zmaQc^nJm91YQgJj6&sl|NlN&c!N>49hG*pzb#=lYxHQV{pINZ%V&o+0U0O~NPB}Lv ze{1?iik5=k(Z50xa$3iHasQB*p!LM(KBzxK-up1< zk#|Ig^>;b?hD*rKRZmQ;i5V#tUx}$k)+xkfF`Mhe_*afIh%x=HA;jgj9vEF9-YdPA z5`*OeRuKJaLoJAlcQ3CbIvh!0d1IcP#>;zvt1?S2?XUb*L5XP>QqSu2ifvYVl@?=v zSu|F)EbT&Qg-E2z{Di&OqC|ZiF}?Yv`e`zM)Z4?u$IcLsIXsw!X@KhEjRk3CA@3G zlSqfZ>x2)h#zZLLK5nlHhxG}pJY@A# z;-~nO<#*%{t1lMZEjMFRWzfI-4 zE;T<*=cgCHr*ztiOTXvx@0Q6++4W~D|4-SG%v}5;;3JopUc^DwVZ`*7Os{`xb8|3T)WK{K{ESvud0x2TvlK zLJc)(%SJtCX3>Vbq0Ez2<>}0_O1Gjk+FmiPK9g8>u1lX-+P?cQv1G$>XJYXneU~X_ zb3WYpm(k`i>*))xzO0~fVaB`tjFMkEhy}_&1kj)ToySUHJPS3bHt45)Ju#5a`5Dpo zkGmFe$z`uq#Km#GtUq)cT*{7fiVw@7dfVpFZ{fE(A9sVwrd=yoyU^RTidi+SdTj~S z%WIdl6EOl?Jj(h?#XS10_UEh~Voiw6OX9|Ne(Vg@8)Mm>XoGk59ICI!;zALiDzG>m+)5Eq+CGm-AucBbOZkyQu8&J|u}~Qy8I4v|1JYjc8Vqm`*fw zNjpu{`j-8HI8kTa38FNA#YrMYnzu(;-=L^Yztt&dv&^b#nD?8?o2=Yfk5m0Ql1NXNcqO_Om-zBV{bb91hOJ#eXAQ|Gq#bK=7 z%zM7vh{|Sn7}We_!;SQ(eX z@~C2PRXvp}RP$KRRlcc^JsFhGDC?#AvSU@uZ)MrlOktUA4YQz3u8u{h^h!f4bU$*q zKzq9^cVYS9_{jY{mF*3@UJz|`{Frst@0R*ed9GXNO`=(7B&#>(i(&rJdy-f~^)t4n zvFJ`6lch^#6@$D;qKshCQ6g{LhJ!@(18IWH{!P{jEN&YU)JOY+HbbUw!+k4p+HZr1 z(_LcKf+bIhm8*k~5G$@kZDrI+Y9p3+XRypJH(1T`q3m=X>w(JFuDeIu%bW{YMwTfS z*HO9jSt(OqI#7=O*vZf-ifZlexUtq_Yqr>h$_q-pBZyWT{fmf}-a#y$ria3rexrBG znP2qR#4_u&?UPvR)R0VP?Py|EwkaK_@NKOfQG#2{S}TXYT7k-ld%rNdQuVMxDV3}F zr}`2%cR zWkQ6AMrF%z6z1wjqT+};7IEK+)49p)J~8=n2J6jKam(2>Q%#hJ6(8oa{HXAC;!?T%++r57@`e7)Uu8Q(OsKxh zGm^FF($6susa)Efz^+^xm%>_d>6}z%S*dI~J5R}*43^m?BP*eJzPk(Sm8{0otUBVp z!|M>yT+DZfXrdo@jA+Cc@|&o?F+z-}vm=^$S8Gl@yAMp`P1#8Gs&7ZXeM0fr>NQlB zUY_qm6r5TzmI%FX|Ic}%EMF@t6-L{;f*R|IEBa>Y&>j`qvssT_zIU!9mCNVZIugr{ zxG+o07I`uqr8oRoKUo?V^n|vTs)n=sXvsg3AE;c?6@7^@CzdHK35sWtEwM-}VD)2@ zozUJLUB6MuLdj!Cdz~{8N2sjzPxNP^dO`w=o|@wd zJu0i%WwP>Eo7GH(#H4)I8u|1}SQaAAs+{YzXT?Ub=fv{A^322KEt67M*-mQ)vFxG& zYk_6yX6dY~JbyHv?e-t3Tx#tWNG$o!i{(v8i7$(PiB%wLPsP82S*8|W2-`sW6}K;A z{c>?(X) zLey}KVdJXFZ$`goZ^E4wZB(!LI+Nv(EH{VUM?_Wgw^BWKU5PLex*d3!C(B-lk8-Iz zv%5@T;xgJ^dRsG?am6gwqm-)8SxDuQJ9CQ}GZvm;RCdfJ7Tfmf)3)YeHT#28a3MZzCWkX%2WNfUI`q!#rym`V1(d&(Y3D zi{I0Pz7qLMpBJ`5zV0dnH)H<&3i^`YpccjwZg?ND8e?jBa`+=5^@J~@zA^+*XRq!`+s@xeI+#R#x~0}(2s4F{Ll@1Ei0k> zIJPT-xQ2BFbeF>)uc7-n#+uVW_>BBI7=^JodR%%x>w6M5KvOXM)d%g7@z4(+#y7)O zwCU8B(2wJ?Cqch4{D79(=>$LAhHhN90=l;4VWfq)Z#{~USRV+xS~fvnCN#kp?TF3x z1`zS;9sp{UL!oyc|kvpk9!K6k+Z3=t@ADXfMd76haaAezQ-!Y@!OCKm3yHZw$;=? zw;Seyb)geJY{hxnd9m#Qbfv9-MO+_mV`=2L6DS z!Nc&!6A(GG0I?acKwjYYe&m50Z0~c%vl<7sp*}DM`W5hu2b;R#n>Y>VzXCrPKz|qf zU=H1|KR*oGiqJDGfNtbQ75viPNKYcrdkXDA0+dD_{N9RvJ58YLIySs!iEFeYAF9DN_;xdXZ`FX-Q2cn| z7}(U(fpe>Z&@g~FG}l7II}kqHg%~ycfNt~wO()UzlfW9ZfhS-jasjsOybt}zso^H* zvVcz5p!XH}9%6mNQ*a&b6$79(r(IOoBlhIC! zp??+fq7ydyqkXs{{;=P77xW`0p|E{B&L4wVZ!?1*jzKqU%RUX=xaPW-(7hUWQ24kN zKG+2Nw%{C%IA;su-|hgNu&E1LnvUbz*sn(%;Nz zz_ky@gZMe}9r{I}qa6A+;r+iWboF7*1o<|w1Y-pFZ$KYo#Wrv%mw68gs~=!Q>gTcA4yzt=-=5{`WfeR;Sh@~z4V znFhS0dd zpZjNGE=>-!!McD0U zUOV`>4t2OD{k^sNBDC?-=sW(!y$^A$TZFN|a`^5p^u7Ueus*B}T!{5y$emi)eF3>q z^9bt)p2Kd$gFeCA3qMU02fMHiU_XdsC*qjC1$d7S`)J+O1U>LRcm;fk?NkpROc4T+ zOByF}Tm}3g3LDp>ovni(aBfR4=!cDV&d7sFXdge({^QYK;-?*Pi-Jw9uxG_b=%0f3 z|B=w2hY`|i=>CBAfVzfEqeBL)3ez}bO(~&3m>G6O+Q0~IEImp9K4dlfNyrVou||HU*5QaJ?;HD*EPTF!w9;YoTB0gl=!d8o$>eh8@SC7j_J^L*HxYH-nCU z5qB~4p}(*$?iq+2yE=@gw>!`Yzio))a2_I;HsBgh&Lg+r@8>f>_~I4fR0X~N{eYce zm^*a>ahxJFc30vVu@*X_FlS%@U9e3O^?itmgf58qOK{O1#-bkA>_>cM>QRpzmcNGm z&*FTrrza8qKz?;$8$CyF&qV)efjq!*4%nxy4dV%6=vT%#;yUsk=S_v34ZavRyoPqf zr^*4kHQ}3s(2cz8`3#-AkpEiH6@_+QjeXpa*BuyJ!~D&h{7f42Ax;(inFfCix(*GL_JZUNjUVE4vV&<;OsK#V$ITcr=~ZJyAz1M&YCdhq*I z%*CJM zRx_7}6Wq?J-*BAgNXjS9jf(BO4(lVi+|m=g<+b;?V~Q8?uIM)9N)+nw&Oac_`Lo`I zSMU-q=T&|k@0`bGoS(VgyxZTt;a#3HS76OIGhUJGV4;VMM>Zl~InszQ;&xCjmN9LtAaV1Iv1oa zLfb*kOtQC$BV<9W%aB0JKu$`?;qHXI3{?y#Rz|BJlaZI-Rp&CQPHHBW-I_dwm4hd< z{VRIaSpHN+st!|qRjSf6te-kma#Hc9%qRZL{A#7y>gR+sRzFpdwa^vn%*-60?*2oV ze?``W>_`=1r$issaaj|ESH*r-4Xn5=TpcZ}8qr}WTp1apI%BVzaAx?63E$4X6OIl& zs_JlGN;o_Crs~(1hlIP9_NjjV_*CRw;HybW-_MIA1iDXp^*dE$X23JGjK60@MErlK zIpRI$SN}z7Q^7ZWr_``+O!$eP{iL_x{aSg^+hp&C5?S(&Xdfcx~PU4dpyN8DegZZUHfSq4t2tUfyvj z9W$>@a25I$oipR2{wxX6@ba05?CwZx3_7gsvQ%8+qkp${(+Yh_O&=BQYeoE$E?zR) zubMO^Jv`F2FARN>)L*2gU2t-u#4pzfZMR!x5?5X3XzM;*B{AZpIpf~Dc&Ten1vBHn z=1LYh-JE&$=P8Mu&WhUHKg%R$IM34_gU|I}ak@Pd-*+Is$*FQ?7#Qi~J`?YI#m&k# zjyXqm78NR^N5$Xu(3sdoTx&bEiMZzUbUEVc8trMstf5)2h%5IRqUGbg_y?o+#B?u{ z24dny`3YPs^lf~Mc2TXO$W8^jM zcAI|icp$%i!E!Ubs3-D!=JlFsu8EXCZxLc9ze!vEglUuM!|prsHFG>oS04ILe!kHi zlh0S`$38UjG4cC{Z)}QD(wx1ozl{|#QZsJ+n-lW@D;qO)1!zNuu?fCwOIFoHgGr+0&-&B5(ow)&OM~SN!sn%5MfMXJpJ` z`H}j!XfJ$GIa)-@(ax6Vaz)j8Rn+J!FZ zRoi7I&lqs2-F{B$qL#Kxz=06S?bGKwZ@y$C@o~DGQ|QBK5=W;mad`epOycSE2lj~{ z$4Qz_FShOZ`ax<)>!HoJpRQ8sGj7=U{|=XYG&67ElRy2E2erp9O!|9Va+|jKf<1r# zO15R|Onyi9W#(!I64NGWvpA;6>3ySeqV4QY#JDz-Q^Xhriz4Fk6s!5fWrGV@e;Inr z?hloN{GHi-!{24mJt})WS;FooE)@X_scc;o{Epw9TVb3Q>^g3);GP+4mrCiZkZjX< z9AswKCw^t>#b9o5o|v`T_2AhVn?(I4S_MxluM?@BAR2U|BSZL^ihhvRzNNyR$_`6; z&rcE-Q%(u+x-T!Rpfb-d`Nb4rxAFEqb?-k4w@e6K^7X5$@E27HuY@1#M7kzwd1n1O zD6(`ThjQ6t6&=c|RsP_AJGS0r~}(9U&Uj z$0-x1RU~RjHS)bs`Ica#(I8wsZhFFV>n5SFvHKHk{U-|g$sSBxmU2iSL)tcRL2(-Y zprl2@u9ltr!s1)vpY0srTO)QdZrACBd`9BqVs6|K;aeo(6jlDTm~T+>K%~{%OZ@86 zTFX>Fujj9qNeuJ(ZYIDhTM)|gbEm*!xquMf-}VAkV`c&=UeC+t3`G0E!uE%-n z%ptp?jp@@Bm@8XoEJX}oYsTyiIX@Spa>Q9^{upAw6kAsI9q(vNWv{cYp+pZMkAH|R zHQvl0_B?^zRJK|bo=G%zjb-;+jn8S4R31B+y+crsXPWr7)e9%i<|`B_UL9^`&bvlP zY_*D~8c&~qXm&#EL>?i&{H($}5pEuD#HzSW)45Z48dj=x&fz@b5zRQi?>(oFTbrJB z&Vy6HO-`G3--WZ1$7_Y@O99SF-aW~4K3H+h_{9>Fzov7$1oRVleiZSD3#!LG`DMxD zCnOeo|93f0htTJk>wk{$e2fUvXK@WnF&ZKJg7=%=CkB4DWcLYwE9*y8_DQf|@%38e z@SVyY{;twQ*GC@FM916S6NomC0$BX#)rLk;dCr+A)=%n;Ns6JeDkqEeufi$oo#^id z@%)davw*JZTEcMLiF-(hySuw9ad%hZLP&^*BuH=%?ohPF3oXS@)w&?0xj!*bi4~PZjzeH^*{aZVUP1h~ys2Gs&QA5s%3J(`^;BW#2;j z{2FHNoTc`}9)-<3Gj%}L5woZJI}wrCls?_ckSoV?VY*}#l+4VS5X03&%Aiv&nWb>rq^oxg*+f}lL{e%vF(fsU_4uF6J3_XXR|&_>`NvA0C#`+!H&VO)-F8i)Qf7Y? z5ocfr1e|$PGmHM3kzngX9C;tGg*dzE1J_eSk-F*ZIS^R!PnExk#-^_XGA4 z6Y4{j662mnbQ5FZW15JOZSncUu$W|AC1BhiN#9NMJCMV=JiinMk?m4n#?iMuP{X#V zY7>tO?Q=N(~>xSisMD~Ez6dsZNDg9h=eRF2;$n1SEmq&VU(xOkaUeEpIJd%5+uUgG^&|2=lM~a?Z zARZ?-Wk9!{zY1A#SAw1sV_L&b5F?*QZ6=2M(Op*LJw1`fL7-V`E7`ttGI>4E$$5EX zyKFB`C)%sfQwiLYajmr?>Mw2Pc~h-nDrZ;X`7|D-7!R7_9O>ypnq222UFNKJxWR6S|?$#W#71wnI5=Aaddq+h6lO#_Q zN5nLE&%>sstH>VmbK=NNYxQ>{dvHw@SKPp#f+Ny^dagFL_otQe`h7U1z#KbPojWCo42AOrZN|lmpoTGX?X3 z?~4SEnzvpG_u~E_gX_d4Ayw_`5Mgf63mO6Lmtrb0pYlEVt;DtKg7Omxt!-d z!;&JhdpB3DVfxk`Aog5u;`Mrl+A`RVnSWKm-%mYDcK7A(Z8*P?3o#)p;9)pt z#cy@=EV6wfCOQ&5k0ib#x;;+4M0EZ>le6U@m&ft4K3wz-wVT~7=ja>8)^IiJ%xSnz z?JBO5Gg5fjh;x}Hhm>kX%mX}ov)eOZ@jYa8)=Eu#6};vGbz=M{QHz4A%2 zM2%k?=MfcVOlB{|r*=Ol8@hRW&_wnN*#j9G3B>;UhBC}jEBFPy_ndiz^)>o%K6_t; zaL>JM(XO<-S32Pov1f4_&zC)J*)?Q$|DMkk+&!n5m360_N2KqRh9R~0P15Ia(I;xL zne5(0j(lY4b@Jf$o@@S`sh-L(_OM4TW|-FNUYYP6Ga;4hrdu@AlkBb^a{8Gw^X-^< zg&e;w|Dtc%)-O>bPJLY3if4Gb;fiFr+C;HVXX`jivK{Uu93t8kq*M^CM>D*M7U?;* zM3Zd=WkiG4lHnwVQ?A~4D7BXGcUlV)& zp1>osXUvQv+!Jm$huXVexcQ@;u3I8H5yFyMCG7=2>r zy@{-^b8Dgp+ug|mJ2};c?SQl?OpEj}reelS@zb%$dmW#@ToddKveQe}UZxqEFwig6A*+*p{BV2m9c@B&sJ2Gr`(}IQK-})(Ybq z1ix!A=h2&Zt4ndMf^o45`=I|1wsIY=-Boda6aCg86J!73+BX~2#l4+E-2Ze(M6_{V zv>PJ|ZA;tKeAi7J46J?)VI1bbFxg)_0&CBWB$P ztcRG<=SzL}LNBxj+yK*Y&b14=F$N=%kJTS>jz+|9(ofho;*5Y=<_~{4g{vzJN1Q__P>v%UmVsS%zmD=ws0Y zwC%@z|C8tgbwl_6#}K=P$jQnTAm)Ts(6`_PeEI@n8Rcp_egmdJ|1;=fAr;|J(n527B{xuE@fYzv<~5c{5i5$%sR#!1qQi=w5<2Aihh`PuE*$yM-f5 zE{HlEse)dtJBk=AL>!Edv5A?5ue*Eo@nQwhN&JlNGogB;^@MkSz;8X%efymt&=yGlW*CH;#U?jGqecVJp zX<(wDu2$_pT}*=ysFNrw5dOp?J}VH%)XVVE6VLTdLBBWRAP)W5f7KUgz}RS1g#K_` zA*(~T17?uP(1;ujV*7=MaVCm=FOzpE;ln<>KXn$m5r=U2z5@G=gAZdmm?x08<*?}! zT+1YI4-@T6?jsKCq2+;KTrBz(aTtW&JD6F~=R$d$c_AMQ;xR86LoZ@5HxGKy|03A) zCZexGv|Yfy9YCzR2L8`QF4t>f4*3Oo4Z!6X^YCp>9mc>PAo|{_4E?AP`rd~%&~I-7 zU5K9z{HOP2tT855eZX_54d8X~8u$a9Lx8jK{sVkmm4vvR!M-uBT)IH?0X{8iLmYCT8#OQ`2D&?NgoV%Z zmtcN;3ccueR1}m%+eYa0Lmw-l2m4xqILxtymL}B7LFm5?=0W#1a6D=s+mGJGTsRN> z4$s_v1EFJw67+UM&!5nPeOaO3mGIjl7eo%tpnK&`&<;ERrh-Rt4vD^3uEFQ|iSXM7 zwYgFc@j&gZn2zxh3Ej6bPEe0y@Hz0NApenw(NfH{2^sMH6z0pz(4UWcV13Zb2%Ek)X092uB1V+QMFY?`3;Te^(TC7)1fuT^y_iFhqb&~L zROm(Dv#g;P>&|?IXR=s_?gH(Gwwdej{s8i`61lUKfdBBt6n(8o$2sC`5I!5ihZX44 z&;mp)8G3_%;~d%(yo+-QvJW9HabO|p1Tm%eZXB+F6ENQ7q2C5|fw8j;aSB6x>Aj4J zsEx&wFkk9I3+97@Ezk{Ls`QcLAMx418PJV*()Ym4g&zaZG$#u_qyO3HgX&-uF<<5n zebBMG6U+XA{`X)!>UYdX3QT1IA!Itg`|-43n`OIXA`r#}W{a zeDpIJ@y2U!N)@S|%z zbZ@|T7=&*4F&lo)!oC)tfL?GF_B8|T8~vbXH}W0|qQBkndt?~T$B%*V_n{F$4Ii06nM$df#9?+3u7=V(GTLg{444NbIfwY*aq!O?_%Eg9(4fU{1B5xsJTeg_(H@q z8UD>jZ1Rw=dFF@%`k1o{&%_Yt+1S3<6}q=WE0)cKFAETp8RHRqjQ!~%&>s$+;0_7s zu|d9(hoNq~A5w-n75@Ez_)KfVdjeLV4&IZAz%d6gKZAV?uEu*KRbUI=r7eJen6tDN zgV3XP1AfoK`wPg;vSM5#2tyD0l1IHRN5A77p%-;DE+2e{cKnWg#`?M2a~$G;_=fxkO%pLsY=!<(oJTx>{&t){VA&{QI2r!Uyom9D zxXeJzXJg+Zh{3X#&>MpKUk|R?bE?}JHVn<(goFa5iqZ!Z{z_asa) z$NYo$f$BiC-}n~9{%%rx9Nw2%2*033`7~Sl2kjXqk+|~0p{&$TxXo>foP)pqy7k`g|5_s=N2V-mjz9&Zwbi?*wln7x%#2%oZrA`7az9NjsV7(#HO5&1GQ7FKAxx$Db;(!=1v90h^ z#A5>PLFHllQPf)xv@~Hpjm9_##rz5XXsk!TmzfK3y@5E7)FKWwsNbdVEfIS4F(%5P z^9S@@4?WPj{W_LC#(R*^(y57jyWrURBk~H5CL>P&Gz+h7MJ(UR2z_k+AhhMR!B77cxwzCYO`719VX0aaOgw3UTIsMQ)#YPzf1E`)nm%fA*-t4zlOnk^P3axKu2TX@I(-`Oimq zrnZ7m+pGzq1vWnlOAh;ry$ci)?&{w!5t33Ye7AeGWJJZcA`TrdBp-E76Um*tQOaia zIFZJd?NZijE{ZfXew6&@yEP(t^}8k4p88QFqBdU246uU z#IBS_%SOGc7MoP2D7XFNw_<^%G5^@httAdERPrMZj;gWl0WnQv4CCpU_9JG&_)E-8Jyb91 zR8%jLI51xq)rq`*&<-RHZ&XD!pr1^|!*b6=_jL^_&ojI%zPRn9>N5A864s4I>Jwrv zNi3XXt)W!#K;m|#qQ;Vz8U*nLTz{C_nL@5+~y%oDwd($pmy%6+t1bQ6Qu1QT z2JPmrR+2kYytHTI|09hhZ_vj3Qj&9$CurmQAS4HeEoCrE!vA4K%(AG%WrFVo={D2) zne3@Dy1cx@SRbPZ=eo0u-V-OMnRXG|2F%wpH7tXe9#*Ws?UB_)vL{cVZzIF8@Vc3g zc#!a5^#{{<%{ocV;$~Axn>VtGxvR~hg6m~-GtQeUXEewzNZDrITB{^`AkoNtL*HMr z=O*f!?_A_0doiZde0b|c*&id{ntLBLlwBSE(CpE9aoK5M17wbthHQ9YtIt_y4LQ zV;|~r`D~Q(klkXJxEo5!B6hjXi|_j@owB*^c=P!QmDP6fju+neD!beFI&S~atmNrX z@7Vuog5oqs6UXe&R~6+Qw>Wxyd7^O0DZtSH??2SES!(mRZ#t*P@u>gHD3AQF4K~B9 z4t`NuI-MKiKT~KFr(ob>8kr`V&QSGoy7b>-`m8TyMdS$F$ZRZnh=u< zBc+JZGSOKQ??hw+=0s_XpCIMpY8HOVK}_MHU2*vF@B*c$);l6z|CuQvx76gD$lq39mVIcnDKc)avuvbcV8rn0P?>86--Xv-cgOn;x55nW{UNi* zFfZi9^9Y$M29JY2zAlkVFwzS$e?LR^v9W4k%SRX4oyKPZ9)Ef#JI5p;V9FP5*Y z0rFopW!q}s>MN3e)$ffr5i9-8G2`PN(GhDt0+f{7bKZ+AomqeWbGKh;dG5Df7R2mG z-&w?rErEK()a^JR;3x4zWG*qzJZ^v(wl#Sg(JLymUTCF|o!#QBT$SEtgBE(-QOQpwMnJIopd3kF8U*AcLQ<;{$?dc?mMAdnT7zPq+R2Rp8efvd9MD5nZ zrym|kUQ$0lQRCwk$-^4`arK||B==}K#s2!mQ*u}Nm{3F5j)m>o8cmd8Gz|4xf@#-@p9h`~iE+lgMg za(LX>+$p(5wr*vWzw~C28>;G+mkfs`W-5kOb@}9rr;L-VI+8L^EJ`M|YHLlo=p-q> zs^q>!B1a`QRxVt)SHw-cxnk~?FyZrJGs~L}uNLkTeOBiG%TeJtG3}D+H&ukQ#T|+Y z9>6ZF2SL=hW$e+>@*$4l-Dtbx!N!GhhKB5<7PG>oO zE)cy@@Pow;@+;5S<{x7A5(k`3pq@kNZVaCLzw+QXrHpwWCOgT_Kb06i63pX1c5&D% zvZK_Zx&A|6P5hSZfHTQBqT?L$YgPi$p|%KT3Ah&dx5kG!?)TPk;opQt#Dm(FYvUXL zMU`8hyL=Uv5N>OE6q_W}Ddf|qz+Q&EsL>3jcA`9;*{{h!_*uxQo5OnVplyF>2}Tw&x5?c@+8|+3g7#JhQePtKy;7 z8at(y+MC}DXAzsWE#N&hPF{V2?1nV@jzY}j1$*;}b-hP$UW7QEJTb)d|C#kqI&&W9 zV2E4oC63P|m1~P|Z>ZY-8MP*vIO7Z!d4A>2QH?v|b&~9uUO$d@luRJUB|Ieb8)^^n zisbPSa4L2q**oCx6c4HQQDSo*1^Kx9d`Si^qT!vDtJ~g4pD|sGQiCw{kzR zVQj-AV*QtGoU!`JyY$&MpwCt!PS^I0F{d9y#ZG+Tbcn3jn{K|u=)In-GqTUuo9uA) z03Ht^3qsi2z;h9NzU8+q#*&tMTgS8Qu93W+Y^UIigGB4MdAQ=hHT{cH8KU-{8lHFL zOxnoAPtOt&*4MR3gL~-wYB7V_JN9^r5vSyabL87qQnu7IB(_fv^dU~}q|fo- zjIBQ1h}ha%s6%X-U*$k-KHWITRBq=ZcvD07QL-B!51eDR4s-oCs?q2Ep#S{nR_3BP zt<17{VR&}&)a@!+!B4!nZUg`F-9WbgjzHdW)B?eAj_58C72VXQ|zS^kr}FA#le{5i_rq4eox+=Koc#U;(=`Lp3qWKXuR9Y<`daxWpa?h8~Tw!DvI|6AM>9+2HUCxe$ay~%q)c2hx#K==L1 z>tr`}*7`F|8+hJnxYNuTZrIw&ack(Fj5CtHE=wj z`xPw*4P+XKlkL?f65E;#oQbWMtV)><&fADBOMKFp!t{A-=+BK_MQl2en9mGL=i@=+ z&p8~Y#<)TrR}C*p`AFWdyn?rDD60BM>o<5#;&IrZQrkmz{VNje@zjf>>u%#`Nv*E& zf&E11=#V!=hYt~)KfCl86|$}SCmtYLL?w+8O$O4~Hqg)Jy4Sf`z*HM8olnc$NJ`WrL5+yJ@_yniLj zxz?ZOGsn3>8D!gchn^A=58pH_fo+dA>=<+I z2fR75jZuLd`G%X}9@O4Y8xzRXi05%te>8a~+4aro1fhE0%(YDE>~Dy5f9AR~kL6V` z*W}N{dCp{?4zlbo2;QHz{SYipw)Ok4BBJHDkvz`LonkA=HYraa2pQTXUnJ_aroSU< zo9A$qtG+ArCtLpavKpe~z8WbabbKpdvzF**`m1T%I76njS|73Txb70>fQcv5(%O#L zaNKbpv&Nn0fd&)bJ!ID(590c$uLzH3TOpc-*PV>}k8J$QV$N(`eDV<6wyC2``7|CM zwfEEcI8u8q6Z4VnXP-~B)TSiBjcBzrcnZ;CO&C|HSwR$!LgNRqTsMXm36p8L-p3Sw zqE1pqDp5l;=KxXZc4043_FmZ>qS&VzSt9iOe|~7R6Xysw{5g*E*3hmN%*&m}3v3~y zF|zBw7W+i+srJh}q0coG8Y$ zjz7;-O$;DT`jiyKe2|PdTJ84DAj{GyV1Q^|70h*P+AesX*f=PPtI6O-oE9ygppmeP zsPi?2;tWk%6v~x3sgyovk9M~x z1*TT?A*MvEGO^})9LKljPTYGu3ktzC!5iFP##r=9!~NG=I94F8i~aF@-yZiZO)-Z+ z@xn>qdfacngZ4JC1?!={==qzMG48*v!LbM1&UeQ(mJ{wr!q*V^H_sO5XeD?qwF2j? zY9Q86)W!YJa$Lh@;(qNhT-%)m;agz>?uW+X%4a3+6QVY%Z-Xj`;0N3nZO4pq1NXDB zk11s!X00xa=;@bnhW-qMe*>6TreiD&ZNYutz4(Q$5v()g5$Hqr9zpas3SWocVV^_b zRrunG`^u;duieo92lOE>i=fqICUj$a=Sb*;?Q|NP09y_^QH%8d4dz3G>s;vkig^46 zB6eO_HV^xwBhOsSeL*f@46em~!oIL9`Uoh6Ynb2R1AI!w@nG~I;(*wUqIL_e!B^C5 zSvhnsLmVE0vKUd((1Q51MnEUx(}A|>nz%A?hAzar54jm}z&%j-PuHZw*v~L(V}=Qc zb!K568b(cwLi5li>>EB0LDO8+;Sgdn7kw^y3jIf+ANzNP_60v+?(BrlKXJ@V0TVHY zLifDCV8?-@Se^v>B0h-e+*gQ4Jcu}W5QA|pg0?x>XMi<`K0;n#-|#oe0EFg=^WalH zuJN#J)+$`{20`yj#Gw$>MI79qp@!}aK`&z1un0uGw4%=u=nG-Jal6F z`G~b0md#7R9BPGau-pcM(Bz4D&c2ItQ_`P} zx_Am-P!DuwK8k(B*+YL8uI;hzO!$>ax%&n8ez4y3e-Q^A&`VKbCC*wa^#*7`%pk6@plg-gy{AZO-!mC7^L3#?T+o zJOf1SEQBxf`;c#WtYZYdt2iE`W;YqZhi?Vjp`!^iS7O{g0t- zKe!pXhrtHuehJ254umiLPT&>j#(u0PU>oGxVjpyD#W4fRXG4RT9+-mXa;S&d>9C`~ zSURSFeuxWlJzEX&!0+e{#A7bli1Bp*RKYme4xeEAVIMP5(;?-cJmv|+ZU*w5fZCpp ze$!DmBa;vZ3+SGLIAHxD#AOotorV}R?F3~oKgvRH5atEseE_i>7{ad*w!xU~??&Ih zfmm;j2V#W$&4>Se;n0os`b41@b=QkHFL?xF`7-q1i~TM83LVIaxjOuA!#UDP&;i#< z79jdCvINa=&Vi>@7yYE9kG;?HX{Vr2&mZ^sCgao8$M~l&zXiG@-wpn zM1M1p3+-VLu^8VB{*3K&!L5jAIv9(1lwf=KZHwhIByb!qhJG8IUueO1Ym5)Xa0t1G zjfeg-IDVEv|9r$@KQtm%<%=eunF%=KvxI)-E4+22JKrGgQxNS3}QZl{cA4+5kF0; z*C@QlfcarMd{M234%jMlKe_!15fQ}*LHhK{HM{)cF2N0jUf1n$&sFXy$YcW4Qf^KJM!t!p^ z%>eXFMcvYSw4J-4UlzJn`pgi6WgFo$M&|8VQ^#R@s`wYVO9p^y!zv}~z zJ`2Dlv8h{)@R2hNTE03^n3-ihc*-OQbEd#p3w62Ku*S zp6r2sQJgmjLH7X0Lo#&VM=aoLXStxSDcEk_PUzeqsC)X~v}*&PXF7Bvj`Up`JAMX5 z1m6YKG8OMZ&B7c5{|@cPRV~KK5i=0=a}+){C*l2(D%2(Rp%4N8u)geh_?wTx9+XJA{c7WDH5@py)Q zv0qym?C%)PFHE2xK8LwLKb9pSc0K5`pbmBZ6!YUP=>7q@mPCF}VVgtHjo8fH2ffJs zm<@DYLY*5y2mIdYien1K;C|FYBQzg*jB~GF@jei=HNf{X$ZMP7?Wzh2mF{{Qey$4ejF5tkoa6SG94*y=<*g@=DMi|v_cCx7hz zPRYc$T7`2jEG7D5uPUy5>nkA^Tdd^upM&_WSQVu$pN@-n##~o=|D|3$H)fZz&DZJT zkuep@`2SMkK9j|zZjqnOr^j(+H<~JOWz;=XL*=0EBsAHsnXWTLc6F{EMilC)PTz)D z`Io^P=66Pk%n!zf#Hwe;2E-a2!^3Q^n@}zEqmX-Xp6(N+*Wzy3TDpIkMMxb;^_~#t zGb*i-kfiUI=q#NatEzvvEMB@TvPS=IN160sn5+Jq(SM|egA?`tTDwrXGvKKH(B5g% zMSd&wHBW7l4)fKT@WZuAX?q|23ElVfr1ibB^n#zo%53#&(d&6FD*f4Ox!#)hxzYn( zC-ioF43~EHdZM@Mv%S=3ZyCLBzEnwF^ET1j^fg}UP+f+?TlTk7HJ4cVR5OoQ{)^5P zV(F_1s>G6PLuS!)W6VMr%L~m$i3NFjYw6plv5HH^qLCm}Bl3L(KGb$|fc$ zI=+(nS7dplqeGSML8&EvU+fk;e3jqm`MrHZgtUUOYrg%d+!+d4j??YWHtkcWvHfa) zbl6{^%v#BQ-STS+R+ee@n|CRV``i4redAC0a<|QH+x>D$QLfvp%ueq1ExB~Fd|UU& zS#q%^LDmv4-Yck^F0gv?)?wTevrSefKMapkHqWt|@o|gXYV(U$iJukaDlD9=48JJI z`Ion;aU4ocX{(c;MV-386AKCr*zdd!W1b0fb_xFfQPvkrjzeaG%_CYbeUtrNV(M+D z%f#dluIq@2KX~jTPCV&@nG)CB{|0yv1M7p=3vUtXaMuquRuhvju~`|o%5tlmpSeL$ zT;LkHxyFlvr83fFy9}CxGwOn5rt57F?j1NJy?1R7Tn%(NUm>|xb(kC5{zY z3CoBkvyxZKiHlCtsZJU;(v>=>k(oT*`xnVBm7h~&lFcM)6t|@KS5=EQ$P1;U_skYs zEc;iA&Vpjm`!e>)Wt$sCGo=1Z>OI^b@>I$^G3MM#ksVSc@!M|P6*(rY8TazOiO5G8 znOKeI)}rCkAyEfkX^Bsg`95;p+iT*6vNt1+eaI2}Aoop#+JB$K9*s*5ANu4Xb}O@G z0?&8pc1EG(U#hn0HDa>5WfU>d#s)Jy^tw7I6XV>R(}^)gZY{*fGoCzuguVCW?SuCQ zx>39TqR^v6FV*M}qElX?CDC+GmJ?CsdC_vwMqzQ8_Tq^;ZKCy(y2Z0y^+eLe78Lu& zwg~r&Y%f|^v|H$&a7N*wHbhWfr?@h+ zhOYFGomur)A2Flg87oP9^irU3_Z!Y|%Fw&5!Z_PVKKuT@@T6paqlvV3qPZ#8dAyZn zIoWY;Hh&Ofyd46GQLfGli4jU}I11vq=pio^Vz9FB2+{v*U@FlkDwN~uJ{EfKcjo27|DB92M`OVZsW==XxYo2=Jy@Vr}n&WPVye} z{CJ}SdizW{dNH#sMW{7uzD*-BVyXR0V%RKaoN1uGr@GYcur`6$_lY=iAtIHN-yye?(cIP>!-8)rnv)eaJCpINbvN#4G! zqk2{xN4D})jyo-{m|LYlEKg|7B$nCsE+Lj0%;1@=M0EZpvWtzE|4b}OU8hGZ+^~iF zDOBFU87|nkr;yqU68G|vp+J8BZ>VcS3$B)MQ)`~rLf!4HXszHNC)5n)wItVFM1Mbz zdqkh7KK4YfTz`&-dv$O#+0J*u`8>udTL_6{KayRTkjrSWC8F znaeVwPow)0qF1`tTcU@AUoz1(FOZKLP7^~p&vu=H=iycoaeUrn(woF}rq`6g^{;xj zfag=mWtFFBd+6UO`i@w8UX3emQoHeKvTJM{+23kKKdzk0hmi%;UU4Uh&s559=kN?w z_FpNV!IU}C=d)24ZJZFHk}FeO$S$$y<|BCV&VHWxi=&1FNB*xP=V*D+4>NdwMRR6B zvA>DUR%-RlcHnX0z1}&9Y|ra%iA498o}3NWUwydlof`wV+8j0nb3NErhL6&EmNTNc z8cn{&^Y;2BDJ|5l6`jR(qOiS4jck!u)f0%&zg1$8ILS**oLFOF$Qh_sw)G~v%GINd zSQ!w+k*!FH{+8_W{$#F`vVB=M$u9j`$dy`JP{DgH`F#?5R^rl_Mazp%w`MbI+Q*oV zoqkNAE)!zWrEYlWwaJc0o5xp2j)!}O%N||pJaT$ObdGnuOLUy)@h{PSoe%4@t*399 z#l7rTLC1*}`e9{6lhaYDM1!Ys6-3?mL>@01JJU7ER&33cBTD)UzTE}mei_-&eNTEV zvGS?v5YtHl4{2IK9jwM@9Z(<%%YbfagQRVma*F?FWa(^R={#LSq z2;IL5MKe`pxTPXam35Wx)#Z99cQN6LEZb@`LhF?|x+oA!w|a41lv)PdBD-X37)P{Z zT=Y${i&w?-JW}kF%;Tu&ej2wIt;xJh%Zu`J?3qq^++UGGek0k1PYSRfyW@_h$+9hU z*+#U!=)QtzW$VS`#3I0#mz#|bl%;m#RUxfJgCh~zM7_%BuS9M7fGK{|z9dg2D&}VJ zUZiXCI7>oDOL&|h&u2ucX^nDc*-~QJCRH(}=Xj1!>1iXLSxd7lxl&8+()Wf_y}K2DxkZM8H`)u&hH`ugXGZL$^$LTc=P(uHIL-xECf+8yV1Ggrb5-IJ zW^WQQXa3xY>)33oD`&yf+k>NSyvm!a&hV7qQCeGnZQyI7o|oXMx=v;!AJsHfW6n{# zYG^#qUJ3_Ocovq4$#_ETq9^ith|qEU|J)_+%679{FH=XQo>=sUwi|P!eiXCZbOKYK zK3@x6x9mBRg+nf@*`DYr$fuOgSF#I!3Yf?k zi+RKLirACL_pkI6o9f;5717Ae<2KP?o%em>gx~x{h`QefvG+Rhp**TJJ0kkF#1zcHSGiZ<#+iO=2!^J;5yVIK}kx=K9K0_dP;(?o0p8 z%!`66z}$mDb!=}7&S$O&8ISv`!Z=q@#C=5gR$|*Vpdb2#KOH*Q7xvwOYVY-he#}LV zzd*knbfW&~d9v*p=)?_`xf9oLR-h`bWgo(qS-4+)3BG;BH9!35F2wr~Kf-71KOZsdvOye5 zpat=*SO9%kw`MblxYl<-$8p5rUoac@Mon;E6h5~jK2xBvGZ}=&E*G?YLEq~@Y~O>* zZHK?Thrq?~4RtZJ8oGL+7u(xpK_7gx!gw0+0ntxC;%SAy`>~GIVG#MS{sUA-yt>fG zQ^aF0h&pj<1glYB--24G3*@hNCC=GVW4#f$hB1NVI^syXm z@VOg0={r_>plvd8-8TWWg9dp}4crI)A<%``_9Gvbm;w47aIOfy`o6=l1l#r%fo-4% z+L8CZ@mLQv()$r{!M=OXA|B4*4vZH=umb0#Q$h6M4*z=)BkvzT8;p-B@M#(DU5tW? zxW@ks-B>>!@t(Q}&-cEE-ro=hdr%2+KwAg)Te1Us@pol6^nJpW$vChQSFEAXaSh`^ z6~tI+??+AiiETST_}qnfx0z$#SFsLa*w+gF2#tq9)YiaO5Pi}!^?vkeA&zyhUo$WG z4-KZWAmU+yb$ZcmGKjtqCsS?kE!GPHuVXtg@Dk!t53WT#kgFcluj2#|`Ea#{-s7kX z#ERZ!@;e9LuwIBCbmQ;HW1uwdVK&2eXi5o#Zv3640^REo2dvYMbxJKkEu4u*K`-`E zhg`Is$9O>9wE5$AHuUVlwpJkaN#mde%gHBtuGhB(41n%*P!76bH{Zn^uoXOoF@aq4 z+=9-Hpc{^vui@`K97CY7`v`~{WyXPrVBZFz+gJv~Iwq)xZsgBAAKZX=Aa31=xm^lq zjB&CJKAk{aEC8X!=XdBvU-Tc(JCVBx=;+vvdqHE+4Zo7FfI^6a2y`Rn1)9)}+?3vd z)?Qqhpl({vVqPc*b)iWIzXMpe4tg*rOhtT~8=xf+l!AU}Y}ya~ufRs={uXq_T!`_| zq=08~W~eD>9(e)(o09{!)c3y^E142vJLbPLSb)k0kp`q(nY?lq9 z=8UNyeBFF_oTi`G>*^ZpxpFJgY&2SQ&X{BMrOI_Rru9s2qO6h`dfVQ;AV=CTn*abqPdIj{vfzaN$1qI4e@p(tG3Rf*H-YUdx8wOa;!uhBuRxyL zP!mdH;6}U$0Zo%*aIHx3P{X|gLdISOK* znux^|<4v0??<;H1_9B~hW?|fpg#z4Xhgo@U+y~Sm%^2K zF?7SP`n}K%pW6|m8pNmv`Ra5LVQf!;FgYhxl9hVNDCLmf_m-X!=Hj(5YC!B2NwBl#d67WiHa)Jr?!D0&@w zq(KAl92g0`sd!&v2;7DBk>`#>h||9y_N$nI^?t+n$;S4l5sz;4hum1;IM4?Fokp5j)iOZsaF_2EH$*7FT0u@!rn>2>*^_AGxdW|H6I)F^0|=V(fjv|Ic~~ zUdI0!`iOk!!b$uzTM5|sUPzk$YH$!WA=Z5rpTkU(MDMUYq;@e^OJmkR%|4g9Mr`tv zgev6QT689{^Z)Uj0>340BMykaDtvGLjCljK(SUfkAUBgP;<#}Fy8UsT)eODYp&h;y zzeg>NL1#Sj9|1j&k#`^X4Sk!?cNR44#dygq!TT_G@$^m)de-5&GxC2k6nzy42|Y%i zsqpf3FJ22Q7ZQ5kBIJ?$6TTnjxsY6HnBYB_6!cH;#nkBwslsicnkupJ#Hw&fWCgy= zl|dDv{=&zhXZV+^kV7neuEcsv&nZ`OyN!w#vD{omky!Ck2};plf&#~}Ax1iy?503r zKan<}+)4Q25cL;A&&xN7-LtwX+*o8Fk>x*M_;#+EWJj`=h;znzDfjYJk&4vuQY{^x zBArRbQhl=yi}b`7OO>xS7HNyUFJ-@{L8L7D7s+?WGepuNPf1B%`c)(|!c8jbj-p6y zXq{yGV-vCOL#|3W|GQ93H6%ys_qW5M>qA7O<3Ic@S`d6xdi^IYQMcf^(sw>D71arD zl#%{2LsX{hl*C`;XGyWldSX$!yc)6K8zp^WzMINTVxFElW+&8@hh`HoXP$NdGf?Lk z(`x)3=9umPU=PXU_EyZEJ;* z3Y|@YyJz7^4mMofMp^t>u3hAG8 zYJ7Gj`bzE84Db~xKOlKPEzQ?^YPQ4;<+r{zb4?`l74P_*UjIbAUBSY~Z2x7k7xEh3 z0jH0NEgbi=*Z6BHVpHX%J?{UtT5PubH1`!x%*4JMr{Y@iVy&dUe6q{t*LNj0D8##n zzB?h2r6}h-`NMY-4vKS~75{rJp`F;G9!P%0_i4={#@!mffEXJ!p@$fK!I0w<6=C8; zcEmn&8DhA!ajF@_3m5`KBPq^0K zKjGi2hlehDrY%$j4{QH@A#zLDI%xKr4I+Ia#({soHx!8#xfWRTVZVrdOoP_nu}|pU3o3TQ2+j*IB6AmVB_`>t<%}g<+s-31{>Xt$T0ZgcF*{=1owJfm z`wO#)u`90aW7_;VjTm$B4wi=<))gizR9Ro17+hn-TLu1Mf};uY8)E)}=r>~ZhUjz9 zj@R@0&M}y5kA4@#8rKfD-M=F`9iUI2;F@Bl|4&3qp?CBrqIyHhM52gsAhlO-$Oh)}5I6aPuHDU^{0f;nW_EV?y3ujz@yd0YkjsP&i>Ft>u5okoV#jV=_v% z&tdanqPMBlbfRaO?J}Z!r^C-g*J@`zvvMBiu0*zjiPub`%}T!xqJ?=d$IHkgVkOx+ zk`sH0^7qoO5OIWJb%?`$l`*pOpO|bQ<|VlF6LT&HZ6ao8PvppDY0-TN)XC|RRATz+ z+HhjpMLI`CJl+fb??bB7;7+nrI%m`olON1UV3sc^V#+T*PE6XqYz?zv>=)>5G+@8H z#f&*xp511(JOK$PP{> zJNd-WF6P1!#M%81qs?Tw^_lW0bXBpKLbme~YxdIdogHuOpzg@ou`_ew^{sEab5tz@ zy!m))rb2h!px-9wF;Oor{70guXly!BVOg>UQS@*QdkOun;yknD?NM=~CAo7Zum?GV zR$TYlOI-@6J!^ySYhvaPVP}XLx8v?H^;0Ji({pkxh-s^ejF@WWoXOPD8dj2OT+fx7 za{#(ep|nERwCQ- zg_|VNe2u3)(c~YWMMT400og>o-66w7t?whb4pg$^P<6OQl}YI$LN9NJ`uCO;W?Mn| zE-}YImq%1~wpkVQS`o7rpOr4~C#I#u%Uc}VTInSBx zh2xkiC0mFoX9VAukutN2>nJ6?MvB{ACY9md*%H$lvh30Y?@8H;Si6#K-DSsBYI)T$ zh-`~-E*y0;MRzN*jdy!x5Dnh=o*?Rd6F5rLUK`4Fp*9-Dwt|n~_#mm2%2|M3M4x_g zLIv-EWY;M3npuZ*u2FlIqA^!sW|#FGvNP@ro;+qu^im)@{gB`}X1Z}$J=tlqqaQN0 z;x77R;w&ouVttWSF8DT zdybl!Iep74^4{Re^MO&7hdkK^THX;vy*R&biFoeEqgee;*del&PDD2mW#`26UPafY z$&rom&T)j^O6gXzGY=^HGu^e>uZ$Ch24rVM2%c-EpR{{IcKSqDe`4A#Z$oB5Kszz@ zL1+@QAyP0Nq+-{RopLB)0<$ey5C`{EuD2B7^lWNRK9|9sChyL?ggl3sbDqu3t$5Zo z{lkW<(4@|uqil4>iRV#6P5P87?nP>P946`>@ZqY~{@0)5s4*JsKTrfWhMJ3bnWbBtEpWv zN-#glCd9;(Enbz7MnoPH1x%M0EoS?e%-_rkrKL{4x zCx0@1Lw52(!I?~Qhus~vJ)OQVMd<$yK;J zr0Y6d?@4?0dA>`UYs~X~Qib`Syq=de=Q~N3q`d1G1VQ&*{|r zodS zgMy+USibk1^~>{wH?uoCbI$LanVsFccj=LlpQB~RLV>C6+af)_?VaK$wESwxM&(X< zb6Vh237VAwZzik%{u@#?3;h~1u1PK5ce9@p`h@4*E%eGLoFjDqu|!*Q%_!GsIR0I& zt=h%cFOmJ`$C~u~$@R|5QpS!Fs}|*S<2jJFHO}v8d5cG#L7#QXC;W}=&xhD+c}KYB zPunBW&01a%w?)~RxKCM}vQ!zL9;>v;94BnOnXMMJewN#y<>PrTDxb+etXy57I=4Ph zh+cAkIpq-d0`piKzs>zctWM;3`CK>=WoBVZ!oS?d-9?%HW^#5-nhnX}ZWZMneJPqHZuRHKjZ1@Ed+i6eXzZd=`;OBNe zZ+Q|w$cGp-p3d zB)_Zhvmg8DBkCXQ{RA>zrcU9U`ZXj5Q7$kEqV-hrBKke(gD#_?9eOOHkFOXn#Bd6> zq=rJ~@{9){$LHY3WMWuAoF?~Ye7ugoKXA=I43?k+?N8jvy`YQuc^e(3!-434jpL7^ z1MQDbMTg_~xd|OUf==Aq$M&uz+)F18U6K60h8AydY#U^(P1*{H=ae<%3R=l$g=62u z=UI?rXN-q;F$SvfgX1IbrY=53G+-yO3tt8gLu{PttR)*RePFJ*B8R9ui+GQw?OA_g*LSQT$f-%gSVLgnBrndTdtm^a0@EP6PGSs(mP6`= zq01!tjiAmX;t|yh$pawoaAB?_GF;*#6gS?^qN2(6k>yX&RkCY@jI9= zX>S~QHGU4G(7}Yi_n<=s{(i^`yb4BerRss7vzQ+r#Gh06@F+yTu1fx<-3i2fH2WuG z_h>Yn`YT%DyUf|6=zrz`n9jK%1KKh-($UDTI7gt<1Y#(6W+z~K&_siQY@0BbbLuGg z6kGv+V!vn|PW|q%1YPW5AM%B~n#l1{sW2Zs&~>6S^Ttl&_%yapp#N-i8~+UBqc8pv z$5LV;pIcUMz?XIC(1pK;&;c7I&b?MaZ0>&@e`hm4hT$Kv9&ro0vo8UE$gAOx(s> zjPuC2iHwgm`28C5#8Uhw52_Br5Oi?Dw`_EX!teg9xbbr|bq1R8_j%?8jvL8wqsY&Z zv?t#ekaq~m7#sdO{wKrv_`eW(5cj@}A=;ixP7E81zi-17o|_=2htlsta(L(&K0ob6 z|4*=1^n%p!d6Tv|-uqp+2sXlNumD{~!u^naKF9Ej*jOYMJLDaie`1gYMMndVzZQJuaMk4A>^; zYM&@LgM66+8yP?RJO-)*Vw-~pF9Ku zSYHsM(SNeOT1Ef+(Sf`e*%uwi$>F!Sg20|(#JK1RkRZQl#===VH$wgX*u3Uh7{l{3_&S1E zI1>Mn`*@yXD|Q{=TJZ<$BsMnF&|?kPO!KgR1SDpi$q?H*kFfs%{Eg*v{S&YaeX=33 zc00}fZ^#og=*&S6VmFpNiNen@Xe-~49EDxEh4jmBc_{vGV}2Nb-@kC>i4H^XuY;I% z(2txK24Tx2{2GY=v)b{`LfnrTek>stvesJh0Xak*R&_w~aa{>xYaP!+ErDqFa5{6& zr@T+58E)qJAbjt=lILc6(EkwpS&km$m6`kVBpQ9ggLGJhs-({>XhoXBo@@eox z*!(_zvtQ=E0mN)#JpS4;?;XcKj=!gzI_S5OyzEW;Yu9sb3CB<3)Uzjk5tsIjydR0S z+c|FMyX4q?JRgI0Jf;kNgZLpXFy*ojFA~biQ?z zGRB6MDL2|KP~NtEML4{>ZHsW^!`3ed$EKTx3df}Ri&fEn2L!*1KsK+}z_vVTH#P+eid}?=r z=R&^a(>mIDF@!em=6RU+SfiuO;qGYroym0UbGXK2dhdRi&2uoszwtWniNW$l=DtrB zqJKHY@-wK|YKCyYbGFIC{uAxD3Hz;7B?)6D7Lk;t9y8?@q?F!!9^S!%PnWj{|V=g!I2d8nzN%+K`ux2sL{#ZU8In59-Di_=W2ufJ(NTXe=8@kh9MR?$ZD;y=U8 z1w~`cNAJX%J&GF4*Z!Jo`n}J28x$q4{^awItFXPA2hMfPZYt zYnQwKoA!du^A$y&t~C)he-}ULxx0UeZG8S-&p##{vn|P~^KxADux(Xl4==0rdu_|p z9`t-=C;L-!JX>G(w6#wf>~Zq=Gd33!y*(zLdD-Tjgl--Y-)ymYJ}%4c&`-1No{H;o z`{r7$?cZ_Fxcz?PbK3=RKe*kz`Lk_oe1O~a+txOh;w#-Q-K89yQ~#E zoA0>i3Y$)PJ|pb*st;LA{=9C<7dCw6-=Op}zD-p>Hs~KI*S#&Paaa)6O<21-{6l4U zB(nf(=Z>f@Va3=e-JbVPX|;dO+l#Z4(`T4=;-f z9Ch5u9MUW5u6d4*sezwH?OHX*VUqufs1=X5+P`Dj6y>+?ar-Ra$jDi5yW73(Qxx&W z$Gz?D@%|(H?+b_Qy1f4iPyI2)uFLbwkngX)&SofxPsjzmUFCz#03;mOX)vSc^l?117;A)8Nt^{(LnfpZ2-8ny_Yp>alY5=_=J*BL z<%|nD=Md_9F!$x`4!d8y^74jvyJq{PyF=a^!zS2#;gXSWp59L$q!UdlZEeTaFbZGFbQ zR~DFGwtg+G_IipeE2|N(fLSbEc~1iqw&wb5cju~b1xb1P08*`ZI*KS z_nAY5NoVsk&!Q%l>U`oISbI{oJA7LAm2b7x7q)iwds1hbpRnp#Kda^)(^1o`y65?v zC60)klY0)(?k=6Fs?R=9Bju`tk1*HE)%#O_2rE+e>Bug(dSi=}%bbpDrj}-Xq?uSU z`J85A@i*T*D*KDa{iv1~+h18gZFiqG*;?|3b0-YiJ5gA9-%G*D@Pj`KE8c$PIM;r+jQK5pUx1On>x@qs zb7zI>e3w&hjPq=lD2;38W3g6pbo%XhR!3YjxFkI%O#U$SS7E}RnVLVb3v)Z99C4vg zqZL#jt47x3I~wj6GIRDe*elpGSN>`*h*~LZ+nCi|*mB!=vq1OB%?G92?A`agu-oq8 zX~M<_$7$v^JThJD*B_XlD%-Sd|+cliZj?dk_^D;?JL6xOWS_>wZ`;Zefs8;^X- zHBXuUX(?r=1ZiGm1%|vU<%}zGHI2WoM5_8}gJU!=Qoe{MSMfVB$yJ!>ofM0*!ajSH|ZYK5tih$$rN_nzjfzL!B_b=iPqVyT$j(PPSpPGQ4yT~SJ_$*NQR*clp;x^Lzd%J#ak z3;tAkFA5XZzPEU}a?MgkdiuG*IZ{gdJop!3>ic0Mg(-U?z85A>iPmgP3W$r5a>B9% ztrvG7S*?hPJh#?uzN;&k6Y@JVnmgGMoWxuXs&1TPkE7VJ; zr|Ztic2j+ej&}UsY^(8VeZ-@$>}WY0I8kXAHAdLIDM>T2c|+DoDK{N2ysorV>=$&&C4AA_qe|>PH?62<_R(-SnGBR)-5b;Ev0Q!hf+W!{kefmd^*g??)a z4hg-7l>ATV`cvh1Lc7Q7^?X9SHM{ZqCA*(wPxo8yH1HvUk)S~;|4pRnOfqh@l$`0neqY||q}SpQ@%!~em3G*b2c{Uc<1 z-TwyspnPReEb*NlvP(+QJHk-~e_xH%Q4{%0jP@EaD^Ar9_e-2F`$Na3XtaVm(>1>X zL$h9y?S8#-)hq8?g%3&D{b1=~p;ON)%?InOhHX;D?}Z9e^H=sd{+oNazaU$h-tyBK zq^Y0W@5A5A@;+dASK>mYS9*=G@rfLrM;g-#)uM*C$~=9kzPfD%uWl?^@utl=^$M4qoc46@U zlKh218L7^~fbxtCq2+7iy-GfTc`Kys@j{VqcUe}}OUm{s)oO()r{T7g@wb;*TkQ6; z!!jv%Tj#DLty`I|#;5U@U~AdlxGiFjvQL~vX-+N{Hf%B8WYf@=Geyevw+gi9`fVi@ zTCOYCaZztmr4gxnt2Rlt*WFX!N7>S-9@Hgwo2+HmCeG7g5uqBV(2)_2vNdE?l&Tzj zf2`(j(BSyzWqZKCN%si-tK?gn_+OH-N$CAi_70(ESe|;}`exA*DLXz~rsK$FK(%^_ z{fA^b{^`gOS_?`hepJVIFeQKiO3^UKIMyNLAguXJ(v{vZsHx&ZBM}`QB1?b}!Oi?EWaz z@nk;#|2oub^zdhzwayszt&a2Li24GzbIMTf+rqj({hv{O8PZpIFhXbIy16krU)Bvs zF#L;6nJN2gFQ@DLQ2Sce2`w+pouh2d|56!J_=~XSPO(~4bG9^I%WoO~Lt4#q<=ObV zQr=Q6_n;&4lo3%{+b=#=N0;wE^7c^fEv-*FEcCjZs=a!AlW|_kZmYAE&gb&&rR?xX z(N>|&LuHzktW$ENjJ-Mv;B1@MwY=O>d#au9cCVHvdnYT$`3+EZ1R2}g!gMC8O^qto z?Y^-Zxthy~8vmLjDQbDmBgS)7H6t<`q+U%`_5;eu+(}B?d>s$f|0~cut3FfMCEKgt zDq=qMvklewTZTo1$X4GcqjVPb*&iDrW$)F-y4fo^N%P!eQR+I`?zT8X^>E3}RywZC zyDHo51{aMKT1_tNA!I!}(O~r~ljeQ(CR<%;R3CIyg{#lIsp8e&dX18r)u${Puj)?& z^t@30ZOD4v{%*LggQ{PQ&ernNaXNmg?@tWSa!2wCWo7CSWmNjhN{`H`!m6uTnuk@N zdP?ibZA^co+d+3HyxuW@w$A*qjSck7l~By{PK zF+=ENmpw~pKPgYgi%q-nbdG6Jsp`UdUaf>H&EH7P%6IG>l)pI{_ISA7lyX(6=PqT9 zZ;-OL|1{+w#T~dv=;6kKFIA=ckY{=XAOZaqYpzHNX(+%;(p?N@JDE2`%vyf z(wAImk37b4=s%L*c>vs^c%90dxngU zAz9qxdzkxu%>4uRLfY>TJ!n~$*XJNhJ}<$G@<67k=RpR_mXIo1;F zA4waMck;Pe#M9I{3crS{*-tworc!?*B)6i`Y(y=3a3&o=ddLVG5rQ7q>EjmHD7zs2 zq|^RzY|0{z!!x;dCv%2<%QgKT!{5>d7)pk4+)!d$^BBxS2kaYi79Ebj0qF1}eo&_e z^TuHO?{yy1R^NN@hqKW~ z0YC9+#9-D?HPqS1nqoif3D-jO2s;IdQTR;SxV#Sq_< zz2OG(f_{hfCNG}EzdPK!ApeGXG z+{!f>It`soUJQcm?sTd>b9M!-3p0Cl3eU)4+I$)*W}l4*KAj0U`K?AN}!h_!sa6 z{Pu&(83Sn1e*oM~-IJ`P&}&GptfjDn_yz?+;v3`){|Bi%_%G_&Q;&TiXg8z`T~{1c*iz$SQzHRt2- zM|8pN!L%ESHiJXaV>YC(sA_0toDi3e&&i7j_yqShf?y-#gFKP(n!6qjLkG#zbIg~- zXdwQ`liCALqXYd7NJEED@ef;CX{&#n@tICP^y^Em^dlbfo!-9q-64KWLVJAdi#@|r z(CQQXNAo_5@&7T{2mkT6PZs|F0MTviv-FGYerPbTj%$W#kR0;;7d`^NhqPl!z+Upp zau!aeKDj(-2fA#4ACfP$F^IY$S0Q;6{x$r7c>@~a z#sQl5=J=6z)V+@X*C2T|W+PmM-#6#A(T?ro(X73V=P2gTAM_-ieb=&f zS_!YPcKQ{2=-2%*cpBn={~qk`4)M*CeFL!Di~a_TByU_He*2w*^b=$Qm!Zc;u!3kKNugsz&z&5F8al`QuOI_1|9x{wAp}0y&0d~f5%Va-hKzazN0Sf z_ADm1QrNZ^|M|Neokw764{RR&9;_nX*w#ir@{C>ES^QlMiSr}}IFaWEXuGYH=SYI+ zr&ZRS6@|;1q562xQFWMn}B{9zWlDioL=;svkSM5{s4=o}YUe zZP91?r;y(nXw(xwoxY}DTkaWbg)eZ;_zZnc;+o+$_7O|_SKt@$d+cAt{>LFPb0kjv zMxzg7rQeh2@*AYC7k~E?Ju)C;A-I|PM>(H_LSOP?1MQ(n+5_}6i20KCdJRPfwC_oK zHH@ovv}hWPzm5E&PaAqjj<(Kb9;m^er}6(dbR_T5sryv&oIab+6K6DR9)rIe(@gwk z;B(Vbo*VFhnk(eESAJ@uByA{-*7YaQq_nBc1VsV>*At544-q z1BMabNOEW<{uV>V<~;grn8EWR@52zD2P1a%mwA5TE%-Xm%_PFRc)wHv`u>7n=ja#T zOgFFxE#;@@UW2_38tlE^V4ryg`_i}k$b6#Q%)cDd_f7QK18LvM3gWj1`O#+p^C`OY z&SU<>-=5f$c!2)8m@nU@e|#>ZiPj2i9)jPr*Itj`fy}XI@DqPV66;3v8Gji2{~+G~ zaM$J<&qpkT_V~#-uAPj3Xi@V4&jm$8VtrpN=VI)9;DoV8Tm36s!Sf^c!v>z4d4Yb3 zi~O|Fj@~{tm$2^=`Io#HXi)OT zt`9n7GT)x29-0JVPy45=FR-<3H|wgWi2FmVqlj-ag*r~O7G*jk#<^0H+uCUJm{z3a*^yi+1|M(U5H9p_Ne2E5)FXP)%!{1)y ze$^8EN2hW$m|cp!!Niw%7rn##VIJpPORG68;pFqzIyL~GjovIcgTOy699nDag3Gn3d{nnS+_tr#`r&sf`T!s@a1BZO6tIW`L` z|8PbzxY%W@vdGOSd$?C?IohK^InmQiSY_)uU059~XII*H@+c8DEOS-G8?V^gNVz)0 zKF_<$DyY=S;dp|h)vEj#9KS4WwfZXC-s%4KAZyRGqfVDb54TQ8PI9)ITWg(>;N${>G6Bk_7I zV4ZSEAfuTz!nL52!n{qvWF~9ulRheLZkMNVNUhuxUZHSs&Yf9Qaevu10tJ z-~1YbLkAzTALvsVykpvXcC$UVgxKCY-S!#xj*!4jkv2D6=LhfFeavQ{^Dn`c*FLoV z+Ua6Y@Atm7zSn7H;F{0wwI1U%D&Vz?cGkn3?)Sg?(>&|(4nr*`eqL)A>Db+};MbRJ zS3B8RGJfA;o9?v6_m`X7ZGI_y)sf7??pIu5h528&Ny?b=-8__e?OqX5&fVgpI^}$C ze9Dj$>!*;+{mfKhyOEYY$|F!ztE;6I%fZpbRtnba3G%3^^Z(ftp$p4|Z z*i@drb?tPMFD*a0jeJMZInRA1OzHjVJYn*HDZ@VIT*qv@@vAgp!sVapl%`)a zqvIC-7G(Z~S?bE~k>>3=t6kKt?5Esbl3H13Jait&3h{bR%9)iu8pn+BmQSUe{(wKD z3oD)oyev$8IK)<%($n}{FzHmp8&XbqCwikW_P2O@VdUQAt-_$W#^=Et%4 zJZ}~%V~jMUAGTqZ`yTvsu+fP zT@$AEKyrRkru(@IlQ$Y~RZe<3h}i~}A2!|xl+YM=(uwpRy;<^obf#k)+D;km%pku2CooSHYWHB zD?GA^6Zvtmv`|?3rt!V@lD#dQ|H+dheLfc!ebS+R7XCG|QObp_T?2&$2PbhJf(g@| zg!#|S`k%7fJhde6#)2bK&U<~~53F$`yfkm)Ci-~D*4S4qVZxZ7{qvOJfx4oIE)Tv( z%2BDI>Q}_&2+g+eF;N=d(7R$EmHol~37W#|LP9D;7odm2&xJ<9pp@uVtT=a_OaFwY$`{N|i4uYuqW@i|=c_Dl9tJ z`+jB70A=A*L(Ebxj2eDfSa4vpdQvdDQ!~0CdfbDuJ^%6q%F(UfF;a?p$u~)9>sKU< ztTUbyinu#yrj*0i8=s4ZO$*cP42_GNE!%lNlaAKFCGp`>_Pb_$4(hW!ZM2j<%*LlD zPVNQqQa0C?w+iw5y0y+E6?a^<#for?j?nV?VO6rf?4vk66PLxLDodASza`sCzAAE2 z)|4~Lp~K^~xk}e=nqft&TeeEMD7;-GQMk8{jg$*}_tSZ&(8hQpNx|U`Lyvn0Gh)L( z@cv6`g;!WK3&S4u*VaO>2BymP(5PUYeL`|V*Gf6qJN$|;@IaL6;Qx>DIjH4ALcMJF zNl4x;^w^%hOXw1wqgiQ}SlCU<#QFRGc+0j{%Y$5>7M7im>vvcg94jn68TpyATfB~g zlGCZ`SINNa2-#lzV?m>GRH^z|bgfeJs%TDaplmM+XwVETJZL*1$nGmNq8DSJu}y6QM6t@GCLT=H$e za@k(8HEgc3A^NJY_;SKU<;v9c%G6BlvFL1`>RB|kNT>FqpwcC>zwq6P4ax=8rOM*k zrAq7i>B53j4LZIGp6!;8f2)0N$ksrAi=J%*mIi24{J#halI{M1A>D<3F=3m8zPBRn zg+2?TpAve#5~t(FW08E@7yn;O)vR@j&eVCvc7LvpGvYH$_T%3g(<91Odq1Vc<+iZ+ zL$9&Q2mI9j;-0~;XgNG$jj-rqjGhmQ)+8G7ZcTO6?e-a(Pld;FG*1d=<)_Q`!kogN zg#|ZC>XdJn^;2%D@KR2!9Ib4tnt^`@d;_H9*W?!>w7eCd>RFrIk-PZ#JuU1* zp?5>1?)N+y{e_g>|B8EA=z1biXKkmSQ~OKVeoW?Ip|y8zmk>V;n2NSr8TL=K-=f>c zxIC_`_8g;(_SKPBWF3fo`16(VNp#_Jkq5MVPps-y*qCr$%Wf$i!h$c2|M9NiiOjdO zJU3^6vMSGre{ex>Df2%cX@=&XE!N}m-z;HV`G)#>%U+*X{rr_Y7$@}J5>zSl`YJ@{ z0nck;?@QU^NF-T=|83FV3SF1R9TGY>C4Mb*SduzIXmiu}wz=u8+(A;t&b|NfRqI48 zAF}_>po=kI?e&VERl>a6dDHOoS>q`buXf9iveomf@pcl={2xM>IKi(SWC^k z-yGb8`A*K4l|k-0((*&SOSBwi(fH?w24-qGAVl*c-$_0%;rMG&Wy-TLpD7Q<7b({# zs(yL%lQsT%gHv@Sm{*^+Lifj~zo-n)cth!&iS8c5eD0ExM}XxKq5Bj5&nhi)mw@yB z(BR*NuJgls30($6oE17&0 zOJmgE+|JlPwcIEEZDmQK=38!dlAZx_gOZ=q?Y=2S**>*9em41NRNU+=7TN3ih`*}p z>S3&(T!t9eht3N^&&z(NJ`p2@4!5Emg!Z+uI#1XJCfty+)xwl&A?x@ggYv%;%TLxR z^IlbQ-bUfwMhsJ8T zE?mzSIYp7i{^Y2?bbDmXMx}48Q8vZLOF8?`gcRkqggeUrB|b)cJG?c^Tta*o%U0)u ze%qC?0Y`*R^McfB$33AMcZb#C8gKjJs8O=tc6n^B(0XQqX0z$bhC zJwEHZ5Y;Q|hp+>>{o4r5+^n;ahqe4^w4L&u7#-kS=t1KS0vt9M84n-*7tjUB^Mr#ZiH< zi)#~CNZWBWuz+i}Ct(EFbokf)D~d3p+TX=f{%&7HroIkanfdlY_Q?}9Jziy{L7P3M zuma73F|5SVsqI_touPai8r7YJXxbP6y|}l?IBTWdW^8V~pL?F#AZJZf_wjwOi1GK6>2XT5b&dflLX9Z*omf7W9+|-4lhIERnrf0T-_&-HX4)g=WTSTfyAYmc3QBpWfi~Z z(@Oi@#gDJ_U2r`lK5b|bKs#brAbz%?bI?-w zB)SmCw&&5K7{0?b3fi<`b7UMm$u-;(c!azNhmVsNS0U{s{{rbR9UtUAc~&mAqJOT$ zZvi?m!dlr@On)uR1!Ye`?5$i0tI(kh`+rA=@8KSF=mE!~!(vEobZ%?iuJX8@s^wAxA5~t^ir-3B|+g>l@BuKoug_6Ksjd`2Jq54^;@fj&Zc{;c^^^5Sdw4C8~`Xhzp$ zY>@WSvAGF#5uR3fzhR(Qq1m<6Hdz&JjhBzx(__J9ez4u}_|c_Y@t2Ajdb3g^BPr zIG?_Vi&q?+gDxqM{PJ0W-4^s_ z4`LwWr45bi>hXUBbTIP27Mpr+;8^0&=LB5BXKzQ~7(RPjMm=nFpAB!Zw#2sja>zKY ze;A4#e()N^XZMxxSJvRfNaEp1{YG-ZdmsFpJfYkz89g>Zd=5hUZYhit`fa>JUUb1v zxc7&Tjrf&#FU)0pa9qQ)=uicFpu-yaKZ*`7!)kQ+0Q-)k!$H{0FEOgUz_Ax$2RZdM zIYRrbtKm-a;4e4;|A|pe1peRPF5v(0n|M~Ed%t%eee_3%YHS>UJ~a=rru+r|4Exe< zA83Z(v9{#cx(Sp;XLNGG=lVsgy+tSVaQhRx$pepf;a2n@Rt;y+<21a){NV<_WSpR3 z!+!E&CLB**yaW>&9}To~7#*lrpTm6l8T~wu4)dThI{bqj3s^r)#lD-^%s8o;OkH%X zru`g@&w5+<9 zHDw*dPsc}S_W_8FHF>Nh@wEm&99^+zF`SQmzSO6Wy1nQmdeFA(I7nOWufuJOpDmF6 z76-TyJ${7r9ZI|PVdTX*jz^ccFJLO44M_XXq67I}LrmlwEj8FwjJDOZRdGM|p?NL& zQbjwB^i%m3^T89a68{-f6(8XLAUKA&r$Hy;Ol|v07ozIG~+!Y;HTlm?4LHy$5>}_g>uPyNKV|R*H@C>|QCkJQQt8@N0N? zh;}2shuA!d{UufKUyh&4Jrmj}Cr7PmrvjU-X3;--noq(za5lD_g>$g;ak-YjevYxa z0>9+=hwzK`>?q4UK>4Jw_FnQt%Gm2guGR)KZ}?GvE%PU_ttKY2uCHcWQatS!qC+nI zp;tcnQ;~;l#G$;JV*~iRKjWYlzldAg)7XEAaZe7FVCR4oa%Td5Coz_;5?{tv5jKxR z<03Df7jk5+j*gvXh^<}ZSRvYsBZh_eJ)ZtbHj@;8(EbI;Px)Yjl8f?FxyN7?agiV6 zou2s9*C^Ng@E_N}C2U7K>wWNZ@`d(mcAy7-)?_n(jO2L6WndS6<4*({SI%R;Ou%pQ zJ98WTi><`B^aT5EVc!bI!AJOs4)P99HJ35!>Pq1HqY|KF8=$%iohLCLB)%p<3W z|48P~5%|owiu;yb;rLiV``A_c7IE6kxc?mg^6?uDGJfLuuX|W)FrMbW&N-$Ee~vJ> z5Z~3)7+YxYkeS>fep~#Zh38-#(3rg5!LbRnzl;2g|AOaV(&2vI6Z0!v%X?z*IQxI* zGAuM@ms?>CdLFguR8Fz|SXp2nrA&1oBiWzjI7V6Q#OS6x(^(^*b-@{{XlI3suP|qm z^DSXscjI}A!i5fu5c264s~*ClM$<@_Z%rXNGtD1I7Mhl&-LU#TZ=~r=;_udvcl*oi z8oSr}&X9C-Y~*d5h^d#&8DU3kBA0G9X9WLlgAErx| zOIEv%$C-}!p0cX@W4PdY;PM=%auZ_Qtv^gq1WCwzsA~m z$PKf3g!d&=|37NYQE6Lk9L26QM_aN3oi`Z&?@?-|!&6dDx#Z-b+-bZYCS`^T%Co)J zl}v+a?#W7PkDkKhA3diiU-KgKC_m(FaH!8%EeH5A6R^hK<8$09)%1AK+un~^oNTvS z@_j}pe`Nc$=TV>Ut72>)cN^xrsqd#Yo17ahY2&w8?{L^`dHnAAR`1)*wmiKq*eb|o zyQSauv*yLtVZJ9{x@fkwvi6NW`lM->d6ZA*sUMjFs=RlfpU2eL!|S_m2b(6EmwH9~ z^pt5Ks~wM@cUVv6EWh{qS*xE-54v~Wm~6E%ahsjSCo#>qi=J@Ik+TkYG|`FC2i;{< zlRw8@FDbj+hbo;s$S`txy_e3cv4460BIVc?-$#Wp^?uq;)CGA8n>q1VFj>#J;#zoz z&}V}2`Hw?-{8YD>thQPIn{XlaJ##nH>BQQSM@-Ck2_N>*87cnP;Ya0&c!w#BZF>0a zF80#HM=OGa(XXvrFN|8f`5|HCuqV5O5v_Z|h2bOiF%G!eS$?RSF!byj!<9uxRtZDi zJ@z-Pra6R5DdxDN&I2)HowfHE50~SzJ^E$0e#$=X{}V=i<+)T@FIO4#`k>EcVZ>p% z8l~4w{yNiy1qDS)Im9vKwlLs;@hwd6U*&Ef=aS{dd!d;L?s8@xU_|W*j}vBom#%(g zSW0yyrHzs`JDK;tULOjRmk(BdlUl|EOF6N066aWSE10=f7~edfIg|)(yyuEA_U+|P z%FO#UA~9RnG)g%pVtrp>^r?;XA8B!9Cc%&6&H>6PF1wV`ZaQy-zv+HX%Hj2%n%`ju zy|bho=Iv`G3@tV8XNH8x+xA#1y%MDJWWYsv`krg_vz)ST|JE-HFKYqeP$oSk3mk`q!b$LqT@W|jO$@3 zhpccPsEqZr6$bC{dR1xbvsf5ZW0@)pZ1%rP=>Kn^>gP8)BuvV_`C+$&Uinc=gsv~f z=L+rSrwRDU9c3{4j`I-tE9+a|7lfH#g{prUf5c@-IU_bzVFzITaMCI54F2cl{9Xhiot{tioODq_!?I-*;f|)MxXXj3- z6?oi5?GC)#ZKakAJakkAeCl~o$^q@(8a4l?jr;q4ANZ*rmhJNG6#Q-rx*+u45IR}t zSsF24=z2RQU+7qx=qWUxProcA{%KYr!mQEG>QCl!Z(XZooC;he+cR<_T7>D_;+|I8 zq&zB28<(Y)rJl=QA?4J9lA*$s=PS+1s9GJ7$xk*AXLQML7LYG3n%PNr_bAbFQO^pc zRj)JT?Z?KaYJShV&XlcwbKKpOi5@yDSq^(mkg_Gmr%>p-$dV}Z+32rj@9D?X>7D z=DACQ>+=uw!?@s|5&(v+kCrGJ-B2}+c+gQWj*X464{O(LGSNdjXek7mD*7+oPQQlnH zo}5#lGgZ>>#cD~?(UL!9d(!%{`O2~K%&u3Oi>m7t?W(_B2Wv|N8$&KU?BJ z+0OC0Fy%Y92b3=vPwb`4@^jSk&>*!WB{%ddDJTCEsTr62PRu)6ULUXVP41th{wDjS z-Y46WK2JCN-Q}HaevlD{cwNIRmZ>k8uuEh<=)%K z2e(^ZC#38)$wyUoebMrolwDph&X3MZgM6jzWE-+k=-?1OLTGz$)CQqdY}_azcBysv zkzlr$a&o2ZSY?`V#!4=9U8d!9&pt|DpDV(o>;7%Zi$VL8Cqs2)CGCm$NXrYN*C+?X zr7BYr3>{2KyQQ4?d5V@352oq7lDIluBbGQdLp@F$nn|X+b~+!I+OAVvHEynh-E}r~ zjrY*(b9v88^Vp@*N6!z=_ge0e`c5nSj|d%m1%4~EzaXE2;s2#@9S_#yqXtXa) zB=%_ZVU+oE*^yXot9hN+>6oGAWiH#48{L0buJHC(E;c@aPMqhj<2!L~&{^F+CUlOn zSNJt$R#ciYI7W3#xMQ4e626pc3f31#8}53x!IVt9Bz9)EMUFtM11823es^ zkov6K9RK4Xla2fp8*Zg}9lO9*=e^hy4x?pzoQtuNiz{{AqvatUvC7F_bCpYdURB;_ z(eVkykF~0jJj7jG`gpPdAG|xAyY>4P9XD1_7;keimj!Ab zu@XHX`&oJaWYBo-7G0K_LuE^3qP33G$ep%Jr5qJ(uXzzQ-tiSJA2Y7tqyBMyS<2Cw z?mLuyJf|sFdRHkQF(MMZ)iPeo`}{5{_Xp%Cj|Hw#o(Ote`EIaLK4!dkCi-Z|Kf3*B zD4A|E&LKleHai_P&uyM})>+%;Nmm_3HsjpYdh5SDbyZ_M*gIV6TP-#I7Z>vwzZay; ziZse#aDRiLDF(yb{^MHnV)-jPO|E+3tF|4&h&1~ek6w)4Yy+ z*~3%I-+MkOjI#2MQ2P1Yqs;a_r!4f-yooCD*MSpNBcC5ozh9t^pQ!f0H?-U#-&<#U z@1PUJ)y6(vO4fA_y4QN7(*!MdxM)6D$Gcfe+3Ki=juWd)FKyL4Og;_dr>6xq<;Pf0 zpvP-QIru*vf-f4+frP9#zbSh{ORc9UKeJ60hSk~WhzdLIutdt?*-olQ_%i21TK?SC z(80A*3Pt3#j47(llzC*X4wrNgTF%N7QeZWvE)x)RzAWtM=j)R z5!eTkyFqWkml+wvx$+1eqHyJLEcJt*pgjFmzRpb02~jJK@h#soOH6}kko+hd#LAL* zR%WmQN3RO(%EF$CH@V040mRn4@8DSO;n8MADfhOvLm%VbX89HF^_}9rApMrd@w=6M z_${AbRQ7F4g&se^k?4Uh6|6oY6X9Kqcz!EJG2@+wWti1a3qRVpqDEancQPj69hvF$(+KVB}!9i@advA@$?-!h0AWGa&w? zU|*>x*5Fx$`9NW^;cV*1@0PEcWA%d~ec&Tq<@#pATRw zx_k#Wp+^J!1wH=67UJQDwxVCaWk^m1i|*u7C_a}ABrmX6Y>r~Q$p6I~dy3<4Gd|F! z_-p2ghv0T}m;li~GY=M_12z{yMdU)18NR{zxCYlV zK5jvLPj-hX=z!0K9G7tu66b8|j18o% zc#bV#TN1v?9GH3#cA&!rm~7-j{ukIb89T_Ag1=x3IZ_I-v$UOkjH7belxGkt&^&Jm z{tt&k@&8GPEj7X@{9gsh?>e-~ew%AY;+cajPUL7#KWKrcVLCcB!Nu@6*J5au*8>uR zJo3`joBpZewhU6oqX>S09_WyN13l2XfVsyHy9>yXzyT1A<^LZlpsjG)%>SNwf_?cf zFi-4+Bheugx}yW_=8;z!KSK1(#_v4($m5t?+80f8`7OQ!`;!OwlgqIcCD{Kz{3qXX zUd8{Fa0C9MaSnagUWfQmhmSdx#^>mnW4VUnHI`YkT=@rF@AjKLiF+92iX>M4We7vLO7c7 zK|J$3m?v)09yyS>A9kU`Y#4}bk@PEl&*OIv8a)Dur_5d1*dudl_Fd!wzu5(hgNGn- zu0}_Bw{2}0doSUk-reG|jlNYvVkueHxr*C3y`yix$ z+xMuyntD~Vp9KGgY;(YN`L2iK0*If^?buB`Ttz3gd(=YW>y7rg^ksP-=8+flor@o# zw3qWO>xyo$3my8vd~`s=?B~z{JF?L`lfSbajW)8Dl1t);EqQQ^eZ-=ScI6#JmH3hw zfd9-786V^SHpt)gXr0lC-{K!J?dA)yQ=aWgzX4Cu7rt2Efy6=n-;*>nmjCf0o$+9G zo%+l#R{z2;*^Zr=j~n%~`lAoFWZ{P$K4g<`4#ZX74eGQ3e~5=G{mZvDJ;;NcAjS!~ zmVJ}FSO<4=9{B{KMFcuz{e})E*ntk4=;s}5Nrz~d^(_74SKceIj69f#eP_voTadpi zlOZ`#8Kz;<<{c@TQt? zO8D7eBKpWr(lUd|-3_Mr|HsP)F;#!ka|~vX=kk+z>OY?Ok8X^kF#Kk_1Ab*hk!Jj+ z4<#?|!S7n;34T)}7#B0}^E7|IN&nlJ55C5~3HaZRKWJ4m274Jp-H27(c;Y*fV_x9- zAo41fe)_kfCH@Wi3gY9{Z?`4UaP<$XEiaA+sb`}BoAydQ{h6M{DLuEA#**3;m9ygx_! z=I@2XA##dgU*s^;SMpcnc=JW&5-W{p#&+803*-K^TQ5v}!A9FjS9OSaD(B~;_)UHV;#bUKw28yNEb_hz`!dOA z{Fb|Zo%n7^;W?O|j4ABB|83?PUz6!kG;nX^Jumwib6=ZG2k^iJUk@k3F}xq86VleZ zj5n9j{69f>=JGVeVppR2E@RiVpUHIM3G@m#?h=KDSgF0C>DKC3XseCEY4Y?S_3pD< zr#xhj#gxxF5J7myv9~ZR)QPCVa%T_aP-oRMY^=);Ezflwp`7N12l%j$v*ai)UF~v3<$CZ`&>NXI2Y6tVc~Uoi@3944*yTWXoh-u)INz zbpLRpx6tj@Hew3npE)3OE!(GK)MewQ{7*Rpnw^GLh|@?46W5jc?ZlzT`-x*#3-Dqw-PbiOPvCTb16fWF~Rk z?A{{u-|xZf#F{d}+fL}yCRgiN+cWrmAsO(egJw{~ui=b+GJSid_8gW_@sN~5_BE3a zoMmVAStJaq7-A6y1`u+70{kbI3jNEb|0DEkm=`IuEV}zSq3;Jv$p;vIoeV4+|S}PR?3#&oOddB zx@bL1rSbnq`EGGnzkPOjzAF2@ql|Cec^tC5CuNs~LBT@n1ySRKjGzM!GlbF4S{@fh zmCALw=#%_^ti1@!A@BP%S>YnbJp3a1p_xyYb zEt&(VUgnJ=5y*d{5l)Fb0NajS`KY&Eio(CFysc*@RWF-AbQ zM-%!`uA4L;entzZrL$NVM@n@Li)K;Y64R{Gc_}$Z?YB~@woZdaD7ACg^Hg+Pm2zTh zXKQXC)T+=*AXFu@?*S^;klDq^&P_%%dqs`r7~RQYuf=F*DX}B3Y~GXK=feo~*N7@< z9buJ9Y^!v~E`*jB-4|0@`(k{9E>iE3>YV5rwcm^XQvM_LVU*Ecrn*dK4`cf* zMIfbId74l&S~Y`EIanJb659Q_ZW*EMgaOSTajx-4V)N!&3JB5ueHm@WiZ75?)+d!G zC_VM0gjSWtpC~(6V!VS6)pk=T+dI?zwy1SKKx~Uh@8^W(587%{P6(h8nezf465DJ` zP$OlxVCtFa&(LkeHa!rwjB;)_yibuMpuINKiG&xdR>pcPrTT$AF&0YCJzV^&s|1q4enI(%Bot- z7{O*_S^m|kCFPcT^yzqJIhuU`3ATZS6QM=D4P!F<2CapaGi_hdMQPyFhtTY< z3(X6&61Q{Ip5d{Xvb$G1N?Y$7N`+57{H_zk5KHPPq{l(&0#O0A4~c1SlU|ZqQoB}$ z(FEJ&viYG>9|i3vl3kjeNx8UQ%bZZOMu+xh!85(H#O5tDq`83ILC0IriuaP* z#-dV67a3h+ZmGzmwh8%O2ewn_JRvmuPM!-3zB0N>*~p%&W46aao7!nsiIhWZ)=;*y zTTiKS7(rW!zDKFgI*dTXQSatN{&eoqbYhLSxmk7zLY~nVU(HD zHk1W&x`k<}k}7CgtVQE9-Ogrcnr_o)_Ikqubo+erTxHa^(2RO$I@bILwfkFEQMR)V zq_nW1Be|)>wwBl?-`G47lc)Bpk+co%#1`1GU;E+x)TVjD?W6mhl;a4DtRst2v6??QG~}&3;olTKG}wT6$7Stdx{ot5Z0R>$3Ue{9OJPQYzpGnkc)8^eLx`CsIx(Puax! z{<0`S{y!SOC}%0CSG*mXg~aAA(W0Y1&R5j=uTMvN=ut`5gReM02@QMk=@y1tgtUE) zc;akQZqz|aGtOwP#y)CSvppEy(WLPjz0?{-%8j`?G#+D-?saMl^rIOKE;1TX9gR80 zR7ay$lPRR!=(lNq%1>srKN-C-!??;_z@@Fjlklp^THX{sZAV_cka~$Hz0thpOT~Za z`d8%Y6Sga4^T&DSa_R+lpziu1X3tU&Jto6)Zy%a@W8{RY81 zLIZ#D`?g@VWEEw-jP`3o4Y>`m4ZA34KQSE2^20DiMc-$bq0P42s6+Q;xJyq$x8I>} zM_FRvPPxyJ>S9=A_>tOKM)ZhhxY@WZY&{P1ub6w3tmRtrzEY+Ls1Do;a&->nXT^NV zGRbVpB$+ND=Ys~#6HcI_g4!HSb^f#Y<~YM*>*?JxvW3n|E*%$i7qa;vx~+mKq+Bmv zB&WP3-b<)&%g$W%N6Kgm=@-epX!&gg9ajzbnp8&vb5$==ZeXu9gR;GLE@dAbnpXzB z*!^&WA$kL7`4BxEC$aq?ecHkXgAC|?Nf}+1FmSI?hViW^mkK6PZWG?4TqYh*Iaoro z8)r&o)aJ;?F)A$>HOm=QHH=#9eH^VHTpv=Ry@7qQ)A8U_zjO*%|IihQ=s2c3UE)Eu z(>*AiN!co+`L5?77ZF=;vZ4!Ro^mW@spfRbbE;&@>smB!y}RUo9kzd?eV6iw4%_ax z&R1&xqlb%g{&usGaVzMX(akzv^1I}m4 z!(7?|nn`>uVr#YvED2TP*}MqV9Z@G@YYh-n9kh0`X+Kh~?Ii0+nV{iHxkgUo z)vlDErS???9m%xcDy^ygMOi}Gs!44f4b5f5)-ln1j%${VEdH)8i~(I3-R%EU7j6gg zE{u@$d;)s-F{p zY`oBP5F%fpPmU;x@{O2!pz0toC$=h0@|N<1lxD8#vupvewT#*GX0!s?$fea=PBT#} zQGTDUPhm5_w9?s(QLRk!%@Qx<7#U|gZ)1Ba?KaMk?Y~US$K~&GW8(pSPsU4zF z4hW4+_k!h-VmtS5&;j+kLkn-b$GrtQbOxa#`F^1LIp`3JI?#R!GcXL9 zikxt@01=z3Dfkn##QLt_1n??Y3SHo*E9%f3fVQxO9%DentyKt~LXVSzZ=na;#~t

zT}(S zywCt2K@a%p`UiS^!v4j`i-({Hc>!JAP^SeS6ha4Ww!Mu4M4Wb3;4$cc^{(5I7x%yn z__6`SXhiPOxc0_-%R%@>?zy-kR&vkMRS6vsqsuSo0Ndp$;>W&Ske5E2!Sm3;5_Lbp zkq`bk+ypOz*iMR^bu2Aj}N=3~DC|Qs0#ab248?E6L)60NuKO(w;j67g-=*7MO)b; z?`81G0lsQLFNc}X1DZQrLVq#CeoT=UDiCGl8*Yw^kQc}WNAxFyTi|r`57Nfj=pUQG zS?C|o$`Ng2l?3|3r#&F*A@j-{(Kj6RQ2$NnAOVj<2l(lL`rOcF4)DbT+mdSzo~WBV z!^*1=#J;_uzk?3qM{YO>S%0wq3~s}|xcJQ77VHaJfG0rsMLx3&yMs;OM))!ax|oCT zh3H0py_kFsux*7d4e$|dF2nom-b0T{=o11xmV(*P137084YlgPU&sseEeARBq8h|l zU^E2fKadyKK=?(z;YH?5S>m;Q5%xI>gzt9P-aZ;S2tc%{vn7bW?y7@z$U(Oj5N+%+ z5iEfY(8>-zcx!=E5WhW$IDOuL@Q=iA*ADlQ5x@BXoGC&t3uwqkEEdq0kM_0<2iJmc z!AH<%70#T{rq+JoUl98g-i42&q01leCG_Y8UE+`@pTIrP<0AG0-4(CdepT4F9pceO zj@m6oUMvT*&_5DD#BKte$#*Br?t#A8H*(F6gSvxIAKHiLV2d_!bO#X^>GQT-pu>F7 z0R3SQw*86t(a&t)pI0u3_`I)!h{cEan}+z0f)fxw>aa<~eN^aVIu2)u(AN~Pahu@7 zF0cmrpqzUfx|m?S1Vmjt_-dIBT}05O1NZ<$8w58gnYd_(;{(BmoFuiO$m zjBx`o*gQmD#DK4m7u`VQkHK)T0sRBHO!|P?STGg)f)6%P>OU^p9{aUE3mx)7w2O-Z z9ECiH1fiP;>a&KgUb^rL`}RgGR>u(kM{o<`=7ZTF+Q|xfv^fYSV_pUHGw#g612e!6 zpd;F(2E_L4+8=yE8*@ydivb8f%~3z+33MrdPNncQ2>R><5tjfySPev;>;|!aG1|gf zj{c$#24Xxt38K9<4}r*U?YCe*^bfqYMlKkk-0BVXiS4b>W|mXI1<+wHi1x7Gjy%|G`@#;8^ME^M>QHm{sclp;~AJw0pE?Wk4{^`2sXcfJ-r%j zvXc3)pUY^loY63i(MW9@4`;SXJfmp}qZ#%?7IVZ%77JrWbNI(eMtLvj;RvFwB+C%r zG33Q+FcimABg9vWd{BYV(|ix&!G3H9z|S@42k@8N>vKo$7-7FYXkSCPQ-JNScoY`P54C?GOvM; zeVD?38Dceo?%I6BI~#xQsAm?&ioU3~3)(*%`$hcZGqK($w6i~`i+B+Sne*P|7Boc6 zVR8`p)g3;QtAG)RSsVKG!ZzAtF+b`Dh`!g?7epQXTtPSR1&Frkk8wx|UCE+}_92TZ zi%}~`&1+eBtLsV1Mp*X z0p+2%Yn0tap)VoQ((w_5qCZohCD>!e7ee8>Ip|{`cL8k~!H^}9#O9Z0TWMHuz7t!cj7w{iJMw6`JcF-6%H_ZKb%cs8Y`%~p zSr||4Oc62~<*DNKl-?5bUTi-@+CV6~r9r(FrKv^}8=13G@Q_e9Tz5U8_IV4MNm{!d zZxdU!+Y{}GmS}0q$O}9}Y-M;b`Ze}cLY^UrJ$#QqyMi%&b`xq;4M1Ci9b?i6WxEH@ zp&T&GgHZZ$IL&Nn@d)TC8c)igZZ9=Ia3+#hlBHaXDA-zu+en$tTSfVrKbTM!DDb8n zD>R^-BT`T%icKhWB>f4cW67sj)Mufwmrz))+)RkL(PPP?CuHAu*Okdn5nCsM{H`PP zs5Z8sbhoG=)Y@tLg3^(E_JTf}-QhoI=$%cdSk(OA*DZgCKvR25`2X+ zpFGnGc0{-qrLjS_UqsQ=J}9Q@i#tka{}2t6VZ=iHjq($OJTAL>3>~DzM%*z19YXCV?E1WRv2qx- zd$VthYV!=J(prbfc{lW!Vg7;A!J77ARkPg_Vyl+1-%(L{xl+$HAGx0-<(he3R0qx8 zK2#q~rQcjquDscnmMcsAOL2_fM9SbF&3@=Ig~KDZz?^f0vV@yTC^X^qqf8;A8|?i8 zC(1^l7iG1GW|S~lyq4I4`;vbM`Hy5YJ9+->zA*fy*+@nXvK}nqZ==ir9%dz00hCGQ+~3a;jxDWpAr@ltDJe zl#aFn%rPw7X-KU9w#;KCTq}0m3D*ENxcTIb7*EL^?B#X7Rq??{55ceIEeDNl#W!&TN-ny{YJt1{a4K; z)c(ot9BOjO^*_Att1fK`<$HaaU&@DubbL`Z8qrvkb;fjDQ66HyXr|m_N;6)$*$nGX z9y&o)uj+j~gw(dn=g2t1|F+nwGbWXrMAy~wMo~UxcO5uQf&L#dLgBjAb*E6nSiBrs9a4j)#gfN*wR7 z-7WIHGVqC3H_Ch3>nI=T+^2k?$ECc@zSpX_LGCAD`&xq%%Jby;5{Gs+P?ah@8Xl3- zLjO8C4&*(n{YC6Fvy=A-|7{t>UaR%s@G_Xq=G|iC5Hnjem{CksC+7jomeT%&BaW2J z>j!hVcPT&f;SY{;QG$zWy3QO`IuQ-$IXfOSuhnud{XQ z>q&XilDbgBe_I6XHP?-ir`CtRlG%bwjKaT+Vmi(sPt@fSe@-x2BRS2beoI|>IKM;w zl=06H%49+Uj%)y%p(EQW9!TwG$xK2GIs3&&4L?~awZk-Mo@fk_7gIY~kxQAbjHg^h zt`p*Yd789kGz!S|b=XC!YCL-{C<66GxwIf-ZD!F4%IHmSx55j)8nI2)Q z82x1zsn=wkdMRh*((w@^$3M&8iW)l}z~D3+rjC77T0l~6pBOOLeT*F2h;k`d%O z7<8%>+#!@o$n#La0c@s@bfx$lwNFWQQ@)a>Q~r^~5y}iTY$%;HE>O0SCsOv5|DcRi zjG!E#IFDx%E^KWjRzVhH?iI!*8yE+zy3>oS@3rGL&DIXfn`u_MeQ%sg%5_tjF68z9 zx^PXH&7*qah-1ra{uf5UGDe|2XAyZNtm4v)6Se2*5L;BndqpTV<{zaTCs;vwmYunZ z|A=Uu5?}JY7w9!gyn}KjyB{nml+ef|C!~3_yop>7!glv%iz#2rX#JAk8X@Qh>UdX1 zvbYz;GR_*tI98J}=*ctM-+jA2p}p9_@i9H>N#?ZFky<&N8?;|>IJc?Ftc?Dr#}yn& z+*ld={sQvlIJ5bY965Q#f5X{JD450_K>3wNz!47RRZ^bj4<{6vvGXobf`E>=qGG0t z=$??qE&4}96&8DnjmY-mZsMJkaS~0+$&yKw^CYJ!mrJq#Oa+TGHANl&0mjj;j8Vyq z;m(YHqiF=7kMc=XIfFpWq1iJ*p`Ov>@dMVjZrFafPeI88{3Il|3C8n3Wg z_?X&FBHB{IHzL}jMI6y>QZAB-(PL9ZEWW9Mj0r0l`@duCn#$;x&FB!qXb{23;e4W5 z&Eb4kj|0EwklHz%f35%Dk!|&F|Cz2F&U04A9mb&<$o;~h{_^6uG!uEp*e4#oIn#xo zz%q-!jqgC-$-l{8MJQ0R9w;yq^rv=+U<+k};05Jup%djIVGMrjJBj%j7sl9UC}WpF zj6R(hT?!cW?=f=p)%-uk`~P-3;?w`QxN=0ad@YA6#T9etNW~q(^&sWk!(4iV;=bYj zBsR~E&9mXfknhjI&SLXbc_n;zYMfk>^S6KD^$zK7^yW_-&~Vk{%icd>B6Cru25 z7DI5%84XUvC-BSQT3nmz1Y+zrECtb~Mi0TgxQ2&3wy1#*W5Dy+XC8P4bz&Pr3*N&UGmKgQxE8J6Pyb@pqc3f=_=N0{0u!7BNhYb@fGyK7>qM}^Fh$#H3(mf!ocD1WeJGbOc1j#U8@53kS@FQXAoMr=4jn?lZ{P_K`?0Zu_GoLN49vs``vKfd zjzl2ZRERbvzq%)!2Bv_B*8qQ_QSc4Aigm!l;C1-u2|bR1dC=n&cm#SNca5Q=9Q7H; zLl3lp@mA<@0DOSFa79dLL#;Bf4f4Vl><>NgUXw}i0sfk-!9E+o9jG%Lghs}5!9x5U z#UJW3MO`Kv5&Ls+J@j}Cu7e)6;7aJRkkQHyMDAO`FOy}^p)0r)#Qw?CHTf67?jSTF zeU*O|ME??S(KgUZ&>LJ1B4&LJ=+PO>0N;YhLD3%gIs?rdLSO7pV;S2#Ecv_x|^Uo zVz2^Tpab@0j5Z^AVeAGS#(>CG3+QNU1|1Zj1y}>>LkDPWj5f4_uf}Kxa?g>>3g;n4 zE#w_L+nQ%>kLu90dm;z zGIT&)hS1Wu2yB2J55XqrAOh>5gBZL5{$R8?2ciuvM}cTF@;o)tK33?HhTFg=@S#7B zD1$)kmrx}I5r+yfaLeGEA&5SuRSI2Vpif)y26!8~q{8P3&?6W=tDpzkM0XDK@Bxu0 z;=#~oJoMNFLJM+!uWtf9@z0FaT@>k!MQO&6y8<_+Sl)Sh%+EH421ZT3qN60&ajFc&&~7^Iw7&p$lTs ziH08VRR{YNkAp6FujB=|5PHl65sMsoMy??#S`e!f_5pwNB2g#$rrspH7qRH2V4HW~ zQfRap%z+N@QxEkR6|!>U&)_oXfI7&mesYgqZ!L5P2NyvH=ug=MW~L?7TJz-Mpp4+tH(hoBG2dDyp>74+B+LMw6w zg3R$2IfKig2ej0FjD7+?b)db55=33{W^e`SMy`_Yn5YWC%h(p}pab7^;e*aY=zw^1 zo}mqE!6(oG`AgOtuLse7LSMqo!ihs6TAw(WaZ>sLgxYE9|@iVv5n4M=l~xi zzYq@=c1;6q)rZ;trO#Pr%h4`mA#(;Pa~PFcV1LAL6ndcjG-II$+Dr2}^caJfMnjJ) zAp8{#ggzeFrxcuueIgIE&Oi^up!FJc6WyQjL!_@S)>9k3sAPC|~A+Pa7zV-qPiN4t}HEslW(h<^r%?Z|Vzh)w2#h{{wjdk!}H5@v$0h6Eu-cR%---J{pA|D2TgQ0^N7z!QMfE}R2 zN6-)X0PR$55q|`;EwGN%ZwYNwz94*31tNY@FClbicO@~#>C-UiZ{v_xqW8=eBiG0x zdB!MhVw4?V)L6hMcTh7`%`6bPrLcq^C&6XV12HM?Vqam<#}WMmaVg=8bPKo$I*@*s zfxjX6+W;TYzRG;);0&T)>BWOfpaWhjXF-RBV1L9f0J|X%(2tZIp#$HFQz72Uo(!O6E7Okdd#ZU>mcAdl^Oh7|A&{StK=#(xZ$r#6lL0 zVQQ-TlSZD}hMr^|kvs%?90Z|@NDLOEuB9OABga*8Z%^?FJO&-GZ~1oUfc7WPu+sYg zLU+S~AnGwj%yPtQig?IV>CKQ|a*Rh7#MVdLJwPqQ-3!z}y!N0Jd<@EP9+}K+n?KA) z`rnkj=Au5b@Q_Pn;rC}0jA0Z)bFzrC8O3V7BxTH&s%;tCi!8DqYF4OO06i|D9DP7A z8GMAi7zJW{kfG0!Z?lkjLo(>DaUwrNM-U&z3egV4*9dOFv^O&laXT4-nIQBKq2D<#0asw2 zl?W^ZM-m;xq$h(iWGk+&)r#&BKG-itYy1z(TUN$Z=Mo?OkcF?d1!z~Y2=6e8;1gNI zPZ|F;&wyPUMEL}4Yt8(WPseNcs2h!3NkrVxj1Svd49%J`Pi!;@-Cd3%r~YETh!uDm zr$2~*TZQ>T$Xzbh`A!9|V!oIc_zK*G_X$Aw&Vx2>G{ImHugTp8^31Dm+u85dzwBXl zhM`@Koamg#T?(kDJ`XYz=QUBR@h-v?o~v^EkSc?>IC= za4oEkuK2HiTtg$|Iy~=a^MX?3u#T>*ck!W2CBMUm#o2o$C8v!YW4koQ4rp_-bVB@O z={$)sSnW#)jS%yrkTYcII!eulxEL4~fULok$ZYb(F5&} zeH_ldv23pe@4RU3xkub9N%?tZ_w;B-$Z7T5hxofh)7qNuM1LfO_4U!nLYzuR_V*^N^y!Uk z#C;CO9vIO$oV8(LwErw#5d4+c$yuF;5+*$ANNw`^f3s|2n7JdTD6n-j? zW(YrB7)Q&ulF##4UoH!zJSbm9S)rsY#owX&LhaQ$dX)3^=orQyW1vCp9_$hWb}uKL#TQhjX?fsUu-kX(C234rga=0=3uA zh?_#}j0v$AvG5F{jF|R>qcaAy5=JHV!w80)Yu|f3p;uId3E}^+;K)Z7Zi1TX{NVAp zUZjKGu8w-~t)A({8 zPo{Z2uVx(0zKPqC!pZvv-Aa5)*zH2%2*Nhy@hybbWkc!q%DaQM5*tsuI>7kf{?k@O z=_n3uFV0zR8?p`8hKz~eDE=tQJp!5!+$Tb+98V;AK+1Vu>9c$evA3IM(s5z!r}R_A zUVL_;DdCh(^Ntga@JrcC7;$f=im-j+G};;tO_QC8t$TDl8?{Cz(SFC_j4>nS$RK^j zM4Csa>9Nq3mHgL#sxYi)tc1IPvKx)R`hKO*Cfqrq~ z?v&%jA1D_{)>CFkX^-TtmX=UEUuJ;$4^>;{6RV25IgD_3)uwX74O#2`2(urorTIN8 zEr-UR^le2bDeo7QLC4q75ld;@Zm$;xkaA;js+dp|Gj}E-hm$fyO$p_(o^iq>bp2cr)q}HyJTLL!;{%IHX{BGaf^gfks$#-5NB4FnOuJvwi*V}UZCQjd zFE@@R?0I@URo~AtuYuThr&iJTE1k2_iH$pk8fpgp2YuDH`iPQI&hEP{4{#Vs)?_7; z-{wRMbR0o5E&Ij%-NaszkWUp}5nO3V?T~t!$#_jYgFfoK;?m;+dVn_B4jixMO-8<* zn(=CGNBn&+3?^3DkvbaR2Kkxq#9pDSNhO>aa;OX8n3gIoVXw3@+Mm1B?WA;GwZ)2* z8*SK3^M~^-pSC8MNkPiNos8=zGHwWG+}MG!pr62jyxJ7ts71JWIr&{~4yUjt;VTzIa zAhB_zdBnI&-3n#u@p3oQi?fG~ikv-n$oF3GtA{t(FRkqh3Qr?;#mO;Iga>0Y7f@F2 z*ho406dnH$4taonjUN5#?^43u87#hS;f(9l@#d)SWG~yp%I9h`P8-NLRz|qh=o#&& z>-RmIM`~M9`jC2+Qqyvc*zrb8kA7-~D(dK{<70NNgseA7I{A)}Z&iJVki$7bM=6|v z4QKYTD#qid7*D)stfAvDhjYrB!zCrBg6)b3Pp=7IM|d`T+#14jA=!HfFGTL4jB6-{~lopZ}`|sdcf% z+ZMuPJ9a<6-{=MC0)BYltQ5?IW2!y3UO7llCVZfoOJvv&nWiGOuR5MDq-1 z>|2=Kq|T3KHfnKN_F4BNYi`XAdqsG+_juY8_l0>b#D3tjKY;N5-pe#Y?*+WSLF^WF zyEf>txXu_b9_`M!zn-yFJ>#XQl-YUeJNU~hh`m;Q-#=?BTf1O7J*7`*dj=Ie zeogl3P;Z#|4>gpbYY%8vSe)e!&ohFyE)OWB;t}=V`ZNl_AW~Jg2C)vwXJI0Y&jQva*y^EilkoC6lY`%w1;J@a7JXRm& z|7HIdSCZ{HoL8F|KhXY!c+}?+zi9T8Pr7V% zoR$Bj$AMNX#QxR5_+G;J;3#8r9OH#*#*=ED4yk7_l%FT%^VFm3B=!7{c=bGhKE>=^ zUA8d#_%Pa@VB~OKj3ax;!+q8L;FJ2O^_}*14(GQz@Bg*^|C!{P3(=uNJmW}v#`N=y zm46to(mZHw{W+i6tmc2|@t=JEfUUo;?k6oOW}lzSc*2}8DT7&qH!(&WW9;~e(Z`q3 zMx9;S<;;e^!-yCE-k$$|Z2`@c)>gL@tlpsy7}GKtOX(4~wY6aev%f?#GLQZ<{{Nl* zQ9VxFQ;#bxw7*0>X0=3iX6&FIRsR*g^$=FBt?q^YH{&Kz{4e!UWm{YAr?B#9I!?B> z&Y>epYin@^E5BI4_-;Dm|2G}}Q=f0`|Mh<63$a>T$0ttnCbjbgRyaW;ul{ZMA8Zv) z*RX|(V~IzH1mR9t9A^?|0Vju3#My@{4p%u3IUl)P%tf){dT~2*`*4SIr*PA_x!f&W ze4~Ne$bH29#N+X_dDc8{UKd_p-U!}Q-a_6g-d0{E?=-K8_n7yY&*$s#ZTLR?V19r8 zNd7ebB7PobL+$6E;a}rF;eQbb1iAuSfv+G`FhGzXm@Zf>SS=_PR0+-st_z+Dz6ymx zJ)xb@PuNvBP?#u87A_I45pEYA5Y`Hth0lcFL?V&C$X?V|6efxijS|ferHj^zc8Cs& z&WTz?&qd$GVzGhPQS2`c7e|Xni)V_Lir0xt#D~P^#W%z+#6KhwiIK!f(oWJ%5+fNS znI%~!$(NK$4ofabZc1KCeoAFhW2v(=K-yh8NSY*_EzOXwm+q8SOY5Y!q_3pEWg0RQ znTxEwtcNUCHddA*%am=9?UEglU6kFHy^;OVkZYJ~xN3CJ=&3PSW1PkujpZ5}HOe%O zYSe4o)p)D%SFVto$=&3E@(B45`FQzUd6v9DzFU4w-XOmxe<%M(p;VYF+!Y-ak&2;; z35t1&Y{e$U9>sCRWyO8Pdqt~KQ)!{}PEuNOPmbI3*Ru`?lTJc&_w9>RzX>HZ2)HE_N83i*M>|-% zpY{mtsoIOQ^R%~V@7F$~eNFp`_7@$2j;@Zaj;~ILPJf+|I@5I)>#Wu()~V7tt8-oF zsm@njp{|~;ovxp5sO|vWMBQZFCAw>Lx9c9zt<`PTeWv?OPo$@>XRp^rud7~^-YC5p zdg*#=^>*kT)H|owqW4_yyS`Z8K;J>Xt$vt(wEk%Qnfgoh*Xft&AJRXse?$L;{tp9* zfuVt;fxkgFgBXJ`2D1#78RQ$38XPvbU~tpmrNK`_siBdflVN~icf&!3NrtlxGYr=o z?li16tTVi2_{#8?k<7^0$i=9=5uSHvG}b7^DAQMdbBvc8Z!|75K5ATVe8>2W@gEa~iJ6I;NuWuD$qg)Fchiohk)}gUCz#GN%{JX+y2tdmX@luK)Ay#WW}0ReW*%mp%zBv( zGn;5O-)x21X0vj$6K0pq9+-VF=a{R^EzLd6gUoxI$C*zuPc>g@UTD78{G|C6^M~di zEw~n17FHHs7M(5nSPZwAY_Y&1$D+t$pGA#Dqs1eOPnJAOZA)uQZ_6&0eJ$fHr&y+0 z=2~vCtgt+7*<|_H^0O7+O2^8^%Ev0$s-M*etEpBCtyWoWwc2lW#_F2Y6RR)Q0&87s zTWeqI5bOTdBdw=dFS5?FF1D_+K5Kp5`lC+oaQ(!ciQMw=5*Al-sz6h8>c_c za%WR#SLZv zbPICp?H1=Y$t~4wrCXufUbmBOSKJ=BeQ@WxYq?vwd%1UZ@8dq)eX{!k_Z;^k_kHd) z?pNI(x_|QEd1!lBdw6?v@#yOj?=i(A%_G-ii${gWDUU{vM;@O&`JOtSHl9A7!Jhp* zM|e*4Tt0X2 zzIqG2^}Ox8{k%iH2Y4rVPxoHzz1q9jyUM%PyV?7h_ctGrkG_w+PaB`EJ_CIceUg2a z_^k2S?sL%RoKK6-bD!_NVqXJa2j8~7VZKqmqkL!hru(k-E%80%d*1hk?+f1_eiA=J zKSw`*zi_{3ztMg({g(RW`<40~_PgMB)9e}3D^Qz6Swz9UyZJpZ&wC&z@P}`)oDQz>`ZfLu!?UA+@+um;by6ta&4Sy4V z7ytJDJ^W++$NJClU+%xrzs&!rf4%=5|2O`B+R59QwsURQpel>>15N%r&DmJew{{in%Ze$r&XP{cB<@j zx>Hl9$DKY034(NkY=eA*LW24SjSQL=v?wSqXj{d?B-TcNK) ze|430HSX%%HK1$vu7kQJb)DTcqwD&vySg6fda>*6uCKfP4$}xT33CZ+AJ!u*Hf(HI zN?2yt#;~%mqha-7cf#I;{Rx+cn})lFcL?tpJ~(___?+;p@PhE&;m5)+h2IT-8~(SO zqMKPaw{C&mBDxLfHon{3ZrR;7b=%YJc(;ab_qx67_D^?Zck}M<-8*)V>^`*ngzodZ zujszHdwKU0-7j~)-~D~})*hNYEP8nK=+vWEk6}F~^+@fpvPWT$y**C$xYFZ6j}JXL zJyks|dwTW^>e;*J@Sc-=!vAa%$wl$W@VBBP%0MM>a)1j{Mw<-%F>L zO)uYGA-($d8rf@FuSLD`dTr~qzt@>w*Lpqa^`*CAP+|91Vm^^fU4rvI$|%lhZ{FYSN0|AqcH`@ib{Yk+Kk z@c`!m0Ry@Z7&IVh!0Z7T1J)1NIiPw#-GJKzUJv*^P-CFUK$n5-2lf~kJ89`6F|C6%2U!gA7}RM{uR+5GO&m0T(27BYgZ2(OIq1ru2ZKJua$;4nma(3( zL9xAK<6mlAlx(w+%B!0-$Aq$7B8nSgr<&e`unua_c@_8tKsLoKEp*}-{ zhxQvfa_F?7i-zV6-8OXp&@)4?4Sh27%P_$(-C?%Fe20Y$8!#+k*z{qGhpiq~JgjQi z*bXBX!e*EMcnTw+{u+>*F8aogh##MQ<%$32VtHe57Zf4Kedw!_1Q zM-3k}e8%wf;cJKQ7=Cd0x#2CtpAY{YFOD~ecZ~Os508(IA00n4erf!=_>%ZT@#o`j z#J`CDF+wuJaD>x{b|both#4_v#H{jr^6MkzkVGlF&Y(M?!4E*o2gX%!CaIyAqBhTuiu~ z@H*j7qCC+w(KWF{V$a0EiQ^LIBrZ?fm{^v0G_gMMPU73dzoQhR%tpD53LF(NYRIVZ zqvnpv8dWfA_o!o|E{(c3>fNY+Mk_~~k9Hs3adhP9p`#~^o;Nys^rq2!Mjs!2dG!6! z??<AIEaXYK^rT>ovCX*gj*2kDWYr!PuO!MPn<*o*LUY_R-i+ z<9Oq=$61f_9@k}D-*NHdri@D)mpg9jxXN*-$2E<6Jnr*&{&=17HsgK92aoSJe#H2x z;}?$48^3M*{_$tVUmO2q{Fe!W3Az((C-_bXnb3d2$O+RXES|7>Lh*#E31=r%fCa#&ded2+MwG*2sKAZS$l4z3tB>PEiCUu=OaMGwr zGbW`^T03dSq=S>rO=_9+eA4&H;>iY+9VWM(95y+6^61GkCoi46ZgR=wLzB->zA^d5 zY%Af zQ)f@jn7V%I&Z*T?>!#kC`fBR0X|id?)10TZpVnhq?6k4dQl@22+c0g{v?J3lPP;wr z^|as9HKvg2|KRUgB`km=-rvFKnCz~a^B?l%)Bo9d* zpFB4?E4d(fck;31OUZYW-zNW^p`2kp!+l1_8Id!F&X_P`-i+)Sn`Z2paePL@jC(WQ z&1jveIn!dM$IMPMd(9j+bK=bTGgr*qJhOb}iJ6yY-k9zJ{W>;ZQ^i7FRnUa#0lAE$6r6T2YN>j??l+Sbcb9Cm|%<-8MJg48B5p$-_ zSvY6aoUL;z=bV{yZO)T9U*-zt>dv*D>pM4OZvVL>=T4iuXl~xzZF8&Uo}GJr?$fzn z=LzTO&9j^5H!pPFfO!e?rq5eEZ}q(G^A60bo!30?*}QM_Mf3IN+s|(^zw7*g^AqPM z&tEcs?ff0{56(X~zh(aO`QKB;sRpSIsclokQlnBwrOrrQnz}BvB=u10`P3V!FH(Oj zkSs7<;JCnlLHL5`1)~?tTCi+E{({m4hZkH}aC5=S1wYfIX+~*IY3C^Fj!Pn!3|%r|$-E`mOExXpv*h@ah9&owyj${5 zx-#87-6OqIdav|h=@ZlEr>{ugoL-)OBK>mu{q*4#;UWm?OumU%7fysXc%;mam3Td*u=S<$k6%W9TgUG{L<#|&PE zc7}C^cSe_tz8UcuQ!>&rax=DMRAijWXv}z&@i~*9sgr4w>600p*)MZM=G4rEnX59l zW>#jN&TPtjlKEx1V7cyc+vUE?LzeenK63fA<%^c*E#J0$|MD}-uP=YP{A-plOE1eV z%P%W5Yd}^)*7U5!S*x>(v#PSrW;JI$%leir%GS@e&u)|5HG5!oVs>)&lI%6v+p`a3 zpUZB^exCh(g?NR*3WpVKSA?yIS}|(Hj1}oC)~?vG;?RooD{icKvEs){$x6eOjw}6F zhOdlXIeO*Hl}lHyTUomD@X8A-Z?1f~@@I}T$0)}sr(I6BoS2+3IkR$><*d)ynNyup zmvbxURnD(mS*~%eb8bLx_uN6bNx8FgGjliO?#exqdolNR?(5v&t29=bta4e^epQcE zv8%?enzL&8s*S74Rvleczv|AaH>>{S$@5I}T=P2Q^~@WbH$HD}URGW~-tN3(d6)9; z=Dp4PyIQf@Y_;3!z||3}hpwKmdfw{n)tgrDS$%wU!|Hph->v>%v zwr1j*`D<3J*}SHF&51Ra*W6$8eogCI&9xS5J=S(w+k0)?+DU6u*REV!xOVT_lWVW6 zeX#b!I?g)PI?HvQ>pHLNvu^mh$?F!Z%UM^nZr{3^bywFtT=y}bo3E8`mG7P3CBJWe zeEyXDwEW!sE%_Dsr}7)~ALV~q&s(p(-e$ee`r!5b){j^}b^XHitJZH_U%CGD`lj`d z*MHu?-=Mp}c7yMRkPZDejNCA7!=ep&8@6rOzv0Y=Ya5D;E4O)ob6*euy>xY=>D|K{+`(VIta zp1FDH=5?D(HXqu2e)G-EFE{@zlolElIu*7n>{b|4IHqt`;j+T~!qURSg>{9u3SSle zDv}i$7daON6m>5eRFqUSyC|b*ebLUMBSjaBZWp~S`n^SCi^&$3E$z4T*b=*C?3R=* znOin&Dcf>%OZ}ERTi$H>vsJ#;bgS#u4qJO}9lUki);U|3Z!Ormd+V{Sm$u&B`gZHz zZHjGX+uXJVZj0D9WZU>{bGK!0+q7-Zw&U9xw%yzIZreY_%3||k_u`Jlk;OxcClt>w zUQxWcxV-p8@#W(C#qWz-w`*><*zU2t)AnB5hi#vk-5^jlBiB*YLN#~M2CGjOwO43Sl zOSY6$l$rV+En_u^z%;sPMw`L zJAHPB?CigD-ZOg7%sor@tlLwv z=g^+>dv5G`vFB&GwA`rNsk~izxAK_sG3B$$mzC$2mzEzczfgX&{AKyCy|TT=d!6?N z?CrjH(B7oIv-f7~UB7qd-s-(|dvEQ1z4!M%jeREjT=uo!*JEGozOnmK_GRwduy5DC zBl|AyyR+}jzCRW63eyVLiVhV$D+X7LtC&-W{N zMpO=|9A7!NGOMzna(CtN%7)5&mG3J5*{|GhzTbU+$NiD}hwh)Sf8PG={hRie??18s z^8Wk#-|ug&(yX$m@~G-m)vIb))x@g#RV%6rtM*o%th!S5pz6Z`&H>c{%LASVf)4aP z5O-kGfz$&z2Z|2tJ5Y1r>Vby`J|5&A)H-N&(Cc95gMAJTKREed+QHm|TMkwnJaw?~ z;G=_|4)G3YAF@8=eW=T!zK7xuO*ypi(5gdQ4^Zs<3pbh^AGDBwmIx`IQVeC z!y^t)JG|&{-r;SB_a8oU_}bwohrd({s&%Vvt9`3Os{27l15oSt_&`}C&Mdrlue-EjK; z>G!8w&uE^pIOB1q)0tjphMk#sX8xHKXEvWHKXc;Dl`{{{d^pQFt2%3W*7I!8+1_X4 z&Q3a;dUoa6!n1qN)||b1_Tkx&wcJ{*TB};G+Rn9oYKPZOu3b=@Q(IJ9QG2SkvG!5z zr*ph>+UKm#d7tZYuJ5_{b5qWxoy$G9^<3q-)90GbJwEsOJpa7Td7JY-=Y!ApJ3r$5 z)bk6^=bhhne*gJ1=dYcAa{kK&!3Et5wikRagk0!0q=%W5b`-^QZcD*?8V&cUa z7t=4Uy}0Az!HefEwp@IE@q4|v-k{#0zHNP2eN_GE`kD1h>(|wn)E}xpUw@1Ttq!KlHhpb9=as=%#$B0nW%-qjSIVv&y;6VW&XqS;{#=z`HM{C|HSlW0)gf2MU!8k3 z>uSN(-B*uYy>#{N)wfswHYys;8{Hc_HbyoMZJf|JuQ9uEQ{$e-`)izQs%w_lJg)^^>wPWm+N5i#*H&ID zyten+$!k}xJ-GJqI`_KPb*t-M*E?VDbA9;r$=4TL&$(W7ec$z(>sPNoy8fw|*R0)a z-R#}mrMYi&eDjp%wC3FAEzK3pr<$9ZA2)w);kW3t*tGbx1h@2S8PPJeWns&zmaQ$7 zEoWM;wLEG0azk)K_lE5a-~Wfb>kf3RXsjS$iGm=48W$A>HL*~nML~K|x)d87 z0i_oOl@3y3K?DR1s7O&0Dbi7zbfk9>SlZIgZ|3aI-s>TIF^ReN`8|)`Ki>Pz%$fP# zcfOf3XJ(dE9IH50p;KX2;auTY5mE8HBD12bqNQS}lBse{<(A4ll_Hh$mAaMYl`fV3 zm64T+m2WFQRJK+QSIw_tsp78MTP0ehP^DL8QRP|{Q1!6tMO9W+c~x80NcDnh)@q(= z!D_K;#cKU(%WAjkpz5gVr0VSIit6_2(VB%dYiqXF?5h#4QK~sxV^!l(6I>HrlU$Qi zQ(4ndL#bU<%T~)Dgn(fFh7N6(L;A7ekh{Fwi-=41EA ziF)Sxb@lx92kNEk)$7mI+tqv3ht$<5{nn?g>8&NLO|64%^V(LoakcGkJJxopO{dMQ&AH95Eu!sNTSi-H zTT9zeJ5&3b_ATvu+C|#s+jZN`+g;lI+aI()Z_jN1(B9fU+%dm{rGvX;Z-;1yLWf?5 zMTcugKu2UpVnz|M!ANuAl96`k#!qg@NT z)^=^}+SeuCrPOt{%c{%0E2t}~E4eGDtFo)3i_*QQo2{F-dw=)wZsl%+ZtHH3?%?j2 z?v(D_?yBz2?y;W5J?uT(dW3o;dQ^H0doK4}>j~+3)RWqi*Hhio)id6^q?eQlj| z+D|>7Ci|B5t?%33cd$>oPrdJa-<7@_ec^qN`(F1I_SN)+77qyJF9O#kWr z3;kF7Z}$Jv|D^x7{&)Q!`#<$#1K$m79N0PV<4ZQ+!^?F;P-*|1N8%a z<+(7OhoISW=aMR$f!6SpRgIa?ogN}nf zgZBm#2Ga(M2O9?mhUN^d9NIi2Fm!ZCZb*B`bjWGQcj*4m)1maClA)#{^6=c@Rl{7v zyN8brpBmN~HXC*x_8X2Eem0yjTsqu5JUB9MWX;Hykv$_KBl07*xq&0fm*qLlLBiQ4}fq z6ibR5C6Mxv@`92@DW|kkM#mP8tsUDswr@;)Olj=wnAMp3SkPG1SkhSbSmjv97-f9X zINLby`2O+Z<5lCG<6{$xC)g*pO$bd$OsGs4PF$Y2HgS6* zW+G)GZ=!mlYhrwI$t1@l-=y%Q+4i$<&Av1H z*V(_%em}c@cHf*?bC%Efe$EebewuS)&Y3wE=h)A=HRsNpU+4Tj=lz`eIel|y&0RkC z`?){N{b}xrxo75HoNGV#*4#UDf1UgL-1l?q=k|gB_Sf=x-_QGD-cR#R%sVsh;yn9# zx8~iM_v^gh=e?g-Kd+Bz7SnR3@0osJ`ibcT(;23VO!iE-nC>wB%Je(ad!~A(KJXV~ zme2ow{txqintx*cnfVvz+t0r>|IYkh=l?$c{rvj*eG6tSSiazU@b`CqT5w{)nFSZY z)!|zU?kxCq!S4&+FQ{M8w{X_NWYdyeOAaqNxkPixr6mqayqDZv62IillA

  • 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 c#*QEMQ=?x#$8Y@olP*3Z(mnsj1hFQO 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Ξ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 z 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

    H_R5$Nxr4wJndeT{n5YvIu^ARjNlI?b(7 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

    &xld0P_>}QJ?&C08V5c_R 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%0D5EdWQR+y@UGk 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 Iq>_^V2l!u3%m4rY literal 712888 zcmaI7byQT{|38YYkKHYuf`K9kDx!iSih>{@h=hP3Eje}0nGG4tPA|BipVn--HCcwqFoV{|Pu+HRC$6ls)U6k~MM$i&FYXrIweBYz_gqjg3b zM`atMSflt+>woR`qnc==^iluVQH{eWPBJ=SWcz>4KgQ}m`F%(8{~MKJlxmba8XIpE zXLM{d+I3XBeRQrF&9l~M)#%e?)Faa<$|!NvCwf#mIvSHSS}Wct`9IRX4F9$K%Qk-0 zmOL6|GRih)6vh09)&F!6HCpNa#PnbO|GOWP(M^>#3#0g7dF<#k`t#?1 zuRliM=zRMY_z8}^D;?eE4UYr<2L5g}055^-`nSMGaH=3{)W?tT7dRG7IBEj?0h4yx zk7^Km!|1O36e)fnTTW@EEr=YTyv4?NS^>5Q#oh?;hNpbXAs>)+ya*%*O3H7%CC7=dQ+zTY zIMM)Uf1tCxq|pc*H*iMG*+Y4EF?K9r!oa3NIH;_O?ofv4u3*U z=B?V+O}@|ExH5+_8!P*?oOq~7`q-H0TNih^jTlnp+(RWEFFjXXP6Q2CRMo_Wd}qc% z(qEcsC$dQ-*^_V^(l^oiZJFd4cKyl*GLv@YZ#Hp7FYBS0IIW}fk_T}{^I*3baYY@o zDvan_*{UQEPn4L_{fOO#OVXQ3=IZN*wIs1@(zY$+@w}NUpOGEuW8Z%vygIk}{%^wd z!HNrAgyECRI=cziJN~NpL-^7ZqgY2=SA7-_BxaW0OgAR>7Wf}tOIoRN_4q)l5|pgG zPx`}%e|Mj7?#82gw+U^RI?v}3@`r^TMFeesU-@-Hdsn=CG2v&^TN<0VzQ#DMgP2qt z5%!9BK5wQ+DJfMveq}4^IkWlgZ$jrolY3(cH6t14h6ubXW$jl8$k}D(V+rb03uT80 zcRDW7CJ|>eZcWQ2x|E*?>m~{cmUz%eu9C|u%Sb&e-N)mYC1u)UD-@)xxKfJTqO9wE zhIms}zp0Nz;`3T+u%MyS9(u{^syG7~xb}+8PzW2souJt) zqqG9>6k}dkK3Iw8csPR~=3!?HZb6)1Z>M%?WA4~cH>iG`Jp;8U(%R#pz0%?GrQmO| zOjZF_3eB*GU?%TrY9Z*sSr*y_Zeq4<%>@_Z@wRV)8|cxOI_kob$s<%qs(&=R0J6+) zXl(*pw1-QHV3g{FbOSg?Zi4E7XA+B)V&Ie@?a*&vh`Vy@Y(USD+f4z2u*~P5p@RB} zHy=PNs+XV12KD7zTg*V`;^oD^f%}D_;s<~@Zvv75q^j(a>wp8&qlfkb2Zht!M*wTK zkzD}g3{Cv(0F=_nxv?J{Y58&52=r|rHeCd+RSSzw0dV)&;$d(g8T_d-ze`@ z_8}K2ZzMhLb(E7_Z#ym}0dITK33;Awxz+&|_MroG(5UNJBM6XMIt&P4S05vkQC?M= zQ`wZ(VtP_2g{sR4iJ$R{Z)kyJ9-4&3QfyMf&|pec=n{kv z*l%URT;Q~=FI5jlKKYyJk4(BwW$c9cgOBMB@VsU#+<}S|C()9rYs5_$lR6)XL@TKC zlBq~N^z4uyG65QPe+4gvG`35r?hx_uK}J0D#?_znSjMA)bUcWDz40@2U4%s^l_0Cp)R0`5i&VJVQJdgGn@`XSYR5x4{j_NEm0fth0Pnv@YvDa@ z*pCfzt@L%+B6hcM5$em@K{ZDBj5mp=;b!{k-~!l!*19E@8jNfvg_BW+@G@V7bnunnU1T~}bNmjxgFQFsF13YmZ}SD{1MQkk z0px(%+}ne*^zSb`rfCZP>OFwf>4}MDA7a zv^S6yCBE$2a8O}1nM1A1n-*^aeNu=6|3FD%>gG+LkOSHV00ns5Es)mNzkhfyR@t4^ z@g8NgHCGHGKx2%i5N@xDV0BQxmQhJ!>Tbi1V<`}*RRxm4Kk_4+zJl9$uWfySM0(@R z99qSBn;|z$czUS)IvUZ3me(UYJ5jX&rZit?Hd7mGjftJm&+rn8yY>lyzDmO*&m}i31@cAW&EKUnq)*9=wWqN zTn_l7=uN>35x^3qI8=0qWNrX~j%9sS+u zN4!n+W$jL!MtoDbguQ|0qdvnLhpAaB87lNM$&$VcJsS6c)__O?`mtR2tJ^Sg3%0c0 z1;%29Ff^b3$Mrrkh30DQLe(KpFJ0rF%Ky~wz=_J+(*&`;s>_OJGBL$9 zImqypMd88tXR$8l7j0O$E=Gz)@MieGL><}dU8`Ug-OD`x`S z#z`#1aKxZu&dk3gbD&?u2Ogs6SeMv;;|p+ zuW_9k3wwjuowb$qO)TfiEBZ)AZ7Ewin|{Ke#2oOY`E#-!V{bJxqMK1r_Rg;c2^2ZF z5~=xYgY|dt8$Rt^EZ3s@P4^eJwmr5koMqJXsc-=!w)VaF7Tvhg1D!$ZEgsIijnNC9 zMLk4ks||j}@H^>cS66Bf_mlM}u$#X7tS8s%j8E4Uwz_|3tt0bow_pBi#*Wq^Q7is; z!vSOhjafA%<16M-;v40RwCO(WFMq~g&Wp>Hg=`|ae zKL!xpAI9Dud*LJebK53(Hw~>{pAm|!u4s?!LlpX?{lPF%UBB@pb)ryW-2w`j?q`XL zR|H|VTy~K#T*s9Z5*HMzMF=rm!Vz>3Pomd(dQwQ1h*M7b7#+YmNS65-GmcVrZ49Md z2AnLg-f>_<+(f&rcMwe)=J1Ibj$ z_)0s`BGFoHv0%Pn9sefpFpmN8IH{bD6UMA&wnM}X2Aer=-%PxSzRvj%W`@OJSR~lG!h{ zJFPlvuYGwFZ`W9*E-h;F-!6WA`q@H!rs*1XWR^Piya=pE+K`eUE3>RM# zoT)#o$l&R!%GfJ77t8jNqgYoAE-A~HQ+0)heeoO0{ykmTABn#+f+TatT9r}9;*WYJ zOWySJ>k~y^y6+Up1!voxyzLS@QC1U|odh&)`afKya(~vuqnr*)fJWpVQowLzJ`h)lZWojP}w? zVODrj!6ctAm{fVgc@bhE$gs+RE-|{hUgp0gEU3GccYv_Jh^Ve0DCJ>_UxXJdM_DQH z0I5*?k@!9t5+;*mVGXAc)5xjBt->hrYS5B$)O;n0S zBxXzXX`h*Qk+Y?Gy(Wphq|i+HllfBOD?i3i)3-`3>B`)fA||d#^c2|9&V(-Enq!9D z0#+Pa?z9m@}@yW{f>VA=B{zql7fGpl38|3Nn-4cwuJa>ukJ)3k~ z$5*o!9@2C28IHR*F<;?ir^Wbw%*CPz-Hc?lkhSINf{H4&tCFm1QJj}Yh?dGcq+@74 z;$NcIIiA9JfimF{e>qQdXdK6u{m}a|^8_>2X(sJ7KF{JcqDGH3FVpTZsLKzlZWP?i zOH&-zIS5`zZ)$8X53xWQpM6B|L*^a-lUE_8hd8iX`0u@am}59{r^&Q!j7654;SX3$ z<5{g`)vmH-s+zJ7T4#kzaTUKuDlhzrx{1AYf~-tIxwpx=mSw@zrFp(DCK-JnbXO>)2)z-7r&lDEbjl3*rQh5+ENj$ySD>Fh6UBEdui~Cc% zKL}*~Bfq_C1H)T%etj<{=FG56hn;XjeTvq-d$71xb*4R1)u6C#{)@X!8d^7h^f%9| z%B+k~!TORhacj73g<}t1WtFNGJ5MpjORLx8SSYJ`JnU*wzl9_(JPcLODMd9j4+dQa>N!mrYVD4(snAh z!BIzXnF+iyfG@J5-t>fc5VhRVnOQ|mFkeiQP!CqzDLue?ng6=Thj~vbF5JQBWmM=U z(K(a~&2rq3s#LVm`lEkH3u&_gRtl@Jxt{BJ)6lJs3z-`cEAvgXE{AsCaWbP3y<>hH z<0A*klqGIT>%2OHgWOI`EO3yn#Rs(?MSsX+)f0tFQ=H@m{^Y205*63=zz#tp>)Z}4 zcRoWfn!$l4Hm^Y6q0XhT#kUKxwJiO)yr-h5{Ii;P+9@qpsUn%G)bfSNnQ~Xj_NWDt z)xshFJb^clwZoND$VMHf(Dn2*^RK8UW>w-?Tw9i_iP7g59})WGOZ11a0j-bjZ=$Jd0;Of17W-TIc1oY^yjFD>+}uOg($g*D~`DJQQ2B%GxZOJJf&c8q?6 zC`j{W`G@N0 z=qcIQs`scJdw=;pgbp1jj)1>p1r-j%`SF2y#qgoSxvD3yg>Qw-jCybDOJO^;XEnrr zOck1q#otq5T~6%_)^h2_sy$3|ma?ppu?Vax>Z4D{Y%6rZ-H#3CEvIFN{Zd6>L%w^Z zdFbP-9c6B=Y7~)`NjUR_kax67*TnZLEHOAx)}eyHCfP3ldn!;-9t~B1<|e{f!ey7etDWWy>g`#XWT87iwl4m zh9;pbV@JVC{=+zyb{20;=oe)O=g?l7B#&jbb)8@<&i3rmC;htSXiW4HayCKHawDP5vM`Q~zBnOCQb;Q&q-#Xx7Q24qa4`B*-3(ctCL8 zy@Y>+8?c(d+{@6L&p>}+cU9dr^QwsgK}BN46x^buzNCo+>kaxZX)knN@-t#G)xDbd zLzaq(iko}P#r~2#?uU8r1(R1tGoG=6%*{|OtxtKUW^7XvUsrLc?i$Uhgk3#{sM8-S z8%~?0D=r#1TBVLJm>z=4^_t5*O`^B*4EM!6p(u6rc7~FDeKbQXE>yZz-|Sq-`=?@S z%UO(DlG%V0$LoEoYg36jR{5%`4TV5)*52x$fG*Layc9SSakxkijt!I* zn1L?4HmWm0mfJa*9r)XRHQx+EO?EQ3L0?6jjsUcTal6GFoee&%e~n~hzO43ze;j{P zJ{|6km{T+t#sa{`31bueZ$IkDpkAC5w}F?Y}DD_iMIp^F_AND;S%AV z_DTE(dUexzUMO&?PQiJZal2{)o0#yc^eQX*$Zq{}regq4ca*VoXP~kkuX5WZfobXX zUR(w`WO9MdM2Ld!whZZ4x@pr^i50M>ZjQ(=!?O|+BqgMj?&CcOzoI|FwF+31cbhHS zIZNrlkP>S_>86ulmhX7 zFsFif1*!fUHA?MV&sTCIxztrG91>;PC$k#ZS4{6?b$Auy{;2^{7L?w*k_2Wy?m$Vz zq@3nJQcLugx@@v-@V$yYa@)SS#Z?r~ZC~@Z0<)ZDs+GVa+x?>X;QbYq>^Mlxp!ENQ zJfIalhru`5{Pr%8mSo?g0i&avYKK7}*if+?tn|HDJRZEYtyw3ARyk)VIgr9OScp?+ zthmg&OATVo>tBl{fTz1zXm7Sh+k50^;^W3!NK!Ohy9}`nCY9&HFMat%!En{Kq`ZeP z#o1f&8cwy16MTpFuK3N`1FxVr_hqxjfuydp%!yf_+E&r;B&r&h;WwjwYm#vL;GnWA zv@G8vhB9nun^WFuY_jtzg*TdN3knhto$(rGGyIl*^yCn~3tZi0!i&i&XazZU6ZbTv zvE!qsR-a+{1>2OZXPWq~GfZMk*fvXx*=_p|F9t6#v81PC*7$^8r^20-+Z_ZQCo`n^qGtH`*t$C9{f8SnSYtc@l09-_O2(Xx`bTc zURW_LV|UZTlH7#9YIS-^L{CMF?$1H1;xXz6dtT)KQta`Ns2ar=otI1Q^Tl>noVTpS zCe^qn?K!r;$Gky6HfcXrlXv2JQ+Y*gd|mDFlE{dx3P>Lj_`2v!-l;w3^G~UIJT$6Y zX}j|(iCpl<&Y4rhdSh}LpN1cRs?Nref9Bj6j3B>G`Fb*dtcvyMs3nUJA83vz-}L`j zyNYtq`&GG$a(&B?o(`zi`)V$MN39*i4%*zcwZ2+_Z^`XaK*JG;yle!FE?;bgdP{a@-VxY;^D)Ch}~ zzhg(kA&~vhA{Hm-@Tr+hG$p)eEMt94MO!+3M%d@ZeYlT*b+tK-=^a;^jNRE{Q?LWG zTt80Lhf1v}qGibC6*jEXh$%GV%n|4p-Cmq;G1Ar+c3RlW1})3SzrHGm zImbJ;q@Dg@i)lU=FIYcQwS-2ut`iclMJv)-%aMm*-{~T0RL<-^rMNm}ewRSl8*{XE zDt{!bv;Gs$&tFZnKG50WBp3dO*^pSBGU&If(Hk`sxz|7 zPd-!nCO3E9lYNVs))FF-g~ipoiA4Usl~V`E8`5$nu zu^S@>+XVa`JYL|G?R(NMPm+ANbG!Qd(W>TJ#oMs4b%^Y^-=~VbV)?FDMS9_)&Hv;{ zcvIG|QY>R{wDIEaqAQG<^e(I)Xdif7;+plVx65FhJhh`J|HaWm&6BiPsJix~3i6Yc zqw*!Y1`O{d=38cJ{}B+@`^quy44Y_PH>1S3haN`T0}uxiDs!`HdbgK;NjlYGRg`da zQ4_I19lEd9HqXW{upfM89luHGB!Ru6bHu=I2&ctU0smq`_7>aZ8kTljPufz3deKnT?V+ zpS9Cu9R3ks^jSfALU{DlhCG+J{aO-v8&TIsCMOWD)wPjDr1{!@@>NnRdopDnIVF=w z38GAmaHhy9#2wz0&%m6O3jlXO{_!NSntJ(hB=H@Uc%_!Kn!3FAHYpy`*Se7OP>?2y z^b-nVo+j^uGBXm%rBL({SIS?I$98~1g{InFq>O-PKU^Y|G3P!^BYa~lzI2-CL!Z;L zj3}l3sn!r5(d<=^NS@dUMh+;R+`7h*GxD6RVT(^Ogxv-rbn?j*lzI&6~AbfP6 zOPDFxbKxB!m8a^8BAn*julz||%qA#3Dr0$E0Zf9h02w!lh?R0HHNsBkA;H7H=Ki850YBwFYK0*-O>9mRoQ55$Vhhf)k^Wu^PCN(S6Xv( zc!ry$+jH&|xJoDGhG?gt3AukOccdf}Y9)$87m29?|E;DZH&(1&JgJp7|M|~ss}6^o zx3ZI)8_tAepQ_){GC9YhictI}2Pm5?zLGmZe;0|(Rp{K4%L#r;@}Ygi$&zL6--y>a zy>lwuK`;2o&il`Y__B)(BPN-x$U^{ za1K_VKqcf(t{k5P=SuZwLlDAN^>6oMM0a6@T{dYpbMh1WtkRLYSAS)FyxMR|o^5sh zL<1>1aWGvUmwmS9u>j3E(rN--$r-8rmSmiJxTGy)NA9n@ckY{r6UC`^F~k?l_b=B` zPv)kK)Kf!q9}Pc-J`(n|or81)URf`cMtCl(gSHZ@uqV(A5;HXoyh#oUGXnd`zdg2t zWt0oH6p#rppC5x*(8`;Cpe^9Hq3z&Xu&vbxtOAdehJjqrQJM^HMTJ;4ge)$X>t+>)3Jyh(vzaoCT8M$Vba49~JB?=P9RT%2Tcs zjRbB`Q?f;#`qz|jL6mRlI;0yAgkazqv`3uiCXn?YXeRT8r z(OWKoHvJS7t-e=7E~(YYZ$KA$ha60} zLCzJg4YDMk*cCEQdom7Z$D{&bp^+s6kU3Ue3=C3%j0uMI_=_vuB7L(rs| zner4c2BJd)^8O&U$R+L!Sb;=R1n_kDS9~8e9gaQdLS01tv}puVQNyik zpcT-An~%}^+>~JtbR*|L=LrO5FR0YR_nFOF1Dwb(u=}Vl=?FQ8nvPSBeS%)n%mOnZ z4K`+zJ>-axtugQ68hK2AY0qsNZTTw>EY z?HJ#nP7#T?1Ue)zjk5;daV-KCfHkZPw`g!D-ej!>E}*GbTHqgLz`zFhM6pjx7WJWi zRmoYZr>;ji3+mL!=%tXW;z#a#@V4|~>{>8ec%^ev`dZxc4ss56_qip-&)+Gv>`yjIad1Hs7RT{%<0F$L*In*gEO z$Da%wkwUKj0Mob?HqI0!ecFXsIQ+D*_aAC;Uv)zqbh+!HVHPx}^^jB!avNq~2)MZN zbha~4S+eY?HLy;1(SIQ@LGi)0f^vy}&1NbEV|bn?!0RuK@10J?hs)}TP|JXqeiit= zXPV>`nB8WEo&tW?n`FrVyrMq30T`oC_8X*}RTsKaC#vk3=JHG1x!1F;`&V}Fn*m1zp-ycl@ zvRs!S7QhRuxzwLv+<6an2g>MmW7VV68f=*uf*Bkc{_x+@&-74OLK};_!JgSV+Dhu5 zqb}%6D%Y`Sa%Qe7Avf7fKkizDtt|+G3H7-aXH-v zeL!R2>#}MwJ}oSofgZ)y`7J_-=;n=%@NW2v)f}oj_0#Yy)>?6Smp#)~w6Jz7W0v4p zK`#D=#}*%<{osy6im^BB(9BwF4D(skdE^28$9@`Ogzt74pzJdOo=9> zL&Z?5R#cbKrSgZm7dSzBT=!RaG>M^$?}Ld8%%Ei`uKAgs zixenBB9_1$NrUeowMG!`!iADpNmd_02U>W4Kcl;?sbvnmtVvP62~V#RtLtg2D}VDA zV|Jwma0yZy?R z;+xyft7O>wMhSN+`m`nwn1fs{>rbtOZyPeg8>y{Y?cPh!XStipbnp#t(5er(OFw;5 z$RG?qY5Yi!9e7b{hFkRBQdVIj?f-CG(2Gq8ltV~s_4U-*aC7NU_*N>jVB%g7>QxRn z-vxUGfmYQ(J44=2mM+UW(&8#UnDw>%x{#c$(y;j@IWGJ$yyZC$!55r8xu?^2v1Ej@ zBSQ=kvB=jPe?iK3UW>JoKUrYN4Z!o{H_00ExTaQ-fV`kAL2!kYaV6gk)@1<6!u;vo=W+%;WoAlP+3rrM9`;KB;EmkYm5+f!n{&5!Ccrz zHHQ~Kt>F}LMyLst4z>-|DfI+XM4ca=M9+t=?43pX4OMMmp|>H}LW)dtEaRs=7t>Ku`hRJ7G6zq3OIpa5W;P5^AGBkXTk_ICD4Li|z7`CW^ z_0*GHwZd9qd|jEqUNEjm%aiih@_x=M&Jz}uO=QEQE6m%hDanr+@r=I1dvFnb+Md-H8wUE$m6UjD}X-G!~(Ds7+SH)o9M8Dl&P zRcs^FFdj-bCBCL-iA14tS{dKmXBjr1{eHt3_#s_x2|zE=Uu~X(+=@?CA-o@@^#wuP z$RdHbl3iFh79U}m=2hlaG03Ws_^O3O>Z z!6shiB;L8Y?))*_<<*l#5$ru>y)*-}r>HYW%~)J8FX0m9whLKn}(?Th{izKZS5tMlH0T#^6dwe?k$nVW9u$@3y<894) z(xx(4HI5XleI_3yWe8Ad28o6~6DN{dvi}lJBb&yT@@|lo!RI(jDdxNM%xX&0x*i+> zNal9v70|DtP#r?OS{kI>Mujv(a$~ABpClQ9T9N0XyAUC3iGT@(9lOnog+hZJ*;SC| zuGOP&xp%H(;tL>eb6+$8%Bqi2@#v3A>=gjrQr#(w$Afqr$tqejGDWljE6&`nPzbKK8#Co60SSFC1^WKi?81aG2F51>-N!>qSMVQku12WrbihiUu>w8`$`Wh zPe`|l^&FCTvapcqD4fi{d7_Kg!@Uzb!fE4J9yGAbnKySD)BEXd>wGaW_R9Pxd=sgw z4p4m2-PQZao@uFyC6epvE$mGqxk3Xi7YJml(=YS9#m8g5ay*4bfj5~o-0NOCx&d!};Tr#EQ7Jf>otnVgI-~=i z7ZM}3OSxxBoHcdK9LjRjo3tx{qF7s$L>$oA7Zwno3Vn6ANk-T$%@fihqL<2rbRelx zzL0b(GDhM`-tYH8pdo+U?!!GmF{}|Xega(6ceFr|RAexypg0cd^XQ3U5+hk+V)e$SjE=a%M1b#7MwN1~7g!OBp7*nZ#%)GHk zs!D%E@53c1&GKcOL>@!?k?n;;sw( z9T`ei4ro%dj>%^zMe#}EFS78%c|td_#P=QdB>%TZ6bs>~M>$MnEHFQS%*K-Q>Iyzq zxk!Y%t!3X>RvJ?AMR30|U2mOvR92;{KgJXb)SY1?f{ThRz5(2W;;yZ~SS$F;z;DZSO_S zce%}0J@d54cFjWCF?OE0FHFaywKEDDI{ZYJbkkd$83CI04a+DD<^1ZH6J4@BWxwN= zitP-iLW>1~x*vN}Ij5Ajw;pBkC624V($;YvneT#w=rh$bt9e=Lg)1v|X0_wrOFm@p zBcCvMXMaq;nEy7XAa=8MS}ym{X(f{Y?n#td6Kl786fPvaaCpt`pa3R4bT8n&YD3jI zVuc{B93>9p`$}AiuSwVSTGFy~&-{I)q?iFs7U}h&IK?k=)*cIqhGMzplt4gv;_#Hc z5x8yg5bpx}l+jhwAR52AY!LFNDU0dQOwy{tAK-9WiLL=`j@hJs2KI!!RAhl8KHZXK z;HNE!U_NByaGTW*#hcE+-A3>Dr&fm2T6sfdOK5AbGe!3?CNZ-x5WSo>PB#w?JX)gm zK^}!9$nPPjPq>%~|Jt&X&xS<~H&`z4R8x0aEwx^rUD3ta$h})iVSAt-iac3s3H1f7 zjNhq2d0C8^N9U_5=!=5i$USinpK+qEw0T?R@r|&_4)>U4NU>=yZ5gbS=_*{slen`> zz6;stN<*(;M(#faPP`*2CE8b<57B_im>mp_VNK$3&*7dQJcXNn-MAZGtE|>b6oLFb%pRbK$Mty+-(%t=+8S z{$x6@GGbt~A7-=B0W?9uHQ zJuRB=J^JO9cYbpOm&a~$_`{e*7npgXUf6bVQ~B1i%d8E>KZ{RMlk~;oL37DJD(_t%1a;CQn{IJ>1bq$z^bl63*#V@C z_CsV|_N@6GgHc@DFbf>k@2+vle5u3AuN?ndv$VJ=Vw+-9!Og&C$&fa6mq9?3U)fa5 zfkaA&YWh<4J+lBL9T#(rTX$xiLmxHfWbY=W*DA6vr#-Lq$w7{7EZvdo8Fof5AZ+j_ z=|YL7o`tIEq`-|j=>js#j?cq^xyJU)@j_t(f8V%Cd=M_R zYahLdzsb0Ro_t>Xa(ItV~ zWzuMY&Lv+Uu|-! z@>humi!T*lkG3dm*G~ve&zqLV@%^HFt`cnDDru53T+;YY1s7IMV8*d}P3NG0<4ck7 zUiX}-L`lb=oYeIEmX4gEW9{{ybEA(Ks#6F{1E-hGCrFF_6{W|i(Bjl=9a!$bO(m3*OAGTge zfwoT6vVkp5p7ICa80!&1IQVG!bCx}X!(H73=nrv5`xdAzeL?dq=+H5@x@gGi$j-`d zkbS^VNj2o@6Ipm4ig3TGxd4fs*2tZqd)D9hgH*c}#!N9a820Sa(;$MpEe?B|rf+h_ z*2UebWuu}a6DwDtE&+wbZ;(4a&V`E++`UXQ1+jH9lcDf)n-zQq7+(>}_zth7-tK(N z-a>G0Enw|W+uoSUbcq9M1{ikX?G?%Nn1Iyc)i}@RuYzFOpgXSKgI#o5F1?Qaw(;gM zkY_9OjQz+sDy4I)a8d5VmS6nt)YlECdAsAxYm7PP!=uW3*@^(mB7n7Z_i%m*bFBLj zRX#n_X@PVNKHDajdkx!SJdTbd1JLh|3b{BpsU=R@kxFcE6km(2sfL9&4!+s^(8FnEREg(-y@s{Imffp#aeUBynlgja?lfNf56jl3k3+(Tj2rRAm@W9Y{iI=G zj&E~Dflo?${i-}PrnxFs4Trrgy|3u@zoutM72Z$thD0M9j;t!artnhrOTq#P}C&C#{>9Hh3YIa>A_7A-6xFuM5k) z9?5LoO;{5$so@}@XP-sY38K=AQEElXa{FD7LN++gRnMoKvaAtRgUgncvoAw)h@pdH zDJxFQK6#WfJE63*pF9|u+`=b!2fwe^lYi}-S=mQP^EzH~g7VhwettVp;W$;53MN{f z6)lIhEgNBbL1&4}2dt?h>DPK$RBFQUjyKS&NZ000h!uRR?hcf-Z${-f2=NLjE`gM8 zy}H-XEysz<2C9waKSCn)#PUU~BC3cma%wyNSGugnK#NJR?HG@Nk>i_gpuNGT>L#Fm z`{q?RB5%D87F|T7ZuPo3h?nCG#ox$GD+j?YmBh#}Bu~^Oi*vHF|I)!K9iDc9`$WvO<=T*E+*iMz@SFrzbiuO6rbJND&7`xpn)UY5o}f6!sq#FOCNF#o;B+mj&efefp;4rfI?t%Wlx$kkwiV^%5W}kbY_i-UH&9ZZYuK(Cz3r+L= zNO8TlYEn>4)j@gW-q$6Wk| zrH*v88U)8^EfWh;jwIG~1w z#EZF1S}w_jz)$^3sw3uy1&}w8C?31XAITzHA%#z2ym*+CLLL}dpYxS`b$DBDHu+`S zrrfvWk7XW&aLP299pN=43X3HsQU+4zlg0xpLQzry5W2O9OaPR&krXT7^s}GY=KmK( zXBiho+r?qKyA=_TG65A31VlkZ1OaIjq(N!ej)|S!neFam>F$)UQH;m#?(S}1-Y@fU zKFx3LbMABfuY=j&2q6ui+EW?iSake;9{Cw7ueOJh%lx4lq)umQP)}+lGq}Ks7L8on zRYsqTwhAQOw@A+2elMCAAf>Yh&K36q0?Bimc0Xl5&2_x{9ldDl?FnoD(3hzVvHiU%b)m5 zmQ$rC@g)1@&&b zzf}@E7)g*C4tDeq-F4F|t%*m~O)@EotN6sIC-0E~xnxR`cyHWxYK%a>(SinX%9g#S z??I>Dug1|EZd{DV+tAOk$)S>OC~{*> zl&cc9&llPVzU}e=+D&Zdy>Z3Ay20}Ya8>Q>BNq6?W_@c7VRn5?SvaAqI$E-bC@iak zNThuxa&{fLNV`6E9wkSy#pgOzCmas!(`anboy_9aBYo#Aa0v%&4q^B)`-Ls*@EskX z`2%5hbEoJU(W7oAm_?de@nPQ!@!3HQ-ZeI?VE1GEjCAGg;PtIk~h?=Eih ziME45xNAqm%_H!n{&OV*1dHw@VH4p;%RK;3JXZH$-wsks`T7_avRVJpCxr4{7P~xz zHix(QmSb`175L0G+{|+i4+P-KPT4n&!f!g-Y&wR2JWwJyPB_+;MDHMSo6Gi|CgoIp zkG@5YF%9}Gr0iErUhYPH%3pe459Q-)E}nw65#VFZkTo&3BMF*GnqKh(vLGFoRX~p9 z+l+E(8Rc8qp*mpivN_OQkbUN>c_cMN(IiMN^7xg(&T@5C;U)z4#yY zKA~6g#zgN1>^VEU{s05$6Gs$uVD7(mox05Q>r^T=+HknvOcm&$hI`Zj%_QR|>TBgS z!FrmHJeuxEE0J1c{i0ilLZaH}75pBr9$+KK(y$g+qn8^k@HP}e!y{A^{#?eO8W~#nrO{A&iR#CI*wqlN#ncmOiE}H=?!YnVdD5KlY zov^1YYgw|NMu}(;*FL9kY7BZ`%E^jb+&fekGmScfT4K;=2GShV{gGN)r`*;{Opg>? zToy&|WJg?lNA5i!8I+PQ_ipL_Nq*k7s764U+nTK#LD|*tn$t%asy0y;QeDe#WT>d^ zhLe%@G=KGEuUOi5@s4HTbUdg1!XQ~XlC@=z|rbl^2Pl{nx~Yx9ntJ& z3ex08_M$wl(PWIG#+0T-9Hu_j3B9J#+N8)bYkD~M)A=FtuJdI_lgaSu%+8Z!&he#H z1ajS>CF-B#*S-6&tCZMw5s5`?0xQ0G^UiO8m!jR6~O(nxa0WfSPOymMD{Xe6$F zh|D^OSM;r7*$|-mL8gfqVYFlVk?i>$$VGA>trkh9q-G^D-cof@!Hh0iw->-D29`Uh z8EZi5rO&J-v=PT|F*|5M`;AOjnyM}WIZV5$KZ6w0*YOz0OnN`Hn$ZGm$<#7-0_P*^ z8LPl}ubJ>qXq*EVJ`9yz+=aYBY6txgF_PLd8L>hZ)ZAwrWDMzO3^t>b8^-Ww2q9N!vr&tPNO&eIdc$OR4AaM<7zo7U zNYE;4c!}t-`Z4rI$iv=2M+7rSdZ?UtBz+si;7-}u0&&?aPcy_uQyp?4925O-I~;7- zafk-b*KKR3K=(D9D@2e{HA=M?%2bR(P0)Jj0U{AvB0iLs42>1K?3@8j=Uw*9fhMwf z4rcH*tM;@Es;bIAa0a53*S4O60!l}geT2rDrYT;77xkg6Xs}+hln@DOl)F<4K#uf6 zI0=-CAkTOZ<34cs4emm3o%{`LY1uHa1sdCMswE!mt7VkxL44&!c^?>97R3x5c42J8 zXMt9_zLaKgj>53g$X`1Mk^mhl;_Uy^6k5V11XY=_?r6)^3gmJ~wTb zseqxnnMfeeR=EU+02Su8lu>|2KP8L@v?*IXX9Gt?1jqG211I{#Ht^)pyS+6a@nC-A zZE$?w+>#wYeb+Rp5}>zwGU9;LdSY=W5M1S+TmZP06o)MZqP0^zP6G^y%yB%xas4eNyz%(%GRNTzNtGgQc*ZPcK4N>24&t9-!Q?wB z&rv_Bb=W}`M2qxrVWRYxcF&L|aPQD;-e=13J|oY8x}@2G>qbS)r#QaUhw`~>(r~?S z1mn>@;y$7EbWX}zRx_|F%#HaIxU~L0b1K+m_Z;zt7{?Xd3yi6~4&3SRjm93%D!9Ic z%-#yqrS~xfOkmWb$6y9-1nVCxOUAPn!s1XfvluQ}FGl2WgZ)^>fAGn{X`IuXn>`0O zV>tE=ne65443j?=j;SO^&_--DT*LZ|78NgL1+hLSonn$$UZL}l`^=K{KFD0;nEgD) z9%RAM9QJ#uRks&=z4&3>53EQeGrUBrgiFLQI-36u;oTga*#e1xoMb^KL-iaoJn9X%92ADN3@pTE zc2Qa_(bTrXl_OcQW_z^{v%7u_FOE5>dI4RzT=&n#>!;3gyejjyQdkcl;-TmmDzyk@r# z+-8gko(OMLr@L>0bYhuMb4Z?TRg0Yo#5y$(64qZups+ z2vIv>8b4f^O&m+R$A3oJnD>?klXDU_aV}Gi1v|2fXj9!LqLuVxws9<5Fum`JY&E&B zWu4>^#kPVkrcn&)>7r58sXPb45h{;*ksm_y$eYOhKzp`Z$qA*`Zg0Ro0C}$ep{v0H z+jM3#l;4{qT?XlzPKw_{NV$th0}+)MgsY%b?il`WD4%kMXMmKsOS#d|$z6BZhoCpx zmt*;`m8*f(0q?d|GJW8No>!99>p`c+tgK2&rGwxSz2qxp8MLGp9%HCB91 z0;hsCc2@w~hDizPMei_2yB4$7A<4E!kyDIM-38)U(YuEEB3t1-bF1K?U{KEGOZiOf z0}s!mk$!QVxEa|B&Ug+fz8({^mjy+jk?42VXl4s5$@UAfooU_qOVp~KSl1{NDGN%r z3zFq`WzPKhvRP;s_p5|Ve9LJO)$OZh3x)IJUSk%#AKPxRZgWSw1~Z+oL_2>*7t5_9 zS7dKqT5BVmZoF?iz<;hkBX_iDI0q8xqKa?QXyoSW2r#$ZgwKl_kh(`lDaSx2bOyd2#!zA0VzAK}8Vm zJv+!eC-V*FYzT?bv(BnB19vk^Wv5(6Fg^(?>@LB(*rFDuFsb)KWr|=!*B{+1-m~_N zLN_j<=^n$I<5Smzn}dC-JeIizJy+@$Gm({}58e8nxm`K5uAk8@;@Q=}>o}%nL}-6x zc}0O>!oWwZ1Fv^~t00ma+OZ$bz4ri185Qw5Q~3;Gp1DcSHagg|*woGsx} zt1>D@<+QwLK(K|rGvF?71+aF_d3FxCYw1GN3IZF4v@<}Ye33c~^ z(o5ff#v+RN9e6AKoM;}jBI+{#5QGcJ=hj1mYdWwG@am-ztQxqkp+K_=rIp@L6`=Ff zGZd|?8lGHsiM1H)kgjC*6*h@CF!R%w2n(2AQ6YRs!Pc$0yv5)#*;;Jrx5@k*l!&az377kDx(e#;O?hDNV3 zqc51hm!4-~RB}vM;@)e3fdAjrhhar_nJm~ktFGObwtVAP)>r;;iw)3w= zdh!-QI393M&jq#sCrMHpi%U)g;f~m@4mLKJBRpvOTpG=CR<1YwW4`0t7`m8x2-U4;I^t{8uaG-g_mr+kb3(MN z7g6uHELI}%n`Q|*krhr|oCl0|HYsQsS-&=y^tdmYhII+xDn<{h;^3qUgo-Ff}FEBPsM{_sm z_leH}*EMfNdvH#wa-mhGLH?OPxZ6uA;ORpChycznUn9ScO?0}#K8qIF{A7`tkM*Py zOy@8CZgkS%Irh32ssr@vnjFP};!xEh*|UuM@?6Q4T{7up@uZL<(O5yb?+(5TFVX1{ zdkcH#(s1S#)>BZ%Pl*l&( zzYrQF(>H$Oof1xWx`kckPFc!g#-mrYPNwH|q2f-1wz>%Ytn;mCqFz*2mQo8jN`DhB zJxwOjy^r52aZ;ZTP7|(_AKs|vC5m4=bq(h_9xUY}Ke6kYIMYCDx#*e!*OZ7(*G;N- zqI^^*RnrT)6<^AKr8USlmRyKy5MMTo+WtmxNC3+PMnNFTdjtui6q zKSa|F0UbM8LE2j_^%Qrta|5nmvSO$POq(m4S$-&PrPx%mYdcrK)wcTl;r1!=of6SU z!nUQ^2*gQK9&Yd|dMJ?8ZYn;&oK@wEYa=_AeZzO>&nWp!*q=JzkVhIFyISi>-X4^x z^q}1I&XjU#dsbNq>VY_`CXNZRQjVyPAZ73$)a)S*6Lyuk&TBNZtw9coQhJoPzvL&7yvkl+4fb2zM2Ls`)X(1@o? zAwZpb*(3z6q)gQ>1bt#c)IY%bZHE<8Abao0l6#F9b}JRmCJpJZnS=f_A~EF@~e+%Y}mYtyQ(5EqHLn#8t#JWxqNiC zz5b^(Vb6d@Dn_DqDEY!?fkDzE{KH=1!_`6ODke7u`(YD+&SqT@=T@heL}B6zmT@VN zURtl8R{Y(>&@}DK)bmutJ(ij!@(+mgp@F6B6<2M$LuDjfyJekFBuet}JN7MPan) z)T(Sw0dJiRo3#>?3(ZxJ8V|7gD`wO+(JD(Vst1bp7%x=BXMNC}EVWL!p^h1*vJWbP zv=_G8NvO)G4HCfz>B3e1oca7R8!GcLdzav4Re5^@YgGB279Z+Y^Yeylg-4CLn)g{5 zI#p#rLW0`f{5T?7G1G82;IhPB-LWA~P$j#+%7Oi#pvQ*9EMvdtEbKgAoCd*dQMh3O zx#>T=MedQh`-Bx~+GxXq z9`;MobU{1U&rxiIo-SV?+6tSOD7b!%P1uh1b;uxaq4^L}N?6zshV09UtDzw4QVS~{ zA&#*R%$3OUP*=klWQCud`Y&Sb{ztAx?3Q~78xXrCH#k*@Giqqt%eewLH+|#`pH%e- zyEXe#bt`*9%8v>gOco22Jj3SfxNDe&nm0dJhp>LRzm$Ds?OUEGoW`uSa^Q?+&O@iR zwu)!d8=5>tGx4MA&Iu=FhgFZ|zfU2TllbFeCzovGjobn0^SN_3*Qi?9SKY73;<3i% zY(Xw+Z^dK}^W?1EtuvHA=wll7idCWWaWw*umV=z;>$ZN+O-8I39 z%_*uSynF6_(j(kC%bWSfur{kF!yc-OOi@dzfll*jbkX69OKXQT?7hD$f2uN*eaey* zg)t*cwle3CCfzQH`(`U;rLfN3DBZ%}y!;T~hcnCC4x5I`kz*~J%M+-@4Oh(fiyqge znb5tFm6-lvlDYJec3(8fSgt}t0=2i~Up75b+Dq!)X_BKt;qq?YQ7&NZiB@4T$l~U& zwOY#Y25Hs)qHVRa%YS5@tXyV(khHiIFn*36Vf5Ak!EdxU^`1>Fiv99L_jpOPShn2E zOXqc4uR~L?-;AQ>#^zZR>xRhsYlXcvmukwgVk@3hj@#2y>Qh=1Rb}{RYz(f_uGP)l z#8BiaiSFK#kA!Pq?ym#)C&IkCXAnGku8;?F|LYt< zS(rv_X`)o@`p_V!M(!L_T}JcVwxZmcZsFr@!~y~m;7|N3z*&4 z3&8j{-A{)9&#aCGfI4k`^I71~uA%w^;N0+cRaZgLw%KJd&={Ykh8Cz|-6%B~9v1yd z_>2*jYk5Z*Lb|s1H1Z1%bbUrn$lCDJmERG!z>lR=#KUKj z{ubiDZk(zYiF0TbKScIgf;>wkkG_2WTTT~#Vb@H~s+_}ZerzyR+%!xd?h35^hwTej zRob8*0*{$1QPBI9emd*Jx(TWgETY2`u^aP((2C_Jr$Bb>o#07~gS;2u7Wk_;4Co3utS57>b*? zbsc5$wCp=ASESEU>KoLOg!tSVxp-{Yo$?MLCD65GlVG;DQrp9eST{;h&1rXx6CT6l zOIp|uSWl?3?ytIw#mWu~&He0cEn%upDK-t$6ffgm)r^ua2rDSJk^I~G)YKtf>RqUH z5u9H8Td|O5aHI%Vvj>;_W{036>gaBAsb%r#cC)E#-{I!7hTX~4^@#RTTv2tNniV#( zjIX%1wZvp6BY4MYD#e7gKjcC|i6cW$&-rDw5POQPp|HE>SDhrZ^o#;3c{U)U0p*&O;mQ96A1`j)lg0D^`B9#r+o38 zU+PO!I1lQBfSGoy5_We@q^^m|Z6#6< z2CuFELR0zAs(MYwd0Lv~K$-J(T{Sph7c093PqcU`D29LFg-4P>r`)p#oWZr}@AiKH z$0cm~y0-fbn?9V&UWpAx1vPbJLBamDA?O+Zg%z98-JW*F zAFKy1R+v)pm{2ktA@=3MMG%TA|#@7g2v z-<{fO5O+nkHQI|Zwx6o*6+HDjRJNbb@%UkYxQ|`DRF^oJ_Ga-~jBa^_bBOh|`1b)f zZC}ow{Xf;W)3}}e%E!BYwfvIbjSOpmWsA4ttLI7<`*F)GMG+n^^{)g=UACz_cvkl3 zL=v`e$qJ4wDk?S&XiIq6zxSsY-O`*pt#uc6Rky@xA|t-kUr||Zx2ejNtNap5A!)S7 z8-28h=Q1q#;J>whDjLr*EeT`yVV1>V1NIdy*^ND~OMj%k@2Dv8*;Ukh-VhhjSs$S7 z4|-I2N7d`M+5A&6#p93eilo^Er?eL`?cWN`T=tSEHi$`!9`_%sosk{UBdMC4+SakP z?AxyG%>^Yj5z4wphWenPN=WPL=V>lct@WIyBghh6c#1=!0}i8ve!PuK_OjiucMmoa z1%+jo7Le8ywI4e|I$nIcqkx=%A6Yq*{DLq=Rzpz{lNps%7gB3(1ob1uJuZiKhze{B zpg*P0aQq3}1@QN@_%~$f1p%RjGV16~VlD-1w<6h7CzoF$oul%lFxg1+gsUiVv^P0? z>IQmmY#+@YNcK5G&j1%YUIX&Lo;ycy$?&IhU3ho+^kFt(4qP#OTD*p#vKV4BoGWoA zY2h45O)i8f*~chFFdRFAN`PrT%V-zi7{`P3*RaE_t3_Y9-Tz%HzR3B0Z~%9LW8Zuo z-^~s-Um*xEv*<2SguVtPBnBFuJ&9b(LSw=xhnXk51+)!FjiZ5{$I#rkS9n@>^324d zI%(#C8O8PDS53jV8c|9~3Z5;TFH{kX{7QgDtmEz4x0&>e(;i(;S!QWDjT!Bh{t5(qP)q|MGCJTN(1-QGHdF4lyzBiKqM9s@$ zshc=!F1*OQaXkE3R{rC|4PE+zn*-yjoeFPvpVyo&I@k7y-G&?2@QLhp)&QdDU|EHu&ceaF9m%kQTn99xBUz0mc=d& z3i?i5n(-1{g{KQV=#L4H>9YZAQb5)aKqB9Xssr9peZ9S6aBD6e&+sfP@(M=!6blR|z{u>E%NCo;Bz&RtaLING>AdM2obXJh4qIp%#v;*}C6t@oP3h;UI`;X9`Lul)-SZf|m?d&Z1~wsQ|GP*yrY$`@nYdnku44xA zpz>d(Gbvm#K|PUlOSTnrC5t59qzM#nQFhu3>SV#(op|a)?o&@G?HzX3K}R28O*%6N z|GoUr!6X8qbZ=Weair;UxtXXjY*m^`E44>ie@M?%X9>^AX2puscN9=^G5ivBx3I>O zLCfa)IQ*fnL!(YH@EMI?2d?4o)^)agCG4rzmjx2ORyZqgM5*}=^A{=3I2Zqeyg*x( zYD*cR3=NN>JdwJ15~;uWOvlZ%Axtv#9rvM!-XDuk?(|696=U#|NXnA-lsq!5a|^pq$yJW@45X@sUmd+@6!yClS8ePG)psB)rplUkPgAd&U%I#OdV?oo<*^ouf;#QDKrHC7pP7@t30_crG$E0}r zTmIx7kAM*F%=O8@02XMk0mm_~9vMxWR64!$HEp%2ySAPdW?<+mXgJ+eQ6{ZKeGsgp z-BL~|%%abi)$GZqXNXlh!ssUiP3xlpH%^KDH-L!FKSZIzbyXcjRC%?zW-GORwK zG<9yPebqofe}JhUCyL$UE0Bq9+OM z9bD+`Y{kGJ<;=k0)+dy6`v)p-Q4V%q(^yl^wZ`$+Q~oxNqurryuRfpmiYhE0l|Z4s zFDdxi-6%Qz?{*&sJl$!1eUKr(4+X31{ z>cWPLd26Xr)jM{-rq-L+1eem5YY}%n?W*L6{X=>vS8zzcam)AbXk!Bf?3$ZcXW?VL zCHlMAL-+#C!Qnt>)&Txv!9SJ-ad+ZR=05V65GwMSB6B;9WYDy>D#mA^;NTqW9l@d9 zA4?!yttO+*M7{PZI*F7h=w}JZi-D!g&y=YJ3z+GYFNwj(aoYIczeqZLnwx_06iBeG zV^Bfv01qvtN4K6t7t#q;lUQ_mg$853pkL!Fm@L4SZpEAg@bjGzCGa(YkIVx11``=W z;4QZd#vUlq_UGQ=h~L@PM+F)CT9uH)V&w_R{(BIna4gP*6H#;+MI;g0`~1 z+Fb_kv95M18Clhv>s%R&D?n2}e7N+1v>r||y+!xJiwyR}^U!6@i+vEJQB8>(fFfkO zwta$Dh_1Wd0k85V+Rp&9(Qh4d8Dm=R)Lez@8U;o=yrFK7ga@6i>Stv_Xn7#v1GKrs zb#E^;QO}991W&6@Z9~8|S+Hvjh!bqGp8(EfuW7prpV_~+x(_bs>@XBSU)n6h90+NA z#l%5tYM&G4gHJ1GX8i*z&H7j&n6A6BZ9W*OOmp1>t`xc1T>&0&wzZyv^@rY6^}#{? zSM@~ba?gNB3#GQdN954d=0toL*jsxwD-6u9Xp9{NI+(@=wu7_OCtdA;_u>Y-UZ9yf zt>cJzYF=G!r|?<+b5psXqcB7|z(?Yo38@V+(4g2(v3#&rHE!ZnG3S4XU2ZRhrqiV3wG6Pd7A##T^@ zW8Y(uRDEDI8cy54wuvb0_b>4GT)4(SL%38$V%N&ZZqSH z$b-|sXhU4tcNr?&4eT|8pZNrv#1O@ZSf3e%TaUAb%^Yhb$S20irGt$3jJZvhcnv() zisjtnT&6aIbAxkA@R|LL{edx?ZNm;MevECvl$kTobo5{J3)U{wdTT0^&x%}&BKgd< zwxbyNNN8gm_ql9kSsQnuDZ_^Kf~SdI$$Y|j z6YzmKhn=vN!FY?h*+#+lnZ@GJ1xm5W@}9yY=xQl1 zeGMy1Y=}x@<_V_<5D-1DaxKirV#nEbz*|`Qx}#MlIh%Wn2#YH zP@z=q{elmya@B`49P^nXD)IpGL-IOcJhEEYvbF&J&JDMH3!O%rYNv2w8~&Pu z`YFe{bFmR+$G3LKM_@%wIoMZ}Sf`-%uqvva=0`IJ%L-GcGDn(%BXr0D&5JF|8A^;gg&<2&<6JHs>ke?{eA{9+o^{nn}!8?t4 z88M%6UH{a7h_P6;a7`yXLsVj00*&G5YPP6Mc^M`P#rJ%j{Fpqd;48aUT2-`@K3C#W ztjW(472=&!*9a~WdLmT3^CYf+Gdi`$!7r0X9L`>y*QDgl_a2Pa!^99Tgu(KJ#$^uI&8xd(;iWOK@q<8^K1nJLxrV5WW$9hVvG_ z?-#_5g4*; z07RhDf-zROKps!@2gMB0zp8xRCSh6mRq(f9nfU^q%DZm-l=X?bM<+UgI8YII>7WpjEP-6#ot1z>!6`aa{P`wgY!sC?x zm$jZdp`?5FX?BPH#g05|s_N6Gc`T(Y*cpe=1p!NkcQUXE`s3pB-5l8}k+Ne9Cq?Md z!UERvI~xj$uksRVWSJb!_40eW*RiQ3#UY>3liF_IepaX=$=Mh26pEM1;T;?YT}BBj zFGXr&49gd?<@%)scj!5qYenuw4^+cYVg^|ej$g8CqiiCfBlx{|4N1MxK~PRfS#^yY zL_2I%i7|ke+8onf+**mRAqe*uJFIiZU!&D%MiE+zoK<6q;`BRm1F1K@SDHe87%UYj zs6IX)1v6>9RW~>XfGt*+(C^@FO{_7K;wE0L-$Q9Yo3*J_Yif;pBb8SeqTEIspFUsq zjMf`JUeZY~3?4813V8U`@nPWis^=Vc@Sn96nh$+fFE`+zQqeeFG1S9S4IAK(P?}U( zP-g)_L4t}I~te(_9X(B5n_L?|=wRrn7K^@cVDwn3EEeXJP7 zS#e8uMF{ZkXwC`rh(`6Cf0*=Kai7xs7y!vs@Nu-oHt*#S8Pm4l`I$jim4Mh z2n0bJ`Q&o^LefFr*ay_~e;lclEDmws5`DbK4HyeyP!WF(*glvU(0`%iV8Nhpfe%C5U!; zgFm}f9Z;JCRw+ZOn(;g2R^{~U15#Uaep0sRj^RMm55aZq&cIu|NX1RBL!7aas#Vun zL;L_65#up?lDJKCx2*`ft)A5E0bEheZ5W5+%bwSSWlxv9tvIviyr{;^kHQItVaC8h z-V}9`R}s5g#$VOIq6-Rb5Jm~RQ50KUm#08GD*oj6&@Yq)7mh5Jl%yA>>>FhmDDFyZ z*DCOPBI8xV35Km}ecW6M9|F3{JMM&YZA zN17mlY%ivNO2iUFHD^f2A}1+7lfMW2mE}`2Jj=vhv?D7bdEWrhl9TLYXr-XDvV?qs zwW53yWiu_#Or`8E@-#M6-LtOhEvTmw_G`w|sy!fc#5e^JdKIu$Is7W3-A@IRBSzC1MhhGd2|c1qtu7>lVUXWvC0eD4Wn3|nJg`p`F*!WMPMG@ zDIWIl$hLfu>|=U*dIoeSi4?657R;+t5M=X}8(G;76mP7}+)dMY}G>B9L|7A^OKOG{2j zUy{ceVd*Vs$AGpuWw`_OmT{L=L`slZLssmeoyBEyz)znuG8ia9ZD zp6antAJ;s*LCQbOM(V3x;cqYeEVuHo;k^-uuBgWPc*WKV=3J~9-EF?#v=UfsV%D$1 zAJqS=*^uL>U0ZQEm8~i*HOD#2YmJ9OTP44AR(@xNRm!~e4|yu-_!StI#fPj#$Vv8Q z#^Tnw`I9Ll8($RI7IxKj6eeWFRUKwKkuSa8avHZ2?10rR<8bz5MZ;a(qr%wQZhTAD*eV}F?H)?`NMdVLW{Cyqcd(0| zOWEKnQ!k<(aBYxJrLS}h5LN-dEw^!(KwRi|^CU8tJfi+3`Cq}Qnllt!CZ{r3&3yl@OuWU1xQVIs7-$pZ8xh1C54_Z8Sz zKLj}$zbbHGd!nJ#2mBM+ZcK;vY}aWYL*2gXluCG!Yl*Z81|7=a-yC#UYa<$7sxG%BaR?%n(>l2M#XEv?G zovPLv=H%R}km(#!Kb5Z4jNEnGG)DPvXNt~SuHJT7byb?VajeWN61uvH2KYCY`EvJh zlC9EMx6lsi(>kAuEx47{n@Z2+Y_D)Gfl`aiM-5MQB^hNpeE2)VFY0fi$i2r5WXqp}_ z*TOpOwgsvM>J%TD^pf0r-4o$cam=!5oN^w`Dw5@iT_hgrIax3(|8u8L;moX2t&K$s z_N;GgDNc>?t$l^-4*6OcNl4pbE}csnwPAz)3}vDVs(Md-Y{!wHfV)Kle;qWR$m{OH zJ<7k(u?{cHeB9DOShr_!!%5=&nB}#zNpnM9S8&LQTTJE{ieW>5ei3bri%}I!ueR$H zzW{L-&v{ztAqIZ-7oM_T|2Y4-ocumVt@+OWN!~O6Inv4v>*(74pbL(2>nT%(R2bn-( zVC{3}=HV5ITbV0E3QEs0=Wf|xY(oBQn5WSqk6iv!j6u%Y=L#<%b&J1o_y`++r2Qec zE6=|rkvlsB98N=JCp@TK#6BIpv=U(N3|U$_2|MWj$M6nw_57lKh+;06|2G4 zSu-s2*yot3c*pkH;%B){&5Ggg`Ax%0VOv7{a2IZhs;xNAZwo$Zj^!!+yA6I^k>@$J zC&$m_rmT!T-Ttc}1*KWOWKU&z;jp$`<&oTJP2UtN)1&L$tGi@SqU zN(M!9{EPJ60<~wOs+rg6azi$Q^Vwku|1{RL#1o^jUKRgry{iA3!)n^AeVcZyZg@{kW>`bC*wGUIx7fZa(WItoEk%=?zvV0&0Y{a5fqpjXu^D8jeC%oFNx zPcfvy{;Th)=fJ0J_e!QPGA){Ts~8vZw)Hu%=4RS-4`){PTx`!_=Ea<7p3SriB!~PKUABMOSVno?a1KbIou+oKKFNT6gM~HP8Wf5agV4? z%vltJHo3D2Vc~Vw*pIE>D;Hxqz7#VKed->mYemDIW+(yHN!!07Hf!EuIj4>ZW{Lz ztt-kWN=i0Zt&UfD2fQsK$@?~5F@Ba7xo^;H7IB?+%SZCh+m#BIatbWj7#Dq){i}Oa zc~9D>cF)p93HO^LOhwVN>ptj9c6_gTsI?BbTsB_ixpBzIkxSkE)E6adopNMi;Y7O@ zejnG-Qh}|@U(Sgex`r#wJ<+!cpOPO{Uq^5%cx{|Q_*k@?4-uc^rqR+#|KZ!S z0?6-%D~dqs0&=!jAgz(gbJz!rpzpifQTP|P{KU?px46Ii2aE6EpVXz|t`ctQFXIP@ z1H1&nb<%liKJfwhUM8RHKwTMGN6Dvc9nMbL(q#@2bOF$K@j-z%4L`^&+)iujnO>AZ zdsB11m`Qijr4Kj8!%_fz5B&oLPq+=FWLzQn0k0y*ldHhQ4QW(5c*Y@&J_1^D{$rko zwfJaDeh2et*Uo|u%;;*bA}8eSa26r}X<)y?DUocl2!9E2%Wx;gGTuiNlddspJl|6; zFl-!xXgFAV_Ghk>aMt06d69y-9o6~e{85!%1;4oO)bgU`+&S1lv4XRhWW>E@d!@q! zKDKD*ZPHS7qNj%9!NfbnP(L#M{AZnGsVX?MIyXcy*gi3@LO!ozWx+)0Zq>5FZQ`3K zqi9Gpp9tgD3212o{0m;uPA8&}GhDcnThS8^Dk`42^Q ztbA|nF-21WOAW9*ie@QJ6a0$#ve?ude6-jvynr}H5bqg6cIE^*e5QP2)t?mX!|G@E zAIrW`Gp@NWcU|T9(%E_D(jj?n{u|R_rcEJJzZ}1=c#Qf<3I%slemd+LK`MUd=|LLg znH|?rgy`p?aeLo%9_|ay4r-gz6q;jf$}c&XH@+@Mwjn>Zsv4PD@TJTSx1oq){FU5+ zi`DdpB@*V#&w5TL?Gf5KI#V{V6HbiU%Q=|RyM5o&zLkvuIjg%qnR;@?ZT`{?d3PJ{ zFzgB#HJswSqOs-tWc%VLM%S=$_&Rlf$8FLC@h->Fh+oL%Z=|+V>v+W9Tg0qS)IoY+xL_ zJt|#_C?FspA>9qq(hbXY@9fUZ&TMz@vUHaMieh(n`&q~C?$(e0VXwV@^FGgW-&?8s zlz*Jx(vOMAXUgf$HTC;1(eW6UtyAec>dtgTGFITQ`n8O1{0m+Mb3JjGYQ;Q4E-(4U zqEiVeJAqhwkl!hGHIv~qo0ALRPMxBb5f|;tpk5?RAMT(>DezW2iccY#W$sq6>r&J#b$`xrm>s3}p*+`&(jyUcB^ zSgM}2NTa5uuwY~c-3gdMcBMZC%*80<20I~H%zVgx?l%hv;z*npv(v%p#}|^qxQV+C zlWudZH%E{a@U7-|lmghOj-al9>F{UT0yv+PLVFD-6+NW?hSw(jV%oq~zMEMl=z^0q za2#SEbs>Be|J?DN*ezZ=&_p7Oa+)aQ93ffxk>VxT5B-n2mj97hMYH1v7J1MkcnL{Z z1_iD4EoE6Ci=4cGDERi_V*GQ>kI`7dkXqJ1j;K&MG`u146m1GM86!^x`zRdgK|(H- zA;~OEpbdz4i5KaQ1m}E%m;f)=iNQL8EI-(Q``NT)n+|`@{I)lnFlc&UE+Y0B`sJP^ zv#yE5A@9|!#IL6uSAHr;q|KH)C9bBYOF&;w#s|SMr~g<1D0}};TyppMkx6*#jvw83 z@gLe^>t_(2H)qP`67M$1*<$ic(|TM6#Ze!gKlU-A1`{^ZF3R8gx-!_}Db5bev%G!# zaM+z&7Ht_TA#U#KqT!?Zvy4XwzTLf&w?vPQm4Jd&(fkEVCXYSjH=d`wGK3_A&=S=B zzLOcVr6gxNCRt#)HwT-%J9(IlTRK|axe<4HtHv;h-#-{Geo7eaU&(4FzUy+W>n6`? zMK`Xe(9GKS$JD#}i9YA)JLLwaPfQf#RZk*yD_8^`MTCpz>Q}MgmFUXS%v>Zq3g2d?@8SSHwH|WUBa5w<=0K^0R zz%qi%$OFKU=+W~9SV0OgTLUTNB-u4UO-bfV2Ch;?xHIf&w4M3)*rkls2_p70Cc5?$ z#|*4=I18>~8}_|rqV&eC>zM6~x!uLgLkzxYm^FzxPO4`WG5Nqp)&Z6~_CH`A>w3OD zAOqUtf3VlEOV@7ajN=42eBm^6-tKi`SV8r}GDadK?7YlCp=x6)<0cdbvx z?h_l<+OQ4_ydD1ocxd=`EG4vKOTRs3sLir@EA`*z0d)tpvEd_sBW-nkA+4Ww$FQNs zhtAP9<|HuER4ZbOm|n66YnQO1L>ry#f!RFz$aC_@W=Zc(%G~~frb{!G6BU=xX(??T#n#r5C zjy5KfKMw^ct08>iyQhqDmpaya8KYu^jM-s^n2>C%;|CT| z@NCOf($9TAx`)X{yS_DKl83i{QD7(@TQZS+%E3+VC=;m69$n>gnsvJ>OG5kGXcyx~ z|7x)EW-x;l>l|;g0)?Za6Hwb~PX7g@zjj%R39-jq)F`<_SVS<9TY{fWU&x(Acv3S6 zZzeV6w8D9m;g}b25UtHC9Ugm2*vG&&0AX7vSB{VG6LI|sMa^aK6(Uzngb`9R?fkbP{uU$5wwcYL-m2CG3%;+fR9VhDEjZ>HQ@jM1fOC)w;6l)Y5(oYR7FRiNeuA1TCFd`AFj@u%fFC{of>da+ z{asK4`3~*j2nGLke&W#ho6P@k3izw#EKUMX%N20acy{D9oOHCa(u0$N`ek0`6d{e# z3pt(0JkLj*x7lYJ^D_Gu-{i2L{SBQoFp2fI6>6;n<~Dol zHv{t<-Ji#7YDmzYK13cG0 z84K#W(Xx;Qb^p*oth&wsQ2`6nHlO{Sg*MN{Z(waQ1Et4V|1$<{7!TNLXGg9FP^G1( z0eCJx?>L^lgkRRXk>$13y6Gp&WAM5b&ssPzB+O;a?VZS;%yRBz;yA3t)|I7mS)|4l z>15VU!>@?TfStzHGX*e6cR5@J{wJXJQiWe75;2u!Q-m z?+~`1W!rh8B$u_mby?aY7Tdfy0>iqiqkAp{a^$NVb_1=#!2Wje;p)k){-Ospdi`nP zJ4~Y3D4d3!%(*1Uz}4gL@gV|OR?XW*ir7Fw&r`}HhEYpewFim>GZ)%E=b8XcU!G_K zPS`SEsKfW__6Uv=Zj0Lae@TIXPJe*f(9cNTNQ|lKBRjNyy|qp@##Xct!LNIA3%J<3h<*bP=;FeI=61 zY6^eJy$L8hXk1tJ0lQ*Y!@1I3#2;b{8dLd;**i5>JUsipAObzh{=<5MrgMC-ImjN4 zsAR0A$GMX>Hbe$jhs(L{Aln0k8^J4feefK}rSlZ8f#+*J#ao1aQH^y~(PrM`v2}_I za}UBruGM96zaaeL@cvuaFLZDFoKaY?xw#j(=CmfJJv*|jwba0Yx9sFltmV^Pbdi|mG(3j4~ zlpTG?WZSeop9CH?k54)Vmg_x27l1CRe)lh&J(4r_dpUlB*^Rfjj@!O#*TZMF zn8hqOeJ}=$g|74$lCMKG-R)Ib;Lr9M8&89VrjevzaFyxbkRi@9%^ml>9F}Z_eGmJ$ z;7qeoZC7<$KSOz_rcj!xD8@{KUdt!d?WO#ZKES0_FCOcJgy##y>q!45jR;#PaUphs za9Yvo9Xy2TVzUjk1_qlj$|JZ5x_=acG4DHG9#1HOY{uSka!QDFDrs|7op>L`a^p)8 zOl2hn3ck{9g75JA7+Y44qCZ%tZ5|=@>}`$K3O*%Mb3tB7wG@ZTVyO?nX;KGTJvmw8 zOwX(|iJmYLH`)kCnEr`+K`<*mSje9Nq^~}M;@O*ReUbT`*X9HAe85Ew$r1oq_*)tX zoMJze*aCk^Sz;Gut|-XTXKVcT%i)mtv2kR&2vh5fepR7Da>;ZYP8Yg~G|@GX>Rx(40s7O1>ffDbJtR zxqftvPjb+0Huo07v2%t&F56&|Xf+e$RIyogg=ZrgQ0`{t3x^aX_*lU?`O>lg{!VFq z&Pv`fNpyTN+9QJ2=OViV=iQcYqj<2L5W0)B>x;#|%!_6D;>o65)LAs&u${pb&eQF~ zi3O`Pw@S@?YgI?KiRY{6i#v-t%H{?ALj1%HZqwjHf;796P!`&+vk}AXJgJ{Z*&2@6 z2=&dDbhALxAjKZyH`gyL`OMQ9?6Rk#TeO(CB&1#WBuLBMAycis4#$f8>@I+hdHb{z z#jE??Nt{KoJrP_>VRGko+GasW+vd8D{M64Xxr_=`6i_g&HE6)kXHjLIX-T}6SD#V0fyM;Rqn{gMw`?@ED zaTJ<%9?`3|K}{hQ75-6@$&WLLawRn<`loaqeS!ZU@oL7Nm3IYH))(u;Ja6_-rH3({ ztP*V3H&CiM547*8K4h`Ro%*xpl*&XqRT!mcqTkwZQg(!KFB*`*teO7DMN(jm>v;ZC z_NdJwvacQA{{Q-#8D)e98c;o$rmvNLdE zx=cD3E{SRqPlgNqDZ)6o*fpMa7S6O8K~!*&bh|EIC`6+*&BF04t$MbAMNlj2_}8n# zfdT=)-N0kjAGYg^6DLtrsk z^VM*S8>r6FuV?I5p4Fbiy;LmMEUGvwYf+K%-b&6Y#Ho+PezF^pX~GSXrgfwI4iV@| zMs4|nwq5W=lqO2laGM+9m8v(5P4r{RT=P!ce0i6NTrp3!$Pkg2DT&hdrk04ds-q(w z2rejAuG`4BmacP+Lz;yc+bwVwk0gxNSak`Y<*ND)N7`lO&Ef6$(vkfA^xJ*wvEs)e!QSUy?bEnji^fKJxYD8INUwC zu0}qm{Y+W2l-II1*IK-{;de@&$iY+>@y{49`?TK>uR_UK`H1^mvcT2|4fEgfyW37z zJ98v0)isS&ucir@wHUdXUiYk2XL7>{v%l)A36f+_&21?=*zl2#_k0H)0U1RhiZOHD{@yM@|K4~UV@nLGk zcY3hTC0R7%>k5*n4+yt9$ZzB%qhDHT$#(47O-|%578{%*B9x<1(g_^r8L{^Lvfh z$YqrlU)86wo@KE$y?`O{qbi*3ANovQ#eVP8CV9!}T5(250yWlEygH}`S+mW~wdFa|wSGyHPMSMm8Ot;6o4( zB1#u)K@9h~%{+8H7YkcA$mOn#{Q7K}7h$6@K$=;#R`*+yTX<6QK+MWGqRJG}5>Ulr zp(f<56eq~{i4o7|`?;*=ccXna1jK-lAj^g+x>9(d9FE{K{msNr~s`6Rk3Qf8K z&RDNJA-k0@UoMxHg%~9-#1x;oBC)X5C6vF6?`t!F%s{iirDkD6JPk2b*Ryb2$5Qgs z6??RA^ydly^Yv z2dEvUaV<*hL;Z~=sA7Va(=b2(x;n$OZ-c$!y8eE=i>yuS9{iv9i?VAiM<|h{t@yxO zA#$|o<$CbGvWfMko&w4hV?*b8tc{-2o>-o#UD;BaAEKVo*pc3>Fx5xL?U0ok76$Xh z1L_xRgN5D-ixrpAb7BvhUid%0gz=*PTeX~+(z~?gTMgXhgMo_&+UH>da?CBRxMwL= z4NZhk(G{jN($l~!T@p2R%@5UfI>)I%`i@m(IZybWeT@;{cLJ*-T#VWsoR2?N zT--K}xG<-6-T%18k3bVSm^ zakcCh41n#lPd#b|2`}wD$#`1zvV9^mvnZ+g7xQj5xzU9MCwrQ90MSuHdIRt?;E(zm z`>N-B1;Xib`X&AV?y#~DSU^oQ&u%rChr8Hu9IUJgYO?_Gg(JBjV*;E9&5$vpU8b<#H)aoyVo)vBm9E zB+eDDT5`qJ1!yB))R}p|eo*);@u4AIxH_^!nsffaf?FlV@^n6@Es`t-W}Y z5DNKRr-M4UuDuPf{8b7cKBDCs*s>}Y}3VZpHHA>0L3UH5F;#wG;QW^V{#&Hnx0j zh0AK2BAVScCYj?K6dN8Iwe=1Ot98W&uZT!BQCsVelb=+cUNdI8l9f5L1>;2PtXW7T z-vM`SD_VoA;toaE?kS$OX?6Ho?5@;|u7&u*n60f(iM1h*o5qn#eQiu@sn^{8 z(LQ9%w|}iz#d^NyVWyI6Jx;bjyn3o-_Nf?{b5ZwZSb!Qw;2PD3%@PaF>;c=72A;>cKw@W+i#x zHsf~D(%xfC->k1)8O$Ro{q1vDbuoTTzkq-ct=R|o=DSee#(w3tK`r52b7+@M20t%5 zB+Q1c)%_ft1kSB^(SHxLENtmH3EF1KJM+M}l$5rAK~41ArYYdFko@{+$kXSy?l7ct zD^neSzBxRW#=|w1&Vmkje_icnXLM6Vb^mxYvv5`SOLS7!iVhe#m;9|Y1lbnd)98)J zLzbIZNV(4=-FU>;jjXaj<~y#DsJYiITlufJ?U+lO{Kcor|Le06k1rVLo-c~a+}=JU zY)Lk?kcA7Q3mXW6^574~gZ%wIr?v6CPj09(mKWs65no1QtnB%#5k4k#fS^>BXY`gT z@(SF$3go_-(QSWa^OOCWk4qOu&oiGFKMdYwbP*l*8P;qQmbr-(0|Hyeez6aaZAIi6 z(ZJfB{iFJUvMW8qx~cg)I(s#gjGJwds>?~|o98Kuqqdt@%DaMTV~VqBJ}Qls_?H`` zm?N6+xJA^--)zO>S)&hX{ri_U%rDF9ajajEpVT?m=$HYtcIX!+k(#L5(5T}2X7$Wq zKf@fw4O`N7Y7d2_TeWaJ7sICV4#yKh&$SIm&OYF)Zt4X z4fxu8kMYtgt6s>0T&r|jfS-1KiWJV#rF`)O$e{w+j%Dm9+_U97b6WPTL4X;Xx}jgn zJRWE6KF6vIyWZ{!cn3Ufx&eIk$~P%E<6I@$^PC@cpX4y)y!3@A7`CXe+ExM1F02@S z2QJRmY$k!zQvdA}f~(`Iy3T=wuq|zF;E90qjd!7cy*3&wJ!shN)T;k%)j@jTVT5*G9u7WTxvG zjmwy8$sql}eYotVU@!MzIdiK-Jg?yDkd-JWd-_1T(45lLvq$hbZc^t|0XeL$g~q=Y z(AnV65BAD8%;0HU->Zwz-}axR%TYheD*k80Snj%|O@WLZTY}|TSqJ;i$(&R2y5C4A z#h&Vjlq?AgX+A2R7$7q1MdQ5k^|gW%t7fWp@V7X4jkU*9ED!PX(2%l|!xwbk1+JS3 z8e>*n-*45IlsVm&%IsKfJ4^m2Y<%-V8vE3?b)qEkvAwm3-Uu=1s zcMrWH9PcJ6Hy5S1lAYI&0ZNgf2r@P z6-vJ7k3*uED2TE=&*SsrO1}+tHo4~0Hbt2~WrmN9`=33>U~|fyOp1YmG~3Y*W1n! z&ei@;`;&OOt`E&2&%_;~ETlvec9u+|UM8Pi#!Pm+lQZ)p$Nkv&Y735Xr=+Hq(=u?Q_AN)*B&cI@G^)ASE1aFscRZEz zoLEVm1kNj(NBRoJCY4ZbgDhVxeFNC&w1!y>_8+mX%n}rjo~t^?KhwXy2FqX4I16LL zBPsUQHS#RL+qe=GC7^^E=#;`r(h{U9@g`*<_lmD8Z5V#*l*qUPFF2G|F-~dTZd-{e zGJD&q*T^TCg*88Nz)$tdAs z4&ciEtN%W-p@L@o(fz1uh5oncLG^d-8|nSp4$TsFMO};X6>dF_E`OO{P1q%^NPtN< z#nXJAQJeVtoSxC2A{X~Z$t^Jl~>~5lk#LTpQ}`N(M;ztMIX;{uXAbYp!@Ke^2zowL!Ol0Gux-9J4`oO%4c(blO9wA;=W%-Oyj!5{<%jxcXXpeo#i5>9J+A?rt zr2SKc_0SW2Xywy^ZK9UyhMtQ|VePJt1(?>lq2`vnbiB3cXS^S=T)WFhMyZu;b^eF; zR0)Ulg|sBQzNlZL@@ z#(rDj1f*abqk!}~VLMYy_49EB7Bglz++`QC_y;P9_LwgtJ;YPk#2!6~g=?+vCg%_) z$to#<#2mJk8cTYC3!;TnO7qj{C~aNB8pc>wy!Ji|VSaLW2s{RM?UUnU$OpGPC0J6# zUGE4#sq0P4i9c!MrE^H1X=ec(#gcvyn@DwMbZu;)DVWFOo9RDUSJrBnm)P?iegY{R zt33l)Bk*;yv}VKW;iK0@5X-onZ!{oq*CQ7QJE#JpeBMov%sGP(me zer+t%2F!4r%i04fcU`EP#S;wXVXb*C?Jc-)v{%0d52LF@bV48UA2WtD2^l*hlfw{~ zykyEn?$$UHt(qIVb}j>g&5oWdKj`z$d9^#`#hZpP_hor)ld)FP1nm%xD)AE9;dhGT z8BRoZkyovn1PfQ^(kM>++i_EbPGb9f>MJLx5)Z)1Z1M5JQhQB5k+`Er?GuIEg+Vv8!Ivf2HR~O?=O#Mon#P=L2OI=0IC3+Jar&tfqS4_M0D7-6TXBdD+e+ zPi=UNiZV+X?R}I+6W@1oVqo~;TW3_&kDTj%R(*0fxq(}Achi50W{i8^IHade(3L|; z$N98AuCm1+Y}}XCLELVn#e|X@G!pN6nw9jY({>0i5CaENKBv!HKbO~HB9PG{i=emNI_8KmLZHNZK_SFcg_ zRr)LYM$R^tX#08E2xd+H9{S|Erj{ytDsH?cn0_3O;csH35RTEdGhUKPYt}GH!3vXBzz|bYQBo zlIjS=q5jnCKtH8}*2%W6s-YLM(X6A40`}kNeN2eM^m1Xn2gf-~WG@6U!!+W3ovnQoOibMkITScEU!=T;WGj74;wCgbEJzp};;fgg%i!E^03$ z5dGl!nt2JSb07f=xQjQ>#~14c+RF(ET5ltZ=&n8`wIDgG)Uc>GFKU*de&*K*~?``A8hCMq%xFm=P?tcXVbB^4|9S zGsYyD+T4hX*>pqu5%;lgkMIQkdiP2;k#MH{5bgo-Z*ya533;*kNct#6pdaJYQh%%0 zd&=pLqz;Z#m{o$=y-wI^JIb53V*fXCR`VC99QG1i!b6*;11N#jYl)jq+}e>`(oZ_m zd^X*U5>!7eVh44Lw%@am-X`mC_{v-(xVs4jpOx)z`vUH**lA1z=~eqBFTuo`VN3(x;oZ`&j4B4IKn8D=kWJV?Yt8qEw2>e}rmN^~1%zwkoh0UxH=2n=8UCWve z7R~vtj6ecE35+P-|xgeT{gcnMdCuVyo6Ntb|W_ScXvO z!pvj57a(=Bn1%d3MGu+#_>)sxSn0e);f}yO)X!rW_|E-mAH!~dAGQCWS!l+a-qEzG z3yK}|S;}5?HeIBMWjN6P%6?-eGhivM@CW0wWLnByW~(SDtdE5eNIizeoHFkAo7htk z_cl3oo%xWlm%7LFRBog>8?BJJG_!shJ(9jqJHIxO-m5xVxPjrN*q)Na_$pfv7R9_I zHh6TiE(_M!e+7hSPOA^4v*V?KMqSj#lJTiEE!Ny+)T@o9v>IAU{mB{~?VVw$U>jYi zy_bBFu~8Ks`j8nayW;_}Hi*(3CIOZ_b&C}xY~Y(7M;Yu}CKXYBcW1#a)S8ZER1x)A z%irqDG-;z}!92Q?sXIB2{!O7UO-yIpJV^Ok(_DPhK zEt_D-o4TrZl+r;R?pj(sm6p@mpI=6M+sH{eLf>n&3AJaKG?pH7nY*Oz_P1F^K~0;K zk14|#5Ad#6WXf;zT&l8>L{w2zO!q^bG2yj~kO3@O7>fAfjVTMb!z9bl72I43XeW>@F4A}TNGT$thJp3djp%AuOagZV|HQgS)y9n$i!G8%hHllH#G2z?~33D2T0dtAK(y3|lkg1V%PofhwVR4F*bvaH0#4 zHB`sh559!b$g$vAD6?`HY=x>eI)e;|l{g4uAa3vrumO_0;lNQyWP1thg+%5EFhp=q z^&c26kO&h%cYy;t6P(YNlcs^=`7ROR=$ZdP5e5yien+#laRu(6}km4 z<&^Qaxsf?4w9k&u5pjPQv)FOQ9SRS2u3I%XoEsXvF$ z0~AJjSuxP48_0(Ag;=^|k1z(MX0V1Dl{It$6v zf)S!e_DcQ*(tmMYyzP{SfoAkF?TYIFvWZExe#1Qg+|Z(89)5@9mgp$qF899h5AiKM zN$5-Zh7A&EDU(WK_`9gNSyjA;G<|F%`j{~@Fb8#DQe96W%YZza0Im;bu4awMhlYri zLMc4}ZW3IhpQE`77BkZ8V)zushhiqLm3bs{6MB;+id}?G0IC9=kUDmV>uaurlW7CO zTflVHRpCFJc9Ex`lJfwH;_v2sr+ns5<$TA4^DyAjqIR?m%*ptQyaA0dMr0j$Ip72L zBs6Q)WUd7iW3vnPh7cu*|CD!LaEYJB({VoVcJgA$2Y5@+>$Se92n7lcBj-`ejCIH= zxOtll%*{Mt|RX? zONsZ8Je8_c*$#v7u$v*{~HL7%QEPITMQbOD1G5!XqKtgkU0gmnF zZO?PQqaP&#bbO};l7Xn(PB1?p7A@U`b=>l%g;h@Q9kV*$A5Jk+(x*aqb#RmmRIKXq z4*-A4r@C$hQ$%FjDJXLPA=Rt4eqssd}) zRp1nNFw627^3_;;Dpsn+w?-i17E+kseBpb_z7==*`x&-YE$9berD(lYT4M*NX{Oiq zF(#Kw@d(y53@(LKr&-`~P0+Vd4Z_{*7nR{ulG z##~sAn$@^JP?G8r!J9r^$s{IXlNJAxO3GKt?vkP0Txl}pT?$rwnHCv-Su~6OKi_Kt zEi>Q6fu{uOtd}EKI5C2$s#nyp|3_s9?O*B}MILQ$UA*isJ+~}gdYCakr%~d~oSJ-6 zbe#D*yj-|~^~raXe+&5Jl8k=mL|9{y7?8yKPq`2H#QvqAu_Gu4gr4Lj zidOqPK|=*%7b920E3(l-Uy&g=Ru)?SFXOaysZmIrAbw()TJ=d}(zz8$gf*JNOi-{; zwKj1%@0Y?qv=ZGXZTHb217c4XI(LF#fz1enM+c!K>4}!(^ed8)rpp9tG1~B@%1z`~ zKV0}kILpY)9LGPR+n2DPH=tP_Iuk8Z9PkN8!lg2o1XwQ|6Z1ebcw&$!P48-t6@ z`QD&SxJk9aB2Bm!9Sd2D=umV8(AD< zA8Ul{qCW#n!64cpw_W87yiaqHe`KSvDKZPr%=K%;H#ps1H$}6+kmUjV z8t{+RadZmQ#UvTTTsxABZUFvWYtZ};zEbi*^&alao1}Dy+f%jj>2Pn%b?It&d(dO? zQh1x!VPP@6V|gL(G~8>w0I7q!8HIXSBlOsrC=mYa?g#VdRb2eJocblth+E(upt9UUyXsB#MI9&2qmdA{OX zNK%(4AWXqk>vM20Z$0IUc6wVk_Pv_X!mT`~Jk(TO*eZWy{*Y}e3otb$yGye4hokO@ zy0w!6^8`9&mFEuLHrd4GL5SVh^6>%mf_H;>sOxC?%&{AyU&X~TOlxOV|3;gpCpDuR zbPdIr&GGw8!MMfY3VjM;<2pz6NwS@Ltzwuu;&4==V=i5mBy?g=ATH}9RsX6DXnRqM zDVxz!g1MJ>wQ(DkyCL5kfp>~G8U2W>!dbck@|<-}s&~|4cS!z@u5kD)e$K)!QwdP^ zeFC+^8RuTp-a3d+C}lPK5lZq>8#Kg@^yl@Cq)+jF25X8c+)bNKo4IbBYCQd}yI5|; zY;yDzy93Xbz2INxT*sekdqCb@{l0}kVU-+jnnCr5!xMdxB?sf&cyLK%u%g71FQ zr7!t+-6`Ts-Yq95{s=0tG9U^>gt^u%{a2NEh<|HW^J zpfpwxi-Q79ugR(2uDV^+{jMj~6BrZiw#eqP9xp8xzUBl~S@yGVImMiwP58`QL+4XM zdfLmj8$?sWqUMjJ4-tM1u@qC#Jmc6>(A!RXfU&^!k;<0&((bD?iXFQ2fN%|HUuo=H zN$x26)?GtM%AMD-mGU_a-@1ubStLt~A&)6c^ zUqa`MEVB`ipt%*FduK3L6yem(>D=j{}aftOfTvk8!6%}aIZ)2Bw zeO4dmgs+;Z$OCQc0r6I7)iRL32l`u)-ZKN-QFx&<863))-DUzer|O&Q!OL;)8+Jl- z!xK%`P)1<2?jof0dZc;}JzV7^SHS-ECqy6M#$_M)7Vxw3-CbXJrwWrhqIfyk9jy)M zm(<{<4zxS2&wLUkhA%P(qOO6V+F!_Xuj?vjq-9m0>@ZT{uu$ZJ%(JZJg>x^K`*ux{ zKn4G`SBiVHBU+A$?xehKyd+u_S6cr^hzq-8;0n3}7i&}b@4SvELH?Xok+Ma+SceE9 zgvMF!M7t4b*+{3m3N9#bGbux|ZZ>~X{F9<=_#-2K5IvA$bpO=&c+|vw+-M#u1 zcZHp+LZo zu_Q~ZW{(y{Zq2Bjkn?V63C1g3G;p@AFahj!#y*Ym>)eG$)_)!ID9QY2jdU{NQEP0b zO>vp7jbr55E|%8=Axli6M;x?h&hTs8wwxWCPvA}IG5vZ1H6gfXJaKc>gpLOCxb>G? z3Mt)w+7`+VvqejOimbqb!p%b{`AkmsCK9DA?Rj4oWSNn}Znh{bJ0?Og|5b-pJbJlCH+ESJ?JRpK)F+Efi)z;e~4lvzarq zUkxNO^V4L#>zEz!jh*{gt0RH7GS;Q_h6iBQm$O7Cf-NpfLoRLV^BzfXxuCd-c-jq#>Bx*_7x|O9FAK^BR)`C-V|#-{sl}b9tw5LSNXu6P-X^EM0gNh$;V5f1u)B){~wr z`OegBooO;K?p5nkX>!EFrmd3f_2cW$iv4}x7#u~bJalTk;Lgg4ateR5{Y;TFZ@pzS zdI$B+=k|%TN3)>r7R|cU@(!7*KW?CPsnRl{yYYkkY|!cY<+3Q>(|V=kqK8sFN%Udm zOxb;*ul)jH8{gS745gr(^H=shHXhFM>H4MrlfndljT7&x+lt-GO2&csk-BAsAR;ZVgoGh)i`!0tsHfMu(VZDIheymL z*1_HQay9Pv;7FwlVP1Pz)m7q5{rnme$y0>IxRVQ+zF2F@2*wZhi+V42gqTJziCaMy zGcJrJVkN9LhtG`d>{UAzrIqxoO~1-l(En?jUpa*lsO_ry&e$n*soBchz;MAFWm(jg zWB0Rkxr+&YKx%9cNyVP#-AJuxzjpkGVa4eh-Cc}>z7C|8MnSh*q~%eNSrcAa0TKBx zs*}bxXEwDmh*P7e>xPIqWPC7G61$qX9m@5tp}c_n9aquy(7bKG3Xh4t_6-*girkvV zmmU(PsV-KG7w~wERkQhTX%;nfzF)NwGt7gtdvUd>F{X|16FJ}=Puai~JJ!){Vf@JQ zf>`bRo{vSzYIS2q2~IUz8CG^cAw>Nv9?N|w*Q)EJ%~kx`!xG!9{n!>!K+H5kynyQM zOFqGy=(vwI$i2OVoxifNwL8Bs-VB;=7E?_{@>iu74ED&JigCK7i){sS_@@W z*7&+#GG(*|zeoJkdpS8%5bOAbmX59%`m=F$_twr21;rho>!n4iwgB0ol8?<%+{xvu z8YH9-l{ZX*75}SA(K}|=)@@V=Mf>4BzEyIh*bKkXCD!$*x&xQysfZQW(NLS8KRCRys!Apdqn(D9ZQ=`_NaYQT}Ua$ zMr21&-xJoxET;2FZ@l7|avIfs5b$M+N8q~Im7cvktVPwECKsGVO_ORF-XB9nFA#9p zVCp>L1AKgylDwX1o7GMEL9UB#r){I^yyh`pG4ky9v39cdZE3B!hrQQ*3^NzMxIt7G zM{rlPV|$5}2!i`b>LGt8$SMC;_K>Dh^D;k^pVPiXFQXo1fSy+wE-bSBP1Z8D_0XBB zd(`h;(`(k#`s!cRw$okZYwDKM4|7AYS_X~u1|P+Ys<=qF!TgY!PP)lD8`VO&3Uqol z(97Aw_Me#`M>%LwX#o~@6jwnY!&Fi;4J?yhs2v6K;OTX7AV_?Lvj;oNf8j5JqZvcQ zx8SL$Rg?+fBTq7IC-~99lJN!nx+%51NI0?WRK;fj)o{Pc#J?)R)Kv3*z;k1LlEZ}i zSWBK)`2yTiv~9yjq66|Ua*&*WczYJo9Jt;NB@6&g>8~$+sOoEVEte~+^_i7n3OCW8 zYG>I4jVS_Lyay7}sKjE28RigC{dl?hB+xuphT&{oG zyuD0nnymd(5o+)do~l}@Tf;`G|BkIdzGK`}R;5K)SH=8v0lrHLMw}##7ccZor!L~3 zcKA(iLVos`ia&MqG^LkrZFAS`C@*O~DCn<@Yn%lLsvYYQoI`D?0ar3mhtnGV&(K*v zM6tI~Tz#*4?Y@dMh=?Epf*{=@-JQFz-MzCjyR$R1-3v=Mh}ezYdhNV+cXzk%{sYf1 zGv9iib3P|;1Z$Z2ccO^HH1q~V^LsU}b0&!r6!s9snu@hq9Z7iSRVCK#wTD+QmHP;* z`{znlk<>k77!{Or9U-_ew1+L7xi%(Zo0J&B{$)NBXzov3Q<1^EdzpPDxDSJ&q1Vg<>B!!nuRBY7N~BRoc3Q)?9&858m|#NDi4 zi3fob+}!~`z&v5Oy9jCqOsl0F5y8^q&GjPHG(y~C6c_DWUOV-(6y(G7{Vcse#k_() zBjmBSe=FbM=a_a=0lJEqHCmD!#CyrGdZ=wm{0F!<^gF?KMkyF4E^YhxmJC9tqQgR9R(! zMBFUv@R%qmm!0i5Qk|6(TN`Oa#gI9dKB!oRH8aOy7sdUo8VsR{*iSHr>U?f2x-MrT z?+5A}-z(UIGzBolqvU5j3W2+FkKX&_4pV%~D9TS`wDATl#}JD~(@*NX?LSVa&W9>u z-Ozlh;&QUpSF#Iu3skl7{({lUQ2`7Q19SD*0#qSzkCbF=UeL6c{I*ePSWiuCc!4aW z9jtd1VvJA=o3e%Z*2Jwm&V~%jvyO2^y5hM1_$1AO0GjZ*GR)(L_$|7tdm(X8Pkp0? z?9^4HZ=}?Ac*_@2@3yWI^wCS2v&o;C9yYjgKI?$>RaQ3VylHtH%DbR91r!LGYNqE@ zJ5gjrmp3tRy=`iRl@;G~H1i>+yxtfW z&Z{-G1S}Lz)8aixiW8L1ohgKY4G-+6?cZyUYY&j~S8bFDDR)-5^8V0j`*x9}jF_&5 z@;A)qZL2bAoUx4qu`hWuEMEe~3C`*6c#aTHP`>Ql1w5!KYrZa-T(jMHM&erg4;moJ zAs`}uNjK>rbs{*NN~#(U7SYdU?F6s0_Q!sLWL%{`URo`Tb90t?0*yUX(R#v&rZwWp z#2bd~;$m_y5+vSFl?ao8czQA=7P!D9RhCLp*#%jll6TxKvCF}2{4f6b&_2;`w|Hrr zWPR6JK@aV9qo**4k)V$gu3*aGyP{y$CBYogMNSBLnOMcWQ~?7n{G?1P@Jjf1Y>MQD zXt#ehGy(YKCXxOHe(#Lt9p(`lR`7-VDD73j1Uo&vQ?O02gFjWs5O$LAqDax2@@=BG zVq3;9@e^Qe%va!#WWRqFSOvMet%f+#!uFNiIbdMDFZTmz(C~RH!2{ANJ{$bX{V9lr za)<)qJZN{>3*iUp)C`h%tdtis0K`cz`=?2c$dcWzf$wF5t-skTu@ROgP7``v^_|N^ zyP;9MBD9cmoF9dH5m+H`gc&rKt)WAnq+;?f0z5S1}~oKUGOiM}Lys0j8?1zOM+ zcU1BMiEsMKoNG%lo@Fhpzp0?JU9AwXiQ{R0%G$>DG|_8^czK5PC3-$d?~BkSF)=H(HA{Snoz^^!`IeJq`&2ubYpQ3J z4CigL%t@Or2sSQ=_7bkvRr~vh)v7h_ZzaRAm9~@g>jPu-R~UEuy3t<+d+)9@oA3NHNUIupLd^$Ukj)5_L@&Z;V^;M?7DHxjzRsD25uI(F@lc)qP?R zR(?m0FiTe~7Dcjnecu^Ewx;_5?ilB0$E>1Pym2k^)L6c*;Z~GR@WYHPxFvd`ee3=T z;49(gBzZ>Fe3PSmR*hJ33O<5A5Bz|2ge9!)Fhl}s5tu>sEh&JD={>1G;bpA0s9A6Y zm*RT^#)OeBH{gxHn#Mn}=sMK!OBO@KVP|AsUh3*=H$Nup_crdRip&eJ6_s?z$$+Y~Y`US(0XMgf3C?fVU8d04MQ> z*|mNN{9E+TpjL1J=L((|{wxZG#)<#8Oaw82$Vh^n1VHf{BW(pgxPr2=(k$x`Fbx>c zd;qu-FZesKRRRgtN`_0$)BZ?G!T6d?$q;z95Cca+X(_)zBXlh?5Q>#n`#DHQ%SO1a zlImp^OQ>i7nV^=7-I1xXRxyf<Pq00d|$zKNua%JO_Ka4mqpwM z+vEj)?hqg!?fOXr+MkqO2mfv1(KI4L-2iG@6cNoG%Opzx&eEcuxz z+n}@SH{R*T<)@3a+6_x%fGYK?2p37TD%Q^ljK+Su^@HzFf5UWsW$P_$uV8qK4;Utp zHmNx^g5S0la*zO8IX?^>s@%a zdSlR=e08^{ge(}-Ifp$cFtr^dS%tG(I2HZEOO5q;6p^C-W-=rum@~scAWHw)_o^gA zz0vI==%^^sCG#o=x1uBX{|qb!Z2Xmd|FRwklDZ!f9|&%Dx>igQ_O`CieI?3ms!Mhd z`_(&#hlszLX8Z1zjMk2KyDzz}bT*W#v#SiED8p_{ek&J7(Yte(Omq`lLmrD-2kL=+e@u4Gu;{Q3nl^>M6)*i&#s3c@7 zmP>mM<;w;49xA>O)-3mu z%<~z7-+;GW?1}4AygF8H6Z^nR1-Mdr-lY-tky(|$;rVcoYz#aTE*6}DhrtwjiR=wbu2sk$!jh8v zvR$w(dxESHUYBrOW`lQ!CCiS$hkYK%&cHidF3I}gZT3|7?dnm`F6kas7r#|{NEJGEZc)tH11T`BN+xT5oCw zo1ufoRlH8(=r*IJaY&wIhO6-6y{6QfF7^fE zRQv;yRez5VUG+`(gaj2_(ypZ@q!TnU`o-92^<>tQ;MK~T++%Z3E7F9!oHk)2B?)kh zaZT-e(Q89H;U;^&-bz|e`b$?&u~b3Y12lR8RkM%nBiSz?R7i}3cta5{q;XX+uP|m% znIXUjs}x0|Vs8iRf0DnPgOFPg9(tkEu}2AZX!mj!GXK%M;QA4~HRE^z6*trg{ItA3 zsz||>)a%Mr;rEzKMUvPq|HClgjdwCy3Ep(3A{kO6cu_k`*v{|PWQnpFqtz@8&2K+jNhq5eipb814`z*Orw&Ltkl>IT|!Xtxvg#bgR}z zy+Ot*m5Z*(I}{XeD|`-p=Tay8iCh#h6^8oP>_+UT^$3N5Ra(~JW}q9**`+1u4CD74 zCxmJ!Pm#!<>uyDL%5jS5j}9H{7W>5$RUE5au1TPvP*1cRDyk~gA{n%Ff$ zG|aZP4DX0?-2gi! z;G^amFL=(NN+ep~ctRnStmYqTEU3ND9N(~qaD@1%ejcf*N@c01D2lF|7txrRM~ytj z#pF2sQTE>v%d|(i8v=f5rV9e+Tu`1Cw>jDQOkf-DY{Mx^3B#|xkouT7-Exy&PtD{6LuTe?|NrY1omH@5h-mXt&Ev7HA zJY`oAyvz`XSnPNoEY#%RR&!33Q^R7@12^_ z<`UXqXJ$i zHFhUXg*~CB-{~YeNp_0;+DrhqQnO8?!C$pyh9PK4d6gayK?PHF{?N^Iyk>>8FtI?L zBRw7-rF{#+uIT_Ig999fN%Dh_9B4na-ru>Bb2J^eoOFM_$tbd@<;qL1O zG$YC!wdLyKypI|`)%G-j>WK1ZLW8nJS-fPcBHzx~X~9ylm0o?wTGZlfkOv}%nF|dW z<{zZHdKc4oT!QwFX=15GqcJ?slc@{zXVYdYf9oU(X^O|%xFtett-33KWX}zs=+%i# zRLpkX5BH$!7+QU2(_~V#PGuXaS+C7);FnIB@FGk^f2beUo=w#2{%Y;68KZg9{JTV@Uf(n}w_nw53rJ-v z`PQfLM-)`^#wFu0N5i%NC*+a#p;xCoPNjC4CA+0?rmXJXQ9Y_Qz0-{Iu4ri|)|M8$ zYjr0a${O7~fjlkwm5oMy7E^A0%P@wlH+^Rx_1j{g@Q!-S(f%zuIJ-r)1oWhg@0weC z7ynIAd%uE}`ib$@kAHzwD{$k$F^9?Z? zhY7@fS9NPet3B$~8j0C4NO4~}jI^$OIupW)TfJFrWsjOe*sJo%jk7r~GB!4N@ZyrL zSl06IN1IGcVM$1Z{*HLA-(Br?;GV}x)n3TmQK|@#jUYa5?cqn&Y-!%Y|5E1Lcw8`$ zccfvbP@3UpJuPAo5NRSQ>nWlXw-Qo99GeSo3v}-%y zIH!r|4fq2gpy`(!s$S6OEGLxQZAg<>=Wel<%kk-9X1$!B*lC}$tD^e!dGe0nx7w-l zEqf8h@(Lss`Ia)#wsjJzm+Bn`YrC7o^=Xbt{e~<{7w( zoG7wRgFO#Ep((;}eos|A^qwb#okqi)`VbXzp!T(Wx^bgwdP9l+NAY{BQSYDg%-p0) zNK+b*YpID7^cywgs72bFY9M$(y-5|}cV2lyInEQq{4kr-Y57;wP|LU3ac7mC_3Nz3 z#Tv_V%bXmu>AUGt+7f$br#s<-KHe}lYP43O+Zn7@r)p05?Nw&0K6xt9jfz7~&*d5{ z9RH|cusN}ET>Y%Z{l$M>K|Mxy)o-KX zn?~x{g61f9InR%vM;_q`-M%*X69hf2xlVp}MU9FlAP0RWFIk z%AeLfi*_<&T!)1rO1{wM%?gfL(>$7!wPddCA6`tr7fZ8Xoe$4w7X5THXmye|v;9>; z(yXeBeId-ul8fDMSowLX&duzSbWM8*XH9Z-%Sqm}n4HE<{DWan>dy&N10I+;;!q!h z!62F7c2=_%!p~MJnX>q*pq@*-p^~Vs20l6WPe+BoDSbxk6XB$!pUs$PX3TJ#NSqV4 z!MXyV2V64MN-p^f>f4|N?o-q^q&H{ZQfz@2Rhql4Kv40f&V0a_Yi{=d-rH3)LlQ;O zmZoaZC;C_e5quh^vkXGEfOAH%l;?9)w?~%hUZS1^=Qze;-{fu;U%O)9z~YdODX@30 zf9osQFOA!5gfo*wjfpTE-Bw=>ZwsTDx53W?P8k~Ifj*D4x8;C)pDI#*%5g2W7@1T7 zbb2dJ7oBP!r>M%g*76?vlNQj_gsn}Au@zvPXr@(#`G#ef-lH!A4(V^8-9GQN?r5d^ zd8Hct+wl`>L(Y}|>G0L9FRE^H)!xd1TSjSTrao>Q)MO|AZeXcbMlZ4KQ#}ZqXNpt# z1Z>d`Cphy)cLp57r;n z3!_I{f^-RCql`zj4grI@&1$93C-oE6X!qBON=35MT*QV=FCW{s%@$e+wd|`um3^XV zrL{J-!d7IylW3?>BwTNp~P|B zvYMrN_|+A7?~Il~Lfz!0zRUfH6>+3qAM%RuL!IR`B=~geA!gVDQX`YoJ9mw>oqyD& z+pt2sXV!g9D|n~)>6(3YoAVZ}d`e8ns9Q0XbSe33-xJEIxY+JbwA10MJHnZ1!G~Km zvj-P&Z9?AQ+!K~vLaxh2{axUL!(8=aXk&5j>VGI@xsL~{sBIaOmiN$ZClB`4Gn8?| zx>mAc!;!WxoXX%0%~D>;0h$L73X=+GOd+Fx)O9#p)Q99s&tvC zX!GDK9*{eFxti~jp49u6eFEwVdjT-%PUlsLOKeU1SjpLNhh`br8Ei)` zKqU)$EpgI(djiORvIMsYnrfIbdynFPJhf=fa=xrOr@wEw443w&8qQ>NB9mBEDNKoPR{$#8vhtl&13s1Y) z#X;{St!eK^2Vz58KB1Z=zZ*MIVz9VggeEUIZ0bV2yie%;&`EBCs*}hkM?IE}JT0v0 zTdet$Graq*CN2%_q^fmEthP4Qa8&z%x>=}(Pn zHY{mu0QDuo;g&|-xCN&Sr!`sghHLXxtKB{-ofO9$FCkAccuNdnSy|rTR-&!qc>5#L zv+6R_5Cy@9pjz65x?8*_^v|U8L_G5pm0bvO<};2ZZ{P{o&x6!L690=wz4*A8wJ8Ii zhTFR0@7i0ngKb=bhR|*llGvmx2#*p@9mf4Z!_$d`76z9oE4ay?#F?KQ#?|xI2W1Pk z3Ez73h?fCdH{?|-DVpWWa8D7km1R>+AJc>kNSvg-R2RWs6d+EctcMANN z7x?FsHgW*r+MpTy8^BDDt)ec_a~-jA7-xTqIy;3{q#{LwR1 z@CF7}PAPh2c-6VSG*|zm{!aN--5u3HRgd;E$i*$ud}0o(%TV9O(MWStr*kdTZY49} zG2^PjJFu5K2Bmsx1Zw%a6<8s^X>mtr$w*thRZ+IG{)3WJsk4Sl>S{vGs~E1ewZ?-r z8;LpkkGX$So@-YpG%zC7s=!W8qhht^K|u%_Kj2jm(EYycS<&6jZI+_awsurOs%U6+ z0(jNAP4=`Je51{!W<0@aMRPhSai-7&J6=KW7HH=9s{i)9!heEwEDy@3t?X_6UF1FR z$SfcwLgJ-*s@CI{Q00t5F{R zn|9T5K9Iq#*RA%v!3UIGt5;F|OF#CEqIp&*8^_USS9@tpj0)Tz=oNEC-CE{Xb~tGx zel}+twL145Z#`pA!al(u`#}II4&i@u7f2GsvXys9CAeu_5ZP4g*07y&f#9Jg(ke(b z;1l{oN(0k@xs5&vSHY$*!*i>+E$oj8h5UUyWk87t7T$8#13Q6jE56tLOK$1dM~tQV z)w_}o)4G-4C{o5!d*HPX^CM##V;=i*4a^$F<>YMQ)bWA%8@x?IYJjh>U;M#+B`_9r z8kmQ#W;eA@s+-7JZLt!LaO)KsehBhcA(IQbP(3Q;9L zK~17el&`PyqLs_htUJtLd0bpK`;q*wh4=V%@G6gRQ94}JGqXaZ+u6jbLbdMgxVo#bH?-j<*1>MEbn zu&Hr!Wn6uxepWTd@(Estdtep{=GQGYO(m;|-wfpyTPafAfy`s{HqB7%ca} znIhcdk`O~3IwMP8bUHNbt613Xu6Yz>pGt9jo%nV(vl*EpPXn&?|Es_-Q5vp8hZ zXdjI;VvjIC>S7n(=DtwLJzfd@F-pgx($E2V{qAzK@0)f+<-wk2>HV72&O1CKeq(zA zX)eLmGNQbX9B6x!=|SUJ{}U%ty`uVWkTZXyl%VvG;0mE49Am)nqx!ELiaB{~Z(j}IpA%zmmZqk-hRUEx+ zJpFI(a-NQ%=3OGbWMv8h%R|{Oghd%N?q|`#7?}SXaQAlk*UnE6kAZwfCMfyF?ORz1*mp>Cq@}DexD0Ovv z2`rS}YBks1gDsY21Toy8T1%P=tHCwo$FPjUr*46*g!%L{a98Pe=6bj-J)JWKRz?5E z%Y}LN3Mp`od#HE_4r_ja_tfZ2M`~}XUnrLn8r1ocI+9AYj-5|os+{T~Xsea@lDCXC ziVbO-*?!pmXc4y_z3%TI*o^eJH;Uus-A$&NW7a?;hHp22Q@GVpOlN>{BG(A9=wzxP zz80qL*BvP-pOFI>&x*2wU)z zU#mXu{zVk52yKv8QC3aYwbqocpdvDSWdCW=ggSiB5k?-7(|HfKn*6pcyXYRxzv*LY z3gdTuM^rPr$D~>Cl<%pHb^jw8rX1DcDp*q5Y}zN-P!X+MARJfqND?Bn;8wBThyv^4 zYX?OiNEsz5;vVXh)FVJ6gB$rx($8-5eF2TE{T`X>I+QHph<6#7OY<#@pZ~nNt z9AE+e3{k}zA?PP>#NQNl&|-@_MFNH{HB)S3mq!i(M|pqwJ_JjJ^{!sfa$rZJ3%iW? zRsWWgL~cZl+-X!d(G}is+7-q%-fu<|?!I6StFP#ca4v_nY>$Y?8;GQd&j=3qK9`up zCf5q^7x;HW4|6)RSf^*Xu>d5VJ%cS5uH*P|*3++XGr8|^<9XeDT9G6FgkaOMcwvet zCNfBLR=msiBXC%<-qipWLxg%y`c&ax+HgjQaHV_(GffmI7-Z>0XKA0<|A{pRC`UtI6dR}&vepdQ|58DO6 zW2x_0t+JSE1}9j?FWANHl(nTSJfkaGf_Q$@GE;L%fR7$FC45y6xtUj5%fDT$ZD}9)FQ+M7ywv*vh z@_lZMjuL*BAE)v58zsD@^mn@@{*Ip4V}z!z1DG$#zhj4_iM+b)6#D=*x5Y^6r#){X zRSYq1H5|@UvU;q`l6yI4O=H8mco%hFeBTJAs-JH6#VfFDx?OdD1~O3+v9s?!@PIt8 zN5yuf-0eI{nnXj}=T`(WWXZbfmj+c&P5SHXgF}BsmC|kt8 z>wHFbLcH5>90;o3p@;-5xEmk>T&#V^VN3jpKBPaAZgN4z5a>?*m=_7E8Tm=qpegJ{ zOWdFh+=o65QiV|K{7n`LoYgNCz9mMZ=S2wVnZ%xkK*8A2Vt}@k_!gMNm{fiS7-9wF zN+b!Kf0D{1-+8#Ox8Om6(LRkjECyUcr8aPy_6`3OBMxa2089XwAe_YNU_}eJvF{P5 zi>Tbi<GSE4k132Dy;8Qjja2 zz%LaJXW|6&ga-&k!eOF@GOqBQ*qBo$IslLo*N87kXkoj7Z(xE^t&C6N2qZl7i5uqWg+@^T*hgBsN!rXO{^omh)yA{>^;LFVruLzb&|~ofW!56sw-?^V6;*QP@|v09BwAy0$$@vW9WA z733ab-fzB0S;rpNcn_Dz@v#jnp2M|RS7#3LZkYM;{Q|N<6Dkm%)gJVDF78!@yIz#c z!cb&A?M<&1_{3P!jpI5nYdfkGPW-X8t38 zL7fr@$u}_+A!d0qd%JhMTqgL(>8P9u3`b$PYc)@DNInVI%H08fs@+Vfgr5^$*Yv}m z$!sW$*Sh;`0(1_Brl{|8N` zM~QQxbVegv20_frq&jFTdtud6=o6>D;E>dh7nfclE#M!B6-ir#hL8;DcX6!ufD9)= zohh<@NG{tTS<3SgrAf^EDXd1x4gMoyAGkztq$&~Y5N;|62S19=q`iWch)=}E+s~KJ zA?Z?oaH97K=>bUKY?V1nH%qPJK8dq18u&|MW_AEva0KC~WH`vLR7niroBTF#G$cr) zf;i||%m?t1loApI!O|Pv52XuaHO|MR9kN?clJFODSuji_M|Lnc;+e?Cx*g(UNOwgu zz((rxE=tBDtkmNY1WAj5L1$!q@MrL_{HXUQNF}dyag>gi&jg1FwrC@HXN7qh8@)pK zO*6LkuxP!yw*08LOm#GG0Wd)|EY;p~SEj_wkd!HMf;WJZuqyAb;1krvzPb@)0dSo^ zV0pzoASf}Pq_Kp}`Ll|-pJ?fN&k6#Fgq*X5U9^BVmwfE+KN0RUaJNVBjy zhn=G~;3VWOg0orrTvL8L`6T@>T!8;F0fjm*(iYp^_)py(&|KlZ!Ko2Zt% zH`zY(<(Ee^Af3YWKn%$jdw9|0S0qhNa(OAVi+2!R!P&-`hvst+5xvkUyrIf3$aVhK zqFQ8~;9zDsk}n#a^i}>%>=R-4%>rnkMUF|1c-iCu5Y?$4J|(@%y@8Cevl=qx|B7D_ z%H_)eX=RGMTk=ogDS3}%YsM`(6{ICK$-STn5z+7y=-)sSd_hX}+6vobVNPe^c-bq? zIamU>(Q@HDcvT%2&Vf%>h+!K1r0^eDEgzMU40GhpNv^P+cM|>{c9aJNGT=#aU$0ZL zNAl^;Q)L74$?UDNc$J8nAq!HCsWr;Nm7B}A%5s#;3Rp6V;$iwB8BtM_I3z2^o`(0x z(y`dU2w67T==Gm064~rrESru@VXc+=8tW-#(g4F2{61-@{(bp4X^j4_{AbcMopU-) zTB7-tNR?96Z^EmkGL<}VwA7|__PQi(#LAsJq$v6i^F2grxI|tFq4nK(PsnK1ml+_7 zB`jYHwVIx$dqUfcv5Aq;4gElPF!W0+3Aitvrp9|+w`+edI^U2^L%%aK!Hcb_q~Fk} z=7Tr{a&5{f8v!k}8S`gBiS^ghPCyLHj)V_TlWB0t4`@h#H{c+&UmNE23i?+y(!~ur zgbgviTieT`?Ox!*iXAoon#Wbglsq@?!hOm;Y-p;}r>5!WlXk|(Y0pttg+A1TF+=>L zRJS>Z=Ln^v;D_U1*h=6I!{6LjT|j(m65%8@amM`G<`TdVM7Wnr(1(*fQ%7n)Q{Ti- z(d=eOLoccm+4cU*RHJz!&jpHF5z#RL8zZ?u4=|ps+fE!~I6>4^)AfhRsl_{W+o{1h zJG7_hp39gT`ztxFO)X&$hBm2ud9nV>l(Pg|J*%;9V6>wStpOj><{AE?qJ$~>8MNP3 zI-Ms2SM)(Um-#ejlqQJ{r2MD$;^N{wRjz!8&??1m;e7urg^SqT(~Mr1>~lPX?1p|( zqjb^ij=B(S0cWW4UyYEvyC_}V!Mm2tRoxbhNGVj_7E)r5Dn5wTghpdufQ9~5ShS?g za~C=X5;(p@++<@YY)z-|daY2sN2IKDRQ(VK7Vc1GiC<)WQ0@fQEPbK4BQeB^7309d zPrU9+gxF=sk4yjXP`jAAGY_V0oPFd&gA@^6L&zWWC+P`u- zDcgm7CT3ypEz4`#FqXNmYyiDxI+VW&4Kc3EOhMKex|0WxdHQ8BhG(vcQ?gUd9t=OoFRmDSG0(k~bv54QP~^;E2E!BvhcLYwTnWVX<@AD^7+ z+%UQBN&JB2IoTy*z|IDl6|~;KVD6re)8%np-S(@Sh3yWXmF1FZ-0PN@>gtNfCLK;( zloz?w(G=@LVZIf>1$S(bq(d)GJ<6R?N7X;DTc|7NHI{@>w}tf@jU8$gN7y? z;l4om8=%fsVn3kx8m?_Q;O|ITt|D2^L^R{x>eFd?Wk(^zbfJw#unNn$- z$4`!n)Yl2lhp*5c7A+2{Qoj(toIj)@NfhoaibANtaRh3UC02d6W($^;%FVZhqw+VK z6v9)Pqm4eI4NHINUy2)JU+L0-zHpA_u%s!dKs_8hF#o*L2wiYLi#5pRI>sW;;Hat~ z^BJ(EIn)(o=B-~hx)Z{HU%tk6Q0(57Ps->CQ9;7ywsPRYe;WJb>k=mez z$`qt*{w?e!lI-D(Iw0F47iF(9PX-^Ev)vr!p zqy3-mO7bJS6MRyvv#Lisb;$#zOfxHJn&NNO(EJPNMrEEyy!K2kaFJRChgy@>a!q zCjy*=EiBFJEhzWOzurB!l9%Pt@u&Jm%F4EF_?Gw^Elq@&$a#(bk-^1d8+>ST{{r(5 zR;+iVaS?Z?%QJ1aDA-|wYP;lY>8S3K>b3dZo$*HZu2%{D)3ky1eOsOpo~g*&JARA`I3R&c~2-<_O+(|6&7I81CJonAzn z@eS|2+KG}z*Lx~w=!BQRBcGeHSpsxP1=|Q%_N;AGoQ<$F^CncRR1sSHs zS`AzE0pYOjqs}2@hBjO~+@Ga-q!!J~QtVW|cl(6;C>A=dkSC&la<>j5rq zrsPUs&v{_Z;{`gm=%tJoscV}%=y$8SN&g~zpTbnVlH;oDHVv%8+NuJNm$`kW^fg+ajDQ0fO-dr06TE$C_c}K6b;(cLtO9&odCMXpFOt;wPJ}Mr+Au|YAh6Gp3q1Cv8b^Ya zUjORm*wdOusf@D9*#X#oxI0_i83y3eR<|z(PA4B|^^+`(i*LFsc^O$~+YHt(-eCOz z6$Y+0XG+KVY7JARpXLtJ2Fp&m)+*P+r)RG~Kgun3M!|C#l*VuUBhx3hv<#Q6jq_^U zBYSJ-EwsZCi~B9#VRPUb6C1we+oeyG$IkW9P~?rSy^8nppR?biSx83KrMAu3;j}p| z*Dx@-yy+&E7W>0y!xl!m*2^*X#d`A}Y*b*su>pPHyFn*H*UU{(_oFn|!-@pd&2cia z2l<%AZC$4UQ_nTuQol@gX}ql##GY?xR*$r2mo%tWEasSlRC5EH4R@98zPq*O6&L4L zt4AnCxn9GDu$hhyNCpaId9>^^AgQXR&-%?tk8OW+A7j_l|Eu$hxNo_rl`bwf=`_88 zIzyWJpzi@~vPv_Tr;;hNT)$(<*b~QC`8)K}igz^;1!{koGOD7TkXE@K za3KZN?4~g&(zC#2Ke=A2xiKH<#R%v^=bM0g4&WyRF-_n~gwY2@xul`hav&_pK;CIT3 zJEmmks~Gj-Ja^?Y4Ny2$StgxXQlU7>?JE~3vWd>sLD<$ZJboQEGrgbq14 z{t)|r@(%ag{5bf2TWhA;%&^YR(U~&TG5M>EbD)vM&iY53t!4ST1BA+|Ky7vDRor3C zr1S#f0##k~H)@RHiocmsC*7X8)0WIrw~ zw)WR;uFNs>N=Y>zjCJYr2?E`*=vS2Gngai3);#4rk9giXw53InKDpP)?39(=^-O6u ztaNOVfQ3il`pl4b(d=5r7MYh@Q=9H z$h`!B@P+z-OfB=Gf1`~^Ph)Lj#zq%%$(%U94}up07uS8_z2d5NLe)+DQ|qCcrn-yj zgZOIVN~o|-OtyDOiAw4@!bI{PhEHi3EsqtHHptB4?2UTC3E{i=UFW|Pg}6Qxy#p?` zwp0wK9+heq5T*eQB}>Z}YAy{#17Hdx2Lq9s-!P7H~4`A)`v zbU@*5gCCMuLeVD+d&^n6c>0;D9BmqID(yZZ)2R8T%4wjWzQTn9HeDkv!pyrA3ec`@3Z^P_m3(1SL z2P1W~Z)(GWG3+;rjqXJLca&!RU(V*PshW&@ZHF_Ax2yja3mi%tn*Y#%inhjE)jw-u z8bS-%wHnLLWlp4(MqQ+VhU(Pz3azSccLIM1!z}4J(+5VV4S8?+?5v=|{XGGEamnXS z0`+0V@V0%`g6a*;vcmDTBW?VYXQU+-b0k3XF+5x_fnBa~cNg=uiqfVt)JX-1v4A$R zn1t2SUYF&I#f*iOAagDgt`XtxvS-!4DYA0Rq-o0%c}>(W5yu5vnFe1sF~|#Zsh4aQ zMK>-XO(>7hzb7YFcA%9MLG=d_mHHE}XGG8qgnw|3ObU5I;cK=Vb#uxoZY|?a1jOIW z8Rt7iv{5k9Wk}*IW;V#{g7AsDV#12L1@il(8N^Y-S>%&s7y4|flDeoSfZj=OEA(X= znLARVIFmUQ5q>-!@1pM{;a<@sm*+qcaMgMrS3|k3xmi1kmJTcH2I&L*2Sh7#0c|o_ z!rEC~L_N(>6bR^_c+;2eU~LwR41d6_5MK73Ech3QbafJ&!E8%*)gjJ)wX8(CRCmyodXZ%FQgViKFOyUVyHK~md%q+^!4MX zO1oS)iP*CF#yMpWN>i+@XhMU*|EhMOqc~l-P~-wRxOM;;sQ5uNBZNE^B?9qCE~V?_ zhr|6?tK=l#G~N*W!Od0le~Qkry|K0n!(*GZ-A*yJZ98om+xFhcR$Oa3_A|C^+qP}% z&HE+4Ajz@rwXW+the1o5k2V~)pTJm6<88ln>xpDriew3;zm>)&(d?F9LM^k`Jhyrb zhiKZGH-Uf7*qk(4JOY!2GUOTPP%pk}J^apY!j*Ju(DcUbUEbP_gusq#;;W>m?M(;vMN;$XP`>PpG1$whszsx0GwbPdrXtja`?HEQ zKbmU$dc?UT&)z;(0_Ax3+9npGUuR{NkoBhBJ@*o?rzJD-tMIqY7Rr*z%mcj4s*zZ# z^+Da2D4H*lJnkxL(dG(?#MC0sp%uST(GdcLTbY-umY79%UOUd!fB&b7I>$ z4`CbUDX(08m>0v}Bs|C8AuMJr5$21YHSQ7zNKRJFliZW3vMl`$$H*hT$O zJIZ5}ZW>T%*}xnjkwOF(B&Dm4uz$!31)sUwXI91rCTvahe45&_LYo!k~ zk@4#l)3w^*7pRyK7218fk%Vd4f)?kJ5HDvXis96Z9u`+VLwGzNnQ!TUP zLG&o|FYa+B%Un(kV%trd>L2nPJcu%!KwvD%Di;?za0-DAbIfaZhsEN+0kvaBD!*VZq~Q`BuKiXS7znN|jO zDBfdsPow%e@)98vKKH%R&Lq3e$dWFjM)hptbkNbR50n7ruFmXwCyuf`w)6z=duvJ7 z5YbrssrdeqhgMdwUD07G^R%c<=nHroA!B~N<_AeSH&NE zx1If^JE2s=Lpx4oUKXxtofr39(rTX(+^VQBZ}wcEuD~`MV^qUyVc>}h!&S+7s@wQP z?qzi?v6k{%{g9GbFVf7QA1H0rX0rZdywfG{Ud2uV@}J#_YL+2|4wuqMZIW~u?Y-o$OvAX&UM#1x{*nhMYPp`ZdzCu=@{(AUUHB!#Mg7V_ z{M)ZBkuw8+0~1w`-A;o>?RV&-$d&z8GfEuDWr;sZ{CW3TTctUI7E*+aB}%RxEk7!W zD_*S}CjFCsLA6K`5wlejr%DM7)WvB&x{m}d0@a3%{5@i4^-#eBiI3PrG*lYG8Y(8s zaKt{zZn>qVO;(|JRa_w7r3y)(uf)`wV>YX^wBCUgTBYuvdjXK-@OZGfJ5@!>7rei! z8=@dVnOe<^7v9!H5uS=UnithSrJ>p_MHgh-bnNtc#X=xEW`SdF84;+_T+@$mpQ+oe z{{Z}A?>D3=+PE=>B*8P@MgxxFBH$UYrVk=F!-nb@$#4g?FIu|Y@Fwk@{3tXuMy}in zxdhJFBtg?W`s*^F3f)$gtLcushP}g7%-_##Fy5k1<%bwKO;ZK0jRUJ}qMsO4xIuCj z8=lrD?~e*%3X~&|Yk`~9YmqS?RoZhfq+P<;(t1u-#gew{;N9T(G#{qbaDUsk;Whk& zw!Kx8gfAWPgC_BPi!O~KOEFJ~2~v=ZI|6sAebDb71}z?0u6ad2-*Z^HiaEc#fLF+_ z?fgi6z>VnO<2`ww+kRDE5{9@Fu>P<_^9k(i;EjCsQgbYxJe`+XeA@jP0A! zrhmwHidt=G6m9i8W%woUb9JbG)UUN3I#;|_x!c)n2fMt@6QEE^mXZa7)^VGv!KN(_lNh&}Y$Q~gk zE6;Q0vp=fTyy;|`dOH6L4pP4mZYdAfY!{!%YtbsCE0S00c=GR22*6Nz`=>Z4J^kDw z9i(7XSt0u%JR#!C*NJ|zqZI~880oxHAvNHJs2H--WvA3EMP*)|CQrF0d4`s%Zj73# zGiYA;i+~5ZFK#sOGq_igChf0SBGgOoD#Zyxp136)mw*n))Q8t-ZAbDbsSjWSi`d`AyD71=~D1X_0E2@oQ9u+KfH$f2QT4 zT6awM5>ZLK`2n4JZmR(5$faEto@|e5@)C!%eySZL(Y72c0c4)dML9P4Qrn9pvr=T8 z5EZWaX)gBvp!sAR?Y>cmqD-;P@q`ZMeBvOpwB2hMe|V$BOr@~#;|4a50D3Zakv+~Z%BU^!LHyZZ)^PYYj~>4szAStmJ_SB1o#yid-l&}6@)};E zl?jWXE{Y554%9~Tp!9><7+wuip$-_RI(?00(4m3 z>N^E`q^@&~hQ8?*2&U*OS%J)pdN%tO*-LNb+Hj5f&3tBMvi^}Uso;)bl$f76#SkIo z#OE4#^6TLNhTSS3-%@CTHqw<3l>(Rej+dSQV7vuL!mA`P@Sixm{t7rsvZUfHD3^^Z zFoLJ$J2UR+M=O)!v-KSHxbPDF4b4$s)X)G7bDd$>4F2E+XmPSXj0o)<`E%k0-8jXg z`g+|q<(CQ;;7DW?L<7$>t{Ka~G_7lV3bqFxw0oU}~!nq*MFwOVAez;-3 z+bDe(l+OuN4TV3@N>t78S%RlJ7Cu}1QZo|1T%N4C4d2Kw)~<#xr2o%PF7 z!YhGJxXbq|$bhMCj*TH)%AT%hvD~3Dl+!GEO?Ao}=1a9jszv6?vIA<4>2lszO@%2o zeUH}FxHxW|_8)dLJXUuE8{;<=*oO{x>i}V-n$;yYwmzerQKYu~#$QytY)Pnjs9e!p zQl?a~?99AlYN9PCeXb_oIz4WNw!*wSJWv;5D)jRJGBLf|6>t)oz#1+)*X>J5lh5gV zgD+B4cU-IyDW|prWzNbQZ83QU)$Nw~=`{6)W{)_b=9z7BxQq6T#nmrI_sY1@Jp?$8 z{$MU_ZmEOGi|pGQq8rO?=kR~3Cs`km#*|nbO^#nV2Q2}NmQ;$lgncXet*M6pI5fs+ z6aVM!gIN^oTt=dMG=CT`ZPW1@@>nZCxZZHVa)_K>wb(L-`m)5|tY#QYawkrgQZ7mETM$tc+r# z@d(G1{l*y1FG@LqEfSuO-hd5~ya+8sTjW=~VdRy1mrFas0EW}v7%wnQ#9CtwyA)TA z-QbR^tiVcE9&2)I&ywt@$jEB+OQ!Zejf)&;m!%}yB$yJ*^@XG3?i zzeCqT`+yuDUuYKi+|>tC844&$Xp%oYT%Le`xrq!xip^f`CC;0F(&q zO}+;CfsE*8!(V-P=sv?6{Vksg!+paV*CxYNh)nL)&oS)46ZMeccE9|*E-DVq-@+9nm82544E=1pL`Wlk~^oNPWHoewHZYeJWT2aK@K zEWHyp#%;VFhmIlM(nYr)ZrG}0w_UB_>Cm>JWvRNwt%C{x-OZN4nX`cm`;p{mV1=zM zIshDRc@Vl7B%5P=PJ#Q45pELw2=o|!SNGkz_jQaexM6O^$xi1cRuQFr2?@#RZo^TP zsRvv3FvrC+n-e+Ah-w>OfCk>MJdiYbMw#9yS2UT2NBJwq_L?6Iv(*jI4KN*Cv32V3S#?mMXX z^JHh^wwjhGdLnX-dezCGDy&Cy!D}2U09Y<=h*7V{HP~>HjOsQkU&<^KTIR`SI!Z84 z<*&2uo2!%|DKe8@H9u~yae?|O1iN^w=fRDIsqtxfX)GXgO(y^^(L=Y_=aJz%M#cR zGS&SxdxIHOc#{xBOC`qR;Pd>I#xOlGs|MSoKb|rLb2FsG@le#TI-(KT0!S(Q(Wp{QT!WDG+?^LgkkG%70uZA2rJ{~|Y0-#9YDMV%rD z@M+{n&`vlN+2eH>YC~u)KcR6*Xx&6?nWe4Ljs;jkN-m;i^Q-(!sfRWO$h=GlC8K8t!x&TP?1yi=Xr0C zM0;}PCHRu9HTf_MTUW=Wz=@VK5jbeK*&cKQ$}+`!yBKz13tb@t1+`TDn|;5YTjoA% zV&j;?;e9zx7qXLjDWngnpSo95U&r6-1eq<rk}iy3pI-$39;=#(l2kwrZSH zooS1DS5|*E$Ar7}MEpqxs^{xy`G@ z>HY<_UfEgq3+8|78mD&S58eH$`Wb2DC8djcHc+<|EbNY>U(CAKxq_9Gy1XNm^I!bB zHX^@edS#1Ulp4CoUM-#N&$eU!qO<;`Iv}_ain?Aj{zqB;;KkElYgnzSTy6UP&k!hqZ*x3bRf`=;IyApT< zN_sl3^6mKt+cDwPtgtp;(T!B+mPZnEd~tKOtaZAFZKXmUy3Mjfb;W;|d5Y$@N1M?N zSmsPe7wC6YIK~EXRmte~@e*4;uJxAmOy+}@x$=aR$IXai>k@7suJWAjWNlT?4!vmJ zq}BR=Hn{`79*?jzeUS4(PqI^W>58vlx=o*&9V5Y z)|1-1)2CV_y62&9OdG+(fM8>&p5PgaG7Ots0uc{rYdPE+pfeRGJBau1^S0Xm0`g3W z?HV{fWw!MixFCL%WxhUlx{H~ke-bvxc-F8wpcErQC7w*jH~gmy5w^l$`LyP1uy4_4 z`*k=v549bDDVbH)R(Mv5)nbQF#1AzK;IGsDOa#Oy%nN&o6a@&-KBU+aMy4RiE@DRx zWO~_I`!vrSi%qWY|xHCm#wi{=}4=`Db`03%sE~86WDwc$;2xv$C zU=uv&z;n<_7X!2wIa!uv+hD6Ga<<;G-pjpVxob6LJTV`%I;G^8?pl_|-7$W!jGI2y zIKnIoOF?&;tO5TaRwLwj8cxAdUG_l~lu*2T;m7(%`DycaHG)~&=1K_DQ?0Xyk;@Yf z_1&cvMd$VgGv9`5y4txlL0#5xdig5yj!!m)GJy1nJW70)S4M&7ByjMkD7BlI=5>Ke|vaq`*x8!=y=P0>3d(6 zouTw~duJhOr#jV`#)DIfj?PYH%*!*(V0ZZl?Z(o?7O^zm2;x~_u)AUdi;Djpo( z+!ilo2HkO>HJH9#wh*nF46Mb#XaxE zZ!_iHdD8ThMV(67{)D*piwgf}x7H)d3*qyc_p4dKzP1D{&u^q<5D@MD$f(rUIt$SG zhBt+bp8bm0Tyl4+(ls-?bCqgb3fBHn?XY9Fu{7b)o-MGJ7QWFwS7#3{vqpeJ{3^{u z_2nK#Sf}B<^K0ZX^r|qSJ71fYo7s6sdm=Nuqh7~JQMWAuf)adNeSmAx0nLrzqVQw3 znRN!k4EI=%#vySoY4CQWw%~ZjV$3J!K|29+%6Q&- z3!9cw+2W5CB#g3e!|J1bZJ}6I_*2VDEIs&`X|`h~e~j%xH+mdLwxF>t2{0bHRUm3N zS=@81ZDr=G8FO3in3txwG$)(+@lR|I%n{K;tvu6(@ayK^CT{Rq(*Wafzdu-_ae&7g zq#PURLV?GiP4g-U)s@!nv816j%dN}Ed+Kk3_o#32Wa&+YD{&p;repiAXbj^{WLz%R z2-3I{Qc)3}_z zK}RCUS^dO2$X=W@`Y0NXcNM2)QiUEx{kgf~Un#J#zpOiSzx0gqwP%!alV(TX)2fYZ ztSz@Tj62Q9u0PG&p$%_5ClHJF6PAmn(()+2k^%Jx=vwKzLLz&k{A9{x{!-=I&^40P znh4Ko#YtWLjIi={@wJwtRmqa?4ujkz>37X|T&;YJ@B*Hrm_oIZ!j&cU9@LYn#)2EH z67}lj{XD7Wdgu!AE}i31ub2!x>FFyutRXd1%NJ;#A@{1*YU@>B>O!;*LTH0pmqU0)&a(Ux(^VC`cX_(0~|0&%cdzDOL-$u`bIScB4?eV0^qMahJe_q+f1{+M@3Guev9)&t_gc-2?)fBsLt1B0 zZ2&>u_MpI@dZ_tl@=n$+TT)oHFxRxf>!l1rKek8Ym>2WSWd$J%BlPvf=jUCMk1PK< z$C=Biemc`cnuwd*tE~Cnbgye!K`1q^eQfe|7QT5|m{K^(lI}f9hR4qLUZEyc&TmPe z_10`bS@f6nH`KAro%l+@7WPcy97+xM29;kI%74MQUEm?w!}U!%A>APCACjq@DShNI zP_s+1VDL?Gts+p`#aD>!zNndR-gdnO5w4dZc4_CaRsF+6HN!ls)S<-&yLY}H- zFQ-CqDeoQstoTThgCQ>yhq%h;EAM*btHU(=J67NZvvydPH~MmT23k`!Z?JqX@d^Jl z_X343M2WxX4v1~dSe8thn@8eh%C(7Wgb$R;kf}0IGs#1)O4HS~53YG5I$}<(PZfXD z2Q{paj+L!!0%R$ir=)l}o|s1MQLL&KG0rJ3=04;+Q0FAl1sgT3A?{MUuGC|*5(VzG znyX?}&y62yHmh5~0rhnnKk4E|mS!LOFM*&fB_QO#+P78L=^~vnSIyo9cqc~kcK};L z(j`~GR!?{35IwbJQ283@Io4anhF|tbcoarEw3t~MM8#L zKh_4QEO8?5F615}lcXEIdCpO+FnqUfEL~)!p_Galmebn()yphl;tlowW+|(xQEl4W z6hnlK&niDr(~WMqBbiSyuS9oVEE*TGM0_4`_xz+F!#EpOe6=$G$t(NO{#$ddDyHqE z=u_>zRwi?ELw(Cc{CZ^>EMxViU8ty(V4AAu$~*^_r*{hb*^lEZQ~m z46G^r)EBDptW4-Ni+D9(x@R&oaZu+0Jg4bsyQOjw`M*|uZVtn2zn>`KI$7x<*TiE@ zkzNzzr_kNj$%Vfch@i`*Y4b>G2bge9uJBn+`pnaeGxZl{sPH43{JYmwa>)}qy>inT zV_L5#nmN1dJ3>B-u9(+*MaUOnU2Wd1sLGSZzwGjw%fKp5ef?Xh3-<)RhMmu^AX=N2 z3nQtORSs$|<7Cb$|tXeVjQL|+)knEja&))96QK9C#7{ZVn8ZxS%Gw~9K%;&`>RR~8*)P%4zi-1(Yr z%~czdP{aHPpC$#eXRAL^267XHS82)o;S3!^C^*$fX8Vb5RrqjsO15UF3dhSw#HUD# zl)*u53aa|E`wI1D9m#UPu}ruFf|^Q2PgR$Rbjd)$4f1_yI^7|xlt~&^FiYjP%55AU zrBBv*{!Z1N_`zadO;pelxmxGr{!!fzxNTlp4P0CbjcZVqiJ9{Z`YccGJcBjvh>&3D3?3>AH>~rxr*bnq#+FnU znR9@xwXaP3P_5j^snDct;diuXU1CeP3Aw&RWv^Clwd2;8XPa( z2_N)~Ri1(qP^?nlwo$jLrlfVgY<7J}O9wZvQPfPJ^blmBl-c$+N?pG z31s7Tlw?%|w^4Vq3z8nkI)`{w#V zWL@il(!=z@%|Ei7*(%%G_yPPri#{0dNRlk~EKmlcdc>)G{#=Q+xXLygk_u~uGrKrM z+<_SlJy~^YNjEwVm0D@?b}(xgdtgg*{78P9ZBMX7vf1q9Nml&EN=;h+>&h?S zIl;A>ck+M2Ik*8lFVQMIfjVA%iU`+NNRy~prA@LKjC~n96)oJcF%MKr1#bgTEnWJ< z^%pQpg~R@F_TkC^i2JJXoa{D#0HKlVCm@i+DN(|`)W>z5Vj0uF0Ud(?H zvrIWdTpWOD+T|PF97azyjEb2(#80|$tlyOWQah)X=FI-Yeaq02efcKV;o8kYgbS98 z7qj?((jQ1)h}~lV1xxxpV2Qd{xzSCo3)H+t2GGPz56v0I0MZI}#bK(@m`vFi_33~&$}QTD?qfA8f$N4s z;%LPXm6`NTv04ODUMY#pbb5|z8eu21UG=qkGp9=Zph(MmpxK`GROGBZ6%!`)(H#r) zQ4R#BxPzJ?eLi>#zX^<0CKAqoMZyZwUr@$KqT0c=O}8Dc=4aJ|S>N@3h2OZF^@Oxp zLO1=&7*|QD{!<`D!8A0u|5oob90L|M?81I1#x{+_41ye@BNIh$pm?Jjn*wP&(E2Kn zc>{S@IES+v=}D6cDv;0^SMehFOklhG1zhV+T87A{HUiB9`J$#@_KCF3 zq?5LB`2VPCt8bMjV~=HAA)S5H?4HKuTZ}Jbf<%9?Q-Mq6BDC6rtNMkcYhTp8>mDQ1 zHUOP-c<=E49JiPT;^np@cnZbRN~wHFf84yIu!ud>o}8xOy|tFbB#R7YW#Ah5IO7Np zs%jM)t0mQW&I*@)$L;KEX6gso?t@G2UJh*v$ zOu8u8Ixp~m?2<{~0jMhj9T^81WW`Ja@NIYUxNszdw>Q9T+^oZ+`jw_SeNH50_tJG5K*kBC<3UEx@= zjr%|pK%Gx{CnhikH5`}NS+x}bvXNYm{A4-I-;n%SDHT17Qm6^iYkudoXOvrAyMRMl zCk>wSfKew|$BSXU=Un2W?AhdBg5O*#?uCfW=alm$VZz0E>!tU^>ylS1#>=v!_^L?7 z694|1o9d&k4|V@^h}xay!l#Qjuv-P4oKf6~!ZYMr-X(D=u1rx zR5C2Ps@xVOR(h#H|5(i+?IpMAx_aQg@)dofOe5Or_*ai&XRrq=`jggi2P=NoALD&g zz9<8PF{)p=KgC(<&&hSti`v*Ig(6i)@K>m-fk$pLwHNj2iX~LCE?;P;Pt%E6vCJvD zy~LC3A|R-KDA!?YEq%WJz0UQ z6NsrIq=Y%0u0uu=J}}R~H|rWWgW*l3G~Oy0&7CHk2$PcDNczJ`Q6kxT*xmoB${+gZ zPS?DJp302Gb2c&`CBL$&8D!dU%Q`|4gJphHdyBQw99}w{D>dPBz6gdG|4X_p4#o~g zDWw0<5B`6Y^N_3VCJl^?kiH@8>~P|JCB11oPJd1v(>lB9Bc0b$Q#*&bzB#1iKBw7s zBIiCo&Dx&yNMtkrj>4omlR998G9FX8+ciPRH>teoM(-;gM)K^*q@$G5t_@8KX*)VT z*ETYTwl|fmVt;N0b9V5yH=j?sB=WE=jIv7oEY<)&#TVmg_l@fJ=x%wohF_)OKhj*Q z&195nopG^EH?&MVTpOd^PFz^xrAwspvO9H07~c}M0t>li;j6(eVY<&v{Y9D1g=n~< z9xofE#BkxfQ>viGW_pEc3tSwWd*hhuT?8)y!qQ%KD|Ha7HHJbV~lCa1`hf zGku=v2P?+9bQ;1nK9WPSnZ$VRY`KUWPm5BdP>UPyDksr5SJx@;vc?p_symz)SrzJ= z{Py@?+Hld$aFI?gee63K^i{rgd90UfMPgWdkUo!Nmh5HbQ?sN8*!>%a$!>7_Rdvem z@ZJ~RRysQx?l)D%VpjY~^-bB-aILmU(d%0Vq^O^`Mu0nXhec&Ve_kTHPn5woQaZ$H z!NUera#JL)@|O9DzZN3$`O@8)^BuOPruc)ZO-f$)OiiP@#WU8x2qAIlkWxX zUf`nZX~3$l5qNPHYbeZJypfvCA*n4D*jZ~DM-xN#i@moNxr;(P)L0n|1}g<(IPwur4|&6 z??HJPhorlpns}l7EhG*~0`(;uZL@VLT@(CeR=k_=M67PsInkqan4T%lRMlUbBOBPA4H;r08|~NKYFt z0Hdg*s`CIM9V-EVwanK!ZJ-n9R%!%j<99_r*9VEdgi`fqWuD$FL!YYJr4&lizGZGu zAEjL)cW9y+^BTu!*0K~;v$aW_=HlDh{k-;^VLFQ7Z^~t$pEx=CEO1#iDpUuqQLOV` ztlzAe=J;hHKnSBpS;`$s+M>M1(>F*|m|$R4sJdRbtr*gHiEFbDXnspGQr2qs$p=K= za@@g_LRSIn)g|7K!6&*QE@$<(z()FFxrdlQ{475y;o}}DR!L`69#bBcy)2GVT~hdE z+te?V_LMHoN!5ku*V=0uQRp4rZS5PMU~oEc&vk-6Pj9Aekq%XHiSE)HsxP={vis_# zl?jRP@rf&3zxm;6HPj&U84r_J!De)!Cg2Elr$>y(FsBE`6 zJo&kz%7jF3S2x7WT9-e@^mE)x4S zuPqci2q(+4N@YGaS@Hq-aVt4`sdA6`Q`l5B-(>e4s?}lp+&I8!R7SR$e^ysCZZqrZ zCf6)8U2YgqdfDXNRFc2i*g_Iy5V7C1ltcq&W}b+=jE&_*1wBN!iz+-fp_TH3&e`Y) zO+D$Hu?#o8(Gz>yxV**>0|-f_By0rPH$NNQME#I48YMBwiAAUzr#bV4Do`8V~oX&N&~0m+E+gA5aJ_4!6MYkKtSO%y5n6T#{`##3{&&F`VEL z(t{1R1P>F|89s{>BYPlESxB%mL{hx*DuGsMY%W8gS3oOaAb7|@FS!S9;O?!$gIoEu z;@jYT;q=_QdLPlFwC8%B};H%N*;VgZh!0)L=}n(mwIJV3-IF zZ~+Xn^at=VjZAT*&Z1eTL@V>P6IJBm(c1Ou#@uvWlO{P$1B})tC*Xlr-L%MK;ADUv zyd0bXYP`qjYxJjG4(NXx9yV@NZP9(Iy{aAyBvq_eBf!F<*&2V)E$6l7I%rPI)UMPI zOo-Pt>Cwo&fSVyScr$R)u-!Wn+yqs-e9$YQ%ZaoTP3Emo4BR%rCwi-Jfd__mayu4Mwax~Vp0bGQ% zHAKrEH_xeI$ZhuL|E=z|xJGW*+%x?Pexm(j zyz0FbsKfBCyFnsaQWw-du6l3f)V9HO9mSVh?ljnPuQxAidXPc0&m#{{{Am-@?#H-V z@hoZBVas^lOaE`CFJcdmp~m@&b|)3KSo5WJX^R$DSh2I&(s-q~&E7%)a~Ie;$Y4gS z^#Bc*c+YZ{c_n6o`8juD*d^0hp>Mzx<2}h&k2q|f@~P80^o{mz?LgZHLRLkF&56`f z9Bxgcyv!}K@aUcCkIaWz&WZEP1GwSQFHA*((P3wdO!3NqNNkmSl!p*Kt)@GDM8kFW zYZ5JH>gw`^=0o(YMVrh6m`8J-n94X~(yhjmyx2sXF-CALdOx;QTpo5F{VWp%)Sv=o zna6VEg64InKlaG^|u@Dz= zkJ-22Nh;^GgRryOJ>eESQBxV+2Yt|j(_EqdbpHZALmaTo(*R}bZ@P?t@}N#n`o6&NhB*eB=TgH$ zDBUI6Z~%HzIaS|nFqVALiwzqJX6us-zp~l-u~2>*q8|h46OQOJq2197^#*vzv_kzF zm>d|PzYMo{?l+8s7rEpas^AS3>p(iTwWJTM#by`Of*#o7>}=o_HY-ix_yiM9fH7EE z^k%RV3z^0TU!$)Aar$J`;Q3s?1i9nFHVi}<6)^zU>RaLrC@d%Qp8!=BYt|be+7g-; z2V|S~C(HxpnWLloz~QEi)7YTQ_%%=tUNBDb3f5PluUro451|uE5A;5-2`wz@q16x1 zS<`j8ab$W!XD~sO#BAS3UJ$dPZ8#l{SlvQry9Vp+ME(-rmDXPIQ@1r{g|cw!ZsP;3 zq*UBpiR&oz?0k+7$(h*!5pJcIw@)QMO`^0urk#x0*1}{}N9?h`<<1YDZ<``K?t96i zl&*HWYqG1_roJ`$>B>tdc5EZm6g+Adkyhu3+9Ijr(nDL`(+?$OHa}ri$1Jk9kFnBaB963Zen8obRMBs=csY<#ZV>t2dMT85KDKn6w^Uu_xA+L(XW{+(mb zo@e{aBd1xcUj>B3W7bg7^ccJ)N}`UKYYvyK2)e@vYrI9-Wn4O9D+F|zB*v>XLUToz27Ljm37{z{Eydf~hx>7#b zhh)B_a&fCO9@Xxh`Uazb^4z4Z5v-)lWgQDS0jWRQr}0K5cD61Pc*as&D54>e?e^Oe zW*Em-Bij^6x6~--`1G1)X#(ArV0(dSPPwQ}&&xU3{)wNInclWWa4&UfYoiEGtZV)% z$&SskpO;>VY_-Yd$HD;X80EUac5|r4&F790)kV9HM^AuDolYX#4Wb-*>vhSd%%Lqi zq(4%@X0tpqF~gpwSR9*bi&5T)oNFDZt`D1QKBBo8c+50Hx7~LdrUh%~M8l0AsZ8zxNWqh#p0+v+3ssy7G>nt(g^H_#CQ4dDmG36Tq!~Piw zhI2vH*idMm?;hj=9N_*DUI@>3Zi9Zpk8^@-o={K5C2KzPCY5TL2ICWpOmE?nu}tGH z#3}NP(F>tW^T%qCr9nMt2=dhTFXE5f@fZP5N0vIvpzR1d`>o{*24*x{BCx*HspdfJ zP~u4AAM9~#oY56~6L|)!#2!v_LVK}GL5mOz_Me{zycCP}h=y*VkaHgdAg{W~4bi2Y zwnKQAinnlJ)3cgtWe_P7HhS-(gtTplUSAuQjC*7H}63f05@9Ez|7V({4z5LxKg#B^-HR$ z^XL3#?`R)A%ClFZmBL5@JX1V zL?k$+TUfqK8SWX?Cue2ouaHgxL2Iq;gv`HQ* z@>sy%{xC08z7$O^>`RjTvS!ISYOK=ShZ9yXuMl*(VHro zn}YP6*-I(U^sC|@v%>WIg4YP%Ih>F2GKqm^9h$M+lngD+ks9x+6AC0op-@)x346-O ztqj4ajpcPY=*fyS{4g{=dmi~4VoK=86v2;!UkVIxyyq-g40O@_Ee&iNWmujCwz{c^ zd23px2o4l;><{Rx%P-mXG(4*HuyQKA8-81+XI~^wG_6R;V(d01hPVkPqDs$W(sxLd znU*@jL2Gcz4C=utZ{>2k9tx_9ayz~0MP=vOvIA~L>nbx1|z}} z8IsT6XJmR_k#0aM%;QrA%+1vA&xo9@P=Yz~nSK0Ug-tUWXg^E8_rx~vs=?0H6&^Tk zJ2|JEc(H|(aFKr8))NBqO%5u^0BJiG*)okduJj1zLRwTgS~rj~xrQd5L7RY^!raaX z!uR1PvUZYoR;=eb(~#_$0x~-;-bZ|z&ka1Rz)7~a%~$_XPPW61BWsQz^YM@ByEHoq zdm9@>FxihFW1OS5lVy$N3^>)!EntS7VNi;5+ z*de`I=0+`*S7jPlW0f(n&v>xvUf^Ykx7Np9rC0|97>5-1$wInBS=gIu-tSI{6a9iY3vRYZeZ&}9WP0WaO2 z;=_PiwxQe$IM2aa@`et064F7GKm77%XmOvsh<+NlhdrP3n~$v)}QtO z)f_4jEqE4QJFVujD`crq=hFO3ISvytrOgv~@@D7$MFi@|-5S zgMK%jr9Lkk3Hs90E7RmEhPcMgUB+_8MNzcu8~BBFJ-pGR?Il|Uo-|`drg#K9Ee4jk z@D%|;Du2mE*8^ILvL34^4X#XP&7k_EU2E7- zGn#8wU8v*pK8dd4ehSFU`S@SLPsAa_8)9blDQcb6tBA~4C)<(M!TF&$7`;|FSk)Jx zcMwHJx?NT!0xFIS41D^<(ab{zY%%QJ@Qfxsp<7g-42V7_>?^wh*%& zmn|>3VjIYxR#9Qipg}c778;&_8)WXT+}{M7{wo|sUSYhP=FPZ+U5b9pU57pi6o{`Q zJ3Sf{8{t=4S;4@Lx3Y=FlJ?EKwPiosP?~S`Fh_rWLfx(Ao0WDvXs;_AL^^E!lUBh9 zu;j$JaD7el1C3%GruV2)u#wlA*ZG6{MoXKE&|V=grfhWg73#q%@6O+ihid<%@2EsYBS?n}GQ@{y9VvEMGP@{hj>EE!_%Ssxl8-J|bT5>S+amo)%_6xk zGoikWKb|$aaUyLLr;HHMxQqLX>|Sv}FrM~b{#wyw=8u#>$z7gb6jQ!Qc+ZcgZj`Nc z9j41xozWhkOu)xW&r?qjl-#>?6X_h~3$uf&ZaBm?(SKG9;=X77%pc`&q90E_AZ7@w zqq1d6iN&u+)u`CuO47>}wCIJ+ov#xL?K+Ie;m?hPY#y&ut%g2#NQwjus zaU*G`MV7Kz%*zr&?g!2;*~H{Y0)-+!YK-`&s=)89f~k4$Hc9;k$Wm^oFA(1p;Trx& z+F1s*@dfT0cXx+`1h)XeEfCxxxI=IaNg%|9;83(KXsOWRZE0zXx72Z|p)FOsg&KeE zr+a7ao%wyZXJ%)1XZGXn*`0Hq_jxa(1``*<)wAzM!K0+n%RwPA3z%O0<{W# z(nq`~EREtXSa>l$G!Rs<9bp#ISYQ{>75<6Y;PEQ@L;e@OurPncJ z!C$kF=;@lYUt%087UpcyJF_o%o~#p1J>@e{!$j8kf2!sWzZyiVObT!a z{amr(L5u>IYr`+Z0ZLme7L$O*osctW9fcEW%Gt5Zz~g_~K}Ie%F+<<$Y5KKHJ>Q}D zkD31vn-LLNzk;a&mry^#<~(B2o>A`{hA>y++RR?(G$bYH4dXh}8i9R;uxt%EArdKP z8-0*6is(vwVWTNtb-}CCQV{(^>5_u$)dE8>m_2jql)p41zS&0$xh*16Hki;^- zo>cAR%dVf(lhZU|^O#D_o8W=p&f<=4O{z&+kF7}F zjA=!lOHBx&CVWZ<`iUoVW{kSVrIu&ihGElxWfz+kp=2=2dPodUE}v>dZcpCIaTxhL zF*IX0;&Ena5^vPoENt{)EEq)z-a_8Z9`LPAltX`W`JMa;>kZRLE6+J=nw+_YbJxS7 z+4J73UeDPk?8?vJg-OHd^I=@MritPap1EhD!BLNJiov$AwYcZLEb;nzXqTcSN4&A! zTq+p<&D1^P9^s2#S+*c?3B;abLsnJ@%d4hXrM(V*Mb1c24}+0iqkJqQ}XB zKJ>U^GTKEiVV->6u0DC2JZb8XK1$KiyM}V4l!KhG?NoM!?mR7OUg}ZcYv$+pkdSPq zU1UqRQhrB}OcWqr*9RPPz!-4ej>j=P?HEa8^k1gFX^Zp*y%$*}^Z-ygR)e;p@Dg`y zpiHF%pv$t5E5VwjVUe)V_a%veQxV^aQ@szPr;5s)=aHDgN;_)eM!}G2R+=7jSno#` zTmDNB6EngfDm=%f(`l)y2)AlZWNDCM<=Keckk2Pv15ZVWmA~_T7A;tI#`$*KlTvlN zjKsj=FQz%E{Y4@A!kO0!W*ecDM3!`n5Uj)nVyA_KAW0j7c2oV?(E z@2FhyaABv--2G@-TQ=NA+$Sgx-Y4m@_BvrKZ3m!6I?fKrk|=t)xv8EgIN~)jFdG)+ zAK{GF4A~E$Vw59zyhxa%s9#PxIht{`Hi^063BQdm=kcamXdiPQnQ{PQ;w(l__7<6m zt4NVd{~S6Qr=O`3z7?*W6%=KJNJBNmyz|V>euT_$bjMgGmRUc*cBK%EU30Hy=xI0Q zoj}zAkc6)}f^wpy@x0Zf?UcqC^;m;6-q@`$hx9_^oPSj&AW_<*HS72@1wWtdoH}O> zL;uNeG8WA-M@4D3;zBSsfQ$G89H(3giJJgRoKHNF*cgLI1||!Io=aItIqlDr_B<`c zLpvis0|YnAVjd?S|7B-ogN}3h>zI1&p5i~O_)PI$uNjMk-*F} z4i!uyW`+A*OzA)kxKE|sKnpu;XZ*mNwwgdm0|sttU4AKbsNcx{S^|PpqA6xLUaVM z7DNWH1Xn|5k#8oLQe2Sx(SpRl$hBAjVqoxPq&X4m%S`Ac-gWzt%tzvI@JgK~#aSg} zq>x@1eMeQ2({;2kNfdtIliUN!xcnY|n2JJbMyfGTk)UWt`fkusEP-C>%ZEIo!`vDZ zIrH4KXxgTZpXQ55q%CwcHN9gd_c>l8)Uu2@k6>L<(J*UJR|D;`8y75SFaEBsG6N)T88S4|6myb;OAa6On$>W)(Z0Ic}Dj ztBP7M$i}_JP&JkDw46hgOkxopDrZ4fB7TkNPy3SA7wnXA?B4J@E+);ibAN|Y$$IAa zF#BS*rA<4=3%zL;fStt_8|3HS%e|n9$fMhSM1$v7s_79foOK{}M%Bd$}D z!qt<)@%(|y$>Vre--y&$e2d$!bX$U|qi7}%;k*q5r9(6^<3Vc@UmGy7C8QC}bGbLk zmjF)q07|302{DO^3u7jrsXc)%iGQh7pM~TLRHWOvR5CRbKAG-M4X_c&Y@)`R9-tPf z;4)H$X#PAiZC{l5mb582U2qb!kdKP5hOTIv=CN ztm0`m`6WUWLn>5& z{=i2afu%S3^Lq`@LjnOVsdSEzR{Jj6aQGj~kF=H;KIkc0GjdLMkk+5vsMbPT&rnuM zpo7tWWiHX4f>&TlKH`E?d%Cr5H#;Ax~VOcHe0sco&R$gD!vR_2r@0cH+ym&99 ziql8@V8RKQE5SBt)?$pXk$S=SEwLuUTDOXni8`&eM0UsARpy|C;l_{GNX>}KfsC9F z@i%>2b3GHW9?aa?WDh4gt}Hd!Za2?0-P)oEub)|FJV@X{JsZ1@vKHsZ3uE%xv0s4?gVKj7%r>oZ2i!ySCg4RFg$8t`m(nZqK`owbH$Z z-^^vGyAtK{&MBWFogv!F36Q7AaRCCT9@HP7;Tr^paQjVZzUcm`@Z)R2CYTT7kRe2Cc zboO}Oh8-BghA%b$i!CPv8&h-Hi4fhFxVxlK^=dqvj8qXM>Qd_Ds!8oshX3#MF*3qC zCu5w9a=V{7Nxtl8h~g)&*|B7MP$bR2p^qpL#x!g@<$>;p+)k>Sde1Q#byvlZaEYcO z*G;mgW%yrAi(*WA1JX&1OK!M~GDe{zZ{`z5yzLfBl3{7SmHmMsYFv%E&*0SK%h{zL zs;}ZU=u;~31T#8GZiToA?thkoD#FRAjWb|)8q_OEt2UknWFhshLq zhx%D@7dA(SiGJfO{ylV?P19;v3 z6siS1c7he02)$}I$2^MoVmZsKjs62YU}_-y3_9{hlgzbD@?F!egNzv~Sqq9PjNBZ3 z84$w~pX{}gKN_;@M$GpQ&v9I5e25aYD`S+!{I#rNgd*=iM;N+ELIyPq_EcjnbNW~& z6y!%gpS`UZOef^F%OukAgiJ39+J2Oe>k{pJOsylD<{P(W2cdxzGA-?Cz@%|#8BH(s zh5?RdmXW39Kr=(_gK#uAEJU$}hRuV^w9>kWWKS204RYMon!=Yb3g0JxO&YU(N#0M{ zvDl}8)4oE(DM^_T21%4ls6MSQ$}7wRP#aY!H&1bqnumWcvqk+%D)Z5wQX)PEtU%f! zDk)LO_sLqa*C`~*ZTFen1MG?mE6z9Pmcu5lFZZ17F>!*cu}ICE%S(hx;5+b{21o*h zz|`s_h7u3JjwD4gRH==uM5&RTKK3fqxku;d5{^CaISoXJ!jb^C=`q%Jwbut=Ja0}}g^ z=5I5e<4voyh{@TZwL_se9@>;aYaWCypsj!}q5Fb+2m|y8rC%gdx|Qq}Ih-!(b{0L! zv~XI)4m!|1eQYaH)S}oXN$Kk{B`s zS$rYhUFSnlN78Hcyu#e{SfFb`Eb6TM0n;Gotu#762|w=)FU5uIJ5-fah1c4472l46 zS#lJ8jkPpk76rw#K!OV|C#C7E6>O%qsTVP~GM@rdm}2N!1)Y2?oSk$Vqn_}@=~7X9 zl(2(n;YJL`*0<0oZr&!8js73W| z`X?+uaFCvoyP(iU=O zp2VixXp)C>3d~o@eYrQFPsvlbR)`WsI&WE5n&M4R*RZ4{4&RD@bB_i?DE#JpPpRZ;~h>%6x&uP1J_IC8-miLmWw^q&i)H(hqW~Mj6?aLQ#Ew zY}avAd`S^KeyW`*=V+;L8^R58CrsqHn@rn!m@rJaWj;i>OSOP56PBoTkZ58!^_Ok| z@gproW090e+XP9IcIhgLJLGPvdBPTJWWYH88`Z-wV$$!3THoA3*h(L?0 zHP?e$Ot4j7!orVj38csg-L{JPI9AQka(KcTSh3VGbz0?QF)=GcZu6J}QIc9L5W@Sx zq-ui$kk*f@-v=Ws2vy!;K_=-Zh9Y|nlPU^gUh58(%f;W(Tr2HO4hFjxe@Nd}c~s<@ ztuGHKAmv6&b1_{AdUn^UGD7yPnUzZ6trkHQ!%{T`jeqzMs{g^0RhqPrro+x2wSWz1}W35`A8RKoiUFH-wXaXozNk}t< zmDne(=nfXcQ-2+|z}sXTg3$$&*+T#UW?hbqd{KT7UQ!yvXdrRec9$N;4O_L9vLtYt zpDAHWGJ_tc$Wtl}d5gT#+H`Lg(lUcJ{}eQ#euAr*(O6diEZ-TYE4^Lr8PiL6iR1Yg?uQWXQ6ekGuN`aw1k=ZnD5~Je97D~Krure zZ>-=0=6cFoEfTCE(NKXgXS>iC@KhA$dpC1KtAVR#$@RZ=3C@gYnd?a z-~_-w>C^Zqz*{;SF-T#67Dld+`A*ZOD%pzVFQZkhtn#xkiRR9X4eV9u1qLGLm!Sat z04JxrMeoU@YGu=r_%CX3+5_T4pgs*iwo(+Lc2VYJ4XCZuFE-!lGdP45h@PM4Y;JdK z0kVa*(JBZqLmiquQ9@6Z1|$h<_0!nMLTZ<(4HO?>A=Qm)rf5P{r%B2xQ9WsOHaj#E z;%6%r>R-}1b13yRIShK83Z%#znp2i3ZF(@uYpR>pKIIMdquO6e7p)#RM>$VBRP>_^ z(}6NSsd99ATXrf3^^TP!Oey8+FkXwt!kg5(2wt{#ZON*~kuN)cy>sf$qf z8PUMM6lI2wB9Ve+u*k|%KG7RkSdNbV_mQ4}F=RO&>>L0V7S{iD_J553$F&Fx3)}G> zA}lH_1}t_gJ}l8JSu8Y`DwYP8PL@HI36^D+ZB|xRQC0vegcZi>%X%E)Vx_ZIvo^AJ zu@13LvaYc1u(7d;u>si(+3eZ;*y7mGYz(#k-!+*GI0O+}zyK+#1|w+%DX~+)3Ox?jr8f+*i2oa6jgr=icBx;Njts<v@xSH&#{XA9P(V>YSHN1pQy@YhU4SG|E^tBMhQNJ+7Xt4Dz6<;l z6cSVt)DyH3^b(8|%n&3CRtR1cyearV@TK5;!A-#k9A$=iRA#b55p-dr)&*wwPMX;Jz^tb(_(94d*U4865=3nV{y1RLL4cM6=#aq ziMNRNijRuVh_8$9OK?g^N`NJx5{?o95(yGH5(N?`B`!Ly}8UN>WYI zMAAtzNHS3}SF%v@lw_;qZOKQHbCMq=e@bynNlU3qnMyfJ1xqDK;iQVBPD@>px+C>i zYF=tX>Oh)DT1Hw!+DzJ2Iz&2II#0S-`i%5d=|1Uk=>_Re(uXpz6T{cWMRhA%IDtk`$y6ipKr?RhQzsUZU zdeL(NRhMJ-q@SuIbkSnZ73Rkc2~akT}tPilwiyy~**n(F52 zuIeG`De8Fj67{p{*VON-KT%&)|E&H?gHJs*6UFV_BOP%*Rn>t6jBDyNN2D)~-KDyDmS-Mo+O5J+h z4&4FWSGr5OTY9W|qIv*5h#pMOS1(2nrAO1N(reJ`)Em^B&|B8q(Pz^a(+BDs>f7u4 z>Bs74>(lkC^&9oO^oR5(^;h(F4cHCD4O9(`3>*yn4dM*Y1`LB5gC>J+gJFXygEfOa z2nR$00)iMr;1C1^3Bf?}A+?ZZNDpKLG6PwM>>F|#N*aOCtl;-E#)GtjHhKIk}f0s0Ag zXu@kEYocjlZsKYZVv=lOV6I@U zV{T>cVIFRtZcZ{UH@{$h!~DMabMv?6-^~A72wEsw=vr7?cv?hSWLS_bDl9Hq+_ZRL z@xtPr#dnK;mO_?FmU@;pmfn_8mYJ3m%M+HDEZZ#~TE4V=Z@FoCWF>5+Y^85yXXRrR zZIxw3wW_qLx9YGOuzF>+WVL0@Vl85=Vhyo|S^HYYSfi|I)>YOG)}7Xa))Ust*4s9$ zHlj8_8$%m=8$X*^n`|4pO|?y0K3LQ>4v^v~&c;qneu;Fk3=Yh+>HQ;7&7kDr{366so!B4}l z!0*7v;S2Cj@IyylM_ETrM{`G4#}LP4$2`Yk$1{#s9q&3maa?r#?D)%x&q>Zn%gMsY z%_-C=#R>0J;&j&Oy3;+UV~3N|7pLFO{Lb>u+Rm2F?#^M(sm=uFQs?u|ZO;A9&z#>l ze|7%jBH*InqT^!a;^7kRlIB8mDR;Txa>M1m%X62vF5g`Kx(d1~y6U=GyL!4txTd?3 zTq|5Jy54ks;QGS#o$Ghke{Mo!=zU02;!Qvs}q2giSVdvpZ;W@ocdd7`caQgo_q6w#_nr@j zkAx4{2kPVK6W|l?gY{wh)cLgd^!kkY%=oPP?E7;1O8Kh!n)o{T2KpxW=J*!)p7g!! zd&_ssch>iV?+-sNKWRU8KT|(vzaYOvzg)jUzf*p#ez*M|`OW!#^!w@0<1gc{;cw>e z;vejv;+oS=_&poE}UHE)TvCd^7k#@QdJg!QX@bg$RWxh3JLYgm{HShGc}0Ln=Zpg|vq} z40##yK4dfGC{#F9IaEK?Hq<*bDl{{c5_%%EKC~lrAoNw}Qs`C~OPENQN|-^IU6@Z; zbXZmxHLNPEA*?fOFl-`hIcz(eHC!|t5Dp24h5Lrbgrmag;nm@d;a%ZF;gjJj;X4s* z5n>U*2*U{b2)~Hf2y_G^q9&p#qB~+ZVk%-aVmFdKQan;M(kRj)(mxUziHXdQtc`4r z?1>zSoQ_7Ffl86FD86OiD0a5W$$Aa*vx~P_@-l);2nW*)s{bt#)ZTs$K}Np z$DN708rK&$9=8zpDee%-iH83B-i5g!2h)3H=Gr z65b?yOZb~8n5dYjn`oWrnHZ6no=8e8PrQ(LBk_LX^TcYEyqib|!WR;4zi zcBKxbPNuG;?xeA$iKPM44Abn>{L*66veW2k)oD#>-D$&VQ)#PdyXoxd;_0gCM(Gae z{^@b)=yXPUZF+NhPx?suboyHQUIs^oL3B#mf2*oeh$1^7)Cq0LhQ=W4n=SI%`oaZ@jbH3&L%@xX3%GJxY z$@R*O%+1Ip=T_ui%)OcWAooS?yWH=&M>t`eGEN_7i}S`s;WBX)+zH$zTs!U|?j`O$ zZYz%^Pb5zz&mhk(&nGWBFDs9lSD9Cz*O51n_bP8WZyV2w7sUhc5IhX;i;uyh@HBiC zz5(BfAH+}MSMWOoHi8%dNH8SW6Z{CVglqzxP)%qgbPBK7+MSq zh8rV{k;))2N*U)E*BSR1PmgV@Ul_mh`Sa!Twev0WJ@Uiz)AEV=W%=jx+w%MKpXI;F z|C;}YDZo@<>M*UCp3DelI+MgKXI^05VBTjwXTD{AWBx4=EKn@aEwCx@Du^t|C?FS9 z6kII0S@59XMZvp*?*;z~g$k7l^$Tqay$hoXGYct&CkihWwiiAud|7zx$t^r85-w6H zGAObu@+pcg$||B3RTkA3brcO0y((HN+A3x#7A*!8LyBR=zQr-csA5`iRdGXcXYpY1 zMDcR*b_rXFSP8Jiu*AN^uOzl4yM$g+UD8<6RWejES+Y{HTgqN4UaDGZRO(RbUm916 zE@hO~ls1)imkyUsm9CZUm2s3wl!3~O%iv{*GGrO1EWfO_thubGY@}?aY`tv1oU>fA z99#}9cPtMmk1xlTGt2ABTgrRON6Tl+Ka~Hd;Hr?SP^&PhaH51k?ShzF4o8yPAZ+$J85&$>txi)%#)OpCr(~E z*?#ij$(JYJpWHlobV~S?@+tjOwx@hfMW4z#MLkt{s{T~Rsex0kPA#3Uzc`YhvY&Do~2-Dii-PMuvnyL*oPoWwcMIpcHi zbBJ@ubC`4a=W5S2pX)g{a&G$E+PS^+oaZIagU>_HJDv|XAAcTuo_W6Re9QUX^P}fy z&aa>Uae?cC)CIK*CKsG81YStEkaMBn!pRGlFWkB?c479y#|u9%a$l6bsD9D(qVvU| zi-{L=FBV=rb+Ps0?Te2t&RyKNcyNj5lFTKIOJl^~LpP>aW)K)jz3Utp8m9tAVdUu0gB8qQR{pv>~Md z-%!$Uw&7aCy@sa^uN%HJ{BGoLlyB5-v}|;53~NknBs7*bo@;Dt>~DP5_@?n|GD5o%Ft(QC13@oI@|$!MXpoM^e!(%$m0tJmd%!<%fgqHFY8~n zz3hEC>T=d)>gCGI^_M#?4_tnAdFk?2D@&_Lt4gaut6i&4Yji8BmDXC-+R)nBI@mhV zy4<>bh4qT)6~Gn971$NuE3sFyuh6elUunG3b!F(vHN0wn)&FYT zRrFQH)takKSG%tcU!A(TdUf|2`!(@vs@IIJ!LK2%A+KSs~-e#y6Y|1d#{gPpSiw%eZP&fO|ng`&7{q#EwC-2EvK!Z z?PS~Kwp(puZL@73+J4;Nx*>f-{f6lc=Nmyc5^v<*D7~!x8>rCw=be49W>%881uk&f=o6fJDf4T&^6uNY}thzk9!n@MCh+Sn}=eydv`n#TY zz3uwe^|xEFTd`ZW+q&DcJEA+io77$2eWCkC_k->i-S4`;cmL}V>QU;^>#^za>WS>h z=ppx1^jz#|?|InsvgduzX3tTtaIbQ&ey?q>cW+d0W-q1pL~ng>NAE!ItKOyFty?U& zL~g0vGPq@T%jZ_~t*l$rTUECjZgt)oyftxa`PTMr*4v`D0k@OsYVI`M>Ao|3XX?)Co!vh6KJh-) zKBGQ|KL5VBK1^SJUu|D=Ur*mi-*n$v-`-u0yApRnca87D?;`HT-^Jc#-mSaaa<}*H z=-rvS>v#9>ao&@>2fhcr=XfvhUc$Ycdj- z-`}`@@POxm%md8_<_}ySggi)okoTbY!I=kFAM`yKf3Wc2(}Tl@ybt9bYCW`g==L!5 zVah}N!;*(*A6|QS_u-R=iw{3P{58NoAU~izU^(DE5H^rHKo}?;I5%*8;NHN~f!70H z27V6;3@Qxj3|b9(42BP;4H5^-2G0++4fYQ{8+{w?vVA6=TO8@`VeWT zeCWc^jiLKP&xhU)eINQaEHtb%tT${k>@^%YoN*kzt{A>Jd~^80@QdO1!<)lLBf=xf zBl;t@Bi zj!uj&k8Y2#j){%|#vo&`G2gM6G1M4stZJ-btZQs&Y;tU6Z08Z%Be6%oM~08=ANf6s zeU$x({;2v<)1&T3!;hvOtv=d)%>G#XvFc-^#}1GEAICjLKW03xecb%G=kdtn>Bno2 z_r^KKCB{MH#^dmD#5i&sGoC+QH{LSdJ3cx-Grm5)|Ah02b$S~3G~sFP)552xp0+-{{q)h(xu+kW{(Q#$ zO!}GnGt+0z&w`#MJ;OaKdUpERm1lRJJ$^R-Y~$I%bDrli&o!Q#J$HE?@;v!@-t*$; zXP#eu-uHa``NH#0&ktYlzL0&P`NI5#+l$Z_DKGFZN?x3OaqY$37f)U+zWDs&*Gs;a zaxb-BTE29D8TK;uCE;c1%X2TUzr6SI>C4wIzr6hYivN}TE1g$XuRLCbze;;Wd{y@9 z{HwNC{jZ+Adh_b*t3MM06N(eM6V?-+6A=^X6Qqgqi3<}qChku>pLjd*ZQ}2w;H1)| z-lWZ>*JR{m#w2;NV)EkT&B+IoFDBnjexLj|B|N1(r9Wjm~MD(^=Eh>B{N)>5l1v=~vTB)7vwwGomwq8ORK5#&;%W z1~o&QshVk+>6{synV4Cb*_maV6`KXl8qV6!`pw49X3x@Rt7jW$yJm-Gr)F1YcjwsW z#OGA!jOHBX{O984&~uErnz^RA?zxe<>AAJJy?Ks#iFwex@jQGUF^`&d&)3|qrC+PRHht~)h9cuTQ_e^7_u}$FJvK zZ@fNu!}CVwjm8_ZH!g32-z2@ky(xZk=FQbNeQ(C!EWG*j=I|}=TiLgoZ_VGjz72Vs z{1*SV}`?UAO_hs+Tzi)fr|NhzgH}Ai`|Fa~pq_Cv3WVPhE6tR@P zL|Q6ey0CO(>HgC5rMFApmi{gaE-NnUF54`7Ek`bAER&ZjmM<>fTz;_pV)@p zLMuuu`YX08-YZcnnJbi)6DyZi+E*T~yj*#|vbl1!D!i(^YOrdz>a!ZXnzc$@tz4~N z?N}XHeYLu@y0yl#Cb9-tgRH^UeAi;uP;0ccsaa(!ie=L7o(@eisWj6OJg@c$6^0sVpTq2@!=hwcxiRY0Yw~eOsrc)euh+ib{rcqV;@8h#e|_Wo zCihM2o5eS`Z=v5(zTv->d^`8;`nP-Eo_>4%?aQ~{-}%4Gf7kwQ`Q80{*!R@$gzshF z&wp?G-v9mC_c!0ae*d#6u&J=AvuU;Iu^GOZwn^G7-@LGSWApyz^Ub%L-!}hl32rHF z>26tXd2U5)Wo(hRDz+|e-Q0Sx^tO6)_Ta<8&qMA*=|lBH(?jROpu@z&+{41dQ-`gGw+|m3 z&K+(X9{l3@CG$(;m)S3uU%|hUe&K!<{W|^Y%C9@W9{*bS_378)Z{FXszcqiG|91Ty z@;mu=-tXeyXMSJ(-S_*+@5SGrfB*W!_ebuJ)*p*MZhu1mr2N7EDfx5u&$T~y|2+Nk z`p=g?zyI?8mH(^#*YdCX->|=_e+hp}|DOAM{cr!@XMf-P{rdOMKY@P=|8)LY{qy)2 z{x9tx@n6}$^Z#!AyZ`U`zqkLs{rh_)c%*owdt`m&c@%M!endJdKe~8y^XS3Ri=%f( z-;e$s{m1yf_W!9Yl`Qov9V`PZuUM8?wpdwMMOal>4Os11eORMevskIDm8|uw9jpVa zuUMB@x7b+NMA%f=4A|`0eAuGdve>9>m2CBF9c%+^uh^E@w%A$NMc7r?4cP72eb}Sf zv)HNZmF)HG9qa?_uh^H^w>VfhL^xD93^?pKd^n;xvN)(5l^pdP9UKE3uQ--Cwm4Zh zML1PB4LI#MeK?~zvpA`om7MjQ9h?K4uQ-=Dx42liM7UJA47lvLe7K^yvbd;Rm0a~) z9b5xkueg@DwzyfiMYvVC4Y=*NeYm5!v$(0;mE85*9oz%lueg`Ew|H21M0iwq40!B# ze0ZXHvUsRGl|1!49Xta(uXvVtws={1MR-+sA-phNU)~sA6fcdpinoEclXsAJf_IsB zn~#-Gln=lM;e+w{^2P9>_-K4pd<}e^e1m)we9L^>{H*+<`~ZFkKaAg(KZYO0PvfuR zZ{Y9bALO6lU*_KyU=1t$cT1-FG*g+zq_LJ%RCkgrgT5K4$9R3+3P)G0J5G$FJs zv@OgkEGi5Th6uxieT8F$QNlFgD&dCzAOIRfIz(EAPJF#N%~60NTMWZl2wuolAV%+k`t24lG{?OQle4-DTowI%2z5z z3MEC8s*-Au>XaIknvhzS+LmUO7L^7_L!@ESzS1$$C~2B>m2`u2r}Uuog!HoXwhXI` zs0=^`A_J50m5Gr-$y?WR_*NWm#oKWdX7fS(vP^Y>X^QmL^*z+aTL1 zJ19FLyDYmc$0{c(2atov!Q_19V&qVAG`T9d2DwhTLAeRJWw~v6R(Vl*fILJVChsdB zBcCl#m#>y@l<$%slAn}ck>62ZQxH=CDi|u*EBGnIDr74hmyjzoDs(9fDNHJ?DC{V* zDT*lq6%7^b75x-r6|)uTiq(pZid~9Bij#^fiaSbdN@7YtB|{~9B|oKDrEDd-QngZ} zQkT+@(xlRg(vC8lvY0YZ*-+VD*-trEIa`^oT&>)w+@(D99}K{d%B0GQ$_{`HAO-*e z3<354KR_%X8$btC0~!HcfFZynU9%*I0;+< z?x?bld3DKJ0LcY7zhY51lfc9K(U}~5FJzv zY6NwGhCq{`70?ct4J-x*f(^m;U_WpyI2%j{SA!eDUEm?`BzOh9qsFEtrUq0qRI^v} zQ;Sv0R->y`t2L^1sST-3s;#K)sI#eysRPvw)$P^&)MM4N)#>Wh>W%7M>O<<2>MQCy z8f+S38bA$04SNkgjaZFr4Z23PMx#cT#*oIO#)`&{CYz?1CQ#E*(_Yh0GgdQOldf5< z*{Ip2IixwMxuUtF#ik{u1=KRsve)v{iq*>2qH9%aHEMNf4QWkkt!V9NvuTTI1GNpc z?X~^1W3{uj>DtxWjoMw>L)w$tE806cY&v2(KpjIJdmTTWSeo>2>Q3>rLsc>h0>Y>x=8F>Ko}h==7(@-`ZfAZ`rZ1&`cwL=|3Lw)8tg*Y zA>t5Kh!MmA;tz>~pdk!M4WtRu4H|pF~ z9A}I+W*FBPHyL*u4;xPzuNv<{*`eZ4Rj3iv0qPHpgQB4fXbrRp+6^6sPC-|pyC&== z;wGvlMkWp>{w8rIXcLA>jY*S9x5=={l*y{et|_~zxT&hCk*R~JziFH)+LU2hW7=fe zZ8~f^Wx8s*YsPLSZl-ExWaePzZx&~UHe;C8m^GPon+=;ynXQ`bnzNgWo2!}|nLC*K zo5z`>%^Bu3=1u0^=ELSw=Bwtr7VH+{7OECT77iBv7I7A63x-9FMUzFh#jwSc#j3@w zCA+1#rK+WorGurvWt=72l3`h6*<{&mIczy)xoWv<#cm~TrD|nllFty=9`vs;T>t6CdbJ6QW$$62GT8P+w{P1fDk!`4&QtJb?V>^9;ysy0S8 z4mSQaaW-fhhE0u4lTEkHu+5ass?Dw~`~N2gaBRATfndfkI1B+p!Z5IWSS_p>)&m=X zO~ck;d-fdm680c_V|%zg!X9alvCp@!wQsiXu^+LYwqLW~bKr20Z~!?NJHQZua5w^vgk#|O@LG5?yazr4pN6l&_Z&GKB^*JH z#*T1Dgd@@s)7nr<2d3t?YQQ+=fvS8;RJFrc7i)0oRG&AjrmTsPR&j|P9sj! zPHRqk&K%AX&LC%FXSg%M8R?91&UdbLZg%c*9&w&_UUS}a;c$^~0l65vz+Dh7NEeJt zzDuo3vrCW5h|9Fgn#-OmhpU7u$ko^t?uu|lx?)`OU29#NU3*+dT&G>vT=(2K+$7vU zZpLnKH-sC~4da&YR_oU6*5fwfHtn|Nw&%{_F5wPxH+F}+Bixbh825blTK8u69`_OV zY4Vd#rivd2)D4c!E5QJ>i}RPoyWt zGvBk;v)Qx9bHsDnbIo(li^EI83*=?&1@}UDA-ynO`CheN&0alTBVN;9YhHWa9NrS% zp#LBNKt9Gka36#Z(g)*{?^Em3?9<~j;xp~D=CkL^;Va<_@-_B_`yzaiz8K$p-&)^h z-yYu)-)Y}9-#tGLKM6mOpRpg@FTgL}59`PDtMhB|>-8J;oAF!s+xO@6m-GkwL;W57 z1N`ItvHnc|I{y~`UjI@58UJOGAT-c1Fd#5K5F5x0tP5-j z>i2X>;NXbZWBs9`7G9WTO5*x{ktcz@k?2R0aoQYhI z+>hdnl8gdJL8Bc1g9UJm4v3EbANJllx~=o;8cfqRoD{=Q4kvA$G@P_)8-_v}M%yt% z60>DSv5c}MW6UHoW6aEsnMt-~w#;;A%dMQg-#hR8X3eZ`&6>56f6h`YUp;%DefBx` zd9LjznolgAu%GxmiGGsxr1DAUlQGHnCD%)SBl&~mImw%nGLo8-7Lsg9AIWIREXhjA zPRTK;_odcLeIxaQ)H$h}QZiDSQWjEdDIck5sVu2VsZOae>G!4AOMfH%gY-G+o6<7U zn$i~1Y-u0qXz48JO6gANv8V4pUH|l(r$0PB_w?pdnWvghEuK0&^?e%iH2Z1QQ~uL& znPoB?WOm9NkvT7OOGZ{kOU6>hLB>}mMkZUPN`@~pF1t*2gX~V(BeLgZZ^_EaYROv4 zI>`FU#>i&NR>|^Z$K{sEZIIh3cSP>I+$}j-IW0L$IR`mkxfr=@xhgrn+_?NQ`3>?r z<&Vgpm%k-1E3YMQDeoZfD<31DEng+immgPHrm#U_r@|41^9r{VWEHd&EEOCSd=+98 zvK6Wn_zL5S%M>>#?!@0_Ij?w2QC3k)(NfVt(N{4>F4JtcTj;NehxuqhjqNQS~;-KQI5~Gr>Ql-LI8CPAVxJioRs<%{SRkc(t zRUK4)Rby1MRjX9_s^ia=J=^eX=d&Zv&Of{LO!hxK4Iukm>$&A~hv&Y}W1eR}uX@gZ zKK^3aiw!S!zBuyY{EJ&JWM62#uzcb0!uLhYi|iLwFZeIU)t0GkP}`|?MD4uVEj3v+ zEj3Fu2Q^={7`1G*DmA{^xcV~n4eC49kEowlzojm#uBC3N?x60g9;2SEUZu`gAJ zu|Z>}#u1J48n-lLHMBG=H5@d2HDWZfHL5iD8snPFG&gAO)I6ejUh|fwtfrQxrKW?X zuV##9HhyxKuQ{%@OlyPIPOT$a=e2HW$!ck7S!y|G`D(>zWouPwb!km#FW26vy-WM3 z_66#b1xF z*6Grj&|R*(QFoW_QQZr=w{_)owROq5j=FxjvAQ|G zn?xo#lKe=qq#RN;sf#qBw_I&fY9>yh;w_5Ac=^>Xy8^}6&X^q1>z z)Ze9lRR4nhZGAa?ZGE!7qrRVhtbUGuwSJfWgu!xyjRw06jv8DrxNRV3plv|L?=SW< zh&9MDs5a;_m@r&!xY2Nz;Zeg2hPMsn47Cl(hK`1QhOve@hSi2$h7(51jW!zXGCFE> z!RWS;oRPK>`9C}lKsI*7&qu@>=NMNTcNtHZEH~L`vdiSC$pw?!CUPd)CS(&w6F-w! zlN^(3lP;49)8(ccO?R0dHN9YZ+f>d}+mvkTXzFJgYno$PZQ5lzVYb|CquDOAqh=S( zZkx%OX`7MF9L@a9V$E{Qs?EC0Cd`+cZ#3U!e$@Pe`E7GKb8U07xudzCd8~Pkd9`_$ z`Gm!Ci;Wh$ERI@Su()j@XQ6FDws5rYvxv3Gv8cA_vY4=3Zn@ENm*r8*3zoMnZazUF4(W3*_5mIkGmHOm-yukz>g@vXQcj za+Gp`a+@MY(Wa0ojubyiEG36hP3fXcP?u9TQg>62Q7=;OQ01vQR0@?t^{2*BbE!4d zZt5g$1#J^;H|-ehBJB=Mo~A>i&^R=IS{yBxRzvHiP10A;H_>;~kI^sE@6hGxI&=!1 zL-(i0(R1lF^lthjV+CUqV>ja%<09h@L!P0-pfETLe?}Z5mr=v$W=t|yFgG!GGmkMZ zGVd_unL11glf(39#xZl5HOy}2Bx?n06Kgl?80#YI4ojY;!=kV_EPqxUE0Sj$^ zt+3i;wcF~L)kUj2R`OOlRun6amH&TuBEa7|&N|n+#=6^j(q@ItCY#+h$80Xz+_90j z(XpY}aBTc-;%stlYHYe~CT&;PZnE8Nd(8Ht?HyZrTOC`9Eyvd1HqJKJw#K&GcG7Nz z-6p%;cE{{4+TF2}x6`qs*m3Oq?c(fm?P~10?I!J4*l)7mZGX)EqWv9vd3zmuiap2P z-#*Sh*S^NS+kTS0g1w2on|+LZk$s0P&(>j6*c`S$JC2>pu3>kxCmmKeY;xG`aLnPN z!yN~C2OS5B1INMNAjA?I^J=VchqsDIC32Q9pfBx9cvuB z9Va;}IGZ@TImb8`Id?en932jY!{PXI;yAgS8csK7lDmStiMyM7jC+xLhbzz3;ZnF9 zu0J=9o6D`?c5^44Ryb{P+U<1A>7vseCwV6wCyEot$=@l?Dc7mSsoQDNd4=;P=iSc7 zoG&`xaaM5Fb*4IVodcZXo%5V)oqL?8TvoblcG=@{+~tzXT^9uxT^Fhg*CoIu-X+ha z)}_Z~%5|mdX4gHg$6YVE-gQ-Q)pe!1a$N&l<6ZMyYh8O>r`%S$ZFbw^cHHff+g&#W zH(fWX8`mwsE#589t=6r_ZOVP6`)2%N;^Xd@-0!+8xa+!8-MQ`o?(yz<|KXW{yqC2v zdtOd?tn}FIvB%@M$0d)u9ts}19#jvmM}SAXN1jKmM~}yp=St7bo_joxdtUOq>#5+W z>q+(GdIosLd**r8diHoud9C!??6t@1xYs4GyI%OS8eUW{u2+CpyjPxAtyhoNl=n*S z&E9*wk9%M8zU!^vt?Nzo=6VNs$9v~_*LwGOPx-9$+3d5&=eW-$pSwN^KDs_sAFfY; zPrOf_Ppwan&y?><-_5>ze2@EH^1bV;;H&FP_2v2o_{RI@`PTaO_)ht)^xN#W$M3k` zCBM6V3VynNR6nj?fM2{{o?oqBkKdI4O8?FNd;E|4U-G}}ui&riPxa^e2l&VP=lR$A z_xMi*tPI#3uqWVnz@>n@0SW=S0n`9)KtMozKwdy?Ku^F_;L5kSd z8%Pc01_lJi2j&IV2KEF_1+5I)9JD9sc+jPwyFm&;xD4{%cJtRyZ~N2FOOHt>)}lWuMFNCyeIg0@TK6p!3x2;!PH=Ga6oWE zaDH%IupoFkWL3zPki8)%LN15g3sDRqh0sErLIOh)Lh?iELIfexp{qi-gzgPJ5qdfF zUZ`RyDU=rK6dD+s5Skxa7b^GepFqQAZj{# zRrHqVz0oJ4FGt^tR*WV^)1sZC1EUk7^P}sc1<}(nt75jq?2S1Qb2;W-jA9Hah8E)# z6Bv^alOIzTBZ!%fT@||}c5m#7*vql^VijXav9wsH*udC?*!JKP6>et2?_ZLbqRum>BLouTN3vso=Ci$crQ^g zk(5YFbV>|NOi0X6tVi_b&fSLdJT)^tIt!ewxPNrQ+yPu|%rk6%fb509NOH3G#u>()H5m>CWjv>51tD>GkQo=`$ItGqz^z%Q%^FCF6dE5`OrX zp5dGkl#!TGkWrt}n=zBQI&*90zRZ)ES2FKsDrM?r(lebigEA8{3o`37doyRUR%dO^ z+Lv`Q>q^%BETt^HEP9r6R!~-ARzX&MR&Ul!_Ui1d+556jW?#v^pRJUwmrc)h&JM~> z%r3~T&+g5h$yuGVHD_PW$($=W_j8nT^m6Dq&N)Fji8%#1^*OycGr6mCx90B4J(+tY z_kONYu3j!Z*Eu&RH!-&$w?4NwcP4Lj-qyT*c_;I(7~x4L8XbM1*P?+y`?i{tIM{Q z?JGN3cBSlonNpcv8NJN8ET}B8te~vEtha2Ye0BNO@_pr}%CD9`C|54mFK3jyl=I4y z$_vXI%KOS^E7nwOtJq(0s^V(Jg9_ye{R&2fO9ihYsiLr=p`x#1_Vt?A+g|T~ed_hq z*AHGRzt(@vcLieXnOL*Hmt+++TUB@@nOSO65xZN=BtiC9g86vaqtD zvafQsYE9L)s{K``s;*W&s8X)duVPfWRPm~kstT(bs`{#CtJhR-tKMIIs`_g6gKFh! z{c1+FOEs@Lsk*Sbp}Mbnwq{MuwwnDlr)sX&Jg8Bw(XV0DxYY1!l4=TT8fyA#W^32f zZmZp2d#d(o?Soq7TK!r^txGMhHmSC-wxPDKcD8O!-L|^@b*JjC);*|GuG6n$)Vb90 z>XPaT>l*6%>SpWL)NiZbUw^9pYW;(H<$C>kM!ictuRf{1u)d+buYR^+O~bZ^{SBuY zt~NYqP;Ss~U^KWi@EVdD3L6?4`Wj{%*EDWx+~0Vr@oM9PM&(BRMn$cYYt*2VAwmxW8Zq;vPw7RtNT9aA}TN_&Y zT4&qVv~6qK-*&3)YTJW0so``Twa)^u#^*xzxg<7&r)4&@I04n~J-M{q}SM^Q&(M}Nm$=i1Kg zod-HkcV6p!*s0QK(8=s{?F{Zr?kwtT?CkHH{jVE=w^1ib_aJScNcXxcK3JB^{nmL-gBVmbkDV(hdnAi20hFk*Ph^>o?Uy6;-w!#sks?fnP( zPxoKzf7q|mZ_v-|ckK`EPwp@3Z|v{ypBq>^uzldb!0CZ&0}lsO1`Gz61Fi$X1IYtL z1C0ay19O9G2e%I%7(6|AZSdis%71t|KxN2ah&kjs6g-qXR5a8$)IT&gymol|@PXme z!`Fr%4yz0s3^Rvahl7Wchl_?Ahx>=;M%IpOA2~2`dgR*3!x5DcgAwM4>qziO@<`E0 z<4FI=oN%phyYPVUwD6knp-@F=AY=+%g~7sPVUe&=*e{$LT|2sc^uXxp(QBg*M^#1* zMwz3oqrs!eqeY{Qqy3|EV{6B@j~y60J$7yE;h4&p!5DMQbu4%+d8}xxajbuAZhY^VLiANKv6NVG43Ac%m ziIj=riKdBxiTTNOlRG94PM(>(KKW=;b<%K>HR(1PGMO@2JlQlkFgZW9ZfeKW!KpJ- z*QXv$sZJSAv8LRnLZ(util>^U2Bzkx*G=!3J~(}5`ug;vY1L`NY1XvcbjWndbn$f4 z^uYA|%(|H!GY4nR%v_&&G^09WIK!H8n+cgonJJ!Wni-gxpItY*WA@*+V&hxjNe~Wpc7l>^1Ywus5Lz}%5H<|1)9arJg8Vg?Tlx!*vDC!L^6+^_J%Jy4`c?Hd(C`_0H3u zSW!BXn$*UEt$*$8Y!MFLvT5m3>-cg&&3cy4;um#)Zl}@xdC&UJCu}Z1t9NzVea9{Q zkUqcG0Eat#&w*WyVVpUB>)20;Cyd zQa2KW*HT7##xOy+@3fN0ISpO(*eDjPhAs^4YDx}bz4eaI%ccmzDvaw?wE}v0#C2*o zftc^n)(D-LTLnLE>_prjDb)m=Vm&a*@>YuYviq>Yw0@8UC62ybvje*tNF2Rx)4@OMjJZdnmk9ntyl16TVqGmSK z&fj`g*~;`>>t4s7w?D(57g)7@?MUKh_Q|!%J8=0P$p1l3bJv5xCk=%h1OCjAMU?^9 zv3K(@^q5d?5*hvj_%Jkk6^^{cCYjGg`~g1xv`~pM{}&&cRPTga;KQD=A=&MXZ@esK zUM8$B@9^S@{y z0srSUx9Thr#lG-&JS*v9JPc5>Gb#T@?k1qosSYvO}wMOuL`vAL` zpVoI(od2fxISG8`pke(%?y;`mq1ejPTvp%O;gQ$n+^>2)h491V<3>c7DM2LuVX`{> zd+@c+qLI7Y2V2!wA47*Z+l2d@c+ea2e&XN=W_oFIbW zI@`(@8i0ow_M@^cg0SXrT`IqWPgpypHdMnWw)mcGbOsMsBYtiw1P}5le~Nt4MyF7( z0sOPys~6NA0}uC_*aYp|u71W6iQ#n)pjeoMI?HDB<;KPFZpd9+P_>Jpa=ld_eR18;XLj90s zQ+{3G!LP8e;REm>->59|N4v=8>DnEruh3>;-EOfC#D3U!#ac(8*U1q3V22~Sh;P{2 zCB|Rx!adb}Y%rl_Ggm@zdw6$6D_5s4cf`LUl6$$&NhndW)1|SWEtDw!%_U>NLc~Lc zqd{+oJwc>78LEZCpI+G+X@q)1C!ZKE3DXB36(&(4eZWWb!r_ZC+bj|zv;M`04NX7s zE_@@InVAaTeHqKL&4LedJ8dQlMD-ExuutThi}lg^vZ`@2^zba~VUrwqko!ju5rsYV z`QTx1)2doWeBa;oaLFdN#kGF_q>L5O`DODj;yUQguHSzs{cX zw5NS=uyT~E*IPYoR$9X441R~a{}T&aT<;7%7D^P|dui7jD3r+0^>FP!B;p}A)xb6c zeL3ql1LKfy!OORXpM>~8C+$Y-LJvVF*Noc35EGvnXZ_npVjfypL;{CcAG|4AR??a` zzTx(bRZcFh=U`#iUh>tOxx&=V^?U>HisuNjS&CGXE%JV~B%$8$jW5{WYHF{w73)Ae z7l`Kp@f;w=-|(FCvdeC0=VIMg{9X6rycbrwwf46PB?>g$W(Ic)CGu1};s(@&5;;Zw zpZ5fbcqsVY;Bs&}LF8{SxE|d0hL_BC1N9Iof=Fi@-U)%9z3MP}7>Yb4IT*hamIIya zFs%CTmmRG2W`lbDn z=9JpCM7)hv%d5JKiGTWH-v`#a1g|<@i~FD$zqs#JIB^yGrAD5XYC10+_#F9mcJJ@| zKqyhD>F(2S0Nh`B+!*}w4Q?_1>}P@Ndp;KNP*_NM8S)4*UtcZ+zEI$zKOQ^`UVbo; z4;}z7J_hWNbp(-_WRMsFzep=Kj0@?7PA(c{hg}381t!5Foy6u@tc^ha#e9hS%F76r zdlu#+hoyF8kzX+LxDlfH%1qAxdSmPx9_+W&91-=2zw1G)192UQ`+yj~*!RVH7w289 z_kvrVjw0QQ@#e_+_x79E&yK?vMwlA9bT`q0is=tJqh?d<3d9zj}qb5YL}> z`rO+h-xSZ6s{2~(hhiTT;}`p0u_V`d*adn2$mzkzUf}g} z`EAVO4espq0h)q!LJ4t9?dQe!jtC|Gr$`W0D@bJCmjv-zgLIGQOc3Q^q~Ccn1X22z z&QNeA`1w#L{U3fxLeSp|3-qN$y2&3gxEb8|hL?=JfBQ1#GSMfVG09}wdg*S$FJc>&&sdK2H^&Pofs(_@4@y9S=^ zi5E(wCGx_0_rHnB&SBen;SY#gMe&tXm}?K`O(ckVLT_y#`ej`@sUa|eAZis!r9tT1 zHOomv5atOnPZcvHWnKY6lx^4jC>VScFV%_so1eeyN?cE3-%ay1bP0tH67W}!MRgO- zCI^b{=Uy7Ko@H-GefV%atE*5K=TnY0dBP{nTR*8iEUtrQS&j)mX<(OF_hP+^buQMo zSl8kRoOgS@7V!R`#`xutKlfi3O8l>pAlk0zv;6}IqBTO_*uNcdmA+)aCj`;5NB_$J z%-hX-_3{HM2%_nLURdBx@Kr||4FnH0xum|J&;G^JG7?RsqoR48lm&kN(T$jwlqW`Q zVSB(wBsnB@EBwOEuD@gxc(|5wvB_ulXDfsDiN;UF`4{J1j62Pcr`!7y`TZv*eH;Ew z-_Jsc|0%{yME}))RVeX)HxdM2*6<@g65?aS5B<=$`0pCNYog9N9Kj7{B%%IQ@ zzTcs3VD0ysAle%ZN)Y3!#-I42E+!0( zrG07_&)>XkJ z#GcGw1&aT3{1=WT##7!{)pVuFPVaDnn29yH;r$G_B20X}p_jQalWea$SpGc|3lE+M zhcVARL==q(*If(ou+suggNuLTCGD`moCVx}GW!?4xCzr zjOKpandy9Iy|HzeAoQDEE|$-N=RE=ODX!q5G4g;X@KdU?cR6muo!YPE5nMQQk#3DG z=K>+DZfgip{9?Ll6!oANFc39(LMXAQ6Yo}b_oFv@aX4BtBI0LJH`gkwdNtngyJcHXF1bP z6t%B2u+IRTql|kCk;^zSjXNi;aK__NbQtZG%uoA&!uzGH8as}{C?0by>(-0-_SskP z3KLWs@2_~&gT?8Xp=+ z^ja&90d$DS`$Cjwu!IJ9|52uT|9Rm5!TP68FhvS>yx5oweeLx)Rq-Ws@FIYe{Qx?+ z6Ji(h4q`wY$@4q#5So3OT?oHyD)U>YkHfF=OBtYxBQ>^;H!#_C)Z44VnYwg^5~|UJ zQLnU6Ld$yCeAxU=-H3G}t{>*QrsV^sZ+KxlRju#u0WbeVv2NIXm3{;7{>_6<5G!7U zN86S$x)6V3U=?`1j)D6I;LT?M9U_adz>Ag|721%-u)+Z6wW5K zHp2%hTvX~GK?mbr=@pn1&=(Hop@W(R1@BF<0S~E>ry^dUF1}2pdg2b1QVBhbV~66; zvXzco;1lP|BRF_}>gSb}T<}%&u*Sj3iXf^V)U_zKVsiUjD4~3bAo_oM6V)~eoA7(H zCG<=O&JUIdC5#)pBZgMI@e{gZ$Bv#h@bHhXSpU^x*q!x;mj&D{jK>QxjDc>3Jlil1 zEktR?^@aG9VKxRmYYj7(4AX$$nDxto{;5_e-DSZ4yM2E<{80a(lSd=;VaWF|tlkM7 z-156wYzO=nL3^^ni`k_RW?}_&;1<;ymJ1#Xlk69H7$fi_rlrjeH8?3TFaKb%KDY#t zx1?Ip3A(5*thM8!B5PLHQ8fI@uvUSWHg=bar|2kTJX6AyyALSW89eN0PY$_;Aj-$Jaf}9l%Y*wDfWXI zonzJ?^x%$Ccc;Bx2PQ2&Ev`y4{NGT+U7;4=hxy2)Vg+Ru zO*{+uug9DUl}F4<))e#L(1$y(zS8~dY51i}*@R;+?nEdRrCfBT40@F`*B!c$gDxb& z$5h>Og(avLGw9(TA63mD2m$7Rg;<3cKxFmqfv;{GUNNMOx=|MJhH*bC_E)i=(EsQ# z?SU?4fk!KfabhYA@eD(4;zPuGM(F7Kz`cSgH&lrj&w8*>|KD40?Lj}#5!!#;f%WRG z;+$?lUJaaG;~L=iM#)~ESE)e1Ib|h|@ZI3`6}vd#FGau7o(o;%@2TcGDG)^EXsx2t zX7J%yzlFP(NUf$f+*DyhA2gxF3ps-5#{94ton}(|P75Wpb%#G0UIU%n>~$H%K8#UX z_pV{|8Tg6ppsY}0vLCpM7%JnxBGxbjLMCwUU^0h{5S>`r{hRRr0XD~bz`IVeU0o;m zBKbPLXcYqgT9-48S-`*1<5(^DGhXR4SAlvk@d&t3D8la_RGAI^m>mrXO2PHaA|j<@ zwjzeaX$7NySahY#d438W%CpaN?}3L0#aG!==o_7m=d=p@ALL%&P2# z`QjVs0@tm%RCh=&5j$u+p@i5sRDS>u??Vsn#JphozejPO(L3GOF|75bZpKj0S`&;x z;acF{$1ENC4bhiXurU98X#GMUnghJ;C|%ou|CU2wTQ_{b%=zPH=+f}W%ae7lMRnkP zrfMm8sPii-MV?H52%O5-Ma<(BXKny)<%u z0e5wMT>__$n6Ft{Kd6NI>;yhl66$0K(TJGu-TL37hJsLW81+D64KxlN5K4@|=d_YrvcF zPT$aqHPC^4fJqVhh$%D3Gj}gyMsQ&|cr@z?%S;5%<`vO*Bh3)cCHxTt9b4W^UF`|H z6wmBCTqp2AE&7ffiyg}GvilD3KhLqUImc}D(H|>RIltf}WmV;Ut|R*CvFc?D^TmxC zJ15jrjeG4p7wf3GQNKq)iy#`lg>S6-+eiP^XNex@!>)MHtjDLhLM3bB;HWqHZs>@{ z2&V$1=@P&P)7YaOs29B#T(wr@+2E|JMPm|lFzKOK z2fWb1TqV|Toaz5XsV#8t4lFJRK#byPX5R+>iy@Aw#}NY~PRHZA7Qe@wiWmbA`x2?5 z9WP5ts+{LK@ZgsHP~?9M%R+Vb9CoJs%QiWnZeG4uHtqN)PMYyY<`?S&>%_eIXh9c& z)ze(mXGKiyStlvzV!Td$u}%(P2MPF;C&35m|JgUt2mJDXiv1UWThl6E5RWKrJKYWc z*L7pR=y(PE%QzV#AJ8vx(Q4uYzwgT(_2+@V#A~iP4)_&)hbq2<4tN2Vie`a7BIs0J z6yodP4>B3RuNP{a0)EWWBhSS>1`jbYf`})G>k_>Jb-@EQwN%_MoOWYJhF%!XhW>4K zlx-8uRhYB+i#`FpMILy)hZBRjVq;~Ah=<%`)u*_r=p*N9^qmT!heNfwT=;Cw(z;F# z{HbPVeVy1hRLuY8Llt$}i#hXuji|zdMueL*&KsVay!WyO=hsw|XfI!!I|P|8@tMYI zjLB>L=dq90LEXobLAI9AY(r7SRwtR$5vExEEo-lsd}O)9)-n-lHzFLq6PHjNOyo0b()NPAn}xBdxUT7e*EXq8jYU{< z$*U7kOL+Izl%;S{-o%S!ZG3Jr9!XKbv@uBBNdY>BB~h9BoH$62Cf-YLo4HQ+B6_lh zCbltn#C+bn!i&sUI7-1_FbkP0mg)P`3QU)}^?2AIgJn})OKsr{{)6_upQ2Cqv%=TP%o2X^)w2u zK|Nvnar`ad`psS~#Y)5nmzz2&iXIB7$e!`ipl?#45@YkoZ&Ohv#)b*hQ~}b1BMDQpZo6U4@`aF-#m1mg|!s5_BC2L0soDjEE_264gQWBcInuw zhsuJ64e~^86Y#NNmCMn8>Em6KeI94P$2+FJ-r$AnWbv^dzRp=qITJVmH#@VhFOd3BA?`7Q=RZRauD|ejH%=aYQeEMJTpS1(muWMSv?QO7!N`)J5 z(U->EKEb3^;F?;fy*E*NbPX$xRPSoWppVt@hRcA6$zm|L@V|S5t&ML>qP5 zSeONL5yYB}S_U1L+kO{c44g~Yf2P8%j0orXRPb#?_(i3{MUDRmi&?0TbMY%u$HBut zbzu@#Sd@lbnYGrHr*6e{zUP0J0(~*{$Jxo6z;8ovlV3syI)rq}5D`MxCZf`YW{T+X zL`Bx~@c>3U>fpzb{j3!@V{zzDwgOir5rXyBDZoD=)_=!mcBs|YgRS@M9f7~D`91bY zI0+r@b4ah)0eT1x)K?SjL-5iJ9&&1_$+rR%Ygyp$Sj4}~4xUx{aqDt>)M)kICIvRWUNc+Y?{FMv5uSLi!GrX@J-SNd z4ZW|}&}(>#ezqgD75v!XsA#$m=rE)@qn^e3aOWAPcy0k7o6PEbaBYr0IWQ1iz}AKK zzUX`pf6KK#5_l+AZ50w!Mfe@R7wO)Jc*#oj0{$<8AEdGnAIGju%>)lRnN4Z%7ZZo# zr)i(VAD=YMy?O{fod*QTs3)s*A~E?ou4_W*rj!vRI-MY=pPBv@DV)ouj=D3ip$?h{ z&$8O#gMNa1>$|}3C&u62WCz@pH(HeKk&9}R#ymD^vsSVGmctpGVI8V+Vq0V4NWgS5 ztb5uP`in8s)wN3_h^X&Lp=_)xLQ`Mf0eJ~|Uthqf!t)*%4PQ9JM}0pqULw+m`(b0D zry6u2Fn{9fhB{HA1P1|^bt=6ieE)(jxG@#LCv8toLERV;F2q9rcqizG1s+aEhluVv zOyn{f7W{!yx-t!V68j@_@7VQZ8hA)0zD;fr>p<*><3}0ur~?PF5BBb{#`l)VEaLy% z{xjfbG)Pir2{PIyJbJRjn zKf&+sy%kZ5{JPtoPFyD9;qU%oyu{ycK^MECK1t004`P2%FY8W2KP0<$l%_Bj>Oq+N z6j6alO7S7Sqo)(!rTdHPVAziJD|}$Ax5R25ePCXUzpc_9nyRd9e#Tw`-QO4MzIr(u znr?6^dt{INH|;E_vjg^K{oHqKk<%9B`PDIvSnI#={L5KQBOBCXB1vmZ#7n$}&WJ6z zi!p&t(0e0YN#ktB8y^Y!*>Iy1H0S#@^zj?|N}5T#ml^o5Aa4j*_h!z(eBmjYFN~Ks z9Qb>#@XB78C;piu#5|aO{hA}18z?^AU!{Bm9gv8QWM$~UnaEF-5zhr;9}v$0i}<(O z!*i_LF8%sE`#a?QPVp}L?ZCY(H_z4^xV1CgL}v=EWvSj)H8`7FgDEvi z!`ce?({^b5VFewEc}bem46u0*ynLav)n)_g=Z-GT7JeT!N_t?AYeg*8w{(Q|g0c*p zosb)`f4F{Sn&s64-*|_zHwfCZ8fHd^L)Ydf?LJD{Bhtk`ee`z35|J*%Jc#=xgElge zjGk}xBk^s@gZU_WIk6<;7jZun_dzj!ao=l{V?$fDFRSa>k;uDJsf#@odB2mt$xaEl zKhE^B_6P26G43RD78_@k(s9nrKXGS9!d=Trb!8^%AuCfoo(0`!9@dayC4(0Yjh9w8 z{>4kM*1I;)cfwH}GaFnpCWrLE&iqZ?@X8I8MR&zwKAdyS9{Hd)Q784HIzb;<@QcOz z_%L*PDs(31LEI-;F4Hy1@GC|(;g%{Zt^;u&Sj7L2?~8T+dKY^=@-7R#3HJ28QU9^PRS%V2&8+{uyg3}EB8henI`n!BLa{E!#f3>)lzsi~b}uEx~9U#)|Q z-kR;JZp!QgFI5`bSuM^`=XkvB%cYSmP!w`6X44W10HFrG={(}Jz=w=5b zieC57eC-*sxC7IK*YrF)O~?8R3!iJ#v97|CFMgzVfuFt?JO;il<|ijZZH8F^-Gr$# zSbC_ZI~opFs0(o&iG3wTLs#0a9X=AOuj7~{@(-hNQGel@l2?m-gZ`_vbqrtR7hW-` zw&1}vvo&=Nz7Wv;S;|`Iz@ErURTcYy7{9pg#q}<(b20AtO-%IiPC0R&LzXbU1l|V$ z6vipw<@m%i9s#eH=hqC>K(Cwo0S0o@r|fc$0j>5U59Pa5OemA+IjdBXsfw6E%2fAI zvCd+3RUaDi_Aj1N=rNetAH8@c($pe9JJt6w@%@N|}{>x=M{d%CCXM!?5+a7uOP!oxZ< z)&g^=qrt?0iIf(9j2qF=gFyk$i#JCm1@@80Dp)(r7k+1AZW7*pR^Ml z-`gO+RpY7BRu6&uOh5(W0r2XJ^C`v$T;O!*74@a)tZg`3jKl1ErW%2BKGS0?XiF$z zBFC~8MdJo5)FSp{HLR5L8{i&JF_O0a`~S(d=&!@bORJ%R3z_w=sIFkQ@LEy9 z_WyOH;JQi*j${VnQ+&=#oWgvja*>4@uG81@UiAIWz!FkmQ(uloj zh8+0#;B(#O_LwDrqnPsouW$YDdJQj?SKMq4KjTL!Oq(-Bo{HC~<8C9x8uO2l6Dg%- zX3$>m4yEg6&{D5Z>1R{)_x@u_znef017S-0jA_VGnbJO^ZCG=l(gOo%Z}O(1KzB1i z%m*t*0|NfZ$|`;+iYlJE<^A|hlTUq4B!$62xz%T^HVhsgRjyk{RVmX&-(ODNCYq@_ zEG**Ve!-gLEPjeOj5Q5g91nqR1n-&81Qj3_o0kOSV@*=#4FB&C+stEp2jC0en&fi!Dd5Ops|EL8m4)5<$u<(wCKXm_WaV6q1 za`%qKwy{!#j)Ve5arFsgAx$4%xgu@y7g`{=Lh5>-p2Dj)=EE-y5HcN zc30Y>y%f*E=qS!`dD-L1mdWaT^pGoWGoeBONt3Xb*u4#nAZfMk!|Noo5wzAK+HFk5;%uJ$_I>6 z+(ufbD^i;#$HB)0<8H4k_6xqEF&m+!y4%$2Wq94RlcJq(ggLRB9F-LSKiNiJpN6{X z(6BU0-iMl_TZF}Tfu~>#ejMt*>y|}s4Cd~x84I6iIq>Cbp%wwJ>n1E@!Y09&G;nq) zhW>*y@j2@DO4U6q2}11%wI~ES(CT#hfc67;SQAaBEXSSxzNByI zsKjQCRBLJ|F07gnOj|YyJb8`u&4UW)S(oVNTO&j|p`RqB^=@MUznmhg<|~3wRMUD?xQ8H~KQ~WL0xESWmaJbJ_QzMcNz03U zBur3|-F)7w!=fjO24~ZPDD^}Pk(g;nEuGp0J}T(Dhp*!P@)muv^Bj7+CymmSh#sa% zTVE54p0}F%Ss66ibdX|Qh)-@Fr|9NEyRE;ITe6G5k01F(h7b73u`EkPuj;V2!&i9h;t{>H7RcRi_FZdj~4kjGIAX=%mv1&UR2=g>x(+kz(Pdz zGg++@|hm+FUIR`#n*x)4>|ns$et2|flhHc`yxDVWhx#eC3Ogz)5INBU?#53|cYx@yN3 z%pnT&t<7xAIOQ~>dJt1LLoF7aKsSUe@{(KhGk8&;JT6!YUR?eQ?#jo|9B_v|-ZL%A z^B0eK<6(%_Ps&I9f%}f+_yAm3%0t?w=X2oCl{ISvPcp`ePaA#({+lnPE5Csc6p=nH zEG39%mZp6ResGz}OMp+PXIa&RxPymrr}tgpBf8zbt7*S2@L);CYHYX1U!%MSpE#Yg zm-+&CdLAh$bY!YoDb=1KfRh)c^-`;`z&|p)C=qjI#C-O}MLrsY?cie#J!JsCQGSW> zLl-htd7OTy74=dbNb_!5gZhb~ovllOujo@}D-jzascXyjqK*#CZwBsy#}YGOK=Pf( zmXr4o6`x3q_91pi?i&Vf_`Rvn+z^u;3 z60B2or}6T<-=PCN@}bmX;QxbhC0~+)Ay)WctIad3rruO*ZWt#sGAokuFb7AZCeGnX4!zb0@%9 z+9DrbqlQpYAYF4v4n8u#Aos#IUw=h+ZpR9$f@qV?UC@ag?VtLgU8{`*FX>ZIkK|8} zi^lOv((Q@25G+bkCF6%a0Pf>by?t1xRL)agH~4z`ncVknPRPHv;+{rCImc(MHK=pN zhg#a@8!;dKX3$o+AAYD~{wnJb>fk48WKtV=xWO`wM5Src*cEVr7{4*8ngKwUrV?E7=&;`^yIFRPYSPMSd((9>l*!Fxk zQ=QT~+l2eGcNY1`8Z84KKZt#mq0qkqb#t4p(fJv4QZDur`d3ZJNbMJ6xUS^jlcJFe zh*?tK4FZqUJ?ZnkmdN{iG9Pw@0RMM#lr~4;XDB{s0v~d&&)%(tJ`|cYk5=Tu2ekDn zi}1c@drUveg&VzKkz>-}%IaI`Y4KFV0c*Q(Twm)hXRptF_#^q{QtmeJU=v`!$OHU` zekU%{aug?uEeY-v3+$Y?CsC+JaVHy+@{%S(!AadruZ1pT(v~wn!6f%d`X>4p=={Vtg2De zg(OR*Ru23C{48m%pc(it$Y^)n2L8u#!EM&SZ?5>bNeTErQ5Dpoeid{zb}slpI%#(a zSXbR(yuIKcbTDE0PS$tO!AWXd3h=5gWxkBzpdR$?eh5KcwOX9kdx1Y4frlk$DR?Lh z)TE(L=&eItfKO^_oD=zvg}$*%>=Tq=)Q4>HxJVa;g|7k@{Q|u7)}@& zVqS(fg+ka8wprV$U(6z7Io6AO$c}mA3aRve`V6ga&|$$xe($XUA6NU$fICq7cYzGz z6Pe7e)xa++H`hi7ev+a>Q#|I2ZdG<&5b&Q@-(7|GDLv95l|jEM7KU<#VEI|MnS1UU z=pd1@Bz*^XsG?k(z}1v@cL zar)$QI05j8Zzbcp0Z$SWDN@)$Uz>cLiqFmcHf4^6>sRheJxH%c*RM>SVCA|J+MsLaA=G$qlKFC{nVrbAodKnDe@ zfP06`27WOjRen_)bS$H%sNFOV{L!j^)Wh%Oi`6LASKtE$+VbLlSo}3~Fk<4KuLJy# zEj1T(aE6-n>M?lWGvAL(1P@s@x)H#mb+9-xf9#-w=Lxg>dhk%<^AS4`Je=j-U*y36C!62LS%`Kz?5g9X$z;rz zhZ9C9hY2E#l;le3LVai?SBia;23=MCmU@Vu23>rd+9BF)9UMvHF}Fh(7t&>EO!!7k zhAezEa=s5f8ZwWsWG|uqJYxuDt)ezhp~CaJY3Ig~;ldMbxQ^_f3J04t5Y<&m8_om& z?H9Ld;Gzl>nt_!&Q3tuC)n)h`6^dbLA$0Rh*X;egI^fr{Y!vr}R8*r{2qQo|Cq((8 z9=^0M3vmPw?M@&10>91;cY7D~1=0sT0{c1e@H?-4kp~m(OsT|~i{}V3_;-;^a9Q*T ztS|0^WF@L3(6Ccds5wxz=PQBOFX#gJXMEa^j7H2EO=*LS-$Z_q9zp*Qe0-3>qgD{) z`LxUsO41w3H5_t^T|Xs@eXEk+Iz)>@%M? zS?@4~uC~>z#R+Pl23vZ$)gpV6WJj;vIFFd7Kk;)xwg14n#Cr(!d)fUJJOtE1TxVV; zP=Db$$SpDpfz4}q2f z8Q-(0kB><6tY5%Khryia{Kj^N(Y*a2_LWsl-MGiGujp%0=?Wd0e@_0@)9sBeNLs9j z;5FdE(qU6D)~gfb`U%emxJmwh^7aDn?-9y8pl|wT$|zNeA%ELT$d2e2IBk8_Mn3Z@OjU{19Y>f1Apj175Tw6BET;TUyr>!K^EyC zffzZ$z#yJ-p??YE4xX%P5#w*or-lH3Nuw=g1a)#9PcvJoyP3v=k5`&&ESBP&a+lUQ zGG2oZRT@6SF-z|=R=DUc$WX}!E^i}Ye4bqi-90x8a#BJbJ|lnZ4p%a{L~-_p8yak2 zZVI%9F05?#g^2jDar%(=3b-HmwDQgY@7?g7LGyV1f3Wt}QB`ek)G)SQJFo4vyD$(H z>;#dLmOgYI4tbJ1ba!_gN*bgDBt;ZNP(n~dF|fP%=0Xqt{`vlR-|^lt9M9cw_TFpG zXFhYSz1BLLHzi-w>v81@&Tjybn0RbdYz=z79tMdEdCI!!3p&q6>PPKi+u9+5fVd}_eO06 z{mW`0-%s%swx1q?HhH{oDv8{Q_HA|PjKe+neqr6_&C3MdvHIATFeQTuyt3J$B;R&V zO2(xF1O0kkXL>DS(k<#`vlpLY;&HA_?m9w#r8^d;ayBFG>!6}@F^%%Ti$;GLIsI0HYo8z_1) zs)vTUo^Pq* z_f0|x@MU>*rGu}r`Z%95Ekh1`H0Sq|{$k80JKN>c-@q4EKhaNzP902srt-k66VdDv z@Vgpq>qH%J(PpbJD@pxd4SN0E6FgOp>Az3YZ5QyT+~4GS4ES&Gb>DKr1-ZT9(Ae#= z7q|uL_Bq#MzJgk#=Yr4Ol1JZSVw7NG3vPEC3)-4tHYmsVnOzFJN6&OBW6@uoq)jx} zXXA58D=jt?ABj!0^m3X1Kl+%#_(8@UzGC*vgNH`P8EMf^{>Lvo1H{Ot0O)`#tAN`$=)^ayAf@w=lcME9Kg^2gH*TO!2i56 zg!>b^mu#hSp{XY7jZl|M$or{!mNWW=n_p{uoPB{ixJuatUUaLqvJ_8dBe#lCQ?`b~ zRyE+(%7|s{@t2o^D&xJj$Y-9Q$q_o*b7hmM4+H1$`pmAe;A6?#sUPg&195Ver=3wx z@DDNf+`s*-H`5_MY!C9epDP!S9NIkc>d6#B{L_!pb#iUeU;fntV|v&0jK#zk-mCBu za2~G7>xK?efA@>t$U)IXem}^^-y7x%ZtITSea=NqH4L{5yYwLMGL36T^?vC34d-g$ zoN>*|*&g#UbrlNSDTr^%mb$`sTGg%^llp1JxZ&Ds15eA#(AE;e*_K`4<%yxO)no9| zYGh@t_&>ZT8SC2O9{l>@`$hRz2w@%oiW~Oz{kM{>KW%y4<0{nlX`GD`+J;7*5&i{-oN&mO!|SL6CM#{{Kxlw zzV7+;Uia^)-mR;SJEJeZZCk0~x*0rtEi-mQE^jxM6uRO3R{x?HcjU75YvB=(a1x;< zEB#AU;J&_2|Fs3Yv^w9wmi8R{95iUMbjH2A4Rx)c)6x@0Le^*-zmD>&jd^yc(JKR{ z(v0=+^!Mg7Sr}*WeU;A##-kjvM(KKnTOAt)-;Bd}b0+FSho_VQ&C@&U9;N5O9}^xk zi9b4`R(QIoEBM}(=1=OL--!?M^WUZGYKOX4x_y!htu=Ku=(#L_-lMB4TuuOQK!qZA z8t}d?Rdoe_t$M{FZUu;+3Tr%|#n!I{Q#_H|)~~tUUO2B!B1g&_`e>6OTGBB#ry=gv zEjPEsJvQt4nBNCK<@!gc(E0V1`p-uBkuiw2+y&kIYq*r?ru2)^B&*MVdExsCUnfZm zEcQA;XW&EDJ@LzAj~?{_5x2pg}09tMWC5wN^UdMcv5P#u@cvY;u+EkNzf&I-8>gK4NW@-E&YUKb)E( z*JC^}IW!;>{Vii<-9W~C)Wg-EPCUOq<01p#4~72E-l1`UtFgRpk27krg;u$O+YQ{O zOH|#?1Lyt1?H*SVzvVvm!nN8CXGeLDLmbQq^!6q*d1>0-$Yr}zN{5dzVoI`r&oJV< z1SKEzm3KSiJ$z9gcgu0k2F>pV>bQ2R=6i!X(AF(2QA6~fEl;%u4ZlHiW!h(r;H}Ng zl*Pt`H#y21lV0$2O=q%M<^S-sLNCO;5B#jv@3QEGZe|EfCt z)Q>FnLw$6Pi>USsMqC}P>jy1%THv3m`cs`J_{<0OpSl~#IT~AZFCos?P|!`lHT^Wg zby2hJA2j;(jw5c@T&>rRHXPQp(?^@zgtX=xh=RYLT6Dux;H_L+$_UqMR;0W)c?O<7 z=va}uyS`KZGi?X__lUWG6TFJo@3ti8$gf3S_pZA1#y%bjTt;+UIhzYD-nPtr>xJXC zJ!u)@558B>Ht9&JANrQg)nQ?N+YkprUHp*4djcV^{C#kIH(1-> z5XWXgR{lK1@Bjt>IhdEG2MGE5A}R;i25d&08({fLf2(&>ocH2$%lXlm+{R)H@yLH?O z12qs`v9>o)<)=FGHK3=GrLK(FrIM|N96VN3(N=3lY*AURW`)@=Pvv&icbN52RF+T` z#2T@XQt)LeW(VIZO;Uj;z1X67NNEuJDK;p~P(*FM>yXR2RD;=}`?8lV!lUs5jT^E{ zNHor|&3{&e%Gi}OH*?d_EdL)J_1^D?%6>e%x7&tVgE7nd);`j$EgUliIISjMAqJNerL%zZnaocKc+M|N+41Kn1gEs;iEI)j=ZZl8 zBO?-C2RFUnGBP5Qa!R4k6!XExdh}X3%-8)2P$J*guG( z0tX&_0m~BE!lEym@cUCogt~$AlEek81{tiET&GORlEA!YtAihB7UnTSGrAbn=y6Ol z?s1S2JWs55gbL8-tYyvU-HS1eIqOUFQ}ktv*b%jp;6<~UODmp3H?tX)CEws1N{p|g z{8%tGa&U*vL##Pj1Bf-O>cJ+a`7IEoj?#PI$+T|&wP@490`kqyuXzxnLP-8a+tg<`0Tyq%u^Y_L}sOd z*XcA`{XckZj{YFWk{r>|d|&iD4Br55y70ZxIOz}Wz5~UdpbUvp;hNXLc`^U+rzd^D zpL}9`*AVb`il1(&9T`#4QB0``!g`s9u4^7#P6l1*=EcPu5#uxo;rAD;z z=0XeT>1Pn~2?v*8E`bLTCKQMaw&tO9mFe7; z_)oQ>f|P~ied@1cJ>5~Wu=F)_&~BVhW+e5N)9(k@!!H|rrZJFBs(W&Xog`*>Hl^OB z19!OruaWFf8~B;NoK0>x!i(g@keG4E5v~C~HnVIVqwY)RGGF%2K;1Yq1MYC3lclWU z=04O9-i6qJ9Ns+7-h3T*zIBl`SoH|~@f*gWiX!l0!)Pqaf^Jk8VOPha@cyQXA2;e_*IQ%*4Uo!cq)WCe;cQ|!uH2>}5 zhuY}q7Y<%}-Q+PcqP9fMq$(Wih1&Yg1w5>eP^dLYaab1-w5Rx^K8zduyBRp2s-Em_ z`xP@fs;T~T)I;8Go&p03ZBo(?acGoG}BcboHz#EiF&rX=QWV97q&jq!Ik zYhm9`JQLY6n>r6*%)5&ze)}ZGdXw1Z&CtP(&+LwdP2k0a{jqite0PX#U#$;bs0@0g z19+KCt~QqMHwQ||@rC~1_$8JJ`|$Jr3hlXACDQe5Gju=x81>N>;Lkk0yX)a-{!iTT z85vQe$)-2E!3U&N-qao=>&KMP($COAk8$FayQl|KYs=VH@bJ~y#25USqy$Z6pxS9u zlC5l0Fr#%KRoo6)%Q%$wn6U~^I*-$ZSkMX41!p#C883^L*O$O6> z!Os}@J=HPU*%th{)u#&E!Oao^)9mOns1F6+4F>Su6-jqx<8!a)@fwJ4fRAVn>JohT z+k-#MQ%!XQYEm!G$|M$_XU%!E4p*pV&FKY_YI|mThZ=Me%RGO37=Dt(`q=y$I$6Tb zZTtaV3O;26cZ+b%`>lwt4>`SN1HZe-{uj8Or0$U)Ptc`E1)P}CUkN{5bmsgh{(5nx zyK{k`COz0v4Q35G`WlQPs(7Xh@Y`&fF2mOanm6*}EHC~KA6Xnd z`~W^`|BS>eoiRR81(>(V8}rp44^XL9Ynem$pqJX&%-%ZzP~0%f=$1NodHWW8Ud%dl z=G8xlZ$xK3-vRvBj#dnA1OC1fdHtw1neAtCyO2-WF7ZQmxg#U;kEK&@eSr_=DEQtu z2mA|F-D<(EhLv_>Wh`_sVDPmVJW+bgDziDLhiDs%geRznJcrkzdGLjGUZNh2;9(?; zJH`Xt+o>((mmR7)EIe&09of9n%M+x7&)Tl^eGDF4{Z2ZS1-viE^V&I62~J)(XWD4| z%&{jiV}`>*60-`%>IHm*43oSoU#3;ZqOig%$N`7r5ax8ZNf2jrvpK2U!Hb>OL) zS#1IQQ}k~0b&&4~9hh1qrsJ-9)978XuP|O%<}4nZ1RmmiR=J~U%}$5=jqwnOarVcQ z?{?rlWJc-(zE6zShavAKV>;Z;B;9OG7ih=VaXj8wo&50)PBg)tA>sgk0w3S_d^mNJ zzq~Z0za~C;^#WlfL}$5 z*II{uAX~16?EAPJsGQJv20EzK5V)R*I@qKmQHi?Oo@6LjoBbMB%Eq2V_`rK5 z$0p=aZH=0K9dx51tgTrU3ms7O*?b)opm)~Mp?YVb9lG~zS0+WG9v0i%Mm&TsNV=H^ zfFI)l|68sY2bkqVUKryc1~U<}Qa;-Om%mi1kDUZ&fIZSo=xA@=9-a){6p$im5lE&>uclT~iM|sC#H8)KLqE=gwD!Us44DX(qcU)5m-ib&q~l+#!_2Y)3vHtfFCDvEUg$|DEVv}e$auM`NPq1g1R+5Z83N-WJ$!{Lp@A%)(K-^ zKh21zpD*gf#5-uQ%UA3pnHn|blXmz#TQ_CU7Czy%ELGV~1T$BDY4gT>Vk>&Xa9${5 z6-EQw(uEjsy*qa4{$siTZ*PWqRb%6fQ62Eo`Qr_a9l@XejX&;i0Ds^k$ zUAi|i18PvHsgG1a)M;*voR9clM^r>7qDlXkNZiNL`lVXrJhJ}r^?i6R=69j+a9Pan zVnh*vb}`Oj&q4#*1BFFHO>AdWR2!M^#9IC%tUu4f9O*ao%4j3+`m;19Mhcl00|`v@ z(Ak}Rsm$ZxVJFt*Hkuh(Py8P~axEg555R|&<$ZgMIo#@O9LSo8^F8_scNtuN0_&j9 z0^AQfGyLHa^aajAA=PLv$4xbg4&2XuX2hUP)RN#?G17>NQSs3)fV(_(Y80x)qBm!8 z6jW-_eKj@`qYj!%O~)t?hnkxskwx07&W{n@h`s|;Be!9eLi5e)hYw&>c89z}$udp7Ni8VHiUhKhP0{C)*bEGT;esIeJPB$IkUoh~T31wwx@bPym zGuW6HRm1+5Hzv0%pvGVoGX*Q~=>OC_-A*3*u(r6yf*w4lS?zN0#&!1Cu5fvb>sQdf zdo)28QEWM1w27tSI2edFjOk*?b6yPcKy3G899$nG4}w!-5CBE3@6}ccJ5-}yuzut zc8y^dS+@u~Z^E%4`tUN_YXvU-KbT)5y}8e7ivbpT36E&2ct=63$GF>)$%GL{59VYq z=#w+fexu)Nw2$q4I^-;LG21OK3i+V6`-a3MAy$MA#ViBvONncu@i~i*tRqpE5xYt@ zMb-lEpSrNfX>N@KUo^FDnTR?>r6)a+LEty`>p1d$0lN^i)du%51`jd7zZP|Xe{5(b z4!U%}J(HG0x8JdcArI}W0scdeQXq#UpP5uVhUd(St>D%iM_1ICk$1 zBkzah`-0u1Uu#C|0kt1K_}33uyP<)^K!ywqS?zz=hu_%V_1>}7pnOd(SL zU7Hxn!2ka48wPS%=-qah*$@0$EiEi?O1`@k|5-Q4=p(MVKySe01NbN~IBl*0eS{gu zo5R&ZW|$6R^4%sTKTl=$GB0Mb2e*mEU-@bBfbIa5eC# zyDy9O1rN9V@5clqDn(w2MqVxIdFD~@QH#4pnIlfQMy&WHc`_at$z7syIir<<< zpswst*Wvr21LQn{4IP|8?&NU4Y_we+b$SYQ06w`_fgk#I&&N2jmY@IowG3#sVC&tj zOlYz2ZtHOtK2ub3bBKKy`1dpwvZ1|_N$?Uee4o$+-YTkd+Xx)T8tMIKG7q(PU;mC- zG}^Gtc#%13GsM`m)DrdM|K_(oyoPAy?8kq7)bTwd#S^~4_s=n1w0ZxGf&QrpVPP=~ zfuHY}68V=Sp|3F>=Co~(c#7jc{%CXjvrNQ4e|?ePFR&`mMnBXga*<@m_ra$Pq#wxA z?F(XVNB)KGi!ro;-=f`?=?(ltw=c7x`68d@qiikU_ib$F+(t~StKk6K)w!r40g8(* z^qh81hoXNG*M6X*W2gYGvvjMBQCm@8^({!)_*^d4b(Y^!ECe z^EqCq$CtL2TyW3tPngzDTi_r6>oBPY`cddW3OewF4vPQQfeU;uZO;&!8Hax03qSw&>KKl|A9Cj_ z3)(59+*-y)PK)l|IKbHk+@1|wdpcr$ZLB>;fFLlo7=3kw}xa!54pdEZ42|a1Lilz@fhS0yD5BF@gbhbDB>l>V1991&T z7}LdFzl4~0@KF~hJn9pjx%;A40yn=dHgtGI+=4HJzhsf|f}JzC2d{h`@W%zeeSkj> z;N$NsXY2#+{cSd6rnhMRO&Rtg;N>*daLN#q>eB3?ixShCK?mgI>awaIPE;KCR0ccs z;kX^#scC-JxP(zWN9&blCU{BJ?$&k($GzGgbifbKQD?p$@{%kIUcN&od-Y};+n{ca z8q6@C__yEne_?*r?#SPMmfyd!bRC}t@__$^=YrAxR3SWWv>$EBu8cYl9<*w1k@uO= zj^D40xQl+$=!0m)Dd+$-5wQe1fcKDok?aRZ-hw(@Mf$-$4<_=PyRTE8iTWt0xc!)A z0Q}q=E7@y-?`-{J&O1cK>%9))h(XoTPUy=@`YIirDuMfXxt24oTdG?+(`7g2eRtw_ zaq7=hJ#dX4jdZniT=RowlsfR{-O|d}boi^6OmWIaod$-f|tagO%@L`yrWQOG!4|n1w`duMnng6Fyq&u za4+aU1YDzr?NM6^kNN!oKmT{z7_X53h?W6X6Y@Q$F@d83EYoX!>|GEaRi`*YTP5!* z70Gz2bWOQ{Gd^ERy-IOW25ya_Z!STYuR31%z*QH=XlKQ8)gJt6q|8f=uF?apI@KjE zgRA1F8vDsQUSYAOh&nWse^QIBx$7@4837c1UF4tdv$2MHD@>5T@TJD{$o>HM#|=AS zVhFmvB*ErF}(b z$lloU83h|%MG*`0=x)$h#l##bw_k|JL(PQCD;4rFXZ7@Qt>QDx)$CSXs01IZuu?5n zM*mk9q~@*y&aY~zJE%^FZu>)dIoGYpvZHSN`&nu1v|-TL?cnqI1Ux_~9dKh_Cv; zH7~Nmy4)N2vQMClRq(?#4|vz) zesG%rEbFfLyW#wb+$>u%15_!LVdefB@gc9u18uwp?bWYV3Xw&=>rN_fx+I2Ku=C0{ z`9#^7RBAEmndS%Y4+FR63!X`x+@~&|*%K zcCWTKu-WS#GK$4)lYoUk+Y)tR;W;h&A*q+DzC7^imIDqm`W%_?$lPkwyE<@Btn_gr zwR)#mo(p}HJ;=T13csv4o+ajf8Thn$&piTxYeTB4X9XfNsnH8stP)Ci?}b{da*e;> zt&I3N_JKDKGdYqmsXogPU8C>#0Bdzx^mw1Ii15zaJ7sJxU|f0YrcC&Sc0?taHVJ64 z#aDK`1nS{tzpUCt-1FwYvR5U+M|1NfeM#i6SwwE3loWVeE0-)S2mYqZzm(1dZ&8Yo zGULG4Vdd4A&V#3^m)9sff<_nMd*IN0L4s)%8@`bIuPZl8sz=?rK3Tg%zpKv60{5Iz zNpp6`XQ$^rbj3LpXL1^@EY`E8hWwlz$3 za(ZP_H{VvPK!dMX9L?1Lw(Bv;n8)={SF4!<2d(EO!^Zu|NkQPK-`dM zJvtA&4>n179l<>wBuS_qL7nt%mRK#?h}dwUN%SDT1MPLeR0MwU&{F)NFl zCZNq4;yDMpus`Ia*t7l6(=*BQj(cB__l2B2y894j4}H#V6vXF#c4>F(v%&RCUp7|`45YuX|@q^WC4HKDByoF%!dkoR8u1!QKc*2;b;9==$= z#33=-37XsJa5DmR(zw=9H4HV?80PpS6#8!*a()mhhTng8@e3)#@g(k%5DgsnxXulM z78`tAuLO@E>bOyYUn4GYr-b~A>pBC6ig@aQA?$ZKEiNwf4tSKs$L$9nPmhT0-G`h! zJAd9}?<>4RWBA>J2FuC?+6 zZZ>kHc`@!iGIBg^mC_p%%!}_lCf}2d`AliO)z!$FRfYeMSN7-k_GQ-sxht?6!>^S5 zflK_C)k5!Td4uQ0d(8i;yx?OtUnhG{&Q!d(FmBJY&?!vzLB|w99H4ewA3i&MS3XwHrkz=`gNFSf=T4v83M~TXvQ3rvmgLTp)7GPgzv&-;xdv!{l>qMo z((0pI7Uz;E(l9@q#KX38xSw$)k%9SU&xOIm=2fRUsz*k|C-0A_k;43Uo&4K0C`NxF zD~^F|S^mQ_wu17?G!y%*;fm;EB7VpCrMAZ8o8#%<=!+VsqOW#mE+6H^nU!7Ifiu3b z0}B_zFIzdnxpPMOsmnr**Q~Oik^wDVXWAR3se-5d_G!ueh!5{xLV{tq*=*zR-H`8SpEva_E3s&$72O>fp4JCC9Du2@mHL z;>h>AwN0tU=4zP7?gc4IQ00VXn*)FMZPd5oV`PT(b$`LJRO#u>j@E>{iE z|8%jh7KuPN^VpI3v%$~6Sbh0kfp=F&kgFfvym%C+==VQ)Zk~_Y18&PX&=4YJ4%CYn zIp_B0OyD-2hnFdWpOS?Jra!qgX;de+ji`_OeT7^%(fEmaJzPDf=qqrE zY?}M@!$sg;x?tg}aOB-&(csf>BO}MyD{l6M0>AIN_oMhPZC^zG&cTIr;r%thEv0)h zrG$ZXku}mQGi$LPv`FPe)ETUURU34XUBMI=<}Q(ILa)aUtYSZK7#TS=as8bRY2;sF`@c64#nXkt z>rTN3w2$SM+hd*Vt@y1`9bA@smbx12VHY%p$=|)v3NWd3IS3x4*!Rdxpnh$zwn-&s za`Hl4%tVppiZC;C=%w~#_&TZzbdeHfPJ2sQ7%D_VHNZF4Tbhv=nZW0R33tF8(tveI zH}Iz2w*A=-{Fw{sk6Ydmo!I?oI*IyW(67~Xf|sw1hu1fNmu$XX$a`-@7R>qaxfs!A zp3nO-;6AfJ@iopmqOi#7`7!9;aar19@N&H2zpuThlvAo3oIB)!UupZi7G>byvHxNN z>iS~#5zaN#i}ba#J;iER9~F>p&!%Es?6IF!o%lM6`_j==%O3`X&ov} z>IHnvrB#v`E^LXPqrc4?;{*2rA4{#W9-ILm@ir0np!D>ee1GNZgdT7Mm6&VwIv=>t zF53PAydL?qRN*Q3KUTj|^Wi7pFI+pRM-TX)Yz!X54__0r-z(qb3m+^#Y<|5Ob@1av zAbIbFOq>|6$R9c|mvOuT-74EEr6oT?JrrpzjIhDF@FAmT3pmGu6Wi%@@GUQ^L2J%VI=c7WT?Q6+3*FhPKe47x1v1 zc4Rar(5grbPqqSYn8%#Q=YyU|j*})>Y4^c5Q)k++yU<_oBy5N8Zh}r4=`y#ULnrs2 zi$M4EWod&?p?kqqjt{58_olBc?8fowd7EbO@!tj?Vu$ur-{1iMr9(1xU|CZASk`EN zP=c3x>0-ZZywuuJKhThSnc)Lp^uPQi0a;M{M)?*NLe_;%u97z|QYPD`ve7!7Oc&kJ zx~N56&@uDU7yQ{2?eWhDy<`TxrBsE{%uvl`bHcuuuf$VWWcWlX>hY0Jm?=#LBc0(; z1DX-R8M=&SLSopuKmE#2tF`1fT62sK8aYmkw_4ekLHe07A5rOOB6ailCh&*<=hP2> zJ9&PcPPZNK@7QEMhW`ohPuO#)`84p)Iw)EXKf3tv=(cJd_`uZD-es+*gUc6+izYz_ z<+4+9HbMtNO0&{-q8@rQ1Y&ogpM0+8A2If{SgPa&L&?`7xlr4 zCb&PNHu!_-c&woLgf2COZ^So;?J!G0^@@abnNP#0Pbhq)IehE>nebU;XKS(6;xSLugh>ZmUsRCDCl zLpbuOX=C)E4*gE+f`4*CWyksxF@iI+@sDo^ zTb?J!kz!WnB*x6MenVoMqaE}NKE96O$NkSc2u`?(`V$Wp@@_(%N^~8*!}o#e8Nk2w z^w-gG!7uU3;!fzmO*)mYgRE@SL#fKP)HU$MiyBX2QE%#ndJFiz;EVdyPPfW%*$*CM z+3gJYx$brMbtXTdhlb$GCTH-Ctu4U=CbbwxrJ>&feqkDPgZMAaj70bb#sgrM%O7`;m2B`a z*587C1p`rie3~0;_{yjp>jdG(-^}1{_R;3)R8$9Bn0D0)EZG%X4Kt?T=`h>&Dd#(O zv)D2ByIjOmk|le@a~IG|bnf>C3;J8U`n^!C`WpgodrBcLjyzAkd!?_KyvO4xVomlE zcd%d}T;$+(2+_SN(G{&UC}|pTg&P|<++9iLm<>Gp=aBd28rZ*JxZ?UITfeO)-%U3S z#GEg#Yvu&TW?{Y;ig3S=`Cd4Sx6appsL^oR>i0*euIPD^hksJ3z(4odI4T4Es>r}J zDn@WIVSUFfp#0dp?qJgM#NENV+-%*?I_v(24`ajc#;9J$9VQn@RdVi8@kRu=`Dsg< z4ccM5+PaJBkNZxcZ*xTTnUt}dT)$x#P?y75?}xy-%-z~c5pkQpt!F5H{vxb`ywyj4 zdP0!LB}DbitL}Bcx32K58}JyUROOQI>>BjmC~`&B8bow>bD?U3@<->ngs-C4X|4{y zFaImlr4aEQc=&=mi~|qDnC}JWnOPXm_CjhoiILz(M`Td zuDJ#Hm`Y8f$zgqIh1GW3TUd9RV!MFNMm}aTvYq4p=mOW&-^rcf1zqXy_Icp>7;#0& zkmm{#QysxWD1c4>P$?yD1&` zw?YSS3@*;60=Ih`@*xTxeENKv3JnGHy?I2%HADBjSV6Txf6@C`j0z3MT<(jpI0^je z-BF}xjeB-)t`+!;H)&6^hI1r92Z8e_?rJ#4Hy?Z;UtT7<5fo^~UBzHG`Kw$m5=QHc z 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 z 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%0AEV~24IJA8C4VqE1r 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

    { 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, /// Tone value increase at 50 % for C, M, Y, K. pub tvi: [f64; 4], /// Grid points of the AToB (4D) and BToA (3D) tables. @@ -60,6 +68,32 @@ pub struct CmykParams { /// encoding and separates to a trace of ink. Off by default, which keeps the bytes of the /// shipped Photocraft profile. pub white_on_node: bool, + /// How the BToA tables bring colours into the gamut. [`GamutMapping::Legacy`] by default, + /// which keeps the bytes of the shipped Photocraft profile. + pub mapping: GamutMapping, +} + +/// How the BToA tables map colours the printer cannot reach. +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum GamutMapping { + /// The shipped Photocraft profile: out-of-gamut colours land on the closest reachable + /// colour (ΔE76); perceptual scales L* onto the device black and compresses Lab chroma; + /// saturation shares the perceptual table. + Legacy, + /// Gamut mapping in Oklab, whose hue lines stay perceptually constant (a CIELAB hue line + /// from a saturated blue toward grey drifts toward purple; an Oklab one does not): + /// + /// * **Colorimetric**: in-gamut colours separate exactly. An out-of-gamut colour takes the + /// closest colour the printer reaches in Oklab, lightness and hue weighted above chroma, + /// and more so the further outside it is; black is generated from the clipped colour, so + /// inks the clip drives to 100 % stay there. + /// * **Perceptual** and **saturation**: the ICC v4 perceptual reference black is mapped + /// onto the device black linearly in XYZ (as black point compensation does) for neutrals, + /// fading out with Oklab chroma, so greys separate as with colorimetric + BPC and colourful + /// colours keep their lightness. Perceptual then compresses Oklab chroma above `knee` × + /// the gamut boundary into the boundary; saturation scales Oklab chroma by `saturation` + /// and clips as colorimetric does. + Oklab { knee: f64, saturation: f64 }, } impl Default for CmykParams { @@ -71,10 +105,12 @@ impl Default for CmykParams { gcr_start: 0.2, k_max: 0.95, gcr_gamma: 1.1, + gcr_curve: Vec::new(), tvi: [0.14, 0.14, 0.14, 0.17], grid_a2b: 11, grid_b2a: 21, white_on_node: false, + mapping: GamutMapping::Legacy, } } } @@ -183,6 +219,11 @@ impl Forward for TableForward { /// Bounded least-squares solve for C, M, Y given K, minimising ΔE76 to `target`, subject to /// `C + M + Y ≤ limit` (projected Levenberg–Marquardt with a numerical Jacobian). fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f64, seeds: &[[f64; 3]]) -> ([f64; 3], f64) { + solve_cmy_by(model, k, limit, seeds, |l| [l[0] - target[0], l[1] - target[1], l[2] - target[2]]) +} + +/// [`solve_cmy`] minimising the norm of `residual(lab)` instead of ΔE76. +fn solve_cmy_by(model: &F, k: f64, limit: f64, seeds: &[[f64; 3]], residual: impl Fn([f64; 3]) -> [f64; 3]) -> ([f64; 3], f64) { let project = |mut x: [f64; 3]| { for _ in 0..4 { for v in &mut x { @@ -202,10 +243,7 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 } x }; - let err = |x: [f64; 3]| { - let l = model.lab([x[0], x[1], x[2], k]); - [l[0] - target[0], l[1] - target[1], l[2] - target[2]] - }; + let err = |x: [f64; 3]| residual(model.lab([x[0], x[1], x[2], k])); let norm2 = |e: [f64; 3]| e[0] * e[0] + e[1] * e[1] + e[2] * e[2]; let mut best = ([0.0; 3], f64::INFINITY); for seed in seeds { @@ -275,13 +313,32 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 const SEEDS: [[f64; 3]; 5] = [[0.3, 0.3, 0.3], [0.05, 0.05, 0.05], [0.8, 0.8, 0.8], [0.9, 0.2, 0.2], [0.2, 0.9, 0.9]]; +/// Black for a gray component `g` (the smallest of C, M, Y without black). +fn gcr(p: &CmykParams, g: f64) -> f64 { + let Some(first) = p.gcr_curve.first() else { + // The Photocraft profile's curve. + return if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + }; + let mut k = first[1]; + for w in p.gcr_curve.windows(2) { + let ([g0, k0], [g1, k1]) = (w[0], w[1]); + if g >= g1 { + k = k1; + } else if g > g0 { + k = k0 + (k1 - k0) * (g - g0) / (g1 - g0); + break; + } + } + k.clamp(0.0, 1.0) +} + /// Colorimetric separation of a relative Lab target: GCR black generation then a CMY solve. pub fn separate(model: &F, p: &CmykParams, target: [f64; 3], warm: Option<[f64; 4]>) -> ([f64; 4], f64) { let mut seeds: Vec<[f64; 3]> = warm.map(|w| vec![[w[0], w[1], w[2]]]).unwrap_or_default(); seeds.extend_from_slice(&SEEDS); let (cmy0, _) = solve_cmy(model, target, 0.0, 3.0, &seeds); let g = cmy0[0].min(cmy0[1]).min(cmy0[2]); - let k = if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + let k = gcr(p, g); let mut seeds2 = vec![[(cmy0[0] - k).max(0.0), (cmy0[1] - k).max(0.0), (cmy0[2] - k).max(0.0)], cmy0]; seeds2.extend_from_slice(&seeds); let (cmy, de) = solve_cmy(model, target, k, (p.tac - k).max(0.0), &seeds2); @@ -383,6 +440,187 @@ impl Gbd { } } +/// ΔE76 under which a separation counts as reaching its target. +const REACH: f64 = 1.5; +/// Oklab chroma beyond any printable colour: the top of the boundary search. +const OKLAB_CHROMA_MAX: f64 = 0.5; +/// Oklab chroma above which the perceptual and saturation tables no longer lift black: they lift +/// neutrals fully, and less the more colourful a colour is. +const LIFT_CHROMA: f64 = 0.1; +/// Weight of lightness and hue against chroma when a colour just outside the gamut is clipped. +const CLIP_WEIGHT: f64 = 1.5; +/// Growth of that weight with the squared share of chroma the clip loses. +const CLIP_WEIGHT_GROWTH: f64 = 200.0; + +// Oklab (Björn Ottosson, 2020): XYZ (D65) → cone response → cube root → Lab-like axes. +const OKLAB_M1: math::Mat3 = + [[0.8189330101, 0.3618667424, -0.1288597137], [0.0329845436, 0.9293118715, 0.0361456387], [0.0482003018, 0.2643662691, 0.6338517070]]; +const OKLAB_M2: math::Mat3 = + [[0.2104542553, 0.7936177850, -0.0040720468], [1.9779984951, -2.4285922050, 0.4505937099], [0.0259040371, 0.7827717662, -0.8086757660]]; +const OKLAB_M1_INV: math::Mat3 = + [[1.2270138511, -0.5577999807, 0.2812561490], [-0.0405801784, 1.1122568696, -0.0716766787], [-0.0763812845, -0.4214819784, 1.5861632204]]; +const OKLAB_M2_INV: math::Mat3 = [[1.0, 0.3963377774, 0.2158037573], [1.0, -0.1055613458, -0.0638541728], [1.0, -0.0894841775, -1.2914855480]]; + +/// The [`GamutMapping::Oklab`] separations of one forward model. +struct OklabMapper<'a, F: Forward + ?Sized> { + model: &'a F, + p: &'a CmykParams, + knee: f64, + saturation: f64, + /// XYZ scale that maps the v4 perceptual reference black onto the device black (the white + /// stays fixed): `v' = a·v + w·(1 − a)`. + black_scale: f64, + to_d65: math::Mat3, + to_d50: math::Mat3, +} + +impl<'a, F: Forward + ?Sized> OklabMapper<'a, F> { + fn new(model: &'a F, p: &'a CmykParams, knee: f64, saturation: f64) -> Self { + let d65 = math::xy_to_xyz(math::D65_XY); + // The darkest neutral the printer reaches. + let (black, _) = separate(model, p, [0.0, 0.0, 0.0], None); + let device = math::lab_to_xyz([model.lab(black)[0], 0.0, 0.0], math::D50)[1]; + let reference = crate::transform::PERCEPTUAL_BLACK[1]; + OklabMapper { + model, + p, + knee, + saturation, + black_scale: (1.0 - device) / (1.0 - reference), + to_d65: math::bradford(math::D50, d65), + to_d50: math::bradford(d65, math::D50), + } + } + + fn oklab(&self, lab: [f64; 3]) -> [f64; 3] { + let xyz = math::apply(&self.to_d65, math::lab_to_xyz(lab, math::D50)); + math::apply(&OKLAB_M2, math::apply(&OKLAB_M1, xyz).map(f64::cbrt)) + } + + fn lab(&self, ok: [f64; 3]) -> [f64; 3] { + let lms = math::apply(&OKLAB_M2_INV, ok).map(|v| v * v * v); + math::xyz_to_lab(math::apply(&self.to_d50, math::apply(&OKLAB_M1_INV, lms)), math::D50) + } + + /// The most chroma (scale of `ok`'s chroma in `[0, top]`) the printer reaches at `ok`'s + /// lightness and hue, and its separation; `None` when even the neutral is out of reach. + fn boundary(&self, ok: [f64; 3], top: f64, warm: Option<[f64; 4]>) -> Option<(f64, [f64; 4])> { + let (grey, d) = separate(self.model, self.p, self.lab([ok[0], 0.0, 0.0]), warm); + if d > REACH { + return None; + } + let (mut lo, mut hi, mut best) = (0.0, top, grey); + for _ in 0..14 { + let mid = 0.5 * (lo + hi); + let (c, d) = separate(self.model, self.p, self.lab([ok[0], ok[1] * mid, ok[2] * mid]), Some(best)); + if d <= REACH { + lo = mid; + best = c; + } else { + hi = mid; + } + } + Some((lo, best)) + } + + /// Colorimetric: exact in gamut; outside, the closest colour the printer reaches in Oklab, + /// lightness and hue weighted above chroma, and more so the further outside the colour is. + fn clip(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let (cmyk, de) = separate(self.model, self.p, lab, warm); + if de <= REACH { + return cmyk; + } + let ok = self.oklab(lab); + let c0 = ok[1].hypot(ok[2]); + // Unit vectors along the colour's chroma and hue directions. + let (u, v) = if c0 > 1e-9 { ([ok[1] / c0, ok[2] / c0], [-ok[2] / c0, ok[1] / c0]) } else { ([1.0, 0.0], [0.0, 1.0]) }; + // Lightness and hue errors weighted by `w`, chroma error by 1; scaled by 100 so the + // solver's step tolerances suit it as they suit ΔE76. + let residual = |w: f64| { + move |l: [f64; 3]| { + let o = self.oklab(l); + let (da, db) = (o[1] - ok[1], o[2] - ok[2]); + [100.0 * w * (o[0] - ok[0]), 100.0 * (da * u[0] + db * u[1]), 100.0 * w * (da * v[0] + db * v[1])] + } + }; + let solve = |w: f64, k: f64, from: [f64; 3]| { + let mut seeds = vec![from]; + seeds.extend_from_slice(&SEEDS); + solve_cmy_by(self.model, k, (self.p.tac - k).max(0.0), &seeds, residual(w)).0 + }; + // A first clip without black measures how far outside the colour is. A colour just + // outside may give up a little lightness and hue to keep its chroma (a red reaches the + // full magenta and yellow edge); one far outside keeps its lightness and hue and loses + // chroma (a saturated blue does not slide along the gamut surface). + let first = solve(CLIP_WEIGHT, 0.0, [cmyk[0], cmyk[1], cmyk[2]]); + let o = self.oklab(self.model.lab([first[0], first[1], first[2], 0.0])); + let loss = if c0 > 1e-9 { (1.0 - o[1].hypot(o[2]) / c0).clamp(0.0, 1.0) } else { 0.0 }; + let w = CLIP_WEIGHT * (1.0 + CLIP_WEIGHT_GROWTH * loss * loss); + let free = solve(w, 0.0, first); + let norm = |c: [f64; 4]| residual(w)(self.model.lab(c)).iter().map(|v| v * v).sum::(); + // Candidates, the closest kept: the separation itself (a colour it nearly reaches stays + // continuous with its in-gamut neighbours), the clip with the separation's black, and + // the clip with black generated from the black-free clip's gray component (inks the + // clip drives to 100 % stay there and black replaces the rest). + let mut best = (norm(cmyk), cmyk); + for k in [cmyk[3], gcr(self.p, free[0].min(free[1]).min(free[2]))] { + for from in [[cmyk[0], cmyk[1], cmyk[2]], free] { + let cmy = solve(w, k, from); + let c = [cmy[0], cmy[1], cmy[2], k]; + let n = norm(c); + if n < best.0 { + best = (n, c); + } + } + } + // Near paper white the gamut narrows to a point: the separation's closest colour keeps + // light tints' chroma where holding lightness would drop them toward bare paper, and + // the table nodes there carry the in-gamut tints between them. The inks blend from the + // clip at L* 85 to the separation at L* 95. + let clip_share = ((95.0 - lab[0]) / 10.0).clamp(0.0, 1.0); + std::array::from_fn(|i| clip_share * best.1[i] + (1.0 - clip_share) * cmyk[i]) + } + + /// Maps the v4 perceptual reference black onto the device black, linearly in XYZ, for + /// neutrals; colourful colours keep their lightness. + fn lift_black(&self, lab: [f64; 3]) -> [f64; 3] { + let ok = self.oklab(lab); + let neutral = (1.0 - ok[1].hypot(ok[2]) / LIFT_CHROMA).clamp(0.0, 1.0); + let a = 1.0 - neutral * (1.0 - self.black_scale); + let xyz = math::lab_to_xyz(lab, math::D50); + math::xyz_to_lab(std::array::from_fn(|i| a * xyz[i] + math::D50[i] * (1.0 - a)), math::D50) + } + + fn perceptual(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let lab = self.lift_black(lab); + let ok = self.oklab(lab); + let c = ok[1].hypot(ok[2]); + if c < 1e-9 { + return self.clip(lab, warm); + } + let Some((s, edge)) = self.boundary(ok, OKLAB_CHROMA_MAX / c, warm) else { + return self.clip(lab, warm); + }; + // Chroma above the knee is compressed smoothly into the boundary chroma `cb`. + let cb = s * c; + let knee = self.knee * cb; + if c <= knee { + return self.clip(lab, warm); + } + let c2 = knee + (cb - knee) * ((c - knee) / (cb - knee).max(1e-9)).tanh(); + let f = c2 / c; + if f >= s { + return edge; + } + self.clip(self.lab([ok[0], ok[1] * f, ok[2] * f]), Some(edge)) + } + + fn saturation(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let ok = self.oklab(self.lift_black(lab)); + self.clip(self.lab([ok[0], ok[1] * self.saturation, ok[2] * self.saturation]), warm) + } +} + fn lab_node_legacy(i: usize, n: usize) -> f64 { i as f64 / (n - 1) as f64 } @@ -419,6 +657,18 @@ fn white_node_curve(l_axis: bool, x: f64) -> f64 { } fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) -> Result { + b2a_table_with(p, |lab, warm| { + let target = match gbd { + Some(g) => g.compress(lab), + None => lab, + }; + separate(model, p, target, warm).0 + }) +} + +/// Samples a BToA table: `node` separates each relative Lab node, warm-started from the +/// previous node along b. +fn b2a_table_with(p: &CmykParams, node: impl Fn([f64; 3], Option<[f64; 4]>) -> [f64; 4] + Sync) -> Result { let n = p.grid_b2a.max(2); let nodes = n * n * n; let step = (n - 1) as f64; @@ -434,11 +684,7 @@ fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) } else { decode_v2([lab_node_legacy(li, n), lab_node_legacy(ai, n), lab_node_legacy(bi, n)]) }; - let target = match gbd { - Some(g) => g.compress(lab), - None => lab, - }; - let (cmyk, _) = if p.white_on_node && lab == [100.0, 0.0, 0.0] { ([0.0; 4], 0.0) } else { separate(model, p, target, warm) }; + let cmyk = if p.white_on_node && lab == [100.0, 0.0, 0.0] { [0.0; 4] } else { node(lab, warm) }; warm = Some(cmyk); out.extend(cmyk.map(|v| v as f32)); } @@ -460,6 +706,15 @@ fn check_grids(p: &CmykParams) -> Result<(), CmsError> { if p.white_on_node && p.grid_b2a.is_multiple_of(2) { return Err(invalid_arg(format!("white on a node needs an odd BToA grid, not {}", p.grid_b2a))); } + let valid = |v: &[f64; 2]| v.iter().all(|x| (0.0..=1.0).contains(x)); + if !p.gcr_curve.iter().all(valid) || p.gcr_curve.windows(2).any(|w| w[1][0] <= w[0][0]) { + return Err(invalid_arg(format!("black generation curve {:?} needs points in [0, 1] with increasing gray components", p.gcr_curve))); + } + if let GamutMapping::Oklab { knee, saturation } = p.mapping + && !((0.0..1.0).contains(&knee) && saturation.is_finite() && saturation > 0.0) + { + return Err(invalid_arg(format!("Oklab gamut mapping needs a knee in [0, 1) and a positive saturation, not {knee} and {saturation}"))); + } Ok(()) } @@ -518,11 +773,23 @@ pub fn cmyk_profile_from_model(model: &F, paper: [f64; 3], } fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &CmykParams) -> Result { - let gbd = Gbd::new(model, p); - let colorimetric = b2a_table(model, p, None)?; - let perceptual = b2a_table(model, p, Some(&gbd))?; + let (perceptual, colorimetric, saturation) = match p.mapping { + GamutMapping::Legacy => { + let gbd = Gbd::new(model, p); + let colorimetric = b2a_table(model, p, None)?; + let perceptual = b2a_table(model, p, Some(&gbd))?; + (perceptual.clone(), colorimetric, perceptual) + } + GamutMapping::Oklab { knee, saturation } => { + let m = OklabMapper::new(model, p, knee, saturation); + let colorimetric = b2a_table_with(p, |lab, warm| m.clip(lab, warm))?; + let perceptual = b2a_table_with(p, |lab, warm| m.perceptual(lab, warm))?; + let saturation = b2a_table_with(p, |lab, warm| m.saturation(lab, warm))?; + (perceptual, colorimetric, saturation) + } + }; let a2b = lut16(a2b, false); - let (b0, b1) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node)); + let (b0, b1, b2) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node), lut16(saturation, p.white_on_node)); Ok(Profile { version: (4, 0x30), class: ProfileClass::Output, @@ -538,7 +805,7 @@ fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &C trc: None, gray_trc: None, a2b: [Some(a2b.clone()), Some(a2b.clone()), Some(a2b)], - b2a: [Some(b0.clone()), Some(b1), Some(b0)], + b2a: [Some(b0), Some(b1), Some(b2)], bytes: None, hash: Default::default(), } @@ -576,6 +843,46 @@ mod tests { } } + #[test] + fn oklab_mapping_refuses_bad_parameters() { + for (knee, saturation) in [(1.0, 1.0), (-0.1, 1.0), (f64::NAN, 1.0), (0.5, 0.0), (0.5, f64::INFINITY), (0.5, f64::NAN)] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, mapping: GamutMapping::Oklab { knee, saturation }, ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "knee {knee}, saturation {saturation}"); + } + } + + #[test] + fn black_generation_curve() { + let p = CmykParams { gcr_curve: vec![[0.0, 0.0], [0.5, 0.2], [1.0, 0.9]], ..CmykParams::default() }; + for (g, k) in [(-1.0, 0.0), (0.0, 0.0), (0.25, 0.1), (0.5, 0.2), (0.75, 0.55), (1.0, 0.9), (2.0, 0.9)] { + assert!((gcr(&p, g) - k).abs() < 1e-12, "g {g}: {} != {k}", gcr(&p, g)); + } + for curve in [vec![[0.5, 0.2], [0.5, 0.3]], vec![[0.5, 0.2], [0.2, 0.3]], vec![[0.0, 1.5]], vec![[f64::NAN, 0.0]]] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, gcr_curve: curve.clone(), ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "{curve:?}"); + } + } + + #[test] + fn oklab_round_trips() { + let m = CmykModel::coated(CmykParams::default().tvi); + let p = CmykParams::default(); + let mapper = OklabMapper::new(&m, &p, 0.65, 1.05); + for lab in [[50.0, 0.0, 0.0], [44.0, 63.7, 47.0], [31.9, 32.9, -76.8], [90.0, -5.0, 80.0]] { + let back = mapper.lab(mapper.oklab(lab)); + // The published matrices carry 10 digits, so the inverses are exact to about 1e-5 ΔE. + assert!(math::delta_e76(lab, back) < 1e-3, "{lab:?} -> {back:?}"); + } + } + + #[test] + fn oklab_profile_has_three_tables() { + let p = CmykParams { grid_a2b: 5, grid_b2a: 5, mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; + let profile = cmyk_profile(&p).unwrap(); + let [Some(b0), Some(b1), Some(b2)] = &profile.b2a else { panic!("missing BToA tables") }; + assert!(b0 != b1 && b0 != b2, "perceptual shares a table"); + } + #[test] fn separation_hits_in_gamut_targets() { let m = CmykModel::coated(CmykParams::default().tvi); diff --git a/crates/cms/src/transform.rs b/crates/cms/src/transform.rs index c4f6e11cc..38a3223d9 100644 --- a/crates/cms/src/transform.rs +++ b/crates/cms/src/transform.rs @@ -46,7 +46,7 @@ const OUT_TABLE: usize = GpuMatrixShaper::OUTPUT_ENTRIES; const _: () = assert!(OUT_TABLE.is_power_of_two()); /// ICC v4 perceptual reference medium black (ICC.1:2010 §6.3.4.4), XYZ. -const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; +pub(crate) const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; /// Accelerated representation of a transform. #[derive(Debug)] diff --git a/crates/cms/tests/fogra39.rs b/crates/cms/tests/fogra39.rs index f958ffc51..d08e3bae6 100644 --- a/crates/cms/tests/fogra39.rs +++ b/crates/cms/tests/fogra39.rs @@ -12,7 +12,7 @@ //! ([`synth::cmyk_profile_from_model`]). use craft_cms::math::{self, delta_e2000}; -use craft_cms::synth::{self, CmykParams, Forward}; +use craft_cms::synth::{self, CmykParams, Forward, GamutMapping}; use craft_cms::{Builtin, Intent, Profile, Transform}; const DATA: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/FOGRA39.txt"); @@ -346,8 +346,10 @@ fn regen_coated_fogra39() { description: Builtin::CoatedFogra39.description().into(), copyright: craft_cms::builtin::COATED_FOGRA39_COPYRIGHT.into(), tac: 3.3, + gcr_curve: vec![[0.0, 0.0], [0.2, 0.05], [0.5, 0.205], [0.67, 0.5], [1.0, 0.95]], grid_b2a: 33, white_on_node: true, + mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; let profile = synth::cmyk_profile_from_model(&f, paper(&p), ¶ms).unwrap(); @@ -564,3 +566,60 @@ fn stand_in_separations_respect_the_ink_limit() { } } } + +/// sRGB patches and their separations by the reference application (Convert to Profile to +/// Coated FOGRA39, dither on), CMYK % per intent: relative + BPC, relative, perceptual, +/// saturation, absolute. Measured for storytold/photocraft#14267. +const REFERENCE_SEPARATIONS: [([u8; 3], [[f32; 4]; 5]); 3] = [ + ( + [200, 30, 30], + [[14.5, 97.7, 95.3, 4.3], [13.3, 100.0, 100.0, 5.5], [18.0, 96.9, 92.9, 8.6], [14.9, 100.0, 100.0, 5.9], [8.6, 100.0, 100.0, 2.4]], + ), + ([30, 60, 200], [[91.8, 75.3, 0.0, 0.0], [94.5, 76.5, 0.0, 0.0], [94.5, 77.7, 0.0, 0.0], [93.7, 76.9, 0.0, 0.0], [92.6, 74.9, 0.0, 0.0]]), + ( + [128, 128, 128], + [[49.0, 38.4, 38.4, 20.0], [49.8, 39.2, 38.8, 21.2], [49.0, 38.4, 38.4, 20.0], [49.0, 38.4, 38.4, 20.0], [46.7, 36.9, 38.4, 18.4]], + ), +]; + +const SEPARATION_INTENTS: [(Intent, bool); 5] = [ + (Intent::RelativeColorimetric, true), + (Intent::RelativeColorimetric, false), + (Intent::Perceptual, true), + (Intent::Saturation, true), + (Intent::AbsoluteColorimetric, false), +]; + +fn separation(intent: Intent, bpc: bool, rgb: [u8; 3]) -> [f32; 4] { + let t = Transform::new(Builtin::Srgb.profile(), fogra39(), intent, bpc).unwrap(); + let mut o = [0.0f32; 4]; + t.eval(&rgb.map(|v| v as f32 / 255.0), &mut o).unwrap(); + o.map(|v| v * 100.0) +} + +/// sRGB → Coated FOGRA39 matches the reference application's inks on a red, a saturated blue +/// and a mid grey for every intent. Most land within 2 % per ink; red at the magenta–yellow +/// edge lands between table nodes that are and are not clipped, which costs up to 2.2 % with +/// the 33³ BToA tables. +#[test] +fn separates_like_the_reference_application() { + let mut worst = 0.0f32; + for (rgb, want) in REFERENCE_SEPARATIONS { + for ((intent, bpc), want) in SEPARATION_INTENTS.into_iter().zip(want) { + let got = separation(intent, bpc, rgb); + let diff = (0..4).map(|i| (got[i] - want[i]).abs()).fold(0.0f32, f32::max); + eprintln!("{rgb:?} {intent:?} bpc {bpc}: {got:.1?} reference {want:?} (max {diff:.1})"); + worst = worst.max(diff); + } + } + assert!(worst <= 2.5, "worst ink difference {worst} %"); +} + +/// Saturation has its own table: a red separates with more magenta and yellow than +/// perceptual, whose chroma compression takes some back. +#[test] +fn saturation_and_perceptual_separate_differently() { + let red = [200, 30, 30]; + let (perceptual, saturation) = (separation(Intent::Perceptual, true, red), separation(Intent::Saturation, true, red)); + assert!(saturation[1] > perceptual[1] + 1.0 && saturation[2] > perceptual[2] + 1.0, "perceptual {perceptual:?}, saturation {saturation:?}"); +} diff --git a/crates/prepress/src/output.rs b/crates/prepress/src/output.rs index 9bc9a0296..428597d33 100644 --- a/crates/prepress/src/output.rs +++ b/crates/prepress/src/output.rs @@ -191,10 +191,12 @@ mod tests { let p = Plates { inks, unseparated: Vec::new(), width: 2, height: 1, dpi: 72.0, conversion: Conversion::DeviceFormulas, planes }; let output = Output::new(fogra39(), fogra39(), Intent::RelativeColorimetric, false).unwrap(); let cmyk = p.composite_to(&[], &output); - // Magenta's round trip through the profile adds a little yellow. - assert!(near(&cmyk[0..4], &[255, 255, 8, 0], 8), "spot over cyan: {:?}", &cmyk[0..4]); - assert!(near(&cmyk[4..8], &[0, 255, 8, 0], 8), "spot alone: {:?}", &cmyk[4..8]); - assert!(near(&p.composite_to(&[true, true, true, true, false], &output)[0..4], &[255, 0, 0, 0], 6), "spot hidden"); + // The press profile's round trip: its BToA tables generate their own black, so a + // full-tone ink comes back a little short with a trace of black, as a printer would + // separate it. The tolerance is the profile's own round trip, not an exchange total. + assert!(near(&cmyk[0..4], &[250, 247, 17, 2], 8), "spot over cyan: {:?}", &cmyk[0..4]); + assert!(near(&cmyk[4..8], &[8, 247, 11, 1], 8), "spot alone: {:?}", &cmyk[4..8]); + assert!(near(&p.composite_to(&[true, true, true, true, false], &output)[0..4], &[250, 7, 6, 1], 8), "spot hidden"); } #[test] From 7107fb8daf5a1255706bc13da805b36fd3b9e9b6 Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Tue, 17 Nov 2026 14:14:51 -0500 Subject: [PATCH 78/97] =?UTF-8?q?cms:=20keep=20black-only=20CMYK=20black-o?= =?UTF-8?q?nly=20across=20CMYK=20=E2=86=92=20CMYK=20transforms=20(#2029)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * cms: keep black-only CMYK black-only across CMYK to CMYK transforms Opt-in BlackPreserving: a colour with exactly zero C, M and Y converts to exactly (0, 0, 0, K'), K' matching the source K-only L* in the destination (both ramps sampled at construction with the transform's intent and BPC). Transform itself is unchanged. Adapted from icccer (MIT, same author) black_preserve.rs at 08ca16ab. Co-Authored-By: Claude Opus 5.5 * cms: map black past the destination maximum to exactly K = 1 between samples Co-Authored-By: Claude Opus 5.5 * cms: README says the K-ramp check is sampled Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: KenM76 Co-authored-by: Claude Opus 5.5 --- crates/cms/README.md | 6 + crates/cms/src/black.rs | 205 ++++++++++++++++++++++++++++++++++ crates/cms/src/black_tests.rs | 149 ++++++++++++++++++++++++ crates/cms/src/lib.rs | 2 + 4 files changed, 362 insertions(+) create mode 100644 crates/cms/src/black.rs create mode 100644 crates/cms/src/black_tests.rs diff --git a/crates/cms/README.md b/crates/cms/README.md index 71f3146d5..cbee391cd 100644 --- a/crates/cms/README.md +++ b/crates/cms/README.md @@ -81,6 +81,12 @@ Buffers are checked once per call, before any pixel is written. the exact and float paths compare each pixel with white; all other colours are left as the profiles give them. With a profile whose white falls between its nodes (`coated-cmyk`: 0.4 % C), the last step to white is that much larger than its neighbours. +* Black preservation (opt-in, `BlackPreserving`): for CMYK → CMYK, a colour with exactly zero + C, M and Y comes out as exactly `(0, 0, 0, K')`, where `K'` is the destination black whose + K-only L* equals the source's (both K ramps sampled at 1024 points when the transform is + built, with its intent and BPC). The test is exact zero, so an input with any chromatic ink + takes the ordinary path. Absolute colorimetric, non-CMYK profiles and K ramps that reverse at + one of the 1024 samples are refused (a reversal between samples is not detected). ## Built-in profiles (all CC0-1.0, generated by this crate) diff --git a/crates/cms/src/black.rs b/crates/cms/src/black.rs new file mode 100644 index 000000000..f80defeef --- /dev/null +++ b/crates/cms/src/black.rs @@ -0,0 +1,205 @@ +//! K-only black preservation for CMYK → CMYK transforms. +//! +//! A CMYK → CMYK transform goes through the three-component PCS, so black alone (C = M = Y = 0) +//! comes out as a four-ink mix. ISO 32000-2 §8.6.5.7 notes that this loses fidelity in the black +//! component. ICC defines no black preservation; this is a named policy the caller opts into. +//! +//! [`BlackPreserving`] converts like its [`Transform`], except that a colour with exactly zero +//! cyan, magenta and yellow becomes exactly `(0, 0, 0, K')`. `K'` is the destination black whose +//! K-only L* equals the source's, both measured to Lab with the transform's own intent and BPC +//! setting: both ramps are sampled once, at construction, and the destination ramp is inverted. +//! A source black darker than the destination's maximum black maps to K = 1. The test is exact zero, so the transform is discontinuous at C = M = Y = 0: an input +//! with any chromatic ink takes the ordinary path. + +use crate::transform::{Transform, TransformOptions}; +use crate::{Builtin, CmsError, ColorSpace, Intent, Profile, invalid_arg}; + +/// Samples along each K-only ramp. Linear interpolation between samples of a smooth ramp is far +/// below the 16-bit quantum. +const K_SAMPLES: usize = 1024; +/// Slack for the monotonicity checks (L* units, K units). +const MONOTONIC_EPS: f64 = 1e-6; + +/// A CMYK → CMYK transform that keeps black-only colours black-only. +#[derive(Debug)] +pub struct BlackPreserving { + transform: Transform, + /// Destination K for source K at `i / (K_SAMPLES - 1)`; `K_SAMPLES` values in `[0, 1]`. + curve: Vec, + /// Source K from which the source black is at least as dark as the destination's darkest: + /// mapped to exactly 1. Infinite when the destination's black is the darker. + saturate: f32, + /// The mapping at the 256 8-bit source codes, already quantised. + curve8: [u8; 256], +} + +impl BlackPreserving { + /// Transform from `src` to `dst` with black preservation. + /// + /// Errors with [`CmsError::InvalidArgument`] when either profile is not CMYK or the intent is + /// absolute colorimetric (which reproduces the source's paper and black, so there is no + /// black to map), and with [`CmsError::Unsupported`] when a profile's K-only ramp is not + /// monotonic at its 1024 samples (black that gets lighter as K rises has no equal-lightness + /// inverse; a reversal between samples is not detected). Other errors + /// are those of [`Transform::with_options`]. + pub fn new(src: &Profile, dst: &Profile, opts: TransformOptions) -> Result { + if src.color_space != ColorSpace::Cmyk || dst.color_space != ColorSpace::Cmyk { + return Err(invalid_arg("black preservation needs CMYK source and destination profiles")); + } + if opts.intent == Intent::AbsoluteColorimetric { + return Err(invalid_arg("black preservation does not apply to absolute colorimetric")); + } + let transform = Transform::with_options(src, dst, opts)?; + let src_l = k_ramp_lightness(src, opts)?; + let dst_l = k_ramp_lightness(dst, opts)?; + let (curve, saturate) = k_curve(&src_l, &dst_l)?; + let mut curve8 = [0u8; 256]; + for (code, slot) in curve8.iter_mut().enumerate() { + *slot = quantise(map(&curve, saturate, code as f32 / 255.0), 255.0) as u8; + } + Ok(BlackPreserving { transform, curve, saturate, curve8 }) + } + + /// The ordinary transform, which every colour with chromatic ink goes through. Converting with + /// it directly does not preserve black. + pub fn transform(&self) -> &Transform { + &self.transform + } + + /// Destination K for a black-only source colour of `k` (clamped to `[0, 1]`). + pub fn map_k(&self, k: f32) -> f32 { + map(&self.curve, self.saturate, k) + } + + /// Exact evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Lookup-table evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval_fast(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval_fast(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Converts float pixels; layout and errors as in [`Transform::convert_f32`]. + pub fn convert_f32(&self, src: &[f32], src_stride: usize, dst: &mut [f32], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_f32(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + self.patch_one(s, d); + } + Ok(()) + } + + /// Converts 8-bit pixels; layout and errors as in [`Transform::convert_u8`]. + pub fn convert_u8(&self, src: &[u8], src_stride: usize, dst: &mut [u8], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u8(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = self.curve8[usize::from(*k)]; + } + } + Ok(()) + } + + /// Converts 16-bit pixels; layout and errors as in [`Transform::convert_u16`]. + pub fn convert_u16(&self, src: &[u16], src_stride: usize, dst: &mut [u16], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u16(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = quantise(self.map_k(f32::from(*k) / 65535.0), 65535.0) as u16; + } + } + Ok(()) + } + + fn patch_one(&self, input: &[f32], out: &mut [f32]) { + if let ([0.0, 0.0, 0.0, k, ..], [c, m, y, kd, ..]) = (input, out) { + (*c, *m, *y) = (0.0, 0.0, 0.0); + *kd = self.map_k(*k); + } + } +} + +/// The sampled mapping from the source to the destination K-only ramp, and the source K at +/// which the destination's darkest black is reached (the `saturate` field). +fn k_curve(src_l: &[f64], dst_l: &[f64]) -> Result<(Vec, f32), CmsError> { + let curve: Vec = src_l.iter().map(|&l| invert(dst_l, l) as f32).collect(); + if !curve.windows(2).all(|w| f64::from(w[0]) - f64::from(w[1]) <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: the K mapping is not monotonic".into())); + } + let saturate = match (src_l.last(), dst_l.last()) { + (Some(&s), Some(&d)) if s < d => invert(src_l, d) as f32, + _ => f32::INFINITY, + }; + Ok((curve, saturate)) +} + +/// L* of `p`'s K-only ramp at `K_SAMPLES` points, light to dark; refused when it is not +/// non-increasing. +fn k_ramp_lightness(p: &Profile, opts: TransformOptions) -> Result, CmsError> { + let to_lab = Transform::with_options(p, Builtin::LabD50.profile(), TransformOptions { precise_float: true, ..opts })?; + let mut ramp = Vec::with_capacity(K_SAMPLES); + let mut lab = [0.0f32; 3]; + for i in 0..K_SAMPLES { + let k = i as f32 / (K_SAMPLES - 1) as f32; + to_lab.eval(&[0.0, 0.0, 0.0, k], &mut lab)?; + ramp.push(f64::from(lab[0]) * 100.0); + } + if !ramp.iter().all(|l| l.is_finite()) || !ramp.windows(2).all(|w| w[1] - w[0] <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: a K-only ramp is not monotonic".into())); + } + Ok(ramp) +} + +/// The K in `[0, 1]` at which the non-increasing `ramp` reaches `target`, clamped to its ends. +fn invert(ramp: &[f64], target: f64) -> f64 { + let (Some(&first), Some(&last)) = (ramp.first(), ramp.last()) else { return 0.0 }; + if ramp.len() < 2 || target >= first { + return 0.0; + } + if target <= last { + return 1.0; + } + // ramp[lo] > target >= ramp[hi] + let (mut lo, mut hi) = (0usize, ramp.len() - 1); + while hi - lo > 1 { + let mid = lo + (hi - lo) / 2; + if ramp.get(mid).is_some_and(|&v| v > target) { + lo = mid; + } else { + hi = mid; + } + } + let (a, b) = (ramp.get(lo).copied().unwrap_or(first), ramp.get(hi).copied().unwrap_or(last)); + let t = if a - b > MONOTONIC_EPS { (a - target) / (a - b) } else { 0.0 }; + (lo as f64 + t) / (ramp.len() - 1) as f64 +} + +/// Linear interpolation in `curve` (samples over `[0, 1]`) at `k`, clamped; 1 from `saturate`. +fn map(curve: &[f32], saturate: f32, k: f32) -> f32 { + let Some(&last) = curve.last() else { return 0.0 }; + let k = if k.is_nan() { 0.0 } else { k.clamp(0.0, 1.0) }; + if k >= saturate { + return 1.0; + } + let x = k * (curve.len() - 1) as f32; + let i = x.floor() as usize; + match (curve.get(i), curve.get(i + 1)) { + (Some(&a), Some(&b)) => a + (b - a) * (x - i as f32), + _ => last, + } +} + +fn quantise(v: f32, max: f32) -> f32 { + (v.clamp(0.0, 1.0) * max + 0.5).floor() +} + +#[cfg(test)] +#[path = "black_tests.rs"] +mod tests; diff --git a/crates/cms/src/black_tests.rs b/crates/cms/src/black_tests.rs new file mode 100644 index 000000000..8752cdaa2 --- /dev/null +++ b/crates/cms/src/black_tests.rs @@ -0,0 +1,149 @@ +use super::*; + +fn coated() -> &'static Profile { + Builtin::CoatedCmyk.profile() +} +fn fogra() -> &'static Profile { + Builtin::CoatedFogra39.profile() +} +fn opts() -> TransformOptions { + TransformOptions::default() +} + +/// L* of a CMYK colour under `p`, measured as the transform with `o` measures it. +fn lightness(p: &Profile, o: TransformOptions, cmyk: [f32; 4]) -> f32 { + let t = Transform::with_options(p, Builtin::LabD50.profile(), o).unwrap(); + let mut lab = [0.0f32; 3]; + t.eval(&cmyk, &mut lab).unwrap(); + lab[0] * 100.0 +} + +#[test] +fn the_plain_transform_turns_black_into_four_inks() { + // What the policy is for: without it, black alone gains chromatic ink across presses. + let t = Transform::with_options(coated(), fogra(), opts()).unwrap(); + let mut out = [0.0f32; 4]; + t.eval(&[0.0, 0.0, 0.0, 0.5], &mut out).unwrap(); + assert!(out[..3].iter().any(|v| *v > 0.01), "{out:?}"); +} + +#[test] +fn black_only_stays_black_only_on_every_path() { + for (src, dst) in [(coated(), fogra()), (fogra(), coated()), (fogra(), fogra())] { + let bp = BlackPreserving::new(src, dst, opts()).unwrap(); + for k in [0.0f32, 0.1, 0.5, 0.9, 1.0] { + for fast in [false, true] { + let mut out = [1.0f32; 4]; + if fast { bp.eval_fast(&[0.0, 0.0, 0.0, k], &mut out) } else { bp.eval(&[0.0, 0.0, 0.0, k], &mut out) }.unwrap(); + assert_eq!(out[..3], [0.0; 3], "k {k} fast {fast}"); + assert_eq!(out[3], bp.map_k(k)); + } + } + let src8: Vec = (0..=255u8).flat_map(|k| [0, 0, 0, k, 7]).collect(); + let mut dst8 = vec![0u8; src8.len()]; + bp.convert_u8(&src8, 5, &mut dst8, 5, true).unwrap(); + for (k, px) in dst8.as_chunks::<5>().0.iter().enumerate() { + assert_eq!(px[..3], [0; 3], "u8 k {k}"); + assert!((f32::from(px[3]) - bp.map_k(k as f32 / 255.0) * 255.0).abs() <= 0.5, "u8 k {k}: {}", px[3]); + assert_eq!(px[4], 7, "extra channel copied"); + } + let src16: Vec = (0..=64u16).flat_map(|k| [0, 0, 0, k * 1023]).collect(); + let mut dst16 = vec![0u16; src16.len()]; + bp.convert_u16(&src16, 4, &mut dst16, 4, false).unwrap(); + for (px, k) in dst16.as_chunks::<4>().0.iter().zip(src16.as_chunks::<4>().0) { + assert_eq!(px[..3], [0; 3], "u16 {k:?}"); + assert!((f32::from(px[3]) - bp.map_k(f32::from(k[3]) / 65535.0) * 65535.0).abs() <= 0.5, "u16 {k:?}: {}", px[3]); + } + let srcf: Vec = (0..=10).flat_map(|k| [0.0, 0.0, 0.0, k as f32 / 10.0]).collect(); + let mut dstf = vec![0.0f32; srcf.len()]; + bp.convert_f32(&srcf, 4, &mut dstf, 4, false).unwrap(); + for (px, k) in dstf.as_chunks::<4>().0.iter().zip(srcf.as_chunks::<4>().0) { + assert_eq!(*px, [0.0, 0.0, 0.0, bp.map_k(k[3])], "f32 {k:?}"); + } + } +} + +#[test] +fn the_destination_black_matches_the_source_lightness() { + // Measured worst error over 201 K steps, both directions, both intents, BPC on and off: + // 0.007 L*. + for intent in [Intent::RelativeColorimetric, Intent::Perceptual] { + for bpc in [true, false] { + let o = TransformOptions { intent, bpc, ..opts() }; + for (src, dst) in [(coated(), fogra()), (fogra(), coated())] { + let bp = BlackPreserving::new(src, dst, o).unwrap(); + let dst_black = lightness(dst, o, [0.0, 0.0, 0.0, 1.0]); + for k in [0.1f32, 0.3, 0.5, 0.7, 0.9, 1.0] { + let want = lightness(src, o, [0.0, 0.0, 0.0, k]); + if want <= dst_black { + assert_eq!(bp.map_k(k), 1.0, "darker than the destination's black clamps to K = 1"); + continue; + } + let got = lightness(dst, o, [0.0, 0.0, 0.0, bp.map_k(k)]); + assert!((got - want).abs() < 0.02, "{intent:?} bpc {bpc} k {k}: L* {got} for {want}"); + } + assert_eq!(bp.map_k(0.0), 0.0, "paper stays paper"); + assert!(bp.map_k(1.0) > 0.95, "full black stays near full black: {}", bp.map_k(1.0)); + assert!(bp.map_k(0.25) < bp.map_k(0.75)); + } + } + } + let same = BlackPreserving::new(fogra(), fogra(), opts()).unwrap(); + for k in [0.0f32, 0.2, 0.6, 1.0] { + assert!((same.map_k(k) - k).abs() < 1e-3, "{k} -> {}", same.map_k(k)); + } +} + +#[test] +fn colours_with_any_chromatic_ink_take_the_ordinary_path() { + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for input in [[1e-6f32, 0.0, 0.0, 0.5], [0.0, 0.2, 0.0, 0.5], [0.3, 0.3, 0.3, 0.0], [0.0, 0.0, 1.0, 1.0]] { + let (mut a, mut b) = ([0.0f32; 4], [0.0f32; 4]); + bp.eval(&input, &mut a).unwrap(); + bp.transform().eval(&input, &mut b).unwrap(); + assert_eq!(a, b, "{input:?}"); + } + let src = [1u8, 0, 0, 128, 0, 1, 0, 128]; + let (mut a, mut b) = ([0u8; 8], [0u8; 8]); + bp.convert_u8(&src, 4, &mut a, 4, false).unwrap(); + bp.transform().convert_u8(&src, 4, &mut b, 4, false).unwrap(); + assert_eq!(a, b); +} + +#[test] +fn refusals_and_hostile_values() { + let srgb = Builtin::Srgb.profile(); + assert!(matches!(BlackPreserving::new(srgb, fogra(), opts()), Err(CmsError::InvalidArgument(_)))); + assert!(matches!(BlackPreserving::new(fogra(), srgb, opts()), Err(CmsError::InvalidArgument(_)))); + let abs = TransformOptions { intent: Intent::AbsoluteColorimetric, ..opts() }; + assert!(matches!(BlackPreserving::new(fogra(), coated(), abs), Err(CmsError::InvalidArgument(_)))); + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for k in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, -1.0, 2.0] { + assert!((0.0..=1.0).contains(&bp.map_k(k)), "{k}"); + } + let mut out = [0.0f32; 4]; + assert!(bp.eval(&[0.0; 3], &mut out).is_err(), "short input"); + assert!(bp.convert_u8(&[0, 0, 0, 9, 0], 4, &mut [0u8; 4], 4, false).is_err(), "partial pixel"); + assert_eq!(invert(&[], 50.0), 0.0); + assert_eq!(invert(&[100.0], 50.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], 150.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], -5.0), 1.0); + assert!((invert(&[100.0, 50.0, 0.0], 25.0) - 0.75).abs() < 1e-12); + assert_eq!(map(&[], f32::INFINITY, 0.5), 0.0); +} + +#[test] +fn black_beyond_the_destination_maximum_maps_to_full_black_between_samples() { + // Source L* = 100 (1 - K), destination L* = 100 - 50 K: from K = 0.5 the source is darker + // than any destination black, and 0.5 falls between the 1024 samples. + let ramp = |f: fn(f64) -> f64| (0..K_SAMPLES).map(|i| f(i as f64 / (K_SAMPLES - 1) as f64)).collect::>(); + let (src, dst) = (ramp(|k| 100.0 * (1.0 - k)), ramp(|k| 100.0 - 50.0 * k)); + let (curve, saturate) = k_curve(&src, &dst).unwrap(); + assert!((saturate - 0.5).abs() < 1e-6, "{saturate}"); + for k in [0.5001f32, 0.6, 1.0] { + assert_eq!(map(&curve, saturate, k), 1.0, "{k}"); + } + assert!((map(&curve, saturate, 0.25) - 0.5).abs() < 1e-4); + let (_, never) = k_curve(&dst, &src).unwrap(); + assert_eq!(never, f32::INFINITY, "a lighter source never saturates"); +} diff --git a/crates/cms/src/lib.rs b/crates/cms/src/lib.rs index b082f67a5..38f926dcf 100644 --- a/crates/cms/src/lib.rs +++ b/crates/cms/src/lib.rs @@ -19,6 +19,7 @@ //! CIE 15, and Adobe's published black point compensation paper. #![forbid(unsafe_code)] +pub mod black; pub mod builtin; mod builtin_v2; pub mod clut; @@ -39,6 +40,7 @@ pub mod transform; mod write; pub mod write_v2; +pub use black::BlackPreserving; pub use builtin::Builtin; pub use clut::Clut; pub use curve::Curve; From e1d883e444fe23a518feeab9f9c6b8a96774731b Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Tue, 17 Nov 2026 14:23:06 -0500 Subject: [PATCH 79/97] psd: share legacy guide record prefix decoding Adapt PhotoCraft parse_guides from 16941f7198, retaining signed-position semantics from 1a54384d80. Allocation-free framing preserves complete-prefix recovery. Co-authored-by: Dylan M. Taylor --- crates/psd/src/guides.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/crates/psd/src/guides.rs b/crates/psd/src/guides.rs index 5f100c480..a9d566e21 100644 --- a/crates/psd/src/guides.rs +++ b/crates/psd/src/guides.rs @@ -5,6 +5,29 @@ //! Unknown direction values retain PhotoCraft's vertical interpretation. Grid cycles, reserved //! bytes and trailing data are not interpreted. Resource 1097 remains opaque except its count. +/// One legacy Grid and Guides record (resource 1032). +/// Position is signed 1/32 pixel; direction 1 is horizontal, all others vertical. +/// Adapted from PhotoCraft's reader by Brandon Thomas and writer by aiongg. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct GuideV1 { + /// Signed position in units of 1/32 pixel. + pub location: i32, + /// Raw direction byte, retained without normalization. + pub direction: u8, +} + +/// Read complete legacy records, preserving the valid prefix on truncation. +/// Matches PhotoCraft recovery: version/grid fields are ignored. Declared counts +/// cannot drive allocation or scanning beyond complete records in the input. +pub fn parse_v1_prefix(data: &[u8]) -> impl Iterator + '_ { + let count = be_u32(data, 12).unwrap_or(0); + data.get(16..) + .unwrap_or_default() + .chunks_exact(5) + .zip(0..count) + .map(|(g, _)| GuideV1 { location: i32::from_be_bytes([g[0], g[1], g[2], g[3]]), direction: g[4] }) +} + /// Grid and Guides version 2 resource ID. pub const GUIDES_V2: u16 = 1092; /// Associated guide identifiers resource ID. From d55beb8f612bcedfe2af1907b8d2bef9fc548187 Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 14:23:06 -0500 Subject: [PATCH 80/97] psd: share legacy guide header and record encoding Extract PhotoCraft guide framing from 2aa88b0956; leave rounding and document ordering with callers. Add fixed-byte and hostile-prefix coverage. Co-authored-by: Dylan M. Taylor --- crates/psd/src/guides.rs | 45 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/crates/psd/src/guides.rs b/crates/psd/src/guides.rs index a9d566e21..f122c7805 100644 --- a/crates/psd/src/guides.rs +++ b/crates/psd/src/guides.rs @@ -16,6 +16,23 @@ pub struct GuideV1 { pub direction: u8, } +impl GuideV1 { + /// Encode exactly one five-byte record without allocation. + pub fn to_bytes(self) -> [u8; 5] { + let p = self.location.to_be_bytes(); + [p[0], p[1], p[2], p[3], self.direction] + } +} + +/// Encode a legacy resource header. Grid cycles and count are caller supplied. +pub fn header_v1(horizontal_cycle: u32, vertical_cycle: u32, count: u32) -> [u8; 16] { + let mut out = [0; 16]; + for (chunk, value) in out.chunks_exact_mut(4).zip([1u32, horizontal_cycle, vertical_cycle, count]) { + chunk.copy_from_slice(&value.to_be_bytes()); + } + out +} + /// Read complete legacy records, preserving the valid prefix on truncation. /// Matches PhotoCraft recovery: version/grid fields are ignored. Declared counts /// cannot drive allocation or scanning beyond complete records in the input. @@ -124,3 +141,31 @@ mod tests { assert_eq!(ids_count(&[0, 0, 0]), None); } } + +#[cfg(test)] +mod v1_tests { + use super::*; + + #[test] + fn wire_roundtrip_and_signed_unknown_direction() { + let entries = [GuideV1 { location: -33, direction: 1 }, GuideV1 { location: i32::MAX, direction: 255 }]; + let mut data = header_v1(576, 576, 2).to_vec(); + assert_eq!(data, [0, 0, 0, 1, 0, 0, 2, 64, 0, 0, 2, 64, 0, 0, 0, 2]); + for e in entries { + data.extend(e.to_bytes()); + } + assert_eq!(&data[16..21], &[255, 255, 255, 223, 1]); + assert_eq!(parse_v1_prefix(&data).collect::>(), entries); + for end in 0..=data.len() { + assert_eq!(parse_v1_prefix(&data[..end]).count(), end.saturating_sub(16) / 5); + } + data[..4].copy_from_slice(&99u32.to_be_bytes()); + data[12..16].copy_from_slice(&u32::MAX.to_be_bytes()); + data.extend([9, 9, 9, 9]); + assert_eq!(parse_v1_prefix(&data).collect::>(), entries); + data[12..16].copy_from_slice(&1u32.to_be_bytes()); + assert_eq!(parse_v1_prefix(&data).collect::>(), &entries[..1]); + data[12..16].fill(0); + assert_eq!(parse_v1_prefix(&data).count(), 0); + } +} From ea0218294591cef788a8efe9e5b31f1d8dafc6a6 Mon Sep 17 00:00:00 2001 From: Martin Ball <98639962+benandez@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:27:49 +0100 Subject: [PATCH 81/97] image-codecs: add jpeg_worst_case_coefficients (#778) (#2063) A conservative pre-decode coefficient budget for hostile JPEG headers: the larger of JpegInfo::held_coefficients and a whole-picture estimate over every progressive frame header (SOF2/6/10/14, any precision, sampling clamped to 1..=4), with the costliest frame charged at the first frame's size when the header can't be followed. held_coefficients is unchanged. Co-authored-by: Claude Opus 5.5 --- crates/image-codecs/src/codecs/jpeg.rs | 241 +++++++++++++++++++++++++ crates/image-codecs/src/lib.rs | 9 + 2 files changed, 250 insertions(+) diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index 415a5d717..56593a5f5 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -86,6 +86,83 @@ fn held_coefficients(marker: u8, seg: &[u8], scan_components: Option) -> u64 factors.iter().map(|&(fh, fv)| mcus * fh * fv * 64 * 2).sum() } +/// Bytes of DCT coefficients to budget for before decoding hostile `b`: the larger of +/// [`crate::JpegInfo::held_coefficients`]'s rule (first frame; SOF2, or SOF0/SOF1 whose first +/// scan lacks components; 8-bit only; sampling factors as written) and a coarser one that +/// keeps a progressive JPEG's coefficients for the whole picture: +/// - every SOF2, SOF6, SOF10 and SOF14 header before the first scan counts, at any precision, and +/// the largest wins; each charges 2 bytes a coefficient: per component, `2 * 64 * h * v` per +/// MCU, with `h` and `v` clamped to 1..=4 and the MCUs covering the frame at the largest `h`, `v`; +/// - a header that can't be followed (a segment that is cut, a length under 2, a frame header +/// without its components, no `0xFF` where a marker belongs) charges the costliest frame, +/// four components sampled 4 × 4, at the first frame's size (as `scan_metadata` reads it), and 0 without one. +/// +/// Never less than either rule. Frames `craft-jpeg` decodes (arithmetic, lossless, 12-bit) +/// enforce `max_alloc` on their own buffers, and SOF6/SOF14 (hierarchical) are not decoded at all, +/// so charging them is only a conservative budget. Arithmetic saturates; the scan is linear. +pub(crate) fn worst_case_coefficients(b: &[u8]) -> u64 { + let m = scan_metadata(b); + let mut at = 2usize; + let mut most = 0u64; + let first: Option<(u64, u64)> = m.frame.map(|(w, h, _)| (u64::from(w), u64::from(h))); + let mut broken = false; + while !broken { + if b.get(at) != Some(&0xFF) { + broken = true; + break; + } + while b.get(at) == Some(&0xFF) { + at += 1; + } + let Some(&code) = b.get(at) else { + broken = true; + break; + }; + at += 1; + match code { + 0xD8 | 0x01 | 0xD0..=0xD7 => continue, + 0xD9 | 0xDA => break, + _ => {} + } + let len = match (b.get(at), b.get(at + 1)) { + (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), + _ => 0, + }; + let Some(seg) = (len >= 2).then(|| b.get(at + 2..at + len)).flatten() else { + broken = true; + break; + }; + if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { + match progressive_frame_coefficients(seg) { + Some(held) => most = most.max(held), + None => { + broken = true; + break; + } + } + } + at += len; + } + if broken && let Some((w, h)) = first { + let mcus = w.div_ceil(32).saturating_mul(h.div_ceil(32)); + most = most.max(mcus.saturating_mul(2 * 64 * 16 * 4)); + } + most.max(m.held_coefficients) +} + +/// [`worst_case_coefficients`]'s charge for one frame header `sof` (after its length). +fn progressive_frame_coefficients(sof: &[u8]) -> Option { + let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); + let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); + let n = usize::from(*sof.get(5)?); + let comps = sof.get(6..6usize.checked_add(n.checked_mul(3)?)?)?; + let factors: Vec<(u64, u64)> = + comps.as_chunks::<3>().0.iter().map(|&[_, f, _]| (u64::from(f >> 4).clamp(1, 4), u64::from(f & 15).clamp(1, 4))).collect(); + let (hmax, vmax) = factors.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); + let mcus = width.div_ceil(8 * hmax).saturating_mul(height.div_ceil(8 * vmax)); + Some(factors.iter().fold(0u64, |sum, &(h, v)| sum.saturating_add(mcus.saturating_mul(2 * 64 * h * v)))) +} + /// Walk the marker segments up to SOS and collect metadata. pub(crate) fn scan_metadata(b: &[u8]) -> JpegMeta { let mut m = JpegMeta::default(); @@ -825,6 +902,170 @@ mod tests { assert_eq!(held(&frame(0xC2, 12, &[0x11, 0x11, 0x11], None)), Some(0)); } + /// The consumer's own estimate (WordCraft's `jpeg_coefficients`), ported as the oracle that + /// `worst_case_coefficients` must never undercut. + fn oracle(bytes: &[u8]) -> u64 { + fn worst(bytes: &[u8]) -> u64 { + let Some((w, h)) = info(bytes).map(|i| (i.width, i.height)) else { return 0 }; + let mcus = u64::from(w).div_ceil(32) * u64::from(h).div_ceil(32); + mcus.saturating_mul(2 * 64 * 16 * 4) + } + fn frame(sof: &[u8]) -> Option { + let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); + let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); + let n = usize::from(*sof.get(5)?); + let s: Vec<(u64, u64)> = sof + .get(6..6 + 3 * n)? + .as_chunks::<3>() + .0 + .iter() + .map(|&[_, s, _]| (u64::from(s >> 4).clamp(1, 4), u64::from(s & 15).clamp(1, 4))) + .collect(); + let (hm, vm) = s.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); + let mcus = width.div_ceil(8 * hm).checked_mul(height.div_ceil(8 * vm))?; + s.iter().try_fold(0u64, |sum, &(h, v)| sum.checked_add(mcus.checked_mul(2 * 64 * h * v)?)) + } + let mut at = 2; + let mut most = 0u64; + loop { + if bytes.get(at) != Some(&0xFF) { + return worst(bytes).max(most); + } + while bytes.get(at) == Some(&0xFF) { + at += 1; + } + let Some(&code) = bytes.get(at) else { return worst(bytes).max(most) }; + at += 1; + match code { + 0xD8 | 0x01 | 0xD0..=0xD7 => continue, + 0xD9 | 0xDA => return most, + _ => {} + } + let len = match (bytes.get(at), bytes.get(at + 1)) { + (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), + _ => 0, + }; + let Some(seg) = bytes.get(at + 2..at + len).filter(|_| len >= 2) else { return worst(bytes).max(most) }; + if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { + let Some(h) = frame(seg) else { return worst(bytes).max(most) }; + most = most.max(h); + } + at += len; + } + } + + /// A JPEG header: each frame is (marker, precision, width, height, sampling bytes), then an + /// optional scan of `scan` components, then EOI. + fn header(frames: &[(u8, u8, u16, u16, &[u8])], scan: Option) -> Vec { + let mut b = vec![0xFF, 0xD8]; + for &(marker, precision, w, h, f) in frames { + b.extend_from_slice(&[0xFF, marker]); + b.extend_from_slice(&(8 + 3 * f.len() as u16).to_be_bytes()); + b.push(precision); + b.extend_from_slice(&h.to_be_bytes()); + b.extend_from_slice(&w.to_be_bytes()); + b.push(f.len() as u8); + for (i, &s) in f.iter().enumerate() { + b.extend_from_slice(&[i as u8 + 1, s, 0]); + } + } + if let Some(n) = scan { + b.extend_from_slice(&[0xFF, 0xDA, 0, 6 + 2 * n, n]); + (1..=n).for_each(|c| b.extend_from_slice(&[c, 0])); + b.extend_from_slice(&[0, 63, 0]); + } + b.extend_from_slice(&[0xFF, 0xD9]); + b + } + + /// Never less than the oracle or `held_coefficients`; equal to the larger on valid headers. + #[test] + fn worst_case_coefficients_covers_both_rule_sets() { + const C3: &[u8] = &[0x22, 0x11, 0x11]; + const G: &[u8] = &[0x11]; + let cases: Vec> = vec![ + header(&[(0xC0, 8, 640, 480, C3)], Some(3)), + header(&[(0xC0, 8, 640, 480, G)], Some(1)), + header(&[(0xC0, 8, 640, 480, C3)], Some(1)), + header(&[(0xC1, 8, 640, 480, C3)], None), + header(&[(0xC2, 8, 640, 480, C3)], Some(1)), + header(&[(0xC2, 12, 640, 480, C3)], Some(1)), + header(&[(0xC6, 8, 640, 480, C3)], None), + header(&[(0xCA, 8, 640, 480, C3)], None), + header(&[(0xCE, 8, 640, 480, C3)], None), + header(&[(0xC0, 8, 64, 64, G), (0xC2, 8, 6000, 4000, C3), (0xC2, 8, 100, 100, C3)], Some(1)), + header(&[(0xC2, 8, 640, 480, &[0x00, 0x00, 0x00])], None), + header(&[(0xC2, 8, 640, 480, &[0xFF, 0xFF, 0xFF, 0xFF])], None), + header(&[(0xC2, 8, 65535, 65535, &[0x44; 4])], None), + header(&[(0xC0, 8, 65535, 65535, &[0xFF; 4])], Some(1)), + header(&[], None), + vec![0xFF, 0xD8], + vec![], + b"not a jpeg at all".to_vec(), + ]; + for b in &cases { + let held = scan_metadata(b).held_coefficients; + let got = worst_case_coefficients(b); + assert!(got >= oracle(b) && got >= held, "{b:02x?}"); + assert!(got >= info(b).map_or(0, |i| i.held_coefficients)); + } + let at = |i: usize| worst_case_coefficients(&cases[i]); + // Equal to the oracle where the shared rule charges nothing extra. + for i in [0, 1, 6, 7, 8, 9, 10, 12, 14] { + assert_eq!(at(i), oracle(&cases[i]), "case {i}"); + } + // Where it does, the shared figure wins (the oracle misses a short first scan). + assert_eq!(oracle(&cases[2]), 0); + assert_eq!(at(2), scan_metadata(&cases[2]).held_coefficients); + // Unclamped factors (15 × 15) charge the shared rule more than the clamped oracle. + assert_eq!(at(11), scan_metadata(&cases[11]).held_coefficients); + assert!(at(11) > oracle(&cases[11])); + assert!(at(2) > 0 && at(3) == 0 && at(0) == 0); + // 12-bit and arithmetic progressive frames are charged though craft-jpeg limits itself. + assert_eq!(at(5), at(4)); + // Sampling factors clamp: 0 acts as 1, 15 as 4. + assert_eq!(at(10), 80 * 60 * 3 * 128); + assert_eq!(at(12), 2048 * 2048 * 4 * 2 * 64 * 16); + // The largest of several frames wins. + assert_eq!(at(9), oracle(&header(&[(0xC2, 8, 6000, 4000, C3)], None))); + } + + /// A cut header charges the costliest frame at its size; every prefix and random damage stays + /// bounded, never panics and never undercuts the oracle. + #[test] + fn worst_case_coefficients_hostile_input() { + let full = header(&[(0xC2, 8, 6000, 4000, &[0x22, 0x11, 0x11])], Some(1)); + let cut = &full[..full.len() - 8]; + // Cut inside the component list: a frame the scan can't read, at its own size. + let sof_cut = &full[..14]; + assert_eq!(worst_case_coefficients(sof_cut), oracle(sof_cut)); + assert_eq!(worst_case_coefficients(cut), oracle(cut)); + let mut bases = vec![full.clone(), header(&[(0xC0, 8, 6000, 4000, &[0x11; 3])], Some(1))]; + bases.push(header(&[(0xC2, 8, 65535, 65535, &[0xFF; 4])], None)); + let mut seed = 0x9E37_79B9_7F4A_7C15u64; + let mut next = move || { + seed = seed.wrapping_mul(6_364_136_223_846_793_005).wrapping_add(1_442_695_040_888_963_407); + (seed >> 33) as usize + }; + for base in &bases { + for n in 0..=base.len() { + let b = &base[..n]; + let got = worst_case_coefficients(b); + assert!(got >= oracle(b) && got < 1 << 50); + } + for _ in 0..2000 { + let mut b = base.clone(); + for _ in 0..=next() % 4 { + let i = next() % b.len(); + b[i] = next() as u8; + } + b.truncate(next() % (b.len() + 1)); + let got = worst_case_coefficients(&b); + assert!(got >= oracle(&b) && got >= scan_metadata(&b).held_coefficients && got < 1 << 50); + } + } + } + /// An APP1 Extended XMP fragment (GUID, total size, offset, data). fn extended_xmp(offset: u32) -> Vec { let mut seg = EXTENDED_XMP_HEADER.to_vec(); diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index dc2ac2933..47e3f12e3 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -307,6 +307,15 @@ pub fn jpeg_info(bytes: &[u8]) -> Option { jpeg::info(bytes) } +/// Bytes of DCT coefficients to budget for a JPEG before decoding it: never less than +/// [`JpegInfo::held_coefficients`] nor than the whole-picture estimate of every progressive +/// frame header (SOF2, SOF6, SOF10, SOF14 at any precision, sampling clamped to 1..=4), and the +/// costliest frame at the first size read when the header can't be followed. 0 without a +/// readable frame. See the function body's rules for the precise charges. +pub fn jpeg_worst_case_coefficients(bytes: &[u8]) -> u64 { + jpeg::worst_case_coefficients(bytes) +} + /// PCX's dimensions are available from its fixed-size header without decoding the RLE rows. pub fn pcx_dimensions(bytes: &[u8]) -> Option<(u32, u32)> { codecs::pcx::dimensions(bytes) From 1928693fbb7a4f8e6b945e614b2fac3e181476ea Mon Sep 17 00:00:00 2001 From: Martin Ball <98639962+benandez@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:27:53 +0100 Subject: [PATCH 82/97] image-codecs: header-only PNG pixel model and WebP alpha probes (#778) (#2064) png_probe::pixel_model reads width, height, bit depth, colour type and tRNS presence from IHDR and the chunk headers before IDAT without inflating iCCP; PixelModel::bytes_per_pixel and has_alpha give a caller's pixel size and alpha. webp_probe::has_alpha reads the VP8X alpha flag, the VP8L alpha_is_used bit, and treats plain VP8 as opaque. Differential tests compare against WordCraft's png_chunks as an oracle. Co-authored-by: Claude Opus 5.5 --- crates/image-codecs/src/png_probe.rs | 223 ++++++++++++++++++++++++++ crates/image-codecs/src/webp_probe.rs | 54 +++++++ 2 files changed, 277 insertions(+) diff --git a/crates/image-codecs/src/png_probe.rs b/crates/image-codecs/src/png_probe.rs index 73f1199eb..e7af74334 100644 --- a/crates/image-codecs/src/png_probe.rs +++ b/crates/image-codecs/src/png_probe.rs @@ -136,6 +136,93 @@ pub fn color_chunks(b: &[u8]) -> Option { Some(result) } +/// Most chunks [`pixel_model`] walks before the image data; each chunk is at least 12 bytes. +const MAX_PROBE_CHUNKS: usize = 1 << 16; + +/// Pixel model of a PNG, from `IHDR` and the chunk headers before the first `IDAT`. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PixelModel { + pub width: u32, + pub height: u32, + /// `IHDR` bit depth (1, 2, 4, 8 or 16). + pub bit_depth: u8, + /// `IHDR` colour type (0 grey, 2 RGB, 3 palette, 4 grey+alpha, 6 RGBA). + pub color_type: u8, + /// A `tRNS` chunk precedes the image data; it adds alpha to grey, RGB and palette images. + pub has_trns: bool, +} + +impl PixelModel { + /// Channels of the decoded buffer (palette expands to RGB; `tRNS` adds an alpha channel). + pub fn channels(&self) -> u8 { + let base = match self.color_type { + 0 => 1, + 2 | 3 => 3, + 4 => 2, + _ => 4, + }; + base + u8::from(self.has_trns && matches!(self.color_type, 0 | 2 | 3)) + } + + /// Bytes per pixel of the buffer a decoder that expands sub-byte samples to 8 bits gives: + /// `channels * (2 if bit_depth == 16 else 1)`. + pub fn bytes_per_pixel(&self) -> u8 { + self.channels() * if self.bit_depth == 16 { 2 } else { 1 } + } + + /// Whether the image has transparency (alpha colour type or `tRNS`). + pub fn has_alpha(&self) -> bool { + matches!(self.color_type, 4 | 6) || self.has_trns + } +} + +/// Dimensions, bit depth, colour type and `tRNS` presence without inflating anything (an `iCCP` +/// profile is skipped, not decompressed). Walks at most 65,536 chunk headers and stops at `IDAT`; +/// `IEND` or the end of the input before `IDAT` is an error. Does not validate CRCs. +/// A caller gets its `(width, height, bytes_per_pixel, alpha)` as +/// `(m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())`. +pub fn pixel_model(b: &[u8]) -> Result { + if !b.starts_with(b"\x89PNG\r\n\x1a\n") { + return Err(err("bad signature")); + } + let be32 = |p: usize| b.get(p..p.checked_add(4)?).and_then(|v| <[u8; 4]>::try_from(v).ok()).map(u32::from_be_bytes); + if be32(8) != Some(13) || b.get(12..16) != Some(b"IHDR") { + return Err(err("missing IHDR")); + } + let ihdr = b.get(16..29).ok_or_else(|| err("truncated IHDR"))?; + let (width, height) = (be32(16).unwrap_or(0), be32(20).unwrap_or(0)); + let (bit_depth, color_type) = (ihdr[8], ihdr[9]); + if width == 0 || height == 0 || width > i32::MAX as u32 || height > i32::MAX as u32 { + return Err(err("dimensions out of range")); + } + let depth_ok = match color_type { + 0 => matches!(bit_depth, 1 | 2 | 4 | 8 | 16), + 3 => matches!(bit_depth, 1 | 2 | 4 | 8), + 2 | 4 | 6 => matches!(bit_depth, 8 | 16), + _ => false, + }; + if !depth_ok { + return Err(err("invalid IHDR")); + } + let mut has_trns = false; + let mut p = 8usize; + for _ in 0..MAX_PROBE_CHUNKS { + let len = be32(p).ok_or_else(|| err("truncated"))?; + let kind = p.checked_add(4).and_then(|k| b.get(k..k.checked_add(4)?)).ok_or_else(|| err("truncated"))?; + match kind { + b"IDAT" => return Ok(PixelModel { width, height, bit_depth, color_type, has_trns }), + b"IEND" => return Err(err("no image data")), + b"tRNS" => has_trns = true, + _ => {} + } + if len > i32::MAX as u32 { + return Err(err("chunk length out of range")); + } + p = p.checked_add(12).and_then(|q| q.checked_add(len as usize)).ok_or_else(|| err("truncated"))?; + } + Err(CodecError::LimitExceeded("PNG chunk count".into())) +} + #[cfg(test)] mod tests { use super::*; @@ -187,4 +274,140 @@ mod tests { assert!(!color.srgb); assert!(color_chunks(b"not png").is_none()); } + + /// WordCraft's `png_chunks` (crates/geom/src/picture.rs) as the differential oracle. + fn oracle(bytes: &[u8]) -> Option<(u32, u32, u64, bool)> { + let be = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_be_bytes); + if bytes.get(12..16) != Some(b"IHDR".as_slice()) { + return None; + } + let (width, height) = (be(16)?, be(20)?); + let (depth, color) = (*bytes.get(24)?, *bytes.get(25)?); + let mut trns = false; + let mut at = 8usize; + loop { + let len = usize::try_from(be(at)?).ok()?; + match bytes.get(at.checked_add(4)?..at.checked_add(8)?)? { + b"IDAT" => break, + b"IEND" => return None, + b"tRNS" => trns = true, + _ => {} + } + at = at.checked_add(12)?.checked_add(len)?; + } + let (channels, alpha) = match color { + 0 => (1 + u64::from(trns), trns), + 2 | 3 => (3 + u64::from(trns), trns), + 4 => (2, true), + 6 => (4, true), + _ => return None, + }; + Some((width, height, channels * if depth == 16 { 2 } else { 1 }, alpha)) + } + + fn tuple(b: &[u8]) -> Option<(u32, u32, u64, bool)> { + pixel_model(b).ok().map(|m| (m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())) + } + + fn png_with(depth: u8, color: u8, before_idat: &[(&[u8; 4], Vec)]) -> Vec { + let mut bytes = b"\x89PNG\r\n\x1a\n".to_vec(); + let mut ihdr = Vec::new(); + ihdr.extend_from_slice(&5u32.to_be_bytes()); + ihdr.extend_from_slice(&7u32.to_be_bytes()); + ihdr.extend_from_slice(&[depth, color, 0, 0, 0]); + chunk(&mut bytes, b"IHDR", &ihdr); + for (k, d) in before_idat { + chunk(&mut bytes, k, d); + } + chunk(&mut bytes, b"IDAT", &[1, 2, 3]); + chunk(&mut bytes, b"IEND", &[]); + bytes + } + + #[test] + fn pixel_model_matches_oracle_for_every_color_type_depth_and_trns() { + let valid: [(u8, &[u8]); 5] = [(0, &[1, 2, 4, 8, 16]), (2, &[8, 16]), (3, &[1, 2, 4, 8]), (4, &[8, 16]), (6, &[8, 16])]; + for (color, depths) in valid { + for &depth in depths { + for trns in [false, true] { + let extra: Vec<(&[u8; 4], Vec)> = if trns { vec![(b"tRNS", vec![0, 0])] } else { vec![] }; + let bytes = png_with(depth, color, &extra); + assert!(tuple(&bytes).is_some(), "color {color} depth {depth}"); + assert_eq!(tuple(&bytes), oracle(&bytes), "color {color} depth {depth} trns {trns}"); + } + } + } + } + + #[test] + fn pixel_model_known_values() { + let m = pixel_model(&png_with(16, 2, &[(b"tRNS", vec![0; 6])])).unwrap(); + assert_eq!((m.width, m.height, m.channels(), m.bytes_per_pixel(), m.has_alpha()), (5, 7, 4, 8, true)); + let m = pixel_model(&png_with(4, 3, &[])).unwrap(); + assert_eq!((m.bytes_per_pixel(), m.has_alpha()), (3, false)); + } + + #[test] + fn pixel_model_skips_a_huge_iccp_without_inflating() { + let junk = vec![0xAB; 20 << 20]; + let bytes = png_with(8, 2, &[(b"iCCP", junk), (b"tRNS", vec![0; 6])]); + assert_eq!(tuple(&bytes), oracle(&bytes)); + assert_eq!(tuple(&bytes), Some((5, 7, 4, true))); + } + + #[test] + fn pixel_model_malformed_inputs_agree_with_oracle_and_never_panic() { + let full = png_with(8, 6, &[(b"tRNS", vec![0]), (b"gAMA", vec![0; 4])]); + for n in 0..=full.len() { + let cut = &full[..n]; + let got = tuple(cut); + // an Err where the oracle answers can only be a stricter header check + if got.is_some() { + assert_eq!(got, oracle(cut), "prefix {n}"); + } + } + assert!(pixel_model(&full[..33]).is_err()); + // missing IHDR + let mut bad = full.clone(); + bad[12..16].copy_from_slice(b"IHDX"); + assert!(pixel_model(&bad).is_err() && oracle(&bad).is_none()); + // chunk length overflow: a length past the input, then one past i32::MAX + for len in [u32::MAX, i32::MAX as u32, 0x7fff_fff0] { + let mut o = full.clone(); + o[33..37].copy_from_slice(&len.to_be_bytes()); + assert!(pixel_model(&o).is_err(), "len {len:#x}"); + assert_eq!(tuple(&o), oracle(&o)); + } + // IEND before IDAT, unknown colour type, zero size, bad signature + let mut iend = png_with(8, 2, &[]); + let at = iend.windows(4).position(|w| w == b"IDAT").unwrap(); + iend[at..at + 4].copy_from_slice(b"IEND"); + assert!(pixel_model(&iend).is_err() && oracle(&iend).is_none()); + assert!(pixel_model(&png_with(8, 5, &[])).is_err()); + let mut zero = png_with(8, 2, &[]); + zero[16..20].copy_from_slice(&0u32.to_be_bytes()); + assert!(pixel_model(&zero).is_err()); + assert!(pixel_model(b"not a png").is_err()); + // deterministic pseudo-random corruption + let mut s = 0x9e37_79b9u32; + for _ in 0..2000 { + let mut f = full.clone(); + for _ in 0..3 { + s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + let i = (s >> 8) as usize % f.len(); + f[i] = (s >> 24) as u8; + } + let _ = pixel_model(&f); + } + } + + #[test] + fn pixel_model_many_tiny_chunks_and_the_chunk_cap() { + let many: Vec<(&[u8; 4], Vec)> = (0..10_000).map(|_| (b"tEXt", Vec::new())).chain([(b"tRNS", vec![0])]).collect(); + let bytes = png_with(8, 0, &many); + assert_eq!(tuple(&bytes), oracle(&bytes)); + assert_eq!(tuple(&bytes), Some((5, 7, 2, true))); + let over: Vec<(&[u8; 4], Vec)> = (0..MAX_PROBE_CHUNKS + 1).map(|_| (b"tEXt", Vec::new())).collect(); + assert!(matches!(pixel_model(&png_with(8, 0, &over)), Err(CodecError::LimitExceeded(_)))); + } } diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index 4a31def00..1c22411dc 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -32,6 +32,25 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { Ok((w, h, orientation)) } +/// Whether a WebP carries transparency, from the first chunk only (nothing is decoded): +/// `VP8X` flag bit 0x10, `VP8L` `alpha_is_used`, plain `VP8` never. +pub fn has_alpha(bytes: &[u8]) -> Result { + let err = |s: &str| CodecError::malformed(Format::WebP, s); + if bytes.get(..4) != Some(b"RIFF") || bytes.get(8..12) != Some(b"WEBP") { + return Err(err("bad signature")); + } + match bytes.get(12..16) { + Some(b"VP8X") => Ok(bytes.get(20).ok_or_else(|| err("truncated VP8X"))? & 0x10 != 0), + // 0x2f signature byte, then 14+14 size bits, then the alpha_is_used bit (bit 28) + Some(b"VP8L") => match bytes.get(20..25) { + Some([0x2f, a, b, c, d]) => Ok(u32::from_le_bytes([*a, *b, *c, *d]) >> 28 & 1 != 0), + _ => Err(err("bad VP8L header")), + }, + Some(b"VP8 ") => Ok(false), + _ => Err(err("no image data")), + } +} + #[cfg(test)] mod tests { use super::*; @@ -71,4 +90,39 @@ mod tests { bytes.push(0); assert!(header(&bytes).is_err()); } + + #[test] + fn has_alpha_reads_vp8x_vp8l_and_plain_vp8() { + for (layout, want) in [(crate::ChannelLayout::Rgb, false), (crate::ChannelLayout::Rgba, true)] { + let n = layout.channels(); + let image = crate::Image::from_u8(2, 3, layout, vec![42; 6 * n]).unwrap(); + let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + assert_eq!(has_alpha(&bytes).unwrap(), want); + } + let riff = |chunk: &[u8; 4], body: &[u8]| { + let mut v = b"RIFF\0\0\0\0WEBP".to_vec(); + v.extend_from_slice(chunk); + v.extend_from_slice(&(body.len() as u32).to_le_bytes()); + v.extend_from_slice(body); + v + }; + let mut x = [0u8; 10]; + assert!(!has_alpha(&riff(b"VP8X", &x)).unwrap()); + x[0] = 0x10; + assert!(has_alpha(&riff(b"VP8X", &x)).unwrap()); + assert!(!has_alpha(&riff(b"VP8 ", &[0; 10])).unwrap()); + assert!(has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0x10])).unwrap()); + assert!(!has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0])).unwrap()); + } + + #[test] + fn has_alpha_rejects_malformed_prefixes() { + let full = [b"RIFF\0\0\0\0WEBPVP8X\x0a\0\0\0".as_slice(), &[0x10; 10]].concat(); + for n in 0..20 { + assert!(has_alpha(&full[..n]).is_err(), "prefix {n}"); + } + assert!(has_alpha(&full[..21]).is_ok()); + assert!(has_alpha(b"RIFF\0\0\0\0WEBPVP8L\x05\0\0\0\x2e").is_err()); + assert!(has_alpha(b"junk").is_err()); + } } From 3e82d1719cb0c6a5e0e4978a73d6893072c2ce17 Mon Sep 17 00:00:00 2001 From: Martin Ball <98639962+benandez@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:45:52 +0100 Subject: [PATCH 83/97] craft-mcp-server: options for apps that report argument errors as tool results (#2061) * craft-mcp-server: options for apps that report argument errors as tool results (#778) Add `Options` (default = today's behaviour) and `Server::with_options`: - `website_url`: sent as `serverInfo.websiteUrl` at `initialize`. - `tool_errors_as_results`: a `tools/call` whose arguments fail the schema check, or whose tool is unknown, returns a tool result with `isError: true` and the message as text, not -32602. - `strict_request_ids`: a request id that is not a string or number gets -32600 with a null id. `Info` is unchanged, so existing struct-literal callers still compile. Tests cover each option on and off, and hostile input with all options on. Co-Authored-By: Claude Opus 5.5 * craft-mcp-server: strict request ids also apply to the missing-method error (#778) With strict_request_ids, a message without `method` echoed an object, array or bool id in its -32600 reply. It now answers with a null id for any id that is not a string or number, as the later strict check does. Valid ids, absent ids and incoming responses behave as before. Co-Authored-By: Claude Sonnet 5.5 --------- Co-authored-by: Claude Opus 5.5 --- crates/mcp-server/src/lib.rs | 2 +- crates/mcp-server/src/server.rs | 45 +++++++++-- crates/mcp-server/src/tests.rs | 131 +++++++++++++++++++++++++++++++- 3 files changed, 171 insertions(+), 7 deletions(-) diff --git a/crates/mcp-server/src/lib.rs b/crates/mcp-server/src/lib.rs index 17e6827c4..66568fc05 100644 --- a/crates/mcp-server/src/lib.rs +++ b/crates/mcp-server/src/lib.rs @@ -15,7 +15,7 @@ mod server; pub use content::{Contents, base64, image_result, text_result}; pub use schema::{Effect, check_arguments, object, string, tool}; -pub use server::{Incoming, Info, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, read_message, response}; +pub use server::{Incoming, Info, Options, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, read_message, response}; #[cfg(test)] mod tests; diff --git a/crates/mcp-server/src/server.rs b/crates/mcp-server/src/server.rs index b7ed05027..e0d064da5 100644 --- a/crates/mcp-server/src/server.rs +++ b/crates/mcp-server/src/server.rs @@ -4,7 +4,7 @@ use std::io::{BufRead, Write}; use serde_json::{Value, json}; -use crate::content::Contents; +use crate::content::{Contents, text_result}; use crate::schema::{check_arguments, check_prompt_arguments}; /// The newest protocol revision we speak; offered when the client asks for one we don't know. @@ -88,9 +88,25 @@ pub struct Info { pub max_line: usize, } +/// Opt-in behaviour for apps with their own conventions; `Options::default()` is what [`Server::new`] +/// does. Set with [`Server::with_options`]. +#[derive(Clone, Debug, Default)] +pub struct Options { + /// Sent as `serverInfo.websiteUrl` at `initialize` (MCP 2025-06-18) when set. + pub website_url: Option, + /// Report a `tools/call` whose arguments fail the check against the tool's schema, or whose + /// tool is unknown, as a tool result with `isError: true` and the message as text, not as a + /// JSON-RPC -32602 error. For apps whose clients read every tool failure from the result. + pub tool_errors_as_results: bool, + /// Refuse a request whose `id` is neither a string nor a number (JSON-RPC 2.0) with -32600 and + /// a null id, instead of echoing the id back. + pub strict_request_ids: bool, +} + /// An MCP server over the app's [`Tools`]. pub struct Server { info: Info, + options: Options, tools: T, initialized: bool, } @@ -157,7 +173,13 @@ pub fn response(id: Value, result: Value) -> Value { impl Server { pub fn new(info: Info, tools: T) -> Self { - Self { info, tools, initialized: false } + Self { info, options: Options::default(), tools, initialized: false } + } + /// This server with `options` ([`Options`]) in place of the defaults. + #[must_use] + pub fn with_options(mut self, options: Options) -> Self { + self.options = options; + self } pub fn tools(&mut self) -> &mut T { &mut self.tools @@ -215,7 +237,11 @@ impl Server { if o.contains_key("result") || o.contains_key("error") { return None; } - return Some(error(id.unwrap_or(Value::Null), INVALID_REQUEST, "missing `method`")); + let echoed = match id { + Some(id) if !self.options.strict_request_ids || id.is_string() || id.is_number() => id, + _ => Value::Null, + }; + return Some(error(echoed, INVALID_REQUEST, "missing `method`")); }; let params = o.get("params").cloned().unwrap_or(Value::Null); let Some(id) = id else { @@ -224,6 +250,9 @@ impl Server { } return None; }; + if self.options.strict_request_ids && !(id.is_string() || id.is_number()) { + return Some(error(Value::Null, INVALID_REQUEST, "`id` must be a string or number")); + } Some(match self.request(method, ¶ms) { Ok(r) => response(id, r), Err((code, m)) => error(id, code, m), @@ -236,10 +265,14 @@ impl Server { let asked = params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL_VERSION); let version = if SUPPORTED_VERSIONS.contains(&asked) { asked } else { PROTOCOL_VERSION }; let Info { name, title, version: server_version, .. } = self.info; + let mut server_info = json!({"name": name, "title": title, "version": server_version}); + if let Some(url) = &self.options.website_url { + server_info["websiteUrl"] = json!(url); + } Ok(json!({ "protocolVersion": version, "capabilities": self.capabilities(), - "serverInfo": {"name": name, "title": title, "version": server_version}, + "serverInfo": server_info, "instructions": self.tools.instructions(), })) } @@ -251,7 +284,9 @@ impl Server { None | Some(Value::Null) => json!({}), Some(a) => a.clone(), }; - check_arguments(&self.tools.list(), name, &args).map_err(|e| (INVALID_PARAMS, e))?; + if let Err(e) = check_arguments(&self.tools.list(), name, &args) { + return if self.options.tool_errors_as_results { Ok(text_result(e, true)) } else { Err((INVALID_PARAMS, e)) }; + } Ok(self.tools.call(name, &args)) } "resources/list" => Ok(json!({"resources": self.tools.resources()})), diff --git a/crates/mcp-server/src/tests.rs b/crates/mcp-server/src/tests.rs index b687ee2e8..3f8f8d315 100644 --- a/crates/mcp-server/src/tests.rs +++ b/crates/mcp-server/src/tests.rs @@ -1,7 +1,8 @@ use serde_json::{Value, json}; use crate::{ - Contents, Effect, Info, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, check_arguments, object, string, text_result, tool, + Contents, Effect, Info, Options, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, check_arguments, object, string, text_result, + tool, }; /// One app's tools: `echo` and `level`, nothing behind them (no engine, no design). `log` records @@ -366,3 +367,131 @@ fn every_call_runs_right_after_its_listing() { reply(&mut s, &json!([call("level", json!({})), call("echo", json!({"text": "b"}))])); assert_eq!(s.tools().log, ["list", "list", "call echo", "list", "list", "call level", "list", "call echo"]); } + +fn with(options: Options) -> Server { + Server::new(info(), Echo::default()).with_options(options) +} + +fn call_msg(id: u64, name: &str, args: Value) -> Value { + json!({"jsonrpc": "2.0", "id": id, "method": "tools/call", "params": {"name": name, "arguments": args}}) +} + +/// `websiteUrl` is sent only when set. +#[test] +fn website_url_is_sent_only_when_set() { + let init = json!({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}); + let off = reply(&mut with(Options::default()), &init).unwrap(); + assert!(off["result"]["serverInfo"].get("websiteUrl").is_none(), "{off}"); + let on = reply(&mut with(Options { website_url: Some("https://example.org/echo".into()), ..Options::default() }), &init).unwrap(); + assert_eq!(on["result"]["serverInfo"]["websiteUrl"], "https://example.org/echo"); + assert_eq!(on["result"]["serverInfo"]["name"], "echo"); +} + +/// With `tool_errors_as_results`, argument failures and unknown tools are `isError` results that +/// carry the message and never run the tool; other errors stay JSON-RPC errors. +#[test] +fn tool_errors_as_results_replaces_invalid_params() { + let mut s = with(Options { tool_errors_as_results: true, ..Options::default() }); + let bad = [ + call_msg(1, "echo", json!({})), + call_msg(2, "echo", json!({"text": 3})), + call_msg(3, "echo", json!({"text": "a", "loud": true})), + call_msg(4, "shout", json!({})), + call_msg(5, "echo", json!([])), + call_msg(6, "echo", json!("text")), + call_msg(7, "echo", json!(7)), + ]; + for msg in &bad { + let r = reply(&mut s, msg).unwrap(); + assert!(r.get("error").is_none(), "{r}"); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert!(r["result"]["content"][0]["text"].as_str().is_some_and(|t| !t.is_empty()), "{r}"); + } + let r = reply(&mut s, &bad[0]).unwrap(); + assert_eq!(r["result"]["content"][0]["text"], "echo: missing required argument `text`"); + assert!(s.tools().calls.is_empty()); + let ok = reply(&mut s, &call_msg(8, "echo", json!({"text": "hi"}))).unwrap(); + assert_eq!(ok["result"], json!({"content": [{"type": "text", "text": "hi"}]})); + let nomethod = reply(&mut s, &json!({"jsonrpc": "2.0", "id": 9, "method": "nope"})).unwrap(); + assert_eq!(nomethod["error"]["code"], -32601); + let noname = reply(&mut s, &json!({"jsonrpc": "2.0", "id": 10, "method": "tools/call", "params": {}})).unwrap(); + assert_eq!(noname["error"]["code"], -32602); + // Unchanged with the option off. + let mut off = with(Options::default()); + for msg in &bad { + assert_eq!(reply(&mut off, msg).unwrap()["error"]["code"], -32602); + } +} + +/// With `strict_request_ids`, an id that is not a string or number is -32600 with a null id; the +/// tool never runs. Off, such ids are echoed as before. Notifications have no id and are unaffected. +#[test] +fn strict_request_ids_refuse_other_id_types() { + let odd = [json!(null), json!(true), json!({"a": 1}), json!([1])]; + let mut on = with(Options { strict_request_ids: true, ..Options::default() }); + let mut off = with(Options::default()); + for id in &odd { + let msg = json!({"jsonrpc": "2.0", "id": id, "method": "tools/call", "params": {"name": "echo", "arguments": {"text": "x"}}}); + let r = reply(&mut on, &msg).unwrap(); + assert_eq!(r["error"]["code"], -32600, "{id}: {r}"); + assert_eq!(r["id"], Value::Null); + let r = reply(&mut off, &json!({"jsonrpc": "2.0", "id": id, "method": "ping"})).unwrap(); + assert_eq!(r["id"], *id); + assert_eq!(r["result"], json!({})); + } + assert!(on.tools().calls.is_empty()); + for id in [json!("a"), json!(1), json!(1.5), json!(-3)] { + let r = reply(&mut on, &json!({"jsonrpc": "2.0", "id": id, "method": "ping"})).unwrap(); + assert_eq!(r["result"], json!({}), "{id}"); + } + assert!(reply(&mut on, ¬ification()).is_none()); +} + +/// The missing-`method` error follows the same id rule: strict mode echoes only string and number +/// ids and answers with a null id for the rest; off, ids are echoed as before. +#[test] +fn strict_request_ids_apply_to_the_missing_method_error() { + let mut on = with(Options { strict_request_ids: true, ..Options::default() }); + let mut off = with(Options::default()); + for id in [json!(true), json!({"a": 1}), json!([1])] { + let msg = json!({"jsonrpc": "2.0", "id": id}); + let r = reply(&mut on, &msg).unwrap(); + assert_eq!((r["error"]["code"].clone(), r["id"].clone()), (json!(-32600), Value::Null), "{id}"); + assert_eq!(reply(&mut off, &msg).unwrap()["id"], id); + } + for id in [json!("a"), json!(7)] { + assert_eq!(reply(&mut on, &json!({"jsonrpc": "2.0", "id": id})).unwrap()["id"], id); + } + assert_eq!(reply(&mut on, &json!({"jsonrpc": "2.0"})).unwrap()["id"], Value::Null); +} + +/// Hostile input with every option on: oversized and non-UTF-8 lines, odd ids and wrongly typed +/// arguments are answered and serving goes on, and nothing panics. +#[test] +fn every_option_on_survives_hostile_input() { + let mut input = vec![b'x'; (1 << 16) + 10]; + input.push(b'\n'); + input.extend_from_slice(b"\xff\xfe\n"); + for id in ["null", "true", "{}", "[]", "\"s\"", "1e999"] { + input.extend_from_slice( + format!( + "{{\"jsonrpc\":\"2.0\",\"id\":{id},\"method\":\"tools/call\",\"params\":{{\"name\":\"echo\",\"arguments\":{{\"text\":{id}}}}}}}\n" + ) + .as_bytes(), + ); + } + for args in ["null", "1", "\"a\"", "[]", "{\"text\":[1]}", "{\"text\":{}}"] { + input.extend_from_slice( + format!("{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{{\"name\":\"level\",\"arguments\":{args}}}}}\n").as_bytes(), + ); + } + input.extend_from_slice(json!({"jsonrpc": "2.0", "id": 9, "method": "ping"}).to_string().as_bytes()); + let mut output = Vec::new(); + let options = Options { website_url: Some("https://example.org".into()), tool_errors_as_results: true, strict_request_ids: true }; + with(options).serve(std::io::Cursor::new(input), &mut output).unwrap(); + let replies: Vec = String::from_utf8(output).unwrap().lines().map(|l| serde_json::from_str(l).unwrap()).collect(); + assert_eq!(replies.len(), 2 + 6 + 6 + 1, "{replies:?}"); + assert_eq!(replies[0]["error"]["code"], -32600); + assert_eq!(replies[1]["error"]["code"], -32700); + assert_eq!(replies.last().map(|r| &r["result"]), Some(&json!({}))); +} From 93dac78c93a7f1fd66e2022edeb089233b1dc45a Mon Sep 17 00:00:00 2001 From: Martin Ball <98639962+benandez@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:45:56 +0100 Subject: [PATCH 84/97] craft-image-codecs: wrap a clipboard DIB as a BMP (dib_to_bmp, dib_layout) (#2062) * image-codecs: wrap a clipboard DIB as a BMP (#778) Add bmp_probe::dib_to_bmp (prepend the 14-byte file header, pixel offset from the header with saturating arithmetic, try_reserve for the output) and bmp_probe::dib_layout (V4/V5 alpha-mask BI_RGB becomes BI_BITFIELDS, mask copy after the header). Both are ported from WordCraft's crates/geom/src/picture.rs so it can drop its local copies. Tests compare byte-for-byte with the originals over crafted DIBs and every prefix, and decode wrapped results. Co-Authored-By: Claude Opus 5.5 * image-codecs: fix DIB offsets for V2/V3 bitfields and ambiguous mask copies (#778) - dib_to_bmp no longer adds 12 appended-mask bytes to the pixel offset for 52- and 56-byte BI_BITFIELDS headers, which carry their masks inside the header; the decoder reads the pixels at bfOffBits, so the offset was 12 bytes too far. - dib_layout treats 12 bytes after the header that equal the masks as an existing copy only when more bytes follow than the pixels need, so an exact-length DIB whose pixels equal the masks gets its copy inserted. - dib_layout reserves the 12 bytes before changing compression or masks, so a failed reservation returns the DIB unchanged; the mask bytes are a [u8; 12] array, not a heap copy. The differential tests against the WordCraft originals now exclude exactly the 52/56-byte bitfields offset and the exact-length payload cases, and assert the new behaviour for them. Co-Authored-By: Claude Sonnet 5.5 --------- Co-authored-by: Claude Opus 5.5 --- crates/image-codecs/src/bmp_probe.rs | 442 +++++++++++++++++++++++++++ 1 file changed, 442 insertions(+) diff --git a/crates/image-codecs/src/bmp_probe.rs b/crates/image-codecs/src/bmp_probe.rs index 5b47721bc..89f6a3b97 100644 --- a/crates/image-codecs/src/bmp_probe.rs +++ b/crates/image-codecs/src/bmp_probe.rs @@ -1,5 +1,7 @@ //! Header-only BMP dimensions and pixel-data coverage, without allocating a canvas. +use crate::error::CodecError; + /// Recognize a BMP file header with a supported DIB header kind. /// /// This is a format-routing check, not full validation: dimensions and pixel data may still @@ -13,6 +15,115 @@ pub fn is_supported_header(b: &[u8]) -> bool { false } +/// Wrap a DIB (a BMP without its 14-byte `BITMAPFILEHEADER`, as the Windows clipboard holds one +/// for `CF_DIB` and `CF_DIBV5`) as a BMP file the decoders here read. The pixel offset is computed +/// from the header with saturating arithmetic, so a hostile header cannot overflow; whether the +/// pixel data exists is left to the decoder. Apply [`dib_layout`] first for clipboard DIBs. +/// +/// # Errors +/// +/// Returns [`CodecError::LimitExceeded`] when the output (`dib.len() + 14` bytes) cannot be allocated. +pub fn dib_to_bmp(dib: &[u8]) -> Result, CodecError> { + let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let bi_size = u32_at(0).unwrap_or(40); + let offset = if bi_size == 12 { + let bpp = u16_at(10).unwrap_or(24); + let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; + 14 + bi_size + palette + } else { + let bpp = u16_at(14).unwrap_or(24); + let compression = u32_at(16).unwrap_or(0); + let clr_used = u32_at(32).unwrap_or(0); + let palette_entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + // The masks of a 52- or 56-byte (V2/V3) header are inside the header; only the other + // header kinds carry them as 12 further bytes before the pixels. + let masks = if compression == 3 && bi_size >= 40 && !matches!(bi_size, 52 | 56) { 12 } else { 0 }; + 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) + }; + let total = dib.len().saturating_add(14); + let file_size = u32::try_from(total).unwrap_or(u32::MAX); + let mut bmp = Vec::new(); + bmp.try_reserve_exact(total).map_err(|_| CodecError::LimitExceeded(format!("a {total}-byte BMP")))?; + bmp.extend_from_slice(b"BM"); + bmp.extend_from_slice(&file_size.to_le_bytes()); + bmp.extend_from_slice(&[0u8; 4]); + bmp.extend_from_slice(&offset.to_le_bytes()); + bmp.extend_from_slice(dib); + Ok(bmp) +} + +/// Put a clipboard DIB with a V4 or V5 header (108 bytes or more) in the layout the decoder reads. +/// A 32-bit one whose alpha mask is set but whose compression says `BI_RGB` is marked +/// `BI_BITFIELDS` (with the usual colour masks when it gives none), so its alpha is kept as +/// Windows programs mean it; arboard makes the same change. Bit fields then need the colour masks +/// after the header too, where Windows puts a copy and the decoder skips them; a DIB without that +/// copy gets it. Any other DIB comes back unchanged, as does one whose 12 extra bytes cannot be +/// allocated. +pub fn dib_layout(mut dib: Vec) -> Vec { + let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; + let put = |d: &mut Vec, at: usize, v: u32| { + if let Some(b) = d.get_mut(at..at + 4) { + b.copy_from_slice(&v.to_le_bytes()); + } + }; + // Decide everything first and mutate only after the 12-byte reservation succeeded, so a failed + // allocation returns the DIB unchanged. + let promote = dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000); + let default_masks = promote && (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)); + let mut masks = dib.get(40..52).and_then(|b| <[u8; 12]>::try_from(b).ok()); + if default_masks { + let mut m = [0u8; 12]; + m[0..4].copy_from_slice(&0x00FF_0000u32.to_le_bytes()); + m[4..8].copy_from_slice(&0x0000_FF00u32.to_le_bytes()); + m[8..12].copy_from_slice(&0x0000_00FFu32.to_le_bytes()); + masks = Some(m); + } + let bitfields = promote || u32_at(&dib, 16) == Some(3); + // Bytes equal to the masks right after the header are a copy only when more bytes follow than + // the pixels need; otherwise they are the pixels (e.g. a 3x1 V5 DIB with pixels equal to the masks). + let has_copy = |m: &[u8; 12]| { + dib.get(size..size.saturating_add(12)) == Some(m.as_slice()) && pixel_bytes(&dib).is_none_or(|need| dib.len().saturating_sub(size) > need) + }; + let insert = match masks { + Some(m) if bitfields && size <= dib.len() && !has_copy(&m) => Some(m), + _ => None, + }; + if insert.is_some() && dib.try_reserve(12).is_err() { + return dib; + } + if promote { + put(&mut dib, 16, 3); + if default_masks { + put(&mut dib, 40, 0x00FF_0000); + put(&mut dib, 44, 0x0000_FF00); + put(&mut dib, 48, 0x0000_00FF); + } + } + if let Some(m) = insert { + dib.splice(size..size, m); + } + dib +} + +/// Bytes of pixel rows (4-byte aligned stride) the info-header dimensions of `dib` call for, or +/// `None` when width, height or bit count cannot be read. +fn pixel_bytes(dib: &[u8]) -> Option { + let i32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(i32::from_le_bytes); + let w = u64::try_from(i32_at(4)?).ok()?; + let h = u64::from(i32_at(8)?.unsigned_abs()); + let bpp = u64::from(u16::from_le_bytes(dib.get(14..16)?.try_into().ok()?)); + let stride = w.checked_mul(bpp)?.div_ceil(32).checked_mul(4)?; + usize::try_from(stride.checked_mul(h)?).ok() +} + /// Coverage of the declared pixel array. Row byte counts include row padding; RLE coverage /// counts the pixels drawn by commands and may be smaller than the canvas. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -174,4 +285,335 @@ mod tests { b[0] = b'X'; assert!(!is_supported_header(&b)); } + + // The WordCraft originals, kept verbatim as the oracle. + fn oracle_dib_to_bmp(dib: &[u8]) -> Vec { + let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let bi_size = u32_at(0).unwrap_or(40); + let offset = if bi_size == 12 { + let bpp = u16_at(10).unwrap_or(24); + let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; + 14 + bi_size + palette + } else { + let bpp = u16_at(14).unwrap_or(24); + let compression = u32_at(16).unwrap_or(0); + let clr_used = u32_at(32).unwrap_or(0); + let palette_entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + let masks = if compression == 3 && bi_size >= 40 { 12 } else { 0 }; + 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) + }; + let file_size = u32::try_from(14 + dib.len()).unwrap_or(u32::MAX); + let mut bmp = Vec::with_capacity(14 + dib.len()); + bmp.extend_from_slice(b"BM"); + bmp.extend_from_slice(&file_size.to_le_bytes()); + bmp.extend_from_slice(&[0u8; 4]); + bmp.extend_from_slice(&offset.to_le_bytes()); + bmp.extend_from_slice(dib); + bmp + } + + fn oracle_dib_layout(mut dib: Vec) -> Vec { + let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; + let put = |d: &mut Vec, at: usize, v: u32| { + if let Some(b) = d.get_mut(at..at + 4) { + b.copy_from_slice(&v.to_le_bytes()); + } + }; + if dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000) { + put(&mut dib, 16, 3); + if (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)) { + put(&mut dib, 40, 0x00FF_0000); + put(&mut dib, 44, 0x0000_FF00); + put(&mut dib, 48, 0x0000_00FF); + } + } + if u32_at(&dib, 16) == Some(3) + && size <= dib.len() + && let Some(masks) = dib.get(40..52).map(<[u8]>::to_vec) + && dib.get(size..size + 12) != Some(masks.as_slice()) + { + dib.splice(size..size, masks); + } + dib + } + + fn core(bpp: u16) -> Vec { + let mut d = Vec::new(); + d.extend_from_slice(&12u32.to_le_bytes()); + d.extend_from_slice(&2u16.to_le_bytes()); + d.extend_from_slice(&2u16.to_le_bytes()); + d.extend_from_slice(&1u16.to_le_bytes()); + d.extend_from_slice(&bpp.to_le_bytes()); + d.resize(12 + 64, 7); + d + } + + #[allow(clippy::too_many_arguments)] + fn info(size: u32, bpp: u16, comp: u32, clr_used: u32, masks: [u32; 4], tail: usize) -> Vec { + let mut d = vec![0u8; size.clamp(40, 124) as usize]; + d[0..4].copy_from_slice(&size.to_le_bytes()); + d[4..8].copy_from_slice(&2i32.to_le_bytes()); + d[8..12].copy_from_slice(&2i32.to_le_bytes()); + d[12..14].copy_from_slice(&1u16.to_le_bytes()); + d[14..16].copy_from_slice(&bpp.to_le_bytes()); + d[16..20].copy_from_slice(&comp.to_le_bytes()); + d[32..36].copy_from_slice(&clr_used.to_le_bytes()); + for (i, m) in masks.iter().enumerate() { + if let Some(b) = d.get_mut(40 + 4 * i..44 + 4 * i) { + b.copy_from_slice(&m.to_le_bytes()); + } + } + d.extend((0..tail).map(|i| (i * 31 + 5) as u8)); + d + } + + fn corpus() -> Vec> { + let mut v = Vec::new(); + for bpp in [1, 4, 8, 24, 0, 99] { + v.push(core(bpp)); + } + for bpp in [1u16, 4, 8, 16, 24, 32, 0, 255] { + for clr in [0u32, 1, 5, 256, u32::MAX] { + v.push(info(40, bpp, 0, clr, [0; 4], 40)); + } + } + for (size, comp, masks) in [ + (40, 3, [0xFF0000, 0xFF00, 0xFF, 0]), + (40, 3, [0; 4]), + (52, 3, [0xFF0000, 0xFF00, 0xFF, 0]), + (108, 3, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (108, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (108, 0, [0, 0, 0, 0xFF00_0000]), + (108, 0, [0; 4]), + (124, 3, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (124, 0, [0, 0, 0, 0xFF00_0000]), + (124, 0, [1, 0, 0, 0xFF00_0000]), + (124, 0, [0xFF0000, 0xFF00, 0xFF, 0]), + (124, 1, [0, 0, 0, 0xFF00_0000]), + (124, 3, [1, 2, 3, 4]), + (0, 0, [0; 4]), + (12, 0, [0; 4]), + (u32::MAX, 3, [0; 4]), + (u32::MAX, 0, [0; 4]), + (200, 3, [9; 4]), + ] { + for bpp in [8u16, 16, 32] { + for clr in [0u32, 2, u32::MAX] { + v.push(info(size, bpp, comp, clr, masks, 48)); + } + } + } + // 52/56-byte bitfields headers with and without a pixel tail, and 3x1 V5 DIBs. + for size in [52, 56] { + v.push(info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 4)); + v.push(info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 0)); + } + v.push(v5_3x1(false)); + v.push(v5_3x1(true)); + v + } + + /// 3x1 32-bit V5 BI_BITFIELDS whose three pixels equal the colour masks; with `copy` the DIB + /// also holds the real 12-byte mask copy before the pixels. + fn v5_3x1(copy: bool) -> Vec { + let masks = [0x00FF_0000u32, 0x0000_FF00, 0x0000_00FF]; + let mut d = info(124, 32, 3, 0, [masks[0], masks[1], masks[2], 0xFF00_0000], 0); + d[4..8].copy_from_slice(&3i32.to_le_bytes()); + d[8..12].copy_from_slice(&1i32.to_le_bytes()); + for _ in 0..usize::from(copy) + 1 { + for m in masks { + d.extend_from_slice(&m.to_le_bytes()); + } + } + d + } + + fn dib_u32(d: &[u8], at: usize) -> Option { + d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes) + } + + /// Fixed case 1: a 52- or 56-byte BI_BITFIELDS header holds its masks itself, so `dib_to_bmp` + /// no longer adds the 12 appended-mask bytes the WordCraft original added to the pixel offset. + fn bmp_offset_fixed(dib: &[u8]) -> bool { + matches!(dib_u32(dib, 0).unwrap_or(40), 52 | 56) && dib_u32(dib, 16) == Some(3) + } + + /// Fixed case 2: the original read 12 pixel bytes equal to the masks (exact-length payload) as a + /// mask copy and inserted nothing. Returns the corrected output when `cut` is such a case. + fn exact_length_fixed(cut: &[u8]) -> Option> { + let o = oracle_dib_layout(cut.to_vec()); + let size = usize::try_from(dib_u32(&o, 0).filter(|&s| s >= 108)?).ok()?; + let need = pixel_bytes(&o)?; + let same = o.len() == cut.len() + && dib_u32(&o, 16) == Some(3) + && size <= o.len() + && o.get(size..size + 12).is_some() + && o.get(size..size + 12) == o.get(40..52) + && o.len() - size <= need; + if !same { + return None; + } + let mut want = o.clone(); + want.splice(size..size, o[40..52].to_vec()); + Some(want) + } + + #[test] + fn dib_helpers_match_the_wordcraft_originals_byte_for_byte() { + let (mut total, mut offset_cases, mut exact_cases) = (0usize, 0usize, 0usize); + for dib in corpus() { + for n in 0..=dib.len() { + let cut = &dib[..n]; + total += 1; + let fixed_layout = exact_length_fixed(cut); + match &fixed_layout { + Some(want) => { + exact_cases += 1; + assert_eq!(&dib_layout(cut.to_vec()), want, "exact-length layout len {n}"); + } + None => assert_eq!(dib_layout(cut.to_vec()), oracle_dib_layout(cut.to_vec()), "layout len {n}"), + } + if bmp_offset_fixed(cut) { + offset_cases += 1; + let (new, old) = (dib_to_bmp(cut).unwrap(), oracle_dib_to_bmp(cut)); + assert_eq!(new[..10], old[..10]); + assert_eq!(new[14..], old[14..]); + let (a, b) = (dib_u32(&new, 10).unwrap(), dib_u32(&old, 10).unwrap()); + assert_eq!(a.saturating_add(12), b, "offset len {n}"); + } else { + assert_eq!(dib_to_bmp(cut).unwrap(), oracle_dib_to_bmp(cut), "bmp len {n}"); + } + let both = dib_layout(cut.to_vec()); + let old_both = oracle_dib_layout(cut.to_vec()); + if fixed_layout.is_none() && !bmp_offset_fixed(&both) { + assert_eq!(dib_to_bmp(&both).unwrap(), oracle_dib_to_bmp(&old_both)); + } + } + } + eprintln!("corpus cases {total}: 52/56-byte bitfields offset {offset_cases}, exact-length payload {exact_cases}"); + assert!(offset_cases > 0 && exact_cases > 0); + } + + #[test] + fn dib_helpers_survive_pseudo_random_bytes() { + let mut x = 0x9E37_79B9_7F4A_7C15u64; + for len in 0..300usize { + let d: Vec = (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect(); + let laid = dib_layout(d.clone()); + if exact_length_fixed(&d).is_none() && !bmp_offset_fixed(&laid) { + assert_eq!(dib_to_bmp(&laid).unwrap(), oracle_dib_to_bmp(&oracle_dib_layout(d))); + } + } + } + + #[test] + fn huge_palette_count_saturates_the_offset() { + let b = dib_to_bmp(&info(40, 8, 0, u32::MAX, [0; 4], 8)).unwrap(); + assert_eq!(u32::from_le_bytes([b[10], b[11], b[12], b[13]]), u32::MAX); + let b = dib_to_bmp(&info(u32::MAX, 8, 3, u32::MAX, [0; 4], 8)).unwrap(); + assert_eq!(u32::from_le_bytes([b[10], b[11], b[12], b[13]]), u32::MAX); + } + + #[test] + fn wrapped_dibs_decode_and_keep_alpha() { + // 2x2 32-bit V5, BI_RGB with an alpha mask, bottom-up BGRA pixels. + let mut d = info(124, 32, 0, 0, [0, 0, 0, 0xFF00_0000], 0); + let px = [[1u8, 2, 3, 255], [4, 5, 6, 128], [7, 8, 9, 64], [10, 11, 12, 0]]; + for p in px { + d.extend_from_slice(&p); + } + let bmp = dib_to_bmp(&dib_layout(d)).unwrap(); + let img = crate::decode(&bmp).unwrap(); + let alphas: Vec = img.to_rgba8().chunks(4).map(|p| u16::from(p[3])).collect(); + assert_eq!(alphas, [64, 0, 255, 128]); + // 24-bit plain DIB and a 12-byte core 8-bit one open too. + let mut d = info(40, 24, 0, 0, [0; 4], 0); + d.extend_from_slice(&[0, 0, 255, 0, 255, 0, 0, 0, 0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); + assert!(crate::decode(&dib_to_bmp(&d).unwrap()).is_ok()); + let mut c = core(8); + c.truncate(12); + c.extend((0..256 * 3).map(|i| i as u8)); + c.extend_from_slice(&[0, 1, 0, 0, 2, 3, 0, 0]); + assert!(crate::decode(&dib_to_bmp(&c).unwrap()).is_ok()); + } + + /// 1x1 32-bit BI_BITFIELDS DIB, one pixel B=10 G=20 R=30 A=128, with the given header size. + fn one_pixel(size: u32) -> Vec { + let mut d = info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 0); + d[4..8].copy_from_slice(&1i32.to_le_bytes()); + d[8..12].copy_from_slice(&1i32.to_le_bytes()); + if size == 40 { + for m in [0xFF0000u32, 0xFF00, 0xFF] { + d.extend_from_slice(&m.to_le_bytes()); + } + } + d.extend_from_slice(&[10, 20, 30, 128]); + d + } + + #[test] + fn bitfields_pixel_offset_for_each_header_size_decodes() { + for size in [40u32, 52, 56] { + let bmp = dib_to_bmp(&one_pixel(size)).unwrap(); + let off = 14 + size + if size == 40 { 12 } else { 0 }; + assert_eq!(dib_u32(&bmp, 10), Some(off), "offset for {size}"); + let img = crate::decode(&bmp).unwrap_or_else(|e| panic!("{size}-byte header: {e:?}")); + let rgba = img.to_rgba8(); + assert_eq!(&rgba[..3], &[30, 20, 10], "size {size}"); + if size == 56 { + assert_eq!(rgba[3], 128); + } + } + // V5: the header's masks, a copy inserted by `dib_layout`, then the pixel. + let bmp = dib_to_bmp(&dib_layout(one_pixel(124))).unwrap(); + assert_eq!(&crate::decode(&bmp).unwrap().to_rgba8()[..4], &[30, 20, 10, 128]); + } + + #[test] + fn exact_length_pixels_equal_to_the_masks_are_not_a_mask_copy() { + let d = v5_3x1(false); + let laid = dib_layout(d.clone()); + assert_eq!(laid.len(), d.len() + 12); + assert_eq!(laid[124..136], d[40..52]); + assert_eq!(oracle_dib_layout(d).len(), laid.len() - 12, "the original skipped the insertion"); + let img = crate::decode(&dib_to_bmp(&laid).unwrap()).unwrap().to_rgba8(); + assert_eq!(img.len(), 12); + // pixel 0 is 0x00FF0000 (blue 0, green 0, red 255 under the masks). + assert_eq!(&img[..3], &[255, 0, 0]); + // A real copy followed by the pixels is left alone. + let real = v5_3x1(true); + assert_eq!(dib_layout(real.clone()), real); + assert!(crate::decode(&dib_to_bmp(&real).unwrap()).is_ok()); + } + + #[test] + fn layout_decides_before_it_mutates() { + // BI_RGB V5 with an alpha mask and no colour masks: promoted and given a copy together. + let mut d = info(124, 32, 0, 0, [0, 0, 0, 0xFF00_0000], 16); + d[4..8].copy_from_slice(&2i32.to_le_bytes()); + let laid = dib_layout(d.clone()); + assert_eq!(laid.len(), d.len() + 12); + assert_eq!(dib_u32(&laid, 16), Some(3)); + // Unreadable dimensions keep the byte-equality rule. + let mut odd = info(108, 32, 3, 0, [1, 2, 3, 0], 0); + odd[4..8].copy_from_slice(&(-1i32).to_le_bytes()); + let copy = odd[40..52].to_vec(); + odd.extend_from_slice(©); + assert_eq!(dib_layout(odd.clone()), odd); + } } From 8d5c939e203fbbd7cd7543f0d4e79043b9a500a5 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 14:46:32 -0500 Subject: [PATCH 85/97] psd: use fixed-size guide chunks for strict clippy --- crates/psd/src/guides.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/crates/psd/src/guides.rs b/crates/psd/src/guides.rs index f122c7805..2b654ec8f 100644 --- a/crates/psd/src/guides.rs +++ b/crates/psd/src/guides.rs @@ -27,7 +27,7 @@ impl GuideV1 { /// Encode a legacy resource header. Grid cycles and count are caller supplied. pub fn header_v1(horizontal_cycle: u32, vertical_cycle: u32, count: u32) -> [u8; 16] { let mut out = [0; 16]; - for (chunk, value) in out.chunks_exact_mut(4).zip([1u32, horizontal_cycle, vertical_cycle, count]) { + for (chunk, value) in out.as_chunks_mut::<4>().0.iter_mut().zip([1u32, horizontal_cycle, vertical_cycle, count]) { chunk.copy_from_slice(&value.to_be_bytes()); } out @@ -40,7 +40,9 @@ pub fn parse_v1_prefix(data: &[u8]) -> impl Iterator + '_ { let count = be_u32(data, 12).unwrap_or(0); data.get(16..) .unwrap_or_default() - .chunks_exact(5) + .as_chunks::<5>() + .0 + .iter() .zip(0..count) .map(|(g, _)| GuideV1 { location: i32::from_be_bytes([g[0], g[1], g[2], g[3]]), direction: g[4] }) } From 408ab93329f35bb05b27883dfb6e966c0d788f95 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Wed, 18 Nov 2026 04:01:51 +0800 Subject: [PATCH 86/97] Preserve SVG siblings and share embedded-image validation --- Cargo.lock | 1 - crates/image-codecs/src/codecs/jpeg.rs | 30 +++++ crates/image-codecs/src/lib.rs | 1 + crates/svg/Cargo.toml | 6 +- crates/svg/README.md | 47 ++++--- crates/svg/src/tree.rs | 138 ++++++++++++-------- crates/svg/src/tree/draw.rs | 2 + crates/svg/src/tree/draw/decoder_edges.rs | 13 +- crates/svg/src/tree/draw/raster.rs | 68 ++++------ crates/svg/src/tree/draw/raster_tests.rs | 4 - crates/svg/src/tree/image_href.rs | 40 +++++- crates/svg/src/tree/tests.rs | 10 +- crates/svg/src/tree/validated.rs | 141 +++++++++++---------- crates/svg/src/tree/validated/tests.rs | 78 +++++++----- crates/svg/src/tree/validated/xml_tests.rs | 30 +++++ 15 files changed, 370 insertions(+), 239 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 4da6cf6c9..90f2450ed 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3103,7 +3103,6 @@ dependencies = [ "usvg 0.48.1", "vectorcraft-geom", "vectorcraft-pathops", - "zune-jpeg", ] [[package]] diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index 415a5d717..ef6601a58 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -46,6 +46,36 @@ pub(crate) struct JpegMeta { pub held_coefficients: u64, } +/// Validate a JPEG by decoding the 8-bit RGBA output used by renderers. +/// +/// This deliberately uses the existing zune backend's default decode policy. +/// Unlike general JPEG import it does not fall back to additional JPEG modes, +/// apply orientation, or retain pixels. The caller supplies the admitted pixel count. +pub fn validate_jpeg_rgba8(bytes: &[u8], max_pixels: u64) -> Result<(), CodecError> { + let decode = || { + let options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA); + let mut decoder = zune_jpeg::JpegDecoder::new_with_options(std::io::Cursor::new(bytes), options); + decoder.decode_headers().map_err(|error| CodecError::malformed(F, format_args!("{error:?}")))?; + let info = decoder.info().ok_or_else(|| CodecError::malformed(F, "missing frame dimensions"))?; + let pixels = u64::from(info.width) * u64::from(info.height); + if pixels == 0 { + return Err(CodecError::malformed(F, "empty frame")); + } + if pixels > max_pixels { + return Err(CodecError::LimitExceeded("JPEG exceeds the admitted pixel count".into())); + } + let length = usize::try_from(pixels * 4).map_err(|_| CodecError::LimitExceeded("JPEG RGBA output is too large".into()))?; + if decoder.output_colorspace() != Some(ColorSpace::RGBA) || decoder.output_buffer_size() != Some(length) { + return Err(CodecError::malformed(F, "unexpected RGBA output")); + } + let mut output = Vec::new(); + output.try_reserve_exact(length).map_err(|_| CodecError::LimitExceeded("could not allocate JPEG RGBA output".into()))?; + output.resize(length, 0); + decoder.decode_into(&mut output).map_err(|error| CodecError::malformed(F, format_args!("{error:?}"))) + }; + std::panic::catch_unwind(decode).map_err(|_| CodecError::malformed(F, "JPEG decoder failed on this frame"))? +} + /// The first frame of `b` as [`crate::JpegInfo`], from its markers alone (see [`crate::jpeg_info`]). pub(crate) fn info(b: &[u8]) -> Option { let m = scan_metadata(b); diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index dc2ac2933..231197b61 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -45,6 +45,7 @@ pub use crate::cicp::ContentLightLevel; pub use crate::codecs::avif::{HDR_REFERENCE_WHITE_NITS, HdrTransfer, encode_avif_hdr, encode_avif_with_speed}; pub use crate::codecs::exr_cryptomatte::{cryptomatte_id, cryptomatte_key, cryptomatte_preview_color}; pub use crate::codecs::gif_frames::{AnimationFrame, MAX_GIF_FRAMES}; +pub use crate::codecs::jpeg::validate_jpeg_rgba8; pub use crate::codecs::png::{ PngDecodeRows, PngExtras, PngHeader, PngPalette, PngRowSink, PngRows, SharedBytes, encode_indexed as encode_png_indexed, encode_pq as encode_png_pq, palette as png_palette, stereo as png_stereo, diff --git a/crates/svg/Cargo.toml b/crates/svg/Cargo.toml index 4b7e928a8..eb5e01c91 100644 --- a/crates/svg/Cargo.toml +++ b/crates/svg/Cargo.toml @@ -32,9 +32,7 @@ resvg = { version = "=0.48.1", default-features = false, features = ["text", "ra data-url = { version = "0.3.2", optional = true } # Renderer-specific validation uses the same resolved backends as resvg0.48.1. -# zune-jpeg is used under its MIT licence option. The locked edge-alignment -# regression must pass when changing this renderer/backend dependency group. -zune-jpeg = { version = "=0.5.15", optional = true } +# JPEG validation uses the existing backend in craft-image-codecs. gif = { version = "=0.14.2", optional = true } image-webp = { version = "=0.2.4", optional = true } @@ -52,7 +50,7 @@ tree-text = ["tree", "usvg/text"] # The system's fonts in `usvg::fontdb`. tree-system-fonts = ["tree-text", "usvg/system-fonts"] # Bounded rendering of a parsed tree through the matching resvg/tiny-skia versions. -tree-render = ["tree", "dep:resvg", "dep:zune-jpeg", "dep:gif", "dep:image-webp"] +tree-render = ["tree", "dep:resvg", "dep:gif", "dep:image-webp"] tree-render-system-fonts = ["tree-render", "resvg/system-fonts"] [dev-dependencies] diff --git a/crates/svg/README.md b/crates/svg/README.md index 519015c1b..a82d88028 100644 --- a/crates/svg/README.md +++ b/crates/svg/README.md @@ -26,20 +26,19 @@ raster validation. Existing `ImageResolver::new`/`resolver` and legacy parse ent points retain their behavior. Opt in explicitly: ```rust -# #[cfg(feature = "tree-render")] -# fn example() -> Result<(), craft_svg::tree::Error> { -use craft_svg::tree::{self, Limits, ValidatedImageResolver, usvg}; -let images = ValidatedImageResolver::new(Limits::default()); -let checked = tree::preflight( - "", - &images.limits(), -)?; -let drawing = images.parse_preflight(checked, usvg::Options::default())?; -let usage = images.usage(); -// Importers disclose usage's invalid_* and *_limit_images; strict consumers refuse them. -# let _ = (drawing, usage); -# Ok(()) -# } +fn example() -> Result<(), craft_svg::tree::Error> { + use craft_svg::tree::{self, Limits, ValidatedImageResolver, usvg}; + let images = ValidatedImageResolver::new(Limits::default()); + let checked = tree::preflight( + "", + &images.limits(), + )?; + let drawing = images.parse_preflight(checked, usvg::Options::default())?; + let usage = images.usage(); + // Importers disclose usage's invalid_* and *_limit_images; strict consumers refuse them. + let _ = (drawing, usage); + Ok(()) +} ``` The caller supplies fonts and a sufficient stack/worker for its depth policy. @@ -53,11 +52,14 @@ An overlapping root conversion on the same context is refused. Unchanged XML converts from its original checked DOM. A modified data URL requires one checked replacement DOM. Invalid URLs become bounded resolver-visible image -failures; hidden, unused and foreign elements do not acquire omission counts. +failures. The normal path counts only resolved images. If a repair cannot fit, +the checked original can still convert when all its MIME headers meet the work +limit. In that case malformed image declarations are counted conservatively. Original UTF-8 child bytes are charged before XML conversion or shorter repairs, -with per-document and aggregate bounds. Failed inflation/text work is not refunded; -separate bounded retry-classification work never admits another child. Encoded -raster callbacks spend at most `limits.bytes + limits.embedded_bytes` cumulatively, +with per-document and aggregate bounds. A malformed plain encoding spends its +input bytes and leaves the remaining work for siblings. Failed inflation can +exhaust its attempted allowance, and the separate bounded retry classification +never admits another child. Encoded raster callbacks spend at most `limits.bytes + limits.embedded_bytes` cumulatively, without retaining their sources. Pixel work and decoder allocation are admitted before decoding; attempted failures keep their charge. An oversized unattempted image does not prevent a later smaller image from fitting. @@ -67,9 +69,6 @@ context, rather than an unchecked DOM or a precharged-budget override. `usage()` reports omissions and work after conversion. The context is for one drawing, not a global rendering cache. -The renderer has no public decoded-pixel or decode-result hook. Validation therefore -still decodes raster pixels before later renderer painting. The shared validator -owns the backend dependencies; locked dependency-edge tests in both the shared -workspace and consumers must keep them aligned with the selected resvg/usvg graph. -This is a fail-fast maintenance check, not automatic access to private renderer -code or a decode-once performance claim. Direct zune-jpeg use selects its MIT option. +The validator uses the existing JPEG backend in craft-image-codecs. The lockfile +test checks that it and the other validation backends match the selected resvg +dependency edges. resvg decodes the image again when it paints. diff --git a/crates/svg/src/tree.rs b/crates/svg/src/tree.rs index 690320e82..3a549e773 100644 --- a/crates/svg/src/tree.rs +++ b/crates/svg/src/tree.rs @@ -22,10 +22,10 @@ //! 16 MB or so, and a 1 MB stack takes a depth of about 34. use std::borrow::Cow; +use std::collections::HashMap; use std::collections::hash_map::Entry; -use std::collections::{HashMap, HashSet}; use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering}; -use std::sync::{Arc, Mutex, PoisonError}; +use std::sync::{Arc, Mutex, PoisonError, Weak}; pub use usvg; @@ -70,9 +70,9 @@ pub struct Limits { pub embedded_bytes: usize, /// SVG documents embedded inside one another, for [`image_resolver`]. pub embedded_depth: usize, - /// Decoded RGBA pixels retained across the raster images embedded in one drawing. Dimensions - /// are probed before usvg hands the bytes to a decoder; repeated references to the same data - /// URL share one charge. + /// Cumulative raster decode pixels for a drawing. usvg sends each data-URL + /// resolution separately, so repeated uses normally spend a separate charge. + /// The legacy resolver can share a charge for the same live input allocation. pub embedded_raster_pixels: u64, } @@ -437,7 +437,7 @@ struct Used { svg_count: AtomicUsize, svg_depth: AtomicUsize, raster_pixels: AtomicU64, - raster_data: Mutex>, + raster_data: Mutex>>>, invalid_raster: AtomicUsize, raster_limit: AtomicUsize, invalid_svg: AtomicUsize, @@ -493,7 +493,7 @@ impl ImageResolver { svg_count: AtomicUsize::new(0), svg_depth: AtomicUsize::new(0), raster_pixels: AtomicU64::new(0), - raster_data: Mutex::new(HashSet::new()), + raster_data: Mutex::new(HashMap::new()), invalid_raster: AtomicUsize::new(0), raster_limit: AtomicUsize::new(0), invalid_svg: AtomicUsize::new(0), @@ -561,28 +561,51 @@ fn account_invalid_data_urls(xml: &roxmltree::Document<'_>, used: &Used) { } } -fn raster_format(data: &[u8]) -> Option { - match craft_image_codecs::detect(data)? { - format @ (craft_image_codecs::Format::Png - | craft_image_codecs::Format::Jpeg - | craft_image_codecs::Format::Gif - | craft_image_codecs::Format::WebP) => Some(format), +#[derive(Clone, Copy)] +enum SvgRaster { + Png, + Jpeg, + Gif, + WebP, +} + +impl SvgRaster { + fn codec(self) -> craft_image_codecs::Format { + match self { + Self::Png => craft_image_codecs::Format::Png, + Self::Jpeg => craft_image_codecs::Format::Jpeg, + Self::Gif => craft_image_codecs::Format::Gif, + Self::WebP => craft_image_codecs::Format::WebP, + } + } + + fn image_kind(self, data: Arc>) -> usvg::ImageKind { + match self { + Self::Png => usvg::ImageKind::PNG(data), + Self::Jpeg => usvg::ImageKind::JPEG(data), + Self::Gif => usvg::ImageKind::GIF(data), + Self::WebP => usvg::ImageKind::WEBP(data), + } + } +} + +/// Match supported raster signatures to the MIME types both image resolvers accept. +fn declared_raster(mime: &str, data: &[u8]) -> Option { + use craft_image_codecs::Format; + match (mime, craft_image_codecs::detect(data)?) { + ("image/png" | "text/plain", Format::Png) => Some(SvgRaster::Png), + ("image/jpg" | "image/jpeg" | "text/plain", Format::Jpeg) => Some(SvgRaster::Jpeg), + ("image/gif" | "text/plain", Format::Gif) => Some(SvgRaster::Gif), + ("image/webp" | "text/plain", Format::WebP) => Some(SvgRaster::WebP), _ => None, } } -fn raster_image(used: &Used, limits: &Limits, data: Arc>, format: craft_image_codecs::Format) -> Option { +fn raster_image(used: &Used, limits: &Limits, data: Arc>, format: SvgRaster) -> Option { let Ok((width, height)) = craft_image_codecs::probe_allocation_size(&data) else { used.invalid_raster.fetch_add(1, Ordering::Relaxed); return None; }; - if !matches!( - format, - craft_image_codecs::Format::Png | craft_image_codecs::Format::Jpeg | craft_image_codecs::Format::Gif | craft_image_codecs::Format::WebP - ) { - used.invalid_raster.fetch_add(1, Ordering::Relaxed); - return None; - } let pixels = u64::from(width).checked_mul(u64::from(height))?; if pixels == 0 || pixels > limits.embedded_raster_pixels { used.raster_limit.fetch_add(1, Ordering::Relaxed); @@ -590,12 +613,11 @@ fn raster_image(used: &Used, limits: &Limits, data: Arc>, format: craft_ } let pointer = Arc::as_ptr(&data) as usize; let mut seen = used.raster_data.lock().unwrap_or_else(PoisonError::into_inner); - if seen.insert(pointer) { + if let Entry::Vacant(entry) = seen.entry(pointer) { let mut current = used.raster_pixels.load(Ordering::Relaxed); loop { let next = current.checked_add(pixels)?; if next > limits.embedded_raster_pixels { - seen.remove(&pointer); used.raster_limit.fetch_add(1, Ordering::Relaxed); return None; } @@ -604,13 +626,16 @@ fn raster_image(used: &Used, limits: &Limits, data: Arc>, format: craft_ Err(actual) => current = actual, } } + // The weak reference pins the allocation identity, not its encoded bytes. + // At most one entry is added for each nonrefundable pixel charge. + entry.insert(Arc::downgrade(&data)); } drop(seen); // A valid header is not proof of valid pixels. resvg can silently omit a damaged // image later; decode now under explicit limits so omission accounting is honest. let decode_limits = craft_image_codecs::Limits::new(width, height, pixels, limits.embedded_raster_pixels.saturating_mul(8)); let options = craft_image_codecs::DecodeOptions { limits: decode_limits, keep_orientation: true }; - if let Err(error) = craft_image_codecs::decode_as_with(format, &data, &options) { + if let Err(error) = craft_image_codecs::decode_as_with(format.codec(), &data, &options) { // No tree retains this allocation on failure. Forget its address before it // can be reused, but keep the pixel charge for the decode work already spent. used.raster_data.lock().unwrap_or_else(PoisonError::into_inner).remove(&pointer); @@ -624,15 +649,37 @@ fn raster_image(used: &Used, limits: &Limits, data: Arc>, format: craft_ } return None; } - Some(match format { - craft_image_codecs::Format::Png => usvg::ImageKind::PNG(data), - craft_image_codecs::Format::Jpeg => usvg::ImageKind::JPEG(data), - craft_image_codecs::Format::Gif => usvg::ImageKind::GIF(data), - craft_image_codecs::Format::WebP => usvg::ImageKind::WEBP(data), - _ => return None, + Some(format.image_kind(data)) +} + +/// Decode one child within the original byte allowance, including encoding expansion. +fn embedded_text<'a>(data: &'a [u8], room: usize, limits: &Limits) -> Result, svgz::Error> { + let text = svgz::text(data, room.min(limits.bytes))?; + if text.len() > room { + return Err(svgz::Error::TooLarge(room)); + } + Ok(text) +} + +enum ChildRefusal { + Depth, + Bytes, + Invalid, +} + +fn preflight_child<'a>(text: &'a str, limits: &Limits) -> Result, ChildRefusal> { + preflight(text, limits).map_err(|error| match error { + Error::TooDeep(_) => ChildRefusal::Depth, + Error::Text(svgz::Error::TooLarge(_)) => ChildRefusal::Bytes, + _ => ChildRefusal::Invalid, }) } +/// Reserve the complete checked height within the parent's remaining XML room. +fn child_total_depth(parent: usize, checked: &Preflight<'_>, limits: &Limits) -> Option { + parent.checked_add(checked.height).filter(|depth| *depth <= limits.tree_depth) +} + /// An embedded SVG document, if the budgets allow it. fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<'_>) -> Option { if used.depth.load(Ordering::Relaxed) >= limits.embedded_depth { @@ -641,7 +688,7 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<' return None; } let left = limits.embedded_bytes.saturating_sub(used.bytes.load(Ordering::Relaxed)); - let text = match svgz::text(data, left.min(limits.bytes)) { + let text = match embedded_text(data, left, limits) { Ok(text) => text, // What a refused document unpacked before it was refused was work too: it uses up what // is left, so the next image can't repeat it. @@ -654,25 +701,17 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<' return None; } }; - // The raw/inflated bytes can fit while UTF-16/Latin-1 decoding expands - // beyond the aggregate allowance. A refusal consumes the remaining work. - if text.len() > left { - used.bytes.fetch_add(left, Ordering::Relaxed); - used.svg_limit.fetch_add(1, Ordering::Relaxed); - used.svg_resource_limit.fetch_add(1, Ordering::Relaxed); - return None; - } used.bytes.fetch_add(text.len(), Ordering::Relaxed); - let checked = match preflight(&text, limits) { + let checked = match preflight_child(&text, limits) { Ok(checked) => checked, // Decoding UTF-16 or Latin-1 can exceed the text cap after the // raw/inflated bytes fitted. This is a resource refusal, not invalid XML. - Err(Error::Text(svgz::Error::TooLarge(_))) => { + Err(ChildRefusal::Bytes) => { used.svg_limit.fetch_add(1, Ordering::Relaxed); used.svg_resource_limit.fetch_add(1, Ordering::Relaxed); return None; } - Err(Error::TooDeep(_)) => { + Err(ChildRefusal::Depth) => { used.svg_limit.fetch_add(1, Ordering::Relaxed); return None; } @@ -682,9 +721,7 @@ fn embedded(used: &Used, limits: &Limits, data: &[u8], options: &usvg::Options<' } }; // The nesting usvg converts, references followed, not the source depth alone. - let xml_depth = checked.height; - let total_depth = used.xml_depth.load(Ordering::Relaxed).checked_add(xml_depth); - let Some(total_depth) = total_depth.filter(|depth| *depth <= limits.tree_depth) else { + let Some(total_depth) = child_total_depth(used.xml_depth.load(Ordering::Relaxed), &checked, limits) else { used.svg_limit.fetch_add(1, Ordering::Relaxed); return None; }; @@ -719,16 +756,7 @@ pub fn image_resolver(limits: Limits) -> usvg::ImageHrefResolver<'static> { fn image_resolver_for(limits: Limits, used: Arc) -> usvg::ImageHrefResolver<'static> { usvg::ImageHrefResolver { resolve_data: Box::new(move |mime, data, options| { - let detected = raster_format(&data); - let format = match mime { - "image/jpg" | "image/jpeg" => (detected == Some(craft_image_codecs::Format::Jpeg)).then_some(craft_image_codecs::Format::Jpeg), - "image/png" => (detected == Some(craft_image_codecs::Format::Png)).then_some(craft_image_codecs::Format::Png), - "image/gif" => (detected == Some(craft_image_codecs::Format::Gif)).then_some(craft_image_codecs::Format::Gif), - "image/webp" => (detected == Some(craft_image_codecs::Format::WebP)).then_some(craft_image_codecs::Format::WebP), - "text/plain" => detected, - _ => None, - }; - if let Some(format) = format { + if let Some(format) = declared_raster(mime, &data) { return raster_image(&used, &limits, data, format); } // usvg can decode only the raster variants above. Count every other declared diff --git a/crates/svg/src/tree/draw.rs b/crates/svg/src/tree/draw.rs index 8a8bb1a7a..642a3888b 100644 --- a/crates/svg/src/tree/draw.rs +++ b/crates/svg/src/tree/draw.rs @@ -33,6 +33,8 @@ pub use resvg::tiny_skia; mod raster; #[cfg(feature = "tree-render")] pub use raster::{RasterValidationFailure, validate_raster}; +#[cfg(feature = "tree-render")] +pub(super) use raster::{decode_raster, probe_raster_pixels}; /// Filter primitives per filter. A result of every primitive is kept; real filters have 1 to 12 /// (Inkscape's drop shadow has 5), and 64 leaves headroom for generated ones. diff --git a/crates/svg/src/tree/draw/decoder_edges.rs b/crates/svg/src/tree/draw/decoder_edges.rs index ce6543b81..f83130cec 100644 --- a/crates/svg/src/tree/draw/decoder_edges.rs +++ b/crates/svg/src/tree/draw/decoder_edges.rs @@ -73,9 +73,15 @@ impl LockGraph { pub(crate) fn assert_renderer_edges(graph: &LockGraph, svg: &PackageId) { let renderer = graph.dependency(svg, "resvg"); assert_eq!(graph.dependency(svg, "usvg"), graph.dependency(&renderer, "usvg"), "shared and renderer trees must be the same resolved package"); - for codec in ["gif", "image-webp", "zune-jpeg"] { + for codec in ["gif", "image-webp"] { assert_eq!(graph.dependency(svg, codec), graph.dependency(&renderer, codec), "validator and selected renderer differ for {codec}"); } + let codecs = graph.dependency(svg, "craft-image-codecs"); + assert_eq!( + graph.dependency(&codecs, "zune-jpeg"), + graph.dependency(&renderer, "zune-jpeg"), + "JPEG validator and renderer must use the same backend" + ); } #[test] @@ -116,7 +122,10 @@ dependencies = ["codec"] fn selected_renderer_graph_rejects_a_split_validator_backend() { use std::fmt::Write; let make = |split: bool| { - let mut text = String::from("[[package]]\nname='craft-svg'\nversion='1'\ndependencies=['resvg', 'usvg', 'gif', 'image-webp', '"); + let mut text = String::from( + "[[package]]\nname='craft-svg'\nversion='1'\ndependencies=['resvg', 'usvg', 'gif', 'image-webp', 'craft-image-codecs']\n\ + [[package]]\nname='craft-image-codecs'\nversion='1'\ndependencies=['", + ); text.push_str(if split { "zune-jpeg 2" } else { "zune-jpeg 1" }); text.push_str( "']\n[[package]]\nname='resvg'\nversion='1'\nsource='registry+one'\ndependencies=['usvg', 'gif', 'image-webp', 'zune-jpeg 1']\n", diff --git a/crates/svg/src/tree/draw/raster.rs b/crates/svg/src/tree/draw/raster.rs index ffeb0d684..48bff6ae9 100644 --- a/crates/svg/src/tree/draw/raster.rs +++ b/crates/svg/src/tree/draw/raster.rs @@ -6,7 +6,7 @@ use std::io::Cursor; use std::num::NonZeroU64; -use crate::tree::{draw::tiny_skia, usvg}; +use crate::tree::{SvgRaster, draw::tiny_skia, usvg}; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum RasterValidationFailure { @@ -20,28 +20,41 @@ pub enum RasterValidationFailure { /// Failed attempted decodes keep their pixel charge. No decoded pixels are retained. SVG /// children use the same wrapped resolver and need no second recursive walk. pub fn validate_raster(kind: &usvg::ImageKind, max_pixels: u64, pixels_left: &mut u64) -> Result<(), RasterValidationFailure> { - let data = match kind { - usvg::ImageKind::PNG(data) | usvg::ImageKind::JPEG(data) | usvg::ImageKind::GIF(data) | usvg::ImageKind::WEBP(data) => data, + let (format, data) = match kind { + usvg::ImageKind::PNG(data) => (SvgRaster::Png, data), + usvg::ImageKind::JPEG(data) => (SvgRaster::Jpeg, data), + usvg::ImageKind::GIF(data) => (SvgRaster::Gif, data), + usvg::ImageKind::WEBP(data) => (SvgRaster::WebP, data), usvg::ImageKind::SVG(_) => return Ok(()), }; - // The allocation probe includes oversized GIF/WebP frames, not merely their - // canvas. Reserve before asking any rendering decoder to allocate pixels. + let pixels = probe_raster_pixels(data, max_pixels)?; + *pixels_left = pixels_left.checked_sub(pixels).ok_or(RasterValidationFailure::Limit)?; + decode_raster(format, data, pixels) +} + +pub(in crate::tree) fn probe_raster_pixels(data: &[u8], max_pixels: u64) -> Result { + // The allocation probe accounts for oversized GIF/WebP frames as well as the canvas. let (width, height) = craft_image_codecs::probe_allocation_size(data).map_err(|_| RasterValidationFailure::Invalid)?; let pixels = area(width, height)?; if pixels > max_pixels { return Err(RasterValidationFailure::Limit); } - *pixels_left = pixels_left.checked_sub(pixels).ok_or(RasterValidationFailure::Limit)?; - match kind { - usvg::ImageKind::PNG(data) => { + Ok(pixels) +} + +pub(in crate::tree) fn decode_raster(format: SvgRaster, data: &[u8], pixels: u64) -> Result<(), RasterValidationFailure> { + match format { + SvgRaster::Png => { let decoded = tiny_skia::Pixmap::decode_png(data).map_err(|_| RasterValidationFailure::Invalid)?; rgba_bytes(decoded.width(), decoded.height(), pixels)?; Ok(()) } - usvg::ImageKind::JPEG(data) => jpeg(data, pixels), - usvg::ImageKind::GIF(data) => gif(data, pixels), - usvg::ImageKind::WEBP(data) => webp(data, pixels), - usvg::ImageKind::SVG(_) => Ok(()), + SvgRaster::Jpeg => craft_image_codecs::validate_jpeg_rgba8(data, pixels).map_err(|error| match error { + craft_image_codecs::CodecError::LimitExceeded(_) => RasterValidationFailure::Limit, + _ => RasterValidationFailure::Invalid, + }), + SvgRaster::Gif => gif(data, pixels), + SvgRaster::WebP => webp(data, pixels), } } @@ -68,24 +81,6 @@ fn buffer(length: usize) -> Result, RasterValidationFailure> { Ok(output) } -fn jpeg(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { - use zune_jpeg::zune_core::colorspace::ColorSpace; - use zune_jpeg::zune_core::options::DecoderOptions; - - // Preserve the rendering decoder's default limits and RGBA conversion; a - // general photo decoder may accept formats the SVG renderer cannot draw. - let options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA); - let mut decoder = zune_jpeg::JpegDecoder::new_with_options(Cursor::new(data), options); - decoder.decode_headers().map_err(|_| RasterValidationFailure::Invalid)?; - let info = decoder.info().ok_or(RasterValidationFailure::Invalid)?; - let length = rgba_bytes(u32::from(info.width), u32::from(info.height), admitted)?; - if decoder.output_colorspace() != Some(ColorSpace::RGBA) || decoder.output_buffer_size() != Some(length) { - return Err(RasterValidationFailure::Invalid); - } - let mut output = buffer(length)?; - decoder.decode_into(&mut output).map_err(|_| RasterValidationFailure::Invalid) -} - fn gif(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { let bytes = admitted.checked_mul(4).ok_or(RasterValidationFailure::Limit)?; // Do not loosen the renderer's default 50 MB GIF frame limit. Smaller @@ -115,19 +110,12 @@ fn webp(data: &[u8], admitted: u64) -> Result<(), RasterValidationFailure> { let (width, height) = decoder.dimensions(); let rgba = rgba_bytes(width, height, admitted)?; let channels = if decoder.has_alpha() { 4 } else { 3 }; - let expected = usize::try_from(area(width, height)?.checked_mul(channels).ok_or(RasterValidationFailure::Limit)?) - .map_err(|_| RasterValidationFailure::Limit)?; - if expected > rgba { - return Err(RasterValidationFailure::Limit); - } + let expected = rgba / 4 * channels; if decoder.output_buffer_size() != Some(expected) { return Err(RasterValidationFailure::Invalid); } - // A small valid image can have a compressed chunk larger than its pixels. - // Bound decoder scratch without rejecting that ordinary encoding overhead. - let admitted_bytes = - usize::try_from(admitted.checked_mul(4).ok_or(RasterValidationFailure::Limit)?).map_err(|_| RasterValidationFailure::Limit)?; - decoder.set_memory_limit(admitted_bytes.max(data.len())); + // The decoder's metadata memory limit does not cap read_image scratch. + // Admit the frame and exact output buffer before calling read_image. let mut output = buffer(expected)?; decoder.read_image(&mut output).map_err(webp_error) } diff --git a/crates/svg/src/tree/draw/raster_tests.rs b/crates/svg/src/tree/draw/raster_tests.rs index 273705744..be84e4738 100644 --- a/crates/svg/src/tree/draw/raster_tests.rs +++ b/crates/svg/src/tree/draw/raster_tests.rs @@ -132,10 +132,6 @@ fn renderer_validator_rejects_corrupt_pixels_after_valid_dimensions_without_refu for (format, data, dimensions) in cases { assert_eq!(craft_image_codecs::probe_allocation_size(&data).unwrap(), dimensions, "{format:?}"); match format { - Format::Jpeg => { - let mut headers = zune_jpeg::JpegDecoder::new(Cursor::new(&data)); - headers.decode_headers().expect("intact JPEG scan headers before unavailable pixel-decode table"); - } Format::Gif => { gif::DecodeOptions::new().read_info(data.as_slice()).expect("intact GIF headers before corrupt LZW pixels"); } diff --git a/crates/svg/src/tree/image_href.rs b/crates/svg/src/tree/image_href.rs index d33388846..620289a80 100644 --- a/crates/svg/src/tree/image_href.rs +++ b/crates/svg/src/tree/image_href.rs @@ -36,11 +36,7 @@ pub(super) fn normalize<'a>(checked: &super::Preflight<'a>) -> Result()).min(usize::try_from(limits.xml_nodes).unwrap_or(usize::MAX)); let mut patches: Vec = Vec::new(); for node in xml.descendants().filter(|node| node.is_element()) { @@ -99,6 +95,30 @@ pub(super) fn normalize<'a>(checked: &super::Preflight<'a>) -> Result) -> Option { + let mut work = checked.xml.input_text().len().saturating_add(checked.limits.entity_bytes).saturating_mul(6); + let mut omitted = 0usize; + for node in checked.xml.descendants().filter(|node| node.is_element() && matches!(node.tag_name().name(), "image" | "feImage")) { + for href in node.attributes().filter(|a| a.name() == "href" && matches!(a.namespace(), None | Some(XLINK_NS))) { + let value = href.value(); + work = work.checked_sub(value.len())?; + if !mime_header_admitted(value) { + return None; + } + } + if let Some(value) = node.attribute((XLINK_NS, "href")).or_else(|| node.attribute("href")) + && malformed_data_url_replacement(value, &mut work).ok()? == Some(INVALID_IMAGE) + { + omitted = omitted.saturating_add(1); + } + } + Some(omitted) +} + // The pinned MIME parser searches all earlier parameters for each new name. // Cap even quoted semicolons before invoking it: source-byte work is already // charged, so at most this constant times the bounded XML work reaches MIME @@ -295,6 +315,16 @@ mod tests { Limits { bytes: 1 << 20, depth: 32, tree_depth: 32, entity_bytes: 65_536, ..Default::default() } } + #[test] + fn original_dom_fallback_does_not_bypass_mime_admission() { + let ordinary = ""; + assert_eq!(unrepaired_image_omissions(&super::super::preflight(ordinary, &limits()).unwrap()), Some(1)); + + let header = "a=b;".repeat(MAX_MIME_SEPARATORS + 1); + let excessive = format!(""); + assert!(unrepaired_image_omissions(&super::super::preflight(&excessive, &limits()).unwrap()).is_none()); + } + #[test] fn malformed_image_urls_are_repaired_in_both_svg_namespaces_and_filter_resources() { for tag in ["image", "feImage"] { diff --git a/crates/svg/src/tree/tests.rs b/crates/svg/src/tree/tests.rs index abdf0f772..7663ab301 100644 --- a/crates/svg/src/tree/tests.rs +++ b/crates/svg/src/tree/tests.rs @@ -547,7 +547,7 @@ mod invalid_image_accounting { } #[test] - fn failed_decode_forgets_address_but_preserves_spent_budget() { + fn failed_decode_releases_input_but_preserves_spent_budget() { let valid = png(); let idat = valid.windows(4).position(|b| b == b"IDAT").unwrap(); let invalid = Arc::new(valid[..idat + 4].to_vec()); @@ -555,11 +555,12 @@ mod invalid_image_accounting { let limits = Limits { embedded_raster_pixels: 3, ..shallow() }; let resolver = ImageResolver::new(limits); let used = &resolver.used; - let format = craft_image_codecs::Format::Png; + let format = SvgRaster::Png; assert!(raster_image(used, &limits, invalid, format).is_none()); - assert!(!used.raster_data.lock().unwrap().contains(&pointer)); + assert!(!used.raster_data.lock().unwrap().contains_key(&pointer)); assert_eq!(resolver.usage().raster_pixels, 1); let first_data = Arc::new(valid.clone()); + let first_pointer = Arc::as_ptr(&first_data) as usize; let first = raster_image(used, &limits, first_data.clone(), format).unwrap(); assert_eq!(resolver.usage().raster_pixels, 2); let repeated = raster_image(used, &limits, first_data, format).unwrap(); @@ -569,6 +570,9 @@ mod invalid_image_accounting { assert!(raster_image(used, &limits, Arc::new(valid), format).is_none()); assert_eq!(resolver.usage().raster_limit_images, 1); drop((first, repeated, second)); + let seen = used.raster_data.lock().unwrap(); + let identity = seen.get(&first_pointer).expect("the cache holds the allocation identity"); + assert!(identity.upgrade().is_none(), "the cache must not retain encoded bytes"); } #[test] diff --git a/crates/svg/src/tree/validated.rs b/crates/svg/src/tree/validated.rs index a09aa3929..c6c591f5d 100644 --- a/crates/svg/src/tree/validated.rs +++ b/crates/svg/src/tree/validated.rs @@ -1,6 +1,10 @@ //! Opt-in complete image validation and checked-DOM normalization. //! Legacy ImageResolver entry points retain their existing behavior. -use super::{Error, ImageUsage, Limits, Preflight, image_href, preflight, raster_format, usvg}; +use super::draw::{RasterValidationFailure, decode_raster, probe_raster_pixels}; +use super::{ + ChildRefusal, Error, ImageUsage, Limits, Preflight, child_total_depth, declared_raster, embedded_text, image_href, preflight, preflight_child, + usvg, +}; use crate::svgz; use std::sync::{Arc, Mutex, PoisonError}; @@ -125,33 +129,6 @@ impl State { self.svg_resource_limits = self.svg_resource_limits.saturating_add(1); } } - - fn raster(&mut self, kind: &usvg::ImageKind) -> bool { - let encoded = match kind { - usvg::ImageKind::SVG(_) => return true, - usvg::ImageKind::PNG(data) | usvg::ImageKind::JPEG(data) | usvg::ImageKind::GIF(data) | usvg::ImageKind::WEBP(data) => data, - }; - // usvg supplies a fresh Arc for every data-URL resolution, including - // repeated instances. Charge each actual validation, never retain - // encoded buffers in an address-keyed memo that cannot hit this boundary. - let Some(left) = self.encoded_left.checked_sub(encoded.len()) else { - self.raster_limits = self.raster_limits.saturating_add(1); - return false; - }; - self.encoded_left = left; - let result = super::draw::validate_raster(kind, self.pixel_limit, &mut self.pixels_left); - match result { - Ok(()) => true, - Err(super::draw::RasterValidationFailure::Invalid) => { - self.invalid_raster = self.invalid_raster.saturating_add(1); - false - } - Err(super::draw::RasterValidationFailure::Limit) => { - self.raster_limits = self.raster_limits.saturating_add(1); - false - } - } - } } /// One opt-in drawing's image work, normalization and exact rendering validation. @@ -196,7 +173,7 @@ impl ValidatedImageResolver { // contributes its complete checked height, as in legacy child admission. let _scope = self.root_scope(checked.height.saturating_sub(1))?; options.image_href_resolver = self.resolver(); - convert_checked(checked, &options) + self.convert_checked(checked, &options) } /// Resolve an already-decoded child SVG, charging original text before XML @@ -224,24 +201,8 @@ impl ValidatedImageResolver { usvg::ImageHrefResolver { resolve_string: Box::new(|_, _| None), resolve_data: Box::new(move |mime, data, options| { - let detected = raster_format(&data); - let format = match mime { - "image/jpg" | "image/jpeg" => (detected == Some(craft_image_codecs::Format::Jpeg)).then_some(craft_image_codecs::Format::Jpeg), - "image/png" => (detected == Some(craft_image_codecs::Format::Png)).then_some(craft_image_codecs::Format::Png), - "image/gif" => (detected == Some(craft_image_codecs::Format::Gif)).then_some(craft_image_codecs::Format::Gif), - "image/webp" => (detected == Some(craft_image_codecs::Format::WebP)).then_some(craft_image_codecs::Format::WebP), - "text/plain" => detected, - _ => None, - }; - if let Some(format) = format { - let kind = match format { - craft_image_codecs::Format::Png => usvg::ImageKind::PNG(data), - craft_image_codecs::Format::Jpeg => usvg::ImageKind::JPEG(data), - craft_image_codecs::Format::Gif => usvg::ImageKind::GIF(data), - craft_image_codecs::Format::WebP => usvg::ImageKind::WEBP(data), - _ => return None, - }; - return this.state.lock().unwrap_or_else(PoisonError::into_inner).raster(&kind).then_some(kind); + if let Some(format) = declared_raster(mime, &data) { + return this.raster_with(&data, |pixels| decode_raster(format, &data, pixels)).then(|| format.image_kind(data)); } if !matches!(mime, "image/svg+xml" | "text/plain") { if mime.starts_with("image/") { @@ -255,6 +216,33 @@ impl ValidatedImageResolver { } } + fn raster_with(&self, data: &[u8], decode: impl FnOnce(u64) -> Result<(), RasterValidationFailure>) -> bool { + let result = self.reserve_raster(data).and_then(decode); + if let Err(error) = result { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + match error { + RasterValidationFailure::Invalid => state.invalid_raster = state.invalid_raster.saturating_add(1), + RasterValidationFailure::Limit => state.raster_limits = state.raster_limits.saturating_add(1), + } + return false; + } + true + } + + fn reserve_raster(&self, data: &[u8]) -> Result { + { + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + // usvg uses a fresh Arc for each data-URL callback. Each actual validation + // spends encoded work, including when the header or decoder refuses it. + state.encoded_left = state.encoded_left.checked_sub(data.len()).ok_or(RasterValidationFailure::Limit)?; + } + let pixels = probe_raster_pixels(data, self.limits.embedded_raster_pixels)?; + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + state.pixels_left = state.pixels_left.checked_sub(pixels).ok_or(RasterValidationFailure::Limit)?; + // The caller decodes after releasing the mutex. The work stays charged. + Ok(pixels) + } + fn can_start_child(&self) -> bool { let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); if state.depth >= self.limits.embedded_depth { @@ -277,15 +265,24 @@ impl ValidatedImageResolver { } state.svg_bytes_left }; - let text = match svgz::text(data, room.min(self.limits.bytes)) { - Ok(text) if text.len() <= room => text, - error => { + let text = match embedded_text(data, room, &self.limits) { + Ok(text) => text, + Err(error) => { let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + if matches!(error, svgz::Error::Encoding) && !crate::sniff::is_svgz(data) { + // Plain text validation can spend at most the input's bytes. + // An invalid encoding does not exhaust a later sibling's room. + state.svg_bytes_left = state.svg_bytes_left.saturating_sub(data.len()); + state.invalid_svg = state.invalid_svg.saturating_add(1); + return None; + } state.svg_bytes_left = 0; - if matches!(error, Err(svgz::Error::TooLarge(_))) || error.is_ok() { + if matches!(error, svgz::Error::TooLarge(_)) { state.svg_limits = state.svg_limits.saturating_add(1); state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); } else { + // An unreadable compressed stream may have used the entire + // allowed inflation work. Later callbacks can only classify. state.invalid_svg = state.invalid_svg.saturating_add(1); state.svg_failure_exhausted = true; state.classification_content_left = room; @@ -316,24 +313,24 @@ impl ValidatedImageResolver { // an attribute or conversion subsequently fails. state.svg_bytes_left = left; } - let checked = match preflight(text, &self.limits) { + let checked = match preflight_child(text, &self.limits) { Ok(checked) => checked, Err(error) => { let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); match error { - Error::TooDeep(_) => state.svg_limits = state.svg_limits.saturating_add(1), - Error::Text(svgz::Error::TooLarge(_)) => { + ChildRefusal::Depth => state.svg_limits = state.svg_limits.saturating_add(1), + ChildRefusal::Bytes => { state.svg_limits = state.svg_limits.saturating_add(1); state.svg_resource_limits = state.svg_resource_limits.saturating_add(1); } - _ => state.invalid_svg = state.invalid_svg.saturating_add(1), + ChildRefusal::Invalid => state.invalid_svg = state.invalid_svg.saturating_add(1), } return None; } }; let scope = { let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); - let Some(total) = state.xml_depth.checked_add(checked.height).filter(|depth| *depth <= self.limits.tree_depth) else { + let Some(total) = child_total_depth(state.xml_depth, &checked, &self.limits) else { state.svg_limits = state.svg_limits.saturating_add(1); return None; }; @@ -345,7 +342,7 @@ impl ValidatedImageResolver { state.svg_depth = state.svg_depth.max(state.depth); Scope { state: Arc::clone(&self.state), previous, child: true } }; - let result = convert_checked(checked, options); + let result = self.convert_checked(checked, options); drop(scope); let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); match result { @@ -359,6 +356,25 @@ impl ValidatedImageResolver { } } } + fn convert_checked(&self, checked: Preflight<'_>, options: &usvg::Options<'_>) -> Result { + match image_href::normalize(&checked) { + Ok(std::borrow::Cow::Borrowed(_)) => checked.parse(options), + Ok(std::borrow::Cow::Owned(text)) => { + let limits = checked.limits; + drop(checked); + preflight(&text, &limits)?.parse(options) + } + Err(repair_error) => { + // Keep the original checked DOM if its URLs are safe to pass to + // usvg. Malformed optional URLs are dropped by its parser. + let omitted = image_href::unrepaired_image_omissions(&checked).ok_or(repair_error)?; + let tree = checked.parse(options)?; + let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner); + state.invalid_raster = state.invalid_raster.saturating_add(omitted); + Ok(tree) + } + } + } } struct Scope { @@ -378,17 +394,6 @@ impl Drop for Scope { } } -fn convert_checked(checked: Preflight<'_>, options: &usvg::Options<'_>) -> Result { - match image_href::normalize(&checked)? { - std::borrow::Cow::Borrowed(_) => checked.parse(options), - std::borrow::Cow::Owned(text) => { - let limits = checked.limits; - drop(checked); - preflight(&text, &limits)?.parse(options) - } - } -} - #[cfg(test)] mod tests; diff --git a/crates/svg/src/tree/validated/tests.rs b/crates/svg/src/tree/validated/tests.rs index c090d7ab6..7eaa47dab 100644 --- a/crates/svg/src/tree/validated/tests.rs +++ b/crates/svg/src/tree/validated/tests.rs @@ -15,9 +15,6 @@ fn test_limits(pixels: u64) -> Limits { ..Default::default() } } -fn test_state(pixels: u64) -> State { - State::new(test_limits(pixels)) -} fn wrapped_options(pixels: u64) -> (usvg::Options<'static>, Arc>, Arc) { let resolver = Arc::new(ValidatedImageResolver::new(test_limits(pixels))); let options = usvg::Options { image_href_resolver: resolver.resolver(), ..Default::default() }; @@ -184,40 +181,51 @@ fn failed_raster_callbacks_release_sources_and_keep_every_decode_charge() { let idat = broken.windows(4).position(|bytes| bytes == b"IDAT").unwrap(); broken[idat + 4] ^= 1; assert_eq!(craft_image_codecs::probe_allocation_size(&broken).unwrap(), (2, 2)); - let mut state = test_state(8); - let encoded_before = state.encoded_left; + let (options, state, resolver) = wrapped_options(8); + let encoded_before = state.lock().unwrap().encoded_left; for attempt in 1..=2 { // Match usvg's actual callback boundary: each href gets a new Arc. let encoded = Arc::new(broken.clone()); let weak = Arc::downgrade(&encoded); - let kind = usvg::ImageKind::PNG(Arc::clone(&encoded)); - assert!(!state.raster(&kind)); - assert_eq!(state.pixels_left, 8 - attempt * 4); - assert_eq!(state.encoded_left, encoded_before - attempt as usize * encoded.len()); - assert_eq!(state.invalid_raster, attempt as usize); - drop(kind); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::clone(&encoded), &options).is_none()); + let usage = resolver.usage(); + assert_eq!(usage.raster_pixels, attempt * 4); + assert_eq!(state.lock().unwrap().encoded_left, encoded_before - attempt as usize * encoded.len()); + assert_eq!(usage.invalid_raster_images, attempt as usize); drop(encoded); assert!(weak.upgrade().is_none(), "validation must not retain failed callback buffers until parse completion"); } - assert!(!state.raster(&usvg::ImageKind::PNG(Arc::new(png())))); - assert_eq!((state.invalid_raster, state.raster_limits), (2, 1)); - assert_eq!(state.usage().raster_pixels, 8); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::new(png()), &options).is_none()); + let usage = resolver.usage(); + assert_eq!((usage.invalid_raster_images, usage.raster_limit_images, usage.raster_pixels), (2, 1, 8)); } #[test] fn valid_raster_callbacks_spend_exact_pixel_and_encoded_allowances_per_call() { let encoded = Arc::new(png()); - let kind = usvg::ImageKind::PNG(Arc::clone(&encoded)); - let mut state = test_state(8); - state.encoded_left = encoded.len() * 2; - assert!(state.raster(&kind)); - assert_eq!((state.pixels_left, state.encoded_left), (4, encoded.len())); - assert!(state.raster(&kind), "even a directly reused Arc is a new actual validation call"); - assert_eq!((state.pixels_left, state.encoded_left), (0, 0)); - assert!(!state.raster(&kind)); - assert_eq!((state.invalid_raster, state.raster_limits), (0, 1)); - let usage = state.usage(); - assert_eq!((usage.raster_pixels, usage.raster_limit_images), (8, 1)); + let (options, state, resolver) = wrapped_options(8); + let call = || (options.image_href_resolver.resolve_data)("image/png", Arc::clone(&encoded), &options); + state.lock().unwrap().encoded_left = encoded.len() * 2; + assert!(call().is_some()); + assert_eq!(resolver.usage().raster_pixels, 4); + assert_eq!(state.lock().unwrap().encoded_left, encoded.len()); + assert!(call().is_some(), "even a directly reused Arc is a new actual validation call"); + assert_eq!(state.lock().unwrap().encoded_left, 0); + assert!(call().is_none()); + let usage = resolver.usage(); + assert_eq!((usage.raster_pixels, usage.invalid_raster_images, usage.raster_limit_images), (8, 0, 1)); +} + +#[test] +fn raster_decode_happens_after_the_work_is_charged_and_mutex_released() { + let (_, state, resolver) = wrapped_options(4); + let image = png(); + assert!(resolver.raster_with(&image, |admitted| { + assert_eq!(admitted, 4); + assert!(state.try_lock().is_ok(), "a usage snapshot must not wait for the raster decode"); + assert_eq!(resolver.usage().raster_pixels, 4); + Ok(()) + })); } #[test] @@ -237,13 +245,14 @@ fn encoded_raster_refusal_is_per_image_and_does_not_consume_unattempted_work() { let bytes = png(); let mut oversized = bytes.clone(); oversized.extend([0; 32]); - let mut state = test_state(4); - state.encoded_left = bytes.len(); - assert!(!state.raster(&usvg::ImageKind::PNG(Arc::new(oversized)))); - assert_eq!((state.encoded_left, state.pixels_left), (bytes.len(), 4)); - assert!(state.raster(&usvg::ImageKind::PNG(Arc::new(bytes)))); - assert_eq!((state.encoded_left, state.pixels_left), (0, 0)); - let usage = state.usage(); + let (options, state, resolver) = wrapped_options(4); + state.lock().unwrap().encoded_left = bytes.len(); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::new(oversized), &options).is_none()); + assert_eq!(state.lock().unwrap().encoded_left, bytes.len()); + assert_eq!(resolver.usage().raster_pixels, 0); + assert!((options.image_href_resolver.resolve_data)("image/png", Arc::new(bytes), &options).is_some()); + assert_eq!(state.lock().unwrap().encoded_left, 0); + let usage = resolver.usage(); assert_eq!((usage.raster_pixels, usage.raster_limit_images, usage.invalid_raster_images), (4, 1, 0)); } @@ -285,7 +294,10 @@ fn plain_legacy_encoding_rechecks_have_a_separate_bounded_work_allowance() { bytes.to_vec() } }; - assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encode(&[0xff])), &options).is_none()); + // A failed compressed decode exhausts the primary pool. The + // callbacks under test may use plain or compressed encodings. + let invalid = Arc::new(crate::svgz::compress(&[0xff])); + assert!((options.image_href_resolver.resolve_data)("image/svg+xml", invalid, &options).is_none()); state.lock().unwrap_or_else(PoisonError::into_inner).classification_text_bytes_left = xml.len(); assert!((options.image_href_resolver.resolve_data)("image/svg+xml", Arc::new(encode(xml)), &options).is_none()); { diff --git a/crates/svg/src/tree/validated/xml_tests.rs b/crates/svg/src/tree/validated/xml_tests.rs index e0ea41aca..e156c42e6 100644 --- a/crates/svg/src/tree/validated/xml_tests.rs +++ b/crates/svg/src/tree/validated/xml_tests.rs @@ -42,6 +42,36 @@ fn parse_count(text: &str, limits: Limits) -> (super::super::ImageUsage, usize) (context.usage(), PREFLIGHT_PASSES.with(|count| count.get())) } +#[test] +fn malformed_plain_child_leaves_work_for_valid_siblings() { + let child = drawing(""); + for invalid in [&[0xff][..], &[0xff, 0xfe, 0xd8][..]] { + let contents = format!("{}{}", image(&url(invalid)), image(&url(child.as_bytes()))); + let root = drawing(&contents); + let limits = Limits { embedded_bytes: invalid.len() + child.len(), ..Default::default() }; + let context = ValidatedImageResolver::new(limits); + let tree = context.parse_preflight(preflight(&root, &limits).unwrap(), usvg::Options::default()).unwrap(); + let usage = context.usage(); + assert_eq!((usage.invalid_svg_images, usage.embedded_svg_count, usage.svg_limit_images), (1, 1, 0)); + assert_eq!(usage.embedded_svg_bytes, limits.embedded_bytes); + let mut pixmap = super::super::draw::tiny_skia::Pixmap::new(4, 4).unwrap(); + super::super::draw::resvg::render(&tree, Default::default(), &mut pixmap.as_mut()); + assert_eq!(pixmap.pixel(2, 2).unwrap().red(), 255); + } +} + +#[test] +fn a_malformed_image_at_the_svg_byte_cap_does_not_drop_the_drawing() { + let root = drawing(""); + let limits = Limits { bytes: root.len(), ..Default::default() }; + let context = ValidatedImageResolver::new(limits); + let tree = context.parse_preflight(preflight(&root, &limits).unwrap(), usvg::Options::default()).unwrap(); + assert_eq!(context.usage().invalid_raster_images, 1); + let mut pixmap = super::super::draw::tiny_skia::Pixmap::new(4, 4).unwrap(); + super::super::draw::resvg::render(&tree, Default::default(), &mut pixmap.as_mut()); + assert_eq!(pixmap.pixel(2, 2).unwrap().red(), 255); +} + #[test] fn validated_root_reuses_checked_xml_and_rechecks_only_changed_attributes() { let ordinary = drawing(""); From 6413cbb8060d55d0514adfe8e883904b441426d5 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Wed, 18 Nov 2026 04:34:32 +0800 Subject: [PATCH 87/97] Guard SVG JPEG validation on panic-abort builds --- crates/image-codecs/src/codecs/jpeg.rs | 53 ++++++++++++++++++++------ 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index ef6601a58..7f9cdaeaa 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -52,6 +52,15 @@ pub(crate) struct JpegMeta { /// Unlike general JPEG import it does not fall back to additional JPEG modes, /// apply orientation, or retain pixels. The caller supplies the admitted pixel count. pub fn validate_jpeg_rgba8(bytes: &[u8], max_pixels: u64) -> Result<(), CodecError> { + validate_jpeg_rgba8_with_panic_policy(bytes, max_pixels, cfg!(panic = "abort")) +} + +fn validate_jpeg_rgba8_with_panic_policy(bytes: &[u8], max_pixels: u64, panic_aborts: bool) -> Result<(), CodecError> { + // The decoder can assert while upsampling these frames. On abort builds the + // unwind guard below cannot turn that assertion into an image omission. + if panic_aborts && first_component_subsampled(bytes) { + return Err(CodecError::malformed(F, "JPEG first component is subsampled below the frame maximum")); + } let decode = || { let options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA); let mut decoder = zune_jpeg::JpegDecoder::new_with_options(std::io::Cursor::new(bytes), options); @@ -1103,25 +1112,45 @@ mod tests { (v * 65535.0 / 4095.0).round() as u16 } + fn progressive_frame_header(comps: &[(u8, u8)]) -> Vec { + let mut s = vec![0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC2, 0, (8 + 3 * comps.len()) as u8, 8, 0, 8, 0, 8, comps.len() as u8]; + for (i, &(h, v)) in comps.iter().enumerate() { + s.extend([i as u8 + 1, (h << 4) | v, 0]); + } + s + } + #[test] fn first_component_subsampling() { - let sof = |comps: &[(u8, u8)]| { - let mut s = vec![0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC2, 0, (8 + 3 * comps.len()) as u8, 8, 0, 8, 0, 8, comps.len() as u8]; - for (i, &(h, v)) in comps.iter().enumerate() { - s.extend([i as u8 + 1, (h << 4) | v, 0]); - } - s - }; - assert!(first_component_subsampled(&sof(&[(1, 1), (1, 1), (1, 1), (2, 2)]))); - assert!(first_component_subsampled(&sof(&[(1, 2), (1, 2), (2, 1)]))); - assert!(!first_component_subsampled(&sof(&[(2, 2), (1, 1), (1, 1)]))); - assert!(!first_component_subsampled(&sof(&[(1, 1); 4]))); - assert!(!first_component_subsampled(&sof(&[]))); + assert!(first_component_subsampled(&progressive_frame_header(&[(1, 1), (1, 1), (1, 1), (2, 2)]))); + assert!(first_component_subsampled(&progressive_frame_header(&[(1, 2), (1, 2), (2, 1)]))); + assert!(!first_component_subsampled(&progressive_frame_header(&[(2, 2), (1, 1), (1, 1)]))); + assert!(!first_component_subsampled(&progressive_frame_header(&[(1, 1); 4]))); + assert!(!first_component_subsampled(&progressive_frame_header(&[]))); assert!(!first_component_subsampled(&[0xFF, 0xD8, 0xFF, 0xDA, 0, 2])); assert!(!first_component_subsampled(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 20, 8])); assert!(!first_component_subsampled(b"not a jpeg")); } + #[test] + fn renderer_validation_refuses_unsafe_sampling_under_abort_policy() { + // The frame header alone exercises refusal before any pixel decode. + let header = progressive_frame_header(&[(1, 1), (1, 1), (1, 1), (2, 2)]); + let refuses_sampling = |result| { + matches!( + result, + Err(CodecError::Malformed { format: Format::Jpeg, message }) + if message == "JPEG first component is subsampled below the frame maximum" + ) + }; + assert!(refuses_sampling(validate_jpeg_rgba8_with_panic_policy(&header, 64, true))); + assert!(!refuses_sampling(validate_jpeg_rgba8_with_panic_policy(&header, 64, false))); + + let mut ordinary = Vec::new(); + jpeg_encoder::Encoder::new(&mut ordinary, 90).encode(&[128], 1, 1, jpeg_encoder::ColorType::Luma).unwrap(); + validate_jpeg_rgba8_with_panic_policy(&ordinary, 1, true).unwrap(); + } + #[test] fn routing() { assert!(!uses_craft_jpeg(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11, 8, 0, 8, 0, 8, 1, 1, 0x11, 0])); From 1d5255e07f2463ea784860505e1f7ce68d6adffd Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 15:48:26 -0500 Subject: [PATCH 88/97] vectordrawable: bound configurable XML depth with iterative writing --- crates/vectordrawable/src/write.rs | 135 +++++++++++++++++++++++++---- 1 file changed, 116 insertions(+), 19 deletions(-) diff --git a/crates/vectordrawable/src/write.rs b/crates/vectordrawable/src/write.rs index ec14fca97..5a883df77 100644 --- a/crates/vectordrawable/src/write.rs +++ b/crates/vectordrawable/src/write.rs @@ -13,6 +13,10 @@ use crate::model::{Cap, Color, Fill, GradientKind, Group, Item, ItemKind, Join, /// never recurses without bound. Android Studio's own drawables nest a handful of levels. pub const MAX_DEPTH: usize = 256; +/// Hard ceiling for [`document_with_depth_limit`]. A caller may need extra XML groups for +/// transforms and clips around each bounded application layer, but cannot disable the guard. +pub const MAX_CONFIGURED_DEPTH: usize = 1024; + const ANDROID: &str = "http://schemas.android.com/apk/res/android"; const AAPT: &str = "http://schemas.android.com/aapt"; @@ -110,18 +114,37 @@ impl Out { } /// Whether a path that is written (see [`MAX_DEPTH`]) has a gradient fill. -fn uses_gradient(items: &[Item], depth: usize) -> bool { - items.iter().any(|it| match &it.kind { - ItemKind::Path(p) => matches!(p.fill, Some(Fill::Gradient(_))), - ItemKind::Group(g) => depth < MAX_DEPTH && uses_gradient(&g.children, depth + 1), - }) +fn uses_gradient(items: &[Item], max_depth: usize) -> bool { + let mut pending = vec![(1, items.iter())]; + while let Some((depth, items)) = pending.last_mut() { + let depth = *depth; + match items.next().map(|it| &it.kind) { + Some(ItemKind::Path(p)) if matches!(p.fill, Some(Fill::Gradient(_))) => return true, + Some(ItemKind::Group(g)) if depth < max_depth => pending.push((depth + 1, g.children.iter())), + Some(_) => {} + None => { + pending.pop(); + } + } + } + false } /// The whole file: a `width`×`height` dp drawable with a viewport of the same size. pub fn document(width: f64, height: f64, items: &[Item]) -> String { + document_with_depth_limit(width, height, items, MAX_DEPTH) +} + +/// Write with a caller-selected XML group depth cap, clamped to `1..=MAX_CONFIGURED_DEPTH`. +/// +/// A group at the cap keeps its attributes and clip but not its children. The default +/// [`document`] cap is unchanged. Use this when one bounded source layer projects to several +/// XML wrapper groups; the caller must include those wrappers in its depth calculation. +pub fn document_with_depth_limit(width: f64, height: f64, items: &[Item], max_depth: usize) -> String { + let max_depth = max_depth.clamp(1, MAX_CONFIGURED_DEPTH); let mut o = Out { s: String::from("\n") }; let mut attrs = vec![("xmlns:android", ANDROID.to_string())]; - if uses_gradient(items, 1) { + if uses_gradient(items, max_depth) { attrs.push(("xmlns:aapt", AAPT.to_string())); } attrs.extend([ @@ -135,21 +158,35 @@ pub fn document(width: f64, height: f64, items: &[Item]) -> String { // Android refuses a without a ("no path defined"): one empty, unfilled path. o.open(1, "path", &[("android:pathData", "M0,0".to_string())], true); } - for it in items { - item(&mut o, 1, it); - } + write_items(&mut o, items, max_depth); o.close(0, "vector"); o.s } -fn item(o: &mut Out, depth: usize, it: &Item) { - match &it.kind { - ItemKind::Path(p) => path(o, depth, p), - ItemKind::Group(g) => group(o, depth, g), +fn write_items(o: &mut Out, items: &[Item], max_depth: usize) { + // One iterator per open group, not one pending entry per sibling. The configured depth + // bounds this stack, and wide documents do not require a second list of their items. + let mut pending = vec![(1, items.iter())]; + while let Some((depth, items)) = pending.last_mut() { + let depth = *depth; + match items.next().map(|it| &it.kind) { + Some(ItemKind::Path(p)) => path(o, depth, p), + Some(ItemKind::Group(g)) => { + if group(o, depth, g, max_depth) { + pending.push((depth + 1, g.children.iter())); + } + } + None => { + pending.pop(); + if depth > 1 { + o.close(depth - 1, "group"); + } + } + } } } -fn group(o: &mut Out, depth: usize, g: &Group) { +fn group(o: &mut Out, depth: usize, g: &Group, max_depth: usize) -> bool { let mut attrs = Vec::new(); if let Some(n) = &g.name { attrs.push(("android:name", esc(n))); @@ -172,19 +209,21 @@ fn group(o: &mut Out, depth: usize, g: &Group) { attrs.push(("android:translateY", num(x.translate.1))); } } - let children: &[Item] = if depth < MAX_DEPTH { &g.children } else { &[] }; + let children: &[Item] = if depth < max_depth { &g.children } else { &[] }; if children.is_empty() && g.clip.is_none() { o.open(depth, "group", &attrs, true); - return; + return false; } o.open(depth, "group", &attrs, false); if let Some(c) = &g.clip { o.open(depth + 1, "clip-path", &[("android:pathData", path_data(c))], true); } - for c in children { - item(o, depth + 1, c); + if children.is_empty() { + o.close(depth, "group"); + false + } else { + true } - o.close(depth, "group"); } fn stroke_attrs(attrs: &mut Vec<(&str, String)>, s: &Stroke) { @@ -445,3 +484,61 @@ mod tests { assert!(xml.contains(" Item { + let mut item = Item { + bbox: Rect::ZERO, + kind: ItemKind::Path(Path { + name: Some("deep".into()), + data: BezPath::new(), + stroke: None, + even_odd: false, + fill: Some(Fill::Gradient(Gradient { kind: GradientKind::Sweep { center: (0.0, 0.0) }, stops: vec![] })), + }), + }; + for _ in 0..groups { + item = Item { bbox: Rect::ZERO, kind: ItemKind::Group(Group { name: None, transform: None, clip: None, children: vec![item] }) }; + } + item + } + + #[test] + fn expanded_source_layers_keep_their_leaf_and_namespace() { + let items = [nested(514)]; + assert!(!document(1.0, 1.0, &items).contains("aapt")); + let xml = document_with_depth_limit(1.0, 1.0, &items, 516); + assert_eq!(xml.matches(" Date: Tue, 17 Nov 2026 15:49:47 -0500 Subject: [PATCH 89/97] Deduplicate JUMP destination resolution in the payability walkers --- crates/evm/src/lib.rs | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 502e451e1..2b1b089d5 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -677,6 +677,13 @@ pub fn analyze(code: &[u8]) -> Result { }) } +/// Resolve the destination of a JUMP to an instruction index, when the PUSH right before it is +/// readable and lands on an instruction boundary. +fn jump_destination(code: &[u8], ins: &[Ins], k: usize, index_of: &dyn Fn(usize) -> Option) -> Option { + let push = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op))?; + index_of(usize::try_from(imm_u64(code, push)?).ok()?) +} + /// Follow a function's entry for a few instructions (and up to two unconditional jumps) looking /// for a CALLVALUE check. fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) -> Option) -> (&'static str, String) { @@ -686,17 +693,14 @@ fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) - let Some(i) = ins.get(k) else { break }; match i.op { 0x34 if rejects_value(code, ins, k, index_of) => return ("nonpayable", format!("rejects nonzero CALLVALUE at {:#x}", i.off)), - 0x56 => { - let target = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op)).and_then(|p| imm_u64(code, p)); - match target.and_then(|t| index_of(usize::try_from(t).ok()?)) { - Some(t) if hops < 2 => { - hops += 1; - k = t; - continue; - } - _ => return ("unknown", "jumps somewhere we cannot follow before any CALLVALUE check".into()), + 0x56 => match jump_destination(code, ins, k, index_of) { + Some(t) if hops < 2 => { + hops += 1; + k = t; + continue; } - } + _ => return ("unknown", "jumps somewhere we cannot follow before any CALLVALUE check".into()), + }, 0x57 => return ("unknown", "branches before any CALLVALUE check".into()), 0xfd | 0xfe => return ("unknown", "halts with an error before any CALLVALUE check".into()), 0x00 | 0xf3 | 0xff | 0x35 | 0x37 | 0x54 | 0x55 | 0xf1 | 0xf4 | 0xfa | 0xa0..=0xa4 => { @@ -735,17 +739,14 @@ fn reverts_soon(code: &[u8], ins: &[Ins], mut k: usize, index_of: &dyn Fn(usize) let Some(i) = ins.get(k) else { return false }; match i.op { 0xfd | 0xfe => return true, - 0x56 => { - let target = k.checked_sub(1).and_then(|p| ins.get(p)).filter(|p| is_push(p.op)).and_then(|p| imm_u64(code, p)); - match target.and_then(|t| index_of(usize::try_from(t).ok()?)) { - Some(t) if hops < 2 => { - hops += 1; - k = t; - continue; - } - _ => return false, + 0x56 => match jump_destination(code, ins, k, index_of) { + Some(t) if hops < 2 => { + hops += 1; + k = t; + continue; } - } + _ => return false, + }, 0x5b | 0x50 | 0x80..=0x9f | 0x5f | 0x60..=0x7f => {} _ => return false, } From 6815dd6b7c1c5b5df02cc4d8c24201a830c57625 Mon Sep 17 00:00:00 2001 From: Terra854 Date: Wed, 18 Nov 2026 04:58:02 +0800 Subject: [PATCH 90/97] Find JPEG sampling headers after marker padding --- crates/image-codecs/src/codecs/jpeg.rs | 27 ++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index 7f9cdaeaa..d14974d7e 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -379,10 +379,17 @@ fn first_component_subsampled(b: &[u8]) -> bool { return false; } let mut i = 2; - while let (Some(&0xFF), Some(&m)) = (b.get(i), b.get(i + 1)) { + while let Some(&prefix) = b.get(i) { + // The decoder searches forward between segments. Stray bytes and + // stuffed FF 00 pairs must not hide a frame from the abort-build guard. + if prefix != 0xFF { + i += 1; + continue; + } + let Some(&m) = b.get(i + 1) else { return false }; match m { 0xFF => i += 1, - 0x01 | 0xD0..=0xD8 => i += 2, + 0x00 | 0x01 | 0xD0..=0xD8 => i += 2, 0xD9 | 0xDA => return false, _ => { let Some(len) = b.get(i + 2..i + 4).map(|l| usize::from(u16::from_be_bytes([l[0], l[1]]))) else { return false }; @@ -1151,6 +1158,22 @@ mod tests { validate_jpeg_rgba8_with_panic_policy(&ordinary, 1, true).unwrap(); } + #[test] + fn jpeg_sampling_guard_finds_frame_after_marker_padding() { + let header = progressive_frame_header(&[(1, 1), (1, 1), (1, 1), (2, 2)]); + // Exercise the shared header guard, without a pixel payload. + for split in [2, 8] { + let (before, after) = header.split_at(split); + for padding in [&[0][..], &[0x7F, 0][..], &[0xFF, 0][..], &[0xFF][..]] { + let padded = [before, padding, after].concat(); + assert!(first_component_subsampled(&padded), "offset {split}, padding {padding:?}"); + let got = validate_jpeg_rgba8_with_panic_policy(&padded, 64, true); + assert!(matches!(got, Err(CodecError::Malformed { message, .. }) if message.contains("frame maximum"))); + } + } + assert!(!first_component_subsampled(&[0xFF, 0xD8, 0, 0xFF])); + } + #[test] fn routing() { assert!(!uses_craft_jpeg(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11, 8, 0, 8, 0, 8, 1, 1, 0x11, 0])); From 971e8ad8f8f3dee5d171516c28ffbccef665cf03 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 16:00:45 -0500 Subject: [PATCH 91/97] jpeg: add tokenless two-pass baseline encoding --- crates/jpeg/src/encode.rs | 127 ++++++++++++++--- crates/jpeg/src/encode_low_memory_tests.rs | 155 +++++++++++++++++++++ crates/jpeg/src/lib.rs | 2 +- 3 files changed, 261 insertions(+), 23 deletions(-) create mode 100644 crates/jpeg/src/encode_low_memory_tests.rs diff --git a/crates/jpeg/src/encode.rs b/crates/jpeg/src/encode.rs index 548f4c9f9..fb5fe183c 100644 --- a/crates/jpeg/src/encode.rs +++ b/crates/jpeg/src/encode.rs @@ -419,6 +419,34 @@ pub fn encode_baseline( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], ) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode(data, width, height, channels, quality, sub, app_segments)) +} + +/// Encode the same optimized baseline JPEG as [`encode_baseline`], trading a second DCT pass +/// for working memory independent of image height. This path is sequential even when the +/// `parallel` feature is enabled. It retains only one MCU row of conversion planes and writes +/// directly into the returned encoded buffer: no image-wide tokens or duplicate coded buffer. +/// +/// Scratch consists of at most `24 * width + 8` floats (odd-width 4:2:0), plus fixed-size coding tables. +/// The caller still owns the input pixels and the returned JPEG; this is not a cap on output +/// size or a replacement for the caller's image/admission budget. Geometry, quality, metadata, +/// Huffman tables and restart boundaries match [`encode_baseline`] byte for byte. +#[allow(clippy::too_many_arguments)] +pub fn encode_baseline_low_memory( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], +) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode_impl(data, width, height, channels, quality, sub, app_segments, true, true)) +} + +fn validate_encode(data: &[u8], width: usize, height: usize, channels: usize, app_segments: &[(u8, Vec)]) -> Result<(), EncodeError> { let fits = width.checked_mul(height).and_then(|n| n.checked_mul(channels)).is_some_and(|n| n <= data.len()); if !fits || width == 0 || height == 0 || width > 65_535 || height > 65_535 || !matches!(channels, 1 | 3 | 4) { return Err(EncodeError::InvalidInput(format!("{width}x{height}, {channels} channels, {} bytes", data.len()))); @@ -426,7 +454,7 @@ pub fn encode_baseline( if app_segments.iter().any(|(marker, payload)| !(0xE0..=0xEF).contains(marker) || payload.len() > 65_533) { return Err(EncodeError::InvalidInput("APP markers must be 0xE0..=0xEF with payloads no larger than 65533 bytes".into())); } - Ok(encode(data, width, height, channels, quality, sub, app_segments)) + Ok(()) } /// [`encode`], with optimized Huffman tables or (`optimize` false) the Annex K example tables. @@ -440,6 +468,21 @@ fn encode_with( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], optimize: bool, +) -> Vec { + encode_impl(data, width, height, channels, quality, sub, app_segments, optimize, false) +} + +#[allow(clippy::too_many_arguments)] +fn encode_impl( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], + optimize: bool, + low_memory: bool, ) -> Vec { // The public entry takes caller-sized dimensions: refuse (an empty output) what would size an allocation from // them or index past `data`, rather than panic or allocate for them. @@ -509,6 +552,8 @@ fn encode_with( planes.push(Plane { w: cw, h: crows.len(), data: cb }); planes.push(Plane { w: cw, h: crows.len(), data: cr }); } + #[cfg(test)] + low_memory_tests::record_planes(planes.iter().map(|p| p.data.len()).sum()); planes }; @@ -519,45 +564,58 @@ fn encode_with( let (mx, my) = (width.div_ceil(mcu_w), height.div_ceil(mcu_h)); // restart interval: whole MCU rows per band, ≤ 65535 MCUs, enough bands to keep all cores busy let rows_per_band = (my / 64).clamp(1, (65_535 / mx.max(1)).max(1)); - let bands: Vec = (0..my.div_ceil(rows_per_band)).collect(); + let num_bands = my.div_ceil(rows_per_band); + let bands: Vec = if low_memory { Vec::new() } else { (0..num_bands).collect() }; // first pass: each band's quantized blocks as symbols, with their counts per table (DC // prediction restarts per band, as the restart markers say) - let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let visit_band = |band: &usize, emit: &mut dyn FnMut(&[i16; 64], &mut i32, bool)| { let (mut blk, mut q) = ([0f32; 64], [0i16; 64]); - let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); let mut pred = [0i32; 3]; let (m0, m1) = (band * rows_per_band, ((band + 1) * rows_per_band).min(my)); - // the band's planes, its MCU row `m0` at their top (blocks past the image's bottom repeat its last row, - // which is the band's last row then) - let planes = convert(m0 * mcu_h..(m1 * mcu_h).min(height), m0 * 8..(m1 * 8).min(ch)); for mcu_y in m0..m1 { - let mcu_y = mcu_y - m0; + // Convert only the current MCU row. DC predictors still span the original band, + // so its symbols/restart decisions are identical to whole-band conversion. + let planes = convert(mcu_y * mcu_h..((mcu_y + 1) * mcu_h).min(height), mcu_y * 8..((mcu_y + 1) * 8).min(ch)); for mcu_x in 0..mx { for vy in 0..vs { for hx in 0..hs { - planes[0].block(mcu_x * hs + hx, mcu_y * vs + vy, &mut blk); + planes[0].block(mcu_x * hs + hx, vy, &mut blk); fdct_quant(&blk, &rl, &mut q); - tokenize_block(&q, &mut pred[0], false, &mut tokens, &mut freq); + emit(&q, &mut pred[0], false); } } if !gray { for (plane, pred) in planes.iter().zip(pred.iter_mut()).take(3).skip(1) { - plane.block(mcu_x, mcu_y, &mut blk); + plane.block(mcu_x, 0, &mut blk); fdct_quant(&blk, &rc, &mut q); - tokenize_block(&q, pred, true, &mut tokens, &mut freq); + emit(&q, pred, true); } } } } + }; + let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); + visit_band(band, &mut |q, pred, chroma| tokenize_block(q, pred, chroma, &mut tokens, &mut freq)); + #[cfg(test)] + low_memory_tests::record_tokens(tokens.len()); (tokens, freq) }; #[cfg(feature = "parallel")] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.par_iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.par_iter().map(tokenize_band).collect() }; #[cfg(not(feature = "parallel"))] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.iter().map(tokenize_band).collect() }; // the tables: DC luma, AC luma, DC chroma, AC chroma let tables: [([u8; 16], Vec); 4] = if optimize { let mut total = [[0u64; 256]; 4]; + if low_memory { + for band in 0..num_bands { + visit_band(&band, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, _, _| total[base + ac as usize][symbol & 0xFF] += 1); + }); + } + } for (_, f) in &tokenized { for (t, f) in total.iter_mut().zip(f) { for (t, f) in t.iter_mut().zip(f) { @@ -577,9 +635,9 @@ fn encode_with( let huff = tables.each_ref().map(|(bits, vals)| Huff::new(bits, vals)); // second pass: code the symbols #[cfg(feature = "parallel")] - let coded: Vec> = tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; #[cfg(not(feature = "parallel"))] - let coded: Vec> = tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; // headers let mut out = Vec::with_capacity(coded.iter().map(Vec::len).sum::() + 4096); @@ -617,7 +675,7 @@ fn encode_with( dht(&mut out, 0x11, acb, acv); } let interval = (rows_per_band * mx) as u16; - if coded.len() > 1 { + if num_bands > 1 { segment(&mut out, 0xDD, &interval.to_be_bytes()); } if gray { @@ -625,11 +683,32 @@ fn encode_with( } else { segment(&mut out, 0xDA, &[3, 1, 0x00, 2, 0x11, 3, 0x11, 0, 63, 0]); } - let last = coded.len().saturating_sub(1); - for (i, c) in coded.iter().enumerate() { - out.extend_from_slice(c); - if i < last { - out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + if low_memory { + let last = num_bands.saturating_sub(1); + for i in 0..num_bands { + // Continue directly in the final buffer, resetting entropy bits at the same band + // boundaries as the retained-token path. Only the output grows with image height. + let mut bits = Bits { out, acc: 0, n: 0 }; + visit_band(&i, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, extra, n| { + let (code, len) = huff[base + ac as usize].code[symbol & 0xFF]; + bits.put(code as u32, len as u32); + bits.put(extra & 0xFFFF, n & 0xF); + }); + }); + out = bits.finish(); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } + } + } else { + let last = coded.len().saturating_sub(1); + for (i, c) in coded.iter().enumerate() { + out.extend_from_slice(c); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } } } out.extend_from_slice(&[0xFF, 0xD9]); @@ -877,3 +956,7 @@ mod tests { assert!(psnr(&src, &px) > 35.0); } } + +#[cfg(test)] +#[path = "encode_low_memory_tests.rs"] +mod low_memory_tests; diff --git a/crates/jpeg/src/encode_low_memory_tests.rs b/crates/jpeg/src/encode_low_memory_tests.rs new file mode 100644 index 000000000..de45f8dfe --- /dev/null +++ b/crates/jpeg/src/encode_low_memory_tests.rs @@ -0,0 +1,155 @@ +use super::*; +use std::cell::Cell; + +thread_local! { + static STATS: Cell<(usize, usize)> = const { Cell::new((0, 0)) }; +} + +pub(super) fn record_planes(samples: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak.max(samples), tokens)); + }); +} +pub(super) fn record_tokens(count: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak, tokens + count)); + }); +} + +fn noise(len: usize) -> Vec { + let mut seed = 0x89ab_cdefu32; + (0..len) + .map(|_| { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + seed as u8 + }) + .collect() +} + +fn compare(src: &[u8], w: usize, h: usize, ch: usize, q: u8, sub: ChromaSubsampling, app: &[(u8, Vec)]) { + let expected = encode_baseline(src, w, h, ch, q, sub, app).unwrap(); + STATS.with(|s| s.set((0, 0))); + let actual = encode_baseline_low_memory(src, w, h, ch, q, sub, app).unwrap(); + assert_eq!(actual, expected, "{w}x{h} channels={ch} quality={q} subsampling={sub:?}"); + let (peak, tokens) = STATS.with(Cell::get); + assert!(peak <= 24 * w + 8, "MCU-row scratch exceeded: {peak}"); + assert_eq!(tokens, 0, "low-memory mode retained entropy tokens"); +} + +#[test] +fn all_sampling_and_channels_match_retained_tokens_byte_for_byte() { + for (w, h) in [(1, 1), (7, 9), (17, 31), (33, 65), (17, 1025)] { + for ch in [1, 3, 4] { + let src = noise(w * h * ch); + for sub in [ChromaSubsampling::S444, ChromaSubsampling::S422, ChromaSubsampling::S420] { + for q in [0, 1, 25, 50, 90, 100, 255] { + compare(&src, w, h, ch, q, sub, &[]); + } + } + } + } +} + +#[test] +fn high_entropy_hd_and_wide_frames_keep_only_one_mcu_row() { + for (w, h) in [(1920, 1080), (65_535, 1)] { + let src = noise(w * h * 3); + compare(&src, w, h, 3, 100, ChromaSubsampling::S444, &[]); + } +} + +#[test] +fn metadata_empty_tables_and_extra_source_bytes_keep_exact_output() { + let app = [(0xe0, b"custom density".to_vec()), (0xe2, vec![73; 65_533])]; + for ch in [1, 3, 4] { + let src = vec![127; 19 * 23 * ch + 5]; + compare(&src, 19, 23, ch, 75, ChromaSubsampling::S420, &app); + } +} + +#[test] +fn checked_admission_matches_original_without_panics() { + for (w, h, ch) in [(0, 1, 3), (1, 0, 3), (1, 1, 0), (1, 1, 2), (usize::MAX, 2, 4), (65_536, 1, 1), (1, 65_536, 1), (4, 4, 3)] { + let src = vec![0; if w == 65_536 || h == 65_536 { 65_536 } else { 8 }]; + let old = encode_baseline(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + let new = encode_baseline_low_memory(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + assert!(new.is_err()); + assert_eq!(new, old); + } + for app in [vec![(0xdf, vec![])], vec![(0xf0, vec![])], vec![(0xe1, vec![0; 65_534])]] { + assert_eq!( + encode_baseline_low_memory(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app), + encode_baseline(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app) + ); + } +} + +// Generated with the immutable pre-change encoder at craft-libs +// 937ac93c5cf3cd4b6a81e195b078fe161eb081b9, not the refactored token-retaining path. +// Odd chroma edges and 1025/2049-row inputs exercise multi-row restart bands. +#[test] +fn prechange_encoded_bytes_remain_pinned_across_band_boundaries() { + let cases = [ + (1, 1, 1, 1, 444, 159, 0xe3bd59145381ba57), + (1, 1, 1, 75, 422, 159, 0xcb2b103914bbdbd3), + (1, 1, 1, 100, 420, 160, 0xd9f640613efb6abf), + (1, 1, 3, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 3, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 3, 100, 420, 288, 0x5660667f1abd0a63), + (1, 1, 4, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 4, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 4, 100, 420, 288, 0x5660667f1abd0a63), + (17, 31, 1, 1, 444, 240, 0xf8d277e9499253d4), + (17, 31, 1, 75, 422, 515, 0xa6946d4f144bf243), + (17, 31, 1, 100, 420, 793, 0xbb3db259708d8951), + (17, 31, 3, 1, 444, 363, 0xff2b5b41ffb3f81b), + (17, 31, 3, 75, 422, 877, 0x0374ffb527378dfe), + (17, 31, 3, 100, 420, 1220, 0x2feeedfa90885737), + (17, 31, 4, 1, 444, 366, 0xde7f8d1330e436eb), + (17, 31, 4, 75, 422, 879, 0xb1559fbfc3ee0cf6), + (17, 31, 4, 100, 420, 1214, 0xaf5dcf12d28c8e88), + (33, 65, 1, 1, 444, 388, 0xbee80491e42c8fd2), + (33, 65, 1, 75, 422, 1470, 0x284f4eb78b785ca5), + (33, 65, 1, 100, 420, 2576, 0xa81cc94015f326dc), + (33, 65, 3, 1, 444, 526, 0xf75b4036acc30874), + (33, 65, 3, 75, 422, 2322, 0x6fbc56bd9a1eec70), + (33, 65, 3, 100, 420, 3796, 0xcad25051562ac816), + (33, 65, 4, 1, 444, 527, 0x4bfedc11153de4c1), + (33, 65, 4, 75, 422, 2309, 0x47bf11bf32bac6a4), + (33, 65, 4, 100, 420, 3775, 0x64c2303fde273cd1), + (17, 1025, 1, 1, 444, 2017, 0x242f4a95d8579612), + (17, 1025, 1, 75, 422, 10728, 0xfe49408f379bdffb), + (17, 1025, 1, 100, 420, 19686, 0x1355b995e38d6467), + (17, 1025, 3, 1, 444, 2137, 0x4e319440cb6946c2), + (17, 1025, 3, 75, 422, 17682, 0xf456c63b731dde8f), + (17, 1025, 3, 100, 420, 29015, 0x0631001154b128cf), + (17, 1025, 4, 1, 444, 2155, 0xa2de9c1d77e62aa6), + (17, 1025, 4, 75, 422, 17648, 0x7d85fbdf56061f0c), + (17, 1025, 4, 100, 420, 29010, 0x4848eeb93daf1df2), + (19, 2049, 1, 1, 444, 3531, 0x9b93cf219ff85796), + (19, 2049, 1, 75, 422, 26283, 0xb160523444397608), + (19, 2049, 1, 100, 420, 51883, 0xc5c26836c0a976c6), + (19, 2049, 3, 1, 444, 3303, 0x26eaac2272e1fdb8), + (19, 2049, 3, 75, 422, 42745, 0x38b9843fb54db698), + (19, 2049, 3, 100, 420, 79868, 0xd6a7917af19682f7), + (19, 2049, 4, 1, 444, 3343, 0x6bf577903528692f), + (19, 2049, 4, 75, 422, 42706, 0x0e62366274593a93), + (19, 2049, 4, 100, 420, 79804, 0x867d05cf9d944599), + ]; + for (w, h, ch, q, sampling, len, hash) in cases { + let sub = match sampling { + 444 => ChromaSubsampling::S444, + 422 => ChromaSubsampling::S422, + _ => ChromaSubsampling::S420, + }; + let src = noise(w * h * ch); + for actual in [encode_baseline(&src, w, h, ch, q, sub, &[]).unwrap(), encode_baseline_low_memory(&src, w, h, ch, q, sub, &[]).unwrap()] { + let actual_hash = actual.iter().fold(0xcbf29ce484222325u64, |h, b| (h ^ u64::from(*b)).wrapping_mul(0x100000001b3)); + assert_eq!((actual.len(), actual_hash), (len, hash), "{w}x{h} channels={ch} quality={q} sampling={sampling}"); + } + } +} diff --git a/crates/jpeg/src/lib.rs b/crates/jpeg/src/lib.rs index 23434fdd0..ed2ee1988 100644 --- a/crates/jpeg/src/lib.rs +++ b/crates/jpeg/src/lib.rs @@ -1705,7 +1705,7 @@ mod tests; /// Baseline JPEG encoder (8-bit, Huffman-coded sequential DCT). mod encode; -pub use encode::{ChromaSubsampling, EncodeError, encode_baseline}; +pub use encode::{ChromaSubsampling, EncodeError, encode_baseline, encode_baseline_low_memory}; mod app14; pub use app14::adobe_transform; From d118983bf922ac96c68b885dc55da30435adbc7d Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 16:13:18 -0500 Subject: [PATCH 92/97] Extract Java class reader and JVM opcode decoder (#2048) * Port Java class source: Craft Anything Source: storytold/craft-anything@f64ae3bf3c8863a982af1304e06de20653803968 * Port Java class source: Find class usage in multidimensional object arrays (R0.5) (#437) Source: storytold/craft-anything@ffe15c916574aa0ba6ba4d548c4f1a0f871a5689 * Port Java class source: More format parsers keep to their declared lengths and refuse impossible values (#722) Source: storytold/craft-anything@b9ca099903aeef5d4b33a7e83e8e7062ab94c65a * Port Java class source: Address the parser review findings from #722 (#766) Source: storytold/craft-anything@eab6a0f01bf9fc3a36798d322e4442e169394dfc * Port Java class source: Read JVM method parameters containing parentheses in class names (R3.12) (#1342) Source: storytold/craft-anything@fb4c437fe613f7c29fd8d32033c9574cd48107dc * Port Java class source: Reject Java constants that exceed the constant-pool slots (R3.12) (#1373) Source: storytold/craft-anything@1c4f233f08caf2c54391d611d2f5781229d89ee6 * Port Java class source: Validate JVM switch tables before allocating decoded pairs (R3.12) (#1503) Source: storytold/craft-anything@b40c56ef5cb52d377d6e8a2078235ce6e98bef57 * Port Java class source: Reuse constant-pool names while reading Java attributes (R3.12) (#1549) Source: storytold/craft-anything@76fcdaadb776ce692aa27e1262c9c71f4c8d3c80 * Port Java class source: Trace JVM bootstrap dependencies at their bytecode use sites (R3.12) (#1648) Source: storytold/craft-anything@c5e524dd084fb265d0aad9991188d76c77eaf233 * Port Java class source: Reject impossible JVM array allocation operands (R3.12) (#1675) Source: storytold/craft-anything@f04d7456e00aea406a86a6e468d0b68fbb934edb * Port Java class source: Report truncated Java class attribute tables (R3.12) Source: storytold/craft-anything@420552ff7473f4859985f53ae57d3214209d8415 * Expose neutral Java class API and retain checked reader and synthetic fixtures * Retain Java regression: java_array_operands Source: storytold/craft-anything@f04d7456e00aea406a86a6e468d0b68fbb934edb * Retain Java regression: java_attribute_names Source: storytold/craft-anything@76fcdaadb776ce692aa27e1262c9c71f4c8d3c80 * Retain Java regression: java_constant_pool_slots Source: storytold/craft-anything@1c4f233f08caf2c54391d611d2f5781229d89ee6 * Retain Java regression: java_invoke_operands Source: storytold/craft-anything@eab6a0f01bf9fc3a36798d322e4442e169394dfc * Retain Java regression: java_linkage_references Source: storytold/craft-anything@c5e524dd084fb265d0aad9991188d76c77eaf233 * Retain Java regression: java_truncated_attributes Source: storytold/craft-anything@420552ff7473f4859985f53ae57d3214209d8415 * Retain Java regression: java_wide_opcodes Source: storytold/craft-anything@b9ca099903aeef5d4b33a7e83e8e7062ab94c65a * Register Java class reader and retain source regression coverage --------- Co-authored-by: Brandon Thomas Co-authored-by: Afloat <132809511+Afloat16@users.noreply.github.com> Co-authored-by: BFlat Co-authored-by: Afloat Co-authored-by: RRFZ <247457381+Plastic-time@users.noreply.github.com> --- ATTRIBUTION.md | 4 + Cargo.lock | 8 + Cargo.toml | 1 + crates/java-class/Cargo.toml | 13 + crates/java-class/src/bytes.rs | 51 + crates/java-class/src/descriptor.rs | 19 + crates/java-class/src/java_class.rs | 1082 +++++++++++++++++ crates/java-class/src/java_ops.rs | 711 +++++++++++ crates/java-class/src/lib.rs | 50 + .../src/regressions/java_array_operands.rs | 48 + .../src/regressions/java_attribute_names.rs | 132 ++ .../regressions/java_constant_pool_slots.rs | 53 + .../src/regressions/java_invoke_operands.rs | 76 ++ .../regressions/java_linkage_references.rs | 97 ++ .../regressions/java_truncated_attributes.rs | 46 + .../src/regressions/java_wide_opcodes.rs | 33 + crates/java-class/src/test_support.rs | 316 +++++ 17 files changed, 2740 insertions(+) create mode 100644 crates/java-class/Cargo.toml create mode 100644 crates/java-class/src/bytes.rs create mode 100644 crates/java-class/src/descriptor.rs create mode 100644 crates/java-class/src/java_class.rs create mode 100644 crates/java-class/src/java_ops.rs create mode 100644 crates/java-class/src/lib.rs create mode 100644 crates/java-class/src/regressions/java_array_operands.rs create mode 100644 crates/java-class/src/regressions/java_attribute_names.rs create mode 100644 crates/java-class/src/regressions/java_constant_pool_slots.rs create mode 100644 crates/java-class/src/regressions/java_invoke_operands.rs create mode 100644 crates/java-class/src/regressions/java_linkage_references.rs create mode 100644 crates/java-class/src/regressions/java_truncated_attributes.rs create mode 100644 crates/java-class/src/regressions/java_wide_opcodes.rs create mode 100644 crates/java-class/src/test_support.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 07e84f37b..ae72ae851 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -143,6 +143,10 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. +## Java class inspection + +`crates/java-class` extracts Craft Anything `java_class.rs` and `java_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0), preserving separate primary-author source-history ports by Brandon Thomas, BFlat, Afloat and RRFZ. The checked byte-reader, modified UTF-8 unit decoder, descriptor display helper and synthetic class fixtures come from the same source snapshot. Seven regression files retain their source authors. Neutral error wiring and shared crate integration are subsequent changes. No JAR archive, application I/O or bytecode execution is imported. + ## WebAssembly inspection `crates/wasm` extracts Craft Anything `crates/formats/src/wasm.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2`, with its checked byte-reader subset and original synthetic WASM/testkit fixtures (MIT OR Apache-2.0). Eight core-history ports preserve Brandon Thomas, Afloat and RRFZ as primary authors; component, repeated-custom-section and referenced-string regression imports retain source authors and commit references. Fixtures come from `crates/testkit/src/formats.rs` and deterministic mutation helpers from `crates/testkit/src/lib.rs`; no third-party binaries. Shared error naming and workspace wiring are subsequent changes. Existing inspection limits and report behavior are unchanged; this crate validates/inspects/renders, never executes modules. diff --git a/Cargo.lock b/Cargo.lock index c1eb3006b..cc0965d17 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2292,6 +2292,14 @@ dependencies = [ "widestring", ] +[[package]] +name = "craft-java-class" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + [[package]] name = "craft-jmap" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 3468f29f6..fd9ccf7a6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-java-class = { path = "crates/java-class" } craft-sourcemap = { path = "crates/sourcemap" } craft-pcap = { path = "crates/pcap" } craft-har = { path = "crates/har" } diff --git a/crates/java-class/Cargo.toml b/crates/java-class/Cargo.toml new file mode 100644 index 000000000..6dfbd16e5 --- /dev/null +++ b/crates/java-class/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name="craft-java-class" +description="Java class-file inspection and JVM bytecode decoding with retained bounds and partial reports" +version.workspace=true +edition.workspace=true +license.workspace=true +rust-version.workspace=true +repository.workspace=true +[lints] +workspace=true +[dependencies] +serde={workspace=true} +thiserror={workspace=true} diff --git a/crates/java-class/src/bytes.rs b/crates/java-class/src/bytes.rs new file mode 100644 index 000000000..bc26aea19 --- /dev/null +++ b/crates/java-class/src/bytes.rs @@ -0,0 +1,51 @@ +//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range. + +#[derive(Debug, Clone, Copy)] +pub struct Reader<'a> { + data: &'a [u8], +} + +impl<'a> Reader<'a> { + pub fn new(data: &'a [u8]) -> Self { + Reader { data } + } + + pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> { + let end = off.checked_add(len)?; + self.data.get(off..end) + } + + pub fn u8(&self, off: usize) -> Option { + self.data.get(off).copied() + } + + fn arr(&self, off: usize) -> Option<[u8; N]> { + self.slice(off, N)?.try_into().ok() + } + + pub fn u16_be(&self, off: usize) -> Option { + self.arr(off).map(u16::from_be_bytes) + } + + pub fn u32_be(&self, off: usize) -> Option { + self.arr(off).map(u32::from_be_bytes) + } + + pub fn u64_be(&self, off: usize) -> Option { + self.arr(off).map(u64::from_be_bytes) + } +} + +/// Decode one modified UTF-8 code unit. Invalid bytes consume only themselves, +/// so a damaged sequence cannot hide valid text or borrow missing bytes. +pub(crate) fn mutf8_unit(bytes: &[u8]) -> (u16, usize) { + match bytes { + [a @ 0x00..=0x7f, ..] => (u16::from(*a), 1), + [0xc0, 0x80, ..] => (0, 2), + [a @ 0xc2..=0xdf, b @ 0x80..=0xbf, ..] => ((u16::from(*a & 0x1f) << 6) | u16::from(*b & 0x3f), 2), + [a @ 0xe0..=0xef, b @ 0x80..=0xbf, c @ 0x80..=0xbf, ..] if *a != 0xe0 || *b >= 0xa0 => { + ((u16::from(*a & 0x0f) << 12) | (u16::from(*b & 0x3f) << 6) | u16::from(*c & 0x3f), 3) + } + _ => (0xfffd, 1), + } +} diff --git a/crates/java-class/src/descriptor.rs b/crates/java-class/src/descriptor.rs new file mode 100644 index 000000000..3f4b32bd7 --- /dev/null +++ b/crates/java-class/src/descriptor.rs @@ -0,0 +1,19 @@ +// Descriptor display helper retained from the source DEX reader. +pub fn java_name(desc: &str) -> String { + let dims = desc.chars().take_while(|&c| c == '[').count(); + let base = desc.get(dims..).unwrap_or(""); + let name = match base { + "V" => "void".to_string(), + "Z" => "boolean".to_string(), + "B" => "byte".to_string(), + "S" => "short".to_string(), + "C" => "char".to_string(), + "I" => "int".to_string(), + "J" => "long".to_string(), + "F" => "float".to_string(), + "D" => "double".to_string(), + b if b.starts_with('L') && b.ends_with(';') => b.get(1..b.len() - 1).unwrap_or("").replace('/', "."), + b => b.to_string(), + }; + format!("{name}{}", "[]".repeat(dims.min(255))) +} diff --git a/crates/java-class/src/java_class.rs b/crates/java-class/src/java_class.rs new file mode 100644 index 000000000..4b751ec3e --- /dev/null +++ b/crates/java-class/src/java_class.rs @@ -0,0 +1,1082 @@ +//! Java `.class` files (JVMS): the magic and version, the constant pool (every tag including +//! `MethodHandle`/`MethodType`/`Dynamic`/`InvokeDynamic`/`Module`/`Package`), access flags, the +//! this/super class and interfaces, fields and methods with their attributes (`Code` with its +//! exception table and line numbers, `ConstantValue`, `Exceptions`, `Signature`), and the +//! class-level `SourceFile`, `InnerClasses` and annotation attributes (type names, best-effort). +//! +//! Counts and lengths are checked against the file size, strings are decoded from modified UTF-8, +//! and every read is bounds-checked, so hostile input yields warnings, not panics. + +use crate::bytes::Reader; +use crate::java_ops::{self, Insn}; +use crate::{FormatError, descriptor as dex}; +use serde::Serialize; + +/// Most constant-pool entries, fields, methods, attributes or interfaces we read from one file. +const MAX_ITEMS: usize = 1 << 20; +/// Most attributes per element. +const MAX_ATTRS: usize = 64 * 1024; +/// Deepest annotation/element-value nesting we walk. +const MAX_ANNO_DEPTH: usize = 32; + +/// One constant-pool entry. Index 0 and the slot after a `Long`/`Double` are `Unusable`. +#[derive(Debug, Clone, PartialEq)] +pub enum Const { + Unusable, + Utf8(String), + Integer(i32), + Float(f32), + Long(i64), + Double(f64), + /// `name_index` → a Utf8 internal name. + Class(u16), + /// `string_index` → a Utf8. + String(u16), + /// `class_index`, `name_and_type_index`. + FieldRef(u16, u16), + MethodRef(u16, u16), + InterfaceMethodRef(u16, u16), + /// `name_index`, `descriptor_index`. + NameAndType(u16, u16), + /// `reference_kind`, `reference_index`. + MethodHandle(u8, u16), + /// `descriptor_index`. + MethodType(u16), + /// `bootstrap_method_attr_index`, `name_and_type_index`. + Dynamic(u16, u16), + InvokeDynamic(u16, u16), + Module(u16), + Package(u16), +} + +/// The class-file version. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +pub struct Version { + pub major: u16, + pub minor: u16, +} + +impl Version { + /// A friendly Java platform label (`Java 8`, `Java 17`, `Java 1.3`). + pub fn java_label(self) -> String { + match self.major { + 45..=48 => format!("Java 1.{}", self.major - 44), + m if m >= 49 => format!("Java {}", m - 44), + m => format!("pre-standard (major {m})"), + } + } +} + +/// An exception-table row of a `Code` attribute. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct ExceptionEntry { + pub start_pc: u16, + pub end_pc: u16, + pub handler_pc: u16, + /// Dotted caught type; `None` is catch-all (a `finally` or `catch (Throwable)` with index 0). + pub catch_type: Option, +} + +/// A parsed `Code` attribute. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Code { + pub max_stack: u16, + pub max_locals: u16, + pub bytecode: Vec, + pub exceptions: Vec, + /// `(start_pc, line)` from the `LineNumberTable`. + pub line_numbers: Vec<(u16, u16)>, +} + +/// A field or method. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct Member { + pub access: u16, + pub name: String, + pub descriptor: String, + /// The generic `Signature` attribute, if present. + pub signature: Option, + /// A field's `ConstantValue`, rendered to text. + pub constant_value: Option, + /// A method's declared `throws` types (dotted). + pub exceptions: Vec, + /// A method's code. + pub code: Option, + pub deprecated: bool, + /// The `Synthetic` attribute (separate from the access flag). + pub synthetic_attr: bool, +} + +/// An `InnerClasses` row. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct InnerClass { + pub inner: Option, + pub outer: Option, + /// Simple name; `None` for an anonymous class. + pub name: Option, + pub access: u16, +} + +/// A parsed class file. +#[derive(Debug, Clone)] +pub struct ClassFile { + pub version: Version, + pub access: u16, + /// Internal name of this class (`com/example/Main`). + pub this_class: String, + /// Internal name of the superclass; `None` only for `java/lang/Object` and modules. + pub super_class: Option, + /// Internal names of the implemented interfaces. + pub interfaces: Vec, + pub fields: Vec, + pub methods: Vec, + pub source_file: Option, + pub signature: Option, + pub inner_classes: Vec, + /// Class-level annotation types (dotted), with `(runtime)`/`(class)` visibility. + pub annotations: Vec, + /// Bootstrap method handle and static arguments, indexed by dynamic pool constants. + pub bootstrap_methods: Vec<(u16, Vec)>, + pub pool: Vec, + pub warnings: Vec, +} + +// --------------------------------------------------------------------------------------------- +// Names, descriptors and access flags + +/// `java/lang/String` → `java.lang.String`; `[Ljava/lang/String;` → `java.lang.String[]`. +pub fn internal_to_dotted(name: &str) -> String { + if name.starts_with('[') { dex::java_name(name) } else { name.replace('/', ".") } +} + +/// A field descriptor (`Ljava/lang/String;`, `[I`, `I`) as a Java type. +pub fn field_type(desc: &str) -> String { + dex::java_name(desc) +} + +/// Read parameter descriptors up to the closing parenthesis and return the remaining return descriptor. +fn split_types(s: &str) -> Option<(Vec, &str)> { + let b = s.as_bytes(); + let mut out = Vec::new(); + let mut i = 0usize; + while i < b.len() && out.len() < MAX_ITEMS { + if b.get(i) == Some(&b')') { + return Some((out, s.get(i + 1..)?)); + } + let start = i; + while b.get(i) == Some(&b'[') { + i += 1; + } + match b.get(i) { + Some(b'L') => match s.get(i..).and_then(|r| r.find(';')) { + Some(semi) => i = i + semi + 1, + None => i = b.len(), + }, + Some(_) => i += 1, + None => break, + } + match s.get(start..i) { + Some(t) if !t.is_empty() => out.push(t.to_string()), + _ => break, + } + } + None +} + +/// Parameter types and return type of a method descriptor (`(Ljava/lang/String;I)V`). +pub fn method_params(desc: &str) -> (Vec, String) { + let Some(rest) = desc.strip_prefix('(') else { return (Vec::new(), "?".into()) }; + let Some((params, ret)) = split_types(rest) else { return (Vec::new(), "?".into()) }; + (params.iter().map(|t| field_type(t)).collect(), field_type(ret)) +} + +/// What a set of access flags belongs to. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum AccessKind { + Class, + Field, + Method, + InnerClass, +} + +/// Human names of the set access flags. +pub fn access_flags(flags: u16, kind: AccessKind) -> Vec<&'static str> { + let mut v = Vec::new(); + let common: &[(u16, &str)] = &[(0x0001, "public"), (0x0002, "private"), (0x0004, "protected"), (0x0008, "static"), (0x0010, "final")]; + for (bit, name) in common { + if flags & bit != 0 { + v.push(*name); + } + } + match kind { + AccessKind::Method => { + for (bit, name) in [ + (0x0020u16, "synchronized"), + (0x0040, "bridge"), + (0x0080, "varargs"), + (0x0100, "native"), + (0x0400, "abstract"), + (0x0800, "strictfp"), + (0x1000, "synthetic"), + ] { + if flags & bit != 0 { + v.push(name); + } + } + } + AccessKind::Field => { + for (bit, name) in [(0x0040u16, "volatile"), (0x0080, "transient"), (0x1000, "synthetic"), (0x4000, "enum")] { + if flags & bit != 0 { + v.push(name); + } + } + } + AccessKind::Class | AccessKind::InnerClass => { + for (bit, name) in [ + (0x0020u16, "super"), + (0x0200, "interface"), + (0x0400, "abstract"), + (0x1000, "synthetic"), + (0x2000, "annotation"), + (0x4000, "enum"), + (0x8000, "module"), + ] { + if flags & bit != 0 { + // "super" is an internal marker on classes; hide it unless it is the only flag of note. + if name == "super" && kind == AccessKind::Class { + continue; + } + v.push(name); + } + } + } + } + v +} + +/// A resolved reference to a field or method. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Ref { + /// Internal owner name (`java/lang/System`). + pub owner: String, + pub name: String, + pub descriptor: String, +} + +impl Ref { + /// `java.lang.System.out:java.io.PrintStream` style display. A field descriptor is shown as a + /// Java type; a method descriptor is left in its raw `(args)ret` form. + pub fn display(&self) -> String { + let ty = if self.descriptor.starts_with('(') { self.descriptor.clone() } else { field_type(&self.descriptor) }; + format!("{}.{}:{}", internal_to_dotted(&self.owner), self.name, ty) + } +} + +// --------------------------------------------------------------------------------------------- +// Modified UTF-8 + +/// Decode a modified-UTF-8 byte run (class-file `Utf8` content) to a String. +fn decode_mutf8(bytes: &[u8]) -> String { + let mut units: Vec = Vec::new(); + let mut i = 0usize; + while i < bytes.len() { + let (unit, consumed) = crate::bytes::mutf8_unit(bytes.get(i..).unwrap_or_default()); + units.push(unit); + i += consumed; + } + String::from_utf16_lossy(&units) +} + +// --------------------------------------------------------------------------------------------- +// Cursor + +struct Cursor<'a> { + r: Reader<'a>, + pos: usize, +} + +impl<'a> Cursor<'a> { + fn new(data: &'a [u8]) -> Self { + Cursor { r: Reader::new(data), pos: 0 } + } + fn u8(&mut self) -> Option { + let v = self.r.u8(self.pos)?; + self.pos += 1; + Some(v) + } + fn u16(&mut self) -> Option { + let v = self.r.u16_be(self.pos)?; + self.pos += 2; + Some(v) + } + fn u32(&mut self) -> Option { + let v = self.r.u32_be(self.pos)?; + self.pos += 4; + Some(v) + } + fn u64(&mut self) -> Option { + let v = self.r.u64_be(self.pos)?; + self.pos += 8; + Some(v) + } + fn take(&mut self, n: usize) -> Option<&'a [u8]> { + let s = self.r.slice(self.pos, n)?; + self.pos += n; + Some(s) + } +} + +// --------------------------------------------------------------------------------------------- +// Parsing + +/// True when the bytes begin a Java class file (0xCAFEBABE and a plausible major version). +/// A big-endian Mach-O fat binary shares the magic but has a small arch count where the version +/// is, so it fails the major-version check. +pub fn is_class(data: &[u8]) -> bool { + if !data.starts_with(&[0xca, 0xfe, 0xba, 0xbe]) { + return false; + } + let r = Reader::new(data); + matches!(r.u16_be(6), Some(major) if (45..=255).contains(&major)) +} + +fn utf8_of(pool: &[Const], idx: u16) -> &str { + match pool.get(idx as usize) { + Some(Const::Utf8(s)) => s.as_str(), + _ => "", + } +} + +/// Parse a class file. +pub fn parse(data: &[u8]) -> Result { + if !data.starts_with(&[0xca, 0xfe, 0xba, 0xbe]) { + return Err(FormatError::Malformed("not a Java class file (no 0xCAFEBABE magic)".into())); + } + let mut c = Cursor::new(data); + let mut warnings = Vec::new(); + let _magic = c.u32(); + let minor = c.u16().ok_or_else(|| FormatError::Truncated("version".into()))?; + let major = c.u16().ok_or_else(|| FormatError::Truncated("version".into()))?; + if major < 45 { + return Err(FormatError::Unsupported(format!("class major version {major} is below 45 (not a standard class file)"))); + } + let version = Version { major, minor }; + let cp_count = c.u16().ok_or_else(|| FormatError::Truncated("constant pool count".into()))?; + if cp_count == 0 { + return Err(FormatError::Malformed("constant pool count is zero".into())); + } + let pool = parse_pool(&mut c, cp_count, &mut warnings)?; + let access = c.u16().ok_or_else(|| FormatError::Truncated("access flags".into()))?; + let this_idx = c.u16().ok_or_else(|| FormatError::Truncated("this_class".into()))?; + let super_idx = c.u16().ok_or_else(|| FormatError::Truncated("super_class".into()))?; + let this_class = class_name_at(&pool, this_idx); + let super_class = if super_idx == 0 { None } else { Some(class_name_at(&pool, super_idx)) }; + // Interfaces + let n_iface = c.u16().ok_or_else(|| FormatError::Truncated("interfaces count".into()))? as usize; + let mut interfaces = Vec::new(); + for _ in 0..n_iface.min(MAX_ITEMS) { + let Some(i) = c.u16() else { + warnings.push("interface list ended early".into()); + break; + }; + interfaces.push(class_name_at(&pool, i)); + } + // Fields + let fields = parse_members(&mut c, &pool, &mut warnings, "field")?; + // Methods + let methods = parse_members(&mut c, &pool, &mut warnings, "method")?; + // Class attributes + let (attrs, complete) = read_attrs(&mut c, &pool); + if !complete { + warnings.push("class attribute table ended early".into()); + } + let mut source_file = None; + let mut signature = None; + let mut inner_classes = Vec::new(); + let mut annotations = Vec::new(); + let mut bootstrap_methods = Vec::new(); + for a in &attrs { + match a.name { + "SourceFile" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + source_file = Some(utf8_of(&pool, i).to_string()); + } + } + "Signature" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + signature = Some(utf8_of(&pool, i).to_string()); + } + } + "BootstrapMethods" => match bootstrap_table(a.info) { + Some(table) => bootstrap_methods = table, + None => warnings.push("invalid BootstrapMethods table".into()), + }, + "InnerClasses" => inner_classes = parse_inner_classes(a.info, &pool), + "RuntimeVisibleAnnotations" => annotations.extend(parse_annotation_types(a.info, &pool, "runtime")), + "RuntimeInvisibleAnnotations" => annotations.extend(parse_annotation_types(a.info, &pool, "class")), + _ => {} + } + } + Ok(ClassFile { + version, + access, + this_class, + super_class, + interfaces, + fields, + methods, + source_file, + signature, + inner_classes, + annotations, + bootstrap_methods, + pool, + warnings, + }) +} + +fn parse_pool(c: &mut Cursor<'_>, cp_count: u16, warnings: &mut Vec) -> Result, FormatError> { + let mut pool = vec![Const::Unusable]; // index 0 + let mut i = 1u16; + while i < cp_count { + let tag = c.u8().ok_or_else(|| FormatError::Truncated("constant pool entry".into()))?; + let entry = match tag { + 1 => { + let len = c.u16().ok_or_else(|| FormatError::Truncated("Utf8 length".into()))? as usize; + let bytes = c.take(len).ok_or_else(|| FormatError::Truncated("Utf8 bytes".into()))?; + Const::Utf8(decode_mutf8(bytes)) + } + 3 => Const::Integer(c.u32().ok_or_else(|| trunc("Integer"))? as i32), + 4 => Const::Float(f32::from_bits(c.u32().ok_or_else(|| trunc("Float"))?)), + 5 => Const::Long(c.u64().ok_or_else(|| trunc("Long"))? as i64), + 6 => Const::Double(f64::from_bits(c.u64().ok_or_else(|| trunc("Double"))?)), + 7 => Const::Class(c.u16().ok_or_else(|| trunc("Class"))?), + 8 => Const::String(c.u16().ok_or_else(|| trunc("String"))?), + 9 => Const::FieldRef(c.u16().ok_or_else(|| trunc("Fieldref"))?, c.u16().ok_or_else(|| trunc("Fieldref"))?), + 10 => Const::MethodRef(c.u16().ok_or_else(|| trunc("Methodref"))?, c.u16().ok_or_else(|| trunc("Methodref"))?), + 11 => Const::InterfaceMethodRef(c.u16().ok_or_else(|| trunc("InterfaceMethodref"))?, c.u16().ok_or_else(|| trunc("InterfaceMethodref"))?), + 12 => Const::NameAndType(c.u16().ok_or_else(|| trunc("NameAndType"))?, c.u16().ok_or_else(|| trunc("NameAndType"))?), + 15 => Const::MethodHandle(c.u8().ok_or_else(|| trunc("MethodHandle"))?, c.u16().ok_or_else(|| trunc("MethodHandle"))?), + 16 => Const::MethodType(c.u16().ok_or_else(|| trunc("MethodType"))?), + 17 => Const::Dynamic(c.u16().ok_or_else(|| trunc("Dynamic"))?, c.u16().ok_or_else(|| trunc("Dynamic"))?), + 18 => Const::InvokeDynamic(c.u16().ok_or_else(|| trunc("InvokeDynamic"))?, c.u16().ok_or_else(|| trunc("InvokeDynamic"))?), + 19 => Const::Module(c.u16().ok_or_else(|| trunc("Module"))?), + 20 => Const::Package(c.u16().ok_or_else(|| trunc("Package"))?), + other => { + return Err(FormatError::Malformed(format!("unknown constant pool tag {other} at index {i}"))); + } + }; + let wide = matches!(entry, Const::Long(_) | Const::Double(_)); + let next = i + .checked_add(if wide { 2 } else { 1 }) + .filter(|next| *next <= cp_count) + .ok_or_else(|| FormatError::Malformed(format!("constant pool entry {i} has no reserved second slot")))?; + pool.push(entry); + if wide { + pool.push(Const::Unusable); + } + i = next; + } + if pool.len() > MAX_ITEMS { + warnings.push("constant pool is unusually large".into()); + } + Ok(pool) +} + +fn trunc(what: &str) -> FormatError { + FormatError::Truncated(format!("constant pool {what}")) +} + +struct RawAttr<'a, 'p> { + // Many attributes can reference one long constant-pool name. The pool + // already owns it for the entire parse; a per-attribute copy amplifies it. + name: &'p str, + info: &'a [u8], +} + +/// Return the complete attributes in the readable prefix and whether the whole table was read. +fn read_attrs<'a, 'p>(c: &mut Cursor<'a>, pool: &'p [Const]) -> (Vec>, bool) { + let mut out = Vec::new(); + let Some(n) = c.u16().map(usize::from) else { return (out, false) }; + for _ in 0..n.min(MAX_ATTRS) { + let (Some(ni), Some(len)) = (c.u16(), c.u32()) else { return (out, false) }; + let Some(info) = c.take(len as usize) else { return (out, false) }; + out.push(RawAttr { name: utf8_of(pool, ni), info }); + } + (out, n <= MAX_ATTRS) +} + +fn bootstrap_table(data: &[u8]) -> Option)>> { + let mut cursor = Cursor::new(data); + let mut table = Vec::new(); + for _ in 0..cursor.u16()? { + let handle = cursor.u16()?; + let count = usize::from(cursor.u16()?); + let args = cursor.take(count * 2)?.as_chunks::<2>().0.iter().map(|b| u16::from_be_bytes(*b)).collect(); + table.push((handle, args)); + } + (cursor.pos == data.len()).then_some(table) +} + +fn parse_members(c: &mut Cursor<'_>, pool: &[Const], warnings: &mut Vec, what: &str) -> Result, FormatError> { + let n = c.u16().ok_or_else(|| FormatError::Truncated(format!("{what} count")))? as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let (Some(access), Some(name_idx), Some(desc_idx)) = (c.u16(), c.u16(), c.u16()) else { + warnings.push(format!("{what} table ended early")); + break; + }; + let mut m = + Member { access, name: utf8_of(pool, name_idx).to_string(), descriptor: utf8_of(pool, desc_idx).to_string(), ..Default::default() }; + let (attrs, _) = read_attrs(c, pool); + for a in attrs { + match a.name { + "Code" => m.code = parse_code(a.info, pool), + "ConstantValue" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + m.constant_value = Some(const_display(pool, i)); + } + } + "Exceptions" => m.exceptions = parse_exceptions_attr(a.info, pool), + "Signature" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + m.signature = Some(utf8_of(pool, i).to_string()); + } + } + "Deprecated" => m.deprecated = true, + "Synthetic" => m.synthetic_attr = true, + _ => {} + } + } + out.push(m); + } + Ok(out) +} + +fn parse_code(info: &[u8], pool: &[Const]) -> Option { + let mut c = Cursor::new(info); + let max_stack = c.u16()?; + let max_locals = c.u16()?; + let code_len = c.u32()? as usize; + let bytecode = c.take(code_len)?.to_vec(); + let n_exc = c.u16()? as usize; + let mut exceptions = Vec::new(); + for _ in 0..n_exc.min(MAX_ITEMS) { + let (Some(start_pc), Some(end_pc), Some(handler_pc), Some(catch)) = (c.u16(), c.u16(), c.u16(), c.u16()) else { break }; + exceptions.push(ExceptionEntry { start_pc, end_pc, handler_pc, catch_type: (catch != 0).then(|| class_name_at(pool, catch)) }); + } + let mut line_numbers = Vec::new(); + let (attrs, _) = read_attrs(&mut c, pool); + for a in attrs { + if a.name == "LineNumberTable" { + let mut lc = Cursor::new(a.info); + let n = lc.u16().unwrap_or(0) as usize; + for _ in 0..n.min(MAX_ITEMS) { + let (Some(pc), Some(line)) = (lc.u16(), lc.u16()) else { break }; + line_numbers.push((pc, line)); + } + } + } + Some(Code { max_stack, max_locals, bytecode, exceptions, line_numbers }) +} + +fn parse_exceptions_attr(info: &[u8], pool: &[Const]) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let Some(i) = c.u16() else { break }; + out.push(class_name_at(pool, i)); + } + out +} + +fn parse_inner_classes(info: &[u8], pool: &[Const]) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let (Some(inner), Some(outer), Some(name), Some(access)) = (c.u16(), c.u16(), c.u16(), c.u16()) else { break }; + out.push(InnerClass { + inner: (inner != 0).then(|| class_name_at(pool, inner)), + outer: (outer != 0).then(|| class_name_at(pool, outer)), + name: (name != 0).then(|| utf8_of(pool, name).to_string()), + access, + }); + } + out +} + +/// Extract annotation type names (dotted) from a `Runtime*Annotations` attribute, best-effort. +fn parse_annotation_types(info: &[u8], pool: &[Const], visibility: &str) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + match read_annotation(&mut c, pool, 0) { + Some(t) => out.push(format!("{t} ({visibility})")), + None => break, + } + } + out +} + +/// Read one `annotation` structure, returning its (dotted) type name; advances past its values. +fn read_annotation(c: &mut Cursor<'_>, pool: &[Const], depth: usize) -> Option { + if depth > MAX_ANNO_DEPTH { + return None; + } + let type_idx = c.u16()?; + let n_pairs = c.u16()? as usize; + let type_name = field_type(utf8_of(pool, type_idx)); + for _ in 0..n_pairs.min(MAX_ITEMS) { + let _name_idx = c.u16()?; + skip_element_value(c, pool, depth + 1)?; + } + Some(type_name) +} + +fn skip_element_value(c: &mut Cursor<'_>, pool: &[Const], depth: usize) -> Option<()> { + if depth > MAX_ANNO_DEPTH { + return None; + } + let tag = c.u8()?; + match tag { + b'B' | b'C' | b'D' | b'F' | b'I' | b'J' | b'S' | b'Z' | b's' | b'c' => { + c.u16()?; + } + b'e' => { + c.u16()?; + c.u16()?; + } + b'@' => { + read_annotation(c, pool, depth + 1)?; + } + b'[' => { + let n = c.u16()? as usize; + for _ in 0..n.min(MAX_ITEMS) { + skip_element_value(c, pool, depth + 1)?; + } + } + _ => return None, + } + Some(()) +} + +/// Internal class name at a `Class` constant index (`java/lang/String` or `[I`). +fn class_name_at(pool: &[Const], idx: u16) -> String { + match pool.get(idx as usize) { + Some(Const::Class(name_idx)) => utf8_of(pool, *name_idx).to_string(), + _ => format!(""), + } +} + +/// Render a loadable constant (for `ldc`/`ConstantValue`) to text. +fn const_display(pool: &[Const], idx: u16) -> String { + match pool.get(idx as usize) { + Some(Const::Integer(v)) => v.to_string(), + Some(Const::Float(v)) => format!("{v}f"), + Some(Const::Long(v)) => format!("{v}L"), + Some(Const::Double(v)) => v.to_string(), + Some(Const::String(s)) => format!("{:?}", utf8_of(pool, *s)), + Some(Const::Class(n)) => format!("{}.class", internal_to_dotted(utf8_of(pool, *n))), + Some(Const::MethodHandle(k, _)) => format!("MethodHandle(kind {k})"), + Some(Const::MethodType(d)) => format!("MethodType({})", utf8_of(pool, *d)), + _ => format!("#{idx}"), + } +} + +// --------------------------------------------------------------------------------------------- +// Resolution and formatting on a parsed class + +impl ClassFile { + /// The Utf8 at `idx`, or an empty string. + pub fn utf8(&self, idx: u16) -> &str { + utf8_of(&self.pool, idx) + } + + /// The dotted name of this class. + pub fn name_dotted(&self) -> String { + internal_to_dotted(&self.this_class) + } + + /// Resolve a `Fieldref`/`Methodref`/`InterfaceMethodref` index to owner, name and descriptor. + pub fn resolve_ref(&self, idx: u16) -> Option { + let (class_idx, nat_idx) = match self.pool.get(idx as usize)? { + Const::FieldRef(c, n) | Const::MethodRef(c, n) | Const::InterfaceMethodRef(c, n) => (*c, *n), + _ => return None, + }; + let owner = class_name_at(&self.pool, class_idx); + let (name, descriptor) = self.name_and_type(nat_idx); + Some(Ref { owner, name, descriptor }) + } + + /// Resolve a `NameAndType` index to (name, descriptor). + pub fn name_and_type(&self, idx: u16) -> (String, String) { + match self.pool.get(idx as usize) { + Some(Const::NameAndType(n, d)) => (self.utf8(*n).to_string(), self.utf8(*d).to_string()), + _ => (format!(""), String::new()), + } + } + + /// The (name, descriptor) of an `InvokeDynamic` (or `Dynamic`) constant's `NameAndType`. + pub fn name_and_type_of_indy(&self, idx: u16) -> Option<(String, String)> { + match self.pool.get(idx as usize)? { + Const::InvokeDynamic(_, nat) | Const::Dynamic(_, nat) => Some(self.name_and_type(*nat)), + _ => None, + } + } + + /// Dotted class name at a `Class` constant index. + pub fn class_dotted(&self, idx: u16) -> String { + internal_to_dotted(&class_name_at(&self.pool, idx)) + } + + /// A Java-style method signature (`public static void log(java.lang.String)`). + pub fn method_signature(&self, m: &Member) -> String { + let (params, ret) = method_params(&m.descriptor); + let flags = access_flags(m.access, AccessKind::Method).join(" "); + let params = params.join(", "); + if m.name == "" || m.name == "" { + format!("{}{}{}({params})", flags, if flags.is_empty() { "" } else { " " }, m.name).trim().to_string() + } else { + format!("{}{}{} {}({params})", flags, if flags.is_empty() { "" } else { " " }, ret, m.name).trim().to_string() + } + } + + /// Render one decoded instruction with its constant-pool reference resolved. + pub fn format_insn(&self, i: &Insn) -> String { + let mut operand = String::new(); + if let Some(cp) = i.cp_index { + operand = match i.opcode { + 0x12..=0x14 => const_display(&self.pool, cp), + 0xb2..=0xb5 => self.resolve_ref(cp).map(|r| r.display()).unwrap_or_else(|| format!("#{cp}")), + 0xb6..=0xb9 => self + .resolve_ref(cp) + .map(|r| format!("{}.{}{}", internal_to_dotted(&r.owner), r.name, r.descriptor)) + .unwrap_or_else(|| format!("#{cp}")), + 0xba => { + // invokedynamic: show the bootstrap name:descriptor + match self.pool.get(cp as usize) { + Some(Const::InvokeDynamic(_, nat)) => { + let (n, d) = self.name_and_type(*nat); + format!("{n}{d}") + } + _ => format!("#{cp}"), + } + } + 0xbb | 0xbd | 0xc0 | 0xc1 | 0xc5 => self.class_dotted(cp), + _ => format!("#{cp}"), + }; + } else if i.opcode == 0xbc { + // newarray + operand = java_ops::array_type(i.int.unwrap_or(0)).to_string(); + } else if i.opcode == 0x84 { + // iinc local, const + operand = format!("{}, {}", i.local.unwrap_or(0), i.int.unwrap_or(0)); + } else if let Some(l) = i.local { + operand = l.to_string(); + } else if let Some(v) = i.int { + operand = v.to_string(); + } else if let Some(b) = i.branch { + operand = format!("{b}"); + } + if i.opcode == 0xc5 { + // multianewarray class, dims + operand = format!("{}, {}", operand, i.int.unwrap_or(0)); + } + let mut s = if operand.is_empty() { i.name.to_string() } else { format!("{} {}", i.name, operand) }; + if let Some(sw) = &i.switch { + let cases: Vec = sw.pairs.iter().take(32).map(|(k, t)| format!("{k} -> {t}")).collect(); + s.push_str(&format!(" # default -> {}; {}", sw.default, cases.join(", "))); + } + s + } +} + +// --------------------------------------------------------------------------------------------- +// References + +/// One place a method's bytecode refers to a class, method or field. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Reference { + /// The calling method, `owner.name:descriptor`. + pub caller: String, + /// Byte offset in the caller's code. + pub pc: u32, + pub instruction: &'static str, + /// Direct member/type use or a method handle, method type or bootstrap linkage. + pub kind: &'static str, + pub target: String, +} + +fn class_component(name: &str) -> Option<&str> { + if name.starts_with('[') { name.trim_start_matches('[').strip_prefix('L')?.strip_suffix(';') } else { Some(name) } +} + +fn descriptor_mentions(mut descriptor: &str, owner: &str) -> bool { + while let Some((_, rest)) = descriptor.split_once('L') { + let Some((class, tail)) = rest.split_once(';') else { return false }; + if class == owner { + return true; + } + descriptor = tail; + } + false +} + +/// Resolve a loadable constant to its named dependency, retaining the linkage role. +fn constant_dependency(cf: &ClassFile, idx: u16, owner: &str, method: Option<&str>, bootstrap: bool) -> Option<(&'static str, String)> { + match cf.pool.get(usize::from(idx))? { + Const::Class(utf) if method.is_none() => { + let name = cf.utf8(*utf); + (class_component(name) == Some(owner)).then(|| ("type", internal_to_dotted(name))) + } + Const::MethodType(utf) if method.is_none() => { + let desc = cf.utf8(*utf); + descriptor_mentions(desc, owner).then(|| ("method-type", desc.to_owned())) + } + Const::MethodHandle(kind, target) => { + let member = cf.pool.get(usize::from(*target))?; + let valid = matches!( + (kind, member), + (1..=4, Const::FieldRef(..)) + | (5 | 8, Const::MethodRef(..)) + | (6 | 7, Const::MethodRef(..) | Const::InterfaceMethodRef(..)) + | (9, Const::InterfaceMethodRef(..)) + ); + let target = cf.resolve_ref(*target)?; + (valid && (!bootstrap || matches!(*kind, 6 | 8)) && target.owner == owner && method.is_none_or(|m| *kind >= 5 && target.name == m)) + .then(|| (if bootstrap { "bootstrap-method" } else { "method-handle" }, target.display())) + } + _ => None, + } +} + +/// Every instruction in `cf` that refers to the internal class `owner` (optionally only calls to +/// its methods named `method`). The bool is true when decoding or the reference limit stops a scan early. +pub fn references(cf: &ClassFile, owner: &str, method: Option<&str>, max: usize) -> (Vec, bool) { + let mut out = Vec::new(); + let mut incomplete = false; + // A single bootstrap record may be referenced by every instruction in a class. + let mut linkage_budget = 200_000usize; + for m in &cf.methods { + let Some(code) = &m.code else { continue }; + let caller = Ref { owner: cf.this_class.clone(), name: m.name.clone(), descriptor: m.descriptor.clone() }.display(); + let (insns, complete) = java_ops::decode(&code.bytecode, 200_000); + incomplete |= !complete; + for i in &insns { + let Some(cp) = i.cp_index else { continue }; + if matches!(i.opcode, 0x12..=0x14 | 0xba) { + let link = match (cf.pool.get(usize::from(cp)), i.opcode) { + (Some(Const::Dynamic(n, _)), 0x12..=0x14) | (Some(Const::InvokeDynamic(n, _)), 0xba) => Some(*n), + (Some(Const::Class(_) | Const::MethodType(_) | Const::MethodHandle(..)), 0x12 | 0x13) => None, + _ => continue, + }; + let record = link.and_then(|idx| cf.bootstrap_methods.get(usize::from(idx))); + let (handle, args): (u16, &[u16]) = record.map_or((cp, &[][..]), |(h, a)| (*h, a)); + let mut seen = std::collections::BTreeSet::new(); + for (index, &operand) in std::iter::once(&handle).chain(args).enumerate() { + let Some(left) = linkage_budget.checked_sub(1) else { return (out, true) }; + linkage_budget = left; + let is_bootstrap = index == 0 && record.is_some(); + if seen.insert((operand, is_bootstrap)) + && let Some((kind, target)) = constant_dependency(cf, operand, owner, method, is_bootstrap) + { + if out.len() >= max { + return (out, true); + } + out.push(Reference { caller: caller.clone(), pc: i.pc, instruction: i.name, kind, target }); + } + } + continue; + } + let hit = match i.opcode { + 0xb6..=0xb9 => { + cf.resolve_ref(cp).and_then(|r| (r.owner == owner && method.is_none_or(|n| r.name == n)).then(|| ("method", r.display()))) + } + 0xb2..=0xb5 if method.is_none() => cf.resolve_ref(cp).and_then(|r| (r.owner == owner).then(|| ("field", r.display()))), + 0xbb | 0xbd | 0xc0 | 0xc1 | 0xc5 if method.is_none() => { + let name = class_name_at(&cf.pool, cp); + (class_component(&name) == Some(owner)).then_some(("type", internal_to_dotted(&name))) + } + _ => None, + }; + if let Some((kind, target)) = hit { + if out.len() >= max { + return (out, true); + } + out.push(Reference { caller: caller.clone(), pc: i.pc, instruction: i.name, kind, target }); + } + } + } + (out, incomplete) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_support::java as fx; + + /// Two valid static methods: a one-dimensional allocation and a two-dimensional one. + fn array_reference_class(component: &str, array: &str) -> ClassFile { + let utf8 = |s: &str| { + let mut bytes = vec![1]; + bytes.extend_from_slice(&(s.len() as u16).to_be_bytes()); + bytes.extend_from_slice(s.as_bytes()); + bytes + }; + let pool = [ + utf8("sample/ArrayUses"), + vec![7, 0, 1], + utf8("java/lang/Object"), + vec![7, 0, 3], + utf8("Code"), + utf8("row"), + utf8(&format!("()[L{component};")), + utf8("grid"), + utf8(&format!("(){array}")), + utf8(component), + vec![7, 0, 10], + utf8(array), + vec![7, 0, 12], + ]; + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52, 0, 14]; + bytes.extend(pool.into_iter().flatten()); + // public/super, this, super, no interfaces or fields, two methods. + bytes.extend_from_slice(&[0, 0x21, 0, 2, 0, 4, 0, 0, 0, 0, 0, 2]); + for (name, descriptor, code) in [(6u16, 7u16, vec![4, 0xbd, 0, 11, 0xb0]), (8, 9, vec![4, 4, 0xc5, 0, 13, 2, 0xb0])] { + for word in [9u16, name, descriptor, 1, 5] { + bytes.extend_from_slice(&word.to_be_bytes()); + } + bytes.extend_from_slice(&(12u32 + code.len() as u32).to_be_bytes()); + bytes.extend_from_slice(&[0, 2, 0, 0]); // max_stack, max_locals + bytes.extend_from_slice(&(code.len() as u32).to_be_bytes()); + bytes.extend_from_slice(&code); + bytes.extend_from_slice(&[0, 0, 0, 0]); // exception table and nested attributes + } + bytes.extend_from_slice(&[0, 0]); // class attributes + let cf = parse(&bytes).unwrap(); + assert!(cf.warnings.is_empty(), "{:?}", cf.warnings); + cf + } + + #[test] + fn parentheses_in_reference_types_are_part_of_the_class_name() { + let (params, result) = method_params("(Lpkg/A)B;[Lpkg/C(D;J)Lpkg/R)S;"); + assert_eq!(params, ["pkg.A)B", "pkg.C(D[]", "long"]); + assert_eq!(result, "pkg.R)S"); + } + + #[test] + fn object_arrays_reference_the_component_class() { + let cf = array_reference_class("java/lang/String", "[[Ljava/lang/String;"); + let (refs, more) = references(&cf, "java/lang/String", None, 10); + assert!(!more); + assert_eq!(refs.len(), 2, "{refs:?}"); + assert_eq!((refs[0].instruction, refs[0].pc), ("anewarray", 1)); + assert_eq!((refs[1].instruction, refs[1].pc), ("multianewarray", 2)); + assert_eq!(refs[1].target, "java.lang.String[][]"); + let (limited, more) = references(&cf, "java/lang/String", None, 1); + assert_eq!(limited, refs[..1]); + assert!(more); + assert_eq!(references(&cf, "java/lang/String", Some("grid"), 10), (Vec::new(), false)); + assert_eq!(references(&cf, "java/lang/Integer", None, 10), (Vec::new(), false)); + } + + #[test] + fn array_components_keep_class_names_beginning_with_l() { + for component in ["Leaf", "LLeaf"] { + let cf = array_reference_class(component, &format!("[[L{component};")); + let (refs, more) = references(&cf, component, None, 10); + assert_eq!(refs.len(), 2, "{component}: {refs:?}"); + assert!(!more); + } + } + + #[test] + fn primitive_arrays_do_not_reference_a_class_named_after_the_descriptor() { + let cf = array_reference_class("I", "[[I"); + let (refs, more) = references(&cf, "I", None, 10); + assert!(!more); + assert_eq!(refs.len(), 1, "{refs:?}"); + assert_eq!(refs[0].instruction, "anewarray"); + } + + #[test] + fn parses_fixture() { + let data = fx::hello_class(); + let cf = parse(&data).unwrap(); + assert!(cf.warnings.is_empty(), "{:?}", cf.warnings); + assert_eq!(cf.this_class, "com/example/Hello"); + assert_eq!(cf.super_class.as_deref(), Some("java/lang/Object")); + assert_eq!(cf.interfaces, vec!["java/lang/Runnable"]); + assert_eq!(cf.source_file.as_deref(), Some("Hello.java")); + assert!(cf.version.major >= 45); + // field + let f = cf.fields.iter().find(|f| f.name == "count").unwrap(); + assert_eq!(field_type(&f.descriptor), "int"); + // run() loads a string and calls println + let run = cf.methods.iter().find(|m| m.name == "run").unwrap(); + assert_eq!(cf.method_signature(run), "public void run()"); + let code = run.code.as_ref().unwrap(); + let (ins, complete) = java_ops::decode(&code.bytecode, 1000); + assert!(complete, "{ins:?}"); + let text: Vec = ins.iter().map(|i| cf.format_insn(i)).collect(); + assert!(text.iter().any(|t| t == "getstatic java.lang.System.out:java.io.PrintStream"), "{text:?}"); + assert!(text.iter().any(|t| t.starts_with("ldc \"Hello")), "{text:?}"); + assert!(text.iter().any(|t| t == "invokevirtual java.io.PrintStream.println(Ljava/lang/String;)V"), "{text:?}"); + // references to System from this class + let (refs, more) = references(&cf, "java/lang/System", None, 100); + assert!(!more); + assert!(refs.iter().any(|r| r.kind == "field" && r.target.contains("out")), "{refs:?}"); + } + + #[test] + fn helpers() { + assert_eq!(internal_to_dotted("java/lang/String"), "java.lang.String"); + assert_eq!(internal_to_dotted("[Ljava/lang/String;"), "java.lang.String[]"); + assert_eq!(method_params("(Ljava/lang/String;I)V"), (vec!["java.lang.String".to_string(), "int".to_string()], "void".to_string())); + assert_eq!(method_params("()I"), (Vec::new(), "int".to_string())); + assert_eq!(Version { major: 52, minor: 0 }.java_label(), "Java 8"); + assert_eq!(Version { major: 65, minor: 0 }.java_label(), "Java 21"); + assert_eq!(decode_mutf8(&[0xc0, 0x80, 0x41]), "\0A"); + } + + #[test] + fn hostile() { + let data = fx::hello_class(); + let walk = |cf: &ClassFile| { + let _ = cf.name_dotted(); + for m in cf.methods.iter().chain(&cf.fields) { + let _ = cf.method_signature(m); + if let Some(code) = &m.code { + let (ins, _) = java_ops::decode(&code.bytecode, 10_000); + for i in &ins { + let _ = cf.format_insn(i); + } + } + } + let _ = references(cf, "java/lang/System", None, 100); + }; + for m in crate::test_support::mutations(&data) { + if let Ok(cf) = parse(&m) { + walk(&cf); + } + } + for len in 0..data.len() { + if let Ok(cf) = parse(&data[..len]) { + walk(&cf); + } + } + for seed in 0..64 { + let mut n = crate::test_support::noise(seed, 2048); + n[..4].copy_from_slice(&[0xca, 0xfe, 0xba, 0xbe]); + n[6] = 0; + n[7] = 52; + if let Ok(cf) = parse(&n) { + walk(&cf); + } + } + } +} diff --git a/crates/java-class/src/java_ops.rs b/crates/java-class/src/java_ops.rs new file mode 100644 index 000000000..46e5cdf30 --- /dev/null +++ b/crates/java-class/src/java_ops.rs @@ -0,0 +1,711 @@ +//! JVM bytecode: the opcode table (every defined opcode plus the `wide`, `tableswitch` and +//! `lookupswitch` variable-length forms) and a decoder for each instruction. Pure decoding; +//! constant-pool index operands are resolved by the caller (see [`crate::java_class`]). + +use serde::Serialize; + +/// The shape of an opcode's operands. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +pub enum Operands { + /// No operands. + None, + /// One signed byte immediate (`bipush`). + Byte, + /// One signed short immediate (`sipush`). + Short, + /// A one-byte local-variable index. + Local, + /// `iinc`: a one-byte local index and a signed byte increment. + LocalConst, + /// A two-byte signed branch offset. + Branch2, + /// A four-byte signed branch offset (`goto_w`, `jsr_w`). + Branch4, + /// A one-byte constant-pool index (`ldc`). + Cp1, + /// A two-byte constant-pool index. + Cp2, + /// `newarray`: a one-byte primitive array type. + NewArray, + /// `invokeinterface`: a two-byte index, a count byte and a zero byte. + InvokeInterface, + /// `invokedynamic`: a two-byte index and two zero bytes. + InvokeDynamic, + /// `multianewarray`: a two-byte class index and a dimension byte. + MultiANewArray, + /// `tableswitch` (variable length, 4-byte aligned). + TableSwitch, + /// `lookupswitch` (variable length, 4-byte aligned). + LookupSwitch, + /// `wide`: a prefix that widens the following load/store/ret/iinc. + Wide, + /// A reserved or unknown opcode. + Reserved, +} + +/// One opcode slot. +#[derive(Debug, Clone, Copy)] +pub struct Op { + pub name: &'static str, + pub operands: Operands, +} + +const fn op(name: &'static str, operands: Operands) -> Op { + Op { name, operands } +} + +/// The opcode table entry for `b`. +pub fn opcode(b: u8) -> Op { + use Operands as O; + match b { + 0x00 => op("nop", O::None), + 0x01 => op("aconst_null", O::None), + 0x02 => op("iconst_m1", O::None), + 0x03 => op("iconst_0", O::None), + 0x04 => op("iconst_1", O::None), + 0x05 => op("iconst_2", O::None), + 0x06 => op("iconst_3", O::None), + 0x07 => op("iconst_4", O::None), + 0x08 => op("iconst_5", O::None), + 0x09 => op("lconst_0", O::None), + 0x0a => op("lconst_1", O::None), + 0x0b => op("fconst_0", O::None), + 0x0c => op("fconst_1", O::None), + 0x0d => op("fconst_2", O::None), + 0x0e => op("dconst_0", O::None), + 0x0f => op("dconst_1", O::None), + 0x10 => op("bipush", O::Byte), + 0x11 => op("sipush", O::Short), + 0x12 => op("ldc", O::Cp1), + 0x13 => op("ldc_w", O::Cp2), + 0x14 => op("ldc2_w", O::Cp2), + 0x15 => op("iload", O::Local), + 0x16 => op("lload", O::Local), + 0x17 => op("fload", O::Local), + 0x18 => op("dload", O::Local), + 0x19 => op("aload", O::Local), + 0x1a => op("iload_0", O::None), + 0x1b => op("iload_1", O::None), + 0x1c => op("iload_2", O::None), + 0x1d => op("iload_3", O::None), + 0x1e => op("lload_0", O::None), + 0x1f => op("lload_1", O::None), + 0x20 => op("lload_2", O::None), + 0x21 => op("lload_3", O::None), + 0x22 => op("fload_0", O::None), + 0x23 => op("fload_1", O::None), + 0x24 => op("fload_2", O::None), + 0x25 => op("fload_3", O::None), + 0x26 => op("dload_0", O::None), + 0x27 => op("dload_1", O::None), + 0x28 => op("dload_2", O::None), + 0x29 => op("dload_3", O::None), + 0x2a => op("aload_0", O::None), + 0x2b => op("aload_1", O::None), + 0x2c => op("aload_2", O::None), + 0x2d => op("aload_3", O::None), + 0x2e => op("iaload", O::None), + 0x2f => op("laload", O::None), + 0x30 => op("faload", O::None), + 0x31 => op("daload", O::None), + 0x32 => op("aaload", O::None), + 0x33 => op("baload", O::None), + 0x34 => op("caload", O::None), + 0x35 => op("saload", O::None), + 0x36 => op("istore", O::Local), + 0x37 => op("lstore", O::Local), + 0x38 => op("fstore", O::Local), + 0x39 => op("dstore", O::Local), + 0x3a => op("astore", O::Local), + 0x3b => op("istore_0", O::None), + 0x3c => op("istore_1", O::None), + 0x3d => op("istore_2", O::None), + 0x3e => op("istore_3", O::None), + 0x3f => op("lstore_0", O::None), + 0x40 => op("lstore_1", O::None), + 0x41 => op("lstore_2", O::None), + 0x42 => op("lstore_3", O::None), + 0x43 => op("fstore_0", O::None), + 0x44 => op("fstore_1", O::None), + 0x45 => op("fstore_2", O::None), + 0x46 => op("fstore_3", O::None), + 0x47 => op("dstore_0", O::None), + 0x48 => op("dstore_1", O::None), + 0x49 => op("dstore_2", O::None), + 0x4a => op("dstore_3", O::None), + 0x4b => op("astore_0", O::None), + 0x4c => op("astore_1", O::None), + 0x4d => op("astore_2", O::None), + 0x4e => op("astore_3", O::None), + 0x4f => op("iastore", O::None), + 0x50 => op("lastore", O::None), + 0x51 => op("fastore", O::None), + 0x52 => op("dastore", O::None), + 0x53 => op("aastore", O::None), + 0x54 => op("bastore", O::None), + 0x55 => op("castore", O::None), + 0x56 => op("sastore", O::None), + 0x57 => op("pop", O::None), + 0x58 => op("pop2", O::None), + 0x59 => op("dup", O::None), + 0x5a => op("dup_x1", O::None), + 0x5b => op("dup_x2", O::None), + 0x5c => op("dup2", O::None), + 0x5d => op("dup2_x1", O::None), + 0x5e => op("dup2_x2", O::None), + 0x5f => op("swap", O::None), + 0x60 => op("iadd", O::None), + 0x61 => op("ladd", O::None), + 0x62 => op("fadd", O::None), + 0x63 => op("dadd", O::None), + 0x64 => op("isub", O::None), + 0x65 => op("lsub", O::None), + 0x66 => op("fsub", O::None), + 0x67 => op("dsub", O::None), + 0x68 => op("imul", O::None), + 0x69 => op("lmul", O::None), + 0x6a => op("fmul", O::None), + 0x6b => op("dmul", O::None), + 0x6c => op("idiv", O::None), + 0x6d => op("ldiv", O::None), + 0x6e => op("fdiv", O::None), + 0x6f => op("ddiv", O::None), + 0x70 => op("irem", O::None), + 0x71 => op("lrem", O::None), + 0x72 => op("frem", O::None), + 0x73 => op("drem", O::None), + 0x74 => op("ineg", O::None), + 0x75 => op("lneg", O::None), + 0x76 => op("fneg", O::None), + 0x77 => op("dneg", O::None), + 0x78 => op("ishl", O::None), + 0x79 => op("lshl", O::None), + 0x7a => op("ishr", O::None), + 0x7b => op("lshr", O::None), + 0x7c => op("iushr", O::None), + 0x7d => op("lushr", O::None), + 0x7e => op("iand", O::None), + 0x7f => op("land", O::None), + 0x80 => op("ior", O::None), + 0x81 => op("lor", O::None), + 0x82 => op("ixor", O::None), + 0x83 => op("lxor", O::None), + 0x84 => op("iinc", O::LocalConst), + 0x85 => op("i2l", O::None), + 0x86 => op("i2f", O::None), + 0x87 => op("i2d", O::None), + 0x88 => op("l2i", O::None), + 0x89 => op("l2f", O::None), + 0x8a => op("l2d", O::None), + 0x8b => op("f2i", O::None), + 0x8c => op("f2l", O::None), + 0x8d => op("f2d", O::None), + 0x8e => op("d2i", O::None), + 0x8f => op("d2l", O::None), + 0x90 => op("d2f", O::None), + 0x91 => op("i2b", O::None), + 0x92 => op("i2c", O::None), + 0x93 => op("i2s", O::None), + 0x94 => op("lcmp", O::None), + 0x95 => op("fcmpl", O::None), + 0x96 => op("fcmpg", O::None), + 0x97 => op("dcmpl", O::None), + 0x98 => op("dcmpg", O::None), + 0x99 => op("ifeq", O::Branch2), + 0x9a => op("ifne", O::Branch2), + 0x9b => op("iflt", O::Branch2), + 0x9c => op("ifge", O::Branch2), + 0x9d => op("ifgt", O::Branch2), + 0x9e => op("ifle", O::Branch2), + 0x9f => op("if_icmpeq", O::Branch2), + 0xa0 => op("if_icmpne", O::Branch2), + 0xa1 => op("if_icmplt", O::Branch2), + 0xa2 => op("if_icmpge", O::Branch2), + 0xa3 => op("if_icmpgt", O::Branch2), + 0xa4 => op("if_icmple", O::Branch2), + 0xa5 => op("if_acmpeq", O::Branch2), + 0xa6 => op("if_acmpne", O::Branch2), + 0xa7 => op("goto", O::Branch2), + 0xa8 => op("jsr", O::Branch2), + 0xa9 => op("ret", O::Local), + 0xaa => op("tableswitch", O::TableSwitch), + 0xab => op("lookupswitch", O::LookupSwitch), + 0xac => op("ireturn", O::None), + 0xad => op("lreturn", O::None), + 0xae => op("freturn", O::None), + 0xaf => op("dreturn", O::None), + 0xb0 => op("areturn", O::None), + 0xb1 => op("return", O::None), + 0xb2 => op("getstatic", O::Cp2), + 0xb3 => op("putstatic", O::Cp2), + 0xb4 => op("getfield", O::Cp2), + 0xb5 => op("putfield", O::Cp2), + 0xb6 => op("invokevirtual", O::Cp2), + 0xb7 => op("invokespecial", O::Cp2), + 0xb8 => op("invokestatic", O::Cp2), + 0xb9 => op("invokeinterface", O::InvokeInterface), + 0xba => op("invokedynamic", O::InvokeDynamic), + 0xbb => op("new", O::Cp2), + 0xbc => op("newarray", O::NewArray), + 0xbd => op("anewarray", O::Cp2), + 0xbe => op("arraylength", O::None), + 0xbf => op("athrow", O::None), + 0xc0 => op("checkcast", O::Cp2), + 0xc1 => op("instanceof", O::Cp2), + 0xc2 => op("monitorenter", O::None), + 0xc3 => op("monitorexit", O::None), + 0xc4 => op("wide", O::Wide), + 0xc5 => op("multianewarray", O::MultiANewArray), + 0xc6 => op("ifnull", O::Branch2), + 0xc7 => op("ifnonnull", O::Branch2), + 0xc8 => op("goto_w", O::Branch4), + 0xc9 => op("jsr_w", O::Branch4), + 0xca => op("breakpoint", O::None), + 0xfe => op("impdep1", O::None), + 0xff => op("impdep2", O::None), + _ => op("unknown", O::Reserved), + } +} + +/// The primitive array type for a `newarray` atype operand. +pub fn array_type(atype: i32) -> &'static str { + match atype { + 4 => "boolean", + 5 => "char", + 6 => "float", + 7 => "double", + 8 => "byte", + 9 => "short", + 10 => "int", + 11 => "long", + _ => "?", + } +} + +/// A decoded `tableswitch`/`lookupswitch`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Switch { + /// Absolute byte offset of the default branch. + pub default: i64, + /// `(key, absolute target)` pairs in listing order. + pub pairs: Vec<(i32, i64)>, +} + +/// One decoded instruction. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Insn { + /// Byte offset from the start of the method's code. + pub pc: u32, + pub opcode: u8, + pub name: &'static str, + /// Total length in bytes, including operands. + pub len: u32, + /// Local-variable index operand (load/store/ret/iinc). + #[serde(skip_serializing_if = "Option::is_none")] + pub local: Option, + /// Integer immediate (`bipush`/`sipush`/`iinc` increment/`newarray` type/`multianewarray` dims). + #[serde(skip_serializing_if = "Option::is_none")] + pub int: Option, + /// Constant-pool index operand (resolved by the caller). + #[serde(skip_serializing_if = "Option::is_none")] + pub cp_index: Option, + /// Absolute byte offset of a branch target. + #[serde(skip_serializing_if = "Option::is_none")] + pub branch: Option, + /// A switch table when the opcode is `tableswitch`/`lookupswitch`. + #[serde(skip_serializing_if = "Option::is_none")] + pub switch: Option, + /// True when this instruction was prefixed by `wide`. + #[serde(skip_serializing_if = "std::ops::Not::not")] + pub wide: bool, +} + +/// Most entries decoded from one switch table. +const MAX_SWITCH: usize = 1 << 20; + +fn s8(code: &[u8], at: usize) -> Option { + code.get(at).map(|&b| i32::from(b as i8)) +} +fn u16b(code: &[u8], at: usize) -> Option { + Some(u16::from(*code.get(at)?) << 8 | u16::from(*code.get(at + 1)?)) +} +fn s16(code: &[u8], at: usize) -> Option { + u16b(code, at).map(|v| i32::from(v as i16)) +} +fn s32(code: &[u8], at: usize) -> Option { + Some(i32::from(*code.get(at)?) << 24 | i32::from(*code.get(at + 1)?) << 16 | i32::from(*code.get(at + 2)?) << 8 | i32::from(*code.get(at + 3)?)) +} + +fn base(pc: usize, opcode: u8, name: &'static str) -> Insn { + Insn { pc: pc as u32, opcode, name, len: 1, local: None, int: None, cp_index: None, branch: None, switch: None, wide: false } +} + +/// Decode one instruction at `pc`, or `None` for invalid or incomplete operands. +pub fn decode_one(code: &[u8], pc: usize) -> Option { + let b = *code.get(pc)?; + let o = opcode(b); + let mut insn = base(pc, b, o.name); + let rel = |d: i32| pc as i64 + i64::from(d); + match o.operands { + Operands::None | Operands::Reserved => {} + Operands::Byte => { + insn.int = Some(s8(code, pc + 1)?); + insn.len = 2; + } + Operands::Short => { + insn.int = Some(s16(code, pc + 1)?); + insn.len = 3; + } + Operands::Local => { + insn.local = Some(u16::from(*code.get(pc + 1)?)); + insn.len = 2; + } + Operands::LocalConst => { + insn.local = Some(u16::from(*code.get(pc + 1)?)); + insn.int = Some(s8(code, pc + 2)?); + insn.len = 3; + } + Operands::Branch2 => { + insn.branch = Some(rel(s16(code, pc + 1)?)); + insn.len = 3; + } + Operands::Branch4 => { + insn.branch = Some(rel(s32(code, pc + 1)?)); + insn.len = 5; + } + Operands::Cp1 => { + insn.cp_index = Some(u16::from(*code.get(pc + 1)?)); + insn.len = 2; + } + Operands::Cp2 => { + insn.cp_index = Some(u16b(code, pc + 1)?); + insn.len = 3; + } + Operands::NewArray => { + let atype = *code.get(pc + 1)?; + if !(4..=11).contains(&atype) { + return None; + } + insn.int = Some(i32::from(atype)); + insn.len = 2; + } + Operands::InvokeInterface => { + insn.cp_index = Some(u16b(code, pc + 1)?); + if *code.get(pc + 3)? == 0 || *code.get(pc + 4)? != 0 { + return None; + } + insn.len = 5; + } + Operands::InvokeDynamic => { + insn.cp_index = Some(u16b(code, pc + 1)?); + if *code.get(pc + 3)? != 0 || *code.get(pc + 4)? != 0 { + return None; + } + insn.len = 5; + } + Operands::MultiANewArray => { + insn.cp_index = Some(u16b(code, pc + 1)?); + let dimensions = *code.get(pc + 3)?; + if dimensions == 0 { + return None; + } + insn.int = Some(i32::from(dimensions)); + insn.len = 4; + } + Operands::Wide => return decode_wide(code, pc), + Operands::TableSwitch => return decode_tableswitch(code, pc), + Operands::LookupSwitch => return decode_lookupswitch(code, pc), + } + if pc.checked_add(insn.len as usize)? > code.len() { + return None; + } + Some(insn) +} + +fn decode_wide(code: &[u8], pc: usize) -> Option { + let real = *code.get(pc + 1)?; + if !matches!(real, 0x15..=0x19 | 0x36..=0x3a | 0x84 | 0xa9) { + return None; + } + let o = opcode(real); + let mut insn = base(pc, real, o.name); + insn.wide = true; + if real == 0x84 { + // wide iinc: 2-byte local, 2-byte signed const + insn.local = Some(u16b(code, pc + 2)?); + insn.int = Some(s16(code, pc + 4)?); + insn.len = 6; + } else { + // wide load/store/ret: 2-byte local + insn.local = Some(u16b(code, pc + 2)?); + insn.len = 4; + } + if pc.checked_add(insn.len as usize)? > code.len() { + return None; + } + Some(insn) +} + +/// Padding so the operand word after a switch opcode is 4-byte aligned from the code start. +fn switch_pad(pc: usize) -> usize { + (4 - ((pc + 1) % 4)) % 4 +} + +fn decode_tableswitch(code: &[u8], pc: usize) -> Option { + let mut at = pc + 1 + switch_pad(pc); + let default = rel_i64(pc, s32(code, at)?); + let low = s32(code, at + 4)?; + let high = s32(code, at + 8)?; + at += 12; + if high < low { + return None; + } + let count = usize::try_from(i64::from(high) - i64::from(low) + 1).ok()?; + if count > MAX_SWITCH { + return None; + } + let end = at.checked_add(count.checked_mul(4)?)?; + code.get(at..end)?; + let mut pairs = Vec::with_capacity(count); + for i in 0..count { + let off = s32(code, at + i * 4)?; + pairs.push((low.wrapping_add(i as i32), rel_i64(pc, off))); + } + let mut insn = base(pc, 0xaa, "tableswitch"); + insn.switch = Some(Switch { default, pairs }); + insn.len = (end - pc) as u32; + Some(insn) +} + +fn decode_lookupswitch(code: &[u8], pc: usize) -> Option { + let mut at = pc + 1 + switch_pad(pc); + let default = rel_i64(pc, s32(code, at)?); + let npairs = s32(code, at + 4)?; + at += 8; + if npairs < 0 { + return None; + } + let count = npairs as usize; + if count > MAX_SWITCH { + return None; + } + let end = at.checked_add(count.checked_mul(8)?)?; + code.get(at..end)?; + let mut pairs = Vec::with_capacity(count); + let mut previous = None; + for i in 0..count { + let key = s32(code, at + i * 8)?; + if previous.is_some_and(|previous| key <= previous) { + return None; + } + previous = Some(key); + let off = s32(code, at + i * 8 + 4)?; + pairs.push((key, rel_i64(pc, off))); + } + let mut insn = base(pc, 0xab, "lookupswitch"); + insn.switch = Some(Switch { default, pairs }); + insn.len = (end - pc) as u32; + Some(insn) +} + +fn rel_i64(pc: usize, off: i32) -> i64 { + pc as i64 + i64::from(off) +} + +/// Decode a whole method body, stopping at `max` instructions. `complete` is false when a +/// instruction has invalid/incomplete operands or the cap was hit. +pub fn decode(code: &[u8], max: usize) -> (Vec, bool) { + let mut out = Vec::new(); + let mut pc = 0usize; + let mut complete = true; + while pc < code.len() { + if out.len() >= max { + complete = false; + break; + } + match decode_one(code, pc) { + Some(i) => { + pc += (i.len as usize).max(1); + out.push(i); + } + None => { + complete = false; + break; + } + } + } + (out, complete) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn lookup(pc: usize, keys: &[i32]) -> Vec { + let mut code = vec![0; pc]; + code.push(0xab); + while !code.len().is_multiple_of(4) { + code.push(0); + } + code.extend_from_slice(&0i32.to_be_bytes()); + code.extend_from_slice(&(keys.len() as i32).to_be_bytes()); + for key in keys { + code.extend_from_slice(&key.to_be_bytes()); + code.extend_from_slice(&0i32.to_be_bytes()); + } + code + } + + #[test] + fn lookup_keys_must_increase_strictly() { + for keys in [&[1, 1][..], &[1, 0], &[0, -1], &[i32::MIN, i32::MAX, i32::MIN]] { + for pc in 0..4 { + let mut code = lookup(pc, keys); + code.push(0xb1); + assert!(decode_one(&code, pc).is_none(), "pc {pc}, keys {keys:?}"); + let (decoded, complete) = decode(&code, 100); + assert!(!complete); + assert_eq!(decoded.len(), pc, "preserve preceding nops, stop before the bad switch"); + } + } + } + + #[test] + fn lookup_keys_use_signed_order_at_every_alignment() { + for keys in [&[][..], &[i32::MIN, -1, 0, i32::MAX]] { + for pc in 0..4 { + let code = lookup(pc, keys); + let insn = decode_one(&code, pc).unwrap(); + assert_eq!(insn.len as usize, code.len() - pc); + let switch = insn.switch.unwrap(); + assert_eq!(switch.default, pc as i64); + assert_eq!(switch.pairs, keys.iter().map(|&key| (key, pc as i64)).collect::>()); + assert!(decode(&code, 100).1); + } + } + } + + #[test] + fn switch_payloads_must_be_complete() { + for pc in 0..4 { + let lookup = lookup(pc, &[-1, 1]); + let mut dense = vec![0; pc]; + dense.push(0xaa); + while !dense.len().is_multiple_of(4) { + dense.push(0); + } + for word in [0i32, i32::MAX - 1, i32::MAX, 0, 0] { + dense.extend_from_slice(&word.to_be_bytes()); + } + for code in [lookup, dense] { + assert!(decode_one(&code, pc).is_some()); + for end in pc + 1..code.len() { + assert!(decode_one(&code[..end], pc).is_none(), "pc {pc}, end {end}"); + } + } + } + } + + #[test] + fn switch_counts_cannot_reserve_an_absent_table() { + let mut lookup = lookup(0, &[]); + lookup[8..12].copy_from_slice(&(MAX_SWITCH as i32).to_be_bytes()); + assert!(decode_one(&lookup, 0).is_none()); + for (low, high) in [(0i32, MAX_SWITCH as i32 - 1), (i32::MIN, i32::MAX)] { + let mut dense = vec![0xaa, 0, 0, 0]; + for word in [0, low, high] { + dense.extend_from_slice(&word.to_be_bytes()); + } + assert!(decode_one(&dense, 0).is_none()); + } + } + + #[test] + fn table_covers_defined_opcodes() { + let mut named = 0; + for b in 0..=255u8 { + if opcode(b).name != "unknown" { + named += 1; + } + } + // 0x00..=0xca is 203 opcodes, plus impdep1/impdep2. + assert_eq!(named, 203 + 2); + assert_eq!(opcode(0xb6).name, "invokevirtual"); + assert_eq!(opcode(0x10).name, "bipush"); + assert_eq!(opcode(0xc4).name, "wide"); + } + + #[test] + fn decodes_core_formats() { + // iconst_1; bipush 7; istore_1; goto +3 ; (pad to reach len) return + let code = [0x04, 0x10, 0x07, 0x3c, 0xa7, 0x00, 0x03, 0xb1]; + let (ins, complete) = decode(&code, 100); + assert!(complete, "{ins:?}"); + assert_eq!(ins[0].name, "iconst_1"); + assert_eq!(ins[1].name, "bipush"); + assert_eq!(ins[1].int, Some(7)); + assert_eq!(ins[2].name, "istore_1"); + assert_eq!(ins[3].name, "goto"); + assert_eq!(ins[3].branch, Some(7)); // pc 4 + 3 + assert_eq!(ins[4].name, "return"); + } + + #[test] + fn decodes_invoke_and_wide() { + // invokevirtual #5 ; invokeinterface #6 count 2 ; wide iload 300 + let code = [0xb6, 0x00, 0x05, 0xb9, 0x00, 0x06, 0x02, 0x00, 0xc4, 0x15, 0x01, 0x2c]; + let (ins, complete) = decode(&code, 100); + assert!(complete); + assert_eq!(ins[0].name, "invokevirtual"); + assert_eq!(ins[0].cp_index, Some(5)); + assert_eq!(ins[0].len, 3); + assert_eq!(ins[1].name, "invokeinterface"); + assert_eq!(ins[1].cp_index, Some(6)); + assert_eq!(ins[1].len, 5); + assert_eq!(ins[2].name, "iload"); + assert!(ins[2].wide); + assert_eq!(ins[2].local, Some(300)); + assert_eq!(ins[2].len, 4); + } + + #[test] + fn decodes_switches() { + // tableswitch at pc 0: pad 3, default +40, low 1, high 2, offsets +10, +20 + let mut code = vec![0xaa, 0, 0, 0]; + code.extend_from_slice(&40i32.to_be_bytes()); + code.extend_from_slice(&1i32.to_be_bytes()); + code.extend_from_slice(&2i32.to_be_bytes()); + code.extend_from_slice(&10i32.to_be_bytes()); + code.extend_from_slice(&20i32.to_be_bytes()); + let i = decode_one(&code, 0).unwrap(); + assert_eq!(i.name, "tableswitch"); + let sw = i.switch.unwrap(); + assert_eq!(sw.default, 40); + assert_eq!(sw.pairs, vec![(1, 10), (2, 20)]); + assert_eq!(i.len as usize, code.len()); + + // lookupswitch at pc 0: pad 3, default +4, npairs 1, (key 99 -> +8) + let mut lk = vec![0xab, 0, 0, 0]; + lk.extend_from_slice(&4i32.to_be_bytes()); + lk.extend_from_slice(&1i32.to_be_bytes()); + lk.extend_from_slice(&99i32.to_be_bytes()); + lk.extend_from_slice(&8i32.to_be_bytes()); + let l = decode_one(&lk, 0).unwrap(); + let sw = l.switch.unwrap(); + assert_eq!(sw.default, 4); + assert_eq!(sw.pairs, vec![(99, 8)]); + } + + #[test] + fn hostile() { + for seed in 0..256 { + let n = crate::test_support::noise(seed, 512); + let _ = decode(&n, 10_000); + } + // truncated operands never panic + let _ = decode(&[0xb6, 0x00], 10); + let _ = decode(&[0xaa, 0, 0, 0, 0, 0, 0, 0], 10); + let _ = decode(&[0xab, 0, 0, 0, 0, 0, 0, 0, 0x7f, 0xff, 0xff, 0xff], 10); + let _ = decode(&[0xc4], 10); + } +} diff --git a/crates/java-class/src/lib.rs b/crates/java-class/src/lib.rs new file mode 100644 index 000000000..4d135e16b --- /dev/null +++ b/crates/java-class/src/lib.rs @@ -0,0 +1,50 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +//! Java class-file inspection and JVM bytecode decoding. Never executes bytecode. +//! Retains source item, attribute and annotation-depth limits and partial reports. +mod bytes; +mod descriptor; +pub mod java_class; +pub mod java_ops; +pub use java_class::*; +#[cfg(test)] +mod test_support; +/// File admission errors; damaged optional structures retain partial-report warnings. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum JavaClassError { + #[error("the file ends early ({0})")] + Truncated(String), + #[error("the file is malformed ({0})")] + Malformed(String), + #[error("not supported: {0}")] + Unsupported(String), +} +use JavaClassError as FormatError; + +#[cfg(test)] +#[path = "regressions/java_array_operands.rs"] +mod java_array_operands; + +#[cfg(test)] +#[path = "regressions/java_attribute_names.rs"] +mod java_attribute_names; + +#[cfg(test)] +#[path = "regressions/java_constant_pool_slots.rs"] +mod java_constant_pool_slots; + +#[cfg(test)] +#[path = "regressions/java_invoke_operands.rs"] +mod java_invoke_operands; + +#[cfg(test)] +#[path = "regressions/java_linkage_references.rs"] +mod java_linkage_references; + +#[cfg(test)] +#[path = "regressions/java_truncated_attributes.rs"] +mod java_truncated_attributes; + +#[cfg(test)] +#[path = "regressions/java_wide_opcodes.rs"] +mod java_wide_opcodes; diff --git a/crates/java-class/src/regressions/java_array_operands.rs b/crates/java-class/src/regressions/java_array_operands.rs new file mode 100644 index 000000000..b5867db52 --- /dev/null +++ b/crates/java-class/src/regressions/java_array_operands.rs @@ -0,0 +1,48 @@ +use crate::java_ops::{decode, decode_one}; + +#[test] +fn invalid_primitive_array_types_stop_before_the_allocation() { + for atype in (0..=u8::MAX).filter(|value| !(4..=11).contains(value)) { + assert!(decode_one(&[0xbc, atype], 0).is_none(), "atype {atype}"); + let (instructions, complete) = decode(&[0, 0xbc, atype, 0xb1], 100); + assert!(!complete, "atype {atype}"); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); + } +} + +#[test] +fn zero_dimension_multidimensional_allocations_are_not_complete_bytecode() { + assert!(decode_one(&[0xc5, 0, 1, 0], 0).is_none()); + let (instructions, complete) = decode(&[0, 0xc5, 0, 1, 0, 0xb1], 100); + assert!(!complete); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); +} + +#[test] +fn every_defined_primitive_type_and_nonzero_dimension_remains_decodable() { + for atype in 4..=11 { + let (instructions, complete) = decode(&[0xbc, atype, 0xb1], 100); + assert!(complete); + assert_eq!(instructions.len(), 2); + assert_eq!(instructions[0].int, Some(i32::from(atype))); + assert_eq!(instructions[0].len, 2); + } + for dimensions in 1..=u8::MAX { + let instruction = decode_one(&[0, 0xc5, 0x12, 0x34, dimensions], 1).unwrap(); + assert_eq!(instruction.pc, 1); + assert_eq!(instruction.cp_index, Some(0x1234)); + assert_eq!(instruction.int, Some(i32::from(dimensions))); + assert_eq!(instruction.len, 4); + } +} + +#[test] +fn incomplete_array_operands_remain_rejected() { + for instruction in [&[0xbc, 10][..], &[0xc5, 0, 1, 2][..]] { + for end in 1..instruction.len() { + assert!(decode_one(&instruction[..end], 0).is_none()); + } + } +} diff --git a/crates/java-class/src/regressions/java_attribute_names.rs b/crates/java-class/src/regressions/java_attribute_names.rs new file mode 100644 index 000000000..c506ed0c9 --- /dev/null +++ b/crates/java-class/src/regressions/java_attribute_names.rs @@ -0,0 +1,132 @@ +use crate::java_class::{self, ClassFile, Const}; + +#[derive(Clone, Copy, Debug)] +enum Scope { + Class, + Field, + Method, + Code, +} + +fn u16b(out: &mut Vec, n: u16) { + out.extend_from_slice(&n.to_be_bytes()); +} + +fn u32b(out: &mut Vec, n: u32) { + out.extend_from_slice(&n.to_be_bytes()); +} + +fn utf8(out: &mut Vec, text: &str) { + out.push(1); + u16b(out, text.len() as u16); + out.extend_from_slice(text.as_bytes()); +} + +fn attr(name: u16, info: &[u8]) -> Vec { + let mut out = Vec::new(); + u16b(&mut out, name); + u32b(&mut out, info.len() as u32); + out.extend_from_slice(info); + out +} + +fn attributes(out: &mut Vec, repeated: u16, known: &[Vec]) { + u16b(out, repeated + known.len() as u16); + for _ in 0..repeated { + out.extend_from_slice(&attr(5, &[])); + } + for bytes in known { + out.extend_from_slice(bytes); + } +} + +// A valid shared CONSTANT_Utf8 is named by every unknown attribute. Known +// attributes follow it, so avoiding name copies must not discard their facts. +fn fixture(scope: Scope, repeated: u16) -> Vec { + let mut out = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52]; + u16b(&mut out, 17); + utf8(&mut out, "AttributeFixture"); // 1 + out.push(7); + u16b(&mut out, 1); // 2: this class + utf8(&mut out, "java/lang/Object"); // 3 + out.push(7); + u16b(&mut out, 3); // 4: superclass + utf8(&mut out, &format!("org.example.{}", "A".repeat(usize::from(u16::MAX) - 12))); // 5 + for text in ["SourceFile", "AttributeFixture.java", "field", "I"] { + utf8(&mut out, text); // 6..9 + } + out.push(3); + u32b(&mut out, 42); // 10 + for text in ["ConstantValue", "run", "()V", "Code", "LineNumberTable", "Deprecated"] { + utf8(&mut out, text); // 11..16 + } + for word in [0x0021, 2, 4, 0, 1, 0x0019, 8, 9] { + u16b(&mut out, word); + } + attributes(&mut out, if matches!(scope, Scope::Field) { repeated } else { 0 }, &[attr(11, &10u16.to_be_bytes()), attr(16, &[])]); + for word in [1, 0x0009, 12, 13] { + u16b(&mut out, word); + } + let mut code = vec![0, 0, 0, 0, 0, 0, 0, 1, 0xb1, 0, 0]; + attributes(&mut code, if matches!(scope, Scope::Code) { repeated } else { 0 }, &[attr(15, &[0, 1, 0, 0, 0, 7])]); + attributes(&mut out, if matches!(scope, Scope::Method) { repeated } else { 0 }, &[attr(14, &code)]); + attributes(&mut out, if matches!(scope, Scope::Class) { repeated } else { 0 }, &[attr(6, &7u16.to_be_bytes())]); + out +} + +fn check_facts(parsed: &ClassFile) { + assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings); + assert_eq!(parsed.this_class, "AttributeFixture"); + assert_eq!(parsed.super_class.as_deref(), Some("java/lang/Object")); + assert_eq!(parsed.source_file.as_deref(), Some("AttributeFixture.java")); + assert_eq!(parsed.fields.len(), 1); + assert_eq!(parsed.fields[0].name, "field"); + assert_eq!(parsed.fields[0].constant_value.as_deref(), Some("42")); + assert!(parsed.fields[0].deprecated); + assert_eq!(parsed.methods.len(), 1); + assert_eq!(parsed.methods[0].name, "run"); + let code = parsed.methods[0].code.as_ref().unwrap(); + assert_eq!(code.bytecode, [0xb1]); + assert_eq!(code.line_numbers, [(0, 7)]); + assert!(matches!(&parsed.pool[5], Const::Utf8(name) if name.len() == usize::from(u16::MAX))); +} + +#[test] +fn known_attributes_survive_repeated_unknown_names_at_every_scope() { + for scope in [Scope::Class, Scope::Field, Scope::Method, Scope::Code] { + check_facts(&java_class::parse(&fixture(scope, 64)).unwrap()); + } +} + +fn memory_case(scope: Scope) { + let bytes = fixture(scope, 4096); + assert!(bytes.len() < 100_000); + check_facts(&java_class::parse(&bytes).unwrap()); +} + +// Run each ignored case separately with a 128 MiB process address-space limit. +// The original parser copies 256 MiB of one attribute name; the fixture itself +// is under 100 KiB. These checks deliberately make no timing assertion. +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_class_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Class); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_field_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Field); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_method_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Method); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_code_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Code); +} diff --git a/crates/java-class/src/regressions/java_constant_pool_slots.rs b/crates/java-class/src/regressions/java_constant_pool_slots.rs new file mode 100644 index 000000000..15ad88567 --- /dev/null +++ b/crates/java-class/src/regressions/java_constant_pool_slots.rs @@ -0,0 +1,53 @@ +use crate::{FormatError, java_class}; + +fn class_with_pool(count: u16, pool: &[u8]) -> Vec { + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52]; + bytes.extend_from_slice(&count.to_be_bytes()); + bytes.extend_from_slice(pool); + bytes.extend_from_slice(&[0; 14]); + bytes +} + +#[test] +fn a_wide_constant_needs_its_reserved_slot() { + for tag in [5, 6] { + let mut pool = vec![tag]; + pool.extend_from_slice(&[0; 8]); + let bytes = class_with_pool(2, &pool); + assert!(matches!(java_class::parse(&bytes), Err(FormatError::Malformed(message)) if message.contains("second slot"))); + } +} + +#[test] +fn the_largest_pool_cannot_overflow_on_a_trailing_wide_constant() { + for tag in [5, 6] { + let mut pool = [3, 0, 0, 0, 0].repeat(usize::from(u16::MAX) - 2); + pool.push(tag); + pool.extend_from_slice(&[0; 8]); + let bytes = class_with_pool(u16::MAX, &pool); + assert!(matches!(java_class::parse(&bytes), Err(FormatError::Malformed(message)) if message.contains("second slot"))); + } +} + +#[test] +fn a_wide_constant_with_two_remaining_slots_is_retained() { + for tag in [5, 6] { + for count in [3, u16::MAX] { + let mut pool = [3, 0, 0, 0, 0].repeat(usize::from(count) - 3); + pool.push(tag); + pool.extend_from_slice(&[0; 8]); + let parsed = java_class::parse(&class_with_pool(count, &pool)).unwrap(); + assert_eq!(parsed.pool.len(), usize::from(count)); + assert!(matches!(parsed.pool.last(), Some(java_class::Const::Unusable))); + assert!(matches!(parsed.pool[usize::from(count) - 2], java_class::Const::Long(_) | java_class::Const::Double(_))); + } + } +} + +#[test] +fn ordinary_final_constants_and_existing_classes_still_parse() { + let parsed = java_class::parse(&class_with_pool(2, &[3, 0, 0, 0, 7])).unwrap(); + assert_eq!(parsed.pool, vec![java_class::Const::Unusable, java_class::Const::Integer(7)]); + let parsed = java_class::parse(&crate::test_support::java::hello_class()).unwrap(); + assert!(!parsed.methods.is_empty()); +} diff --git a/crates/java-class/src/regressions/java_invoke_operands.rs b/crates/java-class/src/regressions/java_invoke_operands.rs new file mode 100644 index 000000000..a99d8803b --- /dev/null +++ b/crates/java-class/src/regressions/java_invoke_operands.rs @@ -0,0 +1,76 @@ +use crate::java_class; +use crate::java_ops::{decode, decode_one}; + +#[test] +fn invokeinterface_requires_a_count_and_zero_reserved_byte() { + for code in [[0xb9, 0, 1, 0, 0], [0xb9, 0, 1, 1, 1], [0xb9, 0, 1, 255, 255]] { + assert!(decode_one(&code, 0).is_none(), "{code:?}"); + assert!(!decode(&code, 16).1); + } +} + +#[test] +fn invokedynamic_requires_both_reserved_bytes_to_be_zero() { + for code in [[0xba, 0, 1, 1, 0], [0xba, 0, 1, 0, 1], [0xba, 0, 1, 255, 255]] { + assert!(decode_one(&code, 0).is_none(), "{code:?}"); + assert!(!decode(&code, 16).1); + } +} + +#[test] +fn valid_and_truncated_invocations_keep_their_boundaries() { + for count in [1, 2, 255] { + let instruction = decode_one(&[0xb9, 0x12, 0x34, count, 0], 0).unwrap(); + assert_eq!(instruction.cp_index, Some(0x1234)); + assert_eq!(instruction.len, 5); + } + let instruction = decode_one(&[0xba, 0x12, 0x34, 0, 0], 0).unwrap(); + assert_eq!(instruction.cp_index, Some(0x1234)); + for code in [[0xb9, 0, 1, 1, 0], [0xba, 0, 1, 0, 0]] { + for len in 1..5 { + assert!(decode_one(&code[..len], 0).is_none()); + } + } + let (instructions, complete) = decode(&[0xb9, 0, 1, 1, 0, 0xba, 0, 2, 0, 0, 0xb1], 16); + assert!(complete); + assert_eq!(instructions.len(), 3); + assert_eq!(instructions[2].pc, 10); +} + +fn reference_class() -> java_class::ClassFile { + let mut class = java_class::parse(&crate::test_support::java::hello_class()).unwrap(); + class.methods.retain(|method| method.name == "run"); + class +} + +#[test] +fn malformed_invocations_mark_reference_scans_incomplete() { + let valid = reference_class(); + let (expected, incomplete) = java_class::references(&valid, "java/io/PrintStream", None, 10); + assert!(!incomplete); + assert_eq!(expected.len(), 1); + for invalid in [[0xb9, 0, 1, 0, 0], [0xb9, 0, 1, 1, 1], [0xba, 0, 1, 1, 0], [0xba, 0, 1, 0, 1]] { + let mut class = valid.clone(); + let code = &mut class.methods[0].code.as_mut().unwrap().bytecode; + let later_reference = code.clone(); + *code = invalid.to_vec(); + code.extend_from_slice(&later_reference); + let (found, incomplete) = java_class::references(&class, "java/io/PrintStream", None, 10); + assert!(found.is_empty()); + assert!(incomplete, "invalid invocation must not hide an unfinished reference scan: {invalid:?}"); + } +} + +#[test] +fn incomplete_scans_keep_earlier_references_and_scan_other_methods() { + let mut class = reference_class(); + let mut later_method = class.methods[0].clone(); + later_method.name = "later".into(); + class.methods[0].code.as_mut().unwrap().bytecode.extend_from_slice(&[0xba, 0, 1, 1, 0]); + class.methods.push(later_method); + let (found, incomplete) = java_class::references(&class, "java/io/PrintStream", None, 10); + assert!(incomplete); + assert_eq!(found.len(), 2); + assert!(found[0].caller.contains(".run:(")); + assert!(found[1].caller.contains(".later:(")); +} diff --git a/crates/java-class/src/regressions/java_linkage_references.rs b/crates/java-class/src/regressions/java_linkage_references.rs new file mode 100644 index 000000000..7c05abe94 --- /dev/null +++ b/crates/java-class/src/regressions/java_linkage_references.rs @@ -0,0 +1,97 @@ +use crate::java_class::{parse, references}; + +/// A method with a chosen load or call, plus a dynamic call site and a dynamic constant with distinct bootstrap signatures. +fn class(code: &[u8]) -> Vec { + fn utf(s: &str) -> Vec { + let mut b = vec![1]; + b.extend((s.len() as u16).to_be_bytes()); + b.extend(s.bytes()); + b + } + let pool = [ + utf("Uses"), + vec![7, 0, 1], + utf("java/lang/Object"), + vec![7, 0, 3], + utf("run"), + utf("()V"), + utf("Code"), + utf("BootstrapMethods"), + utf("Target"), + vec![7, 0, 9], + utf("apply"), + vec![12, 0, 11, 0, 6], + vec![10, 0, 10, 0, 12], + vec![15, 6, 0, 13], + utf("Factory"), + vec![7, 0, 15], + utf("boot"), + vec![12, 0, 17, 0, 28], + vec![10, 0, 16, 0, 18], + vec![15, 6, 0, 19], + utf("([LTarget;)V"), + vec![16, 0, 21], + vec![18, 0, 0, 0, 12], + utf("value"), + utf("I"), + vec![12, 0, 24, 0, 25], + vec![17, 0, 1, 0, 26], + utf( + "(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;Ljava/lang/invoke/MethodHandle;)Ljava/lang/invoke/CallSite;", + ), + utf("(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/Class;)I"), + vec![12, 0, 17, 0, 29], + vec![10, 0, 16, 0, 30], + vec![15, 6, 0, 31], + ]; + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 55]; + bytes.extend((pool.len() as u16 + 1).to_be_bytes()); + for e in pool { + bytes.extend(e); + } + bytes.extend([0, 0x21, 0, 2, 0, 4, 0, 0, 0, 0, 0, 1, 0, 9, 0, 5, 0, 6, 0, 1, 0, 7]); + bytes.extend(((12 + code.len()) as u32).to_be_bytes()); + bytes.extend([0, 3, 0, 0]); + bytes.extend((code.len() as u32).to_be_bytes()); + bytes.extend(code); + bytes.extend([0, 0, 0, 0]); + let boots = [0, 2, 0, 20, 0, 1, 0, 14, 0, 32, 0, 0]; + bytes.extend([0, 1, 0, 8]); + bytes.extend((boots.len() as u32).to_be_bytes()); + bytes.extend(boots); + bytes +} +fn kinds(code: &[u8], owner: &str, method: Option<&str>) -> Vec<&'static str> { + let cf = parse(&class(code)).unwrap(); + let (hits, partial) = references(&cf, owner, method, 10); + assert!(!partial); + hits.into_iter().map(|r| r.kind).collect() +} +#[test] +fn class_literal_has_a_use_site() { + assert_eq!(kinds(&[0x12, 10, 0x57, 0xb1], "Target", None), ["type"]); +} +#[test] +fn literal_method_handle_finds_its_member() { + assert_eq!(kinds(&[0x12, 14, 0x57, 0xb1], "Target", Some("apply")), ["method-handle"]); +} +#[test] +fn method_type_mentions_object_array_components() { + assert_eq!(kinds(&[0x12, 22, 0x57, 0xb1], "Target", None), ["method-type"]); +} +#[test] +fn dynamic_call_exposes_factory_dependency() { + assert_eq!(kinds(&[0xba, 0, 23, 0, 0, 0xb1], "Factory", Some("boot")), ["bootstrap-method"]); +} +#[test] +fn dynamic_call_exposes_static_method_handle_argument() { + assert_eq!(kinds(&[0xba, 0, 23, 0, 0, 0xb1], "Target", Some("apply")), ["method-handle"]); +} +#[test] +fn dynamic_constant_exposes_bootstrap_dependency() { + assert_eq!(kinds(&[0x12, 27, 0x57, 0xb1], "Factory", Some("boot")), ["bootstrap-method"]); +} +#[test] +fn unused_bootstrap_does_not_introduce_a_reference() { + assert!(kinds(&[0xb1], "Factory", None).is_empty()); +} diff --git a/crates/java-class/src/regressions/java_truncated_attributes.rs b/crates/java-class/src/regressions/java_truncated_attributes.rs new file mode 100644 index 000000000..700640f33 --- /dev/null +++ b/crates/java-class/src/regressions/java_truncated_attributes.rs @@ -0,0 +1,46 @@ +use crate::java_class::parse; +use crate::test_support::java::hello_class; + +/// The fixture ends in a class attribute count and a single two-byte SourceFile attribute. +const ATTRIBUTE_TABLE_BYTES: usize = 10; + +/// Every cut of the attribute count, header or body leaves a partial class report. +#[test] +fn incomplete_class_attribute_table_reports_a_warning() { + let data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + for end in start..data.len() { + let class = parse(&data[..end]).unwrap(); + assert_eq!(class.methods.len(), 4); + assert!(class.source_file.is_none()); + assert!(class.warnings.iter().any(|warning| warning.contains("class attribute table")), "cut at {}", end - start); + } +} + +/// A complete attribute stays available when a subsequent attribute is cut short. +#[test] +fn completed_class_attributes_survive_a_truncated_record() { + let mut data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + data[start..start + 2].copy_from_slice(&2u16.to_be_bytes()); + data.extend_from_slice(&[0, 1, 0, 0, 0, 2, 0]); + let class = parse(&data).unwrap(); + assert_eq!(class.source_file.as_deref(), Some("Hello.java")); + assert!(class.warnings.iter().any(|warning| warning.contains("class attribute table"))); +} + +/// Complete, empty and unknown class attributes do not trigger a truncation warning. +#[test] +fn complete_class_attribute_tables_are_accepted() { + let mut data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + let original = parse(&data).unwrap(); + assert_eq!(original.source_file.as_deref(), Some("Hello.java")); + assert!(original.warnings.is_empty()); + data[start..start + 2].copy_from_slice(&2u16.to_be_bytes()); + data.extend_from_slice(&[0, 1, 0, 0, 0, 1, 0]); + assert!(parse(&data).unwrap().warnings.is_empty()); + data.truncate(start + 2); + data[start..].fill(0); + assert!(parse(&data).unwrap().warnings.is_empty()); +} diff --git a/crates/java-class/src/regressions/java_wide_opcodes.rs b/crates/java-class/src/regressions/java_wide_opcodes.rs new file mode 100644 index 000000000..85c03ffaa --- /dev/null +++ b/crates/java-class/src/regressions/java_wide_opcodes.rs @@ -0,0 +1,33 @@ +use crate::java_ops::{decode, decode_one}; + +#[test] +fn only_defined_wide_opcodes_are_accepted() { + for op in 0..=255u8 { + let valid = matches!(op, 0x15..=0x19 | 0x36..=0x3a | 0x84 | 0xa9); + let code = [0xc4, op, 0x01, 0x2c, 0xff, 0xfe]; + assert_eq!(decode_one(&code, 0).is_some(), valid, "opcode {op:#x}"); + } +} + +#[test] +fn invalid_wide_does_not_invent_a_method_body() { + let (instructions, complete) = decode(&[0x00, 0xc4, 0xb1, 0, 1, 0xb1], 32); + assert!(!complete); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); +} + +#[test] +fn wide_locals_and_signed_increments_are_preserved() { + for op in [0x15, 0x16, 0x17, 0x18, 0x19, 0x36, 0x37, 0x38, 0x39, 0x3a, 0xa9] { + let instruction = decode_one(&[0xc4, op, 0xff, 0xff], 0).unwrap(); + assert_eq!(instruction.local, Some(u16::MAX)); + assert_eq!(instruction.len, 4); + assert!(instruction.wide); + } + let instruction = decode_one(&[0xc4, 0x84, 0x01, 0x2c, 0xff, 0xfe], 0).unwrap(); + assert_eq!(instruction.local, Some(300)); + assert_eq!(instruction.int, Some(-2)); + assert_eq!(instruction.len, 6); + assert!(decode_one(&[0xc4, 0x84, 0x00, 1], 0).is_none()); +} diff --git a/crates/java-class/src/test_support.rs b/crates/java-class/src/test_support.rs new file mode 100644 index 000000000..45853e807 --- /dev/null +++ b/crates/java-class/src/test_support.rs @@ -0,0 +1,316 @@ +/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. +pub fn noise(seed: u64, len: usize) -> Vec { + let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; + (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect() +} + +/// Every way to damage a sample used by robustness tests: truncations at many lengths and +/// single-byte corruptions spread across the file. +pub fn mutations(sample: &[u8]) -> Vec> { + let mut out = Vec::new(); + let n = sample.len(); + let step = (n / 64).max(1); + let mut len = 0; + while len < n { + out.push(sample[..len].to_vec()); + len += step; + } + for (i, seed) in (0..n).step_by(step).zip(1u64..) { + let mut m = sample.to_vec(); + let noise = noise(seed, 8); + for (j, v) in noise.iter().enumerate() { + if let Some(b) = m.get_mut(i + j) { + *b = *v; + } + } + out.push(m); + let mut m = sample.to_vec(); + if let Some(b) = m.get_mut(i) { + *b = 0xff; + } + out.push(m); + } + out +} + +pub mod java { + use std::collections::HashMap; + + /// A constant-pool builder that interns entries and tracks the double slot after `Long`/`Double`. + #[derive(Default)] + struct Pool { + items: Vec>, + /// Next free index (1-based; accounts for long/double taking two slots). + count: u16, + cache: HashMap, + } + + impl Pool { + fn new() -> Self { + Pool { items: Vec::new(), count: 1, cache: HashMap::new() } + } + fn add(&mut self, bytes: Vec, slots: u16) -> u16 { + let idx = self.count; + self.items.push(bytes); + self.count += slots; + idx + } + fn utf8(&mut self, s: &str) -> u16 { + let key = format!("u:{s}"); + if let Some(&i) = self.cache.get(&key) { + return i; + } + let mut b = vec![1u8]; + b.extend_from_slice(&(s.len() as u16).to_be_bytes()); + b.extend_from_slice(s.as_bytes()); + let i = self.add(b, 1); + self.cache.insert(key, i); + i + } + fn class(&mut self, name: &str) -> u16 { + let n = self.utf8(name); + let key = format!("c:{name}"); + if let Some(&i) = self.cache.get(&key) { + return i; + } + let mut b = vec![7u8]; + b.extend_from_slice(&n.to_be_bytes()); + let i = self.add(b, 1); + self.cache.insert(key, i); + i + } + fn string(&mut self, s: &str) -> u16 { + let u = self.utf8(s); + let mut b = vec![8u8]; + b.extend_from_slice(&u.to_be_bytes()); + self.add(b, 1) + } + fn nat(&mut self, name: &str, desc: &str) -> u16 { + let n = self.utf8(name); + let d = self.utf8(desc); + let mut b = vec![12u8]; + b.extend_from_slice(&n.to_be_bytes()); + b.extend_from_slice(&d.to_be_bytes()); + self.add(b, 1) + } + fn reff(&mut self, tag: u8, owner: &str, name: &str, desc: &str) -> u16 { + let c = self.class(owner); + let nt = self.nat(name, desc); + let mut b = vec![tag]; + b.extend_from_slice(&c.to_be_bytes()); + b.extend_from_slice(&nt.to_be_bytes()); + self.add(b, 1) + } + fn long(&mut self, v: i64) -> u16 { + let mut b = vec![5u8]; + b.extend_from_slice(&v.to_be_bytes()); + self.add(b, 2) + } + /// The serialized constant pool and the count field. + fn finish(&self) -> (Vec, u16) { + (self.items.concat(), self.count) + } + } + + fn u16b(v: &mut Vec, x: u16) { + v.extend_from_slice(&x.to_be_bytes()); + } + fn u32b(v: &mut Vec, x: u32) { + v.extend_from_slice(&x.to_be_bytes()); + } + + /// Build an attribute: name_index, length, body. + fn attr(name_idx: u16, body: Vec) -> Vec { + let mut v = Vec::new(); + u16b(&mut v, name_idx); + u32b(&mut v, body.len() as u32); + v.extend_from_slice(&body); + v + } + + /// A method's `Code` attribute body (max_stack, max_locals, code, exception table, no nested attrs). + fn code_body(max_stack: u16, max_locals: u16, code: &[u8], exc: &[(u16, u16, u16, u16)]) -> Vec { + let mut v = Vec::new(); + u16b(&mut v, max_stack); + u16b(&mut v, max_locals); + u32b(&mut v, code.len() as u32); + v.extend_from_slice(code); + u16b(&mut v, exc.len() as u16); + for (s, e, h, t) in exc { + u16b(&mut v, *s); + u16b(&mut v, *e); + u16b(&mut v, *h); + u16b(&mut v, *t); + } + u16b(&mut v, 0); // nested attributes count + v + } + + /// A method_info: access, name, descriptor, and one already-built Code attribute. + fn method(p: &mut Pool, access: u16, name: &str, desc: &str, code_attribute: Vec) -> Vec { + let name_idx = p.utf8(name); + let desc_idx = p.utf8(desc); + let mut v = Vec::new(); + u16b(&mut v, access); + u16b(&mut v, name_idx); + u16b(&mut v, desc_idx); + u16b(&mut v, 1); // one attribute + v.extend_from_slice(&code_attribute); + v + } + + /// Assemble a whole class from its parts. + #[allow(clippy::too_many_arguments)] + fn assemble( + pool: &Pool, + access: u16, + this_c: u16, + super_c: u16, + interfaces: &[u16], + fields: &[Vec], + methods: &[Vec], + class_attrs: &[Vec], + ) -> Vec { + let (cp, count) = pool.finish(); + let mut v = Vec::new(); + v.extend_from_slice(&[0xca, 0xfe, 0xba, 0xbe]); + u16b(&mut v, 0); // minor + u16b(&mut v, 52); // major (Java 8) + u16b(&mut v, count); + v.extend_from_slice(&cp); + u16b(&mut v, access); + u16b(&mut v, this_c); + u16b(&mut v, super_c); + u16b(&mut v, interfaces.len() as u16); + for i in interfaces { + u16b(&mut v, *i); + } + u16b(&mut v, fields.len() as u16); + for f in fields { + v.extend_from_slice(f); + } + u16b(&mut v, methods.len() as u16); + for m in methods { + v.extend_from_slice(m); + } + u16b(&mut v, class_attrs.len() as u16); + for a in class_attrs { + v.extend_from_slice(a); + } + v + } + + pub const HELLO: &str = "Hello, Craft!"; + + /// `public class com.example.Hello implements Runnable` with a `count` field, a `BIG` long + /// constant, ``, `run()` (System.out.println("Hello, Craft!")), `pick(int)` (a tableswitch) + /// and `guarded()` (a try/catch over the println call). + pub fn hello_class() -> Vec { + let mut p = Pool::new(); + let this_c = p.class("com/example/Hello"); + let obj_c = p.class("java/lang/Object"); + let runnable_c = p.class("java/lang/Runnable"); + let code_attr = p.utf8("Code"); + + // fields: int count; static final long BIG; + let count_name = p.utf8("count"); + let i_desc = p.utf8("I"); + let big_name = p.utf8("BIG"); + let j_desc = p.utf8("J"); + let constval_attr = p.utf8("ConstantValue"); + let big_val = p.long(0x1122_3344_5566_7788); + + // refs used by code + let obj_init = p.reff(10, "java/lang/Object", "", "()V"); + let sysout = p.reff(9, "java/lang/System", "out", "Ljava/io/PrintStream;"); + let hello = p.string(HELLO); + let println = p.reff(10, "java/io/PrintStream", "println", "(Ljava/lang/String;)V"); + let rt_exc = p.class("java/lang/RuntimeException"); + + // (): aload_0; invokespecial Object.; return + let mut init = vec![0x2a, 0xb7]; + init.extend_from_slice(&obj_init.to_be_bytes()); + init.push(0xb1); + let init_m = method(&mut p, 0x0001, "", "()V", attr(code_attr, code_body(1, 1, &init, &[]))); + + // run(): getstatic System.out; ldc "Hello"; invokevirtual println; return + let mut run = vec![0xb2]; + run.extend_from_slice(&sysout.to_be_bytes()); + run.push(0x12); + run.push(hello as u8); // ldc (1-byte index; pool is small) + run.push(0xb6); + run.extend_from_slice(&println.to_be_bytes()); + run.push(0xb1); + let run_m = method(&mut p, 0x0001, "run", "()V", attr(code_attr, code_body(2, 1, &run, &[]))); + + // pick(int): iload_0; tableswitch{0->L0,1->L1,default->Ldef}; L0: bipush 10; ireturn; L1: bipush 20; ireturn; Ldef: iconst_m1; ireturn + // offsets: iload_1@0; tableswitch@1 (pad 2) ends @24; L0@24; L1@27; Ldef@30 + let mut pick = vec![0x1b, 0xaa, 0x00, 0x00]; + u32b(&mut pick, 29); // default -> 1+29 = 30 + u32b(&mut pick, 0); // low + u32b(&mut pick, 1); // high + u32b(&mut pick, 23); // case 0 -> 1+23 = 24 + u32b(&mut pick, 26); // case 1 -> 1+26 = 27 + debug_assert_eq!(pick.len(), 24); + pick.extend_from_slice(&[0x10, 10, 0xac]); // @24: bipush 10; ireturn + pick.extend_from_slice(&[0x10, 20, 0xac]); // @27: bipush 20; ireturn + pick.extend_from_slice(&[0x02, 0xac]); // @30: iconst_m1; ireturn + let pick_m = method(&mut p, 0x0001, "pick", "(I)I", attr(code_attr, code_body(1, 1, &pick, &[]))); + + // guarded(): try { System.out.println("Hello"); } catch (RuntimeException e) {} (then return) + // 0: getstatic(3) ; 3: ldc(2) ; 5: invokevirtual(3) ; 8: goto +5 ->13 ; 11: astore_1 ; 12: return ; 13: return + let mut g = vec![0xb2]; + g.extend_from_slice(&sysout.to_be_bytes()); + g.push(0x12); + g.push(hello as u8); + g.push(0xb6); + g.extend_from_slice(&println.to_be_bytes()); + g.extend_from_slice(&[0xa7, 0x00, 0x05]); // @8 goto -> 13 + g.push(0x4c); // @11 astore_1 + g.push(0xb1); // @12 return + g.push(0xb1); // @13 return + let guarded_m = method(&mut p, 0x0001, "guarded", "()V", attr(code_attr, code_body(2, 2, &g, &[(0, 8, 11, rt_exc)]))); + + // field infos + let field = |p: &mut Pool, access: u16, name_idx: u16, desc_idx: u16, attrs: &[Vec]| -> Vec { + let _ = p; + let mut v = Vec::new(); + u16b(&mut v, access); + u16b(&mut v, name_idx); + u16b(&mut v, desc_idx); + u16b(&mut v, attrs.len() as u16); + for a in attrs { + v.extend_from_slice(a); + } + v + }; + let count_f = field(&mut p, 0x0002, count_name, i_desc, &[]); // private int count + let mut cv = Vec::new(); + u16b(&mut cv, big_val); + let big_f = field(&mut p, 0x0019, big_name, j_desc, &[attr(constval_attr, cv)]); // public static final long BIG + + let source_attr = p.utf8("SourceFile"); + let source_val = p.utf8("Hello.java"); + let mut sf = Vec::new(); + u16b(&mut sf, source_val); + let source = attr(source_attr, sf); + + assemble( + &p, + 0x0021, // public super + this_c, + obj_c, + &[runnable_c], + &[count_f, big_f], + &[init_m, run_m, pick_m, guarded_m], + &[source], + ) + } +} From 65e38419d770ffdb67d6064a3baa391ad984d01b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 16:44:09 -0500 Subject: [PATCH 93/97] testkit: share the sampled-damage corpus with WASM and Java class --- Cargo.lock | 2 ++ crates/java-class/Cargo.toml | 2 ++ crates/java-class/src/test_support.rs | 42 +-------------------------- crates/wasm/Cargo.toml | 2 ++ crates/wasm/src/test_support.rs | 42 +-------------------------- 5 files changed, 8 insertions(+), 82 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 4d32c4f1c..1fb437385 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2306,6 +2306,7 @@ dependencies = [ name = "craft-java-class" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", "thiserror 2.0.21", ] @@ -3389,6 +3390,7 @@ dependencies = [ name = "craft-wasm" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", "thiserror 2.0.21", "wasmparser 0.261.0", diff --git a/crates/java-class/Cargo.toml b/crates/java-class/Cargo.toml index 6dfbd16e5..1a5144fc3 100644 --- a/crates/java-class/Cargo.toml +++ b/crates/java-class/Cargo.toml @@ -11,3 +11,5 @@ workspace=true [dependencies] serde={workspace=true} thiserror={workspace=true} +[dev-dependencies] +craft-testkit = { workspace = true } diff --git a/crates/java-class/src/test_support.rs b/crates/java-class/src/test_support.rs index 45853e807..e2e13ddbd 100644 --- a/crates/java-class/src/test_support.rs +++ b/crates/java-class/src/test_support.rs @@ -1,44 +1,4 @@ -/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. -pub fn noise(seed: u64, len: usize) -> Vec { - let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; - (0..len) - .map(|_| { - x ^= x << 13; - x ^= x >> 7; - x ^= x << 17; - x as u8 - }) - .collect() -} - -/// Every way to damage a sample used by robustness tests: truncations at many lengths and -/// single-byte corruptions spread across the file. -pub fn mutations(sample: &[u8]) -> Vec> { - let mut out = Vec::new(); - let n = sample.len(); - let step = (n / 64).max(1); - let mut len = 0; - while len < n { - out.push(sample[..len].to_vec()); - len += step; - } - for (i, seed) in (0..n).step_by(step).zip(1u64..) { - let mut m = sample.to_vec(); - let noise = noise(seed, 8); - for (j, v) in noise.iter().enumerate() { - if let Some(b) = m.get_mut(i + j) { - *b = *v; - } - } - out.push(m); - let mut m = sample.to_vec(); - if let Some(b) = m.get_mut(i) { - *b = 0xff; - } - out.push(m); - } - out -} +pub use craft_testkit::sample_damage::{mutations, noise}; pub mod java { use std::collections::HashMap; diff --git a/crates/wasm/Cargo.toml b/crates/wasm/Cargo.toml index c9a1cdcf3..ea07add48 100644 --- a/crates/wasm/Cargo.toml +++ b/crates/wasm/Cargo.toml @@ -13,3 +13,5 @@ serde = { workspace = true } thiserror = { workspace = true } wasmparser = { version = "0.261", default-features = false, features = ["std", "validate", "features", "component-model", "simd"] } wasmprinter = { version = "0.261", default-features = false, features = ["component-model"] } +[dev-dependencies] +craft-testkit = { workspace = true } diff --git a/crates/wasm/src/test_support.rs b/crates/wasm/src/test_support.rs index 58e7783a0..800f368fd 100644 --- a/crates/wasm/src/test_support.rs +++ b/crates/wasm/src/test_support.rs @@ -1,45 +1,5 @@ // Synthetic fixtures and mutations from Craft Anything testkit, same source revision. -/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. -pub fn noise(seed: u64, len: usize) -> Vec { - let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; - (0..len) - .map(|_| { - x ^= x << 13; - x ^= x >> 7; - x ^= x << 17; - x as u8 - }) - .collect() -} - -/// Every way to damage a sample used by robustness tests: truncations at many lengths and -/// single-byte corruptions spread across the file. -pub fn mutations(sample: &[u8]) -> Vec> { - let mut out = Vec::new(); - let n = sample.len(); - let step = (n / 64).max(1); - let mut len = 0; - while len < n { - out.push(sample[..len].to_vec()); - len += step; - } - for (i, seed) in (0..n).step_by(step).zip(1u64..) { - let mut m = sample.to_vec(); - let noise = noise(seed, 8); - for (j, v) in noise.iter().enumerate() { - if let Some(b) = m.get_mut(i + j) { - *b = *v; - } - } - out.push(m); - let mut m = sample.to_vec(); - if let Some(b) = m.get_mut(i) { - *b = 0xff; - } - out.push(m); - } - out -} +pub use craft_testkit::sample_damage::{mutations, noise}; pub mod formats { fn leb(mut v: u32, out: &mut Vec) { From 019d54bfffb429b3f10778a8bf7a318a9843455d Mon Sep 17 00:00:00 2001 From: aiongg Date: Tue, 17 Nov 2026 22:07:49 +0000 Subject: [PATCH 94/97] ci(jpeg): the uncached wasm check gets a 20-minute limit --- .github/workflows/jpeg.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index c49c03581..495af8b23 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -19,7 +19,8 @@ concurrency: jobs: check: - timeout-minutes: 10 + # Uncached: the wasm check builds its dependencies on every run (about 10 minutes with setup). + timeout-minutes: 20 # fmt, clippy and the tests run in the Workspace gate on every OS. name: JPEG WASM runs-on: ubuntu-latest From e5f00f5bf658ef2cce7bf96fbbd769a6fff5bc72 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 17:47:23 -0500 Subject: [PATCH 95/97] Extract bounded XFDF field-value reader (#2056) * Extract bounded XFDF field-value reader * Record retained XFDF source contributor provenance --------- Co-authored-by: Brandon Thomas --- ATTRIBUTION.md | 6 ++ Cargo.lock | 8 ++ Cargo.toml | 1 + crates/xfdf/Cargo.toml | 13 +++ crates/xfdf/README.md | 11 +++ crates/xfdf/src/lib.rs | 177 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 216 insertions(+) create mode 100644 crates/xfdf/Cargo.toml create mode 100644 crates/xfdf/README.md create mode 100644 crates/xfdf/src/lib.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index ae72ae851..232635e98 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -157,3 +157,9 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. ## HTTP Archive reader `crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned. + +## XFDF field reader + +`crates/xfdf` extracts PDFCraft field reading from #5937 refresh `cb564fd827f572818e9ddb0ea5989a432b1f39fd` (MIT OR Apache-2.0). App-side annotation and form policy remains local; source history is retained in the original repository. + +Retained XFDF source contributors (move-aware blame): Brandon Thomas, Marco Arnulfo, pkibiego and storybored379; module split by aiongg. Subsequent budget/integration work by Dylan M. Taylor. diff --git a/Cargo.lock b/Cargo.lock index cc0965d17..d7561e563 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3458,6 +3458,14 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-xfdf" +version = "0.1.0" +dependencies = [ + "craft-xml", + "thiserror 2.0.21", +] + [[package]] name = "craft-xfl" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index fd9ccf7a6..159c22ad4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,6 +15,7 @@ craft-java-class = { path = "crates/java-class" } craft-sourcemap = { path = "crates/sourcemap" } craft-pcap = { path = "crates/pcap" } craft-har = { path = "crates/har" } +craft-xfdf = { path = "crates/xfdf" } craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } craft-score = { path = "crates/score" } diff --git a/crates/xfdf/Cargo.toml b/crates/xfdf/Cargo.toml new file mode 100644 index 000000000..9b1304d89 --- /dev/null +++ b/crates/xfdf/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "craft-xfdf" +description = "Bounded XFDF field-value reader without PDF or form policy" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +craft-xml = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/xfdf/README.md b/crates/xfdf/README.md new file mode 100644 index 000000000..ce8c2802e --- /dev/null +++ b/crates/xfdf/README.md @@ -0,0 +1,11 @@ +# craft-xfdf + +Scoped XFDF field-value reader extracted from PDFCraft #5937 refresh cb564fd82. Does not read FDF/PDF, parse annotations or apply field values. PDF application, permissions, calculations and password filtering stay caller-owned. + +Preserves local-name matching, duplicate field order, dotted names, empty leaf clearing and ignored rich-text-only fields, direct split text concatenation and source UTF-8 replacement policy. XML depth1024, field depth64,2million nodes and64MiB charged expanded names/text. Names and values are charged before copying; temporary parents and emitted name copies both count. XML input/tree memory remains governed by craft-xml defaults, not this output budget alone. + +Current strict craft-xml also rejects duplicate raw/expanded attributes and more than1024 active inherited namespace declarations; older app XML accepted those. These deliberate tighter admissions must be disclosed by consumers. No complete XFDF or corpus parity claim. + +Source history remains in PDFCraft. Shared move and preallocation budget reconciliation by Dylan M. Taylor, MIT OR Apache-2.0. No assets are imported. + +Retained source contributors (move-aware blame): Brandon Thomas, Marco Arnulfo, pkibiego and storybored379; module split by aiongg. Subsequent budget/integration work by Dylan M. Taylor. diff --git a/crates/xfdf/src/lib.rs b/crates/xfdf/src/lib.rs new file mode 100644 index 000000000..002376106 --- /dev/null +++ b/crates/xfdf/src/lib.rs @@ -0,0 +1,177 @@ +//! Bounded XFDF field values; PDF annotations and form application remain caller-owned. +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +const MAX_NODES: u32 = 2_000_000; +const MAX_DEPTH: usize = 64; +const MAX_XML_DEPTH: usize = 1024; +const MAX_XFDF_TEXT: usize = 64 << 20; +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + #[error("this file isn't XFDF, FDF, XML or text form data")] + UnknownFormat, + #[error("the file can't be read: {0}")] + Malformed(String), +} +/// Read field names and values in file order. This does not apply values to a PDF. +/// UTF-8 replacement and leading BOM/space handling retain the source app policy. +pub fn read_fields(bytes: &[u8]) -> Result)>, Error> { + let text = String::from_utf8_lossy(bytes); + let text = text.trim_start_matches('\u{feff}').trim_start(); + check_form_xml_depth(text)?; + let root = parse_form_xml(text).map_err(|_| Error::UnknownFormat)?; + if root.local() != "xfdf" { + return Err(Error::UnknownFormat); + } + let mut values = Vec::new(); + if let Some(fields) = root.child(craft_xml::Local("fields")) { + walk_xfdf(fields, "", &mut values, 0, &mut 0)?; + } + Ok(values) +} +fn xml_nesting_depth(text: &str) -> usize { + fn find(hay: &[u8], from: usize, needle: &[u8]) -> Option { + (from..hay.len()).find(|&p| hay[p..].starts_with(needle)) + } + let b = text.as_bytes(); + let (mut i, mut depth, mut max) = (0usize, 0usize, 0usize); + while i < b.len() { + if b[i] != b'<' { + i += 1; + } else if b[i..].starts_with(b"").map_or(b.len(), |p| p + 3); + } else if b[i..].starts_with(b"").map_or(b.len(), |p| p + 3); + } else if b[i..].starts_with(b"").map_or(b.len(), |p| p + 2); + } else if b[i..].starts_with(b"").map_or(b.len(), |p| p + 1); + } else if b[i..].starts_with(b"").map_or(b.len(), |p| p + 1); + } else { + depth += 1; + max = max.max(depth); + // Skip the rest of the start tag, over any quoted attribute value, and remember its last + // significant byte: a tag that ends in `/` closes itself, so it is one level deep while it + // is read rather than a level left open. + i += 1; + let mut quote = 0u8; + let mut last = 0u8; + while i < b.len() { + let c = b[i]; + if quote != 0 { + if c == quote { + quote = 0; + } + } else if c == b'"' || c == b'\'' { + quote = c; + } else if c == b'>' { + i += 1; + break; + } else if !c.is_ascii_whitespace() { + last = c; + } + i += 1; + } + if last == b'/' { + depth -= 1; + } + } + } + max +} + +fn check_form_xml_depth(text: &str) -> Result<(), Error> { + let depth = xml_nesting_depth(text); + if depth > MAX_XML_DEPTH { + return Err(Error::Malformed(format!("the file nests XML elements {depth} deep, past the {MAX_XML_DEPTH} the reader accepts"))); + } + Ok(()) +} + +fn parse_form_xml(text: &str) -> Result { + let mut opts = craft_xml::Options { strict: true, doctype: craft_xml::Doctype::Reject, ..Default::default() }; + opts.limits.max_nodes = MAX_NODES as usize; + opts.limits.max_depth = MAX_XML_DEPTH.max(1024); + opts.parse(text.as_bytes()) +} + +fn el_text(el: &craft_xml::El) -> String { + el.children + .iter() + .filter_map(|n| match n { + craft_xml::Node::Text(t) => Some(t.as_str()), + _ => None, + }) + .collect() +} + +fn walk_xfdf(node: &craft_xml::El, prefix: &str, out: &mut Vec<(String, Vec)>, depth: usize, bytes: &mut usize) -> Result<(), Error> { + if depth > MAX_DEPTH { + return Err(Error::Malformed(format!("XFDF fields nest more than {MAX_DEPTH} deep"))); + } + for f in node.children(craft_xml::Local("field")) { + let Some(name) = f.attr("name") else { continue }; + // Charge temporary parent names too, before allocation/recursion can amplify them. + let full_len = if prefix.is_empty() { name.len() } else { prefix.len().saturating_add(1).saturating_add(name.len()) }; + charge_xfdf_text(bytes, full_len)?; + let full = if prefix.is_empty() { name.to_string() } else { format!("{prefix}.{name}") }; + let mut vals = Vec::new(); + for value in f.children(craft_xml::Local("value")) { + let len = value + .children + .iter() + .filter_map(|n| match n { + craft_xml::Node::Text(t) => Some(t.len()), + _ => None, + }) + .fold(0, usize::saturating_add); + charge_xfdf_text(bytes, len)?; + vals.push(el_text(value)); + } + // A leaf with no `` is an empty field (the export writes one that way), so it + // clears the field like FDF's `/V ()`; a field with kids only names their parent. A + // leaf holding only `` is not read yet, so it leaves the field alone. + let names_kids_or_rich = f.elements().any(|c| matches!(c.local(), "field" | "value-richtext")); + if !vals.is_empty() || !names_kids_or_rich { + charge_xfdf_text(bytes, full.len())?; // The emitted name is a second owned copy. + out.push((full.clone(), vals)); + } + walk_xfdf(f, &full, out, depth + 1, bytes)?; + } + Ok(()) +} + +fn charge_xfdf_text(bytes: &mut usize, amount: usize) -> Result<(), Error> { + *bytes = bytes.saturating_add(amount); + if *bytes > MAX_XFDF_TEXT { + return Err(Error::Malformed(format!("the file expands to more than {} MiB of field names and values", MAX_XFDF_TEXT >> 20))); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn field_order_empty_rich_and_split_values() { + let xml = b"abcskiplast"; + assert_eq!( + read_fields(xml).unwrap(), + vec![("parent.child".into(), vec!["ab".into(), "c".into()]), ("empty".into(), vec![]), ("parent.child".into(), vec!["last".into()])] + ); + } + #[test] + fn bounds_and_strict_xml_hardening() { + assert_eq!(read_fields(b""), Err(Error::UnknownFormat)); + assert!(read_fields(b"").is_err()); + assert!(read_fields(b"").is_err()); + let text = format!("{}{}{}", "".repeat(65), "x", "".repeat(65)); + assert!(read_fields(text.as_bytes()).is_err()); + let fields = parse_form_xml("").unwrap(); + let mut out = Vec::new(); + assert!(walk_xfdf(&fields, "", &mut out, 0, &mut (MAX_XFDF_TEXT - 5)).is_err()); + assert!(out.is_empty()); + walk_xfdf(&fields, "", &mut out, 0, &mut (MAX_XFDF_TEXT - 6)).unwrap(); + } +} From 17f1b5d20fe9a25007682e25e7a7308e0f00af85 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 19:45:22 -0500 Subject: [PATCH 96/97] Keep uncertain EVM fallback and jump payability unknown --- crates/evm/src/lib.rs | 5 ++++- crates/evm/tests/evm_selector_dedup.rs | 31 ++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/crates/evm/src/lib.rs b/crates/evm/src/lib.rs index 2b1b089d5..29d254b40 100644 --- a/crates/evm/src/lib.rs +++ b/crates/evm/src/lib.rs @@ -628,7 +628,10 @@ pub fn analyze(code: &[u8]) -> Result { let (short_calldata, receive) = short_calldata_path(body, &ins, disp_start); let mut fallback = "unknown"; + // At the selector cap the remaining dispatcher has not been scanned. + // Its next comparison is not evidence that a fallback body exists. if let Some(j) = last_jumpi + && functions.len() < MAX_FUNCTIONS && solc_like > 0 { fallback = if reverts_soon(body, &ins, j + 1, &index_of) { "absent" } else { "present" }; @@ -694,7 +697,7 @@ fn payability(code: &[u8], ins: &[Ins], start: usize, index_of: &dyn Fn(usize) - match i.op { 0x34 if rejects_value(code, ins, k, index_of) => return ("nonpayable", format!("rejects nonzero CALLVALUE at {:#x}", i.off)), 0x56 => match jump_destination(code, ins, k, index_of) { - Some(t) if hops < 2 => { + Some(t) if hops < 2 && ins.get(t).is_some_and(|target| target.op == 0x5b) => { hops += 1; k = t; continue; diff --git a/crates/evm/tests/evm_selector_dedup.rs b/crates/evm/tests/evm_selector_dedup.rs index 2761a23d3..99aac44ba 100644 --- a/crates/evm/tests/evm_selector_dedup.rs +++ b/crates/evm/tests/evm_selector_dedup.rs @@ -82,3 +82,34 @@ fn repeated_comparisons_keep_fallback_scan_after_the_last_dispatch() { assert_eq!(report.fallback, expected); } } + +#[test] +fn selector_cap_leaves_fallback_unknown() { + for ending in [&[0x5f, 0x5f, 0xfd][..], &[0x00][..]] { + let mut code = prefix(); + for selector in 0..4097 { + comparison(&mut code, selector, 4, 0); + } + code.extend_from_slice(ending); + let report = evm::analyze(&code).unwrap(); + assert_eq!(report.functions.len(), 4096); + assert_eq!(report.fallback, "unknown"); + } +} + +#[test] +fn payability_only_follows_jumps_to_jumpdest() { + for (target, expected) in [(&[0x5b, 0x00][..], "payable"), (&[0x00][..], "unknown")] { + let mut code = prefix(); + let entry = u8::try_from(code.len() + 10).unwrap(); + comparison(&mut code, 0xfeed0001, 4, entry); + code.push(0x00); + assert_eq!(code.len(), usize::from(entry)); + code.extend([0x5b, 0x60, entry + 4, 0x56]); + code.extend_from_slice(target); + let report = evm::analyze(&code).unwrap(); + assert_eq!(report.functions.len(), 1); + assert!(report.functions[0].jumpdest_valid); + assert_eq!(report.functions[0].mutability, expected); + } +} From aa423ded8095ce5a92e1590aee31a6625f54febe Mon Sep 17 00:00:00 2001 From: FredApps <153173854+FredApps@users.noreply.github.com> Date: Wed, 18 Nov 2026 03:36:07 +0100 Subject: [PATCH 97/97] docs(xfa): distinguish extracted baseline from later hardening --- ATTRIBUTION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 63061b638..eb9a55eeb 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -145,7 +145,7 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. ## XFA XML DOM -`crates/xfa/src/xml.rs` is extracted from PDFCraft at `271e479c53723b1b294c866d5cb2f27604601b29`, originally by Dylan M. Taylor (`eead4541`, `7d44e654`), MIT OR Apache-2.0. Only visibility and module boundaries change; PDF/layout/form policy remains in the app. +`crates/xfa/src/xml.rs` is extracted from PDFCraft at `271e479c53723b1b294c866d5cb2f27604601b29`, originally by Dylan M. Taylor (`eead4541`, `7d44e654`), MIT OR Apache-2.0. The initial extraction changes visibility and module boundaries; subsequent namespace-retention budget hardening intentionally tightens resource admission. PDF/layout/form policy remains in the app. ## Java class inspection