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

svc_infra/api/fastapi/middleware/timeout.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from fastapi import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from svc_infra.api.fastapi.middleware.errors.handlers import problem_response
+from svc_infra.app.env import pick
+
+
+def _env_int(name: str, default: int) -> int:
+    v = os.getenv(name)
+    if v is None:
+        return default
+    try:
+        return int(v)
+    except Exception:
+        return default
+
+
+REQUEST_BODY_TIMEOUT_SECONDS: int = pick(
+    prod=_env_int("REQUEST_BODY_TIMEOUT_SECONDS", 15),
+    nonprod=_env_int("REQUEST_BODY_TIMEOUT_SECONDS", 30),
+)
+REQUEST_TIMEOUT_SECONDS: int = pick(
+    prod=_env_int("REQUEST_TIMEOUT_SECONDS", 30),
+    nonprod=_env_int("REQUEST_TIMEOUT_SECONDS", 15),
+)
+
+
+class HandlerTimeoutMiddleware:
+    """
+    Caps total handler execution time. If exceeded, returns 504 Problem+JSON.
+
+    Use skip_paths for endpoints that may run longer than the timeout
+    (e.g., streaming responses, long-polling, file uploads).
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        timeout_seconds: int | None = None,
+        skip_paths: list[str] | None = None,
+    ) -> None:
+        self.app = app
+        self.timeout_seconds = (
+            timeout_seconds if timeout_seconds is not None else REQUEST_TIMEOUT_SECONDS
+        )
+        self.skip_paths = skip_paths or []
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+
+        # Skip specified paths (e.g., long-running endpoints)
+        if any(skip in path for skip in self.skip_paths):
+            await self.app(scope, receive, send)
+            return
+
+        # Track if response has started (headers sent)
+        response_started = False
+
+        async def send_wrapper(message: dict) -> None:
+            nonlocal response_started
+            if message.get("type") == "http.response.start":
+                response_started = True
+            await send(message)
+
+        try:
+            await asyncio.wait_for(
+                self.app(scope, receive, send_wrapper),  # type: ignore[arg-type]  # ASGI send signature
+                timeout=self.timeout_seconds,
+            )
+        except asyncio.TimeoutError:
+            # Only send 504 if response hasn't started yet
+            if not response_started:
+                response = problem_response(
+                    status=504,
+                    title="Gateway Timeout",
+                    detail=f"Handler did not complete within {self.timeout_seconds}s",
+                )
+                await response(scope, receive, send)
+            # If response already started, we can't change it - just let it fail
+
+
+class BodyReadTimeoutMiddleware:
+    """
+    Enforces a timeout while reading the request body to mitigate slowloris.
+    If body read does not make progress within the timeout, returns 408 Problem+JSON.
+    """
+
+    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
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Strategy: greedily drain the incoming request body here while enforcing
+        # per-receive timeout, then replay it to the downstream app from a buffer.
+        # This ensures we can detect slowloris-style uploads even if the app only
+        # reads the body later (after the server has finished buffering).
+        buffered = bytearray()
+
+        try:
+            while True:
+                message = await asyncio.wait_for(
+                    receive(), timeout=self.timeout_seconds
+                )
+
+                mtype = message.get("type")
+                if mtype == "http.request":
+                    chunk = message.get("body", b"") or b""
+                    if chunk:
+                        buffered.extend(chunk)
+                    # Stop when server indicates no more body
+                    if not message.get("more_body", False):
+                        break
+                    # else: continue reading remaining chunks with timeout
+                    continue
+
+                if mtype == "http.disconnect":  # client disconnected mid-upload
+                    # Treat as end of body for the purposes of replay; downstream
+                    # will see an empty body. No timeout response needed here.
+                    break
+                # Ignore other message types and continue
+        except asyncio.TimeoutError:
+            # Timed out while waiting for the next body chunk → return 408
+            request = Request(scope, receive=receive)
+            trace_id = None
+            for h in ("x-request-id", "x-correlation-id", "x-trace-id"):
+                v = request.headers.get(h)
+                if v:
+                    trace_id = v
+                    break
+            resp = problem_response(
+                status=408,
+                title="Request Timeout",
+                detail="Timed out while reading request body.",
+                code="REQUEST_TIMEOUT",
+                instance=str(request.url),
+                trace_id=trace_id,
+            )
+            await resp(scope, receive, send)
+            return
+
+        # Replay the drained body to the app as a single http.request message.
+        # IMPORTANT: After replaying the body, we must forward the original receive()
+        # so that Starlette's listen_for_disconnect can properly detect client disconnects.
+        # This is required for streaming responses on ASGI spec < 2.4.
+        body_sent = False
+
+        async def _replay_receive() -> dict[str, Any]:
+            nonlocal body_sent
+            if not body_sent:
+                body_sent = True
+                return {
+                    "type": "http.request",
+                    "body": bytes(buffered),
+                    "more_body": False,
+                }
+            # After body is sent, forward to original receive for disconnect detection
+            return dict(await receive())
+
+        await self.app(scope, _replay_receive, send)

svc_infra/api/fastapi/openapi/apply.py

@@ -5,7 +5,9 @@ from typing import Any, Callable
 from fastapi import APIRouter
 
 
-def apply_default_security(router: APIRouter, *, default_security: list[dict] | None) -> None:
+def apply_default_security(
+    router: APIRouter, *, default_security: list[dict] | None
+) -> None:
     if default_security is None:
         return
     original_add = router.add_api_route
@@ -17,7 +19,7 @@ def apply_default_security(router: APIRouter, *, default_security: list[dict] |
             kwargs["openapi_extra"] = ox
         return original_add(path, endpoint, **kwargs)
 
-    router.add_api_route = _wrapped_add_api_route  # type: ignore[attr-defined]
+    setattr(router, "add_api_route", _wrapped_add_api_route)
 
 
 def apply_default_responses(router: APIRouter, defaults: dict[int, dict]) -> None:
@@ -38,4 +40,4 @@ def apply_default_responses(router: APIRouter, defaults: dict[int, dict]) -> Non
         kwargs["responses"] = responses
         return original_add(path, endpoint, **kwargs)
 
-    router.add_api_route = _wrapped_add_api_route  # type: ignore[attr-defined]
+    setattr(router, "add_api_route", _wrapped_add_api_route)

svc_infra/api/fastapi/openapi/conventions.py

@@ -16,7 +16,11 @@ PROBLEM_SCHEMA: Dict[str, Any] = {
             "description": "URI identifying the error type",
         },
         "title": {"type": "string", "description": "Short, human-readable summary"},
-        "status": {"type": "integer", "format": "int32", "description": "HTTP status code"},
+        "status": {
+            "type": "integer",
+            "format": "int32",
+            "description": "HTTP status code",
+        },
         "detail": {"type": "string", "description": "Human-readable explanation"},
         "instance": {
             "type": "string",
@@ -36,7 +40,10 @@ PROBLEM_SCHEMA: Dict[str, Any] = {
                 },
             },
         },
-        "trace_id": {"type": "string", "description": "Correlation/trace id (if available)"},
+        "trace_id": {
+            "type": "string",
+            "description": "Correlation/trace id (if available)",
+        },
     },
     "required": ["title", "status"],
 }

svc_infra/api/fastapi/openapi/mutators.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import Dict, Iterable, Iterator, Tuple
+from typing import Callable, Dict, Iterable, Iterator, Tuple
 
 from ..auth.security import auth_login_path
 from .models import APIVersionSpec, ServiceInfo, VersionInfo
@@ -51,7 +51,7 @@ def pagination_components_mutator(
     *,
     default_limit: int = 50,
     max_limit: int = 200,
-) -> callable:
+) -> Callable[[dict], dict]:
     """
     Adds reusable pagination/filtering parameters & paginated envelope schemas.
     - Cursor: cursor/limit
