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

svc_infra/api/fastapi/db/sql/session.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import logging
+import os
 from typing import Annotated, AsyncIterator, Tuple
 
 from fastapi import Depends
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     AsyncSession,
@@ -53,6 +55,20 @@ async def get_session() -> AsyncIterator[AsyncSession]:
     if _SessionLocal is None:
         raise RuntimeError("Database not initialized. Call add_sql_db(app, ...) first.")
     async with _SessionLocal() as session:
+        # Optional: set a per-transaction statement timeout for Postgres if configured
+        raw_ms = os.getenv("DB_STATEMENT_TIMEOUT_MS")
+        if raw_ms:
+            try:
+                ms = int(raw_ms)
+                if ms > 0:
+                    try:
+                        # SET LOCAL applies for the duration of the current transaction only
+                        await session.execute(text("SET LOCAL statement_timeout = :ms"), {"ms": ms})
+                    except Exception:
+                        # Non-PG dialects (e.g., SQLite) will error; ignore silently
+                        pass
+            except ValueError:
+                pass
         try:
             yield session
             await session.commit()

svc_infra/api/fastapi/db/sql/users.py

@@ -12,6 +12,7 @@ from svc_infra.api.fastapi.auth.settings import get_auth_settings
 from svc_infra.api.fastapi.dual.dualize import dualize_public, dualize_user
 from svc_infra.api.fastapi.dual.router import DualAPIRouter
 from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV
+from svc_infra.security.jwt_rotation import RotatingJWTStrategy
 
 from ...auth.security import auth_login_path
 from ...auth.sender import get_sender
@@ -94,7 +95,18 @@ def get_fastapi_users(
         lifetime = getattr(jwt_block, "lifetime_seconds", None) if jwt_block else None
         if not isinstance(lifetime, int) or lifetime <= 0:
             lifetime = 3600
-        return JWTStrategy(secret=secret, lifetime_seconds=lifetime)
+        old = []
+        if jwt_block and getattr(jwt_block, "old_secrets", None):
+            old = [s.get_secret_value() for s in jwt_block.old_secrets or []]
+        audience = "fastapi-users:auth"
+        if old:
+            return RotatingJWTStrategy(
+                secret=secret,
+                lifetime_seconds=lifetime,
+                old_secrets=old,
+                token_audience=audience,
+            )
+        return JWTStrategy(secret=secret, lifetime_seconds=lifetime, token_audience=audience)
 
     bearer_transport = BearerTransport(tokenUrl=auth_login_path)
     auth_backend = AuthenticationBackend(
@@ -107,7 +119,7 @@ def get_fastapi_users(
         fastapi_users.get_auth_router(auth_backend, requires_verification=True)
     )
     users_router = dualize_user(
-        fastapi_users.get_users_router(user_schema_read, user_schema_create, user_schema_update)
+        fastapi_users.get_users_router(user_schema_read, user_schema_update)
     )
     register_router = dualize_public(
         fastapi_users.get_register_router(user_schema_read, user_schema_create)

svc_infra/api/fastapi/dependencies/ratelimit.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+from fastapi import HTTPException
+from starlette.requests import Request
+
+from svc_infra.api.fastapi.middleware.ratelimit_store import InMemoryRateLimitStore, RateLimitStore
+
+try:
+    from svc_infra.api.fastapi.tenancy.context import resolve_tenant_id as _resolve_tenant_id
+except Exception:  # pragma: no cover - minimal builds
+    _resolve_tenant_id = None  # type: ignore
+from svc_infra.obs.metrics import emit_rate_limited
+
+
+class RateLimiter:
+    def __init__(
+        self,
+        *,
+        limit: int,
+        window: int = 60,
+        key_fn: Callable = lambda r: "global",
+        limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+        scope_by_tenant: bool = False,
+        store: RateLimitStore | None = None,
+    ):
+        self.limit = limit
+        self.window = window
+        self.key_fn = key_fn
+        self._limit_resolver = limit_resolver
+        self.scope_by_tenant = scope_by_tenant
+        self.store = store or InMemoryRateLimitStore(limit=limit)
+
+    async def __call__(self, request: Request):
+        # Try resolving tenant when asked
+        tenant_id = None
+        if self.scope_by_tenant or self._limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
+        key = self.key_fn(request)
+        if self.scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = self.limit
+        if self._limit_resolver:
+            try:
+                v = self._limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else self.limit
+            except Exception:
+                eff_limit = self.limit
+
+        count, store_limit, reset = self.store.incr(str(key), self.window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception:
+                pass
+            raise HTTPException(
+                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+            )
+
+
+__all__ = ["RateLimiter"]
+
+
+def rate_limiter(
+    *,
+    limit: int,
+    window: int = 60,
+    key_fn: Callable = lambda r: "global",
+    limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+    scope_by_tenant: bool = False,
+    store: RateLimitStore | None = None,
+):
+    store_ = store or InMemoryRateLimitStore(limit=limit)
+
+    async def dep(request: Request):
+        tenant_id = None
+        if scope_by_tenant or limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
+        key = key_fn(request)
+        if scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = limit
+        if limit_resolver:
+            try:
+                v = limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else limit
+            except Exception:
+                eff_limit = limit
+
+        count, _store_limit, reset = store_.incr(str(key), window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception:
+                pass
+            raise HTTPException(
+                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+            )
+
+    return dep

svc_infra/api/fastapi/docs/add.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, Request
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from .landing import CardSpec, DocTargets, render_index_html
+from .scoped import DOC_SCOPES
+
+
+def add_docs(
+    app: FastAPI,
+    *,
+    redoc_url: str = "/redoc",
+    swagger_url: str = "/docs",
+    openapi_url: str = "/openapi.json",
+    export_openapi_to: Optional[str] = None,
+    # Landing page options
+    landing_url: str = "/",
+    include_landing: bool = True,
+) -> None:
+    """Enable docs endpoints and optionally export OpenAPI schema to disk on startup.
+
+    We mount docs and OpenAPI routes explicitly so this works even when configured post-init.
+    """
+
+    # OpenAPI JSON route
+    async def openapi_handler() -> JSONResponse:  # noqa: ANN201
+        return JSONResponse(app.openapi())
+
+    app.add_api_route(openapi_url, openapi_handler, methods=["GET"], include_in_schema=False)
+
+    # Swagger UI route
+    async def swagger_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_swagger_ui_html(openapi_url=openapi_url, title="API Docs")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
+
+    app.add_api_route(swagger_url, swagger_ui, methods=["GET"], include_in_schema=False)
+
+    # Redoc route
+    async def redoc_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_redoc_html(openapi_url=openapi_url, title="API ReDoc")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
+
+    app.add_api_route(redoc_url, redoc_ui, methods=["GET"], include_in_schema=False)
+
+    # Optional export to disk on startup
+    if export_openapi_to:
+        export_path = Path(export_openapi_to)
+
+        async def _export_docs() -> None:
+            # Startup export
+            spec = app.openapi()
+            export_path.parent.mkdir(parents=True, exist_ok=True)
+            export_path.write_text(json.dumps(spec, indent=2))
+
+        app.add_event_handler("startup", _export_docs)
+
+    # Optional landing page with the same look/feel as setup_service_api
+    if include_landing:
+        # Avoid path collision; if landing_url is already taken for GET, fallback to "/_docs"
+        existing_paths = {
+            (getattr(r, "path", None) or getattr(r, "path_format", None))
+            for r in getattr(app, "routes", [])
+            if getattr(r, "methods", None) and "GET" in r.methods
+        }
+        landing_path = landing_url or "/"
+        if landing_path in existing_paths:
+            landing_path = "/_docs"
+
+        async def _landing() -> HTMLResponse:  # noqa: ANN201
+            cards: list[CardSpec] = []
+            # Root docs card using the provided paths
+            cards.append(
+                CardSpec(
+                    tag="",
+                    docs=DocTargets(swagger=swagger_url, redoc=redoc_url, openapi_json=openapi_url),
+                )
+            )
+            # Scoped docs (if any were registered via add_prefixed_docs)
+            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=app.title or "API", release=app.version or "", cards=cards
+            )
+            return HTMLResponse(html)
+
+        app.add_api_route(landing_path, _landing, methods=["GET"], include_in_schema=False)
+
+
+def _with_dark_mode(resp: HTMLResponse) -> HTMLResponse:
+    """Return a copy of the HTMLResponse with a minimal dark-theme CSS injected.
+
+    We avoid depending on custom Swagger/ReDoc builds; this works by inlining a small CSS
+    block and toggling a `.dark` class on the body element.
+    """
+    try:
+        body = resp.body.decode("utf-8", errors="ignore")
+    except Exception:  # pragma: no cover - very unlikely
+        return resp
+
+    css = _DARK_CSS
+    if "</head>" in body:
+        body = body.replace("</head>", f"<style>\n{css}\n</style></head>", 1)
+    # add class to body to allow stronger selectors
+    body = body.replace("<body>", '<body class="dark">', 1)
+    return HTMLResponse(content=body, status_code=resp.status_code, headers=dict(resp.headers))
+
+
+_DARK_CSS = """
+/* Minimal dark mode override for Swagger/ReDoc */
+@media (prefers-color-scheme: dark) { :root { color-scheme: dark; } }
+html.dark, body.dark { background: #0b0e14; color: #e0e6f1; }
+#swagger, .redoc-wrap { background: transparent; }
+a { color: #62aef7; }
+"""
+
+
+def add_sdk_generation_stub(
+    app: FastAPI,
+    *,
+    on_generate: Optional[callable] = None,
+    openapi_path: str = "/openapi.json",
+) -> None:
+    """Hook to add an SDK generation stub.
+
+    Provide `on_generate()` to run generation (e.g., openapi-generator). This is a stub only; we
+    don't ship a hard dependency. If `on_generate` is provided, we expose `/_docs/generate-sdk`.
+    """
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    if not on_generate:
+        return
+
+    router = public_router(prefix="/_docs", include_in_schema=False)
+
+    @router.post("/generate-sdk")
+    async def _generate() -> dict:  # noqa: ANN201
+        on_generate()
+        return {"status": "ok"}
+
+    app.include_router(router)
+
+
+__all__ = ["add_docs", "add_sdk_generation_stub"]

svc_infra/api/fastapi/docs/landing.py

@@ -115,7 +115,7 @@ def render_index_html(*, service_name: str, release: str, cards: Iterable[CardSp
     <section class="grid">
       {grid}
     </section>
-    <footer>Tip: each card exposes Swagger, ReDoc, and a pretty JSON view.</footer>
+    <footer>Tip: each card exposes Swagger, ReDoc, and a JSON view.</footer>
   </div>
 </body>
 </html>

svc_infra/api/fastapi/docs/scoped.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import copy
+from typing import Dict, Iterable, List, Optional, Set, Tuple
+
+from fastapi import FastAPI
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.responses import HTMLResponse
+
+from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV, Environment
+
+# (prefix, swagger_path, redoc_path, openapi_path, title)
+DOC_SCOPES: List[Tuple[str, str, str, str, str]] = []
+
+_HTTP_METHODS = {"get", "put", "post", "delete", "patch", "options", "head", "trace"}
+
+
+def _path_included(
+    path: str,
+    include_prefixes: Optional[Iterable[str]] = None,
+    exclude_prefixes: Optional[Iterable[str]] = None,
+) -> bool:
+    def _match(pfx: str) -> bool:
+        pfx = pfx.rstrip("/") or "/"
+        return path == pfx or path.startswith(pfx + "/")
+
+    if include_prefixes and not any(_match(p) for p in include_prefixes):
+        return False
+    if exclude_prefixes and any(_match(p) for p in exclude_prefixes):
+        return False
+    return True
+
+
+def _collect_refs(obj, refset: Set[Tuple[str, str]]):
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if k == "$ref" and isinstance(v, str) and v.startswith("#/components/"):
+                parts = v.split("/")
+                if len(parts) >= 4:
+                    refset.add((parts[2], parts[3]))
+            else:
+                _collect_refs(v, refset)
+    elif isinstance(obj, list):
+        for it in obj:
+            _collect_refs(it, refset)
+
+
+def _close_over_component_refs(
+    full_components: Dict, initial: Set[Tuple[str, str]]
+) -> Set[Tuple[str, str]]:
+    to_visit = list(initial)
+    seen = set(initial)
+    while to_visit:
+        section, name = to_visit.pop()
+        comp = (full_components or {}).get(section, {}).get(name)
+        if not isinstance(comp, dict):
+            continue
+        nested: Set[Tuple[str, str]] = set()
+        _collect_refs(comp, nested)
+        for ref in nested:
+            if ref not in seen:
+                seen.add(ref)
+                to_visit.append(ref)
+    return seen
+
+
+def _prune_to_paths(
+    full_schema: Dict,
+    keep_paths: Dict[str, dict],
+    title_suffix: Optional[str],
+    server_prefix: Optional[str] = None,
+) -> Dict:
+    schema = copy.deepcopy(full_schema)
+    schema["paths"] = keep_paths
+
+    # Set server URL for scoped docs
+    if server_prefix is not None:
+        schema["servers"] = [{"url": server_prefix}]
+
+    used_tags: Set[str] = set()
+    direct_refs: Set[Tuple[str, str]] = set()
+    used_security_schemes: Set[str] = set()
+
+    for path_item in keep_paths.values():
+        for method, op in path_item.items():
+            if method.lower() not in _HTTP_METHODS:
+                continue
+            for t in op.get("tags", []) or []:
+                used_tags.add(t)
+            _collect_refs(op, direct_refs)
+            for sec in op.get("security", []) or []:
+                for scheme_name in sec.keys():
+                    used_security_schemes.add(scheme_name)
+
+    comps = schema.get("components") or {}
+    all_refs = _close_over_component_refs(comps, direct_refs)
+
+    pruned_components: Dict[str, Dict] = {}
+    if isinstance(comps, dict):
+        for section, items in comps.items():
+            keep_names = {name for (sec, name) in all_refs if sec == section}
+            if section == "securitySchemes":
+                keep_names |= used_security_schemes
+            if not keep_names:
+                continue
+            pruned = {name: items[name] for name in keep_names if name in items}
+            if pruned:
+                pruned_components[section] = pruned
+    schema["components"] = pruned_components if pruned_components else {}
+
+    if "tags" in schema and isinstance(schema["tags"], list):
+        schema["tags"] = [
+            t for t in schema["tags"] if isinstance(t, dict) and t.get("name") in used_tags
+        ]
+
+    info = dict(schema.get("info") or {})
+    if title_suffix:
+        info["title"] = f"{info.get('title') or 'API'} • {title_suffix}"
+    schema["info"] = info
+    return schema
+
+
+def _build_filtered_schema(
+    full_schema: Dict,
+    *,
+    include_prefixes: Optional[List[str]] = None,
+    exclude_prefixes: Optional[List[str]] = None,
+    title_suffix: Optional[str] = None,
+) -> Dict:
+    paths = full_schema.get("paths", {}) or {}
+    keep_paths = {
+        p: v for p, v in paths.items() if _path_included(p, include_prefixes, exclude_prefixes)
+    }
+
+    # Determine the server prefix for scoped docs
+    server_prefix = None
+    if include_prefixes and len(include_prefixes) == 1:
+        # Single include prefix = scoped docs
+        server_prefix = include_prefixes[0].rstrip("/") or "/"
+
+        # Strip prefix from paths to make them relative to the server
+        stripped_paths = {}
+        for path, spec in keep_paths.items():
+            if path.startswith(server_prefix) and path != server_prefix:
+                # Remove prefix, keeping the leading slash
+                relative_path = path[len(server_prefix) :]
+                stripped_paths[relative_path] = spec
+            else:
+                # Path equals prefix or doesn't start with it
+                stripped_paths[path] = spec
+        keep_paths = stripped_paths
+
+    return _prune_to_paths(full_schema, keep_paths, title_suffix, server_prefix=server_prefix)
+
+
+def _ensure_original_openapi_saved(app: FastAPI) -> None:
+    if not hasattr(app.state, "_scoped_original_openapi"):
+        app.state._scoped_original_openapi = app.openapi  # type: ignore[attr-defined]
+
+
+def _get_full_schema_from_original(app: FastAPI) -> Dict:
+    _ensure_original_openapi_saved(app)
+    return copy.deepcopy(app.state._scoped_original_openapi())  # type: ignore[attr-defined]
+
+
+def _install_root_filter(app: FastAPI, exclude_prefixes: List[str]) -> None:
+    _ensure_original_openapi_saved(app)
+    app.state._scoped_root_exclusions = sorted(set(exclude_prefixes))  # type: ignore[attr-defined]
+
+    def root_filtered_openapi():
+        full_schema = _get_full_schema_from_original(app)
+        return _build_filtered_schema(full_schema, exclude_prefixes=app.state._scoped_root_exclusions)  # type: ignore[attr-defined]
+
+    app.openapi = root_filtered_openapi
+
+
+def _current_registered_scopes() -> List[str]:
+    return [scope for (scope, *_rest) in DOC_SCOPES]
+
+
+def _ensure_root_excludes_registered_scopes(app: FastAPI) -> None:
+    scopes = _current_registered_scopes()
+    if scopes:
+        _install_root_filter(app, scopes)
+
+
+def _normalize_envs(envs: Optional[Iterable[Environment | str]]) -> Optional[set[Environment]]:
+    if envs is None:
+        return None
+    out: set[Environment] = set()
+    for e in envs:
+        out.add(e if isinstance(e, Environment) else Environment(e))
+    return out
+
+
+def add_prefixed_docs(
+    app: FastAPI,
+    *,
+    prefix: str,
+    title: str,
+    auto_exclude_from_root: bool = True,
+    visible_envs: Optional[Iterable[Environment | str]] = (LOCAL_ENV, DEV_ENV),
+) -> None:
+    scope = prefix.rstrip("/") or "/"
+
+    # Always exclude from root if requested, regardless of environment
+    if auto_exclude_from_root:
+        _ensure_original_openapi_saved(app)
+        # Add to exclusion list for root docs
+        if not hasattr(app.state, "_scoped_root_exclusions"):
+            app.state._scoped_root_exclusions = []
+        if scope not in app.state._scoped_root_exclusions:
+            app.state._scoped_root_exclusions.append(scope)
+            _install_root_filter(app, app.state._scoped_root_exclusions)
+
+    # Only create scoped docs in allowed environments
+    allow = _normalize_envs(visible_envs)
+    if allow is not None and CURRENT_ENVIRONMENT not in allow:
+        return
+
+    openapi_path = f"{scope}/openapi.json"
+    swagger_path = f"{scope}/docs"
+    redoc_path = f"{scope}/redoc"
+
+    _ensure_original_openapi_saved(app)
+    _scope_cache: Dict | None = None
+
+    def _scoped_schema():
+        nonlocal _scope_cache
+        if _scope_cache is None:
+            full = _get_full_schema_from_original(app)
+            _scope_cache = _build_filtered_schema(
+                full, include_prefixes=[scope], title_suffix=title
+            )
+        return _scope_cache
+
+    # --- Register directly on the app to ensure truly public & collision-proof ---
+    @app.get(openapi_path, include_in_schema=False)
+    def scoped_openapi():
+        return _scoped_schema()
+
+    @app.get(swagger_path, include_in_schema=False, response_class=HTMLResponse)
+    def scoped_swagger():
+        return get_swagger_ui_html(openapi_url=openapi_path, title=f"{title} • Swagger")
+
+    @app.get(redoc_path, include_in_schema=False, response_class=HTMLResponse)
+    def scoped_redoc():
+        return get_redoc_html(openapi_url=openapi_path, title=f"{title} • ReDoc")
+
+    DOC_SCOPES.append((scope, swagger_path, redoc_path, openapi_path, title))
+
+
+def replace_root_openapi_with_exclusions(app: FastAPI, *, exclude_prefixes: List[str]) -> None:
+    _install_root_filter(app, exclude_prefixes)