@x-oasis/async-call-rpc 0.1.38

package/src/buffer/README.md

@@ -0,0 +1,147 @@
+# Buffer Serialization Formats
+
+本模块提供了可插拔的序列化/反序列化机制，支持多种数据格式用于 RPC 通信。
+
+## 支持的序列化格式
+
+### 1. JSON (默认)
+- **格式**: `SerializationFormat.JSON`
+- **特点**: 人类可读、易于调试、跨平台兼容
+- **性能**: 中等，适合大多数场景
+- **使用**: 默认格式，无需额外配置
+
+### 2. MessagePack (推荐高性能方案)
+- **格式**: `SerializationFormat.MESSAGEPACK`
+- **特点**: 二进制格式、体积小、性能高（比 JSON 快 2-3 倍）
+- **性能**: 高，适合性能敏感场景
+- **依赖**: `@msgpack/msgpack`
+
+### 3. CBOR
+- **格式**: `SerializationFormat.CBOR`
+- **特点**: 标准二进制格式（RFC 7049）、支持更多数据类型
+- **性能**: 高
+- **依赖**: `cbor` 或 `cbor-web`
+
+### 4. Protocol Buffers
+- **格式**: `SerializationFormat.PROTOBUF`
+- **特点**: Google 出品、高性能、需要 schema 定义
+- **性能**: 极高，适合大规模系统
+- **依赖**: `protobufjs` 或 `@grpc/proto-loader`
+
+## 使用方法
+
+### 方式 1: 在 Channel 中重写 buffer getter
+
+```typescript
+import { SerializationFormat, BufferFactory } from '@x-oasis/async-call-rpc/buffer';
+import AbstractChannelProtocol from './AbstractChannelProtocol';
+
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    // 使用 MessagePack
+    return BufferFactory.createReadBuffer(SerializationFormat.MESSAGEPACK);
+  }
+  
+  get writeBuffer() {
+    return BufferFactory.createWriteBuffer(SerializationFormat.MESSAGEPACK);
+  }
+}
+```
+
+### 方式 2: 注册自定义序列化器
+
+```typescript
+import { BufferFactory } from '@x-oasis/async-call-rpc/buffer';
+import { encode, decode } from '@msgpack/msgpack';
+import ReadBaseBuffer from '@x-oasis/async-call-rpc/buffer/ReadBaseBuffer';
+import WriteBaseBuffer from '@x-oasis/async-call-rpc/buffer/WriteBaseBuffer';
+
+// 实现 MessagePack 序列化器
+class MessagePackReadBuffer extends ReadBaseBuffer {
+  decode(data: string | ArrayBuffer | Uint8Array): any {
+    if (typeof data === 'string') {
+      const encoder = new TextEncoder();
+      return decode(encoder.encode(data));
+    }
+    return decode(data as Uint8Array);
+  }
+  
+  getFormat(): string {
+    return 'msgpack';
+  }
+}
+
+class MessagePackWriteBuffer extends WriteBaseBuffer {
+  encode(data: any): Uint8Array {
+    return encode(data);
+  }
+  
+  getFormat(): string {
+    return 'msgpack';
+  }
+}
+
+// 注册到工厂
+BufferFactory.registerReadBuffer('msgpack', () => new MessagePackReadBuffer());
+BufferFactory.registerWriteBuffer('msgpack', () => new MessagePackWriteBuffer());
+```
+
+### 方式 3: 使用工厂创建（推荐）
+
+```typescript
+import { BufferFactory, SerializationFormat } from '@x-oasis/async-call-rpc/buffer';
+
+// 创建 JSON buffer（默认）
+const jsonReadBuffer = BufferFactory.createReadBuffer(SerializationFormat.JSON);
+const jsonWriteBuffer = BufferFactory.createWriteBuffer(SerializationFormat.JSON);
+
+// 创建 MessagePack buffer（需要先注册）
+const msgpackReadBuffer = BufferFactory.createReadBuffer(SerializationFormat.MESSAGEPACK);
+const msgpackWriteBuffer = BufferFactory.createWriteBuffer(SerializationFormat.MESSAGEPACK);
+```
+
+## 性能对比
+
+根据社区实践和基准测试：
+
+| 格式 | 序列化速度 | 体积 | 可读性 | 推荐场景 |
+|------|-----------|------|--------|---------|
+| JSON | 基准 | 100% | ⭐⭐⭐⭐⭐ | 开发、调试、小数据量 |
+| MessagePack | 2-3x | 60-70% | ⭐ | 生产环境、性能敏感 |
+| CBOR | 2-3x | 60-70% | ⭐ | 标准兼容场景 |
+| Protobuf | 3-5x | 50-60% | ⭐ | 大规模系统、跨服务 |
+
+## 内容协商
+
+未来可以支持在 RPC 握手时协商序列化格式：
+
+```typescript
+// 客户端发送支持的格式列表
+const supportedFormats = [
+  SerializationFormat.MESSAGEPACK,
+  SerializationFormat.JSON
+];
+
+// 服务端选择最佳格式并返回
+const selectedFormat = negotiateFormat(supportedFormats);
+```
+
+## 注意事项
+
+1. **二进制格式传输**: MessagePack、CBOR、Protobuf 等二进制格式需要确保传输层支持二进制数据（如 WebSocket 的 binary 模式）
+
+2. **类型兼容性**: 不同格式对 JavaScript 类型的支持不同：
+   - JSON: 不支持 Date、Map、Set、undefined 等
+   - MessagePack: 支持更多类型，包括 Date、Binary 等
+   - CBOR: 支持最广泛的类型
+
+3. **向后兼容**: 切换序列化格式时，需要确保客户端和服务端使用相同的格式
+
+4. **错误处理**: 序列化/反序列化失败时，应该回退到 JSON 或抛出明确的错误
+
+## 参考实现
+
+- **JSON-RPC 2.0**: https://www.jsonrpc.org/specification
+- **MessagePack**: https://msgpack.org/
+- **CBOR**: https://cbor.io/
+- **Protocol Buffers**: https://developers.google.com/protocol-buffers

