Caddy服务器中HTTP/2 WebSocket连接问题分析与解决方案

问题背景

在Caddy服务器的最新版本中，当启用内容编码(encode)功能时，部分WebSocket连接会出现失败的情况。这个问题主要出现在HTTP/2协议下，且当客户端需要发送第一条消息的WebSocket连接场景中。

技术原理分析

WebSocket协议在HTTP/2下的实现与HTTP/1.x有所不同。在HTTP/1.x中，WebSocket升级过程会明确返回101状态码，而在HTTP/2中，成功的WebSocket连接会返回200状态码，因为HTTP/2使用CONNECT方法来建立隧道。

Caddy的内容编码功能在处理响应时，会根据响应内容决定是否进行编码。这个决策过程会导致在HTTP/2 WebSocket连接中出现以下问题：

1. 当客户端请求包含"accept-encoding"头时，编码响应器会立即写入信息性头部
2. 在HTTP/1.x中，WebSocket升级会明确写入101状态码并立即刷新到客户端
3. 在HTTP/2中，虽然调用了FlushError，但响应码是200，与表示成功的其他状态码相同
4. 编码模块会存储这个状态码，直到确定响应是否可以编码后才刷新

问题表现

当WebSocket传输协议要求客户端先发送数据时，由于响应永远不会被发送，客户端会认为握手没有完成，导致连接卡住。这种情况在以下场景特别明显：

• 使用HTTP/2协议
• 启用了内容编码功能
• WebSocket协议要求客户端先发送消息

临时解决方案

目前可以通过添加匹配规则来忽略HTTP/2 WebSocket升级的编码：

@not_h2_ws not {
    header :protocol *
    method CONNECT
    protocol http/2
}
encode @not_h2_ws zstd gzip

根本解决方案建议

从技术原理上看，更优雅的解决方案应该考虑以下几点：

1. 对于所有CONNECT请求，应该给予"identity"处理
2. 需要正确处理HTTP/2 WebSocket特有的伪头部字段转换
3. 在编码决策过程中，应该特别处理WebSocket升级场景

RFC规范明确指出，CONNECT请求用于建立到远程主机的隧道，200状态码表示连接成功。服务器应该在此之后盲目转发客户端和远程主机之间的数据包。在WebSocket over HTTP/2场景中，这一原则同样适用。

总结

这个问题揭示了在实现现代Web协议时需要考虑的复杂性，特别是当多个协议特性(如HTTP/2、WebSocket和内容编码)交互时。Caddy作为现代化的Web服务器，需要在这些场景中提供既符合规范又用户友好的解决方案。

对于开发者而言，理解这些底层协议交互原理有助于更好地调试和解决类似问题。同时，这也提醒我们在实现协议转换和内容处理功能时，需要全面考虑各种使用场景。