@comake/skl-js-engine 1.3.8 → 1.3.10

package/src/JsExecutor/transport/stdio/ChildStdioTransport.ts

@@ -0,0 +1,251 @@
+/* eslint-disable indent */
+import { EventEmitter } from 'node:events';
+import type { ClientTransport } from '../../jsonRpc/JsonRpcClient';
+import { JsonRpcClient } from '../../jsonRpc/JsonRpcClient';
+import { JsonRpcServer } from '../../jsonRpc/JsonRpcServer';
+import { isResponse, MessageBuffer } from '../utils/MessageUtils';
+
+/**
+ * Custom logger that outputs to stderr to avoid contaminating stdout JSON-RPC channel
+ */
+class ChildProcessLogger {
+  private readonly name?: string;
+  private metadata: Record<string, any> = {};
+
+  public setMetadata(metadata: Record<string, any>): void {
+    this.metadata = { ...this.metadata, ...metadata };
+  }
+
+  public log(message: string, data?: any): void {
+    const logEntry = {
+      message,
+      metadata: this.metadata,
+      ...data && { data }
+    };
+    // Use stderr to avoid contaminating stdout JSON-RPC channel
+    process.stderr.write(`${message} ${JSON.stringify(logEntry.metadata)} ${data ? JSON.stringify(data) : ''}\n`);
+  }
+
+  public error(message: string, error?: Error): void {
+    const logEntry = {
+      level: 'error',
+      message,
+      metadata: this.metadata,
+      ...error && { error: error.message, stack: error.stack }
+    };
+    process.stderr.write(`ERROR: ${JSON.stringify(logEntry)}\n`);
+  }
+}
+
+/**
+ * Bidirectional StdioTransport for child processes
+ * This class handles both server (receiving requests) and client (sending requests) functionality
+ * over a single stdio channel with proper message routing.
+ *
+ * Usage in child process:
+ * ```typescript
+ * const transport = new ChildStdioTransport();
+ *
+ * // Register methods that parent can call
+ * transport.registerMethod('ping', async () => 'pong');
+ *
+ * // Make requests to parent
+ * const result = await transport.request('getTime');
+ * ```
+ */
+export class ChildStdioTransport extends EventEmitter {
+  private readonly server: JsonRpcServer;
+  private readonly client: JsonRpcClient;
+  private readonly logger = new ChildProcessLogger();
+  private readonly messageBuffer = new MessageBuffer();
+  private name?: string;
+  private initialized = false;
+
+  public constructor() {
+    super();
+    this.server = new JsonRpcServer({
+      requestTimeout: 60 * 60 * 1000
+    });
+    this.client = new JsonRpcClient({
+      defaultTimeout: 60 * 60 * 1000
+    });
+
+    // Set up the client transport that routes through our stdio
+    const clientTransport: ClientTransport = {
+      send: async(message: string): Promise<void> => {
+        this.sendMessage(message);
+      },
+      onMessage(): void {
+        // The message routing will handle client responses automatically
+      },
+      async close(): Promise<void> {
+        // Nothing to close for stdio
+      }
+    };
+
+    this.client.setTransport(clientTransport);
+    this.setupEventHandlers();
+  }
+
+  /**
+   * Set a name for this transport (used in logging)
+   */
+  public setName(name: string): void {
+    this.name = name;
+    this.logger.setMetadata({ name, transport: 'ChildStdioTransport' });
+  }
+
+  /**
+   * Initialize the bidirectional transport
+   * This should be called once after setting up all methods
+   */
+  public async initialize(): Promise<void> {
+    if (this.initialized) {
+      throw new Error('Transport already initialized');
+    }
+
+    this.initialized = true;
+    this.setupStdioCommunication();
+    this.logger.log('Transport initialized');
+  }
+
+  /**
+   * Register a method that the parent can call
+   * @param method - Method name
+   * @param handler - Method handler function
+   */
+  public registerMethod<TParams = any, TResult = any>(
+    method: string,
+    handler: (params: TParams) => Promise<TResult> | TResult
+  ): void {
+    this.server.registerMethod(method, handler);
+  }
+
+  /**
+   * Send a request to the parent process
+   * @param method - Method name
+   * @param params - Method parameters
+   * @param options - Request options
+   * @returns Promise resolving to the response
+   */
+  public async request<TParams = any, TResult = any>(
+    method: string,
+    params?: TParams,
+    options?: { timeout?: number }
+  ): Promise<TResult> {
+    if (!this.initialized) {
+      throw new Error('Transport not initialized. Call initialize() first.');
+    }
+    return this.client.request<TParams, TResult>(method, params, options);
+  }
+
+  /**
+   * Send a notification to the parent process (no response expected)
+   * @param method - Method name
+   * @param params - Method parameters
+   */
+  public async notify<TParams = any>(method: string, params?: TParams): Promise<void> {
+    if (!this.initialized) {
+      throw new Error('Transport not initialized. Call initialize() first.');
+    }
+    return this.client.notify(method, params);
+  }
+
+  /**
+   * Get transport statistics
+   */
+  public getStats(): {
+    serverMethods: number;
+    pendingRequests: number;
+    initialized: boolean;
+  } {
+    return {
+      serverMethods: 0,
+      pendingRequests: this.client.getStats().pendingRequests,
+      initialized: this.initialized
+    };
+  }
+
+  /**
+   * Close the transport and cleanup resources
+   */
+  public async close(): Promise<void> {
+    await this.client.close();
+    this.initialized = false;
+    this.removeAllListeners();
+  }
+
+  /**
+   * Set up stdio communication handlers
+   */
+  private setupStdioCommunication(): void {
+    // Handle incoming data from parent
+    process.stdin.on('data', async(data: Buffer): Promise<void> => {
+      const messages = this.messageBuffer.addData(data.toString());
+
+      for (const messageData of messages) {
+        await this.handleIncomingMessage(messageData);
+      }
+    });
+
+    // Handle process termination gracefully
+    process.on('SIGTERM', (): void => {
+      this.close().finally((): void => process.exit(0));
+    });
+
+    process.on('SIGINT', (): void => {
+      this.close().finally((): void => process.exit(0));
+    });
+  }
+
+  /**
+   * Handle incoming message and route to appropriate handler
+   */
+  private async handleIncomingMessage(messageData: string): Promise<void> {
+    try {
+      const message = JSON.parse(messageData);
+
+      // Check if this is a response to our request (has 'result' or 'error' and 'id')
+      if (isResponse(message)) {
+        // This is a response to a request we made - route to client
+        this.logger.log(`Routing response to client: ${message.id}`);
+        await this.client.handleIncomingMessage(messageData);
+      } else {
+        // This is a request or notification for us - route to server
+        this.logger.log(`Routing request to server: ${message.method}`);
+        const response = await this.server.processMessage(messageData);
+        this.logger.log('Sending response to parent process', response);
+        // Only send response if there is one (requests get responses, notifications don't)
+        if (response) {
+          this.sendMessage(JSON.stringify(response));
+        }
+      }
+    } catch (error: unknown) {
+      process.stderr.write(`Error processing message: ${(error as Error).message}\n`);
+      this.emit('error', error);
+    }
+  }
+
+  /**
+   * Send a message to the parent process
+   */
+  private sendMessage(message: string): void {
+    this.logger.log(`Sending: ${message}`);
+    process.stdout.write(`${message}\n`);
+  }
+
+  /**
+   * Set up event handlers
+   */
+  private setupEventHandlers(): void {
+    this.server.on('error', (error: Error): void => {
+      this.logger.error('Server error', error);
+      this.emit('error', error);
+    });
+
+    this.client.on('error', (error: Error): void => {
+      this.logger.error('Client error', error);
+      this.emit('error', error);
+    });
+  }
+}

