~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
"""The wire contract of ``/api/v1`` — the surface external scripts see.
``web/routers/api_v1.py`` is the FastAPI port of ``web/api.py`` on main.
Unlike the rest of the app, this router is a *published* programmatic
interface: scripts outside this repository post JSON to it and parse the
body by key. So the thing that has to survive the migration is not "a 200
came back" but the exact bytes-level shape — which keys exist, what they
nest inside, what the failure envelope is called, and which status code
carries it.
What this file pins, and why each piece was not already pinned:
1. **The ``{"error": ...}`` envelope.** Every hand-built failure response
in this module uses ``error``. The rest of the app uses ``detail``
(``fastapi_app._register_exception_handlers``' final branch), and the
``/api/v1`` special case in that same handler emits ``error`` *and*
``detail`` together for ``HTTPException``-derived failures so both
audiences keep working. ``tests/web/test_exception_handler_contract.py``
::TestApiV1ErrorEnvelope pins the 401 half of that. Nothing pinned the
other half: the responses the *handlers themselves* return (400 / 500 /
504) carry ``error`` and deliberately NO ``detail``. A future "let's
unify the error envelope" refactor that rewrote those to ``detail``
would pass every existing test and break every external caller, so the
absence of ``detail`` is asserted explicitly here, not just the
presence of ``error``.
2. **Response body shape.** ``findings[].documents[]`` are ``Document``
objects that both main (``_serialize_results``) and the port flatten to
``{"metadata": ..., "content": ...}`` — note ``page_content`` is
RENAMED to ``content``. ``generate_report`` truncates a >10 000-char
``content`` to the first 2 000 chars plus a literal marker and adds
``content_truncated: True``. Neither was covered anywhere in the suite
(``grep -r page_content tests/web tests/security`` and
``grep -r content_truncated tests/`` both come back empty of api_v1).
3. **The request contract.** The server-side default
(``searches_per_section``) and the deliberate ABSENCE of
``search_tool`` / ``iterations`` defaults are part of what a caller
gets when they omit a key. ``tests/security/test_api_v1_boundary_fastapi.py`` pins the
identity params (``username`` / ``settings_snapshot``); the defaults
were unpinned. ``temperature`` is NOT defaulted, and never reaches the
research function, on ``quick_summary``/``generate_report`` — it is a
documented no-op on the REST path (see
``_ACCEPTED_BUT_INEFFECTIVE_PARAMS`` in ``api_v1.py``) — but IS
accepted with a 200 and a ``warnings`` entry, not a 400, because it was
a publicly documented parameter (``GET /api/v1``, release notes 1.8.1);
``tests/security/test_api_v1_boundary_fastapi.py`` pins that
accept-but-strip behavior.
4. **``require_api_access`` and the API kill-switch over HTTP.**
``tests/web/test_rate_limit_coverage.py``::TestRequireApiAccess calls the
dependency directly with a ``Mock`` request and asserts the raised
``HTTPException``. That proves the raise, not the response an external
client actually receives — which is produced two layers later by the
``/api/v1`` branch of the global handler.
5. **The rate limit, end to end.** ``_api_exempt`` /
``_api_user_key`` are unit-tested in
``tests/web/dependencies/test_rate_limit_keys.py``. What was untested is
the wiring between them: that ``require_api_access`` really does reach
``set_request_api_rate_limit`` -> ContextVar -> ``exempt_when`` on a real
request (it crosses an async dependency, a threadpool hop for sync
handlers, and slowapi's decorator), and that all four routes share ONE
bucket via ``scope="api_v1"``.
Test design
-----------
* No LLM and no search engine ever runs: the three research functions are
the stub boundary, patched at the exact import site each handler uses.
* Authentication, the encrypted per-user database, sessions and CSRF all
run for real via the shared ``authenticated_client`` fixture.
* Where a *setting* has to take a particular value, only
``get_settings_manager``'s ``get_setting`` is wrapped — the DB read is
redirected, the code under test (``require_api_access``) is untouched,
and ``get_settings_snapshot`` stays real so
``_load_user_context_into_params`` still succeeds.
* The rate-limit tests shrink the live limiter's *configured value* for
the four api_v1 routes and restore it; ``key_func`` and ``exempt_when``
stay the real ones, so what is measured is the real limiter.
* Every "must not happen" assertion is paired with a positive control in
the same test or an adjacent one, so it cannot pass because the route
was unreachable.
"""
from __future__ import annotations
import uuid
from contextlib import contextmanager
from unittest.mock import patch
import pytest
from fastapi.testclient import TestClient
from limits import parse as parse_rate_limit
from local_deep_research.web.dependencies.rate_limit import (
API_RATE_LIMIT_DEFAULT,
_api_default_exempt,
limiter,
)
from local_deep_research.web.routers import api_v1
DOCS = "/api/v1/"
HEALTH = "/api/v1/health"
QUICK = "/api/v1/quick_summary"
REPORT = "/api/v1/generate_report"
ANALYZE = "/api/v1/analyze_documents"
# Patch targets differ per endpoint because the handlers import
# differently: quick_summary / generate_report are imported inside the
# handler body (circular-import avoidance), analyze_documents at module
# import time (its signature seeds _ANALYZE_DOCUMENTS_PARAMS).
QS_TARGET = "local_deep_research.api.research_functions.quick_summary"
GR_TARGET = "local_deep_research.api.research_functions.generate_report"
AD_TARGET = "local_deep_research.web.routers.api_v1.analyze_documents"
GENERIC_500 = "An internal error has occurred. Please try again later."
class _Doc:
"""Stand-in for a langchain ``Document``.
The serialization step reads exactly two attributes and nothing else,
so a real Document would add an import without adding coverage.
"""
def __init__(self, metadata, page_content):
self.metadata = metadata
self.page_content = page_content
def _unique_ip() -> str:
"""A private (therefore proxy-trusted) IP no other bucket uses."""
parts = [uuid.uuid4().int % 254 + 1 for _ in range(3)]
return f"10.{parts[0]}.{parts[1]}.{parts[2]}"
def _anon_client(app) -> TestClient:
"""An UNauthenticated client that still passes CSRF.
CSRFMiddleware runs outside the router, so without a session-bound
token a POST is rejected with 403 before ``require_api_access`` is
ever consulted — and a test meaning to assert "401 for anonymous"
would silently be asserting "403 for tokenless".
"""
client = TestClient(app, raise_server_exceptions=False)
client.headers.update({"X-Forwarded-For": _unique_ip()})
client.get("/auth/login")
token = client.get("/auth/csrf-token").json()["csrf_token"]
client.headers.update({"X-CSRFToken": token})
return client
@contextmanager
def _api_settings(*, enable_api=None, api_rate_limit=None):
"""Force the two settings ``require_api_access`` reads.
Wraps the real ``SettingsManager`` instance rather than replacing it:
``get_settings_snapshot`` stays live, so the request still gets past
``_load_user_context_into_params`` and reaches the endpoint under
test. Only the specific keys named by the caller are redirected;
everything else falls through to the real database read.
"""
real_factory = api_v1.get_settings_manager
def _factory(db_session=None, username=None):
manager = real_factory(db_session, username)
real_get = manager.get_setting
def _get(key, *args, **kwargs):
if key == "app.enable_api" and enable_api is not None:
return enable_api
if key == "app.api_rate_limit" and api_rate_limit is not None:
return api_rate_limit
return real_get(key, *args, **kwargs)
manager.get_setting = _get
return manager
with patch.object(api_v1, "get_settings_manager", _factory):
yield
# ---------------------------------------------------------------------------
# 1. The failure envelope
# ---------------------------------------------------------------------------
class TestTheErrorEnvelopeIsNotTheDetailEnvelope:
"""``/api/v1`` answers with ``error``; the rest of the app uses
``detail``. Both halves of that split are asserted, in both
directions, so "unify the envelope" cannot land silently."""
@pytest.mark.parametrize(
"path,body,expected",
[
(QUICK, {}, "Query parameter is required"),
(REPORT, {}, "Query parameter is required"),
(
ANALYZE,
{"query": "q"},
"Both query and collection_name parameters are required",
),
],
ids=["quick_summary", "generate_report", "analyze_documents"],
)
def test_handler_built_400s_carry_error_and_no_detail(
self, authenticated_client, path, body, expected
):
resp = authenticated_client.post(path, json=body)
assert resp.status_code == 400, resp.text[:300]
# Exact body: an extra key is as much a contract change as a
# renamed one, and `detail` in particular would mean the envelope
# was quietly unified with the rest of the app.
assert resp.json() == {"error": expected}
def test_handler_built_500s_carry_error_and_no_detail(
self, authenticated_client
):
with patch(QS_TARGET, side_effect=RuntimeError("boom")):
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 500, resp.text[:300]
assert resp.json() == {"error": GENERIC_500}
def test_dependency_raised_403_carries_both_error_and_detail(
self, authenticated_client
):
"""The kill-switch path goes through ``HTTPException``, so it is
the global handler that builds the body — and for ``/api/v1`` that
handler emits BOTH keys (``error`` for main-era scripts, ``detail``
for the in-app frontend). Only the 401 half of this was pinned."""
with _api_settings(enable_api=False):
resp = authenticated_client.get(DOCS)
assert resp.status_code == 403, resp.text[:300]
assert resp.json() == {
"error": "API access is disabled",
"detail": "API access is disabled",
}
def test_the_kill_switch_is_what_produced_that_403(
self, authenticated_client
):
"""Positive control for the test above: with the same client and
the setting left alone, the same GET succeeds."""
with _api_settings(enable_api=True):
resp = authenticated_client.get(DOCS)
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["api_version"] == "v1"
@pytest.mark.parametrize(
"path", [QUICK, REPORT, ANALYZE], ids=["quick", "report", "analyze"]
)
def test_anonymous_post_is_a_json_401_in_the_api_v1_envelope(
self, app, path
):
client = _anon_client(app)
resp = client.post(path, json={"query": "q"}, follow_redirects=False)
assert resp.status_code == 401, resp.text[:300]
assert resp.json() == {
"error": "Authentication required",
"detail": "Authentication required",
}
def test_a_sibling_non_api_v1_route_keeps_the_detail_only_shape(self, app):
"""The contrast that gives the assertions above their meaning: the
SAME 401, raised by the SAME dependency, on a path outside
``/api/v1`` must NOT grow an ``error`` key."""
client = _anon_client(app)
resp = client.get(
"/settings/api",
headers={"Accept": "application/json"},
follow_redirects=False,
)
assert resp.status_code == 401, resp.text[:300]
body = resp.json()
assert "detail" in body
assert "error" not in body, (
"a non-/api/v1 route must keep the detail-only envelope; "
f"got {body}"
)
@pytest.mark.parametrize(
"path", [DOCS, HEALTH, QUICK], ids=["docs", "health", "quick"]
)
def test_every_response_is_application_json(
self, authenticated_client, path
):
if path == QUICK:
with patch(QS_TARGET, return_value={"summary": "s"}):
resp = authenticated_client.post(path, json={"query": "q"})
else:
resp = authenticated_client.get(path)
assert resp.status_code == 200, resp.text[:300]
assert resp.headers["content-type"].startswith("application/json")
# ---------------------------------------------------------------------------
# 2. Malformed bodies
# ---------------------------------------------------------------------------
class TestMalformedBodies:
"""Both branches return 400 with an ``error`` key, as main did — but
with different message text than main's ``@require_json_body``
produced. A non-JSON Content-Type gets main's message again; that
half of the contract is pinned in
``tests/web/routers/test_json_body_contract_port_fidelity.py``. The
status and envelope are what external callers branch on, so those are
pinned exactly; the strings are pinned so a further drift is visible."""
@pytest.mark.parametrize(
"path", [QUICK, REPORT, ANALYZE], ids=["quick", "report", "analyze"]
)
def test_unparseable_body_is_400_invalid_json_body(
self, authenticated_client, path
):
resp = authenticated_client.post(
path,
content=b"{not json at all",
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:300]
assert resp.json() == {"error": "Invalid JSON body"}
@pytest.mark.parametrize("body", [b"[1, 2]", b'"a string"', b"12", b"null"])
@pytest.mark.parametrize(
"path", [QUICK, REPORT, ANALYZE], ids=["quick", "report", "analyze"]
)
def test_json_that_is_not_an_object_is_400_not_500(
self, authenticated_client, path, body
):
"""A JSON array/scalar parses fine but has no ``.get()``. Before
the explicit guard it reached ``data.get()`` and 500'd."""
resp = authenticated_client.post(
path,
content=body,
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 400, resp.text[:300]
assert resp.json() == {"error": "Request body must be a JSON object"}
# Every JSON value type other than string, including null. Keep this as data
# rather than parametrizing the tests: each test reuses one authenticated
# client, avoiding eighteen expensive encrypted-account bootstrap cycles.
_NON_STRING_JSON_VALUES = (
("integer", 7),
("number", 2.5),
("boolean", True),
("array", ["not", "a", "query"]),
("object", {"not": "a string"}),
("null", None),
)
class TestResearchFieldTypes:
"""Wrong-typed fields are rejected at the HTTP boundary.
A JSON object can satisfy the required-key checks while carrying a value
that is unusable by the research pipeline. ``quick_summary`` already
rejected that type confusion; these tests pin the same contract on its two
sibling endpoints and prove rejection happens before downstream dispatch.
"""
def test_generate_report_requires_a_string_query(
self, authenticated_client
):
with patch(GR_TARGET, return_value={"content": "unused"}) as fn:
for label, value in _NON_STRING_JSON_VALUES:
resp = authenticated_client.post(REPORT, json={"query": value})
assert resp.status_code == 400, (
f"{label} query returned {resp.status_code}: "
f"{resp.text[:300]}"
)
assert resp.json() == {"error": "Query must be a string"}
fn.assert_not_called()
def test_analyze_documents_requires_a_string_query(
self, authenticated_client
):
with patch(AD_TARGET, return_value={"summary": "unused"}) as fn:
for label, value in _NON_STRING_JSON_VALUES:
resp = authenticated_client.post(
ANALYZE,
json={"query": value, "collection_name": "collection"},
)
assert resp.status_code == 400, (
f"{label} query returned {resp.status_code}: "
f"{resp.text[:300]}"
)
assert resp.json() == {"error": "Query must be a string"}
fn.assert_not_called()
def test_analyze_documents_requires_a_string_collection_name(
self, authenticated_client
):
with patch(AD_TARGET, return_value={"summary": "unused"}) as fn:
for label, value in _NON_STRING_JSON_VALUES:
resp = authenticated_client.post(
ANALYZE,
json={"query": "query", "collection_name": value},
)
assert resp.status_code == 400, (
f"{label} collection_name returned {resp.status_code}: "
f"{resp.text[:300]}"
)
assert resp.json() == {
"error": "Collection name must be a string"
}
fn.assert_not_called()
# ---------------------------------------------------------------------------
# 3. quick_summary response shape
# ---------------------------------------------------------------------------
def _quick_summary_payload():
"""A fresh payload per call — the handler shallow-copies the result
and then mutates ``findings`` IN PLACE, so a shared module-level dict
would be corrupted by the first test that used it."""
return {
"summary": "A short synthesis.",
"findings": [
{
"phase": "Follow-up 1",
"content": "some finding text",
"documents": [
_Doc({"source": "a.pdf", "page": 3}, "page one text"),
_Doc({"source": "b.pdf"}, "page two text"),
],
}
],
"iterations": 2,
"questions": {"1": ["what?", "why?"]},
"formatted_findings": "## Findings\n\nbody",
"sources": [{"title": "T", "link": "https://example.invalid/x"}],
"all_links_of_system": [],
"research_id": 17,
}
class TestQuickSummaryResponseShape:
def test_documents_are_flattened_to_metadata_and_content(
self, authenticated_client
):
"""``page_content`` is RENAMED to ``content`` and every other
Document attribute is dropped. This is the single most
wire-visible transformation the endpoint performs and it had no
test on either side of the migration."""
with patch(QS_TARGET, return_value=_quick_summary_payload()):
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
documents = resp.json()["findings"][0]["documents"]
assert documents == [
{
"metadata": {"source": "a.pdf", "page": 3},
"content": "page one text",
},
{"metadata": {"source": "b.pdf"}, "content": "page two text"},
]
def test_the_rest_of_the_payload_is_returned_verbatim_and_unwrapped(
self, authenticated_client
):
"""No envelope, no renaming, no added keys: the research
function's dict IS the response body (documents aside)."""
payload = _quick_summary_payload()
with patch(QS_TARGET, return_value=_quick_summary_payload()):
resp = authenticated_client.post(QUICK, json={"query": "q"})
body = resp.json()
assert set(body) == set(payload), (
"the response key set must equal the research function's; "
f"extra={set(body) - set(payload)} "
f"missing={set(payload) - set(body)}"
)
assert body["summary"] == payload["summary"]
assert body["iterations"] == 2 and isinstance(body["iterations"], int)
assert body["research_id"] == 17
assert body["questions"] == {"1": ["what?", "why?"]}
assert body["sources"] == payload["sources"]
assert body["findings"][0]["phase"] == "Follow-up 1"
assert body["findings"][0]["content"] == "some finding text"
def test_a_payload_without_findings_still_serializes(
self, authenticated_client
):
"""``.get("findings", [])`` — a research function that omits the
key entirely must not 500 the endpoint."""
with patch(QS_TARGET, return_value={"summary": "s", "research_id": 1}):
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
assert resp.json() == {"summary": "s", "research_id": 1}
# ---------------------------------------------------------------------------
# 4. The request contract: what the server fills in for you
# ---------------------------------------------------------------------------
class TestServerSideRequestDefaults:
def test_quick_summary_does_not_default_iterations(
self, authenticated_client
):
"""Omitted ``iterations`` must not be filled with 1: that would
clobber the caller's stored ``search.iterations``."""
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
args, kwargs = fn.call_args
assert args == ("q",), "query is passed positionally"
assert "iterations" not in kwargs
def test_quick_summary_does_not_default_search_tool(
self, authenticated_client
):
"""Deliberate omission: with no ``search_tool`` key,
``quick_summary`` falls back to the caller's stored
``search.tool``. Defaulting it here would silently override every
user's configured engine."""
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
authenticated_client.post(QUICK, json={"query": "q"})
assert "search_tool" not in fn.call_args.kwargs
def test_quick_summary_accepts_but_strips_temperature(
self, authenticated_client
):
"""``temperature`` is a documented no-op on the REST path (see
``_ACCEPTED_BUT_INEFFECTIVE_PARAMS`` in ``api_v1.py``), but unlike
the hard-400ed no-ops it was a PUBLICLY DOCUMENTED REST parameter
(``GET /api/v1``, release notes 1.8.1), so hard-rejecting it would
break existing callers. It is accepted (200), stripped before the
research call, and surfaced as a ``warnings`` entry instead.
``tests/security/test_api_v1_boundary_fastapi.py`` covers this in
depth; this just pins that the request-defaults contract genuinely
never forwards ``temperature`` to quick_summary."""
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(
QUICK, json={"query": "q", "temperature": 0.1}
)
assert resp.status_code == 200, resp.text[:300]
assert "temperature" not in fn.call_args.kwargs
assert any("temperature" in w for w in resp.json().get("warnings", []))
def test_body_values_win_over_the_defaults(self, authenticated_client):
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
authenticated_client.post(
QUICK,
json={"query": "q", "iterations": 5},
)
kwargs = fn.call_args.kwargs
assert kwargs["iterations"] == 5
def test_generate_report_defaults_searches_per_section(
self, authenticated_client
):
with patch(GR_TARGET, return_value={"content": "c"}) as fn:
resp = authenticated_client.post(REPORT, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
args, kwargs = fn.call_args
assert args == ("q",)
assert kwargs["searches_per_section"] == 1
assert "temperature" not in kwargs
def test_analyze_documents_passes_both_positionals_and_no_defaults(
self, authenticated_client
):
"""``analyze_documents`` has no ``**kwargs``; the handler adds no
defaults of its own, so the function's own signature defaults
apply."""
with patch(AD_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(
ANALYZE, json={"query": "q", "collection_name": "c"}
)
assert resp.status_code == 200, resp.text[:300]
args, kwargs = fn.call_args
assert args == ("q", "c")
assert "temperature" not in kwargs
assert "max_results" not in kwargs
@pytest.mark.parametrize(
"path,target,body",
[
(QUICK, QS_TARGET, {"query": "q"}),
(REPORT, GR_TARGET, {"query": "q"}),
(ANALYZE, AD_TARGET, {"query": "q", "collection_name": "c"}),
],
ids=["quick", "report", "analyze"],
)
def test_allow_default_settings_is_never_forwarded_downstream(
self, authenticated_client, path, target, body
):
"""It is a transport-level flag for this router only. Forwarding
it would be invisible on quick_summary/generate_report (they take
``**kwargs``) and a hard TypeError on analyze_documents."""
with patch(target, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(
path, json={**body, "allow_default_settings": True}
)
assert resp.status_code == 200, resp.text[:300]
assert "allow_default_settings" not in fn.call_args.kwargs
# ---------------------------------------------------------------------------
# 5. generate_report truncation
# ---------------------------------------------------------------------------
class TestGenerateReportContentTruncation:
""">10 000 chars of ``content`` is replaced by its first 2 000 plus a
literal marker, and ``content_truncated`` appears. Untested until now,
yet it is the difference between a caller receiving their report and
receiving 2 KB of it."""
_MARKER = "... [Content truncated]"
def test_content_at_the_threshold_is_untouched(self, authenticated_client):
content = "x" * 10000
with patch(
GR_TARGET, return_value={"content": content, "metadata": {"a": 1}}
):
resp = authenticated_client.post(REPORT, json={"query": "q"})
body = resp.json()
assert body["content"] == content
assert "content_truncated" not in body, (
"main omitted the key entirely rather than setting it False; "
"a caller doing `if 'content_truncated' in r` must keep working"
)
def test_content_one_char_over_the_threshold_is_truncated(
self, authenticated_client
):
content = "y" * 10001
with patch(
GR_TARGET,
return_value={
"content": content,
"metadata": {"a": 1},
"file_path": "/tmp/r.md",
},
):
resp = authenticated_client.post(REPORT, json={"query": "q"})
body = resp.json()
assert body["content"] == "y" * 2000 + self._MARKER
assert body["content_truncated"] is True
# The truncation must not disturb the rest of the payload.
assert body["metadata"] == {"a": 1}
assert body["file_path"] == "/tmp/r.md"
def test_non_string_content_is_left_alone(self, authenticated_client):
"""The guard is ``isinstance(result["content"], str)``; a dict
payload has no ``len`` semantics to truncate."""
with patch(
GR_TARGET, return_value={"content": {"sections": ["a", "b"]}}
):
resp = authenticated_client.post(REPORT, json={"query": "q"})
assert resp.json() == {"content": {"sections": ["a", "b"]}}
def test_a_payload_with_no_content_key_passes_through(
self, authenticated_client
):
with patch(GR_TARGET, return_value={"file_path": "/tmp/r.md"}):
resp = authenticated_client.post(REPORT, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
assert resp.json() == {"file_path": "/tmp/r.md"}
# ---------------------------------------------------------------------------
# 6. analyze_documents parameter allowlist — the exact advertised body
# ---------------------------------------------------------------------------
class TestAnalyzeDocumentsUnknownParameterBody:
# The wire-visible allowlist. Derived in src from the real signature
# so the two cannot drift; hard-coded here because THIS list is what
# a client reads out of the 400 body, so any change to it is an API
# change that should have to be made deliberately in two places.
# ``programmatic_mode`` IS a declared parameter of analyze_documents but
# is deliberately excluded from the wire allowlist: it is
# identity/audit plumbing (see ``_IDENTITY_PLUMBING_PARAMS`` /
# ``_ANALYZE_DOCUMENTS_PARAMS`` in api_v1.py) that
# ``_load_user_context_into_params`` manages itself via
# ``setdefault``, so a caller-supplied value would otherwise let a
# request opt itself out of DB-backed metrics/rate-limit accounting.
# ``output_file`` is ALSO deliberately excluded, for the same reason it
# is rejected on quick_summary/generate_report (see
# ``_SERVER_PATH_PARAMS`` in api_v1.py): analyze_documents reaches the
# identical bare-``open()`` ``write_file_verified`` sink, so a
# server-side filesystem path is not a REST-shaped parameter here
# either. Deliberate contract change from post-merge review of this
# follow-up — do not add output_file back to make this pass.
ALLOWED = [
"force_reindex",
"max_results",
"temperature",
]
def test_the_400_body_has_exactly_two_keys_with_the_advertised_list(
self, authenticated_client
):
with patch(AD_TARGET) as fn:
resp = authenticated_client.post(
ANALYZE,
json={"query": "q", "collection_name": "c", "bogus": 1},
)
assert resp.status_code == 400, resp.text[:300]
assert fn.call_count == 0
assert resp.json() == {
"error": "Unknown parameter(s) for analyze_documents: bogus",
"allowed_parameters": self.ALLOWED,
}
def test_multiple_unknown_keys_are_sorted_and_comma_joined(
self, authenticated_client
):
with patch(AD_TARGET):
resp = authenticated_client.post(
ANALYZE,
json={
"query": "q",
"collection_name": "c",
"zebra": 1,
"alpha": 2,
},
)
assert resp.json()["error"] == (
"Unknown parameter(s) for analyze_documents: alpha, zebra"
)
@pytest.mark.parametrize("name", ALLOWED)
def test_every_advertised_parameter_is_actually_accepted(
self, authenticated_client, name
):
"""Positive control for the allowlist: the 400 above must be
caused by the key being unknown, not by the route rejecting
extra keys wholesale."""
with patch(AD_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(
ANALYZE,
json={"query": "q", "collection_name": "c", name: 1},
)
assert resp.status_code == 200, resp.text[:300]
assert fn.call_args.kwargs[name] == 1
def test_programmatic_mode_is_rejected_with_400(self, authenticated_client):
"""``programmatic_mode`` is a genuine declared parameter of
``analyze_documents`` (unlike ``bogus`` above), so it would
otherwise survive the signature-derived allowlist untouched.
It must be explicitly subtracted (see ``_ANALYZE_DOCUMENTS_PARAMS``
in api_v1.py) so a caller cannot opt their own analyze_documents
calls out of DB-backed metrics/rate-limit accounting the same way
already closed for quick_summary/generate_report.
"""
with patch(AD_TARGET) as fn:
resp = authenticated_client.post(
ANALYZE,
json={
"query": "q",
"collection_name": "c",
"programmatic_mode": True,
},
)
assert resp.status_code == 400, resp.text[:300]
assert fn.call_count == 0
assert "programmatic_mode" in resp.json()["error"]
assert "programmatic_mode" not in resp.json()["allowed_parameters"]
# ---------------------------------------------------------------------------
# 7. Timeout and failure status codes
# ---------------------------------------------------------------------------
class TestTimeoutAndFailurePaths:
def test_quick_summary_timeout_is_504_with_its_own_message(
self, authenticated_client
):
with patch(QS_TARGET, side_effect=TimeoutError):
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 504, resp.text[:300]
assert resp.json() == {
"error": (
"Request timed out. Please try with a simpler query or "
"fewer iterations."
)
}
def test_generate_report_timeout_is_504_with_a_different_message(
self, authenticated_client
):
"""The two messages differ on main (only quick_summary mentions
iterations) and the port preserves that. Asserted separately so a
well-meaning de-duplication is caught."""
with patch(GR_TARGET, side_effect=TimeoutError):
resp = authenticated_client.post(REPORT, json={"query": "q"})
assert resp.status_code == 504, resp.text[:300]
assert resp.json() == {
"error": "Request timed out. Please try with a simpler query."
}
def test_analyze_documents_timeout_is_500_not_504(
self, authenticated_client
):
"""Asymmetry inherited from main: ``api_analyze_documents`` has no
``except TimeoutError`` branch, so a timeout there is indistinguishable
from any other failure. Pinned as-is — a client that retries on 504
will not retry this one, and that behaviour must not change
accidentally in either direction."""
with patch(AD_TARGET, side_effect=TimeoutError):
resp = authenticated_client.post(
ANALYZE, json={"query": "q", "collection_name": "c"}
)
assert resp.status_code == 500, resp.text[:300]
assert resp.json() == {"error": GENERIC_500}
@pytest.mark.parametrize(
"path,target,body",
[
(QUICK, QS_TARGET, {"query": "q"}),
(REPORT, GR_TARGET, {"query": "q"}),
(ANALYZE, AD_TARGET, {"query": "q", "collection_name": "c"}),
],
ids=["quick", "report", "analyze"],
)
def test_an_exception_below_the_endpoint_is_a_fixed_opaque_500(
self, authenticated_client, path, target, body
):
secret = "sk-EXTERNALCONTRACT99887766"
with patch(target, side_effect=RuntimeError(f"blew up: {secret}")):
resp = authenticated_client.post(path, json=body)
assert resp.status_code == 500, resp.text[:300]
assert resp.json() == {"error": GENERIC_500}
assert secret not in resp.text
# ---------------------------------------------------------------------------
# 8. The hand-written documentation payload
# ---------------------------------------------------------------------------
class TestApiDocumentationPayload:
"""``tests/web/routers/test_api_v1_documentation_is_current.py`` checks
that the advertised paths are served and that no POST route is missing
from the list. It does not pin the payload's SHAPE — which is what a
client parsing this endpoint actually consumes."""
@pytest.fixture
def docs(self, authenticated_client):
resp = authenticated_client.get(DOCS)
assert resp.status_code == 200, resp.text[:300]
return resp.json()
def test_top_level_shape(self, docs):
assert set(docs) == {"api_version", "description", "endpoints"}
assert docs["api_version"] == "v1"
assert docs["description"] == "REST API for Local Deep Research"
assert isinstance(docs["endpoints"], list)
def test_each_endpoint_entry_shape(self, docs):
for entry in docs["endpoints"]:
assert set(entry) == {
"path",
"method",
"description",
"parameters",
}, entry
assert isinstance(entry["parameters"], dict)
assert all(
isinstance(v, str) for v in entry["parameters"].values()
), entry
def test_the_three_advertised_endpoints_and_their_parameter_keys(
self, docs
):
by_path = {entry["path"]: entry for entry in docs["endpoints"]}
assert set(by_path) == {
"/api/v1/quick_summary",
"/api/v1/generate_report",
"/api/v1/analyze_documents",
}
assert all(e["method"] == "POST" for e in by_path.values())
# ``temperature`` IS advertised for all three endpoints, but its
# quick_summary/generate_report entries carry a "no effect on this
# endpoint" annotation (see api_documentation in api_v1.py): it is a
# dead no-op there (accepted with a 200 + ``warnings`` entry, not
# forwarded to the research function — see
# _ACCEPTED_BUT_INEFFECTIVE_PARAMS), but omitting it entirely would
# misrepresent the wire contract for callers following release
# notes 1.8.1, which documents it as a valid /quick_summary
# parameter. It stays a real, forwarded parameter for
# analyze_documents below.
assert set(by_path["/api/v1/quick_summary"]["parameters"]) == {
"query",
"search_tool",
"iterations",
"allow_default_settings",
"temperature",
}
# ``output_file`` is deliberately NOT advertised here: this
# follow-up rejects it with a 400 on generate_report (see
# _SERVER_PATH_PARAMS in api_v1.py) rather than merely
# documenting the risk, so it must not appear as an accepted
# parameter any more. This is a deliberate contract change, not
# an oversight — do not add output_file back to make this pass.
assert set(by_path["/api/v1/generate_report"]["parameters"]) == {
"query",
"searches_per_section",
"model_name",
"allow_default_settings",
"temperature",
}
assert set(by_path["/api/v1/analyze_documents"]["parameters"]) == {
"query",
"collection_name",
"max_results",
"temperature",
"force_reindex",
"allow_default_settings",
}
def test_health_and_the_index_are_deliberately_not_advertised(self, docs):
paths = {entry["path"] for entry in docs["endpoints"]}
assert HEALTH not in paths
assert DOCS not in paths
# ---------------------------------------------------------------------------
# 9. /health — the only unauthenticated endpoint
# ---------------------------------------------------------------------------
class TestHealthWireShape:
"""``tests/web/routers/test_health_diagnostics.py`` covers the
``resources`` block. The ``subsystems`` block is an addition over main
with the same authenticated-only gating and had no test at all."""
def test_anonymous_gets_exactly_mains_three_keys(self, app):
client = _anon_client(app)
body = client.get(HEALTH).json()
assert set(body) == {"status", "message", "timestamp"}, (
"an anonymous prober must learn nothing beyond main's triple; "
f"got {sorted(body)}"
)
assert body["status"] == "ok"
assert body["message"] == "API is running"
assert isinstance(body["timestamp"], float)
def test_authenticated_gets_the_subsystems_block(
self, authenticated_client
):
body = authenticated_client.get(HEALTH).json()
assert set(body["subsystems"]) == {"queue_processor", "db_manager"}
assert body["subsystems"]["queue_processor"] in {
"ok",
"not_started",
"error",
}
assert body["subsystems"]["db_manager"] in {"ok", "error"}
def test_a_degraded_subsystem_does_not_change_the_top_level_status(
self, authenticated_client
):
"""Documented contract: ``status`` stays ``ok`` so existing
liveness probes keep passing; only ``subsystems`` reports the
degradation."""
from local_deep_research.database import encrypted_db
class _Broken:
@property
def has_encryption(self):
raise RuntimeError("db manager is down")
with patch.object(encrypted_db, "db_manager", _Broken()):
body = authenticated_client.get(HEALTH).json()
assert body["subsystems"]["db_manager"] == "error"
assert body["status"] == "ok"
assert body["message"] == "API is running"
def test_health_needs_no_authentication_at_all(self, app):
"""Unlike every other route in the module it has no
``require_api_access`` dependency — the Docker healthcheck depends
on that."""
client = _anon_client(app)
assert client.get(HEALTH).status_code == 200
# ---------------------------------------------------------------------------
# 10. The per-user rate limit, end to end
# ---------------------------------------------------------------------------
_API_V1_LIMIT_KEYS = [
f"local_deep_research.web.routers.api_v1.{name}"
for name in (
"api_documentation",
"api_quick_summary",
"api_generate_report",
"api_analyze_documents",
)
]
@pytest.fixture
def api_limit_of_two():
"""Shrink the api_v1 shared limit to 2/minute for one test.
Only the configured VALUE is swapped on the live ``Limit`` objects —
``key_func`` (per-user bucket) and ``exempt_when``
(``_api_default_exempt``) stay the real ones, so what the test measures
is the production limiter, not a stand-in. Also forces
``limiter.enabled`` on, because ``_RATE_LIMITING_ENABLED`` is
resolved at import time and CI may have disabled it.
"""
saved: dict[str, list] = {}
original_enabled = limiter.enabled
for key in _API_V1_LIMIT_KEYS:
registered = limiter._route_limits.get(key)
assert registered, (
f"{key} carries no static slowapi limit — the @api_rate_limit "
"decorator is missing or slowapi's registry moved"
)
for lim in registered:
assert lim.scope == "api_v1", (
f"{key} must share the 'api_v1' bucket, got {lim.scope!r}"
)
assert lim.exempt_when is _api_default_exempt, (
f"{key} lost the 0-disables-it / custom-value-handoff "
"exemption hook"
)
saved[key] = [lim.limit for lim in registered]
for lim in registered:
lim.limit = parse_rate_limit("2 per minute")
limiter.enabled = True
limiter.reset()
try:
yield
finally:
for key, items in saved.items():
for lim, item in zip(limiter._route_limits[key], items):
lim.limit = item
limiter.enabled = original_enabled
# Best-effort: a storage backend that refuses reset must not turn
# teardown into an error that masks the test's own result. The
# autouse reset_all_singletons fixture resets it again anyway.
try:
limiter.reset()
except Exception: # allow: silent-exception
pass
class TestApiRateLimitOverHttp:
def test_the_limit_is_enforced_and_answers_in_mains_429_body(
self, authenticated_client, api_limit_of_two
):
statuses = [
authenticated_client.get(DOCS).status_code for _ in range(3)
]
assert statuses[:2] == [200, 200], statuses
assert statuses[2] == 429, statuses
resp = authenticated_client.get(DOCS)
assert resp.status_code == 429
assert resp.json() == {
"error": "Too many requests",
"message": "Too many attempts. Please try again later.",
}
def test_all_four_endpoints_draw_on_one_shared_bucket(
self, authenticated_client, api_limit_of_two
):
"""``scope="api_v1"`` means the quota is per USER, not per route:
two GETs on the index must exhaust the budget for a POST to
quick_summary. Without the shared scope each route would get its
own 2/minute and the POST below would be a 200."""
assert authenticated_client.get(DOCS).status_code == 200
assert authenticated_client.get(DOCS).status_code == 200
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 429, resp.text[:300]
assert fn.call_count == 0, (
"the limiter must reject before the research function runs"
)
def test_the_shared_bucket_claim_is_not_vacuous(
self, authenticated_client, api_limit_of_two
):
"""Control for the test above: with the bucket untouched, the very
same POST succeeds — so the 429 there came from the two prior GETs
and not from anything intrinsic to the POST."""
with patch(QS_TARGET, return_value={"summary": "s"}) as fn:
resp = authenticated_client.post(QUICK, json={"query": "q"})
assert resp.status_code == 200, resp.text[:300]
assert fn.call_count == 1
def test_zero_disables_the_limit_end_to_end(
self, authenticated_client, api_limit_of_two
):
"""``app.api_rate_limit = 0`` is main's kill-switch for the API
rate limit. Proving it works needs the whole chain: the setting is
read by ``require_api_access``, cached in a ContextVar by
``set_request_api_rate_limit``, and read back by ``_api_exempt``
from inside slowapi's decorator — across an async dependency and
(for this sync handler) a threadpool hop. Each piece is unit
tested; the chain was not."""
with _api_settings(api_rate_limit=0):
statuses = [
authenticated_client.get(DOCS).status_code for _ in range(6)
]
assert statuses == [200] * 6, (
"app.api_rate_limit=0 must exempt the route entirely; "
f"statuses={statuses}"
)
def test_a_nonzero_setting_leaves_the_limit_enforced(
self, authenticated_client, api_limit_of_two
):
"""Control for the exemption above: the same six requests with a
non-zero setting DO get cut off, so the all-200s result there is
attributable to the zero and not to a dead fixture."""
with _api_settings(api_rate_limit=API_RATE_LIMIT_DEFAULT):
statuses = [
authenticated_client.get(DOCS).status_code for _ in range(6)
]
assert 429 in statuses, statuses
@pytest.mark.parametrize("value", [2, "2"], ids=["int", "numeric-string"])
def test_a_custom_per_user_rate_limit_value_is_honoured(
self, authenticated_client, value
):
"""A custom nonzero ``app.api_rate_limit`` caps the user at THAT
value (#5988). Runs against the real registered limits - no
``api_limit_of_two`` - so what is measured is the dynamic custom
limit ``rate_limit.py`` registers alongside the static default,
not a swapped-in stand-in. The string form is what an env override
or a text-typed settings row reads back as (the key has no
defaults entry, so nothing converts it); main honoured it too."""
original_enabled = limiter.enabled
limiter.enabled = True
limiter.reset()
try:
with _api_settings(api_rate_limit=value):
statuses = [
authenticated_client.get(DOCS).status_code for _ in range(4)
]
finally:
limiter.enabled = original_enabled
limiter.reset()
assert 429 in statuses, (
f"app.api_rate_limit={value!r} should cap this user at 2/min; "
f"{statuses}"
)
@pytest.mark.parametrize(
"bad_value",
[-5, "abc", "12a", "9" * 5000],
ids=["negative", "non-numeric", "mixed-string", "over-int-digit-limit"],
)
def test_an_invalid_setting_falls_back_to_the_default_limit(
self, authenticated_client, api_limit_of_two, bad_value
):
"""``app.api_rate_limit`` has no settings-schema entry, so a
negative or non-numeric value can be stored and read back. It must
NOT count as a custom value: that would exempt the static default
and hand the dynamic limit a string slowapi cannot parse, which it
logs and skips - no limit at all. (``"12a"`` is the near miss for
the digit-string coercion above; the 5000-digit string is past
``int()``'s conversion limit and must not 500 the request.)
``api_limit_of_two`` pins the static default at 2/min, so the 429
proves the user stayed on it."""
with _api_settings(api_rate_limit=bad_value):
statuses = [
authenticated_client.get(DOCS).status_code for _ in range(6)
]
assert 429 in statuses, statuses