Failover System

Configuration

Basic Failover Setup

const { Aqua } = require('aqualink');

const aqua = new Aqua(client, {
  nodes: [
    {
      host: 'localhost',
      port: 2333,
      auth: 'youshallnotpass',
      ssl: false,
      name: 'main-node'
    },
    {
      host: 'backup.server.com',
      port: 2333,
      auth: 'backup_password',
      ssl: false,
      name: 'backup-node'
    }
  ],
  defaultSearchPlatform: 'ytsearch',
  nodeResolver: 'LeastLoad'
  shouldDeleteMessage: false,
  leaveOnEnd: true,
  restVersion: 'v4',
  plugins: [],
  autoResume: false,
  infiniteReconnects: false,
  failoverOptions: {
    enabled: true,
    maxRetries: 3,
    retryDelay: 1000,
    preservePosition: true,
    resumePlayback: true,
    cooldownTime: 5000,
    maxFailoverAttempts: 5
  }
});

Failover Configuration Options

Available Options

const failoverOptions = {
  enabled: true,
  maxRetries: 3,
  retryDelay: 1000,
  preservePosition: true,
  resumePlayback: true,
  cooldownTime: 5000,
  maxFailoverAttempts: 5
};

Option Descriptions

enabled: Whether failover is active
maxRetries: Maximum retry attempts per failure
retryDelay: Delay between retries (milliseconds)
preservePosition: Keep track position during failover
resumePlayback: Automatically resume after failover
cooldownTime: Wait time before allowing new failover attempts
maxFailoverAttempts: Total failover attempts before giving up

Multiple Nodes Setup

Adding Backup Nodes

const aqua = new Aqua(client, {
  nodes: [
    {
      host: 'primary.server.com',
      port: 2333,
      auth: 'primary_pass',
      ssl: false,
      name: 'primary-node'
    },
    {
      host: 'secondary.server.com',
      port: 2333,
      auth: 'secondary_pass',
      ssl: false,
      name: 'secondary-node'
    },
    {
      host: 'tertiary.server.com',
      port: 2333,
      auth: 'tertiary_pass',
      ssl: false,
      name: 'tertiary-node'
    }
  ],
  failoverOptions: {
    enabled: true,
    maxRetries: 5,
    retryDelay: 2000,
    preservePosition: true,
    resumePlayback: true,
    cooldownTime: 10000,
    maxFailoverAttempts: 10
  }
});

Event Handling

Failover Events

const { AqualinkEvents } = require('aqualink');

aqua.on(AqualinkEvents.NodeFailover, (node) => {
  console.log(`Node ${node.name} is failing over...`);
});

aqua.on(AqualinkEvents.NodeFailoverComplete, (node, successful, failed) => {
  console.log(`Node ${node.name} failover complete. Migrated ${successful} players, ${failed} failed.`);
});

aqua.on(AqualinkEvents.PlayerMigrated, (oldPlayer, newPlayer, newNode) => {
  console.log(`Player for guild ${oldPlayer.guildId} moved from ${oldPlayer.nodes.name} to ${newNode.name}`);
});

aqua.on(AqualinkEvents.NodeDisconnect, (node, { code, reason }) => {
  console.log(`Node ${node.name} disconnected: ${reason} (code: ${code})`);
});

aqua.on(AqualinkEvents.NodeError, (node, error) => {
  console.error(`Node ${node.name} error:`, error);
});

Node Management

Check Node Status

function getNodeStatus() {
  const nodes = aqua.nodeMap;
  const status = {};
  
  for (const [name, node] of nodes) {
    status[name] = {
      connected: node.connected,
      players: node.players.size,
      stats: node.stats
    };
  }
  
  return status;
}

console.log('Node Status:', getNodeStatus());

Get Available Nodes

function getAvailableNodes() {
  return Array.from(aqua.nodeMap.values())
    .filter(node => node.connected)
    .map(node => ({
      name: node.name,
      players: node.players.size,
      connected: node.connected
    }));
}

Player State Preservation

State Backup During Failover

class PlayerStateManager {
  constructor() {
    this.states = new Map();
  }
  
