@larc-iu/plaid-client 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/sse.js

@@ -1,5 +1,22 @@
 import { transformResponse } from './transforms.js';
 
+// A live SSE stream is never silent for long: the server sends a keepalive
+// comment on service channels (every 25s) and a heartbeat event on the /listen
+// bus (every 30s). So if NOTHING arrives for longer than this, the connection is
+// dead: the server was killed without closing the socket, the network dropped
+// it, or a reconnect caught the server mid-restart (port accepting, app not yet
+// streaming). We must surface that as a drop so the registration supervisor in
+// serve() can reopen it. Without the watchdog such a silent drop
+// leaves `reader.read()` pending forever: readyState never reaches CLOSED, so
+// nothing reconnects and the service never heals. Comfortably above both server
+// cadences, so a healthy idle stream never trips it.
+export const SSE_IDLE_TIMEOUT_MS = 60000;
+
+// The last failure warned about per stream URL, so a stream retried every few
+// seconds through an outage warns once per distinct failure rather than once
+// per attempt. Cleared when the stream opens. Mirrors the Python client.
+const lastWarning = new Map();
+
 /**
  * Project a parsed SSE `data:` object onto what a listener callback sees.
  *
@@ -30,7 +47,10 @@ export function eventPayload(eventType, parsed) {
  *   /listen bus; service request channels pass their own. Only /listen emits
  *   `heartbeat` events needing a POST confirmation — other streams keep
  *   themselves alive with ignored SSE comments.
- * @returns {Object} SSE connection with .close(), .getStats(), .readyState
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
  */
 export function createSSEConnection(client, projectId, onEvent, path) {
   const streamPath = path || `/api/v1/projects/${projectId}/listen`;
@@ -59,13 +79,30 @@ export function createSSEConnection(client, projectId, onEvent, path) {
     }
   };
 
