hzhang
e706f3d6ef
Replaces the Python v1 (preserved on archive/python-v1 branch).
Stack: Go 1.23 + chi router + sqlx + MySQL 8. Distroless static
container. 12-factor config from env. Embedded SQL migrations.
Schema (internal/db/migrations/001_init.sql):
- topics: 议题 with 4-timestamp lifecycle (signup_open/close +
debate_start/end), visibility (default private), status state machine,
verdict_schema FK
- signups: agent self-enrollment with willing_camps (JSON array of
pro|con|judge), pre_validated audit flag, (topic,agent) unique
- camps: post-allocation lock (one row per topic+camp) — written by
Phase 2D allocator
- rounds + arguments: chronological debate transcript
- verdicts: judge structured output, one per topic, with token-cost
trail for future budgeting
- agent_keys + system_keys: peppered sha256 hashes, never raw
- verdict_schemas: seeded with binary, claim-resolution (for
analyze-intel), policy-recommendation, free-form
Auth (internal/auth):
- AgentAPIKey: real bearer-token middleware against agent_keys;
best-effort last_used_at touch on success
- OIDCBrowser: Phase 2 stub. Dev mode accepts x-dev-bypass header
(constant-time compare); prod 401s with a Phase-4-pending hint.
Real Keycloak JWKS verification lands with the frontend rewrite.
HTTP API (internal/httpapi):
- /api/healthz — db ping + version + uptime
- GET /api/topics — list with status/visibility/limit/offset filters;
anonymous callers see public only
- GET /api/topics/{id} — visibility-gated (private → 404 hide)
- POST /api/topics — create with RFC3339 lifecycle validation
(signup_open < signup_close <= debate_start < debate_end)
- PUT /api/topics/{id}/visibility — dialectic-admin role gate
- POST /api/topics/{id}/signups — agent self-enroll; rejects when
topic.status != signup_open OR outside signup window; idempotent
upsert per (topic, agent)
- GET /api/topics/{id}/signups — list (any authed caller)
Auth chains:
- optionalAuth: try bearer → try oidc → fall through anonymous
(handlers branch on Caller.Kind == ""). Uses captureWriter to demote
inner 401s to "try next" without leaking response bytes.
- requireAnyAuth: chain that 401s if neither succeeds.
- requireAgent: strict bearer-only (signup POST).
Run: `docker compose -f docker-compose.dev.yml up --build`. Migrations
auto-apply on first connect; idempotent on reboot. README documents
env vars, dev bypass usage, agent-key provisioning SQL, and the
Phase 2D/E/3/4/5 roadmap.
go vet clean, gofmt clean, single 11M static binary.
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
# Dialectic.Backend — v2 (Go)
|
|
|
|
Greenfield Go rewrite of the Python v1 backend. Agent-native debate
|
|
platform per [`/home/hzhang/arch/DIALECTIC-V2-DESIGN.md`](../DIALECTIC-V2-DESIGN.md).
|
|
|
|
Python v1 history is preserved on branch `archive/python-v1`.
|
|
|
|
## What's here (Phase 2A + 2B + 2C, 2026-05-23)
|
|
|
|
| Subsystem | Status |
|
|
|-----------|--------|
|
|
| HTTP server (`chi` router) | ✅ |
|
|
| Config from env (`internal/config`) | ✅ |
|
|
| MySQL via `sqlx` + embedded SQL migrations | ✅ |
|
|
| Schema: `topics`, `signups`, `camps`, `rounds`, `arguments`, `verdicts`, `agent_keys`, `system_keys`, `verdict_schemas` | ✅ |
|
|
| Auth middlewares: agent bearer (real), OIDC browser (Phase 2 stub w/ dev bypass) | ✅ |
|
|
| `/api/healthz` | ✅ |
|
|
| `/api/topics` list / get / create / set-visibility | ✅ |
|
|
| `/api/topics/{id}/signups` list / create (agent self-enroll) | ✅ |
|
|
| Orchestration engine (camp allocation, round driver, judge invocation) | ⬜ Phase 2D |
|
|
| SSE live transcripts | ⬜ Phase 2D |
|
|
| Full OIDC + Keycloak JWKS verification | ⬜ Phase 4 |
|
|
| Nginx + CF Origin Cert on server.t3 | ⬜ Phase 2E |
|
|
|
|
## Layout
|
|
|
|
```
|
|
main.go entrypoint (load → wire → serve)
|
|
go.mod
|
|
Dockerfile
|
|
docker-compose.dev.yml backend + mysql for local iteration
|
|
internal/
|
|
config/ 12-factor env loader
|
|
db/
|
|
db.go sqlx + embedded migration runner
|
|
migrations/001_init.sql v2 schema, idempotent
|
|
models/ entity types (sqlx + json tags)
|
|
store/ query layer (per-entity)
|
|
auth/ agent api-key + oidc middlewares
|
|
httpapi/
|
|
routes.go chi router + auth chains
|
|
handlers/ per-endpoint handlers
|
|
```
|
|
|
|
## Run locally
|
|
|
|
```
|
|
docker compose -f docker-compose.dev.yml up --build
|
|
# backend on http://localhost:8090
|
|
curl http://localhost:8090/api/healthz
|
|
```
|
|
|
|
Env vars (see `internal/config/config.go` for the full list):
|
|
|
|
| Var | Default (dev) | Required in prod |
|
|
|-----|---------------|-------------------|
|
|
| `ENV_MODE` | `dev` | must be `prod` |
|
|
| `HTTP_ADDR` | `0.0.0.0:8090` | — |
|
|
| `CORS_ALLOW_ORIGINS` | `*` | concrete list (no `*`) |
|
|
| `DB_HOST/PORT/NAME/USER/PASSWORD` | dev defaults | ✓ password required |
|
|
| `AGENT_API_KEY_PEPPER` | — | ✓ |
|
|
| `OIDC_ISSUER` / `OIDC_CLIENT_ID` | — | ✓ |
|
|
| `OIDC_DEV_BYPASS_TOKEN` | unset | ignored in prod |
|
|
| `SYSTEM_API_KEY` | unset | populate when announce-channel push lands |
|
|
|
|
## Dev bypass for browser routes
|
|
|
|
In `ENV_MODE=dev` with `OIDC_DEV_BYPASS_TOKEN=<token>` set:
|
|
|
|
```
|
|
curl -H "x-dev-bypass: <token>" http://localhost:8090/api/topics
|
|
# attached as user 'dev-operator' with role 'dialectic-admin'
|
|
```
|
|
|
|
In `prod`, this header is ignored regardless of value.
|
|
|
|
## Agent bearer for plugin routes
|
|
|
|
The OpenClaw plugin (`Dialectic.OpenclawPlugin`, Phase 3) calls with:
|
|
|
|
```
|
|
Authorization: Bearer <raw-agent-api-key>
|
|
```
|
|
|
|
The key is hashed with `AGENT_API_KEY_PEPPER` and matched against
|
|
`agent_keys.key_hash`. To provision an agent's key (Phase 3 will add a
|
|
proper `hf user create-dialectic-key` CLI; for now, manual SQL):
|
|
|
|
```sql
|
|
INSERT INTO agent_keys (agent_id, key_hash)
|
|
VALUES ('manager', SHA2(CONCAT('<pepper>:', '<raw>'), 256));
|
|
```
|
|
|
|
## What's next
|
|
|
|
- **Phase 2D**: camp allocation algorithm + round driver + judge
|
|
invocation. Wired to Fabric announce channel (via system-api-key) +
|
|
the Dialectic.OpenclawPlugin's tool for agent argument submission.
|
|
- **Phase 2E**: nginx config + CF Origin Cert + deploy to server.t3.
|
|
- **Phase 3**: Dialectic.OpenclawPlugin — agent-facing tools.
|
|
- **Phase 4**: frontend rewrite (STYLE.md + real Keycloak OIDC + visibility toggle UI).
|
|
- **Phase 5**: end-to-end integration with `analyze-intel` workflow.
|