@procedures/client 0.7.0 → 0.8.1

package/src/events/bus.ts

@@ -11,8 +11,11 @@ import type {
   EventHandler,
   Unsubscribe,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
 } from "./types.js";
+import { realClock, type Clock } from "../clock.js";
+import { toMs, type Duration } from "../duration.js";
 
 /** The error of a wait that its signal ended. */
 function abortedError(channel: string): Error {
@@ -21,6 +24,16 @@ function abortedError(channel: string): Error {
   return error;
 }
 
+/**
+ * The error of a wait that `clear()` ended. Its name is `AbortError`, so code that ignores a
+ * cancelled wait ignores this one too.
+ */
+function clearedError(channel: string): Error {
+  const error = new Error(`The wait on channel "${channel}" ended, because clear() removed the channel`);
+  error.name = "AbortError";
+  return error;
+}
+
 // =============================================================================
 // Event Bus Implementation
 // =============================================================================
@@ -32,8 +45,11 @@ function abortedError(channel: string): Error {
 export class DefaultEventBus implements EventBus {
   private readonly subscribers = new Map<string, Set<EventHandler<unknown>>>();
   private readonly buffer = new Map<string, unknown[]>();
-  /** For each channel, a function per open stream that ends it (for `clear()`). */
-  private readonly streamEnders = new Map<string, Set<() => void>>();
+  /**
+   * 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>;
 
   constructor(options: EventBusOptions = {}) {
@@ -85,9 +101,10 @@ export class DefaultEventBus implements EventBus {
   }
 
   /**
-   * Subscribe to events on a channel.
+   * 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.
    */
-  on<T>(channel: string, handler: EventHandler<T>): Unsubscribe {
+  on<T>(channel: string, handler: EventHandler<T>, options: EventListenOptions = {}): Unsubscribe {
     if (this.options.debug) {
       console.log(`[EventBus] subscribe "${channel}"`);
     }
@@ -100,6 +117,30 @@ export class DefaultEventBus implements EventBus {
 
     channelSubs.add(handler as EventHandler<unknown>);
 
+    // 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.)
+    // A clear() also ends the handler: then its unsubscribe does nothing.
+    let subscribed = true;
+    const { onClear } = options;
+    let cleared: (() => void) | undefined;
+    if (onClear) {
+      cleared = () => {
+        if (!subscribed) return;
+        subscribed = false;
+        try {
+          onClear();
+        } catch (error) {
+          this.options.onError(error instanceof Error ? error : new Error(String(error)), channel);
+        }
+      };
+      let handlers = this.clearHandlers.get(channel);
+      if (!handlers) {
+        handlers = new Set();
+        this.clearHandlers.set(channel, handlers);
+      }
+      handlers.add(cleared);
+    }
+
     // Replay buffered events if any
     const buffered = this.buffer.get(channel);
     if (buffered && buffered.length > 0) {
@@ -115,9 +156,6 @@ export class DefaultEventBus implements EventBus {
       }
     }
 
-    // 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.)
-    let subscribed = true;
     return () => {
       if (!subscribed) return;
       subscribed = false;
@@ -130,9 +168,23 @@ export class DefaultEventBus implements EventBus {
       if (channelSubs.size === 0 && this.subscribers.get(channel) === channelSubs) {
         this.subscribers.delete(channel);
       }
+      if (cleared) {
+        const handlers = this.clearHandlers.get(channel);
+        if (handlers?.delete(cleared) && handlers.size === 0) this.clearHandlers.delete(channel);
+      }
     };
   }
 
+  /** This function runs the clear handlers of the channels, after it removed them from the bus. */
+  private runClearHandlers(channels: readonly string[]): void {
+    const handlers: Array<() => void> = [];
+    for (const channel of channels) {
+      handlers.push(...(this.clearHandlers.get(channel) ?? []));
+      this.clearHandlers.delete(channel);
+    }
+    for (const cleared of handlers) cleared();
+  }
+
   /**
    * Subscribe to a single event on a channel. On a buffered channel, the first buffered event
    * resolves the promise. When the signal aborts first, the promise rejects with an `AbortError`.
@@ -153,14 +205,26 @@ export class DefaultEventBus implements EventBus {
         reject(abortedError(channel));
       };
       // on() can replay a buffered event before it returns: the handler must not need
-      // `unsubscribe` yet (before, it threw a ReferenceError, and the promise never settled)
-      unsubscribe = this.on<T>(channel, (data) => {
-        if (settled) return;
-        settled = true;
-        unsubscribe?.();
-        signal?.removeEventListener("abort", onAbort);
-        resolve(data);
-      });
+      // `unsubscribe` yet (before, it threw a ReferenceError, and the promise never settled).
+      // clear() rejects the wait: before, the promise never settled.
+      unsubscribe = this.on<T>(
+        channel,
+        (data) => {
+          if (settled) return;
+          settled = true;
+          unsubscribe?.();
+          signal?.removeEventListener("abort", onAbort);
+          resolve(data);
+        },
+        {
+          onClear: () => {
+            if (settled) return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            reject(clearedError(channel));
+          },
+        },
+      );
       if (settled) {
         unsubscribe();
         return;
@@ -182,23 +246,7 @@ export class DefaultEventBus implements EventBus {
         const queue: T[] = [];
         let resolve: ((value: IteratorResult<T>) => void) | null = null;
         let done = signal?.aborted ?? false;
-
-        // Subscribe to channel
-        const unsubscribe = done
-          ? () => {}
-          : self.on<T>(channel, (data) => {
-              if (done) return;
-
-              if (resolve) {
-                // Someone is waiting, resolve immediately
-                const r = resolve;
-                resolve = null;
-                r({ value: data, done: false });
-              } else {
-                // Queue for later
-                queue.push(data);
-              }
-            });
+        let unsubscribe: Unsubscribe = () => {};
 
         // End the stream: no more events, and a waiting reader gets `done`
         const end = (): void => {
@@ -206,19 +254,31 @@ export class DefaultEventBus implements EventBus {
           done = true;
           unsubscribe();
           signal?.removeEventListener("abort", end);
-          self.streamEnders.get(channel)?.delete(end);
           const r = resolve;
           resolve = null;
           r?.({ value: undefined, done: true });
         };
+
+        // Subscribe to channel. A clear() of the channel ends the stream.
         if (!done) {
+          unsubscribe = self.on<T>(
+            channel,
+            (data) => {
+              if (done) return;
+
+              if (resolve) {
+                // Someone is waiting, resolve immediately
+                const r = resolve;
+                resolve = null;
+                r({ value: data, done: false });
+              } else {
+                // Queue for later
+                queue.push(data);
+              }
+            },
+            { onClear: end },
+          );
           signal?.addEventListener("abort", end, { once: true });
-          let enders = self.streamEnders.get(channel);
-          if (!enders) {
-            enders = new Set();
-            self.streamEnders.set(channel, enders);
-          }
-          enders.add(end);
         }
 
         return {
@@ -276,7 +336,8 @@ export class DefaultEventBus implements EventBus {
   }
 
   /**
-   * Remove all subscribers from a channel.
+   * Remove all subscribers from a channel. The `onClear` of each removed handler runs, and each
+   * stream of the channel ends.
    */
   clear(channel: string): void {
     if (this.options.debug) {
@@ -284,13 +345,14 @@ export class DefaultEventBus implements EventBus {
     }
     this.subscribers.delete(channel);
     this.buffer.delete(channel);
-    // The streams of the channel end: before, their readers waited forever (deep dive CORE-15)
-    for (const end of [...(this.streamEnders.get(channel) ?? [])]) end();
-    this.streamEnders.delete(channel);
+    // The streams of the channel end: before, their readers waited forever (deep dive CORE-15).
+    // The remote subscriptions end with notice too (EVENTS.md).
+    this.runClearHandlers([channel]);
   }
 
   /**
-   * Remove all subscribers from all channels.
+   * Remove all subscribers from all channels. The `onClear` of each removed handler runs, and
+   * each stream ends.
    */
   clearAll(): void {
     if (this.options.debug) {
@@ -298,10 +360,7 @@ export class DefaultEventBus implements EventBus {
     }
     this.subscribers.clear();
     this.buffer.clear();
-    for (const enders of [...this.streamEnders.values()]) {
-      for (const end of [...enders]) end();
-    }
-    this.streamEnders.clear();
+    this.runClearHandlers([...this.clearHandlers.keys()]);
   }
 }
 
@@ -398,7 +457,7 @@ export function withEventBusSignal(bus: EventBus, signal: AbortSignal): EventBus
   const waitOptions = (options?: EventWaitOptions): EventWaitOptions => ({ signal: options?.signal ?? signal });
   return {
     emit: (channel, data) => bus.emit(channel, data),
-    on: (channel, handler) => bus.on(channel, handler),
+    on: (channel, handler, options) => bus.on(channel, handler, options),
     once: (channel, options) => bus.once(channel, waitOptions(options)),
     stream: (channel, options) => bus.stream(channel, waitOptions(options)),
     subscriberCount: (channel) => bus.subscriberCount(channel),
@@ -435,8 +494,8 @@ export function createChannelPrefix(bus: EventBus, prefix: string) {
       bus.emit(prefixed(channel), data);
     },
 
-    on<T>(channel: string, handler: EventHandler<T>): Unsubscribe {
-      return bus.on(prefixed(channel), handler);
+    on<T>(channel: string, handler: EventHandler<T>, options?: EventListenOptions): Unsubscribe {
+      return bus.on(prefixed(channel), handler, options);
     },
 
     once<T>(channel: string, options?: EventWaitOptions): Promise<T> {
@@ -525,68 +584,77 @@ export function mapChannel<TIn, TOut>(
   });
 }
 
+/** Options of `debounceChannel()` and `throttleChannel()`. */
+export interface ChannelTimingOptions {
+  /** The clock of the timers. The default is the clock of the platform. A test gives a fake clock. */
+  clock?: Clock;
+}
+
 /**
- * Debounce events on a channel.
+ * This function sends the last event of `source` to `target` after `delay` without a new event
+ * (a debounce). The delay is a `Duration`, such as `ms(300)`. A plain number throws a `TypeError`.
  *
  * @param bus - Event bus
  * @param source - Source channel
  * @param target - Target channel
- * @param delay - Debounce delay in milliseconds
+ * @param delay - The time without an event before the send
  * @returns Unsubscribe function
  */
 export function debounceChannel<T>(
   bus: EventBus,
   source: string,
   target: string,
-  delay: number
+  delay: Duration,
+  options: ChannelTimingOptions = {},
 ): Unsubscribe {
-  let timer: ReturnType<typeof setTimeout> | null = null;
+  const delayMs = toMs(delay, "debounceChannel delay");
+  const clock = options.clock ?? realClock;
+  let cancel: (() => void) | null = null;
   let lastData: T | undefined;
 
   const unsub = bus.on<T>(source, (data) => {
     lastData = data;
-
-    if (timer) {
-      clearTimeout(timer);
-    }
-
-    timer = setTimeout(() => {
+    cancel?.();
+    cancel = clock.after(delayMs, () => {
+      cancel = null;
       if (lastData !== undefined) {
         bus.emit(target, lastData);
       }
-      timer = null;
-    }, delay);
+    });
   });
 
   return () => {
     unsub();
-    if (timer) {
-      clearTimeout(timer);
-    }
+    cancel?.();
+    cancel = null;
   };
 }
 
 /**
- * Throttle events on a channel.
+ * This function sends an event of `source` to `target` at most one time in each `interval` (a
+ * throttle). It drops the events between. The interval is a `Duration`, such as `seconds(1)`. A
+ * plain number throws a `TypeError`.
  *
  * @param bus - Event bus
  * @param source - Source channel
  * @param target - Target channel
- * @param interval - Throttle interval in milliseconds
+ * @param interval - The shortest time between two sends
  * @returns Unsubscribe function
  */
 export function throttleChannel<T>(
   bus: EventBus,
   source: string,
   target: string,
-  interval: number
+  interval: Duration,
+  options: ChannelTimingOptions = {},
 ): Unsubscribe {
-  let lastEmit = 0;
+  const intervalMs = toMs(interval, "throttleChannel interval");
+  const clock = options.clock ?? realClock;
+  let lastEmit: number | undefined;
 
   return bus.on<T>(source, (data) => {
-    const now = Date.now();
-
-    if (now - lastEmit >= interval) {
+    const now = clock.now();
+    if (lastEmit === undefined || now - lastEmit >= intervalMs) {
       lastEmit = now;
       bus.emit(target, data);
     }

package/src/events/index.ts

@@ -40,6 +40,7 @@ export type {
   ProcedureChannels,
   DefaultChannels,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
 } from "./types.js";
 
@@ -65,6 +66,7 @@ export type {
   RemoteEvent,
   RemoteEventHandler,
   RemoteEventsOptions,
+  ResubscribeBackoff,
   SubscribeInput,
   SubscribeOptions,
   Subscription,
@@ -81,3 +83,4 @@ export {
   debounceChannel,
   throttleChannel,
 } from "./bus.js";
+export type { ChannelTimingOptions } from "./bus.js";

package/src/events/publisher.ts

@@ -8,11 +8,17 @@
  *
  * - The topic rule (`topics`) is the expose rule of the topics. A topic outside it gives
  *   `TOPIC_NOT_FOUND`.
+ * - `reads` gives the resources that a subscriber of a topic reads. The capability of the call
+ *   must permit them, as for a procedure that reads them (roadmap CLI-15). By default, a topic
+ *   `collections.<name>` reads `collection:<name>`.
  * - `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.
  *
+ * - A value with rows (`withRows()`) reaches each subscriber through the output filter of its host
+ *   (`ctx.admit`): each row passes the filter, and the subscriber gets only the admitted rows.
+ *
  * 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.
@@ -21,10 +27,13 @@
 import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError } from "../procedures/invoke.js";
+import { capabilityRefusal } from "../procedures/capability.js";
+import { collectionTopicReads } from "../procedures/collection/changes.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";
+import { admittedValue, rowsOf } from "./rows.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -64,6 +73,18 @@ export interface EventPublisherOptions {
    * @default 1024
    */
   buffer?: number | undefined;
+  /**
+   * The resources that a subscriber of a topic reads (roadmap CLI-15). The publisher refuses a
+   * topic whose reads the capability of the call does not permit, as for a procedure that reads
+   * them: `FORBIDDEN` with the reason `effects-exceeded`.
+   * @default `collectionTopicReads`: a topic `collections.<name>` reads `collection:<name>`
+   */
+  reads?: ((topic: string) => readonly string[]) | undefined;
+}
+
+/** A procedure that reads resources, for the admission of a topic under a capability. */
+function topicReader(reads: readonly string[]): AnyProcedure {
+  return { path: [...EVENTS_SUBSCRIBE_PATH], metadata: { effects: { reads: [...reads], writes: [] } } } as unknown as AnyProcedure;
 }
 
 /** This function gives the test of a topic rule. */
@@ -92,6 +113,14 @@ function stoppedError(): Error {
   return Object.assign(new Error("The publisher of the events stops"), { code: "UNAVAILABLE", retryable: true });
 }
 
+/**
+ * The error that ends a subscription when `clear()` or `clearAll()` of the bus removes the
+ * listener of one of its topics. The subscriber does not resubscribe: the host removed the topic.
+ */
+function clearedError(topic: string): Error {
+  return Object.assign(new Error(`The host cleared the topic "${topic}", so the subscription ends`), { code: "TOPIC_CLEARED", retryable: false });
+}
+
 const topicSchema = z.string().min(1).max(MAX_TOPIC_LENGTH);
 
 const subscribeInput = z.object({
@@ -115,14 +144,17 @@ const eventItemSchema = z.discriminatedUnion("type", [
 /**
  * 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.
+ * `fail()` remove the listeners. When `clear()` of the bus removes a listener, the subscription
+ * gives the events of its queue, and then it ends with `TOPIC_CLEARED`.
  */
 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 waiter:
+    | { resolve: (result: IteratorResult<EventItem> | PromiseLike<IteratorResult<EventItem>>) => void; reject: (error: unknown) => void }
+    | undefined;
   private closed = false;
   private failure: unknown;
   private readonly unsubscribes: Unsubscribe[];
@@ -133,9 +165,14 @@ 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,
   ) {
     this.confirmation = { type: "subscribed", topics };
-    this.unsubscribes = topics.map((topic) => bus.on(topic, (data) => this.push(topic, data)));
+    // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
+    this.unsubscribes = topics.map((topic) =>
+      bus.on(topic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
+    );
     signal?.addEventListener("abort", this.onAbort, { once: true });
   }
 
@@ -154,7 +191,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     const waiter = this.waiter;
     if (waiter && this.queue.length === 0) {
       this.waiter = undefined;
-      waiter.resolve({ value: this.withDropped(event), done: false });
+      waiter.resolve(this.deliver(event));
       return;
     }
     if (this.queue.length >= this.buffer) {
@@ -165,6 +202,16 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     this.queue.push(event);
   }
 
+  /**
+   * The item of an event for the subscriber. The rows of its data pass the output filter of the
+   * host for this subscriber, and the subscriber gets only the admitted rows.
+   */
+  private deliver(event: Extract<EventItem, { type: "event" }>): Promise<IteratorResult<EventItem>> {
+    const item = this.withDropped(event) as Extract<EventItem, { type: "event" }>;
+    if (!this.admit || !rowsOf(item.data)) return Promise.resolve({ value: item, done: false });
+    return admittedValue(item.data, this.admit).then((data): IteratorResult<EventItem> => ({ value: { ...item, data }, done: false }));
+  }
+
   /** 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;
@@ -180,7 +227,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
       return Promise.resolve({ value: confirmation, done: false });
     }
     const event = this.queue.shift();
-    if (event) return Promise.resolve({ value: this.withDropped(event), done: false });
+    if (event) return this.deliver(event);
     if (this.failure !== undefined) {
       const failure = this.failure;
       this.failure = undefined;
@@ -201,14 +248,19 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     return this;
   }
 
-  /** This function ends the subscription with an error: the reader gets it at its next item. */
-  fail(error: unknown): void {
+  /**
+   * This function ends the subscription with an error: the reader gets it at its next item. With
+   * `keepQueue`, the reader first gets the confirmation and the events of the queue.
+   */
+  fail(error: unknown, options: { keepQueue?: boolean } = {}): void {
     if (this.closed) return;
     const waiter = this.waiter;
     this.waiter = undefined;
     this.release();
-    this.queue.length = 0;
-    this.confirmation = undefined;
+    if (!options.keepQueue) {
+      this.queue.length = 0;
+      this.confirmation = undefined;
+    }
     if (waiter) waiter.reject(error);
     else this.failure = error;
   }
@@ -251,6 +303,7 @@ export class EventPublisher {
   readonly procedure: AnyProcedure;
   private readonly known: (topic: string) => boolean;
   private readonly allow: EventPublisherOptions["allow"];
+  private readonly reads: (topic: string) => readonly string[];
   private readonly buffer: number;
   private readonly open = new Set<TopicSubscription>();
 
@@ -258,6 +311,7 @@ export class EventPublisher {
     this.bus = options.bus ?? getGlobalEventBus();
     this.known = topicMatcher(options.topics);
     this.allow = options.allow;
+    this.reads = options.reads ?? collectionTopicReads;
     this.buffer = Math.max(1, Math.floor(options.buffer ?? 1024));
     this.procedure = createProcedure()
       .path([...EVENTS_SUBSCRIBE_PATH])
@@ -299,6 +353,13 @@ export class EventPublisher {
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
     }
+    // A subscriber of a topic reads its resources: the capability of the call must permit them
+    for (const topic of unique) {
+      const reads = this.reads(topic);
+      if (reads.length === 0) continue;
+      const refusal = capabilityRefusal(topicReader(reads), ctx.capability);
+      if (refusal) throw new InvocationError("FORBIDDEN", `The topic "${topic}": ${refusal.message}`, ctx.path, refusal.reason);
+    }
     if (this.allow) {
       const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata };
       for (const topic of unique) {
@@ -307,7 +368,7 @@ export class EventPublisher {
         }
       }
     }
-    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed));
+    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }