svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/api/fastapi/dual/dualize.py

@@ -1,22 +1,30 @@
 from __future__ import annotations
 
-from typing import Callable, Sequence
+from typing import Callable
 
 from fastapi import APIRouter
-from fastapi.routing import APIRoute
 
 from .protected import protected_router, service_router, user_router
 from .public import public_router
 from .router import DualAPIRouter
-from .utils import _alt_with_slash, _norm_primary
 
 
 def dualize_into(
     src: APIRouter, dst_factory: Callable[..., DualAPIRouter], *, show_in_schema=True
 ) -> DualAPIRouter:
-    """Clone routes from an APIRouter into a new DualAPIRouter created by `dst_factory`."""
+    """
+    Clone `src` into a DualAPIRouter without re-parsing the primary endpoints.
+
+    Strategy:
+      1) Create an empty DualAPIRouter (prefix="").
+      2) Include the original router `src` so the *original* APIRoute objects
+         (and their already-resolved request models) are used and shown in OpenAPI.
+      3) Add *hidden* trailing-slash twins that point to the same endpoint callables.
+         These don’t show in OpenAPI, so re-parsing them is harmless.
+    """
+    # IMPORTANT: make a fresh router with NO prefix; we will include `src` with its own prefix.
     dst = dst_factory(
-        prefix=src.prefix,
+        prefix="",  # prevent double-prefixing on include_router
         tags=list(src.tags or []),
         dependencies=list(src.dependencies or []),
         default_response_class=src.default_response_class,  # type: ignore[arg-type]
@@ -29,17 +37,37 @@ def dualize_into(
         on_shutdown=list(src.on_shutdown),
     )
 
+    # 1) Keep original routes *intact* (OpenAPI stays correct).
+    #    We pass prefix=src.prefix so paths remain the same.
+    dst.include_router(
+        src,
+        prefix=src.prefix,
+        tags=src.tags,
+        include_in_schema=show_in_schema,
+    )
+
+    # 2) Add hidden trailing-slash twins (no OpenAPI).
+    from fastapi.routing import APIRoute
+
+    from .utils import _alt_with_slash, _norm_primary
+
     for r in src.routes:
         if not isinstance(r, APIRoute):
             continue
 
-        methods: Sequence[str] = sorted(r.methods or [])
+        methods = sorted(r.methods or [])
         primary = _norm_primary(r.path)
         alt = _alt_with_slash(r.path)
 
-        # visible primary (no trailing slash)
+        if alt == primary:
+            continue
+
+        # Build full path using the same prefix we used for include_router
+        alt_full = f"{src.prefix}{alt}"
+
+        # Add a hidden twin. Re-parsing here is okay because this route is not in the schema.
         dst.add_api_route(
-            primary,
+            alt_full,
             r.endpoint,
             methods=list(methods),
             response_model=r.response_model,
@@ -51,37 +79,14 @@ def dualize_into(
             responses=r.responses,
             deprecated=r.deprecated,
             name=r.name,
-            operation_id=r.operation_id,
+            operation_id=None,
             response_class=r.response_class,
             response_description=r.response_description,
             callbacks=r.callbacks,
             openapi_extra=r.openapi_extra,
-            include_in_schema=show_in_schema,
+            include_in_schema=False,
         )
 
-        # hidden twin (with trailing slash)
-        if alt != primary:
-            dst.add_api_route(
-                alt,
-                r.endpoint,
-                methods=list(methods),
-                response_model=r.response_model,
-                status_code=r.status_code,
-                tags=r.tags,
-                dependencies=r.dependencies,
-                summary=r.summary,
-                description=r.description,
-                responses=r.responses,
-                deprecated=r.deprecated,
-                name=r.name,
-                operation_id=None,
-                response_class=r.response_class,
-                response_description=r.response_description,
-                callbacks=r.callbacks,
-                openapi_extra=r.openapi_extra,
-                include_in_schema=False,
-            )
-
     return dst
 
 

svc_infra/api/fastapi/dual/router.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from typing import Any, Callable
+from typing import Any, Callable, Type
 
 from fastapi import APIRouter
+from fastapi.params import Depends
+from pydantic import BaseModel
 
+from ..pagination import Paginated, make_pagination_injector
 from .utils import _alt_with_slash, _norm_primary
 
 
@@ -85,6 +88,50 @@ class DualAPIRouter(APIRouter):
     def head(self, path: str, *_, show_in_schema: bool = True, **kwargs: Any):
         return self._dual_decorator(path, ["HEAD"], show_in_schema=show_in_schema, **kwargs)
 
+    def list(
+        self,
+        path: str,
+        *,
+        model: Type[BaseModel],
+        envelope: bool = False,
+        cursor: bool = True,
+        page: bool = True,
+        default_limit: int = 50,
+        max_limit: int = 200,
+        show_in_schema: bool = True,
+        **kwargs: Any,
+    ):
+        """
+        Sugar for list endpoints.
+
+        - Auto-inject pagination/filter context (no Depends in your signature).
+        - Auto-picks response_model: list[model] or Paginated[model].
+        - Works with your OpenAPI mutators which already attach the shared params.
+        - Per-route opt-out of OpenAPI param auto-attach: openapi_extra={"x_no_auto_pagination": True}
+        """
+        # pick response model
+        if envelope:
+            response_model = Paginated[model]  # type: ignore[index]
+        else:
+            response_model = list[model]  # type: ignore[index]
+
+        injector = make_pagination_injector(
+            envelope=envelope,
+            allow_cursor=cursor,
+            allow_page=page,
+            default_limit=default_limit,
+            max_limit=max_limit,
+        )
+
+        # ensure our injector runs; don't mutate caller's dependencies
+        deps = list(kwargs.get("dependencies") or [])
+        deps.append(Depends(injector))
+        kwargs["dependencies"] = deps
+        kwargs["response_model"] = kwargs.get("response_model") or response_model
+
+        # we still want the dual-registration behavior
+        return self._dual_decorator(path, ["GET"], show_in_schema=show_in_schema, **kwargs)
+
     # ---------- WebSocket ----------
 
     def websocket(self, path: str, *_, **kwargs: Any):

svc_infra/api/fastapi/dx.py

@@ -7,7 +7,7 @@ Usage:
         easy_service_app, easy_service_api, EasyAppOptions, LoggingOptions, ObservabilityOptions,
 
         # Auth bootstrap
-        add_auth, get_auth_settings, AuthSettings, AuthPolicy, DefaultAuthPolicy,
+        add_auth_users, get_auth_settings, AuthSettings, AuthPolicy, DefaultAuthPolicy,
 
         # Identity (endpoint params + router deps + guards)
         Principal, Identity, OptionalIdentity,
@@ -31,7 +31,7 @@ Usage:
 # ----------------
 # Auth bootstrap / config
 # ----------------
-from svc_infra.api.fastapi.auth.add import add_auth
+from svc_infra.api.fastapi.auth.add import add_auth_users
 from svc_infra.api.fastapi.auth.mfa.router import mfa_router
 from svc_infra.api.fastapi.auth.mfa.security import RequireMFAIfEnabled
 from svc_infra.api.fastapi.auth.policy import AuthPolicy, DefaultAuthPolicy
@@ -102,7 +102,7 @@ __all__ = [
     "LoggingOptions",
     "ObservabilityOptions",
     # Auth bootstrap / config
-    "add_auth",
+    "add_auth_users",
     "get_auth_settings",
     "AuthSettings",
     "AuthPolicy",

svc_infra/api/fastapi/http/concurrency.py

@@ -0,0 +1,14 @@
+from fastapi import HTTPException, Request, status
+
+
+def require_if_match(request: Request, current_etag: str):
+    val = request.headers.get("If-Match")
+    if not val:
+        raise HTTPException(
+            status_code=status.HTTP_428_PRECONDITION_REQUIRED,
+            detail="If-Match header required for update.",
+        )
+    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."
+        )

svc_infra/api/fastapi/http/conditional.py

@@ -0,0 +1,33 @@
+from datetime import datetime, timezone
+from email.utils import format_datetime, parsedate_to_datetime
+from hashlib import sha256
+
+from fastapi import Request, Response
+
+
+def compute_etag(payload: bytes) -> str:
+    return '"' + sha256(payload).hexdigest() + '"'
+
+
+def set_conditional_headers(
+    resp: Response, etag: str | None = None, last_modified: datetime | None = None
+):
+    if etag:
+        resp.headers["ETag"] = etag
+    if last_modified:
+        if last_modified.tzinfo is None:
+            last_modified = last_modified.replace(tzinfo=timezone.utc)
+        resp.headers["Last-Modified"] = format_datetime(last_modified)
+
+
+def maybe_not_modified(request: Request, etag: str | None, last_modified: datetime | None) -> bool:
+    inm = request.headers.get("If-None-Match")
+    ims = request.headers.get("If-Modified-Since")
+    etag_ok = etag and inm and etag in [t.strip() for t in inm.split(",")]
+    time_ok = False
+    if last_modified and ims:
+        try:
+            time_ok = parsedate_to_datetime(ims) >= last_modified
+        except Exception:
+            pass
+    return bool(etag_ok or time_ok)

svc_infra/api/fastapi/http/deprecation.py

@@ -0,0 +1,21 @@
+from functools import wraps
+
+
+def deprecated(sunset_http_date: str | None = None, link: str | None = None):
+    def deco(handler):
+        @wraps(handler)
+        async def wrapper(*a, **kw):
+            resp = await handler(*a, **kw)
+            # starlette Response or FastAPI returns both OK
+            headers = getattr(resp, "headers", None)
+            if headers is not None:
+                headers.setdefault("Deprecation", "true")
+                if sunset_http_date:
+                    headers.setdefault("Sunset", sunset_http_date)
+                if link:
+                    headers.setdefault("Link", f'<{link}>; rel="deprecation"')
+            return resp
+
+        return wrapper
+
+    return deco

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

@@ -2,6 +2,7 @@ import logging
 import traceback
 from typing import Any, Dict, Optional
 
+import httpx
 from fastapi import Request
 from fastapi.exceptions import HTTPException, RequestValidationError
 from fastapi.responses import JSONResponse, Response
@@ -46,6 +47,7 @@ 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] = {
         "type": type_uri,
@@ -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,25 @@ 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:
+            if getattr(exc, "headers", None):
+                # FastAPI/Starlette exceptions store headers as a dict[str, str]
+                hdrs = dict(getattr(exc, "headers"))  # type: ignore[arg-type]
+        except Exception:
+            hdrs = None
         return problem_response(
             status=exc.status_code,
             title=title,
@@ -119,19 +146,29 @@ 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:
+            if getattr(exc, "headers", None):
+                hdrs = dict(getattr(exc, "headers"))  # type: ignore[arg-type]
+        except Exception:
+            hdrs = None
         return problem_response(
             status=exc.status_code,
             title=title,
@@ -139,6 +176,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,87 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Optional
+
+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
+        state = scope.get("app").state  # type: ignore[attr-defined]
+        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: Optional[float] = 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):  # noqa: ANN202
+        # 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

svc_infra/api/fastapi/middleware/idempotency.py

@@ -0,0 +1,116 @@
+import base64
+import hashlib
+import time
+from typing import Annotated, Dict, Optional
+
+from fastapi import Header, HTTPException, Request
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse, Response
+
+from .idempotency_store import IdempotencyStore, InMemoryIdempotencyStore
+
+
+class IdempotencyMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app,
+        ttl_seconds: int = 24 * 3600,
+        store: Optional[IdempotencyStore] = None,
+        header_name: str = "Idempotency-Key",
+    ):
+        super().__init__(app)
+        self.ttl = ttl_seconds
+        self.store: IdempotencyStore = store or InMemoryIdempotencyStore()
+        self.header_name = header_name
+
+    def _cache_key(self, request, idkey: str):
+        # The cache key must NOT include the body to allow conflict detection for mismatched payloads.
+        sig = hashlib.sha256(
+            (request.method + "|" + request.url.path + "|" + idkey).encode()
+        ).hexdigest()
+        return f"idmp:{sig}"
+
+    async def dispatch(self, request, call_next):
+        if request.method in {"POST", "PATCH", "DELETE"}:
+            # read & buffer body once
+            body = await request.body()
+            request._body = body
+            idkey = request.headers.get(self.header_name)
+            if idkey:
+                k = self._cache_key(request, idkey)
+                now = time.time()
+                # build request hash to detect mismatched replays
+                req_hash = hashlib.sha256(body or b"").hexdigest()
+
+                existing = self.store.get(k)
+                if existing and existing.exp > now:
+                    # If payload mismatches any existing claim, return conflict
+                    if existing.req_hash and existing.req_hash != req_hash:
+                        return JSONResponse(
+                            status_code=409,
+                            content={
+                                "type": "about:blank",
+                                "title": "Conflict",
+                                "detail": "Idempotency-Key re-used with different request payload.",
+                            },
+                        )
+                    # If response cached and payload matches, replay it
+                    if existing.status is not None and existing.body_b64 is not None:
+                        return Response(
+                            content=base64.b64decode(existing.body_b64),
+                            status_code=existing.status,
+                            headers=existing.headers or {},
+                            media_type=existing.media_type,
+                        )
+
+                # Claim the key if not present
+                exp = now + self.ttl
+                created = self.store.set_initial(k, req_hash, exp)
+                if not created:
+                    # Someone else claimed; re-check for conflict or replay
+                    existing = self.store.get(k)
+                    if existing and existing.req_hash and existing.req_hash != req_hash:
+                        return JSONResponse(
+                            status_code=409,
+                            content={
+                                "type": "about:blank",
+                                "title": "Conflict",
+                                "detail": "Idempotency-Key re-used with different request payload.",
+                            },
+                        )
+                    if existing and existing.status is not None and existing.body_b64 is not None:
+                        return Response(
+                            content=base64.b64decode(existing.body_b64),
+                            status_code=existing.status,
+                            headers=existing.headers or {},
+                            media_type=existing.media_type,
+                        )
+
+                # Proceed to handler
+                resp = await call_next(request)
+                if 200 <= resp.status_code < 300:
+                    body_bytes = b"".join([section async for section in resp.body_iterator])
+                    headers: Dict[str, str] = dict(resp.headers)
+                    self.store.set_response(
+                        k,
+                        status=resp.status_code,
+                        body=body_bytes,
+                        headers=headers,
+                        media_type=resp.media_type,
+                    )
+                    return Response(
+                        content=body_bytes,
+                        status_code=resp.status_code,
+                        headers=headers,
+                        media_type=resp.media_type,
+                    )
+                return resp
+        return await call_next(request)
+
+
+async def require_idempotency_key(
+    idempotency_key: Annotated[str, Header(alias="Idempotency-Key")],
+    request: Request,
+) -> None:
+    if not idempotency_key.strip():
+        raise HTTPException(status_code=400, detail="Idempotency-Key must not be empty.")