package/src/buffer/ReadBaseBuffer.ts

@@ -0,0 +1,20 @@
+/**
+ * Base class for read buffer/deserialization
+ * Supports both string and binary (ArrayBuffer/Uint8Array) input
+ */
+abstract class ReadBaseBuffer {
+  /**
+   * Decode/deserialize data
+   * @param data - Encoded data (string or binary)
+   * @returns Decoded data
+   */
+  abstract decode(data: string | ArrayBuffer | Uint8Array): any;
+
+  /**
+   * Get the format identifier this decoder supports
+   * @returns Format name (e.g., 'json', 'msgpack', 'cbor')
+   */
+  abstract getFormat(): string;
+}
+
+export default ReadBaseBuffer;

package/src/buffer/ReadBuffer.ts

@@ -0,0 +1,58 @@
+import ReadBaseBuffer from './ReadBaseBuffer';
+
+export enum DataType {
+  Undefined = 0,
+  String = 1,
+  Buffer = 2,
+  VSBuffer = 3,
+  Array = 4,
+  Object = 5,
+  Int = 6,
+}
+
+/**
+ * JSON-based read buffer implementation
+ * Default deserializer using JSON.parse
+ */
+export default class ReadBuffer extends ReadBaseBuffer {
+  decode(data: string | ArrayBuffer | Uint8Array): any {
+    // Handle binary input (convert to string first)
+    if (data instanceof ArrayBuffer || data instanceof Uint8Array) {
+      const decoder = new TextDecoder();
+      const text = decoder.decode(data);
+      return JSON.parse(text);
+    }
+    // Handle string input
+    return JSON.parse(data as string);
+  }
+
+  getFormat(): string {
+    return 'json';
+  }
+}
+
+// export class BufferReader implements IReader {
+
+// 	private pos = 0;
+
+// 	constructor(private buffer: VSBuffer) { }
+
+// 	read(bytes: number): VSBuffer {
+// 		const result = this.buffer.slice(this.pos, this.pos + bytes);
+// 		this.pos += result.byteLength;
+// 		return result;
+// 	}
+// }
+
+// export class BufferWriter implements IWriter {
+
+// 	private buffers: VSBuffer[] = [];
+
+// 	get buffer(): VSBuffer {
+// 		return VSBuffer.concat(this.buffers);
+// 	}
+
+// 	write(buffer: VSBuffer): void {
+// 		this.buffers.push(buffer);
+// 	}
+// }

package/src/buffer/SerializationFormat.ts

