@procedures/client 0.3.0 → 0.5.0

package/dist/events/publisher.js

@@ -0,0 +1,268 @@
+/**
+ * The publisher of the remote events (`documentation/EVENTS.md`).
+ *
+ * An `EventPublisher` serves the procedure `events.subscribe` from an event bus. A host gives it
+ * to `ProcedureServer` (the option `events`) or to `LocalTransport`. Each subscription is a stream
+ * without an end: its first item confirms the listeners, and each other item is one event of the
+ * bus.
+ *
+ * - The topic rule (`topics`) is the expose rule of the topics. A topic outside it gives
+ *   `TOPIC_NOT_FOUND`.
+ * - `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.
+ *
+ * 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.
+ */
+import { z } from "zod";
+import { createProcedure } from "../procedures/define.js";
+import { InvocationError } from "../procedures/invoke.js";
+import { getGlobalEventBus } from "./bus.js";
+import { EVENTS_SUBSCRIBE_PATH } from "./remote.js";
+/** The number of topics that one subscription can name. */
+export const MAX_SUBSCRIPTION_TOPICS = 64;
+/** The number of characters of a topic name. */
+export const MAX_TOPIC_LENGTH = 256;
+/** This function gives the test of a topic rule. */
+export function topicMatcher(rule) {
+    if (typeof rule === "function")
+        return rule;
+    const exact = new Set();
+    const prefixes = [];
+    let all = false;
+    for (const pattern of rule) {
+        if (pattern === "*")
+            all = true;
+        else if (pattern.endsWith("*"))
+            prefixes.push(pattern.slice(0, -1));
+        else
+            exact.add(pattern);
+    }
+    return (topic) => all || exact.has(topic) || prefixes.some((prefix) => topic.startsWith(prefix));
+}
+/** The error of a topic outside the topic rule. */
+class TopicNotFoundError extends Error {
+    name = "TopicNotFoundError";
+    code = "TOPIC_NOT_FOUND";
+    retryable = false;
+}
+/** The error that ends each subscription when the publisher stops. A resubscribe can succeed later. */
+function stoppedError() {
+    return Object.assign(new Error("The publisher of the events stops"), { code: "UNAVAILABLE", retryable: true });
+}
+const topicSchema = z.string().min(1).max(MAX_TOPIC_LENGTH);
+const subscribeInput = z.object({
+    topics: z.array(topicSchema).min(1).max(MAX_SUBSCRIPTION_TOPICS).describe("The topics of the subscription"),
+});
+const eventItemSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("subscribed"),
+        topics: z.array(z.string()).describe("The topics that the publisher listens to for this subscription"),
+    }),
+    z.object({
+        type: z.literal("event"),
+        topic: z.string(),
+        data: z.unknown(),
+        seq: z.number().int().describe("The number of the event in the subscription, from 1"),
+        dropped: z.number().int().optional().describe("The events that the publisher dropped immediately before this one"),
+    }),
+]);
+/**
+ * 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.
+ */
+class TopicSubscription {
+    buffer;
+    signal;
+    onClose;
+    confirmation;
+    queue = [];
+    seq = 0;
+    dropped = 0;
+    waiter;
+    closed = false;
+    failure;
+    unsubscribes;
+    constructor(bus, topics, buffer, signal, onClose) {
+        this.buffer = buffer;
+        this.signal = signal;
+        this.onClose = onClose;
+        this.confirmation = { type: "subscribed", topics };
+        this.unsubscribes = topics.map((topic) => bus.on(topic, (data) => this.push(topic, data)));
+        signal?.addEventListener("abort", this.onAbort, { once: true });
+    }
+    /** This function closes a subscription whose call aborted before it started. */
+    closeIfAborted() {
+        if (this.signal?.aborted)
+            this.close();
+        return this;
+    }
+    onAbort = () => this.close();
+    /** This function takes one event of the bus. It never waits. */
+    push(topic, data) {
+        if (this.closed)
+            return;
+        const event = { type: "event", topic, data, seq: ++this.seq };
+        const waiter = this.waiter;
+        if (waiter && this.queue.length === 0) {
+            this.waiter = undefined;
+            waiter.resolve({ value: this.withDropped(event), done: false });
+            return;
+        }
+        if (this.queue.length >= this.buffer) {
+            // A slow subscriber: the oldest event goes, and the next event tells the loss
+            this.queue.shift();
+            this.dropped++;
+        }
+        this.queue.push(event);
+    }
+    /** The event with the number of events that the publisher dropped before it. */
+    withDropped(event) {
+        if (this.dropped === 0)
+            return event;
+        const dropped = this.dropped;
+        this.dropped = 0;
+        return { ...event, dropped };
+    }
+    next() {
+        if (this.confirmation) {
+            const confirmation = this.confirmation;
+            this.confirmation = undefined;
+            return Promise.resolve({ value: confirmation, done: false });
+        }
+        const event = this.queue.shift();
+        if (event)
+            return Promise.resolve({ value: this.withDropped(event), done: false });
+        if (this.failure !== undefined) {
+            const failure = this.failure;
+            this.failure = undefined;
+            return Promise.reject(failure);
+        }
+        if (this.closed)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve, reject) => {
+            this.waiter = { resolve, reject };
+        });
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /** This function ends the subscription with an error: the reader gets it at its next item. */
+    fail(error) {
+        if (this.closed)
+            return;
+        const waiter = this.waiter;
+        this.waiter = undefined;
+        this.release();
+        this.queue.length = 0;
+        this.confirmation = undefined;
+        if (waiter)
+            waiter.reject(error);
+        else
+            this.failure = error;
+    }
+    /** This function ends the subscription without an error. */
+    close() {
+        if (this.closed)
+            return;
+        const waiter = this.waiter;
+        this.waiter = undefined;
+        this.release();
+        this.queue.length = 0;
+        this.confirmation = undefined;
+        waiter?.resolve({ value: undefined, done: true });
+    }
+    /** This function removes the listeners from the bus and from the signal. */
+    release() {
+        this.closed = true;
+        for (const unsubscribe of this.unsubscribes)
+            unsubscribe();
+        this.signal?.removeEventListener("abort", this.onAbort);
+        this.onClose(this);
+    }
+}
+/**
+ * The publisher of the remote events: it serves `events.subscribe` from a bus, under a topic
+ * rule. `ProcedureServer` makes one from its option `events`.
+ *
+ * @example
+ * ```typescript
+ * const publisher = new EventPublisher({ bus, topics: ["orders.*"] });
+ * const server = new ProcedureServer({ registry, autoRegister: true, events: publisher });
+ * publisher.publish("orders.created", { order: 1 });
+ * ```
+ */
+export class EventPublisher {
+    /** The bus that the subscriptions read. */
+    bus;
+    /** The procedure `events.subscribe` of this publisher. A host pins it, outside its registry. */
+    procedure;
+    known;
+    allow;
+    buffer;
+    open = new Set();
+    constructor(options) {
+        this.bus = options.bus ?? getGlobalEventBus();
+        this.known = topicMatcher(options.topics);
+        this.allow = options.allow;
+        this.buffer = Math.max(1, Math.floor(options.buffer ?? 1024));
+        this.procedure = createProcedure()
+            .path([...EVENTS_SUBSCRIBE_PATH])
+            .input(subscribeInput)
+            .output(eventItemSchema)
+            .meta({
+            description: "A subscription to topics of the event bus of the host: a stream without an end, with one item for each event",
+            effects: { reads: ["events"], writes: [] },
+            stream: { unbounded: true },
+        })
+            .handler((async (input, ctx) => this.subscribe(input.topics, ctx)))
+            .build();
+    }
+    /** This function publishes an event on the bus: each subscription of the topic gets it. */
+    publish(topic, data) {
+        this.bus.emit(topic, data);
+    }
+    /** The number of open subscriptions. */
+    get subscriptions() {
+        return this.open.size;
+    }
+    /**
+     * This function ends each open subscription with a retryable `UNAVAILABLE`: the publisher stops.
+     * A subscriber resubscribes after its backoff. `ProcedureServer.stop()` calls it first.
+     */
+    end() {
+        for (const subscription of [...this.open])
+            subscription.fail(stoppedError());
+    }
+    /**
+     * 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.
+     */
+    subscribe(topics, ctx) {
+        const unique = [...new Set(topics)];
+        for (const topic of unique) {
+            if (!this.known(topic))
+                throw new TopicNotFoundError(`The host has no topic "${topic}"`);
+        }
+        if (this.allow) {
+            const call = { capability: ctx.capability, metadata: ctx.metadata };
+            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));
+        this.open.add(subscription);
+        return subscription.closeIfAborted();
+    }
+}
+//# sourceMappingURL=publisher.js.map

