hexastack-fastapi 0.0.0__py3-none-any.whl

hexastack_fastapi/infra/__init__.py

@@ -0,0 +1,41 @@
+from hexastack_fastapi.infra.autodiscovery import (
+    autodiscover_routes,
+    create_route_visitor,
+)
+from hexastack_fastapi.infra.bootstrap import FastApiBootstrapper
+from hexastack_fastapi.infra.config import (
+    CorsConfig,
+    HealthConfig,
+    HexastackFastApiConfig,
+    RequestLoggingConfig,
+    register_fastapi_config,
+)
+from hexastack_fastapi.infra.decorators import (
+    RouteMetadata,
+    api_command,
+    api_query,
+)
+from hexastack_fastapi.infra.exception_handlers import (
+    register_exception_handlers,
+)
+from hexastack_fastapi.infra.middleware import (
+    CorrelationHttpMiddleware,
+    RequestLoggingHttpMiddleware,
+)
+
+__all__ = [
+    "api_command",
+    "api_query",
+    "autodiscover_routes",
+    "CorrelationHttpMiddleware",
+    "CorsConfig",
+    "create_route_visitor",
+    "FastApiBootstrapper",
+    "HealthConfig",
+    "HexastackFastApiConfig",
+    "register_exception_handlers",
+    "register_fastapi_config",
+    "RequestLoggingConfig",
+    "RequestLoggingHttpMiddleware",
+    "RouteMetadata",
+]

hexastack_fastapi/infra/autodiscovery.py

@@ -0,0 +1,103 @@
+import inspect
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+from fastapi import FastAPI
+
+from hexastack_core.domain import Command, Query
+from hexastack_core.infra.autodiscovery import (
+    DiscoveryVisitor,
+    scan_modules,
+)
+from hexastack_fastapi.adapters.routing import CqrsRouter
+from hexastack_fastapi.infra.decorators import (
+    _ROUTE_METADATA_ATTR,
+    RouteMetadata,
+)
+
+__all__ = [
+    "autodiscover_routes",
+    "create_route_visitor",
+]
+
+
+def autodiscover_routes(
+    app: FastAPI,
+    packages_to_scan: Sequence[str | ModuleType],
+    router: CqrsRouter | None = None,
+) -> CqrsRouter:
+    """Automatically discover decorated routes from packages and attach them to a FastAPI application.
+
+    Args:
+        app: Target FastAPI application instance.
+        packages_to_scan: Sequence of package names or module objects to inspect.
+        router: Optional CqrsRouter instance to populate and mount.
+
+    Returns:
+        The mounted CqrsRouter instance.
+
+    Raises:
+        None.
+    """
+    target_router = router or CqrsRouter()
+    visitor = create_route_visitor(target_router)
+    scan_modules(packages_to_scan, [visitor])
+    app.include_router(target_router)
+    return target_router
+
+
+def create_route_visitor(router: CqrsRouter) -> DiscoveryVisitor:
+    """Create a DiscoveryVisitor callback for single-pass HTTP route registration.
+
+    Notes/Architectural Intent:
+        Inspects discovered classes for @api_command and @api_query metadata,
+        mounting them onto the supplied CqrsRouter without duplicate reflection loops.
+
+    Args:
+        router: Target CqrsRouter instance.
+
+    Returns:
+        DiscoveryVisitor callable accepting (member, module).
+
+    Raises:
+        None.
+    """
+
+    def visitor(obj: Any, module: ModuleType) -> None:
+        if not inspect.isclass(obj):
+            return
+
+        meta: RouteMetadata | None = getattr(obj, _ROUTE_METADATA_ATTR, None)
+        if meta is None:
+            return
+
+        tags = list(meta.tags) if meta.tags else None
+        if (
+            meta.kind == "command"
+            and isinstance(obj, type)
+            and issubclass(obj, Command)
+        ):
+            router.add_command(
+                path=meta.path,
+                command_cls=obj,
+                method=meta.method,
+                status_code=meta.status_code,
+                output_format=meta.output_format,
+                summary=meta.summary,
+                tags=tags,
+                feature_flag=meta.feature_flag,
+            )
+        elif meta.kind == "query" and isinstance(obj, type) and issubclass(obj, Query):
+            router.add_query(
+                path=meta.path,
+                query_cls=obj,
+                method=meta.method,
+                status_code=meta.status_code,
+                output_format=meta.output_format,
+                summary=meta.summary,
+                tags=tags,
+                feature_flag=meta.feature_flag,
+            )
+
+    return visitor

