@procedures/client 0.8.0 → 0.9.0

package/src/client/client.ts

@@ -30,6 +30,7 @@ import type {
   Method,
   Metadata,
   Message,
+  ResponseItem,
   ClientMiddleware,
   ClientContext,
   ClientRunner,
@@ -56,8 +57,19 @@ import { RouteResolver, type ResolvedRoute, type RouteResolutionResult } from ".
 import { BatchExecutor, type ExecutionContext } from "./batch-executor.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { EventBus } from "../events/types.js";
+import {
+  remoteEvents,
+  subscribeRemote,
+  type EventTransport,
+  type RemoteEvent,
+  type RemoteEventHandler,
+  type RemoteEventsOptions,
+  type SubscribeOptions,
+  type Subscription,
+} from "../events/remote.js";
 import { narrowCapability } from "../procedures/capability.js";
-import { TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { DEADLINE_METADATA_KEY, TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { ms } from "../duration.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -169,6 +181,12 @@ function callerOf(options: ExecOptions): CallerContext {
   return caller;
 }
 
+/**
+ * The timeouts of a subscription: none. The timeout middleware takes 0 as "no timeout", so the
+ * timeouts of the client do not end a subscription, which has no end (roadmap CLI-15).
+ */
+const NO_SUBSCRIPTION_TIMEOUT = Object.freeze({ overall: ms(0), perAttempt: ms(0) });
+
 /**
  * Generate a unique message ID.
  */
@@ -221,6 +239,8 @@ export class Client<TContext = {}> {
   private readonly throwOnError: boolean;
   /** The bus of the local procedures. Undefined: the global bus. */
   private bus: EventBus | undefined;
+  /** The transport of the subscriptions through the middleware, made at the first subscription */
+  private subscriptionTransport: EventTransport | undefined;
   /** The interceptors of the local invocations (roadmap 1.2) */
   private interceptors: readonly Interceptor[] = [];
   /** The capability of the local invocations (CAPABILITIES-2026-10). Undefined: no limits. */
@@ -779,6 +799,68 @@ export class Client<TContext = {}> {
     }
   }
 
+  /**
+   * This method subscribes to topics of the event bus of the server (`documentation/EVENTS.md`).
+   * The call of `events.subscribe` goes through the middleware and the context of this client, as
+   * `stream()` does. Thus a token of the auth middleware goes with it. The subscriber resubscribes
+   * after a failure that a retry can repair, and the subscribers of the same topics share one call.
+   *
+   * A subscription has no deadline: the timeouts of the client (its timeout middleware, the
+   * `timeout` of its context and a `procedure-timeout` of its metadata) do not apply to it. For a
+   * deadline, give it in the metadata of the options, for example
+   * `{ metadata: { timeout: { overall: minutes(5) } } }`.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param handler - The handler of each event. A promise that it gives holds the next event.
+   * @param options - `onSubscribed`, `onError`, a signal, the metadata of the call, the resubscribe rules
+   * @returns The unsubscribe function, with the `ready` promise of the first confirmation
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.subscribe("collections.users", (event) => console.log(event));
+   * await unsubscribe.ready;
+   * unsubscribe();
+   * ```
+   */
+  subscribe<T = unknown>(topics: string | readonly string[], handler: RemoteEventHandler<T>, options: SubscribeOptions = {}): Subscription {
+    return subscribeRemote<T>(this.eventTransport(), topics, handler, options);
+  }
+
+  /**
+   * This method gives the events of topics of the event bus of the server as an async iterator,
+   * through the middleware of this client. A `break` or the signal ends the subscription. As for
+   * `subscribe()`, the timeouts of the client do not apply: the metadata of the options can give one.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param options - A signal, `onSubscribed`, the metadata of the call, the resubscribe rules
+   */
+  events<T = unknown>(topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
+    return remoteEvents<T>(this.eventTransport(), topics, options);
+  }
+
+  /**
+   * The transport of the subscriptions of this client: each call goes through the middleware, with
+   * the context of the client in its metadata. The subscriptions of one client share it, so they
+   * share their calls. The timeouts and the deadline of the client stay out: only the metadata of
+   * the subscription can give them.
+   */
+  private eventTransport(): EventTransport {
+    if (!this.subscriptionTransport) {
+      const send = <TReq, TRes>(message: Message<TReq>): AsyncIterable<ResponseItem<TRes>> => {
+        const metadata: Metadata = { ...this.defaultMetadata, ...(this.getEffectiveContext() as object) };
+        delete metadata["timeout"];
+        delete metadata[TIMEOUT_METADATA_KEY];
+        delete metadata[DEADLINE_METADATA_KEY];
+        metadata["timeout"] = NO_SUBSCRIPTION_TIMEOUT as unknown as NonNullable<Metadata["timeout"]>;
+        Object.assign(metadata, message.metadata);
+        absorbTimeout(metadata);
+        return this.composeMiddleware<TReq, TRes>()({ message: { ...message, metadata } });
+      };
+      this.subscriptionTransport = { send };
+    }
+    return this.subscriptionTransport;
+  }
+
   /**
    * Compose middleware chain using universal middleware composition.
    *

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,15 @@
 import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError } from "../procedures/invoke.js";
+import { capabilityRefusal } from "../procedures/capability.js";
+import { collectionChangeTopic, collectionTopicReads } from "../procedures/collection/changes.js";
+import { collectionTopicPartition, partitionOfCall } from "../procedures/collection/partition.js";
 import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/types.js";
+import type { Principal } from "../server/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;
@@ -44,6 +55,8 @@ export interface TopicCall {
   readonly capability: Capability;
   /** The metadata of the call: the connection id and the headers of a network request. */
   readonly metadata: Readonly<Record<string, unknown>>;
+  /** The principal of the call, from the authentication of the host. */
+  readonly principal?: Principal | undefined;
 }
 
 /** The options of an `EventPublisher`. */
@@ -64,6 +77,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. */
@@ -131,22 +156,27 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   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[];
 
   constructor(
     bus: EventBus,
-    topics: readonly string[],
+    /** The topics of the subscriber, each with the topic of the bus that it listens to */
+    routes: ReadonlyArray<readonly [topic: string, busTopic: string]>,
     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.confirmation = { type: "subscribed", topics: routes.map(([topic]) => topic) };
     // 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 }) }),
+    this.unsubscribes = routes.map(([topic, busTopic]) =>
+      bus.on(busTopic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
     );
     signal?.addEventListener("abort", this.onAbort, { once: true });
   }
@@ -166,7 +196,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) {
@@ -177,6 +207,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;
@@ -192,7 +232,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;
@@ -268,6 +308,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>();
 
@@ -275,6 +316,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])
@@ -307,24 +349,46 @@ export class EventPublisher {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
   }
 
