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

svc_infra/api/fastapi/tenancy/context.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Annotated, Any
+
+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: Callable[..., Any] | None = None
+
+
+def set_tenant_resolver(
+    fn: Callable[..., Any] | None,
+) -> 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: str | None = None,
+    identity: Any = Depends(OptionalIdentity) if OptionalIdentity else None,  # type: ignore[arg-type]
+) -> str | None:
+    """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: str | None = 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[str | None, 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,102 @@
+"""
+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 collections.abc import Callable
+from typing import Any, 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[method-assign]
+
+    # 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",
 ]

svc_infra/app/env.py

@@ -5,7 +5,7 @@ import warnings
 from enum import StrEnum
 from functools import cache
 from pathlib import Path
-from typing import List, NamedTuple, Optional
+from typing import NamedTuple
 
 from dotenv import load_dotenv
 
@@ -39,7 +39,7 @@ SYNONYMS: dict[str, Environment] = {
     "production": PROD_ENV,
 }
 
-ALL_ENVIRONMENTS = {e for e in Environment}
+ALL_ENVIRONMENTS = set(Environment)
 
 
 def _normalize(raw: str | None) -> Environment | None:
@@ -132,7 +132,7 @@ def pick(*, prod, nonprod=None, dev=None, test=None, local=None):
     raise ValueError("pick(): No value found for environment and 'nonprod' was not provided.")
 
 
-def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
+def find_env_file(start: Path | None = None) -> Path | None:
     env_file = os.getenv("APP_ENV_FILE") or os.getenv("SVC_INFRA_ENV_FILE")
     if env_file:
         p = Path(env_file).expanduser()
@@ -146,7 +146,7 @@ def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
     return None
 
 
-def load_env_if_present(path: Optional[Path], *, override: bool = False) -> List[str]:
+def load_env_if_present(path: Path | None, *, override: bool = False) -> list[str]:
     if not path:
         return []
     before = dict(os.environ)
@@ -166,3 +166,69 @@ def prepare_env() -> Path:
     env_file = find_env_file(start=root)
     load_env_if_present(env_file, override=False)
     return root
+
+
+class MissingSecretError(RuntimeError):
+    """Raised when a required secret is not configured in production/staging."""
+
+    pass
+
+
+def require_secret(
+    value: str | None,
+    name: str,
+    *,
+    dev_default: str | None = None,
+    environments: tuple[str, ...] = ("prod", "production", "staging", "test"),
+) -> str:
+    """Require a secret to be set in production environments.
+
+    In development/local environments, falls back to dev_default if provided.
+    In production environments, raises MissingSecretError if not set.
+
+    Args:
+        value: The secret value (may be None or empty)
+        name: Name of the secret for error messages (e.g., "SESSION_SECRET")
+        dev_default: Default value to use in development (NEVER in production)
+        environments: Environments where the secret is required
+
+    Returns:
+        The secret value
+
+    Raises:
+        MissingSecretError: If secret is not set in production environments
+
+    Example:
+        >>> secret = require_secret(
+        ...     os.getenv("SESSION_SECRET"),
+        ...     "SESSION_SECRET",
+        ...     dev_default="dev-only-secret",
+        ... )
+    """
+    if value:
+        return value
+
+    current_env = get_current_environment()
+
+    # Check if we're in a production-like environment
+    raw_env = os.getenv("APP_ENV") or os.getenv("RAILWAY_ENVIRONMENT_NAME") or ""
+    is_production_like = (
+        current_env == PROD_ENV
+        or current_env == TEST_ENV  # staging/preview
+        or raw_env.lower() in environments
+    )
+
+    if is_production_like:
+        raise MissingSecretError(
+            f"SECURITY ERROR: {name} must be set in production/staging environments. "
+            f"Current environment: {current_env} (raw: {raw_env!r})"
+        )
+
+    # In development, use the dev default if provided
+    if dev_default is not None:
+        return dev_default
+
+    raise MissingSecretError(
+        f"{name} is not set and no dev_default was provided. "
+        "Either set the environment variable or provide a dev_default."
+    )

svc_infra/app/logging/add.py

@@ -2,11 +2,15 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Sequence
 from logging.config import dictConfig
-from typing import Sequence
+from typing import TYPE_CHECKING, cast
 
 from svc_infra.app.env import CURRENT_ENVIRONMENT
 