hexastack_fastapi/infra/bootstrap.py

@@ -0,0 +1,85 @@
+from fastapi import FastAPI
+
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.infra.registries.exception import ExceptionRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+from hexastack_fastapi.infra.config import (
+    HexastackFastApiConfig,
+    register_fastapi_config,
+)
+
+
+class FastApiBootstrapper(BootstrapperPort):
+    """Bootstrap extension configuring FastAPI web presentation layer.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort for hexastack-fastapi, registering 'fastapi'
+        configuration in Phase 1 and creating/binding the FastAPI application instance
+        in Phase 2 after logging (order=10) and CQRS pipeline (order=20).
+    """
+
+    name: str = "fastapi"
+    order: int = 30
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Instantiate FastAPI app, configure middleware, and register in container.
+
+        Args:
+            context: BootstrapContext containing DI container, configuration, and properties.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        from hexastack_fastapi.adapters.app import create_fastapi_app
+        from hexastack_fastapi.adapters.routing import CqrsRouter
+        from hexastack_fastapi.infra.autodiscovery import create_route_visitor
+
+        cfg = context.get_config("fastapi", HexastackFastApiConfig)
+
+        pipeline = context.properties.get("pipeline")
+        if pipeline is None and ExecutionPipeline in context.container:
+            pipeline = context.container.resolve(ExecutionPipeline)
+
+        exception_reg = None
+        if ExceptionRegistry in context.container:
+            exception_reg = context.container.resolve(ExceptionRegistry)
+
+        app = create_fastapi_app(
+            config=cfg,
+            container=context.container,
+            pipeline=pipeline,
+            exception_registry=exception_reg,
+        )
+
+        if cfg.auto_register_routes:
+            router = CqrsRouter()
+            visitor = create_route_visitor(router)
+            context.register_visitor(visitor)
+            app.include_router(router)
+
+        context.container.add_instance(app, declared_class=FastAPI)
+        context.properties["app"] = app
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register FastAPI configuration schema under 'fastapi'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        register_fastapi_config(registry)
+
+
+__all__ = [
+    "FastApiBootstrapper",
+]

hexastack_fastapi/infra/config.py

