@pilaf/backends 1.0.2 → 1.2.1

package/lib/mineflayer-backend.js

@@ -8,6 +8,9 @@ const { PilafBackend } = require('./backend.js');
 const { BotPool } = require('./BotPool.js');
 const { BotLifecycleManager } = require('./BotLifecycleManager.js');
 const { ServerHealthChecker } = require('./ServerHealthChecker.js');
+const { RconBackend } = require('./rcon-backend.js');
+const { QueryHelper } = require('./helpers/QueryHelper.js');
+const { EventObserver } = require('./helpers/EventObserver.js');
 
 class MineflayerBackend extends PilafBackend {
   /**
@@ -22,6 +25,9 @@ class MineflayerBackend extends PilafBackend {
     this._connectConfig = {};
     this._botPool = new BotPool();
     this._healthChecker = null;
+    this._rconBackend = null;  // Optional RconBackend for QueryHelper
+    this._queryHelper = null;
+    this._eventObserver = null;
   }
 
   /**
@@ -82,16 +88,36 @@ class MineflayerBackend extends PilafBackend {
       rconPassword: config?.rconPassword || 'cavarest'
     });
 
+    // Create RconBackend if RCON config is provided (for QueryHelper)
+    if (config?.rconHost || config?.rconPort || config?.rconPassword) {
+      this._rconBackend = new RconBackend();
+      await this._rconBackend.connect({
+        host: config?.rconHost || this._host,
+        port: config?.rconPort || 25575,
+        password: config?.rconPassword || 'cavarest'
+      });
+      // Initialize query helper with the RCON backend
+      this._queryHelper = new QueryHelper(this._rconBackend);
+    } else {
+      this._queryHelper = null;
+    }
+
     return this;
   }
 
   /**
-   * Disconnect all bots
+   * Disconnect all bots and RCON
    * @returns {Promise<void>}
    */
   async disconnect() {
     const results = await this._botPool.quitAll({ disconnectTimeout: 10000 });
     this._botPool.clear();
+
+    // Disconnect RCON backend if it was created
+    if (this._rconBackend) {
+      await this._rconBackend.disconnect();
+      this._rconBackend = null;
+    }
   }
 
   /**
@@ -201,6 +227,245 @@ class MineflayerBackend extends PilafBackend {
     return this._botPool;
   }
 
+  /**
+   * Get query helper instance
+   * @returns {QueryHelper}
+   */
+  getQueryHelper() {
+    return this._queryHelper;
+  }
+
+  /**
+   * Get event observer instance
+   * @returns {EventObserver}
+   */
+  getEventObserver() {
+    return this._eventObserver;
+  }
+
+  // ==========================================================================
+  // QUERY HELPER METHODS
+  // ==========================================================================
+
+  /**
+   * Get player information via RCON
+   * @param {string} username - Player username
+   * @returns {Promise<Object>} Player information
+   */
+  async getPlayerInfo(username) {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getPlayerInfo(username);
+  }
+
+  /**
+   * List all online players
+   * @returns {Promise<Object>} List of players
+   */
+  async listPlayers() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.listPlayers();
+  }
+
+  /**
+   * Get current world time
+   * @returns {Promise<Object>} World time information
+   */
+  async getWorldTime() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getWorldTime();
+  }
+
+  /**
+   * Get current weather
+   * @returns {Promise<Object>} Weather information
+   */
+  async getWeather() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getWeather();
+  }
+
+  /**
+   * Get difficulty level
+   * @returns {Promise<Object>} Difficulty information
+   */
+  async getDifficulty() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getDifficulty();
+  }
+
+  /**
+   * Get game mode
+   * @param {string} [player='@s'] - Target player selector
+   * @returns {Promise<Object>} Game mode information
+   */
+  async getGameMode(player = '@s') {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getGameMode(player);
+  }
+
+  /**
+   * Get server TPS
+   * @returns {Promise<Object>} TPS information
+   */
+  async getTPS() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getTPS();
+  }
+
+  /**
+   * Get world seed
+   * @returns {Promise<Object>} Seed information
+   */
+  async getSeed() {
+    if (!this._queryHelper) {
+      throw new Error('Backend not connected. Call connect() first.');
+    }
+    return await this._queryHelper.getSeed();
+  }
+
+  // ==========================================================================
+  // EVENT OBSERVATION METHODS
+  // ==========================================================================
+
+  /**
+   * Subscribe to server events
+   * @param {string} pattern - Event pattern (supports wildcards)
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onEvent(pattern, callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onEvent(pattern, callback);
+  }
+
+  /**
+   * Subscribe to player join events
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onPlayerJoin(callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onPlayerJoin(callback);
+  }
+
+  /**
+   * Subscribe to player leave events
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onPlayerLeave(callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onPlayerLeave(callback);
+  }
+
+  /**
+   * Subscribe to player death events
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onPlayerDeath(callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onPlayerDeath(callback);
+  }
+
+  /**
+   * Subscribe to command events
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onCommand(callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onCommand(callback);
+  }
+
+  /**
+   * Subscribe to world events
+   * @param {Function} callback - Event callback
+   * @returns {Function} Unsubscribe function
+   */
+  onWorldEvent(callback) {
+    this._ensureEventObserver();
+    return this._eventObserver.onWorldEvent(callback);
+  }
+
+  /**
+   * Start observing server events
+   * @returns {Promise<void>}
+   */
+  async observe() {
+    this._ensureEventObserver();
+    await this._eventObserver.start();
+  }
+
+  /**
+   * Stop observing server events
+   * @returns {void}
+   */
+  unobserve() {
+    if (this._eventObserver) {
+      this._eventObserver.stop();
+    }
+  }
+
+  /**
+   * Check if currently observing events
+   * @returns {boolean}
+   */
+  isObserving() {
+    return this._eventObserver && this._eventObserver.isObserving;
+  }
+
+  /**
+   * Ensure event observer is initialized
+   * @private
+   */
+  _ensureEventObserver() {
+    if (!this._eventObserver) {
+      // Lazy initialization - requires LogMonitor and parser
+      const { LogMonitor } = require('./monitoring/index.js');
+      const { MinecraftLogParser } = require('./parsers/index.js');
+      const { DockerLogCollector } = require('./collectors/index.js');
+      const { UsernameCorrelationStrategy } = require('./monitoring/correlations/index.js');
+
+      // Create log collector for this server
+      const collector = new DockerLogCollector({
+        container: this._host, // Use server host as container name
+        follow: true
+      });
+
+      // Create parser
+      const parser = new MinecraftLogParser();
+
+      // Create log monitor
+      const logMonitor = new LogMonitor({
+        collector,
+        parser,
+        correlation: new UsernameCorrelationStrategy(),
+        bufferSize: 1000
+      });
+
+      // Create event observer
+      this._eventObserver = new EventObserver({
+        logMonitor,
+        parser
+      });
+    }
+  }
+
   /**
    * Get entities from all bots
    * @param {string} selector - Entity selector (optional, unused in Mineflayer)

package/lib/monitoring/CircularBuffer.js

@@ -0,0 +1,202 @@
+/**
+ * CircularBuffer - Fixed-size circular buffer implementation
+ *
+ * A circular buffer is a fixed-size data structure that uses a single,
+ * contiguous block of memory. When the buffer is full, new data overwrites
+ * the oldest data.
+ *
+ * This provides O(1) time complexity for push and pop operations,
+ * making it ideal for streaming data and log monitoring scenarios.
+ *
+ * Usage Example:
+ *   const buffer = new CircularBuffer(3);
+ *   buffer.push(1);  // [1]
+ *   buffer.push(2);  // [1, 2]
+ *   buffer.push(3);  // [1, 2, 3]
+ *   buffer.push(4);  // [2, 3, 4] - 1 was overwritten
+ *   buffer.pop();    // Returns 2, buffer is [3, 4]
+ */
+
+/**
+ * CircularBuffer class for efficient fixed-size buffer operations
+ */
+class CircularBuffer {
+  /**
+   * Create a CircularBuffer
+   *
+   * @param {number} capacity - Maximum number of elements (must be > 0)
+   * @throws {Error} If capacity is not a positive integer
+   */
+  constructor(capacity) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`Capacity must be a positive integer, got: ${capacity}`);
+    }
+
+    /**
+     * Maximum capacity of the buffer
+     * @private
+     * @type {number}
+     */
+    this._capacity = capacity;
+
+    /**
+     * Internal array to store elements
+     * @private
+     * @type {Array}
+     */
+    this._buffer = new Array(capacity);
+
+    /**
+     * Index of the oldest element (front of queue)
+     * @private
+     * @type {number}
+     */
+    this._head = 0;
+
+    /**
+     * Index where the next element will be inserted (back of queue)
+     * @private
+     * @type {number}
+     */
+    this._tail = 0;
+
+    /**
+     * Current number of elements in the buffer
+     * @private
+     * @type {number}
+     */
+    this._size = 0;
+  }
+
+  /**
+   * Add a value to the buffer
+   *
+   * If the buffer is full, the oldest value is removed and returned.
+   *
+   * @param {*} value - Value to add
+   * @returns {*} - The displaced value if buffer was full, undefined otherwise
+   */
+  push(value) {
+    const displaced = this.isFull ? this._buffer[this._head] : undefined;
+
+    this._buffer[this._tail] = value;
+    this._tail = (this._tail + 1) % this._capacity;
+
+    if (this.isFull) {
+      this._head = (this._head + 1) % this._capacity;
+    } else {
+      this._size++;
+    }
+
+    return displaced;
+  }
+
+  /**
+   * Remove and return the oldest value
+   *
+   * @returns {*} - The oldest value, or undefined if buffer is empty
+   */
+  pop() {
+    if (this.isEmpty) {
+      return undefined;
+    }
+
+    const value = this._buffer[this._head];
+    this._buffer[this._head] = undefined; // Clear reference
+    this._head = (this._head + 1) % this._capacity;
+    this._size--;
+
+    return value;
+  }
+
+  /**
+   * Get value at logical index (0 = oldest, size-1 = newest)
+   *
+   * @param {number} index - Logical index
+   * @returns {*} - Value at index, or undefined if index is out of bounds
+   */
+  get(index) {
+    if (index < 0 || index >= this._size) {
+      return undefined;
+    }
+
+    const physicalIndex = (this._head + index) % this._capacity;
+    return this._buffer[physicalIndex];
+  }
+
+  /**
+   * Convert buffer to a regular array (ordered from oldest to newest)
+   *
+   * @returns {Array} - Array containing all elements
+   */
+  toArray() {
+    const result = [];
+    for (let i = 0; i < this._size; i++) {
+      result.push(this.get(i));
+    }
+    return result;
+  }
+
+  /**
+   * Extract a slice of the buffer
+   *
+   * @param {number} start - Start index (default: 0)
+   * @param {number} end - End index (default: size)
+   * @returns {Array} - Array containing elements from start to end-1
+   */
+  slice(start = 0, end = this._size) {
+    const result = [];
+    for (let i = start; i < Math.min(end, this._size); i++) {
+      result.push(this.get(i));
+    }
+    return result;
+  }
+
+  /**
+   * Clear all elements from the buffer
+   */
+  clear() {
+    this._buffer = new Array(this._capacity);
+    this._head = 0;
+    this._tail = 0;
+    this._size = 0;
+  }
+
+  /**
+   * Get the current number of elements
+   *
+   * @type {number}
+   */
+  get size() {
+    return this._size;
+  }
+
+  /**
+   * Get the maximum capacity
+   *
+   * @type {number}
+   */
+  get capacity() {
+    return this._capacity;
+  }
+
+  /**
+   * Check if buffer is empty
+   *
+   * @type {boolean}
+   */
+  get isEmpty() {
+    return this._size === 0;
+  }
+
+  /**
+   * Check if buffer is full
+   *
+   * @type {boolean}
+   */
+  get isFull() {
+    return this._size === this._capacity;
+  }
+}
+
+module.exports = { CircularBuffer };