返回文章列表

用 Rust 从零实现 WebSocket:握手和帧协议到底怎么写的

557 字·5 分钟阅读
Rust从零造轮子网络编程

用 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 解析是同一个约束,只是这次它更致命。