@procedures/client 0.7.0 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Procedures as data for TypeScript: define typed procedures once and call them in process, over HTTP, WebSocket, the CLI or MCP. Streaming, middleware, retries, caching and a JSON program format.",
   "keywords": [
     "rpc",

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

@@ -566,7 +566,7 @@ export class HttpServerTransport implements ServerTransport {
 
         server.listen(this.options.port, this.options.host, () => {
           console.log(
-            `[${this.name}] Server listening on http://${this.options.host}:${this.options.port}`
+            `[${this.name}] Server listening on http://${this.options.host}:${this.port() ?? this.options.port}`
           );
           resolve();
         });
@@ -610,4 +610,14 @@ export class HttpServerTransport implements ServerTransport {
   isRunning(): boolean {
     return !this.stopped && this.httpServer !== null && this.httpServer.listening;
   }
+
+  /**
+   * The port that the server of the transport listens on. With the option `port` 0, the system
+   * gives a free port, and this function returns that port. Before `start()` and after `stop()`,
+   * the function returns undefined.
+   */
+  port(): number | undefined {
+    const address = this.httpServer?.listening ? this.httpServer.address() : null;
+    return typeof address === "object" && address !== null ? address.port : undefined;
+  }
 }

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,
@@ -411,6 +415,7 @@ export type {
   TypedEventBus,
   EventHandler,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
   ChannelMap,
 } from "./events/index.js";
@@ -424,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);
       }
     };
   };