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

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/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.

svc_infra/docs/jobs.md

@@ -0,0 +1,67 @@
+# Background Jobs & Scheduling
+
+This module provides a lightweight JobQueue abstraction with a Redis backend for production and in-memory implementations for local/tests. A simple interval scheduler and CLI runner are included.
+
+> ℹ️ Job-related environment variables are documented in [Environment Reference](environment.md).
+
+## Quickstart
+
+- Initialize in app code:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+queue, scheduler = easy_jobs()  # uses JOBS_DRIVER=memory|redis
+```
+
+- Enqueue a job:
+
+```python
+job = queue.enqueue("send_email", {"to": "user@example.com"})
+```
+
+- Process one job (async):
+
+```python
+from svc_infra.jobs.worker import process_one
+await process_one(queue, handler)
+```
+
+- Run the CLI runner:
+
+```bash
+svc-infra jobs run
+```
+
+## Redis Backend
+
+Set environment variables:
+- JOBS_DRIVER=redis
+- REDIS_URL=redis://localhost:6379/0
+
+Features:
+- Visibility timeout during processing
+- Exponential backoff on failures (base backoff_seconds * attempts)
+- DLQ after max_attempts
+
+## Scheduler
+
+An interval-based scheduler runs async callables. You can define tasks via environment JSON:
+
+- JOBS_SCHEDULE_JSON:
+
+```json
+[
+  {"name": "ping", "interval_seconds": 60, "target": "myapp.tasks:ping"}
+]
+```
+
+The `target` must be an import path of the form `module:function`. Sync functions are wrapped.
+
+## Testing
+
+- In-memory queue and scheduler enable fast, deterministic tests.
+- Redis tests use `fakeredis` and cover enqueue/reserve/ack/fail and DLQ path.
+
+## Next
+
+- Add metrics, Redis Lua for atomic multi-ops, SQL-backed queue, distributed scheduler.

svc_infra/docs/observability.md

@@ -0,0 +1,16 @@
+# Observability guide
+
+`svc_infra.obs` adds Prometheus metrics, OpenTelemetry instrumentation, and a CLI to spin up Grafana dashboards.
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(name="Billing", release="1.2.3")  # ENABLE_OBS toggles middleware
+```
+
+### Environment
+
+- `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS` – FastAPI bootstrap toggles for metrics exposure. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】
+- `SVC_INFRA_DISABLE_PROMETHEUS` – disable the ASGI middleware entirely (used by tests/sidecars). 【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】
+- `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE` – tune the Grafana dashboards generated by the CLI. 【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
+- Grafana Cloud support looks for `GRAFANA_CLOUD_URL`, `GRAFANA_CLOUD_TOKEN`, `GRAFANA_CLOUD_PROM_URL`, `GRAFANA_CLOUD_PROM_USERNAME`, `GRAFANA_CLOUD_RW_TOKEN`. 【F:src/svc_infra/obs/README.md†L37-L119】

svc_infra/docs/ops.md

@@ -0,0 +1,33 @@
+# SLOs & Ops
+
+This guide explains how to use svc-infra’s probes, circuit breaker, and metrics for SLOs.
+
+## Probes
+
+- `add_probes(app, prefix="/_ops")` exposes:
+  - `GET /_ops/live` — liveness
+  - `GET /_ops/ready` — readiness
+  - `GET /_ops/startup` — startup
+
+## Circuit breaker (placeholder)
+
+- `circuit_breaker_dependency()` returns a dependency that returns 503 when `CIRCUIT_OPEN` is truthy.
+- Use it per-route: `@app.get("/x", dependencies=[Depends(circuit_breaker_dependency())])`.
+
+## Metrics and route classification
+
+- `add_observability(app, ...)` enables Prometheus metrics and optional DB pool metrics.
+- You can pass an optional `route_classifier(base_path, method) -> class` callable. When provided, the metrics middleware encodes the resolved route label as `"{base}|{class}"`. Dashboards can split this label to filter public/internal/admin routes.
+
+## Dashboards
+
+- A minimal Grafana dashboard JSON is provided at `src/svc_infra/obs/grafana/dashboards/http-overview.json` (import into Grafana).
+- It shows:
+  - Success rate over 5 minutes
+  - p99 latency
+  - Top routes by 5xx rate
+
+## Defaults & environment
+
+- Prometheus middleware is enabled unless `SVC_INFRA_DISABLE_PROMETHEUS=1`.
+- Observability settings: `METRICS_ENABLED`, `METRICS_PATH`, and optional histogram buckets.

