@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.en.md
ADDED
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
# @h-ai/scheduler
|
|
2
|
+
|
|
3
|
+
[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
|
|
4
|
+
|
|
5
|
+
[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
|
|
6
|
+
|
|
7
|
+
## Introduction
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
## Core features
|
|
12
|
+
|
|
13
|
+
- Run tasks on a cron schedule or trigger them from application code.
|
|
14
|
+
- Execute HTTP requests, trusted JavaScript and application hooks, with retry and cancellation.
|
|
15
|
+
- Persist tasks, execution journals and renewable leases in a shared database, with unknown-outcome isolation.
|
|
16
|
+
|
|
17
|
+
## Getting started
|
|
18
|
+
|
|
19
|
+
### Dependencies
|
|
20
|
+
|
|
21
|
+
- `@h-ai/reldb`: initialize the shared database first; tasks, execution journals and leases are mandatory, and `enableDb` accepts only true.
|
|
22
|
+
|
|
23
|
+
### Quick start
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { reldb } from '@h-ai/reldb'
|
|
27
|
+
import { scheduler } from '@h-ai/scheduler'
|
|
28
|
+
|
|
29
|
+
await reldb.init({ type: 'sqlite', database: './scheduler.db' })
|
|
30
|
+
|
|
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
|
+
### Unified task model
|
|
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
|
+
Notes:
|
|
120
|
+
|
|
121
|
+
- All tasks can be persisted, including `kind: 'js'` tasks.
|
|
122
|
+
- JS tasks are compiled at runtime and cached by source to avoid recompilation on every trigger.
|
|
123
|
+
- `handler` can be omitted; use global `hooks.onTaskExecute` for execution in that case.
|
|
124
|
+
|
|
125
|
+
> ⚠️ **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.
|
|
126
|
+
|
|
127
|
+
### Task lifecycle hooks
|
|
128
|
+
|
|
129
|
+
Provide hooks at initialization or set them at runtime with `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
|
+
### Execution logs
|
|
152
|
+
|
|
153
|
+
Filter logs by trigger source:
|
|
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
|
+
Execution logs support automatic cleanup policies configured at initialization:
|
|
167
|
+
|
|
168
|
+
- `maxLogs`: retain at most N logs.
|
|
169
|
+
- `retentionDays`: retain at most the last N days.
|
|
170
|
+
|
|
171
|
+
### API overview
|
|
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
|
+
### Error handling
|
|
188
|
+
|
|
189
|
+
All public APIs except `close()` return `HaiResult<T>`.
|
|
190
|
+
|
|
191
|
+
Common error codes:
|
|
192
|
+
|
|
193
|
+
| Error code | code | Description |
|
|
194
|
+
| ----------------------------------------- | ------------------- | ----------------------------- |
|
|
195
|
+
| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | Not initialized |
|
|
196
|
+
| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | Initialization failed |
|
|
197
|
+
| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | Invalid configuration |
|
|
198
|
+
| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | Task not found |
|
|
199
|
+
| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | Task already exists |
|
|
200
|
+
| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Invalid cron expression |
|
|
201
|
+
| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | Execution failed |
|
|
202
|
+
| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS execution failed |
|
|
203
|
+
| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API execution failed |
|
|
204
|
+
| `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | Database save failed |
|
|
205
|
+
| `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | Already running |
|
|
206
|
+
| `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | Not running |
|
|
207
|
+
| `HaiSchedulerError.JS_COMPILE_FAILED` | `hai:scheduler:030` | JS compilation failed |
|
|
208
|
+
| `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook execution failed |
|
|
209
|
+
| `HaiSchedulerError.LOG_PERSIST_FAILED` | `hai:scheduler:032` | Log persistence not confirmed |
|
|
210
|
+
|
|
211
|
+
### Runtime behavior and limits
|
|
212
|
+
|
|
213
|
+
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.
|
|
214
|
+
|
|
215
|
+
`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.
|
|
216
|
+
|
|
217
|
+
`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.
|
|
218
|
+
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
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.
|
|
222
|
+
|
|
223
|
+
Repair shrinks the pending list. Drain batches repeatedly at offset=0 instead of advancing the offset while repairing.
|
|
224
|
+
|
|
225
|
+
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.
|
|
226
|
+
|
|
227
|
+
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. Supported old logs are archived and copied by module migrations; execution ledgers remain separate. Closing waits for in-flight repairs; close scheduler before the database.
|
|
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()` 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.
|
|
242
|
+
|
|
243
|
+
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.
|
|
244
|
+
|
|
245
|
+
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.
|
|
246
|
+
|
|
247
|
+
`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`.
|
|
248
|
+
|
|
249
|
+
Cron is matched by minute; the same minute determines a persistent occurrenceId. Delayed ticks still check the current minute once per running scheduler.
|
|
250
|
+
|
|
251
|
+
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.
|
|
252
|
+
|
|
253
|
+
### Optional integrations
|
|
254
|
+
|
|
255
|
+
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.
|
|
256
|
+
|
|
257
|
+
## Legacy database upgrades
|
|
258
|
+
|
|
259
|
+
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.
|
|
260
|
+
|
|
261
|
+
After RelDB init, `migrateScheduler({ dryRun: true })` previews changes; scheduler.init applies supported migrations before repositories. Existing tasks retain data with idempotent=false. Legacy logs are archived as hai_scheduler_logs_alpha65 and copied with stable legacy:<id> keys, preserving complete snapshots without re-executing tasks or duplicating history after interruption. SQLite/PostgreSQL roll back transactions; MySQL resumes from actual structure with old writers stopped. Back up first and restore matching database/binaries for rollback.
|
|
262
|
+
|
|
263
|
+
## Development and testing
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
pnpm --filter @h-ai/scheduler test
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Declaration JSDoc examples import real public entries. Internal repositories, the runner, compiler and cron helpers are marked as internal module context and are not root exports. Examples distinguish HaiResult, explicit cancellation rejection, and close returning Promise<void>; business status and log persistence remain separate, and log repair never reruns business work. Maintainers can run `node scripts/check-module-jsdoc.mjs --package scheduler` to check declaration coverage and real types. Compiling examples does not replace shared-database and independent-process validation.
|
|
270
|
+
|
|
271
|
+
## License
|
|
272
|
+
|
|
273
|
+
Apache-2.0
|
package/README.ja.md
ADDED
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
# @h-ai/scheduler
|
|
2
|
+
|
|
3
|
+
[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
|
|
4
|
+
|
|
5
|
+
[フレームワークのホーム](../../README.ja.md) · 関連モジュール:[@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
|
|
6
|
+
|
|
7
|
+
## 概要
|
|
8
|
+
|
|
9
|
+
共通のタスクモデル、cron スケジュール、JS 関数文字列・HTTP API の実行、永続化、実行ログ検索、全体のライフサイクル Hook を提供するスケジューラーモジュールです。
|
|
10
|
+
|
|
11
|
+
## 主な機能
|
|
12
|
+
|
|
13
|
+
- cron による定期実行とアプリケーションからの手動実行。
|
|
14
|
+
- HTTP、信頼できる JavaScript、アプリ Hook に対応し、再試行とキャンセルを提供。
|
|
15
|
+
- 共有 DB による定義・実行状態・更新可能リースの永続化と結果不明の隔離。
|
|
16
|
+
|
|
17
|
+
## 使い始める
|
|
18
|
+
|
|
19
|
+
### 依存関係
|
|
20
|
+
|
|
21
|
+
- `@h-ai/reldb`:先に共有 DB を初期化し、タスク・journal・リースを保存します。`enableDb` は true のみです。
|
|
22
|
+
|
|
23
|
+
### クイックスタート
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { reldb } from '@h-ai/reldb'
|
|
27
|
+
import { scheduler } from '@h-ai/scheduler'
|
|
28
|
+
|
|
29
|
+
await reldb.init({ type: 'sqlite', database: './scheduler.db' })
|
|
30
|
+
|
|
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'` を含むすべてのタスクを DB に永続化できます。
|
|
122
|
+
- JS タスクは実行時にコンパイルし、ソース単位でキャッシュして毎回の再コンパイルを避けます。
|
|
123
|
+
- `handler` は省略可能で、その場合は共通の `hooks.onTaskExecute` で実行します。
|
|
124
|
+
|
|
125
|
+
> ⚠️ **セキュリティ注意**:`kind: 'js'` は信頼できるサーバー側コード専用です。Node.js の `vm` による実行は**安全なサンドボックスではありません**。ユーザー、テナント、管理画面から任意の JS 文字列を直接受け付けないでください。設定可能なタスクには `kind: 'api'` または `hooks.onTaskExecute` を優先してください。
|
|
126
|
+
|
|
127
|
+
### タスクのライフサイクル Hook
|
|
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
|
+
`close()` を除くすべての公開 API は `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 は復活・コミットできません。`tasks` は最後に成功した定義スナップショットで、読取失敗や削除・無効化・変更は旧試行を中断します。外部副作用は自動で戻りません。
|
|
214
|
+
|
|
215
|
+
`context.occurrenceId` は永続化された発生 ID で、同じ cron 分と再試行で共通です。手動では 1~128 文字の `idempotencyKey` で元の記録を再利用し、省略時は別発生になります。`executionToken` は取得ごとに変わり、`sequence` / `attempt` が世代を示します。API は `Idempotency-Key`、`X-Scheduler-Sequence`、`X-Scheduler-Attempt`、`X-Scheduler-Task`(ID を percent-encoding)を上書きします。取得済みのライフサイクルイベントも `event.context` を提供し、副作用には同じキーによる排除が必要です。
|
|
216
|
+
|
|
217
|
+
`idempotent` の既定は false。受信側が排除台帳と全副作用をアトミックに永続化する場合だけ true にします。期限切れ実行は true のとき同 occurrenceId で引継ぎ、非冪等実行、または保存済み retry.maxAttempts(既定 1、範囲 1–100、初回と復旧を含む)の予算を使い切った場合は `unknown` となりタスク枠を保持します。停止中の旧プロセスが送った外部操作をリースで撤回できず、ヘッダーだけでは排除できません。再試行もこの宣言に従います。
|
|
218
|
+
|
|
219
|
+
正規状態は `scheduler.execution.get(occurrenceId)`、不明一覧は `listUnknown({ limit, offset })`(limit 1~100、offset 0~1000000)で確認します。信頼された担当者が外部効果を照合し旧 runner の終了を確認してから、`resolveUnknown(id, { status: 'success' | 'discarded', expectedUpdatedAt })` の CAS で枠を解放します。不明実行を直接再投入しないでください。`log.occurrenceId` が照会用受領記録で、`getLogs` は試行の観測ログです。ログ保持は journal と排除履歴を削除しません。
|
|
220
|
+
|
|
221
|
+
各試行のログ `id` は固定 UUID です。`persistence.status` は業務 `status` と独立し、`persisted` はログと確認記録の保存済み、`pending` は業務終態の確定後にログ補完待ち、`unconfirmed` は確定済み業務結果を前提にできない状態です。有効な owner とリースの条件で終態と全試行を保存してからログへ投影し、失効ノードは成功を投影できません。ログ失敗を理由に業務成功を失敗へ変更したり、業務を再実行したりしません。
|
|
222
|
+
|
|
223
|
+
補完後は pending 一覧が縮小するため、処理中に offset を進めず、offset=0 のバッチを繰り返し取得してください。
|
|
224
|
+
|
|
225
|
+
信頼されたサーバーは `execution.listLogFailures({ limit, offset })`(listUnknown と同じ上限)で pending を監視し、`execution.repairLog(occurrenceId)` で共有 journal から補完します。別ノード・再起動後・同時呼び出しも可能で、固定主キーと全内容の照合によりコミット後の応答消失を排除します。`LOG_PERSIST_FAILED`(032)は pending を維持して安全な警告を出します。終態の保存前に DB 全体が停止した場合は unknown の外部効果を照合し、復元可能な結果があると仮定しないでください。補完と保持処理は業務 Hook を呼ばず、保持失敗は警告のみです。`onTaskFinish` は未確定のローカル業務終了通知で、保存確認は trigger の戻り値と execution.get.logPersistence を使います。
|
|
226
|
+
|
|
227
|
+
取得前の競合・スキップの interrupted は観測ログで、補完できる確定終態はありません。応答が確認できなければ unconfirmed です。JSON 列で MySQL の 255 文字制限を避け、完全な結果と全再試行を保持します。対応する旧ログはモジュール移行で保存・コピーし、実行台帳は独立します。終了は補完処理を待つため、DB より先に 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 の終了完了まで DB を維持し、その後に依存モジュールを終了します。
|
|
242
|
+
|
|
243
|
+
JS 文字列は呼び出しごとの独立 Worker で実行します。`timeout` は起動を含めて既定 30000 ms です。時間超過時はスレッドを終了し、終了を待ってから失敗記録・再試行を行います。同期の無限ループでもメインイベントループをブロックしません。コンテキストと戻り値は構造化クローンに対応する必要があります。Worker 内の `vm` も安全なサンドボックスではなく、信頼できるサーバー側コードのみを使用します。
|
|
244
|
+
|
|
245
|
+
API タスクの `timeout`(既定 30000 ms)はリクエストと応答本文全体の読み取りを含みます。`ApiTaskConfig.maxResponseBytes` は受信バイト上限で、正の安全な整数、既定は 1048576(1 MiB)です。`maxResponseBytes: 10 * 1024 * 1024` なら最大 10 MiB を許可し、不正値は送信前に失敗します。タイムアウト・上限超過・非成功 HTTP 応答は既定では unknown となり、冪等性を宣言した場合だけ有限回再試行します。
|
|
246
|
+
|
|
247
|
+
`init()` は全タスクの読み込み完了後にのみ成功します。空 ID、重複 ID(保存済みタスクとの重複を含む)、不正な cron、DB 読み取り失敗、保存タスクの解析失敗では失敗を返し、初期化状態を消去します。設定・データを修正してから再初期化し、既存の DB タスクを `tasks` に重複宣言しないでください。
|
|
248
|
+
|
|
249
|
+
cron は分単位で照合し、同じ分から永続 occurrenceId を生成します。遅延 tick でも現在の分を実行中に一度確認します。
|
|
250
|
+
|
|
251
|
+
取得・開始・更新・完了・期限切れ検索・隔離の期限は、同じ SQL 文内でデータベース時刻から計算・検証します。PostgreSQL は clock_timestamp、MySQL は SYSDATE(3)、SQLite はストレージ側 now を使用し、先に時刻を読むだけでは最終条件を代替できません。cron の分 occurrence と式の照合も DB 時刻を使用します。timezone の省略時は UTC、明示した IANA 時区は壁時計の解釈だけを変更し、ノードの TZ は識別子や照合を変えません。Node の Date.now は診断専用です。ノード間で数時間の差があっても早期引継ぎや失効 owner の復活を許可せず、行ロック待機後も期限を検証します。DB 自体の時刻は運用側で信頼性を保ち、外部効果が不明な場合は自動再実行せず照合してください。
|
|
252
|
+
|
|
253
|
+
### 任意の連携
|
|
254
|
+
|
|
255
|
+
Reach 通知を実行するタスクでは、調度ロックやタスク完了だけで外部配信の一意性は保証できません。[Reach キューの意味](../reach/README.ja.md) に従い、永続化された queueId を使ってください。HTTP 受信側は副作用と重複排除を原子的に保存し、SMTP/SMS の配信中の結果不明は手動照合します。スケジューラーの再試行で無条件に再送しないでください。
|
|
256
|
+
|
|
257
|
+
## 旧データベースの更新
|
|
258
|
+
|
|
259
|
+
定義の更新読込、登録、変更、削除は、変更に必要な読込と保存を含めプロセス内で受付順に調整します。正当な並行登録はスナップショットの交錯だけでは失敗せず、実際の DB 障害は失敗として返します。close は入口と runner を停止し、読取待機と未着手の書込を中止して、開始済みの永続書込を待ってから状態を解放します。遅延スナップショットは反映しません。業務コールバックはこのキューを占有しません。ノード間の整合性は引き続き共有 DB、バージョンとリースで保証し、この調整を分散ロックの代替にしません。
|
|
260
|
+
|
|
261
|
+
RelDB 初期化後に `migrateScheduler({ dryRun: true })` で確認し、scheduler.init がリポジトリー前に対応する移行を実行します。旧タスクを保持し idempotent=false を追加します。旧ログを hai_scheduler_logs_alpha65 に保存し、安定した legacy:<id> で完全なスナップショットを冪等コピーします。中断後も履歴を重複せず旧タスクを実行しません。SQLite/PostgreSQL はロールバック、MySQL は旧書込停止下で実構造から再開します。事前バックアップと互換 DB/コードによる復旧が必要です。
|
|
262
|
+
|
|
263
|
+
## 開発とテスト
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
pnpm --filter @h-ai/scheduler test
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
宣言の JSDoc 例は実在する公開入口から import します。内部リポジトリ、runner、コンパイラ、cron ツールは「模块内部上下文」と明記し、パッケージルートの公開 API を意味しません。HaiResult、明示的な取消しの reject、close の Promise<void> を区別し、業務 status とログ persistence も別に確認します。ログ修復で業務を再実行しません。保守時は `node scripts/check-module-jsdoc.mjs --package scheduler` で宣言網羅性と実際の型を検証します。例のコンパイルは共有 DB・独立プロセス検証を代替しません。
|
|
270
|
+
|
|
271
|
+
## ライセンス
|
|
272
|
+
|
|
273
|
+
Apache-2.0
|