@procedures/client 0.6.0 → 0.8.0

package/src/adapters/http/server/types.ts

@@ -8,6 +8,8 @@ import type { Request, Express } from "express";
 import type { Server as HttpServer } from "http";
 import type { Method } from "../../../client/types.js";
 import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
+import type { Clock } from "../../../clock.js";
+import type { Duration } from "../../../duration.js";
 
 /**
  * URL strategy for converting HTTP requests to RPC methods.
@@ -68,6 +70,21 @@ export interface HttpServerTransportOptions extends BrowserGuardOptions {
    */
   bodyLimit?: number;
 
+  /**
+   * The quiet time of an NDJSON stream. After it, the server writes a keep-alive line: a blank
+   * line. Each line of the stream starts the time again. Thus a proxy or a client with an idle
+   * timeout does not close a quiet stream. `false`, or a duration of zero or less, sends no
+   * keep-alive line.
+   * @default seconds(15) (`TIMER_DEFAULTS.httpServer.keepAliveMs`)
+   */
+  keepAlive?: Duration | false;
+
+  /**
+   * The clock of the keep-alive timers (roadmap R35). The default is the clock of the platform. A
+   * test gives a fake clock.
+   */
+  clock?: Clock;
+
   /**
    * Custom CORS options. `origin` is "*", one origin or a list: the response names the
    * request's origin when it is in the list.

package/src/adapters/sequence.ts

@@ -10,6 +10,8 @@
  *   number of lost frames in its metadata key `stream-gap`, and the caller writes a warning. The
  *   caller also gives back the credit of the lost frames.
  * - A frame without `seq` comes from an older peer. The caller takes it as before.
+ * - A blank line of an NDJSON stream is a keep-alive line. It is not a frame and it has no `seq`,
+ *   so the reader skips it before the check.
  */
 
 /**
@@ -18,6 +20,14 @@
  */
 export const STREAM_GAP_METADATA_KEY = "stream-gap";
 
