seyfert 4.5.0 → 4.6.0

package/lib/websocket/discord/shard.js

@@ -22,8 +22,13 @@ class Shard {
         interval: 30e3,
         ack: true,
     };
-    isConnecting = false;
     reconnectPromise;
+    // Invalidates delayed connects and callbacks that belong to a replaced socket.
+    lifecycle = 0;
+    connectingLifecycle;
+    handledWebsocket;
+    localClose;
+    firstHeartbeatTimeout;
     bucket;
     offlineSendQueue = [];
     pendingGuilds;
@@ -76,45 +81,99 @@ class Shard {
         return this.websocket.ping();
     }
     async connect() {
-        if (this.isConnecting) {
+        if (this.connectingLifecycle === undefined)
+            this.reconnectPromise = undefined;
+        return this.connectSocket(false);
+    }
+    async connectSocket(immediate) {
+        if (this.connectingLifecycle !== undefined) {
             this.debugger?.debug(`[Shard #${this.id}] Already connecting, skipping`);
             return;
         }
-        this.isConnecting = true;
-        await this.connectTimeout.wait();
+        const lifecycle = ++this.lifecycle;
+        this.connectingLifecycle = lifecycle;
+        if (!immediate)
+            await this.connectTimeout.wait();
+        if (this.connectingLifecycle !== lifecycle)
+            return;
+        if (lifecycle !== this.lifecycle) {
+            this.connectingLifecycle = undefined;
+            return;
+        }
         if (this.isOpen) {
             this.debugger?.debug(`[Shard #${this.id}] Attempted to connect while open`);
-            this.isConnecting = false;
+            this.connectingLifecycle = undefined;
             return;
         }
-        clearTimeout(this.heart.nodeInterval);
-        this.debugger?.debug(`[Shard #${this.id}] Connecting to ${this.currentGatewayURL}`);
-        this.connectionTimeout = setTimeout(() => this.reconnect(shared_1.ShardSocketCloseCodes.Timeout), this.options.connectionTimeout);
+        this.clearHeartbeat();
+        clearTimeout(this.connectionTimeout);
+        const url = this.currentGatewayURL;
+        this.debugger?.debug(`[Shard #${this.id}] Connecting to ${url}`);
         // @ts-expect-error Use native websocket when using Bun
-        this.websocket = new basesocket_1.BaseSocket(typeof Bun === 'undefined' ? 'ws' : 'bun', this.currentGatewayURL);
-        this.websocket.onmessage = ({ data }) => {
-            this.handleMessage(data);
+        const websocket = new basesocket_1.BaseSocket(typeof Bun === 'undefined' ? 'ws' : 'bun', url);
+        this.isReady = false;
+        this.handledWebsocket = undefined;
+        this.localClose = undefined;
+        this.websocket = websocket;
+        this.connectionTimeout = setTimeout(() => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            void this.reconnectWith(shared_1.ShardSocketCloseCodes.Timeout, this.options.reconnectTimeout, 'Gateway connection timed out').catch(error => this.logger.error(error));
+        }, this.options.connectionTimeout);
+        websocket.onmessage = ({ data }) => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            try {
+                void Promise.resolve(this.handleMessage(data)).catch(error => this.logger.error(error));
+            }
+            catch (error) {
+                this.logger.error(error);
+            }
         };
-        this.websocket.onclose = (event) => this.handleClosed(event);
-        this.websocket.onerror = (event) => this.logger.error(event);
-        this.websocket.onopen = () => {
-            this.isConnecting = false;
+        websocket.onclose = (event) => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            const localClose = this.localClose?.websocket === websocket ? this.localClose : undefined;
+            void this.handleConnectionClosed({
+                code: event.code,
+                reason: event.reason,
+                locallyInitiated: !!localClose,
+                applyPolicy: localClose?.applyPolicy,
+            }, websocket).catch(error => this.logger.error(error));
+        };
+        websocket.onerror = (event) => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            this.logger.error(`Shard #${this.id}`, event);
+        };
+        websocket.onopen = () => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            this.connectingLifecycle = undefined;
             this.heart.ack = true;
             void this.options.onShardReconnect?.({ shardId: this.id });
         };
     }
     async send(force, message) {
-        this.debugger?.info(`[Shard #${this.id}] Sending: ${types_1.GatewayOpcodes[message.op]} ${JSON.stringify(message.d, (_, value) => {
-            if (typeof value === 'string')
-                return value.replaceAll(this.options.token, v => {
-                    const split = v.split('.');
-                    return `${split[0]}.${'*'.repeat(split[1].length)}.${'*'.repeat(split[2].length)}`;
-                });
-            return value;
-        }, 1)}`);
+        if (this.debugger) {
+            this.debugger.info(`[Shard #${this.id}] Sending: ${types_1.GatewayOpcodes[message.op]} ${JSON.stringify(message.d, (_, value) => {
+                if (typeof value === 'string')
+                    return value.replaceAll(this.options.token, v => {
+                        const split = v.split('.');
+                        return `${split[0]}.${'*'.repeat(split[1].length)}.${'*'.repeat(split[2].length)}`;
+                    });
+                return value;
+            }, 1)}`);
+        }
         await this.checkOffline(force);
+        const websocket = this.websocket;
         await this.bucket.acquire(force);
         await this.checkOffline(force);
+        // Authentication is connection-scoped; never deliver an Identify or Resume
+        // that finished waiting after its socket was replaced.
+        if ((message.op === types_1.GatewayOpcodes.Identify || message.op === types_1.GatewayOpcodes.Resume) &&
+            (!websocket || !this.isCurrentConnection(websocket)))
+            return;
         this.websocket?.send(JSON.stringify(message));
     }
     async identify() {
@@ -144,43 +203,110 @@ class Shard {
         });
     }
     heartbeat(requested) {
+        const websocket = this.websocket;
+        if (!websocket)
+            return;
         this.debugger?.debug(`[Shard #${this.id}] Sending ${requested ? '' : 'un'}requested heartbeat (Ack=${this.heart.ack})`);
+        if (!requested && !this.heart.ack) {
+            void this.reconnectWith(shared_1.ShardSocketCloseCodes.ZombiedConnection, 0, 'Heartbeat ACK was not received before the next interval').catch(error => this.logger.error(error));
+            return;
+        }
+        if (websocket.readyState !== 1)
+            return;
         if (!requested) {
-            if (!this.heart.ack) {
-                this.reconnect(shared_1.ShardSocketCloseCodes.ZombiedConnection);
-                return;
-            }
             this.heart.ack = false;
         }
         this.heart.lastBeat = Date.now();
-        this.websocket.send(JSON.stringify({
+        websocket.send(JSON.stringify({
             op: types_1.GatewayOpcodes.Heartbeat,
             d: this.data.resume_seq ?? null,
         }));
-        clearTimeout(this.heart.ackTimeout);
-        this.heart.ackTimeout = setTimeout(() => {
-            if (!this.heart.ack) {
-                this.reconnect(shared_1.ShardSocketCloseCodes.ZombiedConnection);
-            }
-        }, this.heart.interval * 1.5);
     }
     disconnect(code = shared_1.ShardSocketCloseCodes.Shutdown) {
-        clearTimeout(this.connectionTimeout);
-        this.connectionTimeout = undefined;
-        clearTimeout(this.heart.ackTimeout);
-        this.isConnecting = false;
+        this.lifecycle++;
+        this.reconnectPromise = undefined;
         this.debugger?.info(`[Shard #${this.id}] Disconnecting`);
-        this.close(code, 'Shard down request');
+        this.closeConnection(code, 'Shard down request', this.shouldApplyLocalClosePolicy(code));
     }
     async reconnect(code = shared_1.ShardSocketCloseCodes.Reconnect) {
-        return (this.reconnectPromise ??= (async () => {
+        return this.reconnectWith(code, this.options.reconnectTimeout, 'Shard reconnect request');
+    }
+    reconnectWith(code, wait, reason, immediate = code === shared_1.ShardSocketCloseCodes.Timeout ? false : this.resumable) {
+        if (this.reconnectPromise)
+            return this.reconnectPromise;
+        const reconnect = (async () => {
+            const lifecycle = ++this.lifecycle;
             this.debugger?.info(`[Shard #${this.id}] Reconnecting`);
-            this.disconnect(code);
-            await (0, common_1.delay)(this.options.reconnectTimeout);
-            await this.connect();
-        })().finally(() => {
-            this.reconnectPromise = undefined;
-        }));
+            this.closeConnection(code, reason);
+            if (code === shared_1.ShardSocketCloseCodes.Timeout)
+                this.resetSession();
+            if (wait > 0)
+                await (0, common_1.delay)(wait);
+            if (lifecycle !== this.lifecycle)
+                return;
+            await this.connectSocket(immediate);
+        })();
+        const settled = reconnect.finally(() => {
+            if (this.reconnectPromise === settled)
+                this.reconnectPromise = undefined;
+        });
+        this.reconnectPromise = settled;
+        return settled;
+    }
+    isCurrentConnection(websocket) {
+        return this.websocket === websocket && this.handledWebsocket !== websocket;
+    }
+    clearHeartbeat() {
+        clearTimeout(this.firstHeartbeatTimeout);
+        clearInterval(this.heart.nodeInterval);
+        this.firstHeartbeatTimeout = undefined;
+        this.heart.nodeInterval = undefined;
+    }
+    resetSession() {
+        this.data.resume_seq = null;
+        this.data.session_id = undefined;
+        this.data.resume_gateway_url = undefined;
+        this.pendingGuilds = undefined;
+    }
+    startHeartbeat(websocket) {
+        this.clearHeartbeat();
+        this.heart.ack = true;
+        this.firstHeartbeatTimeout = setTimeout(() => {
+            if (!this.isCurrentConnection(websocket))
+                return;
+            this.heartbeat(false);
+            this.heart.nodeInterval = setInterval(() => {
+                if (this.isCurrentConnection(websocket))
+                    this.heartbeat(false);
+            }, this.heart.interval);
+        }, this.heart.interval * Math.random());
+    }
+    closeConnection(code, reason, applyPolicy = false) {
+        const websocket = this.websocket;
+        if (!websocket) {
+            this.connectingLifecycle = undefined;
+            clearTimeout(this.connectionTimeout);
+            this.connectionTimeout = undefined;
+            this.clearHeartbeat();
+            this.debugger?.warn(`[Shard #${this.id}] Is not open, reason:`, reason);
+            return;
+        }
+        this.debugger?.debug(`[Shard #${this.id}] Called close with reason:`, reason);
+        // Native and custom sockets report local Close frames differently. Mark the
+        // owner before closing so both paths finalize the same lifecycle exactly once.
+        this.localClose = { websocket, applyPolicy };
+        try {
+            websocket.close(code, reason);
+        }
+        catch (error) {
+            this.localClose = undefined;
+            throw error;
+        }
+        this.connectingLifecycle = undefined;
+        if (this.handledWebsocket !== websocket) {
+            const close = { code, reason, locallyInitiated: true, applyPolicy };
+            void this.handleConnectionClosed(close, websocket).catch(error => this.logger.error(error));
+        }
     }
     flushOfflineSendQueue() {
         const queue = this.offlineSendQueue.splice(0);
@@ -194,12 +320,13 @@ class Shard {
         this.debugger?.debug(`[Shard #${this.id}]`, packet.t ? packet.t : types_1.GatewayOpcodes[packet.op], this.data.resume_seq);
         switch (packet.op) {
             case types_1.GatewayOpcodes.Hello: {
+                const websocket = this.websocket;
+                if (!websocket)
+                    return;
                 clearTimeout(this.connectionTimeout);
                 this.connectionTimeout = undefined;
-                clearInterval(this.heart.nodeInterval);
                 this.heart.interval = packet.d.heartbeat_interval;
-                this.heartbeat(false);
-                this.heart.nodeInterval = setInterval(() => this.heartbeat(false), this.heart.interval);
+                this.startHeartbeat(websocket);
                 if (this.resumable) {
                     return this.resume();
                 }
@@ -209,24 +336,18 @@ class Shard {
                 {
                     this.heart.ack = true;
                     this.heart.lastAck = Date.now();
-                    clearTimeout(this.heart.ackTimeout);
                 }
                 break;
             case types_1.GatewayOpcodes.Heartbeat:
                 this.heartbeat(true);
                 break;
             case types_1.GatewayOpcodes.Reconnect:
-                return this.reconnect();
+                return this.reconnectWith(shared_1.ShardSocketCloseCodes.Reconnect, 0, 'Discord requested a reconnect', true);
             case types_1.GatewayOpcodes.InvalidSession: {
-                if (packet.d) {
-                    if (!this.resumable) {
-                        return this.logger.fatal('This is a completely unexpected error message.');
-                    }
-                    return this.resume();
-                }
-                this.data.resume_seq = 0;
-                this.data.session_id = undefined;
-                return this.identify();
+                const canResume = packet.d && this.resumable;
+                if (!canResume)
+                    this.resetSession();
+                return this.reconnectWith(shared_1.ShardSocketCloseCodes.Reconnect, 0, canResume ? 'Discord invalidated the resumable session' : 'Discord invalidated the session');
             }
             case types_1.GatewayOpcodes.Dispatch:
                 {
@@ -342,6 +463,7 @@ class Shard {
                 }
                 break;
         }
+        return undefined;
     }
     async requestGuildMember(options) {
         const nonce = Date.now().toString() + Math.random().toString(36);
@@ -379,59 +501,74 @@ class Shard {
         });
         return promise;
     }
-    async handleClosed(close) {
+    isExpectedLocalClose(code) {
+        return (code === shared_1.ShardSocketCloseCodes.Shutdown ||
+            code === shared_1.ShardSocketCloseCodes.Reconnect ||
+            code === shared_1.ShardSocketCloseCodes.Resharding ||
+            code === shared_1.ShardSocketCloseCodes.ShutdownAll);
+    }
+    shouldApplyLocalClosePolicy(code) {
+        return !this.isExpectedLocalClose(code) && code !== shared_1.ShardSocketCloseCodes.ZombiedConnection;
+    }
+    async handleConnectionClosed(close, websocket) {
+        if (!websocket || !this.isCurrentConnection(websocket))
+            return;
+        this.handledWebsocket = websocket;
+        if (this.localClose?.websocket === websocket)
+            this.localClose = undefined;
         this.isReady = false;
-        clearInterval(this.heart.nodeInterval);
-        clearTimeout(this.heart.ackTimeout);
-        this.logger.warn(`${shared_1.ShardSocketCloseCodes[close.code] ?? types_1.GatewayCloseCodes[close.code] ?? close.code} (${close.code})`, close.reason);
+        this.connectingLifecycle = undefined;
+        clearTimeout(this.connectionTimeout);
+        this.connectionTimeout = undefined;
+        this.clearHeartbeat();
+        const closeMessage = `Shard #${this.id} closed: ${shared_1.ShardSocketCloseCodes[close.code] ?? types_1.GatewayCloseCodes[close.code] ?? close.code} (${close.code})`;
+        if (close.locallyInitiated && this.isExpectedLocalClose(close.code)) {
+            this.logger.info(closeMessage, close.reason);
+        }
+        else {
+            this.logger.warn(closeMessage, close.reason);
+        }
         try {
-            switch (close.code) {
-                case shared_1.ShardSocketCloseCodes.Shutdown:
-                case shared_1.ShardSocketCloseCodes.Reconnect:
-                case shared_1.ShardSocketCloseCodes.Resharding:
-                case shared_1.ShardSocketCloseCodes.ShutdownAll:
-                case shared_1.ShardSocketCloseCodes.ZombiedConnection:
-                    //Force disconnect, ignore
-                    break;
-                case 1000:
-                case types_1.GatewayCloseCodes.UnknownOpcode:
-                case types_1.GatewayCloseCodes.InvalidSeq:
-                case types_1.GatewayCloseCodes.SessionTimedOut:
-                // shard failed to connect, try connecting from scratch
-                case shared_1.ShardSocketCloseCodes.Timeout:
-                    {
-                        this.data.resume_seq = 0;
-                        this.data.session_id = undefined;
-                        this.data.resume_gateway_url = undefined;
-                        await this.reconnect();
-                    }
-                    break;
-                case 1001:
-                case 1006:
-                case types_1.GatewayCloseCodes.UnknownError:
-                case types_1.GatewayCloseCodes.DecodeError:
-                case types_1.GatewayCloseCodes.NotAuthenticated:
-                case types_1.GatewayCloseCodes.AlreadyAuthenticated:
-                case types_1.GatewayCloseCodes.RateLimited:
-                    {
-                        this.logger.info('Trying to reconnect');
-                        await this.reconnect();
-                    }
-                    break;
-                case types_1.GatewayCloseCodes.AuthenticationFailed:
-                case types_1.GatewayCloseCodes.DisallowedIntents:
-                case types_1.GatewayCloseCodes.InvalidAPIVersion:
-                case types_1.GatewayCloseCodes.InvalidIntents:
-                case types_1.GatewayCloseCodes.InvalidShard:
-                case types_1.GatewayCloseCodes.ShardingRequired:
-                    this.logger.fatal('Cannot reconnect');
-                    break;
-                default:
-                    {
-                        this.logger.warn('Unknown close code, trying to reconnect anyways');
-                        await this.reconnect();
-                    }
-                    break;
+            if (!close.locallyInitiated || close.applyPolicy) {
+                switch (close.code) {
+                    case 1000:
+                    case types_1.GatewayCloseCodes.UnknownOpcode:
+                    case types_1.GatewayCloseCodes.InvalidSeq:
+                    case types_1.GatewayCloseCodes.SessionTimedOut:
+                    case shared_1.ShardSocketCloseCodes.Timeout:
+                        {
+                            this.resetSession();
+                            await this.reconnect();
+                        }
+                        break;
+                    case 1001:
+                    case 1006:
+                    case types_1.GatewayCloseCodes.UnknownError:
+                    case types_1.GatewayCloseCodes.DecodeError:
+                    case types_1.GatewayCloseCodes.NotAuthenticated:
+                    case types_1.GatewayCloseCodes.AlreadyAuthenticated:
+                    case types_1.GatewayCloseCodes.RateLimited:
+                        {
+                            this.logger.info('Trying to reconnect');
+                            await this.reconnect();
+                        }
+                        break;
+                    case types_1.GatewayCloseCodes.AuthenticationFailed:
+                    case types_1.GatewayCloseCodes.DisallowedIntents:
+                    case types_1.GatewayCloseCodes.InvalidAPIVersion:
+                    case types_1.GatewayCloseCodes.InvalidIntents:
+                    case types_1.GatewayCloseCodes.InvalidShard:
+                    case types_1.GatewayCloseCodes.ShardingRequired:
+                        this.lifecycle++;
+                        this.logger.fatal(`Shard #${this.id} cannot reconnect`);
+                        break;
+                    default:
+                        {
+                            this.logger.warn(`Shard #${this.id} unknown close code (${close.code}), trying to reconnect anyways`);
+                            await this.reconnect();
+                        }
+                        break;
+                }
             }
         }
         finally {
@@ -443,23 +580,19 @@ class Shard {
         }
     }
     close(code, reason) {
-        clearInterval(this.heart.nodeInterval);
-        if (!this.websocket) {
-            return this.debugger?.warn(`[Shard #${this.id}] Is not open, reason:`, reason);
-        }
-        this.debugger?.debug(`[Shard #${this.id}] Called close with reason:`, reason);
-        this.websocket?.close(code, reason);
+        this.lifecycle++;
+        this.reconnectPromise = undefined;
+        this.closeConnection(code, reason, this.shouldApplyLocalClosePolicy(code));
     }
     handleMessage(data) {
         let packet;
         try {
-            if (data instanceof Buffer) {
+            if (data instanceof Buffer)
                 data = (0, node_zlib_1.inflateSync)(data);
-            }
             packet = JSON.parse(data);
         }
-        catch (e) {
-            this.logger.error(e);
+        catch (error) {
+            this.logger.error(error);
             return;
         }
         return this.onpacket(packet);

package/lib/websocket/discord/sharder.d.ts

@@ -1,4 +1,4 @@
-import { Logger, type MakeRequired } from '../../common';
+import { Logger, type MakePresent, type MakeRequired } from '../../common';
 import type { MakeDeepPartial } from '../../common/types/util';
 import { type GatewaySendPayload, type GatewayUpdatePresence, type GatewayVoiceStateUpdate } from '../../types';
 import { ShardManagerDefaults } from '../constants';
@@ -7,7 +7,7 @@ import { Shard } from './shard';
 import { type ShardData, type ShardManagerOptions, ShardSocketCloseCodes } from './shared';
 export declare class ShardManager extends Map<number, Shard> {
     connectQueue: ConnectQueue;
-    options: MakeRequired<ShardManagerOptions, keyof typeof ShardManagerDefaults>;
+    options: MakePresent<ShardManagerOptions, keyof typeof ShardManagerDefaults>;
     debugger?: Logger;
     constructor(options: MakeDeepPartial<ShardManagerOptions, 'resharding'>);
     get totalShards(): number;

package/lib/websocket/discord/sharder.js

@@ -156,7 +156,7 @@ class ShardManager extends Map {
     }
     /*
      * spawns buckets in order
-     * https://discord.com/developers/docs/topics/gateway#sharding-max-concurrency
+     * https://docs.discord.com/developers/topics/gateway#sharding-max-concurrency
      */
     spawnBuckets() {
         this.debugger?.info('#0 Preparing buckets');

package/lib/websocket/discord/shared.d.ts

@@ -61,7 +61,12 @@ export interface WorkerManagerOptions extends Omit<ShardManagerOptions, 'handleP
     adapter?: CustomManagerAdapter;
     workers?: number;
     /**
-     * @default 16
+     * Environment variables to add to each worker.
+     * Variables managed by Seyfert take precedence over matching keys.
+     */
+    workerEnv?: Readonly<Record<string, string>>;
+    /**
+     * @default 8
      */
     shardsPerWorker?: number;
     workerProxy?: boolean;
@@ -78,7 +83,7 @@ export interface ShardData {
     resume_seq: number | null;
     /**
      * resume_gateway_url is the url to resume the connection
-     * @link https://discord.com/developers/docs/topics/gateway#ready-event
+     * @link https://docs.discord.com/developers/topics/gateway#ready-event
      */
     resume_gateway_url?: string;
     /**

package/lib/websocket/discord/workermanager.d.ts

@@ -20,7 +20,7 @@ export declare class WorkerManager extends Map<number, (ClusterWorker | WorkerTh
         shardEnd: number;
         shardsPerWorker: number;
     }, logger?: Logger): number[][];
-    options: PickPartial<Required<WorkerManagerOptions>, 'adapter' | 'handleWorkerMessage' | 'handlePayload' | 'getRC'>;
+    options: PickPartial<Required<WorkerManagerOptions>, 'adapter' | 'handleWorkerMessage' | 'handlePayload' | 'getRC' | 'workerEnv'>;
     debugger?: Logger;
     connectQueue: ConnectQueue;
     workerQueue: (() => void)[];
@@ -53,6 +53,7 @@ export declare class WorkerManager extends Map<number, (ClusterWorker | WorkerTh
         workerId: number;
     }): Promise<number>;
     calculateShardId(guildId: string): number;
+    private createWorkerNotFoundError;
     calculateWorkerId(shardId: number): number;
     postMessage(id: number, body: ManagerMessages | WorkerHeartbeaterMessages): void;
     prepareWorkers(shards: number[][], rawResharding?: boolean): void;
@@ -111,6 +112,7 @@ export type ManagerSendCacheResult = CreateManagerMessage<'CACHE_RESULT', {
 export type ManagerSendBotReady = CreateManagerMessage<'BOT_READY'>;
 export type ManagerSendApiResponse = CreateManagerMessage<'API_RESPONSE', {
     response: any;
+    responseType?: 'arrayBuffer';
     error?: any;
     nonce: string;
 }>;