基于 libwebsockets 的 HTTP 自定义请求/响应头处理实战:minimal-http-client-custom-headers 源码剖析

原创2026-10-06 15:04:511,898 阅读
文章标签:人工智能大模型语音音频多模态AI Agent实时分析后端插件系统Web框架开发者工具低代码MCP Clients工作流自动化跨平台

基于 libwebsockets 的 HTTP 自定义请求/响应头处理实战:minimal-http-client-custom-headers 源码剖析

导读

在基于 HTTP 的客户端开发中,自定义 Header(请求头与响应头)常被用于传递鉴权信息、追踪 ID、客户端能力声明等业务元数据。本文以 TEN-framework 仓库中 vendored 的 libwebsockets(third_party/libwebsockets)所附带的官方最小示例 minimal-http-client-custom-headers 为骨架,完整讲解自定义请求头如何写入握手、自定义响应头如何被解析与读取、为什么该能力目前仅适用于 HTTP/1.x,并结合仓库头文件 API 文档与底层解析源码,让你在阅读后既能直接构建运行该示例,也能在自己的 lws 客户端工程中正确收发自定义 Header。

示例概览:示例解决了什么问题

该示例位于仓库 third_party/libwebsockets/minimal-examples/http-client/minimal-http-client-custom-headers,由三个文件组成:

它的核心演示内容有两点:

  1. 发送自定义请求头:在 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER 回调中,通过 lws_add_http_header_by_name() 向即将发出的请求追加 dnt: 1 这一自定义头部;
  2. 读取自定义响应头:在连接建立(LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP)后,通过 lws_hdr_custom_length() / lws_hdr_custom_copy() 读取服务器返回的自定义头部 test-custom-header(warmcat.com 会为测试返回固定值 hello)。

示例同时演示了 HTTP/1.x 与 HTTP/2 在自定义头部能力上的差异:由于自定义响应头的读取目前只支持 HTTP/1,因此示例强制将 ALPN 协商结果固定为 http/1.1(源码第 209 行 i.alpn = "http/1.1"),即便对端开启了 h2 也不会升级。

构建与运行

构建步骤

示例的 CMakeLists.txt 采用标准的 libwebsockets 最小示例组织方式:

project(lws-minimal-http-client-custom-headers C)
cmake_minimum_required(VERSION 2.8.12)
find_package(libwebsockets CONFIG REQUIRED)
list(APPEND CMAKE_MODULE_PATH ${LWS_CMAKE_DIR})
include(CheckCSourceCompiles)
include(LwsCheckRequirements)

set(SAMP lws-minimal-http-client-custom-headers)
set(SRCS minimal-http-client-custom-headers.c)

set(requirements 1)
require_lws_config(LWS_ROLE_H1 1 requirements)
require_lws_config(LWS_WITH_CLIENT 1 requirements)

构建命令与原文档一致:

cmake . && make

两点值得注意的构建前提:

  • 通过 require_lws_config(LWS_ROLE_H1 1 requirements) 与 require_lws_config(LWS_WITH_CLIENT 1 requirements),CMake 会检查当前 lws 库构建时是否启用了 HTTP/1 角色与客户端支持,若未启用则跳过编译,避免链接期符号缺失;
  • 示例依赖 lws 的 custom headers 存储能力(编译期宏 LWS_WITH_CUSTOM_HEADERS)。该选项在 third_party/libwebsockets/CMakeLists.txt 第 284 行定义:option(LWS_WITH_CUSTOM_HEADERS "Store and allow querying custom HTTP headers (H1 only)" ON),即默认开启,但官方明确标注其语义为 仅 HTTP/1 有效。

命令行选项

原文档给出了三个运行时选项,整理如下:

选项 含义
-d <loglevel> 以十进制设置调试日志详细级别,例如 -d15
-l 连接到 https://localhost:7681 并接受自签名证书(用于本地联调测试)
-n 禁用 TLS,走纯 HTTP

此外源码还支持 --h1(启动横幅中打印)以及 -l 与 -n 的组合用法。默认(不带任何选项)情况下,程序以 TLS 连接 warmcat.com:443 并请求路径 /。

默认运行效果

默认直接运行可执行文件,期望输出大致如下(原文档示例日志,时间戳因运行时刻而异):

$ ./lws-minimal-http-client-custom-headers
USER: LWS minimal http client Custom Headers [-d<verbosity>] [-l] [--h1]
NOTICE: created client ssl context for default
USER: Connected with server response: 200
NOTICE: callback_http: custom header: 'hello'
USER: RECEIVE_CLIENT_HTTP_READ: read 1024
...

日志中的关键信息点:

  • Connected with server response: 200 表示连接建立且服务器返回 200;
  • callback_http: custom header: 'hello' 表明成功从响应中解析出自定义头 test-custom-header 的值 hello;
  • 随后的 RECEIVE_CLIENT_HTTP_READ: read 1024 是响应体(HTML 页面)被逐块读取的打印;源码中默认用 #if 0 关闭了正文转储,如需把 HTML 直接打印到终端,可把该宏改为 #if 1 重新编译。

