@nest-omni/core 4.1.3-11 → 4.1.3-12

package/file-upload/providers/local-storage.provider.d.ts

@@ -0,0 +1,98 @@
+import { BatchDeleteResult, CopyResult, HealthStatus, IStorageProvider, ListResult, LocalStorageOptions, MoveResult, PreSignedUploadInfo, UploadResult } from '../interfaces/storage-provider.interface';
+import { FileBuffer } from '../interfaces/file-buffer.interface';
+import { UploadOptions } from '../interfaces/upload-options.interface';
+import { FileMetadata } from '../interfaces/file-metadata.interface';
+/**
+ * 本地文件存储提供者
+ */
+export declare class LocalStorageProvider implements IStorageProvider {
+    private readonly options;
+    name: string;
+    private readonly logger;
+    private initialized;
+    constructor(options: LocalStorageOptions);
+    /**
+     * 初始化存储配置
+     */
+    initialize(): Promise<void>;
+    /**
+     * 上传文件
+     */
+    upload(file: FileBuffer, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * 下载文件
+     */
+    download(filePath: string): Promise<FileBuffer>;
+    /**
+     * 删除文件
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * 批量删除
+     */
+    deleteBatch(paths: string[]): Promise<BatchDeleteResult>;
+    /**
+     * 检查文件是否存在
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * 获取文件元数据
+     */
+    getMetadata(filePath: string): Promise<FileMetadata>;
+    /**
+     * 获取预签名URL（本地存储不支持，返回直接URL）
+     */
+    getSignedUrl(filePath: string, expiresIn?: number): Promise<string>;
+    /**
+     * 获取预签名上传URL（本地存储不支持）
+     */
+    getSignedUploadUrl(filePath: string, expiresIn?: number, contentType?: string): Promise<PreSignedUploadInfo>;
+    /**
+     * 复制文件
+     */
+    copy(sourcePath: string, destinationPath: string): Promise<CopyResult>;
+    /**
+     * 移动文件
+     */
+    move(sourcePath: string, destinationPath: string): Promise<MoveResult>;
+    /**
+     * 列出文件
+     */
+    list(prefix?: string, limit?: number): Promise<ListResult>;
+    /**
+     * 健康检查
+     */
+    healthCheck(): Promise<HealthStatus>;
+    /**
+     * 生成文件路径
+     */
+    private generateFilePath;
+    /**
+     * 获取文件URL
+     */
+    private getFileUrl;
+    /**
+     * 计算文件哈希
+     */
+    private calculateFileHash;
+    /**
+     * 递归读取目录
+     */
+    private readDirRecursive;
+    /**
+     * 验证路径安全性，防止路径遍历攻击
+     */
+    private validatePath;
+    /**
+     * 验证文件是否在上传目录内
+     */
+    private ensurePathWithinUpload;
+    /**
+     * 根据扩展名获取 MIME 类型
+     */
+    private getMimeTypeFromExtension;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+}

package/file-upload/providers/local-storage.provider.js

@@ -0,0 +1,484 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var LocalStorageProvider_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageProvider = void 0;
+const common_1 = require("@nestjs/common");
+const file_upload_exception_1 = require("../exceptions/file-upload.exception");
+const checksum_util_1 = require("../utils/checksum.util");
+const fs = require("fs-extra");
+const path = require("path");
+const crypto = require("crypto");
+/**
+ * 本地文件存储提供者
+ */
+let LocalStorageProvider = LocalStorageProvider_1 = class LocalStorageProvider {
+    constructor(options) {
+        this.options = options;
+        this.name = 'local';
+        this.logger = new common_1.Logger(LocalStorageProvider_1.name);
+        this.initialized = false;
+    }
+    /**
+     * 初始化存储配置
+     */
+    initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.initialized) {
+                return;
+            }
+            // 确保上传目录存在
+            yield fs.ensureDir(this.options.uploadPath);
+            // 设置目录权限
+            if (this.options.dirMode) {
+                yield fs.chmod(this.options.uploadPath, parseInt(this.options.dirMode, 8));
+            }
+            this.initialized = true;
+            this.logger.log(`Local storage initialized at: ${this.options.uploadPath}`);
+        });
+    }
+    /**
+     * 上传文件
+     */
+    upload(file, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            // 生成文件路径
+            const filePath = yield this.generateFilePath(file, options);
+            const fullPath = path.join(this.options.uploadPath, filePath);
+            // 确保目录存在
+            yield fs.ensureDir(path.dirname(fullPath));
+            // 写入文件
+            yield fs.writeFile(fullPath, file.buffer);
+            // 设置文件权限
+            if (this.options.fileMode) {
+                yield fs.chmod(fullPath, parseInt(this.options.fileMode, 8));
+            }
+            // 计算文件哈希
+            const hash = yield this.calculateFileHash(fullPath);
+            // 获取文件统计信息
+            const stats = yield fs.stat(fullPath);
+            return {
+                key: filePath,
+                url: this.getFileUrl(filePath),
+                etag: hash,
+                size: stats.size,
+                uploadedAt: new Date(),
+                metadata: {
+                    originalName: file.originalName,
+                    mimeType: file.mimeType,
+                    hash,
+                },
+            };
+        });
+    }
+    /**
+     * 下载文件
+     */
+    download(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            // 验证路径安全性
+            const normalizedPath = this.validatePath(filePath);
+            // 构建完整路径
+            const fullPath = path.join(this.options.uploadPath, normalizedPath);
+            // 确保最终路径在上传目录内
+            this.ensurePathWithinUpload(fullPath);
+            try {
+                // 直接尝试读取文件，避免 TOCTOU 竞态条件
+                const buffer = yield fs.readFile(fullPath);
+                const stats = yield fs.stat(fullPath);
+                // 根据扩展名猜测 MIME 类型
+                const mimeType = this.getMimeTypeFromExtension(normalizedPath);
+                return {
+                    buffer,
+                    size: stats.size,
+                    mimeType,
+                    originalName: path.basename(normalizedPath),
+                };
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    throw new file_upload_exception_1.StorageException('download', new Error(`File not found: ${filePath}`));
+                }
+                throw new file_upload_exception_1.StorageException('download', error);
+            }
+        });
+    }
+    /**
+     * 删除文件
+     */
+    delete(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const fullPath = path.join(this.options.uploadPath, filePath);
+            if (yield fs.pathExists(fullPath)) {
+                yield fs.unlink(fullPath);
+                this.logger.log(`File deleted: ${filePath}`);
+            }
+        });
+    }
+    /**
+     * 批量删除
+     */
+    deleteBatch(paths) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const deleted = [];
+            const failed = [];
+            for (const filePath of paths) {
+                try {
+                    yield this.delete(filePath);
+                    deleted.push(filePath);
+                }
+                catch (error) {
+                    failed.push({
+                        path: filePath,
+                        error: error.message,
+                    });
+                }
+            }
+            return {
+                deleted,
+                failed,
+                total: paths.length,
+            };
+        });
+    }
+    /**
+     * 检查文件是否存在
+     */
+    exists(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const fullPath = path.join(this.options.uploadPath, filePath);
+            return fs.pathExists(fullPath);
+        });
+    }
+    /**
+     * 获取文件元数据
+     */
+    getMetadata(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const fullPath = path.join(this.options.uploadPath, filePath);
+            if (!(yield fs.pathExists(fullPath))) {
+                throw new file_upload_exception_1.StorageException('getMetadata', new Error(`File not found: ${filePath}`));
+            }
+            const stats = yield fs.stat(fullPath);
+            const hash = yield this.calculateFileHash(fullPath);
+            return {
+                size: stats.size,
+                mimeType: this.getMimeTypeFromExtension(filePath),
+                lastModified: stats.mtime,
+                etag: hash,
+                extension: path.extname(filePath),
+                metadata: {
+                    created: stats.birthtime,
+                    modified: stats.mtime,
+                    accessed: stats.atime,
+                },
+            };
+        });
+    }
+    /**
+     * 获取预签名URL（本地存储不支持，返回直接URL）
+     */
+    getSignedUrl(filePath, expiresIn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.getFileUrl(filePath);
+        });
+    }
+    /**
+     * 获取预签名上传URL（本地存储不支持）
+     */
+    getSignedUploadUrl(filePath, expiresIn, contentType) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new file_upload_exception_1.StorageException('getSignedUploadUrl', new Error('Pre-signed upload URL not supported for local storage'));
+        });
+    }
+    /**
+     * 复制文件
+     */
+    copy(sourcePath, destinationPath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const sourceFullPath = path.join(this.options.uploadPath, sourcePath);
+            const destFullPath = path.join(this.options.uploadPath, destinationPath);
+            if (!(yield fs.pathExists(sourceFullPath))) {
+                throw new file_upload_exception_1.StorageException('copy', new Error(`Source file not found: ${sourcePath}`));
+            }
+            // 确保目标目录存在
+            yield fs.ensureDir(path.dirname(destFullPath));
+            // 复制文件
+            yield fs.copy(sourceFullPath, destFullPath);
+            const stats = yield fs.stat(destFullPath);
+            const hash = yield this.calculateFileHash(destFullPath);
+            return {
+                destinationPath,
+                size: stats.size,
+                copiedAt: new Date(),
+                etag: hash,
+            };
+        });
+    }
+    /**
+     * 移动文件
+     */
+    move(sourcePath, destinationPath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const sourceFullPath = path.join(this.options.uploadPath, sourcePath);
+            const destFullPath = path.join(this.options.uploadPath, destinationPath);
+            if (!(yield fs.pathExists(sourceFullPath))) {
+                throw new file_upload_exception_1.StorageException('move', new Error(`Source file not found: ${sourcePath}`));
+            }
+            // 确保目标目录存在
+            yield fs.ensureDir(path.dirname(destFullPath));
+            // 移动文件
+            yield fs.move(sourceFullPath, destFullPath);
+            const stats = yield fs.stat(destFullPath);
+            const hash = yield this.calculateFileHash(destFullPath);
+            return {
+                destinationPath,
+                size: stats.size,
+                movedAt: new Date(),
+                etag: hash,
+            };
+        });
+    }
+    /**
+     * 列出文件
+     */
+    list(prefix, limit) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const searchPath = prefix
+                ? path.join(this.options.uploadPath, prefix)
+                : this.options.uploadPath;
+            const files = [];
+            if (yield fs.pathExists(searchPath)) {
+                const entries = yield this.readDirRecursive(searchPath);
+                for (const entry of entries) {
+                    const relativePath = path.relative(this.options.uploadPath, entry);
+                    const stats = yield fs.stat(entry);
+                    if (stats.isFile()) {
+                        const hash = yield this.calculateFileHash(entry);
+                        files.push({
+                            key: relativePath,
+                            size: stats.size,
+                            lastModified: stats.mtime,
+                            etag: hash,
+                        });
+                        if (limit && files.length >= limit) {
+                            break;
+                        }
+                    }
+                }
+            }
+            return {
+                files,
+                hasMore: false,
+                totalCount: files.length,
+            };
+        });
+    }
+    /**
+     * 健康检查
+     */
+    healthCheck() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const startTime = Date.now();
+            try {
+                yield this.ensureInitialized();
+                // 检查目录是否可写
+                const testFile = path.join(this.options.uploadPath, '.health-check');
+                yield fs.writeFile(testFile, 'test');
+                yield fs.unlink(testFile);
+                return {
+                    healthy: true,
+                    responseTime: Date.now() - startTime,
+                    details: {
+                        uploadPath: this.options.uploadPath,
+                        writable: true,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    healthy: false,
+                    responseTime: Date.now() - startTime,
+                    error: error.message,
+                    details: {
+                        uploadPath: this.options.uploadPath,
+                        writable: false,
+                    },
+                };
+            }
+        });
+    }
+    /**
+     * 生成文件路径
+     */
+    generateFilePath(file, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const ext = path.extname(file.originalName);
+            const basename = path.basename(file.originalName, ext);
+            // 生成文件名
+            const filename = options.filename
+                ? `${options.filename}${ext}`
+                : `${basename}-${Date.now()}${ext}`;
+            // 根据配置生成子目录
+            let subdirectory = '';
+            if (this.options.subdirectoryFormat) {
+                switch (this.options.subdirectoryFormat) {
+                    case 'date': {
+                        const now = new Date();
+                        const year = now.getFullYear();
+                        const month = String(now.getMonth() + 1).padStart(2, '0');
+                        const day = String(now.getDate()).padStart(2, '0');
+                        subdirectory = `${year}/${month}/${day}`;
+                        break;
+                    }
+                    case 'hash': {
+                        const hash = crypto.createHash('md5').update(filename).digest('hex');
+                        subdirectory = `${hash.substring(0, 2)}/${hash.substring(2, 4)}`;
+                        break;
+                    }
+                    case 'none':
+                    default:
+                        break;
+                }
+            }
+            // 组合路径
+            const relativePath = options.path || '';
+            return path.join(relativePath, subdirectory, filename);
+        });
+    }
+    /**
+     * 获取文件URL
+     */
+    getFileUrl(filePath) {
+        if (this.options.baseUrl) {
+            return `${this.options.baseUrl}/${filePath}`;
+        }
+        return filePath;
+    }
+    /**
+     * 计算文件哈希
+     */
+    calculateFileHash(fullPath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return checksum_util_1.ChecksumUtil.calculate(fullPath, 'md5');
+        });
+    }
+    /**
+     * 递归读取目录
+     */
+    readDirRecursive(dir) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entries = yield fs.readdir(dir, { withFileTypes: true });
+            const files = [];
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    const subFiles = yield this.readDirRecursive(fullPath);
+                    files.push(...subFiles);
+                }
+                else {
+                    files.push(fullPath);
+                }
+            }
+            return files;
+        });
+    }
+    /**
+     * 验证路径安全性，防止路径遍历攻击
+     */
+    validatePath(filePath) {
+        // 规范化路径
+        const normalizedPath = path.normalize(filePath);
+        // 检查是否为绝对路径
+        if (path.isAbsolute(normalizedPath)) {
+            throw new file_upload_exception_1.StorageException('download', new Error('Absolute paths not allowed'));
+        }
+        // 检查是否包含向上目录遍历
+        if (normalizedPath.includes('..')) {
+            throw new file_upload_exception_1.StorageException('download', new Error('Path traversal not allowed'));
+        }
+        // 确保路径不包含危险字符
+        if (normalizedPath.includes('\0')) {
+            throw new file_upload_exception_1.StorageException('download', new Error('Null character in path'));
+        }
+        return normalizedPath;
+    }
+    /**
+     * 验证文件是否在上传目录内
+     */
+    ensurePathWithinUpload(fullPath) {
+        const resolvedUploadPath = path.resolve(this.options.uploadPath);
+        const resolvedFullPath = path.resolve(fullPath);
+        if (!resolvedFullPath.startsWith(resolvedUploadPath)) {
+            throw new file_upload_exception_1.StorageException('download', new Error('Path traversal detected: file is outside upload directory'));
+        }
+    }
+    /**
+     * 根据扩展名获取 MIME 类型
+     */
+    getMimeTypeFromExtension(filename) {
+        const ext = path.extname(filename).toLowerCase();
+        const mimeTypes = {
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.png': 'image/png',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+            '.svg': 'image/svg+xml',
+            '.pdf': 'application/pdf',
+            '.doc': 'application/msword',
+            '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            '.xls': 'application/vnd.ms-excel',
+            '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            '.txt': 'text/plain',
+            '.csv': 'text/csv',
+            '.json': 'application/json',
+            '.xml': 'application/xml',
+            '.zip': 'application/zip',
+            '.mp4': 'video/mp4',
+            '.mp3': 'audio/mpeg',
+        };
+        return mimeTypes[ext] || 'application/octet-stream';
+    }
+    /**
+     * 确保已初始化
+     */
+    ensureInitialized() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.initialized) {
+                yield this.initialize();
+            }
+        });
+    }
+};
+exports.LocalStorageProvider = LocalStorageProvider;
+exports.LocalStorageProvider = LocalStorageProvider = LocalStorageProvider_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], LocalStorageProvider);

