imprimatur 0.1.0

data/ext/imprimatur_native/core/src/pdf/objects.rs

@@ -0,0 +1,141 @@
+//! PDF file syntax: numbered objects, compressed streams, the
+//! cross-reference table and the trailer (ISO 32000-1, section 7).
+
+use std::fmt;
+use std::io::Write;
+
+use crate::{Error, Result};
+
+/// The header, with the binary comment that marks the file as binary.
+const HEADER: &[u8] = b"%PDF-1.7\n%\xE2\xE3\xCF\xD3\n";
+/// zlib's default trade-off between size and speed.
+const LEVEL: u8 = 6;
+/// The largest offset a cross-reference entry's ten digits hold.
+const MAX_OFFSET: usize = 9_999_999_999;
+
+/// Streams a PDF into `out`; objects are numbered from 1 in the order
+/// written, and only their offsets are kept for the cross-reference table.
+pub struct PdfWriter<W: Write> {
+    out: W,
+    written: usize,
+    offsets: Vec<usize>,
+}
+
+impl<W: Write> PdfWriter<W> {
+    pub fn new(out: W) -> Result<Self> {
+        let mut writer = Self { out, written: 0, offsets: Vec::new() };
+        writer.write(HEADER)?;
+        Ok(writer)
+    }
+
+    /// Writes `id 0 obj <dictionary> endobj`; ids must come in order.
+    pub fn object(&mut self, id: usize, dictionary: fmt::Arguments<'_>) -> Result<()> {
+        self.begin(id)?;
+        self.write_fmt(format_args!("{dictionary}\nendobj\n"))
+    }
+
+    /// Writes a Flate-compressed stream object.
+    pub fn stream(&mut self, id: usize, data: &[u8]) -> Result<()> {
+        let compressed = miniz_oxide::deflate::compress_to_vec_zlib(data, LEVEL);
+        self.begin(id)?;
+        let length = compressed.len();
+        self.write_fmt(format_args!("<< /Length {length} /Filter /FlateDecode >>\nstream\n"))?;
+        self.write(&compressed)?;
+        self.write(b"\nendstream\nendobj\n")
+    }
+
+    /// Writes the cross-reference table and the trailer; returns `out`.
+    pub fn finish(mut self, root: usize, info: usize) -> Result<W> {
+        let xref = self.written;
+        let size = self.offsets.len() + 1;
+        self.write_fmt(format_args!("xref\n0 {size}\n0000000000 65535 f \n"))?;
+        for index in 0..self.offsets.len() {
+            let offset = self.offsets[index];
+            (offset <= MAX_OFFSET).ok_or(Error::ArchiveTooLarge("PDF over 10 GB"))?;
+            self.write_fmt(format_args!("{offset:010} 00000 n \n"))?;
+        }
+        self.write_fmt(format_args!(
+            "trailer\n<< /Size {size} /Root {root} 0 R /Info {info} 0 R >>\n\
+             startxref\n{xref}\n%%EOF\n"
+        ))?;
+        self.out.flush()?;
+        Ok(self.out)
+    }
+
+    fn begin(&mut self, id: usize) -> Result<()> {
+        debug_assert_eq!(id, self.offsets.len() + 1, "PDF objects are written in id order");
+        self.offsets.push(self.written);
+        self.write_fmt(format_args!("{id} 0 obj\n"))
+    }
+
+    fn write(&mut self, bytes: &[u8]) -> Result<()> {
+        self.out.write_all(bytes)?;
+        self.written += bytes.len();
+        Ok(())
+    }
+
+    /// Formats straight into `out`, counting what it writes.
+    fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> Result<()> {
+        let mut counted = Counted { out: &mut self.out, written: 0 };
+        counted.write_fmt(args)?;
+        self.written += counted.written;
+        Ok(())
+    }
+}
+
+/// A writer that counts the bytes passing through it.
+struct Counted<'a, W: Write> {
+    out: &'a mut W,
+    written: usize,
+}
+
+impl<W: Write> Write for Counted<'_, W> {
+    fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+        let written = self.out.write(bytes)?;
+        self.written += written;
+        Ok(written)
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        self.out.flush()
+    }
+}
+
+/// A number for a content stream: two decimals at most, no trailing zeros,
+/// formatted without an intermediate `String`.
+#[derive(Clone, Copy)]
+pub struct Num(pub f64);
+
+impl fmt::Display for Num {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        #[expect(
+            clippy::cast_possible_truncation,
+            reason = "page coordinates are far inside i64 hundredths"
+        )]
+        let hundredths = (self.0 * 100.0).round() as i64;
+        if hundredths < 0 {
+            f.write_str("-")?;
+        }
+        let (whole, fraction) = (hundredths.unsigned_abs() / 100, hundredths.unsigned_abs() % 100);
+        match fraction {
+            0 => write!(f, "{whole}"),
+            tenths if tenths % 10 == 0 => write!(f, "{whole}.{}", tenths / 10),
+            fraction => write!(f, "{whole}.{fraction:02}"),
+        }
+    }
+}
+
+/// Appends a literal string `( ... )`, escaped.
+pub fn push_string(out: &mut Vec<u8>, bytes: &[u8]) {
+    out.reserve(bytes.len() + 2);
+    out.push(b'(');
+    for &byte in bytes {
+        match byte {
+            b'(' | b')' | b'\\' => out.extend_from_slice(&[b'\\', byte]),
+            // A bare CR inside a string reads back as LF.
+            b'\r' => out.extend_from_slice(b"\\r"),
+            _ => out.push(byte),
+        }
+    }
+    out.push(b')');
+}

