@h-ai/storage 0.1.0-alpha.67 → 0.1.0-alpha.69

package/dist/node.js

@@ -1,7 +1,9 @@
-import { HaiStorageError, StorageConfigSchema } from './chunk-KXE6OO5T.js';
-export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-KXE6OO5T.js';
-import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-25GYTRA7.js';
-export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-25GYTRA7.js';
+import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-B4Q2NMST.js';
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-B4Q2NMST.js';
+import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-I4BSES63.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-I4BSES63.js';
+export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './chunk-P65WYXJG.js';
+import process from 'node:process';
 import { core, err, ok } from '@h-ai/core';
 import { Buffer } from 'node:buffer';
 import * as crypto from 'node:crypto';
@@ -11,9 +13,21 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { S3Client, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, CopyObjectCommand, DeleteObjectsCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { S3Client, HeadBucketCommand, CreateBucketCommand, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, CopyObjectCommand, DeleteObjectsCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
+function toStorageDeleteResult(summary) {
+  if (summary.failures.length === 0)
+    return ok(summary);
+  return {
+    success: false,
+    error: {
+      ...HaiStorageError.OPERATION_FAILED,
+      message: storageM("storage_deleteManyFailed", { params: { count: summary.failures.length } }),
+      ext: { deleteMany: summary }
+    }
+  };
+}
 async function* toByteStream(data, signal) {
   signal?.throwIfAborted();
   if (typeof data === "string" || data instanceof Uint8Array) {
@@ -366,21 +380,22 @@ function createLocalProvider() {
     },
     async deleteMany(keys) {
       logOperation("write", "file.deleteMany", { count: keys.length, keys });
-      const results = await Promise.allSettled(keys.map((key) => file.delete(key)));
-      const errors = [];
-      for (const result of results) {
-        if (result.status === "fulfilled" && !result.value.success) {
-          errors.push(result.value.error);
+      const summary = { deletedKeys: [], failures: [] };
+      const uniqueKeys = [...new Set(keys)];
+      for (let offset = 0; offset < uniqueKeys.length; offset += 32) {
+        const batch = uniqueKeys.slice(offset, offset + 32);
+        const results = await Promise.allSettled(batch.map((key) => file.delete(key)));
+        for (const [index, result] of results.entries()) {
+          const key = batch[index];
+          if (result.status === "rejected")
+            summary.failures.push({ key, code: "UnexpectedDeleteFailure", retryable: false, outcome: "failed" });
+          else if (!result.value.success)
+            summary.failures.push({ key, code: String(result.value.error.code), retryable: false, outcome: "failed" });
+          else
+            summary.deletedKeys.push(key);
         }
       }
-      if (errors.length > 0) {
-        return err(
-          HaiStorageError.OPERATION_FAILED,
-          storageM("storage_deleteManyFailed", { params: { count: errors.length } }),
-          errors
-        );
-      }
-      return ok(void 0);
+      return toStorageDeleteResult(summary);
     },
     async copy(sourceKey, destKey, options = {}) {
       if (isMetaFile(sourceKey) || isMetaFile(destKey)) {
@@ -423,49 +438,85 @@ function createLocalProvider() {
     async list(options = {}) {
       try {
         const cfg = getConfig();
-        const prefix = options.prefix || "";
-        const delimiter = options.delimiter || "";
-        const maxKeys = options.maxKeys || 1e3;
+        const prefix = options.prefix === void 0 ? "" : options.prefix;
+        const delimiter = options.delimiter === void 0 ? "" : options.delimiter;
+        const maxKeys = options.maxKeys === void 0 ? 1e3 : options.maxKeys;
+        if (typeof prefix !== "string" || typeof delimiter !== "string" || !Number.isInteger(maxKeys) || maxKeys < 1 || maxKeys > 1e3 || Buffer.from(prefix).toString("utf8") !== prefix || Buffer.from(delimiter).toString("utf8") !== delimiter) {
+          return err(HaiStorageError.INVALID_LIST_OPTIONS, storageM("storage_listOptionsInvalid"));
+        }
         logOperation("read", "dir.list", { options });
-        const basePath = safePath(cfg.root, prefix);
-        const files = [];
-        const commonPrefixes = /* @__PURE__ */ new Set();
-        async function readDir(dirPath) {
-          let entries;
+        safePath(cfg.root, prefix);
+        const root = await fsp.realpath(cfg.root);
+        const scope = crypto.createHash("sha256").update(JSON.stringify([root, prefix, delimiter])).digest("hex");
+        let after = "";
+        if (options.continuationToken !== void 0) {
+          const token = options.continuationToken;
           try {
-            entries = await fsp.readdir(dirPath, { withFileTypes: true });
+            if (typeof token !== "string" || token.length === 0 || token.length > 262144)
+              throw new Error("Invalid cursor encoding");
+            const bytes = Buffer.from(token, "base64url");
+            if (bytes.toString("base64url") !== token)
+              throw new Error("Invalid cursor encoding");
+            const decoded = JSON.parse(bytes.toString("utf8"));
+            if (!Array.isArray(decoded) || decoded.length !== 3 || decoded[0] !== 1 || decoded[1] !== scope || typeof decoded[2] !== "string" || decoded[2].length === 0 || !decoded[2].startsWith(prefix)) {
+              throw new Error("Invalid cursor scope");
+            }
+            after = decoded[2];
           } catch {
-            return;
+            return err(HaiStorageError.INVALID_LIST_OPTIONS, storageM("storage_listCursorInvalid"));
           }
+        }
+        const files = [];
+        const commonPrefixes = [];
+        const compare = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+        async function* readDir(dirPath, directoryKey) {
+          const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+          entries.sort((left, right) => compare(left.name + (left.isDirectory() ? "/" : ""), right.name + (right.isDirectory() ? "/" : "")));
           for (const entry of entries) {
-            if (files.length >= maxKeys)
-              return;
-            const fullEntryPath = path.join(dirPath, entry.name);
-            const key = path.relative(cfg.root, fullEntryPath).replace(/\\/g, "/");
             if (isMetaFile(entry.name))
               continue;
+            const key = directoryKey + entry.name;
+            const filePath = path.join(dirPath, entry.name);
             if (entry.isDirectory()) {
-              if (delimiter) {
-                commonPrefixes.add(`${key}/`);
-              } else {
-                await readDir(fullEntryPath);
+              const childPrefix = `${key}/`;
+              if (prefix.startsWith(childPrefix) || childPrefix.startsWith(prefix)) {
+                yield* readDir(filePath, childPrefix);
               }
-            } else if (entry.isFile()) {
-              const stat2 = await fsp.stat(fullEntryPath);
-              files.push({
-                key,
-                size: stat2.size,
-                contentType: getMimeType2(key),
-                lastModified: stat2.mtime
-              });
+            } else if (entry.isFile() && key.startsWith(prefix)) {
+              yield { key, filePath };
             }
           }
         }
-        await readDir(basePath);
+        let previous = "";
+        let last = "";
+        let count = 0;
+        let isTruncated = false;
+        for await (const entry of readDir(root, "")) {
+          const index = delimiter ? entry.key.indexOf(delimiter, prefix.length) : -1;
+          const logicalKey = index < 0 ? entry.key : entry.key.slice(0, index + delimiter.length);
+          if (logicalKey === previous)
+            continue;
+          previous = logicalKey;
+          if (compare(logicalKey, after) <= 0)
+            continue;
+          if (count === maxKeys) {
+            isTruncated = true;
+            break;
+          }
+          if (index >= 0) {
+            commonPrefixes.push(logicalKey);
+          } else {
+            const stat2 = await fsp.stat(entry.filePath);
+            files.push({ key: entry.key, size: stat2.size, contentType: getMimeType2(entry.key), lastModified: stat2.mtime });
+          }
+          count++;
+          last = logicalKey;
+        }
         return ok({
           files,
-          commonPrefixes: Array.from(commonPrefixes),
-          isTruncated: files.length >= maxKeys
+          commonPrefixes,
+          isTruncated,
+          ...isTruncated ? { nextContinuationToken: Buffer.from(JSON.stringify([1, scope, last])).toString("base64url") } : {}
         });
       } catch (error) {
         return err(toStorageError(error));
@@ -488,17 +539,11 @@ function createLocalProvider() {
   const presign = {
     async getUrl(key, options) {
       logOperation("read", "presign.getUrl", { key, options });
-      const expiresIn = options?.expiresIn || 3600;
-      const expires = Math.floor(Date.now() / 1e3) + expiresIn;
-      const signature = crypto.createHash("sha256").update(`${key}:${expires}`).digest("hex").slice(0, 16);
-      return ok(`local://${key}?expires=${expires}&signature=${signature}`);
+      return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
     async putUrl(key, options) {
       logOperation("write", "presign.putUrl", { key, options });
-      const expiresIn = options?.expiresIn || 3600;
-      const expires = Math.floor(Date.now() / 1e3) + expiresIn;
-      const signature = crypto.createHash("sha256").update(`put:${key}:${expires}`).digest("hex").slice(0, 16);
-      return ok(`local://${key}?action=put&expires=${expires}&signature=${signature}`);
+      return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
     publicUrl(key) {
       logOperation("read", "presign.publicUrl", { key });
@@ -543,18 +588,8 @@ function createLocalProvider() {
 var logger2 = core.logger.child({ module: "storage", scope: "provider-s3" });
 var TRAILING_SLASHES_REGEX = /\/+$/;
 var LEADING_SLASHES_REGEX = /^\/+/;
-function sanitizeEndpointUrl(url) {
-  try {
-    const parsed = new URL(url);
-    if (parsed.username)
-      parsed.username = "***";
-    if (parsed.password)
-      parsed.password = "***";
-    return parsed.toString();
-  } catch {
-    return "(invalid url)";
-  }
-}
+var DELETE_BATCH_SIZE = 1e3;
+var RETRYABLE_DELETE_CODES = /* @__PURE__ */ new Set(["InternalError", "ServiceUnavailable", "SlowDown", "RequestTimeout"]);
 function toStorageError2(error, key) {
   const e = error;
   if (e.name === "PreconditionFailed" || e.$metadata?.httpStatusCode === 412)
@@ -609,15 +644,46 @@ function withoutPrefix(key, prefix) {
 }
 function createS3Provider() {
   let client = null;
+  let deleteClient = null;
   let config = null;
-  function getClient() {
-    if (!client) {
+  let ready = false;
+  let closing = null;
+  function closeClients() {
+    ready = false;
+    config = null;
+    if (closing)
+      return closing;
+    closing = Promise.resolve().then(() => {
+      const failures = [];
+      for (const kind of ["normal", "delete"]) {
+        const owned = kind === "normal" ? client : deleteClient;
+        if (!owned)
+          continue;
+        try {
+          owned.destroy();
+          if (kind === "normal")
+            client = null;
+          else deleteClient = null;
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      if (failures.length > 0)
+        throw new AggregateError(failures, "S3 client cleanup failed");
+    }).finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
+  function getClient(operation) {
+    const selected = operation === "deleteMany" ? deleteClient : client;
+    if (!ready || !selected) {
       throw new Error(storageM("storage_s3ClientNotInitialized"));
     }
-    return client;
+    return selected;
   }
   function getConfig() {
-    if (!config) {
+    if (!ready || !config) {
       throw new Error(storageM("storage_s3ConfigNotInitialized"));
     }
     return config;
@@ -777,19 +843,65 @@ function createS3Provider() {
     },
     async deleteMany(keys) {
       try {
-        const s3Client = getClient();
+        const s3Client = getClient("deleteMany");
         const s3Config = getConfig();
-        if (keys.length === 0) {
-          return ok(void 0);
-        }
         logOperation("write", "file.deleteMany", { count: keys.length, keys });
-        await s3Client.send(new DeleteObjectsCommand({
-          Bucket: s3Config.bucket,
-          Delete: {
-            Objects: keys.map((key) => ({ Key: fullKey(key) }))
+        const uniqueKeys = [...new Set(keys)];
+        const summary = { deletedKeys: [], failures: [] };
+        for (let offset = 0; offset < uniqueKeys.length; offset += DELETE_BATCH_SIZE) {
+          let pending = uniqueKeys.slice(offset, offset + DELETE_BATCH_SIZE);
+          for (let attempt = 0; pending.length > 0 && attempt < 3; attempt++) {
+            let response;
+            try {
+              response = await s3Client.send(new DeleteObjectsCommand({
+                Bucket: s3Config.bucket,
+                Delete: { Objects: [...new Set(pending.map(fullKey))].map((Key) => ({ Key })), Quiet: false }
+              }));
+            } catch (cause) {
+              const failure = cause && typeof cause === "object" ? cause : {};
+              const status = failure.$metadata?.httpStatusCode;
+              const code = failure.name && /^[\w.-]{1,80}$/.test(failure.name) ? failure.name : "RequestFailed";
+              const retryable = status === void 0 || status === 408 || status === 429 || status >= 500;
+              const outcome = status !== void 0 && status >= 400 && status < 500 && status !== 408 ? "failed" : "unknown";
+              summary.failures.push(...pending.map((key) => ({ key, code, retryable, outcome })));
+              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({ key, code, retryable, outcome: "notAttempted" })));
+              return toStorageDeleteResult(summary);
+            }
+            const outcomes = /* @__PURE__ */ new Map();
+            const requested = new Set(pending.map(fullKey));
+            let malformed = false;
+            const items = [
+              ...(response.Deleted ?? []).map((item) => ({ key: item.Key, code: null })),
+              ...(response.Errors ?? []).map((item) => ({ key: item.Key, code: item.Code && /^[\w.-]{1,80}$/.test(item.Code) ? item.Code : "UnknownError" }))
+            ];
+            for (const item of items) {
+              if (!item.key || !requested.has(item.key) || outcomes.has(item.key)) {
+                malformed = true;
+                break;
+              }
+              outcomes.set(item.key, item.code);
+            }
+            if (malformed || outcomes.size !== requested.size) {
+              summary.failures.push(...pending.map((key) => ({ key, code: "InvalidDeleteResponse", retryable: false, outcome: "unknown" })));
+              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({ key, code: "InvalidDeleteResponse", retryable: false, outcome: "notAttempted" })));
+              return toStorageDeleteResult(summary);
+            }
+            const retry = [];
+            for (const key of pending) {
+              const code = outcomes.get(fullKey(key));
+              if (code === null)
+                summary.deletedKeys.push(key);
+              else if (code && RETRYABLE_DELETE_CODES.has(code) && attempt < 2)
+                retry.push(key);
+              else
+                summary.failures.push({ key, code: code ?? "UnknownError", retryable: !!code && RETRYABLE_DELETE_CODES.has(code), outcome: "failed" });
+            }
+            pending = retry;
+            if (pending.length > 0)
+              await new Promise((resolve2) => setTimeout(resolve2, 100 * 2 ** attempt));
           }
-        }));
-        return ok(void 0);
+        }
+        return toStorageDeleteResult(summary);
       } catch (error) {
         return err(toStorageError2(error));
       }
@@ -882,6 +994,7 @@ function createS3Provider() {
   const presign = {
     async getUrl(key, options) {
       try {
+        const parsed = PresignOptionsSchema.parse(options ?? {});
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
@@ -889,11 +1002,11 @@ function createS3Provider() {
         const command = new GetObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath,
-          ResponseContentType: options?.responseContentType,
-          ResponseContentDisposition: options?.responseContentDisposition
+          ResponseContentType: parsed.responseContentType,
+          ResponseContentDisposition: parsed.responseContentDisposition
         });
         const url = await getSignedUrl(s3Client, command, {
-          expiresIn: options?.expiresIn || 3600
+          expiresIn: parsed.expiresIn
         });
         return ok(url);
       } catch (error) {
@@ -906,6 +1019,7 @@ function createS3Provider() {
     },
     async putUrl(key, options) {
       try {
+        const parsed = PresignUploadOptionsSchema.parse(options ?? {});
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
@@ -913,10 +1027,10 @@ function createS3Provider() {
         const command = new PutObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath,
-          ContentType: options?.contentType || "application/octet-stream"
+          ContentType: parsed.contentType
         });
         const url = await getSignedUrl(s3Client, command, {
-          expiresIn: options?.expiresIn || 3600
+          expiresIn: parsed.expiresIn
         });
         return ok(url);
       } catch (error) {
@@ -950,13 +1064,14 @@ function createS3Provider() {
         );
       }
       try {
+        await closeClients();
         config = cfg;
         logger2.info("Connecting S3 provider", {
           bucket: cfg.bucket,
           region: cfg.region,
-          endpoint: cfg.endpoint ? sanitizeEndpointUrl(cfg.endpoint) : void 0
+          endpoint: cfg.endpoint ? core.sanitize.sanitizeUrl(cfg.endpoint) : void 0
         });
-        client = new S3Client({
+        const clientConfig = {
           region: cfg.region,
           endpoint: cfg.endpoint,
           forcePathStyle: cfg.forcePathStyle,
@@ -967,30 +1082,52 @@ function createS3Provider() {
             accessKeyId: cfg.accessKeyId,
             secretAccessKey: cfg.secretAccessKey
           }
-        });
+        };
+        client = new S3Client(clientConfig);
+        deleteClient = new S3Client({ ...clientConfig, maxAttempts: 1 });
+        if (cfg.createBucket) {
+          try {
+            await client.send(new HeadBucketCommand({ Bucket: cfg.bucket }));
+          } catch (error) {
+            if (!(error && typeof error === "object" && "$metadata" in error && error.$metadata && typeof error.$metadata === "object" && "httpStatusCode" in error.$metadata && error.$metadata.httpStatusCode === 404)) {
+              throw error;
+            }
+            try {
+              await client.send(new CreateBucketCommand({
+                Bucket: cfg.bucket,
+                // AWS us-east-1 要省略 LocationConstraint；兼容服务可使用自定义区域名。
+                ...cfg.region === "us-east-1" ? {} : { CreateBucketConfiguration: { LocationConstraint: cfg.region } }
+              }));
+              logger2.info("S3 bucket created", { bucket: cfg.bucket });
+            } catch (createError) {
+              if (!(createError instanceof Error && createError.name === "BucketAlreadyOwnedByYou"))
+                throw createError;
+              await client.send(new HeadBucketCommand({ Bucket: cfg.bucket }));
+            }
+          }
+        }
         await client.send(new ListObjectsV2Command({
           Bucket: cfg.bucket,
           MaxKeys: 1
         }));
+        config = cfg;
+        ready = true;
         logger2.info("S3 provider connected", { bucket: cfg.bucket });
         return ok(void 0);
       } catch (error) {
         logger2.error("S3 provider connect failed", { error });
-        config = null;
-        client = null;
-        return err(toStorageError2(error));
-      }
-    },
-    async close() {
-      if (client) {
-        client.destroy();
-        client = null;
-        config = null;
-        logger2.info("S3 provider disconnected");
+        const original = toStorageError2(error);
+        try {
+          await closeClients();
+          return err(original);
+        } catch (cleanupError) {
+          return err({ ...original, ext: { ...original.ext, cleanupPending: true, cleanupError } });
+        }
       }
     },
+    close: closeClients,
     isConnected() {
-      return client !== null && config !== null;
+      return ready && client !== null && deleteClient !== null && config !== null;
     }
   };
 }
@@ -1031,6 +1168,40 @@ var logger3 = core.logger.child({ module: "storage", scope: "main" });
 var currentProvider = null;
 var currentConfig = null;
 var initInProgress = false;
+var pendingProvider = null;
+var initCompletion = null;
+var closingPromise = null;
+async function closeOwnedProvider() {
+  if (currentProvider) {
+    pendingProvider = currentProvider;
+    currentProvider = null;
+  }
+  currentConfig = null;
+  if (!pendingProvider)
+    return ok(void 0);
+  try {
+    await pendingProvider.close();
+    pendingProvider = null;
+    return ok(void 0);
+  } catch (error) {
+    logger3.error("Provider cleanup failed; retaining resource for retry", { error });
+    return err({ ...HaiStorageError.CONNECTION_FAILED, message: storageM("storage_operationFailed", {
+      params: { error: error instanceof Error ? error.message : String(error) }
+    }), cause: error, ext: { cleanupPending: true } });
+  }
+}
+async function failInitialization(result) {
+  const cleanup = await closeOwnedProvider();
+  if (result.success)
+    return result;
+  if (cleanup.success) {
+    const ext = { ...result.error.ext };
+    delete ext.cleanupPending;
+    delete ext.cleanupError;
+    return err({ ...result.error, ext: Object.keys(ext).length > 0 ? ext : void 0 });
+  }
+  return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error } });
+}
 function createProvider(config) {
   switch (config.type) {
     case "s3":
@@ -1060,13 +1231,22 @@ var storage = {
    * 初始化存储连接。
    *
    * 如果当前已有活跃连接，会先自动 close 再重新初始化。
-   * 配置会通过 Zod Schema 校验；校验失败或连接异常会返回 `CONNECTION_FAILED`。
+   * 配置通过 Zod Schema 校验；校验、连接或清理失败均返回 HaiResult，不发布失败候选。
    *
    * @param config 存储配置（S3 或本地），支持省略带默认值的字段。
    * @returns 成功时返回 ok(undefined)；失败时返回包含错误码和消息的 err。
+   * @example
+   * ```ts
+   * import { storage } from '@h-ai/storage'
+   *
+   * const initialized = await storage.init({ type: 'local', root: './data/uploads' })
+   * if (!initialized.success) throw new Error(initialized.error.message)
+   * const closed = await storage.close()
+   * if (!closed.success) throw new Error(closed.error.message)
+   * ```
    */
   async init(config) {
-    if (initInProgress) {
+    if (initInProgress || closingPromise) {
       logger3.warn("Storage init already in progress, skipping concurrent call");
       return err(
         HaiStorageError.OPERATION_FAILED,
@@ -1074,14 +1254,14 @@ var storage = {
       );
     }
     initInProgress = true;
+    let resolveInit;
+    initCompletion = new Promise((resolve2) => {
+      resolveInit = resolve2;
+    });
     try {
-      if (currentProvider) {
-        logger3.warn("Storage module is already initialized, reinitializing");
-        const closeResult = await storage.close();
-        if (!closeResult.success) {
-          return closeResult;
-        }
-      }
+      const cleanup = await closeOwnedProvider();
+      if (!cleanup.success)
+        return cleanup;
       logger3.info("Initializing storage module");
       const parseResult = StorageConfigSchema.safeParse(config);
       if (!parseResult.success) {
@@ -1093,30 +1273,36 @@ var storage = {
         );
       }
       const parsed = parseResult.data;
+      if (core.module.requiresSharedState(process.env) && parsed.type === "local")
+        return err(HaiStorageError.CONFIG_ERROR, storageM("storage_sharedBackendRequired"));
       const provider = createProvider(parsed);
+      pendingProvider = provider;
       const connectResult = await provider.connect(parsed);
       if (!connectResult.success) {
         logger3.error("Storage module initialization failed", {
           code: connectResult.error.code,
           message: connectResult.error.message
         });
-        return connectResult;
+        return await failInitialization(connectResult);
       }
+      pendingProvider = null;
       currentProvider = provider;
       currentConfig = parsed;
       logger3.info("Storage module initialized");
       return ok(void 0);
     } catch (error) {
       logger3.error("Storage module initialization failed", { error });
-      return err(
+      return await failInitialization(err(
         HaiStorageError.CONNECTION_FAILED,
         storageM("storage_operationFailed", {
           params: { error: error instanceof Error ? error.message : String(error) }
         }),
         error
-      );
+      ));
     } finally {
       initInProgress = false;
+      initCompletion = null;
+      resolveInit();
     }
   },
   /** 文件操作接口。未初始化时所有方法返回 NOT_INITIALIZED 错误 */
@@ -1137,38 +1323,33 @@ var storage = {
   },
   /** 是否已完成初始化 */
   get isInitialized() {
-    return currentProvider !== null;
+    return currentProvider !== null && currentProvider.isConnected();
   },
   /**
    * 关闭存储连接并释放资源
    *
    * 关闭后 file/dir/presign 操作将返回 NOT_INITIALIZED 错误。
-   * 重复调用不会报错。
+   * 等待初始化并合并并发关闭；失败时保留资源供 close/init 重试。
+   * @returns 所有客户端释放成功才返回成功。
+   * @example
+   * ```ts
+   * import { storage } from '@h-ai/storage'
+   *
+   * const closed = await storage.close()
+   * if (!closed.success) throw new Error(closed.error.message)
+   * ```
    */
   async close() {
-    if (!currentProvider) {
-      currentConfig = null;
-      logger3.info("Storage module already closed, skipping");
-      return ok(void 0);
-    }
-    logger3.info("Closing storage module");
-    try {
-      await currentProvider.close();
-      logger3.info("Storage module closed");
-      return ok(void 0);
-    } catch (error) {
-      logger3.error("Storage module close failed", { error });
-      return err(
-        HaiStorageError.CONNECTION_FAILED,
-        storageM("storage_operationFailed", {
-          params: { error: error instanceof Error ? error.message : String(error) }
-        }),
-        error
-      );
-    } finally {
-      currentProvider = null;
-      currentConfig = null;
+    if (!closingPromise) {
+      closingPromise = (async () => {
+        if (initCompletion)
+          await initCompletion;
+        return await closeOwnedProvider();
+      })().finally(() => {
+        closingPromise = null;
+      });
     }
+    return await closingPromise;
   }
 };