Skip to content

~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.

30.7 KB
Raw Blame
"""A whole-app census of content negotiation, not a hand-picked sample.

The policy lives in one function -- ``_is_api_request`` in
``web/fastapi_app.py``, successor to main's ``_is_api_path`` in
``web/auth/decorators.py``. It says a request is "API" when its path
contains an ``/api/`` segment (or ends in ``/api``), **or** when it
carries ``Accept: application/json`` without ``text/html``. API requests
get JSON; everything else is a browser and gets HTML or a redirect.

Existing suites test that function and the exception handlers on
throwaway apps (``test_exception_handler_contract.py``,
``test_exception_handler_matrix.py``) or spot-check individual routes
(``test_chat_page_login_redirect.py``, ``test_login_required_
boundaries.py``). None of them asks the question this file asks: *for
every route the assembled app actually serves, does its error path obey
the policy?* A rule with two mechanisms and 300-odd routes cannot be
validated by examples -- the interesting failures are the routes nobody
thought to name.

So this file enumerates. It imports the real, fully-mounted ``app`` and
drives every registered ``GET`` route, plus it AST-sweeps every route's
handler. The census records these negotiation contracts and remaining gaps:

1. **The ``/history/*`` XHR family requires explicit JSON negotiation.**
   Its paths have no ``/api/`` segment. The shared browser API client now
   sends ``Accept: application/json``, so expired sessions return a JSON
   401 that its login handler can recognize. Vitest exercises the actual
   JavaScript wrapper; this census verifies the assembled server's
   response for all six routes. Browser navigations still redirect.

2. **``CSRFMiddleware`` does not negotiate at all.** All three of its
   rejection sites (``web/dependencies/csrf.py``) build a bare
   ``JSONResponse(403)``. It is ASGI middleware, so it short-circuits
   before the exception handlers and ``_is_api_request`` is never
   consulted. The only routes that take real browser form posts --
   ``POST /auth/login``, ``/auth/register``, ``/auth/change-password``,
   ``/settings/save_settings`` -- are exactly the ones a stale token hits,
   so a user whose token expired sees a raw JSON blob where the login page
   should be.

3. **The 429 handler does not negotiate either.** ``_rate_limit_exceeded``
   (``fastapi_app.py``) always returns JSON. Most rate-limited routes are
   ``/api/``-shaped, so that is right for the majority -- but eight are
   not, and they include ``POST /auth/login``, ``/auth/register``,
   ``/auth/change-password`` and ``/settings/save_settings``. Six bad
   password attempts therefore replace the login page with
   ``{"error": "Too many requests"}`` in the address bar.

4. **``_send_413`` re-implements half the policy.**
   ``BodySizeLimitMiddleware._send_413`` inlines ``"/api/" in path or
   path.endswith("/api")`` -- a hand copy of ``_is_api_request``'s first
   mechanism, missing the second. A programmatic client sending
   ``Accept: application/json`` to a non-``/api/`` route gets
   ``text/plain``. Same divergence-by-duplication risk the 404 handler
   already had.

Two census results are *clean*, and are pinned here so they stay clean:
the 401 axis over all 180 GET routes (every ``/api/``-shaped path answers
a browser with JSON, every browser-shaped path answers with a redirect or
HTML, with four reviewed exceptions), and the "``return`` a JSONResponse
error instead of ``raise``" class, which bypasses the handlers entirely
and is now absent from every HTML-rendering route.

Deliberately **not** re-reported here: ``favicon`` and ``serve_static``
answering a browser 404 with JSON. Those are known and reported
elsewhere; they appear below only as reviewed entries in the census
exception table, because a census that quietly dropped them would not be
a census.

Also a census result rather than a defect: the catch-all ``Exception``
handler returns JSON for every 500 regardless of client. That is
deliberate and documented at the handler, and pinned by
``test_exception_handler_contract.py::Test500Contract``; it is noted here
so the enumeration is complete and not silently incomplete.
"""