data/ext/imprimatur_native/core/src/pdf.rs

@@ -0,0 +1,84 @@
+//! PDF output: the document laid out with the standard Helvetica fonts
+//! (`WinAnsiEncoding`, so Windows-1252 text), written with our own object
+//! writer. Embedded TrueType fonts, and with them every other script, come next.
+
+mod font;
+mod layout;
+#[rustfmt::skip]
+pub mod metrics;
+mod objects;
+#[cfg(test)]
+mod tests;
+
+use std::fmt;
+use std::io::Write;
+
+use crate::Result;
+use crate::doc::{Block, Document};
+use font::Face;
+use layout::Layout;
+use objects::{Num, PdfWriter};
+
+const CATALOG: usize = 1;
+const PAGES: usize = 2;
+/// Fonts are objects 3 to 6, in [`Face::ALL`] order; the info dictionary follows.
+const FIRST_FONT: usize = 3;
+const INFO: usize = FIRST_FONT + Face::ALL.len();
+
+pub fn write<W: Write>(document: &Document, out: W) -> Result<W> {
+    let mut layout = Layout::new(document.page_size());
+    for block in document.blocks() {
+        match block {
+            Block::Heading { level, text } => layout.heading(*level, text)?,
+            Block::Paragraph(paragraph) => layout.paragraph(paragraph)?,
+            Block::Table(table) => layout.table(table)?,
+            Block::PageBreak => layout.page_break(),
+        }
+    }
+    let (width, height) = layout.page_size();
+    let pages = layout.finish(document.has_page_numbers());
+
+    let mut pdf = PdfWriter::new(out)?;
+    // Each page is a page object followed by its content stream.
+    let page_id = |index: usize| INFO + 1 + 2 * index;
+    pdf.object(CATALOG, format_args!("<< /Type /Catalog /Pages {PAGES} 0 R >>"))?;
+    let kids = fmt::from_fn(|f| {
+        for index in 0..pages.len() {
+            write!(f, "{} 0 R ", page_id(index))?;
+        }
+        Ok(())
+    });
+    let count = pages.len();
+    pdf.object(PAGES, format_args!("<< /Type /Pages /Kids [{kids}] /Count {count} >>"))?;
+    for (id, face) in (FIRST_FONT..).zip(Face::ALL) {
+        let name = face.metrics().name;
+        pdf.object(
+            id,
+            format_args!(
+                "<< /Type /Font /Subtype /Type1 /BaseFont /{name} /Encoding /WinAnsiEncoding >>"
+            ),
+        )?;
+    }
+    pdf.object(INFO, format_args!("<< /Producer (imprimatur) >>"))?;
+
+    let fonts = fmt::from_fn(|f| {
+        for (id, face) in (FIRST_FONT..).zip(Face::ALL) {
+            write!(f, "/{} {id} 0 R ", face.resource())?;
+        }
+        Ok(())
+    });
+    let (width, height) = (Num(width), Num(height));
+    for (index, content) in pages.iter().enumerate() {
+        let id = page_id(index);
+        pdf.object(
+            id,
+            format_args!(
+                "<< /Type /Page /Parent {PAGES} 0 R /MediaBox [0 0 {width} {height}] \
+                 /Resources << /Font << {fonts}>> >> /Contents {} 0 R >>",
+                id + 1
+            ),
+        )?;
+        pdf.stream(id + 1, content)?;
+    }
+    pdf.finish(CATALOG, INFO)
+}

