@fieldnotes/sync-server 0.2.0 → 0.3.0

package/README.md

@@ -34,4 +34,43 @@ const { close } = createSyncServer({ port: 8080 });
 // ws://localhost:8080?room=my-room
 ```
 
-Auth and a Redis `HubBackend` are upcoming.
+## Authentication
+
+Pass an `authenticate` hook to gate connections:
+
+```ts
+import { createSyncServer } from '@fieldnotes/sync-server';
+
+createSyncServer({
+  port: 8080,
+  authenticate: async ({ req, room }) => {
+    const token = new URL(req.url ?? '', 'http://x').searchParams.get('token');
+    const member = await myCampaign.verify(token, room); // your app's check (Redis/DB/JWT)
+    return member ? { userId: member.id, role: member.isDM ? 'dm' : 'player' } : null;
+  },
+});
+```
+
+`authenticate({ req, room }) → { userId, role? } | null` runs on each connection and
+may be sync or async. Returning `null` (or throwing) **rejects** the connection: the
+socket is closed with WS code `4401` and the connection is never admitted to the room —
+no membership, no snapshot. A resolved result admits the connection carrying its
+`userId` and optional `role`.
+
+With **no hook**, rooms stay open: every connection is admitted anonymously with
+`userId = connId`. `role` is captured now and enforced in an upcoming release
+(role-based authorization and per-viewer visibility filtering).
+
+Messages that arrive during an async auth (notably the client's initial
+`request-snapshot`) are queued and replayed once the connection is admitted, so the
+first snapshot is never lost to the auth round-trip.
+
+### Passing a token
+
+A browser `WebSocket` can't set request headers, so pass the token as a URL query
+param (`ws://relay?room=R&token=…`) and read it from `req.url` in `authenticate`. URLs
+land in access/proxy logs, so prefer **short-lived / single-use** tokens. Non-browser
+clients can instead put the token in `req.headers` (e.g. `Authorization`), which
+`authenticate` reads directly.
+
+A Redis `HubBackend` and cross-instance fan-out ship in [`@fieldnotes/sync-redis`](../sync-redis).

package/dist/index.cjs

@@ -189,20 +189,48 @@ function createSyncServer(options = {}) {
       return;
     }
     const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;
-    hub.addConnection({
-      id: connId,
-      room,
-      send: (m) => {
-        try {
-          ws.send(m);
-        } catch {
-        }
+    let state = "pending";
+    let closed = false;
+    const queue = [];
+    const MAX_QUEUE = 100;
+    const send = (m) => {
+      try {
+        ws.send(m);
+      } catch {
       }
-    });
+    };
     ws.on("message", (data) => {
-      void hub.handleMessage(connId, String(data)).catch((err) => console.error("[sync-server]", err));
+      const msg = String(data);
+      if (state === "rejected") return;
+      if (state === "pending") {
+        if (queue.length < MAX_QUEUE) queue.push(msg);
+        return;
+      }
+      void hub.handleMessage(connId, msg).catch((err) => console.error("[sync-server]", err));
+    });
+    ws.on("close", () => {
+      closed = true;
+      if (state === "ready") hub.removeConnection(connId);
+    });
+    Promise.resolve(options.authenticate ? options.authenticate({ req, room }) : { userId: connId }).then((result) => {
+      if (closed) return;
+      if (!result) {
+        state = "rejected";
+        ws.close(4401, "unauthorized");
+        return;
+      }
+      state = "ready";
+      hub.addConnection({ id: connId, room, userId: result.userId, role: result.role, send });
+      for (const m of queue) {
+        void hub.handleMessage(connId, m).catch((err) => console.error("[sync-server]", err));
+      }
+      queue.length = 0;
+    }).catch(() => {
+      if (!closed) {
+        state = "rejected";
+        ws.close(4401, "unauthorized");
+      }
     });
-    ws.on("close", () => hub.removeConnection(connId));
   });
   return {
     hub,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/hub-fanout.ts","../src/create-sync-server.ts"],"sourcesContent":["export { SyncHub } from './sync-hub';\nexport type { SyncHubOptions, Connection } from './sync-hub';\nexport { MemoryHubBackend } from './memory-hub-backend';\nexport type { HubBackend } from './hub-backend';\nexport { createSyncServer } from './create-sync-server';\nexport type { CreateSyncServerOptions } from './create-sync-server';\nexport { InMemoryHubFanout } from './hub-fanout';\nexport type { HubFanout } from './hub-fanout';\n","import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport { InMemoryHubFanout, type HubFanout } from './hub-fanout';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nconst HUB_FROM = 'hub';\n\nfunction generateInstanceId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')\n    return crypto.randomUUID();\n  return `i-${Math.random().toString(36).slice(2)}`;\n}\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n  private readonly instanceId: string;\n  private readonly fanout: HubFanout;\n  private readonly fanoutUnsub: () => void;\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n    this.instanceId = options.instanceId ?? generateInstanceId();\n    this.fanout = options.fanout ?? new InMemoryHubFanout();\n    this.fanoutUnsub = this.fanout.subscribe((payload) => this.onFanout(payload));\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n      this.fanout.publish(JSON.stringify({ o: this.instanceId, room: conn.room, m: message }));\n    }\n    // 'snapshot' from a client → ignored\n  }\n\n  private onFanout(payload: string): void {\n    // Off the serial queue on purpose: forward-only (no backend re-apply — the origin already applied to the\n    // SHARED backend), and delivery is already ordered. Do not wrap this in roomQueues.\n    let env: { o?: unknown; room?: unknown; m?: unknown };\n    try {\n      env = JSON.parse(payload);\n    } catch {\n      return;\n    }\n    if (typeof env.o !== 'string' || typeof env.room !== 'string' || typeof env.m !== 'string')\n      return;\n    if (env.o === this.instanceId) return; // our own publish — already forwarded locally\n    const members = this.rooms.get(env.room);\n    if (!members) return;\n    const m = env.m;\n    for (const id of members) {\n      try {\n        this.conns.get(id)?.send(m);\n      } catch {\n        /* a throwing socket must not break the fanout loop */\n      }\n    }\n  }\n\n  close(): void {\n    this.fanoutUnsub();\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from './hub-backend';\r\n\r\nexport class MemoryHubBackend implements HubBackend {\r\n  private rooms = new Map<string, Map<string, CanvasElement>>();\r\n\r\n  private room(id: string): Map<string, CanvasElement> {\r\n    let r = this.rooms.get(id);\r\n    if (!r) {\r\n      r = new Map();\r\n      this.rooms.set(id, r);\r\n    }\r\n    return r;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    return [...this.room(room).values()];\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    applyOpToMap(this.room(room), op);\r\n  }\r\n}\r\n","export interface HubFanout {\n  publish(payload: string): void;\n  subscribe(handler: (payload: string) => void): () => void;\n  close?(): void;\n}\n\nexport class InMemoryHubFanout implements HubFanout {\n  private readonly handlers = new Set<(payload: string) => void>();\n\n  publish(payload: string): void {\n    for (const h of this.handlers) {\n      try {\n        h(payload);\n      } catch {\n        /* one throwing subscriber must not break the publish loop */\n      }\n    }\n  }\n\n  subscribe(handler: (payload: string) => void): () => void {\n    this.handlers.add(handler);\n    return () => this.handlers.delete(handler);\n  }\n}\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\nimport type { HubFanout } from './hub-fanout';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({\n    backend: options.backend,\n    fanout: options.fanout,\n    instanceId: options.instanceId,\n  });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n    hub.addConnection({\n      id: connId,\n      room,\n      send: (m) => {\n        try {\n          ws.send(m);\n        } catch {\n          /* socket closed mid-send */\n        }\n      },\n    });\n    ws.on('message', (data) => {\n      void hub\n        .handleMessage(connId, String(data))\n        .catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => hub.removeConnection(connId));\n  });\n  return {\n    hub,\n    wss,\n    close: () =>\n      new Promise<void>((resolve) => {\n        hub.close();\n        wss.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,eAA8B;;;ACA9B,kBAA0C;AAInC,IAAM,mBAAN,MAA6C;AAAA,EAC1C,QAAQ,oBAAI,IAAwC;AAAA,EAEpD,KAAK,IAAwC;AACnD,QAAI,IAAI,KAAK,MAAM,IAAI,EAAE;AACzB,QAAI,CAAC,GAAG;AACN,UAAI,oBAAI,IAAI;AACZ,WAAK,MAAM,IAAI,IAAI,CAAC;AAAA,IACtB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,WAAO,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,OAAO,CAAC;AAAA,EACrC;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,kCAAa,KAAK,KAAK,IAAI,GAAG,EAAE;AAAA,EAClC;AACF;;;ACjBO,IAAM,oBAAN,MAA6C;AAAA,EACjC,WAAW,oBAAI,IAA+B;AAAA,EAE/D,QAAQ,SAAuB;AAC7B,eAAW,KAAK,KAAK,UAAU;AAC7B,UAAI;AACF,UAAE,OAAO;AAAA,MACX,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAAA,EAEA,UAAU,SAAgD;AACxD,SAAK,SAAS,IAAI,OAAO;AACzB,WAAO,MAAM,KAAK,SAAS,OAAO,OAAO;AAAA,EAC3C;AACF;;;AFNA,IAAM,WAAW;AAEjB,SAAS,qBAA6B;AACpC,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe;AAChE,WAAO,OAAO,WAAW;AAC3B,SAAO,KAAK,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AACjD;AAEO,IAAM,UAAN,MAAc;AAAA,EACF;AAAA,EACA,QAAQ,oBAAI,IAAwB;AAAA,EACpC,QAAQ,oBAAI,IAAyB;AAAA;AAAA,EACrC,aAAa,oBAAI,IAA2B;AAAA;AAAA,EAC5C;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,UAA0B,CAAC,GAAG;AACxC,SAAK,UAAU,QAAQ,WAAW,IAAI,iBAAiB;AACvD,SAAK,aAAa,QAAQ,cAAc,mBAAmB;AAC3D,SAAK,SAAS,QAAQ,UAAU,IAAI,kBAAkB;AACtD,SAAK,cAAc,KAAK,OAAO,UAAU,CAAC,YAAY,KAAK,SAAS,OAAO,CAAC;AAAA,EAC9E;AAAA,EAEA,cAAc,MAAwB;AACpC,SAAK,MAAM,IAAI,KAAK,IAAI,IAAI;AAC5B,QAAI,MAAM,KAAK,MAAM,IAAI,KAAK,IAAI;AAClC,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAI;AACd,WAAK,MAAM,IAAI,KAAK,MAAM,GAAG;AAAA,IAC/B;AACA,QAAI,IAAI,KAAK,EAAE;AAAA,EACjB;AAAA,EAEA,iBAAiB,QAAsB;AACrC,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM;AACX,SAAK,MAAM,OAAO,MAAM;AACxB,UAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,QAAI,SAAS;AACX,cAAQ,OAAO,MAAM;AACrB,UAAI,QAAQ,SAAS,GAAG;AACtB,aAAK,MAAM,OAAO,KAAK,IAAI;AAC3B,aAAK,WAAW,OAAO,KAAK,IAAI;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YAAoB;AAClB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA,EAEA,cAAc,QAAgB,SAAgC;AAC5D,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM,QAAO,QAAQ,QAAQ;AAClC,UAAM,OAAO,KAAK;AAClB,UAAM,OAAO,KAAK,WAAW,IAAI,IAAI,KAAK,QAAQ,QAAQ;AAC1D,UAAM,OAAO,KACV,KAAK,MAAM,KAAK,QAAQ,MAAM,OAAO,CAAC,EACtC,MAAM,MAAM;AAAA,IAEb,CAAC;AACH,SAAK,WAAW,IAAI,MAAM,IAAI;AAC9B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,QAAQ,MAAkB,SAAgC;AACtE,UAAM,UAAM,4BAAc,OAAO;AACjC,QAAI,CAAC,IAAK;AACV,UAAM,KAAK,IAAI;AACf,QAAI,GAAG,SAAS,oBAAoB;AAClC,YAAM,WAAW,MAAM,KAAK,QAAQ,SAAS,KAAK,IAAI;AACtD,WAAK;AAAA,QACH,KAAK,UAAU,EAAE,MAAM,UAAU,IAAI,EAAE,MAAM,YAAY,IAAI,IAAI,MAAM,SAAS,EAAE,CAAC;AAAA,MACrF;AAAA,IACF,WAAW,GAAG,SAAS,YAAY,GAAG,SAAS,YAAY,GAAG,SAAS,SAAS;AAC9E,YAAM,KAAK,QAAQ,MAAM,KAAK,MAAM,EAAE;AACtC,YAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,UAAI,SAAS;AACX,mBAAW,MAAM,SAAS;AACxB,cAAI,OAAO,KAAK,GAAI;AACpB,eAAK,MAAM,IAAI,EAAE,GAAG,KAAK,OAAO;AAAA,QAClC;AAAA,MACF;AACA,WAAK,OAAO,QAAQ,KAAK,UAAU,EAAE,GAAG,KAAK,YAAY,MAAM,KAAK,MAAM,GAAG,QAAQ,CAAC,CAAC;AAAA,IACzF;AAAA,EAEF;AAAA,EAEQ,SAAS,SAAuB;AAGtC,QAAI;AACJ,QAAI;AACF,YAAM,KAAK,MAAM,OAAO;AAAA,IAC1B,QAAQ;AACN;AAAA,IACF;AACA,QAAI,OAAO,IAAI,MAAM,YAAY,OAAO,IAAI,SAAS,YAAY,OAAO,IAAI,MAAM;AAChF;AACF,QAAI,IAAI,MAAM,KAAK,WAAY;AAC/B,UAAM,UAAU,KAAK,MAAM,IAAI,IAAI,IAAI;AACvC,QAAI,CAAC,QAAS;AACd,UAAM,IAAI,IAAI;AACd,eAAW,MAAM,SAAS;AACxB,UAAI;AACF,aAAK,MAAM,IAAI,EAAE,GAAG,KAAK,CAAC;AAAA,MAC5B,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAAA,EAEA,QAAc;AACZ,SAAK,YAAY;AAAA,EACnB;AACF;;;AGrIA,gBAAgC;AAczB,SAAS,iBAAiB,UAAmC,CAAC,GAInE;AACA,QAAM,MAAM,IAAI,QAAQ;AAAA,IACtB,SAAS,QAAQ;AAAA,IACjB,QAAQ,QAAQ;AAAA,IAChB,YAAY,QAAQ;AAAA,EACtB,CAAC;AACD,QAAM,MAAM,QAAQ,SAChB,IAAI,0BAAgB,EAAE,QAAQ,QAAQ,OAAO,CAAC,IAC9C,IAAI,0BAAgB,EAAE,MAAM,QAAQ,QAAQ,EAAE,CAAC;AACnD,MAAI,UAAU;AACd,MAAI,GAAG,cAAc,CAAC,IAAI,QAAQ;AAChC,UAAM,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,kBAAkB;AACrD,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM;AACxC,QAAI,CAAC,MAAM;AACT,SAAG,MAAM,MAAM,eAAe;AAC9B;AAAA,IACF;AACA,UAAM,SAAS,IAAI,EAAE,OAAO,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AACtE,QAAI,cAAc;AAAA,MAChB,IAAI;AAAA,MACJ;AAAA,MACA,MAAM,CAAC,MAAM;AACX,YAAI;AACF,aAAG,KAAK,CAAC;AAAA,QACX,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF,CAAC;AACD,OAAG,GAAG,WAAW,CAAC,SAAS;AACzB,WAAK,IACF,cAAc,QAAQ,OAAO,IAAI,CAAC,EAClC,MAAM,CAAC,QAAQ,QAAQ,MAAM,iBAAiB,GAAG,CAAC;AAAA,IACvD,CAAC;AACD,OAAG,GAAG,SAAS,MAAM,IAAI,iBAAiB,MAAM,CAAC;AAAA,EACnD,CAAC;AACD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,OAAO,MACL,IAAI,QAAc,CAAC,YAAY;AAC7B,UAAI,MAAM;AACV,UAAI,MAAM,MAAM,QAAQ,CAAC;AAAA,IAC3B,CAAC;AAAA,EACL;AACF;","names":["import_sync"]}
+{"version":3,"sources":["../src/index.ts","../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/hub-fanout.ts","../src/create-sync-server.ts"],"sourcesContent":["export { SyncHub } from './sync-hub';\nexport type { SyncHubOptions, Connection } from './sync-hub';\nexport { MemoryHubBackend } from './memory-hub-backend';\nexport type { HubBackend } from './hub-backend';\nexport { createSyncServer } from './create-sync-server';\nexport type { CreateSyncServerOptions } from './create-sync-server';\nexport { InMemoryHubFanout } from './hub-fanout';\nexport type { HubFanout } from './hub-fanout';\nexport type { AuthInfo, AuthResult, Authenticate } from './authenticate';\n","import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport { InMemoryHubFanout, type HubFanout } from './hub-fanout';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  userId?: string;\n  role?: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nconst HUB_FROM = 'hub';\n\nfunction generateInstanceId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')\n    return crypto.randomUUID();\n  return `i-${Math.random().toString(36).slice(2)}`;\n}\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n  private readonly instanceId: string;\n  private readonly fanout: HubFanout;\n  private readonly fanoutUnsub: () => void;\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n    this.instanceId = options.instanceId ?? generateInstanceId();\n    this.fanout = options.fanout ?? new InMemoryHubFanout();\n    this.fanoutUnsub = this.fanout.subscribe((payload) => this.onFanout(payload));\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n      this.fanout.publish(JSON.stringify({ o: this.instanceId, room: conn.room, m: message }));\n    }\n    // 'snapshot' from a client → ignored\n  }\n\n  private onFanout(payload: string): void {\n    // Off the serial queue on purpose: forward-only (no backend re-apply — the origin already applied to the\n    // SHARED backend), and delivery is already ordered. Do not wrap this in roomQueues.\n    let env: { o?: unknown; room?: unknown; m?: unknown };\n    try {\n      env = JSON.parse(payload);\n    } catch {\n      return;\n    }\n    if (typeof env.o !== 'string' || typeof env.room !== 'string' || typeof env.m !== 'string')\n      return;\n    if (env.o === this.instanceId) return; // our own publish — already forwarded locally\n    const members = this.rooms.get(env.room);\n    if (!members) return;\n    const m = env.m;\n    for (const id of members) {\n      try {\n        this.conns.get(id)?.send(m);\n      } catch {\n        /* a throwing socket must not break the fanout loop */\n      }\n    }\n  }\n\n  close(): void {\n    this.fanoutUnsub();\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from './hub-backend';\r\n\r\nexport class MemoryHubBackend implements HubBackend {\r\n  private rooms = new Map<string, Map<string, CanvasElement>>();\r\n\r\n  private room(id: string): Map<string, CanvasElement> {\r\n    let r = this.rooms.get(id);\r\n    if (!r) {\r\n      r = new Map();\r\n      this.rooms.set(id, r);\r\n    }\r\n    return r;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    return [...this.room(room).values()];\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    applyOpToMap(this.room(room), op);\r\n  }\r\n}\r\n","export interface HubFanout {\r\n  publish(payload: string): void;\r\n  subscribe(handler: (payload: string) => void): () => void;\r\n  close?(): void;\r\n}\r\n\r\nexport class InMemoryHubFanout implements HubFanout {\r\n  private readonly handlers = new Set<(payload: string) => void>();\r\n\r\n  publish(payload: string): void {\r\n    for (const h of this.handlers) {\r\n      try {\r\n        h(payload);\r\n      } catch {\r\n        /* one throwing subscriber must not break the publish loop */\r\n      }\r\n    }\r\n  }\r\n\r\n  subscribe(handler: (payload: string) => void): () => void {\r\n    this.handlers.add(handler);\r\n    return () => this.handlers.delete(handler);\r\n  }\r\n}\r\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\nimport type { HubFanout } from './hub-fanout';\nimport type { Authenticate } from './authenticate';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n  authenticate?: Authenticate;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({\n    backend: options.backend,\n    fanout: options.fanout,\n    instanceId: options.instanceId,\n  });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n\n    let state: 'pending' | 'ready' | 'rejected' = 'pending';\n    let closed = false;\n    const queue: string[] = [];\n    const MAX_QUEUE = 100;\n\n    const send = (m: string) => {\n      try {\n        ws.send(m);\n      } catch {\n        /* socket closed mid-send */\n      }\n    };\n\n    ws.on('message', (data) => {\n      const msg = String(data);\n      if (state === 'rejected') return;\n      if (state === 'pending') {\n        if (queue.length < MAX_QUEUE) queue.push(msg);\n        return;\n      }\n      void hub.handleMessage(connId, msg).catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => {\n      closed = true;\n      if (state === 'ready') hub.removeConnection(connId);\n    });\n\n    Promise.resolve(options.authenticate ? options.authenticate({ req, room }) : { userId: connId })\n      .then((result) => {\n        if (closed) return;\n        if (!result) {\n          state = 'rejected';\n          ws.close(4401, 'unauthorized');\n          return;\n        }\n        state = 'ready';\n        hub.addConnection({ id: connId, room, userId: result.userId, role: result.role, send });\n        for (const m of queue) {\n          void hub.handleMessage(connId, m).catch((err) => console.error('[sync-server]', err));\n        }\n        queue.length = 0;\n      })\n      .catch(() => {\n        if (!closed) {\n          state = 'rejected';\n          ws.close(4401, 'unauthorized');\n        }\n      });\n  });\n  return {\n    hub,\n    wss,\n    close: () =>\n      new Promise<void>((resolve) => {\n        hub.close();\n        wss.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":"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","names":["import_sync"]}

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { CanvasElement } from '@fieldnotes/core';
 import { SyncOp } from '@fieldnotes/sync';
 import { WebSocketServer } from 'ws';
-import { Server } from 'http';
+import { IncomingMessage, Server } from 'http';
 
 interface HubFanout {
     publish(payload: string): void;
@@ -22,6 +22,8 @@ interface HubBackend {
 interface Connection {
     id: string;
     room: string;
+    userId?: string;
+    role?: string;
     send(message: string): void;
 }
 interface SyncHubOptions {
@@ -54,12 +56,23 @@ declare class MemoryHubBackend implements HubBackend {
     apply(room: string, op: SyncOp): Promise<void>;
 }
 
+interface AuthInfo {
+    req: IncomingMessage;
+    room: string;
+}
+interface AuthResult {
+    userId: string;
+    role?: string;
+}
+type Authenticate = (info: AuthInfo) => AuthResult | null | Promise<AuthResult | null>;
+
 interface CreateSyncServerOptions {
     port?: number;
     server?: Server;
     backend?: HubBackend;
     fanout?: HubFanout;
     instanceId?: string;
+    authenticate?: Authenticate;
 }
 declare function createSyncServer(options?: CreateSyncServerOptions): {
     hub: SyncHub;
@@ -67,4 +80,4 @@ declare function createSyncServer(options?: CreateSyncServerOptions): {
     close: () => Promise<void>;
 };
 
-export { type Connection, type CreateSyncServerOptions, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };
+export { type AuthInfo, type AuthResult, type Authenticate, type Connection, type CreateSyncServerOptions, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { CanvasElement } from '@fieldnotes/core';
 import { SyncOp } from '@fieldnotes/sync';
 import { WebSocketServer } from 'ws';
-import { Server } from 'http';
+import { IncomingMessage, Server } from 'http';
 
 interface HubFanout {
     publish(payload: string): void;
@@ -22,6 +22,8 @@ interface HubBackend {
 interface Connection {
     id: string;
     room: string;
+    userId?: string;
+    role?: string;
     send(message: string): void;
 }
 interface SyncHubOptions {
@@ -54,12 +56,23 @@ declare class MemoryHubBackend implements HubBackend {
     apply(room: string, op: SyncOp): Promise<void>;
 }
 
+interface AuthInfo {
+    req: IncomingMessage;
+    room: string;
+}
+interface AuthResult {
+    userId: string;
+    role?: string;
+}
+type Authenticate = (info: AuthInfo) => AuthResult | null | Promise<AuthResult | null>;
+
 interface CreateSyncServerOptions {
     port?: number;
     server?: Server;
     backend?: HubBackend;
     fanout?: HubFanout;
     instanceId?: string;
+    authenticate?: Authenticate;
 }
 declare function createSyncServer(options?: CreateSyncServerOptions): {
     hub: SyncHub;
@@ -67,4 +80,4 @@ declare function createSyncServer(options?: CreateSyncServerOptions): {
     close: () => Promise<void>;
 };
 
-export { type Connection, type CreateSyncServerOptions, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };
+export { type AuthInfo, type AuthResult, type Authenticate, type Connection, type CreateSyncServerOptions, type HubBackend, type HubFanout, InMemoryHubFanout, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };

package/dist/index.js

@@ -160,20 +160,48 @@ function createSyncServer(options = {}) {
       return;
     }
     const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;
-    hub.addConnection({
-      id: connId,
-      room,
-      send: (m) => {
-        try {
-          ws.send(m);
-        } catch {
-        }
+    let state = "pending";
+    let closed = false;
+    const queue = [];
+    const MAX_QUEUE = 100;
+    const send = (m) => {
+      try {
+        ws.send(m);
+      } catch {
       }
-    });
+    };
     ws.on("message", (data) => {
-      void hub.handleMessage(connId, String(data)).catch((err) => console.error("[sync-server]", err));
+      const msg = String(data);
+      if (state === "rejected") return;
+      if (state === "pending") {
+        if (queue.length < MAX_QUEUE) queue.push(msg);
+        return;
+      }
+      void hub.handleMessage(connId, msg).catch((err) => console.error("[sync-server]", err));
+    });
+    ws.on("close", () => {
+      closed = true;
+      if (state === "ready") hub.removeConnection(connId);
+    });
+    Promise.resolve(options.authenticate ? options.authenticate({ req, room }) : { userId: connId }).then((result) => {
+      if (closed) return;
+      if (!result) {
+        state = "rejected";
+        ws.close(4401, "unauthorized");
+        return;
+      }
+      state = "ready";
+      hub.addConnection({ id: connId, room, userId: result.userId, role: result.role, send });
+      for (const m of queue) {
+        void hub.handleMessage(connId, m).catch((err) => console.error("[sync-server]", err));
+      }
+      queue.length = 0;
+    }).catch(() => {
+      if (!closed) {
+        state = "rejected";
+        ws.close(4401, "unauthorized");
+      }
     });
-    ws.on("close", () => hub.removeConnection(connId));
   });
   return {
     hub,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/hub-fanout.ts","../src/create-sync-server.ts"],"sourcesContent":["import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport { InMemoryHubFanout, type HubFanout } from './hub-fanout';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nconst HUB_FROM = 'hub';\n\nfunction generateInstanceId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')\n    return crypto.randomUUID();\n  return `i-${Math.random().toString(36).slice(2)}`;\n}\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n  private readonly instanceId: string;\n  private readonly fanout: HubFanout;\n  private readonly fanoutUnsub: () => void;\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n    this.instanceId = options.instanceId ?? generateInstanceId();\n    this.fanout = options.fanout ?? new InMemoryHubFanout();\n    this.fanoutUnsub = this.fanout.subscribe((payload) => this.onFanout(payload));\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n      this.fanout.publish(JSON.stringify({ o: this.instanceId, room: conn.room, m: message }));\n    }\n    // 'snapshot' from a client → ignored\n  }\n\n  private onFanout(payload: string): void {\n    // Off the serial queue on purpose: forward-only (no backend re-apply — the origin already applied to the\n    // SHARED backend), and delivery is already ordered. Do not wrap this in roomQueues.\n    let env: { o?: unknown; room?: unknown; m?: unknown };\n    try {\n      env = JSON.parse(payload);\n    } catch {\n      return;\n    }\n    if (typeof env.o !== 'string' || typeof env.room !== 'string' || typeof env.m !== 'string')\n      return;\n    if (env.o === this.instanceId) return; // our own publish — already forwarded locally\n    const members = this.rooms.get(env.room);\n    if (!members) return;\n    const m = env.m;\n    for (const id of members) {\n      try {\n        this.conns.get(id)?.send(m);\n      } catch {\n        /* a throwing socket must not break the fanout loop */\n      }\n    }\n  }\n\n  close(): void {\n    this.fanoutUnsub();\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from './hub-backend';\r\n\r\nexport class MemoryHubBackend implements HubBackend {\r\n  private rooms = new Map<string, Map<string, CanvasElement>>();\r\n\r\n  private room(id: string): Map<string, CanvasElement> {\r\n    let r = this.rooms.get(id);\r\n    if (!r) {\r\n      r = new Map();\r\n      this.rooms.set(id, r);\r\n    }\r\n    return r;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    return [...this.room(room).values()];\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    applyOpToMap(this.room(room), op);\r\n  }\r\n}\r\n","export interface HubFanout {\n  publish(payload: string): void;\n  subscribe(handler: (payload: string) => void): () => void;\n  close?(): void;\n}\n\nexport class InMemoryHubFanout implements HubFanout {\n  private readonly handlers = new Set<(payload: string) => void>();\n\n  publish(payload: string): void {\n    for (const h of this.handlers) {\n      try {\n        h(payload);\n      } catch {\n        /* one throwing subscriber must not break the publish loop */\n      }\n    }\n  }\n\n  subscribe(handler: (payload: string) => void): () => void {\n    this.handlers.add(handler);\n    return () => this.handlers.delete(handler);\n  }\n}\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\nimport type { HubFanout } from './hub-fanout';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({\n    backend: options.backend,\n    fanout: options.fanout,\n    instanceId: options.instanceId,\n  });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n    hub.addConnection({\n      id: connId,\n      room,\n      send: (m) => {\n        try {\n          ws.send(m);\n        } catch {\n          /* socket closed mid-send */\n        }\n      },\n    });\n    ws.on('message', (data) => {\n      void hub\n        .handleMessage(connId, String(data))\n        .catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => hub.removeConnection(connId));\n  });\n  return {\n    hub,\n    wss,\n    close: () =>\n      new Promise<void>((resolve) => {\n        hub.close();\n        wss.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/hub-fanout.ts","../src/create-sync-server.ts"],"sourcesContent":["import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport { InMemoryHubFanout, type HubFanout } from './hub-fanout';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  userId?: string;\n  role?: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n}\n\nconst HUB_FROM = 'hub';\n\nfunction generateInstanceId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')\n    return crypto.randomUUID();\n  return `i-${Math.random().toString(36).slice(2)}`;\n}\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n  private readonly instanceId: string;\n  private readonly fanout: HubFanout;\n  private readonly fanoutUnsub: () => void;\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n    this.instanceId = options.instanceId ?? generateInstanceId();\n    this.fanout = options.fanout ?? new InMemoryHubFanout();\n    this.fanoutUnsub = this.fanout.subscribe((payload) => this.onFanout(payload));\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n      this.fanout.publish(JSON.stringify({ o: this.instanceId, room: conn.room, m: message }));\n    }\n    // 'snapshot' from a client → ignored\n  }\n\n  private onFanout(payload: string): void {\n    // Off the serial queue on purpose: forward-only (no backend re-apply — the origin already applied to the\n    // SHARED backend), and delivery is already ordered. Do not wrap this in roomQueues.\n    let env: { o?: unknown; room?: unknown; m?: unknown };\n    try {\n      env = JSON.parse(payload);\n    } catch {\n      return;\n    }\n    if (typeof env.o !== 'string' || typeof env.room !== 'string' || typeof env.m !== 'string')\n      return;\n    if (env.o === this.instanceId) return; // our own publish — already forwarded locally\n    const members = this.rooms.get(env.room);\n    if (!members) return;\n    const m = env.m;\n    for (const id of members) {\n      try {\n        this.conns.get(id)?.send(m);\n      } catch {\n        /* a throwing socket must not break the fanout loop */\n      }\n    }\n  }\n\n  close(): void {\n    this.fanoutUnsub();\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from './hub-backend';\r\n\r\nexport class MemoryHubBackend implements HubBackend {\r\n  private rooms = new Map<string, Map<string, CanvasElement>>();\r\n\r\n  private room(id: string): Map<string, CanvasElement> {\r\n    let r = this.rooms.get(id);\r\n    if (!r) {\r\n      r = new Map();\r\n      this.rooms.set(id, r);\r\n    }\r\n    return r;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    return [...this.room(room).values()];\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    applyOpToMap(this.room(room), op);\r\n  }\r\n}\r\n","export interface HubFanout {\r\n  publish(payload: string): void;\r\n  subscribe(handler: (payload: string) => void): () => void;\r\n  close?(): void;\r\n}\r\n\r\nexport class InMemoryHubFanout implements HubFanout {\r\n  private readonly handlers = new Set<(payload: string) => void>();\r\n\r\n  publish(payload: string): void {\r\n    for (const h of this.handlers) {\r\n      try {\r\n        h(payload);\r\n      } catch {\r\n        /* one throwing subscriber must not break the publish loop */\r\n      }\r\n    }\r\n  }\r\n\r\n  subscribe(handler: (payload: string) => void): () => void {\r\n    this.handlers.add(handler);\r\n    return () => this.handlers.delete(handler);\r\n  }\r\n}\r\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\nimport type { HubFanout } from './hub-fanout';\nimport type { Authenticate } from './authenticate';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n  fanout?: HubFanout;\n  instanceId?: string;\n  authenticate?: Authenticate;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({\n    backend: options.backend,\n    fanout: options.fanout,\n    instanceId: options.instanceId,\n  });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n\n    let state: 'pending' | 'ready' | 'rejected' = 'pending';\n    let closed = false;\n    const queue: string[] = [];\n    const MAX_QUEUE = 100;\n\n    const send = (m: string) => {\n      try {\n        ws.send(m);\n      } catch {\n        /* socket closed mid-send */\n      }\n    };\n\n    ws.on('message', (data) => {\n      const msg = String(data);\n      if (state === 'rejected') return;\n      if (state === 'pending') {\n        if (queue.length < MAX_QUEUE) queue.push(msg);\n        return;\n      }\n      void hub.handleMessage(connId, msg).catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => {\n      closed = true;\n      if (state === 'ready') hub.removeConnection(connId);\n    });\n\n    Promise.resolve(options.authenticate ? options.authenticate({ req, room }) : { userId: connId })\n      .then((result) => {\n        if (closed) return;\n        if (!result) {\n          state = 'rejected';\n          ws.close(4401, 'unauthorized');\n          return;\n        }\n        state = 'ready';\n        hub.addConnection({ id: connId, room, userId: result.userId, role: result.role, send });\n        for (const m of queue) {\n          void hub.handleMessage(connId, m).catch((err) => console.error('[sync-server]', err));\n        }\n        queue.length = 0;\n      })\n      .catch(() => {\n        if (!closed) {\n          state = 'rejected';\n          ws.close(4401, 'unauthorized');\n        }\n      });\n  });\n  return {\n    hub,\n    wss,\n    close: () =>\n      new Promise<void>((resolve) => {\n        hub.close();\n        wss.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":";AAAA,SAAS,qBAAqB;;;ACA9B,SAAS,oBAAiC;AAInC,IAAM,mBAAN,MAA6C;AAAA,EAC1C,QAAQ,oBAAI,IAAwC;AAAA,EAEpD,KAAK,IAAwC;AACnD,QAAI,IAAI,KAAK,MAAM,IAAI,EAAE;AACzB,QAAI,CAAC,GAAG;AACN,UAAI,oBAAI,IAAI;AACZ,WAAK,MAAM,IAAI,IAAI,CAAC;AAAA,IACtB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,WAAO,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,OAAO,CAAC;AAAA,EACrC;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,iBAAa,KAAK,KAAK,IAAI,GAAG,EAAE;AAAA,EAClC;AACF;;;ACjBO,IAAM,oBAAN,MAA6C;AAAA,EACjC,WAAW,oBAAI,IAA+B;AAAA,EAE/D,QAAQ,SAAuB;AAC7B,eAAW,KAAK,KAAK,UAAU;AAC7B,UAAI;AACF,UAAE,OAAO;AAAA,MACX,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAAA,EAEA,UAAU,SAAgD;AACxD,SAAK,SAAS,IAAI,OAAO;AACzB,WAAO,MAAM,KAAK,SAAS,OAAO,OAAO;AAAA,EAC3C;AACF;;;AFJA,IAAM,WAAW;AAEjB,SAAS,qBAA6B;AACpC,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe;AAChE,WAAO,OAAO,WAAW;AAC3B,SAAO,KAAK,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AACjD;AAEO,IAAM,UAAN,MAAc;AAAA,EACF;AAAA,EACA,QAAQ,oBAAI,IAAwB;AAAA,EACpC,QAAQ,oBAAI,IAAyB;AAAA;AAAA,EACrC,aAAa,oBAAI,IAA2B;AAAA;AAAA,EAC5C;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,UAA0B,CAAC,GAAG;AACxC,SAAK,UAAU,QAAQ,WAAW,IAAI,iBAAiB;AACvD,SAAK,aAAa,QAAQ,cAAc,mBAAmB;AAC3D,SAAK,SAAS,QAAQ,UAAU,IAAI,kBAAkB;AACtD,SAAK,cAAc,KAAK,OAAO,UAAU,CAAC,YAAY,KAAK,SAAS,OAAO,CAAC;AAAA,EAC9E;AAAA,EAEA,cAAc,MAAwB;AACpC,SAAK,MAAM,IAAI,KAAK,IAAI,IAAI;AAC5B,QAAI,MAAM,KAAK,MAAM,IAAI,KAAK,IAAI;AAClC,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAI;AACd,WAAK,MAAM,IAAI,KAAK,MAAM,GAAG;AAAA,IAC/B;AACA,QAAI,IAAI,KAAK,EAAE;AAAA,EACjB;AAAA,EAEA,iBAAiB,QAAsB;AACrC,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM;AACX,SAAK,MAAM,OAAO,MAAM;AACxB,UAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,QAAI,SAAS;AACX,cAAQ,OAAO,MAAM;AACrB,UAAI,QAAQ,SAAS,GAAG;AACtB,aAAK,MAAM,OAAO,KAAK,IAAI;AAC3B,aAAK,WAAW,OAAO,KAAK,IAAI;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YAAoB;AAClB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA,EAEA,cAAc,QAAgB,SAAgC;AAC5D,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM,QAAO,QAAQ,QAAQ;AAClC,UAAM,OAAO,KAAK;AAClB,UAAM,OAAO,KAAK,WAAW,IAAI,IAAI,KAAK,QAAQ,QAAQ;AAC1D,UAAM,OAAO,KACV,KAAK,MAAM,KAAK,QAAQ,MAAM,OAAO,CAAC,EACtC,MAAM,MAAM;AAAA,IAEb,CAAC;AACH,SAAK,WAAW,IAAI,MAAM,IAAI;AAC9B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,QAAQ,MAAkB,SAAgC;AACtE,UAAM,MAAM,cAAc,OAAO;AACjC,QAAI,CAAC,IAAK;AACV,UAAM,KAAK,IAAI;AACf,QAAI,GAAG,SAAS,oBAAoB;AAClC,YAAM,WAAW,MAAM,KAAK,QAAQ,SAAS,KAAK,IAAI;AACtD,WAAK;AAAA,QACH,KAAK,UAAU,EAAE,MAAM,UAAU,IAAI,EAAE,MAAM,YAAY,IAAI,IAAI,MAAM,SAAS,EAAE,CAAC;AAAA,MACrF;AAAA,IACF,WAAW,GAAG,SAAS,YAAY,GAAG,SAAS,YAAY,GAAG,SAAS,SAAS;AAC9E,YAAM,KAAK,QAAQ,MAAM,KAAK,MAAM,EAAE;AACtC,YAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,UAAI,SAAS;AACX,mBAAW,MAAM,SAAS;AACxB,cAAI,OAAO,KAAK,GAAI;AACpB,eAAK,MAAM,IAAI,EAAE,GAAG,KAAK,OAAO;AAAA,QAClC;AAAA,MACF;AACA,WAAK,OAAO,QAAQ,KAAK,UAAU,EAAE,GAAG,KAAK,YAAY,MAAM,KAAK,MAAM,GAAG,QAAQ,CAAC,CAAC;AAAA,IACzF;AAAA,EAEF;AAAA,EAEQ,SAAS,SAAuB;AAGtC,QAAI;AACJ,QAAI;AACF,YAAM,KAAK,MAAM,OAAO;AAAA,IAC1B,QAAQ;AACN;AAAA,IACF;AACA,QAAI,OAAO,IAAI,MAAM,YAAY,OAAO,IAAI,SAAS,YAAY,OAAO,IAAI,MAAM;AAChF;AACF,QAAI,IAAI,MAAM,KAAK,WAAY;AAC/B,UAAM,UAAU,KAAK,MAAM,IAAI,IAAI,IAAI;AACvC,QAAI,CAAC,QAAS;AACd,UAAM,IAAI,IAAI;AACd,eAAW,MAAM,SAAS;AACxB,UAAI;AACF,aAAK,MAAM,IAAI,EAAE,GAAG,KAAK,CAAC;AAAA,MAC5B,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAAA,EAEA,QAAc;AACZ,SAAK,YAAY;AAAA,EACnB;AACF;;;AGvIA,SAAS,uBAAuB;AAgBzB,SAAS,iBAAiB,UAAmC,CAAC,GAInE;AACA,QAAM,MAAM,IAAI,QAAQ;AAAA,IACtB,SAAS,QAAQ;AAAA,IACjB,QAAQ,QAAQ;AAAA,IAChB,YAAY,QAAQ;AAAA,EACtB,CAAC;AACD,QAAM,MAAM,QAAQ,SAChB,IAAI,gBAAgB,EAAE,QAAQ,QAAQ,OAAO,CAAC,IAC9C,IAAI,gBAAgB,EAAE,MAAM,QAAQ,QAAQ,EAAE,CAAC;AACnD,MAAI,UAAU;AACd,MAAI,GAAG,cAAc,CAAC,IAAI,QAAQ;AAChC,UAAM,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,kBAAkB;AACrD,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM;AACxC,QAAI,CAAC,MAAM;AACT,SAAG,MAAM,MAAM,eAAe;AAC9B;AAAA,IACF;AACA,UAAM,SAAS,IAAI,EAAE,OAAO,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAEtE,QAAI,QAA0C;AAC9C,QAAI,SAAS;AACb,UAAM,QAAkB,CAAC;AACzB,UAAM,YAAY;AAElB,UAAM,OAAO,CAAC,MAAc;AAC1B,UAAI;AACF,WAAG,KAAK,CAAC;AAAA,MACX,QAAQ;AAAA,MAER;AAAA,IACF;AAEA,OAAG,GAAG,WAAW,CAAC,SAAS;AACzB,YAAM,MAAM,OAAO,IAAI;AACvB,UAAI,UAAU,WAAY;AAC1B,UAAI,UAAU,WAAW;AACvB,YAAI,MAAM,SAAS,UAAW,OAAM,KAAK,GAAG;AAC5C;AAAA,MACF;AACA,WAAK,IAAI,cAAc,QAAQ,GAAG,EAAE,MAAM,CAAC,QAAQ,QAAQ,MAAM,iBAAiB,GAAG,CAAC;AAAA,IACxF,CAAC;AACD,OAAG,GAAG,SAAS,MAAM;AACnB,eAAS;AACT,UAAI,UAAU,QAAS,KAAI,iBAAiB,MAAM;AAAA,IACpD,CAAC;AAED,YAAQ,QAAQ,QAAQ,eAAe,QAAQ,aAAa,EAAE,KAAK,KAAK,CAAC,IAAI,EAAE,QAAQ,OAAO,CAAC,EAC5F,KAAK,CAAC,WAAW;AAChB,UAAI,OAAQ;AACZ,UAAI,CAAC,QAAQ;AACX,gBAAQ;AACR,WAAG,MAAM,MAAM,cAAc;AAC7B;AAAA,MACF;AACA,cAAQ;AACR,UAAI,cAAc,EAAE,IAAI,QAAQ,MAAM,QAAQ,OAAO,QAAQ,MAAM,OAAO,MAAM,KAAK,CAAC;AACtF,iBAAW,KAAK,OAAO;AACrB,aAAK,IAAI,cAAc,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,QAAQ,MAAM,iBAAiB,GAAG,CAAC;AAAA,MACtF;AACA,YAAM,SAAS;AAAA,IACjB,CAAC,EACA,MAAM,MAAM;AACX,UAAI,CAAC,QAAQ;AACX,gBAAQ;AACR,WAAG,MAAM,MAAM,cAAc;AAAA,MAC/B;AAAA,IACF,CAAC;AAAA,EACL,CAAC;AACD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,OAAO,MACL,IAAI,QAAc,CAAC,YAAY;AAC7B,UAAI,MAAM;AACV,UAAI,MAAM,MAAM,QAAQ,CAAC;AAAA,IAC3B,CAAC;AAAA,EACL;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fieldnotes/sync-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Authoritative WebSocket relay server for Field Notes real-time sync",
   "type": "module",
   "sideEffects": false,