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

svc_infra/docs/admin.md

@@ -0,0 +1,425 @@
+# Admin Scope & Operations
+
+This guide covers the admin subsystem: admin-only routes, permissions, impersonation, and operational guardrails.
+
+## Overview
+
+The admin module provides:
+- **Admin router pattern**: Role-gated endpoints under `/admin` with fine-grained permission checks
+- **Impersonation**: Controlled user impersonation for support and debugging with full audit trails
+- **Permission alignment**: `admin.impersonate` permission integrated with the RBAC system
+- **Easy integration**: One-line setup via `add_admin(app, ...)`
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.admin import add_admin
+
+app = FastAPI()
+
+# Mount admin endpoints with defaults
+add_admin(app)
+
+# Endpoints are now available:
+# POST /admin/impersonate/start
+# POST /admin/impersonate/stop
+```
+
+### Custom User Loader
+
+If you have a custom user model or retrieval logic:
+
+```python
+from fastapi import Request
+
+async def my_user_getter(request: Request, user_id: str):
+    # Your custom user loading logic
+    user = await my_user_service.get_user(user_id)
+    if not user:
+        raise HTTPException(404, "user_not_found")
+    return user
+
+add_admin(app, impersonation_user_getter=my_user_getter)
+```
+
+### Configuration
+
+Environment variables:
+
+- `ADMIN_IMPERSONATION_SECRET`: Secret for signing impersonation tokens (falls back to `APP_SECRET` or `"dev-secret"`)
+- `ADMIN_IMPERSONATION_TTL`: Token TTL in seconds (default: 900 = 15 minutes)
+- `ADMIN_IMPERSONATION_COOKIE`: Cookie name (default: `"impersonation"`)
+
+Function parameters:
+
+```python
+add_admin(
+    app,
+    base_path="/admin",              # Base path for admin routes
+    enable_impersonation=True,        # Enable impersonation endpoints
+    secret=None,                      # Override token signing secret
+    ttl_seconds=15 * 60,              # Token TTL (15 minutes)
+    cookie_name="impersonation",      # Cookie name
+    impersonation_user_getter=None,   # Custom user loader
+)
+```
+
+## Permissions & RBAC
+
+### Admin Role
+
+The `admin` role includes the following permissions by default:
+
+- `user.read`, `user.write`: User management
+- `billing.read`, `billing.write`: Billing operations
+- `security.session.list`, `security.session.revoke`: Session management
+- `admin.impersonate`: User impersonation
+
+### Permission Guards
+
+Admin endpoints use layered guards:
+
+1. **Role gate** at router level: `RequireRoles("admin")`
+2. **Permission gate** at endpoint level: `RequirePermission("admin.impersonate")`
+
+This ensures both coarse-grained role membership and fine-grained permission enforcement.
+
+### Custom Admin Routes
+
+```python
+from svc_infra.api.fastapi.admin import admin_router
+from svc_infra.security.permissions import RequirePermission
+
+# Create an admin-only router
+router = admin_router(prefix="/admin", tags=["admin"])
+
+@router.get("/analytics", dependencies=[RequirePermission("analytics.read")])
+async def admin_analytics():
+    return {"data": "..."}
+
+app.include_router(router)
+```
+
+## Impersonation
+
+### Use Cases
+
+- **Customer support**: Debug issues as the affected user
+- **Testing**: Verify permission boundaries and user-specific behavior
+- **Compliance**: Audit access patterns under controlled conditions
+
+### Workflow
+
+#### 1. Start Impersonation
+
+```bash
+POST /admin/impersonate/start
+Content-Type: application/json
+
+{
+  "user_id": "u-12345",
+  "reason": "Investigating billing issue #789"
+}
+```
+
+**Requirements:**
+- Authenticated user must have `admin` role
+- User must have `admin.impersonate` permission
+- `reason` field is mandatory
+
+**Response:** `204 No Content` with impersonation cookie set
+
+#### 2. Make Requests as Impersonated User
+
+All subsequent requests will be made as the target user while preserving the admin's permissions for authorization checks:
+
+```bash
+GET /api/v1/profile
+Cookie: impersonation=<token>
+
+# Returns the impersonated user's profile
+```
+
+**Behavior:**
+- `request.user` reflects the impersonated user
+- `request.user.roles` inherits the actor's roles (admin maintains permissions)
+- `principal.via` is set to `"impersonated"` for tracking
+
+#### 3. Stop Impersonation
+
+```bash
+POST /admin/impersonate/stop
+
+# Response: 204 No Content
+# Cookie deleted, subsequent requests use original identity
+```
+
+### Security Guardrails
+
+#### Short TTL
+- Default: 15 minutes
+- No sliding refresh: token expires after TTL regardless of activity
+- Rationale: Minimize blast radius of compromised impersonation sessions
+
+#### Explicit Reason
+- Required for every impersonation start
+- Logged in audit trail for compliance and forensics
+
+#### Audit Trail
+Every impersonation action is logged with:
+- `admin.impersonation.started`: actor, target, reason, expiry
+- `admin.impersonation.stopped`: termination reason (manual/expired)
+
+Example log entry:
+```json
+{
+  "message": "admin.impersonation.started",
+  "actor_id": "u-admin-42",
+  "target_id": "u-12345",
+  "reason": "Investigating billing issue #789",
+  "expires_in": 900,
+  "timestamp": "2025-11-01T12:00:00Z"
+}
+```
+
+#### Token Security
+- HMAC-SHA256 signed tokens with nonce
+- Includes: actor_id, target_id, issued_at, expires_at, nonce
+- Tamper detection via signature verification
+- Cookie attributes:
+  - `httponly=true`: No JavaScript access
+  - `samesite=lax`: CSRF protection
+  - `secure=true` in production: HTTPS only
+
+#### Permission Preservation
+- Impersonated requests maintain the actor's permissions
+- Prevents privilege escalation by impersonating a higher-privileged user
+- Target user context for data scoping, actor permissions for authorization
+
+### Operational Recommendations
+
+#### Development
+```python
+# Relaxed for local testing
+add_admin(
+    app,
+    secret="dev-secret",
+    ttl_seconds=60 * 60,  # 1 hour for convenience
+)
+```
+
+#### Production
+```python
+# Strict settings
+add_admin(
+    app,
+    secret=os.environ["ADMIN_IMPERSONATION_SECRET"],  # Strong secret from vault
+    ttl_seconds=15 * 60,  # 15 minutes max
+)
+```
+
+**Best practices:**
+- Rotate `ADMIN_IMPERSONATION_SECRET` periodically
+- Monitor impersonation logs for anomalies
+- Set up alerts for frequent impersonation by the same actor
+- Consider org/tenant scoping for multi-tenant systems
+- Document allowed impersonation reasons in your runbook
+
+## Monitoring & Observability
+
+### Metrics
+
+Label admin routes with `route_class=admin` for SLO tracking:
+
+```python
+from svc_infra.obs.add import add_observability
+
+def route_classifier(path: str) -> str:
+    if path.startswith("/admin"):
+        return "admin"
+    # ... other classifications
+    return "public"
+
+add_observability(app, route_classifier=route_classifier)
+```
+
+### Audit Log Queries
+
+Search for impersonation events:
+```python
+# Example: Query structured logs
+logs.filter(message="admin.impersonation.started") \
+    .filter(actor_id="u-admin-42") \
+    .order_by(timestamp.desc()) \
+    .limit(100)
+```
+
+Compliance report:
+```python
+# Generate monthly impersonation summary
+impersonations = audit_log.filter(
+    event_type__in=["admin.impersonation.started", "admin.impersonation.stopped"],
+    timestamp__gte=start_of_month,
+)
+report = impersonations.group_by("actor_id").agg(count="id", targets=unique("target_id"))
+```
+
+## Testing
+
+### Unit Tests
+
+```python
+import pytest
+from svc_infra.api.fastapi.admin import add_admin
+
+@pytest.mark.admin
+def test_impersonation_requires_permission():
+    app = make_test_app()
+    add_admin(app, impersonation_user_getter=lambda req, uid: User(id=uid))
+
+    # Without admin role → 403
+    client = TestClient(app)
+    r = client.post("/admin/impersonate/start", json={"user_id": "u-2", "reason": "test"})
+    assert r.status_code == 403
+```
+
+### Acceptance Tests
+
+```python
+@pytest.mark.acceptance
+@pytest.mark.admin
+def test_impersonation_lifecycle(admin_client):
+    # Start impersonation
+    r = admin_client.post(
+        "/admin/impersonate/start",
+        json={"user_id": "u-target", "reason": "acceptance test"}
+    )
+    assert r.status_code == 204
+
+    # Verify impersonated context
+    profile = admin_client.get("/api/v1/profile")
+    assert profile.json()["id"] == "u-target"
+
+    # Stop impersonation
+    r = admin_client.post("/admin/impersonate/stop")
+    assert r.status_code == 204
+```
+
+Run admin tests:
+```bash
+pytest -m admin
+```
+
+## Troubleshooting
+
+### Impersonation Not Working
+
+**Symptom:** Impersonation cookie set but requests still use original identity
+
+**Check:**
+1. Cookie is being sent: verify `Cookie: impersonation=<token>` in request headers
+2. Token is valid: check signature and expiry
+3. User getter succeeds: ensure `impersonation_user_getter` doesn't raise exceptions
+4. Dependency override is active: `add_admin` registers a global override on startup
+
+**Debug:**
+```python
+# Enable debug logging
+import logging
+logging.getLogger("svc_infra.api.fastapi.admin").setLevel(logging.DEBUG)
+```
+
+### Permission Denied
+
+**Symptom:** 403 when calling `/admin/impersonate/start`
+
+**Check:**
+1. User has `admin` role: verify `user.roles` includes `"admin"`
+2. Permission registered: ensure `admin.impersonate` is in the permission registry
+3. Permission assigned to role: check `PERMISSION_REGISTRY["admin"]` includes `"admin.impersonate"`
+
+### Token Expired Too Soon
+
+**Symptom:** Impersonation session ends before expected TTL
+
+**Possible causes:**
+1. TTL misconfigured: check `ADMIN_IMPERSONATION_TTL` environment variable
+2. Server time skew: verify system clock is synchronized (NTP)
+3. Cookie attributes: ensure `max_age` matches TTL
+
+## Security Considerations
+
+### Threat Model
+
+| Threat | Mitigation |
+|--------|-----------|
+| Token theft (XSS) | `httponly=true` cookie prevents JavaScript access |
+| Token theft (network) | `secure=true` requires HTTPS in production |
+| CSRF attacks | `samesite=lax` prevents cross-site cookie sending |
+| Privilege escalation | Actor permissions preserved during impersonation |
+| Prolonged access | Short TTL (15 min default) with no refresh |
+| Abuse detection | Audit logs with reason, actor, and target tracking |
+| Insider threat | Required reason and comprehensive audit trail |
+
+### Compliance
+
+**SOC 2 / ISO 27001:**
+- Audit trail requirement: ✅ All impersonation events logged
+- Access justification: ✅ Mandatory `reason` field
+- Time-bound access: ✅ Short TTL with no renewal
+- Least privilege: ✅ Permission-based access control
+
+**GDPR / Data Protection:**
+- Lawful basis: Support/debugging under legitimate interest or contract performance
+- Data minimization: Only necessary user context loaded
+- Transparency: Log access for data subject access requests (DSAR)
+- Documentation: This guide serves as basis for DPA documentation
+
+## API Reference
+
+### `add_admin(app, **kwargs)`
+
+Wire admin endpoints and impersonation to a FastAPI app.
+
+**Parameters:**
+- `app` (FastAPI): Target application
+- `base_path` (str): Admin router base path (default: `"/admin"`)
+- `enable_impersonation` (bool): Enable impersonation endpoints (default: `True`)
+- `secret` (str | None): Token signing secret (default: env `ADMIN_IMPERSONATION_SECRET`)
+- `ttl_seconds` (int): Token TTL (default: `900` = 15 minutes)
+- `cookie_name` (str): Cookie name (default: `"impersonation"`)
+- `impersonation_user_getter` (Callable | None): Custom user loader `(request, user_id) -> user`
+
+**Returns:** None (modifies app in place)
+
+**Idempotency:** Safe to call multiple times; only wires once per app instance
+
+### `admin_router(**kwargs)`
+
+Create an admin-only router with role gate.
+
+**Parameters:** Same as `APIRouter` (FastAPI)
+
+**Returns:** APIRouter with `RequireRoles("admin")` dependency
+
+**Example:**
+```python
+from svc_infra.api.fastapi.admin import admin_router
+
+router = admin_router(prefix="/admin/reports", tags=["admin-reports"])
+
+@router.get("/summary")
+async def admin_summary():
+    return {"total_users": 1234}
+```
+
+## Further Reading
+
+- [ADR 0011: Admin scope and impersonation](../src/svc_infra/docs/adr/0011-admin-scope-and-impersonation.md)
+- [Security & Auth Hardening](./security.md)
+- [Permissions & RBAC](./security.md#permissions-and-rbac)
+- [Audit Logging](./security.md#audit-logging)
+- [Observability](./observability.md)

svc_infra/docs/adr/0002-background-jobs-and-scheduling.md

@@ -0,0 +1,40 @@
+# ADR 0002: Background Jobs & Scheduling
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+We need production-grade background job processing and simple scheduling with a one-call setup. The library already includes in-memory queue/scheduler for tests/local. We need a production backend and a minimal runner.
+
+## Decision
+- JobQueue protocol defines enqueue/reserve/ack/fail with retry and exponential backoff (base seconds * attempts). Jobs have: id, name, payload, available_at, attempts, max_attempts, backoff_seconds, last_error.
+- Backends:
+  - InMemoryJobQueue for tests/local.
+  - RedisJobQueue for production using Redis primitives with visibility timeout and atomic operations.
+- Scheduler:
+  - InMemoryScheduler providing interval-based scheduling via next_run_at. Cron parsing is out of scope initially; a simple YAML loader can be added later.
+- Runner:
+  - A CLI loop `svc-infra jobs run` will tick the scheduler and process jobs in a loop with small sleep/backoff.
+- Configuration:
+  - One-call `easy_jobs()` returns (queue, scheduler). Picks backend via `JOBS_DRIVER` env (memory|redis). Redis URL via `REDIS_URL`.
+
+## Alternatives Considered
+- Using RQ/Huey/Celery: heavier dependency and less control over API ergonomic goals; we prefer thin primitives aligned with svc-infra patterns.
+- SQL-backed queue first: we will consider later; Redis is sufficient for v1.
+
+## Consequences
+- Enables outbox/webhook processors on a reliable queue.
+- Minimal cognitive load: consistent APIs, ENV-driven.
+- Future work: SQL queue, cron YAML loader, metrics, concurrency controls.
+
+## Redis Data Model (initial)
+- List `jobs:ready` holds ready job IDs; a ZSET `jobs:delayed` with score=available_at keeps delayed jobs; a HASH per job `job:{id}` stores fields.
+- Reserve uses RPOPLPUSH from `jobs:ready` to `jobs:processing` or BRPOPLPUSH with timeout; sets `visible_at` on job as now+vt and increments `attempts`.
+- Ack removes job from `jobs:processing` and deletes `job:{id}`.
+- Fail increments attempts and computes next available_at = now + backoff_seconds * attempts; moves job to delayed ZSET.
+- A housekeeping step periodically moves due jobs from delayed ZSET to ready list. Reserve also checks ZSET for due jobs opportunistically.
+
+## Testing Strategy
+- Unit tests cover enqueue/reserve/ack/fail, visibility timeout behavior, and DLQ after max_attempts.
+- Runner tests cover one iteration loop processing.

svc_infra/docs/adr/0003-webhooks-framework.md

@@ -0,0 +1,24 @@
+# ADR 0003: Webhooks Framework
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+Services need a consistent way to publish domain events to external consumers via webhooks, verify inbound signatures, and handle retries with backoff. We already have an outbox pattern, a job queue, and a webhook delivery worker.
+
+## Decision
+- Event Schema: minimal fields {topic, payload, version, created_at}. Versioning included to evolve payloads.
+- Signing: HMAC-SHA256 over canonical JSON payload; header `X-Signature` carries hex digest. Future: include timestamp and v1 signature header variant.
+- Outbox → Job Queue: Producer writes events to Outbox; outbox tick enqueues delivery jobs; worker performs HTTP POST with signature.
+- Subscriptions: In-memory subscription store maps topic → {url, secret}. Persistence deferred.
+- Verification: Provide helper for verifying incoming webhook requests by recomputing the HMAC.
+- Retry: Already handled by JobQueue backoff; DLQ after max attempts.
+
+## Consequences
+- Clear boundary: producers don't call HTTP directly; they publish to Outbox.
+- Deterministic signing & verification across producer/consumer.
+- Extensibility: timestamped signed headers, secret rotation, persisted subscriptions are future extensions.
+
+## Testing
+- Unit tests for verification helper and end-to-end publish→outbox→queue→delivery using in-memory components and a fake HTTP client.

svc_infra/docs/adr/0004-tenancy-model.md

@@ -0,0 +1,42 @@
+# ADR-0004: Tenancy Model and Enforcement
+
+Date: 2025-10-15
+
+Status: Proposed
+
+## Context
+
+The framework needs a consistent, ergonomic multi-tenant story across modules (API scaffolding, SQL/Mongo persistence, auth/security, payments, jobs, webhooks). Existing patterns already reference `tenant_id` in many places (payments models and service, audit/session models, SQL/Mongo scaffolds). However, enforcement and app ergonomics were not unified.
+
+## Decision
+
+Adopt a default "soft-tenant" isolation model via a `tenant_id` column and centralized enforcement primitives:
+
+- Resolution: `resolve_tenant_id` and `require_tenant_id` FastAPI dependencies in `api.fastapi.tenancy.context`. Resolution order: override hook → identity (user/api_key) → `X-Tenant-Id` header → `request.state.tenant_id`.
+- Enforcement in SQL: `TenantSqlService(SqlService)` that scopes list/get/update/delete/search/count with a `where` clause and injects `tenant_id` on create when the model supports it. Repository methods accept optional `where` filters.
+- Router ergonomics: `make_tenant_crud_router_plus_sql` which requires `TenantId` and uses `TenantSqlService` under the hood. This keeps route code simple while enforcing scoping.
+- Extensibility: `set_tenant_resolver` hook to override resolution logic per app; `tenant_field` parameter to support custom column names. Future: schema-per-tenant or db-per-tenant via alternate repository/service implementations.
+
+## Alternatives considered
+
+1) Enforce tenancy at the ORM layer (SQLAlchemy events/session) – rejected for clarity and testability; we prefer explicit service/dep composition.
+2) Global middleware that rewrites queries – rejected due to SQLAlchemy complexity and opacity.
+3) Only rely on developers to remember filters – rejected due to footguns.
+
+## Consequences
+
+- Clear default behavior with escape hatches. Minimal changes for consumers using CRUD builders and SqlService.
+- Requires models to include an optional or required `tenant_id` column for scoping.
+- Non-SQL stores should add equivalent wrappers; Mongo scaffolds already include `tenant_id` fields and can mirror these patterns later.
+
+## Implementation Notes
+
+- New modules: `api.fastapi.tenancy.context`, `db.sql.tenant`. Repository updated to accept `where` filters.
+- CRUD router extended with `make_tenant_crud_router_plus_sql` to require `TenantId`.
+- Tests added: `tests/tenancy/*` for resolution and service scoping.
+
+## Open Items
+
+- Per-tenant quotas & rate limit overrides (tie into rate limit dependency/middleware via a resolver that returns per-tenant config).
+- Export tenant CLI (dump/import data for a specific tenant).
+- Docs: isolation guidance (column vs schema vs db), migration guidance.

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