From 89f2b1ed15e29ff044d62507c585d3ae6d8e8d6b Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Mon, 4 May 2026 07:50:54 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20homogenize=20API=20+=20B?= =?UTF-8?q?DD=20env=20docs=20(verifier=20skill=20audit)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First PR shipping after the new ~/.vibe/skills/verifier/ skill went live. Verifier ran on already-merged PRs and flagged 3 BLOCK doc gaps: - /api/healthz (PR #20) — 0 mentions in documentation/ - /api/admin/cache/flush (PR #29) — 0 mentions - BDD_SCHEMA_ISOLATION env var (PR #35) — 0 mentions Adds: - documentation/API.md — system + admin + v1 + v2 endpoint reference, curl examples, response schemas, ADR cross-refs, Swagger UI link - documentation/BDD_TEST_ENV.md — required + optional env vars (BDD_SCHEMA_ISOLATION, FEATURE, GODOG_TAGS, BDD_ENABLE_CLEANUP_LOGS), recommended local commands, 2.85x speedup note Both files use relative links per docs-homogeneity.md checklist. Closes the verifier feedback loop: skill produces actionable findings → findings get fixed in next PR. Demonstrates audit→fix loop on real diffs. --- documentation/API.md | 90 +++++++++++++++++++++++++++++++++++ documentation/BDD_TEST_ENV.md | 89 ++++++++++++++++++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 documentation/API.md create mode 100644 documentation/BDD_TEST_ENV.md diff --git a/documentation/API.md b/documentation/API.md new file mode 100644 index 0000000..e4c9a5c --- /dev/null +++ b/documentation/API.md @@ -0,0 +1,90 @@ +# API endpoints + +Reference document for all HTTP endpoints exposed by `dance-lessons-coach` server. The authoritative source is the swag-generated Swagger UI at `/swagger/index.html` (served by the Go binary). This markdown is the human-readable index, intentionally short — when in doubt, run the server and open Swagger. + +## Conventions + +- All paths under `/api/` (no other prefix is used) +- Versioned API under `/api/v1/` and `/api/v2/` (cf. ADR-0010 v2 feature flag) +- System / Health / Version endpoints at root (`/api/`, no version) +- Admin endpoints under `/api/admin/` (require master admin password header) +- Response Content-Type: `application/json` unless documented otherwise +- Error envelope: `{"error":"","message":""}` (HTTP 4xx/5xx) + +## System endpoints (no auth) + +| Method | Path | Purpose | Cf. | +|---|---|---|---| +| GET | `/api/health` | Liveness check (legacy, returns `{"status":"healthy"}`) | `pkg/server/server.go` | +| GET | `/api/healthz` | **Kubernetes-style** rich health: status / version / uptime_seconds / timestamp | PR #20 — handler with swag `@Router /healthz [get]` | +| GET | `/api/ready` | Readiness check (DB connection + service deps) | `pkg/server/server.go handleReadiness` | +| GET | `/api/version` | Version info (cached 60s, since PR #29) | `pkg/server/server.go handleVersion` | + +`/api/healthz` body schema (`HealthzResponse`): + +```json +{ + "status": "healthy", + "version": "1.4.0", + "uptime_seconds": 1234, + "timestamp": "2026-05-04T08:00:00Z" +} +``` + +Use `/api/healthz` for kubelet liveness probes — richer than `/api/health` and stable. + +## Admin endpoints (require X-Admin-Password header) + +| Method | Path | Purpose | Cf. | +|---|---|---|---| +| POST | `/api/admin/cache/flush` | Flush the entire in-memory cache. Returns `{"flushed":true,"items_flushed":N,"timestamp":"..."}` (200) or `{"error":"unauthorized"}` (401) or `{"error":"cache_disabled"}` (503) | PR #29 — `pkg/server/server.go handleAdminCacheFlush` | + +Auth: header `X-Admin-Password: ` (matches `auth.admin_master_password` in config / `DLC_AUTH_ADMIN_MASTER_PASSWORD` env var). Default `admin123` for local dev — **change in production**. + +## v1 API (auth + greeting) + +Mounted at `/api/v1/...` with the rate-limit middleware (cf. ADR-0022 Phase 1, since PR #22). Cached responses on greet (since PR #29). + +### Auth (`/api/v1/auth/...`) + +| Method | Path | Purpose | +|---|---|---| +| POST | `/api/v1/auth/register` | User registration | +| POST | `/api/v1/auth/login` | Login with username + password, returns JWT | +| POST | `/api/v1/auth/validate` | Validate a JWT token | +| POST | `/api/v1/auth/password-reset/request` | Request password reset (admin-flagged users only) | +| POST | `/api/v1/auth/password-reset/complete` | Complete password reset | + +JWT secret rotation policies: cf. ADR-0021 + JWT secrets endpoints under `/api/v1/admin/jwt/secrets` (admin-only). + +### Greet (`/api/v1/greet/...`) + +| Method | Path | Purpose | +|---|---|---| +| GET | `/api/v1/greet?name=X` | Greeting (cached per name 60s, header `X-Cache: HIT/MISS`) | +| GET | `/api/v1/greet/{name}` | Greeting (path param variant, same caching) | + +### Admin under v1 (`/api/v1/admin/...`) + +JWT secret management endpoints. Cf. swag annotations in handlers + features/jwt/ BDD scenarios for the exact contract. + +## v2 API + +Enabled via `api.v2_enabled` config (cf. ADR-0010 v2 feature flag). + +| Method | Path | Purpose | +|---|---|---| +| POST | `/api/v2/greet` | v2 greeting (JSON body, more validation) | + +## Swagger UI + +Served at `/swagger/index.html` (and `/swagger/doc.json` for the embedded spec). Always reflects what the running binary exposes — when in doubt, prefer Swagger over this markdown. + +## Cross-references + +- [ADR-0002](../adr/0002-chi-router.md) — Chi router choice +- [ADR-0010](../adr/0010-api-v2-feature-flag.md) — v2 feature flag +- [ADR-0013](../adr/0013-openapi-swagger-toolchain.md) — OpenAPI / Swagger toolchain +- [ADR-0018](../adr/0018-user-management-auth-system.md) — User management & auth +- [ADR-0021](../adr/0021-jwt-secret-retention-policy.md) — JWT secret retention +- [ADR-0022](../adr/0022-rate-limiting-cache-strategy.md) — Rate limiting + cache diff --git a/documentation/BDD_TEST_ENV.md b/documentation/BDD_TEST_ENV.md new file mode 100644 index 0000000..9ca476a --- /dev/null +++ b/documentation/BDD_TEST_ENV.md @@ -0,0 +1,89 @@ +# BDD test environment + +Environment variables and tooling specific to running BDD scenarios locally and in CI. Companion to [BDD_GUIDE.md](BDD_GUIDE.md) (which covers the BDD authoring workflow itself). + +## Required env vars (database connection) + +The BDD test server needs a Postgres instance reachable via: + +| Var | Default | Notes | +|---|---|---| +| `DLC_DATABASE_HOST` | `localhost` | Host of the Postgres instance | +| `DLC_DATABASE_PORT` | `5432` | | +| `DLC_DATABASE_USER` | `postgres` | Test-only credentials (NOT production) | +| `DLC_DATABASE_PASSWORD` | `postgres` | | +| `DLC_DATABASE_NAME` | `dance_lessons_coach_bdd_test` | Dedicated test DB | +| `DLC_DATABASE_SSL_MODE` | `disable` | Tests run without TLS | + +Local setup: + +```bash +docker compose up -d # Postgres container +docker exec dance-lessons-coach-postgres psql -U postgres \ + -c "CREATE DATABASE dance_lessons_coach_bdd_test;" # one-time +``` + +In CI: `.gitea/workflows/ci-cd.yaml` provisions a Postgres service container and exports the same vars. + +## Optional env vars + +### `BDD_SCHEMA_ISOLATION` (since [PR #35](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/pulls/35) — T12 stage 2/2) + +| Value | Behaviour | +|---|---| +| `true` | Each test PACKAGE (process) gets its own isolated PostgreSQL schema with migrations. Packages run in **parallel** safely. **~2.85x speedup observed locally.** This is the new default in CI. | +| (unset / `false`) | Falls back to single shared `public` schema with `CleanupDatabase` (TRUNCATE) between scenarios. Forces sequential package execution (`-p 1`). Slower but simpler. | + +Implementation: `pkg/bdd/testserver/server.go Start()` builds a per-package isolated repo via `user.NewPostgresRepositoryFromDSN` (PR #34). `Stop()` drops the schema + closes the per-package pool. + +ADR-0025 documents the isolation strategy ("Implemented" since PR #35). + +### `FEATURE` (per-package selector) + +When set, `pkg/bdd/testserver/server.go shouldEnableV2()` reads it. Used to scope per-feature behaviour (e.g. enable v2 endpoints only when `FEATURE=greet` AND `GODOG_TAGS` includes `@v2`). + +Without `FEATURE` set, falls back to `bdd` (generic). + +### `GODOG_TAGS` (scenario filter) + +Standard godog env var. The default suite excludes flaky/todo/skip/v2 tags: +``` +GODOG_TAGS="~@flaky && ~@todo && ~@skip && ~@v2" +``` + +Scoped runs (e.g. `@critical` only): set `GODOG_TAGS="@critical"` and run. + +### `BDD_ENABLE_CLEANUP_LOGS` (debug) + +Set `=true` to log each scenario's CLEANUP / ISOLATION operation. Useful when debugging flakiness. + +## Recommended local commands + +Run all BDD with isolation (parallel, fast): +```bash +DLC_DATABASE_HOST=localhost DLC_DATABASE_PORT=5432 \ +DLC_DATABASE_USER=postgres DLC_DATABASE_PASSWORD=postgres \ +DLC_DATABASE_NAME=dance_lessons_coach_bdd_test DLC_DATABASE_SSL_MODE=disable \ +BDD_SCHEMA_ISOLATION=true \ +go test ./features/... +``` + +Run one feature with v2 enabled: +```bash +DLC_DATABASE_HOST=... \ +BDD_SCHEMA_ISOLATION=true FEATURE=greet GODOG_TAGS="@v2" \ +go test ./features/greet/... +``` + +Repro CI conditions (sequential, no isolation): +```bash +DLC_DATABASE_HOST=... \ +go test ./features/... -p 1 +``` + +## Cross-references + +- [BDD_GUIDE.md](BDD_GUIDE.md) — authoring scenarios + steps +- [ADR-0008](../adr/0008-bdd-testing.md) — choice of Godog +- [ADR-0024](../adr/0024-bdd-test-organization-and-isolation.md) — feature directory organization +- [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) — isolation strategies (Implemented since PR #35) -- 2.49.1