@joystick.js/db-canary 0.0.0-canary.2275 → 0.0.0-canary.2277

package/src/server/lib/write_forwarder.js

@@ -1,636 +0,0 @@
-/**
- * @fileoverview Write operation forwarder for JoystickDB secondary nodes.
- * Enables secondary nodes to forward write operations to the primary node in a
- * master-secondary architecture. Provides authentication, timeout handling, retry logic,
- * and comprehensive monitoring for reliable write operation forwarding with statistics.
- */
-
-import net from 'net';
-import crypto from 'crypto';
-import { get_settings } from './load_settings.js';
-import { encode_message, create_message_parser } from './tcp_protocol.js';
-import create_logger from './logger.js';
-
-const { create_context_logger } = create_logger('write_forwarder');
-
-/**
- * Manages forwarding of write operations from secondary nodes to primary node.
- * Handles connection management, authentication, operation forwarding, timeout handling,
- * and provides comprehensive statistics for monitoring secondary node behavior.
- */
-class WriteForwarder {
-  /**
-   * Creates a new WriteForwarder instance with default configuration.
-   * Initializes connection tracking, operation forwarding, and statistics collection.
-   */
-  constructor() {
-    /** @type {Object|null} Connection to primary node */
-    this.primary_connection = null;
-    
-    /** @type {boolean} Whether this node is operating in secondary mode */
-    this.is_secondary_mode = false;
-    
-    /** @type {Object|null} Primary node configuration */
-    this.primary_config = null;
-    
-    /** @type {Map<string, Object>} Map of pending forward operations by ID */
-    this.pending_forwards = new Map();
-    
-    /** @type {number} Timeout for forward operations in milliseconds */
-    this.forward_timeout_ms = 10000;
-    
-    /** @type {number} Delay between reconnection attempts in milliseconds */
-    this.reconnect_delay_ms = 5000;
-    
-    /** @type {Object} Logger instance for write forwarding events */
-    this.log = create_context_logger();
-    
-    /** @type {Object} Write forwarding statistics and metrics */
-    this.stats = {
-      total_forwards: 0,
-      successful_forwards: 0,
-      failed_forwards: 0,
-      avg_forward_latency_ms: 0,
-      total_forward_time_ms: 0,
-      connection_attempts: 0,
-      last_connection_attempt: null
-    };
-  }
-
-  /**
-   * Initializes write forwarder with configuration from settings.
-   * Checks if node is configured as secondary, loads primary configuration,
-   * and establishes connection to primary node for write forwarding.
-   * @returns {void}
-   */
-  initialize() {
-    try {
-      const settings = get_settings();
-      
-      // Check if this node is configured as secondary
-      if (settings.mode !== 'secondary' || !settings.primary) {
-        this.log.info('Node not configured as secondary - write forwarding disabled');
-        return;
-      }
-      
-      this.is_secondary_mode = true;
-      this.primary_config = settings.primary;
-      this.forward_timeout_ms = settings.replication?.timeout_ms || 10000;
-      
-      this.log.info('Initializing write forwarder for secondary mode', {
-        primary_ip: this.primary_config.ip,
-        primary_port: this.primary_config.port,
-        timeout_ms: this.forward_timeout_ms
-      });
-      
-      // Connect to primary node
-      this.connect_to_primary();
-      
-    } catch (error) {
-      this.log.warn('Could not initialize write forwarder - settings not loaded', {
-        error: error.message
-      });
-    }
-  }
-
-  /**
-   * Establishes connection to the primary node with authentication and error handling.
-   * Sets up TCP connection, message parsing, event handlers, and automatic reconnection.
-   * Tracks connection attempts and handles authentication with the primary node.
-   * @returns {Promise<void>}
-   */
-  async connect_to_primary() {
-    if (!this.is_secondary_mode || !this.primary_config) {
-      return;
-    }
-    
-    const { ip, port, public_key } = this.primary_config;
-    
-    this.log.info('Connecting to primary node', { ip, port });
-    this.stats.connection_attempts++;
-    this.stats.last_connection_attempt = Date.now();
-    
-    try {
-      const socket = new net.Socket();
-      const message_parser = create_message_parser();
-      
-      socket.connect(port, ip, () => {
-        this.log.info('Connected to primary node', { ip, port });
-        
-        // Send authentication message
-        this.authenticate_with_primary(socket, public_key);
-      });
-      
-      socket.on('data', (data) => {
-        try {
-          const messages = message_parser.parse_messages(data);
-          for (const message of messages) {
-            this.handle_primary_response(message);
-          }
-        } catch (error) {
-          this.log.error('Failed to parse primary response', {
-            error: error.message
-          });
-        }
-      });
-      
-      socket.on('error', (error) => {
-        this.log.error('Primary connection error', {
-          error: error.message
-        });
-        
-        this.primary_connection = null;
-        
-        // Fail all pending forwards
-        this.fail_pending_forwards('Primary connection error');
-        
-        // Attempt reconnection after delay
-        setTimeout(() => {
-          this.connect_to_primary();
-        }, this.reconnect_delay_ms);
-      });
-      
-      socket.on('close', () => {
-        this.log.warn('Primary connection closed');
-        this.primary_connection = null;
-        
-        // Fail all pending forwards
-        this.fail_pending_forwards('Primary connection closed');
-        
-        // Attempt reconnection after delay
-        setTimeout(() => {
-          this.connect_to_primary();
-        }, this.reconnect_delay_ms);
-      });
-      
-      this.primary_connection = {
-        socket,
-        authenticated: false,
-        last_ping: Date.now()
-      };
-      
-    } catch (error) {
-      this.log.error('Failed to connect to primary', {
-        ip,
-        port,
-        error: error.message
-      });
-      
-      // Retry connection after delay
-      setTimeout(() => {
-        this.connect_to_primary();
-      }, this.reconnect_delay_ms);
-    }
-  }
-
-  /**
-   * Authenticates with the primary node using HMAC-SHA256 signature.
-   * Creates timestamped signature using public key and sends authentication message.
-   * Identifies this node as a secondary for proper handling by the primary.
-   * @param {net.Socket} socket - Socket connection to primary node
-   * @param {string} public_key - Base64 encoded public key for signing
-   * @returns {void}
-   */
-  authenticate_with_primary(socket, public_key) {
-    try {
-      const timestamp = Date.now();
-      const node_id = `secondary-${process.pid}`;
-      const message_to_sign = `${node_id}:${timestamp}`;
-      
-      // Create signature using public key (in real implementation, this would use private key)
-      const signature = crypto
-        .createHmac('sha256', Buffer.from(public_key, 'base64'))
-        .update(message_to_sign)
-        .digest('base64');
-      
-      const auth_message = {
-        op: 'authentication',
-        data: {
-          password: signature, // Use signature as password for now
-          node_type: 'secondary',
-          node_id
-        }
-      };
-      
-      const encoded_message = encode_message(auth_message);
-      socket.write(encoded_message);
-      
-      this.log.debug('Sent authentication to primary');
-      
-    } catch (error) {
-      this.log.error('Failed to authenticate with primary', {
-        error: error.message
-      });
-    }
-  }
-
-  /**
-   * Processes responses from the primary node including authentication and operation results.
-   * Routes different message types to appropriate handlers and maintains connection state.
-   * Handles authentication confirmations, forwarded operation responses, and ping responses.
-   * @param {Object|string} message - Parsed message from primary node
-   * @returns {void}
-   */
-  handle_primary_response(message) {
-    if (!this.primary_connection) return;
-    
-    try {
-      const parsed_message = typeof message === 'string' ? JSON.parse(message) : message;
-      
-      // Handle authentication response
-      if (parsed_message.ok === 1 && parsed_message.message === 'Authentication successful') {
-        this.primary_connection.authenticated = true;
-        this.log.info('Primary authentication successful');
-        return;
-      }
-      
-      // Handle forwarded operation responses
-      if (parsed_message.forward_id) {
-        this.handle_forward_response(parsed_message);
-        return;
-      }
-      
-      // Handle ping responses
-      if (parsed_message.ok === 1 && !parsed_message.forward_id) {
-        this.primary_connection.last_ping = Date.now();
-        return;
-      }
-      
-      this.log.debug('Unhandled primary response', {
-        type: typeof parsed_message,
-        keys: Object.keys(parsed_message)
-      });
-      
-    } catch (error) {
-      this.log.error('Failed to handle primary response', {
-        error: error.message
-      });
-    }
-  }
-
-  /**
-   * Processes responses to forwarded operations and updates statistics.
-   * Tracks operation latency, success/failure rates, and forwards responses to original clients.
-   * Clears timeouts and removes pending operations from tracking.
-   * @param {Object} response - Response from primary node with forward_id
-   * @param {string} response.forward_id - Unique identifier for the forwarded operation
-   * @param {number|boolean} response.ok - Success indicator (1/true for success, 0/false for failure)
-   * @param {string} [response.error] - Error message if operation failed
-   * @returns {void}
-   */
-  handle_forward_response(response) {
-    const { forward_id } = response;
-    const pending_forward = this.pending_forwards.get(forward_id);
-    
-    if (!pending_forward) {
-      this.log.warn('Received response for unknown forward', { forward_id });
-      return;
-    }
-    
-    const latency = Date.now() - pending_forward.sent_at;
-    this.stats.total_forward_time_ms += latency;
-    
-    // Clear timeout
-    clearTimeout(pending_forward.timeout);
-    
-    // Remove from pending forwards
-    this.pending_forwards.delete(forward_id);
-    
-    // Create response without forward_id for client
-    const client_response = { ...response };
-    delete client_response.forward_id;
-    
-    if (response.ok === 1 || response.ok === true) {
-      this.stats.successful_forwards++;
-      this.log.debug('Forward operation successful', {
-        forward_id,
-        latency_ms: latency,
-        operation: pending_forward.operation
-      });
-    } else {
-      this.stats.failed_forwards++;
-      this.log.error('Forward operation failed', {
-        forward_id,
-        latency_ms: latency,
-        operation: pending_forward.operation,
-        error: response.error
-      });
-    }
-    
-    // Update average latency
-    const total_ops = this.stats.successful_forwards + this.stats.failed_forwards;
-    this.stats.avg_forward_latency_ms = total_ops > 0 
-      ? Math.round(this.stats.total_forward_time_ms / total_ops)
-      : 0;
-    
-    // Send response to original client
-    try {
-      const encoded_response = encode_message(client_response);
-      pending_forward.client_socket.write(encoded_response);
-    } catch (error) {
-      this.log.error('Failed to send response to client', {
-        forward_id,
-        error: error.message
-      });
-    }
-  }
-
-  /**
-   * Determines if an operation should be forwarded to the primary node.
-   * Checks if node is in secondary mode and if operation is a write operation
-   * that requires forwarding to maintain data consistency.
-   * @param {string} op_type - Type of operation to check
-   * @returns {boolean} True if operation should be forwarded to primary
-   */
-  should_forward_operation(op_type) {
-    if (!this.is_secondary_mode) {
-      return false;
-    }
-    
-    const write_operations = [
-      'insert_one',
-      'update_one', 
-      'delete_one',
-      'bulk_write',
-      'create_index',
-      'drop_index'
-    ];
-    
-    return write_operations.includes(op_type);
-  }
-
-  /**
-   * Forwards a write operation to the primary node with timeout and error handling.
-   * Creates forward request with unique ID, sends to primary, and tracks pending operation.
-   * Handles connection failures and provides error responses to clients when needed.
-   * @param {net.Socket} client_socket - Original client socket for response delivery
-   * @param {string} op_type - Type of operation to forward (insert_one, update_one, etc.)
-   * @param {Object} data - Operation data including collection, document, and filters
-   * @returns {Promise<boolean>} True if forwarding was initiated or handled with error
-   */
-  async forward_operation(client_socket, op_type, data) {
-    if (!this.is_secondary_mode || !this.should_forward_operation(op_type)) {
-      return false;
-    }
-    
-    if (!this.primary_connection || !this.primary_connection.authenticated) {
-      this.log.error('Cannot forward operation - not connected to primary', {
-        operation: op_type,
-        connected: !!this.primary_connection,
-        authenticated: this.primary_connection?.authenticated || false
-      });
-      
-      // Send error response to client
-      const error_response = {
-        ok: 0,
-        error: 'Secondary node not connected to primary'
-      };
-      const encoded_error = encode_message(error_response);
-      client_socket.write(encoded_error);
-      
-      return true; // Operation was handled (with error)
-    }
-    
-    const forward_id = this.generate_forward_id();
-    
-    this.log.debug('Forwarding operation to primary', {
-      forward_id,
-      operation: op_type,
-      client_id: client_socket.id
-    });
-    
-    // Create forward request with metadata
-    const forward_request = {
-      op: op_type,
-      data,
-      forward_id,
-      forwarded_by: `secondary-${process.pid}`,
-      original_client_id: client_socket.id,
-      timestamp: Date.now()
-    };
-    
-    try {
-      const encoded_request = encode_message(forward_request);
-      this.primary_connection.socket.write(encoded_request);
-      
-      // Track pending forward with timeout
-      const timeout = setTimeout(() => {
-        this.handle_forward_timeout(forward_id);
-      }, this.forward_timeout_ms);
-      
-      this.pending_forwards.set(forward_id, {
-        client_socket,
-        operation: op_type,
-        data,
-        sent_at: Date.now(),
-        timeout
-      });
-      
-      this.stats.total_forwards++;
-      
-      return true; // Operation forwarded successfully
-      
-    } catch (error) {
-      this.log.error('Failed to forward operation', {
-        forward_id,
-        operation: op_type,
-        error: error.message
-      });
-      
-      // Send error response to client
-      const error_response = {
-        ok: 0,
-        error: `Failed to forward operation: ${error.message}`
-      };
-      const encoded_error = encode_message(error_response);
-      client_socket.write(encoded_error);
-      
-      return true; // Operation was handled (with error)
-    }
-  }
-
-  /**
-   * Handles timeout for forwarded operations that don't receive responses.
-   * Removes pending operation, updates statistics, and sends timeout error to client.
-   * Provides graceful handling of network delays or primary node issues.
-   * @param {string} forward_id - Unique identifier of the timed-out forward operation
-   * @returns {void}
-   */
-  handle_forward_timeout(forward_id) {
-    const pending_forward = this.pending_forwards.get(forward_id);
-    
-    if (!pending_forward) {
-      return;
-    }
-    
-    this.log.error('Forward operation timed out', {
-      forward_id,
-      operation: pending_forward.operation,
-      timeout_ms: this.forward_timeout_ms
-    });
-    
-    this.pending_forwards.delete(forward_id);
-    this.stats.failed_forwards++;
-    
-    // Update average latency
-    const latency = Date.now() - pending_forward.sent_at;
-    this.stats.total_forward_time_ms += latency;
-    const total_ops = this.stats.successful_forwards + this.stats.failed_forwards;
-    this.stats.avg_forward_latency_ms = total_ops > 0 
-      ? Math.round(this.stats.total_forward_time_ms / total_ops)
-      : 0;
-    
-    // Send timeout error to client
-    try {
-      const error_response = {
-        ok: 0,
-        error: 'Operation forwarding timed out'
-      };
-      const encoded_error = encode_message(error_response);
-      pending_forward.client_socket.write(encoded_error);
-    } catch (error) {
-      this.log.error('Failed to send timeout error to client', {
-        forward_id,
-        error: error.message
-      });
-    }
-  }
-
-  /**
-   * Fails all pending forward operations with a specified reason.
-   * Clears timeouts, sends error responses to clients, and updates statistics.
-   * Used when primary connection is lost or during shutdown procedures.
-   * @param {string} reason - Reason for failing all pending operations
-   * @returns {void}
-   */
-  fail_pending_forwards(reason) {
-    for (const [forward_id, pending_forward] of this.pending_forwards) {
-      clearTimeout(pending_forward.timeout);
-      
-      this.log.error('Failing pending forward operation', {
-        forward_id,
-        operation: pending_forward.operation,
-        reason
-      });
-      
-      // Send error response to client
-      try {
-        const error_response = {
-          ok: 0,
-          error: `Forward operation failed: ${reason}`
-        };
-        const encoded_error = encode_message(error_response);
-        pending_forward.client_socket.write(encoded_error);
-      } catch (error) {
-        this.log.error('Failed to send error to client', {
-          forward_id,
-          error: error.message
-        });
-      }
-    }
-    
-    this.stats.failed_forwards += this.pending_forwards.size;
-    this.pending_forwards.clear();
-  }
-
-  /**
-   * Generates a unique identifier for forward operations.
-   * Creates timestamp-based ID with random suffix for uniqueness and traceability.
-   * @returns {string} Unique forward operation identifier
-   */
-  generate_forward_id() {
-    return `fwd_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-  }
-
-  /**
-   * Retrieves comprehensive write forwarder status and statistics.
-   * Returns current configuration, connection state, pending operations,
-   * and detailed statistics for monitoring and debugging purposes.
-   * @returns {Object} Complete write forwarder status information
-   * @returns {boolean} returns.enabled - Whether write forwarding is enabled
-   * @returns {boolean} returns.connected_to_primary - Whether connected and authenticated to primary
-   * @returns {Object|null} returns.primary_config - Primary node configuration (IP and port)
-   * @returns {number} returns.pending_forwards - Number of pending forward operations
-   * @returns {Object} returns.stats - Detailed forwarding statistics and metrics
-   */
-  get_forwarder_status() {
-    return {
-      enabled: this.is_secondary_mode,
-      connected_to_primary: !!this.primary_connection && this.primary_connection.authenticated,
-      primary_config: this.primary_config ? {
-        ip: this.primary_config.ip,
-        port: this.primary_config.port
-      } : null,
-      pending_forwards: this.pending_forwards.size,
-      stats: this.stats
-    };
-  }
-
-  /**
-   * Gracefully shuts down write forwarder and closes primary connection.
-   * Fails all pending operations, closes connection to primary, and resets state
-   * for clean shutdown without leaving clients waiting for responses.
-   * @returns {Promise<void>}
-   */
-  async shutdown() {
-    this.log.info('Shutting down write forwarder');
-    
-    // Fail all pending forwards
-    this.fail_pending_forwards('Server shutting down');
-    
-    // Close primary connection
-    if (this.primary_connection) {
-      try {
-        this.primary_connection.socket.end();
-      } catch (error) {
-        this.log.warn('Error closing primary connection', {
-          error: error.message
-        });
-      }
-      this.primary_connection = null;
-    }
-    
-    this.is_secondary_mode = false;
-    
-    this.log.info('Write forwarder shutdown complete');
-  }
-}
-
-/** @type {WriteForwarder|null} Singleton write forwarder instance */
-let write_forwarder_instance = null;
-
-/**
- * Gets the write forwarder singleton instance.
- * Creates new instance if one doesn't exist, ensuring single forwarder per process.
- * @returns {WriteForwarder} Write forwarder singleton instance
- */
-export const get_write_forwarder = () => {
-  if (!write_forwarder_instance) {
-    write_forwarder_instance = new WriteForwarder();
-  }
-  return write_forwarder_instance;
-};
-
-/**
- * Initializes the write forwarder singleton with configuration.
- * Gets or creates forwarder instance and calls initialize to load settings
- * and establish primary connection if in secondary mode.
- * @returns {void}
- */
-export const initialize_write_forwarder = () => {
-  const forwarder = get_write_forwarder();
-  forwarder.initialize();
-};
-
-/**
- * Shuts down the write forwarder singleton and cleans up resources.
- * Calls shutdown on existing instance and resets singleton reference
- * for clean process termination.
- * @returns {Promise<void>}
- */
-export const shutdown_write_forwarder = async () => {
-  if (write_forwarder_instance) {
-    await write_forwarder_instance.shutdown();
-    write_forwarder_instance = null;
-  }
-};