  backup(player) {
    const state = {
      guildId: player.guildId,
      voiceChannel: player.voiceChannel,
      textChannel: player.textChannel,
      queue: player.queue.slice(),
      currentTrack: player.current,
      position: player.position,
      volume: player.volume,
      paused: player.paused,
      timestamp: Date.now()
    };
    
    this.states.set(player.guildId, state);
    return state;
  }
  
  restore(player, state) {
    if (!state) return false;
    
    try {
      if (state.queue && state.queue.length > 0) {
        player.queue.push(...state.queue);
      }
      
      if (state.currentTrack) {
        player.queue.unshift(state.currentTrack);
        player.seek(state.position);
      }
      
      if (state.volume !== player.volume) {
        player.setVolume(state.volume);
      }
      
      if (state.paused) {
        player.pause(true);
      }
      
      return true;
    } catch (error) {
      console.error('Failed to restore player state:', error);
      return false;
    }
  }
}

const stateManager = new PlayerStateManager();

Manual Node Operations

Force Node Switch

async function movePlayerToNode(guildId, targetNodeName) {
  const player = aqua.players.get(guildId);
  if (!player) {
    console.log('Player not found');
    return false;
  }
  
  const targetNode = aqua.nodeMap.get(targetNodeName);
  if (!targetNode || !targetNode.connected) {
    console.log('Target node not available');
    return false;
  }
  
  const state = stateManager.backup(player);
  
  try {
    await player.destroy();
    
    const newPlayer = aqua.createConnection({
      guildId: guildId,
      voiceChannel: state.voiceChannel,
      textChannel: state.textChannel
    });
    
    stateManager.restore(newPlayer, state);
    
    console.log(`Player moved to ${targetNodeName}`);
    return true;
  } catch (error) {
    console.error('Manual node switch failed:', error);
    return false;
  }
}

Node Health Check

async function checkNodeHealth(nodeName) {
  const node = aqua.nodeMap.get(nodeName);
  if (!node) {
    return { healthy: false, error: 'Node not found' };
  }
  
  return {
    healthy: node.connected,
    players: node.players.size,
    uptime: node.stats.uptime,
    stats: node.stats
  };
}

async function checkAllNodesHealth() {
  const results = {};
  
  for (const [name, node] of aqua.nodeMap) {
    results[name] = await checkNodeHealth(name);
  }
  
  return results;
}

Monitoring

Failover Metrics

class FailoverMetrics {
  constructor() {
    this.metrics = {
      totalFailovers: 0,
      successfulFailovers: 0,
      failedFailovers: 0,
      nodeFailures: new Map(),
      lastFailover: null
    };
    
    this.setupEventListeners();
  }
  
  setupEventListeners() {
    aqua.on('nodeDisconnect', (node) => {
      this.recordNodeFailure(node.name);
    });
    
    aqua.on('playerMigrated', (player, newPlayer, newNode) => {
      this.recordFailover(true, player.nodes.name, newNode.name);
    });
  }
  
  recordNodeFailure(nodeName) {
    const current = this.metrics.nodeFailures.get(nodeName) || 0;
    this.metrics.nodeFailures.set(nodeName, current + 1);
  }
  
  recordFailover(success, fromNode, toNode) {
    this.metrics.totalFailovers++;
    
    if (success) {
      this.metrics.successfulFailovers++;
    } else {
      this.metrics.failedFailovers++;
    }
    
    this.metrics.lastFailover = {
      timestamp: Date.now(),
      success,
      fromNode,
      toNode
    };
  }
  
  getReport() {
    const successRate = this.metrics.totalFailovers > 0 
      ? (this.metrics.successfulFailovers / this.metrics.totalFailovers) * 100 
      : 0;
    
    return {
      ...this.metrics,
      successRate: successRate.toFixed(2) + '%'
    };
  }
}

const metrics = new FailoverMetrics();

Testing

Simulate Node Failure

async function simulateNodeFailure(nodeName) {
  const node = aqua.nodeMap.get(nodeName);
  if (!node) {
    console.log('Node not found');
    return;
  }
  
  console.log(`Simulating failure for node: ${nodeName}`);
  
  const affectedPlayers = Array.from(aqua.players.values())
    .filter(player => player.nodes.name === nodeName);
  
  console.log(`${affectedPlayers.length} players will be affected`);
  
  if (node.ws) {
    node.ws.close(1006, 'Simulating node failure');
  }
  
  setTimeout(() => {
    console.log('Attempting to reconnect node...');
    node.connect();
  }, 10000);
}