@@ -0,0 +1,81 @@
+/**
+ * Supported serialization formats for RPC communication
+ *
+ * Based on JSON-RPC community practices:
+ * - JSON: Default, human-readable, good for debugging
+ * - MessagePack: Binary format, 2-3x faster, smaller size
+ * - CBOR: Standard binary format (RFC 7049)
+ * - Protobuf: High performance, requires schema
+ */
+export enum SerializationFormat {
+  /** JSON - Default text format, human-readable */
+  JSON = 'json',
+  /** MessagePack - Binary format, high performance */
+  MESSAGEPACK = 'msgpack',
+  /** CBOR - Concise Binary Object Representation (RFC 7049) */
+  CBOR = 'cbor',
+  /** Protocol Buffers - High performance, schema-based */
+  PROTOBUF = 'protobuf',
+  /** Custom format - User-defined serialization */
+  CUSTOM = 'custom',
+}
+
+/**
+ * Serialization format metadata
+ */
+export interface SerializationFormatInfo {
+  format: SerializationFormat;
+  name: string;
+  description: string;
+  mimeType: string;
+  isBinary: boolean;
+  isText: boolean;
+}
+
+/**
+ * Format metadata registry
+ */
+export const FORMAT_INFO: Record<SerializationFormat, SerializationFormatInfo> =
+  {
+    [SerializationFormat.JSON]: {
+      format: SerializationFormat.JSON,
+      name: 'JSON',
+      description: 'JavaScript Object Notation - Human-readable text format',
+      mimeType: 'application/json',
+      isBinary: false,
+      isText: true,
+    },
+    [SerializationFormat.MESSAGEPACK]: {
+      format: SerializationFormat.MESSAGEPACK,
+      name: 'MessagePack',
+      description:
+        'Binary serialization format - High performance, compact size',
+      mimeType: 'application/x-msgpack',
+      isBinary: true,
+      isText: false,
+    },
+    [SerializationFormat.CBOR]: {
+      format: SerializationFormat.CBOR,
+      name: 'CBOR',
+      description: 'Concise Binary Object Representation (RFC 7049)',
+      mimeType: 'application/cbor',
+      isBinary: true,
+      isText: false,
+    },
+    [SerializationFormat.PROTOBUF]: {
+      format: SerializationFormat.PROTOBUF,
+      name: 'Protocol Buffers',
+      description: 'Google Protocol Buffers - Schema-based binary format',
+      mimeType: 'application/x-protobuf',
+      isBinary: true,
+      isText: false,
+    },
+    [SerializationFormat.CUSTOM]: {
+      format: SerializationFormat.CUSTOM,
+      name: 'Custom',
+      description: 'User-defined custom serialization format',
+      mimeType: 'application/octet-stream',
+      isBinary: true,
+      isText: false,
+    },
+  };

package/src/buffer/WriteBaseBuffer.ts

@@ -0,0 +1,20 @@
+/**
+ * Base class for write buffer/serialization
+ * Supports both string and binary (ArrayBuffer/Uint8Array) output
+ */
+abstract class WriteBaseBuffer {
+  /**
+   * Encode/serialize data
+   * @param data - Data to encode
+   * @returns Encoded data (string for text formats, ArrayBuffer/Uint8Array for binary formats)
+   */
+  abstract encode(data: any): string | ArrayBuffer | Uint8Array;
+
+  /**
+   * Get the format identifier for content negotiation
+   * @returns Format name (e.g., 'json', 'msgpack', 'cbor')
+   */
+  abstract getFormat(): string;
+}
+
+export default WriteBaseBuffer;

package/src/buffer/WriteBuffer.ts

@@ -0,0 +1,15 @@
+import WriteBaseBuffer from './WriteBaseBuffer';
+
+/**
+ * JSON-based write buffer implementation
+ * Default serializer using JSON.stringify
+ */
+export default class WriteBuffer extends WriteBaseBuffer {
+  encode(data: any): string {
+    return JSON.stringify(data);
+  }
+
+  getFormat(): string {
+    return 'json';
+  }
+}

package/src/buffer/examples.ts

