svc-infra 0.1.629__py3-none-any.whl → 0.1.631__py3-none-any.whl

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)

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/cache/__init__.py

@@ -5,6 +5,8 @@ This module offers high-level decorators for read/write caching, cache invalidat
 and resource-based cache management.
 """
 
+from .add import add_cache
+
 # Core decorators - main public API
 from .decorators import cached  # alias for cache_read
 from .decorators import mutates  # alias for cache_write
@@ -32,4 +34,6 @@ __all__ = [
     # Resource-based caching
     "resource",
     "entity",
+    # Easy integration helper
+    "add_cache",
 ]

svc_infra/cache/add.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+"""
+Easy integration helper to wire the cache backend into an ASGI app lifecycle.
+
+Contract:
+- Idempotent: multiple calls are safe; startup/shutdown handlers are registered once.
+- Env-driven defaults: respects CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION, APP_ENV.
+- Lifecycle: registers startup (init + readiness probe) and shutdown (graceful close).
+- Ergonomics: exposes the underlying cache instance at app.state.cache by default.
+
+This does not replace the per-function decorators (`cache_read`, `cache_write`) and
+does not alter existing direct APIs; it simply standardizes initialization and wiring.
+"""
+
+import logging
+import os
+from typing import Any, Callable, Optional
+
+from svc_infra.cache.backend import DEFAULT_READINESS_TIMEOUT
+from svc_infra.cache.backend import instance as _instance
+from svc_infra.cache.backend import setup_cache as _setup_cache
+from svc_infra.cache.backend import shutdown_cache as _shutdown_cache
+from svc_infra.cache.backend import wait_ready as _wait_ready
+
+logger = logging.getLogger(__name__)
+
+
+def _derive_settings(
+    url: Optional[str], prefix: Optional[str], version: Optional[str]
+) -> tuple[str, str, str]:
+    """Derive cache settings from parameters or environment variables.
+
+    Precedence:
+      - explicit function arguments
+      - environment variables (CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION)
+      - sensible defaults (mem://, "svc", "v1")
+    """
+
+    derived_url = url or os.getenv("CACHE_URL") or os.getenv("REDIS_URL") or "mem://"
+    derived_prefix = prefix or os.getenv("CACHE_PREFIX") or "svc"
+    derived_version = version or os.getenv("CACHE_VERSION") or "v1"
+    return derived_url, derived_prefix, derived_version
+
+
+def add_cache(
+    app: Any | None = None,
+    *,
+    url: str | None = None,
+    prefix: str | None = None,
+    version: str | None = None,
+    readiness_timeout: float | None = None,
+    expose_state: bool = True,
+    state_key: str = "cache",
+) -> Callable[[], None]:
+    """Wire cache initialization and lifecycle into the ASGI app.
+
+    If an app is provided, registers startup/shutdown handlers. Otherwise performs
+    immediate initialization (best-effort) without awaiting readiness.
+
+    Returns a no-op shutdown callable for API symmetry with other helpers.
+    """
+
+    # Compute effective settings
+    eff_url, eff_prefix, eff_version = _derive_settings(url, prefix, version)
+
+    # If no app provided, do a simple init and return
+    if app is None:
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+            logger.info(
+                "Cache initialized (no app wiring): backend=%s namespace=%s",
+                eff_url,
+                f"{eff_prefix}:{eff_version}",
+            )
+        except Exception:
+            logger.exception("Cache initialization failed (no app wiring)")
+        return lambda: None
+
+    # Idempotence: avoid duplicate wiring
+    try:
+        state = getattr(app, "state", None)
+        already = bool(getattr(state, "_svc_cache_wired", False))
+    except Exception:
+        state = None
+        already = False
+
+    if already:
+        logger.debug("add_cache: app already wired; skipping re-registration")
+        return lambda: None
+
+    # Define lifecycle handlers
+    async def _startup():
+        _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        try:
+            await _wait_ready(timeout=readiness_timeout or DEFAULT_READINESS_TIMEOUT)
+        except Exception:
+            # Bubble up to fail fast on startup; tests and prod prefer visibility
+            logger.exception("Cache readiness probe failed during startup")
+            raise
+        # Expose cache instance for convenience
+        if expose_state and hasattr(app, "state"):
+            try:
+                setattr(app.state, state_key, _instance())
+            except Exception:
+                logger.debug("Unable to expose cache instance on app.state", exc_info=True)
+
+    async def _shutdown():
+        try:
+            await _shutdown_cache()
+        except Exception:
+            # Best-effort; shutdown should not crash the app
+            logger.debug("Cache shutdown encountered errors (ignored)", exc_info=True)
+
+    # Register event handlers when supported
+    register_ok = False
+    try:
+        if hasattr(app, "add_event_handler"):
+            app.add_event_handler("startup", _startup)
+            app.add_event_handler("shutdown", _shutdown)
+            register_ok = True
+    except Exception:
+        register_ok = False
+
+    if not register_ok:
+        # Fallback: attempt FastAPI/Starlette .on_event decorators dynamically
+        try:
+            on_event = getattr(app, "on_event", None)
+            if callable(on_event):
+                on_event("startup")(_startup)  # type: ignore[misc]
+                on_event("shutdown")(_shutdown)  # type: ignore[misc]
+                register_ok = True
+        except Exception:
+            register_ok = False
+
+    # Mark wired and expose state immediately if desired
+    if hasattr(app, "state"):
+        try:
+            setattr(app.state, "_svc_cache_wired", True)
+            if expose_state and not hasattr(app.state, state_key):
+                setattr(app.state, state_key, _instance())
+        except Exception:
+            pass
+
+    if register_ok:
+        logger.info("Cache wired: url=%s namespace=%s", eff_url, f"{eff_prefix}:{eff_version}")
+    else:
+        # If we cannot register handlers, at least initialize now
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        except Exception:
+            logger.exception("Cache initialization failed (no event registration)")
+
+    # Return a simple shutdown handle for symmetry with other add_* helpers
+    return lambda: None
+
+
+__all__ = ["add_cache"]

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