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

svc_infra/app/env.py

@@ -129,7 +129,9 @@ def pick(*, prod, nonprod=None, dev=None, test=None, local=None):
         return local
     if nonprod is not None:
         return nonprod
-    raise ValueError("pick(): No value found for environment and 'nonprod' was not provided.")
+    raise ValueError(
+        "pick(): No value found for environment and 'nonprod' was not provided."
+    )
 
 
 def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
@@ -166,3 +168,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

@@ -3,10 +3,13 @@ from __future__ import annotations
 import logging
 import os
 from logging.config import dictConfig
-from typing import Sequence
+from typing import TYPE_CHECKING, Sequence, 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 +30,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/formats.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 import os
 from enum import StrEnum
-from typing import Sequence
+from typing import Sequence, cast
 
 from pydantic import BaseModel
 
@@ -35,7 +35,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 +50,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 +107,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/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((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,241 @@
+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)