hexastack-fastapi 0.7.0__tar.gz → 0.9.0__tar.gz

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexastack-fastapi
-Version: 0.7.0
+Version: 0.9.0
 Summary: FastAPI presentation adapter for Hexastack
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -14,11 +14,13 @@ Requires-Dist: limits>=5.8.0 ; extra == 'ratelimit'
 Requires-Dist: slowapi>=0.1.10 ; extra == 'ratelimit'
 Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
 Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
+Requires-Dist: openziti>=1.0.0 ; extra == 'ziti'
 Requires-Python: >=3.13
 Provides-Extra: auth
 Provides-Extra: docs
 Provides-Extra: ratelimit
 Provides-Extra: testing
+Provides-Extra: ziti
 Description-Content-Type: text/markdown
 
 ![hexastack-fastapi](../../docs/assets/static/logos/packages/hexastack_fastapi.png)

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.7.0"
+version = "0.9.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -26,6 +26,7 @@ testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
 ]
+ziti = ["openziti>=1.0.0"]
 
 [project.entry-points."hexastack.bootstrappers"]
 fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.7.0"
+version = "0.9.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
 license = "Apache-2.0"
@@ -29,6 +29,9 @@ testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
 ]
+ziti = [
+    "openziti>=1.0.0",
+]
 
 [project.entry-points."hexastack.bootstrappers"]
 fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/adapters/__init__.py

@@ -14,6 +14,11 @@ from hexastack_fastapi.adapters.docs import (
 )
 from hexastack_fastapi.adapters.health import create_health_router
 from hexastack_fastapi.adapters.metrics import create_metrics_router
+from hexastack_fastapi.adapters.openziti import (
+    OpenZitiASGIAdapter,
+    OpenZitiConfig,
+    openziti_bind,
+)
 from hexastack_fastapi.adapters.ratelimit import (
     SlowapiRateLimiterAdapter,
     get_remote_address,
@@ -45,6 +50,9 @@ __all__ = [
     "get_remote_address",
     "get_user_or_ip_key",
     "mount_zensical_docs",
+    "openziti_bind",
+    "OpenZitiASGIAdapter",
+    "OpenZitiConfig",
     "rate_limit",
     "require_feature",
     "require_rate_limit",

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/adapters/dependencies.py

@@ -240,14 +240,19 @@ def require_rate_limit(
 
     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)},
-                )
+        if limiter is None:
+            from hexastack_core.adapters.ratelimit import InMemoryRateLimiter
+
+            limiter = InMemoryRateLimiter()
+            request.app.state.rate_limiter = limiter
+
+        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.9.0/src/hexastack_fastapi/adapters/openziti.py

