@larc-iu/plaid-client 0.2.0-alpha.1 → 0.2.0-alpha.12

package/src/services.js

@@ -52,13 +52,38 @@ export function discardService(client, projectId, serviceId) {
  * @param {Object} serviceInfo - {serviceId, serviceName, description}
  * @param {function} onServiceRequest - Handler callback (data, responseHelper)
  * @param {Object} extras - Optional additional metadata
- * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .serviceInfo
+ * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+ *   connection-state transitions: 'registered', 'reconnected', 'disconnected'.
+ *   Called once per transition, not once per retry.
+ * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .isConnected(),
+ *   .serviceInfo
  */
-export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}) {
+export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}, onStatus = null) {
   const { serviceId, serviceName, description = '' } = serviceInfo;
   let connection = null;
   let isRunning = true;
   let reconnectTimer = null;
+  // Last state REPORTED, so an outage produces one "lost" line and one "back"
+  // line however many retries it took.
+  let isConnected = false;
+  let everConnected = false;
+
+  const report = (event, detail) => {
+    if (!onStatus) return;
+    try { onStatus(event, projectId, detail); } catch (_) { /* never disturb the loop */ }
+  };
+  const noteConnected = () => {
+    if (isConnected) return;
+    const first = !everConnected;
+    isConnected = true;
+    everConnected = true;
+    report(first ? 'registered' : 'reconnected');
+  };
+  const noteDisconnected = () => {
+    if (!isConnected) return;
+    isConnected = false;
+    report('disconnected');
+  };
 
   const reportEvent = (requestId, body) =>
     client
@@ -76,6 +101,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
       if (connection) connection.close();
     },
     isRunning: () => isRunning,
+    // Whether the request channel is open RIGHT NOW, i.e. whether the server
+    // currently sees this service as online. A registration that is retrying
+    // through a server restart is still running but not connected.
+    isConnected: () => isRunning && !!connection && connection.readyState === 1,
     serviceInfo: { serviceId, serviceName, description, extras },
   };
 
@@ -89,26 +118,92 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
   const qs = params.toString();
   const channelPath = `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests${qs ? `?${qs}` : ''}`;
 
