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

svc_infra/api/fastapi/openapi/mutators.py

@@ -367,6 +367,18 @@ def auth_mutator(include_api_key: bool):
 
     def _m(schema: dict) -> dict:
         schema = dict(schema)
+
+        # Detect if any operation already references APIKeyHeader
+        any_op_wants_api_key = False
+        for _, _, op in _iter_ops(schema):
+            for sec in op.get("security") or []:
+                if isinstance(sec, dict) and "APIKeyHeader" in sec:
+                    any_op_wants_api_key = True
+                    break
+            if any_op_wants_api_key:
+                break
+
+        # Add OAuth2 (always)
         comps = schema.setdefault("components", {}).setdefault("securitySchemes", {})
         comps.setdefault(
             "OAuth2PasswordBearer",
@@ -375,11 +387,21 @@ def auth_mutator(include_api_key: bool):
                 "flows": {"password": {"tokenUrl": auth_login_path, "scopes": {}}},
             },
         )
-        if include_api_key:
+
+        # Add API key scheme only if:
+        #  - include_api_key flag is True (from spec/root), OR
+        #  - at least one operation already references APIKeyHeader.
+        if include_api_key or any_op_wants_api_key:
             comps.setdefault(
-                "APIKeyHeader", {"type": "apiKey", "name": "X-API-Key", "in": "header"}
+                "APIKeyHeader",
+                {
+                    "type": "apiKey",
+                    "name": "X-API-Key",
+                    "in": "header",
+                },
             )
 
+        # Normalize operation security (drop only 'SessionCookie')
         drop = {"SessionCookie"}
         for _, _, op in _iter_ops(schema):
             op["security"] = _normalize_security_list(op.get("security"), drop)
@@ -689,57 +711,91 @@ def strip_ref_siblings_in_parameters_mutator():
 
 def dedupe_parameters_mutator():
     """
-    Deduplicate operation.parameters:
-      - Prefer $ref entries over inline params with the same name.
-      - Deduplicate repeated $ref entries (same target).
-      - Deduplicate repeated inline entries by (name, in).
+    Deduplicate operation.parameters by actual (name, in):
+      - Prefer **inline** params over $ref so per-op 'required: true' (e.g., Idempotency-Key) wins.
+      - Collapse duplicate $refs.
+      - If a $ref and an inline share the same (name, in), keep the inline and drop the $ref.
     """
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
+        comps = schema.get("components") or {}
+        comp_params = (comps.get("parameters") or {}).copy()
+
+        def _resolve_ref(ref: str) -> tuple[str, str] | None:
+            # '#/components/parameters/<Key>' -> ('Idempotency-Key','header'), etc.
+            try:
+                key = ref.rsplit("/", 1)[-1]
+                p = comp_params.get(key) or {}
+                name = p.get("name")
+                where = p.get("in")
+                if isinstance(name, str) and isinstance(where, str):
+                    return (name, where)
+            except Exception:
+                pass
+            return None
+
         for _, _, op in _iter_ops(schema):
             params = op.get("parameters")
             if not isinstance(params, list) or not params:
                 continue
 
-            # First, collect all $ref target names: "#/components/parameters/<NAME>"
-            ref_targets: list[str] = []
+            # First pass: collect inline params by (name, in)
+            inline_by_key: dict[tuple[str, str], dict] = {}
             for p in params:
-                if isinstance(p, dict) and "$ref" in p and isinstance(p["$ref"], str):
-                    ref_targets.append(p["$ref"].rsplit("/", 1)[-1])
-
-            seen_refs: set[str] = set()
-            seen_inline_keys: set[tuple[str, str]] = set()
+                if isinstance(p, dict) and "$ref" not in p:
+                    name = p.get("name")
+                    where = p.get("in")
+                    if isinstance(name, str) and isinstance(where, str):
+                        # Prefer the first inline; later duplicates ignored
+                        inline_by_key.setdefault((name, where), p)
+
+            seen_ref_targets: set[str] = set()
+            seen_keys: set[tuple[str, str]] = set()
             result: list[dict] = []
 
             for p in params:
                 if not isinstance(p, dict):
                     continue
 
-                # Handle $ref params
-                if "$ref" in p and isinstance(p["$ref"], str):
-                    ref_name = p["$ref"].rsplit("/", 1)[-1]
-                    if ref_name in seen_refs:
+                if "$ref" in p:
+                    ref = p.get("$ref")
+                    if not isinstance(ref, str):
                         continue
