3458860c1f
Adds 23 tests across 4 files, taking total broker coverage from
21 → 44 passing in ~2.5s.
Unit tests (no I/O):
- tests/rate-limit.test.ts (6): TokenBucket capacity, refill rate,
no-overflow cap, independent buckets per key, sweep GC.
- tests/metrics.test.ts (5): all 10 series present in /metrics,
counter increment semantics, labelled series produce distinct lines,
gauge set overwrites, Prometheus format well-formed.
- tests/logging.test.ts (5): JSON per line, required fields (ts, level,
component, msg), context merging, level preservation, no plain-text
escape hatches.
Integration tests (spawn real broker subprocesses on random ports):
- tests/integration/health.test.ts (7):
* GET /health 200 + {status, db, version, gitSha, uptime} (healthy DB)
* GET /health 503 + {status:degraded, db:down} (unreachable DB)
* GET /metrics 200 text/plain with all expected series
* GET /nope → 404
* POST /hook/set-status oversized body → 413
* POST /hook/set-status 6th req/min → 429
* Rate limit isolation by (pid, cwd) key
Integration tests use node:child_process (vitest runs under Node, not
Bun — Bun.spawn isn't available). Each suite spawns its own broker
subprocess with a random port + tailored env vars.
Not yet covered (flagged for follow-up):
- WebSocket connection caps (needs seeded mesh + WS client setup)
- WebSocket message-size rejection (ws.maxPayload behavior)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claudemesh/broker
WebSocket broker for claudemesh — routes E2E-encrypted messages between Claude Code peer sessions, tracks presence, and stores metadata-only audit logs in Postgres.
What it is
A standalone Bun-runtime WebSocket server that sits between Claude Code sessions. Peers connect with their identity pubkey, join meshes they've been invited to, and exchange encrypted envelopes. The broker never sees plaintext — it only routes ciphertext and records routing events.
Running locally
# from the repo root
pnpm --filter=@claudemesh/broker dev # watch mode
pnpm --filter=@claudemesh/broker start # production
Required env vars
| Var | Default | Purpose |
|---|---|---|
BROKER_PORT |
7900 |
Single port for HTTP routes + WebSocket upgrade |
DATABASE_URL |
— | Postgres connection string (shared with apps/web) |
STATUS_TTL_SECONDS |
60 |
Flip stuck-"working" peers to idle after this TTL |
HOOK_FRESH_WINDOW_SECONDS |
30 |
How long a hook signal beats JSONL inference |
Routes (single port)
| Path | Protocol | Purpose |
|---|---|---|
/ws |
WebSocket | Authenticated peer connections |
/hook/set-status |
HTTP POST | Claude Code hook scripts report status |
/health |
HTTP GET | Liveness probe |
Depends on
@turbostarter/db— Drizzle/Postgres schema (uses themeshpgSchema)@turbostarter/shared— cross-package utilities
Deployment
Runs as a separate process (not inside Next.js). Intended deployment targets:
Fly.io, Railway, or Coolify on the surfquant VPS. WebSocket server must be
reachable at ic.claudemesh.com.
Status
Scaffold only. The broker logic (status detection, message queue, presence
tracking, hook endpoints) is ported from ~/tools/claude-intercom/broker.ts
in a follow-up step.