@larc-iu/plaid-client 0.2.0-alpha.29 → 0.2.0-alpha.30

package/src/http.js

@@ -1,7 +1,6 @@
 import { markReplayed } from "./replayed.js";
 import { transformRequest, transformResponse } from "./transforms.js";
-import { takeRefs } from "./batchRef.js";
-import { uuidv7 } from "./ids.js";
+import { nextIdempotencyKey } from "./operations.js";
 
 // ---------------------------------------------------------------------------
 // Batches: which calls a batch carries, and which go over the wire anyway.
@@ -268,7 +267,7 @@ export async function retryWhileBusy(
 // keyed write for a day, and the same key sent again for the same request is
 // answered from it with `Idempotent-Replayed: true`, writing nothing. So a
 // write whose answer was lost (no response, 502, 504) can be sent again
-// safely: it lands once. `makeRequest` and `_postBatch` do that three times
+// safely: it lands once. `makeRequest` and `postBatch` do that three times
 // themselves (retryUnknown), and the error that escapes carries the key as
 // `idempotencyKey`.
 //
@@ -338,29 +337,6 @@ export async function retryUnknown(
   }
 }
 
-/**
- * The key for the next keyed request, and the strict-mode stamp it must
- * claim when an earlier run of its operation already sent it. `joins` says
- * whether the request joins the open logical operation.
- * Returns `{ key, pin, record }`: `pin` is undefined when nothing is pinned,
- * and `record(version)` pins what this request claimed, the first time.
- */
-export function nextIdempotencyKey(client, joins) {
-  const frame = joins ? client.operationGroup?.frames.at(-1) : null;
-  const keys = frame?.keys;
-  if (!keys) return { key: uuidv7(), pin: undefined, record: () => {} };
-  const n = frame.count;
-  frame.count += 1;
-  const pinned = keys.stamps.has(n);
-  return {
-    key: `${keys.seed}.${n}`,
-    pin: pinned ? keys.stamps.get(n) : undefined,
-    record: (version) => {
-      if (!pinned) keys.stamps.set(n, version ?? null);
-    },
-  };
-}
-
 /**
  * Build a fetch AbortSignal that fires after `timeout` ms, or undefined when
  * timeouts are disabled / unsupported.
@@ -699,43 +675,49 @@ async function learnOmittedVersionQuietly(client) {
 }
 
 /**
- * A call made on a batch (see `PlaidClient#batch`). A write of project data is
- * queued as one operation of the batch and answers `{ batched: true }`; its
- * result is the matching entry of what `submit()` resolves to. A read, and a
- * signal marked `outOfBand`, is the client's to make and goes over the wire
- * now, exactly as if it had been made on the client.
+ * One send of a request by fetch, under a fresh timeout signal: an
+ * AbortSignal.timeout fires once and stays aborted, so a retry needs its own.
+ * `timeoutMs` 0 or null sends with none.
  */