-  // The channel only carries `connected` (ignored) and `service_request` events.
+  // The requests this channel is serving, by id, each flagged once a
+  // `service_cancel` arrives. The handler reads it as `responseHelper.cancelled`;
+  // whether to stop is the handler's decision (a write under way should
+  // finish), and the request still ends with whatever it reports.
+  const cancelled = new Map();
+
+  // Beyond `connected` (ignored), the channel carries `service_request` and
+  // `service_cancel` events.
   const onChannelEvent = (eventType, payload) => {
     if (!isRunning) return true;
-    if (eventType !== 'service_request' || !payload) return;
+    if (!payload) return;
+    if (eventType === 'service_cancel') {
+      if (cancelled.has(payload.requestId)) cancelled.set(payload.requestId, true);
+      return;
+    }
+    if (eventType !== 'service_request') return;
     const requestId = payload.requestId;
     if (!requestId) return;
+    cancelled.set(requestId, false);
+    const finished = () => cancelled.delete(requestId);
 
+    // Every service is told who asked (`requesterId`), beside the payload
+    // when that is a plain object, and on the helper regardless.
+    const requesterId = payload.requesterId || null;
+    const data =
+      requesterId && payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+        ? { ...payload.data, requesterId }
+        : payload.data;
+
+    const scope = createCancelScope(() => cancelled.get(requestId) === true);
     const responseHelper = {
-      progress: (percent, msg) =>
-        reportEvent(requestId, { status: 'progress', progress: { percent, message: msg } }),
-      complete: (data) =>
-        reportEvent(requestId, { status: 'completed', data }),
-      error: (error) =>
-        reportEvent(requestId, { status: 'error', data: { error: error?.message || error } }),
+      requestId,
+      requesterId,
+      // True once the requester asked for the request to stop.
+      get cancelled() {
+        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`).
+      //
+      // 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(payload.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);
@@ -118,12 +213,17 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
     throw new Error(`Failed to start service: ${error.message}`);
   }
 
-  // Reopen the channel if it drops (e.g. the server restarted). Reopening
-  // re-registers the service server-side, so presence and reachability come
-  // back together.
+  // Reopen the channel whenever it drops (e.g. the server restarted), for as
+  // long as the service runs. Reopening re-registers the service server-side,
+  // so presence and reachability come back together, and a server restart never
+  // means a service restart. A reopened channel counts as connected only once
+  // the server has actually answered it (readyState OPEN), not merely because
+  // the attempt was made.
   reconnectTimer = setInterval(() => {
-    if (!isRunning) return;
-    if (connection && connection.readyState === 2) { // CLOSED (dropped)
+    if (!isRunning || !connection) return;
+    if (connection.readyState === 1) { noteConnected(); return; }
+    if (connection.readyState === 2) { // CLOSED (dropped or failed)
+      noteDisconnected();
       try { connection = openChannel(); } catch (_) { /* retry next tick */ }
     }
   }, 3000);
@@ -136,17 +236,32 @@ 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
+ * result given the request id, which `opts.onAccepted` receives as soon as
+ * the server has taken the request. Pass `opts.requestId` (a UUID you mint)
+ * 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]
+ * @param {string} [opts.requestId] - A client-minted request id (UUID)
+ * @param {function} [opts.onAccepted] - Called with the request id once the server has it
  * @returns {Promise<any>} The service's result
  */
-export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress) {
+export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress, signal, opts = {}) {
   // Propagate an open logical operation (client.beginOperation) to the
   // service: its writes then fold under the requester's audit-log entry
   // (the Python BaseService adopts the id around process_request). Only for a
@@ -157,6 +272,133 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
     group && data && typeof data === 'object' && !Array.isArray(data)
       ? { ...data, operationGroup: { id: group.id, message: group.message } }
       : data;
+  const qs = opts.requestId ? `?request-id=${encodeURIComponent(opts.requestId)}` : '';
+  return streamServiceRequest(
+    client,
+    {
+      url: `${client.baseUrl}/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests${qs}`,
+      method: 'POST',
+      body: JSON.stringify(payload === undefined ? null : transformRequest(payload)),
+      onStatus: (response) =>
+        response.status === 503 ? new Error(`No live service '${serviceId}' on this project`) : null,
+      what: 'Service request',
+    },
+    timeout,
+    onProgress,
+    signal,
+    opts.onAccepted,
+  );
+}
+
+/**
+ * Rejoin a service request made earlier (by this user) and await its result:
+ * 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). 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] - 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
+ */
+export function attachServiceRequest(client, projectId, requestId, timeout = 10000, onProgress, signal) {
+  return streamServiceRequest(
+    client,
+    {
+      url: `${client.baseUrl}/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`,
+      method: 'GET',
+      what: 'Attach to service request',
+    },
+    timeout,
+    onProgress,
+    signal,
+  );
+}
+
+/**
+ * Ask the service to stop a request made earlier (by this user). The request
+ * still ends with whatever the service then reports, on the stream of whoever
+ * is awaiting it. Rejects with 404 if unknown or expired, 409 once finished.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @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`,
+ * and `result` / `error` settle the promise.
+ */
+function streamServiceRequest(client, { url, method, body, onStatus, what }, timeout, onProgress, signal, onAccepted) {
   return new Promise((resolve, reject) => {
     const abortController = new AbortController();
     let settled = false;
@@ -167,38 +409,70 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
       abortController.abort();
       fn(arg);
     };
-    const timer = setTimeout(
-      () => finish(reject, new Error(`Service request 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
+    // failure. The service is not told here: it goes on, and its result can
+    // still be collected by request id (see cancelServiceRequest to stop it).
+    const stop = () => {
+      const err = new Error('The service request was stopped');
+      err.name = 'AbortError';
+      finish(reject, stillRunning(err));
+    };
+    if (signal) {
+      if (signal.aborted) {
+        stop();
+        return;
+      }
+      signal.addEventListener('abort', stop, { once: true });
+    }
 
     (async () => {
       let response;
       try {
-        response = await fetch(
-          `${client.baseUrl}/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests`,
-          {
-            method: 'POST',
-            headers: {
-              'Authorization': `Bearer ${client.token}`,
-              'Content-Type': 'application/json',
-              'Accept': 'text/event-stream',
-            },
-            body: JSON.stringify(payload === undefined ? null : transformRequest(payload)),
-            signal: abortController.signal,
+        response = await fetch(url, {
+          method,
+          headers: {
+            'Authorization': `Bearer ${client.token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'text/event-stream',
           },
-        );
+          ...(body === undefined ? {} : { body }),
+          signal: abortController.signal,
+        });
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, new Error(`Failed to submit service request: ${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;
       }
 
-      if (response.status === 503) {
-        finish(reject, new Error(`No live service '${serviceId}' on this project`));
+      const special = onStatus ? onStatus(response) : null;
+      if (special) {
+        finish(reject, special);
         return;
       }
       if (!response.ok) {
-        finish(reject, new Error(`Service request failed: HTTP ${response.status} ${response.statusText}`));
+        const err = new Error(`${what} failed: HTTP ${response.status} ${response.statusText}`);
+        err.status = response.status;
+        finish(reject, err);
         return;
       }
 
@@ -223,13 +497,16 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
               dataLine = line.slice(6);
             } else if (line === '' && eventType && dataLine) {
               const payload = transformResponse(JSON.parse(dataLine));
-              if (eventType === 'progress') {
+              waitAgain(); // it spoke, so it is not hung
+              if (eventType === 'accepted') {
+                if (onAccepted) { try { onAccepted(payload.requestId); } catch (_) { /* ignore */ } }
+              } else if (eventType === 'progress') {
                 if (onProgress) { try { onProgress(payload.progress); } catch (_) { /* ignore */ } }
               } else if (eventType === 'result') {
                 finish(resolve, payload.data);
                 return;
               } else if (eventType === 'error') {
-                finish(reject, new Error(payload?.error || 'Service request failed'));
+                finish(reject, new Error(payload?.error || `${what} failed`));
                 return;
               }
               eventType = '';
@@ -237,9 +514,9 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
             }
           }
         }
-        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(`Service request stream error: ${error.message}`));
+        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} stream error: ${error.message}`)));
       }
     })();
   });

