baldur.api.admin — Framework-Free Admin HTTP Server

Stdlib http.server.ThreadingHTTPServer-based management API. Runs in a daemon thread, dispatches to framework-agnostic handler functions, and integrates with ShutdownCoordinator for graceful drain. Auto-starts via baldur.init() when BALDUR_ADMIN_AUTOSTART=1 (the default).

admin

Framework-free admin HTTP server.

Stdlib http.server.ThreadingHTTPServer based management API. Runs in a daemon thread, dispatches to framework-agnostic handler functions, and integrates with :class:baldur.core.shutdown_coordinator.ShutdownCoordinator for graceful drain.

Public entry point::

import baldur

baldur.init()
baldur.start_admin_server(port=9090)   # manual start

Or auto-start via :func:baldur.init when BALDUR_ADMIN_AUTOSTART=1 (the default).

Status: Public

AdminRoute `dataclass`

AdminRoute(
    method: HttpMethod,
    path: str,
    handler: HandlerFunc,
    permission_level: PermissionLevel = PermissionLevel.VIEWER,
)

A single admin-server route.

Attributes:

Name	Type	Description
`method`	`HttpMethod`	HTTP method.
`path`	`str`	Path template with optional `{param}` segments.
`handler`	`HandlerFunc`	Framework-agnostic handler function.
`permission_level`	`PermissionLevel`	Required permission to invoke the handler.

match

match(method: str, path: str) -> dict[str, str] | None

Return path params dict if route matches, else None.

Captured segments are percent-decoded: the client encodes a path param with encodeURIComponent (the console JS does so for DLQ ids), so a Redis-adapter composite id like host:pid:hash:seq arrives as host%3Apid%3A... and must be decoded back before it reaches get_by_id — otherwise every per-id lookup 404s.

AdminServer

AdminServer(
    settings: AdminServerSettings | None = None,
    registry: AdminRegistry | None = None,
)

Daemon-thread admin HTTP server.

Lifecycle

AdminServer(...) → :meth:start → (serving in background) → :meth:stop. :meth:stop is idempotent.

Use the module-level :func:start_admin_server / :func:stop_admin_server helpers from application code; :class:AdminServer is exposed for tests and advanced integrations.

bound_port `property`

bound_port: int | None

Actual port the server bound to (useful with port=0 in tests).

start

start() -> None

Start listening. Idempotent.

Raises:

Type	Description
`AdminAuthRequiredError`	non-localhost bind without an API key.

stop

stop(timeout: float = 5.0) -> None

Stop the server. Idempotent and safe from any thread.

register_admin_route

register_admin_route(
    method: HttpMethod | str,
    path: str,
    handler: HandlerFunc,
    permission_level: PermissionLevel = PermissionLevel.VIEWER,
) -> None

Convenience wrapper: register_admin_route("GET", "/health", health_check).

get_admin_server

get_admin_server() -> AdminServer | None

Return the running server instance, or None if not started.

reset_admin_server

reset_admin_server() -> None

Reset the module-level singleton — test isolation only.

start_admin_server

start_admin_server(
    port: int | None = None,
    bind: str | None = None,
    *,
    register_shutdown: bool = True
) -> AdminServer

Public entry point — start the admin server.

Arguments override the corresponding settings when provided; otherwise settings (BALDUR_ADMIN_*) apply. Subsequent calls return the already running server.

Parameters:

Name	Type	Description	Default
`port`	`int \| None`	Override `BALDUR_ADMIN_PORT`.	`None`
`bind`	`str \| None`	Override `BALDUR_ADMIN_BIND`.	`None`
`register_shutdown`	`bool`	When True (default), integrates with :class:`~baldur.core.shutdown_coordinator.ShutdownCoordinator` so the server stops cleanly on process shutdown.	`True`

Returns:

Name	Type	Description
`The`	`AdminServer`	class:`AdminServer` instance.