feat: logging configuration, X-Request-ID, rate-limit headers, SecretStr - #16

Summary

Builds on #15 (merge that first; this PR then shows only its own commits). Closes the logging half of the Known Issues entry No logging configuration or observability, which becomes No metrics, tracing or error tracking.

Logging configuration (logging_config.py, new)

• LOG_LEVEL (default INFO) and LOG_FORMAT (json lines in production by default, text elsewhere; config.log_format() is tested like docs_enabled()).
• Standard-library pipeline from dictConfig: a QueueHandler on the root logger and a QueueListener thread writing to stderr, so a slow destination never blocks the event loop. Python 3.12+ builds the listener from the config; the lifespan runs it as a context manager (Python 3.14) so it starts before the first line and drains on shutdown.
• The queue handler subclass keeps the record intact (the base prepare drops exc_info for pickling, which a same-process listener does not need) and stamps the request id on the task that logged.
• uvicorn's own loggers keep their handlers and do not propagate, so they are untouched.

X-Request-ID (request_id.py, new)

• Pure ASGI middleware, outermost: every response carries the header, 413s and CORS preflights included; expose_headers lets a browser client read it.
• A supplied id is kept when it is 1 to 128 characters of [A-Za-z0-9._-], otherwise a UUIDv7 is generated. The id is in a context variable for the duration of the request and appears on every log line of that request.

X-RateLimit headers

• Limiter(headers_enabled=True): POST /token and POST /api/users/ answer with X-RateLimit-Limit, -Remaining and -Reset (Unix time). slowapi writes them onto a response: Response parameter when the route returns a model, hence the parameter on both routes (verified in slowapi 0.1.10). The custom 429 handler and its Retry-After are unchanged.

SecretStr

• API_KEY and JWT_SECRET_KEY are pydantic SecretStr values; repr is **********. Three use sites call get_secret_value().

Docs: docs/setup.md (table rows, a Logging section), docs/api.md (request id and rate-limit paragraphs), .env.example, AGENTS.md (Logging rule, structure), CHANGELOG.md.

Verification

• New pure tests: tests/test_logging_config.py (formatter fields and exception text, queue handler stamping, dictConfig shape, listener start/stop and delivery with the id), tests/test_request_id.py (generated UUIDv7, echo, replacement of bad ids, contextvar reset after a failing route), test_limiter.py (budget headers on a limited route of a throwaway app), test_config.py (log_format, secret reprs). One database test added in tests/test_rate_limit.py.
• Locally on Python 3.14.7: black --check, flake8, mypy zero errors, 62 pure tests passed with --noconftest; the pipeline smoke-run in both formats shows the id and the traceback in the right field; the header is present on a preflight and on a 413.
• The last commit fixes two assertions that parsed the reset header as an integer (it is a Unix time with a fraction); the earlier commits were pushed before that was caught.

🤖 Generated with Claude Code