PaperForge 1.4.5 — Production Hardening
I’ve just released PaperForge 1.4.5.
The last few releases have followed a fairly deliberate progression.
1.4.3 made rendering easier to understand through validation and diagnostics.
1.4.4 focused on doing less work, allocating less memory, and avoiding repeated computation.
1.4.5 asks the next question:
What happens when PaperForge runs for a long time, under load, or receives input it should not trust?
This release is focused on production hardening.
PDF parsing and writing now support configurable limits for object counts, source size, uncompressed stream data, and nested PDF value depth. Import, diagnostic rendering, and export operations can also run with bounded timeouts.
The goal is that an unexpectedly large, malformed, or hostile document should produce a structured failure rather than consume an unreasonable amount of CPU or memory.
PaperForge now has a stable PF8xxx family of runtime errors for:
- timeouts;
- cancellation;
- resource-limit violations;
- isolated worker failures;
- circuit-open resources;
- concurrent job failures.
These errors are structured and include operation metadata, so they can be consumed by application logs, APIs, monitoring systems, and eventually the Problems panel in PaperForge Studio.
I also added a pure-Elixir circuit breaker for resources that fail repeatedly during PDF processing.
It supports configurable failure thresholds and recovery windows, clears failures after healthy calls, expires inactive entries, and keeps its internal state bounded. Expected document-validation errors do not incorrectly trip the circuit.
Testing was another major part of this release.
PaperForge now has:
- writer → binary → parser round-trip tests;
- StreamData properties for parser invariants;
- declarative atom-safety properties;
- mutated-PDF fuzz testing;
- an opt-in
mix test.fuzztask; - soak-test profiles;
- timeout and cancellation tests;
- crash-isolation coverage;
- concurrent determinism checks;
- temporary-file cleanup tests;
- hostile-input and resource-limit tests.
The current release suite includes 298 regular tests, including 3 property tests, plus 2 dedicated fuzz-profile tests.
CI tests Elixir 1.20.2 on both OTP 28 and OTP 29, with warnings treated as errors.
One interesting issue appeared during the release.
The OTP 28 job found a failure after StreamData generated this mutation sequence:
[:truncate, :truncate, :truncate, :truncate, :truncate, :truncate, :flip]
The parser itself was not failing incorrectly. The fuzz mutator had shortened the PDF until the following byte-flip operation selected a position outside the remaining binary.
That was a useful reminder that fuzz infrastructure must be just as defensive as the code it tests. The mutator is now total for every binary size, and the exact reduced counterexample is preserved as a deterministic regression test.
This release also includes a fix prompted by the first external issue report against PaperForge.
Text inside table cells could cross into the row above because one rendering path treated the top of the cell as if it were the PDF text baseline. Table rendering now calculates a font-aware baseline and consistently applies padding and vertical alignment for both supported coordinate origins.
A minimal reproduction from a real user made this much easier to isolate and verify. That is exactly the kind of feedback I hoped to receive by sharing PaperForge here.
Internally, I also refactored several large areas:
- classic PDF parsing;
- object and stream resolution;
- writer finalization;
- declarative expansion;
- CSS import;
- TrueType cmap parsing;
- EXIF orientation handling;
- validation;
- table rendering.
Strict Credo findings were reduced from 58 to 31 without disabling checks or adding suppressions.
The documentation was consolidated as well. Several overlapping files were removed in favor of the README and a smaller set of focused guides.
The theme of 1.4.5 is:
fail predictably, recover cleanly, and remain stable under pressure.
What comes next: PaperForge 1.5.0
The next release will take PaperForge in a new direction.
Until now, its main workflow has been:
Elixir → PaperForge → PDF
PaperForge 1.5.0 will begin establishing:
Existing PDF → PaperForge → Analysis or transformation → PDF
The working theme is:
PDF Interoperability & Transformation Engine.
The goal is to expand the existing classic PDF parser into a deeper PDF object-graph engine capable of understanding documents produced by other systems.
The planned work includes:
- cross-reference streams;
- compressed object streams;
- hybrid-reference files;
- incremental updates;
- multiple object generations;
- chained trailers;
- inherited page resources;
- additional stream filters;
- supported encrypted PDFs when a password is provided.
I also want to introduce an API along these lines:
{:ok, pdf} = PaperForge.open("contract.pdf")
PaperForge.page_count(pdf)
PaperForge.metadata(pdf)
PaperForge.forms(pdf)
PaperForge.annotations(pdf)
PaperForge.attachments(pdf)
PaperForge.outlines(pdf)
PaperForge.signatures(pdf)
Another important part will be structured PDF analysis:
{:ok, analysis} = PaperForge.analyze(pdf)
That analysis should be able to report:
- PDF version and file structure;
- page and object counts;
- cross-reference type;
- compressed objects;
- incremental revisions;
- fonts and images;
- duplicate resources;
- broken or orphaned references;
- forms and annotations;
- attachments;
- signatures;
- encryption and permissions;
- tagged-PDF information;
- normalization opportunities.
I’m also planning a command-line inspector:
mix paper_forge.inspect document.pdf
The longer-term transformation API should make workflows like this possible:
"input.pdf"
|> PaperForge.open!()
|> PaperForge.delete_pages(10..15)
|> PaperForge.rotate_pages([2, 3], 90)
|> PaperForge.add_watermark("CONFIDENTIAL")
|> PaperForge.update_metadata(title: "Reviewed report")
|> PaperForge.write!("output.pdf")
That creates a path toward merging, splitting, extracting, reordering, normalizing, and incrementally editing existing PDFs.
I don’t expect 1.5.0 to repair every malformed PDF ever produced. PDF compatibility is a very large problem, and real-world files will undoubtedly reveal assumptions that synthetic fixtures cannot.
The priority is to establish a reliable parser, object graph, inspection API, and transformation foundation.
So if you have unusual PDFs, compressed-object files, incrementally updated documents, old reports, forms, signed documents, or files generated by less common tools, I would be very interested in representative samples and compatibility reports.
As always, thank you for the feedback. PaperForge is becoming much better because people are trying it against real documents rather than only the examples I created for it.