@zucker-framework/storage 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import { ReadStream } from 'fs';
+import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+
+interface UploadOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    acl?: 'private' | 'public-read';
+}
+interface UploadResult {
+    key: string;
+    /**
+     * Stable public URL when the provider is configured for public delivery.
+     * Private providers may return an empty string; callers must persist `key`
+     * and request a short-lived URL with `getDownloadUrl` when needed.
+     */
+    url: string;
+    size: number;
+}
+interface FileInfo {
+    key: string;
+    size: number;
+    lastModified: Date;
+    contentType?: string;
+    /**
+     * 文件 MD5 哈希 — 对应 jetlinks FileInfo.md5
+     * 用于文件去重和完整性校验
+     */
+    md5?: string;
+    /**
+     * 文件 SHA-256 哈希 — 对应 jetlinks FileInfo.sha256
+     */
+    sha256?: string;
+}
+type StorageProviderType = 'local' | 's3' | 'webdav';
+/**
+ * 文件上传校验配置
+ * 支持后缀名白名单/黑名单和 MIME 类型白名单/黑名单
+ */
+interface FileUploadValidation {
+    /** 允许的文件后缀（不含 .），设置后仅这些后缀的文件可上传 */
+    allowExtensions?: string[];
+    /** 拒绝的文件后缀（不含 .） */
+    denyExtensions?: string[];
+    /** 允许的 MIME 类型 */
+    allowMimeTypes?: string[];
+    /** 拒绝的 MIME 类型 */
+    denyMimeTypes?: string[];
+    /** 最大文件大小（字节），0 表示不限制 */
+    maxFileSize?: number;
+}
+/**
+ * Default dangerous file extensions that should be blocked unless explicitly allowed.
+ */
+declare const DANGEROUS_EXTENSIONS: readonly string[];
+/**
+ * 文件名安全清洗
+ *
+ * 文件上传安全规则：
+ * 1. Unicode NFKC 规范化 — 将不同编码形式的字符统一
+ *    （如全角字符 `＼` → `\`），防止绕过路径检查
+ * 2. 将反斜杠统一为正斜杠后仅提取文件名部分
+ * 3. 仅允许字母数字和 ._- 组成的文件名用于原始名保留
+ *
+ * @param fileName 原始文件名
+ * @returns 清洗后的安全文件名
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * 检查文件名是否为安全的原始文件名（仅字母数字 ._-）
+ */
+declare function isSafeOriginalFileName(name: string): boolean;
+/**
+ * 判断文件是否被拒绝上传（基于后缀名与 MIME 类型校验）
+ * 根据文件名、扩展名和大小检查上传限制。
+ *
+ * @param fileName 文件名
+ * @param mimeType MIME 类型（可选）
+ * @param validation 校验配置
+ * @param fileSize 文件大小（字节，可选），用于最大文件大小校验
+ */
+declare function isFileDenied(fileName: string, mimeType: string | undefined, validation: FileUploadValidation, fileSize?: number): boolean;
+/**
+ * 生成基于日期的存储路径
+ * 按 YYYYMMDD 归档，避免单目录文件过多
+ */
+declare function generateDateBasedKey(originalName: string, options?: {
+    useOriginalFileName?: boolean;
+    prefix?: string;
+}): string;
+/**
+ * Chunk upload progress — tracks multipart/chunked upload state.
+ */
+/**
+ * POSIX 文件权限配置
+ *
+ * 使用 Node.js 的 fs.chmod 模式数字设置文件权限。
+ *
+ * @example
+ * ```ts
+ * // 所有者可读写，同组用户可读
+ * const permissions: PosixFilePermissions = { mode: 0o640 };
+ * ```
+ */
+interface PosixFilePermissions {
+    /**
+     * POSIX 权限模式（八进制），如 0o644, 0o755
+     * 使用标准 POSIX 权限位
+     */
+    mode: number;
+}
+interface ChunkUploadState {
+    /** Upload session ID */
+    uploadId: string;
+    /** Target storage key */
+    key: string;
+    /** Total number of chunks expected */
+    totalChunks: number;
+    /** Chunks received so far */
+    receivedChunks: number[];
+    /** Total file size in bytes (if known) */
+    totalSize?: number;
+    /** Whether the upload is complete */
+    complete: boolean;
+}
+interface FileManager {
+    readonly providerType: StorageProviderType;
+    isConfigured(): boolean;
+    upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    download(key: string): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getPublicUrl(key: string): Promise<string>;
+    getDownloadUrl(key: string, expiresIn?: number): Promise<string>;
+    list(prefix: string): Promise<FileInfo[]>;
+    /**
+     * 获取单个文件的元信息
+     * 返回 undefined 表示文件不存在
+     */
+    getFileInfo?(key: string): Promise<FileInfo | undefined>;
+    /**
+     * 从指定偏移量开始读取文件 — 对应 jetlinks FileManager.read(id, position)
+     *
+     * 支持断点续传和范围读取场景。
+     * @param key 存储键
+     * @param position 起始偏移量（字节）
+     */
+    downloadRange?(key: string, position: number, length?: number): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    /**
+     * 复制文件
+     */
+    copy?(sourceKey: string, destKey: string): Promise<void>;
+    /**
+     * 移动/重命名文件
+     */
+    move?(sourceKey: string, destKey: string): Promise<void>;
+    /**
+     * Initialize a chunked/multipart upload session.
+     *
+     * @param key Target storage key
+     * @param totalChunks Total number of chunks expected
+     * @param totalSize Total file size in bytes (optional)
+     * @returns Upload session ID
+     */
+    initChunkedUpload?(key: string, totalChunks: number, totalSize?: number): Promise<string>;
+    /**
+     * Upload a single chunk in a multipart upload.
+     *
+     * @param uploadId Upload session ID from initChunkedUpload
+     * @param chunkIndex Zero-based chunk index
+     * @param buffer Chunk data
+     */
+    uploadChunk?(uploadId: string, chunkIndex: number, buffer: Buffer): Promise<void>;
+    /**
+     * Complete a chunked upload, assembling all chunks into the final file.
+     *
+     * @param uploadId Upload session ID
+     * @param options Optional upload options (contentType, metadata, acl)
+     * @returns Upload result with final URL
+     */
+    completeChunkedUpload?(uploadId: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Abort a chunked upload, cleaning up any temporary chunks.
+     *
+     * @param uploadId Upload session ID
+     */
+    abortChunkedUpload?(uploadId: string): Promise<void>;
+    /**
+     * 便捷文件保存
+     *
+     * 自动根据文件类型生成日期归档路径并保存，简化调用方使用。
+     * 内部调用 generateDateBasedKey + upload。
+     *
+     * @param buffer 文件内容
+     * @param fileType 文件类型/后缀（如 "png", ".jpg"）
+     * @param options 上传选项
+     * @returns 上传结果
+     */
+    saveFile?(buffer: Buffer, fileType: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * 应用 POSIX 文件权限
+     *
+     * 在文件写入后设置 POSIX 权限（仅对本地存储有效，S3/WebDAV 忽略）。
+     * 这里使用 Node.js fs.chmodSync() 实现。
+     *
+     * @param key 存储键
+     * @param permissions POSIX 权限配置
+     */
+    applyFilePermission?(key: string, permissions: PosixFilePermissions): Promise<void>;
+}
+
+declare class LocalFileStorage implements FileManager {
+    private readonly logger;
+    readonly providerType: "local";
+    private readonly basePath;
+    private readonly baseUrl;
+    /** Active chunked upload sessions */
+    private readonly chunkedUploads;
+    constructor(options: {
+        basePath: string;
+        baseUrl?: string;
+    });
+    isConfigured(): boolean;
+    upload(buffer: Buffer, key: string, _options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    download(key: string): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getPublicUrl(key: string): Promise<string>;
+    getDownloadUrl(key: string): Promise<string>;
+    list(prefix: string): Promise<FileInfo[]>;
+    downloadRange(key: string, position: number, length?: number): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    getFileInfo(key: string): Promise<FileInfo | undefined>;
+    copy(sourceKey: string, destKey: string): Promise<void>;
+    move(sourceKey: string, destKey: string): Promise<void>;
+    initChunkedUpload(key: string, totalChunks: number, totalSize?: number): Promise<string>;
+    uploadChunk(uploadId: string, chunkIndex: number, buffer: Buffer): Promise<void>;
+    completeChunkedUpload(uploadId: string, _options?: UploadOptions): Promise<UploadResult>;
+    abortChunkedUpload(uploadId: string): Promise<void>;
+    /**
+     * 便捷文件保存
+     * 自动根据文件类型生成日期归档路径并保存。
+     */
+    saveFile(buffer: Buffer, fileType: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * 应用 POSIX 文件权限
+     * 使用 fs.chmodSync 设置文件权限，非 POSIX 系统静默忽略错误。
+     */
+    applyFilePermission(key: string, permissions: PosixFilePermissions): Promise<void>;
+    /**
+     * Resolve a storage key to an absolute file path.
+     * Validates against path traversal attacks (e.g. "../../../etc/passwd").
+     */
+    private resolvePath;
+    private buildUrl;
+}
+
+type S3ObjectAclMode = 'object-acl' | 'none';
+type S3UploadUrlMode = 'signed' | 'public-only';
+interface S3StorageOptions {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region?: string;
+    endpoint?: string;
+    bucket: string;
+    publicUrl?: string;
+    forcePathStyle?: boolean;
+    objectAclMode?: S3ObjectAclMode;
+    uploadUrlMode?: S3UploadUrlMode;
+    signedUrlExpiresIn?: number;
+}
+declare class S3Storage implements FileManager, OnModuleDestroy {
+    private readonly logger;
+    private readonly client;
+    private readonly bucket;
+    private readonly publicUrl;
+    private readonly objectAclMode;
+    private readonly uploadUrlMode;
+    private readonly signedUrlExpiresIn;
+    readonly providerType: "s3";
+    constructor(options: S3StorageOptions);
+    onModuleDestroy(): void;
+    isConfigured(): boolean;
+    upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    download(key: string): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getPublicUrl(key: string): Promise<string>;
+    getDownloadUrl(key: string, expiresIn?: number): Promise<string>;
+    list(prefix: string): Promise<FileInfo[]>;
+    getFileInfo(key: string): Promise<FileInfo | undefined>;
+    copy(sourceKey: string, destKey: string): Promise<void>;
+    move(sourceKey: string, destKey: string): Promise<void>;
+}
+
+interface WebDavStorageOptions {
+    /** WebDAV 服务地址，如 https://nextcloud.example.com/remote.php/dav/files/user */
+    url: string;
+    username: string;
+    password: string;
+    /** 公开访问 URL 前缀（可选） */
+    publicUrl?: string;
+    /** 基础路径前缀（可选，默认 '/'） */
+    basePath?: string;
+}
+declare class WebDavStorage implements FileManager {
+    private readonly logger;
+    private clientPromise?;
+    private readonly publicUrl;
+    private readonly basePath;
+    private readonly directoryPromises;
+    readonly providerType: "webdav";
+    private readonly options;
+    constructor(options: WebDavStorageOptions);
+    private initClient;
+    private getClient;
+    isConfigured(): boolean;
+    upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    download(key: string): Promise<{
+        stream: ReadStream;
+        size: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getPublicUrl(key: string): Promise<string>;
+    getDownloadUrl(key: string): Promise<string>;
+    list(prefix: string): Promise<FileInfo[]>;
+    getFileInfo(key: string): Promise<FileInfo | undefined>;
+    copy(sourceKey: string, destKey: string): Promise<void>;
+    move(sourceKey: string, destKey: string): Promise<void>;
+    /**
+     * 递归创建目录
+     */
+    private ensureDirectory;
+    private createDirectoryIfMissing;
+    private resolvePath;
+    private stripBasePath;
+    private buildUrl;
+}
+
+/**
+ * 文件生命周期管理器。
+ *
+ * 支持文件过期自动清理、临时文件管理、存储配额检查。
+ */
+interface FileLifecyclePolicy {
+    /** 文件最大保留时间（毫秒），0 表示永久 */
+    maxAge?: number;
+    /** 文件最大数量，超出后按 FIFO 清理 */
+    maxCount?: number;
+    /** 文件最大总大小（字节），超出后按 FIFO 清理 */
+    maxTotalSize?: number;
+    /** 文件路径前缀匹配（用于作用域限定） */
+    pathPrefix?: string;
+}
+interface FileMetadata {
+    key: string;
+    size: number;
+    createdAt: number;
+    lastAccessedAt?: number;
+    contentType?: string;
+    tags?: Record<string, string>;
+}
+interface LifecycleResult {
+    deletedCount: number;
+    freedBytes: number;
+    reason: 'expired' | 'count_exceeded' | 'size_exceeded';
+}
+declare class FileLifecycleManager {
+    private readonly logger;
+    private readonly policies;
+    /** 注册一个生命周期策略 */
+    registerPolicy(policy: FileLifecyclePolicy): void;
+    /** 获取所有已注册策略 */
+    getPolicies(): FileLifecyclePolicy[];
+    /**
+     * 评估文件列表，返回需要清理的文件 keys。
+     * 调用方负责实际删除操作。
+     */
+    evaluate(files: FileMetadata[], policy?: FileLifecyclePolicy): string[];
+}
+
+declare const FILE_MANAGER = "FILE_MANAGER";
+type StorageModuleOptions = {
+    provider: 'local';
+    basePath: string;
+    baseUrl?: string;
+} | ({
+    provider: 's3';
+} & S3StorageOptions) | ({
+    provider: 'webdav';
+} & WebDavStorageOptions);
+interface StorageModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    useFactory?: (...args: unknown[]) => StorageModuleOptions | Promise<StorageModuleOptions>;
+    useClass?: Type<StorageModuleOptionsFactory>;
+    useExisting?: Type<StorageModuleOptionsFactory>;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+interface StorageModuleOptionsFactory {
+    createStorageOptions(): StorageModuleOptions | Promise<StorageModuleOptions>;
+}
+declare class ZuckerStorageModule {
+    static forRoot(options: StorageModuleOptions): DynamicModule;
+    static forRootAsync(options: StorageModuleAsyncOptions): DynamicModule;
+    private static createFileManager;
+    private static createAsyncProviders;
+}
+
+declare enum StorageProvider {
+    LOCAL = "LOCAL",
+    S3 = "S3",
+    WEBDAV = "WEBDAV"
+}
+
+export { type ChunkUploadState, DANGEROUS_EXTENSIONS, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, type UploadOptions, type UploadResult, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, isFileDenied, isSafeOriginalFileName, sanitizeFileName };