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

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,37 @@
+# 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.
+
+## See also
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — request/body/handler timeouts, outbound client timeouts, DB statement timeouts, jobs/webhooks, and graceful shutdown.

svc_infra/docs/rate-limiting.md

@@ -0,0 +1,125 @@
+# 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.
+
+## Related
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — complements rate limits by bounding slow uploads, long handlers, and downstream timeouts.
+
+## 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.

svc_infra/docs/security.md

@@ -0,0 +1,176 @@
+# Security: Configuration & Examples
+
+This guide covers the security primitives built into svc-infra and how to wire them:
+
+> ℹ️ Environment variables for the auth/security helpers are catalogued in [Environment Reference](environment.md).
+
+- Password policy and breach checking
+- Account lockout (exponential backoff)
+- Sessions and refresh tokens (rotation + revocation)
+- JWT key rotation
+- Signed cookies
+- CORS and security headers
+- RBAC and ABAC
+- MFA policy hooks
+
+Module map (examples reference these):
+- `svc_infra.security.lockout` (LockoutConfig, compute_lockout, record_attempt, get_lockout_status)
+- `svc_infra.security.signed_cookies` (sign_cookie, verify_cookie)
+- `svc_infra.security.audit` and `security.audit_service` (hash-chain audit logs)
+- `svc_infra.api.fastapi.auth.gaurd` (password login with lockout checks)
+- `svc_infra.api.fastapi.auth.routers.*` (sessions, oauth routes, etc.)
+- `svc_infra.api.fastapi.auth.settings.get_auth_settings` (cookie + token settings)
+- `svc_infra.api.fastapi.middleware.security_headers` and CORS setup (strict defaults)
+
+## Password policy and breach checking
+- Enforced by validators with a configurable policy.
+- Breach checking uses the HIBP k-Anonymity range API; can be toggled via settings.
+
+Example toggles (pseudo-config):
+- `AUTH_PASSWORD_MIN_LENGTH=12`
+- `AUTH_PASSWORD_REQUIRE_SYMBOL=True`
+- `AUTH_PASSWORD_BREACH_CHECK=True`
+
+## Account lockout
+- Exponential backoff with a max cooldown cap to deter credential stuffing.
+- Attempts tracked by user_id and/or IP hash.
+- Login endpoint blocks with 429 + `Retry-After` during cooldown.
+
+Key API (from `svc_infra.security.lockout`):
+- `LockoutConfig(threshold=5, window_minutes=15, base_cooldown_seconds=30, max_cooldown_seconds=3600)`
+- `compute_lockout(fail_count, cfg)` → `LockoutStatus(locked, next_allowed_at, failure_count)`
+- `record_attempt(session, user_id, ip_hash, success)`
+- `get_lockout_status(session, user_id, ip_hash, cfg)`
+
+Login integration (simplified):
+```python
+from svc_infra.security.lockout import get_lockout_status, record_attempt
+
+# Compute ip_hash from request.client.host
+status = await get_lockout_status(session, user_id=None, ip_hash=ip_hash)
+if status.locked:
+		raise HTTPException(429, headers={"Retry-After": ..})
+
+user = await user_manager.user_db.get_by_email(email)
+if not user:
+		await record_attempt(session, user_id=None, ip_hash=ip_hash, success=False)
+		raise HTTPException(400, "LOGIN_BAD_CREDENTIALS")
+```
+
+## Sessions and refresh tokens
+- Sessions are enumerable and revocable via the sessions router.
+- Refresh tokens are rotated; old tokens are invalidated via a revocation list.
+
+Operational notes:
+- Persist sessions/tokens in a durable DB.
+- Favor short access token TTLs if refresh flow is robust.
+
+## JWT key rotation
+- Primary secret plus `old_secrets` allow seamless rotation.
+- Set environment variables:
+	- `AUTH_JWT__SECRET="..."`
+	- `AUTH_JWT__OLD_SECRETS="old1,old2"`
+
+## Signed cookies
+Module: `svc_infra.security.signed_cookies`
+
+```python
+from svc_infra.security.signed_cookies import sign_cookie, verify_cookie
+
+sig = sign_cookie({"sub": "user-123"}, secret="k1", exp_seconds=3600)
+payload = verify_cookie(sig, secret="k1", old_secrets=["k0"])  # returns dict
+```
+
+## CORS and security headers
+- Strict CORS defaults (deny by default). Provide allowlist entries.
+- Security headers middleware sets common protections (X-Frame-Options, X-Content-Type-Options, etc.).
+
+Use `svc_infra.security.add.add_security` to install the default middlewares on any
+FastAPI app. By default it adds:
+
+- `SecurityHeadersMiddleware` with practical defaults:
+  - **Content-Security-Policy**: Allows same-origin resources, inline styles/scripts, data URI images, and HTTPS images. Blocks external scripts and framing.
+  - **Strict-Transport-Security**: Forces HTTPS with long max-age and subdomain support
+  - **X-Frame-Options**: Blocks framing (DENY)
+  - **X-Content-Type-Options**: Prevents MIME sniffing (nosniff)
+  - **Referrer-Policy**: Limits referrer leakage
+  - **X-XSS-Protection**: Disabled (CSP is the modern protection)
+- A strict `CORSMiddleware` that only enables CORS when origins are provided (via
+  parameters or environment variables such as `CORS_ALLOW_ORIGINS`).
+
+The default CSP policy is:
+```
+default-src 'self';
+script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;
+style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;
+img-src 'self' data: https:;
+connect-src 'self';
+font-src 'self' https://cdn.jsdelivr.net;
+frame-ancestors 'none';
+base-uri 'self';
+form-action 'self'
+```
+
+This works out-of-the-box for most web applications, including FastAPI's built-in documentation (Swagger UI, ReDoc), while maintaining strong security.
+
+The helper also supports optional toggles so you can match the same cookie and
+header configuration that `setup_service_api` uses.
+
+```python
+from fastapi import FastAPI
+
+from svc_infra.security.add import add_security
+
+app = FastAPI()
+
+add_security(
+    app,
+    cors_origins=["https://app.example.com"],
+    headers_overrides={"Content-Security-Policy": "default-src 'self'; script-src 'self'"},  # Stricter CSP
+    install_session_middleware=True,  # adds Starlette's SessionMiddleware
+)
+```
+
+Environment variables (applied when parameters are omitted):
+
+| Variable | Purpose |
+| --- | --- |
+| `CORS_ALLOW_ORIGINS` | Comma-separated CORS origins (e.g. `https://app.example.com, https://admin.example.com`) |
+| `CORS_ALLOW_METHODS` | Allowed HTTP methods (defaults to `*`) |
+| `CORS_ALLOW_HEADERS` | Allowed headers (defaults to `*`) |
+| `CORS_ALLOW_ORIGIN_REGEX` | Regex used when matching origins (ignored if not set) |
+| `CORS_ALLOW_CREDENTIALS` | Toggle credentials support (`true` / `false`) |
+| `SESSION_COOKIE_NAME` | Session cookie name (defaults to `svc_session`) |
+| `SESSION_COOKIE_MAX_AGE_SECONDS` | Max age for the session cookie (defaults to `14400`) |
+| `SESSION_COOKIE_SAMESITE` | SameSite policy (`lax` by default) |
+| `SESSION_COOKIE_SECURE` | Force the session cookie to be HTTPS-only |
+| `SESSION_SECRET` | Secret key for Starlette's SessionMiddleware |
+
+When your service already uses `setup_service_api`, call `add_security` after
+building the parent app if you need additional overrides while keeping the
+defaults intact:
+
+```python
+from svc_infra.api.fastapi.setup import setup_service_api
+from svc_infra.security.add import add_security
+
+app = setup_service_api(...)
+
+add_security(
+    app,
+    headers_overrides={"Strict-Transport-Security": "max-age=63072000; includeSubDomains"},
+    enable_hsts_preload=False,
+)
+```
+
+## RBAC and ABAC
+- RBAC decorators guard endpoints by role/permission.
+- ABAC evaluates resource ownership and attributes (e.g., `owns_resource`).
+
+## MFA policy hooks
+- Policy decides when MFA is required; login returns 401 with `MFA_REQUIRED` and a pre-token when applicable.
+
+## Troubleshooting
+- 429 on login: lockout active. Check `Retry-After` and `FailedAuthAttempt` rows.
+- Token invalid post-refresh: confirm rotation + revocation writes.
+- Cookie verification errors: check signing keys/exp.

