基于 Boost 的 HTTP 服务器:HTTP 协议细节

基于 Boost 的 HTTP 服务器:HTTP 协议细节

本文是 http_server 系列的协议篇,对应总览中的功能地图
展开四个核心协议特性的语义与实现:304 条件请求、Range 断点续传、gzip 协商、405/OPTIONS

http_server


条件请求:ETag 与 304

请求条件头的语义

客户端已有缓存,如何避免重复传输?
条件请求:服务端校验缓存是否仍然有效,有效则回 304,无效才回 200

条件请求的核心是验证器:服务端为资源生成验证器(ETag / Last-Modified),
客户端在条件头中带回,服务端比较后决定响应。

本项目使用两个条件头(参考 RFC 7232):

条件头 携带的验证器 命中条件
If-None-Match ETag 列表 任一 ETag 弱匹配当前资源
If-Modified-Since 时间戳 资源 Last-Modified 不晚于该时间

弱比较与列表匹配

ETag 比较分强比较与弱比较。弱比较忽略 W/ 弱验证器前缀后比较字符串:

1
2
3
4
5
6
7
// src/utils.cpp
// RFC 7232 弱比较: 忽略 W/ 前缀后字符串相等
bool
weak_etag_equal(boost::beast::string_view a, boost::beast::string_view b)
{
return strip_weak_prefix(a) == strip_weak_prefix(b);
}

