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:
1 parent
c6bf175b61
commit
21d34fb9a7
18 files changed
+166
-1
No files matched your search
Generated
+2
@@ -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",
|
||||
]
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
@@ -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");
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2c: the JavaScript-path JSON side effects of the import. Written by the R4.2c track.
|
||||
@@ -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;
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2b: `inflateFlate` of inflate.ts on miniz_oxide. Written by the R4.2b track.
|
||||
@@ -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()
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2d: `locateAttachment` of scan.ts. Written after R4.2a, b and c.
|
||||
@@ -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
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2a: `hasArchiveStamp` of scan.ts. Written by the R4.2a track.
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2a: `decodePdfString` of scan.ts. Written by the R4.2a track.
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2: placeholder, written by its track.
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2: placeholder, written by its track.
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2: placeholder, written by its track.
|
||||
@@ -0,0 +1 @@
|
||||
//! R4.2: placeholder, written by its track.
|
||||
@@ -18,7 +18,7 @@ default = []
|
||||
proofs = []
|
||||
|
||||
[dependencies]
|
||||
faunosteo-core = { path = "../core" }
|
||||
faunosteo-core = { path = "../core", features = ["pdf-read"] }
|
||||
wasm-bindgen.workspace = true
|
||||
|
||||
[lints]
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user