@procedures/client 0.4.0 → 0.5.0

package/src/adapters/sequence.ts

@@ -0,0 +1,55 @@
+/**
+ * The sequence numbers of the stream frames (wire protocol v1, `documentation/WIRE-PROTOCOL.md`).
+ *
+ * - The callee writes `seq` in each `stream` frame of a call: 1 in the first frame, and one more
+ *   in each next frame. The end frame has a number too. An NDJSON line `item` or `done` has the
+ *   same field.
+ * - The caller drops a frame whose `seq` is not above the last one. Thus a duplicate frame or a
+ *   late frame gives no item.
+ * - A gap is a loss. The delivery is at most once, so the stream continues. The next item has the
+ *   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.
+ */
+
+/**
+ * The metadata key of a stream item after a gap: the number of frames that did not arrive
+ * immediately before this item. The receiver sets it. It does not cross the wire.
+ */
+export const STREAM_GAP_METADATA_KEY = "stream-gap";
+
+/** The order of the stream frames of one call, at the side that receives them. */
+export class StreamSequence {
+  private last = 0;
+
+  /**
+   * This function examines the `seq` of a frame. It gives -1 for a frame to drop: its `seq` is
+   * not above the last one. Else it gives the number of frames that did not arrive before this
+   * frame. A frame without a valid `seq` gives 0.
+   */
+  next(seq: unknown, id: string): number {
+    if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) return 0;
+    if (seq <= this.last) return -1;
+    const gap = seq - this.last - 1;
+    this.last = seq;
+    if (gap > 0) console.warn(`[stream] Frames lost before seq ${seq} of the call ${id}: ${gap}`);
+    return gap;
+  }
+}
+
+/**
+ * This function gives the metadata of a stream item. The key `stream-gap` has the gap of the
+ * receiver only: the receiver removes a key of the same name that the peer sent.
+ */
+export function itemMetadata(metadata: Record<string, unknown> | undefined, gap: number): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...metadata };
+  delete out[STREAM_GAP_METADATA_KEY];
+  if (gap > 0) out[STREAM_GAP_METADATA_KEY] = gap;
+  return out;
+}
+
+/** 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];
+  return typeof gap === "number" ? gap : 0;
+}

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

@@ -10,6 +10,7 @@ import type { WebSocketTransportOptions, WebSocketMessage, ServerRequestHandler,
 import { WebSocketState } from "./types.js";
 import { withoutInternalKeys } from "../../metadata.js";
 import { IncomingCalls } from "../shared/rpc.js";
+import { StreamSequence, gapOf, itemMetadata } from "../../sequence.js";
 import type { RequestHandler, ServerResponse } from "../../../server/types.js";
 import { methodToPath } from "../../../server/method.js";
 import { optionalMs } from "../../../duration.js";
@@ -20,6 +21,17 @@ import { heartbeat, type Heartbeat } from "@mark1russell7/service/heartbeat";
 import { backoffDelay } from "@mark1russell7/service/backoff";
 import type { MachineTransition } from "../../../machines.js";
 import { WEBSOCKET_CONNECTION_MACHINE } from "../../../machines.js";
+import {
+  SubscriptionError,
+  remoteEvents,
+  subscribeRemote,
+  type RemoteEvent,
+  type RemoteEventHandler,
+  type RemoteEventsOptions,
+  type SubscribeOptions,
+  type Subscription,
+  type SubscriptionHooks,
+} from "../../../events/remote.js";
 
 /**
  * Pending request waiting for response.
@@ -74,6 +86,8 @@ interface PendingRequest {
   messageId: string;
   /** The response items of the request, in order */
   queue: ItemQueue<ResponseItem<unknown>>;
+  /** The `seq` of the stream frames: a duplicate or a late frame gives no item */
+  order: StreamSequence;
   /** The request timeout: it runs until the first frame arrives */
   timeout?: Cancel | undefined;
 }
