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

package/src/pull-round.ts

@@ -0,0 +1,103 @@
+/**
+ * @packageDocumentation
+ * 一轮拉取里与「谁推的、映射回哪一行」有关的两步。
+ *
+ * @remarks
+ * `pullBatchOnce`（`pull-batch.ts`）与 `pullSingleRepository`（`pull-repository.ts`）走的是
+ * 同一段流程：**拆分自推与他人的变更 → 回填自推变更的 `remoteId` → 压缩他人变更 → 解冲突 →
+ * 合并进实体表 → 推水位线**。两边曾各抄一份，而抄件会分叉——next-11 评审复核时实测到的分叉
+ * 正在这里：一侧把「只回填还没映射过的行」写进 SQL（`remoteId = null` → `IS NULL`），
+ * 一侧写成 JS 守卫（`local.remoteId == null`）。两种写法当时判据相同，但**没有任何东西保证
+ * 下一次改动仍然相同**，而一侧漏改不会让任何用例变红。
+ *
+ * 本模块收的是那段流程里**不碰受信写原语**的前半截。后半截（`executor.mergeChanges` 与随之
+ * 而来的 supersession 标记）留在各自文件里，不是嫌麻烦：那一次写要按 `file`·`symbol`·`intent`
+ * 在 `TRUSTED_CALLSITE_REGISTRY` 里对号入座（`declareTrustedWrite`），搬进本模块等于把两个
+ * 登记入口合并成一个——那是核心包的适配器契约变更，不是同步插件自己能定的事。
+ */
+
+import { type IRepository, type RemoteChange, type RxDBChange } from '@aiao/rxdb';
+
+/** {@link splitRemoteChangesByOrigin} 的结果 */
+export interface RemoteChangeOrigins {
+  /** 本客户端自己 push 上去、这轮又拉回来的变更 */
+  ownChanges: RemoteChange[];
+  /** 其他客户端产生的变更，只有这一批进 apply / conflict 链路 */
+  otherChanges: RemoteChange[];
+}
+
+/**
+ * 按 `clientId` 把一批远端变更拆成「自己推的」与「他人的」
+ *
+ * @param changes - 本轮拉到的远端变更
+ * @param clientId - 本客户端 id
+ * @returns 两个互斥的子集，顺序与入参一致
+ *
+ * @remarks
+ * **只认 `clientId`，不拿 `localId` 当替补**：push 走 actions-only 路径时远端记录不带 `localId`，
+ * 若用「有 localId 就是自己的」去判，这类记录会被判成他人的而重复应用一遍；反过来，若把
+ * 「没有 clientId」也算成自己的，那这批数据拉下来了却永远不进 apply 链路——静默丢数据。
+ * 所以缺 `clientId` 一律算他人的：多走一遍幂等的 apply，好过整批不落库。
+ */
+export const splitRemoteChangesByOrigin = (
+  changes: RemoteChange[],
+  clientId: string | undefined
+): RemoteChangeOrigins => {
+  const ownChanges: RemoteChange[] = [];
+  const otherChanges: RemoteChange[] = [];
+
+  for (const change of changes) {
+    if (change.clientId != null && change.clientId === clientId) {
+      ownChanges.push(change);
+    } else {
+      otherChanges.push(change);
+    }
+  }
+
+  return { ownChanges, otherChanges };
+};
+
+/**
+ * 把自推变更拿到的远端 id 回填到对应的本地 `RxDBChange` 行上
+ *
+ * @param changeRepo - 变更表仓库；在事务里调用时必须是经 executor 取到的那一个
+ * @param ownChanges - {@link splitRemoteChangesByOrigin} 分出的自推变更
+ *
+ * @remarks
+ * 只回填 `remoteId` 还空着的行，判据写在 SQL 里（`= null` 由适配器编译成 `IS NULL`）而不是
+ * 取回来再用 JS 挑：少取一批行是次要的，主要是让「只写没映射过的」成为查询本身的一部分，
+ * 而不是一条可以被下一次改动顺手删掉的 `if`。
+ *
+ * 覆盖已有映射不是小事：`cleanupExpired` 按 `remoteId` 判「这条已经同步出去了」，
+ * 把旧映射改写成本轮的 id 会让保留窗口整段错位——旧变更被当成刚同步的留下来，
+ * 而真正该留的那批反而先到期。
+ *
+ * 没有 `localId` 的自推变更直接跳过：对不上本地行，硬回填只能靠猜。
+ */
+export const backfillOwnChangeRemoteIds = async (
+  changeRepo: IRepository<typeof RxDBChange>,
+  ownChanges: RemoteChange[]
+): Promise<void> => {
+  const mappableChanges = ownChanges.filter(change => change.localId != null);
+  if (mappableChanges.length === 0) return;
+
+  const locals = await changeRepo.find({
+    where: {
+      combinator: 'and',
+      rules: [
+        { field: 'id', operator: 'in', value: mappableChanges.map(change => change.localId!) },
+        { field: 'remoteId', operator: '=', value: null },
+        // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+        // 不该被本轮回填覆盖掉——覆盖了反而让 cleanupExpired 的保留窗口误判
+        { field: 'rejectedAt', operator: '=', value: null }
+      ]
+    }
+  });
+  if (locals.length === 0) return;
+
+  const remoteIdByLocalId = new Map(mappableChanges.map(change => [change.localId!, change.id]));
+  for (const local of locals) {
+    const remoteId = remoteIdByLocalId.get(local.id);
+    if (remoteId != null) await changeRepo.update(local, { remoteId });
+  }
+};