import ast
import asyncio
import inspect
import re
import textwrap

import pytest
from fastapi.testclient import TestClient

from local_deep_research.web.dependencies.rate_limit import limiter
from local_deep_research.web.fastapi_app import (
    BodySizeLimitMiddleware,
    app,
    _is_api_request,
)

# What a real browser sends on a top-level navigation.
BROWSER_ACCEPT = (
    "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
)
# Native fetch's default. The shared JSON client overrides this explicitly.
FETCH_DEFAULT_ACCEPT = "*/*"
JSON_ACCEPT = "application/json"


def _path_is_api_shaped(path: str) -> bool:
    """The path half of the policy, applied to a route *template*.

    This is not a re-implementation of ``_is_api_request`` standing in for
    the real thing -- the tests below all call the real function or drive
    real requests. It is used only to *partition* the route table into the
    two populations whose behaviour then gets asserted, and
    ``test_partition_helper_agrees_with_the_real_policy`` pins it against
    ``_is_api_request`` so the partition cannot drift.
    """
    return "/api/" in path or path.endswith("/api")


def _fill(path: str) -> str:
    """Turn a route template into a concrete URL."""
    return re.sub(r"\{[^}]+\}", "probe", path)


# Test-only probe routes, registered on the live ``app`` singleton at
# IMPORT time by other test modules -- tests/web/test_security_headers_
# matrix.py (``/__sec_matrix__/*``), test_middleware_order_and_headers.py
# (``/__mw_order_probe__/*``), test_middleware_stack_contracts.py
# (``/__mw_stack__/*``), test_streaming_and_sse_contracts.py and
# tests/security/test_security_headers_fastapi.py. They deliberately raise,
# stream SSE, or emit ndjson, so the census below scores them as violations
# -- for routes no product code serves, and only when one of those modules
# happens to have been imported into the same process first. No product
# route uses this prefix. Same exclusion the sibling sweeps already apply:
# tests/web/routers/test_all_endpoints.py and
# tests/web/routers/test_full_surface_smoke.py (``_PROBE_PREFIX``).
_PROBE_PREFIX = "/__"


def _get_routes():
    """Every GET-serving route on the assembled app, as (path, url)."""
    out = []
    for route in app.routes:
        methods = getattr(route, "methods", None)
        if not methods or "GET" not in methods:
            continue
        if route.path.startswith(_PROBE_PREFIX):
            continue
        out.append((route.path, _fill(route.path)))
    return sorted(set(out))


@pytest.fixture(scope="module")
def client():
    with TestClient(app, raise_server_exceptions=False) as c:
        yield c


@pytest.fixture
def fresh_limiter():
    """Isolate the shared slowapi limiter around a test that exhausts it.

    Also forces ``limiter.enabled = True``. ``enabled`` is resolved from
    the environment once, at import time
    (``web/dependencies/rate_limit.py``: ``limiter.enabled =
    _RATE_LIMITING_ENABLED``), and CI runs with
    ``LDR_DISABLE_RATE_LIMITING=true`` -- so without this every request
    below is admitted, no 429 is ever produced, and both the positive
    control and the strict xfail it guards stop testing the limiter at
    all. ``limiter.reset()`` clears the buckets but does NOT re-enable
    enforcement. Same pattern as
    ``tests/web/routers/test_auth_rate_limits.py::rate_limiting_enforced``
    and ``test_benchmark_start_shared_bucket.py``.
    """
    original_enabled = limiter.enabled
    limiter.enabled = True
    limiter.reset()
    try:
        yield
    finally:
        limiter.enabled = original_enabled
        limiter.reset()


# ---------------------------------------------------------------------------
# The census: every GET route, driven as an unauthenticated browser
# ---------------------------------------------------------------------------

