@h-ai/cache 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/index.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
+import process from 'process';
 import { core, err, ok } from '@h-ai/core';
 import Redis from 'ioredis';
+import { Buffer } from 'buffer';
+import { createHash } from 'crypto';
 
 // src/cache-config.ts
 var RedisClusterNodeSchema = z.object({
@@ -27,7 +30,7 @@ var RedisConfigSchema = z.object({
   host: z.string().default("localhost"),
   /** 端口号；默认 6379 */
   port: z.number().int().min(1).max(65535).default(6379),
-  /** 认证密码 */
+  /** 单机、Cluster 和 Sentinel 数据节点的认证密码；url 模式使用 URL 内凭据。 */
   password: z.string().optional(),
   /** 数据库编号（0~15）；默认 0 */
   db: z.number().int().min(0).max(15).default(0),
@@ -68,7 +71,36 @@ var en_US_default = {
   cache_keyNotFound: "Key not found",
   cache_indexOutOfRange: "Index out of range",
   cache_configError: "Cache config validation failed: {error}",
-  cache_invalidHashSetInput: "Invalid hash hset input: pass a field and value, or a field object"
+  cache_invalidHashSetInput: "Invalid hash hset input: pass a field and value, or a field object",
+  cache_invalidScan: "Invalid scan cursor or options",
+  cache_scanTopologyChanged: "Scan topology or match changed; restart from 0",
+  cache_crossSlot: "This operation requires keys in the same Redis Cluster slot; use a shared hash tag",
+  cache_sharedBackendRequired: "Production mode requires a shared backend; local files and memory backends are for development or explicit end-to-end tests.",
+  cache_invalidSetOptions: "Invalid SET options: use one positive safe-integer expiry, do not combine it with keepTtl, and choose at most one of nx/xx",
+  cache_setUnexpectedReply: "Redis returned an unexpected SET result",
+  cache_serializationFailed: "The cache value could not be serialized as JSON"
+};
+
+// messages/ja-JP.json
+var ja_JP_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  cache_notInitialized: "\u30AD\u30E3\u30C3\u30B7\u30E5\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u5148\u306Bcache.init()\u3092\u547C\u3073\u51FA\u3057\u3066\u304F\u3060\u3055\u3044",
+  cache_operationFailed: "\u30AD\u30E3\u30C3\u30B7\u30E5\u64CD\u4F5C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  cache_redisConnectionFailed: "Redis\u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  cache_initFailed: "\u30AD\u30E3\u30C3\u30B7\u30E5\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  cache_unsupportedType: "\u672A\u5BFE\u5FDC\u306E\u30AD\u30E3\u30C3\u30B7\u30E5\u306E\u7A2E\u985E\u3067\u3059: {type}",
+  cache_valueNotNumber: "\u5024\u304C\u6570\u5024\u3067\u306F\u3042\u308A\u307E\u305B\u3093",
+  cache_keyNotFound: "\u30AD\u30FC\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093",
+  cache_indexOutOfRange: "\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u304C\u7BC4\u56F2\u5916\u3067\u3059",
+  cache_configError: "\u30AD\u30E3\u30C3\u30B7\u30E5\u8A2D\u5B9A\u306E\u691C\u8A3C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  cache_invalidHashSetInput: "\u30CF\u30C3\u30B7\u30E5\u306Ehset\u5165\u529B\u304C\u7121\u52B9\u3067\u3059\u3002\u30D5\u30A3\u30FC\u30EB\u30C9\u3068\u5024\u3001\u307E\u305F\u306F\u30D5\u30A3\u30FC\u30EB\u30C9\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3092\u6E21\u3057\u3066\u304F\u3060\u3055\u3044",
+  cache_invalidScan: "\u30B9\u30AD\u30E3\u30F3\u30AB\u30FC\u30BD\u30EB\u307E\u305F\u306F\u30AA\u30D7\u30B7\u30E7\u30F3\u304C\u7121\u52B9\u3067\u3059",
+  cache_scanTopologyChanged: "\u30B9\u30AD\u30E3\u30F3\u306E\u30C8\u30DD\u30ED\u30B8\u30FC\u307E\u305F\u306F\u4E00\u81F4\u6761\u4EF6\u304C\u5909\u66F4\u3055\u308C\u307E\u3057\u305F\u30020 \u304B\u3089\u518D\u958B\u3057\u3066\u304F\u3060\u3055\u3044",
+  cache_crossSlot: "\u3053\u306E\u64CD\u4F5C\u306E\u30AD\u30FC\u306F\u540C\u3058 Redis Cluster \u30B9\u30ED\u30C3\u30C8\u306B\u914D\u7F6E\u3059\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\u3002\u5171\u901A\u306E\u30CF\u30C3\u30B7\u30E5\u30BF\u30B0\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044",
+  cache_sharedBackendRequired: "\u672C\u756A\u74B0\u5883\u306B\u306F\u5171\u6709\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u304C\u5FC5\u8981\u3067\u3059\u3002\u30ED\u30FC\u30AB\u30EB\u30D5\u30A1\u30A4\u30EB\u3068\u30E1\u30E2\u30EA\u30FC\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u306F\u958B\u767A\u74B0\u5883\u307E\u305F\u306F\u660E\u793A\u7684\u306A E2E \u30C6\u30B9\u30C8\u3067\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059\u3002",
+  cache_invalidSetOptions: "SET \u30AA\u30D7\u30B7\u30E7\u30F3\u304C\u7121\u52B9\u3067\u3059\u3002\u6709\u52B9\u671F\u9650\u306B\u306F\u6B63\u306E\u5B89\u5168\u306A\u6574\u6570\u30921\u7A2E\u985E\u3060\u3051\u6307\u5B9A\u3057\u3001keepTtl \u3068\u4F75\u7528\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002nx \u3068 xx \u306F\u540C\u6642\u306B\u6307\u5B9A\u3067\u304D\u307E\u305B\u3093",
+  cache_setUnexpectedReply: "Redis \u304C\u4E88\u671F\u3057\u306A\u3044 SET \u306E\u7D50\u679C\u3092\u8FD4\u3057\u307E\u3057\u305F",
+  cache_serializationFailed: "\u30AD\u30E3\u30C3\u30B7\u30E5\u5024\u3092 JSON \u306B\u30B7\u30EA\u30A2\u30E9\u30A4\u30BA\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F"
 };
 
 // messages/zh-CN.json
@@ -83,13 +115,21 @@ var zh_CN_default = {
   cache_keyNotFound: "\u952E\u4E0D\u5B58\u5728",
   cache_indexOutOfRange: "\u7D22\u5F15\u8D8A\u754C",
   cache_configError: "\u7F13\u5B58\u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A{error}",
-  cache_invalidHashSetInput: "Hash hset \u53C2\u6570\u65E0\u6548\uFF1A\u8BF7\u4F20\u5165\u5B57\u6BB5\u548C\u503C\uFF0C\u6216\u4F20\u5165\u5B57\u6BB5\u5BF9\u8C61"
+  cache_invalidHashSetInput: "Hash hset \u53C2\u6570\u65E0\u6548\uFF1A\u8BF7\u4F20\u5165\u5B57\u6BB5\u548C\u503C\uFF0C\u6216\u4F20\u5165\u5B57\u6BB5\u5BF9\u8C61",
+  cache_invalidScan: "\u626B\u63CF\u6E38\u6807\u6216\u53C2\u6570\u65E0\u6548",
+  cache_scanTopologyChanged: "\u626B\u63CF\u62D3\u6251\u6216\u5339\u914D\u89C4\u5219\u5DF2\u6539\u53D8\uFF0C\u8BF7\u4ECE0\u91CD\u65B0\u5F00\u59CB",
+  cache_crossSlot: "\u6B64\u64CD\u4F5C\u8981\u6C42\u6240\u6709\u952E\u4F4D\u4E8E\u540C\u4E00Redis Cluster slot\uFF0C\u8BF7\u4F7F\u7528\u5171\u540Chash tag",
+  cache_sharedBackendRequired: "\u751F\u4EA7\u6A21\u5F0F\u9700\u8981\u8DE8\u8282\u70B9\u5171\u4EAB\u540E\u7AEF\uFF1B\u672C\u673A\u6587\u4EF6\u6216\u5185\u5B58\u540E\u7AEF\u4EC5\u7528\u4E8E\u5F00\u53D1\u548C\u663E\u5F0F\u7AEF\u5230\u7AEF\u6D4B\u8BD5\u3002",
+  cache_invalidSetOptions: "SET \u9009\u9879\u65E0\u6548\uFF1A\u671F\u9650\u987B\u4E3A\u6B63\u5B89\u5168\u6574\u6570\u4E14\u53EA\u80FD\u9009\u4E00\u79CD\uFF0C\u4E0D\u80FD\u4E0E keepTtl \u540C\u65F6\u4F7F\u7528\uFF0Cnx/xx \u4E0D\u80FD\u540C\u65F6\u542F\u7528",
+  cache_setUnexpectedReply: "Redis \u8FD4\u56DE\u4E86\u975E\u9884\u671F\u7684 SET \u7ED3\u679C",
+  cache_serializationFailed: "\u7F13\u5B58\u503C\u65E0\u6CD5\u5E8F\u5217\u5316\u4E3A JSON"
 };
 
 // src/cache-i18n.ts
 var cacheM = core.i18n.createMessageGetter({
   "zh-CN": zh_CN_default,
-  "en-US": en_US_default
+  "en-US": en_US_default,
+  "ja-JP": ja_JP_default
 });
 var CacheErrorInfo = {
   CONNECTION_FAILED: "001:500",
@@ -100,9 +140,44 @@ var CacheErrorInfo = {
   TIMEOUT: "006:504",
   NOT_INITIALIZED: "010:500",
   UNSUPPORTED_TYPE: "011:400",
-  CONFIG_ERROR: "012:500"
+  CONFIG_ERROR: "012:500",
+  INVALID_SCAN: "013:400",
+  SCAN_TOPOLOGY_CHANGED: "014:409",
+  CROSS_SLOT: "015:400",
+  INVALID_SET_OPTIONS: "016:400"
 };
 var HaiCacheError = core.error.buildHaiErrorsDef("cache", CacheErrorInfo);
+function validateSetOptions(options) {
+  const invalid = () => err(HaiCacheError.INVALID_SET_OPTIONS, cacheM("cache_invalidSetOptions"));
+  if (options !== void 0 && (options === null || typeof options !== "object" || Array.isArray(options)))
+    return invalid();
+  for (const flag of ["nx", "xx", "keepTtl"]) {
+    if (options?.[flag] !== void 0 && typeof options[flag] !== "boolean")
+      return invalid();
+  }
+  if (options?.nx && options.xx)
+    return invalid();
+  const entries = ["ex", "px", "exat", "pxat"].filter((key) => options?.[key] !== void 0);
+  if (entries.length > 1 || entries.length > 0 && options?.keepTtl)
+    return invalid();
+  const result = { nx: options?.nx === true, xx: options?.xx === true, keepTtl: options?.keepTtl === true };
+  const mode = entries[0];
+  if (mode) {
+    const value = options[mode];
+    if (!Number.isSafeInteger(value) || value <= 0)
+      return invalid();
+    const milliseconds = mode === "ex" || mode === "exat" ? value * 1e3 : value;
+    const expiresAt = mode === "ex" || mode === "px" ? Date.now() + milliseconds : milliseconds;
+    if (!Number.isSafeInteger(expiresAt))
+      return invalid();
+    const command = { ex: "EX", px: "PX", exat: "EXAT", pxat: "PXAT" };
+    result.expiry = [command[mode], value];
+    result.expiresAt = expiresAt;
+  }
+  return ok(result);
+}
+
+// src/providers/cache-provider-memory.ts
 function serializeValue(value) {
   return JSON.stringify(value);
 }
@@ -146,35 +221,58 @@ function createMemoryProvider() {
     }
     return entry;
   }
-  function calculateExpiry(options) {
-    if (!options)
-      return void 0;
-    const now = Date.now();
-    if (options.ex)
-      return now + options.ex * 1e3;
-    if (options.px)
-      return now + options.px;
-    if (options.exat != null)
-      return options.exat * 1e3;
-    if (options.pxat != null)
-      return options.pxat;
-    return void 0;
-  }
   const kv = {
+    async compareAndSwap(key, expected, value, options) {
+      try {
+        if (options?.px !== void 0 && (!Number.isSafeInteger(options.px) || options.px <= 0) || options?.px !== void 0 && options.keepTtl)
+          throw new TypeError("Invalid compare-and-swap expiry");
+        const entry = getValidEntry(key);
+        const actual = entry ? serializeValue(entry.value) : void 0;
+        if (actual !== (expected === void 0 ? void 0 : serializeValue(expected)))
+          return ok(false);
+        if (value === void 0) {
+          store.delete(key);
+        } else {
+          const expiresAt = options?.px !== void 0 ? Date.now() + options.px : options?.keepTtl ? entry?.expiresAt : void 0;
+          store.set(key, { value: deserializeValue(serializeValue(value)), expiresAt });
+        }
+        return ok(true);
+      } catch (error) {
+        return err(HaiCacheError.OPERATION_FAILED, cacheM("cache_operationFailed", { params: { error: "Compare-and-swap failed" } }), error);
+      }
+    },
     async get(key) {
-      const entry = getValidEntry(key);
-      return ok(entry ? entry.value : null);
+      try {
+        const entry = getValidEntry(key);
+        return ok(entry ? deserializeValue(serializeValue(entry.value)) : null);
+      } catch (error) {
+        return err(HaiCacheError.SERIALIZATION_FAILED, cacheM("cache_operationFailed", { params: { error: "JSON snapshot failed" } }), error);
+      }
     },
     async set(key, value, options) {
-      const existing = getValidEntry(key) !== null;
-      if (options?.nx && existing)
-        return ok(void 0);
-      if (options?.xx && !existing)
-        return ok(void 0);
+      const validated = validateSetOptions(options);
+      if (!validated.success)
+        return validated;
+      const policy = validated.data;
       const currentEntry = getValidEntry(key);
-      const expiresAt = options?.keepTtl && currentEntry ? currentEntry.expiresAt : calculateExpiry(options);
-      store.set(key, { value, expiresAt });
-      return ok(void 0);
+      const existing = currentEntry !== null || Boolean(hashStore.get(key)?.size || listStore.get(key)?.length || setStore.get(key)?.size || zsetStore.get(key)?.size);
+      if (policy.nx && existing || policy.xx && !existing)
+        return ok(false);
+      try {
+        const snapshot = deserializeValue(serializeValue(value));
+        const expiresAt = policy.keepTtl ? currentEntry?.expiresAt : policy.expiresAt;
+        hashStore.delete(key);
+        listStore.delete(key);
+        setStore.delete(key);
+        zsetStore.delete(key);
+        if (expiresAt !== void 0 && expiresAt <= Date.now())
+          store.delete(key);
+        else
+          store.set(key, { value: snapshot, expiresAt });
+        return ok(true);
+      } catch (error) {
+        return err(HaiCacheError.SERIALIZATION_FAILED, cacheM("cache_serializationFailed"), error);
+      }
     },
     async del(...keys) {
       let count = 0;
@@ -246,12 +344,16 @@ function createMemoryProvider() {
       return kv.incrBy(key, -decrement);
     },
     async mget(...keys) {
-      const results = [];
-      for (const key of keys) {
-        const entry = getValidEntry(key);
-        results.push(entry ? entry.value : null);
+      try {
+        const results = [];
+        for (const key of keys) {
+          const entry = getValidEntry(key);
+          results.push(entry ? deserializeValue(serializeValue(entry.value)) : null);
+        }
+        return ok(results);
+      } catch (error) {
+        return err(HaiCacheError.SERIALIZATION_FAILED, cacheM("cache_operationFailed", { params: { error: "JSON snapshot failed" } }), error);
       }
-      return ok(results);
     },
     async mset(entries) {
       for (const [key, value] of entries) {
@@ -260,6 +362,8 @@ function createMemoryProvider() {
       return ok(void 0);
     },
     async scan(cursor, options) {
+      if (typeof cursor !== "string" || !/^\d{1,20}$/.test(cursor) || BigInt(cursor) > 18446744073709551615n || !Number.isSafeInteger(options?.count ?? 10) || (options?.count ?? 10) <= 0)
+        return err(HaiCacheError.INVALID_SCAN, cacheM("cache_invalidScan"));
       const allKeys = Array.from(store.keys()).filter((key) => {
         const entry = store.get(key);
         return entry && !isExpired(entry);
@@ -267,10 +371,10 @@ function createMemoryProvider() {
       const regex = options?.match ? globToRegex(options.match) : null;
       const filtered = regex ? allKeys.filter((k) => regex.test(k)) : allKeys;
       const count = options?.count || 10;
-      const start = cursor;
+      const start = Number(cursor);
       const end = Math.min(start + count, filtered.length);
       const keys = filtered.slice(start, end);
-      const nextCursor = end >= filtered.length ? 0 : end;
+      const nextCursor = end >= filtered.length ? "0" : String(end);
       return ok([nextCursor, keys]);
     },
     async keys(pattern) {
@@ -754,16 +858,16 @@ function createMemoryProvider() {
     async acquire(key, options) {
       const lockKey = `${LOCK_PREFIX}${key}`;
       const ttl = options?.ttl ?? 30;
-      const owner = options?.owner ?? "default";
+      const owner = core.id.uuid();
       const existing = getValidEntry(lockKey);
       if (existing) {
-        return ok(false);
+        return ok(null);
       }
       store.set(lockKey, {
         value: owner,
         expiresAt: Date.now() + ttl * 1e3
       });
-      return ok(true);
+      return ok(owner);
     },
     async release(key, owner) {
       const lockKey = `${LOCK_PREFIX}${key}`;
@@ -771,7 +875,7 @@ function createMemoryProvider() {
       if (!entry) {
         return ok(false);
       }
-      if (owner !== void 0 && entry.value !== owner) {
+      if (!owner || entry.value !== owner) {
         return ok(false);
       }
       store.delete(lockKey);
@@ -788,7 +892,7 @@ function createMemoryProvider() {
       if (!entry) {
         return ok(false);
       }
-      if (owner !== void 0 && entry.value !== owner) {
+      if (!owner || entry.value !== owner) {
         return ok(false);
       }
       entry.expiresAt = Date.now() + ttl * 1e3;
@@ -828,19 +932,104 @@ function createMemoryProvider() {
     }
   };
 }
-var logger = core.logger.child({ module: "cache", scope: "redis" });
-function sanitizeRedisUrl(url) {
-  try {
-    const u = new URL(url);
-    if (u.password)
-      u.password = "***";
-    if (u.username)
-      u.username = "***";
-    return u.toString();
-  } catch {
-    return "(invalid url)";
+var RedisScanError = class extends Error {
+  constructor(reason) {
+    super(`Redis scan ${reason}`);
+    this.reason = reason;
+  }
+  reason;
+};
+var PositionSchema = z.string().regex(/^\d{1,20}$/).refine((value) => BigInt(value) <= 18446744073709551615n);
+var ClusterCursorSchema = z.object({
+  topology: z.string().regex(/^[a-f0-9]{64}$/),
+  node: z.number().int().nonnegative(),
+  position: PositionSchema
+});
+function sortedMasters(client) {
+  return client.nodes("master").sort((left, right) => {
+    const a = `${left.options.host}:${left.options.port}`;
+    const b = `${right.options.host}:${right.options.port}`;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+function escapeGlob(prefix) {
+  return prefix.replace(/[\\*?[\]]/g, "\\$&");
+}
+async function scanRedisKeys(client, cursor, options = {}) {
+  const prefix = client.options.keyPrefix ?? ("redisOptions" in client.options ? client.options.redisOptions?.keyPrefix : "") ?? "";
+  const count = options.count ?? 10;
+  if (!Number.isSafeInteger(count) || count <= 0 || typeof cursor !== "string" || cursor.length > 1024)
+    throw new RedisScanError("invalid");
+  const match = options.match ?? "*";
+  const pattern = `${escapeGlob(prefix)}${match}`;
+  let node;
+  let position = cursor;
+  let state;
+  let masters = [];
+  if ("nodes" in client) {
+    masters = sortedMasters(client);
+    const topology = createHash("sha256").update(JSON.stringify({
+      nodes: masters.map((master) => [master.options.host, master.options.port]),
+      // slot 所有者变化也使旧游标失效，避免无提示地跳过迁移数据。
+      slots: client.slots.map((nodes) => nodes[0]),
+      prefix,
+      match
+    })).digest("hex");
+    if (cursor === "0") {
+      state = { topology, node: 0, position: "0" };
+    } else {
+      if (!cursor.startsWith("c1."))
+        throw new RedisScanError("invalid");
+      try {
+        state = ClusterCursorSchema.parse(JSON.parse(Buffer.from(cursor.slice(3), "base64url").toString("utf8")));
+      } catch {
+        throw new RedisScanError("invalid");
+      }
+      if (state.topology !== topology)
+        throw new RedisScanError("topology");
+    }
+    if (masters.length === 0 || state.node >= masters.length)
+      throw new RedisScanError("topology");
+    node = masters[state.node];
+    position = state.position;
+  } else {
+    if (!PositionSchema.safeParse(cursor).success)
+      throw new RedisScanError("invalid");
+    node = client;
+  }
+  const [nextPosition, keys] = await node.scan(position, "MATCH", pattern, "COUNT", count);
+  const logicalKeys = keys.filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+  if (!state)
+    return [nextPosition, logicalKeys];
+  if (nextPosition === "0") {
+    state.node++;
+    state.position = "0";
+    if (state.node >= masters.length)
+      return ["0", logicalKeys];
+  } else {
+    state.position = nextPosition;
   }
+  return [`c1.${Buffer.from(JSON.stringify(state)).toString("base64url")}`, logicalKeys];
 }
+
+// src/providers/cache-provider-redis.ts
+var logger = core.logger.child({ module: "cache", scope: "redis" });
+var COMPARE_AND_SWAP_SCRIPT = `
+  local current = redis.call('get', KEYS[1])
+  if ARGV[1] == 'missing' then
+    if current then return 0 end
+  elseif current ~= ARGV[2] then return 0 end
+  if ARGV[3] == 'delete' then
+    redis.call('del', KEYS[1])
+  elseif ARGV[5] == 'keep' then
+    redis.call('set', KEYS[1], ARGV[4], 'KEEPTTL')
+  elseif ARGV[5] == 'px' then
+    redis.call('set', KEYS[1], ARGV[4], 'PX', ARGV[6])
+  else
+    redis.call('set', KEYS[1], ARGV[4])
+  end
+  return 1
+`;
 var RELEASE_LOCK_SCRIPT = `
   if redis.call("get", KEYS[1]) == ARGV[1] then
     return redis.call("del", KEYS[1])
@@ -857,6 +1046,30 @@ var EXTEND_LOCK_SCRIPT = `
 `;
 function createRedisProvider() {
   let client = null;
+  let ready = false;
+  let closing = null;
+  function closeClient() {
+    const graceful = ready && client?.status === "ready";
+    ready = false;
+    if (closing)
+      return closing;
+    const owned = client;
+    if (!owned)
+      return Promise.resolve();
+    closing = (async () => {
+      try {
+        if (graceful)
+          await owned.quit();
+      } catch (error) {
+        logger.warn("Redis graceful shutdown failed; disconnecting client", { error });
+      }
+      owned.disconnect();
+      client = null;
+    })().finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
   function serialize(value) {
     return JSON.stringify(value);
   }
@@ -870,7 +1083,7 @@ function createRedisProvider() {
     }
   }
   async function wrapOperation(operation) {
-    if (!client) {
+    if (!ready || !client) {
       return err(
         HaiCacheError.NOT_INITIALIZED,
         cacheM("cache_notInitialized")
@@ -880,6 +1093,11 @@ function createRedisProvider() {
       const result = await operation();
       return ok(result);
     } catch (error) {
+      if (error instanceof RedisScanError) {
+        return error.reason === "topology" ? err(HaiCacheError.SCAN_TOPOLOGY_CHANGED, cacheM("cache_scanTopologyChanged"), error) : err(HaiCacheError.INVALID_SCAN, cacheM("cache_invalidScan"), error);
+      }
+      if (error instanceof Error && error.message.startsWith("CROSSSLOT"))
+        return err(HaiCacheError.CROSS_SLOT, cacheM("cache_crossSlot"), error);
       return err(
         HaiCacheError.OPERATION_FAILED,
         cacheM("cache_operationFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
@@ -890,7 +1108,20 @@ function createRedisProvider() {
   function isRedisOne(result) {
     return result === 1 || result === "1";
   }
+  async function mapIndependentKeys(keys, operation) {
+    const values = [];
+    for (let offset = 0; offset < keys.length; offset += 64)
+      values.push(...await Promise.all(keys.slice(offset, offset + 64).map(operation)));
+    return values;
+  }
   const kv = {
+    async compareAndSwap(key, expected, value, options) {
+      return wrapOperation(async () => {
+        if (options?.px !== void 0 && (!Number.isSafeInteger(options.px) || options.px <= 0) || options?.px !== void 0 && options.keepTtl)
+          throw new TypeError("Invalid compare-and-swap expiry");
+        return isRedisOne(await client.eval(COMPARE_AND_SWAP_SCRIPT, 1, key, expected === void 0 ? "missing" : "value", expected === void 0 ? "" : serialize(expected), value === void 0 ? "delete" : "value", value === void 0 ? "" : serialize(value), options?.keepTtl ? "keep" : options?.px !== void 0 ? "px" : "none", options?.px ?? 0));
+      });
+    },
     async get(key) {
       return wrapOperation(async () => {
         const value = await client.get(key);
@@ -898,30 +1129,43 @@ function createRedisProvider() {
       });
     },
     async set(key, value, options) {
+      const validated = validateSetOptions(options);
+      if (!validated.success)
+        return validated;
       return wrapOperation(async () => {
+        const policy = validated.data;
         const args = [key, serialize(value)];
-        if (options?.ex)
-          args.push("EX", options.ex);
-        else if (options?.px)
-          args.push("PX", options.px);
-        else if (options?.exat)
-          args.push("EXAT", options.exat);
-        else if (options?.pxat)
-          args.push("PXAT", options.pxat);
-        if (options?.nx)
+        if (policy.expiry)
+          args.push(...policy.expiry);
+        if (policy.nx)
           args.push("NX");
-        else if (options?.xx)
+        else if (policy.xx)
           args.push("XX");
-        if (options?.keepTtl)
+        if (policy.keepTtl)
           args.push("KEEPTTL");
-        await client.set(...args);
+        const result = await client.call("SET", ...args);
+        if (result !== "OK" && result !== null)
+          throw new Error(cacheM("cache_setUnexpectedReply"));
+        return result === "OK";
       });
     },
     async del(...keys) {
-      return wrapOperation(() => client.del(...keys));
+      return wrapOperation(async () => {
+        if (keys.length === 0)
+          return 0;
+        if (client instanceof Redis.Cluster)
+          return (await mapIndependentKeys(keys, (key) => client.del(key))).reduce((sum, value) => sum + value, 0);
+        return client.del(...keys);
+      });
     },
     async exists(...keys) {
-      return wrapOperation(() => client.exists(...keys));
+      return wrapOperation(async () => {
+        if (keys.length === 0)
+          return 0;
+        if (client instanceof Redis.Cluster)
+          return (await mapIndependentKeys(keys, (key) => client.exists(key))).reduce((sum, value) => sum + value, 0);
+        return client.exists(...keys);
+      });
     },
     async expire(key, seconds) {
       return wrapOperation(async () => {
@@ -958,12 +1202,14 @@ function createRedisProvider() {
     },
     async mget(...keys) {
       return wrapOperation(async () => {
-        const values = await client.mget(...keys);
+        const values = keys.length === 0 ? [] : client instanceof Redis.Cluster ? await mapIndependentKeys(keys, (key) => client.get(key)) : await client.mget(...keys);
         return values.map((v) => deserialize(v));
       });
     },
     async mset(entries) {
       return wrapOperation(async () => {
+        if (entries.length === 0)
+          return;
         const args = [];
         for (const [key, value] of entries) {
           args.push(key, serialize(value));
@@ -972,23 +1218,19 @@ function createRedisProvider() {
       });
     },
     async scan(cursor, options) {
-      return wrapOperation(async () => {
-        let result;
-        if (options?.match && options?.count) {
-          result = await client.scan(cursor, "MATCH", options.match, "COUNT", options.count);
-        } else if (options?.match) {
-          result = await client.scan(cursor, "MATCH", options.match);
-        } else if (options?.count) {
-          result = await client.scan(cursor, "COUNT", options.count);
-        } else {
-          result = await client.scan(cursor);
-        }
-        const [nextCursor, keys] = result;
-        return [Number.parseInt(nextCursor, 10), keys];
-      });
+      return wrapOperation(() => scanRedisKeys(client, cursor, options));
     },
     async keys(pattern) {
-      return wrapOperation(() => client.keys(pattern));
+      return wrapOperation(async () => {
+        let cursor = "0";
+        const keys = /* @__PURE__ */ new Set();
+        do {
+          const page = await scanRedisKeys(client, cursor, { match: pattern, count: 100 });
+          cursor = page[0];
+          for (const key of page[1]) keys.add(key);
+        } while (cursor !== "0");
+        return [...keys];
+      });
     },
     async type(key) {
       return wrapOperation(() => client.type(key));
@@ -1273,20 +1515,18 @@ function createRedisProvider() {
       return wrapOperation(async () => {
         const lockKey = `${LOCK_PREFIX}${key}`;
         const ttl = options?.ttl ?? 30;
-        const owner = options?.owner ?? "default";
+        const owner = core.id.uuid();
         const result = await client.set(lockKey, owner, "EX", ttl, "NX");
-        return result === "OK";
+        return result === "OK" ? owner : null;
       });
     },
     async release(key, owner) {
       return wrapOperation(async () => {
         const lockKey = `${LOCK_PREFIX}${key}`;
-        if (owner !== void 0) {
-          const result = await client.eval(RELEASE_LOCK_SCRIPT, 1, lockKey, owner);
-          return isRedisOne(result);
-        }
-        const deleted = await client.del(lockKey);
-        return deleted === 1;
+        if (!owner)
+          return false;
+        const result = await client.eval(RELEASE_LOCK_SCRIPT, 1, lockKey, owner);
+        return isRedisOne(result);
       });
     },
     async isLocked(key) {
@@ -1299,12 +1539,10 @@ function createRedisProvider() {
     async extend(key, ttl, owner) {
       return wrapOperation(async () => {
         const lockKey = `${LOCK_PREFIX}${key}`;
-        if (owner !== void 0) {
-          const result2 = await client.eval(EXTEND_LOCK_SCRIPT, 1, lockKey, owner, ttl);
-          return isRedisOne(result2);
-        }
-        const result = await client.expire(lockKey, ttl);
-        return result === 1;
+        if (!owner)
+          return false;
+        const result = await client.eval(EXTEND_LOCK_SCRIPT, 1, lockKey, owner, ttl);
+        return isRedisOne(result);
       });
     }
   };
@@ -1330,7 +1568,9 @@ function createRedisProvider() {
         );
       }
       try {
+        await closeClient();
         const redisOptions = {
+          ...!config.url && config.password !== void 0 ? { password: config.password } : {},
           connectTimeout: config.connectTimeout,
           commandTimeout: config.commandTimeout,
           keyPrefix: config.keyPrefix,
@@ -1350,6 +1590,8 @@ function createRedisProvider() {
           client = new Redis(config.url, redisOptions);
         } else if (config.cluster && config.cluster.length > 0) {
           const clusterOptions = {
+            // Cluster 自身也必须延迟连接，避免构造时与下方显式 connect 竞争。
+            lazyConnect: true,
             redisOptions,
             clusterRetryStrategy: (times) => {
               if (times > config.maxRetries)
@@ -1363,7 +1605,6 @@ function createRedisProvider() {
             ...redisOptions,
             sentinels: config.sentinel.sentinels,
             name: config.sentinel.name,
-            password: config.password,
             db: config.db
           });
         } else {
@@ -1371,32 +1612,37 @@ function createRedisProvider() {
             ...redisOptions,
             host: config.host,
             port: config.port,
-            password: config.password,
             db: config.db
           });
         }
+        client.on("error", () => logger.warn("Redis client connection error"));
         await client.connect();
         await client.ping();
-        const address = config.url ? sanitizeRedisUrl(config.url) : `${config.host}:${config.port}`;
+        ready = true;
+        const address = config.url ? core.sanitize.sanitizeUrl(config.url) : `${config.host}:${config.port}`;
         logger.info("Redis connected", { address });
         return ok(void 0);
       } catch (error) {
-        return err(
+        ready = false;
+        let cleanupError;
+        try {
+          client?.disconnect();
+          client = null;
+        } catch (failure) {
+          cleanupError = failure;
+        }
+        const result = err(
           HaiCacheError.CONNECTION_FAILED,
           cacheM("cache_redisConnectionFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
           error
         );
+        if (cleanupError !== void 0 && !result.success)
+          return err({ ...result.error, ext: { cleanupPending: true, cleanupError } });
+        return result;
       }
     },
-    async close() {
-      if (client) {
-        logger.info("Disconnecting Redis");
-        await client.quit();
-        client = null;
-        logger.info("Redis disconnected");
-      }
-    },
-    isConnected: () => client !== null,
+    close: closeClient,
+    isConnected: () => ready && client !== null && client.status === "ready",
     kv,
     hash,
     list,
@@ -1414,6 +1660,40 @@ var logger2 = core.logger.child({ module: "cache", 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) {
+    logger2.error("Provider cleanup failed; retaining resource for retry", { error });
+    return err({ ...HaiCacheError.CONNECTION_FAILED, message: cacheM("cache_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 "memory":
@@ -1456,7 +1736,7 @@ var cache = {
    * ```
    */
   async init(config) {
-    if (initInProgress) {
+    if (initInProgress || closingPromise) {
       logger2.warn("Cache init already in progress, skipping concurrent call");
       return err(
         HaiCacheError.OPERATION_FAILED,
@@ -1464,11 +1744,14 @@ var cache = {
       );
     }
     initInProgress = true;
+    let resolveInit;
+    initCompletion = new Promise((resolve) => {
+      resolveInit = resolve;
+    });
     try {
-      if (currentProvider) {
-        logger2.warn("Cache module is already initialized, reinitializing");
-        await cache.close();
-      }
+      const cleanup = await closeOwnedProvider();
+      if (!cleanup.success)
+        return cleanup;
       logger2.info("Initializing cache module");
       const parseResult = CacheConfigSchema.safeParse(config);
       if (!parseResult.success) {
@@ -1480,35 +1763,41 @@ var cache = {
         );
       }
       const parsed = parseResult.data;
+      if (core.module.requiresSharedState(process.env) && parsed.type === "memory")
+        return err(HaiCacheError.CONFIG_ERROR, cacheM("cache_sharedBackendRequired"));
       try {
         const providerResult = createProvider(parsed);
         if (!providerResult.success)
           return err(providerResult.error);
         const provider = providerResult.data;
+        pendingProvider = provider;
         const connectResult = await provider.connect(parsed);
         if (!connectResult.success) {
           logger2.error("Cache module initialization failed", {
             code: connectResult.error.code,
             message: connectResult.error.message
           });
-          return connectResult;
+          return await failInitialization(connectResult);
         }
+        pendingProvider = null;
         currentProvider = provider;
         currentConfig = parsed;
         logger2.info("Cache module initialized", { type: parsed.type });
         return ok(void 0);
       } catch (error) {
         logger2.error("Cache module initialization failed", { error });
-        return err(
+        return await failInitialization(err(
           HaiCacheError.CONNECTION_FAILED,
           cacheM("cache_initFailed", {
             params: { error: error instanceof Error ? error.message : String(error) }
           }),
           error
-        );
+        ));
       }
     } finally {
       initInProgress = false;
+      initCompletion = null;
+      resolveInit();
     }
   },
   /** KV 操作子接口；未 init 时所有方法返回 NOT_INITIALIZED */
@@ -1551,23 +1840,24 @@ var cache = {
   ping() {
     return currentProvider?.ping() ?? Promise.resolve(notInitialized.result());
   },
-  /** 关闭缓存连接并释放资源；未初始化时调用安全无副作用 */
+  /**
+   * 停止提供缓存操作并释放资源；等待正在进行的初始化，并合并并发关闭。
+   * @returns 清理失败返回错误并保留资源，后续 close/init 先重试同一资源。
+   * @example
+   * const closed = await cache.close()
+   * if (!closed.success) await cache.close()
+   */
   async close() {
-    if (!currentProvider) {
-      currentConfig = null;
-      logger2.info("Cache module already closed, skipping");
-      return;
-    }
-    logger2.info("Closing cache module");
-    try {
-      await currentProvider.close();
-      logger2.info("Cache module closed");
-    } catch (error) {
-      logger2.error("Cache module close failed", { error });
-    } finally {
-      currentProvider = null;
-      currentConfig = null;
+    if (!closingPromise) {
+      closingPromise = (async () => {
+        if (initCompletion)
+          await initCompletion;
+        return await closeOwnedProvider();
+      })().finally(() => {
+        closingPromise = null;
+      });
     }
+    return await closingPromise;
   }
 };