@procedures/client 0.15.0 → 0.15.1

package/src/events/publisher.ts

@@ -18,6 +18,8 @@
  *
  * - 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.
+ * - An open subscription gets the same checks again at a change of the rights (`rightsChanged()`,
+ *   `recheck.rightsChanges`) and after `recheck.maxAge` (roadmap CLI-44). A refusal ends it.
  *
  * 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
@@ -36,6 +38,8 @@ 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";
+import { realClock, type Clock } from "../clock.js";
+import { SubscriptionRechecks, type RightsChange, type SubscriptionRecheck } from "./recheck.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -73,7 +77,8 @@ export interface EventPublisherOptions {
   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.
+   * full, the publisher drops the oldest event. The events that wait for a re-check (roadmap
+   * CLI-44) are in the same queue, so a slow check holds at most this number of events too.
    * @default 1024
    */
   buffer?: number | undefined;
@@ -89,6 +94,23 @@ export interface EventPublisherOptions {
    * @default the read of the collection of `collectionTopicTarget()`, with the repository of the call
    */
   reads?: ((topic: string) => readonly string[]) | undefined;
+  /**
+   * The clock of the re-check after `recheck.maxAge` (roadmap CLI-44). A test gives the
+   * `fakeClock` of `@mark1russell7/service/testing`. A `ProcedureServer` gives its own clock to the
+   * publisher that it makes from its option `events`.
+   * @default the clock of the platform
+   */
+  clock?: Clock | undefined;
+  /**
+   * The re-check of the admission of each open subscription (roadmap CLI-44). A right can change
+   * after the start of a subscription. The publisher then examines the subscription again with the
+   * same checks: the topic rule, the reads, `allow` and the partition. A refusal ends it, for
+   * example with `FORBIDDEN`. `maxAge` starts a check after a time on the clock, and
+   * `rightsChanges` starts a check at each change from a source of the app. `rightsChanged()` also
+   * starts a check.
+   * @default no check after the start, other than at a call of `rightsChanged()`
+   */
+  recheck?: SubscriptionRecheck | undefined;
 }
 
 /** A procedure that reads resources, for the admission of a topic under a capability. */
@@ -167,6 +189,10 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   private closed = false;
   private failure: unknown;
   private readonly unsubscribes: Unsubscribe[];
+  /** The re-check of the admission that runs (roadmap CLI-44). The events wait for it. */
+  private recheck: Promise<void> | undefined;
+  /** The functions that run when the subscription ends */
+  private readonly endListeners: Array<() => void> = [];
 
   constructor(
     bus: EventBus,
@@ -201,7 +227,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     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) {
+    if (waiter && this.queue.length === 0 && !this.recheck) {
       this.waiter = undefined;
       waiter.resolve(this.deliver(event));
       return;
@@ -239,6 +265,8 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
       this.confirmation = undefined;
       return Promise.resolve({ value: confirmation, done: false });
     }
+    // The events wait for a re-check of the admission (roadmap CLI-44)
+    if (this.recheck) return this.recheck.then(() => this.next());
     const event = this.queue.shift();
     if (event) return this.deliver(event);
     if (this.failure !== undefined) {
@@ -295,9 +323,51 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     for (const unsubscribe of this.unsubscribes) unsubscribe();
     this.signal?.removeEventListener("abort", this.onAbort);
     this.onClose(this);
+    for (const listener of this.endListeners.splice(0)) listener();
+  }
+
+  /**
+   * This function holds the events until the check ends (roadmap CLI-44). A check that passes gives
+   * the held events to the reader. A check that fails ends the subscription with its error, and the
+   * held events go. The promise ends when the check ends, and it does not reject.
+   */
+  hold(check: Promise<void>): Promise<void> {
+    if (this.closed) return check.then(ignore, ignore);
+    const running: Promise<void> = check.then(
+      () => {
+        if (this.recheck === running) this.recheck = undefined;
+        this.flush();
+      },
+      (error: unknown) => {
+        if (this.recheck === running) this.recheck = undefined;
+        this.queue.length = 0;
+        this.fail(error);
+      },
+    );
+    this.recheck = running;
+    return running;
+  }
+
+  /** This function runs the listener when the subscription ends, or at once after its end. */
+  onEnd(listener: () => void): void {
+    if (this.closed) listener();
+    else this.endListeners.push(listener);
+  }
+
+  /** This function gives the first held event to a reader that waits, after a check passes. */
+  private flush(): void {
+    const waiter = this.waiter;
+    const event = this.queue[0];
+    if (!waiter || !event || this.recheck) return;
+    this.waiter = undefined;
+    this.queue.shift();
+    waiter.resolve(this.deliver(event));
   }
 }
 
