网页入站接口规范 0.8.0

这些函数只读取当前 HTTP 请求，离开本次请求后不能调用。读取入站方法 返回宿主接收的方法文字；读取入站原路径 返回 URL 的百分号编码路径，不含查询串或片段；读取入站解码路径 对该路径严格解码一次百分号和 UTF-8，坏编码时报错；读取入站标头值 按 ASCII 不区分大小写的名称读取标头，缺失时返回空字符串。调用方若把路径当作文件名或包名，仍须验证解码后的斜线、控制字符与业务规则。

标头读取不会自动授予调用方使用凭据或向外转发的权限；网络、服务绑定和持久存储仍需独立能力与资源授权。无当前 HTTP 请求时调用失败。当前适配以 Worker 的原生 Request 实现，未来类型化 豫言操作系统网页服务 入口接通后可由请求值直接传递同一资料。

事件种类

读取入站事件种类 返回本次宿主调用的事件种类文字，一次调用内不变。云工宿主当前实际可返回下列取值：

• 携带当前 HTTP 请求：fetch（普通请求）、service-fetch（经服务绑定送达的请求）、durable-fetch（送达持久对象的请求）。本包其余读取函数只能在这三种事件内使用。
• 不携带 HTTP 请求：queue、scheduled、email、durable-alarm、durable-transaction、durable-block、durable-websocket-message、durable-websocket-close、durable-websocket-error、websocket-open、websocket-message、websocket-close、websocket-error、stream-pull、stream-cancel、html-element、html-text、html-comments、html-doctype、html-document-text、html-document-comments、html-end、html-end-tag、workflow、workflow-step、workflow-rollback。

其他宿主只返回自己实际提供的种类，宿主新增种类时须同步更新云工宿主的事件说明。应用只应依赖上述已文档化的取值；遇到不认识的取值，须按“没有 HTTP 请求的事件”处理，不得当作 fetch。

查询参数、来源与同源网址

读取入站查询参数 按浏览器 URL 查询参数规则读取第一个同名值，已经百分号解码；无该参数时返回空字符串。入站查询参数存在 按同一规则判断参数名是否出现，?after= 这样的空值仍返回阳，使应用能区分缺失与空值。读取入站来源 返回 URL 标准的 origin，供应用比较同源请求；它不代表已经完成跨站请求授权。构造入站同源网址 接受新绝对路径、待设置的键值列表及待删除的键列表；空路径保留原路径。宿主复制当前请求 URL，先删后设，未指定参数原样保留，并返回同源绝对网址，不发起请求。新路径须以单个 / 起首，拒绝 //、反斜线、控制字符、? 和 #；查询键和值由宿主编码。设置或删除列表各最多 16 项，超限失败。

读取入站主机名 返回当前请求 URL 的 hostname，依 URL 规则规范化为小写且不含端口。读取入站原查询 返回原请求的查询串，非空时保留开头 ?；它不进行参数解码，适用于保留现有查询的跳转。

标头存在性（0.7.0 新增）

入站标头存在 接受一个标头名称，返回当前请求是否含该标头：只要标头出现即为阳，值为空字符串也算出现；名称不区分大小写（headers.has 语义）。它补足 读取入站标头值 无法区分“缺失”与“空值”的缺口。名称必须是 RFC 9110 令牌字符（数字、字母与 !#$%&'*+-.^_|~`）组成的 1 至 256 字节字符串，否则属于违规，抛出可捕获的豫言异常，消息为“入站标头名称无效”。

有限正文读取（0.7.0 新增）

读取入站有限正文文字（宽松 UTF-8 解码）、读取入站有限正文严格文字（严格 UTF-8 解码）与 读取入站有限正文字节（原始字节）读取当前请求的正文，且从不缓冲超过所给上限。参数是字节上限，须在 1 至 16777216（16 MiB）之间，越界属于违规，抛出可捕获的豫言异常（“入站正文字节上限须在 1 至 16777216”）。返回二元组（状态，结果），状态是整数：

| 状态 | 含义 | 结果 | | --- | --- | --- | | 0 | 成功，正文不超过上限 | 文字或字节，可以为空 | | 1 | 正文超过上限 | 空 | | 2 | 没有正文：方法为 GET 或 HEAD，或宿主没有为该请求提供正文流 | 空 | | 3 | 正文已被读取：本包任一读取函数、宿主的其他读取，或其他读取器已锁定正文流 | 空 | | 4 | 仅严格文字：正文不是有效 UTF-8 | 空字符串 |

