@h-ai/scheduler 1.0.0-beta.13 → 1.0.0-beta.15
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 +2 -0
- package/README.ja.md +2 -0
- package/README.md +2 -0
- package/dist/index.js +7 -3
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.en.md
CHANGED
|
@@ -214,6 +214,8 @@ All nodes must initialize the same shared RelDB first (PostgreSQL/MySQL for prod
|
|
|
214
214
|
|
|
215
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
216
|
|
|
217
|
+
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.
|
|
218
|
+
|
|
217
219
|
`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
220
|
|
|
219
221
|
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.
|
package/README.ja.md
CHANGED
|
@@ -214,6 +214,8 @@ const logs = await scheduler.getLogs({
|
|
|
214
214
|
|
|
215
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
216
|
|
|
217
|
+
PostgreSQL では、同じ分内の再起動や複数ノードでの同時取得により、既存の実行記録や使用中のタスク枠に行き当たることがあります。スケジューラーはこれらを通常の競合として処理します。`scheduler.execution.get(occurrenceId)` で実行状態を確認し、重複実行を防ぐために実行台帳と一意制約を保持してください。
|
|
218
|
+
|
|
217
219
|
`idempotent` の既定は false。受信側が排除台帳と全副作用をアトミックに永続化する場合だけ true にします。期限切れ実行は true のとき同 occurrenceId で引継ぎ、非冪等実行、または保存済み retry.maxAttempts(既定 1、範囲 1–100、初回と復旧を含む)の予算を使い切った場合は `unknown` となりタスク枠を保持します。停止中の旧プロセスが送った外部操作をリースで撤回できず、ヘッダーだけでは排除できません。再試行もこの宣言に従います。
|
|
218
220
|
|
|
219
221
|
正規状態は `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 と排除履歴を削除しません。
|
package/README.md
CHANGED
|
@@ -214,6 +214,8 @@ const logs = await scheduler.getLogs({
|
|
|
214
214
|
|
|
215
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
216
|
|
|
217
|
+
使用 PostgreSQL 时,同一分钟重启或多个节点同时领取可能遇到已有执行记录或被占用的任务槽。调度器将这些冲突作为正常竞争处理。排查任务是否完成时,用 `scheduler.execution.get(occurrenceId)` 查看执行状态,并保留账本和唯一约束以防止重复执行。
|
|
218
|
+
|
|
217
219
|
`idempotent` 默认为 false;只有接收端已将幂等账本和全部副作用原子持久提交,才声明 true。租约过期的已执行任务仅在 true 时以同 occurrenceId 接管;非幂等或耗尽本 occurrence 保存的 retry.maxAttempts(默认 1,范围 1–100,包含首次执行及恢复)时进入 `unknown` 并继续占住任务槽。租约无法强制撤销暂停进程已发出的外部操作,单有 HTTP 头不构成去重实现。重试同样受幂等声明约束。
|
|
218
220
|
|
|
219
221
|
`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/幂等历史。
|
package/dist/index.js
CHANGED
|
@@ -341,16 +341,20 @@ var SchedulerExecutionRepository = class extends BaseReldbCrudRepository {
|
|
|
341
341
|
return failed(ready.error);
|
|
342
342
|
const clock = this.databaseClock();
|
|
343
343
|
const owner = `${nodeId}:${randomUUID()}`;
|
|
344
|
+
const postgres = this.db.config?.type === "postgresql";
|
|
345
|
+
const conflictClause = postgres ? " ON CONFLICT DO NOTHING" : "";
|
|
344
346
|
let created;
|
|
345
347
|
try {
|
|
346
348
|
created = await this.db.sql.execute(
|
|
347
349
|
`INSERT INTO ${TABLE} (occurrence_id, task_id, active_task, status, owner, leased_until, attempt_count, max_attempts, idempotent, snapshot, trigger_json, log_persistence, updated_at, created_at)
|
|
348
|
-
VALUES (?, ?, ?, ?, ?, ${clock} + ?, 0, ?, ?, ?, ?, ?, ${clock}, ${clock})`,
|
|
349
|
-
[id, task.id, task.id, "claimed", owner, leaseMs, task.retry?.maxAttempts ?? 1,
|
|
350
|
+
VALUES (?, ?, ?, ?, ?, ${clock} + ?, 0, ?, ?, ?, ?, ?, ${clock}, ${clock})${conflictClause}`,
|
|
351
|
+
[id, task.id, task.id, "claimed", owner, leaseMs, task.retry?.maxAttempts ?? 1, postgres ? task.idempotent === true : Number(task.idempotent === true), JSON.stringify(task), JSON.stringify(trigger), "unconfirmed"]
|
|
350
352
|
);
|
|
351
353
|
} catch (cause) {
|
|
352
354
|
return failed(cause);
|
|
353
355
|
}
|
|
356
|
+
if (postgres && !created.success)
|
|
357
|
+
return failed(created.error);
|
|
354
358
|
const existing = await this.byOccurrence(id);
|
|
355
359
|
if (!existing.success)
|
|
356
360
|
return existing;
|
|
@@ -359,7 +363,7 @@ var SchedulerExecutionRepository = class extends BaseReldbCrudRepository {
|
|
|
359
363
|
return active.success && active.data.length > 0 ? ok(null) : failed(created.success ? void 0 : created.error);
|
|
360
364
|
}
|
|
361
365
|
const row = existing.data;
|
|
362
|
-
if (created.success || ["success", "failed", "interrupted", "discarded"].includes(row.status))
|
|
366
|
+
if (created.success && created.data.changes === 1 || ["success", "failed", "interrupted", "discarded"].includes(row.status))
|
|
363
367
|
return ok(row);
|
|
364
368
|
if (row.status === "unknown")
|
|
365
369
|
return ok(null);
|