From c950dacd39ebfe014dff47271d35ca270f858f4d Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Fri, 13 Nov 2026 23:50:23 -0500 Subject: [PATCH 001/200] craft-xlsx: read row heights, column widths and default sizes of a binary sheet BrtRowHdr fills Row's height, custom height, hidden, outline level, collapsed and style (with thickTop, thickBot and ph kept as the XML reader keeps them); BrtColInfo fills SheetPart::columns; BrtWsFmtInfo fills the new typed Features::format (SheetFormat, mirroring sheetFormatPr), which the .xlsx reader now fills too and to_xml writes from the field. A row's ht follows Excel's .xlsx: set by hand, or differing from the default. Column ranges outside the grid are skipped with a warning, column records are capped at 16,384, and heights past 8,192 twips are ignored. Closes #1254. --- crates/xlsx/README.md | 17 +++-- crates/xlsx/src/features.rs | 32 ++++++++- crates/xlsx/src/lib.rs | 4 +- crates/xlsx/src/xlsb.rs | 130 +++++++++++++++++++++++++++++++++--- crates/xlsx/tests/xlsb.rs | 129 ++++++++++++++++++++++++++++++++++- 5 files changed, 291 insertions(+), 21 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 1dc30574d..367056ef9 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -36,8 +36,9 @@ were. Part names and relationship ids are kept, so a file read and written witho where it did, and writing it twice gives the same bytes. The calculation chain is dropped (Excel rebuilds it). `XlsxKind` is the workbook part's content type (`.xlsx`, `.xlsm`, `.xltx`, `.xltm`). Typed worksheet features (`SheetPart::features`), each mirroring its element with optional -attributes and the unnamed ones kept: sheet views (panes, selections), print setup (options, -margins, page setup, header and footer, page breaks), data validation (also read from the `x14` +attributes and the unnamed ones kept: sheet views (panes, selections), the default sizes +(`sheetFormatPr`), print setup (options, margins, page setup, header and footer, page breaks), +data validation (also read from the `x14` extension), conditional formats (colour scales, data bars, icon sets, rule extensions kept), hyperlinks (with their URLs), the legacy drawing. Comments (`Comments`, from the comments part) and the note shapes of the VML drawing (`NoteShape`). A sheet that gains comments and has no VML @@ -83,8 +84,11 @@ for new pictures (`vm = i + 1`) and the `XLDAPR` dynamic-array metadata (`cm = 1 The parts this crate writes use the transitional namespaces; a strict file's kept parts stay as they were. A binary workbook is not written. -A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not -read (each cell keeps its format index). Its cell formulas are decoded from their tokens into the +A binary workbook gives the same `Workbook`, strings, rows (with their heights, outline levels, +hidden flags and styles), columns, default sizes and merged cells. Its styles are not read (each +cell keeps its format index). The descent Excel records for rows and the sheet +(`x14ac:dyDescent`) is in alternate-content blocks, which are skipped. Its cell formulas are +decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the @@ -102,8 +106,9 @@ other workbooks, Python code stored outside the cell, data tables. The XLSB func (40 million records, 4 million cells and as many shared strings, 256 MiB of text, as `craft-xls` allows). `binary_formula_text`: decoded formula text over the workbook (128 MiB); past it, formulas keep their saved results. A formula's tokens are bounded at 16 KB, its - nesting at 256 levels and an array constant at 65,536 values. Fixed caps: 1024 sheets, 100,000 merged ranges per sheet, 64 nested - extension blocks. + nesting at 256 levels and an array constant at 65,536 values. Fixed caps: 1024 sheets, 100,000 + merged ranges and 16,384 column records per sheet, 64 nested extension blocks. A row taller + than 8,192 twips keeps the default height. - Cells and rows outside the 1,048,576 × 16,384 grid are dropped and counted. SpreadsheetML is read leniently: a damaged optional part is a warning, a damaged worksheet keeps diff --git a/crates/xlsx/src/features.rs b/crates/xlsx/src/features.rs index 17c2c2aab..9bae562b5 100644 --- a/crates/xlsx/src/features.rs +++ b/crates/xlsx/src/features.rs @@ -1,6 +1,7 @@ -//! The worksheet's typed features, each mirroring its SpreadsheetML element: sheet views, print -//! setup, data validation, conditional formatting, hyperlinks (ECMA-376 Part 1, 18.3), and the -//! comments part (18.7) with the legacy note shapes Excel draws comments with. +//! The worksheet's typed features, each mirroring its SpreadsheetML element: sheet views, the +//! sheet's default sizes, print setup, data validation, conditional formatting, hyperlinks +//! (ECMA-376 Part 1, 18.3), and the comments part (18.7) with the legacy note shapes Excel draws +//! comments with. //! //! An attribute the file may leave out is an `Option` (`None`: not written, the schema's //! default applies), so a feature reads and writes back as it was. Attributes a type does not @@ -213,6 +214,27 @@ impl SheetView { } } +// ------------------------------------------------------------------------------- sheet format + +element! { + /// ``: the sheet's default column width and row height, and its outline depth. + pub struct SheetFormat { + /// Characters of the default font's maximum digit width, padding excluded (8 when absent). + base_col_width: u32 = "baseColWidth", + /// Characters, padding included, like [`crate::Column::width`]. + default_col_width: f64 = "defaultColWidth", + /// Points. + default_row_height: f64 = "defaultRowHeight", + custom_height: bool = "customHeight", + /// Rows are hidden unless they say otherwise. + zero_height: bool = "zeroHeight", + thick_top: bool = "thickTop", + thick_bottom: bool = "thickBottom", + outline_level_row: u32 = "outlineLevelRow", + outline_level_col: u32 = "outlineLevelCol", + } +} + // ------------------------------------------------------------------------------- printing element! { @@ -643,6 +665,8 @@ impl Hyperlink { #[derive(Clone, Debug, Default, PartialEq)] pub struct Features { pub views: Vec, + /// `sheetFormatPr`. + pub format: Option, pub print: Print, pub validations: Option, pub conditional_formats: Vec, @@ -660,6 +684,7 @@ impl Features { let attrs_of = |n: &str| root.child(n); Features { views: root.child("sheetViews").map(|v| v.children("sheetView").map(SheetView::read).collect()).unwrap_or_default(), + format: attrs_of("sheetFormatPr").map(SheetFormat::read_attrs), print: Print { options: attrs_of("printOptions").map(PrintOptions::read_attrs), margins: attrs_of("pageMargins").map(PageMargins::read_attrs), @@ -708,6 +733,7 @@ impl Features { let p = &self.print; vec![ ("sheetViews", Vec::from_iter((!self.views.is_empty()).then_some(views))), + ("sheetFormatPr", Vec::from_iter(self.format.as_ref().map(|f| el("sheetFormatPr", &|e| f.write_attrs(e))))), ("conditionalFormatting", self.conditional_formats.iter().map(ConditionalFormatting::to_el).collect()), ("dataValidations", Vec::from_iter(validations)), ("hyperlinks", Vec::from_iter((!self.hyperlinks.is_empty()).then_some(links))), diff --git a/crates/xlsx/src/lib.rs b/crates/xlsx/src/lib.rs index 5a64ae0ab..9105ba886 100644 --- a/crates/xlsx/src/lib.rs +++ b/crates/xlsx/src/lib.rs @@ -75,8 +75,8 @@ pub use document::{Document, DrawingPart, KeptPart, PivotCachePart, PivotTablePa pub use drawing::{Anchor, Drawing, Item, Marker, ObjectKind, Placement}; pub use features::{ Break, CfRule, Cfvo, ColorScale, Comment, Comments, ConditionalFormatting, DataBar, DataValidation, DataValidations, Features, HeaderFooter, - Hyperlink, IconSet, NoteShape, PageMargins, PageSetup, Pane, Print, PrintOptions, Selection, SheetView, Table, TableColumn, TableStyleInfo, - notes_vml, parse_sqref, range_ref, + Hyperlink, IconSet, NoteShape, PageMargins, PageSetup, Pane, Print, PrintOptions, Selection, SheetFormat, SheetView, Table, TableColumn, + TableStyleInfo, notes_vml, parse_sqref, range_ref, }; pub use package::{Package, is_xlsb}; pub use pivot::{ diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 2fdde59be..20953cbad 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -1,7 +1,8 @@ -//! Binary workbooks ([MS-XLSB]): the workbook part, shared strings and worksheet cells, from -//! their records. Cell formulas are decoded from their tokens ([`formula`]) into the text an -//! `.xlsx` file holds; one that can't be keeps only its saved result, with a warning saying why. -//! Styles are not read. A record that does not parse fails the read. +//! Binary workbooks ([MS-XLSB]): the workbook part, shared strings and worksheets (rows, cells, +//! columns, default sizes, merged cells), from their records. Cell formulas are decoded from +//! their tokens ([`formula`]) into the text an `.xlsx` file holds; one that can't be keeps only +//! its saved result, with a warning saying why. Styles are not read. A record that does not parse +//! fails the read. mod expr; mod formula; @@ -13,7 +14,8 @@ use std::sync::Arc; use craft_opc::{ContentTypes, Rels}; use craft_sheet::{CellError, CellRef, MAX_COLS, MAX_ROWS, Range, Visibility}; -use crate::sheet::{Cell, CellFormula, CellValue, FormulaKind, Row, SheetPart}; +use crate::features::SheetFormat; +use crate::sheet::{Cell, CellFormula, CellValue, Column, FormulaKind, Row, SheetPart}; use crate::strings::StringItem; use crate::workbook::{SheetEntry, SheetKind, Workbook}; use crate::{Error, Limits, Warnings}; @@ -28,6 +30,10 @@ pub(crate) const STRINGS: &str = "application/vnd.ms-excel.sharedStrings"; const MAX_SHEETS: usize = 1024; /// Most merged ranges in one worksheet. const MAX_MERGES: usize = 100_000; +/// Most column records in one worksheet: one per column. +const MAX_COLUMNS: usize = MAX_COLS as usize; +/// The tallest row, in twips (409.6 points). +const MAX_ROW_TWIPS: u16 = 8192; /// Defined names (Excel's hidden ones for newer functions included) read at most; past it, the /// workbook's formulas keep their saved results. const MAX_NAMES: usize = 65_536; @@ -731,7 +737,87 @@ fn value(id: u16, b: &mut Bytes<'_>, strings: usize, limits: &Limits, budget: &B Ok(value) } -/// A worksheet part: rows (BrtRowHdr) and cells inside BrtBeginSheetData, merged cells after. +/// `BrtRowHdr` after `rw`, up to its column spans: the row's height, flags and style, as the +/// `.xlsx` row Excel writes. `miyRw` is the height of every row: it is `ht` when set by hand +/// (`fUnsynced`) or when it differs from the sheet's default, and past 8192 twips it is ignored. +fn row_header(index: u32, b: &mut Bytes<'_>, default_twips: Option) -> Result { + let ixfe = b.u32()?; + let twips = b.u16()?; + let [borders, flags, phonetic] = [b.u8()?, b.u8()?, b.u8()?]; + let custom = flags & 0x20 != 0; + let height = (twips <= MAX_ROW_TWIPS && (custom || default_twips.is_some_and(|d| d != twips))).then(|| f64::from(twips) / 20.0); + let mut attrs = vec![]; + for (bit, byte, name) in [(1, borders, "thickTop"), (2, borders, "thickBot"), (1, phonetic, "ph")] { + if byte & bit != 0 { + attrs.push((name.to_string(), "1".to_string())); + } + } + Ok(Row { + index, + height, + custom_height: custom && height.is_some(), + hidden: flags & 0x10 != 0, + outline_level: flags & 7, + collapsed: flags & 0x08 != 0, + style: (flags & 0x40 != 0).then_some(ixfe), + cells: vec![], + attrs, + }) +} + +/// `BrtWsFmtInfo`: `sheetFormatPr` as Excel writes it, and the default row height in twips. +/// `dxGCol` is the default width in 256ths of a character (`0xFFFFFFFF`: none set); +/// `cchDefColWidth` is the base width, left out at its default of 8. +fn sheet_format(b: &mut Bytes<'_>) -> Result<(SheetFormat, u16), Error> { + let width = b.u32()?; + let base = b.u16()?; + let twips = b.u16()?; + let flags = b.u16()?; + let rows = b.u8()?; + let cols = b.u8()?; + let set = |bit: u16| (flags & bit != 0).then_some(true); + let level = |n: u8| (n > 0).then_some(u32::from(n.min(7))); + let format = SheetFormat { + base_col_width: (base != 8).then_some(u32::from(base)), + default_col_width: (width != u32::MAX).then(|| f64::from(width) / 256.0), + default_row_height: Some(f64::from(twips) / 20.0), + custom_height: set(1), + zero_height: set(2), + thick_top: set(4), + thick_bottom: set(8), + outline_level_row: level(rows), + outline_level_col: level(cols), + attrs: vec![], + }; + Ok((format, twips)) +} + +/// `BrtColInfo`: `None` for a range outside the grid or backwards. `coldx` is the width in 256ths +/// of a character, which is the `.xlsx` width exactly. +fn column(b: &mut Bytes<'_>) -> Result, Error> { + let first = b.u32()?; + let last = b.u32()?; + let width = b.u32()?; + let style = b.u32()?; + let flags = b.u16()?; + if first > last || last >= MAX_COLS { + return Ok(None); + } + Ok(Some(Column { + first, + last, + width: Some(f64::from(width) / 256.0), + custom_width: flags & 2 != 0, + best_fit: flags & 4 != 0, + hidden: flags & 1 != 0, + outline_level: ((flags >> 8) & 7) as u8, + collapsed: flags & 0x1000 != 0, + style: (style != 0).then_some(style), + })) +} + +/// A worksheet part: the sheet's default sizes (BrtWsFmtInfo) and columns (BrtColInfo) before +/// BrtBeginSheetData, rows (BrtRowHdr) and cells inside it, merged cells after. /// Formulas refer to the workbook's `links`; with none, each keeps its saved result. #[allow(clippy::too_many_arguments)] pub(crate) fn worksheet( @@ -750,6 +836,9 @@ pub(crate) fn worksheet( let mut data_seen = false; let mut row: Option = None; let mut col = None; + // The default row height in twips: a row of another height has `ht` even when it was not set + // by hand (a large font, a thick border), as Excel writes it in `.xlsx`. + let mut default_twips: Option = None; // BrtCellMeta applies to the cell record that follows it (a dynamic-array formula), as `cm` // does in `.xlsx`: a one-based index into the metadata part's cell metadata. Excel may write // the cell's BrtValueMeta (a rich value, such as a spill error) in between. @@ -818,15 +907,14 @@ pub(crate) fn worksheet( if r >= MAX_ROWS || row.as_ref().is_some_and(|previous| r <= previous.index) { return Err(invalid("row is out of bounds or unordered")); } - // ixfe, miyRw and the flags are not read. - b.take(9)?; + let next = row_header(r, &mut b, default_twips)?; let spans = b.u32()?; if spans > 16 { return Err(invalid("too many row spans")); } b.take(spans as usize * 8)?; b.finish()?; - if let Some(previous) = row.replace(Row { index: r, ..Row::default() }) { + if let Some(previous) = row.replace(next) { each(previous)?; } sheet.rows += 1; @@ -885,6 +973,30 @@ pub(crate) fn worksheet( }); col = Some(c); } + 485 => { + if data_seen { + return Err(invalid("sheet format after worksheet data")); + } + let (format, twips) = sheet_format(&mut b)?; + b.finish()?; + default_twips = Some(twips); + sheet.features.format = Some(format); + } + 60 => { + if data_seen { + return Err(invalid("column after worksheet data")); + } + let column = column(&mut b)?; + b.finish()?; + let Some(column) = column else { + warnings.warn("invalid XLSB column ranges were skipped"); + continue; + }; + if sheet.columns.len() >= MAX_COLUMNS { + return Err(Error::TooLarge(format!("XLSB exceeds {MAX_COLUMNS} column records"))); + } + sheet.columns.push(column); + } 176 => { if data { return Err(invalid("merge inside worksheet data")); diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index ee9ac3afd..0cf2c5c14 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -5,7 +5,7 @@ mod common; use common::{read, read_with}; use craft_xlsx::testing::zip; -use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Range, SheetKind, Value, Visibility, is_xlsb}; +use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Package, Range, Row, SheetKind, SheetPart, Value, Visibility, is_xlsb}; const ROOT: &str = r#""#; const RELS: &str = r#""#; @@ -930,3 +930,130 @@ fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); assert!(warned(&wb, "missing from the file"), "{:?}", wb.warnings); } + +/// `BrtRowHdr` with its style, height and three flag bytes, and no column spans. +fn row_hdr(r: u32, ixfe: u32, twips: u16, flags: [u8; 3]) -> Vec { + record(0, &[&r.to_le_bytes()[..], &ixfe.to_le_bytes(), &twips.to_le_bytes(), &flags, &0u32.to_le_bytes()].concat()) +} +/// `BrtColInfo`. +fn col_info(first: u32, last: u32, coldx: u32, ixfe: u32, flags: u16) -> Vec { + record(60, &[&first.to_le_bytes()[..], &last.to_le_bytes(), &coldx.to_le_bytes(), &ixfe.to_le_bytes(), &flags.to_le_bytes()].concat()) +} +/// `BrtWsFmtInfo`. +fn ws_fmt_info(dx: u32, base: u16, twips: u16, flags: u16, levels: [u8; 2]) -> Vec { + record(485, &[&dx.to_le_bytes()[..], &base.to_le_bytes(), &twips.to_le_bytes(), &flags.to_le_bytes(), &levels].concat()) +} +/// A worksheet with `head` before its data (the sheet format and columns) and `rows` in it. +fn sized_sheet(head: &[u8], rows: &[u8]) -> Vec { + [&record(129, &[])[..], head, &record(145, &[]), rows, &record(146, &[]), &record(130, &[])].concat() +} +fn sizes_of(bytes: &[u8]) -> Result<(Vec, SheetPart, Vec), Error> { + let mut p = Package::open(bytes, &Limits::default())?; + let wb = p.workbook()?; + let mut rows = vec![]; + let part = p.sheet(&wb.sheets[0], |r| { + rows.push(r); + Ok(()) + })?; + Ok((rows, part, p.warnings().to_vec())) +} +fn xml_sheet(xml: &str) -> (Vec, SheetPart) { + let types = r#""#; + let root = r#""#; + let rels = r#""#; + let book = r#""#; + let bytes = zip(&[ + ("[Content_Types].xml", types.as_bytes()), + ("_rels/.rels", root.as_bytes()), + ("xl/workbook.xml", book.as_bytes()), + ("xl/_rels/workbook.xml.rels", rels.as_bytes()), + ("xl/sheet.xml", xml.as_bytes()), + ]); + let (rows, part, _) = sizes_of(&bytes).unwrap(); + (rows, part) +} + +/// The binary sheet below as Excel spells it in `.xlsx`. Excel writes `ht` for a row whose +/// height differs from the default even when it was not set by hand. +const SIZES_XML: &str = r#"1"#; + +fn sizes_bin() -> Vec { + let head = [ + ws_fmt_info(3225, 10, 285, 0x0A, [2, 1]), + record(390, &[]), + col_info(2, 2, 5273, 0, 0x0002), + col_info(3, 5, 0, 0, 0x0103), + col_info(7, 7, 2321, 7, 0), + col_info(8, 8, 6075, 0, 0x0006), + col_info(9, 9, 2321, 0, 0x1000), + col_info(16_383, 16_383, 7833, 0, 0x0002), + record(391, &[]), + ] + .concat(); + let rows = [ + row_hdr(0, 0, 285, [0, 0, 0]), + cell(2, 0, &((1u32 << 2) | 2).to_le_bytes()), + row_hdr(1, 0, 600, [0, 0x20, 0]), + row_hdr(2, 0, 533, [0, 0, 0]), + row_hdr(3, 0, 285, [0, 0x10, 0]), + row_hdr(4, 0, 300, [3, 0, 0]), + row_hdr(5, 0, 285, [0, 2, 0]), + row_hdr(6, 0, 285, [0, 0x11, 0]), + row_hdr(7, 0, 285, [0, 0x08, 0]), + row_hdr(8, 3, 285, [0, 0x40, 0]), + // A style without fGhostDirty is not applied. + row_hdr(9, 5, 285, [0, 0, 0]), + row_hdr(10, 0, 285, [0, 0, 1]), + // Past 8192 twips the height is ignored, set by hand or not. + row_hdr(11, 0, 9000, [0, 0x20, 0]), + ] + .concat(); + sized_sheet(&head, &rows) +} + +#[test] +fn row_heights_and_column_widths_are_read_as_their_xlsx_spelling() { + let (rows, part, _) = sizes_of(&file(&sizes_bin())).unwrap(); + let (xml_rows, xml_part) = xml_sheet(SIZES_XML); + assert_eq!(rows, xml_rows); + assert_eq!(part.columns, xml_part.columns); + assert_eq!(part.features.format, xml_part.features.format); + // A few of the conversions, spelled out. + assert_eq!((rows[1].height, rows[1].custom_height), (Some(30.0), true)); + assert_eq!((rows[2].height, rows[2].custom_height), (Some(26.65), false)); + assert_eq!(rows[8].style, Some(3)); + assert_eq!(part.columns[0].width, Some(5273.0 / 256.0)); + let format = part.features.format.clone().unwrap(); + assert_eq!((format.default_col_width, format.default_row_height), (Some(12.59765625), Some(14.25))); + // Written as SpreadsheetML, the binary sheet has its default sizes and columns. + let written = String::from_utf8(part.to_xml(&rows)).unwrap(); + assert!(written.contains(r#""#), "{written}"); + assert!(written.contains(r#""#), "{written}"); +} + +#[test] +fn damaged_sizes_are_skipped_or_refused() { + // A column range outside the grid, or backwards, is skipped with a warning. + let head = [record(390, &[]), col_info(0, 16_384, 2321, 0, 0), col_info(5, 4, 2321, 0, 0), col_info(1, 1, 512, 0, 2), record(391, &[])].concat(); + let (_, part, warnings) = sizes_of(&file(&sized_sheet(&head, &row(0)))).unwrap(); + assert_eq!(part.columns.len(), 1); + assert_eq!((part.columns[0].first, part.columns[0].width), (1, Some(2.0))); + assert!(warnings.iter().any(|w| w.contains("column ranges")), "{warnings:?}"); + // Without a sheet format, only a height set by hand is a row's `ht`. + let (rows, _, _) = sizes_of(&file(&sized_sheet(&[], &[row_hdr(0, 0, 300, [0, 0, 0]), row_hdr(1, 0, 400, [0, 0x20, 0])].concat()))).unwrap(); + assert_eq!((rows[0].height, rows[1].height), (None, Some(20.0))); + // More column records than columns are refused. + let many = [&record(390, &[])[..], &col_info(0, 0, 2321, 0, 0).repeat(16_385), &record(391, &[])].concat(); + assert!(matches!(sizes_of(&file(&sized_sheet(&many, &[]))), Err(Error::TooLarge(_)))); + // A sheet format or column after the data, or a record of the wrong size, fails the read. + for (why, sheet) in [ + ("format after data", worksheet(&[], &ws_fmt_info(u32::MAX, 8, 285, 0, [0, 0]))), + ("column after data", worksheet(&[], &col_info(0, 0, 2321, 0, 0))), + ("short column", sized_sheet(&record(60, &[0; 16]), &[])), + ("short format", sized_sheet(&record(485, &[0; 11]), &[])), + ("long row header", sized_sheet(&[], &record(0, &[0; 18]))), + ] { + assert!(matches!(sizes_of(&file(&sheet)), Err(Error::Invalid(_))), "{why}"); + } +} From eca1698ef11bc0a523dea6da95cdc613b11a405b Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:38:58 -0500 Subject: [PATCH 002/200] craft-xlsx: review fix: skipped column records count toward the column cap A sheet of 16,385 reversed or out-of-grid BrtColInfo ranges was skipped one by one without reaching the cap, since only kept columns were counted. Every column record now counts. --- crates/xlsx/src/xlsb.rs | 9 ++++++--- crates/xlsx/tests/xlsb.rs | 3 +++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index fdda0d5cb..73755c3dc 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -840,6 +840,8 @@ pub(crate) fn worksheet( let mut sheet = SheetPart::default(); let mut data = false; let mut data_seen = false; + // Every BrtColInfo counts toward the cap, a skipped one too. + let mut column_records = 0usize; let mut row: Option = None; let mut col = None; // The default row height in twips: a row of another height has `ht` even when it was not set @@ -992,15 +994,16 @@ pub(crate) fn worksheet( if data_seen { return Err(invalid("column after worksheet data")); } + if column_records >= MAX_COLUMNS { + return Err(Error::TooLarge(format!("XLSB exceeds {MAX_COLUMNS} column records"))); + } + column_records += 1; let column = column(&mut b)?; b.finish()?; let Some(column) = column else { warnings.warn("invalid XLSB column ranges were skipped"); continue; }; - if sheet.columns.len() >= MAX_COLUMNS { - return Err(Error::TooLarge(format!("XLSB exceeds {MAX_COLUMNS} column records"))); - } sheet.columns.push(column); } 176 => { diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index d1e7feafc..4f6886b26 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1046,6 +1046,9 @@ fn damaged_sizes_are_skipped_or_refused() { // More column records than columns are refused. let many = [&record(390, &[])[..], &col_info(0, 0, 2321, 0, 0).repeat(16_385), &record(391, &[])].concat(); assert!(matches!(sizes_of(&file(&sized_sheet(&many, &[]))), Err(Error::TooLarge(_)))); + // Skipped (reversed) column records count toward that cap too. + let reversed = [&record(390, &[])[..], &col_info(5, 4, 2321, 0, 0).repeat(16_385), &record(391, &[])].concat(); + assert!(matches!(sizes_of(&file(&sized_sheet(&reversed, &[]))), Err(Error::TooLarge(_)))); // A sheet format or column after the data, or a record of the wrong size, fails the read. for (why, sheet) in [ ("format after data", worksheet(&[], &ws_fmt_info(u32::MAX, 8, 285, 0, [0, 0]))), From 76ddfc37493022c9127095f8fa20a23429ba59a6 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 21:57:59 +0100 Subject: [PATCH 003/200] 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 004/200] 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 005/200] 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 006/200] 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 007/200] 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 5628ad359d8f5bf9778f53edba9b9989b4b61d09 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 11:49:53 +0100 Subject: [PATCH 008/200] 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 a2541707240580153c8ea9ef3043ec0257468d0a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:40 +0000 Subject: [PATCH 009/200] 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 8a1bad8c2cc47f71c2a75fb19b67b54762fe8389 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:56 +0000 Subject: [PATCH 010/200] 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 011/200] 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 e9eaaf5641640b4e2735b0af79ef589c5a74a88a Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 16:52:35 +0100 Subject: [PATCH 012/200] 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 013/200] 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 014/200] 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 015/200] 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 016/200] 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 017/200] 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 018/200] 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 9c3c82e1c63e53248f99531a71cb8401f5c76150 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:04 +0000 Subject: [PATCH 019/200] 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 da7007385609e66337f9ba37c5aca8ca6215b2f2 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:23:46 +0000 Subject: [PATCH 020/200] Expose tolerant JPEG marker inspection --- crates/metadata/src/container.rs | 146 +++++++++++++++++++++++++++++-- 1 file changed, 137 insertions(+), 9 deletions(-) diff --git a/crates/metadata/src/container.rs b/crates/metadata/src/container.rs index 842020683..c972867e1 100644 --- a/crates/metadata/src/container.rs +++ b/crates/metadata/src/container.rs @@ -84,22 +84,83 @@ pub fn embedded(bytes: &[u8]) -> Embedded { const XMP_SIG: &[u8] = b"http://ns.adobe.com/xap/1.0/\0"; const XMP_EXT_SIG: &[u8] = b"http://ns.adobe.com/xmp/extension/\0"; +/// JPEG frame, marker and metadata details collected before the first scan. +#[derive(Debug, Default)] +pub struct JpegInspection { + /// Stored frame width. + pub width: u32, + /// Stored frame height. + pub height: u32, + /// Number of frame components. + pub components: u8, + /// Sample precision. + pub precision: u8, + /// Start-of-frame marker byte. + pub sof: u8, + /// Components in the first scan. + pub first_scan_components: u8, + /// Number of APP1 segments. + pub app1: u32, + /// First EXIF TIFF payload. + pub exif: Option>, + /// Offset of the EXIF TIFF payload. + pub exif_offset: usize, + /// First standard XMP packet. + pub xmp: Option, + /// Reassembled ICC profile. + pub icc: Option>, + /// ICC chunks were malformed or inconsistent. + pub icc_invalid: bool, + /// Adobe APP14 transform byte. + pub adobe_transform: Option, + /// MPF TIFF offset and payload. + pub mpf: Option<(usize, Vec)>, + /// ISO gain-map APP2 payload following its identifier. + pub iso_gainmap: Option>, + valid: bool, +} + +impl JpegInspection { + /// Whether metadata identifies this image as a gain map. + pub fn is_gain_map(&self) -> bool { + self.iso_gainmap.as_ref().is_some_and(|p| p.len() > 4) || self.xmp.as_deref().is_some_and(|x| x.contains("hdrgm:GainMapMax")) + } +} + +/// Inspect markers before the first scan, tolerating garbage between segments and truncated +/// final payloads. Returns `None` for a missing SOI or an invalid segment length. +pub fn inspect_jpeg(b: &[u8]) -> Option { + if !b.starts_with(&[0xff, 0xd8]) { + return None; + } + let (embedded, _, mut inspection) = jpeg_segments_inner(b, false, true); + if !inspection.valid { + return None; + } + inspection.exif = embedded.exif; + inspection.xmp = embedded.xmp.map(|x| x.trim_end_matches('\0').to_string()); + inspection.icc = embedded.icc; + Some(inspection) +} + /// Walk JPEG markers up to SOS and collect APP1 Exif / XMP, APP2 ICC and APP13 IPTC. pub fn jpeg_segments(b: &[u8]) -> Embedded { - jpeg_segments_inner(b, false).0 + jpeg_segments_inner(b, false, false).0 } /// Walk JPEG metadata and return every ordinary XMP APP1 packet in segment order, along with the /// usual [`Embedded`] projection (which retains only the first ordinary packet). pub fn jpeg_segments_with_all_xmp(b: &[u8]) -> (Embedded, Vec) { - jpeg_segments_inner(b, true) + let (embedded, packets, _) = jpeg_segments_inner(b, true, false); + (embedded, packets) } -fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool) -> (Embedded, Vec) { +fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool, inspect: bool) -> (Embedded, Vec, JpegInspection) { let mut out = Embedded::default(); let mut xmp_packets = Vec::new(); + let mut inspection = JpegInspection { valid: true, ..Default::default() }; if !b.starts_with(&[0xff, 0xd8]) { - return (out, xmp_packets); + return (out, xmp_packets, inspection); } let mut icc_parts: [Option<&[u8]>; 255] = [None; 255]; let mut icc_total = None; @@ -110,6 +171,10 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool) -> (Embedded, Vec (Embedded, Vec (Embedded, Vec= 6 && inspection.components == 0 { + inspection.precision = payload[0]; + inspection.sof = marker; + inspection.height = u32::from(u16::from_be_bytes([payload[1], payload[2]])); + inspection.width = u32::from(u16::from_be_bytes([payload[3], payload[4]])); + inspection.components = payload[5]; + } + if marker == 0xe1 { + inspection.app1 = inspection.app1.saturating_add(1); + } + if marker == 0xe1 && payload.starts_with(b"Exif\0\0") && out.exif.is_none() { + inspection.exif_offset = start + 6; + } + if marker == 0xe2 && payload.starts_with(b"MPF\0") && inspection.mpf.is_none() { + inspection.mpf = Some((start + 4, payload[4..].to_vec())); + } + if marker == 0xe2 && inspection.iso_gainmap.is_none() { + if let Some(data) = payload.strip_prefix(b"urn:iso:std:iso:ts:21496:-1\0") { + inspection.iso_gainmap = Some(data.to_vec()); + } + } + if marker == 0xee && payload.starts_with(b"Adobe") && payload.len() >= 12 { + inspection.adobe_transform = Some(payload[11]); + } + } match marker { - 0xe1 if payload.starts_with(b"Exif\0") && out.exif.is_none() => out.exif = Some(payload.get(6..).unwrap_or(&[]).to_vec()), + 0xe1 if payload.starts_with(if inspect { b"Exif\0\0" } else { b"Exif\0" }) && out.exif.is_none() => { + out.exif = Some(payload.get(6..).unwrap_or(&[]).to_vec()) + } 0xe1 if payload.starts_with(XMP_SIG) && out.xmp.is_none() => { let packet = String::from_utf8_lossy(&payload[XMP_SIG.len()..]).into_owned(); if collect_all_xmp { @@ -145,7 +242,7 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool) -> (Embedded, Vec { xmp_packets.push(String::from_utf8_lossy(&payload[XMP_SIG.len()..]).into_owned()); } - 0xe1 if payload.starts_with(XMP_EXT_SIG) => { + 0xe1 if !inspect && payload.starts_with(XMP_EXT_SIG) => { // GUID (32) + full length (4) + offset (4) + data let p = &payload[XMP_EXT_SIG.len()..]; if p.len() >= 40 { @@ -184,7 +281,7 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool) -> (Embedded, Vec out.iptc = photoshop_iptc(&payload[14..]), + 0xed if !inspect && payload.starts_with(b"Photoshop 3.0\0") && out.iptc.is_none() => out.iptc = photoshop_iptc(&payload[14..]), _ => {} } i = end; @@ -214,8 +311,11 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool) -> (Embedded, Vec, marker: u8, data: &[u8]) { + out.extend_from_slice(&[0xff, marker]); + out.extend_from_slice(&((data.len() as u16) + 2).to_be_bytes()); + out.extend_from_slice(data); + } + #[test] + fn tolerant_walk_keeps_offsets_frame_and_icc_chunks() { + let mut b = vec![0xff, 0xd8, 0x44]; + segment(&mut b, 0xe1, b"Exif\0\0II"); + segment(&mut b, 0xe2, b"ICC_PROFILE\0\x02\x02B"); + segment(&mut b, 0xe2, b"ICC_PROFILE\0\x01\x02A"); + segment(&mut b, 0xc0, &[8, 0, 2, 0, 3, 3]); + b.extend_from_slice(&[0xff, 0xda, 0, 3, 3]); + let info = inspect_jpeg(&b).unwrap(); + assert_eq!((info.width, info.height, info.components, info.first_scan_components), (3, 2, 3, 3)); + assert_eq!(info.app1, 1); + assert_eq!(&b[info.exif_offset..info.exif_offset + 2], b"II"); + assert_eq!(info.icc.as_deref(), Some(&b"AB"[..])); + assert!(!info.icc_invalid); + // The existing strict API still stops at the garbage byte. + assert!(jpeg_segments(&b).exif.is_none()); + assert!(inspect_jpeg(&[0xff, 0xd8, 0xff, 0xe1, 0, 1]).is_none()); + } +} From e275d533cfacf21817200694e48aa7054a2f5a2c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:24:17 +0000 Subject: [PATCH 021/200] Export JPEG inspection API --- crates/metadata/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/metadata/src/lib.rs b/crates/metadata/src/lib.rs index ff2c530fa..bf6700455 100644 --- a/crates/metadata/src/lib.rs +++ b/crates/metadata/src/lib.rs @@ -37,7 +37,7 @@ pub mod tags; mod xmp; mod xmp_merge; -pub use container::{Embedded, embedded, jpeg_segments, jpeg_segments_with_all_xmp, png_chunks, webp_chunks}; +pub use container::{Embedded, JpegInspection, embedded, inspect_jpeg, jpeg_segments, jpeg_segments_with_all_xmp, png_chunks, webp_chunks}; pub use datetime::{DatePrecision, DateTime}; pub use exif::{from_tiff, read_exif, strip_exif_header, try_read_exif, try_read_exif_with, write_exif}; pub use focus::FocusPoint; From e58b7c5a362a05411e98f1f94e1c995f2a888910 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:25:34 +0000 Subject: [PATCH 022/200] Factor JPEG inspection fields from shared walker --- crates/metadata/src/container.rs | 53 +++++++++++++++++--------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/crates/metadata/src/container.rs b/crates/metadata/src/container.rs index c972867e1..4f90cffc2 100644 --- a/crates/metadata/src/container.rs +++ b/crates/metadata/src/container.rs @@ -203,30 +203,7 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool, inspect: bool) -> (Embed let end = declared_end.min(b.len()); let Some(payload) = b.get(start..end) else { break }; if inspect { - if (0xc0..=0xcf).contains(&marker) && !matches!(marker, 0xc4 | 0xc8 | 0xcc) && payload.len() >= 6 && inspection.components == 0 { - inspection.precision = payload[0]; - inspection.sof = marker; - inspection.height = u32::from(u16::from_be_bytes([payload[1], payload[2]])); - inspection.width = u32::from(u16::from_be_bytes([payload[3], payload[4]])); - inspection.components = payload[5]; - } - if marker == 0xe1 { - inspection.app1 = inspection.app1.saturating_add(1); - } - if marker == 0xe1 && payload.starts_with(b"Exif\0\0") && out.exif.is_none() { - inspection.exif_offset = start + 6; - } - if marker == 0xe2 && payload.starts_with(b"MPF\0") && inspection.mpf.is_none() { - inspection.mpf = Some((start + 4, payload[4..].to_vec())); - } - if marker == 0xe2 && inspection.iso_gainmap.is_none() { - if let Some(data) = payload.strip_prefix(b"urn:iso:std:iso:ts:21496:-1\0") { - inspection.iso_gainmap = Some(data.to_vec()); - } - } - if marker == 0xee && payload.starts_with(b"Adobe") && payload.len() >= 12 { - inspection.adobe_transform = Some(payload[11]); - } + inspect_marker(&mut inspection, marker, payload, start, out.exif.is_none()); } match marker { 0xe1 if payload.starts_with(if inspect { b"Exif\0\0" } else { b"Exif\0" }) && out.exif.is_none() => { @@ -318,6 +295,34 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool, inspect: bool) -> (Embed (out, xmp_packets, inspection) } +fn inspect_marker(info: &mut JpegInspection, marker: u8, payload: &[u8], start: usize, needs_exif: bool) { + if (0xc0..=0xcf).contains(&marker) && !matches!(marker, 0xc4 | 0xc8 | 0xcc) && payload.len() >= 6 && info.components == 0 { + info.precision = payload[0]; + info.sof = marker; + info.height = u32::from(u16::from_be_bytes([payload[1], payload[2]])); + info.width = u32::from(u16::from_be_bytes([payload[3], payload[4]])); + info.components = payload[5]; + } + if marker == 0xe1 { + info.app1 = info.app1.saturating_add(1); + } + if marker == 0xe1 && payload.starts_with(b"Exif\0\0") && needs_exif { + info.exif_offset = start + 6; + } + if marker == 0xe2 && payload.starts_with(b"MPF\0") && info.mpf.is_none() { + info.mpf = Some((start + 4, payload[4..].to_vec())); + } + if marker == 0xe2 + && info.iso_gainmap.is_none() + && let Some(data) = payload.strip_prefix(b"urn:iso:std:iso:ts:21496:-1\0") + { + info.iso_gainmap = Some(data.to_vec()); + } + if marker == 0xee && payload.starts_with(b"Adobe") && payload.len() >= 12 { + info.adobe_transform = Some(payload[11]); + } +} + /// Put the Extended XMP of JPEG `b` into `out`: when the standard packet links one, only that GUID's /// chunks count, checked strictly ([`extended_xmp`]); otherwise every chunk, offset-sorted. fn attach_extension(out: &mut Embedded, b: &[u8], mut ext: Vec<(u32, Vec)>, ext_headers: &[(&[u8], u32)]) { From 091baf624fcaa67ad740c2ea9d6df3216b4bddc7 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:26:21 +0000 Subject: [PATCH 023/200] Share ICC chunk collection between JPEG inspection modes --- crates/metadata/src/container.rs | 50 +++++++++++++++----------------- 1 file changed, 23 insertions(+), 27 deletions(-) diff --git a/crates/metadata/src/container.rs b/crates/metadata/src/container.rs index 4f90cffc2..d8eb261db 100644 --- a/crates/metadata/src/container.rs +++ b/crates/metadata/src/container.rs @@ -230,33 +230,7 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool, inspect: bool) -> (Embed } } 0xe2 if payload.starts_with(b"ICC_PROFILE\0") => { - if !complete || payload.len() < 14 { - icc_invalid = true; - } else if let Some(header) = payload.get(12..14) { - let (Some(&sequence), Some(&total)) = (header.first(), header.get(1)) else { - icc_invalid = true; - i = end; - continue; - }; - if sequence == 0 || total == 0 || sequence > total || icc_total.is_some_and(|expected| expected != total) { - icc_invalid = true; - } else { - icc_total = Some(total); - if let Some(slot) = icc_parts.get_mut(usize::from(sequence - 1)) { - if slot.is_some() { - icc_invalid = true; - } else if let Some(data) = payload.get(14..) { - *slot = Some(data); - } else { - icc_invalid = true; - } - } else { - icc_invalid = true; - } - } - } else { - icc_invalid = true; - } + collect_icc_part(payload, complete, &mut icc_parts, &mut icc_total, &mut icc_invalid); } 0xed if !inspect && payload.starts_with(b"Photoshop 3.0\0") && out.iptc.is_none() => out.iptc = photoshop_iptc(&payload[14..]), _ => {} @@ -295,6 +269,28 @@ fn jpeg_segments_inner(b: &[u8], collect_all_xmp: bool, inspect: bool) -> (Embed (out, xmp_packets, inspection) } +fn collect_icc_part<'a>(payload: &'a [u8], complete: bool, parts: &mut [Option<&'a [u8]>; 255], total: &mut Option, invalid: &mut bool) { + if !complete || payload.len() < 14 { + *invalid = true; + return; + } + let (sequence, count) = (payload[12], payload[13]); + if sequence == 0 || count == 0 || sequence > count || total.is_some_and(|expected| expected != count) { + *invalid = true; + return; + } + *total = Some(count); + let Some(slot) = parts.get_mut(usize::from(sequence - 1)) else { + *invalid = true; + return; + }; + if slot.is_some() { + *invalid = true; + } else { + *slot = payload.get(14..); + } +} + fn inspect_marker(info: &mut JpegInspection, marker: u8, payload: &[u8], start: usize, needs_exif: bool) { if (0xc0..=0xcf).contains(&marker) && !matches!(marker, 0xc4 | 0xc8 | 0xcc) && payload.len() >= 6 && info.components == 0 { info.precision = payload[0]; From c97bc006df861d97d5da6f0db387693ab5592a65 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:28:10 +0000 Subject: [PATCH 024/200] Cover JPEG MPF and gain-map inspection --- crates/metadata/src/container.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/crates/metadata/src/container.rs b/crates/metadata/src/container.rs index d8eb261db..65a47ba05 100644 --- a/crates/metadata/src/container.rs +++ b/crates/metadata/src/container.rs @@ -975,6 +975,20 @@ mod jpeg_inspection_tests { out.extend_from_slice(&((data.len() as u16) + 2).to_be_bytes()); out.extend_from_slice(data); } + #[test] + fn reports_mpf_gainmap_and_adobe_transform() { + let mut b = vec![0xff, 0xd8]; + segment(&mut b, 0xe2, b"MPF\0IIabc"); + segment(&mut b, 0xe2, b"urn:iso:std:iso:ts:21496:-1\0abcde"); + segment(&mut b, 0xee, b"Adobe\0\0\0\0\0\0\x02"); + b.extend_from_slice(&[0xff, 0xd9]); + let info = inspect_jpeg(&b).unwrap(); + let (offset, data) = info.mpf.unwrap(); + assert_eq!(&b[offset..offset + data.len()], data); + assert_eq!(info.iso_gainmap.as_deref(), Some(&b"abcde"[..])); + assert_eq!(info.adobe_transform, Some(2)); + } + #[test] fn tolerant_walk_keeps_offsets_frame_and_icc_chunks() { let mut b = vec![0xff, 0xd8, 0x44]; From 476599c792851f9f1e00159d6f365d9b6a44d39e Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:29:27 +0000 Subject: [PATCH 025/200] Expose MPF index inspection for located payloads --- crates/metadata/src/mpf.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/metadata/src/mpf.rs b/crates/metadata/src/mpf.rs index 602c8f90d..5c7f5a7cd 100644 --- a/crates/metadata/src/mpf.rs +++ b/crates/metadata/src/mpf.rs @@ -113,7 +113,14 @@ pub fn images(jpeg: &[u8]) -> Vec { }; // offsets count from the byte-order field, which follows the signature let Some(base) = segs.iter().find(|s| jpeg.get(s.1..s.2) == Some(payload)).map(|s| s.1 + SIGNATURE.len()) else { return Vec::new() }; - let Some(tiff) = payload.get(SIGNATURE.len()..).and_then(|t| Tiff::parse(t).ok()) else { return Vec::new() }; + let Some(index) = payload.get(SIGNATURE.len()..) else { return Vec::new() }; + images_from_index(index, base) +} + +/// Read an already located MPF TIFF index. `base` is the index's offset in the containing file. +/// Entries are bounded to [`MAX_ENTRIES`] and returned without reading image payloads. +pub fn images_from_index(index: &[u8], base: usize) -> Vec { + let Some(tiff) = Tiff::parse(index).ok() else { return Vec::new() }; let Some(list) = tiff.ifds.first().and_then(|i| i.bytes(MP_ENTRY)) else { return Vec::new() }; let u32_at = |rec: &[u8], at: usize| rec.get(at..at + 4).and_then(|s| <[u8; 4]>::try_from(s).ok()).map(|s| tiff.order.u32(s) as usize); let mut out = Vec::new(); From 591061efb488727cb4a38cbb10cb861dec0bc832 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:29:43 +0000 Subject: [PATCH 026/200] Cover located MPF index parity --- crates/metadata/src/mpf.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/metadata/src/mpf.rs b/crates/metadata/src/mpf.rs index 5c7f5a7cd..edeb29348 100644 --- a/crates/metadata/src/mpf.rs +++ b/crates/metadata/src/mpf.rs @@ -233,6 +233,7 @@ mod tests { let segs = segments(&file).unwrap(); assert_eq!(segs.iter().map(|s| s.0).collect::>(), [0xe0, 0xe1, 0xe2, 0xdb]); let (_, a, e) = segs[2]; + assert_eq!(images_from_index(&file[a + SIGNATURE.len()..e], a + SIGNATURE.len()), found); let mut without = file[..a - 4].to_vec(); without.extend_from_slice(&file[e..found[0].offset]); assert_eq!(without, primary); From 149e74d739443d22fabb877745dad665f51c5eff Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:32:40 +0000 Subject: [PATCH 027/200] Preserve bounded MPF index directory validation --- crates/metadata/src/mpf.rs | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/crates/metadata/src/mpf.rs b/crates/metadata/src/mpf.rs index edeb29348..9da7dc8c6 100644 --- a/crates/metadata/src/mpf.rs +++ b/crates/metadata/src/mpf.rs @@ -114,12 +114,38 @@ pub fn images(jpeg: &[u8]) -> Vec { // offsets count from the byte-order field, which follows the signature let Some(base) = segs.iter().find(|s| jpeg.get(s.1..s.2) == Some(payload)).map(|s| s.1 + SIGNATURE.len()) else { return Vec::new() }; let Some(index) = payload.get(SIGNATURE.len()..) else { return Vec::new() }; - images_from_index(index, base) + parse_index(index, base) } /// Read an already located MPF TIFF index. `base` is the index's offset in the containing file. /// Entries are bounded to [`MAX_ENTRIES`] and returned without reading image payloads. pub fn images_from_index(index: &[u8], base: usize) -> Vec { + // The bounded legacy reader requires a complete classic first IFD, while the generic TIFF + // parser can salvage partial directories. Preserve that refusal for located MPF indices. + let le = match index.get(..2) { + Some(b"II") => true, + Some(b"MM") => false, + _ => return Vec::new(), + }; + let read16 = + |at: usize| index.get(at..at.checked_add(2)?).map(|b| if le { u16::from_le_bytes([b[0], b[1]]) } else { u16::from_be_bytes([b[0], b[1]]) }); + let read32 = |at: usize| { + index + .get(at..at.checked_add(4)?) + .map(|b| if le { u32::from_le_bytes([b[0], b[1], b[2], b[3]]) } else { u32::from_be_bytes([b[0], b[1], b[2], b[3]]) }) + }; + if read16(2) != Some(42) { + return Vec::new(); + } + let Some(at) = read32(4).and_then(|v| usize::try_from(v).ok()) else { return Vec::new() }; + let Some(count) = read16(at).map(usize::from).filter(|n| *n <= 4096) else { return Vec::new() }; + if at.checked_add(2).and_then(|p| count.checked_mul(12).and_then(|n| p.checked_add(n))).is_none_or(|end| end > index.len()) { + return Vec::new(); + } + parse_index(index, base) +} + +fn parse_index(index: &[u8], base: usize) -> Vec { let Some(tiff) = Tiff::parse(index).ok() else { return Vec::new() }; let Some(list) = tiff.ifds.first().and_then(|i| i.bytes(MP_ENTRY)) else { return Vec::new() }; let u32_at = |rec: &[u8], at: usize| rec.get(at..at + 4).and_then(|s| <[u8; 4]>::try_from(s).ok()).map(|s| tiff.order.u32(s) as usize); From 0a909223512f4ecd2fb705e013bd1614085f13ad Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:33:19 -0500 Subject: [PATCH 028/200] fix: rewrite container.rs for craft-zip public API - Archive::open() instead of ZipArchive constructor - Writer::add(name, data, compression) instead of start_file+write_all - Archive::entry_name() for name iteration (no file_names iterator) - Archive::contains(), declared_size(), read(name, max) for entry access - Reader no longer generic over Read+Seek; reads all bytes into memory (needed because Archive<'a> borrows 'static bytes) - Thumbnail::read no longer generic --- crates/format/src/container.rs | 157 ++++++++++----------------- crates/format/src/container_tests.rs | 1 + 2 files changed, 60 insertions(+), 98 deletions(-) diff --git a/crates/format/src/container.rs b/crates/format/src/container.rs index a987bb1fb..1b07c2de1 100644 --- a/crates/format/src/container.rs +++ b/crates/format/src/container.rs @@ -6,7 +6,7 @@ //! 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::io::{Read, Seek, SeekFrom}; use std::sync::Arc; use serde_json::Value; @@ -84,7 +84,7 @@ pub struct PartDigest { /// A container being written. pub struct Writer { - zip: zip::ZipWriter>>, + zip: craft_zip::Writer, names: BTreeSet, expanded: usize, resolved: usize, @@ -95,7 +95,7 @@ pub struct Writer { 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 } + Writer { zip: craft_zip::Writer::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 @@ -111,7 +111,7 @@ impl Writer { /// The container's bytes. pub fn finish(self) -> Result, FormatError> { - Ok(self.zip.finish().map_err(invalid)?.into_inner()) + Ok(self.zip.finish().map_err(invalid)?) } /// Add a part, compressed or stored. A name already written is written once. @@ -138,22 +138,8 @@ impl Writer { 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)?; - } + let compression = if compressed { craft_zip::Compression::Deflated } else { craft_zip::Compression::Stored }; + self.zip.add(name, bytes, compression).map_err(invalid)?; Ok(()) } @@ -168,10 +154,8 @@ impl Writer { 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)) + budget.saturating_sub(self.names.len().saturating_add(entries).saturating_mul(256).saturating_add(65_536)) + .min((self.limits.max_expanded)().saturating_sub(self.expanded)) } /// Add a payload as a blob, `blobs/.`, and say its name, for the JSON that @@ -189,10 +173,13 @@ impl Writer { } } -/// 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, +/// A container being read. Opening reads all bytes into memory (needed because the archive +/// borrows them), checks the directory (the entry count, unique and plain names, every part's +/// declared size), not the parts. +pub struct Reader { + /// The raw archive bytes, kept alive so the archive can borrow them. + bytes: Vec, + archive: craft_zip::Archive<'static>, blobs: BTreeMap>, /// The bytes of payloads resolved so far, repeats counted: bounded by the expanded budget. pub hydrated: usize, @@ -200,64 +187,42 @@ pub struct Reader { limits: Limits, } -impl Reader { - pub fn new(mut source: R, limits: Limits) -> Result { +impl Reader { + pub fn new(mut source: impl Read + Seek, 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")); + + // Read all bytes into memory for the archive. + source.seek(SeekFrom::Start(0)).map_err(invalid)?; + let mut bytes = Vec::with_capacity(length as usize); + source.read_to_end(&mut bytes).map_err(invalid)?; + + // Leak the Vec to get 'static bytes (needed because Archive<'a> borrows them). + // This is acceptable: Reader holds the bytes for its lifetime anyway, and + // ZIP archives are typically small-to-moderate size. + let leaked: &'static [u8] = Box::leak(bytes.into_boxed_slice()); + + let mut archive = craft_zip::Archive::open(leaked, craft_zip::Limits { + max_entries: limits.max_entries as u64, + max_total_bytes: (limits.max_expanded)() as u64, + }).map_err(invalid)?; + + // Validate entry names match format rules: no empty, no backslashes, + // no path components that are "." or "..", and no duplicates. + let mut name_set = BTreeSet::new(); + for entry_idx in 0..archive.len() { + if let Ok(Some(name)) = archive.entry_name(entry_idx) { + if name.is_empty() + || name.contains('\\') + || name.split('/').any(|c| c.is_empty() || c == "." || c == "..") + || !name_set.insert(name) + { + return Err(invalid("duplicate or invalid archive entry")); + } } } - Ok(Self { zip, blobs: BTreeMap::new(), hydrated: 0, document: None, limits }) + + Ok(Self { bytes: leaked.to_vec(), archive, blobs: BTreeMap::new(), hydrated: 0, document: None, limits }) } /// The file's own part, `document.json`, read once and kept: provisional caches and the @@ -265,35 +230,32 @@ impl Reader { /// 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()); + let bytes = self.limited_part("document.json", limit)?; + self.document = Some(bytes.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() + self.archive.contains(name) } /// 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() + self.archive.names().map(|n| n.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(); + let expected = self.archive.declared_size(name).ok_or_else(|| invalid("part not found"))?; 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")); + // Read within budget. craft-zip's read() handles decompression bombs via the limit. + let bytes = self.archive.read(name, limit as u64).map_err(invalid)?.ok_or_else(|| invalid("part not found"))?; + if bytes.len() as u64 != expected { + return Err(invalid("part length mismatch")); } Ok(bytes) } @@ -367,9 +329,8 @@ impl Thumbnail { 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)?; + 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(()); } @@ -379,7 +340,7 @@ impl Thumbnail { /// 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> { + 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) diff --git a/crates/format/src/container_tests.rs b/crates/format/src/container_tests.rs index bda37d000..50bd86715 100644 --- a/crates/format/src/container_tests.rs +++ b/crates/format/src/container_tests.rs @@ -1,4 +1,5 @@ use super::*; +use std::io::Cursor; const LIMITS: Limits = Limits { max_entries: 8, From 9fad598f4bd35a173e1ff3d3fdac9c41d3c0004e Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:38:18 +0000 Subject: [PATCH 029/200] Share Samsung SEF repair and JPEG EOI inspection --- crates/image-codecs/src/codecs/jpeg.rs | 29 ++++++++- crates/image-codecs/src/jpeg_sef.rs | 82 ++++++++++++++++++++++++++ crates/image-codecs/src/lib.rs | 1 + 3 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 crates/image-codecs/src/jpeg_sef.rs diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index bcd86ad5a..158491134 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -195,6 +195,27 @@ enum DataEnd { /// measured on these, not on the file length, which APP padding can inflate without /// adding image data. fn data_end(b: &[u8]) -> (DataEnd, u64) { + data_end_mode(b, false) +} + +/// Whether the marker walk actually reaches the first EOI, with malformed segment lengths refused. +pub(crate) fn reaches_eoi(b: &[u8]) -> bool { + data_end_mode(b, true).0 == DataEnd::Complete +} + +fn find_ff(b: &[u8]) -> Option { + const ONES: u64 = 0x0101_0101_0101_0101; + let (words, tail) = b.as_chunks::<8>(); + for (i, word) in words.iter().enumerate() { + let x = !u64::from_ne_bytes(*word); + if x.wrapping_sub(ONES) & !x & (ONES << 7) != 0 { + return word.iter().position(|&v| v == 0xff).map(|j| i * 8 + j); + } + } + tail.iter().position(|&v| v == 0xff).map(|j| words.len() * 8 + j) +} + +fn data_end_mode(b: &[u8], strict: bool) -> (DataEnd, u64) { // Where the bytes run out: inside the image data once a scan has held some. let cut = |scan_data: bool, scanned: u64| (if scan_data { DataEnd::Truncated } else { DataEnd::Empty }, scanned); let mut i = 2; // past SOI @@ -207,7 +228,7 @@ fn data_end(b: &[u8]) -> (DataEnd, u64) { // segments after the stray bytes (padding among them) are still recognised. Stray // bytes are not scan data, so they never count (junk would buy budget as padding // did); with no marker left, the image data ends here. - let Some(p) = b.get(i..).and_then(|r| r.iter().position(|&v| v == 0xFF)) else { return cut(scan_data, scanned) }; + let Some(p) = b.get(i..).and_then(find_ff) else { return cut(scan_data, scanned) }; i += p; continue; } @@ -216,15 +237,19 @@ fn data_end(b: &[u8]) -> (DataEnd, u64) { 0xD9 => return (DataEnd::Complete, scanned), 0xFF => i += 1, 0x01 | 0xD0..=0xD8 => i += 2, + 0x00 if strict => i += 2, _ => { let Some(len) = b.get(i + 2..i + 4).and_then(|s| <[u8; 2]>::try_from(s).ok()).map(u16::from_be_bytes) else { return cut(scan_data, scanned); }; + if strict && len < 2 { + return cut(scan_data, scanned); + } i = i.saturating_add(2 + usize::from(len)); if code == 0xDA { let start = i; loop { - let Some(p) = b.get(i..).and_then(|r| r.iter().position(|&v| v == 0xFF)) else { + let Some(p) = b.get(i..).and_then(find_ff) else { // EOF inside this scan: everything from the scan start to the end // of the file is scan data (inside a declared segment it may not // be, so only count what remains). diff --git a/crates/image-codecs/src/jpeg_sef.rs b/crates/image-codecs/src/jpeg_sef.rs new file mode 100644 index 000000000..6ae878013 --- /dev/null +++ b/crates/image-codecs/src/jpeg_sef.rs @@ -0,0 +1,82 @@ +//! Validated Samsung SEF trailer repair for JPEGs missing their final EOI marker. +use std::borrow::Cow; + +/// Whether the first JPEG image reaches an EOI through its marker and scan structure. +pub fn reaches_eoi(bytes: &[u8]) -> bool { + crate::codecs::jpeg::reaches_eoi(bytes) +} + +/// Borrow ordinary input unchanged. For a validated Samsung SEF trailer following an open JPEG +/// scan, remove that trailer and append the missing EOI. The owned copy is made only on repair. +pub fn repair(bytes: &[u8]) -> Cow<'_, [u8]> { + let Some(image) = image_end(bytes).and_then(|end| bytes.get(..end)) else { return Cow::Borrowed(bytes) }; + if reaches_eoi(image) { + return Cow::Borrowed(bytes); + } + let mut fixed = Vec::with_capacity(image.len().saturating_add(2)); + fixed.extend_from_slice(image); + fixed.extend_from_slice(&[0xff, 0xd9]); + let in_scan = craft_metadata::inspect_jpeg(&fixed).is_some_and(|m| m.first_scan_components > 0) && reaches_eoi(&fixed); + if in_scan { Cow::Owned(fixed) } else { Cow::Borrowed(bytes) } +} + +fn image_end(b: &[u8]) -> Option { + let le32 = |at: usize| b.get(at..at.checked_add(4)?)?.try_into().ok().map(|v| u32::from_le_bytes(v) as usize); + let tail = b.len().checked_sub(8)?; + if b.get(tail.checked_add(4)?..)? != b"SEFT" { + return None; + } + let dir = tail.checked_sub(le32(tail)?)?; + if b.get(dir..dir.checked_add(4)?)? != b"SEFH" { + return None; + } + let count = le32(dir.checked_add(8)?)?; + let entries = dir.checked_add(12)?; + if count == 0 || count > tail.checked_sub(entries)? / 12 { + return None; + } + let mut start = dir; + for i in 0..count { + let entry = entries.checked_add(i.checked_mul(12)?)?; + let block = dir.checked_sub(le32(entry.checked_add(4)?)?)?; + let len = le32(entry.checked_add(8)?)?; + let kind = |at: usize| b.get(at.checked_add(2)?..at.checked_add(4)?); + if len < 4 || block.checked_add(len)? > dir || kind(block)? != kind(entry)? { + return None; + } + start = start.min(block); + } + Some(start) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn repairs_only_valid_sef_after_an_open_scan() { + let image = [0xff, 0xd8, 0xff, 0xc0, 0, 8, 8, 0, 1, 0, 1, 1, 0xff, 0xda, 0, 3, 1, 0x12, 0xff, 0, 0x34]; + let mut b = image.to_vec(); + let block = [0, 0, 0xe0, 0x08, 1, 2, 3, 4]; + b.extend_from_slice(&block); + b.extend_from_slice(b"SEFH"); + b.extend_from_slice(&106u32.to_le_bytes()); + b.extend_from_slice(&1u32.to_le_bytes()); + b.extend_from_slice(&[0, 0, 0xe0, 0x08]); + b.extend_from_slice(&(block.len() as u32).to_le_bytes()); + b.extend_from_slice(&(block.len() as u32).to_le_bytes()); + b.extend_from_slice(&24u32.to_le_bytes()); + b.extend_from_slice(b"SEFT"); + let mut expected = image.to_vec(); + expected.extend_from_slice(&[0xff, 0xd9]); + assert_eq!(repair(&b).as_ref(), expected); + assert!(matches!(repair(&image), Cow::Borrowed(_))); + b[image.len() + 2] = 0; + assert!(matches!(repair(&b), Cow::Borrowed(_))); + } + #[test] + fn eoi_requires_valid_lengths_and_skips_stuffed_bytes() { + assert!(reaches_eoi(&[0xff, 0xd8, 0xff, 0, 0xff, 0xd9])); + assert!(!reaches_eoi(&[0xff, 0xd8, 0xff, 0xe1, 0, 1, 0xff, 0xd9])); + assert!(!reaches_eoi(&[0xff, 0xd8, 0xff, 0xe1, 0, 4, 0xff, 0xd9])); + } +} diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..74968ccaa 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -25,6 +25,7 @@ mod fidelity; mod format; mod image; mod inspection; +pub mod jpeg_sef; mod lab; mod options; pub mod orientation; From 5da1f0c521143adaeb1829afa65ef36d623823ef Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:39:20 +0000 Subject: [PATCH 030/200] Cover JPEG scan byte search --- crates/image-codecs/src/codecs/jpeg.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index 158491134..15346ea56 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -678,6 +678,20 @@ mod tests { } /// `info` reads the frame from the markers, and which decoder the file goes to. + #[test] + fn ff_search_matches_plain_search() { + let mut b: Vec = (0..300u32).map(|i| (i * 7 % 255) as u8).collect(); + for at in [None, Some(0), Some(7), Some(8), Some(15), Some(203), Some(296), Some(299)] { + if let Some(i) = at { + b[i] = 0xff; + } + for start in [0, 1, 5, 9, 290, 299, 300] { + let s = &b[start..]; + assert_eq!(find_ff(s), s.iter().position(|&v| v == 0xff)); + } + } + } + #[test] fn info_reads_the_frame_and_the_decoder() { let img = Image::from_raw(37, 21, ChannelLayout::Rgb, SampleType::U8, vec![128; 37 * 21 * 3]).unwrap(); From b30a9623e163637fa0660bc219482435ec93f35f Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:48:29 +0000 Subject: [PATCH 031/200] Share explicit raw EXIF and JPEG APP metadata helpers --- crates/image-codecs/src/lib.rs | 1 + crates/image-codecs/src/raw_metadata.rs | 153 ++++++++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 crates/image-codecs/src/raw_metadata.rs diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 74968ccaa..8f5e7586b 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -29,6 +29,7 @@ pub mod jpeg_sef; mod lab; mod options; pub mod orientation; +pub mod raw_metadata; pub mod resolution; pub mod source_settings; pub mod web; diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs new file mode 100644 index 000000000..e0465776c --- /dev/null +++ b/crates/image-codecs/src/raw_metadata.rs @@ -0,0 +1,153 @@ +//! Explicit verbatim EXIF and JPEG APP metadata helpers for callers that preserve stored orientation. +//! Normal encoder APIs still normalize metadata for upright pixels; callers opt in to these helpers. +use crate::{CodecError, Format}; + +/// Borrowed metadata used to construct JPEG APP segments. +#[derive(Clone, Copy, Default)] +pub struct JpegMetadata<'a> { + /// TIFF-structured EXIF bytes. + pub exif: Option<&'a [u8]>, + /// XMP packet. + pub xmp: Option<&'a str>, + /// ICC profile bytes. + pub icc: Option<&'a [u8]>, + /// Pixels per inch, if nonzero. + pub ppi: Option, +} + +fn error(format: Format, message: &str) -> CodecError { + CodecError::encode(format, message) +} + +/// Build JFIF, EXIF, XMP and ICC APP payloads in that order, preserving bytes and segment limits. +pub fn jpeg_segments(meta: JpegMetadata<'_>) -> Result)>, CodecError> { + let mut segments = Vec::new(); + let density = meta.ppi.filter(|p| *p > 0).map_or([0, 0, 1, 0, 1], |p| { + let [hi, lo] = p.to_be_bytes(); + [1, hi, lo, hi, lo] + }); + segments.push((0xe0, [&b"JFIF\0\x01\x02"[..], &density, &[0, 0]].concat())); + if let Some(exif) = meta.exif { + if exif.len() > 65_527 { + return Err(error(Format::Jpeg, "EXIF larger than one APP1 segment (64 KiB)")); + } + segments.push((0xe1, [&b"Exif\0\0"[..], exif].concat())); + } + if let Some(xmp) = meta.xmp { + segments.push((0xe1, jpeg_xmp(xmp)?)); + } + if let Some(icc) = meta.icc { + let chunks: Vec<_> = icc.chunks(65_519).collect(); + if chunks.len() > 255 { + return Err(error(Format::Jpeg, "ICC profile too large for JPEG")); + } + for (i, chunk) in chunks.iter().enumerate() { + segments.push((0xe2, [&b"ICC_PROFILE\0"[..], &[i as u8 + 1, chunks.len() as u8], chunk].concat())); + } + } + Ok(segments) +} + +/// Build a single standard XMP APP1 payload, rejecting extended-XMP-sized packets. +pub fn jpeg_xmp(xmp: &str) -> Result, CodecError> { + let payload = [&b"http://ns.adobe.com/xap/1.0/\0"[..], xmp.as_bytes()].concat(); + if payload.len() > 65_533 { + return Err(error(Format::Jpeg, "XMP larger than one APP1 segment (extended XMP not supported)")); + } + Ok(payload) +} + +/// Restore bytes in the first existing JPEG EXIF payload when it has room. No segment is inserted. +pub fn replace_jpeg_exif(jpeg: &mut [u8], exif: &[u8]) { + if let Some(pos) = jpeg.windows(6).position(|w| w == b"Exif\0\0") + && let Some(end) = pos.checked_add(6).and_then(|v| v.checked_add(exif.len())) + && let Some(dst) = jpeg.get_mut(pos + 6..end) + { + dst.copy_from_slice(exif); + } +} + +/// Replace the existing PNG eXIf chunk, preserving the other chunks and recomputing its CRC. +/// No chunk is inserted when one is absent. +pub fn replace_png_exif(png: &mut Vec, exif: &[u8]) -> Result<(), CodecError> { + let len = u32::try_from(exif.len()).map_err(|_| error(Format::Png, "EXIF too large"))?; + let mut p = 8usize; + while let Some(bytes) = p.checked_add(4).and_then(|end| png.get(p..end)) { + let size = u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) as usize; + let Some(end) = p.checked_add(12).and_then(|v| v.checked_add(size)).filter(|end| *end <= png.len()) else { break }; + if png.get(p + 4..p + 8) == Some(b"eXIf") { + let mut chunk = Vec::new(); + chunk.extend_from_slice(&len.to_be_bytes()); + chunk.extend_from_slice(b"eXIf"); + chunk.extend_from_slice(exif); + let crc = crc32fast::hash(&chunk[4..]); + chunk.extend_from_slice(&crc.to_be_bytes()); + png.splice(p..end, chunk); + break; + } + p = end; + } + Ok(()) +} + +/// Replace the existing WebP EXIF chunk, including padding and the RIFF size. No chunk is inserted +/// when one is absent. The input must be an encoded WebP as emitted by this crate. +pub fn replace_webp_exif(webp: &mut Vec, exif: &[u8]) -> Result<(), CodecError> { + let len = u32::try_from(exif.len()).map_err(|_| error(Format::WebP, "EXIF too large"))?; + let mut p = 12usize; + while let Some(h) = webp.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).saturating_add(size & 1); + if &h[..4] == b"EXIF" && end <= webp.len() { + let new_len = webp + .len() + .checked_sub(end - p) + .and_then(|v| v.checked_add(8)) + .and_then(|v| v.checked_add(exif.len())) + .and_then(|v| v.checked_add(exif.len() & 1)) + .ok_or_else(|| error(Format::WebP, "RIFF too large"))?; + let riff_len = u32::try_from(new_len.saturating_sub(8)).map_err(|_| error(Format::WebP, "RIFF too large"))?; + let mut chunk = Vec::new(); + chunk.extend_from_slice(b"EXIF"); + chunk.extend_from_slice(&len.to_le_bytes()); + chunk.extend_from_slice(exif); + if exif.len() & 1 == 1 { + chunk.push(0); + } + webp.splice(p..end, chunk); + webp[4..8].copy_from_slice(&riff_len.to_le_bytes()); + break; + } + p = end; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + const EXIF: &[u8] = b"II\x2a\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x06\0\0\0\0\0\0\0"; + #[test] + fn explicit_replacements_preserve_raw_orientation_in_real_encodings() { + let mut image = crate::Image::from_u8(2, 2, crate::ChannelLayout::Rgb, vec![80; 12]).unwrap(); + image.meta.exif = Some(EXIF.to_vec()); + for format in [Format::Jpeg, Format::Png, Format::WebP] { + let mut bytes = crate::encode(&image, format, &crate::EncodeOptions::default()).unwrap(); + match format { + Format::Jpeg => replace_jpeg_exif(&mut bytes, EXIF), + Format::Png => replace_png_exif(&mut bytes, EXIF).unwrap(), + Format::WebP => replace_webp_exif(&mut bytes, EXIF).unwrap(), + _ => unreachable!(), + } + let decoded = crate::decode_as_with(format, &bytes, &crate::DecodeOptions { keep_orientation: true, ..Default::default() }).unwrap(); + assert_eq!(decoded.meta.exif.as_deref().map(crate::exif_orientation), Some(6), "{format:?}"); + } + } + #[test] + fn jpeg_segments_keep_order_and_enforce_limits() { + let parts = jpeg_segments(JpegMetadata { exif: Some(EXIF), xmp: Some(""), icc: Some(&[1, 2]), ppi: Some(300) }).unwrap(); + assert_eq!(parts.iter().map(|v| v.0).collect::>(), [0xe0, 0xe1, 0xe1, 0xe2]); + assert!(jpeg_segments(JpegMetadata { exif: Some(&vec![0; 65_528]), ..Default::default() }).is_err()); + assert!(jpeg_xmp(&"x".repeat(65_533)).is_err()); + } +} From a99e47639e63552863d23696229704fa458c71a7 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:48:37 +0000 Subject: [PATCH 032/200] Keep metadata fixture exhaustive without panic --- crates/image-codecs/src/raw_metadata.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs index e0465776c..d7d21b698 100644 --- a/crates/image-codecs/src/raw_metadata.rs +++ b/crates/image-codecs/src/raw_metadata.rs @@ -137,7 +137,7 @@ mod tests { Format::Jpeg => replace_jpeg_exif(&mut bytes, EXIF), Format::Png => replace_png_exif(&mut bytes, EXIF).unwrap(), Format::WebP => replace_webp_exif(&mut bytes, EXIF).unwrap(), - _ => unreachable!(), + _ => {} } let decoded = crate::decode_as_with(format, &bytes, &crate::DecodeOptions { keep_orientation: true, ..Default::default() }).unwrap(); assert_eq!(decoded.meta.exif.as_deref().map(crate::exif_orientation), Some(6), "{format:?}"); From 8767ba1c7e3198d9aaf2e8bc69320f4b32eb58ea Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:51:06 +0000 Subject: [PATCH 033/200] Compare EXIF replacements on mutated containers --- crates/image-codecs/src/raw_metadata.rs | 70 +++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs index d7d21b698..0ea3a104e 100644 --- a/crates/image-codecs/src/raw_metadata.rs +++ b/crates/image-codecs/src/raw_metadata.rs @@ -127,6 +127,76 @@ pub fn replace_webp_exif(webp: &mut Vec, exif: &[u8]) -> Result<(), CodecErr mod tests { use super::*; const EXIF: &[u8] = b"II\x2a\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x06\0\0\0\0\0\0\0"; + #[test] + fn replacements_match_previous_code_on_mutated_containers() { + fn old_png(png: &mut Vec, exif: &[u8]) { + let mut p = 8usize; + while let Some(b) = png.get(p..p + 4) { + let size = u32::from_be_bytes([b[0], b[1], b[2], b[3]]) as usize; + let end = p.saturating_add(12).saturating_add(size); + if end > png.len() { + break; + } + if png.get(p + 4..p + 8) == Some(b"eXIf") { + let mut chunk = (exif.len() as u32).to_be_bytes().to_vec(); + chunk.extend_from_slice(b"eXIf"); + chunk.extend_from_slice(exif); + let mut crc = 0xffff_ffffu32; + for &v in &chunk[4..] { + crc ^= u32::from(v); + for _ in 0..8 { + crc = if crc & 1 != 0 { (crc >> 1) ^ 0xedb8_8320 } else { crc >> 1 }; + } + } + chunk.extend_from_slice(&(!crc).to_be_bytes()); + png.splice(p..end, chunk); + return; + } + p = end; + } + } + fn old_webp(webp: &mut Vec, exif: &[u8]) { + let mut p = 12usize; + while let Some(h) = webp.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).saturating_add(size & 1); + if &h[..4] == b"EXIF" && end <= webp.len() { + let mut chunk = b"EXIF".to_vec(); + chunk.extend_from_slice(&(exif.len() as u32).to_le_bytes()); + chunk.extend_from_slice(exif); + if exif.len() & 1 == 1 { + chunk.push(0); + } + webp.splice(p..end, chunk); + let size = (webp.len().saturating_sub(8)) as u32; + webp[4..8].copy_from_slice(&size.to_le_bytes()); + return; + } + p = end; + } + } + let mut image = crate::Image::from_u8(2, 2, crate::ChannelLayout::Rgb, vec![80; 12]).unwrap(); + image.meta.exif = Some(EXIF.to_vec()); + for format in [Format::Png, Format::WebP] { + let encoded = crate::encode(&image, format, &crate::EncodeOptions::default()).unwrap(); + for at in 0..encoded.len() { + for value in [0, 255] { + let mut original = encoded.clone(); + original[at] = value; + let mut shared = original.clone(); + if format == Format::Png { + old_png(&mut original, EXIF); + replace_png_exif(&mut shared, EXIF).unwrap(); + } else { + old_webp(&mut original, EXIF); + replace_webp_exif(&mut shared, EXIF).unwrap(); + } + assert_eq!(shared, original, "{format:?}: byte {at} value {value}"); + } + } + } + } + #[test] fn explicit_replacements_preserve_raw_orientation_in_real_encodings() { let mut image = crate::Image::from_u8(2, 2, crate::ChannelLayout::Rgb, vec![80; 12]).unwrap(); From a152abdb8be4817339fb02fabf81bb38d4c4c7ff Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:51:44 +0000 Subject: [PATCH 034/200] Cover JPEG EXIF mutation parity --- crates/image-codecs/src/raw_metadata.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs index 0ea3a104e..6be61992e 100644 --- a/crates/image-codecs/src/raw_metadata.rs +++ b/crates/image-codecs/src/raw_metadata.rs @@ -177,14 +177,21 @@ mod tests { } let mut image = crate::Image::from_u8(2, 2, crate::ChannelLayout::Rgb, vec![80; 12]).unwrap(); image.meta.exif = Some(EXIF.to_vec()); - for format in [Format::Png, Format::WebP] { + for format in [Format::Jpeg, Format::Png, Format::WebP] { let encoded = crate::encode(&image, format, &crate::EncodeOptions::default()).unwrap(); for at in 0..encoded.len() { for value in [0, 255] { let mut original = encoded.clone(); original[at] = value; let mut shared = original.clone(); - if format == Format::Png { + if format == Format::Jpeg { + if let Some(pos) = original.windows(6).position(|w| w == b"Exif\0\0") + && let Some(dst) = original.get_mut(pos + 6..pos + 6 + EXIF.len()) + { + dst.copy_from_slice(EXIF); + } + replace_jpeg_exif(&mut shared, EXIF); + } else if format == Format::Png { old_png(&mut original, EXIF); replace_png_exif(&mut shared, EXIF).unwrap(); } else { From 1ef2c5359dc671fb6ca7f851a623a9a919b5867c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:53:32 +0000 Subject: [PATCH 035/200] Verify default EXIF normalization remains intact --- crates/image-codecs/src/raw_metadata.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs index 6be61992e..3a6c13eb7 100644 --- a/crates/image-codecs/src/raw_metadata.rs +++ b/crates/image-codecs/src/raw_metadata.rs @@ -210,6 +210,8 @@ mod tests { image.meta.exif = Some(EXIF.to_vec()); for format in [Format::Jpeg, Format::Png, Format::WebP] { let mut bytes = crate::encode(&image, format, &crate::EncodeOptions::default()).unwrap(); + let normal = crate::decode_as_with(format, &bytes, &crate::DecodeOptions { keep_orientation: true, ..Default::default() }).unwrap(); + assert_eq!(normal.meta.exif.as_deref().map(crate::exif_orientation), Some(1), "default {format:?}"); match format { Format::Jpeg => replace_jpeg_exif(&mut bytes, EXIF), Format::Png => replace_png_exif(&mut bytes, EXIF).unwrap(), From 3a28181f0e8aaade4e7dd5fc712dd1fec58499a1 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:55:14 +0000 Subject: [PATCH 036/200] Cover JPEG ICC segment boundaries --- crates/image-codecs/src/raw_metadata.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/crates/image-codecs/src/raw_metadata.rs b/crates/image-codecs/src/raw_metadata.rs index 3a6c13eb7..76fa4aa73 100644 --- a/crates/image-codecs/src/raw_metadata.rs +++ b/crates/image-codecs/src/raw_metadata.rs @@ -228,5 +228,10 @@ mod tests { assert_eq!(parts.iter().map(|v| v.0).collect::>(), [0xe0, 0xe1, 0xe1, 0xe2]); assert!(jpeg_segments(JpegMetadata { exif: Some(&vec![0; 65_528]), ..Default::default() }).is_err()); assert!(jpeg_xmp(&"x".repeat(65_533)).is_err()); + let profile = vec![42; 65_520]; + let chunks = jpeg_segments(JpegMetadata { icc: Some(&profile), ..Default::default() }).unwrap(); + assert_eq!(chunks.len(), 3); + assert_eq!(&chunks[1].1[12..14], &[1, 2]); + assert_eq!(&chunks[2].1[12..14], &[2, 2]); } } From c6f4f5115e6d7e5a53180f297c7cda8c5c4cb3c9 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:12:58 +0000 Subject: [PATCH 037/200] Preserve legacy EXIF orientation in PNG inspection --- crates/image-codecs/src/png_probe.rs | 2 +- crates/metadata/src/compat_orientation.rs | 52 +++++++++++++++++++++++ crates/metadata/src/lib.rs | 1 + 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 crates/metadata/src/compat_orientation.rs diff --git a/crates/image-codecs/src/png_probe.rs b/crates/image-codecs/src/png_probe.rs index 7edda454d..73f1199eb 100644 --- a/crates/image-codecs/src/png_probe.rs +++ b/crates/image-codecs/src/png_probe.rs @@ -88,7 +88,7 @@ pub fn header_with_max_pixels(b: &[u8], max_pixels: u64) -> Result<(u32, u32, u1 if !after_idat { return Err(err("truncated image data")); } - Ok((w, h, exif.map_or(1, crate::exif_orientation))) + Ok((w, h, exif.map_or(1, craft_metadata::compat_orientation::orientation))) } /// Container color declarations preceding image data. Raw values leave color policy to callers. diff --git a/crates/metadata/src/compat_orientation.rs b/crates/metadata/src/compat_orientation.rs new file mode 100644 index 000000000..3590b7c48 --- /dev/null +++ b/crates/metadata/src/compat_orientation.rs @@ -0,0 +1,52 @@ +//! Compatibility orientation reading for legacy clients that accepted loosely formed classic EXIF. +//! The ordinary `exif_orientation` API remains strict; use this only to retain older behavior. + +/// Read the last IFD0 orientation entry as older lightweight readers did. Entry count is bounded; +/// a complete entry table is required, but an absent next-IFD pointer is accepted. BYTE, UNDEFINED, +/// SHORT, LONG and IFD values are read inline regardless of count. Invalid/missing values give 1. +pub fn orientation(bytes: &[u8]) -> u16 { + let b = bytes.strip_prefix(b"Exif\0\0").unwrap_or(bytes); + let little = match b.get(..2) { + Some(b"II") => true, + Some(b"MM") => false, + _ => return 1, + }; + let u16_at = + |at: usize| b.get(at..at.checked_add(2)?).map(|v| if little { u16::from_le_bytes([v[0], v[1]]) } else { u16::from_be_bytes([v[0], v[1]]) }); + let u32_at = |at: usize| { + b.get(at..at.checked_add(4)?) + .map(|v| if little { u32::from_le_bytes([v[0], v[1], v[2], v[3]]) } else { u32::from_be_bytes([v[0], v[1], v[2], v[3]]) }) + }; + if u16_at(2) != Some(42) { + return 1; + } + let Some(ifd) = u32_at(4).and_then(|v| usize::try_from(v).ok()) else { return 1 }; + let Some(count) = u16_at(ifd).map(usize::from).filter(|n| *n <= 4096) else { return 1 }; + let Some(start) = ifd.checked_add(2) else { return 1 }; + let Some(end) = count.checked_mul(12).and_then(|n| start.checked_add(n)).filter(|end| *end <= b.len()) else { return 1 }; + let mut orientation = None; + for at in (start..end).step_by(12) { + if u16_at(at) == Some(0x0112) { + let value = match u16_at(at + 2) { + Some(3) => u16_at(at + 8).map(u32::from), + Some(4 | 13) => u32_at(at + 8), + Some(1 | 7) => b.get(at + 8).copied().map(u32::from), + _ => None, + }; + orientation = value.map(|v| v as u16).filter(|v| (1..=8).contains(v)); + } + } + orientation.unwrap_or(1) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn accepts_legacy_count_zero_but_bounds_the_table() { + let mut b = b"II\x2a\0\x08\0\0\0\x01\0\x12\x01\x03\0\0\0\0\0\x06\0\0\0".to_vec(); + assert_eq!(orientation(&b), 6); + b.truncate(21); + assert_eq!(orientation(&b), 1); + } +} diff --git a/crates/metadata/src/lib.rs b/crates/metadata/src/lib.rs index ff2c530fa..05f9b81b4 100644 --- a/crates/metadata/src/lib.rs +++ b/crates/metadata/src/lib.rs @@ -20,6 +20,7 @@ //! [`Embedded`] and call [`from_embedded`]. pub mod camera_fields; +pub mod compat_orientation; mod container; pub mod cr3; mod datetime; From e3712dd643591f1a36ab04e5be6329e8fd4d8a76 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:14:48 +0000 Subject: [PATCH 038/200] Preserve legacy WebP EXIF orientation --- crates/image-codecs/src/webp_probe.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index 8e33a71cf..07d6e0269 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -26,7 +26,7 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { return Err(err("no image data")); } let (w, h) = crate::probe_size(bytes)?; - let orientation = exif.map_or(1, crate::exif_orientation); + let orientation = exif.map_or(1, craft_metadata::compat_orientation::orientation); let (w, h) = if (5..=8).contains(&orientation) { (h, w) } else { (w, h) }; Ok((w, h, orientation)) } From f04d6381c76a4ff68b255a59c17ee3b32d73949b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:18:18 +0000 Subject: [PATCH 039/200] Share legacy EXIF summary and thumbnail inspection --- crates/metadata/src/compat_orientation.rs | 206 ++++++++++++++++++---- 1 file changed, 168 insertions(+), 38 deletions(-) diff --git a/crates/metadata/src/compat_orientation.rs b/crates/metadata/src/compat_orientation.rs index 3590b7c48..69f6c9517 100644 --- a/crates/metadata/src/compat_orientation.rs +++ b/crates/metadata/src/compat_orientation.rs @@ -1,52 +1,182 @@ -//! Compatibility orientation reading for legacy clients that accepted loosely formed classic EXIF. -//! The ordinary `exif_orientation` API remains strict; use this only to retain older behavior. +//! Compatibility EXIF summary and helpers for legacy clients that accepted loosely formed classic TIFF. +//! The ordinary strict EXIF orientation API remains unchanged. -/// Read the last IFD0 orientation entry as older lightweight readers did. Entry count is bounded; -/// a complete entry table is required, but an absent next-IFD pointer is accepted. BYTE, UNDEFINED, -/// SHORT, LONG and IFD values are read inline regardless of count. Invalid/missing values give 1. +/// Read a legacy orientation, with an optional `Exif\0\0` prefix. pub fn orientation(bytes: &[u8]) -> u16 { - let b = bytes.strip_prefix(b"Exif\0\0").unwrap_or(bytes); - let little = match b.get(..2) { - Some(b"II") => true, - Some(b"MM") => false, - _ => return 1, - }; - let u16_at = - |at: usize| b.get(at..at.checked_add(2)?).map(|v| if little { u16::from_le_bytes([v[0], v[1]]) } else { u16::from_be_bytes([v[0], v[1]]) }); - let u32_at = |at: usize| { - b.get(at..at.checked_add(4)?) - .map(|v| if little { u32::from_le_bytes([v[0], v[1], v[2], v[3]]) } else { u32::from_be_bytes([v[0], v[1], v[2], v[3]]) }) - }; - if u16_at(2) != Some(42) { - return 1; + summarize(bytes.strip_prefix(b"Exif\0\0").unwrap_or(bytes)).orientation.unwrap_or(1) +} + +/// Byte-order aware reader over a TIFF-structured blob. +#[derive(Clone, Copy)] +struct Tiff<'a> { + pub data: &'a [u8], + le: bool, +} + +#[derive(Clone, Copy, Debug)] +struct Entry { + pub tag: u16, + pub typ: u16, + pub count: u32, + /// Offset of the 4-byte value/offset field within `data`. + pub value_pos: usize, +} + +impl<'a> Tiff<'a> { + pub fn new(data: &'a [u8]) -> Option> { + let le = match data.get(0..2)? { + b"II" => true, + b"MM" => false, + _ => return None, + }; + Some(Tiff { data, le }) } - let Some(ifd) = u32_at(4).and_then(|v| usize::try_from(v).ok()) else { return 1 }; - let Some(count) = u16_at(ifd).map(usize::from).filter(|n| *n <= 4096) else { return 1 }; - let Some(start) = ifd.checked_add(2) else { return 1 }; - let Some(end) = count.checked_mul(12).and_then(|n| start.checked_add(n)).filter(|end| *end <= b.len()) else { return 1 }; - let mut orientation = None; - for at in (start..end).step_by(12) { - if u16_at(at) == Some(0x0112) { - let value = match u16_at(at + 2) { - Some(3) => u16_at(at + 8).map(u32::from), - Some(4 | 13) => u32_at(at + 8), - Some(1 | 7) => b.get(at + 8).copied().map(u32::from), - _ => None, - }; - orientation = value.map(|v| v as u16).filter(|v| (1..=8).contains(v)); + pub fn u16_at(&self, pos: usize) -> Option { + let b = self.data.get(pos..pos.checked_add(2)?)?; + Some(if self.le { u16::from_le_bytes([b[0], b[1]]) } else { u16::from_be_bytes([b[0], b[1]]) }) + } + pub fn u32_at(&self, pos: usize) -> Option { + let b = self.data.get(pos..pos.checked_add(4)?)?; + let a = [b[0], b[1], b[2], b[3]]; + Some(if self.le { u32::from_le_bytes(a) } else { u32::from_be_bytes(a) }) + } + pub fn first_ifd(&self) -> Option { + let magic = self.u16_at(2)?; + if magic != 42 { + return None; + } + Some(self.u32_at(4)? as usize) + } + /// Entries of the IFD at `pos` and the offset of the next IFD (0 = none). + pub fn ifd(&self, pos: usize) -> Option<(Vec, usize)> { + let n = self.u16_at(pos)? as usize; + if n > 4096 { + return None; + } + let mut v = Vec::with_capacity(n); + for i in 0..n { + let e = pos.checked_add(2)?.checked_add(i.checked_mul(12)?)?; + v.push(Entry { tag: self.u16_at(e)?, typ: self.u16_at(e + 2)?, count: self.u32_at(e + 4)?, value_pos: e + 8 }); + } + let next = + pos.checked_add(2).and_then(|p| n.checked_mul(12).and_then(|v| p.checked_add(v))).and_then(|p| self.u32_at(p)).unwrap_or(0) as usize; + Some((v, next)) + } + /// First value of a SHORT/LONG entry. + pub fn uint(&self, e: &Entry) -> Option { + match e.typ { + 3 => self.u16_at(e.value_pos).map(u32::from), + 4 | 13 => self.u32_at(e.value_pos), + 1 | 7 => self.data.get(e.value_pos).map(|b| *b as u32), + _ => None, } } - orientation.unwrap_or(1) + /// Raw bytes of an entry's value (for ASCII/UNDEFINED/BYTE types). + pub fn bytes(&self, e: &Entry) -> Option<&'a [u8]> { + let size = match e.typ { + 1 | 2 | 6 | 7 => 1usize, + 3 | 8 => 2, + 4 | 9 | 11 | 13 => 4, + 5 | 10 | 12 => 8, + _ => return None, + }; + let len = size.checked_mul(e.count as usize)?; + let start = if len <= 4 { e.value_pos } else { self.u32_at(e.value_pos)? as usize }; + self.data.get(start..start.checked_add(len)?) + } +} + +/// What the decoder cares about from an EXIF (TIFF-structured) blob. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct ExifSummary { + /// Valid orientation (1–8), if present. + pub orientation: Option, + /// (offset, length) of the IFD1 JPEG thumbnail within the blob. + pub thumbnail: Option<(usize, usize)>, + /// EXIF ColorSpace = 0xFFFF with InteropIndex "R03" (Adobe RGB (1998) "option" files). + pub adobe_rgb_hint: bool, +} + +pub fn summarize(blob: &[u8]) -> ExifSummary { + let mut s = ExifSummary::default(); + let Some(t) = Tiff::new(blob) else { return s }; + let Some(ifd0) = t.first_ifd() else { return s }; + let Some((entries, next)) = t.ifd(ifd0) else { return s }; + let mut exif_ifd = None; + for e in &entries { + match e.tag { + 0x0112 => s.orientation = t.uint(e).map(|v| v as u16).filter(|v| (1..=8).contains(v)), + 0x8769 => exif_ifd = t.uint(e).map(|v| v as usize), + _ => {} + } + } + if next != 0 + && next != ifd0 + && let Some((e1, _)) = t.ifd(next) + { + let off = e1.iter().find(|e| e.tag == 0x0201).and_then(|e| t.uint(e)); + let len = e1.iter().find(|e| e.tag == 0x0202).and_then(|e| t.uint(e)); + if let (Some(o), Some(l)) = (off, len) { + let (o, l) = (o as usize, l as usize); + if l > 4 && o.checked_add(l).is_some_and(|end| end <= blob.len()) && blob[o..o + 2] == [0xFF, 0xD8] { + s.thumbnail = Some((o, l)); + } + } + } + if let Some(p) = exif_ifd + && let Some((ee, _)) = t.ifd(p) + { + let cs = ee.iter().find(|e| e.tag == 0xA001).and_then(|e| t.uint(e)); + let interop = ee.iter().find(|e| e.tag == 0xA005).and_then(|e| t.uint(e)); + if cs == Some(0xFFFF) + && let Some((ie, _)) = interop.and_then(|p| t.ifd(p as usize)) + { + s.adobe_rgb_hint = ie.iter().any(|e| e.tag == 1 && t.bytes(e).is_some_and(|b| b.starts_with(b"R03"))); + } + } + s +} + +/// Build a tiny EXIF blob (little-endian TIFF) with just an orientation tag. Used by tests and by +/// callers that need to stamp orientation on export when no source EXIF exists. +pub fn minimal_exif(orientation: u16) -> Vec { + let mut v = Vec::with_capacity(26); + v.extend_from_slice(b"II"); + v.extend_from_slice(&42u16.to_le_bytes()); + v.extend_from_slice(&8u32.to_le_bytes()); + v.extend_from_slice(&1u16.to_le_bytes()); + v.extend_from_slice(&0x0112u16.to_le_bytes()); + v.extend_from_slice(&3u16.to_le_bytes()); + v.extend_from_slice(&1u32.to_le_bytes()); + v.extend_from_slice(&orientation.to_le_bytes()); + v.extend_from_slice(&[0, 0]); + v.extend_from_slice(&0u32.to_le_bytes()); + v } #[cfg(test)] mod tests { use super::*; + #[test] fn accepts_legacy_count_zero_but_bounds_the_table() { - let mut b = b"II\x2a\0\x08\0\0\0\x01\0\x12\x01\x03\0\0\0\0\0\x06\0\0\0".to_vec(); - assert_eq!(orientation(&b), 6); - b.truncate(21); - assert_eq!(orientation(&b), 1); + let mut bytes = minimal_exif(6); + bytes[14..18].fill(0); + assert_eq!(orientation(&bytes), 6); + bytes.truncate(21); + assert_eq!(orientation(&bytes), 1); + } + + #[test] + fn orientation_roundtrip() { + for o in 1..=8 { + assert_eq!(summarize(&minimal_exif(o)).orientation, Some(o)); + } + } + + #[test] + fn garbage_ok() { + assert_eq!(summarize(b"II*\0\xff\xff\xff\xff"), ExifSummary::default()); + assert_eq!(summarize(&[]), ExifSummary::default()); } } From 42abc84c82cd573e2fb0277298caffecb7bee905 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:19:33 +0000 Subject: [PATCH 040/200] Match legacy partial-value boundary --- crates/metadata/src/compat_orientation.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/metadata/src/compat_orientation.rs b/crates/metadata/src/compat_orientation.rs index 69f6c9517..22db7b414 100644 --- a/crates/metadata/src/compat_orientation.rs +++ b/crates/metadata/src/compat_orientation.rs @@ -163,7 +163,7 @@ mod tests { let mut bytes = minimal_exif(6); bytes[14..18].fill(0); assert_eq!(orientation(&bytes), 6); - bytes.truncate(21); + bytes.truncate(19); assert_eq!(orientation(&bytes), 1); } From 1fb21f048785bba73b5ba604ec61cf5fb69367b0 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:25:28 +0000 Subject: [PATCH 041/200] Share legacy TIFF RAW classification policy --- crates/image-codecs/src/codecs/tiff.rs | 93 +++++++++++++++++++- crates/image-codecs/src/lib.rs | 6 ++ crates/image-codecs/tests/legacy_tiff_raw.rs | 21 +++++ 3 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 crates/image-codecs/tests/legacy_tiff_raw.rs diff --git a/crates/image-codecs/src/codecs/tiff.rs b/crates/image-codecs/src/codecs/tiff.rs index c74ab4436..376d3dcf6 100644 --- a/crates/image-codecs/src/codecs/tiff.rs +++ b/crates/image-codecs/src/codecs/tiff.rs @@ -71,6 +71,18 @@ const TAG_DNG_VERSION: u16 = 50706; /// first IFD is often a reduced preview, so this runs before decoding. /// Reads only bounds-checked header bytes; anything malformed is "not raw". fn camera_raw(b: &[u8]) -> bool { + camera_raw_mode(b, false) +} + +/// The older LightCraft RAW/TIFF classification policy, sharing this bounded directory walk. +pub(crate) fn legacy_camera_raw(b: &[u8]) -> bool { + camera_raw_mode(b, true) +} + +fn camera_raw_mode(b: &[u8], legacy: bool) -> bool { + if legacy && b.get(8..10) == Some(b"CR") { + return true; + } let le = match b.get(0..4) { Some(b"II*\0") => true, Some(b"MM\0*") => false, @@ -92,8 +104,48 @@ fn camera_raw(b: &[u8]) -> bool { let value = |e: usize| match u16_at(e.saturating_add(2))? { 3 => u16_at(e.saturating_add(8)).map(u32::from), 4 | 13 => u32_at(e.saturating_add(8)), + 1 | 7 if legacy => b.get(e.saturating_add(8)).copied().map(u32::from), _ => None, }; + // The compatibility policy recognizes Sony lossless YCbCr only when IFD0 names Sony. + let is_sony = if legacy { + u32_at(4) + .and_then(|v| usize::try_from(v).ok()) + .and_then(|ifd| { + let n = usize::from(u16_at(ifd)?); + if n > 4096 { + return None; + } + for i in 0..n { + let e = ifd.checked_add(2)?.checked_add(i.checked_mul(12)?)?; + let tag = u16_at(e)?; + let ty = u16_at(e + 2)?; + let count = u32_at(e + 4)? as usize; + if tag == 0x010f { + let matches = (|| { + let size = match ty { + 1 | 2 | 6 | 7 => 1usize, + 3 | 8 => 2, + 4 | 9 | 11 | 13 => 4, + 5 | 10 | 12 => 8, + _ => return None, + }; + let len = size.checked_mul(count)?; + let start = if len <= 4 { e + 8 } else { u32_at(e + 8)? as usize }; + Some(b.get(start..start.checked_add(len)?)?.get(..4)?.eq_ignore_ascii_case(b"SONY")) + })() + .unwrap_or(false); + if matches { + return Some(true); + } + } + } + Some(false) + }) + .unwrap_or(false) + } else { + false + }; let mut queue: Vec = u32_at(4).into_iter().collect(); let mut visited = 0; while let Some(ifd) = queue.pop() { @@ -104,6 +156,44 @@ fn camera_raw(b: &[u8]) -> bool { } let ifd = ifd as usize; let Some(n) = u16_at(ifd) else { continue }; + if legacy + && (n > 4096 + || (n > 0 + && ifd + .checked_add(2) + .and_then(|p| usize::from(n - 1).checked_mul(12).and_then(|v| p.checked_add(v))) + .and_then(|p| p.checked_add(8)) + .is_none_or(|end| end > b.len()))) + { + continue; + } + if is_sony { + let mut cfa = false; + let (mut compression, mut photo, mut samples) = (None, None, None); + let (mut saw_compression, mut saw_photo, mut saw_samples) = (false, false, false); + for i in 0..usize::from(n) { + let e = ifd.saturating_add(2 + 12 * i); + match u16_at(e) { + Some(0x828e) => cfa = true, + Some(0x0103) if !saw_compression => { + saw_compression = true; + compression = value(e); + } + Some(0x0106) if !saw_photo => { + saw_photo = true; + photo = value(e); + } + Some(0x0115) if !saw_samples => { + saw_samples = true; + samples = value(e); + } + _ => {} + } + } + if cfa && compression == Some(7) && photo == Some(6) && samples == Some(3) { + return true; + } + } for i in 0..usize::from(n) { let e = ifd.saturating_add(2 + 12 * i); let (Some(tag), Some(count)) = (u16_at(e), u32_at(e.saturating_add(4))) else { @@ -111,6 +201,7 @@ fn camera_raw(b: &[u8]) -> bool { }; match tag { TAG_DNG_VERSION => return true, + 0x0103 if legacy && matches!(value(e), Some(32767 | 32769 | 32770 | 34316 | 34713 | 65000 | 65535)) => return true, TAG_PHOTOMETRIC if matches!(value(e), Some(PHOTOMETRIC_CFA | PHOTOMETRIC_LINEAR_RAW)) => { return true; } @@ -125,7 +216,7 @@ fn camera_raw(b: &[u8]) -> bool { _ => {} } } - if let Some(next) = u32_at(ifd.saturating_add(2 + 12 * usize::from(n))).filter(|&o| o != 0) { + if !legacy && let Some(next) = u32_at(ifd.saturating_add(2 + 12 * usize::from(n))).filter(|&o| o != 0) { queue.push(next); } } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index d8659bf54..96a6d78a2 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -216,6 +216,12 @@ pub fn probe_size(bytes: &[u8]) -> Result<(u32, u32), CodecError> { Ok(if (5..=8).contains(&o) { (h, w) } else { (w, h) }) } +/// Classify classic TIFF camera RAWs using LightCraft's historical bounded heuristic. +/// This compatibility policy differs from the decoder's own RAW rejection policy. +pub fn legacy_tiff_raw_hint(bytes: &[u8]) -> bool { + tiff::legacy_camera_raw(bytes) +} + /// A JPEG's frame as its header declares it, read without decoding pixels: the stored size, the /// layout [`decode`] returns, whether [`decode`] hands the file to its whole-coefficient /// decoder (arithmetic-coded, lossless or 12-bit frames), whose working set is several times the diff --git a/crates/image-codecs/tests/legacy_tiff_raw.rs b/crates/image-codecs/tests/legacy_tiff_raw.rs new file mode 100644 index 000000000..87d99bad7 --- /dev/null +++ b/crates/image-codecs/tests/legacy_tiff_raw.rs @@ -0,0 +1,21 @@ +use craft_image_codecs::legacy_tiff_raw_hint; + +fn tiff(tag: u16, ty: u16, value: u32) -> Vec { + let mut b = b"II\x2a\0\x08\0\0\0\x01\0".to_vec(); + b.extend_from_slice(&tag.to_le_bytes()); + b.extend_from_slice(&ty.to_le_bytes()); + b.extend_from_slice(&1u32.to_le_bytes()); + b.extend_from_slice(&value.to_le_bytes()); + b.extend_from_slice(&0u32.to_le_bytes()); + b +} + +#[test] +fn recognizes_legacy_raw_compression_and_broad_cr_marker() { + assert!(legacy_tiff_raw_hint(&tiff(0x0103, 3, 34713))); + assert!(!legacy_tiff_raw_hint(&tiff(0x0103, 3, 1))); + assert!(legacy_tiff_raw_hint(b"II*\0\x08\0\0\0CR")); + let mut cut = tiff(0xc612, 1, 1); + cut.truncate(17); + assert!(!legacy_tiff_raw_hint(&cut)); +} From d052bfdd5c87764a59560949cd8d92c4353f5529 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 12:30:01 -0500 Subject: [PATCH 042/200] retrigger CI From 34a40314adcd84fa521bf0e0022da787e962cd46 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:31:17 +0000 Subject: [PATCH 043/200] Exercise optional AVIF codecs in coverage --- .github/workflows/sonarcloud.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml index 654fe4c02..40d2defff 100644 --- a/.github/workflows/sonarcloud.yml +++ b/.github/workflows/sonarcloud.yml @@ -23,5 +23,5 @@ jobs: # The codec and format code behind features that are off by default. Without these the # coverage build never compiles it, and new code there reads as untested. cargo-features: >- - craft-video/dnx,craft-video/vp8,craft-video/prores,craft-video/h264,craft-video/hevc,craft-video/vp9,craft-video/av1,craft-video/threads,craft-audio/decode,craft-audio/encode,craft-audio/peaks,craft-audio/rayon,craft-audio/serde,craft-media/matroska,craft-media/ogg,craft-media/bitstream,craft-media/serde,craft-mesh/stl,craft-mesh/obj,craft-mesh/ply,craft-mesh/gltf,craft-metafile/write + craft-image-codecs/avif,craft-image-codecs/avif-decode,craft-video/dnx,craft-video/vp8,craft-video/prores,craft-video/h264,craft-video/hevc,craft-video/vp9,craft-video/av1,craft-video/threads,craft-audio/decode,craft-audio/encode,craft-audio/peaks,craft-audio/rayon,craft-audio/serde,craft-media/matroska,craft-media/ogg,craft-media/bitstream,craft-media/serde,craft-mesh/stl,craft-mesh/obj,craft-mesh/ply,craft-mesh/gltf,craft-metafile/write secrets: inherit From d7696c4c767857d21e34e0718f33caff6df02665 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:32:45 +0000 Subject: [PATCH 044/200] Format Sun Raster feature gates --- crates/image-codecs/src/codecs.rs | 4 ++-- crates/image-codecs/src/format.rs | 8 +++++++- crates/image-codecs/src/lib.rs | 24 ++++++++++++++++-------- 3 files changed, 25 insertions(+), 11 deletions(-) diff --git a/crates/image-codecs/src/codecs.rs b/crates/image-codecs/src/codecs.rs index cc1b5a44e..81288cb4d 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -18,10 +18,10 @@ pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; pub(crate) mod pnm; -#[cfg(feature = "sunraster")] -pub(crate) mod sunraster; #[cfg(feature = "sgi")] pub(crate) mod sgi; +#[cfg(feature = "sunraster")] +pub(crate) mod sunraster; pub(crate) mod tga; pub(crate) mod tiff; pub(crate) mod tiff_exif; diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index aab2292b0..f4f3c7186 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -328,7 +328,13 @@ 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 { read: cfg!(feature = "sunraster"), write: cfg!(feature = "sunraster"), layouts: &[L::Gray, L::Rgb, L::Rgba], alpha: true, ..base }, + Format::SunRaster => FormatCaps { + read: cfg!(feature = "sunraster"), + write: cfg!(feature = "sunraster"), + layouts: &[L::Gray, L::Rgb, L::Rgba], + alpha: true, + ..base + }, Format::Sgi => { FormatCaps { read: cfg!(feature = "sgi"), write: cfg!(feature = "sgi"), depths: &[S::U8, S::U16], layouts: RGB_GRAY, alpha: true, ..base } } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index c86301520..e958bada6 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -64,10 +64,10 @@ 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; -#[cfg(feature = "sunraster")] -use crate::codecs::sunraster; #[cfg(feature = "sgi")] use crate::codecs::sgi; +#[cfg(feature = "sunraster")] +use crate::codecs::sunraster; use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jpegls, jxl, pcx, png, pnm, tiff, via_image, webp, xpm}; /// Detect the format and decode with default [`Limits`]. @@ -109,10 +109,14 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res Format::Iff => iff::decode(bytes, l), Format::SunRaster => { #[cfg(feature = "sunraster")] - { sunraster::decode(bytes, l) } + { + sunraster::decode(bytes, l) + } #[cfg(not(feature = "sunraster"))] - { Err(CodecError::unsupported(format, "Sun Raster support requires the sunraster feature")) } - }, + { + Err(CodecError::unsupported(format, "Sun Raster support requires the sunraster feature")) + } + } Format::Sgi => { #[cfg(feature = "sgi")] { @@ -482,10 +486,14 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result iff::encode(image, plan), Format::SunRaster => { #[cfg(feature = "sunraster")] - { sunraster::encode(image, plan) } + { + sunraster::encode(image, plan) + } #[cfg(not(feature = "sunraster"))] - { Err(CodecError::unsupported(format, "Sun Raster support requires the sunraster feature")) } - }, + { + Err(CodecError::unsupported(format, "Sun Raster support requires the sunraster feature")) + } + } Format::Sgi => { #[cfg(feature = "sgi")] { From d2f95f488c25ef3d94746148ef63d9d190259ac4 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:33:21 +0000 Subject: [PATCH 045/200] Include Sun Raster in coverage build --- .github/workflows/sonarcloud.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml index 654fe4c02..f27878af5 100644 --- a/.github/workflows/sonarcloud.yml +++ b/.github/workflows/sonarcloud.yml @@ -23,5 +23,5 @@ jobs: # The codec and format code behind features that are off by default. Without these the # coverage build never compiles it, and new code there reads as untested. cargo-features: >- - craft-video/dnx,craft-video/vp8,craft-video/prores,craft-video/h264,craft-video/hevc,craft-video/vp9,craft-video/av1,craft-video/threads,craft-audio/decode,craft-audio/encode,craft-audio/peaks,craft-audio/rayon,craft-audio/serde,craft-media/matroska,craft-media/ogg,craft-media/bitstream,craft-media/serde,craft-mesh/stl,craft-mesh/obj,craft-mesh/ply,craft-mesh/gltf,craft-metafile/write + craft-video/dnx,craft-video/vp8,craft-video/prores,craft-video/h264,craft-video/hevc,craft-video/vp9,craft-video/av1,craft-video/threads,craft-audio/decode,craft-audio/encode,craft-audio/peaks,craft-audio/rayon,craft-audio/serde,craft-media/matroska,craft-media/ogg,craft-media/bitstream,craft-media/serde,craft-mesh/stl,craft-mesh/obj,craft-mesh/ply,craft-mesh/gltf,craft-metafile/write,craft-image-codecs/sunraster secrets: inherit From a864f0c27eba27cb5069d78e2b4f676b81fb23e0 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 17:41:29 +0000 Subject: [PATCH 046/200] timeline: offer bounded FCPXML diagnostics --- crates/timeline/src/fcpxml.rs | 100 ++++++++++++++++++++--------- crates/timeline/src/report.rs | 11 ++++ crates/timeline/tests/it/fcpxml.rs | 16 +++++ 3 files changed, 96 insertions(+), 31 deletions(-) diff --git a/crates/timeline/src/fcpxml.rs b/crates/timeline/src/fcpxml.rs index 4a255ba43..88cbce1cf 100644 --- a/crates/timeline/src/fcpxml.rs +++ b/crates/timeline/src/fcpxml.rs @@ -139,6 +139,7 @@ struct Imp<'a, 'c, 'r> { b: Builder<'c>, opts: &'a ImportOptions<'a>, report: &'r mut Report, + report_limit: Option, formats: HashMap, asset_nodes: HashMap>, assets: HashMap, @@ -181,6 +182,10 @@ struct Ctx { /// Read an FCPXML document. Media paths are resolved against `opts.base_dir`; filters are looked /// up in `opts.catalog` by name. What cannot be represented is in `report`. pub fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result { + import_with_report_limit(text, opts, report, None) +} +/// Read FCPXML with an optional distinct-diagnostic limit. +pub fn import_with_report_limit(text: &str, opts: &ImportOptions, report: &mut Report, report_limit: Option) -> Result { let doc = crate::xml::parse(text).map_err(|e| Error::parse(Format::Fcpxml, e))?; let root = Node(&doc); if root.name() != "fcpxml" { @@ -189,7 +194,7 @@ pub fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result().ok()).unwrap_or(0); if !v.starts_with("1.") || minor > 11 { - report.info(format!("FCPXML version {v} is newer than 1.11; unknown elements were ignored")); + report.info_limited(report_limit, format!("FCPXML version {v} is newer than 1.11; unknown elements were ignored")); } } let lib_name = child(root, "library").and_then(|l| child(l, "event")).and_then(|e| e.attribute("name")).unwrap_or("Imported FCPXML"); @@ -197,6 +202,7 @@ pub fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result Result { let rate = match r.attribute("frameDuration") { Some(fd) => rate_from_frame_duration(fd).unwrap_or_else(|| { - imp.report.warn(format!("format \"{id}\" has an invalid frameDuration \"{fd}\"; the default frame rate was used")); + imp.report.warn_limited( + imp.report_limit, + format!("format \"{id}\" has an invalid frameDuration \"{fd}\"; the default frame rate was used"), + ); FrameRate::default() }), None => FrameRate::default(), @@ -274,7 +283,7 @@ pub fn import(text: &str, opts: &ImportOptions, report: &mut Report) -> Result Imp<'a, '_, '_> { self.b.file_media(&format!("file:{p}"), &name, &p, &spec, bin) } None => { - self.report.warn(format!("asset \"{name}\" has no media; imported offline")); + self.report.warn_limited(self.report_limit, format!("asset \"{name}\" has no media; imported offline")); let p = resolve_path(&name, self.opts.base_dir); let it = self.b.file_media(&format!("asset:{id}"), &name, &p, &spec, bin); if let Some(m) = self.b.p.item_mut(it).and_then(|i| i.as_media_mut()) { @@ -365,7 +374,7 @@ impl<'a> Imp<'a, '_, '_> { // Check before the cache: a truncated resource may already have an item while it // is being rebuilt, but a back-edge must never turn that item into a self-cycle. if self.media_active.contains(id) { - self.report.warn(format!("recursive FCPXML media resource {id:?} ignored")); + self.report.warn_limited(self.report_limit, format!("recursive FCPXML media resource {id:?} ignored")); return None; } let depth = self.media_active.len(); @@ -381,9 +390,10 @@ impl<'a> Imp<'a, '_, '_> { if !shallower || self.reimports_left == 0 { if self.cache_reaches_active(i) { self.depth_hits += 1; - self.report.warn(format!( - "FCPXML cached media {id:?} could form a recursive graph or exceeds the cache traversal budget; imported as a gap" - )); + self.report.warn_limited( + self.report_limit, + format!("FCPXML cached media {id:?} could form a recursive graph or exceeds the cache traversal budget; imported as a gap"), + ); return None; } return Some(i); @@ -397,7 +407,7 @@ impl<'a> Imp<'a, '_, '_> { // would otherwise recurse once per resource. if depth >= MAX_MEDIA_DEPTH { self.depth_hits += 1; - self.report.warn(format!("FCPXML media resource {id:?} is nested too deeply; imported as a gap")); + self.report.warn_limited(self.report_limit, format!("FCPXML media resource {id:?} is nested too deeply; imported as a gap")); return None; } self.media_active.insert(id.into()); @@ -445,7 +455,10 @@ impl<'a> Imp<'a, '_, '_> { fn storyline(&mut self, seq: &mut Sequence, ctx: &Ctx, spine: Node<'a>, origin: Tick, lane: i32, primary: bool) { if self.depth >= MAX_XML_DEPTH { self.depth_hits += 1; - self.report.warn(format!("XML storylines are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped")); + self.report.warn_limited( + self.report_limit, + format!("XML storylines are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped"), + ); return; } self.depth += 1; @@ -471,7 +484,7 @@ impl<'a> Imp<'a, '_, '_> { let vidx = if lane >= 0 { lane as usize } else { usize::MAX }; for (pos, el) in transitions { if vidx == usize::MAX { - self.report.warn("transitions on audio storylines are not supported"); + self.report.warn_limited(self.report_limit, "transitions on audio storylines are not supported"); continue; } let start = origin + attr_time(el, "offset").unwrap_or(Tick::ZERO); @@ -499,7 +512,13 @@ impl<'a> Imp<'a, '_, '_> { } else { TransitionAlign::CenterAtCut }; - let effect = transition_effect(self.b.catalog, &name, false, self.report); + let mut temporary = Report::default(); + let effect = transition_effect(self.b.catalog, &name, false, &mut temporary); + for e in temporary.entries { + for _ in 0..e.count { + self.report.warn_limited(self.report_limit, &e.message); + } + } let id = TransitionId(self.b.alloc()); // The clips may have been moved to another track by placement; find the track holding them. let clip = from.or(to).map(|c| c.0); @@ -525,7 +544,10 @@ impl<'a> Imp<'a, '_, '_> { fn element(&mut self, seq: &mut Sequence, ctx: &Ctx, el: Node<'a>, t0: Tick, lane: i32, primary: bool) -> (Tick, Option) { if self.depth >= MAX_XML_DEPTH { self.depth_hits += 1; - self.report.warn(format!("XML elements are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped")); + self.report.warn_limited( + self.report_limit, + format!("XML elements are nested too deeply (more than {MAX_XML_DEPTH}); deeper clips were skipped"), + ); return (t0, None); } self.depth += 1; @@ -554,7 +576,8 @@ impl<'a> Imp<'a, '_, '_> { .flatten() .filter(|a| a.has_video); if asset.is_none() { - self.report.warn(format!("FCPXML