@aiao/rxdb-plugin-sync 0.0.0-stage → 0.0.26

package/src/sync-branches.ts

@@ -0,0 +1,156 @@
+import { type IRepository, RxDBBranch, RxDBChange, RxDBError } from '@aiao/rxdb';
+import { toLocalFromChangeId } from './branch-change-id.js';
+import type { SyncManager } from './SyncManager.js';
+
+export interface SyncBranchesResult {
+  created: number;
+  updated: number;
+  total: number;
+
+  /**
+   * 因分叉点变更尚未拉到本地而**本轮未创建**的分支 id。
+   *
+   * 远端分支行上的 `fromChangeId` 是远端 change id，落到本地必须翻译成本地 id
+   * （见 {@link toLocalFromChangeId}）。翻译不出来时既不能写远端 id（本地会当自己的 id 消费，
+   * 分叉点变成一个无关变更），也不能写 `null`（`find-switch-branch-step` 会当「分叉于根」，
+   * 切换分支时从第一条变更起算）。唯一无损的选择是本轮跳过，等分叉点变更拉到本地后再建。
+   */
+  skipped: string[];
+}
+
+/** `pullBranches()` 交回来的形状里，本函数只依赖这三个字段。 */
+interface RemoteBranchRow {
+  id: string;
+  parentId?: string | null;
+}
+
+/**
+ * 把远端分支按「父在前」重排。
+ *
+ * `rxdb_branch.parentId` 是指向自己的外键，逐条落库时父必须先在库里。而 `pullBranches()`
+ * 返回的数组**没有顺序保证** —— 远端按 `updatedAt`、按主键、按它高兴的任何顺序返回都合法，
+ * 分页更是会把父子切到不同批次。所以顺序必须由本地重建，不能指望远端。
+ *
+ * 判定一个分支「可落库」的依据是它的父是否已经就绪：要么父本来就在本地，要么父在本批里
+ * 且已排到它前面。反复扫描直到某一轮一条都排不出去 —— 剩下的就是父确实找不到
+ * （远端删了父 / 父被分页切走）或互相成环，两者都无法安全落库。
+ *
+ * @param remoteBranches - 远端原样交回的分支数组，顺序不可信
+ * @param localIds - 已在本地的分支 id，它们可以充当父
+ * @returns 父一定排在子前面的新数组
+ * @throws RxDBError 存在父分支缺失或互相成环的记录时。整批放弃优于留下孤儿：
+ * 孤儿会被切分支时的「父节点缺失即当作到根」静默吞掉，损坏无声。
+ */
+function sortBranchesParentFirst<T extends RemoteBranchRow>(remoteBranches: T[], localIds: Set<string>): T[] {
+  const resolved = new Set(localIds);
+  // 本批自己带来的 id：用来把「父确实缺失」和「父只是还排在后面」区分开，好让报错说人话。
+  const incoming = new Set(remoteBranches.map(branch => branch.id));
+  const sorted: T[] = [];
+  let pending = remoteBranches;
+
+  while (pending.length > 0) {
+    const ready = pending.filter(branch => {
+      const parentId = branch.parentId ?? null;
+      return parentId === null || resolved.has(parentId);
+    });
+    if (ready.length === 0) break;
+    for (const branch of ready) {
+      sorted.push(branch);
+      resolved.add(branch.id);
+    }
+    pending = pending.filter(branch => !resolved.has(branch.id));
+  }
+
+  if (pending.length > 0) {
+    const detail = pending
+      .map(branch => {
+        const parentId = branch.parentId ?? null;
+        // 父在本批里却始终排不出去 = 成环；否则就是父压根不存在。
+        const reason = parentId !== null && incoming.has(parentId) ? 'cycle' : 'missing parent';
+        return `'${branch.id}' -> '${String(parentId)}' (${reason})`;
+      })
+      .join(', ');
+    throw new RxDBError(`syncBranches: 远端分支拓扑无法解析，整批放弃：${detail}`);
+  }
+
+  return sorted;
+}
+
+/**
+ * 从远程拉取所有分支信息并同步到本地
+ *
+ * 规则：
+ * 1. 远程新分支 → 在本地创建（local: false, remote: true）
+ * 2. 本地已有的远程分支 → 更新 remote 标记为 true
+ * 3. 纯本地分支（remote=false）→ 不受影响
+ *
+ * @remarks
+ * 读本地、排序、落库全部在**同一个事务窗口**内完成：
+ *
+ * - 无事务时中途失败会留下半批已提交的分支，下次重试撞主键，同步就此永久卡死；
+ * - 读若在事务外做，快照与写之间存在窗口，并发建分支会让「本地已有」的判断过时，
+ *   重复 create 同样撞主键。
+ *
+ * 事务体内只能用 `executor` 作用域的仓库。绑在适配器上的那一份走并发度 1 的写队列，
+ * 在事务体内调用会排到自己这个事务后面 —— 直接死锁。
+ */
+export async function syncBranches(sm: SyncManager): Promise<SyncBranchesResult> {
+  const { adapter: remoteAdapter } = await sm.getRemoteRepositories();
+
+  if (!remoteAdapter.pullBranches) {
+    return { created: 0, updated: 0, total: 0, skipped: [] };
+  }
+
+  const remoteBranches = await remoteAdapter.pullBranches();
+  if (remoteBranches.length === 0) {
+    return { created: 0, updated: 0, total: 0, skipped: [] };
+  }
+
+  const { adapter } = await sm.getLocalRepositories();
+
+  return adapter.transaction(async executor => {
+    const branchRepository = executor.getRepository(RxDBBranch) as unknown as IRepository<typeof RxDBBranch>;
+    const changeRepository = executor.getRepository(RxDBChange) as unknown as IRepository<typeof RxDBChange>;
+
+    const localBranches = await branchRepository.find({
+      where: { combinator: 'and', rules: [] }
+    });
+    const localMap = new Map(localBranches.map(b => [b.id, b]));
+
+    let created = 0;
+    let updated = 0;
+    const skipped: string[] = [];
+
+    for (const remote of sortBranchesParentFirst(remoteBranches, new Set(localMap.keys()))) {
+      const local = localMap.get(remote.id);
+      if (local) {
+        if (!local.remote) {
+          await branchRepository.update(local, { remote: true, updatedAt: new Date() });
+          updated++;
+        }
+        continue;
+      }
+
+      // 远端 change id 必须翻译成本地 id 才能写进本地分支行
+      const remoteFromChangeId = remote.fromChangeId ?? null;
+      const fromChangeId =
+        remoteFromChangeId === null ? null : await toLocalFromChangeId(changeRepository, remoteFromChangeId);
+      if (remoteFromChangeId !== null && fromChangeId === null) {
+        skipped.push(remote.id);
+        continue;
+      }
+
+      await branchRepository.create({
+        id: remote.id,
+        activated: false,
+        local: false,
+        remote: true,
+        fromChangeId,
+        parentId: remote.parentId ?? null
+      } as InstanceType<typeof RxDBBranch>);
+      created++;
+    }
+
+    return { created, updated, total: remoteBranches.length, skipped };
+  });
+}

