@h-ai/scheduler 0.1.0-alpha8 → 1.0.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +273 -0
- package/README.ja.md +273 -0
- package/README.md +106 -34
- package/dist/index.d.ts +559 -53
- package/dist/index.js +1385 -599
- package/dist/index.js.map +1 -1
- package/dist/scheduler-js-worker.d.ts +22 -0
- package/dist/scheduler-js-worker.js +20 -0
- package/dist/scheduler-js-worker.js.map +1 -0
- package/package.json +18 -13
package/README.md
CHANGED
|
@@ -1,21 +1,32 @@
|
|
|
1
1
|
# @h-ai/scheduler
|
|
2
2
|
|
|
3
|
+
[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
|
|
4
|
+
|
|
5
|
+
[框架首页](../../README.md) · 相关模块:[@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
|
|
6
|
+
|
|
7
|
+
## 简介
|
|
8
|
+
|
|
3
9
|
定时任务调度模块,支持统一任务模型、cron 调度、JS 函数字符串 / HTTP API 执行、任务持久化、执行日志查询,以及全局任务生命周期回调。
|
|
4
10
|
|
|
5
|
-
##
|
|
11
|
+
## 核心功能清单
|
|
12
|
+
|
|
13
|
+
- 按 cron 定时执行,也可从业务代码手动触发。
|
|
14
|
+
- 支持 HTTP、受信任的 JavaScript 和应用 Hook,提供重试与取消。
|
|
15
|
+
- 共享数据库持久化任务、执行状态与可续期租约,支持未知结果隔离。
|
|
16
|
+
|
|
17
|
+
## 使用入门
|
|
6
18
|
|
|
7
|
-
|
|
8
|
-
- `@h-ai/cache` — 分布式锁,可选;初始化后自动参与定时触发抢锁
|
|
19
|
+
### 依赖
|
|
9
20
|
|
|
10
|
-
|
|
21
|
+
- `@h-ai/reldb` — 必须先初始化共享数据库,保存任务、执行 journal 与自动续租;`enableDb` 只能为 true。
|
|
22
|
+
|
|
23
|
+
### 快速开始
|
|
11
24
|
|
|
12
25
|
```ts
|
|
13
|
-
import { cache } from '@h-ai/cache'
|
|
14
26
|
import { reldb } from '@h-ai/reldb'
|
|
15
27
|
import { scheduler } from '@h-ai/scheduler'
|
|
16
28
|
|
|
17
29
|
await reldb.init({ type: 'sqlite', database: './scheduler.db' })
|
|
18
|
-
await cache.init({ type: 'memory' }) // 可选
|
|
19
30
|
|
|
20
31
|
await scheduler.init({
|
|
21
32
|
enableDb: true,
|
|
@@ -34,7 +45,6 @@ await scheduler.register({
|
|
|
34
45
|
description: '每 5 分钟执行一次系统健康检查',
|
|
35
46
|
cron: '*/5 * * * *',
|
|
36
47
|
params: { channel: 'ops' },
|
|
37
|
-
retry: { maxAttempts: 3, backoffMs: [1000, 5000] },
|
|
38
48
|
handler: {
|
|
39
49
|
kind: 'api',
|
|
40
50
|
url: 'https://api.example.com/health',
|
|
@@ -69,7 +79,7 @@ scheduler.stop()
|
|
|
69
79
|
await scheduler.close()
|
|
70
80
|
```
|
|
71
81
|
|
|
72
|
-
|
|
82
|
+
### 统一任务模型
|
|
73
83
|
|
|
74
84
|
```ts
|
|
75
85
|
interface TaskDefinition {
|
|
@@ -77,8 +87,10 @@ interface TaskDefinition {
|
|
|
77
87
|
name: string
|
|
78
88
|
description?: string
|
|
79
89
|
cron: string
|
|
90
|
+
timezone?: string // IANA 时区,例如 Asia/Shanghai;省略时为 UTC,不读取节点 TZ
|
|
80
91
|
enabled?: boolean
|
|
81
92
|
deleteAfterRun?: boolean
|
|
93
|
+
idempotent?: boolean
|
|
82
94
|
retry?: {
|
|
83
95
|
maxAttempts: number
|
|
84
96
|
backoffMs?: number[]
|
|
@@ -93,6 +105,7 @@ interface ApiTaskConfig {
|
|
|
93
105
|
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
|
|
94
106
|
headers?: Record<string, string>
|
|
95
107
|
body?: unknown
|
|
108
|
+
maxResponseBytes?: number
|
|
96
109
|
timeout?: number
|
|
97
110
|
}
|
|
98
111
|
|
|
@@ -109,13 +122,15 @@ interface JsTaskConfig {
|
|
|
109
122
|
- JS 任务会在运行时编译,并基于源码做缓存,避免每次触发都重新编译
|
|
110
123
|
- `handler` 可为空;此时可通过全局 `hooks.onTaskExecute` 统一执行
|
|
111
124
|
|
|
112
|
-
|
|
125
|
+
> ⚠️ **安全警示**:`kind: 'js'` 仅适用于受信任的服务端代码。当前实现基于 Node.js `vm` 做便捷执行,**不是安全沙箱**;禁止直接接收用户、租户或后台任意输入的 JS 字符串。可配置任务优先使用 `kind: 'api'` 或 `hooks.onTaskExecute`。
|
|
126
|
+
|
|
127
|
+
### 任务生命周期回调
|
|
113
128
|
|
|
114
129
|
初始化时传入或运行时通过 `setHooks()` 设置:
|
|
115
130
|
|
|
116
131
|
```ts
|
|
117
132
|
await scheduler.init({
|
|
118
|
-
enableDb:
|
|
133
|
+
enableDb: true,
|
|
119
134
|
hooks: {
|
|
120
135
|
onTaskStart(event) {
|
|
121
136
|
void event
|
|
@@ -133,7 +148,7 @@ await scheduler.init({
|
|
|
133
148
|
})
|
|
134
149
|
```
|
|
135
150
|
|
|
136
|
-
|
|
151
|
+
### 执行日志
|
|
137
152
|
|
|
138
153
|
查询日志时可按触发来源过滤:
|
|
139
154
|
|
|
@@ -153,49 +168,106 @@ const logs = await scheduler.getLogs({
|
|
|
153
168
|
- `maxLogs`:最多保留 N 条日志
|
|
154
169
|
- `retentionDays`:最多保留最近 N 天日志
|
|
155
170
|
|
|
156
|
-
|
|
171
|
+
### API 概览
|
|
157
172
|
|
|
158
173
|
- `init(config?)`
|
|
159
174
|
- `register(task)`
|
|
160
175
|
- `unregister(taskId)`
|
|
161
176
|
- `updateTask(taskId, updates)`
|
|
177
|
+
- `refreshTasks()`
|
|
162
178
|
- `start()` / `stop()`
|
|
163
|
-
- `trigger(taskId, { source? })`
|
|
179
|
+
- `trigger(taskId, { source?, idempotencyKey? })`
|
|
164
180
|
- `getLogs(options?)`
|
|
181
|
+
- `execution.listLogFailures(options?)` / `execution.repairLog(occurrenceId)`
|
|
182
|
+
- `execution.get(occurrenceId)` / `execution.listUnknown(options?)` / `execution.resolveUnknown(occurrenceId, input)`
|
|
165
183
|
- `setHooks(hooks)` / `clearHooks()`
|
|
166
184
|
- `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
|
|
167
185
|
- `close()`
|
|
168
186
|
|
|
169
|
-
|
|
187
|
+
### 错误处理
|
|
170
188
|
|
|
171
189
|
所有公共 API(除 `close()`)返回 `HaiResult<T>`。
|
|
172
190
|
|
|
173
191
|
常用错误码:
|
|
174
192
|
|
|
175
|
-
| 错误码 | code | 说明
|
|
176
|
-
| ----------------------------------------- | ------------------- |
|
|
177
|
-
| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | 未初始化
|
|
178
|
-
| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | 初始化失败
|
|
179
|
-
| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | 配置错误
|
|
180
|
-
| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | 任务不存在
|
|
181
|
-
| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | 任务已存在
|
|
182
|
-
| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Cron 表达式无效
|
|
183
|
-
| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | 执行失败
|
|
184
|
-
| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS 执行失败
|
|
185
|
-
| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API 执行失败
|
|
186
|
-
| `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | DB 保存失败
|
|
187
|
-
| `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | 已在运行
|
|
188
|
-
| `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | 未在运行
|
|
189
|
-
| `HaiSchedulerError.
|
|
190
|
-
| `HaiSchedulerError.
|
|
191
|
-
| `HaiSchedulerError.
|
|
192
|
-
|
|
193
|
-
|
|
193
|
+
| 错误码 | code | 说明 |
|
|
194
|
+
| ----------------------------------------- | ------------------- | ---------------- |
|
|
195
|
+
| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | 未初始化 |
|
|
196
|
+
| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | 初始化失败 |
|
|
197
|
+
| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | 配置错误 |
|
|
198
|
+
| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | 任务不存在 |
|
|
199
|
+
| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | 任务已存在 |
|
|
200
|
+
| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Cron 表达式无效 |
|
|
201
|
+
| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | 执行失败 |
|
|
202
|
+
| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS 执行失败 |
|
|
203
|
+
| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API 执行失败 |
|
|
204
|
+
| `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | DB 保存失败 |
|
|
205
|
+
| `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | 已在运行 |
|
|
206
|
+
| `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | 未在运行 |
|
|
207
|
+
| `HaiSchedulerError.JS_COMPILE_FAILED` | `hai:scheduler:030` | JS 编译失败 |
|
|
208
|
+
| `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook 执行失败 |
|
|
209
|
+
| `HaiSchedulerError.LOG_PERSIST_FAILED` | `hai:scheduler:032` | 日志持久化未确认 |
|
|
210
|
+
|
|
211
|
+
### 运行行为与边界
|
|
212
|
+
|
|
213
|
+
所有节点必须先初始化同一共享 RelDB(跨主机生产使用 PostgreSQL/MySQL;SQLite 文件只适合可正确共享同一文件的本机进程)。数据库保存任务、执行 journal、全局任务占位和租约,`enableDb` 只能为 true;不再依赖缓存。`leaseMs` 默认 300000,范围 1000~86400000 毫秒,执行中自动续期。cron、手动和跨周期执行均争用同一任务槽,过期 owner 不能续活或提交。节点每个 `tickInterval` 刷新定义,`tasks` 只是最近成功快照;定义读取失败、删除、禁用、改期均中断旧尝试,已发生副作用不会回滚。
|
|
214
|
+
|
|
215
|
+
`context.occurrenceId` 是持久发生标识;同一 cron 分钟跨节点一致,手动可传 1~128 字符 `idempotencyKey` 重用原记录,省略时每次独立。`executionToken` 每次领取变化,`sequence` / `attempt` 提供执行代信息。API 会覆盖 `Idempotency-Key`、`X-Scheduler-Sequence`、`X-Scheduler-Attempt`、`X-Scheduler-Task`(任务 ID 使用 percent-encoding)。Hook 及生命周期回调已领取时的 `event.context` 使用同一发生标识;观测回调若产生副作用也须去重。
|
|
216
|
+
|
|
217
|
+
`idempotent` 默认为 false;只有接收端已将幂等账本和全部副作用原子持久提交,才声明 true。租约过期的已执行任务仅在 true 时以同 occurrenceId 接管;非幂等或耗尽本 occurrence 保存的 retry.maxAttempts(默认 1,范围 1–100,包含首次执行及恢复)时进入 `unknown` 并继续占住任务槽。租约无法强制撤销暂停进程已发出的外部操作,单有 HTTP 头不构成去重实现。重试同样受幂等声明约束。
|
|
218
|
+
|
|
219
|
+
`scheduler.execution.get(occurrenceId)` 查询权威状态;`listUnknown({ limit, offset })` 分页获取未知结果,limit 为 1~100,offset 为 0~1000000。可信人工先核实外部效果、确认旧 runner 已终止,再按 `expectedUpdatedAt` CAS 调用 `resolveUnknown(id, { status: 'success' | 'discarded', expectedUpdatedAt })` 释放占位;不能直接把 unknown 重排。`log.occurrenceId` 可作查询回执;`getLogs` 仅为尝试观测日志,日志保留策略不删除 journal/幂等历史。
|
|
220
|
+
|
|
221
|
+
日志的 `id` 是每次尝试固定的 UUID,`persistence.status` 与业务 `status` 独立:`persisted` 表示日志及确认回执已持久化;`pending` 表示业务终态已提交但日志待补写;`unconfirmed` 表示没有已确认的业务终态,不能据此补写成功。只有 owner 与有效租约条件提交的终态会发布完整尝试列表,随后才投影日志;失租节点不能投影成功。日志失败不会把业务成功改成失败,也不会因此重跑业务。
|
|
222
|
+
|
|
223
|
+
补写会缩小 pending 列表;批量补写应反复读取 offset=0,避免一边补写一边增加 offset 跳过记录。
|
|
224
|
+
|
|
225
|
+
可信服务端用 `execution.listLogFailures({ limit, offset })` 监控 pending(范围与 listUnknown 相同),用 `execution.repairLog(occurrenceId)` 从共享 journal 幂等补写;可跨节点、重启及并发调用。写入已提交但回执丢失时通过固定主键和完整内容核对去重。补写返回 `LOG_PERSIST_FAILED`(032)时继续保留 pending,并输出安全告警;全部数据库不可用且终态未提交时仍按 unknown 核对外部效果,不能假定存在可恢复结果。补写与日志保留均不调用业务 Hook。保留策略失败仅告警,不撤销已保存日志。`onTaskFinish` 是本地业务完成通知,其 unconfirmed 状态不是持久化确认;以 trigger 返回值及 execution.get 的 logPersistence 为准。
|
|
226
|
+
|
|
227
|
+
领取前竞争/跳过的 interrupted 仅为观测日志,没有可补写的终态;其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录,避免 MySQL 的 255 字符截断;支持的旧日志由模块版本迁移归档并复制;执行账本保持独立。关闭会等待在途补写,先关闭 scheduler 再关闭数据库。
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
const result = await scheduler.trigger('cleanup', { idempotencyKey: 'cleanup-2026-10-23' })
|
|
231
|
+
if (!result.success)
|
|
232
|
+
return result
|
|
233
|
+
if (result.data.persistence.status === 'pending' && result.data.occurrenceId) {
|
|
234
|
+
const repaired = await scheduler.execution.repairLog(result.data.occurrenceId)
|
|
235
|
+
if (!repaired.success)
|
|
236
|
+
return repaired
|
|
237
|
+
}
|
|
238
|
+
// 不用日志补写失败重新 trigger 业务;定期按页扫描 listLogFailures。
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`await scheduler.close()` 停止接收并取消 HTTP、JS Worker 与重试等待,再等待执行链退出后清理状态。重新初始化等待关闭完成。所有生命周期事件提供 `signal`;Hook 必须监听取消并停止自己的外部副作用(框架无法强制终止同一线程中的业务代码),不要在 Hook 中阻塞事件循环。取消后的旧执行不再重试、不自动删除任务,也不会调用新实例的 Hook。关闭期间保持数据库可用,待 scheduler 关闭后再关闭依赖。
|
|
242
|
+
|
|
243
|
+
JS 字符串在每次调用的独立 Worker 中执行,`timeout` 默认 30000 毫秒(含启动)。到期后终止并等待线程退出,再记录失败或重试;同步死循环也不会阻塞主事件循环。上下文及返回值必须支持结构化克隆。Worker 中的 `vm` 仍不是安全沙箱,代码必须来自受信任的服务端来源。
|
|
244
|
+
|
|
245
|
+
API 任务的 `timeout`(默认 30000 毫秒)覆盖请求和完整响应体读取。`ApiTaskConfig.maxResponseBytes` 指定响应体实际接收字节上限(正安全整数,默认 1048576 即 1 MiB);例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB,非法值在请求前失败;超时、超限或非成功 HTTP 状态在默认非幂等模式进入 unknown;仅声明幂等能力后才按有限重试策略处理。
|
|
246
|
+
|
|
247
|
+
`init()` 必须完整加载全部任务才返回成功。配置中的空 ID、重复 ID(含与持久化任务重复)、无效 cron,以及数据库读取或持久化任务解析失败,均返回失败并清空初始化状态;修正配置或数据后重新初始化。不要同时在 `tasks` 中重复声明已有的数据库任务。
|
|
248
|
+
|
|
249
|
+
调度循环按分钟匹配 cron,并从同一分钟生成持久 occurrenceId;延迟 tick 仍检查当前分钟,运行中每分钟只检查一次。
|
|
250
|
+
|
|
251
|
+
共享租约的首次领取、开始、续租、完成、过期扫描和隔离,均在同一条数据库 SQL 内计算或核验存储端时间。PostgreSQL 使用 clock_timestamp、MySQL 使用 SYSDATE(3)、SQLite 使用存储端 now;先查时间再写入不能替代最终 deadline 条件。cron 也读取 DB 时间选定分钟 occurrence 并匹配表达式,省略 timezone 时固定 UTC;显式 IANA 时区仅改变 cron 的墙上时间解释,节点 TZ 不改变身份或匹配。节点 Date.now 仅用于耗时诊断,不授权 owner;两个节点相差数小时也不会提前接管或延长过期凭据。行锁等待结束后仍须通过期限条件,失租结果不能投影成功日志。数据库服务自身的时间须由运维保持可信;未知外部副作用仍须核对,不能自动重放。
|
|
252
|
+
|
|
253
|
+
### 可选集成
|
|
254
|
+
|
|
255
|
+
调度任务触发 Reach 通知时,调度锁或任务完成不等于外部消息只投递一次。按 [Reach 队列语义](../reach/README.md) 使用持久 queueId;HTTP 接收端须原子持久去重,SMTP/短信等在途未知结果须人工核对,不能由调度重试直接重发。
|
|
256
|
+
|
|
257
|
+
## 旧库升级
|
|
258
|
+
|
|
259
|
+
任务定义的刷新、注册、更新和删除在同一进程内按接收顺序协调,包含写操作所需的刷新与提交。合法并发注册不会仅因快照交错而失败;真实数据库故障仍返回失败。close 先停止入口和 runner,取消只读等待和尚未开始写入的操作,再等待已开始的持久写入;迟到快照不发布,避免关闭后旧操作重新填充任务表。执行回调不占用这条队列;跨节点仍依靠共享数据库、版本与租约,不把进程内协调当分布式锁。
|
|
260
|
+
|
|
261
|
+
RelDB 初始化后调用 `migrateScheduler({ dryRun: true })` 查看变化,scheduler.init 在创建仓库前执行支持的版本迁移。旧任务保留,补 idempotent=false;旧日志表归档为 hai_scheduler_logs_alpha65,按稳定 legacy:<id> 幂等复制完整快照,超过一批和中断重试不重复历史,也不执行旧任务。SQLite/PostgreSQL 事务回滚;MySQL 按真实结构继续,需保持旧写入停止。升级前备份,回退恢复匹配数据库与代码,执行账本与旧历史不混为同一发生记录。
|
|
262
|
+
|
|
263
|
+
## 开发测试
|
|
194
264
|
|
|
195
265
|
```bash
|
|
196
266
|
pnpm --filter @h-ai/scheduler test
|
|
197
267
|
```
|
|
198
268
|
|
|
199
|
-
|
|
269
|
+
声明旁的 JSDoc 示例从真实公开入口导入,内部仓库、runner、编译器和 cron 工具则明确标注“模块内部上下文”,不代表可从包根导入。示例区分 HaiResult、显式取消异常和 close 的 Promise<void>,并检查业务 status 与日志 persistence;补写日志不会重做业务。维护时运行 `node scripts/check-module-jsdoc.mjs --package scheduler`,同时校验声明覆盖与真实类型;示例编译不代替共享数据库/独立进程验收。
|
|
270
|
+
|
|
271
|
+
## 许可证
|
|
200
272
|
|
|
201
273
|
Apache-2.0
|