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

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,24 +118,58 @@ 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 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 cancelled.get(requestId) === true;
+      },
+      // 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 } }),
+      complete: (data) => {
+        finished();
+        return reportEvent(requestId, { status: 'completed', data });
+      },
+      error: (error) => {
+        finished();
+        return reportEvent(requestId, { status: 'error', data: { error: error?.message || error } });
+      },
     };
 
     try {
-      onServiceRequest(payload.data, responseHelper);
+      onServiceRequest(data, responseHelper);
     } catch (error) {
       responseHelper.error(error?.message || error);
     }
@@ -118,12 +181,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);
@@ -138,15 +206,26 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * response (no broadcast). Rejects if no service is connected (503), if the
  * service reports an error, or on timeout.
  *
+ * 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.
+ *
  * @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 {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 +236,73 @@ 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).
+ *
+ * @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 {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>}
+ */
+export function cancelServiceRequest(client, projectId, requestId) {
+  return client._request('DELETE', `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`);
+}
+
+/**
+ * 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;
@@ -168,37 +314,54 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
       fn(arg);
     };
     const timer = setTimeout(
-      () => finish(reject, new Error(`Service request timed out after ${timeout}ms`)),
+      () => finish(reject, new Error(`${what} timed out after ${timeout}ms`)),
       timeout,
     );
 
+    // 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, 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}`));
+        if (error.name !== 'AbortError') finish(reject, 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 +386,15 @@ 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') {
+              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 = '';
@@ -239,7 +404,7 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
         }
         finish(reject, 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, 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