package/src/pull.ts

@@ -0,0 +1,204 @@
+import {
+  findCurrentSyncRecord,
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  isRepositorySyncEnabled,
+  PullOptions,
+  PullRepositoryResult,
+  PullResult,
+  RxDBError,
+  RxDBPartialSyncError,
+  SyncBeginEvent,
+  SyncCompleteEvent,
+  SyncErrorEvent
+} from '@aiao/rxdb';
+import { BulkSyncOptions } from './bulk-sync.js';
+import { pullBatch } from './pull-batch.js';
+import { pullRepository } from './pull-repository.js';
+import type { SyncManager } from './SyncManager.js';
+
+/**
+ * Pull 功能实现
+ *
+ * 从远程拉取变更并应用到本地实体表
+ *
+ * 默认使用 pullBatch 单次 HTTP 请求拉取所有实体的变更。
+ * 当指定 repositoryFilter 时，降级为 bulkSync 逐实体拉取。
+ *
+ * @param sm - SyncManager 实例
+ * @param options - Pull 选项
+ * @returns Pull 结果
+ */
+export async function pull(sm: SyncManager, options?: PullOptions): Promise<PullResult> {
+  const rxdb = sm.rxdb;
+
+  // 验证远程适配器配置
+  const remoteAdapterName = rxdb.config.sync?.remote?.adapter;
+  if (!remoteAdapterName) {
+    throw new RxDBError('Remote adapter not configured.');
+  }
+
+  // 触发同步开始事件
+  rxdb.dispatchEvent(new SyncBeginEvent('pull'));
+
+  try {
+    let pullResult: PullResult;
+
+    if (!options?.repositoryFilter?.length) {
+      // 无过滤时使用批量拉取（单次 HTTP 请求）
+      pullResult = await pullBatch(sm, {
+        limit: options?.limit,
+        fetchAll: options?.fetchAll,
+        conflictResolver: options?.conflictResolver
+      });
+      // pullBatch 对 syncType === 'filter' 的仓库直接 continue（过滤条件是逐仓库的，
+      // 拼不进一次批量请求）。不补这一趟，pull() 就会对 filter 仓库一条不拉却报告
+      // `hasMore:false, failures:[]` —— isCompletePull 判真、pullableCount 归零，
+      // 用户看到的是「已全部同步」。
+      await pullFilterRepositories(sm, options, pullResult);
+    } else {
+      // 指定仓库过滤时降级为逐仓库拉取
+      pullResult = await pullWithBulkSync(sm, options);
+    }
+
+    // 触发同步完成事件
+    rxdb.dispatchEvent(new SyncCompleteEvent('pull', pullResult));
+
+    return pullResult;
+  } catch (error) {
+    // 触发同步错误事件
+    rxdb.dispatchEvent(new SyncErrorEvent('pull', error as Error));
+    throw error;
+  }
+}
+
+/**
+ * 补拉 `syncType === 'filter'` 的仓库，并把结果并进批量拉取的聚合里。
+ *
+ * @param sm - SyncManager 实例
+ * @param options - 调用方传给 `pull()` 的选项，`limit` / `fetchAll` 原样透传
+ * @param aggregated - `pullBatch` 的结果，**就地**累加
+ *
+ * @remarks
+ * `includeRelated: false`：批量那一趟已经覆盖了所有非 filter 仓库，再级联一次只会重复拉取。
+ * 单个仓库失败不中断其余仓库，失败结构化进 `failures` —— 与 `pullWithBulkSync` 同口径。
+ */
+async function pullFilterRepositories(sm: SyncManager, options: PullOptions | undefined, aggregated: PullResult) {
+  const rxdb = sm.rxdb;
+
+  for (const EntityClass of rxdb.config.entities) {
+    const metadata = getEntityMetadata(EntityClass);
+    const syncType = getSyncType(metadata, rxdb.entitySync);
+    if (syncType !== 'filter' || !getSyncCapability(syncType).pull) continue;
+
+    const repoSync = await findCurrentSyncRecord(sm.rxdb, metadata.namespace, metadata.name);
+    if (!isRepositorySyncEnabled(repoSync)) continue;
+
+    let result: PullRepositoryResult;
+    try {
+      result = await pullRepository(sm, metadata.namespace, metadata.name, {
+        limit: options?.limit,
+        fetchAll: options?.fetchAll,
+        conflictResolver: options?.conflictResolver,
+        includeRelated: false
+      });
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      // 失败前已提交的进度挂在 RxDBPartialSyncError.result 上，同样要并进聚合
+      if (normalized instanceof RxDBPartialSyncError) {
+        accumulatePullProgress(aggregated, normalized.result as PullRepositoryResult);
+      }
+      aggregated.failures.push({
+        repository: { namespace: metadata.namespace, entity: metadata.name },
+        error: normalized instanceof RxDBPartialSyncError ? normalized.cause : normalized
+      });
+      continue;
+    }
+
+    accumulatePullProgress(aggregated, result);
+    aggregated.failures.push(...result.failures);
+  }
+}
+
+/** 把一个仓库的拉取进度就地累加进聚合结果（不含 failures）。 */
+function accumulatePullProgress(aggregated: PullResult, result: PullRepositoryResult): void {
+  aggregated.pulled += result.pulled;
+  aggregated.compacted += result.compacted;
+  aggregated.applied += result.applied;
+  aggregated.conflictsResolved += result.conflictsResolved;
+  aggregated.conflictsDeferred += result.conflictsDeferred;
+  aggregated.hasMore ||= result.hasMore;
+  aggregated.persistedProgress ||= result.persistedProgress;
+  aggregated.historyInvalidated ||= result.historyInvalidated;
+}
+
+/**
+ * 降级方案：使用 bulkSync 逐仓库拉取（用于指定 repositoryFilter 的场景）
+ */
+async function pullWithBulkSync(sm: SyncManager, options: PullOptions): Promise<PullResult> {
+  const bulkOptions: BulkSyncOptions = {
+    operation: 'pull',
+    repositories: options.repositoryFilter?.map(item => {
+      if (typeof item === 'string') {
+        return { namespace: 'public', entity: item };
+      }
+      return item;
+    }),
+    // 此前这里漏传，逐仓库拉取时 limit/fetchAll 静默失效
+    pull: { limit: options.limit, fetchAll: options.fetchAll, conflictResolver: options.conflictResolver }
+  };
+
+  const bulkResult = await sm.bulkSync(bulkOptions);
+
+  const aggregated: PullResult = {
+    pulled: 0,
+    compacted: 0,
+    applied: 0,
+    hasMore: false,
+    conflictsResolved: 0,
+    conflictsDeferred: 0,
+    persistedProgress: false,
+    historyInvalidated: false,
+    failures: []
+  };
+
+  for (const result of bulkResult.results) {
+    // 失败仓库自己已提交的进度也要累加 —— 它藏在 `RxDBPartialSyncError.result`
+    // 里，被 bulkSync 原样挂在 `result.result` 上，只看 success 会把这段进度丢掉。
+    const pullResult = result.result?.pullResult;
+    if (pullResult) {
+      aggregated.pulled += pullResult.pulled;
+      aggregated.compacted += pullResult.compacted;
+      aggregated.applied += pullResult.applied;
+      aggregated.conflictsResolved += pullResult.conflictsResolved;
+      aggregated.conflictsDeferred += pullResult.conflictsDeferred;
+      aggregated.hasMore ||= pullResult.hasMore;
+      aggregated.persistedProgress ||= pullResult.persistedProgress;
+      aggregated.historyInvalidated ||= pullResult.historyInvalidated;
+    }
+
+    if (result.success) continue;
+
+    // 此前失败的仓库被静默跳过，调用方拿到「成功」的聚合结果
+    // 只留第一个失败会让后面几个仓库的失败无处可查，全部结构化保留
+    const failure =
+      result.error ??
+      new RxDBError(`Repository pull failed: ${result.repository.namespace}:${result.repository.entity}`);
+    aggregated.failures.push({
+      repository: result.repository,
+      // 嵌套的 partial error 解包成根因，避免调用方拿到「错误里套错误」
+      error: failure instanceof RxDBPartialSyncError ? failure.cause : failure
+    });
+  }
+
+  const [firstFailure] = aggregated.failures;
+  if (firstFailure) {
+    // 单个失败且零进度时包装只会多剥一层，原始错误更有用（对齐 pull-batch.ts 的约定）；
+    // 但只要有进度、或有多于一个失败，就必须包装 —— 否则进度和其余失败都无处可查。
+    if (!aggregated.persistedProgress && aggregated.failures.length === 1) throw firstFailure.error;
+    throw new RxDBPartialSyncError<PullResult>(aggregated, firstFailure.error);
+  }
+
+  return aggregated;
+}

