svc-infra 0.1.600__py3-none-any.whl → 0.1.664__py3-none-any.whl

svc_infra/docs/adr/0005-data-lifecycle.md

@@ -0,0 +1,86 @@
+# ADR 0005: Data Lifecycle — Soft Delete, Retention, Erasure, Backups
+
+Date: 2025-10-16
+Status: Accepted
+
+## Context
+We need a coherent Data Lifecycle story in svc-infra that covers:
+- Migrations & fixtures: simple way to run DB setup/migrations and load reference data.
+- Soft delete conventions: consistent filtering and model scaffolding support.
+- Retention policies: periodic purging of expired records per model/table.
+- GDPR/PII erasure: queued workflow to scrub user-related data while preserving legal audit.
+- Backups/PITR verification: a job that exercises restore checks or at least validates backup health signals.
+
+Existing building blocks:
+- Migrations CLI with end-to-end "setup-and-migrate" and new `sql seed` command for executing a user-specified seed callable.
+  - Code: `src/svc_infra/cli/cmds/db/sql/alembic_cmds.py` (cmd_setup_and_migrate, cmd_seed)
+- Soft delete support in repository and scaffold:
+  - Repo filtering: `src/svc_infra/db/sql/repository.py` (soft_delete flags, `deleted_at` timestamp, optional active flag)
+  - Model scaffolding: `src/svc_infra/db/sql/scaffold.py` (optional `deleted_at` field)
+- Easy-setup helper to coordinate lifecycle bits:
+  - `src/svc_infra/data/add.py` provides a startup hook to auto-migrate and optional callbacks for fixtures, retention jobs, and an erasure job.
+
+Gaps:
+- No standardized fixture loader contract beyond the callback surface.
+- No built-in retention policy registry or purge execution job.
+- No opinionated GDPR erasure workflow and audit trail.
+- No backup/PITR verification job implementation.
+
+## Decision
+Introduce minimal, composable primitives that keep svc-infra flexible while providing a clear path to production-grade lifecycle.
+
+1) Fixture Loader Contract
+- Provide a simple callable signature for deterministic, idempotent fixture loading: `Callable[[], None | Awaitable[None]]`.
+- Document best practices: UPSERT by natural keys, avoid random IDs, guard on existing rows.
+- Expose via `add_data_lifecycle(on_load_fixtures=...)` (already available); add docs and tests.
+
+2) Retention Policy Registry
+- Define a registry API that allows services to register per-resource retention rules.
+- Basic shape:
+  - `RetentionPolicy(name: str, model: type, where: list[Any] | None, older_than_days: int, soft_delete_field: str = "deleted_at")`
+  - A purge function computes a cutoff timestamp and issues DELETE or marks soft-delete fields.
+- Execution model: a periodic job (via jobs scheduler) calls `run_retention_purge(registry)`.
+- Keep SQL-only first; room for NoSQL extensions later.
+
+3) GDPR Erasure Workflow
+- Provide a single callable entrypoint `erase_principal(principal_id: str) -> None | Awaitable[None]`.
+- Default strategy: enqueue a job that runs a configurable erasure plan composed of steps (delete/soft-delete/overwrite) across tables.
+- Add an audit log entry per erasure request with outcome and timestamp (reuse `security.audit` helpers if feasible).
+- Keep the plan provider pluggable so apps specify which tables/columns participate.
+
+4) Backup/PITR Verification Job
+- Define an interface `verify_backups() -> HealthReport` with a minimal default implementation that:
+  - Queries the backup system or driver for last successful backup timestamp and retention window.
+  - Emits metrics/logs and returns a structured status.
+- Defer full "restore drill" capability; provide extension hook only.
+
+## Interfaces
+- Registry
+  - `register_retention(policy: RetentionPolicy) -> None`
+  - `run_retention_purge(session_factory, policies: list[RetentionPolicy]) -> PurgeReport`
+- Erasure
+  - `erase_principal(principal_id: str, plan: ErasurePlan, session_factory) -> ErasureReport`
+- Fixtures
+  - `load_fixtures()` as provided by caller via `add_data_lifecycle`.
+- Backup
+  - `verify_backups() -> BackupHealthReport`
+
+## Alternatives Considered
+- Heavy-weight DSL for retention and erasure: rejected for now; keep APIs Pythonic and pluggable.
+- Trigger-level soft delete enforcement: skipped to avoid provider lock-in; enforced at repository and query layer.
+- Full restore drill automation: out of scope for v1; introduce later behind provider integrations.
+
+## Consequences
+- Minimal surface that doesn't over-constrain adopters; provides default patterns and contracts.
+- Requires additional test scaffolds and example docs to demonstrate usage.
+- SQL-focused initial implementation; other backends can plug via similar interfaces.
+
+## Rollout & Testing
+- Add unit/integration tests for fixture loader, retention purge logic, and erasure workflow skeleton.
+- Provide docs in `docs/database.md` with examples and operational guidance.
+
+## References
+- `src/svc_infra/db/sql/repository.py` soft-delete handling
+- `src/svc_infra/db/sql/scaffold.py` deleted_at field scaffolding
+- `src/svc_infra/data/add.py` data lifecycle helper
+- `src/svc_infra/cli/cmds/db/sql/alembic_cmds.py` migrations & seed

