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

svc_infra/api/fastapi/setup.py

@@ -9,14 +9,20 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import HTMLResponse
 from fastapi.routing import APIRoute
+from starlette.types import ASGIApp, Receive, Scope, Send
 
 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
@@ -34,8 +40,9 @@ def _gen_operation_id_factory():
 
     def _gen(route: APIRoute) -> str:
         base = route.name or getattr(route.endpoint, "__name__", "op")
-        base = _normalize(base)
-        tag = _normalize(route.tags[0]) if route.tags else ""
+        base = _normalize(str(base))  # Convert Enum to str if needed
+        tag_raw = route.tags[0] if route.tags else ""
+        tag = _normalize(str(tag_raw)) if tag_raw else ""
         method = next(iter(route.methods or ["GET"])).lower()
 
         candidate = base
@@ -55,34 +62,103 @@ def _gen_operation_id_factory():
     return _gen
 
 
+def _origin_to_regex(origin: str) -> str | None:
+    """Convert a wildcard origin pattern to a regex.
+
+    Supports patterns like:
+      - "https://*.vercel.app" -> matches any subdomain
+      - "https://nfrax-*.vercel.app" -> matches nfrax-xxx.vercel.app
+
+    Returns None if the origin is not a pattern (no wildcards).
+    """
+    import re
+
+    if "*" not in origin:
+        return None
+    # Escape special regex chars except *, then replace * with regex pattern
+    escaped = re.escape(origin).replace(r"\*", "[a-zA-Z0-9_-]+")
+    return f"^{escaped}$"
+
+
 def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None):
+    # Collect origins from parameter
     if isinstance(public_cors_origins, list):
-        origins = [o.strip() for o in public_cors_origins if o and o.strip()]
+        param_origins = [o.strip() for o in public_cors_origins if o and o.strip()]
     elif isinstance(public_cors_origins, str):
-        origins = [o.strip() for o in public_cors_origins.split(",") if o and o.strip()]
+        param_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")
-        origins = [o.strip() for o in fallback.split(",") if o and o.strip()]
+        param_origins = []
+
+    # Collect origins from environment variable
+    env_value = os.getenv("CORS_ALLOW_ORIGINS", "")
+    env_origins = [o.strip() for o in env_value.split(",") if o and o.strip()]
+
+    # Merge both sources, removing duplicates while preserving order
+    seen = set()
+    origins = []
+    for o in param_origins + env_origins:
+        if o not in seen:
+            seen.add(o)
+            origins.append(o)
 
     if not origins:
         return
 
     cors_kwargs = dict(allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+
+    # Check for "*" (allow all) first
     if "*" in origins:
         cors_kwargs["allow_origin_regex"] = ".*"
     else:
-        cors_kwargs["allow_origins"] = origins
+        # Separate exact origins from wildcard patterns
+        exact_origins = []
+        patterns = []
+        for o in origins:
+            regex = _origin_to_regex(o)
+            if regex:
+                patterns.append(regex)
+            else:
+                exact_origins.append(o)
+
+        # If we have patterns, combine into a single regex with exact origins
+        if patterns:
+            # Convert exact origins to regex patterns too
+            import re
+
+            for exact in exact_origins:
+                patterns.append(f"^{re.escape(exact)}$")
+            # Combine all patterns with OR
+            cors_kwargs["allow_origin_regex"] = "|".join(patterns)
+        else:
+            # No patterns, just use allow_origins
+            cors_kwargs["allow_origins"] = exact_origins
+
+    app.add_middleware(CORSMiddleware, **cors_kwargs)  # type: ignore[arg-type]  # CORSMiddleware accepts these kwargs
+
+
+def _setup_middlewares(app: FastAPI, skip_paths: list[str] | None = None):
+    """Configure middleware stack. All middlewares are pure ASGI for streaming compatibility.
+
+    Args:
+        app: FastAPI application
+        skip_paths: Paths to skip for certain middlewares (e.g., long-running or streaming endpoints)
+    """
+    paths = skip_paths or []
 
-    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, skip_paths=paths)
     app.add_middleware(CatchAllExceptionMiddleware)
-    app.add_middleware(IdempotencyMiddleware)
-    app.add_middleware(SimpleRateLimitMiddleware)
+    # Idempotency and rate limiting
+    app.add_middleware(IdempotencyMiddleware, skip_paths=paths)
+    app.add_middleware(SimpleRateLimitMiddleware, skip_paths=paths)
     register_error_handlers(app)
-    _add_route_logger(app)
+    _add_route_logger(app, skip_paths=paths)
+    # Graceful shutdown: track in-flight and wait on shutdown
+    install_graceful_shutdown(app)
 
 
 def _coerce_list(value: str | Iterable[str] | None) -> list[str]:
@@ -97,23 +173,30 @@ def _dump_or_none(model):
     return model.model_dump(exclude_none=True) if model is not None else None
 
 
-def _build_child_app(service: ServiceInfo, spec: APIVersionSpec) -> FastAPI:
-    title = f"{service.name} • {spec.tag}" if getattr(spec, "tag", None) else service.name
+def _build_child_app(
+    service: ServiceInfo, spec: APIVersionSpec, skip_paths: list[str] | None = None
+) -> FastAPI:
+    title = (
+        f"{service.name} • {spec.tag}" if getattr(spec, "tag", None) else service.name
+    )
     child = FastAPI(
         title=title,
         version=service.release,
         contact=_dump_or_none(service.contact),
         license_info=_dump_or_none(service.license),
         terms_of_service=service.terms_of_service,
-        description=service.description,
+        description=service.description or "",
         generate_unique_id_function=_gen_operation_id_factory(),
     )
 
-    _setup_middlewares(child)
+    _setup_middlewares(child, skip_paths=skip_paths)
 
     # ---- OpenAPI pipeline (DRY!) ----
-    include_api_key = bool(spec.include_api_key) if spec.include_api_key is not None else False
-    mount_path = f"/{spec.tag.strip('/')}"
+    include_api_key = (
+        bool(spec.include_api_key) if spec.include_api_key is not None else False
+    )
+    tag_str = str(spec.tag).strip("/")
+    mount_path = f"/{tag_str}"
     server_url = (
         mount_path
         if not spec.public_base_url
@@ -130,11 +213,17 @@ def _build_child_app(service: ServiceInfo, spec: APIVersionSpec) -> FastAPI:
 
     if spec.routers_package:
         register_all_routers(
-            child, base_package=spec.routers_package, prefix="", environment=CURRENT_ENVIRONMENT
+            child,
+            base_package=spec.routers_package,
+            prefix="",
+            environment=CURRENT_ENVIRONMENT,
         )
 
     logger.info(
-        "[%s] initialized version %s [env: %s]", service.name, spec.tag, CURRENT_ENVIRONMENT
+        "[%s] initialized version %s [env: %s]",
+        service.name,
+        spec.tag,
+        CURRENT_ENVIRONMENT,
     )
     return child
 
@@ -146,23 +235,25 @@ def _build_parent_app(
     root_routers: list[str] | str | None,
     root_server_url: str | None = None,
     root_include_api_key: bool = False,
+    skip_paths: list[str] | None = None,
+    **fastapi_kwargs,  # Accept FastAPI kwargs
 ) -> FastAPI:
-    show_root_docs = CURRENT_ENVIRONMENT in (LOCAL_ENV, DEV_ENV)
-
+    # Root docs are now enabled in all environments to match root card visibility
     parent = FastAPI(
         title=service.name,
         version=service.release,
         contact=_dump_or_none(service.contact),
         license_info=_dump_or_none(service.license),
         terms_of_service=service.terms_of_service,
-        description=service.description,
-        docs_url=("/docs" if show_root_docs else None),
-        redoc_url=("/redoc" if show_root_docs else None),
-        openapi_url=("/openapi.json" if show_root_docs else None),
+        description=service.description or "",
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        **fastapi_kwargs,  # Forward to FastAPI constructor
     )
 
     _setup_cors(parent, public_cors_origins)
-    _setup_middlewares(parent)
+    _setup_middlewares(parent, skip_paths=skip_paths)
 
     mutators = setup_mutators(
         service=service,
@@ -181,23 +272,54 @@ def _build_parent_app(
     )
     # app-provided root routers
     for pkg in _coerce_list(root_routers):
-        register_all_routers(parent, base_package=pkg, prefix="", environment=CURRENT_ENVIRONMENT)
+        register_all_routers(
+            parent, base_package=pkg, prefix="", environment=CURRENT_ENVIRONMENT
+        )
 
     return parent
 
 
-def _add_route_logger(app: FastAPI):
-    @app.middleware("http")
-    async def _log_route(request, call_next):
-        resp = await call_next(request)
-        route = request.scope.get("route")
-        # Prefer FastAPI's path_format (shows param patterns), fall back to path
-        path = getattr(route, "path_format", None) or getattr(route, "path", None)
-        if path:
-            # Include mount root_path so mounted children show their full path
-            root_path = request.scope.get("root_path", "") or ""
-            resp.headers["X-Handled-By"] = f"{request.method} {root_path}{path}"
-        return resp
+class RouteLoggerMiddleware:
+    """Pure ASGI middleware to add X-Handled-By header."""
+
+    def __init__(self, app: ASGIApp, skip_paths: list[str] | None = None):
+        self.app = app
+        self.skip_paths = skip_paths or []
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        method = scope.get("method", "")
+
+        # Skip specified paths
+        if any(skip in path for skip in self.skip_paths):
+            await self.app(scope, receive, send)
+            return
+
+        # Wrap send to add header after response starts
+        async def send_wrapper(message):
+            if message["type"] == "http.response.start":
+                route = scope.get("route")
+                route_path = getattr(route, "path_format", None) or getattr(
+                    route, "path", None
+                )
+                if route_path:
+                    root_path = scope.get("root_path", "") or ""
+                    headers = list(message.get("headers", []))
+                    headers.append(
+                        (b"x-handled-by", f"{method} {root_path}{route_path}".encode())
+                    )
+                    message = {**message, "headers": headers}
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+
+def _add_route_logger(app: FastAPI, skip_paths: list[str] | None = None):
+    app.add_middleware(RouteLoggerMiddleware, skip_paths=skip_paths)
 
 
 def setup_service_api(
@@ -208,6 +330,8 @@ def setup_service_api(
     public_cors_origins: list[str] | str | None = None,
     root_public_base_url: str | None = None,
     root_include_api_key: bool | None = None,
+    skip_paths: list[str] | None = None,
+    **fastapi_kwargs,  # Forward all other FastAPI kwargs (lifespan, etc.)
 ) -> FastAPI:
     # infer if not explicitly provided
     effective_root_include_api_key = (
@@ -223,31 +347,35 @@ def setup_service_api(
         root_routers=root_routers,
         root_server_url=root_server,
         root_include_api_key=effective_root_include_api_key,
+        skip_paths=skip_paths,
+        **fastapi_kwargs,  # Forward to _build_parent_app
     )
 
     # Mount each version
     for spec in versions:
-        child = _build_child_app(service, spec)
-        mount_path = f"/{spec.tag.strip('/')}"
-        parent.mount(mount_path, child, name=spec.tag.strip("/"))
+        child = _build_child_app(service, spec, skip_paths=skip_paths)
+        tag_str = str(spec.tag).strip("/")
+        mount_path = f"/{tag_str}"
+        parent.mount(mount_path, child, name=tag_str)
 
-    @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)
 
-        if is_local_dev:
-            # Root card
-            cards.append(
-                CardSpec(
-                    tag="",
-                    docs=DocTargets(swagger="/docs", redoc="/redoc", openapi_json="/openapi.json"),
-                )
+        # Root card - always show in all environments
+        cards.append(
+            CardSpec(
+                tag="",
+                docs=DocTargets(
+                    swagger="/docs", redoc="/redoc", openapi_json="/openapi.json"
+                ),
             )
+        )
 
         # Version cards
         for spec in versions:
-            tag = spec.tag.strip("/")
+            tag = str(spec.tag).strip("/")
             cards.append(
                 CardSpec(
                     tag=tag,
@@ -265,11 +393,15 @@ def setup_service_api(
                 cards.append(
                     CardSpec(
                         tag=scope.strip("/"),
-                        docs=DocTargets(swagger=swagger, redoc=redoc, openapi_json=openapi_json),
+                        docs=DocTargets(
+                            swagger=swagger, redoc=redoc, openapi_json=openapi_json
+                        ),
                     )
                 )
 
-        html = render_index_html(service_name=service.name, release=service.release, cards=cards)
+        html = render_index_html(
+            service_name=service.name, release=service.release, cards=cards
+        )
         return HTMLResponse(html)
 
     return parent

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[misc,assignment]
+
+
+_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
+    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")
+        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/api/fastapi/versioned.py

@@ -0,0 +1,101 @@
+"""
+Utilities for capturing routers from add_* functions for versioned routing.
+
+This module provides helpers to use integration functions (add_banking, add_payments, etc.)
+under versioned routing without creating separate documentation cards.
+
+See: svc-infra/docs/versioned-integrations.md
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+from unittest.mock import patch
+
+from fastapi import APIRouter, FastAPI
+
+__all__ = ["extract_router"]
+
+T = TypeVar("T")
+
+
+def extract_router(
+    add_function: Callable[..., T],
+    *,
+    prefix: str,
+    **kwargs: Any,
+) -> tuple[APIRouter, T]:
+    """
+    Capture the router from an add_* function for versioned mounting.
+
+    This allows you to use integration functions like add_banking(), add_payments(),
+    etc. under versioned routing (e.g., /v0/banking) without creating separate
+    documentation cards.
+
+    Args:
+        add_function: The add_* function to capture from (e.g., add_banking)
+        prefix: URL prefix for the routes (e.g., "/banking")
+        **kwargs: Arguments to pass to the add_function
+
+    Returns:
+        Tuple of (router, return_value) where:
+        - router: The captured APIRouter with all routes
+        - return_value: The original return value from add_function (e.g., provider instance)
+
+    Example:
+        ```python
+        # In routers/v0/banking.py
+        from svc_infra.api.fastapi.versioned import extract_router
+        from fin_infra.banking import add_banking
+
+        router, banking_provider = extract_router(
+            add_banking,
+            prefix="/banking",
+            provider="plaid",
+            cache_ttl=60,
+        )
+
+        # svc-infra auto-discovers 'router' and mounts at /v0/banking
+        ```
+
+    Pattern:
+        1. Creates a mock FastAPI app
+        2. Intercepts include_router to capture the router
+        3. Patches add_prefixed_docs to prevent separate card creation
+        4. Calls the add_function which creates all routes
+        5. Returns the captured router for auto-discovery
+
+    See Also:
+        - docs/versioned-integrations.md: Full pattern documentation
+        - api/fastapi/dual/public.py: Similar pattern for dual routers
+    """
+    # Create mock app to capture router
+    mock_app = FastAPI()
+    captured_router: APIRouter | None = None
+
+    def _capture_router(router: APIRouter, **_kwargs: Any) -> None:
+        """Intercept include_router to capture instead of mount."""
+        nonlocal captured_router
+        captured_router = router
+
+    setattr(mock_app, "include_router", _capture_router)
+
+    # Patch add_prefixed_docs to prevent separate card (no-op if function doesn't call it)
+    def _noop_docs(*args: Any, **kwargs: Any) -> None:
+        pass
+
+    # Call add_function with patches active
+    with patch("svc_infra.api.fastapi.docs.scoped.add_prefixed_docs", _noop_docs):
+        result = add_function(
+            mock_app,
+            prefix=prefix,
+            **kwargs,
+        )
+
+    if captured_router is None:
+        raise RuntimeError(
+            f"Failed to capture router from {add_function.__name__}. "
+            f"The function may not call app.include_router()."
+        )
+
+    return captured_router, result

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/app/__init__.py

@@ -1,4 +1,4 @@
-from .env import pick
+from .env import MissingSecretError, pick, require_secret
 from .logging import setup_logging
 from .logging.formats import LoggingConfig, LogLevelOptions
 
@@ -7,4 +7,6 @@ __all__ = [
     "LoggingConfig",
     "LogLevelOptions",
     "pick",
+    "require_secret",
+    "MissingSecretError",
 ]