package/src/JsExecutor/transport/stdio/ParentStdioTransport.ts

@@ -0,0 +1,308 @@
+import { Logger } from '../../../logger';
+import type { ClientTransport } from '../../jsonRpc/JsonRpcClient';
+import { JsonRpcClient } from '../../jsonRpc/JsonRpcClient';
+import type { JsonRpcServer } from '../../jsonRpc/JsonRpcServer';
+import type { LogNotification, StatusRequest, StatusResponse } from '../../jsonRpc/types';
+import { STANDARD_METHODS } from '../../jsonRpc/types';
+import type { ExecutionOptions } from '../../types';
+import { BaseTransport } from '../base/BaseTransport';
+import { ProcessManager } from '../process/ProcessManager';
+import type { TransportConfig } from '../Transport';
+import { TransportStatus } from '../Transport';
+import { isResponse, MessageBuffer } from '../utils/MessageUtils';
+import { pollUntilSuccess } from '../utils/PollingUtils';
+
+/**
+ * Client transport implementation for stdio communication
+ */
+export class StdioClientTransport implements ClientTransport {
+  private messageHandler?: (message: string) => void;
+  private name?: string;
+  private readonly logger = Logger.getInstance();
+
+  public constructor(private readonly processManager: ProcessManager) {}
+
+  public setName(name: string): void {
+    this.name = name;
+    this.logger.setMetadata({ name, transport: 'StdioClientTransport' });
+  }
+
+  public async send(message: string): Promise<void> {
+    this.logger.log('Sending message', message);
+    this.processManager.write(`${message}\n`);
+  }
+
+  public onMessage(handler: (message: string) => void): void {
+    this.messageHandler = handler;
+    // Note: Message handling is done in the main ParentStdioTransport class
+    // This is here for interface compliance
+  }
+
+  public async close(): Promise<void> {
+    this.messageHandler = undefined;
+  }
+}
+
+/**
+ * StdioTransport implementation for parent process communication with child
+ * This is the parent-side transport that manages a child process
+ */
+export class ParentStdioTransport extends BaseTransport {
+  private readonly processManager = new ProcessManager();
+  private readonly server: JsonRpcServer;
+  private readonly client: JsonRpcClient;
+  private readonly clientTransport: StdioClientTransport;
+  private readonly executorScriptPath: string;
+  private readonly messageBuffer = new MessageBuffer();
+
+  public constructor(executorScriptPath: string, server: JsonRpcServer) {
+    super();
+    this.executorScriptPath = executorScriptPath;
+    this.server = server;
+    this.client = new JsonRpcClient({
+      // 1 hour
+      defaultTimeout: 60 * 60 * 1000
+    });
+    this.clientTransport = new StdioClientTransport(this.processManager);
+
+    this.setupServerMethods();
+    this.setupEventHandlers();
+  }
+
+  /**
+   * Initialize the transport connection
+   */
+  public async initialize(config?: TransportConfig, executionOptions?: ExecutionOptions): Promise<void> {
+    if (this.internalStatus !== TransportStatus.disconnected) {
+      throw new Error(`Cannot initialize transport in ${this.internalStatus} state`);
+    }
+
+    try {
+      this.setStatus(TransportStatus.connecting);
+
+      // Set up client transport
+      this.client.setTransport(this.clientTransport);
+
+      // Spawn the process
+      // Use spawnTimeout if provided, otherwise fall back to timeout or default
+      const spawnTimeout = config?.spawnTimeout ?? config?.timeout ?? 3000;
+      await this.processManager.spawn({
+        scriptPath: this.executorScriptPath,
+        executionOptions,
+        startupTimeout: spawnTimeout
+      });
+
+      // Set up process communication
+      this.setupProcessCommunication();
+
+      // Wait for process to be ready
+      // Use readyTimeout if provided, otherwise fall back to timeout or default
+      const readyTimeout = config?.readyTimeout ?? config?.timeout ?? 10000;
+      await this.waitForReady(readyTimeout);
+
+      this.setStatus(TransportStatus.connected);
+    } catch (error: unknown) {
+      this.setStatus(TransportStatus.error);
+      throw error;
+    }
+  }
+
+  /**
+   * Send a message through the transport
+   */
+  public async send<TRequest, TResponse>(message: TRequest): Promise<TResponse> {
+    if (!this.isReady()) {
+      throw new Error('Transport is not ready');
+    }
+
+    // Expect message to have method and params for direct RPC calls
+    const rpcMessage = message as any;
+    if (rpcMessage.method) {
+      return this.client.request(rpcMessage.method, rpcMessage.params);
+    }
+    throw new Error('Message must have a method property for RPC calls');
+  }
+
+  /**
+   * Make a direct RPC request to the child process
+   */
+  public async request<TParams = any, TResult = any>(
+    method: string,
+    params?: TParams,
+    options?: { timeout?: number; retries?: number }
+  ): Promise<TResult> {
+    if (!this.isReady()) {
+      throw new Error('Transport is not ready');
+    }
+    return this.client.request<TParams, TResult>(method, params, options);
+  }
+
+  /**
+   * Send a notification to the child process (no response expected)
+   */
+  public async notify<TParams = any>(method: string, params?: TParams): Promise<void> {
+    if (!this.isReady()) {
+      throw new Error('Transport is not ready');
+    }
+    return this.client.notify(method, params);
+  }
+
+  /**
+   * Close the transport connection
+   */
+  public async close(): Promise<void> {
+    if (this.internalStatus === TransportStatus.disconnected) {
+      return;
+    }
+
+    this.setStatus(TransportStatus.disconnected);
+
+    // Close JSON-RPC client
+    await this.client.close();
+
+    // Terminate child process
+    await this.processManager.terminate();
+  }
+
+  /**
+   * Check if the transport is ready for communication
+   */
+  public isReady(): boolean {
+    return this.internalStatus === TransportStatus.connected && this.processManager.isRunning();
+  }
+
+  /**
+   * Set up server methods for handling incoming requests from Deno process
+   */
+  private setupServerMethods(): void {
+    // Handle status requests
+    this.server.registerMethod<StatusRequest, StatusResponse>(STANDARD_METHODS.getStatus, async() => ({
+      status: 'ready',
+      uptime: process.uptime() * 1000,
+      memoryUsage: {
+        used: process.memoryUsage().heapUsed,
+        total: process.memoryUsage().heapTotal
+      }
+    }));
+
+    // Handle ping requests
+    this.server.registerMethod(STANDARD_METHODS.ping, async() => 'pong');
+
+    // Handle log notifications
+    this.server.registerMethod<LogNotification, void>(STANDARD_METHODS.log, async params => {
+      if (this.messageHandler) {
+        await this.messageHandler(params);
+      }
+    });
+  }
+
+  /**
+   * Set up event handlers
+   */
+  private setupEventHandlers(): void {
+    this.server.on('error', error => {
+      this.emit('error', error);
+    });
+
+    this.client.on('error', error => {
+      this.emit('error', error);
+    });
+
+    this.processManager.on('error', error => {
+      this.emit('error', error);
+    });
+
+    this.processManager.on('exit', (code, signal) => {
+      if (this.internalStatus === TransportStatus.connected) {
+        const error = new Error(`Process exited unexpectedly (code: ${code}, signal: ${signal})`);
+        this.setStatus(TransportStatus.error);
+        this.emit('error', error);
+      }
+    });
+  }
+
+  /**
+   * Set up process communication handlers
+   */
+  private setupProcessCommunication(): void {
+    // Handle stdout data (responses from Deno process)
+    this.processManager.on('stdout', (data: Buffer) => {
+      const messages = this.messageBuffer.addData(data.toString());
+
+      for (const messageData of messages) {
+        this.logger.log('Received message', messageData);
+        this.handleIncomingMessage(messageData).catch(error => {
+          this.emit('error', error);
+        });
+      }
+    });
+
+    // Handle stderr data (log messages and errors from Deno process)
+    this.processManager.on('stderr', (data: Buffer) => {
+      const stderrOutput = data.toString().trim();
+
+      // Only treat messages starting with "ERROR:" as actual errors
+      if (stderrOutput.startsWith('ERROR:')) {
+        this.emit('error', new Error(`Deno process error: ${stderrOutput}`));
+      } else {
+        // Log normal stderr output as debug information
+        this.logger.log('Child process log', stderrOutput);
+      }
+    });
+  }
+
+  /**
+   * Handle incoming message from Deno process with bidirectional routing
+   */
+  private async handleIncomingMessage(messageData: string): Promise<void> {
+    try {
+      const message = JSON.parse(messageData);
+
+      // Check if this is a response to our request (has 'result' or 'error' and 'id')
+      if (isResponse(message)) {
+        // This is a response to a request we made - route to client
+        this.logger.log('Routing response to parent client', { id: message.id });
+        await this.client.handleIncomingMessage(messageData);
+      } else {
+        // This is a request or notification for us - route to server
+        this.logger.log('Routing request to parent server', { method: message.method, id: message.id });
+        const response = await this.server.processMessage(messageData);
+        this.logger.log('Sending response to parent process', response);
+
+        // Only send response if there is one (requests get responses, notifications don't)
+        if (response) {
+          const responseData = `${JSON.stringify(response)}\n`;
+          this.processManager.write(responseData);
+        }
+      }
+    } catch (error: unknown) {
+      // Silently ignore invalid JSON messages (likely log output from child process)
+      if (error instanceof SyntaxError && error.message.includes('JSON')) {
+        this.logger.log('Ignoring invalid JSON message', { message: messageData });
+        return;
+      }
+
+      // Re-throw other types of errors
+      this.emit('error', new Error(`Failed to handle incoming message: ${(error as Error).message}`));
+    }
+  }
+
+  /**
+   * Wait for the process to be ready
+   */
+  private async waitForReady(timeout: number): Promise<void> {
+    // Use a reasonable ping timeout (1/4 of total timeout, min 500ms, max 2000ms)
+    const pingTimeout = Math.max(500, Math.min(2000, timeout / 4));
+
+    await pollUntilSuccess(
+      () => this.client.request(STANDARD_METHODS.ping, undefined, { timeout: pingTimeout }),
+      {
+        timeout,
+        interval: 100,
+        // Let process start before first ping
+        initialDelay: 100
+      },
+      'Transport initialization timed out'
+    );
+  }
+}

