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

svc_infra/docs/cache.md

@@ -0,0 +1,76 @@
+# 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】
+
+## Easy integration: add_cache
+
+Use the one-liner helper to wire cache initialization into your ASGI app lifecycle with sensible defaults. This doesn’t replace the decorators; it standardizes init/readiness/shutdown and exposes a handle for convenience.
+
+```python
+from fastapi import FastAPI
+from svc_infra.cache import add_cache, cache_read, cache_write, resource
+
+app = FastAPI()
+
+# Wires startup (init + readiness) and shutdown (graceful close). Idempotent.
+add_cache(app)
+
+user = resource("user", "user_id")
+
+@user.cache_read(suffix="profile", ttl=300)
+async def get_user_profile(user_id: int):
+    ...
+
+@user.cache_write()
+async def update_user_profile(user_id: int, payload):
+    ...
+
+# Optional: direct cache instance for advanced scenarios
+# available after startup when using add_cache(app)
+# app.state.cache -> cashews cache instance
+```
+
+### Env-driven defaults
+
+- URL: `CACHE_URL` → `REDIS_URL` → `mem://`
+- Prefix: `CACHE_PREFIX` (default `svc`)
+- Version: `CACHE_VERSION` (default `v1`)
+
+You can override explicitly:
+
+```python
+add_cache(app, url="redis://localhost:6379/0", prefix="myapp", version="v2")
+```
+
+### Behavior
+
+- Idempotent: multiple calls won’t duplicate handlers.
+- Startup/shutdown hooks: registered when supported by the app; startup performs a readiness probe. Startup is optional for correctness, but recommended for production reliability.
+- app.state exposure: by default, exposes `app.state.cache` to access the underlying cashews instance.
+
+### No-app usage
+
+If you’re not wiring an app (e.g., a script), you can initialize without startup hooks:
+
+```python
+from svc_infra.cache import add_cache
+
+shutdown = add_cache(None)  # immediate init (best-effort)
+# ... do work ...
+# call shutdown() is a no-op placeholder for symmetry
+```

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`).

svc_infra/docs/environment.md

@@ -0,0 +1,114 @@
+# Environment Reference
+
+This guide consolidates every environment variable consumed by the svc-infra helpers in FastAPI, jobs, observability, security, and webhooks. Defaults shown below reflect the library's fallbacks when a variable is absent. Where a helper relies on `svc_infra.app.pick`, the note column calls out the environment-specific behavior.
+
+## FastAPI helpers
+
+### App bootstrap (`easy_service_app` / `setup_service_api`)
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `ENABLE_LOGGING` | `true` | `EasyAppOptions.from_env()` | Disables `setup_logging` when set to false. |
+| `LOG_LEVEL` | Auto (`INFO` in prod/test, `DEBUG` in dev/local via `pick()`) | `easy_service_app()` | Overrides the log level chosen by `svc_infra.app.pick`. |
+| `LOG_FORMAT` | Auto (JSON in prod, plain elsewhere) | `easy_service_app()` | Explicit `json` or `plain` format overrides auto-detection. |
+| `ENABLE_OBS` | `true` | `EasyAppOptions.from_env()` / `easy_service_app()` | Turns observability instrumentation on/off. |
+| `METRICS_PATH` | `None` → falls back to Observability settings | `EasyAppOptions.from_env()` | Use to expose metrics at a non-default path. |
+| `OBS_SKIP_PATHS` | `None` → defaults to metrics + health endpoints | `EasyAppOptions.from_env()` | Comma/space-separated list of paths skipped by Prometheus middleware. |
+| `CORS_ALLOW_ORIGINS` | `""` (no origins) | `_setup_cors()` | Adds `CORSMiddleware` allow-list when non-empty. |
+
+### SQL helpers (`add_sql_db`, `setup_sql`)
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `SQL_URL` (overridable via `dsn_env`) | _required_ | `add_sql_db()` / `setup_sql()` | Missing value raises `RuntimeError`; point at your primary database URL. |
+
+### Mongo helpers (`add_mongo_db`, `init_mongo`)
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `MONGO_URL` / `MONGODB_URL` | `mongodb://localhost:27017` | `MongoSettings`, `add_mongo_db()` | Primary Mongo connection string; `_FILE` suffix or `MONGO_URL_FILE` allow secret mounts. |
+| `MONGO_DB` / `MONGODB_DB` / `MONGO_DATABASE` | unset (optional) | `get_mongo_dbname_from_env()` | When set, verified against the connected database name. |
+| `MONGO_APPNAME` | `svc-infra` | `MongoSettings` | Sets the Mongo client `appname`. |
+| `MONGO_MIN_POOL` | `0` | `MongoSettings` | Minimum Motor/Mongo client pool size. |
+| `MONGO_MAX_POOL` | `100` | `MongoSettings` | Maximum Motor/Mongo client pool size. |
+| `MONGO_URL_FILE` | unset | `get_mongo_url_from_env()` | Alternate secret file path when not using `_FILE` suffix envs. |
+| `/run/secrets/mongo_url` | unset | `get_mongo_url_from_env()` | Auto-mounted Docker/K8s secret fallback for the URL. |
+
+### Auth settings (`get_auth_settings` → `AuthSettings`)
+
+Pydantic loads these with the `AUTH_` prefix and `__` as the nested delimiter.
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `AUTH_JWT__SECRET` | _required when JWT auth enabled_ | `AuthSettings.jwt.secret` | Primary HS256 signing secret. |
+| `AUTH_JWT__LIFETIME_SECONDS` | `604800` (7 days) | `AuthSettings.jwt.lifetime_seconds` | Adjusts refresh token lifetime. |
+| `AUTH_JWT__OLD_SECRETS__*` | `[]` | `AuthSettings.jwt.old_secrets` | Accepted legacy secrets during rotation. |
+| `AUTH_PASSWORD_CLIENTS__{n}__CLIENT_ID` | `[]` | `AuthSettings.password_clients[*].client_id` | Register password clients (list entries indexed by `{n}`). |
+| `AUTH_PASSWORD_CLIENTS__{n}__CLIENT_SECRET` | `[]` | `AuthSettings.password_clients[*].client_secret` | Secret per password client. |
+| `AUTH_REQUIRE_CLIENT_SECRET_ON_PASSWORD_LOGIN` | `false` | `AuthSettings.require_client_secret_on_password_login` | Enforces client secret on password grant. |
+| `AUTH_MFA_DEFAULT_ENABLED_FOR_NEW_USERS` | `false` | `AuthSettings.mfa_default_enabled_for_new_users` | Enable TOTP by default on signup. |
+| `AUTH_MFA_ENFORCE_FOR_ALL_USERS` | `false` | `AuthSettings.mfa_enforce_for_all_users` | Force MFA globally. |
+| `AUTH_MFA_ENFORCE_FOR_TENANTS` | `[]` | `AuthSettings.mfa_enforce_for_tenants` | Tenant allow-list requiring MFA. |
+| `AUTH_MFA_ISSUER` | `"svc-infra"` | `AuthSettings.mfa_issuer` | Label for TOTP apps. |
+| `AUTH_MFA_PRE_TOKEN_LIFETIME_SECONDS` | `300` | `AuthSettings.mfa_pre_token_lifetime_seconds` | Lifespan of MFA pre-token. |
+| `AUTH_MFA_RECOVERY_CODES` | `8` | `AuthSettings.mfa_recovery_codes` | Number of recovery codes issued. |
+| `AUTH_MFA_RECOVERY_CODE_LENGTH` | `10` | `AuthSettings.mfa_recovery_code_length` | Digits per recovery code. |
+| `AUTH_EMAIL_OTP_TTL_SECONDS` | `300` | `AuthSettings.email_otp_ttl_seconds` | Email OTP validity window. |
+| `AUTH_EMAIL_OTP_COOLDOWN_SECONDS` | `60` | `AuthSettings.email_otp_cooldown_seconds` | Cooldown between OTP sends. |
+| `AUTH_EMAIL_OTP_ATTEMPTS` | `5` | `AuthSettings.email_otp_attempts` | Maximum OTP attempts before lock. |
+| `AUTH_SMTP_HOST` | `None` | `AuthSettings.smtp_host` | SMTP hostname (required for prod email). |
+| `AUTH_SMTP_PORT` | `587` | `AuthSettings.smtp_port` | SMTP port. |
+| `AUTH_SMTP_USERNAME` | `None` | `AuthSettings.smtp_username` | SMTP username. |
+| `AUTH_SMTP_PASSWORD` | `None` | `AuthSettings.smtp_password` | SMTP password/secret. |
+| `AUTH_SMTP_FROM` | `None` | `AuthSettings.smtp_from` | Default From address. |
+| `AUTH_AUTO_VERIFY_IN_DEV` | `true` | `AuthSettings.auto_verify_in_dev` | Auto-confirms accounts outside prod. |
+| `AUTH_GOOGLE_CLIENT_ID` | `None` | `AuthSettings.google_client_id` | Built-in Google OAuth client ID. |
+| `AUTH_GOOGLE_CLIENT_SECRET` | `None` | `AuthSettings.google_client_secret` | Built-in Google OAuth secret. |
+| `AUTH_GITHUB_CLIENT_ID` | `None` | `AuthSettings.github_client_id` | GitHub OAuth client ID. |
+| `AUTH_GITHUB_CLIENT_SECRET` | `None` | `AuthSettings.github_client_secret` | GitHub OAuth secret. |
+| `AUTH_MS_CLIENT_ID` | `None` | `AuthSettings.ms_client_id` | Microsoft OAuth client ID. |
+| `AUTH_MS_CLIENT_SECRET` | `None` | `AuthSettings.ms_client_secret` | Microsoft OAuth secret. |
+| `AUTH_MS_TENANT` | `None` | `AuthSettings.ms_tenant` | Microsoft tenant ID. |
+| `AUTH_LI_CLIENT_ID` | `None` | `AuthSettings.li_client_id` | LinkedIn OAuth client ID. |
+| `AUTH_LI_CLIENT_SECRET` | `None` | `AuthSettings.li_client_secret` | LinkedIn OAuth secret. |
+| `AUTH_OIDC_PROVIDERS__{n}__NAME` | `[]` | `AuthSettings.oidc_providers[*].name` | Custom OIDC providers (list entries indexed by `{n}`). |
+| `AUTH_OIDC_PROVIDERS__{n}__ISSUER` | `[]` | `AuthSettings.oidc_providers[*].issuer` | OIDC issuer URL. |
+| `AUTH_OIDC_PROVIDERS__{n}__CLIENT_ID` | `[]` | `AuthSettings.oidc_providers[*].client_id` | OIDC client ID. |
+| `AUTH_OIDC_PROVIDERS__{n}__CLIENT_SECRET` | `[]` | `AuthSettings.oidc_providers[*].client_secret` | OIDC client secret. |
+| `AUTH_OIDC_PROVIDERS__{n}__SCOPE` | `"openid email profile"` | `AuthSettings.oidc_providers[*].scope` | Additional OIDC scopes. |
+| `AUTH_POST_LOGIN_REDIRECT` | `http://localhost:3000/app` | `AuthSettings.post_login_redirect` | Default redirect after login. |
+| `AUTH_REDIRECT_ALLOW_HOSTS_RAW` | `"localhost,127.0.0.1"` | `AuthSettings.redirect_allow_hosts_raw` | CSV/JSON allow-list for redirects. |
+| `AUTH_SESSION_COOKIE_NAME` | `"svc_session"` | `AuthSettings.session_cookie_name` | Session cookie key. |
+| `AUTH_AUTH_COOKIE_NAME` | `"svc_auth"` | `AuthSettings.auth_cookie_name` | Auth cookie key. |
+| `AUTH_SESSION_COOKIE_SECURE` | `false` | `AuthSettings.session_cookie_secure` | Marks session cookie `Secure`. |
+| `AUTH_SESSION_COOKIE_SAMESITE` | `"lax"` | `AuthSettings.session_cookie_samesite` | SameSite policy. |
+| `AUTH_SESSION_COOKIE_DOMAIN` | `None` | `AuthSettings.session_cookie_domain` | Explicit cookie domain. |
+| `AUTH_SESSION_COOKIE_MAX_AGE_SECONDS` | `14400` (4 hours) | `AuthSettings.session_cookie_max_age_seconds` | Session cookie lifetime. |
+
+## Jobs helpers
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `JOBS_DRIVER` | `memory` | `JobsConfig`, `easy_jobs()` | Choose `redis` to activate Redis-backed queue. |
+| `REDIS_URL` | `redis://localhost:6379/0` | `easy_jobs()` (Redis driver) | Redis connection string when `JOBS_DRIVER=redis`. |
+| `JOBS_SCHEDULE_JSON` | unset | `schedule_from_env()` | JSON array of scheduler tasks (name, interval_seconds, target). |
+
+## Observability helpers
+
+| Variable | Default | Consumed by | Notes |
+| --- | --- | --- | --- |
+| `METRICS_ENABLED` | `true` | `ObservabilitySettings` | Gate for Prometheus middleware registration. |
+| `METRICS_PATH` | `/metrics` | `ObservabilitySettings`, `add_observability()` | Metrics endpoint path. |
+| `METRICS_DEFAULT_BUCKETS` | `0.005,0.01,0.025,0.05,0.1,0.25,0.5,1.0,2.0,5.0,10.0` | `ObservabilitySettings` | Histogram buckets for request latency. |
+| `SVC_INFRA_DISABLE_PROMETHEUS` | unset (`"1"` disables) | `metrics.asgi` | Skip Prometheus setup when toggled. |
+| `SVC_INFRA_RATE_WINDOW` | unset | `cloud_dash.push_dashboards_from_pkg()` | Overrides `$__rate_interval` in dashboards. |
+| `SVC_INFRA_DASHBOARD_REFRESH` | `5s` | `cloud_dash.push_dashboards_from_pkg()` | Grafana dashboard auto-refresh interval. |
+| `SVC_INFRA_DASHBOARD_RANGE` | `now-6h` | `cloud_dash.push_dashboards_from_pkg()` | Default Grafana time range start. |
+
+## Security helpers
+
+The primitives under `svc_infra.security` rely on configuration objects passed from application code; they do not read environment variables directly beyond the shared `AuthSettings` listed above.
+
+## Webhook helpers
+
+Current webhook helpers (`fastapi.require_signature`, `InMemoryWebhookSubscriptions`, `WebhookService`) rely on dependency injection for secrets and stores and do not read environment variables directly.

svc_infra/docs/getting-started.md

@@ -0,0 +1,63 @@
+# svc-infra
+
+[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](.)
+
+svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
+
+## Helper index
+
+| Area | What it covers | Guide |
+| --- | --- | --- |
+| Getting Started | Overview and entry points | [This page](getting-started.md) |
+| Environment | Feature switches and env vars | [Environment](environment.md) |
+| API | FastAPI bootstrap, middleware, docs wiring | [API guide](api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](auth.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security](security.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](database.md) |
+| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](tenancy.md) |
+| Idempotency | Idempotent endpoints and middleware | [Idempotency](idempotency.md) |
+| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rate-limiting.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache](cache.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs](jobs.md) |
+| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](observability.md) |
+| Ops | Probes, breakers, SLOs & dashboards | [Ops](ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks](webhooks.md) |
+| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](cli.md) |
+| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](docs-and-sdks.md) |
+| Acceptance | Acceptance harness and flows | [Acceptance](acceptance.md), [Matrix](acceptance-matrix.md) |
+| Contributing | Dev setup and quality gates | [Contributing](contributing.md) |
+| Repo Review | Checklist for releasing/PRs | [Repo review](repo-review.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](data-lifecycle.md) |
+
+## Minimal FastAPI bootstrap
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.ease import easy_service_app
+from svc_infra.api.fastapi.db.sql.add import add_sql_db
+from svc_infra.cache import init_cache
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.fastapi import require_signature
+
+app = easy_service_app(name="Billing", release="1.2.3")
+add_sql_db(app)              # reads SQL_URL / DB_* envs
+init_cache()                 # honors CACHE_PREFIX / CACHE_VERSION
+queue, scheduler = easy_jobs()  # switches via JOBS_DRIVER / REDIS_URL
+
+@app.post("/webhooks/billing")
+async def handle_webhook(payload = Depends(require_signature(lambda: ["current", "next"]))):
+    queue.enqueue("process-billing-webhook", payload)
+    return {"status": "queued"}
+```
+
+## Environment switches
+
+- **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
+- **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
+- **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
+- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
+- **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
+- **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
+- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
+- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】

svc_infra/docs/idempotency.md

@@ -0,0 +1,111 @@
+# Idempotency & Concurrency Controls
+
+This guide explains how idempotency works in svc-infra and how to enable it for safe retries.
+
+## What it does
+- Prevents duplicate processing of mutating requests (POST/PATCH/DELETE).
+- Replays the previously successful response when the same `Idempotency-Key` is used.
+- Detects conflicts when the same key is reused with a different request body, returning 409.
+
+## Middleware usage
+```python
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+
+app.add_middleware(IdempotencyMiddleware)  # default: in-memory store, 24h TTL
+```
+- Header name: `Idempotency-Key` (configurable via `header_name`)
+- TTL: defaults to 24 hours (`ttl_seconds`)
+
+### Redis store (recommended for multi-instance)
+```python
+import redis
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.idempotency_store import RedisIdempotencyStore
+
+r = redis.Redis.from_url("redis://localhost:6379/0")
+store = RedisIdempotencyStore(r, prefix="idmp")
+app.add_middleware(IdempotencyMiddleware, store=store, ttl_seconds=24*3600)
+```
+
+## Per-route enforcement
+If an endpoint must require idempotency always, add the dependency:
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.middleware.idempotency import require_idempotency_key
+
+@app.post("/payments/intents", dependencies=[Depends(require_idempotency_key)])
+async def create_intent(...):
+    ...
+```
+
+## Semantics
+- First request with a key:
+  - The middleware claims the key and records a hash of the request body.
+  - On success (2xx), the response envelope is cached until TTL.
+- Replay with same key and same body:
+  - Returns the cached response with the original status and headers.
+- Replay with same key but different body:
+  - Returns 409 Conflict (don’t reuse keys for different logical operations).
+
+## Testing
+- Marker: `-m concurrency` selects concurrency tests in this repo.
+- Scenarios covered:
+  - Successful first request and replay
+  - Conflict on mismatched payload reusing the same key
+
+## Notes and pitfalls
+- Use a unique key per logical operation (e.g., `order-{id}-capture-1`).
+- TTL should exceed your max retry horizon.
+- For stronger guarantees in Redis, consider a Lua script to make the claim + response update atomic (future improvement).
+- If you also use optimistic locking, surface 409 when `If-Match` version mismatches during updates.
+
+---
+
+## Optimistic Locking
+
+Use the `If-Match` header and a version field on your models.
+
+```python
+from svc_infra.api.fastapi.middleware.optimistic_lock import require_if_match, check_version_or_409
+
+@app.patch("/resource/{rid}")
+async def update_resource(rid: str, v: str = Depends(require_if_match)):
+    current = await repo.get(...)
+    check_version_or_409(lambda: current.version, v)
+    current.version += 1
+    await repo.save(current)
+    return {...}
+```
+
+Pitfalls:
+- Always bump the version on successful updates.
+- Return 428 when `If-Match` is missing on mutating routes that require optimistic locking.
+- Consider ETag headers for GETs to complement conditional requests.
+
+---
+
+## Outbox / Inbox
+
+Outbox: record events/changes that must be delivered to external systems; a relay fetches and delivers reliably.
+
+```python
+from svc_infra.db.outbox import InMemoryOutboxStore
+
+ob = InMemoryOutboxStore()
+msg = ob.enqueue("orders.created", {"order_id": 123})
+nxt = ob.fetch_next(topics=["orders.created"])  # process
+ob.mark_processed(nxt.id)
+```
+
+Inbox: deduplicate external deliveries (e.g., webhook replays) with TTL.
+
+```python
+from svc_infra.db.inbox import InMemoryInboxStore
+
+ib = InMemoryInboxStore()
+if not ib.mark_if_new("provider-evt-abc", ttl_seconds=86400):
+    return 200  # duplicate
+```
+
+Notes:
+- In-memory stores are for tests/local dev; implement SQL/Redis for production with row locks and `SKIP LOCKED` (or Lua) as needed.