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

package/index.d.ts

@@ -15,7 +15,7 @@ interface ServiceParam {
   /** Key the value is sent under in the request payload. */
   key: string;
   label: string;
-  type: "string" | "number" | "boolean" | "enum" | "multiselect";
+  type: "string" | "number" | "boolean" | "enum" | "multiselect" | "field";
   description?: string;
   default?: any;
   required?: boolean;
@@ -30,6 +30,11 @@ interface ServiceParam {
   /** `string` only. */
   placeholder?: string;
   multiline?: boolean;
+  /**
+   * `field` only: the scope of the project's annotation fields the value names
+   * one of. A `field` value is a string everywhere else.
+   */
+  scope?: "Sentence" | "Word" | "Morpheme";
 }
 
 /** A service's standardized self-description (lives in `extras`). */
@@ -201,6 +206,7 @@ interface RelationsBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
 }
 
 interface SpanLayersBundle {
@@ -250,15 +256,12 @@ interface SpansBundle {
   update(spanId: string, value: any, auditMessage?: string): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   setMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(spanId: string, auditMessage?: string): Promise<any>;
   patchMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
 }
 
-interface BatchBundle {
-  submit(body: any[], auditMessage?: string): Promise<any>;
-}
-
 interface TextsBundle {
   setMetadata(textId: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(textId: string, auditMessage?: string): Promise<any>;
@@ -320,12 +323,26 @@ interface UserDataEntry {
   value?: any;
 }
 
+interface UserDataOptions {
+  prefix?: string;
+  pattern?: string;
+  includeValues?: boolean;
+}
+
 /** Private per-user key/value storage (owner or admin only; not audited). */
 interface UserDataBundle {
   list(
     userId: string,
-    opts?: { prefix?: string; includeValues?: boolean },
+    opts?: UserDataOptions & { pageSize?: number },
   ): Promise<UserDataEntry[]>;
+  listPage(
+    userId: string,
+    opts?: UserDataOptions & { limit?: number; cursor?: string },
+  ): Promise<Page<UserDataEntry>>;
+  iterPages(
+    userId: string,
+    opts?: UserDataOptions & { pageSize?: number },
+  ): AsyncGenerator<UserDataEntry[]>;
   get(userId: string, key: string): Promise<UserDataEntry & { value: any }>;
   put(
     userId: string,
@@ -345,6 +362,60 @@ interface CommentFilters {
 type CommentableType =
   "document" | "text" | "token" | "span" | "relation" | "vocab-item";
 
+/**
+ * One entry in a project's annotation manual: a short Markdown document
+ * stating a convention the project follows. Read by the people on the
+ * project, and by the assistant before it proposes anything.
+ */
+interface Guideline {
+  id: string;
+  projectId: string;
+  /** The handle the assistant asks for a guideline by. Not required to be unique. */
+  title: string;
+  /** The Markdown text. Present on a single read and on a list made with `includeBodies`. */
+  body?: string;
+  /** The body's length in characters. Present on a list made WITHOUT `includeBodies`. */
+  bodyChars?: number;
+  /** Whether the assistant is given this one in full on every turn. */
+  pinned: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface GuidelinesBundle {
+  create(
+    projectId: string,
+    title: string,
+    opts?: { body?: string; pinned?: boolean },
+    auditMessage?: string,
+  ): Promise<{ id: string }>;
+  get(id: string): Promise<Guideline>;
+  update(
+    id: string,
+    changes?: {
+      title?: string;
+      body?: string;
+      pinned?: boolean;
+      /** Write only if this is still the stored updatedAt; 409 otherwise. */
+      expectedUpdatedAt?: string;
+    },
+    auditMessage?: string,
+  ): Promise<Guideline>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  list(
+    projectId: string,
+    opts?: { includeBodies?: boolean },
+  ): Promise<Guideline[]>;
+  listPage(
+    projectId: string,
+    opts?: { includeBodies?: boolean; limit?: number; cursor?: string },
+  ): Promise<Page<Guideline>>;
+  iterPages(
+    projectId: string,
+    opts?: { includeBodies?: boolean; pageSize?: number },
+  ): AsyncGenerator<Guideline[]>;
+}
+
 interface Comment {
   id: string;
   /** The owning project, or null for a comment on a vocabulary entry. */
@@ -568,6 +639,14 @@ interface AdminBundle {
     userId?: string;
   }): Promise<{ result: string }>;
   logs(opts?: {
+    limit?: number;
+    q?: string;
+    level?: string;
+    status?: string;
+    user?: string;
+    method?: string;
+  }): Promise<LiveLog>;
+  logFile(opts?: {
     lines?: number;
   }): Promise<{ file: string | null; lines: string[]; error?: string }>;
   userData(opts?: AdminUserDataOptions): Promise<AdminUserDataEntry[]>;
@@ -576,6 +655,71 @@ interface AdminBundle {
   ): Promise<Page<AdminUserDataEntry>>;
 }
 
+/** One HTTP request as the log buffer holds it. */
+interface LoggedRequest {
+  /** Epoch milliseconds. */
+  ts: number;
+  method: string;
+  path: string;
+  /** Query string with sensitive values replaced, or null. */
+  query: string | null;
+  /** Null when the handler threw before producing one. */
+  status: number | null;
+  ms: number;
+  /** Null for a request nobody was authenticated for. */
+  user: string | null;
+  ip: string | null;
+  /** Set when a named API token signed the request. */
+  token: string | null;
+  /** Exception class, when the handler threw. */
+  error: string | null;
+}
+
+/** One log event that was not a request. */
+interface LoggedEvent {
+  ts: number;
+  level: string;
+  ns: string;
+  message: string;
+  trace?: string;
+}
+
+/**
+ * The live log. Requests and events are buffered separately, so a burst of
+ * requests cannot evict an error.
+ */
+interface LiveLog {
+  requests: {
+    entries: LoggedRequest[];
+    /** How many passed the filters, which may exceed what `entries` holds. */
+    matched: number;
+    /** How many are buffered in total. */
+    held: number;
+    capacity: number;
+    stats: {
+      count: number;
+      failures: number;
+      serverErrors: number;
+      p50: number | null;
+      p95: number | null;
+      max: number | null;
+      perMinute: number | null;
+      oldest: number | null;
+      newest: number | null;
+    };
+  };
+  events: {
+    entries: LoggedEvent[];
+    matched: number;
+    held: number;
+    capacity: number;
+    /** Counts per level of what the search matched, before the level filter. */
+    byLevel: Record<string, number>;
+  };
+  /** Absolute path of the configured log file, or null when logging to stdout. */
+  file: string | null;
+}
+
 /** Narrowings for the cross-account private-data listing. */
 interface AdminUserDataOptions {
   /** Only keys starting with this literal head. */
@@ -692,10 +836,39 @@ interface TokenLayersBundle {
   ): Promise<any>;
 }
 
+/** Handle passed to a `documents.locked()` block. */
+export declare class DocumentLock {
+  readonly documentId: string;
+  /** The DocumentLockLost if the lock lapsed, else null. */
+  readonly lost: DocumentLockLost | null;
+  /** Throw if the lock lapsed; call it between steps that have not written. */
+  raiseIfLost(): void;
+}
+
+/** The lock a `documents.locked()` block was holding is no longer held. */
+export declare class DocumentLockLost extends Error {
+  readonly name: "DocumentLockLost";
+  readonly documentId: string;
+  readonly cause?: unknown;
+}
+
+/** The server's default document-lock window, in ms. */
+export const DOCUMENT_LOCK_TTL_MS: 60000;
+
 interface DocumentsBundle {
   checkLock(documentId: string, asOf?: string): Promise<any>;
   acquireLock(documentId: string, auditMessage?: string): Promise<any>;
   releaseLock(documentId: string, auditMessage?: string): Promise<any>;
+  /**
+   * Hold the document's lock for the length of `fn`, renewing it while `fn`
+   * runs and releasing it on the way out. Rejects with a 423 if another user
+   * holds it, and with DocumentLockLost if a renewal fails.
+   */
+  locked<T>(
+    documentId: string,
+    fn: (lock: DocumentLock) => T | Promise<T>,
+    options?: { keepAlive?: boolean },
+  ): Promise<T>;
   getMedia(documentId: string): Promise<ArrayBuffer>;
   uploadMedia(
     documentId: string,
@@ -894,6 +1067,7 @@ interface VocabItemsBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   get(id: string, asOf?: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
   update(id: string, form: string, auditMessage?: string): Promise<any>;
@@ -953,6 +1127,7 @@ interface TokensBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   split(tokenId: string, position: number, auditMessage?: string): Promise<any>;
   merge(
     tokenId: string,
@@ -997,6 +1172,21 @@ export interface OperationGroupsBundle {
   update(id: string, message: string | null): Promise<any>;
 }
 
+/**
+ * A batch: the client's bundles, on which every write of project data queues
+ * until `submit()`. See `PlaidClient.batch()`.
+ */
+export interface PlaidBatch extends PlaidClient {
+  /** The client this batch was opened on. */
+  readonly client: PlaidClient;
+  /** The queued operations, in order. */
+  readonly operations: Array<{ path: string; method: string; body?: any }>;
+  /** Send the queued operations as one atomic request; one result per operation. */
+  submit(): Promise<any[]>;
+  /** Drop the queued operations without sending them. */
+  abort(): void;
+}
+
 export declare class PlaidClient {
   constructor(baseUrl: string, token: string, options?: PlaidClientOptions);
   static login(
@@ -1025,13 +1215,20 @@ export declare class PlaidClient {
   /** Fired once on HTTP 401 (see PlaidClientOptions.onAuthError). */
   onAuthError: ((error: Error) => void) | null;
 
-  // Batch control methods
-  beginBatch(): void;
-  submitBatch(): Promise<any[]>;
-  abortBatch(): void;
-  isBatchMode(): boolean;
-  /** Run `fn` with a batch open, then submit atomically (or abort if `fn` throws). Resolves to the results array. */
-  batched(fn: () => void | Promise<void>): Promise<any[]>;
+  // Batches.
+  //
+  // A batch is a view of the client with the same bundles. A write of project
+  // data made on the batch queues; a call made on the client itself always
+  // goes over the wire, whatever batches are open, so a write by code that
+  // knows nothing about a batch can never land inside it. A read, or a signal
+  // that carries no project data (stopping a service request, a service
+  // reporting its progress, taking and dropping a document lock, the admin
+  // actions on the server itself), goes over the wire even when made on the
+  // batch.
+  /** Open a batch. Queue writes on it, then `submit()` them as one atomic request, or `abort()`. Not nestable. */
+  batch(): PlaidBatch;
+  /** Run `fn` with a batch, then submit atomically (or abort if `fn` throws). Resolves to the results array, one entry per queued write. */
+  batched(fn: (batch: PlaidBatch) => void | Promise<void>): Promise<any[]>;
 
   // Strict mode methods
   enterStrictMode(documentId: string): void;
@@ -1057,7 +1254,6 @@ export declare class PlaidClient {
   relations: RelationsBundle;
   spanLayers: SpanLayersBundle;
   spans: SpansBundle;
-  batch: BatchBundle;
   texts: TextsBundle;
   users: UsersBundle;
   apiTokens: ApiTokensBundle;
@@ -1067,6 +1263,7 @@ export declare class PlaidClient {
   admin: AdminBundle;
   audit: AuditBundle;
   comments: CommentsBundle;
+  guidelines: GuidelinesBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
   messages: MessagesBundle;
@@ -1136,6 +1333,7 @@ export const TASKS: {
   readonly TRANSLATE: "translate";
   readonly ASSIST: "assist";
   readonly DETECT_SPEECH: "detect-speech";
+  readonly COMPARE: "compare";
 };
 /** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
 export function servesTask(service: DiscoveredService, task: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.13",
+  "version": "0.2.0-alpha.16",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/documentLock.js

@@ -0,0 +1,299 @@
+/**
+ * Keeping a document lock alive for as long as a `locked()` block runs.
+ *
+ * plaid-core expires a document lock about a minute after it was taken, and the
+ * holder's own writes are what renew it (`plaid.sql.operation` calls
+ * `refresh-locks!` on every write it accepts). That is the right rule for an
+ * editor, which writes as the person types. It is the wrong one for a service:
+ * a parser loads a model, reads the document, spends minutes in inference and
+ * only then writes, so for most of its run it holds nothing. The lock lapses in
+ * silence, a person's edit lands between the read the work was planned from and
+ * the write about to go out, and the write clobbers it.
+ *
+ * A `locked()` block therefore renews on a timer of its own. The renewal is a
+ * plain acquire: the server refreshes a lock whose holder asks for it again.
+ *
+ * The beat is unconditional rather than "only when no write has gone out
+ * recently". The request layer knows the method of a call but not which
+ * document it touched, so a write to some other document would count as a
+ * renewal here and would not be one. Two extra requests a minute is the whole
+ * cost.
+ *
+ * A renewal that fails means the block is no longer holding what it asked for,
+ * so it stops the run: the loss is recorded on the client and every later write
+ * throws `DocumentLockLost`. The guard sits in the request layer because the
+ * callers are services, and a check they have to remember to call is a check
+ * that is missing somewhere.
+ */
+
+/**
+ * How long plaid-core holds a document lock before it expires, in ms.
+ * `plaid.server.locks/default-lock-expiration-ms`. An operator can change it
+ * with `:plaid.server.locks/config :expiration-ms`, and a server publishes what
+ * it enforces as `lockExpirationMs` in `GET /info`. This is the last resort:
+ * what a live lock is renewed against is the `expiresAt` on the acquire
+ * response, which names the moment rather than the window.
+ */
+export const DOCUMENT_LOCK_TTL_MS = 60000;
+
+// Widest lock lifetime we will believe from a server response. Past this the
+// number is a clock skew between this machine and the server rather than a
+// configured window, and the documented default is the better guess.
+const MAX_BELIEVABLE_TTL_MS = 3600000;
+
+/**
+ * The lock a `documents.locked()` block was holding is no longer held.
+ *
+ * Thrown by the keep-alive when it cannot renew the lock, and then by the
+ * request layer on every write this client attempts, so work that has been
+ * running for minutes stops rather than writing over an edit that may have
+ * landed while the lock was gone.
+ */
+export class DocumentLockLost extends Error {
+  constructor(message, documentId, cause) {
+    super(message);
+    this.name = "DocumentLockLost";
+    this.documentId = documentId;
+    this.cause = cause;
+  }
+}
+
+/**
+ * How long a freshly taken lock lasts, from the server's own answer.
+ *
+ * `expiresAt` is the epoch-millisecond stamp the lock endpoints return.
+ * Comparing it against this machine's clock is the only way to learn a window
+ * an operator has retuned, and it is also the one place a clock skew can get
+ * in, so an answer outside a believable band falls back to the documented
+ * default rather than to a beat that never fires or fires constantly.
+ *
+ * @param {number|undefined} expiresAt
+ * @param {number} nowMs
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function lockTtlMs(
+  expiresAt,
+  nowMs,
+  fallback = DOCUMENT_LOCK_TTL_MS,
+) {
+  if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
+    const ttl = expiresAt - nowMs;
+    if (ttl > 0 && ttl <= MAX_BELIEVABLE_TTL_MS) return ttl;
+  }
+  return fallback;
+}
+
+/**
+ * Renews one document's lock until the block holding it exits.
+ *
+ * `refresh` is called with the document id and must reject on failure.
+ * `onLost` is called once, with the `DocumentLockLost`, when the lock can no
+ * longer be assumed.
+ *
+ * `clock` and `sleep` exist so the whole policy can be run on a fake clock:
+ * `sleep(delayMs)` resolves to true once the block has exited.
+ */
+export class LockKeeper {
+  constructor(
+    refresh,
+    documentId,
+    ttlMs,
+    { onLost = null, clock = Date.now, sleep = null } = {},
+  ) {
+    this._refresh = refresh;
+    this._documentId = documentId;
+    // A window under two seconds leaves no room for a retry; treat it as a
+    // misconfiguration and beat at the documented rate instead.
+    this._ttlMs = ttlMs >= 2000 ? ttlMs : DOCUMENT_LOCK_TTL_MS;
+    this._onLost = onLost;
+    this._clock = clock;
+    this._sleep = sleep || ((ms) => this._defaultSleep(ms));
+    this._stopped = false;
+    this._wake = null;
+    this._running = null;
+    /** The `DocumentLockLost` this keeper raised, or null. */
+    this.lost = null;
+  }
+
+  /**
+   * Time between renewals: half the window, so a renewal that fails has a
+   * second chance before the lock it is renewing expires.
+   */
+  get intervalMs() {
+    return Math.max(1000, this._ttlMs / 2);
+  }
+
+  /**
+   * Time before retrying a renewal that failed. A blip should not end a run
+   * that the server still considers the holder of.
+   */
+  get retryMs() {
+    return Math.max(500, this._ttlMs / 10);
+  }
+
+  _defaultSleep(ms) {
+    if (this._stopped) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._wake = null;
+        resolve(this._stopped);
+      }, ms);
+      // Never hold a Node process open on the beat alone.
+      if (timer && typeof timer.unref === "function") timer.unref();
+      this._wake = () => {
+        clearTimeout(timer);
+        this._wake = null;
+        resolve(true);
+      };
+    });
+  }
+
+  /** The beat. Resolves when the block exits or the lock is lost. */
+  async run() {
+    let deadline = this._clock() + this._ttlMs;
+    let delay = this.intervalMs;
+    while (!(await this._sleep(delay))) {
+      try {
+        await this._refresh(this._documentId);
+      } catch (error) {
+        // 423 is definitive: somebody else holds the document now, so ours had
+        // already expired. Anything else may be a blip, and is only fatal once
+        // the lock we are renewing has actually run out.
+        if (error?.status === 423 || this._clock() >= deadline) {
+          this._fail(error);
+          return;
+        }
+        delay = this.retryMs;
+        continue;
+      }
+      deadline = this._clock() + this._ttlMs;
+      delay = this.intervalMs;
+    }
+  }
+
+  start() {
+    this._running = this.run();
+    // Nothing awaits the beat: a failure inside it is reported through onLost,
+    // not through this promise.
+    this._running.catch(() => {});
+    return this._running;
+  }
+
+  stop() {
+    this._stopped = true;
+    if (this._wake) this._wake();
+  }
+
+  _fail(error) {
+    this.lost = new DocumentLockLost(
+      `The lock on document ${this._documentId} lapsed: it could not be renewed.`,
+      this._documentId,
+      error,
+    );
+    if (this._onLost) this._onLost(this.lost);
+  }
+}
+
+/**
+ * What a `client.documents.locked(id, (lock) => ...)` block gets.
+ *
+ * The block does not have to consult it: a lost lock stops the next write on
+ * its own. Read `lock.lost` (or call `lock.raiseIfLost()`) to give up earlier,
+ * between steps of work that has not written anything yet.
+ */
+export class DocumentLock {
+  constructor(documentId, keeper) {
+    this.documentId = documentId;
+    this._keeper = keeper;
+  }
+
+  /** The `DocumentLockLost` if the lock lapsed, else null. */
+  get lost() {
+    return this._keeper ? this._keeper.lost : null;
+  }
+
+  raiseIfLost() {
+    if (this.lost) throw this.lost;
+  }
+}
+
+/**
+ * Hold `documentId`'s server-enforced lock for the length of `fn`.
+ * `client.documents.locked` is the entry point; see its doc comment.
+ *
+ * @param {object} client
+ * @param {string} documentId
+ * @param {(lock: DocumentLock) => any} fn
+ * @param {{ keepAlive?: boolean }} [options]
+ */
+export async function withDocumentLock(
+  client,
+  documentId,
+  fn,
+  { keepAlive = true } = {},
+) {
+  let info;
+  try {
+    info = await client.documents.acquireLock(documentId);
+  } catch (error) {
+    if (error?.status === 423) {
+      // The error body is raw JSON off the wire, so it is still kebab-cased.
+      const body = error.responseData || {};
+      const holder = body.userId || body["user-id"] || "another user";
+      const readable = new Error(
+        `Document ${documentId} is locked by ${holder} (likely being edited); try again once they're done.`,
+      );
+      readable.status = 423;
+      readable.statusText = error.statusText;
+      readable.url = error.url;
+      readable.method = error.method;
+      readable.responseData = error.responseData;
+      readable.cause = error;
+      throw readable;
+    }
+    throw error;
+  }
+
+  let keeper = null;
+  if (keepAlive) {
+    const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
+    client.documentLockLost = null;
+    keeper = new LockKeeper(
+      (id) => client.documents.acquireLock(id),
+      documentId,
+      ttlMs,
+      {
+        onLost: (lost) => {
+          client.documentLockLost = lost;
+        },
+      },
+    );
+    keeper.start();
+  }
+
+  let result;
+  let threw = false;
+  try {
+    result = await fn(new DocumentLock(documentId, keeper));
+  } catch (error) {
+    threw = true;
+    throw error;
+  } finally {
+    if (keeper) keeper.stop();
+    const lost = keeper ? keeper.lost : null;
+    client.documentLockLost = null;
+    // Best-effort release: the server TTL reclaims a stranded lock, and we must
+    // not let a release failure mask the real error from the body.
+    try {
+      await client.documents.releaseLock(documentId);
+    } catch {
+      /* the lock expires on its own */
+    }
+    // A block that ran to the end without the lock it asked for did not do what
+    // it says it did. Only throw when nothing else is already propagating, so
+    // the real failure is never masked.
+    if (lost && !threw) throw lost;
+  }
+  return result;
+}