PiohrunandClaude Opus 5.5
d90cee4669
* fix(render): read each object stream's index once (vendored hayro-syntax patch 22) `XRef::get_with` parsed an object stream's whole index of `objnum offset` pairs again for every object it fetched from that stream, so reading all of a stream of N objects took N² steps. Firefox keeps every object of a page in one stream: the pdf.js corpus file bug1978317.pdf (65,542 objects in one stream) took 37 s to draw and 40 s to extract its text, and was a known timeout in the robustness baseline. The parsed index is now kept per stream, beside the decoded stream data it indexes (`ObjectStreamIndexes`), and never cleared, as that data isn't. A malformed index is remembered as malformed; `/N` or `/First` that can't be read (a reference that can't be followed while another stream loads) is not remembered. An offset past `usize` is malformed instead of wrapping. A poisoned lock is still used: entries are inserted whole. Release build, Linux: bug1978317.pdf draws in 0.5 s (was 37 s) and extracts its text in 1.9 s (was 40 s), and leaves the baseline's known timeouts; 40,000 pages in one stream open in 0.2 s (was 54 s). `raster::tests::objects_in_one_large_object_stream_are_read_in_linear_time` times out at 20 s with the fix reverted and passes in 0.2 s with it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MoEx9Nj8KC4WKDcf5YaokQ * test(render): an object stream offset past usize is malformed, not a panic Review follow-up on #2427. Mutation testing by mtlcl410 found that replacing patch (22)'s `checked_add` in `read_object_stream_index` with a plain `+` survived every test, although in a debug build that `+` panics on the very input it guards against (and wraps in a release build). Their test pins it: it fails with "attempt to add with overflow" under that mutant and passes on this branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
hayro-syntax
A low-level library for reading PDF files.
This crate implements the Syntax chapter of the PDF reference, and therefore
serves as a very good basis for building various abstractions on top of it, without having to reimplement
the PDF parsing logic.
This crate does not provide more high-level functionality, such as parsing fonts or color spaces.
Such functionality is out-of-scope for hayro-syntax, since this crate is supposed to be
as light-weight and application-agnostic as possible.
Functionality-wise, this crate is therefore close to feature-complete. The main missing feature is support for password-protected documents. In addition to that, more low-level APIs might be added in the future.
The crate is no_std compatible but requires an allocator to be available.
Example
This short example shows you how to load a PDF file and iterate over the content streams of all pages.
use hayro_syntax::Pdf;
use std::path::PathBuf;
// First load the data that constitutes the PDF file.
let data = std::fs::read(
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../hayro-tests/pdfs/custom/text_with_rise.pdf"),
)
.unwrap();
// Then create a new PDF file from it.
//
// Here we are just unwrapping in case reading the file failed, but you
// might instead want to apply proper error handling.
let pdf = Pdf::new(data).unwrap();
// First access all pages, and then iterate over the operators of each page's
// content stream and print them.
let pages = pdf.pages();
for page in pages.iter() {
let mut ops = page.typed_operations();
while let Some(op) = ops.next() {
println!("{op:?}");
}
}
Safety
When the unsafe feature is disabled, there is only use of unsafe in hayro-syntax.
We also unconditionally use the smallvec crate which uses unsafe internally, but that's
it.
For better performance, it is strongly recommended to enable the unsafe feature,
which does result in slightly more unsafe code being, but does give better performance:
- We will use the
flate2crate for decoding flate streams. - SIMD will be enabled to accelerate decoding of images.
memchrwill be used to accelerate some of the fallback parsing code.
Features
The supported features include:
- Parsing xref tables in all its possible formats, including xref streams.
- Best-effort attempt at repairing PDF files with broken xref tables.
- Parsing of all objects types (also in object streams).
- Parsing and decoding PDF streams.
- Iterating over pages as well as their content streams in a typed or untyped fashion.
- The crate is very lightweight, especially in comparison to other PDF crates.
Limitations
- There are still a few features missing, for example, support for password-protected PDFs. In addition to that, many properties (like page annotations) are currently not exposed.
- This crate is for read-only processing, you cannot directly use it to manipulate PDF files. If you need to do that, there are other crates in the Rust ecosystem that are suitable for this.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.