@zucker-framework/storage 1.0.0 → 1.0.5

package/dist/index.js

@@ -31,18 +31,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BufferedFileManagerStore: () => BufferedFileManagerStore,
   DANGEROUS_EXTENSIONS: () => DANGEROUS_EXTENSIONS,
   FILE_MANAGER: () => FILE_MANAGER,
   FileLifecycleManager: () => FileLifecycleManager,
   LocalFileStorage: () => LocalFileStorage,
   S3Storage: () => S3Storage,
   StorageProvider: () => StorageProvider,
+  StorageTransferError: () => StorageTransferError,
+  UnavailableFileManager: () => UnavailableFileManager,
   WebDavStorage: () => WebDavStorage,
   ZuckerStorageModule: () => ZuckerStorageModule,
   generateDateBasedKey: () => generateDateBasedKey,
+  hydrateStorageUrls: () => hydrateStorageUrls,
   isFileDenied: () => isFileDenied,
   isSafeOriginalFileName: () => isSafeOriginalFileName,
-  sanitizeFileName: () => sanitizeFileName
+  sanitizeFileName: () => sanitizeFileName,
+  transferVerifiedObject: () => transferVerifiedObject,
+  verifyStoredObject: () => verifyStoredObject
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -431,6 +437,7 @@ LocalFileStorage = _ts_decorate([
 var import_common2 = require("@nestjs/common");
 var import_client_s3 = require("@aws-sdk/client-s3");
 var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+var import_node_stream = require("stream");
 function _ts_decorate2(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") {
@@ -523,6 +530,9 @@ var S3Storage = class _S3Storage {
     if (!response.Body) {
       throw new Error("Stored object response had no body");
     }
+    if (!(response.Body instanceof import_node_stream.Readable)) {
+      throw new Error("Stored object response must be a Node readable stream");
+    }
     return {
       stream: response.Body,
       size: response.ContentLength ?? 0
@@ -629,7 +639,8 @@ __name(encodeKeyPath, "encodeKeyPath");
 // src/webdav-storage.ts
 var import_common3 = require("@nestjs/common");
 var path2 = __toESM(require("path"));
-var import_stream = require("stream");
+var import_node_stream2 = require("stream");
+var import_promises = require("stream/promises");
 function _ts_decorate3(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") {
@@ -662,7 +673,7 @@ var WebDavStorage = class _WebDavStorage {
   providerType = "webdav";
   options;
   constructor(options) {
-    if (!options.url || !options.username || !options.password) {
+    if (!options.url || !options.allowAnonymous && (!options.username || !options.password)) {
       throw new Error("WebDAV url, username and password are required");
     }
     this.options = options;
@@ -689,7 +700,7 @@ var WebDavStorage = class _WebDavStorage {
     const remotePath = this.resolvePath(key);
     const parentDir = remotePath.substring(0, remotePath.lastIndexOf("/"));
     if (parentDir && parentDir !== "/") {
-      await this.ensureDirectory(parentDir);
+      await this.ensureRemoteDirectory(parentDir);
     }
     await client.putFileContents(remotePath, buffer, {
       contentLength: buffer.length,
@@ -705,21 +716,87 @@ var WebDavStorage = class _WebDavStorage {
     };
   }
   async uploadStream(stream, key, options) {
-    const chunks = [];
-    for await (const chunk of stream) {
-      chunks.push(Buffer.from(chunk));
+    const controller = new AbortController();
+    const abort = /* @__PURE__ */ __name(() => controller.abort(options?.signal?.reason), "abort");
+    options?.signal?.addEventListener("abort", abort, {
+      once: true
+    });
+    if (options?.signal?.aborted) abort();
+    let size = 0;
+    const counter = new import_node_stream2.Transform({
+      transform(chunk, _encoding, callback) {
+        size += chunk.length;
+        callback(null, chunk);
+      }
+    });
+    let transfer;
+    let pumping;
+    const sourceError = /* @__PURE__ */ __name((error) => controller.abort(error), "sourceError");
+    stream.on("error", sourceError);
+    (0, import_node_stream2.addAbortSignal)(controller.signal, stream);
+    try {
+      controller.signal.throwIfAborted();
+      const client = await this.getClient();
+      const remotePath = this.resolvePath(key);
+      await this.ensureRemoteDirectory(path2.posix.dirname(remotePath), controller.signal);
+      controller.signal.throwIfAborted();
+      transfer = client.putFileContents(remotePath, counter, {
+        overwrite: true,
+        contentLength: false,
+        signal: controller.signal,
+        headers: options?.contentType ? {
+          "Content-Type": options.contentType
+        } : void 0
+      });
+      pumping = (0, import_promises.pipeline)(stream, counter, {
+        signal: controller.signal
+      });
+      await Promise.all([
+        transfer,
+        pumping
+      ]);
+      return {
+        key,
+        url: this.buildUrl(key),
+        size
+      };
+    } catch (error) {
+      controller.abort(error);
+      stream.destroy(error instanceof Error ? error : new Error("Storage upload failed"));
+      counter.destroy();
+      await Promise.allSettled([
+        transfer,
+        pumping,
+        (0, import_promises.finished)(stream, {
+          cleanup: true
+        })
+      ]);
+      throw error;
+    } finally {
+      options?.signal?.removeEventListener("abort", abort);
+      stream.off("error", sourceError);
     }
-    return this.upload(Buffer.concat(chunks), key, options);
   }
-  async download(key) {
+  async download(key, options) {
+    options?.signal?.throwIfAborted();
     const client = await this.getClient();
     const remotePath = this.resolvePath(key);
-    const stat = await client.stat(remotePath);
-    const buffer = await client.getFileContents(remotePath);
-    const readable = import_stream.Readable.from(buffer);
+    const stat = await client.stat(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (stat.type !== "file") throw new Error("Remote path is not a file");
+    options?.signal?.throwIfAborted();
+    const stream = client.createReadStream(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (options?.signal) (0, import_node_stream2.addAbortSignal)(options.signal, stream);
     return {
-      stream: readable,
-      size: stat.size ?? buffer.length
+      stream,
+      size: stat.size
     };
   }
   async delete(key) {
@@ -744,22 +821,26 @@ var WebDavStorage = class _WebDavStorage {
   async getDownloadUrl(key) {
     return this.getPublicUrl(key);
   }
-  async list(prefix) {
+  async list(prefix, options = {}) {
     const client = await this.getClient();
     const remotePath = this.resolvePath(prefix);
     try {
       const items = await client.getDirectoryContents(remotePath, {
-        deep: true
+        deep: options.deep ?? true
       });
-      return items.filter((item) => item.type === "file").map((item) => ({
+      return items.filter((item) => item.type === "file" || options.includeDirectories).map((item) => ({
         key: this.stripBasePath(item.filename),
+        type: item.type,
+        filename: item.filename,
+        basename: item.basename,
+        lastmod: item.lastmod,
         size: item.size ?? 0,
         lastModified: new Date(item.lastmod ?? Date.now()),
         contentType: item.mime
       }));
     } catch (error) {
       const err = error;
-      if (err.status === 404) return [];
+      if (err.status === 404 && options.missing !== "throw") return [];
       throw error;
     }
   }
@@ -804,7 +885,12 @@ var WebDavStorage = class _WebDavStorage {
   /**
   * 递归创建目录
   */
-  async ensureDirectory(dirPath) {
+  /** Accepts a storage key, with the same traversal protection as upload. */
+  async ensureDirectory(key) {
+    return this.ensureRemoteDirectory(this.resolvePath(key));
+  }
+  async ensureRemoteDirectory(dirPath, signal) {
+    if (signal) return this.createDirectoryIfMissing(dirPath, signal);
     const inflight = this.directoryPromises.get(dirPath);
     if (inflight) return inflight;
     const creation = this.createDirectoryIfMissing(dirPath);
@@ -817,21 +903,35 @@ var WebDavStorage = class _WebDavStorage {
       }
     }
   }
-  async createDirectoryIfMissing(dirPath) {
+  async createDirectoryIfMissing(dirPath, signal) {
+    signal?.throwIfAborted();
     const client = await this.getClient();
-    if (await client.exists(dirPath)) return;
+    if (await client.exists(dirPath, ...signal ? [
+      {
+        signal
+      }
+    ] : [])) return;
     const parent = dirPath.substring(0, dirPath.lastIndexOf("/"));
     if (parent && parent !== "/") {
-      await this.ensureDirectory(parent);
+      await this.ensureRemoteDirectory(parent, signal);
     }
     try {
-      await client.createDirectory(dirPath);
+      signal?.throwIfAborted();
+      await client.createDirectory(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : []);
     } catch (error) {
       const status = error.status;
       if ([
         405,
         409
-      ].includes(status ?? 0) && await client.exists(dirPath)) return;
+      ].includes(status ?? 0) && await client.exists(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : [])) return;
       throw error;
     }
   }
@@ -1057,6 +1157,198 @@ ZuckerStorageModule = _ts_decorate5([
   (0, import_common5.Module)({})
 ], ZuckerStorageModule);
 
+// src/storage-url-hydrator.ts
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+__name(isPlainRecord, "isPlainRecord");
+async function hydrateStorageUrls(value, options) {
+  const signedUrls = /* @__PURE__ */ new Map();
+  const hydrate = /* @__PURE__ */ __name(async (current) => {
+    if (Array.isArray(current)) return Promise.all(current.map(hydrate));
+    if (!isPlainRecord(current)) return current;
+    const entries = await Promise.all(Object.entries(current).map(async ([key2, nested]) => [
+      key2,
+      await hydrate(nested)
+    ]));
+    const result = Object.fromEntries(entries);
+    const key = result[options.storageKeyField];
+    if (typeof key === "string" && key.length > 0 && options.allowedStorageKeys.has(key)) {
+      let signed = signedUrls.get(key);
+      if (!signed) {
+        signed = options.getDownloadUrl(key);
+        signedUrls.set(key, signed);
+      }
+      const url = await signed;
+      for (const field of options.urlFields) {
+        Object.defineProperty(result, field, {
+          value: url,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      }
+    }
+    return result;
+  }, "hydrate");
+  return hydrate(value);
+}
+__name(hydrateStorageUrls, "hydrateStorageUrls");
+
+// src/unavailable-file-manager.ts
+var UnavailableFileManager = class {
+  static {
+    __name(this, "UnavailableFileManager");
+  }
+  providerType;
+  message;
+  constructor(providerType, message = `Storage provider ${providerType} is not configured`) {
+    this.providerType = providerType;
+    this.message = message;
+  }
+  isConfigured() {
+    return false;
+  }
+  unavailable() {
+    return new Error(this.message);
+  }
+  upload(_buffer, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  uploadStream(_stream, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  download(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  delete(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  exists(_key) {
+    return Promise.resolve(false);
+  }
+  getPublicUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  getDownloadUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  list(_prefix) {
+    return Promise.resolve([]);
+  }
+};
+
+// src/verified-object-transfer.ts
+var import_node_crypto2 = require("crypto");
+var StorageTransferError = class extends Error {
+  static {
+    __name(this, "StorageTransferError");
+  }
+  code;
+  constructor(code) {
+    super(code), this.code = code;
+    this.name = "StorageTransferError";
+  }
+};
+function verifyStoredObject(object, expected, detectMimeType, errorFactory = (code) => new StorageTransferError(code)) {
+  if (object.reportedSize !== object.body.length || object.body.length !== expected.size) throw errorFactory("TARGET_SIZE_CONFLICT");
+  if (detectMimeType(object.body) !== expected.mimeType) throw errorFactory("TARGET_MIME_CONFLICT");
+  if ((0, import_node_crypto2.createHash)("sha256").update(object.body).digest("hex") !== expected.sha256) throw errorFactory("TARGET_HASH_CONFLICT");
+}
+__name(verifyStoredObject, "verifyStoredObject");
+async function transferVerifiedObject(options) {
+  const fail = options.errorFactory ?? ((code) => new StorageTransferError(code));
+  const body = options.source.body;
+  if (options.source.reportedSize !== body.length || body.length === 0) throw fail("SOURCE_SIZE_MISMATCH");
+  const metadata = {
+    sha256: (0, import_node_crypto2.createHash)("sha256").update(body).digest("hex"),
+    size: body.length,
+    mimeType: options.detectMimeType(body)
+  };
+  if (await options.target.exists(options.destinationKey)) {
+    verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+    return {
+      ...metadata,
+      targetDisposition: options.mode === "dry-run" ? "planned" : "reused"
+    };
+  }
+  if (options.mode === "dry-run" || !options.allowUpload) return {
+    ...metadata,
+    targetDisposition: "planned"
+  };
+  const uploaded = await options.target.write(options.destinationKey, body, {
+    contentType: metadata.mimeType,
+    metadata: {
+      sha256: metadata.sha256,
+      size: String(metadata.size),
+      mimeType: metadata.mimeType
+    },
+    private: true
+  });
+  if (uploaded.size !== metadata.size) throw fail("UPLOAD_SIZE_MISMATCH");
+  verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+  return {
+    ...metadata,
+    targetDisposition: "uploaded"
+  };
+}
+__name(transferVerifiedObject, "transferVerifiedObject");
+
+// src/buffered-file-manager-store.ts
+var BufferedFileManagerStore = class {
+  static {
+    __name(this, "BufferedFileManagerStore");
+  }
+  manager;
+  maxObjectBytes;
+  errorFactory;
+  constructor(manager, maxObjectBytes, errorFactory = (code) => new StorageTransferError(code)) {
+    this.manager = manager;
+    this.maxObjectBytes = maxObjectBytes;
+    this.errorFactory = errorFactory;
+    if (!Number.isSafeInteger(maxObjectBytes) || maxObjectBytes < 1) throw new RangeError("maxObjectBytes must be a positive integer");
+    if (!manager.isConfigured()) throw errorFactory("STORAGE_NOT_CONFIGURED");
+  }
+  async read(key) {
+    const downloaded = await this.manager.download(key);
+    if (downloaded.size < 1 || downloaded.size > this.maxObjectBytes) {
+      downloaded.stream.destroy();
+      throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of downloaded.stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += buffer.length;
+      if (size > this.maxObjectBytes) {
+        downloaded.stream.destroy();
+        throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+      }
+      chunks.push(buffer);
+    }
+    return {
+      body: Buffer.concat(chunks),
+      reportedSize: downloaded.size
+    };
+  }
+  exists(key) {
+    return this.manager.exists(key);
+  }
+  async write(key, body, options) {
+    if (body.length > this.maxObjectBytes) throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    const result = await this.manager.upload(body, key, {
+      contentType: options.contentType,
+      metadata: options.metadata,
+      acl: "private"
+    });
+    return {
+      size: result.size
+    };
+  }
+};
+
 // src/index.ts
 var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
   StorageProvider2["LOCAL"] = "LOCAL";
@@ -1066,16 +1358,22 @@ var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
 })({});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BufferedFileManagerStore,
   DANGEROUS_EXTENSIONS,
   FILE_MANAGER,
   FileLifecycleManager,
   LocalFileStorage,
   S3Storage,
   StorageProvider,
+  StorageTransferError,
+  UnavailableFileManager,
   WebDavStorage,
   ZuckerStorageModule,
   generateDateBasedKey,
+  hydrateStorageUrls,
   isFileDenied,
   isSafeOriginalFileName,
-  sanitizeFileName
+  sanitizeFileName,
+  transferVerifiedObject,
+  verifyStoredObject
 });