@@ -0,0 +1,242 @@
+/**
+ * Examples of using different serialization formats
+ *
+ * This file demonstrates how to use various serialization formats
+ * with the async-call-rpc buffer system.
+ */
+
+import { BufferFactory, SerializationFormat } from './index';
+import ReadBaseBuffer from './ReadBaseBuffer';
+import WriteBaseBuffer from './WriteBaseBuffer';
+
+// ============================================================================
+// Example 1: Using MessagePack (requires @msgpack/msgpack)
+// ============================================================================
+
+/**
+ * To use MessagePack, first install the dependency:
+ * npm install @msgpack/msgpack
+ *
+ * Then implement the buffers:
+ */
+export function registerMessagePack() {
+  // Dynamic import to avoid requiring the dependency if not used
+  // In production, you might want to use a static import
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { encode, decode } = require('@msgpack/msgpack');
+
+    class MessagePackReadBuffer extends ReadBaseBuffer {
+      decode(data: string | ArrayBuffer | Uint8Array): any {
+        if (typeof data === 'string') {
+          // Convert string to Uint8Array
+          const encoder = new TextEncoder();
+          return decode(encoder.encode(data));
+        }
+        // Handle ArrayBuffer or Uint8Array
+        const uint8Array =
+          data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+        return decode(uint8Array);
+      }
+
+      getFormat(): string {
+        return SerializationFormat.MESSAGEPACK;
+      }
+    }
+
+    class MessagePackWriteBuffer extends WriteBaseBuffer {
+      encode(data: any): Uint8Array {
+        return encode(data);
+      }
+
+      getFormat(): string {
+        return SerializationFormat.MESSAGEPACK;
+      }
+    }
+
+    // Register with the factory
+    BufferFactory.registerReadBuffer(
+      SerializationFormat.MESSAGEPACK,
+      () => new MessagePackReadBuffer()
+    );
+    BufferFactory.registerWriteBuffer(
+      SerializationFormat.MESSAGEPACK,
+      () => new MessagePackWriteBuffer()
+    );
+
+    return true;
+  } catch (e) {
+    console.warn(
+      'MessagePack not available. Install @msgpack/msgpack to use it.'
+    );
+    return false;
+  }
+}
+
+// ============================================================================
+// Example 2: Using CBOR (requires cbor or cbor-web)
+// ============================================================================
+
+/**
+ * To use CBOR, install one of:
+ * npm install cbor
+ * npm install cbor-web
+ */
+export function registerCBOR() {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cbor = require('cbor');
+
+    class CBORReadBuffer extends ReadBaseBuffer {
+      decode(data: string | ArrayBuffer | Uint8Array): any {
+        if (typeof data === 'string') {
+          const encoder = new TextEncoder();
+          const uint8Array = encoder.encode(data);
+          return cbor.decode(uint8Array);
+        }
+        const uint8Array =
+          data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+        return cbor.decode(uint8Array);
+      }
+
+      getFormat(): string {
+        return SerializationFormat.CBOR;
+      }
+    }
+
+    class CBORWriteBuffer extends WriteBaseBuffer {
+      encode(data: any): Uint8Array {
+        return cbor.encode(data);
+      }
+
+      getFormat(): string {
+        return SerializationFormat.CBOR;
+      }
+    }
+
+    BufferFactory.registerReadBuffer(
+      SerializationFormat.CBOR,
+      () => new CBORReadBuffer()
+    );
+    BufferFactory.registerWriteBuffer(
+      SerializationFormat.CBOR,
+      () => new CBORWriteBuffer()
+    );
+
+    return true;
+  } catch (e) {
+    console.warn('CBOR not available. Install cbor or cbor-web to use it.');
+    return false;
+  }
+}
+
+// ============================================================================
+// Example 3: Custom serialization format
+// ============================================================================
+
+/**
+ * Example of a custom compression + JSON serialization
+ */
+export function registerCompressedJSON() {
+  class CompressedJSONReadBuffer extends ReadBaseBuffer {
+    decode(data: string | ArrayBuffer | Uint8Array): any {
+      // In a real implementation, you would decompress first
+      // This is just a placeholder
+      if (typeof data === 'string') {
+        return JSON.parse(data);
+      }
+      const decoder = new TextDecoder();
+      const text = decoder.decode(data);
+      return JSON.parse(text);
+    }
+
+    getFormat(): string {
+      return 'compressed-json';
+    }
+  }
+
+  class CompressedJSONWriteBuffer extends WriteBaseBuffer {
+    encode(data: any): string {
+      // In a real implementation, you would compress the JSON
+      // This is just a placeholder
+      return JSON.stringify(data);
+    }
+
+    getFormat(): string {
+      return 'compressed-json';
+    }
+  }
+
+  BufferFactory.registerReadBuffer(
+    'compressed-json',
+    () => new CompressedJSONReadBuffer()
+  );
+  BufferFactory.registerWriteBuffer(
+    'compressed-json',
+    () => new CompressedJSONWriteBuffer()
+  );
+}
+
+// ============================================================================
+// Example 4: Using in a Channel
+// ============================================================================
+
+/**
+ * Example of using a custom format in a channel implementation
+ */
+export function createChannelWithMessagePack() {
+  // First register MessagePack
+  if (!registerMessagePack()) {
+    throw new Error('MessagePack not available');
+  }
+
+  // Then use it in your channel
+  // This would be in your channel class:
+  /*
+  class MyChannel extends AbstractChannelProtocol {
+    get readBuffer() {
+      return BufferFactory.createReadBuffer(SerializationFormat.MESSAGEPACK);
+    }
+    
+    get writeBuffer() {
+      return BufferFactory.createWriteBuffer(SerializationFormat.MESSAGEPACK);
+    }
+  }
+  */
+}
+
+// ============================================================================
+// Example 5: Format negotiation
+// ============================================================================
+
+/**
+ * Example of format negotiation between client and server
+ * This would typically happen during connection handshake
+ */
+export interface FormatNegotiation {
+  clientFormats: string[];
+  serverFormats: string[];
+  selectedFormat?: string;
+}
+
+export function negotiateFormat(
+  clientFormats: string[],
+  serverFormats: string[]
+): string | null {
+  // Find the first format that both support
+  for (const format of clientFormats) {
+    if (serverFormats.includes(format)) {
+      return format;
+    }
+  }
+
+  // Fallback to JSON if available
+  if (
+    clientFormats.includes(SerializationFormat.JSON) &&
+    serverFormats.includes(SerializationFormat.JSON)
+  ) {
+    return SerializationFormat.JSON;
+  }
+
+  return null;
+}

