baja-lite 1.8.9 → 1.8.11

package/cache.js

@@ -1,8 +1,86 @@
 import { DBType } from 'baja-lite-field';
 import { sleep } from './fn.js';
 import { Throw } from './error.js';
-import { _dao, _EventBus, _GlobalSqlOption, _LoggerService, _memCache, _memInflight, _primaryDB, } from './const/symbols.js';
-import { StorageType } from './const/index.js';
+import { _dao, _EventBus, _LoggerService, _primaryDB, } from './const/symbols.js';
+/** @internal 输出缓存分类日志（仅当 setLogLevels 包含 'cache' 时生效） */
+function cacheLog(message, ...params) {
+    const logger = globalThis[_LoggerService];
+    // pino-pretty 的 messageFormat 会根据 level=24 自动添加 [CACHE] 前缀
+    logger.debugCategory?.('cache', message, ...params);
+}
+/**
+ * @internal 全局 stale 刷新 Promise 映射。
+ *  key = 缓存 key（不含前缀），value = 正在进行的 stale 刷新 Promise。
+ * @MethodCache 内部的 staleBackgroundRefresh 通过这个映射注册刷新 Promise，
+ * 同一 key 的并发 stale 命中复用同一个 Promise，避免重复执行 fn()。
+ * Redis 后端下此映射是每个进程本地的；但因为 [cache-sf]key 在 Redis 里全局可见，
+ * 所以跨进程的 single-flight 仍然有效。
+ */
+const globalStaleInflight = new Map();
+/**
+ * @internal [cache] 前缀下的子 key 命名全部收拢到这里，避免散落在各处 magic string。
+ *
+ * 命名规范：
+ * - [cache]key                    缓存值（JSON: { v, d, s } — v=版本 d=数据 s=是否 stale）
+ * - [cache-sf]key                 single-flight 首飞标记（SETNX 抢锁用）
+ * - [cache-meta]key               stale-allowed 标记（带 TTL，与缓存同生命周期）
+ * - [cache-parent]key / [cache-child]key   关联清除的 parent↔child 双向 set
+ */
+const CacheKey = {
+    value: (k) => `[cache]${k}`,
+    sf: (k) => `[cache-sf]${k}`,
+    meta: (k) => `[cache-meta]${k}`,
+    parent: (k) => `[cache-parent]${k}`,
+    child: (k) => `[cache-child]${k}`,
+};
+/** @internal 序列化缓存值 */
+function serializeCacheValue(data, timestamp, stale = false, staleAllowed = false) {
+    const v = { t: timestamp, d: data };
+    if (stale)
+        v.s = 1;
+    if (staleAllowed)
+        v.sa = 1;
+    return JSON.stringify(v);
+}
+/** @internal 反序列化缓存值 */
+function deserializeCacheValue(raw) {
+    try {
+        const v = JSON.parse(raw);
+        return { ...v, isNullish: v.d === 'null' || v.d === 'undefined' };
+    }
+    catch {
+        // 旧格式兼容：纯字符串（无 JSON 包装）
+        return { t: 0, d: raw, isNullish: raw === 'null' || raw === 'undefined' };
+    }
+}
+/**
+ * @internal 统一的 stale-allowed 注册表 key。
+ * 用带 TTL 的 string（而非全局 set），每个 stale-allowed 缓存独立管理自己的标记。
+ * key = [cache-meta]realKey，value = '1'，TTL = 缓存 TTL。
+ * 好处：自动过期，不再需要全局 set，内存占用与缓存数量而非请求数量成正比。
+ */
+/**
+ * 缓存被清理时的行为策略。
+ * 由 @MethodCache 的 `staleMode` 配置决定，clearMethodCache 依此自动选择清理方式。
+ */
+export var CacheStaleMode;
+(function (CacheStaleMode) {
+    /**
+     * 默认。清理时直接删除缓存值，下次请求触发 single-flight 重建。
+     * 优点：数据强一致，不会读到旧值。
+     * 缺点：重建期间所有请求被阻塞，直到 fn() 执行完毕。
+     */
+    CacheStaleMode[CacheStaleMode["Purge"] = 0] = "Purge";
+    /**
+     * 清理时保留旧值并标记为过期（stale），同时设一个 stale 窗口（默认 30s）。
+     * 窗口内：请求仍读到旧值（零阻塞），同时后台 single-flight 异步刷新。
+     * 窗口过后：stale 标记自动消失，退化回 Purge 行为。
+     *
+     * 适用场景：读多写少、能容忍秒级旧数据、fn() 执行代价高。
+     * 注意：开启后业务层可能收到乱序数据，需自行处理（如按时间戳丢弃过期包）。
+     */
+    CacheStaleMode[CacheStaleMode["StaleWhileRevalidate"] = 1] = "StaleWhileRevalidate";
+})(CacheStaleMode || (CacheStaleMode = {}));
 export function getRedisDB(db) {
     const rd = globalThis[_dao][DBType.Redis][db ?? _primaryDB];
     Throw.if(!rd, 'not found redis!');
@@ -37,7 +115,7 @@ export async function GetRedisLock(key, lockMaxActive) {
             lastError = er;
             // 指数退避，避免 redis 抖动时打死服务
             const delay = Math.min(GET_REDIS_LOCK_BASE_DELAY * Math.pow(2, attempt), 1000);
-            globalThis[_LoggerService].debug?.(`GetRedisLock ${key} attempt ${attempt + 1} failed: ${er?.message}, retry after ${delay}ms`);
+            globalThis[_LoggerService].debugCategory?.('sql', `GetRedisLock ${key} attempt ${attempt + 1} failed: ${er?.message}, retry after ${delay}ms`);
             await sleep(delay);
         }
         finally {
@@ -63,24 +141,24 @@ export async function excuteWithLock(config, fn__) {
         const lock = await GetRedisLock(key, config.lockMaxActive);
         if (lock === false) {
             if (config.lockWait !== false && ((config.lockMaxWaitTime ?? 0) === 0 || (wait_time + (config.lockRetryInterval ?? 100)) <= (config.lockMaxWaitTime ?? 0))) {
-                globalThis[_LoggerService].debug?.(`get lock ${key} fail, retry after ${config.lockRetryInterval ?? 100}ms...`);
+                globalThis[_LoggerService].debugCategory?.('sql', `get lock ${key} fail, retry after ${config.lockRetryInterval ?? 100}ms...`);
                 await sleep(config.lockRetryInterval ?? 100);
                 wait_time += (config.lockRetryInterval ?? 100);
                 return await fn();
             }
             else {
-                globalThis[_LoggerService].debug?.(`get lock ${key} fail`);
+                globalThis[_LoggerService].debugCategory?.('sql', `get lock ${key} fail`);
                 throw new Error(config.errorMessage || `get lock fail: ${key}`);
             }
         }
         else {
-            globalThis[_LoggerService].debug?.(`get lock ${key} ok!`);
+            globalThis[_LoggerService].debugCategory?.('sql', `get lock ${key} ok!`);
             await db.pexpire(key, config.lockMaxTime ?? 60000);
             try {
                 return await fn__();
             }
             finally {
-                globalThis[_LoggerService].debug?.(`unlock ${key} ok!`);
+                globalThis[_LoggerService].debugCategory?.('sql', `unlock ${key} ok!`);
                 await db.decr(key);
             }
         }
@@ -105,114 +183,10 @@ export function MethodLock(config) {
         };
     };
 }
-/** 全局 LRU 上限。可在 boot 时通过 `globalThis[_GlobalSqlOption].memCacheMaxSize` 覆盖。 */
-const MEMORY_CACHE_DEFAULT_MAX_SIZE = 10000;
-function getMemCache() {
-    let m = globalThis[_memCache];
-    if (!m) {
-        m = new Map();
-        globalThis[_memCache] = m;
-    }
-    return m;
-}
-function getMemInflight() {
-    let m = globalThis[_memInflight];
-    if (!m) {
-        m = new Map();
-        globalThis[_memInflight] = m;
-    }
-    return m;
-}
-function getMemCacheMaxSize() {
-    return globalThis[_GlobalSqlOption]?.memCacheMaxSize ?? MEMORY_CACHE_DEFAULT_MAX_SIZE;
-}
-/** 内存版的 parent→children 关联表，对应 redis 的 [cache-parent]* / [cache-child]* set。 */
-const memParentChild = {
-    parentToChildren: new Map(),
-    childToParents: new Map(),
-    link(parents, child) {
-        for (const p of parents) {
-            let s = this.parentToChildren.get(p);
-            if (!s) {
-                s = new Set();
-                this.parentToChildren.set(p, s);
-            }
-            s.add(child);
-            let r = this.childToParents.get(child);
-            if (!r) {
-                r = new Set();
-                this.childToParents.set(child, r);
-            }
-            r.add(p);
-        }
-    },
-    unlinkChild(child) {
-        const parents = this.childToParents.get(child);
-        if (!parents)
-            return;
-        for (const p of parents) {
-            this.parentToChildren.get(p)?.delete(child);
-        }
-        this.childToParents.delete(child);
-    },
-    drainParent(parent) {
-        const children = this.parentToChildren.get(parent);
-        if (!children)
-            return [];
-        const list = [...children];
-        for (const c of list) {
-            this.childToParents.get(c)?.delete(parent);
-        }
-        this.parentToChildren.delete(parent);
-        return list;
-    }
-};
 /**
- * 写一条内存缓存。
- * - 用 Map 的插入顺序天然实现 LRU：先 delete 再 set，把 key 放到尾部；
- *   超过上限时从头部（最少最近使用）开始淘汰。
- * - `cacheNullValue=true` 时，null/undefined 也会以 null 形式写入（防穿透）。
+ * 内存 LRU 条目，存储格式与 Redis 一致（CacheValue）。
+ * `expiresAt = 0` 表示永不过期。
  */
-function memSet(key, result, config) {
-    const isNullish = result === null || result === undefined;
-    if (isNullish && !config.cacheNullValue) {
-        return;
-    }
-    const ttlMinutes = isNullish ? (config.nullCacheTime ?? config.autoClearTime) : config.autoClearTime;
-    const expiresAt = ttlMinutes ? Date.now() + ttlMinutes * 60000 : 0;
-    const value = isNullish ? null : result;
-    const cache = getMemCache();
-    if (cache.has(key))
-        cache.delete(key);
-    cache.set(key, { value, expiresAt });
-    const max = getMemCacheMaxSize();
-    while (cache.size > max) {
-        const oldest = cache.keys().next().value;
-        if (oldest === undefined)
-            break;
-        cache.delete(oldest);
-        memParentChild.unlinkChild(oldest);
-    }
-    if (config.clearKey && config.clearKey.length > 0) {
-        memParentChild.link(config.clearKey, key);
-    }
-    globalThis[_LoggerService].debug?.(`memcache ${key} seted${isNullish ? ' (null)' : ''}!`);
-}
-/** 读内存缓存，lazy expire。命中后挪到 LRU 尾部。 */
-function memGet(key) {
-    const cache = getMemCache();
-    const entry = cache.get(key);
-    if (!entry)
-        return { hit: false };
-    if (entry.expiresAt !== 0 && entry.expiresAt <= Date.now()) {
-        cache.delete(key);
-        memParentChild.unlinkChild(key);
-        return { hit: false };
-    }
-    cache.delete(key);
-    cache.set(key, entry);
-    return { hit: true, value: entry.value };
-}
 /** 设置方法缓存 */
 async function setMethodCache(config, devid) {
     const db = getRedisDB();
@@ -222,7 +196,7 @@ async function setMethodCache(config, devid) {
         return;
     }
     // 统一序列化：undefined 不是合法 JSON，归一化成 null。
-    const payload = isNullish ? 'null' : JSON.stringify(config.result);
+    const dataStr = isNullish ? 'null' : JSON.stringify(config.result);
     // 负缓存通常用更短 TTL，避免业务恢复后还长时间返回旧的 null。
     const ttl = isNullish
         ? (config.nullCacheTime ?? config.autoClearTime)
@@ -230,100 +204,122 @@ async function setMethodCache(config, devid) {
     // 映射关系存放（负缓存也参与关联清除，因为外部清缓存的语义不区分正负）
     if (config.clearKey && config.clearKey.length > 0) {
         for (const clear of config.clearKey) {
-            await db.sadd(`[cache-parent]${clear}`, config.key);
-            await db.sadd(`[cache-child]${config.key}`, clear);
+            await db.sadd(CacheKey.parent(clear), config.key);
+            await db.sadd(CacheKey.child(config.key), clear);
         }
     }
+    // 写入缓存值（带时间戳 + staleAllowed 标志）。
+    // 保留旧 sa：只有显式 StaleWhileRevalidate 才设 1，否则沿用旧值（防止覆盖已有的 sa=1）。
+    const timestamp = Date.now();
+    const existingSa = await db.get(CacheKey.value(config.key)).then(r => r ? deserializeCacheValue(r).sa : undefined);
+    const staleAllowed = config.staleMode === CacheStaleMode.StaleWhileRevalidate ? true : (existingSa ?? false);
+    const payload = serializeCacheValue(dataStr, timestamp, false, staleAllowed);
     if (ttl) { // 自动清空
-        await db.set(`[cache]${config.key}`, payload, 'EX', ttl * 60);
-        globalThis[_LoggerService].debug?.(`cache ${config.key} seted${isNullish ? ' (null)' : ''}!`);
-        // 订阅：清空 clear list —— 同一 key 在缓存生命周期内只注册一次监听器，
-        // 否则每次 miss 都会 .on 一次，clearMethodCache 触发时回调会被执行 N 遍，
-        // 长期运行造成监听器泄漏。
-        if (config.clearKey && config.clearKey.length > 0) {
-            const event = `[cache]${config.key}`;
-            if (globalThis[_EventBus].listenerCount(event) === 0) {
-                globalThis[_EventBus].on(event, async (key) => {
-                    await clearChild(key, true);
-                    globalThis[_LoggerService].debug?.(`cache ${key} clear by key!`);
-                });
-            }
-        }
+        await db.set(CacheKey.value(config.key), payload, 'EX', ttl * 60);
+        cacheLog(`cache ${config.key} seted t${timestamp}${isNullish ? ' (null)' : ''}!`);
     }
     else {
-        await db.set(`[cache]${config.key}`, payload);
-        globalThis[_LoggerService].debug?.(`cache ${config.key} seted${isNullish ? ' (null)' : ''}!`);
+        await db.set(CacheKey.value(config.key), payload);
+        cacheLog(`cache ${config.key} seted t${timestamp}${isNullish ? ' (null)' : ''}!`);
+    }
+    // staleAllowed 已存储在缓存值内部（CacheValue.sa），无需单独的 meta key
+    // 删除旧格式残留（兼容升级）
+    await db.del(CacheKey.meta(config.key));
+    // 订阅：清空 clear list —— 同一 key 在缓存生命周期内只注册一次监听器，
+    // 否则每次 miss 都会 .on 一次，clearMethodCache 触发时回调会被执行 N 遍，
+    // 长期运行造成监听器泄漏。
+    if (config.clearKey && config.clearKey.length > 0) {
+        const event = CacheKey.value(config.key);
+        if (globalThis[_EventBus].listenerCount(event) === 0) {
+            globalThis[_EventBus].on(event, async (key) => {
+                await clearCacheKey(key);
+                cacheLog(`cache ${key} clear by key!`);
+            });
+        }
     }
     if (devid) {
         // 订阅：清空 clear list —— 同样去重，避免每次 miss 都重复注册。
         const event = `user-${devid}`;
         if (globalThis[_EventBus].listenerCount(event) === 0) {
-            globalThis[_EventBus].on(event, async function (key) {
-                await clearChild(key);
-                globalThis[_LoggerService].debug?.(`cache ${key} clear by devid!`);
+            globalThis[_EventBus].on(event, async (key) => {
+                await clearCacheKey(key);
+                cacheLog(`cache ${key} clear by devid!`);
             });
         }
     }
 }
 /**
- * 清空方法缓存。同时清 redis 和 memory 两边，业务侧无需关心存储是哪种。
- * - redis 侧只在配置了 redis 时才操作；没配 redis 时安静跳过，不抛错。
- * - 关联清除（clearKey）在两边都生效。
+ * 单个缓存 key 的 stale-or-purge 决策与执行。
+ * - CacheValue.sa=1 → 标记 s=1（保留缓存值，StaleWhileRevalidate）
+ * - 否则 → 直接删缓存值（Purge）
+ *
+ * 无论哪种路径，parent↔child 关联关系都清理。
+ *
+ * @returns 受影响的 children 列表（parent 路径会返回所有被级联清理的 child key）
  */
-export async function clearMethodCache(key) {
-    // 内存侧
-    const cache = getMemCache();
-    // 1. 如果 key 是 parent，把它关联的所有 children 都清掉
-    const childrenFromParent = memParentChild.drainParent(key);
-    for (const child of childrenFromParent) {
-        cache.delete(child);
-        memParentChild.unlinkChild(child);
-    }
-    // 2. 如果 key 本身是个缓存条目，直接清，并清掉它的反向链接
-    if (cache.has(key)) {
-        cache.delete(key);
-    }
-    memParentChild.unlinkChild(key);
-    // redis 侧：没配 redis 时跳过
-    const redisDao = globalThis[_dao]?.[DBType.Redis]?.[_primaryDB];
-    if (!redisDao)
-        return;
+async function clearCacheKey(key) {
     const db = getRedisDB();
-    let type = await db.type(`[cache-parent]${key}`);
-    if (type === 'set') {
-        await clearParent(key);
+    const affectedChildren = [];
+    // 1. 先处理 parent 级联：把关联的 children 全部清掉
+    const parentType = await db.type(CacheKey.parent(key));
+    if (parentType === 'set') {
+        const childKeys = await db.smembers(CacheKey.parent(key));
+        for (const child of childKeys) {
+            cacheLog(`cache ${child} cleared via parent ${key}!`);
+            await clearCacheKey(child);
+            affectedChildren.push(child);
+        }
+        await db.del(CacheKey.parent(key));
     }
-    type = await db.type(`[cache]${key}`);
-    if (type !== 'none') {
-        await clearChild(key);
+    // 2. 判断 stale-allowed：查缓存值内部的 sa 标志
+    const valueRaw = await db.get(CacheKey.value(key));
+    const v = valueRaw ? deserializeCacheValue(valueRaw) : null;
+    if (v?.sa) {
+        // stale-allowed：保留缓存值，标记 s=1，同时保留 sa=1（防止下次 clear 变成 purge）
+        const newPayload = serializeCacheValue(v.d, v.t, true, true);
+        const ttlSec = await db.ttl(CacheKey.value(key));
+        if (ttlSec > 0) {
+            await db.set(CacheKey.value(key), newPayload, 'EX', ttlSec);
+        }
+        else {
+            await db.set(CacheKey.value(key), newPayload);
+        }
+        cacheLog(`cache ${key} marked stale (t${v.t})`);
     }
-}
-async function clearChild(key, skipDel = false) {
-    const db = getRedisDB();
-    if (skipDel === false) {
-        await db.del(`[cache]${key}`);
+    else {
+        // Purge：直接删缓存值
+        await db.del(CacheKey.value(key));
+        cacheLog(`cache ${key} purged!`);
     }
-    const childtype = await db.type(`[cache-child]${key}`);
-    if (childtype === 'set') {
-        const parentKeys = await db.smembers(`[cache-child]${key}`);
-        for (const clear of parentKeys) {
-            const type = await db.type(`[cache-parent]${clear}`);
-            if (type === 'set') {
-                await db.srem(`[cache-parent]${clear}`, key);
+    // 清理旧格式残留
+    await db.del(CacheKey.meta(key));
+    // 3. 清理 child→parent 反向关联
+    const childType = await db.type(CacheKey.child(key));
+    if (childType === 'set') {
+        const parentKeys = await db.smembers(CacheKey.child(key));
+        for (const pk of parentKeys) {
+            const t = await db.type(CacheKey.parent(pk));
+            if (t === 'set') {
+                await db.srem(CacheKey.parent(pk), key);
             }
         }
-        await db.del(`[cache-child]${key}`);
+        await db.del(CacheKey.child(key));
     }
+    return affectedChildren;
 }
-async function clearParent(clearKey) {
-    const db = getRedisDB();
-    const keys = await db.smembers(`[cache-parent]${clearKey}`);
-    if (keys) {
-        for (const key of keys) {
-            globalThis[_LoggerService].debug?.(`cache ${key} cleared!`);
-            await clearChild(key);
-        }
-    }
+/**
+ * 清空方法缓存。
+ * - redis 侧只在配置了 redis 时才操作；没配 redis 时安静跳过，不抛错。
+ * - 关联清除（clearKey）生效。
+ * - 被清理的 key 如果启用了 StaleWhileRevalidate（CacheValue.sa=1），会保留旧值并标记 stale。
+ *
+ * @param key  要清理的缓存 key 或 parent key
+ */
+export async function clearMethodCache(key) {
+    const redisDao = globalThis[_dao]?.[DBType.Redis]?.[_primaryDB];
+    if (!redisDao)
+        return;
+    await clearCacheKey(key);
 }
 /**
  * Redis 缓存执行：先查缓存 → miss 后单飞抢锁执行 → 其它等待者只盯缓存、不抢锁。
@@ -336,30 +332,92 @@ async function clearParent(clearKey) {
  * 命中判断用 `cached !== null`（ioredis 在 key 不存在时返回 `null`），
  * 这样 `cacheNullValue=true` 时存进去的字面量 `'null'` 也会算作命中，达到防穿透效果。
  *
+ * 命中时若发现 stale 标志（CacheValue.s=1），说明该值是"已被声明过期但保留的旧值"，
+ * 此时仍返回旧值（零阻塞），同时触发后台 single-flight 异步刷新。
+ * 这样 clearMethodCache 后的首次读取不会被阻塞，后续读取将命中刷新后的新值。
+ *
  * redis 不可用或 SETNX 异常时退化为无锁直跑，保留可用性。
  */
 const SINGLEFLIGHT_LOCK_TTL_MS = 30000; // 首飞标记 TTL，兜底首飞挂掉的情况
 const SINGLEFLIGHT_POLL_INTERVAL_MS = 50; // 等待者轮询缓存的间隔
 const SINGLEFLIGHT_MAX_WAIT_MS = 30000; // 等待者最长等多久；超时就自己跑 fn（保底，不应该常发生）
+/**
+ * 后台异步刷新：fire-and-forget，不阻塞调用方。
+ * 只有抢到首飞标记的实例才会执行 fn() 并写缓存；其它实例直接放弃。
+ * 刷新完成后删除 stale 标记，后续读取将命中新值。
+ * 如果配置了 onCacheUpdated 回调，调用时传入 ctx（方法的 this 上下文）。
+ */
+async function staleBackgroundRefresh(opts, setOpts) {
+    const db = getRedisDB();
+    const sfKey = CacheKey.sf(opts.key);
+    try {
+        const ok = await db.set(sfKey, '1', 'PX', SINGLEFLIGHT_LOCK_TTL_MS, 'NX');
+        if (ok !== 'OK')
+            return; // 别人已经在刷新了，自己放弃
+    }
+    catch {
+        return; // redis 出错，放弃刷新，下次读取再试
+    }
+    try {
+        const result = await opts.fn();
+        // 写新值（setMethodCache 内部会清除 stale 标志 s=1）
+        await setMethodCache({ key: opts.key, ...setOpts, result }, opts.devid);
+        // 调用缓存更新回调（带 ctx）
+        void opts.onCacheUpdated?.call(opts.ctx, result, ...(opts.args ?? []));
+        cacheLog(`cache ${opts.key} stale background refresh done!`);
+    }
+    catch (error) {
+        globalThis[_LoggerService].warn?.(`cache ${opts.key} stale background refresh failed: ${error?.message}`);
+    }
+    finally {
+        try {
+            await db.del(sfKey);
+        }
+        catch { /* TTL 兜底 */ }
+    }
+}
 async function redisCacheCore(opts) {
     const db = getRedisDB();
-    const cacheKey = `[cache]${opts.key}`;
-    const cached = await db.get(cacheKey);
-    if (cached !== null) {
-        globalThis[_LoggerService].debug?.(`cache ${opts.key} hit!`);
-        return JSON.parse(cached);
+    const cacheKey = CacheKey.value(opts.key);
+    const raw = await db.get(cacheKey);
+    if (raw !== null) {
+        // 一次读取拿到全部信息（值 + stale 状态）
+        const v = deserializeCacheValue(raw);
+        const isStale = v.s === 1;
+        if (isStale) {
+            // stale 窗口内：返回旧值 + 触发后台刷新（不阻塞）
+            cacheLog(`cache ${opts.key} hit (stale t${v.t})!`);
+            const setOpts = {
+                clearKey: opts.clearKey,
+                autoClearTime: opts.autoClearTime,
+                cacheNullValue: opts.cacheNullValue,
+                nullCacheTime: opts.nullCacheTime,
+                staleMode: opts.staleMode
+            };
+            if (!globalStaleInflight.has(opts.key)) {
+                const refreshP = staleBackgroundRefresh(opts, setOpts).finally(() => {
+                    globalStaleInflight.delete(opts.key);
+                });
+                globalStaleInflight.set(opts.key, refreshP);
+            }
+        }
+        else {
+            cacheLog(`cache ${opts.key} hit (t${v.t})!`);
+        }
+        return JSON.parse(v.d);
     }
-    globalThis[_LoggerService].debug?.(`cache ${opts.key} miss!`);
+    cacheLog(`cache ${opts.key} miss!`);
     const setOpts = {
         clearKey: opts.clearKey,
         autoClearTime: opts.autoClearTime,
         cacheNullValue: opts.cacheNullValue,
-        nullCacheTime: opts.nullCacheTime
+        nullCacheTime: opts.nullCacheTime,
+        staleMode: opts.staleMode
     };
     // 用一个独立的"首飞标记" key 选出谁去执行 fn——SET NX PX 是原子操作，
     // 同一时刻只有一个调用者拿到 true，其它返回 null。这把"标记"不重入也不计数，
     // 只是个 single-flight 指示器，和 redlock / GetRedisLock 的并发计数器不冲突。
-    const sfKey = `[sf]${opts.key}`;
+    const sfKey = CacheKey.sf(opts.key);
     let isLeader = false;
     try {
         const ok = await db.set(sfKey, '1', 'PX', SINGLEFLIGHT_LOCK_TTL_MS, 'NX');
@@ -370,6 +428,7 @@ async function redisCacheCore(opts) {
         globalThis[_LoggerService].warn?.(`single-flight setnx ${opts.key} failed: ${error?.message}, fallback to no-lock`);
         const result = await opts.fn();
         await setMethodCache({ key: opts.key, ...setOpts, result }, opts.devid);
+        void opts.onCacheUpdated?.call(opts.ctx, result, ...(opts.args ?? []));
         return result;
     }
     if (isLeader) {
@@ -377,6 +436,7 @@ async function redisCacheCore(opts) {
         try {
             const result = await opts.fn();
             await setMethodCache({ key: opts.key, ...setOpts, result }, opts.devid);
+            void opts.onCacheUpdated?.call(opts.ctx, result, ...(opts.args ?? []));
             return result;
         }
         finally {
@@ -394,18 +454,19 @@ async function redisCacheCore(opts) {
         await sleep(SINGLEFLIGHT_POLL_INTERVAL_MS);
         const recheck = await db.get(cacheKey);
         if (recheck !== null) {
-            globalThis[_LoggerService].debug?.(`cache ${opts.key} hit after wait!`);
-            return JSON.parse(recheck);
+            cacheLog(`cache ${opts.key} hit after wait!`);
+            return JSON.parse(deserializeCacheValue(recheck).d);
         }
         // 首飞挂了（TTL 到期，sf 标记自动消失）但缓存仍然空——抢做下一任首飞
         const leaderGone = await db.get(sfKey);
         if (leaderGone === null) {
             const taken = await db.set(sfKey, '1', 'PX', SINGLEFLIGHT_LOCK_TTL_MS, 'NX');
             if (taken === 'OK') {
-                globalThis[_LoggerService].debug?.(`cache ${opts.key}: previous leader gone, taking over`);
+                cacheLog(`cache ${opts.key}: previous leader gone, taking over`);
                 try {
                     const result = await opts.fn();
                     await setMethodCache({ key: opts.key, ...setOpts, result }, opts.devid);
+                    void opts.onCacheUpdated?.call(opts.ctx, result, ...(opts.args ?? []));
                     return result;
                 }
                 finally {
@@ -422,56 +483,20 @@ async function redisCacheCore(opts) {
             globalThis[_LoggerService].warn?.(`cache ${opts.key}: wait timed out, running fn without lock`);
             const result = await opts.fn();
             await setMethodCache({ key: opts.key, ...setOpts, result }, opts.devid);
+            void opts.onCacheUpdated?.call(opts.ctx, result, ...(opts.args ?? []));
             return result;
         }
     }
 }
-/**
- * 内存缓存执行：单进程内的 single-flight 不需要任何分布式协调——
- * JS 单线程 + 同一份 in-flight Map 就够了。同一 key 的并发调用全部 await 同一个 Promise，
- * Promise 解析后所有等待者下个事件循环 tick 并发返回，零序列化、零 redis 往返。
- */
-async function memoryCacheCore(opts) {
-    const cacheKey = opts.key;
-    // 1. 看缓存
-    const hit = memGet(cacheKey);
-    if (hit.hit) {
-        globalThis[_LoggerService].debug?.(`memcache ${opts.key} hit!`);
-        return hit.value;
-    }
-    globalThis[_LoggerService].debug?.(`memcache ${opts.key} miss!`);
-    // 2. 已有等待中的 Promise → 直接 await，single-flight 自动达成
-    const inflight = getMemInflight();
-    const existing = inflight.get(cacheKey);
-    if (existing) {
-        return await existing;
-    }
-    // 3. 首飞：把 Promise 提前塞进 inflight，让后到者命中
-    const p = (async () => {
-        try {
-            const result = await opts.fn();
-            memSet(cacheKey, result, {
-                autoClearTime: opts.autoClearTime,
-                cacheNullValue: opts.cacheNullValue,
-                nullCacheTime: opts.nullCacheTime,
-                clearKey: opts.clearKey
-            });
-            return result;
-        }
-        finally {
-            inflight.delete(cacheKey);
-        }
-    })();
-    inflight.set(cacheKey, p);
-    return await p;
-}
+/** @internal 唯一的执行入口（Memory 后端已移除） */
 async function excuteCacheCore(opts) {
-    return opts.storage === StorageType.Memory ? await memoryCacheCore(opts) : await redisCacheCore(opts);
+    return await redisCacheCore(opts);
 }
 /**
  * 执行一个方法fn，
  * 如果有缓存，则返回缓存，否则【加锁、二次检查】后执行方法并缓存，防止缓存击穿。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透；负缓存默认沿用 autoClearTime，可单独用 nullCacheTime 设短。
+ * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
  */
 export async function excuteWithCache(config, fn) {
     const key = typeof config.key === 'function' ? config.key() : config.key;
@@ -481,7 +506,10 @@ export async function excuteWithCache(config, fn) {
         autoClearTime: config.autoClearTime,
         cacheNullValue: config.cacheNullValue,
         nullCacheTime: config.nullCacheTime,
-        storage: config.storage,
+        staleMode: config.staleMode,
+        onCacheUpdated: config.onCacheUpdated,
+        ctx: config.ctx,
+        args: config.args ?? [],
         fn
     });
 }
@@ -489,7 +517,8 @@ export async function excuteWithCache(config, fn) {
  * 缓存注解：先查缓存 → miss 才加锁 → 锁内再查一次 → 仍 miss 才执行原方法。
  * 已内置 single-flight，不需要再叠 `@MethodLock`。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透。
- * 可选 `storage: 'memory'` 用进程内 LRU 替代 redis（单进程场景，毫秒级延迟）。
+ * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
+ * 可选 `onCacheUpdated` 设置缓存更新回调（带 this 上下文）。
  */
 export function MethodCache(config) {
     return function (_target, _propertyKey, descriptor) {
@@ -506,10 +535,59 @@ export function MethodCache(config) {
                 autoClearTime: config.autoClearTime,
                 cacheNullValue: config.cacheNullValue,
                 nullCacheTime: config.nullCacheTime,
-                storage: config.storage,
+                staleMode: config.staleMode,
+                onCacheUpdated: config.onCacheUpdated,
+                ctx: this, // 传递当前 this 上下文
+                args, // 传递方法输入参数
                 devid,
                 fn: async () => await fn.call(this, ...args)
             });
         };
     };
 }
+/**
+ * 外部直接设置缓存值。用于绕过 @MethodCache 装饰器直接更新缓存的场景
+ * （如外部事件驱动的数据变更、手动刷新等）。
+ *
+ * 内部使用统一格式 { t, d, s, sa } 序列化，确保与 @MethodCache 的读取逻辑兼容。
+ *
+ * @param cacheKey   缓存 key（不含 [cache] 前缀，与 @MethodCache 的 key 一致）
+ * @param value      要缓存的值
+ * @param options    选项
+ *
+ * @example
+ * ```ts
+ * // 外部事件驱动更新缓存
+ * await setCache('match-timer-123', timer, { autoClearTime: 120 });
+ *
+ * // 同时触发 onCacheUpdated 回调（如果有）
+ * await setCache('match-timer-123', timer, {
+ *     autoClearTime: 120,
+ *     onCacheUpdated(this: MyService, value) {
+ *         this.broadcast(value);
+ *     }
+ * });
+ * ```
+ */
+export async function setCache(cacheKey, value, options = {}) {
+    const { autoClearTime, cacheNullValue = false, onCacheUpdated, ctx, args = [] } = options;
+    const isNullish = value === null || value === undefined;
+    if (isNullish && !cacheNullValue) {
+        return;
+    }
+    const dataStr = isNullish ? 'null' : JSON.stringify(value);
+    const timestamp = Date.now();
+    const db = getRedisDB();
+    // 保留旧 sa：沿用已有标志（防止外部直写清掉 sa=1，导致 clearMethodCache 变 purge）
+    const existingSa = await db.get(CacheKey.value(cacheKey)).then(r => r ? deserializeCacheValue(r).sa : undefined);
+    const payload = serializeCacheValue(dataStr, timestamp, false, !!existingSa);
+    if (autoClearTime) {
+        await db.set(CacheKey.value(cacheKey), payload, 'EX', autoClearTime * 60);
+    }
+    else {
+        await db.set(CacheKey.value(cacheKey), payload);
+    }
+    // 触发回调
+    void onCacheUpdated?.call(ctx, value, ...args);
+    cacheLog(`cache ${cacheKey} externally set (t${timestamp})`);
+}