判定顺序固定：先验证参数；再判断 2 与 3；随后若请求的 Content-Length 全由 1 至 18 位十进制数字组成且已超过上限，或长达 19 位以上（必然超过任何上限），立即返回 1 而不读取任何字节；其余形态的 Content-Length 一概忽略，只按流式计数判断。读取时逐块累计字节数，一旦超过上限就取消读取流并返回 1，因此宿主最多持有已接受的字节再加使总数越界的那一块，不会继续读取更多数据；取消时上游的取消回调即使失败也被吞掉，仍返回 1。空正文流返回状态 0 与空结果。除状态 2、3 与由 Content-Length 预判得到的 1 之外，读取会消费或取消请求体，之后同一请求再读得到状态 3。

宽松文字的解码与 TextDecoder 整块解码的默认行为相同：非法序列各替换为 U+FFFD；只有整个正文开头的 BOM 被剥除，正文中间的 U+FEFF 原样保留；多字节字符跨块也能正确解码，且结果与如何分块无关。因每个非法字节都变成 3 字节的 U+FFFD，解码后文字可能长于字节数；若超过 16 MiB，属于违规，抛出可捕获的豫言异常（“宽松解码后的文字超过 16 MiB”）。严格文字按 fatal 解码：过长编码、代理对编码、越界码点、孤立的延续字节与末尾残缺序列都算非法，得状态 4，且发现后立即取消读取流；合法的正文与宽松文字的结果相同。字节接口原样返回全部字节，BOM 与零字节都保留。读取流本身失败（如连接中断）是平台故障，抛出含原因的可捕获异常（“读取入站正文失败：…”）。

JSON 正文

读取入站癸象正文文 从当前请求读取并解析一次 JSON 正文，返回可由豫言 癸象解析 再次解析的规范化 JSON 文字。0.7.0 起它先按上述规则以 2 MiB 上限读取字节（不再无界读取），再以 UTF-8 解码（剥除 BOM）并按 JSON 解析；对合法输入的行为不变，数字仍沿用宿主 JSON 解析的精度，规范化后的文字也不得超过 2 MiB。下列情形都是可捕获的豫言异常，且不会让宿主异常越过 Wasm 边界：正文超过 2 MiB（“入站 JSON 正文超过 2 MiB”）、没有正文、正文已被读取、JSON 无效或嵌套过深（消息以“入站 JSON 正文无效：”起首并含平台报告的原因）。此过渡文字边界将在类型化网页处理入口接通后由请求值替代。

有限 JSON 正文（0.8.0 新增）

读取入站有限癸象正文文 上限 是 读取入站癸象正文文 的有界、可分状态版本：不抛异常地区分各种正文问题，并让应用自己定字节上限（旧函数固定为 2 MiB，且所有失败都是异常）。它先按 读取入站有限正文严格文字 的全部规则读取正文（上限 1 至 8388608，即 8 MiB，越界属于违规，抛出可捕获的豫言异常“入站 JSON 正文字节上限须在 1 至 8388608”；判定顺序、Content-Length 预判、逐块累计与取消、状态含义都相同），严格按 UTF-8 解码（BOM 剥除），再交宿主的 JSON.parse 校验并由宿主 JSON.stringify 写成规范化文字。返回二元组（状态，文字）：

| 状态 | 含义 | 文字 | | --- | --- | --- | | 0 | 成功 | 规范化 JSON 文字（去冗白；数字按 ECMAScript 书写；重复键只保留最后一次的值并停在第一次出现的位置；整数样式的键按 JavaScript 对象规则排在最前） | | 1 | 正文超过上限 | 空 | | 2 | 没有正文（GET、HEAD 或宿主没有提供正文流） | 空 | | 3 | 正文已被读取或读取流已被锁定 | 空 | | 4 | 正文不是有效 UTF-8 | 空 | | 5 | 不是有效 JSON（语法错、畸形转义、嵌套过深等） | 平台报告的原因（供诊断，不宜原样回给客户端） |

