From 76ddfc37493022c9127095f8fa20a23429ba59a6 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 21:57:59 +0100 Subject: [PATCH 001/165] craft-heif: items reads the primary image's metadata; add scan and exif_tiff Port the container reader of storytold/lightcraft#1208 into `items`: - `read` follows `pitm`, `cdsc` and the `dimg` inputs to return the primary image's EXIF and XMP, then items tied to no image. A thumbnail's or depth map's metadata is no longer the photo's. - `scan` returns every EXIF and XMP item, with each item's bytes or why they can't be read, and `Scan::complete` is false when the item catalog can't be read in full. An app that must prove a file has no location refuses when unsure. - `exif_tiff` finds the TIFF stream with or without a correct offset field or an `Exif\0\0` prefix. - `iloc` is walked once; the module denies indexing and unchecked arithmetic; boxes, items and gathered bytes are bounded. The tests of #1055 and lightcraft#1208 come along, adapted to assert the returned bytes and the scan's completeness. --- crates/heif/Cargo.toml | 3 + crates/heif/src/items.rs | 1044 +++++++++++++++++----------- crates/heif/src/items/tests.rs | 1173 ++++++++++++++++++++++++++++++++ 3 files changed, 1806 insertions(+), 414 deletions(-) create mode 100644 crates/heif/src/items/tests.rs diff --git a/crates/heif/Cargo.toml b/crates/heif/Cargo.toml index a5734e611..9cd59453f 100644 --- a/crates/heif/Cargo.toml +++ b/crates/heif/Cargo.toml @@ -19,6 +19,9 @@ heic-rs = { version = "=0.1.4", default-features = false, features = ["std"], op heic-rs = { version = "=0.1.4", default-features = false, features = ["std", "parallel"], optional = true } rayon = { workspace = true, optional = true } +[dev-dependencies] +proptest = { workspace = true } + [features] default = ["decode"] # The decoder (probe, decode, decode_thumbnail, read_metadata): heic-rs for the container and HEVC. diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index 7d4ffe0dc..d00dbdf06 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -1,223 +1,652 @@ //! HEIF / HEIC / AVIF metadata from the box structure alone (feature `metadata`): the `Exif` and -//! XMP items of the ISO base media file container (box structure from ISO/IEC 14496-12, item model -//! from ISO/IEC 23008-12). It needs no HEVC decoder and no heic-rs, so a build that only catalogues +//! XMP items of the image file format built on the ISO base media file format (ISO/IEC 23008-12 +//! on ISO/IEC 14496-12). It needs no HEVC decoder and no heic-rs, so a build that only catalogues //! photos can read their capture time, camera and lens. //! -//! The `meta` box holds an item information box (`iinf`, one `infe` per item) naming each item's -//! type, and an item location box (`iloc`) saying where its bytes are: in the file, or in the -//! `idat` box next to it. The `Exif` item is a four-byte offset followed by a TIFF stream; the XMP -//! packet is a `mime` item whose content type is `application/rdf+xml`. The first such item counts -//! (the decoder's [`crate::read_metadata`] takes the primary image's instead). Moved from LightCraft's -//! `lightcraft-meta`. +//! - `ftyp` names a HEIF or AVIF brand ([`is_heif`]). +//! - The top-level `meta` box lists the items (`iinf`, one `infe` each), says where each item's +//! bytes are (`iloc`: extents in the file, construction method 0, or in the `meta` box's own +//! `idat`, method 1), which item is the photo (`pitm`) and how items relate (`iref`). +//! - EXIF is an item of type `Exif`: a 4-byte big-endian offset to the TIFF header, then the +//! payload (ISO/IEC 23008-12 annex A). iPhones write offset 6 and an `Exif\0\0` prefix; libheif +//! and avif-serialize write offset 0 and the TIFF stream ([`exif_tiff`]). +//! - XMP is an item of type `mime` with content type `application/rdf+xml`. +//! - A `cdsc` ("content describes") reference ties a metadata item to the image it describes. The +//! photo's items are those tied to the primary image or to an image it is made from (its `dimg` +//! inputs: a grid's tiles, the picture an `iden` turns, an `iovl` overlay's or a `tmap` tone +//! map's inputs), else those tied to no image (they describe the file). An item tied only to +//! other images (a thumbnail, a depth map, another photo of a collection) is not this photo's. +//! +//! [`read`] returns the photo's own EXIF and XMP, as the decoder's [`crate::read_metadata`] does. +//! [`scan`] returns every EXIF and XMP item instead, whichever image it describes, and says when +//! it can't be sure it saw them all ([`Scan::complete`], [`Unreadable`]). An app that must prove a +//! file holds no location before copying it out (export's "remove location") refuses when unsure. +//! +//! The ICC profile is left to the decoder, which reads it for rendering. Every size and offset is +//! checked against the buffer; the boxes read, the items considered and the bytes gathered are +//! bounded, and `iloc` is walked once. Moved from LightCraft's `lightcraft-meta`. +#![deny(clippy::indexing_slicing, clippy::arithmetic_side_effects, clippy::unwrap_used, clippy::expect_used, clippy::panic)] + +use std::collections::{HashMap, HashSet}; use crate::{Error, SEQUENCE}; -/// The Exif and XMP blocks found. -#[derive(Default)] -struct Embedded { - exif: Option>, - xmp: Option, -} +/// The `ftyp` brands of HEIF still images and image sequences, and of AVIF. +const IMAGE_BRANDS: [&[u8; 4]; 12] = [b"mif1", b"msf1", b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"avif", b"avis"]; +/// Brands of other formats in the same container (Canon CR3, JPEG XL), which win when listed too. +const OTHER_BRANDS: [&[u8; 4]; 2] = [b"crx ", b"jxl "]; -/// The first `Exif` item's TIFF stream (without HEIF's offset header) and the first XMP packet of a -/// HEIF file, as [`crate::read_metadata`] returns them. An error when the file is not an ISO base -/// media still image ([`is_heif`]), or has no `meta` box (an image sequence); an item that can't be -/// located is left out rather than reported. -pub fn read(bytes: &[u8]) -> Result<(Option>, Option), Error> { - if !is_heif(bytes) { - return Err(Error::Malformed("not a HEIF file".into())); - } - let mut budget = MAX_BOXES; - if !boxes(bytes, 0, bytes.len(), &mut budget).iter().any(|b| &b.kind == b"meta") { - return Err(Error::Unsupported(SEQUENCE)); - } - let e = metadata(bytes); - Ok((e.exif, e.xmp)) -} - -/// At most this many boxes are walked in one file. -pub const MAX_BOXES: usize = 4096; - -/// Brands that declare a still image in the ISO base media container. -const IMAGE_BRANDS: [&[u8]; 12] = [b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"mif1", b"msf1", b"avif", b"avis"]; - -/// Longest `ftyp` box this reads brands from. +/// How far into the `ftyp` box brands are looked for. pub const MAX_FTYP: usize = 4096; -/// Most items one file's `iinf` / `iloc` describes (an iPhone HEIC has a handful). -pub const MAX_ITEMS: usize = 1024; -/// Most extents one item's bytes are split into. -pub const MAX_EXTENTS: u16 = 1024; -/// Largest metadata item this returns; a real photo's Exif and XMP are a few hundred kilobytes. -pub const MAX_ITEM: usize = 32 << 20; +/// Boxes read in one file. An iPhone photo has about a hundred items, a large grid a few hundred. +pub const MAX_BOXES: usize = 1 << 16; +/// Metadata items [`read`] considers for the photo's own EXIF and XMP (a real file has one or two). +pub const MAX_CANDIDATES: usize = 64; +/// Metadata items [`scan`] returns; a file with more is not [`Scan::complete`]. +pub const MAX_SCANNED: usize = 1024; +/// The most bytes one metadata item may gather (EXIF and XMP are kilobytes). +pub const MAX_ITEM: usize = 16 << 20; +/// The most bytes [`scan`] gathers over all items. +pub const MAX_SCANNED_BYTES: usize = 64 << 20; -/// Does this file declare an ISO base media still image (HEIF / HEIC / AVIF)? +/// Does the `ftyp` box name a HEIF or AVIF brand (and not CR3 or JPEG XL)? pub fn is_heif(bytes: &[u8]) -> bool { if bytes.get(4..8) != Some(b"ftyp".as_slice()) { return false; } - let Some(size) = be32(bytes, 0).map(|v| v as usize) else { - return false; - }; - let end = size.min(bytes.len()).min(MAX_FTYP); - let brand = |at: usize| bytes.get(at..at.saturating_add(4)).is_some_and(|b| IMAGE_BRANDS.contains(&b)); - // the major brand, then (after the minor version) the compatible brands - brand(8) || (16..end).step_by(4).any(brand) + // major brand at 8, minor version at 12, compatible brands from 16 to the end of the box + let size = be32(bytes, 0).and_then(|s| usize::try_from(s).ok()).unwrap_or(0); + let end = size.clamp(12, MAX_FTYP).min(bytes.len()); + let compatible = (16..end).step_by(4).filter_map(|at| bytes.get(at..at.checked_add(4).filter(|&e| e <= end)?)); + let mut heif = false; + for brand in bytes.get(8..12).into_iter().chain(compatible) { + if OTHER_BRANDS.iter().any(|b| b.as_slice() == brand) { + return false; + } + heif |= IMAGE_BRANDS.iter().any(|b| b.as_slice() == brand); + } + heif } -/// The Exif and XMP blocks of a HEIF file. Anything malformed is left out rather than reported: -/// a file whose items can't be located simply has no metadata, as before this reader existed. -fn metadata(bytes: &[u8]) -> Embedded { - let mut out = Embedded::default(); - let mut budget = MAX_BOXES; - let Some(meta) = boxes(bytes, 0, bytes.len(), &mut budget).into_iter().find(|b| &b.kind == b"meta") else { - return out; +/// The photo's EXIF (its TIFF stream, see [`exif_tiff`]) and XMP packet, as +/// [`crate::read_metadata`] returns them: the primary image's items first, then those tied to no +/// image; the first that reads well wins. An error when the file is not HEIF ([`is_heif`]) or has +/// no `meta` box (an image sequence); an item that can't be read is left out rather than reported. +pub fn read(bytes: &[u8]) -> Result<(Option>, Option), Error> { + let c = Container::read(bytes, MAX_CANDIDATES).ok_or_else(not_heif)?; + if !c.has_meta { + return Err(Error::Unsupported(SEQUENCE)); + } + let ranked = |kind: Kind| { + let mut order: Vec<(u8, usize)> = + c.items.iter().enumerate().filter(|(_, it)| it.kind == kind).filter_map(|(i, it)| Some((it.rank(c.primary.is_some())?, i))).collect(); + order.sort_by_key(|&(rank, _)| rank); + order.into_iter().filter_map(|(_, i)| match c.gather(i, MAX_ITEM) { + Gathered::Bytes(b) => Some(b), + _ => None, + }) }; - // `meta` is a FullBox: a version and flags before its children - let (mut items, mut locs, mut idat) = (Vec::new(), Vec::new(), None); - for b in boxes(bytes, meta.body.saturating_add(4), meta.end, &mut budget) { - match &b.kind { - b"iinf" => items = item_infos(bytes, &b, &mut budget), - b"iloc" => locs = item_locations(bytes.get(b.body..b.end).unwrap_or_default()), - b"idat" => idat = bytes.get(b.body..b.end), - _ => {} + let exif = ranked(Kind::Exif).find_map(|item| exif_tiff(&item).map(<[u8]>::to_vec)); + let xmp = ranked(Kind::Xmp).next().map(|item| String::from_utf8_lossy(&item).trim_end_matches('\0').to_string()); + Ok((exif, xmp)) +} + +/// Every EXIF and XMP item of a HEIF file, whichever image it describes, in `iinf` order. An error +/// only when the file is not HEIF ([`is_heif`]); a file without a `meta` box has no items. +/// +/// The scan says when it may be missing something: [`Scan::complete`] is false when the item +/// catalog can't be read in full, and an item whose bytes can't be read comes back as +/// [`Unreadable`]. An item a complete `iloc` doesn't place is left out: it has no bytes. +pub fn scan(bytes: &[u8]) -> Result, Error> { + scan_within(bytes, MAX_SCANNED_BYTES) +} + +/// [`scan`], gathering at most `budget` bytes over all items. +fn scan_within(bytes: &[u8], budget: usize) -> Result, Error> { + let container = Container::read(bytes, MAX_SCANNED).ok_or_else(not_heif)?; + Ok(Scan { container, next: 0, budget }) +} + +fn not_heif() -> Error { + Error::Malformed("not a HEIF file".into()) +} + +/// The metadata items of a HEIF file, from [`scan`]: an iterator over [`Item`]s. +pub struct Scan<'a> { + container: Container<'a>, + next: usize, + /// Bytes still to gather, of [`MAX_SCANNED_BYTES`]. + budget: usize, +} + +impl Scan<'_> { + /// Whether the iterator returns every metadata item in the file: the boxes up to and through + /// the item catalog were read to their ends, there was one `meta` box with one `iinf`, every + /// catalog entry was understood, and there were at most [`MAX_SCANNED`] metadata items. A + /// complete file without a `meta` box is complete, with no items. + pub fn complete(&self) -> bool { + self.container.catalog_complete && !self.container.more + } +} + +impl Iterator for Scan<'_> { + type Item = Item; + + fn next(&mut self) -> Option { + loop { + let i = self.next; + let (id, kind) = self.container.items.get(i).map(|c| (c.id, c.kind))?; + self.next = i.saturating_add(1); + let data = match self.container.gather(i, MAX_ITEM.min(self.budget)) { + Gathered::Bytes(b) => { + self.budget = self.budget.saturating_sub(b.len()); + Ok(b) + } + Gathered::NotPlaced => continue, + Gathered::Unreadable => Err(Unreadable::Placement), + Gathered::TooLarge => Err(Unreadable::TooLarge), + }; + return Some(Item { id, kind, data }); } } - for (id, kind, content_type) in items { - let want_exif = &kind == b"Exif" && out.exif.is_none(); - let want_xmp = &kind == b"mime" && content_type == "application/rdf+xml" && out.xmp.is_none(); - if !want_exif && !want_xmp { - continue; - } - let Some(loc) = locs.iter().find(|l| l.id == id) else { continue }; - let Some(block) = item_bytes(bytes, idat, loc) else { continue }; - if want_exif { - // ISO/IEC 23008-12 A.2.1: a four-byte offset from the end of itself to the TIFF header - let skip = be32(&block, 0).and_then(|v| usize::try_from(v).ok()).and_then(|v| v.checked_add(4)); - out.exif = skip.and_then(|at| block.get(at..)).filter(|b| !b.is_empty()).map(<[u8]>::to_vec); +} + +/// One metadata item from [`scan`]. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Item { + /// Its item id. + pub id: u32, + pub kind: Kind, + /// Its bytes as stored (for EXIF, with the offset field: see [`exif_tiff`]), or why there are + /// none. + pub data: Result, Unreadable>, +} + +/// What a metadata item holds. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub enum Kind { + /// An `Exif` item. + Exif, + /// An XMP packet: a `mime` item of type `application/rdf+xml`. + Xmp, + /// An XMP packet with a content encoding (compressed). Its bytes are returned as stored; this + /// crate doesn't decode them. + EncodedXmp, +} + +/// Why a metadata item's bytes can't be read. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub enum Unreadable { + /// `iloc` is missing or damaged before the item's entry, or the entry points outside the file + /// (or `idat`), into another file, or builds the item from other items (method 2). + Placement, + /// More than [`MAX_ITEM`] bytes, or more than [`scan`] has left of [`MAX_SCANNED_BYTES`]. + TooLarge, +} + +/// The TIFF stream of an `Exif` item: past its 4-byte offset field and the bytes that offset +/// skips. An item whose offset is wrong, or that has no offset field, is read too when an +/// `Exif\0\0` prefix or the TIFF header itself shows where the stream starts. `None` when no TIFF +/// header is found. +pub fn exif_tiff(item: &[u8]) -> Option<&[u8]> { + let tiff = |b: &&[u8]| b.starts_with(b"II*\0") || b.starts_with(b"MM\0*"); + let stated = be32(item, 0).and_then(|n| usize::try_from(n).ok()?.checked_add(4)).and_then(|at| item.get(at..)); + let after_field = item.get(4..).map(strip_exif_header); + [stated, after_field, Some(strip_exif_header(item))].into_iter().flatten().find(tiff) +} + +/// `b` without a leading `Exif\0` and the byte after it (the JPEG APP1 prefix), if it has one. +fn strip_exif_header(b: &[u8]) -> &[u8] { + match b.get(..5) { + Some(b"Exif\0") => b.get(6..).unwrap_or(b), + _ => b, + } +} + +/// A metadata item and the images it describes. +#[derive(Debug)] +struct Candidate { + id: u32, + kind: Kind, + /// Tied to some image by a `cdsc` reference. + describes: bool, + /// Tied to the primary image or an image it is made from. + describes_primary: bool, +} + +impl Candidate { + /// 0 for the photo's own, 1 for one tied to no image (or any, when the file names no primary + /// image that exists); `None` for one that describes other images only. + fn rank(&self, has_primary: bool) -> Option { + if self.describes_primary { + Some(0) + } else if !self.describes || !has_primary { + Some(1) } else { - out.xmp = Some(String::from_utf8_lossy(&block).trim_end_matches('\0').to_string()); + None } } - out } -/// `iinf` → one `(item_ID, item_type, content_type)` per `infe` entry. Entries of version 0 and 1 -/// name no item type and are skipped; HEIF files use version 2 or 3. -fn item_infos(bytes: &[u8], iinf: &BoxRef, budget: &mut usize) -> Vec<(u32, [u8; 4], String)> { - // FullBox version and flags, then a 16- or 32-bit entry count before the `infe` boxes - let version = *bytes.get(iinf.body).unwrap_or(&0); - let entries_at = iinf.body.saturating_add(if version == 0 { 6 } else { 8 }); - let mut out = Vec::new(); - for b in boxes(bytes, entries_at, iinf.end, budget) { - if &b.kind != b"infe" || out.len() >= MAX_ITEMS { - continue; +/// What the `meta` box says about the metadata items, and where their bytes are. +struct Container<'a> { + file: &'a [u8], + /// A top-level `meta` box was found. + has_meta: bool, + idat: Option<&'a [u8]>, + iloc: Option>, + /// The primary image, when `pitm` names an item `iinf` lists. + primary: Option, + /// The EXIF and XMP items, in `iinf` order (the first `cap` of them). + items: Vec, + /// More metadata items than `cap`. + more: bool, + /// Discovery read the whole item catalog, including each entry's type. + catalog_complete: bool, + /// Where each of `items` is (from one walk of `iloc`). + places: Vec>, + /// A complete `iloc` walk established that any unplaced item has no entry. + iloc_complete: bool, +} + +impl<'a> Container<'a> { + /// `None` when `bytes` is not HEIF; no items when there is no `meta` box. + fn read(bytes: &'a [u8], cap: usize) -> Option> { + if !is_heif(bytes) { + return None; } - let Some(e) = bytes.get(b.body..b.end) else { continue }; - let (id, kind_at) = match *e.first().unwrap_or(&0) { - 2 => (be16(e, 4).map(u32::from), 8), - 3 => (be32(e, 4), 10), + let mut c = Container { + file: bytes, + has_meta: false, + idat: None, + iloc: None, + primary: None, + items: Vec::new(), + more: false, + catalog_complete: false, + places: Vec::new(), + iloc_complete: false, + }; + let mut budget = MAX_BOXES; + let top = boxes(bytes, 0, bytes.len(), &mut budget); + c.catalog_complete = top.last().is_some_and(|b| b.end == bytes.len()); + // A complete file without an item `meta` has no item catalog (e.g. a sequence). + let Some(meta) = top.iter().find(|b| &b.kind == b"meta") else { return Some(c) }; + c.has_meta = true; + // `meta` is a full box: version and flags, then the boxes inside it. + let first = meta.body.saturating_add(4); + let inside = boxes(bytes, first, meta.end, &mut budget); + c.catalog_complete &= version(bytes, meta) == Some(0) + && first <= meta.end + && inside.last().map_or(first, |b| b.end) == meta.end + && top.iter().filter(|b| &b.kind == b"meta").count() == 1 + && inside.iter().filter(|b| &b.kind == b"iinf").count() == 1; + let child = |kind: &[u8; 4]| inside.iter().find(|b| &b.kind == kind); + let payload = |kind: &[u8; 4]| child(kind).and_then(|b| bytes.get(b.body..b.end)); + let mut ids = Vec::new(); + if let Some(iinf) = child(b"iinf") { + let catalog = item_infos(bytes, iinf, cap, &mut budget); + ids = catalog.ids; + c.items = catalog.items; + c.more = catalog.more; + c.catalog_complete &= catalog.complete; + } + c.primary = payload(b"pitm").and_then(primary_item).filter(|p| ids.binary_search(p).is_ok()); + if let Some(iref) = child(b"iref") { + link(bytes, iref, c.primary, &mut c.items, &mut budget); + } + c.idat = payload(b"idat"); + c.iloc = payload(b"iloc").and_then(Iloc::parse); + (c.places, c.iloc_complete) = match &c.iloc { + Some(iloc) => iloc.locate(&c.items), + None => (Vec::new(), false), + }; + Some(c) + } + + /// The bytes of `items[i]`, at most `limit` of them. + fn gather(&self, i: usize, limit: usize) -> Gathered { + match (&self.iloc, self.places.get(i)) { + (Some(iloc), Some(Some(place))) => iloc.gather(self.file, self.idat, place, limit), + _ if self.iloc_complete => Gathered::NotPlaced, + _ => Gathered::Unreadable, + } + } +} + +/// An item's bytes, or why there are none. +#[derive(Debug)] +enum Gathered { + Bytes(Vec), + /// A complete `iloc` walk found no entry for the item. + NotPlaced, + /// Placement unresolved, outside the data, in another file, or built from other items (method 2). + Unreadable, + /// More than the limit. + TooLarge, +} + +/// A full box's version: the first byte of its own payload (`None` for an empty box). +fn version(bytes: &[u8], b: &BoxRef) -> Option { + bytes.get(b.body..b.end)?.first().copied() +} + +/// `pitm`: the primary item's id (16 bits in version 0, else 32). +fn primary_item(pitm: &[u8]) -> Option { + match pitm.first()? { + 0 => be16(pitm, 4).map(u32::from), + _ => be32(pitm, 4), + } +} + +/// What `iinf` lists. Best-effort discovery is kept even when the catalog cannot establish that +/// all items were read. +#[derive(Default)] +struct ItemCatalog { + /// Every item id listed, sorted. + ids: Vec, + items: Vec, + more: bool, + complete: bool, +} + +/// `iinf` → its item ids and its metadata items (at most `cap`). The catalog is complete when the +/// table version is known, its count matches its entries, the entries fill the box, and each is +/// an `infe` this reader understands. +fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> ItemCatalog { + let mut catalog = ItemCatalog::default(); + let Some(data) = bytes.get(iinf.body..iinf.end) else { return catalog }; + // Only the supported versions establish the count and where the entries start. + let (count, header) = match version(bytes, iinf) { + Some(0) => (be16(data, 4).map(u32::from), 6), + Some(1) => (be32(data, 4), 8), + _ => return catalog, + }; + let Some(count) = count else { return catalog }; + let first = iinf.body.saturating_add(header); + let entries = boxes(bytes, first, iinf.end, budget); + catalog.complete = entries.last().map_or(first, |b| b.end) == iinf.end && u32::try_from(entries.len()).ok() == Some(count); + for b in &entries { + let info = bytes.get(b.body..b.end).filter(|_| &b.kind == b"infe").and_then(item_info); + let Some((id, kind)) = info else { + catalog.complete = false; + continue; + }; + catalog.ids.push(id); + match kind { + Some(_) if catalog.items.len() >= cap => catalog.more = true, + Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false }), + None => {} + } + } + catalog.ids.sort_unstable(); + catalog.ids.dedup(); + catalog +} + +/// An `infe` entry's item id, and its kind when it is an unprotected `Exif` or XMP item (`mime`, +/// `application/rdf+xml`). `None` when the entry can't be read to its last field. +fn item_info(infe: &[u8]) -> Option<(u32, Option)> { + let version = *infe.first()?; + // version and flags, the item id (32 bits in version 3), the protection index + let (id, at) = match version { + 0..=2 => (u32::from(be16(infe, 4)?), 6usize), + 3 => (be32(infe, 4)?, 8usize), + _ => return None, + }; + if be16(infe, at)? != 0 { + return Some((id, None)); // protected (encrypted) + } + let at = at.checked_add(2)?; + // versions 0 and 1 have no item type and describe MIME items; 2 and 3 name the type + let (kind, at) = if version >= 2 { (infe.get(at..at.checked_add(4)?)?, at.checked_add(4)?) } else { (b"mime".as_slice(), at) }; + let (_name, at) = string(infe, at)?; + let kind = match kind { + b"Exif" => Some(Kind::Exif), + b"mime" => { + let (content_type, at) = string(infe, at)?; + // Content encoding may be absent, but a present string must terminate. + let encoding = if at == infe.len() { b"".as_slice() } else { string(infe, at)?.0 }; + match (content_type.trim_ascii().eq_ignore_ascii_case(b"application/rdf+xml"), encoding.trim_ascii().is_empty()) { + (true, true) => Some(Kind::Xmp), + (true, false) => Some(Kind::EncodedXmp), + (false, _) => None, + } + } + b"uri " => { + string(infe, at)?; + None + } + _ => None, + }; + Some((id, kind)) +} + +/// The NUL-terminated string at `at` and where the next field starts. +fn string(b: &[u8], at: usize) -> Option<(&[u8], usize)> { + let rest = b.get(at..)?; + let n = rest.iter().position(|&c| c == 0)?; + Some((rest.get(..n)?, at.checked_add(n)?.checked_add(1)?)) +} + +/// Mark the candidates that `cdsc` references tie to an image, and those tied to the primary image +/// or one it is made from (`dimg`, followed to any depth; each image once, so loops end). +fn link(bytes: &[u8], iref: &BoxRef, primary: Option, items: &mut [Candidate], budget: &mut usize) { + // full box; item ids are 16 bits in version 0, 32 in version 1 + let width = match version(bytes, iref) { + Some(0) => 2usize, + Some(1) => 4, + _ => return, + }; + let index: HashMap = items.iter().enumerate().rev().map(|(i, c)| (c.id, i)).collect(); + let mut inputs: HashMap> = HashMap::new(); + let mut described: Vec<(usize, Vec)> = Vec::new(); + for r in boxes(bytes, iref.body.saturating_add(4), iref.end, budget) { + let cdsc = match &r.kind { + b"cdsc" => true, + b"dimg" => false, _ => continue, }; - let (Some(id), Some(kind)) = (id, e.get(kind_at..kind_at + 4)) else { continue }; - let mut kind4 = [0u8; 4]; - kind4.copy_from_slice(kind); - // the item name, then (for a `mime` item) the content type, both NUL-terminated - let mut strings = e.get(kind_at + 4..).unwrap_or_default().split(|&c| c == 0).skip(1); - let content_type = String::from_utf8_lossy(strings.next().unwrap_or_default()).into_owned(); - out.push((id, kind4, content_type)); + let Some(body) = bytes.get(r.body..r.end) else { continue }; + let Some(from) = id_at(body, 0, width) else { continue }; + let item = index.get(&from).copied(); + if cdsc && item.is_none() { + continue; + } + let count = be16(body, width).unwrap_or(0); + let mut to = Vec::new(); + let mut at = width.saturating_add(2); + for _ in 0..count { + let Some(id) = id_at(body, at, width) else { break }; + to.push(id); + at = at.saturating_add(width); + } + match item { + Some(i) if cdsc => described.push((i, to)), + _ => inputs.entry(from).or_default().extend(to), + } + } + // the primary image and every image it is made from + let mut photo = HashSet::new(); + let mut todo: Vec = primary.into_iter().collect(); + while let Some(id) = todo.pop() { + if photo.insert(id) { + todo.extend(inputs.get(&id).into_iter().flatten().filter(|i| !photo.contains(*i))); + } + } + for (i, to) in described { + if let Some(item) = items.get_mut(i) + && !to.is_empty() + { + item.describes = true; + item.describes_primary |= to.iter().any(|t| photo.contains(t)); + } } - out } -/// Where one item's bytes are. -struct Loc { - id: u32, - /// 0 = offsets into the file, 1 = into the `idat` box, 2 = another item (not read). - construction: u8, +fn id_at(b: &[u8], at: usize, width: usize) -> Option { + if width == 2 { be16(b, at).map(u32::from) } else { be32(b, at) } +} + +/// `iloc`: its field sizes, read once. +struct Iloc<'a> { + data: &'a [u8], + version: u8, + offset_size: usize, + length_size: usize, + base_size: usize, + index_size: usize, +} + +/// Where an item is: how it is built, and its extents in `iloc`. +#[derive(Clone, Copy, Debug)] +struct Place { + method: u16, + data_reference: u16, base: u64, - /// `(offset, length)` per extent, in order. - extents: Vec<(u64, u64)>, + /// Where its first extent starts in `iloc`. + extents_at: usize, + extents: usize, } -/// `iloc` (payload after the box header) → one [`Loc`] per entry, stopping at the first -/// unreadable one. -fn item_locations(p: &[u8]) -> Vec { - let version = *p.first().unwrap_or(&0); - let (Some(sizes), Some(base_index)) = (p.get(4), p.get(5)) else { return Vec::new() }; - let (offset_size, length_size) = ((sizes >> 4) as usize, (sizes & 0xf) as usize); - let (base_size, index_size) = ((base_index >> 4) as usize, if version > 0 { (base_index & 0xf) as usize } else { 0 }); - let (count, mut at) = match version { - 0 | 1 => (be16(p, 6).map(usize::from), 8), - 2 => (be32(p, 6).and_then(|v| usize::try_from(v).ok()), 10), - _ => return Vec::new(), - }; - let mut out = Vec::new(); - for _ in 0..count.unwrap_or(0).min(MAX_ITEMS) { - let (id, after_id) = match version { - 2 => (be32(p, at), at + 4), - _ => (be16(p, at).map(u32::from), at + 2), - }; - // version 1 and 2 put the construction method in the low nibble of a reserved 16-bit field - let construction = if version == 0 { Some(0) } else { be16(p, after_id).map(|v| (v & 0xf) as u8) }; - let after_method = after_id + if version == 0 { 0 } else { 2 }; - // a data reference index of 0 means this file; an external reference has no bytes here - let external = be16(p, after_method).is_some_and(|v| v != 0); - let base = uint(p, after_method + 2, base_size); - let extent_at = after_method + 2 + base_size; - let (Some(id), Some(construction), Some(base), Some(extent_count)) = (id, construction, base, be16(p, extent_at)) else { - break; - }; - let stride = index_size + offset_size + length_size; - let mut extents = Vec::new(); - let mut e = extent_at + 2; - for _ in 0..extent_count.min(MAX_EXTENTS) { - let (Some(offset), Some(length)) = (uint(p, e + index_size, offset_size), uint(p, e + index_size + offset_size, length_size)) else { - return out; - }; - extents.push((offset, length)); - e += stride; +impl<'a> Iloc<'a> { + fn parse(data: &'a [u8]) -> Option> { + let version = *data.first()?; + if version > 2 { + return None; } - at = e; - if !external { - out.push(Loc { id, construction, base, extents }); + // version and flags, then four 4-bit field sizes: offset, length, base offset, extent index + let (sizes, more) = (*data.get(4)?, *data.get(5)?); + let (offset_size, length_size) = (usize::from(sizes >> 4), usize::from(sizes & 15)); + let base_size = usize::from(more >> 4); + let index_size = if version == 0 { 0 } else { usize::from(more & 15) }; // reserved in version 0 + if [offset_size, length_size, base_size, index_size].into_iter().any(|n| !matches!(n, 0 | 4 | 8)) { + return None; } + Some(Iloc { data, version, offset_size, length_size, base_size, index_size }) + } + + /// One walk over the entries: where each of `items` is (the first entry for an id wins). It + /// stops once all are placed, or where the entries stop making sense. The boolean is true + /// only if the walk exhausted the entries, so an absent placement is known to be absent. + fn locate(&self, items: &[Candidate]) -> (Vec>, bool) { + let mut places = vec![None; items.len()]; + if items.is_empty() { + return (places, false); + } + let wanted: HashMap = items.iter().enumerate().rev().map(|(i, c)| (c.id, i)).collect(); + let mut left = wanted.len(); + let complete = self.walk(|id, place| { + if let Some(&i) = wanted.get(&id) + && let Some(slot @ None) = places.get_mut(i) + { + *slot = Some(place); + left = left.saturating_sub(1); + } + left > 0 + }); + (places, complete.unwrap_or(false)) + } + + /// Call `f` with each entry's item id and place. `Some(true)` means every entry was read, + /// `Some(false)` means `f` stopped the walk, and `None` means an entry ran past the box. + fn walk(&self, mut f: impl FnMut(u32, Place) -> bool) -> Option { + let (version, data) = (self.version, self.data); + let id_size = if version == 2 { 4 } else { 2 }; + let (count, mut at) = if version == 2 { (be32(data, 6)?, 10usize) } else { (u32::from(be16(data, 6)?), 8usize) }; + let extent_size = self.index_size.checked_add(self.offset_size)?.checked_add(self.length_size)?; + // (every entry takes at least six bytes, so a count larger than the box ends at its end) + for _ in 0..count { + iloc_entry_visited(); + let id = uint(data, at, id_size)?; + at = at.checked_add(id_size)?; + let method = if version == 0 { + 0 + } else { + let m = be16(data, at)? & 15; + at = at.checked_add(2)?; + m + }; + let data_reference = be16(data, at)?; + let base = uint(data, at.checked_add(2)?, self.base_size)?; + at = at.checked_add(2)?.checked_add(self.base_size)?; + let extents = usize::from(be16(data, at)?); + at = at.checked_add(2)?; + let place = Place { method, data_reference, base, extents_at: at, extents }; + at = at.checked_add(extents.checked_mul(extent_size)?)?; + if at > data.len() { + return None; + } + if let Ok(id) = u32::try_from(id) + && !f(id, place) + { + return Some(false); + } + } + Some(true) + } + + /// An item's bytes, its extents in order from the file (construction method 0) or from the + /// `meta` box's `idat` (method 1), at most `limit` of them. + fn gather(&self, file: &[u8], idat: Option<&[u8]>, place: &Place, limit: usize) -> Gathered { + // data reference 0 is this file + let source = match (place.data_reference, place.method, idat) { + (0, 0, _) => file, + (0, 1, Some(idat)) => idat, + _ => return Gathered::Unreadable, + }; + let mut out = Vec::new(); + let mut at = place.extents_at; + for _ in 0..place.extents { + let Some((piece, next)) = self.extent(source, place.base, at) else { return Gathered::Unreadable }; + at = next; + if out.len().saturating_add(piece.len()) > limit { + return Gathered::TooLarge; + } + out.extend_from_slice(piece); + } + Gathered::Bytes(out) + } + + /// The extent at `at`: its bytes in `source` (a length of 0 runs to the end) and where the + /// next extent starts. + fn extent<'s>(&self, source: &'s [u8], base: u64, at: usize) -> Option<(&'s [u8], usize)> { + let at = at.checked_add(self.index_size)?; + let offset = uint(self.data, at, self.offset_size)?; + let at = at.checked_add(self.offset_size)?; + let length = uint(self.data, at, self.length_size)?; + let at = at.checked_add(self.length_size)?; + let rest = source.get(usize::try_from(base.checked_add(offset)?).ok()?..)?; + let piece = if length == 0 { rest } else { rest.get(..usize::try_from(length).ok()?)? }; + Some((piece, at)) } - out } -/// A big-endian unsigned integer of `size` bytes; `size` 0 is the value 0, and the item boxes -/// allow no other width than 4 or 8. +#[cfg(test)] +thread_local! { + /// `iloc` entries walked on this thread, for the tests that bound the work. + static ILOC_ENTRIES: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +fn iloc_entry_visited() { + #[cfg(test)] + ILOC_ENTRIES.with(|n| n.set(n.get().saturating_add(1))); +} + +/// A big-endian unsigned field of `size` bytes (0 reads as 0). fn uint(b: &[u8], at: usize, size: usize) -> Option { match size { 0 => Some(0), + 2 => be16(b, at).map(u64::from), 4 => be32(b, at).map(u64::from), 8 => be64(b, at), _ => None, } } -/// An item's bytes, its extents concatenated. `None` when they don't fit the file (or the `idat` -/// box), when the item is built by referencing another one, or when it is implausibly large. -fn item_bytes(bytes: &[u8], idat: Option<&[u8]>, loc: &Loc) -> Option> { - let src = match loc.construction { - 0 => bytes, - 1 => idat?, - _ => return None, - }; - let mut out = Vec::new(); - for &(offset, length) in &loc.extents { - let at = loc.base.checked_add(offset)?; - let (start, end) = (usize::try_from(at).ok()?, usize::try_from(at.checked_add(length)?).ok()?); - let extent = src.get(start..end)?; - if out.len().checked_add(extent.len())? > MAX_ITEM { - return None; - } - out.extend_from_slice(extent); - } - (!out.is_empty()).then_some(out) -} - -/// A box: its type and where its payload ends. +/// A box: its type, where its payload starts and where it ends. struct BoxRef { kind: [u8; 4], /// Start of the payload (after the header and, for `uuid`, the 16-byte uuid). @@ -225,33 +654,33 @@ struct BoxRef { end: usize, } -/// The boxes directly inside `[from, to)`; stops at the first malformed header. +/// The boxes directly inside `[from, to)`, at most `budget` of them (shared over the calls of one +/// read); stops at the first malformed header. fn boxes(bytes: &[u8], from: usize, to: usize, budget: &mut usize) -> Vec { let mut out = Vec::new(); - let mut at = from; let to = to.min(bytes.len()); - while at.saturating_add(8) <= to && *budget > 0 { - *budget -= 1; - let (Some(size), Some(kind)) = (be32(bytes, at), bytes.get(at + 4..at + 8)) else { break }; - let mut kind4 = [0u8; 4]; - kind4.copy_from_slice(kind); - let (len, mut hdr) = match size { - 0 => (to - at, 8), - 1 => match be64(bytes, at + 8).and_then(|v| usize::try_from(v).ok()) { - Some(l) => (l, 16), + let mut at = from; + while *budget > 0 { + let Some(header_end) = at.checked_add(8).filter(|&e| e <= to) else { break }; + *budget = budget.saturating_sub(1); + let (Some(size), Some(kind)) = (be32(bytes, at), bytes.get(at.saturating_add(4)..header_end)) else { break }; + let Ok(kind) = <[u8; 4]>::try_from(kind) else { break }; + let (len, header) = match size { + 0 => (to.saturating_sub(at), 8usize), + 1 => match be64(bytes, header_end).and_then(|v| usize::try_from(v).ok()) { + Some(len) => (len, 16), None => break, }, - n => (n as usize, 8), + n => match usize::try_from(n) { + Ok(len) => (len, 8), + Err(_) => break, + }, }; - let Some(end) = at.checked_add(len).filter(|&e| e <= to && len >= hdr) else { break }; - if &kind4 == b"uuid" { - // the 16-byte extended type is part of the header - if at + hdr + 16 > end { - break; - } - hdr += 16; - } - out.push(BoxRef { kind: kind4, body: at + hdr, end }); + // the 16-byte extended type of a `uuid` box is part of its header + let header = if &kind == b"uuid" { header.saturating_add(16) } else { header }; + let Some(end) = at.checked_add(len).filter(|&e| e <= to && len >= header) else { break }; + let Some(body) = at.checked_add(header) else { break }; + out.push(BoxRef { kind, body, end }); at = end; } out @@ -259,231 +688,18 @@ fn boxes(bytes: &[u8], from: usize, to: usize, budget: &mut usize) -> Vec Option { - b.get(at..at.checked_add(2)?).map(|s| u16::from_be_bytes([s[0], s[1]])) + b.get(at..at.checked_add(2)?)?.try_into().ok().map(u16::from_be_bytes) } + /// A big-endian `u32` at `at`, or `None` when the buffer is shorter than that. fn be32(b: &[u8], at: usize) -> Option { - b.get(at..at.checked_add(4)?).map(|s| u32::from_be_bytes([s[0], s[1], s[2], s[3]])) + b.get(at..at.checked_add(4)?)?.try_into().ok().map(u32::from_be_bytes) } + /// A big-endian `u64` at `at`, or `None` when the buffer is shorter than that. fn be64(b: &[u8], at: usize) -> Option { - let s = b.get(at..at.checked_add(8)?)?; - let mut a = [0u8; 8]; - a.copy_from_slice(s); - Some(u64::from_be_bytes(a)) + b.get(at..at.checked_add(8)?)?.try_into().ok().map(u64::from_be_bytes) } #[cfg(test)] -mod tests { - use super::*; - - /// One box: its own size, its four-letter kind, then its payload. - fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec { - let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec(); - v.extend_from_slice(kind); - v.extend_from_slice(payload); - v - } - - /// A FullBox: a box whose payload begins with a version byte and three flag bytes. - fn full_box(kind: &[u8; 4], version: u8, payload: &[u8]) -> Vec { - bx(kind, &[&[version, 0, 0, 0][..], payload].concat()) - } - - struct Item<'a> { - kind: &'a [u8; 4], - content_type: &'a str, - data: Vec, - } - - /// A HEIC-shaped file holding `items`: `ftyp`, a `meta` box with one `infe` per item, and the - /// item bytes in `idat` (`in_idat`, construction method 1) or in `mdat` (method 0). - fn heic(items: &[Item<'_>], iloc_version: u8, in_idat: bool) -> Vec { - let mut iinf = (items.len() as u16).to_be_bytes().to_vec(); - for (i, it) in items.iter().enumerate() { - let mut e = vec![2u8, 0, 0, 0]; // version 2, flags - e.extend_from_slice(&(i as u16 + 1).to_be_bytes()); - e.extend_from_slice(&[0, 0]); // protection index - e.extend_from_slice(it.kind); - e.extend_from_slice(b"an item\0"); - if it.kind == b"mime" { - e.extend_from_slice(it.content_type.as_bytes()); - e.push(0); - } - iinf.extend_from_slice(&bx(b"infe", &e)); - } - let iinf = full_box(b"iinf", 0, &iinf); - let payload: Vec = items.iter().flat_map(|i| i.data.iter().copied()).collect(); - let idat = if in_idat { bx(b"idat", &payload) } else { Vec::new() }; - let iloc = |base: u32| { - // four-byte offsets and lengths, no base offset and no extent index - let mut l = vec![0x44, 0x00]; - match iloc_version { - 2 => l.extend_from_slice(&(items.len() as u32).to_be_bytes()), - _ => l.extend_from_slice(&(items.len() as u16).to_be_bytes()), - } - let mut at = base; - for (i, it) in items.iter().enumerate() { - match iloc_version { - 2 => l.extend_from_slice(&(i as u32 + 1).to_be_bytes()), - _ => l.extend_from_slice(&(i as u16 + 1).to_be_bytes()), - } - if iloc_version > 0 { - l.extend_from_slice(&[0, u8::from(in_idat)]); // construction method - } - l.extend_from_slice(&[0, 0]); // data reference index: this file - l.extend_from_slice(&[0, 1]); // one extent - l.extend_from_slice(&at.to_be_bytes()); - l.extend_from_slice(&(it.data.len() as u32).to_be_bytes()); - at += it.data.len() as u32; - } - full_box(b"iloc", iloc_version, &l) - }; - let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); - let meta = |base| full_box(b"meta", 0, &[iloc(base), iinf.clone(), idat.clone()].concat()); - if in_idat { - return [ftyp, meta(0)].concat(); - } - let base = (ftyp.len() + meta(0).len() + 8) as u32; - [ftyp, meta(base), bx(b"mdat", &payload)].concat() - } - - const TIFF: &[u8] = b"MM\0\x2a\0\0\0\x08\0\0\0\0\0\0"; - - /// An `Exif` item's payload: the offset from the end of this field to the TIFF header, then - /// `skip` bytes of padding, then the TIFF stream. - fn exif_item(tiff: &[u8], skip: usize) -> Vec { - [&(skip as u32).to_be_bytes()[..], &vec![0u8; skip], tiff].concat() - } - - fn exif_only(tiff: &[u8]) -> Vec> { - vec![Item { kind: b"Exif", content_type: "", data: exif_item(tiff, 0) }] - } - - /// Every item location box the format allows: counts and ids are 16-bit before version 2 and - /// 32-bit in it, and the bytes live in `mdat` or in `idat` next to the location box itself. - #[test] - fn items_are_located_in_every_iloc_version() { - for (version, in_idat) in [(0, false), (1, false), (1, true), (2, false), (2, true)] { - let file = heic(&exif_only(TIFF), version, in_idat); - assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None), "iloc v{version}, idat {in_idat}"); - } - } - - /// The XMP packet is the `mime` item that declares `application/rdf+xml`, not any other one. - #[test] - fn the_xmp_packet_is_the_rdf_mime_item() { - let items = vec![ - Item { kind: b"mime", content_type: "text/plain", data: b"not the packet".to_vec() }, - Item { kind: b"mime", content_type: "application/rdf+xml", data: b"\0".to_vec() }, - Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }, - ]; - assert_eq!(read(&heic(&items, 1, false)).unwrap(), (Some(TIFF.to_vec()), Some("".into()))); - } - - /// The `Exif` item's leading offset may point past padding, not only straight at the TIFF header. - #[test] - fn the_exif_items_tiff_header_offset_is_honoured() { - let items = vec![Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 6) }]; - assert_eq!(read(&heic(&items, 1, false)).unwrap().0.as_deref(), Some(TIFF)); - } - - /// Which `ftyp` brands count as a still image in this container, major or compatible. - #[test] - fn brands() { - for brand in ["heic", "heix", "mif1", "avif", "hevc", "msf1"] { - let file = bx(b"ftyp", format!("{brand}\0\0\0\0mif1").as_bytes()); - assert!(is_heif(&file), "{brand}"); - } - assert!(is_heif(&bx(b"ftyp", b"mp41\0\0\0\0isomheic"))); - assert!(!is_heif(&bx(b"ftyp", b"crx \0\0\0\0crx isom"))); - assert!(!is_heif(&bx(b"ftyp", b"jxl \0\0\0\0jxl "))); - assert!(!is_heif(b"\xff\xd8\xff\xe1 a jpeg")); - assert!(!is_heif(b"")); - // a compatible brand past MAX_FTYP bytes is not read - let mut long = b"mp41\0\0\0\0".to_vec(); - long.resize(MAX_FTYP, b'x'); - long.extend_from_slice(b"heic"); - assert!(!is_heif(&bx(b"ftyp", &long))); - } - - /// Not a HEIF file, an image sequence (no `meta`), garbage: errors as the decoder reports them. - #[test] - fn what_is_not_a_still_image_is_an_error() { - assert!(matches!(read(b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"), Err(Error::Unsupported(m)) if m.contains("sequence"))); - for bytes in [&b""[..], b"\0\0\0\x18ftypheic\0\0\0\0mif1heic", &[0xFF; 64]] { - assert!(read(bytes).is_err()); - } - } - - /// A truncated or scrambled file never panics, and lies about sizes find nothing. - #[test] - fn broken_files_never_panic() { - let good = heic( - &[ - Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }, - Item { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, - ], - 1, - false, - ); - for cut in 0..good.len() { - let _ = read(&good[..cut]); - } - for at in 0..good.len() { - let mut bad = good.clone(); - bad[at] ^= 0xff; - let _ = read(&bad); - } - let mut lying = good.clone(); - if let Some(at) = lying.windows(4).position(|w| w == b"iloc") { - lying.splice(at + 8..at + 12, u32::MAX.to_be_bytes()); - } - assert_eq!(read(&lying).unwrap().0, None); - } - - /// Past MAX_ITEMS `infe` entries the rest are not read; an item larger than MAX_ITEM is left out. - #[test] - fn item_limits() { - let mut items: Vec> = (0..MAX_ITEMS).map(|_| Item { kind: b"mime", content_type: "text/plain", data: vec![b'x'] }).collect(); - items.push(Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }); - assert_eq!(read(&heic(&items, 2, false)).unwrap().0, None, "the Exif item is entry {}", MAX_ITEMS + 1); - items.remove(0); - assert_eq!(read(&heic(&items, 2, false)).unwrap().0.as_deref(), Some(TIFF)); - let big = vec![Item { kind: b"Exif", content_type: "", data: exif_item(&vec![0; MAX_ITEM], 0) }]; - assert_eq!(read(&heic(&big, 1, true)).unwrap().0, None); - } - - /// The box walk stops after MAX_BOXES boxes: a `meta` box after that many is not found. - #[test] - fn box_limit() { - let mut file = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); - for _ in 0..MAX_BOXES { - file.extend(bx(b"free", &[])); - } - file.extend(heic(&exif_only(TIFF), 1, true).split_off(bx(b"ftyp", b"heic\0\0\0\0mif1heic").len())); - assert!(matches!(read(&file), Err(Error::Unsupported(_)))); - } - - /// The container writer of this crate's tests: the reader agrees with the layout an encoder writes. - #[test] - fn a_synthetic_heif_file_carries_its_exif() { - let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); - spec.exif = Some(TIFF.to_vec()); - assert_eq!(read(&crate::testdata::build(&spec)).unwrap(), (Some(TIFF.to_vec()), None)); - assert_eq!(read(&crate::testdata::build(&crate::testdata::Spec::new(16, 16, &|_, _| [0; 3]))).unwrap(), (None, None)); - } - - /// With the decoder built too, both readers give the same answer on files with one Exif item. - #[cfg(feature = "decode")] - #[test] - fn agrees_with_the_decoders_read_metadata() { - let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); - spec.exif = Some(TIFF.to_vec()); - for file in [crate::testdata::build(&spec), crate::testdata::build(&crate::testdata::Spec::new(8, 8, &|_, _| [0; 3]))] { - assert_eq!(read(&file), crate::read_metadata(&file)); - } - let sequence = b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"; - assert_eq!(read(sequence), crate::read_metadata(sequence)); - } -} +mod tests; diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs new file mode 100644 index 000000000..49cc9d789 --- /dev/null +++ b/crates/heif/src/items/tests.rs @@ -0,0 +1,1173 @@ +#![allow(clippy::arithmetic_side_effects)] + +use super::*; + +/// One box: its own size, its four-letter kind, then its payload. +fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec { + let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec(); + v.extend_from_slice(kind); + v.extend_from_slice(payload); + v +} + +/// A FullBox: a box whose payload begins with a version byte and three flag bytes. +fn full_box(kind: &[u8; 4], version: u8, payload: &[u8]) -> Vec { + bx(kind, &[&[version, 0, 0, 0][..], payload].concat()) +} + +/// A big-endian field of `size` bytes. +fn put(v: &mut Vec, x: u64, size: u8) { + match size { + 0 => assert_eq!(x, 0, "a value needs a field"), + 2 => v.extend_from_slice(&(x as u16).to_be_bytes()), + 4 => v.extend_from_slice(&(x as u32).to_be_bytes()), + 8 => v.extend_from_slice(&x.to_be_bytes()), + _ => panic!("no {size}-byte fields"), + } +} + +const TIFF: &[u8] = b"MM\0\x2a\0\0\0\x08\0\0\0\0\0\0"; + +/// The 100-byte EXIF of LightCraft's issue sweep `synthetic-metadata.heic`: Make "Synthetic", +/// Model "Issue sweep camera", DateTime 2026:10:12 12:34:56, big-endian. +const SWEEP_TIFF: [u8; 100] = [ + 0x4d, 0x4d, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x08, 0x00, 0x03, 0x01, 0x0f, 0x00, 0x02, 0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, // + 0x00, 0x32, 0x01, 0x10, 0x00, 0x02, 0x00, 0x00, 0x00, 0x13, 0x00, 0x00, 0x00, 0x3c, 0x01, 0x32, 0x00, 0x02, 0x00, 0x00, // + 0x00, 0x14, 0x00, 0x00, 0x00, 0x50, 0x00, 0x00, 0x00, 0x00, 0x53, 0x79, 0x6e, 0x74, 0x68, 0x65, 0x74, 0x69, 0x63, 0x00, // + 0x49, 0x73, 0x73, 0x75, 0x65, 0x20, 0x73, 0x77, 0x65, 0x65, 0x70, 0x20, 0x63, 0x61, 0x6d, 0x65, 0x72, 0x61, 0x00, 0x00, // + 0x32, 0x30, 0x32, 0x36, 0x3a, 0x31, 0x30, 0x3a, 0x31, 0x32, 0x20, 0x31, 0x32, 0x3a, 0x33, 0x34, 0x3a, 0x35, 0x36, 0x00, +]; + +/// A TIFF stream as far as this reader looks: a big-endian TIFF header, then `marker`. +fn tiff_with(marker: &str) -> Vec { + [b"MM\0*\0\0\0\x08".as_slice(), marker.as_bytes()].concat() +} + +/// An XMP packet holding `title`. +fn xmp_with(title: &str) -> String { + format!("{title}") +} + +/// An EXIF item as HEIF stores it: the 4-byte offset, `skip` (which the offset jumps), the TIFF. +fn exif_item(skip: &[u8], tiff: &[u8]) -> Vec { + [&(skip.len() as u32).to_be_bytes()[..], skip, tiff].concat() +} + +/// The photo's EXIF, as [`read`] gives it. +fn exif(f: &[u8]) -> Option> { + read(f).ok()?.0 +} + +/// The photo's XMP packet, as [`read`] gives it. +fn xmp(f: &[u8]) -> Option { + read(f).ok()?.1 +} + +/// Every metadata item [`scan`] finds, when it is sure it saw them all: `None` when the catalog +/// is incomplete or an item can't be read. +fn sure(f: &[u8]) -> Option)>> { + let s = scan(f).ok()?; + if !s.complete() { + return None; + } + s.map(|it| it.data.ok().map(|d| (it.id, it.kind, d))).collect() +} + +// -- The single-`meta` builder of the first version of this reader -------------------------------- + +struct Entry<'a> { + kind: &'a [u8; 4], + content_type: &'a str, + data: Vec, +} + +/// A HEIC-shaped file holding `items`: `ftyp`, a `meta` box with one `infe` per item, and the +/// item bytes in `idat` (`in_idat`, construction method 1) or in `mdat` (method 0). No `pitm` and +/// no `iref`: every item describes the file. +fn heic(items: &[Entry<'_>], iloc_version: u8, in_idat: bool) -> Vec { + let mut iinf = (items.len() as u16).to_be_bytes().to_vec(); + for (i, it) in items.iter().enumerate() { + let mut e = vec![2u8, 0, 0, 0]; // version 2, flags + e.extend_from_slice(&(i as u16 + 1).to_be_bytes()); + e.extend_from_slice(&[0, 0]); // protection index + e.extend_from_slice(it.kind); + e.extend_from_slice(b"an item\0"); + if it.kind == b"mime" { + e.extend_from_slice(it.content_type.as_bytes()); + e.push(0); + } + iinf.extend_from_slice(&bx(b"infe", &e)); + } + let iinf = full_box(b"iinf", 0, &iinf); + let payload: Vec = items.iter().flat_map(|i| i.data.iter().copied()).collect(); + let idat = if in_idat { bx(b"idat", &payload) } else { Vec::new() }; + let iloc = |base: u32| { + // four-byte offsets and lengths, no base offset and no extent index + let mut l = vec![0x44, 0x00]; + match iloc_version { + 2 => l.extend_from_slice(&(items.len() as u32).to_be_bytes()), + _ => l.extend_from_slice(&(items.len() as u16).to_be_bytes()), + } + let mut at = base; + for (i, it) in items.iter().enumerate() { + match iloc_version { + 2 => l.extend_from_slice(&(i as u32 + 1).to_be_bytes()), + _ => l.extend_from_slice(&(i as u16 + 1).to_be_bytes()), + } + if iloc_version > 0 { + l.extend_from_slice(&[0, u8::from(in_idat)]); // construction method + } + l.extend_from_slice(&[0, 0]); // data reference index: this file + l.extend_from_slice(&[0, 1]); // one extent + l.extend_from_slice(&at.to_be_bytes()); + l.extend_from_slice(&(it.data.len() as u32).to_be_bytes()); + at += it.data.len() as u32; + } + full_box(b"iloc", iloc_version, &l) + }; + let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + let meta = |base| full_box(b"meta", 0, &[iloc(base), iinf.clone(), idat.clone()].concat()); + if in_idat { + return [ftyp, meta(0)].concat(); + } + let base = (ftyp.len() + meta(0).len() + 8) as u32; + [ftyp, meta(base), bx(b"mdat", &payload)].concat() +} + +/// An `Exif` item's payload: the offset from the end of this field to the TIFF header, then +/// `skip` bytes of padding, then the TIFF stream. +fn exif_padded(tiff: &[u8], skip: usize) -> Vec { + [&(skip as u32).to_be_bytes()[..], &vec![0u8; skip], tiff].concat() +} + +fn exif_only(tiff: &[u8]) -> Vec> { + vec![Entry { kind: b"Exif", content_type: "", data: exif_padded(tiff, 0) }] +} + +/// Every item location box the format allows: counts and ids are 16-bit before version 2 and +/// 32-bit in it, and the bytes live in `mdat` or in `idat` next to the location box itself. +#[test] +fn items_are_located_in_every_iloc_version() { + for (version, in_idat) in [(0, false), (1, false), (1, true), (2, false), (2, true)] { + let file = heic(&exif_only(TIFF), version, in_idat); + assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None), "iloc v{version}, idat {in_idat}"); + } +} + +/// The XMP packet is the `mime` item that declares `application/rdf+xml`, not any other one. +#[test] +fn the_xmp_packet_is_the_rdf_mime_item() { + let items = vec![ + Entry { kind: b"mime", content_type: "text/plain", data: b"not the packet".to_vec() }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"\0".to_vec() }, + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + ]; + assert_eq!(read(&heic(&items, 1, false)).unwrap(), (Some(TIFF.to_vec()), Some("".into()))); +} + +/// The `Exif` item's leading offset may point past padding, not only straight at the TIFF header. +#[test] +fn the_exif_items_tiff_header_offset_is_honoured() { + let items = vec![Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 6) }]; + assert_eq!(read(&heic(&items, 1, false)).unwrap().0.as_deref(), Some(TIFF)); +} + +/// Which `ftyp` brands count as a still image in this container, major or compatible. +#[test] +fn brands() { + for brand in ["heic", "heix", "mif1", "avif", "hevc", "msf1"] { + let file = bx(b"ftyp", format!("{brand}\0\0\0\0mif1").as_bytes()); + assert!(is_heif(&file), "{brand}"); + } + assert!(is_heif(&bx(b"ftyp", b"mp41\0\0\0\0isomheic"))); + assert!(!is_heif(&bx(b"ftyp", b"crx \0\0\0\0crx isom"))); + assert!(!is_heif(&bx(b"ftyp", b"jxl \0\0\0\0jxl "))); + assert!(!is_heif(b"\xff\xd8\xff\xe1 a jpeg")); + assert!(!is_heif(b"")); + // a compatible brand past MAX_FTYP bytes is not read + let mut long = b"mp41\0\0\0\0".to_vec(); + long.resize(MAX_FTYP, b'x'); + long.extend_from_slice(b"heic"); + assert!(!is_heif(&bx(b"ftyp", &long))); +} + +/// Not a HEIF file, an image sequence (no `meta`), garbage: errors as the decoder reports them. +#[test] +fn what_is_not_a_still_image_is_an_error() { + assert!(matches!(read(b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"), Err(Error::Unsupported(m)) if m.contains("sequence"))); + for bytes in [&b""[..], b"\0\0\0\x18ftypheic\0\0\0\0mif1heic", &[0xFF; 64]] { + assert!(read(bytes).is_err()); + } + assert!(scan(&[0xFF; 64]).is_err(), "only a file that isn't HEIF is an error to scan"); +} + +/// A truncated or scrambled file never panics, and lies about sizes find nothing. +#[test] +fn broken_files_never_panic() { + let good = heic( + &[ + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, + ], + 1, + false, + ); + for cut in 0..good.len() { + let _ = read(&good[..cut]); + let _ = scan(&good[..cut]).map(Iterator::count); + } + for at in 0..good.len() { + let mut bad = good.clone(); + bad[at] ^= 0xff; + let _ = read(&bad); + let _ = scan(&bad).map(Iterator::count); + } + let mut lying = good.clone(); + if let Some(at) = lying.windows(4).position(|w| w == b"iloc") { + lying.splice(at + 8..at + 12, u32::MAX.to_be_bytes()); + } + assert_eq!(read(&lying).unwrap().0, None); + assert_eq!(sure(&lying), None, "an item `iloc` can't place is unreadable, not absent"); +} + +/// [`read`] considers the first MAX_CANDIDATES metadata items; an item larger than MAX_ITEM is +/// left out by [`read`] and too large for [`scan`]. +#[test] +fn item_limits() { + let mut items: Vec> = + (0..MAX_CANDIDATES).map(|_| Entry { kind: b"Exif", content_type: "", data: exif_padded(b"not TIFF", 0) }).collect(); + items.push(Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }); + assert_eq!(read(&heic(&items, 2, false)).unwrap().0, None, "the TIFF is metadata item {}", MAX_CANDIDATES + 1); + items.remove(0); + assert_eq!(read(&heic(&items, 2, false)).unwrap().0.as_deref(), Some(TIFF)); + let big = heic(&[Entry { kind: b"Exif", content_type: "", data: exif_padded(&vec![0; MAX_ITEM], 0) }], 1, true); + assert_eq!(read(&big).unwrap().0, None); + let found: Vec = scan(&big).unwrap().collect(); + assert_eq!(found, [Item { id: 1, kind: Kind::Exif, data: Err(Unreadable::TooLarge) }]); +} + +/// The scan gathers at most its byte budget over all items; past it an item is too large. +#[test] +fn the_scan_byte_budget() { + let items = [ + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, + ]; + let f = heic(&items, 1, true); + let first = TIFF.len() + 4; + let found: Vec = scan_within(&f, first + 5).unwrap().collect(); + assert_eq!(found[0].data.as_deref().map(<[u8]>::len), Ok(first)); + assert_eq!(found[1].data, Err(Unreadable::TooLarge)); + let found: Vec = scan_within(&f, first + 12).unwrap().collect(); + assert_eq!(found[1].data.as_deref(), Ok(b"".as_slice())); +} + +/// The box walk stops after MAX_BOXES boxes: a `meta` box after that many is not found. +#[test] +fn box_limit() { + let mut file = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + for _ in 0..MAX_BOXES { + file.extend(bx(b"free", &[])); + } + file.extend(heic(&exif_only(TIFF), 1, true).split_off(bx(b"ftyp", b"heic\0\0\0\0mif1heic").len())); + assert!(matches!(read(&file), Err(Error::Unsupported(_)))); + assert!(!scan(&file).unwrap().complete()); +} + +/// The container writer of this crate's tests: the reader agrees with the layout an encoder writes. +#[test] +fn a_synthetic_heif_file_carries_its_exif() { + let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + spec.exif = Some(TIFF.to_vec()); + let file = crate::testdata::build(&spec); + assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None)); + let mut exif = 0u32.to_be_bytes().to_vec(); + exif.extend_from_slice(TIFF); + assert!(matches!(sure(&file).as_deref(), Some([(_, Kind::Exif, data)]) if *data == exif)); + assert_eq!(read(&crate::testdata::build(&crate::testdata::Spec::new(16, 16, &|_, _| [0; 3]))).unwrap(), (None, None)); +} + +/// With the decoder built too, both readers give the same answer, also on files with a +/// thumbnail and with several items. +#[cfg(feature = "decode")] +#[test] +fn agrees_with_the_decoders_read_metadata() { + let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + spec.exif = Some(TIFF.to_vec()); + let mut thumbnailed = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + thumbnailed.exif = Some(TIFF.to_vec()); + thumbnailed.thumbnail = Some(&|_, y| [y as u16 * 4, 0, 0]); + let files = [ + crate::testdata::build(&spec), + crate::testdata::build(&thumbnailed), + crate::testdata::build(&crate::testdata::Spec::new(8, 8, &|_, _| [0; 3])), + ]; + for file in files { + assert_eq!(read(&file), crate::read_metadata(&file)); + } + let sequence = b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"; + assert_eq!(read(sequence), crate::read_metadata(sequence)); +} + +// -- A builder with a primary image, references and every `iloc` layout ---------------------------- + +#[derive(Clone, Copy, PartialEq)] +enum Store { + File, + Idat, +} + +struct Part { + id: u32, + kind: &'static [u8; 4], + /// `mime` items: content type and content encoding. + mime: (&'static str, &'static str), + data: Vec, + store: Store, + /// Extents the data is split into. + extents: usize, +} + +/// A HEIF file for the tests: `ftyp`, `meta` (`hdlr`, `pitm`, `iinf`, `iref`, `iloc`, `idat`) +/// and `mdat`. +struct Heif { + ftyp: Vec, + primary: u32, + items: Vec, + /// `iref` references: type, from, to. + refs: Vec<(&'static [u8; 4], u32, Vec)>, + /// `iloc` version and its offset, length, base-offset and index field sizes. + iloc: (u8, [u8; 4]), + /// 32-bit item ids: `infe` version 3, `pitm` and `iref` version 1 (`iloc` must be version 2). + wide: bool, +} + +impl Heif { + /// A primary HEVC picture, item 1 (its bytes don't matter here). + fn new() -> Heif { + let picture = Part { id: 1, kind: b"hvc1", mime: ("", ""), data: b"coded picture".to_vec(), store: Store::File, extents: 1 }; + Heif { ftyp: b"heic\0\0\0\0mif1heic".to_vec(), primary: 1, items: vec![picture], refs: Vec::new(), iloc: (1, [4, 4, 0, 0]), wide: false } + } + + fn item(mut self, id: u32, kind: &'static [u8; 4], data: Vec, store: Store, extents: usize) -> Heif { + self.items.push(Part { id, kind, mime: ("", ""), data, store, extents }); + self + } + + fn xmp(mut self, id: u32, mime: (&'static str, &'static str), data: Vec) -> Heif { + self.items.push(Part { id, kind: b"mime", mime, data, store: Store::File, extents: 1 }); + self + } + + fn cdsc(self, from: u32, to: &[u32]) -> Heif { + self.iref(b"cdsc", from, to) + } + + fn iref(mut self, kind: &'static [u8; 4], from: u32, to: &[u32]) -> Heif { + self.refs.push((kind, from, to.to_vec())); + self + } + + fn meta(&self, mdat_at: usize) -> Vec { + let id = |v: &mut Vec, id: u32| put(v, u64::from(id), if self.wide { 4 } else { 2 }); + let mut hdlr = vec![0u8; 4]; + hdlr.extend_from_slice(b"pict"); + hdlr.extend_from_slice(&[0; 13]); + let mut pitm = Vec::new(); + id(&mut pitm, self.primary); + let mut iinf = Vec::new(); + put(&mut iinf, self.items.len() as u64, if self.wide { 4 } else { 2 }); + for it in &self.items { + let mut e = Vec::new(); + id(&mut e, it.id); + e.extend_from_slice(&[0, 0]); // not protected + e.extend_from_slice(it.kind); + e.push(0); // no name + if it.kind == b"mime" { + e.extend_from_slice(it.mime.0.as_bytes()); + e.push(0); + e.extend_from_slice(it.mime.1.as_bytes()); + e.push(0); + } + iinf.extend(full_box(b"infe", if self.wide { 3 } else { 2 }, &e)); + } + let mut iref = Vec::new(); + for (kind, from, to) in &self.refs { + let mut r = Vec::new(); + id(&mut r, *from); + put(&mut r, to.len() as u64, 2); + to.iter().for_each(|t| id(&mut r, *t)); + iref.extend(bx(kind, &r)); + } + let (version, [o, l, b, i]) = self.iloc; + let mut iloc = vec![o << 4 | l, b << 4 | i]; + put(&mut iloc, self.items.len() as u64, if version == 2 { 4 } else { 2 }); + let (mut in_file, mut in_idat) = (mdat_at as u64, 0u64); + let mut idat = Vec::new(); + for it in &self.items { + put(&mut iloc, u64::from(it.id), if version == 2 { 4 } else { 2 }); + let at = match it.store { + Store::File => &mut in_file, + Store::Idat => &mut in_idat, + }; + if version > 0 { + put(&mut iloc, if it.store == Store::Idat { 1 } else { 0 }, 2); + } + put(&mut iloc, 0, 2); // this file + let base = if b > 0 { *at } else { 0 }; + put(&mut iloc, base, b); + let chunk = it.data.len().div_ceil(it.extents.max(1)).max(1); + let pieces: Vec<&[u8]> = it.data.chunks(chunk).collect(); + put(&mut iloc, pieces.len() as u64, 2); + for piece in pieces { + if version > 0 { + put(&mut iloc, 0, i); + } + put(&mut iloc, *at - base, o); + put(&mut iloc, piece.len() as u64, l); + *at += piece.len() as u64; + } + if it.store == Store::Idat { + idat.extend_from_slice(&it.data); + } + } + let ref_version = if self.wide { 1 } else { 0 }; + let boxes = [ + full_box(b"hdlr", 0, &hdlr), + full_box(b"pitm", ref_version, &pitm), + full_box(b"iinf", ref_version, &iinf), + full_box(b"iref", ref_version, &iref), + full_box(b"iloc", version, &iloc), + bx(b"idat", &idat), + ]; + full_box(b"meta", 0, &boxes.concat()) + } + + fn build(&self) -> Vec { + let ftyp = bx(b"ftyp", &self.ftyp); + let mdat_at = ftyp.len() + self.meta(0).len() + 8; + let mdat: Vec = self.items.iter().filter(|i| i.store == Store::File).flat_map(|i| i.data.iter().copied()).collect(); + [ftyp, self.meta(mdat_at), bx(b"mdat", &mdat)].concat() + } +} + +/// One item's bytes, as [`read`] gathers them: its place from `iloc`, then its extents. +fn item_bytes(file: &[u8], iloc: &[u8], idat: Option<&[u8]>, id: u32) -> Option> { + let iloc = Iloc::parse(iloc)?; + let mut place = None; + iloc.walk(|i, p| { + if i == id { + place = Some(p); + } + place.is_none() + })?; + match iloc.gather(file, idat, &place?, MAX_ITEM) { + Gathered::Bytes(b) => Some(b), + _ => None, + } +} + +/// LightCraft's issue sweep case, laid out as its HEIF test builder writes it: `iloc` version 1, +/// the EXIF item (offset 0, then the TIFF) tied to the primary image by `cdsc`. +#[test] +fn the_issue_sweep_heic_gives_its_exif() { + let f = Heif::new().item(8, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(8, &[1]).build(); + assert_eq!(exif(&f).as_deref(), Some(SWEEP_TIFF.as_slice())); +} + +/// The 4-byte offset in front of the TIFF stream: iPhones write 6 and `Exif\0\0`, libheif and +/// avif-serialize 0. Writers that left the field out, or got it wrong, are read when the stream +/// is plain to see; anything else is no EXIF. +#[test] +fn exif_items_with_and_without_their_offset() { + let t = &SWEEP_TIFF[..]; + let tiff = Some(t); + assert_eq!(exif_tiff(&exif_item(b"Exif\0\0", t)), tiff, "iPhone"); + assert_eq!(exif_tiff(&exif_item(&[], t)), tiff, "libheif, avif-serialize"); + assert_eq!(exif_tiff(&exif_item(b"\0\0padding", t)), tiff, "any bytes the offset skips"); + assert_eq!(exif_tiff(&[b"\0\0\0\0Exif\0\0".as_slice(), t].concat()), tiff, "offset 0 though a prefix follows"); + assert_eq!(exif_tiff(&[&1000u32.to_be_bytes()[..], t].concat()), tiff, "offset past the end"); + assert_eq!(exif_tiff(&[b"Exif\0\0".as_slice(), t].concat()), tiff, "no offset field, JPEG style"); + assert_eq!(exif_tiff(t), tiff, "no offset field at all"); + assert_eq!(exif_tiff(&exif_item(&[], b"not a TIFF stream")), None); + assert_eq!(exif_tiff(&[0, 0]), None); + assert_eq!(exif_tiff(&[]), None); + assert_eq!(exif_tiff(b"Exif\0"), None, "a prefix cut short"); + // and through a whole file, the iPhone way + let f = Heif::new().item(2, b"Exif", exif_item(b"Exif\0\0", t), Store::File, 1).cdsc(2, &[1]).build(); + assert_eq!(exif(&f).as_deref(), tiff); +} + +/// Items in several extents, in the file or the `meta` box's `idat`, with every `iloc` version +/// and field size. +#[test] +fn item_extents_and_construction_methods() { + let packet = xmp_with("Harbour at dusk"); + let rdf = ("application/rdf+xml", ""); + // EXIF in `idat` (method 1), XMP in the file in three extents, a 32-bit base offset + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::Idat, 1).cdsc(2, &[1]).xmp(3, rdf, packet.clone().into_bytes()); + h.items[2].extents = 3; + h.iloc = (1, [8, 4, 4, 0]); + let f = h.cdsc(3, &[1]).build(); + assert_eq!(read(&f).unwrap(), (Some(SWEEP_TIFF.to_vec()), Some(packet.clone()))); + // version 2: 32-bit item ids, an extent index, 64-bit lengths; EXIF in two extents + let mut h = Heif::new().item(70_000, b"Exif", exif_item(b"Exif\0\0", &SWEEP_TIFF), Store::File, 2).cdsc(70_000, &[70_001]); + (h.primary, h.items[0].id, h.wide, h.iloc) = (70_001, 70_001, true, (2, [4, 8, 0, 4])); + assert_eq!(exif(&h.build()).as_deref(), Some(SWEEP_TIFF.as_slice())); + // version 0: no construction method, file offsets only + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]); + h.iloc = (0, [4, 4, 0, 0]); + assert_eq!(exif(&h.build()).as_deref(), Some(SWEEP_TIFF.as_slice())); + // an XMP item in `idat` + let mut h = Heif::new().xmp(5, rdf, packet.clone().into_bytes()); + h.items[1].store = Store::Idat; + assert_eq!(xmp(&h.build()), Some(packet)); +} + +/// `iloc` entries the builder doesn't write: a length of 0 (to the end of the data), an item +/// in another file, an item built from other items, unknown versions and field sizes. +#[test] +fn iloc_entries_that_are_read_or_refused() { + let file = b"0123456789".as_slice(); + let idat = b"abcdefgh".as_slice(); + // version 1, offset and length 4 bytes, no base or index; one item with one extent + let iloc = |version: u8, sizes: [u8; 2], method: u16, data_ref: u16, offset: u32, length: u32| { + let mut l = vec![version, 0, 0, 0]; + l.extend_from_slice(&sizes); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + if version > 0 { + l.extend_from_slice(&method.to_be_bytes()); + } + l.extend_from_slice(&data_ref.to_be_bytes()); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&offset.to_be_bytes()); + l.extend_from_slice(&length.to_be_bytes()); + l + }; + let get = |l: &[u8]| item_bytes(file, l, Some(idat), 7); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 2, 3)).as_deref(), Some(b"234".as_slice())); + assert_eq!(get(&iloc(1, [0x44, 0], 1, 0, 2, 3)).as_deref(), Some(b"cde".as_slice()), "from idat"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 6, 0)).as_deref(), Some(b"6789".as_slice()), "length 0: to the end of the file"); + assert_eq!(get(&iloc(1, [0x44, 0], 1, 0, 5, 0)).as_deref(), Some(b"fgh".as_slice()), "length 0: to the end of idat"); + assert_eq!(item_bytes(file, &iloc(1, [0x44, 0], 1, 0, 0, 1), None, 7), None, "method 1 without idat"); + assert_eq!(get(&iloc(1, [0x44, 0], 2, 0, 0, 1)), None, "method 2 (from other items)"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 1, 0, 1)), None, "in another file"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 8, 3)), None, "past the end"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 11, 0)), None, "starts past the end"); + assert_eq!(get(&iloc(1, [0x22, 0], 0, 0, 0, 1)), None, "2-byte fields are not in the standard"); + assert_eq!(get(&iloc(3, [0x44, 0], 0, 0, 0, 1)), None, "unknown version"); + assert_eq!(item_bytes(file, &iloc(1, [0x44, 0], 0, 0, 0, 1), None, 8), None, "no such item"); + // a base offset near u64::MAX plus an extent offset overflows: refused, not wrapped + let mut l = vec![1, 0, 0, 0, 0x44, 0x80]; + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); // method 0, data reference 0 + l.extend_from_slice(&u64::MAX.to_be_bytes()); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + assert_eq!(get(&l), None); +} + +/// The primary image's metadata is read; metadata tied only to another image is not. +#[test] +fn the_primary_images_metadata_is_read() { + let thumb = |h: Heif| h.item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1); + // a thumbnail's EXIF comes first in the file; the primary image's is the one read + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Primary")), Store::File, 1) + .cdsc(10, &[2]) + .cdsc(11, &[1]) + .build(); + assert_eq!(exif(&f), Some(tiff_with("Primary"))); + // EXIF tied only to another image is not this photo's + let f = thumb(Heif::new()).item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1).cdsc(10, &[2]).build(); + assert_eq!(exif(&f), None); + // tied to no image: it describes the file; tied to both: read + let f = Heif::new().item(10, b"Exif", exif_item(&[], &tiff_with("Whole file")), Store::File, 1).build(); + assert_eq!(exif(&f), Some(tiff_with("Whole file"))); + let f = thumb(Heif::new()).item(10, b"Exif", exif_item(&[], &tiff_with("Both")), Store::File, 1).cdsc(10, &[2, 1]).build(); + assert_eq!(exif(&f), Some(tiff_with("Both"))); + // a primary image's EXIF that can't be read gives way to one tied to no image + let f = Heif::new() + .item(10, b"Exif", exif_item(&[], b"damaged"), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Fallback")), Store::File, 1) + .cdsc(10, &[1]) + .build(); + assert_eq!(exif(&f), Some(tiff_with("Fallback"))); + // XMP: only uncompressed `application/rdf+xml` items, the primary image's first + let f = thumb(Heif::new()) + .xmp(20, ("image/jpeg", ""), b"\xff\xd8 not XMP".to_vec()) + .xmp(21, ("application/rdf+xml", "deflate"), b"compressed".to_vec()) + .xmp(22, ("application/rdf+xml", ""), xmp_with("Thumbnail").into_bytes()) + .xmp(23, (" Application/RDF+XML ", ""), xmp_with("Primary").into_bytes()) + .cdsc(22, &[2]) + .cdsc(23, &[1]) + .build(); + assert_eq!(xmp(&f), Some(xmp_with("Primary"))); + // 32-bit ids in `pitm`, `iinf` and `iref` + let mut h = Heif::new().item(70_000, b"Exif", exif_item(&[], &tiff_with("Wide")), Store::File, 1).cdsc(70_000, &[70_001]); + (h.primary, h.items[0].id, h.wide, h.iloc.0) = (70_001, 70_001, true, 2); + assert_eq!(exif(&h.build()), Some(tiff_with("Wide"))); +} + +/// EXIF tied to an image the primary is derived from (`dimg`: an `iden` turn, an `iovl` overlay, +/// a `tmap` tone map, a grid) is the primary image's, through any depth and despite loops. So is +/// EXIF in a file whose `pitm` names no item. A thumbnail's EXIF still isn't. +#[test] +fn metadata_of_the_images_a_primary_is_made_from_is_read() { + let base = |h: Heif| { + let mut h = h + .item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1) + .item(3, b"hvc1", b"coded picture".to_vec(), Store::File, 1) + .item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Input")), Store::File, 1) + .cdsc(10, &[2]) + .cdsc(11, &[3]); + h.items[0].kind = b"iden"; + h + }; + // the primary (1) turns item 3 + let f = base(Heif::new()).iref(b"dimg", 1, &[3]).build(); + assert_eq!(exif(&f), Some(tiff_with("Input"))); + // two levels (a tone map of a grid of 3), and a loop back to the primary + let f = + base(Heif::new()).item(4, b"grid", Vec::new(), Store::File, 1).iref(b"dimg", 1, &[4]).iref(b"dimg", 4, &[3]).iref(b"dimg", 3, &[1]).build(); + assert_eq!(exif(&f), Some(tiff_with("Input"))); + // `pitm` names an item that doesn't exist: there is no primary image, so tied items count + let mut h = Heif::new().item(11, b"Exif", exif_item(&[], &tiff_with("Orphan")), Store::File, 1).cdsc(11, &[1]); + h.primary = 99; + assert_eq!(exif(&h.build()), Some(tiff_with("Orphan"))); + // the thumbnail is not an input of the primary: without the `dimg`, nothing is the photo's + assert_eq!(exif(&base(Heif::new()).build()), None); +} + +/// HEIF, HEIC and AVIF brands are read; other files built of the same boxes are not HEIF. +#[test] +fn heif_and_avif_brands() { + let with = |ftyp: &[u8]| { + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]); + h.ftyp = ftyp.to_vec(); + h.build() + }; + for ftyp in [&b"heic\0\0\0\0mif1heic"[..], b"mif1\0\0\0\0mif1", b"heix\0\0\0\0mif1heix", b"avif\0\0\0\0avifmif1miaf", b"msf1\0\0\0\0msf1hevc"] { + assert!(is_heif(&with(ftyp)), "{}", String::from_utf8_lossy(ftyp)); + assert_eq!(exif(&with(ftyp)).as_deref(), Some(SWEEP_TIFF.as_slice()), "{}", String::from_utf8_lossy(ftyp)); + } + // MP4 and QuickTime video, JPEG XL, Canon CR3 + for ftyp in [&b"isom\0\0\x02\0isomiso2mp41"[..], b"qt \0\0\0\0qt ", b"jxl \0\0\0\0jxl ", b"crx \0\0\0\x01crx isom", b"mif1\0\0\0\0crx "] { + assert!(!is_heif(&with(ftyp)), "{}", String::from_utf8_lossy(ftyp)); + assert!(read(&with(ftyp)).is_err() && scan(&with(ftyp)).is_err()); + } + assert!(!is_heif(b"\0\0\0\x0cftyp"), "no brand"); + assert!(!is_heif(&[0xff, 0xd8, 0xff, 0xe0, 0, 0x10, b'J', b'F', b'I', b'F', 0, 1]), "JPEG"); + // a HEIF file without a `meta` box has no metadata + let bare = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + assert!(matches!(read(&bare), Err(Error::Unsupported(_)))); + assert_eq!(sure(&bare), Some(Vec::new())); +} + +/// Damaged structure: an out-of-range box, an `iinf` or `iref` that claims more than it holds, +/// extents that overlap to gather more than [`MAX_ITEM`], an item count far past the box. +#[test] +fn malformed_bounds_are_refused() { + let good = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]).build(); + // the `meta` box says it is longer than the file: nothing is read + let mut f = good.clone(); + let at = u32::from_be_bytes(f[0..4].try_into().unwrap()) as usize; // `meta` follows `ftyp` + assert_eq!(&f[at + 4..at + 8], b"meta"); + f[at..at + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert_eq!(exif(&f), None); + assert_eq!(sure(&f), None); + // an extent past the end of the file + let mut f = good.clone(); + f.truncate(f.len() - 1); + assert_eq!(exif(&f), None); + // 65,535 extents over the same 64 KiB: refused at MAX_ITEM, quickly + let file = vec![0u8; 64 << 10]; + let mut l = vec![1, 0, 0, 0, 0x44, 0]; + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); + l.extend_from_slice(&u16::MAX.to_be_bytes()); + for _ in 0..u16::MAX { + l.extend_from_slice(&0u32.to_be_bytes()); + l.extend_from_slice(&(file.len() as u32).to_be_bytes()); + } + assert_eq!(item_bytes(&file, &l, None, 7), None); + // an item count of 2^32 - 1 in a box holding one entry + let mut l = vec![2, 0, 0, 0, 0x44, 0]; + l.extend_from_slice(&u32::MAX.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0, 0, 0]); + assert_eq!(item_bytes(&file, &l, None, 7), None); + // a `cdsc` claiming 65,535 targets with none there, an `infe` cut short + let mut iref = vec![0, 0, 0, 0]; + iref.extend(bx(b"cdsc", &[0, 2, 0xff, 0xff])); + let iref = bx(b"iref", &iref); + let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false }]; + let mut budget = MAX_BOXES; + let b = boxes(&iref, 0, iref.len(), &mut budget); + link(&iref, &b[0], Some(1), &mut items, &mut budget); + assert!(!items[0].describes); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 0, b'E', b'x']), None, "cut short: the item type is unknown"); + assert_eq!(item_info(&[4, 0, 0, 0, 0, 2, 0, 0, b'E', b'x', b'i', b'f', 0]), None, "unknown infe version"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, None)), "protected"); + // a full box's version is its own first byte, never the next box's + let two = [bx(b"iref", &[]), bx(b"free", &[1, 2, 3])].concat(); + let mut budget = MAX_BOXES; + let b = boxes(&two, 0, two.len(), &mut budget); + assert_eq!((version(&two, &b[0]), version(&two, &b[1])), (None, Some(1))); +} + +/// Box headers that lie: a 64-bit size, a `uuid` box too short for its extended type, a size +/// smaller than the header, a size of 0 (to the end). +#[test] +fn box_headers() { + let mut large = 1u32.to_be_bytes().to_vec(); + large.extend_from_slice(b"free"); + large.extend_from_slice(&20u64.to_be_bytes()); + large.extend_from_slice(b"abcd"); + let mut budget = MAX_BOXES; + let b = boxes(&large, 0, large.len(), &mut budget); + assert_eq!((b.len(), b[0].body, b[0].end), (1, 16, 20)); + large[8..16].copy_from_slice(&u64::MAX.to_be_bytes()); + assert!(boxes(&large, 0, large.len(), &mut budget).is_empty(), "a 64-bit size past the end"); + let short_uuid = bx(b"uuid", &[0; 8]); + assert!(boxes(&short_uuid, 0, short_uuid.len(), &mut budget).is_empty()); + let uuid = bx(b"uuid", &[0; 20]); + assert_eq!(boxes(&uuid, 0, uuid.len(), &mut budget)[0].body, 24); + assert!(boxes(&[0, 0, 0, 4, b'f', b'r', b'e', b'e'], 0, 8, &mut budget).is_empty(), "smaller than its header"); + let to_end = [&[0u8, 0, 0, 0][..], b"mdat", b"payload"].concat(); + assert_eq!(boxes(&to_end, 0, to_end.len(), &mut budget)[0].end, to_end.len()); + assert!(boxes(&to_end, 9, 4, &mut budget).is_empty(), "an empty range"); + let mut none = 0; + assert!(boxes(&to_end, 0, to_end.len(), &mut none).is_empty(), "no budget left"); +} + +/// Every cut-short or damaged file is read without a panic. +#[test] +fn truncated_and_damaged_files_never_panic() { + let mut h = Heif::new() + .item(2, b"Exif", exif_item(b"Exif\0\0", &SWEEP_TIFF), Store::Idat, 2) + .xmp(3, ("application/rdf+xml", ""), xmp_with("t").into_bytes()) + .cdsc(2, &[1]) + .cdsc(3, &[1]); + h.items[2].extents = 3; + h.iloc = (1, [4, 8, 4, 4]); + let f = h.build(); + assert!(matches!(read(&f), Ok((Some(_), Some(_))))); + for n in 0..f.len() { + let _ = read(&f[..n]); + let _ = scan(&f[..n]).map(Iterator::count); + } + for i in 0..f.len() { + for v in [0x00, 0xff, 0x7f, 0x01] { + let mut g = f.clone(); + g[i] = v; + let _ = read(&g); + let _ = scan(&g).map(Iterator::count); + } + } +} + +/// [`scan`] returns every EXIF and XMP item, not only the photo's own first EXIF: a thumbnail's +/// EXIF and XMP, the primary image's second EXIF item, a compressed XMP item. +#[test] +fn the_scan_returns_every_metadata_item() { + let plain = tiff_with("Primary"); + let thumb = |h: Heif| h.item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1); + let ids = |f: &[u8]| sure(f).map(|items| items.into_iter().map(|(id, kind, _)| (id, kind)).collect::>()); + // the thumbnail's EXIF + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .cdsc(10, &[1]) + .cdsc(11, &[2]) + .build(); + assert_eq!(exif(&f), Some(plain.clone()), "the photo's own EXIF"); + let all = sure(&f).unwrap(); + assert_eq!(all[1], (11, Kind::Exif, exif_item(&[], &tiff_with("Thumbnail")))); + // the primary image's second EXIF item + let f = Heif::new() + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Second")), Store::File, 1) + .cdsc(10, &[1]) + .cdsc(11, &[1]) + .build(); + assert_eq!(exif(&f), Some(plain.clone())); + assert_eq!(ids(&f), Some(vec![(10, Kind::Exif), (11, Kind::Exif)])); + // a thumbnail's XMP (with place names, say) is not the photo's, but the scan has it + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .cdsc(10, &[1]) + .xmp(20, ("application/rdf+xml", ""), xmp_with("Thumbnail").into_bytes()) + .cdsc(20, &[2]) + .build(); + assert_eq!(xmp(&f), None, "the thumbnail's packet is not the primary image's"); + assert_eq!(sure(&f).unwrap()[1], (20, Kind::Xmp, xmp_with("Thumbnail").into_bytes())); + // a compressed XMP item comes back as stored, for the caller to judge + let f = Heif::new().xmp(20, ("application/rdf+xml", "deflate"), b"compressed".to_vec()).build(); + assert_eq!(sure(&f), Some(vec![(20, Kind::EncodedXmp, b"compressed".to_vec())])); + // an EXIF item cut off by the end of the file, one larger than the reader takes, more items + // than it looks at: not sure + let mut f = Heif::new().item(10, b"Exif", exif_item(&[], &plain), Store::File, 1).build(); + f.truncate(f.len() - 1); + assert_eq!(sure(&f), None, "cut off"); + let f = Heif::new().item(10, b"Exif", exif_item(&[], &vec![0; MAX_ITEM]), Store::File, 1).build(); + assert_eq!(scan(&f).unwrap().next().map(|it| it.data), Some(Err(Unreadable::TooLarge)), "too large"); + let mut h = Heif::new(); + for id in 0..(MAX_SCANNED as u32 + 1) { + h = h.item(10 + id, b"Exif", exif_item(&[], &plain), Store::File, 1); + } + let f = h.build(); + assert!(!scan(&f).unwrap().complete(), "too many items"); + assert_eq!(scan(&f).unwrap().count(), MAX_SCANNED); + assert_eq!(exif(&f), Some(plain), "read still finds the photo's EXIF"); +} + +/// Replace only the catalog; the real metadata remains in `idat` with unchanged `iloc`. +fn with_iinf(h: &Heif, iinf: Option<&[u8]>) -> Vec { + assert!(h.items.iter().filter(|it| it.kind == b"Exif" || it.kind == b"mime").all(|it| it.store == Store::Idat)); + let meta = h.meta(0); + let mut budget = MAX_BOXES; + let children: Vec = boxes(&meta, 12, meta.len(), &mut budget) + .iter() + .flat_map(|b| if &b.kind == b"iinf" { iinf.map(|data| bx(b"iinf", data)).unwrap_or_default() } else { bx(&b.kind, &meta[b.body..b.end]) }) + .collect(); + [bx(b"ftyp", &h.ftyp), full_box(b"meta", 0, &children)].concat() +} + +fn catalog(version: u8, count: u32, entries: &[u8]) -> Vec { + let mut data = vec![version, 0, 0, 0]; + put(&mut data, u64::from(count), if version == 0 { 2 } else { 4 }); + data.extend_from_slice(entries); + data +} + +fn catalog_entry(version: u8, id: u32, kind: &[u8; 4], fields: &[u8]) -> Vec { + let mut data = vec![version, 0, 0, 0]; + put(&mut data, u64::from(id), if version == 3 { 4 } else { 2 }); + data.extend_from_slice(&[0, 0]); + if version >= 2 { + data.extend_from_slice(kind); + } + data.extend_from_slice(fields); + data +} + +/// An `infe` cut anywhere, even one that keeps the id and part of the type, makes the scan unsure. +#[test] +fn item_catalog_truncated_type_is_uncertain() { + let tiff = tiff_with("Located"); + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff), Store::Idat, 1); + for version in [2, 3] { + let entry = catalog_entry(version, 2, b"Exif", b"\0"); + let intact = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry)))); + assert_eq!(exif(&intact), Some(tiff.clone()), "infe v{version}"); + assert_eq!(sure(&intact), Some(vec![(2, Kind::Exif, exif_item(&[], &tiff))]), "infe v{version}"); + for end in 0..entry.len() { + let damaged = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry[..end])))); + assert_eq!(sure(&damaged), None, "infe v{version}, cut at {end}"); + } + } +} + +/// An XMP entry cut in its fields or strings makes the scan unsure, in every `infe` and `iinf` version. +#[test] +fn item_catalog_truncated_fields_and_strings_are_uncertain() { + let packet = xmp_with("Located").into_bytes(); + let mut h = Heif::new().xmp(2, ("application/rdf+xml", ""), packet.clone()); + h.items[1].store = Store::Idat; + for version in 0..=3 { + // The optional content encoding is absent; name and content type are terminated. + let entry = catalog_entry(version, 2, b"mime", b"name\0application/rdf+xml\0"); + for table_version in [0, 1] { + let intact = with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry)))); + assert_eq!(sure(&intact), Some(vec![(2, Kind::Xmp, packet.clone())]), "infe v{version}, iinf v{table_version}"); + for end in 0..entry.len() { + let damaged = with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry[..end])))); + assert_eq!(sure(&damaged), None, "infe v{version}, iinf v{table_version}, cut at {end}"); + } + } + } +} + +/// A missing or cut catalog, unknown versions, unknown entry boxes, a count that doesn't match +/// the entries and unterminated strings all make the scan unsure. +#[test] +fn item_catalog_incomplete_walks_counts_and_versions_are_uncertain() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + let entry = catalog_entry(2, 2, b"Exif", b"\0"); + let intact = catalog(0, 1, &bx(b"infe", &entry)); + assert!(sure(&with_iinf(&h, Some(&intact))).is_some()); + let mut cases = vec![("missing catalog".to_string(), None)]; + for end in 0..intact.len() { + cases.push((format!("catalog cut at {end}"), Some(intact[..end].to_vec()))); + } + cases.push(("unsupported table version".into(), Some(catalog(2, 1, &bx(b"infe", &entry))))); + let mut unsupported = entry.clone(); + unsupported[0] = 4; + cases.push(("unsupported entry version".into(), Some(catalog(0, 1, &bx(b"infe", &unsupported))))); + cases.push(("unknown entry box".into(), Some(catalog(0, 1, &bx(b"free", &entry))))); + // A valid image entry cannot explain a declared but absent second entry. + let image = bx(b"infe", &catalog_entry(2, 1, b"hvc1", b"\0")); + for version in [0, 1] { + for count in [0, 2] { + cases.push((format!("iinf v{version}, count {count}"), Some(catalog(version, count, &image)))); + } + } + for (kind, fields) in [(b"hvc1", b"unterminated".as_slice()), (b"uri ", b"name\0unterminated"), (b"mime", b"name\0image/jpeg\0gzip")] { + cases.push((format!("unterminated {kind:?} field"), Some(catalog(0, 1, &bx(b"infe", &catalog_entry(2, 2, kind, fields)))))); + } + for (label, data) in cases { + assert_eq!(sure(&with_iinf(&h, data.as_deref())), None, "{label}"); + } +} + +/// An unreadable catalog entry doesn't stop [`read`] from returning the EXIF it could read. +#[test] +fn item_catalog_uncertainty_keeps_readable_exif() { + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Readable")), Store::Idat, 1).xmp( + 3, + ("application/rdf+xml", ""), + xmp_with("Located").into_bytes(), + ); + h.items[2].store = Store::Idat; + assert!(sure(&h.build()).is_some()); + let exif_entry = bx(b"infe", &catalog_entry(2, 2, b"Exif", b"\0")); + let broken = bx(b"infe", &catalog_entry(2, 3, b"mime", b"name\0application/rdf+")); + for entries in [[exif_entry.clone(), broken.clone()], [broken, exif_entry]] { + let f = with_iinf(&h, Some(&catalog(0, 2, &entries.concat()))); + assert_eq!(exif(&f), Some(tiff_with("Readable"))); + assert_eq!(sure(&f), None, "unreadable XMP after or before readable EXIF"); + } +} + +/// Catalogs without metadata items, and protected items, leave a complete, empty scan. +#[test] +fn item_catalog_benign_entries_and_empty_tables_are_complete() { + let h = Heif::new(); + assert_eq!(sure(&h.build()), Some(Vec::new()), "image only"); + for table_version in [0, 1] { + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 0, &[])))), Some(Vec::new()), "empty catalog"); + for version in 0..=3 { + for fields in [b"\0image/jpeg\0".as_slice(), b"name\0image/jpeg\0\0", b"name\0image/jpeg\0gzip\0"] { + let entry = catalog_entry(version, 1, b"mime", fields); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + } + } + for kind in [b"hvc1", b"av01", b"zzzz", b"uri "] { + let fields = if kind == b"uri " { b"name\0https://example.invalid/item\0".as_slice() } else { b"name\0" }; + let entry = catalog_entry(2, 1, kind, fields); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + } + } + // A protected (encrypted) item is not a metadata item this reader can read. + let mut entry = catalog_entry(2, 2, b"Exif", b"\0"); + entry[7] = 1; + let h = h.item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + // Complete top-level files without an item meta box have no item catalog to inspect. + assert_eq!(sure(&bx(b"ftyp", b"msf1\0\0\0\0msf1")), Some(Vec::new())); +} + +/// Running out of box budget, or a walk that stops before the end of its box, never makes a +/// scan complete. +#[test] +fn item_catalog_box_budget_and_enclosing_walks_cannot_clear_uncertainty() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + let f = h.build(); + let ftyp = bx(b"ftyp", &h.ftyp); + let mut top_cut = f.clone(); + top_cut[ftyp.len()..ftyp.len() + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert_eq!(sure(&top_cut), None, "meta box cut short"); + let hidden = [ftyp.clone(), bx(b"free", &[]).repeat(MAX_BOXES), h.meta(0)].concat(); + assert_eq!(sure(&hidden), None, "top-level budget hides meta"); + let hidden = [ftyp.clone(), full_box(b"meta", 0, &[bx(b"free", &[]).repeat(MAX_BOXES), h.meta(0)[12..].to_vec()].concat())].concat(); + assert_eq!(sure(&hidden), None, "meta budget hides catalog"); + let image = bx(b"infe", &catalog_entry(2, 1, b"hvc1", b"\0")); + let data = catalog(1, MAX_BOXES as u32, &image.repeat(MAX_BOXES)); + assert_eq!(sure(&with_iinf(&h, Some(&data))), None, "catalog budget"); + let hidden = [ftyp, full_box(b"meta", 0, &[vec![0; 3], h.meta(0)[12..].to_vec()].concat())].concat(); + assert_eq!(sure(&hidden), None, "incomplete meta child walk"); +} + +/// Replace `iloc` in a builder fixture. Metadata stays in `idat`, so changing the box sizes +/// cannot change its offsets. The coded picture is not used by these metadata tests. +fn with_iloc(h: &Heif, iloc: Option<&[u8]>) -> Vec { + assert!(h.items.iter().filter(|it| it.kind == b"Exif" || it.kind == b"mime").all(|it| it.store == Store::Idat)); + let meta = h.meta(0); + let mut budget = MAX_BOXES; + let children: Vec = boxes(&meta, 12, meta.len(), &mut budget) + .iter() + .flat_map(|b| if &b.kind == b"iloc" { iloc.map(|data| bx(b"iloc", data)).unwrap_or_default() } else { bx(&b.kind, &meta[b.body..b.end]) }) + .collect(); + [bx(b"ftyp", &h.ftyp), full_box(b"meta", 0, &children)].concat() +} + +/// The `iloc` bytes of a builder fixture. +fn iloc_of(f: &[u8]) -> Vec { + Container::read(f, MAX_SCANNED).unwrap().iloc.unwrap().data.to_vec() +} + +/// An `iloc` cut after a readable EXIF entry leaves the later XMP unresolved: [`read`] still +/// returns the EXIF, and the scan reports the XMP as unreadable. +#[test] +fn iloc_truncation_after_readable_exif_leaves_xmp_unreadable() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("First")), Store::Idat, 1); + assert!(sure(&h.build()).is_some(), "readable EXIF alone"); + let mut h = h.xmp(3, ("application/rdf+xml", ""), xmp_with("Located").into_bytes()); + h.items[2].store = Store::Idat; + let f = h.build(); + assert_eq!(sure(&f).map(|v| v.len()), Some(2), "the intact XMP"); + let iloc = iloc_of(&f); + let cut = with_iloc(&h, Some(&iloc[..iloc.len() - 1])); + assert_eq!(exif(&cut), Some(tiff_with("First")), "the first metadata item still reads"); + let found: Vec = scan(&cut).unwrap().collect(); + assert_eq!(found[1], Item { id: 3, kind: Kind::Xmp, data: Err(Unreadable::Placement) }, "the unresolved XMP isn't skipped"); +} + +/// A missing, cut or unsupported `iloc` leaves every metadata item unreadable. +#[test] +fn iloc_unresolved_metadata_is_unreadable() { + for kind in [b"Exif", b"mime"] { + let mut h = Heif::new().item(2, kind, b"unread metadata".to_vec(), Store::Idat, 1); + h.items[1].mime = ("application/rdf+xml", ""); + let iloc = iloc_of(&h.build()); + assert_eq!(sure(&with_iloc(&h, None)), None, "missing iloc: {kind:?}"); + // Every cut leaves the metadata entry unresolved, including cuts in its last extent. + for end in 0..iloc.len() { + assert_eq!(sure(&with_iloc(&h, Some(&iloc[..end]))), None, "{kind:?}: iloc cut at {end}"); + } + // Unsupported version or any one of the four field sizes. + for (at, value) in [(0, 3), (4, 0x24), (4, 0x42), (5, 0x20), (5, 0x02)] { + let mut bad = iloc.clone(); + bad[at] = value; + assert_eq!(sure(&with_iloc(&h, Some(&bad))), None, "{kind:?}: field {at} = {value}"); + } + } +} + +/// A partial `iloc` walk that placed one item doesn't make another, unplaced item absent. +#[test] +fn iloc_partial_walk_does_not_clear_unresolved_metadata() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1).item(3, b"Exif", b"unread metadata".to_vec(), Store::Idat, 1); + let iloc = iloc_of(&h.build()); + // Picture: 16 bytes; empty EXIF: 8 bytes; final EXIF: 16 bytes. Keep the first EXIF + // intact while cutting the second entry at every byte, including its extent fields. + for end in 32..iloc.len() { + let cut = with_iloc(&h, Some(&iloc[..end])); + let partial = Container::read(&cut, MAX_SCANNED).unwrap(); + assert!(matches!(partial.gather(0, MAX_ITEM), Gathered::Bytes(b) if b.is_empty())); + assert_eq!(sure(&cut), None, "iloc cut at {end}"); + } +} + +/// A complete `iloc` that places no entry for an item, or one with no extents, is sure: the +/// item has no bytes. +#[test] +fn iloc_complete_walk_allows_unplaced_and_empty_items() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1); + assert_eq!(sure(&h.build()), Some(vec![(2, Kind::Exif, Vec::new())]), "placed EXIF with no extents"); + // A well-formed empty table, or a complete table placing only a different item. + for version in 0..=2 { + let mut iloc = vec![version, 0, 0, 0, 0, 0]; + put(&mut iloc, 0, if version == 2 { 4 } else { 2 }); + assert_eq!(sure(&with_iloc(&h, Some(&iloc))), Some(Vec::new()), "empty iloc v{version}"); + let count_at = iloc.len() - 1; + iloc[count_at] = 1; + put(&mut iloc, 9, if version == 2 { 4 } else { 2 }); + if version > 0 { + put(&mut iloc, 0, 2); // construction method + } + iloc.extend_from_slice(&[0, 0, 0, 0]); // this file, no extents + assert_eq!(sure(&with_iloc(&h, Some(&iloc))), Some(Vec::new()), "absent item in complete iloc v{version}"); + } + // No metadata candidates: there is nothing to resolve, even without a usable iloc. + assert_eq!(sure(&Heif::new().build()), Some(Vec::new())); + for iloc in [None, Some([3, 0, 0, 0, 0, 0].as_slice())] { + ILOC_ENTRIES.with(|n| n.set(0)); + assert_eq!(sure(&with_iloc(&Heif::new(), iloc)), Some(Vec::new())); + assert_eq!(ILOC_ENTRIES.with(std::cell::Cell::get), 0); + } +} + +/// The `iloc` walk ends once every metadata item is placed, before a damaged later entry. +#[test] +fn iloc_stops_after_all_metadata_is_placed() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1).item(3, b"hvc1", vec![1], Store::File, 1); + let iloc = iloc_of(&h.build()); + // The last picture entry is truncated. The only metadata entry is already complete. + let cut = with_iloc(&h, Some(&iloc[..32])); + ILOC_ENTRIES.with(|n| n.set(0)); + assert_eq!(sure(&cut), Some(vec![(2, Kind::Exif, Vec::new())])); + assert_eq!(ILOC_ENTRIES.with(std::cell::Cell::get), 2, "stop after the picture and the EXIF entry"); +} + +/// A placed item whose extents leave its data, or pass the limit, can't be read. +#[test] +fn iloc_resolved_extents_still_obey_bounds_and_budget() { + let h = Heif::new().item(2, b"Exif", b"abcd".to_vec(), Store::Idat, 1); + let f = h.build(); + let c = Container::read(&f, MAX_SCANNED).unwrap(); + assert!(matches!(c.gather(0, 4), Gathered::Bytes(b) if b == b"abcd")); + assert!(matches!(c.gather(0, 3), Gathered::TooLarge)); + let iloc = iloc_of(&f); + for (offset, length) in [(0u32, 5u32), (5, 0), (u32::MAX, 1)] { + let mut bad = iloc.clone(); + let end = bad.len(); + bad[end - 8..end - 4].copy_from_slice(&offset.to_be_bytes()); + bad[end - 4..].copy_from_slice(&length.to_be_bytes()); + let f = with_iloc(&h, Some(&bad)); + let c = Container::read(&f, MAX_SCANNED).unwrap(); + assert!(matches!(c.gather(0, MAX_ITEM), Gathered::Unreadable)); + assert_eq!(sure(&f), None); + } +} + +/// `iloc` is walked once, however many metadata items there are to place (one walk per item +/// took over a second on a 48 MB `iloc` with 64 items). +#[test] +fn iloc_is_walked_once() { + // 64 metadata items, none placed by `iloc`, and 20,000 entries for other items + let mut iinf = vec![0u8, 0, 0, 0]; + iinf.extend_from_slice(&64u16.to_be_bytes()); + for id in 0..64u16 { + let mut e = vec![2u8, 0, 0, 0]; + e.extend_from_slice(&(1000 + id).to_be_bytes()); + e.extend_from_slice(&[0, 0]); + e.extend_from_slice(if id % 2 == 0 { b"Exif\0" } else { b"mime\0application/rdf+xml\0" }); + iinf.extend(bx(b"infe", &e)); + } + let entries = 20_000usize; + let mut iloc = vec![2u8, 0, 0, 0, 0, 0]; + iloc.extend_from_slice(&(entries as u32).to_be_bytes()); + for _ in 0..entries { + iloc.extend_from_slice(&[0, 0, 0, 1, 0, 0, 0, 0, 0, 0]); // item 1, method 0, this file, no extents + } + let meta = full_box(b"meta", 0, &[bx(b"iinf", &iinf), bx(b"iloc", &iloc)].concat()); + let f = [bx(b"ftyp", b"heic\0\0\0\0mif1heic"), meta].concat(); + let walked = |run: &dyn Fn(&[u8])| { + ILOC_ENTRIES.with(|n| n.set(0)); + run(&f); + ILOC_ENTRIES.with(std::cell::Cell::get) + }; + let n = walked(&|f| assert_eq!(read(f).unwrap(), (None, None))); + assert!(n <= entries, "read walked {n} entries of {entries}"); + let n = walked(&|f| assert_eq!(sure(f), Some(Vec::new()))); + assert!(n <= entries, "scan walked {n} entries of {entries}"); +} + +proptest::proptest! { + /// Arbitrary bytes behind a HEIF `ftyp`, or inside its `meta` box, never panic. + #[test] + fn arbitrary_boxes_never_panic(body in proptest::collection::vec(proptest::prelude::any::(), 0..512)) { + for f in [[bx(b"ftyp", b"heic\0\0\0\0mif1heic"), body.clone()].concat(), [bx(b"ftyp", b"heic\0\0\0\0mif1heic"), full_box(b"meta", 0, &body)].concat()] { + let _ = read(&f); + let _ = scan(&f).map(Iterator::count); + } + } +} From 402e686c7a002a8b686afa5b4ea34c13d3fd14b8 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 21:57:59 +0100 Subject: [PATCH 002/165] craft-heif: document items::read, scan and exif_tiff --- crates/heif/README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/crates/heif/README.md b/crates/heif/README.md index d5adf6fdd..6842dcc0d 100644 --- a/crates/heif/README.md +++ b/crates/heif/README.md @@ -36,11 +36,24 @@ Errors are `Error::Unsupported` (image sequences, overlays, 4:2:2/4:4:4, …), ` `Error::Malformed`. It never panics: every call into heic-rs runs under `catch_unwind`, and a panic inside it (PhotoCraft's fuzzing found two in 0.1.1) becomes `Error::Malformed`. -Features: `decode` (default) is the decoder above. `metadata` adds `craft_heif::items::read`: the -first `Exif` item and XMP packet from the box structure alone (`iinf`, `iloc`, `idat`; at most 4096 -boxes, 1024 items, 1024 extents per item, 32 MiB per item), without heic-rs. A build with +Features: `decode` (default) is the decoder above. `metadata` adds `craft_heif::items`, which reads +the `Exif` and XMP items from the box structure alone (`pitm`, `iinf`, `iref`, `iloc`, `idat`), +without heic-rs: + +- `items::read` returns the photo's own EXIF and XMP: the items `cdsc` ties to the primary image or + to an image it is made from (`dimg`: grid tiles, `iden`, `iovl`, `tmap`), else those tied to no + image. A thumbnail's or depth map's metadata is not the photo's. +- `items::scan` returns every EXIF and XMP item, whichever image it describes, and says when it + can't be sure it saw them all: `Scan::complete` is false for an incomplete or damaged item + catalog, and an item whose bytes can't be read comes back as `Unreadable`. An app that must + prove a file has no location (before an export that removes it) refuses when unsure. +- `items::exif_tiff` finds the TIFF stream in an `Exif` item, with or without a correct offset + field or an `Exif\0\0` prefix. + +The reader walks at most 65,536 boxes and walks `iloc` once. It gathers at most 16 MiB per item, +and a scan gathers at most 64 MiB in all. A build with `default-features = false, features = ["metadata"]` has no heic-rs dependency, and its -`read_metadata` is that reader. With both features, a test checks that the two readers agree. +`read_metadata` is `items::read`. With both features, a test checks that the two readers agree. Feature `testdata` exposes `craft_heif::testdata`: lossless synthetic HEIF files (PCM-coded 32 × 32 HEVC pictures, grids, every property above) for the tests of the crates above. From 2caa7deba14a39465de8fc5a24cceabd3fc71275 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 23:28:51 +0100 Subject: [PATCH 003/165] craft-heif: record the proptest dev-dependency in Cargo.lock --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index 52b28f0bd..34837eec4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1785,6 +1785,7 @@ name = "craft-heif" version = "0.1.0" dependencies = [ "heic-rs", + "proptest", "rayon", ] From 7ad164ff8a8938965774fc2581e6545404839b6a Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sun, 15 Nov 2026 00:26:42 +0100 Subject: [PATCH 004/165] craft-heif: refuse a too-large item before copying any of it `Iloc::gather` copied extents until it passed its limit and then returned `TooLarge`, and `scan` charges its byte budget only for items it returns. So 1,024 items, each naming one 64 KiB region 257 times, copied 16 GiB from a 2 MiB file, and `read` up to 1 GiB. Check every extent and sum the lengths first, and copy only when the total fits. The new test counts the bytes copied over the full 1,024-gather scan and `read`'s 64 candidates; it copied 16 GiB before. --- crates/heif/src/items.rs | 39 ++++++++++++++++++----- crates/heif/src/items/tests.rs | 57 ++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 7 deletions(-) diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index d00dbdf06..2d86b3027 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -589,7 +589,9 @@ impl<'a> Iloc<'a> { } /// An item's bytes, its extents in order from the file (construction method 0) or from the - /// `meta` box's `idat` (method 1), at most `limit` of them. + /// `meta` box's `idat` (method 1), at most `limit` of them. Every extent is checked and the + /// lengths summed before anything is copied, so an item that is too large (say, the same + /// region named by thousands of extents) costs no copying. fn gather(&self, file: &[u8], idat: Option<&[u8]>, place: &Place, limit: usize) -> Gathered { // data reference 0 is this file let source = match (place.data_reference, place.method, idat) { @@ -597,14 +599,25 @@ impl<'a> Iloc<'a> { (0, 1, Some(idat)) => idat, _ => return Gathered::Unreadable, }; - let mut out = Vec::new(); - let mut at = place.extents_at; - for _ in 0..place.extents { - let Some((piece, next)) = self.extent(source, place.base, at) else { return Gathered::Unreadable }; - at = next; - if out.len().saturating_add(piece.len()) > limit { + let pieces = || { + let mut at = place.extents_at; + (0..place.extents).map(move |_| { + let (piece, next) = self.extent(source, place.base, at)?; + at = next; + Some(piece) + }) + }; + let mut total = 0usize; + for piece in pieces() { + let Some(piece) = piece else { return Gathered::Unreadable }; + total = total.saturating_add(piece.len()); + if total > limit { return Gathered::TooLarge; } + } + let mut out = Vec::with_capacity(total); + for piece in pieces().flatten() { + bytes_copied(piece.len()); out.extend_from_slice(piece); } Gathered::Bytes(out) @@ -635,6 +648,18 @@ fn iloc_entry_visited() { ILOC_ENTRIES.with(|n| n.set(n.get().saturating_add(1))); } +#[cfg(test)] +thread_local! { + /// Item bytes copied on this thread, for the tests that bound the work. + static COPIED: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +#[cfg_attr(not(test), allow(unused_variables))] +fn bytes_copied(n: usize) { + #[cfg(test)] + COPIED.with(|c| c.set(c.get().saturating_add(n))); +} + /// A big-endian unsigned field of `size` bytes (0 reads as 0). fn uint(b: &[u8], at: usize, size: usize) -> Option { match size { diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs index 49cc9d789..6f73ff6c1 100644 --- a/crates/heif/src/items/tests.rs +++ b/crates/heif/src/items/tests.rs @@ -1128,6 +1128,63 @@ fn iloc_resolved_extents_still_obey_bounds_and_budget() { } } +/// A file whose MAX_SCANNED `Exif` items each name one 64 KiB region 257 times: every item is +/// too large, and finding that out copies nothing, for [`scan`] (all 1,024 gathers) and for +/// [`read`] (its MAX_CANDIDATES). Before, each gather copied MAX_ITEM bytes before giving up, +/// about 16 GiB for the scan of a 2 MiB file. +#[test] +fn too_large_items_are_refused_before_copying() { + const REGION: u32 = 64 << 10; + const REPEATS: u16 = 257; + let count = MAX_SCANNED as u16; + let mut iinf = count.to_be_bytes().to_vec(); + for id in 1..=count { + let mut e = vec![2u8, 0, 0, 0]; + e.extend_from_slice(&id.to_be_bytes()); + e.extend_from_slice(&[0, 0]); + e.extend_from_slice(b"Exif\0"); + iinf.extend(bx(b"infe", &e)); + } + let iloc = |region_at: u32| { + let mut l = vec![0x44, 0x00]; + l.extend_from_slice(&count.to_be_bytes()); + for id in 1..=count { + l.extend_from_slice(&id.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); // method 0, this file + l.extend_from_slice(&REPEATS.to_be_bytes()); + for _ in 0..REPEATS { + l.extend_from_slice(®ion_at.to_be_bytes()); + l.extend_from_slice(®ION.to_be_bytes()); + } + } + full_box(b"iloc", 1, &l) + }; + let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + let meta = |region_at| full_box(b"meta", 0, &[full_box(b"iinf", 0, &iinf), iloc(region_at)].concat()); + let region_at = (ftyp.len() + meta(0).len() + 8) as u32; + let f = [ftyp, meta(region_at), bx(b"mdat", &vec![0; REGION as usize])].concat(); + + COPIED.with(|c| c.set(0)); + let s = scan(&f).unwrap(); + assert!(s.complete()); + let found: Vec = s.collect(); + assert_eq!(found.len(), MAX_SCANNED); + assert!(found.iter().all(|it| it.data == Err(Unreadable::TooLarge))); + assert_eq!(COPIED.with(std::cell::Cell::get), 0, "scan copied bytes of items it refused"); + + COPIED.with(|c| c.set(0)); + assert_eq!(read(&f).unwrap(), (None, None)); + assert_eq!(COPIED.with(std::cell::Cell::get), 0, "read copied bytes of items it refused"); + + // an item that fits is copied once, extent by extent + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::Idat, 3); + h.iloc = (1, [4, 4, 4, 0]); + let f = h.build(); + COPIED.with(|c| c.set(0)); + assert_eq!(sure(&f), Some(vec![(2, Kind::Exif, exif_item(&[], &SWEEP_TIFF))])); + assert_eq!(COPIED.with(std::cell::Cell::get), SWEEP_TIFF.len() + 4); +} + /// `iloc` is walked once, however many metadata items there are to place (one walk per item /// took over a second on a 48 MB `iloc` with 64 items). #[test] From ed70d09162f4f932876536cd4bfc0905fc070605 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sun, 15 Nov 2026 00:28:28 +0100 Subject: [PATCH 005/165] craft-heif: a protected Exif or XMP item is unreadable, not absent A nonzero protection index made `item_info` return before it read the item type, so a protected `Exif` or XMP item vanished: `scan` was complete and empty, as if the file held no metadata. The protection index doesn't hide the type, so read it, and return the item from `scan` as `Unreadable::Protected`. `read` still leaves it out. --- crates/heif/src/items.rs | 29 ++++++++++++++++++++--------- crates/heif/src/items/tests.rs | 33 +++++++++++++++++++++++++++------ 2 files changed, 47 insertions(+), 15 deletions(-) diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index 2d86b3027..e0b2d2c93 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -145,6 +145,7 @@ impl Iterator for Scan<'_> { Gathered::NotPlaced => continue, Gathered::Unreadable => Err(Unreadable::Placement), Gathered::TooLarge => Err(Unreadable::TooLarge), + Gathered::Protected => Err(Unreadable::Protected), }; return Some(Item { id, kind, data }); } @@ -184,6 +185,9 @@ pub enum Unreadable { Placement, /// More than [`MAX_ITEM`] bytes, or more than [`scan`] has left of [`MAX_SCANNED_BYTES`]. TooLarge, + /// The item is protected (encrypted): its `infe` entry names a protection scheme, so its + /// stored bytes are not the metadata in the clear. + Protected, } /// The TIFF stream of an `Exif` item: past its 4-byte offset field and the bytes that offset @@ -214,6 +218,8 @@ struct Candidate { describes: bool, /// Tied to the primary image or an image it is made from. describes_primary: bool, + /// Protected (encrypted): there, but not readable. + protected: bool, } impl Candidate { @@ -308,6 +314,9 @@ impl<'a> Container<'a> { /// The bytes of `items[i]`, at most `limit` of them. fn gather(&self, i: usize, limit: usize) -> Gathered { + if self.items.get(i).is_some_and(|c| c.protected) { + return Gathered::Protected; + } match (&self.iloc, self.places.get(i)) { (Some(iloc), Some(Some(place))) => iloc.gather(self.file, self.idat, place, limit), _ if self.iloc_complete => Gathered::NotPlaced, @@ -326,6 +335,8 @@ enum Gathered { Unreadable, /// More than the limit. TooLarge, + /// A protected (encrypted) item. + Protected, } /// A full box's version: the first byte of its own payload (`None` for an empty box). @@ -370,14 +381,14 @@ fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> It catalog.complete = entries.last().map_or(first, |b| b.end) == iinf.end && u32::try_from(entries.len()).ok() == Some(count); for b in &entries { let info = bytes.get(b.body..b.end).filter(|_| &b.kind == b"infe").and_then(item_info); - let Some((id, kind)) = info else { + let Some((id, kind, protected)) = info else { catalog.complete = false; continue; }; catalog.ids.push(id); match kind { Some(_) if catalog.items.len() >= cap => catalog.more = true, - Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false }), + Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false, protected }), None => {} } } @@ -386,9 +397,11 @@ fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> It catalog } -/// An `infe` entry's item id, and its kind when it is an unprotected `Exif` or XMP item (`mime`, -/// `application/rdf+xml`). `None` when the entry can't be read to its last field. -fn item_info(infe: &[u8]) -> Option<(u32, Option)> { +/// An `infe` entry's item id, its kind when it is an `Exif` or XMP item (`mime`, +/// `application/rdf+xml`), and whether it is protected (encrypted). A protected entry still names +/// its type in the clear, so protected metadata is found too. `None` when the entry can't be read +/// to its last field. +fn item_info(infe: &[u8]) -> Option<(u32, Option, bool)> { let version = *infe.first()?; // version and flags, the item id (32 bits in version 3), the protection index let (id, at) = match version { @@ -396,9 +409,7 @@ fn item_info(infe: &[u8]) -> Option<(u32, Option)> { 3 => (be32(infe, 4)?, 8usize), _ => return None, }; - if be16(infe, at)? != 0 { - return Some((id, None)); // protected (encrypted) - } + let protected = be16(infe, at)? != 0; let at = at.checked_add(2)?; // versions 0 and 1 have no item type and describe MIME items; 2 and 3 name the type let (kind, at) = if version >= 2 { (infe.get(at..at.checked_add(4)?)?, at.checked_add(4)?) } else { (b"mime".as_slice(), at) }; @@ -421,7 +432,7 @@ fn item_info(infe: &[u8]) -> Option<(u32, Option)> { } _ => None, }; - Some((id, kind)) + Some((id, kind, protected)) } /// The NUL-terminated string at `at` and where the next field starts. diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs index 6f73ff6c1..35a193613 100644 --- a/crates/heif/src/items/tests.rs +++ b/crates/heif/src/items/tests.rs @@ -707,14 +707,15 @@ fn malformed_bounds_are_refused() { let mut iref = vec![0, 0, 0, 0]; iref.extend(bx(b"cdsc", &[0, 2, 0xff, 0xff])); let iref = bx(b"iref", &iref); - let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false }]; + let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false, protected: false }]; let mut budget = MAX_BOXES; let b = boxes(&iref, 0, iref.len(), &mut budget); link(&iref, &b[0], Some(1), &mut items, &mut budget); assert!(!items[0].describes); assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 0, b'E', b'x']), None, "cut short: the item type is unknown"); assert_eq!(item_info(&[4, 0, 0, 0, 0, 2, 0, 0, b'E', b'x', b'i', b'f', 0]), None, "unknown infe version"); - assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, None)), "protected"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, Some(Kind::Exif), true)), "protected"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x']), None, "protected and cut short"); // a full box's version is its own first byte, never the next box's let two = [bx(b"iref", &[]), bx(b"free", &[1, 2, 3])].concat(); let mut budget = MAX_BOXES; @@ -946,7 +947,7 @@ fn item_catalog_uncertainty_keeps_readable_exif() { } } -/// Catalogs without metadata items, and protected items, leave a complete, empty scan. +/// Catalogs without metadata items leave a complete, empty scan. #[test] fn item_catalog_benign_entries_and_empty_tables_are_complete() { let h = Heif::new(); @@ -965,15 +966,35 @@ fn item_catalog_benign_entries_and_empty_tables_are_complete() { assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); } } - // A protected (encrypted) item is not a metadata item this reader can read. - let mut entry = catalog_entry(2, 2, b"Exif", b"\0"); + // A protected (encrypted) image item is no metadata item. + let mut entry = catalog_entry(2, 1, b"hvc1", b"\0"); entry[7] = 1; - let h = h.item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); assert_eq!(sure(&with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry))))), Some(Vec::new())); // Complete top-level files without an item meta box have no item catalog to inspect. assert_eq!(sure(&bx(b"ftyp", b"msf1\0\0\0\0msf1")), Some(Vec::new())); } +/// A protected (encrypted) `Exif` or XMP item is in the scan, as unreadable: the file holds +/// metadata that can't be checked. [`read`] leaves it out. +#[test] +fn protected_metadata_is_unreadable_not_absent() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + for (kind, fields, expected) in [(b"Exif", b"\0".as_slice(), Kind::Exif), (b"mime", b"name\0application/rdf+xml\0", Kind::Xmp)] { + for version in [2, 3] { + let mut entry = catalog_entry(version, 2, kind, fields); + let protection_at = if version == 3 { 9 } else { 7 }; + entry[protection_at] = 1; + let f = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry)))); + let s = scan(&f).unwrap(); + assert!(s.complete(), "{kind:?} v{version}"); + let found: Vec = s.collect(); + assert_eq!(found, [Item { id: 2, kind: expected, data: Err(Unreadable::Protected) }], "{kind:?} v{version}"); + assert_eq!(sure(&f), None, "{kind:?} v{version}"); + assert_eq!(read(&f).unwrap(), (None, None), "{kind:?} v{version}"); + } + } +} + /// Running out of box budget, or a walk that stops before the end of its box, never makes a /// scan complete. #[test] From 2e3ff2162bbf0ee24dc225fc54df19eb4e539547 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 11:44:48 +0100 Subject: [PATCH 006/165] craft-image-codecs: SGI image reader and writer Adds Format::Sgi: 8- and 16-bit gray, gray+alpha, RGB and RGBA, verbatim and run-length encoded on read, run-length encoded on write. Palette-mapped files are reported as unsupported. Closes #1559 --- crates/image-codecs/README.md | 1 + crates/image-codecs/src/codecs.rs | 1 + crates/image-codecs/src/codecs/sgi.rs | 345 ++++++++++++++++++++ crates/image-codecs/src/format.rs | 14 +- crates/image-codecs/src/lib.rs | 4 +- crates/image-codecs/tests/it/detect_caps.rs | 17 + 6 files changed, 379 insertions(+), 3 deletions(-) create mode 100644 crates/image-codecs/src/codecs/sgi.rs diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..135853490 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -56,6 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "< | Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in | | DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in | | Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in | +| SGI (`.sgi`, `.rgb`, `.bw`) | yes | yes (RLE) | U8, U16 | Gray, Gray+A, RGB, RGBA | yes | no | no | no | no | no | no | built in | | AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` | | HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` | diff --git a/crates/image-codecs/src/codecs.rs b/crates/image-codecs/src/codecs.rs index 0288ae22b..6f070a290 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -17,6 +17,7 @@ pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; pub(crate) mod pnm; +pub(crate) mod sgi; pub(crate) mod tga; pub(crate) mod tiff; pub(crate) mod tiff_exif; diff --git a/crates/image-codecs/src/codecs/sgi.rs b/crates/image-codecs/src/codecs/sgi.rs new file mode 100644 index 000000000..1e31b5f0a --- /dev/null +++ b/crates/image-codecs/src/codecs/sgi.rs @@ -0,0 +1,345 @@ +//! SGI image files (`.sgi`, `.rgb`, `.rgba`, `.bw`): 8- and 16-bit gray, gray + alpha, RGB and +//! RGBA, verbatim or run-length encoded. +//! +//! Read and write follow the published SGI image file format description: a 512-byte big-endian +//! header, then one plane per channel with the rows stored bottom to top. Palette-mapped files +//! (colormap ID other than 0) are rejected. The writer uses the run-length encoding. + +use crate::error::CodecError; +use crate::fidelity::Plan; +use crate::format::Format; +use crate::image::{ChannelLayout, Image, SampleType}; +use crate::options::Limits; + +const F: Format = Format::Sgi; +const HEADER: usize = 512; +const MAGIC: u16 = 474; + +fn bad(reason: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, reason) +} + +fn be16(b: &[u8], i: usize) -> u16 { + u16::from_be_bytes([b[i], b[i + 1]]) +} + +fn be32(b: &[u8], i: usize) -> u32 { + u32::from_be_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]) +} + +/// The fields of the header that decoding needs, already checked for plausibility. +struct Header { + rle: bool, + wide: bool, + width: u32, + height: u32, + planes: usize, +} + +/// Parse the 512-byte header. `None` when the bytes are not a plausible SGI header. +fn header(b: &[u8]) -> Option
{ + if b.len() < HEADER || be16(b, 0) != MAGIC { + return None; + } + let (storage, bpc, dimension) = (b[2], b[3], be16(b, 4)); + let (width, height, planes) = (u32::from(be16(b, 6)), u32::from(be16(b, 8)), usize::from(be16(b, 10))); + if storage > 1 || !(1..=2).contains(&bpc) || !(1..=3).contains(&dimension) { + return None; + } + // A one-dimensional image has one row, a two-dimensional one a single plane. + let (height, planes) = match dimension { + 1 => (1, 1), + 2 => (height, 1), + _ => (height, planes), + }; + if width == 0 || height == 0 || !(1..=4).contains(&planes) { + return None; + } + Some(Header { rle: storage == 1, wide: bpc == 2, width, height, planes }) +} + +/// Whether `b` starts with a plausible SGI header (the magic number plus consistent fields). +pub(crate) fn looks_like_sgi(b: &[u8]) -> bool { + header(b).is_some() +} + +fn layout_of(planes: usize) -> ChannelLayout { + match planes { + 1 => ChannelLayout::Gray, + 2 => ChannelLayout::GrayA, + 3 => ChannelLayout::Rgb, + _ => ChannelLayout::Rgba, + } +} + +/// Expand one run-length encoded row into exactly `out.len()` samples. +fn read_rle_row(src: &[u8], wide: bool, out: &mut [u16]) -> Result<(), CodecError> { + let step = if wide { 2 } else { 1 }; + let sample = |pos: usize| -> Result { + let s = src.get(pos..pos + step).ok_or_else(|| bad("truncated RLE row"))?; + Ok(if wide { u16::from_be_bytes([s[0], s[1]]) } else { u16::from(s[0]) }) + }; + let (mut pos, mut n) = (0usize, 0usize); + while n < out.len() { + let code = sample(pos)?; + pos += step; + let count = usize::from(code & 0x7f); + if count == 0 { + return Err(bad("RLE row ends before the image width")); + } + if count > out.len() - n { + return Err(bad("RLE packet runs past the end of the row")); + } + if code & 0x80 != 0 { + for slot in &mut out[n..n + count] { + *slot = sample(pos)?; + pos += step; + } + } else { + let value = sample(pos)?; + pos += step; + out[n..n + count].fill(value); + } + n += count; + } + Ok(()) +} + +pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { + let h = header(b).ok_or_else(|| bad("invalid SGI header"))?; + if be32(b, 104) != 0 { + return Err(CodecError::unsupported(F, "palette-mapped SGI files are not supported")); + } + let layout = layout_of(h.planes); + let sample = if h.wide { SampleType::U16 } else { SampleType::U8 }; + limits.check(h.width, h.height, layout, sample)?; + let (w, ht, planes) = (h.width as usize, h.height as usize, h.planes); + let rows = ht.checked_mul(planes).ok_or_else(|| bad("image size overflow"))?; + let bps = if h.wide { 2 } else { 1 }; + let total = w.checked_mul(rows).ok_or_else(|| bad("image size overflow"))?; + // Reject inputs that cannot hold the declared pixels before allocating anything for them. + let table = if h.rle { rows.checked_mul(8).ok_or_else(|| bad("image size overflow"))? } else { 0 }; + let min_len = if h.rle { + // Every row needs at least a packet and a terminator. + HEADER + table + rows * bps + } else { + HEADER + total.checked_mul(bps).ok_or_else(|| bad("image size overflow"))? + }; + if b.len() < min_len { + return Err(bad("the file is too short for the declared image")); + } + let mut out = Vec::new(); + out.try_reserve_exact(total).map_err(|_| bad("pixel buffer is too large"))?; + out.resize(total, 0u16); + let mut row = vec![0u16; w]; + for z in 0..planes { + for y in 0..ht { + let index = y + z * ht; + if h.rle { + let start = be32(b, HEADER + index * 4) as usize; + let len = be32(b, HEADER + rows * 4 + index * 4) as usize; + let end = start.checked_add(len).filter(|&e| e <= b.len() && start >= HEADER).ok_or_else(|| bad("RLE row lies outside the file"))?; + read_rle_row(&b[start..end], h.wide, &mut row)?; + } else { + let start = HEADER + index * w * bps; + let s = &b[start..start + w * bps]; + for (x, v) in row.iter_mut().enumerate() { + *v = if h.wide { u16::from_be_bytes([s[2 * x], s[2 * x + 1]]) } else { u16::from(s[x]) }; + } + } + // Rows are stored bottom to top; planes are separate. + let top_y = ht - 1 - y; + for (x, &v) in row.iter().enumerate() { + out[(top_y * w + x) * planes + z] = v; + } + } + } + if h.wide { + Image::from_u16(h.width, h.height, layout, &out) + } else { + Image::from_u8(h.width, h.height, layout, out.iter().map(|&v| v as u8).collect()) + } +} + +/// Append one run-length encoded row (one packet list and a terminator). +fn write_rle_row(row: &[u16], wide: bool, out: &mut Vec) { + let put = |out: &mut Vec, v: u16| { + if wide { + out.extend_from_slice(&v.to_be_bytes()); + } else { + out.push(v as u8); + } + }; + let mut i = 0; + while i < row.len() { + let mut run = 1; + while i + run < row.len() && run < 127 && row[i + run] == row[i] { + run += 1; + } + if run >= 2 { + put(out, run as u16); + put(out, row[i]); + i += run; + } else { + // A literal packet extends until the next run of two or more. + let mut end = i + 1; + while end < row.len() && end - i < 127 && !(end + 1 < row.len() && row[end] == row[end + 1]) { + end += 1; + } + put(out, 0x80 | (end - i) as u16); + for &v in &row[i..end] { + put(out, v); + } + i = end; + } + } + put(out, 0); +} + +/// Writes a run-length encoded SGI file: 8 or 16 bits per channel, gray, gray + alpha, RGB or RGBA. +pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { + let enc = |msg: String| CodecError::encode(F, msg); + let img = src.converted(plan.layout, plan.sample); + let wide = match img.sample_type() { + SampleType::U8 => false, + SampleType::U16 => true, + s => return Err(enc(format!("SGI stores 8 or 16 bits per channel, not {s:?}"))), + }; + let planes = img.layout().channels(); + if !matches!(img.layout(), ChannelLayout::Gray | ChannelLayout::GrayA | ChannelLayout::Rgb | ChannelLayout::Rgba) { + return Err(enc(format!("no SGI layout for {:?}", img.layout()))); + } + let (w, ht) = img.dimensions(); + let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(ht)) else { + return Err(enc(format!("dimensions exceed 65535x65535: {w}x{ht}"))); + }; + let (w, ht) = (w as usize, ht as usize); + let bps = if wide { 2 } else { 1 }; + let data = img.data(); + if data.len() != w * ht * planes * bps { + return Err(enc("the image has the wrong number of samples".into())); + } + let sample_at = |i: usize| -> u16 { if wide { u16::from_ne_bytes([data[2 * i], data[2 * i + 1]]) } else { u16::from(data[i]) } }; + let rows = ht * planes; + let table = HEADER; + let mut starts = Vec::with_capacity(rows); + let mut lens = Vec::with_capacity(rows); + let mut body = Vec::new(); + let mut row = vec![0u16; w]; + let base = u32::try_from(HEADER + rows * 8).map_err(|_| enc("image too large".into()))?; + for z in 0..planes { + for y in 0..ht { + let src_y = ht - 1 - y; // stored bottom to top + for (x, v) in row.iter_mut().enumerate() { + *v = sample_at((src_y * w + x) * planes + z); + } + let before = body.len(); + write_rle_row(&row, wide, &mut body); + let start = u32::try_from(base as usize + before).map_err(|_| enc("image too large".into()))?; + starts.push(start); + lens.push((body.len() - before) as u32); + } + } + let mut out = Vec::with_capacity(table + rows * 8 + body.len()); + out.extend_from_slice(&MAGIC.to_be_bytes()); + out.push(1); // RLE + out.push(bps as u8); + out.extend_from_slice(&(if planes > 1 { 3u16 } else { 2u16 }).to_be_bytes()); + out.extend_from_slice(&w16.to_be_bytes()); + out.extend_from_slice(&h16.to_be_bytes()); + out.extend_from_slice(&(planes as u16).to_be_bytes()); + out.extend_from_slice(&0u32.to_be_bytes()); // pixmin + out.extend_from_slice(&(if wide { 65535u32 } else { 255 }).to_be_bytes()); // pixmax + out.resize(HEADER, 0); // dummy, image name, colormap 0, padding + for s in &starts { + out.extend_from_slice(&s.to_be_bytes()); + } + for l in &lens { + out.extend_from_slice(&l.to_be_bytes()); + } + out.extend_from_slice(&body); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn gradient(w: u32, h: u32, layout: ChannelLayout) -> Image { + let ch = layout.channels(); + let data = (0..w as usize * h as usize * ch).map(|i| ((i * 7 + i / 5) % 251) as u8).collect(); + Image::from_u8(w, h, layout, data).unwrap() + } + + #[test] + fn rle_round_trips_every_layout_in_8_bits() { + for layout in [ChannelLayout::Gray, ChannelLayout::GrayA, ChannelLayout::Rgb, ChannelLayout::Rgba] { + let img = gradient(37, 11, layout); + let plan = Plan { layout, sample: SampleType::U8 }; + let bytes = encode(&img, plan).unwrap(); + assert!(looks_like_sgi(&bytes)); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!(back.layout(), layout); + assert_eq!(back.data(), img.data()); + } + } + + #[test] + fn rle_round_trips_16_bits_with_long_runs() { + let (w, h) = (300u32, 4u32); + let samples: Vec = (0..w * h * 3).map(|i| if (i / 3) % 200 < 150 { 4242 } else { (i * 31) as u16 }).collect(); + let img = Image::from_u16(w, h, ChannelLayout::Rgb, &samples).unwrap(); + let bytes = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U16 }).unwrap(); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!(back.sample_type(), SampleType::U16); + assert_eq!(back.data(), img.data()); + } + + /// A hand-built verbatim file: two rows, one plane, stored bottom to top. + #[test] + fn verbatim_files_read_bottom_to_top() { + let mut f = vec![0u8; HEADER]; + f[0..2].copy_from_slice(&MAGIC.to_be_bytes()); + f[2] = 0; // verbatim + f[3] = 1; + f[4..6].copy_from_slice(&2u16.to_be_bytes()); + f[6..8].copy_from_slice(&3u16.to_be_bytes()); // x + f[8..10].copy_from_slice(&2u16.to_be_bytes()); // y + f[10..12].copy_from_slice(&1u16.to_be_bytes()); // z + f.extend_from_slice(&[10, 11, 12, 20, 21, 22]); // bottom row first + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!(img.layout(), ChannelLayout::Gray); + assert_eq!(img.data(), &[20, 21, 22, 10, 11, 12]); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + let img = gradient(16, 8, ChannelLayout::Rgb); + let good = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U8 }).unwrap(); + // Every truncation fails cleanly. + for len in 0..good.len() { + let _ = decode(&good[..len], &Limits::default()); + } + // A row table pointing outside the file, and a packet that overruns its row. + let mut bad_table = good.clone(); + bad_table[HEADER..HEADER + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&bad_table, &Limits::default()).is_err()); + let mut overrun = good.clone(); + let start = be32(&overrun, HEADER) as usize; + overrun[start] = 127; // a run longer than the 16-pixel row + assert!(decode(&overrun, &Limits::default()).is_err()); + // A huge declared size is stopped by the limits or the length check, before allocating. + let mut huge = good; + huge[6..8].copy_from_slice(&u16::MAX.to_be_bytes()); + huge[8..10].copy_from_slice(&u16::MAX.to_be_bytes()); + assert!(decode(&huge, &Limits::default()).is_err()); + } + + #[test] + fn palette_mapped_files_are_unsupported() { + let img = gradient(4, 4, ChannelLayout::Gray); + let mut f = encode(&img, Plan { layout: ChannelLayout::Gray, sample: SampleType::U8 }).unwrap(); + f[104..108].copy_from_slice(&1u32.to_be_bytes()); + assert!(matches!(decode(&f, &Limits::default()), Err(CodecError::Unsupported { .. }))); + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..d0d938bb7 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -44,6 +44,8 @@ pub enum Format { Iff, /// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`]. Jp2, + /// SGI image files (`.sgi`, `.rgb`, `.bw`): 8- and 16-bit gray, gray + alpha, RGB and RGBA. + Sgi, } /// What a format can hold **and** what this crate reads/writes for it. @@ -113,7 +115,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L:: impl Format { /// Every format known to the crate (enabled or not). - pub const ALL: [Format; 24] = [ + pub const ALL: [Format; 25] = [ Format::Png, Format::Jpeg, Format::Jp2, @@ -138,6 +140,7 @@ impl Format { Format::Cineon, Format::Dicom, Format::Iff, + Format::Sgi, ]; pub fn caps(self) -> FormatCaps { @@ -176,6 +179,7 @@ impl Format { Format::Dicom => "DICOM", Format::Iff => "Amiga IFF", Format::Jp2 => "JPEG 2000", + Format::Sgi => "SGI", } } @@ -207,6 +211,7 @@ impl Format { Format::Dicom => &["dcm", "dicom", "dc3"], Format::Iff => &["iff", "lbm", "ilbm"], Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"], + Format::Sgi => &["sgi", "rgb", "rgba", "bw"], } } @@ -236,13 +241,14 @@ impl Format { Format::Dicom => "application/dicom", Format::Iff => "image/x-iff", Format::Jp2 => "image/jp2", + Format::Sgi => "image/x-sgi", } } /// Maximum encodable dimensions, if the format has a hard limit. pub fn max_dimensions(self) -> Option<(u32, u32)> { match self { - Format::Jpeg | Format::Gif | Format::Iff => Some((65535, 65535)), + Format::Jpeg | Format::Gif | Format::Iff | Format::Sgi => Some((65535, 65535)), Format::WebP => Some((16384, 16384)), Format::Ico => Some((256, 256)), _ => None, @@ -310,6 +316,7 @@ pub fn caps(format: Format) -> FormatCaps { Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base }, + Format::Sgi => FormatCaps { depths: &[S::U8, S::U16], layouts: RGB_GRAY, alpha: true, ..base }, Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base }, } } @@ -388,6 +395,9 @@ pub fn detect(bytes: &[u8]) -> Option { if b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n") { return Some(Format::Xpm); } + if crate::codecs::sgi::looks_like_sgi(b) { + return Some(Format::Sgi); + } if crate::codecs::pcx::looks_like_pcx(b) { return Some(Format::Pcx); } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 21130e392..cad63019d 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -62,7 +62,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_ pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding}; pub use half::f16; -use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm}; +use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, sgi, tiff, via_image, webp, xpm}; /// Detect the format and decode with default [`Limits`]. pub fn decode(bytes: &[u8]) -> Result { @@ -101,6 +101,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res Format::Cineon => dpx::decode_cineon(bytes, l), Format::Dicom => dicom::decode(bytes, l), Format::Iff => iff::decode(bytes, l), + Format::Sgi => sgi::decode(bytes, l), Format::OpenExr => exr::decode(bytes, l), Format::Heif => heif::decode(bytes, l, opts.keep_orientation), Format::Jp2 => jp2::decode(bytes, l), @@ -457,6 +458,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result dpx::encode_cineon(image, plan), Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")), Format::Iff => iff::encode(image, plan), + Format::Sgi => sgi::encode(image, plan), Format::OpenExr => exr::encode(image, plan, opts), Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")), Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")), diff --git a/crates/image-codecs/tests/it/detect_caps.rs b/crates/image-codecs/tests/it/detect_caps.rs index 640772c83..d7d448388 100644 --- a/crates/image-codecs/tests/it/detect_caps.rs +++ b/crates/image-codecs/tests/it/detect_caps.rs @@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() { Format::Dpx, Format::Cineon, Format::Iff, + Format::Sgi, ]; for f in expected { assert!(caps(f).read && caps(f).write, "{f:?}"); @@ -218,6 +219,22 @@ fn detect_magic_iff() { assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None); assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err()); } +#[test] +fn detect_magic_sgi() { + use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode}; + let img = Image::from_u8(5, 3, ChannelLayout::Rgba, (0..60).collect()).unwrap(); + let bytes = encode(&img, Format::Sgi, &EncodeOptions::default()).unwrap(); + assert_eq!(detect(&bytes), Some(Format::Sgi)); + assert_eq!(from_extension("scan.RGB"), Some(Format::Sgi)); + assert_eq!(from_extension("scan.bw"), Some(Format::Sgi)); + assert_eq!(decode(&bytes).unwrap().data(), img.data()); + assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::Sgi)); + assert_eq!(Format::Sgi.max_dimensions(), Some((65535, 65535))); + // The magic number alone, without a full header, is not SGI. + assert_eq!(detect(&[0x01, 0xda, 0, 1, 0, 2]), None); + assert!(decode_as(Format::Sgi, &[0x01, 0xda]).is_err()); +} + #[test] fn detect_magic_avif() { assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif)); From 5628ad359d8f5bf9778f53edba9b9989b4b61d09 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 11:49:53 +0100 Subject: [PATCH 007/165] craft-image-codecs: Sun Raster image reader and writer Adds Format::SunRaster: 1-, 8- (gray or colour-mapped), 24- and 32-bit files, uncompressed or byte-encoded (RLE) on read, uncompressed on write. Closes #1560 --- crates/image-codecs/README.md | 1 + crates/image-codecs/src/codecs.rs | 1 + crates/image-codecs/src/codecs/sunraster.rs | 237 ++++++++++++++++++++ crates/image-codecs/src/format.rs | 12 +- crates/image-codecs/src/lib.rs | 4 +- crates/image-codecs/tests/it/detect_caps.rs | 14 ++ 6 files changed, 267 insertions(+), 2 deletions(-) create mode 100644 crates/image-codecs/src/codecs/sunraster.rs diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..f9f5f53e6 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -56,6 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "< | Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in | | DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in | | Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in | +| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, Gray+A, RGB, RGBA | yes | no | no | no | no | no | no | built in | | AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` | | HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` | diff --git a/crates/image-codecs/src/codecs.rs b/crates/image-codecs/src/codecs.rs index 0288ae22b..aecf95bbd 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -17,6 +17,7 @@ pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; pub(crate) mod pnm; +pub(crate) mod sunraster; pub(crate) mod tga; pub(crate) mod tiff; pub(crate) mod tiff_exif; diff --git a/crates/image-codecs/src/codecs/sunraster.rs b/crates/image-codecs/src/codecs/sunraster.rs new file mode 100644 index 000000000..84d60f145 --- /dev/null +++ b/crates/image-codecs/src/codecs/sunraster.rs @@ -0,0 +1,237 @@ +//! Sun Raster files (`.ras`, `.sun`): 1-bit, 8-bit (gray or colour-mapped), 24-bit RGB and 32-bit +//! RGBA, uncompressed or byte-encoded (RLE) on read; uncompressed on write. +//! +//! Follows the published rasterfile format: a 32-byte big-endian header, an optional colour map, +//! then rows padded to an even number of bytes. In the "standard" type (1) 24- and 32-bit pixels +//! are stored blue-first; in the "RGB" type (3) red-first. Other types (TIFF, IFF, experimental) +//! are reported as unsupported. + +use crate::error::CodecError; +use crate::fidelity::Plan; +use crate::format::Format; +use crate::image::{ChannelLayout, Image, SampleType}; +use crate::options::Limits; + +const F: Format = Format::SunRaster; +const HEADER: usize = 32; +const MAGIC: u32 = 0x59a6_6a95; + +fn bad(reason: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, reason) +} + +fn be32(b: &[u8], i: usize) -> u32 { + u32::from_be_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]) +} + +/// Whether `b` starts with a Sun rasterfile header. +pub(crate) fn looks_like_sunraster(b: &[u8]) -> bool { + b.len() >= HEADER && be32(b, 0) == MAGIC && matches!(be32(b, 12), 1 | 8 | 24 | 32) +} + +/// Expand byte-encoded data (`0x80` escapes a run) until `want` bytes are produced. +fn unrle(src: &[u8], want: usize) -> Result, CodecError> { + let mut out = Vec::new(); + out.try_reserve_exact(want).map_err(|_| bad("pixel buffer is too large"))?; + let mut i = 0; + while out.len() < want { + let b = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + if b != 0x80 { + out.push(b); + continue; + } + let n = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + if n == 0 { + out.push(0x80); + continue; + } + let v = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + let count = usize::from(n) + 1; + if count > want - out.len() { + return Err(bad("RLE run passes the end of the image")); + } + out.resize(out.len() + count, v); + } + Ok(out) +} + +pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { + if !looks_like_sunraster(b) { + return Err(bad("invalid Sun raster header")); + } + let (w, h, depth, kind, map_type, map_len) = (be32(b, 4), be32(b, 8), be32(b, 12) as usize, be32(b, 20), be32(b, 24), be32(b, 28) as usize); + if !matches!(kind, 0..=3) { + return Err(CodecError::unsupported(F, format!("Sun raster type {kind} is not supported"))); + } + if map_type > 2 { + return Err(CodecError::unsupported(F, format!("Sun raster map type {map_type} is not supported"))); + } + let layout = match depth { + 1 | 8 if map_type != 1 => ChannelLayout::Gray, + 1 | 8 | 24 => ChannelLayout::Rgb, + _ => ChannelLayout::Rgba, + }; + limits.check(w, h, layout, SampleType::U8)?; + let (wu, hu) = (w as usize, h as usize); + let stride = wu.checked_mul(depth).and_then(|n| n.checked_add(15)).ok_or_else(|| bad("image size overflow"))? / 16 * 2; + let want = stride.checked_mul(hu).ok_or_else(|| bad("image size overflow"))?; + let data_at = HEADER.checked_add(map_len).ok_or_else(|| bad("colour map size overflow"))?; + let map = b.get(HEADER..data_at).ok_or_else(|| bad("truncated colour map"))?; + let rest = &b[data_at..]; + let raw; + let rows: &[u8] = if kind == 2 { + raw = unrle(rest, want)?; + &raw + } else { + rest.get(..want).ok_or_else(|| bad("the file is too short for the declared image"))? + }; + let channels = layout.channels(); + let mut out = Vec::new(); + out.try_reserve_exact(wu * hu * channels).map_err(|_| bad("pixel buffer is too large"))?; + let entries = map_len / 3; + for y in 0..hu { + let row = &rows[y * stride..(y + 1) * stride]; + for x in 0..wu { + match depth { + 1 => { + // A set bit is black. + let bit = (row[x / 8] >> (7 - x % 8)) & 1; + out.push(if bit == 1 { 0 } else { 255 }); + } + 8 if map_type == 1 => { + let i = usize::from(row[x]); + if i >= entries { + return Err(bad("pixel index is outside the colour map")); + } + out.extend_from_slice(&[map[i], map[entries + i], map[2 * entries + i]]); + } + 8 => out.push(row[x]), + 24 => { + let p = &row[3 * x..3 * x + 3]; + out.extend_from_slice(&if kind == 3 { [p[0], p[1], p[2]] } else { [p[2], p[1], p[0]] }); + } + _ => { + let p = &row[4 * x..4 * x + 4]; + out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], p[0]] }); + } + } + } + } + Image::from_u8(w, h, layout, out) +} + +/// Writes an uncompressed rasterfile: 8-bit gray, 24-bit RGB or 32-bit RGBA, in the RGB-ordered type. +pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { + let enc = |msg: String| CodecError::encode(F, msg); + let img = src.converted(plan.layout, plan.sample); + if img.sample_type() != SampleType::U8 { + return Err(enc(format!("Sun raster stores 8 bits per channel, not {:?}", img.sample_type()))); + } + let depth: usize = match img.layout() { + ChannelLayout::Gray => 8, + ChannelLayout::Rgb => 24, + ChannelLayout::Rgba => 32, + l => return Err(enc(format!("no Sun raster layout for {l:?}"))), + }; + let (w, h) = img.dimensions(); + let (wu, hu) = (w as usize, h as usize); + let bytes = depth / 8; + let stride = (wu * bytes).next_multiple_of(2); + let len = stride.checked_mul(hu).and_then(|n| u32::try_from(n).ok()).ok_or_else(|| enc("image too large".into()))?; + let data = img.data(); + if data.len() != wu * hu * bytes { + return Err(enc("the image has the wrong number of samples".into())); + } + let mut out = Vec::with_capacity(HEADER + len as usize); + for v in [MAGIC, w, h, depth as u32, len, 3, 0, 0] { + out.extend_from_slice(&v.to_be_bytes()); + } + for y in 0..hu { + let row = &data[y * wu * bytes..(y + 1) * wu * bytes]; + if depth == 32 { + // Stored alpha first. + for p in row.as_chunks::<4>().0 { + out.extend_from_slice(&[p[3], p[0], p[1], p[2]]); + } + } else { + out.extend_from_slice(row); + } + out.resize(HEADER + (y + 1) * stride, 0); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn pattern(w: u32, h: u32, layout: ChannelLayout) -> Image { + let n = w as usize * h as usize * layout.channels(); + Image::from_u8(w, h, layout, (0..n).map(|i| ((i * 13 + i / 3) % 253) as u8).collect()).unwrap() + } + + #[test] + fn round_trips_gray_rgb_and_rgba_with_odd_widths() { + for layout in [ChannelLayout::Gray, ChannelLayout::Rgb, ChannelLayout::Rgba] { + let img = pattern(13, 7, layout); + let bytes = encode(&img, Plan { layout, sample: SampleType::U8 }).unwrap(); + assert!(looks_like_sunraster(&bytes)); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!((back.layout(), back.data()), (layout, img.data())); + } + } + + fn file(depth: u32, kind: u32, map: &[u8], map_type: u32, w: u32, h: u32, data: &[u8]) -> Vec { + let mut f = Vec::new(); + for v in [MAGIC, w, h, depth, data.len() as u32, kind, map_type, map.len() as u32] { + f.extend_from_slice(&v.to_be_bytes()); + } + f.extend_from_slice(map); + f.extend_from_slice(data); + f + } + + #[test] + fn standard_type_is_blue_first_and_rle_expands() { + let f = file(24, 1, &[], 0, 1, 1, &[1, 2, 3, 0]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[3, 2, 1]); + // 0x80 0x00 is a literal 0x80; 0x80 n v is n + 1 copies of v. The 2x2 image has stride 2. + let f = file(8, 2, &[], 0, 2, 2, &[0x80, 0x00, 0x80, 0x00, 0x80, 0x01, 7]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0x80, 0x80, 7, 7]); + // A run that passes the end of the image is an error. + assert!(decode(&file(8, 2, &[], 0, 2, 2, &[0x80, 0x09, 7]), &Limits::default()).is_err()); + } + + #[test] + fn colour_mapped_and_one_bit_files() { + // Two entries: red plane, green plane, blue plane. + let map = [10, 20, 30, 40, 50, 60]; + let f = file(8, 1, &map, 1, 2, 1, &[0, 1]); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10, 30, 50, 20, 40, 60][..])); + let f = file(8, 1, &map, 1, 1, 1, &[5, 0]); + assert!(decode(&f, &Limits::default()).is_err()); + let f = file(1, 1, &[], 0, 3, 1, &[0b1010_0000, 0]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0, 255, 0]); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + let img = pattern(9, 5, ChannelLayout::Rgb); + let good = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U8 }).unwrap(); + for len in 0..good.len() { + let _ = decode(&good[..len], &Limits::default()); + } + let mut huge = good.clone(); + huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes()); + huge[8..12].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&huge, &Limits::default()).is_err()); + let mut bad_map = good; + bad_map[28..32].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&bad_map, &Limits::default()).is_err()); + assert!(matches!(decode(&file(24, 4, &[], 0, 1, 1, &[0; 4]), &Limits::default()), Err(CodecError::Unsupported { .. }))); + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..d4075cc8e 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -44,6 +44,8 @@ pub enum Format { Iff, /// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`]. Jp2, + /// Sun Raster (`.ras`): 1-, 8-, 24- and 32-bit, uncompressed or RLE. + SunRaster, } /// What a format can hold **and** what this crate reads/writes for it. @@ -113,7 +115,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L:: impl Format { /// Every format known to the crate (enabled or not). - pub const ALL: [Format; 24] = [ + pub const ALL: [Format; 25] = [ Format::Png, Format::Jpeg, Format::Jp2, @@ -138,6 +140,7 @@ impl Format { Format::Cineon, Format::Dicom, Format::Iff, + Format::SunRaster, ]; pub fn caps(self) -> FormatCaps { @@ -176,6 +179,7 @@ impl Format { Format::Dicom => "DICOM", Format::Iff => "Amiga IFF", Format::Jp2 => "JPEG 2000", + Format::SunRaster => "Sun Raster", } } @@ -207,6 +211,7 @@ impl Format { Format::Dicom => &["dcm", "dicom", "dc3"], Format::Iff => &["iff", "lbm", "ilbm"], Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"], + Format::SunRaster => &["ras", "sun"], } } @@ -236,6 +241,7 @@ impl Format { Format::Dicom => "application/dicom", Format::Iff => "image/x-iff", Format::Jp2 => "image/jp2", + Format::SunRaster => "image/x-sun-raster", } } @@ -310,6 +316,7 @@ pub fn caps(format: Format) -> FormatCaps { Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base }, + Format::SunRaster => FormatCaps { layouts: &[L::Gray, L::Rgb, L::Rgba], alpha: true, ..base }, Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base }, } } @@ -388,6 +395,9 @@ pub fn detect(bytes: &[u8]) -> Option { if b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n") { return Some(Format::Xpm); } + if crate::codecs::sunraster::looks_like_sunraster(b) { + return Some(Format::SunRaster); + } if crate::codecs::pcx::looks_like_pcx(b) { return Some(Format::Pcx); } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 21130e392..ab235d2ab 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -62,7 +62,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_ pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding}; pub use half::f16; -use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm}; +use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, sunraster, tiff, via_image, webp, xpm}; /// Detect the format and decode with default [`Limits`]. pub fn decode(bytes: &[u8]) -> Result { @@ -101,6 +101,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res Format::Cineon => dpx::decode_cineon(bytes, l), Format::Dicom => dicom::decode(bytes, l), Format::Iff => iff::decode(bytes, l), + Format::SunRaster => sunraster::decode(bytes, l), Format::OpenExr => exr::decode(bytes, l), Format::Heif => heif::decode(bytes, l, opts.keep_orientation), Format::Jp2 => jp2::decode(bytes, l), @@ -457,6 +458,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result dpx::encode_cineon(image, plan), Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")), Format::Iff => iff::encode(image, plan), + Format::SunRaster => sunraster::encode(image, plan), Format::OpenExr => exr::encode(image, plan, opts), Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")), Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")), diff --git a/crates/image-codecs/tests/it/detect_caps.rs b/crates/image-codecs/tests/it/detect_caps.rs index 640772c83..17fb20442 100644 --- a/crates/image-codecs/tests/it/detect_caps.rs +++ b/crates/image-codecs/tests/it/detect_caps.rs @@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() { Format::Dpx, Format::Cineon, Format::Iff, + Format::SunRaster, ]; for f in expected { assert!(caps(f).read && caps(f).write, "{f:?}"); @@ -218,6 +219,19 @@ fn detect_magic_iff() { assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None); assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err()); } +#[test] +fn detect_magic_sun_raster() { + use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode}; + let img = Image::from_u8(5, 3, ChannelLayout::Rgb, (0..45).collect()).unwrap(); + let bytes = encode(&img, Format::SunRaster, &EncodeOptions::default()).unwrap(); + assert_eq!(detect(&bytes), Some(Format::SunRaster)); + assert_eq!(from_extension("scan.RAS"), Some(Format::SunRaster)); + assert_eq!(decode(&bytes).unwrap().data(), img.data()); + assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::SunRaster)); + assert_eq!(detect(&[0x59, 0xa6, 0x6a, 0x95]), None); + assert!(decode_as(Format::SunRaster, &[0x59, 0xa6, 0x6a, 0x95]).is_err()); +} + #[test] fn detect_magic_avif() { assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif)); From 1985afe943f2088e56697948638d3286260e6db9 Mon Sep 17 00:00:00 2001 From: nuclearspike Date: Sun, 15 Nov 2026 09:40:41 -0500 Subject: [PATCH 008/165] tga: port metadata payload boundaries and regressions from FilmCraft #1932 Source head e7842f76f887005c460c64a8ab51d59d086e6f27; adapt original decoder guard and synthetic regressions to shared Picture/Error API. --- crates/tga/src/lib.rs | 118 ++++++++- crates/tga/src/metadata_tests.rs | 424 +++++++++++++++++++++++++++++++ 2 files changed, 536 insertions(+), 6 deletions(-) create mode 100644 crates/tga/src/metadata_tests.rs diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index ac9d21497..88f4efe6c 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -18,6 +18,8 @@ //! Input is treated as hostile: the picture size is capped by [`Limits`], and a run-length file //! must be long enough to hold the pixels its header declares before anything is allocated. +#[cfg(test)] +mod metadata_tests; #[cfg(test)] mod tests; @@ -180,6 +182,105 @@ impl Stored { } } +fn metadata_offset(body: &[u8], offset: usize, first_pixel: usize) -> Option { + // Optional metadata cannot replace the header, image ID, or colour map. + (offset >= first_pixel && offset < body.len()).then_some(offset) +} + +/// The start of every developer-directory payload with a nonzero length, from the directory at +/// `directory` in `body` (none when that offset holds no readable directory). +fn developer_payload_starts(body: &[u8], directory: usize) -> Vec { + let Some(count) = + body.get(directory..directory.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map(|v| usize::from(u16::from_le_bytes(*v))) + else { + return Vec::new(); + }; + let Some(fields) = body.get(directory.saturating_add(2)..) else { return Vec::new() }; + fields + .chunks(10) + .take(count) + .filter_map(|field| { + let start = field.get(2..6).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v) as usize)?; + let length = field.get(6..10).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v))?; + (length != 0).then_some(start) + }) + .collect() +} + +fn image_data_end(bytes: &[u8], first_pixel: usize) -> Result { + if !bytes.ends_with(SIGNATURE) { + return Ok(bytes.len()); + } + // A TGA 2.0 footer cannot begin inside the mandatory header. A legacy image + // may end with the same signature as pixel bytes. + let Some(footer) = bytes.len().checked_sub(SIGNATURE.len() + 8).filter(|&at| at >= HEADER) else { + return Ok(bytes.len()); + }; + let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or_else(|| Error::Malformed("truncated footer"))?; + let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or_else(|| Error::Malformed("truncated footer"))?; + let directory = offsets + .get(4..) + .and_then(|v| v.first_chunk::<4>()) + .map(|v| u32::from_le_bytes(*v) as usize) + .ok_or_else(|| Error::Malformed("truncated footer"))?; + let body = bytes.get(..footer).ok_or_else(|| Error::Malformed("truncated footer"))?; + let mut end = footer; + + if let Some(offset) = metadata_offset(body, extension, first_pixel) { + // An in-body reference is a conservative image boundary, even if it overlaps + // required pixels. Those bytes cannot be distinguished from a truncated image + // whose missing pixels are supplied by metadata. + end = end.min(offset); + // TGA 2.0 extension fields at byte offsets 482, 486 and 490 point to the colour + // correction, postage-stamp and scan-line tables. The record's first two bytes give + // its size (495 in TGA 2.0); a shorter record has no such fields, and a record never + // reaches into a developer directory that follows it, so those bytes are not read as + // table offsets. Tables may precede the record. + let declared = + body.get(offset..offset.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map_or(0, |v| usize::from(u16::from_le_bytes(*v))); + let mut record_end = offset.saturating_add(declared.min(495)); + // The developer directory and its payloads may sit anywhere after the pixels, a payload + // before its directory included; whichever starts first after the extension ends it. + // A directory offset of zero means there is none: the header is not read as one. + let payloads = metadata_offset(body, directory, first_pixel).map(|d| developer_payload_starts(body, d)).unwrap_or_default(); + for next in std::iter::once(directory).chain(payloads) { + if next > offset { + record_end = record_end.min(next); + } + } + if let Some(area) = body.get(offset..record_end.min(body.len())) { + for field in [482, 486, 490] { + if let Some(value) = area.get(field..field + 4).and_then(|v| v.first_chunk::<4>()) + && let Some(table) = metadata_offset(body, u32::from_le_bytes(*value) as usize, first_pixel) + { + end = end.min(table); + } + } + } + } + + if let Some(offset) = metadata_offset(body, directory, first_pixel) { + end = end.min(offset); + if let Some(count) = + body.get(offset..offset.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map(|v| usize::from(u16::from_le_bytes(*v))) + && let Some(fields) = body.get(offset.saturating_add(2)..) + { + // A corrupt count or final entry does not hide earlier payload offsets. Each + // entry has a 2-byte tag followed by a 4-byte offset and 4-byte length. + for field in fields.chunks(10).take(count) { + if let Some(value) = field.get(2..6).and_then(|v| v.first_chunk::<4>()) + && let Some(length) = field.get(6..10).and_then(|v| v.first_chunk::<4>()) + && u32::from_le_bytes(*length) != 0 + && let Some(payload) = metadata_offset(body, u32::from_le_bytes(*value) as usize, first_pixel) + { + end = end.min(payload); + } + } + } + } + Ok(end) +} + /// Decodes a Targa file to straight-alpha RGBA8, top row first. pub fn decode(bytes: &[u8], limits: &Limits) -> Result { let err = Error::Malformed; @@ -208,13 +309,18 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { } else { None }; - let mut at = HEADER + id_len; - if let Some(l) = map_entry { - let end = at + map_len * l.bytes(); - let map = bytes.get(at..end).ok_or(err("truncated colour map"))?; - palette = map.chunks_exact(l.bytes()).map(|e| l.rgba(e)).collect(); - at = end; + let map_start = HEADER + id_len; + let first_pixel = match map_entry { + Some(layout) => map_start.checked_add(map_len * layout.bytes()).ok_or(err("colour map"))?, + None => map_start, + }; + let end = image_data_end(bytes, first_pixel)?; + let bytes = bytes.get(..end).ok_or(err("truncated image data"))?; + if let Some(layout) = map_entry { + let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; + palette = map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry)).collect(); } + let at = first_pixel; let (stored_as, mapped) = match kind & 7 { 1 => { if map_type != 1 || !matches!(depth, 8 | 16) { diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs new file mode 100644 index 000000000..a5c6c0b12 --- /dev/null +++ b/crates/tga/src/metadata_tests.rs @@ -0,0 +1,424 @@ +//! Metadata-boundary regressions ported from FilmCraft #1932 (nuclearspike). +use super::*; +fn header(kind: u8, w: u16, h: u16, depth: u8, descriptor: u8) -> Vec { + let mut b = vec![0, 0, kind, 0, 0, 0, 0, 0, 0, 0, 0, 0]; + b.extend_from_slice(&w.to_le_bytes()); + b.extend_from_slice(&h.to_le_bytes()); + b.extend_from_slice(&[depth, descriptor]); + b +} +fn dec(bytes: &[u8]) -> Result { + decode(bytes, &Limits::default()) +} +#[test] +fn legacy_pixels_that_end_in_signature_are_not_a_footer_before_header() { + for prefix in [0usize, 7] { + let width = (prefix + SIGNATURE.len()) as u16; + let mut file = header(3, width, 1, 8, 0x20); + file.extend(vec![0; prefix]); + file.extend_from_slice(SIGNATURE); + let image = dec(&file).unwrap(); + assert_eq!((image.width, image.height), (u32::from(width), 1)); + let pixels: Vec = std::iter::repeat_n(0, prefix).chain(SIGNATURE.iter().copied()).flat_map(|gray| [gray, gray, gray, 255]).collect(); + assert_eq!(image.rgba, pixels); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, pixels); + } +} + +#[test] +fn short_extension_followed_by_a_developer_payload_keeps_the_pixels() { + // a 482-byte extension whose size field still says 495, then a developer payload whose + // first bytes land where a full extension keeps its colour-correction offset, then the + // directory that points back at that payload + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[10, 20, 30]); + let extension = file.len() as u32; + let mut area = vec![0; 482]; + area[..2].copy_from_slice(&495u16.to_le_bytes()); + file.extend_from_slice(&area); + let payload = file.len() as u32; + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&[0; 14]); + let directory = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&0u16.to_le_bytes()); + file.extend_from_slice(&payload.to_le_bytes()); + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).expect("the image decodes"); + assert_eq!((source.width, source.height), (1, 1)); + assert_eq!(source.rgba, vec![30, 20, 10, 255]); +} + +#[test] +fn a_footer_without_a_directory_does_not_read_the_header_as_one() { + // no developer directory (offset 0). Read as one, the header's three-byte image ID + // length is an entry count, and the third "entry" is the first words of a colour + // correction table that sits right after a short pixel area; the extension points at + // that table, so the image is incomplete and must stay so. + let mut file = header(2, 2, 1, 24, 0x20); + file[0] = 3; + file.extend_from_slice(&[7, 8, 9]); + file.extend_from_slice(&[0, 0, 255]); + let table = file.len() as u32; + let mut words = vec![0; 2048]; + words[..4].copy_from_slice(&2074u32.to_le_bytes()); + words[4..8].copy_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&words); + let extension = file.len() as u32; + let mut area = vec![0; 495]; + area[..2].copy_from_slice(&495u16.to_le_bytes()); + area[482..486].copy_from_slice(&table.to_le_bytes()); + file.extend_from_slice(&area); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let decoded = dec(&file); + assert!(decoded.is_err(), "the second pixel is missing"); +} + +#[test] +fn short_extension_followed_by_a_developer_directory_keeps_the_pixels() { + // a complete 1x1 image, a 482-byte extension (its size says so) and right after it a + // developer directory whose entry's length lands where a full extension keeps its + // scan-line table offset; reading it as one would move the image end into the header + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[10, 20, 30]); + let extension = file.len() as u32; + let mut area = vec![0; 482]; + area[..2].copy_from_slice(&482u16.to_le_bytes()); + file.extend_from_slice(&area); + let directory = file.len() as u32; + let payload = directory + 2 + 10; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&0u16.to_le_bytes()); + file.extend_from_slice(&payload.to_le_bytes()); + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&[0; 18]); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).expect("the image decodes"); + assert_eq!((source.width, source.height), (1, 1)); +} + +#[test] +fn importing_truncated_pixels_does_not_consume_tga_footer() { + for (kind, data) in [(2, vec![0, 0, 255]), (10, vec![0x80, 0, 0, 255])] { + for metadata in [None, Some(0usize), Some(1)] { + let mut file = header(kind, 2, 1, 24, 0x20); + file.extend_from_slice(&data); // only the first of two pixels + let mut offsets = [0u8; 8]; + if let Some(field) = metadata { + let offset = file.len() as u32; + offsets[field * 4..field * 4 + 4].copy_from_slice(&offset.to_le_bytes()); + let mut area = vec![0; 495]; + if field == 0 { + area[..2].copy_from_slice(&495u16.to_le_bytes()); + } + file.extend_from_slice(&area); // optional metadata is not pixel data + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + let result = dec(&file); + assert!(matches!(result, Err(_)), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); + } + } + for kind in [1, 9] { + let mut file = header(kind, 1, 1, 8, 0x20); + file[1] = 1; + file[5] = 1; + file[7] = 24; + file.extend_from_slice(&[0, 0]); // missing third palette byte and the index + file.extend_from_slice(&[0; 8]); + file.extend_from_slice(SIGNATURE); + let result = dec(&file); + assert!(matches!(result, Err(_)), "kind {kind}: the footer is not colour-map data"); + } +} + +#[test] +fn complete_tga_footer_and_metadata_do_not_change_pixels() { + for metadata in [None, Some(0usize), Some(1)] { + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255]); + let mut offsets = [0u8; 8]; + if let Some(field) = metadata { + let offset = file.len() as u32; + offsets[field * 4..field * 4 + 4].copy_from_slice(&offset.to_le_bytes()); + let mut area = vec![0; 495]; + if field == 0 { + area[..2].copy_from_slice(&495u16.to_le_bytes()); + } + file.extend_from_slice(&area); + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255]); + } +} + +fn preceding_metadata(complete: bool, metadata: usize) -> Vec { + let mut file = header(2, if complete { 1 } else { 2 }, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255]); + let payload_offset = file.len() as u32; + let mut offsets = [0u8; 8]; + if metadata == 0 { + file.extend_from_slice(&[0, 255, 0]); + let directory_offset = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&payload_offset.to_le_bytes()); + file.extend_from_slice(&3u32.to_le_bytes()); + offsets[4..].copy_from_slice(&directory_offset.to_le_bytes()); + } else { + match metadata { + 1 => file.extend_from_slice(&[0; 2048]), + 2 => file.extend_from_slice(&[1, 1, 0, 255, 0]), + 3 => file.extend_from_slice(&18u32.to_le_bytes()), + _ => unreachable!(), + } + let extension_offset = file.len() as u32; + let mut extension = [0; 495]; + extension[..2].copy_from_slice(&495u16.to_le_bytes()); + let field = [0, 482, 486, 490][metadata]; + extension[field..field + 4].copy_from_slice(&payload_offset.to_le_bytes()); + file.extend_from_slice(&extension); + offsets[..4].copy_from_slice(&extension_offset.to_le_bytes()); + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + file +} + +#[test] +fn preceding_metadata_cannot_supply_missing_pixels() { + let mut accepted = Vec::new(); + for metadata in 0..4 { + let result = dec(&preceding_metadata(false, metadata)); + if !matches!(result, Err(_)) { + accepted.push(metadata); + } + } + assert!(accepted.is_empty(), "metadata payloads supplied missing pixels: {accepted:?}"); +} + +#[test] +fn complete_pixels_before_metadata_keep_their_colour() { + for metadata in 0..4 { + let source = dec(&preceding_metadata(true, metadata)).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255], "metadata {metadata}"); + } + let mut file = preceding_metadata(true, 1); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&496u16.to_le_bytes()); + file.insert(footer, 0); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255], "larger complete extensions preserve pixels"); +} + +#[test] +fn malformed_optional_metadata_keeps_complete_pixels_readable() { + let accept = |file: Vec| { + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255]); + }; + for field in [0, 4] { + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + file[footer + field..footer + field + 4].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + } + for metadata in 1..4 { + let mut file = preceding_metadata(true, metadata); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + let field = [0, 482, 486, 490][metadata]; + file[extension + field..extension + field + 4].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + } + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file.drain(directory + 2..footer); + accept(file); + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + accept(file); + // A zero-length entry cannot mark a payload boundary, even if its offset overlaps pixels. + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 4..directory + 8].copy_from_slice(&19u32.to_le_bytes()); + file[directory + 8..directory + 12].copy_from_slice(&0u32.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 2); + file[21..23].copy_from_slice(&[255, 255]); + accept(file); + let mut file = preceding_metadata(true, 2); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 2); + let footer = file.len() - SIGNATURE.len() - 8; + file.remove(footer - 1); // extension is physically short, but its postage offset remains + accept(file); +} + +#[test] +fn malformed_metadata_offsets_inside_id_or_palette_keep_complete_pixels() { + let mut file = header(1, 1, 1, 8, 0x20); + file[0] = 4; // image ID length + file[1] = 1; // colour map present + file[5..7].copy_from_slice(&1u16.to_le_bytes()); + file[7] = 24; // one BGR palette entry + file.extend_from_slice(&[7, 8, 9, 10]); // image ID + file.extend_from_slice(&[0, 0, 255]); // red palette entry + file.push(0); // palette index + for (field, offset) in [(0, HEADER + 1), (4, HEADER + 4 + 1)] { + let mut candidate = file.clone(); + let mut footer_offsets = [0u8; 8]; + footer_offsets[field..field + 4].copy_from_slice(&(offset as u32).to_le_bytes()); + candidate.extend_from_slice(&footer_offsets); + candidate.extend_from_slice(SIGNATURE); + let image = dec(&candidate).unwrap(); + assert_eq!(image.rgba, [255, 0, 0, 255], "footer field {field}"); + } +} + +#[test] +fn malformed_optional_metadata_cannot_supply_missing_pixels() { + let mut file = preceding_metadata(false, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + + // The declared entry count exceeds the bytes before the footer, but the first entry's + // payload still precedes the directory and cannot be used as a second pixel. + let mut file = preceding_metadata(false, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + + let mut file = preceding_metadata(false, 2); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + let mut file = preceding_metadata(false, 2); + let footer = file.len() - SIGNATURE.len() - 8; + file.remove(footer - 1); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn valid_developer_directory_with_overlapping_payload_rejects_pixels() { + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + let mut extra = [0u8; 10]; + extra[..2].copy_from_slice(&2u16.to_le_bytes()); + extra[2..6].copy_from_slice(&(HEADER as u32).to_le_bytes()); + extra[6..10].copy_from_slice(&1u32.to_le_bytes()); + file.splice(footer..footer, extra); + let moved_footer = file.len() - SIGNATURE.len() - 8; + assert_eq!(u32::from_le_bytes(file[moved_footer + 4..moved_footer + 8].try_into().unwrap()), directory as u32); + assert_eq!(u16::from_le_bytes(file[directory..directory + 2].try_into().unwrap()), 2); + assert_eq!(&file[directory + 12..directory + 22], &extra); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn nonempty_developer_reference_inside_pixels_rejects_the_whole_image() { + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + let directory = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&(HEADER as u32 + 3).to_le_bytes()); + file.extend_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_)), "an overlapping reference must not return a partial image"); +} + +#[test] +fn inflated_developer_count_scans_the_next_chunk_as_an_entry_and_rejects_its_pixel_payload() { + // a directory claiming two entries over one real entry: the ten bytes after it, scanned as + // the second entry, name a payload inside the pixels, which is refused like any other + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + let directory = file.len() as u32; + file.extend_from_slice(&2u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&(directory + 22).to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&2u16.to_le_bytes()); + file.extend_from_slice(&(HEADER as u32 + 3).to_le_bytes()); + file.extend_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_)), "a scanned entry's payload inside the pixels is refused"); +} + +#[test] +fn legacy_pixels_that_end_in_signature_at_or_after_the_header_are_read_as_a_footer() { + // a footerless 36×1 grayscale image whose last 26 bytes happen to be eight zeros and the + // signature: the putative trailer begins at byte 28, so it is taken for a footer and the + // image, left with 10 pixel bytes, is rejected as truncated (the ambiguity the body states) + let prefix = 18usize; + let width = (prefix + SIGNATURE.len()) as u16; + let mut file = header(3, width, 1, 8, 0x20); + file.extend(vec![0; prefix]); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn mutated_tga_footer_files_never_panic() { + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + file.extend_from_slice(&[0; 8]); + file.extend_from_slice(SIGNATURE); + for end in 0..file.len() { + assert!(std::panic::catch_unwind(|| dec(&file[..end])).is_ok(), "truncation at {end}"); + } + for at in 0..file.len() { + let mut mutated = file.clone(); + mutated[at] ^= 0xFF; + assert!(std::panic::catch_unwind(|| dec(&mutated)).is_ok(), "mutation at {at}"); + } + for metadata in 0..4 { + let file = preceding_metadata(true, metadata); + assert!(dec(&file).is_ok()); + let footer = file.len() - SIGNATURE.len() - 8; + for end in 0..footer { + let mut truncated = file[..end].to_vec(); + truncated.extend_from_slice(&file[footer..]); + assert!(std::panic::catch_unwind(|| dec(&truncated)).is_ok(), "metadata {metadata}, footer-preserving truncation at {end}"); + } + for at in 0..file.len() { + let mut mutated = file.clone(); + mutated[at] ^= 0xFF; + assert!(std::panic::catch_unwind(|| dec(&mutated)).is_ok(), "metadata {metadata}, mutation at {at}"); + } + } +} From b6b33b6096a247514f5cbd1741633913e7261e91 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:40:41 -0500 Subject: [PATCH 009/165] tga: record original metadata-boundary source attribution --- ATTRIBUTION.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index c087ecda1..e6f928645 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -99,3 +99,5 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso ## Binary Apple property lists `crates/plist` is extracted from `storytold/craft-anything` (`crates/formats/src/plist.rs` and checked byte reads), at source main `88d1d9cac852aec1c7fd97886db451e005e49d2a`. MIT OR Apache-2.0; source license texts are retained in the crate. Primary import Git authors preserve Brandon Thomas, BFlat, RRFZ and Afloat. Regression imports preserve BFlat. XML, JSON projection, calendar formatting and app policy were not imported into the public API. + +`crates/tga/src/metadata_tests.rs` and metadata-boundary helpers in `crates/tga/src/lib.rs` are adapted from nuclearspike's FilmCraft #1932 at `e7842f76f887005c460c64a8ab51d59d086e6f27` (MIT OR Apache-2.0). Synthetic fixtures are original contributor test data; primary Git author retained. From e555cc0afe12d14a3fed4e369e78d45cf084109a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:48:49 -0500 Subject: [PATCH 010/165] fix(tga): use eager static footer errors --- crates/tga/src/lib.rs | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index 88f4efe6c..06a9941a0 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -216,14 +216,11 @@ fn image_data_end(bytes: &[u8], first_pixel: usize) -> Result { let Some(footer) = bytes.len().checked_sub(SIGNATURE.len() + 8).filter(|&at| at >= HEADER) else { return Ok(bytes.len()); }; - let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or_else(|| Error::Malformed("truncated footer"))?; - let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or_else(|| Error::Malformed("truncated footer"))?; - let directory = offsets - .get(4..) - .and_then(|v| v.first_chunk::<4>()) - .map(|v| u32::from_le_bytes(*v) as usize) - .ok_or_else(|| Error::Malformed("truncated footer"))?; - let body = bytes.get(..footer).ok_or_else(|| Error::Malformed("truncated footer"))?; + let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or(Error::Malformed("truncated footer"))?; + let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or(Error::Malformed("truncated footer"))?; + let directory = + offsets.get(4..).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v) as usize).ok_or(Error::Malformed("truncated footer"))?; + let body = bytes.get(..footer).ok_or(Error::Malformed("truncated footer"))?; let mut end = footer; if let Some(offset) = metadata_offset(body, extension, first_pixel) { From d2bb64c4ac41c9242479f5e8277580b847151e5a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:14:40 -0500 Subject: [PATCH 011/165] fix(tga): bound aggregate decoder storage and reserve fallibly --- crates/tga/src/lib.rs | 36 +++++++++++++++++++++++++------- crates/tga/src/metadata_tests.rs | 22 +++++++++---------- crates/tga/src/tests.rs | 33 +++++++++++++++++++++++++++-- 3 files changed, 70 insertions(+), 21 deletions(-) diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index 06a9941a0..5174a8093 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -59,11 +59,13 @@ pub type Result = std::result::Result; pub struct Limits { /// Most pixels (width × height) a picture may have. Default 2^28 (16384 × 16384). pub max_pixels: u64, + /// Maximum combined palette, stored-pixel and RGBA allocation bytes. Default 256 MiB. + pub max_decoded_bytes: usize, } impl Default for Limits { fn default() -> Self { - Self { max_pixels: 1 << 28 } + Self { max_pixels: 1 << 28, max_decoded_bytes: 256 << 20 } } } @@ -313,10 +315,6 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { }; let end = image_data_end(bytes, first_pixel)?; let bytes = bytes.get(..end).ok_or(err("truncated image data"))?; - if let Some(layout) = map_entry { - let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; - palette = map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry)).collect(); - } let at = first_pixel; let (stored_as, mapped) = match kind & 7 { 1 => { @@ -335,14 +333,35 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { }; let data = bytes.get(at..).unwrap_or_default(); let bpp = stored_as.bytes(); + let stored_bytes = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; + let rgba_bytes = pixels.checked_mul(4).ok_or(Error::LimitExceeded("image size"))?; + let palette_bytes = if map_entry.is_some() { map_len * 4 } else { 0 }; + let aggregate = + stored_bytes.checked_add(rgba_bytes).and_then(|n| n.checked_add(palette_bytes)).ok_or(Error::LimitExceeded("decode allocation bytes"))?; + if aggregate > limits.max_decoded_bytes { + return Err(Error::LimitExceeded("decode allocation bytes")); + } + if let Some(layout) = map_entry { + let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; + palette.try_reserve_exact(map_len).map_err(|_| Error::LimitExceeded("allocation failed"))?; + palette.extend(map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry))); + } // The stored values, in file order. let stored: Vec = if rle { unpack_rle(data, pixels, bpp)? } else { let n = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; - data.get(..n).ok_or(err("truncated pixel data"))?.to_vec() + { + let source = data.get(..n).ok_or(err("truncated pixel data"))?; + let mut values = Vec::new(); + values.try_reserve_exact(n).map_err(|_| Error::LimitExceeded("allocation failed"))?; + values.extend_from_slice(source); + values + } }; - let mut rgba = vec![0u8; pixels.checked_mul(4).ok_or(Error::LimitExceeded("image size"))?]; + let mut rgba = Vec::new(); + rgba.try_reserve_exact(rgba_bytes).map_err(|_| Error::LimitExceeded("allocation failed"))?; + rgba.resize(rgba_bytes, 0u8); for (i, v) in stored.chunks_exact(bpp).enumerate().take(pixels) { let (x, y) = (i % w, i / w); let x = if right_to_left { w - 1 - x } else { x }; @@ -386,7 +405,8 @@ fn unpack_rle(mut data: &[u8], pixels: usize, bpp: usize) -> Result> { return Err(short); } let total = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; - let mut out = Vec::with_capacity(total); + let mut out = Vec::new(); + out.try_reserve_exact(total).map_err(|_| Error::LimitExceeded("allocation failed"))?; while out.len() < total { let (&head, rest) = data.split_first().ok_or(short.clone())?; let count = usize::from(head & 0x7F) + 1; diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs index a5c6c0b12..583f5d691 100644 --- a/crates/tga/src/metadata_tests.rs +++ b/crates/tga/src/metadata_tests.rs @@ -124,7 +124,7 @@ fn importing_truncated_pixels_does_not_consume_tga_footer() { file.extend_from_slice(&offsets); file.extend_from_slice(SIGNATURE); let result = dec(&file); - assert!(matches!(result, Err(_)), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); + assert!(result.is_err(), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); } } for kind in [1, 9] { @@ -136,7 +136,7 @@ fn importing_truncated_pixels_does_not_consume_tga_footer() { file.extend_from_slice(&[0; 8]); file.extend_from_slice(SIGNATURE); let result = dec(&file); - assert!(matches!(result, Err(_)), "kind {kind}: the footer is not colour-map data"); + assert!(result.is_err(), "kind {kind}: the footer is not colour-map data"); } } @@ -200,7 +200,7 @@ fn preceding_metadata_cannot_supply_missing_pixels() { let mut accepted = Vec::new(); for metadata in 0..4 { let result = dec(&preceding_metadata(false, metadata)); - if !matches!(result, Err(_)) { + if result.is_ok() { accepted.push(metadata); } } @@ -305,7 +305,7 @@ fn malformed_optional_metadata_cannot_supply_missing_pixels() { let footer = file.len() - SIGNATURE.len() - 8; let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); // The declared entry count exceeds the bytes before the footer, but the first entry's // payload still precedes the directory and cannot be used as a second pixel. @@ -313,17 +313,17 @@ fn malformed_optional_metadata_cannot_supply_missing_pixels() { let footer = file.len() - SIGNATURE.len() - 8; let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); let mut file = preceding_metadata(false, 2); let footer = file.len() - SIGNATURE.len() - 8; let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); let mut file = preceding_metadata(false, 2); let footer = file.len() - SIGNATURE.len() - 8; file.remove(footer - 1); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] @@ -341,7 +341,7 @@ fn valid_developer_directory_with_overlapping_payload_rejects_pixels() { assert_eq!(u32::from_le_bytes(file[moved_footer + 4..moved_footer + 8].try_into().unwrap()), directory as u32); assert_eq!(u16::from_le_bytes(file[directory..directory + 2].try_into().unwrap()), 2); assert_eq!(&file[directory + 12..directory + 22], &extra); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] @@ -356,7 +356,7 @@ fn nonempty_developer_reference_inside_pixels_rejects_the_whole_image() { file.extend_from_slice(&0u32.to_le_bytes()); file.extend_from_slice(&directory.to_le_bytes()); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_)), "an overlapping reference must not return a partial image"); + assert!(dec(&file).is_err(), "an overlapping reference must not return a partial image"); } #[test] @@ -376,7 +376,7 @@ fn inflated_developer_count_scans_the_next_chunk_as_an_entry_and_rejects_its_pix file.extend_from_slice(&0u32.to_le_bytes()); file.extend_from_slice(&directory.to_le_bytes()); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_)), "a scanned entry's payload inside the pixels is refused"); + assert!(dec(&file).is_err(), "a scanned entry's payload inside the pixels is refused"); } #[test] @@ -389,7 +389,7 @@ fn legacy_pixels_that_end_in_signature_at_or_after_the_header_are_read_as_a_foot let mut file = header(3, width, 1, 8, 0x20); file.extend(vec![0; prefix]); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] diff --git a/crates/tga/src/tests.rs b/crates/tga/src/tests.rs index 06109a179..76472075f 100644 --- a/crates/tga/src/tests.rs +++ b/crates/tga/src/tests.rs @@ -116,8 +116,8 @@ fn hostile_headers_fail_without_allocating() { fn the_pixel_limit_is_checked() { let mut f = header(3, 2, 2, 8, 0); f.extend_from_slice(&[0; 4]); - assert!(decode(&f, &Limits { max_pixels: 4 }).is_ok()); - assert_eq!(decode(&f, &Limits { max_pixels: 3 }), Err(Error::LimitExceeded("pixel count"))); + assert!(decode(&f, &Limits { max_pixels: 4, ..Limits::default() }).is_ok()); + assert_eq!(decode(&f, &Limits { max_pixels: 3, ..Limits::default() }), Err(Error::LimitExceeded("pixel count"))); } #[test] @@ -235,3 +235,32 @@ fn written_files_read_back() { assert_eq!(r.rgba, want, "{layout:?}"); } } + +#[test] +fn aggregate_decode_budget_applies_before_rle_expansion() { + let mut file = header(10, 16, 16, 32, 0x28); + file.extend_from_slice(&[255, 0, 0, 255, 255, 255, 0, 0, 255, 255]); + let mut limits = Limits::default(); + limits.max_decoded_bytes = 2047; + assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); + limits.max_decoded_bytes = 2048; + assert_eq!(decode(&file, &limits).unwrap().rgba.len(), 1024); +} +#[test] +fn default_budget_rejects_large_rle_header_without_large_fixture() { + let file = header(10, 16384, 16384, 32, 0x28); + assert_eq!(decode(&file, &Limits::default()), Err(Error::LimitExceeded("decode allocation bytes"))); +} +#[test] +fn aggregate_decode_budget_counts_raw_and_palette_storage() { + let mut file = header(1, 1, 1, 8, 0x20); + file[1] = 1; + file[5] = 1; + file[7] = 24; + file.extend_from_slice(&[0, 0, 255, 0]); + let mut limits = Limits::default(); + limits.max_decoded_bytes = 8; + assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); + limits.max_decoded_bytes = 9; + assert_eq!(decode(&file, &limits).unwrap().rgba, [255, 0, 0, 255]); +} From a33a81b1f19b348deab1ec5bc3942cb26095e692 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:15:49 -0500 Subject: [PATCH 012/165] test(tga): initialize custom decode limits directly --- crates/tga/src/tests.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/crates/tga/src/tests.rs b/crates/tga/src/tests.rs index 76472075f..887c2915a 100644 --- a/crates/tga/src/tests.rs +++ b/crates/tga/src/tests.rs @@ -240,8 +240,7 @@ fn written_files_read_back() { fn aggregate_decode_budget_applies_before_rle_expansion() { let mut file = header(10, 16, 16, 32, 0x28); file.extend_from_slice(&[255, 0, 0, 255, 255, 255, 0, 0, 255, 255]); - let mut limits = Limits::default(); - limits.max_decoded_bytes = 2047; + let mut limits = Limits { max_decoded_bytes: 2047, ..Limits::default() }; assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); limits.max_decoded_bytes = 2048; assert_eq!(decode(&file, &limits).unwrap().rgba.len(), 1024); @@ -258,8 +257,7 @@ fn aggregate_decode_budget_counts_raw_and_palette_storage() { file[5] = 1; file[7] = 24; file.extend_from_slice(&[0, 0, 255, 0]); - let mut limits = Limits::default(); - limits.max_decoded_bytes = 8; + let mut limits = Limits { max_decoded_bytes: 8, ..Limits::default() }; assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); limits.max_decoded_bytes = 9; assert_eq!(decode(&file, &limits).unwrap().rgba, [255, 0, 0, 255]); From 7b51909d40deb15397ec90695dc611bde5d13e34 Mon Sep 17 00:00:00 2001 From: Francesco BV Date: Sun, 15 Nov 2026 10:28:08 -0500 Subject: [PATCH 013/165] shx: preserve CADCraft shape compiler and errors Original source by Francesco BV in cadcraft52c1e6de, copied from main7064a685. App font lookup, text layout and glyph interpretation are not moved. --- crates/shx/src/compile.rs | 313 ++++++++++++++++++++++++++++++++++++++ crates/shx/src/error.rs | 29 ++++ 2 files changed, 342 insertions(+) create mode 100644 crates/shx/src/compile.rs create mode 100644 crates/shx/src/error.rs diff --git a/crates/shx/src/compile.rs b/crates/shx/src/compile.rs new file mode 100644 index 000000000..2e8cb3c25 --- /dev/null +++ b/crates/shx/src/compile.rs @@ -0,0 +1,313 @@ +//! Shape source (`.shp`) to a compiled SHX file, as COMPILE does. +//! +//! A source is a list of definitions: a header line `*number,defbytes,NAME` followed by its +//! specification bytes (on as many lines as needed, ending with 0). Numbers are decimal, or +//! hexadecimal after a leading `0` (`012`, `08cfb`); parentheses only group; `;` starts a +//! comment. A big font starts with `*BIGFONT nchars,nranges,first,last,…` and a Unicode font +//! with `*UNIFONT,6,name` followed by `above,below,modes,encoding,type,0`. Shape 0 is a text +//! font's record (`above,below,modes,0`). +//! +//! Operands are encoded by what they are: a subshape number takes two bytes in a Unicode font +//! (and after `7,0` in a big font), displacements and bulges are two's complement, and an arc's +//! direction byte (`-043`) keeps its sign in the high bit. `defbytes` is not checked: the +//! program's own length is written. + +use super::ShxError; +use super::parse::{BIGFONT, SHAPES_10, UNIFONT}; + +/// Largest source compiled. +const MAX_SOURCE: usize = 8 << 20; + +#[derive(Clone, Copy, PartialEq)] +enum Kind { + Shapes, + Big, + Uni, +} + +struct Shape { + number: u16, + name: String, + program: Vec, +} + +/// A number token: value (sign included). +fn number(tok: &str, line: usize) -> Result { + let t: String = tok.chars().filter(|c| !matches!(c, '(' | ')') && !c.is_whitespace()).collect(); + let (neg, digits) = match t.strip_prefix('-') { + Some(d) => (true, d), + None => (false, t.strip_prefix('+').unwrap_or(&t)), + }; + let err = || ShxError::Source(line, format!("not a number: {tok:?}")); + let v = if digits.len() > 1 && digits.starts_with('0') { + i64::from_str_radix(digits.get(1..).unwrap_or_default(), 16).map_err(|_| err())? + } else { + digits.parse::().map_err(|_| err())? + }; + if v > 0xFFFF { + return Err(err()); + } + Ok(if neg { -v } else { v }) +} + +/// The comma-separated numbers of a line (comment removed, blank fields skipped). +fn numbers(text: &str, line: usize) -> Result, ShxError> { + text.split(',').map(str::trim).filter(|t| !t.is_empty() && *t != "(" && *t != ")").map(|t| number(t, line)).collect() +} + +/// The spec-byte encoder: walks the tokens as the reader walks the bytes. +struct Enc<'a> { + toks: &'a [i64], + i: usize, + out: Vec, + kind: Kind, + line: usize, +} + +impl Enc<'_> { + fn next(&mut self) -> Result { + let v = self.toks.get(self.i).copied().ok_or_else(|| ShxError::Source(self.line, "the shape ends inside a command".into()))?; + self.i += 1; + Ok(v) + } + fn byte(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let b = u8::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not a byte")))?; + self.out.push(b); + Ok(()) + } + /// Two's complement −128..127. + fn signed(&mut self) -> Result { + let v = self.next()?; + let b = i8::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not −128..127")))?; + self.out.extend(b.to_le_bytes()); + Ok(v) + } + /// Sign in the high bit (an arc's direction byte). + fn sign_magnitude(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let m = u8::try_from(v.unsigned_abs()) + .ok() + .filter(|m| *m < 0x80) + .ok_or_else(|| ShxError::Source(self.line, format!("{v} is not an octant byte")))?; + self.out.push(if v < 0 { m | 0x80 } else { m }); + Ok(()) + } + fn word(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let w = u16::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not a shape number")))?; + self.out.extend(w.to_be_bytes()); + Ok(()) + } + + fn program(mut self) -> Result, ShxError> { + while self.i < self.toks.len() { + let code = self.next()?; + let c = u8::try_from(code).map_err(|_| ShxError::Source(self.line, format!("{code} is not a code")))?; + self.out.push(c); + match c { + 0 => break, + 3 | 4 => self.byte()?, + 7 => match self.kind { + Kind::Uni => self.word()?, + Kind::Big => { + let first = self.toks.get(self.i).copied().unwrap_or(0); + if first == 0 { + self.byte()?; + self.word()?; + for _ in 0..4 { + self.byte()?; + } + } else { + self.byte()?; + } + } + Kind::Shapes => self.byte()?, + }, + 8 => { + self.signed()?; + self.signed()?; + } + 9 => loop { + let (x, y) = (self.signed()?, self.signed()?); + if x == 0 && y == 0 { + break; + } + }, + 10 => { + self.byte()?; + self.sign_magnitude()?; + } + 11 => { + for _ in 0..4 { + self.byte()?; + } + self.sign_magnitude()?; + } + 12 => { + for _ in 0..3 { + self.signed()?; + } + } + 13 => loop { + let (x, y) = (self.signed()?, self.signed()?); + if x == 0 && y == 0 { + break; + } + self.signed()?; + }, + _ => {} + } + } + if self.out.last() != Some(&0) { + self.out.push(0); + } + Ok(self.out) + } +} + +/// Compile shape source into an SHX file (a shape file or text font, a big font, or a Unicode +/// font, as its first definition says). +pub fn compile(source: &str) -> Result, ShxError> { + if source.len() > MAX_SOURCE { + return Err(ShxError::TooLarge); + } + let mut kind = Kind::Shapes; + let mut ranges: Vec<(u16, u16)> = Vec::new(); + let mut uni_info: Option<(String, Vec)> = None; + // Definitions: header (number, name, line) and the numbers that follow it. + let mut defs: Vec<(i64, String, usize, Vec)> = Vec::new(); + let mut uni_header_pending = false; + for (no, raw) in source.lines().enumerate() { + let line = no + 1; + let text = raw.split(';').next().unwrap_or_default().trim(); + if text.is_empty() { + continue; + } + if let Some(head) = text.strip_prefix('*') { + let upper = head.trim_start().to_ascii_uppercase(); + if let Some(rest) = upper.strip_prefix("BIGFONT") { + kind = Kind::Big; + let v = numbers(rest, line)?; + let n = usize::try_from(v.get(1).copied().unwrap_or(0)).unwrap_or(0); + for k in 0..n { + let lo = v.get(2 + 2 * k).copied().unwrap_or(0); + let hi = v.get(3 + 2 * k).copied().unwrap_or(lo); + let to = |x: i64| u16::try_from(x).map_err(|_| ShxError::Source(line, "bad escape range".into())); + ranges.push((to(lo)?, to(hi)?)); + } + continue; + } + if upper.starts_with("UNIFONT") { + kind = Kind::Uni; + let name = head.splitn(3, ',').nth(2).unwrap_or_default().trim().to_string(); + uni_info = Some((name, Vec::new())); + uni_header_pending = true; + continue; + } + uni_header_pending = false; + let mut parts = head.splitn(3, ','); + let num = number(parts.next().unwrap_or_default().trim(), line)?; + let _defbytes = parts.next(); + let name = parts.next().unwrap_or_default().trim().to_string(); + defs.push((num, name, line, Vec::new())); + continue; + } + let v = numbers(text, line)?; + if uni_header_pending { + if let Some((_, info)) = uni_info.as_mut() { + for x in v { + info.push(u8::try_from(x).map_err(|_| ShxError::Source(line, "bad font record".into()))?); + } + } + continue; + } + match defs.last_mut() { + Some(d) => d.3.extend(v), + None => return Err(ShxError::Source(line, "specification bytes before any *number,defbytes,NAME line".into())), + } + } + let mut shapes: Vec = Vec::new(); + for (num, name, line, toks) in defs { + let number = u16::try_from(num).map_err(|_| ShxError::Source(line, format!("shape number {num} out of range")))?; + let program = if number == 0 { + // The font record: plain bytes. + toks.iter().map(|x| u8::try_from(*x).map_err(|_| ShxError::Source(line, "bad font record".into()))).collect::, _>>()? + } else { + Enc { toks: &toks, i: 0, out: Vec::new(), kind, line }.program()? + }; + if shapes.iter().any(|s| s.number == number) { + return Err(ShxError::Source(line, format!("shape {number} is defined twice"))); + } + shapes.push(Shape { number, name, program }); + } + if shapes.is_empty() { + return Err(ShxError::Empty); + } + shapes.sort_by_key(|s| s.number); + let record = |s: &Shape| -> Result, ShxError> { + let mut r: Vec = s.name.bytes().filter(|b| *b != 0).collect(); + r.push(0); + r.extend(&s.program); + if r.len() > usize::from(u16::MAX) { Err(ShxError::TooLarge) } else { Ok(r) } + }; + let count = u16::try_from(shapes.len()).map_err(|_| ShxError::TooLarge)?; + let len16 = |r: &[u8]| u16::try_from(r.len()).unwrap_or(u16::MAX); + let mut out = Vec::new(); + match kind { + Kind::Shapes => { + out.extend(SHAPES_10); + out.extend(shapes.first().map_or(0, |s| s.number).to_le_bytes()); + out.extend(shapes.last().map_or(0, |s| s.number).to_le_bytes()); + out.extend(count.to_le_bytes()); + let recs: Vec> = shapes.iter().map(record).collect::>()?; + for (s, r) in shapes.iter().zip(&recs) { + out.extend(s.number.to_le_bytes()); + out.extend(len16(r).to_le_bytes()); + } + for r in &recs { + out.extend(r); + } + out.extend(b"EOF"); + } + Kind::Big => { + out.extend(BIGFONT); + let nranges = u16::try_from(ranges.len()).map_err(|_| ShxError::TooLarge)?; + out.extend(count.to_le_bytes()); + out.extend(count.to_le_bytes()); + out.extend(nranges.to_le_bytes()); + for (lo, hi) in &ranges { + out.extend(lo.to_le_bytes()); + out.extend(hi.to_le_bytes()); + } + let recs: Vec> = shapes.iter().map(record).collect::>()?; + let mut off = out.len() + 8 * recs.len(); + for (s, r) in shapes.iter().zip(&recs) { + out.extend(s.number.to_le_bytes()); + out.extend(len16(r).to_le_bytes()); + out.extend(u32::try_from(off).map_err(|_| ShxError::TooLarge)?.to_le_bytes()); + off += r.len(); + } + for r in &recs { + out.extend(r); + } + } + Kind::Uni => { + out.extend(UNIFONT); + let (name, info) = uni_info.unwrap_or_default(); + out.extend((u32::from(count) + 1).to_le_bytes()); + let mut rec: Vec = name.bytes().filter(|b| *b != 0).collect(); + rec.push(0); + rec.extend(&info); + out.extend(len16(&rec).to_le_bytes()); + out.extend(&rec); + for s in &shapes { + let r = record(s)?; + out.extend(s.number.to_le_bytes()); + out.extend(len16(&r).to_le_bytes()); + out.extend(r); + } + } + } + Ok(out) +} diff --git a/crates/shx/src/error.rs b/crates/shx/src/error.rs new file mode 100644 index 000000000..0addd1c98 --- /dev/null +++ b/crates/shx/src/error.rs @@ -0,0 +1,29 @@ +/// Why a font file can't be read or a shape source can't be compiled. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum ShxError { + /// Not an SHX file (unknown signature). + NotShx, + /// The file ends inside its header or index. + Truncated, + /// The file is larger, or has more of something, than CADCraft reads. + TooLarge, + /// The file is well-formed but holds no shape. + Empty, + /// Shape source error: line and message. + Source(usize, String), +} + +impl std::fmt::Display for ShxError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + ShxError::NotShx => f.write_str("not an SHX shape or font file"), + ShxError::Truncated => f.write_str("the SHX file is truncated"), + ShxError::TooLarge => f.write_str("the SHX file is too large"), + ShxError::Empty => f.write_str("the SHX file has no shapes"), + ShxError::Source(line, msg) => write!(f, "line {line}: {msg}"), + } + } +} + +impl std::error::Error for ShxError {} + From b3307f7814629961841b80ab907116252e41b34d Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:30:48 -0500 Subject: [PATCH 014/165] shx: expose shared bounded shape compiler with hostile-source tests --- Cargo.lock | 4 ++++ Cargo.toml | 1 + crates/shx/Cargo.toml | 11 +++++++++++ crates/shx/README.md | 8 ++++++++ crates/shx/src/compile.rs | 20 +++++++++++++++++--- crates/shx/src/error.rs | 1 - crates/shx/src/lib.rs | 8 ++++++++ crates/shx/tests/compiler.rs | 30 ++++++++++++++++++++++++++++++ 8 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 crates/shx/Cargo.toml create mode 100644 crates/shx/README.md create mode 100644 crates/shx/src/lib.rs create mode 100644 crates/shx/tests/compiler.rs diff --git a/Cargo.lock b/Cargo.lock index add90f8c2..3e9aeba59 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2610,6 +2610,10 @@ dependencies = [ name = "craft-sheet" version = "0.1.0" +[[package]] +name = "craft-shx" +version = "0.1.0" + [[package]] name = "craft-silhouette-studio" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index eae758e17..b68880781 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-shx = { path = "crates/shx" } craft-smime = { path = "crates/smime" } craft-ber = { path = "crates/ber" } craft-proto = { path = "crates/proto" } diff --git a/crates/shx/Cargo.toml b/crates/shx/Cargo.toml new file mode 100644 index 000000000..012f9d2f9 --- /dev/null +++ b/crates/shx/Cargo.toml @@ -0,0 +1,11 @@ +[package] +name = "craft-shx" +description = "Bounded SHP shape-source compiler for SHX shape, big-font and Unicode containers" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true diff --git a/crates/shx/README.md b/crates/shx/README.md new file mode 100644 index 000000000..691890447 --- /dev/null +++ b/crates/shx/README.md @@ -0,0 +1,8 @@ +# craft-shx + +Compiles SHP shape source into SHX shapes, big-font and Unicode containers. +Extracted from CADCraft by Francesco BV (cadcraft52c1e6de); no font assets are bundled. +App font discovery, text layout and glyph interpretation are not part of this crate. +The original 8 MiB source and u16 record bounds remain; malformed double signs, +excess escape ranges and oversized Unicode font records are refused. Duplicate +shape detection is linear rather than a repeated whole-list scan. diff --git a/crates/shx/src/compile.rs b/crates/shx/src/compile.rs index 2e8cb3c25..0d91a9545 100644 --- a/crates/shx/src/compile.rs +++ b/crates/shx/src/compile.rs @@ -13,7 +13,9 @@ //! program's own length is written. use super::ShxError; -use super::parse::{BIGFONT, SHAPES_10, UNIFONT}; +const SHAPES_10: &[u8] = b"AutoCAD-86 shapes 1.0\r\n\x1a"; +const BIGFONT: &[u8] = b"AutoCAD-86 bigfont 1.0\r\n\x1a"; +const UNIFONT: &[u8] = b"AutoCAD-86 unifont 1.0\r\n\x1a"; /// Largest source compiled. const MAX_SOURCE: usize = 8 << 20; @@ -44,7 +46,7 @@ fn number(tok: &str, line: usize) -> Result { } else { digits.parse::().map_err(|_| err())? }; - if v > 0xFFFF { + if !(0..=0xFFFF).contains(&v) { return Err(err()); } Ok(if neg { -v } else { v }) @@ -190,6 +192,11 @@ pub fn compile(source: &str) -> Result, ShxError> { kind = Kind::Big; let v = numbers(rest, line)?; let n = usize::try_from(v.get(1).copied().unwrap_or(0)).unwrap_or(0); + // A big font has byte-valued lead ranges. Bound repeated headers too, + // so a tiny declaration cannot amplify into millions of ranges. + if n > 256 || ranges.len().saturating_add(n) > 256 { + return Err(ShxError::TooLarge); + } for k in 0..n { let lo = v.get(2 + 2 * k).copied().unwrap_or(0); let hi = v.get(3 + 2 * k).copied().unwrap_or(lo); @@ -210,6 +217,9 @@ pub fn compile(source: &str) -> Result, ShxError> { let num = number(parts.next().unwrap_or_default().trim(), line)?; let _defbytes = parts.next(); let name = parts.next().unwrap_or_default().trim().to_string(); + if defs.len() >= usize::from(u16::MAX) { + return Err(ShxError::TooLarge); + } defs.push((num, name, line, Vec::new())); continue; } @@ -228,6 +238,7 @@ pub fn compile(source: &str) -> Result, ShxError> { } } let mut shapes: Vec = Vec::new(); + let mut seen = std::collections::HashSet::new(); for (num, name, line, toks) in defs { let number = u16::try_from(num).map_err(|_| ShxError::Source(line, format!("shape number {num} out of range")))?; let program = if number == 0 { @@ -236,7 +247,7 @@ pub fn compile(source: &str) -> Result, ShxError> { } else { Enc { toks: &toks, i: 0, out: Vec::new(), kind, line }.program()? }; - if shapes.iter().any(|s| s.number == number) { + if !seen.insert(number) { return Err(ShxError::Source(line, format!("shape {number} is defined twice"))); } shapes.push(Shape { number, name, program }); @@ -296,6 +307,9 @@ pub fn compile(source: &str) -> Result, ShxError> { out.extend(UNIFONT); let (name, info) = uni_info.unwrap_or_default(); out.extend((u32::from(count) + 1).to_le_bytes()); + if name.len().saturating_add(1).saturating_add(info.len()) > usize::from(u16::MAX) { + return Err(ShxError::TooLarge); + } let mut rec: Vec = name.bytes().filter(|b| *b != 0).collect(); rec.push(0); rec.extend(&info); diff --git a/crates/shx/src/error.rs b/crates/shx/src/error.rs index 0addd1c98..135214f54 100644 --- a/crates/shx/src/error.rs +++ b/crates/shx/src/error.rs @@ -26,4 +26,3 @@ impl std::fmt::Display for ShxError { } impl std::error::Error for ShxError {} - diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs new file mode 100644 index 000000000..e595e90f5 --- /dev/null +++ b/crates/shx/src/lib.rs @@ -0,0 +1,8 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +//! SHP source compilation to SHX containers, extracted from CADCraft. +//! Font discovery, glyph execution and text layout remain consumer responsibilities. +mod compile; +mod error; +pub use compile::compile; +pub use error::ShxError; diff --git a/crates/shx/tests/compiler.rs b/crates/shx/tests/compiler.rs new file mode 100644 index 000000000..f558e185a --- /dev/null +++ b/crates/shx/tests/compiler.rs @@ -0,0 +1,30 @@ +use craft_shx::{ShxError, compile}; + +#[test] +fn fixed_shape_bytes() { + let b = compile("*65,2,A\n010,0\n").unwrap(); + let mut expected = b"AutoCAD-86 shapes 1.0\r\n\x1a".to_vec(); + expected.extend([65, 0, 65, 0, 1, 0, 65, 0, 4, 0, b'A', 0, 0x10, 0]); + expected.extend(b"EOF"); + assert_eq!(b, expected); +} +#[test] +fn hostile_sources_are_refused() { + for src in [ + "*1,2,X\n7\n", + "*1,2,X\n9,(1,1)\n", + "*99999,1,X\n0\n", + "*1,1,X\n300,0\n", + "010,0\n", + "*1,1,X\n1,0zz,0\n", + "*1,1,X\n0\n*1,1,Y\n0\n", + "*--9223372036854775808,1,X\n0", + "*BIGFONT 1,65535\n*1,1,X\n0", + ] { + assert!(compile(src).is_err(), "{src:?}"); + } + assert_eq!(compile(""), Err(ShxError::Empty)); + assert_eq!(compile(&" ".repeat((8 << 20) + 1)), Err(ShxError::TooLarge)); + let oversized_header = format!("*UNIFONT,6,{}\n10,2,0,0,0,0\n*65,1,A\n0", "n".repeat(65536)); + assert_eq!(compile(&oversized_header), Err(ShxError::TooLarge)); +} From a2541707240580153c8ea9ef3043ec0257468d0a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:40 +0000 Subject: [PATCH 015/165] Share WebP header inspection --- crates/image-codecs/src/lib.rs | 1 + crates/image-codecs/src/webp_probe.rs | 47 +++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 crates/image-codecs/src/webp_probe.rs diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..961a04327 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -31,6 +31,7 @@ pub mod orientation; pub mod resolution; pub mod source_settings; pub mod web; +pub mod webp_probe; pub use crate::allocation::probe_allocation_size; pub use crate::cicp::Cicp; pub use crate::cicp::ContentLightLevel; diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs new file mode 100644 index 000000000..8376274df --- /dev/null +++ b/crates/image-codecs/src/webp_probe.rs @@ -0,0 +1,47 @@ +//! Header-only WebP inspection with image-chunk completeness checks. + +use crate::{CodecError, Format}; + +/// Stored width, height and EXIF orientation without decoding pixels. The image payload must +/// fit in the input, but its compressed contents are not validated. Uses the default decode limits. +pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { + let err = |s: &str| CodecError::malformed(Format::WebP, s); + let mut p = 12usize; + let mut has_image = false; + let mut exif = None; + while let Some(h) = bytes.get(p..p.saturating_add(8)) { + let size = u32::from_le_bytes([h[4], h[5], h[6], h[7]]) as usize; + let end = p.saturating_add(8).saturating_add(size); + if matches!(&h[..4], b"VP8 " | b"VP8L" | b"ANMF") { + if end > bytes.len() { + return Err(err("truncated image data")); + } + has_image = true; + } else if &h[..4] == b"EXIF" && end <= bytes.len() && exif.is_none() { + exif = bytes.get(p + 8..end); + } + p = end.saturating_add(size & 1); + } + if !has_image { + return Err(err("no image data")); + } + let (w, h) = crate::probe_size(bytes)?; + let orientation = exif.map_or(1, crate::exif_orientation); + let (w, h) = if (5..=8).contains(&orientation) { (h, w) } else { (w, h) }; + Ok((w, h, orientation)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rejects_missing_and_truncated_image_chunks() { + let mut bytes = b"RIFF\x00\x00\x00\x00WEBP".to_vec(); + assert!(header(&bytes).is_err()); + bytes.extend_from_slice(b"VP8 "); + bytes.extend_from_slice(&10u32.to_le_bytes()); + bytes.push(0); + assert!(header(&bytes).is_err()); + } +} From 3c5007339754def577b3c5274f523d96384a35c4 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:41 +0000 Subject: [PATCH 016/165] Share bounded SHX container reader --- crates/shx/src/lib.rs | 2 + crates/shx/src/parse.rs | 281 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 crates/shx/src/parse.rs diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs index e595e90f5..ce330450c 100644 --- a/crates/shx/src/lib.rs +++ b/crates/shx/src/lib.rs @@ -4,5 +4,7 @@ //! Font discovery, glyph execution and text layout remain consumer responsibilities. mod compile; mod error; +pub mod parse; pub use compile::compile; pub use error::ShxError; +pub use parse::{ParsedFont, Record, ShxKind}; diff --git a/crates/shx/src/parse.rs b/crates/shx/src/parse.rs new file mode 100644 index 000000000..9cd4a35ad --- /dev/null +++ b/crates/shx/src/parse.rs @@ -0,0 +1,281 @@ +//! Reading the compiled SHX containers (layouts in the module documentation). Every count and +//! offset comes from the file, so each is checked against its length; records that run past +//! the end are dropped and the rest kept. + +use super::ShxError; +use std::collections::HashMap; + +/// The SHX container kind. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ShxKind { + Shapes, + BigFont, + Unifont, +} +/// Byte ranges of one shape name and pen program in [`ParsedFont::data`]. +#[derive(Clone, Copy, Debug)] +pub struct Record { + pub name: (usize, usize), + pub program: (usize, usize), +} +/// Decoded container records and metrics; glyph execution remains a caller concern. +pub struct ParsedFont { + pub kind: ShxKind, + pub name: String, + pub header: bool, + pub above: f64, + pub below: f64, + pub dual: bool, + pub encoding: u8, + pub char_width: f64, + pub ranges: Vec<(u16, u16)>, + pub data: Vec, + pub records: HashMap, +} + +pub const SHAPES_10: &[u8] = b"AutoCAD-86 shapes 1.0\r\n\x1a"; +pub const SHAPES_11: &[u8] = b"AutoCAD-86 shapes 1.1\r\n\x1a"; +pub const BIGFONT: &[u8] = b"AutoCAD-86 bigfont 1.0\r\n\x1a"; +pub const UNIFONT: &[u8] = b"AutoCAD-86 unifont 1.0\r\n\x1a"; + +/// Largest file read (the largest big fonts are a few megabytes). +pub const MAX_FILE_BYTES: usize = 32 << 20; +/// Most escape ranges in a big font (lead bytes: at most 256). +const MAX_RANGES: usize = 256; + +/// A checked little-endian reader. +struct Rd<'a> { + b: &'a [u8], + pos: usize, +} + +impl<'a> Rd<'a> { + fn take(&mut self, n: usize) -> Result<&'a [u8], ShxError> { + let end = self.pos.checked_add(n).ok_or(ShxError::Truncated)?; + let s = self.b.get(self.pos..end).ok_or(ShxError::Truncated)?; + self.pos = end; + Ok(s) + } + fn u16(&mut self) -> Result { + match self.take(2)? { + [a, b] => Ok(u16::from_le_bytes([*a, *b])), + _ => Err(ShxError::Truncated), + } + } + fn u32(&mut self) -> Result { + match self.take(4)? { + [a, b, c, d] => Ok(u32::from_le_bytes([*a, *b, *c, *d])), + _ => Err(ShxError::Truncated), + } + } +} + +/// A font being read. +struct Font { + kind: ShxKind, + name: String, + header: bool, + above: f64, + below: f64, + dual: bool, + encoding: u8, + char_width: f64, + ranges: Vec<(u16, u16)>, + records: HashMap, +} + +impl Font { + fn new(kind: ShxKind) -> Font { + Font { + kind, + name: String::new(), + header: false, + above: 0.0, + below: 0.0, + dual: false, + encoding: 0, + char_width: 0.0, + ranges: Vec::new(), + records: HashMap::new(), + } + } + + /// Add the record of shape `number` at `start..end` of `data`: a NUL-terminated name, then + /// the program. Shape 0 is the font record. A record without a name terminator is dropped; + /// the first record of a number wins. + fn record(&mut self, data: &[u8], number: u16, start: usize, end: usize) { + let Some(bytes) = data.get(start..end) else { return }; + let Some(nul) = bytes.iter().position(|b| *b == 0) else { return }; + let name = (start, start + nul); + let program = (start + nul + 1, end); + if number == 0 { + if !self.header { + self.font_record(data.get(program.0..program.1).unwrap_or_default(), data.get(name.0..name.1).unwrap_or_default()); + } + return; + } + self.records.entry(number).or_insert(Record { name, program }); + } + + /// The font record: above, below, modes (and for a unifont encoding and embedding); an + /// extended big font's is character height, 0, modes, character width. + fn font_record(&mut self, info: &[u8], name: &[u8]) { + self.header = true; + self.name = name.iter().take(255).map(|c| char::from(*c)).collect(); + let byte = |i: usize| info.get(i).copied().unwrap_or(0); + self.above = f64::from(byte(0)); + self.below = f64::from(byte(1)); + self.dual = byte(2) == 2; + if self.kind == ShxKind::Unifont { + self.encoding = byte(3); + } + if self.kind == ShxKind::BigFont && info.len() >= 5 && byte(1) == 0 { + // Extended: height, 0, modes, width, 0. + self.below = 0.0; + self.char_width = f64::from(byte(3)); + } + } + + fn finish(self, data: Vec) -> Result { + if self.records.is_empty() { + return Err(ShxError::Empty); + } + Ok(ParsedFont { + kind: self.kind, + name: self.name, + header: self.header, + above: self.above, + below: self.below, + dual: self.dual, + encoding: self.encoding, + char_width: if self.char_width > 0.0 { self.char_width } else { self.above }, + ranges: self.ranges, + data, + records: self.records, + }) + } +} + +pub fn parse(bytes: &[u8]) -> Result { + if bytes.len() > MAX_FILE_BYTES { + return Err(ShxError::TooLarge); + } + if bytes.starts_with(SHAPES_10) || bytes.starts_with(SHAPES_11) { + shapes(bytes) + } else if bytes.starts_with(BIGFONT) { + bigfont(bytes) + } else if bytes.starts_with(UNIFONT) { + unifont(bytes) + } else { + Err(ShxError::NotShx) + } +} + +fn shapes(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: SHAPES_10.len() }; + let _first = r.u16()?; + let _last = r.u16()?; + let count = usize::from(r.u16()?); + // The whole index must be there before anything is read from it. + let index = r.take(count.checked_mul(4).ok_or(ShxError::TooLarge)?)?; + let mut f = Font::new(ShxKind::Shapes); + let mut pos = r.pos; + for [a, b, c, d] in index.as_chunks::<4>().0 { + let (number, len) = (u16::from_le_bytes([*a, *b]), usize::from(u16::from_le_bytes([*c, *d]))); + let Some(end) = pos.checked_add(len).filter(|e| *e <= bytes.len()) else { break }; + f.record(bytes, number, pos, end); + pos = end; + } + f.finish(bytes.to_vec()) +} + +fn bigfont(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: BIGFONT.len() }; + let index_size = usize::from(r.u16()?); + let count = usize::from(r.u16()?); + let nranges = usize::from(r.u16()?); + if nranges > MAX_RANGES { + return Err(ShxError::TooLarge); + } + let mut f = Font::new(ShxKind::BigFont); + for _ in 0..nranges { + let (lo, hi) = (r.u16()?, r.u16()?); + f.ranges.push((lo.min(hi), lo.max(hi))); + } + // The index has `count` entries of 8 bytes; a file whose count doesn't fit but whose index + // size does is read by that. + let fits = |n: usize| n.checked_mul(8).and_then(|l| r.pos.checked_add(l)).is_some_and(|e| e <= bytes.len()); + let n = if fits(count) { + count + } else if fits(index_size) { + index_size + } else { + return Err(ShxError::Truncated); + }; + let index = r.take(n.checked_mul(8).ok_or(ShxError::TooLarge)?)?; + for [a, b, c, d, o0, o1, o2, o3] in index.as_chunks::<8>().0 { + let number = u16::from_le_bytes([*a, *b]); + let len = usize::from(u16::from_le_bytes([*c, *d])); + let Ok(off) = usize::try_from(u32::from_le_bytes([*o0, *o1, *o2, *o3])) else { continue }; + if len == 0 { + continue; + } + let Some(end) = off.checked_add(len).filter(|e| *e <= bytes.len()) else { continue }; + f.record(bytes, number, off, end); + } + f.finish(bytes.to_vec()) +} + +fn unifont(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: UNIFONT.len() }; + let count = r.u32()?; + let info_len = usize::from(r.u16()?); + let info = r.take(info_len)?; + let mut f = Font::new(ShxKind::Unifont); + let nul = info.iter().position(|b| *b == 0).unwrap_or(info.len()); + f.font_record(info.get(nul.saturating_add(1)..).unwrap_or_default(), info.get(..nul).unwrap_or_default()); + // `count` includes the font record; never trusted beyond the data that is there. + let mut left = count.saturating_sub(1); + while left > 0 { + left -= 1; + let Ok(number) = r.u16() else { break }; + let Ok(len) = r.u16().map(usize::from) else { break }; + let start = r.pos; + let Some(end) = start.checked_add(len).filter(|e| *e <= bytes.len()) else { break }; + r.pos = end; + f.record(bytes, number, start, end); + } + f.finish(bytes.to_vec()) +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + #[test] + fn reads_shapes_bigfont_and_unifont_records() { + for (source, kind, shape) in [ + ("*0,4,font\n6,2,2,0\n*65,4,A\n1,064,0\n", ShxKind::Shapes, 65), + ("*BIGFONT 2,1,081,09F\n*0,4,big\n8,0,0,0\n*082A0,4,square\n1,080,0\n", ShxKind::BigFont, 0x82a0), + ("*UNIFONT,6,uni\n6,2,0,0,0,0\n*00041,4,a\n1,064,0\n", ShxKind::Unifont, 65), + ] { + let bytes = crate::compile(source).unwrap(); + let font = parse(&bytes).unwrap(); + assert_eq!(font.kind, kind); + assert!(font.header); + let record = font.records.get(&shape).unwrap(); + assert_eq!(font.data.get(record.program.1 - 1), Some(&0)); + } + } + #[test] + fn truncation_limits_and_unknown_signatures_are_errors() { + assert!(matches!(parse(b"not a font"), Err(ShxError::NotShx))); + assert!(matches!(parse(&vec![0; MAX_FILE_BYTES + 1]), Err(ShxError::TooLarge))); + let mut shapes = SHAPES_10.to_vec(); + shapes.extend([1, 0, 255, 255, 255, 255]); + assert!(matches!(parse(&shapes), Err(ShxError::Truncated))); + let mut big = BIGFONT.to_vec(); + big.extend([255, 255, 255, 255, 255, 255]); + assert!(matches!(parse(&big), Err(ShxError::TooLarge))); + } +} From b919ac40f3873fd3893c7ad97e6351940714c366 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:48:46 -0500 Subject: [PATCH 017/165] test(tga): validate metadata fixture selector explicitly --- crates/tga/src/metadata_tests.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs index 583f5d691..85c434bf4 100644 --- a/crates/tga/src/metadata_tests.rs +++ b/crates/tga/src/metadata_tests.rs @@ -163,6 +163,7 @@ fn complete_tga_footer_and_metadata_do_not_change_pixels() { } fn preceding_metadata(complete: bool, metadata: usize) -> Vec { + assert!(metadata <= 3, "test metadata selector must be 0..=3"); let mut file = header(2, if complete { 1 } else { 2 }, 1, 24, 0x20); file.extend_from_slice(&[0, 0, 255]); let payload_offset = file.len() as u32; @@ -180,7 +181,7 @@ fn preceding_metadata(complete: bool, metadata: usize) -> Vec { 1 => file.extend_from_slice(&[0; 2048]), 2 => file.extend_from_slice(&[1, 1, 0, 255, 0]), 3 => file.extend_from_slice(&18u32.to_le_bytes()), - _ => unreachable!(), + _ => {} } let extension_offset = file.len() as u32; let mut extension = [0; 495]; From 8a1bad8c2cc47f71c2a75fb19b67b54762fe8389 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:56 +0000 Subject: [PATCH 018/165] Cover WebP stored orientation --- crates/image-codecs/src/webp_probe.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index 8376274df..d70fac38d 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -35,6 +35,14 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { mod tests { use super::*; + #[test] + fn preserves_stored_dimensions_with_exif_orientation() { + let mut image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); + image.meta.exif = Some(b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00".to_vec()); + let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + assert_eq!(header(&bytes).unwrap(), (2, 3, 6)); + } + #[test] fn rejects_missing_and_truncated_image_chunks() { let mut bytes = b"RIFF\x00\x00\x00\x00WEBP".to_vec(); From 82e258ab6eae4f4d6cd9dfe463a8640fd20c96d9 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:50:14 +0000 Subject: [PATCH 019/165] Exercise camera orientation in WebP fixture --- crates/image-codecs/src/webp_probe.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index d70fac38d..8e33a71cf 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -39,7 +39,11 @@ mod tests { fn preserves_stored_dimensions_with_exif_orientation() { let mut image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); image.meta.exif = Some(b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00".to_vec()); - let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + let mut bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + // The writer correctly makes exported pixels upright; simulate a camera file carrying orientation 6. + let exif = bytes.windows(4).position(|v| v == b"EXIF").unwrap(); + let tiff = exif + 8; + bytes[tiff + 18] = 6; assert_eq!(header(&bytes).unwrap(), (2, 3, 6)); } From 5ae0c89fdfca73c924db0521e2772e67c6cd49d3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:50:50 +0000 Subject: [PATCH 020/165] audio: share compatible PCM essence wrappers --- crates/audio/src/essence_pcm.rs | 147 ++++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 4 + 2 files changed, 151 insertions(+) create mode 100644 crates/audio/src/essence_pcm.rs diff --git a/crates/audio/src/essence_pcm.rs b/crates/audio/src/essence_pcm.rs new file mode 100644 index 000000000..593ebb1c2 --- /dev/null +++ b/crates/audio/src/essence_pcm.rs @@ -0,0 +1,147 @@ +//! Compatibility WAVE and AIFF wrappers for embedded PCM essence in interchange files. +//! PCM inside the model is interleaved little-endian signed integers (8-bit unsigned for WAVE). + +pub use crate::{pcm_aiff_header as aiff_header, pcm_wav_file as wav_file, pcm_wav_header as wav_header}; + +/// PCM, channels, sample rate and bits of a WAVE file (integer PCM only). +pub fn parse_wav(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + if b.len() < 12 || &b[..4] != b"RIFF" || &b[8..12] != b"WAVE" { + return None; + } + let mut at = 12; + let mut fmt = None; + while at + 8 <= b.len() { + let id = &b[at..at + 4]; + let len = u32::from_le_bytes(b[at + 4..at + 8].try_into().ok()?) as usize; + let body = &b[at + 8..(at + 8).saturating_add(len).min(b.len())]; + if id == b"fmt " && body.len() >= 16 { + let tag = u16::from_le_bytes([body[0], body[1]]); + let ch = u16::from_le_bytes([body[2], body[3]]); + let sr = u32::from_le_bytes(body[4..8].try_into().ok()?); + let bits = u16::from_le_bytes([body[14], body[15]]); + if tag != 1 && tag != 0xFFFE { + return None; + } + if tag == 0xFFFE { + // The first two bytes of the sub-format GUID carry the real format code. + let sub = body.get(24..26)?; + if u16::from_le_bytes([sub[0], sub[1]]) != 1 { + return None; + } + } + fmt = Some((ch, sr, bits)); + } else if id == b"data" { + let (ch, sr, bits) = fmt?; + return Some((body.to_vec(), ch, sr, bits)); + } + at = at.checked_add(8usize.checked_add(len)?.checked_add(len & 1)?)?; + } + None +} + +/// A complete AIFF file (big-endian PCM) from little-endian PCM. +pub fn aiff_file(pcm: &[u8], channels: u16, sample_rate: u32, bits: u16) -> Vec { + let bps = bits.div_ceil(8) as usize; + let frames = pcm.len() / (bps * channels.max(1) as usize).max(1); + let mut v = aiff_header(frames as u32, channels, sample_rate, bits); + for s in pcm.chunks_exact(bps.max(1)) { + if bps == 1 { + v.push(s[0] ^ 0x80); // WAVE 8-bit is unsigned, AIFF signed + } else { + v.extend(s.iter().rev()); + } + } + if (v.len() - 8) & 1 == 1 { + v.push(0); + } + v +} + +/// PCM (converted to little-endian), channels, sample rate and bits of an AIFF / AIFF-C (`NONE` +/// / `twos` / `sowt`) file. +pub fn parse_aiff(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + if b.len() < 12 || &b[..4] != b"FORM" || !(&b[8..12] == b"AIFF" || &b[8..12] == b"AIFC") { + return None; + } + let mut at = 12; + let mut comm = None; + while at + 8 <= b.len() { + let id = &b[at..at + 4]; + let len = u32::from_be_bytes(b[at + 4..at + 8].try_into().ok()?) as usize; + let body = &b[at + 8..(at + 8).saturating_add(len).min(b.len())]; + if id == b"COMM" && body.len() >= 18 { + let ch = u16::from_be_bytes([body[0], body[1]]); + let bits = u16::from_be_bytes([body[6], body[7]]); + let sr = from_extended(body[8..18].try_into().ok()?).round() as u32; + let little = body.len() >= 22 && &body[18..22] == b"sowt"; + comm = Some((ch, sr, bits, little)); + } else if id == b"SSND" && body.len() >= 8 { + let (ch, sr, bits, little) = comm?; + let off = u32::from_be_bytes(body[..4].try_into().ok()?) as usize; + let data = body.get(8usize.checked_add(off)?..)?; + let bps = bits.div_ceil(8) as usize; + let mut pcm = Vec::with_capacity(data.len()); + for s in data.chunks_exact(bps.max(1)) { + if bps == 1 { + pcm.push(s[0] ^ 0x80); + } else if little { + pcm.extend_from_slice(s); + } else { + pcm.extend(s.iter().rev()); + } + } + return Some((pcm, ch, sr, bits)); + } + at = at.checked_add(8usize.checked_add(len)?.checked_add(len & 1)?)?; + } + None +} + +fn from_extended(b: [u8; 10]) -> f64 { + let e = (u16::from_be_bytes([b[0], b[1]]) & 0x7FFF) as i32; + let m = u64::from_be_bytes(b[2..10].try_into().unwrap_or([0; 8])); + if e == 0 && m == 0 { + return 0.0; + } + m as f64 / (1u64 << 63) as f64 * 2f64.powi(e - 16383) +} + +#[cfg(test)] +mod tests { + /// A mutated EDL whose clip ran for days produced an OMF descriptor for more than 4 GiB of + /// PCM: the RIFF size field overflowed ("attempt to add with overflow"). + #[test] + fn huge_wav_header_saturates() { + let h = super::wav_header(u32::MAX, 2, u32::MAX, 24); + assert_eq!(&h[4..8], &u32::MAX.to_le_bytes()); + } + + use super::*; + + #[test] + fn accepts_truncated_essence_summaries() { + let mut wav = wav_file(&[1, 2, 3, 4], 1, 48_000, 16); + wav.truncate(46); + assert_eq!(parse_wav(&wav), Some((vec![1, 2], 1, 48_000, 16))); + let mut aiff = aiff_file(&[1, 2, 3, 4], 1, 48_000, 16); + aiff.truncate(56); + assert_eq!(parse_aiff(&aiff), Some((vec![1, 2], 1, 48_000, 16))); + } + + #[test] + fn wav_and_aiff_round_trip() { + let pcm: Vec = (0..48u8).collect(); // 8 stereo 24-bit frames + let w = wav_file(&pcm, 2, 48_000, 24); + assert_eq!(parse_wav(&w), Some((pcm.clone(), 2, 48_000, 24))); + let a = aiff_file(&pcm, 2, 44_100, 24); + assert_eq!(parse_aiff(&a), Some((pcm.clone(), 2, 44_100, 24))); + let p16: Vec = (0..32u8).collect(); + assert_eq!(parse_aiff(&aiff_file(&p16, 1, 96_000, 16)), Some((p16, 1, 96_000, 16))); + assert!(parse_wav(b"RIFF").is_none()); + assert!(parse_aiff(&a[..30]).is_none()); + for cut in 0..w.len() { + let _ = parse_wav(&w[..cut]); + let _ = parse_aiff(&a[..cut.min(a.len())]); + } + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..7bbfbbcf5 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -66,6 +66,10 @@ mod wav; feature = "vorbis-encode" ))] mod write; + +/// PCM WAVE and AIFF wrappers for interchange essence. +#[cfg(feature = "pcm-encode")] +pub mod essence_pcm; #[cfg(feature = "vorbis-encode")] pub use write::{OGG_BITRATES, encode_ogg}; From 2f2d1d84e3a36b3f93e81507aeff3f0da97a7162 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:51:27 +0000 Subject: [PATCH 021/165] Share bounded SHX glyph program interpreter --- crates/shx/src/lib.rs | 1 + crates/shx/src/program.rs | 443 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 444 insertions(+) create mode 100644 crates/shx/src/program.rs diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs index ce330450c..e330e59fd 100644 --- a/crates/shx/src/lib.rs +++ b/crates/shx/src/lib.rs @@ -5,6 +5,7 @@ mod compile; mod error; pub mod parse; +pub mod program; pub use compile::compile; pub use error::ShxError; pub use parse::{ParsedFont, Record, ShxKind}; diff --git a/crates/shx/src/program.rs b/crates/shx/src/program.rs new file mode 100644 index 000000000..9115d1c6d --- /dev/null +++ b/crates/shx/src/program.rs @@ -0,0 +1,443 @@ +//! The shape pen program: vector length/direction bytes and special codes 0–14, run into +//! polylines. Bounded everywhere: subshape depth, location stack, steps, points, coordinates. +//! +//! - A byte with a non-zero high nibble is a vector: length (high nibble) in one of 16 +//! directions (low nibble, counter-clockwise from east in 22.5° steps; the off-axis ones +//! are half-unit or unit steps on the minor axis). +//! - 0 end, 1 pen down, 2 pen up, 3/4 divide/multiply vector lengths by the next byte, +//! 5/6 push/pop the location, 7 subshape (one byte; two bytes high first in a Unicode font; +//! `0`, a two-byte number, base point, width and height in an extended big font), +//! 8 one X-Y displacement, 9 displacements up to (0,0), 10 octant arc (radius, +//! ±0SC: sign = clockwise, S start octant, C octants, 0 = 8), 11 fractional arc (start +//! offset, end offset, high and low radius, ±0SC; offsets in 1/256 of 45° from the octant +//! boundaries), 12 bulge arc (dx, dy, bulge: ±127 = semicircle), 13 bulge arcs up to (0,0), +//! 14 the next command is for vertical text only (dual-orientation fonts). +//! - Displacements and bulges are two's complement bytes; the arc direction byte keeps its +//! sign in the high bit. + +use std::f64::consts::{FRAC_PI_4, TAU}; + +use super::ShxKind; +use std::ops::{Add, Mul, Neg, Sub}; + +/// A point in SHX font units. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct Point { + pub x: f64, + pub y: f64, +} +impl Point { + pub const ZERO: Self = Self { x: 0.0, y: 0.0 }; + pub const fn new(x: f64, y: f64) -> Self { + Self { x, y } + } + fn is_finite(self) -> bool { + self.x.is_finite() && self.y.is_finite() + } + fn len(self) -> f64 { + self.x.hypot(self.y) + } + fn len2(self) -> f64 { + self.x * self.x + self.y * self.y + } +} +impl Add for Point { + type Output = Self; + fn add(self, rhs: Self) -> Self { + Self::new(self.x + rhs.x, self.y + rhs.y) + } +} +impl Sub for Point { + type Output = Self; + fn sub(self, rhs: Self) -> Self { + Self::new(self.x - rhs.x, self.y - rhs.y) + } +} +impl Mul for Point { + type Output = Self; + fn mul(self, rhs: f64) -> Self { + Self::new(self.x * rhs, self.y * rhs) + } +} +impl Neg for Point { + type Output = Self; + fn neg(self) -> Self { + Self::new(-self.x, -self.y) + } +} + +/// Font records and metrics the bounded shape interpreter needs. +pub trait Font { + fn kind(&self) -> ShxKind; + fn dual(&self) -> bool; + fn above(&self) -> f64; + fn char_width(&self) -> f64; + fn program(&self, number: u16) -> Option<&[u8]>; +} +/// Pen-down strokes and advance in font units. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Glyph { + pub strokes: Vec>, + pub advance: Point, +} + +/// Subshape nesting (a cycle ends here). +const MAX_DEPTH: usize = 16; +/// Location stack (the format promises four). +const MAX_STACK: usize = 64; +/// Bytes run per glyph, subshapes included. +const MAX_STEPS: usize = 200_000; +/// Points per glyph. +const MAX_POINTS: usize = 50_000; +/// Coordinates in font units. +const MAX_COORD: f64 = 1.0e7; +/// Arc segments per full turn. +const ARC_STEPS: f64 = 64.0; + +/// Why a program stops early: the glyph is then not drawn. +#[derive(Debug)] +pub struct Broken; + +type Res = Result<(), Broken>; + +struct Pen<'a> { + font: &'a dyn Font, + vertical: bool, + pos: Point, + down: bool, + /// Vector length factor (codes 3 and 4). + scale: f64, + /// Per-axis factor of an extended big font subshape. + axes: Point, + stack: Vec, + strokes: Vec>, + active: Vec, + steps: usize, + points: usize, +} + +pub fn outline(font: &dyn Font, number: u16, vertical: bool) -> Result { + let mut pen = Pen { + font, + vertical, + pos: Point::ZERO, + down: true, + scale: 1.0, + axes: Point::new(1.0, 1.0), + stack: Vec::new(), + strokes: Vec::new(), + active: Vec::new(), + steps: 0, + points: 0, + }; + pen.run(number, 0)?; + pen.flush(); + Ok(Glyph { strokes: pen.strokes, advance: pen.pos }) +} + +/// The 16 vector directions (unit length on the major axis). +fn direction(d: u8) -> Point { + let (x, y) = match d & 15 { + 0 => (1.0, 0.0), + 1 => (1.0, 0.5), + 2 => (1.0, 1.0), + 3 => (0.5, 1.0), + 4 => (0.0, 1.0), + 5 => (-0.5, 1.0), + 6 => (-1.0, 1.0), + 7 => (-1.0, 0.5), + 8 => (-1.0, 0.0), + 9 => (-1.0, -0.5), + 10 => (-1.0, -1.0), + 11 => (-0.5, -1.0), + 12 => (0.0, -1.0), + 13 => (0.5, -1.0), + 14 => (1.0, -1.0), + _ => (1.0, -0.5), + }; + Point::new(x, y) +} + +/// A two's complement operand byte. +fn signed(b: u8) -> f64 { + f64::from(i8::from_le_bytes([b])) +} + +/// A program being read: its bytes and position. +struct Cur<'p> { + b: &'p [u8], + pos: usize, +} + +impl Cur<'_> { + fn byte(&mut self) -> Result { + let v = self.b.get(self.pos).copied().ok_or(Broken)?; + self.pos += 1; + Ok(v) + } +} + +impl Pen<'_> { + fn step(&mut self) -> Res { + self.steps += 1; + if self.steps > MAX_STEPS { Err(Broken) } else { Ok(()) } + } + + fn flush(&mut self) { + if self.active.len() >= 2 { + self.strokes.push(std::mem::take(&mut self.active)); + } else { + self.active.clear(); + } + } + + /// Move the pen by `d` font units (already scaled), drawing when the pen is down. + fn to(&mut self, target: Point) -> Res { + if !target.is_finite() || target.x.abs().max(target.y.abs()) > MAX_COORD { + return Err(Broken); + } + if self.down { + if self.active.is_empty() { + self.active.push(self.pos); + self.points += 1; + } + self.active.push(target); + self.points += 1; + if self.points > MAX_POINTS { + return Err(Broken); + } + } else { + self.flush(); + } + self.pos = target; + Ok(()) + } + + /// A displacement in vector units (times the length factor and the subshape axes). + fn by(&mut self, d: Point) -> Res { + let k = d * self.scale; + self.to(self.pos + Point::new(k.x * self.axes.x, k.y * self.axes.y)) + } + + /// An arc of `radius` vector units from the pen, starting at angle `start` on its circle + /// and turning `sweep` radians (positive counter-clockwise). + fn arc(&mut self, radius: f64, start: f64, sweep: f64) -> Res { + let r = radius * self.scale; + if !(r.is_finite() && r > 0.0 && sweep.is_finite()) { + return Ok(()); + } + let n = if self.down { (sweep.abs() / TAU * ARC_STEPS).ceil().clamp(1.0, ARC_STEPS) as usize } else { 1 }; + let from = self.pos; + let s0 = Point::new(start.cos(), start.sin()); + for i in 1..=n { + let a = start + sweep * i as f64 / n as f64; + let d = (Point::new(a.cos(), a.sin()) - s0) * r; + self.to(from + Point::new(d.x * self.axes.x, d.y * self.axes.y))?; + } + Ok(()) + } + + /// An arc to the displacement `d` with `bulge` (−127..127, ±127 a semicircle). + fn bulge(&mut self, d: Point, bulge: f64) -> Res { + let b = bulge.clamp(-127.0, 127.0) / 127.0; + if b == 0.0 || !self.down || d.len2() == 0.0 { + return self.by(d); + } + // Centre from the chord midpoint along its left normal; sweep 4·atan(b). + let centre = d * 0.5 + Point::new(-d.y, d.x) * ((1.0 - b * b) / (4.0 * b)); + let rel = -centre; + self.arc(rel.len(), rel.y.atan2(rel.x), 4.0 * b.atan()) + } + + /// The octant byte `±0SC`: (clockwise, start octant, octants with 0 = 8). + fn octants(spec: u8) -> (f64, f64, f64) { + let sign = if spec & 0x80 != 0 { -1.0 } else { 1.0 }; + let s = f64::from((spec >> 4) & 7); + let c = match spec & 7 { + 0 => 8.0, + c => f64::from(c), + }; + (sign, s, c) + } + + /// The vector unit size of an extended big font's subshape cell. + fn cell(&self) -> Point { + let h = if self.font.above() > 0.0 { self.font.above() } else { 1.0 }; + let w = if self.font.char_width() > 0.0 { self.font.char_width() } else { h }; + Point::new(w, h) + } + + fn run(&mut self, number: u16, depth: usize) -> Res { + if depth >= MAX_DEPTH { + return Err(Broken); + } + let program = self.font.program(number).ok_or(Broken)?; + let mut r = Cur { b: program, pos: 0 }; + let mut skip = false; + while r.pos < r.b.len() { + self.step()?; + let code = r.byte()?; + // Code 14: in a dual-orientation font the next command is for vertical text only. + let exec = !skip; + skip = false; + match code { + 0 => return Ok(()), + 1 if exec => self.down = true, + 2 if exec => { + self.down = false; + self.flush(); + } + 3 | 4 => { + let k = f64::from(r.byte()?); + if exec && k > 0.0 { + let s = if code == 3 { self.scale / k } else { self.scale * k }; + if !(1e-9..=MAX_COORD).contains(&s) { + return Err(Broken); + } + self.scale = s; + } + } + 5 if exec => { + if self.stack.len() >= MAX_STACK { + return Err(Broken); + } + self.stack.push(self.pos); + } + 6 if exec => { + self.flush(); + if let Some(p) = self.stack.pop() { + self.pos = p; + } + } + 7 => self.subshape(&mut r, exec, depth)?, + 8 | 9 | 12 | 13 => loop { + self.step()?; + let d = Point::new(signed(r.byte()?), signed(r.byte()?)); + if matches!(code, 9 | 13) && d == Point::ZERO { + break; + } + let bulge = if matches!(code, 12 | 13) { signed(r.byte()?) } else { 0.0 }; + if exec { + self.bulge(d, bulge)?; + } + if matches!(code, 8 | 12) { + break; + } + }, + 10 => { + let radius = f64::from(r.byte()?); + let (sign, s, c) = Self::octants(r.byte()?); + if exec { + self.arc(radius, s * FRAC_PI_4, sign * c * FRAC_PI_4)?; + } + } + 11 => { + let start = f64::from(r.byte()?) / 256.0; + let end = match r.byte()? { + 0 => 1.0, + e => f64::from(e) / 256.0, + }; + let radius = f64::from(u16::from_be_bytes([r.byte()?, r.byte()?])); + let (sign, s, c) = Self::octants(r.byte()?); + if exec { + // From `start` past the first octant boundary to `end` past the last + // octant's. + self.arc(radius, (s + sign * start) * FRAC_PI_4, sign * (c - 1.0 + end - start) * FRAC_PI_4)?; + } + } + 14 => skip = self.font.dual() && !self.vertical && exec, + 1..=15 => {} + v => { + if exec { + self.by(direction(v) * f64::from(v >> 4))?; + } + } + } + } + Ok(()) + } + + /// Code 7 and its operands. + fn subshape(&mut self, r: &mut Cur, exec: bool, depth: usize) -> Res { + match self.font.kind() { + ShxKind::Unifont => { + let n = u16::from_be_bytes([r.byte()?, r.byte()?]); + if exec { + self.run(n, depth + 1)?; + } + } + ShxKind::BigFont => { + let first = r.byte()?; + if first != 0 { + if exec { + self.run(u16::from(first), depth + 1)?; + } + return Ok(()); + } + // Extended: the primitive drawn in the box (x, y, width, height) of the cell. + let n = u16::from_be_bytes([r.byte()?, r.byte()?]); + let (x, y, w, h) = (f64::from(r.byte()?), f64::from(r.byte()?), f64::from(r.byte()?), f64::from(r.byte()?)); + if !exec { + return Ok(()); + } + let (pos, axes, down) = (self.pos, self.axes, self.down); + let cell = self.cell(); + self.flush(); + self.pos = pos + Point::new(x * axes.x, y * axes.y) * self.scale; + self.axes = Point::new(axes.x * w / cell.x, axes.y * h / cell.y); + let res = self.run(n, depth + 1); + self.flush(); + self.axes = axes; + self.pos = pos; + self.down = down; + res?; + } + ShxKind::Shapes => { + let n = u16::from(r.byte()?); + if exec { + self.run(n, depth + 1)?; + } + } + } + Ok(()) + } +} + +impl Font for crate::ParsedFont { + fn kind(&self) -> ShxKind { + self.kind + } + fn dual(&self) -> bool { + self.dual + } + fn above(&self) -> f64 { + self.above + } + fn char_width(&self) -> f64 { + self.char_width + } + fn program(&self, number: u16) -> Option<&[u8]> { + let r = self.records.get(&number)?; + self.data.get(r.program.0..r.program.1) + } +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + #[test] + fn executes_shape_vectors_without_app_geometry_types() { + let bytes = crate::compile("*1,3,A\n1,010,0\n").unwrap(); + let font = crate::parse::parse(&bytes).unwrap(); + let glyph = outline(&font, 1, false).unwrap(); + assert_eq!(glyph.strokes, vec![vec![Point::new(0.0, 0.0), Point::new(1.0, 0.0)]]); + assert_eq!(glyph.advance, Point::new(1.0, 0.0)); + } + #[test] + fn recursive_shapes_stop_at_the_depth_bound() { + let bytes = crate::compile("*1,3,A\n7,1,0\n").unwrap(); + let font = crate::parse::parse(&bytes).unwrap(); + assert!(outline(&font, 1, false).is_err()); + } +} From 5a36112af6567a60491c47361a9fdd44ad362979 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 16:51:49 +0100 Subject: [PATCH 022/165] craft-image-codecs: SGI rows may share compressed data and must start after the offset tables Addresses review findings: the RLE size check no longer demands separate payload space for every row, and a row offset inside the offset tables is refused. A row without its trailing zero count still reads, as in ffmpeg. --- crates/image-codecs/src/codecs/sgi.rs | 56 +++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/crates/image-codecs/src/codecs/sgi.rs b/crates/image-codecs/src/codecs/sgi.rs index 1e31b5f0a..64c80299c 100644 --- a/crates/image-codecs/src/codecs/sgi.rs +++ b/crates/image-codecs/src/codecs/sgi.rs @@ -120,8 +120,9 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { // Reject inputs that cannot hold the declared pixels before allocating anything for them. let table = if h.rle { rows.checked_mul(8).ok_or_else(|| bad("image size overflow"))? } else { 0 }; let min_len = if h.rle { - // Every row needs at least a packet and a terminator. - HEADER + table + rows * bps + // Both offset tables must fit; rows may share compressed data, so the data itself is + // checked row by row against the offsets below. + HEADER + table } else { HEADER + total.checked_mul(bps).ok_or_else(|| bad("image size overflow"))? }; @@ -138,7 +139,10 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { if h.rle { let start = be32(b, HEADER + index * 4) as usize; let len = be32(b, HEADER + rows * 4 + index * 4) as usize; - let end = start.checked_add(len).filter(|&e| e <= b.len() && start >= HEADER).ok_or_else(|| bad("RLE row lies outside the file"))?; + let end = start + .checked_add(len) + .filter(|&e| e <= b.len() && start >= HEADER + table) + .ok_or_else(|| bad("RLE row lies outside the file"))?; read_rle_row(&b[start..end], h.wide, &mut row)?; } else { let start = HEADER + index * w * bps; @@ -335,6 +339,52 @@ mod tests { assert!(decode(&huge, &Limits::default()).is_err()); } + /// A 1-plane, 8-bit RLE file whose `rows` all start where `starts[i]` says, each `len` bytes long. + fn rle_file(w: u16, starts: &[u32], len: u32, payload: &[u8]) -> Vec { + let mut f = vec![0u8; HEADER]; + f[0..2].copy_from_slice(&MAGIC.to_be_bytes()); + f[2] = 1; + f[3] = 1; + f[4..6].copy_from_slice(&2u16.to_be_bytes()); + f[6..8].copy_from_slice(&w.to_be_bytes()); + f[8..10].copy_from_slice(&(starts.len() as u16).to_be_bytes()); + f[10..12].copy_from_slice(&1u16.to_be_bytes()); + for s in starts { + f.extend_from_slice(&s.to_be_bytes()); + } + for _ in starts { + f.extend_from_slice(&len.to_be_bytes()); + } + f.extend_from_slice(payload); + f + } + + /// The format lets table entries share one compressed row: eight rows, one payload. + #[test] + fn rows_may_share_compressed_data() { + let table = HEADER + 8 * 8; + let f = rle_file(1, &[table as u32; 8], 3, &[0x81, 255, 0]); + assert_eq!(f.len(), table + 3); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.dimensions(), img.data()), ((1, 8), &[255u8; 8][..])); + } + + /// Compressed rows start after both tables: an offset into a table is refused. + #[test] + fn rows_may_not_start_inside_the_offset_tables() { + // 3x1: the tables end at 520; 515 reads the table's own bytes as a packet list. + let f = rle_file(3, &[515], 3, &[0, 0, 0, 0, 0]); + assert!(decode(&f, &Limits::default()).is_err()); + } + + /// FFmpeg's decoder, run as an oracle, also reads a row that ends with its last packet and no + /// zero terminator; so does this one. + #[test] + fn a_row_without_its_terminator_still_reads() { + let f = rle_file(1, &[520], 2, &[0x81, 42]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[42]); + } + #[test] fn palette_mapped_files_are_unsupported() { let img = gradient(4, 4, ChannelLayout::Gray); From e9eaaf5641640b4e2735b0af79ef589c5a74a88a Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 16:52:35 +0100 Subject: [PATCH 023/165] craft-image-codecs: Sun Raster 1-bit colour maps, opaque standard 32-bit pixels, fallible output buffer Addresses review findings: a 1-bit file with an RGB colour map reads as colour; the unused first byte of standard 32-bit pixels is no longer read as alpha; the writer's buffer is reserved with try_reserve_exact. README lists the native layouts correctly. --- crates/image-codecs/README.md | 2 +- crates/image-codecs/src/codecs/sunraster.rs | 52 +++++++++++++++++++-- 2 files changed, 49 insertions(+), 5 deletions(-) diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index f9f5f53e6..a37760d80 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -56,7 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "< | Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in | | DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in | | Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in | -| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, Gray+A, RGB, RGBA | yes | no | no | no | no | no | no | built in | +| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, RGB, RGBA | yes | no | no | no | no | no | no | built in | | AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` | | HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` | diff --git a/crates/image-codecs/src/codecs/sunraster.rs b/crates/image-codecs/src/codecs/sunraster.rs index 84d60f145..85c24acc5 100644 --- a/crates/image-codecs/src/codecs/sunraster.rs +++ b/crates/image-codecs/src/codecs/sunraster.rs @@ -97,9 +97,18 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { for x in 0..wu { match depth { 1 => { - // A set bit is black. let bit = (row[x / 8] >> (7 - x % 8)) & 1; - out.push(if bit == 1 { 0 } else { 255 }); + if map_type == 1 { + // The bit is an index into the (two-entry or longer) colour map. + let i = usize::from(bit); + if i >= entries { + return Err(bad("pixel index is outside the colour map")); + } + out.extend_from_slice(&[map[i], map[entries + i], map[2 * entries + i]]); + } else { + // A set bit is black. + out.push(if bit == 1 { 0 } else { 255 }); + } } 8 if map_type == 1 => { let i = usize::from(row[x]); @@ -115,7 +124,8 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { } _ => { let p = &row[4 * x..4 * x + 4]; - out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], p[0]] }); + // In the standard types the first byte (X in XBGR) is unused, not alpha. + out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], 255] }); } } } @@ -123,6 +133,13 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { Image::from_u8(w, h, layout, out) } +/// A buffer of `cap` bytes, or an error instead of an abort when the allocation cannot be made. +fn reserve(cap: usize) -> std::result::Result, std::collections::TryReserveError> { + let mut v = Vec::new(); + v.try_reserve_exact(cap)?; + Ok(v) +} + /// Writes an uncompressed rasterfile: 8-bit gray, 24-bit RGB or 32-bit RGBA, in the RGB-ordered type. pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { let enc = |msg: String| CodecError::encode(F, msg); @@ -145,7 +162,8 @@ pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { if data.len() != wu * hu * bytes { return Err(enc("the image has the wrong number of samples".into())); } - let mut out = Vec::with_capacity(HEADER + len as usize); + let mut out = reserve(HEADER.checked_add(len as usize).ok_or_else(|| enc("image too large".into()))?) + .map_err(|_| enc("the image is too large to encode".into()))?; for v in [MAGIC, w, h, depth as u32, len, 3, 0, 0] { out.extend_from_slice(&v.to_be_bytes()); } @@ -218,6 +236,32 @@ mod tests { assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0, 255, 0]); } + #[test] + fn one_bit_files_with_a_colour_map_read_as_colour() { + // Two entries: red plane, green plane, blue plane; bit 0 is entry 0. + let map = [10, 20, 30, 40, 50, 60]; + let f = file(1, 1, &map, 1, 3, 1, &[0b0100_0000, 0]); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10, 30, 50, 20, 40, 60, 10, 30, 50][..])); + // A one-entry map has no entry for a set bit. + assert!(decode(&file(1, 1, &[1, 2, 3], 1, 1, 1, &[0b1000_0000, 0]), &Limits::default()).is_err()); + } + + #[test] + fn the_unused_first_byte_of_standard_32_bit_pixels_is_not_alpha() { + let img = decode(&file(32, 1, &[], 0, 1, 1, &[0, 30, 20, 10]), &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgba, &[10, 20, 30, 255][..])); + // In the RGB-ordered type the first byte is the alpha the writer stores there. + let img = decode(&file(32, 3, &[], 0, 1, 1, &[7, 10, 20, 30]), &Limits::default()).unwrap(); + assert_eq!(img.data(), &[10, 20, 30, 7]); + } + + #[test] + fn an_output_buffer_too_large_to_allocate_is_an_error() { + assert!(reserve(usize::MAX).is_err()); + assert!(reserve(16).is_ok()); + } + #[test] fn hostile_input_is_an_error_not_a_panic() { let img = pattern(9, 5, ChannelLayout::Rgb); From 8ce5335e8fc93c4e9546286390a0b0d35897585a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:53:30 +0000 Subject: [PATCH 024/165] aaf: preserve bounded FilmCraft OMF traversal --- crates/aaf/src/lib.rs | 4 + crates/aaf/src/omf/read.rs | 255 +++++++++++++++++++++++++++++++++++-- crates/aaf/src/pcm.rs | 5 - 3 files changed, 248 insertions(+), 16 deletions(-) diff --git a/crates/aaf/src/lib.rs b/crates/aaf/src/lib.rs index ee7448bc0..4968c5b39 100644 --- a/crates/aaf/src/lib.rs +++ b/crates/aaf/src/lib.rs @@ -29,7 +29,11 @@ mod roundtrip_tests; #[cfg(test)] mod testdoc; +/// Diagnostic types used by readers and writers. +pub use craft_timeline::report; pub use craft_timeline::report::Report; +/// Exact time types used by the composition model. +pub use craft_timeline::time; /// Error from a reader or writer. Unsupported *features* never error; they go in the [`Report`]. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] diff --git a/crates/aaf/src/omf/read.rs b/crates/aaf/src/omf/read.rs index d45b6ff63..b9c3bd9d1 100644 --- a/crates/aaf/src/omf/read.rs +++ b/crates/aaf/src/omf/read.rs @@ -12,6 +12,10 @@ type Uid = [u8; 12]; const MAX_REFERENCE_VISITS: usize = 65_536; +/// A source-clip search stopped at its work limit. +#[derive(Clone, Copy)] +struct SearchLimit; + struct R<'a, 'b> { c: &'b Container<'a>, report: &'b mut Report, @@ -21,15 +25,43 @@ struct R<'a, 'b> { media: HashMap>, doc: Document, sources: HashMap<(Uid, u32, String), usize>, + /// Component visits left for [`R::segment`] over the whole document. + budget: usize, + /// Outcome of the source-clip search under each segment: deterministic, so it is made once. + clip_search: HashMap, SearchLimit>>, } +/// Components one document may expand into timeline items; a small file can reference the same +/// sequence from many places and would otherwise multiply without bound. +const MAX_COMPONENT_VISITS: usize = 1_000_000; + +/// Reported when the shared component budget runs out. +const BUDGET_WARNING: &str = "OMF composition is too large to import completely (the remaining components are dropped)"; +/// Most visited components, and most queued references, one source-clip search may spend. +const MAX_CLIP_SEARCH_VISITS: usize = 100_000; +const MAX_CLIP_SEARCH_PENDING: usize = 1_000_000; + pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { + read_with_budget(bytes, report, MAX_COMPONENT_VISITS) +} + +fn read_with_budget(bytes: &[u8], report: &mut Report, budget: usize) -> Result { let perr = |m: String| Error::Parse { format: "OMF", message: m }; let c = Container::open(bytes).map_err(perr)?; let class_of = |o: u32| c.get(o, "OMFI:OOBJ:ObjClass").and_then(|v| v.get(..4).map(|b| [b[0], b[1], b[2], b[3]])); let head = c.objects.keys().copied().find(|&o| class_of(o) == Some(*b"HEAD")).ok_or_else(|| perr("no OMF header object".into()))?; let be = c.get(head, "OMFI:HEAD:ByteOrder").is_none_or(|v| v.first() != Some(&0x49)); - let mut r = R { c: &c, report, be, mobs: HashMap::new(), media: HashMap::new(), doc: Document::default(), sources: HashMap::new() }; + let mut r = R { + c: &c, + report, + be, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget, + clip_search: HashMap::new(), + }; let mob_list = r.refs(head, "OMFI:HEAD:Mobs"); let mob_list = if mob_list.is_empty() { c.objects.keys().copied().filter(|&o| matches!(class_of(o).as_ref(), Some(b"CMOB" | b"MMOB" | b"SMOB"))).collect() @@ -66,8 +98,14 @@ pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { cmobs.iter().copied().filter(|m| r.uid(*m, "OMFI:MOBJ:MobID").is_none_or(|id| !referenced.contains(&id))).collect() }; for m in top { + // every composition spends from the budget too: a list of up to 65,535 repeated entries must not yield that many + if r.budget == 0 && !r.doc.compositions.is_empty() { + r.report.warn(BUDGET_WARNING); + break; + } let comp = r.composition(m); r.doc.compositions.push(comp); + r.budget = r.budget.saturating_sub(1); } if r.doc.compositions.is_empty() { return Err(Error::Empty); @@ -166,6 +204,13 @@ impl R<'_, '_> { let slots = self.refs(m, "OMFI:MOBJ:Slots"); let mut na = 0; for s in slots { + if self.budget == 0 { + self.report.warn(BUDGET_WARNING); + break; + } + // Every slot spends a unit, skipped ones too: a list of up to 65,535 repeated slots + // must not cost that much work in each of 65,535 repeated compositions. + self.budget -= 1; let Some(seg) = self.r#ref(s, "OMFI:MSLT:Segment") else { continue }; let rate = self.rational(s, "OMFI:MSLT:EditRate").filter(|r| r.0 > 0 && r.1 > 0).unwrap_or((25, 1)); let kind = self.data_kind(seg); @@ -213,9 +258,15 @@ impl R<'_, '_> { fn segment(&mut self, seg: u32, rate: (i64, i64), depth: usize) -> Vec { let len = units_to_ticks(self.len(seg), rate.0, rate.1); - if depth > 32 { + // Depth alone does not bound a graph that references the same component many times at + // every level, so each visit also spends from a per-document budget. + if depth > 32 || self.budget == 0 { + if self.budget == 0 { + self.report.warn(BUDGET_WARNING); + } return vec![CItem::Filler(len)]; } + self.budget -= 1; match &self.class(seg) { b"SEQU" => { let mut out = Vec::new(); @@ -306,12 +357,44 @@ impl R<'_, '_> { .find(|&s| self.r#ref(s, "OMFI:MSLT:TrackDesc").and_then(|t| self.u32(t, "OMFI:TRKD:TrackID")) == Some(track)) } - fn first_clip(&self, seg: u32) -> Option { - match &self.class(seg) { - b"SCLP" => Some(seg), - b"SEQU" => self.refs(seg, "OMFI:SEQU:Components").into_iter().find_map(|c| self.first_clip(c)), - _ => None, + /// First source clip under `seg`, depth-first; a sequence referencing itself (directly or + /// through a cycle) ends the search rather than the stack. `Err` when the search spent its + /// budget of visited components or queued references before finishing (the answer is unknown). + fn first_clip(&mut self, seg: u32) -> std::result::Result, SearchLimit> { + if let Some(found) = self.clip_search.get(&seg) { + return *found; } + let found = self.first_clip_within(seg, MAX_CLIP_SEARCH_VISITS, MAX_CLIP_SEARCH_PENDING); + self.clip_search.insert(seg, found); + found + } + + fn first_clip_within(&self, seg: u32, max_visits: usize, max_pending: usize) -> std::result::Result, SearchLimit> { + let mut visited = HashSet::new(); + let mut todo = vec![seg]; + let mut queued = 1usize; + while let Some(seg) = todo.pop() { + if !visited.insert(seg) { + continue; + } + if visited.len() > max_visits { + return Err(SearchLimit); + } + match &self.class(seg) { + b"SCLP" => return Ok(Some(seg)), + b"SEQU" => { + let comps = self.refs(seg, "OMFI:SEQU:Components"); + // sequences may share one component list, so queued references grow with expansions, not visits + queued = queued.saturating_add(comps.len()); + if queued > max_pending { + return Err(SearchLimit); + } + todo.extend(comps.into_iter().rev()); + } + _ => {} + } + } + Ok(None) } fn resolve(&mut self, id: Uid, track: u32, start: Tick, master: Option, depth: usize) -> Option<(usize, Tick)> { @@ -328,7 +411,13 @@ impl R<'_, '_> { match &self.class(mob) { b"MMOB" => { let key = master.unwrap_or_else(|| id.iter().map(|b| format!("{b:02x}")).collect()); - let clip = self.first_clip(seg)?; + let clip = match self.first_clip(seg) { + Ok(c) => c?, + Err(SearchLimit) => { + self.report.warn("a master mob is too large to search for its source clip (imported as a gap)"); + return None; + } + }; let inner = units_to_ticks(self.i32(clip, "OMFI:SCLP:StartTime").unwrap_or(0), rate.0, rate.1); let next = self.uid(clip, "OMFI:SCLP:SourceID")?; let next_track = self.u32(clip, "OMFI:SCLP:SourceTrackID")?; @@ -353,7 +442,9 @@ impl R<'_, '_> { let file_rate = sr.filter(|r| r.0 > 0 && r.1 > 0).unwrap_or(rate); let length = units_to_ticks(self.i32(desc, "OMFI:MDFL:Length").unwrap_or(0), file_rate.0, file_rate.1); let summary = self.c.get(desc, "OMFI:WAVD:Summary").or_else(|| self.c.get(desc, "OMFI:AIFD:Summary")).unwrap_or_default(); - let fmt = crate::pcm::parse_wav(&summary).or_else(|| crate::pcm::parse_aiff(&summary)).map(|(_, ch, sr, bits)| (ch as u32, sr, bits)); + let fmt = craft_audio::essence_pcm::parse_wav(&summary) + .or_else(|| craft_audio::essence_pcm::parse_aiff(&summary)) + .map(|(_, ch, sr, bits)| (ch as u32, sr, bits)); let mut path = None; for l in self.refs(desc, "OMFI:MDES:Locator") { let p = match &self.class(l) { @@ -373,7 +464,8 @@ impl R<'_, '_> { let (file_channels, sample_rate, bits) = fmt.unwrap_or((1, file_rate.0 as u32, 16)); let channel = (file_channels > 1 && sound_slots > 1).then(|| track.saturating_sub(1).min(file_channels - 1)); // timecode of the physical source - let tc = self.first_clip(seg).and_then(|clip| { + let first = self.first_clip(seg).ok().flatten(); + let tc = first.and_then(|clip| { let tid = self.uid(clip, "OMFI:SCLP:SourceID")?; let tape = *self.mobs.get(&tid)?; let (start_tc, fps, trate) = self.refs(tape, "OMFI:MOBJ:Slots").into_iter().find_map(|s| { @@ -415,7 +507,7 @@ impl R<'_, '_> { nested: None, }; if let Some(d) = self.media.get(&id) { - if let Some((pcm, ch, sr, b)) = crate::pcm::parse_wav(d).or_else(|| crate::pcm::parse_aiff(d)) { + if let Some((pcm, ch, sr, b)) = craft_audio::essence_pcm::parse_wav(d).or_else(|| craft_audio::essence_pcm::parse_aiff(d)) { s.embedded = Some(pcm); s.file_channels = ch as u32; s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; @@ -437,3 +529,144 @@ impl R<'_, '_> { } } } + +#[cfg(test)] +mod tests { + use super::super::bento::Writer; + use super::*; + + fn obj(w: &mut Writer, class: &[u8; 4]) -> u32 { + let id = w.new_object(); + w.set(id, "OMFI:OOBJ:ObjClass", "omfi:ClassID", class); + id + } + fn list(w: &mut Writer, o: u32, p: &str, targets: &[u32]) { + let mut v = (targets.len() as u16).to_be_bytes().to_vec(); + for t in targets { + v.extend_from_slice(&t.to_be_bytes()); + } + w.set(o, p, "omfi:ObjRefArray", &v); + } + + fn search(max_visits: usize, max_pending: usize, build: impl FnOnce(&mut Writer) -> u32) -> std::result::Result, SearchLimit> { + let mut w = Writer::new(); + let root = build(&mut w); + let bytes = w.finish(); + let c = Container::open(&bytes).unwrap(); + let mut report = Report::default(); + let r = R { + c: &c, + report: &mut report, + be: true, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget: 0, + clip_search: HashMap::new(), + }; + r.first_clip_within(root, max_visits, max_pending) + } + + #[test] + fn clip_search_reports_its_limits() { + // found within the limits + assert!(matches!( + search(10, 10, |w| { + let (s, c) = (obj(w, b"SEQU"), obj(w, b"SCLP")); + list(w, s, "OMFI:SEQU:Components", &[c]); + s + }), + Ok(Some(_)) + )); + // too many distinct components before any clip + assert!( + search(5, 1000, |w| { + let (s, f) = (obj(w, b"SEQU"), (0..20).map(|_| obj(w, b"FILL")).collect::>()); + list(w, s, "OMFI:SEQU:Components", &f); + s + }) + .is_err() + ); + // few visits, but sequences that each queue a long list of references + assert!( + search(1000, 500, |w| { + let f = obj(w, b"FILL"); + let inner: Vec = (0..20).map(|_| obj(w, b"SEQU")).collect(); + for &i in &inner { + list(w, i, "OMFI:SEQU:Components", &[f; 100]); + } + let s = obj(w, b"SEQU"); + list(w, s, "OMFI:SEQU:Components", &inner); + s + }) + .is_err() + ); + // a search that ends without a clip is not a limit + assert!(matches!(search(10, 10, |w| obj(w, b"FILL")), Ok(None))); + } + + #[test] + fn skipped_slots_spend_the_budget() { + let mut w = Writer::new(); + let head = obj(&mut w, b"HEAD"); + let cm = obj(&mut w, b"CMOB"); + let slot = obj(&mut w, b"MSLT"); + list(&mut w, cm, "OMFI:MOBJ:Slots", &[slot; 200]); + list(&mut w, head, "OMFI:HEAD:Mobs", &[cm]); + list(&mut w, head, "OMFI:HEAD:PrimaryMobs", &[cm]); + let bytes = w.finish(); + let mut report = Report::default(); + read_with_budget(&bytes, &mut report, 50).unwrap(); + assert!(report.mentions(BUDGET_WARNING), "slots with no segment cost nothing before"); + } + + #[test] + fn a_source_clip_search_is_made_once_per_segment() { + let mut w = Writer::new(); + let (s, c) = (obj(&mut w, b"SEQU"), obj(&mut w, b"SCLP")); + list(&mut w, s, "OMFI:SEQU:Components", &[c]); + let bytes = w.finish(); + let c = Container::open(&bytes).unwrap(); + let mut report = Report::default(); + let mut r = R { + c: &c, + report: &mut report, + be: true, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget: 0, + clip_search: HashMap::new(), + }; + let first = r.first_clip(s).ok(); + assert!(matches!(first, Some(Some(_)))); + assert_eq!(r.clip_search.len(), 1); + assert_eq!(r.first_clip(s).ok(), first); + assert_eq!(r.clip_search.len(), 1); + } + + #[test] + fn repeated_slots_and_compositions_spend_the_budget() { + let mut w = Writer::new(); + let head = obj(&mut w, b"HEAD"); + let cm = obj(&mut w, b"CMOB"); + let dd = obj(&mut w, b"DDEF"); + w.set(dd, "OMFI:DDEF:DataKindID", "omfi:UniqueName", b"omfi:data:Sound\0"); + let fill = obj(&mut w, b"FILL"); + w.set(fill, "OMFI:CPNT:DataKind", "omfi:ObjRef", &dd.to_be_bytes()); + let slot = obj(&mut w, b"MSLT"); + w.set(slot, "OMFI:MSLT:Segment", "omfi:ObjRef", &fill.to_be_bytes()); + list(&mut w, cm, "OMFI:MOBJ:Slots", &[slot; 200]); + list(&mut w, head, "OMFI:HEAD:Mobs", &[cm]); + list(&mut w, head, "OMFI:HEAD:PrimaryMobs", &[cm; 200]); + let bytes = w.finish(); + let mut report = Report::default(); + let doc = read_with_budget(&bytes, &mut report, 50).unwrap(); + let tracks: usize = doc.compositions.iter().map(|c| c.tracks.len()).sum(); + assert!(tracks <= 50, "{tracks} tracks from a budget of 50"); + assert!(doc.compositions.len() <= 2, "{} compositions", doc.compositions.len()); + assert!(report.has_warnings()); + } +} diff --git a/crates/aaf/src/pcm.rs b/crates/aaf/src/pcm.rs index 789c976a8..9992b2d3b 100644 --- a/crates/aaf/src/pcm.rs +++ b/crates/aaf/src/pcm.rs @@ -4,8 +4,3 @@ pub(crate) fn parse_wav(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { craft_audio::wav_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) } - -/// The same for an AIFF / AIFF-C (`NONE`, `twos`, `sowt`) file. -pub(crate) fn parse_aiff(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { - craft_audio::aiff_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) -} From 52a6dd6aa7aadf7a57f715135ec1dcbc51088515 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:46:32 +0000 Subject: [PATCH 025/165] aaf: expose bounded Bento container access --- crates/aaf/src/omf.rs | 2 +- crates/aaf/src/omf/bento.rs | 25 ++++++++++++++++++------- crates/aaf/tests/bento_api.rs | 17 +++++++++++++++++ 3 files changed, 36 insertions(+), 8 deletions(-) create mode 100644 crates/aaf/tests/bento_api.rs diff --git a/crates/aaf/src/omf.rs b/crates/aaf/src/omf.rs index 57e0f756c..bbd2e8571 100644 --- a/crates/aaf/src/omf.rs +++ b/crates/aaf/src/omf.rs @@ -21,7 +21,7 @@ //! transition's name) are not in the specification; they were first written by FilmCraft and keep //! their names so that existing files read back. -pub(crate) mod bento; +pub mod bento; mod read; mod write; diff --git a/crates/aaf/src/omf/bento.rs b/crates/aaf/src/omf/bento.rs index 00a7e2a26..171196fe1 100644 --- a/crates/aaf/src/omf/bento.rs +++ b/crates/aaf/src/omf/bento.rs @@ -35,8 +35,8 @@ use std::collections::{BTreeMap, HashMap}; -pub(crate) const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; -pub(crate) const LABEL_SIZE: usize = 24; +pub const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; +pub const LABEL_SIZE: usize = 24; // standard object ids const TOC_OBJECT: u32 = 1; @@ -82,7 +82,7 @@ const MAX_VALUE_BYTES: usize = 16 << 20; const MAX_NAME_BYTES: usize = 4 << 20; /// Builds a Bento container. -pub(crate) struct Writer { +pub struct Writer { data: Vec, names: HashMap<(u32, String), u32>, next: u32, @@ -90,6 +90,12 @@ pub(crate) struct Writer { entries: Vec<(u32, u32, u32, Vec)>, } +impl Default for Writer { + fn default() -> Self { + Self::new() + } +} + impl Writer { pub fn new() -> Writer { Writer { data: Vec::new(), names: HashMap::new(), next: MIN_USER_ID, entries: Vec::new() } @@ -217,9 +223,9 @@ pub(crate) struct Prop { } /// A parsed Bento container. -pub(crate) struct Container<'a> { +pub struct Container<'a> { data: &'a [u8], - pub objects: BTreeMap>, + pub(crate) objects: BTreeMap>, names: HashMap, by_name: HashMap, } @@ -229,11 +235,16 @@ fn be32(b: &[u8], at: usize) -> Option { } /// Whether `b` ends with a Bento label. -pub(crate) fn sniff(b: &[u8]) -> bool { +pub fn sniff(b: &[u8]) -> bool { b.len() >= LABEL_SIZE && b[b.len() - LABEL_SIZE..b.len() - LABEL_SIZE + 8] == MAGIC } impl<'a> Container<'a> { + /// Object identifiers in ascending order. + pub fn object_ids(&self) -> impl Iterator + '_ { + self.objects.keys().copied() + } + pub fn open(data: &'a [u8]) -> Result, String> { if !sniff(data) { return Err("no Bento label at the end of the file".into()); @@ -324,7 +335,7 @@ impl<'a> Container<'a> { } /// The bytes of a value. - pub fn value(&self, p: &Prop) -> Result, String> { + pub(crate) fn value(&self, p: &Prop) -> Result, String> { let total = p.segs.iter().try_fold(0usize, |total, s| { let len = match s { Seg::Imm(b) => b.len(), diff --git a/crates/aaf/tests/bento_api.rs b/crates/aaf/tests/bento_api.rs new file mode 100644 index 000000000..9df70c661 --- /dev/null +++ b/crates/aaf/tests/bento_api.rs @@ -0,0 +1,17 @@ +use craft_aaf::omf::bento::{Container, Writer, sniff}; + +#[test] +fn external_consumer_reads_named_values_and_references() { + let mut writer = Writer::new(); + let first = writer.new_object(); + let second = writer.new_object(); + writer.set(first, "test:value", "test:type", b"long value"); + writer.set_references(first, &[second]); + let bytes = writer.finish(); + assert!(sniff(&bytes)); + let container = Container::open(&bytes).unwrap(); + assert!(container.object_ids().any(|id| id == first)); + assert_eq!(container.get(first, "test:value").as_deref(), Some(b"long value".as_slice())); + assert_eq!(container.resolve(first, second), second); + assert!(Container::open(&bytes[..bytes.len() - 1]).is_err()); +} From 99e448d9199191e86a7dddc6b39a5a1e29aad24c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:58:28 +0000 Subject: [PATCH 026/165] aaf: bound duplicate property detection work --- crates/aaf/src/aaf/hostile_tests.rs | 16 ++++++++++++++++ crates/aaf/src/aaf/store.rs | 4 +++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/crates/aaf/src/aaf/hostile_tests.rs b/crates/aaf/src/aaf/hostile_tests.rs index 853b0000c..527e50da8 100644 --- a/crates/aaf/src/aaf/hostile_tests.rs +++ b/crates/aaf/src/aaf/hostile_tests.rs @@ -108,3 +108,19 @@ fn objects_nested_too_deeply_are_an_error() { let e = store::read(&chain(250)).unwrap_err(); assert!(e.contains("nested too deeply"), "{e}"); } + +/// Many distinct property IDs still reject a duplicate without quadratic scanning. +#[test] +fn duplicate_after_many_distinct_properties_is_rejected() { + let mut props = vec![0x4C, 0x20]; + props.extend_from_slice(&8193u16.to_le_bytes()); + for id in (0..8192u16).chain(std::iter::once(7)) { + props.extend_from_slice(&id.to_le_bytes()); + props.extend_from_slice(&0x82u16.to_le_bytes()); + props.extend_from_slice(&0u16.to_le_bytes()); + } + let mut writer = Writer::new(Version::V3); + writer.stream(Writer::ROOT, "properties", props).unwrap(); + let e = store::read(&writer.finish()).unwrap_err(); + assert!(e.contains("duplicate property id"), "{e}"); +} diff --git a/crates/aaf/src/aaf/store.rs b/crates/aaf/src/aaf/store.rs index 69b14fcf2..859c0ea77 100644 --- a/crates/aaf/src/aaf/store.rs +++ b/crates/aaf/src/aaf/store.rs @@ -461,11 +461,13 @@ impl R<'_> { if at > props.len() { return Err(bad("truncated property index")); } + // A properties stream can name tens of thousands of ids: do not rescan all earlier ids. + let mut seen = std::collections::HashSet::with_capacity(n); for i in 0..n { let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else { return Err(bad("truncated property index")); }; - if o.props.iter().any(|(previous, _)| *previous == pid) { + if !seen.insert(pid) { return Err(bad("duplicate property id")); } let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?; From f751827790237ed116980c3f981f2e2b72d788a1 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:01:42 +0000 Subject: [PATCH 027/165] audio: share streaming PCM export encoding --- crates/audio/src/lib.rs | 3 + crates/audio/src/pcm_export.rs | 264 +++++++++++++++++++++++++++++++++ 2 files changed, 267 insertions(+) create mode 100644 crates/audio/src/pcm_export.rs diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..4a5f352d1 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -66,6 +66,9 @@ mod wav; feature = "vorbis-encode" ))] mod write; + +/// Streaming WAVE and AIFF headers and sample packing. +pub mod pcm_export; #[cfg(feature = "vorbis-encode")] pub use write::{OGG_BITRATES, encode_ogg}; diff --git a/crates/audio/src/pcm_export.rs b/crates/audio/src/pcm_export.rs new file mode 100644 index 000000000..c8456d785 --- /dev/null +++ b/crates/audio/src/pcm_export.rs @@ -0,0 +1,264 @@ +//! Audio-only files: WAV (RIFF, little-endian PCM; RF64 past 4 GiB) and AIFF (big-endian PCM), +//! 16, 24 or 32-bit integer or 32-bit float ([`SampleFormat`]), for streaming export. +//! Float WAV is `WAVE_FORMAT_IEEE_FLOAT` with a `fact` chunk; float AIFF is AIFF-C (`fl32`). +//! +//! The header is written first from the known length ([`header`]), then the samples in chunks +//! ([`encode`]) and the pad byte ([`pad`]), so an export streams to disk instead of building the +//! file in memory. + +/// PCM representation in an exported file. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum SampleFormat { + /// 16-bit signed integer. + Int16, + /// 24-bit signed integer. + Int24, + /// 32-bit signed integer. + Int32, + /// 32-bit IEEE float. + Float32, +} + +impl SampleFormat { + /// Bits per sample. + pub fn bits(self) -> u16 { + match self { + Self::Int16 => 16, + Self::Int24 => 24, + Self::Int32 | Self::Float32 => 32, + } + } + /// Bytes per sample. + pub fn bytes(self) -> usize { + usize::from(self.bits() / 8) + } + /// Whether this is a floating point format. + pub fn is_float(self) -> bool { + self == Self::Float32 + } + /// Clip and quantize one sample with symmetric integer full scale; NaN becomes silence. + pub fn quantise(self, s: f32) -> i32 { + let s = s.clamp(-1.0, 1.0); + match self { + Self::Int16 => (s * 32_767.0).round() as i32, + Self::Int24 => (s * 8_388_607.0).round() as i32, + Self::Int32 => (f64::from(s) * 2_147_483_647.0).round() as i32, + Self::Float32 => 0, + } + } + /// Sanitize a floating sample: NaN becomes silence, infinity becomes the largest finite value. + pub fn float(s: f32) -> f32 { + if s.is_nan() { 0.0 } else { s.clamp(f32::MIN, f32::MAX) } + } +} + +/// The container of an audio-only export. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PcmContainer { + /// RIFF/WAVE or RF64. + Wav, + /// AIFF or AIFF-C. + Aiff, +} + +/// Bytes of sample data for `frames` frames, or None when that does not fit 64 bits. +fn data_len(frames: u64, channels: u16, format: SampleFormat) -> Option { + frames.checked_mul(u64::from(channels))?.checked_mul(format.bytes() as u64) +} + +/// The pad byte after an odd-sized data chunk (RIFF and AIFF chunks are word-aligned). +pub fn pad(frames: u64, channels: u16, format: SampleFormat) -> &'static [u8] { + if data_len(frames, channels, format).is_some_and(|n| n & 1 == 1) { &[0] } else { &[] } +} + +/// `KSDATAFORMAT_SUBTYPE_PCM` / `_IEEE_FLOAT` after their first two bytes (the format tag). +const SUBTYPE_TAIL: [u8; 14] = [0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71]; + +/// AIFF-C format version 1 (`FVER`). +const AIFC_VERSION_1: u32 = 0xA280_5140; + +/// The AIFF-C compression name of `fl32`, as a Pascal string of even length. +const FL32_NAME: &[u8] = b"\x1532-bit floating point"; + +/// Everything before the samples of a file of `frames` frames. A WAV whose RIFF size would not +/// fit 32 bits (4 GiB: 24-bit 5.1 at 96 kHz after about 41 minutes) is written as RF64 (EBU Tech +/// 3306), with the 64-bit sizes in a `ds64` chunk. AIFF has no 64-bit form, so a longer AIFF is +/// an error naming WAV instead. +pub fn header(container: PcmContainer, channels: u16, sample_rate: u32, format: SampleFormat, frames: u64) -> Result, String> { + let too_long = || "the audio is too long to write".to_string(); + let bits = format.bits(); + let bps = bits / 8; + let float = format.is_float(); + let data = data_len(frames, channels, format).ok_or_else(too_long)?; + let block_align = channels.checked_mul(bps).ok_or("too many audio channels")?; + match container { + PcmContainer::Wav => { + let byte_rate = + u32::try_from(u64::from(sample_rate) * u64::from(block_align)).map_err(|_| "the audio sample rate is too high".to_string())?; + let ext = channels > 2; + // plain PCM has no cbSize; IEEE float has an empty one + let fmt_len: u32 = if ext { + 40 + } else if float { + 18 + } else { + 16 + }; + // every format but integer PCM has a `fact` chunk (the frame count; RF64: in `ds64`) + let fact_len: u64 = if float { 12 } else { 0 }; + let padded = data.checked_add(data & 1).ok_or_else(too_long)?; + // "WAVE" + fmt chunk + fact chunk + data chunk header + samples + let riff = (4 + 8 + u64::from(fmt_len) + fact_len + 8).checked_add(padded).ok_or_else(too_long)?; + let rf64 = riff > u64::from(u32::MAX); + let mut v = Vec::with_capacity(100); + if rf64 { + const DS64: u64 = 8 + 28; + v.extend_from_slice(b"RF64"); + v.extend_from_slice(&u32::MAX.to_le_bytes()); + v.extend_from_slice(b"WAVEds64"); + v.extend_from_slice(&28u32.to_le_bytes()); + v.extend_from_slice(&riff.checked_add(DS64).ok_or_else(too_long)?.to_le_bytes()); + v.extend_from_slice(&data.to_le_bytes()); + v.extend_from_slice(&frames.to_le_bytes()); + v.extend_from_slice(&0u32.to_le_bytes()); // no table entries + } else { + v.extend_from_slice(b"RIFF"); + v.extend_from_slice(&(riff as u32).to_le_bytes()); + v.extend_from_slice(b"WAVE"); + } + let tag: u16 = if float { 3 } else { 1 }; + v.extend_from_slice(b"fmt "); + v.extend_from_slice(&fmt_len.to_le_bytes()); + v.extend_from_slice(&(if ext { 0xFFFE } else { tag }).to_le_bytes()); + v.extend_from_slice(&channels.to_le_bytes()); + v.extend_from_slice(&sample_rate.to_le_bytes()); + v.extend_from_slice(&byte_rate.to_le_bytes()); + v.extend_from_slice(&block_align.to_le_bytes()); + v.extend_from_slice(&bits.to_le_bytes()); + if ext { + // cbSize, valid bits, channel mask, KSDATAFORMAT_SUBTYPE_PCM / _IEEE_FLOAT + v.extend_from_slice(&22u16.to_le_bytes()); + v.extend_from_slice(&bits.to_le_bytes()); + let mask: u32 = if channels == 6 { 0x3F } else { 0 }; + v.extend_from_slice(&mask.to_le_bytes()); + v.extend_from_slice(&tag.to_le_bytes()); + v.extend_from_slice(&SUBTYPE_TAIL); + } else if float { + v.extend_from_slice(&0u16.to_le_bytes()); + } + if float { + v.extend_from_slice(b"fact"); + v.extend_from_slice(&4u32.to_le_bytes()); + v.extend_from_slice(&(if rf64 { u32::MAX } else { u32::try_from(frames).unwrap_or(u32::MAX) }).to_le_bytes()); + } + v.extend_from_slice(b"data"); + v.extend_from_slice(&(if rf64 { u32::MAX } else { data as u32 }).to_le_bytes()); + Ok(v) + } + PcmContainer::Aiff => { + let aiff_too_long = || "AIFF holds at most 4 GB of audio: export WAV, which has no such limit".to_string(); + let frames32 = u32::try_from(frames).map_err(|_| aiff_too_long())?; + // SSND: offset + block size + samples + let ssnd = u32::try_from(data.checked_add(8).ok_or_else(aiff_too_long)?).map_err(|_| aiff_too_long())?; + // floats need AIFF-C: a version chunk, and the compression type and name in COMM + let comm: u32 = if float { 18 + 4 + FL32_NAME.len() as u32 } else { 18 }; + let fver: u32 = if float { 8 + 4 } else { 0 }; + let form = (4u32 + fver + (8 + comm)) + .checked_add(8) + .and_then(|n| n.checked_add(ssnd)) + .and_then(|n| n.checked_add(ssnd & 1)) + .ok_or_else(aiff_too_long)?; + let mut v = Vec::with_capacity(90); + v.extend_from_slice(b"FORM"); + v.extend_from_slice(&form.to_be_bytes()); + if float { + v.extend_from_slice(b"AIFCFVER"); + v.extend_from_slice(&4u32.to_be_bytes()); + v.extend_from_slice(&AIFC_VERSION_1.to_be_bytes()); + } else { + v.extend_from_slice(b"AIFF"); + } + v.extend_from_slice(b"COMM"); + v.extend_from_slice(&comm.to_be_bytes()); + v.extend_from_slice(&channels.to_be_bytes()); + v.extend_from_slice(&frames32.to_be_bytes()); + v.extend_from_slice(&bits.to_be_bytes()); + v.extend_from_slice(&extended(sample_rate)); + if float { + v.extend_from_slice(b"fl32"); + v.extend_from_slice(FL32_NAME); + } + v.extend_from_slice(b"SSND"); + v.extend_from_slice(&ssnd.to_be_bytes()); + v.extend_from_slice(&0u32.to_be_bytes()); // offset + v.extend_from_slice(&0u32.to_be_bytes()); // block size + Ok(v) + } + } +} + +/// Append interleaved samples in `format` (little-endian for WAV, big-endian for AIFF). +pub fn encode(container: PcmContainer, interleaved: &[f32], format: SampleFormat, out: &mut Vec) { + let bps = format.bytes(); + out.reserve(interleaved.len().saturating_mul(bps)); + for &s in interleaved { + let q = if format.is_float() { SampleFormat::float(s).to_bits() as i32 } else { format.quantise(s) }; + match container { + PcmContainer::Wav => out.extend_from_slice(q.to_le_bytes().get(..bps).unwrap_or_default()), + PcmContainer::Aiff => out.extend_from_slice(q.to_be_bytes().get(4 - bps..).unwrap_or_default()), + } + } +} + +/// A whole file in memory (short audio; exports stream with [`header`] and [`encode`]). +fn write_whole(container: PcmContainer, interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + let frames = (interleaved.len() / usize::from(channels.max(1))) as u64; + let mut v = header(container, channels, sample_rate, format, frames)?; + encode(container, interleaved, format, &mut v); + v.extend_from_slice(pad(frames, channels, format)); + Ok(v) +} + +/// A RIFF/WAVE file of interleaved samples. More than two channels are written as +/// `WAVE_FORMAT_EXTENSIBLE` with the speaker mask of the layout (6 channels: L, R, C, LFE, Ls, Rs +/// = `0x3F`). +pub fn write_wav(interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + write_whole(PcmContainer::Wav, interleaved, channels, sample_rate, format) +} + +/// IEEE 754 80-bit extended encoding of a sample rate (AIFF `COMM`). +pub fn extended(rate: u32) -> [u8; 10] { + let mut out = [0u8; 10]; + if rate == 0 { + return out; + } + let shift = rate.leading_zeros(); + let mant = (rate as u64) << (32 + shift); + let exp = 16383 + 31 - shift as u16; + out[..2].copy_from_slice(&exp.to_be_bytes()); + out[2..].copy_from_slice(&mant.to_be_bytes()); + out +} + +/// An AIFF file (`FORM`/`AIFF`, `COMM` + `SSND`; AIFF-C for floats) of interleaved samples. +pub fn write_aiff(interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + write_whole(PcmContainer::Aiff, interleaved, channels, sample_rate, format) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn streaming_formats_preserve_samples_and_bounds() { + let samples = [1.0, -1.0, f32::NAN]; + let wav = write_wav(&samples, 1, 48_000, SampleFormat::Int24).unwrap(); + assert_eq!(&wav[..4], b"RIFF"); + assert_eq!(&wav[44..53], &[255, 255, 127, 1, 0, 128, 0, 0, 0]); + let h = header(PcmContainer::Wav, 6, 96_000, SampleFormat::Int24, 96_000 * 3600).unwrap(); + assert_eq!(&h[..4], b"RF64"); + assert!(header(PcmContainer::Aiff, 2, 48_000, SampleFormat::Int24, u64::MAX).is_err()); + let aiff = write_aiff(&[0.25, -3.0], 1, 44_100, SampleFormat::Float32).unwrap(); + assert_eq!(&aiff[8..12], b"AIFC"); + assert_eq!(&aiff[aiff.len() - 8..], [0.25f32.to_be_bytes(), (-3.0f32).to_be_bytes()].concat()); + } +} From 6b82b6a77c995847084311402d27a6361b6491ed Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:05:22 +0000 Subject: [PATCH 028/165] aaf: support legacy reference and locator conventions --- crates/aaf/src/aaf.rs | 47 +++++++++++++++++++++++++++++++++++-- crates/aaf/src/aaf/read.rs | 32 +++++++++++++++++++------ crates/aaf/src/aaf/tests.rs | 29 +++++++++++++++++++++++ crates/aaf/src/aaf/write.rs | 18 ++++++++++---- 4 files changed, 113 insertions(+), 13 deletions(-) diff --git a/crates/aaf/src/aaf.rs b/crates/aaf/src/aaf.rs index 05894f94e..efa618fb3 100644 --- a/crates/aaf/src/aaf.rs +++ b/crates/aaf/src/aaf.rs @@ -57,13 +57,56 @@ pub struct WriteOptions<'a> { /// reported. pub fn write(doc: &Document, opts: &WriteOptions<'_>, report: &mut Report) -> Result> { let version = if opts.small_sectors { craft_cfb::Version::V3 } else { craft_cfb::Version::V4 }; - write::write(doc, version, &opts.identity, report) + write::write(doc, version, &opts.identity, &ReferenceOptions::default(), report) +} + +/// Optional interpretation choices for applications retaining older interchange behavior. +#[derive(Clone, Copy, Debug)] +pub struct ReadOptions { + /// Interpret a source clip's start using its target slot's edit rate. + pub source_slot_rate: bool, + /// Use the referenced mob name when the clip has no explicit name. + pub infer_clip_name: bool, + /// Decode percent escapes in relative network locators. + pub decode_relative_locator: bool, + /// Report selector and nested-scope flattening. + pub report_flattening: bool, + /// Accept truncated PCM WAVE essence summaries. + pub permissive_pcm: bool, +} +impl Default for ReadOptions { + fn default() -> Self { + Self { source_slot_rate: true, infer_clip_name: true, decode_relative_locator: true, report_flattening: true, permissive_pcm: false } + } +} +/// Read using explicitly selected interpretation choices. +pub fn read_with_options(bytes: &[u8], options: &ReadOptions, report: &mut Report) -> Result { + read::read(bytes, options, report) +} + +/// Optional compatibility choices for writing source references and locators. +#[derive(Clone, Copy, Debug)] +pub struct ReferenceOptions { + /// Write source offsets in target-slot units. + pub source_slot_rate: bool, + /// Percent-encode relative locators. + pub encode_relative_locator: bool, +} +impl Default for ReferenceOptions { + fn default() -> Self { + Self { source_slot_rate: true, encode_relative_locator: true } + } +} +/// Write with explicitly selected reference and locator conventions. +pub fn write_with_references(doc: &Document, opts: &WriteOptions<'_>, references: &ReferenceOptions, report: &mut Report) -> Result> { + let version = if opts.small_sectors { craft_cfb::Version::V3 } else { craft_cfb::Version::V4 }; + write::write(doc, version, &opts.identity, references, report) } /// Read an AAF file: its top-level compositions, the compositions nested in them and their /// sources. What cannot be represented is skipped and named in `report`. pub fn read(bytes: &[u8], report: &mut Report) -> Result { - read::read(bytes, report) + read::read(bytes, &ReadOptions::default(), report) } /// Whether `bytes` look like an AAF file (a compound file whose root has the AAF root class or a diff --git a/crates/aaf/src/aaf/read.rs b/crates/aaf/src/aaf/read.rs index 31c841c5d..9739f87ba 100644 --- a/crates/aaf/src/aaf/read.rs +++ b/crates/aaf/src/aaf/read.rs @@ -67,6 +67,7 @@ fn indirect_f64(d: &[u8]) -> Option { struct R<'a> { report: &'a mut Report, + options: super::ReadOptions, mobs: HashMap, essence: HashMap, doc: Document, @@ -90,7 +91,7 @@ struct NestClip<'a> { /// Compositions nested deeper than this are read as gaps. const MAX_NESTING: usize = 16; -pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { +pub(crate) fn read(bytes: &[u8], options: &super::ReadOptions, report: &mut Report) -> Result { let root = store::read(bytes).map_err(|e| Error::Parse { format: "AAF", message: e })?; let header = root.strong(pid::ROOT_HEADER).ok_or_else(|| Error::Parse { format: "AAF", message: "no header object".into() })?; let content = header.strong(pid::CONTENT).ok_or_else(|| Error::Parse { format: "AAF", message: "no content storage".into() })?; @@ -106,7 +107,8 @@ pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { essence.insert(id, d); } } - let mut r = R { report, mobs, essence, doc: Document::default(), sources: HashMap::new(), nests: HashMap::new(), open: Vec::new() }; + let mut r = + R { report, options: *options, mobs, essence, doc: Document::default(), sources: HashMap::new(), nests: HashMap::new(), open: Vec::new() }; // Top-level compositions: those no other composition uses, among the ones tagged top-level // when any are. (Premiere Pro tags a nested sequence's composition top-level too; it is still // only a nested sequence.) Compositions that only use each other in a circle all count. The @@ -331,7 +333,9 @@ impl R<'_> { items } x if x == cls::SELECTOR => { - self.report.info("a selector was flattened to its selected input"); + if self.options.report_flattening { + self.report.info("a selector was flattened to its selected input"); + } match c.strong(pid::SELECTED) { Some(s) => { let mut items = self.segment(s, rate, kind, depth); @@ -342,7 +346,9 @@ impl R<'_> { } } x if x == cls::NESTED_SCOPE => { - self.report.info("a nested scope was flattened to its final input"); + if self.options.report_flattening { + self.report.info("a nested scope was flattened to its final input"); + } match c.objs(pid::NESTED_SLOTS).last() { Some(s) => { let mut items = self.segment(s, rate, kind, depth); @@ -388,7 +394,12 @@ impl R<'_> { let len = units_to_ticks(len_of(c), rate.0, rate.1); let tagged_name = tagged_values(c, pid::COMPONENT_USER_COMMENTS).into_iter().find(|(k, _)| k == "Clip Name").map(|(_, v)| v); let (Some(id), Some(slot)) = (c.mob_id(pid::SOURCE_ID), c.u32(pid::SOURCE_MOB_SLOT_ID)) else { return CItem::Filler(len) }; - let name = tagged_name.or_else(|| self.mobs.get(&id).and_then(|mob| mob.string(pid::MOB_NAME))).unwrap_or_default(); + let name = if self.options.infer_clip_name { + tagged_name.or_else(|| self.mobs.get(&id).and_then(|mob| mob.string(pid::MOB_NAME))) + } else { + tagged_name + } + .unwrap_or_default(); if id == [0; 32] { return CItem::Filler(len); } @@ -401,6 +412,7 @@ impl R<'_> { .and_then(|mob| mob.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(slot))) .and_then(|s| rate_of(s, pid::EDIT_RATE)) .unwrap_or(rate); + let source_rate = if self.options.source_slot_rate { source_rate } else { rate }; let start = units_to_ticks(c.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); match self.resolve(id, slot, start, kind, master_key, 0) { Some((source, t)) => CItem::Clip(CClip { len, source, start: t, gain: None, name }), @@ -506,6 +518,7 @@ impl R<'_> { .and_then(|m| m.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(next_slot))) .and_then(|s| rate_of(s, pid::EDIT_RATE)) .unwrap_or(rate); + let source_rate = if self.options.source_slot_rate { source_rate } else { rate }; let inner = units_to_ticks(clip.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); if next == [0; 32] { return None; @@ -545,7 +558,11 @@ impl R<'_> { DataKind::Sound => CKind::Sound, _ => kind, }; - let path = d.objs(pid::LOCATOR).iter().find_map(|l| l.string(pid::URL_STRING)).map(|u| locator_path(&u)); + let path = d + .objs(pid::LOCATOR) + .iter() + .find_map(|l| l.string(pid::URL_STRING)) + .map(|u| if self.options.decode_relative_locator { locator_path(&u) } else { craft_timeline::path::file_url_to_path(&u) }); let file_rate = rate_of(d, pid::SAMPLE_RATE).unwrap_or(rate); let length = d .i64(pid::FILE_LENGTH) @@ -604,7 +621,8 @@ impl R<'_> { if let Some(data) = self.essence.get(&id) { s.embedded = Some(data.to_vec()); // embedded essence may be a whole WAVE / AIFF file - if let Some((pcm, ch, sr, bits)) = crate::pcm::parse_wav(data) { + let pcm = if self.options.permissive_pcm { craft_audio::essence_pcm::parse_wav(data) } else { crate::pcm::parse_wav(data) }; + if let Some((pcm, ch, sr, bits)) = pcm { s.embedded = Some(pcm); s.file_channels = ch as u32; s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; diff --git a/crates/aaf/src/aaf/tests.rs b/crates/aaf/src/aaf/tests.rs index 3e7794471..34eb2bbb3 100644 --- a/crates/aaf/src/aaf/tests.rs +++ b/crates/aaf/src/aaf/tests.rs @@ -557,3 +557,32 @@ fn relative_media_locator_round_trips_escaped_characters() { let got = read_clean(&bytes); assert!(got.sources.iter().any(|s| s.path.as_deref() == Some("Audio Files/100%20 #1.wav"))); } + +#[test] +fn compatibility_options_keep_relative_paths_and_parent_rate() { + let mut doc = crate::testdoc::sound_only(None); + doc.compositions[0].sample_rate = 44_100; + doc.sources[0].path = Some("Audio Files/100%20 #1.wav".into()); + let mut report = Report::default(); + let references = ReferenceOptions { source_slot_rate: false, encode_relative_locator: false }; + let bytes = write_with_references(&doc, &WriteOptions { identity: IDENTITY, small_sectors: false }, &references, &mut report).unwrap(); + let root = store::read(&bytes).unwrap(); + let mut all = Vec::new(); + walk(&root, &mut all); + assert!( + all.iter().filter(|o| o.class == cls::NETWORK_LOCATOR).any(|o| o.string(pid::URL_STRING).as_deref() == Some("Audio Files/100%20 #1.wav")) + ); + let starts: Vec = all.iter().filter(|o| o.class == cls::SOURCE_CLIP).filter_map(|o| o.i64(pid::START_TIME)).collect(); + assert!(starts.contains(&17_640), "parent rate start: {starts:?}"); + let opts = ReadOptions { + source_slot_rate: false, + infer_clip_name: false, + decode_relative_locator: false, + report_flattening: false, + permissive_pcm: true, + }; + let back = read_with_options(&bytes, &opts, &mut report).unwrap(); + assert!(back.sources.iter().any(|s| s.path.as_deref() == Some("Audio Files/100%20 #1.wav"))); + let clip = back.compositions[0].tracks[0].items.iter().find_map(|i| if let CItem::Clip(c) = i { Some(c) } else { None }).unwrap(); + assert_eq!(clip.start, FrameRate::FPS_25.tick_of(10)); +} diff --git a/crates/aaf/src/aaf/write.rs b/crates/aaf/src/aaf/write.rs index 8c9aae88e..1fcc6a332 100644 --- a/crates/aaf/src/aaf/write.rs +++ b/crates/aaf/src/aaf/write.rs @@ -75,6 +75,7 @@ fn definition(class: Auid, id: Auid, name: &str) -> Obj { struct W<'a> { report: &'a mut Report, inexact: bool, + references: super::ReferenceOptions, } struct IdGen { @@ -350,9 +351,15 @@ fn add_tape_mob(first: &Source, tape_id: [u8; 32], timecode: Option<(i64, FrameR } /// Serialise a composition document. -pub(crate) fn write(doc: &Document, version: craft_cfb::Version, identity: &Identity<'_>, report: &mut Report) -> Result> { +pub(crate) fn write( + doc: &Document, + version: craft_cfb::Version, + identity: &Identity<'_>, + references: &super::ReferenceOptions, + report: &mut Report, +) -> Result> { let comp = doc.compositions.first().ok_or(Error::Empty)?; - let mut w = W { report, inexact: false }; + let mut w = W { report, inexact: false, references: *references }; let mut ids = IdGen::for_document(doc, comp); let MediaOutput { mut mobs, essence, master_ref } = write_media(doc, &mut w, &mut ids); let mut used_ops: Vec = Vec::new(); @@ -360,7 +367,8 @@ pub(crate) fn write(doc: &Document, version: craft_cfb::Version, identity: &Iden // ---- nested compositions: a clip refers to one as it does to a master mob, through the // composition's first track of the clip's kind (a broken-out channel: that channel's track) - let mut refs = Refs { mobs: master_ref, rates: doc.sources.iter().enumerate().map(|(i, s)| (i, source_rate(s))).collect() }; + let rates = if references.source_slot_rate { doc.sources.iter().enumerate().map(|(i, s)| (i, source_rate(s))).collect() } else { HashMap::new() }; + let mut refs = Refs { mobs: master_ref, rates }; let nested_ids: Vec<[u8; 32]> = doc.nested.iter().map(|_| ids.next()).collect(); for (si, s) in doc.sources.iter().enumerate() { let Some((comp, id)) = s.nested.and_then(|n| Some((doc.nested.get(n)?, nested_ids.get(n)?))) else { continue }; @@ -795,8 +803,10 @@ fn descriptor(w: &mut W, s: &Source) -> Obj { if let Some(p) = &s.path { let url = if craft_timeline::path::is_absolute(p) { craft_timeline::path::path_to_file_url(p, false) - } else { + } else if w.references.encode_relative_locator { craft_timeline::path::encode_uri_path(p) + } else { + p.clone() }; d.set(pid::LOCATOR, Value::StrongVec(vec![Obj::new(cls::NETWORK_LOCATOR).data_prop(pid::URL_STRING, utf16z(&url))])); } From 58854566ed89f6b27f304da15eb8922133fb8924 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:10:39 -0500 Subject: [PATCH 029/165] feat: add craft-format (versioned JSON file formats) Port from solidcraft: versioned JSON file format system with: - Format families with hand-written upgrade steps and folded formats - Pending changes that auto-number on release - Container format: content-addressed blobs (SHA-256) in ZIP packages - Newer file handling: read what you can, keep the rest No external dependencies beyond serde_json and craft-zip. Hostile-input bounded reading: sizes, counts, nesting capped. --- crates/format/Cargo.toml | 20 ++ crates/format/src/build.rs | 100 +++++++ crates/format/src/container.rs | 401 +++++++++++++++++++++++++++ crates/format/src/container_tests.rs | 67 +++++ crates/format/src/lib.rs | 252 +++++++++++++++++ crates/format/src/lib_tests.rs | 134 +++++++++ crates/format/src/newer.rs | 401 +++++++++++++++++++++++++++ crates/format/src/newer_tests.rs | 48 ++++ 8 files changed, 1423 insertions(+) create mode 100644 crates/format/Cargo.toml create mode 100644 crates/format/src/build.rs create mode 100644 crates/format/src/container.rs create mode 100644 crates/format/src/container_tests.rs create mode 100644 crates/format/src/lib.rs create mode 100644 crates/format/src/lib_tests.rs create mode 100644 crates/format/src/newer.rs create mode 100644 crates/format/src/newer_tests.rs diff --git a/crates/format/Cargo.toml b/crates/format/Cargo.toml new file mode 100644 index 000000000..943e0b9b6 --- /dev/null +++ b/crates/format/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "craft-format" +description = "Versioned JSON file formats: the format tag, the registry of versions (hand-written steps, then one folder of changes per version, then the pending changes), the upgrade of an older file and the telling of a newer one" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +serde_json = { workspace = true } +# The container: content-addressed blobs (SHA-256) in a ZIP package. +sha2 = { version = "0.10", default-features = false, features = ["std"] } +craft-zip = { workspace = true } + +[dev-dependencies] +proptest = { workspace = true } diff --git a/crates/format/src/build.rs b/crates/format/src/build.rs new file mode 100644 index 000000000..8fb879235 --- /dev/null +++ b/crates/format/src/build.rs @@ -0,0 +1,100 @@ +//! For a build script: the generated lists of a family's changes. Each change is one `.rs` file in +//! the family's folder, in `v/` once a release fixed its number, else in `pending/`; the lists +//! are generated so that a change adds a file and never edits a line another change also edits. +//! +//! The generated code, for the app to `include!`, is per family a `FOLDED` list (each folded +//! format and its parts) and a `PENDING` list, both prefixed by the family's `list_prefix`, then a +//! module per change file. It names the app's `Part` type, which the including module has in scope +//! (`type Part = craft_format::Part;`), and a change file's step as `step` (a +//! `pub fn step(v: &mut Value) -> Result<(), AppError>`, when the file has one). + +use std::fmt::Write as _; +use std::path::{Path, PathBuf}; + +/// A family's change files: their folder (relative to the crate's manifest), the last format +/// before them, and the prefix of the family's lists. +pub struct Family { + pub folder: &'static str, + pub base: u32, + pub list_prefix: &'static str, +} + +/// What [`lists`] made: the code to write, and the folders the build script reruns on. +pub struct Lists { + pub code: String, + pub watch: Vec, +} + +/// The `FOLDED` and `PENDING` lists of every family, and a module for each change file. Refuses +/// versions that are not contiguous from a family's base, a change file not named with lowercase +/// letters, digits and dashes, and one that doesn't start with a `//!` note. +pub fn lists(manifest: &Path, families: &[Family]) -> Result { + let mut code = String::new(); + let mut mods = String::new(); + let mut watch = Vec::new(); + for family in families { + let root = manifest.join(family.folder); + family_lists(family, &root, &mut code, &mut mods)?; + watch.push(root); + } + code.push_str(&mods); + Ok(Lists { code, watch }) +} + +/// A family's `FOLDED` and `PENDING` lists; its folded formats follow on from its base. +fn family_lists(family: &Family, root: &Path, out: &mut String, mods: &mut String) -> Result<(), String> { + let Family { folder, base, list_prefix } = family; + let mut folded: Vec<(u32, PathBuf)> = std::fs::read_dir(root) + .map_err(|e| format!("{}: {e}", root.display()))? + .filter_map(|entry| { + let path = entry.ok()?.path(); + let version = path.file_name()?.to_str()?.strip_prefix('v')?.parse().ok()?; + path.is_dir().then_some((version, path)) + }) + .collect(); + folded.sort(); + for (i, (version, _)) in folded.iter().enumerate() { + let expected = base + 1 + i as u32; + if *version != expected { + return Err(format!("{folder}/: expected v{expected}/ next, found v{version}/ (versions are contiguous)")); + } + } + // Module names start with the family's (`drawing_pending_…`), so two families' changes of one + // name never clash. + let module = list_prefix.to_ascii_lowercase(); + let _ = writeln!( + out, + "/// The changes of each format after the base, oldest first (`{folder}/v/`).\nconst {list_prefix}FOLDED: &[(u32, &[Part])] = &[" + ); + for (version, dir) in &folded { + let _ = writeln!(out, " ({version}, &["); + parts(dir, &format!("{module}v{version}"), out, mods)?; + out.push_str(" ]),\n"); + } + let _ = writeln!(out, "];\n\n/// The changes no release has a number for yet (`{folder}/pending/`).\nconst {list_prefix}PENDING: &[Part] = &["); + parts(&root.join("pending"), &format!("{module}pending"), out, mods)?; + out.push_str("];\n\n"); + Ok(()) +} + +/// The `Part`s of the change files in `dir`, in file-name order, and a module for each. +fn parts(dir: &Path, prefix: &str, out: &mut String, mods: &mut String) -> Result<(), String> { + let Ok(entries) = std::fs::read_dir(dir) else { return Ok(()) }; + let mut files: Vec = entries.filter_map(|e| e.ok().map(|e| e.path())).filter(|p| p.extension().is_some_and(|x| x == "rs")).collect(); + files.sort(); + for path in files { + let name = path.file_stem().and_then(|s| s.to_str()).unwrap_or_default().to_string(); + if name.is_empty() || !name.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-') { + return Err(format!("{}: name a format change file with lowercase letters, digits and dashes", path.display())); + } + let text = std::fs::read_to_string(&path).map_err(|e| format!("{}: {e}", path.display()))?; + if !text.trim_start().starts_with("//!") { + return Err(format!("{}: start a format change with a `//!` note", path.display())); + } + let module = format!("{prefix}_{}", name.replace('-', "_")); + let step = if text.contains("fn step(") { format!("Some({module}::step)") } else { "None".into() }; + let _ = writeln!(out, " Part {{ name: {name:?}, step: {step} }},"); + let _ = writeln!(mods, "#[path = {:?}]\nmod {module};", path.display().to_string()); + } + Ok(()) +} diff --git a/crates/format/src/container.rs b/crates/format/src/container.rs new file mode 100644 index 000000000..a987bb1fb --- /dev/null +++ b/crates/format/src/container.rs @@ -0,0 +1,401 @@ +//! The file container: a ZIP package of named parts (the file's JSON, binary payloads, optional +//! caches), never extracted to filesystem paths. Payloads are content-addressed blobs, +//! `blobs/.`, stored once however often they are referred to. Every size is +//! bounded by the app's [`Limits`]: the file, each part, all parts expanded, the payloads resolved, +//! and the number of entries; a part is read no further than its declared size (a decompression +//! bomb stops there). What a part holds, and how a payload is encoded, is the app's. + +use std::collections::{BTreeMap, BTreeSet}; +use std::io::{Cursor, Read, Seek, SeekFrom, Write}; +use std::sync::Arc; + +use serde_json::Value; +use sha2::{Digest, Sha256}; + +use crate::FormatError; + +/// How hard the payloads are compressed: Fast favours interactive file operations; Compact trades +/// CPU time for space. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Compression { + #[default] + Fast, + Compact, +} + +/// An app's budgets for its containers. The functions are read each time they are needed, so a +/// limit the app lets the user raise takes effect at once. +#[derive(Clone, Copy)] +pub struct Limits { + /// The most entries a container holds. + pub max_entries: usize, + /// The most bytes all parts may expand to, and all payloads may resolve to. + pub max_expanded: fn() -> usize, + /// The most bytes a part of this name may expand to. + pub part_limit: fn(&str) -> usize, + /// The Deflate level of a compressed part of this name and size. + pub level: fn(&str, usize) -> i64, + /// Whether a container of this many bytes may be read, or why not. + pub check_size: fn(u64) -> Result<(), String>, + /// Whether the work is cancelled (a save the person stopped): a long part is written a piece + /// at a time and stops before the next piece when this says so. `None`: it cannot be + /// cancelled here. + pub cancelled: Option bool>, +} + +fn invalid(message: impl std::fmt::Display) -> FormatError { + FormatError::Invalid(message.to_string()) +} + +/// Whether the bytes start as a container does, whatever the file is called. +pub fn is_container(bytes: &[u8]) -> bool { + bytes.starts_with(b"PK\x03\x04") +} + +/// The SHA-256 of the bytes. +pub fn sha256(bytes: &[u8]) -> [u8; 32] { + Sha256::digest(bytes).into() +} + +fn hex(digest: &[u8; 32]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(64); + for byte in digest { + // Writing to a `String` cannot fail. + let _ = write!(&mut out, "{byte:02x}"); + } + out +} + +/// The SHA-256 of the bytes, in lowercase hexadecimal: a blob's name, and how a cache is keyed to +/// the file it was written for. +pub fn digest(bytes: &[u8]) -> String { + hex(&sha256(bytes)) +} + +/// One part a [`Writer`] wrote, with the SHA-256 of its uncompressed content. A caller that signs +/// a container uses these to bind the parts without reading the file back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct PartDigest { + pub name: String, + pub len: u64, + pub digest: [u8; 32], +} + +/// A container being written. +pub struct Writer { + zip: zip::ZipWriter>>, + names: BTreeSet, + expanded: usize, + resolved: usize, + limits: Limits, + /// Which written parts to record for a signature, and the records so far. + tracked: Option<(fn(&str) -> bool, Vec)>, +} + +impl Writer { + pub fn new(limits: Limits) -> Writer { + Writer { zip: zip::ZipWriter::new(Cursor::new(Vec::new())), names: BTreeSet::new(), expanded: 0, resolved: 0, limits, tracked: None } + } + + /// Record the parts written from now on whose name `include` accepts, with their SHA-256, for + /// [`Writer::take_parts`]. Used by a caller that signs the container. + pub fn track_parts(&mut self, include: fn(&str) -> bool) { + self.tracked = Some((include, Vec::new())); + } + + /// The tracked parts written so far, oldest first, and stop tracking. + pub fn take_parts(&mut self) -> Option> { + self.tracked.take().map(|(_, parts)| parts) + } + + /// The container's bytes. + pub fn finish(self) -> Result, FormatError> { + Ok(self.zip.finish().map_err(invalid)?.into_inner()) + } + + /// Add a part, compressed or stored. A name already written is written once. + pub fn part(&mut self, name: &str, bytes: &[u8], compressed: bool) -> Result<(), FormatError> { + self.part_with_digest(name, bytes, compressed, None) + } + + /// [`Writer::part`] with a digest the caller already worked out (a blob's name is its digest), + /// so a signed save does not hash the same bytes twice. + fn part_with_digest(&mut self, name: &str, bytes: &[u8], compressed: bool, digest: Option<[u8; 32]>) -> Result<(), FormatError> { + if bytes.len() > (self.limits.part_limit)(name) { + return Err(invalid("part too large")); + } + if !self.names.insert(name.to_owned()) { + return Ok(()); + } + self.expanded = self.expanded.checked_add(bytes.len()).ok_or_else(|| invalid("expanded size overflow"))?; + if self.expanded > (self.limits.max_expanded)() || self.names.len() > self.limits.max_entries { + return Err(invalid("package too large")); + } + if let Some((include, parts)) = &mut self.tracked + && include(name) + { + let digest = digest.unwrap_or_else(|| sha256(bytes)); + parts.push(PartDigest { name: name.to_owned(), len: bytes.len() as u64, digest }); + } + let method = if compressed { zip::CompressionMethod::Deflated } else { zip::CompressionMethod::Stored }; + let level = (self.limits.level)(name, bytes.len()); + // A part of 4 GiB or more (only with a raised file limit) needs a ZIP64 entry. + let options = zip::write::SimpleFileOptions::default() + .compression_method(method) + .compression_level(compressed.then_some(level)) + .large_file(bytes.len() as u64 >= u64::from(u32::MAX)); + self.zip.start_file(name, options).map_err(invalid)?; + // A piece at a time: a long compression (a large mesh or model cache) stops on Cancel + // within a piece instead of after the whole part. + for piece in bytes.chunks(1 << 20) { + if self.limits.cancelled.is_some_and(|cancelled| cancelled()) { + return Err(FormatError::Cancelled); + } + self.zip.write_all(piece).map_err(invalid)?; + } + Ok(()) + } + + /// Would `entries` more optional parts of `extra` bytes, stored uncompressed, still keep the + /// file within `budget` and its expanded size within the reader's budget? + pub fn room(&self, entries: usize, extra: usize, budget: usize) -> bool { + self.names.len().saturating_add(entries) <= self.limits.max_entries && extra <= self.space(entries, budget) + } + + /// The bytes `entries` more optional parts may hold together ([`Writer::room`]). + pub fn space(&self, entries: usize, budget: usize) -> usize { + if self.names.len().saturating_add(entries) > self.limits.max_entries { + return 0; + } + // The bytes written so far, plus what the open compressed part may still hold back. + let written = self.zip.get_ref().map_or(usize::MAX, |c| c.get_ref().len()).saturating_add(1 << 20); + let directory = self.names.len().saturating_add(entries).saturating_mul(256).saturating_add(65_536); + budget.saturating_sub(written.saturating_add(directory)).min((self.limits.max_expanded)().saturating_sub(self.expanded)) + } + + /// Add a payload as a blob, `blobs/.`, and say its name, for the JSON that + /// refers to it. + pub fn blob(&mut self, bytes: &[u8], extension: &str, compressed: bool) -> Result { + self.resolved = self + .resolved + .checked_add(bytes.len()) + .filter(|&n| n <= (self.limits.max_expanded)()) + .ok_or_else(|| invalid("resolved payloads too large"))?; + let digest = sha256(bytes); + let name = format!("blobs/{}.{extension}", hex(&digest)); + self.part_with_digest(&name, bytes, compressed, Some(digest))?; + Ok(Value::String(name)) + } +} + +/// A container being read, over a seekable source. Opening checks the directory (the entry count, +/// unique and plain names, every part's declared size), not the parts. +pub struct Reader { + zip: zip::ZipArchive, + blobs: BTreeMap>, + /// The bytes of payloads resolved so far, repeats counted: bounded by the expanded budget. + pub hydrated: usize, + document: Option>, + limits: Limits, +} + +impl Reader { + pub fn new(mut source: R, limits: Limits) -> Result { + let length = source.seek(SeekFrom::End(0)).map_err(invalid)?; + (limits.check_size)(length).map_err(invalid)?; + let tail_length = length.min(65_557) as usize; + source.seek(SeekFrom::Start(length - tail_length as u64)).map_err(invalid)?; + let mut tail = vec![0; tail_length]; + source.read_exact(&mut tail).map_err(invalid)?; + // zip's name index can coalesce duplicate central-directory entries. The bounded format + // does not need ZIP64/multiple disks: verify the declared entry count as well so + // duplicate names cannot silently select a payload. + let eocd = tail.windows(4).rposition(|v| v == b"PK\x05\x06").ok_or_else(|| invalid("missing ZIP directory"))?; + let end = tail.get(eocd..).filter(|v| v.len() >= 22).ok_or_else(|| invalid("truncated ZIP directory"))?; + let u16_at = |offset| -> Result { + let array: [u8; 2] = end.get(offset..offset + 2).ok_or_else(|| invalid("truncated ZIP directory"))?.try_into().map_err(invalid)?; + Ok(u16::from_le_bytes(array)) + }; + let declared = u16_at(10)? as usize; + if declared > limits.max_entries + || u16_at(4)? != 0 + || u16_at(6)? != 0 + || u16_at(8)? as usize != declared + || end.len() != 22 + u16_at(20)? as usize + { + return Err(invalid("too many entries or unsupported ZIP directory")); + } + // A container is a ZIP with nothing in front of it. Saying so skips zip's search for a + // prefix, which reads back through the stored parts and would load a large payload + // before a preview can be shown. + let config = zip::read::Config { archive_offset: zip::read::ArchiveOffset::Known(0) }; + let mut zip = zip::ZipArchive::with_config(config, source).map_err(invalid)?; + if u16_at(4)? != 0 + || u16_at(6)? != 0 + || u16_at(8)? as usize != zip.len() + || u16_at(10)? as usize != zip.len() + || end.len() != 22 + u16_at(20)? as usize + { + return Err(invalid("duplicate entries or unsupported ZIP directory")); + } + let mut names = BTreeSet::new(); + let mut total = 0u64; + for i in 0..zip.len() { + let part = zip.by_index_raw(i).map_err(invalid)?; + let name = part.name().map_err(invalid)?.into_owned(); + if name.is_empty() + || name.contains('\\') + || name.split('/').any(|c| c.is_empty() || c == "." || c == "..") + || !names.insert(name.to_owned()) + { + return Err(invalid("duplicate or invalid archive entry")); + } + total = total.checked_add(part.size()).ok_or_else(|| invalid("expanded size overflow"))?; + let limit = (limits.part_limit)(&name); + if part.size() > limit as u64 || total > (limits.max_expanded)() as u64 { + return Err(invalid("expanded package too large")); + } + } + Ok(Self { zip, blobs: BTreeMap::new(), hydrated: 0, document: None, limits }) + } + + /// The file's own part, `document.json`, read once and kept: provisional caches and the + /// authoritative reading are bound to the same bytes, even if another process overwrites the + /// open file in place. Blobs remain hash-checked. + pub fn document(&mut self, limit: usize) -> Result, FormatError> { + if self.document.is_none() { + self.document = Some(self.limited_part("document.json", limit)?.into()); + } + self.document.as_ref().filter(|d| d.len() <= limit).cloned().ok_or_else(|| invalid("metadata budget")) + } + + /// Whether the container has a part of this name. + pub fn has_part(&self, name: &str) -> bool { + self.zip.index_for_name(name).is_some() + } + + /// The names of every part, in the container's order. + pub fn part_names(&self) -> Vec { + self.zip.file_names().filter_map(|name| name.ok().map(|name| name.into_owned())).collect() + } + + /// The part of this name, at most `limit` bytes. + pub fn limited_part(&mut self, name: &str, limit: usize) -> Result, FormatError> { + let part = self.zip.by_name(name).map_err(|e| invalid(format!("required part `{name}`: {e}")))?; + let expected = part.size(); + if expected > limit as u64 { + return Err(invalid("part too large")); + } + let mut bytes = Vec::new(); + bytes.try_reserve_exact(expected as usize).map_err(|_| invalid("could not reserve required part"))?; + // A compressed part may expand beyond its declared size (a decompression bomb): stop + // one byte past it instead of at the limit. + part.take(expected + 1).read_to_end(&mut bytes).map_err(invalid)?; + if bytes.len() > limit || bytes.len() as u64 != expected { + return Err(invalid("part too large or length mismatch")); + } + Ok(bytes) + } + + /// The blob `value`'s `field` names, of this extension, within its part limit. + pub fn blob(&mut self, value: &Value, field: &str, extension: &str) -> Result<&[u8], FormatError> { + let limit = (self.limits.part_limit)(&format!("blob.{extension}")); + self.limited_blob(value, field, extension, limit) + } + + /// [`Reader::blob`] within `limit` bytes. Its hash is checked when it is first read, and every + /// reference counts against the resolved budget. + pub fn limited_blob(&mut self, value: &Value, field: &str, extension: &str, limit: usize) -> Result<&[u8], FormatError> { + let name = value.get(field).and_then(Value::as_str).ok_or_else(|| invalid(format!("missing `{field}` reference")))?; + let hash = name + .strip_prefix("blobs/") + .and_then(|n| n.strip_suffix(&format!(".{extension}"))) + .filter(|h| h.len() == 64 && h.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))) + .ok_or_else(|| invalid("invalid blob reference"))?; + if !self.blobs.contains_key(name) { + let bytes = self.limited_part(name, limit)?; + if digest(&bytes) != hash { + return Err(invalid(format!("blob hash mismatch: {name}"))); + } + self.blobs.insert(name.to_owned(), bytes); + } + let bytes = self.blobs.get(name).ok_or_else(|| invalid("missing blob"))?; + if bytes.len() > limit { + return Err(invalid("blob exceeds its resource budget")); + } + // Count repeated references too: a tiny archive must not expand into unbounded owned + // strings or arrays when the same blob is referenced repeatedly. + self.hydrated = self + .hydrated + .checked_add(bytes.len()) + .filter(|&n| n <= (self.limits.max_expanded)()) + .ok_or_else(|| invalid("resolved payloads too large"))?; + Ok(bytes) + } +} + +/// A small PNG picture of the file, kept in the container as a disposable cache keyed to the +/// exact file it shows: `cache/thumbnail.json` (its key) and `cache/thumbnail.png`. Reading it +/// never resolves a payload; a picture that isn't one, or is stale, is a miss. +#[derive(Clone, Copy, Debug)] +pub struct Thumbnail { + /// The key's format tag. + pub format: &'static str, + /// The build that wrote it: only the same build reads it back. + pub app: &'static str, + /// Its width and height in pixels. + pub size: [usize; 2], + /// The most bytes it may have. + pub max_bytes: usize, +} + +impl Thumbnail { + /// Whether the bytes start as a PNG of this size within the byte budget (not a decode: a + /// consumer decodes with its own dimension and allocation limits). + pub fn valid(&self, bytes: &[u8]) -> bool { + bytes.len() <= self.max_bytes + && bytes.get(..8) == Some(b"\x89PNG\r\n\x1a\n") + && bytes.get(8..16) == Some(b"\0\0\0\rIHDR") + && bytes.get(16..20) == Some((self.size[0] as u32).to_be_bytes().as_slice()) + && bytes.get(20..24) == Some((self.size[1] as u32).to_be_bytes().as_slice()) + } + + /// Add the picture, keyed to `document` (the file's own part), when it is one and there is + /// room for it within `budget`; otherwise leave it out, never failing the save. + pub fn write(&self, writer: &mut Writer, png: &[u8], document: &[u8], budget: usize) -> Result<(), FormatError> { + if !self.valid(png) { + return Ok(()); + } + let key = + serde_json::to_vec(&serde_json::json!({"format": self.format, "app": self.app, "document": digest(document), "payload": digest(png)})) + .map_err(invalid)?; + if !writer.room(2, key.len().saturating_add(png.len()), budget) { + return Ok(()); + } + writer.part("cache/thumbnail.json", &key, false)?; + writer.part("cache/thumbnail.png", png, false) + } + + /// The picture, when this build wrote it for exactly the file's own part (`document.json`, + /// read within `document_limit`). + pub fn read(&self, reader: &mut Reader, document_limit: usize) -> Result, FormatError> { + let key: Value = serde_json::from_slice(&reader.limited_part("cache/thumbnail.json", 4096)?).map_err(invalid)?; + let document = reader.document(document_limit)?; + if key.get("format").and_then(Value::as_str) != Some(self.format) + || key.get("app").and_then(Value::as_str) != Some(self.app) + || key.get("document").and_then(Value::as_str) != Some(digest(&document).as_str()) + { + return Err(invalid("thumbnail key")); + } + let png = reader.limited_part("cache/thumbnail.png", self.max_bytes)?; + if !self.valid(&png) || key.get("payload").and_then(Value::as_str) != Some(digest(&png).as_str()) { + return Err(invalid("thumbnail payload")); + } + Ok(png) + } +} + +#[cfg(test)] +#[path = "container_tests.rs"] +mod tests; diff --git a/crates/format/src/container_tests.rs b/crates/format/src/container_tests.rs new file mode 100644 index 000000000..bda37d000 --- /dev/null +++ b/crates/format/src/container_tests.rs @@ -0,0 +1,67 @@ +use super::*; + +const LIMITS: Limits = Limits { + max_entries: 8, + max_expanded: || 1 << 20, + part_limit: |name| if name.ends_with(".big") { 1 << 20 } else { 1024 }, + level: |_, _| 1, + check_size: |length| if length <= 1 << 20 { Ok(()) } else { Err("too large".into()) }, + cancelled: None, +}; + +/// Parts and blobs written are read back as they were; a blob is stored once, named by its hash, +/// and checked against it. +#[test] +fn parts_and_blobs_read_back() { + let mut writer = Writer::new(LIMITS); + writer.part("document.json", br#"{"a":1}"#, true).unwrap(); + let first = writer.blob(b"payload", "bin", false).unwrap(); + let again = writer.blob(b"payload", "bin", true).unwrap(); + assert_eq!(first, again, "the same payload is one blob"); + assert_eq!(first, Value::String(format!("blobs/{}.bin", digest(b"payload")))); + let bytes = writer.finish().unwrap(); + assert!(is_container(&bytes)); + let mut reader = Reader::new(Cursor::new(bytes), LIMITS).unwrap(); + assert_eq!(reader.part_names().len(), 2); + assert!(reader.has_part("document.json") && !reader.has_part("other.json")); + assert_eq!(&*reader.document(64).unwrap(), br#"{"a":1}"#); + let reference = serde_json::json!({"blob": first}); + assert_eq!(reader.blob(&reference, "blob", "bin").unwrap(), b"payload"); + assert!(reader.blob(&reference, "blob", "png").is_err(), "another extension"); + assert_eq!(reader.hydrated, 7); + reader.hydrated = (LIMITS.max_expanded)(); + assert!(reader.blob(&reference, "blob", "bin").unwrap_err().to_string().contains("resolved payloads too large")); +} + +/// A part past its limit, or more entries than the limit, are refused as they are written. +#[test] +fn budgets_are_kept_when_writing() { + let mut writer = Writer::new(LIMITS); + assert_eq!(writer.part("small.json", &[0; 1025], false), Err(FormatError::Invalid("part too large".into()))); + assert!(writer.part("large.big", &[0; 1025], true).is_ok()); + for i in 0..7 { + writer.part(&format!("{i}.json"), b"x", false).unwrap(); + } + assert_eq!(writer.part("one-more.json", b"x", false), Err(FormatError::Invalid("package too large".into()))); + assert!(!writer.room(1, 0, 1 << 20), "no room for an entry past the limit"); +} + +/// A thumbnail is kept only for the file it shows. +#[test] +fn a_thumbnail_is_keyed_to_its_file() { + let picture = Thumbnail { format: "app-thumbnail/1", app: "1.0", size: [2, 1], max_bytes: 1024 }; + let mut png = b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR".to_vec(); + png.extend_from_slice(&2u32.to_be_bytes()); + png.extend_from_slice(&1u32.to_be_bytes()); + assert!(picture.valid(&png)); + let mut writer = Writer::new(LIMITS); + writer.part("document.json", b"{}", false).unwrap(); + picture.write(&mut writer, &png, b"{}", 8 << 20).unwrap(); + let mut reader = Reader::new(Cursor::new(writer.finish().unwrap()), LIMITS).unwrap(); + assert_eq!(picture.read(&mut reader, 64).unwrap(), png); + let mut writer = Writer::new(LIMITS); + writer.part("document.json", b"{\"changed\":1}", false).unwrap(); + picture.write(&mut writer, &png, b"{}", 8 << 20).unwrap(); + let mut reader = Reader::new(Cursor::new(writer.finish().unwrap()), LIMITS).unwrap(); + assert!(picture.read(&mut reader, 64).is_err(), "stale"); +} diff --git a/crates/format/src/lib.rs b/crates/format/src/lib.rs new file mode 100644 index 000000000..8eb495417 --- /dev/null +++ b/crates/format/src/lib.rs @@ -0,0 +1,252 @@ +//! Versioned file formats: what an app needs to read every file it ever wrote, and to open a file +//! a newer build of it wrote. +//! +//! A file starts with `"format": "N"`. A [`Family`] is one kind of file (an app's designs, +//! its drawings): its tag, its own numbers, and how a file of an older number is brought up to +//! this build's, step by step (N → N+1 → … → current). The app's code only knows the current +//! format; all translation lives in the steps: +//! - the steps written out by hand for the first formats, one per format ([`Formats::hand`]); +//! - then one folder per format, `v/`, one file per change in it ([`Part`]), each with a step +//! when files from before the change are rewritten as they open ([`Formats::folded`]); +//! - then the changes no release has a number for yet, in `pending/` ([`Formats::pending`]): +//! while there are any, the build writes the next number, with their names in the file's +//! `format_pending`, so a later build runs just the steps a file is missing. A release moves +//! them into the next `v/`. [`build`] lists the folders for a build script. +//! +//! A file a newer build wrote says so by a number past this build's or a change name this build +//! doesn't have ([`Family::newer`]); the app then reads what it can and keeps the rest +//! ([`newer`]). A file is saved as JSON, or in a [`container`] with its binary payloads. +//! +//! Steps are JSON-level (the file's shape) and return the app's own error type; every error this +//! crate makes is a [`FormatError`], which the app's error type takes `From`. + +use serde_json::Value; + +pub mod build; +pub mod container; +pub mod newer; + +/// Why a file is refused: its text says what is wrong, as the user reads it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum FormatError { + /// The file isn't one of the family's, or it is damaged. + Invalid(String), + /// The work was cancelled (a save the person stopped): nothing more was written. + Cancelled, +} + +impl std::fmt::Display for FormatError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + FormatError::Invalid(why) => f.write_str(why), + FormatError::Cancelled => f.write_str("cancelled"), + } + } +} + +impl std::error::Error for FormatError {} + +/// One JSON-level upgrade step: rewrites a file in place, or says why it can't. +pub type Step = fn(&mut Value) -> Result<(), E>; + +/// One change to a family's file format: a file in its `v/` or `pending/` folder. +pub struct Part { + /// The file's name, which a file written while the change was pending lists. + pub name: &'static str, + /// How a file from before the change is rewritten as it opens, if it is. + pub step: Option>, +} + +/// Another spelling of a change name that a file of one format may carry (a build that named the +/// change otherwise): read as the change it stands for, never written. +#[derive(Clone, Copy, Debug)] +pub struct Alias { + /// The format whose files may say it. + pub format: u32, + /// The spelling in the file. + pub name: &'static str, + /// The change it stands for. + pub known_as: &'static str, +} + +/// A family's upgrade path: the steps written out by hand, the folded formats after them (each a +/// list of changes) and the pending changes, which make the next format. +pub struct Formats<'a, E> { + /// Entry `i` turns format `i + 1` into `i + 2`. + pub hand: &'a [Step], + /// Each format after the hand-written ones, oldest first, and its changes. + pub folded: &'a [(u32, &'a [Part])], + /// The changes no release has a number for yet. + pub pending: &'a [Part], +} + +/// A kind of file whose format is versioned: its own format tag, its own numbers and its own +/// changes. Reading a file's format, telling a file a newer build saved and the upgrade are the +/// same for every family. +pub struct Family<'a, E> { + /// The app, as messages name it. + pub app: &'static str, + /// What a file of the family is called in messages. + pub noun: &'static str, + /// The tag before the number in a file's `format`. + pub prefix: &'static str, + /// The tag files saved under an older name carry: read, never written. + pub legacy_prefix: Option<&'static str>, + /// The format of a file that names none, if such files exist. + pub untagged: Option, + /// Other spellings of change names that files may carry. + pub aliases: &'a [Alias], + /// The upgrade path. + pub formats: Formats<'a, E>, +} + +/// How a file shows a newer build saved it ([`Family::newer`]). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Newer { + /// The number the file says. + pub format: u32, + /// The number this build reads up to. + pub reads_up_to: u32, + /// The changes the file names that this build doesn't have. + pub unknown_changes: Vec, +} + +impl Formats<'_, E> { + /// The format this build writes: the last folded one, or the next while changes are pending. + pub const fn current(&self) -> u32 { + self.hand.len() as u32 + 1 + self.folded.len() as u32 + if self.pending.is_empty() { 0 } else { 1 } + } + + /// The changes format `version` is made of, if it is made of changes. + fn parts(&self, version: u32) -> Option<&[Part]> { + let after = version.checked_sub(self.hand.len() as u32 + 2)? as usize; + match self.folded.get(after) { + Some((_, parts)) => Some(parts), + None if after == self.folded.len() && !self.pending.is_empty() => Some(self.pending), + None => None, + } + } + + /// Whether a change of this name is anywhere in this build's history. + fn knows_part_name(&self, name: &str) -> bool { + self.folded.iter().flat_map(|(_, parts)| *parts).chain(self.pending).any(|part| part.name == name) + } +} + +impl Family<'_, E> { + /// The format this build writes: the last folded one, or the next while changes are pending. + pub const fn current(&self) -> u32 { + self.formats.current() + } + + /// What a file of the family is called in messages. + pub const fn noun(&self) -> &'static str { + self.noun + } + + /// The names of the pending changes this build writes into a file (`format_pending`). + pub fn pending_names(&self) -> Vec { + self.formats.pending.iter().map(|p| p.name.to_string()).collect() + } + + /// The format tag of format `n`. + pub fn format_string(&self, n: u32) -> String { + format!("{}{n}", self.prefix) + } + + /// The version in one of this family's format tags; `None` for any other tag, another + /// family's included. + pub fn version_of(&self, s: &str) -> Option { + s.strip_prefix(self.prefix).or_else(|| self.legacy_prefix.and_then(|p| s.strip_prefix(p)))?.parse().ok() + } + + /// The change a name a file of format `version` lists stands for: its alias's, or itself. + /// An alias counts only while this build has the change it stands for, so recognising it + /// never grants support to another reader. + fn canonical_applied_name<'name>(&self, version: u32, name: &'name str) -> &'name str { + match self.aliases.iter().find(|a| a.format == version && a.name == name) { + Some(alias) if self.formats.knows_part_name(alias.known_as) => alias.known_as, + _ => name, + } + } + + /// What says a file of format `version` with the changes `applied` came from a newer build: + /// a number past this build's, or a change this build doesn't have anywhere in its history + /// (a branch's pending change may have landed at a later number). A list beside a format that + /// isn't made of changes means nothing (a tool or a test set an older number on a newer file). + /// `None` for a file this build fully knows. + pub fn newer(&self, version: u32, applied: Option<&[String]>) -> Option { + let current = self.current(); + let listed = applied.filter(|_| version > current || self.formats.parts(version).is_some()).unwrap_or_default(); + let unknown_changes: Vec = + listed.iter().filter(|name| !self.formats.knows_part_name(self.canonical_applied_name(version, name))).cloned().collect(); + (version > current || !unknown_changes.is_empty()).then_some(Newer { format: version, reads_up_to: current, unknown_changes }) + } +} + +impl> Family<'_, E> { + /// Read a file's format and take its `format_pending` out of its JSON, before anything else + /// in it is read: a file that isn't this family's is refused here. One a newer build saved is + /// not: [`Family::newer`] says so. + pub fn take_version(&self, v: &mut Value) -> Result<(u32, Option>), E> { + let (app, noun) = (self.app, self.noun); + let not_ours = |what: String| E::from(FormatError::Invalid(format!("not a {app} {noun} ({what})"))); + let Some(obj) = v.as_object() else { return Err(not_ours("expected a JSON object".into())) }; + let version = match obj.get("format") { + None => self.untagged.ok_or_else(|| not_ours("no format".into()))?, + Some(Value::String(f)) => self.version_of(f).ok_or_else(|| not_ours(format!("format `{f}`")))?, + Some(_) => return Err(not_ours("format is not a string".into())), + }; + let applied = take_names(v, "format_pending", noun).map_err(E::from)?; + if version == 0 { + return Err(not_ours("format 0".into())); + } + Ok((version, applied)) + } + + /// Bring a file of format `version` up to this build's; `applied` is its `format_pending` + /// (both from [`Family::take_version`]): the changes of its format it already has, when it + /// was written while they were pending. The others' steps run first, and already-applied + /// changes never run again at their later number. A file past this build's number has no + /// steps to run. + pub fn upgrade(&self, v: &mut Value, version: u32, applied: Option<&[String]>) -> Result<(), E> { + let formats = &self.formats; + if version == 0 { + return Err(E::from(FormatError::Invalid(format!("not a {} {} (format 0)", self.app, self.noun)))); + } + // A list beside a format that isn't made of changes is ignored, like any field an upgrade + // drops. + let applied = applied.filter(|_| formats.parts(version).is_some()); + let already_applied = + |part: &Part| applied.is_some_and(|names| names.iter().any(|name| self.canonical_applied_name(version, name) == part.name)); + if applied.is_some() { + for part in formats.parts(version).unwrap_or_default().iter().filter(|part| !already_applied(part)) { + part.step.map_or(Ok(()), |step| step(v))?; + } + } + for from in version..self.current() { + match formats.hand.get(from as usize - 1) { + Some(step) => step(v)?, + None => { + for part in formats.parts(from + 1).unwrap_or_default().iter().filter(|part| !already_applied(part)) { + part.step.map_or(Ok(()), |step| step(v))?; + } + } + } + } + Ok(()) + } +} + +/// Take a short list of names out of a file's JSON: its `format_pending` (the pending changes it +/// has). +fn take_names(v: &mut Value, key: &str, noun: &str) -> Result>, FormatError> { + let Some(list) = v.as_object_mut().and_then(|o| o.remove(key)) else { return Ok(None) }; + let invalid = || FormatError::Invalid(format!("damaged {noun}: `{key}` is not a short list of names")); + let list = list.as_array().filter(|l| l.len() <= 1000).ok_or_else(invalid)?; + list.iter().map(|n| n.as_str().filter(|n| n.len() <= 128).map(str::to_string).ok_or_else(invalid)).collect::>().map(Some) +} + +#[cfg(test)] +#[path = "lib_tests.rs"] +mod tests; diff --git a/crates/format/src/lib_tests.rs b/crates/format/src/lib_tests.rs new file mode 100644 index 000000000..6874ddbf4 --- /dev/null +++ b/crates/format/src/lib_tests.rs @@ -0,0 +1,134 @@ +use super::*; +use serde_json::json; + +/// The app's error, as an app has one. +#[derive(Debug, PartialEq)] +struct AppError(String); + +impl From for AppError { + fn from(e: FormatError) -> Self { + AppError(e.to_string()) + } +} + +/// Each step appends its name to the file's `log`, so the order steps ran in can be read back. +fn log(v: &mut Value, step: &str) { + if let Some(list) = v.get_mut("log").and_then(Value::as_array_mut) { + list.push(json!(step)); + } +} + +const HAND: [Step; 2] = [ + |v| { + log(v, "1to2"); + Ok(()) + }, + |v| { + log(v, "2to3"); + Ok(()) + }, +]; +const V4: [Part; 2] = [ + Part { + name: "a", + step: Some(|v| { + log(v, "a"); + Ok(()) + }), + }, + Part { name: "b", step: None }, +]; +const V5: [Part; 1] = [Part { + name: "c", + step: Some(|v| { + log(v, "c"); + Ok(()) + }), +}]; +const FOLDED: [(u32, &[Part]); 2] = [(4, &V4), (5, &V5)]; +const PENDING: [Part; 2] = [ + Part { + name: "d", + step: Some(|v| { + log(v, "d"); + Ok(()) + }), + }, + Part { + name: "e", + step: Some(|v| { + log(v, "e"); + Ok(()) + }), + }, +]; +const ALIASES: [Alias; 1] = [Alias { format: 5, name: "old-c", known_as: "c" }]; + +/// Format 1 untagged; hand steps to 3; folded 4 and 5; pending changes make 6. +const FAMILY: Family<'static, AppError> = Family { + app: "App", + noun: "design", + prefix: "app/", + legacy_prefix: Some("old/"), + untagged: Some(1), + aliases: &ALIASES, + formats: Formats { hand: &HAND, folded: &FOLDED, pending: &PENDING }, +}; + +fn steps_run(version: u32, applied: Option<&[String]>) -> Vec { + let mut v = json!({"log": []}); + FAMILY.upgrade(&mut v, version, applied).unwrap(); + v["log"].as_array().unwrap().iter().map(|s| s.as_str().unwrap().to_string()).collect() +} + +#[test] +fn tags_and_numbers() { + assert_eq!(FAMILY.current(), 6); + assert_eq!(FAMILY.format_string(6), "app/6"); + assert_eq!(FAMILY.version_of("app/4"), Some(4)); + assert_eq!(FAMILY.version_of("old/3"), Some(3), "the legacy tag is read"); + assert_eq!(FAMILY.version_of("other/3"), None); + assert_eq!(FAMILY.pending_names(), vec!["d".to_string(), "e".to_string()]); +} + +#[test] +fn a_file_is_taken_apart_or_refused_with_the_apps_words() { + let mut v = json!({"format": "app/6", "format_pending": ["d"], "x": 1}); + assert_eq!(FAMILY.take_version(&mut v), Ok((6, Some(vec!["d".to_string()])))); + assert!(v.get("format_pending").is_none(), "taken out"); + assert_eq!(FAMILY.take_version(&mut json!({})), Ok((1, None)), "untagged"); + let refused = |mut v: Value| FAMILY.take_version(&mut v).unwrap_err().0; + assert_eq!(refused(json!([])), "not a App design (expected a JSON object)"); + assert_eq!(refused(json!({"format": "other/2"})), "not a App design (format `other/2`)"); + assert_eq!(refused(json!({"format": 2})), "not a App design (format is not a string)"); + assert_eq!(refused(json!({"format": "app/0"})), "not a App design (format 0)"); + assert_eq!(refused(json!({"format": "app/2", "format_pending": [1]})), "damaged design: `format_pending` is not a short list of names"); +} + +#[test] +fn every_step_runs_once_in_order() { + assert_eq!(steps_run(1, None), ["1to2", "2to3", "a", "c", "d", "e"]); + assert_eq!(steps_run(4, None), ["c", "d", "e"]); + assert_eq!(steps_run(6, None), Vec::::new()); + // A file written while `d` was pending has it: only `e` runs. + assert_eq!(steps_run(6, Some(&["d".to_string()])), ["e"]); + // A file of format 5 written while `c` was still pending, without it: `c` runs first. + assert_eq!(steps_run(5, Some(&[])), ["c", "d", "e"]); + // Under its other spelling `c` counts as had. + assert_eq!(steps_run(5, Some(&["old-c".to_string()])), ["d", "e"]); + // A list beside a hand-written format means nothing. + assert_eq!(steps_run(2, Some(&["d".to_string()])), ["2to3", "a", "c", "d", "e"]); + let mut v = json!({}); + assert_eq!(FAMILY.upgrade(&mut v, 0, None), Err(AppError("not a App design (format 0)".into()))); +} + +#[test] +fn a_newer_file_is_told_by_its_number_or_an_unknown_change() { + assert_eq!(FAMILY.newer(6, None), None); + assert_eq!(FAMILY.newer(6, Some(&["d".to_string()])), None); + assert_eq!(FAMILY.newer(7, None), Some(Newer { format: 7, reads_up_to: 6, unknown_changes: Vec::new() })); + assert_eq!(FAMILY.newer(6, Some(&["z".to_string()])), Some(Newer { format: 6, reads_up_to: 6, unknown_changes: vec!["z".to_string()] })); + assert_eq!(FAMILY.newer(5, Some(&["old-c".to_string()])), None, "an alias of a known change"); + assert_eq!(FAMILY.newer(4, Some(&["old-c".to_string()])), Some(Newer { format: 4, reads_up_to: 6, unknown_changes: vec!["old-c".to_string()] })); + assert_eq!(FAMILY.newer(2, Some(&["z".to_string()])), None, "a list beside a hand-written format means nothing"); +} diff --git a/crates/format/src/newer.rs b/crates/format/src/newer.rs new file mode 100644 index 000000000..e9cb51eb1 --- /dev/null +++ b/crates/format/src/newer.rs @@ -0,0 +1,401 @@ +//! A file a newer build saved: it opens, with a warning, and saving it loses nothing. +//! +//! A newer format number, or a change the file names that this build doesn't have, says a newer +//! build saved the file ([`crate::Family::newer`]). It may use nothing this build lacks, so the app +//! reads it as usual. When part of it can't be read, that part stays out of the way and the rest +//! opens: the app reads the elements of its lists it can ([`NewerFile::keep_element`]), then any +//! other top-level section it can't read is left out whole ([`leave_out_unreadable`], +//! [`read_around`]), and a field it doesn't know, which typed reading would drop, is noticed by +//! comparing the file with what was read ([`NewerFile::compare`]). +//! +//! All of these are named in [`NewerFile::not_understood`] and go back into the file when it is +//! saved ([`NewerFile::restore_into`]), as they came. What can't be put back because the file was +//! changed around it is what `restore_into` returns. + +use std::collections::BTreeMap; +use std::sync::Arc; + +use serde_json::{Map, Value, json}; + +use crate::Newer; + +/// The most sections left out one at a time to find the one a file can't be read with. +const MAX_SECTION_TRIES: usize = 64; + +/// What the file says and holds that this build doesn't read. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct NewerFile { + /// The app, as the notice names it. + pub app: &'static str, + /// The number the file says. + pub format: u32, + /// The number this build reads up to. + pub reads_up_to: u32, + /// The changes the file names that this build doesn't have. + pub unknown_changes: Vec, + /// What this build couldn't read, by name. + pub not_understood: Vec, + /// Fields known records lost in typed reading. + kept: Option, + /// Top-level sections left out whole. + sections: Vec
, + /// Elements left out of a top-level list: its key and the element. + elements: Vec<(String, Value)>, + /// The parts of a container this build has no use for: name and bytes. A blob only one of the + /// kept pieces refers to is one of them. + pub parts: Vec<(String, Arc<[u8]>)>, + /// The file's `container.json`, when this build doesn't know what it says. + pub container: Option, +} + +#[derive(Clone, Debug, PartialEq)] +struct Section { + key: String, + value: Value, + /// This build's record of the section, without the file's: while it is unchanged, the file's + /// goes back. + empty: Option, +} + +/// The fields of a record that typed reading dropped. +#[derive(Clone, Debug, PartialEq)] +enum Kept { + Field(Value), + Fields(BTreeMap), + Items(Vec<(Anchor, Kept)>), +} + +/// Which element of a list some kept fields belong to. +#[derive(Clone, Debug, PartialEq)] +enum Anchor { + Id(u64), + Name(String), + /// Its place, good only while the list keeps its length. + Index { + at: usize, + of: usize, + }, +} + +impl NewerFile { + /// A file of `app` that `newer` says a newer build saved, nothing left out of it yet. + pub fn new(app: &'static str, newer: &Newer) -> NewerFile { + NewerFile { + app, + format: newer.format, + reads_up_to: newer.reads_up_to, + unknown_changes: newer.unknown_changes.clone(), + ..NewerFile::default() + } + } + + /// What to tell the user, whatever else is said. + pub fn notice(&self) -> String { + let (app, reads, format) = (self.app, self.reads_up_to, self.format); + match self.unknown_changes.first() { + Some(change) if format <= reads => { + format!("Saved by a newer {app} (format {format} with `{change}`, which this version doesn't know). If something's missing, update.") + } + _ => format!("Saved by a newer {app} (format {format}, this version reads up to {reads}). If something's missing, update."), + } + } + + /// Every line to report: the notice, then what couldn't be read, by name. + pub fn warnings(&self) -> Vec { + let unread = self.not_understood.iter().map(|what| format!("Not read: {what}. Saving keeps it.")); + std::iter::once(self.notice()).chain(unread).collect() + } + + /// What a reply says about it. + pub fn report(&self) -> Value { + json!({ + "format": self.format, + "reads_up_to": self.reads_up_to, + "unknown_changes": self.unknown_changes, + "not_understood": self.not_understood, + "notice": self.notice(), + }) + } + + /// Whether the next save needs a container to keep what the file holds: plain JSON has no room + /// for parts beside the file's own. + pub fn needs_container(&self) -> bool { + !self.parts.is_empty() + } + + /// Whether anything kept back names this text (a blob's name in a container). + pub fn mentions(&self, text: &str) -> bool { + fn kept(k: &Kept, text: &str) -> bool { + match k { + Kept::Field(v) => value_mentions(v, text), + Kept::Fields(m) => m.values().any(|x| kept(x, text)), + Kept::Items(l) => l.iter().any(|(_, x)| kept(x, text)), + } + } + self.kept.as_ref().is_some_and(|k| kept(k, text)) + || self.sections.iter().any(|s| value_mentions(&s.value, text)) + || self.elements.iter().any(|(_, v)| value_mentions(v, text)) + } + + /// Say that a section the reader couldn't finish reading is left out. `empty` is what the + /// app writes for the section while it holds nothing, if anything. + pub fn keep_section(&mut self, key: &str, value: Value, empty: Option, why: &str) { + self.not_understood.push(format!("section `{key}` ({why})")); + self.sections.push(Section { key: key.into(), value, empty }); + } + + /// Say that an element of the top-level list `key` is left out, as `note` names it; it goes + /// back at the end of the list when the file is saved. + pub fn keep_element(&mut self, key: &str, element: Value, note: String) { + self.not_understood.push(note); + self.elements.push((key.into(), element)); + } + + /// Compare the file as it reads (`file`, after the same upgrade as what was read) with what was + /// read of it (`known`, its typed record written out): what `known` lacks is kept and named. + /// An object whose `type` is `placeholder_tag` (an element the app kept whole) and the fields + /// in `container_only` (what a container adds beside the file's own) are not compared; nor + /// are the top level's `format` and `format_pending`. + pub fn compare(&mut self, file: &Value, known: &Value, placeholder_tag: &str, container_only: &[&str]) { + let mut paths = Vec::new(); + self.kept = vanished(file, known, "", &mut paths, placeholder_tag, container_only); + self.not_understood.extend(paths); + for section in &mut self.sections { + section.empty = known.get(§ion.key).cloned(); + } + } + + /// Write back what was kept of the file into `value`, the file as this build writes it. + /// Returns what couldn't go back, because the file was changed around it. + pub fn restore_into(&self, value: &mut Value) -> Vec { + let mut lost = Vec::new(); + if let Some(kept) = &self.kept { + apply(kept, value, "", &mut lost); + } + if let Some(top) = value.as_object_mut() { + for section in &self.sections { + if top.get(§ion.key) == section.empty.as_ref() { + top.insert(section.key.clone(), section.value.clone()); + } else { + lost.push(format!("section `{}`, replaced by what was edited here", section.key)); + } + } + for (key, element) in &self.elements { + let name = element.get("name"); + match top.entry(key.clone()).or_insert_with(|| json!([])) { + Value::Array(list) if name.is_none() || !list.iter().any(|x| x.get("name") == name) => list.push(element.clone()), + _ => lost.push(format!("`{key}` element {}, replaced by what was made here", name.and_then(Value::as_str).unwrap_or("unnamed"))), + } + } + } + lost + } +} + +fn value_mentions(v: &Value, text: &str) -> bool { + match v { + Value::String(s) => s == text, + Value::Array(a) => a.iter().any(|x| value_mentions(x, text)), + Value::Object(o) => o.values().any(|x| value_mentions(x, text)), + _ => false, + } +} + +/// The first line of a reader's error, without the list of every kind it knows, and without the +/// `" file: "` its reader starts it with. +pub fn short<'a>(why: &'a str, noun: &str) -> &'a str { + let why = why.split(", expected").next().unwrap_or(why); + why.strip_prefix(&format!("{noun} file: ")).unwrap_or(why) +} + +/// Leave a section out and keep it. A section the file needs is left empty. +fn move_out(top: &mut Map, key: &str, why: &str, noun: &str, file: &mut NewerFile) { + let Some(value) = top.remove(key) else { return }; + file.not_understood.push(format!("section `{key}` ({})", short(why, noun))); + file.sections.push(Section { key: key.into(), value, empty: None }); +} + +/// Every top-level section of `top` that doesn't read by itself (`piece`, the app's reading of a +/// file holding just that section) is left out and kept in `file`. `noun` is what a file of the +/// app's is called, which its reader's errors start with. +pub fn leave_out_unreadable( + top: &mut Map, + file: &mut NewerFile, + noun: &str, + piece: impl Fn(&str, &Value) -> Result<(), E>, +) { + let keys: Vec = top.keys().cloned().collect(); + for key in &keys { + let value = top.get(key).cloned().unwrap_or_default(); + if let Err(why) = piece(key, &value) { + move_out(top, key, &why.to_string(), noun, file); + } + } +} + +/// Read `top` with `attempt`, leaving out the sections it can't be read with: if it doesn't read, +/// each section but the `core` ones (which the file can't be read without) is tried left out alone, +/// and as a last resort every one of them is. What is left out is kept in `file`. The error is the +/// first attempt's, when even the core alone doesn't read. +pub fn read_around( + top: &mut Map, + file: &mut NewerFile, + core: &[&str], + noun: &str, + attempt: impl Fn(&Map) -> Result, +) -> Result { + let first = match attempt(top) { + Ok(doc) => return Ok(doc), + Err(why) => why.to_string(), + }; + // Sections that are fine by themselves but not together with the rest. + let keys: Vec = top.keys().filter(|k| !core.contains(&k.as_str())).cloned().collect(); + // Each try reads the whole file: a file of many sections goes straight to the last resort. + for key in keys.iter().filter(|_| keys.len() <= MAX_SECTION_TRIES) { + let mut without = top.clone(); + without.remove(key); + if let Ok(doc) = attempt(&without) { + move_out(top, key, &first, noun, file); + return Ok(doc); + } + } + let mut bare = top.clone(); + bare.retain(|key, _| core.contains(&key.as_str())); + match attempt(&bare) { + Ok(doc) => { + for key in &keys { + move_out(top, key, &first, noun, file); + } + Ok(doc) + } + Err(_) => Err(first), + } +} + +/// A value a writer leaves out without losing anything: not worth telling anyone about. +pub fn looks_default(v: &Value) -> bool { + match v { + Value::Null => true, + Value::Bool(b) => !b, + Value::Number(n) => n.as_f64() == Some(0.0), + Value::String(s) => s.is_empty(), + Value::Array(a) => a.is_empty(), + Value::Object(o) => o.is_empty(), + } +} + +/// What `raw` has that `known`, what was read of it, doesn't. `paths` gets those fields' names. +fn vanished(raw: &Value, known: &Value, path: &str, paths: &mut Vec, placeholder_tag: &str, container_only: &[&str]) -> Option { + match (raw, known) { + (Value::Object(raw), Value::Object(known)) => { + if known.get("type").and_then(Value::as_str) == Some(placeholder_tag) { + return None; + } + let mut kept = BTreeMap::new(); + for (key, value) in raw { + if container_only.contains(&key.as_str()) || (path.is_empty() && matches!(key.as_str(), "format" | "format_pending")) { + continue; + } + let inner = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; + match known.get(key) { + None => { + if !looks_default(value) { + paths.push(format!("field `{inner}`")); + } + kept.insert(key.clone(), Kept::Field(value.clone())); + } + Some(known) => { + if let Some(k) = vanished(value, known, &inner, paths, placeholder_tag, container_only) { + kept.insert(key.clone(), k); + } + } + } + } + (!kept.is_empty()).then_some(Kept::Fields(kept)) + } + (Value::Array(raw), Value::Array(known)) => { + let mut items = Vec::new(); + for (at, element) in raw.iter().enumerate() { + let anchor = anchor_of(element).unwrap_or(Anchor::Index { at, of: raw.len() }); + let Some(partner) = find(known, &anchor) else { continue }; + let label = match (element.get("name").and_then(Value::as_str), &anchor) { + (Some(name), _) => format!("{path}[{name}]"), + (None, Anchor::Id(id)) => format!("{path}[{id}]"), + _ => format!("{path}[{at}]"), + }; + if let Some(k) = vanished(element, partner, &label, paths, placeholder_tag, container_only) { + items.push((anchor, k)); + } + } + (!items.is_empty()).then_some(Kept::Items(items)) + } + _ => None, + } +} + +fn anchor_of(element: &Value) -> Option { + if let Some(id) = element.get("id").and_then(Value::as_u64) { + return Some(Anchor::Id(id)); + } + element.get("name").and_then(Value::as_str).map(|name| Anchor::Name(name.to_string())) +} + +fn find<'a>(list: &'a [Value], anchor: &Anchor) -> Option<&'a Value> { + match anchor { + Anchor::Id(id) => list.iter().find(|x| x.get("id").and_then(Value::as_u64) == Some(*id)), + Anchor::Name(name) => list.iter().find(|x| x.get("name").and_then(Value::as_str) == Some(name)), + Anchor::Index { at, of } => (list.len() == *of).then(|| list.get(*at)).flatten(), + } +} + +fn find_mut<'a>(list: &'a mut [Value], anchor: &Anchor) -> Option<&'a mut Value> { + match anchor { + Anchor::Id(id) => list.iter_mut().find(|x| x.get("id").and_then(Value::as_u64) == Some(*id)), + Anchor::Name(name) => list.iter_mut().find(|x| x.get("name").and_then(Value::as_str) == Some(name)), + Anchor::Index { at, of } => (list.len() == *of).then(|| list.get_mut(*at)).flatten(), + } +} + +/// Put the kept fields back. An element that is gone was deleted here, its fields with it; one +/// whose place can't be told any more, and a field whose record is gone, go into `lost`. +fn apply(kept: &Kept, value: &mut Value, path: &str, lost: &mut Vec) { + match kept { + Kept::Field(_) => {} + Kept::Fields(fields) => { + let Some(object) = value.as_object_mut() else { + lost.push(format!("field `{path}`")); + return; + }; + for (key, sub) in fields { + let inner = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; + match (sub, object.get_mut(key)) { + (Kept::Field(v), None) => { + object.insert(key.clone(), v.clone()); + } + (Kept::Field(_), Some(_)) => {} + (sub, Some(inner_value)) => apply(sub, inner_value, &inner, lost), + // The list it was in is empty and not written: its elements were deleted. + (Kept::Items(_), None) => {} + (_, None) => lost.push(format!("field `{inner}`")), + } + } + } + Kept::Items(items) => { + let Some(list) = value.as_array_mut() else { + lost.push(format!("field `{path}`")); + return; + }; + for (anchor, sub) in items { + match (find_mut(list, anchor), anchor) { + (Some(element), _) => apply(sub, element, path, lost), + (None, Anchor::Index { at, .. }) => lost.push(format!("element {at} of `{path}`")), + (None, _) => {} + } + } + } + } +} + +#[cfg(test)] +#[path = "newer_tests.rs"] +mod tests; diff --git a/crates/format/src/newer_tests.rs b/crates/format/src/newer_tests.rs new file mode 100644 index 000000000..90e5b0037 --- /dev/null +++ b/crates/format/src/newer_tests.rs @@ -0,0 +1,48 @@ +use super::*; + +fn newer() -> Newer { + Newer { format: 9, reads_up_to: 8, unknown_changes: Vec::new() } +} + +/// What typed reading dropped is named and goes back on saving, where it was. +#[test] +fn dropped_fields_are_named_and_put_back() { + let file = json!({"name": "A", "format": "app/9", "items": [{"id": 1, "size": 2, "colour": "red"}], "extra": {"x": 1}}); + let known = json!({"name": "A", "items": [{"id": 1, "size": 2}]}); + let mut said = NewerFile::new("App", &newer()); + said.compare(&file, &known, "placeholder", &[]); + assert_eq!(said.not_understood, ["field `extra`", "field `items[1].colour`"]); + let mut saved = json!({"name": "A", "items": [{"id": 1, "size": 3}]}); + assert!(said.restore_into(&mut saved).is_empty()); + assert_eq!(saved, json!({"name": "A", "items": [{"id": 1, "size": 3, "colour": "red"}], "extra": {"x": 1}})); + assert_eq!(said.notice(), "Saved by a newer App (format 9, this version reads up to 8). If something's missing, update."); +} + +/// A section that can't be read is left out, kept, and goes back while it is unchanged here. +#[test] +fn unreadable_sections_are_left_out_and_kept() { + let mut top = match json!({"name": "A", "good": 1, "bad": 2}) { + Value::Object(m) => m, + _ => unreachable!(), + }; + let mut said = NewerFile::new("App", &newer()); + leave_out_unreadable(&mut top, &mut said, "design", |key: &str, _: &Value| if key == "bad" { Err("design file: no") } else { Ok(()) }); + assert!(!top.contains_key("bad")); + assert_eq!(said.not_understood, ["section `bad` (no)"]); + let read = + read_around( + &mut top, + &mut said, + &["name"], + "design", + |top: &Map| { + if top.contains_key("good") { Err("design file: clash") } else { Ok(top.len()) } + }, + ); + assert_eq!(read, Ok(1)); + assert_eq!(said.not_understood, ["section `bad` (no)", "section `good` (clash)"]); + let mut saved = json!({"name": "A"}); + said.compare(&saved.clone(), &saved.clone(), "placeholder", &[]); + assert!(said.restore_into(&mut saved).is_empty()); + assert_eq!(saved, json!({"name": "A", "good": 1, "bad": 2})); +} From 939146a5b159a268ee5fc67e26b3dc915b4d4094 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:14:11 +0000 Subject: [PATCH 030/165] tga dpx: share uncompressed RGBA8 export --- crates/dpx/src/lib.rs | 3 + crates/dpx/src/rgba8_dpx10.rs | 105 ++++++++++++++++++++++++++++++++++ crates/tga/src/lib.rs | 3 + crates/tga/src/rgba8_raw.rs | 60 +++++++++++++++++++ 4 files changed, 171 insertions(+) create mode 100644 crates/dpx/src/rgba8_dpx10.rs create mode 100644 crates/tga/src/rgba8_raw.rs diff --git a/crates/dpx/src/lib.rs b/crates/dpx/src/lib.rs index a762566f8..26d9e8656 100644 --- a/crates/dpx/src/lib.rs +++ b/crates/dpx/src/lib.rs @@ -34,6 +34,9 @@ //! Input is treated as hostile: every header read is bounds-checked, the picture size is capped //! by [`Limits`] and the image data must be present in full before anything is allocated. +/// RGBA8-to-10-bit DPX encoding. +pub mod rgba8_dpx10; + #[cfg(test)] mod tests; diff --git a/crates/dpx/src/rgba8_dpx10.rs b/crates/dpx/src/rgba8_dpx10.rs new file mode 100644 index 000000000..6ec5e23b4 --- /dev/null +++ b/crates/dpx/src/rgba8_dpx10.rs @@ -0,0 +1,105 @@ +//! Uncompressed RGB(A) output from top-down RGBA8 pixels. +/// Why the supplied frame cannot be encoded. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Rgba8EncodeError { + /// Empty, overflowing, or mismatched dimensions. + FrameSize, + /// A dimension cannot fit the output format. + TooLarge, +} +fn checked_len(rgba: &[u8], w: u32, h: u32) -> std::result::Result { + let n = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(4)).ok_or(Rgba8EncodeError::FrameSize)?; + if w == 0 || h == 0 || rgba.len() != n { + return Err(Rgba8EncodeError::FrameSize); + } + Ok(n) +} +/// Header size of the DPX files we write (file + image + orientation + film + TV headers). +const DPX_HEADER: usize = 2048; + +/// A DPX file: 10-bit RGB (8-bit values widened by bit replication, so 0 → 0 and 255 → 1023). +pub fn encode_rgba8_dpx10(rgba: &[u8], w: u32, h: u32, creator: &str) -> std::result::Result, Rgba8EncodeError> { + let n = checked_len(rgba, w, h)?; + // one 32-bit word per pixel; `n` is already `w * h * 4` + let size = n.checked_add(DPX_HEADER).ok_or_else(|| Rgba8EncodeError::FrameSize)?; + let file_size = u32::try_from(size).map_err(|_| Rgba8EncodeError::TooLarge)?; + // SMPTE ST 268: undefined numeric fields are all ones, undefined text fields are NUL + let mut hd = vec![0xFF_u8; DPX_HEADER]; + for (a, b) in [ + (36, 660), // file name, creation time, creator, project, copyright + (664, 768), // reserved + (1356, 1408), // reserved + (1432, 1620), // source file name, time, input device, serial number + (1644, 1664), // reserved + (1664, 1712), // film manufacturer, type, offset, prefix, count, format + (1732, 1920), // frame id, slate, reserved + (1972, 2048), // reserved + ] { + hd[a..b].fill(0); + } + for e in 0..8 { + let d = 780 + e * 72 + 40; + hd[d..d + 32].fill(0); // element descriptions + } + let put32 = |hd: &mut Vec, at: usize, v: u32| hd[at..at + 4].copy_from_slice(&v.to_be_bytes()); + let put16 = |hd: &mut Vec, at: usize, v: u16| hd[at..at + 2].copy_from_slice(&v.to_be_bytes()); + // file information header + hd[0..4].copy_from_slice(b"SDPX"); + put32(&mut hd, 4, DPX_HEADER as u32); // offset to the image data + hd[8..16].copy_from_slice(b"V2.0\0\0\0\0"); + put32(&mut hd, 16, file_size); + put32(&mut hd, 20, 1); // ditto key: new frame + put32(&mut hd, 24, 1664); // generic header length + put32(&mut hd, 28, 384); // industry header length + put32(&mut hd, 32, 0); // user data length + let creator = creator.as_bytes(); + let n = creator.len().min(100); + hd[160..160 + n].copy_from_slice(&creator[..n]); + // image information header + put16(&mut hd, 768, 0); // orientation: left to right, top to bottom + put16(&mut hd, 770, 1); // one image element + put32(&mut hd, 772, w); + put32(&mut hd, 776, h); + let el = 780; + put32(&mut hd, el, 0); // unsigned + put32(&mut hd, el + 4, 0); // reference low data code + put32(&mut hd, el + 12, 1023); // reference high data code + hd[el + 20] = 50; // descriptor: RGB + hd[el + 21] = 6; // transfer: ITU-R BT.709 + hd[el + 22] = 6; // colorimetric: ITU-R BT.709 + hd[el + 23] = 10; // bit depth + put16(&mut hd, el + 24, 1); // packing: filled to 32-bit words, method A + put16(&mut hd, el + 26, 0); // no encoding (uncompressed) + put32(&mut hd, el + 28, DPX_HEADER as u32); // offset to the element's data + put32(&mut hd, el + 32, 0); // end-of-line padding + put32(&mut hd, el + 36, 0); // end-of-image padding + // image orientation header: no offset, square pixels + put32(&mut hd, 1408, 0); + put32(&mut hd, 1412, 0); + put32(&mut hd, 1424, w); + put32(&mut hd, 1428, h); + put32(&mut hd, 1628, 1); + put32(&mut hd, 1632, 1); + // television header: progressive + hd[1928] = 0; + let mut out = Vec::with_capacity(size); + out.extend_from_slice(&hd); + let ten = |v: u8| (u32::from(v) << 2) | (u32::from(v) >> 6); + for &[r, g, b, _] in rgba.as_chunks::<4>().0 { + out.extend_from_slice(&((ten(r) << 22) | (ten(g) << 12) | (ten(b) << 2)).to_be_bytes()); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn packed_rgb_and_creator() { + let bytes = encode_rgba8_dpx10(&[255, 0, 128, 255], 1, 1, "FilmCraft").unwrap(); + assert_eq!(&bytes[..4], b"SDPX"); + assert_eq!(&bytes[160..169], b"FilmCraft"); + assert_eq!(&bytes[2048..], &((1023u32 << 22) | (514u32 << 2)).to_be_bytes()); + assert_eq!(encode_rgba8_dpx10(&[], 0, 1, ""), Err(Rgba8EncodeError::FrameSize)); + } +} diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index ac9d21497..3a92052ff 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -18,6 +18,9 @@ //! Input is treated as hostile: the picture size is capped by [`Limits`], and a run-length file //! must be long enough to hold the pixels its header declares before anything is allocated. +/// Uncompressed RGBA8-to-Targa encoding. +pub mod rgba8_raw; + #[cfg(test)] mod tests; diff --git a/crates/tga/src/rgba8_raw.rs b/crates/tga/src/rgba8_raw.rs new file mode 100644 index 000000000..acec4b9bc --- /dev/null +++ b/crates/tga/src/rgba8_raw.rs @@ -0,0 +1,60 @@ +//! Uncompressed RGB(A) output from top-down RGBA8 pixels. +/// Why the supplied frame cannot be encoded. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Rgba8EncodeError { + /// Empty, overflowing, or mismatched dimensions. + FrameSize, + /// A dimension cannot fit the 16-bit Targa header. + Dimensions, +} +fn checked_len(rgba: &[u8], w: u32, h: u32) -> std::result::Result { + let n = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(4)).ok_or(Rgba8EncodeError::FrameSize)?; + if w == 0 || h == 0 || rgba.len() != n { + return Err(Rgba8EncodeError::FrameSize); + } + Ok(n) +} +/// An uncompressed Targa file: 24-bit BGR, or 32-bit BGRA with `alpha` (straight alpha, as the +/// frame carries it). +pub fn encode_rgba8_raw(rgba: &[u8], w: u32, h: u32, alpha: bool) -> std::result::Result, Rgba8EncodeError> { + checked_len(rgba, w, h)?; + let (tw, th) = match (u16::try_from(w), u16::try_from(h)) { + (Ok(tw), Ok(th)) => (tw, th), + _ => return Err(Rgba8EncodeError::Dimensions), + }; + let bpp: usize = if alpha { 4 } else { 3 }; + let row = w as usize * 4; + let mut out = Vec::with_capacity(18 + w as usize * h as usize * bpp + 26); + out.extend_from_slice(&[0, 0, 2]); // no ID, no colour map, uncompressed true-colour + out.extend_from_slice(&[0; 5]); // colour map specification (unused) + out.extend_from_slice(&[0, 0, 0, 0]); // x / y origin + out.extend_from_slice(&tw.to_le_bytes()); + out.extend_from_slice(&th.to_le_bytes()); + out.push(if alpha { 32 } else { 24 }); + out.push(if alpha { 8 } else { 0 }); // attribute bits; bottom-left origin + // bottom-left origin: the last frame row comes first + for line in rgba.chunks_exact(row).rev() { + for &[r, g, b, a] in line.as_chunks::<4>().0 { + out.extend_from_slice(&[b, g, r]); + if alpha { + out.push(a); + } + } + } + // TGA 2.0 footer without extension or developer areas + out.extend_from_slice(&[0; 8]); + out.extend_from_slice(b"TRUEVISION-XFILE.\0"); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn raw_round_trip() { + let bytes = encode_rgba8_raw(&[1, 2, 3, 4], 1, 1, true).unwrap(); + assert_eq!(&bytes[18..22], &[3, 2, 1, 4]); + assert_eq!(&bytes[bytes.len() - 18..], b"TRUEVISION-XFILE.\0"); + assert_eq!(encode_rgba8_raw(&[], 0, 1, false), Err(Rgba8EncodeError::FrameSize)); + } +} From 9c3c82e1c63e53248f99531a71cb8401f5c76150 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:04 +0000 Subject: [PATCH 031/165] audio: fix PCM export module documentation --- crates/audio/src/pcm_export.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/audio/src/pcm_export.rs b/crates/audio/src/pcm_export.rs index c8456d785..14e45783b 100644 --- a/crates/audio/src/pcm_export.rs +++ b/crates/audio/src/pcm_export.rs @@ -2,8 +2,8 @@ //! 16, 24 or 32-bit integer or 32-bit float ([`SampleFormat`]), for streaming export. //! Float WAV is `WAVE_FORMAT_IEEE_FLOAT` with a `fact` chunk; float AIFF is AIFF-C (`fl32`). //! -//! The header is written first from the known length ([`header`]), then the samples in chunks -//! ([`encode`]) and the pad byte ([`pad`]), so an export streams to disk instead of building the +//! The header is written first from the known length (`header`), then the samples in chunks +//! (`encode`) and the pad byte (`pad`), so an export streams to disk instead of building the //! file in memory. /// PCM representation in an exported file. From 2aa7f7f8d211786650d6cc3a4d3f6be165ddb30a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:22:05 +0000 Subject: [PATCH 032/165] dpx: fix RGBA writer lint --- crates/dpx/src/rgba8_dpx10.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/dpx/src/rgba8_dpx10.rs b/crates/dpx/src/rgba8_dpx10.rs index 6ec5e23b4..05ce20b15 100644 --- a/crates/dpx/src/rgba8_dpx10.rs +++ b/crates/dpx/src/rgba8_dpx10.rs @@ -21,7 +21,7 @@ const DPX_HEADER: usize = 2048; pub fn encode_rgba8_dpx10(rgba: &[u8], w: u32, h: u32, creator: &str) -> std::result::Result, Rgba8EncodeError> { let n = checked_len(rgba, w, h)?; // one 32-bit word per pixel; `n` is already `w * h * 4` - let size = n.checked_add(DPX_HEADER).ok_or_else(|| Rgba8EncodeError::FrameSize)?; + let size = n.checked_add(DPX_HEADER).ok_or(Rgba8EncodeError::FrameSize)?; let file_size = u32::try_from(size).map_err(|_| Rgba8EncodeError::TooLarge)?; // SMPTE ST 268: undefined numeric fields are all ones, undefined text fields are NUL let mut hd = vec![0xFF_u8; DPX_HEADER]; From 159b942defe3613c91a4beec5fadfcb1593f2600 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:24:27 +0000 Subject: [PATCH 033/165] Share contextual directional text shaping --- Cargo.lock | 1 + crates/font-catalog/Cargo.toml | 1 + crates/font-catalog/src/lib.rs | 2 + crates/font-catalog/src/shape.rs | 150 +++++++++++++++++++++++++++++++ 4 files changed, 154 insertions(+) create mode 100644 crates/font-catalog/src/shape.rs diff --git a/Cargo.lock b/Cargo.lock index 9424cf3fe..3e1487dca 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1761,6 +1761,7 @@ name = "craft-font-catalog" version = "0.1.0" dependencies = [ "fontique", + "harfrust 0.13.3", "kurbo 0.13.1", "skrifa 0.47.0", "thiserror 2.0.21", diff --git a/crates/font-catalog/Cargo.toml b/crates/font-catalog/Cargo.toml index 1f0830a63..c53d871b8 100644 --- a/crates/font-catalog/Cargo.toml +++ b/crates/font-catalog/Cargo.toml @@ -15,6 +15,7 @@ default = ["system"] system = ["dep:fontique"] [dependencies] +harfrust = "0.13" kurbo = { workspace = true } skrifa = { version = "0.47", default-features = false, features = ["std"] } thiserror = { workspace = true } diff --git a/crates/font-catalog/src/lib.rs b/crates/font-catalog/src/lib.rs index 7da4ca310..176a38738 100644 --- a/crates/font-catalog/src/lib.rs +++ b/crates/font-catalog/src/lib.rs @@ -26,6 +26,7 @@ mod fontconfig; mod outline; mod registry; mod scan; +mod shape; mod suitcase; pub mod system; @@ -34,6 +35,7 @@ pub use env::{FontEnv, Os, font_dirs, font_store_dir, office_font_dirs}; pub use fontconfig::fontconfig_dirs; pub use outline::{FontOutline, OutlineError}; pub use scan::{FaceInfo, LocalizedName, Source, is_font_file, style_italic, style_weight, style_width}; +pub use shape::{RunGlyph, RunInput, ShapeRunError, shape_run}; #[cfg(test)] mod tests; diff --git a/crates/font-catalog/src/shape.rs b/crates/font-catalog/src/shape.rs new file mode 100644 index 000000000..7fb0814d3 --- /dev/null +++ b/crates/font-catalog/src/shape.rs @@ -0,0 +1,150 @@ +//! Shape a run with its source clusters and surrounding text context. + +use std::sync::Arc; + +use harfrust::{BufferClusterLevel, Direction, Feature, Language, Script, ShapeOptions, ShapePlan, Shaper, UnicodeBuffer}; + +/// Parameters for a single directional run. Text is in logical order and `source_start` is its +/// byte offset in the complete source. Context influences joining but emits no glyphs. +pub struct RunInput<'a> { + /// Text in this run. + pub text: &'a str, + /// Its byte offset in the complete source. + pub source_start: usize, + /// Text before the run, within the same shaping context. + pub pre_context: &'a str, + /// Text after the run, within the same shaping context. + pub post_context: &'a str, + /// Direction of shaping. + pub direction: Direction, + /// Language used for language-specific forms. + pub language: Option<&'a Language>, + /// OpenType features with ranges in source byte coordinates. + pub features: &'a [Feature], + /// Use character-level instead of monotone grapheme clusters. + pub character_clusters: bool, + /// Uppercase each mapped character without losing its source cluster. + pub uppercase: bool, +} + +/// A glyph in design units, with its source-byte cluster and directional advances and offsets. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct RunGlyph { + pub glyph_id: u32, + pub cluster: u32, + pub x_advance: i32, + pub y_advance: i32, + pub x_offset: i32, + pub y_offset: i32, +} + +/// A run's source offsets cannot fit HarfRust's 32-bit clusters. +#[derive(Debug, thiserror::Error)] +#[error("shaping cluster exceeds the 32-bit source offset range")] +pub struct ShapeRunError; + +/// Shape a run using a caller's face-specific plan cache. `map_character` applies digit or other +/// character mapping before case conversion; expansions retain the original byte cluster. +/// The plan callback receives the guessed script, direction, language and feature set so it can +/// reuse plans for the particular shaper and its variable-font instance. +pub fn shape_run( + shaper: &Shaper<'_>, + input: &RunInput<'_>, + mut map_character: impl FnMut(char) -> char, + plan: impl FnOnce(&Shaper<'_>, Direction, Option