# Routes whose response to an unauthenticated browser navigation does not
# match its path shape. Every entry is reviewed; a new route landing here
# is a content-negotiation bug until someone justifies it in this table.
#
REVIEWED_CENSUS_EXCEPTIONS = {
    # Deliberate: an XHR auth probe, not a navigable page. The frontend
    # reads {"authenticated": false} to decide whether to show a login
    # prompt, so a 302 to the login HTML would defeat its only purpose.
    "/auth/check": "auth probe endpoint, JSON by design",
    # Deliberate: a public JSON endpoint the login form fetches before it
    # can post anything. No browser navigates here.
    "/auth/csrf-token": "public JSON token endpoint, JSON by design",
    # KNOWN DEFECT, reported elsewhere; listed so this census is complete.
    "/favicon.ico": "known defect: JSON 404 to a browser",
    "/static/{path:path}": "known defect: JSON 404 to a browser",
}


def _classify(response):
    """'json', 'browser', or a description of something unexpected."""
    ctype = response.headers.get("content-type", "").split(";")[0].strip()
    if 300 <= response.status_code < 400:
        return "browser"
    if ctype == "application/json":
        return "json"
    if ctype.startswith("text/html"):
        return "browser"
    return f"neither (status={response.status_code} type={ctype!r})"


class TestUnauthenticatedBrowserCensus:
    """Every GET route, hit signed-out with a browser ``Accept``."""

    def test_route_table_is_large_enough_to_be_a_census(self):
        """Guard the sweep against silently enumerating nothing.

        If the app ever fails to mount its routers, ``app.routes`` shrinks
        to a handful and every sweep below passes vacuously. This is the
        tripwire for that.
        """
        routes = _get_routes()
        assert len(routes) > 150, (
            f"only {len(routes)} GET routes found; the app did not mount "
            "its routers and every census below would pass vacuously"
        )
        # Both populations must be non-empty, or one branch of the policy
        # is going untested.
        api = [p for p, _ in routes if _path_is_api_shaped(p)]
        browser = [p for p, _ in routes if not _path_is_api_shaped(p)]
        assert len(api) > 50 and len(browser) > 20, (
            f"degenerate partition: {len(api)} api-shaped, "
            f"{len(browser)} browser-shaped"
        )

    def test_every_get_route_matches_its_path_shape(self, client):
        """The whole-app gate: response kind must follow path shape.

        An ``/api/``-shaped path must answer a browser with JSON (a
        programmatic caller must never be bounced into an HTML login
        page); a browser-shaped path must answer with HTML or a redirect
        (a user must never be shown a raw JSON body). Collected across
        every route so one run reports every violation, not the first.
        """
        violations = []
        for path, url in _get_routes():
            response = client.get(
                url,
                headers={"accept": BROWSER_ACCEPT},
                follow_redirects=False,
            )
            kind = _classify(response)
            expected = "json" if _path_is_api_shaped(path) else "browser"
            if kind == expected:
                continue
            if path in REVIEWED_CENSUS_EXCEPTIONS:
                continue
            violations.append(
                f"{path}: expected {expected}, got {kind} "
                f"(status={response.status_code}, "
                f"body={response.text[:60]!r})"
            )
        assert not violations, (
            "routes whose unauthenticated browser response contradicts "
            "their path shape:\n  " + "\n  ".join(violations)
        )

    def test_reviewed_exceptions_are_all_still_real(self, client):
        """Keep the exception table honest.

        A table of blessed deviations rots into a table of blessed
        anything the moment an entry stops deviating. Each entry must
        still actually deviate, or it has been fixed and must be deleted
        so the route rejoins the gate above.
        """
        stale = []
        by_path = dict(_get_routes())
        for path in REVIEWED_CENSUS_EXCEPTIONS:
            assert path in by_path, (
                f"{path} is in the exception table but is no longer a "
                "GET route; delete the entry"
            )
            response = client.get(
                by_path[path],
                headers={"accept": BROWSER_ACCEPT},
                follow_redirects=False,
            )
            expected = "json" if _path_is_api_shaped(path) else "browser"
            if _classify(response) == expected:
                stale.append(path)
        assert not stale, (
            "these no longer deviate and must be removed from "
            f"REVIEWED_CENSUS_EXCEPTIONS: {stale}"
        )

    def test_partition_helper_agrees_with_the_real_policy(self, client):
        """``_path_is_api_shaped`` must track ``_is_api_request``.

        The partition above decides what each route is *expected* to do.
        If it drifted from the shipped policy the census would grade
        against a fiction, so pin it against the real function -- driven
        through a real request object, with an ``Accept`` that cannot
        itself trigger the policy's second mechanism.
        """
        from starlette.requests import Request

        mismatches = []
        for path, url in _get_routes():
            scope = {
                "type": "http",
                "method": "GET",
                "path": url,
                "headers": [(b"accept", BROWSER_ACCEPT.encode())],
                "query_string": b"",
            }
            real = _is_api_request(Request(scope))
            if real != _path_is_api_shaped(url):
                mismatches.append((path, url, real))
        assert not mismatches, (
            "the census partition disagrees with the shipped "
            f"_is_api_request: {mismatches}"
        )