svc_infra/docs/adr/0006-ops-slos-and-metrics.md

@@ -0,0 +1,47 @@
+# ADR-0006: Ops SLOs, SLIs, and Metrics Naming
+
+Date: 2025-10-16
+
+## Status
+Accepted
+
+## Context
+We already expose Prometheus metrics via `svc_infra.obs.add.add_observability`, which mounts the `PrometheusMiddleware` and exports:
+- `http_server_requests_total{method,route,code}`
+- `http_server_request_duration_seconds_bucket{route,method}` + _sum/_count
+- `http_server_inflight_requests{route}`
+- `http_server_response_size_bytes_bucket` + _sum/_count (where available)
+- `http_server_exceptions_total{route,exception}` (where available)
+
+We also optionally expose SQLAlchemy pool metrics and instrument `requests`/`httpx`. Logging is configured via `svc_infra.app.logging.setup_logging`.
+
+## Decision
+1. Metric naming and labels
+   - Keep `http_server_*` naming aligned with Prometheus and OpenTelemetry conventions.
+   - Labels: `route` uses normalized FastAPI route pattern (e.g., `/users/{id}`); `method` is uppercase HTTP verb; `code` is the 3-digit status.
+   - Add DB pool metrics with `db_pool_*` prefix when bound (labels: `engine`/`pool_name`).
+2. SLIs
+   - Request Success Rate: 1 - error_ratio, where errors are 5xx by default; optionally include 429/499 as errors per service config.
+   - Request Latency: p50/p90/p99 on `http_server_request_duration_seconds` by `route` and overall.
+   - Availability (Probes): uptime of `/_ops/live` and `/_ops/ready` endpoints.
+3. SLOs
+   - Default SLOs per service class:
+     - Public API: 99.9% success, p99 < 500ms.
+     - Internal API/Jobs control plane: 99.5% success, p99 < 1000ms.
+   - Error Budget: monthly window; alert on burn rates of 2h (fast) and 24h (slow). Budgets computed from success SLI.
+4. Dashboards & Alerts
+   - Provide Grafana JSON dashboard templates referencing the above metrics and labels.
+   - Include alert rules for budget burn (fast/slow).
+
+## Consequences
+- Developers can rely on consistent metrics and labels for dashboards.
+- SLO targets are explicit and can be overridden per service.
+- Future work: Emit `http_server_exceptions_total` where missing; provide helper to register per-route classes (public/internal/admin) to pick default SLOs.
+
+## Alternatives Considered
+- OpenTelemetry SDK direct instrumentation was considered but deferred to keep dependency surface minimal; we keep the naming aligned for easy migration.
+
+## References
+- `src/svc_infra/obs/metrics/asgi.py`
+- `src/svc_infra/api/fastapi/ops/add.py`
+- Google SRE Workbook: SLOs and Error Budgets

svc_infra/docs/adr/0007-docs-and-sdks.md

