@procedures/client 0.15.0 → 0.16.0

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

@@ -5,13 +5,20 @@
  * Prevents overwhelming services with too many requests.
  *
  * Works with both client and server!
+ *
+ * The bucket is a keyed limiter of `@mark1russell7/service/limiter` (CLI-40): the same primitive
+ * as the limits of the procedures server. Its policy is a token bucket of `maxRequests` tokens
+ * that refills `maxRequests` tokens in each `window`, as before.
  */
 
+import { valueIn, type Quantity } from "@mark1russell7/quantity";
+import { keyedLimiter, memoryStore, type Decision, type LimitRule } from "@mark1russell7/service/limiter";
 import type { ClientMiddleware, ClientRunner, ClientContext, TypedClientMiddleware } from "../types.js";
 import type { RateLimitContext } from "./contexts.js";
 import { abortedItem } from "./items.js";
 import { optionalMs, type Duration } from "../../duration.js";
 import { TIMER_DEFAULTS } from "../../timers.js";
+import type { Cancel, Clock } from "../../clock.js";
 
 /**
  * Rate limiting options.
@@ -19,12 +26,18 @@ import { TIMER_DEFAULTS } from "../../timers.js";
 export interface RateLimitOptions {
   /**
    * Maximum number of requests per time window.
+   *
+   * Kept for compatibility: a value below 1 never lets a request in, and a value above 1 that is
+   * not whole gives a bucket of that size. An infinite value limits nothing.
    * @default 100
    */
   maxRequests?: number;
 
   /**
    * Time window in milliseconds.
+   *
+   * Kept for compatibility: a window of 0 or less fills the bucket again at each request, so a
+   * `maxRequests` of 1 or more limits nothing.
    * @default 60000 (1 minute)
    */
   window?: Duration;
