命名持久服务之约 0.3.0

请求命名持久服务文字 受获授绑定名、对象名、内部绝对址、法、查询键值列、请头列与正文。宿主先循当前程序 DO 许可核绑定，乃以 getByName 定其内对象；不得因对象名越至异绑定或外网。对象名非空，至多一百二十八字，惟 ASCII 字母、数字、下划线、连字符、斜线（斜线自〇点三始许，见文末“〇点三之变”）。内部址惟许 https://asset/ 或 https://internal/，其径拒反斜线、控字、?、#，毋自带查询片段。法限 GET、HEAD、POST。查询至多十六项，由宿主编码；请头惟许精确 Origin、Content-Type、Cookie，至多八项且毋重名，值惟可见 ASCII 字（自空格至 ~），首尾不得为空格，至多八一九二字节；GET/HEAD 正文必空，POST 正文不逾八 MiB（〇点一为二 MiB）。正文以字节发之，不经 JSON 转义，凡字皆原样而达。

宿主返有效 JSON 物文：status 为上游整数号，body 为全 UTF-8 文（宽解，非法序为 U+FFFD，去字节序记，同 Response.text()），headers 惟载上游现有之 content-type、location、set-cookie、x-yuyan-revision 四小写名及值。正文不逾八 MiB（〇点一为二 MiB），逾则告豫言异常；先观 Content-Length，无所称则流式累计。HTTP 错号仍属得答。对象抛错或请败则告豫言异常（〇点一此情使宿主崩，不可捕）。不得露异头、句柄或异程序之对象。今 _start 以 JSON 文传果，后可易豫言记录与字节流。

〇点二新增：流答、渐读与转入站请

〇点二惟增八术，请求命名持久服务文字 之型与义不变（限额之增与败之可捕见上）。所增者，为“读云端项目对象之 SSE、NDJSON 长答”与“以入站请原样转于对象而回传其事件流”而设。

流请

请求命名持久服务流(绑定名, 对象名, 网址, 方法, 查询, 标头, 正文, 超时毫秒) 返「（成否，答柄或误文）」。绑定名、对象名、网址、法、查询、头、正文之验，与 请求命名持久服务文字 全同（违则告豫言异常，不及对象），另加超时毫秒一至九〇〇〇〇〇（越界告豫言异常），期限以 AbortSignal.timeout 贯“发请、候答头、读答文”之全程。不随改向。请败（对象抛错、传输败）或答头未至而期满，返“阴”与误文，误文以 持久服务请求失败或超时： 或 持久服务请求超时 始；成则返“阳”与答柄。正文以字节发之。

答柄与渐读

答柄为不透明之文，惟创之之事有效，不可存、不可序、不可伪；请求命名持久服务文字 内部亦用此机，然不返柄。非本包所发之文皆告豫言异常。同柄之读当有序，异柄可错综。

• 读取命名持久服务响应标头(柄, 名)：返答头之值，名不分大小写，须为一至一二八字节之合法头令牌，无则空文。此术可读 x-yuyan-revision 以外之任一答头，以对象乃客自己之码也。
• 读取命名持久服务响应状态(柄)：返 HTTP 状态号。
• 读取命名持久服务响应文字块(柄, 最大字节)：返「（状态，文）」，最大字节一至六五五三六。状态零得一块：宿主流式解 UTF-8，跨块而裂之多字节字必正相衔，非法序为 U+FFFD，去字节序记，文绝无半字，其 UTF-8 字节数不逾最大字节（不足四者以四计），溢出者留待后调（上游连送六十四空块以上之极端，可返文空之状态零，客照常续读）；状态一读尽（文空；无正文之答首读即得；流末残缺之序先以一 U+FFFD 为状态零之块返之）；状态二读败（文为“名称: 消息”）；状态三期满、已止，或有限整读因逾限已止（文为简说）。一、二、三为终态，再调返同果。
• 读取命名持久服务响应有限文字(柄, 字节上限)：一次读毕余文，字节上限一至八三八八六〇八。状态零成；状态一逾上限（先观 Content-Length，所称已逾则一字不读；无所称或不实则流式累计，逾则止，恰等于上限不为逾）；状态二败；状态三期满或已止。
• 取消命名持久服务响应(柄)：止读而对对象答流行 cancel，此后之读返状态三；幂等。对象能否即回调其流之 cancel，视平台而定，不作保证。

以流答为终答

回应入站以命名持久服务原答(柄) 以 请求命名持久服务流 所得之答（状态、头、正文流，含 SSE）原样为当前入站请之终答。所以处“先向对象发内请，验状态而行他事，乃以对象之事件流回传于客”者。柄须由 请求命名持久服务流 所发；已始渐读（或已定局）之柄告豫言异常；一入站请惟一终答；既交则此柄不可复读，读则返状态三与 已作终答。

转入站请

转发入站请求至命名持久服务(绑定名, 对象名, 网址, 查询, 保留标头名, 固定标头) 以当前入站请转于对象，并以对象之答为当前入站请之终答。须有当前入站请；无则宿主报。

