fix(plugin-email): sys_email 的 queued 行在启动时被清扫,drain 失败升为 error (#5161)

[os-zhuang]

Fixes #5161

基于 #5173 合并后的 main(9c4f1743c)工作。

问题

sys_email 的 status: 'queued' 只有一个消费时机:insert 当时的 afterInsert drain 钩子(以及 #5160 之后 send() 自己发出的 email.send.async 作业)。此后没有任何东西再看这一行。进程在 insert 之后、投递完成之前死掉,或者 drain 的投递抛错,这一行就永远停在 queued —— 一个以队列命名、却没有读者的状态,而调用方早就被告知"消息已接受"。

实现

1. 启动清扫 sweepStrandedOutbox(新文件 outbox-sweep.ts)

挂在 kernel:ready,位置在 email.send.async 订阅者注册与 #5160 的 boot 门之后 —— 注册表定型、订阅者已就位,重新入队的行才有地方落。按当前模式分流:

• 队列模式:通过 EmailService.enqueuePersistedRow 发布 { rowId }。这是刻意复用 send() 自己的生产者:同一个 EMAIL_SEND_QUEUE 常量、同一份 publish options、同一个 sys_email: + 行 id 的 idempotencyKey。第二个生产者用自己的方式拼载荷,正是队列两半漂移的起点;而共享的幂等键让"还挂着 pending 作业的行"被清扫时收敛到那个作业上,而不是把第二个 worker 推到同一行上。
• 内联模式(以及 publish 失败时的回退):deliverPersistedRow 就地把行推进到 sent/failed —— 进程没死的话 drain 钩子本来就会做这件事。publish 失败回退内联,与 send() 自身的判断一致:行已经提交了,把它继续留给"没人"才是本 issue 要修的 bug。

2. 捞取判据:只捞"够老"的行(5 分钟)

这是 PR 里最需要说清楚的一条。合格条件是 status='queued' 且 created_at 早于 now - 5min,而不是"早于本次 boot"。理由:

• 几秒前插入的行不是滞留,而是某个人正在处理的在途工作 —— 可能是本进程 send() 的 insert 与 transport.send 之间,可能是本进程 setTimeout(0) 延后的 drain 钩子,也可能是多实例部署下另一个实例的同样两者。清扫它就等于把别人手里的活抢过来发第二遍。
• "本次 boot 时间"在多实例下没有意义:兄弟实例一秒前插入的行比我的 boot 还新,但它显然不是我的。年龄是唯一在每个实例上含义相同的属性。
• 5 分钟这个值:内联重试循环自己的退避上限是 2s,所以一次活着的投递要么早已定稿要么早已抛错;同时短到崩溃后重启仍能在同一个维护窗口里把信发出去。

年龄门之下还有两道兜底(不是许可):本进程 send() 正在持有的行(isServiceManaged)不碰;已经带 message_id 或已不是 queued 的行跳过 —— 与 email.send.async 订阅者投递前的幂等守卫同一套语义。

诚实交代边界:内联模式没有跨进程协调,本来也从来没有(drain 钩子同样如此),年龄门就是那里的全部保护。多实例的持久投递正是队列模式存在的理由,在那里幂等键使重复发布成为 no-op。

3. 边界与可见性

• 每次 boot 最多 500 行,按 created_at 升序;多读一行判断是否截断,所以"还有更多"是事实而不是"整页=可能还有"的推断,截断时日志明说下次 boot 继续。
• 结果打一行 info(捞了几行、requeued / sent / failed / skipped 各几);failed > 0 时另有一行 error,带后果与修复。
• boot 不 await 清扫:一堆滞留邮件不该把服务器挡在端口外(内联模式下每一行都是一次网络往返)。清扫自 catch 并 error,不依赖钩子传播语义 —— LiteKernel 上 kernel:ready handler 抛错会被吞(core: kernel:ready 钩子抛错在 ObjectKernel 上失败 boot、在 LiteKernel 上被吞成一条 error 日志 —— 同一钩子两套失败语义 #5170),对一个耐久性清扫来说那等于把它存在的意义本身丢掉。需要确定性的调用方(测试)等 EmailServicePlugin.outboxSweepSettled。
• 未加周期性清扫(issue 建议 2):队列模式下新写入的行已由 plugin-email: 邮件投递接入持久化队列 —— send 走 email.send.async / sys_job_queue(重试+DLQ),可配置开关 #5160 覆盖,为覆盖率再造一套调度不划算;内联模式下 drain 失败的行等到下次重启被捞 —— 这一点在 error 文案里就直说了。

4. drain 钩子失败升 error

两处 catch 从 warn 升到 error,并按 AGENTS.md 的 degradation-log-level 标准带上后果(这封信没有发出、行停在 queued、本进程不会再重试)与修复(下次重启的清扫会捞;要让失败被重试和进 DLQ 就打开 Settings → Mail → "Durable queue delivery")。同时把 deliverPersistedRow 加进 DURABILITY_CRITICAL_CALLEES,以后再有 catch 把它悄悄降级会被 pnpm check:durability-log-level 挡住(该 gate 现为 14 个 seam,全绿)。

验收对照

• 人为构造"insert 后进程死亡"的行:测试直接把行写进表(不触发钩子),重启后队列模式发出 { rowId } 作业并由真实 DbQueueAdapter 的一次 poll 推到 sent,内联模式直接推到 sent;不可发送的行推到 failed 而不是继续滞留。
• drain 失败的日志级别与文案有用例钉住:断言 error 通道里有这行、warn 通道里没有,并逐条钉后果/修复/成因文本。
• 默认路径不变:正常 send() 仍内联投递、app 写入的行仍由 afterInsert 钩子恰好投递一次,清扫在这两种情况下 scanned: 0。

测试

pnpm --filter @objectstack/plugin-email test    # 13 files / 195 tests passed
pnpm --filter @objectstack/plugin-email typecheck   # clean
node scripts/check-durability-degradation-log-level.mjs   # 14 seams, all loud
node scripts/check-startup-registry-verdict.mjs           # 40 seams, none recording a verdict
npx eslint packages/plugins/plugin-email/src --max-warnings=0   # clean

新增用例:outbox-sweep.test.ts(14 例,含年龄门、路由、兜底、边界与失败路径)、email-plugin.outbox-sweep.test.ts(10 例,真实 DbQueueAdapter 端到端 + drain 日志级别 + 默认路径)。

影响面

只动 packages/plugins/plugin-email/src/{email-plugin,email-service,index}.ts 与新增文件,外加 scripts/check-durability-degradation-log-level.mjs 的一条词表。未碰 headers/attachments 相关的任何东西(留给 #5177)、未碰 packages/spec、未碰 content/docs/releases/。用户可见,已带 changeset。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_017MCKJaEomEqg4tvz4SzdNd

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 8:35am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-email.

4 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via @objectstack/plugin-email)
• content/docs/deployment/environment-variables.mdx (via @objectstack/plugin-email)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-email)
• content/docs/protocol/kernel/index.mdx (via @objectstack/plugin-email)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.