41f144d7bd
- request_id generated or sanitized-propagated on every request (x-request-id)
- structured JSON logging (pino), one correlated line per request, injectable logger
- error envelope v2 { error: { statusCode, code, message, details? }, requestId }
- 5xx messages always generic; stack traces stay in server logs only
- explicit parseJson (zod) input validation hook at the API layer
- README HTTP contract section; deps justified in spec/tech.md
- all gates approved; verify.sh green
38 lines
1.6 KiB
Markdown
38 lines
1.6 KiB
Markdown
# SPEC — F-003 HTTP foundation and request context
|
|
|
|
## Problem
|
|
Every request needs identity, structured logs and predictable errors. Today the app
|
|
answers with ad-hoc console logging potential, no request correlation id, and an
|
|
error envelope without request context.
|
|
|
|
## Goal
|
|
request_id everywhere, JSON logs, one error envelope, no magic.
|
|
|
|
## Scope IN
|
|
- request_id generated or propagated on every request
|
|
- Structured JSON logging with request_id
|
|
- Single error response envelope (v2: adds stable `code` + `requestId`)
|
|
- Input validation hook on API layer (foundation helper, explicit usage)
|
|
|
|
## Scope OUT
|
|
- No tracing backend
|
|
- No metrics backend
|
|
- No production endpoints that consume validation yet (first consumer: F-005 identity)
|
|
|
|
## Acceptance criteria
|
|
1. Every response carries `request_id` (via `x-request-id` response header; error bodies also embed it).
|
|
2. Every log line for a request carries the same request_id.
|
|
3. Given an invalid request When handled Then the error envelope shape is stable.
|
|
4. Internal stack traces never leak to API responses (5xx message is generic; stack stays server-side in logs).
|
|
5. `./scripts/verify.sh` green.
|
|
|
|
## Non-functional
|
|
- JSON-only logs (no pretty printers in runtime).
|
|
- Incoming `x-request-id` must be sanitized before reuse (length/charset limits).
|
|
- No new framework magic: logging hooks and error handler are explicit code in the composition root.
|
|
|
|
## Dependencies added
|
|
- pino (JSON structured logging; Fastify ecosystem standard)
|
|
- zod (explicit input validation; no decorators/annotations magic)
|
|
Justification goes to `spec/tech.md`.
|