-export async function queueRequest(batch, method, path, options = {}) {
-  if (method === "GET" || options.outOfBand) {
-    return batch.client._request(method, path, options);
-  }
-  if (!batch.open) {
-    throw new Error(`This batch was already submitted or aborted: ${path}`);
-  }
-  if (options.noBatch) {
-    throw new Error(`This endpoint cannot be used in a batch: ${path}`);
-  }
-  const { url, requestBody, stampedDocument, stampedGroup } = prepareRequest(
-    batch.client,
-    method,
-    path,
-    options,
-  );
-  const operation = {
-    path: url.replace(batch.client.baseUrl, ""),
-    method: method.toUpperCase(),
-  };
-  if (requestBody !== undefined) {
-    // Each b.ref() in the body goes beside it, as the path to a null the
-    // server fills with the id (batchRef.js).
-    const { body, refs } = takeRefs(batch, requestBody);
-    operation.body = body;
-    if (refs) operation.refs = refs;
+export function fetchWithTimeout(url, fetchOptions, timeoutMs) {
+  const signal = timeoutSignal(timeoutMs);
+  return fetch(url, signal ? { ...fetchOptions, signal } : fetchOptions);
+}
+
+/**
+ * Run `attempt` with the client's retries: a 503 is retried (unless
+ * `noBusyRetry`), and a keyed request whose answer was lost is sent again
+ * under its key (retryUnknown). Each retry is told to `onRetry` listeners.
+ */
+export function withRetries(client, attempt, { keyed = false, noBusyRetry = false } = {}) {
+  const onRetry = (info) => client._noteRetry?.(info);
+  const busy = noBusyRetry ? { onRetry, retries: 0 } : { onRetry };
+  return keyed
+    ? retryUnknown(() => retryWhileBusy(attempt, busy), {
+        delaysMs: client.retryDelaysMs,
+        onRetry,
+      })
+    : retryWhileBusy(attempt, busy);
+}
+
+/**
+ * A 401 means the token is missing, expired or invalid. Fire the app's
+ * auth-error handler once per client (it discards the token and routes back
+ * to login). A 403 (authenticated but not permitted) deliberately does not.
+ */
+export function noteAuthError(client, error) {
+  if (
+    error?.status === 401 &&
+    typeof client.onAuthError === "function" &&
+    !client._authErrorFired
+  ) {
+    client._authErrorFired = true;
+    try {
+      client.onAuthError(error);
+    } catch (_) {
+      /* handler must not mask the original error */
+    }
   }
-  batch.operations.push(operation);
-  batch.stampedDocuments.push(stampedDocument);
-  batch.stampedGroups.push(stampedGroup);
-  return { batched: true };
 }
 
 /**
@@ -762,6 +744,10 @@ export async function queueRequest(batch, method, path, options = {}) {
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ *   blobResponse    - Return a Blob of the body, its `type` the response's
+ *                     Content-Type (a recording, whose reader needs both)
+ *   onDownloadProgress - With blobResponse, called with `{ loaded, total }`
+ *                     (bytes; total null when unknown) as the body arrives
  *   noBusyRetry     - If true, a 503 is not retried. For a query: core
  *                     answers 503 when its queue of large queries stays full
  *                     until the query's deadline, and asking again at once
@@ -775,12 +761,72 @@ export async function queueRequest(batch, method, path, options = {}) {
  *                     where the timeout only fires when the upload stalls;
  *                     elsewhere the callback is ignored and fetch is used.
  */
+/**
+ * What a write about to go out needs to tell the lock keepers it renewed:
+ * each held document's keeper, its version now and the send time. Empty when
+ * no `documents.locked()` block on `client` keeps a lock. The server renews a
+ * live lock on every write its holder makes to the document, so a write that
+ * moved the held document's version renewed it (`writesLanded`).
+ * @private
+ */
+export function writesStarted(client) {
+  const keepers = client.lockKeepers;
+  if (!keepers || keepers.size === 0) return [];
+  return [...keepers.entries()].map(([docId, keeper]) => [
+    keeper,
+    client.documentVersions?.[docId],
+    keeper.now(),
+  ]);
+}
+
+/**
+ * The write `started` was read before has been taken, and its answer's
+ * versions learned. A held document whose version it moved was written by
+ * this run. A replayed answer was not taken again, and renewed nothing.
+ * @private
+ */
+export function writesLanded(client, started, replayed = false) {
+  if (replayed || !started?.length) return;
+  for (const [keeper, before, sent] of started) {
+    const after = client.documentVersions?.[keeper.documentId];
+    if (before != null && after != null && after !== before) {
+      keeper.noteWrite(sent);
+    }
+  }
+}
+
+/**
+ * A response's body as a Blob typed by its Content-Type, `onProgress` told
+ * `{ loaded, total }` after each piece when given (total null when the
+ * response has no Content-Length).
+ * @private
+ */
+async function readBlob(response, onProgress) {
+  const type = response.headers.get("content-type") ?? "";
+  const reader = onProgress ? response.body?.getReader?.() : null;
+  if (!reader) return new Blob([await response.arrayBuffer()], { type });
+  const length = Number(response.headers.get("content-length"));
+  const total = length > 0 ? length : null;
+  const parts = [];
+  let loaded = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    parts.push(value);
+    loaded += value.byteLength;
+    onProgress({ loaded, total });
+  }
+  return new Blob(parts, { type });
+}
+
 export async function makeRequest(client, method, path, options = {}) {
   const {
     formData,
     skipResponseTransform,
     noAuth,
     binaryResponse,
+    blobResponse,
+    onDownloadProgress,
     timeout,
     onUploadProgress,
     learningOmittedVersion,
@@ -829,13 +875,19 @@ export async function makeRequest(client, method, path, options = {}) {
         timeout: timeoutMs,
       });
     }
-    const signal = timeoutSignal(timeoutMs);
-    return fetch(url, signal ? { ...fetchOptions, signal } : fetchOptions);
+    return fetchWithTimeout(url, fetchOptions, timeoutMs);
   };
 
   // One attempt: a 503, and for a keyed write a 502 or 504, surfaces as a
   // throw so the retries below can see it. Other failures are thrown from
   // the checks after it.
