@x-oasis/async-call-rpc 0.1.38

package/src/protocol/AbstractChannelProtocol.ts

@@ -0,0 +1,343 @@
+import { Disposable } from '@x-oasis/disposable';
+import { Event } from '@x-oasis/emitter';
+import { Deferred } from '@x-oasis/deferred';
+import { generateRandomKey } from '@x-oasis/id';
+
+import {
+  SendingProps,
+  IMessageChannel,
+  ClientMiddleware,
+  SenderMiddleware,
+  RequestRawSequenceId,
+  PendingSendEntry,
+  AbstractChannelProtocolProps,
+} from '../types';
+import { runMiddlewares, sendRequest } from '../middlewares';
+import ReadBaseBuffer from '../buffer/ReadBaseBuffer';
+import WriteBaseBuffer from '../buffer/WriteBaseBuffer';
+import { BufferFactory } from '../buffer/BufferFactory';
+import { SerializationFormat } from '../buffer/SerializationFormat';
+import { resumeMiddlewares } from '../middlewares/utils';
+
+import { deserialize, serialize } from '../middlewares/buffer';
+import { handleResponse } from '../middlewares/handleResponse';
+import RPCService from '../endpoint/RPCService';
+import { prepareNormalData } from '../middlewares/prepareRequestData';
+import { updateSeqInfo } from '../middlewares/updateSeqInfo';
+import { normalizeMessageChannelRawMessage } from '../middlewares/normalize';
+import { handleRequest } from '../middlewares/handleRequest';
+
+abstract class AbstractChannelProtocol
+  extends Disposable
+  implements IMessageChannel
+{
+  private readonly _masterProcessName: string;
+
+  private _key: string;
+
+  private _service: RPCService;
+
+  private readonly _description: string;
+
+  private _seqId: RequestRawSequenceId = -1;
+
+  // decoder should comes first !!!!
+  protected _onMessageMiddleware: ClientMiddleware[] = [
+    normalizeMessageChannelRawMessage,
+    deserialize,
+    handleRequest,
+    handleResponse,
+  ];
+
+  private _senderMiddleware: SenderMiddleware[] = [
+    prepareNormalData,
+    updateSeqInfo,
+    serialize,
+    sendRequest,
+  ];
+
+  private _readBuffer: ReadBaseBuffer | null = null;
+
+  private _writeBuffer: WriteBaseBuffer | null = null;
+
+  private _serializationFormat: string;
+
+  private _isConnected = true;
+
+  /**
+   * 如果说channel存在的话，那么就是ongoing request
+   */
+  public ongoingRequests: Map<string, Deferred> = new Map();
+
+  /**
+   * 如果说channel不存在，那么请求就会暂时放到这个里面
+   */
+  public pendingSendEntries = new Set<PendingSendEntry>();
+
+  public requestEvents: Map<string, any> = new Map();
+
+  private onDidConnectedEvent = new Event({ name: 'on-did-connected' });
+
+  onDidConnected = this.onDidConnectedEvent.subscribe;
+
+  private onDidDisconnectedEvent = new Event({ name: 'on-did-disconnect' });
+
+  onDidDisconnected = this.onDidDisconnectedEvent.subscribe;
+
+  constructor(props?: AbstractChannelProtocolProps) {
+    super();
+    const {
+      description,
+      masterProcessName,
+      connected = true,
+      serializationFormat = SerializationFormat.JSON,
+      readBuffer,
+      writeBuffer,
+    } = props || {};
+
+    this._description = description;
+    this._isConnected = connected;
+    this._masterProcessName = masterProcessName;
+    this._serializationFormat = serializationFormat;
+
+    // 如果提供了自定义 buffer，直接使用
+    if (readBuffer) {
+      this._readBuffer = readBuffer;
+    }
+    if (writeBuffer) {
+      this._writeBuffer = writeBuffer;
+    }
+
+    // 需要创建，否则创建'message'监听时，会出现混乱
+    this._key = generateRandomKey();
+    this.registerDisposable(this.onDidConnected(this.didConnected.bind(this)));
+
+    this._onMessageMiddleware = this.decorateOnMessageMiddleware(
+      this._onMessageMiddleware
+    );
+    this._senderMiddleware = this.decorateSendMiddleware(
+      this._senderMiddleware
+    );
+
+    this.applyOnMessageMiddleware(this._onMessageMiddleware);
+    this.applySendMiddleware(this._senderMiddleware);
+  }
+
+  get service() {
+    return this._service;
+  }
+
+  setService(service: RPCService) {
+    this._service = service;
+  }
+
+  get senderMiddleware() {
+    return this._senderMiddleware;
+  }
+
+  /**
+   * Get or create read buffer instance
+   * Uses lazy initialization with caching for performance
+   *
+   * Priority:
+   * 1. Custom buffer provided in constructor
+   * 2. Cached instance
+   * 3. Create new instance using BufferFactory with configured format
+   *
+   * Subclasses can override this method to provide custom buffer logic
+   */
+  get readBuffer(): ReadBaseBuffer {
+    if (this._readBuffer) {
+      return this._readBuffer;
+    }
+
+    // Try to create using BufferFactory
+    try {
+      this._readBuffer = BufferFactory.createReadBuffer(
+        this._serializationFormat
+      );
+    } catch (error) {
+      // Fallback to JSON if configured format is not available
+      console.warn(
+        `[AbstractChannelProtocol] Failed to create read buffer with format "${this._serializationFormat}", falling back to JSON.`,
+        error
+      );
+      this._readBuffer = BufferFactory.createReadBuffer(
+        SerializationFormat.JSON
+      );
+    }
+
+    return this._readBuffer;
+  }
+
+  /**
+   * Get or create write buffer instance
+   * Uses lazy initialization with caching for performance
+   *
+   * Priority:
+   * 1. Custom buffer provided in constructor
+   * 2. Cached instance
+   * 3. Create new instance using BufferFactory with configured format
+   *
+   * Subclasses can override this method to provide custom buffer logic
+   */
+  get writeBuffer(): WriteBaseBuffer {
+    if (this._writeBuffer) {
+      return this._writeBuffer;
+    }
+
+    // Try to create using BufferFactory
+    try {
+      this._writeBuffer = BufferFactory.createWriteBuffer(
+        this._serializationFormat
+      );
+    } catch (error) {
+      // Fallback to JSON if configured format is not available
+      console.warn(
+        `[AbstractChannelProtocol] Failed to create write buffer with format "${this._serializationFormat}", falling back to JSON.`,
+        error
+      );
+      this._writeBuffer = BufferFactory.createWriteBuffer(
+        SerializationFormat.JSON
+      );
+    }
+
+    return this._writeBuffer;
+  }
+
+  /**
+   * Get the configured serialization format
+   */
+  get serializationFormat(): string {
+    return this._serializationFormat;
+  }
+
+  /**
+   * Set serialization format (will recreate buffers on next access)
+   * Note: This will clear cached buffers, new instances will be created on next access
+   */
+  setSerializationFormat(format: string): void {
+    if (this._serializationFormat !== format) {
+      this._serializationFormat = format;
+      // Clear cached buffers to force recreation with new format
+      this._readBuffer = null;
+      this._writeBuffer = null;
+    }
+  }
+
+  // start from 1
+  get seqId() {
+    this._seqId += 1;
+    return `${this._key}_${this._seqId}`;
+  }
+
+  get description() {
+    return this._description;
+  }
+
+  get masterProcessName() {
+    return this._masterProcessName;
+  }
+
+  addPendingSendEntry(entry: PendingSendEntry) {
+    this.pendingSendEntries.add(entry);
+  }
+
+  /**
+   *
+   * @param middlewares
+   * @returns
+   *
+   * 增加自定义的middleware，需要重写这个方法
+   */
+  decorateSendMiddleware(middlewares: SenderMiddleware[]) {
+    return middlewares;
+  }
+
+  decorateOnMessageMiddleware(middlewares: ClientMiddleware[]) {
+    return middlewares;
+  }
+
+  applyOnMessageMiddleware(fns: Function | Function[]) {
+    const copy = [].concat(fns);
+    this._onMessageMiddleware = [];
+    copy.forEach((fn) => {
+      if (typeof fn === 'function') {
+        this._onMessageMiddleware.push(fn(this));
+      }
+    });
+  }
+
+  applySendMiddleware(fns: Function | Function[]) {
+    const copy = [].concat(fns);
+    this._senderMiddleware = [];
+
+    copy.forEach((fn) => {
+      if (typeof fn === 'function') {
+        this._senderMiddleware.push(fn(this));
+      }
+    });
+  }
+
+  isConnected() {
+    return this._isConnected;
+  }
+
+  send(..._args: any[]) {
+    throw new Error('send method is not implemented');
+  }
+
+  on(..._args: any[]) {
+    throw new Error('onMessage method is not implemented');
+  }
+
+  resumePendingEntry() {
+    this.pendingSendEntries.forEach((entry) => {
+      this.pendingSendEntries.delete(entry);
+      resumeMiddlewares(this.senderMiddleware, entry);
+    });
+  }
+
+  didConnected() {
+    this.resumePendingEntry();
+  }
+
+  connect() {
+    this.onDidConnectedEvent.fire();
+  }
+
+  // 已经绑定了channel，这个时候需要直接触发
+  activate() {
+    this._isConnected = true;
+    this.onDidConnectedEvent.fire();
+  }
+
+  disconnect() {
+    this._isConnected = false;
+    this.onDidDisconnectedEvent.fire();
+  }
+
+  makeRequest(props: SendingProps, transfer?: MessagePort[]): Deferred | void;
+
+  makeRequest(
+    requestPath: string,
+    fnName: string,
+    ...args: any[]
+  ): Deferred | void;
+
+  makeRequest(...args: any[]) {
+    //
+    const { returnValue } = runMiddlewares(this.senderMiddleware, args);
+    if (returnValue) return returnValue;
+  }
+
+  sendReply(...args: any[]) {
+    this.send(...args);
+  }
+
+  onMessage(...args: any[]) {
+    runMiddlewares(this._onMessageMiddleware, args);
+  }
+}
+
+export default AbstractChannelProtocol;

