@kne/fastify-task 3.0.0 → 3.0.4

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.
@@ -368,7 +368,7 @@ module.exports = fp(async (fastify, options) => {
368
368
  schema: {
369
369
  tags: [CALLBACK_TAG],
370
370
  summary: '任务回调',
371
- description: `外部服务回传任务最终结果:先把回调内容记入任务日志,code 为 0 时任务成功(data 作为输出),否则任务失败(message 作为错误);${SIGNATURE_HINT}。该接口不鉴权`,
371
+ description: `外部服务回传任务结果:先把回调内容记入任务日志,code 为 0 时任务成功(data 作为输出),否则任务失败(message 作为错误);code 为 0 且传了小于 100 的 progress 时只上报进度(更新任务 progress 并记日志,任务保持原状态);${SIGNATURE_HINT}。该接口不鉴权`,
372
372
  body: {
373
373
  type: 'object',
374
374
  properties: {
@@ -378,7 +378,7 @@ module.exports = fp(async (fastify, options) => {
378
378
  },
379
379
  code: {
380
380
  type: 'number',
381
- description: '结果码,0 表示成功,其他表示失败'
381
+ description: '结果码(必填),0 表示成功,其他表示失败'
382
382
  },
383
383
  data: {
384
384
  type: 'object',
@@ -386,13 +386,20 @@ module.exports = fp(async (fastify, options) => {
386
386
  },
387
387
  message: {
388
388
  type: 'string',
389
- description: '结果说明,失败时作为错误信息'
389
+ description: '结果说明,失败时作为错误信息;进度上报时作为日志说明'
390
+ },
391
+ progress: {
392
+ type: 'number',
393
+ minimum: 0,
394
+ maximum: 100,
395
+ description: '任务进度 0-100。code 为 0 且小于 100 时仅上报进度,任务不结束;不传或为 100 时按最终结果处理'
390
396
  },
391
397
  signature: {
392
398
  type: 'string',
393
399
  description: 'HMAC-SHA256签名'
394
400
  }
395
- }
401
+ },
402
+ required: ['code']
396
403
  },
397
404
  query: {
398
405
  type: 'object',
@@ -17,6 +17,8 @@ const createContext = (fastify, options) => {
17
17
  if (task.reload && typeof task.reload === 'function') {
18
18
  await task.reload();
19
19
  }
20
+ // errorHandler 重试会把任务改回 pending,此时任务未结束,等最终结束时再采集
21
+ if (!TERMINAL_STATUSES.includes(task.status)) return;
20
22
  const completedAt = task.completedAt || new Date();
21
23
  const createdAt = task.createdAt;
22
24
  const startedAt = task.startedAt;
@@ -108,14 +110,17 @@ const createContext = (fastify, options) => {
108
110
  return { handler: config };
109
111
  }
110
112
  if (config && typeof config === 'object' && !Array.isArray(config)) {
111
- const { handler, errorHandler, next } = config;
113
+ const { handler, errorHandler, cancelHandler, next } = config;
112
114
  if (handler != null && typeof handler !== 'function') {
113
115
  throw new Error(`任务 ${taskName} 的 handler 必须是一个函数`);
114
116
  }
115
117
  if (errorHandler != null && typeof errorHandler !== 'function') {
116
118
  throw new Error(`任务 ${taskName} 的 errorHandler 必须是一个函数`);
117
119
  }
118
- return { handler, errorHandler, next };
120
+ if (cancelHandler != null && typeof cancelHandler !== 'function') {
121
+ throw new Error(`任务 ${taskName} 的 cancelHandler 必须是一个函数`);
122
+ }
123
+ return { handler, errorHandler, cancelHandler, next };
119
124
  }
120
125
  throw new Error(`任务 ${taskName} 的 handler 必须是一个函数`);
121
126
  };
@@ -135,6 +140,7 @@ const createContext = (fastify, options) => {
135
140
  scriptName: scriptName || (namespace === mainNamespace ? options.scriptName : 'index'),
136
141
  handler: normalizedConfig.handler,
137
142
  errorHandler: normalizedConfig.errorHandler,
143
+ cancelHandler: normalizedConfig.cancelHandler,
138
144
  next: normalizedConfig.next
139
145
  };
140
146
  options.taskRegistry[registryKey] = declaration;
@@ -240,6 +246,12 @@ const createContext = (fastify, options) => {
240
246
  return declaration.errorHandler;
241
247
  };
242
248
 
249
+ const getTaskCancelHandler = declaration => {
250
+ const legacyConfig = options.task[declaration.type] || (declaration.namespace === mainNamespace ? options.task[declaration.taskName] : null);
251
+ if (legacyConfig && typeof legacyConfig === 'object' && typeof legacyConfig.cancelHandler === 'function') return legacyConfig.cancelHandler;
252
+ return declaration.cancelHandler;
253
+ };
254
+
243
255
  const getTaskNext = declaration => {
244
256
  const legacyConfig = options.task[declaration.type] || (declaration.namespace === mainNamespace ? options.task[declaration.taskName] : null);
245
257
  if (legacyConfig && typeof legacyConfig === 'object' && Object.prototype.hasOwnProperty.call(legacyConfig, 'next')) return legacyConfig.next;
@@ -292,6 +304,22 @@ const createContext = (fastify, options) => {
292
304
  return true;
293
305
  };
294
306
 
307
+ // 任务被取消后的通知:任务级 cancelHandler 优先,未配置时调用全局 options.cancelHandler;
308
+ // 取消已经生效,处理器抛错只记录日志,不影响取消结果
309
+ const handleTaskCancel = async ({ task }) => {
310
+ const declaration = resolveTaskDeclaration(task.type);
311
+ const taskCancelHandler = declaration && getTaskCancelHandler(declaration);
312
+ const cancelHandler = typeof taskCancelHandler === 'function' ? taskCancelHandler : options.cancelHandler;
313
+ if (typeof cancelHandler !== 'function') {
314
+ return;
315
+ }
316
+ try {
317
+ await cancelHandler({ task, context: task.context });
318
+ } catch (e) {
319
+ fastify.log.error(e);
320
+ }
321
+ };
322
+
295
323
  const handleTaskError = async ({ task, error }) => {
296
324
  const declaration = resolveTaskDeclaration(task.type);
297
325
  let currentError = error;
@@ -549,6 +577,7 @@ const createContext = (fastify, options) => {
549
577
  resolveTaskDeclaration,
550
578
  detail,
551
579
  failTask,
580
+ handleTaskCancel,
552
581
  create,
553
582
  executor,
554
583
  finalizeSuccess
@@ -52,20 +52,46 @@ const taskList = {
52
52
  }
53
53
  };
54
54
 
55
+ const DURATION_ITEM = '每项为 { count, avgWaitingTime, avgExecutionTime, avgTotalTime }';
56
+
57
+ const bucket = obj('趋势桶', {
58
+ key: str('桶 key:YYYY-MM-DD(日 / 周起始日)或 YYYY-MM(月)'),
59
+ start: any('桶起点(含)'),
60
+ end: any('桶终点(不含);最后一个桶为当前时间')
61
+ });
62
+
63
+ const duration = obj('范围内耗时汇总;查询异常时为 null', {
64
+ completedCount: num('已结束任务数'),
65
+ successCount: num('成功任务数'),
66
+ failedCount: num('失败任务数'),
67
+ canceledCount: num('取消任务数'),
68
+ avgWaitingTime: num('平均等待时间(毫秒),无耗时数据时为 0'),
69
+ avgExecutionTime: num('平均执行时间(毫秒),无耗时数据时为 0'),
70
+ avgTotalTime: num('平均总耗时(毫秒),无耗时数据时为 0'),
71
+ byType: obj(`按任务类型拆分,键为任务类型,${DURATION_ITEM}`),
72
+ byRunnerType: obj(`按执行方式拆分,键为 manual / system,${DURATION_ITEM}`),
73
+ byTypeByRunnerType: obj(`先按执行方式再按任务类型拆分,结构为 { [runnerType]: { [type]: 耗时项 } },${DURATION_ITEM}`)
74
+ });
75
+
55
76
  const statistics = {
56
77
  type: 'object',
57
78
  additionalProperties: true,
58
79
  properties: {
59
80
  range: str('时间范围:7d / 1m / 3m / 1y'),
60
81
  rangeLabel: str('时间范围名称,如「近7天」'),
82
+ granularity: str('趋势粒度:7d / 1m 为 day,3m 为 week(周一起),1y 为 month'),
83
+ startTime: any('统计起始时间(第一个桶的起点)'),
84
+ endTime: any('统计截止时间(当前时间)'),
85
+ buckets: list('趋势桶列表,按时间正序', bucket),
61
86
  totalTasks: num('范围内已结束(成功、失败、取消)的任务总数'),
62
87
  byStatus: any('按状态统计的任务数,键为 success / failed / canceled'),
63
88
  byType: any('按任务类型统计的任务数,键为任务类型'),
64
89
  byRunnerType: any('按执行方式统计的任务数,键为 manual / system'),
65
- recentTrend: any('每日趋势,每项为 { date, count }'),
66
- recentTrendByStatus: any('每日按状态趋势,每项为 { date, status, count }'),
67
- recentTrendByType: any('每日按类型趋势,每项为 { date, type, count }'),
68
- durationTrend: any('每日耗时趋势,每项含 date、完成/成功/失败数及平均等待、执行、总耗时(毫秒)'),
90
+ recentTrend: any('按桶趋势,每项为 { date, count },date 为桶 key,无数据的桶补 0'),
91
+ recentTrendByStatus: any('按桶按状态趋势,每项为 { date, status, count },每个桶都含 success / failed / canceled'),
92
+ recentTrendByType: any('按桶按类型趋势,每项为 { date, type, count }'),
93
+ durationTrend: any('按桶耗时趋势,每项含 date(桶 key)、完成/成功/失败数及平均等待、执行、总耗时(毫秒)'),
94
+ duration,
69
95
  hourlyTrend: any('按小时趋势,每项为 { date, hour, total, success, failed, canceled };查询失败或无数据时不返回'),
70
96
  hourlyCompletionTrend: any('按小时、类型、执行方式的完成明细,每项含 date、hour、type、runnerType 及完成/成功/失败/取消数')
71
97
  }
@@ -66,11 +66,41 @@ module.exports = fp(async (fastify, options) => {
66
66
  return log({ id: targetId, data, message });
67
67
  };
68
68
 
69
- const callback = async ({ id, code, data, message }) => {
69
+ const ACTIVE_STATUSES = ['pending', 'running', 'waiting'];
70
+
71
+ const normalizeProgress = progress => {
72
+ if (progress == null) return null;
73
+ if (typeof progress !== 'number' || !Number.isFinite(progress) || progress < 0 || progress > 100) {
74
+ throw new Error('progress 必须是 0-100 之间的数字');
75
+ }
76
+ return progress;
77
+ };
78
+
79
+ // 进度上报:只更新进度并记日志,任务保持原状态,不触发 handler / next / errorHandler
80
+ const reportProgress = async ({ id, code, data, message, progress }) => {
81
+ const task = await context.detail({ id });
82
+ const updated = await context.updateTaskByStatus({
83
+ task,
84
+ allowedStatuses: ACTIVE_STATUSES,
85
+ updateData: { progress: Math.round(progress) }
86
+ });
87
+ if (!updated) {
88
+ return;
89
+ }
90
+ await log({ id, message: message || '进度回调', data: { code, data, message, progress } });
91
+ };
92
+
93
+ const callback = async ({ id, code, data, message, progress }) => {
70
94
  await context.detail({ id });
71
95
 
96
+ const currentProgress = normalizeProgress(progress);
97
+ // code 为 0 且 progress 小于 100 视为进度上报;不带 progress 或 progress 为 100 时与原来一致,按最终结果处理
98
+ if (code === 0 && currentProgress != null && currentProgress < 100) {
99
+ return reportProgress({ id, code, data, message, progress: currentProgress });
100
+ }
101
+
72
102
  const result = { code, data, message };
73
- await log({ id, message: '回调结果', data: JSON.stringify(result) });
103
+ await log({ id, message: '回调结果', data: result });
74
104
  const input = Object.assign(
75
105
  {},
76
106
  { id },
@@ -88,15 +118,16 @@ module.exports = fp(async (fastify, options) => {
88
118
  await fastify[options.name].services.complete(input);
89
119
  };
90
120
 
91
- const callbackWithSignature = async ({ id, taskId, code, data, message, signature }) => {
121
+ const callbackWithSignature = async ({ id, taskId, code, data, message, progress, signature }) => {
92
122
  const targetId = id || taskId;
93
123
  const task = await context.detail({ id: targetId });
94
124
 
95
- if (task.context?.secret && !context.verifySignature({ secret: task.context.secret, id: targetId, data: { code, data, message }, signature })) {
125
+ // progress 为 undefined 时 JSON 序列化会忽略该字段,签名内容与不带进度的旧回调完全一致
126
+ if (task.context?.secret && !context.verifySignature({ secret: task.context.secret, id: targetId, data: { code, data, message, progress }, signature })) {
96
127
  throw new Error('签名验证失败');
97
128
  }
98
129
 
99
- return callback({ id: targetId, code, data, message });
130
+ return callback({ id: targetId, code, data, message, progress });
100
131
  };
101
132
 
102
133
  Object.assign(fastify[options.name].services, {
@@ -63,12 +63,17 @@ module.exports = fp(async (fastify, options) => {
63
63
  return fastify[options.name].services.log(Object.assign({}, props, { taskId: task.id }));
64
64
  };
65
65
 
66
- const createTimeout = ms => new Promise((_, reject) => setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms));
66
+ let timeoutTimer;
67
+ const createTimeout = ms =>
68
+ new Promise((_, reject) => {
69
+ timeoutTimer = setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms);
70
+ });
67
71
 
68
72
  const executorPromise = context.executor({ type: task.type, scriptName: task.scriptName, task, log: addLog });
69
73
  const racePromise = options.taskTimeout > 0 ? Promise.race([executorPromise, createTimeout(options.taskTimeout)]) : executorPromise;
70
74
 
71
75
  return racePromise
76
+ .finally(() => clearTimeout(timeoutTimer))
72
77
  .then(async result => {
73
78
  if (result === false) {
74
79
  return;