svc-infra 0.1.600__py3-none-any.whl → 0.1.640__py3-none-any.whl

svc_infra/api/fastapi/middleware/timeout.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import asyncio
+import os
+
+from fastapi import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from svc_infra.api.fastapi.middleware.errors.handlers import problem_response
+from svc_infra.app.env import pick
+
+
+def _env_int(name: str, default: int) -> int:
+    v = os.getenv(name)
+    if v is None:
+        return default
+    try:
+        return int(v)
+    except Exception:
+        return default
+
+
+REQUEST_BODY_TIMEOUT_SECONDS: int = pick(
+    prod=_env_int("REQUEST_BODY_TIMEOUT_SECONDS", 15),
+    nonprod=_env_int("REQUEST_BODY_TIMEOUT_SECONDS", 30),
+)
+REQUEST_TIMEOUT_SECONDS: int = pick(
+    prod=_env_int("REQUEST_TIMEOUT_SECONDS", 30),
+    nonprod=_env_int("REQUEST_TIMEOUT_SECONDS", 15),
+)
+
+
+class HandlerTimeoutMiddleware:
+    """
+    Caps total handler execution time. If exceeded, returns 504 Problem+JSON.
+    """
+
+    def __init__(self, app: ASGIApp, timeout_seconds: int | None = None) -> None:
+        self.app = app
+        self.timeout_seconds = (
+            timeout_seconds if timeout_seconds is not None else REQUEST_TIMEOUT_SECONDS
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def _call_next() -> None:
+            await self.app(scope, receive, send)
+
+        try:
+            await asyncio.wait_for(_call_next(), timeout=self.timeout_seconds)
+        except asyncio.TimeoutError:
+            # Build a minimal Request to extract headers and URL for trace info
+            request = Request(scope, receive=receive)
+            trace_id = None
+            for h in ("x-request-id", "x-correlation-id", "x-trace-id"):
+                v = request.headers.get(h)
+                if v:
+                    trace_id = v
+                    break
+            resp = problem_response(
+                status=504,
+                title="Gateway Timeout",
+                detail="The request took too long to complete.",
+                code="GATEWAY_TIMEOUT",
+                instance=str(request.url),
+                trace_id=trace_id,
+            )
+            await resp(scope, receive, send)
+
+
+class BodyReadTimeoutMiddleware:
+    """
+    Enforces a timeout while reading the request body to mitigate slowloris.
+    If body read does not make progress within the timeout, returns 408 Problem+JSON.
+    """
+
+    def __init__(self, app: ASGIApp, timeout_seconds: int | None = None) -> None:
+        self.app = app
+        self.timeout_seconds = (
+            timeout_seconds if timeout_seconds is not None else REQUEST_BODY_TIMEOUT_SECONDS
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Strategy: greedily drain the incoming request body here while enforcing
+        # per-receive timeout, then replay it to the downstream app from a buffer.
+        # This ensures we can detect slowloris-style uploads even if the app only
+        # reads the body later (after the server has finished buffering).
+        buffered = bytearray()
+
+        try:
+            while True:
+                message = await asyncio.wait_for(receive(), timeout=self.timeout_seconds)
+
+                mtype = message.get("type")
+                if mtype == "http.request":
+                    chunk = message.get("body", b"") or b""
+                    if chunk:
+                        buffered.extend(chunk)
+                    # Stop when server indicates no more body
+                    if not message.get("more_body", False):
+                        break
+                    # else: continue reading remaining chunks with timeout
+                    continue
+
+                if mtype == "http.disconnect":  # client disconnected mid-upload
+                    # Treat as end of body for the purposes of replay; downstream
+                    # will see an empty body. No timeout response needed here.
+                    break
+                # Ignore other message types and continue
+        except asyncio.TimeoutError:
+            # Timed out while waiting for the next body chunk → return 408
+            request = Request(scope, receive=receive)
+            trace_id = None
+            for h in ("x-request-id", "x-correlation-id", "x-trace-id"):
+                v = request.headers.get(h)
+                if v:
+                    trace_id = v
+                    break
+            resp = problem_response(
+                status=408,
+                title="Request Timeout",
+                detail="Timed out while reading request body.",
+                code="REQUEST_TIMEOUT",
+                instance=str(request.url),
+                trace_id=trace_id,
+            )
+            await resp(scope, receive, send)
+            return
+
+        # Replay the drained body to the app as a single http.request message.
+        sent = False
+
+        async def _replay_receive() -> dict:
+            nonlocal sent
+            if not sent:
+                sent = True
+                return {"type": "http.request", "body": bytes(buffered), "more_body": False}
+            # Subsequent calls return an empty terminal body event
+            return {"type": "http.request", "body": b"", "more_body": False}
+
+        await self.app(scope, _replay_receive, send)

svc_infra/api/fastapi/openapi/mutators.py

@@ -1102,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)
@@ -1429,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"]

svc_infra/api/fastapi/pagination.py

@@ -89,7 +89,9 @@ class PaginationContext(Generic[T]):
 
     @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

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

@@ -14,9 +14,14 @@ from svc_infra.api.fastapi.docs.landing import CardSpec, DocTargets, render_inde
 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
@@ -79,11 +84,16 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
 
 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]:
@@ -232,7 +242,7 @@ 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)

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

