svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/api/fastapi/dual/router.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Type
+from collections.abc import Callable
+from typing import Any
 
 from fastapi import APIRouter
 from fastapi.params import Depends
@@ -37,10 +38,14 @@ class DualAPIRouter(APIRouter):
             if is_rootish:
                 # primary root
                 self.add_api_route(
-                    "", func, methods=methods, include_in_schema=show_in_schema, **kwargs
+                    "",
+                    func,
+                    methods=methods,
+                    include_in_schema=show_in_schema,
+                    **kwargs,
                 )
                 # only add the "/" twin for *safe* methods
-                if set(m.upper() for m in methods) <= safe_methods:
+                if {m.upper() for m in methods} <= safe_methods:
                     self.add_api_route(
                         "/", func, methods=methods, include_in_schema=False, **kwargs
                     )
@@ -48,7 +53,11 @@ class DualAPIRouter(APIRouter):
 
             # non-root unchanged
             self.add_api_route(
-                primary, func, methods=methods, include_in_schema=show_in_schema, **kwargs
+                primary,
+                func,
+                methods=methods,
+                include_in_schema=show_in_schema,
+                **kwargs,
             )
             if alt != primary:
                 self.add_api_route(alt, func, methods=methods, include_in_schema=False, **kwargs)
@@ -57,7 +66,7 @@ class DualAPIRouter(APIRouter):
         return decorator
 
     def add_api_route(self, path, endpoint, **kwargs):
-        methods = set((kwargs.get("methods") or []))
+        methods = set(kwargs.get("methods") or [])
         for r in self.routes:
             if getattr(r, "path", None) == path and methods & (
                 getattr(r, "methods", set()) or set()
@@ -92,7 +101,7 @@ class DualAPIRouter(APIRouter):
         self,
         path: str,
         *,
-        model: Type[BaseModel],
+        model: type[BaseModel],
         envelope: bool = False,
         cursor: bool = True,
         page: bool = True,
@@ -110,10 +119,11 @@ class DualAPIRouter(APIRouter):
         - Per-route opt-out of OpenAPI param auto-attach: openapi_extra={"x_no_auto_pagination": True}
         """
         # pick response model
+        response_model: Any
         if envelope:
-            response_model = Paginated[model]  # type: ignore[index]
+            response_model = Paginated[model]  # type: ignore[valid-type]
         else:
-            response_model = list[model]  # type: ignore[index]
+            response_model = list[model]  # type: ignore[valid-type]
 
         injector = make_pagination_injector(
             envelope=envelope,

svc_infra/api/fastapi/dx.py

@@ -59,19 +59,36 @@ from svc_infra.api.fastapi.auth.security import (
     RequireUser,
 )
 from svc_infra.api.fastapi.auth.settings import AuthSettings, get_auth_settings
-from svc_infra.api.fastapi.dual.protected import (
+
+# ----------------
+# WebSocket identity primitives (lightweight JWT, no DB required)
+# ----------------
+from svc_infra.api.fastapi.auth.ws_security import (
+    AllowWSIdentity,
+    OptionalWSIdentity,
+    RequireWSAnyScope,
+    RequireWSIdentity,
+    RequireWSScopes,
+    WSIdentity,
+    WSPrincipal,
+)
+from svc_infra.api.fastapi.dual.protected import (  # WebSocket routers (DualAPIRouter with JWT auth, no DB required)
     optional_identity_router,
     protected_router,
     roles_router,
     scopes_router,
     service_router,
     user_router,
+    ws_optional_router,
+    ws_protected_router,
+    ws_scopes_router,
+    ws_user_router,
 )
 
 # ----------------
 # Pre-wired routers (OpenAPI security auto-injected)
 # ----------------
-from svc_infra.api.fastapi.dual.public import public_router
+from svc_infra.api.fastapi.dual.public import public_router, ws_public_router
 
 # ----------------
 # App bootstrap
@@ -127,6 +144,20 @@ __all__ = [
     "service_router",
     "scopes_router",
     "roles_router",
+    # WebSocket identity
+    "WSPrincipal",
+    "WSIdentity",
+    "OptionalWSIdentity",
+    "RequireWSIdentity",
+    "AllowWSIdentity",
+    "RequireWSScopes",
+    "RequireWSAnyScope",
+    # WebSocket routers
+    "ws_public_router",
+    "ws_protected_router",
+    "ws_user_router",
+    "ws_scopes_router",
+    "ws_optional_router",
     # Feature routers
     "apikey_router",
     "mfa_router",

svc_infra/api/fastapi/ease.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import os
-from typing import Iterable, Sequence
+from collections.abc import Iterable, Sequence
 
 from fastapi import FastAPI
 from pydantic import BaseModel, Field
@@ -64,7 +64,7 @@ class EasyAppOptions(BaseModel):
     observability: ObservabilityOptions = ObservabilityOptions()
 
     @classmethod
-    def from_env(cls) -> "EasyAppOptions":
+    def from_env(cls) -> EasyAppOptions:
         """
         Build options from environment variables:
 
@@ -88,7 +88,7 @@ class EasyAppOptions(BaseModel):
             ),
         )
 
