@fieldnotes/sync-server 0.12.0 → 0.14.0

package/dist/index.js

@@ -2,14 +2,19 @@
 import {
   parseEnvelope,
   isValidElement,
-  isNewerLayerRecord
+  isNewerLayerRecord,
+  FogLedger as FogLedger2
 } from "@fieldnotes/sync";
 
 // src/memory-hub-backend.ts
-import { applyOpToMap } from "@fieldnotes/sync";
+import {
+  applyOpToMap,
+  FogLedger
+} from "@fieldnotes/sync";
 var MemoryHubBackend = class {
   rooms = /* @__PURE__ */ new Map();
   roomLayers = /* @__PURE__ */ new Map();
+  roomFog = /* @__PURE__ */ new Map();
   room(id) {
     let r = this.rooms.get(id);
     if (!r) {
@@ -48,6 +53,26 @@ var MemoryHubBackend = class {
   async applyLayerRecord(room, record) {
     this.layers(room).set(record.id, record);
   }
+  fog(room) {
+    let ledger = this.roomFog.get(room);
+    if (!ledger) {
+      ledger = new FogLedger();
+      this.roomFog.set(room, ledger);
+    }
+    return ledger;
+  }
+  async fogSnapshot(room) {
+    return this.fog(room).snapshot();
+  }
+  async applyFogMeta(room, record) {
+    return this.fog(room).applyMeta(record);
+  }
+  async applyFogTile(room, record) {
+    return this.fog(room).applyTile(record);
+  }
+  async applyFogPatch(room, records) {
+    return this.fog(room).applyPatch(records);
+  }
 };
 
 // src/hub-fanout.ts
@@ -75,6 +100,7 @@ var DEFAULT_MAX_PENDING_AUTH_BYTES = 2 * 1024 * 1024;
 var DEFAULT_MESSAGES_PER_SECOND = 120;
 var DEFAULT_MESSAGE_BURST = 240;
 var DEFAULT_PRESENCE_THROTTLE_MS = 50;
+var DEFAULT_MAX_PRESENCE_LANES = 16;
 function hasJsonDepthAtMost(message, maxDepth) {
   let depth = 0;
   let inString = false;
@@ -130,6 +156,16 @@ function isFanoutOp(op) {
   if (o.kind === "remove") return typeof o.id === "string";
   return o.kind === "clear";
 }
+var FALLBACK_PRESENCE_LANE = "";
+var MAX_PRESENCE_LANE_LENGTH = 64;
+function presenceLaneOf(data) {
+  if (typeof data !== "object" || data === null) return FALLBACK_PRESENCE_LANE;
+  const kind = data.kind;
+  if (typeof kind !== "string" || kind.length === 0 || kind.length > MAX_PRESENCE_LANE_LENGTH) {
+    return FALLBACK_PRESENCE_LANE;
+  }
+  return kind;
+}
 function isLayerOp(op) {
   if (typeof op !== "object" || op === null) return false;
   const k = op.kind;
@@ -151,6 +187,11 @@ function isPresenceOp(op) {
   const k = op.kind;
   return k === "presence" || k === "presence-leave";
 }
+function isFogOp(op) {
+  if (typeof op !== "object" || op === null) return false;
+  const k = op.kind;
+  return k === "fog-meta" || k === "fog-patch";
+}
 var SyncHub = class {
   backend;
   conns = /* @__PURE__ */ new Map();
@@ -164,22 +205,48 @@ var SyncHub = class {
   fanoutUnsub;
   authorize;
   authorizeLayer;
+  authorizeFog;
   canRead;
-  /** Fallback layer-record store for backends without layer persistence. */
   memoryLayers = /* @__PURE__ */ new Map();
+  memoryFog = /* @__PURE__ */ new Map();
   maxJsonDepth;
   presenceThrottleMs;
-  lastPresenceAt = /* @__PURE__ */ new Map();
-  pendingPresence = /* @__PURE__ */ new Map();
+  maxPresenceLanes;
+  /**
+   * Presence throttle state keyed by connection, then by lane. A lane is the
+   * payload's `kind` (a non-empty string of at most 64 chars) or the reserved
+   * fallback lane `''`, so a rapid stream of one kind (awareness cursors) can
+   * never replace a pending frame of another kind (a ping, a path `cleared`).
+   * Within a lane the newest payload wins. The lane count per connection is
+   * capped by `maxPresenceLanes`, counting the fallback lane, so a client
+   * cannot mint timers by varying `kind`.
+   */
+  presenceLanes = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.backend = options.backend ?? new MemoryHubBackend();
+    const fogMethods = [
+      this.backend.fogSnapshot,
+      this.backend.applyFogMeta,
+      this.backend.applyFogPatch
+    ];
+    if ((fogMethods.some(Boolean) || Boolean(this.backend.applyFogTile)) && !fogMethods.every(Boolean)) {
+      throw new Error(
+        "HubBackend fog support is an all-or-none capability: fogSnapshot, applyFogMeta, and applyFogPatch are required"
+      );
+    }
     this.instanceId = options.instanceId ?? generateInstanceId();
     this.fanout = options.fanout ?? new InMemoryHubFanout();
     this.authorize = options.authorize;
     this.authorizeLayer = options.authorizeLayer;
+    this.authorizeFog = options.authorizeFog;
     this.canRead = options.canRead;
     this.maxJsonDepth = options.maxJsonDepth ?? DEFAULT_MAX_JSON_DEPTH;
     this.presenceThrottleMs = options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS;
+    const maxPresenceLanes = options.maxPresenceLanes ?? DEFAULT_MAX_PRESENCE_LANES;
+    if (!Number.isFinite(maxPresenceLanes) || maxPresenceLanes < 1) {
+      throw new RangeError("maxPresenceLanes must be a finite number of at least 1");
+    }
+    this.maxPresenceLanes = Math.floor(maxPresenceLanes);
     this.fanoutUnsub = this.fanout.subscribe((payload) => this.onFanout(payload));
   }
   addConnection(conn) {
@@ -197,10 +264,7 @@ var SyncHub = class {
     this.conns.delete(connId);
     const room = conn.room;
     const hadPresence = this.presenceConnections.delete(connId);
-    this.lastPresenceAt.delete(connId);
-    const pendingPresence = this.pendingPresence.get(connId);
-    if (pendingPresence) clearTimeout(pendingPresence.timer);
-    this.pendingPresence.delete(connId);
+    this.clearPresenceLanes(connId);
     const members = this.rooms.get(room);
     if (members) {
       members.delete(connId);
@@ -251,16 +315,19 @@ var SyncHub = class {
       const all = await this.backend.snapshot(conn.room);
       const elements = this.canRead ? all.filter((el) => this.mayRead(conn, el.audience)) : all;
       const layers = await this.getLayerRecords(conn.room);
-      conn.send(
-        // `to` is a private correlation address for the requesting SyncClient. It is never
-        // broadcast; every public sender identity below comes from the server-owned connection.
-        JSON.stringify({
-          from: HUB_FROM,
-          op: layers.length > 0 ? { kind: "snapshot", to: env.from, elements, layers } : { kind: "snapshot", to: env.from, elements }
-        })
-      );
+      const fog = await this.getFogSnapshot(conn.room);
+      const snapshotOp = {
+        kind: "snapshot",
+        to: env.from,
+        elements
+      };
+      if (layers.length > 0) snapshotOp["layers"] = layers;
+      if (fog) snapshotOp["fog"] = fog;
+      conn.send(JSON.stringify({ from: HUB_FROM, op: snapshotOp }));
     } else if (op.kind === "layer-upsert" || op.kind === "layer-remove") {
       await this.processLayerOp(conn, op);
+    } else if (op.kind === "fog-meta" || op.kind === "fog-patch") {
+      await this.processFogOp(conn, op);
     } else if (op.kind === "upsert" || op.kind === "remove" || op.kind === "clear") {
       const id = op.kind === "upsert" ? op.element.id : op.kind === "remove" ? op.id : void 0;
       const needCurrent = (this.authorize || this.canRead) && id !== void 0;
@@ -366,6 +433,121 @@ var SyncHub = class {
     }
     map.set(record.id, record);
   }
+  // ── Fog processing ──
+  fogBackend() {
+    const { fogSnapshot, applyFogMeta, applyFogPatch } = this.backend;
+    if (!fogSnapshot || !applyFogMeta || !applyFogPatch) return null;
+    return {
+      fogSnapshot: fogSnapshot.bind(this.backend),
+      applyFogMeta: applyFogMeta.bind(this.backend),
+      applyFogPatch: applyFogPatch.bind(this.backend)
+    };
+  }
+  getFogLedger(room) {
+    let ledger = this.memoryFog.get(room);
+    if (!ledger) {
+      ledger = new FogLedger2();
+      this.memoryFog.set(room, ledger);
+    }
+    return ledger;
+  }
+  async getFogSnapshot(room) {
+    const backend = this.fogBackend();
+    if (backend) return backend.fogSnapshot(room);
+    return this.getFogLedger(room).snapshot();
+  }
+  async applyFogMeta(room, record) {
+    const backend = this.fogBackend();
+    if (backend) return backend.applyFogMeta(room, record);
+    return this.getFogLedger(room).applyMeta(record);
+  }
+  async applyFogPatch(room, records) {
+    const backend = this.fogBackend();
+    if (backend) return backend.applyFogPatch(room, records);
+    return this.getFogLedger(room).applyPatch(records);
+  }
+  async processFogOp(conn, op) {
+    const current = await this.getFogSnapshot(conn.room);
+    if (this.authorizeFog) {
+      const allowed = await this.authorizeFog({
+        userId: conn.userId,
+        role: conn.role,
+        room: conn.room,
+        op,
+        current
+      });
+      if (!allowed) {
+        if (op.kind === "fog-meta") {
+          const correction = current?.meta ?? { version: 1, editor: HUB_FROM };
+          conn.send(
+            JSON.stringify({ from: HUB_FROM, op: { kind: "fog-meta", record: correction } })
+          );
+        } else if (current?.meta.definition) {
+          const corrections = op.tiles.map((t) => {
+            const existing = current.tiles.find((ct) => ct.x === t.x && ct.y === t.y);
+            return existing ?? {
+              generation: current.meta.definition?.generation ?? op.generation,
+              x: t.x,
+              y: t.y,
+              version: 1,
+              editor: HUB_FROM
+            };
+          });
+          conn.send(
+            JSON.stringify({
+              from: HUB_FROM,
+              op: {
+                kind: "fog-patch",
+                generation: current.meta.definition.generation,
+                tiles: corrections
+              }
+            })
+          );
+        } else {
+          conn.send(
+            JSON.stringify({
+              from: HUB_FROM,
+              op: {
+                kind: "fog-meta",
+                record: current?.meta ?? { version: 1, editor: HUB_FROM }
+              }
+            })
+          );
+        }
+        return;
+      }
+    }
+    let outbound;
+    if (op.kind === "fog-meta") {
+      const result = await this.applyFogMeta(conn.room, op.record);
+      if (!result.accepted) {
+        if (result.correction) {
+          conn.send(
+            JSON.stringify({ from: HUB_FROM, op: { kind: "fog-meta", record: result.correction } })
+          );
+        }
+        return;
+      }
+      outbound = op;
+    } else {
+      const { accepted, corrections } = await this.applyFogPatch(conn.room, op.tiles);
+      if (corrections.length > 0) {
+        const correctionGeneration = corrections[0]?.generation ?? op.generation;
+        conn.send(
+          JSON.stringify({
+            from: HUB_FROM,
+            op: { kind: "fog-patch", generation: correctionGeneration, tiles: corrections }
+          })
+        );
+      }
+      if (accepted.length === 0) return;
+      outbound = { kind: "fog-patch", generation: op.generation, tiles: accepted };
+    }
+    await this.fanout.publish(
+      JSON.stringify({ o: this.instanceId, room: conn.room, from: conn.id, op: outbound })
+    );
+    this.relayToRoom(conn.room, conn.id, JSON.stringify({ from: conn.id, op: outbound }));
+  }
   mayRead(conn, audience) {
     if (!this.canRead) return true;
     return this.canRead({ userId: conn.userId, role: conn.role, room: conn.room, audience });
@@ -406,34 +588,63 @@ var SyncHub = class {
       })
     );
   }
+  clearPresenceLanes(connId) {
+    const lanes = this.presenceLanes.get(connId);
+    if (!lanes) return;
+    for (const lane of lanes.values()) {
+      if (lane.pending) clearTimeout(lane.pending.timer);
+    }
+    this.presenceLanes.delete(connId);
+  }
   schedulePresence(conn, data) {
     if (this.presenceThrottleMs <= 0) {
       this.broadcastClientPresence(conn, data);
       return;
     }
+    const lane = this.presenceLaneFor(conn.id, presenceLaneOf(data));
     const now = Date.now();
-    const lastSentAt = this.lastPresenceAt.get(conn.id);
-    if (lastSentAt === void 0 || now - lastSentAt >= this.presenceThrottleMs) {
-      this.lastPresenceAt.set(conn.id, now);
+    if (lane.lastSentAt === void 0 || now - lane.lastSentAt >= this.presenceThrottleMs) {
+      if (lane.pending) {
+        clearTimeout(lane.pending.timer);
+        lane.pending = null;
+      }
+      lane.lastSentAt = now;
       this.broadcastClientPresence(conn, data);
       return;
     }
-    const existing = this.pendingPresence.get(conn.id);
-    if (existing) {
-      existing.data = data;
+    if (lane.pending) {
+      lane.pending.data = data;
       return;
     }
     const timer = setTimeout(
       () => {
-        const pending = this.pendingPresence.get(conn.id);
-        this.pendingPresence.delete(conn.id);
+        const pending = lane.pending;
+        lane.pending = null;
         if (!pending || !this.conns.has(conn.id)) return;
-        this.lastPresenceAt.set(conn.id, Date.now());
+        lane.lastSentAt = Date.now();
         this.broadcastClientPresence(conn, pending.data);
       },
-      this.presenceThrottleMs - (now - lastSentAt)
+      this.presenceThrottleMs - (now - lane.lastSentAt)
     );
-    this.pendingPresence.set(conn.id, { data, timer });
+    lane.pending = { data, timer };
+  }
+  presenceLaneFor(connId, requested) {
+    let lanes = this.presenceLanes.get(connId);
+    if (!lanes) {
+      lanes = /* @__PURE__ */ new Map();
+      this.presenceLanes.set(connId, lanes);
+    }
+    let key = requested;
+    if (key !== FALLBACK_PRESENCE_LANE && !lanes.has(key)) {
+      const named = lanes.size - (lanes.has(FALLBACK_PRESENCE_LANE) ? 1 : 0);
+      if (named >= this.maxPresenceLanes - 1) key = FALLBACK_PRESENCE_LANE;
+    }
+    let lane = lanes.get(key);
+    if (!lane) {
+      lane = { lastSentAt: void 0, pending: null };
+      lanes.set(key, lane);
+    }
+    return lane;
   }
   broadcastLeave(room, from) {
     const message = JSON.stringify({ from, op: { kind: "presence-leave" } });
@@ -517,6 +728,25 @@ var SyncHub = class {
       this.relayToRoom(env.room, void 0, JSON.stringify({ from: env.from, op }));
       return;
     }
+    if (isFogOp(op)) {
+      const previous = this.roomQueues.get(env.room) ?? Promise.resolve();
+      const operation = previous.then(async () => {
+        const accepted = await this.applyFanoutFogOp(env.room, op);
+        if (accepted) {
+          this.relayToRoom(
+            env.room,
+            void 0,
+            JSON.stringify({ from: env.from, op: accepted })
+          );
+        }
+      });
+      this.roomQueues.set(
+        env.room,
+        operation.catch(() => {
+        })
+      );
+      return;
+    }
     if (!isFanoutOp(op)) return;
     const prevAudience = typeof env.prev === "string" ? env.prev : void 0;
     const prevExisted = env.existed === true;
@@ -528,9 +758,17 @@ var SyncHub = class {
     if (current && !isNewerLayerRecord(record, current)) return;
     await this.applyLayerRecord(room, record);
   }
+  async applyFanoutFogOp(room, op) {
+    if (this.backend.sharedAcrossInstances === true && this.fogBackend()) return op;
+    if (op.kind === "fog-meta") {
+      const result = await this.applyFogMeta(room, op.record);
+      return result.accepted ? op : null;
+    }
+    const { accepted } = await this.applyFogPatch(room, op.tiles);
+    return accepted.length > 0 ? { ...op, tiles: accepted } : null;
+  }
   close() {
-    for (const pending of this.pendingPresence.values()) clearTimeout(pending.timer);
-    this.pendingPresence.clear();
+    for (const connId of [...this.presenceLanes.keys()]) this.clearPresenceLanes(connId);
     this.fanoutUnsub();
   }
 };
@@ -619,9 +857,11 @@ function createSyncServer(options = {}) {
     instanceId: options.instanceId,
     authorize: options.authorize,
     authorizeLayer: options.authorizeLayer,
+    authorizeFog: options.authorizeFog,
     canRead: options.canRead,
     maxJsonDepth: options.maxJsonDepth ?? DEFAULT_MAX_JSON_DEPTH,
-    presenceThrottleMs: options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS
+    presenceThrottleMs: options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS,
+    maxPresenceLanes: options.maxPresenceLanes
   });
   const maxMessageBytes = options.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
   const wss = options.server ? new WebSocketServer({ server: options.server, maxPayload: maxMessageBytes }) : new WebSocketServer({ port: options.port ?? 0, maxPayload: maxMessageBytes });