# ---------------------------------------------------------------------------
# History JSON requests negotiate independently of their path shape
# ---------------------------------------------------------------------------

# JSON endpoints called only by JavaScript whose paths carry no /api/
# segment. Derived by enumerating the route table, not hand-picked.
HISTORY_XHR_ROUTES = [
    "/history/status/{research_id}",
    "/history/logs/{research_id}",
    "/history/report/{research_id}",
    "/history/markdown/{research_id}",
    "/history/details/{research_id}",
    "/history/log_count/{research_id}",
]


class TestXhrRoutesWithoutAnApiPathSegment:
    """The shared browser client explicitly requests JSON for these routes."""

    @pytest.mark.parametrize("path", HISTORY_XHR_ROUTES)
    def test_an_expired_session_reaches_the_caller_as_a_401(self, client, path):
        """A JSON endpoint must report auth failure *as* auth failure.

        Follow redirects as fetch does by default, so an accidental login
        redirect cannot look like a successful JSON response.
        """
        response = client.get(
            _fill(path),
            headers={
                "accept": JSON_ACCEPT,
                "content-type": "application/json",
            },
            follow_redirects=True,
        )
        assert response.status_code == 401, (
            f"XHR caller got {response.status_code} "
            f"{response.headers.get('content-type')} from "
            f"{response.url.path} after {len(response.history)} redirects"
        )
        assert response.headers["content-type"].startswith("application/json")
        assert response.history == []

    def test_the_api_shaped_sibling_gets_this_right(self, client):
        """An /api/ route also returns JSON with native fetch's default."""
        response = client.get(
            "/api/research/probe/status",
            headers={
                "accept": FETCH_DEFAULT_ACCEPT,
                "content-type": "application/json",
            },
            follow_redirects=True,
        )
        assert response.status_code == 401
        assert response.headers["content-type"].startswith("application/json")
        assert response.history == [], (
            "the api-shaped sibling should answer directly, not redirect"
        )


# ---------------------------------------------------------------------------
# Defect 2: CSRFMiddleware short-circuits before the policy exists
# ---------------------------------------------------------------------------

# The only routes in the app that accept a real browser form submission.
BROWSER_FORM_POSTS = [
    ("/auth/login", {"username": "u", "password": "p"}),
    ("/auth/register", {"username": "u", "password": "p"}),
    ("/settings/save_settings", {"some_setting": "1"}),
]


