@fieldnotes/sync-server 0.17.1 → 0.18.0

package/README.md

@@ -184,13 +184,13 @@ authorize(ctx) => boolean | Promise<boolean>
   userId?: string;          // the connection's authenticated user (from authenticate)
   role?: string;            // the connection's role (from authenticate)
   room: string;
-  op: SyncOp;               // the incoming upsert / remove / clear
+  op: WireSyncOp;           // the incoming upsert / remove / clear
   currentElement?: OwnedElement; // the STORED element, if this id already exists
 }
 ```
 
 `currentElement` is the element currently in room state for an `upsert`/`remove` of an
-**existing** id (typed `OwnedElement = CanvasElement & { ownerId?: string }`), and
+**existing** id (typed `OwnedElement = WireSyncElement`), and
 `undefined` for a new/absent id.
 
 **Ownership is server-stamped and un-forgeable.** A new element's `ownerId` is set to the

package/dist/index.cjs

@@ -30,6 +30,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/sync-hub.ts
 var import_sync2 = require("@fieldnotes/sync");
+var import_core = require("@fieldnotes/core");
 
 // src/memory-hub-backend.ts
 var import_sync = require("@fieldnotes/sync");
@@ -98,8 +99,10 @@ var ServerPluginRegistry = class {
   byName = /* @__PURE__ */ new Map();
   legacyOwners = /* @__PURE__ */ new Map();
   extensions = /* @__PURE__ */ new Map();
+  definitions;
   constructor(plugins) {
     for (const plugin of plugins) this.register(plugin);
+    this.definitions = new Map([...this.extensions].map(([name, entry]) => [name, entry.kind]));
   }
   register(plugin) {
     if (this.byName.has(plugin.name))
@@ -131,6 +134,12 @@ var ServerPluginRegistry = class {
   extension(extensionKind) {
     return this.extensions.get(extensionKind);
   }
+  get extensionKinds() {
+    return [...this.extensions.keys()];
+  }
+  get extensionDefinitions() {
+    return this.definitions;
+  }
 };
 
 // src/resource-limits.ts
@@ -193,7 +202,7 @@ function generateInstanceId() {
 function isFanoutOp(op) {
   if (typeof op !== "object" || op === null) return false;
   const o = op;
-  if (o.kind === "upsert") return (0, import_sync2.isValidElement)(o.element);
+  if (o.kind === "upsert") return (0, import_sync2.isValidWireElement)(o.element);
   if (o.kind === "remove") return typeof o.id === "string";
   return o.kind === "clear";
 }
@@ -223,6 +232,9 @@ function layerRecordToOp(record) {
     editor: record.editor
   } : { kind: "layer-remove", id: record.id, version: record.version, editor: record.editor };
 }
+function capabilityProfile(capabilities) {
+  return JSON.stringify([capabilities.elementEnvelope, capabilities.extensionKinds]);
+}
 function isPresenceOp(op) {
   if (typeof op !== "object" || op === null) return false;
   const k = op.kind;
@@ -242,6 +254,8 @@ var SyncHub = class {
   authorize;
   authorizeLayer;
   pluginRegistry;
+  elementRegistry;
+  peerCapabilities = /* @__PURE__ */ new Map();
   canRead;
   memoryLayers = /* @__PURE__ */ new Map();
   maxJsonDepth;
@@ -260,6 +274,7 @@ var SyncHub = class {
   constructor(options = {}) {
     this.backend = options.backend ?? new MemoryHubBackend();
     this.pluginRegistry = new ServerPluginRegistry(options.plugins ?? []);
+    this.elementRegistry = options.elementRegistry ?? (0, import_core.getDefaultElementRegistry)();
     this.instanceId = options.instanceId ?? generateInstanceId();
     this.fanout = options.fanout ?? new InMemoryHubFanout();
     this.authorize = options.authorize;
@@ -287,6 +302,7 @@ var SyncHub = class {
     const conn = this.conns.get(connId);
     if (!conn) return;
     this.conns.delete(connId);
+    this.peerCapabilities.delete(connId);
     const room = conn.room;
     const hadPresence = this.presenceConnections.delete(connId);
     this.clearPresenceLanes(connId);
@@ -320,6 +336,14 @@ var SyncHub = class {
     if (!hasJsonDepthAtMost(message, this.maxJsonDepth)) return Promise.resolve();
     const env = (0, import_sync2.parseEnvelope)(message);
     if (!env) return Promise.resolve();
+    if (env.op.kind === "capabilities") {
+      this.peerCapabilities.set(conn.id, env.op.capabilities);
+      this.sendToConnection(conn, HUB_FROM, {
+        kind: "capabilities",
+        capabilities: (0, import_sync2.createCurrentCapabilities)(this.pluginRegistry.extensionKinds)
+      });
+      return Promise.resolve();
+    }
     if (env.op.kind === "presence") {
       this.schedulePresence(conn, env.op.data);
       return Promise.resolve();
@@ -335,9 +359,14 @@ var SyncHub = class {
     return operation;
   }
   async process(conn, env) {
-    const op = env.op;
+    let op = env.op;
+    if (op.kind === "upsert") {
+      const element = this.normalizeElement(op.element);
+      if (!element) return;
+      op = { ...op, element };
+    }
     if (op.kind === "request-snapshot") {
-      const all = await this.backend.snapshot(conn.room);
+      const all = this.normalizeElements(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 snapshotOp = {
@@ -358,7 +387,7 @@ var SyncHub = class {
         else extensions[plugin.name] = snapshot;
       }
       if (Object.keys(extensions).length > 0) snapshotOp["extensions"] = extensions;
-      conn.send(JSON.stringify({ from: HUB_FROM, op: snapshotOp }));
+      this.sendToConnection(conn, HUB_FROM, snapshotOp);
     } else if (op.kind === "layer-upsert" || op.kind === "layer-remove") {
       await this.processLayerOp(conn, op);
     } else if (op.kind === "extension") {
@@ -376,7 +405,8 @@ var SyncHub = class {
     } 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;
-      const current = needCurrent ? await this.backend.get(conn.room, id) : void 0;
+      const storedCurrent = needCurrent ? await this.backend.get(conn.room, id) : void 0;
+      const current = storedCurrent ? this.normalizeElement(storedCurrent) ?? void 0 : void 0;
       let outboundOp = op;
       if (this.authorize) {
         const allowed = await this.authorize({
@@ -400,7 +430,7 @@ var SyncHub = class {
       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 }));
+        this.sendToConnection(conn, HUB_FROM, correction);
       }
       const accepted = result.accepted;
       if (accepted && (accepted.kind === "upsert" || accepted.kind === "remove" || accepted.kind === "clear")) {
@@ -456,7 +486,7 @@ var SyncHub = class {
   }
   async deliverPluginResult(conn, result) {
     for (const correction of result.corrections) {
-      conn.send(JSON.stringify({ from: HUB_FROM, op: correction }));
+      this.sendToConnection(conn, HUB_FROM, correction);
     }
     if (result.accepted) await this.publishPluginOp(conn, result.accepted, result.locality);
     for (const broadcast of result.broadcast ?? []) {
@@ -469,7 +499,7 @@ var SyncHub = class {
         JSON.stringify({ o: this.instanceId, room: conn.room, from: conn.id, op })
       );
     }
-    this.relayToRoom(conn.room, conn.id, JSON.stringify({ from: conn.id, op }));
+    this.relayOpToRoom(conn.room, conn.id, conn.id, op);
   }
   /**
    * Applies a layer-definition edit on the room's serial queue. Convergence is
@@ -491,19 +521,19 @@ var SyncHub = class {
       });
       if (!allowed) {
         const correction = current ?? { id: record.id, version: record.version, editor: HUB_FROM };
-        conn.send(JSON.stringify({ from: HUB_FROM, op: layerRecordToOp(correction) }));
+        this.sendToConnection(conn, HUB_FROM, layerRecordToOp(correction));
         return;
       }
     }
     if (current && !(0, import_sync2.isNewerLayerRecord)(record, current)) {
-      conn.send(JSON.stringify({ from: HUB_FROM, op: layerRecordToOp(current) }));
+      this.sendToConnection(conn, HUB_FROM, layerRecordToOp(current));
       return;
     }
     await this.applyLayerRecord(conn.room, record);
     await this.fanout.publish(
       JSON.stringify({ o: this.instanceId, room: conn.room, from: conn.id, op })
     );
-    this.relayToRoom(conn.room, conn.id, JSON.stringify({ from: conn.id, op }));
+    this.relayOpToRoom(conn.room, conn.id, conn.id, op);
   }
   layerBackend() {
     const { layerRecords, getLayerRecord, applyLayerRecord } = this.backend;
@@ -564,6 +594,86 @@ var SyncHub = class {
     }
     return sent;
   }
+  /**
+   * Translates `op` for the peer and sends it. Returns false when the op is
+   * lossy for this peer (no legacy encoding) or the socket throws; neither
+   * may reject the room operation that produced it.
+   */
+  sendToConnection(conn, from, op, encoded) {
+    const capabilities = this.peerCapabilities.get(conn.id) ?? (0, import_sync2.createLegacyCapabilities)();
+    const profile = encoded ? capabilityProfile(capabilities) : void 0;
+    let message = profile === void 0 ? void 0 : encoded?.get(profile);
+    if (message === void 0) {
+      message = this.encodeForPeer(from, op, capabilities);
+      if (profile !== void 0) encoded?.set(profile, message);
+    }
+    if (message === null) return false;
+    try {
+      conn.send(message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Returns the wire frame for `op` translated for `capabilities`, or null when lossy. */
+  encodeForPeer(from, op, capabilities) {
+    try {
+      const translated = (0, import_sync2.translateOpForPeer)(
+        op,
+        capabilities,
+        this.elementRegistry,
+        this.pluginRegistry.extensionDefinitions
+      );
+      return JSON.stringify({ from, op: translated });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Normalize registered legacy wire elements before authorization, storage,
+   * and relay. A legacy type this hub has no adapter for is forwarded and
+   * stored verbatim — the hub is a relay, and the peers decide whether they
+   * understand it — so a hub deployed without domain adapters never erases
+   * the room's existing elements. Only a malformed registered element is dropped.
+   */
+  normalizeElement(element) {
+    if ((0, import_sync2.isValidElement)(element)) return element;
+    const adapter = this.elementRegistry.getAdapterByLegacyType(element.type);
+    if (!adapter) return element;
+    try {
+      const raw = Object.fromEntries(Object.entries(element));
+      const envelope = adapter.decodeLegacy(raw);
+      if (!adapter.validateEnvelope(envelope)) return null;
+      return {
+        ...envelope,
+        ...typeof raw["audience"] === "string" ? { audience: raw["audience"] } : {},
+        ...typeof raw["ownerId"] === "string" ? { ownerId: raw["ownerId"] } : {}
+      };
+    } catch {
+      return null;
+    }
+  }
+  normalizeElements(elements) {
+    const normalized = [];
+    for (const element of elements) {
+      const runtime = this.normalizeElement(element);
+      if (runtime) normalized.push(runtime);
+    }
+    return normalized;
+  }
+  relayOpToRoom(room, excludeId, from, op) {
+    const members = this.rooms.get(room);
+    if (!members) return 0;
+    let sent = 0;
+    const encoded = /* @__PURE__ */ new Map();
+    for (const connectionId of members) {
+      if (connectionId === excludeId) continue;
+      const conn = this.conns.get(connectionId);
+      if (!conn) continue;
+      if (this.sendToConnection(conn, from, op, encoded)) sent += 1;
+    }
+    return sent;
+  }
   broadcastClientPresence(conn, data) {
     this.presenceConnections.add(conn.id);
     const message = JSON.stringify({ from: conn.id, op: { kind: "presence", data } });
@@ -645,41 +755,33 @@ var SyncHub = class {
   deliverToRoom(room, excludeId, from, op, prevAudience, prevExisted) {
     const members = this.rooms.get(room);
     if (!members) return;
-    const send = (conn, msg) => {
-      try {
-        conn.send(msg);
-      } catch {
-      }
-    };
+    const encoded = /* @__PURE__ */ new Map();
     if (op.kind === "upsert") {
       const audience = op.element.audience;
-      const upsertMsg = JSON.stringify({ from, op });
-      const removeMsg = JSON.stringify({
-        from: HUB_FROM,
-        op: { kind: "remove", id: op.element.id }
-      });
+      const removeOp = { kind: "remove", id: op.element.id };
+      const encodedRemove = /* @__PURE__ */ new Map();
       for (const cid of members) {
         if (cid === excludeId) continue;
         const conn = this.conns.get(cid);
         if (!conn) continue;
-        if (this.mayRead(conn, audience)) send(conn, upsertMsg);
-        else if (prevExisted && this.mayRead(conn, prevAudience)) send(conn, removeMsg);
+        if (this.mayRead(conn, audience)) this.sendToConnection(conn, from, op, encoded);
+        else if (prevExisted && this.mayRead(conn, prevAudience)) {
+          this.sendToConnection(conn, HUB_FROM, removeOp, encodedRemove);
+        }
       }
     } else if (op.kind === "remove") {
-      const removeMsg = JSON.stringify({ from, op });
       for (const cid of members) {
         if (cid === excludeId) continue;
         const conn = this.conns.get(cid);
         if (!conn) continue;
         const wasVisible = !this.canRead || prevExisted && this.mayRead(conn, prevAudience);
-        if (wasVisible) send(conn, removeMsg);
+        if (wasVisible) this.sendToConnection(conn, from, op, encoded);
       }
     } else if (op.kind === "clear") {
-      const clearMsg = JSON.stringify({ from, op });
       for (const cid of members) {
         if (cid === excludeId) continue;
         const conn = this.conns.get(cid);
-        if (conn) send(conn, clearMsg);
+        if (conn) this.sendToConnection(conn, from, op, encoded);
       }
     }
   }
@@ -690,11 +792,11 @@ var SyncHub = class {
     } else if (op.kind === "remove") {
       correction = current ? this.mayRead(conn, current.audience) ? { kind: "upsert", element: current } : { kind: "remove", id: current.id } : void 0;
     } else if (op.kind === "clear") {
-      const all = await this.backend.snapshot(conn.room);
+      const all = this.normalizeElements(await this.backend.snapshot(conn.room));
       const elements = this.canRead ? all.filter((el) => this.mayRead(conn, el.audience)) : all;
       correction = { kind: "snapshot", to: from, elements };
     }
-    if (correction) conn.send(JSON.stringify({ from: HUB_FROM, op: correction }));
+    if (correction) this.sendToConnection(conn, HUB_FROM, correction);
   }
   onFanout(payload) {
     let env;
@@ -714,7 +816,7 @@ var SyncHub = class {
     if (isLayerOp(op)) {
       void this.applyFanoutLayerOp(env.room, op).catch(() => {
       });
-      this.relayToRoom(env.room, void 0, JSON.stringify({ from: env.from, op }));
+      this.relayOpToRoom(env.room, void 0, env.from, op);
       return;
     }
     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;
@@ -729,11 +831,7 @@ var SyncHub = class {
         };
         const accepted = plugin.applyFanout ? await plugin.applyFanout(op, context) : op;
         if (accepted) {
-          this.relayToRoom(
-            env.room,
-            void 0,
-            JSON.stringify({ from: env.from, op: accepted })
-          );
+          this.relayOpToRoom(env.room, void 0, env.from, accepted);
         }
       });
       this.roomQueues.set(
@@ -744,9 +842,14 @@ var SyncHub = class {
       return;
     }
     if (!isFanoutOp(op)) return;
+    const runtimeOp = op.kind === "upsert" ? (() => {
+      const element = this.normalizeElement(op.element);
+      return element ? { ...op, element } : null;
+    })() : op;
+    if (!runtimeOp) return;
     const prevAudience = typeof env.prev === "string" ? env.prev : void 0;
     const prevExisted = env.existed === true;
-    this.deliverToRoom(env.room, void 0, env.from, op, prevAudience, prevExisted);
+    this.deliverToRoom(env.room, void 0, env.from, runtimeOp, prevAudience, prevExisted);
   }
   async applyFanoutLayerOp(room, op) {
     const record = layerOpToRecord(op);
@@ -848,7 +951,8 @@ function createSyncServer(options = {}) {
     canRead: options.canRead,
     maxJsonDepth: options.maxJsonDepth ?? DEFAULT_MAX_JSON_DEPTH,
     presenceThrottleMs: options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS,
-    maxPresenceLanes: options.maxPresenceLanes
+    maxPresenceLanes: options.maxPresenceLanes,
+    elementRegistry: options.elementRegistry
   });
   const maxMessageBytes = options.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
   const wss = options.server ? new import_ws.WebSocketServer({ server: options.server, maxPayload: maxMessageBytes }) : new import_ws.WebSocketServer({ port: options.port ?? 0, maxPayload: maxMessageBytes });