~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
"""What runs — and what it *does* — before ``require_auth`` answers.
``tests/web/dependencies/test_dependency_contracts.py`` pins the shape of
FastAPI's dependency solver: signature order, caching, override plumbing,
``yield`` teardown. This module pins the layer underneath it — the part
that decides whether "auth is declared first" is actually a gate.
The distinction matters because the notes body-gate bug was never really
about parameter order. It was about a *side effect that a 401 cannot
undo*: the body had already been pulled off the wire and ``json.loads``-ed
by the time ``require_auth`` said no. Swapping two parameters fixed that
one instance. It does not, and cannot, fix the general case — because
FastAPI reads the request body **before** ``solve_dependencies`` is
called at all (``fastapi/routing.py``: body at ~line 404, dependencies at
~line 457, fastapi 0.136.3). No parameter ordering reaches earlier than
that.
So the questions this module answers are the ones ordering alone cannot:
1. **Body** — which routes still hand an anonymous caller's bytes to a
parser before auth runs, and what does the client learn from it.
2. **Rate-limit slots** — a slot consumed by a request that then 401s is
a side effect a later auth failure cannot undo. Two different answers
here depending on whether the limit is a decorator or the middleware
default.
3. **``get_db_session_dep``** — whether a database is opened before auth
is decided, whether the session can be another session's, and what its
``try/except`` does to an exception that came from the *route*, not
from the dependency.
4. **Divergence** — ``Depends`` caches per callable, so two dependencies
that both "resolve the username" are two independent answers. They do
disagree, on the same request, today.
5. **Error paths** — what the client sees when a dependency fails in a
way that is not an ``HTTPException``.
Every ordering claim here is asserted against an observed side effect (a
byte count pulled through ``receive``, a rate-limit counter, a recorded
``get_user_db_session`` call, a ``Set-Cookie``), never against a status
code alone.
"""
from __future__ import annotations
import ast
import contextlib
import pathlib
import threading
from typing import Any
from unittest import mock
import pytest
from fastapi import Body, Depends, FastAPI, Form, HTTPException, Request
from fastapi.testclient import TestClient
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.errors import RateLimitExceeded
from slowapi.middleware import SlowAPIMiddleware
from starlette.middleware.sessions import SessionMiddleware
from local_deep_research.database.session_context import (
DatabaseSessionError,
)
from local_deep_research.web.dependencies import auth as auth_module
from local_deep_research.web.dependencies import rate_limit as rl_module
SECRET = "unit-test-session-secret-key-0123456789"
_DEPS_DIR = pathlib.Path(auth_module.__file__).parent
_WEB_DIR = _DEPS_DIR.parent
_ROUTERS_DIR = _WEB_DIR / "routers"
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
class ReceiveSpy:
"""ASGI wrapper counting body bytes the inner app pulls off the wire.
The only honest way to ask "was the body consumed before the 401?" —
a status code cannot tell you, and ``Request.body()`` caches, so
inspecting it after the fact proves nothing about *when*.
"""
def __init__(self, app):
self.app = app
self.body_bytes = 0
self.receive_calls = 0
def reset(self) -> None:
self.body_bytes = 0
self.receive_calls = 0
async def __call__(self, scope, receive, send):
async def spy():
message = await receive()
self.receive_calls += 1
if message["type"] == "http.request":
self.body_bytes += len(message.get("body", b""))
return message
await self.app(scope, spy, send)
def _denying_gate(log: list[str]):
"""A stand-in for ``require_auth`` that always refuses.
Used where the point is the solver's ordering, not ``require_auth``'s
internals; the real dependency is exercised directly further down.
"""
def gate(request: Request) -> str:
log.append("auth")
raise HTTPException(status_code=401, detail="Authentication required")
return gate
def _make_recording_db_session(calls: list[tuple]):
"""Replacement for ``get_user_db_session`` that records how it was
called: which username, which ``session_id``, and on which thread.
"""
@contextlib.contextmanager
def fake(username=None, password=None, session_id=None, **kwargs):
calls.append(("open", username, session_id, threading.get_ident()))
try:
yield object()
finally:
calls.append(("close", threading.get_ident()))
return fake
class _AlwaysConnected:
@staticmethod
def is_user_connected(username): # noqa: ARG004
return True
@contextlib.contextmanager
def _authenticated_auth_module():
"""Patch ``require_auth``'s two collaborators so it accepts a session
carrying ``username`` + ``session_id``. Both are patched at the seams
the module itself documents; nothing about the ordering under test is
faked.
"""
with (
mock.patch.object(
auth_module.db_manager,
"is_user_connected",
_AlwaysConnected.is_user_connected,
),
mock.patch.object(
auth_module, "_server_session_valid", lambda request, user: True
),
):
yield
def _session_app() -> FastAPI:
app = FastAPI()
app.add_middleware(
SessionMiddleware, secret_key=SECRET, session_cookie="session"
)
return app
def _add_login_stub(app: FastAPI, session_id: str = "sid-1") -> None:
@app.post("/_stub-login")
def _stub_login(request: Request):
request.session["username"] = "alice"
request.session["session_id"] = session_id
return {"ok": True}
def _route_functions(path: pathlib.Path):
"""Yield ``(func_node, is_route)`` for every ``@router.<verb>`` def."""
tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
for node in ast.walk(tree):
if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
continue
for dec in node.decorator_list:
if (
isinstance(dec, ast.Call)
and isinstance(dec.func, ast.Attribute)
and isinstance(dec.func.value, ast.Name)
and dec.func.value.id == "router"
):
yield node
break
def _params_with_defaults(node):
args = node.args
positional = list(args.posonlyargs) + list(args.args)
pad = [None] * (len(positional) - len(args.defaults))
pairs = list(zip(positional, pad + list(args.defaults)))
pairs += list(zip(args.kwonlyargs, args.kw_defaults))
return pairs
def _annotated_metadata(annotation):
"""Yield each metadata expression inside ``Annotated[T, meta, ...]``.
Handles both the bare-name (``Annotated[...]``) and qualified
(``typing.Annotated[...]``) spellings. ``ast.Subscript.slice`` is the
expression directly on the Python versions this project targets (3.9+),
so a multi-element subscript is an ``ast.Tuple``.
"""
if not isinstance(annotation, ast.Subscript):
return
head = annotation.value
is_annotated = (isinstance(head, ast.Name) and head.id == "Annotated") or (
isinstance(head, ast.Attribute) and head.attr == "Annotated"
)
if not is_annotated:
return
sl = annotation.slice
elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
# elts[0] is the wrapped type; everything after it is metadata.
yield from elts[1:]
def _declared_body_params(node) -> list[tuple[str, str]]:
"""Body-bound parameters: ``Form()`` / ``File()`` / ``Body()`` defaults
and ``UploadFile`` annotations. These are the ones FastAPI resolves
from the request body, i.e. the ones that force a pre-dependency read.
A parameter may spell its body binding either the legacy way
(``x: T = Form()``) or via ``Annotated``
(``x: Annotated[T, Form()]``) -- both must be detected or this scan
silently blinds itself to every ``Annotated``-spelled route (which is
exactly what the FAST002 conversion produced for every ``Form``
parameter in this router directory).
"""
found = []
for arg, default in _params_with_defaults(node):
candidates = [default] if default is not None else []
candidates += list(_annotated_metadata(arg.annotation))
for candidate in candidates:
if (
isinstance(candidate, ast.Call)
and isinstance(candidate.func, ast.Name)
and candidate.func.id in {"Form", "File", "Body"}
):
found.append((arg.arg, candidate.func.id))
if arg.annotation is not None:
rendered = ast.unparse(arg.annotation)
if "UploadFile" in rendered:
found.append((arg.arg, "UploadFile"))
return found
def _depends_target(default):
if (
isinstance(default, ast.Call)
and isinstance(default.func, ast.Name)
and default.func.id == "Depends"
and default.args
):
target = default.args[0]
return (
target.id
if isinstance(target, ast.Name)
else getattr(target, "attr", "")
)
return None
def _declares_require_auth(node) -> bool:
for arg, default in _params_with_defaults(node):
candidates = [default] if default is not None else []
candidates += list(_annotated_metadata(arg.annotation))
for candidate in candidates:
if _depends_target(candidate) == "require_auth":
return True
return False
# ---------------------------------------------------------------------------
# 1. The body is read before any dependency, so ordering cannot gate it
# ---------------------------------------------------------------------------
class TestBodyArrivesBeforeAnyDependency:
"""The notes fix works because its gate is a ``Depends``.
A *declared* body parameter is not a dependency: FastAPI resolves it
from a body it has already read, before ``solve_dependencies`` runs.
So for those routes the notes remedy (put auth first) is unavailable
by construction, and the tests below measure exactly how much work an
anonymous caller gets out of the process anyway.
"""
@staticmethod
def _app(log: list[str]):
gate = _denying_gate(log)
app = FastAPI()
@app.post("/with-form")
def with_form(
username: str = Depends(gate),
payload: str = Form(""),
):
log.append("handler")
return {"ok": True}
@app.post("/no-body-field")
def no_body_field(username: str = Depends(gate)):
log.append("handler")
return {"ok": True}
@app.post("/with-json")
def with_json(
username: str = Depends(gate),
data: dict = Body(...),
):
log.append("handler")
return {"ok": True}
return app
def test_a_declared_form_body_is_fully_read_before_auth_refuses(self):
log: list[str] = []
spy = ReceiveSpy(self._app(log))
client = TestClient(spy)
raw = b"payload=" + b"x" * 5000
response = client.post(
"/with-form",
content=raw,
headers={"content-type": "application/x-www-form-urlencoded"},
)
assert response.status_code == 401
# The gate ran and the handler did not — ordering is intact.
assert log == ["auth"]
# And yet every byte was pulled through ``receive`` and handed to
# Starlette's form parser first. That is the side effect the 401
# cannot undo.
assert spy.body_bytes == len(raw)
def test_a_route_without_a_body_field_reads_nothing(self):
"""Negative control for the test above.
Same client, same method, same bytes on the wire. The only
difference is the declared ``Form`` parameter — so the 5008 bytes
measured above are attributable to it and not to the transport,
the TestClient, or ``Content-Length`` handling.
"""
log: list[str] = []
spy = ReceiveSpy(self._app(log))
client = TestClient(spy)
raw = b"payload=" + b"x" * 5000
response = client.post(
"/no-body-field",
content=raw,
headers={"content-type": "application/x-www-form-urlencoded"},
)
assert response.status_code == 401
assert log == ["auth"]
assert spy.body_bytes == 0
def test_unparseable_json_422s_without_running_the_auth_dependency(self):
"""The strongest form of the ordering problem.
A body that will not parse raises ``RequestValidationError`` from
the body-reading block, i.e. before ``solve_dependencies`` is
entered. ``require_auth`` never executes. An anonymous caller
therefore gets a 422 that describes the route's body contract —
including the byte offset of their syntax error — from a route
they are not authorised to call.
"""
log: list[str] = []
client = TestClient(self._app(log))
response = client.post(
"/with-json",
content=b"{not json",
headers={"content-type": "application/json"},
)
assert response.status_code == 422
assert log == []
detail = response.json()["detail"]
assert detail[0]["type"] == "json_invalid"
def test_a_parseable_but_wrongly_shaped_body_still_loses_to_auth(self):
"""Positive control: body *validation* does happen after
dependencies, which is why only the parse failure escapes the
gate. Without this the test above would read as "422 always wins",
which is not the contract.
"""
log: list[str] = []
client = TestClient(self._app(log))
response = client.post(
"/with-json",
json=[1, 2],
)
assert response.status_code == 401
assert log == ["auth"]
assert response.json()["detail"] == "Authentication required"
def test_change_password_is_the_only_authed_route_with_a_body_field(self):
"""Census, and the guard the notes ordering test cannot provide.
``tests/web/routers/test_notes_body_gate_ordering.py`` pins that
the notes ``Depends`` gate stays after ``require_auth``. That
remedy is unavailable to any route with a *declared* body field,
so the only durable guard is to keep such routes off the
authenticated surface.
Today exactly one authenticated route has one:
``POST /auth/change-password``. Its three ``Form`` parameters are
parsed from an anonymous caller's body before ``require_auth``
runs, and reordering the signature would not change that. The
exposure is bounded — urlencoded, under ``BodySizeLimitMiddleware``
and behind ``CSRFMiddleware`` — but it is the same shape as the
notes bug, and this list must not grow.
The three unauthenticated ``/auth`` form routes are listed too, so
that a new one is noticed rather than silently absorbed.
"""
rows = {}
for path in sorted(_ROUTERS_DIR.glob("*.py")):
for node in _route_functions(path):
body_params = _declared_body_params(node)
if body_params:
rows[(path.name, node.name)] = (
_declares_require_auth(node),
tuple(sorted(body_params)),
)
assert set(rows) == {
("auth.py", "login"),
("auth.py", "validate_password"),
("auth.py", "register"),
("auth.py", "change_password"),
}, (
"a router route grew a declared body field; FastAPI reads the "
"body before any dependency, so Depends(require_auth) cannot "
f"gate it. Current census: {rows}"
)
authed = {name for name, (is_authed, _) in rows.items() if is_authed}
assert authed == {("auth.py", "change_password")}
assert rows[("auth.py", "change_password")][1] == (
("confirm_password", "Form"),
("current_password", "Form"),
("new_password", "Form"),
)
def test_no_authenticated_route_declares_an_upload_parameter(self):
"""The severe version of the same problem, currently absent.
A declared ``UploadFile`` / ``File()`` parameter makes FastAPI run
Starlette's multipart parser before dependencies, which spools
parts to disk. That would be an anonymous, pre-auth *disk* write.
The two real upload routes (``rag``, ``research``) avoid it by
calling ``await request.form()`` inside the handler, i.e. after
``require_auth`` has already resolved.
"""
offenders = []
for path in sorted(_ROUTERS_DIR.glob("*.py")):
for node in _route_functions(path):
kinds = {kind for _n, kind in _declared_body_params(node)}
if kinds & {"File", "UploadFile"}:
offenders.append((path.name, node.name))
assert offenders == [], (
"declared upload parameters are parsed to disk before "
f"require_auth runs: {offenders}"
)
# ---------------------------------------------------------------------------
# 2. Rate-limit slots: consumed before or after auth?
# ---------------------------------------------------------------------------
def _probe_limiter(default_limits: list[str] | None = None) -> Limiter:
"""A private in-memory limiter.
Deliberately not the module-level ``rate_limit.limiter`` singleton:
these tests read and would otherwise pollute its shared counters. The
key functions ARE the production ones — the contract under test is
*when* slowapi hits the store relative to the dependency solver, which
is a slowapi/FastAPI property, not a value this module re-implements.
"""
return Limiter(
key_func=rl_module._get_client_ip,
strategy="moving-window",
enabled=True,
default_limits=default_limits or [],
)
def _events(limiter: Limiter) -> dict[str, int]:
"""Moving-window hits recorded in the in-memory store, per bucket."""
return {k: len(v) for k, v in limiter._storage.events.items()}
class TestRateLimitSlotsAndTheAuthGate:
@staticmethod
def _app(limiter: Limiter, *, allow: bool, with_middleware: bool):
app = FastAPI()
app.state.limiter = limiter
app.add_exception_handler(
RateLimitExceeded, _rate_limit_exceeded_handler
)
if with_middleware:
app.add_middleware(SlowAPIMiddleware)
app.add_middleware(SessionMiddleware, secret_key=SECRET)
shared = limiter.shared_limit(
"5 per minute", scope="probe", key_func=rl_module._user_key
)
ran: list[int] = []
def gate(request: Request) -> str:
if not allow:
raise HTTPException(
status_code=401, detail="Authentication required"
)
return "alice"
@app.post("/_stub-login")
def _stub_login(request: Request):
request.session["username"] = "alice"
return {"ok": True}
@app.post("/decorated")
@shared
def decorated(request: Request, username: str = Depends(gate)):
ran.append(1)
return {"ok": True}
@app.post("/undecorated")
def undecorated(request: Request, username: str = Depends(gate)):
ran.append(1)
return {"ok": True}
return app, ran
def test_a_401_consumes_no_slot_on_a_decorated_route(self):
"""``settings_limit`` / ``upload_rate_limit_user`` /
``api_rate_limit`` / the notes write limit are all
``shared_limit`` decorators, which wrap the *endpoint*. The
endpoint is only called once every dependency has resolved, so a
401 from ``require_auth`` short-circuits before slowapi touches
the store.
Security-relevant in the good direction: those buckets are keyed
``user:<name>`` by ``_user_key``, so if the slot were taken first
an anonymous attacker who knew a username could exhaust that
user's settings/upload quota. Asserted on the store, not on the
status code.
"""
limiter = _probe_limiter()
app, ran = self._app(limiter, allow=False, with_middleware=False)
client = TestClient(app)
codes = [client.post("/decorated").status_code for _ in range(4)]
assert codes == [401, 401, 401, 401]
assert ran == []
assert _events(limiter) == {}
def test_the_same_route_does_consume_a_slot_once_auth_passes(self):
"""Positive control for the test above: the limiter is live and
the bucket is the per-user one, so "no events" there means "not
reached", not "not configured".
"""
limiter = _probe_limiter()
app, ran = self._app(limiter, allow=True, with_middleware=False)
client = TestClient(app)
client.post("/_stub-login")
codes = [client.post("/decorated").status_code for _ in range(3)]
assert codes == [200, 200, 200]
assert ran == [1, 1, 1]
events = _events(limiter)
assert [k for k in events if "user:alice" in k], events
assert sum(events.values()) == 3
def test_the_global_default_limit_is_consumed_before_auth_decides(self):
"""The one slot an anonymous caller does take.
``SlowAPIMiddleware`` enforces ``DEFAULT_RATE_LIMIT`` from outside
the router — outside ``SessionMiddleware``'s consumers and before
any dependency — so every request that later 401s has already
counted against the per-IP default bucket. That is intended (a
default limit that only counted authenticated traffic would be
useless), but it is a real pre-auth side effect and the asymmetry
with the decorated case above is worth pinning: the two answers
come from two different enforcement points.
"""
limiter = _probe_limiter(default_limits=["50 per minute"])
app, ran = self._app(limiter, allow=False, with_middleware=True)
client = TestClient(app)
codes = [client.post("/undecorated").status_code for _ in range(3)]
assert codes == [401, 401, 401]
assert ran == []
events = _events(limiter)
assert sum(events.values()) == 3, events
assert all("user:" not in key for key in events), (
"the middleware ran before the session was consulted, so the "
f"bucket must be per-IP, not per-user: {events}"
)
# ---------------------------------------------------------------------------
# 3. get_db_session_dep: what it opens, when, and for whom
# ---------------------------------------------------------------------------
class TestGetDbSessionDep:
"""The dependency ``auth.py`` says not to wire.
It is unwired today (pinned elsewhere), but it is the only DB-session
dependency in the layer and ``get_settings_manager_dep`` already
composes it, so its behaviour is a live contract. Two things here are
findings rather than confirmations; both are marked in place.
"""
@staticmethod
def _app(*, raises: BaseException | None, is_async: bool):
app = _session_app()
_add_login_stub(app)
seen: list[str] = []
if is_async:
@app.get("/r")
async def route_async(
request: Request,
db_session: Any = Depends(auth_module.get_db_session_dep),
):
seen.append("handler")
if raises is not None:
raise raises
return {"ok": True}
else:
@app.get("/r")
def route_sync(
request: Request,
db_session: Any = Depends(auth_module.get_db_session_dep),
):
seen.append("handler")
if raises is not None:
raise raises
return {"ok": True}
return app, seen
def test_an_anonymous_request_never_opens_a_database(self):
"""``require_auth`` is a sub-dependency of ``get_db_session_dep``,
so it resolves first and its 401 short-circuits the parent. The
assertion is on the recorded ``get_user_db_session`` calls: no
connection is opened, no password is resolved, nothing needs
undoing.
"""
calls: list[tuple] = []
app, seen = self._app(raises=None, is_async=False)
with mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
):
client = TestClient(app)
response = client.get("/r")
assert response.status_code == 401
assert seen == []
assert calls == []
def test_the_requests_own_session_id_is_threaded_through(self):
"""Guards the cross-session fallback.
``get_user_db_session`` resolves the password from ``session_id``
when given one and otherwise falls back to
``get_any_session_password(username)`` — "whichever of this user's
live sessions happens to have a password". ``get_db_session_dep``
passes the request's own ``session_id``, so that fallback is not
reachable through it. Asserted on the recorded call arguments.
"""
calls: list[tuple] = []
app, seen = self._app(raises=None, is_async=False)
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
),
):
client = TestClient(app)
client.post("/_stub-login")
response = client.get("/r")
assert response.status_code == 200
opens = [c for c in calls if c[0] == "open"]
assert len(opens) == 1
assert opens[0][1] == "alice"
assert opens[0][2] == "sid-1", (
"session_id must reach get_user_db_session, or the password "
"resolver falls back to any live session for this user"
)
# The open strictly precedes the handler and the close strictly
# follows it: the yield really does bracket the request.
assert seen == ["handler"]
assert [c[0] for c in calls] == ["open", "close"]
def test_database_session_error_while_entering_forces_reauthentication(
self,
):
"""A setup failure is an expired-login failure, not a route error.
``get_user_db_session`` can raise from the context manager's
``__enter__`` before ``get_db_session_dep`` reaches its yield. The
dependency must still invalidate the browser session and the route
handler must never run.
"""
app, seen = self._app(raises=None, is_async=False)
failing_context = mock.MagicMock()
failing_context.__enter__.side_effect = DatabaseSessionError(
"password unavailable"
)
get_db_session = mock.Mock(return_value=failing_context)
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module, "get_user_db_session", get_db_session
),
):
client = TestClient(app)
client.post("/_stub-login")
assert client.cookies.get("session")
response = client.get("/r")
assert response.status_code == 401
assert response.json() == {
"detail": "Session expired — please log in again"
}
assert seen == []
get_db_session.assert_called_once_with("alice", session_id="sid-1")
failing_context.__enter__.assert_called_once_with()
failing_context.__exit__.assert_not_called()
cleared = [
value.decode()
for key, value in response.headers.raw
if key.lower() == b"set-cookie"
and value.decode().startswith("session=")
]
assert len(cleared) == 1, response.headers.raw
assert "expires=Thu, 01 Jan 1970" in cleared[0]
assert dict(client.cookies) == {}
def test_none_from_database_context_is_500_without_clearing_session(self):
"""A context that enters but has no session is not an auth expiry.
The dependency emits its explicit 500 contract before yielding, so
the handler stays gated. Because no ``DatabaseSessionError`` was
raised, the authenticated browser session must remain usable.
"""
app, seen = self._app(raises=None, is_async=False)
null_context = mock.MagicMock()
null_context.__enter__.return_value = None
get_db_session = mock.Mock(return_value=null_context)
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module, "get_user_db_session", get_db_session
),
):
client = TestClient(app)
client.post("/_stub-login")
assert client.cookies.get("session")
response = client.get("/r")
assert response.status_code == 500
assert response.json() == {
"detail": "Failed to get database session"
}
assert seen == []
assert client.cookies.get("session")
assert not any(
b"expires=Thu, 01 Jan 1970" in value
for key, value in response.headers.raw
if key.lower() == b"set-cookie"
)
# A second request with a working database context proves that
# the first response left the authenticated session usable.
live_context = mock.MagicMock()
live_context.__enter__.return_value = object()
get_db_session.return_value = live_context
follow_up = client.get("/r")
assert follow_up.status_code == 200
assert follow_up.json() == {"ok": True}
assert seen == ["handler"]
assert get_db_session.call_args_list == [
mock.call("alice", session_id="sid-1"),
mock.call("alice", session_id="sid-1"),
]
null_context.__enter__.assert_called_once_with()
assert null_context.__exit__.call_count == 1
def test_a_route_raised_database_error_becomes_a_forced_logout(self):
"""FINDING. The ``try/except`` wraps the ``yield``, not just the
setup, so FastAPI's teardown ``throw()`` lands inside it.
A ``DatabaseSessionError`` raised by the *route handler* — a
failed query, an expired password mid-request, anything from the
business logic — is therefore caught by the dependency, converted
into ``401 "Session expired"``, and, critically,
``request.session.clear()`` destroys the user's session. The
client is logged out by an error that had nothing to do with
their credentials.
Asserted on the ``Set-Cookie``, not the status: the session cookie
comes back emptied and expired, and the client's jar is empty
afterwards.
"""
app, seen = self._app(
raises=DatabaseSessionError("query blew up"), is_async=False
)
calls: list[tuple] = []
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
),
):
client = TestClient(app)
client.post("/_stub-login")
assert client.cookies.get("session")
response = client.get("/r")
assert seen == ["handler"], "the route did run; this is its error"
assert response.status_code == 401
assert response.json()["detail"].startswith("Session expired")
cleared = [
value.decode()
for key, value in response.headers.raw
if key.lower() == b"set-cookie"
and value.decode().startswith("session=")
]
assert len(cleared) == 1, response.headers.raw
assert "expires=Thu, 01 Jan 1970" in cleared[0]
assert dict(client.cookies) == {}
def test_an_unrelated_route_exception_leaves_the_session_alone(self):
"""Negative control for the finding above.
Same app, same dependency, same teardown path — only the
exception type differs. A ``ValueError`` propagates as a 500 and
the session cookie is untouched, which is what makes the
``DatabaseSessionError`` behaviour a conversion by this dependency
rather than something FastAPI does to every failing request.
"""
app, seen = self._app(raises=ValueError("unrelated"), is_async=False)
calls: list[tuple] = []
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
),
):
client = TestClient(app, raise_server_exceptions=False)
client.post("/_stub-login")
response = client.get("/r")
assert seen == ["handler"]
assert response.status_code == 500
session_cookies = [
value
for key, value in response.headers.raw
if key.lower() == b"set-cookie"
]
assert session_cookies == []
assert client.cookies.get("session")
def test_the_forced_logout_happens_on_async_routes_too(self):
"""``get_db_session_dep`` is a *sync* generator, so on an
``async def`` route FastAPI still drives it through
``contextmanager_in_threadpool``. The conversion — and the
``request.session.clear()`` that goes with it — therefore runs on
a pooled worker thread while the event loop waits, and still
reaches the response. Same outcome, different thread.
"""
app, seen = self._app(
raises=DatabaseSessionError("query blew up"), is_async=True
)
calls: list[tuple] = []
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
),
):
client = TestClient(app)
client.post("/_stub-login")
response = client.get("/r")
assert seen == ["handler"]
assert response.status_code == 401
assert response.json()["detail"].startswith("Session expired")
assert dict(client.cookies) == {}
# The dependency was driven off the event loop: the recorded
# thread ids are not the loop's.
opens = [c for c in calls if c[0] == "open"]
assert opens and opens[0][3] != threading.get_ident()
def test_settings_manager_dep_opens_nothing_before_auth_decides(self):
"""``get_settings_manager_dep`` declares ``db_session`` *before*
``username``, which reads like the notes ordering bug. It is not:
``require_auth`` is a sub-dependency of ``get_db_session_dep``, so
depth-first resolution still puts it first. Pinned on the call
log, because the signature alone does not say so.
"""
app = _session_app()
_add_login_stub(app)
@app.get("/settings")
def settings_route(
manager: Any = Depends(auth_module.get_settings_manager_dep),
):
return {"ok": True}
calls: list[tuple] = []
with mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
):
client = TestClient(app)
anonymous = client.get("/settings")
assert anonymous.status_code == 401
assert calls == []
made: list[tuple] = []
with (
_authenticated_auth_module(),
mock.patch.object(
auth_module,
"get_user_db_session",
_make_recording_db_session(calls),
),
mock.patch.object(
auth_module,
"get_settings_manager",
lambda db, user: made.append((db, user)) or object(),
),
):
client = TestClient(app)
client.post("/_stub-login")
allowed = client.get("/settings")
assert allowed.status_code == 200
assert [c[0] for c in calls if c[0] == "open"] == ["open"]
assert [user for _db, user in made] == ["alice"]
def test_render_template_opens_a_db_without_the_request_session_id(self):
"""FINDING (static). The sibling helper does what
``get_db_session_dep``'s docstring forbids.
``get_db_session_dep`` threads ``session_id`` through precisely to
avoid ``get_any_session_password``. ``template_helpers.
render_template`` — reached by every HTML route, including the
unauthenticated ``GET /auth/login`` and ``GET /auth/register`` —
calls ``get_user_db_session(username)`` with a bare positional
username and no ``session_id``, off an unvalidated
``request.session["username"]``, to read ``policy.egress_scope``.
The password resolver then falls back to *any* live session for
that user. The residual exposure is same-user-cross-session rather
than cross-user (``DatabaseMiddleware._enforce_session_revocation``
clears a revoked cookie before the router is reached), but it is a
database open driven by a session the auth layer never validated,
and it is exactly the pattern the neighbouring docstring calls a
leak risk.
Asserted structurally so the two helpers cannot drift further
apart: within ``web/dependencies/``, ``render_template`` is the
only ``get_user_db_session`` call site that omits ``session_id``.
"""
omissions = []
for path in sorted(_DEPS_DIR.glob("*.py")):
tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
func = node.func
name = (
func.id
if isinstance(func, ast.Name)
else getattr(func, "attr", "")
)
if name != "get_user_db_session":
continue
passes_sid = any(kw.arg == "session_id" for kw in node.keywords)
if not passes_sid:
omissions.append(path.name)
assert omissions == ["template_helpers.py"], (
"a dependency-layer call to get_user_db_session dropped "
"session_id, re-enabling the get_any_session_password "
f"fallback: {omissions}"
)
# ---------------------------------------------------------------------------
# 4. Two dependencies, one username, two answers
# ---------------------------------------------------------------------------
class _DeadSessionManager:
"""Every session id is unknown — logout, password change, restart."""
@staticmethod
def validate_session(session_id): # noqa: ARG004
return None
@staticmethod
def session_owner(session_id): # noqa: ARG004
return None
@pytest.mark.real_session_check
class TestUsernameReadersDiverge:
"""``Depends`` caches by callable, so "the username" is not one value.
``get_session_username`` returns the raw cookie claim.
``require_auth`` additionally requires an open database *and* a live
server-side session. (Marked ``real_session_check`` so
``tests/conftest.py``'s autouse ``_legacy_bare_username_auth`` does not
relax the very gate that produces the divergence.) Both live in ``auth.py``, both take only
``Request``, and both are wired to real routes
(``api_v1.health_check`` uses the former). On a session whose
server-side record is gone they return different things on the same
request — and the cache cannot reconcile them, because it is keyed on
the callable.
"""
@staticmethod
def _app(log: list):
app = _session_app()
_add_login_stub(app, session_id="destroyed-sid")
def recording_soft(
username: str | None = Depends(auth_module.get_session_username),
) -> str | None:
# A thin recorder around the real dependency: it can only
# append once ``get_session_username`` has already resolved,
# so an entry here proves that resolution happened.
log.append(("soft", username))
return username
@app.get("/soft")
def soft(username: str | None = Depends(recording_soft)):
return {"username": username}
@app.get("/both")
def both(
soft_name: str | None = Depends(recording_soft),
hard_name: str = Depends(auth_module.require_auth),
):
log.append(("handler", soft_name, hard_name))
return {"soft": soft_name, "hard": hard_name}
return app
def test_the_soft_reader_accepts_what_require_auth_rejects(self):
log: list = []
app = self._app(log)
with (
mock.patch.object(
auth_module.db_manager,
"is_user_connected",
_AlwaysConnected.is_user_connected,
),
mock.patch.object(
auth_module, "session_manager", _DeadSessionManager()
),
):
client = TestClient(app)
client.post("/_stub-login")
soft = client.get("/soft")
assert soft.status_code == 200
assert soft.json() == {"username": "alice"}
assert log == [("soft", "alice")]
def test_the_earlier_reader_still_observes_the_session_after_the_401(
self,
):
"""The divergence is order-visible, which is the notes bug's shape
applied to dependencies rather than to the body.
``get_session_username`` is declared first, so it resolves,
records "alice", and only then does ``require_auth`` refuse. Its
observation stands: a dependency placed before the gate has
already run and anything it did is not rolled back by the 401.
Here that is only an append to a list; the point is that the
solver offers no mechanism that would make it anything less.
"""
log: list = []
app = self._app(log)
with (
mock.patch.object(
auth_module.db_manager,
"is_user_connected",
_AlwaysConnected.is_user_connected,
),
mock.patch.object(
auth_module, "session_manager", _DeadSessionManager()
),
):
client = TestClient(app)
client.post("/_stub-login")
both = client.get("/both")
assert both.status_code == 401
# The soft reader resolved "alice"; the handler never ran.
assert log == [("soft", "alice")]
def test_require_auth_really_does_clear_the_cookie_end_to_end(self):
"""``require_auth``'s docstring promises the client is "sent back
to login instead of 401-ing on every request". That promise
depends on ``request.session.clear()`` surviving an
``HTTPException`` raised from *inside the dependency solver* —
i.e. on ``SessionMiddleware`` sitting outside the exception
handling that turns the raise into a response.
Every existing test of this calls the function with a fake request
object, which cannot show that. Asserted here through the real
ASGI stack: the 401 carries an emptied, expired session cookie and
the next request is anonymous.
"""
log: list = []
app = self._app(log)
with (
mock.patch.object(
auth_module.db_manager,
"is_user_connected",
_AlwaysConnected.is_user_connected,
),
mock.patch.object(
auth_module, "session_manager", _DeadSessionManager()
),
):
client = TestClient(app)
client.post("/_stub-login")
assert client.cookies.get("session")
response = client.get("/both")
cleared = [
value.decode()
for key, value in response.headers.raw
if key.lower() == b"set-cookie"
and value.decode().startswith("session=")
]
assert len(cleared) == 1, response.headers.raw
assert "expires=Thu, 01 Jan 1970" in cleared[0]
assert dict(client.cookies) == {}
follow_up = client.get("/soft")
assert follow_up.json() == {"username": None}
# ---------------------------------------------------------------------------
# 5. Error paths: what the client sees when auth itself breaks
# ---------------------------------------------------------------------------
class _ExplodingDbManager:
@staticmethod
def is_user_connected(username): # noqa: ARG004
raise RuntimeError("connection registry unavailable")
class TestErrorPathsInsideTheAuthDependencies:
def test_a_non_http_exception_from_require_auth_is_a_500_not_a_401(self):
"""``require_auth`` calls out to ``db_manager`` and
``session_manager``; neither call is guarded. Anything other than
an ``HTTPException`` escapes as a 500.
That matters for the browser branch specifically: the app converts
a dependency's *401* into a 302 to ``/auth/login``
(``fastapi_app.handle_http_exception``), keyed on
``HTTPException.status_code``. A RuntimeError from inside auth
therefore cannot take that path — the user gets a server error
page instead of a login page, and the failure is indistinguishable
from a backend outage.
"""
app = _session_app()
_add_login_stub(app)
@app.get("/protected")
def protected(username: str = Depends(auth_module.require_auth)):
return {"username": username}
with mock.patch.object(
auth_module.db_manager,
"is_user_connected",
_ExplodingDbManager.is_user_connected,
):
client = TestClient(app, raise_server_exceptions=False)
client.post("/_stub-login")
response = client.get("/protected", headers={"accept": "text/html"})
assert response.status_code == 500
def test_require_auth_500s_without_session_middleware(self):
"""``require_auth`` reads ``request.session`` unguarded.
Starlette raises ``AssertionError`` when ``SessionMiddleware`` is
not installed, so on any mount that lacks it — or from anything
running outside it — the auth dependency produces a 500 rather
than a 401. It fails closed, but it fails as an outage.
"""
app = FastAPI()
@app.get("/protected")
def protected(username: str = Depends(auth_module.require_auth)):
return {"username": username}
client = TestClient(app, raise_server_exceptions=False)
response = client.get("/protected")
assert response.status_code == 500
def test_the_rate_limit_key_funcs_degrade_in_the_same_scope(self):
"""Contrast, and the reason the asymmetry above is worth pinning.
``_user_key`` and ``_api_user_key`` guard the same access with
``"session" in request.scope`` and fall back to the client IP,
because ``SlowAPIMiddleware`` runs outside ``SessionMiddleware``.
``require_auth`` has no such guard. Same module family, same
hazard, two different treatments.
"""
app = FastAPI()
@app.get("/keys")
def keys(request: Request):
return {
"user": rl_module._user_key(request),
"api": rl_module._api_user_key(request),
}
client = TestClient(app)
response = client.get("/keys")
assert response.status_code == 200
assert response.json() == {
"user": "testclient",
"api": "api_ip:testclient",
}