svc_infra/docs/rate-limiting.md

@@ -0,0 +1,121 @@
+# Rate Limiting & Abuse Protection
+
+This guide shows how to enable and tune the built-in rate limiter and request-size guard, and how to hook simple metrics for abuse detection.
+
+## Features
+
+- Global middleware-based rate limiting with standard headers
+- Per-route dependency for fine-grained limits
+- 429 responses include `Retry-After`
+- Pluggable store interface (in-memory provided; Redis store available)
+- Request size limit middleware returning 413
+- Metrics hooks for rate-limiting events and suspect payloads
+
+## Global middleware
+
+```python
+from svc_infra.api.fastapi.middleware.ratelimit import SimpleRateLimitMiddleware
+
+app.add_middleware(
+    SimpleRateLimitMiddleware,
+    limit=120,   # requests
+    window=60,   # seconds
+    key_fn=lambda r: r.headers.get("X-API-Key") or r.client.host,
+)
+```
+
+Responses include headers:
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset` (epoch seconds)
+
+When exceeded, responses are 429 with `Retry-After` and the same headers.
+
+Advanced options:
+- `scope_by_tenant=True` to automatically include tenant id in the key if tenancy is configured.
+- `limit_resolver=request -> int | None` to override the limit dynamically per request (e.g., per-plan quotas).
+
+## Per-route dependency
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.dependencies.ratelimit import rate_limiter
+
+limiter = rate_limiter(limit=10, window=60, key_fn=lambda r: r.client.host)
+
+@app.get("/resource", dependencies=[Depends(limiter)])
+def get_resource():
+    return {"ok": True}
+```
+
+The dependency supports the same options as the middleware: `scope_by_tenant`, `limit_resolver`, and a custom `store`.
+
+## Store interface
+
+The limiter uses a store abstraction so you can inject Redis or other backends.
+
+- Default: `InMemoryRateLimitStore` (best-effort, single-process)
+- Interface: `RateLimitStore` with `incr(key, window) -> (count, limit, resetEpoch)`
+
+### Redis store
+
+Use `RedisRateLimitStore` for multi-instance deployments. It implements a fixed-window counter
+with atomic increments and sets expiry to the end of the window.
+
+```python
+import redis
+from svc_infra.api.fastapi.middleware.ratelimit_store import RedisRateLimitStore
+from svc_infra.api.fastapi.middleware.ratelimit import SimpleRateLimitMiddleware
+
+r = redis.Redis.from_url("redis://localhost:6379/0")
+store = RedisRateLimitStore(r, limit=120, prefix="rl")
+
+app.add_middleware(SimpleRateLimitMiddleware, limit=120, window=60, store=store)
+```
+
+Notes:
+- Fixed-window counters are simple and usually sufficient. For smoother limits, consider
+  sliding window or token bucket in a future iteration.
+- Use a namespace/prefix per environment/tenant if needed.
+
+## Request size guard
+
+```python
+from svc_infra.api.fastapi.middleware.request_size_limit import RequestSizeLimitMiddleware
+
+app.add_middleware(RequestSizeLimitMiddleware, max_bytes=1_000_000)
+```
+
+- Returns 413 with a Problem+JSON-like structure when `Content-Length` exceeds `max_bytes`.
+
+## Metrics hooks
+
+Hooks live in `svc_infra.obs.metrics` and are no-ops by default. Assign them to log or emit metrics.
+
+```python
+import logging
+import svc_infra.obs.metrics as metrics
+
+logger = logging.getLogger(__name__)
+
+metrics.on_rate_limit_exceeded = lambda key, limit, retry: logger.warning(
+    "rate_limited", extra={"key": key, "limit": limit, "retry_after": retry}
+)
+
+metrics.on_suspect_payload = lambda path, size: logger.warning(
+    "suspect_payload", extra={"path": path, "size": size}
+)
+```
+
+## Tuning tips
+
+- Prefer API key or user ID for `key_fn`; fall back to IP if unauthenticated.
+- Keep windows small (e.g., 60s); layer multiple limits when needed.
+- For distributed deployments, use `RedisRateLimitStore` for atomic increments.
+- Consider separate limits for read vs write routes.
+- Combine with request size limits and auth lockout for layered defense.
+
+## Testing
+
+- Use `-m ratelimit` to select rate-limiting tests.
+- `-m security` also includes these in this repo by default.

