@procedures/client 0.7.0 → 0.8.1

package/dist/events/remote.js

@@ -10,13 +10,21 @@
  * - `remoteEvents()` gives an async iterator of the events.
  * - `subscribeRemote()` calls a handler for each event, and gives the unsubscribe function.
  *
+ * The subscribers of the same topics with the same options on one transport share one call: one
+ * wire subscription with a reference count. The last unsubscribe sends the cancel. Each subscriber
+ * has its own queue, its own `seq`, its own `ready` and its own end.
+ *
  * 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.
+ * subscriber sends the call again after a backoff, at most `maxAttempts` times without a
+ * confirmation. 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.
+ * This file imports only types, the backoff, the clock and the durations, so a page or a worker
+ * that subscribes stays small.
  */
 import { backoffDelay } from "@mark1russell7/service/backoff";
+import { realClock } from "../clock.js";
+import { toMs } from "../duration.js";
 /** The path of the procedure of a subscription. */
 export const EVENTS_SUBSCRIBE_PATH = Object.freeze(["events", "subscribe"]);
 /** The method of the procedure of a subscription. */
@@ -42,9 +50,22 @@ export class SubscriptionError extends Error {
 }
 /** The codes after which a resubscribe can succeed, also when the item does not say retryable. */
 const RESUBSCRIBE_CODES = new Set(["UNAVAILABLE", "TIMEOUT", "CONNECTION_CLOSED", "ABORTED"]);
-/** The default backoff: from 250 ms, twice as long at each try, at most 30 s, with full jitter. */
+/** The default number of resubscribe tries (EVENTS.md). */
+const DEFAULT_MAX_ATTEMPTS = 10;
+/** The default backoff, in milliseconds: from 250 ms, twice as long at each try, at most 30 s, with full jitter. */
+const DEFAULT_BACKOFF = { initialDelayMs: 250, maxDelayMs: 30_000, backoffMultiplier: 2, jitter: 1 };
+/**
+ * The number of events that the queue of one subscriber holds when another subscriber of its
+ * shared subscription reads faster. When it is full, the oldest event goes, as at the publisher.
+ */
+const SUBSCRIBER_BUFFER = 1024;
+/** The default backoff of `DEFAULT_BACKOFF`. */
 function defaultBackoff(attempt) {
-    return backoffDelay({ base: 250, factor: 2, cap: 30_000, jitter: { kind: "subtract", fraction: 1 } }, attempt);
+    return exponentialBackoff([DEFAULT_BACKOFF.initialDelayMs, DEFAULT_BACKOFF.maxDelayMs, DEFAULT_BACKOFF.backoffMultiplier, DEFAULT_BACKOFF.jitter], attempt);
+}
+/** The delay before try `attempt`: an exponential backoff of `[base, cap, factor, jitter]`. */
+function exponentialBackoff([base, cap, factor, jitter], attempt) {
+    return backoffDelay({ base, factor, cap, jitter: { kind: "subtract", fraction: jitter } }, attempt);
 }
 let subscriptions = 0;
 /** The topics of a subscription as a list. */
@@ -69,17 +90,18 @@ function linkSignals(signals) {
         },
     };
 }
