~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
"""Request/response semantics at the Flask -> Starlette boundary.
Werkzeug and Starlette answer the same questions differently, and a
mechanical port keeps compiling while quietly changing the answer. Every
test here pins one of those answers on a route this app actually serves.
The five differences that drive this file:
1. ``request.args`` (Werkzeug ``MultiDict``) became
``request.query_params`` (Starlette ``QueryParams``). ``.args`` does not
exist on a Starlette request, so a missed rename is an
``AttributeError`` -> 500 rather than a name error at import time.
2. **Repeated keys resolve the other way round.** Werkzeug's
``MultiDict.get`` returns the FIRST value for ``?a=1&a=2``; Starlette's
``QueryParams.get`` returns the LAST. Both are silent. A route that
validates ``?period=`` against a whitelist now sees a different value
than it did on main for the same URL.
3. **Absent is not empty.** ``request.args.get(k, default)`` returned
*default* only when the key was ABSENT — ``?x=`` yielded ``""``.
``request.query_params.get(k, default)`` agrees, but the common port
``request.query_params.get(k) or default`` does not: it also swallows
``""``, ``"0"`` and ``"false"``. One instance of exactly this shipped on
this branch (``pdf_storage=`` in ``routers/rag.py``, since fixed with an
``is None`` check and a comment explaining why). These tests pin the
distinction on routes where the app genuinely makes it, so a future
``or``-shaped simplification fails instead of silently overriding what
the caller sent.
4. **``Request.json()`` never looks at Content-Type.** It is literally
``json.loads(await self.body())``. Flask's ``request.get_json()``
required ``application/json`` unless ``force=True``. So a body labelled
``text/plain`` or ``multipart/form-data`` still parses here, which makes
any size/routing decision derived from the *declared* Content-Type
unsound — the real reason ``BodySizeLimitMiddleware``'s large cap is
gated on PATH rather than on the content type.
5. **Invalid UTF-8 raises ``UnicodeDecodeError``, not
``json.JSONDecodeError``.** ``json.loads`` decodes the bytes before it
parses them, so the app registers both exception types with the same 400
handler. Every bare ``await request.json()`` call therefore retains
Flask's client-error contract for malformed bytes as well as bad syntax.
A sixth, found while writing this file: FastAPI's ``APIRoute`` does not
grant HEAD to GET routes the way ``starlette.routing.Route`` (and Werkzeug
before it) does, so ``HEAD`` is 405 everywhere, including on ``/`` and on
static assets. Also pinned as a defect. See the METHODS section.
Verification note: the expected values in this file were measured against
the running app before the local test-run freeze; the AST/exec tests are
self-verifying and carry their own negative control.
"""
import ast
import json
from pathlib import Path
import pytest
from local_deep_research import web
from local_deep_research.web.dependencies import json_body
# Locate the shipped source through the packages themselves, so these
# tests can never end up reading a stale checkout. Only the two lightweight
# modules are imported: pulling in ``web.fastapi_app`` here would build the
# whole application at collection time, so its source is reached via the
# package directory instead.
JSON_BODY_SRC = Path(json_body.__file__).resolve()
FASTAPI_APP_SRC = Path(web.__file__).resolve().parent / "fastapi_app.py"
#: A JSON document that is well-formed *as text* but is not valid UTF-8.
#: json.loads() dies in the decode step, before the parser ever runs.
INVALID_UTF8_JSON = b'{"name": "\xff\xfe"}'
RATE_LIMIT_URL = "/metrics/api/rate-limiting"
BULK_URL = "/settings/api/bulk"
COST_URL = "/metrics/api/cost-calculation"
FOLDERS_URL = "/news/api/subscription/folders"
def _period(client, url):
"""The `period` value a real route echoed back from query_params.get."""
resp = client.get(url)
assert resp.status_code == 200, (
f"{url} -> {resp.status_code} {resp.text[:300]}"
)
return resp.json()["period"]
def _bulk_settings(client, url, params=None):
"""The `settings` mapping /settings/api/bulk built from getlist()."""
resp = client.get(url, params=params)
assert resp.status_code == 200, (
f"{url} -> {resp.status_code} {resp.text[:300]}"
)
payload = resp.json()
assert payload["success"] is True, payload
return payload["settings"]
def _setting_value(client, key):
settings = _bulk_settings(client, BULK_URL + "?keys[]=" + key)
return settings[key]["value"]
# ---------------------------------------------------------------------------
# QUERY PARAMETERS — repeated keys
# ---------------------------------------------------------------------------
def test_repeated_query_param_is_last_wins_on_a_real_route(
authenticated_client,
):
"""``?period=7d&period=1y`` must resolve to ``1y``.
``/metrics/api/rate-limiting`` echoes the raw
``request.query_params.get("period", "30d")`` straight back, so it is a
direct read-out of the resolution rule. On main (Werkzeug) the same URL
resolved to ``7d``. Nothing in the app depends on duplicates being sent
deliberately — the point is that the answer is now the opposite one, so
a framework change back (or a helper that switches to ``getlist()[0]``)
surfaces here rather than in whichever dashboard silently re-scopes its
time window.
"""
# Positive controls: each value on its own really does reach the route.
assert _period(authenticated_client, RATE_LIMIT_URL + "?period=7d") == "7d"
assert _period(authenticated_client, RATE_LIMIT_URL + "?period=1y") == "1y"
both = _period(
authenticated_client, RATE_LIMIT_URL + "?period=7d&period=1y"
)
assert both == "1y", (
"Starlette's QueryParams.get is last-wins; got "
f"{both!r}. {both!r} == '7d' means first-wins (Werkzeug) semantics "
"are back and every duplicate-parameter URL now resolves the way "
"main did, silently."
)
def test_starlette_queryparams_get_and_getlist_disagree_by_design():
"""The mechanism behind the route test above, on the real class.
``request.query_params`` IS a ``starlette.datastructures.QueryParams``,
so this is the shipped implementation, not a model of it. Kept separate
so a Starlette upgrade that changed the rule is diagnosable without an
app fixture.
"""
from starlette.datastructures import QueryParams
params = QueryParams("period=7d&period=1y")
assert params.get("period") == "1y", "QueryParams.get must be last-wins"
assert params.getlist("period") == ["7d", "1y"], (
"getlist must preserve every value in send order — it is the only "
"way a route can see a duplicate at all"
)
assert params["period"] == "1y", "__getitem__ must agree with .get()"
def test_repeated_keys_are_all_preserved_where_the_route_uses_getlist(
authenticated_client,
):
"""``/settings/api/bulk`` reads ``keys[]`` with ``getlist``, so unlike
``.get()`` it must see BOTH values, in order. This is the other half of
the contract: a well-meaning port of ``getlist`` to ``.get()`` would
keep returning 200 while silently dropping every key but the last.
"""
settings = _bulk_settings(
authenticated_client,
BULK_URL + "?keys[]=llm.provider&keys[]=search.tool",
)
assert set(settings) == {"llm.provider", "search.tool"}, (
"both repeated keys[] values must reach the route; a single key "
"here means getlist() was replaced by a last-wins .get()"
)
assert list(settings) == ["llm.provider", "search.tool"], (
f"getlist must preserve send order, got {list(settings)}"
)
# ---------------------------------------------------------------------------
# QUERY PARAMETERS — absent vs. present-but-empty
# ---------------------------------------------------------------------------
def test_absent_query_param_defaults_but_an_empty_one_does_not(
authenticated_client,
):
"""``?period=`` must NOT be treated as "no period given".
This is the ``or``-default bug class on a route that shows its work.
``request.query_params.get("period", "30d")`` returns ``"30d"`` only
when the key is absent and ``""`` when it is present-but-empty — the
Flask contract. Rewriting it as ``... .get("period") or "30d"`` passes
every other test in the suite and fails this one.
"""
# Positive control: a real value is honoured, so the assertions below
# are reading a live parameter and not a constant.
assert _period(authenticated_client, RATE_LIMIT_URL + "?period=7d") == "7d"
assert _period(authenticated_client, RATE_LIMIT_URL) == "30d", (
"an ABSENT period must fall back to the default"
)
assert _period(authenticated_client, RATE_LIMIT_URL + "?period=") == "", (
"a PRESENT-but-empty period must stay empty. '30d' here means the "
"default is being applied to an explicitly-empty value — the "
"`x or default` port that already shipped once as pdf_storage="
)
def test_absent_keys_list_defaults_but_an_empty_one_does_not(
authenticated_client,
):
"""Same distinction, list-shaped, on ``/settings/api/bulk``.
``getlist`` returns ``[]`` for an absent key and ``[""]`` for
``?keys[]=``, and the route branches on ``if not requested``. The two
inputs therefore produce visibly different responses: a ten-key default
bundle, versus a lookup of the empty-string key. A port that reached
for ``.get()`` — or that stripped falsy entries out of the list before
the check — would collapse them into one.
"""
# Positive control: an explicit key is honoured and nothing else leaks in.
explicit = _bulk_settings(
authenticated_client, BULK_URL + "?keys[]=llm.provider"
)
assert set(explicit) == {"llm.provider"}, explicit
absent = _bulk_settings(authenticated_client, BULK_URL)
assert len(absent) > 1, (
f"an ABSENT keys[] must fall back to the default bundle, got {absent}"
)
assert {"llm.provider", "search.tool"} <= set(absent), sorted(absent)
empty = _bulk_settings(authenticated_client, BULK_URL + "?keys[]=")
assert set(empty) == {""}, (
"a PRESENT-but-empty keys[] must be looked up as the empty-string "
f"key, not replaced by the default bundle; got {sorted(empty)}"
)
assert empty[""]["exists"] is False, empty
# ---------------------------------------------------------------------------
# REQUEST BODIES — Content-Type independence
# ---------------------------------------------------------------------------
#
# Oracle for "did request.json() parse this body?". The cost route cannot
# answer it alone any more: it reads the body through ``read_json_dict``,
# which gives an unparseable body and a parsed non-object the SAME 400, so
# only "parsed to a dict" stands apart:
#
# body did not parse, or was not a dict -> 400 {"error": "No data provided"}
# parsed to a dict -> 400 {"error": "model_name is required"}
#
# POST /benchmark/api/validate-config still reads its body with a bare
# ``await request.json()`` (one of the four sites test_encoding_and_non_ascii
# pins in UNGUARDED_JSON_BODY_SITES), so it keeps all three outcomes apart:
#
# body did not parse -> 400 {"error": "Invalid JSON body"} (app handler)
# parsed, but not a dict -> 200 {"valid": false, "errors": ["No data provided"]}
# parsed to a dict -> 200 {"valid": true, "errors": [], ...}
#
# Neither route touches the pricing calculator, the network or a model
# lookup, so these tests do none. If validate-config moves to
# ``read_json_dict``, point the bare-route tests at another site that is
# still in that inventory.
VALIDATE_CONFIG_URL = "/benchmark/api/validate-config"
#: A benchmark configuration validate-config reports as valid.
VALID_BENCHMARK_CONFIG = json.dumps(
{
"search_config": {
"search_tool": "searxng",
"search_strategy": "focused_iteration",
},
"datasets_config": {"simpleqa": {"count": 5}},
}
).encode()
#: What the app-level handler answers for a body ``request.json()`` could not
#: parse or decode.
APP_HANDLER_ENVELOPE = {"error": "Invalid JSON body"}
#: Every Content-Type label a client can put on a JSON body.
DECLARED_CONTENT_TYPES = (
"application/json",
"text/plain",
"multipart/form-data; boundary=----WebKitFormBoundaryXYZ",
"application/x-www-form-urlencoded",
None, # no Content-Type header at all
)
def _cost_error(client, body, content_type=None):
headers = {"Content-Type": content_type} if content_type else {}
resp = client.post(COST_URL, content=body, headers=headers)
return resp.status_code, resp.json().get("error")
def _bare_route_outcome(client, body, content_type=None):
"""What ``request.json()`` made of ``body``, read off validate-config.
``"unparsed"``, ``"not-an-object"`` or ``"parsed"``. Anything else comes
back as a description of the surprise, so a failing assertion shows it.
"""
headers = {"Content-Type": content_type} if content_type else {}
resp = client.post(VALIDATE_CONFIG_URL, content=body, headers=headers)
payload = resp.json()
if (resp.status_code, payload) == (400, APP_HANDLER_ENVELOPE):
return "unparsed"
if resp.status_code == 200 and payload.get("errors") == [
"No data provided"
]:
return "not-an-object"
if resp.status_code == 200 and payload.get("valid") is True:
return "parsed"
return f"unexpected: {resp.status_code} {resp.text[:200]}"
def test_json_body_parses_regardless_of_the_declared_content_type(
authenticated_client,
):
"""``Request.json()`` is ``json.loads(await self.body())`` — it never
inspects Content-Type, so a JSON body wearing any label still parses.
Pinned because it is load-bearing: it is why a body-size or routing
decision made from the *declared* Content-Type is unsound (a client can
label a 100 MB JSON body ``multipart/form-data`` and still have it
parsed on the event loop), and why the large-body cap is gated on PATH.
Flask's ``get_json()`` refused a non-``application/json`` body outright,
so this is a genuine widening, not a detail.
"""
parsed_dict = b'{"model_name": ""}'
for content_type in DECLARED_CONTENT_TYPES:
status, error = _cost_error(
authenticated_client, parsed_dict, content_type
)
assert (status, error) == (400, "model_name is required"), (
f"a JSON body labelled {content_type!r} must still be parsed as "
f"JSON; got {status} {error!r}"
)
def test_a_bare_request_json_route_parses_whatever_the_declared_content_type(
authenticated_client,
):
"""The same property, asked of ``request.json()`` itself rather than of
the helper wrapped around it."""
for content_type in DECLARED_CONTENT_TYPES:
outcome = _bare_route_outcome(
authenticated_client, VALID_BENCHMARK_CONFIG, content_type
)
assert outcome == "parsed", (
f"a JSON body labelled {content_type!r} must still be parsed as "
f"JSON; the oracle says {outcome}"
)
def test_the_content_type_oracle_can_actually_say_no(authenticated_client):
"""Discrimination control for the two tests above.
"It parsed" is only meaningful if a body that genuinely cannot parse
produces a different answer through the same code path — otherwise the
loops above would pass against a route that answered "parsed"
unconditionally.
"""
# Cost route: only "parsed to a dict" stands apart. An unparseable body
# and a parsed non-object share the route's one envelope by design.
for body, content_type in (
(b"model_name=", "application/x-www-form-urlencoded"),
(b"123", "application/json"),
):
status, error = _cost_error(authenticated_client, body, content_type)
assert (status, error) == (400, "No data provided"), (
f"{body!r} is not a JSON object and must not reach the "
f"route's own validation; got {status} {error!r}"
)
# Bare route: all three outcomes apart, through one route and one code
# path. A form-encoded body must NOT parse as JSON, and valid JSON that
# is not an object is rejected on shape, not on parsing.
outcomes = {
"form-encoded": _bare_route_outcome(
authenticated_client,
b"model_name=",
"application/x-www-form-urlencoded",
),
"malformed": _bare_route_outcome(
authenticated_client, b"{nope", "application/json"
),
"non-object": _bare_route_outcome(
authenticated_client, b"123", "application/json"
),
"object": _bare_route_outcome(
authenticated_client, VALID_BENCHMARK_CONFIG, "application/json"
),
}
assert outcomes == {
"form-encoded": "unparsed",
"malformed": "unparsed",
"non-object": "not-an-object",
"object": "parsed",
}
def test_malformed_json_is_a_400_not_a_500(authenticated_client):
"""Flask parity: malformed JSON uses the route's validation response."""
status, error = _cost_error(
authenticated_client, b"{nope", "application/json"
)
assert (status, error) == (400, "No data provided"), (
f"malformed JSON must be a 400, got {status} {error!r}"
)
# ---------------------------------------------------------------------------
# REQUEST BODIES — invalid UTF-8
# ---------------------------------------------------------------------------
def test_invalid_utf8_body_is_a_400_on_the_cost_route(
authenticated_client,
):
"""An undecodable request body is a client error, matching Flask.
``json.loads`` decodes before it parses, so invalid UTF-8 raises
``UnicodeDecodeError``. The shared object parser turns it into the
route's own validation response, so this route never reaches the
application-level handler; that is pinned on a bare ``request.json()``
route by the test below.
"""
# Positive control: the same route, same headers, valid UTF-8 -> 400.
# Without it a 500 here could just mean the route is broken outright.
assert _cost_error(
authenticated_client, b'{"model_name": ""}', "application/json"
) == (
400,
"model_name is required",
)
status, error = _cost_error(
authenticated_client, INVALID_UTF8_JSON, "application/json"
)
assert (status, error) == (400, "No data provided"), (
"an undecodable request body must use the route's client-error "
f"contract; got {status} {error!r}"
)
def test_invalid_utf8_body_is_a_400_on_a_bare_request_json_route(
authenticated_client,
):
"""An undecodable request body is a client error, matching Flask.
It is not a ``json.JSONDecodeError``, so both types must be registered
explicitly with the shared application-level handler. validate-config
reads its body with a bare ``await request.json()``, so no route-local
guard stands between the exception and that handler: this is the HTTP
half of ``test_unicode_decode_error_handler_is_registered``.
"""
# Positive control: the same route and headers, valid UTF-8 -> parsed.
# Without it a 500 here could just mean the route is broken outright.
assert (
_bare_route_outcome(
authenticated_client, VALID_BENCHMARK_CONFIG, "application/json"
)
== "parsed"
)
resp = authenticated_client.post(
VALIDATE_CONFIG_URL,
content=INVALID_UTF8_JSON,
headers={"Content-Type": "application/json"},
)
assert (resp.status_code, resp.json()) == (400, APP_HANDLER_ENVELOPE), (
"an undecodable request body must use the shared client-error "
f"contract; got {resp.status_code} {resp.text[:300]}"
)
def test_invalid_utf8_is_already_a_400_where_read_json_dict_guards_the_body(
authenticated_client,
):
"""The shared helper retains its route-specific error envelope.
``dependencies/json_body.read_json_dict`` catches ``ValueError`` around
the parse, and ``UnicodeDecodeError`` is one, so it answers before the
global handler does and returns the route's configured message. This pins
the intentional envelope difference while both parsing idioms return 400.
"""
client = authenticated_client
# Positive control 1: a well-formed body really is accepted here.
ok = client.post(FOLDERS_URL, json={"name": "boundary-контроль"})
assert ok.status_code == 201, f"{ok.status_code} {ok.text[:300]}"
# Positive control 2: a parsed-but-invalid body reaches the handler's
# own validation, so a 400 below is not just "everything is 400".
empty = client.post(FOLDERS_URL, json={})
assert (empty.status_code, empty.json().get("error")) == (
400,
"Folder name is required",
), empty.text[:300]
bad = client.post(
FOLDERS_URL,
content=INVALID_UTF8_JSON,
headers={"Content-Type": "application/json"},
)
assert (bad.status_code, bad.json().get("error")) == (
400,
"Request body must be valid JSON",
), (
"read_json_dict must absorb UnicodeDecodeError into the same 400 a "
f"malformed body gets; got {bad.status_code} {bad.text[:300]}"
)
# --- static half: the exception-handler registry, and the real guard code ---
def _registered_exception_types():
"""Every exception type fastapi_app registers a handler for, as source
text (``@app.exception_handler(X)`` and ``app.add_exception_handler(X,
...)``)."""
tree = ast.parse(FASTAPI_APP_SRC.read_text(encoding="utf-8"))
found = []
for node in ast.walk(tree):
if not isinstance(node, ast.Call) or not isinstance(
node.func, ast.Attribute
):
continue
if node.func.attr not in ("exception_handler", "add_exception_handler"):
continue
if node.args:
found.append(ast.unparse(node.args[0]))
return found
def test_unicode_decode_error_handler_is_registered():
"""Static companion to the HTTP contract
(``test_invalid_utf8_body_is_a_400_on_a_bare_request_json_route``): pin
the registration itself.
Reading the registry rather than the response means the fixer gets
pointed at the one line that has to change, and this guard cannot rot
into passing for an unrelated reason.
"""
registered = _registered_exception_types()
# Premise guard: an empty/short scan would make the assertion vacuous.
assert len(registered) >= 5, (
f"the handler scan found only {registered} — it is probably no "
"longer matching how handlers are registered"
)
assert "json.JSONDecodeError" in registered, (
"the malformed-body -> 400 handler must be registered; without it "
"the 400 pinned above comes from somewhere else entirely: "
f"{registered}"
)
assert "UnicodeDecodeError" in registered, (
"undecodable JSON bytes would fall through to the catch-all 500 "
f"without the explicit handler registration: {registered}"
)
def _exec_json_body_source(mutate=None, source_out=None):
"""Compile and run the REAL ``json_body.py`` definitions, verbatim.
Takes the module's imports plus its two function definitions straight
out of the AST — no reimplementation — so what is exercised below is
the shipped code. ``mutate`` may rewrite the tree first; that is how
the negative control produces a counterfactual.
"""
tree = ast.parse(JSON_BODY_SRC.read_text(encoding="utf-8"))
wanted = ("json_body_error", "read_json_dict")
kept = [
node
for node in tree.body
if isinstance(node, (ast.Import, ast.ImportFrom))
or (
isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
and node.name in wanted
)
or isinstance(node, ast.Assign)
]
module = ast.Module(body=kept, type_ignores=[])
if mutate is not None:
module = mutate(module)
ast.fix_missing_locations(module)
if source_out is not None:
source_out.append(ast.unparse(module))
namespace = {}
# S102: the point of this helper is to run the shipped source verbatim
# rather than a paraphrase of it; the input is a repo file, not input.
exec(compile(module, str(JSON_BODY_SRC), "exec"), namespace) # noqa: S102
assert set(wanted) <= set(namespace), (
f"failed to lift the real definitions out of {JSON_BODY_SRC}: "
f"{sorted(namespace)}"
)
return namespace
class _RequestRaising:
"""Minimal stand-in whose ``.json()`` fails the way Starlette's does."""
def __init__(self, exc):
self._exc = exc
async def json(self):
raise self._exc
def _unicode_decode_error():
"""The exact exception ``json.loads`` raises for an undecodable body."""
with pytest.raises(UnicodeDecodeError) as caught:
INVALID_UTF8_JSON.decode("utf-8")
return caught.value
def test_the_shipped_read_json_dict_really_absorbs_unicode_decode_error():
"""Runs the shipped guard against the real exception object.
``UnicodeDecodeError`` is deliberately built by decoding the same bytes
the HTTP test sends, so the input is the genuine article rather than a
hand-rolled instance.
"""
import anyio
namespace = _exec_json_body_source()
read_json_dict = namespace["read_json_dict"]
assert read_json_dict is not json_body.read_json_dict, (
"this must be a freshly exec'd copy of the source, so the mutation "
"in the negative control cannot touch the imported module"
)
assert namespace["DEFAULT_MESSAGE"] == json_body.DEFAULT_MESSAGE, (
"the lifted copy has drifted from the imported module — the AST "
"extraction is no longer picking up the shipped definitions"
)
# Positive control: a body that parses to a dict comes back as data.
class _Ok:
async def json(self):
return {"name": "x"}
data, err = anyio.run(read_json_dict, _Ok())
assert (data, err) == ({"name": "x"}, None)
data, err = anyio.run(
read_json_dict, _RequestRaising(_unicode_decode_error())
)
assert data is None
assert err is not None and err.status_code == 400, err
assert json.loads(bytes(err.body)) == {
"error": "Request body must be valid JSON"
}
class _RetargetTheGuard(ast.NodeTransformer):
"""Swap the shipped ``except (ValueError, RecursionError)`` for another.
The clause is matched by its element names, not by unparsing it, because
``ast.unparse`` may or may not parenthesise a tuple here depending on the
interpreter. ``hits`` counts the handlers swapped, so a control can
insist it changed exactly the one clause it describes.
"""
def __init__(self, replacement):
self.replacement = replacement
self.hits = 0
def visit_ExceptHandler(self, node):
shipped = isinstance(node.type, ast.Tuple) and {
getattr(element, "id", None) for element in node.type.elts
} == {"ValueError", "RecursionError"}
if shipped:
self.hits += 1
node.type = ast.parse(self.replacement, mode="eval").body
return node
def test_negative_control_a_narrowed_except_clause_lets_the_error_escape(
tmp_path,
):
"""NEGATIVE CONTROL for the two tests above.
Mutates a COPY of the shipped source — the guard's
``except (ValueError, RecursionError)`` becomes
``except json.JSONDecodeError``, which is the idiom the unguarded
``await request.json()`` call sites effectively have — and shows that
the same exec then lets ``UnicodeDecodeError`` escape. It follows that
the guard test above is not vacuous: it goes red the moment the clause
stops covering the encoding failure.
"""
import anyio
transformer = _RetargetTheGuard("json.JSONDecodeError")
mutated_source = []
def mutate(module):
module.body.insert(0, ast.parse("import json").body[0])
return transformer.visit(module)
namespace = _exec_json_body_source(mutate=mutate, source_out=mutated_source)
assert transformer.hits == 1, (
f"expected exactly one `except (ValueError, RecursionError)` to "
f"narrow, hit {transformer.hits} — the mutation no longer describes "
"the shipped guard and this control proves nothing"
)
# Keep the mutated counterfactual on disk so a failure here is
# inspectable as a diff against the real json_body.py.
mutant_path = tmp_path / "json_body_narrowed.py"
mutant_path.write_text(
"# MUTANT of "
+ str(JSON_BODY_SRC)
+ ": `except (ValueError, RecursionError)` -> "
+ "`except json.JSONDecodeError`\n"
+ mutated_source[0],
encoding="utf-8",
)
assert "except json.JSONDecodeError" in mutant_path.read_text(
encoding="utf-8"
), "the mutation did not reach the emitted source"
narrowed = namespace["read_json_dict"]
# The mutant still handles the failure the narrowed clause names, so
# the control isolates the decode case rather than breaking everything.
decode_error = json.JSONDecodeError("Expecting value", "{nope", 1)
data, err = anyio.run(narrowed, _RequestRaising(decode_error))
assert data is None and err is not None and err.status_code == 400
with pytest.raises(UnicodeDecodeError):
anyio.run(narrowed, _RequestRaising(_unicode_decode_error()))
def test_negative_control_a_broad_except_clause_swallows_what_must_propagate():
"""NEGATIVE CONTROL for the propagation tests in
``tests/web/dependencies/test_json_body_contract.py`` and for the 413
tests in ``tests/web/routers/test_json_body_error_envelopes.py``.
Mutates a COPY of the shipped source so the guard catches bare
``Exception`` — what it did before an over-cap body streamed without a
Content-Length was found coming back as the route's 400 — and shows the
mutant answers with the 400 envelope for an exception the shipped guard
lets through to ``BodySizeLimitMiddleware``. It follows that those tests
are not vacuous: they go red the moment the clause is widened again.
"""
import anyio
class _OverTheCap(Exception):
"""Stands in for BodySizeLimitMiddleware's over-cap exception."""
transformer = _RetargetTheGuard("Exception")
widened = _exec_json_body_source(mutate=transformer.visit)["read_json_dict"]
assert transformer.hits == 1, (
f"expected exactly one `except (ValueError, RecursionError)` to "
f"widen, hit {transformer.hits} — the mutation no longer describes "
"the shipped guard and this control proves nothing"
)
shipped = _exec_json_body_source()["read_json_dict"]
# The mutant turns the over-cap error into the route's validation 400 ...
data, err = anyio.run(widened, _RequestRaising(_OverTheCap()))
assert data is None and err is not None and err.status_code == 400
# ... where the shipped guard leaves it for the middleware.
with pytest.raises(_OverTheCap):
anyio.run(shipped, _RequestRaising(_OverTheCap()))
# ---------------------------------------------------------------------------
# UNICODE / ENCODING ROUND-TRIPS
# ---------------------------------------------------------------------------
NON_ASCII = "мод-π✓-ünï"
def test_non_ascii_query_param_survives_the_round_trip(authenticated_client):
"""Percent-encoded non-ASCII must reach the route as the original text
and come back out of the JSON response as UTF-8 bytes.
Werkzeug and Starlette both decode the query string as UTF-8, but they
are separate implementations of it, and the response half differs too:
Flask's ``jsonify`` escaped non-ASCII to ``\\uXXXX`` by default, while
FastAPI's JSONResponse emits raw UTF-8. Anything reading the body as
bytes (a proxy, a test, a non-browser client) sees the difference.
"""
echoed = _period(authenticated_client, RATE_LIMIT_URL)
assert echoed == "30d" # positive control: the echo works at all
resp = authenticated_client.get(
RATE_LIMIT_URL, params={"period": NON_ASCII}
)
assert resp.status_code == 200, resp.text[:300]
assert resp.json()["period"] == NON_ASCII, (
"the query parameter must decode back to the exact original text"
)
assert NON_ASCII.encode("utf-8") in resp.content, (
"the response body must carry raw UTF-8, not \\uXXXX escapes — "
f"got {resp.content[:200]!r}"
)
def test_non_ascii_json_request_body_survives_the_round_trip(
authenticated_client,
):
"""Non-ASCII in a JSON request body must come back byte-identical."""
payload = {"model_name": NON_ASCII, "provider": "prøvider"}
resp = authenticated_client.post(
COST_URL,
content=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json"},
)
assert resp.status_code == 200, f"{resp.status_code} {resp.text[:300]}"
body = resp.json()
assert body["model_name"] == NON_ASCII, body
assert body["provider"] == "prøvider", body
assert NON_ASCII.encode("utf-8") in resp.content, resp.content[:200]
def test_non_ascii_key_and_form_value_survive_a_real_write_and_read_back(
authenticated_client,
):
"""A form POST is the third encoding path (urlencoded body), and it is
the one Flask used ``request.form`` for. Writes a non-ASCII value
through ``POST /settings/save_settings`` and reads it back through the
JSON API, so the value crosses form-decode, the database and
JSON-encode without changing.
The non-ASCII *key* half rides on the same request: ``keys[]`` with
non-ASCII must be looked up verbatim, not mangled into a lookup that
happens to miss.
"""
client = authenticated_client
resp = client.post(
"/settings/save_settings",
data={"llm.model": NON_ASCII},
follow_redirects=False,
)
assert resp.status_code == 302, f"{resp.status_code} {resp.text[:300]}"
assert _setting_value(client, "llm.model") == NON_ASCII, (
"a non-ASCII form value must survive form-decode -> DB -> JSON"
)
unicode_key = "ünï✓.κλειδί"
settings = _bulk_settings(client, BULK_URL) # positive control: works bare
assert unicode_key not in settings
settings = _bulk_settings(client, BULK_URL, params={"keys[]": unicode_key})
assert set(settings) == {unicode_key}, (
f"a non-ASCII keys[] must be echoed verbatim, got {sorted(settings)}"
)
# ---------------------------------------------------------------------------
# FORM FIELDS — repeated, absent, empty
# ---------------------------------------------------------------------------
def test_form_field_semantics_absent_empty_and_repeated(authenticated_client):
"""The form half of differences 2 and 3, end to end on a real write.
``POST /settings/save_settings`` does ``dict(await request.form())`` and
then iterates ``form_data.items()``, so:
* a repeated field collapses last-wins (``dict()`` over a Starlette
``FormData`` keeps the last value) — Werkzeug's ``request.form.get``
would have taken the first;
* an ABSENT field is never iterated, so the stored value is untouched;
* a PRESENT-but-empty field IS iterated and clears the value.
The last two are the pair that an ``or``-shaped default destroys, and
unlike a query parameter the damage here is persistent: the wrong
branch writes to the database.
"""
client = authenticated_client
# Positive control + setup: a plain single-valued write lands.
sentinel = "sentinel-model"
resp = client.post(
"/settings/save_settings",
data={"llm.model": sentinel},
follow_redirects=False,
)
assert resp.status_code == 302, f"{resp.status_code} {resp.text[:300]}"
assert _setting_value(client, "llm.model") == sentinel
# ABSENT: the field is not submitted at all, so it must be left alone.
resp = client.post(
"/settings/save_settings",
data={"search.tool": "searxng"},
follow_redirects=False,
)
assert resp.status_code == 302, f"{resp.status_code} {resp.text[:300]}"
assert _setting_value(client, "llm.model") == sentinel, (
"a field the form did not submit must not be rewritten"
)
# REPEATED: last-wins, not first-wins.
resp = client.post(
"/settings/save_settings",
content=b"llm.model=first-value&llm.model=second-value",
headers={"Content-Type": "application/x-www-form-urlencoded"},
follow_redirects=False,
)
assert resp.status_code == 302, f"{resp.status_code} {resp.text[:300]}"
stored = _setting_value(client, "llm.model")
assert stored == "second-value", (
"dict(FormData) keeps the LAST value for a repeated field; "
f"got {stored!r} ('first-value' would mean Werkzeug semantics)"
)
# PRESENT-but-empty: distinct from absent — it clears the value.
resp = client.post(
"/settings/save_settings",
data={"llm.model": ""},
follow_redirects=False,
)
assert resp.status_code == 302, f"{resp.status_code} {resp.text[:300]}"
assert _setting_value(client, "llm.model") == "", (
"an explicitly-empty form field must be applied, not treated as "
"absent — 'second-value' here means the empty string was swallowed "
"by a falsy-check the way pdf_storage= was"
)
# ---------------------------------------------------------------------------
# METHODS — HEAD and OPTIONS
# ---------------------------------------------------------------------------
def test_head_on_a_get_route_is_405(authenticated_client):
"""PINS A KNOWN DEFECT — Flask answered HEAD on every GET route.
Werkzeug's ``Rule`` adds HEAD to any rule that allows GET, and so does
``starlette.routing.Route``. FastAPI's ``APIRoute`` does not: it sets
``self.methods = {m.upper() for m in methods}`` and stops there. Every
route in this app is an ``APIRoute`` (``@router.get`` / ``@app.get``),
including ``/`` and ``/static/{path:path}``, so ``HEAD`` is 405
app-wide — for health checks, ``curl -I``, link checkers and any proxy
that probes with HEAD before fetching.
RFC 9110 requires a server that supports GET to support HEAD on the
same resource, so this is a spec deviation as well as a parity break.
The fix is a router-level ``methods=["GET", "HEAD"]`` (or re-adding the
Starlette augmentation); when it lands these expectations flip to 200.
"""
client = authenticated_client
# Positive control: the same URL is a perfectly good GET.
assert client.get(RATE_LIMIT_URL).status_code == 200
head = client.head(RATE_LIMIT_URL)
assert head.status_code == 405, (
"current (defective) behaviour: HEAD is rejected on a GET route; "
f"got {head.status_code}. A 200 means HEAD support was added — "
"flip this expectation rather than reverting the fix"
)
assert head.headers.get("allow") == "GET", (
"the 405's Allow header must name the methods the route really "
f"has, got {head.headers.get('allow')!r}"
)
def test_the_head_gap_comes_from_fastapis_apiroute_not_from_starlette():
"""Locates the defect above in one line of framework code.
Constructs both real route classes with the same arguments and compares
``.methods``. ``starlette.routing.Route`` augments GET with HEAD;
``fastapi.routing.APIRoute`` overrides the attribute without doing so.
Cheap, and it keeps the HTTP-level pin diagnosable.
"""
from fastapi.routing import APIRoute
from starlette.routing import Route
async def endpoint():
return {}
starlette_route = Route("/x", endpoint=endpoint, methods=["GET"])
api_route = APIRoute("/x", endpoint=endpoint, methods=["GET"])
assert starlette_route.methods == {"GET", "HEAD"}, (
f"starlette.routing.Route must add HEAD, got {starlette_route.methods}"
)
assert api_route.methods == {"GET"}, (
"fastapi.routing.APIRoute is expected NOT to add HEAD; got "
f"{api_route.methods}. If it now does, FastAPI has changed and the "
"HEAD 405 pin above should be failing too"
)
def test_options_is_not_answered_automatically(authenticated_client):
"""Another Flask parity break, pinned rather than endorsed.
Flask set ``provide_automatic_options`` on every rule, so ``OPTIONS``
returned 200 with an ``Allow`` header. Starlette/FastAPI have no
automatic OPTIONS (CORS middleware only answers *preflight* requests,
which require an ``Origin`` and ``Access-Control-Request-Method``), so a
plain OPTIONS falls through to the 405 branch. It does at least carry
the ``Allow`` header, which is what a client asking OPTIONS wanted.
"""
resp = authenticated_client.options(RATE_LIMIT_URL)
assert resp.status_code == 405, (
"current behaviour: no automatic OPTIONS (Flask returned 200); got "
f"{resp.status_code}"
)
assert resp.headers.get("allow") == "GET", resp.headers.get("allow")
assert resp.json() == {"detail": "Method Not Allowed"}, resp.text[:300]
def test_a_wrong_method_on_a_get_route_is_405_not_404(authenticated_client):
"""Method mismatch must not be reported as a missing route.
Starlette distinguishes "path matched, method did not" (405) from "no
route" (404) — pinned because the two are easy to conflate when routers
are reordered, and because the 404 handler on this app branches on
Accept while the 405 does not.
"""
client = authenticated_client
assert client.get(RATE_LIMIT_URL).status_code == 200 # positive control
wrong_method = client.post(RATE_LIMIT_URL)
assert wrong_method.status_code == 405, wrong_method.text[:300]
missing = client.get("/metrics/api/rate-limiting-does-not-exist")
assert missing.status_code == 404, missing.text[:300]