diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.logos.sha256 index 2eb22f3b..7e4b6c46 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.logos.sha256 @@ -1 +1 @@ -2d75e1791c025472dcf90a0df7fd0c4ece5d85456b5d25e8be70d5e4e5786e86 +2b9a359c078f5fa1b623ee4db45407209b662909044a6a9f6d02eef4d103d72e diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.nologos.sha256 index 3bf1bf0c..19df2bde 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.demo.en.nologos.sha256 @@ -1 +1 @@ -b534afb3a7b40b2c04dbc55b9909835a15324f5b1c49069eee28f061a6f07712 +3d76027dc76f799c3a9cb3e9ac5d082a27e58b2ef1e631e2003ba9fee6903b6b diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.logos.sha256 index 14ffbb82..5248fa00 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.logos.sha256 @@ -1 +1 @@ -ce9bdaab621d510e0e7d307f67f410bac1a5b69a65cb74cd289ff4a6b149e820 +52999af79a82a426ed76e6268388dd641e7eb233f826dab6f87d47c5ecc267ca diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.nologos.sha256 index 2e4adb7a..78de66b2 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.nologos.sha256 @@ -1 +1 @@ -e6ed5ce14bf4338c0f161c51900443747bb033403ea4164f96e13d0810abf881 +e8ee3238a5c4df10c8564c67148abcdb7b2d282b5f7de3ee5dffbc72ff662247 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.real.v2full-obs1.fr.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.real.v2full-obs1.fr.logos.sha256 index 188d02af..4b6b60f5 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.real.v2full-obs1.fr.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.real.v2full-obs1.fr.logos.sha256 @@ -1 +1 @@ -5f98fb659c7d587cf3921d5b9871e7dd10a2a8148003d1063f74d7a1951e37c4 +287f608e77d0d41b15494e72db8415292058f8e65e0e61c4201c76b106763ba3 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.store-path.fr.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.store-path.fr.nologos.sha256 index 64e59139..e8636839 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.store-path.fr.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.store-path.fr.nologos.sha256 @@ -1 +1 @@ -1faf76663e834c5297c2244310a7366d508010d146ba789d4e24016e0959771d +54a0472c39791c1b5426bf17dbf824ba3079acde66f3062b43643163cc869841 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.logos.sha256 index fc6a9949..f8df71e6 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.logos.sha256 @@ -1 +1 @@ -2321f77c211656a41f870584a31d9c44c00868ab420f68428194b254e4c166cd +8ff84417d542cd200b5364844f382a21f19392284f0f7a61040e7e7269fc32dc diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.nologos.sha256 index 6cf66af6..8c1bb760 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.en.nologos.sha256 @@ -1 +1 @@ -781868dbd08050b8191fb727a1b553348c2992c80aff5693fa7781abebc58e2e +6fe8ee50a6c6bda2eab48412f607181b23098cff7132747f623637cb9975c0a0 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.logos.sha256 index 7ed936cd..d991d503 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.logos.sha256 @@ -1 +1 @@ -48503857cab7ba4a27bdc1fec834f77cb1a88f4f9262d1f28f0c262f6ffa7667 +58adc70d9de66848bd84a932edce590e1e151444ec063122a5b4eb67343b16f8 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.nologos.sha256 index 2ca48983..f3715c5e 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2full.fr.nologos.sha256 @@ -1 +1 @@ -bb88a9cebd07a66c669b7fbf656275f003ce327972523cb369494fdfd1abe6c3 +b65b6289ee4c5252a32172b97241af253be73d8030dd92d090e18f9ca88b1d80 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.logos.sha256 index 44e3a7c1..da9fcc95 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.logos.sha256 @@ -1 +1 @@ -14dc9f70873b23ec53ad0081a33942c029298879d14b761c4b53190298e1cb81 +138c6ca5c9513b5e03b2db76e6b085a0b1fe35a3afedb21f4fd5762049d2b82a diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.nologos.sha256 index c618ec19..ecc413c4 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.en.nologos.sha256 @@ -1 +1 @@ -5b96a835158b9783c84d2c71457da32a79102202c1956ce958610d6b54304b58 +b842ceafdefacea26b376ab443b3c6b69a9466e853e640b3138f7f788ff781a5 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.logos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.logos.sha256 index 1465777d..bfcc2785 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.logos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.logos.sha256 @@ -1 +1 @@ -82c3e716e275bc3930249f8f7363ea135efe8f35f8deeffd090d9de1ca6dbb6b +0cf6d48786c388b1c1d2d48b2e78f854f92af378f22dcd2dcbafdb2650b676a3 diff --git a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.nologos.sha256 b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.nologos.sha256 index 46da1594..21731205 100644 --- a/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.nologos.sha256 +++ b/apps/app/tests/fixtures/goldens/r4/pdf.v2unresolved.fr.nologos.sha256 @@ -1 +1 @@ -300d514382483b9cf485a02643d6fd95bfc4dc5e515386ccd8e07a4edbb149a9 +59569ab96f4a022bd70a2a1d260bda13daedb810f80744afc6b719b9f5a3f6d3 diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml index 790deeb1..aa3a86d7 100644 --- a/crates/core/Cargo.toml +++ b/crates/core/Cargo.toml @@ -80,5 +80,9 @@ required-features = ["pdf-read", "pdf-write"] name = "pdf_serialize" required-features = ["pdf-read", "pdf-write"] +[[test]] +name = "pdf_session" +required-features = ["pdf-read", "pdf-write"] + [lints] workspace = true diff --git a/crates/core/src/facade.rs b/crates/core/src/facade.rs index f33d1670..3317a9bf 100644 --- a/crates/core/src/facade.rs +++ b/crates/core/src/facade.rs @@ -103,6 +103,74 @@ pub fn restore_copy(sheet: &LoadedSheet, bytes: Vec) -> String { render(outcome) } +/// The export session behind the wasm facade (R4.6, plan §B.1.4): the same envelopes as +/// the calls, the session's closed kinds (`unknown_key`, `duplicate_key`, `out_of_order`) +/// and the export's (`ExportErrorKind`). +#[cfg(feature = "pdf-write")] +pub mod export { + use super::{Failure, parse_input, render, to_value}; + use crate::pdf::write::input::{ExportError, ExportInput}; + use crate::pdf::write::session::{ExportSession, SessionError}; + + fn export_failure(error: ExportError) -> Failure { + Failure::new(error.kind.as_str(), error.detail) + } + + fn session_failure(error: SessionError) -> Failure { + match error { + SessionError::Refused(refusal) => Failure::new(refusal.as_str(), ""), + SessionError::Export(error) => export_failure(error), + } + } + + /// Opens a session on the `ExportInput` JSON; the failure names today's export kinds, + /// or `invalid_shape` / `invalid_json` / `lone_surrogate` for a text that is not one. + pub fn open(input: &str) -> Result { + let input: ExportInput = parse_input(input)?; + ExportSession::new(input).map_err(export_failure) + } + + /// `next()`: the `ExportStep` as the value. + pub fn next_step(session: &mut ExportSession) -> String { + render( + session + .next_step() + .map_err(session_failure) + .and_then(|step| to_value(&step)), + ) + } + + pub fn add_raster(session: &mut ExportSession, key: &str, png: &[u8]) -> String { + render( + session + .add_raster(key, png) + .map(|()| serde_json::Value::Null) + .map_err(session_failure), + ) + } + + pub fn raster_failed(session: &mut ExportSession, key: &str) -> String { + render( + session + .raster_failed(key) + .map(|()| serde_json::Value::Null) + .map_err(session_failure), + ) + } + + /// `finish()`: the number of parts the file comes in, or the failure (`out_of_order`, + /// `self_check_failed`, …). + pub fn finish(session: &mut ExportSession) -> Result { + session.finish().map_err(session_failure)?; + Ok(session.parts_left()) + } + + /// The warnings so far, as a JSON array (`ExportWarning`). + pub fn warnings(session: &ExportSession) -> String { + render(to_value(&session.warnings())) + } +} + fn unknown(op: &str) -> Failure { Failure::new("unknown_op", format!("no operation named {op}")) } diff --git a/crates/core/src/pdf/write/draw_log.rs b/crates/core/src/pdf/write/draw_log.rs index 542bddec..c7b0c0d6 100644 --- a/crates/core/src/pdf/write/draw_log.rs +++ b/crates/core/src/pdf/write/draw_log.rs @@ -1,6 +1,7 @@ //! The draw log (R4.4): every drawing call the TypeScript engine made through pdf-lib, -//! with every argument at full precision, in call order per page; the images by embed -//! order; the links as the saved annotations carried them. The O1 oracle +//! with every argument at full precision, in call order per page; the links as the saved +//! annotations carried them. The images are referenced by embed index: their bytes went +//! to the writer when they were embedded (R4.6). The O1 oracle //! (`apps/app/tests/fixtures/goldens/r4/draw.*.json`) is this shape; R4.5 turns it into //! content streams. Nothing here rounds or reorders. @@ -111,20 +112,10 @@ pub struct PageLog { pub footer_start: usize, } -/// An embedded image: the PNG bytes as given, in embed order (branding slots first, then -/// each observation's views in view order), with its pixel size from the header. -#[derive(Debug, Clone, PartialEq)] -pub struct Embed { - pub png: Vec, - pub width: u32, - pub height: u32, -} - /// The whole document's drawing, before serialisation. #[derive(Debug, Clone, Default, PartialEq)] pub struct DrawLog { pub pages: Vec, - pub embeds: Vec, pub links: Vec, } @@ -160,12 +151,6 @@ impl DrawLog { contents.chain(footers) } - /// Registers an image; its index is what the draw calls reference. - pub fn embed(&mut self, png: Vec, width: u32, height: u32) -> usize { - self.embeds.push(Embed { png, width, height }); - self.embeds.len() - 1 - } - pub fn text(&mut self, page: usize, op: TextOp) { self.push(page, DrawOp::Text(op)); } diff --git a/crates/core/src/pdf/write/export.rs b/crates/core/src/pdf/write/export.rs index 2b4f4106..23d2ead7 100644 --- a/crates/core/src/pdf/write/export.rs +++ b/crates/core/src/pdf/write/export.rs @@ -1,14 +1,15 @@ //! `exportReportArchive` and `exportFromEnvelope` of `packages/pdf/src/export.ts` (R4.5): //! the checks, the envelope, the layout, the file, then the self-check: the file re-read by //! the R4 reader must carry the envelope it was written with, else `self_check_failed`. +//! Since R4.6 the one-shot form drives the [`ExportSession`] from a map of rasters, so +//! the application's export and these entries share one code path. use serde_json::Value; use super::input::{ - CheckedInput, ExportError, ExportErrorKind, ExportInput, ExportWarning, Rasters, check_input, + CheckedInput, ExportError, ExportErrorKind, ExportInput, ExportWarning, Rasters, }; -use super::layout::layout; -use super::serialize::{Document, Metadata, export_date, serialize}; +use super::session::{ExportSession, ExportStep, SessionError, keyed}; use crate::domain::archive::{EnvelopeFormat, EnvelopeVersion1, Locale, ReportArchiveEnvelope}; use crate::json::to_js_pretty; use crate::pdf::read::MAX_ATTACHMENT_BYTES; @@ -24,7 +25,7 @@ pub struct ExportResult { /// The envelope exactly as the TypeScript built and stringified it (`buildEnvelope`, /// `JSON.stringify(envelope, null, 2)`), under the attachment cap. -fn envelope_text(input: &CheckedInput) -> Result { +pub(super) fn envelope_text(input: &CheckedInput) -> Result { let envelope = ReportArchiveEnvelope { format: EnvelopeFormat, envelope_version: EnvelopeVersion1, @@ -48,12 +49,15 @@ fn envelope_text(input: &CheckedInput) -> Result { Ok(text) } -/// `finish()` re-reads its own output: one scan and one inflation, the attachment's text -/// against the envelope written. The scan runs without the reader's 50 MiB file cap: a -/// larger export (a report near the caps with real rasters) is a valid file that the import -/// refuses by size, as the TypeScript's did (plan §B.1.2); the export is not where to refuse it. -fn self_check(pdf: &[u8], envelope: &str) -> Result<(), ExportError> { - let located = locate_attachment(pdf, ProbeLimits::PRODUCTION).map_err(|kind| ExportError { +/// `finish()` re-reads its own output with the R4 reader: one scan and one inflation, +/// the attachment's text against the envelope written. `scan` is the header and the chunk +/// the attachment objects open (R4.6: the file is never held whole in the module, and the +/// reader finds the attachment by scanning its bytes, never by the xref, so the bytes it +/// reads are these). The scan runs without the reader's 50 MiB file cap: a larger export +/// (a report near the caps with real rasters) is a valid file that the import refuses by +/// size, as the TypeScript's did (plan §B.1.2); the export is not where to refuse it. +pub(super) fn self_check(scan: &[u8], envelope: &str) -> Result<(), ExportError> { + let located = locate_attachment(scan, ProbeLimits::PRODUCTION).map_err(|kind| ExportError { kind: ExportErrorKind::SelfCheckFailed, detail: kind.as_str().to_owned(), })?; @@ -66,42 +70,46 @@ fn self_check(pdf: &[u8], envelope: &str) -> Result<(), ExportError> { Ok(()) } -/// The export, from the checked input and the rasters the caller made. -pub fn export_checked( - input: &CheckedInput, - rasters: &Rasters, -) -> Result { - let envelope = envelope_text(input)?; - let date = export_date(&input.exported_at)?; - let drawn = layout(input, rasters)?; - let labels = input.labels(); - let title = format!( - "{}{}", - labels.pdf_title_suffix_bilan, input.report.animal.name - ); - let document = Document { - log: &drawn.log, - envelope: envelope.as_bytes(), - metadata: Metadata { - title: &title, - author: &input.report.practitioner.name, - subject: &labels.pdf_subject, - date: &date, +/// A session call's failure in a one-shot export: a refused call here is a driver bug, +/// reported as `self_check_failed` (the file is not trusted). +fn export_error(error: SessionError) -> ExportError { + match error { + SessionError::Export(error) => error, + SessionError::Refused(refusal) => ExportError { + kind: ExportErrorKind::SelfCheckFailed, + detail: refusal.as_str().to_owned(), }, - }; - let pdf = serialize(&document)?; - self_check(&pdf, &envelope)?; - Ok(ExportResult { - pdf, - envelope, - warnings: drawn.warnings, - }) + } } -/// `exportReportArchive`: every check, then the file. +/// `exportReportArchive`: every check, then the file, the session answered from the map +/// in request order (a missing key is `raster_failed`). pub fn export_pdf(input: ExportInput, rasters: &Rasters) -> Result { - let checked = check_input(input)?; - export_checked(&checked, rasters) + let mut session = ExportSession::new(input)?; + let keyed = keyed(rasters); + loop { + let requests = match session.next_step().map_err(export_error)? { + ExportStep::Done => break, + ExportStep::Rasters { requests } => requests, + }; + for request in requests { + let answer = match keyed.get(&request.key) { + Some(png) => session.add_raster(&request.key, png), + None => session.raster_failed(&request.key), + }; + answer.map_err(export_error)?; + } + } + session.finish().map_err(export_error)?; + let mut pdf = Vec::with_capacity(session.written()); + while let Some(part) = session.take_part() { + pdf.extend_from_slice(&part); + } + Ok(ExportResult { + pdf, + envelope: session.envelope().to_owned(), + warnings: session.warnings().to_vec(), + }) } /// `exportFromEnvelope`: an archive re-exported from its own snapshot, branding and labels, diff --git a/crates/core/src/pdf/write/input.rs b/crates/core/src/pdf/write/input.rs index 43221ddb..120249a6 100644 --- a/crates/core/src/pdf/write/input.rs +++ b/crates/core/src/pdf/write/input.rs @@ -9,7 +9,7 @@ use serde_json::Value; #[cfg(feature = "ts")] use ts_rs::TS; -use crate::anatomy::svg::read_svg; +use crate::anatomy::svg::{Element, read_svg}; use crate::domain::archive::{ Branding, Locale, PdfLabelSet, PdfLabels, SheetSnapshot, SnapshotRejection, assert_snapshot, }; @@ -104,12 +104,33 @@ pub enum LogoSlot { Partner, } +impl LogoSlot { + /// `embedBranding`'s order. + pub const ALL: [LogoSlot; 4] = [ + LogoSlot::HeaderLogo, + LogoSlot::FooterLogo, + LogoSlot::PoweredBy, + LogoSlot::Partner, + ]; + + /// The serde name (`headerLogo`, …), the slot's spelling in warnings and raster keys. + pub fn as_str(self) -> &'static str { + match self { + Self::HeaderLogo => "headerLogo", + Self::FooterLogo => "footerLogo", + Self::PoweredBy => "poweredBy", + Self::Partner => "partner", + } + } +} + /// `PAGE_CAPS` of export.ts. pub const MAX_OBSERVATIONS: usize = 500; pub const MAX_VIEWS_PER_OBSERVATION: usize = 8; /// The input once every check passed: typed branding and labels, the parsed snapshot and -/// its index, the labels of the locale. +/// its index, the labels of the locale, the sanitised tree of every asset (read once by +/// the gate, composed per view by the session). pub struct CheckedInput { pub report: Report, pub snapshot: SheetSnapshot, @@ -118,6 +139,7 @@ pub struct CheckedInput { pub labels: PdfLabelSet, pub locale: Locale, pub exported_at: String, + assets: Vec<(String, Element)>, } impl CheckedInput { @@ -127,6 +149,14 @@ impl CheckedInput { Locale::En => &self.labels.en, } } + + /// The sanitised drawing of the first snapshot asset of this id. + pub fn sanitised_asset(&self, svg_asset_id: &str) -> Option<&Element> { + self.assets + .iter() + .find(|(id, _)| id == svg_asset_id) + .map(|(_, root)| root) + } } /// Step 0: the branding and the labels pass their schemas again (they reach the engine @@ -139,20 +169,27 @@ fn typed_branding(input: &ExportInput) -> Result<(Branding, PdfLabelSet), Export Ok((branding, labels)) } +type SanitisedAssets = Vec<(String, Element)>; + /// Step 1: the snapshot gate, with every asset accepted by the SVG reader (R3's reader -/// since R4: a drawing it refuses is `snapshot_invalid`, declared RUST.md §9.4). -fn checked_snapshot(value: &Value) -> Result { +/// since R4: a drawing it refuses is `snapshot_invalid`, declared RUST.md §9.4); the +/// sanitised trees are kept for the views. +fn checked_snapshot(value: &Value) -> Result<(SheetSnapshot, SanitisedAssets), ExportError> { let snapshot = assert_snapshot(value).map_err(|rejection| match rejection { SnapshotRejection::Caps => error(ExportErrorKind::SnapshotTooLarge, "caps"), other => error(ExportErrorKind::SnapshotInvalid, &reason_of(other)), })?; + let mut assets = Vec::with_capacity(snapshot.assets.len()); for asset in &snapshot.assets { - if let Err(rejection) = read_svg(&asset.svg) { - let detail = format!("asset {}", rejection.reason()); - return Err(error(ExportErrorKind::SnapshotInvalid, &detail)); + match read_svg(&asset.svg) { + Ok(sanitised) => assets.push((asset.svg_asset_id.clone(), sanitised.root)), + Err(rejection) => { + let detail = format!("asset {}", rejection.reason()); + return Err(error(ExportErrorKind::SnapshotInvalid, &detail)); + } } } - Ok(snapshot) + Ok((snapshot, assets)) } /// The rejection's serde name (`caps`, `schema`, …), today's `SnapshotError.reason`. @@ -191,7 +228,7 @@ fn assert_exportable(report: &Report, snapshot: &SheetSnapshot) -> Result<(), Ex /// Every check of export.ts before a page is drawn, in its order. pub fn check_input(input: ExportInput) -> Result { let (branding, labels) = typed_branding(&input)?; - let snapshot = checked_snapshot(&input.sheet_snapshot)?; + let (snapshot, assets) = checked_snapshot(&input.sheet_snapshot)?; assert_exportable(&input.report, &snapshot)?; let index = SheetIndex::build(&snapshot.document) .map_err(|NoMainView| error(ExportErrorKind::SnapshotInvalid, "no main view"))?; @@ -203,12 +240,13 @@ pub fn check_input(input: ExportInput) -> Result { labels, locale: input.locale, exported_at: input.exported_at, + assets, }) } -/// The rasters the layout embeds (R4.4: given by the caller; R4.6: requested through the -/// session). A slot or view absent from the map, or whose bytes are not a PNG the header -/// of which can be read, draws nothing and leaves a warning, as `embedPng` throwing did. +/// The rasters of a one-shot export (`export_pdf`, the oracle suites): the driver answers +/// the session from this map. A slot or view absent from it is `raster_failed`; bytes the +/// decoder refuses draw nothing and leave the same warning, as `embedPng` throwing did. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct Rasters { pub header_logo: Option>, diff --git a/crates/core/src/pdf/write/layout/mod.rs b/crates/core/src/pdf/write/layout/mod.rs index 9edc2e00..a7357806 100644 --- a/crates/core/src/pdf/write/layout/mod.rs +++ b/crates/core/src/pdf/write/layout/mod.rs @@ -1,18 +1,56 @@ //! The page layouts (`packages/pdf/src/render/*` and the page loop of `export.ts`): one //! observation page per observation, the conclusion page, then the footer of every page, //! into a [`DrawLog`]. Every number is computed in the TypeScript's order on f64, so the -//! log matches the O1 oracle bit for bit. +//! log matches the O1 oracle bit for bit. The images go to an [`ImageSink`] the moment +//! they are embedded (R4.6: the session's writer decodes and writes each one on arrival); +//! the log keeps their index and pixel size only. mod conclusion; mod footer; mod header; -mod observation; +pub mod observation; pub mod png; use super::draw_log::{DrawLog, Rgb, rgb}; use super::input::{CheckedInput, ExportError, ExportErrorKind, ExportWarning, LogoSlot, Rasters}; use super::text::Font; use crate::domain::archive::{Credit, ImageAsset, PdfLabels}; +use crate::domain::report::Observation; + +/// Where an embedded image goes: the writer (decode, image object, PNG and planes +/// dropped) in the product, a recorder in the oracle suites. +pub trait ImageSink { + /// Embeds `png`; `None` when the bytes are not a PNG the decoder accepts, which the + /// layout records as the slot's or the view's warning (as `embedPng` throwing was). + fn embed(&mut self, png: &[u8]) -> Option; +} + +/// The rasters of the four logo slots (SVG assets only need one). +#[derive(Debug, Clone, Copy, Default)] +pub struct LogoRasters<'a> { + pub header_logo: Option<&'a [u8]>, + pub footer_logo: Option<&'a [u8]>, + pub powered_by: Option<&'a [u8]>, + pub partner: Option<&'a [u8]>, +} + +impl<'a> LogoRasters<'a> { + pub fn of(rasters: &'a Rasters) -> Self { + Self { + header_logo: rasters.header_logo.as_deref(), + footer_logo: rasters.footer_logo.as_deref(), + powered_by: rasters.powered_by.as_deref(), + partner: rasters.partner.as_deref(), + } + } +} + +/// A view's image once embedded, in the order the page draws them. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ViewImage { + pub view_id: String, + pub image: Image, +} /// `render/constants.ts`: values identical across callers. pub const MARGIN_X: f64 = 36.0; @@ -56,11 +94,13 @@ pub struct BrandingImages { pub partner: Option, } -/// The whole export's drawing state. +/// The export's drawing state for one phase: the log and the warnings are the session's, +/// lent for the phase (R4.6), the sink receives the images. pub struct Layout<'a> { pub input: &'a CheckedInput, pub log: DrawLog, pub warnings: Vec, + pub sink: &'a mut dyn ImageSink, } impl<'a> Layout<'a> { @@ -68,16 +108,49 @@ impl<'a> Layout<'a> { self.input.labels() } - /// Embeds `png` and returns its handle; `None` (a warning for the caller) when the - /// bytes are not a PNG whose header can be read, as `embedPng` throwing was. - fn embed(&mut self, png: &[u8]) -> Option { - let (width, height) = png::dimensions(png)?; - let embed = self.log.embed(png.to_vec(), width, height); - Some(Image { - embed, - width, - height, - }) + /// Embeds `png` through the sink; `None` is the caller's warning. + pub fn embed(&mut self, png: &[u8]) -> Option { + self.sink.embed(png) + } + + /// The observation's views embedded in view order through the sink, as the one-shot + /// driver answers the session: a view with no raster is warned first (in view order), + /// then each raster is embedded, a refused one warned, in view order. + pub fn embed_views(&mut self, observation: &Observation, rasters: &Rasters) -> Vec { + let view_ids: Vec = observation::observation_view_ids( + &self.input.index.over(&self.input.snapshot.document), + observation, + ) + .into_iter() + .map(str::to_owned) + .collect(); + let raster = |view_id: &str| { + rasters + .views + .get(&(observation.id.clone(), view_id.to_owned())) + }; + for view_id in view_ids.iter().filter(|id| raster(id).is_none()) { + self.warn_view(&observation.id, view_id); + } + let mut images = Vec::new(); + for view_id in &view_ids { + let Some(png) = raster(view_id) else { continue }; + match self.embed(png) { + Some(image) => images.push(ViewImage { + view_id: view_id.clone(), + image, + }), + None => self.warn_view(&observation.id, view_id), + } + } + images + } + + pub fn warn_view(&mut self, observation_id: &str, view_id: &str) { + self.warnings.push(ExportWarning::ViewRasterFailed { + observation_id: observation_id.to_owned(), + view_id: view_id.to_owned(), + }); } /// `embedSlot`: a PNG asset decodes its own base64, an SVG asset takes the raster the @@ -117,32 +190,72 @@ impl<'a> Layout<'a> { } /// `embedBranding`: header, footer, powered-by, partner, in that order. - fn embed_branding(&mut self, rasters: &Rasters) -> BrandingImages { + fn embed_branding(&mut self, rasters: &LogoRasters<'_>) -> BrandingImages { let branding = &self.input.branding; BrandingImages { site_url: branding.site_url.clone(), header: self.embed_slot( LogoSlot::HeaderLogo, branding.header_logo.as_ref(), - rasters.header_logo.as_deref(), + rasters.header_logo, ), footer: self.embed_slot( LogoSlot::FooterLogo, branding.footer_logo.as_ref(), - rasters.footer_logo.as_deref(), + rasters.footer_logo, ), powered_by: self.embed_credit( LogoSlot::PoweredBy, branding.powered_by.as_ref(), - rasters.powered_by.as_deref(), + rasters.powered_by, ), partner: self.embed_credit( LogoSlot::Partner, branding.partner.as_ref(), - rasters.partner.as_deref(), + rasters.partner, ), } } + + /// Phase 1 (`embedBranding` then the link check): the branding, embedded in slot order. + pub fn begin(&mut self, rasters: &LogoRasters<'_>) -> Result { + let branding = self.embed_branding(rasters); + assert_link_urls(&branding)?; + Ok(branding) + } + + /// Phase 2: the page of observation `position`, its views already embedded. + pub fn observation_page( + &mut self, + branding: &BrandingImages, + position: usize, + observation: &Observation, + images: &[ViewImage], + ) { + let header = header_assets(branding); + observation::add_observation_page(self, &header, position, observation, images); + } + + /// Phase 3: the conclusion page, then every page's footer with its pagination. + pub fn end(&mut self, branding: &BrandingImages) { + let header = header_assets(branding); + conclusion::add_conclusion_page(self, &header); + let total = self.log.pages.len(); + for page in 0..total { + self.log.begin_footer(page); + footer::draw_footer(self, page, page + 1, total, branding); + } + // A page's annotations are its own array: the header link, then the footer's, in + // page order, whatever the order the calls were made in. + self.log.links.sort_by_key(|link| link.page); + } +} + +fn header_assets(branding: &BrandingImages) -> header::HeaderAssets<'_> { + header::HeaderAssets { + logo: branding.header, + site_url: &branding.site_url, + } } /// Printable ASCII without the space: what the link sink writes as hex bytes @@ -169,32 +282,25 @@ pub struct Drawn { pub warnings: Vec, } -/// Lays the report out: branding embedded first, one page per observation, the -/// conclusion page, then every page's footer with its pagination. -pub fn layout(input: &CheckedInput, rasters: &Rasters) -> Result { +/// The one-shot form (the oracle suites, `export_pdf` goes through the session): the +/// three phases on the rasters given, the images to `sink`. +pub fn layout( + input: &CheckedInput, + rasters: &Rasters, + sink: &mut dyn ImageSink, +) -> Result { let mut layout = Layout { input, log: DrawLog::default(), warnings: Vec::new(), + sink, }; - let branding = layout.embed_branding(rasters); - assert_link_urls(&branding)?; - let header = header::HeaderAssets { - logo: branding.header, - site_url: &branding.site_url, - }; + let branding = layout.begin(&LogoRasters::of(rasters))?; for (position, observation) in input.report.observations.iter().enumerate() { - observation::add_observation_page(&mut layout, &header, position, observation, rasters); + let images = layout.embed_views(observation, rasters); + layout.observation_page(&branding, position, observation, &images); } - conclusion::add_conclusion_page(&mut layout, &header); - let total = layout.log.pages.len(); - for page in 0..total { - layout.log.begin_footer(page); - footer::draw_footer(&mut layout, page, page + 1, total, &branding); - } - // A page's annotations are its own array: the header link, then the footer's, in - // page order, whatever the order the calls were made in. - layout.log.links.sort_by_key(|link| link.page); + layout.end(&branding); Ok(Drawn { log: layout.log, warnings: layout.warnings, diff --git a/crates/core/src/pdf/write/layout/observation.rs b/crates/core/src/pdf/write/layout/observation.rs index 94016f06..02683ccc 100644 --- a/crates/core/src/pdf/write/layout/observation.rs +++ b/crates/core/src/pdf/write/layout/observation.rs @@ -8,6 +8,7 @@ use super::header::{HeaderAssets, draw_header}; use super::{ BODY_BOLD, BODY_REGULAR, COLOR_ACCENT, COLOR_INK, EYEBROW_Y_OFFSET, HEADING_REGULAR, Image, Layout, MARGIN_X, SECTION_LABEL_GAP, TITLE_RULE_OFFSET, TITLE_RULE_WIDTH, TITLE_Y_OFFSET, + ViewImage, }; use crate::domain::archive::{Locale, PdfLabels}; use crate::domain::report::{Finding, LateralSide, Observation, ReportZone, Severity}; @@ -17,7 +18,6 @@ use crate::json::js_number; use crate::pdf::write::draw_log::{ ImageOp, LineOp, PAGE_HEIGHT, PAGE_WIDTH, Point, RectangleOp, Rgb, TextOp, rgb, }; -use crate::pdf::write::input::{ExportWarning, Rasters}; use crate::pdf::write::text::{js_trim, js_upper, measure, safe_text, wrap_lines}; const MARGIN_BOTTOM: f64 = 48.0; @@ -300,44 +300,28 @@ struct Rendered { aspect: f64, } -/// The observation's views embedded in view order; a missing or unreadable raster is a -/// `view_raster_failed` warning. -fn build_images( - layout: &mut Layout<'_>, - observation: &Observation, - rasters: &Rasters, -) -> Vec { +/// The embedded views with their labels and aspects (`buildObservationImages` after +/// `embedPng`): the images arrive embedded in view order, the failed ones already warned. +fn build_images(layout: &Layout<'_>, images: &[ViewImage]) -> Vec { let sheet = layout.input.index.over(&layout.input.snapshot.document); - let view_ids: Vec = observation_view_ids(&sheet, observation) - .into_iter() - .map(str::to_owned) - .collect(); - let mut rendered = Vec::new(); - for view_id in view_ids { - let key = (observation.id.clone(), view_id.clone()); - let image = rasters.views.get(&key).and_then(|png| layout.embed(png)); - let Some(image) = image else { - layout.warnings.push(ExportWarning::ViewRasterFailed { - observation_id: observation.id.clone(), - view_id, - }); - continue; - }; - let sheet = layout.input.index.over(&layout.input.snapshot.document); - let view = sheet.view(&view_id); - let label = view.map_or_else(String::new, |v| view_label(layout, v)); - let aspect = if image.width > 0 { - f64::from(image.height) / f64::from(image.width) - } else { - 0.6 - }; - rendered.push(Rendered { - label, - image, - aspect, - }); - } - rendered + images + .iter() + .map(|ViewImage { view_id, image }| { + let label = sheet + .view(view_id) + .map_or_else(String::new, |v| view_label(layout, v)); + let aspect = if image.width > 0 { + f64::from(image.height) / f64::from(image.width) + } else { + 0.6 + }; + Rendered { + label, + image: *image, + aspect, + } + }) + .collect() } struct Grid { @@ -651,12 +635,12 @@ pub fn add_observation_page( header: &HeaderAssets<'_>, position: usize, observation: &Observation, - rasters: &Rasters, + images: &[ViewImage], ) { let page = layout.log.add_page(); draw_header(layout, page, header); let title_y = draw_title_block(layout, page, position, observation.severity); - let rendered = build_images(layout, observation, rasters); + let rendered = build_images(layout, images); let max_text_w = PAGE_WIDTH - MARGIN_X * 2.0; let sections = sections(layout, observation); let reserved_bottom = diff --git a/crates/core/src/pdf/write/mod.rs b/crates/core/src/pdf/write/mod.rs index 79fdb012..f253540f 100644 --- a/crates/core/src/pdf/write/mod.rs +++ b/crates/core/src/pdf/write/mod.rs @@ -4,7 +4,8 @@ //! observation page, the conclusion page, then the footers of every page), pinned by the //! O1 oracle (`apps/app/tests/fixtures/goldens/r4/draw.*.json`) and the Step 6 goldens. The //! text rules (`text`, `afm_data`) and the dates (`dates`) are pinned by O4, O5 and O6. The -//! serialiser that turns the log into PDF bytes is R4.5. +//! serialiser that turns the log into PDF bytes is R4.5; the incremental session the +//! application drives (`session`, `views`) is R4.6. pub mod afm_data; pub mod content; @@ -16,4 +17,6 @@ pub mod layout; pub mod objects; pub mod png; pub mod serialize; +pub mod session; pub mod text; +pub mod views; diff --git a/crates/core/src/pdf/write/objects.rs b/crates/core/src/pdf/write/objects.rs index 381491b1..258b0aba 100644 --- a/crates/core/src/pdf/write/objects.rs +++ b/crates/core/src/pdf/write/objects.rs @@ -1,5 +1,5 @@ -//! A minimal PDF object writer (R4.5): numbered objects, streams, a classic xref table and -//! the trailer, with the string forms pdf-lib used (UTF-16BE hex with a BOM for text, +//! A minimal PDF object writer (R4.5, streaming since R4.6): numbered objects written as +//! they come, streams, a classic xref table and the trailer, with the string forms pdf-lib used (UTF-16BE hex with a BOM for text, //! literal dates `D:YYYYMMDDHHmmSSZ`, hex ASCII for URIs). pdf-writer was planned here; a //! writer of this size (the document holds a dozen object kinds) spells every number through //! `numberToString` and keeps the dictionaries under our control, so the B5 precision @@ -7,11 +7,29 @@ use super::content::number_to_string; -/// The bytes of one indirect object's body (a dictionary, or a stream with its dictionary). +/// The file as it is written (R4.6, OD-2): every object lands in the file the moment it +/// is added, in chunks that are never reallocated (an object larger than the chunk's +/// target gets a chunk of its own), so the image streams never wait in a second structure +/// for `finish` and no growing buffer copies the file over itself. The chunk target starts +/// at [`CHUNK_FIRST`] and doubles per chunk up to [`CHUNK_MAX`]: a small file pays little +/// slack, a large one makes few long-lived allocations between the decode transients +/// (measured: 1 MiB chunks cost 0.12 MB of fragmentation per view, 8 MiB none). The chunks +/// are handed out one by one at the end (a `Blob` takes parts), so the file is never held +/// twice. A reserved object (the catalog, the page tree) is written where `set` is +/// called, at the end; the xref maps every number to its offset wherever the object lies. pub struct Objects { - bodies: Vec>, + sealed: Vec>, + current: Vec, + target: usize, + /// Bytes in the sealed chunks and the current one. + total: usize, + /// Offset of each object by number, `None` while reserved. + offsets: Vec>, } +pub const CHUNK_FIRST: usize = 1 << 20; +pub const CHUNK_MAX: usize = 8 << 20; + /// `n 0 R`. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Ref(pub usize); @@ -22,81 +40,170 @@ impl Ref { } } +const HEADER: &[u8] = b"%PDF-1.7\n%\xE2\xE3\xCF\xD3\n\n"; + impl Objects { pub fn new() -> Self { - Self { bodies: Vec::new() } + let mut objects = Self { + sealed: Vec::new(), + current: Vec::new(), + target: CHUNK_FIRST, + total: 0, + offsets: Vec::new(), + }; + objects.open_for(HEADER.len()); + objects.write(HEADER); + objects + } + + /// Bytes written so far (the file's size before the xref). + pub fn written(&self) -> usize { + self.total + } + + /// Closes the current chunk; the next object starts a new one. + fn seal(&mut self) { + if !self.current.is_empty() { + let mut chunk = std::mem::take(&mut self.current); + // The slack of the target is given back: a sealed chunk costs its bytes. + chunk.shrink_to_fit(); + self.sealed.push(chunk); + self.target = (self.target * 2).min(CHUNK_MAX); + } + } + + /// Makes room for an object of `size` bytes in one chunk: the current one when it + /// fits, else a new one of the target size (or the object's, when larger). + fn open_for(&mut self, size: usize) { + if self.current.len() + size > self.current.capacity() { + self.seal(); + } + if self.current.capacity() == 0 { + self.current.reserve_exact(size.max(self.target)); + } + } + + /// The chunk and the offset in it of the file offset `at` (an object's xref offset), + /// once the file is finished. + fn locate(sealed: &[Vec], at: usize) -> (usize, usize) { + let mut start = 0; + for (index, chunk) in sealed.iter().enumerate() { + if at < start + chunk.len() { + return (index, at - start); + } + start += chunk.len(); + } + (sealed.len(), 0) + } + + /// The xref offset of an object already written. + pub fn offset_of(&self, at: Ref) -> Option { + at.0.checked_sub(1) + .and_then(|i| self.offsets.get(i).copied().flatten()) + } + + fn write(&mut self, bytes: &[u8]) { + self.current.extend_from_slice(bytes); + self.total += bytes.len(); } /// Reserves the next object number; its body comes later with [`Objects::set`]. pub fn reserve(&mut self) -> Ref { - self.bodies.push(Vec::new()); - Ref(self.bodies.len()) + self.offsets.push(None); + Ref(self.offsets.len()) } - pub fn set(&mut self, at: Ref, body: Vec) { - if let Some(slot) = at.0.checked_sub(1).and_then(|i| self.bodies.get_mut(i)) { - *slot = body; + /// Writes the body of a reserved object; a second `set` or an unknown number is ignored. + pub fn set(&mut self, at: Ref, body: &[u8]) { + let Some(slot) = at.0.checked_sub(1).and_then(|i| self.offsets.get(i)) else { + return; + }; + if slot.is_some() { + return; } + let offset = self.write_object(at.0, &[body]); + self.offsets[at.0 - 1] = Some(offset); } - pub fn add(&mut self, body: Vec) -> Ref { - self.bodies.push(body); - Ref(self.bodies.len()) + pub fn add(&mut self, body: &[u8]) -> Ref { + let number = self.offsets.len() + 1; + let offset = self.write_object(number, &[body]); + self.offsets.push(Some(offset)); + Ref(number) } /// A stream object: the dictionary entries (without `/Length`) and the data. pub fn add_stream(&mut self, entries: &[(&str, String)], data: &[u8]) -> Ref { - self.bodies.push(stream_body(entries, data)); - Ref(self.bodies.len()) + let number = self.offsets.len() + 1; + let mut head = String::from("<<"); + for (key, value) in entries { + head.push_str(&format!(" /{key} {value}")); + } + head.push_str(&format!(" /Length {} >>\nstream\n", data.len())); + let offset = self.write_object(number, &[head.as_bytes(), data, b"\nendstream"]); + self.offsets.push(Some(offset)); + Ref(number) } - /// The whole file: header, objects in number order, xref, trailer. - pub fn finish(self, root: Ref, info: Ref) -> Vec { - let mut out = - Vec::with_capacity(self.bodies.iter().map(|b| b.len() + 24).sum::() + 256); - out.extend_from_slice(b"%PDF-1.7\n%\xE2\xE3\xCF\xD3\n\n"); - let mut offsets = Vec::with_capacity(self.bodies.len()); - for (i, body) in self.bodies.iter().enumerate() { - offsets.push(out.len()); - out.extend_from_slice(format!("{} 0 obj\n", i + 1).as_bytes()); - out.extend_from_slice(body); - out.extend_from_slice(b"\nendobj\n\n"); + /// `n 0 obj`, the parts, `endobj`, in one chunk. + fn write_object(&mut self, number: usize, parts: &[&[u8]]) -> usize { + let head = format!("{number} 0 obj\n"); + let size = head.len() + parts.iter().map(|p| p.len()).sum::() + 9; + self.open_for(size); + let offset = self.total; + self.write(head.as_bytes()); + for part in parts { + self.write(part); } - let xref = out.len(); - out.extend_from_slice( - format!("xref\n0 {}\n0000000000 65535 f \n", offsets.len() + 1).as_bytes(), - ); - for offset in offsets { - out.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes()); + self.write(b"\nendobj\n\n"); + offset + } + + /// The whole file as its chunks: the objects as written, then the xref and the + /// trailer. A number still reserved is a free entry. `attachment` is the file offset + /// of the attachment stream object, located in the chunks for the self-check. + pub fn finish(mut self, root: Ref, info: Ref, attachment: usize) -> Chunks { + let xref = self.total; + let mut tail = format!("xref\n0 {}\n0000000000 65535 f \n", self.offsets.len() + 1); + for offset in &self.offsets { + match offset { + Some(offset) => tail.push_str(&format!("{offset:010} 00000 n \n")), + None => tail.push_str("0000000000 65535 f \n"), + } } - let trailer = format!( + tail.push_str(&format!( "trailer\n<< /Size {} /Root {} /Info {} >>\nstartxref\n{xref}\n%%EOF\n", - self.bodies.len() + 1, + self.offsets.len() + 1, root.text(), info.text() - ); - out.extend_from_slice(trailer.as_bytes()); - out + )); + self.open_for(tail.len()); + self.write(tail.as_bytes()); + self.seal(); + let attachment = Self::locate(&self.sealed, attachment); + Chunks { + chunks: self.sealed, + attachment, + } } } +/// A finished file: its chunks in order, and where the attachment stream object starts. +pub struct Chunks { + pub chunks: Vec>, + /// `(chunk index, offset in the chunk)`. + pub attachment: (usize, usize), +} + impl Default for Objects { fn default() -> Self { Self::new() } } -fn stream_body(entries: &[(&str, String)], data: &[u8]) -> Vec { - let mut body = Vec::with_capacity(data.len() + 128); - let mut head = String::from("<<"); - for (key, value) in entries { - head.push_str(&format!(" /{key} {value}")); - } - head.push_str(&format!(" /Length {} >>\nstream\n", data.len())); - body.extend_from_slice(head.as_bytes()); - body.extend_from_slice(data); - body.extend_from_slice(b"\nendstream"); - body +/// The header alone, what a chunk needs in front of it for the reader to scan it. +pub fn header() -> &'static [u8] { + HEADER } /// `<< /K v … >>` from entries already spelt as PDF syntax. diff --git a/crates/core/src/pdf/write/serialize.rs b/crates/core/src/pdf/write/serialize.rs index 4b1c52f9..074cf61c 100644 --- a/crates/core/src/pdf/write/serialize.rs +++ b/crates/core/src/pdf/write/serialize.rs @@ -1,19 +1,24 @@ -//! The PDF file from a draw log (R4.5, plan §B.1.3): the objects pdf-lib's `save()` wrote -//! for the Step 6 engine, in our own order and names (B2, B3 of §B.2.3): catalog with the -//! names tree and `/AF`, the page tree, three Type1 fonts with `WinAnsiEncoding`, one image -//! XObject per embed (DeviceRGB 8 bits, a DeviceGray `/SMask` with `/Decode [0 1]` when an -//! alpha is below 255), Link annotations (`/Border [0 0 0]`, a URI action with the URL as hex -//! ASCII), the Info dictionary (Producer and Creator `Faunosteo`, A4; the rest in pdf-lib's -//! forms), the attachment (a Flate `EmbeddedFile` with `Params`, the Filespec, the names -//! tree entry) and a classic xref; no object stream, so the scanner reads the file. +//! The PDF file from a draw log (R4.5, plan §B.1.3; a writer fed as the export goes since +//! R4.6): the objects pdf-lib's `save()` wrote for the Step 6 engine, in our own order and +//! names (B2, B3 of §B.2.3): catalog with the names tree and `/AF`, the page tree, three +//! Type1 fonts with `WinAnsiEncoding`, one image XObject per embed (DeviceRGB 8 bits, a +//! DeviceGray `/SMask` with `/Decode [0 1]` when an alpha is below 255), Link annotations +//! (`/Border [0 0 0]`, a URI action with the URL as hex ASCII), the Info dictionary +//! (Producer and Creator `Faunosteo`, A4; the rest in pdf-lib's forms), the attachment (a +//! Flate `EmbeddedFile` with `Params`, the Filespec, the names tree entry) and a classic +//! xref; no object stream, so the scanner reads the file. The [`Writer`] opens the file +//! with the Info and the fonts, writes each image the moment it is embedded (the PNG and +//! its planes live for that call only) and closes it with the pages and the attachment; +//! the catalog and the page tree, reserved as objects 1 and 2, are written last. use miniz_oxide::deflate::compress_to_vec_zlib; use super::content::{font_resource_name, image_resource_name, page_content}; -use super::draw_log::{DrawLog, DrawOp, Embed, PAGE_HEIGHT, PAGE_WIDTH, PageLog}; +use super::draw_log::{DrawLog, DrawOp, PAGE_HEIGHT, PAGE_WIDTH, PageLog}; use super::input::{ExportError, ExportErrorKind}; +use super::layout::{Image, ImageSink}; use super::objects::{Objects, Ref, dict, hex_ascii, hex_text, literal, name, numbers, pdf_date}; -use super::png::{DecodedPng, decode_png}; +use super::png::decode_png; use super::text::Font; /// pako's default level, what `context.flateStream` used. @@ -34,30 +39,15 @@ pub struct Metadata<'a> { pub date: &'a str, } -/// What `serialize` writes besides the pages: the envelope bytes and the metadata. -pub struct Document<'a> { - pub log: &'a DrawLog, - pub envelope: &'a [u8], - pub metadata: Metadata<'a>, -} - fn deflate(data: &[u8]) -> Vec { compress_to_vec_zlib(data, DEFLATE_LEVEL) } -/// The decoded planes of an embed; a PNG the decoder refuses is an internal inconsistency -/// (the layout read its header), reported as `self_check_failed` rather than drawn wrong. -fn planes(embed: &Embed) -> Result { - decode_png(&embed.png).map_err(|_| ExportError { - kind: ExportErrorKind::SelfCheckFailed, - detail: "image decode".to_owned(), - }) -} - -/// One image XObject (and its SMask when the alpha plane is kept), PNG and planes dropped -/// as soon as written. -fn write_image(objects: &mut Objects, embed: &Embed) -> Result { - let decoded = planes(embed)?; +/// One image XObject (and its SMask when the alpha plane is kept) from a PNG the decoder +/// accepts; `None` for one it refuses (the caller's warning, as `embedPng` throwing was). +/// The planes are dropped as soon as written. +fn write_image(objects: &mut Objects, png: &[u8]) -> Option<(Ref, u32, u32)> { + let decoded = decode_png(png).ok()?; let size = [ ("Width", decoded.width.to_string()), ("Height", decoded.height.to_string()), @@ -85,7 +75,8 @@ fn write_image(objects: &mut Objects, embed: &Embed) -> Result entries.push(("SMask", smask.text())); } entries.push(("Filter", "/FlateDecode".to_owned())); - Ok(objects.add_stream(&entries, &deflate(&decoded.rgb))) + let image = objects.add_stream(&entries, &deflate(&decoded.rgb)); + Some((image, decoded.width, decoded.height)) } fn write_fonts(objects: &mut Objects) -> [(Font, Ref); 3] { @@ -97,7 +88,7 @@ fn write_fonts(objects: &mut Objects) -> [(Font, Ref); 3] { ("BaseFont", format!("/{}", font.as_str())), ("Encoding", "/WinAnsiEncoding".to_owned()), ]); - (font, objects.add(body.into_bytes())) + (font, objects.add(body.as_bytes())) }) } @@ -149,47 +140,10 @@ fn write_link(objects: &mut Objects, rect: [f64; 4], uri: &str) -> Ref { ("Border", "[0 0 0]".to_owned()), ("A", action), ]) - .into_bytes(), + .as_bytes(), ) } -struct Shared<'a> { - pages: Ref, - fonts: &'a [(Font, Ref); 3], - images: &'a [Ref], -} - -fn write_page( - objects: &mut Objects, - doc: &Document<'_>, - index: usize, - shared: &Shared<'_>, -) -> Option { - let page = doc.log.pages.get(index)?; - let content = objects.add_stream( - &[("Filter", "/FlateDecode".to_owned())], - &deflate(&page_content(page)), - ); - let annots: Vec = doc - .log - .links - .iter() - .filter(|link| link.page == index) - .map(|link| write_link(objects, link.rect, &link.uri).text()) - .collect(); - let mut entries = vec![ - ("Type", "/Page".to_owned()), - ("Parent", shared.pages.text()), - ("MediaBox", numbers(&[0.0, 0.0, PAGE_WIDTH, PAGE_HEIGHT])), - ("Contents", content.text()), - ("Resources", resources(shared.fonts, shared.images, page)), - ]; - if !annots.is_empty() { - entries.push(("Annots", format!("[{}]", annots.join(" ")))); - } - Some(objects.add(dict(&entries).into_bytes())) -} - fn write_info(objects: &mut Objects, metadata: &Metadata<'_>) -> Ref { objects.add( dict(&[ @@ -202,17 +156,18 @@ fn write_info(objects: &mut Objects, metadata: &Metadata<'_>) -> Ref { ("CreationDate", metadata.date.to_owned()), ("ModDate", metadata.date.to_owned()), ]) - .into_bytes(), + .as_bytes(), ) } /// The attachment (`attachment/write.ts`, pdf-lib `FileEmbedder`): the Flate stream with -/// its `Params`, then the Filespec in clear with the name in both forms. -fn write_attachment(objects: &mut Objects, doc: &Document<'_>) -> Ref { +/// its `Params`, then the Filespec in clear with the name in both forms. Returns the +/// Filespec and the stream. +fn write_attachment(objects: &mut Objects, envelope: &[u8], date: &str) -> (Ref, Ref) { let params = dict(&[ - ("Size", doc.envelope.len().to_string()), - ("CreationDate", doc.metadata.date.to_owned()), - ("ModDate", doc.metadata.date.to_owned()), + ("Size", envelope.len().to_string()), + ("CreationDate", date.to_owned()), + ("ModDate", date.to_owned()), ]); let stream = objects.add_stream( &[ @@ -221,9 +176,9 @@ fn write_attachment(objects: &mut Objects, doc: &Document<'_>) -> Ref { ("Params", params), ("Filter", "/FlateDecode".to_owned()), ], - &deflate(doc.envelope), + &deflate(envelope), ); - objects.add( + let filespec = objects.add( dict(&[ ("Type", "/Filespec".to_owned()), ("F", literal(ATTACHMENT_FILENAME)), @@ -232,8 +187,9 @@ fn write_attachment(objects: &mut Objects, doc: &Document<'_>) -> Ref { ("Desc", hex_text(ATTACHMENT_DESCRIPTION)), ("AFRelationship", "/Data".to_owned()), ]) - .into_bytes(), - ) + .as_bytes(), + ); + (filespec, stream) } /// The export time in the `D:` form, or the closed refusal of a timestamp that is not ISO. @@ -244,55 +200,157 @@ pub fn export_date(exported_at: &str) -> Result { }) } -/// The whole file. Object order: catalog, pages, info, fonts, then per image its XObject, -/// then per page its content, links and dictionary, then the attachment. -pub fn serialize(doc: &Document<'_>) -> Result, ExportError> { - let mut objects = Objects::new(); - let catalog = objects.reserve(); - let pages = objects.reserve(); - let info = write_info(&mut objects, &doc.metadata); - let fonts = write_fonts(&mut objects); - let mut images = Vec::with_capacity(doc.log.embeds.len()); - for embed in &doc.log.embeds { - images.push(write_image(&mut objects, embed)?); +/// The file being written. Object numbers: 1 catalog and 2 page tree (reserved, written +/// last), 3 Info, 4 to 6 the fonts, then one XObject per image (its SMask first) as the +/// images are embedded, then per page its content, links and dictionary, then the +/// attachment. +pub struct Writer { + objects: Objects, + catalog: Ref, + pages: Ref, + info: Ref, + fonts: [(Font, Ref); 3], + images: Vec, + date: String, +} + +impl Writer { + /// Opens the file: header, Info, fonts. + pub fn begin(metadata: &Metadata<'_>) -> Self { + let mut objects = Objects::new(); + let catalog = objects.reserve(); + let pages = objects.reserve(); + let info = write_info(&mut objects, metadata); + let fonts = write_fonts(&mut objects); + Self { + objects, + catalog, + pages, + info, + fonts, + images: Vec::new(), + date: metadata.date.to_owned(), + } } - let shared = Shared { - pages, - fonts: &fonts, - images: &images, - }; - let mut kids = Vec::with_capacity(doc.log.pages.len()); - for index in 0..doc.log.pages.len() { - if let Some(page) = write_page(&mut objects, doc, index, &shared) { - kids.push(page.text()); + + /// Bytes of the file so far. + pub fn written(&self) -> usize { + self.objects.written() + } + + fn write_page(&mut self, log: &DrawLog, index: usize) -> Option { + let page = log.pages.get(index)?; + let content = self.objects.add_stream( + &[("Filter", "/FlateDecode".to_owned())], + &deflate(&page_content(page)), + ); + let annots: Vec = log + .links + .iter() + .filter(|link| link.page == index) + .map(|link| write_link(&mut self.objects, link.rect, &link.uri).text()) + .collect(); + let mut entries = vec![ + ("Type", "/Page".to_owned()), + ("Parent", self.pages.text()), + ("MediaBox", numbers(&[0.0, 0.0, PAGE_WIDTH, PAGE_HEIGHT])), + ("Contents", content.text()), + ("Resources", resources(&self.fonts, &self.images, page)), + ]; + if !annots.is_empty() { + entries.push(("Annots", format!("[{}]", annots.join(" ")))); + } + Some(self.objects.add(dict(&entries).as_bytes())) + } + + /// Closes the file: the pages, the attachment, the page tree, the catalog, the xref. + /// The chunks of the file, with where the attachment stream starts (the self-check + /// scans from there, header in front). + pub fn finish(mut self, log: &DrawLog, envelope: &[u8]) -> Finished { + let mut kids = Vec::with_capacity(log.pages.len()); + for index in 0..log.pages.len() { + if let Some(page) = self.write_page(log, index) { + kids.push(page.text()); + } + } + let (filespec, stream) = write_attachment(&mut self.objects, envelope, &self.date); + let attachment = self.objects.offset_of(stream).unwrap_or(0); + self.objects.set( + self.pages, + dict(&[ + ("Type", "/Pages".to_owned()), + ("Count", kids.len().to_string()), + ("Kids", format!("[{}]", kids.join(" "))), + ]) + .as_bytes(), + ); + let names = dict(&[( + "EmbeddedFiles", + dict(&[( + "Names", + format!("[{} {}]", hex_text(ATTACHMENT_FILENAME), filespec.text()), + )]), + )]); + self.objects.set( + self.catalog, + dict(&[ + ("Type", "/Catalog".to_owned()), + ("Pages", self.pages.text()), + ("Names", names), + ("AF", format!("[{}]", filespec.text())), + ]) + .as_bytes(), + ); + let chunks = self.objects.finish(self.catalog, self.info, attachment); + Finished { + attachment: chunks.attachment, + chunks: chunks.chunks, } } - let filespec = write_attachment(&mut objects, doc); - objects.set( - pages, - dict(&[ - ("Type", "/Pages".to_owned()), - ("Count", kids.len().to_string()), - ("Kids", format!("[{}]", kids.join(" "))), - ]) - .into_bytes(), - ); - let names = dict(&[( - "EmbeddedFiles", - dict(&[( - "Names", - format!("[{} {}]", hex_text(ATTACHMENT_FILENAME), filespec.text()), - )]), - )]); - objects.set( - catalog, - dict(&[ - ("Type", "/Catalog".to_owned()), - ("Pages", pages.text()), - ("Names", names), - ("AF", format!("[{}]", filespec.text())), - ]) - .into_bytes(), - ); - Ok(objects.finish(catalog, info)) +} + +/// A written file: its chunks in order, and where the attachment stream object starts. +pub struct Finished { + pub chunks: Vec>, + /// `(chunk index, offset in the chunk)`. + pub attachment: (usize, usize), +} + +impl Finished { + /// The bytes from the attachment stream object to the end of its chunk, behind the + /// file header: what the reader scans for the self-check (an object never straddles + /// two chunks). + pub fn attachment_scan(&self) -> Vec { + let (index, offset) = self.attachment; + let chunk = self + .chunks + .get(index) + .and_then(|chunk| chunk.get(offset..)) + .unwrap_or(&[]); + let mut scan = Vec::with_capacity(super::objects::header().len() + chunk.len()); + scan.extend_from_slice(super::objects::header()); + scan.extend_from_slice(chunk); + scan + } + + /// The whole file in one buffer (the one-shot export, the tools, the suites). + pub fn concat(self) -> Vec { + let mut out = Vec::with_capacity(self.chunks.iter().map(Vec::len).sum()); + for chunk in self.chunks { + out.extend_from_slice(&chunk); + } + out + } +} + +impl ImageSink for Writer { + fn embed(&mut self, png: &[u8]) -> Option { + let (image, width, height) = write_image(&mut self.objects, png)?; + self.images.push(image); + Some(Image { + embed: self.images.len() - 1, + width, + height, + }) + } } diff --git a/crates/core/src/pdf/write/session.rs b/crates/core/src/pdf/write/session.rs new file mode 100644 index 00000000..14c0ba86 --- /dev/null +++ b/crates/core/src/pdf/write/session.rs @@ -0,0 +1,490 @@ +//! The incremental export (R4.6, plan §B.1.4, OD-2): the driver opens a session on the +//! checked input, then alternates `next()` (the rasters the next step needs: the SVG logos, +//! then the views of each observation in turn) with `add_raster` or `raster_failed` per +//! key, and closes with `finish()`. A view raster is decoded and written into the file the +//! moment it arrives, so the memory held is the file being written plus one decode; the +//! few logo rasters wait for their batch so that the branding embeds in slot order, as the +//! TypeScript did. Refusals are closed kinds, never a trap: `unknown_key`, `duplicate_key`, +//! `out_of_order`. +//! +//! Buffers and their lives: the input JSON is parsed once into [`CheckedInput`] (report, +//! snapshot, sanitised asset trees), owned by the session; the envelope text is built at +//! `new()` and kept until the self-check; the [`Writer`] holds the file as one buffer, the +//! only copy of the image streams; a PNG given to `add_raster` is borrowed for the call +//! (decoded planes freed before it returns); `finish()` closes the file, whose chunks +//! `take_part()` then moves out one by one (a `Blob` takes parts: the file is never held +//! twice). Dropping the session, finished or not, frees everything it holds. + +use std::collections::HashMap; +use std::mem::take; + +use serde::Serialize; +#[cfg(feature = "ts")] +use ts_rs::TS; + +use super::draw_log::DrawLog; +use super::export::{envelope_text, self_check}; +use super::input::{ + CheckedInput, ExportError, ExportInput, ExportWarning, LogoSlot, Rasters, check_input, +}; +use super::layout::observation::observation_view_ids; +use super::layout::{BrandingImages, Image, ImageSink, Layout, LogoRasters, ViewImage}; +use super::serialize::{Metadata, Writer, export_date}; +use super::views::{RasterRequest, logo_key, logo_request, view_key, view_request}; + +/// What `next()` answers. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(tag = "step", rename_all = "snake_case")] +pub enum ExportStep { + /// The rasters of the current batch; every key answered before the next call. + Rasters { requests: Vec }, + /// Every page is laid out: `finish()`. + Done, +} + +/// A call the state machine refuses (closed kinds). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "snake_case")] +pub enum SessionRefusal { + /// The key is not in the current batch. + UnknownKey, + /// The key was answered already. + DuplicateKey, + /// `next()` with keys unanswered, `finish()` before `done`, any call after `finish()`. + OutOfOrder, +} + +impl SessionRefusal { + pub fn as_str(self) -> &'static str { + match self { + Self::UnknownKey => "unknown_key", + Self::DuplicateKey => "duplicate_key", + Self::OutOfOrder => "out_of_order", + } + } +} + +/// Why a session call failed: a refused call, or an export error. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum SessionError { + Refused(SessionRefusal), + Export(ExportError), +} + +impl SessionError { + pub fn kind(&self) -> &'static str { + match self { + Self::Refused(refusal) => refusal.as_str(), + Self::Export(error) => error.kind.as_str(), + } + } + + pub fn detail(&self) -> &str { + match self { + Self::Refused(_) => "", + Self::Export(error) => &error.detail, + } + } +} + +impl From for SessionError { + fn from(error: ExportError) -> Self { + Self::Export(error) + } +} + +impl From for SessionError { + fn from(refusal: SessionRefusal) -> Self { + Self::Refused(refusal) + } +} + +enum Phase { + Branding, + Observation(usize), + Done, + Finished, +} + +enum Subject { + Logo(LogoSlot), + View(String), +} + +enum Answer { + Awaited, + /// A logo raster, kept until the branding embeds in slot order. + Logo(Vec), + /// A view raster, already decoded and written. + Image(Image), + Failed, +} + +struct Pending { + key: String, + subject: Subject, + answer: Answer, +} + +/// The keys of the current step and their answers. +#[derive(Default)] +struct Batch { + issued: bool, + pending: Vec, +} + +impl Batch { + fn unanswered(&self) -> bool { + self.pending + .iter() + .any(|p| matches!(p.answer, Answer::Awaited)) + } + + fn slot(&mut self, key: &str) -> Result<&mut Pending, SessionRefusal> { + let pending = self + .pending + .iter_mut() + .find(|p| p.key == key) + .ok_or(SessionRefusal::UnknownKey)?; + if !matches!(pending.answer, Answer::Awaited) { + return Err(SessionRefusal::DuplicateKey); + } + Ok(pending) + } +} + +pub struct ExportSession { + input: CheckedInput, + envelope: String, + writer: Option, + /// The file's chunks once finished, handed out front to back. + parts: std::collections::VecDeque>, + written: usize, + log: DrawLog, + warnings: Vec, + branding: Option, + phase: Phase, + batch: Batch, +} + +impl ExportSession { + /// Every check of the input, the envelope under its cap, the file opened. + pub fn new(input: ExportInput) -> Result { + let input = check_input(input)?; + let envelope = envelope_text(&input)?; + let date = export_date(&input.exported_at)?; + let labels = input.labels(); + let title = format!( + "{}{}", + labels.pdf_title_suffix_bilan, input.report.animal.name + ); + let writer = Writer::begin(&Metadata { + title: &title, + author: &input.report.practitioner.name, + subject: &labels.pdf_subject, + date: &date, + }); + Ok(Self { + input, + envelope, + writer: Some(writer), + parts: std::collections::VecDeque::new(), + written: 0, + log: DrawLog::default(), + warnings: Vec::new(), + branding: None, + phase: Phase::Branding, + batch: Batch::default(), + }) + } + + /// The warnings recorded so far (complete after `finish()`). + pub fn warnings(&self) -> &[ExportWarning] { + &self.warnings + } + + /// The envelope text the attachment carries. + pub fn envelope(&self) -> &str { + &self.envelope + } + + /// Bytes of the file written so far; the file's size once finished. + pub fn written(&self) -> usize { + self.writer.as_ref().map_or(self.written, Writer::written) + } + + /// The next part of the finished file, moved out; `None` once every part is taken + /// (or before `finish()`). + pub fn take_part(&mut self) -> Option> { + self.parts.pop_front() + } + + /// Parts of the finished file not yet taken. + pub fn parts_left(&self) -> usize { + self.parts.len() + } + + /// Advances: completes the answered batch, then the next batch of requests, or `done`. + pub fn next_step(&mut self) -> Result { + if self.batch.unanswered() { + return Err(SessionRefusal::OutOfOrder.into()); + } + loop { + match self.phase { + Phase::Branding => { + if !self.batch.issued { + let requests = self.issue_branding(); + if !requests.is_empty() { + return Ok(ExportStep::Rasters { requests }); + } + } + self.complete_branding()?; + } + Phase::Observation(k) if k >= self.input.report.observations.len() => { + self.phase = Phase::Done; + } + Phase::Observation(k) => { + if !self.batch.issued { + let requests = self.issue_observation(k); + if !requests.is_empty() { + return Ok(ExportStep::Rasters { requests }); + } + } + self.complete_observation(k)?; + } + Phase::Done => return Ok(ExportStep::Done), + Phase::Finished => return Err(SessionRefusal::OutOfOrder.into()), + } + } + } + + /// The raster of `key`: a view is decoded and written now (a refused PNG is its + /// `view_raster_failed` warning), a logo waits for its batch. + pub fn add_raster(&mut self, key: &str, png: &[u8]) -> Result<(), SessionError> { + let observation_id = self.current_observation_id(); + let Some(writer) = self.writer.as_mut() else { + return Err(SessionRefusal::OutOfOrder.into()); + }; + let pending = self.batch.slot(key)?; + let mut failed = None; + pending.answer = match &pending.subject { + Subject::Logo(_) => Answer::Logo(png.to_vec()), + Subject::View(view_id) => match writer.embed(png) { + Some(image) => Answer::Image(image), + None => { + failed = Some(view_id.clone()); + Answer::Failed + } + }, + }; + if let Some(view_id) = failed { + self.warnings.push(ExportWarning::ViewRasterFailed { + observation_id, + view_id, + }); + } + Ok(()) + } + + /// `key` could not be rasterised: a view is its warning now (rejection order, as the + /// TypeScript recorded them under `Promise.all`), a logo fails at embedding. + pub fn raster_failed(&mut self, key: &str) -> Result<(), SessionError> { + let observation_id = self.current_observation_id(); + if self.writer.is_none() { + return Err(SessionRefusal::OutOfOrder.into()); + } + let pending = self.batch.slot(key)?; + pending.answer = Answer::Failed; + let failed = match &pending.subject { + Subject::View(view_id) => Some(view_id.clone()), + Subject::Logo(_) => None, + }; + if let Some(view_id) = failed { + self.warnings.push(ExportWarning::ViewRasterFailed { + observation_id, + view_id, + }); + } + Ok(()) + } + + /// The conclusion page, the footers, the file, then the self-check; the parts are then + /// taken with `take_part()`. The session is spent afterwards (`warnings()` stays + /// readable). + pub fn finish(&mut self) -> Result<(), SessionError> { + if !matches!(self.phase, Phase::Done) || self.batch.unanswered() { + return Err(SessionRefusal::OutOfOrder.into()); + } + let Some(branding) = self.branding.take() else { + return Err(SessionRefusal::OutOfOrder.into()); + }; + self.phase = Phase::Finished; + self.with_layout(|layout| layout.end(&branding)); + let Some(writer) = self.writer.take() else { + return Err(SessionRefusal::OutOfOrder.into()); + }; + let log = take(&mut self.log); + let finished = writer.finish(&log, self.envelope.as_bytes()); + self_check(&finished.attachment_scan(), &self.envelope)?; + self.written = finished.chunks.iter().map(Vec::len).sum(); + self.parts = finished.chunks.into(); + Ok(()) + } + + fn current_observation_id(&self) -> String { + match self.phase { + Phase::Observation(k) => self + .input + .report + .observations + .get(k) + .map(|o| o.id.clone()) + .unwrap_or_default(), + _ => String::new(), + } + } + + /// Runs one layout phase with the session's log and warnings lent to it. + fn with_layout(&mut self, phase: impl FnOnce(&mut Layout<'_>) -> R) -> Option { + let writer = self.writer.as_mut()?; + let mut layout = Layout { + input: &self.input, + log: take(&mut self.log), + warnings: take(&mut self.warnings), + sink: writer, + }; + let result = phase(&mut layout); + self.log = layout.log; + self.warnings = layout.warnings; + Some(result) + } + + /// The branding step's requests: one per SVG logo, in slot order. + fn issue_branding(&mut self) -> Vec { + let branding = &self.input.branding; + let assets = [ + branding.header_logo.as_ref(), + branding.footer_logo.as_ref(), + branding.powered_by.as_ref().and_then(|c| c.logo.as_ref()), + branding.partner.as_ref().and_then(|c| c.logo.as_ref()), + ]; + let mut requests = Vec::new(); + for (slot, asset) in LogoSlot::ALL.into_iter().zip(assets) { + if let Some(request) = logo_request(slot, asset) { + self.batch.pending.push(Pending { + key: request.key.clone(), + subject: Subject::Logo(slot), + answer: Answer::Awaited, + }); + requests.push(request); + } + } + self.batch.issued = true; + requests + } + + fn complete_branding(&mut self) -> Result<(), SessionError> { + let batch = take(&mut self.batch); + let logo = |slot: LogoSlot| { + batch + .pending + .iter() + .find_map(|p| match (&p.subject, &p.answer) { + (Subject::Logo(s), Answer::Logo(png)) if *s == slot => Some(png.as_slice()), + _ => None, + }) + }; + let rasters = LogoRasters { + header_logo: logo(LogoSlot::HeaderLogo), + footer_logo: logo(LogoSlot::FooterLogo), + powered_by: logo(LogoSlot::PoweredBy), + partner: logo(LogoSlot::Partner), + }; + let branding = self + .with_layout(|layout| layout.begin(&rasters)) + .ok_or(SessionRefusal::OutOfOrder)??; + self.branding = Some(branding); + self.phase = Phase::Observation(0); + Ok(()) + } + + /// Observation `k`'s requests, main view first; a view that cannot be composed is its + /// warning now (the TypeScript threw before any raster), as `renderHighlightedView` did. + fn issue_observation(&mut self, k: usize) -> Vec { + let Some(observation) = self.input.report.observations.get(k) else { + return Vec::new(); + }; + let sheet = self.input.index.over(&self.input.snapshot.document); + let view_ids: Vec = observation_view_ids(&sheet, observation) + .into_iter() + .map(str::to_owned) + .collect(); + let mut requests = Vec::new(); + for view_id in view_ids { + match view_request(&self.input, observation, &view_id) { + Some(request) => { + self.batch.pending.push(Pending { + key: request.key.clone(), + subject: Subject::View(view_id), + answer: Answer::Awaited, + }); + requests.push(request); + } + None => self.warnings.push(ExportWarning::ViewRasterFailed { + observation_id: observation.id.clone(), + view_id, + }), + } + } + self.batch.issued = true; + requests + } + + fn complete_observation(&mut self, k: usize) -> Result<(), SessionError> { + let batch = take(&mut self.batch); + let images: Vec = batch + .pending + .into_iter() + .filter_map(|p| match (p.subject, p.answer) { + (Subject::View(view_id), Answer::Image(image)) => { + Some(ViewImage { view_id, image }) + } + _ => None, + }) + .collect(); + let Some(branding) = self.branding.clone() else { + return Err(SessionRefusal::OutOfOrder.into()); + }; + self.with_layout(|layout| { + let input = layout.input; + if let Some(observation) = input.report.observations.get(k) { + layout.observation_page(&branding, k, observation, &images); + } + }) + .ok_or(SessionRefusal::OutOfOrder)?; + self.phase = Phase::Observation(k + 1); + Ok(()) + } +} + +/// The rasters of a one-shot export, by request key. +pub fn keyed(rasters: &Rasters) -> HashMap { + let mut map: HashMap = HashMap::new(); + let slots = [ + (LogoSlot::HeaderLogo, &rasters.header_logo), + (LogoSlot::FooterLogo, &rasters.footer_logo), + (LogoSlot::PoweredBy, &rasters.powered_by), + (LogoSlot::Partner, &rasters.partner), + ]; + for (slot, png) in slots { + if let Some(png) = png { + map.insert(logo_key(slot), png.as_slice()); + } + } + for ((observation_id, view_id), png) in &rasters.views { + map.insert(view_key(observation_id, view_id), png.as_slice()); + } + map +} diff --git a/crates/core/src/pdf/write/views.rs b/crates/core/src/pdf/write/views.rs new file mode 100644 index 00000000..2307c311 --- /dev/null +++ b/crates/core/src/pdf/write/views.rs @@ -0,0 +1,157 @@ +//! What the session asks the browser to rasterise (R4.6, plan §B.1.1 `views.rs`): the +//! picture of one view of an observation (`renderHighlightedView` of `svg/view.ts`: the +//! snapshot's drawing, sanitised, framed on the view, the observation's zones highlighted, +//! the halo on the main view) and a branding SVG made safe (`renderBrandingSvg`), each with +//! the pixel size today's rule gives: width 1200 px and the view box aspect, clamped. + +use std::collections::HashSet; + +use serde::Serialize; +#[cfg(feature = "ts")] +use ts_rs::TS; + +use super::input::{CheckedInput, LogoSlot}; +use crate::anatomy::compose::compose_highlight; +use crate::anatomy::svg::number::js_number_of; +use crate::anatomy::svg::{Element, serialize::serialize}; +use crate::domain::archive::{ImageAsset, SheetSnapshotAsset}; +use crate::domain::report::Observation; + +pub const RASTER_WIDTH_PX: u32 = 1200; +const ASPECT_MIN: f64 = 0.2; +const ASPECT_MAX: f64 = 2.0; +const ASPECT_FALLBACK: f64 = 0.6; + +/// One raster the driver owes the session: the SVG text to draw and its pixel size. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "camelCase")] +pub struct RasterRequest { + /// `logo:` or `view::`; answered once. + pub key: String, + pub svg: String, + pub width_px: u32, + pub height_px: u32, +} + +/// A usable dimension: finite and strictly positive (`1e999` parses to Infinity). +fn positive_finite(value: f64) -> bool { + value.is_finite() && value > 0.0 +} + +/// `split(/[\s,]+/)` on the trimmed value: JS `\s` and the comma, runs merged, a leading +/// or trailing separator leaving an empty part. +fn view_box_parts(view_box: &str) -> Vec<&str> { + let trimmed = view_box.trim_matches(is_js_space); + let mut parts = Vec::new(); + let mut rest = trimmed; + loop { + match rest.find(|c: char| is_js_space(c) || c == ',') { + None => { + parts.push(rest); + return parts; + } + Some(at) => { + parts.push(&rest[..at]); + rest = rest[at..].trim_start_matches(|c: char| is_js_space(c) || c == ','); + } + } + } +} + +fn is_js_space(c: char) -> bool { + super::text::is_js_whitespace(c) +} + +/// Height over width of a `viewBox` value, or the fallback when unusable. +fn aspect_of(view_box: Option<&str>) -> f64 { + let parts = view_box_parts(view_box.unwrap_or("")); + if parts.len() != 4 { + return ASPECT_FALLBACK; + } + let width = js_number_of(parts[2]); + let height = js_number_of(parts[3]); + if !positive_finite(width) || !positive_finite(height) { + return ASPECT_FALLBACK; + } + height / width +} + +/// `rasterSizeOf`: `(widthPx, heightPx)`, the height rounded as `Math.round` does. +pub fn raster_size_of(view_box: Option<&str>) -> (u32, u32) { + let aspect = ASPECT_MAX.min(ASPECT_MIN.max(aspect_of(view_box))); + let height = (f64::from(RASTER_WIDTH_PX) * aspect + 0.5).floor().max(1.0); + (RASTER_WIDTH_PX, height as u32) +} + +pub fn logo_key(slot: LogoSlot) -> String { + format!("logo:{}", slot.as_str()) +} + +pub fn view_key(observation_id: &str, view_id: &str) -> String { + format!("view:{observation_id}:{view_id}") +} + +fn request(key: String, root: &Element) -> RasterRequest { + let (width_px, height_px) = raster_size_of(root.attr("viewBox")); + RasterRequest { + key, + svg: serialize(root), + width_px, + height_px, + } +} + +/// `renderBrandingSvg`: the sanitised logo at the size its own viewBox gives; `None` for +/// a PNG asset or an absent one (they need no raster) or an SVG the reader refuses (the +/// slot then fails at embedding, as today). +pub fn logo_request(slot: LogoSlot, asset: Option<&ImageAsset>) -> Option { + match asset? { + ImageAsset::Png(_) => None, + ImageAsset::Svg(svg) => { + let root = crate::anatomy::svg::read_svg(&svg.svg).ok()?.root; + Some(request(logo_key(slot), &root)) + } + } +} + +/// The asset a view draws: its own, else the first up its parent chain (`assetIdOfView`), +/// then the first snapshot asset of that id (`assetText`). +fn asset_of_view<'a>(input: &'a CheckedInput, view_id: &str) -> Option<&'a SheetSnapshotAsset> { + let asset_id = crate::anatomy::compose::asset_id_of_view(&input.snapshot.document, view_id)?; + input + .snapshot + .assets + .iter() + .find(|asset| asset.svg_asset_id == asset_id) +} + +/// `renderHighlightedView`: the view's drawing with the observation's zones of that view +/// highlighted; `None` where the TypeScript threw (unknown view, no asset, a drawing the +/// reader refuses, a composition the layer refuses), which the caller records as +/// `view_raster_failed`. +pub fn view_request( + input: &CheckedInput, + observation: &Observation, + view_id: &str, +) -> Option { + let sheet = input.index.over(&input.snapshot.document); + let view = sheet.view(view_id)?; + let ids: HashSet<&str> = observation + .zones + .iter() + .filter(|zone| zone.view_id == view_id) + .map(|zone| zone.annotation_id.as_str()) + .collect(); + let asset = asset_of_view(input, view_id)?; + let root = input.sanitised_asset(&asset.svg_asset_id)?.clone(); + let composed = compose_highlight( + &input.snapshot.document, + view_id, + root, + &ids, + view.is_main(), + ) + .ok()?; + Some(request(view_key(&observation.id, view_id), &composed)) +} diff --git a/crates/core/tests/common/r4.rs b/crates/core/tests/common/r4.rs index dbdae274..ddcdb2dc 100644 --- a/crates/core/tests/common/r4.rs +++ b/crates/core/tests/common/r4.rs @@ -95,3 +95,22 @@ fn expand_parts(parts: &[Value], dir: &std::path::Path) -> Vec { pub fn latin1_bytes(text: &str) -> Vec { text.chars().map(|c| u32::from(c) as u8).collect() } + +/// An [`ImageSink`] for the layout oracles: keeps every PNG given, sized from its header, +/// so the O1 `pngSha256` per embed index can be checked without a PDF writer. +#[derive(Default)] +pub struct PngKeeper { + pub pngs: Vec>, +} + +impl faunosteo_core::pdf::write::layout::ImageSink for PngKeeper { + fn embed(&mut self, png: &[u8]) -> Option { + let (width, height) = faunosteo_core::pdf::write::layout::png::dimensions(png)?; + self.pngs.push(png.to_vec()); + Some(faunosteo_core::pdf::write::layout::Image { + embed: self.pngs.len() - 1, + width, + height, + }) + } +} diff --git a/crates/core/tests/pdf_layout.rs b/crates/core/tests/pdf_layout.rs index 7377a557..b8c1106f 100644 --- a/crates/core/tests/pdf_layout.rs +++ b/crates/core/tests/pdf_layout.rs @@ -10,11 +10,11 @@ mod common; -use common::r4::{repo_root, sha256_hex}; +use common::r4::{PngKeeper, repo_root, sha256_hex}; use faunosteo_core::domain::archive::Locale; use faunosteo_core::domain::js::parse_json; use faunosteo_core::pdf::read::probe::{ProbeLimits, read_attached_document}; -use faunosteo_core::pdf::write::draw_log::{DrawLog, DrawOp}; +use faunosteo_core::pdf::write::draw_log::DrawOp; use faunosteo_core::pdf::write::input::{ExportInput, Rasters, check_input}; use faunosteo_core::pdf::write::layout::layout; use serde_json::{Value, json}; @@ -96,12 +96,12 @@ fn color(c: &faunosteo_core::pdf::write::draw_log::Rgb) -> Value { } /// One op in the oracle's shape (without `seq`). -fn op_json(op: &DrawOp, log: &DrawLog) -> Value { +fn op_json(op: &DrawOp, pngs: &[Vec]) -> Value { match op { DrawOp::Text(t) => json!({ "op": "drawText", "text": t.text, "options": { "x": t.x, "y": t.y, "size": t.size, "font": t.font.as_str(), "color": color(&t.color) } }), DrawOp::Image(i) => json!({ "op": "drawImage", - "image": { "embedIndex": i.embed, "pngSha256": sha256_hex(&log.embeds[i.embed].png) }, + "image": { "embedIndex": i.embed, "pngSha256": sha256_hex(&pngs[i.embed]) }, "options": { "x": i.x, "y": i.y, "width": i.width, "height": i.height } }), DrawOp::Line(l) => json!({ "op": "drawLine", "options": { "start": { "x": l.start.x, "y": l.start.y }, "end": { "x": l.end.x, "y": l.end.y }, @@ -153,7 +153,8 @@ fn compare_run(report: &str, locale: &str, mode: &str, mismatches: &mut Vec = drawn - .log - .embeds + let embeds: Vec = keeper + .pngs .iter() .enumerate() - .map(|(i, e)| json!({ "embedIndex": i, "pngSha256": sha256_hex(&e.png) })) + .map(|(i, png)| json!({ "embedIndex": i, "pngSha256": sha256_hex(png) })) .collect(); if !same(&oracle["embeds"], &Value::Array(embeds.clone())) { mismatches.push(format!( @@ -256,7 +256,12 @@ fn step6_text_and_image_goldens_derive_from_the_log() { let name = format!("{report}.{locale}.{mode}"); let input = export_input(report, locale, mode); let rasters = stub_rasters(&input, mode); - let drawn = layout(&check_input(input).unwrap(), &rasters).unwrap(); + let drawn = layout( + &check_input(input).unwrap(), + &rasters, + &mut PngKeeper::default(), + ) + .unwrap(); let text: Value = serde_json::from_str( &std::fs::read_to_string(goldens.join(format!("text.{name}.json"))).unwrap(), ) @@ -328,7 +333,7 @@ fn page_caps_and_missing_rasters_behave_as_export_ts() { let first_key = rasters.views.keys().next().cloned().unwrap(); rasters.views.remove(&first_key); let checked = check_input(input).unwrap(); - let drawn = layout(&checked, &rasters).unwrap(); + let drawn = layout(&checked, &rasters, &mut PngKeeper::default()).unwrap(); assert_eq!( drawn.warnings, vec![ @@ -363,13 +368,14 @@ fn layout_of_the_large_reports_stays_fast() { let checked = check_input(input).unwrap(); let checks_ms = started.elapsed().as_millis(); let started = std::time::Instant::now(); - let drawn = layout(&checked, &rasters).unwrap(); + let mut keeper = PngKeeper::default(); + let drawn = layout(&checked, &rasters, &mut keeper).unwrap(); let layout_ms = started.elapsed().as_millis(); let ops: usize = drawn.log.pages.iter().map(|p| p.ops.len()).sum(); println!( "{name}: {} pages, {ops} ops, {} embeds; checks {checks_ms} ms, layout {layout_ms} ms", drawn.log.pages.len(), - drawn.log.embeds.len() + keeper.pngs.len() ); assert!(layout_ms < cap_ms, "{name}: layout {layout_ms} ms"); } diff --git a/crates/core/tests/pdf_session.rs b/crates/core/tests/pdf_session.rs new file mode 100644 index 00000000..cdb5509f --- /dev/null +++ b/crates/core/tests/pdf_session.rs @@ -0,0 +1,382 @@ +//! R4.6: the incremental export session (plan §B.1.4, OD-2). Source: the TypeScript +//! export's behaviours the session reproduces step by step (`packages/pdf/src/export.ts`, +//! `render/observationPage.ts`, `branding.ts`, `svg/view.ts`): the raster requests (SVG +//! logos, then each observation's views, main first), the warning order (a raster that +//! fails before any embed, then a PNG `embedPng` refused, in view order), the state +//! machine's closed refusals, and the file: driven key by key it is the one `export_pdf` +//! gives (the frozen R4 digests). `rasterSizeOf` against the O4 oracle. +#![allow(clippy::disallowed_methods, clippy::unwrap_used, clippy::expect_used)] + +mod common; + +use std::collections::HashSet; + +use common::r4::{r4_oracle, repo_root, sha256_hex}; +use faunosteo_core::anatomy::compose::{asset_id_of_view, compose_highlight}; +use faunosteo_core::anatomy::svg::{read_svg, serialize::serialize}; +use faunosteo_core::domain::js::parse_json; +use faunosteo_core::pdf::read::probe::{ProbeLimits, read_attached_document}; +use faunosteo_core::pdf::write::export::export_pdf; +use faunosteo_core::pdf::write::input::{ExportInput, ExportWarning, LogoSlot, Rasters}; +use faunosteo_core::pdf::write::session::{ + ExportSession, ExportStep, SessionError, SessionRefusal, keyed, +}; +use faunosteo_core::pdf::write::views::{RASTER_WIDTH_PX, RasterRequest, raster_size_of}; +use serde_json::{Value, json}; + +const TWO_BY_ONE_PNG: &str = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR4nGPYEWX///9/AA0PBE/1T7nxAAAAAElFTkSuQmCC"; + +fn base64(text: &str) -> Vec { + faunosteo_core::pdf::write::layout::png::base64_bytes(text).unwrap() +} + +fn fixture(path: &str) -> Vec { + std::fs::read(repo_root().join("apps/app/tests/fixtures").join(path)).unwrap() +} + +fn demo_input() -> ExportInput { + let pdf = fixture("pdf/r3/demo.fr.logos.pdf"); + let located = read_attached_document(&pdf, ProbeLimits::UNBOUNDED).unwrap(); + let envelope: Value = parse_json(&located.text).unwrap(); + serde_json::from_value(json!({ + "report": envelope["report"], + "sheetSnapshot": envelope["sheetSnapshot"], + "branding": envelope["branding"], + "labels": envelope["labels"], + "locale": envelope["locale"], + "exportedAt": envelope["exportedAt"], + })) + .unwrap() +} + +fn stub_rasters(input: &ExportInput, png: &[u8]) -> Rasters { + let mut rasters = Rasters { + header_logo: Some(png.to_vec()), + footer_logo: Some(png.to_vec()), + powered_by: Some(png.to_vec()), + partner: Some(png.to_vec()), + views: Default::default(), + }; + for observation in &input.report.observations { + for zone in &observation.zones { + rasters + .views + .entry((observation.id.clone(), zone.view_id.clone())) + .or_insert_with(|| png.to_vec()); + } + } + rasters +} + +fn refusal(error: SessionError) -> SessionRefusal { + match error { + SessionError::Refused(refusal) => refusal, + SessionError::Export(error) => panic!("export error {error:?}"), + } +} + +fn requests(step: ExportStep) -> Vec { + match step { + ExportStep::Rasters { requests } => requests, + ExportStep::Done => panic!("done too early"), + } +} + +#[test] +fn raster_size_of_reproduces_the_o4_cases() { + let oracle = r4_oracle("text.json"); + let cases = oracle["rasterSizeOf"]["cases"].as_array().unwrap(); + assert!(cases.len() > 40, "{} cases", cases.len()); + for case in cases { + let row = case.as_array().unwrap(); + let input = row[0].as_str(); + let expected = ( + row[1].as_u64().unwrap() as u32, + row[2].as_u64().unwrap() as u32, + ); + assert_eq!(raster_size_of(input), expected, "{:?}", row[0]); + } + assert_eq!(raster_size_of(None).0, RASTER_WIDTH_PX); +} + +/// The branding step asks for the SVG logos only (the demo branding: the partner), each +/// observation step for its views with the main view first; every request's SVG is the +/// R3 composition of that view and its size the composed root's viewBox rule. +#[test] +fn the_requests_are_the_svg_logos_then_each_observations_views_main_first() { + let input = demo_input(); + let report = input.report.clone(); + let snapshot: faunosteo_core::domain::archive::SheetSnapshot = + serde_json::from_value(input.sheet_snapshot.clone()).unwrap(); + let mut session = ExportSession::new(input).unwrap(); + let branding = requests(session.next_step().unwrap()); + assert_eq!( + branding.iter().map(|r| r.key.as_str()).collect::>(), + vec!["logo:partner"] + ); + assert!(branding[0].svg.starts_with(" = seen + .iter() + .filter(|id| **id == main) + .chain(seen.iter().filter(|id| **id != main)) + .map(|id| format!("view:{}:{id}", observation.id)) + .collect(); + assert_eq!( + batch.iter().map(|r| r.key.clone()).collect::>(), + expected_order, + "{}", + observation.id + ); + for request in &batch { + let view_id = request.key.rsplit(':').next().unwrap(); + let ids: HashSet<&str> = observation + .zones + .iter() + .filter(|z| z.view_id == view_id) + .map(|z| z.annotation_id.as_str()) + .collect(); + let asset_id = asset_id_of_view(document, view_id).unwrap(); + let asset = snapshot + .assets + .iter() + .find(|a| a.svg_asset_id == asset_id) + .unwrap(); + let root = read_svg(&asset.svg).unwrap().root; + let composed = + compose_highlight(document, view_id, root, &ids, view_id == main).unwrap(); + assert_eq!(request.svg, serialize(&composed), "{}", request.key); + assert_eq!( + (request.width_px, request.height_px), + raster_size_of(composed.attr("viewBox")), + "{}", + request.key + ); + session + .add_raster(&request.key, &base64(TWO_BY_ONE_PNG)) + .unwrap(); + } + } + assert_eq!(session.next_step().unwrap(), ExportStep::Done); + session.finish().unwrap(); + let pdf = session.take_part().unwrap(); + assert!(pdf.starts_with(b"%PDF-1.7")); + assert!(session.warnings().is_empty()); +} + +/// Driven key by key, the session writes the bytes `export_pdf` writes (the frozen digest), +/// and the file grows as the rasters arrive (nothing waits for `finish`). +#[test] +fn the_session_gives_the_one_shot_bytes_and_grows_as_rasters_arrive() { + let input = demo_input(); + let rasters = stub_rasters(&input, &base64(TWO_BY_ONE_PNG)); + let one_shot = export_pdf(input.clone(), &rasters).unwrap(); + let frozen = std::fs::read_to_string( + repo_root().join("apps/app/tests/fixtures/goldens/r4/pdf.demo.fr.logos.sha256"), + ) + .unwrap(); + assert_eq!(sha256_hex(&one_shot.pdf), frozen.trim()); + let map = keyed(&rasters); + let mut session = ExportSession::new(input).unwrap(); + let opened = session.written(); + assert!(opened > 0); + let mut grew_during_batches = false; + while let ExportStep::Rasters { requests } = session.next_step().unwrap() { + for request in requests { + let before = session.written(); + session.add_raster(&request.key, map[&request.key]).unwrap(); + if request.key.starts_with("view:") { + assert!(session.written() > before, "{}", request.key); + grew_during_batches = true; + } + } + } + assert!(grew_during_batches); + session.finish().unwrap(); + // The parts, each under a few MiB with the stub rasters, moved out one by one. + let parts = session.parts_left(); + assert!(parts >= 1); + let mut pdf = Vec::new(); + while let Some(part) = session.take_part() { + assert!(!part.is_empty()); + pdf.extend_from_slice(&part); + } + assert_eq!(session.take_part(), None); + assert_eq!(session.written(), pdf.len()); + assert_eq!(pdf, one_shot.pdf); + assert_eq!(session.envelope(), one_shot.envelope); + assert_eq!(session.warnings(), one_shot.warnings.as_slice()); +} + +#[test] +fn the_state_machine_refuses_with_closed_kinds_and_never_traps() { + let input = demo_input(); + let png = base64(TWO_BY_ONE_PNG); + let mut session = ExportSession::new(input).unwrap(); + assert_eq!( + refusal(session.add_raster("logo:partner", &png).unwrap_err()), + SessionRefusal::UnknownKey, + "before the first next()" + ); + assert_eq!( + refusal(session.finish().unwrap_err()), + SessionRefusal::OutOfOrder + ); + let branding = requests(session.next_step().unwrap()); + assert_eq!( + refusal(session.next_step().unwrap_err()), + SessionRefusal::OutOfOrder, + "next() with a key unanswered" + ); + assert_eq!( + refusal(session.add_raster("logo:headerLogo", &png).unwrap_err()), + SessionRefusal::UnknownKey + ); + assert_eq!( + refusal(session.add_raster("view:x:y", &png).unwrap_err()), + SessionRefusal::UnknownKey + ); + session.add_raster(&branding[0].key, &png).unwrap(); + assert_eq!( + refusal(session.add_raster(&branding[0].key, &png).unwrap_err()), + SessionRefusal::DuplicateKey + ); + assert_eq!( + refusal(session.raster_failed(&branding[0].key).unwrap_err()), + SessionRefusal::DuplicateKey + ); + while let ExportStep::Rasters { requests } = session.next_step().unwrap() { + for request in requests { + // Garbage, an empty slice and a truncated PNG: a warning each, never a trap. + let bytes: &[u8] = match request.key.len() % 3 { + 0 => b"not a png", + 1 => b"", + _ => &png[..20], + }; + session.add_raster(&request.key, bytes).unwrap(); + } + } + assert_eq!(session.next_step().unwrap(), ExportStep::Done); + session.finish().unwrap(); + assert!(session.take_part().unwrap().starts_with(b"%PDF-1.7")); + assert_eq!( + refusal(session.finish().unwrap_err()), + SessionRefusal::OutOfOrder, + "a second finish()" + ); + assert_eq!( + refusal(session.next_step().unwrap_err()), + SessionRefusal::OutOfOrder + ); + assert_eq!( + refusal(session.add_raster("logo:partner", &png).unwrap_err()), + SessionRefusal::OutOfOrder + ); + let views: usize = session + .warnings() + .iter() + .filter(|w| matches!(w, ExportWarning::ViewRasterFailed { .. })) + .count(); + assert!(views > 0); +} + +/// The warning order of the TypeScript: for an observation, the rasters that failed +/// (`raster_failed`, in the order the driver reports them) come before the PNGs the +/// decoder refused (in view order, as `embedPng` ran); a logo warning sits where its slot +/// embeds, whatever the order its raster arrived in. +#[test] +fn warnings_keep_the_typescript_order() { + let input = demo_input(); + let png = base64(TWO_BY_ONE_PNG); + let two_views = input + .report + .observations + .iter() + .find(|o| { + o.zones + .iter() + .map(|z| &z.view_id) + .collect::>() + .len() + >= 2 + }) + .map(|o| o.id.clone()) + .expect("an observation with two views"); + let mut session = ExportSession::new(input).unwrap(); + let branding = requests(session.next_step().unwrap()); + session.raster_failed(&branding[0].key).unwrap(); + let mut expected = vec![ExportWarning::LogoFailed { + slot: LogoSlot::Partner, + }]; + while let ExportStep::Rasters { requests } = session.next_step().unwrap() { + let key_of = |r: &RasterRequest| r.key.clone(); + let observation_id = requests[0].key.split(':').nth(1).unwrap().to_owned(); + let view_of = |r: &RasterRequest| r.key.rsplit(':').next().unwrap().to_owned(); + if observation_id == two_views { + // The driver reports the second view's failure first (it rejected first), then + // answers the batch in request order with a PNG the decoder refuses. + session.raster_failed(&key_of(&requests[1])).unwrap(); + expected.push(ExportWarning::ViewRasterFailed { + observation_id: observation_id.clone(), + view_id: view_of(&requests[1]), + }); + session.add_raster(&key_of(&requests[0]), b"bad").unwrap(); + expected.push(ExportWarning::ViewRasterFailed { + observation_id: observation_id.clone(), + view_id: view_of(&requests[0]), + }); + for request in &requests[2..] { + session.add_raster(&key_of(request), &png).unwrap(); + } + } else { + for request in &requests { + session.add_raster(&key_of(request), &png).unwrap(); + } + } + } + session.finish().unwrap(); + assert_eq!(session.warnings(), expected.as_slice()); +} + +/// `export_pdf` answers the session from its map: an absent view is `raster_failed`, an +/// absent SVG logo too (its slot warns), a PNG asset logo never asks for a raster. +#[test] +fn the_one_shot_driver_reports_absent_rasters_as_failed() { + let input = demo_input(); + let png = base64(TWO_BY_ONE_PNG); + let mut rasters = stub_rasters(&input, &png); + rasters.partner = None; + rasters.header_logo = None; + let first = rasters.views.keys().min().cloned().unwrap(); + rasters.views.remove(&first); + let result = export_pdf(input, &rasters).unwrap(); + assert_eq!( + result.warnings, + vec![ + ExportWarning::LogoFailed { + slot: LogoSlot::Partner + }, + ExportWarning::ViewRasterFailed { + observation_id: first.0, + view_id: first.1, + }, + ] + ); +} diff --git a/crates/wasm/src/lib.rs b/crates/wasm/src/lib.rs index 6f4cb544..05651039 100644 --- a/crates/wasm/src/lib.rs +++ b/crates/wasm/src/lib.rs @@ -63,6 +63,70 @@ impl SheetHandle { } } +/// The incremental PDF export (R4.6, plan §B.1.4, OD-2): the application opens a session on +/// its `ExportInput` JSON, then alternates `next()` (the rasters the next step needs) with +/// `add_raster` or `raster_failed` per key, and closes with `finish()`. Every answer is the +/// outcome envelope of the calls; a view raster is decoded and written into the file as it +/// arrives (its bytes are copied into linear memory for the call by the glue, and freed +/// with the decode before the call returns), so the session holds the file being written +/// and nothing of the rasters. `free()` (the driver's `finally`) drops everything it holds. +#[wasm_bindgen] +pub struct ExportSession { + inner: faunosteo_core::pdf::write::session::ExportSession, +} + +#[wasm_bindgen] +impl ExportSession { + /// Every check of the input, the envelope under its cap, the file opened; throws an + /// `Error` worded `: ` with today's export kinds when the input is refused. + #[wasm_bindgen(constructor)] + pub fn new(input: &str) -> Result { + faunosteo_core::facade::export::open(input) + .map(|inner| ExportSession { inner }) + .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) + } + + /// `{"ok":true,"value":}`: the next batch of raster requests, or `done`. + pub fn next_step(&mut self) -> String { + faunosteo_core::facade::export::next_step(&mut self.inner) + } + + /// The raster of `key` (a PNG); `{"ok":true}` or a closed refusal. + pub fn add_raster(&mut self, key: &str, png: &[u8]) -> String { + faunosteo_core::facade::export::add_raster(&mut self.inner, key, png) + } + + /// `key` could not be rasterised (its warning); `{"ok":true}` or a closed refusal. + pub fn raster_failed(&mut self, key: &str) -> String { + faunosteo_core::facade::export::raster_failed(&mut self.inner, key) + } + + /// Closes the file: the number of parts `take_part()` then gives; throws an `Error` + /// worded `: ` (`out_of_order`, `self_check_failed`). + pub fn finish(&mut self) -> Result { + faunosteo_core::facade::export::finish(&mut self.inner) + .map(|parts| u32::try_from(parts).unwrap_or(u32::MAX)) + .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) + } + + /// The next part of the finished file, front to back, `undefined` once every part is + /// out. Each part is copied out of linear memory by the glue and freed here, so the + /// file is never held twice (`new Blob(parts)` takes them as they are). + pub fn take_part(&mut self) -> Option> { + self.inner.take_part() + } + + /// `{"ok":true,"value":[…]}`, complete after `finish()`. + pub fn warnings(&self) -> String { + faunosteo_core::facade::export::warnings(&self.inner) + } + + /// Bytes of the file written so far (DEV diagnostics only). + pub fn written(&self) -> u32 { + u32::try_from(self.inner.written()).unwrap_or(u32::MAX) + } +} + /// A file's bytes gathered chunk by chunk in the module's memory (R4.3a): the worker reads /// `file.stream()` and pushes each chunk, so the only whole copy of the file is this one. /// The capacity is reserved up front from the file size the worker announces, capped at the diff --git a/packages/core-wasm/src/export.ts b/packages/core-wasm/src/export.ts new file mode 100644 index 00000000..0215882d --- /dev/null +++ b/packages/core-wasm/src/export.ts @@ -0,0 +1,152 @@ +import type { ExportStep, ExportWarning } from '../types' +import { CORE_UNAVAILABLE, failure, parseOutcome, type CoreOutcome } from './outcome' +import { + closedRefusal, + type CoreRuntime, + type GlueExportSession, + type GlueModule, +} from './runtime' + +/** + * The incremental PDF export (R4.6, plan §B.1.4, OD-2) on the page's runtime: every call + * goes through `CoreRuntime.invoke`, so a trap poisons the instance and answers `internal` + * like any core call, and a session opened on an instance the runtime has since dropped + * (a recovery) answers `core_unavailable` without touching the dead handle, as sheet + * handles do. The driver calls `free()` in its `finally`: the module's buffer (the file + * being written) is released whatever the outcome. + */ +export class CoreExportSession { + private handle: GlueExportSession | null + + constructor( + private readonly runtime: CoreRuntime, + handle: GlueExportSession, + private readonly generation: number, + ) { + this.handle = handle + } + + /** The next batch of raster requests, or `done`. */ + next(): CoreOutcome { + return this.call((handle) => parseOutcome(handle.next_step())) + } + + /** The PNG of `key`: `null` on success, else a closed refusal. */ + addRaster(key: string, png: Uint8Array): CoreOutcome { + return this.call((handle) => + parseOutcome(handle.add_raster(key, png)), + ) + } + + /** `key` could not be rasterised (the session records the warning). */ + rasterFailed(key: string): CoreOutcome { + return this.call((handle) => parseOutcome(handle.raster_failed(key))) + } + + /** + * The file, as the parts the module hands out one by one (each copied out of linear + * memory and freed there, so the file is never held twice; `new Blob(parts)` takes them + * as they are). The module throws a closed `Error` worded `: ` for + * `out_of_order` or `self_check_failed`; anything else is a trap. + */ + finish(): CoreOutcome { + return this.call((handle) => { + let count: number + try { + count = handle.finish() + } catch (error) { + const refusal = closedRefusal(error) + if (refusal === null) throw error + return closedFailure(refusal) + } + const parts: Uint8Array[] = [] + for (let i = 0; i < count; i += 1) { + const part = handle.take_part() + if (!part) break + parts.push(part) + } + return { ok: true, value: parts } + }) + } + + /** The warnings recorded so far (complete after `finish()`). */ + warnings(): CoreOutcome { + return this.call((handle) => + parseOutcome(handle.warnings()), + ) + } + + /** Bytes of the file written so far (DEV diagnostics). */ + written(): number { + const outcome = this.call((handle) => ({ + ok: true as const, + value: handle.written(), + })) + return outcome.ok ? outcome.value : 0 + } + + /** + * Releases the module's buffer. Safe to call twice; a handle of a dropped instance is + * never touched (its memory went with the instance). + */ + free(): void { + const handle = this.handle + this.handle = null + if (!handle || !this.live()) return + try { + handle.free() + } catch { + // The glue refuses a double free; nothing else to do. + } + } + + private live(): boolean { + return ( + this.runtime.generation === this.generation && + this.runtime.status === 'ready' + ) + } + + private call(fn: (handle: GlueExportSession) => CoreOutcome): CoreOutcome { + const handle = this.handle + if (!handle) return failure('out_of_order', 'session freed') + if (!this.live()) { + this.runtime.kickRestart() + return CORE_UNAVAILABLE + } + return this.runtime.invoke(() => fn(handle)) + } +} + +/** `: ` → the failure. */ +function closedFailure(message: string): CoreOutcome { + const colon = message.indexOf(': ') + return colon < 0 + ? failure(message) + : failure(message.slice(0, colon), message.slice(colon + 2)) +} + +/** + * Opens a session on the live instance: the module's checks refuse the input with today's + * export kinds (`branding_invalid`, `snapshot_invalid`, `snapshot_too_large`, + * `sheet_mismatch`, `too_many_pages`, `invalid_input`), a trap poisons the instance. + */ +export function openExportSession( + runtime: CoreRuntime, + inputJson: string, +): CoreOutcome { + return runtime.invoke((glue: GlueModule) => { + let handle: GlueExportSession + try { + handle = new glue.ExportSession(inputJson) + } catch (error) { + const refusal = closedRefusal(error) + if (refusal === null) throw error + return closedFailure(refusal) + } + return { + ok: true, + value: new CoreExportSession(runtime, handle, runtime.generation), + } + }) +} diff --git a/packages/core-wasm/src/index.ts b/packages/core-wasm/src/index.ts index c4a371b4..43ec13fa 100644 --- a/packages/core-wasm/src/index.ts +++ b/packages/core-wasm/src/index.ts @@ -11,10 +11,12 @@ export { closedRefusal, type CoreSource, type CoreStatus, + type GlueExportSession, type GlueFileBytes, type GlueModule, type GlueSheetHandle, } from './runtime' +export { CoreExportSession, openExportSession } from './export' export { CORE_UNAVAILABLE, parseOutcome, diff --git a/packages/core-wasm/src/runtime.ts b/packages/core-wasm/src/runtime.ts index 03c42ef3..00acb060 100644 --- a/packages/core-wasm/src/runtime.ts +++ b/packages/core-wasm/src/runtime.ts @@ -24,6 +24,22 @@ export interface GlueModule { call(op: string, input: string): string SheetHandle: new (bundle: string) => GlueSheetHandle FileBytes: new (expected: number) => GlueFileBytes + /** R4.6: the incremental export; the constructor throws `: ` on a refused input. */ + ExportSession: new (inputJson: string) => GlueExportSession +} + +/** The export session of the module (crates/wasm `ExportSession`): outcome envelopes out. */ +export interface GlueExportSession { + next_step(): string + add_raster(key: string, png: Uint8Array): string + raster_failed(key: string): string + /** Throws `: ` (`out_of_order`, `self_check_failed`); the parts count otherwise. */ + finish(): number + /** The next part of the finished file (copied out, freed in the module), `undefined` at the end. */ + take_part(): Uint8Array | undefined + warnings(): string + written(): number + free(): void } export interface GlueSheetHandle { diff --git a/packages/core-wasm/tests/pdf-export.session.test.ts b/packages/core-wasm/tests/pdf-export.session.test.ts new file mode 100644 index 00000000..f7f64355 --- /dev/null +++ b/packages/core-wasm/tests/pdf-export.session.test.ts @@ -0,0 +1,392 @@ +/** + * R4.6: the export session through the shipped module and the runtime wrapper + * (`CoreExportSession`): driven request by request on the O2 runs it writes the native + * bytes (`goldens/r4/pdf.*.sha256`); every view it asks for is the SVG the TypeScript + * engine composes (`composeHighlightedViewSvg`) and, on the real-raster run, the digests + * and sizes the R4.1 rasteriser recorded (`pdf/r3/real/manifest.json`); the refusals are + * closed kinds; a trap mid-session poisons the instance and the session answers + * `core_unavailable` from then on, `free()` included; the memory held by a fresh instance + * after an export is printed against the file's size (OD-2, RUST.md §10.8). + */ +import { createHash } from 'node:crypto' +import { readFileSync } from 'node:fs' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { composeHighlightedViewSvg } from '@faunosteo/pdf' + +import { + CoreRuntime, + openExportSession, + type CoreExportSession, + type GlueModule, +} from '../src/index' +import { nodeCoreRuntime, nodeCoreSource, type ProofModule } from '../src/node' +import type { ExportStep, ExportWarning } from '../types' +import { readAttachedDocument } from './n-1/scanner/attachment/read' + +const ROOT = fileURLToPath(new URL('../../../', import.meta.url)) +const FIXTURES = join(ROOT, 'apps/app/tests/fixtures') +const sha256 = (data: Uint8Array | string) => + createHash('sha256').update(data).digest('hex') +const ONE_PX_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', + 'base64', +) +const TWO_BY_ONE_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR4nGPYEWX///9/AA0PBE/1T7nxAAAAAElFTkSuQmCC', + 'base64', +) + +interface Envelope { + report: { + observations: Array<{ + id: string + zones: Array<{ viewId: string; annotationId: string }> + }> + } + sheetSnapshot: unknown + branding: unknown + labels: unknown + locale: string + exportedAt: string +} + +interface Run { + name: string + r3: string + report?: string + /** The PNG of a request key, or `null` for a raster that fails. */ + raster: (key: string) => Uint8Array | null +} + +const RUNS: Run[] = [] +for (const report of ['demo', 'v2full', 'v2unresolved']) { + for (const locale of ['fr', 'en']) { + for (const mode of ['nologos', 'logos']) { + const png = mode === 'logos' ? TWO_BY_ONE_PNG : ONE_PX_PNG + RUNS.push({ + name: `${report}.${locale}.${mode}`, + r3: `pdf/r3/${report}.${locale}.${mode}.pdf`, + raster: () => new Uint8Array(png), + }) + } + } +} +RUNS.push({ + name: 'real.v2full-obs1.fr.logos', + r3: 'pdf/r3/real/v2full-obs1.fr.logos.pdf', + raster: (key) => + new Uint8Array( + readFileSync( + join( + FIXTURES, + 'pdf/r3/real', + key === 'logo:partner' ? 'raster-0.png' : 'raster-1.png', + ), + ), + ), +}) +RUNS.push({ + name: 'store-path.fr.nologos', + r3: 'pdf/r3/store-path.fr.nologos.pdf', + report: 'pdf/r3/store-path.report.json', + raster: () => new Uint8Array(ONE_PX_PNG), +}) + +async function envelopeOf(path: string): Promise { + const pdf = new Uint8Array(readFileSync(join(FIXTURES, path))) + return (await readAttachedDocument(pdf)) as Envelope +} + +function inputOf(envelope: Envelope, reportOverride?: string): string { + const report = reportOverride + ? JSON.parse(readFileSync(join(FIXTURES, reportOverride), 'utf8')) + : envelope.report + return JSON.stringify({ + report, + sheetSnapshot: envelope.sheetSnapshot, + branding: envelope.branding, + labels: envelope.labels, + locale: envelope.locale, + exportedAt: envelope.exportedAt, + }) +} + +function unwrap(outcome: { ok: true; value: T } | { ok: false; kind: string; detail?: string }, what: string): T { + if (!outcome.ok) throw new Error(`${what}: ${outcome.kind} ${outcome.detail ?? ''}`) + return outcome.value +} + +interface Driven { + pdf: Uint8Array + parts: number + warnings: ExportWarning[] + requests: Array<{ key: string; svg: string; widthPx: number; heightPx: number }> +} + +/** Drives a session to its file, answering every request from `raster`. */ +function drive(session: CoreExportSession, raster: Run['raster']): Driven { + const requests: Driven['requests'] = [] + for (;;) { + const step = unwrap(session.next(), 'next') + if (step.step === 'done') break + for (const request of step.requests) { + requests.push(request) + const png = raster(request.key) + unwrap( + png ? session.addRaster(request.key, png) : session.rasterFailed(request.key), + request.key, + ) + } + } + const parts = unwrap(session.finish(), 'finish') + const warnings = unwrap(session.warnings(), 'warnings') + return { pdf: Buffer.concat(parts), parts: parts.length, warnings, requests } +} + +describe('R4.6 export session through the shipped module', () => { + it('writes the native bytes on every O2 run, asking for the SVGs the engine composes', async () => { + const runtime = await nodeCoreRuntime('pkg') + for (const run of RUNS) { + const envelope = await envelopeOf(run.r3) + const session = unwrap( + openExportSession(runtime, inputOf(envelope, run.report)), + run.name, + ) + let driven: Driven + try { + driven = drive(session, run.raster) + } finally { + session.free() + } + const expected = readFileSync( + join(FIXTURES, `goldens/r4/pdf.${run.name}.sha256`), + 'utf8', + ).trim() + expect(sha256(driven.pdf), run.name).toBe(expected) + expect(driven.warnings, run.name).toEqual([]) + // Every view request is the TypeScript composition of that view for that observation. + const report = run.report + ? (JSON.parse(readFileSync(join(FIXTURES, run.report), 'utf8')) as Envelope['report']) + : envelope.report + let views = 0 + for (const request of driven.requests) { + if (!request.key.startsWith('view:')) continue + const [, observationId, viewId] = request.key.split(':') + const observation = report.observations.find((o) => o.id === observationId)! + expect( + request.svg, + `${run.name} ${request.key}`, + ).toBe( + composeHighlightedViewSvg( + envelope.sheetSnapshot as never, + viewId!, + observation as never, + ), + ) + views += 1 + } + // Every (observation, view) the snapshot holds was asked for, once. + const snapshot = envelope.sheetSnapshot as { document: { views: Array<{ id: string }> } } + const held = new Set(snapshot.document.views.map((v) => v.id)) + const expectedViews = new Set( + report.observations.flatMap((o) => + o.zones.filter((z) => held.has(z.viewId)).map((z) => `${o.id}\u0000${z.viewId}`), + ), + ) + expect(views, run.name).toBe(expectedViews.size) + } + }, 120_000) + + it('asks for the SVGs and sizes the R4.1 rasteriser recorded on the real-raster run', async () => { + const runtime = await nodeCoreRuntime('pkg') + const run = RUNS.find((r) => r.name.startsWith('real.'))! + const manifest = JSON.parse( + readFileSync(join(FIXTURES, 'pdf/r3/real/manifest.json'), 'utf8'), + ) as { + calls: Array<{ + svgSha256: string + widthPx: number + heightPx: number + subject: { kind: string; slot?: string; observationId?: string; viewId?: string } + }> + } + const session = unwrap(openExportSession(runtime, inputOf(await envelopeOf(run.r3))), run.name) + let driven: Driven + try { + driven = drive(session, run.raster) + } finally { + session.free() + } + const byKey = new Map(driven.requests.map((r) => [r.key, r])) + for (const call of manifest.calls) { + const key = + call.subject.kind === 'logo' + ? `logo:${call.subject.slot}` + : `view:${call.subject.observationId}:${call.subject.viewId}` + const request = byKey.get(key) + expect(request, key).toBeDefined() + expect(sha256(request!.svg), key).toBe(call.svgSha256) + expect([request!.widthPx, request!.heightPx], key).toEqual([ + call.widthPx, + call.heightPx, + ]) + } + expect(byKey.size).toBe(manifest.calls.length) + }) + + it('refuses with closed kinds, never a trap: a refused input, a bad key, the order', async () => { + const runtime = await nodeCoreRuntime('pkg') + const envelope = await envelopeOf('pdf/r3/demo.fr.nologos.pdf') + const bad = { ...JSON.parse(inputOf(envelope)), branding: { siteUrl: 'nope' } } + const refused = openExportSession(runtime, JSON.stringify(bad)) + expect(refused).toEqual({ ok: false, kind: 'branding_invalid', detail: 'branding' }) + expect(openExportSession(runtime, '{ not json')).toMatchObject({ + ok: false, + kind: 'invalid_json', + }) + expect(runtime.status).toBe('ready') + + const session = unwrap(openExportSession(runtime, inputOf(envelope)), 'open') + try { + expect(session.finish()).toEqual({ ok: false, kind: 'out_of_order', detail: '' }) + expect(session.addRaster('view:x:y', ONE_PX_PNG)).toEqual({ + ok: false, + kind: 'unknown_key', + detail: '', + }) + const first = unwrap(session.next(), 'next') as ExportStep + expect(first.step).toBe('rasters') + const key = (first as Extract).requests[0]!.key + expect(session.next()).toEqual({ ok: false, kind: 'out_of_order', detail: '' }) + // A PNG the decoder refuses is the view's warning, not a failure. + expect(session.addRaster(key, new Uint8Array([1, 2, 3]))).toEqual({ ok: true, value: null }) + expect(session.addRaster(key, ONE_PX_PNG)).toEqual({ + ok: false, + kind: 'duplicate_key', + detail: '', + }) + const warnings = unwrap(session.warnings(), 'warnings') + expect(warnings).toHaveLength(1) + expect(warnings[0]).toMatchObject({ kind: 'view_raster_failed' }) + expect(runtime.status).toBe('ready') + } finally { + session.free() + } + expect(session.next()).toEqual({ ok: false, kind: 'out_of_order', detail: 'session freed' }) + session.free() + }) + + it('answers core_unavailable after a trap mid-session, frees safely, and a new session works after the recovery', async () => { + const runtime = new CoreRuntime(nodeCoreSource('pkg-proofs')) + expect(await runtime.ready()).toBe(true) + const envelope = await envelopeOf('pdf/r3/demo.fr.logos.pdf') + const session = unwrap(openExportSession(runtime, inputOf(envelope)), 'open') + const step = unwrap(session.next(), 'next') + expect(step.step).toBe('rasters') + // The trap: another call of the same instance panics (as any core call could). + const trapped = runtime.invoke((glue: GlueModule) => { + ;(glue as ProofModule).panic_for_test() + return { ok: true as const, value: null } + }) + expect(trapped).toMatchObject({ ok: false, kind: 'internal' }) + expect(session.next()).toEqual({ ok: false, kind: 'core_unavailable' }) + expect(session.addRaster('logo:partner', TWO_BY_ONE_PNG)).toEqual({ + ok: false, + kind: 'core_unavailable', + }) + expect(session.finish()).toEqual({ ok: false, kind: 'core_unavailable' }) + session.free() + expect(await runtime.ready()).toBe(true) + expect(runtime.generation).toBe(2) + expect(session.next()).toEqual({ ok: false, kind: 'out_of_order', detail: 'session freed' }) + const again = unwrap(openExportSession(runtime, inputOf(envelope)), 'open again') + try { + const driven = drive(again, () => new Uint8Array(TWO_BY_ONE_PNG)) + expect(sha256(driven.pdf)).toBe( + readFileSync(join(FIXTURES, 'goldens/r4/pdf.demo.fr.logos.sha256'), 'utf8').trim(), + ) + } finally { + again.free() + } + }) +}) + +// --------------------------------------------------------------------------- +// Memory held by the instance (OD-2): a fresh instance per run, linear memory after the +// session is freed (the high-water: linear memory never shrinks) against the file size. + +interface Fresh { + runtime: CoreRuntime + memory: () => number +} + +async function freshRuntime(): Promise { + let memory: WebAssembly.Memory | undefined + const source = nodeCoreSource('pkg') + const runtime = new CoreRuntime({ + compile: source.compile, + importGlue: async (n) => { + const glue = await source.importGlue(n) + return { + ...glue, + default: async (input: { module_or_path: WebAssembly.Module }) => { + const exports = (await glue.default(input)) as { memory?: WebAssembly.Memory } + memory = exports.memory + return exports + }, + } as GlueModule + }, + }) + if (!(await runtime.ready())) throw new Error('module failed to load') + return { runtime, memory: () => memory?.buffer.byteLength ?? 0 } +} + +describe('R4.6 memory held after an export (printed for RUST.md §10.8)', () => { + it('holds the file plus a bounded transient, never the rasters', async () => { + const demo = await envelopeOf('pdf/r3/demo.fr.logos.pdf') + const real = new Uint8Array(readFileSync(join(FIXTURES, 'pdf/r3/real/raster-1.png'))) + const cases: Array<{ name: string; report?: string; png: Uint8Array }> = [ + { name: 'demo stub', png: new Uint8Array(TWO_BY_ONE_PNG) }, + { name: 'L stub', report: 'L', png: new Uint8Array(TWO_BY_ONE_PNG) }, + { name: 'CAP stub', report: 'CAP', png: new Uint8Array(TWO_BY_ONE_PNG) }, + { name: 'demo real', png: real }, + { name: 'L real', report: 'L', png: real }, + ] + const rows = [ + '| Run | views | PDF bytes | parts | linear before | linear after | (after - before) / PDF | ms |', + '|---|---|---|---|---|---|---|---|', + ] + for (const c of cases) { + const fresh = await freshRuntime() + const report = c.report + ? JSON.parse(readFileSync(join(FIXTURES, `r4/reports/${c.report}.json`), 'utf8')) + : demo.report + if (c.report) report.sheet = (demo.report as unknown as { sheet: unknown }).sheet + const input = JSON.stringify({ ...demo, report, locale: 'fr' }) + const before = fresh.memory() + const started = performance.now() + const session = unwrap(openExportSession(fresh.runtime, input), c.name) + let driven: Driven + try { + driven = drive(session, () => c.png) + } finally { + session.free() + } + const ms = performance.now() - started + const after = fresh.memory() + const views = driven.requests.filter((r) => r.key.startsWith('view:')).length + rows.push( + `| ${c.name} | ${views} | ${driven.pdf.byteLength} | ${driven.parts} | ${before} | ${after} | ${((after - before) / driven.pdf.byteLength).toFixed(2)} | ${ms.toFixed(0)} |`, + ) + expect(driven.warnings, c.name).toEqual([]) + // The rasters never accumulate: what the instance holds beyond the file is the + // parsed input (report, snapshot, trees), one decode transient (RGBA, raw, RGB and + // alpha planes of a 1200 × 943 raster, about 10 MB) and the open chunk's slack (up + // to 8 MiB), whatever the number of views; the PNGs of L real alone weigh 64 MB. + const overhead = after - before - driven.pdf.byteLength + expect(overhead, `${c.name}: held beyond the file`).toBeLessThan(24 * 1024 * 1024) + } + console.info(`[core-wasm] R4.6 session memory (fresh instance per run)\n${rows.join('\n')}`) + }, 600_000) +}) diff --git a/packages/core-wasm/types/ExportStep.ts b/packages/core-wasm/types/ExportStep.ts new file mode 100644 index 00000000..137db83f --- /dev/null +++ b/packages/core-wasm/types/ExportStep.ts @@ -0,0 +1,7 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. +import type { RasterRequest } from "./RasterRequest"; + +/** + * What `next()` answers. + */ +export type ExportStep = { "step": "rasters", requests: Array, } | { "step": "done" }; diff --git a/packages/core-wasm/types/RasterRequest.ts b/packages/core-wasm/types/RasterRequest.ts new file mode 100644 index 00000000..4066fcfc --- /dev/null +++ b/packages/core-wasm/types/RasterRequest.ts @@ -0,0 +1,10 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * One raster the driver owes the session: the SVG text to draw and its pixel size. + */ +export type RasterRequest = { +/** + * `logo:` or `view::`; answered once. + */ +key: string, svg: string, widthPx: number, heightPx: number, }; diff --git a/packages/core-wasm/types/SessionRefusal.ts b/packages/core-wasm/types/SessionRefusal.ts new file mode 100644 index 00000000..bdcf865b --- /dev/null +++ b/packages/core-wasm/types/SessionRefusal.ts @@ -0,0 +1,6 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * A call the state machine refuses (closed kinds). + */ +export type SessionRefusal = "unknown_key" | "duplicate_key" | "out_of_order"; diff --git a/packages/core-wasm/types/index.ts b/packages/core-wasm/types/index.ts index 91b84196..9407c69e 100644 --- a/packages/core-wasm/types/index.ts +++ b/packages/core-wasm/types/index.ts @@ -22,6 +22,7 @@ export type { DraftRestore } from './DraftRestore' export type { DraftRestoreInput } from './DraftRestoreInput' export type { ExportErrorKind } from './ExportErrorKind' export type { ExportInput } from './ExportInput' +export type { ExportStep } from './ExportStep' export type { ExportWarning } from './ExportWarning' export type { Finding } from './Finding' export type { FindingCategory } from './FindingCategory' @@ -60,6 +61,7 @@ export type { PngAsset } from './PngAsset' export type { Point } from './Point' export type { Polygon } from './Polygon' export type { Practitioner } from './Practitioner' +export type { RasterRequest } from './RasterRequest' export type { RebaseOutcome } from './RebaseOutcome' export type { Reference } from './Reference' export type { ReferenceType } from './ReferenceType' @@ -69,6 +71,7 @@ export type { ReportIdInput } from './ReportIdInput' export type { ReportIndexInput } from './ReportIndexInput' export type { ReportZone } from './ReportZone' export type { ReviewStatus } from './ReviewStatus' +export type { SessionRefusal } from './SessionRefusal' export type { Severity } from './Severity' export type { SheetCheck } from './SheetCheck' export type { SheetIndexData } from './SheetIndexData'