@@ -0,0 +1,83 @@
+# ADR 0007: Docs & SDKs — Research and Design
+
+Status: Proposed
+
+Date: 2025-10-16
+
+## Context
+
+We want a production-ready documentation and SDK experience built on our existing FastAPI scaffolding.
+Current capabilities in the codebase:
+
+- Docs endpoints and export
+  - `add_docs(app, redoc_url, swagger_url, openapi_url, export_openapi_to)` mounts Swagger, ReDoc, and OpenAPI JSON; optional export on startup.
+  - `setup_service_api(...)` renders a landing page with per-version doc cards and local-only root docs.
+  - `add_prefixed_docs(...)` exposes scoped docs (e.g., for auth/payments) with per-scope OpenAPI, Swagger, ReDoc.
+- OpenAPI conventions and enrichment pipeline
+  - Mutators pipeline (`openapi/mutators.py`) with: conventions, normalized Problem schema, pagination params/components, header params, info mutator, and auth scheme installers.
+  - Conventions define `Problem` schema and normalize examples.
+- DX checks
+  - OpenAPI Problem+JSON lint in `dx/checks.py` and CLI to validate.
+- SDK stub
+  - `add_sdk_generation_stub(app, on_generate=...)` exposes a hook endpoint to trigger SDK generation (no hard deps).
+
+Gaps for a complete v1 experience:
+
+- Enriched OpenAPI with examples and tags is not yet standardized across routers.
+- No built-in SDK generator CLI; only a stub exists. No pinned toolchain or CI integration.
+- No Postman collection generator.
+- No dark-mode toggle/themes for Swagger/ReDoc (landing page supports light/dark).
+- No smoke tests for generated SDKs.
+
+## Decision
+
+We will standardize the Docs & SDKs approach around the following:
+
+1) OpenAPI enrichment
+- Use existing mutators pipeline and add small mutators to:
+  - Inject global tags and tag descriptions for major areas (auth, payments, webhooks, ops).
+  - Attach minimal `x-codeSamples` for common operations (curl/httpie).
+  - Ensure `Problem` schema and example responses are present across 4xx/5xx.
+  - Keep pagination and header parameter mutators enabled by default.
+
+2) Docs UI
+- Continue with Swagger UI and ReDoc via `add_docs` and `setup_service_api`.
+- Add an optional dark mode toggle for Swagger UI via custom CSS and a query param (design-only; implement later).
+- Keep local-only exposure of root docs; version-specific docs always exposed under their mount path.
+
+3) SDK generation pipeline (tools and layout)
+- TypeScript: `openapi-typescript` to generate types (no runtime client) to `clients/typescript/`.
+- Python: `openapi-python-client` to generate a client package to `clients/python/`.
+- Provide a new CLI group `svc-infra sdk` with subcommands:
+  - `svc-infra sdk ts --schema openapi.json --out clients/typescript --package @org/service`
+  - `svc-infra sdk py --schema openapi.json --out clients/python --package service_sdk`
+  - `svc-infra sdk postman --schema openapi.json --out clients/postman_collection.json` (via converter)
+- Pin generator versions in a minimal tool manifest (poetry extras and npm devDeps suggestions in docs) rather than hard deps in core library.
+- Add optional CI steps to generate SDKs on release tags; artifacts uploaded; publishing pipelines documented.
+
+4) Postman collection
+- Use the Postman converter (`openapi-to-postmanv2`) to produce `clients/postman_collection.json` from the exported OpenAPI.
+
+5) Testing & verification
+- Extend `dx` checks to include: schema export presence, generator dry-run, and minimal smoke tests:
+  - TS: typecheck the generated d.ts.
+  - Python: `pip install -e` and import a sample client in a quick script.
+- Keep these checks optional (opt-in via CI config) to avoid burdening minimal users.
+
+## Consequences
+
+- Pros: Clear, tool-agnostic pipeline; no heavy runtime dependencies; easy local and CI usage; versioned artifacts.
+- Cons: Adds extra tooling expectations (node and python generators) for teams that opt in.
+- Risk: Generator/tooling churn; mitigate by pinning versions and providing stubs/fallbacks.
+
+## Implementation Notes (planned)
+
+- Provide a small `svc_infra/cli/cmds/sdk` module with Typer commands that shell out to the generators if available, with helpful error messages if missing.
+- Document usage in `docs/docs-and-sdks.md` (to be added), including examples and troubleshooting.
+- Keep all new code behind DX/CLI; core library remains free of generator dependencies.
+
+## Out of Scope (v1)
+
+- Live “try it” consoles beyond Swagger UI.
+- Multi-language example snippets beyond curl/httpie.
+- Automatic publishing to npm/PyPI (documented manual workflows first).

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

