@fieldnotes/sync-server 0.16.0 → 0.17.0

package/dist/index.cjs

@@ -36,7 +36,6 @@ var import_sync = require("@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) {
@@ -75,26 +74,6 @@ 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 import_sync.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
@@ -114,6 +93,46 @@ var InMemoryHubFanout = class {
   }
 };
 
+// src/sync-plugin.ts
+var ServerPluginRegistry = class {
+  byName = /* @__PURE__ */ new Map();
+  legacyOwners = /* @__PURE__ */ new Map();
+  extensions = /* @__PURE__ */ new Map();
+  constructor(plugins) {
+    for (const plugin of plugins) this.register(plugin);
+  }
+  register(plugin) {
+    if (this.byName.has(plugin.name))
+      throw new Error(`Server plugin "${plugin.name}" is duplicated`);
+    this.byName.set(plugin.name, plugin);
+    for (const kind of plugin.ownedLegacyKinds ?? []) {
+      if (this.legacyOwners.has(kind)) throw new Error(`Sync op kind "${kind}" has two owners`);
+      this.legacyOwners.set(kind, plugin);
+    }
+    plugin.registerExtensionKinds?.({
+      register: (kind, handler) => {
+        if (this.extensions.has(kind.extensionKind)) {
+          throw new Error(`Extension kind "${kind.extensionKind}" has two owners`);
+        }
+        this.extensions.set(kind.extensionKind, {
+          kind,
+          plugin,
+          handler
+        });
+      }
+    });
+  }
+  get plugins() {
+    return [...this.byName.values()];
+  }
+  ownerOf(kind) {
+    return this.legacyOwners.get(kind);
+  }
+  extension(extensionKind) {
+    return this.extensions.get(extensionKind);
+  }
+};
+
 // src/resource-limits.ts
 var DEFAULT_MAX_MESSAGE_BYTES = 1024 * 1024;
 var DEFAULT_MAX_JSON_DEPTH = 32;
@@ -209,11 +228,6 @@ 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();
@@ -227,10 +241,9 @@ var SyncHub = class {
   fanoutUnsub;
   authorize;
   authorizeLayer;
-  authorizeFog;
+  pluginRegistry;
   canRead;
   memoryLayers = /* @__PURE__ */ new Map();
-  memoryFog = /* @__PURE__ */ new Map();
   maxJsonDepth;
   presenceThrottleMs;
   maxPresenceLanes;
@@ -246,21 +259,11 @@ var SyncHub = class {
   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.pluginRegistry = new ServerPluginRegistry(options.plugins ?? []);
     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;
@@ -337,19 +340,39 @@ 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);
-      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;
+      const extensions = {};
+      for (const plugin of this.pluginRegistry.plugins) {
+        let snapshot = await plugin.snapshot?.(conn.room, this.backend);
+        if (!snapshot) continue;
+        if (plugin.filterSnapshot) {
+          snapshot = plugin.filterSnapshot(snapshot, { userId: conn.userId, role: conn.role }) ?? void 0;
+        }
+        if (!snapshot) continue;
+        if (plugin.legacySnapshotKey) snapshotOp[plugin.legacySnapshotKey] = snapshot.data;
+        else extensions[plugin.name] = snapshot;
+      }
+      if (Object.keys(extensions).length > 0) snapshotOp["extensions"] = extensions;
       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 === "extension") {
+      const entry = this.pluginRegistry.extension(op.extensionKind);
+      if (!entry || !entry.kind.codec.validate(op.payload)) return;
+      await this.deliverPluginResult(conn, await entry.handler(op, this.pluginContext(conn)));
+    } else if (this.pluginRegistry.ownerOf(op.kind)) {
+      const owner = this.pluginRegistry.ownerOf(op.kind);
+      if (!owner?.process) return;
+      const result = await owner.process(op, this.pluginContext(conn), async () => ({
+        accepted: null,
+        corrections: []
+      }));
+      await this.deliverPluginResult(conn, result);
     } 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;
@@ -373,21 +396,80 @@ var SyncHub = class {
           outboundOp = { kind: "upsert", element: stampedElement };
         }
       }
-      await this.backend.apply(conn.room, outboundOp);
       const prevExisted = current !== void 0;
       const prevAudience = current?.audience;