class TestCsrfRejectionIgnoresNegotiation:
    """403s from ASGI middleware never reach ``_is_api_request``."""

    @pytest.mark.parametrize("path,form", BROWSER_FORM_POSTS)
    def test_csrf_rejection_is_reached_and_is_json(self, client, path, form):
        """Positive control: the rejection really does fire, and is JSON.

        Establishes that the requests below are actually exercising the
        CSRF path (rather than 404ing or being rejected earlier for some
        other reason), so the xfail that follows is about negotiation and
        nothing else.
        """
        response = client.post(
            path,
            data=form,
            headers={"accept": BROWSER_ACCEPT},
            follow_redirects=False,
        )
        assert response.status_code == 403
        assert "csrf" in response.text.lower(), (
            f"expected a CSRF rejection, got {response.text[:120]!r}"
        )

    @pytest.mark.parametrize("path,form", BROWSER_FORM_POSTS)
    @pytest.mark.xfail(
        strict=True,
        reason=(
            "CSRFMiddleware (web/dependencies/csrf.py) builds a bare "
            "JSONResponse(403) at all three of its rejection sites and "
            "never calls _is_api_request. As ASGI middleware it "
            "short-circuits before the exception handlers, so the policy "
            "is not merely mis-applied -- it is never consulted. These "
            "are the app's only real browser form posts, so a stale "
            "token replaces the login/settings page with a raw JSON "
            "blob. Fix by branching on _is_api_request in csrf.py."
        ),
    )
    def test_a_stale_token_on_a_form_post_does_not_show_json(
        self, client, path, form
    ):
        """A browser submitting a form must never be handed raw JSON."""
        response = client.post(
            path,
            data=form,
            headers={"accept": BROWSER_ACCEPT},
            follow_redirects=False,
        )
        ctype = response.headers.get("content-type", "")
        assert not ctype.startswith("application/json"), (
            f"browser form post to {path} got {ctype}: {response.text[:120]!r}"
        )


# ---------------------------------------------------------------------------
# Defect 3: the 429 handler ignores negotiation, and only browser form
# posts are rate limited
# ---------------------------------------------------------------------------


class TestRateLimitRejectionIgnoresNegotiation:
    """A 429 the browser can reach, rendered only as JSON."""

    def test_browser_shaped_routes_are_among_the_rate_limited(self):
        """Why a non-negotiating 429 matters here specifically.

        Most of the 80-odd rate-limited routes are ``/api/``-shaped, and
        for those an unconditional JSON 429 is exactly right -- which is
        presumably why the handler was written that way. The problem is
        the minority: enumerate the rate-limited set and partition it,
        and a browser-shaped group falls out, including the login form
        itself. Those are the ones the unconditional JSON body breaks.
        """
        limited = []
        for route in app.routes:
            endpoint = getattr(route, "endpoint", None)
            if endpoint is None:
                continue
            key = f"{endpoint.__module__}.{endpoint.__qualname__}"
            if key in getattr(limiter, "_route_limits", {}):
                limited.append(route.path)
        assert limited, (
            "no rate-limited routes found; the limiter registry moved and "
            "this test is checking nothing"
        )
        browser_shaped = sorted(
            {p for p in limited if not _path_is_api_shaped(p)}
        )
        assert browser_shaped, (
            "every rate-limited route is now api-shaped; a JSON-only 429 "
            "would be correct and the xfail below should XPASS"
        )
        # The login form is the case that matters most: it is reachable
        # signed-out, and six wrong passwords is an ordinary user event
        # rather than an attack.
        assert "/auth/login" in browser_shaped, (
            "POST /auth/login is no longer rate limited; re-derive the "
            f"xfail below against one of {browser_shaped}"
        )

    def test_the_rate_limit_is_actually_reachable(self, client, fresh_limiter):
        """Positive control: a browser really can reach the 429.

        Proves the loop in the xfail below drives the limiter rather than
        being absorbed by CSRF, auth, or the bad-password path -- so an
        XFAIL there means "the 429 rendered wrongly", not "no 429
        happened". Deliberately says nothing about the response's
        content type: that is the xfail's job, and asserting it here too
        would mean a fix breaks two tests and obscures which one is the
        regression signal.
        """
        token = client.get("/auth/csrf-token").json()["csrf_token"]
        statuses = []
        for _ in range(8):
            response = client.post(
                "/auth/login",
                data={"username": "nobody", "password": "wrong"},
                headers={"accept": BROWSER_ACCEPT, "X-CSRFToken": token},
                follow_redirects=False,
            )
            statuses.append(response.status_code)
            if response.status_code == 429:
                return
        pytest.fail(f"never hit the rate limit; statuses were {statuses}")

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "_rate_limit_exceeded (fastapi_app.py) always returns a "
            "JSONResponse and never calls _is_api_request. That is right "
            "for the api-shaped majority of rate-limited routes but "
            "wrong for the eight browser-shaped ones, which include the "
            "login, register, change-password and save-settings form "
            "posts. Six bad password attempts therefore replace the "
            'login page with {"error": "Too many requests"} in the '
            "address bar. Fix by branching on _is_api_request in the "
            "handler."
        ),
    )
    def test_hitting_the_login_rate_limit_does_not_show_json(
        self, client, fresh_limiter
    ):
        """A user failing to log in must still see the login page."""
        token = client.get("/auth/csrf-token").json()["csrf_token"]
        for _ in range(8):
            response = client.post(
                "/auth/login",
                data={"username": "nobody", "password": "wrong"},
                headers={"accept": BROWSER_ACCEPT, "X-CSRFToken": token},
                follow_redirects=False,
            )
            if response.status_code == 429:
                ctype = response.headers.get("content-type", "")
                assert not ctype.startswith("application/json"), (
                    f"browser hit the login rate limit and got {ctype}: "
                    f"{response.text[:120]!r}"
                )
                return
        pytest.fail("never hit the rate limit")


