Files

Alejandro Gutiérrez 0a97a0c369 refactor(broker): merge HTTP+WS to single port, populate senderPubkey on push

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>

2026-04-04 21:35:05 +01:00

2.2 KiB

Raw Blame History

@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`	`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.

2.2 KiB Raw Blame History