Skip to content

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.

7.2 KB
Raw Blame
"""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())