http_encoding

分层

xrtHttpQualityParse 与 xrtHttpWeightedTokenNext 位于 <xrt/http.h>，可解析任意 token [ weight ] 字段。需要支持 Brotli、Zstd 或应用私有编码时，可以直接使用这一层，不受内置编码集合限制。

xrtHttpAcceptEncodingInit、Add 和 Parse 在此基础上维护 gzip、deflate、 identity 与 wildcard 的有效质量。重复成员保留最高 qvalue，显式成员覆盖 wildcard。

xrtHttpAcceptEncodingValid 可验证由调用方保存或修改的公开协商状态；它是 零分配纯查询，不改变线程原有错误。

xrtHttpAcceptEncodingSelect 只在调用方给出的可用编码中选择。最高质量相同 时先使用 Preferred，再按 gzip、deflate、identity 排序。

Content-Encoding

同一模块也提供接收方 Content-Encoding 计划，但不绑定 Inflate 或 Body。 xrtHttpCodingParse 把 identity、gzip、兼容别名 x-gzip 和 deflate 映射到 内置枚举；未知合法 token 返回 XHTTP_CODING_NONE，调用方仍可通过原 token 接入 Brotli、Zstd 或应用私有解码器。

xrtHttpContentEncodingNext 按字段出现顺序遍历全部重复字段与列表成员，忽略 RFC 列表中的空成员。xrtHttpContentEncodingPlan 一次汇总字段数、总层数、 内置解码器数、未知层数和原字段值合并后的精确大小。计划不分配内存，也不把 未知层当作错误，因此代理可以保留原始表示，高级客户端则可以选择自动解码、 原样交付或拒绝。

解码顺序必须与字段中的应用顺序相反。例如 gzip, deflate 表示先 gzip、 再 deflate，接收端必须先解 deflate、再解 gzip。identity 按无变换层容错， 但发送方不应在 Content-Encoding 中生成它。

xrtHttpContentEncodingWrite 以 ", " 连接重复字段的原始值，适合删除 Content-Encoding 后保留诊断元数据。它不附加零字符，支持空输出查询精确大小， 容量不足时不会写出部分结果。游标、计划、大小槽和输出区都不能覆盖字段描述符或 借用文本，协议层会在写入前拒绝重叠参数。

缺失与空值

• 没有 Accept-Encoding Header：RFC 9110 规定任意内容编码都可接受。
• 存在空 Header：客户端不希望响应使用内容编码，只选择 identity。
• 未显式列出 identity：默认可接受；只有 identity;q=0，或没有更具体

identity 时的 *;q=0，才排除 identity。

• 已知和 wildcard 质量均为零且 identity 也被排除：选择结果为

XHTTP_CODING_NONE，高层服务器通常应返回 406。

协议接受能力不等于服务器策略。为兼容不完整的旧客户端，高层自动压缩默认可 选择在 Header 缺失时仍发送 identity；纯协商层仍完整保留 RFC 语义。

模块边界

http_decode 才依赖 Inflate，http1_net 才依赖网络块链，http1_tls 才依赖 TLS Stream。 只启用连续内存 HTTP/1 解析不会带入压缩、网络、TLS 或 WebSocket。

借用模型

xhttpfield、xhttp1head、xhttp1message 和所有语法游标都借用调用方输入。 解析器不复制字段名称和值，输入缓冲和字段描述符数组必须覆盖借用视图的使用期。

请求方法同时以原始 xhttp1head.Method 视图和 xhttp1head.MethodCode 枚举发布。 xrtHttpMethodParse 按大小写敏感规则识别 GET、HEAD、POST、PUT、DELETE、CONNECT、 OPTIONS、TRACE 和 PATCH；合法但未内置的方法返回 XHTTP_METHOD_OTHER，非法 token 返回 XHTTP_METHOD_INVALID。每个非零枚举值占用独立 bit，既可以作为实际方法直接 比较，也可以通过位或组合成路由方法集合。XHTTP_METHOD_CRUD 覆盖 GET、POST、PUT、 PATCH 和 DELETE，XHTTP_METHOD_ANY 覆盖全部内置方法及 OTHER；应用仍应保留原始 视图处理具体的扩展方法。

