@buape/carbon 0.14.0 → 0.16.0

package/dist/src/plugins/gateway/GatewayPlugin.js

@@ -1,14 +1,18 @@
 import { EventEmitter } from "node:events";
-import WebSocket from "ws";
+import { createRequire } from "node:module";
 import { Plugin } from "../../abstracts/Plugin.js";
-import { ListenerEvent } from "../../types/index.js";
 import { BabyCache } from "./BabyCache.js";
 import { InteractionEventListener } from "./InteractionEventListener.js";
-import { GatewayCloseCodes, GatewayIntents, GatewayOpcodes } from "./types.js";
+import { fatalGatewayCloseCodes, GatewayIntents, GatewayOpcodes, listenerEvents, nonResumableGatewayCloseCodes, reconnectDefaults } from "./types.js";
 import { startHeartbeat, stopHeartbeat } from "./utils/heartbeat.js";
 import { ConnectionMonitor } from "./utils/monitor.js";
 import { createIdentifyPayload, createRequestGuildMembersPayload, createResumePayload, createUpdatePresencePayload, createUpdateVoiceStatePayload, validatePayload } from "./utils/payload.js";
 import { GatewayRateLimit } from "./utils/rateLimit.js";
+const textDecoder = new TextDecoder();
+const socketOpenState = 1;
+const nodeRequire = typeof process !== "undefined" && process.versions?.node
+    ? createRequire(import.meta.url)
+    : null;
 export class GatewayPlugin extends Plugin {
     id = "gateway";
     client;
@@ -18,6 +22,7 @@ export class GatewayPlugin extends Plugin {
     monitor;
     rateLimit;
     heartbeatInterval;
+    firstHeartbeatTimeout;
     sequence = null;
     lastHeartbeatAck = true;
     emitter;
@@ -30,15 +35,20 @@ export class GatewayPlugin extends Plugin {
     babyCache;
     reconnectTimeout;
     isConnecting = false;
+    socketGeneration = 0;
+    shouldReconnect = false;
+    nextConnectionShouldResume = false;
+    silentSocketClosures = new WeakSet();
+    consecutiveResumeFailures = 0;
     constructor(options, gatewayInfo) {
         super();
         this.options = {
             reconnect: {
-                maxAttempts: 5,
-                baseDelay: 1000,
-                maxDelay: 30000
+                ...reconnectDefaults,
+                ...options.reconnect
             },
-            ...options
+            ...options,
+            intents: options.intents ?? 0
         };
         this.state = {
             sequence: null,
@@ -58,305 +68,265 @@ export class GatewayPlugin extends Plugin {
             ? this.pings.reduce((a, b) => a + b, 0) / this.pings.length
             : null;
     }
+    /**
+     * Bootstraps gateway metadata and opens the initial websocket connection.
+     */
     async registerClient(client) {
         this.client = client;
         if (!this.gatewayInfo) {
+            let response;
             try {
-                const response = await fetch("https://discord.com/api/v10/gateway/bot", {
+                response = await fetch("https://discord.com/api/v10/gateway/bot", {
                     headers: {
                         Authorization: `Bot ${client.options.token}`
                     }
                 });
-                this.gatewayInfo = (await response.json());
             }
             catch (error) {
-                throw new Error(`Failed to get gateway information from Discord: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to get gateway information from Discord: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
+            if (!response.ok) {
+                throw new Error(`Failed to get gateway information from Discord: ${response.status} ${response.statusText}`);
+            }
+            this.gatewayInfo = (await response.json());
         }
-        // Set shard information on the client
         if (this.options.shard) {
             client.shardId = this.options.shard[0];
             client.totalShards = this.options.shard[1];
         }
         if (this.options.autoInteractions) {
-            this.client?.listeners.push(new InteractionEventListener());
+            this.client.registerListener(new InteractionEventListener());
         }
-        this.connect();
+        this.shouldReconnect = true;
+        this.connect(false);
     }
+    /**
+     * Opens a new websocket connection and prepares either IDENTIFY or RESUME on HELLO.
+     */
     connect(resume = false) {
-        if (this.isConnecting)
+        if (this.isConnecting) {
             return;
-        if (this.reconnectTimeout) {
-            clearTimeout(this.reconnectTimeout);
-            this.reconnectTimeout = undefined;
         }
-        this.ws?.close();
+        this.shouldReconnect = true;
+        this.clearReconnectTimeout();
+        stopHeartbeat(this);
+        this.lastHeartbeatAck = true;
+        const oldSocket = this.ws;
+        if (oldSocket) {
+            this.silentSocketClosures.add(oldSocket);
+            this.closeSocketImmediately(oldSocket);
+        }
         const baseUrl = resume && this.state.resumeGatewayUrl
             ? this.state.resumeGatewayUrl
             : (this.gatewayInfo?.url ??
                 this.options.url ??
                 "wss://gateway.discord.gg/");
         const url = this.ensureGatewayParams(baseUrl);
+        this.nextConnectionShouldResume = resume;
+        this.socketGeneration++;
         this.ws = this.createWebSocket(url);
         this.isConnecting = true;
+        this.isConnected = false;
         this.setupWebSocket();
     }
+    /**
+     * Stops heartbeats, clears reconnect state, and closes the active socket intentionally.
+     */
     disconnect() {
+        this.shouldReconnect = false;
+        this.clearReconnectTimeout();
         stopHeartbeat(this);
+        this.lastHeartbeatAck = true;
         this.monitor.resetUptime();
-        this.ws?.close();
-        this.ws = null;
-        if (this.reconnectTimeout) {
-            clearTimeout(this.reconnectTimeout);
-            this.reconnectTimeout = undefined;
+        this.rateLimit.reset();
+        if (this.ws) {
+            this.silentSocketClosures.add(this.ws);
+            this.ws.close(1000, "Client disconnect");
         }
+        this.ws = null;
         this.isConnecting = false;
         this.isConnected = false;
+        this.reconnectAttempts = 0;
+        this.consecutiveResumeFailures = 0;
         this.pings = [];
     }
+    /**
+     * Creates the websocket instance for a gateway URL. Override in tests if needed.
+     */
     createWebSocket(url) {
         if (!url) {
             throw new Error("Gateway URL is required");
         }
-        return new WebSocket(url);
+        const socket = this.options.webSocketFactory
+            ? this.options.webSocketFactory(url)
+            : (() => {
+                if (nodeRequire) {
+                    try {
+                        const wsModule = nodeRequire("ws");
+                        const nodeWebSocket = typeof wsModule.WebSocket === "function"
+                            ? wsModule.WebSocket
+                            : typeof wsModule.default === "function"
+                                ? wsModule.default
+                                : null;
+                        if (nodeWebSocket) {
+                            return new nodeWebSocket(url);
+                        }
+                    }
+                    catch {
+                        // fall through to global WebSocket
+                    }
+                }
+                if (typeof globalThis.WebSocket === "function") {
+                    return new globalThis.WebSocket(url);
+                }
+                return null;
+            })();
+        if (!socket) {
+            throw new Error("No WebSocket implementation available. Provide GatewayPluginOptions.webSocketFactory or install 'ws'.");
+        }
+        if ("binaryType" in socket) {
+            try {
+                ;
+                socket.binaryType = "arraybuffer";
+            }
+            catch {
+                // Ignore runtimes that expose a readonly binaryType.
+            }
+        }
+        return socket;
     }
+    /**
+     * Attaches websocket lifecycle handlers for open, message, close, and error.
+     */
     setupWebSocket() {
-        if (!this.ws)
+        if (!this.ws) {
             return;
-        let closed = false;
-        this.ws.on("open", () => {
+        }
+        const socket = this.ws;
+        const generation = this.socketGeneration;
+        this.onSocketEvent(socket, "open", () => {
+            if (!this.isCurrentSocket(socket, generation)) {
+                return;
+            }
             this.isConnecting = false;
-            this.reconnectAttempts = 0;
-            this.emitter.emit("debug", "WebSocket connection opened");
+            this.emitter.emit("debug", "Gateway websocket opened");
         });
-        this.ws.on("message", (data) => {
+        this.onSocketEvent(socket, "message", (incoming) => {
+            if (!this.isCurrentSocket(socket, generation)) {
+                return;
+            }
             this.monitor.recordMessageReceived();
-            const payload = validatePayload(data.toString());
+            const payloadText = this.getMessageText(incoming);
+            const payload = payloadText ? validatePayload(payloadText) : null;
             if (!payload) {
                 this.monitor.recordError();
-                this.emitter.emit("error", new Error("Invalid gateway payload received"));
+                this.emitter.emit("error", new Error("Invalid gateway payload"));
                 return;
             }
-            const { op, d, s, t } = payload;
-            if (s !== null && s !== undefined) {
-                this.sequence = s;
-                this.state.sequence = s;
+            if (payload.s !== null && payload.s !== undefined) {
+                this.sequence = payload.s;
+                this.state.sequence = payload.s;
             }
-            switch (op) {
-                case GatewayOpcodes.Hello: {
-                    const helloData = d;
-                    const interval = helloData.heartbeat_interval;
-                    startHeartbeat(this, {
-                        interval,
-                        reconnectCallback: () => {
-                            if (closed) {
-                                throw new Error("Attempted to reconnect zombie connection after disconnecting first (this shouldn't be possible)");
-                            }
-                            closed = true;
-                            this.handleZombieConnection();
-                        }
-                    });
-                    if (this.canResume()) {
-                        this.resume();
-                    }
-                    else {
-                        this.identify();
-                    }
+            switch (payload.op) {
+                case GatewayOpcodes.Hello:
+                    this.handleHello(payload.d, generation);
                     break;
-                }
-                case GatewayOpcodes.HeartbeatAck: {
-                    this.lastHeartbeatAck = true;
-                    this.monitor.recordHeartbeatAck();
-                    // Record the latency for ping averaging
-                    const latency = this.monitor.getMetrics().latency;
-                    if (latency > 0) {
-                        this.pings.push(latency);
-                        // Keep only the last 10 pings to prevent unbounded growth
-                        if (this.pings.length > 10) {
-                            this.pings.shift();
-                        }
-                    }
+                case GatewayOpcodes.HeartbeatAck:
+                    this.handleHeartbeatAck();
                     break;
-                }
-                case GatewayOpcodes.Heartbeat: {
-                    this.lastHeartbeatAck = false;
-                    this.send({
-                        op: GatewayOpcodes.Heartbeat,
-                        d: this.sequence
-                    });
+                case GatewayOpcodes.Heartbeat:
+                    this.sendHeartbeatNow();
                     break;
-                }
-                case GatewayOpcodes.Dispatch: {
-                    const payload1 = payload;
-                    const t1 = payload1.t;
-                    try {
-                        if (!Object.values(ListenerEvent).includes(t1)) {
-                            break;
-                        }
-                        if (t1 === "READY") {
-                            const readyData = d;
-                            this.state.sessionId = readyData.session_id;
-                            this.state.resumeGatewayUrl = readyData.resume_gateway_url;
-                        }
-                        if (t && this.client) {
-                            if (!this.options.eventFilter || this.options.eventFilter?.(t1)) {
-                                if (t1 === "READY" || t1 === "RESUMED") {
-                                    this.isConnected = true;
-                                }
-                                if (t1 === "READY") {
-                                    const readyData = d;
-                                    readyData.guilds.forEach((guild) => {
-                                        this.babyCache.setGuild(guild.id, {
-                                            available: false,
-                                            lastEvent: Date.now()
-                                        });
-                                    });
-                                }
-                                if (t1 === "GUILD_CREATE") {
-                                    const guildCreateData = d;
-                                    const existingGuild = this.babyCache.getGuild(guildCreateData.id);
-                                    if (existingGuild && !existingGuild.available) {
-                                        this.babyCache.setGuild(guildCreateData.id, {
-                                            available: true,
-                                            lastEvent: Date.now()
-                                        });
-                                        this.client.eventHandler.handleEvent({
-                                            ...guildCreateData,
-                                            clientId: this.client.options.clientId
-                                        }, "GUILD_AVAILABLE");
-                                        break;
-                                    }
-                                }
-                                if (t1 === "GUILD_DELETE") {
-                                    const guildDeleteData = d;
-                                    const existingGuild = this.babyCache.getGuild(guildDeleteData.id);
-                                    if (existingGuild?.available && guildDeleteData.unavailable) {
-                                        this.babyCache.setGuild(guildDeleteData.id, {
-                                            available: false,
-                                            lastEvent: Date.now()
-                                        });
-                                        this.client.eventHandler.handleEvent({
-                                            ...guildDeleteData,
-                                            clientId: this.client.options.clientId
-                                        }, "GUILD_UNAVAILABLE");
-                                        break;
-                                    }
-                                }
-                                this.client.eventHandler.handleEvent({ ...payload1.d, clientId: this.client.options.clientId }, t1);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        console.error(err);
-                    }
+                case GatewayOpcodes.Dispatch:
+                    this.handleDispatch(payload);
                     break;
-                }
-                case GatewayOpcodes.InvalidSession: {
-                    const canResume = Boolean(d);
-                    setTimeout(() => {
-                        closed = true;
-                        if (canResume && this.canResume()) {
-                            this.connect(true);
-                        }
-                        else {
-                            this.state.sessionId = null;
-                            this.state.resumeGatewayUrl = null;
-                            this.state.sequence = null;
-                            this.sequence = null;
-                            this.pings = [];
-                            this.connect(false);
-                        }
-                    }, 5000);
+                case GatewayOpcodes.InvalidSession:
+                    this.handleInvalidSession(payload.d);
                     break;
-                }
                 case GatewayOpcodes.Reconnect:
-                    if (closed) {
-                        throw new Error("Attempted to reconnect gateway after disconnecting first (this shouldn't be possible)");
-                    }
-                    closed = true;
-                    this.state.sequence = this.sequence;
-                    this.ws?.close();
-                    this.handleReconnect();
+                    this.handleReconnectOpcode();
                     break;
             }
         });
-        this.ws.on("close", (code, _reason) => {
+        this.onSocketEvent(socket, "close", (incoming) => {
+            if (!this.isCurrentSocket(socket, generation)) {
+                return;
+            }
             this.isConnecting = false;
-            this.emitter.emit("debug", `WebSocket connection closed with code ${code}`);
-            this.monitor.recordReconnect();
-            if (closed)
+            this.isConnected = false;
+            stopHeartbeat(this);
+            this.lastHeartbeatAck = true;
+            const wasSilentClose = this.silentSocketClosures.has(socket);
+            if (wasSilentClose) {
+                this.silentSocketClosures.delete(socket);
                 return;
-            closed = true;
+            }
+            const code = this.getCloseCode(incoming);
+            this.monitor.recordReconnect();
+            this.emitter.emit("debug", `Gateway websocket closed: ${code}`);
             this.handleClose(code);
         });
-        this.ws.on("error", (error) => {
+        this.onSocketEvent(socket, "error", (incoming) => {
+            if (!this.isCurrentSocket(socket, generation)) {
+                return;
+            }
             this.isConnecting = false;
             this.monitor.recordError();
-            this.emitter.emit("error", error);
+            this.emitter.emit("error", this.getSocketError(incoming));
         });
     }
-    handleReconnectionAttempt(options) {
-        const { maxAttempts = 5, baseDelay = 1000, maxDelay = 30000 } = this.options.reconnect ?? {};
-        if (this.reconnectAttempts >= maxAttempts) {
-            this.emitter.emit("error", new Error(`Max reconnect attempts (${maxAttempts}) reached${options.code ? ` after code ${options.code}` : ""}`));
-            this.monitor.destroy();
+    /**
+     * Handles close codes and decides whether reconnection should resume or re-identify.
+     */
+    handleClose(code) {
+        if (!this.shouldReconnect) {
             return;
         }
-        if (options.code) {
-            switch (options.code) {
-                case GatewayCloseCodes.AuthenticationFailed:
-                case GatewayCloseCodes.InvalidAPIVersion:
-                case GatewayCloseCodes.InvalidIntents:
-                case GatewayCloseCodes.DisallowedIntents:
-                case GatewayCloseCodes.ShardingRequired: {
-                    this.emitter.emit("error", new Error(`Fatal Gateway error: ${options.code}`));
-                    this.reconnectAttempts = maxAttempts;
-                    this.monitor.destroy();
-                    return;
-                }
-                case GatewayCloseCodes.InvalidSeq:
-                case GatewayCloseCodes.SessionTimedOut: {
-                    this.state.sessionId = null;
-                    this.state.resumeGatewayUrl = null;
-                    this.state.sequence = null;
-                    this.sequence = null;
-                    this.pings = [];
-                    options.forceNoResume = true;
-                    break;
-                }
-            }
-        }
-        if (this.reconnectTimeout || this.isConnecting) {
+        if (fatalGatewayCloseCodes.has(code)) {
+            this.shouldReconnect = false;
+            this.emitter.emit("error", new Error(`Fatal gateway close code: ${code}`));
+            this.disconnect();
             return;
         }
-        this.disconnect();
-        const backoffTime = Math.min(baseDelay * 2 ** this.reconnectAttempts, maxDelay);
-        this.reconnectAttempts++;
-        if (options.isZombieConnection) {
-            this.monitor.recordZombieConnection();
+        if (nonResumableGatewayCloseCodes.has(code)) {
+            this.resetSessionState();
         }
-        const shouldResume = !options.forceNoResume && this.canResume();
-        this.emitter.emit("debug", `${shouldResume ? "Attempting resume" : "Reconnecting"} with backoff: ${backoffTime}ms${options.code ? ` after code ${options.code}` : ""}`);
-        this.reconnectTimeout = setTimeout(() => {
-            this.reconnectTimeout = undefined;
-            this.connect(shouldResume);
-        }, backoffTime);
-    }
-    handleClose(code) {
-        this.handleReconnectionAttempt({ code });
+        this.scheduleReconnect({
+            code,
+            reason: "close",
+            preferResume: !nonResumableGatewayCloseCodes.has(code)
+        });
     }
+    /**
+     * Handles missing heartbeat acknowledgements by forcing a reconnect flow.
+     */
     handleZombieConnection() {
-        this.handleReconnectionAttempt({ isZombieConnection: true });
+        this.monitor.recordZombieConnection();
+        this.scheduleReconnect({
+            reason: "zombie",
+            preferResume: true
+        });
+        this.reconnectWithSocketRestart();
     }
+    /**
+     * Compatibility wrapper that maps to reconnect opcode handling.
+     */
     handleReconnect() {
-        this.handleReconnectionAttempt({});
+        this.handleReconnectOpcode();
     }
+    /**
+     * Returns whether session_id and sequence are both available for RESUME.
+     */
     canResume() {
         return Boolean(this.state.sessionId && this.sequence !== null);
     }
+    /**
+     * Sends a RESUME payload using cached session_id and latest sequence.
+     */
     resume() {
-        if (!this.client || !this.state.sessionId || this.sequence === null)
+        if (!this.client || !this.state.sessionId || this.sequence === null) {
             return;
+        }
         const payload = createResumePayload({
             token: this.client.options.token,
             sessionId: this.state.sessionId,
@@ -364,33 +334,49 @@ export class GatewayPlugin extends Plugin {
         });
         this.send(payload, true);
     }
+    /**
+     * Sends a gateway payload with size and rate-limit safeguards.
+     */
     send(payload, skipRateLimit = false) {
-        if (this.ws && this.ws.readyState === 1) {
-            // Skip rate limiting for essential connection events
-            const isEssentialEvent = payload.op === GatewayOpcodes.Heartbeat ||
-                payload.op === GatewayOpcodes.Identify ||
-                payload.op === GatewayOpcodes.Resume;
-            if (!skipRateLimit && !isEssentialEvent && !this.rateLimit.canSend()) {
-                throw new Error(`Gateway rate limit exceeded. ${this.rateLimit.getRemainingEvents()} events remaining. Reset in ${this.rateLimit.getResetTime()}ms`);
-            }
-            this.ws.send(JSON.stringify(payload));
-            this.monitor.recordMessageSent();
-            if (!isEssentialEvent) {
-                this.rateLimit.recordEvent();
-            }
-            if (payload.op === GatewayOpcodes.Heartbeat) {
-                this.monitor.recordHeartbeat();
-            }
+        if (!this.ws || this.ws.readyState !== socketOpenState) {
+            throw new Error("Gateway websocket is not open");
+        }
+        const isEssentialEvent = payload.op === GatewayOpcodes.Heartbeat ||
+            payload.op === GatewayOpcodes.Identify ||
+            payload.op === GatewayOpcodes.Resume;
+        if (!skipRateLimit && !isEssentialEvent && !this.rateLimit.canSend()) {
+            throw new Error(`Gateway rate limit exceeded. ${this.rateLimit.getRemainingEvents()} events remaining. Reset in ${this.rateLimit.getResetTime()}ms`);
+        }
+        const encodedPayload = JSON.stringify(payload);
+        const payloadSize = typeof Buffer !== "undefined"
+            ? Buffer.byteLength(encodedPayload, "utf8")
+            : new TextEncoder().encode(encodedPayload).byteLength;
+        if (payloadSize > 4096) {
+            throw new Error("Gateway payload exceeds 4096-byte Discord limit");
+        }
+        this.ws.send(encodedPayload);
+        this.monitor.recordMessageSent();
+        if (!isEssentialEvent) {
+            this.rateLimit.recordEvent();
+        }
+        if (payload.op === GatewayOpcodes.Heartbeat) {
+            this.monitor.recordHeartbeat();
         }
     }
+    /**
+     * Sends an IDENTIFY payload for a fresh gateway session.
+     */
     identify() {
-        if (!this.client)
+        if (!this.client) {
             return;
+        }
         const payload = createIdentifyPayload({
             token: this.client.options.token,
             intents: this.options.intents,
             properties: {
-                os: process.platform,
+                os: typeof process !== "undefined" && process?.platform
+                    ? process.platform
+                    : "unknown",
                 browser: "@buape/carbon - https://carbon.buape.com",
                 device: "@buape/carbon - https://carbon.buape.com"
             },
@@ -399,30 +385,25 @@ export class GatewayPlugin extends Plugin {
         this.send(payload, true);
     }
     /**
-     * Update the bot's presence (status, activity, etc.)
-     * @param data Presence data to update
+     * Updates bot presence over the gateway connection.
      */
     updatePresence(data) {
         if (!this.isConnected) {
             throw new Error("Gateway is not connected");
         }
-        const payload = createUpdatePresencePayload(data);
-        this.send(payload);
+        this.send(createUpdatePresencePayload(data));
     }
     /**
-     * Update the bot's voice state
-     * @param data Voice state data to update
+     * Updates bot voice state for a guild over the gateway connection.
      */
     updateVoiceState(data) {
         if (!this.isConnected) {
             throw new Error("Gateway is not connected");
         }
-        const payload = createUpdateVoiceStatePayload(data);
-        this.send(payload);
+        this.send(createUpdateVoiceStatePayload(data));
     }
     /**
-     * Request guild members from Discord. The data will come in through the GUILD_MEMBERS_CHUNK event, not as a return on this function.
-     * @param data Guild members request data
+     * Requests guild members and validates required intents/options.
      */
     requestGuildMembers(data) {
         if (!this.isConnected) {
@@ -441,11 +422,10 @@ export class GatewayPlugin extends Plugin {
         if (!data.query && data.query !== "" && !data.user_ids) {
             throw new Error("Either 'query' or 'user_ids' field is required for requestGuildMembers");
         }
-        const payload = createRequestGuildMembersPayload(data);
-        this.send(payload);
+        this.send(createRequestGuildMembersPayload(data));
     }
     /**
-     * Get the current rate limit status
+     * Returns the current outbound gateway rate-limit snapshot.
      */
     getRateLimitStatus() {
         return {
@@ -455,7 +435,7 @@ export class GatewayPlugin extends Plugin {
         };
     }
     /**
-     * Get information about optionsured intents
+     * Returns helpers describing which intents are currently enabled.
      */
     getIntentsInfo() {
         return {
@@ -468,12 +448,343 @@ export class GatewayPlugin extends Plugin {
         };
     }
     /**
-     * Check if a specific intent is enabled
-     * @param intent The intent to check
+     * Checks if a specific intent bit is enabled.
      */
     hasIntent(intent) {
         return (this.options.intents & intent) !== 0;
     }
+    /**
+     * Guards handlers from acting on stale websocket instances.
+     */
+    isCurrentSocket(socket, generation) {
+        return this.ws === socket && this.socketGeneration === generation;
+    }
+    onSocketEvent(socket, event, handler) {
+        if (typeof socket.on === "function") {
+            socket.on(event, (...args) => {
+                if (args.length === 0) {
+                    handler(undefined);
+                    return;
+                }
+                handler(args.length === 1 ? args[0] : args);
+            });
+            return;
+        }
+        if (typeof socket.addEventListener === "function") {
+            socket.addEventListener(event, (incoming) => {
+                handler(incoming);
+            });
+            return;
+        }
+        throw new Error("WebSocket implementation does not support event listeners");
+    }
+    getMessageText(incoming) {
+        const payload = this.extractSocketPayload(incoming);
+        if (typeof payload === "string") {
+            return payload;
+        }
+        if (payload instanceof ArrayBuffer) {
+            return textDecoder.decode(new Uint8Array(payload));
+        }
+        if (ArrayBuffer.isView(payload)) {
+            return textDecoder.decode(new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength));
+        }
+        if (payload && typeof payload === "object" && "toString" in payload) {
+            const text = String(payload);
+            return text === "[object Object]" ? null : text;
+        }
+        return null;
+    }
+    extractSocketPayload(incoming) {
+        if (Array.isArray(incoming)) {
+            return incoming[0];
+        }
+        if (incoming && typeof incoming === "object" && "data" in incoming) {
+            return incoming.data;
+        }
+        return incoming;
+    }
+    getCloseCode(incoming) {
+        if (Array.isArray(incoming)) {
+            const [code] = incoming;
+            if (typeof code === "number") {
+                return code;
+            }
+        }
+        if (incoming && typeof incoming === "object" && "code" in incoming) {
+            const code = incoming.code;
+            if (typeof code === "number") {
+                return code;
+            }
+        }
+        return 1000;
+    }
+    getSocketError(incoming) {
+        const payload = this.extractSocketPayload(incoming);
+        if (payload instanceof Error) {
+            return payload;
+        }
+        if (payload && typeof payload === "object" && "error" in payload) {
+            const nested = payload.error;
+            if (nested instanceof Error) {
+                return nested;
+            }
+        }
+        return new Error(typeof payload === "string"
+            ? payload
+            : "Gateway socket emitted an unknown error");
+    }
+    closeSocketImmediately(socket) {
+        if (typeof socket.terminate === "function") {
+            socket.terminate();
+            return;
+        }
+        socket.close(1000, "Gateway reconnect");
+    }
+    /**
+     * Processes HELLO, starts heartbeat scheduling, then sends RESUME or IDENTIFY.
+     */
+    handleHello(data, generation) {
+        const heartbeatInterval = data?.heartbeat_interval;
+        if (typeof heartbeatInterval !== "number" || heartbeatInterval <= 0) {
+            this.monitor.recordError();
+            this.emitter.emit("error", new Error("Gateway HELLO missing heartbeat"));
+            this.handleZombieConnection();
+            return;
+        }
+        startHeartbeat(this, {
+            interval: heartbeatInterval,
+            reconnectCallback: () => {
+                if (this.socketGeneration !== generation) {
+                    return;
+                }
+                this.handleZombieConnection();
+            }
+        });
+        const shouldResume = this.nextConnectionShouldResume && this.canResume();
+        this.nextConnectionShouldResume = false;
+        try {
+            if (shouldResume) {
+                this.resume();
+                return;
+            }
+            this.identify();
+        }
+        catch {
+            this.handleZombieConnection();
+        }
+    }
+    /**
+     * Marks heartbeat acknowledged and updates rolling ping metrics.
+     */
+    handleHeartbeatAck() {
+        this.lastHeartbeatAck = true;
+        this.monitor.recordHeartbeatAck();
+        const latency = this.monitor.getMetrics().latency;
+        if (latency > 0) {
+            this.pings.push(latency);
+            if (this.pings.length > 10) {
+                this.pings.shift();
+            }
+        }
+    }
+    /**
+     * Immediately sends a heartbeat in response to gateway heartbeat requests.
+     */
+    sendHeartbeatNow() {
+        this.lastHeartbeatAck = false;
+        try {
+            this.send({
+                op: GatewayOpcodes.Heartbeat,
+                d: this.sequence
+            });
+        }
+        catch {
+            this.handleZombieConnection();
+        }
+    }
+    /**
+     * Processes dispatch events, session caching, and Carbon event forwarding.
+     */
+    handleDispatch(payload) {
+        const type = payload.t;
+        if (!listenerEvents.has(type)) {
+            return;
+        }
+        if (type === "READY") {
+            const readyData = payload.d;
+            this.state.sessionId = readyData.session_id;
+            this.state.resumeGatewayUrl = readyData.resume_gateway_url;
+        }
+        if (type === "READY" || type === "RESUMED") {
+            this.isConnected = true;
+            this.reconnectAttempts = 0;
+            this.consecutiveResumeFailures = 0;
+        }
+        if (!this.client) {
+            return;
+        }
+        if (this.options.eventFilter && !this.options.eventFilter(type)) {
+            return;
+        }
+        if (type === "READY") {
+            const readyData = payload.d;
+            readyData.guilds.forEach((guild) => {
+                this.babyCache.setGuild(guild.id, {
+                    available: false,
+                    lastEvent: Date.now()
+                });
+            });
+        }
+        if (type === "GUILD_CREATE") {
+            const guildCreateData = payload.d;
+            const existingGuild = this.babyCache.getGuild(guildCreateData.id);
+            if (existingGuild && !existingGuild.available) {
+                this.babyCache.setGuild(guildCreateData.id, {
+                    available: true,
+                    lastEvent: Date.now()
+                });
+                this.client.eventHandler.handleEvent({
+                    ...guildCreateData,
+                    clientId: this.client.options.clientId
+                }, "GUILD_AVAILABLE");
+                return;
+            }
+        }
+        if (type === "GUILD_DELETE") {
+            const guildDeleteData = payload.d;
+            const existingGuild = this.babyCache.getGuild(guildDeleteData.id);
+            if (existingGuild?.available && guildDeleteData.unavailable) {
+                this.babyCache.setGuild(guildDeleteData.id, {
+                    available: false,
+                    lastEvent: Date.now()
+                });
+                this.client.eventHandler.handleEvent({
+                    ...guildDeleteData,
+                    clientId: this.client.options.clientId
+                }, "GUILD_UNAVAILABLE");
+                return;
+            }
+            if (!guildDeleteData.unavailable) {
+                this.babyCache.removeGuild(guildDeleteData.id);
+            }
+        }
+        this.client.eventHandler.handleEvent({ ...payload.d, clientId: this.client.options.clientId }, type);
+    }
+    /**
+     * Handles INVALID_SESSION and schedules reconnect with Discord-compliant delay.
+     */
+    handleInvalidSession(data) {
+        const isResumable = Boolean(data) && this.canResume();
+        if (!isResumable) {
+            this.resetSessionState();
+        }
+        const discordRequiredDelay = 1000 + Math.floor(Math.random() * 4000);
+        this.scheduleReconnect({
+            reason: "invalid-session",
+            preferResume: isResumable,
+            minDelayMs: discordRequiredDelay
+        });
+        this.reconnectWithSocketRestart();
+    }
+    /**
+     * Handles RECONNECT opcode by scheduling reconnect with resume preference.
+     */
+    handleReconnectOpcode() {
+        this.scheduleReconnect({
+            reason: "reconnect-opcode",
+            preferResume: true,
+            allowImmediateFirstAttempt: true
+        });
+        this.reconnectWithSocketRestart();
+    }
+    /**
+     * Terminates the current socket after reconnect has been scheduled.
+     */
+    reconnectWithSocketRestart() {
+        stopHeartbeat(this);
+        this.lastHeartbeatAck = true;
+        if (!this.ws) {
+            return;
+        }
+        this.silentSocketClosures.add(this.ws);
+        this.closeSocketImmediately(this.ws);
+    }
+    /**
+     * Schedules a single reconnect attempt with backoff and attempt limits.
+     */
+    scheduleReconnect(options) {
+        if (!this.shouldReconnect || this.reconnectTimeout || this.isConnecting) {
+            return;
+        }
+        const maxAttempts = this.options.reconnect?.maxAttempts ?? reconnectDefaults.maxAttempts;
+        if (Number.isFinite(maxAttempts) && this.reconnectAttempts >= maxAttempts) {
+            this.shouldReconnect = false;
+            this.emitter.emit("error", new Error(`Max reconnect attempts (${maxAttempts}) reached${options.code ? ` after close code ${options.code}` : ""}`));
+            return;
+        }
+        let shouldResume = options.preferResume && this.canResume();
+        const resumeFailureThreshold = 3;
+        if (shouldResume &&
+            this.consecutiveResumeFailures >= resumeFailureThreshold) {
+            this.resetSessionState();
+            shouldResume = false;
+            this.emitter.emit("debug", `Gateway forcing fresh IDENTIFY after ${resumeFailureThreshold} failed resume attempts`);
+        }
+        const delay = this.computeReconnectDelay(options);
+        if (shouldResume) {
+            this.consecutiveResumeFailures++;
+        }
+        else {
+            this.consecutiveResumeFailures = 0;
+        }
+        this.reconnectAttempts++;
+        this.emitter.emit("debug", `Gateway reconnect scheduled in ${delay}ms (${options.reason}, resume=${String(shouldResume)})`);
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = undefined;
+            this.connect(shouldResume);
+        }, delay);
+    }
+    /**
+     * Computes exponential reconnect delay with jitter and optional minimum delay.
+     */
+    computeReconnectDelay(options) {
+        const baseDelay = this.options.reconnect?.baseDelay ?? reconnectDefaults.baseDelay;
+        const maxDelay = this.options.reconnect?.maxDelay ?? reconnectDefaults.maxDelay;
+        if (options.allowImmediateFirstAttempt &&
+            this.reconnectAttempts === 0 &&
+            (options.minDelayMs ?? 0) === 0) {
+            return 0;
+        }
+        const exponentialDelay = Math.min(baseDelay * 2 ** this.reconnectAttempts, maxDelay);
+        const jitterFactor = 0.85 + Math.random() * 0.3;
+        const jitteredDelay = Math.floor(exponentialDelay * jitterFactor);
+        return Math.max(options.minDelayMs ?? 0, jitteredDelay);
+    }
+    /**
+     * Clears any pending reconnect timer.
+     */
+    clearReconnectTimeout() {
+        if (!this.reconnectTimeout) {
+            return;
+        }
+        clearTimeout(this.reconnectTimeout);
+        this.reconnectTimeout = undefined;
+    }
+    /**
+     * Clears resume-related session state after non-resumable failures.
+     */
+    resetSessionState() {
+        this.state.sessionId = null;
+        this.state.resumeGatewayUrl = null;
+        this.state.sequence = null;
+        this.sequence = null;
+        this.consecutiveResumeFailures = 0;
+        this.pings = [];
+    }
+    /**
+     * Ensures gateway URLs include v=10 and encoding=json query parameters.
+     */
     ensureGatewayParams(url) {
         try {
             const parsed = new URL(url);