nghttp2_hd_deflate_new：nghttp2 中 HPACK 头压缩器的初始化与动态表尺寸控制

nghttp2_hd_deflate_new：nghttp2 中 HPACK 头压缩器的初始化与动态表尺寸控制

【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit

导读

nghttp2_hd_deflate_new()是 nghttp2（HTTP/2 C 库）中创建 HPACK 头部压缩器（deflater）的入口函数，负责为待发送的 HTTP/2 请求/响应头部分配压缩上下文，并通过max_deflate_dynamic_table_size参数限定动态头表的内存上界。本文以 nghttp2_hd_deflate_new.rst 文档为骨架，结合仓库内lib/nghttp2-1.65.0/lib/下的实现、示例与测试代码，完整讲解该函数的签名、参数语义、返回值、底层初始化调用链，以及它在 fluent-bit 的 HTTP/2 客户端（src/flb_http_client_http2.c）中的实际应用场景。读完本文，你将掌握 nghttp2 HPACK 压缩器的正确初始化方式、动态表尺寸约束如何影响压缩效率与内存占用，并能写出可运行、可验证的 deflate 完整流程。

函数定位：HPACK 压缩器的初始化入口

在 nghttp2 中，"deflater" 指代 HPACK 编码侧（压缩端）：它将nghttp2_nv形式的 name/value 头部数组编码为符合 RFC 7541 的头部块（header block），供 HTTP/2 帧携带。与它配对的是 "inflater"（解码侧）。nghttp2_hd_deflate_new()就是创建这个编码器对象的第一步，函数原型声明位于公共头文件 nghttp2.h：

#include <nghttp2/nghttp2.h> NGHTTP2_EXTERN int nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr, size_t max_deflate_dynamic_table_size);

• deflater_ptr：输出参数，指向nghttp2_hd_deflater *的指针。函数成功时写入新分配的 deflater 对象指针。
• max_deflate_dynamic_table_size：deflater 将使用的头表大小（header table size）上界，单位为字节。
• 返回值：成功返回0；失败返回负错误码。

nghttp2_hd_deflater是一个不透明类型（opaque type），在 nghttp2.h 中仅以前向声明暴露给应用层，内部结构定义在 nghttp2_hd.h，应用无需也无法直接触碰其字段。

参数详解：max_deflate_dynamic_table_size 的语义

原文档对max_deflate_dynamic_table_size的定义是：deflater 将使用的头表大小的上界（upper bound）。这一参数直接决定 HPACK 动态表（dynamic table）能占用的最大内存，进而影响压缩率与内存的取舍。结合源码可以拆解出三层含义：

1. 它是编码侧的内存上限，而非接收端协商值。HPACK 中，编码器能使用的动态表大小由对端通过SETTINGS_HEADER_TABLE_SIZE告知；而此参数是应用主动给编码器设置的"天花板"。在 nghttp2_hd.c 的初始化函数中可以看到，deflate_hd_table_bufsize_max字段原样记录了这个上界：

   deflater->deflate_hd_table_bufsize_max = max_deflate_dynamic_table_size;

2. 它决定是否触发"表大小变更"通知。初始化逻辑中有这样一段关键判断：

   if (max_deflate_dynamic_table_size < NGHTTP2_HD_DEFAULT_MAX_BUFFER_SIZE) { deflater->notify_table_size_change = 1; deflater->ctx.hd_table_bufsize_max = max_deflate_dynamic_table_size; } else { deflater->notify_table_size_change = 0; }

   其中NGHTTP2_HD_DEFAULT_MAX_BUFFER_SIZE定义为NGHTTP2_DEFAULT_HEADER_TABLE_SIZE（见 nghttp2_hd.h），而后者在 nghttp2.h 中为(1 << 12)，即4096 字节。也就是说：当传入的尺寸小于 4096 时，deflater 会标记notify_table_size_change = 1，在下一次执行 deflate 时先通过"动态表大小更新（Dynamic Table Size Update）"指令通知对端缩小表；当尺寸 ≥ 4096 时则无需通知（RFC 7541 规定默认表大小即为 4096）。

3. 它约束后续nghttp2_hd_deflate_change_table_size()的效果。头文件中明确说明（nghttp2.h）：deflater 永远不会使用超过max_deflate_dynamic_table_size字节的内存。因此即使对端通过SETTINGS_HEADER_TABLE_SIZE通告了更大的值，最终生效的表大小也被截断为这里指定的上界——这为内存受限场景（如嵌入式环境）提供了硬性保护。

经验值：示例 examples/deflate.c 与单元测试均使用4096（与默认一致）。实际项目中，若头部体积大且对端表容量充足，可适当调大以提升跨请求的索引命中率；若内存敏感，可调小以牺牲部分压缩率换取更低内存。

返回值与错误语义

