@pilaf/backends 1.0.2 → 1.2.1

package/lib/collectors/DockerLogCollector.js

@@ -0,0 +1,334 @@
+/**
+ * DockerLogCollector - Collect logs from Docker containers
+ *
+ * Streams log output from Docker containers using the Dockerode API.
+ * Handles reconnection with exponential backoff and supports both
+ * following and historical log retrieval.
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Connect to Docker daemon and stream container logs
+ * - NOT: Parse log content (LogParser's responsibility)
+ * - NOT: Handle container lifecycle (user's responsibility)
+ *
+ * @class
+ * @extends LogCollector
+ *
+ * Usage:
+ *   const collector = new DockerLogCollector();
+ *   await collector.connect({
+ *     containerName: 'minecraft-server',
+ *     follow: true,
+ *     tail: 100
+ *   });
+ *   collector.on('data', (line) => console.log(line));
+ */
+
+const { LogCollector } = require('../core/LogCollector.js');
+const { DockerConnectionError } = require('../errors/index.js');
+
+class DockerLogCollector extends LogCollector {
+  /**
+   * Create a DockerLogCollector
+   * @param {Object} options - Collector options
+   * @param {Object} [options.dockerodeOptions] - Options to pass to Dockerode
+   * @param {string} [options.dockerodeOptions.socketPath] - Docker socket path (default: /var/run/docker.sock)
+   * @param {number} [options.reconnectDelay=1000] - Initial reconnection delay in ms
+   * @param {number} [options.maxReconnectDelay=30000] - Maximum reconnection delay in ms
+   * @param {number} [options.reconnectAttempts=5] - Maximum reconnection attempts
+   */
+  constructor(options = {}) {
+    super();
+
+    /**
+     * Dockerode options
+     * @private
+     * @type {Object}
+     */
+    this._dockerodeOptions = options?.dockerodeOptions || {};
+
+    /**
+     * Reconnection configuration
+     * @private
+     * @type {Object}
+     */
+    this._reconnectConfig = {
+      delay: options?.reconnectDelay || 1000,
+      maxDelay: options?.maxReconnectDelay || 30000,
+      attempts: options?.reconnectAttempts || 5
+    };
+
+    /**
+     * Dockerode instance (lazy loaded)
+     * @private
+     * @type {Object|null}
+     */
+    this._docker = null;
+
+    /**
+     * Docker container instance
+     * @private
+     * @type {Object|null}
+     */
+    this._container = null;
+
+    /**
+     * Log stream instance
+     * @private
+     * @type {Object|null}
+     */
+    this._logStream = null;
+
+    /**
+     * Reconnection timeout ID
+     * @private
+     * @type {NodeJS.Timeout|null}
+     */
+    this._reconnectTimeout = null;
+
+    /**
+     * Current reconnection attempt count
+     * @private
+     * @type {number}
+     */
+    this._reconnectCount = 0;
+
+    /**
+     * Stream options for Docker logs
+     * @private
+     * @type {Object}
+     */
+    this._streamOptions = {
+      follow: true,
+      stdout: true,
+      stderr: true,
+      tail: 0
+    };
+  }
+
+  /**
+   * Connect to Docker container and stream logs
+   *
+   * @param {Object} config - Connection configuration
+   * @param {string} config.containerName - Name or ID of the container
+   * @param {boolean} [config.follow=true] - Follow log stream
+   * @param {number} [config.tail=0] - Number of lines from history (0 = all)
+   * @param {boolean} [config.stdout=true] - Include stdout
+   * @param {boolean} [config.stderr=true] - Include stderr
+   * @param {boolean} [config.disableAutoReconnect=false] - Disable automatic reconnection
+   * @returns {Promise<void>}
+   * @throws {DockerConnectionError} If Docker connection fails
+   */
+  async connect(config) {
+    if (this._connected) {
+      await this.disconnect();
+    }
+
+    this._config = config;
+    this._streamOptions = {
+      follow: config?.follow !== false,
+      stdout: config?.stdout !== false,
+      stderr: config?.stderr !== false,
+      tail: config?.tail || 0
+    };
+
+    try {
+      // Lazy load Dockerode
+      if (!this._docker) {
+        const Docker = require('dockerode');
+        this._docker = new Docker(this._dockerodeOptions);
+      }
+
+      // Get container
+      const containerName = config?.containerName;
+      if (!containerName) {
+        throw new DockerConnectionError(
+          'Container name is required',
+          { config: this._streamOptions }
+        );
+      }
+
+      this._container = this._docker.getContainer(containerName);
+
+      // Verify container exists
+      try {
+        await this._container.inspect();
+      } catch (inspectError) {
+        throw new DockerConnectionError(
+          `Container not found: ${containerName}`,
+          { containerName },
+          inspectError
+        );
+      }
+
+      // Create log stream
+      this._logStream = await this._container.logs(this._streamOptions);
+
+      // Set up stream handlers
+      this._setupStreamHandlers(this._logStream);
+
+      this._connected = true;
+      // Only reset reconnect count on initial connection (not on reconnection)
+      if (!this._reconnectCount) {
+        this._reconnectCount = 0;
+      }
+
+      this.emit('connected');
+    } catch (error) {
+      // Re-throw to let caller handle the error
+      throw error;
+    }
+  }
+
+  /**
+   * Set up event handlers for the log stream
+   *
+   * @private
+   * @param {Object} stream - Docker log stream
+   * @returns {void}
+   */
+  _setupStreamHandlers(stream) {
+    // Docker logs are Buffers, need to decode and strip ANSI codes
+    stream.on('data', (chunk) => {
+      if (!this._connected) return;
+
+      // Decode buffer to string
+      const line = chunk.toString('utf8').trim();
+
+      // Skip empty lines
+      if (!line) return;
+
+      // Strip ANSI color codes if present
+      const cleanLine = this._stripAnsiCodes(line);
+
+      this._emitData(cleanLine);
+    });
+
+    stream.on('error', (error) => {
+      this._emitError(new DockerConnectionError(
+        'Log stream error',
+        { containerName: this._config?.containerName },
+        error
+      ));
+    });
+
+    stream.on('end', () => {
+      this._handleStreamEnd();
+    });
+
+    stream.on('close', () => {
+      this._handleStreamEnd();
+    });
+  }
+
+  /**
+   * Handle log stream termination
+   *
+   * @private
+   * @returns {void}
+   */
+  _handleStreamEnd() {
+    const shouldReconnect = this._config?.disableAutoReconnect !== true &&
+                           this._reconnectCount < this._reconnectConfig.attempts;
+
+    if (shouldReconnect && this._connected) {
+      this._scheduleReconnect();
+    } else {
+      this._emitEnd();
+    }
+  }
+
+  /**
+   * Schedule reconnection with exponential backoff
+   *
+   * @private
+   * @returns {void}
+   */
+  _scheduleReconnect() {
+    if (this._reconnectTimeout) {
+      clearTimeout(this._reconnectTimeout);
+    }
+
+    // Exponential backoff: delay * 2^attempt
+    const delay = Math.min(
+      this._reconnectConfig.delay * Math.pow(2, this._reconnectCount),
+      this._reconnectConfig.maxDelay
+    );
+
+    this._reconnectCount++;
+
+    this.emit('reconnecting', {
+      attempt: this._reconnectCount,
+      maxAttempts: this._reconnectConfig.attempts,
+      delay
+    });
+
+    this._reconnectTimeout = setTimeout(async () => {
+      try {
+        await this.connect(this._config);
+      } catch (error) {
+        this._emitError(error);
+      }
+    }, delay);
+  }
+
+  /**
+   * Strip ANSI escape codes from log line
+   *
+   * @private
+   * @param {string} line - Line that may contain ANSI codes
+   * @returns {string} - Clean line without ANSI codes
+   */
+  _stripAnsiCodes(line) {
+    // Remove ANSI escape sequences
+    // Format: ESC[...m where ESC is \x1b or \u001b
+    const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+    return line.replace(ansiRegex, '');
+  }
+
+  /**
+   * Disconnect from Docker container
+   *
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    // Cancel pending reconnection
+    if (this._reconnectTimeout) {
+      clearTimeout(this._reconnectTimeout);
+      this._reconnectTimeout = null;
+    }
+
+    // Destroy log stream
+    if (this._logStream) {
+      this._logStream.removeAllListeners();
+      if (typeof this._logStream.destroy === 'function') {
+        this._logStream.destroy();
+      }
+      this._logStream = null;
+    }
+
+    // Clear references
+    this._container = null;
+    this._docker = null;
+    this._connected = false;
+
+    this.emit('disconnected');
+  }
+
+  /**
+   * Get current reconnection status
+   *
+   * @returns {Object} - Reconnection status
+   * @property {number} attempt - Current attempt number
+   * @property {number} maxAttempts - Maximum attempts
+   * @property {boolean} reconnecting - Whether reconnection is pending
+   */
+  getReconnectStatus() {
+    return {
+      attempt: this._reconnectCount,
+      maxAttempts: this._reconnectConfig.attempts,
+      reconnecting: this._reconnectTimeout !== null
+    };
+  }
+}
+
+module.exports = { DockerLogCollector };

