Artefact extraction: bound parser resource consumption (memory/decompression + worker), not just wall-clock

[Chris0Jeky]

Context

Follow-up from #1369 / PR #1378, which added a per-extraction wall-clock budget (Artefacts:ExtractionTimeoutSeconds, default 30s). That bounds request latency: the request returns when the budget fires, and a runaway PdfPig PdfDocument.Open(...) is abandoned.

Gap

The wall-clock budget does not bound the parser's actual resource consumption:

1. Abandoned-thread CPU. .NET cannot hard-kill a thread, so an abandoned parser-bomb parse keeps running to completion on a thread-pool thread (CPU + one pool thread held for the full parse). Concurrent bomb submissions could still pressure threads/CPU even though each request returns promptly.
2. Unbounded abandoned-parse accumulation (adversarial-review confirmed residual, PR Bound artefact extraction with a wall-clock budget #1378 round 2). There is no cap on how many abandoned extractions can pile up: N concurrent parser-bomb submissions produce N spinning thread-pool threads that keep burning CPU long after each request recorded its extraction-timeout row and returned. A sustained submission rate above the parse-completion rate grows the abandoned set without bound — thread-pool starvation and CPU exhaustion — so the wall-clock timeout alone must NOT be treated as the DoS boundary. Also flagged independently by chatgpt-codex-connector on PR Bound artefact extraction with a wall-clock budget #1378.
3. Memory / decompression ceiling. There is no bound on the expanded in-memory size (only the compressed 10 MiB input, page, and output-char caps). A FlateDecode decompression bomb that expands massively in memory could exhaust memory before the wall-clock budget fires. (Suggested in Artefact PDF extraction has no wall-clock/parser timeout — parser-bomb DoS (post-merge finding from #1346) #1369 as "add a decompression / allocation ceiling"; intentionally out of scope for the wall-clock slice.)

Why not now

ArtefactExtractionService has no caller yet (not wired to upload/HTTP/worker). The wall-clock budget is the necessary first guard. Real resource bounding needs a heavier design (bounded worker with an allocation/expanded-size ceiling, or process isolation for the parse) and should land before extraction is wired to any request path.

Acceptance (when picked up)

• A configurable expanded/allocation ceiling for a single extraction (bound decompressed size, not just compressed input).
• A hard concurrency cap on parser workers (bounded worker pool or bounded queue with rejection/backpressure) so the abandoned-parse set cannot grow without bound under sustained parser-bomb submissions — including a limit on concurrently abandoned (still-spinning) parses, not just concurrently active requests. This is a hard gate: no request-path or worker wiring of IArtefactExtractionService before this lands.
• A strategy for the abandoned-parse CPU/thread cost (bounded worker pool for extraction, or out-of-process parse) so concurrent bombs cannot exhaust the shared thread pool.
• A regression test using a decompression-bomb-shaped fixture asserting the ceiling aborts extraction and records the standard warning-bearing history row.
• A regression/stress test asserting the concurrency cap holds when submissions exceed capacity (excess submissions are rejected or queued, never unbounded).

References

• Artefact PDF extraction has no wall-clock/parser timeout — parser-bomb DoS (post-merge finding from #1346) #1369 (wall-clock budget defect)
• Bound artefact extraction with a wall-clock budget #1378 (wall-clock budget fix — this follow-up is the tracked residual risk; see the round-2 adversarial-review comment for the accumulation analysis)

[Chris0Jeky]

Design (coordinator, 2026-07-17 overnight run) — ratified for implementation

Verified against the code as of 21197662. Two mechanisms close the three gaps (abandoned-thread CPU, unbounded abandoned accumulation, memory/decompression ceiling), plus tests. No process isolation: for a local-first SQLite app, an out-of-process parse sidecar is disproportionate operational surface; the combination below bounds worst-case consumption to cap × ceiling which is operator-configurable. (ADR to record this trade-off ships with the PR, Proposed.)

1. Extraction permit gate — permits track PARSE-THREAD occupancy, not request lifetime

New Application singleton ArtefactExtractionGate wrapping a SemaphoreSlim(ArtefactStorageSettings.ExtractionMaxConcurrency) (new setting, int, default 2, [Range(1, 64)]).

• ArtefactExtractionService.ExtractAsync acquires with Wait(0) immediately before creating the parse worker task (all extractors, incl. plaintext — uniform). Saturated ⇒ Result.Failure(ErrorCodes.TooManyRequests, ...), no extraction history row (capacity is transient and not a property of the artefact — unlike the ceiling, which is).
• Release points mirror the existing budgetCts.Dispose() discipline exactly: normal completion ⇒ release in the finally when !workerAbandoned; abandoned (budget timeout or caller cancellation) ⇒ release inside the existing AbandonExtraction ContinueWith continuation, i.e. only when the abandoned thread actually finishes. That single property makes the cap cover concurrently-abandoned parses: N bombs exhaust the permits, request N+1 is rejected pre-parse with zero new threads, and CPU burn is bounded at cap spinning threads box-wide.
• This is why rejection (not queueing) is correct at this layer: a queue in front of permits held by spinning bombs is just a second unbounded set. Callers-to-be (upload path / worker, Artefact extraction: bound parser resource consumption (memory/decompression + worker), not just wall-clock #1379 gate) retry on 429.

2. Decompression ceiling — bounded filter provider injected via ParsingOptions.FilterProvider

Verified: PdfPig 0.1.15 (pinned) exposes ParsingOptions.FilterProvider : UglyToad.PdfPig.Filters.IFilterProvider and a public DefaultFilterProvider. New Infrastructure BoundedFilterProvider decorating the default provider; created per parse with a cumulative decoded-bytes counter capped by ArtefactStorageSettings.ExtractionMaxDecodedBytes (new setting, long, default 128 MiB, floor 64 KiB).

• FlateDecode (the practical bomb vector): cheap streaming counting pre-pass over the raw stream bytes with System.IO.Compression.ZLibStream into a fixed 64 KiB discard buffer, aborting the moment the running total exceeds the remaining cumulative budget — the bomb is caught before the real decode materializes anything. Within budget ⇒ delegate to the wrapped default filter (predictors/DecodeParms stay PdfPig's problem; we never reimplement them). Legit files pay one extra bounded inflate — acceptable for ≤10 MiB inputs.
• All filters (backstop): post-decode, add output.Length to the cumulative counter; over ⇒ abort. Catches multi-stream accumulation and non-Flate expansion after materialization.
• LZW (rare, also bombable, no cheap .NET counter): conservative admission — reject an LZW stream when input.Length × 256 > remaining budget (worst-case-ratio bound), recording the same ceiling outcome. Legacy files under the bound decode normally. (Implementer may substitute a real bounded LZW counter if trivially verifiable; not required.)
• Breach ⇒ throw internal ExtractionDecodedSizeLimitException; PdfPigArtefactTextExtractor catches it (both at PdfDocument.Open and per-page GetWords) and returns the standard warning result with new code ArtefactExtractionWarningCodes.DecodedSizeLimit = "decoded-size-limit" — one warning-bearing history row, request returns promptly, no extractor-error misclassification.

3. Tests (acceptance-mapped)

• Bomb fixture (colocated with existing PdfPig extractor tests): minimal in-test-generated PDF whose Flate content stream inflates to ≫ ceiling from a few KiB of input. Assert: decoded-size-limit warning row via the full service path, empty text, completes in ms (pre-pass, not materialization). Parity control: a legit small PDF extracts byte-identical text through BoundedFilterProvider vs default.
• Gate/abandonment (Application.Tests, stub extractor that blocks ignoring cancellation, tiny wall-clock budget): cap=1 → first submission times out and is abandoned (permit still held) → second submission rejected TooManyRequests with no history row → unblock the stub → permit released → third submission succeeds with a history row. This pins the "abandoned parses hold capacity" semantics.
• Stress: cap=2, 8 concurrent submissions against a latched stub → assert max concurrent extractor entries == 2, all excess rejected (never queued/unbounded), no deadlock after release.
• Config validation tests for both new settings mirroring the ExtractionTimeoutSeconds conventions (incl. the double-vs-int Range pitfall documented there).

Docs

docs/platform/CONFIGURATION_REFERENCE.md rows for Artefacts:ExtractionMaxConcurrency and Artefacts:ExtractionMaxDecodedBytes; ADR (Proposed) for in-process bounding vs process isolation; STATUS/masterplan at the wave's docs sweep.

The hard gate stands: still no request-path or worker wiring in this slice — this PR is the prerequisite.