@procedures/client 0.47.1 → 0.48.0

package/src/events/bus.ts

@@ -11,6 +11,7 @@ import type {
   EventHandler,
   Unsubscribe,
   EventBusOptions,
+  EventFanOutOptions,
   EventListenOptions,
   EventWaitOptions,
 } from "./types.js";
@@ -34,6 +35,31 @@ function clearedError(channel: string): Error {
   return error;
 }
 
+/** The default of `fanOut.maxPending`. No bench chose it: a run of a slow channel can change it. */
+const DEFAULT_MAX_PENDING = 1024;
+
+/** The default of `fanOut.schedule`: a later task of the event loop. */
+function nextTask(slice: () => void): void {
+  if (typeof setImmediate === "function") setImmediate(slice);
+  else setTimeout(slice, 0);
+}
+
+/** The handlers of a channel, each with the number of its subscription, in the order of these numbers. */
+type ChannelHandlers = Map<EventHandler<unknown>, number>;
+
+/** One event that waits for its slices. */
+interface PendingEvent {
+  readonly channel: string;
+  readonly data: unknown;
+  /** The handlers of the channel at `emit()`. A new map of the channel gets no old event. */
+  readonly handlers: ChannelHandlers;
+  /** The live cursor: a removed handler gets no call, with no copy of the handlers per event. */
+  readonly cursor: Iterator<[EventHandler<unknown>, number]>;
+  /** The last subscription at `emit()`. A later handler does not get this event. */
+  readonly lastSubscription: number;
+  done: boolean;
+}
+
 // =============================================================================
 // Event Bus Implementation
 // =============================================================================