-/** This function waits for a time, or until the signal aborts. */
-function pause(ms, signal) {
+/** This function waits for a time on the clock, or until the signal aborts. */
+function pause(ms, signal, clock) {
     if (signal.aborted || !(ms > 0))
         return Promise.resolve();
     return new Promise((resolve) => {
+        let cancel;
         const done = () => {
-            clearTimeout(timer);
+            cancel?.();
             signal.removeEventListener("abort", done);
             resolve();
         };
-        const timer = setTimeout(done, ms);
+        cancel = clock.after(ms, done);
         signal.addEventListener("abort", done, { once: true });
     });
 }
@@ -99,11 +121,66 @@ function errorOfFailure(error) {
     const message = error instanceof Error ? error.message : String(error);
     return new SubscriptionError("CONNECTION_CLOSED", message, true);
 }
-/** The events of a subscription, with each resubscribe. The generator ends at the unsubscribe. */
-async function* eventsOf(transport, topics, options, hooks, id) {
-    const { signal, unlink } = linkSignals([options.signal, hooks.lifetime]);
+/** The error that ends a subscription when its resubscribe tries ran out. It keeps the code of the last failure. */
+function exhaustedError(last, tries) {
+    return new SubscriptionError(last.code, `The subscription stopped after ${tries} resubscribe tries without a confirmation: ${last.message}`, last.retryable, last.reason);
+}
+/** The ids of the clocks of the options, for the keys of the shared subscriptions. */
+const clockIds = new WeakMap();
+let clocks = 0;
+/** The id of the clock of the options: 0 without one. */
+function clockIdOf(clock) {
+    if (!clock)
+        return 0;
+    let id = clockIds.get(clock);
+    if (id === undefined) {
+        id = ++clocks;
+        clockIds.set(clock, id);
+    }
+    return id;
+}
+/** The milliseconds of a backoff of the options. A plain number or a function throws a `TypeError`. */
+function backoffSettings(backoff) {
+    if (backoff === null || typeof backoff !== "object") {
+        const given = typeof backoff === "function" ? "a function" : JSON.stringify(backoff);
+        throw new TypeError(`backoff must be an object of durations such as { initialDelay: ms(250), maxDelay: seconds(30) }, got ${given}. The backoff is no longer a function of milliseconds (EVENTS.md).`);
+    }
+    const base = backoff.initialDelay === undefined ? DEFAULT_BACKOFF.initialDelayMs : toMs(backoff.initialDelay, "backoff.initialDelay");
+    const cap = backoff.maxDelay === undefined ? DEFAULT_BACKOFF.maxDelayMs : toMs(backoff.maxDelay, "backoff.maxDelay");
+    const factor = backoff.backoffMultiplier ?? DEFAULT_BACKOFF.backoffMultiplier;
+    const jitter = Math.min(1, Math.max(0, backoff.jitter ?? DEFAULT_BACKOFF.jitter));
+    return [base, cap, factor, jitter];
+}
+/** The resubscribe rules of the options and the hooks. A bad option throws a `TypeError` at once. */
+function policyOf(options, hooks) {
+    const maxAttempts = options.maxAttempts ?? hooks.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    if (typeof maxAttempts !== "number" || Number.isNaN(maxAttempts) || maxAttempts < 0) {
+        throw new TypeError(`maxAttempts must be a number from 0 (Infinity for no limit), got ${JSON.stringify(maxAttempts)}`);
+    }
+    let backoff;
+    let backoffKey;
+    if (options.backoff !== undefined) {
+        const settings = backoffSettings(options.backoff);
+        backoff = (attempt) => exponentialBackoff(settings, attempt);
+        backoffKey = settings;
+    }
+    else {
+        backoff = hooks.backoff ?? defaultBackoff;
+        backoffKey = "transport";
+    }
     const resubscribe = hooks.resubscribe !== false && options.resubscribe !== false;
-    const backoff = options.backoff ?? hooks.backoff ?? defaultBackoff;
+    return {
+        resubscribe,
+        maxAttempts,
+        backoff,
+        clock: options.clock ?? hooks.clock ?? realClock,
+        key: [resubscribe, maxAttempts === Number.POSITIVE_INFINITY ? "Infinity" : maxAttempts, backoffKey, clockIdOf(options.clock)],
+    };
+}
+/** The events of a wire subscription, with each resubscribe. The generator ends when `stop` aborts. */
+async function* wireEvents(transport, call, stop) {
+    const { policy, hooks } = call;
+    const { signal, unlink } = linkSignals([stop, hooks.lifetime]);
     let attempt = 0;
     let tries = 0;
     try {
@@ -116,10 +193,10 @@ async function* eventsOf(transport, topics, options, hooks, id) {
                     return;
             }
             const message = {
-                id: `${id}.${++tries}`,
+                id: `${call.id}.${++tries}`,
                 method: SUBSCRIBE_METHOD,
-                payload: { topics: [...topics] },
-                metadata: { ...(options.metadata ?? {}) },
+                payload: { topics: [...call.topics] },
+                metadata: { ...call.metadata },
                 signal,
             };
             let failure;
@@ -134,18 +211,10 @@ async function* eventsOf(transport, topics, options, hooks, id) {
                         continue;
                     if (payload.type === "subscribed") {
                         attempt = 0;
-                        options.onSubscribed?.(payload.topics);
+                        call.onSubscribed(payload.topics);
                     }
                     else if (payload.type === "event") {
-                        const event = {
-                            topic: payload.topic,
-                            data: payload.data,
-                            seq: payload.seq,
-                            dropped: payload.dropped ?? 0,
-                            subscription: id,
-                        };
-                        hooks.onEvent?.(event);
-                        yield event;
+                        yield payload;
                     }
                 }
             }
@@ -158,48 +227,371 @@ async function* eventsOf(transport, topics, options, hooks, id) {
             // The publisher ended the subscription
             if (!failure)
                 return;
-            if (!resubscribe || !failure.error.retryable)
+            if (!policy.resubscribe || !failure.error.retryable || policy.maxAttempts === 0)
                 throw failure.error;
+            // The tries ran out: before, HTTP resubscribed forever
+            if (attempt >= policy.maxAttempts)
+                throw exhaustedError(failure.error, attempt);
             attempt++;
+            call.onRetry();
             // After a lost connection, the transport waits for its reconnect: no second backoff
             if (!(failure.lost && hooks.ready))
-                await pause(backoff(attempt), signal);
+                await pause(policy.backoff(attempt), signal, policy.clock);
         }
     }
     finally {
         unlink();
     }
 }
+/**
+ * One subscriber of a shared subscription: its queue, and its numbers. Its `seq` counts from the
+ * last event that the shared subscription got before the subscriber joined.
+ */
+class Subscriber {
+    id;
+    /** The `seq` of the wire subscription before the first event of this subscriber. */
+    base = 0;
+    /** The error that ends this subscriber, after the entries of its queue. */
+    failure;
+    /** This function tells the shared subscription that the subscriber waits. */
+    onWait = () => undefined;
+    queue = [];
+    events = 0;
+    waiter;
+    ended = false;
+    constructor(id) {
+        this.id = id;
+    }
+    /** True when the subscriber waits for an entry. */
+    get waiting() {
+        return this.waiter !== undefined;
+    }
+    /** This function gives the subscriber one event of the wire, with its own `seq`. */
+    pushEvent(event) {
+        this.push({ kind: "event", topic: event.topic, data: event.data, seq: event.seq - this.base, dropped: event.dropped ?? 0 });
+    }
+    /** This function gives the subscriber one entry. A full queue drops its oldest event. */
+    push(entry) {
+        if (this.ended)
+            return;
+        const waiter = this.waiter;
+        if (waiter) {
+            this.waiter = undefined;
+            waiter(entry);
+            return;
+        }
+        if (entry.kind === "event") {
+            if (this.events >= SUBSCRIBER_BUFFER) {
+                // The next event of the same wire stream tells the loss. After a confirmation, a new stream starts.
+                const index = this.queue.findIndex((queued) => queued.kind === "event");
+                const lost = this.queue.splice(index, 1)[0];
+                this.events--;
+                const next = index < this.queue.length ? this.queue[index] : entry;
+                if (next.kind === "event")
+                    next.dropped += 1 + lost.dropped;
+            }
+            this.events++;
+        }
+        this.queue.push(entry);
+    }
+    /** The next entry, or undefined at the end. */
+    take() {
+        const entry = this.queue.shift();
+        if (entry) {
+            if (entry.kind === "event")
+                this.events--;
+            return Promise.resolve(entry);
+        }
+        if (this.ended)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            this.waiter = resolve;
+            this.onWait();
+        });
+    }
+    /**
+     * This function ends the subscriber. Without `discard`, it first gives the entries of its queue.
+     * The shared subscription ends it with its error, and an unsubscribe ends it with `discard`.
+     */
+    end(failure, discard = false) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.failure = failure;
+        if (discard) {
+            this.queue.length = 0;
+            this.events = 0;
+        }
+        const waiter = this.waiter;
+        this.waiter = undefined;
+        waiter?.(undefined);
+    }
+}
+/**
+ * One wire subscription and its subscribers. It reads the next item of the wire only when a
+ * subscriber waits, so a single slow subscriber holds the credit, as before the share. It ends
+ * when its last subscriber leaves, or with the end of the wire subscription for each subscriber.
+ */
+class SharedSubscription {
+    shares;
+    key;
+    transport;
+    call;
+    members = new Set();
+    stop = new AbortController();
+    /** The topics of the current confirmation, or undefined before it and during a resubscribe. */
+    confirmed;
+    /** The `seq` of the last event of the wire. */
+    lastSeq = 0;
+    demand;
+    started = false;
+    finished = false;
+    constructor(shares, key, transport, call) {
+        this.shares = shares;
+        this.key = key;
+        this.transport = transport;
+        this.call = call;
+    }
+    /** True while a new subscriber can join. */
+    get open() {
+        return !this.finished && !this.stop.signal.aborted;
+    }
+    /** This function adds a subscriber. On a confirmed subscription, it gets the confirmation at once. */
+    join(subscriber) {
+        this.members.add(subscriber);
+        subscriber.base = this.lastSeq;
+        subscriber.onWait = () => this.wake();
+        if (this.confirmed)
+            subscriber.push({ kind: "subscribed", topics: this.confirmed });
+        if (!this.started) {
+            this.started = true;
+            void this.run();
+        }
+    }
+    /** This function removes a subscriber. The last one ends the wire subscription: the transport sends the cancel. */
+    leave(subscriber) {
+        if (!this.members.delete(subscriber) || this.members.size > 0)
+            return;
+        this.forget();
+        this.stop.abort();
+        this.wake();
+    }
+    wake() {
+        const demand = this.demand;
+        this.demand = undefined;
+        demand?.();
+    }
+    /** This function removes the subscription from the shares of its transport. */
+    forget() {
+        if (this.shares?.get(this.key) === this)
+            this.shares.delete(this.key);
+    }
+    stopped() {
+        return this.stop.signal.aborted || this.call.hooks.lifetime?.aborted === true;
+    }
+    wanted() {
+        for (const member of this.members)
+            if (member.waiting)
+                return true;
+        return false;
+    }
+    async run() {
+        const events = wireEvents(this.transport, {
+            ...this.call,
+            onSubscribed: (topics) => {
+                this.confirmed = topics;
+                this.lastSeq = 0;
+                for (const member of this.members) {
+                    member.base = 0;
+                    member.push({ kind: "subscribed", topics });
+                }
+            },
+            onRetry: () => {
+                this.confirmed = undefined;
+            },
+        }, this.stop.signal);
+        // The end of the transport ends the wait for a subscriber too
+        const lifetime = this.call.hooks.lifetime;
+        const onLifetime = () => this.wake();
+        lifetime?.addEventListener("abort", onLifetime, { once: true });
+        let failure;
+        try {
+            for (;;) {
+                while (!this.stopped() && !this.wanted()) {
+                    await new Promise((resolve) => {
+                        this.demand = resolve;
+                    });
+                }
+                if (this.stopped())
+                    break;
+                const result = await events.next();
+                if (result.done)
+                    break;
+                this.lastSeq = result.value.seq;
+                for (const member of this.members)
+                    member.pushEvent(result.value);
+            }
+        }
+        catch (error) {
+            failure = errorOfFailure(error);
+        }
+        finally {
+            this.finished = true;
+            this.forget();
+            lifetime?.removeEventListener("abort", onLifetime);
+            await events.return(undefined).catch(() => undefined);
+        }
+        // The end of the wire subscription goes to each subscriber
+        for (const member of [...this.members])
+            member.end(failure);
+        this.members.clear();
+    }
+}
+/** The shared subscriptions of each transport, by key. */
+const sharesOf = new WeakMap();
+/** The key of a shared subscription: the set of topics, the metadata and the resubscribe rules. */
+function keyOf(topics, metadata, policy) {
+    try {
+        return JSON.stringify([[...new Set(topics)].sort(), metadata, policy.key]);
+    }
+    catch {
+        // Metadata that is not JSON: the subscription is not shared
+        return undefined;
+    }
+}
+/** The shared subscription of a new subscriber: an open one with the same key, or a new one with the id of the subscriber. */
+function sharedFor(transport, topics, options, hooks, policy, id) {
+    const metadata = { ...(options.metadata ?? {}) };
+    const key = keyOf(topics, metadata, policy);
+    let shares = sharesOf.get(transport);
+    if (!shares) {
+        shares = new Map();
+        sharesOf.set(transport, shares);
+    }
+    const existing = key === undefined ? undefined : shares.get(key);
+    if (existing?.open)
+        return existing;
+    const shared = new SharedSubscription(key === undefined ? undefined : shares, key ?? "", transport, { topics, metadata, policy, hooks, id });
+    if (key !== undefined)
+        shares.set(key, shared);
+    return shared;
+}
+/** The event that a subscriber gets from an entry of its queue. */
+function remoteEventOf(entry, id) {
+    return { topic: entry.topic, data: entry.data, seq: entry.seq, dropped: entry.dropped, subscription: id };
+}
+/** This function calls `onSubscribed`. An error of it goes to `console.error`, and the subscription goes on. */
+function confirmTo(options, topics) {
+    try {
+        options.onSubscribed?.(topics);
+    }
+    catch (error) {
+        console.error("[events] The onSubscribed handler failed:", error);
+    }
+}
+/** This function joins a new subscriber to its shared subscription, and gives the function that leaves it. */
+function attach(subscriber, transport, topics, options, hooks, policy) {
+    if (options.signal?.aborted) {
+        subscriber.end(undefined, true);
+        return () => undefined;
+    }
+    const shared = sharedFor(transport, topics, options, hooks, policy, subscriber.id);
+    let left = false;
+    const leave = () => {
+        if (left)
+            return;
+        left = true;
+        options.signal?.removeEventListener("abort", leave);
+        shared.leave(subscriber);
+        subscriber.end(undefined, true);
+    };
+    options.signal?.addEventListener("abort", leave, { once: true });
+    shared.join(subscriber);
+    return leave;
+}
 /**
  * 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`.
+ * iteration joins the subscription, so it sends the call when no subscriber shares one. A `break`
+ * of the reader, or the abort of the signal, leaves it: the last subscriber 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 options - The signal, the resubscribe rules, the clock and the confirmation handler
  * @param hooks - The parts that a transport adds (its connection, its backoff, its `onEvent`)
+ * @throws TypeError - When `backoff` or `maxAttempts` is not valid, for example a plain number of milliseconds
  */
 export function remoteEvents(transport, topics, options = {}, hooks = {}) {
     const list = topicList(topics);
+    const policy = policyOf(options, hooks);
     return {
-        [Symbol.asyncIterator]: () => eventsOf(transport, list, options, hooks, `events-${++subscriptions}`),
+        [Symbol.asyncIterator]: () => {
+            const subscriber = new Subscriber(`events-${++subscriptions}`);
+            let leave;
+            let stopped = false;
+            const stop = () => {
+                stopped = true;
+                if (leave)
+                    leave();
+                else
+                    subscriber.end(undefined, true);
+            };
+            const iterator = {
+                async next() {
+                    if (!leave && !stopped)
+                        leave = attach(subscriber, transport, list, options, hooks, policy);
+                    for (;;) {
+                        const entry = await subscriber.take();
+                        if (!entry) {
+                            const failure = subscriber.failure;
+                            subscriber.failure = undefined;
+                            stop();
+                            if (failure)
+                                throw failure;
+                            return { value: undefined, done: true };
+                        }
+                        if (entry.kind === "subscribed") {
+                            confirmTo(options, entry.topics);
+                            continue;
+                        }
+                        const event = remoteEventOf(entry, subscriber.id);
+                        hooks.onEvent?.(event);
+                        return { value: event, done: false };
+                    }
+                },
+                async return() {
+                    stop();
+                    return { value: undefined, done: true };
+                },
+                async throw(error) {
+                    stop();
+                    throw error;
+                },
+                [Symbol.asyncIterator]() {
+                    return iterator;
+                },
+            };
+            return iterator;
+        },
     };
 }
 /**
  * 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.
+ * The subscribers of the same topics with the same options on one transport share one call.
  *
  * @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
+ * @throws TypeError - When `backoff` or `maxAttempts` is not valid, for example a plain number of milliseconds
  */
 export function subscribeRemote(transport, topics, handler, options = {}, hooks = {}) {
-    const controller = new AbortController();
-    const id = `events-${++subscriptions}`;
+    const list = topicList(topics);
+    const policy = policyOf(options, hooks);
+    const subscriber = new Subscriber(`events-${++subscriptions}`);
     let confirmed = false;
     let confirm = () => undefined;
     let refuse = () => undefined;
@@ -209,21 +601,23 @@ export function subscribeRemote(transport, topics, handler, options = {}, hooks
     });
     // A caller that does not wait for `ready` gets no unhandled rejection
     ready.catch(() => undefined);
