@pilaf/backends 1.0.0

package/lib/BotLifecycleManager.js

@@ -0,0 +1,242 @@
+/**
+ * BotLifecycleManager - Manages the complete lifecycle of a Mineflayer bot
+ * Handles creation, spawning, and disconnection with proper event-driven patterns
+ */
+
+const { ConnectionState } = require('./ConnectionState.js');
+
+class BotLifecycleManager {
+  /**
+   * Create a bot and wait for it to spawn
+   * @param {Function} createBotFn - Function that creates a Mineflayer bot
+   * @param {Object} options - Bot creation options
+   * @param {number} [options.spawnTimeout] - Max time to wait for spawn (default: 30000ms)
+   * @returns {Promise<{bot: Object, state: string}>} Bot instance and final state
+   */
+  static async createAndSpawnBot(createBotFn, options = {}) {
+    const { spawnTimeout = 30000 } = options;
+    let bot = null;
+    let currentState = ConnectionState.CONNECTING;
+
+    try {
+      // Create the bot
+      bot = createBotFn(options);
+      currentState = ConnectionState.SPAWNING;
+
+      // Wait for spawn event with proper error handling
+      await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+          // Clean up event listeners
+          bot.removeAllListeners('spawn');
+          bot.removeAllListeners('error');
+          bot.removeAllListeners('kicked');
+          bot.removeAllListeners('end');
+          reject(new Error(`Bot spawn timeout after ${spawnTimeout}ms`));
+        }, spawnTimeout);
+
+        bot.once('spawn', () => {
+          clearTimeout(timeoutId);
+          currentState = ConnectionState.SPAWNED;
+          resolve();
+        });
+
+        bot.once('error', (err) => {
+          clearTimeout(timeoutId);
+          currentState = ConnectionState.ERROR;
+          bot.removeAllListeners('spawn');
+          reject(new Error(`Bot connection error: ${err.message}`));
+        });
+
+        bot.once('kicked', (reason) => {
+          clearTimeout(timeoutId);
+          currentState = ConnectionState.ERROR;
+          bot.removeAllListeners('spawn');
+          reject(new Error(`Bot kicked by server: ${reason}`));
+        });
+
+        bot.once('end', () => {
+          if (currentState !== ConnectionState.SPAWNED) {
+            clearTimeout(timeoutId);
+            currentState = ConnectionState.ERROR;
+            bot.removeAllListeners('spawn');
+            reject(new Error(`Bot connection ended before spawn`));
+          }
+        });
+      });
+
+      return { bot, state: currentState };
+    } catch (error) {
+      currentState = ConnectionState.ERROR;
+      // Clean up bot if creation failed
+      if (bot) {
+        try {
+          bot.quit();
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Quit a bot and wait for disconnection to complete
+   * @param {Object} bot - Mineflayer bot instance
+   * @param {Object} options - Options
+   * @param {number} [options.disconnectTimeout] - Max time to wait (default: 10000ms)
+   * @returns {Promise<{success: boolean, reason: string}>}
+   */
+  static async quitBot(bot, options = {}) {
+    const { disconnectTimeout = 10000 } = options;
+
+    return new Promise((resolve) => {
+      let resolved = false;
+
+      // Set up timeout FIRST
+      const timeoutId = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          // Force cleanup on timeout
+          this._forceCleanup(bot);
+          resolve({ success: false, reason: 'Disconnect timeout' });
+        }
+      }, disconnectTimeout);
+
+      // Set up event listeners BEFORE calling bot.quit()
+      // to avoid race condition where 'end' fires before listeners are attached
+
+      // Handle successful disconnection
+      bot.once('end', () => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeoutId);
+          // Force cleanup to ensure all timers and listeners are cleared
+          this._forceCleanup(bot);
+          resolve({ success: true, reason: 'Clean disconnect' });
+        }
+      });
+
+      // Handle disconnection error
+      bot.once('error', (err) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeoutId);
+          // Force cleanup on error
+          this._forceCleanup(bot);
+          resolve({ success: false, reason: `Disconnect error: ${err.message}` });
+        }
+      });
+
+      // Initiate quit AFTER event listeners are set up
+      // Use bot.quit() for graceful disconnect instead of socket.destroy()
+      // This gives the server time to properly clean up player state
+      try {
+        bot.quit();
+      } catch (error) {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeoutId);
+          // Force cleanup on quit failure
+          this._forceCleanup(bot);
+          resolve({ success: false, reason: `Quit failed: ${error.message}` });
+        }
+      }
+    });
+  }
+
+  /**
+   * Force cleanup of bot resources
+   * Clears all event listeners, timers, and destroys the socket
+   * @private
+   * @param {Object} bot - Mineflayer bot instance
+   */
+  static _forceCleanup(bot) {
+    if (!bot) return;
+
+    // Remove all event listeners to prevent further callbacks
+    try {
+      bot.removeAllListeners();
+    } catch (e) {
+      // Ignore errors
+    }
+
+    // Clean up the underlying client connection
+    if (bot._client) {
+      try {
+        // Remove all listeners from the client
+        bot._client.removeAllListeners();
+        // End the connection
+        bot._client.end();
+        // Destroy the socket forcefully
+        if (bot._client.socket) {
+          bot._client.socket.destroy();
+        }
+      } catch (e) {
+        // Ignore errors
+      }
+    }
+
+    // Clear any standard output streams that might have listeners
+    if (bot._serverCertificate) {
+      try {
+        bot._serverCertificate.removeAllListeners();
+      } catch (e) {
+        // Ignore
+      }
+    }
+  }
+
+  /**
+   * Wait for a specific event on a bot
+   * @param {Object} bot - Mineflayer bot instance
+   * @param {string} eventName - Event to wait for
+   * @param {Object} options - Options
+   * @param {number} [options.timeout] - Max time to wait (default: 5000ms)
+   * @returns {Promise<any>} Event data
+   */
+  static async waitForEvent(bot, eventName, options = {}) {
+    const { timeout = 5000 } = options;
+
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        bot.removeAllListeners(eventName);
+        reject(new Error(`Timeout waiting for event "${eventName}" after ${timeout}ms`));
+      }, timeout);
+
+      bot.once(eventName, (...args) => {
+        clearTimeout(timeoutId);
+        resolve(args.length === 1 ? args[0] : args);
+      });
+    });
+  }
+
+  /**
+   * Check if a bot is ready for operations
+   * @param {Object} bot - Mineflayer bot instance
+   * @returns {boolean} True if bot is spawned and ready
+   */
+  static isBotReady(bot) {
+    return bot && bot.entity && typeof bot.health === 'number';
+  }
+
+  /**
+   * Get bot state information
+   * @param {Object} bot - Mineflayer bot instance
+   * @returns {Object} Bot state info
+   */
+  static getBotInfo(bot) {
+    if (!bot) {
+      return { connected: false, spawned: false, username: null };
+    }
+
+    return {
+      connected: true,
+      spawned: !!bot.entity,
+      username: bot.username,
+      health: bot.health,
+      position: bot.entity ? bot.entity.position : null
+    };
+  }
+}
+
+module.exports = { BotLifecycleManager };

