0a97a0c369
Single-port refactor: - Drop the BROKER_PORT+1 HTTP side-port. Use `ws` with noServer:true and attach to a single node:http server via the 'upgrade' event. - Clients connect to ws://host:PORT/ws - Hook POSTs go to http://host:PORT/hook/set-status - Health probe at http://host:PORT/health - One port = one Traefik label, one cert, one deploy route. Matches the Coolify/VPS operational constraints. senderPubkey on push: - drainForMember now joins mesh.message_queue → mesh.member to return the sender's peerPubkey alongside each envelope. No extra round-trip, no cache invalidation needed (option A from review). - index.ts populates WSPushMessage.senderPubkey from the join result instead of the empty-string placeholder. - Receivers can now identify who sent a message directly from the push. README updated with a routes table for the single-port layout. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
55 lines
2.2 KiB
Markdown
55 lines
2.2 KiB
Markdown
# @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
|
|
|
|
```sh
|
|
# 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` | `7899` | 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 the `mesh` pgSchema)
|
|
- `@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.
|