data/ext/imprimatur_native/core/src/read/budget.rs

@@ -0,0 +1,140 @@
+//! The limits a read runs under, and the running tally against them.
+
+use std::cell::Cell;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+
+use crate::{Error, Result};
+
+const MIB: u64 = 1024 * 1024;
+/// Time and cancellation are checked once per this many ticks.
+const TICKS_PER_CHECK: u32 = 4096;
+
+/// What a read may consume. Documents are untrusted input: a zip bomb, a
+/// PDF whose objects refer to each other forever, or a part nested a
+/// million deep must fail fast, not take the process down.
+///
+/// ```
+/// use std::time::Duration;
+/// use imprimatur::read::Limits;
+///
+/// let limits = Limits::default().max_inflated(64 * 1024 * 1024).timeout(Some(Duration::from_secs(5)));
+/// ```
+#[derive(Debug, Clone)]
+pub struct Limits {
+    max_input: usize,
+    max_inflated: u64,
+    max_depth: usize,
+    timeout: Option<Duration>,
+    cancel: Option<Arc<AtomicBool>>,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self {
+            max_input: 512 * 1024 * 1024,
+            max_inflated: 1024 * MIB,
+            max_depth: 256,
+            timeout: Some(Duration::from_mins(1)),
+            cancel: None,
+        }
+    }
+}
+
+impl Limits {
+    /// The largest document accepted, in bytes; 512 MiB by default.
+    #[must_use]
+    pub const fn max_input(mut self, bytes: usize) -> Self {
+        self.max_input = bytes;
+        self
+    }
+
+    /// The most bytes decompression may produce in total, across zip
+    /// entries and PDF streams; 1 GiB by default.
+    #[must_use]
+    pub const fn max_inflated(mut self, bytes: u64) -> Self {
+        self.max_inflated = bytes;
+        self
+    }
+
+    /// How deep XML elements, PDF objects and nested PDF forms may go; 256
+    /// by default.
+    #[must_use]
+    pub const fn max_depth(mut self, depth: usize) -> Self {
+        self.max_depth = depth;
+        self
+    }
+
+    /// Wall-clock time a read may take, one minute by default; `None` for none.
+    #[must_use]
+    pub const fn timeout(mut self, timeout: Option<Duration>) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    /// A flag another thread sets to stop the read with [`Error::Cancelled`].
+    #[must_use]
+    pub fn cancel_on(mut self, flag: Arc<AtomicBool>) -> Self {
+        self.cancel = Some(flag);
+        self
+    }
+}
+
+/// One read's consumption. Single-threaded: a read runs on one thread.
+pub struct Budget<'a> {
+    limits: &'a Limits,
+    deadline: Option<Instant>,
+    inflated: Cell<u64>,
+    ticks: Cell<u32>,
+}
+
+impl<'a> Budget<'a> {
+    pub fn new(limits: &'a Limits, input: usize) -> Result<Self> {
+        (input <= limits.max_input).ok_or(Error::LimitExceeded("input size"))?;
+        let deadline = limits.timeout.map(|timeout| Instant::now() + timeout);
+        Ok(Self { limits, deadline, inflated: Cell::new(0), ticks: Cell::new(0) })
+    }
+
+    pub const fn max_depth(&self) -> usize {
+        self.limits.max_depth
+    }
+
+    /// Decompressed bytes still allowed.
+    pub fn inflatable(&self) -> usize {
+        let left = self.limits.max_inflated.saturating_sub(self.inflated.get());
+        usize::try_from(left).unwrap_or(usize::MAX)
+    }
+
+    /// Records `bytes` more of decompressed output.
+    pub fn inflate(&self, bytes: usize) -> Result<()> {
+        let total = self.inflated.get().saturating_add(u64::try_from(bytes).unwrap_or(u64::MAX));
+        (total <= self.limits.max_inflated).ok_or(Error::LimitExceeded("decompressed size"))?;
+        self.inflated.set(total);
+        Ok(())
+    }
+
+    /// Counts one unit of work; every few thousand, checks the clock and
+    /// the cancel flag.
+    pub fn tick(&self) -> Result<()> {
+        let ticks = self.ticks.get().wrapping_add(1);
+        self.ticks.set(ticks);
+        if ticks.is_multiple_of(TICKS_PER_CHECK) { self.check() } else { Ok(()) }
+    }
+
+    /// Checks the clock and the cancel flag now.
+    pub fn check(&self) -> Result<()> {
+        if self.limits.cancel.as_deref().is_some_and(|flag| flag.load(Ordering::Relaxed)) {
+            return Err(Error::Cancelled);
+        }
+        if self.deadline.is_some_and(|deadline| Instant::now() >= deadline) {
+            return Err(Error::LimitExceeded("time"));
+        }
+        Ok(())
+    }
+
+    /// Fails beyond the depth limit.
+    pub fn nest(&self, depth: usize) -> Result<()> {
+        (depth <= self.limits.max_depth).ok_or(Error::LimitExceeded("nesting depth"))
+    }
+}

