hexastack-fastapi 0.2.0__tar.gz → 0.3.0__tar.gz

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexastack-fastapi
-Version: 0.2.0
+Version: 0.3.0
 Summary: FastAPI presentation adapter for Hexastack
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -40,28 +40,32 @@ Description-Content-Type: text/markdown
 ## 1. Overview & Capabilities
 
 - **Automatic CQRS Routing & Feature Gating**: Map HTTP endpoints directly to `CommandBusPort` or `QueryBusPort` using `@api_command` and `@api_query`, with native feature flag route guards (`@feature_flag_route` and `require_feature(...)`).
+- **Server-Sent Events (SSE) Real-Time Streaming**: Native `ServerSentEvent` formatting and `EventSourceResponse` supporting chunked transfer encoding, keep-alive heartbeat pings, and direct streaming queries on `CqrsRouter.add_streaming_query`.
+- **WebSockets Real-Time Channel Manager & CQRS Bridge**: `WebSocketConnectionManager` managing connection pools, room/channel groupings, and broadcasts, alongside `WebSocketCqrsBridge` mapping incoming socket JSON actions into CQRS Commands and Queries.
 - **Decoupled Database Session Middleware**: `DbSessionMiddleware` (sync) and `AsyncDbSessionMiddleware` (async) manage session-per-request lifecycles by consuming sessionmakers from DI without a hard dependency on `hexastack-db`.
 - **Standardized Exception Handlers**: Automatically translates domain exceptions (`EntityNotFoundError`, `UniqueConstraintViolationError`, `HexastackError`) into appropriate HTTP status codes (404, 409, 500) and structured JSON error envelopes.
-- **Observability & Correlation Middleware**: Injects `X-Correlation-ID` headers and logs HTTP request lifecycles.
+- **Observability & Correlation Middleware**: Injects `X-Correlation-ID` headers, logs HTTP request lifecycles, and captures HTTP RED metrics (`HttpMetricsMiddleware`) exposing a standard `/metrics` endpoint.
 - **Built-in Health Checks**: Configurable `/health` and `/ready` endpoints verifying container and subsystem readiness.
 - **NiceGUI Reactive UI & DevTools Dashboard**: Optional `[ui]` presentation adapter providing `ui_page`, `dispatch_command`, `dispatch_query`, and a zero-config interactive developer console (`mount_devtools_dashboard`) for inspecting CQRS buses, feature flags, and DI services.
 
+
 ---
 
 ## 2. Package Anatomy & Key Components
 
 ```
 hexastack_fastapi/
-├── domain/          # HealthStatus, HTTP error envelope models
-├── adapters/        # create_app, routing decorators, health endpoints, db_session middleware, dependencies, NiceGUI UI adapter
-└── infra/           # FastApiBootstrapper (order=30), exception handlers, correlation/logging middlewares
+├── domain/          # HealthStatus, HTTP error envelope models, HexastackFastApiConfig
+├── adapters/        # routing decorators, SSE streaming, WebSockets, health endpoints, db_session middleware, dependencies, NiceGUI UI adapter
+└── infra/           # create_fastapi_app, FastApiBootstrapper (order=30), exception handlers, correlation/logging middlewares
 ```
 
+
 ### Key Exports
 
 | Category | Exports |
 |---|---|
-| **Application Factory** | `create_app`, `FastApiBootstrapper` (order=30) |
+| **Application Factory** | `create_fastapi_app`, `FastApiBootstrapper` (order=30) |
 | **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `@rate_limit`, `RouteMetadata` |
 | **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature`, `get_rate_limiter`, `require_rate_limit` |
 | **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
@@ -69,12 +73,13 @@ hexastack_fastapi/
 | **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
 | **Rate Limiting** | `SlowapiRateLimiterAdapter`, `get_remote_address`, `get_user_or_ip_key`, `RateLimitConfig` |
 | **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
+| **Real-Time Streaming (SSE & WebSockets)** | `EventSourceResponse`, `ServerSentEvent`, `WebSocketConnectionManager`, `WebSocketCqrsBridge` |
 | **Routing** | `CqrsRouter`, `autodiscover_routes` |
 | **Testing, E2E & Demo Narration** | `create_test_client`, `check_openapi_conformance`, `EphemeralServer`, `ephemeral_server`, `find_free_port`, `smart_click`, `DemoNarrator`, `VIRTUAL_CURSOR_SCRIPT` |
 
-
 ---
 
+
 ## 3. Monorepo & Sibling Relationships
 
 ```mermaid

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/README.md

@@ -15,28 +15,32 @@
 ## 1. Overview & Capabilities
 
 - **Automatic CQRS Routing & Feature Gating**: Map HTTP endpoints directly to `CommandBusPort` or `QueryBusPort` using `@api_command` and `@api_query`, with native feature flag route guards (`@feature_flag_route` and `require_feature(...)`).
