hexastack-fastapi 0.0.0__tar.gz

hexastack_fastapi-0.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.3
+Name: hexastack-fastapi
+Version: 0.0.0
+Summary: FastAPI presentation adapter for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: hexastack-auth ; extra == 'auth'
+Requires-Dist: zensical>=0.0.56 ; extra == 'docs'
+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: testing
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+# hexastack-fastapi
+
+> FastAPI presentation adapter for Hexastack: automatic CQRS routing, database session middleware, exception mapping, and health check endpoints.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 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(...)`).
+- **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.
+- **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
+```
+
+### 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` |
+| **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
+| **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
+| **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
+| **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
+| **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
+graph TD
+    subgraph ClientRequests ["Client HTTP Inbound"]
+        HTTP["HTTP Client Requests"]
+    end
+
+    subgraph FastApiLayer ["hexastack-fastapi"]
+        APP["FastAPI Application"]
+        MW["Middleware (Correlation, HTTP Logging, DB Session)"]
+        ROUTER["CQRS Route Dispatcher"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph DecoupledProviders ["Decoupled Providers (via DI)"]
+        DB_FACTORY["sessionmaker / async_sessionmaker (from hexastack-db)"]
+        LOG_PORT["LoggerPort (from hexastack-logging)"]
+    end
+
+    HTTP --> APP
+    APP --> MW
+    MW --> ROUTER
+    ROUTER -->|dispatches to| CBUS
+    ROUTER -->|dispatches to| QBUS
+
+    MW -. consumes session factory from DI .-> DB_FACTORY
+    MW -. consumes LoggerPort from DI .-> LOG_PORT
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, core ports, exception registry, and context propagation.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `fastapi>=0.141.1`: Web framework and ASGI routing.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Zero-Dependency DB Session Management**: `DbSessionMiddleware` dynamically resolves SQLAlchemy `sessionmaker` from DI without directly importing `hexastack-db`.
+- **Telemetry Integration**: `HttpLoggingMiddleware` outputs structured request telemetry through `LoggerPort`.
+- **Exception Mapping**: Registers global exception handlers translating core domain errors into standard HTTP error responses.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-fastapi
+
+# With Uvicorn development server
+pip install "hexastack-fastapi[web]"  # or: pip install "hexastack[web]"
+
+# Via umbrella package
+pip install "hexastack[fastapi]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.fastapi]
+title = "Hexastack API"
+version = "1.0.0"
+docs_url = "/docs"
+openapi_url = "/openapi.json"
+cors_origins = ["*"]
+enable_correlation_header = true
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from fastapi.testclient import TestClient
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_fastapi.adapters.app import create_app
+
+
+@dataclass(frozen=True)
+class GetGreetingQuery(Query):
+    name: str
+
+
+@query_handler(GetGreetingQuery)
+class GetGreetingHandler:
+    def __call__(self, qry: GetGreetingQuery) -> dict:
+        return {"message": f"Hello, {qry.name}!"}
+
+
+runtime = bootstrap(packages_to_scan=[__name__])
+app = create_app(runtime)
+
+client = TestClient(app)
+response = client.get("/health")
+print(response.json())  # {"status": "healthy"}
+```

hexastack_fastapi-0.0.0/README.md

@@ -0,0 +1,148 @@
+# hexastack-fastapi
+
+> FastAPI presentation adapter for Hexastack: automatic CQRS routing, database session middleware, exception mapping, and health check endpoints.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 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(...)`).
+- **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.
+- **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
+```
+
+### 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` |
+| **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
+| **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
+| **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
+| **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
+| **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
+graph TD
+    subgraph ClientRequests ["Client HTTP Inbound"]
+        HTTP["HTTP Client Requests"]
+    end
+
+    subgraph FastApiLayer ["hexastack-fastapi"]
+        APP["FastAPI Application"]
+        MW["Middleware (Correlation, HTTP Logging, DB Session)"]
+        ROUTER["CQRS Route Dispatcher"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph DecoupledProviders ["Decoupled Providers (via DI)"]
+        DB_FACTORY["sessionmaker / async_sessionmaker (from hexastack-db)"]
+        LOG_PORT["LoggerPort (from hexastack-logging)"]
+    end
+
+    HTTP --> APP
+    APP --> MW
+    MW --> ROUTER
+    ROUTER -->|dispatches to| CBUS
+    ROUTER -->|dispatches to| QBUS
+
+    MW -. consumes session factory from DI .-> DB_FACTORY
+    MW -. consumes LoggerPort from DI .-> LOG_PORT
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, core ports, exception registry, and context propagation.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `fastapi>=0.141.1`: Web framework and ASGI routing.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Zero-Dependency DB Session Management**: `DbSessionMiddleware` dynamically resolves SQLAlchemy `sessionmaker` from DI without directly importing `hexastack-db`.
+- **Telemetry Integration**: `HttpLoggingMiddleware` outputs structured request telemetry through `LoggerPort`.
+- **Exception Mapping**: Registers global exception handlers translating core domain errors into standard HTTP error responses.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-fastapi
+
+# With Uvicorn development server
+pip install "hexastack-fastapi[web]"  # or: pip install "hexastack[web]"
+
+# Via umbrella package
+pip install "hexastack[fastapi]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.fastapi]
+title = "Hexastack API"
+version = "1.0.0"
+docs_url = "/docs"
+openapi_url = "/openapi.json"
+cors_origins = ["*"]
+enable_correlation_header = true
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from fastapi.testclient import TestClient
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_fastapi.adapters.app import create_app
+
+
+@dataclass(frozen=True)
+class GetGreetingQuery(Query):
+    name: str
+
+
+@query_handler(GetGreetingQuery)
+class GetGreetingHandler:
+    def __call__(self, qry: GetGreetingQuery) -> dict:
+        return {"message": f"Hello, {qry.name}!"}
+
+
+runtime = bootstrap(packages_to_scan=[__name__])
+app = create_app(runtime)
+
+client = TestClient(app)
+response = client.get("/health")
+print(response.json())  # {"status": "healthy"}
+```

hexastack_fastapi-0.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "hexastack-fastapi"
+version = "0.0.0"
+description = "FastAPI presentation adapter for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.141.1",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+auth = ["hexastack-auth"]
+docs = ["zensical>=0.0.56"]
+testing = [
+    "playwright>=1.49.0",
+    "schemathesis>=3.39.0",
+]
+ui = ["nicegui>=2.0.0"]
+
+[project.entry-points."hexastack.bootstrappers"]
+fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-auth]
+workspace = true
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_fastapi"]

hexastack_fastapi-0.0.0/pyproject.toml.orig

@@ -0,0 +1,44 @@
+[project]
+name = "hexastack-fastapi"
+version = "0.0.0"
+description = "FastAPI presentation adapter for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.141.1",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[project.optional-dependencies]
+auth = [
+    "hexastack-auth",
+]
+docs = [
+    "zensical>=0.0.56",
+]
+testing = [
+    "playwright>=1.49.0",
+    "schemathesis>=3.39.0",
+]
+ui = [
+    "nicegui>=2.0.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-auth = { workspace = true }
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_fastapi"]

hexastack_fastapi-0.0.0/src/hexastack_fastapi/__init__.py

@@ -0,0 +1,6 @@
+from hexastack_fastapi import adapters, infra
+
+__all__ = [
+    "adapters",
+    "infra",
+]

hexastack_fastapi-0.0.0/src/hexastack_fastapi/adapters/__init__.py

@@ -0,0 +1,41 @@
+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,
+    require_feature,
+)
+from hexastack_fastapi.adapters.docs import (
+    DocumentationNotFoundError,
+    mount_zensical_docs,
+)
+from hexastack_fastapi.adapters.health import create_health_router
+from hexastack_fastapi.adapters.routing import CqrsRouter
+from hexastack_fastapi.adapters.ui import (
+    dispatch_command,
+    dispatch_query,
+    mount_devtools_dashboard,
+    mount_ui_app,
+    ui_page,
+)
+
+__all__ = [
+    "check_openapi_conformance",
+    "CqrsRouter",
+    "create_fastapi_app",
+    "create_health_router",
+    "create_test_client",
+    "dispatch_command",
+    "dispatch_query",
+    "DocumentationNotFoundError",
+    "get_container",
+    "get_feature_flags",
+    "get_pipeline",
+    "mount_devtools_dashboard",
+    "mount_ui_app",
+    "mount_zensical_docs",
+    "require_feature",
+    "ui_page",
+]

hexastack_fastapi-0.0.0/src/hexastack_fastapi/adapters/app.py

@@ -0,0 +1,118 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from rodi import Container
+
+from hexastack_core.infra.registries.exception import ExceptionRegistry
+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.infra.config import HexastackFastApiConfig
+from hexastack_fastapi.infra.exception_handlers import (
+    register_exception_handlers,
+)
+from hexastack_fastapi.infra.middleware.correlation import (
+    CorrelationHttpMiddleware,
+)
+from hexastack_fastapi.infra.middleware.logging import (
+    RequestLoggingHttpMiddleware,
+)
+
+__all__ = [
+    "create_fastapi_app",
+]
+
+
+def create_fastapi_app(
+    config: HexastackFastApiConfig | None = None,
+    container: Container | None = None,
+    pipeline: ExecutionPipeline | None = None,
+    exception_registry: ExceptionRegistry | None = None,
+) -> FastAPI:
+    """Factory creating and configuring a FastAPI application integrated with Hexastack.
+
+    Notes/Architectural Intent:
+        Assembles FastAPI instance with OpenAPI documentation metadata, CORS middleware,
+        Correlation ID ASGI middleware, access logging, health check probes, Zensical docs mounting,
+        unified exception mapping, and DI container lifecycle management.
+
+    Args:
+        config: Optional HexastackFastApiConfig instance.
+        container: Optional rodi Container instance.
+        pipeline: Optional ExecutionPipeline instance.
+        exception_registry: Optional ExceptionRegistry for domain error mapping.
+
+    Returns:
+        Configured FastAPI application instance.
+
+    Raises:
+        None.
+    """
+    cfg = config or HexastackFastApiConfig()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        # Teardown background resources
+        if container is not None and LoggingPort in container:
+            logger = container.resolve(LoggingPort)
+            close_fn = getattr(logger, "close", None)
+            if callable(close_fn):
+                close_fn()
+
+    app = FastAPI(
+        title=cfg.title,
+        version=cfg.version,
+        description=cfg.description,
+        docs_url=cfg.docs_url,
+        redoc_url=cfg.redoc_url,
+        openapi_url=cfg.openapi_url,
+        lifespan=lifespan,
+    )
+
+    # Attach container and pipeline to application state
+    if container is not None:
+        app.state.container = container
+    if pipeline is not None:
+        app.state.pipeline = pipeline
+
+    # Attach CORS middleware if enabled
+    if cfg.cors.enable:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.cors.allow_origins,
+            allow_credentials=cfg.cors.allow_credentials,
+            allow_methods=cfg.cors.allow_methods,
+            allow_headers=cfg.cors.allow_headers,
+        )
+
+    # Attach request logging middleware if enabled
+    if cfg.logging.enable:
+        app.add_middleware(
+            RequestLoggingHttpMiddleware,
+            config=cfg,
+            container=container,
+        )
+
+    # Attach correlation middleware
+    app.add_middleware(CorrelationHttpMiddleware, config=cfg)
+
+    # Register unified exception handlers
+    register_exception_handlers(app, exception_registry=exception_registry)
+
+    # Mount health and readiness endpoints if enabled
+    if cfg.health.enable:
+        health_router = create_health_router(container=container, config=cfg.health)
+        app.include_router(health_router)
+
+    # Mount Zensical documentation site if enabled
+    if cfg.zensical.enable:
+        mount_zensical_docs(
+            app=app,
+            path=cfg.zensical.path,
+            site_dir=cfg.zensical.site_dir,
+        )
+
+    return app