@x-oasis/async-call-rpc 0.1.38

package/src/buffer/BufferFactory.ts

@@ -0,0 +1,124 @@
+import ReadBaseBuffer from './ReadBaseBuffer';
+import WriteBaseBuffer from './WriteBaseBuffer';
+import ReadBuffer from './ReadBuffer';
+import WriteBuffer from './WriteBuffer';
+import { SerializationFormat } from './SerializationFormat';
+
+/**
+ * Factory for creating buffer instances based on serialization format
+ *
+ * This factory allows easy switching between different serialization formats
+ * and supports custom implementations.
+ */
+export class BufferFactory {
+  private static readBufferRegistry = new Map<string, () => ReadBaseBuffer>();
+  private static writeBufferRegistry = new Map<string, () => WriteBaseBuffer>();
+
+  /**
+   * Register a custom read buffer implementation
+   */
+  static registerReadBuffer(
+    format: string,
+    factory: () => ReadBaseBuffer
+  ): void {
+    this.readBufferRegistry.set(format, factory);
+  }
+
+  /**
+   * Register a custom write buffer implementation
+   */
+  static registerWriteBuffer(
+    format: string,
+    factory: () => WriteBaseBuffer
+  ): void {
+    this.writeBufferRegistry.set(format, factory);
+  }
+
+  /**
+   * Create a read buffer for the specified format
+   */
+  static createReadBuffer(
+    format: SerializationFormat | string = SerializationFormat.JSON
+  ): ReadBaseBuffer {
+    const factory = this.readBufferRegistry.get(format);
+    if (factory) {
+      return factory();
+    }
+
+    // Default to JSON
+    switch (format) {
+      case SerializationFormat.JSON:
+        return new ReadBuffer();
+      case SerializationFormat.MESSAGEPACK:
+        // Try to load MessagePack if available
+        try {
+          // Dynamic import example (would need actual implementation)
+          // const { MessagePackReadBuffer } = require('./MessagePackBuffer');
+          // return new MessagePackReadBuffer();
+          throw new Error(
+            'MessagePack not available. Install @msgpack/msgpack and register it.'
+          );
+        } catch (e) {
+          throw new Error(
+            `Unsupported read buffer format: ${format}. Register a custom implementation.`
+          );
+        }
+      default:
+        throw new Error(`Unsupported read buffer format: ${format}`);
+    }
+  }
+
+  /**
+   * Create a write buffer for the specified format
+   */
+  static createWriteBuffer(
+    format: SerializationFormat | string = SerializationFormat.JSON
+  ): WriteBaseBuffer {
+    const factory = this.writeBufferRegistry.get(format);
+    if (factory) {
+      return factory();
+    }
+
+    // Default to JSON
+    switch (format) {
+      case SerializationFormat.JSON:
+        return new WriteBuffer();
+      case SerializationFormat.MESSAGEPACK:
+        // Try to load MessagePack if available
+        try {
+          // Dynamic import example (would need actual implementation)
+          // const { MessagePackWriteBuffer } = require('./MessagePackBuffer');
+          // return new MessagePackWriteBuffer();
+          throw new Error(
+            'MessagePack not available. Install @msgpack/msgpack and register it.'
+          );
+        } catch (e) {
+          throw new Error(
+            `Unsupported write buffer format: ${format}. Register a custom implementation.`
+          );
+        }
+      default:
+        throw new Error(`Unsupported write buffer format: ${format}`);
+    }
+  }
+
+  /**
+   * Get list of registered formats
+   */
+  static getRegisteredFormats(): string[] {
+    const formats = new Set<string>();
+    this.readBufferRegistry.forEach((_, format) => formats.add(format));
+    this.writeBufferRegistry.forEach((_, format) => formats.add(format));
+    return Array.from(formats);
+  }
+}
+
+// Register default JSON format
+BufferFactory.registerReadBuffer(
+  SerializationFormat.JSON,
+  () => new ReadBuffer()
+);
+BufferFactory.registerWriteBuffer(
+  SerializationFormat.JSON,
+  () => new WriteBuffer()
+);

package/src/buffer/CHANGELOG.md

@@ -0,0 +1,207 @@
+# Buffer 优化变更日志
+
+## 优化完成时间
+2024年（当前）
+
+## 概述
+
+本次优化对 `async-call-rpc` 的 buffer 序列化系统进行了全面改进，实现了统一管理、配置化和高性能的序列化方案。
+
+## 主要变更
+
+### 1. 类型定义增强
+
+**文件**: `src/types/channel.ts`
+
+**新增**:
+- `AbstractChannelProtocolProps` 类型，包含序列化配置选项：
+  - `serializationFormat?: string` - 序列化格式配置
+  - `readBuffer?: ReadBaseBuffer` - 自定义读 buffer
+  - `writeBuffer?: WriteBaseBuffer` - 自定义写 buffer
+
+**影响**: 所有 Channel 构造函数现在都支持序列化配置
+
+### 2. AbstractChannelProtocol 优化
+
+**文件**: `src/protocol/AbstractChannelProtocol.ts`
+
+**改进**:
+- ✅ 使用 `BufferFactory` 统一创建 buffer 实例
+- ✅ 支持通过构造函数配置序列化格式
+- ✅ 实现智能缓存机制（首次创建，后续复用）
+- ✅ 添加格式验证和自动回退机制（不支持时回退到 JSON）
+- ✅ 新增 `setSerializationFormat()` 方法支持运行时切换
+- ✅ 新增 `serializationFormat` getter 获取当前格式
+
+**之前**:
+```typescript
+get readBuffer() {
+  if (this._readBuffer) return this._readBuffer;
+  this._readBuffer = new ReadBuffer(); // 硬编码 JSON
+  return this._readBuffer;
+}
+```
+
+**现在**:
+```typescript
+get readBuffer(): ReadBaseBuffer {
+  if (this._readBuffer) return this._readBuffer;
+  // 使用工厂创建，支持配置格式
+  this._readBuffer = BufferFactory.createReadBuffer(this._serializationFormat);
+  return this._readBuffer;
+}
+```
+
+### 3. 子类 Channel 优化
+
+**文件**: 
+- `src/protocol/MessageChannel.ts`
+- `src/protocol/WebSocketChannel.ts`
+- `src/protocol/WorkerChannel.ts`
+
+**改进**:
+- ✅ 移除直接创建 buffer 实例的代码
+- ✅ 继承父类的 buffer getter（使用工厂和缓存）
+- ✅ 构造函数支持 `AbstractChannelProtocolProps` 配置
+- ✅ 统一使用父类的缓存机制
+
+**之前**:
+```typescript
+get readBuffer() {
+  return new ReadBuffer(); // 每次都创建新实例
+}
+```
+
+**现在**:
+```typescript
+// 继承父类实现，使用工厂和缓存
+// 可通过构造函数配置格式
+constructor(options: { port: MessagePort } & AbstractChannelProtocolProps) {
+  super(options); // 传递配置给父类
+}
+```
+
+### 4. 类型定义合并
+
+**文件**: `src/types/messageChannel.ts`
+
+**改进**:
+- ✅ `AbstractChannelProtocolProps` 现在扩展自 `channel.ts` 中的基础定义
+- ✅ 保持向后兼容，添加了序列化相关字段
+
+## 使用方式变更
+
+### 之前的使用方式
+
+```typescript
+// 只能使用默认的 JSON
+const channel = new WebSocketChannel(socket);
+
+// 要使用其他格式，需要重写 getter
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    return new MessagePackReadBuffer(); // 需要手动实现
+  }
+}
+```
+
+### 现在的使用方式
+
+```typescript
+// 方式 1: 通过配置指定格式（推荐）
+const channel = new WebSocketChannel(socket, {
+  serializationFormat: 'msgpack'
+});
+
+// 方式 2: 使用自定义 buffer
+const channel = new MessageChannel({
+  port,
+  readBuffer: new MyCustomBuffer(),
+  writeBuffer: new MyCustomBuffer()
+});
+
+// 方式 3: 运行时切换
+channel.setSerializationFormat('cbor');
+```
+
+## 性能改进
+
+1. **缓存机制**: 所有 Channel 现在都使用缓存，避免重复创建 buffer 实例
+2. **延迟初始化**: Buffer 实例在首次访问时才创建
+3. **工厂模式**: 统一通过工厂创建，便于管理和优化
+
+## 向后兼容性
+
+✅ **完全向后兼容**
+
+- 默认行为保持不变（使用 JSON）
+- 不传配置时，行为与之前完全一致
+- 现有的重写 getter 的代码仍然有效
+
+## 迁移建议
+
+### 如果之前重写了 buffer getter
+
+**之前**:
+```typescript
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    return new ReadBuffer();
+  }
+}
+```
+
+**现在（推荐）**:
+```typescript
+// 方式 1: 使用配置（推荐）
+class MyChannel extends AbstractChannelProtocol {
+  constructor(options?: AbstractChannelProtocolProps) {
+    super({ serializationFormat: 'msgpack', ...options });
+  }
+  // 不需要重写 getter
+}
+
+// 方式 2: 继续重写（如果需要特殊逻辑）
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    if (this._readBuffer) return this._readBuffer;
+    this._readBuffer = BufferFactory.createReadBuffer('msgpack');
+    return this._readBuffer;
+  }
+}
+```
+
+## 新增功能
+
+1. **格式配置**: 通过构造函数配置序列化格式
+2. **运行时切换**: `setSerializationFormat()` 方法
+3. **格式查询**: `serializationFormat` getter
+4. **自动回退**: 格式不支持时自动回退到 JSON
+5. **自定义 buffer**: 支持直接传入自定义 buffer 实例
+
+## 测试建议
+
+1. **基础功能**: 验证默认 JSON 行为不变
+2. **格式配置**: 测试不同格式的配置和使用
+3. **缓存机制**: 验证 buffer 实例被正确缓存
+4. **格式切换**: 测试运行时格式切换
+5. **错误处理**: 测试不支持的格式时的回退机制
+
+## 相关文件
+
+- `src/buffer/BufferFactory.ts` - 工厂实现
+- `src/buffer/SerializationFormat.ts` - 格式定义
+- `src/buffer/README.md` - 使用文档
+- `src/buffer/ARCHITECTURE.md` - 架构说明
+- `src/buffer/OPTIMIZATION.md` - 优化说明
+
+## 总结
+
+本次优化实现了：
+- ✅ 统一的 buffer 管理机制
+- ✅ 灵活的配置方式
+- ✅ 性能优化（缓存）
+- ✅ 易于扩展（工厂模式）
+- ✅ 完全向后兼容
+
+这些改进让序列化系统更加健壮、灵活和高效，同时保持了良好的向后兼容性。

