aqualink 2.14.0 → 2.15.1

package/build/structures/Aqua.js

@@ -2,13 +2,14 @@
 
 const fs = require('node:fs')
 const readline = require('node:readline')
-const { EventEmitter } = require('tseep')
-const { AqualinkEvents } = require('./AqualinkEvents')
+const {EventEmitter} = require('tseep')
+const {AqualinkEvents} = require('./AqualinkEvents')
 const Node = require('./Node')
 const Player = require('./Player')
 const Track = require('./Track')
-const { version: pkgVersion } = require('../../package.json')
+const {version: pkgVersion} = require('../../package.json')
 
+// Constants
 const SEARCH_PREFIX = ':'
 const EMPTY_ARRAY = Object.freeze([])
 const EMPTY_TRACKS_RESPONSE = Object.freeze({
@@ -30,6 +31,10 @@ const NODE_TIMEOUT = 30000
 const MAX_CACHE_SIZE = 20
 const MAX_BROKEN_PLAYERS = 50
 const MAX_FAILOVER_QUEUE = 50
+const MAX_REBUILD_LOCKS = 100
+const WRITE_BUFFER_SIZE = 100
+const MAX_QUEUE_SAVE = 10
+const MAX_TRACKS_RESTORE = 20
 const URL_PATTERN = /^https?:\/\//i
 
 const DEFAULT_OPTIONS = Object.freeze({
@@ -53,13 +58,18 @@ const DEFAULT_OPTIONS = Object.freeze({
   })
 })
 
+// Utility functions (moved to module scope for reuse)
 const _delay = ms => new Promise(r => setTimeout(r, ms))
-const _noop = () => { }
+const _noop = () => {}
 const _isUrl = query => typeof query === 'string' && query.length > 8 && URL_PATTERN.test(query)
 const _formatQuery = (query, source) => _isUrl(query) ? query : `${source}${SEARCH_PREFIX}${query}`
 const _makeTrack = (t, requester, node) => new Track(t, requester, node)
-const _safeCall = fn => { try { fn() } catch { } }
-const _safeCallAsync = async fn => { try { await fn() } catch { } }
+const _safeCall = fn => {
+  try {
+    const result = fn()
+    return result?.then ? result.catch(_noop) : result
+  } catch {}
+}
 
 class Aqua extends EventEmitter {
   constructor(client, nodes, options = {}) {
@@ -75,9 +85,9 @@ class Aqua extends EventEmitter {
     this.initiated = false
     this.version = pkgVersion
 
-    const merged = { ...DEFAULT_OPTIONS, ...options }
+    const merged = {...DEFAULT_OPTIONS, ...options}
     this.options = merged
-    this.failoverOptions = { ...DEFAULT_OPTIONS.failoverOptions, ...options.failoverOptions }
+    this.failoverOptions = {...DEFAULT_OPTIONS.failoverOptions, ...options.failoverOptions}
 
     this.shouldDeleteMessage = merged.shouldDeleteMessage
     this.defaultSearchPlatform = merged.defaultSearchPlatform
@@ -101,8 +111,9 @@ class Aqua extends EventEmitter {
     this._leastUsedNodesCache = null
     this._leastUsedNodesCacheTime = 0
     this._nodeLoadCache = new Map()
+    this._eventHandlers = null
 
-    this._bindEventHandlers()
+    if (this.autoResume) this._bindEventHandlers()
   }
 
   _createDefaultSend() {
@@ -118,30 +129,46 @@ class Aqua extends EventEmitter {
   }
 
   _bindEventHandlers() {
-    if (!this.autoResume) return
-    const onNodeConnect = async node => {
-      this._invalidateCache()
-      await this._rebuildBrokenPlayers(node)
-      this._performCleanup()
-    }
-    const onNodeDisconnect = node => {
-      this._invalidateCache()
-      queueMicrotask(() => {
-        this._storeBrokenPlayers(node)
+    // Store handlers for cleanup
+    this._eventHandlers = {
+      onNodeConnect: async node => {
+        this._invalidateCache()
+        await this._rebuildBrokenPlayers(node)
         this._performCleanup()
-      })
-    }
-    const onNodeReady = (node, { resumed }) => {
-      if (!resumed) return
-      const batch = []
-      for (const player of this.players.values()) {
-        if (player.nodes === node && player.connection) batch.push(player)
+      },
+      onNodeDisconnect: node => {
+        this._invalidateCache()
+        queueMicrotask(() => {
+          this._storeBrokenPlayers(node)
+          this._performCleanup()
+        })
+      },
+      onNodeReady: (node, {resumed}) => {
+        if (!resumed) return
+        const batch = []
+        for (const player of this.players.values()) {
+          if (player.nodes === node && player.connection) batch.push(player)
+        }
+        if (batch.length) queueMicrotask(() => batch.forEach(p => p.connection.resendVoiceUpdate({resume: true})))
       }
-      if (batch.length) queueMicrotask(() => batch.forEach(p => p.connection.resendVoiceUpdate({ resume: true })))
     }
-    this.on(AqualinkEvents.NodeConnect, onNodeConnect)
-    this.on(AqualinkEvents.NodeDisconnect, onNodeDisconnect)
-    this.on(AqualinkEvents.NodeReady, onNodeReady)
+    this.on(AqualinkEvents.NodeConnect, this._eventHandlers.onNodeConnect)
+    this.on(AqualinkEvents.NodeDisconnect, this._eventHandlers.onNodeDisconnect)
+    this.on(AqualinkEvents.NodeReady, this._eventHandlers.onNodeReady)
+  }
+
+  // Cleanup event handlers to prevent memory leaks
+  destroy() {
+    if (this._eventHandlers) {
+      this.off(AqualinkEvents.NodeConnect, this._eventHandlers.onNodeConnect)
+      this.off(AqualinkEvents.NodeDisconnect, this._eventHandlers.onNodeDisconnect)
+      this.off(AqualinkEvents.NodeReady, this._eventHandlers.onNodeReady)
+      this._eventHandlers = null
+    }
+    this.removeAllListeners()
+    this.nodeMap.forEach(node => this._destroyNode(node.name || node.host))
+    this.players.forEach(player => _safeCall(() => player.destroy()))
+    this.players.clear()
   }
 
   get leastUsedNodes() {
@@ -149,10 +176,7 @@ class Aqua extends EventEmitter {
     if (this._leastUsedNodesCache && (now - this._leastUsedNodesCacheTime) < CACHE_VALID_TIME) {
       return this._leastUsedNodesCache
     }
-    const connected = []
-    for (const node of this.nodeMap.values()) {
-      if (node.connected) connected.push(node)
-    }
+    const connected = Array.from(this.nodeMap.values()).filter(n => n.connected)
     const sorted = this.loadBalancer === 'leastRest'
       ? connected.sort((a, b) => (a.rest?.calls || 0) - (b.rest?.calls || 0))
       : this.loadBalancer === 'random'
@@ -179,7 +203,7 @@ class Aqua extends EventEmitter {
       (stats.playingPlayers || 0) * 0.75 +
       (stats.memory ? stats.memory.used / Math.max(1, stats.memory.reservable) : 0) * 40 +
       (node.rest?.calls || 0) * 0.001
-    this._nodeLoadCache.set(id, { load, time: now })
+    this._nodeLoadCache.set(id, {load, time: now})
     if (this._nodeLoadCache.size > MAX_CACHE_SIZE) {
       const first = this._nodeLoadCache.keys().next().value
       this._nodeLoadCache.delete(first)
@@ -192,14 +216,11 @@ class Aqua extends EventEmitter {
     this.clientId = clientId
     if (!this.clientId) return
     const results = await Promise.allSettled(
-      this.nodes.map(n => Promise.race([this._createNode(n), _delay(NODE_TIMEOUT).then(() => { throw new Error('Timeout') })]))
+      this.nodes.map(n => Promise.race([this._createNode(n), _delay(NODE_TIMEOUT).then(() => {throw new Error('Timeout')})]))
     )
     if (!results.some(r => r.status === 'fulfilled')) throw new Error('No nodes connected')
     if (this.plugins?.length) {
-      await Promise.allSettled(this.plugins.map(p => {
-        try { return p.load(this) }
-        catch (err) { this.emit(AqualinkEvents.Error, null, err) }
-      }))
+      await Promise.allSettled(this.plugins.map(p => _safeCall(() => p.load(this))))
     }
     this.initiated = true
     return this
@@ -211,10 +232,10 @@ class Aqua extends EventEmitter {
     const node = new Node(this, options, this.options)
     node.players = new Set()
     this.nodeMap.set(id, node)
-    this._nodeStates.set(id, { connected: false, failoverInProgress: false })
+    this._nodeStates.set(id, {connected: false, failoverInProgress: false})
     try {
       await node.connect()
-      this._nodeStates.set(id, { connected: true, failoverInProgress: false })
+      this._nodeStates.set(id, {connected: true, failoverInProgress: false})
       this._invalidateCache()
       this.emit(AqualinkEvents.NodeCreate, node)
       return node
@@ -267,7 +288,7 @@ class Aqua extends EventEmitter {
     const now = Date.now()
     for (const [guildId, state] of this._brokenPlayers) {
       if (state.originalNodeId === id && (now - state.brokenAt) < BROKEN_PLAYER_TTL) {
-        rebuilds.push({ guildId, state })
+        rebuilds.push({guildId, state})
       }
     }
     if (!rebuilds.length) return
@@ -275,7 +296,7 @@ class Aqua extends EventEmitter {
     for (let i = 0; i < rebuilds.length; i += MAX_CONCURRENT_OPS) {
       const batch = rebuilds.slice(i, i + MAX_CONCURRENT_OPS)
       const results = await Promise.allSettled(
-        batch.map(({ guildId, state }) => this._rebuildPlayer(state, node).then(() => guildId))
+        batch.map(({guildId, state}) => this._rebuildPlayer(state, node).then(() => guildId))
       )
       results.forEach(r => {
         if (r.status === 'fulfilled') successes.push(r.value)
@@ -287,7 +308,7 @@ class Aqua extends EventEmitter {
   }
 
   async _rebuildPlayer(state, targetNode) {
-    const { guildId, textChannel, voiceChannel, current, volume = 65, deaf = true } = state
+    const {guildId, textChannel, voiceChannel, current, volume = 65, deaf = true} = state
     const lockKey = `rebuild_${guildId}`
     if (this._rebuildLocks.has(lockKey)) return
     this._rebuildLocks.add(lockKey)
@@ -297,7 +318,7 @@ class Aqua extends EventEmitter {
         await this.destroyPlayer(guildId)
         await _delay(RECONNECT_DELAY)
       }
-      const player = this.createPlayer(targetNode, { guildId, textChannel, voiceChannel, defaultVolume: volume, deaf })
+      const player = this.createPlayer(targetNode, {guildId, textChannel, voiceChannel, defaultVolume: volume, deaf})
       if (current && player?.queue?.add) {
         player.queue.add(current)
         await player.play()
@@ -321,7 +342,7 @@ class Aqua extends EventEmitter {
     const attempts = this._failoverQueue.get(id) || 0
     if (attempts >= this.failoverOptions.maxFailoverAttempts) return
 
-    this._nodeStates.set(id, { connected: false, failoverInProgress: true })
+    this._nodeStates.set(id, {connected: false, failoverInProgress: true})
     this._lastFailoverAttempt.set(id, now)
     this._failoverQueue.set(id, attempts + 1)
 
@@ -329,7 +350,7 @@ class Aqua extends EventEmitter {
       this.emit(AqualinkEvents.NodeFailover, failedNode)
       const players = Array.from(failedNode.players || [])
       if (!players.length) return
-      const available = this._getAvailableNodes(failedNode)
+      const available = Array.from(this.nodeMap.values()).filter(n => n !== failedNode && n.connected)
       if (!available.length) throw new Error('No failover nodes')
       const results = await this._migratePlayersOptimized(players, available)
       const successful = results.filter(r => r.success).length
@@ -340,7 +361,7 @@ class Aqua extends EventEmitter {
     } catch (error) {
       this.emit(AqualinkEvents.Error, null, error)
     } finally {
-      this._nodeStates.set(id, { connected: false, failoverInProgress: false })
+      this._nodeStates.set(id, {connected: false, failoverInProgress: false})
     }
   }
 
@@ -364,7 +385,7 @@ class Aqua extends EventEmitter {
     for (let i = 0; i < players.length; i += MAX_CONCURRENT_OPS) {
       const batch = players.slice(i, i + MAX_CONCURRENT_OPS)
       const batchResults = await Promise.allSettled(batch.map(p => this._migratePlayer(p, pickNode)))
-      results.push(...batchResults.map(r => ({ success: r.status === 'fulfilled', error: r.reason })))
+      results.push(...batchResults.map(r => ({success: r.status === 'fulfilled', error: r.reason})))
     }
     return results
   }
@@ -375,7 +396,7 @@ class Aqua extends EventEmitter {
     for (let retry = 0; retry < this.failoverOptions.maxRetries; retry++) {
       try {
         const targetNode = pickNode()
-        const newPlayer = await this._createPlayerOnNode(targetNode, state)
+        const newPlayer = this._createPlayerOnNode(targetNode, state)
         await this._restorePlayerState(newPlayer, state)
         this.emit(AqualinkEvents.PlayerMigrated, player, newPlayer, targetNode)
         return newPlayer
@@ -421,18 +442,18 @@ class Aqua extends EventEmitter {
     }
     if (state.queue?.length && newPlayer.queue?.add) newPlayer.queue.add(...state.queue)
     if (state.current && this.failoverOptions.preservePosition) {
-      newPlayer.queue?.add?.(state.current, { toFront: true })
+      newPlayer.queue?.add?.(state.current, {toFront: true})
       if (this.failoverOptions.resumePlayback) {
         ops.push(newPlayer.play())
         if (state.position > 0) setTimeout(() => newPlayer.seek?.(state.position), SEEK_DELAY)
         if (state.paused) ops.push(newPlayer.pause(true))
       }
     }
-    Object.assign(newPlayer, { loop: state.loop, shuffle: state.shuffle })
+    Object.assign(newPlayer, {loop: state.loop, shuffle: state.shuffle})
     await Promise.allSettled(ops)
   }
 
-  updateVoiceState({ d, t }) {
+  updateVoiceState({d, t}) {
     if (!d?.guild_id || (t !== 'VOICE_STATE_UPDATE' && t !== 'VOICE_SERVER_UPDATE')) return
     const player = this.players.get(d.guild_id)
     if (!player) return
@@ -454,10 +475,7 @@ class Aqua extends EventEmitter {
   fetchRegion(region) {
     if (!region) return this.leastUsedNodes
     const lower = region.toLowerCase()
-    const filtered = []
-    for (const node of this.nodeMap.values()) {
-      if (node.connected && node.regions?.includes(lower)) filtered.push(node)
-    }
+    const filtered = Array.from(this.nodeMap.values()).filter(n => n.connected && n.regions?.includes(lower))
     return Object.freeze(filtered.sort((a, b) => this._getNodeLoad(a) - this._getNodeLoad(b)))
   }
 
@@ -498,10 +516,10 @@ class Aqua extends EventEmitter {
     if (!player) return
     this.players.delete(guildId)
     _safeCall(() => player.removeAllListeners())
-    await _safeCallAsync(async () => await player.destroy())
+    await _safeCall(() => player.destroy())
   }
 
-  async resolve({ query, source = this.defaultSearchPlatform, requester, nodes }) {
+  async resolve({query, source = this.defaultSearchPlatform, requester, nodes}) {
     if (!this.initiated) throw new Error('Aqua not initialized')
     const node = this._getRequestNode(nodes)
     if (!node) throw new Error('No nodes available')
@@ -541,8 +559,8 @@ class Aqua extends EventEmitter {
   }
 
   _constructResponse(response, requester, node) {
-    const { loadType, data, pluginInfo: rootPlugin } = response || {}
-    const base = { loadType, exception: null, playlistInfo: null, pluginInfo: rootPlugin || {}, tracks: [] }
+    const {loadType, data, pluginInfo: rootPlugin} = response || {}
+    const base = {loadType, exception: null, playlistInfo: null, pluginInfo: rootPlugin || {}, tracks: []}
     if (loadType === 'error' || loadType === 'LOAD_FAILED') {
       base.exception = data || response.exception || null
       return base
@@ -558,7 +576,7 @@ class Aqua extends EventEmitter {
         if (data) {
           const info = data.info || null
           const thumbnail = data.pluginInfo?.artworkUrl || data.tracks?.[0]?.info?.artworkUrl || null
-          if (info) base.playlistInfo = { name: info.name || info.title, thumbnail, ...info }
+          if (info) base.playlistInfo = {name: info.name || info.title, thumbnail, ...info}
           base.pluginInfo = data.pluginInfo || base.pluginInfo
           base.tracks = Array.isArray(data.tracks) ? data.tracks.map(t => _makeTrack(t, requester, node)) : []
         }
@@ -579,43 +597,26 @@ class Aqua extends EventEmitter {
   async search(query, requester, source = this.defaultSearchPlatform) {
     if (!query || !requester) return null
     try {
-      const { tracks } = await this.resolve({ query, source: source || this.defaultSearchPlatform, requester })
+      const {tracks} = await this.resolve({query, source: source || this.defaultSearchPlatform, requester})
       return tracks || null
-    } catch { return null }
-  }
-
-  async loadPlayers(filePath = './AquaPlayers.jsonl') {
-    const lockFile = `${filePath}.lock`
-    try {
-      await fs.promises.access(filePath).catch(_noop)
-      await fs.promises.writeFile(lockFile, String(process.pid), { flag: 'wx' }).catch(_noop)
-      await this._waitForFirstNode()
-      const stream = fs.createReadStream(filePath, { encoding: 'utf8' })
-      const rl = readline.createInterface({ input: stream, crlfDelay: Infinity })
-      const batch = []
-      for await (const line of rl) {
-        if (!line.trim()) continue
-        try { batch.push(JSON.parse(line)) } catch { continue }
-        if (batch.length >= PLAYER_BATCH_SIZE) {
-          await Promise.allSettled(batch.map(p => this._restorePlayer(p)))
-          batch.length = 0
-        }
-      }
-      if (batch.length) await Promise.allSettled(batch.map(p => this._restorePlayer(p)))
-      await fs.promises.writeFile(filePath, '')
-    } catch { } finally {
-      await fs.promises.unlink(lockFile).catch(_noop)
+    } catch {
+      return null
     }
   }
 
   async savePlayer(filePath = './AquaPlayers.jsonl') {
     const lockFile = `${filePath}.lock`
+    const tempFile = `${filePath}.tmp`
+    let ws = null
     try {
-      await fs.promises.writeFile(lockFile, String(process.pid), { flag: 'wx' }).catch(_noop)
-      const ws = fs.createWriteStream(filePath, { encoding: 'utf8', flags: 'w' })
+      await fs.promises.writeFile(lockFile, String(process.pid), {flag: 'wx'})
+      ws = fs.createWriteStream(tempFile, {encoding: 'utf8', flags: 'w'})
       const buffer = []
+      let writePromise = Promise.resolve()
+
       for (const player of this.players.values()) {
         const requester = player.requester || player.current?.requester
+        console.log(`Saving player for guild ${player.guildId} to ${player}`)
         const data = {
           g: player.guildId,
           t: player.textChannel,
@@ -623,28 +624,84 @@ class Aqua extends EventEmitter {
           u: player.current?.uri || null,
           p: player.position || 0,
           ts: player.timestamp || 0,
-          q: player.queue.slice(0, 10).map(tr => tr.uri),
-          r: requester ? JSON.stringify({ id: requester.id, username: requester.username }) : null,
+          q: player.queue.slice(0, MAX_QUEUE_SAVE).map(tr => tr.uri),
+          r: requester ? `${requester.id}:${requester.username}` : null,
           vol: player.volume,
           pa: player.paused,
           pl: player.playing,
-          nw: player.nowPlayingMessage?.id || null
+          nw: player.nowPlayingMessage?.id || null,
+          resuming: true
         }
         buffer.push(JSON.stringify(data))
-        if (buffer.length >= 100) {
-          ws.write(buffer.join('\n') + '\n')
+
+        if (buffer.length >= WRITE_BUFFER_SIZE) {
+          const chunk = buffer.join('\n') + '\n'
           buffer.length = 0
+          if (!ws.write(chunk)) {
+            writePromise = writePromise.then(() => new Promise(resolve => ws.once('drain', resolve)))
+          }
         }
       }
-      if (buffer.length) ws.write(buffer.join('\n') + '\n')
-      await new Promise(resolve => ws.end(resolve))
+
+      if (buffer.length) {
+        const chunk = buffer.join('\n') + '\n'
+        ws.write(chunk)
+      }
+
+      await writePromise
+      await new Promise((resolve, reject) => {
+        ws.end(err => err ? reject(err) : resolve())
+      })
+      ws = null
+
+      await fs.promises.rename(tempFile, filePath)
     } catch (error) {
       this.emit(AqualinkEvents.Error, null, error)
+      if (ws) _safeCall(() => ws.destroy())
+      await fs.promises.unlink(tempFile).catch(_noop)
     } finally {
       await fs.promises.unlink(lockFile).catch(_noop)
     }
   }
 
+  async loadPlayers(filePath = './AquaPlayers.jsonl') {
+    const lockFile = `${filePath}.lock`
+    let stream = null
+    let rl = null
+    try {
+      await fs.promises.access(filePath)
+      await fs.promises.writeFile(lockFile, String(process.pid), {flag: 'wx'})
+      await this._waitForFirstNode()
+
+      stream = fs.createReadStream(filePath, {encoding: 'utf8'})
+      rl = readline.createInterface({input: stream, crlfDelay: Infinity})
+
+      const batch = []
+      for await (const line of rl) {
+        if (!line.trim()) continue
+        try {
+          batch.push(JSON.parse(line))
+        } catch {
+          continue
+        }
+        if (batch.length >= PLAYER_BATCH_SIZE) {
+          await Promise.allSettled(batch.map(p => this._restorePlayer(p)))
+          batch.length = 0
+        }
+      }
+      if (batch.length) await Promise.allSettled(batch.map(p => this._restorePlayer(p)))
+
+      // Clear file after successful load
+      await fs.promises.writeFile(filePath, '')
+    } catch (err) {
+      if (err.code !== 'ENOENT') this.emit(AqualinkEvents.Error, null, err)
+    } finally {
+      if (rl) _safeCall(() => rl.close())
+      if (stream) _safeCall(() => stream.destroy())
+      await fs.promises.unlink(lockFile).catch(_noop)
+    }
+  }
+
   async _restorePlayer(p) {
     try {
       const player = this.players.get(p.g) || this.createPlayer(this._chooseLeastBusyNode(this.leastUsedNodes), {
@@ -652,14 +709,19 @@ class Aqua extends EventEmitter {
         textChannel: p.t,
         voiceChannel: p.v,
         defaultVolume: p.vol || 65,
-        deaf: true
+        deaf: true,
+        // indicate this player is being restored from persisted state so Connection
+        // can behave accordingly (attempt resume even if voice data is stale)
+        resuming: !!p.resuming
       })
+      // Ensure flag is set on existing players as well
+      player._resuming = !!p.resuming
       const requester = this._parseRequester(p.r)
-      const tracksToResolve = [p.u, ...(p.q || [])].filter(Boolean).slice(0, 20)
-      const resolved = await Promise.all(tracksToResolve.map(uri => this.resolve({ query: uri, requester }).catch(() => null)))
+      const tracksToResolve = [p.u, ...(p.q || [])].filter(Boolean).slice(0, MAX_TRACKS_RESTORE)
+      const resolved = await Promise.all(tracksToResolve.map(uri => this.resolve({query: uri, requester}).catch(() => null)))
       const validTracks = resolved.flatMap(r => r?.tracks || [])
       if (validTracks.length && player.queue?.add) {
-        if (player.queue.length <= 2) player.queue.length = 0;
+        if (player.queue.length <= 2) player.queue.length = 0
         player.queue.add(...validTracks)
       }
       if (p.u && validTracks[0]) {
@@ -677,16 +739,13 @@ class Aqua extends EventEmitter {
           player.nowPlayingMessage = await channel.messages.fetch(p.nw).catch(() => null)
         }
       }
-    } catch { }
+    } catch {}
   }
 
   _parseRequester(str) {
     if (!str || typeof str !== 'string') return null
-    try { return JSON.parse(str) }
-    catch {
-      const i = str.indexOf(':')
-      return i > 0 ? { id: str.substring(0, i), username: str.substring(i + 1) } : null
-    }
+    const i = str.indexOf(':')
+    return i > 0 ? {id: str.substring(0, i), username: str.substring(i + 1)} : null
   }
 
   async _waitForFirstNode(timeout = NODE_TIMEOUT) {
@@ -714,12 +773,12 @@ class Aqua extends EventEmitter {
   _performCleanup() {
     const now = Date.now()
 
+    // Cleanup expired broken players
     for (const [guildId, state] of this._brokenPlayers) {
-      if (now - state.brokenAt > BROKEN_PLAYER_TTL) {
-        this._brokenPlayers.delete(guildId)
-      }
+      if (now - state.brokenAt > BROKEN_PLAYER_TTL) this._brokenPlayers.delete(guildId)
     }
 
+    // Cleanup old failover attempts
     for (const [id, ts] of this._lastFailoverAttempt) {
       if (now - ts > FAILOVER_CLEANUP_TTL) {
         this._lastFailoverAttempt.delete(id)
@@ -729,27 +788,19 @@ class Aqua extends EventEmitter {
 
     this._trimBrokenPlayers()
     if (this._failoverQueue.size > MAX_FAILOVER_QUEUE) this._failoverQueue.clear()
-    if (this._rebuildLocks.size > 100) this._rebuildLocks.clear()
+    if (this._rebuildLocks.size > MAX_REBUILD_LOCKS) this._rebuildLocks.clear()
 
-    for (const [id] of this._nodeStates) {
+    // Cleanup orphaned node states
+    for (const id of this._nodeStates.keys()) {
       if (!this.nodeMap.has(id)) this._nodeStates.delete(id)
     }
   }
 
-
   _trimBrokenPlayers() {
     if (this._brokenPlayers.size <= MAX_BROKEN_PLAYERS) return
     const sorted = [...this._brokenPlayers.entries()].sort((a, b) => a[1].brokenAt - b[1].brokenAt)
     sorted.slice(0, sorted.length - MAX_BROKEN_PLAYERS).forEach(([id]) => this._brokenPlayers.delete(id))
   }
-
-  _getAvailableNodes(excludeNode) {
-    const nodes = []
-    for (const node of this.nodeMap.values()) {
-      if (node !== excludeNode && node.connected) nodes.push(node)
-    }
-    return nodes
-  }
 }
 
 module.exports = Aqua

package/build/structures/Connection.js

@@ -125,10 +125,18 @@ class Connection {
   }
 
   _canAttemptResume () {
-    return !this._destroyed &&
-           this._hasValidVoiceData() &&
-           this._reconnectAttempts < MAX_RECONNECT_ATTEMPTS &&
-           !(this._stateFlags & (STATE_FLAGS.ATTEMPTING_RESUME | STATE_FLAGS.DISCONNECTING | STATE_FLAGS.VOICE_DATA_STALE))
+    // Allow resume if connection isn't destroyed, attempts remain, and we're
+    // not already attempting or disconnecting. If voice data is stale, permit
+    // a resume attempt only when the player was restored from persisted state
+    // (player._resuming === true).
+    if (this._destroyed) return false
+    if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) return false
+    if (this._stateFlags & (STATE_FLAGS.ATTEMPTING_RESUME | STATE_FLAGS.DISCONNECTING)) return false
+
+    if (this._hasValidVoiceData()) return true
+
+    // If voice data is stale, allow a single resume flow for restored players
+    return !!this._player?._resuming
   }
 
   setServerUpdate (data) {
@@ -236,9 +244,38 @@ class Connection {
   async attemptResume () {
     if (!this._canAttemptResume()) {
       this._aqua.emit(AqualinkEvents.Debug, `Resume blocked: destroyed=${this._destroyed}, hasValidData=${this._hasValidVoiceData()}, attempts=${this._reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS}`)
-      if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS || (this._stateFlags & STATE_FLAGS.VOICE_DATA_STALE)) {
+
+      // If voice data is stale (likely after a restart) and this player is
+      // marked as resuming, request a fresh voice state update and schedule
+      // a retry instead of destroying the player immediately.
+      if ((this._stateFlags & STATE_FLAGS.VOICE_DATA_STALE) && this._player?._resuming) {
+        try {
+          this._aqua.emit(AqualinkEvents.Debug, `Requesting fresh voice state for guild ${this._guildId}`)
+          if (typeof this._player.send === 'function' && this._player.voiceChannel) {
+            this._player.send({ guild_id: this._guildId, channel_id: this._player.voiceChannel, self_deaf: this._player.deaf, self_mute: this._player.mute })
+            this._reconnectTimer = setTimeout(this._handleReconnect, 1500)
+            helpers.safeUnref(this._reconnectTimer)
+          }
+        } catch (e) {}
+      } else if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
         this._handleDisconnect()
       }
+
+      return false
+    }
+
+    // If the player was restored from disk but core voice data is still missing,
+    // request a voice state update and retry shortly rather than attempting a
+    // resume payload that will fail.
+    if ((!this.sessionId || !this.endpoint || !this.token) && this._player?._resuming) {
+      try {
+        this._aqua.emit(AqualinkEvents.Debug, `Resuming player but voice data missing, requesting voice state for guild ${this._guildId}`)
+        if (typeof this._player.send === 'function' && this._player.voiceChannel) {
+          this._player.send({ guild_id: this._guildId, channel_id: this._player.voiceChannel, self_deaf: this._player.deaf, self_mute: this._player.mute })
+          this._reconnectTimer = setTimeout(this._handleReconnect, 1500)
+          helpers.safeUnref(this._reconnectTimer)
+        }
+      } catch (e) {}
       return false
     }
 
@@ -263,6 +300,7 @@ class Connection {
 
       this._reconnectAttempts = 0
       this._consecutiveFailures = 0
+      if (this._player) this._player._resuming = false
       this._aqua.emit(AqualinkEvents.Debug, `Resume successful for guild ${this._guildId}`)
       return true
     } catch (error) {
@@ -275,6 +313,7 @@ class Connection {
         helpers.safeUnref(this._reconnectTimer)
       } else {
         this._aqua.emit(AqualinkEvents.Debug, `Max reconnect attempts or failures reached for guild ${this._guildId}`)
+        if (this._player) this._player._resuming = false
         this._handleDisconnect()
       }