feat(domain): R4.5b/c serialiser, export driver, self-check, from_envelope; O2 parity suite

objects.rs (own minimal writer: numbered objects, streams, classic xref, pdf-lib's string
forms; pdf-writer not used: every number spelt through numberToString, no f32), serialize.rs
(catalog with names tree and AF, pages, 3 Type1 WinAnsi fonts, image XObjects with the
DeviceGray SMask, Link annotations with hex ASCII URIs, Info with Producer/Creator
Faunosteo, the Flate attachment with Params and Filespec), export.rs (checks → envelope
as JSON.stringify(_, null, 2) → layout → file → self-check through the R4 reader;
export_from_envelope). cargo pdf_serialize against the 14 R3 PDFs: content streams equal
after resource-name resolution, image planes and SMasks equal, links equal, Info equal
but Producer/Creator, attachment bytes equal (store path: values equal, D-R11 order);
qpdf --check clean, pdfdetach lists the attachment, poppler 150 dpi 0 pixel differs on
14 runs; R4 PDF → Rust import = R3 PDF import, re-export from the envelope byte-identical;
R4 output digests frozen in goldens/r4/pdf.*.sha256.
This commit is contained in:
bchanot committed 2026-10-18 23:10:18 +02:00
1 parent d7984449ed
commit 4d45de5745
21 files changed
+1381 -2

No files matched your search

