fluent-bit 内嵌 nghttp2 1.65.0 宏参考：协议标识、ALPN 线路格式、客户端魔数与流控常量解析
【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit
本篇基于 fluent-bit 仓库中内嵌的 nghttp2 1.65.0 子库文档 macros.rst 展开，系统梳理 HTTP/2 C 库暴露的全部 24 个公共宏：协议版本标识（h2/h2c）、TLS ALPN 线路格式、客户端连接魔数、流控窗口、头部表与 SETTINGS 默认值，以及 RFC 9218 扩展优先级常量。读完本文，你可以准确理解这些常量在握手机制中的位置，并能结合仓库源码验证其在会话调度、ALPN 协商与版本探测中的实际使用方式。
宏定义在代码中的真实位置
nghttp2 的宏文档写在 lib/nghttp2-1.65.0/doc/macros.rst（Sphinx RST 源文件），而宏的实际定义分布在两个头文件中：
- 版本宏：nghttp2ver.h 定义
NGHTTP2_VERSION与NGHTTP2_VERSION_NUM。构建系统会先把 nghttp2ver.h.in 中的占位符@PACKAGE_VERSION_NUM@替换为实际值，因此在 fluent-bit 这份已生成好的头文件中可以直接读到具体版本； - 协议常量宏：其余宏几乎全部集中在主头文件 nghttp2.h，每个宏上方都带有
@macroDoxygen 注释块，说明文字与 macros.rst 中的描述一一对应。
库版本宏：NGHTTP2_VERSION 与 NGHTTP2_VERSION_NUM
这两个宏用于在编译期或运行期标识库版本：
| 宏 | 当前仓库中的值 | 说明 |
|---|---|---|
NGHTTP2_VERSION | "1.65.0" | 版本号的字符串形式 |
NGHTTP2_VERSION_NUM | 0x014100 | 版本号的 24 位数值形式：8 位 major、8 位 minor、8 位 patch |
从源码看（nghttp2ver.h#L32-L40），0x014100正好对应1.65.0（0x65 = 101 = 65）。macros.rst 中给出的编码规则是“Version 1.2.3 becomes 0x010203”，即0xMMmmpp的三段拼接。这种编码的意义在于：数值型版本可以直接做比较运算（如if (NGHTTP2_VERSION_NUM >= 0x014000)），而字符串版本比较容易出错。
版本宏还有运行期出口。nghttp2 通过nghttp2_version()返回一个nghttp2_info结构体，其成员依次为age、version_num、version_str、proto_str。在 nghttp2_version.c#L31 中可以看到这个结构体正是用NGHTTP2_VERSION_AGE、NGHTTP2_VERSION_NUM等宏实例化的；同一文件中还有一处典型用法——调用方传入一个最低可接受版本号参数，若least_version > NGHTTP2_VERSION_NUM则拒绝，这正是NGHTTP2_VERSION_NUM数值可比特性的实际体现。
配套的NGHTTP2_VERSION_AGE宏当前值为1（nghttp2.h#L149），它标记nghttp2_info结构的“年龄”：调用方先检查age字段，只有age == 1时才读取后续字段。从源码结构看，这是 C 语言中常见的 ABI 演进手法——未来若给结构体追加成员，只需递增 age 并把新字段加在尾部，旧调用方依旧安全。
协议版本标识：TLS 下的 "h2" 与明文 TCP 下的 "h2c"
HTTP/2 在不同传输层上需要不同的协议标识符，nghttp2 用两对宏来表达：
| 宏 | 值 | 使用场景 |
|---|---|---|
NGHTTP2_PROTO_VERSION_ID | "h2" | HTTP/2 over TLS 时的协议标识 |
NGHTTP2_PROTO_VERSION_ID_LEN | 2 | 上一宏的长度 |
NGHTTP2_CLEARTEXT_PROTO_VERSION_ID | "h2c" | HTTP/2 over 明文 TCP（h2c）时的协议标识 |
NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN | 3 | 上一宏的长度 |
定义位于 nghttp2.h#L92-L132。h2与h2c这对命名是 HTTP/2 生态的事实标准：TLS 握手的 ALPN 扩展中协商h2，而在明文环境（如Upgrade: h2c请求头、gRPC 本地直连）中则使用h2c。
ALPN 线路格式：NGHTTP2_PROTO_ALPN
真正在 TLS 协商中使用的并不是裸字符串"h2"，而是带长度前缀的线路格式：
#define NGHTTP2_PROTO_ALPN "\x2h2" /* 3 字节：0x02 'h' '2' */ #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)（nghttp2.h#L109-L116）
macros.rst 特别强调了第一字节的含义："\x2h2"中的0x02是后续协议标识"h2"的长度，这正是 TLS ALPN 扩展（RFC 7301）在报文中的序列化形式——protocol = <1..255>.OCTET，即“1 字节长度 + N 字节协议名”。文档原文指出该宏“useful to process incoming ALPN tokens in wire format”，即用于按线路格式解析/构造 ALPN token。
仓库中可以找到这个宏的真实消费者：nghttp2_alpn.c#L49 中用memcmp(..., NGHTTP2_PROTO_ALPN, NGHTTP2_PROTO_ALPN_LEN)判断对方提供的 ALPN token 是否指向 HTTP/2；nghttp2_alpn.c#L61-L62 的select_alpn()则以NGHTTP2_PROTO_ALPN作为首选协议去匹配客户端候选列表——也就是说，nghttp2 自己就内置了“优先协商 h2”的 ALPN 选择逻辑，上层应用可以直接调用而无需手写比对代码。
客户端连接魔数：NGHTTP2_CLIENT_MAGIC
HTTP/2 客户端在建连后必须先发送一段固定前导（connection preface），nghttp2 将其中前 24 字节定义为宏：
#define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" #define NGHTTP2_CLIENT_MAGIC_LEN 24（nghttp2.h#L252-L259）
这串字节是PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n：一次 HTTP/2.0 协议下针对任意资源（*）的 OPTIONS 请求行，加上两个空行和一个SM标记行。服务器端靠识别这 24 字节来区分“这是 HTTP/2 客户端”和“这是发了 HTTP/1.1 请求的普通客户端”。macros.rst 将其描述为“the first 24 bytes byte string of client connection preface”——完整的 client preface 实际上还跟随一个初始 SETTINGS 帧，但该宏只覆盖魔数部分。
会话层对它的两个关键使用点在 nghttp2_session.c：
- 客户端会话初始化时（nghttp2_session.c#L612-L620），nghttp2 会构造一个伪帧记录，把
payloadleft置为NGHTTP2_CLIENT_MAGIC_LEN，让输出路径按统一机制把魔数作为连接 preface 的第一部分发出去； - 服务端接收路径（nghttp2_session.c#L5332）用
memcmp(&NGHTTP2_CLIENT_MAGIC[NGHTTP2_CLIENT_MAGIC_LEN - ...])从尾部滑动比对收到的字节，逐步确认连接 preface 是否合法。
这个宏对协议实现者、代理和抓包分析人员都很实用：自己实现 HTTP/2 服务端时，可直接引用该宏做前导校验，而不用手写容易出错的 C 字符串字面量。
流控窗口常量：NGHTTP2_MAX_WINDOW_SIZE 与两个初始窗口
HTTP/2 采用“连接级 + 流级”双层滑动窗口做流量控制，nghttp2 用三个宏描述其边界：
| 宏 | 值 | 含义 |
|---|---|---|
NGHTTP2_MAX_WINDOW_SIZE | (int32_t)((1U << 31) - 1)，即 2147483647 | 窗口尺寸上限（WINDOW_UPDATE / SETTINGS 中合法的窗口最大值） |
NGHTTP2_INITIAL_WINDOW_SIZE | (1 << 16) - 1，即 65535 | 流级流控的初始窗口（64 KiB - 1） |
NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE | (1 << 16) - 1，即 65535 | 连接级流控的初始窗口 |
定义见 nghttp2.h#L224-L237。窗口最大值用(int32_t)强制符号化，是因为协议规定窗口字段为 31 位（最高位保留为 0），最大合法值正好是2^31 - 1；而两个初始窗口都取 65535，与协议规范的缺省值一致。这些常量是应用调整流控参数时的“合法区间标尺”：任何通过nghttp2_submit_window_update()或 SETTINGS 下发的窗口值都不应越过NGHTTP2_MAX_WINDOW_SIZE。
头部压缩与 SETTINGS 相关默认值
除窗口常量外，macros.rst 还覆盖了头部压缩与 SETTINGS 帧的默认参数：
| 宏 | 值 | 说明 |
|---|---|---|
NGHTTP2_DEFAULT_HEADER_TABLE_SIZE | (1 << 12)，即 4096 | HPACK 动态表默认尺寸（nghttp2.h#L244） |
NGHTTP2_DEFAULT_MAX_SETTINGS | 32 | 单个 SETTINGS 帧内默认最多容纳的 SETTINGS 参数条数（nghttp2.h#L266） |
NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS | 0xffffffffu | 初始最大入站并发流数（宏文档标注 Deprecated，实际初始值即 0xffffffffu） |
NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS的文档描述值得细读：macros.rst 说明“Default maximum number of incoming concurrent streams. Usenghttp2_submit_settings()withNGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMSto change the maximum number of incoming concurrent streams”，并在 note 中补充“最大出站并发流数默认为 100”。即入站方向不设实际限制（2^32-1），出站方向则有一个 100 条并发流的默认上限，应用若需要更高吞吐应通过 SETTINGS 帧显式下发。
已弃用的流依赖权重：NGHTTP2_DEFAULT/MAX/MIN_WEIGHT
RFC 7540 的依赖树优先级（PRIORITY 帧 + weight）已被 RFC 9113 正式弃用，nghttp2 在三个权重宏上都保留了显式弃用警告：
| 宏 | 值 | 状态 |
|---|---|---|
NGHTTP2_DEFAULT_WEIGHT | 16 | 弃用（RFC 7540 优先级被 RFC 9113 弃用） |
NGHTTP2_MAX_WEIGHT | 256 | 弃用 |
NGHTTP2_MIN_WEIGHT | 1 | 弃用 |
定义见 nghttp2.h#L191-L217，每个宏上方的注释块都带着与 macros.rst 相同的 warning：“Deprecated. :rfc:7540priorities are deprecated by :rfc:9113. Consider migrating to :rfc:9218extensible prioritization scheme.”。权重区间为[1, 256]，默认 16，与 RFC 7540 第 5.3 节的规格一致。对维护者而言，这条信息的工程含义是：代码中若仍在用 PRIORITY 帧做优先级表达可以继续工作（库仍实现），但新设计应当转向下一节的 RFC 9218 扩展优先级 API。
RFC 9218 扩展优先级：NGHTTP2_EXTPRI_* 系列
nghttp2 1.65.0 已内置 RFC 9218 扩展优先级（Extensible Priorities）支持，macros.rst 末尾用四个宏描述了其 urgency 模型：
#define NGHTTP2_EXTPRI_DEFAULT_URGENCY 3 #define NGHTTP2_EXTPRI_URGENCY_HIGH 0 #define NGHTTP2_EXTPRI_URGENCY_LOW 7 #define NGHTTP2_EXTPRI_URGENCY_LEVELS (NGHTTP2_EXTPRI_URGENCY_LOW + 1) /* 8 */（nghttp2.h#L4961-L4988）
关键要点：
- urgency 数值越小优先级越高：
NGHTTP2_EXTPRI_URGENCY_HIGH是0，NGHTTP2_EXTPRI_URGENCY_LOW是7，默认级别为3；NGHTTP2_EXTPRI_URGENCY_LEVELS派生为LOW + 1 = 8，表示共有 8 个离散级别； - 调度器按 urgency 分桶：会话结构体 nghttp2_session.h#L217 中有一个
sched[NGHTTP2_EXTPRI_URGENCY_LEVELS]数组，即为每个 urgency 级别维护一个就绪流调度队列——可以推断，发送调度时 nghttp2 会从高优先级（数字小）的桶开始取流； - 取值校验：nghttp2_http.c#L694-L695 在解析
:priority头部时，用val.integer < NGHTTP2_EXTPRI_URGENCY_HIGH || NGHTTP2_EXTPRI_URGENCY_LOW < val.integer判断非法值； - 边界兜底：nghttp2_session.c#L7791-L7792 中，若传入的 urgency 超过
NGHTTP2_EXTPRI_URGENCY_LOW，会被钳制为最低级别；而新流的默认 urgency 在 nghttp2_stream.c#L65 被初始化为NGHTTP2_EXTPRI_DEFAULT_URGENCY。
这几个宏构成了一组自洽的常量族：级别数量由LEVELS统一派生，调度桶数组大小、循环边界（如 nghttp2_session.c#L624 处的for (i = 0; i < NGHTTP2_EXTPRI_URGENCY_LEVELS; ++i)）都引用它，避免了魔数散落。
与 fluent-bit 主体的关系
nghttp2 在 fluent-bit 仓库中是作为 vendored 依赖完整内嵌在 lib/nghttp2-1.65.0 下的（含CMakeLists.txt、lib/、doc/等完整源码树），构建系统通过 cmake/nghttp2.cmake 一类的构建脚本将其编译进 fluent-bit。fluent-bit 自身的 HTTP/2 客户端即建立在该库之上：src/flb_http_client_http2.c 中定义了http2_send_callback、http2_header_callback、http2_frame_recv_callback等全套nghttp2_session_callbacks，并在会话创建处使用nghttp2_settings_entry session_settings[3]数组配置会话参数（见 flb_http_client_http2.c#L476-L477）。
对使用 fluent-bit 的开发者来说，本文宏参考的实际价值体现在：
- 调试 TLS 升级与 ALPN：当某些 HTTPS 输出端点协商失败时，可以对照
NGHTTP2_PROTO_ALPN的线路格式（0x02 'h' '2'）检查抓包中 ALPN 扩展内容； - 调整流控参数：为高吞吐输出流提升窗口时，
NGHTTP2_INITIAL_WINDOW_SIZE（65535）与NGHTTP2_MAX_WINDOW_SIZE（2147483647）给出了上下界； - 理解版本兼容：
NGHTTP2_VERSION_NUM的 24 位编码是 fluent-bit 构建与链接 nghttp2 时做版本兼容判断的基础。
小结
nghttp2 的宏集合虽然只有二十余个，却完整覆盖了 HTTP/2 实现中最常引用的“协议常量面”：版本识别、协议标识（h2/h2c/ALPN 线路格式）、客户端魔数、流控窗口、头部表与 SETTINGS 默认值、已弃用的权重常量，以及新一代 RFC 9218 扩展优先级的 urgency 常量族。macros.rst 提供语义说明，nghttp2.h 与 nghttp2ver.h 提供确切取值，而 nghttp2_alpn.c、nghttp2_session.c、nghttp2_http.c 等实现文件则展示了每个宏在握手机制中的真实落点——三者互为印证，构成了阅读 fluent-bit 内嵌 HTTP/2 栈的可靠起点。
【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