• 法：取入站之法，限 GET、HEAD、POST，否则告豫言异常。正文：POST 则以入站请之正文流原样接于对象（不析、不缓冲，对象可于请未发尽时始读），GET/HEAD 不带正文；入站正文若已读或已锁，告豫言异常。
• 址与对象：对象名、内部址（https://asset/ 或 https://internal/ 起，径则同上）、查询（至多十六项，由宿主编码）之则同 请求命名持久服务文字。
• 保留头名：至多十六项，逐名不分大小写，惟许 Accept、Authorization、Content-Type、Cookie、CF-Connecting-IP、Idempotency-Key、If-None-Match、Last-Event-ID、Origin、Range，及以 X-Yuyan- 起者；不得重出；入站无者略之。宿主惟以此诸头之值原样交于对象，余入站头（如 Host、Content-Length、Transfer-Encoding、X-Forwarded-*）一概不转，且其值不经豫言程序之字符串。
• 定头：至多八项，名惟许 Accept、Content-Type、Origin，及以 X-Yuyan- 起者，值至多八一九二字节之可见 ASCII，不得与保留名或彼此重出，以定值书之。
• 答：对象之 Response（状态、头、正文流，含 SSE）原样为终答，宿主不缓冲、不改写；一入站请惟一终答。不随改向。对象抛错或请败告豫言异常，不设答。

败之分类

| 情形 | 类 | | --- | --- | | 对象名、址、法、查询、头、正文、时限、块限、字节上限诸参违规；柄无效；转发时入站正文已读；已渐读而作原答；对象抛错（文字术与转发） | 告豫言异常，不发请或不设答 | | 绑定未授或无此绑定 | 部署之误，宿主报之 | | 流请败，或答头未至而期满 | 返“阴”与因 | | 读时对象出错、期满、已止、逾限 | 读术之状态二、三、一 | | HTTP 四百、五百号 | 得答之成，由客按状态号处之 |

限额

对象名一二八字；查询十六项；请头八项、值八一九二字节；请与答之正文八 MiB；流时限九〇〇〇〇〇毫秒；块六五五三六字节；有限整读八 MiB；转发保留名十六项、定头八项。

异宿主之一致

异宿主必守：对象惟由授权绑定内按名而定；先验而后发请；流式解 UTF-8 而相衔；期满则读返状态三并对对象答流行 cancel；止则对对象答流行 cancel；转发不缓冲请与答之正文，答逐块随对象所产而至；惟转白名之头；不随改向。

一致之例

• 对象返三事件之 SSE，以十一字节切块渐读，文拼之与原文同。
• 查询 a=1 2、b=中文&=：对象所收为 ?a=1+2&b=%E4%B8%AD%E6%96%87%26%3D；Origin、Content-Type、Cookie 原样而达；POST 正文（含引号、反斜线、换行、制表、表情）逐字节同。
• 对象久不出块，时限三〇〇毫秒：得已至之块，次得状态三，宿主对对象答流行 cancel（因 TimeoutError；能回调 cancel 之宿主可察之）；对象久不回答头：得“阴”与因。
• 文字术：答八三八八六〇八字节成，八三八八六〇九字节告异常；请正文八三八八六〇八字节可发，多一字节告异常；对象答头 x-secret 不现于果。
• 先请后作原答：向对象 GET /events，读得状态二〇七后 回应入站以命名持久服务原答，客所收之状态、头同，正文逐事而至；若先读一块而后作原答，告异常。
• 转发：对象每八十毫秒发一事，共四事，入站方逐事而收（首末到时相差不小于一百五十毫秒）；状态二〇七与 x-yuyan-revision 存之；入站 POST 请体先发首块，对象读得首块后入站方乃发次块，仍得成（缓冲全请体则死锁）；惟转所列之头，Host、X-Cfg 之类不转；保留名含 Host 告异常。

〇点三之变：对象名许斜线

〇点三不增术、不改型。对象名之字集，由“ASCII 字母、数字、下划线、连字符”宽为兼许斜线 /，长仍一至一二八字。所以然者：云工作台之项目对象，自旧制即以“户号/项目号”为名（久物之识由名而出，易名则失旧籍），接口须能依原名而定之。斜线可居名中任何位；宿主惟以名授 getByName，不以为径、址或文件名；余字（空格、点、冒号、反斜线、非 ASCII 等）仍一概拒之，告“持久服务对象名无效”。文字术、流术、转发术三者同守此则。

一致之例（〇点三所增）：对象名 7/3f2a9c1e-4b5d-4e6f-8a7b-9c0d1e2f3a4b（户号斜线项目号）可用，宿主以原名 getByName；a b、a.b、a\b、中文、空串、一二九字之名仍告可捕之豫言异常。

界

宿主不保证对象得见其止，惟保证读者一方立得状态三、不复拉取对象。此包不予：于诸流择先至者之术；对象间之呼与广播；对象之创与唯一之识（惟按名而定）；WebSocket；跨事而存答柄；自动重试。宿主事之总限由宿主配之，此包惟保证依所给期限令读败。