@@ -0,0 +1,113 @@
+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).
+
+    Notes/Architectural Intent:
+        Controls CORS headers, origins, allowed methods, and credential passing for REST endpoints.
+    """
+
+    enable: bool = Field(default=False)
+    allow_origins: list[str] = Field(default_factory=lambda: ["*"])
+    allow_methods: list[str] = Field(default_factory=lambda: ["*"])
+    allow_headers: list[str] = Field(default_factory=lambda: ["*"])
+    allow_credentials: bool = Field(default=False)
+
+
+class HealthConfig(BaseModel):
+    """Configuration schema for health and readiness HTTP endpoints.
+
+    Notes/Architectural Intent:
+        Controls automatic registration of liveness and readiness probe routes for container orchestrators.
+    """
+
+    enable: bool = Field(default=True)
+    health_path: str = Field(default="/health")
+    ready_path: str = Field(default="/ready")
+
+
+class RequestLoggingConfig(BaseModel):
+    """Configuration schema for HTTP request access logging middleware.
+
+    Notes/Architectural Intent:
+        Controls emission of structured HTTP access log records with method, path, status, and duration.
+    """
+
+    enable: bool = Field(default=True)
+    exclude_paths: list[str] = Field(
+        default_factory=lambda: [
+            "/health",
+            "/ready",
+            "/docs",
+            "/redoc",
+            "/openapi.json",
+        ]
+    )
+
+
+class ZensicalDocsConfig(BaseModel):
+    """Configuration schema for mounting pre-built Zensical documentation onto FastAPI.
+
+    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`.
+    """
+
+    enable: bool = Field(default=False)
+    path: str = Field(default="/guide")
+    site_dir: str = Field(default="site")
+
+
+@config_section("fastapi")
+class HexastackFastApiConfig(BaseModel):
+    """Configuration schema for FastAPI HTTP presentation adapter.
+
+    Notes/Architectural Intent:
+        Controls OpenAPI metadata, documentation routes, CORS policy, header identifiers,
+        access logging, health probes, Zensical docs mounting, and automatic route autodiscovery.
+    """
+
+    title: str = Field(default="Hexastack API")
+    version: str = Field(default="0.1.0")
+    description: str = Field(default="")
+    docs_url: str = Field(default="/docs")
+    redoc_url: str = Field(default="/redoc")
+    openapi_url: str = Field(default="/openapi.json")
+    correlation_header: str = Field(default="X-Correlation-ID")
+    user_header: str = Field(default="X-User-ID")
+    tenant_header: str = Field(default="X-Tenant-ID")
+    cors: CorsConfig = Field(default_factory=CorsConfig)
+    health: HealthConfig = Field(default_factory=HealthConfig)
+    logging: RequestLoggingConfig = Field(default_factory=RequestLoggingConfig)
+    zensical: ZensicalDocsConfig = Field(default_factory=ZensicalDocsConfig)
+    auto_register_routes: bool = Field(default=True)
+    packages_to_scan: list[str] = Field(default_factory=list)
+
+
+__all__ = [
+    "CorsConfig",
+    "HealthConfig",
+    "HexastackFastApiConfig",
+    "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/infra/decorators.py

@@ -0,0 +1,199 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal
+
+from hexastack_core.domain import Command, Query
+
+_ROUTE_METADATA_ATTR = "__hexastack_route__"
+
+
+@dataclass(frozen=True)
+class RouteMetadata:
+    """Metadata describing an HTTP endpoint binding for a Command or Query.
+
+    Notes/Architectural Intent:
+        Carries routing parameters attached by decorators for automated endpoint registration,
+        including optional feature flag gating.
+    """
+
+    path: str
+    kind: Literal["command", "query"]
+    method: str = "POST"
+    status_code: int = 200
+    output_format: str | None = None
+    summary: str | None = None
+    tags: tuple[str | Enum, ...] | None = None
+    feature_flag: str | None = None
+
+
+__all__ = [
+    "api_command",
+    "api_query",
+    "feature_flag_route",
+    "RouteMetadata",
+]
+
+
+def api_command[TCommand: Command](
+    path: str,
+    *,
+    method: str = "POST",
+    status_code: int = 200,
+    output_format: str | None = None,
+    summary: str | None = None,
+    tags: list[str | Enum] | None = None,
+    feature_flag: str | None = None,
+) -> Callable[[type[TCommand]], type[TCommand]]:
+    """Decorator marking a Command class for automatic HTTP endpoint exposure.
+
+    Args:
+        path: URL path for the route.
+        method: HTTP method (defaults to 'POST').
+        status_code: Success HTTP status code (defaults to 200).
+        output_format: Optional presenter output format.
+        summary: Optional OpenAPI summary.
+        tags: Optional OpenAPI tags list.
+        feature_flag: Optional feature flag key required for route access.
+
+    Returns:
+        Decorated Command class with attached routing metadata.
+
+    Raises:
+        None.
+    """
+
+    def decorator(cls: type[TCommand]) -> type[TCommand]:
+        meta = RouteMetadata(
+            path=path,
+            kind="command",
+            method=method.upper(),
+            status_code=status_code,
+            output_format=output_format,
+            summary=summary,
+            tags=tuple(tags) if tags else None,
+            feature_flag=feature_flag,
+        )
+        setattr(cls, _ROUTE_METADATA_ATTR, meta)
+        return cls
+
+    return decorator
+
+
+def api_query[TQuery: Query](
+    path: str,
+    *,
+    method: str = "GET",
+    status_code: int = 200,
+    output_format: str | None = None,
+    summary: str | None = None,
+    tags: list[str | Enum] | None = None,
+    feature_flag: str | None = None,
+) -> Callable[[type[TQuery]], type[TQuery]]:
+    """Decorator marking a Query class for automatic HTTP endpoint exposure.
+
+    Args:
+        path: URL path for the route.
+        method: HTTP method ('GET' or 'POST', defaults to 'GET').
+        status_code: Success HTTP status code (defaults to 200).
+        output_format: Optional presenter output format.
+        summary: Optional OpenAPI summary.
+        tags: Optional OpenAPI tags list.
+        feature_flag: Optional feature flag key required for route access.
+
+    Returns:
+        Decorated Query class with attached routing metadata.
+
+    Raises:
+        None.
+    """
+
+    def decorator(cls: type[TQuery]) -> type[TQuery]:
+        meta = RouteMetadata(
+            path=path,
+            kind="query",
+            method=method.upper(),
+            status_code=status_code,
+            output_format=output_format,
+            summary=summary,
+            tags=tuple(tags) if tags else None,
+            feature_flag=feature_flag,
+        )
+        setattr(cls, _ROUTE_METADATA_ATTR, meta)
+        return cls
+
+    return decorator
+
+
+def feature_flag_route(
+    flag_key: str,
+    *,
+    default: bool = False,
+    status_code: int = 404,
+    detail: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator guarding a custom FastAPI route function with dynamic feature flag evaluation.
+
+    Notes/Architectural Intent:
+        Wraps standard FastAPI endpoint callables with dynamic feature flag evaluation,
+        returning an HTTP error (default 404) when the flag evaluates to False.
+
+    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 returned when disabled.
+        detail: Optional error message string.
+
+    Returns:
+        Decorator wrapping the endpoint callable.
+    """
+    import inspect
+    from functools import wraps
+
+    from fastapi import HTTPException
+
+    from hexastack_core.adapters.feature_flags.config import ConfigFeatureFlagAdapter
+    from hexastack_core.domain.feature_flags import EvaluationContext
+    from hexastack_core.ports.feature_flags import FeatureFlagPort
+    from hexastack_fastapi.adapters.dependencies import get_feature_flags
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
+                request = kwargs.get("request")
+                flags: FeatureFlagPort = (
+                    get_feature_flags(request)
+                    if request is not None
+                    else ConfigFeatureFlagAdapter()
+                )
+                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 await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @wraps(fn)
+        def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
+            request = kwargs.get("request")
+            flags: FeatureFlagPort = (
+                get_feature_flags(request)
+                if request is not None
+                else ConfigFeatureFlagAdapter()
+            )
+            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 fn(*args, **kwargs)
+
+        return sync_wrapped
+
+    return decorator

hexastack_fastapi/infra/exception_handlers.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from hexastack_core.domain import HexastackError
+from hexastack_core.infra.registries.exception import ExceptionRegistry
+from hexastack_core.utils.context import get_correlation_id
+
+__all__ = [
+    "register_exception_handlers",
+]
+
+
+def register_exception_handlers(
+    app: FastAPI,
+    exception_registry: ExceptionRegistry | None = None,
+) -> None:
+    """Register unified exception handlers translating domain errors into HTTP responses.
+
+    Args:
+        app: Target FastAPI application instance.
+        exception_registry: Optional ExceptionRegistry for custom exception mappings.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+
+    @app.exception_handler(HexastackError)
+    async def hexastack_error_handler(
+        request: Request, exc: HexastackError
+    ) -> JSONResponse:
+        """Handle HexastackError subclasses with status code inference and correlation metadata."""
+        if exception_registry is not None and type(exc) in exception_registry:
+            mapped = exception_registry.handle(exc)
+            if isinstance(mapped, dict) and "status_code" in mapped:
+                status = mapped.pop("status_code")
+                return JSONResponse(status_code=status, content=mapped)
+            return JSONResponse(status_code=400, content=mapped)
+
+        status_code = 400
+        exc_name = exc.__class__.__name__.lower()
+        if "notfound" in exc_name:
+            status_code = 404
+        elif "conflict" in exc_name or "duplicate" in exc_name:
+            status_code = 409
+        elif "unauthorized" in exc_name or "forbidden" in exc_name:
+            status_code = 401
+        elif "validation" in exc_name:
+            status_code = 422
+
+        content: dict[str, Any] = {
+            "error": str(exc),
+            "error_type": exc.__class__.__name__,
+            "correlation_id": get_correlation_id(),
+        }
+        return JSONResponse(status_code=status_code, content=content)

hexastack_fastapi/infra/middleware/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_fastapi.infra.middleware.correlation import (
+    CorrelationHttpMiddleware,
+)
+from hexastack_fastapi.infra.middleware.logging import (
+    RequestLoggingHttpMiddleware,
+)
+
+__all__ = [
+    "CorrelationHttpMiddleware",
+    "RequestLoggingHttpMiddleware",
+]