网页上游之约 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）。宿主事之总限由宿主配之，此包惟保证依所给期限令读败。

豫言操作系统网页上游 0.2.0