Verified page images¶

The page API returns physical geometry and verified PNG images for the document version that a request names. Importing a file does not automatically render it. This API is separate from text extraction and visual previews.

PDF frames use the effective MediaBox, CropBox, and quarter-turn rotation. Boxes are integer 1/10,000 points. Visible width and height are integer 1/10,000 inches. A rational transform maps source coordinates to a top-left origin, x right and y down. Finite PDF coordinates are rounded half away from zero. Invalid crops, non-default UserUnit, and unsupported precision fail. Page dimensions are never guessed from a filename or a default paper size.

Still PNGs need one CRC-valid, metre-based pHYs chunk before image data, with equal nonzero horizontal and vertical density. Animation, EXIF orientation, missing density, and unequal density are unsupported. PNG rendering retains the original bytes. Omit DPI or use zero for native density. A different requested DPI is rejected. Actual numeric DPI is pixels_per_metre * 127 / 5000. PDF requests default to 144 DPI and accept 1–1200 DPI within pixel limits.

Configure the optional runtime¶

Rendering requires Linux amd64 and three pinned compiled executables: the repository-owned inspector, Poppler's pdftoppm, and util-linux prlimit. Other platforms, missing executables, and failed qualification leave rendering unavailable without disabling other Docbank features. Retained frames and images remain readable without a renderer.

Build the inspector from the same source revision as Docbank:

go build -tags fts5 -o bin/ ./document/pagerender/cmd/docbank-page-inspect

Install all three at immutable regular-file paths, resolve symlinks, calculate their SHA-256 digests, and configure config.toml:

[page_runtime]
deployment_identity = "my-qualified-page-runtime-v1"

[page_runtime.inspector]
path = "/opt/docbank/page-runtime/docbank-page-inspect"
sha256 = "<64 lowercase hexadecimal characters>"

[page_runtime.renderer]
path = "/opt/docbank/page-runtime/pdftoppm"
sha256 = "<64 lowercase hexadecimal characters>"

[page_runtime.limiter]
path = "/opt/docbank/page-runtime/prlimit"
sha256 = "<64 lowercase hexadecimal characters>"

The digests are placeholders, not runnable defaults. Recipes record executable digests and observed versions. The operator manages shared libraries, fonts, and color resources. Requalify the deployment and change deployment_identity whenever they change. The identity is an operator declaration. Docbank does not independently verify the resource content, and the runtime is not a hermetic bundle. Different output for a retained exact recipe is a conflict, never an overwrite.

Both PDF inspection and rendering run under pre-exec address-space limits: 2 GiB for the Go inspector, including Go's virtual-memory reservation, and 512 MiB for Poppler. Each phase has 60 seconds. Each job has ten minutes. These are process resource limits, not filesystem or network sandboxing.

Requests are bounded to 16 explicit pages, documents to 1,000 pages, and source bytes to 64 MiB. Output is limited to 40 million decoded pixels, 16,384 pixels per axis, 32 MiB per PNG, and 256 MiB per job. Geometry output has a 16 MiB cap. Diagnostics have a 64 KiB cap. One worker executes jobs, with at most 64 queued or running. Full decoding, dimensions, size, and SHA-256 are verified. PDF output may differ by one pixel per axis from the rounded frame at supported DPI. The receipt records the actual dimensions. PNG dimensions must match exactly. Successful process exit alone does not establish success.

API and retained authority¶

Every request selects a node revision and exact source version, SHA-256, and size. No operation falls back to the current head.

The OpenAPI document describes request fields. Inventory returns complete frame/count authority separately from available images and their actual recipes. A completed job covers its requested pages, not necessarily the whole document. Requests for identical work already queued, running, or completed return that job. Reusing the retained job's operation UUID returns its original result. Submit a new UUID to retry failed or canceled work. Inventory rejects more than 16,000 retained image receipts in one response.

Frames, recipes, and receipts are immutable. Cancellation, source revision changes, and obsolete claims block later publication. Cancellation lets the current render finish but blocks its publication. Restart requeues unfinished jobs with fresh claims. Partial images remain usable and participate in backup, restore verification, and garbage-collection reachability.

Page authority remains with its exact content version and is removed when that version is removed. Attachment/build derivative purge does not purge page images. There is no separate page-purge API. The PyMuPDF text bridge is unchanged.