svc_infra/docs/tenancy.md

@@ -0,0 +1,35 @@
+# Tenancy model and integration
+
+This framework uses a soft-tenant isolation model by default: tenant_id is a column on tenant-scoped tables, and all queries are filtered by this value. Consumers can later adopt schema-per-tenant or DB-per-tenant strategies; the API surfaces remain compatible.
+
+## How tenant is resolved
+- `resolve_tenant_id(request)` looks up tenant id in this order:
+  1) Global override hook (set via `add_tenancy(app, resolver=...)`)
+  2) Auth identity (user.tenant_id or api_key.tenant_id) when auth is enabled
+  3) `X-Tenant-Id` request header
+  4) `request.state.tenant_id`
+
+Use `TenantId` dependency to require it in routes, and `OptionalTenantId` to access it if present.
+
+## Enforcement in data layer
+- Wrap services with `TenantSqlService` to automatically:
+  - Apply `WHERE model.tenant_id == <tenant>` on list/get/update/delete/search/count.
+  - Inject `tenant_id` upon create when the model has the tenant field.
+
+## Tenant-aware CRUD router
+- When defining a `SqlResource`, set `tenant_field="tenant_id"` to mount a tenant-aware CRUD router. All endpoints will require `TenantId` and enforce scoping.
+
+## Per-tenant rate limits / quotas
+- Global middleware and per-route dependency support tenant-aware policies:
+  - `scope_by_tenant=True` puts requests in independent buckets per tenant.
+  - `limit_resolver(request, tenant_id)` lets you return dynamic limits (e.g., plan-based quotas).
+
+## Export a tenant’s data (SQL)
+- CLI command: `sql export-tenant`
+  - Example:
+    - `python -m svc_infra.cli sql export-tenant items --tenant-id t1 --output out.json`
+  - Flags:
+    - `--tenant-id` (required), `--tenant-field` (default `tenant_id`), `--limit` (optional), `--database-url` (or set `SQL_URL`).
+
+## Migration to other isolation strategies
+- Schema-per-tenant or DB-per-tenant can be layered by adapting the session factory or repository to select the schema/DB based on `tenant_id`. Your application code that relies on `TenantId` and tenant-aware services/routers remains the same.

svc_infra/docs/timeouts-and-resource-limits.md

@@ -0,0 +1,147 @@
+# Timeouts & Resource Limits
+
+This guide covers request/handler timeouts, outbound HTTP client timeouts, database statement timeouts, job/webhook delivery timeouts, and graceful shutdown. It explains defaults, configuration, wiring, and recommended tuning by environment.
+
+## Why timeouts?
+
+- Protects your service from slowloris uploads and hanging requests
+- Limits blast radius of slow downstreams (HTTP, DB, webhooks)
+- Enables predictable backpressure and faster recovery during incidents
+
+## Configuration overview
+
+The library exposes simple environment variables with sensible defaults. Use floats for second values unless noted.
+
+- REQUEST_BODY_TIMEOUT_SECONDS (int)
+  - Default: prod=15, nonprod=30
+  - Purpose: Abort slow request body reads (slowloris defense)
+- REQUEST_TIMEOUT_SECONDS (int)
+  - Default: prod=30, nonprod=15
+  - Purpose: Cap overall handler execution time
+- HTTP_CLIENT_TIMEOUT_SECONDS (float)
+  - Default: 10.0
+  - Purpose: Default timeout for outbound httpx clients created via helpers
+- DB_STATEMENT_TIMEOUT_MS (int)
+  - Default: unset (disabled)
+  - Purpose: Per-transaction statement timeout (Postgres via SET LOCAL)
+- JOB_DEFAULT_TIMEOUT_SECONDS (float)
+  - Default: unset (disabled)
+  - Purpose: Caps per-job handler runtime in the in-process jobs runner
+- WEBHOOK_DELIVERY_TIMEOUT_SECONDS (float)
+  - Default: falls back to HTTP client default (10.0)
+  - Purpose: Timeout for webhook delivery HTTP calls
+- SHUTDOWN_GRACE_PERIOD_SECONDS (float)
+  - Default: prod=20.0, nonprod=5.0
+  - Purpose: Wait time for in-flight requests to drain on shutdown
+
+See ADR-0010 for design rationale: `src/svc_infra/docs/adr/0010-timeouts-and-resource-limits.md`.
+
+## Request/handler timeouts (FastAPI)
+
+Two middlewares enforce timeouts inside your ASGI app:
+
+- BodyReadTimeoutMiddleware
+  - Enforces a per-chunk timeout while reading the incoming request body.
+  - If reads stall beyond the timeout, responds with 408 application/problem+json.
+  - Module: `svc_infra.api.fastapi.middleware.timeout.BodyReadTimeoutMiddleware`
+- HandlerTimeoutMiddleware
+  - Caps overall request handler execution time using asyncio.wait_for.
+  - If exceeded, responds with 504 application/problem+json.
+  - Module: `svc_infra.api.fastapi.middleware.timeout.HandlerTimeoutMiddleware`
+
+Example wiring:
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.middleware.timeout import (
+    BodyReadTimeoutMiddleware,
+    HandlerTimeoutMiddleware,
+)
+
+app = FastAPI()
+
+# Abort slow uploads (slowloris) after 15s in prod / 30s nonprod by default
+app.add_middleware(BodyReadTimeoutMiddleware)  # or timeout_seconds=20
+
+# Cap total handler time (e.g., 30s in prod by default)
+app.add_middleware(HandlerTimeoutMiddleware)  # or timeout_seconds=25
+```
+
+HTTP semantics:
+
+- Body timeout → 408 Request Timeout (Problem+JSON) with fields: type, title, status, detail, instance, trace_id
+- Handler timeout → 504 Gateway Timeout (Problem+JSON) with fields: type, title, status, detail, instance, trace_id
+
+## Outbound HTTP client timeouts (httpx)
+
+Use the provided helpers to create httpx clients with the default timeout (driven by HTTP_CLIENT_TIMEOUT_SECONDS).
+
+- Module: `svc_infra.http.client`
+  - `get_default_timeout_seconds()` → float
+  - `make_timeout(seconds=None) -> httpx.Timeout`
+  - `new_httpx_client(timeout_seconds=None, ...) -> httpx.Client`
+  - `new_async_httpx_client(timeout_seconds=None, ...) -> httpx.AsyncClient`
+
+Error mapping:
+
+- `httpx.TimeoutException` is mapped to 504 Gateway Timeout with Problem+JSON by default when `register_error_handlers(app)` is used.
+  - Module: `svc_infra.api.fastapi.middleware.errors.handlers.register_error_handlers`
+
+## Database statement timeouts (SQLAlchemy / Postgres)
+
+If `DB_STATEMENT_TIMEOUT_MS` is set and Postgres is used, a per-transaction `SET LOCAL statement_timeout = :ms` is executed for sessions yielded by the built-in dependency.
+
+- Module: `svc_infra.api.fastapi.db.sql.session.get_session`
+- Non-Postgres dialects (e.g., SQLite) ignore this gracefully.
+
+## Jobs and webhooks
+
+- Jobs runner
+  - Env: `JOB_DEFAULT_TIMEOUT_SECONDS`
+  - Module: `svc_infra.jobs.worker.process_one` — wraps job handler with `asyncio.wait_for()` when configured.
+- Webhook delivery
+  - Env: `WEBHOOK_DELIVERY_TIMEOUT_SECONDS` (falls back to HTTP client default when unset)
+  - Module: `svc_infra.jobs.builtins.webhook_delivery.make_webhook_handler` — uses `new_async_httpx_client` with derived timeout.
+
+## Graceful shutdown
+
+Install graceful shutdown to wait for in-flight requests (up to a grace period) during application shutdown.
+
+- Module: `svc_infra.api.fastapi.middleware.graceful_shutdown.install_graceful_shutdown`
+- Env: `SHUTDOWN_GRACE_PERIOD_SECONDS` (prod=20.0, nonprod=5.0 by default)
+
+```python
+from svc_infra.api.fastapi.middleware.graceful_shutdown import install_graceful_shutdown
+
+install_graceful_shutdown(app)  # or grace_seconds=30.0
+```
+
+## Tuning recommendations
+
+- Production
+  - REQUEST_BODY_TIMEOUT_SECONDS: 10–20s (shorter for public APIs)
+  - REQUEST_TIMEOUT_SECONDS: 20–30s (align with upstream proxy/gateway timeouts)
+  - HTTP_CLIENT_TIMEOUT_SECONDS: 3–10s (favor quick failover with retries)
+  - DB_STATEMENT_TIMEOUT_MS: set per-route/transaction if queries are constrained
+  - SHUTDOWN_GRACE_PERIOD_SECONDS: 20–60s depending on peak latencies
+- Staging/Dev
+  - Relax timeouts slightly to reduce test flakiness (defaults already reflect this)
+- Gateways/Proxies
+  - Ensure upstream (e.g., NGINX, ALB) timeouts exceed app’s body timeout and are aligned with handler timeout to avoid double timeouts.
+
+## Testing and acceptance
+
+- Unit tests cover body read timeout, handler timeout, outbound timeout mapping, and a smoke check for DB statement timeout.
+- Acceptance tests:
+  - A2-04: slow handler → 504 Problem
+  - A2-05: slow body → 408 Problem or 413 (size) as applicable
+  - A2-06: outbound httpx timeout → 504 Problem
+
+## Troubleshooting
+
+- Seeing 200 instead of 408 for slow uploads under some servers?
+  - Some servers buffer the entire body before invoking the app. The BodyReadTimeoutMiddleware greedily drains with per-chunk timeouts and replays to reliably detect slowloris. Ensure HTTP/1.1 parsing with a streaming-capable server implementation (e.g., uvicorn+httptools) in acceptance tests.
+- Outbound timeouts not mapped to Problem?
+  - Ensure `register_error_handlers(app)` is installed so `httpx.TimeoutException` returns a 504 Problem.
+- Statement timeout ignored on SQLite?
+  - Expected. Non-Postgres dialects skip `SET LOCAL` safely.