@@ -0,0 +1,235 @@
+"""Zero-Trust Dark Microservice ASGI presentation adapter using OpenZiti.
+
+Notes/Architectural Intent:
+    Enables FastAPI/Starlette applications to host services directly on an OpenZiti overlay
+    network fabric without opening listening TCP sockets or exposed host ports.
+    Uses outbound-only mTLS tunnels so services remain dark and invisible to LAN scans
+    and the public internet.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Generator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.utils import require_dependency
+
+__all__ = [
+    "openziti_bind",
+    "OpenZitiASGIAdapter",
+    "OpenZitiConfig",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenZitiConfig:
+    """Configuration for hosting an ASGI application over the OpenZiti overlay network.
+
+    Args:
+        identity_path: Path to the enrolled OpenZiti identity JSON credentials file.
+        service_name: Name of the OpenZiti service configured with Bind permissions.
+        bind_host: Virtual hostname or IP for the intercepted socket. Defaults to '127.0.0.1'.
+        bind_port: Virtual port for the intercepted socket. Defaults to 8000.
+        enabled: Whether OpenZiti overlay hosting is active. Defaults to True.
+
+    Notes/Architectural Intent:
+        The bind_host and bind_port do not open listening kernel ports on the host.
+        They serve as the socket binding hook intercepted by OpenZiti's monkeypatch layer.
+    """
+
+    identity_path: Path | str
+    service_name: str
+    bind_host: str = "127.0.0.1"
+    bind_port: int = 8000
+    enabled: bool = True
+
+    def resolved_identity_path(self) -> Path:
+        """Resolve and validate the OpenZiti identity credentials file path.
+
+        Returns:
+            Resolved Path object pointing to the identity file.
+
+        Raises:
+            FileNotFoundError: If the identity credentials file does not exist on disk.
+        """
+        path = Path(self.identity_path).resolve()
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"OpenZiti identity credentials file not found: {self.identity_path}"
+            )
+        return path
+
+
+class OpenZitiASGIAdapter:
+    """ASGI server adapter enabling zero-trust hosting on the OpenZiti overlay fabric.
+
+    Notes/Architectural Intent:
+        Wraps Python socket operations via OpenZiti's monkeypatching infrastructure to bind
+        ASGI servers (e.g. Uvicorn) directly to an OpenZiti service without opening listening
+        network sockets on the host OS.
+    """
+
+    def __init__(self, config: OpenZitiConfig) -> None:
+        """Initialize the OpenZiti ASGI adapter.
+
+        Args:
+            config: OpenZitiConfig specifying identity path, service name, and virtual bind target.
+        """
+        self.config = config
+
+    @staticmethod
+    def _require_openziti() -> Any:
+        """Dynamically load openziti module or raise MissingDependencyError.
+
+        Returns:
+            The imported openziti module.
+
+        Raises:
+            MissingDependencyError: If openziti is not installed.
+        """
+        return require_dependency(
+            "openziti",
+            extra="ziti",
+            package="hexastack-fastapi",
+            feature_name="OpenZiti Zero-Trust Network",
+        )
+
+    def get_bindings(
+        self, host: str | None = None, port: int | None = None
+    ) -> dict[tuple[str, int], dict[str, Any]]:
+        """Construct the OpenZiti socket binding mapping.
+
+        Args:
+            host: Optional host address override. Defaults to config.bind_host.
+            port: Optional port number override. Defaults to config.bind_port.
+
+        Returns:
+            Dictionary mapping (host, port) to OpenZiti context and service options.
+
+        Raises:
+            FileNotFoundError: If the identity credentials file does not exist.
+        """
+        identity_file = self.config.resolved_identity_path()
+        target_host = host or self.config.bind_host
+        target_port = port if port is not None else self.config.bind_port
+        return {
+            (target_host, target_port): {
+                "ztx": str(identity_file),
+                "service": self.config.service_name,
+            }
+        }
+
+    @contextlib.contextmanager
+    def bind_context(
+        self, host: str | None = None, port: int | None = None
+    ) -> Generator[None]:
+        """Context manager activating OpenZiti overlay socket interception.
+
+        Args:
+            host: Optional bind host override.
+            port: Optional bind port override.
+
+        Yields:
+            None when socket interception is active.
+
+        Raises:
+            MissingDependencyError: If openziti is not installed.
+            FileNotFoundError: If the identity file does not exist.
+
+        Notes/Architectural Intent:
+            Activates openziti.monkeypatch with configured bindings upon entry,
+            restoring original Python socket behaviors upon exit.
+        """
+        if not self.config.enabled:
+            yield
+            return
+
+        openziti = self._require_openziti()
+        bindings = self.get_bindings(host=host, port=port)
+        with openziti.monkeypatch(bindings=bindings):
+            yield
+
+    def zitify(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorate a server runner function to execute within the OpenZiti overlay.
+
+        Args:
+            func: Target callable to decorate (e.g. uvicorn.run or server startup).
+
+        Returns:
+            Decorated callable wrapped with OpenZiti overlay socket interception.
+        """
+
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            with self.bind_context():
+                return func(*args, **kwargs)
+
+        return wrapped
+
+    @staticmethod
+    def _require_uvicorn() -> Any:
+        """Dynamically load uvicorn module or raise MissingDependencyError.
+
+        Returns:
+            The imported uvicorn module.
+
+        Raises:
+            MissingDependencyError: If uvicorn is not installed.
+        """
+        try:
+            import uvicorn
+
+            return uvicorn
+        except ImportError as exc:
+            raise MissingDependencyError(
+                "uvicorn is required to run the ASGI server. "
+                "Install with 'pip install uvicorn[standard]'."
+            ) from exc
+
+    def run_uvicorn(self, app: Any, **uvicorn_kwargs: Any) -> None:
+        """Launch Uvicorn to serve the ASGI application over the OpenZiti overlay.
+
+        Args:
+            app: The FastAPI, Starlette, or ASGI application instance or import string.
+            **uvicorn_kwargs: Additional keyword arguments passed to uvicorn.run.
+
+        Raises:
+            MissingDependencyError: If openziti or uvicorn is not installed.
+            FileNotFoundError: If the identity file does not exist.
+        """
+        uvicorn = self._require_uvicorn()
+        host = uvicorn_kwargs.pop("host", self.config.bind_host)
+        port = uvicorn_kwargs.pop("port", self.config.bind_port)
+
+        with self.bind_context(host=host, port=port):
+            uvicorn.run(app, host=host, port=port, **uvicorn_kwargs)
+
+
+def openziti_bind(
+    identity_path: Path | str,
+    service_name: str,
+    bind_host: str = "127.0.0.1",
+    bind_port: int = 8000,
+) -> contextlib.AbstractContextManager[None]:
+    """Convenience context manager to bind current process sockets to an OpenZiti service.
+
+    Args:
+        identity_path: Path to the enrolled OpenZiti identity credentials file.
+        service_name: Name of the OpenZiti service to host.
+        bind_host: Virtual bind host address. Defaults to '127.0.0.1'.
+        bind_port: Virtual bind port number. Defaults to 8000.
+
+    Returns:
+        Context manager that intercepts socket operations for the given host and port.
+    """
+    config = OpenZitiConfig(
+        identity_path=identity_path,
+        service_name=service_name,
+        bind_host=bind_host,
+        bind_port=bind_port,
+    )
+    adapter = OpenZitiASGIAdapter(config)
+    return adapter.bind_context()

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/adapters/ratelimit.py

