@buoy-gg/sync-broker

Headless Socket.IO broker for the Buoy devtool sync protocol (v1).

This is the message router that sits between devices (React Native apps running a Buoy devtool, connected as Socket.IO clients) and dashboard clients (the Buoy desktop app, and the Buoy MCP server). It was extracted from the desktop app's apps/desktop/src/server so the same implementation can be hosted by either:

• the desktop app (which owns its own express/http server), or
• a standalone process such as the Buoy MCP server, when no desktop app is running.

Usage

Host a complete broker (standalone / MCP)

import { createBroker, DEFAULT_BROKER_PORT } from "@buoy-gg/sync-broker";

const broker = createBroker({
  port: DEFAULT_BROKER_PORT, // 42831
  onListening: (port) => console.log(`broker listening on ${port}`),
  onError: (err) => {
    if (err.code === "EADDRINUSE") {
      // Another broker (e.g. the desktop app) already owns the port —
      // connect to it as a client instead of hosting your own.
    }
  },
});

// later
await broker.close();

Attach to an existing Socket.IO server (desktop app)

import { Server } from "socket.io";
import { socketHandle } from "@buoy-gg/sync-broker";

const io = new Server(httpServer, socketOptions);
socketHandle({ io });

Protocol

The wire contract (events, message shapes, watch/backpressure model) is v1, canonically defined in @buoy-gg/external-sync. The broker reproduces the server-relevant types in src/protocol.ts to stay a dependency-light Node package (no React Native / socket.io-client).

Topology and message flow:

• Devices connect with a handshake carrying deviceId, platform, etc.
• Dashboard clients connect with deviceName: "Dashboard" (exact, no suffix).
• Devices announce devtool-capabilities; the broker replays them to dashboards.
• Dashboards devtool-watch tools; the broker consolidates watch counts so a device receives a single watching true/false per (device, tool) regardless of how many dashboards are watching.
• Dashboards invoke devtool-action; devices reply devtool-action-result.
• Devices push devtool-sync snapshots; the broker forwards them to dashboards.
• The broker emits broker-log entries to dashboards (handshakes, disconnect reasons, duplicate-name renames, protocol-version mismatches), buffering the last 200 so a dashboard that connects late still sees earlier failures.
• Dashboards emit forget-device to remove an offline device from history; offline devices also age out automatically after 24h (User.lastSeenAt).

Security: dev-only. No authentication, CORS is open (*), intended for loopback / trusted LAN.