@pilaf/backends 1.0.2 → 1.2.0

package/lib/helpers/EventObserver.js

@@ -0,0 +1,267 @@
+/**
+ * EventObserver - Observe and subscribe to Minecraft server events
+ *
+ * Wraps LogMonitor and MinecraftLogParser to provide a clean API for
+ * subscribing to Minecraft server events without manually parsing logs.
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Provide clean API for event subscriptions
+ * - NOT: Collect logs (LogCollector's responsibility)
+ * - NOT: Parse logs (LogParser's responsibility)
+ * - NOT: Monitor logs (LogMonitor's responsibility)
+ *
+ * Usage Example:
+ *   const observer = new EventObserver(logMonitor, parser);
+ *   observer.onPlayerJoin((event) => {
+ *     console.log('Player joined:', event.data.player);
+ *   });
+ *   await observer.start();
+ */
+
+const { EventEmitter } = require('events');
+
+/**
+ * EventObserver class for event subscriptions
+ * @extends EventEmitter
+ */
+class EventObserver extends EventEmitter {
+  /**
+   * Create an EventObserver
+   *
+   * @param {Object} options - Observer options
+   * @param {Object} options.logMonitor - LogMonitor instance
+   * @param {Object} options.parser - LogParser instance
+   * @throws {Error} If required dependencies are not provided
+   */
+  constructor(options = {}) {
+    super();
+
+    if (!options.logMonitor) {
+      throw new Error('logMonitor is required');
+    }
+    if (!options.parser) {
+      throw new Error('parser is required');
+    }
+
+    /**
+     * LogMonitor instance for log collection
+     * @private
+     * @type {Object}
+     */
+    this._logMonitor = options.logMonitor;
+
+    /**
+     * LogParser instance for parsing logs
+     * @private
+     * @type {Object}
+     */
+    this._parser = options.parser;
+
+    /**
+     * Event subscriptions: pattern -> Set<callback>
+     * @private
+     * @type {Map<string, Set<Function>>}
+     */
+    this._subscriptions = new Map();
+
+    /**
+     * Whether observer is currently running
+     * @private
+     * @type {boolean}
+     */
+    this._isObserving = false;
+
+    // Set up event listener for log monitor
+    this._logMonitor.on('event', (event) => {
+      this._handleEvent(event);
+    });
+  }
+
+  /**
+   * Subscribe to events matching a pattern
+   *
+   * @param {string} pattern - Event pattern (supports wildcards: "entity.*")
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   *
+   * @example
+   * const unsubscribe = observer.onEvent('entity.*', (event) => {
+   *   console.log('Entity event:', event.type);
+   * });
+   */
+  onEvent(pattern, callback) {
+    if (!this._subscriptions.has(pattern)) {
+      this._subscriptions.set(pattern, new Set());
+    }
+    this._subscriptions.get(pattern).add(callback);
+
+    // Return unsubscribe function
+    return () => {
+      this._subscriptions.get(pattern)?.delete(callback);
+      if (this._subscriptions.get(pattern)?.size === 0) {
+        this._subscriptions.delete(pattern);
+      }
+    };
+  }
+
+  /**
+   * Subscribe to player join events
+   *
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   */
+  onPlayerJoin(callback) {
+    return this.onEvent('entity.join', callback);
+  }
+
+  /**
+   * Subscribe to player leave events
+   *
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   */
+  onPlayerLeave(callback) {
+    return this.onEvent('entity.leave', callback);
+  }
+
+  /**
+   * Subscribe to player death events
+   *
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   */
+  onPlayerDeath(callback) {
+    return this.onEvent('entity.death.*', callback);
+  }
+
+  /**
+   * Subscribe to command events
+   *
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   */
+  onCommand(callback) {
+    return this.onEvent('command.*', callback);
+  }
+
+  /**
+   * Subscribe to world events (time, weather, save)
+   *
+   * @param {Function} callback - Callback function(event)
+   * @returns {Function} - Unsubscribe function
+   */
+  onWorldEvent(callback) {
+    return this.onEvent('world.*', callback);
+  }
+
+  /**
+   * Start observing events
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} If already observing
+   */
+  async start() {
+    if (this._isObserving) {
+      throw new Error('EventObserver is already observing');
+    }
+
+    this._isObserving = true;
+    await this._logMonitor.start();
+    this.emit('start');
+  }
+
+  /**
+   * Stop observing events
+   *
+   * @returns {void}
+   */
+  stop() {
+    if (!this._isObserving) {
+      return;
+    }
+
+    this._isObserving = false;
+    this._logMonitor.stop();
+    this.emit('stop');
+  }
+
+  /**
+   * Check if observer is currently running
+   *
+   * @type {boolean}
+   */
+  get isObserving() {
+    return this._isObserving;
+  }
+
+  /**
+   * Get all active subscriptions
+   *
+   * @returns {Array<Object>} - Array of {pattern, callbackCount}
+   */
+  getSubscriptions() {
+    return Array.from(this._subscriptions.entries()).map(([pattern, callbacks]) => ({
+      pattern,
+      callbackCount: callbacks.size
+    }));
+  }
+
+  /**
+   * Clear all event subscriptions
+   *
+   * @returns {void}
+   */
+  clearSubscriptions() {
+    this._subscriptions.clear();
+  }
+
+  /**
+   * Handle incoming event from log monitor
+   *
+   * @private
+   * @param {Object} event - Parsed event
+   * @returns {void}
+   */
+  _handleEvent(event) {
+    // Find matching subscriptions and notify
+    for (const [pattern, callbacks] of this._subscriptions) {
+      if (this._matchesPattern(event.type, pattern)) {
+        callbacks.forEach(cb => {
+          try {
+            cb(event);
+          } catch (error) {
+            // Emit error event but don't crash
+            this.emit('error', { error, event });
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Check if event type matches pattern
+   *
+   * @private
+   * @param {string} eventType - Event type (e.g., "entity.join")
+   * @param {string} pattern - Pattern (e.g., "entity.*", "command.issued")
+   * @returns {boolean} - True if pattern matches
+   */
+  _matchesPattern(eventType, pattern) {
+    // Wildcard match
+    if (pattern === '*') {
+      return true;
+    }
+
+    // Glob-style pattern matching
+    if (pattern.includes('*')) {
+      const regexPattern = '^' + pattern.replace(/\*/g, '.*') + '$';
+      const regex = new RegExp(regexPattern);
+      return regex.test(eventType);
+    }
+
+    // Exact match
+    return eventType === pattern;
+  }
+}
+
+module.exports = { EventObserver };

package/lib/helpers/QueryHelper.js

@@ -0,0 +1,279 @@
+/**
+ * QueryHelper - Convenience methods for common Minecraft server queries
+ *
+ * Wraps RconBackend to provide structured data from common RCON commands.
+ * Parses raw RCON responses into useful JavaScript objects.
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Provide convenience methods for RCON queries
+ * - NOT: Connect to RCON (RconBackend's responsibility)
+ * - NOT: Handle errors (RconBackend's responsibility)
+ * - NOT: Cache results (caller's responsibility)
+ *
+ * Usage Example:
+ *   const helper = new QueryHelper(rconBackend);
+ *   const players = await helper.listPlayers();
+ *   // Returns: { online: 2, players: ['Steve', 'Alex'] }
+ */
+
+/**
+ * QueryHelper class for structured RCON queries
+ */
+class QueryHelper {
+  /**
+   * Create a QueryHelper
+   *
+   * @param {Object} rconBackend - RconBackend instance
+   * @throws {Error} If rconBackend is not provided
+   */
+  constructor(rconBackend) {
+    if (!rconBackend) {
+      throw new Error('RconBackend is required');
+    }
+
+    /**
+     * RconBackend instance
+     * @private
+     * @type {Object}
+     */
+    this._rcon = rconBackend;
+  }
+
+  /**
+   * Get information about a specific player
+   *
+   * @param {string} username - Player username
+   * @returns {Promise<Object>} - Player information
+   * @property {string} username - Player name
+   * @property {Object} position - Player position {x, y, z}
+   * @property {number} health - Player health
+   * @property {number} food - Player food level
+   * @property {number} exp - Player experience
+   * @property {number} level - Player level
+   */
+  async getPlayerInfo(username) {
+    const response = await this._rcon.sendCommand(`data get entity ${username}`);
+
+    // If RCON returned parsed NBT data, use it
+    if (response.parsed) {
+      return this._parsePlayerInfo(response.parsed, username);
+    }
+
+    // Otherwise parse from raw text or return minimal info
+    return {
+      username,
+      position: null,
+      health: null,
+      food: null,
+      exp: null,
+      level: null,
+      raw: response.raw
+    };
+  }
+
+  /**
+   * List all online players
+   *
+   * @returns {Promise<Object>} - List of online players
+   * @property {number} online - Number of online players
+   * @property {Array<string>} players - Array of player names
+   */
+  async listPlayers() {
+    const response = await this._rcon.sendCommand('/list');
+
+    // Parse response format: "There are 2 players online: Steve, Alex"
+    const onlineMatch = response.raw.match(/There are (\d+) players online:? (.*)/);
+    if (onlineMatch) {
+      const online = parseInt(onlineMatch[1], 10);
+      const playersStr = onlineMatch[2].trim();
+      const players = playersStr === '' ? [] : playersStr.split(', ').map(p => p.trim());
+      return { online, players };
+    }
+
+    // Alternative format: "Steve, Alex"
+    const playersMatch = response.raw.match(/^([a-zA-Z0-9_]+(?:, [a-zA-Z0-9_]+)*)$/);
+    if (playersMatch) {
+      const players = response.raw.split(', ').map(p => p.trim());
+      return { online: players.length, players };
+    }
+
+    // Fallback
+    return { online: 0, players: [], raw: response.raw };
+  }
+
+  /**
+   * Get current world time
+   *
+   * @returns {Promise<Object>} - World time information
+   * @property {number} time - Game time (0-24000)
+   * @property {boolean} daytime - Whether it's daytime
+   */
+  async getWorldTime() {
+    const response = await this._rcon.sendCommand('/time query daytime');
+
+    // Parse: "The time is 1500"
+    const timeMatch = response.raw.match(/The time is (\d+)/);
+    if (timeMatch) {
+      const time = parseInt(timeMatch[1], 10);
+      return {
+        time,
+        daytime: time >= 0 && time < 13000
+      };
+    }
+
+    // Parse: "Time: 1500" (alternative format)
+    const altMatch = response.raw.match(/Time: (\d+)/);
+    if (altMatch) {
+      const time = parseInt(altMatch[1], 10);
+      return {
+        time,
+        daytime: time >= 0 && time < 13000
+      };
+    }
+
+    return { time: null, daytime: null, raw: response.raw };
+  }
+
+  /**
+   * Get current weather state
+   *
+   * @returns {Promise<Object>} - Weather information
+   * @property {string} weather - Weather type (clear, rain, thunder)
+   * @property {number} duration - Remaining duration (if available)
+   */
+  async getWeather() {
+    const response = await this._rcon.sendCommand('/weather query');
+
+    // Parse: "The weather is clear"
+    const weatherMatch = response.raw.match(/The weather is (\w+)/);
+    if (weatherMatch) {
+      return { weather: weatherMatch[1].toLowerCase() };
+    }
+
+    // Parse: "Weather: clear" (alternative format)
+    const altMatch = response.raw.match(/Weather: (\w+)/);
+    if (altMatch) {
+      return { weather: altMatch[1].toLowerCase() };
+    }
+
+    return { weather: null, raw: response.raw };
+  }
+
+  /**
+   * Get difficulty level
+   *
+   * @returns {Promise<Object>} - Difficulty information
+   * @property {string} difficulty - Difficulty (peaceful, easy, normal, hard)
+   */
+  async getDifficulty() {
+    const response = await this._rcon.sendCommand('/difficulty');
+
+    // Parse: "The difficulty is set to: Normal"
+    const match = response.raw.match(/The difficulty is set to: (\w+)/);
+    if (match) {
+      return { difficulty: match[1].toLowerCase() };
+    }
+
+    // Parse: "Difficulty: Normal" (alternative format)
+    const altMatch = response.raw.match(/Difficulty: (\w+)/);
+    if (altMatch) {
+      return { difficulty: altMatch[1].toLowerCase() };
+    }
+
+    return { difficulty: null, raw: response.raw };
+  }
+
+  /**
+   * Get game mode
+   *
+   * @param {string} [player='@s'] - Target player selector
+   * @returns {Promise<Object>} - Game mode information
+   * @property {string} gameMode - Game mode (survival, creative, adventure, spectator)
+   */
+  async getGameMode(player = '@s') {
+    const response = await this._rcon.sendCommand(`/gamemode query ${player}`);
+
+    // Parse: "Game mode: Creative (Player: Steve)"
+    const match = response.raw.match(/Game mode: (\w+)/);
+    if (match) {
+      return { gameMode: match[1].toLowerCase() };
+    }
+
+    return { gameMode: null, raw: response.raw };
+  }
+
+  /**
+   * Get server TPS (ticks per second)
+   *
+   * @returns {Promise<Object>} - TPS information
+   * @property {number} tps - Current TPS
+   */
+  async getTPS() {
+    const response = await this._rcon.sendCommand('/tps');
+
+    // Parse: "TPS from last 1m, 1m, 5m, 15m: 20.0, 20.0, 20.0, 20.0"
+    const match = response.raw.match(/TPS from last [\w, ]+: ([\d., ]+)/);
+    if (match) {
+      const tpsValues = match[1].split(', ').map(s => parseFloat(s.trim()));
+      return {
+        tps: tpsValues[0] || null,
+        allTPS: tpsValues
+      };
+    }
+
+    // Parse: "Current TPS: 20.0"
+    const simpleMatch = response.raw.match(/Current TPS: ([\d.]+)/);
+    if (simpleMatch) {
+      return { tps: parseFloat(simpleMatch[1]) };
+    }
+
+    return { tps: null, raw: response.raw };
+  }
+
+  /**
+   * Get world seed
+   *
+   * @returns {Promise<Object>} - Seed information
+   * @property {string} seed - World seed
+   */
+  async getSeed() {
+    const response = await this._rcon.sendCommand('/seed');
+
+    // Parse: "Seed: [123456789]"
+    const match = response.raw.match(/Seed: \[([-\d]+)\]/);
+    if (match) {
+      return { seed: match[1] };
+    }
+
+    return { seed: null, raw: response.raw };
+  }
+
+  /**
+   * Parse player info from NBT data
+   *
+   * @private
+   * @param {Object} nbtData - NBT data from RCON
+   * @param {string} username - Player username
+   * @returns {Object} - Parsed player info
+   */
+  _parsePlayerInfo(nbtData, username) {
+    // NBT data structure varies by Minecraft version
+    // Common structure: { Pos: [I; x, y, z], Health, FoodLevel, XpLevel, ... }
+
+    return {
+      username,
+      position: nbtData.Pos ? {
+        x: nbtData.Pos[0],
+        y: nbtData.Pos[1],
+        z: nbtData.Pos[2]
+      } : null,
+      health: nbtData.Health || null,
+      food: nbtData.FoodLevel || null,
+      exp: nbtData.XpTotal || nbtData.XpLevel ? (nbtData.XpTotal || 0) : null,
+      level: nbtData.XpLevel || null,
+      raw: nbtData
+    };
+  }
+}
+
+module.exports = { QueryHelper };

package/lib/helpers/index.js

@@ -0,0 +1,13 @@
+/**
+ * Helper Classes for Pilaf Backends
+ *
+ * Utility classes that enhance backend functionality.
+ */
+
+const { QueryHelper } = require('./QueryHelper.js');
+const { EventObserver } = require('./EventObserver.js');
+
+module.exports = {
+  QueryHelper,
+  EventObserver
+};

package/lib/index.js

@@ -11,6 +11,42 @@ const { BotLifecycleManager } = require('./BotLifecycleManager.js');
 const { ServerHealthChecker } = require('./ServerHealthChecker.js');
 const { BotPool } = require('./BotPool.js');
 
+// Core abstractions
+const { LogCollector, LogParser, CommandRouter, CorrelationStrategy } = require('./core/index.js');
+
+// Collectors
+const { DockerLogCollector } = require('./collectors/index.js');
+
+// Parsers
+const { MinecraftLogParser } = require('./parsers/index.js');
+
+// Monitoring
+const { CircularBuffer, LogMonitor, TagCorrelationStrategy, UsernameCorrelationStrategy } = require('./monitoring/index.js');
+
+// Helpers
+const { QueryHelper, EventObserver } = require('./helpers/index.js');
+
+// Errors
+const {
+  PilafError,
+  ConnectionError,
+  RconConnectionError,
+  DockerConnectionError,
+  FileAccessError,
+  CommandExecutionError,
+  CommandTimeoutError,
+  CommandRejectedError,
+  ParseError,
+  MalformedLogError,
+  UnknownPatternError,
+  CorrelationError,
+  ResponseTimeoutError,
+  AmbiguousMatchError,
+  ResourceError,
+  BufferOverflowError,
+  HandleExhaustedError
+} = require('./errors/index.js');
+
 module.exports = {
   PilafBackend,
   RconBackend,
@@ -19,5 +55,40 @@ module.exports = {
   ConnectionState,
   BotLifecycleManager,
   ServerHealthChecker,
-  BotPool
+  BotPool,
+  // Core abstractions
+  LogCollector,
+  LogParser,
+  CommandRouter,
+  CorrelationStrategy,
+  // Collectors
+  DockerLogCollector,
+  // Parsers
+  MinecraftLogParser,
+  // Monitoring
+  CircularBuffer,
+  LogMonitor,
+  TagCorrelationStrategy,
+  UsernameCorrelationStrategy,
+  // Helpers
+  QueryHelper,
+  EventObserver,
+  // Errors
+  PilafError,
+  ConnectionError,
+  RconConnectionError,
+  DockerConnectionError,
+  FileAccessError,
+  CommandExecutionError,
+  CommandTimeoutError,
+  CommandRejectedError,
+  ParseError,
+  MalformedLogError,
+  UnknownPatternError,
+  CorrelationError,
+  ResponseTimeoutError,
+  AmbiguousMatchError,
+  ResourceError,
+  BufferOverflowError,
+  HandleExhaustedError
 };