@procedures/client 0.3.0 → 0.5.0

package/src/client/errors/registry.ts

@@ -15,6 +15,7 @@ import {
 } from "./types.js";
 import { HTTP_ERROR_REGISTRY } from "./http-errors.js";
 import { ErrorCode } from "./codes.js";
+import { ERROR_CODES, type ProtocolErrorCode } from "../../protocol.js";
 
 /**
  * Create error metadata with defaults.
@@ -47,12 +48,72 @@ function defineError(
   return result;
 }
 
+/** The texts of an entry. For a code of the protocol, `ERROR_CODES` gives the status and the retry flag. */
+type ProtocolErrorTexts = Omit<ErrorMetadata, "code" | "httpStatus" | "retryable">;
+
 /**
- * Universal Error Registry
- *
- * Protocol-agnostic error codes with rich metadata.
+ * This function makes the entry of a code of the wire protocol. The HTTP status and the retry
+ * flag come from `ERROR_CODES` (`protocol.ts`, `WIRE-PROTOCOL.md`), the source of these facts.
+ */
+function defineProtocolError(code: ProtocolErrorCode, texts: ProtocolErrorTexts): ErrorMetadata {
+  const info = ERROR_CODES[code];
+  return defineError(code, { ...texts, httpStatus: info.http, retryable: info.retryable });
+}
+
+/** The category of each code of the protocol, for a code that the registry does not describe. */
+const PROTOCOL_CATEGORIES: Readonly<Record<ProtocolErrorCode, ErrorCategory>> = {
+  NOT_FOUND: ErrorCategory.CLIENT,
+  NO_HANDLER: ErrorCategory.SERVER,
+  NOT_EXPOSED: ErrorCategory.AUTH,
+  NOT_DECLARED: ErrorCategory.AUTH,
+  FORBIDDEN: ErrorCategory.AUTH,
+  UNAUTHORIZED: ErrorCategory.AUTH,
+  VALIDATION_ERROR: ErrorCategory.CLIENT,
+  INVALID_REQUEST: ErrorCategory.PROTOCOL,
+  PROTOCOL_VERSION: ErrorCategory.PROTOCOL,
+  OUTPUT_VALIDATION_ERROR: ErrorCategory.SERVER,
+  NO_OUTPUT: ErrorCategory.SERVER,
+  HANDLER_ERROR: ErrorCategory.SERVER,
+  INTERNAL_ERROR: ErrorCategory.SERVER,
+  NOT_ACCEPTABLE: ErrorCategory.CLIENT,
+  DUPLICATE: ErrorCategory.CLIENT,
+  DUPLICATE_REQUEST: ErrorCategory.CLIENT,
+  ABORTED: ErrorCategory.CANCELLED,
+  TIMEOUT: ErrorCategory.TIMEOUT,
+  UNAVAILABLE: ErrorCategory.SERVER,
+  CONNECTION_CLOSED: ErrorCategory.NETWORK,
+  CONNECTION_NOT_FOUND: ErrorCategory.CLIENT,
+  TOPIC_NOT_FOUND: ErrorCategory.CLIENT,
+};
+
+/**
+ * This function gives the registry with one entry for each code of the protocol. The status and
+ * the retry flag of such an entry come from `ERROR_CODES`, so the two lists agree (before, the
+ * registry gave `TIMEOUT` the status 408 and two codes another retry flag). A code without texts
+ * here gets the meaning of the protocol as its texts.
+ */
+function withProtocolCodes(described: ErrorRegistry): ErrorRegistry {
+  const registry: ErrorRegistry = { ...described };
+  for (const code of Object.keys(ERROR_CODES) as ProtocolErrorCode[]) {
+    const info = ERROR_CODES[code];
+    const meaning = `${info.meaning}.`;
+    const texts: ProtocolErrorTexts = described[code] ?? {
+      summary: info.meaning,
+      detail: meaning,
+      category: PROTOCOL_CATEGORIES[code],
+      severity: info.retryable ? ErrorSeverity.WARNING : ErrorSeverity.ERROR,
+      userMessage: meaning,
+      devMessage: meaning,
+    };
+    registry[code] = { ...texts, code, httpStatus: info.http, retryable: info.retryable };
+  }
+  return registry;
+}
+
+/**
+ * The entries with their own texts. `ERROR_REGISTRY` adds the codes of the protocol.
  */
