nolo-cli 0.1.12 → 0.1.14

package/database/actions/read.ts

@@ -0,0 +1,337 @@
+// 文件路径: database/actions/read.ts
+
+import type { AppThunkApi } from "app/store";
+import { getRuntimeServerContext } from "database/runtimeServerContext";
+import {
+  fetchFromClientDb,
+  fetchFromServer,
+  isReadTimeoutError,
+  logger,
+} from "./common";
+import { readRequestManager } from "./readRequestManager";
+import { shouldReplaceWithNextRecord } from "../tombstones";
+import { scheduleExistingRecordReplication } from "./replication";
+
+// --- 辅助函数 ---
+
+const updateClientDbIfNewer = async (
+  clientDb: any,
+  dbKey: string,
+  remoteData: any,
+  localData: any
+): Promise<void> => {
+  if (!clientDb) return;
+  try {
+    if (isRemoteDataNewer(remoteData, localData)) {
+      await clientDb.put(dbKey, remoteData);
+    }
+  } catch (err) {
+    throw err;
+  }
+};
+
+const isRemoteDataNewer = (remoteData: any, localData: any): boolean => {
+  if (!remoteData || typeof remoteData !== "object") return false;
+  if (!localData || typeof localData !== "object") return true;
+  return shouldReplaceWithNextRecord(remoteData, localData);
+};
+
+const shouldSyncLocalToServer = (localData: any, remoteData: any): boolean => {
+  return !!localData && !remoteData;
+};
+
+const syncLocalDataToServer = async (
+  thunkApi: AppThunkApi,
+  dbKey: string,
+  localData: any
+): Promise<void> => {
+  try {
+    const state = thunkApi.getState();
+    const { currentServer, syncServers } = getRuntimeServerContext(state);
+    scheduleExistingRecordReplication({
+      currentServer,
+      syncServers,
+      dbKey,
+      localData,
+      state,
+    });
+  } catch (err) {
+    // Error ignored
+  }
+};
+
+const saveRemoteDataToClientDb = async (
+  clientDb: any,
+  dbKey: string,
+  remoteData: any,
+  serverOrigin?: string | null
+): Promise<void> => {
+  if (!clientDb) return;
+  try {
+    await clientDb.put(
+      dbKey,
+      serverOrigin
+        ? {
+            ...remoteData,
+            serverOrigin,
+          }
+        : remoteData
+    );
+  } catch (err) {
+    // Error ignored
+  }
+};
+
+const getValidRemoteData = (
+  dbKey: string,
+  settledResults: PromiseSettledResult<any>[],
+  localData?: any
+): { data: any; index: number } | null => {
+  const validResults = settledResults
+    .map((result, index) => ({
+      data: result.status === "fulfilled" ? result.value : null,
+      index,
+    }))
+    .filter((item) => item.data !== null && typeof item.data === "object");
+
+  if (validResults.length === 0) return null;
+
+  const latest = validResults.reduce((latest, current) => {
+    return shouldReplaceWithNextRecord(current.data, latest.data) ? current : latest;
+  });
+
+  return {
+    ...latest,
+    data: latest.data,
+  };
+};
+
+const processRemoteDataInBackground = async (
+  clientDb: any,
+  dbKey: string,
+  remotePromises: Promise<any>[],
+  remoteServers: string[],
+  localData: any,
+  thunkApi: AppThunkApi
+): Promise<void> => {
+  if (!clientDb) return;
+  try {
+    const settledResults = await Promise.allSettled(remotePromises);
+    const remoteResult = getValidRemoteData(dbKey, settledResults, localData);
+    const validRemoteData = remoteResult ? remoteResult.data : null;
+    const serverOrigin =
+      remoteResult && remoteServers[remoteResult.index]
+        ? remoteServers[remoteResult.index]
+        : undefined;
+
+    if (validRemoteData && localData) {
+      await updateClientDbIfNewer(
+        clientDb,
+        dbKey,
+        serverOrigin ? { ...validRemoteData, serverOrigin } : validRemoteData,
+        localData
+      );
+    }
+    if (shouldSyncLocalToServer(localData, validRemoteData)) {
+      await syncLocalDataToServer(thunkApi, dbKey, localData);
+    }
+  } catch (err) {
+    // Background sync errors ignored
+  }
+};
+
+// --- 主函数 ---
+
+export const readAction = async (
+  payload: {
+    dbKey: string;
+    signal?: AbortSignal;
+    preferredServerOrigin?: string | null;
+  },
+  thunkApi: AppThunkApi
+): Promise<any> => {
+  const dbKey = payload.dbKey;
+  const signal = payload.signal;
+  const preferredServerOrigin = payload.preferredServerOrigin;
+
+  if (!dbKey || typeof dbKey !== "string") {
+    throw new Error("readAction requires a non-empty dbKey.");
+  }
+
+  // 2. 尽早检查中止信号，快速退出
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError");
+  }
+
+  const { db: clientDb } = thunkApi.extra;
+  if (!clientDb) {
+    throw new Error("Client database is not available.");
+  }
+
+  const executeRead = async (): Promise<any> => {
+    const state = thunkApi.getState();
+    const { currentToken, remoteServers: allServers } =
+      getRuntimeServerContext(state, preferredServerOrigin);
+    const isLoggedIn = !!currentToken;
+    const now = Date.now();
+    const localData = await fetchFromClientDb(clientDb, dbKey);
+    readRequestManager.cleanupMisses(now);
+    readRequestManager.cleanupLocalHitRevalidations(now);
+
+    if (localData) {
+      readRequestManager.clearMiss(dbKey);
+    } else {
+      const retryInMs = readRequestManager.getRetryInMs(dbKey, now);
+      if (typeof retryInMs === "number" && retryInMs > 0) {
+        logger.debug(
+          { dbKey, retryInMs },
+          "[readAction] Suppressing repeated miss read"
+        );
+        throw new Error(`Read temporarily suppressed for missing key "${dbKey}".`);
+      }
+    }
+
+    // 离线 / 无可用远程服务器：只看本地
+    if (allServers.length === 0) {
+      if (localData) {
+        return { ...localData, dbKey };
+      }
+      readRequestManager.markMiss(dbKey, now);
+      throw new Error(
+        `Failed to fetch data for key "${dbKey}" because network is offline and no local data is available.`
+      );
+    }
+
+    const preferredServer =
+      typeof preferredServerOrigin === "string" && preferredServerOrigin.trim().length > 0
+        ? preferredServerOrigin.trim().replace(/\/+$/, "")
+        : null;
+    const remainingServers = preferredServer
+      ? allServers.filter((server) => server.replace(/\/+$/, "") !== preferredServer)
+      : allServers;
+
+    if (localData) {
+      // Local-first: return durable local data immediately and only revalidate
+      // against remote servers in the background. This avoids turning a
+      // preferred-server timeout into a visible read failure for data we
+      // already have locally (for example createDialog -> initDialog).
+      if (!signal?.aborted) {
+        const retryInMs = readRequestManager.getLocalHitRevalidateInMs(
+          dbKey,
+          now
+        );
+        if (retryInMs === null) {
+          readRequestManager.markLocalHitRevalidated(dbKey, now);
+          const revalidationServers = preferredServer
+            ? [preferredServer, ...remainingServers]
+            : remainingServers;
+          const remotePromises = revalidationServers.map((server) =>
+            fetchFromServer(server, dbKey, isLoggedIn ? currentToken : undefined, signal)
+          );
+          void (async () => {
+            await processRemoteDataInBackground(
+              clientDb,
+              dbKey,
+              remotePromises,
+              revalidationServers,
+              localData,
+              thunkApi
+            );
+          })();
+        } else {
+          logger.debug(
+            { dbKey, retryInMs },
+            "[readAction] Skipping frequent local-hit revalidation"
+          );
+        }
+      }
+      return { ...localData, dbKey };
+    }
+
+    if (preferredServer) {
+      try {
+        const preferredRemoteData = await fetchFromServer(
+          preferredServer,
+          dbKey,
+          isLoggedIn ? currentToken : undefined,
+          signal
+        );
+
+        if (preferredRemoteData) {
+          await saveRemoteDataToClientDb(
+            clientDb,
+            dbKey,
+            preferredRemoteData,
+            preferredServer
+          );
+          readRequestManager.clearMiss(dbKey);
+          return { ...preferredRemoteData, dbKey, serverOrigin: preferredServer };
+        }
+      } catch (error) {
+        if (signal?.aborted || (error as { name?: string } | null)?.name === "AbortError") {
+          throw error;
+        }
+        if (isReadTimeoutError(error)) {
+          logger.warn(
+            { dbKey, preferredServer, error: String((error as Error).message) },
+            "[readAction] Preferred server timed out; falling back to remaining servers"
+          );
+        } else {
+          logger.warn(
+            { dbKey, preferredServer, error: String(error) },
+            "[readAction] Preferred server read failed; falling back to remaining servers"
+          );
+        }
+      }
+    }
+
+    // 3. 将 signal 传递给所有网络请求
+    const remotePromises = remainingServers.map((server) =>
+      fetchFromServer(server, dbKey, isLoggedIn ? currentToken : undefined, signal)
+    );
+
+    // 如果本地没有数据，则等待网络请求结果
+    const settledResults = await Promise.allSettled(remotePromises);
+
+    // 4. 在处理网络结果前，再次检查中止信号
+    if (signal?.aborted) {
+      throw new DOMException("Aborted", "AbortError");
+    }
+
+    const remoteResult = getValidRemoteData(dbKey, settledResults, localData);
+    if (remoteResult) {
+      const { data: validRemoteData } = remoteResult;
+      const serverOrigin = remainingServers[remoteResult.index];
+      if (!signal?.aborted) {
+        await saveRemoteDataToClientDb(
+          clientDb,
+          dbKey,
+          validRemoteData,
+          serverOrigin
+        );
+      }
+      readRequestManager.clearMiss(dbKey);
+      return serverOrigin
+        ? { ...validRemoteData, dbKey, serverOrigin }
+        : { ...validRemoteData, dbKey };
+    }
+
+    readRequestManager.markMiss(dbKey, Date.now());
+    throw new Error(`Failed to fetch data for key "${dbKey}" from all sources.`);
+  };
+
+  const canDedup = !signal;
+  if (canDedup) {
+    const existing = readRequestManager.getInFlight(dbKey);
+    if (existing) return existing;
+
+    let inFlightPromise: Promise<any>;
+    inFlightPromise = executeRead().finally(() => {
+      readRequestManager.clearInFlight(dbKey, inFlightPromise);
+    });
+    readRequestManager.setInFlight(dbKey, inFlightPromise);
+    return inFlightPromise;
+  }
+
+  return executeRead();
+};

package/database/actions/readAndWait.ts

@@ -0,0 +1,224 @@
+// 文件路径: database/actions/readAndWait.ts
+
+import type { AppThunkApi } from "app/store";
+import {
+  fetchFromClientDb,
+  fetchFromServer,
+} from "./common";
+import { readRequestManager } from "./readRequestManager";
+import { scheduleExistingRecordReplication } from "./replication";
+import { getRuntimeServerContext } from "database/runtimeServerContext";
+
+/**
+ * 比较远程数据和本地数据的时间戳，判断远程数据是否更新。
+ * @param remoteData - 从服务器获取的数据。
+ * @param localData - 从本地数据库获取的数据。
+ * @returns 如果远程数据更新，则返回 true。
+ */
+const isRemoteDataNewer = (remoteData: any, localData: any): boolean => {
+  const toComparableTimestamp = (data: any): number => {
+    if (!data || typeof data !== "object") return 0;
+
+    const updatedAtMs = new Date(data.updatedAt).getTime();
+    if (Number.isFinite(updatedAtMs) && updatedAtMs > 0) return updatedAtMs;
+
+    const createdAtMs = new Date(data.createdAt).getTime();
+    if (Number.isFinite(createdAtMs) && createdAtMs > 0) return createdAtMs;
+
+    const metaCreatedAt = Number(data?.meta?.createdAt);
+    if (Number.isFinite(metaCreatedAt) && metaCreatedAt > 0) return metaCreatedAt;
+
+    return 0;
+  };
+
+  const remoteTs = toComparableTimestamp(remoteData);
+  const localTs = toComparableTimestamp(localData);
+  if (remoteTs <= 0) return false;
+  if (localTs <= 0) return true;
+  return remoteTs > localTs;
+};
+
+/**
+ * 触发一个“即发即忘”的异步任务，将本地数据上传（写入）到服务器。
+ * 通常在发现本地存在数据而所有远程服务器上都不存在该数据时调用。
+ */
+const syncLocalDataToServer = async (
+  thunkApi: AppThunkApi,
+  dbKey: string,
+  localData: any
+): Promise<void> => {
+  try {
+    const state = thunkApi.getState();
+    const { currentServer, syncServers } = getRuntimeServerContext(state);
+    scheduleExistingRecordReplication({
+      currentServer,
+      syncServers,
+      dbKey,
+      localData,
+      state,
+    });
+  } catch {
+    // 后台同步失败不阻塞主流程，静默处理即可
+  }
+};
+
+/**
+ * 从所有远程服务器的请求结果中，筛选出有效的、时间戳最新的那一份数据。
+ */
+const getValidRemoteData = (
+  dbKey: string,
+  settledResults: PromiseSettledResult<any>[],
+  localData?: any
+): { data: any; index: number } | null => {
+  const toComparableTimestamp = (data: any): number => {
+    if (!data || typeof data !== "object") return 0;
+
+    const updatedAtMs = new Date(data.updatedAt).getTime();
+    if (Number.isFinite(updatedAtMs) && updatedAtMs > 0) return updatedAtMs;
+
+    const createdAtMs = new Date(data.createdAt).getTime();
+    if (Number.isFinite(createdAtMs) && createdAtMs > 0) return createdAtMs;
+
+    const metaCreatedAt = Number(data?.meta?.createdAt);
+    if (Number.isFinite(metaCreatedAt) && metaCreatedAt > 0) return metaCreatedAt;
+
+    return 0;
+  };
+
+  const validResults = settledResults
+    .map((result, index) => ({
+      data: result.status === "fulfilled" ? result.value : null,
+      index,
+    }))
+    .filter((item) => item.data !== null && typeof item.data === "object");
+
+  if (validResults.length === 0) return null;
+
+  // 从所有有效的远程数据中，选出时间戳最新的那一个。
+  const latest = validResults.reduce((latest, current) => {
+    const latestTimestamp = toComparableTimestamp(latest.data);
+    const currentTimestamp = toComparableTimestamp(current.data);
+    return currentTimestamp > latestTimestamp ? current : latest;
+  });
+
+  return {
+    ...latest,
+    data: latest.data,
+  };
+};
+
+/**
+ * 核心处理函数：协调本地和远程数据，决定最终返回哪个版本的数据，并处理同步逻辑。
+ */
+const processRemoteData = async (
+  db: any,
+  dbKey: string,
+  remotePromises: Promise<any>[],
+  localData: any,
+  thunkApi: AppThunkApi
+): Promise<any> => {
+  try {
+    // 并行执行所有远程请求，并等待它们全部完成（无论成功或失败）。
+    const settledResults = await Promise.allSettled(remotePromises);
+    // 从所有结果中，找出最“权威”的远程版本（时间戳最新）。
+    const remoteResult = getValidRemoteData(dbKey, settledResults, localData);
+    const validRemoteData = remoteResult ? remoteResult.data : null;
+
+    // --- 数据决策核心逻辑 ---
+
+    // 场景 1: 至少一个远程服务器返回了有效数据。
+    if (validRemoteData) {
+      // 如果本地没有数据，或者远程更新更新，则用远程覆盖本地缓存。
+      if (!localData || isRemoteDataNewer(validRemoteData, localData)) {
+        await db.put(dbKey, validRemoteData);
+      }
+      // 最终决策：返回权威的远程数据。
+      return validRemoteData;
+    }
+
+    // 场景 2: 所有远程服务器都没有返回有效数据，但我们本地数据库中存在数据。
+    if (localData) {
+      // 仅当“确实有远程目标”时，才尝试上传本地数据到服务器。
+      if (remotePromises.length > 0) {
+        void syncLocalDataToServer(thunkApi, dbKey, localData);
+      }
+      // 最终决策：返回本地数据。
+      return localData;
+    }
+
+    // 场景 3: 远程和本地都找不到任何数据。
+    throw new Error("Failed to fetch data from all sources");
+  } catch (err) {
+    // 如果在上述过程中发生错误，且有本地数据，则优先返回本地数据，避免崩溃。
+    if (localData) {
+      return localData;
+    }
+    throw err;
+  }
+};
+
+/**
+ * 主函数：读取数据，并等待远程和本地操作都完成后才返回最合适的数据。
+ * - 本地优先：有本地数据时，远程只用于更新缓存或回填云端。
+ * - 远程优先：若拿到了有效远程数据，以其为准。
+ */
+export const readAndWaitAction = async (
+  dbKey: string,
+  thunkApi: AppThunkApi
+): Promise<any> => {
+  const { db } = thunkApi.extra;
+
+  if (!db) {
+    throw new Error(
+      "Database instance is not available in thunk extra argument."
+    );
+  }
+
+  const state = thunkApi.getState();
+  const { currentToken, remoteServers: allServers } =
+    getRuntimeServerContext(state);
+  const isLoggedIn = !!currentToken;
+
+  const executeReadAndWait = async (): Promise<any> => {
+    // 1. 准备所有需要访问的远程服务器（带去重 + 离线检测）
+    // 2. 首先，尝试从本地数据库获取数据（可能为 null）
+    const localData = await fetchFromClientDb(db, dbKey);
+
+    // 如果离线或没有任何可用远程服务器：
+    if (allServers.length === 0) {
+      if (localData) {
+        return { ...localData, dbKey };
+      }
+      throw new Error(
+        `Failed to fetch data for key "${dbKey}" because network is offline and no local data is available.`
+      );
+    }
+
+    // 3. 创建所有到远程服务器的并行请求
+    const remotePromises = allServers.map((server) =>
+      fetchFromServer(server, dbKey, isLoggedIn ? currentToken : undefined)
+    );
+
+    // 4. 将所有信息交给核心处理函数去做最终决策
+    const chosenData = await processRemoteData(
+      db,
+      dbKey,
+      remotePromises,
+      localData,
+      thunkApi
+    );
+
+    // ⭐ 统一：不论返回的是本地还是远程，最终都附加 dbKey 字段
+    return { ...chosenData, dbKey };
+  };
+
+  const existing = readRequestManager.getInFlight(dbKey);
+  if (existing) return existing;
+
+  let inFlightPromise: Promise<any>;
+  inFlightPromise = executeReadAndWait().finally(() => {
+    readRequestManager.clearInFlight(dbKey, inFlightPromise);
+  });
+  readRequestManager.setInFlight(dbKey, inFlightPromise);
+  return inFlightPromise;
+};

