消息队列公约 0.1.0

此包使客向获授之消息队列投 JSON 之书，并于队列之事读当前之批，逐条确认或延而重试。生产与消费同在一包。队列之事，客据[网页入站公约](../网页入站/规范.文言.md)之 读取入站事件种类 返 queue，而择己之消费入口；一批之书当一事、一新程序之例，程序之内存不越事而留，欲跨批之状，当存于久仓或关系库。

生产

发送队列消息 之参依次为队列绑定名、消息体 JSON 文与延迟之秒，投一书。绑定名由宿主许可（如 {"QUEUE":["PAGE_QUEUE"]}）核之：未授或当前部署未置之名，乃部署之误，宿主径止当前请；空名则此包抛豫言异。消息体可为任一 JSON 之值（对象、数组、字符串、数、布尔、null），此包使宿主先析而后规范：去冗白，一其转义，数循 IEEE 754 双精度取值（与 JS 同，绝对值逾 2^53−1 之整数失其精，当改以字符串）。入文与规范之后之文皆不逾一二八 KB，即一二八零零零 UTF-8 字节（平台以十进千字节计，本地 workerd 实测恰一二八零零零字节可投、一二八零零一字节则拒），嵌套不逾二十四层（数组或对象各计一层）；平台之文档言其限含元数据，近限之书若仍遭平台之拒，则以平台之败论。消息体中不得有非 JSON 之值或宿主专用之记（形如 {"$句柄":…}、{"$未定义":…}、{"$大整数":…}、{"$数字":…} 之对象，兼借 \u0024 之类转义所拼之键，及 1e999 之类化为无穷之数），否则抛异：此诸记于宿主桥乃表宿主之物，不许客借消息体而伪造。延迟之秒须在零至四万三千二百（十二时）之间，零谓不延，负或逾限则抛异。书以 JSON 内容之类入队，消费者所读即同一 JSON 之值。

批量发送队列消息 之参依次为队列绑定名与 JSON 数组文，每项为 {"body":任一 JSON 值,"delaySeconds":零至四万三千二百之整数}，delaySeconds 可省，项中不许他字段。数组一至百项，每 body 不逾一二八零零零字节，诸 body 合计不逾二五六零零零字节，数组文不逾一 MiB，嵌套之限同上。此包于豫言尽验全数组而后呼平台，一项不合则一书不投；平台拒整批时已否有部分入队，由平台定之，客欲幂等者自守之。

生产二术，皆以异告败，不返状态：违规、逾限、非 JSON、含宿主之记、延迟越界，皆于呼平台之前抛豫言异，异辞为定文（如 消息体不是有效的 JSON 文字、消息体超过 128000 字节、延迟秒数须在 0 至 43200 之间、批量消息不得超过 100 条）；平台拒之，则异辞为 队列发送失败： 或 队列批量发送失败： 加平台所报之原辞。客可以「尝试运行」捕之。

消费

消费三术惟当前事为队列时可用，于他事而呼之，则抛可捕之豫言异 当前事件不是队列事件；其效止于此一事之内。读取队列批次 返当前批之 JSON 文：{"queue":"队列名","messages":[{"id":"消息标识","attempts":投递之次,"timestamp":入队之刻（Unix 毫秒）,"body":JSON 值},…]}。messages 之序，即确认与重试所用之号序，号自零起；attempts 自一起，每重投加一；timestamp 为整数毫秒。body 必为 JSON 之值：若平台上之消息体非是（如生产者以结构化克隆发 Date、Map、Set、二进制、undefined、BigInt、NaN 或无穷），则 读取队列批次 抛异 队列消息正文不是 JSON 值：序号 n。嵌套逾宿主桥之限（三十二层）之消息体，使宿主止此一事。

确认队列消息 显确第 n 条（自零起），谓此书已处毕，此事之内不复重试之。重试队列消息 请重投第 n 条；次参为延迟之秒，零谓从平台之默认，否则须在一至四万三千二百之间。号小于零或不小于本批之数、延迟越界，皆抛可捕之豫言异（队列消息序号越界、延迟秒数须在 0 至 43200 之间）。同一条重复确认、重试或先确认后重试，其效以平台为准，客当避之。

事之果循平台之义：程序正常而毕，某条未显重试者，视为成，不必逐条确认；豫言之异无人捕，则宿主不吞其异，此次队列之处为败，平台按队列之重试与死信之配，整批重投（attempts 随加一）。已显确之书，是否随整批而重投，由平台定之：Cloudflare 之文档许其不重投，然本地 Miniflare 之模拟器实测，连已确者并整批重投；客不当倚任一方，消费之处必幂等。单事另有宿主所定之运行时限。此包不设整批确认或整批重试，欲之则于每条各呼一次。

一致之例

| 情境 | 必见 | | --- | --- | | 投 {"kind":"page","url":"/release/x","version":"v8","refresh":true}，延迟零 | 平台 send 收同一对象，选项恰为 {"contentType":"json"} | | 延迟三十、四万三千二百／负一、四万三千二百零一 | 前者选项含 delaySeconds；后者抛异而平台未被呼 | | 消息体 {"$句柄":"1"}、{"\u0024句柄":"1"}、1e999、{ | 皆抛异，平台未被呼 | | 消息体恰一二八零零零字节／多一字节 | 前者成，后者抛 消息体超过 128000 字节 | | 批量一项与百项／零项与百零一项 | 前者成；后者抛异，一书不投 | | 批量项含 contentType 字段、缺 body、delaySeconds 为一点五 | 皆抛异，一书不投 | | body 内有 ],[、{"body":1}、含引号与反斜线之字符串 | 每 body 逐字节还原，不被误拆 | | 平台拒之，辞为 Queue is full | 异辞为 队列发送失败：Queue is full | | 队列事中读含三书之批 | 序、id、attempts、毫秒 timestamp、body 皆与平台同；其时无一书被确认或重试 | | 依次确认零、延后三十秒重试一、二不处 | 平台收 ack、retry({delaySeconds:30})，第三条无所呼 | | 确认号等于书数或负一；重试延迟负一或四万三千二百零一 | 皆抛可捕之异，平台未收相应之呼 | | 队列事中程序抛未捕之异 | 宿主以败还平台（不吞其异），平台整批重投，attempts 加一 | | 常 HTTP 请中呼消费之术 | 抛可捕之异 当前事件不是队列事件 |

界

此包不设 ackAll、retryAll、队列之指标、队列与消费者之创设及配置（批之大小、重试之数、死信之队，属部署）、消息之去重、次序之保证或跨队列之事务；惟发与收 JSON 之值，不发文字或二进制之内容类，亦不读书之内容类。云工适配以生产映 Queue 绑定之 send 与 sendBatch，以消费映 queue 事之 MessageBatch；他平台可以等价之队列承之，惟 JSON 值之义、诸限及确认重试之义须同。