hexastack-fastapi 0.0.0__py3-none-any.whl

hexastack_fastapi/__init__.py

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

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/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

hexastack_fastapi/adapters/db_session.py

@@ -0,0 +1,160 @@
+"""SQLAlchemy session-per-request middleware for FastAPI.
+
+Decoupling strategy:
+    This module depends only on SQLAlchemy (already a transitive dep via hexastack-db)
+    and Starlette (already a direct dep via FastAPI). It never imports from hexastack-db.
+    Session factories are resolved from the DI container by SQLAlchemy type at runtime,
+    so the two packages remain fully independent — the DI container is the only coupling.
+
+Usage:
+    # In your app setup (after bootstrapping both DatabaseBootstrapper + FastApiBootstrapper):
+    from hexastack_fastapi.adapters.db_session import (
+        DbSessionMiddleware,
+        AsyncDbSessionMiddleware,
+    )
+
+    # Sync engine:
+    app.add_middleware(DbSessionMiddleware, session_factory=session_factory)
+
+    # Async engine:
+    app.add_middleware(AsyncDbSessionMiddleware, session_factory=async_session_factory)
+
+    # In a handler or dependency:
+    def my_endpoint(request: Request):
+        session = request.state.db_session   # Session | AsyncSession
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import ASGIApp
+
+
+class DbSessionMiddleware(BaseHTTPMiddleware):
+    """Synchronous SQLAlchemy session-per-request Starlette middleware.
+
+    Notes/Architectural Intent:
+        Creates a new Session for every HTTP request and exposes it as
+        request.state.db_session. The session is always closed in the
+        finally block regardless of response outcome. No commit is issued
+        automatically — handlers own transaction boundaries via UnitOfWork.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_factory: Callable[[], Any],
+    ) -> None:
+        """Initialise with a synchronous sessionmaker callable.
+
+        Args:
+            app: The ASGI application to wrap.
+            session_factory: A callable returning a SQLAlchemy Session
+                (e.g. the sessionmaker instance returned by create_session_factory).
+        """
+        super().__init__(app)
+        self._session_factory = session_factory
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[..., Any]
+    ) -> Response:
+        """Attach a fresh session to each request; close it after response.
+
+        Args:
+            request: Incoming Starlette Request.
+            call_next: Next middleware / route handler in the chain.
+
+        Returns:
+            The HTTP Response from the downstream handler.
+        """
+        session = self._session_factory()
+        request.state.db_session = session
+        try:
+            response = await call_next(request)
+        finally:
+            session.close()
+        return response
+
+
+class AsyncDbSessionMiddleware(BaseHTTPMiddleware):
+    """Asynchronous SQLAlchemy session-per-request Starlette middleware.
+
+    Notes/Architectural Intent:
+        Creates a new AsyncSession for every HTTP request via an async_sessionmaker,
+        exposing it as request.state.db_session. Handlers own commit/rollback via
+        AsyncSqlAlchemyUnitOfWork — this middleware only manages lifecycle (open/close).
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_factory: Callable[[], Any],
+    ) -> None:
+        """Initialise with an async_sessionmaker callable.
+
+        Args:
+            app: The ASGI application to wrap.
+            session_factory: A callable returning an AsyncSession
+                (e.g. the async_sessionmaker returned by create_async_session_factory).
+        """
+        super().__init__(app)
+        self._session_factory = session_factory
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[..., Any]
+    ) -> Response:
+        """Attach a fresh AsyncSession to each request; close it after response.
+
+        Args:
+            request: Incoming Starlette Request.
+            call_next: Next middleware / route handler in the chain.
+
+        Returns:
+            The HTTP Response from the downstream handler.
+        """
+        session = self._session_factory()
+        request.state.db_session = session
+        try:
+            response = await call_next(request)
+        finally:
+            await session.close()
+        return response
+
+
+__all__ = [
+    "add_db_session_middleware",
+    "AsyncDbSessionMiddleware",
+    "DbSessionMiddleware",
+]
+
+
+def add_db_session_middleware(
+    app: Any,
+    session_factory: Callable[[], Any],
+    *,
+    async_mode: bool = False,
+) -> None:
+    """Convenience helper to attach the correct session middleware to a FastAPI app.
+
+    Notes/Architectural Intent:
+        Selects DbSessionMiddleware or AsyncDbSessionMiddleware based on async_mode.
+        Intended to be called from the FastAPI bootstrapper or app factory when
+        a session_factory is present in the DI container.
+
+    Args:
+        app: FastAPI / Starlette application instance.
+        session_factory: Sessionmaker callable (sync or async).
+        async_mode: If True, use AsyncDbSessionMiddleware.
+
+    Returns:
+        None.
+    """
+    if async_mode:
+        app.add_middleware(AsyncDbSessionMiddleware, session_factory=session_factory)
+    else:
+        app.add_middleware(DbSessionMiddleware, session_factory=session_factory)

hexastack_fastapi/adapters/dependencies.py

@@ -0,0 +1,190 @@
+from typing import Any
+
+from fastapi import HTTPException, Request, status
+from rodi import Container
+
+from hexastack_core.adapters.feature_flags.config import ConfigFeatureFlagAdapter
+from hexastack_core.adapters.feature_flags.in_memory import InMemoryFeatureFlagAdapter
+from hexastack_core.domain.exceptions import (
+    DependencyResolutionError,
+    MissingDependencyError,
+)
+from hexastack_core.domain.feature_flags import EvaluationContext
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+__all__ = [
+    "check_openapi_conformance",
+    "create_test_client",
+    "get_container",
+    "get_feature_flags",
+    "get_pipeline",
+    "require_feature",
+]
+
+
+def check_openapi_conformance(
+    app: Any,
+    *,
+    schema_url: str = "/openapi.json",
+    validate_schema: bool = True,
+) -> None:
+    """Run Schemathesis contract conformance and schema validation checks against a FastAPI app.
+
+    Notes/Architectural Intent:
+        Automatically tests that all exposed FastAPI endpoints conform to the
+        derived OpenAPI schema, validate properly, and have complete route definitions.
+
+    Args:
+        app: The FastAPI application instance.
+        schema_url: URL path where the OpenAPI JSON is served (defaults to '/openapi.json').
+        validate_schema: Whether to validate the OpenAPI specification structure itself.
+
+    Raises:
+        MissingDependencyError: If `schemathesis` is not installed.
+        AssertionError: If any API contract violation or unhandled error is detected.
+    """
+    try:
+        import schemathesis
+    except ImportError as e:
+        raise MissingDependencyError(
+            "schemathesis is required for check_openapi_conformance. "
+            "Install with 'pip install schemathesis' or 'pip install hexastack[testing]'."
+        ) from e
+
+    schema = schemathesis.openapi.from_asgi(schema_url, app)
+
+    if validate_schema:
+        schema.validate()
+
+
+def create_test_client(
+    app: Any,
+    *,
+    flags: dict[str, Any] | None = None,
+    **test_client_kwargs: Any,
+) -> Any:
+    """Create a FastAPI TestClient configured with an in-memory feature flag adapter.
+
+    Args:
+        app: The FastAPI application instance.
+        flags: Optional initial flag states.
+        **test_client_kwargs: Extra keyword arguments forwarded to TestClient.
+
+    Returns:
+        Configured starlette / fastapi TestClient.
+    """
+    from fastapi.testclient import TestClient
+
+    if flags is not None:
+        container = getattr(app.state, "container", None)
+        flags_adapter = InMemoryFeatureFlagAdapter(flags=flags)
+        if container is not None:
+            container.add_instance(flags_adapter, declared_class=FeatureFlagPort)
+
+    return TestClient(app, **test_client_kwargs)
+
+
+def get_container(request: Request) -> Container:
+    """FastAPI dependency provider resolving the active rodi Container instance.
+
+    Notes/Architectural Intent:
+        Enables endpoint routes to inject and resolve registered domain ports and services.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        The rodi Container attached to the application state.
+
+    Raises:
+        DependencyResolutionError: If Container has not been attached to app.state.
+    """
+    container = getattr(request.app.state, "container", None)
+    if container is None or not isinstance(container, Container):
+        raise DependencyResolutionError(
+            "rodi.Container is not configured on request.app.state.container."
+        )
+    return container
+
+
+def get_feature_flags(request: Request) -> FeatureFlagPort:
+    """FastAPI dependency provider resolving the active FeatureFlagPort instance.
+
+    Notes/Architectural Intent:
+        Retrieves the registered FeatureFlagPort from the application container or
+        falls back to ConfigFeatureFlagAdapter.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        The FeatureFlagPort instance.
+    """
+    container = getattr(request.app.state, "container", None)
+    if isinstance(container, Container) and FeatureFlagPort in container:
+        return container.resolve(FeatureFlagPort)
+    return ConfigFeatureFlagAdapter()
+
+
+def get_pipeline(request: Request) -> ExecutionPipeline:
+    """FastAPI dependency provider resolving the active ExecutionPipeline instance.
+
+    Notes/Architectural Intent:
+        Enables route handlers to execute CQRS commands and queries through the unified pipeline.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        The ExecutionPipeline instance attached to application state or resolved from DI.
+
+    Raises:
+        DependencyResolutionError: If ExecutionPipeline cannot be resolved from application state or container.
+    """
+    pipeline = getattr(request.app.state, "pipeline", None)
+    if isinstance(pipeline, ExecutionPipeline):
+        return pipeline
+
+    container = getattr(request.app.state, "container", None)
+    if isinstance(container, Container) and ExecutionPipeline in container:
+        return container.resolve(ExecutionPipeline)
+
+    raise DependencyResolutionError(
+        "ExecutionPipeline is not available on request.app.state.pipeline or container."
+    )
+
+
+def require_feature(
+    flag_key: str,
+    *,
+    default: bool = False,
+    status_code: int = status.HTTP_404_NOT_FOUND,
+    detail: str | None = None,
+) -> Any:
+    """Create a FastAPI dependency that enforces a feature flag is enabled.
+
+    Notes/Architectural Intent:
+        Evaluates the feature flag dynamically against ambient UserContext / request state.
+        If disabled, raises an HTTPException (default 404 Not Found) to cleanly hide or gate routes.
+
+    Args:
+        flag_key: Unique identifier of the feature flag to check.
+        default: Fallback boolean value if flag is not explicitly configured.
+        status_code: HTTP status code to return when disabled (defaults to 404).
+        detail: Optional error detail message.
+
+    Returns:
+        A FastAPI dependency callable.
+    """
+
+    async def _dependency(request: Request) -> None:
+        flags = get_feature_flags(request)
+        eval_ctx = EvaluationContext.from_current_context()
+        if not flags.is_enabled(flag_key, default=default, context=eval_ctx):
+            raise HTTPException(
+                status_code=status_code,
+                detail=detail or f"Feature '{flag_key}' is disabled.",
+            )
+
+    return _dependency

hexastack_fastapi/adapters/docs.py

@@ -0,0 +1,80 @@
+"""Zensical and static documentation mounting adapter for FastAPI.
+
+Notes/Architectural Intent:
+    Provides a declarative helper to serve pre-built Zensical or static HTML documentation
+    directly alongside FastAPI API routes:
+    1. Supports configurable mount paths (e.g. `/guide`, `/docs-site`, `/handbook`) to avoid
+       conflicts with FastAPI's native OpenAPI Swagger UI (`/docs`) and ReDoc (`/redoc`).
+    2. Allows custom fallback and index.html serving with static directory validation.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class DocumentationNotFoundError(HexastackError):
+    """Raised when configured documentation directory does not exist."""
+
+
+def mount_zensical_docs(
+    app: FastAPI,
+    path: str = "/guide",
+    site_dir: str | Path = "site",
+    name: str = "zensical-docs",
+    html: bool = True,
+) -> None:
+    """Mount a pre-built Zensical static documentation site onto a FastAPI application.
+
+    Notes/Architectural Intent:
+        FastAPI defaults OpenAPI Swagger UI to `/docs` and ReDoc to `/redoc`.
+        Mounting Zensical under a configurable path (defaulting to `/guide`) enables
+        teams to serve complete developer guides, architecture diagrams, and tutorials
+        from the exact same microservice process without routing collisions.
+
+    Args:
+        app: Target FastAPI application.
+        path: URL prefix where documentation will be served (e.g. "/guide" or "/manual").
+        site_dir: Path to directory containing built HTML files (typically "site" from `zensical build`).
+        name: Internal ASGI mount name.
+        html: Enable HTML mode (auto-resolving directory paths to index.html).
+
+    Raises:
+        DocumentationNotFoundError: If site_dir does not exist and is required.
+    """
+    resolved_dir = Path(site_dir).resolve()
+
+    if not resolved_dir.exists():
+        if os.environ.get("ENVIRONMENT", "").lower() in ("prod", "production"):
+            raise DocumentationNotFoundError(
+                f"Zensical documentation directory '{resolved_dir}' not found. "
+                f"Run 'zensical build' before launching the production server."
+            )
+        # In development/test mode, create the directory if missing to allow graceful startup
+        resolved_dir.mkdir(parents=True, exist_ok=True)
+        index_file = resolved_dir / "index.html"
+        if not index_file.exists():
+            index_file.write_text(
+                "<!DOCTYPE html><html><body><h1>Documentation building...</h1>"
+                "<p>Run <code>zensical build</code> to compile docs.</p></body></html>",
+                encoding="utf-8",
+            )
+
+    normalized_path = "/" + path.strip("/")
+    app.mount(
+        normalized_path,
+        StaticFiles(directory=str(resolved_dir), html=html),
+        name=name,
+    )
+
+
+__all__ = [
+    "DocumentationNotFoundError",
+    "mount_zensical_docs",
+]

