@joystick.js/db-canary 0.0.0-canary.2209

package/src/client/index.js

@@ -0,0 +1,752 @@
+import net from 'net';
+import { EventEmitter } from 'events';
+import { encode as encode_messagepack, decode as decode_messagepack } from 'msgpackr';
+import Database from './database.js';
+
+/**
+ * Encodes a message with MessagePack and prepends a 4-byte length header.
+ * @param {any} data - The data to encode
+ * @returns {Buffer} The encoded message with length header
+ */
+const encode_message = (data) => {
+  // NOTE: Use compatible MessagePack options to avoid parsing issues.
+  const messagepack_data = encode_messagepack(data, {
+    useFloat32: false,
+    int64AsType: 'number',
+    mapsAsObjects: true
+  });
+  const length_buffer = Buffer.allocUnsafe(4);
+  length_buffer.writeUInt32BE(messagepack_data.length, 0);
+  return Buffer.concat([length_buffer, messagepack_data]);
+};
+
+/**
+ * Creates a message parser for handling TCP stream data with length-prefixed MessagePack messages.
+ * @returns {Object} Parser object with parse_messages and reset methods
+ */
+const create_message_parser = () => {
+  let buffer = Buffer.alloc(0);
+  let expected_length = null;
+  
+  /**
+   * Parses incoming data and extracts complete messages.
+   * @param {Buffer} data - Raw TCP data
+   * @returns {Array} Array of decoded messages
+   * @throws {Error} When message format is invalid
+   */
+  const parse_messages = (data) => {
+    buffer = Buffer.concat([buffer, data]);
+    const messages = [];
+    
+    while (buffer.length > 0) {
+      if (expected_length === null) {
+        if (buffer.length < 4) {
+          break;
+        }
+        
+        expected_length = buffer.readUInt32BE(0);
+        buffer = buffer.slice(4);
+      }
+      
+      if (buffer.length < expected_length) {
+        break;
+      }
+      
+      const message_data = buffer.slice(0, expected_length);
+      buffer = buffer.slice(expected_length);
+      expected_length = null;
+      
+      try {
+        // NOTE: Use compatible MessagePack options to avoid parsing issues.
+        const decoded_message = decode_messagepack(message_data, {
+          useFloat32: false,
+          int64AsType: 'number',
+          mapsAsObjects: true
+        });
+        messages.push(decoded_message);
+      } catch (error) {
+        throw new Error(`Invalid message format: ${error.message}`);
+      }
+    }
+    
+    return messages;
+  };
+  
+  /**
+   * Resets the parser state, clearing buffers and expected length.
+   */
+  const reset = () => {
+    buffer = Buffer.alloc(0);
+    expected_length = null;
+  };
+  
+  return {
+    parse_messages,
+    reset
+  };
+};
+
+
+/**
+ * @typedef {Object} ClientOptions
+ * @property {string} [host='localhost'] - Server hostname
+ * @property {number} [port=1983] - Server port
+ * @property {string} [password] - Authentication password (required for authenticated connections)
+ * @property {number} [timeout=5000] - Request timeout in milliseconds
+ * @property {boolean} [reconnect=true] - Enable automatic reconnection
+ * @property {number} [max_reconnect_attempts=10] - Maximum reconnection attempts
+ * @property {number} [reconnect_delay=1000] - Initial reconnection delay in milliseconds
+ * @property {boolean} [auto_connect=true] - Automatically connect on instantiation
+ */
+
+/**
+ * JoystickDB TCP client for connecting to JoystickDB server.
+ * @extends EventEmitter
+ * @fires JoystickDBClient#connect
+ * @fires JoystickDBClient#authenticated
+ * @fires JoystickDBClient#error
+ * @fires JoystickDBClient#disconnect
+ * @fires JoystickDBClient#reconnecting
+ * @fires JoystickDBClient#response
+ */
+class JoystickDBClient extends EventEmitter {
+  /**
+   * Creates a new JoystickDB client instance.
+   * @param {ClientOptions} [options={}] - Client configuration options
+   */
+  constructor(options = {}) {
+    super();
+    
+    this.host = options.host || 'localhost';
+    this.port = options.port || 1983;
+    this.password = options.password || null;
+    this.timeout = options.timeout || 5000;
+    this.reconnect = options.reconnect !== false;
+    this.max_reconnect_attempts = options.max_reconnect_attempts || 10;
+    this.reconnect_delay = options.reconnect_delay || 1000;
+    
+    this.socket = null;
+    this.message_parser = null;
+    this.is_connected = false;
+    this.is_authenticated = false;
+    this.is_connecting = false;
+    this.reconnect_attempts = 0;
+    this.reconnect_timeout = null;
+    
+    this.pending_requests = new Map();
+    this.request_id_counter = 0;
+    this.request_queue = [];
+    
+    if (options.auto_connect !== false) {
+      this.connect();
+    }
+  }
+  
+  /**
+   * Establishes connection to the JoystickDB server.
+   */
+  connect() {
+    if (this.is_connecting || this.is_connected) {
+      return;
+    }
+    
+    this.is_connecting = true;
+    this.socket = new net.Socket();
+    this.message_parser = create_message_parser();
+    
+    const connection_timeout = setTimeout(() => {
+      if (this.socket && !this.is_connected) {
+        this.socket.destroy();
+        this.handle_connection_error(new Error('Connection timeout'));
+      }
+    }, this.timeout);
+    
+    this.socket.connect(this.port, this.host, () => {
+      clearTimeout(connection_timeout);
+      this.is_connected = true;
+      this.is_connecting = false;
+      this.reconnect_attempts = 0;
+      
+      this.emit('connect');
+      
+      if (this.password) {
+        this.authenticate();
+      }
+    });
+    
+    this.socket.on('data', (data) => {
+      try {
+        const messages = this.message_parser.parse_messages(data);
+        
+        for (const message of messages) {
+          this.handle_message(message);
+        }
+      } catch (error) {
+        this.emit('error', new Error(`Message parsing failed: ${error.message}`));
+      }
+    });
+    
+    this.socket.on('error', (error) => {
+      clearTimeout(connection_timeout);
+      this.handle_connection_error(error);
+    });
+    
+    this.socket.on('close', () => {
+      clearTimeout(connection_timeout);
+      this.handle_disconnect();
+    });
+  }
+  
+  /**
+   * Authenticates with the server using provided credentials.
+   */
+  async authenticate() {
+    if (!this.password) {
+      this.emit('error', new Error('Password required for authentication. Provide password in client options: joystickdb.client({ password: "your_password" })'));
+      this.disconnect();
+      return;
+    }
+    
+    try {
+      const result = await this.send_request('authentication', {
+        password: this.password
+      });
+      
+      if (result.ok === 1) {
+        this.is_authenticated = true;
+        this.emit('authenticated');
+        this.process_request_queue();
+      } else {
+        throw new Error('Authentication failed');
+      }
+    } catch (error) {
+      this.emit('error', new Error(`Authentication error: ${error.message}`));
+      this.disconnect();
+    }
+  }
+  
+  /**
+   * Handles incoming messages from the server.
+   * @param {Object} message - Decoded message from server
+   */
+  handle_message(message) {
+    if (this.pending_requests.size > 0) {
+      const [request_id, { resolve, reject, timeout }] = this.pending_requests.entries().next().value;
+      clearTimeout(timeout);
+      this.pending_requests.delete(request_id);
+      
+      if (message.ok === 1 || message.ok === true) {
+        resolve(message);
+      } else if (message.ok === 0 || message.ok === false) {
+        const error_message = typeof message.error === 'string' ? message.error : JSON.stringify(message.error) || 'Operation failed';
+        reject(new Error(error_message));
+      } else {
+        resolve(message);
+      }
+    } else {
+      this.emit('response', message);
+    }
+  }
+  
+  /**
+   * Handles connection errors and manages reconnection logic.
+   * @param {Error} error - The connection error
+   */
+  handle_connection_error(error) {
+    this.is_connecting = false;
+    this.is_connected = false;
+    this.is_authenticated = false;
+    
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      this.socket.destroy();
+      this.socket = null;
+    }
+    
+    if (this.message_parser) {
+      this.message_parser.reset();
+    }
+    
+    // NOTE: Reject all pending requests.
+    for (const [request_id, { reject, timeout }] of this.pending_requests) {
+      clearTimeout(timeout);
+      reject(new Error('Connection lost'));
+    }
+    this.pending_requests.clear();
+    
+    this.emit('error', error);
+    
+    if (this.reconnect && this.reconnect_attempts < this.max_reconnect_attempts) {
+      this.schedule_reconnect();
+    } else {
+      this.emit('disconnect');
+    }
+  }
+  
+  /**
+   * Handles disconnection events and manages reconnection logic.
+   */
+  handle_disconnect() {
+    this.is_connected = false;
+    this.is_authenticated = false;
+    this.is_connecting = false;
+    
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      this.socket = null;
+    }
+    
+    if (this.message_parser) {
+      this.message_parser.reset();
+    }
+    
+    // NOTE: Reject all pending requests.
+    for (const [request_id, { reject, timeout }] of this.pending_requests) {
+      clearTimeout(timeout);
+      reject(new Error('Connection closed'));
+    }
+    this.pending_requests.clear();
+    
+    if (this.reconnect && this.reconnect_attempts < this.max_reconnect_attempts) {
+      this.schedule_reconnect();
+    } else {
+      this.emit('disconnect');
+    }
+  }
+  
+  /**
+   * Schedules a reconnection attempt with exponential backoff.
+   */
+  schedule_reconnect() {
+    this.reconnect_attempts++;
+    const delay = Math.min(
+      this.reconnect_delay * Math.pow(2, this.reconnect_attempts - 1),
+      30000
+    );
+    
+    this.emit('reconnecting', { attempt: this.reconnect_attempts, delay });
+    
+    this.reconnect_timeout = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+  
+  /**
+   * Sends a request to the server.
+   * @param {string} op - Operation name
+   * @param {Object} [data={}] - Request data
+   * @param {boolean} [use_queue=true] - Whether to queue request if not connected
+   * @returns {Promise<Object>} Server response
+   */
+  send_request(op, data = {}, use_queue = true) {
+    return new Promise((resolve, reject) => {
+      const request_id = ++this.request_id_counter;
+      const message = {
+        op,
+        data
+      };
+      
+      const request = {
+        message,
+        resolve,
+        reject,
+        request_id
+      };
+      
+      if (!this.is_connected || (op !== 'authentication' && op !== 'setup' && op !== 'ping' && !this.is_authenticated)) {
+        if (use_queue) {
+          this.request_queue.push(request);
+          return;
+        } else {
+          reject(new Error('Not connected or authenticated'));
+          return;
+        }
+      }
+      
+      this.send_request_now(request);
+    });
+  }
+  
+  /**
+   * Immediately sends a request to the server.
+   * @param {Object} request - Request object with message, resolve, reject, and request_id
+   */
+  send_request_now(request) {
+    const { message, resolve, reject, request_id } = request;
+    
+    const timeout = setTimeout(() => {
+      this.pending_requests.delete(request_id);
+      reject(new Error('Request timeout'));
+    }, this.timeout);
+    
+    this.pending_requests.set(request_id, { resolve, reject, timeout });
+    
+    try {
+      const encoded_message = encode_message(message);
+      this.socket.write(encoded_message);
+    } catch (error) {
+      clearTimeout(timeout);
+      this.pending_requests.delete(request_id);
+      reject(error);
+    }
+  }
+  
+  /**
+   * Processes queued requests after connection and authentication.
+   */
+  process_request_queue() {
+    while (this.request_queue.length > 0 && this.is_connected && this.is_authenticated) {
+      const request = this.request_queue.shift();
+      this.send_request_now(request);
+    }
+  }
+  
+  /**
+   * Disconnects from the server and disables reconnection.
+   */
+  disconnect() {
+    this.reconnect = false;
+    
+    if (this.reconnect_timeout) {
+      clearTimeout(this.reconnect_timeout);
+      this.reconnect_timeout = null;
+    }
+    
+    if (this.socket) {
+      this.socket.end();
+    }
+  }
+  
+  
+  
+  // NOTE: Backup Operations.
+  /**
+   * Triggers an immediate backup.
+   * @returns {Promise<Object>} Backup result
+   */
+  async backup_now() {
+    return this.send_request('admin', { admin_action: 'backup_now' });
+  }
+  
+  /**
+   * Lists all available backups.
+   * @returns {Promise<Object>} Backups list
+   */
+  async list_backups() {
+    return this.send_request('admin', { admin_action: 'list_backups' });
+  }
+  
+  /**
+   * Restores from a specific backup.
+   * @param {string} backup_name - Name of backup to restore
+   * @returns {Promise<Object>} Restore result
+   */
+  async restore_backup(backup_name) {
+    return this.send_request('admin', { 
+      admin_action: 'restore_backup', 
+      backup_name 
+    });
+  }
+  
+  // NOTE: Replication Operations.
+  /**
+   * Gets replication status and statistics.
+   * @returns {Promise<Object>} Replication status
+   */
+  async get_replication_status() {
+    return this.send_request('admin', { admin_action: 'get_replication_status' });
+  }
+
+  /**
+   * Adds a secondary node to replication.
+   * @param {Object} secondary - Secondary node configuration
+   * @param {string} secondary.id - Secondary node ID
+   * @param {string} secondary.ip - Secondary node IP address
+   * @param {number} secondary.port - Secondary node port
+   * @param {string} secondary.private_key - Base64 encoded private key
+   * @returns {Promise<Object>} Add secondary result
+   */
+  async add_secondary(secondary) {
+    return this.send_request('admin', { admin_action: 'add_secondary', ...secondary });
+  }
+
+  /**
+   * Removes a secondary node from replication.
+   * @param {string} secondary_id - Secondary node ID to remove
+   * @returns {Promise<Object>} Remove secondary result
+   */
+  async remove_secondary(secondary_id) {
+    return this.send_request('admin', { admin_action: 'remove_secondary', secondary_id });
+  }
+
+  /**
+   * Forces synchronization with all secondary nodes.
+   * @returns {Promise<Object>} Sync result
+   */
+  async sync_secondaries() {
+    return this.send_request('admin', { admin_action: 'sync_secondaries' });
+  }
+
+  /**
+   * Gets health status of secondary nodes.
+   * @returns {Promise<Object>} Secondary health status
+   */
+  async get_secondary_health() {
+    return this.send_request('admin', { admin_action: 'get_secondary_health' });
+  }
+
+  /**
+   * Gets write forwarder status (for secondary nodes).
+   * @returns {Promise<Object>} Write forwarder status
+   */
+  async get_forwarder_status() {
+    return this.send_request('admin', { admin_action: 'get_forwarder_status' });
+  }
+  
+  // NOTE: Health and Utility Operations.
+  /**
+   * Pings the server to check connectivity.
+   * @returns {Promise<Object>} Ping result
+   */
+  async ping() {
+    return this.send_request('ping', {}, false);
+  }
+  
+  /**
+   * Reloads server configuration.
+   * @returns {Promise<Object>} Reload result
+   */
+  async reload() {
+    return this.send_request('reload');
+  }
+  
+  // NOTE: Auto-Indexing Operations.
+  /**
+   * Gets automatic indexing statistics.
+   * @returns {Promise<Object>} Auto-indexing statistics
+   */
+  async get_auto_index_stats() {
+    return this.send_request('admin', { admin_action: 'get_auto_index_stats' });
+  }
+  
+  
+  // NOTE: Setup Operation.
+  /**
+   * Performs initial server setup.
+   * @returns {Promise<Object>} Setup result
+   */
+  async setup() {
+    const result = await this.send_request('setup', {}, false);
+    
+    // NOTE: Display setup instructions to user.
+    if (result.data && result.data.instructions) {
+      console.log(result.data.instructions);
+    }
+    
+    return result;
+  }
+  
+  // NOTE: Database Interface.
+  /**
+   * Returns a database interface for method chaining operations.
+   * @param {string} database_name - Database name
+   * @returns {Database} Database interface instance
+   */
+  db(database_name) {
+    return new Database(this, database_name);
+  }
+  
+  
+  // NOTE: Multi-Database Admin Operations.
+  /**
+   * Lists all databases on the server.
+   * @returns {Promise<Object>} Databases list
+   */
+  async list_databases() {
+    return this.send_request('admin', { admin_action: 'list_databases' });
+  }
+}
+
+/**
+ * Collection interface for method chaining operations.
+ * Provides a fluent API for database operations on a specific collection.
+ */
+class Collection {
+  /**
+   * Creates a new Collection instance.
+   * @param {JoystickDBClient} client - The client instance
+   * @param {string} database_name - Name of the database
+   * @param {string} collection_name - Name of the collection
+   */
+  constructor(client, database_name, collection_name) {
+    this.client = client;
+    this.database_name = database_name;
+    this.collection_name = collection_name;
+  }
+  
+  /**
+   * Inserts a single document into the collection.
+   * @param {Object} document - Document to insert
+   * @param {Object} [options={}] - Insert options
+   * @returns {Promise<Object>} Insert result
+   */
+  async insert_one(document, options = {}) {
+    return this.client.send_request('insert_one', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      document, 
+      options 
+    });
+  }
+  
+  /**
+   * Finds a single document in the collection.
+   * @param {Object} [filter={}] - Query filter
+   * @param {Object} [options={}] - Find options
+   * @returns {Promise<Object|null>} Found document or null
+   */
+  async find_one(filter = {}, options = {}) {
+    const result = await this.client.send_request('find_one', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      filter, 
+      options 
+    });
+    return result.document;
+  }
+  
+  /**
+   * Finds multiple documents in the collection.
+   * @param {Object} [filter={}] - Query filter
+   * @param {Object} [options={}] - Find options
+   * @returns {Promise<Array>} Array of found documents
+   */
+  async find(filter = {}, options = {}) {
+    const result = await this.client.send_request('find', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      filter, 
+      options 
+    });
+    return result.documents || [];
+  }
+  
+  /**
+   * Updates a single document in the collection.
+   * @param {Object} filter - Query filter to match document
+   * @param {Object} update - Update operations
+   * @param {Object} [options={}] - Update options
+   * @returns {Promise<Object>} Update result
+   */
+  async update_one(filter, update, options = {}) {
+    return this.client.send_request('update_one', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      filter, 
+      update, 
+      options 
+    });
+  }
+  
+  /**
+   * Deletes a single document from the collection.
+   * @param {Object} filter - Query filter to match document
+   * @param {Object} [options={}] - Delete options
+   * @returns {Promise<Object>} Delete result
+   */
+  async delete_one(filter, options = {}) {
+    return this.client.send_request('delete_one', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      filter, 
+      options 
+    });
+  }
+  
+  /**
+   * Performs multiple write operations in a single request.
+   * @param {Array<Object>} operations - Array of write operations
+   * @param {Object} [options={}] - Bulk write options
+   * @returns {Promise<Object>} Bulk write result
+   */
+  async bulk_write(operations, options = {}) {
+    return this.client.send_request('bulk_write', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      operations, 
+      options 
+    });
+  }
+  
+  /**
+   * Creates an index on a collection field.
+   * @param {string} field - Field name to index
+   * @param {Object} [options={}] - Index options
+   * @returns {Promise<Object>} Index creation result
+   */
+  async create_index(field, options = {}) {
+    return this.client.send_request('create_index', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      field, 
+      options 
+    });
+  }
+  
+  /**
+   * Creates or updates an index on a collection field (upsert operation).
+   * @param {string} field - Field name to index
+   * @param {Object} [options={}] - Index options
+   * @returns {Promise<Object>} Index upsert result
+   */
+  async upsert_index(field, options = {}) {
+    return this.client.send_request('create_index', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      field, 
+      options: { ...options, upsert: true } 
+    });
+  }
+  
+  /**
+   * Drops an index from a collection field.
+   * @param {string} field - Field name of index to drop
+   * @returns {Promise<Object>} Index drop result
+   */
+  async drop_index(field) {
+    return this.client.send_request('drop_index', { 
+      database: this.database_name,
+      collection: this.collection_name, 
+      field 
+    });
+  }
+  
+  /**
+   * Gets all indexes for the collection.
+   * @returns {Promise<Object>} Indexes information
+   */
+  async get_indexes() {
+    return this.client.send_request('get_indexes', { 
+      database: this.database_name,
+      collection: this.collection_name 
+    });
+  }
+}
+
+// NOTE: Add Collection class as static property for Database class access.
+JoystickDBClient.Collection = Collection;
+
+/**
+ * JoystickDB client factory and utilities.
+ * @namespace
+ */
+const joystickdb = {
+  /**
+   * Creates a new JoystickDB client instance.
+   * @param {ClientOptions} options - Client configuration options
+   * @returns {JoystickDBClient} New client instance
+   */
+  client: (options) => new JoystickDBClient(options)
+};
+
+export default joystickdb;