format

Author: HuakunShen

.journal/2025-01-27.md

@@ -3,15 +3,18 @@
 ## Breaking Change: IoInterface Redesign for Transferable Objects Support
 
 ### Core Decision/Topic
+
 Redesigned the `IoInterface` contract to support transferable objects and structured clone messaging, moving from centralized buffer handling to adapter-level data format conversion.
 
 ### Options Considered
 
 1. **Keep centralized conversion** (main branch approach)
+
    - Pros: No breaking changes, simple for adapters
    - Cons: Can't support transferables, type contracts are unclear, hidden complexity
 
 2. **Move conversion to adapters** (chosen approach)
+
    - Pros: Clean separation of concerns, enables transferables, explicit type contracts
    - Cons: Breaking change, requires adapter updates
 
@@ -24,6 +27,7 @@ Redesigned the `IoInterface` contract to support transferable objects and struct
 **Chose option 2**: Move data format conversion responsibility to adapters.
 
 **Rationale:**
+
 - Enables transferable objects feature (primary goal)
 - Cleaner architecture with explicit responsibilities
 - Better type safety and clearer contracts
@@ -33,27 +37,30 @@ Redesigned the `IoInterface` contract to support transferable objects and struct
 ### Key Changes Made
 
 #### Interface Changes (BREAKING)
+
 ```typescript
 // OLD
 interface IoInterface {
-  read(): Promise<Uint8Array | string | null>
-  write(data: string): Promise<void>
+	read(): Promise<Uint8Array | string | null>
+	write(data: string): Promise<void>
 }
 
-// NEW  
+// NEW
 interface IoInterface {
-  read(): Promise<string | IoMessage | null>
-  write(message: string | IoMessage): Promise<void>
-  capabilities?: IoCapabilities
+	read(): Promise<string | IoMessage | null>
+	write(message: string | IoMessage): Promise<void>
+	capabilities?: IoCapabilities
 }
 ```
 
 #### Channel Changes
+
 - Removed centralized `TextDecoder` buffer conversion
 - Now expects clean string/IoMessage from adapters
 - Added support for structured clone and transferable objects
 
 #### Adapter Updates Required
+
 - **WebSocket**: Added Buffer→string conversion in `onmessage` handlers
 - **All adapters**: Must now handle their own data format conversion
 - **New adapters**: Can declare capabilities for transferables
@@ -63,19 +70,21 @@ interface IoInterface {
 **Severity: MAJOR** (requires major version bump)
 
 **Affected:**
+
 - All custom `IoInterface` implementations
 - Any code depending on `Uint8Array` return type from `read()`
 - Adapters that relied on centralized buffer conversion
 
 **Migration Required:**
+
 ```typescript
 // OLD adapter
 async read(): Promise<Uint8Array | string | null> {
   const data = await this.source.read()
   return data // Could be Buffer/Uint8Array
 }
 
-// NEW adapter  
+// NEW adapter
 async read(): Promise<string | IoMessage | null> {
   const data = await this.source.read()
   // Must convert to string here
@@ -90,10 +99,11 @@ async read(): Promise<string | IoMessage | null> {
 **Root Cause:** The old design had a type lie - WebSocket adapter was typed as returning `string` but actually returned `Buffer` on server side.
 
 **Solution:** Added explicit Buffer→string conversion in WebSocket adapters:
+
 ```typescript
 // Works in both Node.js and browsers
 if (typeof message === "object" && message !== null && "toString" in message) {
-  message = message.toString("utf-8")
+	message = message.toString("utf-8")
 }
 ```
 
@@ -121,4 +131,4 @@ if (typeof message === "object" && message !== null && "toString" in message) {
 
 ---
 
-*This entry documents the architectural decision to redesign IoInterface for transferable objects support, including the breaking change impact and migration requirements.*
+_This entry documents the architectural decision to redesign IoInterface for transferable objects support, including the breaking change impact and migration requirements._

.journal/2025-11-02.md

@@ -3,14 +3,17 @@
 ## Core Decision/Topic: Elysia WebSocket Adapter Development
 
 ### Overview
+
 Today marked significant progress on adding **Elysia WebSocket adapter support** to the kkrpc library, expanding our cross-runtime compatibility to include the modern TypeScript web framework Elysia.
 
 ### Options Considered
+
 1. **Elysia WebSocket Integration**: Adding native support for Elysia's built-in WebSocket functionality powered by uWebSocket
 2. **Standard WebSocket Compatibility**: Ensuring the adapter works with standard WebSocket API for broad compatibility
 3. **Bidirectional Communication**: Maintaining kkrpc's core principle of bi-directional RPC communication
 
 ### Final Decision & Rationale
+
 **Decided to implement a comprehensive Elysia WebSocket adapter** with the following architecture:
 
 - **ElysiaWebSocketServerIO**: Server-side adapter that integrates with Elysia's WebSocket lifecycle
@@ -22,18 +25,22 @@ Today marked significant progress on adding **Elysia WebSocket adapter support**
 ### Key Changes Made
 
 #### New Files Created:
+
 - `packages/kkrpc/src/adapters/elysia-websocket.ts` - Main adapter implementation (470 lines)
 - `packages/kkrpc/__tests__/elysia-websocket.test.ts` - Comprehensive test suite (363 lines)
 - `packages/kkrpc/elysia-websocket.ts` - Public export file for the adapter
 
 #### Core Features Implemented:
+
 1. **Server-Side Integration**:
+
    - Automatic message routing through Elysia's WebSocket handlers
    - Connection information extraction (remote address, query params, headers)
    - Graceful error handling and cleanup
    - Support for both `ws.raw` and standard WebSocket interfaces
 
 2. **Client-Side Implementation**:
+
    - Standard WebSocket API compatibility across runtimes (Bun/Deno/Node.js)
    - Automatic connection waiting with Promise-based readiness
    - Cross-platform WebSocket instantiation
@@ -46,35 +53,41 @@ Today marked significant progress on adding **Elysia WebSocket adapter support**
    - Bidirectional communication verification
 
 #### Technical Implementation Details:
+
 - **Message Processing**: Handles string, ArrayBuffer, and object messages with automatic conversion
 - **Reference Management**: Proper cleanup of WebSocket references to prevent memory leaks
 - **Capability Declaration**: Explicitly declares no support for structuredClone or transfer for now
 - **Destroy Signals**: Implements clean shutdown signaling mechanism
 
 ### Package Updates:
+
 - Updated `packages/kkrpc/mod.ts` to include Elysia WebSocket exports
 - Modified `packages/kkrpc/package.json` dependencies for Elysia support
 - Updated build configuration in `tsdown.config.ts`
 
 ### Development Environment Setup:
+
 - Added `.python-version` and Python-related files for potential cross-language tooling
 - Enhanced `.claude/` configuration for improved AI assistance
 - Updated `.gitignore` to exclude new development artifacts
 
 ### Future Considerations
+
 1. **Performance Optimization**: Consider adding support for transferable objects and structured clone for zero-copy messaging
 2. **Documentation**: Add comprehensive examples to the main documentation
 3. **TypeScript Enhancements**: Improve type inference for Elysia-specific features
 4. **Error Handling**: Enhance error serialization across Elysia WebSocket boundaries
 
 ### Technical Debt & Remaining Work
+
 - Need to update main README.md with Elysia examples
 - Consider adding Elysia-specific demos to the examples directory
 - Potential integration with Elysia's plugin system for even tighter integration
 
 ### Impact Assessment
+
 This implementation significantly expands kkrpc's ecosystem compatibility, making it a compelling choice for developers using modern TypeScript frameworks. The adapter maintains the library's core principles while providing idiomatic Elysia integration patterns.
 
 ---
 
-*Entry created: 2025-11-02T14:30:00Z*
+_Entry created: 2025-11-02T14:30:00Z_

.journal/2025-11-04-redis-streams-improvements.md

@@ -11,6 +11,7 @@
 **问题**: 原实现的 `messageQueue` 没有大小限制，如果消息到达速度超过消费速度，可能导致内存溢出。
 
 **解决方案**:
+
 - 添加 `maxQueueSize` 配置选项（默认 1000 条消息）
 - 队列满时自动丢弃最老的消息，并记录警告日志
 - 提示用户考虑增加 `maxQueueSize` 或加快消息处理速度
@@ -27,6 +28,7 @@ interface RedisStreamsOptions {
 ```
 
 **实现细节**:
+
 ```typescript
 private handleMessage(message: string): void {
 	// ...
@@ -47,29 +49,31 @@ private handleMessage(message: string): void {
 **问题**: 原实现没有对配置选项进行验证，可能导致运行时错误。
 
 **解决方案**:
+
 - 添加 `validateOptions` 方法，在构造函数中验证所有配置
 - 验证类型、范围、整数要求等
 - 无效配置立即抛出异常，提供清晰的错误信息
 
 **验证规则**:
+
 - `blockTimeout`: 必须是非负整数
 - `maxLen`: 必须是正整数
 - `maxQueueSize`: 必须是正整数
 - `url`, `stream`, `consumerGroup`, `consumerName`: 必须是字符串
 
 ```typescript
 private validateOptions(options: RedisStreamsOptions): void {
-	if (options.blockTimeout !== undefined && 
+	if (options.blockTimeout !== undefined &&
 	    (options.blockTimeout < 0 || !Number.isInteger(options.blockTimeout))) {
 		throw new Error("blockTimeout must be a non-negative integer")
 	}
 
-	if (options.maxLen !== undefined && 
+	if (options.maxLen !== undefined &&
 	    (options.maxLen <= 0 || !Number.isInteger(options.maxLen))) {
 		throw new Error("maxLen must be a positive integer")
 	}
 
-	if (options.maxQueueSize !== undefined && 
+	if (options.maxQueueSize !== undefined &&
 	    (options.maxQueueSize <= 0 || !Number.isInteger(options.maxQueueSize))) {
 		throw new Error("maxQueueSize must be a positive integer")
 	}
@@ -83,6 +87,7 @@ private validateOptions(options: RedisStreamsOptions): void {
 **问题**: 原实现只支持 XREAD（pub/sub 模式），在高吞吐量场景下可能不够高效。
 
 **解决方案**:
+
 - 添加 `useConsumerGroup` 配置选项
 - 支持两种消息消费模式：
   - **Pub/Sub 模式**（默认，`useConsumerGroup: false`）: 使用 XREAD，所有 consumer 都能收到所有消息
@@ -101,6 +106,7 @@ interface RedisStreamsOptions {
 ```
 
 **实现细节**:
+
 - 在 pub/sub 模式下，使用 XREAD，不创建 consumer group
 - 在 consumer group 模式下，使用 XREADGROUP，自动创建 consumer group，并在处理完消息后 ACK
 - 根据模式选择不同的连接初始化和消息读取逻辑
@@ -139,10 +145,12 @@ else {
 添加了完整的测试覆盖：
 
 1. **配置验证测试**:
+
    - 测试所有无效配置会抛出正确的错误
    - 测试有效配置能正常创建 adapter
 
 2. **内存管理测试**:
+
    - 测试队列大小限制功能
    - 验证队列满时正确丢弃老消息
 
@@ -155,15 +163,15 @@ else {
 ```typescript
 /**
  * Redis Streams implementation of IoInterface
- * 
+ *
  * 支持两种消息消费模式:
  * 1. Pub/Sub 模式 (默认): 使用 XREAD，所有 consumer 都能收到所有消息
  * 2. Consumer Group 模式: 使用 XREADGROUP，每条消息只被一个 consumer 处理 (负载均衡)
- * 
+ *
  * 内存管理:
  * - 支持最大队列大小限制 (maxQueueSize)，防止消息积压导致内存问题
  * - 队列满时自动丢弃最老的消息并记录警告
- * 
+ *
  * 配置验证:
  * - 构造时验证所有配置选项的类型和范围
  * - 无效配置会立即抛出异常
@@ -173,6 +181,7 @@ else {
 ## 使用示例
 
 ### 基本用法（Pub/Sub 模式）
+
 ```typescript
 const io = new RedisStreamsIO({
 	url: "redis://localhost:6379",
@@ -182,6 +191,7 @@ const io = new RedisStreamsIO({
 ```
 
 ### Consumer Group 模式（负载均衡）
+
 ```typescript
 const io = new RedisStreamsIO({
 	url: "redis://localhost:6379",
@@ -196,13 +206,15 @@ const io = new RedisStreamsIO({
 ## 测试结果
 
 所有新测试通过：
+
 - ✅ 配置验证测试（8 个测试用例）
 - ✅ 内存管理测试（队列大小限制）
 - ✅ Consumer Group 模式测试（2 个场景）
 
 ## 总结
 
 这些改进使 Redis Streams adapter 更加健壮和灵活：
+
 1. **更安全**: 配置验证防止运行时错误，队列大小限制防止内存溢出
 2. **更灵活**: 支持两种消息消费模式，适应不同的使用场景
 3. **更可靠**: 完整的测试覆盖确保功能正常工作
@@ -211,8 +223,8 @@ const io = new RedisStreamsIO({
 ## 未来考虑
 
 Code review 还提到的其他建议（暂未实现）：
+
 - **Enhanced Error Scenarios**: 添加更多网络故障、Redis 不可用等错误场景的测试
 - **Connection Pooling**: 实现连接池以提高资源管理效率
 - **Monitoring**: 添加 metrics 和监控钩子
 - **Dead Letter Queues**: 支持失败消息处理的 DLQ
-