data/ext/imprimatur_native/core/src/read/content.rs

@@ -0,0 +1,266 @@
+//! What a read finds, before it is printed: pages of blocks for a PDF,
+//! sheets of cells for a workbook, blocks for a Word document. Markdown is
+//! one rendering of it ([`Content::to_markdown`]); search and JSON output
+//! work on it directly.
+
+#[cfg(test)]
+mod tests;
+
+use std::ops::Range;
+use std::sync::Arc;
+
+use super::span;
+use crate::xlsx::push_cell_reference;
+use crate::xlsx::{DateTime, cell_reference};
+
+/// A document's content, by format.
+#[derive(Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum Content {
+    Pdf(Vec<Page>),
+    Xlsx(Vec<Sheet>),
+    Docx(Vec<Block>),
+}
+
+impl Content {
+    /// The document's format.
+    #[must_use]
+    pub const fn format(&self) -> super::Format {
+        match self {
+            Self::Pdf(_) => super::Format::Pdf,
+            Self::Xlsx(_) => super::Format::Xlsx,
+            Self::Docx(_) => super::Format::Docx,
+        }
+    }
+}
+
+/// A PDF page: its blocks in reading order, and how many images it draws.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Page {
+    /// From 1.
+    pub number: u32,
+    pub blocks: Vec<Placed>,
+    pub images: u32,
+}
+
+/// A block and where it lies on its page.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Placed {
+    pub block: Block,
+    /// `None` for text that does not run left to right across the page.
+    pub bounds: Option<Bounds>,
+}
+
+/// A rectangle in points from the top-left corner of the page as shown
+/// (its rotation applied).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Bounds {
+    pub left: f64,
+    pub top: f64,
+    pub right: f64,
+    pub bottom: f64,
+}
+
+/// A unit of a document's flow.
+#[derive(Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum Block {
+    /// Level 1 is the largest.
+    Heading {
+        level: u8,
+        text: Text,
+    },
+    /// Its lines separated by `\n`.
+    Paragraph {
+        text: Text,
+    },
+    /// `level` 0 is the outermost list.
+    ListItem {
+        level: u8,
+        ordered: bool,
+        text: Text,
+    },
+    Table(Grid),
+}
+
+impl Block {
+    /// The block's text: a table's cells, each on a line.
+    #[must_use]
+    pub fn plain_text(&self) -> std::borrow::Cow<'_, str> {
+        match self {
+            Self::Heading { text, .. } | Self::Paragraph { text } | Self::ListItem { text, .. } => {
+                std::borrow::Cow::Borrowed(&text.text)
+            }
+            Self::Table(grid) => {
+                let mut joined = String::new();
+                for cell in grid.cells() {
+                    if !joined.is_empty() {
+                        joined.push('\n');
+                    }
+                    joined.push_str(grid.text(cell));
+                }
+                std::borrow::Cow::Owned(joined)
+            }
+        }
+    }
+}
+
+/// Text, and the stretches of it that are styled.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Text {
+    pub text: String,
+    /// Byte ranges of `text`, in order and apart. Readers leave whitespace
+    /// at a stretch's edges out of it.
+    pub marks: Vec<Mark>,
+}
+
+impl Text {
+    pub fn plain(text: impl Into<String>) -> Self {
+        Self { text: text.into(), marks: Vec::new() }
+    }
+}
+
+/// A styled stretch of text.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Mark {
+    pub range: Range<usize>,
+    pub bold: bool,
+    pub italic: bool,
+    pub link: Option<String>,
+}
+
+/// A workbook sheet: its cells, then its comments.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Sheet {
+    pub name: String,
+    pub hidden: bool,
+    pub cells: Grid,
+    pub comments: Vec<Note>,
+}
+
+/// A comment on a cell.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Note {
+    /// The cell's position, from 0.
+    pub row: u32,
+    pub column: u32,
+    /// Shared by the notes of one author.
+    pub author: Option<Arc<str>>,
+    pub text: String,
+}
+
+impl Note {
+    /// The cell's A1 reference: `B2`.
+    #[must_use]
+    pub fn reference(&self) -> String {
+        reference(self.row, self.column)
+    }
+}
+
+/// Appends the A1 reference of a sheet's cell to `out`.
+pub fn push_reference(out: &mut String, row: u32, column: u32) {
+    push_cell_reference(out, row, u16::try_from(column).unwrap_or(u16::MAX));
+}
+
+fn reference(row: u32, column: u32) -> String {
+    cell_reference(row, u16::try_from(column).unwrap_or(u16::MAX))
+}
+
+/// What a cell holds. Its text, as shown, is the grid's
+/// ([`Grid::text`]); the variants carry what the text does not.
+#[derive(Debug, Clone, Copy, PartialEq)]
+#[non_exhaustive]
+pub enum Value {
+    Text,
+    Number(f64),
+    Bool(bool),
+    /// A number formatted as a date or a date and time.
+    Date(DateTime),
+    /// An error such as `#N/A`.
+    Error,
+    /// A formula without a computed value: its text is `=FORMULA`.
+    Formula,
+}
+
+/// A cell of a grid: its position, from 0, and its value.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Cell {
+    pub row: u32,
+    pub column: u32,
+    pub value: Value,
+    text: Range<u32>,
+}
+
+impl Cell {
+    /// The cell's A1 reference, which names it in a sheet: `B2`.
+    #[must_use]
+    pub fn reference(&self) -> String {
+        reference(self.row, self.column)
+    }
+}
+
+/// Cells by row and column, sparse and in row-major order. Their text
+/// shares one buffer.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Grid {
+    text: String,
+    cells: Vec<Cell>,
+    open: usize,
+}
+
+impl Grid {
+    #[must_use]
+    pub fn cells(&self) -> &[Cell] {
+        &self.cells
+    }
+
+    /// The text of a cell of this grid, as shown.
+    #[must_use]
+    pub fn text(&self, cell: &Cell) -> &str {
+        span::slice(&self.text, &cell.text)
+    }
+
+    /// The cells row by row; rows without cells are left out.
+    pub fn rows(&self) -> impl Iterator<Item = &[Cell]> {
+        self.cells.chunk_by(|a, b| a.row == b.row)
+    }
+
+    #[must_use]
+    pub const fn is_empty(&self) -> bool {
+        self.cells.is_empty()
+    }
+
+    /// The buffer to write the next cell's text into, then
+    /// [`end_cell`](Self::end_cell) it.
+    pub(crate) const fn buffer(&mut self) -> &mut String {
+        self.open = self.text.len();
+        &mut self.text
+    }
+
+    /// Ends the cell written since [`buffer`](Self::buffer); a cell with no
+    /// text is dropped.
+    pub(crate) fn end_cell(&mut self, row: u32, column: u32, value: Value) {
+        if self.text[self.open..].trim().is_empty() {
+            self.text.truncate(self.open);
+        } else {
+            let text = span::end(&self.text[..self.open])..span::end(&self.text);
+            self.cells.push(Cell { row, column, value, text });
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn push(&mut self, row: u32, column: u32, text: &str) {
+        self.buffer().push_str(text);
+        self.end_cell(row, column, Value::Text);
+    }
+
+    /// Sorts cells written out of order; of two at one position, the first
+    /// written stays.
+    pub(crate) fn finish(mut self) -> Self {
+        if !self.cells.is_sorted_by_key(|cell| (cell.row, cell.column)) {
+            self.cells.sort_by_key(|cell| (cell.row, cell.column));
+        }
+        self.cells.dedup_by_key(|cell| (cell.row, cell.column));
+        self
+    }
+}