@procedures/client 0.4.0 → 0.6.0

package/src/events/publisher.ts

@@ -0,0 +1,314 @@
+/**
+ * The publisher of the remote events (`documentation/EVENTS.md`).
+ *
+ * An `EventPublisher` serves the procedure `events.subscribe` from an event bus. A host gives it
+ * to `ProcedureServer` (the option `events`) or to `LocalTransport`. Each subscription is a stream
+ * without an end: its first item confirms the listeners, and each other item is one event of the
+ * bus.
+ *
+ * - The topic rule (`topics`) is the expose rule of the topics. A topic outside it gives
+ *   `TOPIC_NOT_FOUND`.
+ * - `allow` examines each topic with the capability of the call. A refusal gives `FORBIDDEN` with
+ *   the reason `topic-not-allowed`.
+ * - The procedure declares that it reads the resource `events`, so the capability of the host
+ *   applies to it as to each procedure.
+ *
+ * The delivery is at most once. The queue of a subscription holds at most `buffer` events. When
+ * it is full, the publisher drops the oldest event, and the next event tells the number of lost
+ * events (`dropped`). The bus never waits for a subscriber.
+ */
+
+import { z } from "zod";
+import { createProcedure } from "../procedures/define.js";
+import { InvocationError } from "../procedures/invoke.js";
+import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/types.js";
+import type { EventBus, Unsubscribe } from "./types.js";
+import { getGlobalEventBus } from "./bus.js";
+import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
+
+/** The number of topics that one subscription can name. */
+export const MAX_SUBSCRIPTION_TOPICS = 64;
+
+/** The number of characters of a topic name. */
+export const MAX_TOPIC_LENGTH = 256;
+
+/**
+ * The topics that a publisher serves: a list of patterns, or a function. A pattern is an exact
+ * name (`orders.created`), a prefix that ends with `*` (`orders.*`), or `*` for each topic.
+ */
+export type TopicRule = readonly string[] | ((topic: string) => boolean);
+
+/** What `allow` knows about the call of a subscription. */
+export interface TopicCall {
+  /** The capability of the call: its clearance, its permitted effects and its deadline. */
+  readonly capability: Capability;
+  /** The metadata of the call: the connection id and the headers of a network request. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+/** The options of an `EventPublisher`. */
+export interface EventPublisherOptions {
+  /** The bus that the subscriptions read. The default is the global bus of `getGlobalEventBus()`. */
+  bus?: EventBus | undefined;
+  /** The topics that a peer can subscribe to. A topic outside the rule gives `TOPIC_NOT_FOUND`. */
+  topics: TopicRule;
+  /**
+   * This function tells if a call can subscribe to a topic of the rule, for example from the
+   * clearance of its capability. A refusal gives `FORBIDDEN` with the reason `topic-not-allowed`.
+   * Without it, each call can subscribe to each topic of the rule.
+   */
+  allow?: ((topic: string, call: TopicCall) => boolean) | undefined;
+  /**
+   * The number of events that one subscription holds for a slow subscriber. When the queue is
+   * full, the publisher drops the oldest event.
+   * @default 1024
+   */
+  buffer?: number | undefined;
+}
+
+/** This function gives the test of a topic rule. */
+export function topicMatcher(rule: TopicRule): (topic: string) => boolean {
+  if (typeof rule === "function") return rule;
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  let all = false;
+  for (const pattern of rule) {
+    if (pattern === "*") all = true;
+    else if (pattern.endsWith("*")) prefixes.push(pattern.slice(0, -1));
+    else exact.add(pattern);
+  }
+  return (topic) => all || exact.has(topic) || prefixes.some((prefix) => topic.startsWith(prefix));
+}
+
+/** The error of a topic outside the topic rule. */
+class TopicNotFoundError extends Error {
+  override readonly name = "TopicNotFoundError";
+  readonly code = "TOPIC_NOT_FOUND";
+  readonly retryable = false;
+}
+
+/** The error that ends each subscription when the publisher stops. A resubscribe can succeed later. */
+function stoppedError(): Error {
+  return Object.assign(new Error("The publisher of the events stops"), { code: "UNAVAILABLE", retryable: true });
+}
+
+const topicSchema = z.string().min(1).max(MAX_TOPIC_LENGTH);
+
+const subscribeInput = z.object({
+  topics: z.array(topicSchema).min(1).max(MAX_SUBSCRIPTION_TOPICS).describe("The topics of the subscription"),
+});
+
+const eventItemSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("subscribed"),
+    topics: z.array(z.string()).describe("The topics that the publisher listens to for this subscription"),
+  }),
+  z.object({
+    type: z.literal("event"),
+    topic: z.string(),
+    data: z.unknown(),
+    seq: z.number().int().describe("The number of the event in the subscription, from 1"),
+    dropped: z.number().int().optional().describe("The events that the publisher dropped immediately before this one"),
+  }),
+]);
+
+/**
+ * One subscription: the listeners on the bus and the queue of its events. It is the async
+ * iterator of the stream of the call. `return()`, the abort of the signal of the call and
+ * `fail()` remove the listeners.
+ */
+class TopicSubscription implements AsyncIterableIterator<EventItem> {
+  private confirmation: EventItem | undefined;
+  private readonly queue: Array<Extract<EventItem, { type: "event" }>> = [];
+  private seq = 0;
+  private dropped = 0;
+  private waiter: { resolve: (result: IteratorResult<EventItem>) => void; reject: (error: unknown) => void } | undefined;
+  private closed = false;
+  private failure: unknown;
+  private readonly unsubscribes: Unsubscribe[];
+
+  constructor(
+    bus: EventBus,
+    topics: readonly string[],
+    private readonly buffer: number,
+    private readonly signal: AbortSignal | undefined,
+    private readonly onClose: (subscription: TopicSubscription) => void,
+  ) {
+    this.confirmation = { type: "subscribed", topics };
+    this.unsubscribes = topics.map((topic) => bus.on(topic, (data) => this.push(topic, data)));
+    signal?.addEventListener("abort", this.onAbort, { once: true });
+  }
+
+  /** This function closes a subscription whose call aborted before it started. */
+  closeIfAborted(): this {
+    if (this.signal?.aborted) this.close();
+    return this;
+  }
+
+  private readonly onAbort = (): void => this.close();
+
+  /** This function takes one event of the bus. It never waits. */
+  private push(topic: string, data: unknown): void {
+    if (this.closed) return;
+    const event = { type: "event" as const, topic, data, seq: ++this.seq };
+    const waiter = this.waiter;
+    if (waiter && this.queue.length === 0) {
+      this.waiter = undefined;
+      waiter.resolve({ value: this.withDropped(event), done: false });
+      return;
+    }
+    if (this.queue.length >= this.buffer) {
+      // A slow subscriber: the oldest event goes, and the next event tells the loss
+      this.queue.shift();
+      this.dropped++;
+    }
+    this.queue.push(event);
+  }
+
+  /** The event with the number of events that the publisher dropped before it. */
+  private withDropped(event: Extract<EventItem, { type: "event" }>): EventItem {
+    if (this.dropped === 0) return event;
+    const dropped = this.dropped;
+    this.dropped = 0;
+    return { ...event, dropped };
+  }
+
+  next(): Promise<IteratorResult<EventItem>> {
+    if (this.confirmation) {
+      const confirmation = this.confirmation;
+      this.confirmation = undefined;
+      return Promise.resolve({ value: confirmation, done: false });
+    }
+    const event = this.queue.shift();
+    if (event) return Promise.resolve({ value: this.withDropped(event), done: false });
+    if (this.failure !== undefined) {
+      const failure = this.failure;
+      this.failure = undefined;
+      return Promise.reject(failure);
+    }
+    if (this.closed) return Promise.resolve({ value: undefined, done: true });
+    return new Promise((resolve, reject) => {
+      this.waiter = { resolve, reject };
+    });
+  }
+
+  return(): Promise<IteratorResult<EventItem>> {
+    this.close();
+    return Promise.resolve({ value: undefined, done: true });
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<EventItem> {
+    return this;
+  }
+
+  /** This function ends the subscription with an error: the reader gets it at its next item. */
+  fail(error: unknown): void {
+    if (this.closed) return;
+    const waiter = this.waiter;
+    this.waiter = undefined;
+    this.release();
+    this.queue.length = 0;
+    this.confirmation = undefined;
+    if (waiter) waiter.reject(error);
+    else this.failure = error;
+  }
+
+  /** This function ends the subscription without an error. */
+  close(): void {
+    if (this.closed) return;
+    const waiter = this.waiter;
+    this.waiter = undefined;
+    this.release();
+    this.queue.length = 0;
+    this.confirmation = undefined;
+    waiter?.resolve({ value: undefined, done: true });
+  }
+
+  /** This function removes the listeners from the bus and from the signal. */
+  private release(): void {
+    this.closed = true;
+    for (const unsubscribe of this.unsubscribes) unsubscribe();
+    this.signal?.removeEventListener("abort", this.onAbort);
+    this.onClose(this);
+  }
+}
+
+/**
+ * The publisher of the remote events: it serves `events.subscribe` from a bus, under a topic
+ * rule. `ProcedureServer` makes one from its option `events`.
+ *
+ * @example
+ * ```typescript
+ * const publisher = new EventPublisher({ bus, topics: ["orders.*"] });
+ * const server = new ProcedureServer({ registry, autoRegister: true, events: publisher });
+ * publisher.publish("orders.created", { order: 1 });
+ * ```
+ */
+export class EventPublisher {
+  /** The bus that the subscriptions read. */
+  readonly bus: EventBus;
+  /** The procedure `events.subscribe` of this publisher. A host pins it, outside its registry. */
+  readonly procedure: AnyProcedure;
+  private readonly known: (topic: string) => boolean;
+  private readonly allow: EventPublisherOptions["allow"];
+  private readonly buffer: number;
+  private readonly open = new Set<TopicSubscription>();
+
+  constructor(options: EventPublisherOptions) {
+    this.bus = options.bus ?? getGlobalEventBus();
+    this.known = topicMatcher(options.topics);
+    this.allow = options.allow;
+    this.buffer = Math.max(1, Math.floor(options.buffer ?? 1024));
+    this.procedure = createProcedure()
+      .path([...EVENTS_SUBSCRIBE_PATH])
+      .input(subscribeInput)
+      .output(eventItemSchema)
+      .meta({
+        description: "A subscription to topics of the event bus of the host: a stream without an end, with one item for each event",
+        effects: { reads: ["events"], writes: [] },
+        stream: { unbounded: true },
+      })
+      .handler((async (input: SubscribeInput, ctx: ProcedureContext) => this.subscribe(input.topics, ctx)) as never)
+      .build() as AnyProcedure;
+  }
+
+  /** This function publishes an event on the bus: each subscription of the topic gets it. */
+  publish<T>(topic: string, data: T): void {
+    this.bus.emit(topic, data);
+  }
+
+  /** The number of open subscriptions. */
+  get subscriptions(): number {
+    return this.open.size;
+  }
+
+  /**
+   * This function ends each open subscription with a retryable `UNAVAILABLE`: the publisher stops.
+   * A subscriber resubscribes after its backoff. `ProcedureServer.stop()` calls it first.
+   */
+  end(): void {
+    for (const subscription of [...this.open]) subscription.fail(stoppedError());
+  }
+
+  /**
+   * The stream of one subscription. The publisher examines each topic before it adds a listener:
+   * the topic rule first, then `allow`. A call with one bad topic makes no subscription.
+   */
+  private subscribe(topics: readonly string[], ctx: ProcedureContext): TopicSubscription {
+    const unique = [...new Set(topics)];
+    for (const topic of unique) {
+      if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
+    }
+    if (this.allow) {
+      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata };
+      for (const topic of unique) {
+        if (!this.allow(topic, call)) {
+          throw new InvocationError("FORBIDDEN", `The capability of the call does not permit the topic "${topic}"`, ctx.path, "topic-not-allowed");
+        }
+      }
+    }
+    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed));
+    this.open.add(subscription);
+    return subscription.closeIfAborted();
+  }
+}