# ---------------------------------------------------------------------------
# Defect 4: _send_413 re-implements half of _is_api_request
# ---------------------------------------------------------------------------


def _drive_413(path: str, accept: str):
    """Run the real BodySizeLimitMiddleware over an oversized body."""

    async def _never(scope, receive, send):  # pragma: no cover - guard
        raise AssertionError("request should have been rejected as too large")

    middleware = BodySizeLimitMiddleware(
        _never, max_body_size=10, max_json_body_size=10
    )
    sent = []

    async def receive():
        return {"type": "http.request", "body": b"x" * 100, "more_body": False}

    async def send(message):
        sent.append(message)

    asyncio.run(
        middleware(
            {
                "type": "http",
                "method": "POST",
                "path": path,
                "headers": [
                    (b"content-length", b"100"),
                    (b"accept", accept.encode()),
                ],
            },
            receive,
            send,
        )
    )
    start = next(m for m in sent if m["type"] == "http.response.start")
    ctype = dict(start["headers"])[b"content-type"].decode()
    return start["status"], ctype


# A JSON route with no /api/ segment, so only the Accept mechanism can
# classify it. Taken from the census, not invented.
NON_API_JSON_POST = "/settings/save_all_settings"


class TestBodyLimit413NegotiatesOnPathOnly:
    """``_send_413`` implements the path mechanism and not the other."""

    def test_the_path_mechanism_works(self):
        """Positive control: the half that is implemented does work.

        Without this, a failure below could equally mean the middleware
        never negotiates at all, or that the probe is malformed.
        """
        status, ctype = _drive_413("/api/start_research", BROWSER_ACCEPT)
        assert status == 413
        assert ctype.startswith("application/json")

        status, ctype = _drive_413(NON_API_JSON_POST, BROWSER_ACCEPT)
        assert status == 413
        # PR #5424: a browser on a non-api path now gets the branded
        # pages/error.html page (text/html), not plain text or JSON.
        assert ctype.startswith("text/html"), (
            "a browser on a non-api path should get HTML, not JSON"
        )

    def test_the_route_really_has_no_api_segment(self):
        """Guard the probe: if this path gained an ``/api/`` segment the
        test below would pass for the wrong reason."""
        assert not _path_is_api_shaped(NON_API_JSON_POST)
        assert any(route.path == NON_API_JSON_POST for route in app.routes), (
            f"{NON_API_JSON_POST} is no longer a route; pick another"
        )

    @pytest.mark.xfail(
        strict=True,
        reason=(
            "BodySizeLimitMiddleware._send_413 (fastapi_app.py) inlines "
            '\'"/api/" in path or path.endswith("/api")\' -- a hand copy '
            "of _is_api_request's first mechanism that omits the second. "
            "It never reads the Accept header, so a programmatic client "
            "sending Accept: application/json to a non-/api/ JSON route "
            "gets the branded text/html error page (PR #5424) instead of "
            "JSON, and its json() call fails. Fix by calling "
            "_is_api_request instead of duplicating half of it."
        ),
    )
    def test_an_explicit_json_accept_is_honoured(self):
        """The second mechanism must work here too, or it is not a policy.

        ``_is_api_request`` promises JSON to a caller that asks for JSON,
        whatever the path. A second implementation that honours only the
        path is exactly the drift the 404 handler already suffered.
        """
        status, ctype = _drive_413(NON_API_JSON_POST, JSON_ACCEPT)
        assert status == 413
        assert ctype.startswith("application/json"), (
            f"client sent Accept: application/json and got {ctype!r}"
        )