package/dist/events/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../../src/events/publisher.ts"],"names":[],"mappings":"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"}

package/dist/events/remote.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The subscriber of the remote events (`documentation/EVENTS.md`).
+ *
+ * A peer subscribes to the topics of the bus of another peer with a streaming call of the
+ * procedure `events.subscribe`. The first item of the stream confirms the subscription, and each
+ * other item is one event. The frames are the frames of each call: credit is the backpressure,
+ * and a cancel is the unsubscribe. Thus each transport with streams carries a subscription:
+ * WebSocket in the two directions, HTTP with NDJSON, a message port and the local transport.
+ *
+ * - `remoteEvents()` gives an async iterator of the events.
+ * - `subscribeRemote()` calls a handler for each event, and gives the unsubscribe function.
+ *
+ * After a failure that a retry can repair (a closed connection, `UNAVAILABLE`, `TIMEOUT`), the
+ * subscriber sends the call again after a backoff. The delivery is at most once: the events
+ * between the failure and the new confirmation are lost. Each other error ends the subscription.
+ *
+ * This file imports only types and the backoff, so a page or a worker that subscribes stays small.
+ */
+import type { Transport } from "../client/types.js";
+/** The path of the procedure of a subscription. */
+export declare const EVENTS_SUBSCRIBE_PATH: readonly ["events", "subscribe"];
+/** The input of `events.subscribe`. */
+export interface SubscribeInput {
+    /** The topics: from 1 to 64 names of 1 to 256 characters. */
+    readonly topics: readonly string[];
+}
+/**
+ * An item of the stream of `events.subscribe`. The first item is `subscribed`. Each other item is
+ * an `event`. A subscriber ignores an item of another type: it comes from a newer publisher.
+ */
+export type EventItem = {
+    readonly type: "subscribed";
+    readonly topics: readonly string[];
+} | {
+    readonly type: "event";
+    readonly topic: string;
+    readonly data: unknown;
+    /** The number of the event in its subscription, from 1. A gap shows lost events. */
+    readonly seq: number;
+    /** The number of events that the publisher dropped immediately before this one. */
+    readonly dropped?: number | undefined;
+};
+/** One event that a subscriber gets. */
+export interface RemoteEvent<T = unknown> {
+    /** The topic (the channel of the bus of the publisher). */
+    readonly topic: string;
+    /** The data of the event, after a trip as JSON. */
+    readonly data: T;
+    /** The number of the event in its subscription, from 1. A resubscribe starts again at 1. */
+    readonly seq: number;
+    /** The number of events that the publisher dropped immediately before this one: 0 without a loss. */
+    readonly dropped: number;
+    /** The id of the subscription. It stays the same after a resubscribe. */
+    readonly subscription: string;
+}
+/**
+ * The handler of the events of a subscription. When it gives a promise, the subscriber waits for
+ * it before the next event, so a slow handler holds the credit of its own subscription only.
+ */
+export type RemoteEventHandler<T = unknown> = (data: T, event: RemoteEvent<T>) => void | Promise<void>;
+/** The options of a subscription. */
+export interface RemoteEventsOptions {
+    /** When this signal aborts, the subscription ends: the transport sends a cancel. */
+    signal?: AbortSignal | undefined;
+    /**
+     * True: the subscriber sends the call again after a failure that a retry can repair. False: such
+     * a failure ends the subscription.
+     * @default true
+     */
+    resubscribe?: boolean | undefined;
+    /**
+     * This function gives the time before resubscribe try `attempt` (from 1), in milliseconds. The
+     * default is an exponential backoff from 250 ms to 30 s with full jitter. The WebSocket
+     * transport uses its reconnect backoff.
+     */
+    backoff?: ((attempt: number) => number) | undefined;
+    /** This function gets the topics of each confirmation: the first one, and one after each resubscribe. */
+    onSubscribed?: ((topics: readonly string[]) => void) | undefined;
+    /** The metadata of the call, for example a trace. */
+    metadata?: Record<string, unknown> | undefined;
+}
+/** The options of `subscribeRemote()`. */
+export interface SubscribeOptions extends RemoteEventsOptions {
+    /**
+     * This function gets the error that ends the subscription: a refusal (`TOPIC_NOT_FOUND`,
+     * `FORBIDDEN`), an older publisher (`NOT_FOUND`), or a transport that closed. An unsubscribe is
+     * not an error.
+     */
+    onError?: ((error: SubscriptionError) => void) | undefined;
+}
+/**
+ * The unsubscribe function of a subscription. A second call does nothing. `ready` resolves at the
+ * first confirmation of the publisher. It rejects when the subscription ends before it.
+ */
+export interface Subscription {
+    (): void;
+    /** This promise resolves when the publisher confirms the subscription the first time. */
+    readonly ready: Promise<void>;
+    /** The id of the subscription: the `subscription` of its events. */
+    readonly id: string;
+}
+/** The error that ends a subscription. */
+export declare class SubscriptionError extends Error {
+    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+    readonly code: string;
+    /** True when a resubscribe can repair the failure. */
+    readonly retryable: boolean;
+    /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
+    readonly reason?: string | undefined;
+    readonly name = "SubscriptionError";
+    constructor(
+    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+    code: string, message: string, 
+    /** True when a resubscribe can repair the failure. */
+    retryable: boolean, 
+    /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
+    reason?: string | undefined);
+}
+/**
+ * The parts that a transport adds to its subscriptions. The WebSocket transport waits for its
+ * connection, uses its reconnect backoff, ends its subscriptions at `close()`, and gives each
+ * event to its `onEvent` option.
+ */
+export interface SubscriptionHooks {
+    /** When this signal aborts, each subscription ends without an error. */
+    readonly lifetime?: AbortSignal | undefined;
+    /**
+     * This function resolves when the transport can send the call. It rejects when the transport
+     * closed. After a lost connection, the subscriber waits for it, not for a backoff.
+     */
+    readonly ready?: ((signal: AbortSignal) => Promise<void>) | undefined;
+    /** The backoff, when the options give none. */
+    readonly backoff?: ((attempt: number) => number) | undefined;
+    /** This function gets each event of each subscription. */
+    readonly onEvent?: ((event: RemoteEvent) => void) | undefined;
+    /** False: no resubscribe, whatever the options say (a server cannot reach a closed connection). */
+    readonly resubscribe?: boolean | undefined;
+}
+/** The part of a transport that a subscription uses. */
+export type EventTransport = Pick<Transport, "send">;
+/**
+ * This function gives the events of a subscription to topics of the bus of the other side. The
+ * iteration sends the call. A `break` of the reader, or the abort of the signal, sends the cancel.
+ * An error that ends the subscription ends the iteration with a `SubscriptionError`.
+ *
+ * @param transport - The transport to the publisher: HTTP, WebSocket, a message port, local
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param options - The signal, the resubscribe, the backoff and the confirmation handler
+ * @param hooks - The parts that a transport adds (its connection, its backoff, its `onEvent`)
+ */
+export declare function remoteEvents<T = unknown>(transport: EventTransport, topics: string | readonly string[], options?: RemoteEventsOptions, hooks?: SubscriptionHooks): AsyncIterable<RemoteEvent<T>>;
+/**
+ * This function subscribes to topics of the bus of the other side, and calls the handler for each
+ * event in order. It gives the unsubscribe function, with the `ready` promise of the first
+ * confirmation. An error of the handler goes to `console.error`, and the subscription goes on.
+ *
+ * @param transport - The transport to the publisher
+ * @param topics - One topic, or a list of 1 to 64 topics
+ * @param handler - The handler of each event: it gets the data and the event
+ * @param options - The options of `remoteEvents()`, and the `onError` handler of the end
+ * @param hooks - The parts that a transport adds
+ */
+export declare function subscribeRemote<T = unknown>(transport: EventTransport, topics: string | readonly string[], handler: RemoteEventHandler<T>, options?: SubscribeOptions, hooks?: SubscriptionHooks): Subscription;
+//# sourceMappingURL=remote.d.ts.map

package/dist/events/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/events/remote.ts"],"names":[],"mappings":"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"}