@larc-iu/plaid-client 0.2.0-alpha.13 → 0.2.0-alpha.16

package/src/http.js

@@ -1,5 +1,52 @@
 import { transformRequest, transformResponse } from "./transforms.js";
 
+// ---------------------------------------------------------------------------
+// Batches: which calls a batch carries, and which go over the wire anyway.
+//
+// A batch is an OBJECT (`client.batch()`, or the argument `client.batched(fn)`
+// hands `fn`), a view of the client with the same bundles. A write made on the
+// batch queues; a call made on the client itself always goes over the wire,
+// whatever batches happen to be open. So the editor, the importer and the
+// app's chrome can share one client, and a write by code that knows nothing
+// about a batch can never land inside it. Every call reaching this layer is
+// one of three things, and the third column is what a new endpoint has to
+// pick.
+//
+// 1. A WRITE of project data: an entity, its metadata, a layer, a membership,
+//    a comment. This is what a batch is for, so on a batch it QUEUES. It is
+//    the default and needs no flag.
+//
+// 2. A READ. Every GET is answered from the wire even when made on a batch:
+//    the caller gets data rather than `{ batched: true }`, it takes no slot in
+//    the batch's results, and server-side it runs against the pool rather than
+//    the batch's transaction connection. A read that travels as a POST
+//    (`query`) says so with `outOfBand`.
+//
+// 3. An OUT-OF-BAND SIGNAL: stopping a service request, reporting a service's
+//    progress or result, taking or dropping a document lock, forgetting a
+//    service, an admin action on the server itself. It is shaped like a write
+//    but carries no project data, and its whole value is that it happens NOW.
+//    Pass `outOfBand`: made on a batch it still goes over the wire, and it
+//    never joins an open logical operation. The audit group is a label for
+//    the writes, and a signal that is never audited would mark the group
+//    written and leave the relabel PATCH 404ing on a group nothing ever
+//    created.
+//
+// Strict mode stamps the batch's one expected document-version onto the first
+// write queued on it (whole-batch OCC: stamping every op would 409 the second
+// against the bump the first caused). A call that went over the wire on its
+// own carries its own stamp and spends nothing of any batch's.
+//
+// `noBatch` is not part of that judgment. It marks the five calls the batch
+// transport cannot carry at all (a batch inside a batch, the multipart media
+// and avatar uploads, the user-data store's put and delete) and raises so the
+// caller finds out. Never put it on a read: it turns a swallowed read into a
+// thrown one, which is what the chrome hit when an unrelated import was
+// running. A blobless DELETE beside an upload is not one of them: it carries
+// nothing the transport cannot express, so it takes its class from the three
+// above like anything else.
+// ---------------------------------------------------------------------------
+
 // Default per-request timeout (ms). Applied to every request unless the client
 // is constructed with a different `timeout` (0 / null disables it). Note: this
 // also bounds media up/downloads — bump it (or disable) for very large files.