package/database/actions/readRequestManager.ts

@@ -0,0 +1,120 @@
+const DEFAULT_MISS_COOLDOWN_MS = 2000;
+const DEFAULT_LOCAL_HIT_REVALIDATE_COOLDOWN_MS = 1500;
+const DEFAULT_MISS_CACHE_MAX_SIZE = 1000;
+
+export class ReadRequestManager {
+  private readonly inFlightReads = new Map<string, Promise<any>>();
+  private readonly recentMisses = new Map<string, number>();
+  private readonly recentLocalHitRevalidations = new Map<string, number>();
+
+  constructor(
+    private readonly options: {
+      missCooldownMs?: number;
+      missCacheMaxSize?: number;
+      localHitRevalidateCooldownMs?: number;
+    } = {}
+  ) {}
+
+  private get missCooldownMs() {
+    return this.options.missCooldownMs ?? DEFAULT_MISS_COOLDOWN_MS;
+  }
+
+  private get missCacheMaxSize() {
+    return this.options.missCacheMaxSize ?? DEFAULT_MISS_CACHE_MAX_SIZE;
+  }
+
+  private get localHitRevalidateCooldownMs() {
+    return (
+      this.options.localHitRevalidateCooldownMs ??
+      DEFAULT_LOCAL_HIT_REVALIDATE_COOLDOWN_MS
+    );
+  }
+
+  getInFlight(dbKey: string) {
+    return this.inFlightReads.get(dbKey);
+  }
+
+  setInFlight(dbKey: string, promise: Promise<any>) {
+    this.inFlightReads.set(dbKey, promise);
+  }
+
+  clearInFlight(dbKey: string, promise: Promise<any>) {
+    if (this.inFlightReads.get(dbKey) === promise) {
+      this.inFlightReads.delete(dbKey);
+    }
+  }
+
+  clearMiss(dbKey: string) {
+    this.recentMisses.delete(dbKey);
+  }
+
+  getRetryInMs(dbKey: string, now: number) {
+    const missUntil = this.recentMisses.get(dbKey);
+    if (typeof missUntil !== "number") return null;
+    if (missUntil <= now) {
+      this.recentMisses.delete(dbKey);
+      return null;
+    }
+    return missUntil - now;
+  }
+
+  markMiss(dbKey: string, now: number, cooldownMs = this.missCooldownMs) {
+    this.recentMisses.set(dbKey, now + cooldownMs);
+    this.cleanupMisses(now);
+  }
+
+  getLocalHitRevalidateInMs(dbKey: string, now: number) {
+    const nextAllowedAt = this.recentLocalHitRevalidations.get(dbKey);
+    if (typeof nextAllowedAt !== "number") return null;
+    if (nextAllowedAt <= now) {
+      this.recentLocalHitRevalidations.delete(dbKey);
+      return null;
+    }
+    return nextAllowedAt - now;
+  }
+
+  markLocalHitRevalidated(
+    dbKey: string,
+    now: number,
+    cooldownMs = this.localHitRevalidateCooldownMs
+  ) {
+    this.recentLocalHitRevalidations.set(dbKey, now + cooldownMs);
+    this.cleanupLocalHitRevalidations(now);
+  }
+
+  private cleanupExpiringMap(map: Map<string, number>, now: number) {
+    for (const [key, expiresAt] of Array.from(map.entries())) {
+      if (expiresAt <= now) {
+        map.delete(key);
+      }
+    }
+
+    if (map.size <= this.missCacheMaxSize) return;
+    const overflow = map.size - this.missCacheMaxSize;
+    const keys = Array.from(map.keys());
+    for (let i = 0; i < overflow; i += 1) {
+      const key = keys[i];
+      if (key) map.delete(key);
+    }
+  }
+
+  cleanupMisses(now: number) {
+    this.cleanupExpiringMap(this.recentMisses, now);
+  }
+
+  cleanupLocalHitRevalidations(now: number) {
+    this.cleanupExpiringMap(this.recentLocalHitRevalidations, now);
+  }
+
+  // test helper
+  getMissCacheSize() {
+    return this.recentMisses.size;
+  }
+
+  // test helper
+  getLocalHitRevalidationCacheSize() {
+    return this.recentLocalHitRevalidations.size;
+  }
+}
+
+export const readRequestManager = new ReadRequestManager();