If-None-Match 是逗号分隔的 ETag 列表,任一项弱匹配即命中;
"*" 是特殊形式,匹配任意实体:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// src/utils.cpp
auto inm = req[http::field::if_none_match];
if (!inm.empty()) {
if (trim_ows(inm) == "*") {
return true;
}
// 逗号分隔 ETag 列表,任一项弱匹配即命中
beast::string_view rest = inm;
while (!rest.empty()) {
auto comma = rest.find(',');
auto item =
trim_ows((comma == beast::string_view::npos) ? rest : rest.substr(0, comma));
if (!item.empty() && weak_etag_equal(item, etag)) {
return true;
}
...

If-Modified-Since 与优先级

RFC 7232 规定:If-None-Match 存在时,服务器必须忽略 If-Modified-Since。
实现中先检查 INM,非空则走 ETag 分支并直接返回,IMS 仅在 INM 缺失时生效:

1
2
3
4
5
6
7
8
// src/utils.cpp
auto ims = req[http::field::if_modified_since];
if (!ims.empty()) {
std::time_t since;
if (parse_http_date(ims, since)) {
return last_modified_time <= since;
}
}

HTTP 日期解析用 strptime 严格匹配 RFC 1123 格式(%a, %d %b %Y %H:%M:%S GMT)
后经 timegm 转时间戳,解析失败视为条件头无效(回 200)

304 响应与 ETag 生成

304 的语义是”资源未变化”——不允许携带 body,仅回验证器头:

1
2
3
4
5
6
7
8
9
10
// src/utils.cpp
server_utils::
make_not_modified(...)
{
// 304 不允许携带 body,仅回 ETag/Last-Modified 头
http::response<http::string_body> res{http::status::not_modified, req.version()};
res.set(http::field::etag, etag);
res.set(http::field::last_modified, last_modified);
res.content_length(0);
...

ETag 由文件 mtime 与 size 组合生成——内容变化(mtime 或 size 变)必然导致 ETag 变化:

1
2
3
4
5
6
// src/utils.cpp
std::string
make_etag(std::time_t mtime, std::size_t size)
{
return "\"" + std::to_string(mtime) + "-" + std::to_string(size) + "\"";
}

冷请求拒绝 bug

条件请求的判定最初只存在于缓存命中路径,存在什么漏洞?

修复提交前,is_not_modified 只在 build_content_response
(缓存命中路径)被调用;对于冷缓存路径(首次请求 / 缓存淘汰后)直接返回 200,
条件请求被静默忽略——客户端永远拿不到 304

修复方法:handle_GET_request 与 handle_HEAD_request 的未命中分支,
在读取文件后同样先做条件判定:

1
2
3
4
5
6
7
8
// src/static_file_service.cpp
const std::string etag = server_utils::make_etag(mtime_t, size);
const std::string last_modified = server_utils::to_http_date(mtime_t);

// 条件请求 冷缓存路径同样生效
if(server_utils::is_not_modified(req, etag, mtime_t)) {
return server_utils::make_not_modified(req, etag, last_modified);
}

条件请求是 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
2
3
4
5
6
7
8
9
10
11
// src/utils.cpp
if (left.empty() && right.empty()) {
return false; // "-"
}
if (left.empty()) { // -b 后缀区间
...
} else if (right.empty()) { // a- 开区间
...
} else { // a-b
if (a > b) return false; // 语法非法
}

parse_range_header 负责整头:校验 bytes= 前缀(忽略大小写)、按 , 分割多段、
任一段非法则整头非法:

1
2
3
4
5
6
7
// src/utils.cpp
// 按 ',' 分割,每段委托 parse_single_range
...
// 任一段非法 -> 整头非法
if (!parse_single_range(seg, range)) {
return false;
}

求解与决策汇聚

resolve_range 将区间规格求解为实际字节偏移,边界收敛到文件范围:

1
2
3
4
5
6
7
8
// src/utils.cpp
if (start >= total_size) {
return false; // a 超出文件 -> 416
}
std::size_t end = range.end.has_value()
? std::min(range.end.value(), total_size - 1) // 闭区间截断到文件尾
: total_size - 1;
length = end - start + 1;

决策汇聚在 apply_range(static_file_service.cpp)——三种结果:

1
2
3
4
5
6
7
8
9
10
11
// 解析 Range 头并求解
// 无头/非法/多区间 -> 200;不可满足 -> 416
if (server_utils::parse_range_header(...) && ranges.size() == 1) {
if (server_utils::resolve_range(ranges[0], total, res.start, res.length)) {
res.status = http::status::partial_content; // 206
...
} else {
res.status = http::status::range_not_satisfiable; // 416
res.content_range = "bytes */" + std::to_string(total);
}
}


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
2
3
4
// includes/static_file_service.hpp
return {
{const_buffers_type{body_.data->data() + body_.offset, body_.length}, false}
};

gzip 内容协商

通过选择进行协商,而非压缩

压缩是 CPU 密集操作,每个请求实时压缩会怎样?
高并发下 CPU 成为瓶颈——预压缩:读盘时压一次,请求时挑选版本

读盘阶段按 MIME 判断是否可压缩文本,压缩一次存入缓存条目 compressed;
请求阶段按 Accept-Encoding 挑选已有版本。将协商从”压缩”变为”选择”

容器格式:gzip 15+16

zlib 的 deflateInit2 通过 windowBits 决定输出容器格式:

1
2
3
4
5
// src/utils.cpp
if (deflateInit2(&strm, Z_DEFAULT_COMPRESSION, Z_DEFLATED,
15 + 16, 8, Z_DEFAULT_STRATEGY) != Z_OK) {
return false;
}
windowBits 容器 头部
15 zlib 容器 zlib 头(2 字节)
15 + 16 gzip 容器 gzip 头尾

响应头标 Content-Encoding: gzip 而数据若是 zlib 容器,客户端解压直接失败——
容器格式必须与响应头声明一致,这是协商实现中最典型的坑

协商流程

Accept-Encoding 用 Beast 的 token_list 解析,存在 gzip 即选压缩版本:

1
2
3
4
5
6
7
8
9
// src/static_file_service.cpp
if (compressed &&
server_utils::should_compress(server_utils::mime_type(full_path))) {
http::token_list encodings{req[http::field::accept_encoding]};
if (encodings.exists("gzip")) {
http::response<shared_string_body> res{http::status::ok, req.version()};
res.set(http::field::content_encoding, "gzip");
res.content_length(compressed->size()); // 压缩后长度
res.body() = compressed;

注意 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
2
3
4
5
6
7
8
// src/dynamic_api_service.cpp
dynamic_api_service&
dynamic_api_service::
add_endpoint(http::verb method, std::string path, Handler handler)
{
endpoints_[std::move(path)][method] = std::move(handler);
return *this; // 链式注册
}

handle_request 的判定顺序:
OPTIONS 全局支持 -> 路径不存在 404 -> 方法未注册 405 + Allow -> 调用端点处理器

405 + Allow

RFC 7231:路径存在但方法未注册,回 405,且必须带 Allow 头——
Allow 列出该路径当前支持的完整方法集,客户端据此改派请求:

1
2
3
4
5
6
// src/dynamic_api_service.cpp
auto handler_it = it->second.find(req.method());
if (handler_it == it->second.end()) {
// RFC 7231 路径存在但方法未注册 -> 405 + Allow
return make_method_not_allowed(req, it->second);
}

OPTIONS 动态 Allow

OPTIONS 全局支持:无论路径是否注册,均回 200 + Allow。
Allow 由注册表动态计算——注册 GET 的路径自动附加 HEAD(GET 隐含 HEAD 的语义),
未注册路径的 Allow 为空集:

1
2
3
4
5
6
7
8
9
10
11
// src/dynamic_api_service.cpp
std::string
dynamic_api_service::
build_allow_header(const method_handlers& methods)
{
// GET 隐含 HEAD
if (methods.count(http::verb::get)) {
append(http::verb::get);
append(http::verb::head);
}
...

Allow 输出按固定方法序(GET/HEAD/POST/PUT/DELETE/PATCH)排列,(该服务器仅支持 GET/HEAD/POST)
保证同一路径多次查询的 Allow 头稳定可比较

实现细节:纯路径匹配

handle_request 先剥离 query / fragment 再查注册表:

1
2
3
// src/dynamic_api_service.cpp
// 剥离 query/fragment,端点按纯路径匹配
auto path = server_utils::target_path(req.target());

/api/hello?name=x 与 /api/hello 命中同一端点——
query 属于请求参数而非路径标识


小结

  • 304:条件请求独立于缓存状态生效(项目中的304冷请求bug问题)
  • 206:Range 基于原始字节,多区间/非法可忽略返回 200
  • gzip:协商是选择,容器格式必须与声明一致,不需要每对象压缩
  • 405:方法未注册必须回 Allow,OPTIONS 从注册表动态计算

END