@larc-iu/plaid-client 0.2.0-alpha.14 → 0.2.0-alpha.17

package/src/metadataOps.js

@@ -0,0 +1,117 @@
+/**
+ * Metadata ops: the body of every metadata PATCH, and the `metadata` of a
+ * bulk update entry. An op is `{op: 'set', path, value}` or
+ * `{op: 'delete', path}`, where `path` is a non-empty array of keys into the
+ * nested metadata, the first a top-level key. See the manual, "Metadata".
+ */
+
+import { PLAID_NAMESPACE } from './roles.js';
+import { PROVENANCE_KEYS } from './provenance.js';
+
+const RESERVED_KEYS = new Set([PLAID_NAMESPACE, ...PROVENANCE_KEYS]);
+
+/**
+ * True for a top-level metadata key Plaid keeps for itself: the shared `plaid`
+ * namespace (settings every app reads, such as the text direction) and the
+ * provenance keys. Neither is ever a user's metadata field, so an app neither
+ * lists it as one nor writes a field's value to it.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isReservedMetadataKey = (key) => RESERVED_KEYS.has(key);
+
+// The longest top-level key the server takes, in UTF-16 code units (Java's
+// String length, which is what it counts).
+const MAX_KEY_LENGTH = 200;
+
+// Java's Character.isWhitespace, which the server's blank check uses: the
+// Unicode space separators except the three no-break spaces, and the ASCII
+// whitespace controls.
+const isJavaWhitespace = (c) =>
+  (/[\p{Zs}\p{Zl}\p{Zp}]/u.test(c) && c !== '\u00A0' && c !== '\u2007' && c !== '\u202F') ||
+  /[\t\n\u000B\f\r\u001C-\u001F]/.test(c);
+
+/**
+ * True when the server accepts `k` as a top-level metadata key: not blank,
+ * at most 200 UTF-16 code units, and no ASCII control character.
+ * @param {string} k
+ * @returns {boolean}
+ */
+const validMetadataKey = (k) =>
+  typeof k === 'string' &&
+  k.length <= MAX_KEY_LENGTH &&
+  !/[\u0000-\u001F\u007F]/.test(k) &&
+  ![...k].every(isJavaWhitespace);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The ops that set each top-level key of `fragment`, deleting a key whose
+ * value is null. This is how a provenance fragment (verifyOnEdit,
+ * contributeOnEdit, ...) is sent as a patch.
+ * @param {Object|null|undefined} fragment
+ * @returns {Array<{op: string, path: string[], value?: any}>}
+ */
+export const metadataOps = (fragment) =>
+  Object.entries(fragment || {}).map(([k, v]) =>
+    v === null ? { op: 'delete', path: [k] } : { op: 'set', path: [k], value: v },
+  );
+
+const applyOp = (node, path, depth, o) => {
+  const [k, ...more] = path.slice(depth);
+  if (more.length === 0) {
+    const out = { ...node };
+    if (o.op === 'set') out[k] = o.value;
+    else delete out[k];
+    return out;
+  }
+  const child = Object.prototype.hasOwnProperty.call(node, k) ? node[k] : undefined;
+  if (child === undefined) {
+    return o.op === 'set' ? { ...node, [k]: applyOp({}, path, depth + 1, o) } : node;
+  }
+  if (!isObject(child)) {
+    throw new Error(
+      `Metadata path ${JSON.stringify(path.slice(0, depth + 1))} holds a value that is not an object`,
+    );
+  }
+  return { ...node, [k]: applyOp(child, path, depth + 1, o) };
+};
+
+/**
+ * Apply ops to a local copy of an entity's metadata the way the server does,
+ * for an optimistic update. Returns a new object and never mutates its input.
+ * Throws where the server would refuse (a path through a non-object, or a
+ * first key that is blank, over 200 characters or holds a control character).
+ * @param {Object|null|undefined} metadata
+ * @param {Array<{op: string, path: string[], value?: any}>} ops
+ * @returns {Object}
+ */
+export const applyMetadataOps = (metadata, ops) =>
+  (ops || []).reduce((m, o) => {
+    if (!Array.isArray(o.path) || o.path.length === 0) {
+      throw new Error('A metadata op needs a non-empty path');
+    }
+    if (!validMetadataKey(o.path[0])) {
+      throw new Error('Invalid metadata key');
+    }
+    if (o.op !== 'set' && o.op !== 'delete') {
+      throw new Error(`Unknown metadata op '${o.op}': expected set or delete`);
+    }
+    if (o.op === 'set' && !('value' in o)) {
+      throw new Error('A set op needs a value');
+    }
+    return applyOp(m, o.path, 0, o);
+  }, { ...(metadata || {}) });
+
+/**
+ * Merge a top-level fragment into a local copy, a null value deleting the
+ * key: applyMetadataOps over metadataOps(fragment), so the same result as
+ * sending those ops, refused where the server would refuse them. How an app
+ * mirrors a provenance stamp (verifyOnEdit, contributeOnEdit, ...) on the row
+ * it shows. Returns a new object.
+ * @param {Object|null|undefined} metadata
+ * @param {Object|null|undefined} fragment
+ * @returns {Object}
+ */
+export const mergeMetadata = (metadata, fragment) =>
+  applyMetadataOps(metadata, metadataOps(fragment));

