feat(api): M4.2 — full REST surface + pgx-backed Postgres store
Replaces the M5.1-skeleton handler set with the M4.2 spec from
IMPLEMENTATION_PLAN.md:
Endpoints (authoritative shape in openapi.yaml):
POST /v1/tenants
GET /v1/tenants/{id}
GET /v1/tenants/by-slug/{slug}
POST /v1/tenants/{id}/activate
POST /v1/tenants/{id}/cancel
GET /v1/entitlements?tenant_id=...
GET /v1/catalog
POST /v1/catalog/request
POST /v1/catalog/trial-request
POST /v1/api-keys returns plaintext ONCE
GET /v1/api-keys?tenant_id=...
DELETE /v1/api-keys/{id}
POST /v1/internal/api-keys/verify always 200; valid: bool
POST /v1/audit
GET /v1/audit?{tenant_id,product,actor_id,action,since,until,limit,cursor}
Architecture:
internal/store/store.go Store interface (CRUD + audit + ping)
internal/store/memory.go in-process impl, used when DATABASE_URL
is empty (seed acme tenant, no migrations)
internal/store/postgres.go pgxpool impl against the M4.1 schema
internal/server/server.go router + healthz/readyz
internal/server/{tenants,catalog,apikeys,audit}.go
per-concern handlers (≤250 LoC each)
internal/server/helpers.go writeJSON/writeError/error mapping/log mw
openapi.yaml 3.1 spec; openapi_test.go is the contract gate
API keys:
Plaintext format 'bp_<22-char base64>'. Prefix bp_<8> stored for UI.
Hash is argon2id(salt, time=1, mem=64MB, threads=4, len=32) encoded as
'argon2id|<salt-b64>|<hash-b64>'. Format-tagged so we can rotate
parameters without re-keying. Verify is constant-time.
Store selection:
cmd/server picks Postgres when DATABASE_URL is set, otherwise Memory.
Both implementations are exercised by the same eachStore test harness —
parity is enforced.
Audit:
Every state-changing endpoint emits via s.emitAudit() (fire-and-forget).
audit_log uses ON DELETE SET NULL on tenant_id so forensic history
outlives tenant deletes (per M4.1 schema).
Routing constraint:
Go 1.22 ServeMux can't disambiguate /v1/tenants/{id}/products from
/v1/tenants/by-slug/{slug=products}. Per-tenant subresources moved to
query-param top-level paths: /v1/entitlements?tenant_id=… and
/v1/api-keys?tenant_id=….
Tests:
Every endpoint exercised against both Memory and Postgres via the
eachStore harness. Includes happy paths, validation errors, conflicts,
404s, auto-audit-emit assertion. testcontainers-go for the postgres
harness; gated by -short.
TestOpenAPISpec is the contract gate: every documented operation must
resolve against the router. (kin-openapi v0.138.0.)
Refs: M4.2
This commit is contained in:
@@ -43,28 +43,38 @@ Env vars (override at the shell):
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Returns |
|
||||
Authoritative spec: [`openapi.yaml`](./openapi.yaml). Summary:
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/healthz` | `{"status":"ok"}` — liveness probe |
|
||||
| GET | `/v1/tenants/by-slug/{slug}` | 200 with tenant JSON, 404 if missing |
|
||||
| GET | `/v1/tenants/{id}` | 200 with tenant JSON, 404 if missing |
|
||||
| GET | `/healthz` | Liveness |
|
||||
| GET | `/readyz` | Pings the store |
|
||||
| POST | `/v1/tenants` | Create a tenant |
|
||||
| GET | `/v1/tenants/{id}` | Read by id |
|
||||
| GET | `/v1/tenants/by-slug/{slug}` | Read by slug (portal middleware uses this) |
|
||||
| POST | `/v1/tenants/{id}/activate` | trial → active |
|
||||
| POST | `/v1/tenants/{id}/cancel` | active → frozen |
|
||||
| GET | `/v1/entitlements?tenant_id={id}` | List product entitlements |
|
||||
| GET | `/v1/catalog` | List requestable products |
|
||||
| POST | `/v1/catalog/request` | Customer requests a product (sales follow-up) |
|
||||
| POST | `/v1/catalog/trial-request` | Self-serve 14-day trial |
|
||||
| GET | `/v1/api-keys?tenant_id={id}` | List keys |
|
||||
| POST | `/v1/api-keys` | Create key (plaintext shown once) |
|
||||
| DELETE | `/v1/api-keys/{id}` | Revoke |
|
||||
| POST | `/v1/internal/api-keys/verify` | Used by headless products to validate inbound keys |
|
||||
| POST | `/v1/audit` | Append an audit event |
|
||||
| GET | `/v1/audit` | Query (cursor-paginated) |
|
||||
|
||||
The skeleton's store is in-memory and pre-seeded with one tenant:
|
||||
State-changing endpoints emit audit events automatically. The OpenAPI contract test (`openapi_test.go`) asserts every listed path resolves against the committed spec.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "00000000-0000-0000-0000-000000000001",
|
||||
"slug": "acme",
|
||||
"name": "Acme Inc.",
|
||||
"status": "active",
|
||||
"plan": "professional",
|
||||
"products": ["certifai", "compliance"]
|
||||
}
|
||||
```
|
||||
## Storage
|
||||
|
||||
So `curl http://localhost:8090/v1/tenants/by-slug/acme` works the moment `make dev` is up.
|
||||
The service picks its store based on `DATABASE_URL`:
|
||||
|
||||
The full schema (6 tables: `tenants`, `tenant_projects`, `tenant_products`, `tenant_idp_config`, `api_keys`, `audit_log` — per `PLATFORM_ARCHITECTURE.md §5c`) lives at `migrations/0001_init.up.sql`. The handler-layer in-memory store is still wired in by default; the pgx-backed store + the full REST surface lands in **M4.2**.
|
||||
- **empty** → in-memory store, pre-seeded with the `acme` tenant (`id: 00000000-0000-0000-0000-000000000001`). Useful for portal dev without spinning Postgres.
|
||||
- **set** → pgx-backed Postgres. Run `make migrate-up` against the same DSN first.
|
||||
|
||||
Both implementations pass the same test harness (`internal/server/server_test.go` → `eachStore`).
|
||||
|
||||
## Schema migrations (M4.1)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user