sharang
4c46d673fb
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
134 lines
7.1 KiB
Markdown
134 lines
7.1 KiB
Markdown
# tenant-registry
|
|
|
|
Multi-tenant glue: orgs, entitlements, API keys, audit.
|
|
|
|
> Part of the **Breakpilot Platform**. For the big picture see [`platform/docs`](https://gitea.meghsakha.com/platform/docs):
|
|
> [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
|
|
> [Infrastructure](https://gitea.meghsakha.com/platform/docs/src/branch/main/INFRASTRUCTURE.md) ·
|
|
> [Product Integration Spec](https://gitea.meghsakha.com/platform/docs/src/branch/main/PRODUCT_INTEGRATION_SPEC.md) ·
|
|
> [Implementation Plan](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
|
|
|
## What this is
|
|
|
|
Multi-tenant glue: orgs, entitlements, API keys, audit. Scaffolded under milestone M4.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
|
|
|
|
**Plane:** Control
|
|
**Owner:** @sharang
|
|
**Status:** pre-alpha
|
|
**Linked milestone:** [M4.1](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
|
|
|
## Run locally
|
|
|
|
```bash
|
|
# Prerequisites: Go 1.25+
|
|
# Dependencies (Keycloak, pg-app) come from the dev stack — see platform/orca-platform/dev.
|
|
|
|
# In one terminal — bring up dev dependencies (in the orca-platform clone):
|
|
cd /path/to/platform/orca-platform && make dev-up
|
|
|
|
# In another — run the service:
|
|
make dev # APP_ENV=dev, listens on :8090 (Keycloak owns :8080 in the dev stack)
|
|
make test # unit tests
|
|
make build # compile to ./bin/tenant-registry
|
|
```
|
|
|
|
Env vars (override at the shell):
|
|
|
|
| Var | Default | Purpose |
|
|
|---|---|---|
|
|
| `APP_ENV` | `dev` | one of `dev`, `stage`, `prod` |
|
|
| `ADDR` | `:8090` | listen address (avoids Keycloak's :8080) |
|
|
| `KEYCLOAK_ISSUER` | `http://localhost:8080/realms/breakpilot-dev` | OIDC issuer URL |
|
|
| `DATABASE_URL` | empty (in-memory store in skeleton) | Postgres DSN, wired up in the M4.1 schema PR |
|
|
|
|
## Endpoints
|
|
|
|
Authoritative spec: [`openapi.yaml`](./openapi.yaml). Summary:
|
|
|
|
| Method | Path | Purpose |
|
|
|---|---|---|
|
|
| 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) |
|
|
|
|
State-changing endpoints emit audit events automatically. The OpenAPI contract test (`openapi_test.go`) asserts every listed path resolves against the committed spec.
|
|
|
|
## Storage
|
|
|
|
The service picks its store based on `DATABASE_URL`:
|
|
|
|
- **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)
|
|
|
|
```bash
|
|
# Apply all pending migrations against the dev Postgres (assumes
|
|
# `make dev-up` in platform/orca-platform is running):
|
|
make migrate-up
|
|
|
|
# Inspect current version:
|
|
make migrate-version
|
|
|
|
# Roll back the most recent migration:
|
|
make migrate-down
|
|
|
|
# Wipe everything (DESTRUCTIVE — only safe against a dev DB):
|
|
make migrate-down-all
|
|
|
|
# Create the next pair of empty migration files:
|
|
make migrate-create NAME=add_team_table
|
|
```
|
|
|
|
Migrations are embedded into both `cmd/server` and `cmd/migrate` via `migrations/embed.go`. In production, `cmd/migrate` ships as an Orca init container so the schema is applied before the API server starts (`IMPLEMENTATION_PLAN.md §1.7`: migrations are forward-only and run as an init container before the service).
|
|
|
|
The migrations package ships three integration tests (require Docker):
|
|
|
|
| Test | What it asserts |
|
|
|---|---|
|
|
| `TestMigrate_upDownRoundTrip` | up → all 6 tables + 4 enums exist; down → schema empty; up again succeeds |
|
|
| `TestSeed_canInsertAndQuery` | end-to-end insert across all 6 tables, FK cascade behaviour, `audit_log` SET-NULL on tenant delete |
|
|
| `TestSlugConstraint` | tenant slug regex enforced (rejects too-short / leading dash / uppercase / underscore) |
|
|
|
|
Run them with `make test`. Use `make test-short` in environments without Docker.
|
|
|
|
## Deployment
|
|
|
|
| Env | URL | How |
|
|
|---|---|---|
|
|
| dev | `http://localhost:8090` | `make dev` |
|
|
| stage | `https://tenant-registry.stage.breakpilot.com` | auto on merge to `main` |
|
|
| prod | `https://tenant-registry.breakpilot.com` | manual: tag `vX.Y.Z` + sign-off |
|
|
|
|
Rollback: `orca rollout undo tenant-registry --env={{env}}`.
|
|
|
|
## Observability
|
|
|
|
- Traces, logs, metrics: [SigNoz](https://signoz.meghsakha.com) — service name `tenant-registry`
|
|
- Audit events: Tenant Registry `/audit` (Retraced-shape schema)
|
|
- On-call: `oncall@breakpilot.com` · runbook at `platform/docs/runbooks/tenant-registry.md`
|
|
|
|
## Contributing
|
|
|
|
See [`CONTRIBUTING.md`](./CONTRIBUTING.md). TL;DR: branch from main, open a PR, 1 review + green CI, squash-merge.
|
|
|
|
## License
|
|
|
|
Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See [`LICENSE`](./LICENSE).
|