package/lib/BotPool.js

@@ -0,0 +1,202 @@
+/**
+ * BotPool - Manages a collection of Mineflayer bots with proper lifecycle
+ * Ensures cleanup and provides query methods
+ */
+
+const { ConnectionState } = require('./ConnectionState.js');
+const { BotLifecycleManager } = require('./BotLifecycleManager.js');
+
+class BotPool {
+  /**
+   * Create a BotPool
+   * @param {Object} options - Options
+   * @param {Function} [options.createBotFn] - Function to create bots
+   */
+  constructor(options = {}) {
+    this.bots = new Map(); // username -> { bot, state, createdAt }
+    this.createBotFn = options.createBotFn;
+  }
+
+  /**
+   * Add a bot to the pool
+   * @param {string} username - Bot username
+   * @param {Object} bot - Mineflayer bot instance
+   * @returns {void}
+   */
+  add(username, bot) {
+    if (this.bots.has(username)) {
+      throw new Error(`Bot "${username}" already exists in pool`);
+    }
+
+    this.bots.set(username, {
+      bot,
+      state: ConnectionState.SPAWNED,
+      createdAt: new Date()
+    });
+  }
+
+  /**
+   * Remove a bot from the pool (without disconnecting)
+   * @param {string} username - Bot username
+   * @returns {boolean} True if bot was removed
+   */
+  remove(username) {
+    return this.bots.delete(username);
+  }
+
+  /**
+   * Get a bot by username
+   * @param {string} username - Bot username
+   * @returns {Object|null} Bot instance or null
+   */
+  get(username) {
+    const entry = this.bots.get(username);
+    return entry ? entry.bot : null;
+  }
+
+  /**
+   * Get a bot entry with metadata
+   * @param {string} username - Bot username
+   * @returns {Object|null} Bot entry or null
+   */
+  getEntry(username) {
+    return this.bots.get(username) || null;
+  }
+
+  /**
+   * Check if a bot exists in the pool
+   * @param {string} username - Bot username
+   * @returns {boolean}
+   */
+  has(username) {
+    return this.bots.has(username);
+  }
+
+  /**
+   * Get all bot usernames
+   * @returns {Array<string>}
+   */
+  getUsernames() {
+    return Array.from(this.bots.keys());
+  }
+
+  /**
+   * Get all bots
+   * @returns {Array<Object>} Array of bot instances
+   */
+  getAll() {
+    return Array.from(this.bots.values()).map(entry => entry.bot);
+  }
+
+  /**
+   * Get pool size
+   * @returns {number}
+   */
+  size() {
+    return this.bots.size;
+  }
+
+  /**
+   * Check if pool is empty
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.bots.size === 0;
+  }
+
+  /**
+   * Quit and remove a bot from the pool
+   * @param {string} username - Bot username
+   * @param {Object} options - Options
+   * @returns {Promise<{success: boolean, reason: string}>}
+   */
+  async quitBot(username, options = {}) {
+    const entry = this.bots.get(username);
+    if (!entry) {
+      return { success: false, reason: `Bot "${username}" not found in pool` };
+    }
+
+    const result = await BotLifecycleManager.quitBot(entry.bot, options);
+    this.bots.delete(username);
+    return result;
+  }
+
+  /**
+   * Quit all bots in the pool
+   * @param {Object} options - Options
+   * @returns {Promise<Array<{username: string, result: Object}>>}
+   */
+  async quitAll(options = {}) {
+    const results = [];
+    const usernames = this.getUsernames();
+
+    for (const username of usernames) {
+      const result = await this.quitBot(username, options);
+      results.push({ username, result });
+    }
+
+    return results;
+  }
+
+  /**
+   * Get health status of the pool
+   * @returns {Object} Pool health info
+   */
+  getHealth() {
+    const bots = [];
+    let healthyCount = 0;
+
+    for (const [username, entry] of this.bots.entries()) {
+      const isReady = BotLifecycleManager.isBotReady(entry.bot);
+      if (isReady) healthyCount++;
+
+      bots.push({
+        username,
+        state: entry.state,
+        ready: isReady,
+        createdAt: entry.createdAt
+      });
+    }
+
+    return {
+      total: this.bots.size,
+      healthy: healthyCount,
+      unhealthy: this.bots.size - healthyCount,
+      bots
+    };
+  }
+
+  /**
+   * Find bots by state
+   * @param {string} state - ConnectionState to filter by
+   * @returns {Array<Object>} Array of matching bots
+   */
+  findByState(state) {
+    return Array.from(this.bots.entries())
+      .filter(([_, entry]) => entry.state === state)
+      .map(([username, entry]) => ({ username, ...entry }));
+  }
+
+  /**
+   * Get bots that are ready for operations
+   * @returns {Array<Object>} Array of ready bots
+   */
+  getReadyBots() {
+    return Array.from(this.bots.entries())
+      .filter(([_, entry]) => BotLifecycleManager.isBotReady(entry.bot))
+      .map(([username, entry]) => ({ username, bot: entry.bot }));
+  }
+
+  /**
+   * Clear the pool (remove all references without disconnecting)
+   * Use quitAll() for proper cleanup
+   * @returns {number} Number of bots removed
+   */
+  clear() {
+    const size = this.bots.size;
+    this.bots.clear();
+    return size;
+  }
+}
+
+module.exports = { BotPool };