+      const result = await this.runCorePlugins(conn, outboundOp);
+      for (const correction of result.corrections) {
+        conn.send(JSON.stringify({ from: HUB_FROM, op: correction }));
+      }
+      const accepted = result.accepted;
+      if (accepted && (accepted.kind === "upsert" || accepted.kind === "remove" || accepted.kind === "clear")) {
+        if (result.locality !== "local") {
+          await this.fanout.publish(
+            JSON.stringify({
+              o: this.instanceId,
+              room: conn.room,
+              from: conn.id,
+              op: accepted,
+              prev: prevAudience,
+              existed: prevExisted
+            })
+          );
+        }
+        this.deliverToRoom(conn.room, conn.id, conn.id, accepted, prevAudience, prevExisted);
+      }
+      for (const broadcast of result.broadcast ?? []) {
+        await this.publishPluginOp(conn, broadcast, result.locality);
+      }
+    }
+  }
+  pluginContext(conn) {
+    return {
+      room: conn.room,
+      connectionId: conn.id,
+      userId: conn.userId,
+      role: conn.role,
+      backend: this.backend,
+      backendPlugin: (key) => this.backend.getService?.(key)
+    };
+  }
+  async runCorePlugins(conn, op) {
+    const middleware = this.pluginRegistry.plugins.filter((plugin) => plugin.process);
+    const context = this.pluginContext(conn);
+    const dispatch = async (index, current) => {
+      const plugin = middleware[index];
+      if (!plugin?.process) {
+        await this.backend.apply(conn.room, current);
+        return { accepted: current, corrections: [] };
+      }
+      let called = false;
+      return plugin.process(current, context, async (nextOp, nextContext) => {
+        if (called) throw new Error(`Server plugin "${plugin.name}" called next() more than once`);
+        if (nextContext !== context) {
+          throw new Error(`Server plugin "${plugin.name}" replaced the operation context`);
+        }
+        called = true;
+        return dispatch(index + 1, nextOp);
+      });
+    };
+    return dispatch(0, op);
+  }
+  async deliverPluginResult(conn, result) {
+    for (const correction of result.corrections) {
+      conn.send(JSON.stringify({ from: HUB_FROM, op: correction }));
+    }
+    if (result.accepted) await this.publishPluginOp(conn, result.accepted, result.locality);
+    for (const broadcast of result.broadcast ?? []) {
+      await this.publishPluginOp(conn, broadcast, result.locality);
+    }
+  }
+  async publishPluginOp(conn, op, locality) {
+    if (locality !== "local") {
       await this.fanout.publish(
-        JSON.stringify({
-          o: this.instanceId,
-          room: conn.room,
-          from: conn.id,
-          op: outboundOp,
-          prev: prevAudience,
-          existed: prevExisted
-        })
+        JSON.stringify({ o: this.instanceId, room: conn.room, from: conn.id, op })
       );
-      this.deliverToRoom(conn.room, conn.id, conn.id, outboundOp, prevAudience, prevExisted);
     }
+    this.relayToRoom(conn.room, conn.id, JSON.stringify({ from: conn.id, op }));
   }
   /**
    * Applies a layer-definition edit on the room's serial queue. Convergence is
@@ -455,121 +537,6 @@ 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 import_sync2.FogLedger();
-      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 });
@@ -750,10 +717,17 @@ var SyncHub = class {
       this.relayToRoom(env.room, void 0, JSON.stringify({ from: env.from, op }));
       return;
     }
-    if (isFogOp(op)) {
+    const plugin = typeof op === "object" && op !== null && op.kind === "extension" ? this.pluginRegistry.extension(op.extensionKind ?? "")?.plugin : typeof op === "object" && op !== null && typeof op.kind === "string" ? this.pluginRegistry.ownerOf(op.kind) : void 0;
+    if (plugin && typeof op === "object" && op !== null) {
       const previous = this.roomQueues.get(env.room) ?? Promise.resolve();
       const operation = previous.then(async () => {
-        const accepted = await this.applyFanoutFogOp(env.room, op);
+        const context = {
+          room: env.room,
+          connectionId: env.from,
+          backend: this.backend,
+          backendPlugin: (key) => this.backend.getService?.(key)
+        };
+        const accepted = plugin.applyFanout ? await plugin.applyFanout(op, context) : op;
         if (accepted) {
           this.relayToRoom(
             env.room,
@@ -780,15 +754,6 @@ var SyncHub = class {
     if (current && !(0, import_sync2.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 connId of [...this.presenceLanes.keys()]) this.clearPresenceLanes(connId);
     this.fanoutUnsub();
@@ -879,7 +844,7 @@ function createSyncServer(options = {}) {
     instanceId: options.instanceId,
     authorize: options.authorize,
     authorizeLayer: options.authorizeLayer,
-    authorizeFog: options.authorizeFog,
+    plugins: options.plugins,
     canRead: options.canRead,
     maxJsonDepth: options.maxJsonDepth ?? DEFAULT_MAX_JSON_DEPTH,
     presenceThrottleMs: options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS,