~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""HTTP contract of the FastAPI exception handlers.
Covers ``_register_exception_handlers`` / ``_is_api_request`` in
``web/fastapi_app.py`` plus ``web/exceptions.py`` rendered over HTTP —
the pieces the Flask-era ``register_error_handlers`` provided:
- 404 returns a fixed body, never a traceback or internal path: JSON for
API paths, ``text/html`` for browser navigations (Flask parity — see
``Test404Contract``).
- 405 keeps FastAPI's JSON detail AND the ``Allow`` header (405 from
routing is a Starlette ``HTTPException``, which the custom
``handle_http_exception`` — registered for *fastapi*'s subclass —
must not intercept, or the header would be dropped).
- 401: browser-Accept requests are redirected to ``/auth/login`` with a
URL-encoded ``next=``; API-path or JSON-Accept requests get JSON, no
redirect.
- Unhandled exceptions become a scrubbed, fixed-shape 500.
- ``WebAPIException`` / ``AuthenticationRequiredError`` render their
sanitized ``to_dict()`` with the exception's own status code.
- ``PolicyDeniedError`` maps to a 400 carrying the decision reason only.
- Malformed JSON body on an endpoint that reads ``await request.json()``
returns 400 (Flask ``request.get_json()`` parity). This 500'd before
the ``json.JSONDecodeError`` handler was added alongside these tests.
Unit-level ``to_dict()`` sanitization is covered in
``test_exceptions_behavior.py`` — not repeated here; these tests drive
the registered handlers through real ASGI request/response cycles.
"""
import importlib
import pytest
from fastapi import FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from starlette.requests import Request as StarletteRequest
from local_deep_research.web.exceptions import (
AuthenticationRequiredError,
WebAPIException,
)
from local_deep_research.web.fastapi_app import (
_is_api_request,
_register_exception_handlers,
)
SECRET_MARKER = "sekrit-internal-detail-xyzzy"
BEARER_TOKEN = "sk-abc123DEF456ghi789" # noqa: S105 - fake credential shape
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture(scope="module")
def real_client():
"""TestClient on the real app — full middleware + handler stack."""
from local_deep_research.web.fastapi_app import app
return TestClient(app, raise_server_exceptions=False)
@pytest.fixture(scope="module")
def handler_client():
"""Minimal app wired through the REAL ``_register_exception_handlers``.
Routes raise on demand so each handler branch can be driven without
depending on which real endpoints happen to be able to fail.
"""
mini = FastAPI()
_register_exception_handlers(mini)
@mini.post("/api/echo")
async def echo(request: Request):
return {"ok": await request.json()}
@mini.get("/api/boom")
async def boom():
raise ValueError(f"{SECRET_MARKER} in /srv/ldr/private/app.py")
@mini.get("/browser-boom")
async def browser_boom():
raise RuntimeError(SECRET_MARKER)
@mini.get("/api/webapi")
async def webapi():
raise WebAPIException(
f"upstream auth failed: Authorization: Bearer {BEARER_TOKEN}",
status_code=418,
error_code="TEAPOT",
)
@mini.get("/api/authreq")
async def authreq():
raise AuthenticationRequiredError(username="alice")
@mini.get("/api/policy")
async def policy():
from local_deep_research.security.egress.policy import (
Decision,
PolicyDeniedError,
)
raise PolicyDeniedError(
Decision(allowed=False, reason="scope_mismatch"),
target=f"https://internal.example/{SECRET_MARKER}",
)
@mini.get("/")
async def root():
raise HTTPException(status_code=401, detail="Authentication required")
@mini.get("/account/{item}")
async def account(item: str):
raise HTTPException(status_code=401, detail="Authentication required")
return TestClient(mini, raise_server_exceptions=False)
def _assert_scrubbed(response):
"""No traceback frames, internal paths, or raise-site text leak out."""
assert SECRET_MARKER not in response.text
assert "Traceback" not in response.text
assert "/home/" not in response.text
assert ".py" not in response.text
# ---------------------------------------------------------------------------
# 404 — real app
# ---------------------------------------------------------------------------
class Test404Contract:
def test_api_404_returns_fixed_json_body(self, real_client):
resp = real_client.get(
"/api/v1/definitely-not-a-route-xyzzy",
headers={"Accept": "application/json"},
)
assert resp.status_code == 404
assert resp.headers["content-type"].startswith("application/json")
assert resp.json() == {"error": "Not found"}
def test_browser_404_returns_html_matching_flask(self, real_client):
# This assertion previously pinned a bare "Not found" text/html
# body, itself a deliberate step up from the original JSON-for-
# everyone behavior. PR #5424 goes one step further: instead of
# unstyled "Not found", browser navigations now get a branded,
# STANDALONE `pages/error.html` page (a way back to the app) --
# it deliberately does NOT extend base.html, so it carries no
# sidebar/route map and no {{ version }} for an unauthenticated
# caller to read off a mistyped URL — the plain-text body was
# itself only a fallback for when rendering that page fails (see
# fastapi_app.py::_render_branded_error_page). Serving
# `{"error": "Not found"}` — or bare "Not found" — to a top-level
# browser navigation is what a user sees after a typo or a stale
# bookmark; this asserts on the stable `data-error-page` /
# `data-status-code` markers from error.html rather than prose,
# matching how PR #5424's own test suite pinned it.
resp = real_client.get(
"/definitely-not-a-page-xyzzy", headers={"Accept": "text/html"}
)
assert resp.status_code == 404
assert resp.headers["content-type"].startswith("text/html")
assert "data-error-page" in resp.text
assert 'data-status-code="404"' in resp.text
def test_browser_404_body_does_not_reflect_request_path(self, real_client):
# The HTML branch must stay a fixed constant. A reflected path in an
# HTML response body is a live XSS channel, not merely a leak as it
# would be in JSON. Check for the request-path fragment itself
# rather than the bare words "script"/"alert" -- the branded,
# standalone pages/error.html page (PR #5424) legitimately contains
# "<script" (its own Vite/HMR bootstrap tags), so a bare-word check
# would be a false positive independent of any real reflection.
resp = real_client.get(
"/not-a-page-<script>alert(1)</script>",
headers={"Accept": "text/html"},
)
assert resp.status_code == 404
assert "not-a-page" not in resp.text
assert "<script>alert(1)</script>" not in resp.text
def test_404_body_does_not_reflect_request_path(self, real_client):
# Reflected-path 404 pages are an XSS/leak channel; body is fixed.
resp = real_client.get("/api/xyzzy-<script>-payload")
assert resp.status_code == 404
assert "xyzzy" not in resp.text
assert "script" not in resp.text
# ---------------------------------------------------------------------------
# 405 — real app
# ---------------------------------------------------------------------------
@pytest.mark.parametrize("status_code", [404, 413])
def test_branded_error_pages_omit_app_version(
real_client, monkeypatch, status_code
):
"""Shared template context must not leak through rendered HTML comments."""
version_module = importlib.import_module("local_deep_research.__version__")
private_version = "private-build-marker-for-error-page"
monkeypatch.setattr(version_module, "__version__", private_version)
headers = {"Accept": "text/html"}
if status_code == 413:
# Only a declared size: no oversized body is allocated or sent.
headers["Content-Length"] = str(1 << 40)
response = real_client.get(
"/missing-branded-version-probe", headers=headers
)
assert response.status_code == status_code
assert response.headers["content-type"].startswith("text/html")
assert "data-error-page" in response.text
assert f'data-status-code="{status_code}"' in response.text
assert private_version not in response.text
class Test405Contract:
def test_405_json_detail_and_allow_header(self, real_client):
# GET on a POST-only route; GET is CSRF-safe so the request
# reaches routing. The Allow header is REQUIRED on 405 — it
# survives only because Starlette's routing-raised HTTPException
# falls through to FastAPI's default handler (the custom
# handle_http_exception would drop exc.headers).
resp = real_client.get(
"/auth/logout", headers={"Accept": "application/json"}
)
assert resp.status_code == 405
assert resp.json() == {"detail": "Method Not Allowed"}
assert "POST" in resp.headers.get("allow", "")
def test_405_browser_accept_same_shape(self, real_client):
resp = real_client.get("/auth/logout", headers={"Accept": "text/html"})
assert resp.status_code == 405
assert resp.json() == {"detail": "Method Not Allowed"}
# ---------------------------------------------------------------------------
# 401 routing: browser redirect vs API JSON — real app
# ---------------------------------------------------------------------------
class Test401Contract:
def test_browser_401_redirects_to_login_with_next(self, real_client):
resp = real_client.get(
"/settings/",
headers={"Accept": "text/html"},
follow_redirects=False,
)
assert resp.status_code == 302
assert resp.headers["location"] == "/auth/login?next=/settings/"
def test_json_accept_401_gets_json_not_redirect(self, real_client):
resp = real_client.get(
"/settings/",
headers={"Accept": "application/json"},
follow_redirects=False,
)
assert resp.status_code == 401
assert resp.json() == {"detail": "Authentication required"}
assert "location" not in resp.headers
def test_api_path_401_is_json_even_with_browser_accept(self, real_client):
# The /api/ path prefix alone must force the JSON branch: an API
# client sending Accept: text/html must never get a 302 HTML flow.
resp = real_client.get(
"/api/history",
headers={"Accept": "text/html"},
follow_redirects=False,
)
assert resp.status_code == 401
assert resp.json() == {"detail": "Authentication required"}
assert "location" not in resp.headers
class Test401RedirectShape:
"""next= construction details, driven through the real handler on the
mini app (routes crafted to hit the edge cases)."""
def test_root_path_omits_next_param(self, handler_client):
resp = handler_client.get(
"/", headers={"Accept": "text/html"}, follow_redirects=False
)
assert resp.status_code == 302
assert resp.headers["location"] == "/auth/login"
def test_next_param_percent_encodes_special_chars(self, handler_client):
# Path segment containing '&' (arrives percent-encoded, ASGI
# decodes it). Without quote() the redirect URL would smuggle a
# bare '&' into the query string, truncating next= at 'a'.
resp = handler_client.get(
"/account/a%26b",
headers={"Accept": "text/html"},
follow_redirects=False,
)
assert resp.status_code == 302
assert resp.headers["location"] == "/auth/login?next=/account/a%26b"
def test_api_accept_401_not_redirected(self, handler_client):
resp = handler_client.get(
"/account/x",
headers={"Accept": "application/json"},
follow_redirects=False,
)
assert resp.status_code == 401
assert resp.json() == {"detail": "Authentication required"}
# ---------------------------------------------------------------------------
# 500 — scrubbed fixed-shape body
# ---------------------------------------------------------------------------
class Test500Contract:
def test_unhandled_exception_returns_scrubbed_500(self, handler_client):
resp = handler_client.get(
"/api/boom", headers={"Accept": "application/json"}
)
assert resp.status_code == 500
assert resp.json() == {"error": "Server error"}
_assert_scrubbed(resp)
def test_browser_path_500_same_fixed_body(self, handler_client):
# Flask served plain text "Server error" to browsers; the port
# serves the same JSON everywhere. Pin as implemented.
resp = handler_client.get(
"/browser-boom", headers={"Accept": "text/html"}
)
assert resp.status_code == 500
assert resp.json() == {"error": "Server error"}
_assert_scrubbed(resp)
# ---------------------------------------------------------------------------
# WebAPIException / AuthenticationRequiredError over HTTP
# ---------------------------------------------------------------------------
class TestWebAPIExceptionOverHTTP:
def test_status_code_and_error_code_honored(self, handler_client):
resp = handler_client.get("/api/webapi")
assert resp.status_code == 418
body = resp.json()
assert body["status"] == "error"
assert body["error_code"] == "TEAPOT"
def test_message_is_credential_scrubbed(self, handler_client):
resp = handler_client.get("/api/webapi")
assert BEARER_TOKEN not in resp.text
assert "REDACTED" in resp.json()["message"]
def test_authentication_required_error_maps_to_401(self, handler_client):
resp = handler_client.get("/api/authreq")
assert resp.status_code == 401
body = resp.json()
assert body["error_code"] == "AUTHENTICATION_REQUIRED"
assert body["details"]["username"] == "alice"
# ---------------------------------------------------------------------------
# PolicyDeniedError over HTTP
# ---------------------------------------------------------------------------
class TestPolicyDeniedOverHTTP:
def test_maps_to_400_with_reason(self, handler_client):
resp = handler_client.get("/api/policy")
assert resp.status_code == 400
body = resp.json()
assert body["status"] == "error"
assert "scope_mismatch" in body["message"]
def test_denied_target_not_echoed(self, handler_client):
# The target URL may embed user/query content — reason only.
resp = handler_client.get("/api/policy")
assert SECRET_MARKER not in resp.text
assert "internal.example" not in resp.text
# ---------------------------------------------------------------------------
# Malformed JSON body → 400 (Flask request.get_json() parity)
# ---------------------------------------------------------------------------
class TestMalformedJSONBody:
"""Regression for the FastAPI-migration divergence: a bare
``await request.json()`` on a malformed body raised JSONDecodeError
into the catch-all and returned 500 where Flask returned 400. Fixed
by the ``json.JSONDecodeError`` handler in
``_register_exception_handlers``, which the ``handler_client`` tests
drive. The real-endpoint test uses a route that parses its own body,
so it pins that route's 400 envelope rather than the registered
handler."""
def test_malformed_json_returns_400_via_registered_handler(
self, handler_client
):
resp = handler_client.post(
"/api/echo",
content=b"{not valid json",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400
assert resp.json() == {"error": "Invalid JSON body"}
def test_empty_body_returns_400_not_500(self, handler_client):
resp = handler_client.post(
"/api/echo",
content=b"",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400
assert resp.json() == {"error": "Invalid JSON body"}
def test_valid_json_still_reaches_endpoint(self, handler_client):
# Guard against the handler over-matching: well-formed bodies
# must be untouched.
resp = handler_client.post("/api/echo", json={"a": 1})
assert resp.status_code == 200
assert resp.json() == {"ok": {"a": 1}}
def test_real_endpoint_malformed_json_returns_400(
self, authenticated_client
):
# End-to-end on the real app: an authenticated endpoint that
# uses the route's status-envelope JSON parser (api.py
# api_add_resource). CSRF token header is attached by the
# fixture; the parse failure happens before any DB work.
resp = authenticated_client.post(
"/research/api/resources/some-research-id",
content=b"{definitely not json",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400
assert resp.json() == {
"status": "error",
"message": "Request body must be valid JSON",
}
# ---------------------------------------------------------------------------
# _is_api_request branch behavior
# ---------------------------------------------------------------------------
def _request(path: str, accept: str = None) -> StarletteRequest:
headers = []
if accept is not None:
headers.append((b"accept", accept.encode()))
return StarletteRequest(
{
"type": "http",
"method": "GET",
"path": path,
"raw_path": path.encode(),
"query_string": b"",
"headers": headers,
"server": ("testserver", 80),
"scheme": "http",
}
)
class TestIsApiRequest:
def test_api_segment_in_path_wins_regardless_of_accept(self):
assert _is_api_request(_request("/api/v1/foo", accept="text/html"))
assert _is_api_request(_request("/settings/api/bar"))
def test_path_ending_in_api_counts(self):
assert _is_api_request(_request("/settings/api"))
def test_json_only_accept_is_api(self):
assert _is_api_request(_request("/foo", accept="application/json"))
def test_mixed_accept_with_html_is_browser(self):
# A browser sends "application/json, text/html, ..." style values
# from fetch(); presence of text/html keeps it on the HTML branch.
assert not _is_api_request(
_request("/foo", accept="application/json, text/html")
)
def test_plain_browser_request_is_not_api(self):
assert not _is_api_request(_request("/foo", accept="text/html"))
assert not _is_api_request(_request("/foo"))
class TestApiV1ErrorEnvelope:
"""/api/v1 is the documented programmatic API for external clients.
main built its auth failures inline as ``jsonify({"error": ...})``
(web/api.py). Routing them through HTTPException here would silently
change the envelope to ``{"detail": ...}``, breaking every existing
script that reads ``error`` -- a contract break invisible to the UI,
because the frontend's api.js reads ``detail`` too.
Both keys are emitted rather than swapped, so main's contract is restored
without disturbing the ``{"detail": ...}`` shape the rest of this file
deliberately pins.
"""
def test_api_v1_401_carries_the_error_key_main_clients_expect(
self, real_client
):
resp = real_client.get(
"/api/v1/", headers={"Accept": "application/json"}
)
assert resp.status_code == 401
assert resp.json()["error"] == "Authentication required"
def test_api_v1_401_still_carries_detail_for_the_frontend(
self, real_client
):
resp = real_client.get(
"/api/v1/", headers={"Accept": "application/json"}
)
assert resp.json()["detail"] == "Authentication required"
def test_non_api_v1_paths_keep_the_detail_only_shape(self, real_client):
"""The scoping is the point: widening this to every path would break
the exact-dict assertions elsewhere in this file."""
resp = real_client.get("/auth/logout", headers={"Accept": "text/html"})
assert resp.status_code == 405
assert resp.json() == {"detail": "Method Not Allowed"}
# ---------------------------------------------------------------------------
# A rekey operational fault left unhandled -> retryable 503
# ---------------------------------------------------------------------------
def _session_unavailable():
# Imported when the route runs, so this module still collects against
# a tree that predates the subclass (the fail-on-old run).
from local_deep_research.database.session_context import (
DatabaseSessionUnavailableError,
)
return DatabaseSessionUnavailableError("RekeySidecarIOError")
def _raw_sidecar_fault():
import errno
from pathlib import Path
from local_deep_research.database.rekey_lock import (
RekeySidecarIOError,
RekeySidecarOperation,
)
return RekeySidecarIOError(
Path(f"{SECRET_MARKER}.db"), RekeySidecarOperation.OPEN, errno.EMFILE
)
@pytest.fixture(scope="module")
def database_fault_client():
"""Routes that leave a rekey operational fault unhandled.
``get_user_db_session`` raises ``DatabaseSessionUnavailableError`` when
the database cannot be opened or claimed because of one (an
fd-exhaustion spike on the rekey sidecar, say), and a direct
``db_manager`` call raises the ``RekeyOperationalError`` itself.
"""
mini = FastAPI()
_register_exception_handlers(mini)
faults = {"session": _session_unavailable, "raw": _raw_sidecar_fault}
@mini.get("/page/{kind}")
def page(kind: str):
raise faults[kind]()
@mini.get("/api/v1/data/{kind}")
def api_v1_data(kind: str):
raise faults[kind]()
return TestClient(mini, raise_server_exceptions=False)
class TestDatabaseUnavailableOverHTTP:
"""Not a verdict on the session, so not the catch-all's 500 either.
Same retryable 503 and ``Retry-After`` that ``require_auth`` answers
when its own probe meets the fault, through the HTTPException handler
(so ``/api/v1`` keeps its ``error`` key). The fault's own text (it names
the database file and the errno) never reaches the body.
"""
DETAIL = "Your database is temporarily unavailable. Please try again in a moment."
@pytest.mark.parametrize("kind", ["session", "raw"])
def test_page_answers_retryable_503(self, database_fault_client, kind):
resp = database_fault_client.get(
f"/page/{kind}", headers={"Accept": "text/html"}
)
assert resp.status_code == 503, resp.text[:300]
assert resp.headers["retry-after"] == "5"
assert resp.json() == {"detail": self.DETAIL}
_assert_scrubbed(resp)
assert "errno" not in resp.text
@pytest.mark.parametrize("kind", ["session", "raw"])
def test_api_v1_keeps_its_error_envelope(self, database_fault_client, kind):
resp = database_fault_client.get(
f"/api/v1/data/{kind}", headers={"Accept": "application/json"}
)
assert resp.status_code == 503, resp.text[:300]
assert resp.headers["retry-after"] == "5"
assert resp.json() == {"error": self.DETAIL, "detail": self.DETAIL}