package/lib/ConnectionState.js

@@ -0,0 +1,50 @@
+/**
+ * ConnectionState - Represents the state of a bot or connection
+ * Uses freeze() to create immutable enum-like values
+ */
+
+class ConnectionState {
+  static get DISCONNECTED() { return 'DISCONNECTED'; }
+  static get CONNECTING() { return 'CONNECTING'; }
+  static get CONNECTED() { return 'CONNECTED'; }
+  static get SPAWNING() { return 'SPAWNING'; }
+  static get SPAWNED() { return 'SPAWNED'; }
+  static get ERROR() { return 'ERROR'; }
+  static get DISCONNECTING() { return 'DISCONNECTING'; }
+
+  /**
+   * Check if state is a terminal state (no further transitions possible)
+   * @param {string} state - State to check
+   * @returns {boolean}
+   */
+  static isTerminal(state) {
+    return [
+      ConnectionState.DISCONNECTED,
+      ConnectionState.ERROR
+    ].includes(state);
+  }
+
+  /**
+   * Check if state allows bot operations
+   * @param {string} state - State to check
+   * @returns {boolean}
+   */
+  static canPerformBotOperations(state) {
+    return state === ConnectionState.SPAWNED;
+  }
+
+  /**
+   * Check if state is a transitioning state
+   * @param {string} state - State to check
+   * @returns {boolean}
+   */
+  static isTransitioning(state) {
+    return [
+      ConnectionState.CONNECTING,
+      ConnectionState.SPAWNING,
+      ConnectionState.DISCONNECTING
+    ].includes(state);
+  }
+}
+
+module.exports = { ConnectionState };

