@fieldnotes/sync-server 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { CanvasElement, ServiceKey } from '@fieldnotes/core';
-import { SyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
+import { ServiceKey, ElementRegistry } from '@fieldnotes/core';
+import { WireSyncElement, WireSyncOp, LayerRecord, ExtensionKind, TypedExtensionOp, PluginSnapshot } from '@fieldnotes/sync';
 export { PluginSnapshot } from '@fieldnotes/sync';
 import { WebSocketServer } from 'ws';
 import { IncomingMessage, Server } from 'http';
@@ -18,24 +18,21 @@ declare class InMemoryHubFanout implements HubFanout {
 interface HubBackend {
     /** True when every hub instance addresses the same atomic backing state (for example Redis). */
     readonly sharedAcrossInstances?: boolean;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords?(room: string): Promise<LayerRecord[]>;
     getLayerRecord?(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord?(room: string, record: LayerRecord): Promise<void>;
     getService?<T>(key: ServiceKey<T>): T | undefined;
 }
 
-type OwnedElement = CanvasElement & {
-    ownerId?: string;
-    audience?: string;
-};
+type OwnedElement = WireSyncElement;
 interface AuthorizeContext {
     userId?: string;
     role?: string;
     room: string;
-    op: SyncOp;
+    op: WireSyncOp;
     currentElement?: OwnedElement;
 }
 type Authorize = (ctx: AuthorizeContext) => boolean | Promise<boolean>;
@@ -43,7 +40,7 @@ interface AuthorizeLayerContext {
     userId?: string;
     role?: string;
     room: string;
-    op: Extract<SyncOp, {
+    op: Extract<WireSyncOp, {
         kind: 'layer-upsert' | 'layer-remove';
     }>;
     /** The hub's current record for the target layer, tombstones included. */
@@ -65,9 +62,9 @@ interface ReadContext {
 type CanRead = (ctx: ReadContext) => boolean;
 
 interface ApplyResult {
-    readonly accepted: SyncOp | null;
-    readonly corrections: SyncOp[];
-    readonly broadcast?: SyncOp[];
+    readonly accepted: WireSyncOp | null;
+    readonly corrections: WireSyncOp[];
+    readonly broadcast?: WireSyncOp[];
     readonly locality?: 'shared' | 'local';
 }
 interface ServerOpContext {
@@ -78,7 +75,7 @@ interface ServerOpContext {
     readonly backend: HubBackend;
     backendPlugin<T>(key: ServiceKey<T>): T | undefined;
 }
-type ServerNext = (op: SyncOp, context: ServerOpContext) => Promise<ApplyResult>;
+type ServerNext = (op: WireSyncOp, context: ServerOpContext) => Promise<ApplyResult>;
 interface ServerExtensionRegistry {
     register<TPayload>(kind: ExtensionKind<TPayload>, handler: (op: TypedExtensionOp<TPayload>, context: ServerOpContext) => Promise<ApplyResult>): void;
 }
@@ -86,8 +83,8 @@ interface ServerSyncPlugin {
     readonly name: string;
     readonly ownedLegacyKinds?: readonly string[];
     readonly legacySnapshotKey?: string;
-    process?(op: SyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
-    applyFanout?(op: SyncOp, context: ServerOpContext): Promise<SyncOp | null>;
+    process?(op: WireSyncOp, context: ServerOpContext, next: ServerNext): Promise<ApplyResult>;
+    applyFanout?(op: WireSyncOp, context: ServerOpContext): Promise<WireSyncOp | null>;
     registerExtensionKinds?(registry: ServerExtensionRegistry): void;
     snapshot?(room: string, backend: HubBackend): Promise<PluginSnapshot | undefined>;
     filterSnapshot?(snapshot: PluginSnapshot, viewer: {
@@ -114,6 +111,8 @@ interface SyncHubOptions {
     maxJsonDepth?: number;
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
+    /** Registry used to translate extension elements for legacy peers. */
+    elementRegistry?: ElementRegistry;
 }
 declare class SyncHub {
     private readonly backend;
@@ -127,6 +126,8 @@ declare class SyncHub {
     private readonly authorize?;
     private readonly authorizeLayer?;
     private readonly pluginRegistry;
+    private readonly elementRegistry;
+    private readonly peerCapabilities;
     private readonly canRead?;
     private readonly memoryLayers;
     private readonly maxJsonDepth;
@@ -173,6 +174,24 @@ declare class SyncHub {
     private mayRead;
     private safePublish;
     private relayToRoom;
+    /**
+     * 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.
+     */
+    private sendToConnection;
+    /** Returns the wire frame for `op` translated for `capabilities`, or null when lossy. */
+    private encodeForPeer;
+    /**
+     * 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.
+     */
+    private normalizeElement;
+    private normalizeElements;
+    private relayOpToRoom;
     private broadcastClientPresence;
     private clearPresenceLanes;
     private schedulePresence;
@@ -190,9 +209,9 @@ declare class MemoryHubBackend implements HubBackend {
     private roomLayers;
     private room;
     private layers;
-    snapshot(room: string): Promise<CanvasElement[]>;
-    get(room: string, id: string): Promise<CanvasElement | undefined>;
-    apply(room: string, op: SyncOp): Promise<void>;
+    snapshot(room: string): Promise<WireSyncElement[]>;
+    get(room: string, id: string): Promise<WireSyncElement | undefined>;
+    apply(room: string, op: WireSyncOp): Promise<void>;
     layerRecords(room: string): Promise<LayerRecord[]>;
     getLayerRecord(room: string, id: string): Promise<LayerRecord | undefined>;
     applyLayerRecord(room: string, record: LayerRecord): Promise<void>;
@@ -229,6 +248,12 @@ interface CreateSyncServerOptions {
     presenceThrottleMs?: number;
     maxPresenceLanes?: number;
     shutdownGraceMs?: number;
+    /**
+     * Registry used to translate extension envelopes for legacy peers. Without
+     * it the hub relays unknown legacy element types verbatim and cannot encode
+     * envelopes for pre-envelope clients.
+     */
+    elementRegistry?: ElementRegistry;
 }
 declare function createSyncServer(options?: CreateSyncServerOptions): {
     hub: SyncHub;

package/dist/index.js

@@ -1,12 +1,19 @@
 // src/sync-hub.ts
 import {
+  createCurrentCapabilities,
+  createLegacyCapabilities,
   parseEnvelope,
   isValidElement,
-  isNewerLayerRecord
+  isValidWireElement,
+  isNewerLayerRecord,
+  translateOpForPeer
 } from "@fieldnotes/sync";
+import { getDefaultElementRegistry } from "@fieldnotes/core";
 
 // src/memory-hub-backend.ts
-import { applyOpToMap } from "@fieldnotes/sync";
+import {
+  applyOpToMap
+} from "@fieldnotes/sync";
 var MemoryHubBackend = class {
   rooms = /* @__PURE__ */ new Map();
   roomLayers = /* @__PURE__ */ new Map();
@@ -72,8 +79,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))
@@ -105,6 +114,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
@@ -167,7 +182,7 @@ function generateInstanceId() {
 function isFanoutOp(op) {
   if (typeof op !== "object" || op === null) return false;
   const o = op;
-  if (o.kind === "upsert") return isValidElement(o.element);
+  if (o.kind === "upsert") return isValidWireElement(o.element);
   if (o.kind === "remove") return typeof o.id === "string";
   return o.kind === "clear";
 }
@@ -197,6 +212,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;
@@ -216,6 +234,8 @@ var SyncHub = class {
   authorize;
   authorizeLayer;
   pluginRegistry;
+  elementRegistry;
+  peerCapabilities = /* @__PURE__ */ new Map();
   canRead;
   memoryLayers = /* @__PURE__ */ new Map();
   maxJsonDepth;
@@ -234,6 +254,7 @@ var SyncHub = class {
   constructor(options = {}) {
     this.backend = options.backend ?? new MemoryHubBackend();
     this.pluginRegistry = new ServerPluginRegistry(options.plugins ?? []);
+    this.elementRegistry = options.elementRegistry ?? getDefaultElementRegistry();
     this.instanceId = options.instanceId ?? generateInstanceId();
     this.fanout = options.fanout ?? new InMemoryHubFanout();
     this.authorize = options.authorize;
@@ -261,6 +282,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);
@@ -294,6 +316,14 @@ var SyncHub = class {
     if (!hasJsonDepthAtMost(message, this.maxJsonDepth)) return Promise.resolve();
     const env = 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: createCurrentCapabilities(this.pluginRegistry.extensionKinds)
+      });
+      return Promise.resolve();
+    }
     if (env.op.kind === "presence") {
       this.schedulePresence(conn, env.op.data);
       return Promise.resolve();
@@ -309,9 +339,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 = {
@@ -332,7 +367,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") {
@@ -350,7 +385,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({
@@ -374,7 +410,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")) {
@@ -430,7 +466,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 ?? []) {
@@ -443,7 +479,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
@@ -465,19 +501,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 && !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;
@@ -538,6 +574,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) ?? 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 = 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 (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 } });
@@ -619,41 +735,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);
       }
     }
   }
@@ -664,11 +772,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;
@@ -688,7 +796,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;
@@ -703,11 +811,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(
@@ -718,9 +822,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);
@@ -822,7 +931,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 WebSocketServer({ server: options.server, maxPayload: maxMessageBytes }) : new WebSocketServer({ port: options.port ?? 0, maxPayload: maxMessageBytes });