libwebsockets 自定义 HTTP 响应头实战:minimal-http-server-custom-headers 示例深度解析

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

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 系列的一个最小化示例,其完整源码位于:

与 lws 其他"纯静态"或"纯动态"的 minimal 示例不同,这个示例的特点是同时演示两种服务能力:

  1. 静态内容:从启动目录下的 ./mount-origin 子目录(即 mount-origin 目录)提供静态文件服务;
  2. 动态内容: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;

这段代码的完整流程可拆解为四步:

  1. 查询自定义头:先用 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);
  2. 控制台回显:lwsl_user() 把拼好的字符串同时打印到服务端日志,方便观察每一次请求的实际 DNT 值;
  3. 组装响应头: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() 一步完成);
  4. 申请可写事件: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)。

实践要点与注意事项

  1. DNT 头不是浏览器默认携带的:现代浏览器通常默认不发送 DNT 头,只有用户在隐私设置中显式开启后才会发送,且其值一般是 1。因此第一次访问动态页时,最常见的输出是 DNT header not found——这属于预期行为,可据此反向确认 API 的"查不到返回 -1"分支工作正常。
  2. 自定义头 API 的作用域是 h1:正如示例首页所注明的"At the moment the custom header api only works on h1",该示例的 CMake 检查项 LWS_ROLE_H1 也印证了这一点。若构建时禁用了 HTTP/1.1 角色,示例将无法编译。
  3. 缓冲区边界必须自己把关:lws_hdr_custom_copy() 要求目标缓冲区能装下"值 + 一个结尾 NUL",否则返回 -1;示例中 value[32] 即按此约定声明。实践中应先用 lws_hdr_custom_length() 取得长度、再分配足够空间,避免截断或溢出。
  4. 静态与动态挂载可以级联共存:静态 mount 的 mount_next 指向动态 mount,/ 下未匹配动态路径的资源由静态目录兜底,/dyn 前缀则精准转入回调生成,这一链表式挂载机制正是 lws 组织复杂 URL 空间的基础。
  5. 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 声明、自定义鉴权头,还是任何业务自定义元数据头。

登录后查看全文
ten-framework