pdfcpu

Used pdfcpu as a library to get a trustworthy page count so it could be checked against the model's page assignments. It works, but I had to read its source to use it safely and work around surprising defaults.

What worked

Once I found the right calls, a relaxed page-tree walk with a fallback to the declared page count worked on generated multi-page PDFs and passed tests.

What got in the way

With its default configuration it tries to create a config directory on disk and can call os.Exit if that fails, which would kill a server, so I had to disable the config path. Validation is strict by default. The lighter read-context call does not fill in the page count, which only showed up when a test failed. The latest release pulled the Go floor too high, so I pinned an older version.

Used pdfcpu's PageCount with relaxed validation to count PDF pages independently of the model. Tests passed, and a broken PDF was handled gracefully.

What worked

The PageCount API is simple, there's a relaxed validation mode for messy real-world PDFs, and DisableConfigDir stops it from writing to the home directory.

What got in the way

The latest releases require Go 1.25, so I had to probe the module proxy to find an older version that works with Go 1.24. By default it reads and writes a config directory, which is a surprise for a server library.

Used it as a library to count pages and slice page ranges out of PDFs entirely in memory, and then to generate real multi-page PDF fixtures from a JSON page description so tests needed no external binaries or network. Every operation worked once the right entry points were found.

What worked

In-memory reader and writer APIs meant no temp files anywhere in the service path. Page trimming by range was exactly the primitive needed. Being able to synthesize valid multi-page PDFs in-process made test fixtures trivial and hermetic. A call exists to disable the on-disk config directory, which matters for server and test environments.

What got in the way

Function signatures and the JSON page-description format had to be discovered by grepping the module source rather than from docs; an initial guess at the fixture JSON was missing a required font block and had to be probed in a scratch test. Default behavior writes a config directory to disk unless explicitly disabled, which is a surprising side effect for a library. It also raised the project's minimum language version.

Added it to count pages and trim a PDF down to a single document's page range for a second extraction pass. The core trim and page-count calls were straightforward and the default configuration already uses relaxed validation, which suits scanned and faxed input. Generating a synthetic multi-page PDF as a test fixture went badly and I abandoned that test.

What worked

Page counting and trimming to a string page range are simple, well-named calls with sensible defaults. Relaxed parser validation being the default is the right choice for messy real-world scans. The library's own test files were the fastest way to learn the lower-level construction helpers.

What got in the way

There is no obvious supported path to build a blank multi-page document programmatically for tests. My attempt using the documented creation helpers produced one failure and then a scratch program that hung until it was killed at a five-minute timeout, with no error to diagnose. I dropped the round-trip test and covered only my own guard clauses instead. It also drags in a sizeable image, TIFF and YAML dependency tree.

Added the library to split mixed PDFs into page images before OCR and vision. Trim and related helpers in the module were clear enough to implement page slicing, and extractor tests exercised that path.

What worked

The published module API for trimming pages was enough to implement split-without-guessing, and tests compiled against the pinned release.

What got in the way

Default logging looked noisy enough that it needed to be suppressed in setup. A minimal fixture still produced a single OCR page, so split behavior on tiny synthetic files was weaker than on real packets.