package/src/JsExecutor/transport/utils/MessageUtils.ts

@@ -0,0 +1,139 @@
+import type { JsonRpcResponse } from '../../jsonRpc/types';
+
+/**
+ * Safely parse a JSON message, returning undefined if parsing fails
+ * @param message - String message to parse
+ * @returns Parsed object or undefined if invalid JSON
+ */
+export function safeParse(message: string): any {
+  try {
+    return JSON.parse(message);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if a message is a JSON-RPC response (vs request/notification)
+ * @param message - Parsed message object
+ * @returns True if message is a response
+ */
+export function isResponse(message: any): boolean {
+  return message &&
+         typeof message === 'object' &&
+         ('result' in message || 'error' in message) &&
+         'id' in message &&
+         !('method' in message);
+}
+
+/**
+ * Check if a message is a JSON-RPC request
+ * @param message - Parsed message object
+ * @returns True if message is a request
+ */
+export function isRequest(message: any): boolean {
+  return message &&
+         typeof message === 'object' &&
+         'method' in message &&
+         'id' in message;
+}
+
+/**
+ * Check if a message is a JSON-RPC notification
+ * @param message - Parsed message object
+ * @returns True if message is a notification
+ */
+export function isNotification(message: any): boolean {
+  return message &&
+         typeof message === 'object' &&
+         'method' in message &&
+         !('id' in message);
+}
+
+/**
+ * Create a JSON-RPC error response
+ * @param id - Request ID
+ * @param code - Error code
+ * @param message - Error message
+ * @param data - Optional error data
+ * @returns JSON-RPC error response object
+ */
+export function createErrorResponse(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: any
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message,
+      ...data && { data }
+    }
+  };
+}
+
+/**
+ * Create a JSON-RPC success response
+ * @param id - Request ID
+ * @param result - Response result
+ * @returns JSON-RPC success response object
+ */
+export function createSuccessResponse(id: string | number, result: any): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result
+  };
+}
+
+/**
+ * Validate that a message is a valid JSON-RPC message
+ * @param message - Message to validate
+ * @returns True if valid JSON-RPC message
+ */
+export function isValidJsonRpc(message: any): boolean {
+  return message &&
+         typeof message === 'object' &&
+         message.jsonrpc === '2.0' &&
+         (isRequest(message) || isNotification(message) || isResponse(message));
+}
+
+/**
+ * Buffer manager for handling streaming message data
+ */
+export class MessageBuffer {
+  private buffer = '';
+
+  /**
+   * Add data to the buffer and extract complete messages
+   * @param data - Incoming data chunk
+   * @returns Array of complete message strings
+   */
+  public addData(data: string): string[] {
+    this.buffer += data;
+
+    // Process complete JSON messages (newline-delimited)
+    const lines = this.buffer.split('\n');
+    // Keep incomplete line in buffer
+    this.buffer = lines.pop() ?? '';
+
+    return lines.filter((line): string => line.trim());
+  }
+
+  /**
+   * Clear the buffer
+   */
+  public clear(): void {
+    this.buffer = '';
+  }
+
+  /**
+   * Get current buffer content (for debugging)
+   */
+  public getContent(): string {
+    return this.buffer;
+  }
+}