package/src/protocol/MessageChannel.ts

@@ -0,0 +1,80 @@
+// https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
+import {
+  IMessageChannel,
+  AbstractChannelProtocolProps,
+} from '../types/channel';
+import AbstractChannelProtocol from './AbstractChannelProtocol';
+import { SenderMiddleware, ClientMiddleware } from '../types';
+
+export default class RPCMessageChannel
+  extends AbstractChannelProtocol
+  implements IMessageChannel
+{
+  private readonly port: MessagePort;
+  private sender: any;
+  private targetOrigin: string;
+
+  constructor(
+    options: {
+      port: MessagePort;
+      sender?: any;
+      targetOrigin?: string;
+    } & AbstractChannelProtocolProps
+  ) {
+    // Extract channel-specific options and pass the rest to parent
+    const {
+      port,
+      sender = window,
+      targetOrigin = '*',
+      ...protocolOptions
+    } = options;
+    super(protocolOptions);
+    this.port = port;
+    this.targetOrigin = targetOrigin;
+    this.sender = sender;
+    // MessagePort 需要调用 start() 才能开始接收消息（当使用 addEventListener 时）
+    if (this.port.start) {
+      this.port.start();
+    }
+  }
+
+  on(listener: (event: MessageEvent) => void): void | (() => void) {
+    const f = (ev: MessageEvent): void => {
+      listener(ev);
+    };
+    this.port.addEventListener('message', f);
+    return () => this.port.removeEventListener('message', f);
+  }
+
+  send(message: any, transfer?: Transferable[]) {
+    if (transfer && transfer.length > 0) {
+      this.port.postMessage(message, transfer);
+    } else {
+      this.port.postMessage(message);
+    }
+  }
+
+  /**
+   * Inherits buffer getters from AbstractChannelProtocol
+   * Uses BufferFactory with configured serialization format
+   *
+   * To use a different format, pass serializationFormat in constructor:
+   * new RPCMessageChannel({ port, serializationFormat: 'msgpack' })
+   *
+   * Or override these getters if you need custom buffer logic
+   */
+
+  decorateSendMiddleware(middlewares: SenderMiddleware[]) {
+    return middlewares;
+  }
+
+  decorateOnMessageMiddleware(middlewares: ClientMiddleware[]) {
+    return middlewares;
+  }
+
+  disconnect() {
+    if (this.port) {
+      this.port.close();
+    }
+  }
+}

