持久告警接口规范 0.1.0

本包让应用管理当前持久对象（Durable Object）的告警（alarm）：读取已设置的告警时刻、设置或替换它、删除它，并在告警事件里读取平台已重试的次数。告警是持久对象在指定时刻由平台再次唤醒的机制：到点时宿主以 durable-alarm 事件进入应用的 _start（应用据[网页入站接口](../网页入站/规范.汉语.md)的 读取入站事件种类 辨别），此时没有 HTTP 请求，应用须自己从[持久事务](../持久事务/规范.汉语.md)的持久仓恢复所需状态。告警适合“稍后继续”的后台工作：长任务的分段续跑、定期清理、失败重试。

语义

单个持久对象至多一个告警。设置持久告警 把它设为绝对 Unix 毫秒时刻（自 1970-01-01T00:00:00Z 起的整数毫秒，取值 0 至 8640000000000000），已有告警被替换；时刻已经过去则平台尽快触发。读取持久告警 返回（是否已设置，时刻）：未设置返回（阴，零）。删除持久告警 去掉告警，本来没有时无事发生。

告警事件开始时，该告警视为已清除：处理入口里 读取持久告警 返回（阴，零），入口可以再次 设置持久告警 安排下一次（周期任务就是这样写成的）。处理入口失败（抛出未捕获异常、超过事件时限、被平台终止）时，平台自动退避重试：失败之后、重试开始之前，告警视为已设置（读取持久告警 返回阳与重试时刻）；重试事件里 读取告警重试次数 返回已重试的次数（首次为零，第一次重试为一，依此类推），重试事件开始时告警同样视为已清除。重试的次数上限与退避时间以平台为准（平台文档现行：最多 6 次，指数退避，起始约 2 秒；本地 workerd 已见重试次数 0、1、2 递增，上限待云端验证），用尽后平台放弃该告警。按平台文档，告警至少触发一次（云端待验证），因而处理入口须幂等。非告警事件里 读取告警重试次数 恒为零。

告警函数只在持久对象事件中可用（事件种类以 durable- 开头，含[持久事务](../持久事务/规范.汉语.md)的事务入口与[持久独占](../持久独占/规范.汉语.md)的独占区入口）。在事务入口里设置或删除告警，与该事务同命运：事务提交则生效，回滚或失败则撤销（本地 workerd 已验，云端待验）。清空持久仓 在 SQLite 存储上按兼容日期可能连告警一并清除，需要告警的应用应在清仓之后重新设置。告警事件的墙钟时限默认与其他事件相同（30 秒），宿主可通过构建产物的 执行配置.json 为 durable-alarm 放宽至最多 15 分钟；时限属宿主配置，不属于本接口。

函数

读取持久告警：无参，返回（爻，整数）。设置持久告警：参数为绝对毫秒整数，返回有。删除持久告警：无参，返回有。读取告警重试次数：无参，返回整数。

失败情形

时刻小于 0 或大于 8640000000000000 属违规：抛可捕获的豫言异常，消息 持久告警时刻须在 0 至 8640000000000000 之间。在非持久对象事件里调用前三个函数属违规：抛可捕获的豫言异常，消息 当前事件不属于持久对象。存储后端故障属平台故障，宿主中止当前事件，豫言无法捕获。读取告警重试次数 不失败。

跨宿主一致性

任何实现须保持：单对象单告警、设置即替换、绝对毫秒；告警事件开始时告警视为已清除；失败后重试且重试次数递增、失败等待重试期间告警视为已设置；非告警事件重试数为零；事务内告警变更与事务同命运；上述限额与失败类别。

一致性样例

新对象上 读取持久告警 得（阴，零）；设置持久告警 1900000000000 后得（阳，1900000000000）；再 设置持久告警 1900000005000 后得（阳，1900000005000）；删除持久告警 后得（阴，零）。设置持久告警 -1 与 设置持久告警 8640000000000001 抛异常。告警事件里：首次触发 读取告警重试次数 为 0 且 读取持久告警 为（阴，零）；处理入口故意抛错后，读取持久告警 在下一次进入前为（阳，重试时刻），重试事件里重试次数为 1。事务入口里 设置持久告警 T 后调用 回滚持久事务，事务之后 读取持久告警 仍为（阴，零）。

边界

本包不提供多个告警、周期告警或按名称的定时器；周期任务由处理入口重设告警实现。不保证准点（平台在时刻之后触发，可能延迟），也不保证恰好一次。告警只属于持久对象，Worker 的 scheduled 定时事件另有能力。