~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""The FastAPI dependency-injection contracts this app now leans on.
The Flask port replaced ``@login_required``, ``before_request`` hooks and
``g`` with ``Depends(...)``. That moved a pile of security-relevant control
flow out of code the repo owns and into FastAPI's dependency solver — and
almost none of the solver's behaviour is pinned anywhere, even though the
migration's guards are written as if it were.
The concrete motivation is the notes body-gate bug. All 24 mutating notes
routes shipped as::
body=Depends(_notes_json_body), # <- ran FIRST
username: str = Depends(require_auth),
so an *anonymous* request was fully read and ``json.loads``-ed — on the
event loop, under ``/notes/``'s 100 MB cap, ~11 s of full-instance freeze —
before ``require_auth`` got to answer 401. The fix was to swap the two
parameters, and ``tests/web/routers/test_notes_body_gate_ordering.py`` pins
that the notes router keeps them in that order. But that guard is only as
good as the assumption underneath it: *signature order decides resolution
order*. Nothing else in the tree pins the assumption itself, nor the other
solver behaviours the migration now depends on.
This module pins them, one contract per section:
1. **Resolution order is signature order** — and siblings are awaited one at
a time, not concurrently. If a FastAPI upgrade parallelised sibling
dependencies, "auth is declared first" would stop being a gate at all and
the notes guard would keep passing while protecting nothing.
(Deliberately *not* a re-run of the notes test's throwaway-app proof: this
covers N-way order, depth-first sub-dependency order, decorator-level
``dependencies=[...]`` precedence, and sequential awaiting.)
2. **Sub-dependency composition** — ``require_auth`` is composed into other
dependencies. The composing dependency must receive the *resolved*
username, and a failed ``require_auth`` must short-circuit it and the
handler both.
3. **``dependency_overrides``** — ~15 test modules replace ``require_auth``
through it, most of them on the process-wide ``fastapi_app.app``
singleton. Pins that the override reaches nested dependencies, that
``.pop()`` genuinely restores the real one, and that an unpopped override
really does poison later requests (hence the repo's ``try/finally``
idiom, which is also swept for here).
4. **Exception propagation** — an ``HTTPException`` from a dependency must
produce that status, must not run later sibling dependencies, and must
not run the handler. "Did not run" is asserted against a real execution
log, with a positive control proving the same handler does run when the
dependency succeeds.
5. **``yield`` dependency lifecycle** — including the thread-affinity hazard
documented on ``web/dependencies/auth.py::get_db_session_dep``. That
dependency is deliberately unwired; the hazard is pinned here directly
against ``fastapi.concurrency.contextmanager_in_threadpool`` instead, so
a FastAPI/anyio version that changed it surfaces here rather than in a
cross-request data-corruption bug.
6. **Per-request caching** — a dependency used twice in one request resolves
once, ``use_cache=False`` opts out, and the cache does not survive the
request. ``require_auth`` appears in many signatures, often both directly
and via a sub-dependency, so "resolves once" is what keeps its
session/DB work from being duplicated per route.
"""
from __future__ import annotations
import re
import threading
from contextlib import contextmanager
from pathlib import Path
from unittest.mock import patch
import anyio
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.concurrency import contextmanager_in_threadpool
from fastapi.testclient import TestClient
from starlette.middleware.sessions import SessionMiddleware
from local_deep_research.web.dependencies import auth as auth_module
from local_deep_research.web.dependencies.auth import require_auth
AUTH_SOURCE = Path(auth_module.__file__).resolve()
# .../src/local_deep_research/web/dependencies/auth.py -> .../local_deep_research
SRC_ROOT = AUTH_SOURCE.parents[2]
# .../tests/web/dependencies/<this file> -> .../tests
TESTS_ROOT = Path(__file__).resolve().parents[2]
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
#
# These suites exercise the real ``require_auth`` but are about DI wiring,
# not about the auth gate's own rules. The autouse ``_legacy_bare_username_auth``
# fixture in tests/conftest.py relaxes ``_server_session_valid``, so a bare
# ``username`` in the signed session plus an open database is enough to
# authenticate here. The gate's real rules are pinned in
# tests/security/test_auth_dependencies_fastapi.py and
# tests/web/dependencies/test_session_revocation.py.
@contextmanager
def _connected_db(*usernames: str):
"""Make ``require_auth``'s database check pass for ``usernames``.
Yields the list of usernames ``is_user_connected`` was asked about.
``require_auth`` calls it exactly once per resolution, which makes it a
resolution counter that — unlike wrapping ``require_auth`` in a spy —
does not change the dependency's identity, and therefore does not change
its cache key.
"""
seen = []
def _is_user_connected(username):
seen.append(username)
return username in usernames
with patch.object(
auth_module.db_manager, "is_user_connected", _is_user_connected
):
yield seen
def _session_app() -> FastAPI:
"""A throwaway app with a real signed session and a public seeder."""
app = FastAPI()
app.add_middleware(SessionMiddleware, secret_key="di-contract-tests")
@app.post("/_seed")
def seed(request: Request, payload: dict):
request.session.update(payload)
return {"ok": True}
return app
def _composed_app():
"""App where ``require_auth`` is both a direct dep and a sub-dependency.
Returns ``(app, ran)``; ``ran`` is the execution log the
short-circuit assertions are made against.
"""
app = _session_app()
ran: list = []
def needs_user(username: str = Depends(require_auth)) -> str:
ran.append(("dep", username))
return username.upper()
@app.get("/gated")
def gated(
username: str = Depends(require_auth),
shouted: str = Depends(needs_user),
):
ran.append(("handler", username, shouted))
return {"username": username, "shouted": shouted}
return app, ran
# ---------------------------------------------------------------------------
# 1. Resolution order is signature order
# ---------------------------------------------------------------------------
class TestResolutionOrderIsSignatureOrder:
"""The premise under the notes body-gate guard, pinned generally.
``test_notes_body_gate_ordering.py`` proves the two-dependency case on a
throwaway app. These widen it: N siblings, nested sub-dependencies,
decorator-level dependencies, and — the one that would silently void the
whole idea — whether siblings are awaited sequentially at all.
"""
def test_siblings_resolve_in_declaration_order(self):
ran = []
def d_first():
ran.append("first")
return 1
async def d_second():
ran.append("second")
return 2
def d_third():
ran.append("third")
return 3
app = FastAPI()
@app.get("/order")
def order(
a=Depends(d_first),
b=Depends(d_second),
c=Depends(d_third),
):
ran.append("handler")
return {"a": a, "b": b, "c": c}
response = TestClient(app).get("/order")
assert response.status_code == 200, response.text
assert response.json() == {"a": 1, "b": 2, "c": 3}
assert ran == ["first", "second", "third", "handler"], (
"FastAPI must solve dependencies in signature order — mixing "
"sync and async siblings must not reorder them. Every "
"ordering-based gate in this app (auth before body parsing on "
f"24 notes routes) rests on this. Got {ran}"
)
def test_a_sub_dependency_resolves_before_its_parent(self):
"""Depth-first: a nested dep is complete before the parent starts.
``get_settings_manager_dep`` and the notes/library routers all
compose dependencies this way; the parent is written assuming its
child's value is already resolved.
"""
ran = []
def child():
ran.append("child")
return "c"
def parent(value: str = Depends(child)):
ran.append("parent")
return value + "p"
app = FastAPI()
@app.get("/nested")
def nested(value: str = Depends(parent)):
ran.append("handler")
return {"value": value}
response = TestClient(app).get("/nested")
assert response.status_code == 200, response.text
assert response.json() == {"value": "cp"}
assert ran == ["child", "parent", "handler"], ran
def test_decorator_dependencies_run_before_signature_dependencies(self):
"""``dependencies=[...]`` outranks everything in the signature.
Worth pinning because it is the escape hatch a future fix would
reach for: moving a gate into ``dependencies=[Depends(require_auth)]``
puts it ahead of *every* signature parameter, body gate included.
"""
ran = []
def decorator_level():
ran.append("decorator")
def signature_level():
ran.append("signature")
return "s"
app = FastAPI()
@app.get("/precedence", dependencies=[Depends(decorator_level)])
def precedence(value: str = Depends(signature_level)):
ran.append("handler")
return {"value": value}
assert TestClient(app).get("/precedence").status_code == 200
assert ran == ["decorator", "signature", "handler"], ran
def test_siblings_are_awaited_one_at_a_time(self):
"""Sequential awaiting is what makes declaration order a *gate*.
If FastAPI ever resolved siblings concurrently (it has been
proposed), the notes ordering guard would keep passing while the
body gate ran alongside ``require_auth`` instead of after it — the
anonymous 100 MB parse would be back with no test failing.
"""
finished = []
in_flight = 0
peak = 0
lock = threading.Lock()
async def slow():
nonlocal in_flight, peak
with lock:
in_flight += 1
peak = max(peak, in_flight)
await anyio.sleep(0.05)
finished.append("slow")
with lock:
in_flight -= 1
async def quick():
nonlocal in_flight, peak
with lock:
in_flight += 1
peak = max(peak, in_flight)
finished.append("quick")
with lock:
in_flight -= 1
app = FastAPI()
@app.get("/sequential")
def sequential(a=Depends(slow), b=Depends(quick)):
finished.append("handler")
return {}
assert TestClient(app).get("/sequential").status_code == 200
assert finished == ["slow", "quick", "handler"], (
"a slow dependency declared first must complete before the next "
f"one starts; concurrent resolution would give quick first. "
f"Got {finished}"
)
assert peak == 1, (
f"at most one dependency may be in flight at a time, saw {peak} "
"— sibling dependencies are being resolved concurrently, which "
"voids every ordering-based gate in this app"
)
# ---------------------------------------------------------------------------
# 2. Sub-dependency composition around require_auth
# ---------------------------------------------------------------------------
class TestRequireAuthComposesIntoOtherDependencies:
def test_a_composing_dependency_receives_the_resolved_username(self):
"""Positive control for every short-circuit test below.
Without this, "the handler did not run" proves nothing — it might
never run.
"""
app, ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db("alice"):
assert (
client.post("/_seed", json={"username": "alice"}).status_code
== 200
)
response = client.get("/gated")
assert response.status_code == 200, response.text
assert response.json() == {"username": "alice", "shouted": "ALICE"}
assert ran == [
("dep", "alice"),
("handler", "alice", "ALICE"),
], (
"the composing dependency must be handed require_auth's resolved "
f"username, and the handler must run. Got {ran}"
)
def test_an_anonymous_caller_short_circuits_before_either_runs(self):
app, ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db("alice"):
response = client.get("/gated")
assert response.status_code == 401, response.text
assert response.json()["detail"] == "Authentication required"
assert ran == [], (
"a failed require_auth must short-circuit BOTH the dependency "
"that composes it and the handler. Anything that ran here ran "
f"for an unauthenticated caller. Got {ran}"
)
def test_a_disconnected_database_also_short_circuits(self):
"""The second 401 branch inside ``require_auth``.
A signed session with a username but no open database must be just
as short-circuiting as no session at all — this is the branch a
stale cookie hits after a restart.
"""
app, ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db(): # nobody is connected
assert (
client.post("/_seed", json={"username": "alice"}).status_code
== 200
)
response = client.get("/gated")
assert response.status_code == 401, response.text
assert response.json()["detail"] == "Database connection required"
assert ran == [], ran
# ---------------------------------------------------------------------------
# 3. dependency_overrides
# ---------------------------------------------------------------------------
class TestDependencyOverrides:
"""~15 test modules swap ``require_auth`` out through this map."""
def test_an_override_replaces_the_real_dependency_everywhere(self):
"""Including where it is nested inside another dependency.
Every override in the tree targets ``require_auth`` itself, never
the wrappers around it, so nested substitution is the property they
are all relying on.
"""
app, ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db():
# Positive control: unoverridden, this really is a 401.
assert client.get("/gated").status_code == 401
app.dependency_overrides[require_auth] = lambda: "bob"
try:
response = client.get("/gated")
finally:
app.dependency_overrides.pop(require_auth, None)
assert response.status_code == 200, response.text
assert response.json() == {"username": "bob", "shouted": "BOB"}
assert ran == [("dep", "bob"), ("handler", "bob", "BOB")], (
"the override must be substituted for require_auth both as a "
f"direct dependency and as a sub-dependency. Got {ran}"
)
def test_popping_the_override_restores_the_real_dependency(self):
"""The half the repo's ``try/finally`` relies on actually working."""
app, _ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db():
app.dependency_overrides[require_auth] = lambda: "bob"
try:
assert client.get("/gated").status_code == 200
finally:
app.dependency_overrides.pop(require_auth, None)
after = client.get("/gated")
assert after.status_code == 401, (
"popping the override must put the real require_auth back; it "
f"answered {after.status_code} for an anonymous caller"
)
assert require_auth not in app.dependency_overrides
def test_an_unpopped_override_stays_live_for_later_requests(self):
"""Why cleanup is mandatory, not tidiness.
Most override sites in this tree patch the process-wide
``fastapi_app.app`` singleton, so a leaked entry does not expire
with the test that set it — it silently authenticates every later
test module that shares the app.
"""
app, _ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
try:
with _connected_db():
app.dependency_overrides[require_auth] = lambda: "bob"
first = client.get("/gated")
# A whole separate client, i.e. a separate "test", over the
# same app object.
second = TestClient(app, raise_server_exceptions=False).get(
"/gated"
)
assert first.status_code == 200, first.text
assert second.status_code == 200, (
"an override left in the map must still be active for a "
"later, unrelated request — this is the leak the repo's "
"try/finally pop exists to prevent, and if it stopped being "
"true the cleanup fixtures would be cargo cult"
)
assert second.json()["username"] == "bob"
finally:
app.dependency_overrides.pop(require_auth, None)
def test_every_shared_app_override_site_cleans_up_after_itself(self):
"""Sweep the repo's own usage of the pattern.
A module that installs an override on the imported
``fastapi_app.app`` singleton and never removes it poisons whatever
runs next in the same worker. Modules that build their own throwaway
``FastAPI()`` are exempt — their app dies with them.
"""
sets_override = re.compile(r"dependency_overrides\s*\[[^\]]+\]\s*=")
removes_override = re.compile(
r"dependency_overrides\s*(?:\.pop\(|\.clear\(|\[[^\]]+\]\s*"
r"=\s*\{\}|\s*=\s*\{\})"
)
shared_app = re.compile(
r"from\s+local_deep_research\.web\.fastapi_app\s+import[^\n]*"
r"\bapp\b|fastapi_app\.app"
)
installers = []
offenders = []
for path in sorted(TESTS_ROOT.rglob("test_*.py")):
source = path.read_text(encoding="utf-8")
if not sets_override.search(source):
continue
installers.append(path)
if not shared_app.search(source):
continue
if not removes_override.search(source):
offenders.append(str(path.relative_to(TESTS_ROOT)))
assert len(installers) >= 10, (
f"premise guard: expected the sweep to find the tree's many "
f"dependency_overrides users, found {len(installers)} — the "
"regex has probably stopped matching"
)
assert not offenders, (
"these test modules install a dependency override on the "
"process-wide fastapi_app.app singleton and never remove it, so "
"the override leaks into every test that runs after them in the "
"same worker:\n " + "\n ".join(offenders)
)
# ---------------------------------------------------------------------------
# 4. Exception propagation out of a dependency
# ---------------------------------------------------------------------------
def _short_circuit_app():
"""Returns ``(app, state, ran)``; flip ``state['raise']`` to arm it."""
state = {"raise": True}
ran: list = []
def gate():
ran.append("gate")
if state["raise"]:
raise HTTPException(status_code=403, detail="denied")
return "open"
def later():
ran.append("later")
return "later"
app = FastAPI()
@app.get("/guarded")
def guarded(a: str = Depends(gate), b: str = Depends(later)):
ran.append("handler")
return {"a": a, "b": b}
return app, state, ran
class TestExceptionPropagationFromDependencies:
def test_the_handler_runs_when_the_gate_lets_it_through(self):
"""Positive control: the route below is genuinely reachable."""
app, state, ran = _short_circuit_app()
state["raise"] = False
response = TestClient(app, raise_server_exceptions=False).get(
"/guarded"
)
assert response.status_code == 200, response.text
assert response.json() == {"a": "open", "b": "later"}
assert ran == ["gate", "later", "handler"], ran
def test_an_http_exception_sets_the_status_and_stops_everything_after(
self,
):
app, _state, ran = _short_circuit_app()
response = TestClient(app, raise_server_exceptions=False).get(
"/guarded"
)
assert response.status_code == 403, response.text
assert response.json()["detail"] == "denied"
assert ran == ["gate"], (
"an HTTPException from a dependency must skip the later sibling "
f"dependency AND the handler. Got {ran}"
)
def test_a_non_http_exception_becomes_500_without_running_the_handler(
self,
):
"""The failure mode that matters is silent continuation, not 500.
A dependency that blew up with a plain exception must not leave the
handler running with a half-built context.
"""
ran = []
def broken():
ran.append("dep")
raise RuntimeError("dependency exploded")
app = FastAPI()
@app.get("/broken")
def broken_route(value=Depends(broken)):
ran.append("handler")
return {"value": value}
response = TestClient(app, raise_server_exceptions=False).get("/broken")
assert response.status_code == 500, response.text
assert ran == ["dep"], (
f"the handler must not run after a dependency raised. Got {ran}"
)
def test_a_failing_sub_dependency_stops_its_parent(self):
"""``require_auth``'s real shape: it is nested, and must still gate.
Covered behaviourally for the real dependency in
``TestRequireAuthComposesIntoOtherDependencies``; pinned here as a
solver contract independent of the auth code.
"""
ran = []
def child():
ran.append("child")
raise HTTPException(status_code=401, detail="nope")
def parent(value=Depends(child)):
ran.append("parent")
return value
app = FastAPI()
@app.get("/nested-boom")
def nested_boom(value=Depends(parent)):
ran.append("handler")
return {"value": value}
response = TestClient(app, raise_server_exceptions=False).get(
"/nested-boom"
)
assert response.status_code == 401, response.text
assert ran == ["child"], (
f"the parent dependency and the handler must both be skipped. "
f"Got {ran}"
)
# ---------------------------------------------------------------------------
# 5. yield-dependency lifecycle, and the documented thread-affinity hazard
# ---------------------------------------------------------------------------
class _ScopeDepth(threading.local):
"""Stand-in for ``database/session_context.py``'s thread-local scope.
``enter_scope()`` / ``exit_scope()`` keep a per-thread ``scope_depth``
exactly like this, and ``ThreadLocalSessionManager.get_session`` skips
its stale-transaction rollback whenever the depth is non-zero.
"""
depth = 0
class _ThreadRecordingScope:
"""A sync context manager that behaves like the scoped DB session.
Increments a thread-local on ``__enter__`` and decrements it on
``__exit__``, recording which thread ran each half.
"""
def __init__(self, scope: _ScopeDepth, log: dict):
self._scope = scope
self._log = log
def __enter__(self):
self._scope.depth += 1
self._log["enter_thread"] = threading.get_ident()
return "session"
def __exit__(self, exc_type, exc, tb):
self._log["exit_thread"] = threading.get_ident()
self._log["depth_seen_by_exit"] = self._scope.depth
self._scope.depth -= 1
return False
class TestYieldDependencyLifecycle:
def test_cleanup_runs_after_the_handler(self):
ran = []
def scoped():
ran.append("enter")
yield "value"
ran.append("exit")
app = FastAPI()
@app.get("/scoped")
def scoped_route(value: str = Depends(scoped)):
ran.append("handler")
return {"value": value}
response = TestClient(app).get("/scoped")
assert response.status_code == 200, response.text
assert response.json() == {"value": "value"}
assert ran == ["enter", "handler", "exit"], ran
def test_a_handler_exception_is_thrown_into_the_generator(self):
"""Cleanup gets to see the failure — a ``try/except`` around the
``yield`` really does fire, which is how ``get_db_session_dep``'s
``DatabaseSessionError`` branch is meant to work."""
ran = []
def scoped():
ran.append("enter")
try:
yield "value"
except HTTPException:
ran.append("saw-http-exception")
raise
finally:
ran.append("finally")
app = FastAPI()
@app.get("/failing")
def failing(value: str = Depends(scoped)):
raise HTTPException(status_code=418, detail="teapot")
response = TestClient(app, raise_server_exceptions=False).get(
"/failing"
)
assert response.status_code == 418, response.text
assert ran == ["enter", "saw-http-exception", "finally"], ran
def test_enter_and_exit_share_a_thread_while_the_pool_is_idle(self):
"""Control for the straddle test below: normally it is fine.
This is why the hazard on ``get_db_session_dep`` never reproduced in
120 concurrent requests — with an idle worker available, anyio hands
``__exit__`` the same thread that ran ``__enter__``. It is a
scheduling accident, not a guarantee, and the next test shows the
accident failing.
"""
scope = _ScopeDepth()
log: dict = {}
async def scenario():
async with contextmanager_in_threadpool(
_ThreadRecordingScope(scope, log)
) as value:
log["value"] = value
anyio.run(scenario)
assert log["value"] == "session"
assert log["enter_thread"] == log["exit_thread"], (
"premise of the control: with an idle pool both halves land on "
f"the same worker. Got {log}"
)
assert log["depth_seen_by_exit"] == 1, (
"__exit__ must see the depth __enter__ set — that is what makes "
f"the balanced case balanced. Got {log}"
)
def test_enter_and_exit_straddle_threads_when_the_worker_is_busy(self):
"""Pin the hazard documented on ``get_db_session_dep``.
``contextmanager_in_threadpool`` dispatches ``__enter__`` and
``__exit__`` as two separate ``anyio.to_thread.run_sync`` calls (the
second with its own ``CapacityLimiter``), and anyio offers no task
affinity — it just pops an idle worker. So if the entering worker is
busy when the context exits, ``__exit__`` runs on a *different*
thread. For a ``threading.local()`` scope counter that means the
exiting thread decrements a counter it never incremented, and the
entering thread's counter is stuck above zero **forever** — which in
``ThreadLocalSessionManager`` permanently disables that worker's
stale-transaction rollback and lets one request's uncommitted ORM
state be committed by the next request served on that thread.
This runs inside a fresh ``anyio.run`` so the worker pool starts
empty, which makes the straddle deterministic rather than lucky:
exactly one worker exists, the test pins it with a blocking call,
and ``__exit__`` has no choice but to spawn another.
``get_db_session_dep`` is NOT wired to a route (see the next test)
precisely because of this. If a future FastAPI/anyio makes the two
halves thread-affine, this test fails — and the docstring's warning,
and the ``run_db_sync`` workaround the routes use, can be revisited.
"""
scope = _ScopeDepth()
log: dict = {}
pinned: dict = {}
release = threading.Event()
def pin_the_entering_worker():
pinned["thread"] = threading.get_ident()
pinned["depth_while_pinned"] = scope.depth
release.wait(30)
pinned["depth_after_exit"] = scope.depth
async def scenario():
async with anyio.create_task_group() as task_group:
async with contextmanager_in_threadpool(
_ThreadRecordingScope(scope, log)
):
# __enter__ has returned, so its worker is back in the
# idle pool and is the only one there. Grab it and hold
# it across the exit.
await anyio.sleep(0.05)
task_group.start_soon(
anyio.to_thread.run_sync, pin_the_entering_worker
)
while "thread" not in pinned:
await anyio.sleep(0.01)
release.set()
anyio.run(scenario)
assert pinned["thread"] == log["enter_thread"], (
"premise: anyio reuses the just-idled worker for the next "
"to_thread call, so the blocking call should have landed on the "
f"entering thread. Got {pinned} / {log}"
)
assert log["exit_thread"] != log["enter_thread"], (
"__exit__ ran on the entering thread even though that thread was "
"blocked — contextmanager_in_threadpool has apparently gained "
"thread affinity. If so, the hazard documented on "
"get_db_session_dep is gone and that docstring should be updated"
)
assert log["depth_seen_by_exit"] == 0, (
"the exiting thread must see its OWN thread-local depth (0), not "
f"the entering thread's 1. Got {log}"
)
assert pinned["depth_while_pinned"] == 1
assert pinned["depth_after_exit"] == 1, (
"the entering worker's thread-local depth is stuck at 1 after "
"the scope exited on another thread — this is the permanent "
"leak get_db_session_dep's docstring warns about"
)
def test_get_db_session_dep_is_still_not_wired_to_any_route(self):
"""The mitigation the hazard above relies on.
``get_db_session_dep`` and its only consumer
``get_settings_manager_dep`` must stay out of every route signature
until scope enter/exit is thread-affine (or the route uses
``run_db_sync``, which keeps the whole unit of work on one worker).
"""
wired = re.compile(
r"Depends\(\s*(?:get_db_session_dep|get_settings_manager_dep)\s*\)"
)
auth_source = AUTH_SOURCE.read_text(encoding="utf-8")
assert "def get_db_session_dep(" in auth_source, (
"premise guard: get_db_session_dep is no longer defined in "
f"{AUTH_SOURCE} — this test is scanning for a symbol that has "
"been renamed or removed"
)
# auth.py is excluded from the sweep below because it holds the ONE
# legitimate composition: get_settings_manager_dep's own signature.
# Pin that it stays the only one, so the exclusion is a single known
# line rather than a blanket amnesty for the module.
assert len(wired.findall(auth_source)) == 1, (
"auth.py's docstring says get_settings_manager_dep is "
"get_db_session_dep's only consumer; the sweep below excludes "
"auth.py on that basis and it is no longer true — found "
f"{len(wired.findall(auth_source))} compositions"
)
assert "def get_settings_manager_dep(" in auth_source
scanned = 0
offenders = []
for path in sorted(SRC_ROOT.rglob("*.py")):
scanned += 1
if path == AUTH_SOURCE:
continue
for number, line in enumerate(
path.read_text(encoding="utf-8").splitlines(), start=1
):
if wired.search(line):
offenders.append(f"{path}:{number}: {line.strip()}")
assert scanned >= 50, (
f"premise guard: only {scanned} source files scanned under "
f"{SRC_ROOT}, the sweep is looking in the wrong place"
)
assert not offenders, (
"get_db_session_dep (or get_settings_manager_dep, which wraps "
"it) has been wired into a route. FastAPI drives sync generator "
"dependencies through contextmanager_in_threadpool, whose "
"__enter__/__exit__ can land on different pooled threads (see "
"the straddle test above) — which permanently corrupts the "
"thread-local session scope. Use run_db_sync instead:\n "
+ "\n ".join(offenders)
)
# ---------------------------------------------------------------------------
# 6. Per-request caching
# ---------------------------------------------------------------------------
class TestPerRequestDependencyCaching:
def test_a_dependency_declared_twice_resolves_once(self):
resolutions = []
def counted():
resolutions.append(1)
return object()
app = FastAPI()
@app.get("/twice")
def twice(a=Depends(counted), b=Depends(counted)):
return {"identical": a is b}
response = TestClient(app).get("/twice")
assert response.status_code == 200, response.text
assert response.json() == {"identical": True}
assert len(resolutions) == 1, (
"FastAPI caches a dependency's result for the duration of one "
f"request; it resolved {len(resolutions)} times"
)
def test_use_cache_false_opts_out(self):
resolutions = []
def counted():
resolutions.append(1)
return object()
app = FastAPI()
@app.get("/nocache")
def nocache(
a=Depends(counted),
b=Depends(counted, use_cache=False),
):
return {"identical": a is b}
response = TestClient(app).get("/nocache")
assert response.status_code == 200, response.text
assert response.json() == {"identical": False}
assert len(resolutions) == 2, (
f"use_cache=False must force a fresh resolution, saw "
f"{len(resolutions)}"
)
def test_the_cache_does_not_survive_the_request(self):
"""Per-request, not per-process.
If it were process-wide, ``require_auth`` would resolve once and
every later request would inherit the first caller's identity.
"""
resolutions = []
def counted():
resolutions.append(1)
return len(resolutions)
app = FastAPI()
@app.get("/per-request")
def per_request(a=Depends(counted), b=Depends(counted)):
return {"value": a}
client = TestClient(app)
first = client.get("/per-request")
second = client.get("/per-request")
assert first.json() == {"value": 1}, first.text
assert second.json() == {"value": 2}, second.text
assert len(resolutions) == 2
def test_require_auth_resolves_once_even_when_also_nested(self):
"""The shape most routes actually have.
``require_auth`` is declared directly on the handler *and* inside a
dependency the handler also takes. Caching is what keeps that to one
session lookup and one ``is_user_connected`` call per request rather
than one per occurrence.
"""
app, ran = _composed_app()
client = TestClient(app, raise_server_exceptions=False)
with _connected_db("alice") as connection_checks:
assert (
client.post("/_seed", json={"username": "alice"}).status_code
== 200
)
connection_checks.clear()
response = client.get("/gated")
assert response.status_code == 200, response.text
assert ran == [("dep", "alice"), ("handler", "alice", "ALICE")]
assert connection_checks == ["alice"], (
"require_auth is declared twice on this request (directly and "
"through needs_user) and must resolve once — each resolution "
"makes exactly one is_user_connected call, so this list is the "
f"resolution count. Got {connection_checks}"
)
def test_require_auth_resolves_twice_without_the_cache(self):
"""Negative control for the test above.
Proves ``connection_checks`` really does count resolutions, rather
than ``require_auth`` happening to call ``is_user_connected`` once
per request for some unrelated reason.
"""
app = _session_app()
@app.get("/uncached")
def uncached(
a: str = Depends(require_auth),
b: str = Depends(require_auth, use_cache=False),
):
return {"a": a, "b": b}
client = TestClient(app, raise_server_exceptions=False)
with _connected_db("alice") as connection_checks:
assert (
client.post("/_seed", json={"username": "alice"}).status_code
== 200
)
connection_checks.clear()
response = client.get("/uncached")
assert response.status_code == 200, response.text
assert response.json() == {"a": "alice", "b": "alice"}
assert connection_checks == ["alice", "alice"], connection_checks