与 读取入站癸象正文文 的区别：（1）上限由调用方给出，最大 8 MiB（旧函数 2 MiB）；（2）状态 1 至 5 用返回值表示，应用可以分别回应 413、400 等，不必解析异常消息；（3）状态 0 的文字保证可安全交给豫言 癸象解析——畸形转义、重复键与非法 UTF-8 已在宿主一侧排除或规范化，不会使 Wasm 不可捕获地中止；（4）文字长度不再单独限制为 2 MiB，但受上限约束的原始字节至多 8 MiB，规范化后至多略多（数字的 e+ 写法可使每个数字多一个字节），仍远小于宿主与 Wasm 之间 16 MiB 的交换缓冲。同一请求只能读一次正文；与本包其他读取函数混用时，后读者得状态 3。应用仍须自行校验 Content-Type 并检查顶层值的类型（本函数不要求顶层是对象）。

一致性样例（0.8.0 新增）：

| 情境 | 必须观察到 | | --- | --- | | 上限 1000，正文 { "a" : 1 , "b" : [ 2 ] } | （0，{"a":1,"b":[2]}） | | 正文 {"a":1,"b":2,"a":3} | （0，{"a":3,"b":2}） | | 正文 {"b":1,"2":2,"1":3} | （0，{"1":3,"2":2,"b":1}） | | 正文 {"a":"\u4e2d\/"}（含 \u4e2d 与 \/） | （0，{"a":"中/"}） | | 正文 {"a":1e21} | （0，{"a":1e+21}） | | 正文 {"a":"\x"} 或 {bad 或空正文的 POST（真实 workerd 上空流） | （5，非空原因） | | 正文 {"a":1} 恰好等于上限；上限减一 | （0，…）；（1，空） | | 声明 Content-Length 超过上限 | （1，空），一个字节也不读 | | GET 请求 | （2，空） | | 正文已被本包任一读取函数读过 | （3，空） | | 正文单字节 ff | （4，空） | | 上限 0 或 8388609 | 抛出可捕获的异常 |

违规：标头名称无效、上限越界、宽松解码后的文字超限。业务情形：有限正文读取的状态 1 至 4，用返回值表示。平台故障：读取流失败、当前没有 HTTP 请求，均抛出异常；JSON 正文的各种失败一律抛出异常。

跨宿主一致性

浏览器、Node.js 与原生宿主若实现本包，也必须给出相同的状态划分、判定顺序与限额；可观察语义以下列样例为准。

| 情境 | 必须观察到 | | --- | --- | | 上限 8，正文 8 字节分三块到达 | （0，该 8 字节） | | 上限 7，同一正文 | （1，空），读取流被取消，读到越界块后不再拉取 | | 声明 Content-Length: 11，上限 10 | （1，空），一个字节也不读 | | GET 请求或没有正文的 POST | （2，空）；真实 workerd 上没有正文的 POST 也可能得（0，空）（请求对象仍带一个空流），应用应把这两种结果都当作“没有正文” | | 正文已被读过的请求 | （3，空）；同一请求连续读两次，第二次为 3 | | 正文为单字节 ff | 宽松：（0，U+FFFD）；严格：（4，空字符串） | | 正文 EF BB BF 68 69 | 文字：（0，hi）；字节：（0，五个原始字节） | | 上限 0 或 16777217 | 抛出异常 | | 上限 16777216 的 16 MiB 正文 | （0，全部字节）；再多一个字节得 1 | | 请求头 X-Empty:（空值） | 入站标头存在 对 x-empty 得阳，对缺失名得阴 | | JSON 正文 {bad | 读取入站癸象正文文 抛出可捕获异常，消息含 SyntaxError 一类的原因 |

不做什么

本包不无界读取正文，不解压 Content-Encoding，不解析表单或 multipart，不校验 Content-Type，不读取或暴露 Request、Headers、流等宿主对象，也不枚举全部标头。需要这些能力时应另立接口。

补充：标头名校验与 JSON 正文规范文（独立审查后修订）

• 旧函数 读取入站标头值 的名称不合令牌规则（含空格、冒号、控制字符、非 ASCII、超过 256 字节）时，抛可捕获的「入站标头名称无效」，与 入站标头存在 一致，不再让宿主 Headers.get 的 TypeError 穿出。
• 读取入站癸象正文文 返回宿主规范化后的 JSON 文字（去冗白、数字按 ECMAScript 书写），不再经癸象解析与表示往返：大数组不再栈溢出，超过 2^53 的整数与 1e21 这类数值不再被回绕、截断或拒绝。应用再用癸象解析这段文字时，仍受癸象数值模型（64 位整数、六位小数表示）的限制。