package/src/sse.js

@@ -1,5 +1,36 @@
 import { transformResponse } from './transforms.js';
 
+// A live SSE stream is never silent for long: the server sends a keepalive
+// comment on service channels (every 25s) and a heartbeat event on the /listen
+// bus (every 30s). So if NOTHING arrives for longer than this, the connection is
+// dead: the server was killed without closing the socket, the network dropped
+// it, or a reconnect caught the server mid-restart (port accepting, app not yet
+// streaming). We must surface that as a drop so the registration supervisor in
+// serve() can reopen it. Without the watchdog such a silent drop
+// leaves `reader.read()` pending forever: readyState never reaches CLOSED, so
+// nothing reconnects and the service never heals. Comfortably above both server
+// cadences, so a healthy idle stream never trips it.
+export const SSE_IDLE_TIMEOUT_MS = 60000;
+
+/**
+ * Project a parsed SSE `data:` object onto what a listener callback sees.
+ *
+ * The envelope is API surface and gets the usual `transformResponse` recasing.
+ * A `message` event's `data` is NOT: it is opaque application data (whatever
+ * `sendMessage` was handed), so its keys must survive verbatim, exactly as
+ * `metadata` and `config` do elsewhere. Without this, a key written
+ * `case-marker` reaches a JavaScript listener as `caseMarker` and a Python
+ * listener as `case_marker`, so the same broadcast reads differently depending
+ * on the reader's language.
+ */
+export function eventPayload(eventType, parsed) {
+  const payload = transformResponse(parsed);
+  if (eventType === 'message' && parsed && typeof parsed === 'object' && 'data' in parsed) {
+    payload.data = parsed.data;
+  }
+  return payload;
+}
+
 /**
  * Create an SSE connection to the listen endpoint using fetch-based streaming.
  * Automatically handles heartbeat confirmations and event parsing.
@@ -40,6 +71,21 @@ export function createSSEConnection(client, projectId, onEvent, path) {
     }
   };
 
+  // Watchdog: abort the fetch if the stream goes silent for longer than the
+  // server's keepalive cadence, so a silently-dropped connection lands in the
+  // catch below (readyState CLOSED) instead of blocking on a read that will
+  // never resolve.
+  let idleTimer = null;
+  const clearIdleTimer = () => {
+    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+  const armIdleTimer = () => {
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      if (!isClosed) abortController.abort(new Error('SSE stream went silent'));
+    }, SSE_IDLE_TIMEOUT_MS);
+  };
+
   const sseConnection = {
     readyState: 0, // CONNECTING
     close: () => {
@@ -47,6 +93,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
         isClosed = true;
         isConnected = false;
         sseConnection.readyState = 2; // CLOSED
+        clearIdleTimer();
         abortController.abort();
       }
     },
@@ -64,6 +111,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
   (async () => {
     try {
       const url = `${client.baseUrl}${streamPath}`;
+      armIdleTimer();
       const response = await fetch(url, {
         method: 'GET',
         headers: {
@@ -101,6 +149,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       while (true) {
         const { done, value } = await reader.read();
         if (done || isClosed) break;
+        armIdleTimer();
 
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split('\n');
@@ -124,7 +173,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
                 sendHeartbeatConfirmation();
               } else {
                 const parsedData = JSON.parse(data);
-                const shouldStop = onEvent(eventType, transformResponse(parsedData));
+                const shouldStop = onEvent(eventType, eventPayload(eventType, parsedData));
                 if (shouldStop === true) {
                   sseConnection.close();
                   return;
@@ -144,6 +193,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
         console.warn('SSE connection error:', error);
       }
     } finally {
+      clearIdleTimer();
       isConnected = false;
       isClosed = true;
       sseConnection.readyState = 2; // CLOSED