@@ -1,37 +1,46 @@
 import inspect
 from collections.abc import Callable
 from functools import wraps
-from typing import Any
+from typing import Any, cast
 
 from fastapi import HTTPException, Request, status
 
-from hexastack_core.domain.exceptions import MissingDependencyError
 from hexastack_core.ports.ratelimit import RateLimiterPort
+from hexastack_core.utils import require_dependency
 from hexastack_core.utils.context import get_user_context
 
 
-def get_remote_address(request: Request) -> str:
+def get_remote_address(request: Request, trust_proxy: bool = False) -> str:
     """Extract client IP address from FastAPI request headers or client socket.
 
     Args:
         request: Incoming FastAPI Request object.
+        trust_proxy: Whether to trust X-Forwarded-For headers from upstream proxies.
 
     Returns:
         Client IP string.
     """
+    if trust_proxy:
+        forwarded = request.headers.get("X-Forwarded-For")
+        if forwarded:
+            return forwarded.split(",")[0].strip()
+
+    if request.client and request.client.host:
+        return request.client.host
+
     forwarded = request.headers.get("X-Forwarded-For")
     if forwarded:
         return forwarded.split(",")[0].strip()
-    if request.client and request.client.host:
-        return request.client.host
+
     return "127.0.0.1"
 
 
-def get_user_or_ip_key(request: Request) -> str:
+def get_user_or_ip_key(request: Request, trust_proxy: bool = False) -> str:
     """Extract rate limit bucket key from ambient UserContext or fallback to client IP.
 
     Args:
         request: Incoming FastAPI Request object.
+        trust_proxy: Whether to trust X-Forwarded-For headers from upstream proxies.
 
     Returns:
         Rate limit identifier string (e.g. 'user:usr_123', 'tenant:t_456', or 'ip:1.2.3.4').
@@ -41,7 +50,7 @@ def get_user_or_ip_key(request: Request) -> str:
         return f"user:{user_ctx.user_id}"
     if user_ctx and user_ctx.tenant_id:
         return f"tenant:{user_ctx.tenant_id}"
-    return f"ip:{get_remote_address(request)}"
+    return f"ip:{get_remote_address(request, trust_proxy=trust_proxy)}"
 
 
 class SlowapiRateLimiterAdapter(RateLimiterPort):
@@ -68,14 +77,20 @@ class SlowapiRateLimiterAdapter(RateLimiterPort):
         Raises:
             MissingDependencyError: If slowapi or limits is not installed.
         """
