feat(domain): R4.6 ExportSession (incremental export, OD-2): rasters decoded and written on arrival, chunked file handed out in parts, views composed by the core, raster_size_of (O4); wasm ExportSession and CoreExportSession; R4 digests re-frozen (catalog and page tree written last, B2)

This commit is contained in:
bchanot committed 2026-10-19 01:15:43 +02:00
1 parent 8d16be577c
commit 9e688b6801
38 files changed
+2421 -354

No files matched your search

@@ -1 +1 @@
2d75e1791c025472dcf90a0df7fd0c4ece5d85456b5d25e8be70d5e4e5786e86
2b9a359c078f5fa1b623ee4db45407209b662909044a6a9f6d02eef4d103d72e
@@ -1 +1 @@
b534afb3a7b40b2c04dbc55b9909835a15324f5b1c49069eee28f061a6f07712
3d76027dc76f799c3a9cb3e9ac5d082a27e58b2ef1e631e2003ba9fee6903b6b
@@ -1 +1 @@
ce9bdaab621d510e0e7d307f67f410bac1a5b69a65cb74cd289ff4a6b149e820
52999af79a82a426ed76e6268388dd641e7eb233f826dab6f87d47c5ecc267ca
@@ -1 +1 @@
e6ed5ce14bf4338c0f161c51900443747bb033403ea4164f96e13d0810abf881
e8ee3238a5c4df10c8564c67148abcdb7b2d282b5f7de3ee5dffbc72ff662247
@@ -1 +1 @@
5f98fb659c7d587cf3921d5b9871e7dd10a2a8148003d1063f74d7a1951e37c4
287f608e77d0d41b15494e72db8415292058f8e65e0e61c4201c76b106763ba3
@@ -1 +1 @@
1faf76663e834c5297c2244310a7366d508010d146ba789d4e24016e0959771d
54a0472c39791c1b5426bf17dbf824ba3079acde66f3062b43643163cc869841
@@ -1 +1 @@
2321f77c211656a41f870584a31d9c44c00868ab420f68428194b254e4c166cd
8ff84417d542cd200b5364844f382a21f19392284f0f7a61040e7e7269fc32dc
@@ -1 +1 @@
781868dbd08050b8191fb727a1b553348c2992c80aff5693fa7781abebc58e2e
6fe8ee50a6c6bda2eab48412f607181b23098cff7132747f623637cb9975c0a0
@@ -1 +1 @@
48503857cab7ba4a27bdc1fec834f77cb1a88f4f9262d1f28f0c262f6ffa7667
58adc70d9de66848bd84a932edce590e1e151444ec063122a5b4eb67343b16f8
@@ -1 +1 @@
bb88a9cebd07a66c669b7fbf656275f003ce327972523cb369494fdfd1abe6c3
b65b6289ee4c5252a32172b97241af253be73d8030dd92d090e18f9ca88b1d80
@@ -1 +1 @@
14dc9f70873b23ec53ad0081a33942c029298879d14b761c4b53190298e1cb81
138c6ca5c9513b5e03b2db76e6b085a0b1fe35a3afedb21f4fd5762049d2b82a
@@ -1 +1 @@
5b96a835158b9783c84d2c71457da32a79102202c1956ce958610d6b54304b58
b842ceafdefacea26b376ab443b3c6b69a9466e853e640b3138f7f788ff781a5
@@ -1 +1 @@
82c3e716e275bc3930249f8f7363ea135efe8f35f8deeffd090d9de1ca6dbb6b
0cf6d48786c388b1c1d2d48b2e78f854f92af378f22dcd2dcbafdb2650b676a3
@@ -1 +1 @@
300d514382483b9cf485a02643d6fd95bfc4dc5e515386ccd8e07a4edbb149a9
59569ab96f4a022bd70a2a1d260bda13daedb810f80744afc6b719b9f5a3f6d3
+4
View File
@@ -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
+68
View File
@@ -103,6 +103,74 @@ pub fn restore_copy(sheet: &LoadedSheet, bytes: Vec<u8>) -> 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<ExportSession, Failure> {
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<usize, Failure> {
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}"))
}
+3 -18
View File
@@ -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<u8>,
pub width: u32,
pub height: u32,
}
/// The whole document's drawing, before serialisation.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct DrawLog {
pub pages: Vec<PageLog>,
pub embeds: Vec<Embed>,
pub links: Vec<LinkOp>,
}
@@ -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<u8>, 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));
}
+50 -42
View File
@@ -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<String, ExportError> {
pub(super) fn envelope_text(input: &CheckedInput) -> Result<String, ExportError> {
let envelope = ReportArchiveEnvelope {
format: EnvelopeFormat,
envelope_version: EnvelopeVersion1,
@@ -48,12 +49,15 @@ fn envelope_text(input: &CheckedInput) -> Result<String, ExportError> {
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<ExportResult, ExportError> {
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<ExportResult, ExportError> {
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,
+50 -12
View File
@@ -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<SheetSnapshot, ExportError> {
/// 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<CheckedInput, ExportError> {
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<CheckedInput, ExportError> {
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<Vec<u8>>,
+143 -37
View File
@@ -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<Image>;
}
/// 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<CreditImage>,
}
/// 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<ExportWarning>,
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<Image> {
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<Image> {
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<ViewImage> {
let view_ids: Vec<String> = 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<BrandingImages, ExportError> {
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<ExportWarning>,
}
/// 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<Drawn, ExportError> {
/// 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<Drawn, ExportError> {
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,
+24 -40
View File
@@ -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<Rendered> {
/// 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<Rendered> {
let sheet = layout.input.index.over(&layout.input.snapshot.document);
let view_ids: Vec<String> = 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 =
+4 -1
View File
@@ -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;
+155 -48
View File
@@ -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<Vec<u8>>,
sealed: Vec<Vec<u8>>,
current: Vec<u8>,
target: usize,
/// Bytes in the sealed chunks and the current one.
total: usize,
/// Offset of each object by number, `None` while reserved.
offsets: Vec<Option<usize>>,
}
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<u8>], 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<usize> {
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<u8>) {
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<u8>) -> 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<u8> {
let mut out =
Vec::with_capacity(self.bodies.iter().map(|b| b.len() + 24).sum::<usize>() + 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::<usize>() + 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<Vec<u8>>,
/// `(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<u8> {
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.
+186 -128
View File
@@ -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<u8> {
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<DecodedPng, ExportError> {
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<Ref, ExportError> {
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<Ref, ExportError>
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<Ref> {
let page = doc.log.pages.get(index)?;
let content = objects.add_stream(
&[("Filter", "/FlateDecode".to_owned())],
&deflate(&page_content(page)),
);
let annots: Vec<String> = 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<String, ExportError> {
})
}
/// 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<Vec<u8>, 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<Ref>,
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<Ref> {
let page = log.pages.get(index)?;
let content = self.objects.add_stream(
&[("Filter", "/FlateDecode".to_owned())],
&deflate(&page_content(page)),
);
let annots: Vec<String> = 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<Vec<u8>>,
/// `(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<u8> {
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<u8> {
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<Image> {
let (image, width, height) = write_image(&mut self.objects, png)?;
self.images.push(image);
Some(Image {
embed: self.images.len() - 1,
width,
height,
})
}
}
+490
View File
@@ -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<RasterRequest> },
/// 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<ExportError> for SessionError {
fn from(error: ExportError) -> Self {
Self::Export(error)
}
}
impl From<SessionRefusal> 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<u8>),
/// 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<Pending>,
}
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<Writer>,
/// The file's chunks once finished, handed out front to back.
parts: std::collections::VecDeque<Vec<u8>>,
written: usize,
log: DrawLog,
warnings: Vec<ExportWarning>,
branding: Option<BrandingImages>,
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<Self, ExportError> {
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<Vec<u8>> {
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<ExportStep, SessionError> {
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<R>(&mut self, phase: impl FnOnce(&mut Layout<'_>) -> R) -> Option<R> {
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<RasterRequest> {
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<RasterRequest> {
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<String> = 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<ViewImage> = 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<String, &[u8]> {
let mut map: HashMap<String, &[u8]> = 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
}
+157
View File
@@ -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:<slot>` or `view:<observationId>:<viewId>`; 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<RasterRequest> {
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<RasterRequest> {
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))
}
+19
View File
@@ -95,3 +95,22 @@ fn expand_parts(parts: &[Value], dir: &std::path::Path) -> Vec<u8> {
pub fn latin1_bytes(text: &str) -> Vec<u8> {
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<Vec<u8>>,
}
impl faunosteo_core::pdf::write::layout::ImageSink for PngKeeper {
fn embed(&mut self, png: &[u8]) -> Option<faunosteo_core::pdf::write::layout::Image> {
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,
})
}
}
+20 -14
View File
@@ -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<u8>]) -> 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<Stri
let input = export_input(report, locale, mode);
let rasters = stub_rasters(&input, mode);
let checked = check_input(input).unwrap();
let drawn = layout(&checked, &rasters).unwrap();
let mut keeper = PngKeeper::default();
let drawn = layout(&checked, &rasters, &mut keeper).unwrap();
assert!(drawn.warnings.is_empty(), "{name}: {:?}", drawn.warnings);
let pages = oracle["pages"].as_array().unwrap();
if pages.len() != drawn.log.pages.len() {
@@ -177,7 +178,7 @@ fn compare_run(report: &str, locale: &str, mode: &str, mismatches: &mut Vec<Stri
}
for (i, (e, a)) in expected.iter().zip(actual).enumerate() {
ops += 1;
let a = op_json(a, &drawn.log);
let a = op_json(a, &keeper.pngs);
if !same(&without_seq(e), &a) {
mismatches.push(format!(
"{name} page {p} op {i}\n expected {}\n actual {a}",
@@ -186,12 +187,11 @@ fn compare_run(report: &str, locale: &str, mode: &str, mismatches: &mut Vec<Stri
}
}
}
let embeds: Vec<Value> = drawn
.log
.embeds
let embeds: Vec<Value> = 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");
}
+382
View File
@@ -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<u8> {
faunosteo_core::pdf::write::layout::png::base64_bytes(text).unwrap()
}
fn fixture(path: &str) -> Vec<u8> {
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<RasterRequest> {
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<_>>(),
vec!["logo:partner"]
);
assert!(branding[0].svg.starts_with("<svg"));
assert_eq!(branding[0].width_px, RASTER_WIDTH_PX);
assert_eq!(
(branding[0].width_px, branding[0].height_px),
raster_size_of(read_svg(&branding[0].svg).unwrap().root.attr("viewBox"))
);
session
.add_raster("logo:partner", &base64(TWO_BY_ONE_PNG))
.unwrap();
let document = &snapshot.document;
let main = document.views.iter().find(|v| v.is_main()).unwrap().id();
for observation in &report.observations {
let batch = requests(session.next_step().unwrap());
let mut seen = Vec::new();
for zone in &observation.zones {
if !seen.contains(&zone.view_id.as_str()) {
seen.push(&zone.view_id);
}
}
let expected_order: Vec<String> = 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::<Vec<_>>(),
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::<HashSet<_>>()
.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,
},
]
);
}
+64
View File
@@ -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 `<kind>: <detail>` with today's export kinds when the input is refused.
#[wasm_bindgen(constructor)]
pub fn new(input: &str) -> Result<ExportSession, JsError> {
faunosteo_core::facade::export::open(input)
.map(|inner| ExportSession { inner })
.map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail)))
}
/// `{"ok":true,"value":<ExportStep>}`: 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 `<kind>: <detail>` (`out_of_order`, `self_check_failed`).
pub fn finish(&mut self) -> Result<u32, JsError> {
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<Vec<u8>> {
self.inner.take_part()
}
/// `{"ok":true,"value":[<ExportWarning>…]}`, 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
+152
View File
@@ -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<ExportStep> {
return this.call((handle) => parseOutcome<ExportStep>(handle.next_step()))
}
/** The PNG of `key`: `null` on success, else a closed refusal. */
addRaster(key: string, png: Uint8Array): CoreOutcome<null> {
return this.call((handle) =>
parseOutcome<null>(handle.add_raster(key, png)),
)
}
/** `key` could not be rasterised (the session records the warning). */
rasterFailed(key: string): CoreOutcome<null> {
return this.call((handle) => parseOutcome<null>(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 `<kind>: <detail>` for
* `out_of_order` or `self_check_failed`; anything else is a trap.
*/
finish(): CoreOutcome<Uint8Array[]> {
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<ExportWarning[]> {
return this.call((handle) =>
parseOutcome<ExportWarning[]>(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<T>(fn: (handle: GlueExportSession) => CoreOutcome<T>): CoreOutcome<T> {
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))
}
}
/** `<kind>: <detail>` → the failure. */
function closedFailure(message: string): CoreOutcome<never> {
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<CoreExportSession> {
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),
}
})
}
+2
View File
@@ -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,
+16
View File
@@ -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 `<kind>: <detail>` 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 `<kind>: <detail>` (`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 {
@@ -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<Envelope> {
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<T>(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<ExportStep, { step: 'rasters' }>).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<Fresh> {
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)
})
+7
View File
@@ -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<RasterRequest>, } | { "step": "done" };
+10
View File
@@ -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:<slot>` or `view:<observationId>:<viewId>`; answered once.
*/
key: string, svg: string, widthPx: number, heightPx: number, };
@@ -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";
+3
View File
@@ -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'