修订 chrome.alarms 相关代码

类型:重构 / 行为修正
影响范围:Service Worker 定时任务(周期性 alarm 的创建、触发与补偿)

close #840

背景与目标

• 解决与 chrome.alarms 使用相关的若干不一致与边界状况,确保周期任务能够稳定创建、按时触发、异常可补偿。
• 合并后将关闭问题 (留一个坑)修一下 chrome.alarms 问题 #840 。

主要改动

1. 周期性 Alarm 的幂等创建

   • 新增/完善 mightCreatePeriodicAlarm:

     • 不存在同名 alarm → 创建;已存在且周期一致 → 复用;已存在但周期不同 → 重建。
     • 读取 get() 产生的 runtime.lastError 不阻断创建流程;create() 的 lastError 仅记录但不抛错(保持 resolve)。

2. 触发回调与补偿机制

   • 新增/完善回调注册与监听:setPeriodicAlarmCallback、monitorPeriodicAlarm。

   • 触发参数包含:

     • alarm:原始 alarm 对象;
     • triggeredAt:实际执行时间戳;
     • isFlushed:是否补偿执行(当 scheduledTime 与当前时间相差 ≥ ~65 秒视为补偿)。

   • 在回调前后通过 chrome.storage.local 维护 AlarmPending:<name> 记录,以支持 SW 重启后的补偿扫描:

     • 若两次扫描间 pending 未变化 → 视为上次未完成,进行补偿并在完成后清理;
     • 若 pending 已变化 → 认为已处理/正在处理,不重复补偿。

   • 同一进程内 monitorPeriodicAlarm() 只能启动一次,重复调用将抛错。

   • 当触发阶段出现 runtime.lastError(框架层错误)时,本次事件将被忽略:既不调用回调,也不写入/清理 pending。

3. 单元测试(Vitest)

   • 为上述关键路径补齐系统性测试,包括:

     • 创建/复用/重建分支;
     • lastError 分支(get() 与 create());
     • 准时触发与补偿触发(≥65s);
     • 回调抛错时的 pending 清理;
     • SW 重启后的补偿扫描逻辑;
     • 只能启动一次的监控约束;
     • 触发阶段 runtime.lastError 的忽略策略。

测试说明

• 通过 Vitest + fake timers 固定系统时间、推进异步定时器,模拟实际浏览器调度与补偿场景;
• 通过可控的 chrome Mock(alarms / storage.local / runtime.lastError)精准注入与断言副作用。

兼容性与风险评估

• 行为兼容:对周期一致的已存在 alarm 走复用路径,避免不必要重建;
• 稳健性:lastError 的读取与处理更保守,降低偶发 API 异常带来的连锁失败;
• 幂等与自愈:pending 记录与补偿扫描在 SW 重启场景下可自愈遗漏任务;
• 约束:monitorPeriodicAlarm() 设计为单例监控,若有特殊架构(多入口重复初始化)需留意只初始化一次。

关联问题

• 关闭 (留一个坑)修一下 chrome.alarms 问题 #840 。

变更文件(节选)

• src/app/service/service_worker/alarm.ts(核心逻辑)
• src/app/service/service_worker/alarm.test.ts(单测,376+ 行)
• 以及与 SW 相关的 index.ts、script.ts、subscribe.ts、synchronize.ts 与入口 src/service_worker.ts。

统计

• +576 / −104,涉及 7 个 TypeScript 文件。