Chris CoutinhoandClaude Opus 4.8
8c9339501e
A pathological PDF (a 206-page ChronoScan scan with ~3400 JBIG2/JPX images)
jammed a tenant's structured ingest worker in an infinite reprocess loop,
re-burning a 120s pymupdf4llm parse (and occasionally OOM-racing the 2Gi pod)
every few minutes.
Root cause: the per-user placeholder "failed" mark could not stop the loop. The
placeholder point ID is user-agnostic (uuid5("file:<doc_id>:placeholder")) but
the scanner's freshness gate, query, and status update all filter by user_id.
For a file visible to several users the single shared placeholder's user_id is
overwritten by whoever scanned last, so every other user's scan sees "no record"
and re-queues -- an N-user ping-pong that never honours the failed status.
Fix: when a parse fails terminally (no higher escalation tier available, e.g.
structured with OCR off) record a durable, content-addressed, user-agnostic
dead-letter marker (mirrors vector/sharing_state.py). The scanner consults it
tenant-wide for every user and skips re-queuing until the content (etag) OR the
escalation-tier set (tiers_sig -- e.g. OCR enabled) changes, so the document is
attempted once per content-version instead of forever.
- new vector/dead_letter.py: mark/is/clear, content-addressed marker carrying
is_placeholder=True (inherits search exclusion) + dead_letter=True
- escalation.escalation_tiers_signature(settings): retry-on-tier-change key
- processor: dead-letter terminal failures, clear on successful (re-)index
- scanner: user-agnostic is_dead_lettered skip beside claim_existing_index
- placeholder: exempt dead_letter markers from the orphan sweep (durability)
- metrics: astrolabe_document_dead_lettered_total{reason}
Deck #349.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
43 lines
1.4 KiB
Python
43 lines
1.4 KiB
Python
"""Unit tests for the escalation-tier signature used by dead-letter keying.
|
|
|
|
``escalation_tiers_signature`` fingerprints the runtime escalation config so a
|
|
dead-lettered document becomes retryable when a new tier appears (e.g. an
|
|
operator enables OCR). It must be settings-derived (role-independent) and must
|
|
change when OCR is toggled.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from types import SimpleNamespace
|
|
|
|
import pytest
|
|
|
|
from nextcloud_mcp_server.document_processors.escalation import (
|
|
escalation_tiers_signature,
|
|
)
|
|
|
|
pytestmark = pytest.mark.unit
|
|
|
|
|
|
def _settings(*, ocr: bool, engine: str = "pypdfium2") -> SimpleNamespace:
|
|
return SimpleNamespace(document_ocr_enabled=ocr, document_tier1_engine=engine)
|
|
|
|
|
|
def test_signature_is_stable_for_same_config() -> None:
|
|
assert escalation_tiers_signature(
|
|
_settings(ocr=False)
|
|
) == escalation_tiers_signature(_settings(ocr=False))
|
|
|
|
|
|
def test_enabling_ocr_changes_signature() -> None:
|
|
# Enabling OCR adds an escalation tier -> previously dead-lettered docs retry.
|
|
assert escalation_tiers_signature(
|
|
_settings(ocr=False)
|
|
) != escalation_tiers_signature(_settings(ocr=True))
|
|
|
|
|
|
def test_tier1_engine_change_changes_signature() -> None:
|
|
assert escalation_tiers_signature(
|
|
_settings(ocr=False, engine="pypdfium2")
|
|
) != escalation_tiers_signature(_settings(ocr=False, engine="pymupdf"))
|