基于 Boost 的 HTTP 服务器:HTTP 协议细节
基于 Boost 的 HTTP 服务器:HTTP 协议细节
本文是 http_server 系列的协议篇,对应总览中的功能地图
展开四个核心协议特性的语义与实现:304 条件请求、Range 断点续传、gzip 协商、405/OPTIONShttp_server
条件请求:ETag 与 304
请求条件头的语义
客户端已有缓存,如何避免重复传输?
条件请求:服务端校验缓存是否仍然有效,有效则回 304,无效才回 200
条件请求的核心是验证器:服务端为资源生成验证器(ETag / Last-Modified),
客户端在条件头中带回,服务端比较后决定响应。
本项目使用两个条件头(参考 RFC 7232):
| 条件头 | 携带的验证器 | 命中条件 |
|---|---|---|
| If-None-Match | ETag 列表 | 任一 ETag 弱匹配当前资源 |
| If-Modified-Since | 时间戳 | 资源 Last-Modified 不晚于该时间 |
弱比较与列表匹配
ETag 比较分强比较与弱比较。弱比较忽略 W/ 弱验证器前缀后比较字符串:
1 | // src/utils.cpp |
If-None-Match 是逗号分隔的 ETag 列表,任一项弱匹配即命中;"*" 是特殊形式,匹配任意实体:
1 | // src/utils.cpp |
If-Modified-Since 与优先级
RFC 7232 规定:If-None-Match 存在时,服务器必须忽略 If-Modified-Since。
实现中先检查 INM,非空则走 ETag 分支并直接返回,IMS 仅在 INM 缺失时生效:
1 | // src/utils.cpp |
HTTP 日期解析用 strptime 严格匹配 RFC 1123 格式(%a, %d %b %Y %H:%M:%S GMT)
后经 timegm 转时间戳,解析失败视为条件头无效(回 200)
304 响应与 ETag 生成
304 的语义是”资源未变化”——不允许携带 body,仅回验证器头:
1 | // src/utils.cpp |
ETag 由文件 mtime 与 size 组合生成——内容变化(mtime 或 size 变)必然导致 ETag 变化:
1 | // src/utils.cpp |
冷请求拒绝 bug
条件请求的判定最初只存在于缓存命中路径,存在什么漏洞?
修复提交前,is_not_modified 只在 build_content_response
(缓存命中路径)被调用;对于冷缓存路径(首次请求 / 缓存淘汰后)直接返回 200,
条件请求被静默忽略——客户端永远拿不到 304
修复方法:handle_GET_request 与 handle_HEAD_request 的未命中分支,
在读取文件后同样先做条件判定:
1 | // src/static_file_service.cpp |
条件请求是 HTTP 语义,必须独立于缓存状态生效——缓存只影响服务端读取方式,不影响对客户端条件的判定
Range 断点续传:206/416
Range 头的三种形态
客户端请求资源的一部分(断点续传 / 分段下载),服务端如何回应?
单段 Range 区间有三种形态(RFC 7233):
| 形态 | 含义 | 示例 |
|---|---|---|
a-b |
闭区间 [a, b] | bytes=0-99 |
a- |
开区间,从 a 到结尾 | bytes=100- |
-b |
后缀区间,最后 b 字节 | bytes=-500 |
解析:单段校验与整头合法性
parse_single_range 解析单个区间并做语法校验——"-"(空两端)、a > b、
非数字、无 - 均为语法非法:
1 | // src/utils.cpp |
parse_range_header 负责整头:校验 bytes= 前缀(忽略大小写)、按 , 分割多段、
任一段非法则整头非法:
1 | // src/utils.cpp |
求解与决策汇聚
resolve_range 将区间规格求解为实际字节偏移,边界收敛到文件范围:
1 | // src/utils.cpp |
决策汇聚在 apply_range(static_file_service.cpp)——三种结果:
1 | // 解析 Range 头并求解 |
flowchart TD
A[Range 头] --> B{parse_range_header}
B -- 无头 / 语法非法 / 多区间 --> C[200 全量响应]
B -- 合法单段 --> D{resolve_range}
D -- start >= total --> E[416<br/>Content-Range: bytes */total]
D -- 可满足 --> F[206<br/>Content-Range: bytes s-e/total<br/>shared_slice_body 切片]
多区间回 200 的依据:RFC 7233 允许服务器忽略无法满足的 Range 头
零拷贝切片
206 响应的 body 是缓存内容的一个区间。自定义 shared_slice_body:
value_type 持有缓存 shared_ptr + offset + length,writer 直接构造
指向 data() + offset 的 const_buffer——切片不复制任何字节:
1 | // includes/static_file_service.hpp |
gzip 内容协商
通过选择进行协商,而非压缩
压缩是 CPU 密集操作,每个请求实时压缩会怎样?
高并发下 CPU 成为瓶颈——预压缩:读盘时压一次,请求时挑选版本
读盘阶段按 MIME 判断是否可压缩文本,压缩一次存入缓存条目 compressed;
请求阶段按 Accept-Encoding 挑选已有版本。将协商从”压缩”变为”选择”
容器格式:gzip 15+16
zlib 的 deflateInit2 通过 windowBits 决定输出容器格式:
1 | // src/utils.cpp |
| windowBits | 容器 | 头部 |
|---|---|---|
| 15 | zlib 容器 | zlib 头(2 字节) |
| 15 + 16 | gzip 容器 | gzip 头尾 |
响应头标 Content-Encoding: gzip 而数据若是 zlib 容器,客户端解压直接失败——
容器格式必须与响应头声明一致,这是协商实现中最典型的坑
协商流程
Accept-Encoding 用 Beast 的 token_list 解析,存在 gzip 即选压缩版本:
1 | // src/static_file_service.cpp |
注意 Content-Length 是压缩后字节数(compressed->size()),而非原始大小,
若填写为原始大小,会导致客户端等待阻塞(未接受到期望的字节流大小),导致连接超时
Range 不压缩
Range 请求能返回压缩切片吗?
不能。压缩后字节偏移不再对应文件原始字节——Range 语义基于原始资源(RFC 7233),
所以 206 分支先于 gzip 协商判断,Range 请求一律返回原始字节切片:
flowchart TD
A[请求到达] --> B{合法 Range?}
B -- 是 --> R[206 切片响应<br/>基于原始字节]
B -- 否 --> C{MIME 可压缩?}
C -- 否 --> P[200 明文响应]
C -- 是 --> D{压缩版本存在?}
D -- 否 --> P
D -- 是 --> E{Accept-Encoding 含 gzip?}
E -- 是 --> G[200 压缩响应<br/>Content-Encoding: gzip]
E -- 否 --> P
Vary 与 HEAD 长度一致性
- Vary: Accept-Encoding:304 / 206 / 200 全路径回 Vary——
中间缓存按请求头区分缓存版本,防止压缩版与明文版串用 - HEAD 长度一致性:HEAD 命中缓存时报告
compressed->size(),与 GET 压缩响应一致;
未命中不读文件内容(compressed_size = 0)——注释明确”压缩长度与 GET 缓存命中后一致”。
HEAD 的 Content-Length 必须等于 GET 的 body 长度,否则客户端断流
动态 API:405/OPTIONS
端点注册表
dynamic_api_service 以 base_path 挂载,端点完全自由注册:
注册表 endpoints_[path][method],无内置处理器——
1 | // src/dynamic_api_service.cpp |
handle_request 的判定顺序:
OPTIONS 全局支持 -> 路径不存在 404 -> 方法未注册 405 + Allow -> 调用端点处理器
405 + Allow
RFC 7231:路径存在但方法未注册,回 405,且必须带 Allow 头——
Allow 列出该路径当前支持的完整方法集,客户端据此改派请求:
1 | // src/dynamic_api_service.cpp |
OPTIONS 动态 Allow
OPTIONS 全局支持:无论路径是否注册,均回 200 + Allow。
Allow 由注册表动态计算——注册 GET 的路径自动附加 HEAD(GET 隐含 HEAD 的语义),
未注册路径的 Allow 为空集:
1 | // src/dynamic_api_service.cpp |
Allow 输出按固定方法序(GET/HEAD/POST/PUT/DELETE/PATCH)排列,(该服务器仅支持 GET/HEAD/POST)
保证同一路径多次查询的 Allow 头稳定可比较
实现细节:纯路径匹配
handle_request 先剥离 query / fragment 再查注册表:
1 | // src/dynamic_api_service.cpp |
/api/hello?name=x 与 /api/hello 命中同一端点——
query 属于请求参数而非路径标识
小结
- 304:条件请求独立于缓存状态生效(项目中的304冷请求bug问题)
- 206:Range 基于原始字节,多区间/非法可忽略返回 200
- gzip:协商是选择,容器格式必须与声明一致,不需要每对象压缩
- 405:方法未注册必须回 Allow,OPTIONS 从注册表动态计算