+if TYPE_CHECKING:
+    from .formats import LogFormatOptions, LogLevelOptions
+
 from .filter import filter_logs_for_paths
 from .formats import (
     JsonFormatter,
@@ -27,7 +31,11 @@ def setup_logging(
 ) -> None:
     """Configure logging + optional access-log path filtering."""
     if fmt is not None or level is not None:
-        LoggingConfig(fmt=fmt, level=level)  # pydantic validation
+        # Cast to expected Literal types after validation
+        LoggingConfig(
+            fmt=cast("LogFormatOptions | None", fmt),
+            level=cast("LogLevelOptions | None", level),
+        )  # pydantic validation
 
     if level is None:
         level = _read_level()

svc_infra/app/logging/filter.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Iterable
+from collections.abc import Iterable
 
 
 def _is_metrics_like(record: logging.LogRecord, paths: Iterable[str]) -> bool:

svc_infra/app/logging/formats.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Sequence
 from enum import StrEnum
-from typing import Sequence
+from typing import cast
 
 from pydantic import BaseModel
 
@@ -35,7 +36,7 @@ class LoggingConfig(BaseModel):
 class JsonFormatter(logging.Formatter):
     """Structured JSON formatter for prod and CI logs."""
 
-    def format(self, record: logging.LogRecord) -> str:  # type: ignore[override]
+    def format(self, record: logging.LogRecord) -> str:
         import json
         import os as _os
         from traceback import format_exception
@@ -50,15 +51,19 @@ class JsonFormatter(logging.Formatter):
 
         # Add these two lines:
         if getattr(record, "trace_id", None):
-            payload["trace_id"] = record.trace_id
+            payload["trace_id"] = record.trace_id  # type: ignore[attr-defined]
         if getattr(record, "span_id", None):
-            payload["span_id"] = record.span_id
+            payload["span_id"] = record.span_id  # type: ignore[attr-defined]
 
         # Optional correlation id
         req_id = getattr(record, "request_id", None)
         if req_id is not None:
             payload["request_id"] = req_id
 
+        tenant_id = getattr(record, "tenant_id", None)
+        if tenant_id is not None:
+            payload["tenant_id"] = tenant_id
+
         # Optional HTTP context
         http_ctx = {
             k: v
@@ -103,7 +108,10 @@ def _read_level() -> str:
         return explicit.upper()
     from svc_infra.app.env import pick
 
-    return pick(prod="INFO", nonprod="DEBUG", dev="DEBUG", test="DEBUG", local="DEBUG").upper()
+    return cast(
+        "str",
+        pick(prod="INFO", nonprod="DEBUG", dev="DEBUG", test="DEBUG", local="DEBUG"),
+    ).upper()
 
 
 def _read_format() -> str:

svc_infra/app/root.py

@@ -2,8 +2,8 @@ from __future__ import annotations
 
 import os
 import subprocess
+from collections.abc import Iterable
 from pathlib import Path
-from typing import Iterable, Optional
 
 DEFAULT_SENTRIES: tuple[str, ...] = (
     ".git",
@@ -36,7 +36,7 @@ def _is_root_marker(dir_: Path, sentries: Iterable[str]) -> bool:
     return any((dir_ / name).exists() for name in sentries)
 
 
-def _git_toplevel(start: Path) -> Optional[Path]:
+def _git_toplevel(start: Path) -> Path | None:
     try:
         out = subprocess.check_output(
             ["git", "rev-parse", "--show-toplevel"],
@@ -50,7 +50,7 @@ def _git_toplevel(start: Path) -> Optional[Path]:
 
 
 def resolve_project_root(
-    start: Optional[Path] = None,
+    start: Path | None = None,
     *,
     env_var: str = ENV_VAR,
     extra_sentries: Iterable[str] = (),

svc_infra/billing/__init__.py

@@ -0,0 +1,40 @@
+"""Billing module for usage tracking, metering, and invoicing.
+
+Primary API:
+    AsyncBillingService - Async billing service
+
+Models:
+    UsageEvent, UsageAggregate, Invoice, InvoiceLine, Plan, Subscription, etc.
+
+Example:
+    from svc_infra.billing import AsyncBillingService
+
+    service = AsyncBillingService(async_session, tenant_id)
+    await service.record_usage(metric="api_calls", amount=1, ...)
+"""
+
+from .async_service import AsyncBillingService
+from .models import (
+    Invoice,
+    InvoiceLine,
+    Plan,
+    PlanEntitlement,
+    Price,
+    Subscription,
+    UsageAggregate,
+    UsageEvent,
+)
+
+__all__ = [
+    # Primary API
+    "AsyncBillingService",
+    # Models
+    "UsageEvent",
+    "UsageAggregate",
+    "Plan",
+    "PlanEntitlement",
+    "Subscription",
+    "Price",
+    "Invoice",
+    "InvoiceLine",
+]