+  // Watchdog: abort the fetch if the stream goes silent for longer than the
+  // server's keepalive cadence, so a silently-dropped connection lands in the
+  // catch below (readyState CLOSED) instead of blocking on a read that will
+  // never resolve.
+  let idleTimer = null;
+  const clearIdleTimer = () => {
+    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+  const armIdleTimer = () => {
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      if (!isClosed) abortController.abort(new Error('SSE stream went silent'));
+    }, SSE_IDLE_TIMEOUT_MS);
+  };
+
   const sseConnection = {
     readyState: 0, // CONNECTING
+    error: null,
     close: () => {
       if (!isClosed) {
         isClosed = true;
         isConnected = false;
         sseConnection.readyState = 2; // CLOSED
+        clearIdleTimer();
         abortController.abort();
       }
     },
@@ -83,6 +120,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
   (async () => {
     try {
       const url = `${client.baseUrl}${streamPath}`;
+      armIdleTimer();
       const response = await fetch(url, {
         method: 'GET',
         headers: {
@@ -101,11 +139,14 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           // takes over.
           console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
         }
-        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        const refused = new Error(`HTTP ${response.status} ${response.statusText}`);
+        refused.status = response.status;
+        throw refused;
       }
 
       isConnected = true;
       sseConnection.readyState = 1; // OPEN
+      lastWarning.delete(url);
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -120,6 +161,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       while (true) {
         const { done, value } = await reader.read();
         if (done || isClosed) break;
+        armIdleTimer();
 
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split('\n');
@@ -158,11 +200,26 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           }
         }
       }
+      if (!isClosed) {
+        // The server ended the stream, for instance because the opener lost
+        // the right to it. Say so, so a caller can tell it from a close of
+        // its own.
+        sseConnection.error = Object.assign(new Error('The server closed the stream'), {
+          name: 'StreamClosed',
+        });
+      }
     } catch (error) {
+      if (!isClosed) sseConnection.error = error;
       if (error.name !== 'AbortError') {
-        console.warn('SSE connection error:', error);
+        const url = `${client.baseUrl}${streamPath}`;
+        const message = String(error?.message || error);
+        if (lastWarning.get(url) !== message) {
+          lastWarning.set(url, message);
+          console.warn('SSE connection error:', error);
+        }
       }
     } finally {
+      clearIdleTimer();
       isConnected = false;
       isClosed = true;
       sseConnection.readyState = 2; // CLOSED

package/src/textEdits.js

@@ -0,0 +1,191 @@
+/**
+ * Text edit operations: composing a stream of ops into the net change.
+ *
+ * An op is one of the shapes `PATCH /texts/:id` takes:
+ *
+ *   { type: 'insert',  index, value: string }
+ *   { type: 'delete',  index, value: count }
+ *   { type: 'replace', index, length, value: string }
+ *
+ * Every index and count is in Unicode CODE POINTS (see ./codepoint.js), and
+ * the ops are in running coordinates: each op's `index` is in the body as the
+ * ops before it left it.
+ *
+ * A GAP is `{ start, end, value }` in the OLD body's coordinates: old
+ * [start, end) gives way to `value`. `composeTextEdits` turns any op stream
+ * into gaps that depend only on the net change, never on how the keystrokes
+ * came, which is also how the server reads an edit. The Python client's
+ * `plaid_client.text_edits` is the twin of this module.
+ */
+
+const codePoints = (s) => [...s];
+
+function opName(op) {
+  return JSON.stringify(op);
+}
+
+/**
+ * The op's type after checking its shape and bounds against a body of `len`
+ * code points, as the server checks it. Throws an Error otherwise.
+ */
+function checkOp(op, len) {
+  const type = op && op.type;
+  const { index, value, length } = op || {};
+  const int = Number.isInteger;
+  const wellFormed =
+    (type === 'insert' && int(index) && typeof value === 'string') ||
+    (type === 'delete' && int(index) && int(value)) ||
+    (type === 'replace' && int(index) && int(length) && typeof value === 'string');
+  if (!wellFormed) {
+    throw new Error(
+      `Malformed text edit operation: ${opName(op)}. Expected {type: "insert", index: int, ` +
+        `value: string}, {type: "delete", index: int, value: int} or {type: "replace", ` +
+        `index: int, length: int, value: string}`,
+    );
+  }
+  const inBounds =
+    type === 'insert'
+      ? index >= 0 && index <= len
+      : type === 'delete'
+        ? index >= 0 && value >= 0 && index + value <= len
+        : index >= 0 && length >= 0 && index + length <= len;
+  if (!inBounds) {
+    throw new Error(
+      `Text edit operation out of bounds: ${opName(op)} (text length is ${len} code points)`,
+    );
+  }
+  return type;
+}
+
+// How many code points an op removes and what it types.
+function opParts(type, op) {
+  if (type === 'insert') return [0, op.value];
+  if (type === 'delete') return [op.value, ''];
+  return [op.length, op.value];
+}
+
+const segLength = (seg) => (seg.old ? seg.end - seg.start : seg.chars.length);
+
+// The segment list of the new text, cut so that a segment boundary falls at
+// code point `at`. Returns the index of the first segment at or after `at`.
+function cutAt(segs, at) {
+  let pos = 0;
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    const n = segLength(seg);
+    if (at === pos) return i;
+    if (at < pos + n) {
+      const k = at - pos;
+      const left = seg.old
+        ? { old: true, start: seg.start, end: seg.start + k }
+        : { old: false, chars: seg.chars.slice(0, k) };
+      const right = seg.old
+        ? { old: true, start: seg.start + k, end: seg.end }
+        : { old: false, chars: seg.chars.slice(k) };
+      segs.splice(i, 1, left, right);
+      return i + 1;
+    }
+    pos += n;
+  }
+  return segs.length;
+}
+
+/**
+ * The net change of `ops` applied in turn to `body`, as gaps in the old
+ * body's code points: sorted, and never touching (at least one old code point
+ * is kept between two gaps). Old text deleted and typed back is typed text,
+ * and a gap whose value is the old text it removes is dropped. Throws on a
+ * malformed or out-of-bounds op.
+ */
+export function composeTextEdits(body, ops) {
+  const old = codePoints(body);
+  let segs = old.length ? [{ old: true, start: 0, end: old.length }] : [];
+  let len = old.length;
+  for (const op of ops) {
+    const type = checkOp(op, len);
+    const [del, typed] = opParts(type, op);
+    const chars = codePoints(typed);
+    const from = cutAt(segs, op.index);
+    const to = cutAt(segs, op.index + del);
+    const inserted = chars.length ? [{ old: false, chars }] : [];
+    segs.splice(from, to - from, ...inserted);
+    len += chars.length - del;
+    segs = mergeTyped(segs);
+  }
+
+  const gaps = [];
+  let kept = 0; // the old position the last kept run ended at
+  let typed = [];
+  const close = (next) => {
+    if (next > kept || typed.length) {
+      const value = typed.join('');
+      if (value !== old.slice(kept, next).join('')) gaps.push({ start: kept, end: next, value });
+    }
+    typed = [];
+  };
+  for (const seg of segs) {
+    if (seg.old) {
+      close(seg.start);
+      kept = seg.end;
+    } else {
+      typed.push(...seg.chars);
+    }
+  }
+  close(old.length);
+  return gaps;
+}
+
+// Neighbouring typed segments as one, and neighbouring old ranges as one.
+function mergeTyped(segs) {
+  const out = [];
+  for (const seg of segs) {
+    const last = out[out.length - 1];
+    if (last && !last.old && !seg.old) {
+      out[out.length - 1] = { old: false, chars: last.chars.concat(seg.chars) };
+    } else if (last && last.old && seg.old && last.end === seg.start) {
+      out[out.length - 1] = { old: true, start: last.start, end: seg.end };
+    } else if (segLength(seg) > 0) {
+      out.push(seg);
+    }
+  }
+  return out;
+}
+
+/**
+ * Gaps (old-body coordinates, sorted, not overlapping) as running ops: an
+ * insert where a gap removes nothing, a delete where it types nothing, and a
+ * replace otherwise.
+ */
+export function gapsToOps(gaps) {
+  const ops = [];
+  let shift = 0;
+  for (const { start, end, value } of gaps) {
+    const index = start + shift;
+    const typed = codePoints(value).length;
+    if (start === end) {
+      if (typed) ops.push({ type: 'insert', index, value });
+    } else if (!typed) {
+      ops.push({ type: 'delete', index, value: end - start });
+    } else {
+      ops.push({ type: 'replace', index, length: end - start, value });
+    }
+    shift += typed - (end - start);
+  }
+  return ops;
+}
+
+/**
+ * `body` with `ops` applied in turn (running coordinates, code points).
+ * Throws on a malformed or out-of-bounds op.
+ */
+export function applyTextOps(body, ops) {
+  let chars = codePoints(body);
+  for (const op of ops) {
+    const type = checkOp(op, chars.length);
+    const [del, typed] = opParts(type, op);
+    chars = chars
+      .slice(0, op.index)
+      .concat(codePoints(typed), chars.slice(op.index + del));
+  }
+  return chars.join('');
+}

package/src/transforms.js

@@ -1,3 +1,5 @@
+import { BatchRef } from "./batchRef.js";
+
 /**
  * Convert kebab-case/namespaced key to camelCase.
  * 'layer-id' -> 'layerId'
@@ -27,19 +29,27 @@ export function transformKeyFromCamel(key) {
 // usual case conversion.
 const OPAQUE_KEYS = new Set(['metadata', 'config', 'bindings']);
 
+// A request's `metadata` may also be a list of metadata ops (a bulk update
+// entry), whose values are user data too, so it passes through verbatim.
+const isOpaque = (key, value) =>
+  typeof value === 'object' && value !== null &&
+  (Array.isArray(value) ? key === 'metadata' : OPAQUE_KEYS.has(key));
+
 /**
  * Recursively transform request object keys from camelCase to kebab-case.
  * Preserves `metadata` and `config` contents without transformation.
  */
 export function transformRequest(obj) {
   if (obj === null || obj === undefined) return obj;
+  // A batch ref is taken out whole when its write is queued.
+  if (obj instanceof BatchRef) return obj;
   if (Array.isArray(obj)) return obj.map(item => transformRequest(item));
   if (typeof obj !== 'object') return obj;
 
   const transformed = {};
   for (const [key, value] of Object.entries(obj)) {
     const newKey = transformKeyFromCamel(key);
-    if (OPAQUE_KEYS.has(key) && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (isOpaque(key, value)) {
       transformed[newKey] = value;
     } else {
       transformed[newKey] = transformRequest(value);