@@ -196,7 +196,7 @@ def auto_attach_pagination_params_mutator(
     attach_filters: bool = True,
     apply_when: str = "array_200",
     flag_disable: str = "x_no_auto_pagination",
-) -> callable:
+) -> Callable[[dict], dict]:
     """
     Attaches reusable pagination/filter parameters to GET "listy" operations.
 
@@ -273,7 +273,9 @@ def normalize_problem_and_examples_mutator():
         if not isinstance(val, dict):
             return
         inst = val.get("instance")
-        if isinstance(inst, str) and (inst.startswith("/") or inst.startswith("about:")):
+        if isinstance(inst, str) and (
+            inst.startswith("/") or inst.startswith("about:")
+        ):
             # make absolute to satisfy format: uri
             val["instance"] = ABSOLUTE_INSTANCE
 
@@ -487,13 +489,18 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
         # add missing tags; do NOT override existing descriptions
         for name in sorted(used):
             if name not in existing_map:
-                existing_map[name] = {"name": name, "description": default_desc.format(tag=name)}
+                existing_map[name] = {
+                    "name": name,
+                    "description": default_desc.format(tag=name),
+                }
             else:
                 if not existing_map[name].get("description"):
                     existing_map[name]["description"] = default_desc.format(tag=name)
 
         if existing_map:
-            schema["tags"] = sorted(existing_map.values(), key=lambda x: x.get("name", ""))
+            schema["tags"] = sorted(
+                existing_map.values(), key=lambda x: x.get("name", "")
+            )
 
         return schema
 
@@ -541,7 +548,7 @@ def attach_standard_responses_mutator(
 
 
 def drop_unused_components_mutator(
-    drop_responses: list[str] = None, drop_schemas: list[str] = None
+    drop_responses: list[str] | None = None, drop_schemas: list[str] | None = None
 ):
     drop_responses = drop_responses or []
     drop_schemas = drop_schemas or []
@@ -640,7 +647,9 @@ def ensure_media_type_schemas_mutator():
 
 
 # ---------- 3) Request body descriptions ----------
-def ensure_request_body_descriptions_mutator(default_template="Request body for {method} {path}."):
+def ensure_request_body_descriptions_mutator(
+    default_template="Request body for {method} {path}.",
+):
     def m(schema: dict) -> dict:
         schema = dict(schema)
         for path, method, op in _iter_ops(schema):
@@ -648,7 +657,9 @@ def ensure_request_body_descriptions_mutator(default_template="Request body for
             if isinstance(rb, dict):
                 desc = rb.get("description")
                 if not isinstance(desc, str) or not desc.strip():
-                    rb["description"] = default_template.format(method=method.upper(), path=path)
+                    rb["description"] = default_template.format(
+                        method=method.upper(), path=path
+                    )
         return schema
 
     return m
@@ -836,7 +847,9 @@ def inject_safe_examples_mutator():
     """
 
     def _has_examples(mt_obj: dict) -> bool:
-        return isinstance(mt_obj, dict) and ("example" in mt_obj or "examples" in mt_obj)
+        return isinstance(mt_obj, dict) and (
+            "example" in mt_obj or "examples" in mt_obj
+        )
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -1082,7 +1095,11 @@ def ensure_success_examples_mutator():
                 if not (200 <= ic < 300) or ic == 204:
                     continue
                 mt_obj = (resp.get("content") or {}).get("application/json")
-                if not isinstance(mt_obj, dict) or "example" in mt_obj or "examples" in mt_obj:
+                if (
+                    not isinstance(mt_obj, dict)
+                    or "example" in mt_obj
+                    or "examples" in mt_obj
+                ):
                     continue
                 sch = mt_obj.get("schema") or {}
 
@@ -1102,6 +1119,119 @@ def ensure_success_examples_mutator():
     return m
 
 
+# --- NEW: attach minimal x-codeSamples for common operations ---
+def attach_code_samples_mutator():
+    """Attach minimal curl/httpie x-codeSamples for each operation if missing.
+
+    We avoid templating parameters; samples illustrate method and path only.
+    """
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        servers = schema.get("servers") or [{"url": ""}]
+        base = servers[0].get("url") or ""
+
+        for path, method, op in _iter_ops(schema):
+            # Don't override existing samples
+            if isinstance(op.get("x-codeSamples"), list) and op["x-codeSamples"]:
+                continue
+            url = f"{base}{path}"
+            method_up = method.upper()
+            samples = [
+                {
+                    "lang": "bash",
+                    "label": "curl",
+                    "source": f"curl -X {method_up} '{url}'",
+                },
+                {
+                    "lang": "bash",
+                    "label": "httpie",
+                    "source": f"http {method_up} '{url}'",
+                },
+            ]
+            op["x-codeSamples"] = samples
+        return schema
+
+    return m
+
+
+# --- NEW: ensure Problem+JSON examples exist for standard error responses ---
+def ensure_problem_examples_mutator():
+    """Add example objects for 4xx/5xx responses using Problem schema if absent."""
+
+    try:
+        # Internal helper with sensible defaults
+        from .conventions import _problem_example
+    except Exception:  # pragma: no cover - fallback
+
+        def _problem_example(**kw):  # type: ignore
+            base = {
+                "type": "about:blank",
+                "title": "Error",
+                "status": 500,
+                "detail": "An error occurred.",
+                "instance": "/request/trace",
+                "code": "INTERNAL_ERROR",
+            }
+            base.update(kw)
+            return base
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, _, op in _iter_ops(schema):
+            resps = op.get("responses") or {}
+            for code, resp in resps.items():
+                if not isinstance(resp, dict):
+                    continue
+                try:
+                    ic = int(code)
+                except Exception:
+                    continue
+                if ic < 400:
+                    continue
+                # Do not add content if response is a $ref; avoid creating siblings
+                if "$ref" in resp:
+                    continue
+                content = resp.setdefault("content", {})
+                # prefer problem+json but also set application/json if present
+                for mt in ("application/problem+json", "application/json"):
+                    mt_obj = content.get(mt)
+                    if mt_obj is None:
+                        # Create a basic media type referencing Problem schema when appropriate
+                        if mt == "application/problem+json":
+                            mt_obj = {
+                                "schema": {"$ref": "#/components/schemas/Problem"}
+                            }
+                            content[mt] = mt_obj
+                        else:
+                            continue
+                    if not isinstance(mt_obj, dict):
+                        continue
+                    if "example" in mt_obj or "examples" in mt_obj:
+                        continue
+                    mt_obj["example"] = _problem_example(status=ic)
+        return schema
+
+    return m
+
+
+# --- NEW: attach default tags from first path segment when missing ---
+def attach_default_tags_mutator():
+    """If an operation has no tags, tag it by its first path segment."""
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for path, _method, op in _iter_ops(schema):
+            tags = op.get("tags")
+            if tags:
+                continue
+            seg = path.strip("/").split("/", 1)[0] or "root"
+            op["tags"] = [seg]
+        return schema
+
+    return m
+
+
 def dedupe_tags_mutator():
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -1140,7 +1270,7 @@ def scrub_invalid_object_examples_mutator():
             sch = mt_obj.get("schema")
             ex = mt_obj.get("example")
             if "example" in mt_obj and _invalid_object_example(
-                sch if isinstance(sch, dict) else {}, ex
+                sch if isinstance(sch, dict) else {}, ex if isinstance(ex, dict) else {}
             ):
                 mt_obj.pop("example", None)
 
