@comake/skl-js-engine/src/JsExecutor/jsonRpc/types.ts

Standard Knowledge Language Javascript Engine

/**
 * JSON-RPC 2.0 Protocol Types
 * Based on: https://www.jsonrpc.org/specification
 */

/**
 * JSON-RPC 2.0 version identifier
 */
export const JSONRPC_VERSION = '2.0' as const;

/**
 * JSON-RPC request/response identifier
 */
export type JsonRpcId = string | number | null;

/**
 * JSON-RPC parameters (can be object or array)
 */
export type JsonRpcParams = Record<string, any> | any[] | undefined;

/**
 * JSON-RPC Error codes (standard codes from spec)
 */
export enum JsonRpcErrorCode {
  parseError = -32700,
  invalidRequest = -32600,
  methodNotFound = -32601,
  invalidParams = -32602,
  internalError = -32603,
  // Server error range: -32000 to -32099
  serverErrorStart = -32099,
  serverErrorEnd = -32000,
}

/**
 * JSON-RPC Error object
 */
export interface JsonRpcError {
  code: JsonRpcErrorCode | number;
  message: string;
  data?: any;
}

/**
 * JSON-RPC Request object
 */
export interface JsonRpcRequest<TParams = JsonRpcParams> {
  jsonrpc: typeof JSONRPC_VERSION;
  method: string;
  params?: TParams;
  id: JsonRpcId;
}

/**
 * JSON-RPC Notification object (request without id)
 */
export interface JsonRpcNotification<TParams = JsonRpcParams> {
  jsonrpc: typeof JSONRPC_VERSION;
  method: string;
  params?: TParams;
}

/**
 * JSON-RPC Success Response object
 */
export interface JsonRpcSuccessResponse<TResult = any> {
  jsonrpc: typeof JSONRPC_VERSION;
  result: TResult;
  id: JsonRpcId;
}

/**
 * JSON-RPC Error Response object
 */
export interface JsonRpcErrorResponse {
  jsonrpc: typeof JSONRPC_VERSION;
  error: JsonRpcError;
  id: JsonRpcId;
}

/**
 * JSON-RPC Response object (success or error)
 */
export type JsonRpcResponse<TResult = any> =
  | JsonRpcSuccessResponse<TResult>
  | JsonRpcErrorResponse;

/**
 * JSON-RPC Message (request, notification, or response)
 */
export type JsonRpcMessage<TParams = JsonRpcParams, TResult = any> =
  | JsonRpcRequest<TParams>
  | JsonRpcNotification<TParams>
  | JsonRpcResponse<TResult>;

/**
 * Method handler function signature
 */
export type JsonRpcMethodHandler<TParams = JsonRpcParams, TResult = any> = (
  params: TParams,
  id?: JsonRpcId,
) => Promise<TResult> | TResult;

/**
 * Method registry for JSON-RPC handlers
 */
export type JsonRpcMethodRegistry = Record<string, JsonRpcMethodHandler>;

/**
 * JSON-RPC server configuration
 */
export interface JsonRpcServerConfig {
  /**
   * Maximum number of concurrent requests
   */
  maxConcurrentRequests?: number;

  /**
   * Request timeout in milliseconds
   */
  requestTimeout?: number;

  /**
   * Whether to validate JSON-RPC format strictly
   */
  strictValidation?: boolean;

  /**
   * Custom error handler
   */
  errorHandler?: (error: Error, request?: JsonRpcRequest) => JsonRpcError;
}

/**
 * JSON-RPC client configuration
 */
export interface JsonRpcClientConfig {
  /**
   * Default timeout for requests in milliseconds
   */
  defaultTimeout?: number;

  /**
   * Maximum number of retry attempts
   */
  maxRetries?: number;

  /**
   * Retry delay in milliseconds
   */
  retryDelay?: number;

  /**
   * Whether to generate sequential request IDs
   */
  sequentialIds?: boolean;
}

/**
 * Pending request tracking
 */
export interface PendingRequest<TResult = any> {
  id: JsonRpcId;
  method: string;
  timestamp: number;
  timeout?: number;
  resolve: (value: TResult) => void;
  reject: (error: Error) => void;
}

/**
 * JSON-RPC validation result
 */
export interface ValidationResult {
  valid: boolean;
  error?: JsonRpcError;
}

/**
 * Standard JSON-RPC method names for JSExecutor
 */
export const STANDARD_METHODS = {
  executeCode: 'executeCode',
  getStatus: 'getStatus',
  ping: 'ping',
  shutdown: 'shutdown',
  log: 'log',
  error: 'error'
} as const;

/**
 * JSExecutor specific request/response types
 */
export interface ExecuteCodeRequest {
  code: string;
  args: Record<string, any>;
  functionName: string;
  skdsEndpointUrl: string;
}

export interface ExecuteCodeResponse {
  success: boolean;
  result?: any;
  error?: {
    message: string;
    name?: string;
    stack?: string;
  };
  logs: string[];
  executionTime: number;
}

export interface StatusRequest {
  // Empty for now
}

export interface StatusResponse {
  status: 'ready' | 'busy' | 'error';
  uptime: number;
  memoryUsage?: {
    used: number;
    total: number;
  };
}

export interface LogNotification {
  level: 'info' | 'warn' | 'error' | 'debug';
  message: string;
  timestamp: number;
  data?: any;
}