nolo-cli 0.1.13 → 0.1.15

package/database/actions/patch.ts

@@ -0,0 +1,155 @@
+// 文件路径: database/actions/patch.ts
+
+import type { AppThunkApi } from "app/store";
+import { getRuntimeServerContext } from "database/runtimeServerContext";
+import { toast } from "app/utils/toast";
+import {
+  scheduleConfiguredPatchReplication,
+} from "./replication";
+
+/**
+ * 深度合并两个对象。源对象中的 null 值会删除目标对象中对应的键。
+ * @param target - 目标对象。
+ * @param source - 源对象，包含要应用的更改。
+ * @returns {any} - 合并后的新对象。
+ */
+const deepMerge = (target: any, source: any): any => {
+  const output = { ...target };
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      if (source[key] === null && key in output) {
+        delete output[key]; // null 值用于删除键
+      } else if (
+        source[key] &&
+        typeof source[key] === "object" &&
+        !Array.isArray(source[key])
+      ) {
+        output[key] = deepMerge(output[key] || {}, source[key]); // 递归合并
+      } else {
+        output[key] = source[key]; // 直接赋值
+      }
+    }
+  }
+  return output;
+};
+
+const toTimestamp = (value: unknown): number => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+};
+
+const inferNextUpdatedAt = (currentData: any): number | string | undefined => {
+  const previousUpdatedAt = currentData?.updatedAt;
+  const previousCreatedAt = currentData?.createdAt;
+  const previousMetaCreatedAt = currentData?.meta?.createdAt;
+  const previousTimestamp = Math.max(
+    toTimestamp(previousUpdatedAt),
+    toTimestamp(previousCreatedAt),
+    toTimestamp(previousMetaCreatedAt)
+  );
+  const nextTimestamp = Math.max(Date.now(), previousTimestamp + 1);
+
+  if (
+    typeof previousUpdatedAt === "number" ||
+    typeof previousCreatedAt === "number" ||
+    typeof previousMetaCreatedAt === "number"
+  ) {
+    return nextTimestamp;
+  }
+
+  if (
+    typeof previousUpdatedAt === "string" ||
+    typeof previousCreatedAt === "string"
+  ) {
+    return new Date(nextTimestamp).toISOString();
+  }
+
+  return undefined;
+};
+
+/**
+ * Patch Action: 对现有数据项应用增量更新。
+ * 1. 从本地数据库读取现有数据。
+ * 2. 将传入的 'changes' 对象与现有数据进行深度合并。
+ * 3. 将合并后的新数据写回本地数据库。
+ * 4. 异步地将 'changes' 对象同步到所有相关服务器。
+ * @param payload - 包含 dbKey 和 changes 的对象。
+ * @param {string} payload.dbKey - 要更新的数据的键。
+ * @param {object} payload.changes - 要应用的更改。
+ * @param thunkApi - Redux Thunk API，包含 state 和 extra arugments。
+ * @returns {Promise<any>} 更新后的完整数据对象。
+ * @throws 如果本地数据不存在或更新过程中发生任何错误，则抛出异常。
+ */
+export const patchAction = async (
+  {
+    dbKey,
+    changes,
+    preferredServerOrigin,
+  }: { dbKey: string; changes: any; preferredServerOrigin?: string | null },
+  thunkApi: AppThunkApi
+): Promise<any> => {
+  // 1. 从 thunkApi.extra 中获取数据库实例
+  const { db } = thunkApi.extra;
+  if (!db) {
+    const errorMsg = "Database instance is not available.";
+    toast.error(errorMsg);
+    throw new Error(errorMsg);
+  }
+
+  // 2. 验证输入参数
+  if (!dbKey || !changes || typeof changes !== "object") {
+    const errorMsg = "Patch action requires a valid dbKey and changes object.";
+    toast.error(errorMsg);
+    throw new Error(errorMsg);
+  }
+
+  const state = thunkApi.getState();
+  const { currentServer, syncServers: configuredSyncServers } =
+    getRuntimeServerContext(state);
+
+  try {
+    // 3. 使用注入的 db 实例读取当前数据
+    const currentData = await db.get(dbKey);
+    if (!currentData) {
+      throw new Error(
+        `Cannot apply patch: Data not found locally for key: ${dbKey}.`
+      );
+    }
+
+    const patchChanges = Object.prototype.hasOwnProperty.call(changes, "updatedAt")
+      ? changes
+      : {
+          ...changes,
+          ...(inferNextUpdatedAt(currentData) !== undefined
+            ? { updatedAt: inferNextUpdatedAt(currentData) }
+            : {}),
+        };
+
+    // 4. 合并数据并写回本地数据库
+    const newData = deepMerge(currentData, patchChanges);
+    const persistedData =
+      newData && typeof newData === "object" ? { ...newData, dbKey } : { dbKey };
+    await db.put(dbKey, persistedData);
+
+    // 5. 异步触发对远程服务器的同步（即发即忘）
+    scheduleConfiguredPatchReplication({
+      currentServer,
+      syncServers: configuredSyncServers,
+      preferredServerOrigin,
+      dbKey,
+      changes: patchChanges,
+      state,
+    });
+
+    // 6. 乐观地返回更新后的数据
+    return persistedData;
+  } catch (error: any) {
+    const errorMessage = `Failed to update data for ${dbKey}.`;
+    toast.error(errorMessage);
+    throw new Error(error.message || errorMessage);
+  }
+};

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;
+};