网页请求之约 0.1.0

此包令浏览器中豫言之客，向本站（同源）发 HTTP 请求而读其文字之应。乃 fetch 之至简公共子集，为豫言单事环而设：发请求不候——发起网页请求立返请求号，请求于后台行，毕则宿主投类曰“请求”之事于统一事列（见[网页事件之约](../网页事件/规范.文言.md)）；多请求可同时在途，客仍可理界面之事，亦可随时取消网页请求。为简易之场，另附阻塞之变体请求网页文字。客依此包，诸术皆当具。

发往他来源之请求，及服务端之出站请求，分属[网络](../网络/规范.文言.md)（整体请求与应，暂无浏览器适配）与网页上游、授权服务等包，不在此包。

请求之癸象文

发起网页请求、请求网页文字之参数乃癸象对象，惟“网址”必填，余皆可省；出未知字段或类型不合，一概发事故。

| 字段 | 类型与默认 | 律 | | --- | --- | --- | | 网址 | 文，必填 | 以“/”首（非“//”首）之站内径，或与当前页同源之绝对网址；至多八千一百九十二 UTF-16 码元；无控制字符与反斜杠；片段（“#…”）略之 | | 方法 | 文，默认 GET | 惟 GET、HEAD、POST、PUT、PATCH、DELETE（大写） | | 标头 | 对象，默认无 | 名至值文；至多三十二项；名一至六十四个 ASCII 字母、数字、连字符；值至多四千零九十六码元而无控制字符；宿主拒 fetch 规范所禁之标头名（Cookie、Host、Content-Length、Origin、Referer、User-Agent、Connection、Transfer-Encoding、Upgrade、Via、Accept-Encoding、Date、Expect 及 Sec-、Proxy- 之首） | | 正文 | 文，默认无 | 请求之体，依 UTF-8 而发；至多八 MiB（UTF-8 字节）；GET、HEAD 带正文则违约。有正文而标头无 Content-Type，宿主不代为添，客当自书（如 application/json） | | 缓存 | 文，默认“默认” | “默认”依浏览器缓存之策；“不缓存”等于 cache: 'no-store' | | 超时毫秒 | 整数，默认六万 | 一至六十万；自发至读毕正文之总限 | | 正文上限 | 整数，默认八三八八六零八 | 一至一千六百七十七万七千二百一十六（字节）；应之体逾此则中止而报“正文过大” | | 标记 | 文，默认空 | 至多二百五十六码元；原样见于响应，供客配请求 |

宿主恒用 credentials: 'same-origin'（带本站之饼）与 mode: 'same-origin'（重定向至他来源即视为网络之错），随同源之重定向。请求癸象文整体至多十 MiB。

响应之癸象文

事详情与阻塞变体之返值乃同一形：

{"成":true,"状态":200,"状态文":"OK","网址":"https://例.站/cloud/api/session",
 "标头":{"content-type":"application/json","cache-control":"no-store"},
 "正文":"{\"user\":…}","字节数":1234,"标记":"会话"}

{"成":false,"原因":"超时","说明":"请求超过 60000 毫秒未完成","标记":"会话"}

成为真：得 HTTP 之应而读毕其体；任何状态码（含四百、五百）皆为“成”，客自察“状态”。“网址”乃随重定向后之终址；“标头”名一概小写，同名多值以“, ”连之，Set-Cookie 不可见；“正文”乃应体依严格 UTF-8所解之文（HEAD 与二百零四、二百零五之应为空文）；“字节数”乃应体之字节数。
成为假：“原因”惟四种——“网络错误”（连不通、重定向至他来源、为浏览器所拒等）、“超时”、“正文过大”、“正文不是有效UTF-8”；“说明”乃中文之释。
二形皆带“标记”（省则空文）。

诸术

发起网页请求：字符串，返整数

验请求癸象文后立返请求号（正整数，实例内递增，不复用），请求于后台行。毕则投一事：类曰请求，订阅号即请求号，名曰“完成”（成为真）或“失败”（成为假），详情为响应癸象。同时“在途或果尚未被客取”者至多三十二（含阻塞变体之请求），已至限则发事故——客当以己之状态机控其并发，并速取其果之事。

取消网页请求：整数，返爻

撤一请求。请求仍在行，或其结果之事尚在列而未取，则止其请求、去其事而返阳；号未知，或结果之事已被客取，则返阴。既撤，保证不复收此号之事，故客可以撤请求或世代号解“旧请求之应不得覆新态”之争。

请求网页文字：字符串，返字符串

阻塞变体：参数同发起网页请求，挂起当前调用，候请求毕，返响应癸象。候时他事照常入列，然客于此调返回前不理之，故惟宜启动时之一读，或明欲串行之场；欲并发或可撤者，用发起网页请求。违约之调用发事故；网络类之败归入响应（成为假），不发事故。阻塞变体不可撤，不生事，亦占并发之额。

事

等待网页事件所返之事癸象形如

{"类型":"请求","序":42,"订阅号":7,"名称":"完成","详情":{"成":true,"状态":200,…}}

“请求”类之事列自计其数，默认限一千零二十四；并发之限三十二（含果未取之请求），保结果不因积压而失。

限额与败之类

| 项 | 限 | | --- | --- | | 并发在途之请求（含果未取者） | 三十二 | | 请求癸象文 | 十 MiB；请求正文八 MiB；网址八千一百九十二码元；标头三十二项 | | 应体 | 默认八 MiB，可配至十六 MiB | | 超时 | 默认六十秒，可配一毫秒至十分钟 |

违约之调用（请求癸象文无效、字段未知或越界、网址非同源、并发已满、宿主已闭）发豫言事故，辞为中文而指其出错之字段。
运行时之败（网络错误、超时、正文过大、正文非有效 UTF-8）乃响应之一种，“成”为假，不发事故。
撤则不生任何事。

一致性之例

发起网页请求（{“网址”:“/api/甲”,“标记”:“a”}）返一；等待网页事件得类请求、订阅号一、名完成、详情状态二百、标记“a”、正文为服务器所返之文。
服务器返四百零四与癸象错体：仍为完成，状态四百零四，正文含错体。
三请求同发，服务器反序而返：三事依到达之序入列，订阅号各异。
发起后旋即取消网页请求：返阳，其后列中无此号之事。
服务器断连：失败，原因“网络错误”；应体含无效 UTF-8 字节：失败，原因“正文不是有效UTF-8”。
网址为 https://别处.站/x：发事故（非同源）；第三十三个并发请求：发事故。
请求网页文字于 /api/甲返响应癸象，候时所至之点击事仍在列，返后可取。

界

此包不定：跨来源请求（CORS）、请求与应之流式读写（服务端事件流见网页事件源包）、二进制正文与文件上传、进度事、FormData、Service Worker、HTTP 缓存之细、fetch 之 keepalive 与优先级。

豫言操作系统网页请求 0.1.0