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

package/src/servers/StdioRpcServer.js

@@ -0,0 +1,360 @@
+import { BaseRpcServer } from './BaseRpcServer.js';
+import {
+  StdioFrameReader,
+  StdioFrameWriter
+} from '../transport/IpcMessageBuilder.js';
+import { createComponentLogger } from '../utils/logger.js';
+/**
+ * RPC Server for stdio transport using LSP-style framing
+ *
+ * This server handles JSON-RPC requests over stdio using Language Server Protocol
+ * style framing (Content-Length headers + JSON body). It's designed for process-to-process
+ * communication where the parent process spawns this ability as a child process.
+ */
+export class StdioRpcServer extends BaseRpcServer {
+  /**
+   * Create a new StdioRpcServer instance
+   *
+   * @param {Object} options - Configuration options
+   * @param {number} options.maxBufferSize - Maximum buffer size for frame reader
+   * @param {Readable} options.stdin - Input stream (default: process.stdin)
+   * @param {Writable} options.stdout - Output stream (default: process.stdout)
+   */
+  constructor(options = {}) {
+    super({ ...options, protocol: 'stdio' });
+
+    this.frameReader = new StdioFrameReader(options.stdin || process.stdin, {
+      maxBufferSize: options.maxBufferSize || 8 * 1024 * 1024
+    });
+    this.frameWriter = new StdioFrameWriter(options.stdout || process.stdout);
+
+    this.logger = createComponentLogger('StdioRpcServer');
+    this.logger.lifecycle('constructor', 'StdioRpcServer initialized');
+    this.logger.trace(
+      'constructor',
+      `Max buffer size: ${options.maxBufferSize || 8 * 1024 * 1024} bytes`
+    );
+
+    this.ability = null;
+    this.resolve = null;
+    this.reject = null;
+  }
+
+  /**
+   * Start serving the ability over stdio
+   *
+   * @param {KadiAbility} ability - The ability instance to serve
+   * @returns {Promise<void>} - Promise that resolves when server stops
+   */
+  async serve(ability) {
+    if (this.isServing) {
+      this.logger.error('serve', 'StdioRpcServer is already serving');
+      throw new Error('StdioRpcServer is already serving');
+    }
+
+    this.ability = ability;
+    this.isServing = true;
+
+    this.logger.lifecycle(
+      'serve',
+      `Starting ${ability.name || 'unnamed ability'} on stdio`
+    );
+    this.logger.info(
+      'serve',
+      `Available methods: ${ability.getMethodNames().join(', ')}`
+    );
+    this.logger.trace('serve', 'Setting up frame reader and process handlers');
+
+    // Emit start event
+    this.emit('start', {
+      name: ability.name,
+      version: ability.version,
+      methods: ability.getMethodNames()
+    });
+
+    // Set up frame reading with message handling
+    this.frameReader.onMessage(async (frameResult) => {
+      if (!frameResult.success) {
+        this.logger.error('frame', `Frame corruption: ${frameResult.error}`);
+        this.logger.trace(
+          'frame',
+          `Corruption type: ${frameResult.corruption_type}, message: ${frameResult.message}`
+        );
+
+        // Emit error event but don't crash - frame corruption can be recovered
+        this.emit('error', new Error(`Frame corruption: ${frameResult.error}`));
+        return;
+      }
+
+      try {
+        this.logger.trace(
+          'request',
+          `Processing JSON-RPC request: ${frameResult.data?.method}`
+        );
+
+        // Process the JSON-RPC request
+        const response = await this.handleRequest(frameResult.data);
+
+        // Write response if it's not a notification
+        if (response !== null) {
+          this.logger.trace(
+            'response',
+            `Sending response for request ID: ${frameResult.data?.id}`
+          );
+
+          await this.frameWriter.write(response);
+        } else {
+          this.logger.trace(
+            'notification',
+            `Notification processed: ${frameResult.data?.method}`
+          );
+        }
+      } catch (error) {
+        this.logger.error(
+          'request',
+          `Fatal error processing request: ${error.message}`
+        );
+        this.logger.trace('request', `Error stack: ${error.stack}`);
+
+        this.logError('Fatal error processing request:', error);
+
+        // Try to send an error response if we can extract an ID
+        const requestId = frameResult.data?.id;
+        if (requestId !== undefined) {
+          try {
+            const errorResponse = this.createInternalErrorResponse(
+              requestId,
+              'Internal error',
+              { error: error.message }
+            );
+            await this.frameWriter.write(errorResponse);
+          } catch (writeError) {
+            this.logError('Failed to send error response:', writeError);
+          }
+        }
+
+        // Emit error event
+        this.emit('error', error);
+      }
+    });
+
+    // Handle process termination gracefully
+    const signalHandler = (signal) => {
+      this.logger.lifecycle(
+        'signal',
+        `Received ${signal}, shutting down gracefully`
+      );
+
+      this.log(`Received ${signal}, shutting down gracefully`);
+      this.shutdown(signal);
+    };
+
+    process.on('SIGINT', signalHandler);
+    process.on('SIGTERM', signalHandler);
+
+    // Keep the process alive and handle stdio events
+    return new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+
+      // Handle stdin end - parent process closed the pipe
+      process.stdin.on('end', () => {
+        this.logger.lifecycle('stdin', 'stdin closed, shutting down');
+        this.log('stdin closed, shutting down');
+        this.shutdown('stdin_end');
+      });
+
+      // Handle stdin errors
+      process.stdin.on('error', (error) => {
+        this.logger.error('stdin', `stdin error: ${error.message}`);
+        this.logError('stdin error:', error);
+        this.reject(error);
+      });
+
+      // Handle stdout errors (broken pipe, etc.)
+      process.stdout.on('error', (error) => {
+        this.logger.error('stdout', `stdout error: ${error.message}`);
+        this.logError('stdout error:', error);
+        this.reject(error);
+      });
+    });
+  }
+
+  /**
+   * Handle requests in stdio-native format
+   *
+   * This implementation applies stdio-specific validation and error handling.
+   * Stdio requests come as JSON-RPC over LSP framing and often need more
+   * human-readable error messages since they might be displayed to developers.
+   *
+   * @param {Object} request - The JSON-RPC request object
+   * @returns {Object|null} - JSON-RPC response or null for notifications
+   */
+  async handleRequest(request) {
+    this.logger.trace('validation', 'Validating JSON-RPC request format');
+
+    // Validate JSON-RPC format
+    if (!request || typeof request !== 'object') {
+      this.logger.warn('validation', 'Invalid request: not an object');
+      return this.createInvalidRequestResponse(null);
+    }
+
+    // Check for required jsonrpc field
+    if (request.jsonrpc !== '2.0') {
+      this.logger.warn(
+        'validation',
+        `Invalid JSON-RPC version: ${request.jsonrpc}`
+      );
+      return this.createInvalidRequestResponse(request.id || null);
+    }
+
+    // Check for required method field
+    if (typeof request.method !== 'string') {
+      this.logger.warn('validation', 'Invalid request: method is not a string');
+      return this.createInvalidRequestResponse(request.id || null);
+    }
+
+    // Validate params if present
+    if (
+      request.params !== undefined &&
+      typeof request.params !== 'object' &&
+      !Array.isArray(request.params)
+    ) {
+      this.logger.warn(
+        'validation',
+        'Invalid request: params is not an object or array'
+      );
+      return this.createInvalidRequestResponse(request.id || null);
+    }
+
+    this.logger.trace('validation', 'JSON-RPC request validation passed');
+
+    // Use base class request handling
+    return await super.handleRequest(request);
+  }
+
+  /**
+   * Gracefully shutdown the stdio server
+   *
+   * @param {string} reason - Reason for shutdown
+   */
+  async shutdown(reason = 'unknown') {
+    this.logger.lifecycle(
+      'shutdown',
+      `Shutting down stdio server, reason: ${reason}`
+    );
+    await super.shutdown(reason);
+
+    // Resolve the serve promise to allow clean exit
+    if (this.resolve) {
+      this.logger.trace('shutdown', 'Resolving serve promise for clean exit');
+      this.resolve();
+    }
+  }
+
+  /**
+   * Send a notification to the parent process
+   *
+   * This is useful for sending status updates or logs that don't require a response
+   *
+   * @param {string} method - Notification method name
+   * @param {Object} params - Notification parameters
+   */
+  async sendNotification(method, params = {}) {
+    this.logger.trace('notification', `Sending notification: ${method}`);
+
+    const notification = {
+      jsonrpc: '2.0',
+      method,
+      params
+    };
+
+    try {
+      await this.frameWriter.write(notification);
+      this.logger.trace(
+        'notification',
+        `Notification ${method} sent successfully`
+      );
+    } catch (error) {
+      this.logger.error(
+        'notification',
+        `Failed to send notification ${method}: ${error.message}`
+      );
+
+      this.logError('Failed to send notification:', error);
+    }
+  }
+
+  /**
+   * Publish an event to the parent process via stdio
+   *
+   * Events are sent as JSON-RPC notifications with the special method '__kadi_event'.
+   * The parent process (agent) will receive these and emit them on the ability's
+   * events EventEmitter.
+   *
+   * @param {string} eventName - Name of the event to publish
+   * @param {any} data - Event data payload (must be JSON-serializable)
+   */
+  async publishEvent(eventName, data = {}) {
+    this.logger.trace(
+      'publishEvent',
+      `Publishing event via stdio: ${eventName}`
+    );
+
+    try {
+      // Send as a JSON-RPC notification with special method name
+      // No 'id' field means it's fire-and-forget
+      const eventNotification = {
+        jsonrpc: '2.0',
+        method: '__kadi_event',
+        params: {
+          eventName,
+          data,
+          timestamp: Date.now() // Add timestamp for event ordering
+        }
+      };
+
+      await this.frameWriter.write(eventNotification);
+
+      this.logger.trace('publishEvent', `Event ${eventName} sent successfully`);
+    } catch (error) {
+      // Events are best-effort - log but don't throw
+      this.logger.warn(
+        'publishEvent',
+        `Failed to publish event ${eventName}: ${error.message}`
+      );
+    }
+  }
+
+  /**
+   * Send a status update notification
+   *
+   * @param {string} status - Status message
+   * @param {Object} data - Additional status data
+   */
+  async sendStatus(status, data = {}) {
+    await this.sendNotification('__kadi_status', { status, ...data });
+  }
+
+  /**
+   * Send a progress notification
+   *
+   * @param {number} current - Current progress value
+   * @param {number} total - Total progress value
+   * @param {string} message - Progress message
+   */
+  async sendProgress(current, total, message = '') {
+    this.logger.trace(
+      'progress',
+      `Sending progress: ${current}/${total} - ${message}`
+    );
+    await this.sendNotification('__kadi_progress', {
+      current,
+      total,
+      percentage: Math.round((current / total) * 100),
+      message
+    });
+  }
+}
+
+export default StdioRpcServer;