@kne/fastify-task 3.0.0-alpha.5 → 3.0.0-alpha.6

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.
@@ -0,0 +1,191 @@
1
+ /**
2
+ * 自定义错误类体系
3
+ * 提供结构化的错误处理机制
4
+ */
5
+
6
+ // 基础任务错误类
7
+ class TaskError extends Error {
8
+ constructor(code, message, details = {}) {
9
+ super(message);
10
+ this.name = 'TaskError';
11
+ this.code = code;
12
+ this.details = details;
13
+ this.timestamp = new Date().toISOString();
14
+ Error.captureStackTrace(this, this.constructor);
15
+ }
16
+
17
+ toJSON() {
18
+ return {
19
+ name: this.name,
20
+ code: this.code,
21
+ message: this.message,
22
+ details: this.details,
23
+ timestamp: this.timestamp
24
+ };
25
+ }
26
+ }
27
+
28
+ // 任务不存在错误
29
+ class TaskNotFoundError extends TaskError {
30
+ constructor(taskId, details = {}) {
31
+ super('TASK_NOT_FOUND', `任务不存在: ${taskId}`, { taskId, ...details });
32
+ this.name = 'TaskNotFoundError';
33
+ }
34
+ }
35
+
36
+ // 任务状态错误
37
+ class TaskStatusError extends TaskError {
38
+ constructor(taskId, currentStatus, expectedStatus, details = {}) {
39
+ super(
40
+ 'TASK_STATUS_ERROR',
41
+ `任务状态不允许此操作: 当前状态 ${currentStatus}, 期望状态 ${expectedStatus}`,
42
+ { taskId, currentStatus, expectedStatus, ...details }
43
+ );
44
+ this.name = 'TaskStatusError';
45
+ }
46
+ }
47
+
48
+ // 任务超时错误
49
+ class TaskTimeoutError extends TaskError {
50
+ constructor(taskId, timeout, details = {}) {
51
+ super('TASK_TIMEOUT', `任务执行超时: ${timeout}ms`, { taskId, timeout, ...details });
52
+ this.name = 'TaskTimeoutError';
53
+ }
54
+ }
55
+
56
+ // 任务验证错误
57
+ class TaskValidationError extends TaskError {
58
+ constructor(field, value, reason, details = {}) {
59
+ super(
60
+ 'TASK_VALIDATION_ERROR',
61
+ `任务参数验证失败: ${field} = ${value}, 原因: ${reason}`,
62
+ { field, value, reason, ...details }
63
+ );
64
+ this.name = 'TaskValidationError';
65
+ }
66
+ }
67
+
68
+ // 任务执行错误
69
+ class TaskExecutionError extends TaskError {
70
+ constructor(taskId, originalError, details = {}) {
71
+ super(
72
+ 'TASK_EXECUTION_ERROR',
73
+ `任务执行失败: ${originalError.message}`,
74
+ { taskId, originalError: originalError.message, ...details }
75
+ );
76
+ this.name = 'TaskExecutionError';
77
+ this.originalError = originalError;
78
+ }
79
+ }
80
+
81
+ // 安全错误
82
+ class SecurityError extends TaskError {
83
+ constructor(reason, details = {}) {
84
+ super('SECURITY_ERROR', `安全检查失败: ${reason}`, { reason, ...details });
85
+ this.name = 'SecurityError';
86
+ }
87
+ }
88
+
89
+ // 配置错误
90
+ class ConfigurationError extends TaskError {
91
+ constructor(configKey, reason, details = {}) {
92
+ super('CONFIGURATION_ERROR', `配置错误: ${configKey} - ${reason}`, { configKey, reason, ...details });
93
+ this.name = 'ConfigurationError';
94
+ }
95
+ }
96
+
97
+ // 数据库错误
98
+ class DatabaseError extends TaskError {
99
+ constructor(operation, originalError, details = {}) {
100
+ super(
101
+ 'DATABASE_ERROR',
102
+ `数据库操作失败: ${operation}`,
103
+ { operation, originalError: originalError.message, ...details }
104
+ );
105
+ this.name = 'DatabaseError';
106
+ this.originalError = originalError;
107
+ }
108
+ }
109
+
110
+ // 错误处理工具函数
111
+ class ErrorHandler {
112
+ /**
113
+ * 处理错误并返回适当的响应
114
+ * @param {Error} error - 错误对象
115
+ * @param {Object} logger - 日志记录器
116
+ * @returns {Object} 错误响应
117
+ */
118
+ static handle(error, logger) {
119
+ if (error instanceof TaskError) {
120
+ // 自定义任务错误
121
+ logger.warn(`任务错误 [${error.code}]: ${error.message}`, error.details);
122
+ return {
123
+ success: false,
124
+ error: {
125
+ code: error.code,
126
+ message: error.message,
127
+ details: error.details
128
+ }
129
+ };
130
+ }
131
+
132
+ // 未知错误
133
+ logger.error('未知错误:', error);
134
+ return {
135
+ success: false,
136
+ error: {
137
+ code: 'UNKNOWN_ERROR',
138
+ message: '服务器内部错误',
139
+ details: process.env.NODE_ENV === 'development' ? { message: error.message } : {}
140
+ }
141
+ };
142
+ }
143
+
144
+ /**
145
+ * 异步包装器,自动处理错误
146
+ * @param {Function} fn - 异步函数
147
+ * @param {Object} logger - 日志记录器
148
+ * @returns {Function} 包装后的函数
149
+ */
150
+ static asyncWrapper(fn, logger) {
151
+ return async (...args) => {
152
+ try {
153
+ return await fn(...args);
154
+ } catch (error) {
155
+ throw this.handle(error, logger);
156
+ }
157
+ };
158
+ }
159
+
160
+ /**
161
+ * 将错误转换为任务错误
162
+ * @param {Error} error - 原始错误
163
+ * @param {string} defaultCode - 默认错误代码
164
+ * @param {string} defaultMessage - 默认错误消息
165
+ * @returns {TaskError} 任务错误对象
166
+ */
167
+ static toTaskError(error, defaultCode = 'UNKNOWN_ERROR', defaultMessage = '未知错误') {
168
+ if (error instanceof TaskError) {
169
+ return error;
170
+ }
171
+
172
+ return new TaskError(
173
+ defaultCode,
174
+ defaultMessage,
175
+ { originalError: error.message, stack: error.stack }
176
+ );
177
+ }
178
+ }
179
+
180
+ module.exports = {
181
+ TaskError,
182
+ TaskNotFoundError,
183
+ TaskStatusError,
184
+ TaskTimeoutError,
185
+ TaskValidationError,
186
+ TaskExecutionError,
187
+ SecurityError,
188
+ ConfigurationError,
189
+ DatabaseError,
190
+ ErrorHandler
191
+ };
@@ -0,0 +1,196 @@
1
+ const { TaskExecutionError, TaskTimeoutError } = require('../errors');
2
+ const { CONFIG_CONSTANTS } = require('../config');
3
+
4
+ /**
5
+ * 任务执行器模块
6
+ * 负责任务的实际执行逻辑
7
+ */
8
+ class TaskExecutor {
9
+ constructor(fastify, config, models, securityValidator, cacheManager) {
10
+ this.fastify = fastify;
11
+ this.config = config;
12
+ this.models = models;
13
+ this.securityValidator = securityValidator;
14
+ this.cacheManager = cacheManager;
15
+ this.path = require('node:path');
16
+ this.fs = require('fs-extra');
17
+ }
18
+
19
+ /**
20
+ * 执行任务
21
+ * @param {Object} params - 执行参数
22
+ * @returns {*} 执行结果
23
+ */
24
+ async execute({ type, scriptName, ...props }) {
25
+ try {
26
+ // 验证任务类型
27
+ this.securityValidator.validateTaskType(type, Object.keys(this.config.task || {}));
28
+
29
+ const scriptFile = `${scriptName || this.config.scriptName}${CONFIG_CONSTANTS.SCRIPT_EXTENSION}`;
30
+ let taskModulePath = null;
31
+
32
+ // 安全的路径查找和验证
33
+ for (const dir of this.config.dirs) {
34
+ try {
35
+ const candidate = this.path.join(dir, type, scriptFile);
36
+ const validatedPath = this.securityValidator.validateScriptPath(dir, this.path.join(type, scriptFile));
37
+
38
+ if (await this.fs.exists(validatedPath)) {
39
+ taskModulePath = validatedPath;
40
+ break;
41
+ }
42
+ } catch (error) {
43
+ // 跳过无效路径,继续尝试其他目录
44
+ this.fastify.log.debug(`路径验证失败: ${error.message}`);
45
+ continue;
46
+ }
47
+ }
48
+
49
+ if (!taskModulePath) {
50
+ throw new Error(`未匹配到任务执行器:${type}/${scriptFile},已搜索目录:${this.config.dirs.join(',')}`);
51
+ }
52
+
53
+ // 清除 require 缓存,确保运行期间模块更新后能加载最新版本
54
+ delete require.cache[taskModulePath];
55
+
56
+ return await require(taskModulePath)(this.fastify, this.config, this.createExecutionContext(props));
57
+ } catch (error) {
58
+ throw new TaskExecutionError(props.task?.id, error, { operation: 'executor' });
59
+ }
60
+ }
61
+
62
+ /**
63
+ * 创建执行上下文
64
+ * @param {Object} props - 属性
65
+ * @returns {Object} 执行上下文
66
+ */
67
+ createExecutionContext(props) {
68
+ return {
69
+ ...props,
70
+ updateProgress: this.createProgressUpdater(props),
71
+ polling: this.createPollingFunction(props),
72
+ next: this.createNextFunction(props)
73
+ };
74
+ }
75
+
76
+ /**
77
+ * 创建进度更新器
78
+ * @param {Object} props - 属性
79
+ * @returns {Function} 进度更新函数
80
+ */
81
+ createProgressUpdater(props) {
82
+ return async (progress) => {
83
+ try {
84
+ const validatedProgress = this.securityValidator.validateNumber(progress, {
85
+ min: 0,
86
+ max: 100,
87
+ integer: true
88
+ });
89
+
90
+ if (typeof props?.task?.update === 'function') {
91
+ await props.task.update({ progress: validatedProgress });
92
+
93
+ // 更新缓存
94
+ this.cacheManager.set(`task:${props.task.id}`, props.task, 60000);
95
+ }
96
+ } catch (error) {
97
+ this.fastify.log.warn(`进度更新失败: ${error.message}`);
98
+ }
99
+ };
100
+ }
101
+
102
+ /**
103
+ * 创建轮询函数
104
+ * @param {Object} props - 属性
105
+ * @returns {Function} 轮询函数
106
+ */
107
+ createPollingFunction(props) {
108
+ return async (callback, currentOptions) => {
109
+ const maxPollTimes = this.securityValidator.validateNumber(
110
+ currentOptions?.maxPollTimes || this.config.maxPollTimes,
111
+ { min: 1, max: 1000, integer: true }
112
+ );
113
+
114
+ const pollInterval = this.securityValidator.validateNumber(
115
+ currentOptions?.pollInterval || this.config.pollInterval,
116
+ { min: CONFIG_CONSTANTS.POLL_MIN_INTERVAL_MS, max: CONFIG_CONSTANTS.POLL_MAX_INTERVAL_MS }
117
+ );
118
+
119
+ let pollCount = 0;
120
+ return await new Promise((resolve, reject) => {
121
+ const executePolling = async () => {
122
+ try {
123
+ pollCount++;
124
+ if (pollCount > maxPollTimes) {
125
+ reject(new TaskTimeoutError(props.task?.id, maxPollTimes * pollInterval, {
126
+ reason: `轮询超时(${maxPollTimes}次),任务未完成`
127
+ }));
128
+ return;
129
+ }
130
+
131
+ const pollingResult = Object.assign({}, await callback());
132
+ const { result, data, message, progress } = pollingResult;
133
+
134
+ if (typeof props?.task?.update === 'function') {
135
+ await props.task.reload();
136
+ const limitedPollResults = this.securityValidator.limitLogsSize(
137
+ [...props.task.pollResults, Object.assign({}, pollingResult, { time: new Date() })],
138
+ CONFIG_CONSTANTS.LOGS_MAX_SIZE
139
+ );
140
+
141
+ await props.task.update(
142
+ Object.assign(
143
+ {},
144
+ {
145
+ pollCount: props.task.pollCount + 1,
146
+ pollResults: limitedPollResults
147
+ },
148
+ Number.isInteger(progress) ? { progress } : {}
149
+ )
150
+ );
151
+
152
+ // 更新缓存
153
+ this.cacheManager.set(`task:${props.task.id}`, props.task, 60000);
154
+ }
155
+
156
+ if (result === 'failed') {
157
+ reject(new TaskExecutionError(props.task?.id, new Error(message), { reason: '任务处理失败' }));
158
+ return;
159
+ }
160
+
161
+ if (result === 'success') {
162
+ resolve(data);
163
+ return;
164
+ }
165
+
166
+ // 任务未完成,等待pollInterval后继续执行
167
+ setTimeout(executePolling, pollInterval);
168
+ } catch (e) {
169
+ reject(e);
170
+ }
171
+ };
172
+ // 开始第一次轮询
173
+ setTimeout(executePolling, pollInterval);
174
+ });
175
+ };
176
+ }
177
+
178
+ /**
179
+ * 创建 next 函数
180
+ * @param {Object} props - 属性
181
+ * @returns {Function} next 函数
182
+ */
183
+ createNextFunction(props) {
184
+ return async (context) => {
185
+ if (typeof props?.task?.update === 'function') {
186
+ await props.task.update({ context, status: CONFIG_CONSTANTS.TASK_STATUSES.WAITING });
187
+
188
+ // 更新缓存
189
+ this.cacheManager.set(`task:${props.task.id}`, props.task, 60000);
190
+ }
191
+ return false;
192
+ };
193
+ }
194
+ }
195
+
196
+ module.exports = TaskExecutor;
@@ -0,0 +1,185 @@
1
+ const { TaskExecutionError } = require('../errors');
2
+ const { CONFIG_CONSTANTS } = require('../config');
3
+
4
+ /**
5
+ * 任务处理器模块
6
+ * 负责任务的处理逻辑,包括重试、超时等
7
+ */
8
+ class TaskProcessor {
9
+ constructor(fastify, config, models, executor, collectTaskStatistics, triggerChildTasks) {
10
+ this.fastify = fastify;
11
+ this.config = config;
12
+ this.models = models;
13
+ this.executor = executor;
14
+ this.collectTaskStatistics = collectTaskStatistics;
15
+ this.triggerChildTasks = triggerChildTasks;
16
+ }
17
+
18
+ /**
19
+ * 处理系统任务
20
+ * @param {Object} task - 任务对象
21
+ * @returns {Promise<void>}
22
+ */
23
+ async processSystemTask(task) {
24
+ await task.update({
25
+ status: CONFIG_CONSTANTS.TASK_STATUSES.RUNNING,
26
+ startedAt: new Date(),
27
+ progress: 0,
28
+ error: null,
29
+ output: null,
30
+ pollCount: 0,
31
+ pollResults: [],
32
+ completedAt: null,
33
+ context: {}
34
+ });
35
+
36
+ const addLog = props => {
37
+ return this.fastify[`${this.config.name}`].services.log(Object.assign({}, props, { taskId: task.id }));
38
+ };
39
+
40
+ // 任务超时处理
41
+ const createTimeout = ms => new Promise((_, reject) =>
42
+ setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms)
43
+ );
44
+
45
+ const executorPromise = this.executor.execute({
46
+ type: task.type,
47
+ scriptName: task.scriptName,
48
+ task,
49
+ log: addLog
50
+ });
51
+
52
+ const racePromise = this.config.taskTimeout > 0
53
+ ? Promise.race([executorPromise, createTimeout(this.config.taskTimeout)])
54
+ : executorPromise;
55
+
56
+ return racePromise
57
+ .then(async result => {
58
+ if (result === false) {
59
+ return;
60
+ }
61
+
62
+ await this.config.task[task.type]({ task, result, context: task.context });
63
+
64
+ await task.update({
65
+ status: CONFIG_CONSTANTS.TASK_STATUSES.SUCCESS,
66
+ output: result,
67
+ progress: 100,
68
+ completedAt: new Date()
69
+ });
70
+
71
+ this.collectTaskStatistics(task);
72
+
73
+ // 父任务成功后激活子任务
74
+ await this.triggerChildTasks(task);
75
+ })
76
+ .catch(async error => {
77
+ // 判断是否自动重试
78
+ const currentRetryCount = (task.retryCount || 0) + 1;
79
+ const maxRetries = task.maxRetries || 0;
80
+
81
+ if (currentRetryCount < maxRetries) {
82
+ // 指数退避:baseDelay * 2^retryCount
83
+ const baseDelay = this.config.retryBaseDelay || CONFIG_CONSTANTS.RETRY_BASE_DELAY;
84
+ const backoffDelay = baseDelay * Math.pow(2, currentRetryCount - 1);
85
+
86
+ await task.update({
87
+ status: CONFIG_CONSTANTS.TASK_STATUSES.PENDING,
88
+ retryCount: currentRetryCount,
89
+ error: this.sanitizeStackTrace(error),
90
+ startTime: new Date(Date.now() + backoffDelay),
91
+ completedAt: null
92
+ });
93
+
94
+ this.fastify.log.info(`任务 ${task.id} 第 ${currentRetryCount} 次重试,${backoffDelay}ms 后执行`);
95
+ } else {
96
+ await task.update({
97
+ status: CONFIG_CONSTANTS.TASK_STATUSES.FAILED,
98
+ error: this.sanitizeStackTrace(error),
99
+ completedAt: new Date(),
100
+ retryCount: currentRetryCount
101
+ });
102
+
103
+ this.collectTaskStatistics(task);
104
+ }
105
+ });
106
+ }
107
+
108
+ /**
109
+ * 净化错误堆栈信息
110
+ * @param {Error} error - 错误对象
111
+ * @returns {string} 净化后的堆栈信息
112
+ */
113
+ sanitizeStackTrace(error) {
114
+ if (!error || !error.stack) {
115
+ return '';
116
+ }
117
+ return error.stack.replaceAll(process.cwd(), '/server');
118
+ }
119
+
120
+ /**
121
+ * 触发子任务
122
+ * @param {Object} parentTask - 父任务
123
+ * @returns {Promise<void>}
124
+ */
125
+ async triggerChildTasks(parentTask) {
126
+ const childTasks = await this.models.task.findAll({
127
+ where: {
128
+ parentTaskId: parentTask.id,
129
+ status: CONFIG_CONSTANTS.TASK_STATUSES.PENDING
130
+ }
131
+ });
132
+
133
+ if (childTasks.length === 0) return;
134
+
135
+ this.fastify.log.info(`父任务 ${parentTask.id} 完成,激活 ${childTasks.length} 个子任务`);
136
+
137
+ for (const child of childTasks) {
138
+ if (child.runnerType === CONFIG_CONSTANTS.RUNNER_TYPES.SYSTEM) {
139
+ await this.processSystemTask(child);
140
+ }
141
+ // manual 类型子任务保持 pending,等待手动执行
142
+ }
143
+ }
144
+
145
+ /**
146
+ * 检查超时任务
147
+ * @returns {Promise<void>}
148
+ */
149
+ async checkTimeout() {
150
+ const now = new Date();
151
+ const { Op } = this.fastify.sequelize.Sequelize;
152
+
153
+ const timedOutTasks = await this.models.task.findAll({
154
+ where: {
155
+ status: { [Op.in]: [CONFIG_CONSTANTS.TASK_STATUSES.RUNNING, CONFIG_CONSTANTS.TASK_STATUSES.WAITING] },
156
+ timeout: { [Op.gt]: 0 },
157
+ startedAt: { [Op.ne]: null }
158
+ }
159
+ });
160
+
161
+ const tasksToFail = timedOutTasks.filter(task => {
162
+ const elapsed = now.getTime() - new Date(task.startedAt).getTime();
163
+ return elapsed > task.timeout * 60 * 1000;
164
+ });
165
+
166
+ if (tasksToFail.length === 0) return;
167
+
168
+ this.fastify.log.info(`检测到 ${tasksToFail.length} 个超时任务`);
169
+
170
+ for (const task of tasksToFail) {
171
+ const elapsed = now.getTime() - new Date(task.startedAt).getTime();
172
+ const prevStatus = task.status;
173
+
174
+ await task.update({
175
+ status: CONFIG_CONSTANTS.TASK_STATUSES.FAILED,
176
+ error: `任务超时:已执行 ${Math.round(elapsed / 60000)} 分钟,超过设定的 ${task.timeout} 分钟超时时间`,
177
+ completedAt: now
178
+ });
179
+
180
+ this.collectTaskStatistics(task);
181
+ }
182
+ }
183
+ }
184
+
185
+ module.exports = TaskProcessor;