函数成功返回0；失败时返回负错误码，唯一列出的错误是：

错误码	含义
NGHTTP2_ERR_NOMEM	内存分配失败（out of memory）

两个需要特别注意的语义：

• 失败时*deflater_ptr保持不变。这是"不产生副作用"的原子性保证，调用方在rv != 0时可直接失败退出，无需担心指针被置为悬垂值。
• 源码实现中，NGHTTP2_ERR_NOMEM来自两层：一是为 deflater 结构体本身nghttp2_mem_malloc失败（nghttp2_hd.c），二是内部初始化失败时先释放已分配内存再返回错误码（nghttp2_hd.c），进一步保证了失败路径不泄漏内存。

源码级剖析：从 new 到 deflate_init2 的调用链

nghttp2_hd_deflate_new()本身是一个薄封装，真正的初始化分三步展开（nghttp2_hd.c）：

1. nghttp2_hd_deflate_new()→nghttp2_hd_deflate_new2(..., NULL)：以默认内存分配器（nghttp2_mem_default()）委托给带自定义分配器参数的版本。
2. nghttp2_hd_deflate_new2()：分配nghttp2_hd_deflater结构体，然后调用nghttp2_hd_deflate_init2()；若初始化失败，nghttp2_mem_free释放结构体并直接返回错误码；只有成功后才把指针写入*deflater_ptr。
3. nghttp2_hd_deflate_init2()（nghttp2_hd.c）：
   • 调用hd_context_init()初始化动态表上下文（环形缓冲hd_table、hd_table_bufsize = 0、next_seq = 0）；
   • hd_map_init()初始化大小为HD_MAP_SIZE（128）的索引查找表（nghttp2_hd.h）；
   • 依据传入尺寸与 4096 的关系设置notify_table_size_change；
   • 记录deflate_hd_table_bufsize_max与min_hd_table_bufsize_max = UINT32_MAX（后者用于跟踪后续表大小变更的最小值）。

从nghttp2_hd_deflater结构体（nghttp2_hd.h）可以看出，整个 deflater 的状态机由五部分组成：ctx（共享的 HPACK 上下文：动态表 + 当前表大小）、map（动态表索引哈希）、deflate_hd_table_bufsize_max（本参数存入的上界）、min_hd_table_bufsize_max（已通知的最小表大小）、notify_table_size_change（是否需要先发送表大小更新）。

另外，动态表每项的开销被定义为NGHTTP2_HD_ENTRY_OVERHEAD 32字节（nghttp2_hd.h），即"name 长度 + value 长度 + 32"计入表体积（见 nghttp2_hd.h 的注释），这是计算表内存占用时容易被忽略的细节。

完整使用示例：初始化、编码、释放

仓库提供了可直接编译运行的完整示例 examples/deflate.c，其中初始化部分正是本文函数的标准用法：

#include <nghttp2/nghttp2.h> #define MAKE_NV(K, V) \ { \ (uint8_t *)K, (uint8_t *)V, sizeof(K) - 1, sizeof(V) - 1, \ NGHTTP2_NV_FLAG_NONE, \ } nghttp2_hd_deflater *deflater; nghttp2_hd_inflater *inflater; /* 创建 HPACK 压缩器，动态表上界 4096 字节 */ rv = nghttp2_hd_deflate_new(&deflater, 4096); if (rv != 0) { fprintf(stderr, "nghttp2_hd_deflate_new failed: %s\n", nghttp2_strerror(rv)); exit(EXIT_FAILURE); } /* 创建对应的解压器 */ rv = nghttp2_hd_inflate_new(&inflater); if (rv != 0) { fprintf(stderr, "nghttp2_hd_inflate_new failed: %s\n", nghttp2_strerror(rv)); exit(EXIT_FAILURE); }

示例随后演示了 HPACK 差分编码的典型场景：先编码第一组头部（模拟 HTTP 请求）：

nghttp2_nv nva1[] = { MAKE_NV(":scheme", "https"), MAKE_NV(":authority", "example.org"), MAKE_NV(":path", "/"), MAKE_NV("user-agent", "libnghttp2"), MAKE_NV("accept-encoding", "gzip, deflate")};

再编码第二组头部（复用前一组的状态做差分编码）：

nghttp2_nv nva2[] = { MAKE_NV(":scheme", "https"), MAKE_NV(":authority", "example.org"), MAKE_NV(":path", "/stylesheet/style.css"), MAKE_NV("user-agent", "libnghttp2"), MAKE_NV("accept-encoding", "gzip, deflate"), MAKE_NV("referer", "https://example.org")};

每组头部的编码流程遵循"bound → hd2 → 校验"三步（examples/deflate.c）：