-                    seen_refs.add(ref_name)
-                    # ensure no siblings (if upstream didn't strip)
-                    if len(p) > 1:
-                        p = {"$ref": p["$ref"]}
-                    result.append(p)
+                    # de-dup exact same $ref
+                    if ref in seen_ref_targets:
+                        continue
+                    seen_ref_targets.add(ref)
+
+                    tup = _resolve_ref(ref)
+                    if tup is None:
+                        # keep unresolved ref (unlikely)
+                        result.append({"$ref": ref})
+                        continue
+
+                    # If an inline with same (name, in) exists, prefer inline, skip this $ref
+                    if tup in inline_by_key:
+                        continue
+
+                    # Else, keep this $ref if we didn't already keep a param for that key
+                    if tup in seen_keys:
+                        continue
+                    seen_keys.add(tup)
+                    # Ensure no siblings remain
+                    result.append({"$ref": ref})
                     continue
 
-                # Inline params: drop if a ref with the same name already exists
+                # inline param
                 name = p.get("name")
                 where = p.get("in")
-                if isinstance(name, str) and name in ref_targets:
-                    # There is a component param with the same name; prefer the $ref
+                if not (isinstance(name, str) and isinstance(where, str)):
+                    result.append(p)
                     continue
-
-                # Deduplicate inline params by (name, in)
-                key = (str(name), str(where))
-                if key in seen_inline_keys:
+                key = (name, where)
+                if key in seen_keys:
+                    # already kept an inline with same (name, in)
                     continue
-                seen_inline_keys.add(key)
+                seen_keys.add(key)
                 result.append(p)
 
             op["parameters"] = result
@@ -1046,6 +1102,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  # type: ignore
+    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)
@@ -1244,21 +1411,56 @@ def hardening_components_mutator():
 def attach_header_params_mutator():
     def m(schema: dict) -> dict:
         schema = dict(schema)
+        comps = schema.setdefault("components", {})
+        comp_params = comps.setdefault("parameters", {})
+
+        def _component_param_name(ref: str) -> tuple[str, str] | None:
+            try:
+                key = ref.rsplit("/", 1)[-1]
+                p = comp_params.get(key) or {}
+                name = p.get("name")
+                where = p.get("in")
+                if isinstance(name, str) and isinstance(where, str):
+                    return (name, where)
+            except Exception:
+                pass
+            return None
+
         for _, method, op in _iter_ops(schema):
             params = op.setdefault("parameters", [])
 
-            def add_ref(name):
-                params.append({"$ref": f"#/components/parameters/{name}"})
-
+            # What inline params (non-$ref) are already present?
+            inline_names = {
+                (p.get("name"), p.get("in"))
+                for p in params
+                if isinstance(p, dict) and "$ref" not in p and "name" in p and "in" in p
+            }
+
+            def add_ref_if_absent(name: str):
+                ref = {"$ref": f"#/components/parameters/{name}"}
+                tup = _component_param_name(ref["$ref"])
+                # If an inline with the same (name, in) exists (e.g., from a dependency),
+                # don't add the ref at all.
+                if tup and tup in inline_names:
+                    return
+                params.append(ref)
+
+            # ---- Write methods: Idempotency-Key fallback (optional via $ref) ----
+            # If the dependency added an inline required param, nothing to do;
+            # otherwise, add the optional component ref so callers can still send it.
             if method in ("post", "patch", "delete"):
-                add_ref("IdempotencyKey")
+                if ("Idempotency-Key", "header") not in inline_names:
+                    add_ref_if_absent("IdempotencyKey")
+                # Optional optimistic concurrency for updates
                 if method in ("patch", "put"):
-                    add_ref("IfMatch")
+                    add_ref_if_absent("IfMatch")
+
+            # ---- Conditional GET headers (optional via $ref) ----
             if method == "get":
-                add_ref("IfNoneMatch")
-                add_ref("IfModifiedSince")
+                add_ref_if_absent("IfNoneMatch")
+                add_ref_if_absent("IfModifiedSince")
 
-            # RESPONSE HEADERS — use *hyphenated* header names as keys
+            # ---- Standard success/429 headers (unchanged) ----
             resps = op.get("responses") or {}
             for code, resp in resps.items():
                 try:
@@ -1285,6 +1487,7 @@ def attach_header_params_mutator():
                         "schema": {"type": "integer"},
                         "description": "Seconds until next allowed request.",
                     }
+
         return schema
 
     return m
@@ -1337,6 +1540,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/ops/add.py

@@ -0,0 +1,73 @@
+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"]