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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.20",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

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/created.js

@@ -0,0 +1,29 @@
+/**
+ * The ids a create answered with. A create's response is `{id}` and a bulk
+ * create's is `{ids}`, read straight off the call or off its result in a
+ * batch (`{status, body}`). Every reader of a create response goes through
+ * these, so none guesses at the shape.
+ */
+
+const isId = (v) => typeof v === "string";
+
+/**
+ * The id a single create answered with, or undefined when it gave none.
+ * @param {Object|null|undefined} result - the create's response, or its batch result
+ * @returns {string|undefined}
+ */
+export const createdId = (result) => {
+  if (isId(result?.id)) return result.id;
+  return isId(result?.body?.id) ? result.body.id : undefined;
+};
+
+/**
+ * The ids a bulk create answered with, in input order, or an empty array
+ * when it gave none.
+ * @param {Object|null|undefined} result - the bulk create's response, or its batch result
+ * @returns {string[]}
+ */
+export const createdIds = (result) => {
+  if (Array.isArray(result?.ids)) return result.ids;
+  return Array.isArray(result?.body?.ids) ? result.body.ids : [];
+};

package/src/documentLock.js

@@ -0,0 +1,342 @@
+/**
+ * Keeping a document lock alive for as long as a `locked()` block runs.
+ *
+ * plaid-core expires a document lock about a minute after it was taken, and the
+ * holder's own writes are what renew it (`plaid.sql.operation` calls
+ * `refresh-locks!` on every write it accepts). That is the right rule for an
+ * editor, which writes as the person types. It is the wrong one for a service:
+ * a parser loads a model, reads the document, spends minutes in inference and
+ * only then writes, so for most of its run it holds nothing. The lock lapses in
+ * silence, a person's edit lands between the read the work was planned from and
+ * the write about to go out, and the write clobbers it.
+ *
+ * A `locked()` block therefore renews on a timer of its own. The renewal is an
+ * acquire that names the holder's `lockId`: the server refreshes the lock that
+ * id holds, and refuses one somebody else holds (the same user included).
+ *
+ * The beat is unconditional rather than "only when no write has gone out
+ * recently". The request layer knows the method of a call but not which
+ * document it touched, so a write to some other document would count as a
+ * renewal here and would not be one. Two extra requests a minute is the whole
+ * cost.
+ *
+ * A renewal that fails means the block is no longer holding what it asked for,
+ * so it stops the run: the loss is recorded on the client and every later write
+ * throws `DocumentLockLost`. The guard sits in the request layer because the
+ * callers are services, and a check they have to remember to call is a check
+ * that is missing somewhere.
+ */
+
+/**
+ * How long plaid-core holds a document lock before it expires, in ms.
+ * `plaid.server.locks/default-lock-expiration-ms`. An operator can change it
+ * with `:plaid.server.locks/config :expiration-ms`, and a server publishes what
+ * it enforces as `lockExpirationMs` in `GET /info`. This is the last resort:
+ * what a live lock is renewed against is the `expiresAt` on the acquire
+ * response, which names the moment rather than the window.
+ */
+export const DOCUMENT_LOCK_TTL_MS = 60000;
+
+// Widest lock lifetime we will believe from a server response. Past this the
+// number is a clock skew between this machine and the server rather than a
+// configured window, and the documented default is the better guess.
+const MAX_BELIEVABLE_TTL_MS = 3600000;
+
+/**
+ * The lock a `documents.locked()` block was holding is no longer held.
+ *
+ * Thrown by the keep-alive when it cannot renew the lock, and then by the
+ * request layer on every write this client attempts, so work that has been
+ * running for minutes stops rather than writing over an edit that may have
+ * landed while the lock was gone.
+ */
+export class DocumentLockLost extends Error {
+  constructor(message, documentId, cause) {
+    super(message);
+    this.name = "DocumentLockLost";
+    this.documentId = documentId;
+    this.cause = cause;
+  }
+}
+
+/**
+ * How long a freshly taken lock lasts, from the server's own answer.
+ *
+ * `expiresAt` is the epoch-millisecond stamp the lock endpoints return.
+ * Comparing it against this machine's clock is the only way to learn a window
+ * an operator has retuned, and it is also the one place a clock skew can get
+ * in, so an answer outside a believable band falls back to the documented
+ * default rather than to a beat that never fires or fires constantly.
+ *
+ * @param {number|undefined} expiresAt
+ * @param {number} nowMs
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+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;
+  }
+  return fallback;
+}
+
+/**
+ * Renews one document's lock until the block holding it exits.
+ *
+ * `refresh` is called with the document id and must reject on failure.
+ * `onLost` is called once, with the `DocumentLockLost`, when the lock can no
+ * longer be assumed.
+ *
+ * `clock` and `sleep` exist so the whole policy can be run on a fake clock:
+ * `sleep(delayMs)` resolves to true once the block has exited.
+ */
+export class LockKeeper {
+  constructor(
+    refresh,
+    documentId,
+    ttlMs,
+    { onLost = null, clock = Date.now, sleep = null } = {},
+  ) {
+    this._refresh = refresh;
+    this._documentId = documentId;
+    // A window under two seconds leaves no room for a retry; treat it as a
+    // misconfiguration and beat at the documented rate instead.
+    this._ttlMs = ttlMs >= 2000 ? ttlMs : DOCUMENT_LOCK_TTL_MS;
+    this._onLost = onLost;
+    this._clock = clock;
+    this._sleep = sleep || ((ms) => this._defaultSleep(ms));
+    this._stopped = false;
+    this._wake = null;
+    this._running = null;
+    /** The `DocumentLockLost` this keeper raised, or null. */
+    this.lost = null;
+  }
+
+  /**
+   * Time between renewals: half the window, so a renewal that fails has a
+   * second chance before the lock it is renewing expires.
+   */
+  get intervalMs() {
+    return Math.max(1000, this._ttlMs / 2);
+  }
+
+  /**
+   * Time before retrying a renewal that failed. A blip should not end a run
+   * that the server still considers the holder of.
+   */
+  get retryMs() {
+    return Math.max(500, this._ttlMs / 10);
+  }
+
+  _defaultSleep(ms) {
+    if (this._stopped) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._wake = null;
+        resolve(this._stopped);
+      }, ms);
+      // Never hold a Node process open on the beat alone.
+      if (timer && typeof timer.unref === "function") timer.unref();
+      this._wake = () => {
+        clearTimeout(timer);
+        this._wake = null;
+        resolve(true);
+      };
+    });
+  }
+
+  /** The beat. Resolves when the block exits or the lock is lost. */
+  async run() {
+    let deadline = this._clock() + this._ttlMs;
+    let delay = this.intervalMs;
+    while (!(await this._sleep(delay))) {
+      try {
+        await this._refresh(this._documentId);
+      } catch (error) {
+        // 423 is definitive: somebody else holds the document now, or ours
+        // expired or was dropped, and the server never takes it back.
+        // Anything else may be a blip, and is only fatal once the lock we are
+        // renewing has actually run out.
+        if (error?.status === 423 || this._clock() >= deadline) {
+          this._fail(error);
+          return;
+        }
+        delay = this.retryMs;
+        continue;
+      }
+      deadline = this._clock() + this._ttlMs;
+      delay = this.intervalMs;
+    }
+  }
+
+  start() {
+    this._running = this.run();
+    // Nothing awaits the beat: a failure inside it is reported through onLost,
+    // not through this promise.
+    this._running.catch(() => {});
+    return this._running;
+  }
+
+  stop() {
+    this._stopped = true;
+    if (this._wake) this._wake();
+  }
+
+  _fail(error) {
+    this.lost = new DocumentLockLost(
+      `The lock on document ${this._documentId} lapsed: it could not be renewed.`,
+      this._documentId,
+      error,
+    );
+    if (this._onLost) this._onLost(this.lost);
+  }
+}
+
+/**
+ * What a `client.documents.locked(id, (lock) => ...)` block gets.
+ *
+ * The block does not have to consult it: a lost lock stops the next write on
+ * its own. Read `lock.lost` (or call `lock.raiseIfLost()`) to give up earlier,
+ * between steps of work that has not written anything yet.
+ */
+export class DocumentLock {
+  constructor(documentId, keeper, lockId = null) {
+    this.documentId = documentId;
+    /** The holder id the acquire answered with. */
+    this.lockId = lockId;
+    this._keeper = keeper;
+  }
+
+  /** The `DocumentLockLost` if the lock lapsed, else null. */
+  get lost() {
+    return this._keeper ? this._keeper.lost : null;
+  }
+
+  raiseIfLost() {
+    if (this.lost) throw this.lost;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param {object} client
+ * @param {string} documentId
+ * @param {(lock: DocumentLock) => any} fn
+ * @param {{ keepAlive?: boolean, acquireRetryMs?: number }} [options]
+ */
+export async function withDocumentLock(
+  client,
+  documentId,
+  fn,
+  { keepAlive = true, acquireRetryMs = LOCK_ACQUIRE_RETRY_MS } = {},
+) {
+  const minted = mintLockId();
+  const info = await takeLock(client, documentId, minted, acquireRetryMs);
+
+  const lockId = info?.lockId ?? minted;
+  let keeper = null;
+  if (keepAlive) {
+    const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
+    client.documentLockLost = null;
+    keeper = new LockKeeper(
+      (id) => client.documents.renewLock(id, lockId),
+      documentId,
+      ttlMs,
+      {
+        onLost: (lost) => {
+          client.documentLockLost = lost;
+        },
+      },
+    );
+    keeper.start();
+  }
+
+  let result;
+  let threw = false;
+  try {
+    result = await fn(new DocumentLock(documentId, keeper, lockId));
+  } catch (error) {
+    threw = true;
+    throw error;
+  } finally {
+    if (keeper) keeper.stop();
+    const lost = keeper ? keeper.lost : null;
+    client.documentLockLost = null;
+    // Best-effort release: the server TTL reclaims a stranded lock, and we must
+    // not let a release failure mask the real error from the body.
+    try {
+      await client.documents.releaseLock(documentId, lockId);
+    } catch {
+      /* the lock expires on its own */
+    }
+    // A block that ran to the end without the lock it asked for did not do what
+    // it says it did. Only throw when nothing else is already propagating, so
+    // the real failure is never masked.
+    if (lost && !threw) throw lost;
+  }
+  return result;
+}