svc-infra 0.1.628__py3-none-any.whl → 0.1.630__py3-none-any.whl

svc_infra/billing/jobs.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+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 _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 session.commit()
+            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 session.commit()
+            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)

svc_infra/billing/quotas.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from svc_infra.api.fastapi.db.sql.session import SqlSessionDep
+from svc_infra.api.fastapi.tenancy.context import TenantId
+
+from .models import PlanEntitlement, Subscription, UsageAggregate
+
+
+async def _current_subscription(session: AsyncSession, tenant_id: str) -> Optional[Subscription]:
+    now = datetime.now(tz=timezone.utc)
+    row = (
+        (
+            await session.execute(
+                select(Subscription)
+                .where(Subscription.tenant_id == tenant_id)
+                .order_by(Subscription.effective_at.desc())
+            )
+        )
+        .scalars()
+        .first()
+    )
+    if row is None:
+        return None
+    # basic check: if ended_at is set and in the past, treat as inactive
+    if row.ended_at is not None and row.ended_at <= now:
+        return None
+    return row
+
+
+def require_quota(metric: str, *, window: str = "day", soft: bool = True):
+    async def _dep(tenant_id: TenantId, session: SqlSessionDep) -> None:
+        sub = await _current_subscription(session, tenant_id)
+        if sub is None:
+            # no subscription → allow (unlimited) by default
+            return
+        ent = (
+            (
+                await session.execute(
+                    select(PlanEntitlement).where(
+                        PlanEntitlement.plan_id == sub.plan_id,
+                        PlanEntitlement.key == metric,
+                        PlanEntitlement.window == window,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        if ent is None:
+            # no entitlement → unlimited
+            return
+        # compute current window start
+        now = datetime.now(tz=timezone.utc)
+        if window == "day":
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+        elif window == "month":
+            period_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+            granularity = "month"  # we only aggregate per day, but future-proof
+        else:
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+
+        used_row = (
+            (
+                await session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == tenant_id,
+                        UsageAggregate.metric == metric,
+                        UsageAggregate.granularity == granularity,  # v1 daily baseline
+                        UsageAggregate.period_start == period_start,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        used = int(used_row.total) if used_row else 0
+        limit_ = int(ent.limit_per_window)
+        if used >= limit_:
+            if soft:
+                # allow but signal overage via header later (TODO: add header hook)
+                return
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=f"Quota exceeded for {metric} in {window} window",
+            )
+
+    return _dep
+
+
+QuotaDep = Annotated[None, Depends(require_quota)]
+
+__all__ = ["require_quota"]

svc_infra/billing/schemas.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, conint
+
+
+class UsageIn(BaseModel):
+    metric: str = Field(..., min_length=1, max_length=64)
+    amount: conint(ge=0) = Field(..., description="Non-negative amount for the metric")
+    at: Optional[datetime] = Field(
+        default=None, description="Event timestamp (UTC). Defaults to server time if omitted."
+    )
+    idempotency_key: str = Field(..., min_length=1, max_length=128)
+    metadata: dict = Field(default_factory=dict)
+
+
+class UsageAckOut(BaseModel):
+    id: str
+    accepted: bool = True
+
+
+class UsageAggregateRow(BaseModel):
+    period_start: datetime
+    granularity: str
+    metric: str
+    total: int
+
+
+class UsageAggregatesOut(BaseModel):
+    items: list[UsageAggregateRow] = Field(default_factory=list)
+    next_cursor: Optional[str] = None

svc_infra/cli/cmds/db/sql/alembic_cmds.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 from importlib import import_module
 from typing import List, Optional
@@ -124,7 +125,11 @@ def cmd_current(
 ):
     """Display the current revision for each database."""
     apply_database_url(database_url)
-    core_current(verbose=verbose)
+    result = core_current(verbose=verbose)
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        typer.echo(str(result))
 
 
 def cmd_history(
@@ -189,7 +194,7 @@ def cmd_setup_and_migrate(
     Async vs. sync is inferred from SQL_URL.
     """
     final_pkgs = _find_pkgs(with_payments, discover_packages)
-    core_setup_and_migrate(
+    result = core_setup_and_migrate(
         overwrite_scaffold=overwrite_scaffold,
         create_db_if_missing=create_db_if_missing,
         create_followup_revision=create_followup_revision,
@@ -198,6 +203,12 @@ def cmd_setup_and_migrate(
         discover_packages=final_pkgs or None,
         database_url=database_url,
     )
+    # Echo a concise JSON result so tests and users can introspect outcome
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        # Fallback to plain string if not JSON-serializable for any reason
+        typer.echo(str(result))
 
 
 def register(app: typer.Typer) -> None:
@@ -205,7 +216,11 @@ def register(app: typer.Typer) -> None:
     app.command("init")(cmd_init)
     app.command("revision")(cmd_revision)
     app.command("upgrade")(cmd_upgrade)
-    app.command("downgrade")(cmd_downgrade)
+    # Allow unknown options so users can pass "-1" like Alembic without Click treating it as an option
+    app.command(
+        "downgrade",
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )(cmd_downgrade)
     app.command("current")(cmd_current)
     app.command("history")(cmd_history)
     app.command("stamp")(cmd_stamp)

svc_infra/docs/adr/0008-billing-primitives.md

@@ -14,6 +14,40 @@ We need shared billing primitives to support both usage-based and subscription f
 
 Non-goals for v1: taxes/VAT, complex proration rules, refunds/credits automation, dunning flows, provider-specific webhooks/end-to-end reconciliation.
 
+## Analysis: APF Payments vs Billing Primitives
+
+What APF Payments already covers (provider-facing):
+- Subscriptions lifecycle via provider adapters and HTTP router
+  - Endpoints: create/update/cancel/get/list under `/payments/subscriptions` (see `api/fastapi/apf_payments/router.py`).
+  - Local mirror rows (e.g., `PaySubscription`) are persisted for reference, but state is owned by the provider (Stripe/Aiydan).
+- Plans as Product + Price on the provider side
+  - APF Payments exposes products (`/payments/products`) and prices (`/payments/prices`). In Stripe semantics, a “plan” is represented by a product+price pair.
+  - There is no first-class internal Plan entity in APF Payments; plan semantics are encapsulated as provider product/price metadata.
+- Invoices, invoice line items, and previews
+  - Create/finalize/void/pay invoices; add/list invoice lines; preview invoices — all via provider adapters.
+- Usage records (metered billing) at the provider
+  - Create/list/get usage records mapped to provider subscription items or prices (`/payments/usage_records`).
+- Cross-cutting:
+  - Tenant resolution, pagination, idempotency, and Problem+JSON errors are integrated.
+
+What APF Payments does not cover (gaps filled by Billing Primitives):
+- An internal, provider-agnostic Plan and Entitlement registry (keys, windows, limits).
+- Quota enforcement at runtime (soft/hard limits) against internal entitlements.
+- Internal usage ingestion and aggregation store independent of provider APIs
+  - `UsageEvent` and `UsageAggregate` tables, with idempotent ingestion and windowed rollups.
+- Internal invoice modeling and generation from aggregates (not just provider invoices)
+  - `Invoice` and `InvoiceLine` entities produced from internal totals (jobs-based lifecycle).
+- A dedicated `/_billing` router for usage ingestion and aggregate reads (tenant-scoped, RBAC-protected).
+
+Where they intersect and can complement each other:
+- You can continue to use APF Payments for provider-side subscriptions/invoices and also use Billing Primitives to meter internal features and enforce quotas.
+- Optional bridging: a provider sync hook can map internally generated invoices/lines to provider invoices or payment intents when you want unified billing.
+- Usage: internal `UsageEvent` can be mirrored to provider usage-records if desired, but internal aggregation enables analytics and quota decisions without provider round-trips.
+
+Answering “Are plans and subscriptions covered in APF Payments?”
+- Subscriptions: Yes — fully supported via `/payments/subscriptions` endpoints with adapters (Stripe/Aiydan). APF also persists a local `PaySubscription` record for reference.
+- Plans: APF Payments does not expose a standalone internal Plan model. Instead, providers represent plans as Product + Price. Billing Primitives introduces an internal `Plan` and `PlanEntitlement` registry to support provider-agnostic limits and quotas.
+
 ## Decisions
 
 1) Internal-first data model with optional provider adapters

svc_infra/docs/adr/0010-timeouts-and-resource-limits.md

@@ -0,0 +1,54 @@
+# ADR 0010: Timeouts & Resource Limits (A2)
+
+## Context
+Services need consistent, configurable timeouts to protect against slowloris/body drip attacks, expensive handlers, slow downstreams, and long-running DB statements. Today we lack unified settings and middleware behavior; some httpx usages hard-code timeouts. We also want consistent Problem+JSON semantics for timeout errors.
+
+## Decision
+Introduce environment-driven timeouts and wire them via FastAPI middlewares and helper factories:
+
+- Request body read timeout: aborts slow body streaming (e.g., slowloris) with 408 Request Timeout.
+- Overall request timeout: caps handler execution time and returns 504 Gateway Timeout.
+- httpx client defaults: central helpers that pick a sane default timeout from env.
+- DB statement timeout: future work (PG: SET LOCAL statement_timeout; SQLite/dev: asyncio.wait_for wrapper). Scoped in follow-ups.
+ - Graceful shutdown: track in-flight HTTP requests and wait up to grace period; provide worker runner with stop/grace.
+
+## Configuration
+Environment variables (with suggested defaults):
+
+- REQUEST_BODY_TIMEOUT_SECONDS: int, default 15 (prod), 30 (non-prod)
+- REQUEST_TIMEOUT_SECONDS: int, default 30 (prod), 15 (non-prod)
+- HTTP_CLIENT_TIMEOUT_SECONDS: float, default 10.0
+
+These are read at process start. Services can override per-env.
+
+## Behavior
+- Body read timeout → 408 application/problem+json with title "Request Timeout"; optional Retry-After not included by default.
+- Handler timeout → 504 application/problem+json with title "Gateway Timeout"; include request trace_id in body if present.
+- Errors use existing problem_response helper.
+
+## Placement
+- Middlewares under svc_infra.api.fastapi.middleware.timeout
+- Wiring in svc_infra.api.fastapi.setup._setup_middlewares (after RequestId, before error catching).
+- httpx helpers under svc_infra.http.client: new_httpx_client/new_async_httpx_client with env-driven defaults.
+ - Graceful shutdown under svc_infra.api.fastapi.middleware.graceful_shutdown and svc_infra.jobs.runner.WorkerRunner.
+
+## Alternatives Considered
+- Starlette TimeoutMiddleware: version support/behavior varies; custom middleware gives us consistent Problem+JSON and finer control across environments.
+
+## Consequences
+- Adds two middlewares to every app created via setup_service_api/easy_service_app.
+- Minor overhead per request; mitigated by simple asyncio.wait_for usage.
+
+## Follow-ups
+- PG statement timeout integration; SQLite/dev wrapper.
+- Jobs/webhook runner per-job timeout.
+ - Graceful shutdown drainage hooks for servers/workers.
+- Acceptance tests A2-04..A2-06 per PLANS.
+
+## Change log
+- 2025-10-21: Finalized httpx helpers design and placement; proceed to implementation.
+
+---
+ Status: Accepted
+Date: 2025-10-21
+Related: PLANS A2 — Timeouts & Resource Limits