@@ -52,6 +65,13 @@ export interface RateLimitOptions {
    * Callback when rate limit is exceeded.
    */
   onRateLimitExceeded?: (stats: RateLimitStats) => void;
+
+  /**
+   * The clock of the limiter: the time of the bucket and the timer of the queue (CLI-40). The
+   * default reads `Date.now()` and starts its timer with `setTimeout`, as before, so a queued
+   * request keeps a process alive. A test gives a fake clock.
+   */
+  clock?: Clock | undefined;
 }
 
 /**
@@ -86,6 +106,74 @@ interface QueuedRequest {
   timestamp: number;
 }
 
+/** The name of the keyed limiter of a middleware. Each middleware has its own store, so the name is the same for each one. */
+const LIMITER = "client.rateLimit";
+/** The one key of the bucket of a middleware. */
+const KEY = "client";
+
+/**
+ * The clock of a limiter without the option `clock`: `Date.now()` from the start of the
+ * middleware, and `setTimeout`. Thus the bucket reads the same time as before, and a queued
+ * request keeps a Node process alive until it runs.
+ */
+function wallClock(): Clock {
+  const origin = Date.now();
+  return {
+    now: () => Date.now() - origin,
+    after(delay: number, run: () => void): Cancel {
+      const timer = setTimeout(run, Math.max(0, delay));
+      return () => clearTimeout(timer);
+    },
+  };
+}
+
+/** This function gives a wait in milliseconds as a quantity. */
+const msOf = (value: number): Quantity => ({ value, unit: "ms" });
+
+/**
+ * This function gives the take of the bucket of the options. The take decides at once, without a
+ * promise.
+ *
+ * - A whole `maxRequests` of 1 or more and a `window` above 0: a keyed limiter of the service on a
+ *   memory store (CLI-40). Its token bucket gives `maxRequests` takes at once, and one more take
+ *   each `window / maxRequests`.
+ * - Kept for compatibility: a `maxRequests` above 1 that is not whole gives the same store with a
+ *   bucket of that size. The keyed limiter refuses such a spec, so the rule is given in numbers.
+ * - Kept for compatibility: a `window` of 0 or less fills the bucket again at each request. Thus a
+ *   `maxRequests` of 1 or more limits nothing.
+ * - Kept for compatibility: a `maxRequests` below 1 never lets a request in. A queued request
+ *   waits without an end, and the timer of the queue keeps a process alive, as before.
+ * - Kept for compatibility: an infinite `maxRequests` limits nothing.
+ */
+function bucketOf(maxRequests: number, window: number, clock: Clock): () => Decision {
+  if (window <= 0 && maxRequests >= 1) {
+    const remaining = Math.floor(maxRequests - 1);
+    return () => ({ allowed: true, remaining });
+  }
+  if (!(maxRequests >= 1)) {
+    // The wait of the queue before CLI-40: the time until one token, or 1 ms when it has no value
+    const wait = ((1 - maxRequests) * window) / maxRequests;
+    const waitMs = Number.isFinite(wait) && wait > 1 ? wait : 1;
+    return () => ({ allowed: false, retryAfter: msOf(waitMs), cause: "limit" });
+  }
+  if (maxRequests === Number.POSITIVE_INFINITY) return () => ({ allowed: true, remaining: Number.POSITIVE_INFINITY });
+  const store = memoryStore(clock);
+  const rule: LimitRule = Number.isInteger(maxRequests)
+    ? keyedLimiter(
+        LIMITER,
+        {
+          key: KEY,
+          policy: { type: "token-bucket", rate: { value: maxRequests / window, unit: "count/ms" }, burst: { value: maxRequests, unit: "count" } },
+          store: { kind: "local" },
+          evict: { maxKeys: { value: 1, unit: "count" } },
+        },
+        store,
+      ).rule
+    : { type: "token-bucket", interval: window / maxRequests, burst: maxRequests };
+  // The memory store decides in one step without a promise
+  return () => store.take({ limiter: LIMITER, key: KEY, rule, maxKeys: 1 }) as Decision;
+}
+
 /**
  * Create rate limiting middleware using token bucket algorithm.
  *
@@ -121,34 +209,22 @@ export function createRateLimitMiddleware(
     onRateLimitExceeded,
   } = options;
   const window = optionalMs(options.window, "window") ?? TIMER_DEFAULTS.rateLimit.windowMs;
-
-  // Token bucket state
-  let tokens = maxRequests;
-  let lastRefill = Date.now();
+  const clock = options.clock ?? wallClock();
+  const takeOfBucket = bucketOf(maxRequests, window, clock);
   let totalRequests = 0;
   let rejectedRequests = 0;
+  /** The whole tokens after the last decision: `remaining` of a take, or 0 after a refusal. */
+  let tokensAvailable = maxRequests;
 
   // Queue for "queue" strategy
   const queue: QueuedRequest[] = [];
-  let drainTimer: ReturnType<typeof setTimeout> | undefined;
+  let drainTimer: Cancel | undefined;
 
