@butlerbot/sdk 0.0.23 → 0.0.25

package/dist/link/link.d.ts

@@ -88,11 +88,27 @@ export declare class Link {
     private readonly pending;
     private readonly calls;
     private socket;
+    /** Every socket this link has opened and not yet closed, by generation. */
+    private readonly sockets;
     private frameCounter;
     private currentState;
     private identity?;
-    private connecting?;
-    private readySignal?;
+    /**
+     * Which socket the callbacks below belong to.
+     *
+     * Every handler carries the generation it was made for and does nothing once that is
+     * no longer current. Without it a late `close` from a socket we have already replaced
+     * tears down its successor — one blip turning into a link that flaps for the life of
+     * the process.
+     */
+    private generation;
+    /** True from the moment a socket is created until it is open or gone. */
+    private attempting;
+    private reconnectTimer?;
+    /** Settled per attempt: this is what `connect()` awaits. */
+    private readonly attemptWaiters;
+    /** Settled when the link opens, however many attempts that takes. `ready()` awaits these. */
+    private readonly openWaiters;
     private reconnectAttempt;
     private reconnectAfterMs;
     private heartbeat?;
@@ -112,15 +128,54 @@ export declare class Link {
     get scope(): LinkScopeKind | undefined;
     on<K extends keyof LinkEvents>(event: K, listener: (...args: LinkEvents[K]) => unknown): string;
     off<K extends keyof LinkEvents>(event: K, id: string): void;
-    /** Connects, resolving once every tool and hook has been registered. */
+    /**
+     * Connects, resolving once every tool and hook has been registered.
+     *
+     * Rejects if *this* attempt fails. When `reconnect` is on the link keeps trying in
+     * the background regardless, so a caller can either await this again or just listen
+     * for the `connect` event.
+     */
     connect(): Promise<this>;
-    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    /**
+     * Resolves when the link is usable, connecting first if it has not been asked to yet.
+     *
+     * Bounded by `requestTimeoutMs`, and it never opens a socket of its own while one is
+     * in flight: the callers are hook emits and tool replies, which are worth sending now
+     * or not at all. Waiting out a long outage here used to mean a new connection per
+     * event.
+     */
     ready(): Promise<void>;
     /** Closes for good. Registrations are released server-side as the socket drops. */
     close(reason?: string): void;
+    /**
+     * Starts an attempt, but only when there is nothing to join.
+     *
+     * The single door to opening a socket: an attempt in flight, or a reconnect already
+     * waiting out its backoff, is the attempt.
+     */
+    private ensureAttempting;
     private openSocket;
     private onOpen;
+    /**
+     * Abandons a socket and treats it as closed right now.
+     *
+     * A connection that died without a close frame can take minutes to report it, or
+     * never, so the close is synthesised rather than waited for. Bumping the generation
+     * means the real event, whenever it turns up, is ignored.
+     */
+    private dropSocket;
+    /**
+     * Closes a socket this end has stopped using, whatever generation it belongs to.
+     *
+     * Every path that walks away from a socket goes through here. Forgetting one is not harmless:
+     * the server has no way to tell an abandoned connection from a live one — it has said hello,
+     * registered its tools and claimed its link id — so it keeps it, keeps serving from it, and
+     * hands the link id back and forth between it and its replacements.
+     */
+    private abandon;
     private onClose;
+    /** Retries when it is allowed to, and tells everyone waiting when it is not. */
+    private retryOrGiveUp;
     /**
      * Reconnects with full jitter on top of any delay the server asked for.
      *
@@ -128,8 +183,27 @@ export declare class Link {
      * a fixed delay produces.
      */
     private scheduleReconnect;
+    private clearReconnect;
+    /**
+     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     *
+     * A websocket can die without a close frame — a dropped route, a proxy that forgets
+     * the connection, a suspended machine — leaving both ends convinced they are
+     * connected while every frame sent into it vanishes. An unanswered ping is the only
+     * evidence this end will ever get, so it is treated as a dead connection and
+     * reconnected rather than swallowed.
+     */
     private startHeartbeat;
+    /**
+     * Never longer than the interval itself: a second ping in flight tells us nothing new.
+     *
+     * Floored so that a very short interval cannot declare a merely busy connection dead.
+     */
+    private heartbeatTimeoutMs;
     private stopHeartbeat;
+    /** Parks a caller until someone settles the list it was parked in. 0 waits forever. */
+    private wait;
+    private settleWaiters;
     private registerAll;
     private registerTools;
     private registerHook;

package/dist/link/link.js

@@ -28,8 +28,25 @@ class Link {
         this.pending = new Map();
         this.calls = new Map();
         this.socket = null;
+        /** Every socket this link has opened and not yet closed, by generation. */
+        this.sockets = new Map();
         this.frameCounter = 0;
         this.currentState = "idle";
+        /**
+         * Which socket the callbacks below belong to.
+         *
+         * Every handler carries the generation it was made for and does nothing once that is
+         * no longer current. Without it a late `close` from a socket we have already replaced
+         * tears down its successor — one blip turning into a link that flaps for the life of
+         * the process.
+         */
+        this.generation = 0;
+        /** True from the moment a socket is created until it is open or gone. */
+        this.attempting = false;
+        /** Settled per attempt: this is what `connect()` awaits. */
+        this.attemptWaiters = [];
+        /** Settled when the link opens, however many attempts that takes. `ready()` awaits these. */
+        this.openWaiters = [];
         this.reconnectAttempt = 0;
         this.reconnectAfterMs = 0;
         this.closedByUs = false;
@@ -107,58 +124,113 @@ class Link {
     // =============================================
     // LIFECYCLE
     // =============================================
-    /** Connects, resolving once every tool and hook has been registered. */
+    /**
+     * Connects, resolving once every tool and hook has been registered.
+     *
+     * Rejects if *this* attempt fails. When `reconnect` is on the link keeps trying in
+     * the background regardless, so a caller can either await this again or just listen
+     * for the `connect` event.
+     */
     connect() {
         if (this.currentState === "open")
             return Promise.resolve(this);
-        if (this.connecting)
-            return this.connecting;
         this.closedByUs = false;
-        this.connecting = this.openSocket().then(() => this, error => {
-            this.connecting = undefined;
-            throw error;
-        });
-        return this.connecting;
+        if (this.currentState === "closed")
+            this.currentState = "idle";
+        // Joins whatever attempt is already in flight — or already scheduled — rather than
+        // racing a second socket against it.
+        const waited = this.wait(this.attemptWaiters, 0);
+        this.ensureAttempting();
+        return waited.then(() => this);
     }
-    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    /**
+     * Resolves when the link is usable, connecting first if it has not been asked to yet.
+     *
+     * Bounded by `requestTimeoutMs`, and it never opens a socket of its own while one is
+     * in flight: the callers are hook emits and tool replies, which are worth sending now
+     * or not at all. Waiting out a long outage here used to mean a new connection per
+     * event.
+     */
     async ready() {
         if (this.currentState === "open")
             return;
         if (this.currentState === "closed")
-            throw new Error("This link has been closed.");
-        await this.connect();
+            throw new protocol_1.LinkError("closed", "This link has been closed.");
+        const waited = this.wait(this.openWaiters, this.options.requestTimeoutMs);
+        this.ensureAttempting();
+        await waited;
     }
     /** Closes for good. Registrations are released server-side as the socket drops. */
     close(reason = "client closed") {
+        const closed = new protocol_1.LinkError("closed", "The link was closed.");
         this.closedByUs = true;
         this.currentState = "closed";
+        // Orphans the live socket's callbacks, so its close cannot reopen anything.
+        this.generation += 1;
+        this.attempting = false;
         this.stopHeartbeat();
-        this.failPending(new protocol_1.LinkError("closed", "The link was closed."));
-        this.socket?.close(1000, reason);
+        this.clearReconnect();
+        this.failPending(closed);
+        this.settleWaiters(this.attemptWaiters, closed);
+        this.settleWaiters(this.openWaiters, closed);
+        // Every socket, not just the current one: a link that is being closed for good must not
+        // leave anything of itself attached to the server.
+        for (const generation of [...this.sockets.keys()])
+            this.abandon(generation, reason);
         this.socket = null;
-        this.connecting = undefined;
-        this.readySignal = undefined;
+    }
+    /**
+     * Starts an attempt, but only when there is nothing to join.
+     *
+     * The single door to opening a socket: an attempt in flight, or a reconnect already
+     * waiting out its backoff, is the attempt.
+     */
+    ensureAttempting() {
+        if (this.closedByUs || this.currentState === "open")
+            return;
+        if (this.attempting || this.reconnectTimer)
+            return;
+        this.openSocket();
     }
     openSocket() {
         this.currentState = "connecting";
-        const signal = deferred();
-        this.readySignal = signal;
+        this.attempting = true;
+        const generation = ++this.generation;
         const { url, protocols } = (0, socket_1.buildHandshake)(this.options.serverUrl, "link", this.options.apiKey);
         this.debug(`connecting to ${url.replace(/api_key=[^&]+/, "api_key=***")}`);
         try {
-            this.socket = this.options.socketFactory(url, protocols, {
-                onOpen: () => this.onOpen(),
-                onMessage: (data) => this.onMessage(data),
-                onClose: (code, reason) => this.onClose(code, reason),
-                onError: (error) => this.emitter.emit("error", asError(error)),
+            const socket = this.options.socketFactory(url, protocols, {
+                onOpen: () => this.onOpen(generation),
+                onMessage: (data) => { if (generation === this.generation)
+                    this.onMessage(data); },
+                onClose: (code, reason) => {
+                    this.sockets.delete(generation);
+                    this.onClose(generation, code, reason);
+                },
+                onError: (error) => { if (generation === this.generation)
+                    this.emitter.emit("error", asError(error)); },
             });
+            // Held by generation, not only as `this.socket`, so a socket that stops being the
+            // current one can still be closed. One that is merely forgotten stays open at the far
+            // end: it has already said hello and registered its tools, so the server goes on serving
+            // it, and it answers websocket pings forever because the network stack does that for it.
+            this.sockets.set(generation, socket);
+            this.socket = socket;
         }
         catch (error) {
-            signal.reject(asError(error));
+            // A factory that throws never produces a close event, so this failure is
+            // reported and retried from here instead.
+            const failure = asError(error);
+            this.socket = null;
+            this.attempting = false;
+            this.emitter.emit("error", failure);
+            this.settleWaiters(this.attemptWaiters, failure);
+            this.retryOrGiveUp(failure);
         }
-        return signal.promise;
     }
-    onOpen() {
+    onOpen(generation) {
+        if (generation !== this.generation)
+            return;
         // The handshake declares who we are; nothing else may be sent before it.
         void this.exchange("hello", {
             linkId: this.options.linkId,
@@ -169,39 +241,106 @@ class Link {
             isDone: (frame) => frame.type === "welcome",
         }).then(async (frame) => {
             const welcome = frame.payload;
-            this.identity = { connectionId: welcome.connectionId, scope: welcome.scope };
+            const identity = { connectionId: welcome.connectionId, scope: welcome.scope };
+            this.identity = identity;
             await this.registerAll();
+            // Registration is several round trips; the socket may have gone during them. It is fully
+            // registered at the server by now, so abandoning it quietly would leave it serving tools
+            // nothing here will ever answer.
+            if (generation !== this.generation)
+                return this.abandon(generation, "superseded during handshake");
+            this.attempting = false;
             this.currentState = "open";
             this.reconnectAttempt = 0;
             this.reconnectAfterMs = 0;
-            this.startHeartbeat();
-            this.readySignal?.resolve();
-            this.emitter.emit("connect", this.identity);
+            this.startHeartbeat(generation);
+            this.settleWaiters(this.attemptWaiters);
+            this.settleWaiters(this.openWaiters);
+            this.emitter.emit("connect", identity);
         }).catch((error) => {
+            if (generation !== this.generation)
+                return this.abandon(generation, "superseded during handshake");
             this.emitter.emit("error", error);
-            // A rejected claim or an unsupported protocol will not fix itself by
-            // trying again, so this stops rather than looping.
-            this.closedByUs = true;
-            this.readySignal?.reject(error);
-            this.socket?.close(1000, "handshake failed");
+            this.settleWaiters(this.attemptWaiters, error);
+            // Only the server saying "do not come back" stops us: a rejected claim or an
+            // unsupported protocol will not fix itself. Everything else that can land here —
+            // a timeout, a socket dropped mid-registration, a transient server error — is
+            // precisely what reconnecting is for. Treating all of it as fatal left the link
+            // dead for the life of the process.
+            if (error instanceof protocol_1.LinkError && error.fatal)
+                this.closedByUs = true;
+            this.dropSocket(generation, 1000, "handshake failed");
         });
     }
-    onClose(code, reason) {
+    /**
+     * Abandons a socket and treats it as closed right now.
+     *
+     * A connection that died without a close frame can take minutes to report it, or
+     * never, so the close is synthesised rather than waited for. Bumping the generation
+     * means the real event, whenever it turns up, is ignored.
+     */
+    dropSocket(generation, code, reason) {
+        if (generation !== this.generation)
+            return;
+        this.onClose(generation, code, reason);
+        // 1006 is reserved and rejected by browsers; anything else we raise is a valid
+        // application code.
+        this.abandon(generation, reason, code === 1006 ? 1000 : code);
+    }
+    /**
+     * Closes a socket this end has stopped using, whatever generation it belongs to.
+     *
+     * Every path that walks away from a socket goes through here. Forgetting one is not harmless:
+     * the server has no way to tell an abandoned connection from a live one — it has said hello,
+     * registered its tools and claimed its link id — so it keeps it, keeps serving from it, and
+     * hands the link id back and forth between it and its replacements.
+     */
+    abandon(generation, reason, code = 1000) {
+        const socket = this.sockets.get(generation);
+        if (!socket)
+            return;
+        this.sockets.delete(generation);
+        if (this.socket === socket)
+            this.socket = null;
+        try {
+            socket.close(code, reason);
+        }
+        catch {
+            // Already gone, which is the outcome we wanted anyway.
+        }
+    }
+    onClose(generation, code, reason) {
+        if (generation !== this.generation)
+            return;
+        // Whatever else this socket has to say is now somebody else's news.
+        this.generation += 1;
         const willReconnect = this.options.reconnect && !this.closedByUs;
+        const error = new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`);
         this.socket = null;
         this.identity = undefined;
-        this.connecting = undefined;
+        this.attempting = false;
         this.currentState = willReconnect ? "connecting" : "closed";
         // Nothing about subscriptions survives a socket: the server re-sends the set on every
         // connect, so holding the old one would only risk reporting against ids that are gone.
         this.subscriptionStore.reset();
         this.stopHeartbeat();
-        this.failPending(new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`));
+        this.failPending(error);
+        this.settleWaiters(this.attemptWaiters, error);
         this.emitter.emit("disconnect", { code, reason, willReconnect });
-        this.readySignal?.reject(new protocol_1.LinkError("disconnected", `The link disconnected (${code}).`));
-        this.readySignal = undefined;
         if (willReconnect)
             this.scheduleReconnect();
+        else
+            this.settleWaiters(this.openWaiters, error);
+    }
+    /** Retries when it is allowed to, and tells everyone waiting when it is not. */
+    retryOrGiveUp(error) {
+        if (this.options.reconnect && !this.closedByUs) {
+            this.currentState = "connecting";
+            this.scheduleReconnect();
+            return;
+        }
+        this.currentState = "closed";
+        this.settleWaiters(this.openWaiters, error);
     }
     /**
      * Reconnects with full jitter on top of any delay the server asked for.
@@ -210,33 +349,97 @@ class Link {
      * a fixed delay produces.
      */
     scheduleReconnect() {
+        this.clearReconnect();
         const ceiling = Math.min(this.options.maxReconnectDelayMs, this.options.minReconnectDelayMs * 2 ** this.reconnectAttempt);
         const delay = this.reconnectAfterMs + Math.random() * ceiling;
         this.reconnectAttempt += 1;
         this.debug(`reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempt})`);
-        const timer = setTimeout(() => {
-            if (this.closedByUs)
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.closedByUs || this.currentState === "open" || this.attempting)
                 return;
-            this.openSocket().catch(error => this.emitter.emit("error", asError(error)));
+            this.openSocket();
         }, delay);
-        unref(timer);
+        unref(this.reconnectTimer);
     }
-    startHeartbeat() {
+    clearReconnect() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+    }
+    /**
+     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     *
+     * A websocket can die without a close frame — a dropped route, a proxy that forgets
+     * the connection, a suspended machine — leaving both ends convinced they are
+     * connected while every frame sent into it vanishes. An unanswered ping is the only
+     * evidence this end will ever get, so it is treated as a dead connection and
+     * reconnected rather than swallowed.
+     */
+    startHeartbeat(generation) {
         if (!this.options.heartbeatMs)
             return;
+        this.stopHeartbeat();
         this.heartbeat = setInterval(() => {
+            if (generation !== this.generation)
+                return;
             // The reply is consumed by the exchange, so it never reaches log listeners.
-            this.exchange("ping", {}, { isDone: (frame) => frame.type === "log" })
-                .catch(() => undefined);
+            this.exchange("ping", {}, {
+                awaitReady: false,
+                isDone: (frame) => frame.type === "log",
+                timeoutMs: this.heartbeatTimeoutMs(),
+            }).catch(() => {
+                if (generation !== this.generation)
+                    return;
+                this.debug("heartbeat went unanswered, treating the connection as dead");
+                this.dropSocket(generation, 4000, "heartbeat timeout");
+            });
         }, this.options.heartbeatMs);
         unref(this.heartbeat);
     }
+    /**
+     * Never longer than the interval itself: a second ping in flight tells us nothing new.
+     *
+     * Floored so that a very short interval cannot declare a merely busy connection dead.
+     */
+    heartbeatTimeoutMs() {
+        return Math.max(250, Math.min(this.options.requestTimeoutMs, this.options.heartbeatMs));
+    }
     stopHeartbeat() {
         if (this.heartbeat)
             clearInterval(this.heartbeat);
         this.heartbeat = undefined;
     }
     // =============================================
+    // WAITING
+    // =============================================
+    /** Parks a caller until someone settles the list it was parked in. 0 waits forever. */
+    wait(waiters, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            if (timeoutMs > 0) {
+                waiter.timer = setTimeout(() => {
+                    const index = waiters.indexOf(waiter);
+                    if (index >= 0)
+                        waiters.splice(index, 1);
+                    reject(new protocol_1.LinkError("timeout", `The link was not open within ${timeoutMs}ms.`));
+                }, timeoutMs);
+                unref(waiter.timer);
+            }
+            waiters.push(waiter);
+        });
+    }
+    settleWaiters(waiters, error) {
+        for (const waiter of waiters.splice(0, waiters.length)) {
+            if (waiter.timer)
+                clearTimeout(waiter.timer);
+            if (error)
+                waiter.reject(error);
+            else
+                waiter.resolve();
+        }
+    }
+    // =============================================
     // REGISTRATION
     // =============================================
     async registerAll() {
@@ -269,7 +472,13 @@ class Link {
      * that was valid a moment ago is a race, not a bug worth complaining about.
      */
     async reportHookEvent(hookId, event, payload, chosenIds) {
-        await this.ready();
+        // Not `ready()`: a report is only worth anything now, and while the link is down the
+        // subscription set is empty anyway — so waiting would mean holding a busy guild's
+        // events open to match them against nothing.
+        if (this.currentState !== "open") {
+            this.debug(`dropped ${event}: the link is not connected`);
+            return [];
+        }
         const sourceId = this.hooks.get(hookId)?.sourceId ?? hookId;
         // Explicit ids are still checked against what this link actually holds. Not out of distrust of
         // the caller — the server checks again anyway — but because an id it was never given can only
@@ -490,15 +699,6 @@ exports.Link = Link;
 // =============================================
 // HELPERS
 // =============================================
-function deferred() {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
-    // Rejections are surfaced through connect() and the error event; an unobserved
-    // one here must not take the process down.
-    promise.catch(() => undefined);
-    return { promise, resolve, reject };
-}
 function asError(value) {
     if (value instanceof Error)
         return value;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.23",
+	"version": "0.0.25",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",