Skip to content

A fast, helpful, and open-source document parser

fixes

Logan Markewich24cd52cab457
diff --git a/Cargo.lock b/Cargo.lock
index cf05ac2..9b65311 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2027,6 +2027,7 @@ dependencies = [
"liteparse-pdfium",
"liteparse-pdfium-sys",
"lopdf",
+ "memchr",
"oar-ocr",
"ordered-float",
"regex",
diff --git a/README.md b/README.md
index 57480cb..68487dd 100644
--- a/README.md
+++ b/README.md
@@ -256,12 +256,19 @@ link annotations. The field is absent by default; enabled untagged pages contain
### Document metadata, content bounds, and XFA packets
Parse results (Rust/Node/Python APIs) carry the document's `/Info` `creator`
-and `producer` entries when present, plus `doc_meta`
-(`docMeta` in JavaScript/WASM) with the `/Info` creation/modification
-dates, PDF version and encryption permissions, signature state, incremental-save
-markers, trailer ID comparison, raw XMP packet (capped at 64 KiB), and source
-file size. These document fields are API-only and never appear in CLI JSON
-output. Enable `--extract-content-bounds` (Rust/Python
+and `producer` entries when present; these are API-only and never appear in
+CLI JSON output. Enable `extract_document_metadata` (JavaScript/WASM
+`extractDocumentMetadata`) to add `doc_meta`/`docMeta`, a provenance object
+with the `/Info` creation/modification dates, PDF version and encryption
+permissions, signature state, incremental-save markers, trailer ID comparison,
+the document catalog's XMP packet (capped at 64 KiB, with `xmp_truncated`
+when it was cut), and source file size. It is off by default because it
+streams the whole source file once; it is absent for inputs converted from a
+non-PDF format, where the facts would describe the intermediate PDF rather
+than your file. `xmp` needs a structural parse of the document, so it is
+skipped (left absent) for sources over 16 MiB and in WASM builds — the other
+fields are unaffected.
+Enable `--extract-content-bounds` (Rust/Python
`extract_content_bounds`, JavaScript/WASM `extractContentBounds`) to add a
per-page `content_bounds`: the union bbox of the page's top-level content
objects in viewport coords (absent for empty pages). Enable
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index dd8e07c..5b0fc8a 100644
--- a/crates/liteparse-napi/src/types.rs
+++ b/crates/liteparse-napi/src/types.rs
@@ -65,6 +65,10 @@ pub struct JsLiteParseConfig {
/// Extract raw XFA packets (name + XML content) into
/// `ParseResult.xfaPackets`. Default false.
pub extract_xfa_packets: Option<bool>,
+ /// Collect document provenance metadata into `ParseResult.docMeta`.
+ /// Default false: it streams the whole source file once. Absent for
+ /// inputs converted from a non-PDF format.
+ pub extract_document_metadata: Option<bool>,
/// Emit each page's `contentBounds` (union bbox of top-level content
/// objects, viewport coords). Default false.
pub extract_content_bounds: Option<bool>,
@@ -188,6 +192,9 @@ impl JsLiteParseConfig {
if let Some(v) = self.extract_xfa_packets {
cfg.extract_xfa_packets = v;
}
+ if let Some(v) = self.extract_document_metadata {
+ cfg.extract_document_metadata = v;
+ }
if let Some(v) = self.extract_content_bounds {
cfg.extract_content_bounds = v;
}
@@ -264,6 +271,7 @@ impl JsLiteParseConfig {
extract_form_fields: Some(cfg.extract_form_fields),
extract_structure_tree: Some(cfg.extract_structure_tree),
extract_xfa_packets: Some(cfg.extract_xfa_packets),
+ extract_document_metadata: Some(cfg.extract_document_metadata),
extract_content_bounds: Some(cfg.extract_content_bounds),
detect_screenshot_rects: Some(cfg.detect_screenshot_rects),
render_form_fields: Some(cfg.render_form_fields),
@@ -874,8 +882,9 @@ pub struct JsParseResult {
pub creator: Option<String>,
/// The document's `/Info` `Producer` entry, when present.
pub producer: Option<String>,
- /// Document-level provenance metadata.
- pub doc_meta: JsDocumentMetadata,
+ /// Document-level provenance metadata; present only when
+ /// `extractDocumentMetadata` is enabled and the input was a real PDF.
+ pub doc_meta: Option<JsDocumentMetadata>,
/// Raw XFA packets; present only when `extractXfaPackets` is enabled.
pub xfa_packets: Option<Vec<JsXfaPacket>>,
}
@@ -894,6 +903,8 @@ pub struct JsDocumentMetadata {
pub trailer_id_pair_differs: Option<bool>,
pub raw_file_size: Option<f64>,
pub xmp: Option<String>,
+ /// True when the catalog's XMP stream exceeded the 64 KiB cap.
+ pub xmp_truncated: Option<bool>,
pub signature_count: Option<u32>,
pub signature_byte_range_reaches_eof: Option<bool>,
}
@@ -912,6 +923,7 @@ impl JsDocumentMetadata {
trailer_id_pair_differs: metadata.trailer_id_pair_differs,
raw_file_size: metadata.raw_file_size.map(|value| value as f64),
xmp: metadata.xmp.clone(),
+ xmp_truncated: metadata.xmp_truncated,
signature_count: metadata.signature_count,
signature_byte_range_reaches_eof: metadata.signature_byte_range_reaches_eof,
}
@@ -1103,7 +1115,7 @@ impl JsParseResult {
form_type: result.form_type,
creator: result.creator.clone(),
producer: result.producer.clone(),
- doc_meta: JsDocumentMetadata::from_rust(&result.doc_meta),
+ doc_meta: result.doc_meta.as_ref().map(JsDocumentMetadata::from_rust),
xfa_packets: result
.xfa_packets
.as_ref()
diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rs
index 851dce7..9cb6ca6 100644
--- a/crates/liteparse-python/src/lib.rs
+++ b/crates/liteparse-python/src/lib.rs
@@ -610,7 +610,7 @@ struct PyParseResult {
#[pyo3(get)]
producer: Option<String>,
#[pyo3(get)]
- doc_meta: PyDocumentMetadata,
+ doc_meta: Option<PyDocumentMetadata>,
#[pyo3(get)]
xfa_packets: Option<Vec<PyXfaPacket>>,
}
@@ -641,6 +641,8 @@ struct PyDocumentMetadata {
#[pyo3(get)]
xmp: Option<String>,
#[pyo3(get)]
+ xmp_truncated: Option<bool>,
+ #[pyo3(get)]
signature_count: Option<u32>,
#[pyo3(get)]
signature_byte_range_reaches_eof: Option<bool>,
@@ -660,6 +662,7 @@ impl From<liteparse::types::DocumentMetadata> for PyDocumentMetadata {
trailer_id_pair_differs: metadata.trailer_id_pair_differs,
raw_file_size: metadata.raw_file_size,
xmp: metadata.xmp,
+ xmp_truncated: metadata.xmp_truncated,
signature_count: metadata.signature_count,
signature_byte_range_reaches_eof: metadata.signature_byte_range_reaches_eof,
}
@@ -729,7 +732,7 @@ impl PyParseResult {
form_type: result.form_type,
creator: result.creator,
producer: result.producer,
- doc_meta: result.doc_meta.into(),
+ doc_meta: result.doc_meta.map(Into::into),
xfa_packets: result.xfa_packets.map(|packets| {
packets
.into_iter()
@@ -1052,6 +1055,8 @@ struct PyLiteParseConfig {
#[pyo3(get)]
extract_xfa_packets: bool,
#[pyo3(get)]
+ extract_document_metadata: bool,
+ #[pyo3(get)]
extract_content_bounds: bool,
#[pyo3(get)]
detect_screenshot_rects: bool,
@@ -1123,6 +1128,7 @@ impl PyLiteParseConfig {
extract_form_fields: cfg.extract_form_fields,
extract_structure_tree: cfg.extract_structure_tree,
extract_xfa_packets: cfg.extract_xfa_packets,
+ extract_document_metadata: cfg.extract_document_metadata,
extract_content_bounds: cfg.extract_content_bounds,
detect_screenshot_rects: cfg.detect_screenshot_rects,
render_form_fields: cfg.render_form_fields,
@@ -1180,6 +1186,7 @@ impl LiteParse {
extract_form_fields = None,
extract_structure_tree = None,
extract_xfa_packets = None,
+ extract_document_metadata = None,
extract_content_bounds = None,
detect_screenshot_rects = None,
render_form_fields = None,
@@ -1214,6 +1221,7 @@ impl LiteParse {
extract_form_fields: Option<bool>,
extract_structure_tree: Option<bool>,
extract_xfa_packets: Option<bool>,
+ extract_document_metadata: Option<bool>,
extract_content_bounds: Option<bool>,
detect_screenshot_rects: Option<bool>,
render_form_fields: Option<bool>,
@@ -1298,6 +1306,9 @@ impl LiteParse {
if let Some(v) = extract_xfa_packets {
cfg.extract_xfa_packets = v;
}
+ if let Some(v) = extract_document_metadata {
+ cfg.extract_document_metadata = v;
+ }
if let Some(v) = extract_content_bounds {
cfg.extract_content_bounds = v;
}
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index 4409e84..f6276ef 100644
--- a/crates/liteparse-wasm/src/lib.rs
+++ b/crates/liteparse-wasm/src/lib.rs
@@ -62,6 +62,9 @@ pub struct LiteParseConfig {
/// Extract raw XFA packets (name + XML content) into
/// `ParseResult.xfaPackets`. Default false.
extract_xfa_packets: Option<bool>,
+ /// Collect document provenance metadata into `ParseResult.docMeta`.
+ /// Default false: it streams the whole source file once.
+ extract_document_metadata: Option<bool>,
/// Emit each page's `contentBounds` (union bbox of top-level content
/// objects, viewport coords). Default false.
extract_content_bounds: Option<bool>,
@@ -170,6 +173,9 @@ impl LiteParseConfig {
if let Some(v) = self.extract_xfa_packets {
cfg.extract_xfa_packets = v;
}
+ if let Some(v) = self.extract_document_metadata {
+ cfg.extract_document_metadata = v;
+ }
if let Some(v) = self.extract_content_bounds {
cfg.extract_content_bounds = v;
}
@@ -248,6 +254,7 @@ impl LiteParseConfig {
extract_form_fields: Some(cfg.extract_form_fields),
extract_structure_tree: Some(cfg.extract_structure_tree),
extract_xfa_packets: Some(cfg.extract_xfa_packets),
+ extract_document_metadata: Some(cfg.extract_document_metadata),
extract_content_bounds: Some(cfg.extract_content_bounds),
ocr_failure_fatal: Some(cfg.ocr_failure_fatal),
ocr_hedge_delays_ms: Some(cfg.ocr_hedge_delays_ms.clone()),
@@ -612,8 +619,10 @@ pub struct ParseResult {
/// The document's `/Info` `Producer` entry, when present.
#[serde(skip_serializing_if = "Option::is_none")]
pub producer: Option<String>,
- /// Document-level provenance metadata.
- pub doc_meta: DocumentMetadata,
+ /// Document-level provenance metadata; present only when
+ /// `extractDocumentMetadata` is enabled and the input was a real PDF.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub doc_meta: Option<DocumentMetadata>,
/// Raw XFA packets; present only when `extractXfaPackets` is enabled.
#[serde(skip_serializing_if = "Option::is_none")]
pub xfa_packets: Option<Vec<XfaPacket>>,
@@ -645,6 +654,10 @@ pub struct DocumentMetadata {
pub raw_file_size: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub xmp: Option<String>,
+ /// True when the catalog's XMP stream exceeded the 64 KiB cap. WASM
+ /// builds never populate `xmp`, so this is always absent there.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub xmp_truncated: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub signature_count: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
@@ -665,6 +678,7 @@ impl From<&liteparse::types::DocumentMetadata> for DocumentMetadata {
trailer_id_pair_differs: metadata.trailer_id_pair_differs,
raw_file_size: metadata.raw_file_size.map(|value| value as f64),
xmp: metadata.xmp.clone(),
+ xmp_truncated: metadata.xmp_truncated,
signature_count: metadata.signature_count,
signature_byte_range_reaches_eof: metadata.signature_byte_range_reaches_eof,
}
@@ -1034,7 +1048,7 @@ impl LiteParse {
form_type: result.form_type,
creator: result.creator.clone(),
producer: result.producer.clone(),
- doc_meta: DocumentMetadata::from(&result.doc_meta),
+ doc_meta: result.doc_meta.as_ref().map(DocumentMetadata::from),
xfa_packets: result.xfa_packets.as_ref().map(|packets| {
packets
.iter()
diff --git a/crates/liteparse/Cargo.toml b/crates/liteparse/Cargo.toml
index 24eb493..bdb5285 100644
--- a/crates/liteparse/Cargo.toml
+++ b/crates/liteparse/Cargo.toml
@@ -31,6 +31,7 @@ blake3 = "1"
clap = { version = "4.5.55", features = ["derive"] }
file-format = { version = "0.29.0", features = ["reader"] }
image = { version = "0.25", default-features = false, features = ["default-formats"] }
+memchr = "2"
ordered-float = "5.3.0"
pdfium = { package = "liteparse-pdfium", version = "1.4.0", path = "../pdfium" }
pdfium-sys = { package = "liteparse-pdfium-sys", version = "1.4.0", path = "../pdfium-sys" }
diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rs
index 74e2699..8961e20 100644
--- a/crates/liteparse/src/config.rs
+++ b/crates/liteparse/src/config.rs
@@ -67,6 +67,11 @@ pub struct LiteParseConfig {
/// yield an empty list.
#[serde(default)]
pub extract_xfa_packets: bool,
+ /// Collect document-level provenance metadata into `ParseResult.doc_meta`.
+ /// Default `false`: `None` for inputs converted from a non-PDF format,
+ /// since the facts would describe the intermediate PDF rather than the caller's file.
+ #[serde(default)]
+ pub extract_document_metadata: bool,
/// Detect solid rectangles and thick lines in rendered page screenshots
/// and attach them to each `ScreenshotResult.rects`. Works on the raster,
/// so it also finds structure in scanned/flattened pages that have no
@@ -215,6 +220,7 @@ impl Default for LiteParseConfig {
extract_structure_tree: false,
extract_content_bounds: false,
extract_xfa_packets: false,
+ extract_document_metadata: false,
detect_screenshot_rects: false,
render_form_fields: false,
ocr_failure_fatal: true,
diff --git a/crates/liteparse/src/conversion.rs b/crates/liteparse/src/conversion.rs
index 8bb407f..dc45223 100644
--- a/crates/liteparse/src/conversion.rs
+++ b/crates/liteparse/src/conversion.rs
@@ -88,6 +88,15 @@ pub struct PdfInputGuard {
temps: Vec<TempDir>,
}
+impl PdfInputGuard {
+ /// True when the resolved input is a temporary PDF produced by converting
+ /// a non-PDF source, so raw-file facts describe the intermediate, not the
+ /// document the caller passed in.
+ pub fn is_converted(&self) -> bool {
+ !self.temps.is_empty()
+ }
+}
+
/// Resolve a document input to a PDF suitable for rendering or text extraction.
///
/// When `reject_text_formats` is true, plain-text files (`.txt`, etc.) return a
diff --git a/crates/liteparse/src/document_metadata.rs b/crates/liteparse/src/document_metadata.rs
index 05f892d..c28ad7b 100644
--- a/crates/liteparse/src/document_metadata.rs
+++ b/crates/liteparse/src/document_metadata.rs
@@ -7,6 +7,13 @@ use std::io::{Read, Seek, SeekFrom};
const SCAN_BUFFER_BYTES: usize = 1 << 20;
const SCAN_OVERLAP: usize = 64;
const XMP_MAX_BYTES: usize = 64 * 1024;
+/// Above this size, resolving the catalog's `/Metadata` object costs more than
+/// the whole parse: lopdf decodes every stream, so a 103 MB file takes ~7.8 s
+/// (worst case measured under the cap is ~0.5 s). Larger documents report no
+/// `xmp` at all rather than a cheaper guess — the first `<?xpacket` in the raw
+/// bytes is frequently an embedded image's packet, not the document's.
+#[cfg(not(target_arch = "wasm32"))]
+const XMP_CATALOG_MAX_FILE_BYTES: u64 = 16 * 1024 * 1024;
pub(crate) fn extract(input: &PdfInput, document: &Document<'_>) -> DocumentMetadata {
let mut metadata = match input {
@@ -30,11 +37,40 @@ pub(crate) fn extract(input: &PdfInput, document: &Document<'_>) -> DocumentMeta
metadata.permissions = Some(document.permissions());
}
let signatures = document.signature_summary(metadata.raw_file_size);
- metadata.signature_count = Some(signatures.count);
+ metadata.signature_count = signatures.count;
metadata.signature_byte_range_reaches_eof = signatures.byte_range_reaches_eof;
+
+ #[cfg(not(target_arch = "wasm32"))]
+ if let Some((xmp, truncated)) = catalog_xmp(input, metadata.raw_file_size) {
+ metadata.xmp = Some(xmp);
+ metadata.xmp_truncated = Some(truncated);
+ }
metadata
}
+/// Read the document catalog's `/Metadata` XMP stream — the only XMP that is
+/// certainly the document's own. `None` when the file is too large to parse
+/// cheaply, has no catalog metadata, or cannot be decoded (encrypted or
+/// damaged); the caller then reports no XMP.
+#[cfg(not(target_arch = "wasm32"))]
+fn catalog_xmp(input: &PdfInput, file_size: Option<u64>) -> Option<(String, bool)> {
+ if file_size? > XMP_CATALOG_MAX_FILE_BYTES {
+ return None;
+ }
+ let document = match input {
+ PdfInput::Path(path) => lopdf::Document::load(path).ok()?,
+ PdfInput::Bytes(bytes) => lopdf::Document::load_mem(bytes).ok()?,
+ };
+ let object = document.catalog().ok()?.get(b"Metadata").ok()?;
+ let stream = document.dereference(object).ok()?.1.as_stream().ok()?;
+ let bytes = stream
+ .decompressed_content()
+ .unwrap_or_else(|_| stream.content.clone());
+ let truncated = bytes.len() > XMP_MAX_BYTES;
+ let text = String::from_utf8_lossy(&bytes[..bytes.len().min(XMP_MAX_BYTES)]).into_owned();
+ (!text.trim().is_empty()).then_some((text, truncated))
+}
+
fn extract_raw_facts<R: Read + Seek>(reader: &mut R) -> DocumentMetadata {
let mut metadata = DocumentMetadata::default();
let file_size = reader.seek(SeekFrom::End(0)).ok();
@@ -45,16 +81,13 @@ fn extract_raw_facts<R: Read + Seek>(reader: &mut R) -> DocumentMetadata {
let mut buffer = vec![0u8; SCAN_BUFFER_BYTES];
let mut carry = 0usize;
- let mut file_offset = 0u64;
let mut eof_count = 0u32;
let mut startxref_count = 0u32;
- let mut xmp_start = None;
loop {
- let got = match reader.read(&mut buffer[carry..]) {
- Ok(got) => got,
- Err(_) => break,
- };
+ // Must be a full fill, not a single `read`: a short read would shrink
+ // the window below a marker's length and lose it entirely.
+ let got = fill_buffer(reader, &mut buffer[carry..]);
let window_len = carry + got;
if window_len == 0 {
break;
@@ -71,15 +104,9 @@ fn extract_raw_facts<R: Read + Seek>(reader: &mut R) -> DocumentMetadata {
b"startxref",
countable,
));
- if xmp_start.is_none()
- && let Some(offset) = find_bytes(window, b"<?xpacket begin")
- {
- xmp_start = Some(file_offset + offset as u64);
- }
if got == 0 {
break;
}
- file_offset += countable as u64;
carry = window_len - countable;
buffer.copy_within(countable..window_len, 0);
}
@@ -89,56 +116,49 @@ fn extract_raw_facts<R: Read + Seek>(reader: &mut R) -> DocumentMetadata {
if let Some(file_size) = file_size {
let tail_start = file_size.saturating_sub(SCAN_BUFFER_BYTES as u64);
- if reader.seek(SeekFrom::Start(tail_start)).is_ok() {
- let mut tail = vec![0u8; (file_size - tail_start) as usize];
- if let Ok(got) = reader.read(&mut tail) {
- tail.truncate(got);
- metadata.trailer_id_pair_differs = trailer_id_pair_differs(&tail);
- }
+ if reader.seek(SeekFrom::Start(tail_start)).is_ok()
+ && let Some(tail) = read_up_to(reader, (file_size - tail_start) as usize)
+ {
+ metadata.trailer_id_pair_differs = trailer_id_pair_differs(&tail);
}
}
- if let Some(xmp_start) = xmp_start
- && reader.seek(SeekFrom::Start(xmp_start)).is_ok()
- {
- let mut xmp = vec![0u8; XMP_MAX_BYTES];
- if let Ok(got) = reader.read(&mut xmp) {
- xmp.truncate(got);
- if let Some(packet_end) = find_bytes(&xmp, b"<?xpacket end") {
- let suffix = &xmp[packet_end..];
- let end = find_bytes(suffix, b"?>")
- .map(|offset| packet_end + offset + 2)
- .unwrap_or(packet_end + b"<?xpacket end".len());
- xmp.truncate(end.min(xmp.len()));
- }
- metadata.xmp = Some(String::from_utf8_lossy(&xmp).into_owned());
+ metadata
+}
+
+/// Read up to `max` bytes, retrying short reads. `None` when the reader
+/// yielded nothing at all.
+fn read_up_to<R: Read>(reader: &mut R, max: usize) -> Option<Vec<u8>> {
+ let mut buffer = vec![0u8; max];
+ let got = fill_buffer(reader, &mut buffer);
+ buffer.truncate(got);
+ (got > 0).then_some(buffer)
+}
+
+/// Fill `buf` completely, looping over short reads. Returns the byte count,
+/// short only at EOF or on a read error.
+fn fill_buffer<R: Read>(reader: &mut R, buf: &mut [u8]) -> usize {
+ let mut filled = 0;
+ while filled < buf.len() {
+ match reader.read(&mut buf[filled..]) {
+ Ok(0) => break,
+ Ok(got) => filled += got,
+ Err(ref e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
+ Err(_) => break,
}
}
-
- metadata
+ filled
}
fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option<usize> {
- (!needle.is_empty() && haystack.len() >= needle.len())
- .then(|| {
- haystack
- .windows(needle.len())
- .position(|part| part == needle)
- })
- .flatten()
+ memchr::memmem::find(haystack, needle)
}
fn count_occurrences_before(haystack: &[u8], needle: &[u8], start_limit: usize) -> u32 {
- let mut count = 0u32;
- let mut cursor = 0usize;
- while let Some(offset) = find_bytes(&haystack[cursor..], needle) {
- if cursor + offset >= start_limit {
- break;
- }
- count = count.saturating_add(1);
- cursor += offset + needle.len();
- }
- count
+ memchr::memmem::find_iter(haystack, needle)
+ .take_while(|offset| *offset < start_limit)
+ .count()
+ .min(u32::MAX as usize) as u32
}
fn trailer_id_pair_differs(bytes: &[u8]) -> Option<bool> {
@@ -182,17 +202,39 @@ mod tests {
#[test]
fn extracts_raw_provenance_facts() {
let pdf = b"%PDF-1.4\n/ID [<aaaa><bbbb>]\nstartxref\n1\n%%EOF\n\
- update\n/ID [ <cccc> <dddd> ]\nstartxref\n2\n%%EOF\n\
- <?xpacket begin='x'?><x:xmpmeta>ok</x:xmpmeta><?xpacket end='w'?>tail";
+ update\n/ID [ <cccc> <dddd> ]\nstartxref\n2\n%%EOF\ntail";
let metadata = extract_raw_facts(&mut std::io::Cursor::new(pdf));
assert_eq!(metadata.raw_file_size, Some(pdf.len() as u64));
assert_eq!(metadata.eof_section_count, Some(2));
assert_eq!(metadata.startxref_count, Some(2));
assert_eq!(metadata.trailer_id_pair_differs, Some(true));
- assert_eq!(
- metadata.xmp.as_deref(),
- Some("<?xpacket begin='x'?><x:xmpmeta>ok</x:xmpmeta><?xpacket end='w'?>")
- );
+ // XMP comes from the catalog only; the raw scan never guesses at it.
+ assert_eq!(metadata.xmp, None);
+ }
+
+ /// A reader that hands back one byte at a time, like a slow pipe.
+ struct DripReader(std::io::Cursor<Vec<u8>>);
+
+ impl Read for DripReader {
+ fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+ let take = buf.len().min(1);
+ self.0.read(&mut buf[..take])
+ }
+ }
+
+ impl Seek for DripReader {
+ fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
+ self.0.seek(pos)
+ }
+ }
+
+ #[test]
+ fn short_reads_do_not_lose_markers_or_the_trailer() {
+ let pdf = b"%PDF-1.4\nbody\n/ID [<aaaa><bbbb>]\nstartxref\n1\n%%EOF\n";
+ let metadata = extract_raw_facts(&mut DripReader(std::io::Cursor::new(pdf.to_vec())));
+ assert_eq!(metadata.trailer_id_pair_differs, Some(true));
+ assert_eq!(metadata.startxref_count, Some(1));
+ assert_eq!(metadata.eof_section_count, Some(1));
}
#[test]
@@ -207,13 +249,9 @@ mod tests {
#[test]
fn finds_markers_that_cross_scan_chunks_without_double_counting() {
let mut pdf = vec![b'x'; SCAN_BUFFER_BYTES - 7];
- pdf.extend_from_slice(b"startxref\n%%EOF\n<?xpacket begin='x'?>payload");
+ pdf.extend_from_slice(b"startxref\n%%EOF\npayload");
let metadata = extract_raw_facts(&mut std::io::Cursor::new(pdf));
assert_eq!(metadata.startxref_count, Some(1));
assert_eq!(metadata.eof_section_count, Some(1));
- assert_eq!(
- metadata.xmp.as_deref(),
- Some("<?xpacket begin='x'?>payload")
- );
}
}
diff --git a/crates/liteparse/src/output/json.rs b/crates/liteparse/src/output/json.rs
index 173d9db..bccbf76 100644
--- a/crates/liteparse/src/output/json.rs
+++ b/crates/liteparse/src/output/json.rs
@@ -395,7 +395,7 @@ mod tests {
form_type: None,
creator: Some("LibreOffice".into()),
producer: Some("LibreOffice 7.4".into()),
- doc_meta: crate::types::DocumentMetadata::default(),
+ doc_meta: Some(crate::types::DocumentMetadata::default()),
xfa_packets: Some(vec![crate::types::XfaPacket {
index: 0,
name: Some("datasets".into()),
diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rs
index 43a865b..afd9d10 100644
--- a/crates/liteparse/src/parser.rs
+++ b/crates/liteparse/src/parser.rs
@@ -45,7 +45,9 @@ pub struct ParseResult {
pub producer: Option<String>,
/// Document provenance metadata (dates, version/security, signatures,
/// incremental-save markers, trailer IDs, raw XMP, and source size).
- pub doc_meta: DocumentMetadata,
+ /// Present only when `extract_document_metadata` is enabled, and `None`
+ /// for inputs converted from a non-PDF format.
+ pub doc_meta: Option<DocumentMetadata>,
/// Raw XFA packets, present only when `extract_xfa_packets` is enabled.
/// `Some([])` means extraction ran on a non-XFA document.
pub xfa_packets: Option<Vec<XfaPacket>>,
@@ -364,6 +366,13 @@ impl LiteParse {
let (validated_input, _guard) =
conversion::resolve_pdf_input(input, self.config.password.as_deref(), false).await?;
+ // Provenance facts describe the file on disk, so they are meaningless
+ // for a PDF we generated ourselves from a DOCX/XLSX/image.
+ #[cfg(not(target_arch = "wasm32"))]
+ let want_doc_meta = self.config.extract_document_metadata && !_guard.is_converted();
+ #[cfg(target_arch = "wasm32")]
+ let want_doc_meta = self.config.extract_document_metadata;
+
#[cfg(target_arch = "wasm32")]
let validated_input = input;
@@ -460,16 +469,18 @@ impl LiteParse {
.then(|| document.form_type());
let creator = document.meta_text("Creator");
let producer = document.meta_text("Producer");
- #[cfg(not(target_arch = "wasm32"))]
- let doc_meta = if repaired_input.is_some() {
- let source_document =
- extract::load_document_from_input(&lib, &validated_input, password)?;
- crate::document_metadata::extract(&validated_input, &source_document)
- } else {
+ let doc_meta = want_doc_meta.then(|| {
+ // AcroForm repair rewrites the file, so provenance has to come
+ // from the original document; fall back if it no longer loads.
+ #[cfg(not(target_arch = "wasm32"))]
+ if repaired_input.is_some()
+ && let Ok(source) =
+ extract::load_document_from_input(&lib, &validated_input, password)
+ {
+ return crate::document_metadata::extract(&validated_input, &source);
+ }
crate::document_metadata::extract(&validated_input, &document)
- };
- #[cfg(target_arch = "wasm32")]
- let doc_meta = crate::document_metadata::extract(&validated_input, &document);
+ });
let xfa_packets = self.config.extract_xfa_packets.then(|| {
document
.xfa_packets()
@@ -688,7 +699,7 @@ impl LiteParse {
form_type: None,
creator: None,
producer: None,
- doc_meta: DocumentMetadata::default(),
+ doc_meta: None,
xfa_packets: None,
}
}
diff --git a/crates/liteparse/src/types.rs b/crates/liteparse/src/types.rs
index 01e55f9..b557ab0 100644
--- a/crates/liteparse/src/types.rs
+++ b/crates/liteparse/src/types.rs
@@ -27,17 +27,29 @@ pub struct DocumentMetadata {
pub security_handler_revision: Option<i32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub permissions: Option<u64>,
+ /// Literal `%%EOF` markers in the file. A rough incremental-update signal:
+ /// embedded PDF attachments and content-stream text inflate it.
#[serde(skip_serializing_if = "Option::is_none")]
pub eof_section_count: Option<u32>,
+ /// Literal `startxref` markers in the file, with the same caveat.
#[serde(skip_serializing_if = "Option::is_none")]
pub startxref_count: Option<u32>,
+ /// Whether the two halves of the last trailer `/ID` array differ, which
+ /// usually means the file was updated after creation. `None` when no
+ /// hex-string `/ID` pair was found in the last 1 MiB.
#[serde(skip_serializing_if = "Option::is_none")]
pub trailer_id_pair_differs: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub raw_file_size: Option<u64>,
- /// Raw XMP packet text, capped at 64 KiB.
+ /// The document catalog's `/Metadata` XMP packet, capped at 64 KiB.
+ /// `None` when the document has none, when it is too large to resolve
+ /// cheaply (see `extract_document_metadata`), or in WASM builds.
#[serde(skip_serializing_if = "Option::is_none")]
pub xmp: Option<String>,
+ /// True when the catalog's XMP stream exceeded the 64 KiB cap and `xmp`
+ /// holds only its first 64 KiB.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub xmp_truncated: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub signature_count: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rs
index 42e5c6c..e08528d 100644
--- a/crates/liteparse/tests/integration_test.rs
+++ b/crates/liteparse/tests/integration_test.rs
@@ -153,6 +153,7 @@ async fn test_parse_office_doc_integration() {
async fn test_parse_pdf_integration() {
let lit = LiteParse::new(LiteParseConfig {
ocr_enabled: false,
+ extract_document_metadata: true,
..LiteParseConfig::default()
});
let parsed = lit
@@ -160,16 +161,27 @@ async fn test_parse_pdf_integration() {
.await
.expect("Should be able to parse");
assert_eq!(parsed.pages.len(), 1);
- assert!(parsed.doc_meta.file_version.is_some());
- assert_eq!(parsed.doc_meta.is_encrypted, Some(false));
- assert!(parsed.doc_meta.raw_file_size.is_some_and(|size| size > 0));
- assert!(
- parsed
- .doc_meta
- .eof_section_count
- .is_some_and(|count| count > 0)
- );
- assert_eq!(parsed.doc_meta.signature_count, Some(0));
+ let doc_meta = parsed.doc_meta.expect("doc_meta requested");
+ assert!(doc_meta.file_version.is_some());
+ assert_eq!(doc_meta.is_encrypted, Some(false));
+ assert!(doc_meta.raw_file_size.is_some_and(|size| size > 0));
+ assert!(doc_meta.eof_section_count.is_some_and(|count| count > 0));
+ assert_eq!(doc_meta.signature_count, Some(0));
+}
+
+/// Provenance is opt-in and stays absent on the default path.
+#[tokio::test]
+#[serial]
+async fn test_doc_meta_absent_unless_requested() {
+ let lit = LiteParse::new(LiteParseConfig {
+ ocr_enabled: false,
+ ..LiteParseConfig::default()
+ });
+ let parsed = lit
+ .parse("../../integration_tests_data/sample.pdf")
+ .await
+ .expect("Should be able to parse");
+ assert!(parsed.doc_meta.is_none());
}
#[tokio::test]
@@ -178,6 +190,7 @@ async fn test_parse_bytes_pdf_integration() {
let fixture_path = "../../integration_tests_data/sample.pdf";
let lit = LiteParse::new(LiteParseConfig {
ocr_enabled: false,
+ extract_document_metadata: true,
..LiteParseConfig::default()
});
let data = tokio::fs::read(fixture_path)
@@ -190,7 +203,10 @@ async fn test_parse_bytes_pdf_integration() {
.await
.expect("Should be able to parse");
assert_eq!(parsed.pages.len(), 1);
- assert_eq!(parsed.doc_meta.raw_file_size, Some(expected_size));
+ assert_eq!(
+ parsed.doc_meta.and_then(|meta| meta.raw_file_size),
+ Some(expected_size)
+ );
}
/// Stress test: many concurrent `parse_input` calls on a multi-threaded
diff --git a/crates/pdfium-sys/src/dynamic.rs b/crates/pdfium-sys/src/dynamic.rs
index 7a595e8..9248c9c 100644
--- a/crates/pdfium-sys/src/dynamic.rs
+++ b/crates/pdfium-sys/src/dynamic.rs
@@ -23,6 +23,17 @@ macro_rules! load_fn {
}};
}
+/// Like `load_fn!`, but yields `None` instead of failing the whole load when
+/// the symbol is missing. For APIs a trimmed pdfium build may omit — callers
+/// must degrade gracefully rather than assume the function exists.
+macro_rules! load_fn_opt {
+ ($lib:expr, $name:literal) => {{
+ unsafe { $lib.get::<*const ()>($name.as_bytes()) }
+ .ok()
+ .map(|sym| unsafe { std::mem::transmute(*sym) })
+ }};
+}
+
/// Holds all pdfium function pointers loaded at runtime.
pub struct PdfiumBindings {
// Keep the library handle alive — dropping it would unload the symbols.
@@ -71,14 +82,18 @@ pub struct PdfiumBindings {
unsafe extern "C" fn(FPDF_DOCUMENT, *mut std::os::raw::c_int) -> FPDF_BOOL,
pub FPDF_GetSecurityHandlerRevision: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int,
pub FPDF_GetDocPermissions: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_ulong,
- pub FPDF_GetSignatureCount: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int,
+ // `fpdf_signature` is absent from some trimmed pdfium builds, so these
+ // three load optionally and callers fall back to "no signature info".
+ pub FPDF_GetSignatureCount: Option<unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int>,
pub FPDF_GetSignatureObject:
- unsafe extern "C" fn(FPDF_DOCUMENT, std::os::raw::c_int) -> FPDF_SIGNATURE,
- pub FPDFSignatureObj_GetByteRange: unsafe extern "C" fn(
- FPDF_SIGNATURE,
- *mut std::os::raw::c_int,
- std::os::raw::c_ulong,
- ) -> std::os::raw::c_ulong,
+ Option<unsafe extern "C" fn(FPDF_DOCUMENT, std::os::raw::c_int) -> FPDF_SIGNATURE>,
+ pub FPDFSignatureObj_GetByteRange: Option<
+ unsafe extern "C" fn(
+ FPDF_SIGNATURE,
+ *mut std::os::raw::c_int,
+ std::os::raw::c_ulong,
+ ) -> std::os::raw::c_ulong,
+ >,
pub FPDF_GetXFAPacketCount: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int,
pub FPDF_GetXFAPacketName: unsafe extern "C" fn(
FPDF_DOCUMENT,
@@ -539,9 +554,9 @@ impl PdfiumBindings {
FPDF_GetFileVersion: load_fn!(lib, "FPDF_GetFileVersion"),
FPDF_GetSecurityHandlerRevision: load_fn!(lib, "FPDF_GetSecurityHandlerRevision"),
FPDF_GetDocPermissions: load_fn!(lib, "FPDF_GetDocPermissions"),
- FPDF_GetSignatureCount: load_fn!(lib, "FPDF_GetSignatureCount"),
- FPDF_GetSignatureObject: load_fn!(lib, "FPDF_GetSignatureObject"),
- FPDFSignatureObj_GetByteRange: load_fn!(lib, "FPDFSignatureObj_GetByteRange"),
+ FPDF_GetSignatureCount: load_fn_opt!(lib, "FPDF_GetSignatureCount"),
+ FPDF_GetSignatureObject: load_fn_opt!(lib, "FPDF_GetSignatureObject"),
+ FPDFSignatureObj_GetByteRange: load_fn_opt!(lib, "FPDFSignatureObj_GetByteRange"),
FPDF_GetXFAPacketCount: load_fn!(lib, "FPDF_GetXFAPacketCount"),
FPDF_GetXFAPacketName: load_fn!(lib, "FPDF_GetXFAPacketName"),
FPDF_GetXFAPacketContent: load_fn!(lib, "FPDF_GetXFAPacketContent"),
diff --git a/crates/pdfium/src/document.rs b/crates/pdfium/src/document.rs
index 19d2ea8..d7c42e0 100644
--- a/crates/pdfium/src/document.rs
+++ b/crates/pdfium/src/document.rs
@@ -51,13 +51,51 @@ pub struct XfaPacket {
}
/// Signature summary used for document provenance metadata.
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, Default)]
pub struct SignatureSummary {
- pub count: u32,
+ /// `None` when the loaded pdfium build has no signature API, which is not
+ /// the same as a document with zero signatures.
+ pub count: Option<u32>,
/// `None` when signatures exist but PDFium did not expose any byte range.
pub byte_range_reaches_eof: Option<bool>,
}
+/// The `fpdf_signature` entry points, resolved together. `None` when the
+/// loaded pdfium build does not export them.
+struct SignatureApi {
+ count: unsafe extern "C" fn(pdfium_sys::FPDF_DOCUMENT) -> std::os::raw::c_int,
+ object: unsafe extern "C" fn(
+ pdfium_sys::FPDF_DOCUMENT,
+ std::os::raw::c_int,
+ ) -> pdfium_sys::FPDF_SIGNATURE,
+ byte_range: unsafe extern "C" fn(
+ pdfium_sys::FPDF_SIGNATURE,
+ *mut std::os::raw::c_int,
+ std::os::raw::c_ulong,
+ ) -> std::os::raw::c_ulong,
+}
+
+impl SignatureApi {
+ #[cfg(not(target_arch = "wasm32"))]
+ fn load() -> Option<Self> {
+ let bindings = pdfium_sys::dynamic::pdfium();
+ Some(Self {
+ count: bindings.FPDF_GetSignatureCount?,
+ object: bindings.FPDF_GetSignatureObject?,
+ byte_range: bindings.FPDFSignatureObj_GetByteRange?,
+ })
+ }
+
+ #[cfg(target_arch = "wasm32")]
+ fn load() -> Option<Self> {
+ Some(Self {
+ count: pdfium_sys::FPDF_GetSignatureCount,
+ object: pdfium_sys::FPDF_GetSignatureObject,
+ byte_range: pdfium_sys::FPDFSignatureObj_GetByteRange,
+ })
+ }
+}
+
impl<'lib> Document<'lib> {
pub fn page_count(&self) -> i32 {
unsafe { ffi!(FPDF_GetPageCount(self.handle)) }
@@ -159,31 +197,36 @@ impl<'lib> Document<'lib> {
}
/// Count signatures and determine whether every readable final byte-range
- /// segment reaches the current end of the file.
+ /// segment reaches the current end of the file. Needs `file_size` to answer
+ /// the byte-range question at all — without it the verdict stays `None`
+ /// rather than defaulting to "reaches EOF".
pub fn signature_summary(&self, file_size: Option<u64>) -> SignatureSummary {
const MAX_BYTE_RANGE_VALUES: usize = 8;
- let count = unsafe { ffi!(FPDF_GetSignatureCount(self.handle)) }.max(0) as u32;
- if count == 0 {
+ let Some(api) = SignatureApi::load() else {
+ return SignatureSummary::default();
+ };
+ let count = unsafe { (api.count)(self.handle) }.max(0) as u32;
+ let Some(file_size) = file_size.filter(|_| count > 0) else {
return SignatureSummary {
- count,
+ count: Some(count),
byte_range_reaches_eof: None,
};
- }
+ };
let mut known = false;
let mut reaches_eof = true;
for index in 0..count {
- let signature = unsafe { ffi!(FPDF_GetSignatureObject(self.handle, index as i32)) };
+ let signature = unsafe { (api.object)(self.handle, index as i32) };
if signature.is_null() {
continue;
}
let mut ranges = [0i32; MAX_BYTE_RANGE_VALUES];
let len = unsafe {
- ffi!(FPDFSignatureObj_GetByteRange(
+ (api.byte_range)(
signature,
ranges.as_mut_ptr(),
ranges.len() as std::os::raw::c_ulong,
- ))
+ )
} as usize;
if !(2..=MAX_BYTE_RANGE_VALUES).contains(&len) {
continue;
@@ -191,18 +234,17 @@ impl<'lib> Document<'lib> {
known = true;
let start = i64::from(ranges[len - 2]);
let length = i64::from(ranges[len - 1]);
- if let Some(file_size) = file_size
- && (start < 0
- || length < 0
- || u64::try_from(start + length)
- .ok()
- .is_some_and(|range_end| range_end < file_size))
+ if start < 0
+ || length < 0
+ || u64::try_from(start + length)
+ .ok()
+ .is_some_and(|range_end| range_end < file_size)
{
reaches_eof = false;
}
}
SignatureSummary {
- count,
+ count: Some(count),
byte_range_reaches_eof: known.then_some(reaches_eof),
}
}
diff --git a/packages/node/README.md b/packages/node/README.md
index 155e44d..3666b7f 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -99,10 +99,13 @@ all tagged-PDF roots and recursive elements with type, ID, actual/alternate text
title, typed attributes, MCIDs, children, and referenced link annotations. Untagged
pages have an empty `roots` array; the field is omitted when disabled.
-Every result also carries the document's `/Info` `creator`/`producer` and a
-`docMeta` provenance object with dates, PDF version/security, signature state,
-incremental-save markers, trailer ID comparison, raw XMP (capped at 64 KiB),
-and source size. These are API-level only, not in CLI JSON. With `extractContentBounds`
+Every result also carries the document's `/Info` `creator`/`producer` when
+present. With `extractDocumentMetadata`, `result.docMeta` adds a provenance
+object with dates, PDF version/security, signature state, incremental-save
+markers, trailer ID comparison, the catalog's XMP packet (capped at 64 KiB;
+skipped for sources over 16 MiB), and source size — off by default since it
+streams the whole file, and absent for inputs converted from a non-PDF
+format. These are API-level only, not in CLI JSON. With `extractContentBounds`
each page carries a `contentBounds` union bbox of its top-level content
objects. With `extractXfaPackets`, `result.xfaPackets` lists each raw XFA
packet (index, name, content length, XML content); non-XFA documents yield an
diff --git a/packages/node/native.d.ts b/packages/node/native.d.ts
index bc52fc7..db77ecc 100644
--- a/packages/node/native.d.ts
+++ b/packages/node/native.d.ts
@@ -62,6 +62,7 @@ export interface JsLiteParseConfig {
* `ParseResult.xfaPackets`. Default false.
*/
extractXfaPackets?: boolean
+ extractDocumentMetadata?: boolean
/**
* Emit each page's `contentBounds` (union bbox of top-level content
* objects, viewport coords). Default false.
@@ -319,8 +320,11 @@ export interface JsParseResult {
creator?: string
/** The document's `/Info` `Producer` entry, when present. */
producer?: string
- /** Document-level provenance metadata. */
- docMeta: JsDocumentMetadata
+ /**
+ * Document-level provenance metadata; present only when
+ * `extractDocumentMetadata` is enabled and the input was a real PDF.
+ */
+ docMeta?: JsDocumentMetadata
/** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
xfaPackets?: Array<JsXfaPacket>
}
@@ -336,6 +340,7 @@ export interface JsDocumentMetadata {
trailerIdPairDiffers?: boolean
rawFileSize?: number
xmp?: string
+ xmpTruncated?: boolean
signatureCount?: number
signatureByteRangeReachesEof?: boolean
}
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index 16eb162..72382db 100644
--- a/packages/node/src/lib.ts
+++ b/packages/node/src/lib.ts
@@ -46,6 +46,11 @@ export interface LiteParseConfig {
extractStructureTree: boolean;
/** Extract raw XFA packets (name + XML content) into `ParseResult.xfaPackets` (default: false). */
extractXfaPackets: boolean;
+ /**
+ * Collect document provenance metadata into `result.docMeta`. Default
+ * false: Absent for inputs converted from a non-PDF format.
+ */
+ extractDocumentMetadata: boolean;
/** Emit each page's `contentBounds` (union bbox of top-level content objects) (default: false). */
extractContentBounds: boolean;
/** Detect solid rectangles/lines in rendered page screenshots (default: false). */
@@ -351,8 +356,12 @@ export interface ParseResult {
creator?: string;
/** The document's `/Info` `Producer` entry, when present. */
producer?: string;
- /** Document-level provenance metadata from PDFium and the source PDF. */
- docMeta: DocumentMetadata;
+ /**
+ * Document-level provenance metadata from PDFium and the source PDF.
+ * Present only when `extractDocumentMetadata` is enabled and the input was
+ * a real PDF (not converted from DOCX/XLSX/an image).
+ */
+ docMeta?: DocumentMetadata;
/** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
xfaPackets?: XfaPacket[];
}
@@ -370,8 +379,14 @@ export interface DocumentMetadata {
startxrefCount?: number;
trailerIdPairDiffers?: boolean;
rawFileSize?: number;
- /** Raw XMP packet text, capped at 64 KiB. */
+ /**
+ * The document catalog's `/Metadata` XMP packet, capped at 64 KiB. Absent
+ * when the document has none, when it is too large to resolve cheaply, or
+ * in WASM builds.
+ */
xmp?: string;
+ /** True when the catalog's XMP stream exceeded the 64 KiB cap. */
+ xmpTruncated?: boolean;
signatureCount?: number;
/** False when bytes were appended after a readable signature byte range. */
signatureByteRangeReachesEof?: boolean;
@@ -512,6 +527,7 @@ export class LiteParse {
extractFormFields: userConfig.extractFormFields,
extractStructureTree: userConfig.extractStructureTree,
extractXfaPackets: userConfig.extractXfaPackets,
+ extractDocumentMetadata: userConfig.extractDocumentMetadata,
extractContentBounds: userConfig.extractContentBounds,
detectScreenshotRects: userConfig.detectScreenshotRects,
renderFormFields: userConfig.renderFormFields,
@@ -551,6 +567,7 @@ export class LiteParse {
extractFormFields: resolved.extractFormFields ?? false,
extractStructureTree: resolved.extractStructureTree ?? false,
extractXfaPackets: resolved.extractXfaPackets ?? false,
+ extractDocumentMetadata: resolved.extractDocumentMetadata ?? false,
extractContentBounds: resolved.extractContentBounds ?? false,
detectScreenshotRects: resolved.detectScreenshotRects ?? false,
renderFormFields: resolved.renderFormFields ?? false,
diff --git a/packages/node/src/native.ts b/packages/node/src/native.ts
index 9301a02..7194f14 100644
--- a/packages/node/src/native.ts
+++ b/packages/node/src/native.ts
@@ -37,6 +37,7 @@ export interface LiteParseNativeConfig {
extractFormFields?: boolean;
extractStructureTree?: boolean;
extractXfaPackets?: boolean;
+ extractDocumentMetadata?: boolean;
extractContentBounds?: boolean;
detectScreenshotRects?: boolean;
renderFormFields?: boolean;
@@ -239,7 +240,7 @@ export interface NativeParseResult {
formType?: number;
creator?: string;
producer?: string;
- docMeta: NativeDocumentMetadata;
+ docMeta?: NativeDocumentMetadata;
xfaPackets?: NativeXfaPacket[];
}
@@ -255,6 +256,7 @@ export interface NativeDocumentMetadata {
trailerIdPairDiffers?: boolean;
rawFileSize?: number;
xmp?: string;
+ xmpTruncated?: boolean;
signatureCount?: number;
signatureByteRangeReachesEof?: boolean;
}
diff --git a/packages/python/README.md b/packages/python/README.md
index 2380507..ea849d6 100644
--- a/packages/python/README.md
+++ b/packages/python/README.md
@@ -93,10 +93,12 @@ title, typed attributes, MCIDs, children, and referenced link annotations. Untag
pages have an empty ``roots`` list; the field is ``None`` when disabled.
Every result also carries ``creator``/``producer`` from the PDF ``/Info``
-dictionary and a ``doc_meta`` provenance object with dates, PDF
-version/security, signature state, incremental-save markers, trailer ID
-comparison, raw XMP (capped at 64 KiB), and source size. These document fields
-are API-only and do not alter default CLI JSON.
+dictionary. With ``extract_document_metadata=True``, ``result.doc_meta`` adds a
+provenance object with dates, PDF version/security, signature state,
+incremental-save markers, trailer ID comparison, the catalog's XMP packet
+(capped at 64 KiB; skipped for sources over 16 MiB), and source size. It is off by default because it streams the whole source file,
+and it is ``None`` for inputs converted from a non-PDF format. These document
+fields are API-only and do not alter default CLI JSON.
## Parsing from Bytes
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index b5c41b0..56ff32d 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -310,15 +310,10 @@ def _convert_native_result(native_result: Any) -> ParseResult:
]
native_xfa_packets = getattr(native_result, "xfa_packets", None)
native_doc_meta = getattr(native_result, "doc_meta", None)
- return ParseResult(
- pages=pages,
- text=native_result.text,
- images=images,
- image_error_count=getattr(native_result, "image_error_count", 0),
- form_type=getattr(native_result, "form_type", None),
- creator=getattr(native_result, "creator", None),
- producer=getattr(native_result, "producer", None),
- doc_meta=DocumentMetadata(
+ doc_meta = (
+ None
+ if native_doc_meta is None
+ else DocumentMetadata(
creation_date=getattr(native_doc_meta, "creation_date", None),
mod_date=getattr(native_doc_meta, "mod_date", None),
file_version=getattr(native_doc_meta, "file_version", None),
@@ -334,11 +329,22 @@ def _convert_native_result(native_result: Any) -> ParseResult:
),
raw_file_size=getattr(native_doc_meta, "raw_file_size", None),
xmp=getattr(native_doc_meta, "xmp", None),
+ xmp_truncated=getattr(native_doc_meta, "xmp_truncated", None),
signature_count=getattr(native_doc_meta, "signature_count", None),
signature_byte_range_reaches_eof=getattr(
native_doc_meta, "signature_byte_range_reaches_eof", None
),
- ),
+ )
+ )
+ return ParseResult(
+ pages=pages,
+ text=native_result.text,
+ images=images,
+ image_error_count=getattr(native_result, "image_error_count", 0),
+ form_type=getattr(native_result, "form_type", None),
+ creator=getattr(native_result, "creator", None),
+ producer=getattr(native_result, "producer", None),
+ doc_meta=doc_meta,
xfa_packets=(
[
XfaPacket(
@@ -392,6 +398,7 @@ class LiteParse:
extract_form_fields: Optional[bool] = None,
extract_structure_tree: Optional[bool] = None,
extract_xfa_packets: Optional[bool] = None,
+ extract_document_metadata: Optional[bool] = None,
extract_content_bounds: Optional[bool] = None,
detect_screenshot_rects: Optional[bool] = None,
render_form_fields: Optional[bool] = None,
@@ -514,6 +521,8 @@ class LiteParse:
kwargs["extract_structure_tree"] = extract_structure_tree
if extract_xfa_packets is not None:
kwargs["extract_xfa_packets"] = extract_xfa_packets
+ if extract_document_metadata is not None:
+ kwargs["extract_document_metadata"] = extract_document_metadata
if extract_content_bounds is not None:
kwargs["extract_content_bounds"] = extract_content_bounds
if detect_screenshot_rects is not None:
@@ -696,6 +705,7 @@ class LiteParse:
extract_images=cfg.extract_images,
extract_vector_graphics=cfg.extract_vector_graphics,
extract_xfa_packets=cfg.extract_xfa_packets,
+ extract_document_metadata=cfg.extract_document_metadata,
extract_content_bounds=cfg.extract_content_bounds,
detect_screenshot_rects=cfg.detect_screenshot_rects,
)
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index 59eda9e..4f75d9d 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -228,8 +228,12 @@ class DocumentMetadata:
startxref_count: Optional[int] = None
trailer_id_pair_differs: Optional[bool] = None
raw_file_size: Optional[int] = None
- #: Raw XMP packet text, capped at 64 KiB.
+ #: The document catalog's ``/Metadata`` XMP packet, capped at 64 KiB.
+ #: ``None`` when the document has none or it is too large to resolve
+ #: cheaply.
xmp: Optional[str] = None
+ #: True when the catalog's XMP stream exceeded the 64 KiB cap.
+ xmp_truncated: Optional[bool] = None
signature_count: Optional[int] = None
signature_byte_range_reaches_eof: Optional[bool] = None
@@ -247,8 +251,10 @@ class ParseResult:
creator: Optional[str] = None
#: The document's ``/Info`` ``Producer`` entry, when present.
producer: Optional[str] = None
- #: Document-level provenance metadata.
- doc_meta: DocumentMetadata = field(default_factory=DocumentMetadata)
+ #: Document-level provenance metadata. Present only when
+ #: ``extract_document_metadata=True`` and the input was a real PDF
+ #: (not converted from DOCX/XLSX/an image).
+ doc_meta: Optional[DocumentMetadata] = None
#: Raw XFA packets; present only when ``extract_xfa_packets=True``.
xfa_packets: Optional[List[XfaPacket]] = None
@@ -373,6 +379,7 @@ class LiteParseConfig:
extract_images: bool = False
extract_vector_graphics: bool = False
extract_xfa_packets: bool = False
+ extract_document_metadata: bool = False
detect_screenshot_rects: bool = False
extract_content_bounds: bool = False