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

svc_infra/api/fastapi/pagination.py

@@ -44,8 +44,8 @@ def _encode_cursor(payload: dict) -> str:
     return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
 
 
-# public; handy if you need to decode an incoming cursor
 def decode_cursor(token: Optional[str]) -> dict:
+    """Public: decode an incoming cursor token for debugging/ops."""
     if not token:
         return {}
     s = token + "=" * (-len(token) % 4)
@@ -55,15 +55,14 @@ def decode_cursor(token: Optional[str]) -> dict:
 
 # ---------- Context ----------
 class PaginationContext(Generic[T]):
-    # mode config
     envelope: bool
     allow_cursor: bool
     allow_page: bool
 
-    # values
     cursor_params: CursorParams | None
     page_params: PageParams | None
     filters: FilterParams | None
+    limit_override: int | None
 
     def __init__(
         self,
@@ -90,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
@@ -117,7 +118,6 @@ class PaginationContext(Generic[T]):
             return Paginated[T](items=items, next_cursor=next_cursor, total=total)
         return items
 
-    # convenience: derive a naive next_cursor from the last item
     def next_cursor_from_last(
         self, items: Sequence[T], *, key: Callable[[T], str | int]
     ) -> Optional[str]:
@@ -135,20 +135,20 @@ _pagination_ctx: contextvars.ContextVar[PaginationContext] = contextvars.Context
 def use_pagination() -> PaginationContext:
     ctx = _pagination_ctx.get()
     if ctx is None:
-        # Safe defaults; this happens if a route forgot to install the injector
+        # Safe defaults; if a route forgot to install the injector
         ctx = PaginationContext(
             envelope=False,
             allow_cursor=True,
-            allow_page=True,
+            allow_page=False,
             cursor_params=CursorParams(),
-            page_params=PageParams(),
-            filters=FilterParams(),
+            page_params=None,
+            filters=None,
         )
     return ctx
 
 
+# ---------- Utilities ----------
 def text_filter(items: Iterable[T], q: Optional[str], *getters: Callable[[T], str]) -> list[T]:
-    """Simple contains filter across one or more string fields."""
     if not q:
         return list(items)
     ql = q.lower()
@@ -170,13 +170,10 @@ def sort_by(
     key: Callable[[T], Any],
     desc: bool = False,
 ) -> list[T]:
-    """Stable sort with a key func."""
     return sorted(list(items), key=key, reverse=desc)
 
 
 def cursor_window(items, *, cursor, limit, key, descending: bool, offset: int = 0):
-    # items must already be filtered/sorted
-
     # compute start_index
     if cursor:
         payload = decode_cursor(cursor)
@@ -195,14 +192,14 @@ def cursor_window(items, *, cursor, limit, key, descending: bool, offset: int =
     window = slice_[:limit]
 
     next_cur = None
-    if has_more:
+    if has_more and window:
         last_key = key(window[-1])
         next_cur = _encode_cursor({"after": last_key})
 
     return window, next_cur
 
 
-# ---------- Dependency factory (used by the router decorator) ----------
+# ---------- Dependency factories ----------
 def make_pagination_injector(
     *,
     envelope: bool,
@@ -210,7 +207,97 @@ def make_pagination_injector(
     allow_page: bool,
     default_limit: int = 50,
     max_limit: int = 200,
+    include_filters: bool = False,
 ):
+    """
+    Returns a dependency with a signature that only includes the relevant query params.
+    This keeps the generated OpenAPI in sync with actual behavior.
+    """
+
+    # Cursor-only (common case)
+    if allow_cursor and not allow_page and not include_filters:
+
+        async def _inject(
+            request: Request,
+            cursor: str | None = Query(None),
+            limit: int = Query(default_limit, ge=1, le=max_limit),
+        ):
+            cur = CursorParams(cursor=cursor, limit=limit)
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=True,
+                    allow_page=False,
+                    cursor_params=cur,
+                    page_params=None,
+                    filters=None,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Cursor + filters
+    if allow_cursor and not allow_page and include_filters:
+
+        async def _inject(
+            request: Request,
+            cursor: str | None = Query(None),
+            limit: int = Query(default_limit, ge=1, le=max_limit),
+            q: str | None = Query(None),
+            sort: str | None = Query(None),
+            created_after: str | None = Query(None),
+            created_before: str | None = Query(None),
+            updated_after: str | None = Query(None),
+            updated_before: str | None = Query(None),
+        ):
+            cur = CursorParams(cursor=cursor, limit=limit)
+            flt = FilterParams(
+                q=q,
+                sort=sort,
+                created_after=created_after,
+                created_before=created_before,
+                updated_after=updated_after,
+                updated_before=updated_before,
+            )
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=True,
+                    allow_page=False,
+                    cursor_params=cur,
+                    page_params=None,
+                    filters=flt,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Page-only
+    if not allow_cursor and allow_page:
+
+        async def _inject(
+            request: Request,
+            page: int = Query(1, ge=1),
+            page_size: int = Query(default_limit, ge=1, le=max_limit),
+        ):
+            pag = PageParams(page=page, page_size=page_size)
+            _pagination_ctx.set(
+                PaginationContext(
+                    envelope=envelope,
+                    allow_cursor=False,
+                    allow_page=True,
+                    cursor_params=None,
+                    page_params=pag,
+                    filters=None,
+                )
+            )
+            return None
+
+        return _inject
+
+    # Both cursor + page (rare; exposes all)
     async def _inject(
         request: Request,
         cursor: str | None = Query(None),
@@ -226,23 +313,16 @@ def make_pagination_injector(
     ):
         cur = CursorParams(cursor=cursor, limit=limit) if allow_cursor else None
         pag = PageParams(page=page, page_size=page_size) if allow_page else None
-        flt = FilterParams(
-            q=q,
-            sort=sort,
-            created_after=created_after,
-            created_before=created_before,
-            updated_after=updated_after,
-            updated_before=updated_before,
-        )
-
-        # detect if 'limit' was explicitly provided
-        limit_override = (
-            limit
-            if (
-                "limit" in request.query_params
-                and "page_size" not in request.query_params
-                and cursor is None
+        flt = (
+            FilterParams(
+                q=q,
+                sort=sort,
+                created_after=created_after,
+                created_before=created_before,
+                updated_after=updated_after,
+                updated_before=updated_before,
             )
+            if include_filters
             else None
         )
 
@@ -254,9 +334,30 @@ def make_pagination_injector(
                 cursor_params=cur,
                 page_params=pag,
                 filters=flt,
-                limit_override=limit_override,
             )
         )
         return None
 
     return _inject
+
+
+# ----- Convenience helpers for routers -----
+def cursor_pager(
+    default_limit: int = 50,
+    max_limit: int = 200,
+    *,
+    envelope: bool = True,
+    include_filters: bool = False,
+):
+    """
+    The one-liner most routes should use.
+    Produces OpenAPI with only: `cursor` and `limit` (plus filters if requested).
+    """
+    return make_pagination_injector(
+        envelope=envelope,
+        allow_cursor=True,
+        allow_page=False,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        include_filters=include_filters,
+    )

svc_infra/api/fastapi/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
@@ -61,7 +66,8 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
     elif isinstance(public_cors_origins, str):
         origins = [o.strip() for o in public_cors_origins.split(",") if o and o.strip()]
     else:
-        fallback = os.getenv("CORS_ALLOW_ORIGINS", "http://localhost:3000")
+        # Strict by default: no CORS unless explicitly configured via env or parameter.
+        fallback = os.getenv("CORS_ALLOW_ORIGINS", "")
         origins = [o.strip() for o in fallback.split(",") if o and o.strip()]
 
     if not origins:
@@ -78,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]:
@@ -147,8 +158,7 @@ def _build_parent_app(
     root_server_url: str | None = None,
     root_include_api_key: bool = False,
 ) -> 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,
@@ -156,9 +166,9 @@ def _build_parent_app(
         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),
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
     )
 
     _setup_cors(parent, public_cors_origins)
@@ -231,19 +241,18 @@ 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)
 
-        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:

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/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
+
+    mock_app.include_router = _capture_router  # type: ignore[assignment]
+
+    # 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/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",
+]