/* 1. 用 deflate_bound 计算输出缓冲区上界 */ buflen = nghttp2_hd_deflate_bound(deflater, nva, nvlen); buf = malloc(buflen); /* 2. 执行 HPACK 编码 */ outlen = nghttp2_hd_deflate_hd2(deflater, buf, buflen, nva, nvlen);

其中nghttp2_hd_deflate_bound()给出的上界计算在 nghttp2_hd.c 中有详细注释：按最耗空间的 "Literal Header Field without Indexing - New Name" 格式、并取 Huffman/非 Huffman 中的较小值估算，还预留了至多两次 4-bit 前缀表大小更新（每次至多 6 字节）的开销。

生命周期收尾：所有编码结束后，务必调用nghttp2_hd_deflate_del(deflater)与nghttp2_hd_inflate_del(inflater)释放资源（examples/deflate.c）。nghttp2_hd_deflate_del的实现（nghttp2_hd.c）先从上下文取出内存分配器，再释放内部资源与结构体本身，保证与new时的分配器配对使用。

测试验证：单元测试如何覆盖该函数

nghttp2_hd_test.c 中的test_nghttp2_hd_public_api（L1285-L1324）对本文函数及其配套 API 做了系统性验证：

• 成功路径：nghttp2_hd_deflate_new(&deflater, 4096)与nghttp2_hd_inflate_new(&inflater)均断言返回 0；随后用nghttp2_hd_deflate_bound计算缓冲上界，调用nghttp2_hd_deflate_hd2编码，断言输出字节数大于 0，并回送 inflater 验证解码字节数一致。
• 缓冲区不足路径：第二次以buflen - 1调用nghttp2_hd_deflate_hd2，断言精确返回NGHTTP2_ERR_INSUFF_BUFSIZE，印证了 head 文档中"缓冲区不足即失败、应先用nghttp2_hd_deflate_bound探测上界"的约定。

该测试是理解"new 之后如何正确编码"的最短可读代码，可作为自研用例的模板。

在 fluent-bit 中的实际应用

nghttp2 在本仓库中并非孤立存在：fluent-bit 的 HTTP/2 客户端 src/flb_http_client_http2.c 通过 nghttp2 库构建 HTTP/2 会话，其回调函数体系（nghttp2_session_callbacks）覆盖了发送、头部解析、帧接收、流关闭与数据读取等完整生命周期（flb_http_client_http2.c），并在构建时通过 src/CMakeLists.txt 链接NGHTTP2_LIBRARIES。fluent-bit 的 HTTP 输出插件（如out_http、out_opentelemetry、out_splunk等，均在 plugins 目录下）在启用 HTTP/2 时会走这条路径，其出站请求头部的 HPACK 压缩即由 nghttp2 内部完成——而这一切的起点，正是本文所讲的 deflater 初始化。

换句话说，nghttp2_hd_deflate_new虽属于 nghttp2 的底层 API，但它直接决定了 fluent-bit 通过 HTTP/2 与对端（如 OpenTelemetry Collector、Splunk HEC 等）通信时头部压缩的内存开销与压缩效率，是理解 fluent-bit HTTP/2 数据面不可或缺的一环。

相关 API 家族速览

函数	职责	参考位置
nghttp2_hd_deflate_new()	创建 deflater（默认内存分配器）	nghttp2_hd.c
nghttp2_hd_deflate_new2()	同 new，但可指定自定义内存分配器mem（可为 NULL）	nghttp2.h
nghttp2_hd_deflate_del()	释放 deflater 全部资源	nghttp2_hd.c
nghttp2_hd_deflate_change_table_size()	依据SETTINGS_HEADER_TABLE_SIZE调整动态表大小，但不会超过 new 时指定的上界	nghttp2.h
nghttp2_hd_deflate_bound()	计算编码输出的缓冲区上界	nghttp2_hd.c
nghttp2_hd_deflate_hd2()	执行实际 HPACK 编码（deflate_hd已废弃）	nghttp2.h

每份 API 都有独立的 RST 文档可对照阅读，例如带自定义分配器的变体见 nghttp2_hd_deflate_new2.rst、动态表尺寸变更见 nghttp2_hd_deflate_change_table_size.rst，完整的 HPACK 使用教学可参考 tutorial-hpack.rst。

小结

nghttp2_hd_deflate_new()虽然只是一个初始化函数，但它承载了三个关键设计：失败原子性（*deflater_ptr失败不变）、内存上界约束（deflater 永不超过max_deflate_dynamic_table_size）、表大小变更联动（小于 4096 时自动通知对端）。在实际开发中，建议将 4096 作为起点，结合对端SETTINGS_HEADER_TABLE_SIZE与自身内存预算调整该值，并始终与nghttp2_hd_deflate_bound+nghttp2_hd_deflate_hd2+nghttp2_hd_deflate_del构成完整的编码生命周期。

【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit