@procedures/client 0.7.0 → 0.8.1

package/src/browser.ts

@@ -76,8 +76,9 @@ export {
 export { Server } from "./server/server.js";
 export type { ServerOptions } from "./server/server.js";
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream, tokenMatches } from "./server/procedure-server.js";
-// The credentials of a network request (roadmap R18)
-export { credentialsOf, bearerOf, withoutSecretHeaders } from "./server/request-auth.js";
+// The credentials of a network request (roadmap R18), and the parts that a request hook reads (CLI-2a)
+export { credentialsOf, bearerOf, withoutSecretHeaders, cookiesOf, requestCredentials } from "./server/request-auth.js";
+export type { RequestCredentialsOptions } from "./server/request-auth.js";
 // The procedures of a host: host.health, host.info, host.metrics (roadmap R19)
 export { hostProcedures } from "./server/host-procedures.js";
 export type { HostSource } from "./server/host-procedures.js";
@@ -93,6 +94,9 @@ export type {
   RequestHandler,
   Credentials,
   Principal,
+  PrincipalOf,
+  RequestIdentity,
+  AmbientCredentials,
   ServerHandler,
   ServerMiddleware,
   ServerContext,
@@ -117,6 +121,24 @@ export {
   pathToKey,
   keyToPath,
   createCollectionProcedures,
+  // The change events of the collection writes (roadmap CLI-15)
+  collectionChangeTopic,
+  collectionTopicReads,
+  // The query language of the collection storages (roadmap CLI-14, CLI-34)
+  DEFAULT_FIND_LIMIT,
+  DEFAULT_QUERY_OPERATORS,
+  DEFAULT_QUERY_POLICY,
+  QUERY_OPERATORS,
+  applyPatch,
+  compareStorageValues,
+  compileSelector,
+  isPatchOperations,
+  matchesSelector,
+  mergePatch,
+  patchProblems,
+  queryEntries,
+  queryOptionsProblems,
+  selectorProblems,
   // Manual registration helpers
   registerModule,
   registerProcedures,
@@ -128,6 +150,7 @@ export {
   registerModules,
   createRegistry,
   registerClientProcedures,
+  callerOf,
   // Procedure reference system (procedure-as-data)
   PROCEDURE_SYMBOL,
   PROCEDURE_JSON_KEY,
@@ -213,6 +236,7 @@ export {
 
 export type {
   Effects,
+  FsRootRules,
   PermittedEffects,
   Register,
   ClearanceOf,
@@ -233,8 +257,29 @@ export type {
   CollectionStorage,
   StorageChanges,
   StorageMetadata,
+  StorageWriteOptions,
+  StorageSetChange,
+  StorageDeleteChange,
+  StorageClearChange,
+  StorageChangeEvent,
+  StorageChangeBatch,
+  StorageObserver,
+  StorageFieldOperators,
+  StoragePatch,
+  StorageQueryOptions,
+  StorageSelector,
+  StorageSort,
+  StorageSortDirection,
+  StoragePatchOperations,
+  StorageQueryOperator,
+  StorageQueryPolicy,
+  CollectionProceduresOptions,
+  CollectionChangeEventsOptions,
+  CollectionChangeEvent,
   ProcedureModule,
   ModuleInput,
+  Caller,
+  CallerOptions,
   RegistrationOptions,
   ProcedureRegistryLike,
   ProcedureDefinition,
@@ -331,6 +376,42 @@ export { TIMEOUT_METADATA_KEY, DEADLINE_METADATA_KEY } from "./client/deadline.j
 // Typed durations: each public option that is a time takes a Duration (roadmap R11)
 export { ms, seconds, minutes, hours, toMs, optionalMs, isDuration } from "./duration.js";
 export type { Duration, TimeUnit } from "./duration.js";
+// What the face of a call offers the procedure: the questions to the person at the caller, the
+// progress, and the text from outside the host (CLI-10, CLI-12)
+export {
+  createElicit,
+  elicitWithPolicy,
+  operatorAnswer,
+  elicitInput,
+  elicitConfirmation,
+  NO_ELICITATION_REASON,
+} from "./procedures/elicit.js";
+export type {
+  Elicit,
+  ElicitRequest,
+  ElicitFormRequest,
+  ElicitUrlRequest,
+  ElicitMode,
+  ElicitAction,
+  ElicitResult,
+  ElicitOptions,
+  ElicitField,
+  ElicitFieldBase,
+  ElicitTextField,
+  ElicitNumberField,
+  ElicitBooleanField,
+  ElicitChoiceField,
+  ElicitChoicesField,
+  ElicitValue,
+  ElicitationPolicy,
+  ConfirmationOptions,
+  ConfirmationResult,
+} from "./procedures/elicit.js";
+export type { ProgressUpdate, ReportProgress } from "./procedures/progress.js";
+export { toolHintsOf, toolHintOverrideOf, toolHintOverrideRefusal } from "./procedures/hints.js";
+export type { ToolHintOverride } from "./procedures/hints.js";
+export { untrustedText, untrustedFieldsOf, untrustedTextsOf } from "./procedures/untrusted.js";
+export type { UntrustedText, UntrustedSource, UntrustedValue } from "./procedures/untrusted.js";
 // One manifest type (roadmap R17)
 export { MANIFEST_FORMAT, describeProcedure as describeProcedureEntry, describeRegistry, exposedProcedures, hashOf } from "./procedures/manifest.js";
 export type { ProcedureEntry, ProcedureManifest, CliDescription, DescribeOptions, DescribeRegistryOptions } from "./procedures/manifest.js";
@@ -411,6 +492,7 @@ export type {
   TypedEventBus,
   EventHandler,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
   ChannelMap,
 } from "./events/index.js";
@@ -424,6 +506,7 @@ export type {
   RemoteEvent,
   RemoteEventHandler,
   RemoteEventsOptions,
+  ResubscribeBackoff,
   SubscribeOptions,
   Subscription,
 } from "./events/index.js";

package/src/client/client.ts

@@ -30,6 +30,7 @@ import type {
   Method,
   Metadata,
   Message,
+  ResponseItem,
   ClientMiddleware,
   ClientContext,
   ClientRunner,
@@ -56,8 +57,19 @@ import { RouteResolver, type ResolvedRoute, type RouteResolutionResult } from ".
 import { BatchExecutor, type ExecutionContext } from "./batch-executor.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { EventBus } from "../events/types.js";
+import {
+  remoteEvents,
+  subscribeRemote,
+  type EventTransport,
+  type RemoteEvent,
+  type RemoteEventHandler,
+  type RemoteEventsOptions,
+  type SubscribeOptions,
+  type Subscription,
+} from "../events/remote.js";
 import { narrowCapability } from "../procedures/capability.js";
-import { TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { DEADLINE_METADATA_KEY, TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { ms } from "../duration.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -169,6 +181,12 @@ function callerOf(options: ExecOptions): CallerContext {
   return caller;
 }
 
+/**
+ * The timeouts of a subscription: none. The timeout middleware takes 0 as "no timeout", so the
+ * timeouts of the client do not end a subscription, which has no end (roadmap CLI-15).
+ */
+const NO_SUBSCRIPTION_TIMEOUT = Object.freeze({ overall: ms(0), perAttempt: ms(0) });
+
 /**
  * Generate a unique message ID.
  */
@@ -221,6 +239,8 @@ export class Client<TContext = {}> {
   private readonly throwOnError: boolean;
   /** The bus of the local procedures. Undefined: the global bus. */
   private bus: EventBus | undefined;
+  /** The transport of the subscriptions through the middleware, made at the first subscription */
+  private subscriptionTransport: EventTransport | undefined;
   /** The interceptors of the local invocations (roadmap 1.2) */
   private interceptors: readonly Interceptor[] = [];
   /** The capability of the local invocations (CAPABILITIES-2026-10). Undefined: no limits. */
@@ -779,6 +799,68 @@ export class Client<TContext = {}> {
     }
   }
 
+  /**
+   * This method subscribes to topics of the event bus of the server (`documentation/EVENTS.md`).
+   * The call of `events.subscribe` goes through the middleware and the context of this client, as
+   * `stream()` does. Thus a token of the auth middleware goes with it. The subscriber resubscribes
+   * after a failure that a retry can repair, and the subscribers of the same topics share one call.
+   *
+   * A subscription has no deadline: the timeouts of the client (its timeout middleware, the
+   * `timeout` of its context and a `procedure-timeout` of its metadata) do not apply to it. For a
+   * deadline, give it in the metadata of the options, for example
+   * `{ metadata: { timeout: { overall: minutes(5) } } }`.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param handler - The handler of each event. A promise that it gives holds the next event.
+   * @param options - `onSubscribed`, `onError`, a signal, the metadata of the call, the resubscribe rules
+   * @returns The unsubscribe function, with the `ready` promise of the first confirmation
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.subscribe("collections.users", (event) => console.log(event));
+   * await unsubscribe.ready;
+   * unsubscribe();
+   * ```
+   */
+  subscribe<T = unknown>(topics: string | readonly string[], handler: RemoteEventHandler<T>, options: SubscribeOptions = {}): Subscription {
+    return subscribeRemote<T>(this.eventTransport(), topics, handler, options);
+  }
+
+  /**
+   * This method gives the events of topics of the event bus of the server as an async iterator,
+   * through the middleware of this client. A `break` or the signal ends the subscription. As for
+   * `subscribe()`, the timeouts of the client do not apply: the metadata of the options can give one.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param options - A signal, `onSubscribed`, the metadata of the call, the resubscribe rules
+   */
+  events<T = unknown>(topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
+    return remoteEvents<T>(this.eventTransport(), topics, options);
+  }
+
+  /**
+   * The transport of the subscriptions of this client: each call goes through the middleware, with
+   * the context of the client in its metadata. The subscriptions of one client share it, so they
+   * share their calls. The timeouts and the deadline of the client stay out: only the metadata of
+   * the subscription can give them.
+   */
+  private eventTransport(): EventTransport {
+    if (!this.subscriptionTransport) {
+      const send = <TReq, TRes>(message: Message<TReq>): AsyncIterable<ResponseItem<TRes>> => {
+        const metadata: Metadata = { ...this.defaultMetadata, ...(this.getEffectiveContext() as object) };
+        delete metadata["timeout"];
+        delete metadata[TIMEOUT_METADATA_KEY];
+        delete metadata[DEADLINE_METADATA_KEY];
+        metadata["timeout"] = NO_SUBSCRIPTION_TIMEOUT as unknown as NonNullable<Metadata["timeout"]>;
+        Object.assign(metadata, message.metadata);
+        absorbTimeout(metadata);
+        return this.composeMiddleware<TReq, TRes>()({ message: { ...message, metadata } });
+      };
+      this.subscriptionTransport = { send };
+    }
+    return this.subscriptionTransport;
+  }
+
   /**
    * Compose middleware chain using universal middleware composition.
    *

package/src/client/errors/registry.ts

@@ -84,6 +84,7 @@ const PROTOCOL_CATEGORIES: Readonly<Record<ProtocolErrorCode, ErrorCategory>> =
   CONNECTION_CLOSED: ErrorCategory.NETWORK,
   CONNECTION_NOT_FOUND: ErrorCategory.CLIENT,
   TOPIC_NOT_FOUND: ErrorCategory.CLIENT,
+  TOPIC_CLEARED: ErrorCategory.CANCELLED,
 };
 
 /**

package/src/client/middleware/retry.ts

@@ -108,6 +108,10 @@ export interface RetryOptions {
   /**
    * Hook called after each retry completes (success or failure).
    *
+   * The middleware calls it when the call ends: after the last item, or when the reader stops
+   * reading. A `Client` with `throwOnError` stops at the error item. Before, the hook then did
+   * not run, so it did not hear of a failure. A thrown error and an abort do not call it.
+   *
    * @param success - Whether the retry succeeded
    * @param attempt - Attempt number that just completed
    */
@@ -249,99 +253,106 @@ export function createRetryMiddleware(options: RetryOptions = {}): TypedClientMi
       const idempotencyKey = idempotencyKeyOf(context.message.metadata) ?? newIdempotencyKey();
       context.message.metadata[IDEMPOTENCY_KEY_METADATA] = idempotencyKey;
 
-      let attempt = 0;
-      for (;;) {
-        // Update retry metadata with current state
-        context.message.metadata.retry = {
-          ...(typeof given === "object" && given !== null ? (given as object) : {}),
-          attempt,
-          maxAttempts: maxRetries + 1,
-          idempotent,
-        };
-        // Each attempt gets its own request id. The id correlates the frames of one attempt
-        // on the wire: a cancelled attempt can still answer under its id (deep dive TRN-8/9).
-        context.message.id = attempt === 0 ? baseId : `${baseId}.retry${attempt}`;
+      // The outcome of the call for onAfterRetry. The hook runs in `finally`: a reader that stops
+      // at an error item (a Client with throwOnError) closes this generator at its yield. Before,
+      // the hook came after the yield, so it did not hear of a failure.
+      let outcome: { success: boolean; attempt: number } | undefined;
+      try {
+        let attempt = 0;
+        for (;;) {
+          // Update retry metadata with current state
+          context.message.metadata.retry = {
+            ...(typeof given === "object" && given !== null ? (given as object) : {}),
+            attempt,
+            maxAttempts: maxRetries + 1,
+            idempotent,
+          };
+          // Each attempt gets its own request id. The id correlates the frames of one attempt
+          // on the wire: a cancelled attempt can still answer under its id (deep dive TRN-8/9).
+          context.message.id = attempt === 0 ? baseId : `${baseId}.retry${attempt}`;
 
-        // Check if cancelled before attempt
-        if (signal?.aborted) {
-          yield abortedItem<TRes>(context.message.id);
-          return;
-        }
+          // Check if cancelled before attempt
+          if (signal?.aborted) {
+            yield abortedItem<TRes>(context.message.id);
+            return;
+          }
 
-        // The items pass through as they arrive (BUGS-2026-07 M2: before, the middleware
-        // collected the whole stream first). A retry is possible only while no item has
-        // reached the reader: the first item is a retryable error, or the attempt throws
-        // before its first item. After that, a retry would repeat items.
-        let started = false;
-        let lastItem: ResponseItem<TRes> | undefined;
-        let retryItem: ResponseItem<TRes> | undefined;
-        try {
-          for await (const item of next(context)) {
-            if (!started && attempt < maxRetries && shouldRetryItem(item, attempt)) {
-              retryItem = item;
-              break;
+          // The items pass through as they arrive (BUGS-2026-07 M2: before, the middleware
+          // collected the whole stream first). A retry is possible only while no item has
+          // reached the reader: the first item is a retryable error, or the attempt throws
+          // before its first item. After that, a retry would repeat items.
+          let started = false;
+          let lastItem: ResponseItem<TRes> | undefined;
+          let retryItem: ResponseItem<TRes> | undefined;
+          try {
+            for await (const item of next(context)) {
+              if (!started && attempt < maxRetries && shouldRetryItem(item, attempt)) {
+                retryItem = item;
+                break;
+              }
+              started = true;
+              lastItem = item;
+              outcome = { success: item.status.type === "success", attempt };
+              yield item;
             }
-            started = true;
-            lastItem = item;
-            yield item;
-          }
-        } catch (error) {
-          const isAborted = signal?.aborted || (error instanceof Error && error.name === "AbortError");
-          if (started || isAborted || attempt >= maxRetries) {
-            throw error;
+          } catch (error) {
+            // A thrown error does not call onAfterRetry
+            outcome = undefined;
+            const isAborted = signal?.aborted || (error instanceof Error && error.name === "AbortError");
+            if (started || isAborted || attempt >= maxRetries) {
+              throw error;
+            }
+            // A thrown error is retried only when it is a network failure, or when shouldRetry
+            // says so. Before, every thrown error was retried: a validation error, an open
+            // circuit breaker, a rate limit (deep dive TRN-8).
+            const item = thrownItem<TRes>(context.message.id, error);
+            if (!shouldRetryItem(item, attempt)) {
+              throw error;
+            }
+            retryItem = item;
           }
-          // A thrown error is retried only when it is a network failure, or when shouldRetry
-          // says so. Before, every thrown error was retried: a validation error, an open
-          // circuit breaker, a rate limit (deep dive TRN-8).
-          const item = thrownItem<TRes>(context.message.id, error);
-          if (!shouldRetryItem(item, attempt)) {
-            throw error;
+
+          if (retryItem === undefined) {
+            // Success, a non-retryable error, or the last attempt
+            outcome = { success: lastItem?.status.type === "success", attempt };
+            return;
           }
-          retryItem = item;
-        }
 
-        if (retryItem === undefined) {
-          // Success, a non-retryable error, or the last attempt
-          if (onAfterRetry) {
-            await onAfterRetry(lastItem?.status.type === "success", attempt);
+          // The budget is empty: the error goes to the caller (R12)
+          if (!takeRetry()) {
+            outcome = { success: false, attempt };
+            yield retryItem;
+            return;
           }
-          return;
-        }
 
-        // The budget is empty: the error goes to the caller (R12)
-        if (!takeRetry()) {
-          yield retryItem;
-          if (onAfterRetry) await onAfterRetry(false, attempt);
-          return;
-        }
+          // A server that asks for a wait (Retry-After) gets at least that wait (R12)
+          let delay = Math.max(retryDelayOf(attempt, overrides), retryAfterOf(retryItem) ?? 0);
 
-        // A server that asks for a wait (Retry-After) gets at least that wait (R12)
-        let delay = Math.max(retryDelayOf(attempt, overrides), retryAfterOf(retryItem) ?? 0);
+          // Before retry hook
+          if (onBeforeRetry) {
+            const hookResult = await onBeforeRetry(retryItem, attempt);
+            if (!hookResult.shouldRetry) {
+              // Hook decided not to retry - yield the error and return
+              outcome = { success: false, attempt };
+              yield retryItem;
+              return;
+            }
 
-        // Before retry hook
-        if (onBeforeRetry) {
-          const hookResult = await onBeforeRetry(retryItem, attempt);
-          if (!hookResult.shouldRetry) {
-            // Hook decided not to retry - yield the error and return
-            yield retryItem;
-            if (onAfterRetry) {
-              await onAfterRetry(false, attempt);
+            // Use custom delay if provided by hook
+            if (hookResult.delayMs !== undefined) {
+              delay = hookResult.delayMs;
             }
-            return;
           }
 
-          // Use custom delay if provided by hook
-          if (hookResult.delayMs !== undefined) {
-            delay = hookResult.delayMs;
+          // The backoff stops at once when the caller aborts (deep dive TRN-8)
+          if (!(await sleep(delay, signal, clock))) {
+            yield abortedItem<TRes>(context.message.id);
+            return;
           }
+          attempt++;
         }
-
-        // The backoff stops at once when the caller aborts (deep dive TRN-8)
-        if (!(await sleep(delay, signal, clock))) {
-          yield abortedItem<TRes>(context.message.id);
-          return;
-        }
-        attempt++;
+      } finally {
+        if (outcome && onAfterRetry) await onAfterRetry(outcome.success, outcome.attempt);
       }
     };
   };