package/src/protocol/WebSocketChannel.ts

@@ -0,0 +1,179 @@
+import AbstractChannelProtocol from './AbstractChannelProtocol';
+import {
+  SenderMiddleware,
+  ClientMiddleware,
+  AbstractChannelProtocolProps,
+} from '../types';
+import { normalizeWebSocketRawMessage } from '../middlewares/normalize';
+
+export default class WebSocketChannel extends AbstractChannelProtocol {
+  private socket: WebSocket;
+  readonly name: string;
+  private reconnectAttempts: number;
+  private maxReconnectAttempts: number;
+  private reconnectDelay: number;
+
+  /**
+   * @param socket Pass the WebSocket instance (client-side) or WebSocket connection (server-side).
+   * @param options Configuration options
+   */
+  constructor(
+    socket: WebSocket,
+    options?: {
+      name?: string;
+      maxReconnectAttempts?: number;
+      reconnectDelay?: number;
+      connected?: boolean;
+    } & AbstractChannelProtocolProps
+  ) {
+    // super() must be the first statement - extract options inline using IIFE
+    const opts = options || {};
+    const {
+      name,
+      maxReconnectAttempts,
+      reconnectDelay,
+      connected,
+      ...protocolOptions
+    } = opts;
+
+    super({
+      connected: connected ?? false,
+      ...protocolOptions,
+    });
+
+    // Now we can assign to instance properties
+    this.socket = socket;
+    this.name = name || 'websocket';
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = maxReconnectAttempts ?? 5;
+    this.reconnectDelay = reconnectDelay ?? 1000;
+
+    // Set up WebSocket event handlers
+    this.setupSocketHandlers();
+  }
+
+  private setupSocketHandlers() {
+    this.socket.addEventListener('open', () => {
+      // WebSocket 已打开，激活连接
+      this.activate();
+    });
+
+    this.socket.addEventListener('close', () => {
+      // WebSocket 已关闭，断开连接
+      super.disconnect();
+    });
+
+    this.socket.addEventListener('error', (error) => {
+      console.error(`[WebSocketChannel ${this.name}] Error:`, error);
+    });
+  }
+
+  on(listener: (data: unknown) => void): void | (() => void) {
+    // Handle both browser MessageEvent and Node.js ws library format
+    const f = (ev: MessageEvent | Buffer | string | any): void => {
+      // Debug: log the event structure
+      if (ev === undefined || ev === null) {
+        console.warn(
+          `[WebSocketChannel ${this.name}] Received undefined/null message event`
+        );
+        return;
+      }
+
+      // Pass the raw event/data to listener
+      // The normalizeWebSocketRawMessage middleware will handle the conversion
+      listener(ev);
+    };
+
+    // Try addEventListener first (works in both browser and ws library)
+    if (typeof this.socket.addEventListener === 'function') {
+      this.socket.addEventListener('message', f);
+      return () => {
+        if (typeof this.socket.removeEventListener === 'function') {
+          this.socket.removeEventListener('message', f);
+        }
+      };
+    } else {
+      // Fallback to 'on' method for older ws library versions
+      // Type assertion for Node.js ws library
+      const wsSocket = this.socket as any;
+      if (typeof wsSocket.on === 'function') {
+        wsSocket.on('message', f);
+        return () => {
+          if (typeof wsSocket.off === 'function') {
+            wsSocket.off('message', f);
+          } else if (typeof wsSocket.removeListener === 'function') {
+            wsSocket.removeListener('message', f);
+          }
+        };
+      }
+    }
+
+    // If neither method works, return a no-op cleanup function
+    return () => {};
+  }
+
+  send(data: unknown): void {
+    if (this.socket.readyState === WebSocket.OPEN) {
+      // Data should already be serialized (string) by the middleware
+      // WebSocket.send() accepts string, ArrayBuffer, or Blob
+      if (typeof data === 'string') {
+        this.socket.send(data);
+      } else if (data instanceof ArrayBuffer || data instanceof Blob) {
+        this.socket.send(data);
+      } else {
+        // Fallback: serialize if not already serialized
+        this.socket.send(JSON.stringify(data));
+      }
+    } else {
+      console.warn(
+        `[WebSocketChannel ${this.name}] Cannot send: WebSocket is not open. State: ${this.socket.readyState}`
+      );
+    }
+  }
+
+  /**
+   * Inherits buffer getters from AbstractChannelProtocol
+   * Uses BufferFactory with configured serialization format
+   *
+   * To use a different format, pass serializationFormat in constructor:
+   * new WebSocketChannel(socket, { serializationFormat: 'msgpack' })
+   *
+   * Or override these getters if you need custom buffer logic
+   */
+
+  decorateSendMiddleware(middlewares: SenderMiddleware[]) {
+    return middlewares;
+  }
+
+  decorateOnMessageMiddleware(middlewares: ClientMiddleware[]) {
+    // Replace the first middleware (normalizeMessageChannelRawMessage)
+    // with normalizeWebSocketRawMessage to handle both browser and Node.js ws library formats
+    // Note: We return the factory function, not the result of calling it
+    // because applyOnMessageMiddleware will call fn(this) for each middleware
+    if (middlewares.length > 0) {
+      return [normalizeWebSocketRawMessage, ...middlewares.slice(1)];
+    }
+    return middlewares;
+  }
+
+  disconnect() {
+    if (this.socket) {
+      this.socket.close();
+    }
+    super.disconnect();
+  }
+
+  /**
+   * Get the current WebSocket ready state
+   */
+  get readyState(): number {
+    return this.socket.readyState;
+  }
+
+  /**
+   * Check if WebSocket is open
+   */
+  isOpen(): boolean {
+    return this.socket.readyState === WebSocket.OPEN;
+  }
+}

