Merge pull request #892 from cbcoutinho/feat/309-ocr-timeout-pdf-size-guard

feat(document): configurable OCR timeout and fail-fast PDF size guard

tests/unit/test_config.py

@@ -213,6 +213,24 @@ class TestChunkConfigValidation:
         _reload_config()
         assert get_settings().document_chunk_page_aware is False
 
+    def test_ocr_timeout_default_and_env_override(self):
+        """document_ocr_timeout_seconds defaults to 180 and reads its env var.
+
+        Guards the _DEFAULTS-key-must-match-env-var footgun: a mismatch would
+        leave the override silently ignored.
+        """
+        assert Settings().document_ocr_timeout_seconds == pytest.approx(180.0)
+        with patch.dict(os.environ, {"DOCUMENT_OCR_TIMEOUT_SECONDS": "45"}, clear=True):
+            _reload_config()
+            assert get_settings().document_ocr_timeout_seconds == pytest.approx(45.0)
+
+    def test_max_pdf_size_default_and_env_override(self):
+        """document_max_pdf_size_mb defaults to 50 and reads its env var."""
+        assert Settings().document_max_pdf_size_mb == pytest.approx(50.0)
+        with patch.dict(os.environ, {"DOCUMENT_MAX_PDF_SIZE_MB": "12.5"}, clear=True):
+            _reload_config()
+            assert get_settings().document_max_pdf_size_mb == pytest.approx(12.5)
+
     def test_valid_chunk_settings(self):
         """Test valid chunk size and overlap configuration."""
         settings = Settings(
@@ -491,6 +509,22 @@ class TestDynaconfValidators:
         with pytest.raises(ValidationError, match="DOCUMENT_CHUNK_SIZE"):
             _reload_config()
 
+    @patch.dict(os.environ, {"DOCUMENT_OCR_TIMEOUT_SECONDS": "0"}, clear=True)
+    def test_ocr_timeout_zero_rejected(self):
+        """DOCUMENT_OCR_TIMEOUT_SECONDS=0 fails the gte=1 validator."""
+        from dynaconf import ValidationError
+
+        with pytest.raises(ValidationError, match="DOCUMENT_OCR_TIMEOUT_SECONDS"):
+            _reload_config()
+
+    @patch.dict(os.environ, {"DOCUMENT_MAX_PDF_SIZE_MB": "-1"}, clear=True)
+    def test_max_pdf_size_negative_rejected(self):
+        """DOCUMENT_MAX_PDF_SIZE_MB=-1 fails the gte=0 validator (0 = disabled)."""
+        from dynaconf import ValidationError
+
+        with pytest.raises(ValidationError, match="DOCUMENT_MAX_PDF_SIZE_MB"):
+            _reload_config()
+
     @patch.dict(os.environ, {"METRICS_PORT": "8080"}, clear=True)
     def test_valid_metrics_port(self):
         """Test valid METRICS_PORT passes validation."""

tests/unit/test_ocr_processor.py

@@ -3,6 +3,7 @@
 from types import SimpleNamespace
 from typing import Any
 
+import anyio
 import pytest
 
 from nextcloud_mcp_server.document_processors import ocr
@@ -14,6 +15,7 @@ def _settings(**kw) -> Any:  # a Settings stand-in (only the read fields matter)
     base = dict(
         document_ocr_provider="auto",
         document_ocr_model="mistral/mistral-ocr-latest",
+        document_ocr_timeout_seconds=180.0,
         embedding_gateway_url=None,
         embedding_gateway_client_id=None,
         embedding_gateway_client_secret=None,
@@ -128,3 +130,91 @@ async def test_processor_backend_error_returns_success_false(monkeypatch):
     r = await ocr.OcrProcessor().process(b"%PDF-1.7", "application/pdf")
     assert r.success is False
     assert r.metadata["parse_failed_reason"] == "error"
+
+
+async def test_processor_timeout_returns_timeout_reason(monkeypatch):
+    """A backend TimeoutError gets its own reason bucket (not 'error')."""
+
+    class _TimeoutBackend:
+        async def ocr(self, content, mime_type):
+            raise TimeoutError
+
+    monkeypatch.setattr(
+        ocr, "get_settings", lambda: _settings(document_ocr_timeout_seconds=5.0)
+    )
+    monkeypatch.setattr(ocr, "build_ocr_backend", lambda s: _TimeoutBackend())
+    r = await ocr.OcrProcessor().process(b"%PDF-1.7", "application/pdf")
+    assert r.success is False
+    assert r.metadata["parse_failed_reason"] == "timeout"
+    assert "timed out" in r.error
+
+
+async def test_gateway_httpx_timeout_maps_to_timeout_reason(monkeypatch):
+    """A gateway httpx.ReadTimeout (not a builtin TimeoutError) must still map to
+    parse_failed_reason='timeout', not 'error'."""
+    import httpx
+
+    class _HttpxTimeoutBackend:
+        async def ocr(self, content, mime_type):
+            raise httpx.ReadTimeout("read timed out")
+
+    monkeypatch.setattr(
+        ocr, "get_settings", lambda: _settings(document_ocr_timeout_seconds=5.0)
+    )
+    monkeypatch.setattr(ocr, "build_ocr_backend", lambda s: _HttpxTimeoutBackend())
+    r = await ocr.OcrProcessor().process(b"%PDF-1.7", "application/pdf")
+    assert r.success is False
+    assert r.metadata["parse_failed_reason"] == "timeout"
+    assert "timed out" in r.error
+
+
+async def test_gateway_backend_uses_configured_timeout(mocker, monkeypatch):
+    """The gateway OCR call must use DOCUMENT_OCR_TIMEOUT_SECONDS (resolved per
+    call), not the old hardcoded 180s constant."""
+    resp = mocker.Mock()
+    resp.raise_for_status = mocker.Mock()
+    resp.json = mocker.Mock(return_value={"pages": [{"index": 0, "markdown": "ok"}]})
+
+    client = mocker.MagicMock()
+    client.__aenter__ = mocker.AsyncMock(return_value=client)
+    client.__aexit__ = mocker.AsyncMock(return_value=False)
+    client.post = mocker.AsyncMock(return_value=resp)
+
+    captured: dict[str, Any] = {}
+
+    def _make_client(*args, **kwargs):
+        captured["timeout"] = kwargs.get("timeout")
+        return client
+
+    monkeypatch.setattr(ocr.httpx, "AsyncClient", _make_client)
+    monkeypatch.setattr(
+        ocr, "get_settings", lambda: _settings(document_ocr_timeout_seconds=42.0)
+    )
+
+    backend = ocr._GatewayOcrBackend("https://gw", "mistral/mistral-ocr-latest")
+    await backend.ocr(b"%PDF-1.7", "application/pdf")
+
+    # httpx.Timeout(42.0, connect=10.0): the read/overall budget is the setting.
+    assert captured["timeout"].read == pytest.approx(42.0)
+    assert captured["timeout"].connect == pytest.approx(10.0)
+
+
+async def test_mistral_backend_applies_timeout(mocker, monkeypatch):
+    """The Mistral backend wraps process_async in DOCUMENT_OCR_TIMEOUT_SECONDS,
+    so a slow OCR call fails fast instead of hanging on the SDK default."""
+    monkeypatch.setattr(
+        ocr, "get_settings", lambda: _settings(document_ocr_timeout_seconds=0.01)
+    )
+
+    # Bypass the SDK constructor; only the two attributes ocr() reads matter.
+    backend = ocr._MistralOcrBackend.__new__(ocr._MistralOcrBackend)
+    backend._model = "mistral-ocr-latest"
+
+    async def _slow(*args, **kwargs):
+        await anyio.sleep(1.0)
+
+    backend._client = mocker.MagicMock()
+    backend._client.ocr.process_async = _slow
+
+    with pytest.raises(TimeoutError):
+        await backend.ocr(b"%PDF-1.7", "application/pdf")

tests/unit/test_registry_tiering.py

@@ -74,6 +74,9 @@ class _Settings:
         page_fraction=0.5,
         min_page_chars=16,
         detect_scanned=False,
+        # Guard off by default so existing tiering tests are unaffected; tests
+        # that exercise the size guard pass an explicit cap.
+        max_pdf_size_mb=0.0,
     ):
         self.document_tier1_engine = engine
         self.document_classify_enabled = classify
@@ -82,6 +85,7 @@ class _Settings:
         self.document_ocr_page_fraction = page_fraction
         self.document_ocr_min_page_chars = min_page_chars
         self.document_ocr_detect_scanned = detect_scanned
+        self.document_max_pdf_size_mb = max_pdf_size_mb
 
 
 def _registry(*procs: tuple[DocumentProcessor, int]) -> ProcessorRegistry:
@@ -98,6 +102,43 @@ async def test_pdf_routes_to_fast_tier(monkeypatch):
     assert res.processor == "fast"
 
 
+async def test_oversize_pdf_fails_fast_without_parsing(monkeypatch):
+    """A PDF over the size cap must fail fast as 'oversize' before any tier runs."""
+    monkeypatch.setattr(
+        reg_mod, "get_settings", lambda: _Settings(max_pdf_size_mb=0.001)
+    )
+    fast = _Fake("fast", "fast")
+    ran = False
+    orig = fast.process
+
+    async def _tracking(*a, **k):
+        nonlocal ran
+        ran = True
+        return await orig(*a, **k)
+
+    fast.process = _tracking  # type: ignore[method-assign]
+    r = _registry((fast, 20))
+
+    # ~2 KB > 0.001 MB (~1 KB) cap.
+    res = await r.process(b"%PDF-1.7" + b"0" * 2048, "application/pdf", "big.pdf")
+
+    assert res.success is False
+    assert res.metadata["parse_failed_reason"] == "oversize"
+    assert res.processor == "size_guard"
+    assert ran is False, "size guard must short-circuit before the fast tier runs"
+
+
+async def test_under_cap_pdf_still_parses(monkeypatch):
+    """A PDF under the cap is unaffected by the guard."""
+    monkeypatch.setattr(
+        reg_mod, "get_settings", lambda: _Settings(max_pdf_size_mb=10.0)
+    )
+    r = _registry((_Fake("fast", "fast"), 20))
+    res = await r.process(b"%PDF-1.7", "application/pdf")
+    assert res.success is True
+    assert res.processor == "fast"
+
+
 async def test_engine_rollback_uses_structured(monkeypatch):
     monkeypatch.setattr(reg_mod, "get_settings", lambda: _Settings(engine="pymupdf"))
     r = _registry((_Fake("fast", "fast"), 20), (_Fake("structured", "structured"), 10))