+/**
+ * The metadata key of an item that the HTTP client transport read from an NDJSON stream. Its value
+ * is `true`. The receiver sets it. It does not cross the wire, and the receiver removes a key of
+ * this name that the peer sent. The constant `STREAM_METADATA_KEY` of the server has the same
+ * name, with the value `unbounded` in the metadata of a response.
+ */
+export const STREAM_ITEM_METADATA_KEY = "stream";
+
 /** The order of the stream frames of one call, at the side that receives them. */
 export class StreamSequence {
   private last = 0;
@@ -48,6 +58,14 @@ export function itemMetadata(metadata: Record<string, unknown> | undefined, gap:
   return out;
 }
 
+/**
+ * This function gives the metadata of an item of an NDJSON stream: the metadata of `itemMetadata`,
+ * and the key `stream` with the value `true`. The value of the peer for this key goes away.
+ */
+export function streamItemMetadata(metadata: Record<string, unknown> | undefined, gap: number): Record<string, unknown> {
+  return { ...itemMetadata(metadata, gap), [STREAM_ITEM_METADATA_KEY]: true };
+}
+
 /** The number of frames that did not arrive immediately before an item: 0 without a gap. */
 export function gapOf(metadata: Record<string, unknown> | undefined): number {
   const gap = metadata?.[STREAM_GAP_METADATA_KEY];

package/src/adapters/websocket/client/transport.ts

@@ -874,11 +874,12 @@ export class WebSocketTransport implements Transport {
   /**
    * This function subscribes to topics of the bus of the server (`documentation/EVENTS.md`). The
    * handler gets each event in order. After a drop, the transport sends the subscription again on
-   * the new connection. The events between the drop and the new confirmation are lost.
+   * the new connection. The events between the drop and the new confirmation are lost. The
+   * subscribers of the same topics with the same options share one call.
    *
    * @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
+   * @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
@@ -904,12 +905,17 @@ export class WebSocketTransport implements Transport {
     return remoteEvents<T>(this, topics, options, this.subscriptionHooks());
   }
 
-  /** The parts of the subscriptions of this transport: its connection, its backoff, its close and `onEvent`. */
+  /**
+   * The parts of the subscriptions of this transport: its connection, its backoff, its
+   * `maxAttempts`, its clock, its close and `onEvent`.
+   */
   private subscriptionHooks(): SubscriptionHooks {
     return {
       lifetime: this.subscriptions.signal,
       ready: (signal) => this.whenConnected(signal),
       backoff: (attempt) => reconnectDelay(attempt, this.options.reconnect),
+      maxAttempts: this.options.reconnect.maxAttempts,
+      clock: this.clock,
       onEvent: (event) => {
         if (!this.options.onEvent) return;
         try {

package/src/adapters/websocket/server/transport.ts

@@ -90,6 +90,12 @@ export class WebSocketServerTransport implements ServerTransport {
    */
   private readonly channels = new Map<string, { incoming: IncomingCalls; outgoing: OutgoingCalls }>();
 
+  /**
+   * The transport of the remote events of each connection: one object for each connection, so the
+   * subscriptions of one connection to the same topics share one call (EVENTS.md).
+   */
+  private readonly eventTransports = new Map<string, Transport>();
+
   /** The browser checks of each connection (see `server/browser-guard.ts`) */
   private readonly guard: BrowserGuardOptions;
 
@@ -303,6 +309,7 @@ export class WebSocketServerTransport implements ServerTransport {
       channel?.incoming.abortAll();
       channel?.outgoing.failAll("WebSocket connection closed");
       this.channels.delete(connectionId);
+      this.eventTransports.delete(connectionId);
       const conn = this.trackedConnections.get(connectionId);
       if (conn) {
         this.trackedConnections.delete(connectionId);
@@ -552,7 +559,7 @@ export class WebSocketServerTransport implements ServerTransport {
     handler: RemoteEventHandler<T>,
     options: SubscribeOptions = {},
   ): Subscription {
-    return subscribeRemote<T>(this.transportFor(connectionId), topics, handler, options, { resubscribe: false });
+    return subscribeRemote<T>(this.eventTransportFor(connectionId), topics, handler, options, { resubscribe: false });
   }
 
   /**
@@ -564,7 +571,21 @@ export class WebSocketServerTransport implements ServerTransport {
    * @param options - A signal, `onSubscribed`, the metadata of the call
    */
   events<T = unknown>(connectionId: string, topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
-    return remoteEvents<T>(this.transportFor(connectionId), topics, options, { resubscribe: false });
+    return remoteEvents<T>(this.eventTransportFor(connectionId), topics, options, { resubscribe: false });
+  }
+
+  /**
+   * The transport of the remote events of a connection: the same object for each subscription of
+   * a tracked connection. The close of the connection removes it.
+   */
+  private eventTransportFor(connectionId: string): Transport {
+    if (!this.trackedConnections.has(connectionId)) return this.transportFor(connectionId);
+    let transport = this.eventTransports.get(connectionId);
+    if (!transport) {
+      transport = this.transportFor(connectionId);
+      this.eventTransports.set(connectionId, transport);
+    }
+    return transport;
   }
 
   /**

package/src/browser.ts

@@ -128,6 +128,7 @@ export {
   registerModules,
   createRegistry,
   registerClientProcedures,
+  callerOf,
   // Procedure reference system (procedure-as-data)
   PROCEDURE_SYMBOL,
   PROCEDURE_JSON_KEY,
@@ -213,6 +214,7 @@ export {
 
 export type {
   Effects,
+  FsRootRules,
   PermittedEffects,
   Register,
   ClearanceOf,
@@ -235,6 +237,8 @@ export type {
   StorageMetadata,
   ProcedureModule,
   ModuleInput,
+  Caller,
+  CallerOptions,
   RegistrationOptions,
   ProcedureRegistryLike,
   ProcedureDefinition,
@@ -323,8 +327,9 @@ export type { TraceContext } from "./tracing/traceparent.js";
 // Wire protocol v1: the version and the one list of error codes (roadmap R25)
 export { PROTOCOL_VERSION, PROTOCOL_HEADER, ERROR_CODES, isProtocolErrorCode, httpStatusOf, protocolVersionOf } from "./protocol.js";
 export type { ProtocolErrorCode, ErrorCodeInfo } from "./protocol.js";
-// The seq of the stream frames: the metadata key of an item after a gap (WIRE-PROTOCOL.md)
-export { STREAM_GAP_METADATA_KEY } from "./adapters/sequence.js";
+// The seq of the stream frames: the metadata key of an item after a gap, and the key of an item
+// that the HTTP client read from an NDJSON stream (WIRE-PROTOCOL.md)
+export { STREAM_GAP_METADATA_KEY, STREAM_ITEM_METADATA_KEY } from "./adapters/sequence.js";
 // The deadline of a call: the remaining time goes as procedure-timeout (roadmap R10)
 export { TIMEOUT_METADATA_KEY, DEADLINE_METADATA_KEY } from "./client/deadline.js";
 // Typed durations: each public option that is a time takes a Duration (roadmap R11)
@@ -410,6 +415,7 @@ export type {
   TypedEventBus,
   EventHandler,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
   ChannelMap,
 } from "./events/index.js";
@@ -423,6 +429,7 @@ export type {
   RemoteEvent,
   RemoteEventHandler,
   RemoteEventsOptions,
+  ResubscribeBackoff,
   SubscribeOptions,
   Subscription,
 } from "./events/index.js";

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);
       }
     };
   };