aqualink 2.19.0 → 2.20.0

package/build/structures/Aqua.js

@@ -1,8 +1,6 @@
-'use strict'
-
 const fs = require('node:fs')
 const readline = require('node:readline')
-const { EventEmitter } = require('tseep')
+const { EventEmitter } = require('node:events')
 const { AqualinkEvents } = require('./AqualinkEvents')
 const Node = require('./Node')
 const Player = require('./Player')
@@ -23,7 +21,6 @@ const MAX_CONCURRENT_OPS = 10
 const BROKEN_PLAYER_TTL = 300000
 const FAILOVER_CLEANUP_TTL = 600000
 const PLAYER_BATCH_SIZE = 20
-const SEEK_DELAY = 120
 const RECONNECT_DELAY = 400
 const CACHE_VALID_TIME = 12000
 const NODE_TIMEOUT = 30000
@@ -31,8 +28,7 @@ const MAX_CACHE_SIZE = 20
 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 TRACE_BUFFER_SIZE = 3000
 
 const DEFAULT_OPTIONS = Object.freeze({
   shouldDeleteMessage: false,
@@ -44,6 +40,10 @@ const DEFAULT_OPTIONS = Object.freeze({
   infiniteReconnects: true,
   loadBalancer: 'leastLoad',
   useHttp2: false,
+  debugTrace: false,
+  traceMaxEntries: TRACE_BUFFER_SIZE,
+  traceSink: null,
+  autoRegionMigrate: false,
   failoverOptions: Object.freeze({
     enabled: true,
     maxRetries: 3,
@@ -126,10 +126,22 @@ class Aqua extends EventEmitter {
     this.restrictedDomains = merged.restrictedDomains || []
     this.allowedDomains = merged.allowedDomains || []
     this.loadBalancer = merged.loadBalancer
+    this.autoRegionMigrate = merged.autoRegionMigrate
     this.useHttp2 = merged.useHttp2
     this.maxQueueSave = merged.maxQueueSave
     this.maxTracksRestore = merged.maxTracksRestore
     this.send = merged.send || this._createDefaultSend()
+    this.debugTrace = !!merged.debugTrace
+    this.traceMaxEntries = Math.max(
+      100,
+      Number(merged.traceMaxEntries) || TRACE_BUFFER_SIZE
+    )
+    this.traceSink =
+      typeof merged.traceSink === 'function' ? merged.traceSink : null
+    this._traceBuffer = new Array(this.traceMaxEntries)
+    this._traceBufferCount = 0
+    this._traceBufferIndex = 0
+    this._traceSeq = 0
 
     this._nodeStates = new Map()
     this._failoverQueue = new Map()
@@ -145,6 +157,49 @@ class Aqua extends EventEmitter {
     if (this.autoResume) this._bindEventHandlers()
   }
 
+  _trace(event, data = null) {
+    if (!this.debugTrace) return
+    const entry = {
+      seq: ++this._traceSeq,
+      at: Date.now(),
+      event,
+      data
+    }
+    if (this._traceBuffer.length !== this.traceMaxEntries) {
+      this._traceBuffer = new Array(this.traceMaxEntries)
+      this._traceBufferCount = 0
+      this._traceBufferIndex = 0
+    }
+    this._traceBuffer[this._traceBufferIndex] = entry
+    this._traceBufferIndex = (this._traceBufferIndex + 1) % this.traceMaxEntries
+    if (this._traceBufferCount < this.traceMaxEntries) this._traceBufferCount++
+    if (this.traceSink) _functions.safeCall(() => this.traceSink(entry))
+    if (this.listenerCount(AqualinkEvents.Debug) > 0) {
+      this.emit(AqualinkEvents.Debug, 'trace', JSON.stringify(entry))
+    }
+  }
+
+  getTrace(limit = 300) {
+    const max = Math.max(1, Number(limit) || 300)
+    const count = Math.min(max, this._traceBufferCount)
+    if (!count) return []
+    const out = new Array(count)
+    let start =
+      (this._traceBufferIndex - count + this.traceMaxEntries) %
+      this.traceMaxEntries
+    for (let i = 0; i < count; i++) {
+      out[i] = this._traceBuffer[start]
+      start = (start + 1) % this.traceMaxEntries
+    }
+    return out
+  }
+
+  clearTrace() {
+    this._traceBuffer.fill(undefined)
+    this._traceBufferCount = 0
+    this._traceBufferIndex = 0
+  }
+
   _createDefaultSend() {
     return (packet) => {
       const guildId = packet?.d?.guild_id
@@ -161,12 +216,13 @@ class Aqua extends EventEmitter {
 
   _bindEventHandlers() {
     this._eventHandlers = {
-      onNodeConnect: async (node) => {
+      onNodeConnect: (node) => {
+        this._trace('node.connect', { node: node?.name || node?.host })
         this._invalidateCache()
-        await this._rebuildBrokenPlayers(node)
         this._performCleanup()
       },
       onNodeDisconnect: (node) => {
+        this._trace('node.disconnect', { node: node?.name || node?.host })
         this._invalidateCache()
         queueMicrotask(() => {
           this._storeBrokenPlayers(node)
@@ -174,15 +230,27 @@ class Aqua extends EventEmitter {
         })
       },
       onNodeReady: (node, { resumed }) => {
-        if (!resumed) return
-        const batch = []
-        for (const player of this.players.values()) {
-          if (player.nodes === node && player.connection) batch.push(player)
+        this._trace('node.ready', {
+          node: node?.name || node?.host,
+          resumed: !!resumed,
+          players: this.players.size
+        })
+        if (resumed) {
+          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()
+              })
+            )
+          return
         }
-        if (batch.length)
-          queueMicrotask(() =>
-            batch.forEach((p) => p.connection.resendVoiceUpdate())
-          )
+        queueMicrotask(() => {
+          this._rebuildBrokenPlayers(node).catch(_functions.noop)
+        })
       }
     }
     this.on(AqualinkEvents.NodeConnect, this._eventHandlers.onNodeConnect)
@@ -257,7 +325,11 @@ class Aqua extends EventEmitter {
     const id = node.name || node.host
     const now = Date.now()
     const cached = this._nodeLoadCache.get(id)
-    if (cached && now - cached.time < 5000) return cached.load
+    if (cached && now - cached.time < 5000) {
+      this._nodeLoadCache.delete(id)
+      this._nodeLoadCache.set(id, cached)
+      return cached.load
+    }
     const stats = node?.stats
     if (!stats) return 0
     const cores = Math.max(1, stats.cpu?.cores || 1)
@@ -267,11 +339,15 @@ class Aqua extends EventEmitter {
       (stats.playingPlayers || 0) * 0.75 +
       (stats.memory ? stats.memory.used / reservable : 0) * 40 +
       (node.rest?.calls || 0) * 0.001
-    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)
+    if (this._nodeLoadCache.size >= MAX_CACHE_SIZE) {
+      const iterator = this._nodeLoadCache.keys()
+      while (this._nodeLoadCache.size >= MAX_CACHE_SIZE) {
+        const oldest = iterator.next().value
+        if (!oldest) break
+        this._nodeLoadCache.delete(oldest)
+      }
     }
+    this._nodeLoadCache.set(id, { load, time: now })
     return load
   }
 
@@ -329,9 +405,8 @@ class Aqua extends EventEmitter {
   _destroyNode(id) {
     const node = this.nodeMap.get(id)
     if (!node) return
-    _functions.safeCall(() => node.destroy())
+    _functions.safeCall(() => node.destroy(true))
     this._cleanupNode(id)
-    this.emit(AqualinkEvents.NodeDestroy, node)
   }
 
   _cleanupNode(id) {
@@ -420,18 +495,7 @@ class Aqua extends EventEmitter {
       if (current && player?.queue?.add) {
         player.queue.add(current)
         await player.play()
-        if (state.position > 0) {
-          const seekOnce = (p) => {
-            if (p.guildId === guildId) {
-              this.off(AqualinkEvents.TrackStart, seekOnce)
-              _functions.unrefTimeout(() => player.seek?.(state.position), 50)
-            }
-          }
-          this.once(AqualinkEvents.TrackStart, seekOnce)
-          player.once('destroy', () =>
-            this.off(AqualinkEvents.TrackStart, seekOnce)
-          )
-        }
+        this._seekAfterTrackStart(player, guildId, state.position, 50)
         if (state.paused) player.pause(true)
       }
       return player
@@ -528,9 +592,111 @@ class Aqua extends EventEmitter {
         return newPlayer
       } catch (error) {
         if (retry === maxRetries - 1) throw error
-        await _functions.delay(retryDelay * Math.pow(1.5, retry))
+        await _functions.delay(retryDelay * 1.5 ** retry)
+      }
+    }
+  }
+
+  _regionMatches(configuredRegion, extractedRegion) {
+    if (!configuredRegion || !extractedRegion) return false
+    const configured = String(configuredRegion).trim().toLowerCase()
+    const extracted = String(extractedRegion).trim().toLowerCase()
+    if (!configured || !extracted) return false
+    return configured === extracted
+  }
+
+  _findBestNodeForRegion(region) {
+    if (!region) return null
+    const candidates = []
+    for (const node of this.nodeMap.values()) {
+      if (!node?.connected) continue
+      const regions = Array.isArray(node.regions) ? node.regions : []
+      if (regions.some((r) => this._regionMatches(r, region))) {
+        candidates.push(node)
       }
     }
+    if (!candidates.length) return null
+    return this._chooseLeastBusyNode(candidates)
+  }
+
+  async movePlayerToNode(guildId, targetNode, reason = 'region') {
+    const id = String(guildId)
+    const player = this.players.get(id)
+    if (!player || player.destroyed) throw new Error(`Player not found: ${id}`)
+    if (!targetNode?.connected) throw new Error('Target node is not connected')
+    if (player.nodes === targetNode || player.nodes?.name === targetNode.name)
+      return player
+
+    const state = this._capturePlayerState(player)
+    if (!state) throw new Error(`Failed to capture state for ${id}`)
+    const oldPlayer = player
+    const oldNode = oldPlayer.nodes
+    const oldMessage = oldPlayer.nowPlayingMessage || null
+    const oldConn = oldPlayer.connection
+    const oldVoice = oldConn
+      ? {
+          sessionId: oldConn.sessionId || null,
+          endpoint: oldConn.endpoint || null,
+          token: oldConn.token || null,
+          region: oldConn.region || null,
+          channelId: oldConn.channelId || null
+        }
+      : null
+
+    oldPlayer.destroy({
+      preserveClient: true,
+      skipRemote: true,
+      preserveMessage: true,
+      preserveTracks: true,
+      preserveReconnecting: true
+    })
+
+    const newPlayer = this.createPlayer(targetNode, {
+      guildId: state.guildId,
+      textChannel: state.textChannel,
+      voiceChannel: state.voiceChannel,
+      defaultVolume: state.volume || 100,
+      deaf: state.deaf || false,
+      mute: oldPlayer.mute || false,
+      resuming: true,
+      preserveMessage: true
+    })
+
+    // Bootstrap voice on the new node using last known voice state to avoid
+    // "track queued, waiting for voice state" after region migration.
+    if (oldVoice && newPlayer.connection) {
+      if (oldVoice.sessionId)
+        newPlayer.connection.sessionId = oldVoice.sessionId
+      if (oldVoice.endpoint) newPlayer.connection.endpoint = oldVoice.endpoint
+      if (oldVoice.token) newPlayer.connection.token = oldVoice.token
+      if (oldVoice.region) newPlayer.connection.region = oldVoice.region
+      if (oldVoice.channelId)
+        newPlayer.connection.channelId = oldVoice.channelId
+      newPlayer.connection._lastVoiceDataUpdate = Date.now()
+      newPlayer.connection.resendVoiceUpdate(true)
+      this._trace('player.migrate.voiceBootstrap', {
+        guildId: id,
+        from: oldNode?.name || oldNode?.host,
+        to: targetNode?.name || targetNode?.host,
+        hasSessionId: !!newPlayer.connection.sessionId,
+        hasEndpoint: !!newPlayer.connection.endpoint,
+        hasToken: !!newPlayer.connection.token
+      })
+    }
+
+    await this._restorePlayerState(newPlayer, state)
+    if (oldMessage) newPlayer.nowPlayingMessage = oldMessage
+
+    this._trace('player.migrated', {
+      guildId: id,
+      reason,
+      from: oldNode?.name || oldNode?.host,
+      to: targetNode?.name || targetNode?.host,
+      region:
+        newPlayer?.connection?.region || oldPlayer?.connection?.region || null
+    })
+    this.emit(AqualinkEvents.PlayerMigrated, oldPlayer, newPlayer, targetNode)
+    return newPlayer
   }
 
   _capturePlayerState(player) {
@@ -569,6 +735,16 @@ class Aqua extends EventEmitter {
     })
   }
 
+  _seekAfterTrackStart(player, guildId, position, delay = 50) {
+    if (!player || !guildId || !(position > 0)) return
+    const seekOnce = (p) => {
+      if (p.guildId !== guildId) return
+      _functions.unrefTimeout(() => player.seek?.(position), delay)
+    }
+    this.once(AqualinkEvents.TrackStart, seekOnce)
+    player.once('destroy', () => this.off(AqualinkEvents.TrackStart, seekOnce))
+  }
+
   async _restorePlayerState(newPlayer, state) {
     const ops = []
     if (typeof state.volume === 'number') {
@@ -579,26 +755,17 @@ 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 })
       if (this.failoverOptions.resumePlayback) {
-        ops.push(newPlayer.play())
-        if (state.position > 0) {
-          const guildId = newPlayer.guildId
-          const seekOnce = (p) => {
-            if (p.guildId === guildId) {
-              this.off(AqualinkEvents.TrackStart, seekOnce)
-              _functions.unrefTimeout(
-                () => newPlayer.seek?.(state.position),
-                50
-              )
-            }
-          }
-          this.once(AqualinkEvents.TrackStart, seekOnce)
-          newPlayer.once('destroy', () =>
-            this.off(AqualinkEvents.TrackStart, seekOnce)
-          )
-        }
+        ops.push(newPlayer.play(state.current))
+        this._seekAfterTrackStart(
+          newPlayer,
+          newPlayer.guildId,
+          state.position,
+          50
+        )
         if (state.paused) ops.push(newPlayer.pause(true))
+      } else if (newPlayer.queue?.add) {
+        newPlayer.queue.add(state.current)
       }
     }
     newPlayer.loop = state.loop
@@ -614,6 +781,13 @@ class Aqua extends EventEmitter {
       return
     const player = this.players.get(String(d.guild_id))
     if (!player) return
+    this._trace('voice.gateway', {
+      guildId: String(d.guild_id),
+      type: t,
+      hasSessionId: !!d.session_id,
+      hasEndpoint: !!d.endpoint,
+      hasChannelId: d.channel_id !== undefined
+    })
 
     d.txId = player.txId
     if (t === 'VOICE_STATE_UPDATE') {
@@ -676,6 +850,13 @@ class Aqua extends EventEmitter {
     const player = new Player(this, node, options)
     const guildId = String(options.guildId)
     this.players.set(guildId, player)
+    this._trace('player.create', {
+      guildId,
+      node: node?.name || node?.host,
+      voiceChannel: options.voiceChannel,
+      textChannel: options.textChannel,
+      resuming: !!options.resuming
+    })
     node?.players?.add?.(player)
     player.once('destroy', () => this._handlePlayerDestroy(player))
     player.connect(options)
@@ -687,6 +868,10 @@ class Aqua extends EventEmitter {
     player.nodes?.players?.delete?.(player)
     const guildId = String(player.guildId)
     if (this.players.get(guildId) === player) this.players.delete(guildId)
+    this._trace('player.destroyed', {
+      guildId,
+      node: player?.nodes?.name || player?.nodes?.host
+    })
     this.emit(AqualinkEvents.PlayerDestroyed, player)
   }
 
@@ -694,9 +879,13 @@ class Aqua extends EventEmitter {
     const id = String(guildId)
     const player = this.players.get(id)
     if (!player) return
+
+    // Guard against recursive destroy calls triggered by Player.destroy().
     this.players.delete(id)
-    _functions.safeCall(() => player.removeAllListeners())
     await _functions.safeCall(() => player.destroy())
+
+    // Fallback cleanup in case the player "destroy" listener was not attached.
+    if (player?.nodes?.players?.has?.(player)) this._handlePlayerDestroy(player)
   }
 
   async resolve({ query, source, requester, nodes }) {
@@ -774,7 +963,10 @@ class Aqua extends EventEmitter {
     }
     if (loadType === 'track' && data) {
       base.pluginInfo =
-        data.info?.pluginInfo || data.pluginInfo || base.pluginInfo
+        data.pluginInfo ||
+        data.info?.pluginInfo ||
+        rootPlugin ||
+        base.pluginInfo
       base.tracks.push(_functions.makeTrack(data, requester, node))
     } else if (loadType === 'playlist' && data) {
       const info = data.info
@@ -858,7 +1050,7 @@ class Aqua extends EventEmitter {
         buffer.push(JSON.stringify(data))
 
         if (buffer.length >= WRITE_BUFFER_SIZE) {
-          const chunk = buffer.join('\n') + '\n'
+          const chunk = `${buffer.join('\n')}\n`
           buffer.length = 0
           if (!ws.write(chunk)) {
             drainPromise = drainPromise.then(
@@ -868,7 +1060,7 @@ class Aqua extends EventEmitter {
         }
       }
 
-      if (buffer.length) ws.write(buffer.join('\n') + '\n')
+      if (buffer.length) ws.write(`${buffer.join('\n')}\n`)
       await drainPromise
       await new Promise((resolve, reject) =>
         ws.end((err) => (err ? reject(err) : resolve()))
@@ -935,7 +1127,7 @@ class Aqua extends EventEmitter {
     try {
       const gId = String(p.g)
       const existing = this.players.get(gId)
-      if (existing && existing.playing) return
+      if (existing?.playing) return
 
       const player =
         existing ||
@@ -968,25 +1160,26 @@ class Aqua extends EventEmitter {
           else player.volume = p.vol
         }
 
-        if (p.p > 0) {
-          const seekOnce = (pl) => {
-            if (pl.guildId === gId) {
-              this.off(AqualinkEvents.TrackStart, seekOnce)
-              _functions.unrefTimeout(() => player.seek?.(p.p), 100)
-            }
-          }
-          this.on(AqualinkEvents.TrackStart, seekOnce)
-          player.once('destroy', () => this.off(AqualinkEvents.TrackStart, seekOnce))
-        }
+        this._seekAfterTrackStart(player, gId, p.p, 100)
 
         await player.play(undefined, { startTime: p.p, paused: p.pa })
       }
       if (p.nw && p.t) {
-        const channel = this.client.channels?.cache?.get(p.t)
-        if (channel?.messages)
+        const channel = this.client.channels?.cache?.get?.(p.t)
+        if (channel?.messages?.fetch) {
           player.nowPlayingMessage = await channel.messages
             .fetch(p.nw)
             .catch(() => null)
+        } else if (this.client.messages?.fetch) {
+          player.nowPlayingMessage = await this.client.messages
+            .fetch(p.nw, p.t)
+            .catch(() => null)
+        }
+        this._trace('player.nowPlaying.restore', {
+          guildId: gId,
+          messageId: p.nw,
+          restored: !!player.nowPlayingMessage
+        })
       }
     } catch (e) {
       console.error(
@@ -1067,9 +1260,7 @@ class Aqua extends EventEmitter {
             }
             break
           }
-        } catch {
-          continue
-        }
+        } catch {}
       }
     } catch {
     } finally {

package/build/structures/AqualinkEvents.js

@@ -1,5 +1,3 @@
-'use strict'
-
 const AqualinkEvents = {
   TrackStart: 'trackStart',
   TrackEnd: 'trackEnd',