package/src/pagination.js

@@ -11,10 +11,9 @@
  * headers, base URL, and response transforms all apply exactly as for any
  * other request.
  *
- * A page is a read, so every request these helpers make carries `bypassBatch`
- * (see the three classes at the top of http.js). That is what lets them work
- * while a batch is open on the same client: each page is answered from the
- * pool, in order, against the state the batch has not committed yet.
+ * A page is a read, so it goes over the wire even when the helper is handed a
+ * batch (see the note at the top of http.js): each page is answered from the
+ * pool, in order, against the state no batch has committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -57,7 +56,6 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
-      bypassBatch: true,
     });
     all.push(...entriesOf(response, path));
     prevCursor = cursor;
@@ -87,7 +85,6 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
 export async function listPage(client, path, { limit, cursor, query = {} } = {}) {
   return client._request('GET', path, {
     queryParams: buildQueryParams(query, limit, cursor),
-    bypassBatch: true,
   });
 }
 
@@ -108,7 +105,6 @@ export async function* iterPages(client, path, { pageSize = 1000, query = {} } =
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
-      bypassBatch: true,
     });
     const entries = entriesOf(response, path);
     // Suppress the trailing empty page that the server emits when a collection's

package/src/provenance.js

@@ -228,8 +228,8 @@ export const verifyOnEdit = (metadata) => (needsReview(metadata) ? PROV_CONFIRME
 /**
  * The metadata fragment a CONTRIBUTOR's edit of this entity should merge in
  * (write-contract rule 3): the contributed stamp, plus provConfirmed: null
- * so an earlier confirmation is dropped (a patch deletes null-valued keys;
- * see mergeMetadata for a full replace). Prediction extras a machine
+ * so an earlier confirmation is dropped (send it with metadataOps, which
+ * turns a null into a delete, or apply it locally with mergeMetadata). Prediction extras a machine
  * recorded stay, as history.
  * @param {Object|null|undefined} metadata - unused today; the fragment is
  *   the same whatever the entity was, and the parameter keeps the shape of
@@ -242,20 +242,6 @@ export const contributeOnEdit = (metadata, userId) => ({
   [PROV.confirmedKey]: null,
 });
 
-/**
- * Merge a metadata fragment the way the server's PATCH does — a null value
- * deletes the key — for callers that keep a local copy or send a full
- * replacement (setMetadata). Returns a new object.
- */
-export const mergeMetadata = (metadata, fragment) => {
-  const out = { ...(metadata || {}) };
-  for (const [k, v] of Object.entries(fragment || {})) {
-    if (v === null) delete out[k];
-    else out[k] = v;
-  }
-  return out;
-};
-
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export const serviceSource = (serviceId) => `service:${serviceId}`;
 

package/src/serviceSchema.js

@@ -22,10 +22,15 @@
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
  *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
- *         placeholder?, multiline? }    // string
+ *         placeholder?, multiline?,     // string
+ *         scope? }                      // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
+ * A `field` parameter names one of the project's annotation fields at its
+ * `scope`. A UI that knows the project offers those fields to choose from; to
+ * everything here, and to a UI that does not, it is a string.
+ *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
  * in your service's own convention (Python: snake_case; JS: camelCase) and read
