向授权 HTTPS 来源或运行时登记的公网 HTTPS 上游请求，增量读取回应或将其正文流转给当前入站请求。
源码浏览已生成；不能解析的文件以纯文本展示，不表示通过类型检查。
# 网页上游接口规范 0.2.0 本包用于同时持有当前入站请求与被授权出站 HTTPS 来源的宿主。`请求授权网页上游` 接受绝对 URL、方法、请求标头列表、正文文字和超时毫秒数。宿主须对每次请求核对当前程序许可的完整来源（方案、主机、端口），拒绝 URL 凭据、非 HTTPS、未授权来源与自动重定向；不能先发请求再核对。首版方法限 GET、HEAD、POST；请求头只允许 `Authorization`、`Content-Type`、`Accept`、`X-Yuyan-Request-ID`，不允许重复，最多 16 项；GET/HEAD 正文必须为空，其他正文至多 2 MiB；超时范围为 1 至 180000 毫秒，覆盖“发请求、等响应头、读响应正文”的整次交换。传输失败或超时返回阴和错误文字，成功返回阳和仅本次入站请求有效的响应柄。HTTP 错误状态仍属于成功取得的响应。响应柄不得在请求间保存或伪造；宿主逐次核对归属。 请求头的值须只含可见 ASCII 字符（0x20 至 0x7E）、首尾不得为空格：`Authorization` 至多 8192 字节，其余至多 512 字节；`X-Yuyan-Request-ID` 的值须恰为 36 个字符，只含小写十六进制数字与连字符。名与值不合规抛豫言异常，不发请求。 `读取网页上游状态` 返回原上游状态。`读取网页上游癸象正文文` 一次性读取有效 JSON 正文，规范化后最多 2 MiB；它消耗上游正文。`回应入站以上游流` 保持上游正文流，不缓冲或改写字节，并以状态 200 回应当前入站请求。它只接受 `Content-Type`、`Cache-Control`、`X-Yuyan-Model`、`X-Content-Type-Options` 四种响应头，至多 8 项，不允许重名；其他头和无效值失败。它占用当前入站请求唯一的最终响应，并消耗响应柄；此前若已读取正文或设置最终响应则失败。应用先检查上游状态再选择流式成功响应或错误答复。 当前 `_start` 装载边界用不透明文字标识响应柄。此标识是本次请求内的宿主资源，不是 URL、数据正文或可移植的序列化格式。长期类型化入口可用名义资源类型替换标识，不改变授权与流语义。 ## 0.2.0 新增：增量读取与动态公网 HTTPS 上游 0.2.0 新增四个读取函数与 `请求公网HTTPS上游`，并给请求标头增加 `X-Yuyan-Request-ID`。`请求授权网页上游` 等 0.1.0 函数的签名与语义不变（仅上述标头值校验为新增的收紧）。新增部分服务于“向服务商上游发 POST，边读 SSE/NDJSON 边转发并计费”的应用。 ### 响应柄与增量读取 `请求授权网页上游` 与 `请求公网HTTPS上游` 签发的响应柄，都可用于 `读取网页上游状态` 与下列读取函数；不是本包签发的字符串一律抛豫言异常。响应柄仅在创建它的事件内有效，同一柄的读取应当串行，不同柄可交错。增量读取会消耗并锁定响应正文：某柄一经开始增量读取（或已定局），`读取网页上游癸象正文文` 与 `回应入站以上游流` 对它抛豫言异常；要整体读取应改用 `读取网页上游有限文字`。 `读取网页上游标头值(柄, 名)` 返回响应标头值，名不区分大小写、须是 1 至 128 字节的合法标头令牌，缺失返回空字符串。 `读取网页上游文字块(柄, 最大字节)` 返回“（状态，文字）”，最大字节须在 1 至 65536 之间，否则抛豫言异常。 - 状态 0：数据块。宿主做流式 UTF-8 解码：跨上游块拆开的多字节字符正确拼接，非法序列各换成 U+FFFD，流首的字节序标记去掉，文字绝不含被截断的半个字符；不足一个完整字符的上游块不单独返回，宿主继续读取（上游连续送来 64 个以上空块的极端情形，可返回文字为空的状态 0，应用照常继续读取）。每次返回文字的 UTF-8 字节数不超过最大字节（小于 4 按 4 计）；过大的上游块或因 U+FFFD 而超出的部分留在宿主，由后续调用依序返回。 - 状态 1：正文读尽，文字为空（无正文的响应首次读取即得）。流末尾残缺的字符序列先以一个 U+FFFD 作状态 0 的块返回，再返回状态 1。 - 状态 2：读取错误，文字为平台报告的原因，形如“名称: 消息”。 - 状态 3：期限已满，或应用已取消，或有限读取因超限已取消；文字是简短说明，仅供诊断。期满时宿主同时取消上游。 - 状态 1、2、3 是终态，此后再调用返回同样的终态与文字。 `读取网页上游有限文字(柄, 字节上限)` 一次读完剩余正文，字节上限须在 1 至 8388608 之间，否则抛豫言异常。状态 0：成功，文字为剩余正文（含尚未交付的部分）；状态 1：超过上限，文字为空，宿主已取消上游——先看 `Content-Length`，声明超限则一字不读，无声明或不实则流式累计，累计原始字节超过上限即取消，超出部分不返回，恰等于上限不算超限；状态 2：错误；状态 3：期限已满或已取消。 `取消网页上游(柄)` 取消对响应正文的读取并对上游响应流执行 cancel（对外发连接即断开连接），此后读取返回状态 3；幂等，无效的柄抛豫言异常。上游能否即时观察到取决于平台，不作保证。 ### 动态公网 HTTPS 上游 `请求公网HTTPS上游(网址, 方法, 标头, 正文, 超时毫秒)` 返回“（成功，响应柄或错误文）”，用于应用在运行时登记的、无法列入静态来源清单的上游（例如服务商自己填写的模型端点）。 - 许可：应用须声明“允许动态公网 HTTPS”。云工宿主现以程序许可 `OUTBOUND_ORIGINS` 含通配来源 `https://*` 表示；此通配来源只用于本函数，不使 `请求授权网页上游` 放行任何真实来源。宿主可另设等价形式（如 `PUBLIC_HTTPS`）。未声明则抛豫言异常，不发请求。 - 网址规则（适配在发请求前逐次严格校验，通过后以 URL 规范化的完整网址发出）：原文 1 至 2048 字节，只含可见 ASCII，无空白、控制字符、反斜线、问号、井号；以 `https://` 开头（小写）；无用户信息（含 `@`）、无查询、无片段，路径任意；主机名（规范化后）只含 `a-z`、`0-9`、`.`、`-`，至少含一个点，不以点开头或结尾，无连续点，每段 1 至 63 字符且不以连字符开头或结尾，总长 3 至 253，末段不得全为数字——由此拒绝 IPv4 字面量及其十进制、十六进制、八进制写法，方括号形式的 IPv6 因含非法字符而拒；拒绝 `localhost`、`*.localhost`、`*.local`、`*.internal`、`*.localdomain`、`*.arpa`（含 `*.home.arpa`）、`*.lan`、`*.home`、`*.corp`、`*.intranet`、`*.private`；带点的非 ASCII 域名须已是 `xn--` 形式。 - 端口规则：省略（即 443）、443、2053、2083、2087、2096、8443、11434，以及 8000 至 9999；其余（含全部小于 1024 的端口、10000 及以上除 11434 者）拒绝。选取依据：443 与 Cloudflare 代理支持的 HTTPS 备用端口，8443 与 8000 至 9999 为常见应用高位端口，11434 为常见本地模型服务端口。 - 方法：精确的 `GET` 或 `POST`；`GET` 的正文必须为空。 - 标头：至多 8 项；名只允许 `Content-Type`、`Accept`、`X-Yuyan-Request-ID`（不区分大小写，不得重复）；值规则同上（除请求编号外至多 512 字节的可见 ASCII，请求编号须恰 36 个小写十六进制与连字符字符）。不允许 `Authorization`、`Cookie` 等。 - 正文：至多 2 MiB，按字节发送，不经 JSON 转义。 - 超时毫秒：1 至 900000，覆盖发请求至读完正文的整次交换。 - 不跟随重定向：3xx 作为成功响应返回，状态码与 `Location` 可读，由应用当成“服务商请求失败”。 - 失败：许可未声明与参数违规（方法、标头、正文、超时）抛豫言异常；网址不合公网规则、传输失败、响应头前期满返回“阴”和原因（此为可恢复情形，应用按“服务商不可达”处理）；成功返回“阳”和响应柄，读取与取消同上。 网址规则只约束网址的形式。名称解析后落到私有地址的情形（如公开域名解析为内网地址）由平台的出站网络策略约束，本接口不替代；应用仍应在登记端点时做同样的校验。 ### 失败分类 | 情形 | 类别 | | --- | --- | | 请求头、方法、正文、超时、块上限、字节上限、标头名等参数违规；无效响应柄；已增量读取后再整读或转流答；公网函数无许可 | 抛豫言异常，不发请求 | | 未授权来源（静态函数）、发请求失败、响应头前期满；公网网址不合规则 | 返回“阴”和原因 | | 读取中上游出错、期满、取消、超限 | 读取函数的状态 2、3、1 | | HTTP 4xx、5xx、3xx | 成功响应，由应用按状态码处理 | ### 限额 请求头 16 项（公网 8 项）；请求头值 512 字节（`Authorization` 8192）；请求正文 2 MiB；静态超时 180000 毫秒，公网 900000 毫秒；块 65536 字节；有限整读 8 MiB；`读取网页上游癸象正文文` 沿用 2 MiB。 ### 跨宿主一致性 不同宿主须满足：网址与来源核对先于发请求；流式 UTF-8 解码与拼接；期限覆盖全程且期满后读取返回状态 3 并对上游流执行 cancel；取消对上游流执行 cancel；先看声明长度再读；不跟随重定向；公网网址规则逐条一致。 ### 一致性样例 - 5 帧 SSE 经静态来源或公网函数读取，文字与累计字节和整体一致（同授权服务样例）。 - 公网函数拒绝并返回“阴”（不发请求）：`https://127.0.0.1/x`、`https://0x7f.0.0.1/x`、`https://2130706433/x`、`https://0177.0.0.1/x`、`https://127.1/x`、`https://[::1]/x`、`https://localhost/x`、`https://LOCALHOST./x`、`https://a.localhost/x`、`https://db.internal/x`、`https://router.home.arpa/x`、`https://user:pw@api.provider.com/x`、`https://api.provider.com@evil.com/x`、`http://api.provider.com/x`、`https://api.provider.com/x?y=1`、`https://api.provider.com:22/x`、`https://provider/x`。 - 公网函数接受：`https://api.provider.com/v1/chat`、`https://API.Provider.COM:443/a/../v1`（规范化为 `https://api.provider.com/v1`）、`https://api.provider.com:8443/x`、`https://xn--fsqu00a.xn--fiqs8s/x`。 - 请求头 `X-Yuyan-Request-ID` 为大写十六进制、35 位、含空格或路径分隔符：抛异常。 - 公网上游回 302：函数成功，状态码 302，`Location` 可读。 - 程序许可未声明通配来源：公网函数抛异常，且无请求发出。 ### 边界 宿主不保证上游观察到取消或断开，只保证读取一方立即得到状态 3、不再拉取上游。本包不提供：选择多个流中先到者的原语；跨事件保存响应柄；名称解析结果的检查；HTTP/2 推送；自动重试；上游身份验证头（公网函数不许 `Authorization`）。宿主执行事件的总时限由宿主配置，本包只保证按给定期限令读取失败。
# 网页上游之约 0.2.0 此包供宿主兼持当前入站请与获授外发 HTTPS 来源。`请求授权网页上游` 受绝对址、法、请头列、正文与超时毫秒。宿主每请先核程序所授完整来源（方案、主机、端口），拒 URL 凭据、非 HTTPS、越授来源与自动转址；毋先发后验。初版法限 GET、HEAD、POST；请头惟许 `Authorization`、`Content-Type`、`Accept`、`X-Yuyan-Request-ID`，不许重名，至多十六；GET/HEAD 正文必空，余正文不逾二 MiB；时限一至十八万毫秒，贯“发请、候答头、读答文”之全程。传输败或逾时返阴与错文，成则阳与惟本次入站请可用之答柄。HTTP 错号仍属得答。柄不得跨请留存、伪造；宿主逐次核其归属。 请头之值，惟可见 ASCII 字（自空格至 `~`），首尾不得为空格：`Authorization` 至多八一九二字节，余至多五一二字节；`X-Yuyan-Request-ID` 之值必恰三十六字，惟小写十六进制数与短横。名与值不合规则告豫言异常，不发请。 `读取网页上游状态` 返原上游状态。`读取网页上游癸象正文文` 一次读析有效 JSON，规范后不逾二 MiB，并耗正文。`回应入站以上游流` 存上游正文原流，不缓冲、不改字节，以二百答当前入站请。覆头惟许 `Content-Type`、`Cache-Control`、`X-Yuyan-Model`、`X-Content-Type-Options` 四名，至多八项，不许重名；异名坏值皆败。此术占当前请惟一终答，并耗答柄；正文既读或终答既设则败。客先验上游状态，乃择成功流答或错答。 今 `_start` 载界以不透明文号指答柄。此号惟本请宿主资源，非网址、正文与可移植序文。俟类型化入口可用，可以名义资源类型代之，授权与流义不变。 ## 〇点二新增：渐读与动态公网 HTTPS 上游 〇点二增四读术与 `请求公网HTTPS上游`，并于请头增 `X-Yuyan-Request-ID`。`请求授权网页上游` 等〇点一之术，其型与义不变（惟上述头值之验为新增之收紧）。所增者，为“向服务商上游发 POST，边读 SSE/NDJSON 边转而计费”之客而设。 ### 答柄与渐读 `请求授权网页上游` 与 `请求公网HTTPS上游` 所发答柄，皆可用于 `读取网页上游状态` 及下列读术；非本包所发之文皆告豫言异常。答柄惟创之之事有效，同柄之读当有序，异柄可错综。渐读则耗而锁答文：柄一旦始渐读（或已定局），`读取网页上游癸象正文文` 与 `回应入站以上游流` 于其皆告豫言异常；欲整读者，当改用 `读取网页上游有限文字`。 `读取网页上游标头值(柄, 名)` 返答头之值，名不分大小写，须为一至一二八字节之合法头令牌，无则空文。 `读取网页上游文字块(柄, 最大字节)` 返「（状态，文）」，最大字节当在一至六五五三六之间，否则告豫言异常。 - 状态零：得一块。宿主流式解 UTF-8：跨上游块而裂之多字节字必正相衔，非法序各易为 U+FFFD，流首字节序记去之，文绝无半字；上游块不足一整字者不单返，宿主续读（上游连送六十四空块以上之极端，可返文空之状态零，客照常续读）。每返之文，其 UTF-8 字节数不逾最大字节（不足四者以四计）；上游块过大，或因 U+FFFD 而溢者，余留于宿主，由后续之调依次返之。 - 状态一：正文读尽，文空（无正文之答首读即得）。流末残缺之字序，先以一 U+FFFD 为状态零之块返之，乃返状态一。 - 状态二：读败，文为平台所报之因，形如“名称: 消息”。 - 状态三：期满，或客已止之，或有限整读因逾限已止；文为简说，惟供察验。期满时宿主同止上游。 - 状态一、二、三为终态，此后再调，返同一终态与文。 `读取网页上游有限文字(柄, 字节上限)` 一次读毕余文，字节上限当在一至八三八八六〇八之间，否则告豫言异常。状态零：成，文为余下正文（含未交之部）；状态一：逾上限，文空，宿主已止上游——先观 `Content-Length`，所称已逾则一字不读，无所称或不实则流式累计，累计原字节逾上限即止，逾出之部不归客，恰等于上限不为逾；状态二：败；状态三：期满或已止。 `取消网页上游(柄)` 止读答文而对上游答流行 cancel（于外发之连则断其连），此后之读返状态三；幂等，柄无效则告豫言异常。上游能否即得见，视平台而定，不作保证。 ### 动态公网 HTTPS 上游 `请求公网HTTPS上游(网址, 方法, 标头, 正文, 超时毫秒)` 返「（成否，答柄或误文）」，为客于运行时所录、不能列入静态来源清单之上游（如服务商自填之模型端点）而设。 - 许可：客必声明“许动态公网 HTTPS”。云工宿主今以程序许可 `OUTBOUND_ORIGINS` 含通配来源 `https://*` 表之；此通配惟此术用，不使 `请求授权网页上游` 放行任何真来源。宿主可另设等价之式（如 `PUBLIC_HTTPS`）。未声明则告豫言异常，不发请。 - 址之则（适配于每次发请之前严验，过者以 URL 规范化之全址发出）：原文一至二〇四八字节，惟可见 ASCII，无空白、控字、反斜线、问号、井号；以小写 `https://` 起；无用户信息（含 `@`）、无询串、无片段，径任意；主机名（规范化后）惟含 `a-z`、`0-9`、`.`、`-`，至少一点，不以点始终，无连点，每段一至六十三字且不以短横始终，总长三至二五三，末段不得全为数字——是以拒 IPv4 字面及其十进、十六进、八进之写法，方括号之 IPv6 以含非法字而拒；拒 `localhost`、`*.localhost`、`*.local`、`*.internal`、`*.localdomain`、`*.arpa`（含 `*.home.arpa`）、`*.lan`、`*.home`、`*.corp`、`*.intranet`、`*.private`；带点之非 ASCII 域名须已作 `xn--` 形。 - 端口之则：省略（即四四三）、四四三、二〇五三、二〇八三、二〇八七、二〇九六、八四四三、一一四三四，及八〇〇〇至九九九九；余（含一切小于一〇二四者、一〇〇〇〇以上除一一四三四者）皆拒。所以取之：四四三与 Cloudflare 代理所支持之 HTTPS 备用端口，八四四三与八〇〇〇至九九九九为常见应用高位端口，一一四三四为常见本地模型服务端口。 - 法：正为 `GET` 或 `POST`；`GET` 之正文必空。 - 头：至多八项；名惟 `Content-Type`、`Accept`、`X-Yuyan-Request-ID`（不分大小写，不得重出）；值之则同上（请求编号外至多五一二字节之可见 ASCII，请求编号必恰三十六字之小写十六进制与短横）。不许 `Authorization`、`Cookie` 等。 - 正文：至多二 MiB，以字节发之，不经 JSON 转义。 - 超时毫秒：一至九〇〇〇〇〇，贯发请至读毕之全程。 - 不随转址：三百号作成功之答而返，状态号与 `Location` 可读，由客视为“服务商请求败”。 - 败：许可未声明与参违规（法、头、正文、时限）告豫言异常；址不合公网之则、传输败、答头未至而期满，返“阴”与因（此为可复之情，客宜按“服务商不可达”处之）；成则返“阳”与答柄，读与止同上。 址之则惟约址之形。名解析后落于私有地址者（如公域名解为内网址），由平台之出站网策约之，此约不代；客于录端点时仍宜行同验。 ### 败之分类 | 情形 | 类 | | --- | --- | | 请头、法、正文、时限、块限、字节上限、头名诸参违规；柄无效；渐读后复整读或转流答；公网术无许可 | 告豫言异常，不发请 | | 未授来源（静态术）、发请败、答头未至而期满；公网址不合则 | 返“阴”与因 | | 读时上游出错、期满、已止、逾限 | 读术之状态二、三、一 | | HTTP 四百、五百、三百号 | 得答之成，由客按状态号处之 | ### 限额 请头十六项（公网八项）；请头值五一二字节（`Authorization` 八一九二）；请正文二 MiB；静态时限十八万毫秒，公网九〇〇〇〇〇毫秒；块六五五三六字节；有限整读八 MiB；`读取网页上游癸象正文文` 仍二 MiB。 ### 异宿主之一致 异宿主必守：址与来源之核先于发请；流式解 UTF-8 而相衔；期限贯全程，期满则读返状态三并对上游流行 cancel；止则对上游流行 cancel；先观所称之长而后读；不随转址；公网址之则逐条相同。 ### 一致之例 - 五帧 SSE 经静态来源或公网术而读，文与累计字节和整体相合（同授权服务之例）。 - 公网术拒而返“阴”（不发请）：`https://127.0.0.1/x`、`https://0x7f.0.0.1/x`、`https://2130706433/x`、`https://0177.0.0.1/x`、`https://127.1/x`、`https://[::1]/x`、`https://localhost/x`、`https://LOCALHOST./x`、`https://a.localhost/x`、`https://db.internal/x`、`https://router.home.arpa/x`、`https://user:pw@api.provider.com/x`、`https://api.provider.com@evil.com/x`、`http://api.provider.com/x`、`https://api.provider.com/x?y=1`、`https://api.provider.com:22/x`、`https://provider/x`。 - 公网术受：`https://api.provider.com/v1/chat`、`https://API.Provider.COM:443/a/../v1`（规范为 `https://api.provider.com/v1`）、`https://api.provider.com:8443/x`、`https://xn--fsqu00a.xn--fiqs8s/x`。 - 请头 `X-Yuyan-Request-ID` 为大写十六进制、三十五位、含空格或径分隔符：告异常。 - 公网上游回三〇二：术成，状态号三〇二，`Location` 可读。 - 程序许可未声明通配来源：公网术告异常，且无请发出。 ### 界 宿主不保证上游得见其止或断，惟保证读者一方立得状态三、不复拉取上游。此包不予：于诸流择先至者之术；跨事而存答柄；名解析结果之验；HTTP/2 推送；自动重试；上游身份之头（公网术不许 `Authorization`）。宿主事之总限由宿主配之，此包惟保证依所给期限令读败。