# DESIGN — F-003 HTTP foundation and request context

## Architecture
All cross-cutting HTTP behavior lives in explicit, readable code:

- `src/infrastructure/logging/logger.ts` — pino factory. JSON only, level from
  `LOG_LEVEL` (default `info`), base field `service`. Accepts an optional writable
  destination so tests can capture output without transports (no magic).
- `src/shared/errors.ts` — `AppError` class (statusCode, code, message) and the
  single `errorEnvelope(statusCode, code, message, requestId)` builder. Envelope v2:
  `{ error: { statusCode, code, message }, requestId }`.
- `src/shared/http-input.ts` — `parseJson(schema, input)` using zod. On failure
  throws `AppError(400, VALIDATION_ERROR)` carrying field-level issues (field paths
  only, never internal state).
- `src/app/build-app.ts` — composition root wires everything explicitly:
  - Fastify `genReqId`: trust incoming `x-request-id` only if it matches
    `^[A-Za-z0-9._-]{1,128}$`; otherwise generate `crypto.randomUUID()`.
  - `onRequest` hook: set `x-request-id` response header, start timer.
  - `onResponse` hook: one JSON log line per request
    `{ requestId, method, url, statusCode, durationMs }`.
  - `setErrorHandler`: map `AppError` and Fastify errors to the envelope. 4xx expose
    their message; >=500 always returns generic `Internal Server Error`. Errors are
    logged with stack server-side, tagged with requestId.
  - `setNotFoundHandler`: envelope with code `NOT_FOUND` + requestId.
- `src/infrastructure/http/server.ts` — startup log lines through the logger.

## Request id policy
- Propagation is opt-in and sanitized; anything suspicious is replaced by a fresh UUID.
- Response header name: `x-request-id`.

## Validation policy
- Validation is explicit per route: call `parseJson(schema, body)` inside the handler.
- No schema decorators, no magic body binding. The F-003 deliverable is the hook
  (helper + envelope integration), exercised by composition tests with a test-only
  route registered on the built app.

## Backward compatibility
- `GET /health` response body unchanged; envelope gains fields (additive).

## Files
| File | Role |
|---|---|
| src/infrastructure/logging/logger.ts | pino factory |
| src/shared/errors.ts | AppError + envelope v2 |
| src/shared/http-input.ts | zod parse helper |
| src/app/build-app.ts | hooks, genReqId, handlers |
| src/infrastructure/http/server.ts | startup logging |
| src/app/tests/http-foundation.test.ts | composition tests (request id, logs, envelope, no leak) |
| src/shared/tests/http-input.test.ts | helper unit tests |

## Risks / mitigations
- Double logging (fastify internal + hooks): keep `logger: false` on Fastify, log only via explicit hooks.
- Header injection through propagated id: strict regex + length cap.
- 5xx leaking internals: handler returns fixed generic message for anything >=500; tests assert absence of thrown message/stack.