📝 docs: homogenize API + BDD env docs (verifier skill audit) #36
90
documentation/API.md
Normal file
90
documentation/API.md
Normal file
@@ -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/<resource>` and `/api/v2/<resource>` (cf. ADR-0010 v2 feature flag)
|
||||
- System / Health / Version endpoints at root (`/api/<endpoint>`, no version)
|
||||
- Admin endpoints under `/api/admin/<action>` (require master admin password header)
|
||||
- Response Content-Type: `application/json` unless documented otherwise
|
||||
- Error envelope: `{"error":"<code>","message":"<text>"}` (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: <master-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
|
||||
89
documentation/BDD_TEST_ENV.md
Normal file
89
documentation/BDD_TEST_ENV.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user