hexastack_fastapi/adapters/health.py

@@ -0,0 +1,62 @@
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter
+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",
+]
+
+
+def create_health_router(
+    container: Container | None = None,
+    config: HealthConfig | None = None,
+) -> 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.
+
+    Args:
+        container: Optional rodi Container instance to check dependency health.
+        config: Optional HealthConfig specifying custom URL paths.
+
+    Returns:
+        APIRouter mounted with health endpoints.
+
+    Raises:
+        None.
+    """
+    cfg = config or HealthConfig()
+    router = APIRouter(tags=["Health"])
+
+    @router.get(cfg.health_path, summary="Liveness Probe")
+    async def liveness() -> dict[str, Any]:
+        return {
+            "status": "ok",
+            "timestamp": datetime.now(tz=UTC).isoformat(),
+            "correlation_id": get_correlation_id(),
+        }
+
+    @router.get(cfg.ready_path, summary="Readiness Probe")
+    async def readiness() -> JSONResponse:
+        checks: dict[str, str] = {
+            "container": "ok" if container is not None else "unconfigured",
+        }
+        status_ok = all(v == "ok" for v in checks.values())
+        payload: dict[str, Any] = {
+            "status": "ready" if status_ok else "unhealthy",
+            "timestamp": datetime.now(tz=UTC).isoformat(),
+            "correlation_id": get_correlation_id(),
+            "checks": checks,
+        }
+        status_code = 200 if status_ok else 503
+        return JSONResponse(status_code=status_code, content=payload)
+
+    return router