package/src/sync-listeners.ts

@@ -0,0 +1,289 @@
+import {
+  ENTITY_REMOTE_CREATE_EVENT,
+  ENTITY_REMOTE_REMOVE_EVENT,
+  ENTITY_REMOTE_UPDATE_EVENT,
+  EntityRemoteCreatedEvent,
+  EntityRemoteRemovedEvent,
+  EntityRemoteUpdatedEvent,
+  type EntityType,
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  isSystemEntity,
+  type RepositoryIdentifier,
+  type SyncStateHub
+} from '@aiao/rxdb';
+import { isIgnorableDetachedVersionEventError } from '@aiao/rxdb-plugin-history';
+import { combineLatest, merge, type Observable, Subscription } from 'rxjs';
+import { distinctUntilChanged, exhaustMap, filter, map, withLatestFrom } from 'rxjs/operators';
+import { countQueryCacheOutbox, flushQueryCacheOutbox } from './query-cache-outbox.js';
+import type { SyncManager } from './SyncManager.js';
+
+/**
+ * 远程实体事件类型集合（CREATE/UPDATE/REMOVE）
+ */
+type RemoteEntityEvent = EntityRemoteCreatedEvent | EntityRemoteUpdatedEvent | EntityRemoteRemovedEvent;
+
+/**
+ * 跑一步回推动作，把失败报给面板后吞掉
+ *
+ * @param syncState - 失败的去处
+ * @param task - 这一步
+ * @returns 这一步是否成功
+ *
+ * @remarks
+ * 一轮里的各个仓库互不背书：一个仓库的出站队列重放不上，不代表别的仓库那条 REST 路
+ * 也走不通。任何一步的失败都只影响它自己，剩下的照跑。
+ *
+ * 吞错也是为了不掐断订阅 —— rxjs 里一个逃逸到流上的异常会终结整条链，此后再恢复
+ * 多少次网络都不会再有回推。真正的重试节奏交给
+ * {@link ReachabilityMonitor.wakeup$} 的退避。吞掉不等于藏起来：错误进
+ * {@link SyncStateHub.reportError}，用户在面板上看得见。
+ */
+async function runQuietly(syncState: SyncStateHub, task: () => Promise<unknown>): Promise<boolean> {
+  try {
+    await task();
+    return true;
+  } catch (error) {
+    syncState.reportError(error);
+    return false;
+  }
+}
+
+/**
+ * 接入方声明的实体，即摘掉系统表之后的 `config.entities`
+ *
+ * @remarks
+ * 分派问的是「**用户的**数据该往哪走」，而 `config.entities` 里还混着
+ * {@link SchemaManager.init} 补进来的四张系统表。它们不带自己的 `sync`，于是跟随库级配置 ——
+ * 库级两端俱全时 {@link getSyncType} 会把它们判成 `full`，四张本地簿记表就这么被卷进
+ * 用户数据的分派里。系统表自己的同步由 {@link SyncManager} 直接安排，从不经过这里。
+ */
+function consumerEntities(sm: SyncManager): EntityType[] {
+  return sm.rxdb.config.entities.filter(EntityClass => !isSystemEntity(EntityClass));
+}
+
+/**
+ * 枚举需要走 REST 重放的仓库
+ *
+ * @remarks
+ * 判据是 `offlineWrite && !push`，也就是「能在离线时接受本地写，但没有 changelog 端点」——
+ * 现阶段只有 `querycache`。带 `push` 能力的仓库不在这里：它们由用户显式调
+ * {@link SyncManager.push}，那条路自己按能力矩阵筛。
+ *
+ * 不在这里查 `RxDBSync.enabled`：那要为每个仓库读一次库，而
+ * {@link flushQueryCacheOutbox} 入口本来就会判并返回 `skipped`。判两遍等于把同一个口径
+ * 抄成两份。
+ */
+function queryCacheRepositories(sm: SyncManager): RepositoryIdentifier[] {
+  const repositories: RepositoryIdentifier[] = [];
+
+  for (const EntityClass of consumerEntities(sm)) {
+    const metadata = getEntityMetadata(EntityClass);
+    const capability = getSyncCapability(getSyncType(metadata, sm.rxdb.config.sync));
+    if (capability.offlineWrite && !capability.push) {
+      repositories.push({ namespace: metadata.namespace, entity: metadata.name });
+    }
+  }
+
+  return repositories;
+}
+
+/**
+ * 重放一个 QueryCache 仓库，把判负的实体报给面板
+ *
+ * @remarks
+ * 只有 `conflicts`（解析器判 `KEEP_REMOTE`）进面板：那是用户离线时写的东西被远端盖掉了，
+ * 是唯一需要他知道的一类。逐条上报而不是只报最后一条，`lastConflict` 自然停在最新的那条。
+ */
+async function flushRepository(sm: SyncManager, namespace: string, entity: string): Promise<void> {
+  const { syncState } = sm.rxdb;
+  const result = await flushQueryCacheOutbox(sm.rxdb, namespace, entity);
+
+  for (const entityId of result.conflicts) {
+    syncState.reportConflict({ namespace, entity, entityId, winner: 'remote' });
+  }
+}
+
+/**
+ * 重放本轮所有 QueryCache 仓库
+ *
+ * @param sm - 当前 SyncManager
+ * @param repositories - 本轮的仓库名单，由 {@link queryCacheRepositories} 枚举
+ * @returns 是否每个仓库都成功
+ */
+async function flushRepositories(sm: SyncManager, repositories: RepositoryIdentifier[]): Promise<boolean> {
+  const { syncState } = sm.rxdb;
+  let allSucceeded = true;
+
+  for (const { namespace, entity } of repositories) {
+    const succeeded = await runQuietly(syncState, () => flushRepository(sm, namespace, entity));
+    allSucceeded = succeeded && allSucceeded;
+  }
+
+  return allSucceeded;
+}
+
+/**
+ * 重新数一遍 QueryCache 的出站积压，刷新面板
+ *
+ * @remarks
+ * 失败**不**走 {@link runQuietly}：这是一次读，读不到只意味着面板停在上一个数字，
+ * 而 `lastError` 说的是「你的数据没推上去」。把一次 COUNT 失败写进去会让用户
+ * 以为刚推成功的一轮出了问题。
+ *
+ * 每轮都数而不是只在推过之后数：水位线推进不写 `rxdb_change`，实时查询看不见这个数
+ * （见 {@link SyncStateHub.reportOutboxCount}），一轮一次重算是它唯一的纠偏时机。
+ */
+async function refreshOutboxCount(sm: SyncManager): Promise<void> {
+  try {
+    sm.rxdb.syncState.reportOutboxCount(await countQueryCacheOutbox(sm.rxdb));
+  } catch {
+    // 面板保留上一个数字
+  }
+}
+
+/**
+ * 恢复联网后的一轮回推：逐个重放 QueryCache 仓库的出站队列
+ *
+ * @remarks
+ * 这一轮**只**管 QueryCache 那条 REST 路（[US-020 D5-R](../../../../requirements/stories/core/US-020-querycache-repository.md)）。
+ * changelog 那半边 —— {@link SyncManager.syncBranches} 与 {@link SyncManager.push} ——
+ * 不在这里自动跑：`push` 问的是「把我这条分支上攒的提交送到远端去」，和 git 的 `push`
+ * 一样是用户的决定。自动替他按下去，`pushableCount` 与界面上的 Push 按钮就成了摆设，
+ * 「写在本地、还没推」这个状态从此不存在。QueryCache 没有这层分支语义，它的出站队列
+ * 就是「这次写本该直接进远端，只是当时网断了」，联网补上才是它的正确行为。
+ *
+ * 各仓库串行而非并行 —— 它们打的是同一个远端，恢复瞬间并发只会把刚恢复的连接再压垮一次。
+ *
+ * 一个 QueryCache 仓库都没有时整轮不进：既省掉必然为空的一次 COUNT，也不让面板的
+ * `syncing` 为了一轮什么都不做的回推闪一下。
+ *
+ * `endRound` 放 `finally`：每一步都被 {@link runQuietly} 兜住了，但重算积压那步之外
+ * 若将来再加一步没兜住的，`syncing` 会永久卡在真上，面板从此显示「正在同步」。
+ */
+async function resumeSync(sm: SyncManager): Promise<void> {
+  const repositories = queryCacheRepositories(sm);
+  if (repositories.length === 0) {
+    return;
+  }
+
+  const { syncState } = sm.rxdb;
+  syncState.beginRound();
+
+  try {
+    // 清账放在重算积压之前：先宣布本轮没出错，再把「还剩多少」更新上去
+    if (await flushRepositories(sm, repositories)) {
+      syncState.reportSuccess();
+    }
+    await refreshOutboxCount(sm);
+  } finally {
+    syncState.endRound();
+  }
+}
+
+/**
+ * 构造回推触发流
+ *
+ * @remarks
+ * 两个触发源，语义不同：
+ *
+ * - **可回推了**：`connected$`（适配器生命周期）与 `online$`（网络可达）**同时**为真。
+ *   两者缺一不可，也不能互相替代 —— HTTP 适配器的 `connect()` 不发任何网络请求，
+ *   断网时它照样报 connected；反过来网通了但适配器没连上，回推没有可用的本地仓储。
+ * - **再试一次**：离线期间的退避节拍。它只按 `connected$` 过滤，**不**按 `online$` ——
+ *   节拍存在的意义正是在判定为离线时驱动重试，用离线状态把它挡掉会让重试链彻底断掉。
+ */
+function createResumeTrigger(sm: SyncManager): Observable<unknown> {
+  const connected$ = sm.rxdb.connected$;
+  const ready$ = combineLatest([connected$, sm.rxdb.reachability.online$]).pipe(
+    map(([connected, online]) => connected && online),
+    distinctUntilChanged()
+  );
+
+  return merge(
+    ready$.pipe(filter(ready => ready)),
+    sm.rxdb.reachability.wakeup$.pipe(
+      withLatestFrom(connected$),
+      filter(([, connected]) => connected)
+    )
+  );
+}
+
+/**
+ * 设置 SyncManager 的同步监听器
+ *
+ * 包含两条 reactive 链路：
+ * 1. 「已连接且网络可达」→ 自动重放 QueryCache 出站队列，离线期间由退避节拍驱动重试，
+ *    每个仓库失败仅吞错。changelog 的 `push` 不在其中，见 {@link resumeSync}
+ * 2. Remote 实体事件 → 累计 `pullableCount`（仅统计当前激活分支）
+ *
+ * 调用方负责管理返回的 subscriptions / removers 生命周期（destroy 时清理）。
+ *
+ * @param sm - 当前同步管理器
+ * @returns 已注册的 rxjs subscriptions 和事件解绑闭包
+ */
+export function setupSyncListeners(sm: SyncManager): {
+  subscriptions: Subscription[];
+  removers: Array<() => void>;
+} {
+  const subscriptions: Subscription[] = [];
+  const removers: Array<() => void> = [];
+
+  // 1. 有远程适配器时，恢复联网后自动回推
+  const remoteAdapterName = sm.rxdb.config.sync?.remote?.adapter;
+  if (remoteAdapterName) {
+    // `exhaustMap` 而不是 `mergeMap`：恢复瞬间往往连着来好几个信号（`online` 事件、
+    // 退避节拍、用户手动重试），并发起两轮回推会把同一批变更重放两次 ——
+    // 第二轮读到的还是第一轮尚未推进的水位线。
+    const sub = createResumeTrigger(sm)
+      .pipe(
+        exhaustMap(() =>
+          // 一轮回推失败只终结这一轮。`resumeSync` 里 `runQuietly` 兜住的只有逐仓库 flush，
+          // 枚举仓库与面板上报都在兜底之外；它们抛错顺着 `exhaustMap` 冒到订阅上就会终结整条
+          // 触发流 —— 此后 online 事件、退避节拍、重新连接一律无效，自动回推永久停摆，
+          // 而离线恢复本就是最容易出错的场景。吞掉不等于藏起来：错误进面板，用户看得见。
+          resumeSync(sm).catch((error: unknown) => {
+            sm.rxdb.syncState.reportError(error);
+          })
+        )
+      )
+      .subscribe();
+    subscriptions.push(sub);
+  }
+
+  // 2. 只累计当前激活分支的远程变更数量
+  const filterByBranch = async (entities: { branchId?: string }[]): Promise<number> => {
+    const branch = await sm.getCurrentBranch();
+    return entities.filter(e => !e.branchId || e.branchId === branch.id).length;
+  };
+
+  const makeRemoteHandler = (label: string) => {
+    return (event: RemoteEntityEvent) => {
+      void (async () => {
+        try {
+          const count = await filterByBranch(event.entities);
+          if (count > 0) sm.history.incrementPullableCount(count);
+        } catch (error) {
+          if (!isIgnorableDetachedVersionEventError(error)) {
+            console.error(`[SyncManager] ${label} failed:`, error);
+          }
+        }
+      })();
+    };
+  };
+
+  const remoteHandlers = [
+    { type: ENTITY_REMOTE_CREATE_EVENT, handler: makeRemoteHandler('onRemoteCreate') },
+    { type: ENTITY_REMOTE_UPDATE_EVENT, handler: makeRemoteHandler('onRemoteUpdate') },
+    { type: ENTITY_REMOTE_REMOVE_EVENT, handler: makeRemoteHandler('onRemoteRemove') }
+  ] as const;
+
+  for (const { type, handler } of remoteHandlers) {
+    sm.rxdb.addEventListener(type, handler);
+    // 在注册点闭包捕获已静态对齐的 type/handler，解绑时无需类型断言
+    removers.push(() => sm.rxdb.removeEventListener(type, handler));
+  }
+
+  return { subscriptions, removers };
+}

