@tdxvolt/volt-drive-mcp 0.0.0-stage → 0.1.1

package/src/sync-doc.js

@@ -0,0 +1,268 @@
+import { timeout as timeoutError } from "./errors.js";
+
+/**
+ * Helpers around the Volt `SyncProvider`, which mirrors a server side synapse
+ * document into a local `Y.Doc`.
+ *
+ * Providers are EventEmitters: an `error` event with no listener throws, so
+ * every provider created here gets a permanent listener.
+ */
+
+function toError(err) {
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+/**
+ * Create a provider with a permanent error listener.
+ * @returns {import("node:events").EventEmitter & object}
+ */
+export function createProvider(ctx, driveId, doc, options = {}) {
+  const provider = new ctx.SyncProvider(ctx.Y, ctx.client, driveId, doc, {
+    readOnlyFallback: true,
+    ...options
+  });
+  provider.on("error", (err) => {
+    ctx.logger?.debug?.(
+      `sync error on ${doc.guid || "?"}: ${toError(err).message}`
+    );
+  });
+  return provider;
+}
+
+/**
+ * Start `provider` and resolve once the initial sync with the Volt is done.
+ * Rejects on a sync error or after `timeoutMs`.
+ */
+export function startAndWaitForSync(provider, timeoutMs, what = "document") {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+
+    const cleanup = () => {
+      settled = true;
+      clearTimeout(timer);
+      provider.off("sync", onSync);
+      provider.off("error", onError);
+    };
+
+    const onSync = (synced) => {
+      if (synced && !settled) {
+        cleanup();
+        resolve();
+      }
+    };
+
+    const onError = (err) => {
+      if (!settled) {
+        cleanup();
+        try {
+          provider.stopSync();
+        } catch {
+          // already stopped
+        }
+        reject(toError(err));
+      }
+    };
+
+    timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      cleanup();
+      try {
+        provider.stopSync();
+      } catch {
+        // already stopped
+      }
+      reject(timeoutError(`timed out waiting for ${what} to sync`));
+    }, timeoutMs);
+
+    provider.on("sync", onSync);
+    provider.on("error", onError);
+
+    try {
+      provider.startSync();
+    } catch (err) {
+      onError(err);
+    }
+  });
+}
+
+/**
+ * Stop `provider` and wait (best effort) until its stream has closed, which
+ * is when the Volt has finished receiving everything we sent.
+ */
+export function stopAndWait(provider, timeoutMs = 10_000) {
+  return new Promise((resolve) => {
+    let timer = null;
+    const done = () => {
+      clearTimeout(timer);
+      provider.off("sync", onSync);
+      resolve();
+    };
+    const onSync = (synced) => {
+      if (!synced) {
+        done();
+      }
+    };
+    timer = setTimeout(done, timeoutMs);
+    provider.on("sync", onSync);
+    try {
+      provider.stopSync();
+    } catch {
+      done();
+    }
+  });
+}
+
+/**
+ * Open the document `documentId` of drive `driveId`, run `fn(doc)` once it has
+ * synced, and always close the provider afterwards. Resolves with `fn`'s
+ * result.
+ *
+ * @param {object} ctx - { Y, SyncProvider, client, logger }
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs]
+ * @param {boolean} [options.flush] - wait for outbound updates to drain and for
+ *   the stream to close before resolving (needed after writing).
+ */
+export async function withSyncedDocument(
+  ctx,
+  driveId,
+  documentId,
+  fn,
+  { timeoutMs = 30_000, flush = false } = {}
+) {
+  const doc = new ctx.Y.Doc();
+  doc.guid = documentId;
+  const provider = createProvider(ctx, driveId, doc);
+
+  await startAndWaitForSync(provider, timeoutMs, `document ${documentId}`);
+
+  try {
+    const result = await fn(doc, provider);
+    if (flush) {
+      await provider.whenOutboundDrained();
+    }
+    return result;
+  } finally {
+    await (flush ? stopAndWait(provider) : stopFireAndForget(provider));
+  }
+}
+
+function stopFireAndForget(provider) {
+  try {
+    provider.stopSync();
+  } catch {
+    // already stopped
+  }
+}
+
+/** Read the `content` Y.Text of a text document. */
+export function readTextContent(ctx, driveId, documentId, options) {
+  return withSyncedDocument(
+    ctx,
+    driveId,
+    documentId,
+    (doc) => doc.getText("content").toString(),
+    options
+  );
+}
+
+/** Read the legacy `content` Y.Array-of-bytes encoding of a binary document. */
+export function readLegacyArrayContent(ctx, driveId, documentId, options) {
+  return withSyncedDocument(
+    ctx,
+    driveId,
+    documentId,
+    (doc) => {
+      const values = doc.getArray("content").toArray();
+      const bytes = new Uint8Array(values.length);
+      values.forEach((value, index) => {
+        bytes[index] =
+          typeof value === "number" && value >= 0 && value <= 255 ? value : 0;
+      });
+      return bytes;
+    },
+    options
+  );
+}
+
+const isHighSurrogate = (code) => code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code) => code >= 0xdc00 && code <= 0xdfff;
+
+/**
+ * Turn `ytext`'s current content into `newText` with a single minimal splice
+ * (common prefix and suffix are left untouched). Editing in place, rather than
+ * deleting and re-inserting everything, lets concurrent edits from the native
+ * VoltDrive daemon or other clients merge instead of being clobbered.
+ *
+ * @returns {boolean} true when the text changed.
+ */
+export function applyTextDiff(ytext, newText) {
+  const oldText = ytext.toString();
+  if (oldText === newText) {
+    return false;
+  }
+
+  const limit = Math.min(oldText.length, newText.length);
+  let prefix = 0;
+  while (prefix < limit && oldText.charCodeAt(prefix) === newText.charCodeAt(prefix)) {
+    prefix++;
+  }
+  // Never split a surrogate pair across the edit boundary.
+  while (prefix > 0 && isHighSurrogate(oldText.charCodeAt(prefix - 1))) {
+    prefix--;
+  }
+
+  let suffix = 0;
+  while (
+    suffix < limit - prefix &&
+    oldText.charCodeAt(oldText.length - 1 - suffix) ===
+      newText.charCodeAt(newText.length - 1 - suffix)
+  ) {
+    suffix++;
+  }
+  while (suffix > 0 && isLowSurrogate(oldText.charCodeAt(oldText.length - suffix))) {
+    suffix--;
+  }
+
+  const removeCount = oldText.length - prefix - suffix;
+  const insertText = newText.slice(prefix, newText.length - suffix);
+
+  const apply = () => {
+    if (removeCount > 0) {
+      ytext.delete(prefix, removeCount);
+    }
+    if (insertText.length > 0) {
+      ytext.insert(prefix, insertText);
+    }
+  };
+
+  if (ytext.doc) {
+    ytext.doc.transact(apply);
+  } else {
+    apply();
+  }
+  return true;
+}
+
+/**
+ * Write `text` into the `content` Y.Text of an existing or new text document.
+ * Resolves once the Volt has received the update.
+ * @returns {Promise<boolean>} true when the stored content changed.
+ */
+export function writeTextContent(ctx, driveId, documentId, text, options) {
+  return withSyncedDocument(
+    ctx,
+    driveId,
+    documentId,
+    (doc, provider) => {
+      if (provider.isReadOnly) {
+        throw new Error("this document is read-only for the current identity");
+      }
+      return applyTextDiff(doc.getText("content"), text);
+    },
+    { ...options, flush: true }
+  );
+}