+  /**
+   * 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:
+   * the resolver of the repository gives the partition, so a subscriber cannot name the topic of
+   * another tenant. A collection without partitions refuses a topic with a partition.
+   */
+  private async busTopic(topic: string, ctx: ProcedureContext): Promise<string> {
+    const parts = collectionTopicPartition(topic);
+    if (!parts) return topic;
+    const partition = await partitionOfCall(ctx, parts.collection, parts.partition);
+    return collectionChangeTopic(parts.collection, partition);
+  }
+
   /**
    * The stream of one subscription. The publisher examines each topic before it adds a listener:
-   * the topic rule first, then `allow`. A call with one bad topic makes no subscription.
+   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
    */
-  private subscribe(topics: readonly string[], ctx: ProcedureContext): TopicSubscription {
+  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
     const unique = [...new Set(topics)];
     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 };
+      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata, ...(ctx.principal ? { principal: ctx.principal } : {}) };
       for (const topic of unique) {
         if (!this.allow(topic, call)) {
           throw new InvocationError("FORBIDDEN", `The capability of the call does not permit the topic "${topic}"`, ctx.path, "topic-not-allowed");
         }
       }
     }
-    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed));
+    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);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }

package/src/events/rows.ts

@@ -0,0 +1,48 @@
+/**
+ * The rows of a published value (roadmap CLI-15).
+ *
+ * A value on the bus can hold rows of data: the values of a collection change event, for example.
+ * The publisher of the remote events gives each row to the output filter of the host (`admitItem`)
+ * for each subscriber, and each subscriber gets only the rows that its filter admits. Thus a row
+ * reaches a subscriber only through the same filter as a read.
+ *
+ * The rows are on a symbol key, so they stay in this process: JSON does not take them.
+ */
+
+/** The rows of a published value, and the function that makes the value of the admitted rows. */
+export interface PublishedRows {
+  /** The rows that the output filter examines, one at a time. */
+  readonly rows: readonly unknown[];
+  /** This function gives the value for a subscriber: `admitted[i]` tells if row `i` stays. */
+  keep(admitted: readonly boolean[]): unknown;
+}
+
+/** The key of the rows of a published value. */
+const ROWS: unique symbol = Symbol.for("procedures.publishedRows");
+
+/**
+ * This function gives the value with its rows, for the filter of each subscriber. The rows are not
+ * enumerable: a copy or a comparison of the value does not see them.
+ */
+export function withRows<T extends object>(value: T, rows: PublishedRows): T {
+  return Object.defineProperty(value, ROWS, { value: rows, enumerable: false });
+}
+
+/** The rows of a published value, or undefined for a value without rows. */
+export function rowsOf(value: unknown): PublishedRows | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const rows = (value as { [ROWS]?: unknown })[ROWS];
+  return typeof rows === "object" && rows !== null ? (rows as PublishedRows) : undefined;
+}
+
+/**
+ * The value of a published value for one subscriber: each row passes the filter, and the value
+ * keeps the admitted rows. An error of the filter refuses the row. Without rows or a filter, the
+ * value stays as it is.
+ */
+export async function admittedValue(value: unknown, admit: ((item: unknown) => Promise<boolean>) | undefined): Promise<unknown> {
+  const rows = rowsOf(value);
+  if (!rows || !admit) return value;
+  const admitted = await Promise.all(rows.rows.map((row) => admit(row).catch(() => false)));
+  return rows.keep(admitted);
+}