svc_infra/api/fastapi/tenancy/context.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable, Optional
+
+from fastapi import Depends, HTTPException, Request
+
+try:  # optional import; auth may not be used by all consumers
+    from svc_infra.api.fastapi.auth.security import OptionalIdentity
+except Exception:  # pragma: no cover - fallback for minimal builds
+    OptionalIdentity = None  # type: ignore
+
+
+_tenant_resolver: Optional[Callable[..., Any]] = None
+
+
+def set_tenant_resolver(
+    fn: Optional[Callable[..., Any]],
+) -> None:
+    """Set or clear a global override hook for tenant resolution.
+
+    The function receives (request, identity, tenant_header) and should return a tenant id
+    string or None to fall back to default logic.
+    """
+    global _tenant_resolver
+    _tenant_resolver = fn
+
+
+async def _maybe_await(x):
+    if callable(getattr(x, "__await__", None)):
+        return await x  # type: ignore[misc]
+    return x
+
+
+async def resolve_tenant_id(
+    request: Request,
+    tenant_header: Optional[str] = None,
+    identity: Any = Depends(OptionalIdentity) if OptionalIdentity else None,  # type: ignore[arg-type]
+) -> Optional[str]:
+    """Resolve tenant id from override, identity, header, or request.state.
+
+    Order:
+      1) Global override hook (set_tenant_resolver)
+      2) Auth identity: user.tenant_id then api_key.tenant_id (if available)
+      3) X-Tenant-Id header
+      4) request.state.tenant_id
+    """
+    # read header value if not provided directly (supports direct calls without DI)
+    if tenant_header is None:
+        try:
+            tenant_header = request.headers.get("X-Tenant-Id")  # type: ignore[assignment]
+        except Exception:
+            tenant_header = None
+
+    # 1) global override
+    if _tenant_resolver is not None:
+        try:
+            v = _tenant_resolver(request, identity, tenant_header)
+            v2 = await _maybe_await(v)
+            if v2:
+                return str(v2)
+        except Exception:
+            # fall through to defaults
+            pass
+
+    # 2) from identity
+    try:
+        if identity and getattr(identity, "user", None) is not None:
+            tid = getattr(identity.user, "tenant_id", None)
+            if tid:
+                return str(tid)
+        if identity and getattr(identity, "api_key", None) is not None:
+            tid = getattr(identity.api_key, "tenant_id", None)
+            if tid:
+                return str(tid)
+    except Exception:
+        pass
+
+    # 3) from header
+    if tenant_header and isinstance(tenant_header, str) and tenant_header.strip():
+        return tenant_header.strip()
+
+    # 4) request.state
+    try:
+        st_tid = getattr(getattr(request, "state", object()), "tenant_id", None)
+        if st_tid:
+            return str(st_tid)
+    except Exception:
+        pass
+
+    return None
+
+
+async def require_tenant_id(
+    tenant_id: Optional[str] = Depends(resolve_tenant_id),
+) -> str:
+    if not tenant_id:
+        raise HTTPException(status_code=400, detail="tenant_context_missing")
+    return tenant_id
+
+
+# DX aliases
+TenantId = Annotated[str, Depends(require_tenant_id)]
+OptionalTenantId = Annotated[Optional[str], Depends(resolve_tenant_id)]
+
+
+__all__ = [
+    "TenantId",
+    "OptionalTenantId",
+    "resolve_tenant_id",
+    "require_tenant_id",
+    "set_tenant_resolver",
+]

svc_infra/app/README.md

@@ -14,9 +14,8 @@ This README shows:
 
 ```python
 # main.py (or wherever your app starts)
-from svc_infra.logging.logging import setup_logging
+from svc_infra.app.logging import setup_logging, LogLevelOptions
 from svc_infra.app.env import pick
-from svc_infra.logging.logging import LogLevelOptions
 ```
 
 ---
@@ -39,7 +38,8 @@ What you get by default:
 Set via code:
 
 ```python
-from svc_infra.logging.logging import LogFormatOptions, LogLevelOptions
+from svc_infra.app.logging.formats import LogFormatOptions
+from svc_infra.app.logging import LogLevelOptions
 
 setup_logging(
     level=LogLevelOptions.INFO,          # or "INFO"
@@ -119,7 +119,7 @@ Old (pre-filter) example:
 
 ```python
 from svc_infra.app.env import pick
-from svc_infra.logging.logging import setup_logging, LogLevelOptions
+from svc_infra.app.logging import setup_logging, LogLevelOptions
 
 setup_logging(
     level=pick(
@@ -183,7 +183,7 @@ LOG_DROP_PATHS=/metrics,/health,/healthz
 ## 7) One-liner quickstart
 
 ```python
-from svc_infra.logging import setup_logging
+from svc_infra.app.logging import setup_logging
 setup_logging()  # done: sensible defaults + filters in prod/test
 ```
 

svc_infra/billing/__init__.py

@@ -0,0 +1,23 @@
+from .models import (
+    Invoice,
+    InvoiceLine,
+    Plan,
+    PlanEntitlement,
+    Price,
+    Subscription,
+    UsageAggregate,
+    UsageEvent,
+)
+from .service import BillingService
+
+__all__ = [
+    "UsageEvent",
+    "UsageAggregate",
+    "Plan",
+    "PlanEntitlement",
+    "Subscription",
+    "Price",
+    "Invoice",
+    "InvoiceLine",
+    "BillingService",
+]