feat(pdf): hand the finished file across the wasm boundary in blocks

Author: AbianS

.changeset/the-file-crosses-in-blocks.md

@@ -0,0 +1,22 @@
+---
+"@imprentajs/pdf": patch
+---
+
+The finished PDF crosses the wasm boundary in blocks, never as one buffer.
+
+The writer has always produced the file in blocks that are never moved; the
+join that made them contiguous for `imprenta_out_ptr` was the last place the
+engine held a document twice — and linear memory never shrinks, so that peak
+was the footprint (#7). The module now hands over exactly the blocks the
+writer produced, through `imprenta_out_blocks` / `imprenta_out_block_ptr` /
+`imprenta_out_block_len`, and the one contiguous copy is assembled on the JS
+heap, where memory goes back.
+
+`renderToFile` no longer assembles at all: the worker writes block by block,
+so a long document exists whole nowhere but on disk — not in linear memory,
+not in the Node heap. That was the real reason to want this.
+
+The output is byte for byte what it was; the equivalence tests still compare
+bytes and still pass. Measured on a 10,680-page ledger producing a 21.78 MB
+file: **68.0 → 47.2 MB** of linear memory. The saving is the size of the
+file, so it grows with the document.

crates/imprenta-pdf-wasm/src/job.rs

@@ -27,9 +27,15 @@ pub struct ImageInput {
 }
 
 /// What came of a render.
+///
+/// The file stays in the blocks the writer produced — see
+/// [`imprenta_pdf::Pdf`] — and the host reads them one at a time
+/// through `imprenta_out_block_ptr`. Joining them here would put a second
+/// copy of the document in linear memory, which never shrinks, at exactly the
+/// moment the first is at its largest.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Outcome {
-    pub pdf: Vec<u8>,
+    pub pdf: imprenta_pdf::Pdf,
     pub pages: usize,
     pub diagnostics: Vec<String>,
 }

crates/imprenta-pdf-wasm/src/lib.rs

@@ -29,7 +29,8 @@
 //! - Every call returns `1` for success and `0` for failure, and a failure
 //!   leaves a message at [`imprenta_error_ptr`]. Nothing panics across the boundary:
 //!   a malformed document is an error the host can print, not a dead instance.
-//! - The result is read with [`imprenta_out_ptr`]/[`imprenta_out_len`] and given back with
+//! - The result is read block by block with [`imprenta_out_blocks`]/[`imprenta_out_block_ptr`]/
+//!   [`imprenta_out_block_len`] and given back with
 //!   [`imprenta_out_release`], so a long-lived instance does not sit on the last PDF it
 //!   produced. The pointer is only good until the next allocation grows the
 //!   memory, which is why the JavaScript binding copies rather than handing a
@@ -56,7 +57,7 @@ thread_local! {
     };
     /// The finished document, kept until the host has read it or released it.
     static OUT: RefCell<Outcome> = const {
-        RefCell::new(Outcome { pdf: Vec::new(), pages: 0, diagnostics: Vec::new() })
+        RefCell::new(Outcome { pdf: imprenta_pdf::Pdf::empty(), pages: 0, diagnostics: Vec::new() })
     };
     /// The diagnostics, as the JSON array the host reads.
     static DIAGNOSTICS: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