package/file-upload/providers/s3-storage.provider.d.ts

@@ -0,0 +1,87 @@
+import { BatchDeleteResult, CopyResult, HealthStatus, IStorageProvider, ListResult, MoveResult, PreSignedUploadInfo, S3StorageOptions, UploadResult } from '../interfaces/storage-provider.interface';
+import { FileBuffer } from '../interfaces/file-buffer.interface';
+import { UploadOptions } from '../interfaces/upload-options.interface';
+import { FileMetadata } from '../interfaces/file-metadata.interface';
+/**
+ * AWS S3 存储提供者
+ * 使用动态导入，只在实际使用时加载 AWS SDK
+ */
+export declare class S3StorageProvider implements IStorageProvider {
+    private readonly options;
+    name: string;
+    private readonly logger;
+    private initialized;
+    private s3Client;
+    private S3Commands;
+    private s3GetSignedUrl;
+    constructor(options: S3StorageOptions);
+    /**
+     * 初始化存储配置
+     * 动态导入 AWS S3 SDK
+     */
+    initialize(): Promise<void>;
+    /**
+     * 上传文件
+     */
+    upload(file: FileBuffer, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * 下载文件
+     */
+    download(key: string): Promise<FileBuffer>;
+    /**
+     * 删除文件
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 批量删除
+     */
+    deleteBatch(keys: string[]): Promise<BatchDeleteResult>;
+    /**
+     * 检查文件是否存在
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 获取文件元数据
+     */
+    getMetadata(key: string): Promise<FileMetadata>;
+    /**
+     * 获取预签名URL（下载）
+     */
+    getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * 获取预签名上传URL
+     */
+    getSignedUploadUrl(key: string, expiresIn?: number, contentType?: string): Promise<PreSignedUploadInfo>;
+    /**
+     * 复制文件
+     */
+    copy(sourceKey: string, destinationKey: string): Promise<CopyResult>;
+    /**
+     * 移动文件（复制后删除）
+     */
+    move(sourceKey: string, destinationKey: string): Promise<MoveResult>;
+    /**
+     * 列出文件
+     */
+    list(prefix?: string, limit?: number): Promise<ListResult>;
+    /**
+     * 健康检查
+     */
+    healthCheck(): Promise<HealthStatus>;
+    /**
+     * 生成文件 Key
+     */
+    private generateKey;
+    /**
+     * 获取文件访问 URL
+     */
+    private getFileUrl;
+    /**
+     * 将流转换为 Buffer（带超时和大小限制）
+     */
+    private streamToBuffer;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+}