rabbitkit 0.9.0__py3-none-any.whl

rabbitkit/dashboard/app.py

@@ -0,0 +1,212 @@
+"""Monitoring dashboard ASGI application.
+
+Provides a lightweight, dependency-free HTTP dashboard for monitoring
+a running rabbitkit broker.  Built on **Starlette** (optional dependency).
+
+Requires: ``pip install rabbitkit[dashboard]``
+
+Endpoints
+---------
+GET /               — HTML dashboard with route table and health status
+GET /api/health     — JSON health snapshot (status, connected, consumer_count, …)
+GET /api/routes     — JSON array of all registered routes
+
+Quick start
+-----------
+Mount as a standalone ASGI app with Uvicorn::
+
+    # myapp/dashboard.py
+    from rabbitkit.dashboard import create_dashboard_app
+    from myapp.main import broker      # your AsyncBroker or SyncBroker
+
+    app = create_dashboard_app(broker, auth_token="...")  # see SECURITY below
+
+    # Run separately, bound to loopback only by default (M8):
+    # uvicorn myapp.dashboard:app --host 127.0.0.1 --port 8080
+    #
+    # Only bind 0.0.0.0 deliberately, behind a NetworkPolicy/firewall/reverse
+    # proxy that terminates auth -- the dashboard exposes full broker
+    # topology (queue/exchange/routing-key names, consumer counts).
+
+CLI shortcut::
+
+    rabbitkit dashboard myapp.main:broker --port 8080
+
+Mount inside an existing FastAPI / Starlette app::
+
+    from fastapi import FastAPI
+    from starlette.routing import Mount
+    from rabbitkit.dashboard import create_dashboard_app
+
+    api = FastAPI()
+    dashboard = create_dashboard_app(broker)
+    api.mount("/rabbit", dashboard)
+
+With Management API integration (adds live queue stats)::
+
+    from rabbitkit.management import RabbitManagementClient, ManagementConfig
+    from rabbitkit.dashboard import create_dashboard_app
+
+    mgmt = RabbitManagementClient(
+        ManagementConfig(url="http://rabbitmq:15672", username="admin", password="secret")
+    )
+
+With MetricsCollector (adds throughput / latency metrics from MetricsMiddleware)::
+
+    from rabbitkit.middleware.metrics import MetricsCollector
+    from rabbitkit.dashboard import create_dashboard_app
+
+    collector = MetricsCollector()
+
+Health status values
+--------------------
+``GET /api/health`` returns:
+
+    {
+      "status":         "healthy" | "degraded" | "unhealthy",
+      "started":        true,
+      "connected":      true,
+      "consumer_count": 3,
+      "route_count":    3
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from html import escape
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def create_dashboard_app(
+    broker: Any,
+    *,
+    auth_token: str | None = None,
+) -> Any:
+    """Create an ASGI dashboard application.
+
+    SECURITY (M8): by default this app has NO authentication and exposes
+    broker topology (queue/exchange/routing-key names, consumer counts).
+    Bind the server to loopback (``127.0.0.1``, not ``0.0.0.0``) by default,
+    and mount it behind authn (OIDC/reverse proxy) plus network restriction
+    for anything beyond local access — never expose it publicly.
+
+    For a lightweight built-in guard, pass ``auth_token``: when set, every
+    route requires an ``Authorization: Bearer <auth_token>`` header
+    (compared in constant time via ``hmac.compare_digest``, not a plain
+    string ``!=``, which would leak timing information about the token) and
+    returns ``401`` otherwise. When unset (default), all requests pass
+    through and a startup warning is logged reminding you not to expose the
+    dashboard publicly.
+
+    Args:
+        broker: A rabbitkit broker instance (SyncBroker or AsyncBroker).
+        auth_token: Optional bearer token. When set, all routes require
+            ``Authorization: Bearer <auth_token>``. When None, the dashboard
+            runs unauthenticated (a startup warning is emitted).
+
+    Returns:
+        A Starlette application.
+
+    Raises:
+        ImportError: If starlette is not installed.
+    """
+    import hmac
+
+    try:
+        from starlette.applications import Starlette
+        from starlette.middleware.base import BaseHTTPMiddleware
+        from starlette.requests import Request  # noqa: TC002  # lazy optional import
+        from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse, Response
+        from starlette.routing import Route
+    except ImportError:  # pragma: no cover
+        raise ImportError(  # pragma: no cover
+            "Dashboard requires starlette. Install with: pip install rabbitkit[dashboard]"
+        ) from None
+
+    from rabbitkit.health import broker_health_check
+
+    if auth_token is None:
+        logger.warning("Dashboard running WITHOUT authentication — do not expose publicly")
+
+    class _BearerAuthMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next: Any) -> Response:
+            auth = request.headers.get("Authorization", "")
+            expected = f"Bearer {auth_token}"
+            # M8: hmac.compare_digest instead of != -- a plain string
+            # comparison short-circuits on the first mismatched byte, leaking
+            # the token's length (and, over many requests, its prefix) via a
+            # timing side channel. compare_digest runs in constant time
+            # regardless of where the mismatch is.
+            if not hmac.compare_digest(auth, expected):
+                return PlainTextResponse("Unauthorized", status_code=401)
+            return await call_next(request)  # type: ignore[no-any-return]
+
+    async def index(request: Any) -> Any:
+        routes_count = len(broker.routes)
+        health = broker_health_check(broker)
+        html = f"""<!DOCTYPE html>
+<html><head><title>rabbitkit Dashboard</title>
+<style>
+body {{ font-family: system-ui, sans-serif; max-width: 900px; margin: 2rem auto; padding: 0 1rem; }}
+h1 {{ color: #333; }}
+table {{ border-collapse: collapse; width: 100%; margin: 1rem 0; }}
+th, td {{ border: 1px solid #ddd; padding: 8px; text-align: left; }}
+th {{ background: #f5f5f5; }}
+.healthy {{ color: green; }} .degraded {{ color: orange; }} .unhealthy {{ color: red; }}
+</style></head>
+<body>
+<h1>rabbitkit Dashboard</h1>
+<h2>Health: <span class="{health.status.value}">{health.status.value.upper()}</span></h2>
+<p>Routes: {routes_count} | Connected: {health.connected} | Consumers: {health.consumer_count}</p>
+<h2>Routes</h2>
+<table><tr><th>Name</th><th>Queue</th><th>Exchange</th><th>Ack Policy</th></tr>"""
+        for r in broker.routes:
+            exchange = r.exchange.name if r.exchange else ""
+            # escape() — queue/exchange/route names render into HTML; never trust them raw
+            html += (
+                f"<tr><td>{escape(r.name)}</td><td>{escape(r.queue.name)}</td>"
+                f"<td>{escape(exchange)}</td><td>{escape(r.ack_policy.value)}</td></tr>"
+            )
+        html += "</table></body></html>"
+        return HTMLResponse(html)
+
+    async def api_health(request: Any) -> Any:
+        health = broker_health_check(broker)
+        return JSONResponse(
+            {
+                "status": health.status.value,
+                "started": health.started,
+                "connected": health.connected,
+                "consumer_count": health.consumer_count,
+                "route_count": health.route_count,
+            }
+        )
+
+    async def api_routes(request: Any) -> Any:
+        routes = []
+        for r in broker.routes:
+            routes.append(
+                {
+                    "name": r.name,
+                    "queue": r.queue.name,
+                    "exchange": r.exchange.name if r.exchange else "",
+                    "ack_policy": r.ack_policy.value,
+                    "tags": sorted(r.tags) if r.tags else [],
+                    "description": r.description,
+                }
+            )
+        return JSONResponse(routes)
+
+    app = Starlette(
+        routes=[
+            Route("/", index),
+            Route("/api/health", api_health),
+            Route("/api/routes", api_routes),
+        ],
+    )
+    if auth_token is not None:
+        app.add_middleware(_BearerAuthMiddleware)
+    return app

rabbitkit/di/__init__.py

@@ -0,0 +1,19 @@
+"""Dependency injection module — Depends, Context, Header, Path, DIResolver.
+
+Public API re-exported here per the project convention that each package's
+``__init__.py`` re-exports its public symbols.
+"""
+
+from rabbitkit.di.context import Context, ContextRepo, Header, Path
+from rabbitkit.di.depends import Depends
+from rabbitkit.di.resolver import DependencyScope, DIResolver
+
+__all__ = [
+    "Context",
+    "ContextRepo",
+    "DIResolver",
+    "DependencyScope",
+    "Depends",
+    "Header",
+    "Path",
+]

rabbitkit/di/context.py

@@ -0,0 +1,193 @@
+"""Context, Header, and Path markers + ContextRepo."""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Any
+
+
+class _MissingSentinel:
+    """Distinguishes "no default given" from an explicit ``default=None``
+    (H10) — a plain ``None`` default would be indistinguishable from "not
+    provided" otherwise."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<no default>"
+
+
+_MISSING = _MissingSentinel()
+
+
+class Context:
+    """Marker for context value injection.
+
+    Usage:
+        @broker.subscriber(queue="orders")
+        async def handle(
+            order: Order,
+            app_name: Annotated[str, Context("app")],
+        ) -> None:
+            ...
+
+    H10 — optional values: pass ``default=`` to make a missing context key
+    resolve to that value instead of raising, or simply give the parameter
+    itself a Python default (``app_name: Annotated[str | None, Context("app")]
+    = None``) — the resolver falls back to the parameter default when the
+    marker has none. With neither, a missing key raises
+    ``MissingDependencyError`` (PERMANENT — settles straight to the DLQ,
+    matching the ``KeyError`` this replaces).
+    """
+
+    def __init__(self, key: str, *, default: Any = _MISSING) -> None:
+        self.key = key
+        self.default = default
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not _MISSING
+
+    def __repr__(self) -> str:
+        return f"Context({self.key!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Context):
+            return NotImplemented
+        return self.key == other.key and self.default == other.default
+
+    def __hash__(self) -> int:
+        return hash(("Context", self.key))
+
+
+class Header:
+    """Marker for AMQP header extraction.
+
+    Usage:
+        @broker.subscriber(queue="orders")
+        async def handle(
+            order: Order,
+            tenant: Annotated[str, Header("x-tenant")],
+        ) -> None:
+            ...
+
+    H10 — optional values: pass ``default=`` to make a missing header
+    resolve to that value instead of raising, or simply give the parameter
+    itself a Python default (``tenant: Annotated[str | None,
+    Header("x-tenant")] = None``) — the resolver falls back to the parameter
+    default when the marker has none. With neither, a missing header raises
+    ``MissingDependencyError`` (PERMANENT — settles straight to the DLQ,
+    matching the ``KeyError`` this replaces).
+    """
+
+    def __init__(self, name: str, *, default: Any = _MISSING) -> None:
+        self.name = name
+        self.default = default
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not _MISSING
+
+    def __repr__(self) -> str:
+        return f"Header({self.name!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Header):
+            return NotImplemented
+        return self.name == other.name and self.default == other.default
+
+    def __hash__(self) -> int:
+        return hash(("Header", self.name))
+
+
+class Path:
+    """Marker for topic wildcard segment extraction.
+
+    Usage:
+        @broker.subscriber(queue="events", routing_key="events.*.#")
+        async def handle(
+            event: Event,
+            level: Annotated[str, Path("level")],
+        ) -> None:
+            ...
+
+    H10 — optional values: pass ``default=`` to make a missing path segment
+    resolve to that value instead of raising, or simply give the parameter
+    itself a Python default (``level: Annotated[str | None, Path("level")]
+    = None``) — the resolver falls back to the parameter default when the
+    marker has none. With neither, a missing segment raises
+    ``MissingDependencyError`` (PERMANENT — settles straight to the DLQ,
+    matching the ``KeyError`` this replaces).
+    """
+
+    def __init__(self, segment: str, *, default: Any = _MISSING) -> None:
+        self.segment = segment
+        self.default = default
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not _MISSING
+
+    def __repr__(self) -> str:
+        return f"Path({self.segment!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Path):
+            return NotImplemented
+        return self.segment == other.segment and self.default == other.default
+
+    def __hash__(self) -> int:
+        return hash(("Path", self.segment))
+
+
+class ContextRepo:
+    """Context repository for global and per-request values.
+
+    Global values are shared across all messages (thread-safe via a lock).
+    Local values use ``contextvars.ContextVar`` for correct isolation across
+    both sync threads AND async coroutines on the same event loop —
+    ``threading.local()`` would bleed context between concurrent coroutines
+    sharing one OS thread in an async transport.
+    """
+
+    def __init__(self) -> None:
+        self._global: dict[str, Any] = {}
+        self._local: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar("rabbitkit_local_ctx")
+
+    def set_global(self, key: str, value: Any) -> None:
+        """Set a global context value (shared across all messages)."""
+        self._global[key] = value
+
+    def set_local(self, key: str, value: Any) -> None:
+        """Set a per-request context value.
+
+        Uses ``ContextVar.set`` with an immutable copy so that each
+        coroutine/task gets its own isolated snapshot (contextvars
+        copy-on-write semantics).
+        """
+        try:
+            current = self._local.get()
+        except LookupError:
+            current = {}
+        self._local.set({**current, key: value})
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a context value. Local overrides global."""
+        try:
+            local = self._local.get()
+        except LookupError:
+            local = {}
+        if key in local:
+            return local[key]
+        return self._global.get(key, default)
+
+    def clear_local(self) -> None:
+        """Clear per-request context (called after each message)."""
+        self._local.set({})
+
+    def has(self, key: str) -> bool:
+        """Check if a key exists in either local or global context."""
+        try:
+            return key in self._local.get() or key in self._global
+        except LookupError:
+            return key in self._global

rabbitkit/di/depends.py

@@ -0,0 +1,42 @@
+"""Depends marker — dependency injection for handlers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class Depends:
+    """Marker for dependency injection.
+
+    Usage:
+        async def get_db() -> Session:
+            return Session()
+
+        @broker.subscriber(queue="orders")
+        async def handle(
+            order: Order,
+            db: Annotated[Session, Depends(get_db)],
+        ) -> None:
+            ...
+
+    Per-message lifetime: a fresh dependency graph is resolved for each
+    message. A generator (or async generator) dependency is supported too —
+    yield the value; the code after ``yield`` runs as teardown once the
+    handler completes (see :class:`~rabbitkit.di.resolver.DependencyScope`).
+    """
+
+    def __init__(self, dependency: Callable[..., Any], *, use_cache: bool = True) -> None:
+        self.dependency = dependency
+        self.use_cache = use_cache
+
+    def __repr__(self) -> str:
+        return f"Depends({self.dependency.__qualname__}, use_cache={self.use_cache})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Depends):
+            return NotImplemented
+        return self.dependency is other.dependency and self.use_cache == other.use_cache
+
+    def __hash__(self) -> int:
+        return hash((id(self.dependency), self.use_cache))