@pilaf/backends 1.0.1 → 1.2.0

package/lib/core/LogCollector.js

@@ -0,0 +1,194 @@
+/**
+ * LogCollector - Abstract base class for log collection
+ *
+ * Defines the interface for collecting raw log data from various sources
+ * (Docker containers, log files, syslog, etc.). Concrete implementations
+ * must extend this class and implement the abstract methods.
+ *
+ * @abstract
+ * @class
+ * @extends EventEmitter
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Connect to log source and receive raw log lines
+ * - NOT: Parse log content (LogParser's responsibility)
+ * - NOT: Correlate responses (CorrelationStrategy's responsibility)
+ *
+ * Usage Example:
+ *   // Extend LogCollector and implement abstract methods
+ *   function DockerLogCollector() {
+ *     LogCollector.call(this);
+ *   }
+ *   DockerLogCollector.prototype = Object.create(LogCollector.prototype);
+ *   DockerLogCollector.prototype.connect = async function(config) { ... };
+ *   DockerLogCollector.prototype.disconnect = async function() { ... };
+ */
+
+const EventEmitter = require('events');
+
+class LogCollector extends EventEmitter {
+  /**
+   * Create a LogCollector
+   * @throws {Error} Direct instantiation of abstract class
+   */
+  constructor() {
+    super();
+
+    // Prevent direct instantiation of abstract class
+    if (this.constructor === LogCollector) {
+      throw new Error('LogCollector is abstract and cannot be instantiated directly');
+    }
+
+    /**
+     * Connection state
+     * @protected
+     * @type {boolean}
+     */
+    this._connected = false;
+
+    /**
+     * Pause state
+     * @protected
+     * @type {boolean}
+     */
+    this._paused = false;
+
+    /**
+     * Connection configuration
+     * @protected
+     * @type {Object|null}
+     */
+    this._config = null;
+  }
+
+  /**
+   * Get connection state
+   * @returns {boolean}
+   */
+  get connected() {
+    return this._connected;
+  }
+
+  /**
+   * Get pause state
+   * @returns {boolean}
+   */
+  get paused() {
+    return this._paused;
+  }
+
+  /**
+   * Get connection configuration
+   * @returns {Object|null}
+   */
+  get config() {
+    return this._config;
+  }
+
+  /**
+   * Connect to the log source
+   *
+   * Abstract method that must be implemented by concrete classes.
+   * Should establish connection to the log source and start emitting
+   * 'data' events with raw log lines.
+   *
+   * @abstract
+   * @param {Object} config - Connection configuration
+   * @param {string} [config.host] - Host address (for remote sources)
+   * @param {number} [config.port] - Port number (for remote sources)
+   * @param {string} [config.path] - File path (for file sources)
+   * @param {string} [config.containerName] - Container name (for Docker)
+   * @returns {Promise<void>}
+   * @throws {Error} If connection fails
+   */
+  async connect(config) {
+    throw new Error('Method "connect()" must be implemented by subclass');
+  }
+
+  /**
+   * Disconnect from the log source
+   *
+   * Abstract method that must be implemented by concrete classes.
+   * Should clean up resources and stop emitting events.
+   *
+   * @abstract
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    throw new Error('Method "disconnect()" must be implemented by subclass');
+  }
+
+  /**
+   * Pause log collection
+   *
+   * Stops emitting 'data' events without disconnecting.
+   * Collection can be resumed with resume().
+   *
+   * @returns {void}
+   */
+  pause() {
+    this._paused = true;
+    this.emit('paused');
+  }
+
+  /**
+   * Resume log collection
+   *
+   * Resumes emitting 'data' events after pause().
+   *
+   * @returns {void}
+   */
+  resume() {
+    this._paused = false;
+    this.emit('resumed');
+  }
+
+  /**
+   * Emit a log line (protected method for subclasses)
+   *
+   * Emits 'data' event with raw log line if connected and not paused.
+   * Subclasses should call this method when they receive log data.
+   *
+   * @protected
+   * @param {string} line - Raw log line
+   * @returns {boolean} - True if event was emitted, false if paused/disconnected
+   */
+  _emitData(line) {
+    if (!this._connected || this._paused) {
+      return false;
+    }
+
+    this.emit('data', line);
+    return true;
+  }
+
+  /**
+   * Emit an error (protected method for subclasses)
+   *
+   * Emits 'error' event. Subclasses should call this method when
+   * errors occur during collection.
+   *
+   * @protected
+   * @param {Error} error - The error to emit
+   * @returns {void}
+   */
+  _emitError(error) {
+    this.emit('error', error);
+  }
+
+  /**
+   * Emit end event (protected method for subclasses)
+   *
+   * Emits 'end' event when the log stream terminates.
+   * Subclasses should call this when the stream ends naturally.
+   *
+   * @protected
+   * @returns {void}
+   */
+  _emitEnd() {
+    this._connected = false;
+    this.emit('end');
+  }
+}
+
+module.exports = { LogCollector };