-  /**
-   * Refill tokens based on elapsed time.
-   */
-  function refillTokens(): void {
-    const now = Date.now();
-    const elapsed = now - lastRefill;
-
-    if (elapsed >= window) {
-      // Full refill
-      tokens = maxRequests;
-      lastRefill = now;
-    } else {
-      // Partial refill (tokens per millisecond * elapsed time)
-      const tokensToAdd = (maxRequests / window) * elapsed;
-      tokens = Math.min(maxRequests, tokens + tokensToAdd);
-      lastRefill = now;
-    }
+  /** One take of the bucket, at once, so the requests keep their order, as before. */
+  function take(): Decision {
+    const decision = takeOfBucket();
+    tokensAvailable = decision.allowed ? decision.remaining : 0;
+    return decision;
   }
 
   /**
@@ -156,7 +232,7 @@ export function createRateLimitMiddleware(
    */
   function getStats(): RateLimitStats {
     return {
-      tokensAvailable: Math.floor(tokens),
+      tokensAvailable,
       maxTokens: maxRequests,
       queueSize: queue.length,
       totalRequests,
@@ -170,11 +246,8 @@ export function createRateLimitMiddleware(
    * an arrival could take the token of a queued request (deep dive TRN-12).
    */
   async function acquireToken(signal?: AbortSignal): Promise<boolean> {
-    refillTokens();
-
-    if (queue.length === 0 && tokens >= 1) {
+    if (queue.length === 0 && take().allowed) {
       // Token available
-      tokens -= 1;
       return true;
     }
 
@@ -207,7 +280,7 @@ export function createRateLimitMiddleware(
           signal?.removeEventListener("abort", onAbort);
           resolve(true);
         },
-        timestamp: Date.now(),
+        timestamp: clock.now(),
       };
       // A queued request whose caller aborts leaves the queue (before, it kept its place)
       const onAbort = (): void => {
@@ -223,23 +296,25 @@ export function createRateLimitMiddleware(
 
   /**
    * Give tokens to the queued requests, in order, and wait for the next token while the queue
-   * is not empty. The timer keeps the process alive while requests wait: before, an unref'd
-   * timer let the process exit with queued requests that never ran (deep dive TRN-12).
+   * is not empty. The wait is the `retryAfter` of the refusal of the bucket. The timer of the
+   * default clock keeps the process alive while requests wait: before, an unref'd timer let the
+   * process exit with queued requests that never ran (deep dive TRN-12).
    */
   function scheduleDrain(): void {
     if (drainTimer !== undefined) return;
-    refillTokens();
-    while (queue.length > 0 && tokens >= 1) {
-      tokens -= 1;
+    while (queue.length > 0) {
+      const decision = take();
+      if (!decision.allowed) {
+        // The time until the next whole token
+        const wait = Math.max(1, Math.ceil(valueIn(decision.retryAfter, "ms")));
+        drainTimer = clock.after(wait, () => {
+          drainTimer = undefined;
+          scheduleDrain();
+        });
+        return;
+      }
       queue.shift()!.resolve();
     }
-    if (queue.length === 0) return;
-    // The time until the next whole token
-    const wait = Math.max(1, Math.ceil(((1 - tokens) * window) / maxRequests));
-    drainTimer = setTimeout(() => {
-      drainTimer = undefined;
-      scheduleDrain();
-    }, wait);
   }
 
   const middleware = <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
@@ -253,7 +328,7 @@ export function createRateLimitMiddleware(
       }
       // The state for the other middlewares (RateLimitContext)
       context.message.metadata["rateLimit"] = {
-        tokensAvailable: Math.floor(tokens),
+        tokensAvailable,
         maxTokens: maxRequests,
         queueSize: queue.length,
       };

package/src/events/index.ts

@@ -59,6 +59,7 @@ export {
 // 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 type { RightsChange, SubscriptionRecheck } from "./recheck.js";
 export { EVENTS_SUBSCRIBE_PATH, SubscriptionError, remoteEvents, subscribeRemote } from "./remote.js";
 export type {
   EventItem,

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;
@@ -86,9 +91,26 @@ export interface EventPublisherOptions {
    * collection that the publisher listens to: the collection of `collectionTopicTarget(topic,
    * repository)` with the repository of the host. A function that reads the first part of the
    * topic alone checks `collection:a` for the dotted collection `a.b`.
-   * @default the read of the collection of `collectionTopicTarget()`, with the repository of the call
+   * @default `collectionTopicReads(topic, repository)`: 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:
@@ -374,22 +459,20 @@ export class EventPublisher {
   }
 
   /**
-   * The resources that a subscriber of a topic reads. The default reads the collection of the
-   * topic with the rule of the listener (`collectionTopicTarget`), so the read check and the
-   * listener name the same collection.
+   * The resources that a subscriber of a topic reads. The default (`collectionTopicReads`) reads
+   * the collection of the topic with the rule of the listener (`collectionTopicTarget`) and the
+   * repository of the call, so the read check and the listener name the same collection.
    */
   private readsOf(topic: string, ctx: ProcedureContext): readonly string[] {
     if (!this.defaultReads) return this.reads(topic);
-    const target = collectionTopicTarget(topic, ctx.repository);
-    return target ? [`collection:${target.collection}`] : [];
+    return collectionTopicReads(topic, ctx.repository);
   }
 
   /**
-   * 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 +491,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?.();
+  }
+}