Files

rikrdo 41f144d7bd feat(F-003): HTTP foundation with request context and error envelope

- 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

2026-08-14 22:13:28 +02:00

1.6 KiB

Raw Blame History

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

Every response carries request_id (via x-request-id response header; error bodies also embed it).
Every log line for a request carries the same request_id.
Given an invalid request When handled Then the error envelope shape is stable.
Internal stack traces never leak to API responses (5xx message is generic; stack stays server-side in logs).
./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.

1.6 KiB Raw Blame History