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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexastack-fastapi
-Version: 0.1.0
+Version: 0.3.0
 Summary: FastAPI presentation adapter for Hexastack
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -10,12 +10,15 @@ Requires-Dist: hexastack-core
 Requires-Dist: hexastack-cqrs
 Requires-Dist: hexastack-auth ; extra == 'auth'
 Requires-Dist: zensical>=0.0.56 ; extra == 'docs'
+Requires-Dist: limits>=3.14.0 ; extra == 'ratelimit'
+Requires-Dist: slowapi>=0.1.9 ; extra == 'ratelimit'
 Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
 Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
 Requires-Dist: nicegui>=2.0.0 ; extra == 'ui'
 Requires-Python: >=3.13
 Provides-Extra: auth
 Provides-Extra: docs
+Provides-Extra: ratelimit
 Provides-Extra: testing
 Provides-Extra: ui
 Description-Content-Type: text/markdown
@@ -37,39 +40,46 @@ 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) |
-| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `RouteMetadata` |
-| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature` |
+| **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` |
 | **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
 | **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.1.0 → hexastack_fastapi-0.3.0}/README.md

@@ -15,39 +15,46 @@
 ## 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) |
-| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `RouteMetadata` |
-| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature` |
+| **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` |
 | **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
 | **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.1.0 → hexastack_fastapi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.1.0"
+version = "0.3.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -18,6 +18,10 @@ email = "dopplereffect.us@gmail.com"
 [project.optional-dependencies]
 auth = ["hexastack-auth"]
 docs = ["zensical>=0.0.56"]
+ratelimit = [
+    "limits>=3.14.0",
+    "slowapi>=0.1.9",
+]
 testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
@@ -42,3 +46,24 @@ workspace = true
 
 [tool.importlinter]
 root_packages = ["hexastack_fastapi"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_fastapi"]
+layers = [
+    "infra",
+    "adapters",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.adapters"]
+forbidden_modules = ["hexastack_fastapi.testing"]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.infra"]
+forbidden_modules = ["hexastack_fastapi.testing"]

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

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.1.0"
+version = "0.3.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -21,6 +21,10 @@ auth = [
 docs = [
     "zensical>=0.0.56",
 ]
+ratelimit = [
+    "limits>=3.14.0",
+    "slowapi>=0.1.9",
+]
 testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
@@ -29,6 +33,7 @@ ui = [
     "nicegui>=2.0.0",
 ]
 
+
 [project.entry-points."hexastack.bootstrappers"]
 fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"
 
@@ -43,3 +48,28 @@ hexastack-cqrs = { workspace = true }
 
 [tool.importlinter]
 root_packages = ["hexastack_fastapi"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_fastapi"]
+layers = [
+    "infra",
+    "adapters",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.adapters"]
+forbidden_modules = [
+    "hexastack_fastapi.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.infra"]
+forbidden_modules = [
+    "hexastack_fastapi.testing",
+]

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

@@ -1,18 +1,30 @@
-from hexastack_fastapi.adapters.app import create_fastapi_app
 from hexastack_fastapi.adapters.dependencies import (
     check_openapi_conformance,
     create_test_client,
     get_container,
     get_feature_flags,
     get_pipeline,
+    get_rate_limiter,
     require_feature,
+    require_rate_limit,
 )
 from hexastack_fastapi.adapters.docs import (
     DocumentationNotFoundError,
     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,
+    get_user_or_ip_key,
+    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,
@@ -20,22 +32,36 @@ 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",
+    "get_rate_limiter",
+    "get_remote_address",
+    "get_user_or_ip_key",
     "mount_devtools_dashboard",
     "mount_ui_app",
     "mount_zensical_docs",
+    "rate_limit",
     "require_feature",
+    "require_rate_limit",
+    "ServerSentEvent",
+    "SlowapiRateLimiterAdapter",
     "ui_page",
+    "WebSocketConnectionManager",
+    "WebSocketCqrsBridge",
 ]

{hexastack_fastapi-0.1.0 → hexastack_fastapi-0.3.0}/src/hexastack_fastapi/adapters/dependencies.py

@@ -19,7 +19,9 @@ __all__ = [
     "get_container",
     "get_feature_flags",
     "get_pipeline",
+    "get_rate_limiter",
     "require_feature",
+    "require_rate_limit",
 ]
 
 
@@ -188,3 +190,64 @@ def require_feature(
             )
 
     return _dependency
+
+
+def get_rate_limiter(request: Request) -> Any | None:
+    """FastAPI dependency resolving the registered RateLimiterPort instance if available.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        RateLimiterPort instance from app.state or DI container, or None.
+    """
+    limiter = getattr(request.app.state, "rate_limiter", None)
+    if limiter is not None:
+        return limiter
+
+    container = getattr(request.app.state, "container", None)
+    if isinstance(container, Container):
+        from hexastack_core.ports.ratelimit import RateLimiterPort
+
+        if RateLimiterPort in container:
+            return container.resolve(RateLimiterPort)
+    return None
+
+
+def require_rate_limit(
+    limit: str,
+    *,
+    key_func: Any | None = None,
+    detail: str | None = None,
+) -> Any:
+    """Create a FastAPI dependency that enforces rate limiting on an endpoint.
+
+    Notes/Architectural Intent:
+        Checks rate limit against registered RateLimiterPort. If quota is exceeded,
+        raises an HTTPException with status 429 and Retry-After header.
+
+    Args:
+        limit: Rate limit specification string (e.g. '10/minute').
+        key_func: Optional callable to extract bucket key from request.
+        detail: Optional error message string.
+
+    Returns:
+        A FastAPI dependency callable.
+    """
+    from hexastack_fastapi.adapters.ratelimit import get_user_or_ip_key
+
+    key_extractor = key_func or get_user_or_ip_key
+
+    async def _dependency(request: Request) -> None:
+        limiter = get_rate_limiter(request)
+        if limiter is not None:
+            key = key_extractor(request)
+            if not limiter.hit(key, limit):
+                reset_sec = limiter.get_reset_window(key, limit)
+                raise HTTPException(
+                    status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                    detail=detail or f"Rate limit exceeded: {limit}.",
+                    headers={"Retry-After": str(reset_sec)},
+                )
+
+    return _dependency

{hexastack_fastapi-0.1.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",
+]