@joystick.js/db-canary 0.0.0-canary.2251 → 0.0.0-canary.2253

package/src/server/index.js

@@ -56,25 +56,70 @@ import {
   initialize_recovery_manager,
   reset_recovery_state
 } from './lib/recovery_manager.js';
+import { has_settings } from './lib/load_settings.js';
 
-/** @type {Set<string>} Set of authenticated client socket IDs */
 const authenticated_clients = new Set();
-
-/** @type {Object|null} Connection manager instance */
 let connection_manager = null;
 
+/**
+ * Validates authentication request data.
+ * @param {Object} data - Authentication data
+ * @returns {boolean} True if data is valid
+ */
+const validate_authentication_data = (data) => {
+  return data && data.password;
+};
+
+/**
+ * Creates authentication error response.
+ * @param {string} error_message - Error message
+ * @returns {Object} Error response object
+ */
+const create_authentication_error_response = (error_message) => ({
+  ok: 0,
+  error: error_message
+});
+
+/**
+ * Creates authentication success response.
+ * @returns {Object} Success response object
+ */
+const create_authentication_success_response = () => ({
+  ok: 1,
+  version: "1.0.0",
+  message: 'Authentication successful'
+});
+
+/**
+ * Sends response and closes socket connection.
+ * @param {net.Socket} socket - Client socket
+ * @param {Object} response - Response object to send
+ */
+const send_response_and_close_socket = (socket, response) => {
+  const encoded_response = encode_message(response);
+  socket.write(encoded_response);
+  socket.end();
+};
+
+/**
+ * Sends response to socket without closing.
+ * @param {net.Socket} socket - Client socket
+ * @param {Object} response - Response object to send
+ */
+const send_response_to_socket = (socket, response) => {
+  const encoded_response = encode_message(response);
+  socket.write(encoded_response);
+};
+
 /**
  * Handles client authentication requests.
  * @param {net.Socket} socket - Client socket connection
- * @param {Object} [data={}] - Authentication data containing password
- * @param {string} data.password - Client password for authentication
+ * @param {Object} data - Authentication data containing password
  */
 export const authentication = async (socket, data = {}) => {
-  if (!data?.password) {
-    const response = { ok: 0, error: 'Authentication operation requires password to be set in data.' };
-    const encoded_response = encode_message(response);
-    socket.write(encoded_response);
-    socket.end();
+  if (!validate_authentication_data(data)) {
+    const response = create_authentication_error_response('Authentication operation requires password to be set in data.');
+    send_response_and_close_socket(socket, response);
     return;
   }
   
@@ -82,66 +127,68 @@ export const authentication = async (socket, data = {}) => {
     const client_ip = get_client_ip(socket);
     
     if (is_rate_limited(client_ip)) {
-      const response = { ok: 0, error: 'Too many failed attempts. Please try again later.' };
-      const encoded_response = encode_message(response);
-      socket.write(encoded_response);
-      socket.end();
+      const response = create_authentication_error_response('Too many failed attempts. Please try again later.');
+      send_response_and_close_socket(socket, response);
       return;
     }
     
     const is_valid = await verify_password(data.password, client_ip);
     
     if (!is_valid) {
-      const response = { ok: 0, error: 'Authentication failed' };
-      const encoded_response = encode_message(response);
-      socket.write(encoded_response);
-      socket.end();
+      const response = create_authentication_error_response('Authentication failed');
+      send_response_and_close_socket(socket, response);
       return;
     }
     
     authenticated_clients.add(socket.id);
-    const auth_response = { 
-      ok: 1, 
-      version: "1.0.0",
-      message: 'Authentication successful' 
-    };
-    const encoded_auth_response = encode_message(auth_response);
-    socket.write(encoded_auth_response);
+    const auth_response = create_authentication_success_response();
+    send_response_to_socket(socket, auth_response);
   } catch (error) {
-    const response = { ok: 0, error: `Authentication error: ${error.message}` };
-    const encoded_response = encode_message(response);
-    socket.write(encoded_response);
-    socket.end();
+    const response = create_authentication_error_response(`Authentication error: ${error.message}`);
+    send_response_and_close_socket(socket, response);
   }
 };
 
+/**
+ * Creates setup success response.
+ * @param {string} password - Generated password
+ * @returns {Object} Setup response object
+ */
+const create_setup_success_response = (password) => ({
+  ok: 1,
+  password,
+  message: 'Authentication setup completed successfully. Save this password - it will not be shown again.'
+});
+
+/**
+ * Creates setup error response.
+ * @param {string} error_message - Error message
+ * @returns {Object} Error response object
+ */
+const create_setup_error_response = (error_message) => ({
+  ok: 0,
+  error: `Setup error: ${error_message}`
+});
+
 /**
  * Handles initial server setup, generating authentication password.
  * @param {net.Socket} socket - Client socket connection
- * @param {Object} [data={}] - Setup data (currently unused)
+ * @param {Object} data - Setup data (currently unused)
  */
 export const setup = async (socket, data = {}) => {
   try {
     const password = setup_authentication();
-    
-    // NOTE: Return response format expected by tests.
-    const response = {
-      ok: 1,
-      password,
-      message: 'Authentication setup completed successfully. Save this password - it will not be shown again.'
-    };
-    const encoded_response = encode_message(response);
-    socket.write(encoded_response);
+    const response = create_setup_success_response(password);
+    send_response_to_socket(socket, response);
   } catch (error) {
-    const response = { ok: 0, error: `Setup error: ${error.message}` };
-    const encoded_response = encode_message(response);
-    socket.write(encoded_response);
+    const response = create_setup_error_response(error.message);
+    send_response_to_socket(socket, response);
   }
 };
 
 /**
  * Validates if an operation type is supported.
- * @param {string} [op_type=''] - Operation type to validate
+ * @param {string} op_type - Operation type to validate
  * @returns {boolean} True if operation type is valid
  * @throws {Error} When no operation type is provided
  */
@@ -153,6 +200,32 @@ export const check_op_type = (op_type = '') => {
   return op_types.includes(op_type);
 };
 
+/**
+ * Parses string data as JSON.
+ * @param {string} string_data - String data to parse
+ * @returns {Object|null} Parsed JSON object or null
+ */
+const parse_string_data = (string_data) => {
+  return safe_json_parse(string_data);
+};
+
+/**
+ * Parses Buffer data as MessagePack then JSON.
+ * @param {Buffer} buffer_data - Buffer data to parse
+ * @returns {Object|null} Parsed object or null
+ */
+const parse_buffer_data = (buffer_data) => {
+  try {
+    const decoded_messagepack = decode_messagepack(buffer_data);
+    if (typeof decoded_messagepack === 'string') {
+      return safe_json_parse(decoded_messagepack);
+    }
+    return decoded_messagepack;
+  } catch (error) {
+    return null;
+  }
+};
+
 /**
  * Parses raw data from various formats (string, Buffer, MessagePack) into JavaScript objects.
  * @param {string|Buffer|Object} raw_data - Raw data to parse
@@ -161,17 +234,10 @@ export const check_op_type = (op_type = '') => {
 export const parse_data = (raw_data) => {
   try {
     if (typeof raw_data === 'string') {
-      const data_as_json = safe_json_parse(raw_data);
-      return data_as_json;
+      return parse_string_data(raw_data);
     } else if (Buffer.isBuffer(raw_data)) {
-      // NOTE: Decode MessagePack buffer and then parse as JSON.
-      const decoded_messagepack = decode_messagepack(raw_data);
-      if (typeof decoded_messagepack === 'string') {
-        return safe_json_parse(decoded_messagepack);
-      }
-      return decoded_messagepack;
+      return parse_buffer_data(raw_data);
     } else {
-      // NOTE: raw_data is already decoded from MessagePack by the message parser.
       return raw_data;
     }
   } catch (error) {
@@ -186,7 +252,6 @@ export const parse_data = (raw_data) => {
  * @returns {boolean} True if socket is authenticated or in development mode
  */
 const check_authentication = (socket) => {
-  // NOTE: Bypass authentication in development mode for TCP connections.
   if (is_development_mode()) {
     return true;
   }
@@ -194,363 +259,509 @@ const check_authentication = (socket) => {
   return authenticated_clients.has(socket.id);
 };
 
-
 /**
- * @typedef {Object} ServerOptions
- * @property {number} [worker_count] - Number of worker processes
- * @property {number} [port=1983] - Server port
- * @property {string} [environment] - Environment name for settings file (defaults to NODE_ENV)
+ * Attempts to restore from backup if configured.
+ * @param {Object} settings - Server settings
+ * @param {Function} log - Logger function
  */
+const attempt_startup_restore = async (settings, log) => {
+  if (!settings?.restore_from) {
+    return;
+  }
+
+  try {
+    log.info('Startup restore requested', { backup_filename: settings.restore_from });
+    
+    const restore_result = await restore_backup(settings.restore_from);
+    
+    log.info('Startup restore completed', {
+      backup_filename: settings.restore_from,
+      duration_ms: restore_result.duration_ms
+    });
+    
+    const updated_settings = { ...settings };
+    delete updated_settings.restore_from;
+    
+    process.env.JOYSTICK_DB_SETTINGS = JSON.stringify(updated_settings);
+    
+    load_settings();
+    
+    log.info('Removed restore_from from settings after successful restore');
+  } catch (restore_error) {
+    log.error('Startup restore failed', {
+      backup_filename: settings.restore_from,
+      error: restore_error.message
+    });
+    
+    log.info('Continuing with fresh database after restore failure');
+  }
+};
 
 /**
- * Creates and configures the JoystickDB TCP server.
- * @returns {Promise<net.Server>} Configured TCP server instance with cleanup method
+ * Loads server settings with fallback for missing files.
+ * @returns {Object|null} Settings object or null if not available
  */
-export const create_server = async () => {
-  const { create_context_logger } = create_logger('server');
-  const log = create_context_logger();
-  
-  /*
-    NOTE:
-    Try to load settings, but don't fail if file doesn't exist (for tests).
-  */
-  let settings = null;
+const load_server_settings = () => {
   try {
     load_settings();
-    settings = get_settings();
+    return get_settings();
   } catch (error) {
-    /*
-      NOTE:
-      Settings file doesn't exist - this is OK for tests.
-      We'll handle missing settings in individual operations.
-    */
-  }
-  
-  // NOTE: Handle startup restore if configured.
-  if (settings?.restore_from) {
-    try {
-      log.info('Startup restore requested', { backup_filename: settings.restore_from });
-      
-      const restore_result = await restore_backup(settings.restore_from);
-      
-      log.info('Startup restore completed', {
-        backup_filename: settings.restore_from,
-        duration_ms: restore_result.duration_ms
-      });
-      
-      // NOTE: Remove restore_from from settings after successful restore.
-      const updated_settings = { ...settings };
-      delete updated_settings.restore_from;
-      
-      // NOTE: Update the environment variable with the new settings.
-      process.env.JOYSTICK_DB_SETTINGS = JSON.stringify(updated_settings);
-      
-      // NOTE: Reload settings to reflect the change.
-      load_settings();
-      settings = get_settings();
-      
-      log.info('Removed restore_from from settings after successful restore');
-    } catch (restore_error) {
-      log.error('Startup restore failed', {
-        backup_filename: settings.restore_from,
-        error: restore_error.message
-      });
-      
-      // NOTE: Continue with fresh database if restore fails.
-      log.info('Continuing with fresh database after restore failure');
-    }
-  }
-  
-  // NOTE: Initialize database with data_path from settings if available.
-  let database_path = './data'; // Default path
-  if (settings?.data_path) {
-    database_path = settings.data_path;
+    return null;
   }
+};
+
+/**
+ * Initializes core server components.
+ * @param {Object} settings - Server settings
+ */
+const initialize_server_components = async (settings) => {
+  const database_path = settings?.data_path || './data';
   
   initialize_database(database_path);
   initialize_auth_manager();
   await initialize_api_key_manager();
   initialize_recovery_manager();
-  
-  // NOTE: Initialize replication manager for primary nodes.
+};
+
+/**
+ * Initializes replication manager with error handling.
+ * @param {Function} log - Logger function
+ */
+const initialize_replication_with_logging = (log) => {
   try {
     initialize_replication_manager();
     log.info('Replication manager initialized');
   } catch (replication_error) {
     log.warn('Failed to initialize replication manager', { error: replication_error.message });
   }
-  
-  // NOTE: Initialize write forwarder for secondary nodes.
+};
+
+/**
+ * Initializes write forwarder with error handling.
+ * @param {Function} log - Logger function
+ */
+const initialize_write_forwarder_with_logging = (log) => {
   try {
     initialize_write_forwarder();
     log.info('Write forwarder initialized');
   } catch (forwarder_error) {
     log.warn('Failed to initialize write forwarder', { error: forwarder_error.message });
   }
-  
-  // NOTE: Start backup scheduling if S3 is configured.
-  if (settings?.s3) {
-    try {
-      start_backup_schedule();
-      log.info('Backup scheduling started');
-    } catch (backup_schedule_error) {
-      log.warn('Failed to start backup scheduling', { error: backup_schedule_error.message });
-    }
+};
+
+/**
+ * Starts backup scheduling if S3 is configured.
+ * @param {Object} settings - Server settings
+ * @param {Function} log - Logger function
+ */
+const start_backup_scheduling = (settings, log) => {
+  if (!settings?.s3) {
+    return;
   }
-  
-  connection_manager = create_connection_manager({
-    max_connections: 1000,
-    idle_timeout: 10 * 60 * 1000,
-    request_timeout: 5 * 1000
-  });
-  
-  // NOTE: Start HTTP server for setup and recovery operations.
-  let http_server_instance = null;
+
   try {
-    const { http_port } = get_port_configuration();
-    http_server_instance = await start_http_server(http_port);
+    start_backup_schedule();
+    log.info('Backup scheduling started');
+  } catch (backup_schedule_error) {
+    log.warn('Failed to start backup scheduling', { error: backup_schedule_error.message });
+  }
+};
+
+/**
+ * Starts HTTP server with error handling.
+ * @param {number} http_port - HTTP port number
+ * @param {Function} log - Logger function
+ * @returns {Object|null} HTTP server instance or null
+ */
+const start_http_server_with_logging = async (http_port, log) => {
+  try {
+    const http_server_instance = await start_http_server(http_port);
     if (http_server_instance) {
       log.info('HTTP server started', { http_port });
     }
+    return http_server_instance;
   } catch (http_error) {
     log.warn('Failed to start HTTP server', { error: http_error.message });
+    return null;
   }
-  
-  // NOTE: Display development mode startup message if in development.
+};
+
+/**
+ * Displays appropriate startup messages based on environment.
+ */
+const display_startup_messages = () => {
   if (is_development_mode()) {
     const { tcp_port, http_port } = get_port_configuration();
     display_development_startup_message(tcp_port, http_port);
   } else {
     warn_undefined_node_env();
   }
+};
+
+/**
+ * Creates connection manager instance.
+ * @returns {Object} Connection manager instance
+ */
+const create_server_connection_manager = () => {
+  return create_connection_manager({
+    max_connections: 1000,
+    idle_timeout: 10 * 60 * 1000,
+    request_timeout: 5 * 1000
+  });
+};
+
+/**
+ * Handles socket data processing.
+ * @param {net.Socket} socket - Client socket
+ * @param {Buffer} raw_data - Raw socket data
+ * @param {Object} message_parser - Message parser instance
+ * @param {Function} log - Logger function
+ */
+const handle_socket_data = async (socket, raw_data, message_parser, log) => {
+  connection_manager.update_activity(socket.id);
   
-  const server = net.createServer((socket = {}) => {
-    if (!connection_manager.add_connection(socket)) {
-      return;
-    }
+  try {
+    const messages = message_parser.parse_messages(raw_data);
     
-    const message_parser = create_message_parser();
+    for (const message of messages) {
+      await process_single_message(socket, message, raw_data.length, log);
+    }
+  } catch (error) {
+    log.error('Message parsing failed', {
+      client_id: socket.id,
+      error: error.message
+    });
     
-    socket.on('data', async (raw_data) => {
-      connection_manager.update_activity(socket.id);
+    send_error(socket, { message: 'Invalid message format' });
+    socket.end();
+  }
+};
+
+/**
+ * Processes a single parsed message.
+ * @param {net.Socket} socket - Client socket
+ * @param {Object} message - Parsed message
+ * @param {number} raw_data_size - Size of raw data
+ * @param {Function} log - Logger function
+ */
+const process_single_message = async (socket, message, raw_data_size, log) => {
+  const parsed_data = message;
+  const op_type = parsed_data?.op || null;
+  
+  if (!op_type) {
+    send_error(socket, { message: 'Missing operation type' });
+    return;
+  }
+  
+  const is_valid_op_type = check_op_type(op_type);
+  
+  if (!is_valid_op_type) {
+    send_error(socket, { message: 'Invalid operation type' });
+    return;
+  }
+  
+  const request_timeout = connection_manager.create_request_timeout(socket.id, op_type);
+  
+  try {
+    await route_operation_to_handler(socket, op_type, parsed_data, raw_data_size);
+  } finally {
+    clearTimeout(request_timeout);
+  }
+};
+
+/**
+ * Routes operation to appropriate handler.
+ * @param {net.Socket} socket - Client socket
+ * @param {string} op_type - Operation type
+ * @param {Object} parsed_data - Parsed message data
+ * @param {number} raw_data_size - Size of raw data
+ */
+const route_operation_to_handler = async (socket, op_type, parsed_data, raw_data_size) => {
+  const operation_data = parsed_data?.data || {};
+  
+  switch(op_type) {
+    case 'authentication':
+      await authentication(socket, operation_data);
+      break;
       
-      try {
-        const messages = message_parser.parse_messages(raw_data);
-        
-        for (const message of messages) {
-          // NOTE: Message is already decoded from MessagePack by the message parser.
-          const parsed_data = message;
-          const op_type = parsed_data?.op || null;
-          
-          if (!op_type) {
-            send_error(socket, { message: 'Missing operation type' });
-            continue;
-          }
-          
-          const is_valid_op_type = check_op_type(op_type);
-          
-          if (!is_valid_op_type) {
-            send_error(socket, { message: 'Invalid operation type' });
-            continue;
-          }
-          
-          const request_timeout = connection_manager.create_request_timeout(socket.id, op_type);
-          
-          try {
-            switch(op_type) {
-              case 'authentication':
-                await authentication(socket, parsed_data?.data || {});
-                break;
-                
-              case 'setup':
-                await setup(socket, parsed_data?.data || {});
-                break;
-                
-              case 'insert_one':
-              case 'update_one':
-              case 'delete_one':
-              case 'delete_many':
-              case 'bulk_write':
-              case 'find_one':
-              case 'find':
-              case 'create_index':
-              case 'drop_index':
-              case 'get_indexes':
-                // NOTE: Use shared operation dispatcher for database operations.
-                await handle_database_operation(socket, op_type, parsed_data?.data || {}, check_authentication, raw_data.length, connection_manager, authenticated_clients);
-                break;
-                
-              case 'ping':
-                handle_ping_operation(socket);
-                break;
-                
-              case 'admin':
-                // NOTE: Use shared operation dispatcher for admin operations.
-                await handle_admin_operation(socket, parsed_data?.data || {}, check_authentication, connection_manager, authenticated_clients);
-                break;
-                
-              case 'reload':
-                if (!check_authentication(socket)) {
-                  send_error(socket, { message: 'Authentication required' });
-                  break;
-                }
-                
-                try {
-                  let old_settings = null;
-                  try {
-                    old_settings = get_settings();
-                  } catch (error) {
-                    // NOTE: Settings not loaded yet, that's OK.
-                  }
-                  
-                  let new_settings = null;
-                  try {
-                    await load_settings();
-                    new_settings = get_settings();
-                  } catch (error) {
-                    // NOTE: Settings file doesn't exist, create default settings for tests.
-                    new_settings = {
-                      port: 1983,
-                      authentication: {}
-                    };
-                  }
-                  
-                  const reload_info = {
-                    ok: 1,
-                    status: 'success',
-                    message: 'Configuration reloaded successfully',
-                    changes: {
-                      port_changed: old_settings ? old_settings.port !== new_settings.port : false,
-                      authentication_changed: old_settings ? old_settings.authentication?.password_hash !== new_settings.authentication?.password_hash : false
-                    },
-                    timestamp: new Date().toISOString()
-                  };
-                  
-                  const encoded_response = encode_message(reload_info);
-                  socket.write(encoded_response);
-                } catch (error) {
-                  const error_response = { ok: 0, error: `Reload operation failed: ${error.message}` };
-                  const encoded_error_response = encode_message(error_response);
-                  socket.write(encoded_error_response);
-                }
-                break;
-                
-              default:
-                send_error(socket, { message: `Operation ${op_type} not implemented` });
-            }
-          } finally {
-            clearTimeout(request_timeout);
-          }
-        }
-      } catch (error) {
-        log.error('Message parsing failed', {
-          client_id: socket.id,
-          error: error.message
-        });
-        
-        send_error(socket, { message: 'Invalid message format' });
-        socket.end();
-      }
-    });
+    case 'setup':
+      await setup(socket, operation_data);
+      break;
+      
+    case 'insert_one':
+    case 'update_one':
+    case 'delete_one':
+    case 'delete_many':
+    case 'bulk_write':
+    case 'find_one':
+    case 'find':
+    case 'create_index':
+    case 'drop_index':
+    case 'get_indexes':
+      await handle_database_operation(socket, op_type, operation_data, check_authentication, raw_data_size, connection_manager, authenticated_clients);
+      break;
+      
+    case 'ping':
+      handle_ping_operation(socket);
+      break;
+      
+    case 'admin':
+      await handle_admin_operation(socket, operation_data, check_authentication, connection_manager, authenticated_clients);
+      break;
+      
+    case 'reload':
+      await handle_reload_operation(socket);
+      break;
+      
+    default:
+      send_error(socket, { message: `Operation ${op_type} not implemented` });
+  }
+};
 
-    socket.on('end', () => {
-      log.info('Client disconnected', { socket_id: socket.id });
-      authenticated_clients.delete(socket.id);
-      connection_manager.remove_connection(socket.id);
-    });
+/**
+ * Handles reload operation.
+ * @param {net.Socket} socket - Client socket
+ */
+const handle_reload_operation = async (socket) => {
+  if (!check_authentication(socket)) {
+    send_error(socket, { message: 'Authentication required' });
+    return;
+  }
+  
+  try {
+    const old_settings = get_current_settings();
+    const new_settings = await reload_server_settings();
     
-    socket.on('error', (error) => {
-      log.error('Socket error', {
-        socket_id: socket.id,
-        error: error.message
-      });
-      
-      authenticated_clients.delete(socket.id);
-      connection_manager.remove_connection(socket.id);
-    });
+    const reload_info = create_reload_response(old_settings, new_settings);
+    send_response_to_socket(socket, reload_info);
+  } catch (error) {
+    const error_response = { ok: 0, error: `Reload operation failed: ${error.message}` };
+    send_response_to_socket(socket, error_response);
+  }
+};
+
+/**
+ * Gets current settings with fallback.
+ * @returns {Object|null} Current settings or null
+ */
+const get_current_settings = () => {
+  try {
+    return get_settings();
+  } catch (error) {
+    return null;
+  }
+};
+
+/**
+ * Reloads server settings.
+ * @returns {Object} New settings object
+ */
+const reload_server_settings = async () => {
+  try {
+    await load_settings();
+    return get_settings();
+  } catch (error) {
+    return {
+      port: 1983,
+      authentication: {}
+    };
+  }
+};
+
+/**
+ * Creates reload operation response.
+ * @param {Object} old_settings - Previous settings
+ * @param {Object} new_settings - New settings
+ * @returns {Object} Reload response object
+ */
+const create_reload_response = (old_settings, new_settings) => ({
+  ok: 1,
+  status: 'success',
+  message: 'Configuration reloaded successfully',
+  changes: {
+    port_changed: old_settings ? old_settings.port !== new_settings.port : false,
+    authentication_changed: old_settings ? old_settings.authentication?.password_hash !== new_settings.authentication?.password_hash : false
+  },
+  timestamp: new Date().toISOString()
+});
+
+/**
+ * Handles socket disconnection.
+ * @param {net.Socket} socket - Client socket
+ * @param {Function} log - Logger function
+ */
+const handle_socket_disconnection = (socket, log) => {
+  log.info('Client disconnected', { socket_id: socket.id });
+  authenticated_clients.delete(socket.id);
+  connection_manager.remove_connection(socket.id);
+};
+
+/**
+ * Handles socket errors.
+ * @param {net.Socket} socket - Client socket
+ * @param {Error} error - Socket error
+ * @param {Function} log - Logger function
+ */
+const handle_socket_error = (socket, error, log) => {
+  log.error('Socket error', {
+    socket_id: socket.id,
+    error: error.message
+  });
+  
+  authenticated_clients.delete(socket.id);
+  connection_manager.remove_connection(socket.id);
+};
+
+/**
+ * Sets up socket event handlers.
+ * @param {net.Socket} socket - Client socket
+ * @param {Object} message_parser - Message parser instance
+ * @param {Function} log - Logger function
+ */
+const setup_socket_event_handlers = (socket, message_parser, log) => {
+  socket.on('data', async (raw_data) => {
+    await handle_socket_data(socket, raw_data, message_parser, log);
   });
+
+  socket.on('end', () => {
+    handle_socket_disconnection(socket, log);
+  });
+  
+  socket.on('error', (error) => {
+    handle_socket_error(socket, error, log);
+  });
+};
+
+/**
+ * Handles new socket connections.
+ * @param {net.Socket} socket - New client socket
+ * @param {Function} log - Logger function
+ */
+const handle_new_socket_connection = (socket, log) => {
+  if (!connection_manager.add_connection(socket)) {
+    return;
+  }
   
-  // NOTE: Add cleanup method for tests.
-  server.cleanup = async () => {
+  const message_parser = create_message_parser();
+  setup_socket_event_handlers(socket, message_parser, log);
+};
+
+/**
+ * Creates cleanup function for server shutdown.
+ * @returns {Function} Cleanup function
+ */
+const create_server_cleanup_function = () => {
+  return async () => {
     try {
-      // NOTE: Stop HTTP server.
       await stop_http_server();
-      
-      // NOTE: Stop backup scheduling.
       stop_backup_schedule();
-      
-      // NOTE: Shutdown replication manager.
       await shutdown_replication_manager();
-      
-      // NOTE: Shutdown write forwarder.
       await shutdown_write_forwarder();
       
-      // NOTE: Shutdown connection manager.
       if (connection_manager) {
         connection_manager.shutdown();
       }
       
-      // NOTE: Clear authenticated clients.
       authenticated_clients.clear();
-      
-      // NOTE: Shutdown write queue.
       await shutdown_write_queue();
       
-      // NOTE: Wait a bit to ensure all operations are complete.
       await new Promise(resolve => setTimeout(resolve, 100));
-      
-      // NOTE: Cleanup database (after everything else is shut down).
       await cleanup_database();
       
-      // NOTE: Reset auth state.
       reset_auth_state();
-      
-      // NOTE: Reset recovery state.
       reset_recovery_state();
     } catch (error) {
       // NOTE: Ignore cleanup errors in tests.
     }
   };
-  
-  return server;
 };
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const { create_context_logger } = create_logger('main');
+/**
+ * @typedef {Object} ServerOptions
+ * @property {number} [worker_count] - Number of worker processes
+ * @property {number} [port=1983] - Server port
+ * @property {string} [environment] - Environment name for settings file (defaults to NODE_ENV)
+ */
+
+/**
+ * Creates and configures the JoystickDB TCP server.
+ * @returns {Promise<net.Server>} Configured TCP server instance with cleanup method
+ */
+export const create_server = async () => {
+  const { create_context_logger } = create_logger('server');
   const log = create_context_logger();
   
-  // NOTE: Check for recovery token generation flag.
-  if (process.argv.includes('--generate-recovery-token')) {
-    try {
-      initialize_recovery_manager();
-      const recovery_info = create_recovery_token();
-      
-      console.log('Emergency Recovery Token Generated');
-      console.log(`Visit: ${recovery_info.url}`);
-      console.log('Token expires in 10 minutes');
-      
-      log.info('Recovery token generated via CLI', {
-        expires_at: new Date(recovery_info.expires_at).toISOString()
-      });
-      
-      process.exit(0);
-    } catch (error) {
-      console.error('Failed to generate recovery token:', error.message);
-      log.error('Recovery token generation failed', { error: error.message });
-      process.exit(1);
-    }
-  }
+  const settings = load_server_settings();
   
-  // NOTE: Get port configuration from settings or use defaults.
-  const { tcp_port, http_port } = get_port_configuration();
+  await attempt_startup_restore(settings, log);
+  await initialize_server_components(settings);
+  
+  initialize_replication_with_logging(log);
+  initialize_write_forwarder_with_logging(log);
+  start_backup_scheduling(settings, log);
+  
+  connection_manager = create_server_connection_manager();
   
-  const options = {
+  const { http_port } = get_port_configuration();
+  await start_http_server_with_logging(http_port, log);
+  
+  display_startup_messages();
+  
+  const server = net.createServer((socket = {}) => {
+    handle_new_socket_connection(socket, log);
+  });
+  
+  server.cleanup = create_server_cleanup_function();
+  
+  return server;
+};
+
+/**
+ * Handles recovery token generation from command line.
+ * @param {Function} log - Logger function
+ */
+const handle_recovery_token_generation = (log) => {
+  try {
+    initialize_recovery_manager();
+    const recovery_info = create_recovery_token();
+    
+    console.log('Emergency Recovery Token Generated');
+    console.log(`Visit: ${recovery_info.url}`);
+    console.log('Token expires in 10 minutes');
+    
+    log.info('Recovery token generated via CLI', {
+      expires_at: new Date(recovery_info.expires_at).toISOString()
+    });
+    
+    process.exit(0);
+  } catch (error) {
+    console.error('Failed to generate recovery token:', error.message);
+    log.error('Recovery token generation failed', { error: error.message });
+    process.exit(1);
+  }
+};
+
+/**
+ * Creates server startup options.
+ * @returns {Object} Server options object
+ */
+const create_server_startup_options = () => {
+  const { tcp_port } = get_port_configuration();
+  
+  return {
     worker_count: process.env.WORKER_COUNT ? parseInt(process.env.WORKER_COUNT) : undefined,
     port: tcp_port,
     environment: process.env.NODE_ENV || 'development'
   };
-  
-  const { has_settings } = await import('./lib/load_settings.js');
+};
+
+/**
+ * Logs server startup information.
+ * @param {Object} options - Server options
+ * @param {Function} log - Logger function
+ */
+const log_server_startup_info = (options, log) => {
+  const { tcp_port, http_port } = get_port_configuration();
   const has_db_settings = has_settings();
   
   log.info('Starting JoystickDB server...', {
@@ -561,6 +772,18 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     has_settings: has_db_settings,
     port_source: has_db_settings ? 'JOYSTICK_DB_SETTINGS' : 'default'
   });
+};
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { create_context_logger } = create_logger('main');
+  const log = create_context_logger();
+  
+  if (process.argv.includes('--generate-recovery-token')) {
+    handle_recovery_token_generation(log);
+  }
+  
+  const options = create_server_startup_options();
+  log_server_startup_info(options, log);
   
   start_cluster(options);
 }