Skip to content

feat(pdf-codec): a document-wide decode budget (maxDecodedBytes) - #1815

Open
Mearman wants to merge 3 commits into
mainfrom
feat/pdf-codec-decode-budget
Open

Mearman wants to merge 3 commits into
mainfrom
feat/pdf-codec-decode-budget

Conversation

@Mearman

@Mearman Mearman commented Nov 16, 2026

Copy link
Copy Markdown
Member

Fixes #1814

readPdf, renderPdfPage and openPdfDocument take maxDecodedBytes, one budget charged by every decode the document reaches. The first decode that would pass it throws PdfDecodeBudgetError (a PdfParseError, code pdf/decode-budget-exceeded, carrying maxDecodedBytes, decodedBytes already spent, the stream's objectNumber and its filters). documents.js forwards the option from every pdf conversion and read and re-exports the error.

Decisions

  • One decode path. PdfObjectResolver gains decodeStream(stream, sink) and chargeDecodedBytes(stream, n), and every reader decodes through it instead of importing filters.ts's decodeStream. Only document.ts and xref.ts (which charge the budget themselves) import it, and a test fails if any other module starts to, so a new decode site cannot bypass the budget.
  • Sites covered: cross-reference streams, object streams (on first resolve and during cross-reference recovery), page content streams and /Contents arrays, form XObjects, image XObjects and inline images, /SMask, /Indexed lookups, /Metadata, embedded files, /ToUnicode, /CIDToGIDMap (font read and raster), and font programs for encoding, PostScript name, digest and raster outlines.
  • What counts: every filter stage's output, so [/ASCII85Decode /FlateDecode] pays for both. A predictor is not charged again, since its output is never longer than the stage it rewrites. A stream decoded twice is charged twice (a program two fonts share costs two decodes); the existing per-stream name and digest caches still decode once.
  • Stopping early: Flate inflates through fflate's streaming inflaters, fed in input slices sized to what the remainder can absorb at DEFLATE's maximum expansion (1032 bytes per input byte), keeping inflateTolerant's four recovery tiers. LZW, RunLength and ASCII85 throw at the first byte past the limit. ASCIIHex is refused from its exact size before allocating. CCITTFax is refused from /Rows (or, with none, the most rows its input bits can encode), JBIG2 from /Width and /Height (refused without them), JPEG 2000 from its sample planes before decodeJpeg2000 allocates them (new onSampleAllocation option), and a JPEG renderPdfPage hands to a rasteriser from its frame header. readPdf passes JPEGs through undecoded, so they cost nothing there.
  • A refusal ends the read. readJpeg2000Image rethrows the budget error instead of degrading to "skip this image", and once one decode is refused the budget is spent, so later decodes are refused even through a caller that caught the first error.
  • Encryption: object streams and every resolved stream are decrypted by fetch() before decoding, so the budget charges plaintext decoding. Cross-reference streams are never encrypted. An object stream found by recovery is decoded before the decryptor exists, as it already was, and is charged for whatever that produces.
  • Opt-in. With no budget, decodeStream calls the same unbounded decoders as before (inflateTolerant, not the bounded ladder), so output is unchanged.
  • documents.js boundary: UnifiedConversionOptions, PdfToDocumentOptions, ReadNativeDocumentTreeOptions and ReadDocumentMetadataOptions take maxDecodedBytes and forward it like pages and surfaces: only to the hop that reads the caller's own pdf, never an intermediate pdf a route renders.

Not bounded

Work that produces no decoded bytes: content interpretation, text layout and PNG encoding, which scale with page and content-stream sizes a caller can measure beforehand. JBIG2's intermediate bitmaps stay bounded by its existing per-bitmap ceiling rather than charged.

Tests

  • src/decode-budget.test.ts and src/decode-budget-sites.test.ts: each filter refuses a small stream expanding past the budget, and decodes what fits byte-for-byte as without one (seeded sizes, exact-fit and one-short budgets); inflateTolerantBounded against inflateTolerant over 200 seeded valid, truncated, whitespace-prefixed and raw streams; one document per site whose only large stream is at that site, which reads without a budget and throws naming that object with one (reverting any site's charge makes its test fail); shared font programs charged twice; JPEG 2000 samples; encrypted object streams; renderPdfPage's content, font-program, CIDToGIDMap and JPEG charges; every existing document fixture reads identically with an unlimited budget and with none.
  • src/convert/from-pdf-decode-budget.test.ts (documents.js): each pdf conversion and read refuses with PdfDecodeBudgetError, converts within the budget, and an intermediate pdf is not charged.
  • test/workers/pdf-codec.test.ts: the refusal inside workerd.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pdf-codec: a document-wide decode budget, so a conversion's decoding can be bounded before it runs

1 participant