@h-ai/scheduler 1.0.0-beta.30 → 1.0.0-beta.32

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 CHANGED
@@ -4,318 +4,29 @@
4
4
 
5
5
  [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
6
6
 
7
- A scheduled task module with a unified task model, cron scheduling, JS function strings / HTTP API execution, persistence, execution log queries, and global task lifecycle hooks.
7
+ Use `scheduler` to run JavaScript handlers or call HTTP endpoints on a cron schedule. It saves task settings and execution logs in the database and can call application callbacks before and after runs.
8
8
 
9
9
  ## Quick Start
10
10
 
11
- ### Dependencies
11
+ Install with pnpm: `pnpm add @h-ai/scheduler @h-ai/reldb`.
12
12
 
13
- - `@h-ai/reldb`: initialize the shared database first; tasks, execution journals and leases are mandatory, and `enableDb` accepts only true.
13
+ [Open the quick-start guide](../../docs/usage/function/scheduler.en.md#quick-start).
14
14
 
15
- ```ts
16
- import { reldb } from '@h-ai/reldb'
17
- import { scheduler } from '@h-ai/scheduler'
15
+ ## Configuration Reference
18
16
 
19
- await reldb.init({ type: 'sqlite', database: './scheduler.db' })
17
+ Generated projects define how often to check for work and how long a worker owns a task in `config/_scheduler.yml`. At startup, the application reads the file and passes the settings object to `scheduler.init(config)`.
20
18
 
21
- await scheduler.init({
22
- enableDb: true,
23
- maxLogs: 1000,
24
- retentionDays: 30,
25
- hooks: {
26
- onTaskStart(event) {
27
- void event
28
- },
29
- },
30
- })
31
-
32
- await scheduler.register({
33
- id: 'health-check',
34
- name: '健康检查',
35
- description: '每 5 分钟执行一次系统健康检查',
36
- cron: '*/5 * * * *',
37
- params: { channel: 'ops' },
38
- handler: {
39
- kind: 'api',
40
- url: 'https://api.example.com/health',
41
- method: 'GET',
42
- timeout: 10000,
43
- },
44
- })
45
-
46
- await scheduler.register({
47
- id: 'cleanup',
48
- name: '清理过期数据',
49
- description: '每日凌晨执行过期数据清理',
50
- cron: '0 2 * * *',
51
- deleteAfterRun: true,
52
- params: { source: 'nightly' },
53
- handler: {
54
- kind: 'js',
55
- code: '(context) => ({ taskId: context.taskId, params: context.params })',
56
- },
57
- })
58
-
59
- scheduler.start()
60
-
61
- const manualResult = await scheduler.trigger('cleanup', { source: 'admin-console' })
62
- const logs = await scheduler.getLogs({
63
- triggerType: 'manual',
64
- triggerSource: 'admin-console',
65
- startedAfter: Date.now() - 24 * 60 * 60 * 1000,
66
- })
67
-
68
- scheduler.stop()
69
- await scheduler.close()
70
- ```
19
+ See the [configuration reference](../../docs/usage/configuration/scheduler.en.md) for configuration entry points, defaults, accepted values and when changes take effect.
71
20
 
72
21
  ## Features
73
22
 
74
- - Run tasks on a cron schedule or trigger them from application code.
75
- - Execute HTTP requests, trusted JavaScript and application hooks, with retry and cancellation.
76
- - Persist tasks, execution journals and renewable leases in a shared database, with unknown-outcome isolation.
77
-
78
- ### Operations and results
79
-
80
- Use the complete initialization flow in this section first. The host validates and authorizes example business values; check success before reading data from asynchronous domain results. Here void means completion without data, null means absent; synchronous factories/tools return the listed type directly.
81
-
82
- #### scheduler
83
-
84
- Definitions take task, ID, ID+patch or no-arg refresh and yield void HaiResult. tasks is the last successful read-only snapshot, not authorization or live DB state.
85
-
86
- | Entry | Input parameters | Successful result | Call example |
87
- | ------------------------ | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
88
- | `scheduler.register` | task | `void` | `await scheduler.register({ id: 'daily', name: 'Daily', cron: '0 2 * * *', timezone: 'UTC' })` |
89
- | `scheduler.unregister` | taskId | `void` | `await scheduler.unregister('daily')` |
90
- | `scheduler.updateTask` | taskId, updates | `void` | `await scheduler.updateTask('daily', { enabled: false })` |
91
- | `scheduler.refreshTasks` | No arguments | `void` | `await scheduler.refreshTasks()` |
92
-
93
- #### scheduler
94
-
95
- start/stop return synchronous HaiResult; trigger takes task ID/params and yields an attempt log; getLogs filters/page yield a log page. Stop does not undo in-flight effects.
96
-
97
- | Entry | Input parameters | Successful result | Call example |
98
- | ------------------- | ---------------- | ----------------------------------- | ---------------------------------------------------- |
99
- | `scheduler.start` | No arguments | `void` | `scheduler.start()` |
100
- | `scheduler.stop` | No arguments | `void` | `scheduler.stop()` |
101
- | `scheduler.trigger` | taskId, options | `TaskExecutionLog` | `await scheduler.trigger('daily')` |
102
- | `scheduler.getLogs` | options | `PaginatedResult<TaskExecutionLog>` | `await scheduler.getLogs({ page: 1, pageSize: 20 })` |
103
-
104
- #### scheduler
105
-
106
- Install/clear business/event callbacks, returning synchronous HaiResult. Hooks must honor signal and external-effect idempotency.
107
-
108
- | Entry | Input parameters | Successful result | Call example |
109
- | ---------------------- | ---------------- | ----------------- | ------------------------------- |
110
- | `scheduler.setHooks` | hooks | `void` | `scheduler.setHooks(taskHooks)` |
111
- | `scheduler.clearHooks` | No arguments | `void` | `scheduler.clearHooks()` |
112
-
113
- #### scheduler.execution
114
-
115
- Authoritative journal: get occurrenceId yields entry/null, lists take limit/offset and yield arrays, repairLog ID idempotently repairs logs, resolveUnknown ID/decision/expectedUpdatedAt conditionally releases the slot and yields void.
116
-
117
- | Entry | Input parameters | Successful result | Call example |
118
- | ------------------------------------- | ------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------- |
119
- | `scheduler.execution.get` | occurrenceId | `SchedulerExecutionEntry \| null` | `await scheduler.execution.get(occurrenceId)` |
120
- | `scheduler.execution.listUnknown` | options | `SchedulerExecutionEntry[]` | `await scheduler.execution.listUnknown({ limit: 20, offset: 0 })` |
121
- | `scheduler.execution.listLogFailures` | options | `SchedulerExecutionEntry[]` | `await scheduler.execution.listLogFailures({ limit: 20, offset: 0 })` |
122
- | `scheduler.execution.repairLog` | occurrenceId | `void` | `await scheduler.execution.repairLog(occurrenceId)` |
123
- | `scheduler.execution.resolveUnknown` | occurrenceId, resolution | `void` | `await scheduler.execution.resolveUnknown(occurrenceId, { status: 'success', expectedUpdatedAt })` |
124
-
125
- ### Unified task model
126
-
127
- ```ts
128
- interface TaskDefinition {
129
- id: string
130
- name: string
131
- description?: string
132
- cron: string
133
- timezone?: string // IANA 时区,例如 Asia/Shanghai;省略时为 UTC,不读取节点 TZ
134
- enabled?: boolean
135
- deleteAfterRun?: boolean
136
- idempotent?: boolean
137
- retry?: {
138
- maxAttempts: number
139
- backoffMs?: number[]
140
- }
141
- params?: Record<string, unknown>
142
- handler?: ApiTaskConfig | JsTaskConfig
143
- }
144
-
145
- interface ApiTaskConfig {
146
- kind: 'api'
147
- url: string
148
- method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
149
- headers?: Record<string, string>
150
- body?: unknown
151
- maxResponseBytes?: number
152
- timeout?: number
153
- }
154
-
155
- interface JsTaskConfig {
156
- kind: 'js'
157
- code: string // JS 函数字符串
158
- timeout?: number
159
- }
160
- ```
161
-
162
- Notes:
163
-
164
- - All tasks can be persisted, including `kind: 'js'` tasks.
165
- - JS tasks are compiled at runtime and cached by source to avoid recompilation on every trigger.
166
- - `handler` can be omitted; use global `hooks.onTaskExecute` for execution in that case.
167
-
168
- > ⚠️ **Security warning**: `kind: 'js'` is only for trusted server-side code. Node.js `vm` provides convenient execution and **is not a security sandbox**. Never accept arbitrary JS strings from users, tenants, or admin inputs. Prefer `kind: 'api'` or `hooks.onTaskExecute` for configurable tasks.
169
-
170
- ### Task lifecycle hooks
171
-
172
- Provide hooks at initialization or set them at runtime with `setHooks()`:
173
-
174
- ```ts
175
- await scheduler.init({
176
- enableDb: true,
177
- hooks: {
178
- onTaskStart(event) {
179
- void event
180
- },
181
- async onTaskExecute(event) {
182
- return { via: 'hook', source: event.context.trigger.source }
183
- },
184
- onTaskInterrupted(event) {
185
- void event
186
- },
187
- onTaskFinish(event) {
188
- void event
189
- },
190
- },
191
- })
192
- ```
193
-
194
- ### Execution logs
195
-
196
- Filter logs by trigger source:
197
-
198
- ```ts
199
- const logs = await scheduler.getLogs({
200
- taskId: 'cleanup',
201
- triggerType: 'manual',
202
- triggerSource: 'admin-console',
203
- startedAfter: Date.now() - 24 * 60 * 60 * 1000,
204
- startedBefore: Date.now(),
205
- pagination: { page: 1, pageSize: 20 },
206
- })
207
- ```
208
-
209
- Execution logs support automatic cleanup policies configured at initialization:
210
-
211
- - `maxLogs`: retain at most N logs.
212
- - `retentionDays`: retain at most the last N days.
213
-
214
- ### API overview
215
-
216
- - `init(config?)`
217
- - `register(task)`
218
- - `unregister(taskId)`
219
- - `updateTask(taskId, updates)`
220
- - `refreshTasks()`
221
- - `start()` / `stop()`
222
- - `trigger(taskId, { source?, idempotencyKey? })`
223
- - `getLogs(options?)`
224
- - `execution.listLogFailures(options?)` / `execution.repairLog(occurrenceId)`
225
- - `execution.get(occurrenceId)` / `execution.listUnknown(options?)` / `execution.resolveUnknown(occurrenceId, input)`
226
- - `setHooks(hooks)` / `clearHooks()`
227
- - `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
228
- - `close()`
229
-
230
- ### Runtime behavior and limits
231
-
232
- All nodes must initialize the same shared RelDB first (PostgreSQL/MySQL for production across hosts; SQLite only for local processes that correctly share the same file). Task definitions, execution journals, active task slots and leases are persisted; `enableDb` accepts only true. Cache is no longer required. `leaseMs` defaults to 300000 and accepts 1000–86400000 milliseconds, with renewal during execution. Cron, manual and later periods share one active task slot; an expired owner cannot revive or commit. Nodes refresh definitions every `tickInterval`; `tasks` is the last successful snapshot. Failed reads, deletion, disabling or rescheduling interrupt stale attempts, without rolling back external effects.
233
-
234
- `context.occurrenceId` persists across retries and nodes for a cron minute. Manual triggers accept a 1–128 character `idempotencyKey` to reuse the same record, otherwise each is independent. `executionToken` changes per claim; `sequence` and `attempt` identify the execution generation. API jobs override `Idempotency-Key`, `X-Scheduler-Sequence`, `X-Scheduler-Attempt` and `X-Scheduler-Task` (percent-encoded task ID). Claimed lifecycle callbacks expose the same ID in `event.context`; any callback side effects also need deduplication.
235
-
236
- On PostgreSQL, restarting within the same minute or claiming from multiple nodes can encounter an existing execution record or an occupied task slot. The scheduler handles these conflicts as normal contention. Use `scheduler.execution.get(occurrenceId)` to check the execution status and keep the journal and its unique constraints to prevent duplicate executions.
237
-
238
- `idempotent` defaults to false. Set true only when the receiver atomically persists its deduplication ledger with every side effect. Expired running executions can be recovered with the same occurrenceId only under this declaration; non-idempotent jobs or executions that exhaust the stored retry.maxAttempts budget (default 1, range 1–100 including initial attempts and recovery) become `unknown` and retain the active task slot. A lease cannot revoke an external request already sent by a paused process; headers alone do not implement deduplication. Retries also follow this declaration.
239
-
240
- Use `scheduler.execution.get(occurrenceId)` for authoritative state and `listUnknown({ limit, offset })` with limit 1–100 and offset 0–1000000. Trusted operators must confirm external effects and terminate the old runner before releasing its slot through `resolveUnknown(id, { status: 'success' | 'discarded', expectedUpdatedAt })`, which uses CAS. Never requeue unknown executions directly. `log.occurrenceId` is the receipt; `getLogs` contains observational attempt logs. Log retention does not delete the journal or idempotency history.
241
-
242
- Each attempt has a stable UUID log `id`. `persistence.status` is independent of business `status`: `persisted` confirms both log storage and its receipt, `pending` means a committed business outcome still needs log projection, and `unconfirmed` means no committed outcome can be assumed. Only an owner with a valid lease can publish the terminal outcome and all attempt logs before projection. A stale owner cannot project success. Log failure never turns business success into failure or reruns the task.
243
-
244
- Repair shrinks the pending list. Drain batches repeatedly at offset=0 instead of advancing the offset while repairing.
245
-
246
- Trusted server operators monitor `execution.listLogFailures({ limit, offset })` with the same bounds as listUnknown and call `execution.repairLog(occurrenceId)` to replay logs from the shared journal across nodes, restarts, or concurrent calls. Stable primary keys and complete payload comparison handle committed writes with lost acknowledgements. `LOG_PERSIST_FAILED` (032) retains pending state and emits a safe warning. If the entire database is unavailable before the terminal commit, reconcile unknown effects; do not assume a recoverable outcome exists. Repair and retention never call business hooks. Retention failure only warns. `onTaskFinish` reports local business completion with unconfirmed persistence; use the trigger result and execution.get.logPersistence for confirmation.
247
-
248
- Pre-claim interrupted events are observational logs without a committed outcome to repair; unacknowledged writes remain unconfirmed. JSON payloads preserve full results and all retries beyond MySQL's 255-character text mapping; execution ledgers remain separate. Closing waits for in-flight repairs; close scheduler before the database.
249
-
250
- ```ts
251
- const result = await scheduler.trigger('cleanup', { idempotencyKey: 'cleanup-2026-10-23' })
252
- if (!result.success)
253
- return result
254
- if (result.data.persistence.status === 'pending' && result.data.occurrenceId) {
255
- const repaired = await scheduler.execution.repairLog(result.data.occurrenceId)
256
- if (!repaired.success)
257
- return repaired
258
- }
259
- // 不用日志补写失败重新 trigger 业务;定期按页扫描 listLogFailures。
260
- ```
261
-
262
- `await scheduler.close()` stops intake, cancels HTTP, JS workers, and retry waits, then awaits execution chain exit before clearing state. Reinitialization waits for closure. All lifecycle events expose `signal`; hooks must observe cancellation and stop external side effects. The framework cannot terminate business code on the same thread; do not block the event loop in hooks. Cancelled old executions no longer retry, delete tasks, or call new-instance hooks. Keep the database available until scheduler closure completes, then close dependencies.
263
-
264
- Each JS string runs in its own worker; `timeout` defaults to 30000 ms including startup. On timeout, terminate the thread and await exit before logging failure or retrying. Synchronous infinite loops cannot block the main event loop. Context and results must support structured cloning. A worker's `vm` is still not a security sandbox; code must come from trusted server-side sources.
265
-
266
- API task `timeout` (default 30000 ms) covers the request and full response body read. `ApiTaskConfig.maxResponseBytes` limits received body bytes (positive safe integer; default 1048576, or 1 MiB). `maxResponseBytes: 10 * 1024 * 1024` allows 10 MiB. Invalid values fail before the request. Timeouts, size limits, and non-success HTTP statuses become unknown by default; bounded retry applies only when idempotency is declared.
267
-
268
- `init()` succeeds only after loading all tasks. Empty or duplicate IDs (including persisted duplicates), invalid cron, database read failures, and persisted-task parse failures return failure and clear initialization state. Correct configuration or data before retrying. Do not redeclare existing database tasks in `tasks`.
269
-
270
- Cron is matched by minute; the same minute determines a persistent occurrenceId. Delayed ticks still check the current minute once per running scheduler.
271
-
272
- Claim, begin, renewal, completion, expiration scans and isolation calculate/check lease deadlines inside the database statement using its clock: PostgreSQL clock_timestamp, MySQL SYSDATE(3), or SQLite now. Reading a time first cannot replace the final atomic deadline condition. Cron uses DB time for both the minute occurrence and expression matching. An omitted timezone means UTC; an explicit IANA timezone changes only wall-time interpretation, while node TZ does not change matching or identity. Node Date.now is diagnostic only; opposing node clocks cannot take over early or revive expired ownership. A write waiting on a row lock must still pass its deadline before publishing success. Keep the database service clock trustworthy; unknown external effects still require reconciliation rather than automatic replay.
273
-
274
- ### Optional integrations
275
-
276
- When a scheduled task sends Reach notifications, a scheduler lock or task completion does not guarantee one external delivery. Follow [Reach queue semantics](../reach/README.en.md) with persistent queueId keys. HTTP receivers must atomically persist deduplication with their side effects. Review unknown in-flight SMTP/SMS outcomes manually; scheduler retries must not blindly send them again.
277
-
278
- ### Definition consistency and persistence setup
279
-
280
- Definition refresh, registration, update and deletion are coordinated in arrival order within each process, including a mutation's refresh and commit. Valid concurrent registrations no longer fail merely because snapshots interleave; actual database failures still return errors. close stops entry points and the runner, cancels read waits and operations that have not started writing, then drains active persistent writes. Late snapshots cannot publish or repopulate state afterward. Business callbacks do not hold this queue. Nodes still rely on the shared database, versions and leases; local coordination is not a distributed lock.
281
-
282
- Initialize RelDB before calling `scheduler.init()` to create and validate the task, execution and log tables. Incompatible tables cause initialization to fail. Manage execution records and observation logs according to their distinct purposes.
283
-
284
- ## Configuration
285
-
286
- Lifecycle: init takes backend/business configuration; use the module only after success. Await close before releasing borrowed dependencies. Follow the quick-start example and public signatures for exact return values.
287
-
288
- The host loads and validates configuration before passing it to this module. Keep secrets in private server environment files. Select the backend, capacity, deadlines and logging for the actual use case; reinitialize and check the result after changes.
289
-
290
- [Per-option purpose, use cases and examples](../../docs/usage/configuration/operations.md).
291
-
292
- ## Error Handling
293
-
294
- Check result.success for domain operations. Handle failures with the module error definitions and safe messages; retain codes, correlation IDs and sanitized causes in server logs. Synchronous tools, factories, stream iteration and lifecycle calls follow their own signatures. A completed Promise alone is not business success. See each feature for recovery limits.
295
-
296
- All public APIs except `close()` return `HaiResult<T>`.
23
+ [Browse the API list](../../docs/usage/function/scheduler.en.md#api-reference) for entry points, inputs, results and examples.
297
24
 
298
- Common error codes:
25
+ ## Data Structures
299
26
 
300
- | Error code | code | Description |
301
- | ----------------------------------------- | ------------------- | ----------------------------- |
302
- | `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | Not initialized |
303
- | `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | Initialization failed |
304
- | `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | Invalid configuration |
305
- | `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | Task not found |
306
- | `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | Task already exists |
307
- | `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Invalid cron expression |
308
- | `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | Execution failed |
309
- | `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS execution failed |
310
- | `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API execution failed |
311
- | `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | Database save failed |
312
- | `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | Already running |
313
- | `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | Not running |
314
- | `HaiSchedulerError.JS_COMPILE_FAILED` | `hai:scheduler:030` | JS compilation failed |
315
- | `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook execution failed |
316
- | `HaiSchedulerError.LOG_PERSIST_FAILED` | `hai:scheduler:032` | Log persistence not confirmed |
27
+ See the [data reference](../../docs/usage/data/scheduler.en.md) for tasks, execution logs, distributed leases and recovery state.
317
28
 
318
- ## Development
29
+ ## Development and Testing
319
30
 
320
31
  ```bash
321
32
  pnpm --filter @h-ai/scheduler test