网页入站公约 0.8.0

诸术惟读当前 HTTP 请，离此请不可用。读取入站方法 返所受之法；读取入站原路径 返未析百分号之径，无查询与片段；读取入站解码路径 严析一次百分号与 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 查询之法，取首个同名之值，已析百分号；无则空文。入站查询参数存在 察同名之参有无，值空亦为有。读取入站来源 返 URL 所定之协议、主机与非默认端口，可供同源之比，不自授跨站之权。构造入站同源网址 受新绝对径、待设键值列与待删键列；空径守原。宿主复制当前请之网址，先删后设，余参皆留，返同源绝对址，不发请。新径须单一 / 起首，拒 //、反斜线、控字符、?、#；键值由宿主编码。设与删各至多十六项，逾限则败。

读取入站主机名 取当前请之主机名，循 URL 之规归小写，不含端口。读取入站原查询 取原查询文，有则含首 ?，无则空；不析参数，可供改址保留原查询。

头之有无（0.7.0 新增）

入站标头存在 受一头名，返当前请有无此头：头一出现即为阳，值空亦为出现；名不辨大小写（同 headers.has）。此补 读取入站标头值 不能辨「无」与「空」之缺。名须为 RFC 9110 令牌字（数、字母及 !#$%&'*+-.^_|~`）所成一至二五六字节之文，否则为违约，报可捕之事故，辞曰「入站标头名称无效」。

有限读正文（0.7.0 新增）

读取入站有限正文文字（宽解 UTF-8）、读取入站有限正文严格文字（严解 UTF-8）与 读取入站有限正文字节（原字节）读当前请之正文，而蓄积永不逾所授之限。参数为字节之限，须在一至一六七七七二一六（十六 MiB）之间，越界为违约，报可捕之事故（辞曰「入站正文字节上限须在 1 至 16777216」）。返二元组（状，果），状为整数：

| 状 | 义 | 果 | | --- | --- | --- | | 0 | 成，正文不逾限 | 文或字节，可空 | | 1 | 正文逾限 | 空 | | 2 | 无正文：法为 GET 或 HEAD，或宿主未予此请以正文之流 | 空 | | 3 | 正文已被读：本包任一读术、宿主他读，或他读器已锁其流 | 空 | | 4 | 惟严解之文：正文非有效 UTF-8 | 空文 |

断之序恒定：先验参数；次辨二与三；次若请之 Content-Length 全为一至十八位十进数字而已逾限，或长达十九位以上（必逾任何限），则径返一，不读一字节；其余形之 Content-Length 一概不理，惟以流中计数断之。读时逐块累计字节，一逾其限，即废读取之流而返一，故宿主至多蓄已受之字节与使总数越界之一块，不复多读；废时上游取消之回调纵败亦吞之，仍返一。空之正文流返状零与空果。除状二、状三及由 Content-Length 预断所得之一外，读必耗或废请之体，此后同请再读得三。

宽解之文与 TextDecoder 整块解之默认行同：非法序列各代以 U+FFFD；惟全正文之首 BOM 剥去，正文中间之 U+FEFF 原样存之；多字节之字跨块亦能正解，果与分块之法无涉。因每一非法字节皆化为三字节之 U+FFFD，解后之文或长于字节数；逾十六 MiB 者为违约，报可捕之事故（辞曰「宽松解码后的文字超过 16 MiB」）。严解之文依 fatal 而解：过长编码、代理对编码、越界码点、孤立之续字节及末尾残缺之序列皆为非法，得状四，且一见即废读取之流；正文合法者，其果与宽解同。字节之术原样返全部字节，BOM 与零字节皆存。读流自身败（如连线中断）为平台之故，报含因之可捕事故（辞曰「读取入站正文失败：…」）。

JSON 正文

读取入站癸象正文文 自当前请一次读析 JSON 正文，返可复以豫言 癸象解析 析之规范文。自 0.7.0 起，先依上文以二 MiB 为限读字节（不复无界读），后以 UTF-8 解之（剥 BOM）而按 JSON 析之；于合法之入，其行不变，数仍循宿主 JSON 析之精度，规范后之文亦不得逾二 MiB。下列诸情皆为可捕之事故，且不令宿主之异越过 Wasm 之界：正文逾二 MiB（辞曰「入站 JSON 正文超过 2 MiB」）、无正文、正文已被读、JSON 无效或嵌套过深（辞以「入站 JSON 正文无效：」起，并含平台所报之因）。俟类型化网页入口通，当以请求值代此过渡文界。

有限 JSON 正文（〇点八所增）

读取入站有限癸象正文文 上限 乃 读取入站癸象正文文 之有界而分状者：正文诸病不以异常告，而以返值别之；字节之限由客自定（旧术固为二 MiB，败皆为异常）。先依 读取入站有限正文严格文字 诸则读正文（限一至八三八八六〇八，即八 MiB，越界为违，告可捕之豫言异常“入站 JSON 正文字节上限须在 1 至 8388608”；判序、Content-Length 预断、逐块累计与止读、诸状之义皆同），严解 UTF-8（去字节序记），乃付宿主 JSON.parse 验之，由宿主 JSON.stringify 书为规范文。返二元「（状态，文）」：