package/lib/core/LogParser.js

@@ -0,0 +1,125 @@
+/**
+ * LogParser - Abstract base class for log parsing
+ *
+ * Defines the interface for parsing raw log lines into structured events.
+ * Concrete implementations must extend this class and implement the
+ * abstract parse() method.
+ *
+ * @abstract
+ * @class
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Parse raw log lines into structured events
+ * - NOT: Collect logs (LogCollector's responsibility)
+ * - NOT: Emit events to consumers (LogMonitor's responsibility)
+ * - NOT: Correlate responses (CorrelationStrategy's responsibility)
+ *
+ * Usage:
+ *   class MinecraftLogParser extends LogParser {
+ *     parse(line) {
+ *       // Parse and return { type, data, raw } or null
+ *     }
+ *   }
+ */
+
+class LogParser {
+  /**
+   * Create a LogParser
+   * @throws {Error} Direct instantiation of abstract class
+   */
+  constructor() {
+    // Prevent direct instantiation of abstract class
+    if (this.constructor === LogParser) {
+      throw new Error('LogParser is abstract and cannot be instantiated directly');
+    }
+  }
+
+  /**
+   * Parse a log line into a structured event
+   *
+   * Abstract method that must be implemented by concrete classes.
+   * Should analyze the log line and extract structured data.
+   *
+   * @abstract
+   * @param {string} line - Raw log line to parse
+   * @returns {Object|null} - Parsed event or null if line doesn't match any pattern
+   * @property {string} type - Event type (e.g., 'teleport', 'death', 'command')
+   * @property {Object} data - Parsed event data (structure varies by type)
+   * @property {string} raw - Original raw log line
+   * @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'
+   * // }
+   */
+  parse(line) {
+    throw new Error('Method "parse()" must be implemented by subclass');
+  }
+
+  /**
+   * Add a parsing pattern (optional method for pattern-based parsers)
+   *
+   * Default implementation throws. Pattern-based parsers should override.
+   *
+   * @param {string} name - Pattern name/identifier
+   * @param {RegExp|string} pattern - Regex pattern or string pattern
+   * @param {Function} handler - Handler function: (match) => data
+   * @returns {void}
+   * @throws {Error} If not supported by parser implementation
+   */
+  addPattern(name, pattern, handler) {
+    throw new Error('Method "addPattern()" is not supported by this parser');
+  }
+
+  /**
+   * Remove a parsing pattern (optional method for pattern-based parsers)
+   *
+   * Default implementation throws. Pattern-based parsers should override.
+   *
+   * @param {string} name - Pattern name to remove
+   * @returns {boolean} - True if pattern was removed, false if not found
+   * @throws {Error} If not supported by parser implementation
+   */
+  removePattern(name) {
+    throw new Error('Method "removePattern()" is not supported by this parser');
+  }
+
+  /**
+   * Get all registered patterns (optional method for pattern-based parsers)
+   *
+   * Default implementation throws. Pattern-based parsers should override.
+   *
+   * @returns {Array<string>} - Array of pattern names
+   * @throws {Error} If not supported by parser implementation
+   */
+  getPatterns() {
+    throw new Error('Method "getPatterns()" is not supported by this parser');
+  }
+
+  /**
+   * Validate parse result format
+   *
+   * Protected method to ensure parse() returns correct format.
+   * Used by concrete implementations to validate their output.
+   *
+   * @protected
+   * @param {Object|null} result - Result from parse()
+   * @returns {boolean} - True if format is valid
+   */
+  _validateResult(result) {
+    if (result === null) {
+      return true; // null is valid (no match)
+    }
+
+    return (
+      typeof result === 'object' &&
+      typeof result.type === 'string' &&
+      typeof result.data === 'object' &&
+      typeof result.raw === 'string'
+    );
+  }
+}
+
+module.exports = { LogParser };

package/lib/core/index.js