深入源码:如何在请求中发送自定义 Header

自定义请求头的发送发生在客户端握手的“追加头部”阶段。核心代码如下(minimal-http-client-custom-headers.c 第 38-51 行):

case LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER:
{
	 unsigned char **p = (unsigned char **)in, *end = (*p) + len;

	 if (lws_add_http_header_by_name(wsi,
			 (const unsigned char *)"dnt",
			 (const unsigned char *)"1", 1, p, end))
		 return -1;
	break;
}

要点解析:

  1. 回调时机:LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER 是 lws 预留给客户端应用代码“往握手请求中追加头部”的专用回调(枚举值 24,定义见 lws-callbacks.h 第 537 行附近)。它在请求行与标准头组装完成之后、数据真正发出之前被触发。
  2. 缓冲区协议:in 携带指向当前写入位置指针的指针 p 与缓冲区末尾 end,应用通过 “追加类” API 写入数据,并由 API 内部推进 p,从而天然防止越界。
  3. API 语义:lws_add_http_header_by_name(wsi, name, value, length, p, end) 的签名与说明见 lws-http.h 第 601-615 行——name 为形如 "my-header:" 的头部名,value 为头部值,length 为值的字节长度,返回值非零表示缓冲区空间不足(带 LWS_WARN_UNUSED_RESULT 属性,必须检查返回值)。因此示例中 "dnt" + "1" 实际发出的请求头为 dnt: 1。
  4. 失败处理:追加失败时回调返回 -1,lws 会终止该连接,保证请求不会被发出不完整的头。

需要留意的是,这一机制同样适用于携带请求体(如 POST)的场景:若你通过该回调设置了正文相关头,还需调用 lws_client_http_body_pending(wsi, 1) 并配合 lws_callback_on_writable() 分块发送正文(见 lws-client.h 第 340-360 行的文档说明)。

深入源码:如何读取响应中的自定义 Header

连接建立后,示例在 LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP 回调中处理两件事:先读取 HTTP 状态码,再查询自定义响应头(minimal-http-client-custom-headers.c 第 53-77 行):

case LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP:
	status = (int)lws_http_client_http_response(wsi);
	lwsl_user("Connected with server response: %d\n", status);

	n = lws_hdr_custom_length(wsi, "test-custom-header:", 19);
	if (n < 0)
		lwsl_notice("%s: Can't find test-custom-header\n", __func__);
	else {
		if (lws_hdr_custom_copy(wsi, val, sizeof(val),
					"test-custom-header:", 19) < 0)
			lwsl_notice("%s: custom header too long\n", __func__);
		else
			lwsl_notice("%s: custom header: '%s'\n", __func__, val);
	}
	break;

对应的两个查询 API(lws-http.h 第 456-495 行)语义如下:

  • lws_hdr_custom_length(wsi, name, nlen):name 是带结尾冒号的头部名字符串(如 "test-custom-header:"),nlen 为其长度;头部存在则返回其值部分的字节长度,不存在返回 -1。该调用用于先探测存在性与长度,避免无谓拷贝或缓冲区不足。
  • lws_hdr_custom_copy(wsi, dst, len, name, nlen):把值部分拷贝进 dst(len 为缓冲区大小),成功返回拷贝长度,缓冲区放不下则返回 -1,并且 lws 保证在拷贝内容后附加一个 NUL 终止符,方便按 C 字符串处理。

在 lws 的头部模型里,约 100 个常见 HTTP 头会被解析成预定义的 token 索引;而遇到不认识的头时,lws 会把“名字 + 值”原样保存到连接上的 custom header 存储区,供上述两个 API 按名字查询。这正是示例选用 test-custom-header 这种非常规头名的原因——它必然落入“未知头”分支。

另外,lws-http.h 第 497-515 行还提供了 lws_hdr_custom_name_foreach(),用于遍历当前连接上所有自定义头的名字(通过回调逐个回调),可配合 lws_hdr_custom_copy() 枚举全部未知头,适合调试或通用转发场景。

底层机制:自定义头为何目前仅限 HTTP/1