+/** This function does nothing: the end of a check of a closed subscription. */
+function ignore(): void {}
+
 /**
  * The publisher of the remote events: it serves `events.subscribe` from a bus, under a topic
  * rule. `ProcedureServer` makes one from its option `events`.
@@ -321,8 +391,11 @@ export class EventPublisher {
   private readonly defaultReads: boolean;
   private readonly buffer: number;
   private readonly open = new Set<TopicSubscription>();
+  /** The re-checks of the admission of the open subscriptions (roadmap CLI-44) */
+  private readonly rechecks: SubscriptionRechecks;
 
   constructor(options: EventPublisherOptions) {
+    this.rechecks = new SubscriptionRechecks(options.recheck ?? {}, options.clock ?? realClock);
     this.bus = options.bus ?? getGlobalEventBus();
     this.known = topicMatcher(options.topics);
     this.allow = options.allow;
@@ -360,6 +433,18 @@ export class EventPublisher {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
   }
 
+  /**
+   * This function tells the publisher that rights changed (roadmap CLI-44). Each open subscription
+   * that the change touches gets the checks of its start again: the topic rule, the reads, `allow`
+   * and the partition. Its events wait for the check. A refusal ends the subscription with its
+   * error, for example `FORBIDDEN`. The promise ends when each check ends, and it does not reject.
+   *
+   * @param change - The subscriptions that the change touches. Without it, each open subscription gets a check.
+   */
+  rightsChanged(change?: RightsChange): Promise<void> {
+    return this.rechecks.rightsChanged(change);
+  }
+
   /**
    * The topic of the bus for a topic of a subscriber (roadmap CLI-17). A topic of a partitioned
    * collection names the partition that the subscriber asks for, as the input of a procedure does:
@@ -385,11 +470,10 @@ export class EventPublisher {
   }
 
   /**
-   * The stream of one subscription. The publisher examines each topic before it adds a listener:
-   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
+   * The checks of the topics of a call: the topic rule, the reads of the capability and `allow`.
+   * A subscription passes them at its start and at each re-check (roadmap CLI-44).
    */
-  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
-    const unique = [...new Set(topics)];
+  private admitTopics(unique: readonly string[], ctx: ProcedureContext): void {
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
     }
@@ -408,10 +492,36 @@ export class EventPublisher {
         }
       }
     }
+  }
+
+  /**
+   * The admission of an open subscription again (roadmap CLI-44): the checks of its start, and the
+   * partition of each topic. A refusal of the resolver throws its error. A topic whose partition
+   * changed throws `FORBIDDEN` (reason `partition-not-allowed`), because the listener has the old
+   * partition.
+   */
+  private async readmit(routes: ReadonlyArray<readonly [string, string]>, ctx: ProcedureContext): Promise<void> {
+    this.admitTopics(routes.map(([topic]) => topic), ctx);
+    for (const [topic, busTopic] of routes) {
+      if ((await this.busTopic(topic, ctx)) !== busTopic) {
+        throw new InvocationError("FORBIDDEN", `The partition of the topic "${topic}" changed, so the subscription ends`, ctx.path, "partition-not-allowed");
+      }
+    }
+  }
+
+  /**
+   * The stream of one subscription. The publisher examines each topic before it adds a listener:
+   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
+   */
+  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
+    const unique = [...new Set(topics)];
+    this.admitTopics(unique, ctx);
     const routes: Array<readonly [string, string]> = [];
     for (const topic of unique) routes.push([topic, await this.busTopic(topic, ctx)]);
     const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit, ctx.invocation);
     this.open.add(subscription);
