svc-infra 0.1.622__py3-none-any.whl → 0.1.623__py3-none-any.whl

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,109 @@
+# 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.
+
+## 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/api.md

@@ -0,0 +1,59 @@
+# FastAPI helper guide
+
+The `svc_infra.api.fastapi` package provides a one-call bootstrap (`easy_service_app`) that wires request IDs, idempotency, rate limiting, and shared docs defaults for every mounted version. 【F:src/svc_infra/api/fastapi/ease.py†L176-L220】【F:src/svc_infra/api/fastapi/setup.py†L55-L129】
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(
+    name="Payments",
+    release="1.0.0",
+    versions=[("v1", "myapp.api.v1", None)],
+    public_cors_origins=["https://app.example.com"],
+)
+```
+
+### Environment
+
+`easy_service_app` merges explicit flags with `EasyAppOptions.from_env()` so you can flip behavior without code changes:
+
+- `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT` – control structured logging defaults. 【F:src/svc_infra/api/fastapi/ease.py†L67-L104】
+- `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS` – opt into Prometheus/OTEL middleware and tweak metrics exposure. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】
+- `CORS_ALLOW_ORIGINS` – add allow-listed origins when you don’t pass `public_cors_origins`. 【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
+
+## Quickstart
+
+Use `easy_service_app` for a batteries-included FastAPI with sensible defaults:
+
+Inputs
+- name: service display name used in docs and logs
+- release: version string (shown in docs and headers)
+- versions: list of tuples of (prefix, import_path, router_name_or_None)
+- public_cors_origins: list of allowed origins for CORS (default deny if omitted)
+
+Defaults
+- Logging: enabled with JSON or plain format based on `LOG_FORMAT`; level from `LOG_LEVEL`
+- Observability: Prometheus metrics and OTEL when `ENABLE_OBS=true`; metrics path from `METRICS_PATH` (default `/metrics`)
+- Security headers: strict defaults; CORS disabled unless allowlist provided or `CORS_ALLOW_ORIGINS` set
+- Health: `/ping`, `/healthz`, `/readyz`, `/startupz` are wired
+
+Example
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(
+    name="Example API",
+    release="1.0.0",
+    versions=[("v1", "example.api.v1", None)],
+    public_cors_origins=["https://app.example.com"],
+)
+```
+
+Override with environment
+```bash
+export ENABLE_LOGGING=true
+export LOG_LEVEL=INFO
+export ENABLE_OBS=true
+export METRICS_PATH=/metrics
+export CORS_ALLOW_ORIGINS=https://app.example.com,https://admin.example.com
+```

svc_infra/docs/auth.md

@@ -0,0 +1,11 @@
+# Auth settings
+
+`svc_infra.api.fastapi.auth` wraps FastAPI Users with sensible defaults for sessions, OAuth, MFA, and API keys via `add_auth_users`. Configuration comes from `AuthSettings`, which reads environment variables with the `AUTH_` prefix. 【F:src/svc_infra/api/fastapi/auth/add.py†L240-L321】【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
+
+### Key environment variables
+
+- `AUTH_JWT__SECRET`, `AUTH_JWT__OLD_SECRETS` – rotate signing keys without downtime. 【F:docs/security.md†L63-L70】
+- `AUTH_SMTP_HOST`, `AUTH_SMTP_USERNAME`, `AUTH_SMTP_PASSWORD`, `AUTH_SMTP_FROM` – enable SMTP delivery; required in production. 【F:src/svc_infra/api/fastapi/auth/settings.py†L44-L60】【F:src/svc_infra/api/fastapi/auth/sender.py†L33-L59】
+- `AUTH_SESSION_COOKIE_SECURE`, `AUTH_SESSION_COOKIE_NAME`, `AUTH_SESSION_COOKIE_SAMESITE` – shape session middleware. 【F:src/svc_infra/api/fastapi/auth/settings.py†L65-L88】【F:src/svc_infra/api/fastapi/auth/add.py†L279-L303】
+- `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_PASSWORD_BREACH_CHECK` – enforce password policy. 【F:docs/security.md†L24-L35】
+- `AUTH_MFA_DEFAULT_ENABLED_FOR_NEW_USERS`, `AUTH_MFA_ENFORCE_FOR_ALL_USERS` – adjust MFA enforcement. 【F:src/svc_infra/api/fastapi/auth/settings.py†L32-L40】

