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

svc_infra/api/fastapi/openapi/apply.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from fastapi import APIRouter
 
@@ -17,7 +18,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]
+    router.add_api_route = _wrapped_add_api_route  # type: ignore[method-assign]
 
 
 def apply_default_responses(router: APIRouter, defaults: dict[int, dict]) -> None:
@@ -38,4 +39,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]
+    router.add_api_route = _wrapped_add_api_route  # type: ignore[method-assign]

svc_infra/api/fastapi/openapi/conventions.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-from typing import Any, Dict
+from typing import Any
 
 from fastapi import FastAPI
 
 from .mutators import conventions_mutator
 from .pipeline import apply_mutators
 
-PROBLEM_SCHEMA: Dict[str, Any] = {
+PROBLEM_SCHEMA: dict[str, Any] = {
     "type": "object",
     "properties": {
         "type": {
@@ -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,13 +40,16 @@ 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"],
 }
 
 
-def _problem_example(**kw: Any) -> Dict[str, Any]:
+def _problem_example(**kw: Any) -> dict[str, Any]:
     base = {
         "type": "about:blank",
         "title": "Internal Server Error",
@@ -56,7 +63,7 @@ def _problem_example(**kw: Any) -> Dict[str, Any]:
     return base
 
 
-STANDARD_RESPONSES: Dict[str, Dict[str, Any]] = {
+STANDARD_RESPONSES: dict[str, dict[str, Any]] = {
     "BadRequest": {
         "description": "The request is malformed or missing required fields",
         "content": {

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 collections.abc import Callable, Iterable, Iterator
 
 from ..auth.security import auth_login_path
 from .models import APIVersionSpec, ServiceInfo, VersionInfo
@@ -9,7 +9,7 @@ from .models import APIVersionSpec, ServiceInfo, VersionInfo
 _HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
 
 
-def _iter_ops(schema: dict) -> Iterator[Tuple[str, str, dict]]:
+def _iter_ops(schema: dict) -> Iterator[tuple[str, str, dict]]:
     """Yield (path, method, op) for each operation object."""
     paths = schema.get("paths") or {}
     for path, methods in paths.items():
@@ -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.
 
@@ -479,7 +479,7 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
 
         # map existing tags by name and preserve their fields
         existing_list = schema.get("tags") or []
-        existing_map: Dict[str, dict] = {}
+        existing_map: dict[str, dict] = {}
         for item in existing_list:
             if isinstance(item, dict) and "name" in item:
                 existing_map[item["name"]] = dict(item)
@@ -487,7 +487,10 @@ 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)
@@ -501,8 +504,8 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
 
 
 def attach_standard_responses_mutator(
-    codes: Dict[int, str] | None = None,
-    per_method: Dict[str, Iterable[int]] | None = None,
+    codes: dict[int, str] | None = None,
+    per_method: dict[str, Iterable[int]] | None = None,
     exclude_tags: set[str] | None = None,
     op_flag_disable: str = "x_disable_standard_responses",
 ):
@@ -541,7 +544,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 +643,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):
@@ -1102,6 +1107,117 @@ 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 +1256,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 +1385,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 +1409,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
 
@@ -1362,14 +1484,16 @@ def attach_header_params_mutator():
                     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"}
+                        "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 +1553,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

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
@@ -23,4 +23,4 @@ def apply_mutators(app: FastAPI, *mutators):
         app.openapi_schema = schema
         return schema
 
-    app.openapi = patched
+    app.openapi = patched  # type: ignore[method-assign]

svc_infra/api/fastapi/openapi/responses.py

@@ -1,32 +1,30 @@
 from __future__ import annotations
 
-from typing import Dict
-
 
 def ref(name: str) -> dict:
     return {"$ref": f"#/components/responses/{name}"}
 
 
-DEFAULT_PUBLIC: Dict[int, dict] = {
+DEFAULT_PUBLIC: dict[int, dict] = {
     400: ref("BadRequest"),
     422: ref("ValidationError"),
     500: ref("ServerError"),
 }
-DEFAULT_USER: Dict[int, dict] = {
+DEFAULT_USER: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),
     422: ref("ValidationError"),
     500: ref("ServerError"),
 }
-DEFAULT_SERVICE: Dict[int, dict] = {
+DEFAULT_SERVICE: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),
     429: ref("TooManyRequests"),
     500: ref("ServerError"),
 }
-DEFAULT_PROTECTED: Dict[int, dict] = {
+DEFAULT_PROTECTED: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),

svc_infra/api/fastapi/openapi/security.py

@@ -6,7 +6,7 @@ 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,73 @@
+from __future__ import annotations
+
+import os
+from collections.abc 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:
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/ready")
+    async def ready() -> JSONResponse:
+        # In the future, add checks (DB ping, cache ping) via DI hooks.
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/startup")
+    async def startup_probe() -> JSONResponse:
+        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):
+        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:
+        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"]