package/lib/collectors/index.js

@@ -0,0 +1,9 @@
+/**
+ * Log Collectors
+ *
+ * Concrete implementations of LogCollector for various log sources.
+ */
+
+module.exports = {
+  DockerLogCollector: require('./DockerLogCollector.js').DockerLogCollector
+};

package/lib/core/CommandRouter.js

@@ -0,0 +1,154 @@
+/**
+ * CommandRouter - Abstract base class for command routing
+ *
+ * Defines the interface for routing commands to the appropriate channel
+ * (bot chat, RCON, or log monitoring). Concrete implementations must
+ * extend this class and implement the abstract route() method.
+ *
+ * @abstract
+ * @class
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Decide which channel should handle a command
+ * - NOT: Execute commands (backend's responsibility)
+ * - NOT: Parse responses (parser's responsibility)
+ *
+ * Routing Logic:
+ * - /data get commands → RCON (structured NBT responses)
+ * - /execute with 'run data' → RCON (structured queries)
+ * - useRcon option → RCON (forced routing)
+ * - expectLogResponse option → Log monitoring (event correlation)
+ * - Default → Bot chat (player commands)
+ *
+ * Usage:
+ *   class SmartCommandRouter extends CommandRouter {
+ *     route(command, context) {
+ *       // Analyze command and return { channel, options }
+ *     }
+ *   }
+ */
+
+class CommandRouter {
+  /**
+   * Routing channels
+   * @static
+   * @enum {string}
+   */
+  static get CHANNELS() {
+    return {
+      BOT: 'bot',           // Send via bot.chat()
+      RCON: 'rcon',         // Send via RCON
+      LOG: 'log'            // Send via bot and wait for log response
+    };
+  }
+
+  /**
+   * Create a CommandRouter
+   * @param {Object} options - Router options
+   * @param {Object} [options.rules] - Custom routing rules
+   * @throws {Error} Direct instantiation of abstract class
+   */
+  constructor(options = {}) {
+    // Prevent direct instantiation of abstract class
+    if (this.constructor === CommandRouter) {
+      throw new Error('CommandRouter is abstract and cannot be instantiated directly');
+    }
+
+    /**
+     * Custom routing rules
+     * @protected
+     * @type {Array<{pattern: string|RegExp, channel: string}>}
+     */
+    this._customRules = options?.rules ? Object.entries(options.rules).map(([pattern, channel]) => ({ pattern, channel })) : [];
+  }
+
+  /**
+   * Route a command to the appropriate channel
+   *
+   * Abstract method that must be implemented by concrete classes.
+   * Should analyze the command and context to determine the best channel.
+   *
+   * @abstract
+   * @param {string} command - The command to route
+   * @param {Object} context - Routing context
+   * @param {Object} context.options - Command options (useRcon, expectLogResponse, etc.)
+   * @param {string} [context.username] - Bot username (for correlation)
+   * @param {Object} [context.backend] - Backend instance (for advanced routing)
+   * @returns {Object} Routing decision
+   * @property {string} channel - One of: 'bot', 'rcon', 'log'
+   * @property {Object} options - Options to pass to the channel
+   * @example
+   * // Returns:
+   * // { channel: 'rcon', options: { timeout: 10000 } }
+   */
+  route(command, context) {
+    throw new Error('Method "route()" must be implemented by subclass');
+  }
+
+  /**
+   * Add a custom routing rule
+   *
+   * @param {string|RegExp} pattern - Command pattern to match
+   * @param {string} channel - Channel to route to ('bot', 'rcon', 'log')
+   * @returns {void}
+   * @throws {Error} If channel is invalid
+   */
+  addRule(pattern, channel) {
+    const validChannels = Object.values(CommandRouter.CHANNELS);
+    if (!validChannels.includes(channel)) {
+      throw new Error(`Invalid channel: ${channel}. Must be one of: ${validChannels.join(', ')}`);
+    }
+
+    // Remove existing rule with same pattern (if any)
+    this.removeRule(pattern);
+
+    // Add new rule
+    this._customRules.push({ pattern, channel });
+  }
+
+  /**
+   * Remove a custom routing rule
+   *
+   * @param {string|RegExp} pattern - Pattern to remove
+   * @returns {boolean} - True if rule was removed, false if not found
+   */
+  removeRule(pattern) {
+    const initialLength = this._customRules.length;
+    this._customRules = this._customRules.filter(rule => {
+      // For RegExp, we need to compare by stringification
+      if (pattern instanceof RegExp && rule.pattern instanceof RegExp) {
+        return rule.pattern.toString() !== pattern.toString();
+      }
+      return rule.pattern !== pattern;
+    });
+    return this._customRules.length < initialLength;
+  }
+
+  /**
+   * Check if a command matches a pattern
+   *
+   * Protected helper method for concrete implementations.
+   *
+   * @protected
+   * @param {string} command - Command to check
+   * @param {string|RegExp} pattern - Pattern to match against
+   * @returns {boolean} - True if command matches pattern
+   */
+  _matchesPattern(command, pattern) {
+    if (pattern instanceof RegExp) {
+      return pattern.test(command);
+    }
+    return command.startsWith(pattern);
+  }
+
+  /**
+   * Get custom rules
+   *
+   * @returns {Array<{pattern: string|RegExp, channel: string}>} - Copy of custom rules array
+   */
+  getRules() {
+    return [...this._customRules];
+  }
+}
+
+module.exports = { CommandRouter };