package/src/protocol/WorkerChannel.ts

@@ -0,0 +1,36 @@
+import AbstractChannelProtocol from './AbstractChannelProtocol';
+import { AbstractChannelProtocolProps } from '../types/channel';
+
+export default class WorkerChannel extends AbstractChannelProtocol {
+  private worker: any;
+  readonly name: string;
+
+  /**
+   * @param worker Pass the Worker in the main thread.
+   * @param options Configuration options including serialization format
+   */
+  constructor(
+    worker: any,
+    options?: {
+      name?: string;
+    } & AbstractChannelProtocolProps
+  ) {
+    // Extract Worker-specific options and pass the rest to parent
+    const { name, ...protocolOptions } = options || {};
+    super(protocolOptions);
+    this.worker = worker;
+    this.name = name || 'worker';
+  }
+
+  on(listener: (data: unknown) => void): void | (() => void) {
+    const f = (ev: MessageEvent): void => {
+      listener(ev);
+    };
+    this.worker.addEventListener('message', f);
+    return () => this.worker.removeEventListener('message', f);
+  }
+
+  send(data: unknown): void {
+    this.worker.postMessage(data);
+  }
+}

package/src/types/buffer.ts

@@ -0,0 +1,5 @@
+export type DataBuffer = {
+  // refer to theia/packages/core/src/common/messaging/socket-write-buffer.ts
+  flush: () => void;
+  drain: () => void;
+};

