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

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

svc_infra/billing/async_service.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+
+class AsyncBillingService:
+    def __init__(self, session: AsyncSession, tenant_id: str):
+        self.session = session
+        self.tenant_id = tenant_id
+
+    async def record_usage(
+        self,
+        *,
+        metric: str,
+        amount: int,
+        at: datetime,
+        idempotency_key: str,
+        metadata: dict | None,
+    ) -> str:
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        await self.session.flush()
+        return evt.id
+
+    async def aggregate_daily(self, *, metric: str, day_start: datetime) -> int:
+        day_start = day_start.replace(
+            hour=0, minute=0, second=0, microsecond=0, tzinfo=timezone.utc
+        )
+        next_day = day_start + timedelta(days=1)
+        total = 0
+        rows: Sequence[UsageEvent] = (
+            (
+                await self.session.execute(
+                    select(UsageEvent).where(
+                        UsageEvent.tenant_id == self.tenant_id,
+                        UsageEvent.metric == metric,
+                        UsageEvent.at_ts >= day_start,
+                        UsageEvent.at_ts < next_day,
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in rows:
+            total += int(r.amount)
+
+        agg = (
+            await self.session.execute(
+                select(UsageAggregate).where(
+                    UsageAggregate.tenant_id == self.tenant_id,
+                    UsageAggregate.metric == metric,
+                    UsageAggregate.period_start == day_start,
+                    UsageAggregate.granularity == "day",
+                )
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+        return total
+
+    async def list_daily_aggregates(
+        self, *, metric: str, date_from: Optional[datetime], date_to: Optional[datetime]
+    ) -> list[UsageAggregate]:
+        q = select(UsageAggregate).where(
+            UsageAggregate.tenant_id == self.tenant_id,
+            UsageAggregate.metric == metric,
+            UsageAggregate.granularity == "day",
+        )
+        if date_from is not None:
+            q = q.where(UsageAggregate.period_start >= date_from)
+        if date_to is not None:
+            q = q.where(UsageAggregate.period_start < date_to)
+        rows: list[UsageAggregate] = (await self.session.execute(q)).scalars().all()
+        return rows
+
+    async def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        total = 0
+        aggs: Sequence[UsageAggregate] = (
+            (
+                await self.session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == self.tenant_id,
+                        UsageAggregate.period_start >= period_start,
+                        UsageAggregate.period_start < period_end,
+                        UsageAggregate.granularity == "day",
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in aggs:
+            total += int(r.total)
+
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        await self.session.flush()
+
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        return inv.id

svc_infra/billing/jobs.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import inspect
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from svc_infra.jobs.queue import Job, JobQueue
+from svc_infra.jobs.scheduler import InMemoryScheduler
+from svc_infra.webhooks.service import WebhookService
+
+from .async_service import AsyncBillingService
+
+
+async def job_aggregate_daily(
+    session: AsyncSession, *, tenant_id: str, metric: str, day_start: datetime
+) -> None:
+    """
+    Aggregate usage for a tenant/metric for the given day_start (UTC).
+
+    Intended to be called from a scheduler/worker with an AsyncSession created by the host app.
+    """
+    svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+    if day_start.tzinfo is None:
+        day_start = day_start.replace(tzinfo=timezone.utc)
+    await svc.aggregate_daily(metric=metric, day_start=day_start)
+
+
+async def job_generate_monthly_invoice(
+    session: AsyncSession,
+    *,
+    tenant_id: str,
+    period_start: datetime,
+    period_end: datetime,
+    currency: str,
+) -> str:
+    """
+    Generate a monthly invoice for a tenant between [period_start, period_end).
+    Returns the internal invoice id.
+    """
+    svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+    if period_start.tzinfo is None:
+        period_start = period_start.replace(tzinfo=timezone.utc)
+    if period_end.tzinfo is None:
+        period_end = period_end.replace(tzinfo=timezone.utc)
+    return await svc.generate_monthly_invoice(
+        period_start=period_start, period_end=period_end, currency=currency
+    )
+
+
+# -------- Job helpers and handlers (scheduler/worker wiring) ---------
+
+BILLING_AGGREGATE_JOB = "billing.aggregate_daily"
+BILLING_INVOICE_JOB = "billing.generate_monthly_invoice"
+
+
+def enqueue_aggregate_daily(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    metric: str,
+    day_start: datetime,
+    delay_seconds: int = 0,
+) -> None:
+    payload = {
+        "tenant_id": tenant_id,
+        "metric": metric,
+        "day_start": day_start.astimezone(timezone.utc).isoformat(),
+    }
+    queue.enqueue(BILLING_AGGREGATE_JOB, payload, delay_seconds=delay_seconds)
+
+
+def enqueue_generate_monthly_invoice(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    period_start: datetime,
+    period_end: datetime,
+    currency: str,
+    delay_seconds: int = 0,
+) -> None:
+    payload = {
+        "tenant_id": tenant_id,
+        "period_start": period_start.astimezone(timezone.utc).isoformat(),
+        "period_end": period_end.astimezone(timezone.utc).isoformat(),
+        "currency": currency,
+    }
+    queue.enqueue(BILLING_INVOICE_JOB, payload, delay_seconds=delay_seconds)
+
+
+def make_daily_aggregate_tick(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    metric: str,
+    when: Optional[datetime] = None,
+):
+    """Return an async function that enqueues a daily aggregate job.
+
+    This is a simple helper for local/dev schedulers; it schedules an aggregate
+    for the UTC day of ``when`` (or now). Call repeatedly via a scheduler.
+    """
+
+    async def _tick():
+        ts = (when or datetime.now(timezone.utc)).astimezone(timezone.utc)
+        day_start = ts.replace(hour=0, minute=0, second=0, microsecond=0)
+        enqueue_aggregate_daily(queue, tenant_id=tenant_id, metric=metric, day_start=day_start)
+
+    return _tick
+
+
+def make_billing_job_handler(
+    *,
+    session_factory: "async_sessionmaker[AsyncSession]",
+    webhooks: WebhookService,
+) -> Callable[[Job], Awaitable[None]]:
+    """Create a worker handler that processes billing jobs and emits webhooks.
+
+    Supported jobs and their expected payloads:
+    - billing.aggregate_daily {tenant_id, metric, day_start: ISO8601}
+      → emits topic 'billing.usage_aggregated'
+    - billing.generate_monthly_invoice {tenant_id, period_start: ISO8601, period_end: ISO8601, currency}
+      → emits topic 'billing.invoice.created'
+    """
+
+    async def _maybe_commit(session: Any) -> None:
+        """Commit if the session exposes a commit method (await if coroutine).
+
+        This makes the handler resilient in tests/dev where a dummy session is used.
+        """
+        commit = getattr(session, "commit", None)
+        if callable(commit):
+            result = commit()
+            if inspect.isawaitable(result):
+                await result
+
+    async def _handler(job: Job) -> None:
+        name = job.name
+        data: Dict[str, Any] = job.payload or {}
+        if name == BILLING_AGGREGATE_JOB:
+            tenant_id = str(data.get("tenant_id"))
+            metric = str(data.get("metric"))
+            day_raw = data.get("day_start")
+            if not tenant_id or not metric or not day_raw:
+                return
+            day_start = datetime.fromisoformat(str(day_raw))
+            async with session_factory() as session:
+                svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+                total = await svc.aggregate_daily(metric=metric, day_start=day_start)
+                await _maybe_commit(session)
+            webhooks.publish(
+                "billing.usage_aggregated",
+                {
+                    "tenant_id": tenant_id,
+                    "metric": metric,
+                    "day_start": day_start.astimezone(timezone.utc).isoformat(),
+                    "total": int(total),
+                },
+            )
+            return
+        if name == BILLING_INVOICE_JOB:
+            tenant_id = str(data.get("tenant_id"))
+            period_start_raw = data.get("period_start")
+            period_end_raw = data.get("period_end")
+            currency = str(data.get("currency"))
+            if not tenant_id or not period_start_raw or not period_end_raw or not currency:
+                return
+            period_start = datetime.fromisoformat(str(period_start_raw))
+            period_end = datetime.fromisoformat(str(period_end_raw))
+            async with session_factory() as session:
+                svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+                invoice_id = await svc.generate_monthly_invoice(
+                    period_start=period_start, period_end=period_end, currency=currency
+                )
+                await _maybe_commit(session)
+            webhooks.publish(
+                "billing.invoice.created",
+                {
+                    "tenant_id": tenant_id,
+                    "invoice_id": invoice_id,
+                    "period_start": period_start.astimezone(timezone.utc).isoformat(),
+                    "period_end": period_end.astimezone(timezone.utc).isoformat(),
+                    "currency": currency,
+                },
+            )
+            return
+        # Ignore unrelated jobs
+
+    return _handler
+
+
+def add_billing_jobs(
+    *,
+    scheduler: InMemoryScheduler,
+    queue: JobQueue,
+    jobs: list[dict],
+) -> None:
+    """Register simple interval-based billing job enqueuers.
+
+    jobs: list of dicts with shape {"name": "aggregate", "tenant_id": ..., "metric": ..., "interval_seconds": 86400}
+          or {"name": "invoice", "tenant_id": ..., "period_start": ISO, "period_end": ISO, "currency": ..., "interval_seconds": 2592000}
+    """
+
+    for j in jobs:
+        name = j.get("name")
+        interval = int(j.get("interval_seconds", 86400))
+        if name == "aggregate":
+            tenant_id = j["tenant_id"]
+            metric = j["metric"]
+
+            async def _tick_fn(tid=tenant_id, m=metric):
+                # Enqueue for the current UTC day
+                now = datetime.now(timezone.utc)
+                day_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+                enqueue_aggregate_daily(queue, tenant_id=tid, metric=m, day_start=day_start)
+
+            scheduler.add_task(f"billing.aggregate.{tenant_id}.{metric}", interval, _tick_fn)
+        elif name == "invoice":
+            tenant_id = j["tenant_id"]
+            currency = j["currency"]
+            pstart = datetime.fromisoformat(j["period_start"]).astimezone(timezone.utc)
+            pend = datetime.fromisoformat(j["period_end"]).astimezone(timezone.utc)
+
+            async def _tick_inv(tid=tenant_id, cs=currency, ps=pstart, pe=pend):
+                enqueue_generate_monthly_invoice(
+                    queue, tenant_id=tid, period_start=ps, period_end=pe, currency=cs
+                )
+
+            scheduler.add_task(f"billing.invoice.{tenant_id}", interval, _tick_inv)