# ---------------------------------------------------------------------------
# Census result that is currently clean: no page route returns a JSON
# error instead of raising
# ---------------------------------------------------------------------------

HTML_RENDER_CALLS = {"TemplateResponse", "HTMLResponse", "render_template"}
JSON_RESPONSE_CALLS = {"JSONResponse", "ORJSONResponse"}


def _html_rendering_routes():
    """Routes whose handler renders a template or returns HTML."""
    found = []
    for route in app.routes:
        endpoint = getattr(route, "endpoint", None)
        if endpoint is None:
            continue
        try:
            tree = ast.parse(textwrap.dedent(inspect.getsource(endpoint)))
        except (OSError, TypeError, SyntaxError):
            continue
        called = {
            getattr(node.func, "id", None) or getattr(node.func, "attr", None)
            for node in ast.walk(tree)
            if isinstance(node, ast.Call)
        }
        if called & HTML_RENDER_CALLS:
            found.append((route, tree))
    return found


class TestNoBrowserPageReturnsAJsonError:
    """``return JSONResponse(...)`` never reaches the 404/401 handlers.

    Only ``raise`` enters the exception-handler stack; ``return`` hands
    Starlette a finished response, so a page route that returns a JSON
    error bypasses ``_is_api_request`` no matter how correct the handlers
    are. Four library page routes did exactly this earlier on this
    branch. They are fixed; this is the gate that keeps them fixed and
    catches the next one.
    """

    def test_the_sweep_finds_the_page_routes(self):
        """Tripwire: if the AST scan matches nothing, the gate is vacuous."""
        routes = _html_rendering_routes()
        assert len(routes) > 30, (
            f"only {len(routes)} HTML-rendering routes detected; the "
            "detection heuristic has broken and the gate below would "
            "pass vacuously"
        )

    def test_no_html_route_returns_a_json_error_response(self):
        """Every HTML page route must ``raise`` its errors, not return them."""
        offenders = []
        for route, tree in _html_rendering_routes():
            if _path_is_api_shaped(route.path):
                continue
            for node in ast.walk(tree):
                if not isinstance(node, ast.Return):
                    continue
                if not isinstance(node.value, ast.Call):
                    continue
                name = getattr(node.value.func, "id", None) or getattr(
                    node.value.func, "attr", None
                )
                if name not in JSON_RESPONSE_CALLS:
                    continue
                status = next(
                    (
                        getattr(kw.value, "value", None)
                        for kw in node.value.keywords
                        if kw.arg == "status_code"
                    ),
                    None,
                )
                if isinstance(status, int) and status >= 400:
                    offenders.append(
                        f"{route.path} returns JSONResponse(status_code="
                        f"{status}) at line {node.lineno} of its handler"
                    )
        assert not offenders, (
            "HTML page routes returning a JSON error bypass the exception "
            "handlers entirely (return, not raise):\n  "
            + "\n  ".join(offenders)
        )