@aiao/rxdb-adapter-electron 0.0.26 → 0.0.28

package/src/pglite-host/pglite-host-restore.ts

@@ -0,0 +1,460 @@
+/**
+ * host 侧 PGlite 恢复协调器（US-217 阶段 C）。
+ *
+ * @remarks
+ * 一次恢复的生命周期：`pg.restore.begin` **先**取目录锁、**再**查恢复标记与空状态，独占一直保持到
+ * `commit` 或 `abort`（AC#12）；`prepare` 在第一次落盘之前持久化恢复标记，标记直到整棵树 fsync
+ * 之后才删除（AC#11）。步骤顺序固定为 prepare → write* → open → query* → persist → commit：
+ * 乱序请求报 `protocol_violation` 且不改变恢复状态，其余任何失败之后只接受 `abort`。
+ *
+ * @module pglite-host/pglite-host-restore
+ */
+
+import {
+  RxDBAdapterDesktopError,
+  type DesktopPgliteDataDirEntry,
+  type DesktopPgliteDataDirItem,
+  type DesktopPgliteQueryResult,
+  type DesktopPgliteResponse,
+  type DesktopPgliteRestoreQueryRequest,
+  type DesktopPgliteRestoreStepRequest,
+  type DesktopPgliteRestoreTargetRequest,
+  type DesktopPgliteRestoreWriteRequest
+} from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, type FileHandle } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  errnoOf,
+  hasPgVersion,
+  isEmptyOrMissing,
+  removePgliteDataDirectory,
+  syncPgliteDataDirectory,
+  toHostIoError
+} from './pglite-host-data-dir.js';
+import { acquirePgliteDirectoryLock, type PgliteDirectoryLock } from './pglite-host-lock.js';
+import { runStatement, toWireResult, type ElectronPgliteRuntime } from './pglite-host-runtime.js';
+
+/** 恢复协调器处理的全部请求。 */
+export type DesktopPgliteRestoreRequest =
+  | DesktopPgliteRestoreTargetRequest
+  | DesktopPgliteRestoreStepRequest
+  | DesktopPgliteRestoreWriteRequest
+  | DesktopPgliteRestoreQueryRequest;
+
+/** 作用于一次已开始的恢复的请求。 */
+type RestoreStepRequest = Exclude<DesktopPgliteRestoreRequest, DesktopPgliteRestoreTargetRequest>;
+
+/** {@link createPgliteRestoreCoordinator} 的依赖。 */
+export interface PgliteRestoreCoordinatorOptions {
+  /** 起一个运行时；恢复校验经它打开目标目录，与普通连接用同一份 PGlite 与扩展。 */
+  readonly createRuntime: (dataDirectoryName: string) => Promise<ElectronPgliteRuntime>;
+  /** 逻辑名到物理路径；必须就是 `createRuntime` 打开的目录。 */
+  readonly resolveDataDirectory: (dataDirectoryName: string) => string;
+  /** 本 host 是否正连着该目录；正在关闭的实例要等它关完再回答。 */
+  readonly isInUse: (dataDirectoryName: string) => Promise<boolean>;
+}
+
+/** 一个 host 内全部进行中的恢复。 */
+export interface PgliteRestoreCoordinator {
+  /** 进行中的恢复数。 */
+  readonly openCount: number;
+  /** 该名字是否正被本 host 的恢复占着（含正在取锁的）；`pg.open` 据此报 `restore_in_progress`。 */
+  isReserved(dataDirectoryName: string): boolean;
+  /**
+   * 处理一条恢复请求。
+   *
+   * @throws {@link RxDBAdapterDesktopError} 失败以桌面错误抛出，由 host 统一转成错误应答
+   */
+  handle(request: DesktopPgliteRestoreRequest, ownerId: number): Promise<DesktopPgliteResponse>;
+  /** 打断某个窗口名下的全部恢复：关资源、交还独占，**保留**恢复标记（AC#11）。 */
+  releaseOwner(ownerId: number): Promise<void>;
+  /** 打断全部恢复，语义同 {@link PgliteRestoreCoordinator.releaseOwner}。 */
+  closeAll(): Promise<void>;
+}
+
+type RestoreStage = 'begun' | 'prepared' | 'opened' | 'persisted' | 'failed';
+
+/** 正在写入的文件。 */
+interface OpenFile {
+  readonly handle: FileHandle;
+  readonly path: string;
+  readonly size: number;
+  written: number;
+}
+
+interface RestoreEntry {
+  readonly id: string;
+  readonly owner: number;
+  readonly dataDirectoryName: string;
+  readonly directory: string;
+  readonly lock: PgliteDirectoryLock;
+  stage: RestoreStage;
+  /** 恢复标记已落盘：此后中止必须删目录、清标记。 */
+  marked: boolean;
+  /** 条目声明的大小还没写满的文件。 */
+  file: OpenFile | undefined;
+  /** 校验用的私有实例；只在 `opened` 阶段存在。 */
+  runtime: ElectronPgliteRuntime | undefined;
+  /** 同一次恢复上的请求依次执行：上一步落地之前，下一步不会开始。 */
+  tail: Promise<void>;
+  /** 已提交、已中止或已被打断；排在后面的请求一律按恢复不存在处理。 */
+  finished: boolean;
+}
+
+/**
+ * 这几个 errno 说明归档描述的不是一棵合法的目录树：重复条目（`EEXIST`）、父目录不在归档里
+ * （`ENOENT`）、文件占了目录的位置（`ENOTDIR`）。目标在 begin 时是空的且一直被独占，
+ * 不存在别的来源。
+ */
+const CORRUPTING_ERRNOS: ReadonlySet<string> = new Set(['EEXIST', 'ENOENT', 'ENOTDIR']);
+
+const corrupted = (detail: string, options?: ErrorOptions): RxDBAdapterDesktopError =>
+  new RxDBAdapterDesktopError('database_corrupted', detail, options);
+
+const toWriteError = (error: unknown): RxDBAdapterDesktopError => {
+  if (error instanceof RxDBAdapterDesktopError) return error;
+  if (!CORRUPTING_ERRNOS.has(errnoOf(error) ?? '')) {
+    return toHostIoError(error, 'failed to write the restored PGlite data directory');
+  }
+  return corrupted('the archive does not describe a valid directory tree', { cause: error });
+};
+
+const outOfOrder = (entry: RestoreEntry, kind: RestoreStepRequest['kind']): RxDBAdapterDesktopError =>
+  new RxDBAdapterDesktopError('protocol_violation', `${kind} is not allowed while the restore is ${entry.stage}`);
+
+const expectStage = (entry: RestoreEntry, stage: RestoreStage, kind: RestoreStepRequest['kind']): void => {
+  if (entry.stage !== stage) throw outOfOrder(entry, kind);
+};
+
+const writeData = async (entry: RestoreEntry, bytes: Uint8Array): Promise<void> => {
+  const file = entry.file;
+  if (file === undefined) throw corrupted('a data chunk arrived without a file entry');
+  if (file.written + bytes.byteLength > file.size) {
+    throw corrupted(`the data of "${file.path}" exceeds its declared size`);
+  }
+  // `writeFile` 在当前位置写并自己处理短写；文件以 `wx` 打开后只经这里顺序写入。
+  await file.handle.writeFile(bytes);
+  file.written += bytes.byteLength;
+  if (file.written < file.size) return;
+  entry.file = undefined;
+  await file.handle.close();
+};
+
+const writeEntry = async (entry: RestoreEntry, header: DesktopPgliteDataDirEntry): Promise<void> => {
+  if (entry.file !== undefined) throw corrupted(`the data of "${entry.file.path}" is incomplete`);
+  const target = join(entry.directory, ...header.path.split('/'));
+  // 不递归、不覆盖：父目录必须先出现在归档里，同一路径只能出现一次。
+  if (header.kind === 'directory') {
+    await mkdir(target, { mode: 0o700 });
+    return;
+  }
+  const handle = await open(target, 'wx', 0o600);
+  if (header.size === 0) {
+    await handle.close();
+    return;
+  }
+  entry.file = { handle, path: header.path, size: header.size, written: 0 };
+};
+
+/**
+ * 创建一个 host 的恢复协调器。
+ *
+ * @param options - 运行时工厂、目录解析与本 host 的占用查询
+ * @returns 恢复协调器
+ */
+export const createPgliteRestoreCoordinator = (options: PgliteRestoreCoordinatorOptions): PgliteRestoreCoordinator => {
+  /** 被恢复占着的名字：从取锁之前一直到提交或中止。查与占之间没有 await，两次并发的 begin 只有一个能过。 */
+  const reserved = new Set<string>();
+  const entries = new Map<string, RestoreEntry>();
+
+  const claimTarget = async (name: string, directory: string): Promise<PgliteDirectoryLock> => {
+    if ((await options.isInUse(name)) || reserved.has(name)) {
+      throw new RxDBAdapterDesktopError('database_busy', `"${name}" is open or being restored in this host`);
+    }
+    reserved.add(name);
+    try {
+      return acquirePgliteDirectoryLock(directory);
+    } catch (error) {
+      reserved.delete(name);
+      throw error;
+    }
+  };
+
+  const releaseTarget = (name: string, lock: PgliteDirectoryLock): void => {
+    reserved.delete(name);
+    lock.release();
+  };
+
+  /** 删掉写了一半的目录再清标记；删不掉时标记留着，之后的连接据此被拒绝，而不是连上一个半恢复的库。 */
+  const discardTarget = async (name: string, directory: string, lock: PgliteDirectoryLock): Promise<void> => {
+    try {
+      await removePgliteDataDirectory(directory);
+      lock.clearRestoring();
+    } catch (error) {
+      throw new RxDBAdapterDesktopError(
+        'cleanup_pending',
+        `the incomplete restore of "${name}" could not be removed; run pg.restore.cleanup to retry`,
+        { cause: error }
+      );
+    }
+  };
+
+  const begin = async (request: DesktopPgliteRestoreTargetRequest, ownerId: number): Promise<DesktopPgliteResponse> => {
+    const name = request.storage.dataDirectoryName;
+    const directory = options.resolveDataDirectory(name);
+    const lock = await claimTarget(name, directory);
+    try {
+      if (lock.hasMarker()) {
+        throw new RxDBAdapterDesktopError(
+          'restore_incomplete',
+          `a restore of "${name}" did not finish; run pg.restore.cleanup first`
+        );
+      }
+      if (!(await isEmptyOrMissing(directory))) {
+        throw new RxDBAdapterDesktopError('target_not_empty', `"${name}" already holds data`);
+      }
+    } catch (error) {
+      releaseTarget(name, lock);
+      throw error;
+    }
+    const id = randomUUID();
+    entries.set(id, {
+      id,
+      owner: ownerId,
+      dataDirectoryName: name,
+      directory,
+      lock,
+      stage: 'begun',
+      marked: false,
+      file: undefined,
+      runtime: undefined,
+      tail: Promise.resolve(),
+      finished: false
+    });
+    return { kind: 'pg.restore.begin', result: { restoreId: id } };
+  };
+
+  const cleanup = async (request: DesktopPgliteRestoreTargetRequest): Promise<DesktopPgliteResponse> => {
+    const name = request.storage.dataDirectoryName;
+    const directory = options.resolveDataDirectory(name);
+    const lock = await claimTarget(name, directory);
+    try {
+      if (!lock.hasMarker()) return { kind: 'pg.restore.cleanup', result: { cleaned: false } };
+      await discardTarget(name, directory, lock);
+      return { kind: 'pg.restore.cleanup', result: { cleaned: true } };
+    } finally {
+      releaseTarget(name, lock);
+    }
+  };
+
+  const requireEntry = (restoreId: string, ownerId: number): RestoreEntry => {
+    const entry = entries.get(restoreId);
+    if (entry === undefined) {
+      throw new RxDBAdapterDesktopError('transaction_not_found', `restore ${restoreId} is unknown or already finished`);
+    }
+    if (entry.owner !== ownerId) {
+      throw new RxDBAdapterDesktopError('permission_denied', `restore ${restoreId} belongs to another window`);
+    }
+    return entry;
+  };
+
+  const runStep = <T>(entry: RestoreEntry, run: () => Promise<T>): Promise<T> => {
+    const result = entry.tail.then(() => {
+      if (entry.finished) {
+        throw new RxDBAdapterDesktopError('transaction_not_found', `restore ${entry.id} is already finished`);
+      }
+      return run();
+    });
+    entry.tail = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  };
+
+  /** 关掉本次恢复持有的文件与私有实例。尽力而为：调用方随后要么删目录，要么留着标记。 */
+  const releaseResources = async (entry: RestoreEntry): Promise<void> => {
+    const { file, runtime } = entry;
+    entry.file = undefined;
+    entry.runtime = undefined;
+    await file?.handle.close().catch(() => undefined);
+    await runtime?.close().catch(() => undefined);
+  };
+
+  const poisonOnFailure = async (entry: RestoreEntry, run: () => Promise<void>): Promise<void> => {
+    try {
+      await run();
+    } catch (error) {
+      if (!(error instanceof RxDBAdapterDesktopError && error.code === 'protocol_violation')) {
+        entry.stage = 'failed';
+        await releaseResources(entry);
+      }
+      throw error;
+    }
+  };
+
+  const finish = (entry: RestoreEntry): void => {
+    entry.finished = true;
+    entries.delete(entry.id);
+    releaseTarget(entry.dataDirectoryName, entry.lock);
+  };
+
+  const prepare = async (entry: RestoreEntry): Promise<void> => {
+    expectStage(entry, 'begun', 'pg.restore.prepare');
+    entry.lock.markRestoring();
+    entry.marked = true;
+    try {
+      await mkdir(entry.directory, { recursive: true, mode: 0o700 });
+    } catch (error) {
+      throw toHostIoError(error, 'failed to create the restore target');
+    }
+    entry.stage = 'prepared';
+  };
+
+  const writeStep = async (entry: RestoreEntry, item: DesktopPgliteDataDirItem): Promise<void> => {
+    expectStage(entry, 'prepared', 'pg.restore.write');
+    try {
+      await (item.type === 'data' ? writeData(entry, item.bytes) : writeEntry(entry, item.header));
+    } catch (error) {
+      throw toWriteError(error);
+    }
+  };
+
+  /**
+   * 起恢复专用的私有实例，并确认 PostgreSQL 真的起来了。
+   *
+   * @remarks
+   * 归档完整、PostgreSQL 却起不来，说明数据目录本身不可用：与浏览器端一致归为损坏，而不是 host 故障。
+   * 实例不登记会话，其他窗口与进程连不上它。
+   */
+  const startPrivateRuntime = async (name: string): Promise<ElectronPgliteRuntime> => {
+    let runtime: ElectronPgliteRuntime | undefined;
+    try {
+      runtime = await options.createRuntime(name);
+      await runtime.query('SELECT 1');
+      return runtime;
+    } catch (error) {
+      await runtime?.close().catch(() => undefined);
+      throw corrupted('the restored data directory cannot be opened', { cause: error });
+    }
+  };
+
+  const openTarget = async (entry: RestoreEntry): Promise<void> => {
+    expectStage(entry, 'prepared', 'pg.restore.open');
+    if (entry.file !== undefined) throw corrupted(`the data of "${entry.file.path}" is incomplete`);
+    // 没有 PG_VERSION 的目录会被 PGlite 就地 initdb 成一个空库，必须在起实例之前挡住。
+    if (!(await hasPgVersion(entry.directory))) throw corrupted('the archive has no PG_VERSION');
+    entry.runtime = await startPrivateRuntime(entry.dataDirectoryName);
+    entry.stage = 'opened';
+  };
+
+  const openedRuntime = (entry: RestoreEntry, kind: RestoreStepRequest['kind']): ElectronPgliteRuntime => {
+    const runtime = entry.runtime;
+    if (runtime === undefined) throw outOfOrder(entry, kind);
+    return runtime;
+  };
+
+  /** 校验查询失败只说明这条语句不成立，不作废恢复：是否中止由 renderer 的校验结论决定。 */
+  const query = async (
+    entry: RestoreEntry,
+    request: DesktopPgliteRestoreQueryRequest
+  ): Promise<DesktopPgliteQueryResult> => {
+    const runtime = openedRuntime(entry, request.kind);
+    return toWireResult(await runStatement(() => runtime.query(request.sql, [...request.params])));
+  };
+
+  const persist = async (entry: RestoreEntry): Promise<void> => {
+    const runtime = openedRuntime(entry, 'pg.restore.persist');
+    entry.runtime = undefined;
+    try {
+      await runtime.close();
+    } catch (error) {
+      throw toHostIoError(error, 'failed to close the restored PGlite instance');
+    }
+    await syncPgliteDataDirectory(entry.directory);
+    entry.stage = 'persisted';
+  };
+
+  const commit = (entry: RestoreEntry): void => {
+    expectStage(entry, 'persisted', 'pg.restore.commit');
+    entry.lock.clearRestoring();
+    finish(entry);
+  };
+
+  const abort = async (entry: RestoreEntry): Promise<void> => {
+    try {
+      await releaseResources(entry);
+      if (entry.marked) await discardTarget(entry.dataDirectoryName, entry.directory, entry.lock);
+    } finally {
+      finish(entry);
+    }
+  };
+
+  /** 窗口断开或 host 关闭：关资源、交还独占，**不**删目录也不清标记——重新打开时据标记拒绝连接（AC#11）。 */
+  const interrupt = (entry: RestoreEntry): Promise<void> =>
+    runStep(entry, async () => {
+      await releaseResources(entry);
+      finish(entry);
+    }).catch(() => undefined);
+
+  const runRequest = async (entry: RestoreEntry, request: RestoreStepRequest): Promise<DesktopPgliteResponse> => {
+    switch (request.kind) {
+      case 'pg.restore.prepare':
+        await poisonOnFailure(entry, () => prepare(entry));
+        return { kind: 'pg.restore.prepare' };
+      case 'pg.restore.write':
+        await poisonOnFailure(entry, () => writeStep(entry, request.item));
+        return { kind: 'pg.restore.write' };
+      case 'pg.restore.open':
+        await poisonOnFailure(entry, () => openTarget(entry));
+        return { kind: 'pg.restore.open' };
+      case 'pg.restore.query':
+        return { kind: 'pg.restore.query', result: await query(entry, request) };
+      case 'pg.restore.persist':
+        await poisonOnFailure(entry, () => persist(entry));
+        return { kind: 'pg.restore.persist' };
+      case 'pg.restore.commit':
+        await poisonOnFailure(entry, async () => commit(entry));
+        return { kind: 'pg.restore.commit' };
+      case 'pg.restore.abort':
+        await abort(entry);
+        return { kind: 'pg.restore.abort' };
+      default: {
+        const _exhaustive: never = request;
+        throw new RxDBAdapterDesktopError(
+          'protocol_violation',
+          `unsupported restore request kind: ${String((_exhaustive as { kind?: unknown }).kind)}`
+        );
+      }
+    }
+  };
+
+  const step = async (request: RestoreStepRequest, ownerId: number): Promise<DesktopPgliteResponse> => {
+    const entry = requireEntry(request.restoreId, ownerId);
+    return runStep(entry, () => runRequest(entry, request));
+  };
+
+  return {
+    get openCount(): number {
+      return entries.size;
+    },
+    isReserved: name => reserved.has(name),
+    handle: async (request, ownerId) => {
+      switch (request.kind) {
+        case 'pg.restore.begin':
+          return begin(request, ownerId);
+        case 'pg.restore.cleanup':
+          return cleanup(request);
+        default:
+          return step(request, ownerId);
+      }
+    },
+    releaseOwner: async ownerId => {
+      await Promise.all([...entries.values()].filter(entry => entry.owner === ownerId).map(interrupt));
+    },
+    closeAll: async () => {
+      await Promise.all([...entries.values()].map(interrupt));
+    }
+  };
+};

