Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Blocking-route ratchet: no new ``async def`` handler without an ``await``.
FastAPI runs an ``async def`` handler ON the asyncio event loop; a plain
``def`` handler goes to the anyio threadpool. An ``async def`` body that never
awaits therefore runs its SQLite reads, directory walks and subprocess calls
on the one thread that answers every WebSocket, HTTP route and brain turn —
"every section loads slowly" was almost never the section, it was whichever
such route happened to be busy (measured 2026-08-28: ``/api/health`` 1.9 ms
alone, 8.19 s behind one blocking route; 285 such handlers existed on
2026-09-01, up from 234 four days earlier — they multiply faster than they
get fixed, hence this gate).
A handler is counted when:
* it is ``async def`` and decorated with a router verb
(``get/post/put/patch/delete/head/options/websocket/api_route``), and
* its own body (nested functions excluded) contains no ``await``,
``async for``, ``async with``, or ``yield``.
The fix is almost always to drop ``async`` — FastAPI then runs it in the
threadpool. The backlog is grandfathered per file (baseline JSON beside this
script); a file may never GAIN one.
Usage::
python scripts/ci/check_async_routes.py # gate
python scripts/ci/check_async_routes.py --report # worst files
python scripts/ci/check_async_routes.py --update # re-baseline (lower only)
Static analysis only — it never imports the app. Covered by
``tests/unit/ui/web/test_check_async_routes.py``.
"""
from __future__ import annotations
import argparse
import ast
import json
import sys
from pathlib import Path
_REPO = Path(__file__).resolve().parents[2]
_BASELINE = Path(__file__).resolve().parent / "async-routes-baseline.json"
#: Where route handlers live. Deliberately narrow: this gate is about the web
#: surface whose event loop is shared with voice and every other request.
_GLOB = "dodaios/ui/web/*_routes.py"
_ROUTE_VERBS = {
"get",
"post",
"put",
"patch",
"delete",
"head",
"options",
"websocket",
"api_route",
}
class UnparseableSource(RuntimeError):
"""A scanned file could not be parsed, so its count cannot be trusted."""
def _decorator_verb(node: ast.expr) -> str:
"""The attribute name a decorator call ends in (``router.get`` -> ``get``)."""
if isinstance(node, ast.Call):
node = node.func
if isinstance(node, ast.Attribute):
return node.attr.lower()
return ""
def _is_route_handler(fn: ast.AsyncFunctionDef) -> bool:
return any(_decorator_verb(dec) in _ROUTE_VERBS for dec in fn.decorator_list)
def _body_awaits(fn: ast.AsyncFunctionDef) -> bool:
"""Does the handler's OWN body await / async-iterate / yield?
Nested function definitions are skipped: an ``await`` inside a helper
closure does not put the handler itself on the threadpool.
"""
todo: list[ast.AST] = list(fn.body)
while todo:
node = todo.pop()
if isinstance(node, ast.Await | ast.AsyncFor | ast.AsyncWith | ast.Yield | ast.YieldFrom):
return True
if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda):
continue
todo.extend(ast.iter_child_nodes(node))
return False
def blocking_routes(path: Path) -> list[tuple[int, str]]:
"""``(line, name)`` of every async route handler with no await in *path*."""
source = path.read_text(encoding="utf-8-sig", errors="ignore")
try:
tree = ast.parse(source)
except SyntaxError as exc:
raise UnparseableSource(f"{path.relative_to(_REPO)} cannot be parsed ({exc}).") from exc
return [
(node.lineno, node.name)
for node in ast.walk(tree)
if isinstance(node, ast.AsyncFunctionDef)
and _is_route_handler(node)
and not _body_awaits(node)
]
def scan() -> dict[str, int]:
"""Per-file count of blocking async routes, keyed by repo-relative path."""
counts: dict[str, int] = {}
for path in sorted(_REPO.glob(_GLOB)):
found = blocking_routes(path)
if found:
counts[path.relative_to(_REPO).as_posix()] = len(found)
return counts
def load_baseline() -> dict[str, int]:
if not _BASELINE.exists():
return {}
return json.loads(_BASELINE.read_text(encoding="utf-8"))["files"]
def save_baseline(counts: dict[str, int]) -> None:
payload = {
"_comment": (
"Per-file count of async-def route handlers whose body never "
"awaits - each one runs its disk I/O on the shared event loop. "
"Generated by scripts/ci/check_async_routes.py --update. These "
"numbers may go DOWN freely; an increase is a gate failure."
),
"total": sum(counts.values()),
"files": dict(sorted(counts.items())),
}
_BASELINE.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
def regressions(current: dict[str, int], baseline: dict[str, int]) -> dict[str, tuple[int, int]]:
"""Files that gained blocking routes, mapped to ``(baseline, current)``."""
out: dict[str, tuple[int, int]] = {}
for path, count in sorted(current.items()):
was = baseline.get(path, 0)
if count > was:
out[path] = (was, count)
return out
def main() -> int:
parser = argparse.ArgumentParser(description="Blocking-route ratchet.")
parser.add_argument("--report", action="store_true", help="show the worst files, exit 0")
parser.add_argument("--update", action="store_true", help="rewrite the baseline")
parser.add_argument(
"--allow-increase",
action="store_true",
help="with --update: permit a higher count (say why in the commit)",
)
args = parser.parse_args()
current = scan()
total = sum(current.values())
if args.report:
print(f"{total} blocking async routes across {len(current)} files.\n")
for path, count in sorted(current.items(), key=lambda kv: -kv[1])[:25]:
print(f" {count:4d} {path}")
return 0
baseline = load_baseline()
if args.update:
if baseline and not args.allow_increase:
bad = regressions(current, baseline)
if bad:
print(f"Refusing to raise the baseline for {len(bad)} file(s):\n")
for path, (was, now) in list(bad.items())[:20]:
print(f" {path}: {was} -> {now}")
print("\nDrop the handler's `async`, or pass --allow-increase deliberately.")
return 1
save_baseline(current)
print(f"Baseline written: {total} blocking async routes across {len(current)} files.")
return 0
if not baseline:
print("No baseline yet. Run with --update to create one.")
return 1
bad = regressions(current, baseline)
if not bad:
print(f"OK: no file gained a blocking async route (total {total}).")
return 0
print("New async routes that never await - their I/O blocks every other request:\n")
for path, (was, now) in list(bad.items())[:20]:
print(f" {path}: {was} -> {now}")
print(
"\nFix: drop the `async` - FastAPI runs a plain `def` handler in the "
"anyio threadpool, off the shared event loop. Keep `async` only for a "
"body that actually awaits.",
)
return 1
if __name__ == "__main__":
sys.exit(main())