网页事件流公约 0.1.0

此包使客以事件流（text/event-stream）答当前入站之请：先即提响应头，程序续行，乃逐块书文；书受背压，能察客之断，亦能正终与异终。其用如持久对象向浏览器或本地软件推事、长事回报进度、向服务商长联下任务。SSE 之帧（id:、event:、data:、retry:、冒号起首之注行、空行为尾）客自拼之；此包惟以 UTF-8 书客所予之文，不析、不校、不补其帧。HEAD 与非 GET 之请，客先辨之，此包不代客定路与法。接口包惟依标准库。

流柄

开始入站事件流回应 返不透明之字符串（流柄），余四术以之为首参。流柄惟创之之事可用：他事之柄、伪造之串、未尝创之柄，皆使调用败（豫言之异），不误及同事之他流。一事至多一开事件流之答，再开则败。事毕则柄失；流之终局见“生命周期”。

术

开始入站事件流回应 受状态码与附加标头之列，即提响应头，返流柄，程序续行。状态须在二百至二百九十九，而非二零四、二零五（二者不可带体）。内容种类恒为 text/event-stream; charset=utf-8，客不得覆之；Cache-Control: no-store 为默认，客可以同名之头覆之。附加标头为（名，值）之列，至多三十二项，逐项严校：名为一至六十四字节之 RFC 9110 令牌（字母、数字与 !#$%&'*+-.^_|~）；值惟许可见 ASCII、空格与制表（0x09、0x20 至 0x7E），至多八千一百九十二字节，故无 CR、LF、NUL 与高位字节；名不分大小写而重则败；下列名客不得附：Content-Length、Transfer-Encoding、Connection、Keep-Alive、Upgrade、TE、Trailer、Content-Type、Content-Encoding，及 Set-Cookie、Set-Cookie2`（凭据之答用常答之术）。犯其一即抛豫言之异，时响应未提，客仍可以他术答之。惟 HTTP 事可调（他事抛豫言之异）；当事若已由他术（网页答复等）提终响应而复开事件流，乃客之违，云工宿主报误而止此运行，未必可以「尝试运行」捕之；反之，事件流既开，此事已有终响应，复调网页答复之诸答术，亦为违。

写入入站事件流文字 以 UTF-8 即书其文，每次至多六万五千五百三十六字节，逾则抛豫言之异（先于状态之辨）；一帧逾六十四 KiB 者，客自分数次书之，字节之序不变。返整数：0 已书；1 客已断；2 流已由客终或止。空文不书，惟刷新而返今状。书受背压：缓冲满则阻豫言，直至有隙或客断；缓冲之量由宿主与传输定，公约不承诺块数，亦不承诺书之次数与网络块一一相应，惟承诺字节之序。客断之后，应用犹可续行（如毕计费之结算、清订阅），此后之书惟返一，不复阻。

入站事件流已断开 返已否察见客断，不阻；一旦为阳，恒为阳（此后终或止亦不易）。所察之源：宿主报请已为客所止，或响应体读端已取消、已败。客已正终或止、而先未察见断者，返阴。

结束入站事件流 正终事件流（客读得流之正终），幂等：已终、已止、已断者不报误。中止入站事件流 异终事件流，用于上游败：宿主使响应体流以误终；因（至多一千零二十四字节，逾则抛异）惟供宿主诊断，不告客；幂等。二者之后，书皆返二。

误之类：状态、标头、大小、流柄、事类等违规者抛豫言之异；书时客已断、流已终，乃可复之业务情形，以返值一、二表之，不抛异。

生命周期与宿主相关之实

程序毕前必终或止。 响应头既提而程序返者，流不自终（除宿主于事毕收尾，见下），客将久候。断之察，依宿主与传输：云工适配以请求之 AbortSignal（须开兼容标志 enable_request_signal，见适配说明）与响应体流之误共断之；HTTP/1.1 上空闲之联，其断必待服务端再书而后见，故欲久持之流当按期书心跳（SSE 注行 : ping）。存活之久，以宿主为准：云工每事之豫言实例有墙钟之限（默认三十秒，应用目录之 执行配置.json 可依事类改至多十五分钟），限至则下一调宿主即败、事终；今宿主于此不止未终之响应流（客见流止而联仍开），此宿主待改之项，改前客当于限前自终其流，令客凭 Last-Event-ID 重联（如云端项目之 /events 二十秒而闭）。异终于客之所见，依传输：本地 workerd 之 HTTP/1.1 分块答，客所读者为正终，宿主志记一未捕之异；欲使客可靠辨败者，当先书明示误之事件帧，而后止或终。此诸云端之行，除注明本地 workerd 已验者，皆“待云端验证”。

诸宿主一致之要

同一组调用于诸宿主，返码与异类必同；宿主可异者惟缓冲之量、块之界与断之察时。宿主一旦报断，其后之书必返一而不得阻；终与止必幂等；非法标头、逾限之书、无效流柄，对开始须于提响应头之前、对余术须不改流状而败。书与终不得因慢读者而阻他事。

一致性样例

一、开始（二百，空列）→ 书 data: 1 加空行返零 → 终 → 书 x 返二 → 已断开返阴；客依次读响应头（内容种类固定）、一帧、正终。 二、开始 → 客断 → 书返一，客犹记结算 → 已断开返阳 → 终 → 书返二、已断开仍阳。 三、开始（二百，Content-Type 或 Set-Cookie 或含换行之值）→ 抛豫言之异，响应未提。 四、开始 → 书二帧 → 止 → 客于二帧之后不见正终（所见之形依传输）→ 书返二，再止与再终皆不报误。 五、书六万五千五百三十六字节返零，书六万五千五百三十七字节抛异；多字节字按字节计。 六、他事所得之柄，书之抛豫言之异，无害此事自有之流。

界

不析不造 SSE 帧，不行重联与 Last-Event-ID 之义（客以网页入站读其头而自回放），不作心跳、压缩、二进制流、WebSocket 或多路；不易已提之响应头；不保块界；不于客外自终其流；不授网络之能（授权仍归宿主资源许可）。响应体惟载 UTF-8 之文。