hexastack-fastapi 0.0.0__py3-none-any.whl

hexastack_fastapi/infra/middleware/correlation.py

@@ -0,0 +1,100 @@
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from hexastack_core.utils.context import (
+    UserContext,
+    correlation_id_ctx,
+    new_correlation_id,
+    set_correlation_id,
+    set_user_context,
+    user_ctx,
+)
+from hexastack_fastapi.infra.config import HexastackFastApiConfig
+
+
+class CorrelationHttpMiddleware:
+    """ASGI middleware managing correlation and user identity context from HTTP headers.
+
+    Notes/Architectural Intent:
+        Extracts or generates correlation IDs and tenant/user identities from incoming
+        request headers, sets them in ContextVars for CQRS/logging consumption, and
+        attaches the correlation ID to outgoing HTTP response headers.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        config: HexastackFastApiConfig | None = None,
+    ) -> None:
+        """Initialize middleware with target ASGI application and configuration.
+
+        Args:
+            app: The downstream ASGI application callable.
+            config: Optional HexastackFastApiConfig controlling header names.
+        """
+        self._app = app
+        cfg = config or HexastackFastApiConfig()
+        self._correlation_header = cfg.correlation_header.lower().encode("latin1")
+        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")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Process incoming ASGI request, inject context tokens, and wrap response.
+
+        Args:
+            scope: ASGI connection scope dictionary.
+            receive: ASGI receive callable.
+            send: ASGI send callable.
+
+        Returns:
+            None.
+
+        Raises:
+            Exception: Propagates unhandled exceptions to upstream exception handlers.
+        """
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+
+        headers: list[tuple[bytes, bytes]] = scope.get("headers", [])
+        header_map: dict[bytes, bytes] = dict(headers)
+
+        # 1. Extract or generate Correlation ID
+        raw_cid = header_map.get(self._correlation_header)
+        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)
+
+        # 3. Intercept response to inject correlation header
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                resp_headers: list[tuple[bytes, bytes]] = list(
+                    message.get("headers", [])
+                )
+                resp_headers.append(
+                    (self._correlation_header, correlation_id.encode("latin1"))
+                )
+                message["headers"] = resp_headers
+            await send(message)
+
+        try:
+            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)
+
+
+__all__ = [
+    "CorrelationHttpMiddleware",
+]

hexastack_fastapi/infra/middleware/logging.py

@@ -0,0 +1,95 @@
+import time
+
+from rodi import Container
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from hexastack_core.adapters.logging.standard import StandardLogger
+from hexastack_core.ports.logging import LoggingPort
+from hexastack_fastapi.infra.config import HexastackFastApiConfig
+
+
+class RequestLoggingHttpMiddleware:
+    """ASGI middleware producing structured access logs for HTTP requests.
+
+    Notes/Architectural Intent:
+        Measures HTTP transaction duration, captures client metadata and response status,
+        and logs via the LoggingPort resolved from the DI container.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        config: HexastackFastApiConfig | None = None,
+        container: Container | None = None,
+        logger: LoggingPort | None = None,
+    ) -> None:
+        """Initialize request logging middleware.
+
+        Args:
+            app: Downstream ASGI application.
+            config: Optional HexastackFastApiConfig instance.
+            container: Optional rodi Container to dynamically resolve LoggingPort.
+            logger: Optional pre-configured LoggingPort instance.
+        """
+        self._app = app
+        self._cfg = config or HexastackFastApiConfig()
+        self._container = container
+        self._logger = logger or StandardLogger("hexastack.http")
+        self._exclude_paths = set(self._cfg.logging.exclude_paths)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Intercept request, measure duration, and log access details."""
+        if scope["type"] != "http" or not self._cfg.logging.enable:
+            await self._app(scope, receive, send)
+            return
+
+        path = scope.get("path", "/")
+        if path in self._exclude_paths:
+            await self._app(scope, receive, send)
+            return
+
+        method = scope.get("method", "GET")
+        http_version = scope.get("http_version", "1.1")
+        client = scope.get("client")
+        client_ip = client[0] if client else "unknown"
+
+        status_code = 500
+        start_time = time.perf_counter()
+
+        async def send_wrapper(message: Message) -> None:
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message.get("status", 200)
+            await send(message)
+
+        try:
+            await self._app(scope, receive, send_wrapper)
+        finally:
+            end_time = time.perf_counter()
+            duration_ms = round((end_time - start_time) * 1000, 2)
+            log = self._get_logger()
+            msg = f"{method} {path} HTTP/{http_version} -> {status_code} ({duration_ms}ms)"
+            extra = {
+                "http_method": method,
+                "http_path": path,
+                "http_status": status_code,
+                "duration_ms": duration_ms,
+                "client_ip": client_ip,
+            }
+            if status_code >= 500:
+                log.error(msg, extra=extra)
+            elif status_code >= 400:
+                log.warning(msg, extra=extra)
+            else:
+                log.info(msg, extra=extra)
+
+    def _get_logger(self) -> LoggingPort:
+        """Resolve LoggingPort from container if available, else use fallback."""
+        if self._container is not None and LoggingPort in self._container:
+            return self._container.resolve(LoggingPort)
+        return self._logger
+
+
+__all__ = [
+    "RequestLoggingHttpMiddleware",
+]