-    const { signal, unlink } = linkSignals([options.signal, controller.signal]);
-    const settings = {
-        ...options,
-        signal,
-        onSubscribed: (list) => {
-            if (!confirmed) {
-                confirmed = true;
-                confirm();
-            }
-            options.onSubscribed?.(list);
-        },
-    };
+    const leave = attach(subscriber, transport, list, options, hooks, policy);
     void (async () => {
         try {
-            for await (const event of { [Symbol.asyncIterator]: () => eventsOf(transport, topicList(topics), settings, hooks, id) }) {
+            for (;;) {
+                const entry = await subscriber.take();
+                if (!entry)
+                    break;
+                if (entry.kind === "subscribed") {
+                    if (!confirmed) {
+                        confirmed = true;
+                        confirm();
+                    }
+                    confirmTo(options, entry.topics);
+                    continue;
+                }
+                const event = remoteEventOf(entry, subscriber.id);
+                hooks.onEvent?.(event);
                 try {
                     await handler(event.data, event);
                 }
@@ -231,20 +625,16 @@ export function subscribeRemote(transport, topics, handler, options = {}, hooks
                     console.error(`[events] The handler of ${event.topic} failed:`, error);
                 }
             }
-            if (!confirmed)
-                refuse(new SubscriptionError("ABORTED", "The subscription ended before its confirmation", false));
-        }
-        catch (error) {
-            const failure = errorOfFailure(error);
-            if (!confirmed)
-                refuse(failure);
-            options.onError?.(failure);
         }
         finally {
-            unlink();
+            leave();
         }
+        const failure = subscriber.failure;
+        if (!confirmed)
+            refuse(failure ?? new SubscriptionError("ABORTED", "The subscription ended before its confirmation", false));
+        if (failure)
+            options.onError?.(failure);
     })();
-    const unsubscribe = () => controller.abort();
-    return Object.assign(unsubscribe, { ready, id });
+    return Object.assign(leave, { ready, id: subscriber.id });
 }
 //# sourceMappingURL=remote.js.map