@superblocksteam/shared 0.9607.3 → 0.9608.0

package/dist/socket/heartbeat.d.ts

@@ -0,0 +1,258 @@
+/**
+ * A paced liveness beat over a request channel.
+ *
+ * Every long-lived socket in this repo eventually needs the same thing: proof
+ * that the peer is still answering, cheaply, for as long as the connection is
+ * held. The naive version - an interval that fires a request and counts the
+ * failures - is wrong in three ways that only show up under load, and each one
+ * was found the hard way:
+ *
+ *   1. A request inherits the channel's own budget, which is the whole
+ *      caller-facing operation (minutes). A beat that borrows it cannot report a
+ *      miss inside any window a caller waits in, so it holds its own deadline.
+ *   2. Without an in-flight guard, a peer that stopped answering collects a new
+ *      pending request every interval, none of which can ever be reconciled.
+ *      The answer paces the beats, not the interval.
+ *   3. A beat's response shares the socket with bulk pushes, so a large transfer
+ *      head-of-line blocks the answer past any sane deadline while the
+ *      connection is perfectly healthy. Acting on that kills a busy socket and,
+ *      where the caller reconnects, re-sends the same payload and does it again.
+ *
+ * The third is the subtle one, and it takes two guards, because neither is
+ * sufficient alone. Inbound traffic during the beat's own wait proves the
+ * connection is alive - but a bulk RPC response is a single websocket message,
+ * and no receive event fires until its last byte lands, so that cannot be the
+ * only guard. A single missed beat therefore also gets grace: a transfer merely
+ * has to finish inside one extra interval for the next answer to get through.
+ *
+ * Both guards answer to one bound. Inbound data proves the receive path, not
+ * that the request channel answers, so no amount of either excuse may let a
+ * wedged channel hide forever: once
+ * {@link SocketHeartbeatOptions.maxConsecutiveUnanswered} beats in a row have
+ * gone unanswered, the next silence is believed whatever the reason, and the
+ * grace is bypassed with it.
+ *
+ * Extracted from the browser editor's dev-server heartbeat, which learned all
+ * of the above the hard way and is the first thing to beat with it.
+ */
+/** Why a beat settled the way it did. */
+export type BeatOutcome = 
+/** Answered. The peer is there and the channel works. */
+'success'
+/** A definite answer that was an error. It arrived, so the channel works. */
+ | 'refused'
+/** Unanswered, but the socket was provably delivering data. Excused. */
+ | 'lapse'
+/** Unanswered and believed, but held back so a slow transfer can catch up. */
+ | 'grace'
+/** Unanswered and believed. The caller should act on this one. */
+ | 'miss';
+/**
+ * Running account of the beat, readable at any time and reported when a socket
+ * dies.
+ *
+ * A socket can die before any beat settles, so `sent` counts beats issued
+ * rather than outcomes observed: unanswered beats are the strongest evidence
+ * there is that the peer was gone, and an account built from settled outcomes
+ * alone would report the most telling deaths as having nothing to say.
+ */
+export type HeartbeatAccount = {
+    /**
+     * Consecutive believed silences. Only an unanswered beat that nothing excused
+     * counts here, so this is what decides when the beat is lost - and why a
+     * refusal, which is an answer, can never close a connection on its own.
+     */
+    readonly failures: number;
+    /**
+     * Unanswered beats excused because the socket was provably delivering data at
+     * the time. Purely diagnostic: this is the difference between a dead
+     * connection and a live one whose request channel went quiet, which no close
+     * code can tell apart.
+     *
+     * Cleared by an answered beat or a new connection, not by a refusal - see
+     * {@link HeartbeatAccount.unanswered}.
+     */
+    readonly lapses: number;
+    readonly lastError?: string;
+    readonly lastReceivedAt?: number;
+    readonly lastSuccessAt?: number;
+    /**
+     * When the beat still waiting for its answer went out, or absent if none is.
+     *
+     * `sent` says a beat was issued and {@link HeartbeatAccount.lastSuccessAt}
+     * says one was answered; neither says whether the last one came back. Without
+     * this, a socket that answered a beat and then went silent is indistinguishable
+     * from one answering right up to the close.
+     *
+     * Deliberately survives {@link SocketHeartbeat.stop}, which is the first thing
+     * a caller does with a dead connection: the account is read after the socket
+     * is gone, no settle is coming for a retired beat, and clearing the stamp on
+     * the way out would erase the only record that a beat was outstanding.
+     */
+    readonly pendingSince?: number;
+    /**
+     * Consecutive beats answered with an error. Kept apart from
+     * {@link HeartbeatAccount.failures} because a refusal proves the channel
+     * works: it belongs in the report, never in the decision to give up on a
+     * connection.
+     */
+    readonly refusals: number;
+    /** Every beat issued, including one still waiting. */
+    readonly sent: number;
+    /**
+     * Beats that got no answer, excused or not. This is what the deferral bound is
+     * measured against, so it is also what says how long a silence had been
+     * tolerated when the beat was finally believed.
+     *
+     * Saturates at {@link SocketHeartbeatOptions.maxConsecutiveUnanswered}, so
+     * the run it reports can never exceed the bound it is measured against -
+     * beats keep going out after the alarm is raised, and an unbounded count
+     * would describe a silence longer than the one that was acted on.
+     *
+     * Cleared only by a definite success, proof of life, or a new connection. A
+     * refusal leaves it standing: it answers one beat, and were it to clear the
+     * run, a channel alternating between timing out and refusing could defer the
+     * bound forever while inbound traffic excused every silence.
+     */
+    readonly unanswered: number;
+};
+export interface SocketHeartbeatOptions {
+    /** Issues one beat. The cheapest authorized round trip the channel offers. */
+    beat: () => Promise<unknown>;
+    /** Gap between beats. A beat still in flight when one is due skips it. */
+    intervalMs: number;
+    /** How long one beat waits for its answer before it counts as unanswered. */
+    timeoutMs: number;
+    /**
+     * Consecutive genuine misses before the beat is declared lost. Defaults to
+     * {@link DEFAULT_MAX_CONSECUTIVE_MISSES}.
+     */
+    maxConsecutiveMisses?: number;
+    /**
+     * Consecutive unanswered beats to tolerate before neither proof of life nor
+     * grace may excuse another. Defaults to
+     * {@link DEFAULT_MAX_CONSECUTIVE_UNANSWERED}.
+     */
+    maxConsecutiveUnanswered?: number;
+    /**
+     * Renders a rejection for the account. Channels that reject with plain
+     * objects rather than `Error`s need this, or the cause reads
+     * `[object Object]`.
+     */
+    describeError?: (error: unknown) => string;
+    /**
+     * Whether a rejection means the beat went unanswered, as opposed to being
+     * refused. Only an unanswered beat can lapse or be believed: a refusal is a
+     * definite answer about the peer, and treating it as silence would hide the
+     * very thing it reports. Defaults to recognizing this heartbeat's own
+     * deadline.
+     */
+    isUnanswered?: (error: unknown) => boolean;
+    /**
+     * The beat is lost: enough consecutive beats went unanswered that the peer
+     * cannot be assumed to be there.
+     *
+     * Edge-triggered. It fires on the beat that crosses the threshold and stays
+     * quiet until proof of life re-arms it, because the counters it reports are
+     * an account read at socket death - resetting them to re-arm the alarm would
+     * erase the evidence the death report is built from.
+     *
+     * Throwing from here says the loss could not be acted on - the socket lookup
+     * failed, the close was rejected - and re-arms the alarm, because the
+     * connection this was meant to tear down is still there. A caller that
+     * swallows its own failure instead gets one alarm for a teardown that never
+     * happened.
+     *
+     * A refusal never reaches this. The peer answered, so whatever is wrong is
+     * not the connection, and tearing one down over an application-level refusal
+     * would replace a working channel with an outage.
+     */
+    onLost: (account: HeartbeatAccount) => void;
+    /** Every settled beat, for telemetry. Receives the account at settle time. */
+    onOutcome?: (outcome: BeatOutcome, durationMs: number, account: HeartbeatAccount) => void;
+    /**
+     * Whether the channel can carry a beat at all right now - an authorized
+     * credential, an open socket. A gate that is closed skips the beat entirely
+     * rather than counting it, because a channel with nothing to protect yet has
+     * neither missed nor answered anything.
+     */
+    shouldBeat?: () => boolean;
+}
+export declare const DEFAULT_MAX_CONSECUTIVE_MISSES = 2;
+export declare const DEFAULT_MAX_CONSECUTIVE_UNANSWERED = 8;
+export declare class SocketHeartbeat {
+    private readonly options;
+    private inFlight;
+    private intervalTimer;
+    /**
+     * Identifies the current chain of scheduled beats.
+     *
+     * Separate from {@link epoch} on purpose: a reset means a new connection, not
+     * a new cadence, so retiring an in-flight beat must not also unhook the
+     * interval that would have issued the next one.
+     */
+    private intervalToken;
+    /** Whether the alarm has already been raised for the current run of misses. */
+    private lost;
+    /**
+     * Bumped by every start, stop and reset.
+     *
+     * A deadline armed for a previous connection fires after a reconnect - an
+     * intentional close does not reject the request it was waiting on - and
+     * letting it tick the new run's counters would condemn a healthy socket on
+     * the strength of a dead one's silence.
+     */
+    private epoch;
+    private state;
+    constructor(options: SocketHeartbeatOptions);
+    /** A snapshot, so a caller holding it cannot be surprised by a later beat. */
+    get account(): HeartbeatAccount;
+    /**
+     * Begins beating on a fresh account, replacing any cadence already running.
+     *
+     * Returns the way to stop *this* cadence. The disposer is inert once a later
+     * start has replaced it, which matters whenever one heartbeat is shared
+     * across successive connections: a superseded connection's teardown arrives
+     * late, and an unguarded stop would silently take the live connection's beat
+     * down with it.
+     */
+    start(): () => void;
+    stop(): void;
+    /**
+     * Starts the account over for a new connection, without touching the
+     * interval.
+     *
+     * Separate from {@link start} because a caller may learn it has a new
+     * connection before it is ready to beat on one, and the old socket's armed
+     * deadline has to stop counting the moment that happens rather than when the
+     * first new beat goes out.
+     */
+    reset(): void;
+    /**
+     * Beats once, now, outside the interval.
+     *
+     * For callers with a reason to check immediately - a user who just came back
+     * to the keyboard - rather than waiting out a cadence sized for idle
+     * connections. Safe alongside a running interval: the in-flight guard means
+     * one of the two simply skips.
+     */
+    beatNow(): Promise<void>;
+    /**
+     * Stamps inbound traffic. Call this for every message the socket delivers:
+     * it is what lets a beat starved behind a bulk transfer be told apart from
+     * one starved by a peer that is gone.
+     */
+    recordReceive(): void;
+    /** Retires whatever is in flight, so its settle cannot touch the next run. */
+    private invalidate;
+    private schedule;
+    private fire;
+    private settle;
+    private recordAnswer;
+    private recordRejection;
+    /** Traffic that arrived while this beat was waiting, not merely at some point. */
+    private receivedSince;
+    private get maxConsecutiveMisses();
+    private get maxConsecutiveUnanswered();
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/socket/heartbeat.d.ts.map

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

package/dist/socket/heartbeat.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * A paced liveness beat over a request channel.
+ *
+ * Every long-lived socket in this repo eventually needs the same thing: proof
+ * that the peer is still answering, cheaply, for as long as the connection is
+ * held. The naive version - an interval that fires a request and counts the
+ * failures - is wrong in three ways that only show up under load, and each one
+ * was found the hard way:
+ *
+ *   1. A request inherits the channel's own budget, which is the whole
+ *      caller-facing operation (minutes). A beat that borrows it cannot report a
+ *      miss inside any window a caller waits in, so it holds its own deadline.
+ *   2. Without an in-flight guard, a peer that stopped answering collects a new
+ *      pending request every interval, none of which can ever be reconciled.
+ *      The answer paces the beats, not the interval.
+ *   3. A beat's response shares the socket with bulk pushes, so a large transfer
+ *      head-of-line blocks the answer past any sane deadline while the
+ *      connection is perfectly healthy. Acting on that kills a busy socket and,
+ *      where the caller reconnects, re-sends the same payload and does it again.
+ *
+ * The third is the subtle one, and it takes two guards, because neither is
+ * sufficient alone. Inbound traffic during the beat's own wait proves the
+ * connection is alive - but a bulk RPC response is a single websocket message,
+ * and no receive event fires until its last byte lands, so that cannot be the
+ * only guard. A single missed beat therefore also gets grace: a transfer merely
+ * has to finish inside one extra interval for the next answer to get through.
+ *
+ * Both guards answer to one bound. Inbound data proves the receive path, not
+ * that the request channel answers, so no amount of either excuse may let a
+ * wedged channel hide forever: once
+ * {@link SocketHeartbeatOptions.maxConsecutiveUnanswered} beats in a row have
+ * gone unanswered, the next silence is believed whatever the reason, and the
+ * grace is bypassed with it.
+ *
+ * Extracted from the browser editor's dev-server heartbeat, which learned all
+ * of the above the hard way and is the first thing to beat with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketHeartbeat = exports.DEFAULT_MAX_CONSECUTIVE_UNANSWERED = exports.DEFAULT_MAX_CONSECUTIVE_MISSES = void 0;
+exports.DEFAULT_MAX_CONSECUTIVE_MISSES = 2;
+exports.DEFAULT_MAX_CONSECUTIVE_UNANSWERED = 8;
+/** Keeps a Node timer from holding the process open; a no-op in a browser. */
+function unref(timer) {
+    timer.unref?.();
+}
+/** This heartbeat's own deadline, so a rejection it raised is recognizable. */
+class BeatTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`beat timed out after ${timeoutMs}ms`);
+        this.name = 'BeatTimeoutError';
+    }
+}
+function describeUnknownError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'object' && error !== null) {
+        const { message } = error;
+        if (typeof message === 'string' && message.length > 0) {
+            return message;
+        }
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
+const emptyAccount = () => ({ failures: 0, lapses: 0, refusals: 0, sent: 0, unanswered: 0 });
+class SocketHeartbeat {
+    options;
+    inFlight = false;
+    intervalTimer;
+    /**
+     * Identifies the current chain of scheduled beats.
+     *
+     * Separate from {@link epoch} on purpose: a reset means a new connection, not
+     * a new cadence, so retiring an in-flight beat must not also unhook the
+     * interval that would have issued the next one.
+     */
+    intervalToken = 0;
+    /** Whether the alarm has already been raised for the current run of misses. */
+    lost = false;
+    /**
+     * Bumped by every start, stop and reset.
+     *
+     * A deadline armed for a previous connection fires after a reconnect - an
+     * intentional close does not reject the request it was waiting on - and
+     * letting it tick the new run's counters would condemn a healthy socket on
+     * the strength of a dead one's silence.
+     */
+    epoch = 0;
+    state = emptyAccount();
+    constructor(options) {
+        this.options = options;
+    }
+    /** A snapshot, so a caller holding it cannot be surprised by a later beat. */
+    get account() {
+        return { ...this.state };
+    }
+    /**
+     * Begins beating on a fresh account, replacing any cadence already running.
+     *
+     * Returns the way to stop *this* cadence. The disposer is inert once a later
+     * start has replaced it, which matters whenever one heartbeat is shared
+     * across successive connections: a superseded connection's teardown arrives
+     * late, and an unguarded stop would silently take the live connection's beat
+     * down with it.
+     */
+    start() {
+        this.stop();
+        this.reset();
+        this.schedule();
+        const token = this.intervalToken;
+        return () => {
+            if (token === this.intervalToken) {
+                this.stop();
+            }
+        };
+    }
+    stop() {
+        this.invalidate();
+        this.intervalToken += 1;
+        if (this.intervalTimer) {
+            clearTimeout(this.intervalTimer);
+            this.intervalTimer = undefined;
+        }
+    }
+    /**
+     * Starts the account over for a new connection, without touching the
+     * interval.
+     *
+     * Separate from {@link start} because a caller may learn it has a new
+     * connection before it is ready to beat on one, and the old socket's armed
+     * deadline has to stop counting the moment that happens rather than when the
+     * first new beat goes out.
+     */
+    reset() {
+        this.invalidate();
+        this.state = emptyAccount();
+    }
+    /**
+     * Beats once, now, outside the interval.
+     *
+     * For callers with a reason to check immediately - a user who just came back
+     * to the keyboard - rather than waiting out a cadence sized for idle
+     * connections. Safe alongside a running interval: the in-flight guard means
+     * one of the two simply skips.
+     */
+    async beatNow() {
+        await this.fire(this.epoch);
+    }
+    /**
+     * Stamps inbound traffic. Call this for every message the socket delivers:
+     * it is what lets a beat starved behind a bulk transfer be told apart from
+     * one starved by a peer that is gone.
+     */
+    recordReceive() {
+        this.state.lastReceivedAt = Date.now();
+    }
+    /** Retires whatever is in flight, so its settle cannot touch the next run. */
+    invalidate() {
+        this.epoch += 1;
+        this.inFlight = false;
+        this.lost = false;
+    }
+    schedule() {
+        const token = this.intervalToken;
+        this.intervalTimer = setTimeout(() => {
+            if (token !== this.intervalToken) {
+                return;
+            }
+            // Rescheduled before the beat is issued rather than after it settles, so
+            // the interval stays the gap between beats instead of drifting by however
+            // long each answer took.
+            this.schedule();
+            void this.fire(this.epoch);
+        }, this.options.intervalMs);
+        unref(this.intervalTimer);
+    }
+    async fire(armedEpoch) {
+        if (this.inFlight || this.options.shouldBeat?.() === false) {
+            return;
+        }
+        this.inFlight = true;
+        this.state.sent += 1;
+        const sentAt = Date.now();
+        this.state.pendingSince = sentAt;
+        let deadline;
+        try {
+            await Promise.race([
+                this.options.beat(),
+                new Promise((_, reject) => {
+                    deadline = setTimeout(() => reject(new BeatTimeoutError(this.options.timeoutMs)), this.options.timeoutMs);
+                    unref(deadline);
+                })
+            ]);
+            this.settle(armedEpoch, sentAt, undefined);
+        }
+        catch (error) {
+            this.settle(armedEpoch, sentAt, error ?? new Error('beat failed'));
+        }
+        finally {
+            if (deadline !== undefined) {
+                clearTimeout(deadline);
+            }
+            // Only this epoch's beat owns the guard. Releasing it after a reset would
+            // let a stale settle admit a second concurrent beat.
+            if (armedEpoch === this.epoch) {
+                this.inFlight = false;
+            }
+        }
+    }
+    settle(armedEpoch, sentAt, error) {
+        if (armedEpoch !== this.epoch) {
+            // A beat belonging to a connection that is already gone. It says nothing
+            // about the current one, so it is neither counted nor reported.
+            return;
+        }
+        const durationMs = Date.now() - sentAt;
+        // Nothing is outstanding any more: this beat is the one that was, and a
+        // stale-epoch beat returned above without touching the current run's stamp.
+        delete this.state.pendingSince;
+        const outcome = error === undefined ? this.recordAnswer() : this.recordRejection(error, sentAt);
+        const account = this.account;
+        this.options.onOutcome?.(outcome, durationMs, account);
+        if (outcome === 'miss' && !this.lost) {
+            this.lost = true;
+            try {
+                this.options.onLost(account);
+            }
+            catch {
+                // The caller could not act on the loss, so the connection it meant to
+                // tear down is still there and still not answering. Re-arm, or the one
+                // alarm this run gets has been spent on a teardown that never happened.
+                // Swallowed rather than rethrown: `settle` already runs inside the
+                // beat's own catch, and throwing from here escapes `fire` as an
+                // unhandled rejection.
+                this.lost = false;
+            }
+        }
+    }
+    recordAnswer() {
+        this.state.failures = 0;
+        this.state.lapses = 0;
+        this.state.refusals = 0;
+        this.state.unanswered = 0;
+        this.state.lastSuccessAt = Date.now();
+        this.lost = false;
+        delete this.state.lastError;
+        return 'success';
+    }
+    recordRejection(error, sentAt) {
+        const describe = this.options.describeError ?? describeUnknownError;
+        if (!(this.options.isUnanswered ?? ((cause) => cause instanceof BeatTimeoutError))(error)) {
+            // A definite answer, and recorded as one: a peer that answers is
+            // reachable, so a refusal must never close a connection over what is an
+            // application-level problem.
+            //
+            // It answers this beat and no others, so every count of what went
+            // missing is left exactly as it stands. Clearing `failures` would spend
+            // a refusal on the grace meant for a starved pong; clearing `unanswered`
+            // would hand a channel that alternates between timing out and refusing
+            // an unlimited deferral, because where inbound traffic excuses every
+            // silence that counter is the only thing left that can end one.
+            this.state.refusals += 1;
+            this.state.lastError = describe(error);
+            return 'refused';
+        }
+        // Saturating rather than growing: this is what the caller reports as the
+        // length of the silence that killed the connection, and beats keep going
+        // out after the alarm is raised - the caller still has a socket to tear
+        // down - so an unbounded count would report a run longer than the bound it
+        // is measured against.
+        this.state.unanswered = Math.min(this.state.unanswered + 1, this.maxConsecutiveUnanswered);
+        // The cause of every unanswered beat, excused or not. A lapse that leaves
+        // this stale would have the log for an excused timeout name whatever failed
+        // before it.
+        this.state.lastError = describe(error);
+        const excusable = this.state.unanswered < this.maxConsecutiveUnanswered;
+        if (excusable && this.receivedSince(sentAt)) {
+            this.state.lapses += 1;
+            // Traffic during the beat's own wait proves the connection is alive, which
+            // clears an earlier suspicion as surely as an answer would.
+            this.state.failures = 0;
+            this.lost = false;
+            return 'lapse';
+        }
+        this.state.failures += 1;
+        return excusable && this.state.failures < this.maxConsecutiveMisses ? 'grace' : 'miss';
+    }
+    /** Traffic that arrived while this beat was waiting, not merely at some point. */
+    receivedSince(sentAt) {
+        return this.state.lastReceivedAt !== undefined && this.state.lastReceivedAt >= sentAt;
+    }
+    get maxConsecutiveMisses() {
+        return this.options.maxConsecutiveMisses ?? exports.DEFAULT_MAX_CONSECUTIVE_MISSES;
+    }
+    get maxConsecutiveUnanswered() {
+        return this.options.maxConsecutiveUnanswered ?? exports.DEFAULT_MAX_CONSECUTIVE_UNANSWERED;
+    }
+}
+exports.SocketHeartbeat = SocketHeartbeat;
+//# sourceMappingURL=heartbeat.js.map

package/dist/socket/heartbeat.js.map

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

package/dist/socket/heartbeat.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=heartbeat.test.d.ts.map

package/dist/socket/heartbeat.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.test.d.ts","sourceRoot":"","sources":["../../src/socket/heartbeat.test.ts"],"names":[],"mappings":""}