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

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

svc_infra/api/fastapi/pagination.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+import base64
+import contextvars
+import json
+from typing import Any, Callable, Generic, Iterable, List, Optional, Sequence, TypeVar
+
+from fastapi import Query, Request
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+# ---------- Core query models ----------
+class CursorParams(BaseModel):
+    cursor: Optional[str] = None
+    limit: int = 50
+
+
+class PageParams(BaseModel):
+    page: int = 1
+    page_size: int = 50
+
+
+class FilterParams(BaseModel):
+    q: Optional[str] = None
+    sort: Optional[str] = None
+    created_after: Optional[str] = None
+    created_before: Optional[str] = None
+    updated_after: Optional[str] = None
+    updated_before: Optional[str] = None
+
+
+# ---------- Envelope model ----------
+class Paginated(BaseModel, Generic[T]):
+    items: List[T]
+    next_cursor: Optional[str] = Field(None, description="Opaque cursor for next page")
+    total: Optional[int] = Field(None, description="Total items (optional)")
+
+
+# ---------- Cursor helpers ----------
+def _encode_cursor(payload: dict) -> str:
+    raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def decode_cursor(token: Optional[str]) -> dict:
+    """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)
+
+
+# ---------- Context ----------
+class PaginationContext(Generic[T]):
+    envelope: bool
+    allow_cursor: bool
+    allow_page: bool
+
+    cursor_params: CursorParams | None
+    page_params: PageParams | None
+    filters: FilterParams | None
+    limit_override: int | None
+
+    def __init__(
+        self,
+        *,
+        envelope: bool,
+        allow_cursor: bool,
+        allow_page: bool,
+        cursor_params: CursorParams | None,
+        page_params: PageParams | None,
+        filters: FilterParams | None,
+        limit_override: int | None = None,
+    ):
+        self.envelope = envelope
+        self.allow_cursor = allow_cursor
+        self.allow_page = allow_page
+        self.cursor_params = cursor_params
+        self.page_params = page_params
+        self.filters = filters
+        self.limit_override = limit_override
+
+    @property
+    def cursor(self) -> Optional[str]:
+        return (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
+
+    @property
+    def limit(self) -> int:
+        # 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
+        return 50
+
+    @property
+    def page(self) -> Optional[int]:
+        return self.page_params.page if (self.allow_page and self.page_params) else None
+
+    @property
+    def page_size(self) -> Optional[int]:
+        return self.page_params.page_size if (self.allow_page and self.page_params) else None
+
+    @property
+    def offset(self) -> int:
+        if self.cursor is None and self.allow_page and self.page and self.page_size:
+            return (self.page - 1) * self.page_size
+        return 0
+
+    def wrap(
+        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)
+        return items
+
+    def next_cursor_from_last(
+        self, items: Sequence[T], *, key: Callable[[T], str | int]
+    ) -> Optional[str]:
+        if not items:
+            return None
+        last_key = key(items[-1])
+        return _encode_cursor({"after": last_key})
+
+
+_pagination_ctx: contextvars.ContextVar[PaginationContext] = contextvars.ContextVar(
+    "pagination_ctx", default=None
+)
+
+
+def use_pagination() -> PaginationContext:
+    ctx = _pagination_ctx.get()
+    if ctx is None:
+        # Safe defaults; if a route forgot to install the injector
+        ctx = PaginationContext(
+            envelope=False,
+            allow_cursor=True,
+            allow_page=False,
+            cursor_params=CursorParams(),
+            page_params=None,
+            filters=None,
+        )
+    return ctx
+
+
+# ---------- Utilities ----------
+def text_filter(items: Iterable[T], q: Optional[str], *getters: Callable[[T], str]) -> list[T]:
+    if not q:
+        return list(items)
+    ql = q.lower()
+    out: list[T] = []
+    for it in items:
+        for g in getters:
+            try:
+                if ql in (g(it) or "").lower():
+                    out.append(it)
+                    break
+            except Exception:
+                pass
+    return out
+
+
+def sort_by(
+    items: Iterable[T],
+    *,
+    key: Callable[[T], Any],
+    desc: bool = False,
+) -> list[T]:
+    return sorted(list(items), key=key, reverse=desc)
+
+
+def cursor_window(items, *, cursor, limit, key, descending: bool, offset: int = 0):
+    # compute start_index
+    if cursor:
+        payload = decode_cursor(cursor)
+        after = payload.get("after")
+        ids = [key(x) for x in items]
+        if descending:
+            start_index = next((i for i, v in enumerate(ids) if v < after), len(items))
+        else:
+            start_index = next((i for i, v in enumerate(ids) if v > after), len(items))
+    else:
+        start_index = offset
+
+    # take limit+1 to see if there’s another page
+    slice_ = items[start_index : start_index + limit + 1]
+    has_more = len(slice_) > limit
+    window = slice_[:limit]
+
+    next_cur = None
+    if has_more and window:
+        last_key = key(window[-1])
+        next_cur = _encode_cursor({"after": last_key})
+
+    return window, next_cur
+
+
+# ---------- Dependency factories ----------
+def make_pagination_injector(
+    *,
+    envelope: bool,
+    allow_cursor: bool,
+    allow_page: bool,
+    default_limit: int = 50,
+    max_limit: int = 200,
+    include_filters: bool = False,
+):
+    """
+    Returns a dependency with a signature that only includes the relevant query params.
+    This keeps the generated OpenAPI in sync with actual behavior.
+    """
+
+    # Cursor-only (common case)
+    if allow_cursor and not allow_page and not include_filters:
+
+        async def _inject(
+            request: Request,
+            cursor: str | None = Query(None),
+            limit: int = Query(default_limit, ge=1, le=max_limit),
+        ):
+            cur = CursorParams(cursor=cursor, limit=limit)
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=True,
+                    allow_page=False,
+                    cursor_params=cur,
+                    page_params=None,
+                    filters=None,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Cursor + filters
+    if allow_cursor and not allow_page and include_filters:
+
+        async def _inject(
+            request: Request,
+            cursor: str | None = Query(None),
+            limit: int = Query(default_limit, ge=1, le=max_limit),
+            q: str | None = Query(None),
+            sort: str | None = Query(None),
+            created_after: str | None = Query(None),
+            created_before: str | None = Query(None),
+            updated_after: str | None = Query(None),
+            updated_before: str | None = Query(None),
+        ):
+            cur = CursorParams(cursor=cursor, limit=limit)
+            flt = FilterParams(
+                q=q,
+                sort=sort,
+                created_after=created_after,
+                created_before=created_before,
+                updated_after=updated_after,
+                updated_before=updated_before,
+            )
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=True,
+                    allow_page=False,
+                    cursor_params=cur,
+                    page_params=None,
+                    filters=flt,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Page-only
+    if not allow_cursor and allow_page:
+
+        async def _inject(
+            request: Request,
+            page: int = Query(1, ge=1),
+            page_size: int = Query(default_limit, ge=1, le=max_limit),
+        ):
+            pag = PageParams(page=page, page_size=page_size)
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=False,
+                    allow_page=True,
+                    cursor_params=None,
+                    page_params=pag,
+                    filters=None,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Both cursor + page (rare; exposes all)
+    async def _inject(
+        request: Request,
+        cursor: str | None = Query(None),
+        limit: int = Query(default_limit, ge=1, le=max_limit),
+        page: int = Query(1, ge=1),
+        page_size: int = Query(default_limit, ge=1, le=max_limit),
+        q: str | None = Query(None),
+        sort: str | None = Query(None),
+        created_after: str | None = Query(None),
+        created_before: str | None = Query(None),
+        updated_after: str | None = Query(None),
+        updated_before: str | None = Query(None),
+    ):
+        cur = CursorParams(cursor=cursor, limit=limit) if allow_cursor else None
+        pag = PageParams(page=page, page_size=page_size) if allow_page else None
+        flt = (
+            FilterParams(
+                q=q,
+                sort=sort,
+                created_after=created_after,
+                created_before=created_before,
+                updated_after=updated_after,
+                updated_before=updated_before,
+            )
+            if include_filters
+            else None
+        )
+
+        _pagination_ctx.set(
+            PaginationContext(
+                envelope=envelope,
+                allow_cursor=allow_cursor,
+                allow_page=allow_page,
+                cursor_params=cur,
+                page_params=pag,
+                filters=flt,
+            )
+        )
+        return None
+
+    return _inject
+
+
+# ----- Convenience helpers for routers -----
+def cursor_pager(
+    default_limit: int = 50,
+    max_limit: int = 200,
+    *,
+    envelope: bool = True,
+    include_filters: bool = False,
+):
+    """
+    The one-liner most routes should use.
+    Produces OpenAPI with only: `cursor` and `limit` (plus filters if requested).
+    """
+    return make_pagination_injector(
+        envelope=envelope,
+        allow_cursor=True,
+        allow_page=False,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        include_filters=include_filters,
+    )

svc_infra/api/fastapi/paths/auth.py

@@ -1,19 +1,19 @@
 # --- API KEYS ---
-LIST_KEYS_PATH = "/auth/keys"
-CREATE_KEY_PATH = "/auth/keys"
-REVOKE_KEY_PATH = "/auth/keys/{key_id}/revoke"
-DELETE_KEY_PATH = "/auth/keys/{key_id}"
+LIST_KEYS_PATH = "/keys"
+CREATE_KEY_PATH = "/keys"
+REVOKE_KEY_PATH = "/keys/{key_id}/revoke"
+DELETE_KEY_PATH = "/keys/{key_id}"
 
 # --- MFA ---
-MFA_START_PATH = "/auth/mfa/start"
-MFA_CONFIRM_PATH = "/auth/mfa/confirm"
-MFA_DISABLE_PATH = "/auth/mfa/disable"
-MFA_STATUS_PATH = "/auth/mfa/status"
-MFA_REGENERATE_RECOVERY_PATH = "/auth/mfa/recovery/regenerate"
-MFA_VERIFY_PATH = "/auth/mfa/verify"
-MFA_SEND_CODE_PATH = "/auth/mfa/send_code"
+MFA_START_PATH = "/mfa/start"
+MFA_CONFIRM_PATH = "/mfa/confirm"
+MFA_DISABLE_PATH = "/mfa/disable"
+MFA_STATUS_PATH = "/mfa/status"
+MFA_REGENERATE_RECOVERY_PATH = "/mfa/recovery/regenerate"
+MFA_VERIFY_PATH = "/mfa/verify"
+MFA_SEND_CODE_PATH = "/mfa/send_code"
 
 # --- OAUTH ---
-OAUTH_LOGIN_PATH = "/auth/oauth/{provider}/login"
-OAUTH_CALLBACK_PATH = "/auth/oauth/{provider}/callback"
-OAUTH_REFRESH_PATH = "/auth/oauth/refresh"
+OAUTH_LOGIN_PATH = "/{provider}/login"
+OAUTH_CALLBACK_PATH = "/{provider}/callback"
+OAUTH_REFRESH_PATH = "/refresh"

svc_infra/api/fastapi/paths/prefix.py

@@ -1,3 +1,2 @@
 AUTH_PREFIX = "/auth"
-OAUTH_PREFIX = "/auth/oauth"
 USER_PREFIX = "/users"

svc_infra/api/fastapi/paths/user.py

@@ -6,5 +6,5 @@ REQUEST_VERIFY_TOKEN_PATH = "/request-verify-token"
 VERIFY_PATH = "/verify"
 FORGOT_PASSWORD_PATH = "/forgot-password"
 RESET_PASSWORD_PATH = "/reset-password"
-DISABLE_ACCOUNT_PATH = "/status"
+DISABLE_ACCOUNT_PATH = "/disable"
 DELETE_ACCOUNT_PATH = "/delete"

svc_infra/api/fastapi/routers/ping.py

@@ -14,6 +14,7 @@ router = public_router(tags=["Health Check"])
     PING_PATH,
     status_code=status.HTTP_200_OK,
     description="Operation to check if the service is up and running",
+    operation_id="health_ping_get",
 )
 def ping():
     logging.info("Health check: /ping endpoint accessed. Service is responsive.")

svc_infra/api/fastapi/setup.py

@@ -11,13 +11,22 @@ from fastapi.responses import HTMLResponse
 from fastapi.routing import APIRoute
 
 from svc_infra.api.fastapi.docs.landing import CardSpec, DocTargets, render_index_html
+from svc_infra.api.fastapi.docs.scoped import DOC_SCOPES
 from svc_infra.api.fastapi.middleware.errors.catchall import CatchAllExceptionMiddleware
 from svc_infra.api.fastapi.middleware.errors.handlers import register_error_handlers
+from svc_infra.api.fastapi.middleware.graceful_shutdown import install_graceful_shutdown
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.ratelimit import SimpleRateLimitMiddleware
+from svc_infra.api.fastapi.middleware.request_id import RequestIdMiddleware
+from svc_infra.api.fastapi.middleware.timeout import (
+    BodyReadTimeoutMiddleware,
+    HandlerTimeoutMiddleware,
+)
 from svc_infra.api.fastapi.openapi.models import APIVersionSpec, ServiceInfo
 from svc_infra.api.fastapi.openapi.mutators import setup_mutators
 from svc_infra.api.fastapi.openapi.pipeline import apply_mutators
 from svc_infra.api.fastapi.routers import register_all_routers
-from svc_infra.app.env import CURRENT_ENVIRONMENT
+from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV
 
 logger = logging.getLogger(__name__)
 
@@ -57,7 +66,8 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
     elif isinstance(public_cors_origins, str):
         origins = [o.strip() for o in public_cors_origins.split(",") if o and o.strip()]
     else:
-        fallback = os.getenv("CORS_ALLOW_ORIGINS", "http://localhost:3000")
+        # Strict by default: no CORS unless explicitly configured via env or parameter.
+        fallback = os.getenv("CORS_ALLOW_ORIGINS", "")
         origins = [o.strip() for o in fallback.split(",") if o and o.strip()]
 
     if not origins:
@@ -72,6 +82,20 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
     app.add_middleware(CORSMiddleware, **cors_kwargs)
 
 
+def _setup_middlewares(app: FastAPI):
+    app.add_middleware(RequestIdMiddleware)
+    # Timeouts: enforce body read timeout first, then total handler timeout
+    app.add_middleware(BodyReadTimeoutMiddleware)
+    app.add_middleware(HandlerTimeoutMiddleware)
+    app.add_middleware(CatchAllExceptionMiddleware)
+    app.add_middleware(IdempotencyMiddleware)
+    app.add_middleware(SimpleRateLimitMiddleware)
+    register_error_handlers(app)
+    _add_route_logger(app)
+    # Graceful shutdown: track in-flight and wait on shutdown
+    install_graceful_shutdown(app)
+
+
 def _coerce_list(value: str | Iterable[str] | None) -> list[str]:
     if value is None:
         return []
@@ -85,19 +109,18 @@ def _dump_or_none(model):
 
 
 def _build_child_app(service: ServiceInfo, spec: APIVersionSpec) -> FastAPI:
+    title = f"{service.name} • {spec.tag}" if getattr(spec, "tag", None) else service.name
     child = FastAPI(
-        title=service.name,
+        title=title,
         version=service.release,
-        contact=_dump_or_none(service.contact),  # FastAPI expects plain dicts
+        contact=_dump_or_none(service.contact),
         license_info=_dump_or_none(service.license),
         terms_of_service=service.terms_of_service,
         description=service.description,
         generate_unique_id_function=_gen_operation_id_factory(),
     )
 
-    child.add_middleware(CatchAllExceptionMiddleware)
-    register_error_handlers(child)
-    _add_route_logger(child)
+    _setup_middlewares(child)
 
     # ---- OpenAPI pipeline (DRY!) ----
     include_api_key = bool(spec.include_api_key) if spec.include_api_key is not None else False
@@ -133,8 +156,9 @@ def _build_parent_app(
     public_cors_origins: list[str] | str | None,
     root_routers: list[str] | str | None,
     root_server_url: str | None = None,
-    root_include_api_key: bool = False,  # <-- NEW
+    root_include_api_key: bool = False,
 ) -> FastAPI:
+    # Root docs are now enabled in all environments to match root card visibility
     parent = FastAPI(
         title=service.name,
         version=service.release,
@@ -148,9 +172,7 @@ def _build_parent_app(
     )
 
     _setup_cors(parent, public_cors_origins)
-    parent.add_middleware(CatchAllExceptionMiddleware)
-    register_error_handlers(parent)
-    _add_route_logger(parent)
+    _setup_middlewares(parent)
 
     mutators = setup_mutators(
         service=service,
@@ -219,19 +241,20 @@ def setup_service_api(
         mount_path = f"/{spec.tag.strip('/')}"
         parent.mount(mount_path, child, name=spec.tag.strip("/"))
 
-    @parent.get("/", include_in_schema=False)
+    @parent.get("/", include_in_schema=False, response_class=HTMLResponse)
     def index():
         cards: list[CardSpec] = []
+        is_local_dev = CURRENT_ENVIRONMENT in (LOCAL_ENV, DEV_ENV)
 
-        # Root card first
+        # Root card - always show in all environments
         cards.append(
             CardSpec(
-                tag="",  # renders as "/"
+                tag="",
                 docs=DocTargets(swagger="/docs", redoc="/redoc", openapi_json="/openapi.json"),
             )
         )
 
-        # One card per version
+        # Version cards
         for spec in versions:
             tag = spec.tag.strip("/")
             cards.append(
@@ -245,6 +268,16 @@ def setup_service_api(
                 )
             )
 
+        if is_local_dev:
+            # Scoped cards (auth, payments, etc.)
+            for scope, swagger, redoc, openapi_json, title in DOC_SCOPES:
+                cards.append(
+                    CardSpec(
+                        tag=scope.strip("/"),
+                        docs=DocTargets(swagger=swagger, redoc=redoc, openapi_json=openapi_json),
+                    )
+                )
+
         html = render_index_html(service_name=service.name, release=service.release, cards=cards)
         return HTMLResponse(html)
 

svc_infra/api/fastapi/tenancy/add.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from fastapi import FastAPI
+
+from .context import set_tenant_resolver
+
+
+def add_tenancy(app: FastAPI, *, resolver: Optional[Callable[..., Any]] = None) -> None:
+    """Wire tenancy resolver for the application.
+
+    Provide a resolver(request, identity, header) -> Optional[str] to override
+    the default resolution. Pass None to clear a previous override.
+    """
+    set_tenant_resolver(resolver)
+
+
+__all__ = ["add_tenancy"]