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

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.
@@ -1,196 +0,0 @@
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;
@@ -1,185 +0,0 @@
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;
@@ -1,203 +0,0 @@
1
- const path = require('path');
2
- const crypto = require('node:crypto');
3
-
4
- /**
5
- * 安全验证工具类
6
- * 用于路径验证、输入验证、签名验证等安全检查
7
- */
8
- class SecurityValidator {
9
- /**
10
- * 验证脚本路径是否安全,防止路径遍历攻击
11
- * @param {string} baseDir - 基础目录
12
- * @param {string} requestedPath - 请求的路径
13
- * @returns {string} 解析后的安全路径
14
- * @throws {Error} 如果路径不安全
15
- */
16
- static validateScriptPath(baseDir, requestedPath) {
17
- if (!baseDir || !requestedPath) {
18
- throw new Error('路径参数不能为空');
19
- }
20
-
21
- // 解析为绝对路径
22
- const resolvedBaseDir = path.resolve(baseDir);
23
- const resolvedPath = path.resolve(baseDir, requestedPath);
24
-
25
- // 检查是否在基础目录内
26
- if (!resolvedPath.startsWith(resolvedBaseDir)) {
27
- throw new Error(`非法路径访问: ${requestedPath}`);
28
- }
29
-
30
- // 检查文件扩展名
31
- const ext = path.extname(resolvedPath);
32
- if (ext !== '.js') {
33
- throw new Error(`只允许 .js 文件: ${requestedPath}`);
34
- }
35
-
36
- // 检查路径中是否包含可疑字符
37
- const suspiciousChars = ['..', '~', '$'];
38
- for (const char of suspiciousChars) {
39
- if (requestedPath.includes(char)) {
40
- throw new Error(`路径包含非法字符: ${char}`);
41
- }
42
- }
43
-
44
- return resolvedPath;
45
- }
46
-
47
- /**
48
- * 验证任务类型是否安全
49
- * @param {string} taskType - 任务类型
50
- * @param {Array} allowedTypes - 允许的任务类型列表
51
- * @throws {Error} 如果任务类型不安全
52
- */
53
- static validateTaskType(taskType, allowedTypes = []) {
54
- if (!taskType || typeof taskType !== 'string') {
55
- throw new Error('任务类型必须为非空字符串');
56
- }
57
-
58
- // 检查任务类型格式
59
- if (!/^[a-zA-Z0-9_-]+$/.test(taskType)) {
60
- throw new Error(`任务类型格式无效: ${taskType}`);
61
- }
62
-
63
- // 如果有允许列表,检查是否在列表中
64
- if (allowedTypes.length > 0 && !allowedTypes.includes(taskType)) {
65
- throw new Error(`不支持的任务类型: ${taskType}`);
66
- }
67
-
68
- return taskType;
69
- }
70
-
71
- /**
72
- * 验证数值参数
73
- * @param {number} value - 要验证的值
74
- * @param {Object} options - 验证选项
75
- * @returns {number} 验证后的值
76
- * @throws {Error} 如果验证失败
77
- */
78
- static validateNumber(value, options = {}) {
79
- const {
80
- min = 0,
81
- max = Number.MAX_SAFE_INTEGER,
82
- integer = true,
83
- required = true,
84
- defaultValue = 0
85
- } = options;
86
-
87
- if (value === undefined || value === null) {
88
- if (required) {
89
- throw new Error('数值参数不能为空');
90
- }
91
- return defaultValue;
92
- }
93
-
94
- const numValue = Number(value);
95
-
96
- if (isNaN(numValue)) {
97
- throw new Error('参数必须为有效数字');
98
- }
99
-
100
- if (integer && !Number.isInteger(numValue)) {
101
- throw new Error('参数必须为整数');
102
- }
103
-
104
- if (numValue < min || numValue > max) {
105
- throw new Error(`参数必须在 ${min} 到 ${max} 之间`);
106
- }
107
-
108
- return numValue;
109
- }
110
-
111
- /**
112
- * 生成HMAC-SHA256签名
113
- * @param {Object} params - 签名参数
114
- * @returns {string} 签名结果
115
- */
116
- static generateSignature({ secret, id, data }) {
117
- if (!secret) {
118
- throw new Error('签名密钥不能为空');
119
- }
120
- if (!id) {
121
- throw new Error('签名ID不能为空');
122
- }
123
-
124
- const dataToSign = `${id}|${typeof data === 'string' ? data : JSON.stringify(data)}`;
125
- const hmac = crypto.createHmac('sha256', secret);
126
- hmac.update(dataToSign);
127
- return hmac.digest('hex');
128
- }
129
-
130
- /**
131
- * 验证HMAC-SHA256签名
132
- * @param {Object} params - 验证参数
133
- * @returns {boolean} 验证结果
134
- */
135
- static verifySignature({ secret, id, data, signature }) {
136
- try {
137
- if (!signature) {
138
- return false;
139
- }
140
-
141
- if (!secret) {
142
- // 如果没有配置密钥,则跳过签名验证(向后兼容)
143
- return true;
144
- }
145
-
146
- const expectedSignature = this.generateSignature({ secret, id, data });
147
- return signature === expectedSignature;
148
- } catch (error) {
149
- return false;
150
- }
151
- }
152
-
153
- /**
154
- * 净化错误堆栈信息,防止敏感信息泄露
155
- * @param {Error} error - 错误对象
156
- * @param {string} cwd - 当前工作目录
157
- * @returns {string} 净化后的堆栈信息
158
- */
159
- static sanitizeStackTrace(error, cwd = process.cwd()) {
160
- if (!error || !error.stack) {
161
- return '';
162
- }
163
- return error.stack.replaceAll(cwd, '/server');
164
- }
165
-
166
- /**
167
- * 验证JSON数据
168
- * @param {string} jsonString - JSON字符串
169
- * @param {*} defaultValue - 默认值
170
- * @returns {*} 解析后的JSON对象
171
- */
172
- static safeJSONParse(jsonString, defaultValue = null) {
173
- try {
174
- if (typeof jsonString === 'object') {
175
- return jsonString;
176
- }
177
- return JSON.parse(jsonString);
178
- } catch (error) {
179
- return defaultValue;
180
- }
181
- }
182
-
183
- /**
184
- * 验证并限制日志大小
185
- * @param {Array} logs - 日志数组
186
- * @param {number} maxSize - 最大日志数量
187
- * @returns {Array} 限制后的日志数组
188
- */
189
- static limitLogsSize(logs, maxSize = 100) {
190
- if (!Array.isArray(logs)) {
191
- return [];
192
- }
193
-
194
- if (logs.length <= maxSize) {
195
- return logs;
196
- }
197
-
198
- // 保留最新的 maxSize 条日志
199
- return logs.slice(-maxSize);
200
- }
201
- }
202
-
203
- module.exports = SecurityValidator;