hexastack_fastapi/testing/__init__.py

@@ -0,0 +1,18 @@
+"""Testing utilities and fixtures for Hexastack FastAPI and DevTools applications."""
+
+from hexastack_fastapi.testing.cursor import VIRTUAL_CURSOR_SCRIPT, smart_click
+from hexastack_fastapi.testing.recorder import DemoNarrator
+from hexastack_fastapi.testing.server import (
+    EphemeralServer,
+    ephemeral_server,
+    find_free_port,
+)
+
+__all__ = [
+    "DemoNarrator",
+    "ephemeral_server",
+    "EphemeralServer",
+    "find_free_port",
+    "smart_click",
+    "VIRTUAL_CURSOR_SCRIPT",
+]

hexastack_fastapi/testing/cursor.py

@@ -0,0 +1,115 @@
+"""Visual virtual cursor overlay script and human mouse emulation for feature demo recordings."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from playwright.sync_api import Locator, Page
+
+VIRTUAL_CURSOR_SCRIPT = """
+(() => {
+    let mouseX = 100;
+    let mouseY = 100;
+    let cursor = null;
+    let isPressed = false;
+
+    window.addEventListener('mousemove', (e) => {
+        mouseX = e.clientX;
+        mouseY = e.clientY;
+        if (cursor) {
+            cursor.style.left = mouseX + 'px';
+            cursor.style.top = mouseY + 'px';
+        }
+    }, { passive: true });
+
+    window.addEventListener('mousedown', () => {
+        isPressed = true;
+        if (cursor) {
+            cursor.style.backgroundColor = 'rgba(16, 185, 129, 0.9)'; // emerald-500
+            cursor.style.transform = 'translate(-50%, -50%) scale(1.4)';
+        }
+    }, { passive: true });
+
+    window.addEventListener('mouseup', () => {
+        isPressed = false;
+        if (cursor) {
+            cursor.style.backgroundColor = 'rgba(239, 68, 68, 0.8)';
+            cursor.style.transform = 'translate(-50%, -50%) scale(1.0)';
+        }
+    }, { passive: true });
+
+    const initCursor = () => {
+        if (document.getElementById('playwright-virtual-cursor')) return;
+
+        cursor = document.createElement('div');
+        cursor.id = 'playwright-virtual-cursor';
+        cursor.style.position = 'fixed';
+        cursor.style.left = mouseX + 'px';
+        cursor.style.top = mouseY + 'px';
+        cursor.style.width = '24px';
+        cursor.style.height = '24px';
+        cursor.style.borderRadius = '50%';
+        cursor.style.backgroundColor = isPressed ? 'rgba(16, 185, 129, 0.9)' : 'rgba(239, 68, 68, 0.8)';
+        cursor.style.border = '3px solid #fff';
+        cursor.style.boxShadow = '0 0 10px rgba(0,0,0,0.5), 0 0 5px rgba(239, 68, 68, 0.8)';
+        cursor.style.pointerEvents = 'none';
+        cursor.style.zIndex = '2147483647';
+        cursor.style.transition = 'transform 0.1s ease-out, background-color 0.1s ease';
+        cursor.style.transform = isPressed ? 'translate(-50%, -50%) scale(1.4)' : 'translate(-50%, -50%) scale(1.0)';
+
+        const root = document.documentElement || document.body;
+        if (root) {
+            root.appendChild(cursor);
+        }
+    };
+
+    const interval = setInterval(() => {
+        const parent = document.documentElement || document.body;
+        if (parent) {
+            initCursor();
+            clearInterval(interval);
+        }
+    }, 50);
+
+    window.addEventListener('DOMContentLoaded', initCursor);
+})();
+"""
+
+
+def smart_click(page: Page, locator: Locator | Any, steps: int = 35) -> None:
+    """Emulate human-like smooth mouse movement, pause, and click for demo recordings.
+
+    If RECORD_DEMO is not active, executes instant locator.first.click() for maximum test speed.
+    """
+    record_mode = os.environ.get("RECORD_DEMO") in ("1", "true", "True")
+    element = locator.first if hasattr(locator, "first") else locator
+
+    if not record_mode:
+        element.click()
+        return
+
+    element.scroll_into_view_if_needed()
+    box = element.bounding_box()
+    if not box:
+        element.click()
+        return
+
+    x = box["x"] + box["width"] / 2
+    y = box["y"] + box["height"] / 2
+
+    # Smooth human mouse movement
+    page.mouse.move(x, y, steps=steps)
+    page.wait_for_timeout(800)  # Human-like pause showing target focus
+
+    # Visual click ripple
+    page.mouse.down()
+    page.wait_for_timeout(300)
+    page.mouse.up()
+    page.wait_for_timeout(600)  # Settle delay
+
+
+__all__ = [
+    "smart_click",
+    "VIRTUAL_CURSOR_SCRIPT",
+]

hexastack_fastapi/testing/recorder.py

@@ -0,0 +1,238 @@
+"""Feature demo narrator and WebVTT caption generator for Playwright recordings."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_fastapi.testing.cursor import VIRTUAL_CURSOR_SCRIPT
+
+CAPTION_BANNER_SCRIPT = """
+(() => {
+    const initBanner = () => {
+        if (document.getElementById('hexastack-caption-banner')) return;
+        const banner = document.createElement('div');
+        banner.id = 'hexastack-caption-banner';
+        banner.style.position = 'fixed';
+        banner.style.bottom = '32px';
+        banner.style.left = '50%';
+        banner.style.transform = 'translateX(-50%)';
+        banner.style.backgroundColor = 'rgba(15, 23, 42, 0.92)';
+        banner.style.color = '#ffffff';
+        banner.style.padding = '12px 24px';
+        banner.style.borderRadius = '8px';
+        banner.style.fontSize = '17px';
+        banner.style.fontFamily = 'system-ui, -apple-system, sans-serif';
+        banner.style.fontWeight = '500';
+        banner.style.boxShadow = '0 10px 25px rgba(0, 0, 0, 0.5)';
+        banner.style.border = '1px solid rgba(255, 255, 255, 0.15)';
+        banner.style.backdropFilter = 'blur(8px)';
+        banner.style.zIndex = '2147483646';
+        banner.style.display = 'none';
+        banner.style.transition = 'opacity 0.2s ease-in-out';
+        banner.style.pointerEvents = 'none';
+        banner.style.maxWidth = '80%';
+        banner.style.textAlign = 'center';
+
+        const root = document.documentElement || document.body;
+        if (root) root.appendChild(banner);
+    };
+
+    window.addEventListener('DOMContentLoaded', initBanner);
+    setInterval(() => {
+        const root = document.documentElement || document.body;
+        if (root) initBanner();
+    }, 100);
+})();
+"""
+
+
+class DemoNarrator:
+    """Orchestrates synchronized UI actions, live banner captions, and WebVTT subtitle export.
+
+    Notes/Architectural Intent:
+        Provides high-level narrative actions (`step`, `click`, `fill`, `goto`) that:
+        1. Run at full native speed with zero overhead during CI / standard test runs.
+        2. In demo recording mode (`RECORD_DEMO=1`), displays an elegant on-screen DOM subtitle
+           banner burned into the video, animates smooth cursor movement, and writes .vtt subtitle files.
+    """
+
+    def __init__(self, page: Any, output_name: str | None = None) -> None:
+        """Initialize demo narrator attached to a Playwright page.
+
+        Args:
+            page: Active Playwright Page instance.
+            output_name: Base filename (without extension) for saving .vtt captions.
+
+        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
+
+        self.page = page
+        self.output_name = output_name
+        self.record_mode = os.environ.get("RECORD_DEMO") in ("1", "true", "True")
+        self.start_time: float = time.time()
+        self.captions: list[tuple[float, float, str]] = []
+        self._current_step_start: float | None = None
+        self._current_step_text: str | None = None
+
+        if self.record_mode:
+            self.page.add_init_script(VIRTUAL_CURSOR_SCRIPT)
+            self.page.add_init_script(CAPTION_BANNER_SCRIPT)
+
+    def step(self, caption: str) -> None:
+        """Mark a new narrative step with human-readable on-screen caption banner.
+
+        Args:
+            caption: Subtitle narrative explaining the current action to viewers.
+        """
+        now = time.time() - self.start_time
+
+        if self._current_step_start is not None and self._current_step_text is not None:
+            self.captions.append(
+                (self._current_step_start, now, self._current_step_text)
+            )
+
+        self._current_step_start = now
+        self._current_step_text = caption
+
+        if not self.record_mode:
+            return
+
+        safe_caption = caption.replace("'", "\\'").replace("\n", " ")
+        self.page.evaluate(
+            f"""(() => {{
+                const banner = document.getElementById('hexastack-caption-banner');
+                if (banner) {{
+                    banner.innerText = '{safe_caption}';
+                    banner.style.display = 'block';
+                    banner.style.opacity = '1';
+                }}
+            }})();"""
+        )
+        self.page.wait_for_timeout(400)
+
+    def goto(self, url: str, caption: str | None = None) -> None:
+        """Navigate to a URL with optional step caption."""
+        if caption:
+            self.step(caption)
+        self.page.goto(url)
+        if self.record_mode:
+            self.page.wait_for_timeout(600)
+            if caption:
+                self.step(caption)
+
+    def click(self, locator: Any, caption: str | None = None, steps: int = 35) -> None:
+        """Smoothly click a target element with visual cursor interpolation and caption.
+
+        Args:
+            locator: Playwright Locator or element target.
+            caption: Optional narration text for this specific click.
+            steps: Number of mouse interpolation steps for smooth movement.
+        """
+        if caption:
+            self.step(caption)
+
+        element = locator.first if hasattr(locator, "first") else locator
+
+        if not self.record_mode:
+            element.click()
+            return
+
+        element.scroll_into_view_if_needed()
+        box = element.bounding_box()
+        if not box:
+            element.click()
+            return
+
+        x = box["x"] + box["width"] / 2
+        y = box["y"] + box["height"] / 2
+
+        self.page.mouse.move(x, y, steps=steps)
+        self.page.wait_for_timeout(800)
+
+        self.page.mouse.down()
+        page_timeout = 300
+        self.page.wait_for_timeout(page_timeout)
+        self.page.mouse.up()
+        self.page.wait_for_timeout(700)
+
+    def fill(self, locator: Any, value: str, caption: str | None = None) -> None:
+        """Type text into an input field with optional human-like typing cadence.
+
+        Args:
+            locator: Playwright input locator.
+            value: Text to fill.
+            caption: Optional narration text.
+        """
+        if caption:
+            self.step(caption)
+
+        element = locator.first if hasattr(locator, "first") else locator
+
+        if not self.record_mode:
+            element.fill(value)
+            return
+
+        self.click(element)
+        element.fill("")
+        for char in value:
+            self.page.keyboard.type(char, delay=60)
+        self.page.wait_for_timeout(400)
+
+    def finish(self) -> Path | None:
+        """Complete the demo recording and write WebVTT subtitles to disk.
+
+        Returns:
+            Path to the written .vtt file if in demo mode, or None if in CI mode.
+        """
+        if not self.record_mode:
+            return None
+
+        now = time.time() - self.start_time
+        if self._current_step_start is not None and self._current_step_text is not None:
+            self.captions.append(
+                (self._current_step_start, now, self._current_step_text)
+            )
+
+        self.page.wait_for_timeout(1000)
+
+        # Generate WebVTT content
+        vtt_lines = ["WEBVTT", ""]
+        for idx, (start_s, end_s, text) in enumerate(self.captions, start=1):
+            vtt_lines.append(str(idx))
+            vtt_lines.append(
+                f"{self._format_vtt_time(start_s)} --> {self._format_vtt_time(end_s)}"
+            )
+            vtt_lines.append(text)
+            vtt_lines.append("")
+
+        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")
+        return vtt_path
+
+    @staticmethod
+    def _format_vtt_time(seconds: float) -> str:
+        """Format seconds float into standard WebVTT timestamp (HH:MM:SS.mmm)."""
+        hrs = int(seconds // 3600)
+        mins = int((seconds % 3600) // 60)
+        secs = int(seconds % 60)
+        millis = int(round((seconds - int(seconds)) * 1000))
+        return f"{hrs:02d}:{mins:02d}:{secs:02d}.{millis:03d}"
+
+
+__all__ = [
+    "DemoNarrator",
+]

hexastack_fastapi/testing/server.py

@@ -0,0 +1,120 @@
+"""Ephemeral background server utility for Playwright and integration testing."""
+
+from __future__ import annotations
+
+import http.client
+import os
+import socket
+import subprocess
+import sys
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+
+def find_free_port() -> int:
+    """Find a dynamically available free TCP port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+class EphemeralServer:
+    """Manages lifecycle of an ephemeral Uvicorn web server running in background."""
+
+    def __init__(
+        self,
+        app_factory_code: str,
+        port: int | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize ephemeral server with Python factory script code.
+
+        Args:
+            app_factory_code: Python code string that creates and runs the ASGI app.
+            port: Optional fixed port. If omitted, finds an ephemeral free port.
+            env: Optional environment variables dictionary for subprocess.
+        """
+        self.port = port or find_free_port()
+        self.app_factory_code = app_factory_code
+        self.env = env
+        self.proc: subprocess.Popen[Any] | None = None
+        self.base_url = f"http://127.0.0.1:{self.port}"
+
+    def start(self, ready_path: str = "/", timeout: float = 10.0) -> str:
+        """Start the server process and poll until healthy.
+
+        Args:
+            ready_path: Relative URL path to poll for HTTP 200 readiness.
+            timeout: Maximum seconds to wait before failing.
+
+        Returns:
+            The base URL of the running server.
+
+        Raises:
+            RuntimeError: If server fails to start within timeout.
+        """
+        cmd = [
+            sys.executable,
+            "-c",
+            self.app_factory_code.format(port=self.port),
+        ]
+        proc_env = dict(os.environ)
+        if self.env:
+            proc_env.update(self.env)
+
+        self.proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=proc_env,
+        )
+
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=1.0)
+                conn.request("GET", ready_path)
+                resp = conn.getresponse()
+                if resp.status in (200, 404):  # Responding is ready
+                    conn.close()
+                    return self.base_url
+                conn.close()
+            except Exception:
+                time.sleep(0.25)
+
+        self.stop()
+        raise RuntimeError(f"Ephemeral server failed to start at {self.base_url}")
+
+    def stop(self) -> None:
+        """Stop and terminate the background server process."""
+        if self.proc is not None:
+            self.proc.terminate()
+            try:
+                self.proc.wait(timeout=3.0)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+            self.proc = None
+
+
+@contextmanager
+def ephemeral_server(
+    app_factory_code: str,
+    ready_path: str = "/",
+    env: dict[str, str] | None = None,
+) -> Generator[str]:
+    """Context manager launching an ephemeral server on a free port."""
+    server = EphemeralServer(app_factory_code, env=env)
+    try:
+        url = server.start(ready_path=ready_path)
+        yield url
+    finally:
+        server.stop()
+
+
+__all__ = [
+    "ephemeral_server",
+    "EphemeralServer",
+    "find_free_port",
+]