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

svc_infra/api/fastapi/pagination.py

@@ -3,17 +3,26 @@ from __future__ import annotations
 import base64
 import contextvars
 import json
-from typing import Any, Callable, Generic, Iterable, List, Optional, Sequence, TypeVar
+import logging
+from collections.abc import Callable, Iterable, Sequence
+from typing import (
+    Any,
+    Generic,
+    TypeVar,
+    cast,
+)
 
 from fastapi import Query, Request
 from pydantic import BaseModel, Field
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 
 # ---------- Core query models ----------
 class CursorParams(BaseModel):
-    cursor: Optional[str] = None
+    cursor: str | None = None
     limit: int = 50
 
 
@@ -23,19 +32,19 @@ class PageParams(BaseModel):
 
 
 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
+    q: str | None = None
+    sort: str | None = None
+    created_after: str | None = None
+    created_before: str | None = None
+    updated_after: str | None = None
+    updated_before: str | None = 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)")
+    items: list[T]
+    next_cursor: str | None = Field(None, description="Opaque cursor for next page")
+    total: int | None = Field(None, description="Total items (optional)")
 
 
 # ---------- Cursor helpers ----------
@@ -44,13 +53,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: str | None) -> 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 ----------
@@ -84,23 +93,25 @@ class PaginationContext(Generic[T]):
         self.limit_override = limit_override
 
     @property
-    def cursor(self) -> Optional[str]:
+    def cursor(self) -> str | 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
         return 50
 
     @property
-    def page(self) -> Optional[int]:
+    def page(self) -> int | None:
         return self.page_params.page if (self.allow_page and self.page_params) else None
 
     @property
-    def page_size(self) -> Optional[int]:
+    def page_size(self) -> int | None:
         return self.page_params.page_size if (self.allow_page and self.page_params) else None
 
     @property
@@ -110,7 +121,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: str | None = None,
+        total: int | None = None,
     ):
         if self.envelope:
             return Paginated[T](items=items, next_cursor=next_cursor, total=total)
@@ -118,14 +133,14 @@ class PaginationContext(Generic[T]):
 
     def next_cursor_from_last(
         self, items: Sequence[T], *, key: Callable[[T], str | int]
-    ) -> Optional[str]:
+    ) -> str | None:
         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: contextvars.ContextVar[PaginationContext | None] = contextvars.ContextVar(
     "pagination_ctx", default=None
 )
 
@@ -146,7 +161,7 @@ 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: str | None, *getters: Callable[[T], str]) -> list[T]:
     if not q:
         return list(items)
     ql = q.lower()
@@ -157,8 +172,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
 
 
@@ -168,7 +183,7 @@ def sort_by(
     key: Callable[[T], Any],
     desc: bool = False,
 ) -> list[T]:
-    return sorted(list(items), key=key, reverse=desc)
+    return sorted(items, key=key, reverse=desc)
 
 
 def cursor_window(items, *, cursor, limit, key, descending: bool, offset: int = 0):
@@ -215,7 +230,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 +248,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 +285,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 +308,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 +351,7 @@ def make_pagination_injector(
         )
         return None
 
-    return _inject
+    return _inject_all
 
 
 # ----- Convenience helpers for routers -----

svc_infra/api/fastapi/routers/__init__.py

@@ -4,12 +4,18 @@ import importlib
 import logging
 import pkgutil
 from types import ModuleType
-from typing import Optional
+from typing import Any
 
 from fastapi import FastAPI
 from fastapi.routing import APIRoute
 
-from svc_infra.app.env import ALL_ENVIRONMENTS, CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV, Environment
+from svc_infra.app.env import (
+    ALL_ENVIRONMENTS,
+    CURRENT_ENVIRONMENT,
+    DEV_ENV,
+    LOCAL_ENV,
+    Environment,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -59,7 +65,7 @@ def _validate_base_package(base_package: str) -> ModuleType:
     return package_module
 
 
-def _normalize_environment(environment: Optional[Environment | str]) -> Environment:
+def _normalize_environment(environment: Environment | str | None) -> Environment:
     """Normalize the environment parameter."""
     return (
         CURRENT_ENVIRONMENT
@@ -69,7 +75,7 @@ def _normalize_environment(environment: Optional[Environment | str]) -> Environm
 
 
 def _should_force_include_in_schema(
-    environment: Environment, force_include_in_schema: Optional[bool]
+    environment: Environment, force_include_in_schema: bool | None
 ) -> bool:
     """Determine if routers should be forced to include in schema."""
     if force_include_in_schema is None:
@@ -99,7 +105,7 @@ def _is_router_excluded_by_environment(
         )
         return False
 
-    normalized_excluded_envs = set()
+    normalized_excluded_envs: set[Environment | str] = set()
     for e in router_excluded_envs:
         try:
             normalized_excluded_envs.add(Environment(e) if not isinstance(e, Environment) else e)
@@ -126,7 +132,7 @@ def _is_router_included_by_environment(
             f"ROUTER_ENVIRONMENTS in {module_name} must be a set/list/tuple, got {type(router_envs)}"
         )
         return True
-    normalized = set()
+    normalized: set[Environment | str] = set()
     for e in router_envs:
         try:
             normalized.add(Environment(e) if not isinstance(e, Environment) else e)
@@ -163,7 +169,7 @@ def _build_include_kwargs(module: ModuleType, prefix: str, force_include: bool)
     router_tag = getattr(module, "ROUTER_TAG", None)
     include_in_schema = getattr(module, "INCLUDE_ROUTER_IN_SCHEMA", True)
 
-    include_kwargs = {"prefix": prefix}
+    include_kwargs: dict[str, Any] = {"prefix": prefix}
     if router_prefix:
         include_kwargs["prefix"] = prefix.rstrip("/") + router_prefix
     if router_tag:
@@ -205,10 +211,10 @@ def _process_router_module(
 def register_all_routers(
     app: FastAPI,
     *,
-    base_package: Optional[str] = None,
+    base_package: str | None = None,
     prefix: str = "",
-    environment: Optional[Environment | str] = None,
-    force_include_in_schema: Optional[bool] = None,
+    environment: Environment | str | None = None,
+    force_include_in_schema: bool | None = None,
 ) -> None:
     """
     Recursively discover and register all FastAPI routers under a routers package.

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

@@ -3,20 +3,26 @@ from __future__ import annotations
 import logging
 import os
 from collections import defaultdict
-from typing import Iterable, Sequence
+from collections.abc import Iterable, Sequence
 
 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,35 +62,101 @@ 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:
-        # 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()]
+        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=["*"])
+    cors_kwargs = {"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
-
-    app.add_middleware(CORSMiddleware, **cors_kwargs)
-
+        # 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 []
 
-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]:
@@ -98,7 +171,9 @@ 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:
+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,
@@ -106,15 +181,16 @@ def _build_child_app(service: ServiceInfo, spec: APIVersionSpec) -> FastAPI:
         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('/')}"
+    tag_str = str(spec.tag).strip("/")
+    mount_path = f"/{tag_str}"
     server_url = (
         mount_path
         if not spec.public_base_url
@@ -131,11 +207,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
 
@@ -147,23 +229,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,
@@ -187,18 +271,43 @@ def _build_parent_app(
     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 using prefix matching
+        if any(path.startswith(skip) 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(
@@ -209,6 +318,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 = (
@@ -224,31 +335,33 @@ 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,

svc_infra/api/fastapi/tenancy/add.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import FastAPI
+
+from .context import set_tenant_resolver
+
+
+def add_tenancy(app: FastAPI, *, resolver: Callable[..., Any] | None = 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"]