-export const ERROR_REGISTRY: ErrorRegistry = {
+const DESCRIBED_ERRORS = {
   //
   // ═══ Network Errors ═══
   //
@@ -108,16 +169,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Timeout Errors ═══
   //
 
-  TIMEOUT: defineError(ErrorCode.TIMEOUT, {
+  TIMEOUT: defineProtocolError("TIMEOUT", {
     summary: "Request timed out",
     detail:
       "The request exceeded the configured timeout duration. This may indicate slow server response, network congestion, or overly aggressive timeout settings.",
     category: ErrorCategory.TIMEOUT,
-    retryable: true,
     severity: ErrorSeverity.WARNING,
     userMessage: "The request took too long to complete. Please try again.",
     devMessage: "Request exceeded timeout threshold. Consider increasing timeout or optimizing server response time.",
-    httpStatus: 408,
     suggestions: [
       "Try again with a longer timeout",
       "Check server performance",
@@ -159,11 +218,10 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Cancellation Errors ═══
   //
 
-  ABORTED: defineError(ErrorCode.ABORTED, {
+  ABORTED: defineProtocolError("ABORTED", {
     summary: "Request was aborted",
     detail: "The request was explicitly cancelled by the client via AbortSignal. This is user-initiated.",
     category: ErrorCategory.CANCELLED,
-    retryable: false,
     severity: ErrorSeverity.INFO,
     userMessage: "The request was cancelled.",
     devMessage: "Request aborted via AbortSignal. This is expected and not an error condition.",
@@ -269,15 +327,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  UNAUTHORIZED: defineError(ErrorCode.UNAUTHORIZED, {
+  UNAUTHORIZED: defineProtocolError("UNAUTHORIZED", {
     summary: "Unauthorized",
     detail: "Authentication is required but was not provided or is invalid.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "Authentication required. Please sign in.",
     devMessage: "Missing or invalid authentication credentials. Check auth token/API key.",
-    httpStatus: 401,
     suggestions: [
       "Provide valid authentication credentials",
       "Check token hasn't expired",
@@ -285,15 +341,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  FORBIDDEN: defineError(ErrorCode.FORBIDDEN, {
+  FORBIDDEN: defineProtocolError("FORBIDDEN", {
     summary: "Forbidden",
     detail: "The authenticated user doesn't have permission to access this resource.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "You don't have permission to access this resource.",
     devMessage: "Insufficient permissions. Check user roles and resource ACLs.",
-    httpStatus: 403,
     suggestions: [
       "Verify user has required permissions",
       "Check resource access control lists",
@@ -301,15 +355,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  NOT_FOUND: defineError(ErrorCode.NOT_FOUND, {
+  NOT_FOUND: defineProtocolError("NOT_FOUND", {
     summary: "Not found",
     detail: "The requested resource does not exist.",
     category: ErrorCategory.CLIENT,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "The requested item was not found.",
     devMessage: "Resource not found. Verify ID/path is correct and resource exists.",
-    httpStatus: 404,
     suggestions: [
       "Verify the resource ID is correct",
       "Check the resource hasn't been deleted",
@@ -402,17 +454,15 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Server Errors (5xx) ═══
   //
 
-  INTERNAL_ERROR: defineError(ErrorCode.INTERNAL_ERROR, {
+  INTERNAL_ERROR: defineProtocolError("INTERNAL_ERROR", {
     summary: "Internal server error",
     detail: "The server encountered an unexpected condition. This is a server-side bug.",
     category: ErrorCategory.SERVER,
-    retryable: true,
     severity: ErrorSeverity.CRITICAL,
     userMessage: "Server error occurred. Please try again later.",
     devMessage: "Internal server error. Check server logs for details.",
-    httpStatus: 500,
+    // The protocol says that a retry does not help (ERROR_CODES: retryable false)
     suggestions: [
-      "Retry the request",
       "Check server logs",
       "Contact server team",
     ],
@@ -554,6 +604,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   ...HTTP_ERROR_REGISTRY,
 } as const satisfies ErrorRegistry;
 
+/**
+ * Universal Error Registry
+ *
+ * Protocol-agnostic error codes with rich metadata. Each code of the wire protocol has an entry,
+ * and `ERROR_CODES` gives its HTTP status and its retry flag.
+ */
+export const ERROR_REGISTRY: ErrorRegistry = withProtocolCodes(DESCRIBED_ERRORS);
+
 /**
  * Get error metadata by code.
  *

package/src/client/middleware/rate-limit.ts

@@ -83,7 +83,6 @@ export class RateLimitError extends Error {
  */
 interface QueuedRequest {
   resolve: () => void;
-  reject: (error: Error) => void;
   timestamp: number;
 }
 
@@ -208,7 +207,6 @@ export function createRateLimitMiddleware(
           signal?.removeEventListener("abort", onAbort);
           resolve(true);
         },
-        reject: () => resolve(false),
         timestamp: Date.now(),
       };
       // A queued request whose caller aborts leaves the queue (before, it kept its place)

package/src/client/middleware/timeout.ts

@@ -170,19 +170,12 @@ async function* runWithTimeout<TReq, TRes>(
         phase = "done";
         return;
       }
-      if (result.value.status.type === "error" && timedOut()) {
-        // The transport saw the aborted signal and reported ABORTED: it is a timeout
-        yield timeoutItem();
-        return;
-      }
+      // An item or an error of the transport comes before the abort. `nextOrAbort` adds its abort
+      // listener before it calls `next()`, so a later abort gives ABORTED_FIRST, not an item.
       yield result.value;
     }
   } catch (error) {
     phase = "done";
-    if (timedOut()) {
-      yield timeoutItem();
-      return;
-    }
     throw error;
   } finally {
     clearTimeout(timeoutId);

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,

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