| 状态 | 义 | 文 | | --- | --- | --- | | 零 | 成 | 规范之 JSON 文（去冗白；数依 ECMAScript 书；重键惟留末值而居初见之位；类整数之键依 JavaScript 物之则居前） | | 一 | 正文逾限 | 空 | | 二 | 无正文（GET、HEAD，或宿主未予体流） | 空 | | 三 | 正文已读或流已锁 | 空 | | 四 | 正文非有效 UTF-8 | 空 | | 五 | 非有效 JSON（语法误、转义畸形、嵌套过深等） | 平台所报之因（以供诊断，不宜原样返客） |

与 读取入站癸象正文文 之异：一、限由客授，至多八 MiB（旧术二 MiB）；二、状一至五以返值表，客可分别答四百一十三、四百等，不必析异常之辞；三、状零之文保可安付豫言 癸象解析——畸形转义、重键、坏 UTF-8 皆已在宿主一侧除去或规整，不致使 Wasm 不可捕地中止；四、文之长不复独限二 MiB，然受限之原始字节至多八 MiB，规范后至多略增（数之 e+ 写法可使每数增一字节），仍远小于宿主与 Wasm 间十六 MiB 之交换缓冲。同一请正文惟可读一次；与本包他读取术混用，后读者得状三。客仍须自验 Content-Type 与顶层值之类（此术不要求顶层为物）。

一致之例（〇点八所增）：

| 情境 | 必见 | | --- | --- | | 限一〇〇〇，正文 { "a" : 1 , "b" : [ 2 ] } | （零，{"a":1,"b":[2]}） | | 正文 {"a":1,"b":2,"a":3} | （零，{"a":3,"b":2}） | | 正文 {"b":1,"2":2,"1":3} | （零，{"1":3,"2":2,"b":1}） | | 正文 {"a":"\u4e2d\/"}（含 \u4e2d 与 \/） | （零，{"a":"中/"}） | | 正文 {"a":1e21} | （零，{"a":1e+21}） | | 正文 {"a":"\x"} 或 {bad 或空正文之 POST（真 workerd 上为空流） | （五，非空之因） | | 正文 {"a":1} 恰等于限；限减一 | （零，…）；（一，空） | | 所称 Content-Length 逾限 | （一，空），一字节不读 | | GET 请 | （二，空） | | 正文已为本包任一读取术所读 | （三，空） | | 正文单字节 ff | （四，空） | | 限〇或八三八八六〇九 | 告可捕之异常 |

违约：头名无效、限越界、宽解后之文逾限。业务之情：有限读正文之状一至四，以返值表之。平台之故：读流败、无当前 HTTP 请，皆报事故；JSON 正文诸败一律报事故。

跨宿主之一致

浏览器、节点与原生宿主若承此包，亦须给同一之状划、断序与限额；可察之义，以下列之例为准。

| 情 | 必见 | | --- | --- | | 限八，正文八字节分三块至 | （0，此八字节） | | 限七，同一正文 | （1，空），读流被废，读至越界之块后不复拉取 | | 声 Content-Length: 11，限十 | （1，空），一字节不读 | | GET 之请或无正文之 POST | （2，空）；真 workerd 上无正文之 POST 亦或得（0，空）（请求之器仍带一空流），应用当并视此二果为“无正文” | | 正文已被读之请 | （3，空）；同请连读两次，次为三 | | 正文为单字节 ff | 宽解：（0，U+FFFD）；严解：（4，空文） | | 正文 EF BB BF 68 69 | 文：（0，hi）；字节：（0，五原字节） | | 限〇或 16777217 | 报事故 | | 限 16777216 而正文十六 MiB | （0，尽字节）；多一字节则得一 | | 请之头 X-Empty:（值空） | 入站标头存在 于 x-empty 得阳，于所无之名得阴 | | JSON 正文 {bad | 读取入站癸象正文文 报可捕事故，辞含 SyntaxError 之类之因 |

所不为

此包不无界读正文，不解 Content-Encoding 之压，不析表单及 multipart，不验 Content-Type，不露 Request、Headers、流等宿主之物，亦不枚举诸头。需此诸能者，当另立公约。

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

• 旧术 读取入站标头值 之名不合令牌之则（含空格、冒号、控字、非 ASCII、逾二五六字节）者，抛可捕之「入站标头名称无效」，与 入站标头存在 同，宿主 Headers.get 之 TypeError 不复穿出。
• 读取入站癸象正文文 返宿主规范之 JSON 文（去冗白，数依 ECMAScript），不复经癸象解析与表示往返：大数组不溢栈，逾 2^53 之整数与 1e21 之类不被回绕、截断或拒。应用复以癸象解析此文者，仍限于癸象之数模（六十四位整数、六位小数之表）。