@h-ai/scheduler 0.1.0-alpha.53 → 0.1.0-alpha.55

package/README.md

@@ -2,6 +2,18 @@
 
 定时任务调度模块，支持统一任务模型、cron 调度、JS 函数字符串 / HTTP API 执行、任务持久化、执行日志查询，以及全局任务生命周期回调。
 
+启用数据库时，运行中的节点每个 `tickInterval`（默认 1000 毫秒）刷新持久化定义；`tasks` 是最近一次成功刷新的快照。注册、修改、删除、手工触发和获得调度锁后的每次尝试均重新读取定义，删除/禁用/已改调度时间的旧任务不会继续执行，读取失败则中断本次尝试。已经开始的业务副作用不因远端定义变化自动回滚。`init({ tasks })` 仍是节点本地配置，跨节点动态任务请用持久化的 `register()` 管理；跨节点防重需要共享 Redis，内存缓存仅限单进程。
+
+多节点回归测试会构建当前源码、启动两个真实 Node 进程共享 SQLite 和 Testcontainers Redis，验证定义收敛及同分钟锁竞争；运行 `pnpm --filter @h-ai/scheduler test` 前须有可用的 Docker/Podman 服务。
+
+`await scheduler.close()` 先停止接收任务，取消 HTTP、JS Worker 与重试等待，再等待执行链退出后清理状态。重新初始化等待关闭完成。所有生命周期事件提供 `signal`；Hook 必须监听取消并停止自己的外部副作用（框架无法强制终止同一线程中的业务代码），不要在 Hook 中阻塞事件循环。取消后的旧执行不再重试、不自动删除任务，也不会调用新实例的 Hook。关闭期间保持数据库和缓存可用，待 scheduler 关闭后再关闭依赖。
+
+JS 字符串在每次调用的独立 Worker 中执行，`timeout` 默认 30000 毫秒（含启动）。到期后终止并等待线程退出，再记录失败或重试；同步死循环也不会阻塞主事件循环。上下文及返回值必须支持结构化克隆。Worker 中的 `vm` 仍不是安全沙箱，代码必须来自受信任的服务端来源。
+
+API 任务的 `timeout`（默认 30000 毫秒）覆盖请求和完整响应体读取。`ApiTaskConfig.maxResponseBytes` 指定响应体实际接收字节上限（正安全整数，默认 1048576 即 1 MiB）；例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB，非法值在请求前失败；超时、超限或非成功 HTTP 状态均记录失败并应用任务重试策略。
+
+`init()` 必须完整加载全部任务才返回成功。配置中的空 ID、重复 ID（含与持久化任务重复）、无效 cron，以及数据库读取或持久化任务解析失败，均返回失败并清空初始化状态；修正配置或数据后重新初始化。不要同时在 `tasks` 中重复声明已有的数据库任务。
+
 ## 依赖
 
 - `@h-ai/reldb` — 任务定义与执行日志持久化，`enableDb: true` 时需先初始化
@@ -202,3 +214,5 @@ pnpm --filter @h-ai/scheduler test
 ## License
 
 Apache-2.0
+
+调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。

package/dist/index.d.ts

@@ -81,8 +81,10 @@ interface ApiTaskConfig {
     headers?: Record<string, string>;
     /** 请求体（POST/PUT/PATCH 时使用） */
     body?: unknown;
-    /** 超时时间，单位毫秒（默认 30000） */
+    /** 请求及完整响应体读取的总超时，单位毫秒（默认 30000） */
     timeout?: number;
+    /** 响应体实际接收字节上限，必须为正安全整数（默认 1048576，即 1 MiB） */
+    maxResponseBytes?: number;
 }
 /**
  * JS 任务配置
@@ -99,7 +101,7 @@ interface JsTaskConfig {
     kind: 'js';
     /** JS 函数字符串（仅允许受信任的服务端代码，不是安全沙箱） */
     code: string;
-    /** 软超时时间，单位毫秒 */
+    /** 独立线程执行期限，单位毫秒（默认 30000，含线程启动）；超时终止线程后才允许重试 */
     timeout?: number;
 }
 /** 统一任务处理器配置 */
@@ -177,9 +179,11 @@ interface SchedulerTaskContext {
     trigger: TaskTriggerInfo;
 }
 /** 编译后的 JS 任务函数 */
-type JsTaskHandler = (context: SchedulerTaskContext) => unknown | Promise<unknown>;
+type JsTaskHandler = (context: SchedulerTaskContext, signal?: AbortSignal) => unknown | Promise<unknown>;
 /** 任务开始事件 */
 interface SchedulerTaskStartEvent {
+    /** 关闭调度器时取消；回调必须停止后续副作用并释放资源 */
+    signal: AbortSignal;
     /** 当前任务 */
     task: TaskDefinition;
     /** 触发信息 */