-        try:
-            from limits.storage import storage_from_string
-            from slowapi import Limiter
-        except ImportError as e:
-            raise MissingDependencyError(
-                "slowapi and limits are required for SlowapiRateLimiterAdapter. "
-                "Install with 'pip install hexastack-fastapi[ratelimit]'."
-            ) from e
+        limits_storage = require_dependency(
+            "limits.storage",
+            extra="ratelimit",
+            package="hexastack-fastapi",
+            feature_name="Slowapi Rate Limiter Storage",
+        )
+        slowapi = require_dependency(
+            "slowapi",
+            extra="ratelimit",
+            package="hexastack-fastapi",
+            feature_name="Slowapi Rate Limiter",
+        )
+        storage_from_string = limits_storage.storage_from_string
+        Limiter = slowapi.Limiter
 
         self._key_func = key_func or get_user_or_ip_key
         self._default_limits: list[Any] = list(default_limits or ["100/minute"])
@@ -136,7 +151,10 @@ def _enforce_rate_limit(
 ) -> None:
     """Check rate limit quota against application rate limiter and raise HTTPException if exceeded."""
     if request is None:
-        return
+        raise RuntimeError(
+            f"@rate_limit applied to '{fn_name}', but no Request instance was received. "
+            "Ensure the route declares 'request: Request' or FastAPI forwards the request."
+        )
     limiter_port: RateLimiterPort | None = getattr(
         request.app.state, "rate_limiter", None
     )