@@ -218,7 +219,7 @@ pub unsafe extern "C" fn imprenta_assets_image(
 
 // ── One document, declared whole ────────────────────────────────────────────
 
-/// Renders a declared document. Read the result with [`imprenta_out_ptr`].
+/// Renders a declared document. Read the result with [`imprenta_out_block_ptr`].
 ///
 /// # Safety
 ///
@@ -251,7 +252,7 @@ pub unsafe extern "C" fn imprenta_render(ir_ptr: *const u8, ir_len: usize) -> i3
 // exists and why it packs rather than estimating.
 
 /// Measures a run of table rows, keeps them, and hands back one height each
-/// as little-endian `f32` readable with [`imprenta_out_ptr`].
+/// as little-endian `f32` readable with [`imprenta_out_block_ptr`].
 ///
 /// Only the heights cross: four bytes a row, against the kilobytes the row
 /// itself weighs. The rows stay here for [`imprenta_fragment_measured`], which
@@ -302,7 +303,8 @@ pub unsafe extern "C" fn imprenta_measure_rows(
             MEASURED.with(|slot| *slot.borrow_mut() = rows);
             OUT.with(|slot| {
                 let mut held = slot.borrow_mut();
-                held.pdf = out;
+                // Already contiguous, so it crosses as one block.
+                held.pdf = out.into();
                 held.pages = count;
                 held.diagnostics = Vec::new();
             });
@@ -445,7 +447,8 @@ pub unsafe extern "C" fn imprenta_plan(
             OUT.with(|slot| {
                 let mut held = slot.borrow_mut();
                 held.pages = json.len();
-                held.pdf = bytes;
+                // Already contiguous, so it crosses as one block.
+                held.pdf = bytes.into();
                 held.diagnostics = Vec::new();
             });
             succeed()
@@ -473,7 +476,7 @@ pub unsafe extern "C" fn imprenta_merge_push(ptr: *const u8, len: usize) -> i32
     succeed()
 }
 
-/// Merges what was pushed and publishes the file at [`imprenta_out_ptr`].
+/// Merges what was pushed and publishes the file at [`imprenta_out_block_ptr`].
 #[unsafe(no_mangle)]
 pub extern "C" fn imprenta_merge_finish() -> i32 {
     let fragments = FRAGMENTS.with(|slot| std::mem::take(&mut *slot.borrow_mut()));
@@ -484,7 +487,7 @@ pub extern "C" fn imprenta_merge_finish() -> i32 {
             // caught here rather than by whoever opens the document.
             let pages = merge::pages_in(&pdf).unwrap_or(0);
             publish(Outcome {
-                pdf,
+                pdf: pdf.into(),
                 pages,
                 diagnostics: Vec::new(),
             })
@@ -563,7 +566,7 @@ pub extern "C" fn imprenta_stream_pending() -> usize {
     PRINTER.with(|slot| slot.borrow().as_ref().map_or(0, Printer::pending))
 }
 
-/// Paints what is left and closes the document. Read it with [`imprenta_out_ptr`].
+/// Paints what is left and closes the document. Read it with [`imprenta_out_block_ptr`].
 #[unsafe(no_mangle)]
 pub extern "C" fn imprenta_stream_finish() -> i32 {
     let printer = PRINTER.with(|slot| slot.borrow_mut().take());
@@ -578,14 +581,35 @@ pub extern "C" fn imprenta_stream_finish() -> i32 {
 
 // ── Reading the result ──────────────────────────────────────────────────────
 
+/// How many pieces the result is in. Read them with
+/// [`imprenta_out_block_ptr`] and [`imprenta_out_block_len`]; concatenated in
+/// order they are the file.
+///
+/// Blocks rather than one buffer, deliberately: handing back a contiguous
+/// result meant joining the writer's blocks inside linear memory, which held
+/// two copies of the finished document at the peak — and linear memory never
+/// shrinks, so the peak was the footprint (issue #7). The host assembles the
+/// copy on its own heap, where the memory goes back.
+#[unsafe(no_mangle)]
+pub extern "C" fn imprenta_out_blocks() -> usize {
+    OUT.with(|slot| slot.borrow().pdf.block_count())
+}
+
+/// Where the `index`-th piece starts. Null past the end, never a trap.
 #[unsafe(no_mangle)]
-pub extern "C" fn imprenta_out_ptr() -> *const u8 {
-    OUT.with(|slot| slot.borrow().pdf.as_ptr())
+pub extern "C" fn imprenta_out_block_ptr(index: usize) -> *const u8 {
+    OUT.with(|slot| {
+        slot.borrow()
+            .pdf
+            .block(index)
+            .map_or(std::ptr::null(), <[u8]>::as_ptr)
+    })
 }
 
+/// How long the `index`-th piece is. Zero past the end.
 #[unsafe(no_mangle)]
-pub extern "C" fn imprenta_out_len() -> usize {
-    OUT.with(|slot| slot.borrow().pdf.len())
+pub extern "C" fn imprenta_out_block_len(index: usize) -> usize {
+    OUT.with(|slot| slot.borrow().pdf.block(index).map_or(0, <[u8]>::len))
 }
 
 #[unsafe(no_mangle)]
@@ -625,7 +649,7 @@ pub extern "C" fn imprenta_error_len() -> usize {
 pub extern "C" fn imprenta_out_release() -> i32 {
     OUT.with(|slot| {
         let mut out = slot.borrow_mut();
-        out.pdf = Vec::new();
+        out.pdf = imprenta_pdf::Pdf::empty();
         out.pages = 0;
         out.diagnostics = Vec::new();
     });
@@ -669,8 +693,25 @@ mod tests {
         give_back(data);
     }
 
+    /// The result as the host assembles it: the blocks, in order.
     fn read_out() -> Vec<u8> {
-        unsafe { std::slice::from_raw_parts(imprenta_out_ptr(), imprenta_out_len()) }.to_vec()
+        let mut out = Vec::with_capacity(out_len());
+        for index in 0..imprenta_out_blocks() {
+            out.extend_from_slice(unsafe {
+                std::slice::from_raw_parts(
+                    imprenta_out_block_ptr(index),
+                    imprenta_out_block_len(index),
+                )
+            });
+        }
+        out
+    }
+
+    /// The total the blocks add up to, which is what `out_len` used to say.
+    fn out_len() -> usize {
+        (0..imprenta_out_blocks())
+            .map(|index| imprenta_out_block_len(index))
+            .sum()
     }
 
     fn read_error() -> String {
@@ -815,17 +856,36 @@ mod tests {
         give_back(ir);
     }
 
+    #[test]
+    fn a_block_index_past_the_end_is_null_and_zero_rather_than_a_trap() {
+        // The index arrives over the boundary, where a panic kills the
+        // instance. A host that miscounts must get an answer it can check.
+        let _lock = guard();
+        load_roman();
+        let ir = put(HELLO);
+        unsafe { imprenta_render(ir.0, ir.1) };
+        let count = imprenta_out_blocks();
+
+        assert!(count >= 1);
+        assert!(imprenta_out_block_ptr(count).is_null());
+        assert_eq!(imprenta_out_block_len(count), 0);
+
+        imprenta_out_release();
+        give_back(ir);
+    }
+
     #[test]
     fn releasing_the_result_gives_the_bytes_back() {
         let _lock = guard();
         load_roman();
         let ir = put(HELLO);
         unsafe { imprenta_render(ir.0, ir.1) };
-        assert!(imprenta_out_len() > 0);
+        assert!(out_len() > 0);
 
         imprenta_out_release();
 
-        assert_eq!(imprenta_out_len(), 0);
+        assert_eq!(out_len(), 0);
+        assert_eq!(imprenta_out_blocks(), 0);
         assert_eq!(imprenta_out_pages(), 0);
         assert_eq!(imprenta_diagnostics_len(), 0);
         give_back(ir);

crates/imprenta-pdf-wasm/src/merge.rs

@@ -186,7 +186,7 @@ mod tests {
             r#"{{"page":{{"width":595,"height":842}},"children":[{{"t":"table","columns":[{{"width":{{"unit":"percent","value":0.6}}}},{{"width":{{"unit":"percent","value":0.4}}}}],"rows":[{}]}}]}}"#,
             rows.join(",")
         );
-        run(ir.as_bytes(), &roman()).unwrap().pdf
+        run(ir.as_bytes(), &roman()).unwrap().pdf.into_vec()
     }
 
     fn pages_of(pdf: &[u8]) -> usize {

crates/imprenta-pdf-write/src/blocks.rs

@@ -30,19 +30,45 @@ const CEILING: usize = 4 * 1024 * 1024;
 /// The first block, and the smallest anything costs.
 const FLOOR: usize = 8 * 1024;
 
-#[derive(Default)]
+#[derive(Default, Clone)]
 pub(crate) struct Blocks {
     blocks: Vec<Vec<u8>>,
     len: usize,
 }
 
 impl Blocks {
+    /// Nothing written. `const` so a thread-local on the far side of the wasm
+    /// boundary can start with one without a lazy initialiser.
+    pub const fn empty() -> Self {
+        Self {
+            blocks: Vec::new(),
+            len: 0,
+        }
+    }
+
     /// How many bytes have been written in all. This is the offset the next
     /// object will start at, which is what an xref entry records.
     pub fn len(&self) -> usize {
         self.len
     }
 
+    /// How many pieces the file is in.
+    pub fn count(&self) -> usize {
+        self.blocks.len()
+    }
+
+    /// One piece, by position. `None` past the end rather than a panic,
+    /// because the index arrives over the wasm boundary where a panic is a
+    /// trap that takes the instance with it.
+    pub fn get(&self, index: usize) -> Option<&[u8]> {
+        self.blocks.get(index).map(Vec::as_slice)
+    }
+
+    /// The pieces in file order. Concatenated, they are the file.
+    pub fn iter(&self) -> impl Iterator<Item = &[u8]> {
+        self.blocks.iter().map(Vec::as_slice)
+    }
+
     pub fn push(&mut self, bytes: &[u8]) {
         let mut rest = bytes;
         while !rest.is_empty() {

crates/imprenta-pdf-write/src/lib.rs

@@ -43,9 +43,11 @@
 mod blocks;
 mod font;
 mod image;
+mod pdf;
 
 use blocks::Blocks;
 use imprenta_core::color::Color;
+pub use pdf::Pdf;
 use pdf_writer::{Chunk, Content, Finish, Name, Rect, Ref, Str};
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -225,7 +227,12 @@ impl Writer {
 
     /// Writes the fonts, the images, the page tree and the catalogue, then
     /// the cross-reference table.
-    pub fn finish(mut self) -> Result<Vec<u8>, WriteError> {
+    ///
+    /// What comes back is the file still in its blocks — see [`Pdf`]. A
+    /// caller that wants one buffer dereferences or calls
+    /// [`Pdf::into_vec`]; the wasm boundary and a file sink take the blocks
+    /// as they lie and never pay for the join.
+    pub fn finish(mut self) -> Result<Pdf, WriteError> {
         if self.page_refs.is_empty() {
             return Err(WriteError::NoPages);
         }
@@ -304,7 +311,7 @@ impl Writer {
     ///
     /// Written by hand because everything above it has been: the offsets are
     /// this writer's own, and a table entry is twenty bytes.
-    fn trailer(mut self, catalog: Ref) -> Vec<u8> {
+    fn trailer(mut self, catalog: Ref) -> Pdf {
         self.offsets.sort_unstable();
         let size = 1 + self.offsets.last().map_or(0, |(id, _)| *id);
         let start = self.blocks.len();
@@ -329,7 +336,10 @@ impl Writer {
         ));
         self.blocks.push(table.as_bytes());
 
-        self.blocks.into_vec()
+        // Not joined here, deliberately. This was the last place the engine
+        // held a document twice, and inside a WebAssembly module that peak is
+        // permanent; whoever needs the file contiguous pays for it there.
+        Pdf::from_blocks(self.blocks)
     }
 }