package/src/buffer/DataBuffer.ts

@@ -0,0 +1 @@
+export default class DataBuffer {}

package/src/buffer/MessagePackBuffer.ts

@@ -0,0 +1,79 @@
+import ReadBaseBuffer from './ReadBaseBuffer';
+import WriteBaseBuffer from './WriteBaseBuffer';
+import { SerializationFormat } from './SerializationFormat';
+
+/**
+ * MessagePack Read Buffer Implementation
+ *
+ * Note: This is a reference implementation. To use it, you need to install:
+ * npm install @msgpack/msgpack
+ *
+ * Usage:
+ * ```typescript
+ * import { encode, decode } from '@msgpack/msgpack';
+ *
+ * class MessagePackReadBuffer extends ReadBaseBuffer {
+ *   decode(data: string | ArrayBuffer | Uint8Array): any {
+ *     if (typeof data === 'string') {
+ *       // Convert string to Uint8Array if needed
+ *       const encoder = new TextEncoder();
+ *       const uint8Array = encoder.encode(data);
+ *       return decode(uint8Array);
+ *     }
+ *     return decode(data as Uint8Array);
+ *   }
+ *
+ *   getFormat(): string {
+ *     return SerializationFormat.MESSAGEPACK;
+ *   }
+ * }
+ * ```
+ */
+export class MessagePackReadBuffer extends ReadBaseBuffer {
+  decode(_data: string | ArrayBuffer | Uint8Array): any {
+    // This is a placeholder implementation
+    // In production, use: import { decode } from '@msgpack/msgpack';
+    throw new Error(
+      'MessagePack decoder not implemented. Please install @msgpack/msgpack and implement decode logic.'
+    );
+  }
+
+  getFormat(): string {
+    return SerializationFormat.MESSAGEPACK;
+  }
+}
+
+/**
+ * MessagePack Write Buffer Implementation
+ *
+ * Note: This is a reference implementation. To use it, you need to install:
+ * npm install @msgpack/msgpack
+ *
+ * Usage:
+ * ```typescript
+ * import { encode } from '@msgpack/msgpack';
+ *
+ * class MessagePackWriteBuffer extends WriteBaseBuffer {
+ *   encode(data: any): Uint8Array {
+ *     return encode(data);
+ *   }
+ *
+ *   getFormat(): string {
+ *     return SerializationFormat.MESSAGEPACK;
+ *   }
+ * }
+ * ```
+ */
+export class MessagePackWriteBuffer extends WriteBaseBuffer {
+  encode(_data: any): Uint8Array {
+    // This is a placeholder implementation
+    // In production, use: import { encode } from '@msgpack/msgpack';
+    throw new Error(
+      'MessagePack encoder not implemented. Please install @msgpack/msgpack and implement encode logic.'
+    );
+  }
+
+  getFormat(): string {
+    return SerializationFormat.MESSAGEPACK;
+  }
+}