@@ -43,16 +69,34 @@ function clearedError(channel: string): Error {
  * Supports pub/sub messaging with async iteration.
  */
 export class DefaultEventBus implements EventBus {
-  private readonly subscribers = new Map<string, Set<EventHandler<unknown>>>();
+  private readonly subscribers = new Map<string, ChannelHandlers>();
+  /** The number of the last subscription of this bus. */
+  private lastSubscription = 0;
+  /** The events that wait for their slices, oldest first, from the index `pendingHead`. */
+  private pending: PendingEvent[] = [];
+  private pendingHead = 0;
+  /** For each channel, the number of its events in `pending`. */
+  private readonly pendingOn = new Map<string, number>();
+  private sliceScheduled = false;
+  private drainWaiters: Array<() => void> = [];
   private readonly buffer = new Map<string, unknown[]>();
   /**
    * For each channel, the functions that `clear()` runs: the `onClear` of each handler of `on()`
    * that has one. Each open stream has one too, so `clear()` ends it.
    */
   private readonly clearHandlers = new Map<string, Set<() => void>>();
-  private readonly options: Required<EventBusOptions>;
+  private readonly options: Required<Omit<EventBusOptions, "fanOut">>;
+  private readonly fanOut: Required<EventFanOutOptions> | undefined;
 
   constructor(options: EventBusOptions = {}) {
+    const { fanOut } = options;
+    if (fanOut && (!Number.isInteger(fanOut.sliceSize) || fanOut.sliceSize < 1)) {
+      throw new RangeError(`The option fanOut.sliceSize must be a whole number from 1 up, not ${fanOut.sliceSize}`);
+    }
+    if (fanOut?.maxPending !== undefined && (!Number.isInteger(fanOut.maxPending) || fanOut.maxPending < 1)) {
+      throw new RangeError(`The option fanOut.maxPending must be a whole number from 1 up, not ${fanOut.maxPending}`);
+    }
+    this.fanOut = fanOut && { maxPending: DEFAULT_MAX_PENDING, schedule: nextTask, ...fanOut };
     this.options = {
       bufferSize: options.bufferSize ?? 0,
       onError: options.onError ?? ((error, channel) => {
@@ -64,6 +108,12 @@ export class DefaultEventBus implements EventBus {
 
   /**
    * Emit an event on a channel.
+   *
+   * Without the option `fanOut`, each handler runs before this method returns. With it, a channel
+   * with more than `fanOut.sliceSize` handlers delivers later, in slices (roadmap CLI-90). One
+   * handler gets the events of a channel in the order of `emit()`. An unsubscribe stops the calls
+   * that wait for that handler. A handler that comes after `emit()` does not get the event. The
+   * events of two different channels can reach a handler in another order.
    */
   emit<T>(channel: string, data: T): void {
     if (this.options.debug) {
@@ -87,19 +137,104 @@ export class DefaultEventBus implements EventBus {
     const channelSubs = this.subscribers.get(channel);
     if (!channelSubs) return;
 
-    for (const handler of channelSubs) {
-      try {
-        const result = handler(data);
-        // Handle async handlers
-        if (result instanceof Promise) {
-          result.catch((error) => this.options.onError(error, channel));
-        }
-      } catch (error) {
-        this.options.onError(error instanceof Error ? error : new Error(String(error)), channel);
+    if (this.fanOut && (channelSubs.size > this.fanOut.sliceSize || this.pendingOn.has(channel))) {
+      this.enqueue(channel, data, channelSubs, this.fanOut);
+      return;
+    }
+
+    for (const handler of channelSubs.keys()) this.call(handler, data, channel);
+  }
+
+  /** This function calls one handler. An error goes to `onError`, and it stops no other handler. */
+  private call(handler: EventHandler<unknown>, data: unknown, channel: string): void {
+    try {
+      const result = handler(data);
+      // Handle async handlers
+      if (result instanceof Promise) {
+        result.catch((error) => this.options.onError(error, channel));
+      }
+    } catch (error) {
+      this.options.onError(error instanceof Error ? error : new Error(String(error)), channel);
+    }
+  }
+
+  /** This function puts an event in the queue of the slices. A full queue finishes its oldest events. */
+  private enqueue(channel: string, data: unknown, handlers: ChannelHandlers, fanOut: Required<EventFanOutOptions>): void {
+    this.pending.push({ channel, data, handlers, cursor: handlers.entries(), lastSubscription: this.lastSubscription, done: false });
+    this.pendingOn.set(channel, (this.pendingOn.get(channel) ?? 0) + 1);
+    while (this.pending.length - this.pendingHead > fanOut.maxPending) {
+      const oldest = this.pending[this.pendingHead]!;
+      this.deliverPart(oldest, Number.POSITIVE_INFINITY);
+      this.retire(oldest);
+    }
+    this.scheduleSlice(fanOut);
+  }
+
+  private scheduleSlice(fanOut: Required<EventFanOutOptions>): void {
+    if (this.sliceScheduled || this.pendingHead === this.pending.length) return;
+    this.sliceScheduled = true;
+    fanOut.schedule(() => {
+      this.sliceScheduled = false;
+      this.deliver(fanOut.sliceSize);
+      this.scheduleSlice(fanOut);
+    });
+  }
+
+  /** This function calls at most `limit` handlers of the oldest events. */
+  private deliver(limit: number): void {
+    let left = limit;
+    while (left > 0 && this.pendingHead < this.pending.length) {
+      const event = this.pending[this.pendingHead]!;
+      left -= this.deliverPart(event, left);
+      if (event.done) this.retire(event);
+    }
+    if (this.pendingHead === this.pending.length) this.drainWaiters.splice(0).forEach((resolve) => resolve());
+  }
+
+  /** This function calls at most `limit` handlers of one event, and returns the count of calls. */
+  private deliverPart(event: PendingEvent, limit: number): number {
+    let calls = 0;
+    while (calls < limit && !event.done) {
+      // clear(), or the last unsubscribe: the map of this event is not the map of the channel now
+      const step = this.subscribers.get(event.channel) === event.handlers ? event.cursor.next() : undefined;
+      if (!step || step.done || step.value[1] > event.lastSubscription) {
+        event.done = true;
+        break;
       }
+      this.call(step.value[0], event.data, event.channel);
+      calls++;
+    }
+    return calls;
+  }
+
+  /**
+   * This function takes a finished event from the queue. A handler in a slice can emit, and that
+   * emit can finish the event first, so this function examines the head.
+   */
+  private retire(event: PendingEvent): void {
+    if (this.pending[this.pendingHead] !== event) return;
+    this.pendingHead++;
+    const left = (this.pendingOn.get(event.channel) ?? 1) - 1;
+    if (left === 0) this.pendingOn.delete(event.channel);
+    else this.pendingOn.set(event.channel, left);
+    if (this.pendingHead === this.pending.length) {
+      this.pending = [];
+      this.pendingHead = 0;
+    } else if (this.pendingHead > 1024 && this.pendingHead * 2 > this.pending.length) {
+      this.pending = this.pending.slice(this.pendingHead);
+      this.pendingHead = 0;
     }
   }
 
+  /**
+   * This method resolves when no event waits for a slice. A host calls it before it stops. Without
+   * the option `fanOut`, it resolves at once.
+   */
+  drained(): Promise<void> {
+    if (this.pendingHead === this.pending.length) return Promise.resolve();
+    return new Promise((resolve) => this.drainWaiters.push(resolve));
+  }
+
   /**
    * Subscribe to events on a channel. The `onClear` of the options runs one time when `clear()`
    * or `clearAll()` removes the handler, not at an unsubscribe.
@@ -111,11 +246,14 @@ export class DefaultEventBus implements EventBus {
 
     let channelSubs = this.subscribers.get(channel);
     if (!channelSubs) {
-      channelSubs = new Set();
+      channelSubs = new Map();
       this.subscribers.set(channel, channelSubs);
     }
 
-    channelSubs.add(handler as EventHandler<unknown>);
+    // A handler that is already on the channel keeps its place and its number
+    if (!channelSubs.has(handler as EventHandler<unknown>)) {
+      channelSubs.set(handler as EventHandler<unknown>, ++this.lastSubscription);
+    }
 
     // The unsubscribe function works once, and removes only the set it added to. (Before, a
     // repeated call of an old unsubscribe removed the set of a newer subscriber: deep dive CORE-15.)
@@ -144,16 +282,7 @@ export class DefaultEventBus implements EventBus {
     // Replay buffered events if any
     const buffered = this.buffer.get(channel);
     if (buffered && buffered.length > 0) {
-      for (const data of buffered) {
-        try {
-          const result = handler(data as T);
-          if (result instanceof Promise) {
-            result.catch((error) => this.options.onError(error, channel));
-          }
-        } catch (error) {
-          this.options.onError(error instanceof Error ? error : new Error(String(error)), channel);
-        }
-      }
+      for (const data of buffered) this.call(handler as EventHandler<unknown>, data, channel);
     }
 
     return () => {

package/src/events/index.ts

@@ -40,6 +40,7 @@ export type {
   ProcedureChannels,
   DefaultChannels,
   EventBusOptions,
+  EventFanOutOptions,
   EventListenOptions,
   EventWaitOptions,
 } from "./types.js";

package/src/events/publisher.ts

@@ -226,6 +226,16 @@ function resetHint(): unknown {
  * gives the events of its queue, and then it ends with `TOPIC_CLEARED`.
  */
 class TopicSubscription implements AsyncIterableIterator<EventItem> {
+  private readonly buffer: number;
+  private readonly signal: AbortSignal | undefined;
+  private readonly onClose: (subscription: TopicSubscription) => void;
+  /** The output filter of the host for this subscriber: each row of a value passes it */
+  private readonly admit: ((item: unknown) => Promise<boolean>) | undefined;
+  /** The invocation of the subscription: the rule of the rows of a value gets it (roadmap CLI-41) */
+  private readonly invocation?: Invocation | undefined;
+  /** The row filter of each topic of a collection, by the topic of the subscriber (roadmap CLI-78) */
+  private readonly filters?: ReadonlyMap<string, RowHintFilter> | undefined;
+
   private confirmation: EventItem | undefined;
   private readonly queue: QueuedEvent[] = [];
   private seq = 0;
@@ -245,16 +255,19 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     bus: EventBus,
     /** The topics of the subscriber, each with the topic of the bus that it listens to */
     routes: ReadonlyArray<Route>,
-    private readonly buffer: number,
-    private readonly signal: AbortSignal | undefined,
-    private readonly onClose: (subscription: TopicSubscription) => void,
-    /** The output filter of the host for this subscriber: each row of a value passes it */
-    private readonly admit: ((item: unknown) => Promise<boolean>) | undefined,
-    /** The invocation of the subscription: the rule of the rows of a value gets it (roadmap CLI-41) */
-    private readonly invocation?: Invocation | undefined,
-    /** The row filter of each topic of a collection, by the topic of the subscriber (roadmap CLI-78) */
-    private readonly filters?: ReadonlyMap<string, RowHintFilter> | undefined,
+    buffer: number,
+    signal: AbortSignal | undefined,
+    onClose: (subscription: TopicSubscription) => void,
+    admit: ((item: unknown) => Promise<boolean>) | undefined,
+    invocation?: Invocation | undefined,
+    filters?: ReadonlyMap<string, RowHintFilter> | undefined,
   ) {
+    this.buffer = buffer;
+    this.signal = signal;
+    this.onClose = onClose;
+    this.admit = admit;
+    this.invocation = invocation;
+    this.filters = filters;
     this.confirmation = { type: "subscribed", topics: routes.map(({ topic }) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
     this.unsubscribes = routes.map(({ topic, busTopic }) =>

package/src/events/recheck.ts

@@ -109,6 +109,8 @@ type RecheckCheck = (cause: RecheckCause, scope?: RightsScopes) => Promise<void>
  * each new subscription to `watch()`, with the check of its admission.
  */
 export class SubscriptionRechecks {
+  private readonly clock: Clock;
+
   private readonly watches = new Set<Watch>();
   private readonly maxAgeMs: number | undefined;
   private readonly source: SubscriptionRecheck["rightsChanges"];
@@ -117,8 +119,9 @@ export class SubscriptionRechecks {
 
   constructor(
     options: SubscriptionRecheck,
-    private readonly clock: Clock,
+    clock: Clock,
   ) {
+    this.clock = clock;
     const maxAgeMs = options.maxAge === undefined ? undefined : toMs(options.maxAge, "recheck.maxAge");
     if (maxAgeMs !== undefined && !(maxAgeMs > 0)) {
       throw new TypeError(`recheck.maxAge must be more than 0 ms, got ${maxAgeMs} ms`);

package/src/events/remote.ts

@@ -168,18 +168,25 @@ export interface Subscription {
 
 /** The error that ends a subscription. */
 export class SubscriptionError extends Error {
+  /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+  readonly code: 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;
+
   override readonly name = "SubscriptionError";
 
   constructor(
-    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
-    readonly code: string,
+    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,
+    retryable: boolean,
+    reason?: string | undefined,
   ) {
     super(message);
+    this.code = code;
+    this.retryable = retryable;
+    this.reason = reason;
   }
 }
 
@@ -462,6 +469,8 @@ type Entry =
  * last event that the shared subscription got before the subscriber joined.
  */
 class Subscriber {
+  readonly id: string;
+
   /** The `seq` of the wire subscription before the first event of this subscriber. */
   base = 0;
   /** The error that ends this subscriber, after the entries of its queue. */
@@ -473,7 +482,9 @@ class Subscriber {
   private waiter: ((entry: Entry | undefined) => void) | undefined;
   private ended = false;
 
-  constructor(readonly id: string) {}
+  constructor(id: string) {
+    this.id = id;
+  }
 
   /** True when the subscriber waits for an entry. */
   get waiting(): boolean {
@@ -546,6 +557,11 @@ class Subscriber {
  * when its last subscriber leaves, or with the end of the wire subscription for each subscriber.
  */
 class SharedSubscription {
+  private readonly shares: Map<string, SharedSubscription> | undefined;
+  private readonly key: string;
+  private readonly transport: EventTransport;
+  private readonly call: Omit<WireCall, "onSubscribed" | "onRetry">;
+
   private readonly members = new Set<Subscriber>();
   private readonly stop = new AbortController();
   /** The topics of the current confirmation, or undefined before it and during a resubscribe. */
@@ -557,11 +573,16 @@ class SharedSubscription {
   private finished = false;
 
   constructor(
-    private readonly shares: Map<string, SharedSubscription> | undefined,
-    private readonly key: string,
-    private readonly transport: EventTransport,
-    private readonly call: Omit<WireCall, "onSubscribed" | "onRetry">,
-  ) {}
+    shares: Map<string, SharedSubscription> | undefined,
+    key: string,
+    transport: EventTransport,
+    call: Omit<WireCall, "onSubscribed" | "onRetry">,
+  ) {
+    this.shares = shares;
+    this.key = key;
+    this.transport = transport;
+    this.call = call;
+  }
 
   /** True while a new subscriber can join. */
   get open(): boolean {

package/src/events/types.ts

@@ -273,4 +273,38 @@ export interface EventBusOptions {
    * Default: false
    */
   debug?: boolean;
+
+  /**
+   * The bounded fan-out (roadmap CLI-90). Without it, `emit()` calls each handler before it
+   * returns, at each channel size.
+   */
+  fanOut?: EventFanOutOptions;
+}
+
+/**
+ * The options of the bounded fan-out of an event bus (roadmap CLI-90).
+ *
+ * A channel with more handlers than `sliceSize` delivers after `emit()` returns, in slices. The
+ * event loop runs between two slices, so one event does not hold it. A smaller channel stays
+ * synchronous, while no event of the channel waits.
+ *
+ * The limit is a count of handlers, not a time. The work of a stream reader runs in microtasks
+ * after its handler returns, so a clock in the slice does not see this work.
+ */
+export interface EventFanOutOptions {
+  /** The most handlers that one slice calls. A number from 1 up. */
+  sliceSize: number;
+
+  /**
+   * The most events that wait for their slices. The next event then finishes the oldest events
+   * in its `emit()`: the bus loses no event, and its memory stays bounded.
+   * Default: 1024
+   */
+  maxPending?: number;
+
+  /**
+   * The function that runs a slice in a later task of the event loop.
+   * Default: `setImmediate`, or `setTimeout` where `setImmediate` does not exist
+   */
+  schedule?: (slice: () => void) => void;
 }

package/src/middleware/compose.ts

@@ -6,6 +6,7 @@
  * for any chain length - no manual overloads needed!
  */
 
+import { compose as foldLayers, type Layer } from "@mark1russell7/collections/layers";
 import type {
   Middleware,
   MiddlewareRunner,
@@ -47,12 +48,7 @@ export function wrapWithAsyncMiddlewares<
     true
   >
 ): MiddlewareRunner<TBaseContext, TReturn, true> {
-  const combinedRunner = middlewares.reduceRight(
-    (currentRunner, currentMiddleware) => {
-      return currentMiddleware(currentRunner);
-    },
-    fn
-  ) as MiddlewareRunner<TBaseContext, TReturn, true>;
+  const combinedRunner = foldLayers(...(middlewares as readonly Layer[]))(fn) as MiddlewareRunner<TBaseContext, TReturn, true>;
 
   // Wrap in async to ensure synchronous throws become rejected promises
   return async (context) => {
@@ -85,9 +81,7 @@ export function wrapWithSyncMiddlewares<
     false
   >
 ): MiddlewareRunner<TBaseContext, TReturn, false> {
-  return middlewares.reduceRight((currentRunner, currentMiddleware) => {
-    return currentMiddleware(currentRunner);
-  }, fn) as MiddlewareRunner<TBaseContext, TReturn, false>;
+  return foldLayers(...(middlewares as readonly Layer[]))(fn) as MiddlewareRunner<TBaseContext, TReturn, false>;
 }
 
 /**
@@ -115,13 +109,8 @@ export function compose<TAsync extends boolean = false>(
   const fn = args[args.length - 1];
   const middleware = args.slice(0, -1) as Middleware<any, any, any, TAsync>[];
 
-  // Compose middleware from right to left (onion model)
-  const combined = middleware.reduceRight(
-    (next, mw) => mw(next),
-    fn
-  ) as MiddlewareRunner<any, any, TAsync>;
-
-  return combined;
+  // The first middleware is the outermost one (onion model)
+  return foldLayers(...(middleware as readonly Layer[]))(fn) as MiddlewareRunner<any, any, TAsync>;
 }
 
 /**
@@ -150,10 +139,5 @@ export function compose<TAsync extends boolean = false>(
 export function bundle<TAsync extends boolean = false>(
   ...middleware: Middleware<any, any, any, TAsync>[]
 ): Middleware<any, any, any, TAsync> {
-  return (next) =>
-    middleware.reduceRight((acc, mw) => mw(acc), next) as MiddlewareRunner<
-      any,
-      any,
-      TAsync
-    >;
+  return foldLayers(...(middleware as readonly Layer[])) as Middleware<any, any, any, TAsync>;
 }

package/src/procedures/caller.ts

@@ -1,7 +1,7 @@
 /**
  * A caller of the procedures of some modules (`callerOf`). An app that calls the procedures of a
  * package in its own process repeats three steps: a registry of the module, `invokePath` and
- * `outputValue`. A caller does the three steps in one call. jarvis had four copies of them.
+ * `outputValue`. A caller does the three steps in one call.
  */
 
 import type { ProcedurePath } from "./types.js";

package/src/procedures/collection/admission.ts

@@ -1,6 +1,6 @@
 /**
  * The rules of the rows of a served collection (roadmap CLI-41). A right can depend on the
- * document: a `when` condition of Graph, or `accessAdmitItem()` of `@procedures/access`. The option
+ * document: a `when` condition of an app, or `accessAdmitItem()` of `@procedures/access`. The option
  * `admission` of `createCollectionProcedures()` gives the rules as data:
  *
  * - `admit` examines each row `{ id, value }` that a read gives. It has the shape of `AdmitItem`,

package/src/procedures/collection/hint-filter.ts

@@ -201,6 +201,13 @@ function ignore(): void {}
  * of the topic to `apply()`, one at a time, in the order of the bus.
  */
 export class RowHintFilter {
+  /** The rules of the collection from the registry of the call. */
+  private readonly lookup: () => CollectionAdmission | null | undefined;
+  /** The invocation of the topic (`collectionInvocation()`): the rules get it. */
+  readonly invocation: Invocation | undefined;
+  /** The partition of the topic: `admitsAll` gets it. */
+  private readonly partition: string | undefined;
+
   /** The rules from the registry: undefined when the registry does not know the collection. */
   private rules: CollectionAdmission | null | undefined;
   /** The result of `admitsAll` for one set of rules. */
@@ -213,13 +220,13 @@ export class RowHintFilter {
   private tail: Promise<unknown> = Promise.resolve();
 
   constructor(
-    /** The rules of the collection from the registry of the call. */
-    private readonly lookup: () => CollectionAdmission | null | undefined,
-    /** The invocation of the topic (`collectionInvocation()`): the rules get it. */
-    readonly invocation: Invocation | undefined,
-    /** The partition of the topic: `admitsAll` gets it. */
-    private readonly partition: string | undefined,
+    lookup: () => CollectionAdmission | null | undefined,
+    invocation: Invocation | undefined,
+    partition: string | undefined,
   ) {
+    this.lookup = lookup;
+    this.invocation = invocation;
+    this.partition = partition;
     this.rules = lookup();
   }
 

package/src/server/face-rules.ts

@@ -73,7 +73,7 @@ function exposeRule(expose: NonNullable<FaceRulesOptions["expose"]>): (path: Pro
  *
  * @example
  * ```typescript
- * const rules = faceRules({ narrowing: { effects: { writes: [] } }, expose: ["graphapi.*"] }, policy, "read");
+ * const rules = faceRules({ narrowing: { effects: { writes: [] } }, expose: ["api.*"] }, policy, "read");
  * const handler = { ...inner, handle: (request) => inner.handle(rules.apply(request)) };
  * ```
  */

package/src/server/procedure-server.ts

@@ -146,7 +146,8 @@ export interface ProcedureServerOptions extends ServerOptions {
    * the server answers `UNAUTHORIZED`. Only a local request (`LOCAL_CREDENTIALS`) skips it. The
    * server refuses a request without credentials (CLI-1). Before, only the Express middleware of
    * the peer examined the token, so a `ProcedureServer` with the HTTP or WebSocket transport of the
-   * core and the token of a host policy accepted each request.
+   * core and the token of a host policy accepted each request. An empty token means "refuse each
+   * network request": no presented token matches it, not even an empty one.
    */
   token?: string | undefined;
 
@@ -235,16 +236,18 @@ export interface RegisterProcedureOptions {
 }
 
 /**
- * True when the presented token is the expected one. The comparison reads each character of the
- * expected token for each presented token, so its time depends only on the expected token. The
- * time tells neither the token nor its length. The function runs in a browser too, so it uses
- * no `node:crypto`.
+ * True when the presented token is the expected one. An empty expected token matches nothing, not
+ * even an empty presented token, so a server with an empty token refuses each network request.
+ * The comparison reads each character of the presented token one time, so its time depends only
+ * on what the caller sent. The time tells neither the expected token nor its length. The function
+ * runs in a browser too, so it uses no `node:crypto`.
  */
 export function tokenMatches(expected: string, presented: string | undefined): boolean {
   if (presented === undefined) return false;
-  // A difference of the lengths makes the result false, after the same loop as an equal length
-  let difference = expected.length ^ presented.length;
-  for (let index = 0; index < expected.length; index++) difference |= expected.charCodeAt(index) ^ (presented.charCodeAt(index) | 0);
+  // An empty expected token and a difference of the lengths make the result false, after the same
+  // loop as an equal length. The modulo reuses the expected characters for a longer token.
+  let difference = (expected.length === 0 ? 1 : 0) | (expected.length ^ presented.length);
+  for (let index = 0; index < presented.length; index++) difference |= presented.charCodeAt(index) ^ expected.charCodeAt(index % expected.length);
   return difference === 0;
 }
 

package/src/server/types.ts

@@ -388,12 +388,17 @@ export class HandlerNotFoundError extends Error {
  * before, the default was the string `"500"`).
  */
 export class ServerError extends Error {
+  public readonly code: string;
+  public readonly retryable: boolean;
+
   constructor(
     message: string,
-    public readonly code: string = "INTERNAL_ERROR",
-    public readonly retryable: boolean = false
+    code: string = "INTERNAL_ERROR",
+    retryable: boolean = false
   ) {
     super(message);
+    this.code = code;
+    this.retryable = retryable;
     this.name = "ServerError";
   }
 }

package/src/testing/transport-contract.ts

@@ -20,7 +20,7 @@
  * skips the cases of that feature. Each skip thus is data in the test file of the face.
  *
  * The suite is the entry point `@procedures/client/testing`, so a face in another package (and
- * a server of an app, for example Graph) runs the same cases with the client that it uses. The
+ * a server of an app) runs the same cases with the client that it uses. The
  * suite imports no test runner: the caller gives `describe`, `it`, `afterEach` and `expect`
  * (`ContractRunner`). Those of Vitest fit.
  */