Skip to content

Self-improving AI Employees for everyone

4.7 KB
Raw Blame
"""Plugin-owned shutdown-hook registry for FastAPI lifespan teardown.

Closes the cross-plugin reaches in ``main.py``:

  - ``from nodes.android._relay.manager import close_relay_client``
  - ``from nodes.browser._service import shutdown_browser_service``

Both made the framework's lifespan code know about specific plugins'
internals. Plugins with cleanup logic now self-register a hook; the
lifespan awaits all registered hooks via :func:`run_shutdown_hooks`.

Distinct from :mod:`services._supervisor`: that registry is for
managed-subprocess supervisors (Go binaries, etc.) with a well-defined
``shutdown()`` contract. This registry is the general async-cleanup
hatch — any coroutine-shaped teardown (close a connection, drain a
queue, flush a cache, ...) goes here.

Hook signature
--------------

::

    hook() -> Awaitable[None]

The hook is named (label) so failures during shutdown surface with a
plugin identifier instead of just a traceback. Failures DO NOT block
sibling hooks — every hook runs even if one raises, mirroring the
``shutdown_all_supervisors`` semantics.
"""

from __future__ import annotations

import asyncio
import time
from typing import Awaitable, Callable, List, Tuple

from core.logging import get_logger
from services.plugin.registry import IdempotentRegistry

logger = get_logger(__name__)


ShutdownHook = Callable[[], Awaitable[None]]

# Per-hook ceiling. A hook that never returns used to wedge the whole
# lifespan teardown: under ``company serve`` the CLI's tree-kill (then 5 s
# after SIGTERM) masked it, but a desktop shell waiting for a clean exit (so
# Temporal / the JS executor sidecar / the WhatsApp bridge are reaped, not
# orphaned) saw the backend hang until the desktop deadline killed it.
# Each hook now gets this long, then teardown moves on and names the offender
# at WARNING. Hooks run one after another, so several hooks that each hit
# this cap can outlast what the host allows the whole teardown (the desktop
# deadline in ``core/desktop.py``, the CLI's ``backend_shutdown_grace_seconds``),
# which then kills the process tree (docs-internal/desktop_host_contract.md).
HOOK_TIMEOUT_SECONDS = 10.0


# Registry is keyed by label so each plugin can register exactly one
# hook under a stable name. The `items` view preserves insertion order
# (CPython 3.7+ dict ordering guarantee) which gives deterministic
# shutdown ordering. Plugins that need ordering invariants should
# document them via their label naming.
_REGISTRY: IdempotentRegistry[str, ShutdownHook] = IdempotentRegistry("plugin_shutdown_hook")


def register_shutdown_hook(label: str, hook: ShutdownHook) -> None:
    """Publish a shutdown hook for FastAPI lifespan teardown.

    Idempotent on re-import (same callable for the same label is a
    no-op). A different callable for an existing label raises
    ``ValueError`` to surface plugin namespace collisions at import time.

    Args:
        label: Stable plugin identifier (``"android_relay"``,
            ``"browser_service"``, ...). Surfaces in shutdown logs +
            in the error message if the hook raises.
        hook: Async function taking no arguments. Should be
            idempotent (lifespan may run it multiple times during
            test harness teardown).
    """
    _REGISTRY.register(label, hook)


def registered_labels() -> Tuple[str, ...]:
    """Return registered hook labels in insertion order (snapshot)."""
    return tuple(_REGISTRY.keys())


async def run_shutdown_hooks() -> None:
    """Run every registered shutdown hook in registration order.

    Per-hook failures are caught + logged with the hook's label so
    one slow / broken plugin doesn't strand the rest of the lifespan
    teardown. Mirrors ``services._supervisor.shutdown_all_supervisors``
    semantics.
    """
    hooks: List[Tuple[str, ShutdownHook]] = list(_REGISTRY.items().items())
    if not hooks:
        return

    logger.info(f"Running {len(hooks)} plugin shutdown hook(s): " f"{[label for label, _ in hooks]}")
    for label, hook in hooks:
        started = time.monotonic()
        try:
            await asyncio.wait_for(hook(), timeout=HOOK_TIMEOUT_SECONDS)
            logger.debug(f"Plugin shutdown hook {label!r} finished in {time.monotonic() - started:.2f}s")
        except asyncio.TimeoutError:
            logger.warning(
                f"Plugin shutdown hook {label!r} did not finish within {HOOK_TIMEOUT_SECONDS:g}s; "
                "continuing teardown without it"
            )
        except Exception as exc:  # noqa: BLE001 — log and continue
            logger.error(
                f"Plugin shutdown hook {label!r} raised; continuing: {exc}",
                exc_info=True,
            )


__all__ = [
    "HOOK_TIMEOUT_SECONDS",
    "register_shutdown_hook",
    "registered_labels",
    "run_shutdown_hooks",
    "ShutdownHook",
]