用 Rust 从零实现 WebSocket:握手和帧协议到底怎么写的
用
tokio-tungstenite建 WebSocket 连接只要三行。但协议升级那一瞬间发生了什么,多数人没细看过。
WebSocket 的设计很巧妙:它借道 HTTP 完成升级,之后就跑自己的协议。 这样能穿过只为 HTTP 开洞的代理和防火墙。
这篇从零实现协议本身:握手怎么校验、Accept key 怎么算、帧怎么编解码。
第一步:升级握手
客户端发来的请求长这样:
GET /chat HTTP/1.1\r\n
Host: example.com\r\n
Upgrade: websocket\r\n
Connection: Upgrade\r\n
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n
Sec-WebSocket-Version: 13\r\n
\r\n服务端要做的校验:
pub struct UpgradeRequest {
pub key: String,
pub version: String,
pub path: String,
}
pub fn validate_upgrade(headers: &[(String, String)], path: &str) -> Result<UpgradeRequest, String> {
let get = |name: &str| {
headers
.iter()
.find(|(k, _)| k.eq_ignore_ascii_case(name))
.map(|(_, v)| v.as_str())
};
// 1. Upgrade 必须是 websocket
match get("upgrade") {
Some(v) if v.eq_ignore_ascii_case("websocket") => {}
_ => return Err("missing or invalid Upgrade header".into()),
}
// 2. Connection 里必须包含 Upgrade(注意可能是逗号分隔的列表)
let connection_ok = get("connection")
.map(|v| v.split(',').any(|s| s.trim().eq_ignore_ascii_case("upgrade")))
.unwrap_or(false);
if !connection_ok {
return Err("missing Connection: Upgrade".into());
}
// 3. 版本必须是 13
let version = get("sec-websocket-version").unwrap_or("");
if version != "13" {
return Err(format!("unsupported websocket version: {version}"));
}
// 4. 必须有 key
let key = get("sec-websocket-key")
.ok_or("missing Sec-WebSocket-Key")?
.to_string();
Ok(UpgradeRequest { key, version: version.into(), path: path.into() })
}Connection 头可能是 keep-alive, Upgrade,所以必须按逗号拆分再比较。直接 == "upgrade" 会漏掉一大类客户端——这是自研实现里非常常见的兼容性 bug。
第二步:算 Sec-WebSocket-Accept
这一步看起来最"魔法",规则其实只有一句话:
把客户端的 key 拼上固定的 GUID,做一次 SHA-1,再 Base64。
那个固定的 GUID 是写死在 RFC 里的:
const WS_GUID: &str = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";计算:
use sha1::{Digest, Sha1};
pub fn compute_accept(key: &str) -> String {
let mut hasher = Sha1::new();
hasher.update(key.as_bytes());
hasher.update(WS_GUID.as_bytes());
let digest = hasher.finalize();
base64_encode(&digest)
}手写一个不带依赖的 Base64 编码也不难(标准表的 64 个字符):
const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
pub fn base64_encode(data: &[u8]) -> String {
let mut out = String::new();
for chunk in data.chunks(3) {
let b = [
chunk[0],
*chunk.get(1).unwrap_or(&0),
*chunk.get(2).unwrap_or(&0),
];
let n = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | (b[2] as u32);
out.push(B64[((n >> 18) & 63) as usize] as char);
out.push(B64[((n >> 12) & 63) as usize] as char);
out.push(if chunk.len() > 1 { B64[((n >> 6) & 63) as usize] as char } else { '=' });
out.push(if chunk.len() > 2 { B64[(n & 63) as usize] as char } else { '=' });
}
out
}为什么这个 GUID 存在? 它不是为了安全(key 是明文传输的),而是为了防止一个纯 HTTP 客户端被误认为 WebSocket 客户端。一个普通浏览器请求不可能恰好带上正确的 Sec-WebSocket-Key 并期望这个特定的响应。这是协议层的"握手防误撞",不是加密。
响应:
HTTP/1.1 101 Switching Protocols\r\n
Upgrade: websocket\r\n
Connection: Upgrade\r\n
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n
\r\n状态码必须是 101,而且头部之后立刻结束,之后就是二进制帧了。
101 之后,这个连接就不再是 HTTP 了。 很多实现出 bug 就在这一步:还在用 HTTP 的解析器去读后面的数据。
第三步:帧格式
WebSocket 的帧结构,前两个字节信息量很大:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len | Extended payload length |
|I|S|S|S| (4) |A| (7) | (16/64) |
|N|V|V|V| |S| | (if payload len==126/127) |
| |1|2|3| |K| | |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
| Extended payload length continued, if payload len == 127 |
+ - - - - - - - - - - - - - - - +-------------------------------+
| |Masking-key, if MASK set to 1 |
+-------------------------------+-------------------------------+
| Masking-key (continued) | Payload Data |
+-------------------------------- - - - - - - - - - - - - - - - +拆开看:
- FIN(1 bit):是不是分片的最后一帧
- RSV1-3(3 bit):留给扩展用,不用时必须是 0
- opcode(4 bit):帧类型
- MASK(1 bit):payload 是否被掩码
- payload len(7 bit):长度,或"看后面的扩展长度"
opcode 的取值:
| 值 | 类型 |
|---|---|
| 0x0 | continuation(分片的后续帧) |
| 0x1 | text |
| 0x2 | binary |
| 0x8 | close |
| 0x9 | ping |
| 0xA | pong |
第四步:解码帧
长度字段是第一个坑:7 bit 的长度不够用时,用一个魔数指示"后面还有扩展长度"。
pub struct Frame {
pub fin: bool,
pub opcode: u8,
pub payload: Vec<u8>,
}
pub fn read_frame(reader: &mut impl std::io::Read) -> std::io::Result<Frame> {
let mut header = [0u8; 2];
reader.read_exact(&mut header)?;
let fin = header[0] & 0x80 != 0;
let opcode = header[0] & 0x0F;
let masked = header[1] & 0x80 != 0;
let len7 = (header[1] & 0x7F) as u64;
// 解析长度
let len = match len7 {
126 => {
let mut ext = [0u8; 2];
reader.read_exact(&mut ext)?;
u16::from_be_bytes(ext) as u64
}
127 => {
let mut ext = [0u8; 8];
reader.read_exact(&mut ext)?;
u64::from_be_bytes(ext)
}
n => n,
};
// 读取掩码 key
let mask = if masked {
let mut m = [0u8; 4];
reader.read_exact(&mut m)?;
Some(m)
} else {
None
};
// 读取 payload
let mut payload = vec![0u8; len as usize];
reader.read_exact(&mut payload)?;
// 应用掩码
if let Some(m) = mask {
for (i, byte) in payload.iter_mut().enumerate() {
*byte ^= m[i % 4];
}
}
Ok(Frame { fin, opcode, payload })
}注意 126/127 只是"哨兵值",不是真实长度。 真实长度在后面 2 或 8 字节里。写错的话,大于 125 字节的消息全会解析错。
第五步:掩码规则——一个容易记反的约定
这里有一条非常明确、也非常容易记反的规则:
客户端发给服务端的帧必须掩码(MASK = 1);服务端发给客户端的帧必须不掩码(MASK = 0)。
// 服务端写帧:不加掩码
pub fn write_frame(
out: &mut impl std::io::Write,
opcode: u8,
payload: &[u8],
fin: bool,
) -> std::io::Result<()> {
let mut header = Vec::with_capacity(10);
header.push(if fin { 0x80 | opcode } else { opcode });
let len = payload.len();
if len < 126 {
header.push(len as u8);
} else if len <= u16::MAX as usize {
header.push(126);
header.extend_from_slice(&(len as u16).to_be_bytes());
} else {
header.push(127);
header.extend_from_slice(&(len as u64).to_be_bytes());
}
out.write_all(&header)?;
out.write_all(payload)?;
Ok(())
}如果服务端也加了掩码,浏览器会直接断开连接。 如果客户端不加掩码,服务端应该关闭连接(RFC 要求)。
掩码的作用不是为了加密(算法是公开的 XOR),而是防止代理缓存投毒:早期一些中间设备会缓存它看不懂的二进制流,掩码让攻击者无法构造"看起来像 HTTP 响应"的 payload 来污染缓存。这是历史教训换来的设计。
第六步:分片
FIN 位和 continuation opcode 组成分片机制。一条大消息被切成多帧:
帧1: FIN=0, opcode=0x1(text), payload="Hello "
帧2: FIN=0, opcode=0x0(cont), payload="World"
帧3: FIN=1, opcode=0x0(cont), payload="!"接收方的组装逻辑:
pub struct FrameAssembler {
buffer: Vec<u8>,
message_opcode: u8,
}
impl FrameAssembler {
pub fn push(&mut self, frame: Frame) -> Option<(u8, Vec<u8>)> {
// 控制帧(>= 0x8)不参与分片
if frame.opcode >= 0x8 {
return Some((frame.opcode, frame.payload));
}
// 第一帧记录消息类型
if frame.opcode != 0x0 {
self.message_opcode = frame.opcode;
}
self.buffer.extend_from_slice(&frame.payload);
if frame.fin {
let msg = std::mem::take(&mut self.buffer);
return Some((self.message_opcode, msg));
}
None
}
}控制帧(ping/pong/close)不能分片,也不能被分片打断顺序。 一个常见错误是把 ping 也当分片处理,导致消息永远组不完整。上面的 if frame.opcode >= 0x8 就是在拦住这种情况。
第七步:心跳和关闭
WebSocket 的长连接需要保活。ping/pong 就是协议级的"你还在吗":
// 收到 ping,回 pong(payload 必须原样带回)
0x9 => {
write_frame(&mut stream, 0xA, &frame.payload, true)?;
}pong 必须带回和 ping 相同的 payload。 这是给应用层做往返延迟测量用的。
关闭握手是双向的:
0x8 => {
// 解析关闭码(前 2 字节,大端)
let code = if frame.payload.len() >= 2 {
u16::from_be_bytes([frame.payload[0], frame.payload[1]])
} else {
1000
};
// 回一个 close,然后关连接
let mut reply = code.to_be_bytes().to_vec();
write_frame(&mut stream, 0x8, &reply, true)?;
reply_payload = Some(code);
}关闭码有语义(RFC 定了一组标准值):
| 码 | 含义 |
|---|---|
| 1000 | 正常关闭 |
| 1001 | 端点离开(如页面关闭) |
| 1002 | 协议错误 |
| 1009 | 消息太大 |
| 1011 | 服务端内部错误 |
注意到 1009 了吗?消息太大要主动关。 这是必须做的防护:不然一个客户端发个 2GB 的帧,你的 vec![0u8; len] 直接 OOM。
const MAX_FRAME_SIZE: u64 = 16 * 1024 * 1024;
if len > MAX_FRAME_SIZE {
write_close(&mut stream, 1009)?;
return Ok(());
}任何"按声明长度分配内存"的协议实现,都必须有长度上限。 这是 DoS 防护的第一原则。
第八步:握手之后的循环
pub fn handle_ws(mut stream: TcpStream) -> std::io::Result<()> {
// 1. 读完 HTTP 头部并校验
let req = read_http_upgrade(&mut stream)?;
let accept = compute_accept(&req.key);
// 2. 发 101 响应
write!(
stream,
"HTTP/1.1 101 Switching Protocols\r\n\
Upgrade: websocket\r\n\
Connection: Upgrade\r\n\
Sec-WebSocket-Accept: {accept}\r\n\r\n"
)?;
stream.flush()?;
// 3. 之后就是纯帧协议了
let mut assembler = FrameAssembler::default();
loop {
let frame = read_frame(&mut stream)?;
match frame.opcode {
0x8 => { /* close 握手 */ break; }
0x9 => { write_frame(&mut stream, 0xA, &frame.payload, true)?; }
0xA => { /* pong,更新心跳时间 */ }
_ => {
if let Some((opcode, msg)) = assembler.push(frame) {
// 业务处理:text 或 binary
handle_message(opcode, &msg);
}
}
}
}
Ok(())
}关键提醒:read_http_upgrade 必须是"精确读取到 \r\n\r\n",不能多读一个字节——因为多读的那部分可能已经是第一个帧了。这就是前面 HTTP 服务器里同一个问题:TCP 无边界。
如果用的是带缓冲的 reader,切换协议时要小心缓冲区里残留的数据。这是协议升级实现里最隐蔽的一类 bug:握手之后第一条消息丢了。
结论
WebSocket 的"魔法"拆开就是两步:
握手靠一个固定的 GUID + SHA-1 + Base64 生成 Accept;之后跑自定义帧协议——7 bit 长度不够时用 126/127 扩展,客户端帧必须掩码、服务端必须不掩码,控制帧不能分片。
还有一个贯穿始终的原则:握手完成的那一刻就是 HTTP 和 WebSocket 的分界线,缓冲区里不能有任何"多余"或"不足"的字节。 这跟上一篇 HTTP 解析是同一个约束,只是这次它更致命。