@pilaf/backends 1.0.2 → 1.2.1

package/lib/monitoring/LogMonitor.js

@@ -0,0 +1,303 @@
+/**
+ * LogMonitor - Continuous log monitoring and event processing
+ *
+ * Aggregates LogCollector, LogParser, and CorrelationStrategy to provide
+ * continuous log monitoring with real-time event processing and correlation.
+ *
+ * The monitor polls the log collector at regular intervals, parses each line,
+ * maintains a circular buffer of recent events, and applies correlation strategies.
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Orchestrate log collection, parsing, and correlation
+ * - NOT: Collect logs (LogCollector's responsibility)
+ * - NOT: Parse logs (LogParser's responsibility)
+ * - NOT: Correlate events (CorrelationStrategy's responsibility)
+ *
+ * Usage Example:
+ *   const monitor = new LogMonitor({
+ *     collector: new DockerLogCollector({ container: 'mc-server' }),
+ *     parser: new MinecraftLogParser(),
+ *     correlation: new UsernameCorrelationStrategy(),
+ *     bufferSize: 1000,
+ *     pollInterval: 100
+ *   });
+ *
+ *   monitor.on('event', (event) => console.log('Event:', event.type));
+ *   monitor.on('correlation', (corr) => console.log('Correlation:', corr));
+ *   await monitor.start();
+ */
+
+const { EventEmitter } = require('events');
+const { CircularBuffer } = require('./CircularBuffer.js');
+
+/**
+ * LogMonitor class for continuous log monitoring
+ * @extends EventEmitter
+ */
+class LogMonitor extends EventEmitter {
+  /**
+   * Create a LogMonitor
+   *
+   * @param {Object} options - Monitor options
+   * @param {Object} options.collector - LogCollector instance
+   * @param {Object} options.parser - LogParser instance
+   * @param {Object} options.correlation - CorrelationStrategy instance
+   * @param {number} [options.bufferSize=1000] - Size of circular event buffer
+   * @param {number} [options.pollInterval=100] - Poll interval in milliseconds
+   * @throws {Error} If required dependencies are not provided
+   */
+  constructor(options = {}) {
+    super();
+
+    if (!options.collector) {
+      throw new Error('LogCollector is required');
+    }
+    if (!options.parser) {
+      throw new Error('LogParser is required');
+    }
+    if (!options.correlation) {
+      throw new Error('CorrelationStrategy is required');
+    }
+
+    /**
+     * Log collector for fetching log lines
+     * @private
+     * @type {Object}
+     */
+    this._collector = options.collector;
+
+    /**
+     * Log parser for converting lines to events
+     * @private
+     * @type {Object}
+     */
+    this._parser = options.parser;
+
+    /**
+     * Correlation strategy for linking related events
+     * @private
+     * @type {Object}
+     */
+    this._correlation = options.correlation;
+
+    /**
+     * Circular buffer for storing recent events
+     * @private
+     * @type {CircularBuffer}
+     */
+    this._buffer = new CircularBuffer(options.bufferSize || 1000);
+
+    /**
+     * Poll interval in milliseconds
+     * @private
+     * @type {number}
+     */
+    this._pollInterval = options.pollInterval || 100;
+
+    /**
+     * Whether the monitor is currently running
+     * @private
+     * @type {boolean}
+     */
+    this._isRunning = false;
+
+    /**
+     * Whether the monitor is currently paused
+     * @private
+     * @type {boolean}
+     */
+    this._isPaused = false;
+
+    /**
+     * Interval ID for the polling timer
+     * @private
+     * @type {NodeJS.Timeout|null}
+     */
+    this._intervalId = null;
+  }
+
+  /**
+   * Start monitoring logs
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} If monitor is already running
+   */
+  async start() {
+    if (this._isRunning) {
+      throw new Error('LogMonitor is already running');
+    }
+
+    this._isRunning = true;
+    this.emit('start');
+
+    this._intervalId = setInterval(async () => {
+      // Skip polling if paused
+      if (this._isPaused) {
+        return;
+      }
+
+      try {
+        await this._processLogs();
+      } catch (error) {
+        this.emit('error', error);
+      }
+    }, this._pollInterval);
+  }
+
+  /**
+   * Stop monitoring logs
+   *
+   * @returns {void}
+   */
+  stop() {
+    if (!this._isRunning) {
+      return;
+    }
+
+    this._isRunning = false;
+    this._isPaused = false;
+
+    if (this._intervalId) {
+      clearInterval(this._intervalId);
+      this._intervalId = null;
+    }
+
+    this.emit('stop');
+  }
+
+  /**
+   * Pause monitoring (without stopping)
+   *
+   * @returns {void}
+   */
+  pause() {
+    if (!this._isRunning) {
+      return;
+    }
+
+    this._isPaused = true;
+    this.emit('pause');
+  }
+
+  /**
+   * Resume monitoring after pause
+   *
+   * @returns {void}
+   */
+  resume() {
+    if (!this._isRunning || !this._isPaused) {
+      return;
+    }
+
+    this._isPaused = false;
+    this.emit('resume');
+  }
+
+  /**
+   * Get all events from the buffer
+   *
+   * @returns {Array} - Array of all events (oldest to newest)
+   */
+  getEvents() {
+    return this._buffer.toArray();
+  }
+
+  /**
+   * Get recent events from the buffer
+   *
+   * @param {number} count - Number of recent events to return
+   * @returns {Array} - Array of recent events
+   */
+  getRecentEvents(count = 10) {
+    const start = Math.max(0, this._buffer.size - count);
+    return this._buffer.slice(start);
+  }
+
+  /**
+   * Get all active correlations
+   *
+   * @returns {Array} - Array of active correlations
+   */
+  getCorrelations() {
+    return this._correlation.getActiveCorrelations();
+  }
+
+  /**
+   * Clear all events from the buffer
+   *
+   * @returns {void}
+   */
+  clear() {
+    this._buffer.clear();
+    this.emit('clear');
+  }
+
+  /**
+   * Check if the monitor is running
+   *
+   * @type {boolean}
+   */
+  get isRunning() {
+    return this._isRunning;
+  }
+
+  /**
+   * Check if the monitor is paused
+   *
+   * @type {boolean}
+   */
+  get isPaused() {
+    return this._isPaused;
+  }
+
+  /**
+   * Get the current buffer size
+   *
+   * @type {number}
+   */
+  get bufferSize() {
+    return this._buffer.size;
+  }
+
+  /**
+   * Get the buffer capacity
+   *
+   * @type {number}
+   */
+  get bufferCapacity() {
+    return this._buffer.capacity;
+  }
+
+  /**
+   * Process logs from collector
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _processLogs() {
+    const logs = await this._collector.collect();
+
+    for (const log of logs) {
+      const event = this._parser.parse(log);
+
+      // Skip null events or unknown patterns (when type is null)
+      if (!event || event.type === null) {
+        continue;
+      }
+
+      // Add event to buffer
+      this._buffer.push(event);
+
+      // Emit parsed event
+      this.emit('event', event);
+
+      // Apply correlation strategy
+      const correlation = this._correlation.correlate(event);
+      if (correlation) {
+        this.emit('correlation', correlation);
+      }
+    }
+  }
+}
+
+module.exports = { LogMonitor };

package/lib/monitoring/correlations/TagCorrelationStrategy.js

@@ -0,0 +1,214 @@
+/**
+ * TagCorrelationStrategy - Correlates events by unique tag/ID
+ *
+ * This correlation strategy groups events by a unique tag or identifier
+ * extracted from each event. Useful for tracking request/response cycles,
+ * command executions, or any scenario where events share a common identifier.
+ *
+ * Example use case:
+ * - RCON command returns request ID: "req-12345"
+ * - Subsequent log lines reference: "req-12345 completed"
+ * - Strategy groups all events with tag "req-12345"
+ *
+ * Features:
+ * - Configurable tag extraction function
+ * - Automatic correlation expiration (timeout)
+ * - Efficient Map-based storage
+ * - Thread-safe correlation tracking
+ *
+ * Usage Example:
+ *   const strategy = new TagCorrelationStrategy({
+ *     tagExtractor: (event) => event.data?.requestId,
+ *     timeout: 5000  // 5 seconds
+ *   });
+ *
+ *   const event = { type: 'command.start', data: { requestId: 'req-123' } };
+ *   const correlation = strategy.correlate(event);
+ *   // correlation: { tag: 'req-123', events: [event], timestamp: Date.now() }
+ */
+
+const { EventEmitter } = require('events');
+
+/**
+ * TagCorrelationStrategy class for tag-based event correlation
+ * @extends EventEmitter
+ */
+class TagCorrelationStrategy extends EventEmitter {
+  /**
+   * Create a TagCorrelationStrategy
+   *
+   * @param {Object} options - Strategy options
+   * @param {Function} [options.tagExtractor] - Function to extract tag from event
+   *                                            Default: (event) => event.data?.tag
+   * @param {number} [options.timeout=5000] - Auto-expire correlations after N ms
+   * @param {number} [options.cleanupInterval=60000] - Cleanup interval in ms
+   */
+  constructor(options = {}) {
+    super();
+
+    /**
+     * Function to extract tag from event
+     * @private
+     * @type {Function}
+     */
+    this._tagExtractor = options.tagExtractor || ((event) => event.data?.tag);
+
+    /**
+     * Correlation timeout in milliseconds
+     * @private
+     * @type {number}
+     */
+    this._timeout = options.timeout || 5000;
+
+    /**
+     * Cleanup interval for expired correlations
+     * @private
+     * @type {number}
+     */
+    this._cleanupInterval = options.cleanupInterval || 60000;
+
+    /**
+     * Map of active correlations
+     * @private
+     * @type {Map<string, Object>}
+     */
+    this._correlations = new Map();
+
+    /**
+     * Interval ID for cleanup timer
+     * @private
+     * @type {NodeJS.Timeout|null}
+     */
+    this._cleanupTimer = null;
+
+    // Start cleanup interval if timeout is set
+    if (this._timeout > 0) {
+      this._startCleanup();
+    }
+  }
+
+  /**
+   * Correlate an event by its tag
+   *
+   * @param {Object} event - Parsed event object
+   * @returns {Object|null} - Correlation object with tag, events, timestamp, or null if no tag
+   */
+  correlate(event) {
+    if (!event) {
+      return null;
+    }
+
+    const tag = this._tagExtractor(event);
+    if (!tag) {
+      return null;
+    }
+
+    const now = Date.now();
+
+    if (!this._correlations.has(tag)) {
+      this._correlations.set(tag, {
+        tag,
+        events: [],
+        timestamp: now
+      });
+    }
+
+    const correlation = this._correlations.get(tag);
+    correlation.events.push(event);
+    correlation.timestamp = now;
+
+    return correlation;
+  }
+
+  /**
+   * Get all active correlations
+   *
+   * @returns {Array<Object>} - Array of correlation objects
+   */
+  getActiveCorrelations() {
+    return Array.from(this._correlations.values());
+  }
+
+  /**
+   * Get correlation by tag
+   *
+   * @param {string} tag - Tag to look up
+   * @returns {Object|undefined} - Correlation object or undefined
+   */
+  getCorrelation(tag) {
+    return this._correlations.get(tag);
+  }
+
+  /**
+   * Reset all correlation state
+   *
+   * @returns {void}
+   */
+  reset() {
+    this._correlations.clear();
+    this.emit('reset');
+  }
+
+  /**
+   * Remove expired correlations
+   *
+   * @returns {number} - Number of correlations removed
+   */
+  cleanup() {
+    if (this._timeout <= 0) {
+      return 0;
+    }
+
+    const now = Date.now();
+    const expiredThreshold = now - this._timeout;
+    let removed = 0;
+
+    for (const [tag, correlation] of this._correlations.entries()) {
+      if (correlation.timestamp < expiredThreshold) {
+        this._correlations.delete(tag);
+        removed++;
+      }
+    }
+
+    if (removed > 0) {
+      this.emit('cleanup', removed);
+    }
+
+    return removed;
+  }
+
+  /**
+   * Stop the cleanup timer
+   *
+   * @returns {void}
+   */
+  destroy() {
+    if (this._cleanupTimer) {
+      clearInterval(this._cleanupTimer);
+      this._cleanupTimer = null;
+    }
+  }
+
+  /**
+   * Start the cleanup interval
+   *
+   * @private
+   * @returns {void}
+   */
+  _startCleanup() {
+    this._cleanupTimer = setInterval(() => {
+      this.cleanup();
+    }, this._cleanupInterval);
+  }
+
+  /**
+   * Get the number of active correlations
+   *
+   * @type {number}
+   */
+  get size() {
+    return this._correlations.size;
+  }
+}
+
+module.exports = { TagCorrelationStrategy };