package/src/buffer/OPTIMIZATION.md

@@ -0,0 +1,258 @@
+# Buffer 优化说明
+
+## 优化内容
+
+本次优化对 `async-call-rpc` 的 buffer 序列化机制进行了全面改进，实现了统一、可配置、高性能的序列化方案。
+
+## 主要改进
+
+### 1. ✅ 统一使用 BufferFactory
+
+**之前的问题：**
+- 每个 Channel 子类都直接创建 `new ReadBuffer()` / `new WriteBuffer()`
+- 无法统一管理序列化格式
+- 每次访问 getter 都创建新实例（性能问题）
+
+**优化后：**
+- 所有 Channel 统一使用 `BufferFactory` 创建 buffer
+- 支持通过配置指定序列化格式
+- 实现了实例缓存，避免重复创建
+
+### 2. ✅ 支持配置化序列化格式
+
+**新增功能：**
+- 在构造函数中通过 `serializationFormat` 参数指定格式
+- 支持运行时动态切换格式（`setSerializationFormat()`）
+- 支持自定义 buffer 实例（`readBuffer` / `writeBuffer` 参数）
+
+**使用示例：**
+
+```typescript
+// 方式 1: 通过配置指定格式
+const channel = new WebSocketChannel(socket, {
+  serializationFormat: 'msgpack' // 使用 MessagePack
+});
+
+// 方式 2: 使用自定义 buffer
+const customBuffer = new MyCustomBuffer();
+const channel = new MessageChannel({
+  port,
+  readBuffer: customBuffer,
+  writeBuffer: customBuffer
+});
+
+// 方式 3: 运行时切换格式
+channel.setSerializationFormat('cbor');
+```
+
+### 3. ✅ 优化缓存机制
+
+**之前的问题：**
+- `MessageChannel` 和 `WebSocketChannel` 每次访问都创建新实例
+- `AbstractChannelProtocol` 有缓存，但子类重写后失效
+
+**优化后：**
+- 所有 Channel 都使用父类的缓存机制
+- 首次访问时创建，后续访问复用实例
+- 格式切换时自动清理缓存
+
+### 4. ✅ 增强错误处理
+
+**新增功能：**
+- 格式不支持时自动回退到 JSON
+- 提供清晰的错误提示和警告
+- 支持自定义 buffer 的验证
+
+### 5. ✅ 改进类型定义
+
+**新增类型：**
+- `AbstractChannelProtocolProps` - 统一的配置接口
+- 所有 Channel 构造函数都支持序列化配置
+
+## 使用指南
+
+### 基础使用（默认 JSON）
+
+```typescript
+// 无需配置，默认使用 JSON
+const channel = new WebSocketChannel(socket);
+// 或者
+const channel = new MessageChannel({ port });
+```
+
+### 使用 MessagePack（高性能）
+
+```typescript
+// 1. 先注册 MessagePack（如果还没注册）
+import { registerMessagePack } from '@x-oasis/async-call-rpc/buffer/examples';
+registerMessagePack();
+
+// 2. 创建 Channel 时指定格式
+const channel = new WebSocketChannel(socket, {
+  serializationFormat: 'msgpack'
+});
+```
+
+### 使用自定义格式
+
+```typescript
+// 1. 实现自定义 buffer
+class MyCustomBuffer extends ReadBaseBuffer {
+  decode(data: any): any {
+    // 自定义解码逻辑
+  }
+  getFormat(): string {
+    return 'my-format';
+  }
+}
+
+// 2. 注册到工厂
+import { BufferFactory } from '@x-oasis/async-call-rpc/buffer';
+BufferFactory.registerReadBuffer('my-format', () => new MyCustomBuffer());
+
+// 3. 使用
+const channel = new MessageChannel({
+  port,
+  serializationFormat: 'my-format'
+});
+```
+
+### 运行时切换格式
+
+```typescript
+const channel = new WebSocketChannel(socket);
+
+// 初始使用 JSON
+console.log(channel.serializationFormat); // 'json'
+
+// 切换到 MessagePack
+channel.setSerializationFormat('msgpack');
+console.log(channel.serializationFormat); // 'msgpack'
+
+// 下次访问 buffer 时会使用新格式
+```
+
+## 性能优化
+
+### 缓存机制
+
+```typescript
+// 第一次访问：创建实例
+const buffer1 = channel.readBuffer; // 创建新实例
+
+// 后续访问：复用缓存
+const buffer2 = channel.readBuffer; // 返回缓存的实例
+console.log(buffer1 === buffer2); // true
+```
+
+### 格式切换
+
+```typescript
+// 切换格式时，缓存会被清理
+channel.setSerializationFormat('msgpack');
+
+// 下次访问时会创建新实例
+const buffer3 = channel.readBuffer; // 创建新的 MessagePack 实例
+console.log(buffer1 === buffer3); // false
+```
+
+## 迁移指南
+
+### 从旧版本迁移
+
+**之前：**
+```typescript
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    return new ReadBuffer(); // 每次都创建新实例
+  }
+  
+  get writeBuffer() {
+    return new WriteBuffer();
+  }
+}
+```
+
+**现在（推荐）：**
+```typescript
+// 方式 1: 使用配置（推荐）
+class MyChannel extends AbstractChannelProtocol {
+  constructor(options?: AbstractChannelProtocolProps) {
+    super({ serializationFormat: 'msgpack', ...options });
+  }
+  // 不需要重写 getter，使用父类的实现
+}
+
+// 方式 2: 继续重写（如果需要特殊逻辑）
+class MyChannel extends AbstractChannelProtocol {
+  get readBuffer() {
+    // 使用工厂创建，支持缓存
+    if (this._readBuffer) return this._readBuffer;
+    this._readBuffer = BufferFactory.createReadBuffer('msgpack');
+    return this._readBuffer;
+  }
+}
+```
+
+## 配置选项
+
+### AbstractChannelProtocolProps
+
+```typescript
+interface AbstractChannelProtocolProps {
+  description?: string;
+  masterProcessName?: string;
+  connected?: boolean;
+  serializationFormat?: string;  // 序列化格式：'json' | 'msgpack' | 'cbor' | ...
+  readBuffer?: ReadBaseBuffer;   // 自定义读 buffer（覆盖 serializationFormat）
+  writeBuffer?: WriteBaseBuffer; // 自定义写 buffer（覆盖 serializationFormat）
+}
+```
+
+## 最佳实践
+
+1. **开发环境使用 JSON**：便于调试和查看数据
+   ```typescript
+   const format = process.env.NODE_ENV === 'production' ? 'msgpack' : 'json';
+   const channel = new WebSocketChannel(socket, { serializationFormat: format });
+   ```
+
+2. **生产环境使用 MessagePack**：提升性能
+   ```typescript
+   const channel = new WebSocketChannel(socket, { 
+     serializationFormat: 'msgpack' 
+   });
+   ```
+
+3. **统一配置**：在应用入口统一配置序列化格式
+   ```typescript
+   const RPC_CONFIG = {
+     serializationFormat: process.env.RPC_FORMAT || 'json'
+   };
+   
+   const channel = new WebSocketChannel(socket, RPC_CONFIG);
+   ```
+
+4. **错误处理**：监听格式不支持的情况
+   ```typescript
+   try {
+     const channel = new WebSocketChannel(socket, { 
+       serializationFormat: 'msgpack' 
+     });
+   } catch (error) {
+     // 会自动回退到 JSON，但会输出警告
+     console.warn('MessagePack not available, using JSON');
+   }
+   ```
+
+## 总结
+
+通过本次优化，`async-call-rpc` 的 buffer 系统现在具备：
+
+- ✅ **统一管理**：通过 BufferFactory 统一创建和管理
+- ✅ **配置灵活**：支持多种配置方式
+- ✅ **性能优化**：实例缓存，避免重复创建
+- ✅ **易于扩展**：支持自定义格式和实现
+- ✅ **向后兼容**：默认行为保持不变（使用 JSON）
+
+这些改进让序列化系统更加健壮、灵活和高效。