package/src/buffer/index.ts

@@ -0,0 +1,15 @@
+export { default as ReadBuffer } from './ReadBuffer';
+export { default as WriteBuffer } from './WriteBuffer';
+export { default as DataBuffer } from './DataBuffer';
+export { default as ReadBaseBuffer } from './ReadBaseBuffer';
+export { default as WriteBaseBuffer } from './WriteBaseBuffer';
+export {
+  SerializationFormat,
+  FORMAT_INFO,
+  type SerializationFormatInfo,
+} from './SerializationFormat';
+export { BufferFactory } from './BufferFactory';
+export {
+  MessagePackReadBuffer,
+  MessagePackWriteBuffer,
+} from './MessagePackBuffer';

package/src/common.ts

@@ -0,0 +1,20 @@
+import { isUpperAsciiLetter } from '@x-oasis/is-ascii';
+
+export const isEventMethod = (name: string) => {
+  if (typeof name !== 'string') return false;
+  return (
+    name[0] === 'o' && name[1] === 'n' && isUpperAsciiLetter(name.charCodeAt(2))
+  );
+};
+
+export const isAssignPassingPortMethod = (name: string) => {
+  return /^assignPassingPort$/.test(name);
+};
+
+export const isAcquirePortMethod = (name: string) => {
+  return /^acquire.*Port$/.test(name);
+};
+
+export const isOptionsMethod = (name: string) => {
+  return /Options$/.test(name) || /OptionsRequest$/.test(name);
+};

package/src/endpoint/ProxyRPCClient.ts

@@ -0,0 +1,64 @@
+import AbstractChannelProtocol from '../protocol/AbstractChannelProtocol';
+
+class ProxyRPCClient {
+  readonly requestPath: string;
+
+  private channel: AbstractChannelProtocol;
+
+  constructor(
+    requestPath: string,
+    options?: {
+      channel?: AbstractChannelProtocol;
+    }
+  ) {
+    const { channel } = options || {};
+    this.requestPath = requestPath;
+    if (channel) {
+      this.setChannel(channel);
+    }
+  }
+
+  setChannel(channel: AbstractChannelProtocol) {
+    this.channel = channel;
+    // this.channel.on(this.handleMessage.bind(this));
+  }
+
+  handleMessage(...args: any[]) {
+    this.channel.onMessage(...args);
+  }
+
+  createProxy<T = object>(): T {
+    const getTrap =
+      (_: any, methodName: string) =>
+      (...args: any[]) => {
+        if (!this.channel) {
+          throw new Error(
+            `[ProxyRPCClient error] \`this.channel\` is null, when invoke function ${methodName}`
+          );
+        }
+        return this.channel.makeRequest({
+          requestPath: this.requestPath,
+          methodName,
+          args,
+          // @ts-ignore, 这个地方其实是跟 `updateSeqInfo` 中间件配合的
+          // 因为`updateSeqInfo` 中间件会在`makeRequest`之后，将返回值设置到`returnValue`中
+          // 所以这里需要返回`promise`，以便于在`createProxy`中能够正确地返回`promise`
+          // 否则的话，会出现`promise`不正确的问题
+          // 因为`makeRequest`会返回`promise`，但是`createProxy`会返回`proxy`
+          // 所以这里需要返回`promise`，以便于在`createProxy`中能够正确地返回`promise`
+          // 否则的话，会出现`promise`不正确的问题
+          // 因为`makeRequest`会返回`promise`，但是`createProxy`会返回`proxy`
+          // 所以这里需要返回`promise`，以便于在`createProxy`中能够正确地返回`promise`
+        }).promise;
+      };
+
+    return new Proxy(
+      {},
+      {
+        get: getTrap,
+      }
+    ) as any as T;
+  }
+}
+
+export default ProxyRPCClient;