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
1.7 KiB
1.7 KiB
Architect — F-003 HTTP foundation and request context
done -> work/artifacts/F-003/architect.md
Deliverables
- specs/F-003-http-foundation/SPEC.md
- specs/F-003-http-foundation/DESIGN.md
- specs/F-003-http-foundation/TASKS.md
- specs/F-003-http-foundation/TESTS.md
Key decisions
- pino for JSON structured logging: Fastify ecosystem standard, fast, boring. Fastify's own logger stays OFF (
logger: false); logging happens through explicit onRequest/onResponse hooks so there is exactly one log line per request and zero hidden log paths. - zod for the input validation hook: explicit
parseJson(schema, body)calls inside handlers. No decorators, no magic binding. F-003 ships the hook; first real consumer is F-005 identity. - request_id policy: propagate incoming
x-request-idonly when it matches^[A-Za-z0-9._-]{1,128}$(header-injection defense); otherwisecrypto.randomUUID(). Response headerx-request-idon every response; error envelopes also embed requestId. - Error envelope v2 (additive):
{ error: { statusCode, code, message }, requestId }. Codes: NOT_FOUND, VALIDATION_ERROR, INTERNAL_ERROR, or upstream Fastify error codes for known 4xx. >=500 always answers the genericInternal Server Error; stack goes to logs tagged with requestId, never to the client. - Logger injection:
buildApp({ logger? })— tests capture logs through an in-memory destination. No transports, no env sniffing in tests.
Boundaries
- Cross-cutting code lives in
sharedandinfrastructure/logging; composition wiring only insrc/app. Modules (health) untouched.
Open risks
- Envelope change touches F-001 test expectations (additive; tests will be updated in build).