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

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

@@ -1,6 +1,6 @@
 import logging
 import traceback
-from typing import Any, Dict, Optional
+from typing import Any
 
 import httpx
 from fastapi import Request
@@ -17,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)
@@ -49,7 +49,7 @@ def problem_response(
     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,
@@ -64,9 +64,7 @@ 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, headers=headers
-    )
+    return JSONResponse(status_code=status, content=body, media_type=PROBLEM_MT, headers=headers)
 
 
 def register_error_handlers(app):
@@ -78,11 +76,7 @@ def register_error_handlers(app):
         return problem_response(
             status=504,
             title="Gateway Timeout",
-            detail=(
-                "Upstream request timed out."
-                if IS_PROD
-                else (str(exc) or "httpx 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,
@@ -140,9 +134,10 @@ def register_error_handlers(app):
         # 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):
+            exc_headers = getattr(exc, "headers", None)
+            if exc_headers is not None:
                 # FastAPI/Starlette exceptions store headers as a dict[str, str]
-                hdrs = dict(getattr(exc, "headers"))
+                hdrs = dict(exc_headers)
         except Exception:
             hdrs = None
         return problem_response(
@@ -156,9 +151,7 @@ def register_error_handlers(app):
         )
 
     @app.exception_handler(StarletteHTTPException)
-    async def handle_starlette_http_exception(
-        request: Request, exc: StarletteHTTPException
-    ):
+    async def handle_starlette_http_exception(request: Request, exc: StarletteHTTPException):
         trace_id = _trace_id_from_request(request)
         title = {
             401: "Unauthorized",
@@ -173,8 +166,9 @@ def register_error_handlers(app):
         )
         hdrs: dict[str, str] | None = None
         try:
-            if getattr(exc, "headers", None):
-                hdrs = dict(getattr(exc, "headers"))
+            exc_headers = getattr(exc, "headers", None)
+            if exc_headers is not None:
+                hdrs = dict(exc_headers)
         except Exception:
             hdrs = None
         return problem_response(

svc_infra/api/fastapi/middleware/graceful_shutdown.py

@@ -4,7 +4,6 @@ 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
@@ -47,9 +46,7 @@ class InflightTrackerMiddleware:
         try:
             await self.app(scope, receive, send)
         finally:
-            state._inflight_requests = max(
-                0, getattr(state, "_inflight_requests", 1) - 1
-            )
+            state._inflight_requests = max(0, getattr(state, "_inflight_requests", 1) - 1)
 
 
 async def _wait_for_drain(app: FastAPI, grace: float) -> None:
@@ -70,9 +67,7 @@ async def _wait_for_drain(app: FastAPI, grace: float) -> None:
         )
 
 
-def install_graceful_shutdown(
-    app: FastAPI, *, grace_seconds: Optional[float] = None
-) -> None:
+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
@@ -80,17 +75,13 @@ def install_graceful_shutdown(
     """
     app.add_middleware(InflightTrackerMiddleware)
 
-    g = (
-        float(grace_seconds)
-        if grace_seconds is not None
-        else _get_grace_period_seconds()
-    )
+    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
+    async def _lifespan(a: FastAPI):
         # Startup: initialize inflight counter
         a.state._inflight_requests = 0
         if previous_lifespan is not None:

svc_infra/api/fastapi/middleware/idempotency.py

@@ -2,7 +2,7 @@ import base64
 import hashlib
 import json
 import time
-from typing import Annotated, Optional
+from typing import Annotated
 
 from fastapi import Header, HTTPException, Request
 from starlette.types import ASGIApp, Receive, Scope, Send
@@ -17,15 +17,18 @@ class IdempotencyMiddleware:
     Caches responses for requests with Idempotency-Key header to ensure
     duplicate requests return the same response. Use skip_paths for endpoints
     where idempotency caching is not appropriate (e.g., streaming responses).
+
+    Matching uses prefix matching: "/v1/chat" matches "/v1/chat", "/v1/chat/stream",
+    but not "/api/v1/chat" or "/v1/chatter".
     """
 
     def __init__(
         self,
         app: ASGIApp,
         ttl_seconds: int = 24 * 3600,
-        store: Optional[IdempotencyStore] = None,
+        store: IdempotencyStore | None = None,
         header_name: str = "Idempotency-Key",
-        skip_paths: Optional[list[str]] = None,
+        skip_paths: list[str] | None = None,
     ):
         self.app = app
         self.ttl = ttl_seconds
@@ -45,8 +48,8 @@ class IdempotencyMiddleware:
         path = scope.get("path", "")
         method = scope.get("method", "GET")
 
-        # Skip specified paths
-        if any(skip in path for skip in self.skip_paths):
+        # Skip specified paths using prefix matching
+        if any(path.startswith(skip) for skip in self.skip_paths):
             await self.app(scope, receive, send)
             return
 
@@ -115,11 +118,7 @@ class IdempotencyMiddleware:
                     },
                 )
                 return
-            if (
-                existing
-                and existing.status is not None
-                and existing.body_b64 is not None
-            ):
+            if existing and existing.status is not None and existing.body_b64 is not None:
                 await self._send_cached_response(send, existing)
                 return
 
@@ -182,9 +181,7 @@ class IdempotencyMiddleware:
         await send({"type": "http.response.body", "body": body, "more_body": False})
 
     async def _send_cached_response(self, send, existing) -> None:
-        headers = [
-            (k.encode(), v.encode()) for k, v in (existing.headers or {}).items()
-        ]
+        headers = [(k.encode(), v.encode()) for k, v in (existing.headers or {}).items()]
         if existing.media_type:
             headers.append((b"content-type", existing.media_type.encode()))
         await send(
@@ -208,6 +205,4 @@ async def require_idempotency_key(
     request: Request,
 ) -> None:
     if not idempotency_key.strip():
-        raise HTTPException(
-            status_code=400, detail="Idempotency-Key must not be empty."
-        )
+        raise HTTPException(status_code=400, detail="Idempotency-Key must not be empty.")

svc_infra/api/fastapi/middleware/idempotency_store.py

@@ -4,7 +4,7 @@ import base64
 import json
 import time
 from dataclasses import dataclass
-from typing import Dict, Optional, Protocol
+from typing import Protocol
 
 
 @dataclass
@@ -12,14 +12,14 @@ class IdempotencyEntry:
     req_hash: str
     exp: float
     # Optional response fields when available
-    status: Optional[int] = None
-    body_b64: Optional[str] = None
-    headers: Optional[Dict[str, str]] = None
-    media_type: Optional[str] = None
+    status: int | None = None
+    body_b64: str | None = None
+    headers: dict[str, str] | None = None
+    media_type: str | None = None
 
 
 class IdempotencyStore(Protocol):
-    def get(self, key: str) -> Optional[IdempotencyEntry]:
+    def get(self, key: str) -> IdempotencyEntry | None:
         pass
 
     def set_initial(self, key: str, req_hash: str, exp: float) -> bool:
@@ -32,8 +32,8 @@ class IdempotencyStore(Protocol):
         *,
         status: int,
         body: bytes,
-        headers: Dict[str, str],
-        media_type: Optional[str],
+        headers: dict[str, str],
+        media_type: str | None,
     ) -> None:
         pass
 
@@ -45,7 +45,7 @@ class InMemoryIdempotencyStore:
     def __init__(self):
         self._store: dict[str, IdempotencyEntry] = {}
 
-    def get(self, key: str) -> Optional[IdempotencyEntry]:
+    def get(self, key: str) -> IdempotencyEntry | None:
         entry = self._store.get(key)
         if not entry:
             return None
@@ -69,8 +69,8 @@ class InMemoryIdempotencyStore:
         *,
         status: int,
         body: bytes,
-        headers: Dict[str, str],
-        media_type: Optional[str],
+        headers: dict[str, str],
+        media_type: str | None,
     ) -> None:
         entry = self._store.get(key)
         if not entry:
@@ -102,7 +102,7 @@ class RedisIdempotencyStore:
     def _k(self, key: str) -> str:
         return f"{self.prefix}:{key}"
 
-    def get(self, key: str) -> Optional[IdempotencyEntry]:
+    def get(self, key: str) -> IdempotencyEntry | None:
         raw = self.r.get(self._k(key))
         if not raw:
             return None
@@ -156,8 +156,8 @@ class RedisIdempotencyStore:
         *,
         status: int,
         body: bytes,
-        headers: Dict[str, str],
-        media_type: Optional[str],
+        headers: dict[str, str],
+        media_type: str | None,
     ) -> None:
         entry = self.get(key)
         if not entry:

svc_infra/api/fastapi/middleware/optimistic_lock.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-from typing import Annotated, Any, Callable, Optional
+from collections.abc import Callable
+from typing import Annotated, Any
 
 from fastapi import Header, HTTPException
 
 
 async def require_if_match(
-    version: Annotated[Optional[str], Header(alias="If-Match")] = None,
+    version: Annotated[str | None, Header(alias="If-Match")] = None,
 ) -> str:
     """Require If-Match header for optimistic locking on mutating operations.
 
@@ -31,12 +32,8 @@ def check_version_or_409(get_current_version: Callable[[], Any], provided: str)
         try:
             p = int(provided)
         except Exception:
-            raise HTTPException(
-                status_code=400, detail="Invalid If-Match value; expected integer."
-            )
+            raise HTTPException(status_code=400, detail="Invalid If-Match value; expected integer.")
     else:
         p = provided
     if p != current:
-        raise HTTPException(
-            status_code=409, detail="Version mismatch (optimistic locking)."
-        )
+        raise HTTPException(status_code=409, detail="Version mismatch (optimistic locking).")

svc_infra/api/fastapi/middleware/ratelimit.py

@@ -23,6 +23,9 @@ class SimpleRateLimitMiddleware:
 
     Applies per-key rate limits with configurable windows. Use skip_paths for
     endpoints that should bypass rate limiting (e.g., health checks, webhooks).
+
+    Matching uses prefix matching: "/v1/chat" matches "/v1/chat", "/v1/chat/stream",
+    but not "/api/v1/chat" or "/v1/chatter".
     """
 
     def __init__(
@@ -60,8 +63,8 @@ class SimpleRateLimitMiddleware:
 
         path = scope.get("path", "")
 
-        # Skip specified paths
-        if any(skip in path for skip in self.skip_paths):
+        # Skip specified paths using prefix matching
+        if any(path.startswith(skip) for skip in self.skip_paths):
             await self.app(scope, receive, send)
             return
 
@@ -70,8 +73,7 @@ class SimpleRateLimitMiddleware:
 
         # Default key function
         key_fn = self.key_fn or (
-            lambda r: r.headers.get("X-API-Key")
-            or (r.client.host if r.client else "unknown")
+            lambda r: r.headers.get("X-API-Key") or (r.client.host if r.client else "unknown")
         )
 
         # Resolve tenant when possible
@@ -85,9 +87,7 @@ class SimpleRateLimitMiddleware:
             # Fallback header behavior - ONLY if explicitly allowed
             # Never trust untrusted headers by default to prevent rate limit evasion
             if not tenant_id and self._allow_untrusted_tenant_header:
-                tenant_id = request.headers.get("X-Tenant-Id") or request.headers.get(
-                    "X-Tenant-ID"
-                )
+                tenant_id = request.headers.get("X-Tenant-Id") or request.headers.get("X-Tenant-ID")
 
         key = key_fn(request)
         if self.scope_by_tenant and tenant_id:
@@ -103,7 +103,7 @@ class SimpleRateLimitMiddleware:
                 eff_limit = self.limit
 
         now = int(time.time())
-        count, store_limit, reset = self.store.incr(str(key), self.window)
+        count, _store_limit, reset = self.store.incr(str(key), self.window)
         limit = eff_limit
         remaining = max(0, limit - count)
 

svc_infra/api/fastapi/middleware/ratelimit_store.py

@@ -4,7 +4,8 @@ import logging
 import os
 import time
 import warnings
-from typing import Callable, Optional, Protocol, Tuple
+from collections.abc import Callable
+from typing import Protocol
 
 logger = logging.getLogger(__name__)
 
@@ -29,7 +30,7 @@ def _check_inmemory_production_warning(class_name: str) -> None:
 
 
 class RateLimitStore(Protocol):
-    def incr(self, key: str, window: int) -> Tuple[int, int, int]:
+    def incr(self, key: str, window: int) -> tuple[int, int, int]:
         """Increment and return (count, limit, resetEpoch).
 
         Implementations should manage per-window buckets. The 'limit' is stored configuration.
@@ -44,7 +45,7 @@ class InMemoryRateLimitStore:
         # Track per-key rolling windows: key -> (count, window_start_epoch)
         self._state: dict[str, tuple[int, float]] = {}
 
-    def incr(self, key: str, window: int) -> Tuple[int, int, int]:
+    def incr(self, key: str, window: int) -> tuple[int, int, int]:
         now = time.time()
         count, window_start = self._state.get(key, (0, now))
         # If outside the rolling window, reset
@@ -74,7 +75,7 @@ class RedisRateLimitStore:
         *,
         limit: int = 120,
         prefix: str = "ratelimit",
-        clock: Optional[Callable[[], float]] = None,
+        clock: Callable[[], float] | None = None,
     ):
         self.redis = redis_client
         self.limit = limit
@@ -87,16 +88,14 @@ class RedisRateLimitStore:
         redis_key = f"{self.prefix}:{key}:{win}"
         return redis_key, win, now
 
-    def incr(self, key: str, window: int) -> Tuple[int, int, int]:
+    def incr(self, key: str, window: int) -> tuple[int, int, int]:
         rkey, win, now = self._window_key(key, window)
         # Increment; if this is the first time we've seen this window key, set expiry to window end
         pipe = self.redis.pipeline()
         pipe.incr(rkey)
         pipe.ttl(rkey)
         count, ttl = pipe.execute()
-        if (
-            ttl == -1
-        ):  # key exists without expire or just created; set expire to end of window
+        if ttl == -1:  # key exists without expire or just created; set expire to end of window
             expire_sec = (win + window) - now
             if expire_sec <= 0:
                 expire_sec = window

svc_infra/api/fastapi/middleware/request_id.py

@@ -4,9 +4,7 @@ from uuid import uuid4
 from starlette.datastructures import Headers, MutableHeaders
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
-request_id_ctx: contextvars.ContextVar[str] = contextvars.ContextVar(
-    "request_id", default=""
-)
+request_id_ctx: contextvars.ContextVar[str] = contextvars.ContextVar("request_id", default="")
 
 
 class RequestIdMiddleware:

svc_infra/api/fastapi/middleware/timeout.py

@@ -37,6 +37,9 @@ class HandlerTimeoutMiddleware:
 
     Use skip_paths for endpoints that may run longer than the timeout
     (e.g., streaming responses, long-polling, file uploads).
+
+    Matching uses prefix matching: "/v1/chat" matches "/v1/chat", "/v1/chat/stream",
+    but not "/api/v1/chat" or "/v1/chatter".
     """
 
     def __init__(
@@ -58,8 +61,8 @@ class HandlerTimeoutMiddleware:
 
         path = scope.get("path", "")
 
-        # Skip specified paths (e.g., long-running endpoints)
-        if any(skip in path for skip in self.skip_paths):
+        # Skip specified paths using prefix matching (e.g., long-running endpoints)
+        if any(path.startswith(skip) for skip in self.skip_paths):
             await self.app(scope, receive, send)
             return
 
@@ -77,7 +80,7 @@ class HandlerTimeoutMiddleware:
                 self.app(scope, receive, send_wrapper),  # type: ignore[arg-type]  # ASGI send signature
                 timeout=self.timeout_seconds,
             )
-        except asyncio.TimeoutError:
+        except TimeoutError:
             # Only send 504 if response hasn't started yet
             if not response_started:
                 response = problem_response(
@@ -98,9 +101,7 @@ class BodyReadTimeoutMiddleware:
     def __init__(self, app: ASGIApp, timeout_seconds: int | None = None) -> None:
         self.app = app
         self.timeout_seconds = (
-            timeout_seconds
-            if timeout_seconds is not None
-            else REQUEST_BODY_TIMEOUT_SECONDS
+            timeout_seconds if timeout_seconds is not None else REQUEST_BODY_TIMEOUT_SECONDS
         )
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
@@ -116,9 +117,7 @@ class BodyReadTimeoutMiddleware:
 
         try:
             while True:
-                message = await asyncio.wait_for(
-                    receive(), timeout=self.timeout_seconds
-                )
+                message = await asyncio.wait_for(receive(), timeout=self.timeout_seconds)
 
                 mtype = message.get("type")
                 if mtype == "http.request":
@@ -136,7 +135,7 @@ class BodyReadTimeoutMiddleware:
                     # will see an empty body. No timeout response needed here.
                     break
                 # Ignore other message types and continue
-        except asyncio.TimeoutError:
+        except TimeoutError:
             # Timed out while waiting for the next body chunk → return 408
             request = Request(scope, receive=receive)
             trace_id = None