+- **Server-Sent Events (SSE) Real-Time Streaming**: Native `ServerSentEvent` formatting and `EventSourceResponse` supporting chunked transfer encoding, keep-alive heartbeat pings, and direct streaming queries on `CqrsRouter.add_streaming_query`.
+- **WebSockets Real-Time Channel Manager & CQRS Bridge**: `WebSocketConnectionManager` managing connection pools, room/channel groupings, and broadcasts, alongside `WebSocketCqrsBridge` mapping incoming socket JSON actions into CQRS Commands and Queries.
 - **Decoupled Database Session Middleware**: `DbSessionMiddleware` (sync) and `AsyncDbSessionMiddleware` (async) manage session-per-request lifecycles by consuming sessionmakers from DI without a hard dependency on `hexastack-db`.
 - **Standardized Exception Handlers**: Automatically translates domain exceptions (`EntityNotFoundError`, `UniqueConstraintViolationError`, `HexastackError`) into appropriate HTTP status codes (404, 409, 500) and structured JSON error envelopes.
-- **Observability & Correlation Middleware**: Injects `X-Correlation-ID` headers and logs HTTP request lifecycles.
+- **Observability & Correlation Middleware**: Injects `X-Correlation-ID` headers, logs HTTP request lifecycles, and captures HTTP RED metrics (`HttpMetricsMiddleware`) exposing a standard `/metrics` endpoint.
 - **Built-in Health Checks**: Configurable `/health` and `/ready` endpoints verifying container and subsystem readiness.
 - **NiceGUI Reactive UI & DevTools Dashboard**: Optional `[ui]` presentation adapter providing `ui_page`, `dispatch_command`, `dispatch_query`, and a zero-config interactive developer console (`mount_devtools_dashboard`) for inspecting CQRS buses, feature flags, and DI services.
 
+
 ---
 
 ## 2. Package Anatomy & Key Components
 
 ```
 hexastack_fastapi/
-├── domain/          # HealthStatus, HTTP error envelope models
-├── adapters/        # create_app, routing decorators, health endpoints, db_session middleware, dependencies, NiceGUI UI adapter
-└── infra/           # FastApiBootstrapper (order=30), exception handlers, correlation/logging middlewares
+├── domain/          # HealthStatus, HTTP error envelope models, HexastackFastApiConfig
+├── adapters/        # routing decorators, SSE streaming, WebSockets, health endpoints, db_session middleware, dependencies, NiceGUI UI adapter
+└── infra/           # create_fastapi_app, FastApiBootstrapper (order=30), exception handlers, correlation/logging middlewares
 ```
 
+
 ### Key Exports
 
 | Category | Exports |
 |---|---|
-| **Application Factory** | `create_app`, `FastApiBootstrapper` (order=30) |
+| **Application Factory** | `create_fastapi_app`, `FastApiBootstrapper` (order=30) |
 | **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `@rate_limit`, `RouteMetadata` |
 | **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature`, `get_rate_limiter`, `require_rate_limit` |
 | **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
@@ -44,12 +48,13 @@ hexastack_fastapi/
 | **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
 | **Rate Limiting** | `SlowapiRateLimiterAdapter`, `get_remote_address`, `get_user_or_ip_key`, `RateLimitConfig` |
 | **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
+| **Real-Time Streaming (SSE & WebSockets)** | `EventSourceResponse`, `ServerSentEvent`, `WebSocketConnectionManager`, `WebSocketCqrsBridge` |
 | **Routing** | `CqrsRouter`, `autodiscover_routes` |
 | **Testing, E2E & Demo Narration** | `create_test_client`, `check_openapi_conformance`, `EphemeralServer`, `ephemeral_server`, `find_free_port`, `smart_click`, `DemoNarrator`, `VIRTUAL_CURSOR_SCRIPT` |
 
-
 ---
 
+
 ## 3. Monorepo & Sibling Relationships
 
 ```mermaid

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.2.0"
+version = "0.3.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -52,8 +52,8 @@ name = "Hexagonal architecture layer hierarchy"
 type = "layers"
 containers = ["hexastack_fastapi"]
 layers = [
-    "adapters",
     "infra",
+    "adapters",
 ]
 
 [[tool.importlinter.contracts]]

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.2.0"
+version = "0.3.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -54,8 +54,8 @@ name = "Hexagonal architecture layer hierarchy"
 type = "layers"
 containers = ["hexastack_fastapi"]
 layers = [
-    "adapters",
     "infra",
+    "adapters",
 ]
 
 [[tool.importlinter.contracts]]

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/adapters/__init__.py

@@ -13,6 +13,7 @@ from hexastack_fastapi.adapters.docs import (
     mount_zensical_docs,
 )
 from hexastack_fastapi.adapters.health import create_health_router
