svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/docs/billing.md

@@ -0,0 +1,190 @@
+# Billing Primitives
+
+This module provides internal-first billing building blocks for services that need usage-based and subscription billing without coupling to a specific provider. It complements APF Payments (provider-facing) with portable primitives you can use regardless of Stripe/Aiydan/etc.
+
+## What you get
+
+- Usage ingestion with idempotency (UsageEvent)
+- Windowed usage aggregation (UsageAggregate) — daily baseline
+- Plan and entitlements registry (Plan, PlanEntitlement)
+- Tenant subscriptions (Subscription)
+- Price catalog for fixed/usage items (Price)
+- Invoice and line items (Invoice, InvoiceLine)
+- A small `BillingService` to record usage, aggregate, and generate monthly invoices
+- Optional provider sync hook to mirror internal invoices/lines to your payment provider
+
+## Data model (SQL)
+
+Tables (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, provider_invoice_id, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+See `src/svc_infra/billing/models.py` for full definitions.
+
+## Quick start (Python)
+
+```python
+from datetime import datetime, timezone
+from sqlalchemy.orm import Session
+from svc_infra.billing import BillingService
+
+# session: SQLAlchemy Session (sync) targeting your DB
+bs = BillingService(session=session, tenant_id="t_123")
+
+# 1) Record usage (idempotent by (tenant, metric, idempotency_key))
+evt_id = bs.record_usage(
+    metric="tokens", amount=42,
+    at=datetime.now(tz=timezone.utc),
+    idempotency_key="req-42",
+    metadata={"model": "gpt"},
+)
+
+# 2) Aggregate for a day (baseline v1 granularity)
+bs.aggregate_daily(metric="tokens", day_start=datetime(2025,1,1,tzinfo=timezone.utc))
+
+# 3) Generate a monthly invoice (fixed+usage lines TBD)
+inv_id = bs.generate_monthly_invoice(
+    period_start=datetime(2025,1,1,tzinfo=timezone.utc),
+    period_end=datetime(2025,2,1,tzinfo=timezone.utc),
+    currency="usd",
+)
+```
+
+Optional: pass a provider sync hook if you want to mirror invoices/lines to Stripe/Aiydan:
+
+```python
+from typing import Callable
+from svc_infra.billing.models import Invoice, InvoiceLine
+
+async def sync_to_provider(inv: Invoice, lines: list[InvoiceLine]):
+    # Map internal invoice/lines to provider calls here
+    ...
+
+bs = BillingService(session=session, tenant_id="t_123", provider_sync=sync_to_provider)
+```
+
+### FastAPI router (usage ingestion & aggregates)
+
+Mount the router and start recording usage with idempotency:
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.billing.setup import add_billing
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.errors.handlers import register_error_handlers
+
+app = FastAPI()
+app.add_middleware(IdempotencyMiddleware, store={})
+register_error_handlers(app)
+add_billing(app)  # mounts under /_billing
+
+# POST /_billing/usage  {metric, amount, at?, idempotency_key, metadata?} -> 202 {id}
+# GET  /_billing/usage?metric=tokens -> {items: [{period_start, granularity, metric, total}], next_cursor}
+```
+
+### Quotas (soft/hard limits)
+
+Protect your feature endpoints with a quota dependency based on internal plan entitlements and daily aggregates:
+
+```python
+from fastapi import Depends
+from svc_infra.billing.quotas import require_quota
+
+@app.get("/generate-report", dependencies=[Depends(require_quota("reports", window="day", soft=False))])
+async def generate_report():
+  return {"ok": True}
+```
+
+## Relationship to APF Payments
+
+- APF Payments is provider-facing: customers, intents, methods, products/prices, subscriptions, invoices, usage records via Stripe/Aiydan adapters and HTTP routers.
+- Billing Primitives is provider-agnostic: an internal ledger of usage, plans/entitlements, and invoices that you can keep even if you change providers.
+- You can use both: continue to use APF Payments for card/payments flows, and use Billing to meter custom features and create internal invoices; selectively sync them out later.
+
+## Jobs and webhooks
+
+Billing includes helpers to enqueue and process jobs and emit webhooks:
+
+- Job names:
+  - `billing.aggregate_daily` payload: `{tenant_id, metric, day_start: ISO8601}`
+  - `billing.generate_monthly_invoice` payload: `{tenant_id, period_start: ISO8601, period_end: ISO8601, currency}`
+- Emitted webhook topics:
+  - `billing.usage_aggregated` payload: `{tenant_id, metric, day_start, total}`
+  - `billing.invoice.created` payload: `{tenant_id, invoice_id, period_start, period_end, currency}`
+
+Usage with the built-in queue/scheduler and webhooks outbox:
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.add import add_webhooks
+from svc_infra.webhooks.service import WebhookService
+from svc_infra.db.outbox import InMemoryOutboxStore
+from svc_infra.webhooks.service import InMemoryWebhookSubscriptions
+from svc_infra.billing.jobs import (
+    enqueue_aggregate_daily,
+    enqueue_generate_monthly_invoice,
+    make_billing_job_handler,
+)
+
+# Create queue + scheduler
+queue, scheduler = easy_jobs()
+
+# Setup DB async session factory
+engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+# Setup webhooks (in-memory stores shown here)
+outbox = InMemoryOutboxStore()
+subs = InMemoryWebhookSubscriptions()
+subs.add("billing.usage_aggregated", url="https://example.test/hook", secret="sekrit")
+webhooks = WebhookService(outbox=outbox, subs=subs)
+
+# Worker handler
+handler = make_billing_job_handler(session_factory=SessionLocal, webhooks=webhooks)
+
+# Enqueue example jobs
+from datetime import datetime, timezone
+enqueue_aggregate_daily(queue, tenant_id="t1", metric="tokens", day_start=datetime.now(timezone.utc))
+enqueue_generate_monthly_invoice(
+    queue, tenant_id="t1", period_start=datetime(2025,1,1,tzinfo=timezone.utc), period_end=datetime(2025,2,1,tzinfo=timezone.utc), currency="usd"
+)
+
+# In your worker loop call process_one(queue, handler)
+```
+
+## Roadmap (v1 scope)
+
+- Router: `/_billing` endpoints for usage ingestion (idempotent), aggregate listing, plans/subscriptions read.
+- Quotas: decorator/dependency to enforce per-plan limits (soft/hard, day/month windows).
+- Jobs: integrate aggregation and invoice-generation with the scheduler; emit `billing.*` webhooks. (helpers available in `svc_infra.billing.jobs`) — Implemented.
+- Provider sync: optional mapper to Stripe invoices/payment intents; reuse idempotency.
+- Migrations: author initial Alembic migration for billing tables.
+- Docs: examples for quotas and jobs; admin flows for plans and prices.
+
+## Testing
+
+- See `tests/unit/billing/test_billing_service.py` for usage, aggregation, invoice basics, and idempotency uniqueness.
+- Additions planned: router tests (ingest/list), quotas, job executions, webhook events.
+
+## Security & Tenancy
+
+- All records are tenant-scoped; ensure tenant_id is enforced in your service layer / router dependencies.
+- Protect HTTP endpoints with RBAC permissions (e.g., billing.read, billing.write) if you expose them.
+
+## Observability
+
+Planned metrics (names may evolve):
+- billing_usage_ingest_total
+- billing_aggregate_duration_ms
+- billing_invoice_generated_total
+
+See ADR 0008 for design details.

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.