aqualink 3.0.0 → 3.1.0

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from 'events'
+import { EventEmitter } from 'node:events'
 
 declare module 'aqualink' {
   // Main Classes

package/build/structures/Aqua.js

@@ -1,4 +1,4 @@
-const fs = require('node:fs')
+const fs = require('node:fs')
 const path = require('node:path')
 const _readline = require('node:readline')
 const { EventEmitter } = require('node:events')
@@ -191,7 +191,10 @@ class Aqua extends EventEmitter {
 
   _trace(event, data = null) {
     if (!this.debugTrace) return
-    if (!this._traceBuffer || this._traceBuffer.length !== this.traceMaxEntries) {
+    if (
+      !this._traceBuffer ||
+      this._traceBuffer.length !== this.traceMaxEntries
+    ) {
       this._traceBuffer = new Array(this.traceMaxEntries)
       this._traceBufferCount = 0
       this._traceBufferIndex = 0
@@ -346,9 +349,14 @@ class Aqua extends EventEmitter {
         this._invalidateCache()
         queueMicrotask(() => {
           this._storeBrokenPlayers(node).catch((error) =>
-            reportSuppressedError(this, 'aqua.nodeDisconnect.storeBrokenPlayers', error, {
-              node: node?.name || node?.host
-            })
+            reportSuppressedError(
+              this,
+              'aqua.nodeDisconnect.storeBrokenPlayers',
+              error,
+              {
+                node: node?.name || node?.host
+              }
+            )
           )
           this._performCleanup()
         })

package/build/structures/AquaRecovery.js

@@ -112,7 +112,10 @@ class AquaRecovery {
       const batch = rebuilds.slice(i, i + this.MAX_CONCURRENT_OPS)
       const results = await Promise.allSettled(
         batch.map((state) =>
-          this.restorePlayer(state, node).then((ok) => ({ ok, guildId: state.g }))
+          this.restorePlayer(state, node).then((ok) => ({
+            ok,
+            guildId: state.g
+          }))
         )
       )
       for (let j = 0; j < results.length; j++) {
@@ -551,8 +554,9 @@ class AquaRecovery {
         if (existing?.playing && !existing.destroyed) return true
         if (existing?.destroyed) this.aqua.players.delete(gId)
 
-        const targetNode =
-          preferredNode?.connected ? preferredNode : this.aqua.leastUsedNodes[0]
+        const targetNode = preferredNode?.connected
+          ? preferredNode
+          : this.aqua.leastUsedNodes[0]
         if (!targetNode?.connected) {
           throw new Error(`No connected node available to restore guild ${gId}`)
         }

package/build/structures/Connection.js

@@ -321,7 +321,9 @@ class Connection {
     } catch (e) {
       this._aqua?.emit?.(
         AqualinkEvents.Debug,
-        new Error(`Player destroy failed: ${e?.message || e}`)
+        new Error(
+          `Player destroy failed (guild=${this._guildId}, sessionId=${this.sessionId || 'none'}): ${e?.message || e}`
+        )
       )
     } finally {
       this._stateFlags &= ~STATE.DISCONNECTING
@@ -452,6 +454,15 @@ class Connection {
 
   _executeVoiceUpdate() {
     if (this._destroyed) return
+    if (this._stateFlags & STATE.DISCONNECTING) {
+      this._stateFlags &= ~STATE.UPDATE_SCHEDULED
+      this._voiceFlushTimer = null
+      if (this._pendingUpdate) {
+        sharedPool.release(this._pendingUpdate.payload)
+        this._pendingUpdate = null
+      }
+      return
+    }
     this._stateFlags &= ~STATE.UPDATE_SCHEDULED
     this._voiceFlushTimer = null
 

package/build/structures/ConnectionRecovery.js

@@ -163,6 +163,14 @@ class ConnectionRecovery {
         true
       )
 
+      if (conn._destroyed || !conn._player || conn._player.destroyed) {
+        conn._aqua.emit(
+          AqualinkEvents.Debug,
+          `Resume aborted: player destroyed during attempt for guild ${conn._guildId}`
+        )
+        return false
+      }
+
       if (conn._stateGeneration !== currentGen) {
         conn._aqua.emit(
           AqualinkEvents.Debug,
@@ -178,6 +186,10 @@ class ConnectionRecovery {
         })
       }
 
+      if (conn._destroyed || conn._player?.destroyed) {
+        return false
+      }
+
       conn._reconnectAttempts = 0
       conn._consecutiveFailures = 0
       if (conn._player) conn._player._resuming = false
@@ -189,10 +201,17 @@ class ConnectionRecovery {
       return true
     } catch (error) {
       if (conn._destroyed || !conn._aqua) throw error
+      if (conn._player?.destroyed) {
+        conn._aqua.emit(
+          AqualinkEvents.Debug,
+          `Resume aborted: player destroyed during retry for guild ${conn._guildId}`
+        )
+        return false
+      }
       conn._consecutiveFailures++
       conn._aqua.emit(
         AqualinkEvents.Debug,
-        `Resume failed for guild ${conn._guildId}: ${error?.message || error}`
+        `Resume failed for guild ${conn._guildId} (sessionId=${conn.sessionId || 'none'}, endpoint=${conn.endpoint || 'none'}): ${error?.message || error}`
       )
       if (conn._aqua?.debugTrace) {
         conn._aqua._trace('connection.resume.error', {
@@ -204,7 +223,8 @@ class ConnectionRecovery {
       if (
         conn._reconnectAttempts < this.MAX_RECONNECT_ATTEMPTS &&
         !conn._destroyed &&
-        conn._consecutiveFailures < 5
+        conn._consecutiveFailures < 5 &&
+        !conn._player?.destroyed
       ) {
         const delay = Math.min(
           this.RECONNECT_DELAY * (1 << (conn._reconnectAttempts - 1)),
@@ -265,7 +285,10 @@ class ConnectionRecovery {
         return false
       })
       if (resumed) {
-        conn._player?._clearVoiceRecovery?.(recoveryToken, 'missing_player_resumed')
+        conn._player?._clearVoiceRecovery?.(
+          recoveryToken,
+          'missing_player_resumed'
+        )
       } else if (conn._player?._isVoiceRecoveryActive?.(recoveryToken)) {
         conn.resendVoiceUpdate(true)
       }
@@ -306,8 +329,12 @@ class ConnectionRecovery {
 
   async sendUpdate(payload) {
     const conn = this.connection
-    if (conn._destroyed) throw new Error('Connection destroyed')
-    if (!conn._rest) throw new Error('REST interface unavailable')
+    if (conn._destroyed)
+      throw new Error(`Connection destroyed (guild=${conn._guildId})`)
+    if (!conn._rest)
+      throw new Error(
+        `REST interface unavailable (guild=${conn._guildId}, sessionId=${conn.sessionId || 'none'})`
+      )
 
     try {
       if (conn._aqua?.debugTrace) {
@@ -342,7 +369,7 @@ class ConnectionRecovery {
         if (conn._aqua) {
           conn._aqua.emit(
             AqualinkEvents.Debug,
-            `[Aqua/Connection] Player ${conn._guildId} not found (404)${isSessionError ? ' - Session invalid' : ''}. Recovery failed, destroying.`
+            `[Aqua/Connection] Player ${conn._guildId} not found (404, sessionId=${conn.sessionId || 'none'}, endpoint=${conn.endpoint || 'none'})${isSessionError ? ' - Session invalid' : ''}. Recovery failed, destroying.`
           )
           await conn._aqua.destroyPlayer(conn._guildId)
         }

package/build/structures/Filters.js

@@ -202,7 +202,8 @@ class Filters {
   }
 
   _scheduleUpdate() {
-    if (this._pendingUpdate || !this.player) return this
+    if (this._pendingUpdate || !this.player || this.player.destroyed)
+      return this
     this._pendingUpdate = true
     queueMicrotask(() => {
       this._pendingUpdate = false
@@ -398,6 +399,7 @@ class Filters {
   }
 
   async updateFilters() {
+    this._pendingUpdate = false
     if (!this.player || !this._dirty.size) return this
 
     const dirtyKeys = [...this._dirty]

package/build/structures/Node.js

@@ -80,6 +80,16 @@ const _functions = {
 
   errMsg(err) {
     return err?.message || String(err)
+  },
+
+  statusCode(err) {
+    return (
+      err?.statusCode ||
+      err?.status ||
+      err?.response?.statusCode ||
+      err?.response?.status ||
+      null
+    )
   }
 }
 
@@ -205,7 +215,15 @@ class Node {
         this.isNodelink = !!this.info?.isNodelink
       } catch (err) {
         this.info = null
-        this._emitError(`Failed to fetch node info: ${_functions.errMsg(err)}`)
+        if (_functions.statusCode(err) === 404) {
+          this._emitDebug(
+            'Node info endpoint unavailable (HTTP 404); continuing without remote info'
+          )
+        } else {
+          this._emitError(
+            `Failed to fetch node info: ${_functions.errMsg(err)}`
+          )
+        }
       } finally {
         clearTimeout(timeoutId)
       }
@@ -592,8 +610,8 @@ class Node {
     }
 
     const oldSessionId = this.sessionId
-    const sessionChanged =
-      oldSessionId && oldSessionId !== sessionId && !payload.resumed
+    const sessionInvalidated = !payload.resumed && !!oldSessionId
+    const sessionChanged = sessionInvalidated && oldSessionId !== sessionId
 
     this.sessionId = sessionId
     if (this.aqua?.debugTrace) {
@@ -607,9 +625,9 @@ class Node {
     this.rest.setSessionId(sessionId)
     this._headers['Session-Id'] = sessionId
 
-    if (sessionChanged && this.aqua?.players) {
+    if (sessionInvalidated && this.aqua?.players) {
       this._emitDebug(
-        `Session changed from ${oldSessionId} to ${sessionId}, invalidating stale players`
+        `Session invalidated (resumed=${!!payload.resumed}, old=${oldSessionId}, new=${sessionId}), invalidating stale players`
       )
       try {
         await this.aqua._storeBrokenPlayers?.(this)
@@ -618,6 +636,15 @@ class Node {
           `Failed to snapshot stale players before invalidation: ${e?.message || e}`
         )
       }
+      for (const [, player] of this.aqua.players) {
+        if (player?.nodes === this || player?.nodes?.name === this.name) {
+          if (player.connection) {
+            player.connection._lastEndpoint = null
+            player.connection._stateFlags |= 512
+          }
+        }
+      }
+
       const playersToDestroy = []
       for (const [guildId, player] of this.aqua.players) {
         if (player?.nodes === this || player?.nodes?.name === this.name) {
@@ -650,7 +677,8 @@ class Node {
 
     this.aqua.emit(AqualinkEvents.NodeReady, this, {
       resumed: !!payload.resumed,
-      sessionChanged
+      sessionChanged,
+      sessionInvalidated
     })
 
     if (this.autoResume) {
@@ -672,57 +700,93 @@ class Node {
       })
     }
 
+    let resumeSupported = true
     try {
       await this.rest.makeRequest('PATCH', `/v4/sessions/${this.sessionId}`, {
         resuming: true,
         timeout: this.resumeTimeout
       })
+    } catch (err) {
+      if (_functions.statusCode(err) === 404) {
+        resumeSupported = false
+        this._emitDebug(
+          'Session resume endpoint unavailable (HTTP 404); falling back without server-side session resume'
+        )
+      } else {
+        if (this.aqua?.debugTrace) {
+          this.aqua._trace('node.resume.error', {
+            node: this.name,
+            error: _functions.errMsg(err)
+          })
+        }
+        this._emitError(`Failed to resume session: ${_functions.errMsg(err)}`)
+        throw err
+      }
+    }
+
+    if (!resumeSupported) {
+      try {
+        const existingPlayers = await this.rest.getPlayers()
+        if (Array.isArray(existingPlayers) && existingPlayers.length === 0) {
+          this._emitDebug(
+            'No players found on Lavalink for this session; will rejoin voice only'
+          )
+        }
+      } catch (_) {
+        // getPlayers may also 404 — that's fine, we already know session is invalid
+      }
+    }
 
-      if (this.aqua?.players) {
-        for (const [guildId, player] of this.aqua.players) {
-          if (
-            (player?.nodes === this || player?.nodes?.name === this.name) &&
-            player.voiceChannel
-          ) {
-              try {
-                const recoveryToken = player._claimVoiceRecovery?.(
-                  'node_resume_rejoin'
-                )
-                this._emitDebug(`Rejoining voice for guild ${guildId} on resume`)
-                if (this.aqua?.debugTrace) {
-                  this.aqua._trace('node.resume.rejoin', {
-                    node: this.name,
-                    guildId,
-                    voiceChannel: player.voiceChannel
-                  })
-                }
-                if (player._isVoiceRecoveryActive?.(recoveryToken))
-                  player.connect({
-                    voiceChannel: player.voiceChannel,
-                    deaf: player.deaf,
-                    mute: player.mute
-                  })
+    if (this.aqua?.players) {
+      const PLAYER_BATCH_SIZE = 20
+      const playersToResume = []
+      for (const [guildId, player] of this.aqua.players) {
+        if (
+          (player?.nodes === this || player?.nodes?.name === this.name) &&
+          player.voiceChannel &&
+          !player.destroyed
+        ) {
+          playersToResume.push({ guildId, player })
+        }
+      }
+
+      for (let i = 0; i < playersToResume.length; i += PLAYER_BATCH_SIZE) {
+        const batch = playersToResume.slice(i, i + PLAYER_BATCH_SIZE)
+        await Promise.allSettled(
+          batch.map(async ({ guildId, player }) => {
+            try {
+              const recoveryToken = player._claimVoiceRecovery?.(
+                resumeSupported
+                  ? 'node_resume_rejoin'
+                  : 'node_rejoin_after_resume_404'
+              )
+              this._emitDebug(`Rejoining voice for guild ${guildId} on resume`)
+              if (this.aqua?.debugTrace) {
+                this.aqua._trace('node.resume.rejoin', {
+                  node: this.name,
+                  guildId,
+                  voiceChannel: player.voiceChannel,
+                  resumeSupported
+                })
+              }
+              if (player._isVoiceRecoveryActive?.(recoveryToken))
+                player.connect({
+                  voiceChannel: player.voiceChannel,
+                  deaf: player.deaf,
+                  mute: player.mute
+                })
             } catch (e) {
               this._emitDebug(
                 `Failed to rejoin voice for ${guildId}: ${e?.message || e}`
               )
             }
-          }
-        }
+          })
+        )
       }
+    }
 
-      if (this.aqua.loadPlayers && this.aqua.players.size === 0) {
-        await this.aqua.loadPlayers()
-      }
-    } catch (err) {
-      if (this.aqua?.debugTrace) {
-        this.aqua._trace('node.resume.error', {
-          node: this.name,
-          error: _functions.errMsg(err)
-        })
-      }
-      this._emitError(`Failed to resume session: ${_functions.errMsg(err)}`)
-      throw err
+    if (this.aqua.loadPlayers && this.aqua.players.size === 0) {
+      await this.aqua.loadPlayers()
     }
   }
 

package/build/structures/Player.js

@@ -122,7 +122,8 @@ class MicrotaskUpdateBatcher {
     const { player: p, updates: u } = this
     this.updates = null
     this.scheduled = false
-    if (!u || !p) return Promise.resolve()
+    if (!u || !p || p.destroyed || p.state === PLAYER_STATE.DISCONNECTING)
+      return Promise.resolve()
     return p.updatePlayer(u).catch((err) => {
       _functions.emitAquaError(
         p.aqua,
@@ -296,7 +297,9 @@ class Player extends EventEmitter {
   }
 
   _isVoiceRecoveryActive(token) {
-    return !!token && !this.destroyed && this._activeVoiceRecoveryToken === token
+    return (
+      !!token && !this.destroyed && this._activeVoiceRecoveryToken === token
+    )
   }
 
   _clearVoiceRecovery(token = this._activeVoiceRecoveryToken, reason = null) {
@@ -352,6 +355,11 @@ class Player extends EventEmitter {
 
   async play(track, options = {}) {
     if (this.destroyed || !this.queue) return this
+    if (options != null && typeof options !== 'object') {
+      throw new TypeError(
+        `Player.play(): options must be an object, got ${typeof options}`
+      )
+    }
 
     let item = track
     if (!item) {
@@ -484,7 +492,8 @@ class Player extends EventEmitter {
   }
 
   connect(options = {}) {
-    if (this.destroyed) throw new Error('Cannot connect destroyed player')
+    if (this.destroyed)
+      throw new Error(`Cannot connect destroyed player (guild=${this.guildId})`)
 
     const voiceChannel = _functions.toId(
       options.voiceChannel || this.voiceChannel
@@ -542,38 +551,29 @@ class Player extends EventEmitter {
   }
 
   destroy(options = {}) {
+    if (this.destroyed) return this
+
     const {
       preserveClient = true,
       skipRemote = false,
       preserveMessage = false,
       preserveReconnecting = false,
-      preserveTracks = false
+      preserveTracks = false,
+      abortSignal = null
     } = options
-    if (this.destroyed && !this.queue) {
-      this._reconnectNonce++
-      if (this._reconnectTimers) {
-        _functions.clearTimers(this._reconnectTimers)
-        this._reconnectTimers = null
-      }
-      this._reconnecting = false
-      this._isActivelyReconnecting = false
-      return this
-    }
 
-    if (!this.destroyed) {
-      this._reconnectNonce++
-      this.destroyed = true
-      this._clearVoiceRecovery(undefined, 'destroyed')
-      if (this.aqua?.debugTrace) {
-        this.aqua._trace('player.destroy', {
-          guildId: this.guildId,
-          skipRemote: !!skipRemote,
-          preserveTracks: !!preserveTracks,
-          preserveReconnecting: !!preserveReconnecting
-        })
-      }
-      this.emit('destroy')
+    this._reconnectNonce++
+    this.destroyed = true
+    this._clearVoiceRecovery(undefined, 'destroyed')
+    if (this.aqua?.debugTrace) {
+      this.aqua._trace('player.destroy', {
+        guildId: this.guildId,
+        skipRemote: !!skipRemote,
+        preserveTracks: !!preserveTracks,
+        preserveReconnecting: !!preserveReconnecting
+      })
     }
+    this.emit('destroy')
 
     if (this._voiceWatchdogTimer) {
       clearInterval(this._voiceWatchdogTimer)
@@ -583,7 +583,6 @@ class Player extends EventEmitter {
     _functions.clearTimers(this._pendingTimers)
     this._pendingTimers = null
 
-    // Clear reconnection timers to prevent memory leaks when destroyed externally
     if (this._reconnectTimers) {
       _functions.clearTimers(this._reconnectTimers)
       this._reconnectTimers = null
@@ -633,8 +632,23 @@ class Player extends EventEmitter {
     this.previousTracks = null
     this.previousIdentifiers?.clear()
     this.previousIdentifiers = null
-    this.queue?.clear()
+    if (this.queue) {
+      for (
+        let i = this.queue._head || 0;
+        i < (this.queue._items?.length || 0);
+        i++
+      ) {
+        const t = this.queue._items[i]
+        if (t && typeof t.dispose === 'function') {
+          try {
+            t.dispose()
+          } catch {}
+        }
+      }
+      this.queue.clear()
+    }
     this.queue = null
+    // ML-1: Clear _dataStore to prevent unbounded growth
     this._dataStore?.clear()
     this._dataStore = null
 
@@ -662,14 +676,25 @@ class Player extends EventEmitter {
 
     if (!skipRemote) {
       try {
-        this.send({ guild_id: this.guildId, channel_id: null })
-        this.aqua?.destroyPlayer?.(this.guildId)
-        if (this.nodes?.connected)
-          this.nodes.rest?.destroyPlayer(this.guildId).catch((error) =>
-            reportSuppressedError(this, 'player.destroy.remote', error, {
-              guildId: this.guildId
+        if (abortSignal?.aborted) {
+          if (this.aqua?.debugTrace) {
+            this.aqua._trace('player.destroy.aborted', {
+              guildId: this.guildId,
+              reason: 'abort_signal_already_set'
             })
-          )
+          }
+        } else {
+          this.send({ guild_id: this.guildId, channel_id: null })
+          this.aqua?.destroyPlayer?.(this.guildId)
+          if (this.nodes?.connected)
+            this.nodes.rest
+              ?.destroyPlayer(this.guildId, abortSignal)
+              .catch((error) => {
+                reportSuppressedError(this, 'player.destroy.remote', error, {
+                  guildId: this.guildId
+                })
+              })
+        }
       } catch (error) {
         reportSuppressedError(this, 'player.destroy.gateway', error, {
           guildId: this.guildId
@@ -677,12 +702,23 @@ class Player extends EventEmitter {
       }
     }
 
-    if (!preserveClient) this.aqua = this.nodes = null
+    if (!preserveClient) {
+      try {
+        this.aqua?.removeListener?.('playerUpdate', this._boundPlayerUpdate)
+      } catch {}
+      this.aqua = this.nodes = null
+    }
     return this
   }
 
   pause(paused) {
-    if (this.destroyed || this.paused === !!paused) return this
+    if (this.destroyed) return this
+    if (paused != null && typeof paused !== 'boolean') {
+      throw new TypeError(
+        `Player.pause(): paused must be a boolean, got ${typeof paused}`
+      )
+    }
+    if (this.paused === !!paused) return this
     this.paused = !!paused
     this.batchUpdatePlayer({ paused: this.paused }, true).catch((error) =>
       reportSuppressedError(this, 'player.pause', error, {
@@ -694,8 +730,12 @@ class Player extends EventEmitter {
   }
 
   seek(position) {
-    if (this.destroyed || !this.playing || !_functions.isNum(position))
-      return this
+    if (position == null || !_functions.isNum(position)) {
+      throw new TypeError(
+        `Player.seek(): position must be a non-negative number, got ${typeof position}`
+      )
+    }
+    if (this.destroyed || !this.playing) return this
     const len = this.current?.info?.length || 0
     const clamped = len
       ? Math.min(Math.max(position, 0), len)
@@ -769,6 +809,14 @@ class Player extends EventEmitter {
   }
 
   setVolume(volume) {
+    if (
+      volume == null ||
+      (typeof volume !== 'number' && typeof volume !== 'string')
+    ) {
+      throw new TypeError(
+        `Player.setVolume(): volume must be a number, got ${typeof volume}`
+      )
+    }
     const vol = _functions.clamp(volume)
     if (this.destroyed || this.volume === vol) return this
     this.volume = vol
@@ -1029,6 +1077,7 @@ class Player extends EventEmitter {
     const isReplaced = reason === 'replaced'
 
     if (track) this.previousTracks.push(track)
+    if (isReplaced) return
     if (this.shouldDeleteMessage && !this._reconnecting && !this._resuming)
       _functions.safeDel(this.nowPlayingMessage)
     if (!isReplaced) this.current = null
@@ -1123,8 +1172,8 @@ class Player extends EventEmitter {
     _functions.emitIfActive(this, AqualinkEvents.MixEnded, t, payload)
   }
 
-  async _attemptVoiceResume() {
-    return this._lifecycleController.attemptVoiceResume()
+  async _attemptVoiceResume(abortSignal) {
+    return this._lifecycleController.attemptVoiceResume(abortSignal)
   }
 
   async socketClosed(_player, _track, payload) {
@@ -1142,7 +1191,7 @@ class Player extends EventEmitter {
     } catch (err) {
       _functions.emitAquaError(
         this.aqua,
-        new Error(`Send fail: ${err.message}`)
+        new Error(`Send fail (guild=${this.guildId}): ${err.message}`)
       )
       return false
     }

package/build/structures/PlayerLifecycle.js

@@ -30,6 +30,8 @@ class PlayerLifecycle {
     player.ping = this._functions.isNum(s.ping) ? s.ping : 0
     player.timestamp = this._functions.isNum(s.time) ? s.time : Date.now()
 
+    if (player.destroyed) return
+
     if (!player.connected) {
       if (wasConnected || !player._voiceDownSince) {
         if (player.aqua?.debugTrace) {
@@ -148,7 +150,9 @@ class PlayerLifecycle {
     if (!hasVoiceData) {
       const downFor = Date.now() - player._voiceDownSince
       if (downFor > this.VOICE_DOWN_THRESHOLD * this.VOICE_ABANDON_MULTIPLIER) {
-        const recoveryToken = player._claimVoiceRecovery('watchdog_voice_refresh')
+        const recoveryToken = player._claimVoiceRecovery(
+          'watchdog_voice_refresh'
+        )
         if (player._isVoiceRecoveryActive(recoveryToken))
           player.connection?._requestVoiceState?.()
         if (player._isVoiceRecoveryActive(recoveryToken))
@@ -215,11 +219,15 @@ class PlayerLifecycle {
     }
   }
 
-  async attemptVoiceResume() {
+  async attemptVoiceResume(abortSignal) {
     const player = this.player
-    if (!player.connection?.sessionId) throw new Error('No session')
+    if (!player.connection?.sessionId)
+      throw new Error(`No session (guild=${player.guildId})`)
+    if (abortSignal?.aborted) throw new Error('Resume aborted by signal')
     if (!(await player.connection.attemptResume()))
-      throw new Error('Resume failed')
+      throw new Error(
+        `Resume failed (guild=${player.guildId}, endpoint=${player.connection.endpoint || 'none'})`
+      )
   }
 
   async socketClosed(_player, _track, payload) {
@@ -342,7 +350,8 @@ class PlayerLifecycle {
           return false
         })
       }
-      if (resumed) player._clearVoiceRecovery(recoveryToken, 'socket_soft_resumed')
+      if (resumed)
+        player._clearVoiceRecovery(recoveryToken, 'socket_soft_resumed')
       if (
         resumed ||
         player.connected ||

package/build/structures/Queue.js

@@ -2,6 +2,7 @@ class Queue {
   constructor() {
     this._items = []
     this._head = 0
+    this._compactThreshold = 64
   }
 
   get size() {
@@ -40,13 +41,16 @@ class Queue {
 
   _compact(force = false) {
     if (this._head <= 0) return
-    if (!force && this._head <= this._items.length / 2) return
+    if (!force && this._head < this._compactThreshold) return
     const len = this._items.length - this._head
     for (let i = 0; i < len; i++) {
       this._items[i] = this._items[this._head + i]
     }
     this._items.length = len
     this._head = 0
+    if (this._compactThreshold < len) {
+      this._compactThreshold = Math.min(len * 2, 1024)
+    }
   }
 
   shuffle() {

package/build/structures/Rest.js

@@ -134,6 +134,7 @@ class Rest {
     this.aqua = aqua
     this.node = node
     this.sessionId = node.sessionId
+    this._sessionGeneration = 0
     this.timeout = node.timeout || 30000
 
     const protocol = node.ssl ? 'https:' : 'http:'
@@ -236,10 +237,18 @@ class Rest {
 
   setSessionId(sessionId) {
     this.sessionId = sessionId
+    this._sessionGeneration++
   }
 
-  _getSessionPath() {
+  _getSessionPath(generation) {
     if (!this.sessionId) throw ERRORS.NO_SESSION
+    if (generation != null && generation !== this._sessionGeneration) {
+      const staleErr = new Error(
+        `Stale session: sessionId was updated (expected gen ${generation}, current ${this._sessionGeneration}) for session ${this.sessionId}`
+      )
+      staleErr.statusCode = 404
+      throw staleErr
+    }
     return `${this._apiBase}/sessions/${this.sessionId}`
   }
 
@@ -639,28 +648,33 @@ class Rest {
   }
 
   async updatePlayer({ guildId, data, noReplace = false }) {
+    const gen = this._sessionGeneration
     return this.makeRequest(
       'PATCH',
-      `${this._getSessionPath()}/players/${guildId}?noReplace=${noReplace}`,
+      `${this._getSessionPath(gen)}/players/${guildId}?noReplace=${noReplace}`,
       data
     )
   }
 
   async getPlayer(guildId) {
+    const gen = this._sessionGeneration
     return this.makeRequest(
       'GET',
-      `${this._getSessionPath()}/players/${guildId}`
+      `${this._getSessionPath(gen)}/players/${guildId}`
     )
   }
 
   async getPlayers() {
-    return this.makeRequest('GET', `${this._getSessionPath()}/players`)
+    const gen = this._sessionGeneration
+    return this.makeRequest('GET', `${this._getSessionPath(gen)}/players`)
   }
 
-  async destroyPlayer(guildId) {
+  async destroyPlayer(guildId, abortSignal) {
+    const gen = this._sessionGeneration
+    if (abortSignal?.aborted) return null
     return this.makeRequest(
       'DELETE',
-      `${this._getSessionPath()}/players/${guildId}`
+      `${this._getSessionPath(gen)}/players/${guildId}`
     )
   }
 
@@ -733,9 +747,10 @@ class Rest {
 
     if (guildId) {
       try {
+        const gen = this._sessionGeneration
         const lyrics = await this.makeRequest(
           'GET',
-          `${this._getSessionPath()}/players/${guildId}/track/lyrics?skipTrackSource=${skip}`
+          `${this._getSessionPath(gen)}/players/${guildId}/track/lyrics?skipTrackSource=${skip}`
         )
         if (this._validLyrics(lyrics)) return lyrics
       } catch {}
@@ -776,10 +791,11 @@ class Rest {
 
   async subscribeLiveLyrics(guildId, skipTrackSource = false) {
     try {
+      const gen = this._sessionGeneration
       return (
         (await this.makeRequest(
           'POST',
-          `${this._getSessionPath()}/players/${guildId}/lyrics/subscribe?skipTrackSource=${skipTrackSource ? 'true' : 'false'}`
+          `${this._getSessionPath(gen)}/players/${guildId}/lyrics/subscribe?skipTrackSource=${skipTrackSource ? 'true' : 'false'}`
         )) === null
       )
     } catch {
@@ -789,10 +805,11 @@ class Rest {
 
   async unsubscribeLiveLyrics(guildId) {
     try {
+      const gen = this._sessionGeneration
       return (
         (await this.makeRequest(
           'DELETE',
-          `${this._getSessionPath()}/players/${guildId}/lyrics/subscribe`
+          `${this._getSessionPath(gen)}/players/${guildId}/lyrics/subscribe`
         )) === null
       )
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aqualink",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "An Lavalink/Nodelink client, focused in pure performance and features",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",