@@ -234,6 +248,8 @@ export class WebSocketTransport implements Transport {
   private incoming: IncomingCalls | undefined;
   /** The time limit of the handshake of the socket that opens now */
   private handshakeTimer: Cancel | undefined = undefined;
+  /** The signal of the subscriptions of the transport: `close()` aborts it, so they end (EVENTS.md) */
+  private readonly subscriptions = new AbortController();
 
   constructor(options: WebSocketTransportOptions) {
     this.options = {
@@ -562,7 +578,8 @@ export class WebSocketTransport implements Transport {
       return;
     }
 
-    // Handle event (subscription event from server)
+    // The frame type `event` is reserved: no side of protocol v1 sends it. A server outside this
+    // repository can send it, so the frame still goes to onEvent (EVENTS.md).
     if (message.type === "event") {
       if (this.options.onEvent && message.topic && message.subscriptionId) {
         try {
@@ -577,7 +594,8 @@ export class WebSocketTransport implements Transport {
     // Handle response
     const pending = this.pendingRequests.get(message.id);
     if (!pending) {
-      console.warn(`[${this.name}] Received response for unknown request: ${message.id}`);
+      // A stream frame that left before the cancel of its call is normal: an unsubscribe, a break
+      if (message.type !== "stream") console.warn(`[${this.name}] Received response for unknown request: ${message.id}`);
       return;
     }
 
@@ -590,6 +608,9 @@ export class WebSocketTransport implements Transport {
     // A stream frame: one item, or the end of the stream (BUGS-2026-07 H5: before, the
     // transport resolved on the first frame and dropped the others)
     if (message.type === "stream") {
+      // A duplicate or a late frame: its item came before, or the delivery is at most once
+      const gap = pending.order.next(message.seq, message.id);
+      if (gap < 0) return;
       if (message.stream?.done) {
         this.pendingRequests.delete(message.id);
         pending.queue.end();
@@ -599,7 +620,7 @@ export class WebSocketTransport implements Transport {
         id: pending.messageId,
         status: { type: "success", code: 200 },
         payload: message.payload,
-        metadata: message.metadata || {},
+        metadata: itemMetadata(message.metadata, gap),
       });
       return;
     }
@@ -700,7 +721,7 @@ export class WebSocketTransport implements Transport {
     };
 
     const queue = new ItemQueue<ResponseItem<unknown>>();
-    const pending: PendingRequest = { messageId: message.id, queue };
+    const pending: PendingRequest = { messageId: message.id, queue, order: new StreamSequence() };
     pending.timeout = this.clock.after(this.options.requestTimeout, () => {
       if (this.pendingRequests.get(wireId) !== pending) return;
       this.pendingRequests.delete(wireId);
@@ -733,8 +754,10 @@ export class WebSocketTransport implements Transport {
       let taken = 0;
       for await (const item of queue) {
         yield item as ResponseItem<TRes>;
-        // The reader took the item: give the server credit, in batches of half the window
-        if (++taken >= window / 2 && this.pendingRequests.get(wireId) === pending) {
+        // The reader took the item: give the server credit, in batches of half the window.
+        // The frames of a gap took credit too, and no reader takes them.
+        taken += 1 + gapOf(item.metadata);
+        if (taken >= window / 2 && this.pendingRequests.get(wireId) === pending) {
           this.sendCredit(wireId, taken);
           taken = 0;
         }
@@ -849,9 +872,87 @@ export class WebSocketTransport implements Transport {
   }
 
   /**
-   * Close WebSocket connection. The requests in progress fail.
+   * 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.
+   *
+   * @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
+   * @returns The unsubscribe function, with the `ready` promise of the first confirmation
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = transport.subscribe("orders.created", (order) => console.log(order));
+   * await unsubscribe.ready;
+   * unsubscribe();
+   * ```
+   */
+  subscribe<T = unknown>(topics: string | readonly string[], handler: RemoteEventHandler<T>, options: SubscribeOptions = {}): Subscription {
+    return subscribeRemote<T>(this, topics, handler, options, this.subscriptionHooks());
+  }
+
+  /**
+   * This function gives the events of topics of the bus of the server as an async iterator. A
+   * `break` or the signal ends the subscription. The transport resubscribes after a drop, as for
+   * `subscribe()`. An error that ends the subscription ends the iteration.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param options - A signal, `onSubscribed`, the metadata of the call
+   */
+  events<T = unknown>(topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
+    return remoteEvents<T>(this, topics, options, this.subscriptionHooks());
+  }
+
+  /** The parts of the subscriptions of this transport: its connection, its backoff, its close and `onEvent`. */
+  private subscriptionHooks(): SubscriptionHooks {
+    return {
+      lifetime: this.subscriptions.signal,
+      ready: (signal) => this.whenConnected(signal),
+      backoff: (attempt) => reconnectDelay(attempt, this.options.reconnect),
+      onEvent: (event) => {
+        if (!this.options.onEvent) return;
+        try {
+          this.options.onEvent(event.topic, event.data, event.subscription);
+        } catch (error) {
+          console.error(`[${this.name}] Event handler error:`, error);
+        }
+      },
+    };
+  }
+
+  /**
+   * This function resolves when the transport is connected, or when the signal aborts. It has no
+   * time limit: a subscription waits for each reconnect. It rejects when the transport closed or
+   * stopped its reconnects.
+   */
+  private whenConnected(signal: AbortSignal): Promise<void> {
+    const closed = (): SubscriptionError => new SubscriptionError("CONNECTION_CLOSED", "The WebSocket transport is closed", false);
+    if (this.state === WebSocketState.CONNECTED || signal.aborted) return Promise.resolve();
+    if (this.state === WebSocketState.DISCONNECTED || this.closing) return Promise.reject(closed());
+    return new Promise((resolve, reject) => {
+      const finish = (error?: SubscriptionError): void => {
+        this.stateListeners.delete(check);
+        signal.removeEventListener("abort", onAbort);
+        if (error) reject(error);
+        else resolve();
+      };
+      const check = (): void => {
+        if (this.state === WebSocketState.CONNECTED) finish();
+        else if (this.state === WebSocketState.DISCONNECTED) finish(closed());
+      };
+      const onAbort = (): void => finish();
+      this.stateListeners.add(check);
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  /**
+   * Close WebSocket connection. The requests in progress fail, and the subscriptions end.
    */
   async close(): Promise<void> {
+    // The subscriptions end first: each one sends its cancel while the socket is open
+    this.subscriptions.abort();
     this.closing = true;
     this.setState(WebSocketState.DISCONNECTING, "close");
     this.stopHeartbeat();

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

@@ -152,8 +152,10 @@ export interface WebSocketTransportOptions {
   serve?: RequestHandler;
 
   /**
-   * Handler for subscription events.
-   * Called when the server pushes an event to a subscribed topic.
+   * This handler gets each event of each subscription of this transport (`subscribe()` and
+   * `events()`), with the id of its subscription (`documentation/EVENTS.md`). It is a wrapper: the
+   * handler of a subscription gets the same events. It also gets an `event` frame of a server
+   * outside this repository. No side of protocol v1 sends that frame.
    */
   onEvent?: EventHandler;
 
@@ -250,6 +252,13 @@ export interface WebSocketMessage<T = unknown> {
    */
   credit?: number;
 
+  /**
+   * The number of a `stream` frame in its call: 1 in the first frame, and one more in each next
+   * frame. The receiver drops a frame whose `seq` is not above the last one. A frame of an older
+   * peer has no `seq`.
+   */
+  seq?: number;
+
   /** Stream indicator (for streaming responses) */
   stream?: {
     /** Is this the last message in the stream? */
@@ -286,7 +295,8 @@ export type ServerRequestHandler = (
 ) => Promise<unknown>;
 
 /**
- * Handler for subscription events.
+ * The handler of the `onEvent` option: it gets the topic, the data and the id of the subscription
+ * of each event.
  */
 export type EventHandler = (
   topic: string,

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

@@ -24,6 +24,15 @@ import { optionalMs } from "../../../duration.js";
 import { credentialsOf, withoutSecretHeaders } from "../../../server/request-auth.js";
 import { PROTOCOL_VERSION, protocolVersionOf } from "../../../protocol.js";
 import { TIMER_DEFAULTS } from "../../../timers.js";
+import {
+  remoteEvents,
+  subscribeRemote,
+  type RemoteEvent,
+  type RemoteEventHandler,
+  type RemoteEventsOptions,
+  type SubscribeOptions,
+  type Subscription,
+} from "../../../events/remote.js";
 
 /**
  * WebSocket server transport adapter.
@@ -389,6 +398,8 @@ export class WebSocketServerTransport implements ServerTransport {
     if (channel.incoming.receive(message)) return;
     // A server-response frame of an older client, for a call that no longer exists
     if (message.type === "server-response") return;
+    // A late answer of a call that the server stopped: a cancel (an unsubscribe), a time limit
+    if (message.type === "stream" || message.type === "response" || message.type === "error") return;
     this.sendError(ws, message.id || "unknown", "Invalid message format");
   }
 
@@ -524,6 +535,38 @@ export class WebSocketServerTransport implements ServerTransport {
     };
   }
 
+  /**
+   * This function subscribes to topics of the bus of a client (`documentation/EVENTS.md`). The
+   * client serves them with its `serve` option: a `ProcedureServer` with the option `events`. The
+   * subscription ends with its connection: a reconnect is a new connection, so the server
+   * subscribes again in its `onConnect` handler. The `onError` handler gets the end.
+   *
+   * @param connectionId - The id of the connection of the client
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param handler - The handler of each event, in order
+   * @param options - `onSubscribed`, `onError`, a signal, the metadata of the call
+   */
+  subscribe<T = unknown>(
+    connectionId: string,
+    topics: string | readonly string[],
+    handler: RemoteEventHandler<T>,
+    options: SubscribeOptions = {},
+  ): Subscription {
+    return subscribeRemote<T>(this.transportFor(connectionId), topics, handler, options, { resubscribe: false });
+  }
+
+  /**
+   * This function gives the events of topics of the bus of a client as an async iterator. The
+   * iteration ends with the connection, with an error.
+   *
+   * @param connectionId - The id of the connection of the client
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @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 });
+  }
+
   /**
    * Call a procedure on a specific client (server-to-client RPC). It gives the value of the
    * call, and fails with its error. It is a wrapper of `callConnection` (roadmap R24).
@@ -550,7 +593,6 @@ export class WebSocketServerTransport implements ServerTransport {
   }
 
   /**
-   * Register a handler for new connections.  /**
    * Register a handler for new connections.
    * Returns a function to unregister the handler.
    */

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

@@ -150,6 +150,13 @@ export interface WebSocketMessage<TReq = unknown> {
    */
   credit?: number;
 
+  /**
+   * The number of a `stream` frame in its call: 1 in the first frame, and one more in each next
+   * frame. The receiver drops a frame whose `seq` is not above the last one. A frame of an older
+   * peer has no `seq`.
+   */
+  seq?: number;
+
   /** Stream indicator (for streaming responses) */
   stream?: {
     /** Is this the last message in the stream? */

package/src/adapters/websocket/shared/rpc.ts

@@ -15,6 +15,7 @@ import type { Message, ResponseItem } from "../../../client/types.js";
 import type { RequestHandler, ServerRequest } from "../../../server/types.js";
 import type { WebSocketMessage } from "../server/types.js";
 import { withoutInternalKeys } from "../../metadata.js";
+import { StreamSequence, gapOf, itemMetadata } from "../../sequence.js";
 import { DELIVERY_METADATA_KEY } from "../../../client/middleware/items.js";
 
 /**
@@ -143,6 +144,8 @@ interface PendingCall {
   messageId: string;
   /** The response items of the call, in order */
   queue: ItemQueue<ResponseItem<unknown>>;
+  /** The `seq` of the stream frames: a duplicate or a late frame gives no item */
+  order: StreamSequence;
   /** The time limit until the first frame */
   timeout?: ReturnType<typeof setTimeout> | undefined;
 }
@@ -192,7 +195,7 @@ export class OutgoingCalls {
     const wireId = `${this.options.idPrefix}${message.id}~${++this.seq}`;
     const window = this.options.streamWindow;
     const queue = new ItemQueue<ResponseItem<unknown>>();
-    const pending: PendingCall = { messageId: message.id, queue };
+    const pending: PendingCall = { messageId: message.id, queue, order: new StreamSequence() };
     const limited = Number.isFinite(this.options.requestTimeoutMs) && this.options.requestTimeoutMs > 0;
     if (limited) pending.timeout = setTimeout(() => {
       if (this.pending.get(wireId) !== pending) return;
@@ -231,8 +234,10 @@ export class OutgoingCalls {
       let taken = 0;
       for await (const item of queue) {
         yield item as ResponseItem<TRes>;
-        // The reader took the item: give the other side credit, in batches of half the window
-        if (++taken >= window / 2 && this.pending.get(wireId) === pending) {
+        // The reader took the item: give the other side credit, in batches of half the window.
+        // The frames of a gap took credit too, and no reader takes them.
+        taken += 1 + gapOf(item.metadata);
+        if (taken >= window / 2 && this.pending.get(wireId) === pending) {
           this.sendCredit(wireId, taken);
           taken = 0;
         }
@@ -262,12 +267,15 @@ export class OutgoingCalls {
       pending.timeout = undefined;
     }
     if (frame.type === "stream" && !frame.status) {
+      // A duplicate or a late frame: its item came before, or the delivery is at most once
+      const gap = pending.order.next(frame.seq, frame.id);
+      if (gap < 0) return true;
       if (frame.stream?.done) {
         this.pending.delete(frame.id);
         pending.queue.end();
         return true;
       }
-      pending.queue.push({ id: pending.messageId, status: { type: "success", code: 200 }, payload: frame.payload, metadata: frame.metadata || {} });
+      pending.queue.push({ id: pending.messageId, status: { type: "success", code: 200 }, payload: frame.payload, metadata: itemMetadata(frame.metadata, gap) });
       return true;
     }
     this.pending.delete(frame.id);
@@ -394,13 +402,15 @@ export class IncomingCalls {
 
   /**
    * Send a stream (BUGS-2026-07 H5): one `stream` frame for each item, then a frame with
-   * `stream.done`. An error of the stream ends it with an `error` frame. When the signal aborts
-   * (a cancel frame, a closed socket), the loop stops, and the handler of the stream gets
-   * return(). The stream takes its next item only when the reader has credit for it.
+   * `stream.done`. Each `stream` frame has its `seq`, from 1. An error of the stream ends it with
+   * an `error` frame. When the signal aborts (a cancel frame, a closed socket), the loop stops,
+   * and the handler of the stream gets return(). The stream takes its next item only when the
+   * reader has credit for it.
    */
   private async sendStream(id: string, stream: AsyncIterable<unknown>, signal: AbortSignal, credit: StreamCredit | undefined): Promise<void> {
     const iterator = stream[Symbol.asyncIterator]();
     let done = false;
+    let seq = 0;
     try {
       for (;;) {
         if (credit && !(await credit.take(signal))) return;
@@ -411,11 +421,11 @@ export class IncomingCalls {
           break;
         }
         if (signal.aborted || !this.options.isOpen()) return;
-        const item: WebSocketMessage = { id, type: "stream", payload: result.value, stream: { done: false } };
+        const item: WebSocketMessage = { id, type: "stream", seq: ++seq, payload: result.value, stream: { done: false } };
         if (this.options.sendWithBackpressure) await this.options.sendWithBackpressure(item, signal);
         else this.send(item);
       }
-      this.send({ id, type: "stream", stream: { done: true } });
+      this.send({ id, type: "stream", seq: ++seq, stream: { done: true } });
     } catch (error) {
       done = true;
       if (signal.aborted) return;

package/src/browser.ts

@@ -323,6 +323,8 @@ 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 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)
@@ -411,6 +413,19 @@ export type {
   EventWaitOptions,
   ChannelMap,
 } from "./events/index.js";
+// The remote events: a peer subscribes to the topics of the bus of another peer (EVENTS.md)
+export { EventPublisher, topicMatcher, EVENTS_SUBSCRIBE_PATH, SubscriptionError, remoteEvents, subscribeRemote } from "./events/index.js";
+export type {
+  EventPublisherOptions,
+  TopicRule,
+  TopicCall,
+  EventItem,
+  RemoteEvent,
+  RemoteEventHandler,
+  RemoteEventsOptions,
+  SubscribeOptions,
+  Subscription,
+} from "./events/index.js";
 
 // ============================================================================
 // Components (serializable UI descriptors) moved to @procedures/splay, the UI package

package/src/client/errors/registry.ts

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

package/src/events/index.ts

@@ -55,6 +55,22 @@ export {
   withEventBusSignal,
 } from "./bus.js";
 
+// The remote events: a peer subscribes to the topics of the bus of another peer (EVENTS.md)
+export { EventPublisher, topicMatcher, MAX_SUBSCRIPTION_TOPICS, MAX_TOPIC_LENGTH } from "./publisher.js";
+export type { EventPublisherOptions, TopicRule, TopicCall } from "./publisher.js";
+export { EVENTS_SUBSCRIBE_PATH, SubscriptionError, remoteEvents, subscribeRemote } from "./remote.js";
+export type {
+  EventItem,
+  EventTransport,
+  RemoteEvent,
+  RemoteEventHandler,
+  RemoteEventsOptions,
+  SubscribeInput,
+  SubscribeOptions,
+  Subscription,
+  SubscriptionHooks,
+} from "./remote.js";
+
 // Utilities
 export {
   createChannelPrefix,