svc_infra/docs/cache.md

@@ -0,0 +1,18 @@
+# Cache guide
+
+The cache module wraps [cashews](https://github.com/Krukov/cashews) with decorators and namespace helpers so services can centralize key formats.
+
+```python
+from svc_infra.cache import cache_read, cache_write, init_cache
+
+init_cache()  # uses CACHE_PREFIX / CACHE_VERSION
+
+@cache_read(key="user:{user_id}", ttl=300)
+async def get_user(user_id: int):
+    ...
+```
+
+### Environment
+
+- `CACHE_PREFIX`, `CACHE_VERSION` – change the namespace alias used by the decorators. 【F:src/svc_infra/cache/README.md†L20-L173】
+- `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG` – override canonical TTL buckets. 【F:src/svc_infra/cache/ttl.py†L26-L55】

svc_infra/docs/cli.md

@@ -0,0 +1,74 @@
+# CLI Quick Reference
+
+The `svc-infra` CLI wraps common database, observability, jobs, docs, and DX workflows using Typer.
+
+- Entry points:
+  - Global: `svc-infra ...` (installed via Poetry scripts)
+  - Module: `python -m svc_infra.cli ...` (works in editable installs and containers)
+
+## Top-level help
+
+Run:
+
+```
+svc-infra --help
+```
+
+You should see groups for SQL, Mongo, Observability, DX, Jobs, and SDK.
+
+## Database (Alembic) commands
+
+- End-to-end setup and migrate (detects async from URL):
+  - Environment variables (commonly): `SQL_URL` or compose parts `DB_*`.
+
+Example with SQLite for quick smoke tests:
+
+```
+python -m svc_infra.cli sql setup-and-migrate --database-url sqlite+aiosqlite:///./accept.db \
+  --discover-packages "app.models" --with-payments false
+```
+
+- Current revision, history, upgrade/downgrade:
+
+```
+python -m svc_infra.cli sql current
+python -m svc_infra.cli sql-history
+python -m svc_infra.cli sql upgrade head
+python -m svc_infra.cli sql downgrade -1
+```
+
+- Seed fixtures/reference data with your callable:
+
+```
+python -m svc_infra.cli sql seed path.to.module:seed_func
+```
+
+Notes:
+- The target must be in the format `module.path:callable`.
+- If you previously referenced legacy test modules under `tests.db.*`, the CLI shims import to `tests.unit.db.*` when possible.
+
+## Jobs
+
+Start the local jobs runner loop:
+
+```
+svc-infra jobs run
+```
+
+## DX helpers
+
+- Generate CI workflow and checks template:
+
+```
+python -m svc_infra.cli dx ci --openapi openapi.json
+```
+
+- Lint OpenAPI and Problem+JSON samples:
+
+```
+python -m svc_infra.cli dx openapi openapi.json
+```
+
+## SDKs
+
+Generate SDKs from OpenAPI (dry-run by default): see `docs/docs-and-sdks.md` for full examples.

svc_infra/docs/contributing.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for considering a contribution! This repo aims to provide production-ready primitives with clear gates.
+
+## Local setup
+
+- Python 3.11–3.13
+- Install via Poetry:
+  - `poetry install`
+  - `poetry run pre-commit install`
+
+## Quality gates (run before PR)
+
+- Lint: `poetry run flake8 --select=E,F`
+- Typecheck: `poetry run mypy src`
+- Tests: `poetry run pytest -q -W error`
+- OpenAPI lint (optional): `poetry run python -m svc_infra.cli dx openapi openapi.json`
+- Migrations present (optional): `poetry run python -m svc_infra.cli dx migrations --project-root .`
+- CI dry-run (optional): `poetry run python -m svc_infra.cli dx ci --openapi openapi.json`
+
+## Commit style
+
+- Prefer Conventional Commits: `feat:`, `fix:`, `refactor:`, etc.
+- Use changelog generator for releases:
+  - `poetry run python -m svc_infra.cli dx changelog 0.1.604 --commits-file commits.jsonl`
+
+## Release process
+
+1. Ensure all gates are green locally (see above).
+2. Update version in `pyproject.toml`.
+3. Export OpenAPI (if applicable) via docs helper.
+4. Generate changelog section and review.
+5. Merge to `main`. CI will run tests, lint, and typecheck.
+6. Tag and publish.

svc_infra/docs/data-lifecycle.md

@@ -0,0 +1,52 @@
+# Data Lifecycle
+
+This guide covers fixtures (reference data), retention policies (soft/hard delete), GDPR erasure, and backup verification.
+
+## Quickstart
+
+- Fixtures:
+  - Use `run_fixtures([...])` for ad-hoc loads.
+  - Or wire a one-time loader with `make_on_load_fixtures(fn, run_once_file)`, then `add_data_lifecycle(app, on_startup=[on_load])`.
+- Retention:
+  - Define `RetentionPolicy(name, model, older_than_days, soft_delete_field|None, hard_delete=False)`.
+  - Execute manually with `await run_retention_purge(session, [policy,...])` or schedule via your jobs runner.
+- Erasure:
+  - Compose an `ErasurePlan([ErasureStep(name, func), ...])` where functions accept `(session, principal_id)` and may be async.
+  - Run with `await run_erasure(session, principal_id, plan, on_audit=callable)`; `on_audit` receives `(event, context)`.
+- Backups:
+  - `verify_backups(last_success: datetime|None, retention_days: int)` returns a `BackupHealthReport`.
+  - Wrap as a job: `make_backup_verification_job(checker, on_report=callback)`.
+
+## APIs
+
+- `fixtures.py`:
+  - `run_fixtures(callables: Iterable[Callable]) -> Awaitable[None]`
+  - `make_on_load_fixtures(*fns, run_once_file: str | None = None) -> Callable[[], Awaitable[None]]`
+- `retention.py`:
+  - `RetentionPolicy(name, model, older_than_days, soft_delete_field: str | None, hard_delete: bool = False)`
+  - `run_retention_purge(session, policies: Sequence[RetentionPolicy]) -> Awaitable[int]`
+- `erasure.py`:
+  - `ErasureStep(name: str, func: Callable)`
+  - `ErasurePlan(steps: Sequence[ErasureStep])`
+  - `run_erasure(session, principal_id: str, plan: ErasurePlan, on_audit: Callable | None = None) -> Awaitable[int]`
+- `backup.py`:
+  - `BackupHealthReport(ok: bool, last_success: datetime | None, reason: str | None)`
+  - `verify_backups(last_success: datetime | None = None, retention_days: int = 1) -> BackupHealthReport`
+  - `make_backup_verification_job(checker: Callable[[], BackupHealthReport], on_report: Callable[[BackupHealthReport], None] | None = None) -> Callable[[], BackupHealthReport]`
+
+## Scheduling
+
+Use the jobs helpers to run retention and backup checks periodically. Example schedule JSON (via JOBS_SCHEDULE_JSON):
+
+```json
+[
+  {"name": "retention-purge", "interval": "6h", "handler": "your.module:run_retention"},
+  {"name": "backup-verify",  "interval": "12h", "handler": "your.module:verify_backups_job"}
+]
+```
+
+## Notes
+
+- Soft delete expects a `deleted_at` column and optionally an `is_active` flag in repositories.
+- `run_fixtures` and erasure steps support async functions seamlessly.
+- `add_data_lifecycle` already awaits async fixture loaders and uses lifespan instead of deprecated startup events.

svc_infra/docs/database.md

@@ -0,0 +1,14 @@
+# Database guide
+
+svc-infra exposes helpers for SQLAlchemy and Mongo so APIs get lifecycle management, migrations, and connection URLs from environment variables.
+
+## SQL
+
+- `add_sql_db(app, url=None, dsn_env="SQL_URL")` wires the session and raises if the URL env is missing. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】
+- Build URLs piecemeal with `DB_DIALECT`, `DB_DRIVER`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_PARAMS`, or point at `SQL_URL_FILE`/`DB_PASSWORD_FILE`. 【F:src/svc_infra/db/sql/utils.py†L85-L206】
+- Alembic templates respect overrides such as `ALEMBIC_DISCOVER_PACKAGES`, `ALEMBIC_INCLUDE_SCHEMAS`, and `ALEMBIC_SKIP_DROPS`. 【F:src/svc_infra/db/sql/utils.py†L274-L347】
+
+## Mongo
+
+- `add_mongo_db(app, dsn_env="MONGO_URL")` validates the URL and optional db name. 【F:src/svc_infra/api/fastapi/db/nosql/mongo/add.py†L28-L53】
+- Configure via `MONGO_URL`, `MONGO_DB`, `MONGO_APPNAME`, `MONGO_MIN_POOL`, `MONGO_MAX_POOL`, or point at `MONGO_URL_FILE`. 【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】

svc_infra/docs/docs-and-sdks.md

@@ -0,0 +1,62 @@
+# Docs & SDKs
+
+This guide shows how to enable API docs, enrich your OpenAPI, and generate SDKs.
+
+## Enabling docs
+
+- Use `setup_service_api(...)` for versioned apps; root docs are auto-mounted in local/dev.
+- For standalone FastAPI apps, call `add_docs(app)` to mount:
+  - `/docs` (Swagger UI)
+  - `/redoc` (ReDoc)
+  - `/openapi.json` (OpenAPI schema)
+  - A landing page at `/` listing root and scoped docs (falls back to `/_docs` if `/` is taken).
+
+Tip: Append `?theme=dark` to `/docs` or `/redoc` for a minimal dark mode.
+
+## OpenAPI enrichment
+
+The OpenAPI pipeline adds helpful metadata automatically:
+- `x-codeSamples` per operation (curl and httpie) using your server base URL.
+- Problem+JSON examples on error responses (4xx/5xx) referencing the `Problem` schema.
+- Existing success/media examples are preserved and normalized.
+
+These mutators are applied for both root and versioned apps via `setup_mutators(...)`.
+
+## Exporting OpenAPI
+
+`add_docs(app, export_openapi_to="openapi.json")` writes the schema to disk on startup.
+
+## Generate SDKs (CLI)
+
+Use the CLI to generate SDKs from OpenAPI (defaults to dry-run, uses npx tools):
+
+- TypeScript (openapi-typescript-codegen):
+  svc-infra sdk ts openapi.json --outdir sdk-ts --dry-run=false
+
+- Python (openapi-generator):
+  svc-infra sdk py openapi.json --outdir sdk-py --package-name client_sdk --dry-run=false
+
+- Postman collection:
+  svc-infra sdk postman openapi.json --out postman.json --dry-run=false
+
+## Quick curl examples
+
+Replace URL and payload as needed; these align with x-codeSamples included in the schema.
+
+- GET
+  curl -X GET 'http://localhost:8000/v1/projects'
+
+- POST with JSON
+  curl -X POST 'http://localhost:8000/v1/projects' \
+    -H 'Content-Type: application/json' \
+    -d '{"name":"Example"}'
+
+Notes:
+- You need Node.js; the CLI calls `npx` for generator tools. Add them to your devDependencies for reproducibility.
+- For CI, export OpenAPI to a path and run the CLI with `--dry-run=false`.
+
+## Troubleshooting
+
+- Docs not visible at `/`? If your app already handles `/`, the landing page is mounted at `/_docs`.
+- Dark mode not applying? Use `/docs?theme=dark` or `/redoc?theme=dark`.
+- Missing Problem examples? Ensure your error handlers reference the `Problem` schema and that mutators run (they are wired by default in `setup_service_api`).