~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
"""Executable invariant: no ``async def`` route handler may perform
blocking work directly on the event loop.
MEASURED PROBLEM (not theoretical): under load, ``GET /api/v1/health``
degraded from 0.8ms to 9.8s at N=80 concurrent requests -- past the
Docker healthcheck's 8s timeout, i.e. the container gets killed as
"unhealthy" while the process is still alive. ``health_check`` itself is
a plain ``def`` (Starlette auto-threadpools it), so it isn't the culprit;
the degradation is a *symptom* of something else stalling the process.
WHY THIS HAPPENS: uvicorn runs ``workers=1`` here, so there is exactly one
event loop thread per process. Starlette runs a sync (``def``) handler in
the AnyIO threadpool automatically -- it may block freely. An ``async
def`` handler runs directly ON the event loop. If its body performs
blocking work (a synchronous DB session open, ``time.sleep``, a
``requests``/``httpx`` sync call, a subprocess wait, a synchronous DNS
resolution, ...) inline, that call occupies the ONE event loop thread for
its full duration -- stalling every other concurrent request AND every
sync handler waiting for the loop to dispatch it to the threadpool. A
slow ``async def`` handler is why an unrelated, already-threadpooled
``/health`` GET goes from sub-millisecond to multi-second: it isn't slow
itself, it just can't get scheduled while the loop is wedged.
THE ESTABLISHED FIX: ``run_db_sync(fn, *args, **kwargs)``
(``web/dependencies/threadpool.py``) wraps ``asyncio.to_thread`` plus
per-task DB/thread-local cleanup. The convention used throughout this
codebase (see ``research.py``'s ``start_research`` and ``settings.py``'s
``api_update_setting``) is: the ``async def`` handler does only the
legitimate awaits (``await request.json()`` / ``await request.form()``
/ ``await file.read()``), then hands ALL blocking work to a nested
``def _impl(): ...`` (or a ``lambda: ...``) via
``return await run_db_sync(_impl, ...)`` -- or, for CPU-bound work that
never opens a DB session, ``await asyncio.to_thread(...)`` directly (see
``research.py``'s ``upload_pdf``).
THE INVARIANT (AST-based, over every ``async def`` decorated with
``@router.<verb>`` in ``web/routers/*.py``): walking the handler's body
-- excluding nested ``def``/``lambda`` bodies, which is exactly the
correct offload pattern above -- must not find a direct call to a known
event-loop-blocking primitive: a DB-session opener
(``get_user_db_session`` / ``get_settings_manager`` / ``get_metrics_session``
/ the deprecated ``get_db_session``), ``time.sleep``, a synchronous HTTP
call (``requests.*`` / ``httpx.Client`` / the module-level sync ``httpx``
functions / this repo's own ``safe_get`` / ``safe_get_with_retries``
wrappers), a ``subprocess.run``/``.call``/``.check_output``/
``.check_call``, a raw blocking DNS resolution
(``socket.getaddrinfo``/``gethostbyname*``), or a known-sync service
helper identified below by reading its implementation.
SURVEY METHOD: every ``async def`` route handler across
``web/routers/*.py`` was read (not just grepped) to establish the real
convention and to hand-verify every hit this scanner produces. That
survey found the pattern above holds almost everywhere. It found ONE
genuine exception, now fixed rather than allowlisted: ``news_flask_api.py``'s
``create_subscription`` and ``update_subscription`` called a synchronous
SSRF hostname-resolution helper directly on the event loop before ever
reaching ``run_db_sync``. That helper (``is_safe_custom_llm_endpoint`` ->
``security/ssrf_validator.py``'s ``validate_url``) calls
``socket.getaddrinfo(hostname, ...)``, which takes no timeout parameter
and so cannot be bounded in place -- an unbounded synchronous DNS
resolution reachable by any authenticated user who POSTs a
``custom_endpoint`` to ``/news/subscribe`` or PUTs one to
``/news/subscriptions/{id}``. That is exactly the class of bug the
health-check regression measures: one slow lookup on a black-holed
hostname stalls the entire single-worker process for every user, for the
OS resolver's full retry budget. Both call sites now await
``_reject_custom_endpoint_async``, which offloads to a worker thread;
this guard pins that they stay off the loop.
Detection is AST-based (mirrors ``test_migration_antipattern_guards.py``
in this directory) so a regex over ``get_user_db_session`` would not
false-positive on this file's own module docstring, on the historical
comments in ``run_db_sync``'s docstring, or on a string literal.
"""
import ast
import functools
import importlib.util
from pathlib import Path
import pytest
import local_deep_research.web.routers as routers_pkg
ROUTERS_DIR = Path(routers_pkg.__file__).resolve().parent
# `Path.glob` is non-recursive, so this is exactly the `web/routers/*.py`
# scope the task specifies -- no subpackages, no sibling `web/*.py` files.
#: web/routers/*.py plus web/fastapi_app.py. The latter was outside this
#: guard's scope while holding 9 async `@app`-decorated handlers (7
#: exception handlers, `favicon`, `serve_static`); only the sibling guard
#: `test_no_blocking_in_async_routes.py` saw them, and its blocklist is
#: narrower -- it has no httpx-sync, socket, or CPU-bound-parser entries.
SCANNED_FILES = sorted(ROUTERS_DIR.glob("*.py")) + [
ROUTERS_DIR.parent / "fastapi_app.py"
]
def _rel(path: Path) -> str:
# parents[3] of .../src/local_deep_research/web/routers is the repo
# root, matching the "src/local_deep_research/..." keys used below.
return str(path.relative_to(ROUTERS_DIR.parents[3]))
def _parse(path: Path) -> ast.Module:
return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
# ===========================================================================
# Decorator / route-handler identification
# ===========================================================================
#: Objects whose `.get`/`.post`/... decorators mark an HTTP entry point.
#: `router` covers every module in web/routers (each binds its APIRouter to
#: that name); `app` covers fastapi_app.py, whose `@app.exception_handler`
#: handlers run on the event loop exactly like routes do when they fire, and
#: whose `@app.get` static/favicon routes are the most-hit paths in the app.
_ROUTE_DECORATOR_OBJECTS = ("router", "app")
def _is_router_decorator(dec: ast.AST) -> bool:
"""True for `@router.get(...)` / `@app.exception_handler(...)` etc."""
target = dec.func if isinstance(dec, ast.Call) else dec
return (
isinstance(target, ast.Attribute)
and isinstance(target.value, ast.Name)
and target.value.id in _ROUTE_DECORATOR_OBJECTS
)
def _depends_target_names(tree: ast.AST) -> set[str]:
"""Names passed to `Depends(...)` anywhere in this module.
An async function wired in as a dependency is an HTTP entry point in
every sense that matters here: FastAPI awaits it ON THE EVENT LOOP,
before the handler runs, on every request to every route that declares
it. It just doesn't carry a decorator saying so.
This is not a hypothetical gap. `notes.py::_notes_json_body` is an
async, undecorated `Depends` target wired into all 24 mutating notes
routes; it read up to 100 MB and called `json.loads` on the loop, and
this guard could not see it because it had no `@router` decorator.
"""
names: set[str] = set()
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
func = node.func
callee = (
func.attr
if isinstance(func, ast.Attribute)
else getattr(func, "id", None)
)
if callee != "Depends":
continue
for arg in node.args:
if isinstance(arg, ast.Name):
names.add(arg.id)
elif isinstance(arg, ast.Attribute):
names.add(arg.attr)
return names
def _is_async_router_handler(node: ast.AST, depends_names=frozenset()) -> bool:
if not isinstance(node, ast.AsyncFunctionDef):
return False
return (
any(_is_router_decorator(d) for d in node.decorator_list)
or node.name in depends_names
)
# ===========================================================================
# Blocking-call classification
# ===========================================================================
def _dotted_call_name(node: ast.Call) -> str | None:
"""Best-effort dotted callee name, e.g. 'requests.get' or
'get_user_db_session'. Returns None when the callee isn't a plain
Name/Attribute chain (e.g. it's itself a Call's result, or a
subscript) -- such dynamic callees aren't in our blocklist by
construction, so there is nothing useful to classify."""
func = node.func
parts: list[str] = []
while isinstance(func, ast.Attribute):
parts.append(func.attr)
func = func.value
if isinstance(func, ast.Name):
parts.append(func.id)
else:
return None
return ".".join(reversed(parts))
# Exact "module.func" matches.
# ---------------------------------------------------------------------------
# CPU-bound pure-Python parsers.
#
# The blocklists above model BLOCKING I/O -- a call that parks the thread
# waiting on the network or the disk. This category is different and was
# missed for exactly that reason: these calls never wait on anything, they
# just compute, in Python, for as long as the input is large.
#
# Found by the pre-merge readiness audit: research.py's POST
# /api/save_raw_config parsed a 16 MB-capped body with `tomllib.loads` on the
# coroutine body. Measured at roughly 100 ms per MB of adversarial-but-valid
# TOML, so ~5.5 s of straight-line CPU at the cap -- and the body-size limit's
# own note budgets "roughly 60 ms", a figure calibrated for C-speed
# json.loads.
#
# That "C-speed json.loads" premise was measured and does not hold. This
# category originally excluded json on the reasoning that it is a C extension
# and therefore fast enough that the body-size cap was the right control. On
# the pinned interpreter, against an adversarial-but-valid document (many
# small objects -- what an attacker sends; NOT one long string -- what a
# benign client sends), json.loads runs at ~110 ms/MB and scales linearly:
#
# 2 MB -> 236 ms 4 MB -> 450 ms 8 MB -> 887 ms 16 MB -> 1730 ms
#
# That is the SAME order as the tomllib figure this category was created for,
# not a C-speed exception to it. So the 16 MB default cap costs ~1.7 s on the
# loop, ~29x the budgeted 60 ms, and the 100 MB cap that /notes/ carries costs
# ~11 s. Memory amplifies ~8.2x on top, so 100 MB of body is ~820 MB resident.
#
# This is not hypothetical: all 24 mutating notes routes parsed their body on
# the event loop -- and, until it was fixed, did so BEFORE require_auth ran,
# so an anonymous caller could buy an ~11 s whole-instance freeze per request.
# orjson is genuinely faster and stays off this list.
#
# The fix is the same as for I/O: offload with asyncio.to_thread (the GIL is
# released periodically, so the loop interleaves instead of stopping dead).
# ---------------------------------------------------------------------------
_CPU_BOUND_PARSERS: dict[str, str] = {
"tomllib.loads": (
"tomllib is pure Python -- parse time scales with the request body "
"(~100 ms/MB measured), so a large body computes on the event loop "
"for seconds. Offload with asyncio.to_thread."
),
"tomli.loads": (
"tomli is the pure-Python backport of tomllib and has the same "
"cost profile. Offload with asyncio.to_thread."
),
"yaml.safe_load": (
"PyYAML's pure-Python loader is used unless libyaml is present, and "
"its cost scales with the input. Offload with asyncio.to_thread."
),
"json.loads": (
"json.loads is C-implemented but still scales with the body: "
"~110 ms/MB measured on adversarial-but-valid input, the same order "
"as tomllib. At the 16 MB default cap that is ~1.7 s on the event "
"loop; at the 100 MB /notes/ cap, ~11 s. Offload with "
"asyncio.to_thread above a size where the cost is measurable."
),
"json.load": (
"same cost profile as json.loads, and it reads from a file object "
"on top. Offload with asyncio.to_thread."
),
"yaml.load": (
"same cost profile as yaml.safe_load, and unsafe by default. "
"Offload with asyncio.to_thread."
),
}
# This repo's own wrappers around a parser above. A wrapper hides the parse
# from the direct scan, and the cross-module scan further down sees it only
# while the parse stays in the wrapper's own frame, so the wrapper is named
# here as well. Matched like _BARE_NAME_BLOCKLIST, on the last dotted
# component: `loads_toml_within_limits(...)`,
# `toml_limits.loads_toml_within_limits(...)` and a call through any alias
# of the module all resolve.
_CPU_BOUND_HELPERS: dict[str, str] = {
"loads_toml_within_limits": (
"security/toml_limits.py's loads_toml_within_limits() scans the text "
"for over-long dotted keys and then runs tomllib.loads() on it. Its "
"512 KiB cap bounds the cost but does not remove it: a document of "
"32-part table headers at the cap measured ~0.8 s per call. Offload "
"with asyncio.to_thread, as research.py's save_raw_config does."
),
}
_EXACT_DOTTED_BLOCKLIST: dict[str, str] = {
"time.sleep": (
"blocks the OS thread for its full duration; with uvicorn's "
"workers=1 that IS the event loop thread, so every other "
"concurrent request (including the Docker healthcheck's GET "
"/api/v1/health) stalls until the sleep returns."
),
"subprocess.run": (
"blocks the calling thread until the child process exits -- on "
"the event loop thread that stalls every concurrent request for "
"the process's full runtime."
),
"subprocess.call": "blocks like subprocess.run() -- same event-loop stall.",
"subprocess.check_call": "blocks like subprocess.run() -- same event-loop stall.",
"subprocess.check_output": "blocks like subprocess.run() -- same event-loop stall.",
"socket.getaddrinfo": (
"performs a synchronous DNS resolution with no timeout -- a slow "
"or unresponsive resolver blocks the event loop for the OS "
"resolver's full retry budget (can be many seconds), stalling "
"every concurrent request in this workers=1 process."
),
"socket.gethostbyname": (
"a synchronous, unbounded DNS lookup -- same event-loop stall as "
"socket.getaddrinfo()."
),
"socket.gethostbyname_ex": (
"a synchronous, unbounded DNS lookup -- same event-loop stall as "
"socket.getaddrinfo()."
),
}
# Module-level httpx functions and httpx.Client(...) are synchronous by
# design (unlike httpx.AsyncClient); any of these called directly is a
# same-class stall as `requests.*`.
_HTTPX_SYNC_CALLS = {
"httpx.Client",
"httpx.get",
"httpx.post",
"httpx.put",
"httpx.delete",
"httpx.patch",
"httpx.head",
"httpx.request",
}
# Bare-name matches (last dotted component), so both `get_user_db_session(...)`
# (the common direct-import call site) and a hypothetical
# `module.get_user_db_session(...)` are caught.
_BARE_NAME_BLOCKLIST: dict[str, str] = {
"get_user_db_session": (
"opens a synchronous SQLCipher/SQLAlchemy session (PBKDF2 key "
"derivation + disk I/O) directly on the event loop."
),
"get_settings_manager": (
"constructs a SettingsManager, which opens a synchronous DB "
"session under the hood, directly on the event loop."
),
"get_metrics_session": (
"opens a synchronous metrics DB session directly on the event "
"loop (database/thread_local_session.py)."
),
"get_db_session": (
"deprecated synchronous DB session opener (see "
"utilities/db_utils.py's own deprecation comment) -- same "
"event-loop stall as get_user_db_session."
),
# Verified by reading utilities/url_utils.py: is_safe_custom_llm_endpoint
# calls validate_url(candidate, allow_private_ips=True).
"is_safe_custom_llm_endpoint": (
"utilities/url_utils.py's is_safe_custom_llm_endpoint() calls "
"validate_url(), which calls socket.getaddrinfo() with no "
"timeout set anywhere in ssrf_validator.py -- a genuine, "
"unbounded, synchronous DNS resolution on the event loop."
),
# Verified by reading security/ssrf_validator.py lines ~290-300: the
# hostname-resolution branch calls
# `socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)`
# with no `settimeout`/timeout argument anywhere in the module.
"validate_url": (
"security/ssrf_validator.py's validate_url() calls "
"socket.getaddrinfo() with no timeout -- a genuine, unbounded, "
"synchronous DNS resolution on the event loop."
),
"safe_get": (
"security/safe_requests.py's safe_get() is a synchronous "
"requests.get() wrapper -- blocks the event loop for the full "
"connect/read timeout."
),
"safe_get_with_retries": (
"security/safe_requests.py's safe_get_with_retries() is a "
"synchronous requests wrapper with retries/backoff -- blocks the "
"event loop for multiple round trips."
),
# Verified by reading web/routers/news_flask_api.py's
# `_reject_custom_endpoint`: its entire body is
# `if is_safe_custom_llm_endpoint(custom_endpoint): return None` plus
# an error-response branch -- a thin pass-through with no offload of
# its own, so calling it inherits is_safe_custom_llm_endpoint's
# blocking DNS resolution verbatim.
"_reject_custom_endpoint": (
"web/routers/news_flask_api.py's _reject_custom_endpoint() is a "
"thin synchronous wrapper around is_safe_custom_llm_endpoint() -> "
"validate_url() -> socket.getaddrinfo() (verified by reading its "
"source) -- calling it directly performs an unbounded, "
"synchronous DNS resolution on the event loop."
),
}
def _classify_blocking_call(dotted: str) -> str | None:
"""Return a human-readable reason if `dotted` is a known
event-loop-blocking call, else None."""
if dotted in _EXACT_DOTTED_BLOCKLIST:
return _EXACT_DOTTED_BLOCKLIST[dotted]
if dotted in _CPU_BOUND_PARSERS:
return _CPU_BOUND_PARSERS[dotted]
if dotted == "requests" or dotted.startswith("requests."):
return (
"the `requests` library is fully synchronous -- any "
"requests.* call blocks the event loop for the full "
"connect/read timeout."
)
if dotted in _HTTPX_SYNC_CALLS:
return (
"httpx.Client(...) / the module-level httpx sync functions "
"block the event loop for the full connect/read timeout -- "
"use httpx.AsyncClient with `await`, or offload to a thread."
)
last = dotted.rsplit(".", 1)[-1]
if last in _BARE_NAME_BLOCKLIST:
return _BARE_NAME_BLOCKLIST[last]
if last in _CPU_BOUND_HELPERS:
return _CPU_BOUND_HELPERS[last]
return None
# ===========================================================================
# Body walk: excludes nested def/lambda scopes (the correct offload pattern)
# ===========================================================================
def _collect_blocking_calls(node: ast.AST, out: list) -> None:
"""Recursively walk `node`'s children, recording (lineno, dotted_name,
reason) for every blocking call -- WITHOUT descending into a nested
FunctionDef/AsyncFunctionDef/Lambda.
That exclusion is the entire point: `def _impl(): ...` handed to
`run_db_sync`/`asyncio.to_thread`, or an equivalent `lambda: ...`, is
exactly the correct pattern (it runs on a worker thread, not the event
loop) and must NOT be flagged. Only calls that execute directly in the
handler's own frame -- i.e. ON the event loop -- are violations.
"""
for child in ast.iter_child_nodes(node):
if isinstance(
child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
):
continue
if isinstance(child, ast.Call):
dotted = _dotted_call_name(child)
if dotted is not None:
reason = _classify_blocking_call(dotted)
if reason is not None:
out.append((child.lineno, dotted, reason))
_collect_blocking_calls(child, out)
def find_blocking_calls_in_async_route_handlers(tree: ast.AST):
"""Return (lineno, handler_name, dotted_call_name, reason) for every
event-loop-blocking call found directly in the body of an `async def`
route handler -- `@router.<verb>`/`@app.<verb>`-decorated, or wired in
as a `Depends(...)` target, which FastAPI awaits on the event loop just
the same."""
violations = []
depends_names = _depends_target_names(tree)
for node in ast.walk(tree):
if not _is_async_router_handler(node, depends_names):
continue
# Recurse starting from the handler node itself (not its body
# statements individually) so the nested-def/lambda skip check in
# `_collect_blocking_calls` -- which only inspects *children* of
# whatever node it's given -- gets the chance to see and skip a
# top-level `def _impl(): ...` / `lambda: ...` statement. Handing
# it a body statement directly would start the recursion one
# level too deep, past the check, for exactly that top-level
# nested-def case.
hits: list = []
_collect_blocking_calls(node, hits)
for lineno, dotted, reason in hits:
violations.append((lineno, node.name, dotted, reason))
return violations
# ===========================================================================
# Real-tree scan
# ===========================================================================
# "path::L<lineno>" -> justification. Seeded ONLY with hand-verified-safe
# cases (each entry requires reading the callee's full implementation, not
# just its name). Currently EMPTY: the survey behind this file found every
# other match already goes through the nested-def/lambda + run_db_sync (or
# asyncio.to_thread) pattern and so is never even reported by the scanner
# above -- there was nothing left over that needed allowlisting.
#
# This scanner originally reported two real hits
# (news_flask_api.py::create_subscription and ::update_subscription,
# calling `_reject_custom_endpoint` directly on the event loop). They were
# genuine event-loop stalls, not false positives, and were FIXED rather
# than allowlisted -- both now await `_reject_custom_endpoint_async`,
# which hands the blocking resolver call to a worker thread. Silencing a
# real bug with an allowlist entry would defeat the purpose of this guard.
BLOCKING_CALL_ALLOWLIST: dict[str, str] = {}
def test_no_unallowlisted_event_loop_blocking_in_async_route_handlers():
"""No `async def` `@router`-decorated handler may call a known
event-loop-blocking primitive directly; blocking work belongs behind
`run_db_sync` (or `asyncio.to_thread` for DB-free CPU work).
REGRESSION THIS PINS (found by this scanner, since fixed):
`news_flask_api.py`'s `create_subscription` and `update_subscription`
each called `_reject_custom_endpoint(...)` directly on the event loop,
before the `run_db_sync(...)` offload later in the same try block.
That chains `is_safe_custom_llm_endpoint` -> `validate_url` ->
`socket.getaddrinfo()`, which takes no timeout parameter and so cannot
be bounded in place. Any authenticated user supplying a
`custom_endpoint` whose hostname resolved slowly (or never) stalled the
ENTIRE single-worker process -- the same failure class as the measured
0.8ms -> 9.8s health-check regression. Both now await
`_reject_custom_endpoint_async`, which offloads to a worker thread.
"""
violations = []
for path in SCANNED_FILES:
tree = _parse(path)
for (
lineno,
func_name,
dotted,
reason,
) in find_blocking_calls_in_async_route_handlers(tree):
key = f"{_rel(path)}::L{lineno}"
if key in BLOCKING_CALL_ALLOWLIST:
continue
violations.append(
f" {_rel(path)}:{lineno}: {func_name}() calls "
f"`{dotted}(...)` directly on the event loop -- {reason} "
"FIX: move this call into a nested `def _impl(...): ...` "
"(or `lambda: ...`) and dispatch it via "
"`return await run_db_sync(_impl, ...)` -- see "
"research.py's start_research or settings.py's "
"api_update_setting for the established pattern."
)
assert not violations, (
"Event-loop-blocking call(s) found directly in an `async def` "
"route handler's body (uvicorn runs workers=1, so this IS the "
"single thread serving every concurrent request -- see this "
"file's module docstring for the measured 0.8ms -> 9.8s health-"
"check regression this class of bug causes). If a hit below is a "
"verified false positive (read the callee's actual "
"implementation, not just its name), add "
'`"<relpath>::L<lineno>": "<justification>"` to '
"BLOCKING_CALL_ALLOWLIST in this file. If it is a real stall, do "
"NOT allowlist it -- fix the handler.\n" + "\n".join(violations)
)
def test_scan_covers_the_known_router_modules():
"""If the router layout moves, SCANNED_FILES silently shrinking to
near-nothing would make the scan above pass vacuously. Pin a floor and
spot-check the modules with async handlers exercised by this file's
survey (research.py, settings.py, news_flask_api.py)."""
names = {p.name for p in SCANNED_FILES}
assert len(SCANNED_FILES) >= 15, (
f"Only {len(SCANNED_FILES)} files scanned ({sorted(names)}) -- "
"the web/routers layout moved; update this test's scope."
)
for expected in ("research.py", "settings.py", "news_flask_api.py"):
assert expected in names, (
f"{expected} is no longer in the scanned scope -- it has "
"async route handlers this file's survey depends on. Update "
"SCANNED_FILES / ROUTERS_DIR."
)
# ===========================================================================
# Scanner self-tests: prove the detector actually fires on a violation and
# stays quiet on the compliant shape. A guard that silently stops
# detecting is worse than no guard.
# ===========================================================================
class TestBlockingCallScannerSelfTest:
def test_flags_db_session_opened_directly_on_event_loop(self):
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request, username):\n"
" data = await request.json()\n"
" with get_user_db_session(username) as db_session:\n"
" db_session.query(Thing).all()\n"
" return {'ok': True}\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert len(violations) == 1
lineno, func_name, dotted, _reason = violations[0]
assert (lineno, func_name, dotted) == (4, "h", "get_user_db_session")
def test_ignores_db_session_opened_inside_nested_def_run_db_sync(self):
"""The established compliant pattern: a nested `def _impl()`
handed to `run_db_sync` must NOT be flagged."""
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request, username):\n"
" data = await request.json()\n"
"\n"
" def _impl():\n"
" with get_user_db_session(username) as db_session:\n"
" return db_session.query(Thing).all()\n"
"\n"
" return await run_db_sync(_impl)\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_ignores_db_session_opened_inside_lambda_run_db_sync(self):
"""Equally compliant: a `lambda:` closure handed to `run_db_sync`
(used throughout library_delete.py / metrics.py) must NOT be
flagged either."""
tree = ast.parse(
"@router.delete('/x')\n"
"async def h(request, username):\n"
" return await run_db_sync(\n"
" lambda: get_user_db_session(username).__enter__()\n"
" )\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_flags_time_sleep(self):
tree = ast.parse(
"@router.get('/x')\n"
"async def h(request):\n"
" time.sleep(2)\n"
" return {'ok': True}\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [(3, "time.sleep")]
def test_flags_subprocess_run(self):
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request):\n"
" subprocess.run(['ls'])\n"
" return {'ok': True}\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [(3, "subprocess.run")]
def test_flags_requests_get(self):
tree = ast.parse(
"@router.get('/x')\n"
"async def h(request):\n"
" resp = requests.get('http://example.com')\n"
" return resp.json()\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [(3, "requests.get")]
def test_flags_httpx_client(self):
tree = ast.parse(
"@router.get('/x')\n"
"async def h(request):\n"
" with httpx.Client() as client:\n"
" return client.get('http://example.com').json()\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [(3, "httpx.Client")]
def test_flags_known_sync_ssrf_helper(self):
"""The genuine finding's shape: a known-sync service helper
(identified by reading its implementation, not just its name)
called directly on the event loop."""
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request):\n"
" data = await request.json()\n"
" bad = _reject_custom_endpoint(data.get('custom_endpoint'))\n"
" if bad is not None:\n"
" return bad\n"
" return await run_db_sync(api.create_subscription)\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [
(4, "_reject_custom_endpoint")
]
def test_ignores_sync_def_handler_even_with_direct_blocking_call(self):
"""A plain `def` (not `async def`) handler runs in Starlette's
AnyIO threadpool automatically -- it may block freely and is not
this invariant's concern, no matter what it calls."""
tree = ast.parse(
"@router.get('/x')\n"
"def h(request, username):\n"
" with get_user_db_session(username) as db_session:\n"
" time.sleep(1)\n"
" return db_session.query(Thing).all()\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_ignores_async_function_without_router_decorator(self):
"""A shared body-parsing helper like `_json_object_body` (async,
undecorated) is not itself an HTTP entry point -- only
`@router`-decorated handlers are in scope."""
tree = ast.parse(
"async def _json_object_body(request):\n"
" time.sleep(1)\n"
" return await request.json()\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_flags_blocking_call_nested_deep_in_expression(self):
"""Proves the walk isn't shallow: a blocking call inside an `if`
body (not a top-level statement) must still be caught."""
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request):\n"
" data = await request.json()\n"
" if data.get('slow'):\n"
" time.sleep(5)\n"
" return {'ok': True}\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
assert [(v[0], v[2]) for v in violations] == [(5, "time.sleep")]
def test_flags_every_distinct_violation_not_just_the_first(self):
"""A guard that silently stops after the first hit is worse than
no guard -- prove multiple simultaneous violations are ALL
reported."""
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request, username):\n"
" with get_user_db_session(username) as s:\n"
" pass\n"
" time.sleep(1)\n"
" requests.get('http://example.com')\n"
" subprocess.run(['ls'])\n"
" return {'ok': True}\n"
)
violations = find_blocking_calls_in_async_route_handlers(tree)
dotted_names = sorted(v[2] for v in violations)
assert dotted_names == [
"get_user_db_session",
"requests.get",
"subprocess.run",
"time.sleep",
]
def test_ignores_asyncio_to_thread_offload(self):
"""The other sanctioned escape hatch (DB-free CPU work) --
`await asyncio.to_thread(...)` -- must not itself be flagged, and
a blocking call as its argument (the function being dispatched,
not called inline) is fine too."""
tree = ast.parse(
"@router.post('/x')\n"
"async def h(request):\n"
" def _extract():\n"
" time.sleep(1)\n"
" return 42\n"
" return await asyncio.to_thread(_extract)\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
# ===========================================================================
# One level of indirection: handler -> same-file sync helper -> blocking call
# ===========================================================================
def _same_file_helper_calls_in_own_frame(node, helpers, out):
"""Record calls to module-level sync helpers made in `node`'s OWN frame.
Uses the same non-descending rule as ``_collect_blocking_calls``, and for
the same reason: a helper invoked inside a nested ``def _impl(): ...``
handed to ``run_db_sync``/``asyncio.to_thread`` runs on a worker thread and
is correct, not a violation.
That distinction is the whole test. A first draft of this scan used
``ast.walk`` and reported 8 violations in chat.py — every one of them a
helper called from inside an offloaded nested def, i.e. exactly the pattern
that is supposed to be there. Descending would make this check report the
correct code as broken.
"""
for child in ast.iter_child_nodes(node):
if isinstance(
child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
):
continue
if isinstance(child, ast.Call):
dotted = _dotted_call_name(child)
if dotted in helpers:
out.append((child.lineno, dotted))
_same_file_helper_calls_in_own_frame(child, helpers, out)
def _indirect_blocking_hits(tree, rel_path):
"""(handler, helper, blocking call) for one level of indirection."""
helpers = {n.name: n for n in tree.body if isinstance(n, ast.FunctionDef)}
hits = []
for node in ast.walk(tree):
if not _is_async_router_handler(node):
continue
called = []
_same_file_helper_calls_in_own_frame(node, helpers, called)
for lineno, helper_name in called:
inner = []
_collect_blocking_calls(helpers[helper_name], inner)
for inner_line, dotted, reason in inner:
hits.append(
f" {rel_path}:{lineno}: {node.name}() calls "
f"{helper_name}() in its own frame, and {helper_name}() "
f"calls `{dotted}` at line {inner_line} -- {reason}"
)
return hits
def test_no_blocking_reachable_one_helper_deep_from_an_async_handler():
"""Close the gap the direct scan leaves: a handler that blocks by proxy.
The scan above only sees calls written literally in the handler. A handler
that calls a module-level sync helper which blocks is just as stalled, and
the only defence against that was ``_BARE_NAME_BLOCKLIST`` -- a
hand-maintained list, which by construction only covers what someone
already found. The pre-merge readiness audit flagged this as its top
UNVERIFIABLE item.
Resolved statically for same-file helpers: currently zero. A sync helper
imported from another module of this package is followed one level by
``test_no_blocking_reachable_one_helper_deep_in_another_module`` below.
The residual gap is blocking that no list names and that is reached more
than one call deep, through an async helper or a method, or through a
callee bound other than by an import -- ``PYTHONASYNCIODEBUG=1`` with a
low ``slow_callback_duration``, driven by the Puppeteer suite, is the
experiment that would cover those.
"""
findings = []
for path in SCANNED_FILES:
findings.extend(_indirect_blocking_hits(_parse(path), _rel(path)))
assert not findings, (
"An `async def` route handler reaches an event-loop-blocking call "
"through a same-file sync helper:\n"
+ "\n".join(findings)
+ "\n\nFIX: offload the HELPER call (wrap it in a nested def and "
"dispatch via run_db_sync/asyncio.to_thread), or make the helper "
"async. Calling it directly puts its blocking work on the event "
"loop just as surely as inlining it would."
)
def test_the_indirect_scan_would_actually_catch_something():
"""Anti-vacuity: the test above asserts an empty list, which is also what
a scanner that resolves nothing produces. Build a handler that blocks by
proxy and confirm the scan reports it."""
tree = ast.parse(
"import time\n"
"from fastapi import APIRouter\n"
"router = APIRouter()\n"
"def _helper():\n"
" time.sleep(5)\n"
"@router.get('/x')\n"
"async def handler():\n"
" _helper()\n"
)
hits = _indirect_blocking_hits(tree, "synthetic.py")
assert len(hits) == 1, f"expected exactly one hit, got {hits}"
assert "_helper()" in hits[0] and "time.sleep" in hits[0]
def test_the_indirect_scan_does_not_flag_a_correctly_offloaded_helper():
"""The other half: the offload pattern must NOT be reported, or the test
would fail on correct code and get deleted."""
tree = ast.parse(
"import time, asyncio\n"
"from fastapi import APIRouter\n"
"router = APIRouter()\n"
"def _helper():\n"
" time.sleep(5)\n"
"@router.get('/x')\n"
"async def handler():\n"
" def _impl():\n"
" _helper()\n"
" await asyncio.to_thread(_impl)\n"
)
assert _indirect_blocking_hits(tree, "synthetic.py") == []
# ===========================================================================
# One level of indirection across modules: handler -> sync helper imported
# from another module of this package -> blocking call
# ===========================================================================
#: The directory that holds the package; dotted module names resolve to
#: files under it.
SRC_ROOT = ROUTERS_DIR.parents[2]
_PACKAGE = "local_deep_research"
#: The package that relative imports in a synthetic web/routers module
#: resolve against.
ROUTERS_PACKAGE = routers_pkg.__name__
def _in_package(module: str) -> bool:
return module == _PACKAGE or module.startswith(_PACKAGE + ".")
def _module_file(module: str) -> Path | None:
"""The source file of the dotted *module* under SRC_ROOT, if any."""
base = SRC_ROOT.joinpath(*module.split("."))
for candidate in (base.with_suffix(".py"), base / "__init__.py"):
if candidate.is_file():
return candidate
return None
def _package_of(path: Path) -> str:
"""The package that relative imports in the file at *path* resolve
against."""
parts = path.resolve().relative_to(SRC_ROOT).with_suffix("").parts
return ".".join(parts[:-1])
def _own_frame(node: ast.AST):
"""Yield every node in *node*'s own frame: like
``_collect_blocking_calls``, never descend into a nested def or lambda."""
for child in ast.iter_child_nodes(node):
if isinstance(
child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
):
continue
yield child
yield from _own_frame(child)
def _import_bindings(node: ast.AST, package: str, out: dict) -> None:
"""Record what each name imported in *node*'s own frame refers to.
``out[name]`` becomes ``(module, None)`` for a module of this package,
``(module, attr)`` for ``attr`` imported from one, and ``None`` for a
name imported from outside the package, so that importing a name again
replaces what it was bound to before.
"""
for child in _own_frame(node):
if isinstance(child, ast.ImportFrom):
source = (
importlib.util.resolve_name(
"." * child.level + (child.module or ""), package
)
if child.level
else child.module
)
for alias in child.names:
bound = alias.asname or alias.name
submodule = f"{source}.{alias.name}"
if not _in_package(source):
out[bound] = None
elif _module_file(submodule) is not None:
out[bound] = (submodule, None)
else:
out[bound] = (source, alias.name)
elif isinstance(child, ast.Import):
for alias in child.names:
bound = alias.asname or alias.name.partition(".")[0]
module = alias.name if alias.asname else bound
out[bound] = (module, None) if _in_package(module) else None
@functools.cache
def _parsed_module(path: Path) -> ast.Module:
return _parse(path)
def _module_level_def(module: str, name: str, reexport_hops: int = 1):
"""``(module, node)`` for the top-level sync ``def name`` in *module*.
Follows up to *reexport_hops* re-exports, such as security/__init__.py's
``from .safe_requests import safe_get, safe_post, SafeSession``.
"""
path = _module_file(module)
if path is None:
return None
tree = _parsed_module(path)
for node in tree.body:
if isinstance(node, ast.FunctionDef) and node.name == name:
return module, node
if reexport_hops:
bindings: dict = {}
_import_bindings(tree, _package_of(path), bindings)
target = bindings.get(name)
if target is not None and target[1] is not None:
return _module_level_def(*target, reexport_hops - 1)
return None
def _resolve_imported_function(dotted: str, bindings: dict):
"""``(module, node)`` for a call to a sync function that an import binds
to a module of this package, else None."""
head, *rest = dotted.split(".")
binding = bindings.get(head)
if binding is None:
return None
module, attr = binding
if attr is not None:
# `from pkg.mod import f`: only a bare `f(...)` calls f itself.
return None if rest else _module_level_def(module, attr)
if not rest:
return None
*submodules, name = rest
return _module_level_def(".".join([module, *submodules]), name)
def _cross_module_blocking_hits(tree, rel_path, package):
"""(handler, imported helper, blocking call) for one level of
indirection into another module of this package."""
module_bindings: dict = {}
_import_bindings(tree, package, module_bindings)
depends_names = _depends_target_names(tree)
hits = []
for node in ast.walk(tree):
if not _is_async_router_handler(node, depends_names):
continue
bindings = dict(module_bindings)
_import_bindings(node, package, bindings)
for child in _own_frame(node):
if not isinstance(child, ast.Call):
continue
dotted = _dotted_call_name(child)
target = dotted and _resolve_imported_function(dotted, bindings)
if not target:
continue
helper_module, helper = target
inner: list = []
_collect_blocking_calls(helper, inner)
for inner_line, inner_dotted, reason in inner:
hits.append(
f" {rel_path}:{child.lineno}: {node.name}() calls "
f"{dotted}() in its own frame, and "
f"{helper_module}.{helper.name}() calls "
f"`{inner_dotted}` at line {inner_line} -- {reason}"
)
return hits
def test_no_blocking_reachable_one_helper_deep_in_another_module():
"""The check above, for a sync helper imported from another module.
save_raw_config is why the same-file scan is not enough on its own: its
TOML parse sits behind ``toml_limits.loads_toml_within_limits`` in
security/toml_limits.py, a module that scan never reads, so inlining the
handler's ``asyncio.to_thread`` offload went unreported.
_CPU_BOUND_HELPERS now names that helper for the direct scan; this scan
is for the next wrapper nobody has listed.
Followed: a call, in the own frame of an async route handler or async
``Depends`` target, whose callee an import (at module level or in that
frame) binds to a top-level sync ``def`` in another module of this
package -- ``f(...)`` after ``from pkg.mod import f``, or ``mod.f(...)``
after an import of ``mod`` -- found directly or through one re-export,
such as a package ``__init__``'s.
Not followed: ``async def`` helpers, which the same-file scan skips too
(an async helper can make its own offload decision, as notes.py's
``_parse_json_off_loop`` does when it parses a body under a size
threshold inline); methods; names bound other than by an import; and
anything more than one call deep.
"""
findings = []
for path in SCANNED_FILES:
findings.extend(
_cross_module_blocking_hits(
_parse(path), _rel(path), _package_of(path)
)
)
assert not findings, (
"An `async def` route handler reaches an event-loop-blocking call "
"through a sync helper imported from another module:\n"
+ "\n".join(findings)
+ "\n\nFIX: offload the helper call -- hand the helper to "
"asyncio.to_thread or run_db_sync, as save_raw_config does with "
"toml_limits.loads_toml_within_limits."
)
class _InlineToThread(ast.NodeTransformer):
"""Rewrite ``await asyncio.to_thread(f, *args)`` as ``f(*args)``: the
de-offload these scans exist to catch. ``inlined`` lists each ``f``, in
source order."""
def __init__(self):
self.inlined: list[str] = []
def visit_Await(self, node):
self.generic_visit(node)
call = node.value
if (
isinstance(call, ast.Call)
and _dotted_call_name(call) == "asyncio.to_thread"
and call.args
):
self.inlined.append(ast.unparse(call.args[0]))
inlined = ast.Call(
func=call.args[0], args=call.args[1:], keywords=call.keywords
)
return ast.copy_location(inlined, node)
return node
def test_save_raw_config_with_its_toml_parse_inlined_is_reported():
"""Mutation check on the real handler.
research.py's save_raw_config offloads two calls with
``asyncio.to_thread``: ``toml_limits.loads_toml_within_limits``, then
``_find_blocked_keys`` on the parsed configuration. With both made
directly instead, the direct scan must report the parse (via
_CPU_BOUND_HELPERS) and the cross-module scan must report the
tomllib.loads inside it. As written, the handler is clean for both.
Neither scan reports the inlined walk, which calls nothing on any list
in this file. Its offload is checked by running the handler, in
tests/security/test_save_raw_config_blocked_keys_fastapi.py.
"""
path = ROUTERS_DIR / "research.py"
tree = _parse(path)
package = _package_of(path)
def direct():
return [
(v[0], v[2])
for v in find_blocking_calls_in_async_route_handlers(tree)
if v[1] == "save_raw_config"
]
def cross():
return [
hit
for hit in _cross_module_blocking_hits(tree, _rel(path), package)
if " save_raw_config() " in hit
]
assert direct() == []
assert cross() == []
[handler] = [
node
for node in ast.walk(tree)
if isinstance(node, ast.AsyncFunctionDef)
and node.name == "save_raw_config"
]
inliner = _InlineToThread()
inliner.visit(handler)
assert inliner.inlined == [
"toml_limits.loads_toml_within_limits",
"_find_blocked_keys",
], (
f"save_raw_config offloads {inliner.inlined} with asyncio.to_thread "
"-- update this test to the handler's new shape."
)
reported = direct()
assert [dotted for _line, dotted in reported] == [
"toml_limits.loads_toml_within_limits"
], reported
inner = cross()
assert len(inner) == 1, inner
assert f"{path.name}:{reported[0][0]}:" in inner[0], inner
assert (
"local_deep_research.security.toml_limits.loads_toml_within_limits() "
"calls `tomllib.loads`" in inner[0]
), inner
_TOML_PARSE_SPELLINGS = {
"function-imported": (
"from local_deep_research.security.toml_limits import "
"loads_toml_within_limits\n",
"loads_toml_within_limits",
),
"module-aliased-relative": (
"from ...security import toml_limits as limits\n",
"limits.loads_toml_within_limits",
),
"module-dotted-absolute": (
"import local_deep_research.security.toml_limits\n",
"local_deep_research.security.toml_limits.loads_toml_within_limits",
),
}
@pytest.mark.parametrize(
("imports", "callee"),
list(_TOML_PARSE_SPELLINGS.values()),
ids=list(_TOML_PARSE_SPELLINGS),
)
def test_each_import_spelling_of_the_toml_parse_is_reported(imports, callee):
"""Each of these import spellings leaves the call visible to both scans."""
tree = ast.parse(
imports + "@router.post('/x')\n"
"async def handler(request):\n"
f" return {callee}(await request.body())\n"
)
direct = find_blocking_calls_in_async_route_handlers(tree)
assert [v[2] for v in direct] == [callee], direct
inner = _cross_module_blocking_hits(tree, "synthetic.py", ROUTERS_PACKAGE)
assert len(inner) == 1 and "calls `tomllib.loads`" in inner[0], inner
def test_an_offloaded_toml_parse_is_not_reported():
"""Negative control: the prescribed fix must not trip either scan."""
tree = ast.parse(
"from ...security import toml_limits\n"
"@router.post('/x')\n"
"async def handler(request):\n"
" body = await request.body()\n"
" return await asyncio.to_thread(\n"
" toml_limits.loads_toml_within_limits, body\n"
" )\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
hits = _cross_module_blocking_hits(tree, "synthetic.py", ROUTERS_PACKAGE)
assert hits == [], hits
def test_the_cross_module_scan_follows_a_package_reexport():
"""security/__init__.py re-exports ``safe_post`` from safe_requests.py,
whose own frame calls ``requests.post``. Importing it from the package
must not hide that. (No list in this file names ``safe_post``, so here
only the cross-module scan reports it.)"""
tree = ast.parse(
"from ...security import safe_post\n"
"@router.post('/x')\n"
"async def handler(request):\n"
" return safe_post('https://example.com')\n"
)
hits = _cross_module_blocking_hits(tree, "synthetic.py", ROUTERS_PACKAGE)
assert any(
"local_deep_research.security.safe_requests.safe_post() calls "
"`requests.post`" in hit
for hit in hits
), hits
class TestScopeWideningSelfTest:
"""Prove the three scope fixes actually detect what they were added for.
Each of these reconstructs a shape the guard could NOT see before, in
miniature. The first is not hypothetical: it is `notes.py`'s body gate,
which parsed up to 100 MB on the event loop across 24 routes while this
guard reported the file clean.
"""
def test_flags_a_blocking_call_in_an_async_depends_target(self):
"""The notes bug: an async, undecorated `Depends(...)` target.
FastAPI awaits it on the event loop before the handler runs, on
every request to every route that declares it -- it is an HTTP
entry point without a decorator saying so.
"""
tree = ast.parse(
"async def _notes_json_body(request):\n"
" body = bytearray()\n"
" return json.loads(body)\n"
"\n"
"@router.post('/api/notes')\n"
"def create_note(body=Depends(_notes_json_body)):\n"
" return {}\n"
)
found = find_blocking_calls_in_async_route_handlers(tree)
assert [(f[1], f[2]) for f in found] == [
("_notes_json_body", "json.loads")
], found
def test_ignores_an_async_helper_that_is_not_a_depends_target(self):
"""Scope widened to dependencies, not to every async function.
An undecorated async helper nobody wires into a route is still out
of scope -- otherwise the guard would flag ordinary internal code.
"""
tree = ast.parse(
"async def _some_internal_helper(x):\n return json.loads(x)\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_flags_a_blocking_call_in_an_app_decorated_handler(self):
"""`@app.exception_handler` runs on the loop exactly like a route."""
tree = ast.parse(
"@app.exception_handler(Exception)\n"
"async def unhandled(request, exc):\n"
" time.sleep(1)\n"
" return None\n"
)
found = find_blocking_calls_in_async_route_handlers(tree)
assert [(f[1], f[2]) for f in found] == [("unhandled", "time.sleep")]
def test_flags_json_loads_which_was_previously_exempt(self):
"""json was excluded as "a C extension, therefore fast enough".
Measured at ~110 ms/MB -- the same order as the tomllib figure this
category was created for. See the note above _CPU_BOUND_PARSERS.
"""
tree = ast.parse(
"@router.post('/x')\n"
"async def handler(request):\n"
" return json.loads(await request.body())\n"
)
found = find_blocking_calls_in_async_route_handlers(tree)
assert [f[2] for f in found] == ["json.loads"]
def test_asyncio_to_thread_offload_of_json_is_not_flagged(self):
"""Negative control: the prescribed fix must not trip the guard."""
tree = ast.parse(
"@router.post('/x')\n"
"async def handler(request):\n"
" body = await request.body()\n"
" return await asyncio.to_thread(json.loads, body)\n"
)
assert find_blocking_calls_in_async_route_handlers(tree) == []
def test_fastapi_app_is_in_scope():
"""Premise guard for the widening: if the file moves or is renamed,
the scan would silently stop covering the 9 async `@app` handlers."""
names = {p.name for p in SCANNED_FILES}
assert "fastapi_app.py" in names, (
"fastapi_app.py dropped out of SCANNED_FILES -- its "
"@app.exception_handler and @app.get handlers run on the event "
"loop and would go unscanned by this guard's blocklist."
)
assert (ROUTERS_DIR.parent / "fastapi_app.py").is_file()