@@ -1269,17 +1399,20 @@ def hardening_components_mutator():
             },
         )
         headers.setdefault(
-            "XRateLimitLimit", {"schema": {"type": "integer"}, "description": "Tokens in window."}
+            "XRateLimitLimit",
+            {"schema": {"type": "integer"}, "description": "Tokens in window."},
         )
         headers.setdefault(
             "XRateLimitRemaining",
             {"schema": {"type": "integer"}, "description": "Remaining tokens."},
         )
         headers.setdefault(
-            "XRateLimitReset", {"schema": {"type": "integer"}, "description": "Unix reset time."}
+            "XRateLimitReset",
+            {"schema": {"type": "integer"}, "description": "Unix reset time."},
         )
         headers.setdefault(
-            "XRequestId", {"schema": {"type": "string"}, "description": "Correlation id."}
+            "XRequestId",
+            {"schema": {"type": "string"}, "description": "Correlation id."},
         )
         headers.setdefault(
             "Deprecation",
@@ -1290,7 +1423,10 @@ def hardening_components_mutator():
         )
         headers.setdefault(
             "Sunset",
-            {"schema": {"type": "string"}, "description": "HTTP-date for deprecation sunset."},
+            {
+                "schema": {"type": "string"},
+                "description": "HTTP-date for deprecation sunset.",
+            },
         )
         return schema
 
@@ -1359,17 +1495,23 @@ def attach_header_params_mutator():
                 if 200 <= ic < 300:
                     hdrs = resp.setdefault("headers", {})
                     hdrs.setdefault("ETag", {"$ref": "#/components/headers/ETag"})