+  // A write that lands on a held document renews its lock on the server, so
+  // its keeper hears of it (writesLanded).
+  const started =
+    method !== "GET" && !options.outOfBand ? writesStarted(client) : [];
+  const landed = (headers) =>
+    writesLanded(client, started, headers.get(REPLAYED_HEADER) === "true");
+
   const attempt = async () => {
     let res;
     try {
@@ -853,14 +905,7 @@ export async function makeRequest(client, method, path, options = {}) {
   };
 
   try {
-    const onRetry = (info) => client._noteRetry?.(info);
-    const busy = noBusyRetry ? { onRetry, retries: 0 } : { onRetry };
-    const response = keyed
-      ? await retryUnknown(() => retryWhileBusy(attempt, busy), {
-          delaysMs: client.retryDelaysMs,
-          onRetry,
-        })
-      : await retryWhileBusy(attempt, busy);
+    const response = await withRetries(client, attempt, { keyed, noBusyRetry });
     noteServerClock(client, response.headers);
 
     if (!response.ok) {
@@ -876,32 +921,25 @@ export async function makeRequest(client, method, path, options = {}) {
         return transformResponse({ id: errorData.id });
       }
       const error = makeHttpError(response, errorData, url, method);
-      // 401 means the token is missing/expired/invalid. Fire the app's auth-error
-      // handler once (it discards the token and routes back to login). 403
-      // (forbidden — authenticated but not permitted) deliberately does NOT.
-      if (
-        response.status === 401 &&
-        typeof client.onAuthError === "function" &&
-        !client._authErrorFired
-      ) {
-        client._authErrorFired = true;
-        try {
-          client.onAuthError(error);
-        } catch (_) {
-          /* handler must not mask the original error */
-        }
-      }
+      noteAuthError(client, error);
       throw error;
     }
     // The server took it, so the operation's group exists.
     if (stampedGroup) stampedGroup.written = true;
 
-    // Binary response (getMedia)
+    // Binary response (users.getAvatar)
     if (binaryResponse) {
       extractDocumentVersions(client, response.headers);
+      landed(response.headers);
       if (!learningOmittedVersion) await learnOmittedVersionQuietly(client);
       return await response.arrayBuffer();
     }
+    if (blobResponse) {
+      extractDocumentVersions(client, response.headers);
+      landed(response.headers);
+      if (!learningOmittedVersion) await learnOmittedVersionQuietly(client);
+      return await readBlob(response, onDownloadProgress);
+    }
 
     // JSON or text response
     const contentType = response.headers.get("content-type");
@@ -910,6 +948,7 @@ export async function makeRequest(client, method, path, options = {}) {
       extractDocumentVersions(client, response.headers, data, {
         historical: /[?&]as-of=/.test(url),
       });
+      landed(response.headers);
       if (!learningOmittedVersion) await learnOmittedVersionQuietly(client);
       const answer = skipResponseTransform ? data : transformResponse(data);
       return response.headers.get(REPLAYED_HEADER) === "true"
@@ -917,6 +956,7 @@ export async function makeRequest(client, method, path, options = {}) {
         : answer;
     } else {
       extractDocumentVersions(client, response.headers);
+      landed(response.headers);
       if (!learningOmittedVersion) await learnOmittedVersionQuietly(client);
       return await response.text();
     }