+    // The same checks run again at a change of the rights and after the max age (roadmap CLI-44)
+    this.rechecks.watch(subscription, ctx.principal, () => this.readmit(routes, ctx));
     return subscription.closeIfAborted();
   }
 }

package/src/events/recheck.ts

@@ -0,0 +1,182 @@
+/**
+ * The re-check of the admission of the open subscriptions (roadmap CLI-44).
+ *
+ * At the start of a subscription, a publisher examines the rights of the subscriber. It examines
+ * the topic rule, the reads of the capability, `allow` and the partition. A right can change
+ * later, for example when the app removes a user from a group. Thus the publisher examines each
+ * open subscription again:
+ *
+ * - At a change of the rights. The host uses `rightsChanged()` of the publisher, or the source of
+ *   the option `recheck.rightsChanges` gives the change to its listener.
+ * - After the time `recheck.maxAge` on the clock of the publisher, from the last check.
+ *
+ * The check is the same function as at the start. While it operates, the events of the
+ * subscription wait. A refusal ends the subscription with its error, for example `FORBIDDEN`, and
+ * the events that wait go. Without a call of `rightsChanged()` and without the option, nothing
+ * changes.
+ */
+
+import type { Cancel, Clock } from "../clock.js";
+import { toMs, type Duration } from "../duration.js";
+import type { Principal } from "../server/types.js";
+
+/**
+ * The subscriptions that a change of the rights touches: the id of a principal, or a test of the
+ * principal of a subscription. A subscription without a principal (a call from this process) has
+ * no id, so only a test or a change of each subscription touches it.
+ */
+export type RightsChange = string | ((principal: Principal | undefined) => boolean);
+
+/** The options of the re-check of the open subscriptions of a publisher (roadmap CLI-44). */
+export interface SubscriptionRecheck {
+  /**
+   * The longest time from one check of a subscription to the next check, for example `minutes(1)`.
+   * The time is on the clock of the publisher. Without it, only a change of the rights starts a
+   * check.
+   */
+  readonly maxAge?: Duration | undefined;
+  /**
+   * The source of the changes of the rights of the app. While the publisher has an open
+   * subscription, the source has one listener of the publisher. The source gives the function that
+   * removes the listener. Each call of the listener is a call of `rightsChanged()`: without a
+   * change, each subscription gets a check.
+   */
+  readonly rightsChanges?: ((listener: (change?: RightsChange) => void) => () => void) | undefined;
+}
+
+/** A subscription that the re-checks can hold and watch. */
+export interface RecheckedSubscription {
+  /**
+   * This function holds the events of the subscription until the check ends. A refusal ends the
+   * subscription with its error. The promise ends with the check, and it does not reject.
+   */
+  hold(check: Promise<void>): Promise<void>;
+  /** This function runs the listener when the subscription ends. */
+  onEnd(listener: () => void): void;
+}
+
+/** One subscription that the re-checks watch. */
+interface Watch {
+  readonly principal: Principal | undefined;
+  /** The timer of the max age, or undefined. */
+  timer: Cancel | undefined;
+  /** This function starts a check at once. The promise ends when the check ends. */
+  readonly recheck: () => Promise<void>;
+}
+
+/** True when the change touches a subscription of the principal. A test that throws touches it. */
+function touches(change: RightsChange | undefined, principal: Principal | undefined): boolean {
+  if (change === undefined) return true;
+  if (typeof change === "string") return principal?.id === change;
+  try {
+    return change(principal);
+  } catch {
+    return true;
+  }
+}
+
+/** The promise of a check. A check that throws at once gives a rejected promise. */
+function started(check: () => Promise<void>): Promise<void> {
+  return new Promise<void>((resolve) => resolve(check()));
+}
+
+/**
+ * The re-checks of the open subscriptions of one publisher (roadmap CLI-44). The publisher gives
+ * each new subscription to `watch()`, with the check of its admission.
+ */
+export class SubscriptionRechecks {
+  private readonly watches = new Set<Watch>();
+  private readonly maxAgeMs: number | undefined;
+  private readonly source: SubscriptionRecheck["rightsChanges"];
+  /** The function that removes the listener of the source, while a subscription is open */
+  private stopListening: (() => void) | undefined;
+
+  constructor(
+    options: SubscriptionRecheck,
+    private readonly 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`);
+    }
+    this.maxAgeMs = maxAgeMs;
+    this.source = options.rightsChanges;
+  }
+
+  /** The number of the subscriptions that the re-checks watch. */
+  get size(): number {
+    return this.watches.size;
+  }
+
+  /**
+   * This function watches a subscription until it ends. A change of the rights of its principal
+   * and its max age start the check. The check must throw the refusal.
+   */
+  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: () => Promise<void>): void {
+    const watch: Watch = {
+      principal,
+      timer: undefined,
+      recheck: () => {
+        this.stopTimer(watch);
+        return subscription.hold(started(check)).then(() => {
+          // A check that passes gives the admission a new age
+          if (this.watches.has(watch)) this.startTimer(watch);
+        });
+      },
+    };
+    this.watches.add(watch);
+    subscription.onEnd(() => this.unwatch(watch));
+    if (!this.watches.has(watch)) return;
+    this.startTimer(watch);
+    if (this.source && !this.stopListening) {
+      try {
+        this.stopListening = this.source((change) => void this.rightsChanged(change));
+      } catch (error) {
+        // A source that cannot listen cannot tell a revocation: the subscription ends
+        void subscription.hold(Promise.reject(error));
+      }
+    }
+  }
+
+  /**
+   * This function starts a check of each watched subscription that the change touches. The
+   * promise ends when each check ends.
+   */
+  rightsChanged(change?: RightsChange): Promise<void> {
+    const checks: Array<Promise<void>> = [];
+    for (const watch of [...this.watches]) {
+      if (touches(change, watch.principal)) checks.push(watch.recheck());
+    }
+    return Promise.all(checks).then(() => undefined);
+  }
+
+  /** This function stops the watch of a subscription that ended. */
+  private unwatch(watch: Watch): void {
+    this.stopTimer(watch);
+    if (!this.watches.delete(watch) || this.watches.size > 0) return;
+    // The last subscription ended: the publisher does not listen to the source
+    const stop = this.stopListening;
+    this.stopListening = undefined;
+    stop?.();
+  }
+
+  /** This function starts the timer of the max age of a subscription. */
+  private startTimer(watch: Watch): void {
+    if (this.maxAgeMs === undefined) return;
+    this.stopTimer(watch);
+    const timer = this.clock.after(this.maxAgeMs, () => {
+      if (watch.timer === timer) watch.timer = undefined;
+      void watch.recheck();
+    });
+    // A check does not keep a Node process alive
+    timer.unref?.();
+    watch.timer = timer;
+  }
+
+  /** This function stops the timer of the max age of a subscription. */
+  private stopTimer(watch: Watch): void {
+    const timer = watch.timer;
+    watch.timer = undefined;
+    timer?.();
+  }
+}

package/src/protocol.ts

@@ -49,7 +49,8 @@ export type ProtocolErrorCode =
   | "CONNECTION_NOT_FOUND"
   | "TOPIC_NOT_FOUND"
   | "TOPIC_CLEARED"
-  | "VERSION_CONFLICT";
+  | "VERSION_CONFLICT"
+  | "RATE_LIMITED";
 
 /**
  * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
@@ -82,6 +83,7 @@ export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
   TOPIC_NOT_FOUND: { http: 404, retryable: false, meaning: "The topic rule of the host has no topic with this name" },
   TOPIC_CLEARED: { http: 410, retryable: false, meaning: "The host cleared a topic of the subscription: clear() of its bus removed the listener" },
   VERSION_CONFLICT: { http: 409, retryable: false, meaning: "The current item does not have the version that the write expects. The metadata key conflicts has the current items" },
+  RATE_LIMITED: { http: 429, retryable: true, meaning: "A limit of the host refuses the call. The metadata key retry-after gives the wait, and reason gives the cause" },
 };
 
 /** True when a code is an error code of the protocol. */

package/src/server/host-policy.ts

@@ -18,6 +18,8 @@
  *   call and what the host gives for it (CAPABILITIES-2026-10).
  * - `events`: the remote events of the host (`documentation/EVENTS.md`). The server pins
  *   `events.subscribe` with this topic rule, and its procedures get the bus as `ctx.bus`.
+ * - `limits`, `limitStores`: the limits of the calls (CLI-40). Each server of the policy makes one
+ *   keyed limiter for each limit, and refuses a call above a limit with `RATE_LIMITED`.
  */
 
 import type { Capability, ClearanceOrder, ProcedurePath, ResourcesOf } from "../procedures/types.js";
@@ -30,6 +32,8 @@ import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { ProcedureServerOptions } from "./procedure-server.js";
 import type { EventPublisherOptions } from "../events/publisher.js";
 import { toMs, type Duration } from "../duration.js";
+import type { LimiterStore } from "@mark1russell7/service/limiter";
+import type { CallLimit } from "./limits.js";
 
 /** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
 export interface ToolSurface {
@@ -102,6 +106,15 @@ export interface HostPolicyOptions {
    * `ctx.bus`. Without this option, the host does not serve `events.subscribe`.
    */
   events?: EventPublisherOptions | undefined;
+  /**
+   * The limits of the calls (CLI-40): each limit counts the calls of one key, for example the
+   * writes of each tenant. A refusal is `RATE_LIMITED` on each face. Without it: no limits.
+   * Each limit that covers a call takes one unit, in the sequence of the limits. A limit before a
+   * refusal keeps its unit: the server does not give it back.
+   */
+  limits?: readonly CallLimit[] | undefined;
+  /** The stores that the replicas share, by the name of their dependency, for the limits with a shared store. */
+  limitStores?: Readonly<Record<string, LimiterStore>> | undefined;
 }
 
 /** What a host lets its callers do. */
@@ -120,6 +133,10 @@ export interface HostPolicy {
   readonly admitItem: AdmitItem | undefined;
   /** The remote events: each server of the policy makes its own publisher from these options. */
   readonly events: EventPublisherOptions | undefined;
+  /** The limits of the calls (CLI-40). Each server of the policy makes its own keyed limiters from them. */
+  readonly limits?: readonly CallLimit[] | undefined;
+  /** The shared stores of the limits, by the name of their dependency. */
+  readonly limitStores?: Readonly<Record<string, LimiterStore>> | undefined;
 }
 
 /** The capability function of a policy: the capability of the options, narrowed by `readOnly`. */
@@ -167,6 +184,8 @@ export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
     resources: options.resources,
     admitItem: options.admitItem,
     events: options.events,
+    ...(options.limits && options.limits.length > 0 ? { limits: options.limits } : {}),
+    ...(options.limitStores ? { limitStores: options.limitStores } : {}),
   };
 }
 
@@ -188,5 +207,8 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     ...(policy.admitItem ? { admitItem: policy.admitItem } : {}),
     // The remote events: the server makes its publisher and pins events.subscribe (EVENTS.md)
     ...(policy.events ? { events: policy.events } : {}),
+    // The limits of the calls: the server makes one keyed limiter for each one (CLI-40)
+    ...(policy.limits ? { limits: policy.limits } : {}),
+    ...(policy.limitStores ? { limitStores: policy.limitStores } : {}),
   };
 }