@h-ai/scheduler 1.0.0-beta.3 → 1.0.0-beta.31

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.md CHANGED
@@ -4,261 +4,27 @@
4
4
 
5
5
  [框架首页](../../README.md) · 相关模块:[@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
6
6
 
7
- ## 简介
7
+ 用 `scheduler` 按 cron 表达式运行任务。任务可执行 JavaScript 处理函数或调用 HTTP 接口。模块把任务设置和执行日志写入数据库,也可在执行前后调用应用提供的函数。
8
8
 
9
- 定时任务调度模块,支持统一任务模型、cron 调度、JS 函数字符串 / HTTP API 执行、任务持久化、执行日志查询,以及全局任务生命周期回调。
9
+ ## 快速开始
10
10
 
11
- ## 核心功能清单
11
+ 使用 pnpm 安装:`pnpm add @h-ai/scheduler @h-ai/reldb`。
12
12
 
13
- - 按 cron 定时执行,也可从业务代码手动触发。
14
- - 支持 HTTP、受信任的 JavaScript 和应用 Hook,提供重试与取消。
15
- - 共享数据库持久化任务、执行状态与可续期租约,支持未知结果隔离。
13
+ [跟着最小示例完成接入](../../docs/usage/function/scheduler.md#quick-start)。
16
14
 
17
- ## 使用入门
15
+ ## 配置清单
18
16
 
19
- ### 依赖
17
+ 生成的项目在 `config/_scheduler.yml` 中设置任务检查间隔和执行租约时长。应用启动代码读取该文件,把配置对象传给 `scheduler.init(config)`。
20
18
 
21
- - `@h-ai/reldb` — 必须先初始化共享数据库,保存任务、执行 journal 与自动续租;`enableDb` 只能为 true。
19
+ 在[模块配置清单](../../docs/usage/configuration/scheduler.md)中查阅配置入口、默认值、取值限制和生效条件。
22
20
 
23
- ### 快速开始
21
+ ## 功能说明
24
22
 
25
- ```ts
26
- import { reldb } from '@h-ai/reldb'
27
- import { scheduler } from '@h-ai/scheduler'
23
+ [查 API 清单](../../docs/usage/function/scheduler.md#api-reference),包含调用入口、输入、返回值和用法。
28
24
 
29
- await reldb.init({ type: 'sqlite', database: './scheduler.db' })
25
+ ## 数据结构
30
26
 
31
- await scheduler.init({
32
- enableDb: true,
33
- maxLogs: 1000,
34
- retentionDays: 30,
35
- hooks: {
36
- onTaskStart(event) {
37
- void event
38
- },
39
- },
40
- })
41
-
42
- await scheduler.register({
43
- id: 'health-check',
44
- name: '健康检查',
45
- description: '每 5 分钟执行一次系统健康检查',
46
- cron: '*/5 * * * *',
47
- params: { channel: 'ops' },
48
- handler: {
49
- kind: 'api',
50
- url: 'https://api.example.com/health',
51
- method: 'GET',
52
- timeout: 10000,
53
- },
54
- })
55
-
56
- await scheduler.register({
57
- id: 'cleanup',
58
- name: '清理过期数据',
59
- description: '每日凌晨执行过期数据清理',
60
- cron: '0 2 * * *',
61
- deleteAfterRun: true,
62
- params: { source: 'nightly' },
63
- handler: {
64
- kind: 'js',
65
- code: '(context) => ({ taskId: context.taskId, params: context.params })',
66
- },
67
- })
68
-
69
- scheduler.start()
70
-
71
- const manualResult = await scheduler.trigger('cleanup', { source: 'admin-console' })
72
- const logs = await scheduler.getLogs({
73
- triggerType: 'manual',
74
- triggerSource: 'admin-console',
75
- startedAfter: Date.now() - 24 * 60 * 60 * 1000,
76
- })
77
-
78
- scheduler.stop()
79
- await scheduler.close()
80
- ```
81
-
82
- ### 统一任务模型
83
-
84
- ```ts
85
- interface TaskDefinition {
86
- id: string
87
- name: string
88
- description?: string
89
- cron: string
90
- timezone?: string // IANA 时区,例如 Asia/Shanghai;省略时为 UTC,不读取节点 TZ
91
- enabled?: boolean
92
- deleteAfterRun?: boolean
93
- idempotent?: boolean
94
- retry?: {
95
- maxAttempts: number
96
- backoffMs?: number[]
97
- }
98
- params?: Record<string, unknown>
99
- handler?: ApiTaskConfig | JsTaskConfig
100
- }
101
-
102
- interface ApiTaskConfig {
103
- kind: 'api'
104
- url: string
105
- method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
106
- headers?: Record<string, string>
107
- body?: unknown
108
- maxResponseBytes?: number
109
- timeout?: number
110
- }
111
-
112
- interface JsTaskConfig {
113
- kind: 'js'
114
- code: string // JS 函数字符串
115
- timeout?: number
116
- }
117
- ```
118
-
119
- 说明:
120
-
121
- - 所有任务都可持久化到数据库,包括 `kind: 'js'` 的任务
122
- - JS 任务会在运行时编译,并基于源码做缓存,避免每次触发都重新编译
123
- - `handler` 可为空;此时可通过全局 `hooks.onTaskExecute` 统一执行
124
-
125
- > ⚠️ **安全警示**:`kind: 'js'` 仅适用于受信任的服务端代码。当前实现基于 Node.js `vm` 做便捷执行,**不是安全沙箱**;禁止直接接收用户、租户或后台任意输入的 JS 字符串。可配置任务优先使用 `kind: 'api'` 或 `hooks.onTaskExecute`。
126
-
127
- ### 任务生命周期回调
128
-
129
- 初始化时传入或运行时通过 `setHooks()` 设置:
130
-
131
- ```ts
132
- await scheduler.init({
133
- enableDb: true,
134
- hooks: {
135
- onTaskStart(event) {
136
- void event
137
- },
138
- async onTaskExecute(event) {
139
- return { via: 'hook', source: event.context.trigger.source }
140
- },
141
- onTaskInterrupted(event) {
142
- void event
143
- },
144
- onTaskFinish(event) {
145
- void event
146
- },
147
- },
148
- })
149
- ```
150
-
151
- ### 执行日志
152
-
153
- 查询日志时可按触发来源过滤:
154
-
155
- ```ts
156
- const logs = await scheduler.getLogs({
157
- taskId: 'cleanup',
158
- triggerType: 'manual',
159
- triggerSource: 'admin-console',
160
- startedAfter: Date.now() - 24 * 60 * 60 * 1000,
161
- startedBefore: Date.now(),
162
- pagination: { page: 1, pageSize: 20 },
163
- })
164
- ```
165
-
166
- 执行日志支持自动清理策略(初始化时配置):
167
-
168
- - `maxLogs`:最多保留 N 条日志
169
- - `retentionDays`:最多保留最近 N 天日志
170
-
171
- ### API 概览
172
-
173
- - `init(config?)`
174
- - `register(task)`
175
- - `unregister(taskId)`
176
- - `updateTask(taskId, updates)`
177
- - `refreshTasks()`
178
- - `start()` / `stop()`
179
- - `trigger(taskId, { source?, idempotencyKey? })`
180
- - `getLogs(options?)`
181
- - `execution.listLogFailures(options?)` / `execution.repairLog(occurrenceId)`
182
- - `execution.get(occurrenceId)` / `execution.listUnknown(options?)` / `execution.resolveUnknown(occurrenceId, input)`
183
- - `setHooks(hooks)` / `clearHooks()`
184
- - `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
185
- - `close()`
186
-
187
- ### 错误处理
188
-
189
- 所有公共 API(除 `close()`)返回 `HaiResult<T>`。
190
-
191
- 常用错误码:
192
-
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 按真实结构继续,需保持旧写入停止。升级前备份,回退恢复匹配数据库与代码,执行账本与旧历史不混为同一发生记录。
27
+ 查看[数据结构](../../docs/usage/data/scheduler.md),了解任务、执行日志、分布式租约和恢复状态。
262
28
 
263
29
  ## 开发测试
264
30
 
package/dist/index.d.ts CHANGED
@@ -1,7 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import * as _h_ai_core from '@h-ai/core';
3
3
  import { PaginationOptionsInput, HaiResult, PaginatedResult } from '@h-ai/core';
4
- import * as _h_ai_reldb from '@h-ai/reldb';
5
4
 
6
5
  /**
7
6
  * @h-ai/scheduler — 配置 Schema
@@ -855,16 +854,5 @@ interface SchedulerFunctions {
855
854
  */
856
855
  declare const scheduler: SchedulerFunctions;
857
856
 
858
- /**
859
- * 预检或升级调度器表;旧日志归档并幂等复制,新版执行账本与旧历史隔离。
860
- * @example
861
- * ```ts
862
- * import { migrateScheduler } from '@h-ai/scheduler'
863
- * const plan = await migrateScheduler({ dryRun: true })
864
- * ```
865
- */
866
- declare function migrateScheduler(options?: {
867
- dryRun?: boolean;
868
- }): Promise<_h_ai_core.HaiResult<_h_ai_reldb.SchemaMigrationPlan>>;
869
-
870
- export { type ApiTaskConfig, ExecutionResolutionSchema, type ExecutionStatus, HaiSchedulerError, type JsTaskConfig, type JsTaskHandler, type LogQueryOptions, type SchedulerConfig, type SchedulerConfigInput, SchedulerConfigSchema, type SchedulerExecutionEntry, type SchedulerExecutionOperations, type SchedulerExecutionState, type SchedulerFunctions, type SchedulerInitInput, type SchedulerLogCleanupPolicy, type SchedulerTaskContext, type SchedulerTaskExecuteEvent, type SchedulerTaskFinishEvent, type SchedulerTaskHooks, type SchedulerTaskInterruptedEvent, type SchedulerTaskStartEvent, type TaskDefinition, type TaskExecutionLog, type TaskExecutionTargetType, type TaskHandlerConfig, type TaskHandlerKind, type TaskLogPersistence, type TaskParams, type TaskRetryPolicy, type TaskTriggerInfo, type TaskTriggerType, type TaskUpdateInput, type TriggerTaskInput, TriggerTaskSchema, migrateScheduler, scheduler };
857
+ export { ExecutionResolutionSchema, HaiSchedulerError, SchedulerConfigSchema, TriggerTaskSchema, scheduler };
858
+ export type { ApiTaskConfig, ExecutionStatus, JsTaskConfig, JsTaskHandler, LogQueryOptions, SchedulerConfig, SchedulerConfigInput, SchedulerExecutionEntry, SchedulerExecutionOperations, SchedulerExecutionState, SchedulerFunctions, SchedulerInitInput, SchedulerLogCleanupPolicy, SchedulerTaskContext, SchedulerTaskExecuteEvent, SchedulerTaskFinishEvent, SchedulerTaskHooks, SchedulerTaskInterruptedEvent, SchedulerTaskStartEvent, TaskDefinition, TaskExecutionLog, TaskExecutionTargetType, TaskHandlerConfig, TaskHandlerKind, TaskLogPersistence, TaskParams, TaskRetryPolicy, TaskTriggerInfo, TaskTriggerType, TaskUpdateInput, TriggerTaskInput };