字段描述符允许位于合法的未对齐存储。实现使用安全加载，不要求调用方为了协议 解析调整缓冲布局。

XRT 不再提供动态 Header 容器。需要拥有、修改或索引 Header 的框架应在 xhttp 中建立对象模型；快速路径可以直接使用栈数组或应用自己的存储。

Host 语法

xrtHttpHostParse 保留 Host、可选端口和 IP-literal 分类，任意长度十进制端口在 协议层仍然合法，只有可放入 uint16 的值才带 XHTTP_AUTHORITY_PORT_VALUE。 xrtHttpIpv4Valid 与 xrtHttpIpv6Valid 是无错误副作用的纯谓词，公开同一套严格 IP 文本规则，扩展协议无需复制 Host 内部解析器。

xrtHttpParamHostValid 直接消费 xhttpparam 的语义值。quoted-pair 会在验证时 流式解码，任意长度 reg-name 与 IPvFuture 不进入固定缓冲，也不申请堆内存。

Header 解析

xrtHttp1RequestParse 和 xrtHttp1ResponseParse 接受从消息首字节开始的累计输入：

• XHTTP1_MORE：输入尚未包含完整 Header；
• XHTTP1_FIELDS：Header 完整，但字段描述符容量不足，FieldCount 给出需求；
• XHTTP1_READY：解析完成；
• XHTTP1_ERROR：协议、限额或参数错误。

解析器只接受 CRLF，拒绝 obs-fold、裸 LF、非法字段名、控制字符、冲突的 Content-Length、歧义 Transfer-Encoding 和非法 Upgrade。xhttp1errorinfo 提供稳定错误码、消息相对偏移和行号。

xhttp1limits 分别限制 Header 总长度、起始行、单字段行和字段数量。默认值面向 公网输入，服务端应按路由策略进一步收紧，而不是无上限增长接收缓冲。

网络热路径使用 xrtHttp1RequestParseBuffer、xrtHttp1ResponseParseBuffer 直接扫描 xnetbuf。只有完整 Header 跨块时才连续化实际 Header 前缀，函数不消费输入，Upgrade 后的余量 保持原位。TLS 对应入口是 xrtHttp1RequestParseTls、xrtHttp1ResponseParseTls；输入不足时它们 通过 xrtTlsStreamReadMore 请求下一段受限明文，Header 完成后仍由调用方消费 Head.Bytes。

正文计划

Header 完成后必须调用：

• xrtHttp1RequestBodyPlan 处理请求；
• xrtHttp1ResponseBodyPlan 处理响应，并传入原请求方法。

xhttp1bodyplan 的模式是唯一分帧结论：

• XHTTP1_BODY_NONE：没有正文；
• XHTTP1_BODY_FIXED：Content-Length 定长；
• XHTTP1_BODY_CHUNKED：分块编码；
• XHTTP1_BODY_CLOSE：由可靠 EOF 定界；
• XHTTP1_BODY_TUNNEL：CONNECT 或 101 后的字节不再属于 HTTP。

响应计划覆盖 HEAD、成功 CONNECT、1xx、204 和 304。调用方不应仅凭 Content-Length 判断响应正文。

流式接收

xrtHttp1BodyInit 创建无分配 reader。xrtHttp1BodyRead 每次返回一个借用正文 片段、容量请求或终态，并通过 Consumed 精确说明已消费线路字节。

xrtHttp1BodyLimitsInit 的 MaxBody 默认为 UINT64_MAX，因为底层 reader 不拥有、 聚合或分配正文。服务端、代理以及任何会持有正文的上层必须在接收前按路由和内存预算 设置有限上限，不能把该协议层默认值直接作为公网接收策略。

