Hyperliquid项目中WebSocketTransport连接关闭问题的技术分析

Hyperliquid项目中WebSocketTransport连接关闭问题的技术分析

问题背景

在Hyperliquid项目的WebSocketTransport实现中，当尝试关闭一个处于连接状态(connecting)的WebSocket连接时，发现关闭操作无法正常完成。这个问题在Node.js 24以下版本和Bun 1.2.15环境中尤为明显。

问题本质

该问题的核心在于不同JavaScript运行时环境下WebSocket API实现的差异。具体表现为：

1. Node.js 24以下版本：当WebSocket处于连接状态时调用close()方法，不会触发'close'事件，导致基于Promise的关闭操作永远无法resolve。

2. Bun 1.2.15版本：同样存在类似问题，关闭连接状态的WebSocket不会触发任何事件。

3. Node.js 24及以上版本：行为符合预期，关闭操作能正常触发'close'事件。

技术细节分析

WebSocket状态管理

WebSocket连接有以下几种状态：

• CONNECTING：正在建立连接
• OPEN：连接已建立
• CLOSING：正在关闭连接
• CLOSED：连接已关闭

问题主要出现在CONNECTING状态下调用close()方法时的行为不一致。

实现机制差异

在Node.js 24以下版本中，底层WebSocket实现存在缺陷：

• 当WebSocket处于CONNECTING状态时，调用close()方法不会触发任何事件
• 连接状态不会自动更新为CLOSED
• 没有错误事件被触发

而在符合规范的实现中，关闭一个连接中的WebSocket应该：

1. 立即将状态改为CLOSING
2. 尝试终止连接过程
3. 最终触发'close'事件并将状态改为CLOSED

解决方案探讨

短期解决方案

对于必须使用旧版本Node.js的用户，可以采用以下临时方案：

1. 使用AbortSignal：WebSocketTransport.close()方法支持传入AbortSignal，可以设置超时强制终止等待。

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000); // 5秒超时
await transport.close({ signal: controller.signal });

2. 错误事件监听：在Node.js环境中，可以将'error'事件也作为关闭完成的信号。

长期解决方案

项目维护者决定：

1. 将最低Node.js版本要求提升至24.x
2. 不针对特定运行时的非标准行为进行特殊处理
3. 在文档中明确说明运行环境要求

最佳实践建议

1. 环境选择：推荐使用Node.js 24+或符合Web标准的其他运行时环境。

2. 连接管理：

   • 对于长时间处于CONNECTING状态的连接，应主动设置超时
   • 考虑使用ReconnectingWebSocket自带的连接超时机制

3. 错误处理：始终为WebSocket连接添加错误处理逻辑，特别是在网络不稳定的环境下。

总结

WebSocket实现在不同JavaScript运行时中的行为差异是常见问题。Hyperliquid项目通过明确环境要求而非增加特殊处理代码的方式，保持了代码的简洁性和可维护性。开发者在使用时应注意运行环境的选择和适当的错误处理策略，以确保WebSocket连接的可靠性。

对于必须使用旧版本Node.js的开发者，可以通过AbortSignal机制实现超时控制，这是目前最可靠的解决方案。随着Node.js 24+的普及，这一问题将自然得到解决。