svc-infra 0.1.629__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/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

svc_infra/docs/billing.md

@@ -0,0 +1,190 @@
+# Billing Primitives
+
+This module provides internal-first billing building blocks for services that need usage-based and subscription billing without coupling to a specific provider. It complements APF Payments (provider-facing) with portable primitives you can use regardless of Stripe/Aiydan/etc.
+
+## What you get
+
+- Usage ingestion with idempotency (UsageEvent)
+- Windowed usage aggregation (UsageAggregate) — daily baseline
+- Plan and entitlements registry (Plan, PlanEntitlement)
+- Tenant subscriptions (Subscription)
+- Price catalog for fixed/usage items (Price)
+- Invoice and line items (Invoice, InvoiceLine)
+- A small `BillingService` to record usage, aggregate, and generate monthly invoices
+- Optional provider sync hook to mirror internal invoices/lines to your payment provider
+
+## Data model (SQL)
+
+Tables (v1):
+- usage_events(id, tenant_id, metric, amount, at_ts, idempotency_key, metadata_json, created_at)
+  - Unique (tenant_id, metric, idempotency_key)
+- usage_aggregates(id, tenant_id, metric, period_start, granularity, total, updated_at)
+  - Unique (tenant_id, metric, period_start, granularity)
+- plans(id, key, name, description, created_at)
+- plan_entitlements(id, plan_id, key, limit_per_window, window, created_at)
+- subscriptions(id, tenant_id, plan_id, effective_at, ended_at, created_at)
+- prices(id, key, currency, unit_amount, metric, recurring_interval, created_at)
+- invoices(id, tenant_id, period_start, period_end, status, total_amount, currency, provider_invoice_id, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+See `src/svc_infra/billing/models.py` for full definitions.
+
+## Quick start (Python)
+
+```python
+from datetime import datetime, timezone
+from sqlalchemy.orm import Session
+from svc_infra.billing import BillingService
+
+# session: SQLAlchemy Session (sync) targeting your DB
+bs = BillingService(session=session, tenant_id="t_123")
+
+# 1) Record usage (idempotent by (tenant, metric, idempotency_key))
+evt_id = bs.record_usage(
+    metric="tokens", amount=42,
+    at=datetime.now(tz=timezone.utc),
+    idempotency_key="req-42",
+    metadata={"model": "gpt"},
+)
+
+# 2) Aggregate for a day (baseline v1 granularity)
+bs.aggregate_daily(metric="tokens", day_start=datetime(2025,1,1,tzinfo=timezone.utc))
+
+# 3) Generate a monthly invoice (fixed+usage lines TBD)
+inv_id = bs.generate_monthly_invoice(
+    period_start=datetime(2025,1,1,tzinfo=timezone.utc),
+    period_end=datetime(2025,2,1,tzinfo=timezone.utc),
+    currency="usd",
+)
+```
+
+Optional: pass a provider sync hook if you want to mirror invoices/lines to Stripe/Aiydan:
+
+```python
+from typing import Callable
+from svc_infra.billing.models import Invoice, InvoiceLine
+
+async def sync_to_provider(inv: Invoice, lines: list[InvoiceLine]):
+    # Map internal invoice/lines to provider calls here
+    ...
+
+bs = BillingService(session=session, tenant_id="t_123", provider_sync=sync_to_provider)
+```
+
+### FastAPI router (usage ingestion & aggregates)
+
+Mount the router and start recording usage with idempotency:
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.billing.setup import add_billing
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.errors.handlers import register_error_handlers
+
+app = FastAPI()
+app.add_middleware(IdempotencyMiddleware, store={})
+register_error_handlers(app)
+add_billing(app)  # mounts under /_billing
+
+# POST /_billing/usage  {metric, amount, at?, idempotency_key, metadata?} -> 202 {id}
+# GET  /_billing/usage?metric=tokens -> {items: [{period_start, granularity, metric, total}], next_cursor}
+```
+
+### Quotas (soft/hard limits)
+
+Protect your feature endpoints with a quota dependency based on internal plan entitlements and daily aggregates:
+
+```python
+from fastapi import Depends
+from svc_infra.billing.quotas import require_quota
+
+@app.get("/generate-report", dependencies=[Depends(require_quota("reports", window="day", soft=False))])
+async def generate_report():
+  return {"ok": True}
+```
+
+## Relationship to APF Payments
+
+- APF Payments is provider-facing: customers, intents, methods, products/prices, subscriptions, invoices, usage records via Stripe/Aiydan adapters and HTTP routers.
+- Billing Primitives is provider-agnostic: an internal ledger of usage, plans/entitlements, and invoices that you can keep even if you change providers.
+- You can use both: continue to use APF Payments for card/payments flows, and use Billing to meter custom features and create internal invoices; selectively sync them out later.
+
+## Jobs and webhooks
+
+Billing includes helpers to enqueue and process jobs and emit webhooks:
+
+- Job names:
+  - `billing.aggregate_daily` payload: `{tenant_id, metric, day_start: ISO8601}`
+  - `billing.generate_monthly_invoice` payload: `{tenant_id, period_start: ISO8601, period_end: ISO8601, currency}`
+- Emitted webhook topics:
+  - `billing.usage_aggregated` payload: `{tenant_id, metric, day_start, total}`
+  - `billing.invoice.created` payload: `{tenant_id, invoice_id, period_start, period_end, currency}`
+
+Usage with the built-in queue/scheduler and webhooks outbox:
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.add import add_webhooks
+from svc_infra.webhooks.service import WebhookService
+from svc_infra.db.outbox import InMemoryOutboxStore
+from svc_infra.webhooks.service import InMemoryWebhookSubscriptions
+from svc_infra.billing.jobs import (
+    enqueue_aggregate_daily,
+    enqueue_generate_monthly_invoice,
+    make_billing_job_handler,
+)
+
+# Create queue + scheduler
+queue, scheduler = easy_jobs()
+
+# Setup DB async session factory
+engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+# Setup webhooks (in-memory stores shown here)
+outbox = InMemoryOutboxStore()
+subs = InMemoryWebhookSubscriptions()
+subs.add("billing.usage_aggregated", url="https://example.test/hook", secret="sekrit")
+webhooks = WebhookService(outbox=outbox, subs=subs)
+
+# Worker handler
+handler = make_billing_job_handler(session_factory=SessionLocal, webhooks=webhooks)
+
+# Enqueue example jobs
+from datetime import datetime, timezone
+enqueue_aggregate_daily(queue, tenant_id="t1", metric="tokens", day_start=datetime.now(timezone.utc))
+enqueue_generate_monthly_invoice(
+    queue, tenant_id="t1", period_start=datetime(2025,1,1,tzinfo=timezone.utc), period_end=datetime(2025,2,1,tzinfo=timezone.utc), currency="usd"
+)
+
+# In your worker loop call process_one(queue, handler)
+```
+
+## Roadmap (v1 scope)
+
+- Router: `/_billing` endpoints for usage ingestion (idempotent), aggregate listing, plans/subscriptions read.
+- Quotas: decorator/dependency to enforce per-plan limits (soft/hard, day/month windows).
+- Jobs: integrate aggregation and invoice-generation with the scheduler; emit `billing.*` webhooks. (helpers available in `svc_infra.billing.jobs`) — Implemented.
+- Provider sync: optional mapper to Stripe invoices/payment intents; reuse idempotency.
+- Migrations: author initial Alembic migration for billing tables.
+- Docs: examples for quotas and jobs; admin flows for plans and prices.
+
+## Testing
+
+- See `tests/unit/billing/test_billing_service.py` for usage, aggregation, invoice basics, and idempotency uniqueness.
+- Additions planned: router tests (ingest/list), quotas, job executions, webhook events.
+
+## Security & Tenancy
+
+- All records are tenant-scoped; ensure tenant_id is enforced in your service layer / router dependencies.
+- Protect HTTP endpoints with RBAC permissions (e.g., billing.read, billing.write) if you expose them.
+
+## Observability
+
+Planned metrics (names may evolve):
+- billing_usage_ingest_total
+- billing_aggregate_duration_ms
+- billing_invoice_generated_total
+
+See ADR 0008 for design details.

svc_infra/docs/ops.md

@@ -31,3 +31,7 @@ This guide explains how to use svc-infra’s probes, circuit breaker, and metric
 
 - Prometheus middleware is enabled unless `SVC_INFRA_DISABLE_PROMETHEUS=1`.
 - Observability settings: `METRICS_ENABLED`, `METRICS_PATH`, and optional histogram buckets.
+
+## See also
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — request/body/handler timeouts, outbound client timeouts, DB statement timeouts, jobs/webhooks, and graceful shutdown.

svc_infra/docs/rate-limiting.md

@@ -115,6 +115,10 @@ metrics.on_suspect_payload = lambda path, size: logger.warning(
 - Consider separate limits for read vs write routes.
 - Combine with request size limits and auth lockout for layered defense.
 
+## Related
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — complements rate limits by bounding slow uploads, long handlers, and downstream timeouts.
+
 ## Testing
 
 - Use `-m ratelimit` to select rate-limiting tests.