对于 chunked，reader 会验证 chunk-size、扩展语法、CRLF、last-chunk 和 trailer， 并严格拒绝 chunk-size 与分号或 CRLF 之间的空白，避免端点对报文边界产生分歧。 正文视图不包含分块元数据。Received 是应用正文长度，WireBytes 是正文区实际 线路长度。

当返回 XHTTP1_BODY_FIELDS 时，TrailerCount 给出所需描述符数量。调用 xrtHttp1BodyTrailers 绑定足够存储后，用同一输入继续解析，不会丢失进度。

close-delimited 模式只有在传输层给出可靠 EOF 时才传入 bEnd = true。超时、取消、 RST 和普通 EOF 不能混为同一种上层状态。

gzip 自动解码

xrtHttpDecodeCreate 直接读取解析后的字段数组。把 xrtHttp1BodyRead 发布的每个 正文片段交给 xrtHttpDecodeWrite，并只在 body reader 完成时设置 bFinal。

identity 和显式原样回退路径不复制输入。gzip/deflate 路径按 Content-Encoding 逆序流式解码，验证 gzip Header、CRC、ISIZE 和压缩流终态。每个中间层与最终 输出都受同一明文硬限额约束。

详见 HTTP 正文解码。

原始写出

xrtHttp1RequestWrite 和 xrtHttp1ResponseWrite 不添加 Host、Date、Server 或其他 策略字段。空输出用于精确测量，容量不足不会产生半个 Header。

高性能发送建议：

1. 在连接或协程栈上的小缓冲中写 Header； 2. 用 xrtNetStreamSendVec 一次提交 Header 与小正文； 3. 大正文用 xrtNetStreamSendRef、SendRefs、SendTake 或 SendBuffer； 4. chunked 正文只用 xrtHttp1ChunkLineWrite 生成短前缀，数据本身保持引用发送； 5. XNET_RESULT_AGAIN 时等待 writable/drain，不绕过网络队列硬上限。

这条路径只构造必需的线路字节，不创建请求、响应、字典或正文对象。

报文长度

• xhttp1head.Bytes：起始行、Header 和最终空行的线路长度；
• xhttp1bodyplan.Length：定长正文长度，仅在 FIXED 模式有效；
• xhttp1body.Received：已经发布的应用正文长度；
• xhttp1body.WireBytes：已经消费的正文线路长度；
• xhttp1message.Wire.Size：连续输入中第一条完整消息的线路总长度；
• xhttp1message.BodyBytes：移除 chunked 元数据后的正文长度。

chunked 和 close-delimited 消息在完成前不存在可提前得知的总线路长度。

TLS 与 Upgrade

HTTP 不拥有 TLS。http1_tls 只是块链适配器，不创建连接或安全策略；证书验证、SNI、会话恢复和 ALPN 仍属于通用 TLS 模块。它按需连续化实际 Header，不增加连接级固定缓冲。

xrtHttpUpgrade*、xrtHttpConnection* 和 WebSocket 握手函数共同完成 Upgrade 验证。101 后的剩余字节必须原样交给新协议，不能继续送入 HTTP body reader。

完整消息便利层

xrtHttp1RequestMessageParse 和 xrtHttp1ResponseMessageParse 适合已经连续驻留在 内存中的报文、测试和协议网关。它们仍只借用输入，不持有堆对象。

固定长度或 close-delimited 正文可由 xrtHttp1MessageBodyView 直接查看；chunked 正文使用 xrtHttp1MessageBodyCopy 去除分帧。真正的网络热路径应优先使用流式 body reader，避免等待和复制整个消息。

扩展库边界

客户端池、重定向、重试、缓存、认证、Cookie、MIME、Multipart、FormData、SSE、 服务器路由和中间件属于独立发布的 xhttp 扩展；它们不参与 XRT 核心构建、单头包或 兼容性承诺。