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

package/src/batchRef.js

@@ -0,0 +1,128 @@
+/**
+ * Batch refs: a write in a batch that uses the id an earlier write in the
+ * same batch creates.
+ *
+ * `b.ref()` returns a BatchRef, which the caller puts in a later write's
+ * body where the id goes. When that write is queued, each BatchRef is taken
+ * out of the body (null is left in its place) and recorded beside it as
+ * `refs: [{ at: [key or index, ...], op: n, index?: k }]`, which the server
+ * fills in. The server never searches a body, so user data of any shape,
+ * `{ $ref: 0 }` included, is stored as sent. A BatchRef is a class instance
+ * no JSON value can be, so data can never be taken for one here either.
+ */
+
+const MISPLACED =
+  "b.ref() stands for an id only in the body of a later write on the same batch";
+
+export class BatchRef {
+  #batch;
+
+  constructor(batch, op, index) {
+    this.#batch = batch;
+    /** The op, counted from 0 in the batch, whose id this stands for. */
+    this.$ref = op;
+    /** For a bulk create, which of its ids. */
+    if (index !== undefined) this.index = index;
+    Object.freeze(this);
+  }
+
+  belongsTo(batch) {
+    return this.#batch === batch;
+  }
+
+  // Sent anywhere but a queued body (a call made on the client, a path, a
+  // query), a ref would go out as something the server takes for data.
+  toJSON() {
+    throw new Error(MISPLACED);
+  }
+
+  [Symbol.toPrimitive]() {
+    throw new Error(MISPLACED);
+  }
+}
+
+/**
+ * A BatchRef for op `opIndex` of `batch` (negative counts from the end, -1
+ * is the op queued last), fixed when it is called.
+ */
+export function makeBatchRef(batch, opIndex, index) {
+  const n = opIndex < 0 ? batch.operations.length + opIndex : opIndex;
+  if (!Number.isInteger(n) || n < 0 || n >= batch.operations.length) {
+    throw new Error(`No operation ${opIndex} has been queued on this batch`);
+  }
+  if (index !== undefined && !(Number.isInteger(index) && index >= 0)) {
+    throw new Error(`A ref's index must be a whole number, not ${index}`);
+  }
+  return new BatchRef(batch, n, index);
+}
+
+const isPlainObject = (v) => {
+  if (v === null || typeof v !== "object") return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+
+function holdsRef(v) {
+  if (v instanceof BatchRef) return true;
+  if (Array.isArray(v)) return v.some(holdsRef);
+  if (isPlainObject(v)) {
+    for (const k in v) if (holdsRef(v[k])) return true;
+  }
+  return false;
+}
+
+/**
+ * `body` with each BatchRef in it replaced by null, and the `refs` that say
+ * where they were, or `refs` null when it holds none (the body is then
+ * returned as it was).
+ */
+export function takeRefs(batch, body) {
+  if (!holdsRef(body)) return { body, refs: null };
+  const refs = [];
+  const at = [];
+  const take = (v) => {
+    if (v instanceof BatchRef) {
+      if (!v.belongsTo(batch)) throw new Error(MISPLACED);
+      refs.push(
+        v.index === undefined
+          ? { at: [...at], op: v.$ref }
+          : { at: [...at], op: v.$ref, index: v.index },
+      );
+      return null;
+    }
+    if (!holdsRef(v)) return v;
+    if (Array.isArray(v)) {
+      return v.map((x, i) => {
+        at.push(i);
+        const out = take(x);
+        at.pop();
+        return out;
+      });
+    }
+    const out = {};
+    for (const k of Object.keys(v)) {
+      at.push(k);
+      out[k] = take(v[k]);
+      at.pop();
+    }
+    return out;
+  };
+  return { body: take(body), refs };
+}
+
+/**
+ * `refs` counted from `start`, for an op in a batch sent in several requests
+ * (the server counts within one request). A ref to an op of an earlier
+ * request cannot resolve, so it throws before anything goes.
+ */
+export function rebaseRefs(refs, start) {
+  return refs.map((r) => {
+    if (r.op < start) {
+      throw new Error(
+        `Operation ${start} and later are sent in a request of their own, ` +
+          `so an operation among them cannot use the id operation ${r.op} creates`,
+      );
+    }
+    return { ...r, op: r.op - start };
+  });
+}

package/src/constraints.js

@@ -0,0 +1,84 @@
+/**
+ * Layer constraints: rules an app declares on the token, span and relation
+ * layers it owns, which the server enforces inside every write. A write that
+ * breaks one on a row it writes is refused with 422 and the violations. See
+ * the core manual, "Layer constraints".
+ */
+
+import { transformResponse } from "./transforms.js";
+
+/** The constraint types, by the layer kind that may carry them. */
+export const CONSTRAINT_TYPES = Object.freeze([
+  "max-in-degree",
+  "acyclic",
+  "same-ancestor",
+  "single-span",
+  "value-set",
+  "coextensive",
+  "single-link",
+]);
+
+/**
+ * The violations of a write refused by a layer constraint, camelCased
+ * ({constraint, namespace, layer, layerName, document, at, ids, value?,
+ * parts?}), or null for any other error. The answer lists at most 100, and
+ * `err.responseData["violation-count"]` is the total.
+ * @param {any} err
+ * @returns {Array<object>|null}
+ */
+export function violationsOf(err) {
+  const vs = err?.status === 422 ? err?.responseData?.violations : undefined;
+  return Array.isArray(vs) ? transformResponse(vs) : null;
+}
+
+/** The request body of a constraint write: the list, and `expected` when given. */
+export function constraintsBody(constraints, options) {
+  const body = constraints === undefined ? {} : { constraints };
+  if (options && Object.hasOwn(options, "expected")) {
+    body.expected = options.expected === undefined ? null : options.expected;
+  }
+  return body;
+}
+
+// What String.prototype.trim trims. The server trims a value-set's parts the
+// same way, so a value read as listed here is read so there.
+const splitParts = (value, delimiters) => {
+  const set = new Set([...(delimiters || "")]);
+  if (!set.size) return [value];
+  const out = [];
+  let part = "";
+  for (const ch of value) {
+    if (set.has(ch)) {
+      out.push(part);
+      part = "";
+    } else {
+      part += ch;
+    }
+  }
+  out.push(part);
+  return out;
+};
+
+/**
+ * Whether a value-set constraint ({values, delimiters?, parts?}) allows
+ * `value` as the server reads it: null and blank values pass, a non-string
+ * does not, and every part split on a delimiter (or only the first, with
+ * `parts: "first"`), trimmed, must be listed.
+ * @param {{values: string[], delimiters?: string, parts?: "all"|"first"}} constraint
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function valueSetAllows(constraint, value) {
+  if (value == null) return true;
+  if (typeof value !== "string") return false;
+  if (value.trim() === "") return true;
+  const delimiters = constraint?.delimiters || "";
+  const values = constraint?.values || [];
+  const parts = splitParts(value, delimiters);
+  if (constraint?.parts === "first") {
+    const firsts = new Set(values.map((v) => splitParts(v, delimiters)[0].trim()));
+    return firsts.has(parts[0].trim());
+  }
+  const allowed = new Set(values);
+  return parts.every((p) => p.trim() !== "" && allowed.has(p.trim()));
+}

package/src/documentLock.js

@@ -73,11 +73,7 @@ export class DocumentLockLost extends Error {
  * @param {number} [fallback]
  * @returns {number}
  */
-export function lockTtlMs(
-  expiresAt,
-  nowMs,
-  fallback = DOCUMENT_LOCK_TTL_MS,
-) {
+export function lockTtlMs(expiresAt, nowMs, fallback = DOCUMENT_LOCK_TTL_MS) {
   if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
     const ttl = expiresAt - nowMs;
     if (ttl > 0 && ttl <= MAX_BELIEVABLE_TTL_MS) return ttl;
@@ -222,6 +218,67 @@ export class DocumentLock {
   }
 }
 
+/**
+ * Tries a `locked()` block makes at an acquire whose outcome is unknown, and the
+ * pause before the next, which grows by this much each time.
+ */
+export const LOCK_ACQUIRE_ATTEMPTS = 3;
+export const LOCK_ACQUIRE_RETRY_MS = 500;
+
+// The HTTP status of a request that may or may not have reached the server: no
+// answer at all (0), or a proxy's 502 or 504.
+const UNKNOWN_OUTCOME_STATUSES = new Set([0, 502, 504]);
+
+function mintLockId() {
+  return globalThis.crypto.randomUUID();
+}
+
+/**
+ * The acquire of a `locked()` block, under the holder id it minted.
+ *
+ * An acquire whose outcome is unknown (no answer, a timeout, a 502 or a 504)
+ * may have taken the lock. It is sent again under the same id, which the server
+ * answers 200 while that holder has it. When every attempt is unknown, the lock
+ * it may hold is released on the way out, so it does not stand in everyone's
+ * way until it expires.
+ */
+async function takeLock(client, documentId, lockId, retryMs) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await client.documents.acquireLock(documentId, undefined, lockId);
+    } catch (error) {
+      if (error?.status === 423) {
+        // The error body is raw JSON off the wire, so it is still kebab-cased.
+        const body = error.responseData || {};
+        const holder = body.userId || body["user-id"] || "another user";
+        const readable = new Error(
+          `This document is being edited by ${holder}. Try again once they're done.`,
+        );
+        readable.status = 423;
+        readable.statusText = error.statusText;
+        readable.url = error.url;
+        readable.method = error.method;
+        readable.responseData = error.responseData;
+        readable.cause = error;
+        throw readable;
+      }
+      if (!UNKNOWN_OUTCOME_STATUSES.has(error?.status)) throw error;
+      if (attempt + 1 < LOCK_ACQUIRE_ATTEMPTS) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, retryMs * (attempt + 1)),
+        );
+        continue;
+      }
+      try {
+        await client.documents.releaseLock(documentId, lockId);
+      } catch {
+        /* the lock expires on its own */
+      }
+      throw error;
+    }
+  }
+}
+
 /**
  * Hold `documentId`'s server-enforced lock for the length of `fn`.
  * `client.documents.locked` is the entry point; see its doc comment.
@@ -229,37 +286,18 @@ export class DocumentLock {
  * @param {object} client
  * @param {string} documentId
  * @param {(lock: DocumentLock) => any} fn
- * @param {{ keepAlive?: boolean }} [options]
+ * @param {{ keepAlive?: boolean, acquireRetryMs?: number }} [options]
  */
 export async function withDocumentLock(
   client,
   documentId,
   fn,
-  { keepAlive = true } = {},
+  { keepAlive = true, acquireRetryMs = LOCK_ACQUIRE_RETRY_MS } = {},
 ) {
-  let info;
-  try {
-    info = await client.documents.acquireLock(documentId);
-  } catch (error) {
-    if (error?.status === 423) {
-      // The error body is raw JSON off the wire, so it is still kebab-cased.
-      const body = error.responseData || {};
-      const holder = body.userId || body["user-id"] || "another user";
-      const readable = new Error(
-        `Document ${documentId} is locked by ${holder} (likely being edited); try again once they're done.`,
-      );
-      readable.status = 423;
-      readable.statusText = error.statusText;
-      readable.url = error.url;
-      readable.method = error.method;
-      readable.responseData = error.responseData;
-      readable.cause = error;
-      throw readable;
-    }
-    throw error;
-  }
+  const minted = mintLockId();
+  const info = await takeLock(client, documentId, minted, acquireRetryMs);
 
-  const lockId = info?.lockId ?? null;
+  const lockId = info?.lockId ?? minted;
   let keeper = null;
   if (keepAlive) {
     const ttlMs = lockTtlMs(info?.expiresAt, Date.now());

package/src/events.js

@@ -11,11 +11,16 @@ import { transformRequest } from "./transforms.js";
 // error for the caller. Nothing it does can block or break the screen that
 // called it.
 //
-// It sends nothing for a project whose switch is off. The switch is read once
-// from the project (`config.plaid.research.telemetry`) and kept for
-// FLAG_TTL_MS; `events.setEnabled` tells it at once, which is what the
-// settings checkbox does. A server refusal (the switch was turned off since)
-// turns it off here too.
+// It sends nothing for a project whose switch is off. The switch is read
+// from the project (`config.plaid.research.telemetry`). An "on" is kept for
+// FLAG_TTL_MS, one flush interval, and an "off" for FLAG_OFF_TTL_MS, so a
+// switch another maintainer turns on reaches an open page within a minute,
+// while a page whose switch is off, which records on every render of a grid,
+// does not read the project every few seconds. An event recorded while an old
+// "off" is being read again waits for the answer rather than being dropped.
+// `events.setEnabled` tells it at once, which is what the settings checkbox
+// does. A server refusal (the switch was turned off since) turns it off here
+// too.
 //
 // ONE recorder per server per page, whatever client records into it: an app
 // makes a client per editor, and a suggestion's "shown" is deduplicated for
@@ -33,7 +38,8 @@ export const EVENT_TYPES = Object.freeze([
 
 export const FLUSH_INTERVAL_MS = 10000;
 export const FLUSH_AT = 50;
-export const FLAG_TTL_MS = 5 * 60 * 1000;
+export const FLAG_TTL_MS = FLUSH_INTERVAL_MS;
+export const FLAG_OFF_TTL_MS = 60000;
 // Events per request. A browser refuses a `keepalive` request whose body,
 // with every other keepalive request still in flight, passes 64 KiB, and a
 // refused request is lost. So the pagehide send goes out in small pieces, and
@@ -185,14 +191,18 @@ export class EventRecorder {
   }
 
   // The switch as known now: 'on', 'off' or 'pending'. An unknown one sets
-  // off a read of the project, and a stale one a fresh read while the old
-  // answer stands. The answer flushes or drops what is buffered.
+  // off a read of the project, and a stale one a fresh read. While it is
+  // read, an old "on" stands and an old "off" is 'pending', so what is
+  // recorded meanwhile waits for the answer. The answer flushes or drops what
+  // is buffered.
   _flag(projectId) {
     const known = this.flags.get(projectId);
-    const fresh = known && this.now() - known.at < FLAG_TTL_MS;
+    const ttl = known?.state === "on" ? FLAG_TTL_MS : FLAG_OFF_TTL_MS;
+    const fresh = known && this.now() - known.at < ttl;
     if (known && (fresh || known.checking)) return known.state;
+    const state = known?.state === "on" ? "on" : "pending";
     this.flags.set(projectId, {
-      state: known ? known.state : "pending",
+      state,
       at: known ? known.at : 0,
       checking: true,
     });
@@ -209,7 +219,7 @@ export class EventRecorder {
         else if (this.buffer.length >= FLUSH_AT) this.flush();
         else if (this.buffer.length) this._schedule();
       });
-    return known ? known.state : "pending";
+    return state;
   }
 
   _send(projectId, events, keepalive) {