package/lib/ServerHealthChecker.js

@@ -0,0 +1,174 @@
+/**
+ * ServerHealthChecker - Verifies Minecraft server is ready for bot connections
+ * Uses RCON for fast health checks instead of creating test bots
+ */
+
+const { Rcon } = require('rcon-client');
+
+class ServerHealthChecker {
+  /**
+   * Create a ServerHealthChecker instance
+   * @param {Object} config - Server configuration
+   * @param {string} [config.host] - Server host
+   * @param {number} [config.port] - Server port (for Minecraft, not RCON)
+   * @param {string} [config.auth] - Auth mode
+   * @param {string} [config.rconHost] - RCON host (defaults to host)
+   * @param {number} [config.rconPort] - RCON port (default: 25575)
+   * @param {string} [config.rconPassword] - RCON password (default: 'cavarest')
+   */
+  constructor(config = {}) {
+    this.host = config?.host || 'localhost';
+    this.port = config?.port || 25565;
+    this.auth = config?.auth || 'offline';
+    this.rconHost = config?.rconHost || this.host;
+    this.rconPort = config?.rconPort || 25575;
+    this.rconPassword = config?.rconPassword || 'cavarest';
+    this.ready = false;
+    this.lastCheckTime = null;
+    this.lastCheckResult = null;
+  }
+
+  /**
+   * Perform a single health check using RCON
+   * @returns {Promise<{success: boolean, reason: string, latency: number}>}
+   */
+  async check() {
+    const startTime = Date.now();
+
+    try {
+      const client = await Rcon.connect({
+        host: this.rconHost,
+        port: this.rconPort,
+        password: this.rconPassword
+      });
+
+      // Try to send a simple command to verify server is responsive
+      await client.send('list');
+      await client.end();
+
+      const latency = Date.now() - startTime;
+
+      this.lastCheckTime = new Date();
+      this.lastCheckResult = { success: true };
+      this.ready = true;
+
+      return {
+        success: true,
+        reason: 'Server is ready',
+        latency
+      };
+    } catch (error) {
+      const latency = Date.now() - startTime;
+
+      this.lastCheckTime = new Date();
+      this.lastCheckResult = { success: false, error: error.message };
+      this.ready = false;
+
+      return {
+        success: false,
+        reason: error.message,
+        latency
+      };
+    }
+  }
+
+  /**
+   * Wait for server to become ready, with polling
+   * @param {Object} options - Options
+   * @param {number} [options.timeout] - Total timeout (default: 120000ms)
+   * @param {number} [options.interval] - Polling interval (default: 3000ms)
+   * @param {boolean} [options.fastFail] - Fail immediately on first error (default: false)
+   * @returns {Promise<{success: boolean, checks: number, totalLatency: number}>}
+   */
+  async waitForReady(options = {}) {
+    const {
+      timeout = 120000,
+      interval = 3000,
+      fastFail = false
+    } = options;
+
+    const startTime = Date.now();
+    let checks = 0;
+    let totalLatency = 0;
+
+    while (Date.now() - startTime < timeout) {
+      checks++;
+
+      const result = await this.check();
+      totalLatency += result.latency;
+
+      if (result.success) {
+        this.ready = true;
+        return {
+          success: true,
+          checks,
+          totalLatency
+        };
+      }
+
+      // If fast fail is enabled, don't retry
+      if (fastFail) {
+        break;
+      }
+
+      // Wait before retrying
+      await new Promise(resolve => setTimeout(resolve, interval));
+    }
+
+    this.ready = false;
+    return {
+      success: false,
+      checks,
+      totalLatency
+    };
+  }
+
+  /**
+   * Check if server was marked ready on last check
+   * @returns {boolean}
+   */
+  isReady() {
+    return this.ready;
+  }
+
+  /**
+   * Get last check result
+   * @returns {{success: boolean|null, error: string|null, time: Date|null}}
+   */
+  getLastCheck() {
+    return {
+      success: this.lastCheckResult?.success ?? null,
+      error: this.lastCheckResult?.error ?? null,
+      time: this.lastCheckTime
+    };
+  }
+
+  /**
+   * Reset the ready state
+   */
+  reset() {
+    this.ready = false;
+    this.lastCheckTime = null;
+    this.lastCheckResult = null;
+  }
+
+  /**
+   * Create a health check report
+   * @returns {Object} Health check report
+   */
+  getReport() {
+    return {
+      ready: this.ready,
+      lastCheck: this.getLastCheck(),
+      config: {
+        host: this.host,
+        port: this.port,
+        auth: this.auth,
+        rconHost: this.rconHost,
+        rconPort: this.rconPort
+      }
+    };
+  }
+}
+
+module.exports = { ServerHealthChecker };