-    def merged_with(self, override: "EasyAppOptions | None") -> "EasyAppOptions":
+    def merged_with(self, override: EasyAppOptions | None) -> EasyAppOptions:
         """
         Merge two option sets. Non-None fields in `override` win.
         (For iterables, if override provides a non-None value, it wins entirely.)
@@ -148,7 +148,33 @@ def easy_service_api(
     public_cors_origins: list[str] | str | None = None,
     root_public_base_url: str | None = None,
     root_include_api_key: bool | None = None,
+    skip_paths: list[str] | None = None,
+    **fastapi_kwargs,  # Forward all other FastAPI kwargs
 ) -> FastAPI:
+    """
+    Create a FastAPI application with standard service configuration.
+
+    Args:
+        name: Service name for OpenAPI docs and logging.
+        release: Version string for the service.
+        versions: List of (tag, routers_package, public_base_url) tuples for API versioning.
+        root_routers: Router module(s) to mount at root level.
+        public_cors_origins: Origins to allow for CORS.
+        root_public_base_url: Public base URL for root-level routes.
+        root_include_api_key: Whether to include API key auth for root routes.
+        skip_paths: Path prefixes to exclude from timeout/rate-limit middleware.
+            Uses prefix matching: "/v1/chat" matches "/v1/chat" and "/v1/chat/stream"
+            but not "/api/v1/chat". Falls back to SKIP_MIDDLEWARE_PATHS env var.
+        **fastapi_kwargs: Additional kwargs passed to FastAPI constructor.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    # Env fallback for skip_paths
+    effective_skip = (
+        skip_paths if skip_paths is not None else _env_csv_paths("SKIP_MIDDLEWARE_PATHS")
+    )
+
     service = ServiceInfo(name=name, release=release)
     specs = [
         APIVersionSpec(tag=str(tag), routers_package=pkg, public_base_url=base)
@@ -161,6 +187,8 @@ def easy_service_api(
         public_cors_origins=public_cors_origins,
         root_public_base_url=root_public_base_url,
         root_include_api_key=root_include_api_key,
+        skip_paths=effective_skip,
+        **fastapi_kwargs,  # Forward to setup_service_api
     )
 
 
@@ -173,25 +201,47 @@ def easy_service_app(
     public_cors_origins: list[str] | str | None = None,
     root_public_base_url: str | None = None,
     root_include_api_key: bool | None = None,
+    skip_paths: list[str] | None = None,
     options: EasyAppOptions | None = None,
     enable_logging: bool | None = None,
     enable_observability: bool | None = None,
+    **fastapi_kwargs,  # Forward all other FastAPI kwargs (lifespan, etc.)
 ) -> FastAPI:
     """
-    One-call bootstrap with env + options + flags:
-
-      Precedence (strongest → weakest):
+    One-call bootstrap with env + options + flags.
+
+    Args:
+        name: Service name for OpenAPI docs and logging.
+        release: Version string for the service.
+        versions: List of (tag, routers_package, public_base_url) tuples for API versioning.
+        root_routers: Router module(s) to mount at root level.
+        public_cors_origins: Origins to allow for CORS.
+        root_public_base_url: Public base URL for root-level routes.
+        root_include_api_key: Whether to include API key auth for root routes.
+        skip_paths: Path prefixes to exclude from timeout/rate-limit middleware.
+            Uses prefix matching: "/v1/chat" matches "/v1/chat" and "/v1/chat/stream"
+            but not "/api/v1/chat". Falls back to SKIP_MIDDLEWARE_PATHS env var.
+        options: EasyAppOptions for logging/observability configuration.
+        enable_logging: Override to enable/disable logging.
+        enable_observability: Override to enable/disable observability.
+        **fastapi_kwargs: Additional kwargs passed to FastAPI constructor.
+
+    Precedence (strongest → weakest):
         1) enable_logging / enable_observability args
         2) `options=` object (per-field)
         3) `EasyAppOptions.from_env()`
 
-      Env recognized:
+    Env recognized:
         ENABLE_LOGGING=true|false
         ENABLE_OBS=true|false
         LOG_LEVEL=DEBUG|INFO|...
         LOG_FORMAT=json|plain
         METRICS_PATH=/metrics
         OBS_SKIP_PATHS=/metrics,/health,/internal
+        SKIP_MIDDLEWARE_PATHS=/v1/chat,/v1/stream (for timeout/rate-limit skip)
+
+    Returns:
+        Configured FastAPI application with logging and observability.
     """
     # 0) Start from env
     env_opts = EasyAppOptions.from_env()
@@ -226,6 +276,8 @@ def easy_service_app(
         public_cors_origins=public_cors_origins,
         root_public_base_url=root_public_base_url,
         root_include_api_key=root_include_api_key,
+        skip_paths=skip_paths,
+        **fastapi_kwargs,  # Forward FastAPI kwargs (lifespan, etc.)
     )
 
     # 5) Observability

svc_infra/api/fastapi/http/concurrency.py

@@ -10,5 +10,6 @@ def require_if_match(request: Request, current_etag: str):
         )
     if current_etag not in [t.strip() for t in val.split(",")]:
         raise HTTPException(
-            status_code=status.HTTP_412_PRECONDITION_FAILED, detail="ETag precondition failed."
+            status_code=status.HTTP_412_PRECONDITION_FAILED,
+            detail="ETag precondition failed.",
         )