package/src/sync-manager.utils.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview 同步管理器的纯函数工具集
+ *
+ * 从 {@link SyncManager} 抽出的无状态辅助函数。US-025 阶段 D 之前它们住在
+ * `@aiao/rxdb-plugin-history` 的 `version-manager.utils.ts`，随 `bulkSync` 一起搬过来 ——
+ * 两个函数的形参都是 {@link SyncRepositoryResult}，这是同步侧的类型。
+ */
+
+import { RxDBPartialSyncError } from '@aiao/rxdb';
+import type { SyncRepositoryResult } from './sync-repository.js';
+
+/**
+ * 「这次同步已经改写了本地数据」的共同判据形状。
+ *
+ * @remarks
+ * 四个粒度的结果都满足它，所以判据只需要写一份：整库 / 单仓库的 `PullResult` 只有
+ * `historyInvalidated`，`SyncRepositoryResult` 还多一段 `pushResult`。两项都取可选，
+ * 缺哪一段就当那一段没有进度。
+ */
+interface SyncedProgress {
+  readonly historyInvalidated?: boolean;
+  readonly pushResult?: { readonly pushed: number };
+}
+
+/** 一次仓库同步是否改写了本地实体数据（undo 历史边界因此失效） */
+export const hasSyncedData = (result: SyncedProgress | undefined): boolean =>
+  result?.historyInvalidated === true || (result?.pushResult?.pushed ?? 0) > 0;
+
+/**
+ * 中断的同步里是否带着「已经落库 / 已经上行」的进度。
+ *
+ * @remarks
+ * 部分成功以 {@link RxDBPartialSyncError} 的形式抛出，进度只挂在它的 `result` 上。
+ * `pull` / `pullRepository` / `sync` / `syncRepository` 四个入口共用这一条判据 ——
+ * 各写各的 `instanceof` + 强转，迟早会有一个入口漏掉 `pushResult` 那一半。
+ */
+export const partialSyncInvalidatesHistory = (error: unknown): boolean =>
+  error instanceof RxDBPartialSyncError && hasSyncedData(error.result as SyncedProgress);
+
+/**
+ * 取出失败项里携带的部分进度。
+ *
+ * @remarks
+ * 仓库在失败前可能已经提交了部分结果，它只存在于 {@link RxDBPartialSyncError.result}。
+ * 忽略它会让「远端数据已落库但 undo 边界没推进」的状态逃过检查。
+ */
+export const partialResultOf = (error: Error | undefined): SyncRepositoryResult | undefined =>
+  error instanceof RxDBPartialSyncError ? (error.result as SyncRepositoryResult) : undefined;