package/lib/backend.js

@@ -0,0 +1,78 @@
+/**
+ * Base PilafBackend class - abstract class defining the interface for all backend implementations
+ */
+
+class PilafBackend {
+  /**
+   * Connect to the backend (RCON server or Minecraft server)
+   * @abstract
+   * @param {Object} config - Connection configuration
+   * @returns {Promise<void>}
+   */
+  async connect(config) {
+    throw new Error('Method "connect()" must be implemented.');
+  }
+
+  /**
+   * Disconnect from the backend
+   * @abstract
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    throw new Error('Method "disconnect()" must be implemented.');
+  }
+
+  /**
+   * Send a command to the server
+   * @abstract
+   * @param {string} command - The command to send
+   * @returns {Promise<{raw: string, parsed?: any}>}
+   */
+  async sendCommand(command) {
+    throw new Error('Method "sendCommand()" must be implemented.');
+  }
+
+  /**
+   * Create a bot/player instance
+   * @abstract
+   * @param {Object} options - Bot options (including username)
+   * @returns {Promise<Object>} Bot instance
+   */
+  async createBot(options) {
+    throw new Error('Method "createBot()" must be implemented.');
+  }
+
+  /**
+   * Get all entities on the server
+   * @abstract
+   * @param {string} selector - Entity selector (optional)
+   * @returns {Promise<Array>} Array of entities
+   */
+  async getEntities(selector) {
+    throw new Error('Method "getEntities()" must be implemented.');
+  }
+
+  /**
+   * Get player inventory
+   * @abstract
+   * @param {string} username - Player username
+   * @returns {Promise<Object>} Player inventory
+   */
+  async getPlayerInventory(username) {
+    throw new Error('Method "getPlayerInventory()" must be implemented.');
+  }
+
+  /**
+   * Get block at specific coordinates
+   * @abstract
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {number} z - Z coordinate
+   * @returns {Promise<Object>} Block data
+   */
+  async getBlockAt(x, y, z) {
+    throw new Error('Method "getBlockAt()" must be implemented.');
+  }
+}
+
+module.exports = { PilafBackend };

package/lib/factory.js

@@ -0,0 +1,30 @@
+/**
+ * PilafBackendFactory - Factory for creating backend instances
+ */
+
+const { PilafBackend } = require('./backend.js');
+const { RconBackend } = require('./rcon-backend.js');
+const { MineflayerBackend } = require('./mineflayer-backend.js');
+
+class PilafBackendFactory {
+  /**
+   * Create a backend instance based on type
+   * @param {string} type - Backend type ('rcon' or 'mineflayer')
+   * @param {Object} config - Configuration object
+   * @returns {PilafBackend} Connected backend instance
+   */
+  static create(type, config = {}) {
+    switch (type.toLowerCase()) {
+      case 'rcon':
+        return new RconBackend().connect(config);
+
+      case 'mineflayer':
+        return new MineflayerBackend().connect(config);
+
+      default:
+        throw new Error(`Unknown backend type: ${type}. Supported types: 'rcon', 'mineflayer'`);
+    }
+  }
+}
+
+module.exports = { PilafBackendFactory };

package/lib/index.js

@@ -0,0 +1,23 @@
+/**
+ * Pilaf Backends Package - Main export
+ */
+
+const { PilafBackend } = require('./backend.js');
+const { RconBackend } = require('./rcon-backend.js');
+const { MineflayerBackend } = require('./mineflayer-backend.js');
+const { PilafBackendFactory } = require('./factory.js');
+const { ConnectionState } = require('./ConnectionState.js');
+const { BotLifecycleManager } = require('./BotLifecycleManager.js');
+const { ServerHealthChecker } = require('./ServerHealthChecker.js');
+const { BotPool } = require('./BotPool.js');
+
+module.exports = {
+  PilafBackend,
+  RconBackend,
+  MineflayerBackend,
+  PilafBackendFactory,
+  ConnectionState,
+  BotLifecycleManager,
+  ServerHealthChecker,
+  BotPool
+};

package/lib/mineflayer-backend.js

@@ -0,0 +1,291 @@
+/**
+ * MineflayerBackend - Mineflayer implementation for Pilaf backend
+ * Refactored with proper OOP architecture and separation of concerns
+ */
+
+const mineflayer = require('mineflayer');
+const { PilafBackend } = require('./backend.js');
+const { BotPool } = require('./BotPool.js');
+const { BotLifecycleManager } = require('./BotLifecycleManager.js');
+const { ServerHealthChecker } = require('./ServerHealthChecker.js');
+
+class MineflayerBackend extends PilafBackend {
+  /**
+   * Create a MineflayerBackend
+   * @param {Object} options - Options
+   */
+  constructor(options = {}) {
+    super();
+    this._host = null;
+    this._port = null;
+    this._auth = null;
+    this._connectConfig = {};
+    this._botPool = new BotPool();
+    this._healthChecker = null;
+  }
+
+  /**
+   * Get server host
+   * @returns {string}
+   */
+  get host() {
+    return this._host;
+  }
+
+  /**
+   * Get server port
+   * @returns {number}
+   */
+  get port() {
+    return this._port;
+  }
+
+  /**
+   * Get authentication mode
+   * @returns {string}
+   */
+  get auth() {
+    return this._auth;
+  }
+
+  /**
+   * Connect to server
+   * @param {Object} config - Configuration object
+   * @param {string} config.host - Server host
+   * @param {number} config.port - Server port
+   * @param {string} [config.auth] - Auth mode ('offline' or 'mojang')
+   * @param {string} [config.rconHost] - RCON host (for health checks, defaults to host)
+   * @param {number} [config.rconPort] - RCON port (for health checks, default: 25575)
+   * @param {string} [config.rconPassword] - RCON password (for health checks, default: 'cavarest')
+   * @returns {Promise<this>}
+   */
+  async connect(config) {
+    this._host = config?.host || 'localhost';
+    this._port = config?.port || 25565;
+    this._auth = config?.auth || 'offline';
+
+    // Store complete connection config
+    this._connectConfig = {
+      host: this._host,
+      port: this._port,
+      auth: this._auth,
+      ...config
+    };
+
+    // Initialize health checker with RCON config for fast checks
+    this._healthChecker = new ServerHealthChecker({
+      host: this._host,
+      port: this._port,
+      auth: this._auth,
+      rconHost: config?.rconHost || this._host,
+      rconPort: config?.rconPort || 25575,
+      rconPassword: config?.rconPassword || 'cavarest'
+    });
+
+    return this;
+  }
+
+  /**
+   * Disconnect all bots
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    const results = await this._botPool.quitAll({ disconnectTimeout: 10000 });
+    this._botPool.clear();
+  }
+
+  /**
+   * Send command via default bot
+   * @param {string} command - Command to send
+   * @returns {Promise<{raw: string, parsed?: any}>}
+   */
+  async sendCommand(command) {
+    const readyBots = this._botPool.getReadyBots();
+
+    if (readyBots.length === 0) {
+      throw new Error('No bot available. Create a bot first using createBot()');
+    }
+
+    const bot = readyBots[0].bot;
+
+    try {
+      bot.chat(command);
+      return { raw: '' };
+    } catch (error) {
+      throw new Error(`Failed to send command: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create a Mineflayer bot with proper lifecycle management
+   * @param {Object} options - Bot options
+   * @param {string} options.username - Bot username (required)
+   * @param {string} [options.host] - Server host (optional, uses connect config)
+   * @param {number} [options.port] - Server port (optional, uses connect config)
+   * @param {string} [options.auth] - Auth mode (optional, uses connect config)
+   * @param {number} [options.spawnTimeout] - Max time to wait for spawn (default: 30000ms)
+   * @param {Object} [options] - Additional mineflayer options
+   * @returns {Promise<Object>} Bot instance
+   */
+  async createBot(options) {
+    const username = options?.username;
+    if (!username) {
+      throw new Error('username is required in options');
+    }
+
+    if (this._botPool.has(username)) {
+      throw new Error(`Bot "${username}" already exists`);
+    }
+
+    // Merge connect config with bot options (bot options take precedence)
+    const botConfig = {
+      ...this._connectConfig,
+      ...options
+    };
+
+    // Create and spawn bot using lifecycle manager
+    const { bot } = await BotLifecycleManager.createAndSpawnBot(
+      () => mineflayer.createBot(botConfig),
+      botConfig
+    );
+
+    // Add to pool
+    this._botPool.add(username, bot);
+
+    return bot;
+  }
+
+  /**
+   * Quit a bot and remove from pool
+   * @param {Object} bot - Bot instance to quit
+   * @returns {Promise<{success: boolean, reason: string}>}
+   */
+  async quitBot(bot) {
+    // Find username by bot reference
+    for (const [username, entry] of this._botPool.bots.entries()) {
+      if (entry.bot === bot) {
+        return await this._botPool.quitBot(username);
+      }
+    }
+
+    return { success: false, reason: 'Bot not found in pool' };
+  }
+
+  /**
+   * Check if server is ready for bot connections
+   * @param {Object} options - Options
+   * @param {number} [options.timeout] - Total timeout (default: 120000ms)
+   * @returns {Promise<{success: boolean, checks: number, totalLatency: number}>}
+   */
+  async waitForServerReady(options = {}) {
+    if (!this._healthChecker) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+
+    return await this._healthChecker.waitForReady(options);
+  }
+
+  /**
+   * Get health checker instance
+   * @returns {ServerHealthChecker}
+   */
+  getHealthChecker() {
+    return this._healthChecker;
+  }
+
+  /**
+   * Get bot pool instance
+   * @returns {BotPool}
+   */
+  getBotPool() {
+    return this._botPool;
+  }
+
+  /**
+   * Get entities from all bots
+   * @param {string} selector - Entity selector (optional, unused in Mineflayer)
+   * @returns {Promise<Array>} Array of entities
+   */
+  async getEntities(selector) {
+    const allEntities = [];
+    const bots = this._botPool.getAll();
+
+    for (const bot of bots) {
+      if (bot.entities) {
+        Object.values(bot.entities).forEach(entity => {
+          // Use the built-in getCustomName() method from prismarine-entity
+          // This properly extracts custom name from entity.metadata[2]
+          let customName = null;
+          try {
+            if (typeof entity.getCustomName === 'function') {
+              const customNameObj = entity.getCustomName();
+              if (customNameObj) {
+                // ChatMessage object has a toString() method or text property
+                customName = customNameObj.toString ? customNameObj.toString() : (customNameObj.text || customNameObj);
+              }
+            }
+          } catch (e) {
+            // Ignore errors from getCustomName
+          }
+
+          allEntities.push({
+            id: entity.id,
+            name: entity.name || entity.username,
+            displayName: entity.displayName,
+            customName: customName,
+            type: entity.type,
+            position: entity.position,
+            health: entity.health
+          });
+        });
+      }
+    }
+
+    return allEntities;
+  }
+
+  /**
+   * Get player inventory
+   * @param {string} username - Player username
+   * @returns {Promise<Object>} Player inventory
+   */
+  async getPlayerInventory(username) {
+    const bot = this._botPool.get(username);
+
+    if (!bot) {
+      throw new Error(`Bot "${username}" not found`);
+    }
+
+    return {
+      slots: bot.inventory.slots,
+      items: bot.inventory.items()
+    };
+  }
+
+  /**
+   * Get block at coordinates
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {number} z - Z coordinate
+   * @returns {Promise<Object>} Block data
+   */
+  async getBlockAt(x, y, z) {
+    const readyBots = this._botPool.getReadyBots();
+
+    if (readyBots.length === 0) {
+      throw new Error('No bot available');
+    }
+
+    const bot = readyBots[0].bot;
+    const block = bot.blockAt({ x, y, z });
+
+    return {
+      type: block?.type,
+      name: block?.name,
+      position: block?.position,
+      metadata: block?.metadata
+    };
+  }
+}
+
+module.exports = { MineflayerBackend };

package/lib/rcon-backend.js

@@ -0,0 +1,210 @@
+/**
+ * RconBackend - RCON implementation for Pilaf backend
+ */
+
+const { Rcon } = require('rcon-client');
+const { PilafBackend } = require('./backend.js');
+
+class RconBackend extends PilafBackend {
+  constructor() {
+    super();
+    this.client = null;
+    this.connected = false;
+    this._connectTimeout = null;
+  }
+
+  /**
+   * Connect to RCON server
+   * @param {Object} config - Configuration object
+   * @param {string} config.host - RCON host
+   * @param {number} config.port - RCON port
+   * @param {string} config.password - RCON password
+   * @param {number} [config.timeout=30000] - Connection timeout in milliseconds
+   * @returns {Promise<void>}
+   */
+  async connect(config) {
+    const host = config?.host || 'localhost';
+    const port = config?.port || 25575;
+    const password = config?.password || '';
+    const timeout = config?.timeout || 30000; // 30 second default timeout
+
+    try {
+      // Add timeout to prevent hanging on slow/unresponsive RCON servers
+      // Store timeout ID so we can clear it on success
+      const timeoutPromise = new Promise((_, reject) => {
+        this._connectTimeout = setTimeout(() => {
+          this._connectTimeout = null;
+          reject(new Error(`RCON connection timeout after ${timeout}ms`));
+        }, timeout);
+      });
+
+      this.client = await Promise.race([
+        Rcon.connect({ host, port, password }),
+        timeoutPromise
+      ]);
+
+      // Clear timeout if connection succeeded
+      if (this._connectTimeout) {
+        clearTimeout(this._connectTimeout);
+        this._connectTimeout = null;
+      }
+
+      this.connected = true;
+      return this;
+    } catch (error) {
+      // Clean up timeout on error
+      if (this._connectTimeout) {
+        clearTimeout(this._connectTimeout);
+        this._connectTimeout = null;
+      }
+      throw new Error(`Failed to connect to RCON: ${error.message}`);
+    }
+  }
+
+  /**
+   * Disconnect from RCON server
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    // Clear connection timeout if still pending
+    if (this._connectTimeout) {
+      clearTimeout(this._connectTimeout);
+      this._connectTimeout = null;
+    }
+
+    if (this.client) {
+      // Store the client reference before clearing
+      const client = this.client;
+      this.client = null;
+      this.connected = false;
+
+      // Destroy the socket immediately without waiting for TCP FIN
+      // This prevents Jest from hanging on open handles
+      if (client.socket) {
+        try {
+          client.socket.destroy();
+        } catch (e) {
+          // Socket might already be destroyed
+        }
+      }
+
+      // Clear all event listeners from the internal emitter
+      if (client.emitter) {
+        try {
+          client.emitter.removeAllListeners();
+        } catch (e) {
+          // Emitter might already be cleaned up
+        }
+      }
+    }
+  }
+
+  /**
+   * Send command via RCON
+   * @param {string} command - Command to send
+   * @param {number} [timeout=10000] - Timeout in milliseconds
+   * @returns {Promise<{raw: string, parsed?: any}>}
+   */
+  async sendCommand(command, timeout = 10000) {
+    if (!this.connected || !this.client) {
+      throw new Error('Not connected to RCON server');
+    }
+
+    // Create a single timeout that we can cancel
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`RCON command timeout after ${timeout}ms`));
+      }, timeout);
+    });
+
+    try {
+      // Race the actual send against the timeout
+      const response = await Promise.race([
+        this.client.send(command),
+        timeoutPromise
+      ]);
+
+      // Clear timeout if command succeeded
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+
+      return this._parseResponse(response);
+    } catch (error) {
+      // Clear timeout on error
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      throw new Error(`Failed to send command: ${error.message}`);
+    }
+  }
+
+  /**
+   * Send command via RCON (alias for sendCommand)
+   * @param {string} command - Command to send
+   * @returns {Promise<{raw: string, parsed?: any}>}
+   */
+  async send(command) {
+    return this.sendCommand(command);
+  }
+
+  /**
+   * Parse RCON response
+   * @private
+   * @param {string} response - Raw response
+   * @returns {{raw: string, parsed?: any}}
+   */
+  _parseResponse(response) {
+    const result = { raw: response };
+
+    // Try to parse as JSON
+    try {
+      result.parsed = JSON.parse(response);
+    } catch {
+      // Not JSON, keep raw only
+    }
+
+    return result;
+  }
+
+  /**
+   * RCON doesn't support bot creation
+   */
+  async createBot() {
+    throw new Error('RCON backend does not support bot creation');
+  }
+
+  /**
+   * RCON doesn't support entity listing
+   */
+  async getEntities() {
+    throw new Error('RCON backend does not support entity listing');
+  }
+
+  /**
+   * Get player inventory via RCON command
+   * @param {string} username - Player username
+   * @returns {Promise<Object>}
+   */
+  async getPlayerInventory(username) {
+    const response = await this.sendCommand(`data get entity ${username} Inventory`);
+    return response.parsed || response;
+  }
+
+  /**
+   * Get block at coordinates via RCON command
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {number} z - Z coordinate
+   * @returns {Promise<Object>}
+   */
+  async getBlockAt(x, y, z) {
+    const response = await this.sendCommand(`data get block ${x} ${y} ${z}`);
+    return response.parsed || response;
+  }
+}
+
+module.exports = { RconBackend };

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pilaf/backends",
+  "version": "1.0.0",
+  "main": "lib/index.js",
+  "files": [
+    "lib/*.js",
+    "lib/**/*.js",
+    "!lib/**/*.spec.js",
+    "!lib/**/*.test.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mineflayer": "^4.20.1",
+    "rcon-client": "^4.2.5"
+  }
+}