@@ -50,6 +55,20 @@ export const TASKS = Object.freeze({
   LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
   ANALYZE: "analyze",
+  /**
+   * Draft a meaning representation graph over the sentences of a document,
+   * for correction by hand. The request names a `scope` ('document' or
+   * 'sentence'), a `sentence` number when the scope is one sentence, and
+   * `overwrite`. See plaid-umr's drafting services.
+   *
+   * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
+   * service against, and these two share almost none of it: an analyze
+   * request names the three token layers plus the language, metalanguage and
+   * orthography, and writes morphemes and glosses. Both claimed `analyze` for
+   * a while, so every app offering an analyze spot offered the other app's
+   * services, which could not answer the request they would have been given.
+   */
+  DRAFT_GRAPH: "draft-graph",
   /** Propose a free translation for each sentence. */
   TRANSLATE: "translate",
   /**
@@ -64,6 +83,13 @@ export const TASKS = Object.freeze({
   DETECT_SPEECH: "detect-speech",
   /** A conversational assistant over a project (chat turns; see plaid-agent). */
   ASSIST: "assist",
+  /**
+   * Score one document's annotation against another document's of the same
+   * text (two annotators' copies), writing a report on the scored document's
+   * metadata and never an annotation. The request names the other document
+   * as `against`. See plaid-umr's AnCast service.
+   */
+  COMPARE: "compare",
 });
 
 /**

package/src/services.js

@@ -92,14 +92,7 @@ export function serviceErrorMessage(error, serviceName = '', secrets = []) {
  * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
  */
 export function discoverServices(client, projectId) {
-  // bypassBatch: the registry is read by whoever asked, not by whatever batch
-  // happens to be open on this shared client. The assistant's availability
-  // probe polls for 49 seconds after a mount and landed inside a Grew rewrite
-  // or an import, where the answer was `{batched: true}`, cached as the
-  // service list, and every later render threw on it until a reload.
-  return client._request('GET', `/api/v1/projects/${projectId}/services`, {
-    bypassBatch: true,
-  });
+  return client._request('GET', `/api/v1/projects/${projectId}/services`);
 }
 
 /**
@@ -113,17 +106,21 @@ export function discoverServices(client, projectId) {
  * @returns {Promise<void>}
  */
 export function discardService(client, projectId, serviceId) {
-  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`);
+  // outOfBand: the registry is not project data (see the note at the top of
+  // http.js).
+  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`, {
+    outOfBand: true,
+  });
 }
 
 /**
  * POST a progress, result or error event for an in-flight request; the server
  * relays it to the waiting requester. The Python twin is `_report_event`.
  *
- * bypassBatch: these are out-of-band signals to whoever is waiting, not writes
- * to the project. A service reports them from inside its own
- * `client.batched()` block, where queueing them would hold every one back
- * until submit, deliver none at all if the batch aborts, and take slots in the
+ * outOfBand: these are signals to whoever is waiting, not writes to the
+ * project (see the note at the top of http.js). A service may report them on
+ * the batch it is filling, where queueing them would hold every one back until
+ * submit, deliver none at all if the batch aborts, and take slots in the
  * batch's results. The requester would hear nothing and wait out its idle
  * timeout on work that had already finished.
  *
@@ -137,10 +134,17 @@ export function reportRequestEvent(client, projectId, requestId, body) {
   return client._request(
     'POST',
     `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}/events`,
-    { body, bypassBatch: true },
+    { body, outOfBand: true },
   );
 }
 
+/**
+ * HTTP statuses a refused service channel answers with that retrying cannot
+ * fix: a bad or revoked token, no write access to the project, a project that
+ * does not exist. The same set as the Python client's.
+ */
+const PERMANENT_STATUSES = new Set([400, 401, 403, 404, 405, 422]);
+
 /**
  * Register a service and handle incoming work requests.
  *
@@ -155,7 +159,9 @@ export function reportRequestEvent(client, projectId, requestId, body) {
  * @param {function} onServiceRequest - Handler callback (data, responseHelper)
  * @param {Object} extras - Optional additional metadata
  * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
- *   connection-state transitions: 'registered', 'reconnected', 'disconnected'.
+ *   connection-state transitions: 'registered', 'reconnected', 'disconnected',
+ *   and 'stopped' when the server refuses the channel for a reason retrying
+ *   cannot fix (see PERMANENT_STATUSES), which ends the registration.
  *   Called once per transition, not once per retry.
  * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .isConnected(),
  *   .serviceInfo
@@ -240,11 +246,20 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
     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.
+    // when that is a plain object, and on the helper regardless. A delegating
+    // service (extras `delegation: true`) also gets a short-lived token for the
+    // requesting user (`delegatedToken`) and the projects that token reaches
+    // (`delegatedProjects`, the request's own first), as the Python client
+    // hands them over.
     const requesterId = payload.requesterId || null;
+    const extra = {
+      ...(requesterId ? { requesterId } : {}),
+      ...(payload.delegatedToken ? { delegatedToken: payload.delegatedToken } : {}),
+      ...(payload.delegatedProjects ? { delegatedProjects: payload.delegatedProjects } : {}),
+    };
     const data =
-      requesterId && payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
-        ? { ...payload.data, requesterId }
+      Object.keys(extra).length && payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+        ? { ...payload.data, ...extra }
         : payload.data;
 
     const scope = createCancelScope(() => cancelled.get(requestId) === true);
@@ -331,10 +346,23 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
   // 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.
+  //
+  // A channel the server REFUSED for a reason retrying cannot fix (the token
+  // was revoked, the user lost write access, the project is gone) ends the
+  // registration instead: the server closes a channel whose opener lost the
+  // right to it, and reopening it every few seconds forever would only hide
+  // that from the operator.
   reconnectTimer = setInterval(() => {
     if (!isRunning || !connection) return;
     if (connection.readyState === 1) { noteConnected(); return; }
     if (connection.readyState === 2) { // CLOSED (dropped or failed)
+      const status = connection.error?.status;
+      if (PERMANENT_STATUSES.has(status)) {
+        noteDisconnected();
+        serviceRegistration.stop();
+        report('stopped', `HTTP ${status}`);
+        return;
+      }
       noteDisconnected();
       try { connection = openChannel(); } catch (_) { /* retry next tick */ }
     }