原文档强调“自定义响应头读取目前只支持 HTTP/1”,这背后有两层原因:

  1. 解析路径不同:HTTP/1 的响应由 parsers.c 中的逐字节解析器处理,解析器在遇到未知头时会把名字与值写入 custom header 存储区(相关代码以 #if defined(LWS_WITH_CUSTOM_HEADERS) 保护,遍布该文件多处,如第 33、100、596、1033、1190 行附近)。而 HTTP/2 使用 HPACK 头压缩表(见 lib/roles/h2/hpack.c 第 1242 行附近的 LWS_WITH_CUSTOM_HEADERS 分支),其头处理路径与 HTTP/1 的解析器并不相同,自定义头的存取语义尚未完全对齐。
  2. 配置宏明确标注 H1 only:LWS_WITH_CUSTOM_HEADERS 的 CMake 选项说明原文即为 “Store and allow querying custom HTTP headers (H1 only)”。因此即使库本身支持 h2,示例仍通过 i.alpn = "http/1.1" 强制使用 HTTP/1.1,确保读取逻辑一定生效。

此外,在 HTTP/1 连接从“已发送请求”切换到“等待服务器应答”时,lws 会重置解析器状态,包括 custom header 存储区的写入游标(见 ops-h1.c 第 757-763 行:wsi->http.ah->parser_state = WSI_TOKEN_NAME_PART; wsi->http.ah->lextable_pos = 0;,并在 LWS_WITH_CUSTOM_HEADERS 下清零 unk_pos),确保每个响应从头开始累积自定义头,不会残留上一次请求/响应的数据。

本地联调:用 -l / -n 验证自定义头收发

原文档给出了一个无需外网即可验证完整链路的方案:用 -n 与 -l 让示例以纯 HTTP 连接 localhost:7681,从而确认请求中的 dnt: 1 头确实被发出。验证手段有两种:

  1. 抓包验证:在本地运行任意监听 7681 端口的 HTTP 服务,用 tcpdump 抓取 7681 端口的流量,观察请求头中是否出现 dnt: 1;
  2. 测试服务器日志验证:原文档推荐直接运行 libwebsockets 的本地测试服务器监听 :7681,并以 -d1151 打开日志级别,此时可看到解析器逐字符打印头部名字的过程,例如:
PARSER: WSI_TOKEN_NAME_PART 'd' 0x64 (role=0x20000000) wsi->lextable_pos=0
PARSER: WSI_TOKEN_NAME_PART 'n' 0x6E (role=0x20000000) wsi->lextable_pos=567
PARSER: WSI_TOKEN_NAME_PART 't' 0x74 (role=0x20000000) wsi->lextable_pos=-1
PARSER: WSI_TOKEN_NAME_PART ' ' 0x20 (role=0x20000000) wsi->lextable_pos=-1
PARSER: WSI_TOKEN_NAME_PART '1' 0x31 (role=0x20000000) wsi->lextable_pos=-1

这段输出展示了 dnt: 1 这个名字被 HTTP/1 解析器逐字符扫描的过程:lextable_pos 指向 lws 内置头部词法表中的匹配位置(dnt 不在标准头表中,故在 t 之后匹配位置回落到 -1,表示落入未知头分支),这正是“自定义头”被识别与存储的底层路径。由于 -d 的日志级别只影响 lws 自身输出,若想在日志中看到这些 PARSER: 行,测试服务器必须以 DEBUG 构建类型(-DCMAKE_BUILD_TYPE=DEBUG)编译——源码第 148-156 行的注释明确说明,LLL_ 中高于 NOTICE 级别的解析/头部日志只在 DEBUG 构建下被编译进库。

需要说明的是,-l 模式默认仍会启用 TLS(i.ssl_connection = LCCSCF_USE_SSL),并叠加 LCCSCF_ALLOW_SELFSIGNED 以接受自签名证书;-n 才真正关闭 TLS。因此“无 TLS 的本地纯 HTTP 测试”应组合使用 -n -l。

关于 TLS 后端与证书的补充说明

默认运行需要访问 warmcat.com:443,示例源码第 179-185 行对 TLS 后端做了区分:

#if defined(LWS_WITH_MBEDTLS) || defined(USE_WOLFSSL)
	info.client_ssl_ca_filepath = "./warmcat.com.cer";
#endif
  • 使用 OpenSSL 后端时,直接复用系统信任库,无需额外指定 CA;
  • 使用 mbedTLS 或 WolfSSL 后端时,必须显式告诉 lws 信任哪个 CA,因此示例目录内置了 warmcat.com.cer,并通过 info.client_ssl_ca_filepath 加载——这意味着在 mbedTLS 构建下,可执行文件的工作目录必须能访问该证书文件,否则客户端 SSL 上下文创建会失败。

小结

minimal-http-client-custom-headers 虽然只有约 230 行,却完整覆盖了 lws 客户端自定义头的三个关键知识点:

  1. 写入:在 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER 中调用 lws_add_http_header_by_name(),并务必检查其非零返回值;
  2. 读取:先用 lws_hdr_custom_length() 探测,再用 lws_hdr_custom_copy() 取值,两者都要求编译期开启 LWS_WITH_CUSTOM_HEADERS(默认开启)且只对 HTTP/1 生效;
  3. 范围限制:自定义响应头读取目前仅限 HTTP/1,示例通过 alpn = "http/1.1" 显式固定协议版本;HTTP/2 场景需关注 hpack 路径与 LWS_WITH_CUSTOM_HEADERS 在 hpack.c 中的对应实现。

对于需要在客户端与服务端之间传递自定义元数据的场景,这套“回调追加 + 名字查询”的模式可以直接复用到你自己的 lws 工程中:请求侧只需在握手回调里追加任意 name: value,响应侧则用 lws_hdr_custom_length / lws_hdr_custom_copy(或 lws_hdr_custom_name_foreach 遍历)读取。若你恰好需要调试自定义头的逐字符解析过程,按 DEBUG 构建类型编译 lws 并打开 -d 高日志级别,即可看到本文所述的 WSI_TOKEN_NAME_PART 解析流水。

登录后查看全文
ten-framework