@kne/fastify-task 2.0.5 → 3.0.0-alpha.0

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.
@@ -7,9 +7,47 @@ module.exports = fp(async (fastify, options) => {
7
7
  const { models } = fastify[options.name];
8
8
  const { Op } = fastify.sequelize.Sequelize;
9
9
 
10
- /** statistics 插件在 main 之后注册,不能在初始化时解构,否则恒为 undefined */
11
- const callFlushCompletionStatistics = task =>
12
- fastify[options.name].services.flushCompletionStatistics?.(task);
10
+ /** 通过 @kne/fastify-statistics 采集任务完成数据 */
11
+ const collectTaskStatistics = task => {
12
+ const completedAt = task.completedAt || new Date();
13
+ const createdAt = task.createdAt;
14
+ const startedAt = task.startedAt;
15
+ let waitingTime = 0;
16
+ let executionTime = 0;
17
+ let totalTime = 0;
18
+ let hasTiming = false;
19
+
20
+ if (createdAt && completedAt) {
21
+ totalTime = new Date(completedAt).getTime() - new Date(createdAt).getTime();
22
+ if (startedAt) {
23
+ waitingTime = new Date(startedAt).getTime() - new Date(createdAt).getTime();
24
+ executionTime = new Date(completedAt).getTime() - new Date(startedAt).getTime();
25
+ } else {
26
+ executionTime = totalTime;
27
+ }
28
+ hasTiming = totalTime > 0;
29
+ }
30
+
31
+ const data = {
32
+ total: 1,
33
+ [task.status]: 1
34
+ };
35
+ if (hasTiming) {
36
+ data.waitingTime = waitingTime;
37
+ data.executionTime = executionTime;
38
+ data.totalTime = totalTime;
39
+ }
40
+
41
+ fastify[`${options.name}Statistics`].services
42
+ .collect({
43
+ channel: `task:${task.type}:${task.runnerType || 'manual'}`,
44
+ data,
45
+ time: completedAt
46
+ })
47
+ .catch(e => {
48
+ fastify.log.error(`采集任务统计数据失败: ${e.message}`);
49
+ });
50
+ };
13
51
 
14
52
  const generateSignature = ({ secret, id, data }) => {
15
53
  const dataToSign = `${id}|${typeof data === 'string' ? data : JSON.stringify(data)}`;
@@ -24,7 +62,16 @@ module.exports = fp(async (fastify, options) => {
24
62
  return signature === expectedSignature;
25
63
  };
26
64
 
27
- const create = async ({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, options: currentOptions }) => {
65
+ const create = async ({ userId, input, type, targetId, targetType, runnerType, delay = 0, scriptName, priority = 0, parentTaskId, maxRetries = 0, options: currentOptions }) => {
66
+ if (typeof delay !== 'number' || delay < 0) {
67
+ throw new Error('delay 必须为非负数');
68
+ }
69
+ if (typeof priority !== 'number' || !Number.isInteger(priority)) {
70
+ throw new Error('priority 必须为整数');
71
+ }
72
+ if (typeof maxRetries !== 'number' || !Number.isInteger(maxRetries) || maxRetries < 0) {
73
+ throw new Error('maxRetries 必须为非负整数');
74
+ }
28
75
  if (typeof options.task[type] !== 'function') {
29
76
  throw new Error('未找到合法的任务声明');
30
77
  }
@@ -35,6 +82,9 @@ module.exports = fp(async (fastify, options) => {
35
82
  targetId,
36
83
  targetType,
37
84
  runnerType,
85
+ priority,
86
+ parentTaskId,
87
+ maxRetries,
38
88
  startTime: delay > 0 ? new Date(Date.now() + 1000 * delay) : new Date(),
39
89
  scriptName,
40
90
  options: currentOptions
@@ -55,10 +105,20 @@ module.exports = fp(async (fastify, options) => {
55
105
  };
56
106
 
57
107
  const executor = async ({ type, scriptName, ...props }) => {
58
- const taskModulePath = path.resolve(options.dir, type, `${scriptName || options.scriptName}.js`);
59
- if (!(await fs.exists(taskModulePath))) {
60
- throw new Error(`未匹配到任务执行器:${taskModulePath}`);
108
+ const scriptFile = `${scriptName || options.scriptName}.js`;
109
+ let taskModulePath = null;
110
+ for (const dir of options.dirs) {
111
+ const candidate = path.resolve(dir, type, scriptFile);
112
+ if (await fs.exists(candidate)) {
113
+ taskModulePath = candidate;
114
+ break;
115
+ }
116
+ }
117
+ if (!taskModulePath) {
118
+ throw new Error(`未匹配到任务执行器:${type}/${scriptFile},已搜索目录:${options.dirs.join(',')}`);
61
119
  }
120
+ // 清除 require 缓存,确保运行期间模块更新后能加载最新版本
121
+ delete require.cache[taskModulePath];
62
122
  return await require(taskModulePath)(fastify, options, {
63
123
  ...props,
64
124
  updateProgress: async progress => {
@@ -141,7 +201,7 @@ module.exports = fp(async (fastify, options) => {
141
201
  error: result,
142
202
  completedAt: new Date()
143
203
  });
144
- callFlushCompletionStatistics(task);
204
+ collectTaskStatistics(task);
145
205
  return;
146
206
  }
147
207
  await options.task[task.type]({ task, result: result.data, context: task.context });
@@ -151,54 +211,95 @@ module.exports = fp(async (fastify, options) => {
151
211
  progress: 100,
152
212
  completedAt: new Date()
153
213
  });
154
- callFlushCompletionStatistics(task);
214
+ collectTaskStatistics(task);
155
215
  };
156
216
 
157
217
  const processSystemTask = async task => {
158
- try {
159
- await task.update({
160
- status: 'running',
161
- startedAt: new Date(),
162
- progress: 0,
163
- error: null,
164
- output: null,
165
- pollCount: 0,
166
- pollResults: [],
167
- completedAt: null,
168
- context: {}
169
- });
170
- const addLog = props => {
171
- return log(Object.assign({}, props, { taskId: task.id }));
172
- };
173
- executor({ type: task.type, scriptName: task.scriptName, task, log: addLog })
174
- .then(async result => {
175
- if (result === false) {
176
- return;
177
- }
178
- await options.task[task.type]({ task, result, context: task.context });
218
+ await task.update({
219
+ status: 'running',
220
+ startedAt: new Date(),
221
+ progress: 0,
222
+ error: null,
223
+ output: null,
224
+ pollCount: 0,
225
+ pollResults: [],
226
+ completedAt: null,
227
+ context: {}
228
+ });
229
+ const addLog = props => {
230
+ return log(Object.assign({}, props, { taskId: task.id }));
231
+ };
232
+
233
+ // #3: 任务超时自动失败
234
+ const createTimeout = ms => new Promise((_, reject) =>
235
+ setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms)
236
+ );
237
+
238
+ const executorPromise = executor({ type: task.type, scriptName: task.scriptName, task, log: addLog });
239
+ const racePromise = options.taskTimeout > 0
240
+ ? Promise.race([executorPromise, createTimeout(options.taskTimeout)])
241
+ : executorPromise;
242
+
243
+ return racePromise
244
+ .then(async result => {
245
+ if (result === false) {
246
+ return;
247
+ }
248
+ await options.task[task.type]({ task, result, context: task.context });
249
+ await task.update({
250
+ status: 'success',
251
+ output: result,
252
+ progress: 100,
253
+ completedAt: new Date()
254
+ });
255
+ collectTaskStatistics(task);
256
+ // #2: 任务依赖/链式执行 — 父任务成功后激活子任务
257
+ await triggerChildTasks(task);
258
+ })
259
+ .catch(async e => {
260
+ // #4: 重试策略 — 判断是否自动重试
261
+ const currentRetryCount = (task.retryCount || 0) + 1;
262
+ const maxRetries = task.maxRetries || 0;
263
+ if (currentRetryCount < maxRetries) {
264
+ // 指数退避:baseDelay * 2^retryCount
265
+ const baseDelay = options.retryBaseDelay || 5000;
266
+ const backoffDelay = baseDelay * Math.pow(2, currentRetryCount - 1);
179
267
  await task.update({
180
- status: 'success',
181
- output: result,
182
- progress: 100,
183
- completedAt: new Date()
268
+ status: 'pending',
269
+ retryCount: currentRetryCount,
270
+ error: (e.stack || '').replaceAll(process.cwd(), '/server'),
271
+ startTime: new Date(Date.now() + backoffDelay),
272
+ completedAt: null
184
273
  });
185
- callFlushCompletionStatistics(task);
186
- })
187
- .catch(async e => {
274
+ fastify.log.info(`任务 ${task.id} 第 ${currentRetryCount} 次重试,${backoffDelay}ms 后执行`);
275
+ } else {
188
276
  await task.update({
189
277
  status: 'failed',
190
278
  error: (e.stack || '').replaceAll(process.cwd(), '/server'),
191
- completedAt: new Date()
279
+ completedAt: new Date(),
280
+ retryCount: currentRetryCount
192
281
  });
193
- callFlushCompletionStatistics(task);
194
- });
195
- } catch (e) {
196
- await task.update({
197
- status: 'failed',
198
- error: (e.stack || '').replaceAll(process.cwd(), '/server'),
199
- completedAt: new Date()
282
+ collectTaskStatistics(task);
283
+ }
200
284
  });
201
- callFlushCompletionStatistics(task);
285
+ };
286
+
287
+ // #2: 触发子任务(父任务成功后激活 pending 的子任务)
288
+ const triggerChildTasks = async parentTask => {
289
+ const childTasks = await models.task.findAll({
290
+ where: {
291
+ parentTaskId: parentTask.id,
292
+ status: 'pending'
293
+ }
294
+ });
295
+ if (childTasks.length === 0) return;
296
+
297
+ fastify.log.info(`父任务 ${parentTask.id} 完成,激活 ${childTasks.length} 个子任务`);
298
+ for (const child of childTasks) {
299
+ if (child.runnerType === 'system') {
300
+ await processSystemTask(child);
301
+ }
302
+ // manual 类型子任务保持 pending,等待手动执行
202
303
  }
203
304
  };
204
305
 
@@ -214,6 +315,7 @@ module.exports = fp(async (fastify, options) => {
214
315
  fastify.log.info(`当前运行中的系统任务数(${runningTaskCount})已达上限(${options.limit}),暂不执行新任务`);
215
316
  return;
216
317
  }
318
+ // #1: 按优先级降序 + startTime 升序获取待处理任务
217
319
  const pendingTasks = await models.task.findAll({
218
320
  where: {
219
321
  runnerType: 'system',
@@ -222,18 +324,16 @@ module.exports = fp(async (fastify, options) => {
222
324
  [Op.lte]: new Date()
223
325
  }
224
326
  },
225
- limit: options.limit
226
- });
227
-
228
- const count = await models.task.count({
229
- where: {
230
- runnerType: 'system',
231
- status: 'pending'
232
- }
327
+ order: [
328
+ ['priority', 'DESC'],
329
+ ['startTime', 'ASC']
330
+ ],
331
+ limit: limit
233
332
  });
234
333
 
235
334
  if (pendingTasks.length > 0) {
236
- fastify.log.info(`本轮执行 ${pendingTasks.length}/${count} 个待处理的系统任务`);
335
+ fastify.log.info(`本轮执行 ${pendingTasks.length} 个待处理的系统任务`);
336
+ // #8: await processSystemTask 返回的 Promise,防止同任务重复执行
237
337
  await Promise.all(pendingTasks.map(async task => processSystemTask(task)));
238
338
  }
239
339
  };
@@ -247,6 +347,9 @@ module.exports = fp(async (fastify, options) => {
247
347
  };
248
348
 
249
349
  const cancel = async ({ id, targetId, targetType, type }) => {
350
+ if (!id && !(targetId && targetType && type)) {
351
+ throw new Error('必须提供 id 或 targetId+targetType+type');
352
+ }
250
353
  if (targetId && targetType && type) {
251
354
  const bulkWhere = {
252
355
  targetId,
@@ -268,7 +371,7 @@ module.exports = fp(async (fastify, options) => {
268
371
  }
269
372
  );
270
373
  for (const row of tasksToCancel) {
271
- callFlushCompletionStatistics(Object.assign({}, row, { status: 'canceled', completedAt }));
374
+ collectTaskStatistics(Object.assign({}, row, { status: 'canceled', completedAt }));
272
375
  }
273
376
  return affectedCount;
274
377
  }
@@ -281,15 +384,12 @@ module.exports = fp(async (fastify, options) => {
281
384
  status: 'canceled',
282
385
  completedAt: new Date()
283
386
  });
284
- callFlushCompletionStatistics(task);
387
+ collectTaskStatistics(task);
285
388
  }
286
389
  };
287
390
 
288
391
  const complete = async ({ id, userId, output, ...props }) => {
289
392
  const task = await detail({ id });
290
- if (!task) {
291
- throw new Error('任务不存在');
292
- }
293
393
  if (props.status === 'success') {
294
394
  try {
295
395
  await options.task[task.type]({ task, result: output });
@@ -301,7 +401,7 @@ module.exports = fp(async (fastify, options) => {
301
401
  startedAt: task.startedAt || task.createdAt,
302
402
  completedUserId: userId
303
403
  });
304
- callFlushCompletionStatistics(task);
404
+ collectTaskStatistics(task);
305
405
  } catch (e) {
306
406
  await task.update(
307
407
  Object.assign({}, props, {
@@ -312,7 +412,7 @@ module.exports = fp(async (fastify, options) => {
312
412
  startedAt: task.startedAt || task.createdAt
313
413
  })
314
414
  );
315
- callFlushCompletionStatistics(task);
415
+ collectTaskStatistics(task);
316
416
  throw e;
317
417
  }
318
418
  } else {
@@ -324,17 +424,16 @@ module.exports = fp(async (fastify, options) => {
324
424
  completedUserId: userId
325
425
  })
326
426
  );
327
- callFlushCompletionStatistics(task);
427
+ collectTaskStatistics(task);
328
428
  }
329
429
  };
330
430
 
331
431
  const waitingComplete = async ({ id, pollInterval = 1000, maxPollTimes = 20 }) => {
332
432
  const task = await detail({ id });
333
- if (!task) {
334
- throw new Error('任务不存在');
335
- }
336
433
 
337
434
  if (task.status === 'pending') {
435
+ // 标记为最高优先级,确保立即执行(即使因重试等重新入队也会被优先处理)
436
+ await task.update({ priority: Number.MAX_SAFE_INTEGER });
338
437
  await processSystemTask(task);
339
438
  }
340
439
 
@@ -392,7 +491,7 @@ module.exports = fp(async (fastify, options) => {
392
491
  }
393
492
  };
394
493
 
395
- const list = async ({ filter, perPage, currentPage, sort }) => {
494
+ const list = async ({ filter, perPage = 20, currentPage = 1, sort }) => {
396
495
  const whereQuery = {};
397
496
 
398
497
  ['id', 'targetId', 'type', 'status', 'runnerType'].forEach(key => {
@@ -418,22 +517,18 @@ module.exports = fp(async (fastify, options) => {
418
517
  whereQuery.completedAt = getTimeQuery(filter.completedAt);
419
518
  }
420
519
 
421
- // 处理sort排序
422
- let orderBy = 'createdAt';
423
- let orderDirection = 'DESC';
520
+ // 处理sort排序:支持多字段排序
521
+ let order = [['createdAt', 'DESC']];
424
522
 
425
523
  if (sort && Object.keys(sort).length > 0) {
426
- Object.keys(sort).forEach(key => {
427
- orderBy = key;
428
- orderDirection = sort[key];
429
- });
524
+ order = Object.entries(sort).map(([key, direction]) => [key, direction]);
430
525
  }
431
526
 
432
527
  const { rows, count } = await models.task.findAndCountAll({
433
528
  where: Object.assign({}, whereQuery),
434
529
  offset: perPage * (currentPage - 1),
435
530
  limit: perPage,
436
- order: [[orderBy, orderDirection]]
531
+ order: order
437
532
  });
438
533
 
439
534
  return {
@@ -450,7 +545,9 @@ module.exports = fp(async (fastify, options) => {
450
545
  await task.update({
451
546
  status: 'pending',
452
547
  completedAt: null,
453
- completedUserId: null
548
+ completedUserId: null,
549
+ retryCount: 0,
550
+ error: null
454
551
  });
455
552
  };
456
553
 
@@ -468,9 +565,6 @@ module.exports = fp(async (fastify, options) => {
468
565
  const log = async ({ id, taskId, data, message = '' }) => {
469
566
  const targetId = id || taskId;
470
567
  const task = await detail({ id: targetId });
471
- if (!task) {
472
- throw new Error('任务不存在');
473
- }
474
568
 
475
569
  const currentOptions = task.options || {};
476
570
  const logs = (currentOptions.logs || []).slice(0);
@@ -495,9 +589,6 @@ module.exports = fp(async (fastify, options) => {
495
589
  const logWithSignature = async ({ id, taskId, data, message = '', signature }) => {
496
590
  const targetId = id || taskId;
497
591
  const task = await detail({ id: targetId });
498
- if (!task) {
499
- throw new Error('任务不存在');
500
- }
501
592
 
502
593
  if (task.context?.secret && !verifySignature({ secret: task.context.secret, id: targetId, data: { data, message }, signature })) {
503
594
  throw new Error('签名验证失败');
@@ -507,10 +598,7 @@ module.exports = fp(async (fastify, options) => {
507
598
  };
508
599
 
509
600
  const callback = async ({ id, code, data, message }) => {
510
- const task = await detail({ id });
511
- if (!task) {
512
- throw new Error('任务不存在');
513
- }
601
+ await detail({ id });
514
602
 
515
603
  const result = { code, data, message };
516
604
  await log({ id, message: '回调结果', data: JSON.stringify(result) });
@@ -533,9 +621,6 @@ module.exports = fp(async (fastify, options) => {
533
621
 
534
622
  const callbackWithSignature = async ({ id, code, data, message, signature }) => {
535
623
  const task = await detail({ id });
536
- if (!task) {
537
- throw new Error('任务不存在');
538
- }
539
624
 
540
625
  if (task.context?.secret && !verifySignature({ secret: task.context.secret, id, data: { code, data, message }, signature })) {
541
626
  throw new Error('签名验证失败');
@@ -544,6 +629,33 @@ module.exports = fp(async (fastify, options) => {
544
629
  return callback({ id, code, data, message });
545
630
  };
546
631
 
632
+ const append = async ({ dirs, tasks }) => {
633
+ const result = { dirs: [], tasks: [] };
634
+ if (Array.isArray(dirs)) {
635
+ for (const dir of dirs) {
636
+ if (!options.dirs.includes(dir)) {
637
+ if (!(await fs.exists(dir))) {
638
+ console.warn(`append 目录不存在:${dir},仍会添加但运行时可能无法匹配任务执行器`);
639
+ }
640
+ options.dirs.push(dir);
641
+ result.dirs.push(dir);
642
+ }
643
+ }
644
+ }
645
+ if (tasks && typeof tasks === 'object') {
646
+ Object.entries(tasks).forEach(([type, handler]) => {
647
+ if (typeof handler !== 'function') {
648
+ throw new Error(`任务 ${type} 的 handler 必须是一个函数`);
649
+ }
650
+ if (typeof options.task[type] !== 'function') {
651
+ options.task[type] = handler;
652
+ result.tasks.push(type);
653
+ }
654
+ });
655
+ }
656
+ return result;
657
+ };
658
+
547
659
  Object.assign(fastify[options.name].services, {
548
660
  create,
549
661
  detail,
@@ -560,6 +672,7 @@ module.exports = fp(async (fastify, options) => {
560
672
  executor,
561
673
  processNext,
562
674
  processSystemTask,
563
- waitingComplete
675
+ waitingComplete,
676
+ append
564
677
  });
565
678
  });