feat: multi-worker uvicorn with shared rate-limit backend (#68)

[bk86a]

Summary

Implements #68: multi-worker uvicorn behind a shared rate-limit backend.

• New env vars: PC2NUTS_WORKERS (default 1), PC2NUTS_RATE_LIMIT_STORAGE_URI (default unset).
• Startup hard-fails if WORKERS > 1 without a storage URI configured (Pydantic model validator) — prevents silent per-IP rate-limit cap loosening.
• slowapi in_memory_fallback_enabled=True handles transient backend outages with per-process MemoryStorage fallback and exponential-backoff re-probing — once-WARNING-per-outage, INFO on recovery.
• Default behaviour (single worker, in-memory) is byte-for-byte unchanged: when neither env var is set, the Limiter is constructed exactly as before.

Spec: docs/superpowers/specs/2026-05-01-multi-worker-uvicorn-design.md
Plan: docs/superpowers/plans/2026-05-01-multi-worker-uvicorn.md

Acceptance criteria from #68

• Dockerfile updated to launch N workers via PC2NUTS_WORKERS (shell-form CMD with exec uvicorn ... --workers ${PC2NUTS_WORKERS:-1})
• Rate-limit behaviour with N workers documented in README.md (new "Multi-worker deployment" subsection under ## Configuration)
• Memory usage measured against the container's allocated memory — operational follow-up post-deploy
• Performance baseline re-run; docs/performance.md updated — operational follow-up post-deploy

Test plan

Automated (passing on this branch)

• Existing rate-limit tests still pass (single-worker default branch is byte-for-byte unchanged: 178 passed)
• tests/test_config.py::TestWorkersValidator proves the validator fires for WORKERS>1 + no URI (4 tests covering the truth table including empty-string aliasing)
• tests/test_limiter.py::TestLimiterStorageSelection proves the storage URI is honoured and fallback flag is set
• Docker smoke-test confirmed locally: build OK, single-worker startup OK, PC2NUTS_WORKERS=2 without storage URI fails immediately with the validator's error message naming both env vars

Pre-merge manual (operational)

• Deploy this branch image to the target hosting environment with PC2NUTS_WORKERS=2-4 and a real Redis configured via PC2NUTS_RATE_LIMIT_STORAGE_URI
• Confirm /health returns 200 from all workers
• Fire >120 requests in a minute from a single anonymous client; confirm the 120/minute cap is observed across workers (i.e. shared Redis storage works)
• Fire requests with a valid trusted-token bearer; confirm bypass still works (exempt_when=is_trusted_request runs before the storage call)
• Briefly take Redis offline mid-traffic; confirm one WARNING log line, traffic continues to be served (fallback active), no 5xx burst
• Bring Redis back; confirm one INFO "Rate limit storage recovered" line within ~30 s

Post-merge operational

• Re-run perf baseline (scripts/perf_test.sh) and update docs/performance.md with the new RPS at the chosen worker count
• Document measured per-worker resident-set size and confirm headroom against the container memory cap

Notes

• Final review caught one supply-chain issue (commit d0baaeb): the initial requirements.txt declaration slowapi[redis]>=0.1.9,<1 resolves to redis<4 (slowapi 0.1.9's stale extra constraint), conflicting with the redis==7.4.0 lock pin. Switched to limits[redis]>=2.3 which exposes the modern redis>3,<8 constraint.
• Spec was simplified mid-implementation when slowapi 0.1.9 turned out to ship the fail-degraded behaviour we'd designed (in_memory_fallback_enabled=True); a custom _FailDegradedStorage wrapper class was dropped from the design — see commit 7cf2d00.

🤖 Generated with Claude Code