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

package/src/provenance.js

@@ -99,6 +99,25 @@ export const PROV = Object.freeze({
   CONTRIBUTED: 'contributed',
 });
 
+/**
+ * Every provenance key, for a caller that has to name them as a set rather
+ * than read one: what a token layer declares under
+ * `config.plaid.preserveOnSplit` so a token born of a split inherits the
+ * origin of the token it came from, and what a reshape carries by hand.
+ *
+ * Provenance is the one metadata family Plaid itself owns. The user cannot
+ * maintain it, and in a shared project usually cannot even see it, since it
+ * may belong to an app they are not using. Everything else on an entity is
+ * the user's own content and no structural operation should touch it.
+ */
+export const PROVENANCE_KEYS = Object.freeze([
+  PROV.key,
+  PROV.sourceKey,
+  PROV.confirmedKey,
+  PROV.probKey,
+  PROV.detailKey,
+]);
+
 /** The four provenance states returned by provState. */
 export const PROV_STATES = Object.freeze({
   HUMAN: 'human',

package/src/roles.js

@@ -25,6 +25,15 @@ export const PLAID_NAMESPACE = 'plaid';
 export const ROLE_KEY = 'role';
 
 /** The fixed role inventory. */
+/**
+ * Layer config key naming the metadata keys a token born of a SPLIT inherits
+ * from the token it came from. Plaid honors it without knowing what the keys
+ * mean; see the manual's `Metadata Preserved Across a Split`. An app declares
+ * it so that a split in ANY app, including one that has never heard of these
+ * keys, does not silently drop them.
+ */
+export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',

package/src/serviceSchema.js

@@ -21,7 +21,7 @@
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
- *         min?, max?, step?,            // number
+ *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
  *         placeholder?, multiline? }    // string
  *     ]
  *   }
@@ -52,7 +52,17 @@ export const TASKS = Object.freeze({
   ANALYZE: "analyze",
   /** Propose a free translation for each sentence. */
   TRANSLATE: "translate",
-  /** A conversational assistant over a project (chat turns; see plaid-igt-agent). */
+  /**
+   * Propose time-aligned speech regions for a recording.
+   *
+   * The odd one out: a detect-speech service RETURNS its regions and writes
+   * nothing, because a time-aligned segment is a stretch of the baseline and
+   * cannot exist without text. The response carries
+   * `{segments: [{timeBegin, timeEnd, speaker?}]}` (seconds), and the app
+   * holds them as proposals until a person types into one.
+   */
+  DETECT_SPEECH: "detect-speech",
+  /** A conversational assistant over a project (chat turns; see plaid-agent). */
   ASSIST: "assist",
 });
 

package/src/services.js

@@ -147,31 +147,63 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
         ? { ...payload.data, requesterId }
         : payload.data;
 
+    const scope = createCancelScope(() => cancelled.get(requestId) === true);
     const responseHelper = {
       requestId,
       requesterId,
       // True once the requester asked for the request to stop.
       get cancelled() {
-        return cancelled.get(requestId) === true;
+        return scope.cancelled;
       },
+      raiseIfCancelled: () => scope.raiseIfCancelled(),
+      critical: (fn) => scope.critical(fn),
       // Extra fields ride in the progress payload (a chat service sends the
       // reply text so far as `text`).
-      progress: (percent, msg, extra) =>
-        reportEvent(requestId, { status: 'progress', progress: { percent, message: msg, ...extra } }),
+      //
+      // This is a CANCELLATION CHECKPOINT: it throws ServiceCancelled if the
+      // requester has stopped the request, so a service that reports progress
+      // through its work is cancellable without doing anything else. Use
+      // `critical()` around writes to hold it off.
+      progress: (percent, msg, extra) => {
+        scope.raiseIfCancelled();
+        return reportEvent(requestId, {
+          status: 'progress',
+          progress: { percent, message: msg, ...extra },
+        });
+      },
       complete: (data) => {
         finished();
         return reportEvent(requestId, { status: 'completed', data });
       },
+      // Asked to stop, and it did. Reported as a result carrying
+      // `stopped: true`, so a client can tell "you stopped it" from "it broke".
+      stopped: (data) => {
+        finished();
+        return reportEvent(requestId, {
+          status: 'completed',
+          data: { ...(data || {}), stopped: true },
+        });
+      },
       error: (error) => {
         finished();
         return reportEvent(requestId, { status: 'error', data: { error: error?.message || error } });
       },
     };
 
+    // A handler may be async, so a rejected promise has to be caught too, or a
+    // cancelled async service would report a failure instead of a stop.
+    const settle = (error) => {
+      if (error instanceof ServiceCancelled || error?.name === 'ServiceCancelled') {
+        responseHelper.stopped();
+      } else {
+        responseHelper.error(error?.message || error);
+      }
+    };
     try {
-      onServiceRequest(data, responseHelper);
+      const maybe = onServiceRequest(data, responseHelper);
+      if (maybe && typeof maybe.catch === 'function') maybe.catch(settle);
     } catch (error) {
-      responseHelper.error(error?.message || error);
+      settle(error);
     }
   };
   const openChannel = () => client.messages.listen(projectId, onChannelEvent, channelPath);
@@ -204,7 +236,7 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  *
  * Streams the service's progress + result back over a single server-mediated
  * response (no broadcast). Rejects if no service is connected (503), if the
- * service reports an error, or on timeout.
+ * service reports an error, or after `timeout` of SILENCE.
  *
  * The request outlives this call: after a timeout, an abort, or a dropped
  * connection the service goes on, and `attachServiceRequest` collects the
@@ -213,11 +245,15 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * to know the id before submitting; submitting an id that names a request
  * you already made rejoins it instead of starting another.
  *
