feat(domain): R4.2 scaffold of the pdf reader module (feature pdf-read, miniz_oxide)

Module layout of plan §B.1.1 for the reader (read/{scan,strings,stamp,inflate,probe},
json_js), shared constants and types, index_of; feature-gated test targets; the wasm
facade enables the feature; rust-check runs the gated clippy and tests.
This commit is contained in:
bchanot committed 2026-10-18 15:29:58 +02:00
1 parent c6bf175b61
commit 21d34fb9a7
18 files changed
+166 -1

No files matched your search

Generated
+2
View File
@@ -186,9 +186,11 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
name = "faunosteo-core"
version = "0.1.0"
dependencies = [
"miniz_oxide 0.9.1",
"roxmltree",
"serde",
"serde_json",
"sha2",
"ts-rs",
"url",
]
+3
View File
@@ -30,6 +30,9 @@ url = "2.5.8"
roxmltree = { version = "=0.21.1", default-features = false, features = ["std", "positions"] }
# The CLI in docker/rust-builder.Dockerfile must be this exact version.
wasm-bindgen = "=0.2.129"
# FlateDecode inflation of the PDF attachment (R4): the version `png` already locks through
# flate2; no std, so the same code runs on wasm32.
miniz_oxide = { version = "0.9.1", default-features = false, features = ["with-alloc"] }
image = { version = "0.25.10", default-features = false, features = ["jpeg", "png", "webp"] }
libwebp-sys = "0.14.4"
seccompiler = "0.5.0"
+25
View File
@@ -14,6 +14,9 @@ path = "src/lib.rs"
default = []
# Exports the TypeScript types of the contracts (ts-rs) on `cargo test -p faunosteo-core --features ts`.
ts = ["dep:ts-rs"]
# The PDF reader (R4, plan §B.1.2): byte scan, inflation, attachment probe, import. The wasm
# facade enables it; the worker never does.
pdf-read = ["dep:miniz_oxide"]
[dependencies]
serde.workspace = true
@@ -21,6 +24,28 @@ serde_json.workspace = true
url.workspace = true
roxmltree.workspace = true
ts-rs = { workspace = true, optional = true }
miniz_oxide = { workspace = true, optional = true }
[dev-dependencies]
# Digests of the frozen R4 oracles (bytes and JSON texts the TypeScript recorded as sha256).
sha2.workspace = true
# The R4 reader suites compile only with the feature (cargo skips them otherwise).
[[test]]
name = "pdf_scan"
required-features = ["pdf-read"]
[[test]]
name = "pdf_inflate"
required-features = ["pdf-read"]
[[test]]
name = "pdf_json_js"
required-features = ["pdf-read"]
[[test]]
name = "pdf_import"
required-features = ["pdf-read"]
[lints]
workspace = true
+2
View File
@@ -10,6 +10,8 @@ pub mod domain;
pub mod facade;
pub mod json;
pub mod ops;
#[cfg(feature = "pdf-read")]
pub mod pdf;
/// Version of the core, reported by the wasm facade and the worker.
pub const CORE_VERSION: &str = env!("CARGO_PKG_VERSION");
+1
View File
@@ -0,0 +1 @@
//! R4.2c: the JavaScript-path JSON side effects of the import. Written by the R4.2c track.
+10
View File
@@ -0,0 +1,10 @@
//! The PDF side of the core (R4, plan `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md`).
//!
//! R4.2 brings the reader: the attachment located by a byte scan over the file (never a parse
//! of the object graph, BLK-009), inflated under a cap, probed as JSON, then handed to the
//! R2 session import. Every rule is the one `packages/pdf/src/attachment/scan.ts` applied,
//! pinned by the frozen oracles O7 (`tests/oracles/r4/read.json`), O8 (`tolerance.json`) and
//! O9 (`inflate.json`). The writer (`write`) and the import entry (`import`) follow.
pub mod json_js;
pub mod read;
+1
View File
@@ -0,0 +1 @@
//! R4.2b: `inflateFlate` of inflate.ts on miniz_oxide. Written by the R4.2b track.
+88
View File
@@ -0,0 +1,88 @@
//! Locating the Faunosteo attachment in a PDF's bytes (port of
//! `packages/pdf/src/attachment/{scan,inflate,read}.ts`, plan §B.1.2).
//!
//! A stream object can never live inside an object stream, so every `/Type /EmbeddedFile`
//! dictionary and its data are in clear in the file. Nothing here parses the object graph,
//! the xref or an `/ObjStm`: the only inflation on the import path is the capped one of
//! [`inflate::inflate_flate`]. The scanner never fails on garbage: it returns fewer
//! candidates. Every loop is bounded by the file end, itself capped at [`MAX_PDF_BYTES`].
//!
//! The TypeScript relied on JavaScript regular expressions in a few places; their exact
//! semantics (which bytes `\s` matches, lazy `/EF` removal, `.` excluding CR and LF in a
//! string token) are reproduced explicitly and pinned by the `semantics.*` rows of O7.
pub mod inflate;
pub mod probe;
pub mod scan;
pub mod stamp;
pub mod strings;
/// A Faunosteo PDF weighs a few hundred KB; anything larger is not one.
pub const MAX_PDF_BYTES: usize = 50 * 1024 * 1024;
/// Hard ceiling on an attachment, inflated or not: a report archive weighs a few hundred KB;
/// anything bigger is a decompression bomb or corruption.
pub const MAX_ATTACHMENT_BYTES: usize = 16 * 1024 * 1024;
/// The file name prefix every Faunosteo attachment carries.
pub const ATTACHMENT_NAME_PREFIX: &str = "osteo-report";
/// The keyword stamp every archive carries (`faunosteo-archive/<n>`).
pub const ARCHIVE_STAMP: &str = "faunosteo-archive";
/// Candidates beyond this count are ignored: a crafted file cannot make the reader loop.
pub const MAX_CANDIDATES: usize = 32;
/// A stream or Filespec dictionary is small; a longer one is skipped.
pub const MAX_DICT_BYTES: usize = 4096;
/// The stream filter the scanner recognises.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamFilter {
/// `/FlateDecode`, alone or first in an array.
FlateDecode,
/// Anything else, or no filter: the data is used raw.
None,
}
/// An `/EmbeddedFile` stream found in clear.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EmbeddedFileCandidate {
/// First byte of the stream data.
pub offset: usize,
/// Byte count of the stream data (declared, or measured to `endstream`).
pub length: usize,
pub filter: StreamFilter,
/// From a visible `/Filespec` whose `/EF /F` points at this stream, decoded as text
/// (UTF-16BE with BOM, else Latin-1); a lone surrogate becomes U+FFFD.
pub name: Option<String>,
}
/// Why no attachment comes out of a file (`ArchiveReadErrorKind` of the TypeScript).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadKind {
/// Over [`MAX_PDF_BYTES`], or no `%PDF-` within the first KiB.
InvalidPdf,
/// No candidate holds a versioned JSON object, and no archive stamp is visible.
NoAttachment,
/// No candidate holds a versioned JSON object, but a `/Keywords` string carries the
/// archive stamp: the attachment was stripped by another tool.
AttachmentStripped,
}
impl ReadKind {
/// The closed kind name the facade and the messages use.
pub fn as_str(self) -> &'static str {
match self {
Self::InvalidPdf => "invalid_pdf",
Self::NoAttachment => "no_attachment",
Self::AttachmentStripped => "attachment_stripped",
}
}
}
/// `%PDF-` within the first KiB, as viewers accept it.
pub fn has_pdf_header(bytes: &[u8]) -> bool {
let end = bytes.len().min(1024);
scan::index_of(bytes, b"%PDF-", 0, end).is_some()
}
+1
View File
@@ -0,0 +1 @@
//! R4.2d: `locateAttachment` of scan.ts. Written after R4.2a, b and c.
+22
View File
@@ -0,0 +1,22 @@
//! R4.2a: `findEmbeddedFiles` of scan.ts (header, typed dictionaries, stream bounds,
//! Filespec names). Written by the R4.2a track; `index_of` is shared by the other files.
/// Naive forward search of `needle` in `bytes[from..end]`; the needle's first byte is the
/// fast reject (scan.ts `indexOf`). `None` when absent or when the window is shorter than
/// the needle.
pub fn index_of(bytes: &[u8], needle: &[u8], from: usize, end: usize) -> Option<usize> {
let end = end.min(bytes.len());
if needle.is_empty() || end < needle.len() {
return None;
}
let last = end - needle.len();
let first = needle[0];
let mut i = from;
while i <= last {
if bytes[i] == first && bytes[i..i + needle.len()] == *needle {
return Some(i);
}
i += 1;
}
None
}
+1
View File
@@ -0,0 +1 @@
//! R4.2a: `hasArchiveStamp` of scan.ts. Written by the R4.2a track.
+1
View File
@@ -0,0 +1 @@
//! R4.2a: `decodePdfString` of scan.ts. Written by the R4.2a track.
+1
View File
@@ -0,0 +1 @@
//! R4.2: placeholder, written by its track.
+1
View File
@@ -0,0 +1 @@
//! R4.2: placeholder, written by its track.
+1
View File
@@ -0,0 +1 @@
//! R4.2: placeholder, written by its track.
+1
View File
@@ -0,0 +1 @@
//! R4.2: placeholder, written by its track.
+1 -1
View File
@@ -18,7 +18,7 @@ default = []
proofs = []
[dependencies]
faunosteo-core = { path = "../core" }
faunosteo-core = { path = "../core", features = ["pdf-read"] }
wasm-bindgen.workspace = true
[lints]
+4
View File
@@ -15,6 +15,10 @@ cd "$(dirname "$0")/.."
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
# The PDF reader (R4) is feature-gated in the core: its code and suites compile only here
# and in the wasm module, never in the worker.
cargo clippy -p faunosteo-core --all-targets --features pdf-read --locked -- -D warnings
cargo test -p faunosteo-core --features pdf-read --locked
# Exports the TypeScript types of the contracts (ts-rs) into packages/core-wasm/types.
# `git status --porcelain --untracked-files=all -- packages/core-wasm/types` must stay
# empty afterwards (scripts/check-all.sh, .gitea/workflows/ci.yml): the committed types