package/src/types/channel.ts

@@ -0,0 +1,50 @@
+export type IMessageChannelOnClose = () => void;
+export type IMessageChannelOnError = () => void;
+export type IMessageChannelOnMessage = (message: any) => void;
+export type IMessageChannelSend = (options: any) => void;
+export type IMessageChannelDisconnect = () => void;
+
+/**
+ * A channel is a bidirectional communications channel
+ */
+export type IMessageChannel = {
+  onClose?: IMessageChannelOnClose;
+
+  onError?: IMessageChannelOnError;
+
+  onMessage: IMessageChannelOnMessage;
+
+  send: IMessageChannelSend;
+
+  disconnect: IMessageChannelDisconnect;
+};
+
+export type SendingProps = {
+  requestPath: string;
+  methodName: string;
+  args?: any[];
+  isOptionsRequest?: boolean;
+  transfer?: MessagePort[];
+};
+
+/**
+ * Channel protocol configuration options
+ */
+export type AbstractChannelProtocolProps = {
+  description?: string;
+  masterProcessName?: string;
+  connected?: boolean;
+  /**
+   * Serialization format for buffer encoding/decoding
+   * @default 'json'
+   */
+  serializationFormat?: string;
+  /**
+   * Custom read buffer instance (overrides serializationFormat)
+   */
+  readBuffer?: any;
+  /**
+   * Custom write buffer instance (overrides serializationFormat)
+   */
+  writeBuffer?: any;
+};

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from './channel';
+// export * from './messageChannel';
+export * from './rpc';
+export * from './proxyChannel';
+export * from './proxyService';
+export * from './middleware';
+
+export type ClientMiddleware = any;
+export type SenderMiddleware = any;