+ * Errors that leave the request alive carry `pending: true`: a timeout, a
+ * stop, a dropped connection. An error without it is the end of the request.
+ *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
  * @param {string} serviceId - Service ID to request
  * @param {any} data - Request payload
- * @param {number} [timeout=10000] - Timeout in ms
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms.
+ *   Every event it sends starts the clock again, so this does not cap a long run
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @param {Object} [opts]
@@ -259,12 +295,14 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
  * the latest progress is replayed, then the result comes, or at once if the
  * request already finished. Rejects with an error whose `status` is 404 when
  * the request is unknown or expired (the server keeps a finished request's
- * result for a while, not forever).
+ * result for a while, not forever). As with `requestService`, `timeout` is
+ * how long the service may be silent, and an error carrying `pending: true`
+ * means the request is still there to rejoin again.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
  * @param {string} requestId - The request id (from `onAccepted` or your own)
- * @param {number} [timeout=10000] - Timeout in ms
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @returns {Promise<any>} The service's result
@@ -293,10 +331,68 @@ export function attachServiceRequest(client, projectId, requestId, timeout = 100
  * @param {string} requestId - The request id
  * @returns {Promise<void>}
  */
+/**
+ * Thrown inside a handler when the requester has asked it to stop.
+ *
+ * Cooperative cancellation: nothing interrupts a handler, so the request ends
+ * at the next point the handler looks. `responseHelper.progress` is that
+ * point, which is why a long service that already reports progress needs no
+ * changes at all. `serve` catches this and ends the request as STOPPED rather
+ * than failed.
+ */
+export class ServiceCancelled extends Error {
+  constructor(message = 'The requester stopped this request') {
+    super(message);
+    this.name = 'ServiceCancelled';
+  }
+}
+
+/**
+ * The cancellation half of a responseHelper: a flag, a depth counter, and one
+ * rule about when a checkpoint may raise. Split from the transport so it can
+ * be reasoned about on its own. Mirrors `CancelScope` in the Python client.
+ */
+export function createCancelScope(isCancelled) {
+  // Depth of nested `critical()` blocks; while non-zero, a checkpoint will
+  // not throw.
+  let criticalDepth = 0;
+  return {
+    get cancelled() {
+      return !!isCancelled();
+    },
+    /** Stop here if the requester has asked the request to stop. */
+    raiseIfCancelled() {
+      if (isCancelled() && criticalDepth === 0) throw new ServiceCancelled();
+    },
+    /**
+     * Run `fn` as a stretch that must finish once begun, usually the writes.
+     * Checkpoints inside do not throw, so a half-written document is never
+     * left behind; cancellation takes effect at the first checkpoint after.
+     */
+    async critical(fn) {
+      criticalDepth++;
+      try {
+        return await fn();
+      } finally {
+        criticalDepth--;
+      }
+    },
+  };
+}
+
 export function cancelServiceRequest(client, projectId, requestId) {
   return client._request('DELETE', `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`);
 }
 
+/**
+ * Mark an error as one that leaves the request ALIVE on the server: a timeout,
+ * a stop, a dropped connection. The service goes on working and its result
+ * still waits under the request id, so a caller holding that id can rejoin it
+ * with `attachServiceRequest`, and must not forget the id the way it forgets
+ * a request that really ended. An error without `pending` is terminal.
+ */
+const stillRunning = (err) => Object.assign(err, { pending: true });
+
 /**
  * Open a request stream (submit or attach) and read it to its terminal
  * event: `accepted` names the request, `progress` events go to `onProgress`,
@@ -313,10 +409,23 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
       abortController.abort();
       fn(arg);
     };
-    const timer = setTimeout(
-      () => finish(reject, new Error(`${what} timed out after ${timeout}ms`)),
-      timeout,
-    );
+
+    // `timeout` is IDLE time, meaning how long the service may say nothing. It
+    // is not a deadline on the run: every event from the server restarts it,
+    // because a service that is reporting its progress is not hung. As a
+    // deadline on the whole run it killed working transcriptions at the
+    // five-minute default and left their writes to land on a document the page
+    // had already handed back to the user as editable.
+    let timer;
+    const waitAgain = () => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () =>
+          finish(reject, stillRunning(new Error(`${what} timed out after ${timeout}ms of silence`))),
+        timeout,
+      );
+    };
+    waitAgain();
 
     // An external signal stops waiting on a long request (a UI's Stop button).
     // Reject with an AbortError so a caller can tell a deliberate stop from a
@@ -325,7 +434,7 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
     const stop = () => {
       const err = new Error('The service request was stopped');
       err.name = 'AbortError';
-      finish(reject, err);
+      finish(reject, stillRunning(err));
     };
     if (signal) {
       if (signal.aborted) {
@@ -349,7 +458,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
           signal: abortController.signal,
         });
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, new Error(`${what} could not be sent: ${error.message}`));
+        // The POST may or may not have reached the server. Treat it as alive:
+        // rejoining a request that was never made simply 404s.
+        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} could not be sent: ${error.message}`)));
         return;
       }
 
@@ -386,6 +497,7 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
               dataLine = line.slice(6);
             } else if (line === '' && eventType && dataLine) {
               const payload = transformResponse(JSON.parse(dataLine));
+              waitAgain(); // it spoke, so it is not hung
               if (eventType === 'accepted') {
                 if (onAccepted) { try { onAccepted(payload.requestId); } catch (_) { /* ignore */ } }
               } else if (eventType === 'progress') {
@@ -402,9 +514,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
             }
           }
         }
-        finish(reject, new Error('Service closed the connection without a result'));
+        finish(reject, stillRunning(new Error('Service closed the connection without a result')));
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, new Error(`${what} stream error: ${error.message}`));
+        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} stream error: ${error.message}`)));
       }
     })();
   });