package/src/index.ts

@@ -27,7 +27,7 @@ export type {
   HttpUrlStrategy,
 } from "./server/index.js";
 export { WebSocketServerTransport } from "./server/index.js";
-export { checkBrowserRequest, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
+export { checkBrowserRequest, hasAmbientCredentials, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
 export type { BrowserGuardOptions, GuardedRequest, GuardResult } from "./server/browser-guard.js";
 export type {
   WebSocketServerTransportOptions,

package/src/node.ts

@@ -9,9 +9,30 @@
  * This entry also exports `writeNdjsonStream`: the writer of an NDJSON stream response of wire
  * protocol v1, for a `ServerResponse` of `node:http`. `HttpServerTransport` uses it, so a server
  * without Express writes the same bytes.
+ *
+ * The procedure faces of Node, without a framework (CLI-3): `procedureHandler(server, options)`
+ * gives a request handler `(req, res) => boolean`, and `upgradeHandler(server, options)` gives an
+ * upgrade handler `(req, socket, head) => boolean`. Each one takes the requests of its path and
+ * gives `false` for the others, so the routes of the application share the listener.
  */
 
 export { WebSocketTransport } from "./adapters/websocket/client/node.js";
 export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/websocket/client/types.js";
 export { writeNdjsonStream } from "./adapters/http/server/ndjson.js";
 export type { WriteNdjsonStreamOptions, NdjsonError } from "./adapters/http/server/ndjson.js";
+export { procedureHandler } from "./adapters/http/server/handler.js";
+export type { ProcedureHandlerOptions, NodeProcedureHandler, NodeUrlStrategy, UrlRequest } from "./adapters/http/server/handler.js";
+export type { CorsOptions } from "./adapters/http/server/cors.js";
+export type { RoutedRequest } from "./adapters/http/server/strategies.js";
+export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "./adapters/http/server/strategies.js";
+export { upgradeHandler } from "./adapters/websocket/server/upgrade.js";
+export type { UpgradeHandlerOptions, NodeUpgradeHandler } from "./adapters/websocket/server/upgrade.js";
+export { WebSocketServerTransport } from "./adapters/websocket/server/transport.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage,
+  TrackedConnection,
+  ConnectionEventHandler,
+} from "./adapters/websocket/server/types.js";

package/src/procedures/capability.ts

@@ -178,6 +178,27 @@ export function narrowCapability<C>(
   return Object.freeze(result) as Capability<C>;
 }
 
+/**
+ * This function joins two requests for a narrower capability into one request that asks for
+ * both: the meet of the clearances, the intersection of the effects and the shorter time. Two
+ * different clearances need an order.
+ */
+export function joinNarrowing<C>(first: CapabilityRequest<C>, second: CapabilityRequest<C>, order?: ClearanceOrder<C>): CapabilityRequest<C> {
+  const result: CapabilityRequest<C> = {};
+  if (first.clearance === undefined || second.clearance === undefined || Object.is(first.clearance, second.clearance)) {
+    const clearance = first.clearance ?? second.clearance;
+    if (clearance !== undefined) result.clearance = clearance;
+  } else {
+    if (!order) throw new Error("Two different clearances need a clearance order: give clearanceOrder to the host (hostPolicy)");
+    result.clearance = order.meet(first.clearance, second.clearance);
+  }
+  const effects = first.effects === undefined ? second.effects : narrowEffects(first.effects, second.effects);
+  if (effects !== undefined) result.effects = effects;
+  const times = [first.timeoutMs, second.timeoutMs].filter((time): time is number => typeof time === "number" && Number.isFinite(time) && time >= 0);
+  if (times.length > 0) result.timeoutMs = Math.min(...times);
+  return result;
+}
+
 // =============================================================================
 // Admission
 // =============================================================================