Julien Gautier
2e663e1513
Implements ADR-0012 phase 1, BFF side. The SPA wiring is a
separate phase-2 PR.
Runtime libraries added (production deps):
- nestjs-pino, pino, pino-http structured JSON logging
- nestjs-cls request-scoped context
- @opentelemetry/api / sdk-node / resources / semantic-conventions
- @opentelemetry/exporter-trace-otlp-proto OTLP HTTP/Protobuf
- @opentelemetry/instrumentation-{http,express,nestjs-core,pg,
ioredis,pino} curated, no `auto-instrumentations-
node` mass-import (anti-bricolage)
Dev dep: pino-pretty (gated by NODE_ENV).
Code:
- apps/portal-bff/src/observability/tracing.ts — OTel `NodeSDK`
bootstrap. Documents the load-order constraint inline (must be
the very first import of `main.ts`). Exports nothing — pure
side-effect file.
- apps/portal-bff/src/observability/observability.module.ts —
composes ClsModule (UUID per request stored as `request_id`)
and LoggerModule (pino-pretty in dev / raw JSON in prod,
LOG_LEVEL env-driven, `/health` excluded from auto-logging).
- apps/portal-bff/src/health/{health.controller,health.module}.ts
— `GET /api/health` returning `{status, uptimeSeconds, service,
version}`. Cheap liveness only — no DB / Redis check; that
belongs to a future `/readiness` once dependencies have a
readiness story.
- apps/portal-bff/src/config/check-database-url.ts — fail-fast
validator called from main.ts before NestFactory boots. Catches
the same family of bug that bit pgweb in #63: a literal special
char in POSTGRES_PASSWORD that needs URL-encoding in
DATABASE_URL. Prisma requires a URL string, so we cannot use
discrete CLI flags here — early validation + clear error message
is the v1 mitigation. Six unit tests cover happy path, missing
URL, wrong scheme, encoded special chars, literal `@` in
password, malformed URL.
Wiring:
- main.ts now `import`s `./observability/tracing` as its first
line, calls `assertDatabaseUrl()`, then bootstraps Nest with
`app.useLogger(app.get(Logger))` from nestjs-pino with
`bufferLogs: true` so early-bootstrap lines are not lost.
- app.module.ts imports ObservabilityModule first, then the
PrismaModule, then HealthModule.
- .env.example (BFF and infra/local) document the URL-encoding
constraint on POSTGRES_PASSWORD with the exact char-by-char
encoding table.
Trace ↔ log correlation is automatic via
`@opentelemetry/instrumentation-pino`: every Pino record gets
`trace_id` / `span_id` injected from the active OTel context.
No CLS gymnastics needed for that specific concern.
ADR-0012 §Confirmation rewritten to clearly distinguish what
landed in this PR (phase 1) from what is wired as the
corresponding feature ADRs ship (CLS keys for session/user/
audience, LOG_USER_ID_SALT, redact list, custom spans, SPA-side
SDK, full integration tests, prod Collector config).
Verified locally:
- pnpm exec nx run-many -t lint test build → 8 projects green,
4 test suites for portal-bff, 9 unit tests pass.
- `pnpm nx serve portal-bff` boots, `curl /api/health` returns
the expected JSON; logs are pretty-printed JSON one-liners on
stdout in dev.
- `pnpm audit --audit-level=moderate` reports 0 vulnerabilities.
36 lines
1.2 KiB
Bash
36 lines
1.2 KiB
Bash
# Local-dev secrets and ports for `infra/local/dev.compose.yml`.
|
|
# Copy to `.env` (which is git-ignored) and adjust as needed.
|
|
#
|
|
# cp .env.example .env
|
|
# $EDITOR .env
|
|
|
|
# ---------------------------------------------------------------- Postgres
|
|
# `POSTGRES_PASSWORD` is mandatory — the compose refuses to boot
|
|
# without it.
|
|
#
|
|
# Picking a password — keep it URL-safe in dev. The BFF reads its
|
|
# Postgres URL via `DATABASE_URL` and Prisma demands the URL form;
|
|
# any `@`, `#`, `:`, `/`, `?`, `%`, `&`, `=`, `+`, `;` in the
|
|
# password must be URL-encoded in `apps/portal-bff/.env`. Easiest
|
|
# avoided by sticking to alphanumerics + `-_.~` in dev.
|
|
POSTGRES_USER=portal
|
|
POSTGRES_PASSWORD=portal_dev_change_me
|
|
POSTGRES_DB=portal_dev
|
|
POSTGRES_PORT=5432
|
|
|
|
# ---------------------------------------------------------------- Redis
|
|
# Same — mandatory.
|
|
REDIS_PASSWORD=redis_dev_change_me
|
|
REDIS_PORT=6379
|
|
|
|
# ---------------------------------------------------------------- OTel
|
|
OTEL_GRPC_PORT=4317
|
|
OTEL_HTTP_PORT=4318
|
|
|
|
# ---------------------------------------------------------------- Optional viewers
|
|
# Only consumed when the matching Compose profile is activated:
|
|
# --profile dbtools → pgweb
|
|
# --profile observability → Jaeger UI
|
|
PGWEB_PORT=8081
|
|
JAEGER_UI_PORT=16686
|