@@ -0,0 +1,143 @@
+# ADR 0008: Billing Primitives (Usage, Quotas, Invoicing)
+
+## Status
+
+Proposed — Research and Design complete for v1 scope.
+
+## Context
+
+We need shared billing primitives to support both usage-based and subscription features across services. Goals:
+- Capture fine-grained usage events with idempotency and tenant isolation.
+- Aggregate usage into billable buckets (hour/day/month) with rollups.
+- Enforce entitlements/quotas at runtime (hard/soft limits).
+- Produce invoice data structures and events; enable later integration with external providers (Stripe, Paddle) without coupling core DX to any vendor.
+
+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
+- Persist usage, aggregates, plans, subscriptions, invoices in our SQL layer.
+- Provide interfaces for provider adapters (Stripe later) to map internal invoices/lines and sync state when enabled.
+
+2) Usage ingestion API + idempotency
+- FastAPI router exposes POST /_billing/usage capturing events: {tenant_id, metric, amount, at, idempotency_key, metadata}.
+- Enforce request idempotency via existing middleware + usage-event unique index on (tenant_id, metric, idempotency_key).
+- Emit webhook event `billing.usage_recorded` (optional).
+
+3) Aggregation job (scheduler)
+- Background job reads new UsageEvent rows, aggregates into UsageAggregate by key (tenant, metric, period_start, period_granularity).
+- Granularities: hour, day, month (config). Maintains running totals; idempotent.
+- Emits `billing.usage_aggregated` webhook.
+
+4) Entitlements and quotas
+- Define Plan and PlanEntitlement models (feature flags, quotas per window).
+- Subscriptions bind tenant -> plan, effective_at/ended_at.
+- Runtime enforcement via dependency/decorator: `require_quota("metric", window="day", soft=True)` which raises/records when limit exceeded.
+
+5) Invoicing primitives
+- Invoice and InvoiceLine models created for each billing cycle (monthly default). Lines derived from aggregates and static prices.
+- Price model: unit amount, currency, metric reference (for metered), or fixed recurring.
+- Emit `billing.invoice_created` and `billing.invoice_finalized` webhooks; provider adapter can consume and sync out.
+
+6) Observability
+- Metrics: `billing_usage_ingest_total`, `billing_aggregate_duration_ms`, `billing_invoice_generated_total`.
+- Logs: aggregation windows processed, invoice cycles.
+
+7) Security & tenancy
+- All models include tenant_id; APIs require tenant context. RBAC: billing.read/billing.write for admin/operator roles.
+
+## Data Model (SQL)
+
+Tables (minimal 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, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+All tables will be scaffolded with our SQL helpers and tenant mixin, with Alembic templates.
+
+## APIs
+
+- POST /_billing/usage: record usage events (body as above). Returns 202 with event id.
+- GET /_billing/usage: list usage by metric and window (aggregated).
+- GET /_billing/plans, GET /_billing/subscriptions, POST /_billing/subscriptions.
+- GET /_billing/invoices, GET /_billing/invoices/{id}.
+
+Routers mounted under a `/_billing` prefix and hidden behind auth + tenant guard. OpenAPI tags: Billing.
+
+## Jobs & Webhooks
+
+- Job: `aggregate_usage` runs on schedule; creates/updates UsageAggregate rows.
+- Job: `generate_invoices` runs monthly; emits invoice events and inserts Invoice/InvoiceLine rows.
+- Webhooks: `billing.usage_recorded`, `billing.usage_aggregated`, `billing.invoice_created`, `billing.invoice_finalized` (signed via existing module).
+
+## Implementation Plan (Phased)
+
+Phase 1 (MVP):
+- Models + migrations; CRUD for Plans/Subs/Prices; Usage ingestion + idempotency; Aggregator job (daily granularity); Basic invoice generator (monthly, fixed price + metered by day sum); Webhooks emitted; Tests for ingestion, aggregation, simple invoice.
+
+Phase 2:
+- Granularity options (hourly); soft/hard quota decorator; Read APIs; Observability metrics; Docs.
+
+Phase 3 (Provider adapter optional):
+- Stripe adapter skeleton: map internal invoices/lines -> Stripe, idempotent sync; basic webhook handler to update statuses.
+
+## Alternatives Considered
+
+- Provider-first approach (Stripe-only) rejected for v1 to keep core DX portable and support non-card use-cases.
+- Event-stream aggregation (Kafka) out-of-scope for framework baseline—can be integrated later.
+
+## Risks
+
+- Complexity creep around proration and taxes—explicitly out-of-scope for v1.
+- Performance on large tenants—mitigated by granular aggregation and indexes.
+
+## Testing
+
+- Unit tests for ingestion idempotency, aggregation correctness, invoice totals.
+- E2E-ish tests using in-memory queue + sqlite.
+
+## Documentation
+
+- `docs/billing.md`: usage API, quotas, invoice lifecycle, and Stripe adapter notes.

svc_infra/docs/adr/0009-acceptance-harness.md

@@ -0,0 +1,40 @@
+# ADR 0009: Acceptance Harness & Promotion Gate (A0)
+
+Date: 2025-10-17
+Status: Proposed
+Decision: Adopt a post-build acceptance harness that brings up an ephemeral stack (Docker Compose) and gates image promotion on acceptance results.
+
+## Context
+- We need a thin but strict pre-deploy acceptance layer that runs after building images, before promotion.
+- It should validate golden paths across domains and basic operational invariants.
+- It must be easy to run locally and in CI and support a backend matrix (in-memory vs Redis+Postgres).
+- Supply-chain checks (SBOM, image scan, provenance) should be part of the gate.
+
+## Decision
+- Introduce A0 Acceptance Harness:
+  - Compose stack (api + db + redis), Makefile helpers (accept/up/wait/seed/down).
+  - Seed CLI/script to create ADMIN/USER/TENANT fixtures and API key.
+  - Acceptance tests under `tests/acceptance` with `@pytest.mark.acceptance` and BASE_URL.
+  - CI job `build-and-accept` steps: build → compose up → seed → `pytest -m "acceptance or smoke"` → OpenAPI lint + API Doctor → teardown.
+  - Supply-chain: generate SBOM, image scan (Trivy/Grype) with severity threshold; upload SBOM.
+  - Provenance: sign/attest images via cosign/SLSA (best-effort for v1).
+  - Backend matrix: two jobs (in-memory vs Redis+Postgres).
+
+## Alternatives
+- Testcontainers-only approach (simpler per-test spin-up) — good DX but slower; we can adopt later for certain suites.
+- Kubernetes-in-Docker (kind) for near-prod parity — heavier; likely a v2 improvement.
+
+## Consequences
+- Slightly longer CI time due to matrix and scans.
+- Clearer promotion safety; early detection of config/env gaps.
+
+## Implementation Notes
+- Files to add:
+  - `docker-compose.test.yml`
+  - `Makefile` targets: `accept`, `compose_up`, `wait`, `seed`, `down`
+  - `tests/acceptance/` scaffolding: `conftest.py`, `_seed.py`, `_auth.py`, `_http.py`, first tests (headers/CORS)
+  - CI: `.github/workflows/ci.yml` job `build-and-accept`
+- Env contracts:
+  - `SQL_URL`, `REDIS_URL` for backend matrix; `APP_ENV=test-accept` for toggles.
+- Evidence:
+  - CI run URL, SBOM artifact link, scan report, acceptance summary.

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/adr/0011-admin-scope-and-impersonation.md

@@ -0,0 +1,73 @@
+# 0011 — Admin scope, permissions, and impersonation
+
+## Context
+- The codebase already provides RBAC/permission helpers: `RequireRoles`, `RequirePermission`, ABAC via `RequireABAC`/`owns_resource`.
+- The central permission registry maps roles → permissions (`svc_infra.security.permissions.PERMISSION_REGISTRY`). Notably, the `admin` role includes: `user.read`, `user.write`, `billing.read`, `billing.write`, and `security.session.{list,revoke}`.
+- Acceptance tests demonstrate an “admin-only” route guarded by `RequirePermission("user.write")` and temporary role override to `admin`.
+- There is no dedicated admin API surface yet, and no impersonation flow; observability docs mention an optional route classifier that can label routes like `public|internal|admin`.
+
+## Goals
+- Define a consistent approach for admin-only surfaces and permission alignment.
+- Establish minimal permissions needed for admin operations, including impersonation.
+- Outline an impersonation flow with security and audit guardrails.
+- Prepare for an easy integration helper (`add_admin`) without implementing it yet.
+
+## Non-goals
+- Implement admin endpoints or impersonation logic in this ADR.
+- Replace existing permissions/guards — this ADR aligns and extends them.
+
+## Decisions
+
+1) Permissions alignment and additions
+- Keep permissions as the canonical guard unit; roles remain a mapping to permissions.
+- Extend the registry with a dedicated permission for impersonation:
+  - `admin.impersonate`
+- Keep existing entries (`security.session.{list,revoke}` etc.) as-is.
+- Recommended role → permission mapping updates:
+  - `admin`: add `admin.impersonate` (retains existing permissions).
+  - `auditor`: keep `audit.read` (already present) and may expand in the future.
+
+2) Admin router pattern
+- Provide an admin-only router pattern that layers role and permission checks consistently:
+  - Top-level: role gate via `RequireRoles("admin")` to reflect the “admin area”.
+  - Endpoint-level: permission gates via `RequirePermission(...)` for specific operations.
+- Rationale: roles communicate the coarse-grained area; fine-grained actions are enforced by permissions.
+- A future helper `admin_router()` can wrap `roles_router("admin")` (from `api.fastapi.dual.protected`) for ergonomic mounting.
+
+3) Impersonation flow (design)
+- Endpoints:
+  - `POST /admin/impersonate/start` — body: `{ user_id, reason }`; requires `admin.impersonate`.
+  - `POST /admin/impersonate/stop` — ends the session.
+- Mechanics:
+  - When starting, issue a short-lived, signed impersonation token (or set a dedicated cookie) that encodes: original admin principal id, target user id, issued-at, expires-at, and nonce.
+  - Downstream identity resolution should reflect the impersonated user for request handling, while preserving the original admin as the "actor" for auditing.
+  - Stopping invalidates the token/cookie (server-side revocation list or versioned secret), and subsequent requests fall back to the admin’s own identity.
+- Safety guardrails:
+  - Always require `admin.impersonate`.
+  - Enforce explicit `reason` and capture request fingerprint (ip hash, user-agent) with the event.
+  - Limit scope by tenant/org if applicable; optionally block actions explicitly marked non-impersonable.
+  - Set short TTL (e.g., 15 minutes) with sliding refresh disabled.
+
+4) Audit logging
+- Emit structured audit events for impersonation lifecycle:
+  - `admin.impersonation.started` with actor, target, reason, ip hash, user-agent, and expiry.
+  - `admin.impersonation.stopped` with actor, target, and termination reason (expired/manual).
+- Implementation options (future):
+  - Minimal: log via the existing logging setup (structured logger, e.g., `logger.bind(...).info("audit", ...)`).
+  - Preferred: emit to an audit outbox/table or webhook channel for retention and cross-system visibility.
+
+5) Observability and route classification
+- Encourage passing a `route_classifier` that labels admin routes as `admin` (e.g., for `/admin` base path) so metrics/SLO dashboards can split traffic into `public|internal|admin` classes.
+
+## Consequences
+- Clear, documented permissions and flow for admin-only features.
+- Minimal surface to add later: `admin_router()` and `add_admin(app, ...)` helper that mounts admin routes and wires impersonation endpoints + audit hooks.
+- Tests to plan when implementing:
+  - Role vs permission gating behavior on /admin routes.
+  - Impersonation start/stop lifecycle and audit emission.
+  - Ownership checks that permit admin bypass where intended (e.g., session revocation).
+
+## Follow-ups
+- Update the permission registry to include `admin.impersonate` (and map into `admin`).
+- Implement `admin_router()` and the `add_admin` helper following this ADR.
+- Add admin acceptance tests and documentation for guardrails and operational guidance.