-                    hdrs.setdefault("Last-Modified", {"$ref": "#/components/headers/LastModified"})
-                    hdrs.setdefault("X-Request-Id", {"$ref": "#/components/headers/XRequestId"})
                     hdrs.setdefault(
-                        "X-RateLimit-Limit", {"$ref": "#/components/headers/XRateLimitLimit"}
+                        "Last-Modified", {"$ref": "#/components/headers/LastModified"}
+                    )
+                    hdrs.setdefault(
+                        "X-Request-Id", {"$ref": "#/components/headers/XRequestId"}
+                    )
+                    hdrs.setdefault(
+                        "X-RateLimit-Limit",
+                        {"$ref": "#/components/headers/XRateLimitLimit"},
                     )
                     hdrs.setdefault(
                         "X-RateLimit-Remaining",
                         {"$ref": "#/components/headers/XRateLimitRemaining"},
                     )
                     hdrs.setdefault(
-                        "X-RateLimit-Reset", {"$ref": "#/components/headers/XRateLimitReset"}
+                        "X-RateLimit-Reset",
+                        {"$ref": "#/components/headers/XRateLimitReset"},
                     )
                 if code == "429":
                     resp.setdefault("headers", {})["Retry-After"] = {
@@ -1429,6 +1571,9 @@ def setup_mutators(
         ensure_media_type_schemas_mutator(),
         ensure_examples_for_json_mutator(),
         ensure_success_examples_mutator(),
+        attach_default_tags_mutator(),
+        attach_code_samples_mutator(),
+        ensure_problem_examples_mutator(),
         ensure_media_examples_mutator(),
         scrub_invalid_object_examples_mutator(),
         normalize_no_content_204_mutator(),

svc_infra/api/fastapi/openapi/pipeline.py

@@ -23,4 +23,4 @@ def apply_mutators(app: FastAPI, *mutators):
         app.openapi_schema = schema
         return schema
 
-    app.openapi = patched
+    setattr(app, "openapi", patched)

svc_infra/api/fastapi/openapi/security.py

@@ -6,7 +6,9 @@ from .mutators import auth_mutator
 from .pipeline import apply_mutators
 
 
-def _normalize_security_list(sec: list | None, *, drop_schemes: set[str] = None) -> list:
+def _normalize_security_list(
+    sec: list | None, *, drop_schemes: set[str] | None = None
+) -> list:
     if not sec:
         return []
     drop_schemes = drop_schemes or set()

svc_infra/api/fastapi/ops/add.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+from typing import Callable
+
+from fastapi import FastAPI, HTTPException, Request
+from starlette.responses import JSONResponse
+
+
+def add_probes(
+    app: FastAPI,
+    *,
+    prefix: str = "/_ops",
+    include_in_schema: bool = False,
+) -> None:
+    """Mount basic liveness/readiness/startup probes under prefix."""
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    router = public_router(
+        prefix=prefix, tags=["ops"], include_in_schema=include_in_schema
+    )
+
+    @router.get("/live")
+    async def live() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/ready")
+    async def ready() -> JSONResponse:  # noqa: D401, ANN201
+        # In the future, add checks (DB ping, cache ping) via DI hooks.
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/startup")
+    async def startup_probe() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    app.include_router(router)
+
+
+def add_maintenance_mode(
+    app: FastAPI,
+    *,
+    env_var: str = "MAINTENANCE_MODE",
+    exempt_prefixes: tuple[str, ...] | None = None,
+) -> None:
+    """Enable a simple maintenance gate controlled by an env var.
+
+    When MAINTENANCE_MODE is truthy, all non-GET requests return 503.
+    """
+
+    @app.middleware("http")
+    async def _maintenance_gate(request: Request, call_next):  # noqa: ANN001, ANN202
+        flag = str(os.getenv(env_var, "")).lower() in {"1", "true", "yes", "on"}
+        if flag and request.method not in {"GET", "HEAD", "OPTIONS"}:
+            path = request.scope.get("path", "")
+            if exempt_prefixes and any(path.startswith(p) for p in exempt_prefixes):
+                return await call_next(request)
+            return JSONResponse({"detail": "maintenance"}, status_code=503)
+        return await call_next(request)
+
+
+def circuit_breaker_dependency(limit: int = 100, window_seconds: int = 60) -> Callable:
+    """Return a dependency that can trip rejective errors based on external metrics.
+
+    This is a placeholder; callers can swap with a provider that tracks failures and opens the
+    breaker. Here, we read an env var to simulate an open breaker.
+    """
+
+    async def _dep(_: Request) -> None:  # noqa: D401, ANN202
+        if str(os.getenv("CIRCUIT_OPEN", "")).lower() in {"1", "true", "yes", "on"}:
+            raise HTTPException(status_code=503, detail="circuit open")
+
+    return _dep
+
+
+__all__ = ["add_probes", "add_maintenance_mode", "circuit_breaker_dependency"]