Introduce a reconnection queue with reconnection state times + minor adjustments for that

Author: Tomato6966

docs/src/content/docs/extra/version-log.mdx

@@ -9,6 +9,25 @@ Logs about the changed features.
 
 ---
 
+## **Version 2.7.2**
+
+Make the node auto-reconnection more solid by a reconnection queue, so we can trigger reconnection tries much easier.
+You can check the current state of reconnection by accessing **`node.reconnectionState`** (`"IDLE"` / `"RECONNECTING"` / `"PENDING"` / `"DESTROYING"`)
+Alterantivly you can use the getter property to check wether it's pending to reconnect or reconnecting: **`node.isNodeReconnecting`** (easier to use)
+
+Huge thanks to **[@ductridev](https://github.com/ductridev)** who introduced this change in: [Pull #154](https://github.com/Tomato6966/lavalink-client/pull/154)
+Enhances the resilience of the LavalinkNode by introducing automatic reconnection attempts on WebSocket errors instead of only emitting error events. The implementation adds a state machine using a new ReconnectionState enum to prevent duplicate reconnection attempts.
+
+Key Changes:
+
+- Added ReconnectionState enum to track reconnection status (IDLE, RECONNECTING, PENDING)
+- Refactored reconnect() method to use state guards preventing concurrent reconnection attempts
+- Modified error() handler to trigger reconnection directly instead of emitting error events
+- there is now a new getter: `node.reconnectionAttemptCount` (which allows you to get the count of the current reconnection attempts, considering the new option `node.options.retryTimespan`)
+- Before the `node.reconnectAttempts` was a number-counter. Now it's just an array of Date-Times, to be able to allow Retrys per a timespan (e.g. you can have 20 retries every hour.) - setup able through `node.options.retryTimespan`, on default it's -1. so it behaves as before.
+- FIX: Now instead of counting from "1 retry up" it counts from 0 up, means if you set `node.retryAmount` to "1" it actually tries 1 time to retry, and not 0. (issue before)
+
+
 ## **Version 2.7.1**
 
 Fixes:

src/structures/Node.ts

@@ -2,6 +2,7 @@ import { isAbsolute } from "path";
 import WebSocket from "ws";
 
 import { DebugEvents, DestroyReasons, validSponsorBlocks } from "./Constants";
+import { ReconnectionState } from "./Types/Node";
 import { NodeSymbol, queueTrackEnd, safeStringify } from "./Utils";
 
 import type {
@@ -20,7 +21,6 @@ import type { NodeManager } from "./NodeManager";
 import type {
     BaseNodeStats, LavalinkInfo, LavalinkNodeOptions, LyricsResult, ModifyRequest, NodeStats, SponsorBlockSegment
 } from "./Types/Node";
-import { ReconnectionState } from "./Types/Node";
 /**
  * Lavalink Node creator class
  */
@@ -65,14 +65,14 @@ export class LavalinkNode {
     public resuming: { enabled: boolean, timeout: number | null } = { enabled: true, timeout: null };
     /** Actual Lavalink Information of the Node */
     public info: LavalinkInfo | null = null;
+    /** current state of the Reconnections */
+    public reconnectionState: ReconnectionState = ReconnectionState.IDLE;
     /** The Node Manager of this Node */
     private NodeManager: NodeManager | null = null;
     /** The Reconnection Timeout */
     private reconnectTimeout?: NodeJS.Timeout = undefined;
-    /** The Reconnection Attempt counter */
-    private reconnectAttempts = 1;
-    /** Reconnection current state */
-    private reconnectionState: ReconnectionState = ReconnectionState.IDLE;
+    /** The Reconnection Attempt counter (array of datetimes when it tried it.) */
+    private reconnectAttempts: number[] = [];
     /** The Socket of the Lavalink */
     private socket: WebSocket | null = null;
     /** Version of what the Lavalink Server should be */
@@ -98,6 +98,7 @@ export class LavalinkNode {
             secure: false,
             retryAmount: 5,
             retryDelay: 10e3,
+            retryTimespan: -1,
             requestSignalTimeoutMS: 10000,
             heartBeatInterval: 30_000,
             closeOnError: true,
@@ -1013,60 +1014,81 @@ export class LavalinkNode {
         return `http${this.options.secure ? "s" : ""}://${this.options.host}:${this.options.port}`;
     }
 
+
+    /**
+     * If already trying to reconnect or pending, return
+     */
+    public get isNodeReconnecting(): boolean {
+        return this.reconnectionState !== ReconnectionState.IDLE;
+    }
+
     /**
      * Reconnect to the lavalink node
-     * @param instaReconnect @default false wether to instantly try to reconnect
+     * @param force @default false Wether to instantly try to reconnect (force it)
      * @returns void
      *
      * @example
      * ```ts
      * await player.node.reconnect();
      * ```
      */
-    private reconnect(instaReconnect = false): void {
+    private reconnect(force = false): void {
         // If already trying to reconnect or pending, return
-        if (this.reconnectionState !== ReconnectionState.IDLE) {
+        if (this.isNodeReconnecting) {
             return;
         }
 
         // Set reconnection state to pending
         this.reconnectionState = ReconnectionState.PENDING;
         this.NodeManager.emit("reconnectinprogress", this);
 
-        const executeReconnect = () => {
-            if (this.reconnectAttempts >= this.options.retryAmount) {
-                const error = new Error(`Unable to connect after ${this.options.retryAmount} attempts.`)
-
-                this.NodeManager.emit("error", this, error);
-
-                this.reconnectionState = ReconnectionState.DESTROYING;
-                this.destroy(DestroyReasons.NodeReconnectFail);
-
-                this.reconnectionState = ReconnectionState.IDLE;
-                return;
-            }
-
-            this.NodeManager.emit("reconnecting", this);
-            this.reconnectionState = ReconnectionState.RECONNECTING;
-            this.connect();
-            this.reconnectAttempts++;
-        };
-        if (instaReconnect) {
-            executeReconnect();
+        if (force) {
+            this.executeReconnect();
             return;
         }
         this.reconnectTimeout = setTimeout(() => {
             this.reconnectTimeout = null;
-            executeReconnect();
+            this.executeReconnect();
         }, this.options.retryDelay || 1000);
     }
 
+    public get reconnectionAttemptCount(): number {
+        const maxAllowedTimestan = this.options.retryTimespan || -1;
+        if(maxAllowedTimestan <= 0) return this.reconnectAttempts.length;
+        return this.reconnectAttempts.filter(timestamp => Date.now() - timestamp <= maxAllowedTimestan).length;
+    }
+
+    /**
+     * Private Utility function to execute the reconnection
+    */
+    private executeReconnect() {
+        if (this.reconnectionAttemptCount >= this.options.retryAmount) {
+            const error = new Error(`Unable to connect after ${this.options.retryAmount} attempts.`)
+
+            this.reconnectionState = ReconnectionState.DESTROYING;
+
+            this.NodeManager.emit("error", this, error);
+            this.destroy(DestroyReasons.NodeReconnectFail);
+            // the reconnection State should be set on idle inside of the destroy function
+            return;
+        }
+
+        // state's should be changed before emitting an event
+        this.reconnectAttempts.push(Date.now());
+        this.reconnectionState = ReconnectionState.RECONNECTING;
+
+        this.NodeManager.emit("reconnecting", this);
+        this.connect();
+    };
+
+
     /**
      * Private function to reset the reconnection attempts
      * @returns
      */
     private resetReconnectionAttempts(): void {
-        this.reconnectAttempts = 1;
+        this.reconnectionState = ReconnectionState.IDLE;
+        this.reconnectAttempts = [];
         clearTimeout(this.reconnectTimeout);
         this.reconnectTimeout = null;
         return;
@@ -1095,7 +1117,6 @@ export class LavalinkNode {
         this.isAlive = true;
 
         // Reset reconnection state on successful connection
-        this.reconnectionState = ReconnectionState.IDLE;
         this.resetReconnectionAttempts();
 
         // trigger heartbeat-ping timeout - this is to check wether the client lost connection without knowing it

src/structures/Types/Node.ts

@@ -26,10 +26,12 @@ export interface LavalinkNodeOptions {
     id?: string;
     /** Voice Regions of this Node */
     regions?: string[];
-    /** The retryAmount for the node. */
+    /** The max amount of retries for this node. */
     retryAmount?: number;
-    /** The retryDelay for the node. */
+    /** The delay of how often to retry a reconnection. */
     retryDelay?: number;
+    /** How long a retry is a valid retry, it should be at least retryAmount*retryDelay. if <= 0 (default) then this won't be accounted. */
+    retryTimespan?: number;
     /** signal for cancelling requests - default: AbortSignal.timeout(options.requestSignalTimeoutMS || 10000) - put <= 0 to disable */
     requestSignalTimeoutMS?: number;
     /** Close on error */
@@ -254,4 +256,4 @@ export enum ReconnectionState {
     RECONNECTING = "RECONNECTING",
     PENDING = "PENDING",
     DESTROYING = "DESTROYING"
-}
+}