@pilaf/backends 1.0.2 → 1.2.0

package/lib/parsers/PatternRegistry.js

@@ -0,0 +1,366 @@
+/**
+ * PatternRegistry - Centralized pattern management for log parsing
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Store, compile, and match regex patterns
+ * - NOT: Parse log lines (LogParser's responsibility - uses this registry)
+ * - NOT: Emit events (LogMonitor's responsibility)
+ *
+ * Design Principles:
+ * - Lazy compilation: Regex compiled on first use (performance)
+ * - Priority ordering: Patterns tested in order of addition
+ * - Named capture groups: Support for extracting named data
+ * - Thread-safe: Safe for concurrent access
+ *
+ * Usage:
+ *   const registry = new PatternRegistry();
+ *   registry.addPattern('teleport', /Teleported (\w+) to (.+)/, (match) => ({
+ *     player: match[1],
+ *     destination: match[2]
+ *   }));
+ *   const result = registry.match(logLine);
+ */
+
+class PatternRegistry {
+  /**
+   * Create a PatternRegistry
+   * @param {Object} options - Registry options
+   * @param {boolean} [options.caseInsensitive=false] - Make all patterns case-insensitive
+   */
+  constructor(options = {}) {
+    /**
+     * Map of pattern name to pattern definition
+     * @private
+     * @type {Map<string, Object>}
+     */
+    this._patterns = new Map();
+
+    /**
+     * Ordered array of pattern names (for priority ordering)
+     * @private
+     * @type {Array<string>}
+     */
+    this._patternOrder = [];
+
+    /**
+     * Compiled regex cache
+     * @private
+     * @type {Map<string, RegExp>}
+     */
+    this._compiled = new Map();
+
+    /**
+     * Case-insensitive flag
+     * @private
+     * @type {boolean}
+     */
+    this._caseInsensitive = options?.caseInsensitive || false;
+  }
+
+  /**
+   * Add a pattern to the registry
+   *
+   * @param {string} name - Unique pattern name/identifier
+   * @param {RegExp|string} pattern - Regex pattern or string (will be converted to RegExp)
+   * @param {Function} handler - Handler function: (match: RegExpMatchArray) => Object
+   * @param {number} [priority] - Optional priority (lower = higher priority, default: append to end)
+   * @returns {void}
+   * @throws {Error} If pattern name already exists
+   * @throws {Error} If pattern is invalid
+   * @throws {Error} If handler is not a function
+   *
+   * @example
+   * // Add with regex
+   * registry.addPattern('teleport', /Teleported (\w+) to (.+)/, (match) => ({
+   *   player: match[1],
+   *   position: match[2]
+   * }));
+   *
+   * // Add with string (converted to regex)
+   * registry.addPattern('join', 'UUID of player .* is (.+)', (match) => ({
+   *   username: match[1]
+   * }));
+   */
+  addPattern(name, pattern, handler, priority) {
+    // Validate name
+    if (typeof name !== 'string' || name.trim() === '') {
+      throw new Error('Pattern name must be a non-empty string');
+    }
+
+    // Check for duplicate
+    if (this._patterns.has(name)) {
+      throw new Error(`Pattern "${name}" already exists`);
+    }
+
+    // Validate pattern
+    if (!(pattern instanceof RegExp) && typeof pattern !== 'string') {
+      throw new Error('Pattern must be a RegExp or string');
+    }
+
+    // Validate handler
+    if (typeof handler !== 'function') {
+      throw new Error('Handler must be a function');
+    }
+
+    // Convert string to RegExp if needed
+    let regexPattern = pattern;
+    if (typeof pattern === 'string') {
+      const flags = this._caseInsensitive ? 'i' : '';
+      regexPattern = new RegExp(pattern, flags);
+    }
+
+    // Store pattern definition
+    this._patterns.set(name, {
+      name,
+      pattern: regexPattern,
+      handler,
+      priority: priority ?? this._patternOrder.length
+    });
+
+    // Update order
+    if (priority !== undefined) {
+      this._patternOrder.push(name);
+      this._patternOrder.sort((a, b) => {
+        const pA = this._patterns.get(a).priority;
+        const pB = this._patterns.get(b).priority;
+        return pA - pB;
+      });
+    } else {
+      this._patternOrder.push(name);
+    }
+  }
+
+  /**
+   * Remove a pattern from the registry
+   *
+   * @param {string} name - Pattern name to remove
+   * @returns {boolean} - True if pattern was removed, false if not found
+   */
+  removePattern(name) {
+    if (!this._patterns.has(name)) {
+      return false;
+    }
+
+    this._patterns.delete(name);
+    this._compiled.delete(name);
+    this._patternOrder = this._patternOrder.filter(n => n !== name);
+
+    return true;
+  }
+
+  /**
+   * Get a pattern by name
+   *
+   * @param {string} name - Pattern name
+   * @returns {Object|null} - Pattern definition or null if not found
+   * @property {RegExp} pattern - The regex pattern
+   * @property {Function} handler - The handler function
+   */
+  getPattern(name) {
+    return this._patterns.get(name) || null;
+  }
+
+  /**
+   * Get all pattern names
+   *
+   * @returns {Array<string>} - Array of pattern names in priority order
+   */
+  getPatterns() {
+    return [...this._patternOrder];
+  }
+
+  /**
+   * Get the count of registered patterns
+   *
+   * @returns {number} - Number of patterns
+   */
+  get size() {
+    return this._patterns.size;
+  }
+
+  /**
+   * Clear all patterns
+   *
+   * @returns {void}
+   */
+  clear() {
+    this._patterns.clear();
+    this._compiled.clear();
+    this._patternOrder = [];
+  }
+
+  /**
+   * Match a line against all registered patterns
+   *
+   * Tests patterns in priority order and returns the first match.
+   * Returns null if no patterns match.
+   *
+   * @param {string} line - Log line to match
+   * @returns {Object|null} - Match result or null if no match
+   * @property {string} name - Name of the pattern that matched
+   * @property {*} data - Data returned by the pattern's handler
+   * @property {RegExpMatchArray} match - The regex match result
+   * @property {string} raw - Original input line
+   *
+   * @example
+   * const result = registry.match('[12:34:56] Teleported TestPlayer to 100.0, 64.0, 100.0');
+   * // Returns:
+   * // {
+   * //   name: 'teleport',
+   * //   data: { player: 'TestPlayer', position: '100.0, 64.0, 100.0' },
+   * //   match: RegExpMatchArray,
+   * //   raw: '[12:34:56] Teleported TestPlayer to 100.0, 64.0, 100.0'
+   * // }
+   */
+  match(line) {
+    if (typeof line !== 'string') {
+      return null;
+    }
+
+    // Test each pattern in priority order
+    for (const name of this._patternOrder) {
+      const patternDef = this._patterns.get(name);
+      const regex = this._getCompiledPattern(name, patternDef.pattern);
+
+      const match = line.match(regex);
+      if (match) {
+        try {
+          const data = patternDef.handler(match);
+          return {
+            name,
+            data,
+            match,
+            raw: line
+          };
+        } catch (error) {
+          // Handler failed - continue to next pattern
+          // (Or we could emit an error event)
+          continue;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Match a line against a specific pattern
+   *
+   * @param {string} line - Log line to match
+   * @param {string} patternName - Name of pattern to match against
+   * @returns {Object|null} - Match result or null if no match
+   */
+  matchPattern(line, patternName) {
+    const patternDef = this._patterns.get(patternName);
+    if (!patternDef) {
+      return null;
+    }
+
+    const regex = this._getCompiledPattern(patternName, patternDef.pattern);
+    const match = line.match(regex);
+
+    if (!match) {
+      return null;
+    }
+
+    try {
+      const data = patternDef.handler(match);
+      return {
+        name: patternName,
+        data,
+        match,
+        raw: line
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Test if a pattern matches (without executing handler)
+   *
+   * @param {string} line - Log line to test
+   * @param {string} patternName - Name of pattern to test
+   * @returns {boolean} - True if pattern matches
+   */
+  test(line, patternName) {
+    const patternDef = this._patterns.get(patternName);
+    if (!patternDef) {
+      return false;
+    }
+
+    const regex = this._getCompiledPattern(patternName, patternDef.pattern);
+    return regex.test(line);
+  }
+
+  /**
+   * Get compiled regex for a pattern (lazy compilation)
+   *
+   * @private
+   * @param {string} name - Pattern name
+   * @param {RegExp} pattern - The regex pattern
+   * @returns {RegExp} - Compiled regex (cached or newly compiled)
+   */
+  _getCompiledPattern(name, pattern) {
+    // Check cache first
+    if (this._compiled.has(name)) {
+      return this._compiled.get(name);
+    }
+
+    // For string patterns, we've already converted to RegExp in addPattern
+    // For RegExp patterns, use as-is
+    this._compiled.set(name, pattern);
+    return pattern;
+  }
+
+  /**
+   * Clone the registry (creates a new instance with same patterns)
+   *
+   * @returns {PatternRegistry} - New registry with copied patterns
+   */
+  clone() {
+    const cloned = new PatternRegistry({
+      caseInsensitive: this._caseInsensitive
+    });
+
+    // Copy all patterns
+    for (const [name, patternDef] of this._patterns) {
+      cloned.addPattern(
+        name,
+        patternDef.pattern,
+        patternDef.handler,
+        patternDef.priority
+      );
+    }
+
+    return cloned;
+  }
+
+  /**
+   * Export patterns as JSON (for serialization)
+   *
+   * Note: Handlers cannot be serialized (functions are lost)
+   *
+   * @returns {Object} - JSON-serializable representation
+   */
+  toJSON() {
+    const patterns = {};
+
+    for (const [name, patternDef] of this._patterns) {
+      patterns[name] = {
+        name,
+        pattern: patternDef.pattern.toString(),
+        priority: patternDef.priority
+        // Note: handler function is lost
+      };
+    }
+
+    return {
+      caseInsensitive: this._caseInsensitive,
+      patternCount: this._patterns.size,
+      patterns
+    };
+  }
+}
+
+module.exports = { PatternRegistry };

package/lib/parsers/fixtures/minecraft-logs.js

@@ -0,0 +1,188 @@
+/**
+ * Minecraft Log Fixtures
+ *
+ * Real log lines from Minecraft servers 1.19, 1.20, 1.21+
+ * Used for testing MinecraftLogParser
+ */
+
+module.exports = {
+  // ============================================================================
+  // STATUS EVENTS (Server Lifecycle)
+  // ============================================================================
+
+  status: {
+    starting: [
+      '[12:34:56] [Server thread/INFO]: Starting minecraft server version 1.20.1',
+      '[12:34:56] [Server thread/INFO]: Starting minecraft server on *:25565',
+      '[12:34:56] [Server thread/INFO]: Loading properties',
+      '[12:34:56] [Server thread/INFO]: Default game type: SURVIVAL',
+      '[12:34:56] [Server thread/INFO]: Generating keypair',
+      '[12:34:56] [Worker-Main-1/INFO]: Starting minecraft server version 1.19.4',
+      '[12:34:56] [Worker-Main-2/INFO]: Starting minecraft server version 1.21'
+    ],
+    preparing: [
+      '[12:34:56] [Server thread/INFO]: Preparing level "world"',
+      '[12:34:56] [Server thread/INFO]: Preparing start region for dimension minecraft:overworld',
+      '[12:34:56] [Server thread/INFO]: Preparing start region for level 0'
+    ],
+    done: [
+      '[12:34:56] [Server thread/INFO]: Done (3.452s)! For help, type "help"',
+      '[12:34:56] [Server thread/INFO]: Done (5.123s)! For help, type "help"',
+      '[12:34:56] [Worker-Main-3/INFO]: Time elapsed: 3422 ms'
+    ]
+  },
+
+  // ============================================================================
+  // ENTITY EVENTS (Player join/leave/death/spawn)
+  // ============================================================================
+
+  entity: {
+    join: [
+      '[12:34:56] [Server thread/INFO]: TestPlayer joined the game',
+      '[12:34:56] [Server thread/INFO]: Steve joined the game',
+      '[12:34:56] [Server thread/INFO]: Alex joined the game'
+    ],
+    leave: [
+      '[12:34:56] [Server thread/INFO]: TestPlayer lost connection: Disconnected',
+      '[12:34:56] [Server thread/INFO]: Steve lost connection: Timed out',
+      '[12:34:56] [Server thread/INFO]: Alex lost connection: Internal Exception: java.io.IOException'
+    ],
+    spawn: [
+      '[12:34:56] [Server thread/INFO]: UUID of player TestPlayer is abc123-def456-7890-abcd-ef1234567890',
+      '[12:34:56] [Server thread/INFO]: UUID of player Steve is 12345678-1234-5678-1234-5678123456789'
+    ],
+    death: {
+      slain: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer was slain by Zombie',
+        '[12:34:56] [Server thread/INFO]: Steve was slain by Skeleton',
+        '[12:34:56] [Server thread/INFO]: Alex was slain by Spider',
+        '[12:34:56] [Server thread/INFO]: TestPlayer was slain by Creeper',
+        '[12:34:56] [Server thread/INFO]: Player was slain by Husk',
+        '[12:34:56] [Server thread/INFO]: TestPlayer was slain by Phantom'
+      ],
+      fall: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer fell from a high place',
+        '[12:34:56] [Server thread/INFO]: Steve fell from a high place'
+      ],
+      fire: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer burned to death',
+        '[12:34:56] [Server thread/INFO]: Alex was burnt to a crisp whilst fighting Skeleton'
+      ],
+      lava: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer tried to swim in lava',
+        '[12:34:56] [Server thread/INFO]: Steve was killed by Magma Block',
+        '[12:34:56] [Server thread/INFO]: Alex was killed by Lava'
+      ],
+      drown: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer drowned',
+        '[12:34:56] [Server thread/INFO]: Steve drowned'
+      ],
+      sprint: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer splatted against a wall'
+      ],
+      generic: [
+        '[12:34:56] [Server thread/INFO]: TestPlayer died',
+        '[12:34:56] [Server thread/INFO]: Steve died'
+      ]
+    }
+  },
+
+  // ============================================================================
+  // MOVEMENT EVENTS (Teleport)
+  // ============================================================================
+
+  movement: {
+    teleport: [
+      '[12:34:56] [Server thread/INFO]: Teleported TestPlayer from 100.5, 64.0, 200.3 to 150.2, 70.0, -300.5',
+      '[12:34:56] [Server thread/INFO]: Teleported Steve from -50.0, 80.0, 100.0 to 50.0, 64.0, -50.0',
+      '[12:34:56] [Server thread/INFO]: Teleported Alex from 0.5, 100.0, 0.5 to 100.0, 64.0, 200.0',
+      '[12:34:56] [Server thread/INFO]: Teleported TestPlayer1 from 256.5, 64.0, -128.9 to -256.5, 70.0, 128.9',
+      '[12:34:56] [Server thread/INFO]: Teleported NPC from 10, 70, 20 to 100, 65, -100'
+    ]
+  },
+
+  // ============================================================================
+  // COMMAND EVENTS (Server commands)
+  // ============================================================================
+
+  command: {
+    issued: [
+      '[12:34:56] [Server thread/INFO]: TestPlayer issued server command: /gamemode creative',
+      '[12:34:56] [Server thread/INFO]: Steve issued server command: /time set 1000',
+      '[12:34:56] [Server thread/INFO]: Alex issued server command: /weather rain',
+      '[12:34:56] [Server thread/INFO]: TestPlayer issued server command: /tp Steve 100 64 100',
+      '[12:34:56] [Server thread/INFO]: OP issued server command: /stop',
+      '[12:34:56] [Server thread/INFO]: Server issued server command: /save-all'
+    ]
+  },
+
+  // ============================================================================
+  // WORLD EVENTS (Time/weather/save)
+  // ============================================================================
+
+  world: {
+    time: [
+      '[12:34:56] [Server thread/INFO]: Changing the time to 1000',
+      '[12:34:56] [Server thread/INFO]: Changing the time to 13000',
+      '[12:34:56] [Server thread/INFO]: Changing the time to 18000'
+    ],
+    weather: [
+      '[12:34:56] [Server thread/INFO]: Changing the weather to rain',
+      '[12:34:56] [Server thread/INFO]: Changing the weather to thunder',
+      '[12:34:56] [Server thread/INFO]: Changing the weather to clear'
+    ],
+    difficulty: [
+      '[12:34:56] [Server thread/INFO]: Changing the difficulty to hard',
+      '[12:34:56] [Server thread/INFO]: Changing the difficulty to easy',
+      '[12:34:56] [Server thread/INFO]: Changing the difficulty to normal'
+    ],
+    gamemode: [
+      '[12:34:56] [Server thread/INFO]: The game mode has been updated to Creative',
+      '[12:34:56] [Server thread/INFO]: Gamemode has been updated to Survival Mode',
+      '[12:34:56] [Server thread/INFO]: The game mode has been updated to Spectator'
+    ],
+    save: [
+      '[12:34:56] [Server thread/INFO]: Saving the game',
+      '[12:34:56] [Server thread/INFO]: Saving the game in level 0',
+      '[12:34:56] [Server thread/INFO]: Saved the game',
+      '[12:34:56] [Server thread/INFO]: Saving chunks for level \'world\'/minecraft:overworld'
+    ]
+  },
+
+  // ============================================================================
+  // MIXED EVENTS (for testing priority ordering)
+  // ============================================================================
+
+  mixed: [
+    // Teleport should match over other entity events (priority test)
+    '[12:34:56] [Server thread/INFO]: Teleported TestPlayer from 100.0, 64.0, 200.0 to 150.0, 70.0, -300.0',
+    // Death should match even if contains command-like text
+    '[12:34:56] [Server thread/INFO]: TestPlayer was slain by Zombie using /kill'
+  ],
+
+  // ============================================================================
+  // EDGE CASES AND VARIATIONS
+  // ============================================================================
+
+  edge: [
+    // Different thread names
+    '[12:34:56] [Worker-Main-1/INFO]: TestPlayer joined the game',
+    '[12:34:56] [Worker-Main-2/INFO]: Steve issued server command: /gamemode creative',
+    '[12:34:56] [Server-Add-Worker-1/INFO]: Saving the game',
+
+    // Unicode player names
+    '[12:34:56] [Server thread/INFO]: 张三 joined the game',
+    '[12:34:56] [Server thread/INFO]: игрок joined the game',
+
+    // Long coordinates (negative values)
+    '[12:34:56] [Server thread/INFO]: Teleported TestPlayer from -1024.5, 128.0, 2048.9 to 512.0, -60.0, -512.0',
+
+    // Multi-word death messages
+    '[12:34:56] [Server thread/INFO]: TestPlayer was shot by a Skeleton',
+    '[12:34:56] [Server thread/INFO]: TestPlayer was blown up by a Creeper',
+
+    // Unknown/unmatched patterns
+    '[12:34:56] [Server thread/INFO]: Some unknown log message that does not match any pattern',
+    '[12:34:56] [Server thread/WARN]: Can\'t keep up! Did the system time change, or is the server overloaded?'
+  ]
+};

package/lib/parsers/index.js

@@ -0,0 +1,13 @@
+/**
+ * Log Parsers
+ *
+ * Concrete implementations of LogParser for various log formats.
+ */
+
+const { PatternRegistry } = require('./PatternRegistry.js');
+const { MinecraftLogParser } = require('./MinecraftLogParser.js');
+
+module.exports = {
+  PatternRegistry,
+  MinecraftLogParser
+};

package/lib/rcon-backend.js

@@ -20,6 +20,7 @@ class RconBackend extends PilafBackend {
    * @param {number} config.port - RCON port
    * @param {string} config.password - RCON password
    * @param {number} [config.timeout=30000] - Connection timeout in milliseconds
+   * @param {number} [config.maxRetries=5] - Max connection retry attempts
    * @returns {Promise<void>}
    */
   async connect(config) {
@@ -27,38 +28,53 @@ class RconBackend extends PilafBackend {
     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(() => {
+    const maxRetries = config?.maxRetries || 5; // Retry up to 5 times
+
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      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;
-          reject(new Error(`RCON connection timeout after ${timeout}ms`));
-        }, timeout);
-      });
+        }
 
-      this.client = await Promise.race([
-        Rcon.connect({ host, port, password }),
-        timeoutPromise
-      ]);
+        this.connected = true;
+        return this;
+      } catch (error) {
+        // Clean up timeout on error
+        if (this._connectTimeout) {
+          clearTimeout(this._connectTimeout);
+          this._connectTimeout = null;
+        }
 
-      // Clear timeout if connection succeeded
-      if (this._connectTimeout) {
-        clearTimeout(this._connectTimeout);
-        this._connectTimeout = null;
-      }
+        lastError = error;
 
-      this.connected = true;
-      return this;
-    } catch (error) {
-      // Clean up timeout on error
-      if (this._connectTimeout) {
-        clearTimeout(this._connectTimeout);
-        this._connectTimeout = null;
+        // If not the last attempt, wait before retrying with exponential backoff
+        if (attempt < maxRetries) {
+          const waitTime = Math.min(1000 * Math.pow(2, attempt - 1), 5000); // Max 5 seconds
+          await new Promise(resolve => setTimeout(resolve, waitTime));
+        }
       }
-      throw new Error(`Failed to connect to RCON: ${error.message}`);
     }
+
+    // All retries exhausted
+    throw new Error(`Failed to connect to RCON after ${maxRetries} attempts: ${lastError.message}`);
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilaf/backends",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "main": "lib/index.js",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
     "access": "public"
   },
   "dependencies": {
+    "dockerode": "^4.0.0",
     "mineflayer": "^4.20.1",
     "rcon-client": "^4.2.5"
   }