+from hexastack_fastapi.adapters.metrics import create_metrics_router
 from hexastack_fastapi.adapters.ratelimit import (
     SlowapiRateLimiterAdapter,
     get_remote_address,
@@ -20,6 +21,10 @@ from hexastack_fastapi.adapters.ratelimit import (
     rate_limit,
 )
 from hexastack_fastapi.adapters.routing import CqrsRouter
+from hexastack_fastapi.adapters.sse import (
+    EventSourceResponse,
+    ServerSentEvent,
+)
 from hexastack_fastapi.adapters.ui import (
     dispatch_command,
     dispatch_query,
@@ -27,16 +32,21 @@ from hexastack_fastapi.adapters.ui import (
     mount_ui_app,
     ui_page,
 )
+from hexastack_fastapi.adapters.websockets import (
+    WebSocketConnectionManager,
+    WebSocketCqrsBridge,
+)
 
 __all__ = [
     "check_openapi_conformance",
     "CqrsRouter",
-    "create_fastapi_app",
     "create_health_router",
+    "create_metrics_router",
     "create_test_client",
     "dispatch_command",
     "dispatch_query",
     "DocumentationNotFoundError",
+    "EventSourceResponse",
     "get_container",
     "get_feature_flags",
     "get_pipeline",
@@ -49,6 +59,9 @@ __all__ = [
     "rate_limit",
     "require_feature",
     "require_rate_limit",
+    "ServerSentEvent",
     "SlowapiRateLimiterAdapter",
     "ui_page",
+    "WebSocketConnectionManager",
+    "WebSocketCqrsBridge",
 ]

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/adapters/health.py

@@ -6,7 +6,6 @@ from fastapi.responses import JSONResponse
 from rodi import Container
 
 from hexastack_core.utils.context import get_correlation_id
-from hexastack_fastapi.infra.config import HealthConfig
 
 __all__ = [
     "create_health_router",
@@ -15,17 +14,22 @@ __all__ = [
 
 def create_health_router(
     container: Container | None = None,
-    config: HealthConfig | None = None,
+    config: Any | None = None,
+    health_path: str = "/health",
+    ready_path: str = "/ready",
 ) -> APIRouter:
     """Create APIRouter with standard liveness and readiness probe endpoints.
 
     Notes/Architectural Intent:
         Exposes lightweight /health (liveness) and /ready (readiness) endpoints for orchestration
-        platforms like Kubernetes and container engines.
+        platforms like Kubernetes and container engines. Decoupled from infra configuration schemas
+        by accepting primitives or duck-typed config objects.
 
     Args:
         container: Optional rodi Container instance to check dependency health.
-        config: Optional HealthConfig specifying custom URL paths.
+        config: Optional configuration object specifying custom URL paths (e.g. HealthConfig).
+        health_path: Default liveness probe path (used if config not provided).
+        ready_path: Default readiness probe path (used if config not provided).
 
     Returns:
         APIRouter mounted with health endpoints.
@@ -33,10 +37,19 @@ def create_health_router(
     Raises:
         None.
     """
-    cfg = config or HealthConfig()
+    resolved_health_path = (
+        getattr(config, "health_path", None) or health_path
+        if config is not None
+        else health_path
+    )
+    resolved_ready_path = (
+        getattr(config, "ready_path", None) or ready_path
+        if config is not None
+        else ready_path
+    )
     router = APIRouter(tags=["Health"])
 
-    @router.get(cfg.health_path, summary="Liveness Probe")
+    @router.get(resolved_health_path, summary="Liveness Probe")
     async def liveness() -> dict[str, Any]:
         return {
             "status": "ok",
@@ -44,7 +57,7 @@ def create_health_router(
             "correlation_id": get_correlation_id(),
         }
 
-    @router.get(cfg.ready_path, summary="Readiness Probe")
+    @router.get(resolved_ready_path, summary="Readiness Probe")
     async def readiness() -> JSONResponse:
         checks: dict[str, str] = {
             "container": "ok" if container is not None else "unconfigured",

hexastack_fastapi-0.3.0/src/hexastack_fastapi/adapters/metrics.py

@@ -0,0 +1,44 @@
+"""Prometheus Metrics Endpoint Router for FastAPI."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Response
+from rodi import Container
+
+from hexastack_core.ports.metrics import MetricsPort
+
+
+def create_metrics_router(container: Container | None = None) -> APIRouter:
+    """Create a FastAPI APIRouter mounting the /metrics Prometheus scraper endpoint.
+
+    Args:
+        container: Active rodi Container to resolve MetricsPort.
+
+    Returns:
+        APIRouter exposing GET /metrics.
+    """
+    router = APIRouter(tags=["Observability"])
+
+    @router.get("/metrics", include_in_schema=False)
+    async def get_metrics() -> Response:
+        if container is not None and MetricsPort in container:
+            metrics_port = container.resolve(MetricsPort)
+            body = metrics_port.generate_metrics_text()
+        else:
+            try:
+                from prometheus_client import generate_latest
+
+                body = generate_latest()
+            except ImportError:
+                body = b"# Prometheus metrics not configured"
+
+        return Response(
+            content=body, media_type="text/plain; version=0.0.4; charset=utf-8"
+        )
+
+    return router
+
+
+__all__ = [
+    "create_metrics_router",
+]

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/adapters/routing.py

@@ -8,6 +8,7 @@ from fastapi import APIRouter, Depends
 from hexastack_core.domain import Command, Query
 from hexastack_cqrs.infra.pipeline import ExecutionPipeline
 from hexastack_fastapi.adapters.dependencies import get_pipeline
+from hexastack_fastapi.adapters.sse import EventSourceResponse
 
 
 class CqrsRouter(APIRouter):
@@ -90,7 +91,7 @@ class CqrsRouter(APIRouter):
         Args:
             path: URL path for the route.
             query_cls: Pydantic Query model class.
-            method: HTTP method ('GET' or 'POST').
+            method: HTTP method (e.g., 'GET' or 'POST').
             status_code: Success HTTP status code.
             output_format: Optional presenter format (e.g., 'json').
             summary: Optional OpenAPI summary string.
@@ -126,6 +127,55 @@ class CqrsRouter(APIRouter):
             response_model=None,
         )
 
+    def add_streaming_query[TQuery: Query](
+        self,
+        path: str,
+        query_cls: type[TQuery],
+        *,
+        method: str = "GET",
+        summary: str | None = None,
+        tags: list[str | Enum] | None = None,
+        feature_flag: str | None = None,
+        rate_limit: str | None = None,
+        ping_interval: float | None = None,
+    ) -> None:
+        """Register a Server-Sent Events (SSE) streaming endpoint for a Query model.
+
+        Args:
+            path: URL path for the route.
+            query_cls: Pydantic Query model class.
+            method: HTTP method (e.g. 'GET' or 'POST').
+            summary: Optional OpenAPI summary string.
+            tags: Optional OpenAPI tags list.
+            feature_flag: Optional feature flag key required for endpoint execution.
+            rate_limit: Optional rate limit string (e.g. '10/minute').
+            ping_interval: Optional keep-alive ping interval in seconds.
+
+        Returns:
+            None.
+        """
+        endpoint = _create_streaming_query_endpoint(query_cls, method, ping_interval)
+        dependencies = []
+        if feature_flag:
+            from hexastack_fastapi.adapters.dependencies import require_feature
+
+            dependencies.append(Depends(require_feature(feature_flag)))
+        if rate_limit:
+            from hexastack_fastapi.adapters.dependencies import require_rate_limit
+
+            dependencies.append(Depends(require_rate_limit(rate_limit)))
+
+        self.add_api_route(
+            path=path,
+            endpoint=endpoint,
+            methods=[method.upper()],
+            status_code=200,
+            summary=summary or f"Stream {query_cls.__name__}",
+            tags=tags,
+            dependencies=dependencies if dependencies else None,
+            response_class=EventSourceResponse,
+        )
+
 
 __all__ = [
     "CqrsRouter",
@@ -213,3 +263,59 @@ def _create_query_endpoint(
     ]
     cast("Any", post_endpoint).__signature__ = sig.replace(parameters=params)
     return post_endpoint
+
+
+def _create_streaming_query_endpoint(
+    query_cls: type[Query], method: str, ping_interval: float | None
+) -> Callable[..., Any]:
+    """Dynamically construct an SSE streaming FastAPI endpoint for a Query model."""
+    if method.upper() == "GET":
+
+        async def get_stream_endpoint(
+            qry: Any,
+            pipeline: Annotated[ExecutionPipeline, Depends(get_pipeline)],
+        ) -> EventSourceResponse:
+            gen = pipeline.execute(qry)
+            return EventSourceResponse(gen, ping_interval=ping_interval)
+
+        sig = inspect.signature(get_stream_endpoint)
+        params = [
+            inspect.Parameter(
+                "qry",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=query_cls,
+                default=Depends(query_cls),
+            ),
+            inspect.Parameter(
+                "pipeline",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=ExecutionPipeline,
+                default=Depends(get_pipeline),
+            ),
+        ]
+        cast("Any", get_stream_endpoint).__signature__ = sig.replace(parameters=params)
+        return get_stream_endpoint
+
+    async def post_stream_endpoint(
+        qry: Any,
+        pipeline: Annotated[ExecutionPipeline, Depends(get_pipeline)],
+    ) -> EventSourceResponse:
+        gen = pipeline.execute(qry)
+        return EventSourceResponse(gen, ping_interval=ping_interval)
+
+    sig = inspect.signature(post_stream_endpoint)
+    params = [
+        inspect.Parameter(
+            "qry",
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=query_cls,
+        ),
+        inspect.Parameter(
+            "pipeline",
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=ExecutionPipeline,
+            default=Depends(get_pipeline),
+        ),
+    ]
+    cast("Any", post_stream_endpoint).__signature__ = sig.replace(parameters=params)
+    return post_stream_endpoint

hexastack_fastapi-0.3.0/src/hexastack_fastapi/adapters/sse.py

@@ -0,0 +1,190 @@
+"""Server-Sent Events (SSE) Streaming Response Adapters for FastAPI & Starlette."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterable, AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi.responses import Response
+from starlette.background import BackgroundTask
+from starlette.types import Receive, Scope, Send
+
+
+@dataclass(frozen=True)
+class ServerSentEvent:
+    """Represents an individual Server-Sent Event frame.
+
+    Notes/Architectural Intent:
+        Standardizes the W3C Server-Sent Events wire format.
+        Supports structured JSON data, event type naming, event IDs, retry intervals,
+        and keep-alive comments.
+    """
+
+    data: Any = None
+    event: str | None = None
+    id: str | None = None
+    retry: int | None = None
+    comment: str | None = None
+
+    def encode(self) -> bytes:
+        """Encode the Server-Sent Event into bytes conforming to the text/event-stream spec.
+
+        Returns:
+            Encoded bytes terminated with double newlines.
+        """
+        buffer: list[str] = []
+
+        if self.comment is not None:
+            for line in self.comment.splitlines():
+                buffer.append(f": {line}\n")
+
+        if self.id is not None:
+            buffer.append(f"id: {self.id}\n")
+
+        if self.event is not None:
+            buffer.append(f"event: {self.event}\n")
+
+        if self.retry is not None:
+            buffer.append(f"retry: {self.retry}\n")
+
+        if self.data is not None:
+            raw_data = str(self.data) if not isinstance(self.data, str) else self.data
+            for line in raw_data.splitlines():
+                buffer.append(f"data: {line}\n")
+        elif self.comment is None and self.event is None and self.id is None:
+            buffer.append("data:\n")
+
+        buffer.append("\n")
+        return "".join(buffer).encode("utf-8")
+
+
+class EventSourceResponse(Response):
+    """FastAPI/Starlette Response subclass streaming Server-Sent Events over HTTP.
+
+    Notes/Architectural Intent:
+        Implements chunked transfer encoding over HTTP/1.1 or standard HTTP/2/3 streams
+        with media type 'text/event-stream'. Supports optional background ping keep-alives
+        to prevent reverse proxy timeouts (e.g. NGINX, Cloudflare).
+    """
+
+    media_type = "text/event-stream"
+
+    def __init__(
+        self,
+        content: AsyncIterable[ServerSentEvent | str | bytes | dict[str, Any]],
+        status_code: int = 200,
+        headers: dict[str, str] | None = None,
+        media_type: str | None = None,
+        background: BackgroundTask | None = None,
+        ping_interval: float | None = None,
+    ) -> None:
+        """Initialize EventSourceResponse.
+
+        Args:
+            content: Async generator or iterable yielding ServerSentEvent or raw data.
+            status_code: HTTP status code (default 200).
+            headers: Optional HTTP headers dictionary.
+            media_type: Content-Type override (defaults to text/event-stream).
+            background: Optional Starlette BackgroundTask.
+            ping_interval: Optional interval in seconds to yield keep-alive comment pings.
+        """
+        self.body_iterator = content
+        self.ping_interval = ping_interval
+        headers = headers or {}
+        headers.setdefault("Cache-Control", "no-cache")
+        headers.setdefault("Connection", "keep-alive")
+        headers.setdefault("X-Accel-Buffering", "no")
+        super().__init__(
+            content=b"",
+            status_code=status_code,
+            headers=headers,
+            media_type=media_type or self.media_type,
+            background=background,
+        )
+
+    async def _stream_with_ping(self) -> AsyncIterator[bytes]:
+        """Wrap body_iterator with periodic keep-alive pings."""
+        queue: asyncio.Queue[bytes | None] = asyncio.Queue()
+
+        async def _producer() -> None:
+            try:
+                async for item in self.body_iterator:
+                    if isinstance(item, ServerSentEvent):
+                        await queue.put(item.encode())
+                    elif isinstance(item, bytes):
+                        await queue.put(item)
+                    elif isinstance(item, str):
+                        await queue.put(ServerSentEvent(data=item).encode())
+                    else:
+                        import json
+
+                        await queue.put(ServerSentEvent(data=json.dumps(item)).encode())
+            except Exception:
+                await queue.put(None)
+                raise
+            finally:
+                await queue.put(None)
+
+        producer_task = asyncio.create_task(_producer())
+
+        try:
+            while True:
+                if self.ping_interval and self.ping_interval > 0:
+                    try:
+                        chunk = await asyncio.wait_for(
+                            queue.get(), timeout=self.ping_interval
+                        )
+                        if chunk is None:
+                            break
+                        yield chunk
+                    except TimeoutError:
+                        yield ServerSentEvent(comment="ping").encode()
+                else:
+                    chunk = await queue.get()
+                    if chunk is None:
+                        break
+                    yield chunk
+        finally:
+            if not producer_task.done():
+                producer_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError, Exception):
+                    _res = await producer_task
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI response streaming callable."""
+        await send(
+            {
+                "type": "http.response.start",
+                "status": self.status_code,
+                "headers": self.raw_headers,
+            }
+        )
+
+        async for chunk in self._stream_with_ping():
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": chunk,
+                    "more_body": True,
+                }
+            )
+
+        await send(
+            {
+                "type": "http.response.body",
+                "body": b"",
+                "more_body": False,
+            }
+        )
+
+        if self.background is not None:
+            await self.background()
+
+
+__all__ = [
+    "EventSourceResponse",
+    "ServerSentEvent",
+]

hexastack_fastapi-0.3.0/src/hexastack_fastapi/adapters/websockets.py

@@ -0,0 +1,212 @@
+"""WebSocket Connection Manager and Channel Router Adapters for FastAPI."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+from hexastack_core.domain import Command, Query
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+
+class WebSocketConnectionManager:
+    """Manages active WebSocket connections, grouping by room and client identity.
+
+    Notes/Architectural Intent:
+        Encapsulates connection lifecycle (connect, disconnect, broadcast) and room grouping.
+        Maintains an in-memory connection registry protected by asyncio concurrency semantics.
+    """
+
+    def __init__(self) -> None:
+        """Initialize WebSocketConnectionManager with empty connection pools."""
+        self._active_connections: set[Any] = set()
+        self._rooms: dict[str, set[Any]] = defaultdict(set)
+        self._lock = asyncio.Lock()
+
+    async def connect(self, websocket: Any, room: str | None = None) -> None:
+        """Accept an incoming WebSocket connection and register in pools.
+
+        Args:
+            websocket: Incoming FastAPI WebSocket instance or mock.
+            room: Optional room/channel identifier to subscribe to.
+        """
+        await websocket.accept()
+        async with self._lock:
+            self._active_connections.add(websocket)
+            if room:
+                self._rooms[room].add(websocket)
+
+    async def disconnect(self, websocket: Any, room: str | None = None) -> None:
+        """Remove a WebSocket connection from active pools and rooms.
+
+        Args:
+            websocket: Terminated WebSocket instance.
+            room: Optional specific room from which to unsubscribe.
+        """
+        async with self._lock:
+            self._active_connections.discard(websocket)
+            if room and room in self._rooms:
+                self._rooms[room].discard(websocket)
+                if not self._rooms[room]:
+                    del self._rooms[room]
+            else:
+                for r_name, members in list(self._rooms.items()):
+                    members.discard(websocket)
+                    if not members:
+                        del self._rooms[r_name]
+
+    async def send_personal_message(self, message: Any, websocket: Any) -> None:
+        """Send a message directly to a single connected WebSocket client.
+
+        Args:
+            message: Text, dict, or JSON-serializable payload.
+            websocket: Target WebSocket connection.
+        """
+        if isinstance(message, str):
+            await websocket.send_text(message)
+        elif isinstance(message, bytes):
+            await websocket.send_bytes(message)
+        else:
+            await websocket.send_json(message)
+
+    async def broadcast(self, message: Any, room: str | None = None) -> None:
+        """Broadcast a message to all connected clients or a specific room.
+
+        Args:
+            message: Text, dict, or JSON-serializable payload.
+            room: Optional room identifier. If None, broadcasts to all active connections.
+        """
+        async with self._lock:
+            targets = list(
+                self._rooms.get(room, set()) if room else self._active_connections
+            )
+
+        for connection in targets:
+            try:
+                if isinstance(message, str):
+                    await connection.send_text(message)
+                elif isinstance(message, bytes):
+                    await connection.send_bytes(message)
+                else:
+                    await connection.send_json(message)
+            except Exception:
+                await self.disconnect(connection, room)
+
+    @property
+    def active_connections_count(self) -> int:
+        """Return total count of active WebSocket connections."""
+        return len(self._active_connections)
+
+    def room_members_count(self, room: str) -> int:
+        """Return count of active connections in a specific room."""
+        return len(self._rooms.get(room, set()))
+
+
+class WebSocketCqrsBridge:
+    """Dispatches inbound WebSocket JSON payloads into CQRS ExecutionPipeline.
+
+    Notes/Architectural Intent:
+        Bridges real-time bidirectional WebSocket sessions to domain Commands and Queries,
+        returning execution results over the socket.
+    """
+
+    def __init__(
+        self,
+        pipeline: ExecutionPipeline,
+        manager: WebSocketConnectionManager | None = None,
+    ) -> None:
+        """Initialize WebSocketCqrsBridge.
+
+        Args:
+            pipeline: CQRS ExecutionPipeline instance.
+            manager: Optional WebSocketConnectionManager instance.
+        """
+        self.pipeline = pipeline
+        self.manager = manager or WebSocketConnectionManager()
+        self._message_types: dict[str, type[Command | Query]] = {}
+
+    def register_type(self, type_name: str, message_cls: type[Command | Query]) -> None:
+        """Register a mapping from message type tag to Command/Query model.
+
+        Args:
+            type_name: String discriminator (e.g. 'CreateTask', 'GetStatus').
+            message_cls: Model class to instantiate from payload.
+        """
+        self._message_types[type_name] = message_cls
+
+    async def handle_connection(
+        self,
+        websocket: WebSocket,
+        room: str | None = None,
+        on_message: Callable[[Any], Any] | None = None,
+    ) -> None:
+        """Manage the lifecycle of a WebSocket connection dispatching CQRS messages.
+
+        Args:
+            websocket: Connected WebSocket.
+            room: Optional room to join.
+            on_message: Optional custom callback invoked per processed message.
+        """
+        await self.manager.connect(websocket, room=room)
+        try:
+            while True:
+                data = await websocket.receive_text()
+                try:
+                    payload = json.loads(data)
+                except json.JSONDecodeError:
+                    await websocket.send_json(
+                        {"status": "error", "error": "Invalid JSON payload"}
+                    )
+                    continue
+
+                type_tag = payload.get("type")
+                if not type_tag or type_tag not in self._message_types:
+                    await websocket.send_json(
+                        {
+                            "status": "error",
+                            "error": f"Unknown message type: {type_tag}",
+                        }
+                    )
+                    continue
+
+                msg_cls = self._message_types[type_tag]
+                params = payload.get("payload", {})
+                try:
+                    instance = msg_cls(**params)
+                    result = self.pipeline.execute(instance)
+                    if asyncio.iscoroutine(result):
+                        result = await result
+
+                    response = {
+                        "status": "ok",
+                        "type": type_tag,
+                        "data": result
+                        if isinstance(result, (dict, list, str, int, float, bool))
+                        else str(result),
+                    }
+                    await websocket.send_json(response)
+                    if on_message:
+                        cb_res = on_message(result)
+                        if asyncio.iscoroutine(cb_res):
+                            await cb_res
+                except Exception as exc:
+                    await websocket.send_json(
+                        {
+                            "status": "error",
+                            "type": type_tag,
+                            "error": str(exc),
+                        }
+                    )
+        except WebSocketDisconnect:
+            await self.manager.disconnect(websocket, room=room)
+
+
+__all__ = [
+    "WebSocketConnectionManager",
+    "WebSocketCqrsBridge",
+]

{hexastack_fastapi-0.2.0/src/hexastack_fastapi/infra → hexastack_fastapi-0.3.0/src/hexastack_fastapi/domain}/config.py

@@ -1,8 +1,5 @@
 from pydantic import BaseModel, Field
 
-from hexastack_core.infra.decorators import config_section
-from hexastack_core.infra.registries.config import ConfigRegistry
-
 
 class CorsConfig(BaseModel):
     """Configuration schema for Cross-Origin Resource Sharing (CORS).
@@ -74,7 +71,7 @@ class ZensicalDocsConfig(BaseModel):
 
     Notes/Architectural Intent:
         Controls automatic mounting of Zensical static documentation site.
-        Default mount path is `/guide` to prevent collision with OpenAPI Swagger UI at `/docs`.
+        Default mount path is  to prevent collision with OpenAPI Swagger UI at .
     """
 
     enable: bool = Field(default=False)
@@ -82,7 +79,6 @@ class ZensicalDocsConfig(BaseModel):
     site_dir: str = Field(default="site")
 
 
-@config_section("fastapi")
 class HexastackFastApiConfig(BaseModel):
     """Configuration schema for FastAPI HTTP presentation adapter.
 
@@ -114,22 +110,6 @@ __all__ = [
     "HealthConfig",
     "HexastackFastApiConfig",
     "RateLimitConfig",
-    "register_fastapi_config",
     "RequestLoggingConfig",
     "ZensicalDocsConfig",
 ]
-
-
-def register_fastapi_config(registry: ConfigRegistry) -> None:
-    """Register FastAPI configuration schema with a ConfigRegistry under 'fastapi'.
-
-    Args:
-        registry: Target ConfigRegistry instance.
-
-    Returns:
-        None.
-
-    Raises:
-        None.
-    """
-    registry.register_config_section("fastapi", HexastackFastApiConfig)

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/infra/__init__.py

@@ -1,3 +1,4 @@
+from hexastack_fastapi.infra.app import create_fastapi_app
 from hexastack_fastapi.infra.autodiscovery import (
     autodiscover_routes,
     create_route_visitor,
@@ -29,6 +30,7 @@ __all__ = [
     "autodiscover_routes",
     "CorrelationHttpMiddleware",
     "CorsConfig",
+    "create_fastapi_app",
     "create_route_visitor",
     "FastApiBootstrapper",
     "HealthConfig",

{hexastack_fastapi-0.2.0/src/hexastack_fastapi/adapters → hexastack_fastapi-0.3.0/src/hexastack_fastapi/infra}/app.py

@@ -9,6 +9,7 @@ from hexastack_core.ports.logging import LoggingPort
 from hexastack_cqrs.infra.pipeline import ExecutionPipeline
 from hexastack_fastapi.adapters.docs import mount_zensical_docs
 from hexastack_fastapi.adapters.health import create_health_router
+from hexastack_fastapi.adapters.metrics import create_metrics_router
 from hexastack_fastapi.infra.config import HexastackFastApiConfig
 from hexastack_fastapi.infra.exception_handlers import (
     register_exception_handlers,
@@ -19,6 +20,9 @@ from hexastack_fastapi.infra.middleware.correlation import (
 from hexastack_fastapi.infra.middleware.logging import (
     RequestLoggingHttpMiddleware,
 )
+from hexastack_fastapi.infra.middleware.metrics import (
+    HttpMetricsMiddleware,
+)
 
 __all__ = [
     "create_fastapi_app",
@@ -122,6 +126,13 @@ def create_fastapi_app(
             container=container,
         )
 
+    # Attach HTTP metrics middleware
+    app.add_middleware(
+        HttpMetricsMiddleware,
+        config=cfg,
+        container=container,
+    )
+
     # Attach correlation middleware
     app.add_middleware(CorrelationHttpMiddleware, config=cfg)
 
@@ -133,6 +144,10 @@ def create_fastapi_app(
         health_router = create_health_router(container=container, config=cfg.health)
         app.include_router(health_router)
 
+    # Mount metrics endpoint
+    metrics_router = create_metrics_router(container=container)
+    app.include_router(metrics_router)
+
     # Mount Zensical documentation site if enabled
     if cfg.zensical.enable:
         mount_zensical_docs(

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/infra/bootstrap.py

@@ -35,8 +35,8 @@ class FastApiBootstrapper(BootstrapperPort):
         Raises:
             None.
         """
-        from hexastack_fastapi.adapters.app import create_fastapi_app
         from hexastack_fastapi.adapters.routing import CqrsRouter
+        from hexastack_fastapi.infra.app import create_fastapi_app
         from hexastack_fastapi.infra.autodiscovery import create_route_visitor
 
         cfg = context.get_config("fastapi", HexastackFastApiConfig)

hexastack_fastapi-0.3.0/src/hexastack_fastapi/infra/config.py

@@ -0,0 +1,31 @@
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_fastapi.domain.config import (
+    CorsConfig,
+    HealthConfig,
+    HexastackFastApiConfig,
+    RateLimitConfig,
+    RequestLoggingConfig,
+    ZensicalDocsConfig,
+)
+
+config_section("fastapi")(HexastackFastApiConfig)
+
+__all__ = [
+    "CorsConfig",
+    "HealthConfig",
+    "HexastackFastApiConfig",
+    "RateLimitConfig",
+    "register_fastapi_config",
+    "RequestLoggingConfig",
+    "ZensicalDocsConfig",
+]
+
+
+def register_fastapi_config(registry: ConfigRegistry) -> None:
+    """Register FastAPI configuration schema with a ConfigRegistry under 'fastapi'.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+    """
+    registry.register_config_section("fastapi", HexastackFastApiConfig)

{hexastack_fastapi-0.2.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/infra/middleware/__init__.py

@@ -4,8 +4,12 @@ from hexastack_fastapi.infra.middleware.correlation import (
 from hexastack_fastapi.infra.middleware.logging import (
     RequestLoggingHttpMiddleware,
 )
+from hexastack_fastapi.infra.middleware.metrics import (
+    HttpMetricsMiddleware,
+)
 
 __all__ = [
     "CorrelationHttpMiddleware",
+    "HttpMetricsMiddleware",
     "RequestLoggingHttpMiddleware",
 ]

hexastack_fastapi-0.3.0/src/hexastack_fastapi/infra/middleware/metrics.py

@@ -0,0 +1,122 @@
+"""ASGI middleware for capturing HTTP request rate and duration metrics."""
+
+from __future__ import annotations
+
+import time
+
+from rodi import Container
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from hexastack_core.domain.feature_flags import EvaluationContext
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_core.ports.metrics import MetricsPort
+from hexastack_fastapi.infra.config import HexastackFastApiConfig
+
+
+class HttpMetricsMiddleware:
+    """ASGI middleware recording HTTP RED (Rate, Errors, Duration) metrics.
+
+    Notes/Architectural Intent:
+        Intercepts incoming HTTP transactions, measures duration, and updates
+        MetricsPort counters and histograms. Guards metric emission via FeatureFlagPort.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        config: HexastackFastApiConfig | None = None,
+        container: Container | None = None,
+        metrics: MetricsPort | None = None,
+        flags: FeatureFlagPort | None = None,
+    ) -> None:
+        """Initialize HTTP metrics middleware.
+
+        Args:
+            app: Downstream ASGI application.
+            config: Optional HexastackFastApiConfig instance.
+            container: Optional rodi Container to dynamically resolve MetricsPort / FeatureFlagPort.
+            metrics: Optional pre-configured MetricsPort instance.
+            flags: Optional FeatureFlagPort instance.
+        """
+        self._app = app
+        self._cfg = config or HexastackFastApiConfig()
+        self._container = container
+        self._metrics = metrics
+        self._flags = flags
+        self._exclude_paths = set(self._cfg.logging.exclude_paths)
+
+    def _get_metrics(self) -> MetricsPort | None:
+        if self._metrics is not None:
+            return self._metrics
+        if self._container is not None and MetricsPort in self._container:
+            return self._container.resolve(MetricsPort)
+        return None
+
+    def _get_flags(self) -> FeatureFlagPort | None:
+        if self._flags is not None:
+            return self._flags
+        if self._container is not None and FeatureFlagPort in self._container:
+            return self._container.resolve(FeatureFlagPort)
+        return None
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Intercept request, measure duration, and record metrics."""
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+
+        path = scope.get("path", "/")
+        if path in self._exclude_paths or path == "/metrics":
+            await self._app(scope, receive, send)
+            return
+
+        metrics = self._get_metrics()
+        if metrics is None:
+            await self._app(scope, receive, send)
+            return
+
+        flags = self._get_flags()
+        if flags is not None:
+            eval_ctx = EvaluationContext.from_current_context()
+            if not flags.is_enabled(
+                "features.metrics.http", default=True, context=eval_ctx
+            ):
+                await self._app(scope, receive, send)
+                return
+
+        method = scope.get("method", "GET")
+        status_code = 500
+        start_time = time.perf_counter()
+
+        async def send_wrapper(message: Message) -> None:
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message.get("status", 500)
+            await send(message)
+
+        try:
+            await self._app(scope, receive, send_wrapper)
+        finally:
+            duration = time.perf_counter() - start_time
+            labels = {
+                "method": method,
+                "path": path,
+                "status_code": str(status_code),
+            }
+            metrics.increment_counter(
+                "http_requests_total",
+                value=1.0,
+                labels=labels,
+                description="Total HTTP requests processed",
+            )
+            metrics.record_histogram(
+                "http_request_duration_seconds",
+                value=duration,
+                labels={"method": method, "path": path},
+                description="HTTP request duration distribution in seconds",
+            )
+
+
+__all__ = [
+    "HttpMetricsMiddleware",
+]