http

模块边界

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 核心构建、单头包或 兼容性承诺。

字段

xhttpfield 只有 Name 和 Value 两个借用视图。字段名称不带冒号，字段值不带 两端 OWS 或 CRLF。

xrtHttpFieldParse 解析一条不含 CRLF 的字段行；xrtHttpFieldNext 逐行扫描字段 块；xrtHttpFieldBlockCount 在不保存描述符时完成严格验证和计数。

xrtHttpFieldWrite 写一条字段，xrtHttpFieldBlockWrite 写字段数组和可选最终空行。 两者都支持空输出测量，容量不足时不会部分写出。

查询函数包括：

• xrtHttpFieldNameEqual：ASCII 不区分大小写字段名比较；
• xrtHttpFieldFind、Get、Count：查找重复字段；
• xrtHttpFieldGetUnique：区分缺失、唯一和重复；
• xrtHttpFieldValueValid：验证字段值字节边界。

字段描述符可以未对齐，但描述符数组、借用文本和写出区不能发生不明确重叠。

Content-Length

xrtHttpContentLengthParse 接受十进制值和 RFC 允许的重复相同列表值，拒绝空值、 符号、非数字、溢出和冲突值。

该函数只解析单个字段值。HTTP/1 parser 会合并全部重复 Content-Length 字段， 同时执行 Transfer-Encoding 冲突和请求分帧检查。

token 与列表

• xrtHttpTokenValid 验证 RFC tchar；
• xrtHttpTokenEqual 和 xrtHttpMethodEqual 执行 ASCII 不区分大小写比较；
• xrtHttpTokenNext 迭代逗号 token-list；
• xrtHttpFieldTokenNext 跨重复同名字段迭代；
• xrtHttpFieldTokenCount、Find 处理重复字段集合；
• xrtHttpQualityParse 解析 0 到 1 的 qvalue 为 0 到 1000 定点数；
• xrtHttpWeightedTokenNext 迭代带权 token。

xrtHttpOwsTrim 只移除 SP 和 HTAB，不把其他空白字符当作 HTTP OWS。

方法与状态

xrtHttpStatusText 返回内置状态的标准 reason phrase。未知状态返回空视图，调用方 仍可用 uint16 写出扩展状态。

xrtHttpMethodSafe、xrtHttpMethodIdempotent 和 xrtHttpResponseContentAllowed 提供基础协议语义。它们不替代应用权限、重试和 缓存策略。

参数

启用 XRT_MODULE_HTTP_PARAM 后，xhttpparam 表达 name[=value]：

• XHTTP_PARAM_HAS_VALUE：存在等号和值；
• XHTTP_PARAM_QUOTED：值来自 quoted-string，视图不含外层双引号；
• XHTTP_PARAM_NONE：只有名称。

xrtHttpParamNext 迭代分号参数，xrtHttpDirectiveNext 迭代逗号指令。对应的 Count 和 Find 函数使用同一套严格语法。

xrtHttpQuotedValid、Read、Write 处理 quoted-string 和 quoted-pair； xrtHttpParamValueCursorInit 与 xrtHttpParamValueNext 零分配逐字节读取语义值， 并通过 Offset 暴露已经消耗的原始值长度；xrtHttpParamValueWrite 一次性输出 参数语义值；xrtHttpParamWrite 写单个参数。

Build 便利函数返回由 xrtFree 释放的零结尾字符串。热路径应优先使用测量加 调用方缓冲的 Write 版本。

Host 与 request-target

启用 http_host 后，xrtHttpHostParse 返回借用的 xhttpauthority； xrtHttpHostValid 执行同样的严格验证。解析过程不分配内存，IPv6 与 IPvFuture 字面地址的 Host 视图不包含方括号，PortText 保留显式端口的原始文本。

xrtHttpAuthorityValid 验证解析或手工构造的 authority。手工构造数值端口时设置 XHTTP_AUTHORITY_HAS_PORT | XHTTP_AUTHORITY_PORT_VALUE 并填写 Port，不需要伪造 PortText。xrtHttpAuthorityPort 将可用的显式端口写入调用方变量；省略端口或显式 空端口时返回调用方提供的默认值，超出 uint16 的合法协议端口文本不能直接交给 网络层，因此返回失败。

xrtHttpTargetParse 区分 origin-form、absolute-form、authority-form 和 asterisk-form，并结合方法检查 CONNECT 与 OPTIONS 的专用约束。结果同样只借用输入， 核心层不构建 URL 对象，也不执行查询参数解码。

已迁出能力

动态 Header 容器、RFC 8187 扩展值、MIME、Structured Fields、Digest Fields、 Forwarded、Link、Priority、Cache-Status、Proxy-Status 和 Content-Disposition 不属于 XRT HTTP 核心；需要这些高级协议能力时，请使用独立发布的 xhttp 扩展。