svc_infra/docs/repo-review.md

@@ -0,0 +1,48 @@
+# svc-infra Integration Review
+
+## Executive Summary
+- `setup_service_api` remains the high-level entry point for API construction. It auto-wires common middleware (request IDs, error handling, idempotency, rate limiting) and OpenAPI customisation so downstream services only supply router packages and metadata. 【F:src/svc_infra/api/fastapi/setup.py†L1-L187】
+- Auth, SQL, jobs, cache, and observability still expose single-call helpers (`add_auth_users`, `add_sql_db`/`setup_sql`, `easy_jobs`, `init_cache`, `add_observability`) that hide wiring details while keeping flags and dependency overrides for advanced scenarios. 【F:src/svc_infra/api/fastapi/auth/add.py†L27-L329】【F:src/svc_infra/api/fastapi/db/sql/add.py†L1-L118】【F:src/svc_infra/jobs/easy.py†L1-L28】【F:src/svc_infra/cache/__init__.py†L1-L29】【F:src/svc_infra/obs/add.py†L1-L68】
+- Security primitives (lockout, session rotation, RBAC/ABAC, audit chain) are packaged as small composable functions and documented patterns, making them easy to reuse outside FastAPI while still integrating with the default auth routers. 【F:src/svc_infra/security/lockout.py†L1-L96】【F:src/svc_infra/security/session.py†L1-L98】【F:src/svc_infra/security/permissions.py†L1-L148】【F:src/svc_infra/security/audit_service.py†L1-L73】【F:docs/security.md†L1-L96】
+- Webhook utilities provide signature verification, a subscription service, and a default router, but they do not yet follow the same add-helper pattern (there is no `add_webhooks(app, ...)` or env-driven persistence wiring). This is the primary deviation from the established DX story. 【F:src/svc_infra/webhooks/fastapi.py†L1-L37】【F:src/svc_infra/webhooks/service.py†L1-L45】【F:src/svc_infra/webhooks/router.py†L1-L55】【F:docs/webhooks.md†L1-L59】
+
+## Detailed Findings
+
+### API bootstrap and middleware
+- `setup_service_api` builds a parent app and any versioned child apps, runs the OpenAPI mutation pipeline, registers default routers, and attaches middleware without extra code in downstream projects. 【F:src/svc_infra/api/fastapi/setup.py†L1-L187】
+- Scoped docs helpers automatically group endpoints when `add_auth_users` or versioned routers are mounted, so projects get organised API docs with minimal configuration. 【F:src/svc_infra/api/fastapi/auth/add.py†L269-L329】
+- Idempotency and optimistic locking remain opt-in via middleware or dependencies with clear docs; defaults are safe for local use and can be swapped for Redis-backed stores. 【F:docs/idempotency.md†L1-L110】
+
+### Authentication and security
+- `add_auth_users` continues to be the main integration surface. It mounts routers based on flags, configures session middleware from env, and exposes API-key plus OAuth support as toggles. Projects can override policy objects or provider models if needed, preserving flexibility. 【F:src/svc_infra/api/fastapi/auth/add.py†L27-L329】
+- Runtime security helpers (principal resolution, `RequireRoles`, `RequireScopes`, `RequirePermission`, ABAC predicates) make it straightforward to guard routes consistently with the dual routers that enforce doc security defaults. 【F:src/svc_infra/api/fastapi/auth/security.py†L1-L146】【F:src/svc_infra/api/fastapi/dual/protected.py†L1-L74】【F:src/svc_infra/security/permissions.py†L1-L148】
+- Low-level primitives (lockout, refresh token rotation, audit chain) remain framework agnostic so other stacks can reuse them. Documentation in `docs/security.md` is aligned with the code and offers wiring recipes. 【F:src/svc_infra/security/lockout.py†L1-L96】【F:src/svc_infra/security/session.py†L1-L98】【F:src/svc_infra/security/audit_service.py†L1-L73】【F:docs/security.md†L1-L96】
+- Recommendation: add a security bundle similar to `setup_sql` that can register `SecurityHeadersMiddleware` and strict CORS when FastAPI is not created via `setup_service_api`. 【F:src/svc_infra/security/headers.py†L1-L35】
+
+### Data and jobs
+- SQL helpers offer both granular (`add_sql_db`, `add_sql_resources`) and bundled (`setup_sql`) flows. They guard against duplicate setup and generate CRUD schemas when not provided, keeping the quick-start feel while allowing custom services. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L1-L118】
+- Jobs expose `easy_jobs()` that switches between memory and Redis based on env, matching the pick-style ergonomics used in logging. Documentation explains scheduler tasks and the CLI runner. 【F:src/svc_infra/jobs/easy.py†L1-L28】【F:docs/jobs.md†L1-L65】
+- Cache decorators export both `cache_read` and the friendlier aliases (`cached`, `mutates`) so consumers can adopt them incrementally. 【F:src/svc_infra/cache/__init__.py†L1-L29】
+
+### Observability
+- `add_observability` lazily imports instrumentation, respects env flags, and returns a shutdown no-op to keep signature compatibility. It tolerates missing dependencies to avoid burdening projects that do not enable metrics. 【F:src/svc_infra/obs/add.py†L1-L68】
+- Grafana and Prometheus templates are packaged separately, but the code path aligns with the simple toggle approach used elsewhere.
+
+### Webhooks and outbox
+- Signature utilities (`require_signature`, `verify_any`) and service abstractions (`WebhookService`, `InMemoryWebhookSubscriptions`) follow the composable style, and docs describe usage alongside the shared job and outbox infrastructure. 【F:src/svc_infra/webhooks/fastapi.py†L1-L37】【F:src/svc_infra/webhooks/service.py†L1-L45】【F:docs/webhooks.md†L1-L59】
+- Gaps relative to the rest of the repo:
+  - Router dependencies always create new in-memory stores, so deployments must override dependencies manually. Providing an `add_webhooks(app, store=..., subs=...)` helper that honours env (for example `REDIS_URL`) would mirror `add_sql_db` and `add_observability`. 【F:src/svc_infra/webhooks/router.py†L1-L55】
+  - No convenience function registers the router or scheduler tick automatically; consumers must read docs to wire `make_outbox_tick` and queue processors. A top-level helper such as `setup_webhooks(app, outbox=None, inbox=None)` could bundle router inclusion and scheduler guidance.
+
+### Documentation and DX consistency
+- Feature guides (security, jobs, webhooks, idempotency) contain quickstart snippets that mirror the API surface, reinforcing the ease-of-setup story. 【F:docs/security.md†L1-L96】【F:docs/jobs.md†L1-L65】【F:docs/webhooks.md†L1-L59】【F:docs/idempotency.md†L1-L110】
+- README remains empty; adding a high-level index pointing to these guides would help teams discover the single-call helpers faster. 【F:README.md†L1-L4】
+- Consider adding a matrix listing which environment variables drive each helper (`SQL_URL`, `REDIS_URL`, `METRICS_PATH`, `AUTH_*`) to highlight parity across modules.
+
+## Actionable Suggestions
+1. **Webhook setup helper** — provide `add_webhooks` or `setup_webhooks` to mount the router, accept dependency overrides, and optionally wire scheduler tasks. Default to env-driven outbox or inbox selection to match other modules. 【F:src/svc_infra/webhooks/router.py†L1-L55】
+2. **Security bundle** — offer a helper that installs `SecurityHeadersMiddleware`, strict CORS, and optional signed-cookie settings for apps that bypass `setup_service_api`. This keeps manual FastAPI apps aligned with the default hardening posture. 【F:src/svc_infra/security/headers.py†L1-L35】
+3. **Documentation index** — populate `README.md` with links to the feature guides and highlight key add-style helpers so new projects immediately see the plug-and-play building blocks. 【F:README.md†L1-L4】
+4. **Environment reference** — add a doc or table enumerating env vars consumed by helpers (SQL_URL, REDIS_URL, METRICS_PATH, AUTH_*), emphasising how swapping values maintains flexibility across deployments.
+
+Overall, aside from the webhook ergonomics gap and missing README guidance, the codebase maintains the quick-start plus override pattern highlighted in your sample usage while exposing low-level hooks for teams that need deeper control.