@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.3

package/src/servers/BaseRpcServer.js

@@ -0,0 +1,404 @@
+import { EventEmitter } from 'events';
+import { createComponentLogger } from '../utils/logger.js';
+
+/**
+ * Base class for all RPC servers
+ *
+ * Provides common functionality and defines the interface that all
+ * concrete RPC servers must implement.
+ */
+export class BaseRpcServer extends EventEmitter {
+  /**
+   * Create a new RPC server instance
+   *
+   * @param {Object} options - Configuration options
+   * @param {string} options.protocol - The protocol this server handles
+   * @param {number} options.timeoutMs - Request timeout in milliseconds
+   */
+  constructor(options = {}) {
+    super();
+
+    this.protocol = options.protocol || 'unknown';
+    this.timeoutMs = options.timeoutMs || 15000;
+    this.isServing = false;
+    this.ability = null;
+
+    // Request tracking for timeouts and correlation
+    this.pendingRequests = new Map();
+    this.requestCounter = 0;
+
+    this.logger = createComponentLogger('BaseRpcServer');
+    this.logger.lifecycle(
+      'constructor',
+      `BaseRpcServer created with protocol: ${this.protocol}`
+    );
+    this.logger.trace('constructor', `Timeout: ${this.timeoutMs}ms`);
+  }
+
+  /**
+   * Start serving the given ability
+   *
+   * This is the main entry point that concrete servers must implement.
+   * It should set up the transport, handle incoming requests, and keep
+   * the server running until explicitly stopped.
+   *
+   * @param {KadiAbility} ability - The ability instance to serve
+   * @returns {Promise<void>} - Resolves when server stops
+   */
+  async serve(ability) {
+    this.logger.lifecycle('serve', 'Starting base server serve method');
+    this.logger.info('serve', `Ability: ${ability?.name || 'unnamed'}`);
+    throw new Error('BaseRpcServer.serve() must be implemented by subclasses');
+  }
+
+  /**
+   * Publish an event to connected clients/agents
+   *
+   * This method publishes fire-and-forget event notifications that flow
+   * from the ability to connected agents. The concrete implementation
+   * depends on the transport protocol:
+   *
+   * - Stdio: Sends JSON-RPC notification with __kadi_event method
+   * - Broker: Sends kadi.event message via WebSocket
+   * - Others: Implementation-specific
+   *
+   * Events are best-effort delivery with no acknowledgment expected.
+   * If the transport is disconnected, events may be dropped silently.
+   *
+   * @param {string} eventName - Name of the event to publish
+   * @param {any} data - Event data payload (must be JSON-serializable)
+   *
+   * @abstract
+   * @throws {Error} If not implemented by subclass
+   */
+  async publishEvent(eventName, data) {
+    this.logger.warn(
+      'publishEvent',
+      `BaseRpcServer.publishEvent() not implemented for protocol: ${this.protocol}`
+    );
+    throw new Error(
+      `publishEvent() must be implemented by ${this.protocol} RPC server`
+    );
+  }
+
+  /**
+   * Handle an incoming request
+   *
+   * This method contains the core request processing logic that is
+   * shared across all protocols. Concrete servers call this method
+   * after parsing their protocol-specific request format.
+   *
+   * @param {Object} request - Parsed request object
+   * @param {string|number} request.id - Request ID (may be null for notifications)
+   * @param {string} request.method - Method name to call
+   * @param {Object} request.params - Method parameters
+   * @returns {Object|null} - Response object, or null for notifications
+   */
+  async handleRequest(request) {
+    const { id, method, params = {} } = request;
+
+    this.logger.request(id || 'notification', method, `Handling ${method}`);
+    this.logger.trace('request', `Params: ${JSON.stringify(params)}`);
+
+    this.emit('request', { id, method, params });
+
+    // Handle notifications (no response expected)
+    if (id === null || id === undefined) {
+      this.logger.trace('notification', `Processing notification: ${method}`);
+      try {
+        await this._executeMethod(method, params);
+
+        this.logger.trace('notification', `Notification ${method} completed`);
+
+        this.emit('response', { id, result: null });
+        return null; // No response for notifications
+      } catch (error) {
+        this.emit('response', { id, error: error.message });
+        // Still return null - notifications don't send error responses
+        return null;
+      }
+    }
+
+    // Handle regular requests (response expected)
+    try {
+      const result = await this._executeMethod(method, params);
+      this.logger.response(id, 'success', `Method ${method} completed`);
+
+      const response = this.createSuccessResponse(id, result);
+      this.emit('response', { id, result });
+      return response;
+    } catch (error) {
+      this.logger.response(
+        id,
+        'error',
+        `Method ${method} failed: ${error.message}`
+      );
+      const response = this.createErrorResponse(id, -32603, error.message, {
+        stack: error.stack,
+        method
+      });
+      this.emit('response', { id, error: response.error });
+      return response;
+    }
+  }
+
+  /**
+   * Execute a method on the ability
+   *
+   * @param {string} method - Method name
+   * @param {Object} params - Method parameters
+   * @returns {Promise<any>} - Method result
+   * @private
+   */
+  async _executeMethod(method, params) {
+    this.logger.methodCall('_executeMethod', `Executing method: ${method}`);
+
+    if (!this.ability) {
+      this.logger.error('execute', 'No ability instance available');
+      throw new Error('No ability instance available');
+    }
+
+    // Check for built-in methods first
+    if (method === '__kadi_init') {
+      this.logger.trace('builtin', 'Executing __kadi_init');
+      return this._handleInit(params);
+    }
+
+    if (method === '__kadi_discover') {
+      this.logger.trace('builtin', 'Executing __kadi_discover');
+      return this._handleDiscover(params);
+    }
+
+    // Look up the method handler
+    const handler = this.ability.getMethodHandler(method);
+    if (!handler) {
+      this.logger.error('execute', `Method not found: ${method}`);
+      throw new Error(`Method not found: ${method}`);
+    }
+
+    this.logger.trace(
+      'execute',
+      `Found handler for ${method}, executing with timeout ${this.timeoutMs}ms`
+    );
+
+    // Execute the handler with timeout
+    return await this._executeWithTimeout(handler, params);
+  }
+
+  /**
+   * Execute a handler with timeout protection
+   *
+   * @param {Function} handler - Method handler function
+   * @param {Object} params - Parameters to pass to handler
+   * @returns {Promise<any>} - Handler result
+   * @private
+   */
+  async _executeWithTimeout(handler, params) {
+    this.logger.trace(
+      'timeout',
+      `Starting execution with ${this.timeoutMs}ms timeout`
+    );
+    return new Promise(async (resolve, reject) => {
+      // Set up timeout
+      const timeoutId = setTimeout(() => {
+        this.logger.error(
+          'timeout',
+          `Method execution timed out after ${this.timeoutMs}ms`
+        );
+        reject(
+          new Error(`Method execution timed out after ${this.timeoutMs}ms`)
+        );
+      }, this.timeoutMs);
+
+      try {
+        const result = await handler(params);
+        clearTimeout(timeoutId);
+        this.logger.trace('timeout', 'Method completed within timeout');
+        resolve(result);
+      } catch (error) {
+        clearTimeout(timeoutId);
+
+        this.logger.error('timeout', `Method failed: ${error.message}`);
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Handle built-in __kadi_init method
+   *
+   * @param {Object} params - Init parameters
+   * @returns {Object} - Init response
+   * @private
+   */
+  _handleInit(params) {
+    this.logger.methodCall('_handleInit', 'Processing init request');
+
+    const response = {
+      name: this.ability.name,
+      version: this.ability.version,
+      description: this.ability.description,
+      protocol: this.protocol,
+      functions: this._getFunctionDescriptions()
+    };
+
+    this.logger.success(
+      '_handleInit',
+      `Init complete for ${this.ability.name}@${this.ability.version}`
+    );
+    return response;
+  }
+
+  /**
+   * Handle built-in __kadi_discover method
+   *
+   * @param {Object} params - Discover parameters
+   * @returns {Object} - Discover response
+   * @private
+   */
+  _handleDiscover(params) {
+    this.logger.methodCall('_handleDiscover', 'Processing discover request');
+
+    const functions = this._getFunctionDescriptions();
+
+    this.logger.success(
+      '_handleDiscover',
+      `Discovered ${Object.keys(functions).length} functions`
+    );
+
+    return { functions };
+  }
+
+  /**
+   * Get function descriptions for discovery
+   *
+   * @returns {Object} - Map of function names to descriptions
+   * @private
+   */
+  _getFunctionDescriptions() {
+    this.logger.trace('discovery', 'Building function descriptions');
+
+    const functions = {};
+
+    for (const methodName of this.ability.getMethodNames()) {
+      const schema = this.ability.getMethodSchema(methodName);
+
+      functions[methodName] = {
+        description: schema?.description || `Handler for ${methodName}`,
+        inputSchema: schema?.inputSchema || { type: 'object' },
+        outputSchema: schema?.outputSchema || { type: 'object' }
+      };
+    }
+
+    this.logger.trace(
+      'discovery',
+      `Built descriptions for ${Object.keys(functions).length} functions`
+    );
+
+    return functions;
+  }
+
+  /**
+   * Create a JSON-RPC success response
+   *
+   * @param {string|number} id - Request ID
+   * @param {any} result - Result value
+   * @returns {Object} - JSON-RPC response
+   */
+  createSuccessResponse(id, result) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result
+    };
+  }
+
+  /**
+   * Create a JSON-RPC error response
+   *
+   * @param {string|number} id - Request ID
+   * @param {number} code - Error code
+   * @param {string} message - Error message
+   * @param {any} data - Additional error data
+   * @returns {Object} - JSON-RPC error response
+   */
+  createErrorResponse(id, code, message, data = null) {
+    const error = { code, message };
+    if (data !== null) {
+      error.data = data;
+    }
+
+    return {
+      jsonrpc: '2.0',
+      id,
+      error
+    };
+  }
+
+  /**
+   * Common error responses
+   */
+  createMethodNotFoundResponse(id, method) {
+    this.logger.warn('response', `Method not found: ${method}`);
+    return this.createErrorResponse(id, -32601, `Method not found: ${method}`);
+  }
+
+  createParseErrorResponse(id) {
+    this.logger.error('response', 'Parse error in request');
+    return this.createErrorResponse(id, -32700, 'Parse error');
+  }
+
+  createInvalidRequestResponse(id) {
+    this.logger.error('response', 'Invalid request format');
+    return this.createErrorResponse(id, -32600, 'Invalid Request');
+  }
+
+  createInternalErrorResponse(id, message, data) {
+    this.logger.error('response', `Internal error: ${message || 'Unknown'}`);
+    return this.createErrorResponse(
+      id,
+      -32603,
+      message || 'Internal error',
+      data
+    );
+  }
+
+  /**
+   * Gracefully shutdown the server
+   *
+   * @param {string} reason - Reason for shutdown
+   */
+  async shutdown(reason = 'unknown') {
+    this.isServing = false;
+    this.emit('stop', { reason });
+
+    // Cancel any pending requests
+    for (const [requestId, { reject }] of this.pendingRequests) {
+      reject(new Error(`Server shutdown: ${reason}`));
+    }
+    this.pendingRequests.clear();
+
+    // Give a moment for cleanup
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  /**
+   * Log helper that respects stdio mode
+   *
+   * @param {...any} args - Arguments to log
+   */
+  log(...args) {
+    this.logger.info('general', args.join(' '));
+  }
+
+  /**
+   * Error log helper
+   *
+   * @param {...any} args - Arguments to log
+   */
+  logError(...args) {
+    this.logger.error('general', args.join(' '));
+  }
+}
+
+export default BaseRpcServer;