PDF 2.0 Rust library
A reader and writer for PDF 2.0 — the file format defined by ISO 32000-2. No
unsafe, no C dependencies, and the format is implemented in this crate rather
than wrapped: the four dependencies (flate2, aes, cbc, sha2) only supply
DEFLATE and AES/SHA primitives.
Status
The gate is cargo test, cargo fmt --check and
cargo clippy --all-targets -- -D warnings; all three pass on every commit.
Working today:
- Classic cross-reference tables,
/Prevchains and incremental updates. - Cross-reference streams (
/Type /XRefwith/Wand/Index), object streams (/ObjStm) and hybrid files (/XRefStm). - Filters: FlateDecode (with PNG 10–15 and TIFF 2 predictors), LZWDecode,
ASCIIHexDecode, ASCII85Decode and RunLengthDecode, including
/Filterand/DecodeParmsarrays and indirect/Length. - Every base object type, parsed and re-serialized byte-for-byte.
- The document model: catalog, page tree with inherited
/MediaBox,/CropBox,/Rotateand/Resources, page content streams, and XMP/Metadata. - Content-stream interpretation and text extraction for simple fonts:
BT/ET,Tf,Td,TD,T*,TL,Tm,Tj,TJ,',", withStandardEncoding,WinAnsiEncodingand/Differencesarrays. Line breaks come from the positioning operators, spaces from the text itself or from wideTJadjustments; inline images are skipped. - Lazy object fetching with a cache, and every malformed input reported as an
Errinstead of a panic —tests/robustness.rsopens every fixture from every truncation and from sampled mutations and exercises the whole read API on whatever still opens. - Writing PDF 2.0 files:
Document::new()builds a document,add_pageappends pages,save()emits a%PDF-2.0header, a Flate-compressed/ObjStmfor non-stream objects, a compressed/Type /XRefcross-reference stream with recorded byte offsets, XMP/Metadataand notrailer/Infodictionaries. Files written by this crate are read back by it — the writer has no other proof, andtests/writer.rscompares the whole object graph. - AES-256 encryption, read side:
/V 5 /R 6with the standard security handler. User and owner passwords are both accepted; strings, streams, object streams and XMP metadata are decrypted,/EncryptMetadatais honoured, and the/Permstamper check is verified. Deprecated revisions (RC4, AES-128,/R 5) are refused with an error rather than half-implemented.
Limits
Deliberately out of scope: rendering, PDF/A conformance, RC4 and AES-128, the
Info dictionary, form filling, JavaScript, XFA and image codecs (DCT, JPX,
CCITT, JBIG2). A file that needs one of these is reported as an error rather
than silently misread.
Known limits inside the supported surface:
- Text extraction: composite (Type0) fonts and
/ToUnicodeCMaps are reported as unsupported; the upper half ofMacRomanEncodingis not decoded; glyph names outside the built-in table are skipped rather than guessed. Spaces are recognised from the text itself and from wideTJadjustments, not from glyph advance widths. - Encryption is read-only and revision 6 only; the writer always produces unencrypted files.
/Countin a page tree is treated as a hint and never trusted; pages are counted by walking.- No external validator (
qpdf,verapdf,mutool,gs) exists in the environment this was built in. Proof rests on committed fixtures, byte-exact round-trips and cross-checks against independent implementations (NIST SP 800-38A for AES-256-CBC,base64.a85encodefor ASCII85, a separate encoder for LZW, Python for the PNG predictors).
Layout
| Module | Responsibility |
|---|---|
src/error.rs |
one Error enum, no panics in the read paths |
src/lexer.rs |
tokens: whitespace, comments, numbers, names, strings |
src/object.rs |
the object model and its serialization |
src/parser.rs |
objects and indirect objects, streams by /Length |
src/filter.rs |
stream filters and predictors |
src/document.rs |
cross-reference tables and streams, object fetching |
src/page.rs |
page tree, boxes, XMP metadata |
src/content.rs |
content streams and text extraction |
src/crypto.rs |
AES-256 revision 6 security handler |
src/writer.rs |
Document::new() … save() |
Usage
use ;
An encrypted file takes its password:
use Document;
Writing looks like this (also available as cargo run --example write):
use ;
Tests and fixtures
cargo test runs unit tests next to each module, integration tests in
tests/*.rs, and doc-tests that compile the examples above.
The fixtures in tests/fixtures/ are small, committed PDFs, each named after
the structure it proves — see tests/fixtures/README.md. Six are generated by
tests/fixtures/make_fixtures.py (offsets and zlib streams computed there), and
the encryption pair by cargo run --example make_encrypted_fixture, because no
external PDF tool is available to produce them. Both generators are deterministic:
re-running them reproduces every byte.
tests/robustness.rs is the single corpus that opens every fixture from every
truncation, from sampled byte mutations and from single-byte deletions, and then
exercises pages, metadata, content decoding and text extraction on anything that
still opens.
CI and releases
.github/workflows/ci.yml runs the gate in this README's Status section on
stable, on beta and on the declared MSRV (1.87), builds the docs with warnings
denied, and packages the crate.
rust-toolchain.toml pins stable (with rustfmt and clippy) for local work.
The MSRV stays checkable with cargo +1.87 test, because an explicit
+toolchain argument outranks that file — which is also how CI names every
toolchain it uses.
Releases are published from .github/workflows/publish.yml on a v* tag using
crates.io trusted publishing —
OIDC, short-lived tokens, no secrets. See docs/RELEASING.md
for the one-time crates.io configuration and the tag-and-push flow.
Legal
Dual-licensed under MIT or the UNLICENSE.