package/src/pglite-host/pglite-host-runtime.ts

@@ -0,0 +1,166 @@
+/**
+ * 桌面 PGlite host 与宿主应用之间的运行时契约，以及 host 各处共用的语句与事务工具。
+ *
+ * @module pglite-host/pglite-host-runtime
+ */
+
+import { RxDBAdapterDesktopError, type DesktopPgliteQueryResult } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+
+/** 一条语句的结果；`ElectronPgliteRuntime` 与 PGlite 的 `Results` 在此结构相容。 */
+export interface ElectronPgliteRuntimeResult {
+  readonly rows: Record<string, unknown>[];
+  readonly fields: { name: string; dataTypeID: number }[];
+  readonly affectedRows?: number;
+}
+
+/** 事务句柄；对应 PGlite 的 `Transaction`，只声明 host 真正用到的两个操作。 */
+export interface ElectronPgliteTransaction {
+  query(sql: string, params?: unknown[]): Promise<ElectronPgliteRuntimeResult>;
+  exec(sql: string): Promise<ElectronPgliteRuntimeResult[]>;
+}
+
+/**
+ * host 需要的 PGlite 能力子集。
+ *
+ * @remarks
+ * 刻意不写成 `PGliteInterface`：宿主应用极可能传进来的不是裸 `PGlite`，而是跑在 worker
+ * 里的 `PGliteWorker`——PGlite 的 WASM 在主进程 JS 线程上是**同步**执行的，一条重查询会
+ * 把整个窗口的 IPC 一起卡住（故事「冻结带来的三条实现约束」第 3 条）。声明成结构类型后，
+ * 两者都能直接传入，而这份清单也顺便说清了 host 只需要这五个操作。
+ */
+export interface ElectronPgliteRuntime {
+  query(sql: string, params?: unknown[]): Promise<ElectronPgliteRuntimeResult>;
+  exec(sql: string): Promise<ElectronPgliteRuntimeResult[]>;
+  transaction<T>(callback: (tx: ElectronPgliteTransaction) => Promise<T>): Promise<T>;
+  listen(channel: string, callback: (payload: string) => void): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+/**
+ * 回答 `pg.engine` 的探针运行时：只需要查询与关闭（US-217）。
+ *
+ * @remarks
+ * 裸 `new PGlite()`（内存实例）即满足；它必须与 `createRuntime` 起的实例是同一份 PGlite、
+ * 带同一组扩展，否则回答的引擎版本对真实数据目录不成立。
+ */
+export type ElectronPgliteProbeRuntime = Pick<ElectronPgliteRuntime, 'query' | 'close'>;
+
+/**
+ * 把 PGlite 的结果收窄成能过结构化克隆的形状。
+ *
+ * @remarks
+ * `fields` 上除了 `name` / `dataTypeID` 还挂着 PGlite 自己的解析器，整个丢给
+ * `ipcRenderer.invoke` 会以 DataCloneError 失败——而报错点在 IPC 层，看上去与 SQL 毫无关系。
+ * `rows` 里的 bigint / Uint8Array / Date 都是结构化克隆原生支持的，原样带走（AC#1）。
+ *
+ * @param result - 运行时返回的结果
+ * @returns 可以跨进程传递的结果
+ */
+export const toWireResult = (result: ElectronPgliteRuntimeResult): DesktopPgliteQueryResult => ({
+  rows: result.rows,
+  fields: result.fields.map(field => ({ name: field.name, dataTypeID: field.dataTypeID })),
+  affectedRows: result.affectedRows
+});
+
+/**
+ * 跑一条语句，把引擎抛出的错误归一成 `statement_failed`。
+ *
+ * @remarks
+ * 不归一的话，一条写错的 SQL 会以 `host_internal_error` 回到 renderer——那个码的含义是
+ * 「host 有缺陷」，会把调用方的排查引向完全错误的方向。
+ *
+ * @param run - 执行语句
+ * @returns 语句结果
+ * @throws {@link RxDBAdapterDesktopError} 语句失败时为 `statement_failed`；已经是桌面错误的原样透传
+ */
+export const runStatement = async <T>(run: () => Promise<T>): Promise<T> => {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof RxDBAdapterDesktopError) throw error;
+    throw new RxDBAdapterDesktopError('statement_failed', error instanceof Error ? error.message : String(error), {
+      cause: error
+    });
+  }
+};
+
+/** 一条挂起中的事务：`transaction(cb)` 的 callback 停在 host 持有的 promise 上。 */
+export interface SuspendedTransaction {
+  readonly tx: ElectronPgliteTransaction;
+  /** 结掉 callback：`resolve` 提交，`reject` 让 callback 抛出从而回滚。 */
+  readonly settle: { readonly resolve: () => void; readonly reject: (error: Error) => void };
+  /** `transaction(...)` 本身；等它落地才算真的提交/回滚完。 */
+  readonly finished: Promise<unknown>;
+}
+
+/** 等连接等到超时的哨兵；用 Symbol 是因为任何合法的 `tx` 都不可能与它相等。 */
+const TIMED_OUT = Symbol('transaction begin timed out');
+
+const raceTimeout = async <T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<typeof TIMED_OUT>(resolve => {
+        timer = setTimeout(() => resolve(TIMED_OUT), ms);
+      })
+    ]);
+  } finally {
+    // 不清掉的话，一次成功的 begin 也会让 Node 的事件循环多活 `ms` 毫秒，
+    // 于是应用退出被推迟——在测试里表现为「跑完了但进程不退」。
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * 在运行时上开一条事务并把它挂起，直到调用方结掉 `settle`。
+ *
+ * @remarks
+ * PGlite 只提供 callback 形态的事务（`transaction(cb)`，返回即 COMMIT、抛出即 ROLLBACK），
+ * 而 `cb` 跨不了 IPC。这里进入 `cb` 后立刻 `await` 一个由 host 持有的 promise，事务因此在
+ * PostgreSQL 侧一直开着、连接一直被占住。`pg.begin` 用它把多次 IPC 串成一条真事务，
+ * `pg.backup.begin` 用它在读快照期间挡住一切写入（AC#16）。
+ *
+ * @param runtime - 运行时
+ * @param timeout - 等待连接空闲的上限（毫秒）
+ * @returns 已挂起的事务
+ * @throws {@link RxDBAdapterDesktopError} `transaction_unavailable`：到期时连接仍被别的事务占着
+ */
+export const suspendTransaction = async (
+  runtime: ElectronPgliteRuntime,
+  timeout: number
+): Promise<SuspendedTransaction> => {
+  let settle!: SuspendedTransaction['settle'];
+  const closed = new Promise<void>((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  // 超时路径会在任何人 await 之前就 reject 它；先接住，免得变成未处理拒绝而打死进程。
+  closed.catch(() => undefined);
+
+  let markStarted!: (tx: ElectronPgliteTransaction) => void;
+  const started = new Promise<ElectronPgliteTransaction>(resolve => {
+    markStarted = resolve;
+  });
+  const finished = runtime.transaction(async tx => {
+    markStarted(tx);
+    // 事务从这里一直开着，直到调用方结掉 `closed`。
+    await closed;
+  });
+  finished.catch(() => undefined);
+
+  const tx = await raceTimeout(started, timeout);
+  if (tx === TIMED_OUT) {
+    // 关键在于 reject 而不是简单丢弃：被丢弃的 callback 迟早会在连接空出来的一瞬间
+    // 启动，然后永远挂在 `await closed` 上——于是「超时之后再也开不了事务」，
+    // 而现场看起来只是「数据库不响应」。reject 让它一进 callback 就抛，
+    // PGlite 随即回滚这条空事务并交还连接。
+    settle.reject(
+      new RxDBAdapterDesktopError('transaction_unavailable', 'the begin that opened this transaction timed out')
+    );
+    throw new RxDBAdapterDesktopError(
+      'transaction_unavailable',
+      `waited ${timeout}ms for the PGlite connection but another transaction still holds it`
+    );
+  }
+  return { tx, settle, finished };
+};

package/src/pglite-host.ts

@@ -16,8 +16,10 @@
 export {
   DESKTOP_PGLITE_WATCH_CHANNELS,
   createElectronPgliteHost,
+  type ElectronPgliteBackupOptions,
   type ElectronPgliteHost,
   type ElectronPgliteHostOptions,
+  type ElectronPgliteProbeRuntime,
   type ElectronPgliteRuntime,
   type ElectronPgliteRuntimeResult,
   type ElectronPgliteTransaction
@@ -27,7 +29,9 @@ export {
 // 就该拿全写一个 PGlite host 需要的全部东西。
 export {
   DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS,
+  DESKTOP_PGLITE_EXCLUDED_FILES,
   DESKTOP_PGLITE_MAX_BEGIN_TIMEOUT_MS,
+  DESKTOP_PGLITE_MAX_DATA_CHUNK_BYTES,
   DESKTOP_PGLITE_PROTOCOL_VERSION,
   RxDBAdapterDesktopError,
   // 宿主自己拼数据目录路径时要用：协议校验管的是「请求合法」，落盘前那次校验管的是
@@ -35,6 +39,9 @@ export {
   assertValidDesktopDatabaseName,
   isDesktopPgliteRequestKind,
   parseDesktopPgliteRequest,
+  type DesktopPgliteBackupItem,
+  type DesktopPgliteDataDirItem,
+  type DesktopPgliteEngineResult,
   type DesktopPgliteNotifyMessage,
   type DesktopPgliteQueryResult,
   type DesktopPgliteRequest,

package/src/pglite.ts

@@ -24,6 +24,15 @@ export { RxDBAdapterElectronPGlite } from './pglite/RxDBAdapterElectronPGlite.js
 
 export { DesktopPGliteClient, type DesktopPGliteClientOptions } from './pglite/desktop-pglite-client.js';
 
+// 备份在 adapter 上；恢复的目标还没连接、没有 adapter 可调，只能是自由函数。
+// 选项与阶段沿用浏览器 PGlite 的类型，一并转出，调用方不必为签名再去 import 那个 peer。
+export type { PGliteRestoreOptions, PGliteRestoreStage } from '@aiao/rxdb-adapter-pglite';
+export {
+  cleanupIncompleteElectronPGliteRestore,
+  restoreElectronPGliteDatabase,
+  type ElectronPGliteRestoreTarget
+} from './pglite/restore-electron-pglite-database.js';
+
 // 协议常量与错误类型原样转出，理由与默认入口一致：下游按名字 import，
 // 实现搬到哪个共享包不该让用户改行。
 export {