+128
View File
@@ -0,0 +1,128 @@
//! `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`.
use serde_json::Value;
use super::input::{
CheckedInput, ExportError, ExportErrorKind, ExportInput, ExportWarning, Rasters, check_input,
};
use super::layout::layout;
use super::serialize::{Document, Metadata, export_date, serialize};
use crate::domain::archive::{EnvelopeFormat, EnvelopeVersion1, Locale, ReportArchiveEnvelope};
use crate::json::to_js_pretty;
use crate::pdf::read::MAX_ATTACHMENT_BYTES;
use crate::pdf::read::probe::{ProbeLimits, read_attached_document};
/// What an export gives back: the file, the envelope text it carries and the warnings.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExportResult {
pub pdf: Vec<u8>,
pub envelope: String,
pub warnings: Vec<ExportWarning>,
}
/// 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> {
let envelope = ReportArchiveEnvelope {
format: EnvelopeFormat,
envelope_version: EnvelopeVersion1,
exported_at: input.exported_at.clone(),
locale: input.locale,
report: input.report.clone(),
sheet_snapshot: input.snapshot.clone(),
branding: input.branding.clone(),
labels: input.labels.clone(),
};
let text = to_js_pretty(&envelope).map_err(|error| ExportError {
kind: ExportErrorKind::SelfCheckFailed,
detail: error.to_string(),
})?;
if text.len() > MAX_ATTACHMENT_BYTES {
return Err(ExportError {
kind: ExportErrorKind::SnapshotTooLarge,
detail: "attachment".to_owned(),
});
}
Ok(text)
}
/// `finish()` re-reads its own output: one scan and one inflation, the attachment's text
/// against the envelope written.
fn self_check(pdf: &[u8], envelope: &str) -> Result<(), ExportError> {
let located =
read_attached_document(pdf, ProbeLimits::PRODUCTION).map_err(|kind| ExportError {
kind: ExportErrorKind::SelfCheckFailed,
detail: kind.as_str().to_owned(),
})?;
if located.text != envelope {
return Err(ExportError {
kind: ExportErrorKind::SelfCheckFailed,
detail: "attachment differs from the envelope".to_owned(),
});
}
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,
},
};
let pdf = serialize(&document)?;
self_check(&pdf, &envelope)?;
Ok(ExportResult {
pdf,
envelope,
warnings: drawn.warnings,
})
}
/// `exportReportArchive`: every check, then the file.
pub fn export_pdf(input: ExportInput, rasters: &Rasters) -> Result<ExportResult, ExportError> {
let checked = check_input(input)?;
export_checked(&checked, rasters)
}
/// `exportFromEnvelope`: an archive re-exported from its own snapshot, branding and labels,
/// with the caller's locale and export time; no sheet, no network, no configuration.
pub fn export_from_envelope(
envelope: &Value,
locale: Locale,
exported_at: &str,
rasters: &Rasters,
) -> Result<ExportResult, ExportError> {
let field = |key: &str| envelope.get(key).cloned().unwrap_or(Value::Null);
let report = serde_json::from_value(field("report")).map_err(|error| ExportError {
kind: ExportErrorKind::InvalidInput,
detail: format!("report: {error}"),
})?;
let input = ExportInput {
report,
sheet_snapshot: field("sheetSnapshot"),
branding: field("branding"),
labels: field("labels"),
locale,
exported_at: exported_at.to_owned(),
};
export_pdf(input, rasters)
}
+7
View File
@@ -51,6 +51,11 @@ pub enum ExportErrorKind {
TooManyPages,
/// The branding or the label set fails its schema (URLs included).
BrandingInvalid,
/// R4: the file re-read does not carry the envelope it was written with, or an image
/// the layout sized could not be decoded (today's export alert, `self_check_failed`).
SelfCheckFailed,
/// R4: `exportedAt` is not an ISO UTC timestamp (the application always sends one).
InvalidInput,
}
impl ExportErrorKind {
@@ -61,6 +66,8 @@ impl ExportErrorKind {
Self::SheetMismatch => "sheet_mismatch",
Self::TooManyPages => "too_many_pages",
Self::BrandingInvalid => "branding_invalid",
Self::SelfCheckFailed => "self_check_failed",
Self::InvalidInput => "invalid_input",
}
}
}
+4 -1
View File
@@ -90,7 +90,10 @@ impl<'a> Layout<'a> {
) -> Option<Image> {
let asset = asset?;
let image = match asset {
ImageAsset::Png(png) => png::base64_bytes(&png.base64).and_then(|b| self.embed(&b)),
// `embedImage`: the base64 PNG passes the gate (`pngIssue`) before any decode.
ImageAsset::Png(png) => png::base64_bytes(&png.base64)
.filter(|bytes| super::png::png_issue(bytes).is_none())
.and_then(|b| self.embed(&b)),
ImageAsset::Svg(_) => raster.and_then(|bytes| self.embed(bytes)),
};
if image.is_none() {
+3
View File
@@ -10,7 +10,10 @@ pub mod afm_data;
pub mod content;
pub mod dates;
pub mod draw_log;
pub mod export;
pub mod input;
pub mod layout;
pub mod objects;
pub mod png;
pub mod serialize;
pub mod text;
+190
View File
@@ -0,0 +1,190 @@
//! 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,
//! 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
//! difference the plan allowed never arises and no dependency enters the module.
use super::content::number_to_string;
/// The bytes of one indirect object's body (a dictionary, or a stream with its dictionary).
pub struct Objects {
bodies: Vec<Vec<u8>>,
}
/// `n 0 R`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Ref(pub usize);
impl Ref {
pub fn text(self) -> String {
format!("{} 0 R", self.0)
}
}
impl Objects {
pub fn new() -> Self {
Self { bodies: Vec::new() }
}
/// 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())
}
pub fn set(&mut self, at: Ref, body: Vec<u8>) {
if let Some(slot) = self.bodies.get_mut(at.0 - 1) {
*slot = body;
}
}
pub fn add(&mut self, body: Vec<u8>) -> Ref {
self.bodies.push(body);
Ref(self.bodies.len())
}
/// 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())
}
/// 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");
}
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());
}
let trailer = format!(
"trailer\n<< /Size {} /Root {} /Info {} >>\nstartxref\n{xref}\n%%EOF\n",
self.bodies.len() + 1,
root.text(),
info.text()
);
out.extend_from_slice(trailer.as_bytes());
out
}
}
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
}
/// `<< /K v … >>` from entries already spelt as PDF syntax.
pub fn dict(entries: &[(&str, String)]) -> String {
let mut out = String::from("<<");
for (key, value) in entries {
out.push_str(&format!(" /{key} {value}"));
}
out.push_str(" >>");
out
}
/// A name object: `#xx` for the bytes a name cannot carry bare (`/application#2fjson`).
pub fn name(text: &str) -> String {
let mut out = String::from("/");
for byte in text.bytes() {
let bare = byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'+');
if bare {
out.push(char::from(byte));
} else {
out.push_str(&format!("#{byte:02x}"));
}
}
out
}
/// `PDFHexString.fromText`: UTF-16BE with a BOM, lowercase hex.
pub fn hex_text(text: &str) -> String {
let mut out = String::from("<feff");
for unit in text.encode_utf16() {
out.push_str(&format!("{unit:04x}"));
}
out.push('>');
out
}
/// The hex form of ASCII bytes, one byte per character (`linkAnnotation.ts` `asciiHexOf`).
pub fn hex_ascii(text: &str) -> String {
let mut out = String::from("<");
for byte in text.bytes() {
out.push_str(&format!("{byte:02x}"));
}
out.push('>');
out
}
/// A literal string, the three delimiters escaped (pdf-lib did not escape; a fixed ASCII
/// name never needs it, the escape only guards the form).
pub fn literal(text: &str) -> String {
let mut out = String::from("(");
for c in text.chars() {
if matches!(c, '(' | ')' | '\\') {
out.push('\\');
}
out.push(c);
}
out.push(')');
out
}
/// An array of numbers in pdf-lib's spelling.
pub fn numbers(values: &[f64]) -> String {
let items: Vec<String> = values.iter().map(|v| number_to_string(*v)).collect();
format!("[{}]", items.join(" "))
}
/// `PDFString.fromDate`: `(D:YYYYMMDDHHmmSSZ)` from the UTC fields of an ISO timestamp
/// (`YYYY-MM-DDTHH:MM:SS[.sss]Z`, what `Date.prototype.toISOString` writes); `None` when
/// the text is not one.
pub fn pdf_date(iso: &str) -> Option<String> {
let bytes = iso.as_bytes();
let digits = |range: std::ops::Range<usize>| {
bytes
.get(range.clone())
.filter(|part| part.iter().all(u8::is_ascii_digit))
.map(|_| &iso[range])
};
let (year, month, day) = (digits(0..4)?, digits(5..7)?, digits(8..10)?);
let (hours, minutes, seconds) = (digits(11..13)?, digits(14..16)?, digits(17..19)?);
let separators = bytes.get(4) == Some(&b'-')
&& bytes.get(7) == Some(&b'-')
&& bytes.get(10) == Some(&b'T')
&& bytes.get(13) == Some(&b':')
&& bytes.get(16) == Some(&b':');
let tail = &iso[19..];
let tail_ok = tail == "Z"
|| (tail.starts_with('.')
&& tail.ends_with('Z')
&& tail[1..tail.len() - 1].bytes().all(|b| b.is_ascii_digit()));
(separators && tail_ok).then(|| format!("(D:{year}{month}{day}{hours}{minutes}{seconds}Z)"))
}
+282
View File
@@ -0,0 +1,282 @@
//! 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.
use miniz_oxide::deflate::compress_to_vec_zlib;
use super::content::{font_resource_name, image_resource_name, page_content};
use super::draw_log::{DrawLog, Embed, PAGE_HEIGHT, PAGE_WIDTH};
use super::input::{ExportError, ExportErrorKind};
use super::objects::{Objects, Ref, dict, hex_ascii, hex_text, literal, name, numbers, pdf_date};
use super::png::{DecodedPng, decode_png};
use super::text::Font;
/// pako's default level, what `context.flateStream` used.
const DEFLATE_LEVEL: u8 = 6;
pub const ATTACHMENT_FILENAME: &str = "osteo-report.json";
pub const ATTACHMENT_DESCRIPTION: &str = "Faunosteo report archive v1";
pub const PDF_KEYWORD: &str = "faunosteo-archive/1";
/// A4, Producer and Creator (owner arbitration A4).
pub const PRODUCER: &str = "Faunosteo";
/// The document information the layout does not know.
pub struct Metadata<'a> {
pub title: &'a str,
pub author: &'a str,
pub subject: &'a str,
/// `D:` form of the export time, every date of the file.
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)?;
let size = [
("Width", decoded.width.to_string()),
("Height", decoded.height.to_string()),
];
let smask = decoded.alpha.as_ref().map(|alpha| {
let mut entries = vec![
("Type", "/XObject".to_owned()),
("Subtype", "/Image".to_owned()),
("BitsPerComponent", "8".to_owned()),
];
entries.extend(size.iter().cloned());
entries.push(("ColorSpace", "/DeviceGray".to_owned()));
entries.push(("Decode", "[0 1]".to_owned()));
entries.push(("Filter", "/FlateDecode".to_owned()));
objects.add_stream(&entries, &deflate(alpha))
});
let mut entries = vec![
("Type", "/XObject".to_owned()),
("Subtype", "/Image".to_owned()),
("BitsPerComponent", "8".to_owned()),
];
entries.extend(size.iter().cloned());
entries.push(("ColorSpace", "/DeviceRGB".to_owned()));
if let Some(smask) = smask {
entries.push(("SMask", smask.text()));
}
entries.push(("Filter", "/FlateDecode".to_owned()));
Ok(objects.add_stream(&entries, &deflate(&decoded.rgb)))
}
fn write_fonts(objects: &mut Objects) -> [(Font, Ref); 3] {
let fonts = [Font::Helvetica, Font::HelveticaBold, Font::TimesRoman];
fonts.map(|font| {
let body = dict(&[
("Type", "/Font".to_owned()),
("Subtype", "/Type1".to_owned()),
("BaseFont", format!("/{}", font.as_str())),
("Encoding", "/WinAnsiEncoding".to_owned()),
]);
(font, objects.add(body.into_bytes()))
})
}
fn resources(fonts: &[(Font, Ref); 3], images: &[Ref]) -> String {
let font_entries: Vec<String> = fonts
.iter()
.map(|(font, r)| format!("/{} {}", font_resource_name(*font), r.text()))
.collect();
let image_entries: Vec<String> = images
.iter()
.enumerate()
.map(|(i, r)| format!("/{} {}", image_resource_name(i), r.text()))
.collect();
format!(
"<< /Font << {} >> /XObject << {} >> >>",
font_entries.join(" "),
image_entries.join(" ")
)
}
/// One Link annotation (`linkAnnotation.ts`): the rect as drawn, a URI action in hex ASCII.
fn write_link(objects: &mut Objects, rect: [f64; 4], uri: &str) -> Ref {
let action = dict(&[
("Type", "/Action".to_owned()),
("S", "/URI".to_owned()),
("URI", hex_ascii(uri)),
]);
objects.add(
dict(&[
("Type", "/Annot".to_owned()),
("Subtype", "/Link".to_owned()),
("Rect", numbers(&rect)),
("Border", "[0 0 0]".to_owned()),
("A", action),
])
.into_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)),
];
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(&[
("Title", hex_text(metadata.title)),
("Author", hex_text(metadata.author)),
("Subject", hex_text(metadata.subject)),
("Keywords", hex_text(PDF_KEYWORD)),
("Producer", hex_text(PRODUCER)),
("Creator", hex_text(PRODUCER)),
("CreationDate", metadata.date.to_owned()),
("ModDate", metadata.date.to_owned()),
])
.into_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 {
let params = dict(&[
("Size", doc.envelope.len().to_string()),
("CreationDate", doc.metadata.date.to_owned()),
("ModDate", doc.metadata.date.to_owned()),
]);
let stream = objects.add_stream(
&[
("Type", "/EmbeddedFile".to_owned()),
("Subtype", name("application/json")),
("Params", params),
("Filter", "/FlateDecode".to_owned()),
],
&deflate(doc.envelope),
);
objects.add(
dict(&[
("Type", "/Filespec".to_owned()),
("F", literal(ATTACHMENT_FILENAME)),
("UF", hex_text(ATTACHMENT_FILENAME)),
("EF", dict(&[("F", stream.text())])),
("Desc", hex_text(ATTACHMENT_DESCRIPTION)),
("AFRelationship", "/Data".to_owned()),
])
.into_bytes(),
)
}
/// The export time in the `D:` form, or the closed refusal of a timestamp that is not ISO.
pub fn export_date(exported_at: &str) -> Result<String, ExportError> {
pdf_date(exported_at).ok_or_else(|| ExportError {
kind: ExportErrorKind::InvalidInput,
detail: "exportedAt".to_owned(),
})
}
/// 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)?);
}
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());
}
}
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))
}