Failover Test

async function testFailover() {
  console.log('Starting failover test...');
  
  const initialNodes = getAvailableNodes();
  console.log('Initial nodes:', initialNodes);
  
  if (initialNodes.length < 2) {
    console.log('Need at least 2 nodes for failover test');
    return;
  }
  
  const primaryNode = initialNodes[0].name;
  await simulateNodeFailure(primaryNode);
  
  setTimeout(() => {
    const remainingNodes = getAvailableNodes();
    console.log('Nodes after failure:', remainingNodes);
    
    const activePlayerCount = aqua.players.size;
    console.log(`Active players after failover: ${activePlayerCount}`);
  }, 5000);
}

Error Handling

Failover Error Recovery

// Make sure to import AqualinkEvents from your aqualink package
// const { AqualinkEvents } = require('aqualink');

aqua.on(AqualinkEvents.NodeError, async (node, error) => {
  console.error(`Node ${node.name} encountered error:`, error.message);
  
  if (error.code === 'ECONNREFUSED') {
    console.log('Connection refused, marking node as unavailable');
  }
  
  const availableNodes = getAvailableNodes();
  if (availableNodes.length === 0) {
    console.error('No available nodes for failover!');
    
    await notifyAdmins('Critical: All music nodes are down');
  }
});

async function notifyAdmins(message) {
  console.error('ADMIN NOTIFICATION:', message);
}

Best Practices

Optimal Configuration

const aqua = new Aqua(client, {
  nodes: [
    { host: 'primary.domain.com', port: 2333, auth: 'pass1', name: 'primary', ssl: false },
    { host: 'backup.domain.com', port: 2333, auth: 'pass2', name: 'backup', ssl: false }
  ],
  failoverOptions: {
    enabled: true,
    maxRetries: 3,
    retryDelay: 1500,
    preservePosition: true,
    resumePlayback: true,
    cooldownTime: 10000,
    maxFailoverAttempts: 5
  }
});

Monitoring Setup

setInterval(async () => {
  const healthReport = await checkAllNodesHealth();
  const metricsReport = metrics.getReport();
  
  console.log('Health Report:', healthReport);
  console.log('Metrics Report:', metricsReport);
}, 30000);

Getting started

Essentials

Advanced Features

Usage & Implementation

Events & Integration

User Guides

Support

Configuration

Basic Failover Setup

Failover Configuration Options

Available Options

Option Descriptions

Multiple Nodes Setup

Adding Backup Nodes

Event Handling

Failover Events

Node Management

Check Node Status

Get Available Nodes

Player State Preservation

State Backup During Failover

Manual Node Operations

Force Node Switch

Node Health Check

Monitoring

Failover Metrics

Testing

Simulate Node Failure

Failover Test

Error Handling

Failover Error Recovery

Best Practices

Optimal Configuration

Monitoring Setup

​Configuration

​Basic Failover Setup

​Failover Configuration Options

​Available Options

​Option Descriptions

​Multiple Nodes Setup

​Adding Backup Nodes

​Event Handling

​Failover Events

​Node Management

​Check Node Status

​Get Available Nodes

​Player State Preservation

​State Backup During Failover

​Manual Node Operations

​Force Node Switch

​Node Health Check

​Monitoring

​Failover Metrics

​Testing

​Simulate Node Failure

​Failover Test

​Error Handling

​Failover Error Recovery

​Best Practices

​Optimal Configuration

​Monitoring Setup

Configuration

Basic Failover Setup

Failover Configuration Options

Available Options

Option Descriptions

Multiple Nodes Setup

Adding Backup Nodes

Event Handling

Failover Events

Node Management

Check Node Status

Get Available Nodes

Player State Preservation

State Backup During Failover

Manual Node Operations

Force Node Switch

Node Health Check

Monitoring

Failover Metrics

Testing

Simulate Node Failure

Failover Test

Error Handling

Failover Error Recovery

Best Practices

Optimal Configuration

Monitoring Setup