@@ -178,6 +196,11 @@ def rate_limit(
 
     def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
         fn_name = getattr(fn, "__name__", "endpoint")
+        sig = inspect.signature(fn)
+        has_req_param = any(
+            p.annotation is Request or p.name == "request"
+            for p in sig.parameters.values()
+        )
 
         if inspect.iscoroutinefunction(fn):
 
@@ -185,16 +208,44 @@ def rate_limit(
             async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
                 req = _extract_request(args, kwargs)
                 _enforce_rate_limit(req, fn_name, limit, key_extractor, detail)
+                if not has_req_param:
+                    kwargs.pop("request", None)
                 return await fn(*args, **kwargs)
 
+            if not has_req_param:
+                params = list(sig.parameters.values())
+                params.append(
+                    inspect.Parameter(
+                        "request",
+                        inspect.Parameter.KEYWORD_ONLY,
+                        annotation=Request,
+                    )
+                )
+                cast("Any", async_wrapped).__signature__ = sig.replace(
+                    parameters=params
+                )
+
             return async_wrapped
 
         @wraps(fn)
         def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
             req = _extract_request(args, kwargs)
             _enforce_rate_limit(req, fn_name, limit, key_extractor, detail)
+            if not has_req_param:
+                kwargs.pop("request", None)
             return fn(*args, **kwargs)
 
+        if not has_req_param:
+            params = list(sig.parameters.values())
+            params.append(
+                inspect.Parameter(
+                    "request",
+                    inspect.Parameter.KEYWORD_ONLY,
+                    annotation=Request,
+                )
+            )
+            cast("Any", sync_wrapped).__signature__ = sig.replace(parameters=params)
+
         return sync_wrapped
 
     return decorator

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/adapters/sse.py

@@ -12,7 +12,7 @@ from starlette.background import BackgroundTask
 from starlette.types import Receive, Scope, Send
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class ServerSentEvent:
     """Represents an individual Server-Sent Event frame.
 
@@ -60,6 +60,30 @@ class ServerSentEvent:
         return "".join(buffer).encode("utf-8")
 
 
+def _encode_sse_item(item: Any) -> bytes:
+    """Encode an SSE stream item to bytes."""
+    if isinstance(item, ServerSentEvent):
+        return item.encode()
+    if isinstance(item, bytes):
+        return item
+    if isinstance(item, str):
+        return ServerSentEvent(data=item).encode()
+    import json
+
+    return ServerSentEvent(data=json.dumps(item)).encode()
+
+
+async def _cleanup_producer(producer_task: asyncio.Task[None]) -> None:
+    """Safely cancel or check producer task on stream termination."""
+    if not producer_task.done():
+        producer_task.cancel()
+        _ = await asyncio.gather(producer_task, return_exceptions=True)
+    elif not producer_task.cancelled():
+        exc = producer_task.exception()
+        if exc is not None:
+            raise exc
+
+
 class EventSourceResponse(Response):
     """FastAPI/Starlette Response subclass streaming Server-Sent Events over HTTP.
 
@@ -106,24 +130,14 @@ class EventSourceResponse(Response):
 
     async def _stream_with_ping(self) -> AsyncIterator[bytes]:
         """Wrap body_iterator with periodic keep-alive pings."""
-        queue: asyncio.Queue[bytes | None] = asyncio.Queue()
+        queue: asyncio.Queue[bytes | Exception | None] = asyncio.Queue(maxsize=100)
 
         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
+                    await queue.put(_encode_sse_item(item))
+            except Exception as exc:
+                await queue.put(exc)
             finally:
                 await queue.put(None)
 
@@ -136,20 +150,19 @@ class EventSourceResponse(Response):
                         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()
+                        continue
                 else:
                     chunk = await queue.get()
-                    if chunk is None:
-                        break
-                    yield chunk
+
+                if chunk is None:
+                    break
+                if isinstance(chunk, Exception):
+                    raise chunk
+                yield chunk
         finally:
-            if not producer_task.done():
-                producer_task.cancel()
-                _ = await asyncio.gather(producer_task, return_exceptions=True)
+            await _cleanup_producer(producer_task)
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         """ASGI response streaming callable."""

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/adapters/websockets.py

@@ -195,11 +195,16 @@ class WebSocketCqrsBridge:
                         if asyncio.iscoroutine(cb_res):
                             await cb_res
                 except Exception as exc:
+                    err_msg = (
+                        str(exc)
+                        if isinstance(exc, (ValueError, TypeError, KeyError))
+                        else "Internal server error."
+                    )
                     await websocket.send_json(
                         {
                             "status": "error",
                             "type": type_tag,
-                            "error": str(exc),
+                            "error": err_msg,
                         }
                     )
         except WebSocketDisconnect:

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/domain/config.py

@@ -64,6 +64,10 @@ class RateLimitConfig(BaseModel):
         default="memory://",
         description="Backend storage URI: 'memory://' or 'redis://localhost:6379'.",
     )
+    trust_proxy_headers: bool = Field(
+        default=False,
+        description="Whether to trust X-Forwarded-For headers for client IP extraction.",
+    )
 
 
 class ZensicalDocsConfig(BaseModel):
@@ -96,6 +100,10 @@ class HexastackFastApiConfig(BaseModel):
     correlation_header: str = Field(default="X-Correlation-ID")
     user_header: str = Field(default="X-User-ID")
     tenant_header: str = Field(default="X-Tenant-ID")
+    trust_identity_headers: bool = Field(
+        default=False,
+        description="Whether to trust incoming user and tenant identity headers from upstream clients.",
+    )
     cors: CorsConfig = Field(default_factory=CorsConfig)
     health: HealthConfig = Field(default_factory=HealthConfig)
     logging: RequestLoggingConfig = Field(default_factory=RequestLoggingConfig)

hexastack_fastapi-0.9.0/src/hexastack_fastapi/infra/exception_handlers.py

@@ -0,0 +1,156 @@
+import logging
+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.ports.logging import LoggingPort
+from hexastack_core.utils.context import get_correlation_id
+
+_fallback_logger = logging.getLogger(__name__)
+
+__all__ = [
+    "register_exception_handlers",
+]
+
+
+def _infer_status_code(exc: HexastackError) -> int:
+    """Infer HTTP status code from domain exception class name.
+
+    Args:
+        exc: Domain error instance.
+
+    Returns:
+        Standard HTTP status code matching error semantics.
+    """
+    exc_name = exc.__class__.__name__.lower()
+    if "notfound" in exc_name:
+        return 404
+    if "conflict" in exc_name or "duplicate" in exc_name:
+        return 409
+    if any(k in exc_name for k in ("permission", "forbidden", "accessdenied")):
+        return 403
+    if any(
+        k in exc_name for k in ("unauthorized", "unauthenticated", "invalidcredential")
+    ):
+        return 401
+    if "validation" in exc_name:
+        return 422
+    return 400
+
+
+def _resolve_logger(app: FastAPI, explicit: LoggingPort | None) -> LoggingPort | None:
+    """Resolve LoggingPort from explicit argument or FastAPI application container.
+
+    Args:
+        app: Target FastAPI application.
+        explicit: Optional explicitly supplied LoggingPort instance.
+
+    Returns:
+        Resolved LoggingPort or None.
+    """
+    if explicit is not None:
+        return explicit
+    container = getattr(app.state, "container", None)
+    if container is not None and LoggingPort in container:
+        return container.resolve(LoggingPort)
+    return None
+
+
+def _forward_to_sentry(
+    request: Request,
+    exc: Exception,
+    correlation_id: str | None,
+    active_logger: LoggingPort | None,
+) -> None:
+    """Forward unhandled exception context to Sentry SDK if installed and configured.
+
+    Args:
+        request: FastAPI HTTP request instance.
+        exc: Unhandled exception.
+        correlation_id: Optional correlation trace identifier.
+        active_logger: Optional LoggingPort for diagnostic telemetry.
+    """
+    try:
+        import sentry_sdk
+
+        with sentry_sdk.push_scope() as scope:
+            scope.set_tag("path", request.url.path)
+            scope.set_tag("method", request.method)
+            if correlation_id:
+                scope.set_tag("correlation_id", correlation_id)
+            sentry_sdk.capture_exception(exc)
+    except Exception as sentry_exc:  # noqa: BLE001
+        if active_logger is not None:
+            active_logger.debug(f"Failed to forward exception to Sentry: {sentry_exc}")
+        else:
+            _fallback_logger.debug(
+                "Failed to forward exception to Sentry: %s", sentry_exc
+            )
+
+
+def register_exception_handlers(
+    app: FastAPI,
+    exception_registry: ExceptionRegistry | None = None,
+    logger: LoggingPort | None = None,
+) -> None:
+    """Register unified exception handlers translating domain errors into HTTP responses.
+
+    Notes/Architectural Intent:
+        Intercepts HexastackError domain exceptions and unhandled system errors.
+        Maps domain errors to standardized HTTP status codes (400, 401, 403, 404, 409, 422)
+        and forwards unhandled 500 exceptions with correlation ID and request tags to Sentry if active.
+
+    Args:
+        app: Target FastAPI application instance.
+        exception_registry: Optional ExceptionRegistry for custom exception mappings.
+        logger: Optional LoggingPort instance to receive exception forwarding diagnostics.
+
+    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 = _infer_status_code(exc)
+        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)
+
+    @app.exception_handler(Exception)
+    async def unhandled_exception_handler(
+        request: Request, exc: Exception
+    ) -> JSONResponse:
+        """Handle unhandled server exceptions, push context to Sentry if available, and return 500."""
+        correlation_id = get_correlation_id()
+        active_logger = _resolve_logger(app, logger)
+        if active_logger is not None:
+            active_logger.error(f"Unhandled server exception: {exc}", exc=exc)
+        else:
+            _fallback_logger.error("Unhandled server exception: %s", exc, exc_info=exc)
+        _forward_to_sentry(request, exc, correlation_id, active_logger)
+
+        content: dict[str, Any] = {
+            "error": "Internal server error",
+            "error_type": exc.__class__.__name__,
+            "correlation_id": correlation_id,
+        }
+        return JSONResponse(status_code=500, content=content)

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/infra/middleware/correlation.py

@@ -37,6 +37,7 @@ class CorrelationHttpMiddleware:
         self._correlation_header_name = cfg.correlation_header
         self._user_header = cfg.user_header.lower().encode("latin1")
         self._tenant_header = cfg.tenant_header.lower().encode("latin1")
+        self._trust_identity_headers = cfg.trust_identity_headers
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         """Process incoming ASGI request, inject context tokens, and wrap response.
@@ -64,16 +65,17 @@ class CorrelationHttpMiddleware:
         correlation_id = raw_cid.decode("latin1") if raw_cid else new_correlation_id()
         corr_token = set_correlation_id(correlation_id)
 
-        # 2. Extract User / Tenant context
-        raw_uid = header_map.get(self._user_header)
-        raw_tid = header_map.get(self._tenant_header)
-        user_token = None
-        if raw_uid or raw_tid:
-            user_context = UserContext(
-                user_id=raw_uid.decode("latin1") if raw_uid else "anonymous",
-                tenant_id=raw_tid.decode("latin1") if raw_tid else None,
-            )
-            user_token = set_user_context(user_context)
+        # 2. Extract User / Tenant context (only if explicitly trusted upstream)
+        user_context = None
+        if self._trust_identity_headers:
+            raw_uid = header_map.get(self._user_header)
+            raw_tid = header_map.get(self._tenant_header)
+            if raw_uid or raw_tid:
+                user_context = UserContext(
+                    user_id=raw_uid.decode("latin1") if raw_uid else "anonymous",
+                    tenant_id=raw_tid.decode("latin1") if raw_tid else None,
+                )
+        user_token = set_user_context(user_context)
 
         # 3. Intercept response to inject correlation header
         async def send_wrapper(message: Message) -> None:
@@ -91,8 +93,7 @@ class CorrelationHttpMiddleware:
             await self._app(scope, receive, send_wrapper)
         finally:
             correlation_id_ctx.reset(corr_token)
-            if user_token is not None:
-                user_ctx.reset(user_token)
+            user_ctx.reset(user_token)
 
 
 __all__ = [

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/infra/middleware/metrics.py

@@ -98,9 +98,17 @@ class HttpMetricsMiddleware:
             await self._app(scope, receive, send_wrapper)
         finally:
             duration = time.perf_counter() - start_time
+            route = scope.get("route")
+            if route is not None and hasattr(route, "path_format"):
+                metric_path = route.path_format
+            elif status_code == 404:
+                metric_path = "unmatched"
+            else:
+                metric_path = path
+
             labels = {
                 "method": method,
-                "path": path,
+                "path": metric_path,
                 "status_code": str(status_code),
             }
             metrics.increment_counter(
@@ -112,7 +120,7 @@ class HttpMetricsMiddleware:
             metrics.record_histogram(
                 "http_request_duration_seconds",
                 value=duration,
-                labels={"method": method, "path": path},
+                labels={"method": method, "path": metric_path},
                 description="HTTP request duration distribution in seconds",
             )
 

{hexastack_fastapi-0.7.0 → hexastack_fastapi-0.9.0}/src/hexastack_fastapi/testing/recorder.py

@@ -7,7 +7,8 @@ import time
 from pathlib import Path
 from typing import Any
 
-from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.utils import require_dependency
+from hexastack_core.utils.fs import atomic_write_text
 from hexastack_fastapi.testing.cursor import VIRTUAL_CURSOR_SCRIPT
 
 CAPTION_BANNER_SCRIPT = """
@@ -70,13 +71,12 @@ class DemoNarrator:
         Raises:
             MissingDependencyError: If `playwright` is not installed.
         """
-        try:
-            import playwright  # noqa: F401
-        except ImportError as e:
-            raise MissingDependencyError(
-                "Playwright is required to record feature demos. "
-                "Install with 'pip install hexastack-fastapi[testing]' or 'pip install playwright'."
-            ) from e
+        require_dependency(
+            "playwright",
+            extra="testing",
+            package="hexastack-fastapi",
+            feature_name="Feature Demo Recording",
+        )
 
         self.page = page
         self.output_name = output_name
@@ -220,7 +220,7 @@ class DemoNarrator:
         out_dir = Path("docs/assets/demos")
         out_dir.mkdir(parents=True, exist_ok=True)
         vtt_path = out_dir / f"{self.output_name or 'demo'}.vtt"
-        vtt_path.write_text("\n".join(vtt_lines), encoding="utf-8")
+        atomic_write_text(vtt_path, "\n".join(vtt_lines), encoding="utf-8")
         return vtt_path
 
     @staticmethod

hexastack_fastapi-0.7.0/src/hexastack_fastapi/infra/exception_handlers.py

@@ -1,70 +0,0 @@
-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 (
-            "permission" in exc_name
-            or "forbidden" in exc_name
-            or "accessdenied" in exc_name
-        ):
-            status_code = 403
-        elif (
-            "unauthorized" in exc_name
-            or "unauthenticated" in exc_name
-            or "invalidcredential" 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)