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

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"]

svc_infra/api/fastapi/pagination.py

@@ -3,11 +3,24 @@ from __future__ import annotations
 import base64
 import contextvars
 import json
-from typing import Any, Callable, Generic, Iterable, List, Optional, Sequence, TypeVar
+import logging
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+    cast,
+)
 
 from fastapi import Query, Request
 from pydantic import BaseModel, Field
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 
@@ -44,13 +57,13 @@ def _encode_cursor(payload: dict) -> str:
     return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
 
 
-def decode_cursor(token: Optional[str]) -> dict:
+def decode_cursor(token: Optional[str]) -> dict[Any, Any]:
     """Public: decode an incoming cursor token for debugging/ops."""
     if not token:
         return {}
     s = token + "=" * (-len(token) % 4)
     raw = base64.urlsafe_b64decode(s.encode("ascii")).decode("utf-8")
-    return json.loads(raw)
+    return cast(dict[Any, Any], json.loads(raw))
 
 
 # ---------- Context ----------
@@ -85,11 +98,15 @@ class PaginationContext(Generic[T]):
 
     @property
     def cursor(self) -> Optional[str]:
-        return (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
+        return (
+            (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
+        )
 
     @property
     def limit(self) -> int:
-        if self.allow_cursor and self.cursor_params and self.cursor_params.cursor is not None:
+        # For cursor-based pagination, always honor the requested limit, even on the first page
+        # (cursor may be None for the first page).
+        if self.allow_cursor and self.cursor_params:
             return self.cursor_params.limit
         if self.allow_page and self.page_params:
             return self.limit_override or self.page_params.page_size
@@ -101,7 +118,11 @@ class PaginationContext(Generic[T]):
 
     @property
     def page_size(self) -> Optional[int]:
-        return self.page_params.page_size if (self.allow_page and self.page_params) else None
+        return (
+            self.page_params.page_size
+            if (self.allow_page and self.page_params)
+            else None
+        )
 
     @property
     def offset(self) -> int:
@@ -110,7 +131,11 @@ class PaginationContext(Generic[T]):
         return 0
 
     def wrap(
-        self, items: list[T], *, next_cursor: Optional[str] = None, total: Optional[int] = None
+        self,
+        items: list[T],
+        *,
+        next_cursor: Optional[str] = None,
+        total: Optional[int] = None,
     ):
         if self.envelope:
             return Paginated[T](items=items, next_cursor=next_cursor, total=total)
@@ -125,8 +150,8 @@ class PaginationContext(Generic[T]):
         return _encode_cursor({"after": last_key})
 
 
-_pagination_ctx: contextvars.ContextVar[PaginationContext] = contextvars.ContextVar(
-    "pagination_ctx", default=None
+_pagination_ctx: contextvars.ContextVar[PaginationContext | None] = (
+    contextvars.ContextVar("pagination_ctx", default=None)
 )
 
 
@@ -146,7 +171,9 @@ def use_pagination() -> PaginationContext:
 
 
 # ---------- Utilities ----------
-def text_filter(items: Iterable[T], q: Optional[str], *getters: Callable[[T], str]) -> list[T]:
+def text_filter(
+    items: Iterable[T], q: Optional[str], *getters: Callable[[T], str]
+) -> list[T]:
     if not q:
         return list(items)
     ql = q.lower()
@@ -157,8 +184,8 @@ def text_filter(items: Iterable[T], q: Optional[str], *getters: Callable[[T], st
                 if ql in (g(it) or "").lower():
                     out.append(it)
                     break
-            except Exception:
-                pass
+            except Exception as e:
+                logger.debug("text_filter getter failed for item: %s", e)
     return out
 
 
@@ -215,7 +242,7 @@ def make_pagination_injector(
     # Cursor-only (common case)
     if allow_cursor and not allow_page and not include_filters:
 
-        async def _inject(
+        async def _inject_cursor(
             request: Request,
             cursor: str | None = Query(None),
             limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -233,12 +260,12 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_cursor
 
     # Cursor + filters
     if allow_cursor and not allow_page and include_filters:
 
-        async def _inject(
+        async def _inject_cursor_with_filters(
             request: Request,
             cursor: str | None = Query(None),
             limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -270,12 +297,12 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_cursor_with_filters
 
     # Page-only
     if not allow_cursor and allow_page:
 
-        async def _inject(
+        async def _inject_page(
             request: Request,
             page: int = Query(1, ge=1),
             page_size: int = Query(default_limit, ge=1, le=max_limit),
@@ -293,10 +320,10 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_page
 
     # Both cursor + page (rare; exposes all)
-    async def _inject(
+    async def _inject_all(
         request: Request,
         cursor: str | None = Query(None),
         limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -336,7 +363,7 @@ def make_pagination_injector(
         )
         return None
 
-    return _inject
+    return _inject_all
 
 
 # ----- Convenience helpers for routers -----