豫豫言文档API ATLAS
入口豫言操作系统消息队列适配。包。豫
2 模块38 名称
全部模块

豫言 / 豫言操作系统消息队列适配 @ 0.1.0

用云工 QUEUE 生产者绑定和 queue 事件的消息批次实现消息队列接口。

说明.汉语.md

# 消息队列云工适配

生产者用云工 `QUEUE` 绑定的 `send` 与 `sendBatch`,消费者用 `queue` 事件的 `MessageBatch`(云工宿主已把批次和消息对象放进句柄表,`ack`、`retry({delaySeconds})` 逐条调用)。适配的要点:

- **消息体经宿主规范化**:豫言把消息体文字作为字符串交给宿主的 `JSON.parse`,取回 `JSON.stringify` 的规范文字,再直接放进 `send` 的参数文字;字符串字面量由宿主的 `TextDecoder` 生成,所以任意控制字符都不会出错,也不依赖豫言 JSON 库对转义的支持。规范文字里不许出现 `{"$句柄":`、`{"$未定义":`、`{"$大整数":`、`{"$数字":` 开头的对象:句柄桥会把它们还原成宿主对象或特殊值,允许的话应用可借消息体伪造宿主句柄。宿主规范文字里字符串内的引号都带反斜线,所以这一子串检查既不漏报也不误伤字符串内容。
- **批量数组由豫言拆分**:适配只在规范文字上做一遍带字符串与转义状态的括号扫描,拆出每项与其 `body` 文字,逐项验证形状与限额后重新拼成 `{"body":…,"contentType":"json","delaySeconds":…}`。`body` 始终是不透明的规范文字,不经豫言 JSON 库解析,所以 `\r`、`\uXXXX`、负数、指数等都不受当前 JSON 库限制。
- **消费侧读取**:批次名、消息数、标识、尝试数用云工宿主原有的队列原语;时间戳通过消息句柄读 `timestamp`,`Date` 用 `getTime()` 取毫秒(测试替身也可直接给毫秒整数);`body` 是宿主输出的规范 JSON,含句柄桥记号(`Date`、`Map`、二进制、`undefined`、BigInt、NaN 等)时抛出豫言异常。标识与队列名的字面量:纯可见 ASCII 直接加引号,其他字符经宿主的 `TextDecoder` 与 `JSON.stringify` 生成。
- **越界与延迟由适配先核对**:宿主对越界序号抛的是宿主 JS 错误,豫言捕获不到,所以先用消息数核对再调用,把越界变成可捕获的豫言异常;宿主原语的 `retry({delaySeconds})` 只在延迟大于 0 时使用。
- 适配不使用 `ackAll`、`retryAll`,也不接触消息的内容类型。生产投递固定 `contentType: "json"`。
- 真实本地 workerd(Wrangler 4.129.0)实测:`send`/`sendBatch` 以 `contentType: "json"` 投递,消费者读到 `attempts` 从 1 递增、`timestamp` 为 Date、`body` 为同一 JSON 值;`retry({delaySeconds})` 按延迟重投;单条消息体恰 128000 字节可投、128001 字节被拒(错误文字只是 `Unknown Internal Error (15000)`,所以适配自己按 128000 字节校验并给出中文原因);`sendBatch` 里每条同样以 128000 字节为限(两条各 128000 字节共 256000 字节的批量可投);不显式确认也不重试即视为成功;未捕获异常使**整批**重投,连已显式确认者一并重投(Miniflare 的 broker 在处理失败时不区分已确认消息),所以消费处理必须幂等。
- 单个事件的运行时限(30 秒)和 Wasm 实例不跨事件由云工宿主提供;宿主对 `queue` 事件返回的 Promise 在程序结束时完成,程序抛出未捕获异常则被拒绝,平台据此重试整批。

`一致性验证/` 里有试验应用、真实 Wasm 的 Node 测试(含批量拆分的随机结构对拍)和复跑说明。

说明.文言.md

# 消息队列云工适配

生产用云工 `QUEUE` 绑定之 `send` 与 `sendBatch`,消费用 `queue` 事之 `MessageBatch`(云工宿主已置批与书之物于句柄表,`ack`、`retry({delaySeconds})` 逐条而呼)。适配之要:

- **消息体由宿主规范**:豫言以消息体之文为字符串授宿主之 `JSON.parse`,取回 `JSON.stringify` 之规范文,径入 `send` 之参文;字符串之字面由宿主 `TextDecoder` 所成,故任何控制之字皆不误,亦不倚豫言 JSON 库于转义之能。规范文中不许有以 `{"$句柄":`、`{"$未定义":`、`{"$大整数":`、`{"$数字":` 起首之对象:句柄桥必以之还为宿主之物或特殊之值,若许之,则客可借消息体而伪造宿主之柄。宿主规范之文,字符串内之引号皆带反斜线,故此子串之验,既不漏,亦不伤字符串之内容。
- **批量之数组由豫言拆之**:适配惟于规范文上作一遍兼记字符串与转义之状之括号扫描,拆得每项及其 `body` 之文,逐项验其形与限,复拼为 `{"body":…,"contentType":"json","delaySeconds":…}`。`body` 恒为不透明之规范文,不经豫言 JSON 库之析,故 `\r`、`\uXXXX`、负数、指数等皆不受今 JSON 库之限。
- **消费之读**:批名、书数、标识、尝试数用云工宿主旧有之队列原语;时戳经书柄读 `timestamp`,`Date` 以 `getTime()` 取毫秒(试验之替身亦可径授毫秒整数);`body` 乃宿主所出之规范 JSON,含句柄桥之记(`Date`、`Map`、二进制、`undefined`、BigInt、NaN 之属)则抛豫言异。标识与队列名之字面:纯可见 ASCII 者径加引号,余者经宿主 `TextDecoder` 与 `JSON.stringify` 而成。
- **越界与延迟先由适配核之**:宿主于越界之号所抛乃宿主 JS 之误,豫言不可捕,故先以书数核之而后呼,使越界为可捕之豫言异;`retry({delaySeconds})` 惟延迟大于零时用之。
- 适配不用 `ackAll`、`retryAll`,亦不触书之内容类。生产之投,恒定 `contentType: "json"`。
- 真本地 workerd(Wrangler 4.129.0)实测:`send`、`sendBatch` 以 `contentType: "json"` 而投,消费者所读 `attempts` 自一而增,`timestamp` 为 Date,`body` 为同一 JSON 值;`retry({delaySeconds})` 依延迟而重投;单条消息体恰一二八零零零字节可投、一二八零零一字节则拒(其误辞惟 `Unknown Internal Error (15000)`,故适配自以一二八零零零字节校之而给中文之因);`sendBatch` 中每条亦以一二八零零零字节为限(二条各一二八零零零字节,合二五六零零零字节之批量可投);不显确亦不重试,即视为成;未捕之异使**整批**重投,连已显确者并重投(Miniflare 之 broker 于处败之时不别已确之书),故消费之处必幂等。
- 单事之运行时限(三十秒)与 Wasm 例不越事,皆云工宿主所供;宿主于 `queue` 事所返之 Promise 待程序毕而成,程序抛未捕之异则被拒,平台据此重试整批。

`一致性验证/` 有试应用、真 Wasm 之 Node 测试(含批量拆分之随机结构对拍)及复行之说明。