@@ -253,14 +300,13 @@ export function xhrSend(
  *   rawBody         - Body value passed directly (no transform). Mutually exclusive with body.
  *   formData        - If true, body is FormData; skip Content-Type header
  *   queryParams     - Object of query param key/values to append
- *   noBatch         - If true, throw when in batch mode
- *   bypassBatch     - If true, go over the wire even while a batch is open.
- *                     For READS only: a batch is a write transaction, its
- *                     ops return no value to their caller until submit, and
- *                     the sub-request runs against the tx Connection rather
- *                     than the pool. A read swallowed by an ambient batch is
- *                     therefore useless to the caller AND can fail the whole
- *                     batch (see `query`).
+ *   noBatch         - If true, throw when made on a batch. Only for calls the
+ *                     batch transport cannot carry at all (see the note at the
+ *                     top of this file); never for a read.
+ *   outOfBand       - If true, the call is a signal rather than a write of
+ *                     project data: made on a batch it still goes over the
+ *                     wire, and it never joins an open logical operation (see
+ *                     the note at the top of this file).
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
@@ -273,21 +319,34 @@ export function xhrSend(
  *                     where the timeout only fires when the upload stalls;
  *                     elsewhere the callback is ignored and fetch is used.
  */
-export async function makeRequest(client, method, path, options = {}) {
-  const {
-    body,
-    rawBody,
-    formData,
-    queryParams,
-    noBatch,
-    bypassBatch,
-    skipResponseTransform,
-    noAuth,
-    binaryResponse,
-    auditMessage,
-    timeout,
-    onUploadProgress,
-  } = options;
+/**
+ * Everything a request is before it goes anywhere: the URL with its query
+ * params and the stamps strict mode, a per-call audit message and an open
+ * logical operation add, plus the transformed body. Shared by the wire path
+ * (`makeRequest`) and the batch path (`queueRequest`), so a queued op is
+ * exactly the request that would have gone out. `batch` is the batch the call
+ * is being queued on, if any: strict mode stamps its document-version onto the
+ * first write queued there and no other.
+ */
+export function prepareRequest(
+  client,
+  method,
+  path,
+  options = {},
+  batch = null,
+) {
+  const { body, rawBody, formData, queryParams, outOfBand, auditMessage } =
+    options;
+
+  // A write must not go out on a lock that lapsed. `documents.locked()`
+  // records the loss here when its keep-alive cannot renew, and from that
+  // moment the block is holding nothing: an edit by somebody else can already
+  // have landed between the read the work was planned from and the write about
+  // to go out. Reads pass, and so do the lock routes themselves, which is how
+  // the block still releases on its way out.
+  if (client.documentLockLost && method !== "GET" && !path.endsWith("/lock")) {
+    throw client.documentLockLost;
+  }
 
   // Build URL
   let url = `${client.baseUrl}${path}`;
@@ -317,23 +376,19 @@ export async function makeRequest(client, method, path, options = {}) {
     requestBody = transformRequest(body);
   }
 
-  // Strict mode: append document-version for non-GET requests.
-  // Inside a batch, stamp ONLY the first write: batches run atomically
-  // server-side, so a version check on the first op gives whole-batch OCC
-  // semantics, while stamping every op would 409 the second op against the
-  // version bump the first op itself caused (every queued op captures the
-  // same pre-batch version).
-  if (
-    client.strictModeDocumentId &&
-    method !== "GET" &&
-    !(client.isBatching && client.batchVersionStamped)
-  ) {
+  // Strict mode: append document-version for non-GET requests, on EVERY
+  // queued write of a batch. The server validates the first write it can
+  // (one whose route resolves a document) and skips the rest of that
+  // document's, so the version bump a sub-op causes does not 409 the next
+  // one. Stamping only the first write was silently no check at all
+  // whenever that write was one the route ignores, such as a vocabulary
+  // entry's metadata, which is exactly what the igt editor queues first.
+  if (client.strictModeDocumentId && method !== "GET") {
     const docId = client.strictModeDocumentId;
     if (client.documentVersions[docId]) {
       const docVersion = client.documentVersions[docId];
       const separator = url.includes("?") ? "&" : "?";
       url += `${separator}document-version=${encodeURIComponent(docVersion)}`;
-      if (client.isBatching) client.batchVersionStamped = true;
     }
   }
 
@@ -350,7 +405,12 @@ export async function makeRequest(client, method, path, options = {}) {
   // Logical-operation group (see client.beginOperation): stamp every write
   // with the group id; the message rides along too so the server can label
   // the group lazily on whichever tagged write lands first.
-  if (client.operationGroup && method !== "GET") {
+  //
+  // An out-of-band signal is not one of those writes (see the note at the top
+  // of this file): it never lands in the audit log, so a stamp does nothing
+  // server-side while `written` promises a group that will never exist, and
+  // the relabel PATCH then 404s.
+  if (client.operationGroup && method !== "GET" && !outOfBand) {
     const group = client.operationGroup;
     const separator = url.includes("?") ? "&" : "?";
     url += `${separator}group-id=${encodeURIComponent(group.id)}`;
@@ -359,24 +419,54 @@ export async function makeRequest(client, method, path, options = {}) {
     group.written = true;
   }
 
-  // Batch mode. A `bypassBatch` read is deliberately NOT queued: it belongs to
-  // whoever called it, not to whatever batch happens to be open on this shared
-  // client (a document reconcile, an import), and it reads the pre-batch state
-  // exactly as it would have if the batch were not running.
-  if (client.isBatching && !bypassBatch) {
-    if (noBatch) {
-      throw new Error(`This endpoint cannot be used in batch mode: ${path}`);
-    }
-    const operation = {
-      path: url.replace(client.baseUrl, ""),
-      method: method.toUpperCase(),
-    };
-    if (requestBody !== undefined) {
-      operation.body = requestBody;
-    }
-    client.batchOperations.push(operation);
-    return { batched: true };
+  return { url, requestBody };
+}
+
+/**
+ * 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.
+ */
+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 } = prepareRequest(
+    batch.client,
+    method,
+    path,
+    options,
+    batch,
+  );
+  const operation = {
+    path: url.replace(batch.client.baseUrl, ""),
+    method: method.toUpperCase(),
+  };
+  if (requestBody !== undefined) {
+    operation.body = requestBody;
+  }
+  batch.operations.push(operation);
+  return { batched: true };
+}
+
+export async function makeRequest(client, method, path, options = {}) {
+  const {
+    formData,
+    skipResponseTransform,
+    noAuth,
+    binaryResponse,
+    timeout,
+    onUploadProgress,
+  } = options;
+  const { url, requestBody } = prepareRequest(client, method, path, options);
 
   // Build fetch options
   const headers = {};