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

package/src/servers/StdioRpcServer.js

@@ -1,360 +0,0 @@
-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;