svc_infra/api/fastapi/http/conditional.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from email.utils import format_datetime, parsedate_to_datetime
 from hashlib import sha256
 
@@ -16,7 +16,7 @@ def set_conditional_headers(
         resp.headers["ETag"] = etag
     if last_modified:
         if last_modified.tzinfo is None:
-            last_modified = last_modified.replace(tzinfo=timezone.utc)
+            last_modified = last_modified.replace(tzinfo=UTC)
         resp.headers["Last-Modified"] = format_datetime(last_modified)
 
 

svc_infra/api/fastapi/middleware/debug.py

@@ -15,6 +15,9 @@ class RouteDebugMiddleware(BaseHTTPMiddleware):
         route = request.scope.get("route")
         ep = getattr(route, "endpoint", None) if route else None
         log.info(
-            "MATCHED %s %s -> %s", request.method, request.url.path, getattr(ep, "__name__", ep)
+            "MATCHED %s %s -> %s",
+            request.method,
+            request.url.path,
+            getattr(ep, "__name__", ep),
         )
         return response

svc_infra/api/fastapi/middleware/errors/exceptions.py

@@ -1,6 +1,3 @@
-from typing import Optional
-
-
 class FastApiException(Exception):
     """
     Application error that should be rendered as Problem Details.
@@ -9,10 +6,10 @@ class FastApiException(Exception):
     def __init__(
         self,
         title: str,
-        detail: Optional[str] = None,
+        detail: str | None = None,
         status_code: int = 400,
         *,
-        code: str | None = None
+        code: str | None = None,
     ):
         self.title = title
         self.detail = detail

svc_infra/api/fastapi/middleware/errors/handlers.py

@@ -1,7 +1,8 @@
 import logging
 import traceback
-from typing import Any, Dict, Optional
+from typing import Any
 
+import httpx
 from fastapi import Request
 from fastapi.exceptions import HTTPException, RequestValidationError
 from fastapi.responses import JSONResponse, Response
@@ -16,7 +17,7 @@ logger = logging.getLogger(__name__)
 PROBLEM_MT = "application/problem+json"
 
 
-def _trace_id_from_request(request: Request) -> Optional[str]:
+def _trace_id_from_request(request: Request) -> str | None:
     # Try common headers first; fall back to None
     for h in ("x-request-id", "x-correlation-id", "x-trace-id"):
         v = request.headers.get(h)
@@ -46,8 +47,9 @@ def problem_response(
     code: str | None = None,
     errors: list[dict] | None = None,
     trace_id: str | None = None,
+    headers: dict[str, str] | None = None,
 ) -> Response:
-    body: Dict[str, Any] = {
+    body: dict[str, Any] = {
         "type": type_uri,
         "title": title,
         "status": status,
@@ -62,10 +64,24 @@ def problem_response(
         body["errors"] = errors
     if trace_id:
         body["trace_id"] = trace_id
-    return JSONResponse(status_code=status, content=body, media_type=PROBLEM_MT)
+    return JSONResponse(status_code=status, content=body, media_type=PROBLEM_MT, headers=headers)
 
 
 def register_error_handlers(app):
+    @app.exception_handler(httpx.TimeoutException)
+    async def handle_httpx_timeout(request: Request, exc: httpx.TimeoutException):
+        trace_id = _trace_id_from_request(request)
+        # Map outbound HTTP client timeouts to 504 Gateway Timeout
+        # Keep details generic in prod
+        return problem_response(
+            status=504,
+            title="Gateway Timeout",
+            detail=("Upstream request timed out." if IS_PROD else (str(exc) or "httpx timeout")),
+            code="GATEWAY_TIMEOUT",
+            instance=str(request.url),
+            trace_id=trace_id,
+        )
+
     @app.exception_handler(FastApiException)
     async def handle_app_exception(request: Request, exc: FastApiException):
         trace_id = _trace_id_from_request(request)
@@ -104,14 +120,26 @@ def register_error_handlers(app):
     @app.exception_handler(HTTPException)
     async def handle_http_exception(request: Request, exc: HTTPException):
         trace_id = _trace_id_from_request(request)
-        title = {401: "Unauthorized", 403: "Forbidden", 404: "Not Found"}.get(
-            exc.status_code, "Error"
-        )
+        title = {
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            429: "Too Many Requests",
+        }.get(exc.status_code, "Error")
         detail = (
             exc.detail
             if not IS_PROD or exc.status_code < 500
             else "Something went wrong. Please contact support."
         )
+        # Preserve headers set on the exception (e.g., Retry-After for rate limits)
+        hdrs: dict[str, str] | None = None
+        try:
+            exc_headers = getattr(exc, "headers", None)
+            if exc_headers is not None:
+                # FastAPI/Starlette exceptions store headers as a dict[str, str]
+                hdrs = dict(exc_headers)
+        except Exception:
+            hdrs = None
         return problem_response(
             status=exc.status_code,
             title=title,
@@ -119,19 +147,30 @@ def register_error_handlers(app):
             code=title.replace(" ", "_").upper(),
             instance=str(request.url),
             trace_id=trace_id,
+            headers=hdrs,
         )
 
     @app.exception_handler(StarletteHTTPException)
     async def handle_starlette_http_exception(request: Request, exc: StarletteHTTPException):
         trace_id = _trace_id_from_request(request)
-        title = {401: "Unauthorized", 403: "Forbidden", 404: "Not Found"}.get(
-            exc.status_code, "Error"
-        )
+        title = {
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            429: "Too Many Requests",
+        }.get(exc.status_code, "Error")
         detail = (
             exc.detail
             if not IS_PROD or exc.status_code < 500
             else "Something went wrong. Please contact support."
         )
+        hdrs: dict[str, str] | None = None
+        try:
+            exc_headers = getattr(exc, "headers", None)
+            if exc_headers is not None:
+                hdrs = dict(exc_headers)
+        except Exception:
+            hdrs = None
         return problem_response(
             status=exc.status_code,
             title=title,
@@ -139,6 +178,7 @@ def register_error_handlers(app):
             code=title.replace(" ", "_").upper(),
             instance=str(request.url),
             trace_id=trace_id,
+            headers=hdrs,
         )
 
     @app.exception_handler(IntegrityError)

svc_infra/api/fastapi/middleware/graceful_shutdown.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from svc_infra.app.env import pick
+
+logger = logging.getLogger(__name__)
+
+
+def _get_grace_period_seconds() -> float:
+    default = pick(prod=20.0, nonprod=5.0)
+    raw = os.getenv("SHUTDOWN_GRACE_PERIOD_SECONDS")
+    if raw is None or raw == "":
+        return float(default)
+    try:
+        return float(raw)
+    except ValueError:
+        return float(default)
+
+
+class InflightTrackerMiddleware:
+    """Tracks number of in-flight requests to support graceful shutdown drains."""
+
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        app = scope.get("app")
+        if app is None:
+            await self.app(scope, receive, send)
+            return
+        state = getattr(app, "state", None)
+        if state is None:
+            await self.app(scope, receive, send)
+            return
+        state._inflight_requests = getattr(state, "_inflight_requests", 0) + 1
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            state._inflight_requests = max(0, getattr(state, "_inflight_requests", 1) - 1)
+
+
+async def _wait_for_drain(app: FastAPI, grace: float) -> None:
+    interval = 0.1
+    waited = 0.0
+    while waited < grace:
+        inflight = int(getattr(app.state, "_inflight_requests", 0))
+        if inflight <= 0:
+            return
+        await asyncio.sleep(interval)
+        waited += interval
+    inflight = int(getattr(app.state, "_inflight_requests", 0))
+    if inflight > 0:
+        logger.warning(
+            "Graceful shutdown timeout: %s in-flight request(s) after %.2fs",
+            inflight,
+            waited,
+        )
+
+
+def install_graceful_shutdown(app: FastAPI, *, grace_seconds: float | None = None) -> None:
+    """Install inflight tracking and lifespan hooks to wait for requests to drain.
+
+    - Adds InflightTrackerMiddleware
+    - Registers a lifespan handler that initializes state and waits up to grace_seconds on shutdown
+    """
+    app.add_middleware(InflightTrackerMiddleware)
+
+    g = float(grace_seconds) if grace_seconds is not None else _get_grace_period_seconds()
+
+    # Preserve any existing lifespan and wrap it so our drain runs on shutdown.
+    previous_lifespan = getattr(app.router, "lifespan_context", None)
+
+    @asynccontextmanager
+    async def _lifespan(a: FastAPI):
+        # Startup: initialize inflight counter
+        a.state._inflight_requests = 0
+        if previous_lifespan is not None:
+            async with previous_lifespan(a):
+                yield
+        else:
+            yield
+        # Shutdown: wait for in-flight requests to drain (up to grace period)
+        await _wait_for_drain(a, g)
+
+    app.router.lifespan_context = _lifespan