package/src/push-branch.ts

@@ -0,0 +1,62 @@
+import { MAIN_BRANCH_ID } from '@aiao/rxdb';
+import { toRemoteFromChangeId } from './branch-change-id.js';
+import type { SyncManager } from './SyncManager.js';
+
+export interface PushBranchResult {
+  synced: number;
+  skipped: string[];
+  /**
+   * 分叉点变更还没有 `remoteId`，本次只能带 `fromChangeId: null` 上行。
+   *
+   * 调用方应在实体变更推送完成、分叉点拿到 `remoteId` 之后重推一次分支，
+   * 把远端那一行补全。
+   */
+  forkPointPending: boolean;
+}
+
+/**
+ * 将当前激活分支推送到远程
+ *
+ * 规则:
+ * 1. 不推送根分支（{@link MAIN_BRANCH_ID}）
+ * 2. 不修改远程分支的 activated 属性（由 SQL 函数保证）
+ * 3. `fromChangeId` 翻译成远端 id 后再上行（见 {@link toRemoteFromChangeId}）
+ */
+export async function pushBranch(sm: SyncManager): Promise<PushBranchResult> {
+  const branch = await sm.getCurrentBranch();
+  if (!branch || branch.id === MAIN_BRANCH_ID) {
+    return { synced: 0, skipped: branch ? [MAIN_BRANCH_ID] : [], forkPointPending: false };
+  }
+
+  const { adapter: remoteAdapter } = await sm.getRemoteRepositories();
+
+  if (!remoteAdapter.pushBranches) {
+    return { synced: 0, skipped: [], forkPointPending: false };
+  }
+
+  const { branchRepository, changeRepository } = await sm.getLocalRepositories();
+
+  // 本地 change id 对远端毫无意义，必须翻译成 remoteId 再上行。
+  // 分叉点还没推上去时只能发 null（远端此刻确实不知道这个分叉点），并把这件事报给调用方。
+  const localFromChangeId = branch.fromChangeId ?? null;
+  const remoteFromChangeId =
+    localFromChangeId === null ? null : await toRemoteFromChangeId(changeRepository, localFromChangeId);
+  const forkPointPending = localFromChangeId !== null && remoteFromChangeId === null;
+
+  const branchData: Record<string, unknown> = {
+    id: branch.id,
+    fromChangeId: remoteFromChangeId,
+    local: branch.local,
+    remote: true,
+    parentId: branch.parentId
+  };
+
+  const result = await remoteAdapter.pushBranches([branchData]);
+
+  // 推送成功后更新本地分支的 remote 标记
+  if (result.synced > 0 && !branch.remote) {
+    await branchRepository.update(branch, { remote: true, updatedAt: new Date() });
+  }
+
+  return { ...result, forkPointPending };
+}