package/src/events/remote.ts

@@ -0,0 +1,369 @@
+/**
+ * The subscriber of the remote events (`documentation/EVENTS.md`).
+ *
+ * A peer subscribes to the topics of the bus of another peer with a streaming call of the
+ * procedure `events.subscribe`. The first item of the stream confirms the subscription, and each
+ * other item is one event. The frames are the frames of each call: credit is the backpressure,
+ * and a cancel is the unsubscribe. Thus each transport with streams carries a subscription:
+ * WebSocket in the two directions, HTTP with NDJSON, a message port and the local transport.
+ *
+ * - `remoteEvents()` gives an async iterator of the events.
+ * - `subscribeRemote()` calls a handler for each event, and gives the unsubscribe function.
+ *
+ * After a failure that a retry can repair (a closed connection, `UNAVAILABLE`, `TIMEOUT`), the
+ * subscriber sends the call again after a backoff. The delivery is at most once: the events
+ * between the failure and the new confirmation are lost. Each other error ends the subscription.
+ *
+ * This file imports only types and the backoff, so a page or a worker that subscribes stays small.
+ */
+
+import type { Message, Method, ResponseItem, Transport } from "../client/types.js";
+import { backoffDelay } from "@mark1russell7/service/backoff";
+
+/** The path of the procedure of a subscription. */
+export const EVENTS_SUBSCRIBE_PATH: readonly ["events", "subscribe"] = Object.freeze(["events", "subscribe"] as const);
+
+/** The method of the procedure of a subscription. */
+const SUBSCRIBE_METHOD: Method = Object.freeze({ service: "events", operation: "subscribe" });
+
+/** The input of `events.subscribe`. */
+export interface SubscribeInput {
+  /** The topics: from 1 to 64 names of 1 to 256 characters. */
+  readonly topics: readonly string[];
+}
+
+/**
+ * An item of the stream of `events.subscribe`. The first item is `subscribed`. Each other item is
+ * an `event`. A subscriber ignores an item of another type: it comes from a newer publisher.
+ */
+export type EventItem =
+  | { readonly type: "subscribed"; readonly topics: readonly string[] }
+  | {
+      readonly type: "event";
+      readonly topic: string;
+      readonly data: unknown;
+      /** The number of the event in its subscription, from 1. A gap shows lost events. */
+      readonly seq: number;
+      /** The number of events that the publisher dropped immediately before this one. */
+      readonly dropped?: number | undefined;
+    };
+
+/** One event that a subscriber gets. */
+export interface RemoteEvent<T = unknown> {
+  /** The topic (the channel of the bus of the publisher). */
+  readonly topic: string;
+  /** The data of the event, after a trip as JSON. */
+  readonly data: T;
+  /** The number of the event in its subscription, from 1. A resubscribe starts again at 1. */
+  readonly seq: number;
+  /** The number of events that the publisher dropped immediately before this one: 0 without a loss. */
+  readonly dropped: number;
+  /** The id of the subscription. It stays the same after a resubscribe. */
+  readonly subscription: string;
+}
+
+/**
+ * The handler of the events of a subscription. When it gives a promise, the subscriber waits for
+ * it before the next event, so a slow handler holds the credit of its own subscription only.
+ */
+export type RemoteEventHandler<T = unknown> = (data: T, event: RemoteEvent<T>) => void | Promise<void>;
+
+/** The options of a subscription. */
+export interface RemoteEventsOptions {
+  /** When this signal aborts, the subscription ends: the transport sends a cancel. */
+  signal?: AbortSignal | undefined;
+  /**
+   * True: the subscriber sends the call again after a failure that a retry can repair. False: such
+   * a failure ends the subscription.
+   * @default true
+   */
+  resubscribe?: boolean | undefined;
+  /**
+   * This function gives the time before resubscribe try `attempt` (from 1), in milliseconds. The
+   * default is an exponential backoff from 250 ms to 30 s with full jitter. The WebSocket
+   * transport uses its reconnect backoff.
+   */
+  backoff?: ((attempt: number) => number) | undefined;
+  /** This function gets the topics of each confirmation: the first one, and one after each resubscribe. */
+  onSubscribed?: ((topics: readonly string[]) => void) | undefined;
+  /** The metadata of the call, for example a trace. */
+  metadata?: Record<string, unknown> | undefined;
+}
+
+/** The options of `subscribeRemote()`. */
+export interface SubscribeOptions extends RemoteEventsOptions {
+  /**
+   * This function gets the error that ends the subscription: a refusal (`TOPIC_NOT_FOUND`,
+   * `FORBIDDEN`), an older publisher (`NOT_FOUND`), or a transport that closed. An unsubscribe is
+   * not an error.
+   */
+  onError?: ((error: SubscriptionError) => void) | undefined;
+}
+
+/**
+ * The unsubscribe function of a subscription. A second call does nothing. `ready` resolves at the
+ * first confirmation of the publisher. It rejects when the subscription ends before it.
+ */
+export interface Subscription {
+  (): void;
+  /** This promise resolves when the publisher confirms the subscription the first time. */
+  readonly ready: Promise<void>;
+  /** The id of the subscription: the `subscription` of its events. */
+  readonly id: string;
+}
+
+/** The error that ends a subscription. */
+export class SubscriptionError extends Error {
+  override readonly name = "SubscriptionError";
+
+  constructor(
+    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+    readonly code: string,
+    message: string,
+    /** True when a resubscribe can repair the failure. */
+    readonly retryable: boolean,
+    /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
+    readonly reason?: string | undefined,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * The parts that a transport adds to its subscriptions. The WebSocket transport waits for its
+ * connection, uses its reconnect backoff, ends its subscriptions at `close()`, and gives each
+ * event to its `onEvent` option.
+ */
+export interface SubscriptionHooks {
+  /** When this signal aborts, each subscription ends without an error. */
+  readonly lifetime?: AbortSignal | undefined;
+  /**
+   * This function resolves when the transport can send the call. It rejects when the transport
+   * closed. After a lost connection, the subscriber waits for it, not for a backoff.
+   */
+  readonly ready?: ((signal: AbortSignal) => Promise<void>) | undefined;
+  /** The backoff, when the options give none. */
+  readonly backoff?: ((attempt: number) => number) | undefined;
+  /** This function gets each event of each subscription. */
+  readonly onEvent?: ((event: RemoteEvent) => void) | undefined;
+  /** False: no resubscribe, whatever the options say (a server cannot reach a closed connection). */
+  readonly resubscribe?: boolean | undefined;
+}
+
+/** The part of a transport that a subscription uses. */
+export type EventTransport = Pick<Transport, "send">;
+
+/** The codes after which a resubscribe can succeed, also when the item does not say retryable. */
+const RESUBSCRIBE_CODES: ReadonlySet<string> = new Set(["UNAVAILABLE", "TIMEOUT", "CONNECTION_CLOSED", "ABORTED"]);
+
+/** The default backoff: from 250 ms, twice as long at each try, at most 30 s, with full jitter. */
+function defaultBackoff(attempt: number): number {
+  return backoffDelay({ base: 250, factor: 2, cap: 30_000, jitter: { kind: "subtract", fraction: 1 } }, attempt);
+}
+
+let subscriptions = 0;
+
+/** The topics of a subscription as a list. */
+function topicList(topics: string | readonly string[]): readonly string[] {
+  return typeof topics === "string" ? [topics] : [...topics];
+}
+
+/** A signal that aborts when one of the signals aborts, and a function that removes its listeners. */
+function linkSignals(signals: ReadonlyArray<AbortSignal | undefined>): { signal: AbortSignal; unlink: () => void } {
+  const controller = new AbortController();
+  const present = signals.filter((signal): signal is AbortSignal => signal !== undefined);
+  const abort = (): void => controller.abort();
+  if (present.some((signal) => signal.aborted)) controller.abort();
+  else for (const signal of present) signal.addEventListener("abort", abort, { once: true });
+  return {
+    signal: controller.signal,
+    unlink: () => {
+      for (const signal of present) signal.removeEventListener("abort", abort);
+    },
+  };
+}
+
+/** This function waits for a time, or until the signal aborts. */
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted || !(ms > 0)) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/** The error of an error item of the call. */
+function errorOfItem(item: ResponseItem<unknown>): SubscriptionError {
+  const status = item.status;
+  if (status.type !== "error") return new SubscriptionError("INTERNAL_ERROR", "The item is not an error", false);
+  const code = String(status.code);
+  const reason = item.metadata?.["reason"];
+  return new SubscriptionError(code, status.message, status.retryable === true || RESUBSCRIBE_CODES.has(code), typeof reason === "string" ? reason : undefined);
+}
+
+/** The error of a call that failed in the transport: the connection closed. A resubscribe can repair it. */
+function errorOfFailure(error: unknown): SubscriptionError {
+  if (error instanceof SubscriptionError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new SubscriptionError("CONNECTION_CLOSED", message, true);
+}
+
+/** The events of a subscription, with each resubscribe. The generator ends at the unsubscribe. */
+async function* eventsOf<T>(
+  transport: EventTransport,
+  topics: readonly string[],
+  options: RemoteEventsOptions,
+  hooks: SubscriptionHooks,
+  id: string,
+): AsyncGenerator<RemoteEvent<T>, void, undefined> {
+  const { signal, unlink } = linkSignals([options.signal, hooks.lifetime]);
+  const resubscribe = hooks.resubscribe !== false && options.resubscribe !== false;
+  const backoff = options.backoff ?? hooks.backoff ?? defaultBackoff;
+  let attempt = 0;
+  let tries = 0;
+  try {
+    for (;;) {
+      if (signal.aborted) return;
+      if (hooks.ready) {
+        await hooks.ready(signal);
+        if (signal.aborted) return;
+      }
+      const message: Message<SubscribeInput> = {
+        id: `${id}.${++tries}`,
+        method: SUBSCRIBE_METHOD,
+        payload: { topics: [...topics] },
+        metadata: { ...(options.metadata ?? {}) },
+        signal,
+      };
+      let failure: { error: SubscriptionError; lost: boolean } | undefined;
+      try {
+        for await (const item of transport.send<SubscribeInput, EventItem>(message)) {
+          if (item.status.type === "error") {
+            failure = { error: errorOfItem(item), lost: false };
+            break;
+          }
+          const payload = item.payload as EventItem | undefined;
+          if (payload === null || typeof payload !== "object") continue;
+          if (payload.type === "subscribed") {
+            attempt = 0;
+            options.onSubscribed?.(payload.topics);
+          } else if (payload.type === "event") {
+            const event: RemoteEvent<T> = {
+              topic: payload.topic,
+              data: payload.data as T,
+              seq: payload.seq,
+              dropped: payload.dropped ?? 0,
+              subscription: id,
+            };
+            hooks.onEvent?.(event as RemoteEvent);
+            yield event;
+          }
+        }
+      } catch (error) {
+        failure = { error: errorOfFailure(error), lost: true };
+      }
+      // An unsubscribe, or the end of the transport: no error
+      if (signal.aborted) return;
+      // The publisher ended the subscription
+      if (!failure) return;
+      if (!resubscribe || !failure.error.retryable) throw failure.error;
+      attempt++;
+      // After a lost connection, the transport waits for its reconnect: no second backoff
+      if (!(failure.lost && hooks.ready)) await pause(backoff(attempt), signal);
+    }
+  } finally {
+    unlink();
+  }
+}
+
+/**
+ * This function gives the events of a subscription to topics of the bus of the other side. The
+ * iteration sends the call. A `break` of the reader, or the abort of the signal, sends the cancel.
+ * An error that ends the subscription ends the iteration with a `SubscriptionError`.
+ *
+ * @param transport - The transport to the publisher: HTTP, WebSocket, a message port, local
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param options - The signal, the resubscribe, the backoff and the confirmation handler
+ * @param hooks - The parts that a transport adds (its connection, its backoff, its `onEvent`)
+ */
+export function remoteEvents<T = unknown>(
+  transport: EventTransport,
+  topics: string | readonly string[],
+  options: RemoteEventsOptions = {},
+  hooks: SubscriptionHooks = {},
+): AsyncIterable<RemoteEvent<T>> {
+  const list = topicList(topics);
+  return {
+    [Symbol.asyncIterator]: () => eventsOf<T>(transport, list, options, hooks, `events-${++subscriptions}`),
+  };
+}
+
+/**
+ * This function subscribes to topics of the bus of the other side, and calls the handler for each
+ * event in order. It gives the unsubscribe function, with the `ready` promise of the first
+ * confirmation. An error of the handler goes to `console.error`, and the subscription goes on.
+ *
+ * @param transport - The transport to the publisher
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param handler - The handler of each event: it gets the data and the event
+ * @param options - The options of `remoteEvents()`, and the `onError` handler of the end
+ * @param hooks - The parts that a transport adds
+ */
+export function subscribeRemote<T = unknown>(
+  transport: EventTransport,
+  topics: string | readonly string[],
+  handler: RemoteEventHandler<T>,
+  options: SubscribeOptions = {},
+  hooks: SubscriptionHooks = {},
+): Subscription {
+  const controller = new AbortController();
+  const id = `events-${++subscriptions}`;
+  let confirmed = false;
+  let confirm: () => void = () => undefined;
+  let refuse: (error: SubscriptionError) => void = () => undefined;
+  const ready = new Promise<void>((resolve, reject) => {
+    confirm = resolve;
+    refuse = reject;
+  });
+  // A caller that does not wait for `ready` gets no unhandled rejection
+  ready.catch(() => undefined);
+  const { signal, unlink } = linkSignals([options.signal, controller.signal]);
+  const settings: RemoteEventsOptions = {
+    ...options,
+    signal,
+    onSubscribed: (list) => {
+      if (!confirmed) {
+        confirmed = true;
+        confirm();
+      }
+      options.onSubscribed?.(list);
+    },
+  };
+
+  void (async () => {
+    try {
+      for await (const event of { [Symbol.asyncIterator]: () => eventsOf<T>(transport, topicList(topics), settings, hooks, id) }) {
+        try {
+          await handler(event.data, event);
+        } catch (error) {
+          console.error(`[events] The handler of ${event.topic} failed:`, error);
+        }
+      }
+      if (!confirmed) refuse(new SubscriptionError("ABORTED", "The subscription ended before its confirmation", false));
+    } catch (error) {
+      const failure = errorOfFailure(error);
+      if (!confirmed) refuse(failure);
+      options.onError?.(failure);
+    } finally {
+      unlink();
+    }
+  })();
+
+  const unsubscribe = (): void => controller.abort();
+  return Object.assign(unsubscribe, { ready, id });
+}

package/src/procedures/collection/index.ts

@@ -37,6 +37,7 @@ export {
 
 export type {
   GetInput,
+  GetFoundOutput,
   SetInput,
   DeleteInput,
   HasInput,