libwebsockets 自定义 HTTP 响应头实战:minimal-http-server-custom-headers 示例深度解析
libwebsockets 自定义 HTTP 响应头实战:minimal-http-server-custom-headers 示例深度解析
导读
本篇文章以 libwebsockets(lws)官方 minimal 示例集中的一个经典用例——minimal-http-server-custom-headers 为核心,深入讲解如何在 lws 中构建同时提供静态内容与动态内容的 HTTP 服务器,并重点演示 lws 对"未知自定义 HTTP 请求头"(如浏览器隐私设置中的 DNT: Do-Not-Track 头)的读取与回显机制。读完本文,你将掌握 lws HTTP 服务端的两大核心能力:基于 mount 的静态/动态资源挂载架构,以及 lws_hdr_custom_length() / lws_hdr_custom_copy() 自定义请求头查询 API 的完整用法。该示例在 TEN-framework 仓库中以第三方组件源码的形式完整保留,可直接编译运行与对照学习。
示例概述:一个"既能出静态页、又能出动态内容"的最小服务器
minimal-http-server-custom-headers 是 lws 官方 minimal-examples 中 http-server 系列的一个最小化示例,其完整源码位于:
- 主程序:minimal-http-server-custom-headers.c
- 构建脚本:CMakeLists.txt
- 官方 README:README.md
与 lws 其他"纯静态"或"纯动态"的 minimal 示例不同,这个示例的特点是同时演示两种服务能力:
- 静态内容:从启动目录下的
./mount-origin子目录(即 mount-origin 目录)提供静态文件服务; - 动态内容:URL 路径
/dyn/...下的内容不是磁盘文件,而是由回调函数在运行时动态生成,其核心功能是读取浏览器发来的 DNT 自定义请求头,并把读取结果以 HTML 的形式回显给访问者。
示例的首页 index.html 中有两个入口链接,分别指向 HTTP 与 HTTPS 两个端口的动态路径,直观展示了示例的两种运行形态:
<a href="http://127.0.0.1:7681/dyn/xxx">Show DNT header using h1 over http</a><br>
<a href="https://127.0.0.1:7682/dyn/xxx">Show DNT header using h1 (h2 if enabled) over https</a><br>
也就是说,访问者既可以在 7681 端口的明文 HTTP 下测试 DNT 头的回显,也可以在 7682 端口的 TLS(HTTPS)下测试。
构建与运行:从仓库源码到可执行文件
构建
官方 README 给出的构建步骤非常简洁,两条命令即可:
$ cmake . && make
该示例的 CMakeLists.txt 说明了它编译成功所需的前提条件,通过 require_lws_config() 宏逐一检查 lws 库的编译配置项:
set(requirements 1)
require_lws_config(LWS_ROLE_H1 1 requirements)
require_lws_config(LWS_WITH_CUSTOM_HEADERS 1 requirements)
require_lws_config(LWS_WITH_SERVER 1 requirements)
LWS_ROLE_H1:要求 lws 具备 HTTP/1.1 角色支持。示例首页中提到的"custom header api 目前只工作在 h1"(见 index.html),正是由这个宏约束的;LWS_WITH_CUSTOM_HEADERS:自定义请求头 API 的编译开关,本示例的核心依赖。根据 lws-http.h 中的 API 文档说明,该配置默认开启(on by default),因此大多数发行版构建无需额外处理;LWS_WITH_SERVER:要求以服务器模式构建 lws。
只有当三项检查全部通过(requirements 非零)时,才会真正生成 lws-minimal-http-server-custom-headers 可执行文件;随后根据 lws 是共享库还是静态库,分别链接 websockets_shared 或 websockets。
运行
直接运行生成的可执行文件即可:
$ ./lws-minimal-http-server-dynamic
[2018/03/20 10:24:24:7099] USER: LWS minimal http server dynamic | visit http://localhost:7681
[2018/03/20 10:24:24:7099] NOTICE: Creating Vhost 'default' port 7681, 1 protocols, IPv6 off
启动后访问 http://localhost:7681,首先看到的是 mount-origin 下的静态首页;点击页面上的 /dyn/anything 链接(对应 http://127.0.0.1:7681/dyn/xxx),会打开一个新标签页,展示动态生成的内容——即浏览器发送的 DNT 头信息。
从主程序的日志输出可以发现,该示例还额外支持两个命令行参数:
if ((p = lws_cmdline_option(argc, argv, "-d")))
logs = atoi(p);
...
if (lws_cmdline_option(argc, argv, "--ah1"))
info.max_http_header_pool = 1;
-d <level>:设置 lws 日志级别(LLL_USER | LLL_ERR | LLL_WARN | LLL_NOTICE为默认值),便于调试时打开更详细的日志;--ah1:把max_http_header_pool强制设为 1,用于专门测试 AH(Active Header)队列在极端资源下的表现。源码注释明确说明这只是"for testing ah queue, not useful in real world"(测试用,真实场景不建议使用)。
核心原理一:mount 挂载架构——一份上下文里混排静态与动态
lws 的 HTTP 服务采用 mount(挂载点) 机制来组织 URL 空间:一个 struct lws_http_mount 描述"某个 URL 前缀之下提供什么内容",多个 mount 通过 mount_next 指针构成链表。本示例在主程序中定义了两个 mount。
静态 mount:服务 ./mount-origin 目录
static const struct lws_http_mount mount = {
/* .mount_next */ &mount_dyn, /* linked-list "next" */
/* .mountpoint */ "/", /* mountpoint URL */
/* .origin */ "./mount-origin", /* serve from dir */
/* .def */ "index.html", /* default filename */
/* .protocol */ NULL,
/* .origin_protocol */ LWSMPRO_FILE, /* files in a dir */
/* .mountpoint_len */ 1, /* char count */
...
};
关键字段:
mountpoint = "/":根路径挂载点,承载整个 URL 空间的默认静态服务;origin = "./mount-origin":静态文件的实际磁盘目录,与启动时的当前工作目录相对;def = "index.html":访问目录时默认返回的文件名,对应仓库中的 mount-origin/index.html;origin_protocol = LWSMPRO_FILE:明确告知 lws"这个挂载点提供的是目录中的文件",从而走静态文件服务路径;mount_next = &mount_dyn:把动态挂载点链接到链表中,静态与动态在同一棵树中协同工作。
动态 mount:把 /dyn 交给协议回调
static const struct lws_http_mount mount_dyn = {
/* .mount_next */ NULL, /* linked-list "next" */
/* .mountpoint */ "/dyn", /* mountpoint URL */
/* .origin */ NULL, /* protocol */
/* .def */ NULL,
/* .protocol */ "http",
/* .origin_protocol */ LWSMPRO_CALLBACK, /* dynamic */
/* .mountpoint_len */ 4, /* char count */
...
};
关键字段:
mountpoint = "/dyn",mountpoint_len = 4:URL 前缀/dyn之下的所有请求(如/dyn/anything、/dyn/xxx)都命中该挂载点;origin_protocol = LWSMPRO_CALLBACK:这是与静态挂载点最本质的区别——告诉 lws 该路径下没有真实文件,一切由协议回调函数动态生成;protocol = "http":指定处理该挂载点请求的协议名,与下面协议表(lws_protocols)中注册的"http"协议对应。
双 vhost:HTTP 与 HTTPS 并存
主程序中,同一个 lws_context_creation_info info 被复用来创建两个 vhost(虚拟主机),这是"一份代码、两个端口"的关键:
/* http on 7681 */
info.port = 7681;
info.protocols = protocols;
info.mounts = &mount;
info.vhost_name = "http";
lws_create_vhost(context, &info);
/* https on 7682 */
info.port = 7682;
info.error_document_404 = "/404.html";
#if defined(LWS_WITH_TLS)
info.ssl_cert_filepath = "localhost-100y.cert";
info.ssl_private_key_filepath = "localhost-100y.key";
#endif
info.vhost_name = "https";
lws_create_vhost(context, &info);
- 7681 端口(明文 HTTP):协议、mount 挂载树一次配置,直接创建 vhost;
- 7682 端口(HTTPS):在
LWS_WITH_TLS编译开关开启的前提下,通过ssl_cert_filepath与ssl_private_key_filepath指定证书与私钥,对应仓库根目录下的localhost-100y.cert与localhost-100y.key;同时通过error_document_404 = "/404.html"指定 404 错误页,即 mount-origin/404.html。
vhost 创建前,info.options 还设置了三个重要的全局选项:
info.options = LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT |
LWS_SERVER_OPTION_EXPLICIT_VHOSTS |
LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE;
其中 LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE 会强制 lws 自动为响应附加一组安全最佳实践相关的 HTTP 头,这也是示例名中 "custom headers" 之外隐含的"安全头"实践之一。
核心原理二:协议回调与自定义请求头 API
协议注册:每个连接挂一块私有状态
static struct lws_protocols protocols[] = {
{ "http", callback_http, sizeof(struct pss), 0, 0, NULL, 0 },
LWS_PROTOCOL_LIST_TERM
};
协议名 "http" 与动态挂载点的 .protocol 字段一一对应。第三个字段 sizeof(struct pss) 让 lws 为每个连接分配一块私有会话状态(per-session state):
struct pss {
char result[128 + LWS_PRE];
int len;
};
其中 LWS_PRE 是 lws 为各角色在写缓冲头部预留的字节数(本示例预留 128 字节给 HTML 文本,再加 LWS_PRE 的前缀余量)。
自定义请求头:lws 是如何"认识"未知头的
lws 内置能识别约 100 个常见 HTTP 头,并把它们解析为内部索引(token index);而遇到不认识的请求头时,lws 会把"名字 + 值"原样保存起来,并提供一个专门的查询通道。官方头文件 lws-http.h 对此有明确说明:
"Lws knows about about 100 common http headers, and parses them into indexes when it recognizes them. When it meets a header that it doesn't know, it stores the name and value directly, and you can look them up using lws_hdr_custom_length() and lws_hdr_custom_copy()."
本示例中的 DNT(Do-Not-Track) 头正是这样一个"lws 未内置"的请求头——浏览器通过它向服务器声明"用户不希望被追踪",你可以在浏览器的隐私设置中开启或关闭 DNT。示例首页 index.html 也专门提示读者到浏览器隐私设置中尝试开启 DNT。
对应的两个查询 API 定义在 lws-http.h:
LWS_VISIBLE LWS_EXTERN int
lws_hdr_custom_length(struct lws *wsi, const char *name, int nlen);
LWS_VISIBLE LWS_EXTERN int
lws_hdr_custom_copy(struct lws *wsi, char *dst, int len, const char *name,
int nlen);
lws_hdr_custom_length():返回指定自定义头的值部分的字节长度;若头不存在则返回-1;lws_hdr_custom_copy():把自定义头的值拷贝到调用者提供的缓冲区;若缓冲区不够容纳"值 + 结尾 NUL"则返回-1;- 两者都以
name+nlen方式传参,且 name 必须包含结尾的冒号(示例中即"dnt:"与4); - 两个 API 都要求 lws 以
LWS_WITH_CUSTOM_HEADERS编译(默认开启)。
其底层实现位于 parsers.c。lws 在解析未知头时把它们串成一个链表(ah->unk_ll_head),每个链表节点以 UHO_NLEN(名字长度)、UHO_NAME(名字)、UHO_VLEN(值长度)等偏移量布局存储。lws_hdr_custom_length() 遍历该链表,用大端序读取的长度字段(lws_ser_ru16be)比对名字长度,再用 strncmp 精确比对名字,命中后返回值长度;lws_hdr_custom_copy() 则在此基础上进一步把值区域 strncpy 到目标缓冲区。这种"先查长度、再按需拷贝"的两段式设计,允许调用方先用 lws_hdr_custom_length() 评估所需空间,避免缓冲区溢出,是编写健壮服务器代码的推荐姿势。
LWS_CALLBACK_HTTP 处理流程:读头 → 拼响应 → 写回
示例的回调函数 callback_http() 只重写了 LWS_CALLBACK_HTTP 与 LWS_CALLBACK_HTTP_WRITEABLE 两个事件,其余全部转交给默认处理器 lws_callback_http_dummy():
case LWS_CALLBACK_HTTP:
pss->len = 0;
n = lws_hdr_custom_length(wsi, "dnt:", 4);
if (n < 0)
pss->len = lws_snprintf(pr, e,
"%s: DNT header not found\n", __func__);
else {
pss->len = lws_snprintf(pr, e,
"%s: DNT length %d<br>", __func__, n);
n = lws_hdr_custom_copy(wsi, value, sizeof(value), "dnt:", 4);
...
pss->len += lws_snprintf(pr + pss->len, e - (unsigned int)pss->len,
"%s: DNT value '%s'\n", __func__, value);
}
lwsl_user("%s\n", pr);
if (lws_add_http_common_headers(wsi, HTTP_STATUS_OK,
"text/html", (lws_filepos_t)pss->len, &p, end))
return 1;
if (lws_finalize_write_http_header(wsi, start, &p, end))
return 1;
/* write the body separately */
lws_callback_on_writable(wsi);
return 0;
这段代码的完整流程可拆解为四步:
- 查询自定义头:先用
lws_hdr_custom_length(wsi, "dnt:", 4)判断 DNT 头是否存在并取得长度;若返回-1,则在响应正文里写明DNT header not found;否则继续用lws_hdr_custom_copy()把 DNT 值拷进value[32],并把"长度 + 值"都写入pss->result(偏移LWS_PRE之后的位置pr); - 控制台回显:
lwsl_user()把拼好的字符串同时打印到服务端日志,方便观察每一次请求的实际 DNT 值; - 组装响应头:
lws_add_http_common_headers()写入状态码HTTP_STATUS_OK、内容类型text/html与内容长度(即pss->len);随后lws_finalize_write_http_header()按当前协议(h1/h2)正确终止并写出头部。注意lws_add_http_common_headers()之后允许继续追加其他头,只要最终以lws_finalize_http_header()收尾即可(本示例直接用lws_finalize_write_http_header()一步完成); - 申请可写事件:
lws_callback_on_writable(wsi)请求在下一次可写时发送正文,把"响应头"与"响应体"分成两个阶段处理。
随后在 LWS_CALLBACK_HTTP_WRITEABLE 中真正发送正文:
case LWS_CALLBACK_HTTP_WRITEABLE:
strcpy((char *)start, "hello");
if (lws_write(wsi, (uint8_t *)pr, (unsigned int)pss->len, LWS_WRITE_HTTP_FINAL) != pss->len)
return 1;
if (lws_http_transaction_completed(wsi))
return -1;
return 0;
要点:
lws_write()发送的数据取自pr(pss->result + LWS_PRE),长度pss->len,并以LWS_WRITE_HTTP_FINAL标记本次 HTTP 事务的最后一块数据;lws_http_transaction_completed()告知 lws 本次事务已完成;若返回非零(例如要求关闭连接),则回调返回-1让 lws 释放该连接;- 主事件循环
while (n >= 0 && !interrupted) n = lws_service(context, 0);持续驱动上述回调,SIGINT信号(sigint_handler)则负责让循环优雅退出并销毁上下文(lws_context_destroy)。
实践要点与注意事项
- DNT 头不是浏览器默认携带的:现代浏览器通常默认不发送 DNT 头,只有用户在隐私设置中显式开启后才会发送,且其值一般是
1。因此第一次访问动态页时,最常见的输出是DNT header not found——这属于预期行为,可据此反向确认 API 的"查不到返回 -1"分支工作正常。 - 自定义头 API 的作用域是 h1:正如示例首页所注明的"At the moment the custom header api only works on h1",该示例的 CMake 检查项
LWS_ROLE_H1也印证了这一点。若构建时禁用了 HTTP/1.1 角色,示例将无法编译。 - 缓冲区边界必须自己把关:
lws_hdr_custom_copy()要求目标缓冲区能装下"值 + 一个结尾 NUL",否则返回-1;示例中value[32]即按此约定声明。实践中应先用lws_hdr_custom_length()取得长度、再分配足够空间,避免截断或溢出。 - 静态与动态挂载可以级联共存:静态 mount 的
mount_next指向动态 mount,/下未匹配动态路径的资源由静态目录兜底,/dyn前缀则精准转入回调生成,这一链表式挂载机制正是 lws 组织复杂 URL 空间的基础。 - HTTPS 端口依赖 TLS 构建与本地证书:7682 端口的 HTTPS 能力受
LWS_WITH_TLS开关约束,并在运行时需要仓库内的localhost-100y.cert/localhost-100y.key两个文件就位,否则创建 HTTPS vhost 会失败并进入bail清理路径。
小结
minimal-http-server-custom-headers 用不足 230 行的 C 代码,浓缩了 lws HTTP 服务端三个高频知识点:mount 挂载树实现静态/动态内容混排、双 vhost 实现 HTTP/HTTPS 双端口、自定义请求头 API 读取 lws 未内置的头。通过 minimal-http-server-custom-headers.c、lws-http.h 与 parsers.c 三处源码的相互印证,你可以直接以此为模板,为自己的服务接入"自定义请求头感知"能力——无论是 DNT 声明、自定义鉴权头,还是任何业务自定义元数据头。