package/lib/core/CorrelationStrategy.js

@@ -0,0 +1,172 @@
+/**
+ * CorrelationStrategy - Abstract base class for command response correlation
+ *
+ * Defines the interface for matching command responses in log streams.
+ * Concrete implementations must extend this class and implement the
+ * abstract correlate() method.
+ *
+ * @abstract
+ * @class
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Match log events to commands
+ * - NOT: Parse logs (LogParser's responsibility)
+ * - NOT: Execute commands (backend's responsibility)
+ * - NOT: Store events (LogMonitor's responsibility)
+ *
+ * Strategy Hierarchy (in order of reliability):
+ * 1. Tag-based - Most reliable (uses entity tags)
+ * 2. Username-based - Moderately reliable (uses username + timestamp)
+ * 3. Sequential - Fragile (assumes order preservation)
+ *
+ * Usage:
+ *   class TagCorrelationStrategy extends CorrelationStrategy {
+ *     async correlate(command, eventStream, timeout) {
+ *       // Inject tag and wait for matching response
+ *     }
+ *   }
+ */
+
+const { ResponseTimeoutError } = require('../errors/index.js');
+
+class CorrelationStrategy {
+  /**
+   * Create a CorrelationStrategy
+   * @param {Object} options - Strategy options
+   * @param {number} [options.timeout=5000] - Default timeout in milliseconds
+   * @param {number} [options.window=2000] - Time window for correlation (ms)
+   * @throws {Error} Direct instantiation of abstract class
+   */
+  constructor(options = {}) {
+    // Prevent direct instantiation of abstract class
+    if (this.constructor === CorrelationStrategy) {
+      throw new Error('CorrelationStrategy is abstract and cannot be instantiated directly');
+    }
+
+    /**
+     * Default timeout for correlation
+     * @protected
+     * @type {number}
+     */
+    this._defaultTimeout = options?.timeout || 5000;
+
+    /**
+     * Time window for correlation (ms)
+     * Used by time-based strategies
+     * @protected
+     * @type {number}
+     */
+    this._correlationWindow = options?.window || 2000;
+  }
+
+  /**
+   * Correlate a command with its response from the event stream
+   *
+   * Abstract method that must be implemented by concrete classes.
+   * Should wait for matching event and return the response, or throw
+   * CorrelationError if timeout occurs.
+   *
+   * @abstract
+   * @param {string} command - The command that was sent
+   * @param {AsyncIterable<Object>} eventStream - Stream of parsed events
+   * @param {number} [timeout] - Timeout in milliseconds (uses default if not provided)
+   * @returns {Promise<Object>} - The correlated response event
+   * @throws {ResponseTimeoutError} - If correlation fails or times out
+   * @example
+   * // Returns:
+   * // {
+   * //   type: 'teleport',
+   * //   data: { player: 'TestPlayer', position: { x: 100, y: 64, z: 100 } },
+   * //   raw: '[12:34:56] Teleported TestPlayer to 100.0, 64.0, 100.0'
+   * // }
+   */
+  async correlate(command, eventStream, timeout) {
+    throw new Error('Method "correlate()" must be implemented by subclass');
+  }
+
+  /**
+   * Generate a unique command ID for correlation
+   *
+   * Protected helper for concrete implementations.
+   * Generates a UUID-like string for tagging commands.
+   *
+   * @protected
+   * @returns {string} - Unique command ID
+   */
+  _generateCommandId() {
+    return `pilaf-cmd-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Inject correlation marker into a command
+   *
+   * Protected helper for tag-based strategies.
+   * Modifies the command to include a tag or marker.
+   *
+   * @protected
+   * @param {string} command - Original command
+   * @param {string} marker - Correlation marker
+   * @returns {string} - Modified command with marker
+   * @example
+   * _injectMarker('/tp @s ~ ~ ~', 'pilaf-cmd-123')
+   * // Returns: '/tp @s[tag=pilaf-cmd-123] ~ ~ ~'
+   */
+  _injectMarker(command, marker) {
+    // This is a default implementation - concrete classes may override
+    // For Minecraft commands, we can use entity tags
+    if (command.includes('@s')) {
+      return command.replace('@s', `@s[tag=${marker}]`);
+    }
+    if (command.includes('@p')) {
+      return command.replace('@p', `@p[tag=${marker}]`);
+    }
+    if (command.includes('@a')) {
+      return command.replace('@a', `@a[tag=${marker}]`);
+    }
+    if (command.includes('@e')) {
+      return command.replace('@e', `@e[tag=${marker}]`);
+    }
+    return command;
+  }
+
+  /**
+   * Wait for timeout to expire
+   *
+   * Protected helper for timeout handling.
+   *
+   * @protected
+   * @param {number} timeout - Timeout in milliseconds
+   * @returns {Promise<never>} - Rejects after timeout
+   */
+  async _waitForTimeout(timeout) {
+    return new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new ResponseTimeoutError('unknown', timeout));
+      }, timeout);
+    });
+  }
+
+  /**
+   * Check if an event matches correlation criteria
+   *
+   * Protected helper for concrete implementations.
+   * Provides a default implementation that checks for the
+   * correlation marker in the event data or raw text.
+   *
+   * @protected
+   * @param {Object} event - Parsed event to check
+   * @param {string} marker - Correlation marker to match
+   * @returns {boolean} - True if event matches
+   */
+  _matchesEvent(event, marker) {
+    if (!event || !event.data) {
+      return false;
+    }
+
+    // Check if marker exists anywhere in the event
+    const eventString = JSON.stringify(event);
+    return eventString.includes(marker);
+  }
+}
+
+module.exports = { CorrelationStrategy };