@@ -371,6 +399,9 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @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
+ * @param {string[]} [opts.projectIds] - Other projects the request is about, beside
+ *   `projectId`. A delegating service's token is scoped to `projectId` and to those of
+ *   these the requester can read, and reaches nothing else
  * @returns {Promise<any>} The service's result
  */
 export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress, signal, opts = {}) {
@@ -384,7 +415,10 @@ 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)}` : '';
+  const query = new URLSearchParams();
+  if (opts.requestId) query.set('request-id', opts.requestId);
+  if (opts.projectIds?.length) query.set('project-ids', opts.projectIds.join(','));
+  const qs = String(query) ? `?${query}` : '';
   return streamServiceRequest(
     client,
     {
@@ -487,13 +521,8 @@ export function createCancelScope(isCancelled) {
  * 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.
  *
- * Goes over the wire even while a batch is open on the client. A DELETE, but
- * not a write: it signals a running service out of band and changes no project
- * data. The Stop button lives in the app's chrome, on the same client an
- * import or a bulk edit is batching on, and a stop that waits for that batch to
- * submit has stopped nothing (and if the batch aborts, it never arrives at
- * all), while the queued DELETE shifts every result index the batch's caller
- * reads back.
+ * outOfBand: a DELETE, but not a write. It signals a running service and
+ * changes no project data (see the note at the top of http.js).
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
@@ -504,7 +533,7 @@ export function cancelServiceRequest(client, projectId, requestId) {
   return client._request(
     'DELETE',
     `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`,
-    { bypassBatch: true },
+    { outOfBand: true },
   );
 }
 

package/src/sse.js

@@ -12,6 +12,11 @@ import { transformResponse } from './transforms.js';
 // cadences, so a healthy idle stream never trips it.
 export const SSE_IDLE_TIMEOUT_MS = 60000;
 
+// The last failure warned about per stream URL, so a stream retried every few
+// seconds through an outage warns once per distinct failure rather than once
+// per attempt. Cleared when the stream opens. Mirrors the Python client.
+const lastWarning = new Map();
+
 /**
  * Project a parsed SSE `data:` object onto what a listener callback sees.
  *
@@ -42,7 +47,10 @@ export function eventPayload(eventType, parsed) {
  *   /listen bus; service request channels pass their own. Only /listen emits
  *   `heartbeat` events needing a POST confirmation — other streams keep
  *   themselves alive with ignored SSE comments.
- * @returns {Object} SSE connection with .close(), .getStats(), .readyState
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
  */
 export function createSSEConnection(client, projectId, onEvent, path) {
   const streamPath = path || `/api/v1/projects/${projectId}/listen`;
@@ -88,6 +96,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
 
   const sseConnection = {
     readyState: 0, // CONNECTING
+    error: null,
     close: () => {
       if (!isClosed) {
         isClosed = true;
@@ -130,11 +139,14 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           // takes over.
           console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
         }
-        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        const refused = new Error(`HTTP ${response.status} ${response.statusText}`);
+        refused.status = response.status;
+        throw refused;
       }
 
       isConnected = true;
       sseConnection.readyState = 1; // OPEN
+      lastWarning.delete(url);
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -188,9 +200,23 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           }
         }
       }
+      if (!isClosed) {
+        // The server ended the stream, for instance because the opener lost
+        // the right to it. Say so, so a caller can tell it from a close of
+        // its own.
+        sseConnection.error = Object.assign(new Error('The server closed the stream'), {
+          name: 'StreamClosed',
+        });
+      }
     } catch (error) {
+      if (!isClosed) sseConnection.error = error;
       if (error.name !== 'AbortError') {
-        console.warn('SSE connection error:', error);
+        const url = `${client.baseUrl}${streamPath}`;
+        const message = String(error?.message || error);
+        if (lastWarning.get(url) !== message) {
+          lastWarning.set(url, message);
+          console.warn('SSE connection error:', error);
+        }
       }
     } finally {
       clearIdleTimer();

package/src/transforms.js

@@ -27,6 +27,12 @@ export function transformKeyFromCamel(key) {
 // usual case conversion.
 const OPAQUE_KEYS = new Set(['metadata', 'config', 'bindings']);
 
+// A request's `metadata` may also be a list of metadata ops (a bulk update
+// entry), whose values are user data too, so it passes through verbatim.
+const isOpaque = (key, value) =>
+  typeof value === 'object' && value !== null &&
+  (Array.isArray(value) ? key === 'metadata' : OPAQUE_KEYS.has(key));
+
 /**
  * Recursively transform request object keys from camelCase to kebab-case.
  * Preserves `metadata` and `config` contents without transformation.
@@ -39,7 +45,7 @@ export function transformRequest(obj) {
   const transformed = {};
   for (const [key, value] of Object.entries(obj)) {
     const newKey = transformKeyFromCamel(key);
-    if (OPAQUE_KEYS.has(key) && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (isOpaque(key, value)) {
       transformed[newKey] = value;
     } else {
       transformed[newKey] = transformRequest(value);