@@ -0,0 +1,26 @@
+/**
+ * Core Abstractions Index
+ *
+ * This module exports all core abstraction classes for the Pilaf backend system.
+ * These abstractions define the interfaces that concrete implementations must follow.
+ *
+ * @module core/index
+ */
+
+const { LogCollector } = require('./LogCollector.js');
+const { LogParser } = require('./LogParser.js');
+const { CommandRouter } = require('./CommandRouter.js');
+const { CorrelationStrategy } = require('./CorrelationStrategy.js');
+
+module.exports = {
+  // Abstract base classes
+  LogCollector,
+  LogParser,
+  CommandRouter,
+  CorrelationStrategy,
+
+  // Factory functions (implemented by concrete modules)
+  collectors: null,  // Will be set by collectors/index.js
+  parsers: null,     // Will be set by parsers/index.js
+  strategies: null   // Will be set by strategies/index.js
+};

package/lib/errors/index.js

@@ -0,0 +1,363 @@
+/**
+ * Pilaf Error Hierarchy
+ *
+ * Defines all error types used throughout the Pilaf backend system.
+ * Follows a hierarchical structure with machine-readable codes and
+ * human-readable messages.
+ *
+ * Error Hierarchy:
+ * PilafError (base)
+ * ├── ConnectionError
+ * │   ├── RconConnectionError
+ * │   ├── DockerConnectionError
+ * │   └── FileAccessError
+ * ├── CommandExecutionError
+ * │   ├── CommandTimeoutError
+ * │   └── CommandRejectedError
+ * ├── ParseError
+ * │   ├── MalformedLogError
+ * │   └── UnknownPatternError
+ * ├── CorrelationError
+ * │   ├── ResponseTimeoutError
+ * │   └── AmbiguousMatchError
+ * └── ResourceError
+ *     ├── BufferOverflowError
+ *     └── HandleExhaustedError
+ */
+
+/**
+ * Base Pilaf Error
+ *
+ * All Pilaf errors extend from this class.
+ *
+ * @class
+ * @extends Error
+ * @property {string} code - Machine-readable error code
+ * @property {string} message - Human-readable error message
+ * @property {Object} details - Additional debugging context
+ * @property {Error} [cause] - Original error that caused this error
+ */
+class PilafError extends Error {
+  /**
+   * Create a PilafError
+   * @param {string} code - Machine-readable error code (e.g., 'CONNECTION_FAILED')
+   * @param {string} message - Human-readable error message
+   * @param {Object} [details={}] - Additional debugging context
+   * @param {Error} [cause] - Original error that caused this error
+   */
+  constructor(code, message, details = {}, cause = null) {
+    super(message);
+
+    /**
+     * Error name (class name)
+     * @type {string}
+     */
+    this.name = this.constructor.name;
+
+    /**
+     * Machine-readable error code
+     * @type {string}
+     */
+    this.code = code;
+
+    /**
+     * Human-readable message
+     * @type {string}
+     */
+    this.message = message;
+
+    /**
+     * Additional debugging context
+     * @type {Object}
+     */
+    this.details = details;
+
+    /**
+     * Original cause (if any)
+     * @type {Error|null}
+     */
+    this.cause = cause;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging/serialization
+   * @returns {Object} - JSON representation of error
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : null,
+      stack: this.stack
+    };
+  }
+
+  /**
+   * Pretty-print error for debugging
+   * @returns {string} - Formatted error string
+   */
+  toString() {
+    let output = `[${this.code}] ${this.message}`;
+
+    if (Object.keys(this.details).length > 0) {
+      output += `\nDetails: ${JSON.stringify(this.details, null, 2)}`;
+    }
+
+    if (this.cause) {
+      output += `\nCaused by: ${this.cause.message}`;
+    }
+
+    return output;
+  }
+}
+
+// ============================================================================
+// CONNECTION ERRORS
+// ============================================================================
+
+/**
+ * Base class for connection-related errors
+ */
+class ConnectionError extends PilafError {
+  constructor(message, details = {}, cause = null) {
+    super('CONNECTION_ERROR', message, details, cause);
+  }
+}
+
+/**
+ * RCON connection failure
+ */
+class RconConnectionError extends ConnectionError {
+  constructor(message, details = {}, cause = null) {
+    super(message, { ...details, component: 'RCON' }, cause);
+    this.code = 'RCON_CONNECTION_ERROR';
+  }
+}
+
+/**
+ * Docker API connection failure
+ */
+class DockerConnectionError extends ConnectionError {
+  constructor(message, details = {}, cause = null) {
+    super(message, { ...details, component: 'Docker' }, cause);
+    this.code = 'DOCKER_CONNECTION_ERROR';
+  }
+}
+
+/**
+ * File access failure
+ */
+class FileAccessError extends ConnectionError {
+  constructor(message, details = {}, cause = null) {
+    super(message, { ...details, component: 'FileSystem' }, cause);
+    this.code = 'FILE_ACCESS_ERROR';
+  }
+}
+
+// ============================================================================
+// COMMAND EXECUTION ERRORS
+// ============================================================================
+
+/**
+ * Base class for command execution errors
+ */
+class CommandExecutionError extends PilafError {
+  constructor(message, details = {}, cause = null) {
+    super('COMMAND_ERROR', message, details, cause);
+  }
+}
+
+/**
+ * Command execution timeout
+ */
+class CommandTimeoutError extends CommandExecutionError {
+  constructor(command, timeout, details = {}) {
+    super(
+      `Command timed out after ${timeout}ms`,
+      { ...details, command, timeout },
+      null
+    );
+    this.code = 'COMMAND_TIMEOUT';
+  }
+}
+
+/**
+ * Command rejected by server
+ */
+class CommandRejectedError extends CommandExecutionError {
+  constructor(command, reason, details = {}) {
+    super(
+      `Command rejected by server: ${reason}`,
+      { ...details, command, reason },
+      null
+    );
+    this.code = 'COMMAND_REJECTED';
+  }
+}
+
+// ============================================================================
+// PARSING ERRORS
+// ============================================================================
+
+/**
+ * Base class for parsing errors
+ */
+class ParseError extends PilafError {
+  constructor(message, details = {}, cause = null) {
+    super('PARSE_ERROR', message, details, cause);
+  }
+}
+
+/**
+ * Malformed log line
+ */
+class MalformedLogError extends ParseError {
+  constructor(line, reason, details = {}) {
+    super(
+      `Malformed log line: ${reason}`,
+      { ...details, line },
+      null
+    );
+    this.code = 'MALFORMED_LOG';
+  }
+}
+
+/**
+ * Unknown log pattern
+ */
+class UnknownPatternError extends ParseError {
+  constructor(line, details = {}) {
+    super(
+      'Log line does not match any known pattern',
+      { ...details, line },
+      null
+    );
+    this.code = 'UNKNOWN_PATTERN';
+  }
+}
+
+// ============================================================================
+// CORRELATION ERRORS
+// ============================================================================
+
+/**
+ * Base class for correlation errors
+ */
+class CorrelationError extends PilafError {
+  constructor(message, details = {}, cause = null) {
+    super('CORRELATION_ERROR', message, details, cause);
+  }
+}
+
+/**
+ * Response correlation timeout
+ */
+class ResponseTimeoutError extends CorrelationError {
+  constructor(command, timeout, details = {}) {
+    // Call parent with generic message, then override code
+    super(`No response received within ${timeout}ms`, { ...details, command, timeout }, null);
+    // Override the parent's code
+    this.code = 'CORRELATION_TIMEOUT';
+  }
+}
+
+/**
+ * Ambiguous match (multiple potential responses)
+ */
+class AmbiguousMatchError extends CorrelationError {
+  constructor(command, matches, details = {}) {
+    super(
+      `${matches.length} potential responses found for command`,
+      { ...details, command, matchCount: matches.length },
+      null
+    );
+    this.code = 'AMBIGUOUS_MATCH';
+  }
+}
+
+// ============================================================================
+// RESOURCE ERRORS
+// ============================================================================
+
+/**
+ * Base class for resource-related errors
+ */
+class ResourceError extends PilafError {
+  constructor(message, details = {}, cause = null) {
+    super('RESOURCE_ERROR', message, details, cause);
+  }
+}
+
+/**
+ * Buffer overflow
+ */
+class BufferOverflowError extends ResourceError {
+  constructor(size, limit, details = {}) {
+    super(
+      `Buffer size (${size}) exceeds limit (${limit})`,
+      { ...details, size, limit },
+      null
+    );
+    this.code = 'BUFFER_OVERFLOW';
+  }
+}
+
+/**
+ * Handle/file descriptor exhaustion
+ */
+class HandleExhaustedError extends ResourceError {
+  constructor(resourceType, details = {}) {
+    super(
+      `Unable to allocate ${resourceType} handle`,
+      { ...details, resourceType },
+      null
+    );
+    this.code = 'HANDLE_EXHAUSTED';
+  }
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+module.exports = {
+  // Base error
+  PilafError,
+
+  // Connection errors
+  ConnectionError,
+  RconConnectionError,
+  DockerConnectionError,
+  FileAccessError,
+
+  // Command errors
+  CommandExecutionError,
+  CommandTimeoutError,
+  CommandRejectedError,
+
+  // Parse errors
+  ParseError,
+  MalformedLogError,
+  UnknownPatternError,
+
+  // Correlation errors
+  CorrelationError,
+  ResponseTimeoutError,
+  AmbiguousMatchError,
+
+  // Resource errors
+  ResourceError,
+  BufferOverflowError,
+  HandleExhaustedError
+};