@aiao/rxdb-adapter-electron 0.0.26 → 0.0.28

package/src/RxDBAdapterElectron.ts

@@ -5,11 +5,12 @@
  */
 
 import type { RxDB } from '@aiao/rxdb';
-import { RxDBAdapterSqliteBase } from '@aiao/rxdb-adapter-sqlite-core';
+import { RxDBAdapterSqliteBase, type SqliteBackupStorage, type SqliteClientLike } from '@aiao/rxdb-adapter-sqlite-core';
 import {
   DEFAULT_DATABASE_SUFFIX,
   DesktopSqliteClient,
   assertValidDesktopDatabaseName,
+  connectDesktopRestoreTarget,
   resolveDesktopHostTransport,
   type DesktopOptions
 } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
@@ -28,6 +29,8 @@ import { ADAPTER_NAME } from './electron-adapter.interface.js';
  */
 export class RxDBAdapterElectron extends RxDBAdapterSqliteBase {
   readonly #databaseName: string;
+  /** 备份与恢复争用的锁名，按库文件而不是 `dbName` 区分（见 {@link backupStorage}）。 */
+  readonly #storageKey: string;
   override readonly name: string = ADAPTER_NAME;
 
   /** 解析出的逻辑数据库名，与 host 侧的物理文件一一对应。 */
@@ -48,6 +51,7 @@ export class RxDBAdapterElectron extends RxDBAdapterSqliteBase {
     this.#databaseName = options.databaseName ?? `${rxdb.config.dbName}${DEFAULT_DATABASE_SUFFIX}`;
     // 在构造期就校验：名字非法时根本没有能打开的库，等发出 IPC 才报错只会让原因离现场更远。
     assertValidDesktopDatabaseName(this.#databaseName);
+    this.#storageKey = `${this.name}:file:${this.#databaseName}`;
   }
 
   protected override async createClient(): Promise<DesktopSqliteClient> {
@@ -57,6 +61,41 @@ export class RxDBAdapterElectron extends RxDBAdapterSqliteBase {
       { batchTimeout: this.options.batchTimeout }
     );
   }
+
+  /**
+   * 桌面库是应用数据目录里的一个库文件，备份与恢复都按它支持。
+   *
+   * @remarks
+   * `storageKey` 用库文件名而不是 `dbName`：配了同一个 `databaseName` 的两个实例打开的是同一个文件，
+   * 必须争同一把锁；同名实例恢复到另一个 `databaseName`（新的数据位置）则与原库互不相干。
+   *
+   * @returns 持久化存储后端，`label` 为 `file`
+   */
+  protected override backupStorage(): SqliteBackupStorage {
+    return { kind: 'persistent', label: 'file', storageKey: this.#storageKey };
+  }
+
+  /**
+   * Electron host 以 defensive 模式运行 SQLite，改不了影子表。
+   *
+   * @remarks
+   * host 在特权主进程里执行 renderer 透传的 SQL；defensive 挡住直接改写影子表、`writable_schema` 这类
+   * 能把库文件改坏的操作，不能为了恢复而关掉。含 FTS5 等虚表的库因此不在 Electron 的备份矩阵里。
+   *
+   * @returns 恒为 `false`
+   */
+  protected override shadowTablesWritable(): boolean {
+    return false;
+  }
+
+  /**
+   * 别的窗口、别的进程可能开着同一个库文件，Web Lock 挡不住它们：恢复与清理前先让这条连接独占库文件。
+   *
+   * @returns 独占库文件的连接
+   */
+  protected override createRestoreTargetClient(): Promise<SqliteClientLike> {
+    return connectDesktopRestoreTarget(() => this.createClient(), this.#storageKey);
+  }
 }
 
 declare module '@aiao/rxdb' {

package/src/electron-sqlite-host.ts

@@ -266,6 +266,9 @@ export function createElectronSqliteHost(options: ElectronSqliteHostOptions): El
         return close(request.sessionId);
       case 'version':
         return { kind: 'version', result: requireSession(request.sessionId).version() };
+      case 'mute':
+        requireSession(request.sessionId).setChangeEventsMuted(request.muted);
+        return { kind: 'mute' };
       case 'execute':
         return execute(request);
       default: {

package/src/host.ts

@@ -55,6 +55,7 @@ export {
   type DesktopHostFileStat,
   type DesktopHostHandshakeRequest,
   type DesktopHostHandshakeResult,
+  type DesktopHostMuteRequest,
   type DesktopHostOpenRequest,
   type DesktopHostOpenResult,
   type DesktopHostRequest,

package/src/index.ts

@@ -62,6 +62,7 @@ export {
   type DesktopHostFileStat,
   type DesktopHostHandshakeRequest,
   type DesktopHostHandshakeResult,
+  type DesktopHostMuteRequest,
   type DesktopHostOpenRequest,
   type DesktopHostOpenResult,
   type DesktopHostRequest,

package/src/node-sqlite-engine.ts

@@ -224,6 +224,8 @@ export class NodeSqliteEngine {
   #maxWaitTimer?: BatchTimer;
   #changesStatement?: StatementSync;
   #totalChangesStatement?: StatementSync;
+  /** 为 `true` 时通知函数照常被触发器调用，但变更既不入批也不派发。 */
+  #muted = false;
   #closed = false;
 
   private constructor(db: DatabaseSync, options: NodeSqliteEngineOptions) {
@@ -249,7 +251,9 @@ export class NodeSqliteEngine {
   static open(options: NodeSqliteEngineOptions): NodeSqliteEngine {
     let db: DatabaseSync;
     try {
-      db = new DatabaseSync(options.filePath);
+      // defensive 显式钉住而不靠运行时默认值：host 在特权主进程里执行 renderer 透传的 SQL，
+      // 不能让它直接改写影子表或 schema 把库文件改坏。代价是恢复不了含影子表的库，备份侧因此整体拒绝这类库。
+      db = new DatabaseSync(options.filePath, { defensive: true });
     } catch (error) {
       throw new RxDBAdapterDesktopError(
         classify(error, 'open_failed'),
@@ -317,6 +321,20 @@ export class NodeSqliteEngine {
     return String(row?.rows[0]?.[0]);
   }
 
+  /**
+   * 暂停 / 恢复变更事件采集。
+   *
+   * @remarks
+   * 恢复整库时静音（US-217）：恢复写进去的系统表行不是新变更。静音前已经攒下的批次不丢，
+   * 照常按定时器发出——它们记录的是静音前真实发生的写入。
+   *
+   * @param muted - `true` 时触发器报上来的变更直接丢弃，不入批也不派发
+   */
+  setChangeEventsMuted(muted: boolean): void {
+    this.#assertOpen();
+    this.#muted = muted;
+  }
+
   /**
    * 断开连接并释放文件句柄。
    *
@@ -470,6 +488,7 @@ export class NodeSqliteEngine {
   }
 
   #recordChange(type: SQLiteChangeType, tableName: string, rowId: bigint): void {
+    if (this.#muted) return;
     const key = `${type} ${tableName}`;
     const pending = this.#pendingChanges.get(key);
     if (pending) pending.rowIds.push(rowId);

package/src/pglite/RxDBAdapterElectronPGlite.ts

@@ -4,14 +4,18 @@
  * @module pglite/RxDBAdapterElectronPGlite
  */
 
-import type { RxDB } from '@aiao/rxdb';
+import type { RxDB, RxDBBackupOptions, RxDBBackupResult } from '@aiao/rxdb';
 import { RxDBAdapterPGlite, type IPGliteClient } from '@aiao/rxdb-adapter-pglite';
 import {
+  assertDesktopPgliteResponse,
   assertValidDesktopDatabaseName,
-  resolveDesktopHostTransport
+  parseDesktopPgliteEngineResult,
+  resolveDesktopHostTransport,
+  type DesktopHostTransport
 } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
 import { DesktopPGliteClient } from './desktop-pglite-client.js';
-import { ADAPTER_NAME, DEFAULT_DATA_DIRECTORY_SUFFIX, type ElectronPGliteOptions } from './pglite-adapter.interface.js';
+import { toElectronPGliteBackupError } from './electron-pglite-backup-error.js';
+import { ADAPTER_NAME, resolveDataDirectoryName, type ElectronPGliteOptions } from './pglite-adapter.interface.js';
 
 /**
  * 把 RxDB 接到 Electron 主进程持有的那个唯一 PGlite 实例上。
@@ -50,11 +54,53 @@ export class RxDBAdapterElectronPGlite extends RxDBAdapterPGlite {
     // 传下去只会让 `RxDBAdapterPGlite` 以为自己还管着存储。
     super(rxdb, {});
     this.#options = options;
-    this.#dataDirectoryName = options.dataDirectoryName ?? `${rxdb.config.dbName}${DEFAULT_DATA_DIRECTORY_SUFFIX}`;
+    this.#dataDirectoryName = resolveDataDirectoryName(rxdb.config.dbName, options);
     // 在构造期就校验：名字非法时根本没有能打开的目录，等发出 IPC 才报错只会让原因离现场更远。
     assertValidDesktopDatabaseName(this.#dataDirectoryName);
   }
 
+  /**
+   * 把 host 上的整个数据目录写成一份可恢复的归档（US-217）。
+   *
+   * @remarks
+   * 快照由 host 取：它在本会话那条唯一的连接上挂起一个空事务并 `CHECKPOINT`，写出期间别的窗口、
+   * 别的会话都改不动文件，归档因此对应一个已提交事务边界，快照边界前 WAL 里已提交的数据也都
+   * 已落进数据文件。数据块按 renderer 的读取节奏逐块过 IPC，host 不预读，内存占用与库大小无关。
+   *
+   * 与浏览器端的差异：
+   * - 等连接空闲的上限是构造参数里的 `beginTimeout`，不是 `options.lockTimeoutMs`（后者只管本
+   *   adapter 内部队列的排队）。另一个窗口长期占着事务时报 `lock_timeout`。
+   * - manifest 的元数据（引擎版本、系统表版本）在快照开始之前读取，这两次读取与普通语句一样排在
+   *   别的窗口的事务后面。
+   * - 主进程创建 host 时没有传 `backup` 选项（未接入 US-217）时报 `unsupported_combination`，
+   *   此时不获取输出流的 writer，也不 abort 它。
+   *
+   * 任何失败都归一成 {@link RxDBBackupError}：桌面错误码按
+   * {@link toElectronPGliteBackupError} 的映射表转换，host 不可达等其余失败报 `io_error`，
+   * 原始错误留在 `cause` 上。
+   *
+   * @param sink - 输出流；成功时被 close，快照开始后的失败会 abort 它
+   * @param options - 取消信号与排队时限
+   * @returns 结束标记（条目数、字节数、SHA-256）、manifest 与范围；输出流 close 已完成
+   * @throws RxDBBackupError `unsupported_combination` / `lock_timeout` / `aborted` / `invalid_state` /
+   * `io_error` / `storage_full`
+   *
+   * @example
+   * ```typescript
+   * // sink 由宿主应用提供：沙箱里的 renderer 没有 node:fs，常见做法是 preload 暴露一条
+   * // 只能写进应用备份目录的 WritableStream
+   * const result = await adapter.backup(sink);
+   * console.log(result.sha256);
+   * ```
+   */
+  override async backup(sink: WritableStream<Uint8Array>, options: RxDBBackupOptions = {}): Promise<RxDBBackupResult> {
+    try {
+      return await super.backup(sink, options);
+    } catch (error) {
+      throw toElectronPGliteBackupError(error, this.#dataDirectoryName, 'backup');
+    }
+  }
+
   /**
    * 建出转发到主进程的客户端。
    *
@@ -62,12 +108,41 @@ export class RxDBAdapterElectronPGlite extends RxDBAdapterPGlite {
    */
   protected override createClient(): IPGliteClient {
     return new DesktopPGliteClient({
-      transport: this.#options.transport ?? resolveDesktopHostTransport(),
+      transport: this.#transport(),
       dataDirectoryName: this.#dataDirectoryName,
       ...(this.#options.beginTimeout === undefined ? {} : { beginTimeout: this.#options.beginTimeout }),
       ...(this.#options.batchTimeout === undefined ? {} : { batchTimeout: this.#options.batchTimeout })
     });
   }
+
+  /**
+   * 备份 manifest 记录的存储后端：host 上的一棵数据目录。
+   *
+   * @returns 固定为 `directory`
+   */
+  protected override backupStorage(): string {
+    return 'directory';
+  }
+
+  /**
+   * 备份 manifest 记录的扩展名：host 运行时实际加载的那一组（已去重、排序）。
+   *
+   * @remarks
+   * renderer 侧的 PGlite 选项全部为空，只有 host 知道每个实例装了哪些扩展；恢复时目标 host 必须
+   * 全部提供。host 未启用备份时 `pg.engine` 报 `unsupported_operation`，于是在排队、取 writer 之前
+   * 就拒绝。
+   *
+   * @returns 扩展名
+   */
+  protected override async backupExtensions(): Promise<readonly string[]> {
+    const response = assertDesktopPgliteResponse('pg.engine', await this.#transport().request({ kind: 'pg.engine' }));
+    return parseDesktopPgliteEngineResult(response.result).extensions;
+  }
+
+  /** 构造参数里的传输层，缺省时取 preload 暴露的那条。 */
+  #transport(): DesktopHostTransport {
+    return this.#options.transport ?? resolveDesktopHostTransport();
+  }
 }
 
 declare module '@aiao/rxdb' {

package/src/pglite/desktop-pglite-client.ts

@@ -17,18 +17,22 @@ import {
   PGliteNotificationBatcher,
   type IPGliteClient,
   type PGliteClientEvents,
-  type PGliteClientOptions
+  type PGliteClientOptions,
+  type PGliteDataDirItem
 } from '@aiao/rxdb-adapter-pglite';
 import {
+  DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS,
   RxDBAdapterDesktopError,
   assertDesktopPgliteResponse,
+  parseDesktopPgliteBackupItem,
   parseDesktopPgliteHandshakeResult,
   parseDesktopPgliteNotifyMessage,
   parseDesktopPgliteOpenResult,
   type DesktopHostTransport,
   type DesktopPgliteParam,
-  type DesktopPgliteQueryResult,
-  type DesktopPgliteRequest
+  type DesktopPgliteRequest,
+  type DesktopPgliteResponse,
+  type RxDBAdapterDesktopErrorCode
 } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
 import { EventDispatcher } from '@aiao/utils';
 import type { QueryOptions, Results, Transaction } from '@electric-sql/pglite';
@@ -36,6 +40,8 @@ import type { QueryOptions, Results, Transaction } from '@electric-sql/pglite';
 // `sql` 这些辅助器的语义只有原实现说了算，照抄一份的分叉表征是「同一个模板在桌面下
 // 少转义了一个标识符」。`/template` 是个独立子路径（约 2 KB），不带任何 WASM 进 renderer。
 import { query as compileTemplate } from '@electric-sql/pglite/template';
+import { toDesktopPGliteResults as toResults } from './desktop-pglite-results.js';
+import { toElectronPGliteBackupError } from './electron-pglite-backup-error.js';
 
 /** {@link DesktopPGliteClient} 的构造参数。 */
 export interface DesktopPGliteClientOptions {
@@ -49,18 +55,11 @@ export interface DesktopPGliteClientOptions {
   readonly batchTimeout?: number;
 }
 
-/**
- * 把 host 的应答还原成 PGlite 的 `Results`。
- *
- * @remarks
- * `rows` 里的值已经是 PG 的原生 JS 表示（bigint / `Uint8Array` / `Date` / 普通对象），
- * 结构化克隆逐值搬过来，这里不做任何再解析——多一层转换就多一处能悄悄丢精度的地方。
- */
-const toResults = <T>(result: DesktopPgliteQueryResult): Results<T> => ({
-  rows: result.rows as unknown as T[],
-  fields: result.fields.map(field => ({ name: field.name, dataTypeID: field.dataTypeID })),
-  affectedRows: result.affectedRows
-});
+/** `pg.open` 撞上恢复流程时的拒绝码，见 {@link DesktopPGliteClient.#assertOpened}。 */
+const RESTORE_CONFLICT_CODES: ReadonlySet<RxDBAdapterDesktopErrorCode> = new Set([
+  'restore_in_progress',
+  'restore_incomplete'
+]);
 
 /**
  * 拒绝本代理无法转发的 `QueryOptions`。
@@ -190,6 +189,8 @@ export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> imp
    *
    * @param dbName - RxDB 逻辑库名；只用于变更事件的 `dbName` 字段，不参与落盘位置解析
    * @param options - PGlite 选项；**不得**含 `store` 或 `dataDir`
+   * @throws `RxDBBackupError` 数据目录正在被恢复（`restore_in_progress`）或留着未完成的恢复
+   * （`restore_incomplete`）时，见 {@link DesktopPGliteClient.#assertOpened}
    * @throws {@link RxDBAdapterDesktopError} 指定了落盘位置、协议版本不匹配或 host 打不开数据目录时
    */
   async init(dbName: string, options: PGliteClientOptions): Promise<void> {
@@ -208,8 +209,7 @@ export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> imp
     );
     parseDesktopPgliteHandshakeResult(handshake.result);
 
-    const opened = assertDesktopPgliteResponse(
-      'pg.open',
+    const opened = this.#assertOpened(
       await this.#options.transport.request({
         kind: 'pg.open',
         storage: { engine: 'pglite', dataDirectoryName: this.#options.dataDirectoryName }
@@ -296,6 +296,61 @@ export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> imp
     );
   }
 
+  /**
+   * 在 host 的一致快照上逐项读取数据目录（US-217）。
+   *
+   * @remarks
+   * host 在本会话那条唯一连接上开事务并 `CHECKPOINT`，`fn` 返回之前一直占着它：没有写入能落进
+   * 正在读的文件，快照边界前已提交的 WAL 也都已落进数据文件（AC#16）。
+   *
+   * - **独占**：整段排在本地互斥里，同一客户端的其他语句等快照结束再发。否则它们在 host 上
+   *   排在快照后面，而快照又在等 renderer 来取下一块——两边互等。
+   * - **背压**：`items` 每被取一项才发一次 `pg.backup.next`，同一时刻至多一个在途请求，
+   *   renderer 不取，host 就不读下一块（AC#21）。
+   * - **收尾**：无论 `fn` 读完、提前返回还是抛出，都发 `pg.backup.end` 交还连接（AC#19）。
+   *   `fn` 失败时收尾失败不覆盖原始错误；`fn` 成功而收尾失败则整体失败——快照没结束的
+   *   备份不能报成功。
+   *
+   * 等连接空闲的上限沿用构造参数里的 `beginTimeout`（与 `pg.begin` 同档）：契约方法不带
+   * 备份选项，`lockTimeoutMs` 传不到这里；到期由 host 以 `transaction_unavailable` 拒绝。
+   *
+   * @param fn - 消费快照的回调；`items` 只在回调返回之前有效
+   * @returns 回调的返回值
+   * @throws {@link RxDBAdapterDesktopError} 会话已关闭、host 不带备份能力（`unsupported_operation`）、
+   * 等不到连接或收尾失败时；`fn` 抛出的错误原样重抛
+   */
+  async snapshotDataDir<T>(fn: (items: AsyncIterable<PGliteDataDirItem>) => Promise<T>): Promise<T> {
+    this.#assertOpen();
+    return this.#exclusive(async () => {
+      const begun = assertDesktopPgliteResponse(
+        'pg.backup.begin',
+        await this.#send({
+          kind: 'pg.backup.begin',
+          sessionId: this.sessionId,
+          timeout: this.#options.beginTimeout ?? DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS
+        })
+      );
+      const backupId = begun.result.backupId;
+      const end = async (): Promise<void> => {
+        assertDesktopPgliteResponse(
+          'pg.backup.end',
+          await this.#send({ kind: 'pg.backup.end', sessionId: this.sessionId, backupId })
+        );
+      };
+
+      let result: T;
+      try {
+        result = await fn(this.#backupItems(backupId));
+      } catch (error) {
+        // 收尾失败不覆盖原始错误：调用方要看的是消费方那条，而不是收摊那条。
+        await end().catch(() => undefined);
+        throw error;
+      }
+      await end();
+      return result;
+    });
+  }
+
   /**
    * 断开会话。
    *
@@ -320,6 +375,26 @@ export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> imp
     await this.#closePromise;
   }
 
+  /**
+   * 校验 `pg.open` 应答；目标此刻归恢复流程所有时，改报备份契约里的码。
+   *
+   * @remarks
+   * `restore_in_progress` / `restore_incomplete` 说的不是「连接坏了」，而是「这个目录正被恢复
+   * 或留着一次没做完的恢复」（AC#11、#12）：调用方要么等，要么调
+   * `cleanupIncompleteElectronPGliteRestore()` 收拾，只有按备份契约写的判断接得住。
+   * 其余打不开的原因与恢复无关，仍是桌面错误。
+   */
+  #assertOpened(response: unknown): Extract<DesktopPgliteResponse, { kind: 'pg.open' }> {
+    try {
+      return assertDesktopPgliteResponse('pg.open', response);
+    } catch (error) {
+      if (error instanceof RxDBAdapterDesktopError && RESTORE_CONFLICT_CODES.has(error.code)) {
+        throw toElectronPGliteBackupError(error, this.#options.dataDirectoryName, 'restore');
+      }
+      throw error;
+    }
+  }
+
   /**
    * 解析 `pg.open` 结果；解析不过就先把 host 上刚开出来的会话关掉，再抛原始错误。
    *
@@ -451,6 +526,25 @@ export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> imp
     return toResults<T>(assertDesktopPgliteResponse('pg.query', await this.#send(request)).result);
   }
 
+  /**
+   * 快照的逐项迭代器。
+   *
+   * @remarks
+   * 异步生成器自带排队：消费方连调两次 `next()`，第二次也要等第一次的 `pg.backup.next`
+   * 回来才发，背压因此不依赖消费方守规矩。
+   */
+  async *#backupItems(backupId: string): AsyncGenerator<PGliteDataDirItem> {
+    for (;;) {
+      const next = assertDesktopPgliteResponse(
+        'pg.backup.next',
+        await this.#send({ kind: 'pg.backup.next', sessionId: this.sessionId, backupId })
+      );
+      const item = parseDesktopPgliteBackupItem(next.result);
+      if (item.type === 'end') return;
+      yield item;
+    }
+  }
+
   async #execOn(transactionId: string | undefined, sql: string): Promise<Results[]> {
     const request: DesktopPgliteRequest = {
       kind: 'pg.exec',

package/src/pglite/desktop-pglite-results.ts

@@ -0,0 +1,24 @@
+/**
+ * host 查询应答到 PGlite `Results` 的还原，普通会话与恢复校验共用。
+ *
+ * @module pglite/desktop-pglite-results
+ */
+
+import type { DesktopPgliteQueryResult } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import type { Results } from '@electric-sql/pglite';
+
+/**
+ * 把 host 的应答还原成 PGlite 的 `Results`。
+ *
+ * @remarks
+ * `rows` 里的值已经是 PG 的原生 JS 表示（bigint / `Uint8Array` / `Date` / 普通对象），
+ * 结构化克隆逐值搬过来，这里不做任何再解析——多一层转换就多一处能悄悄丢精度的地方。
+ *
+ * @param result - 已通过协议校验的查询结果
+ * @returns 与浏览器路径同形状的结果
+ */
+export const toDesktopPGliteResults = <T>(result: DesktopPgliteQueryResult): Results<T> => ({
+  rows: result.rows as unknown as T[],
+  fields: result.fields.map(field => ({ name: field.name, dataTypeID: field.dataTypeID })),
+  affectedRows: result.affectedRows
+});

package/src/pglite/electron-pglite-backup-error.ts

@@ -0,0 +1,128 @@
+/**
+ * 桌面 PGlite 备份 / 恢复的错误归一（US-217）。
+ *
+ * @module pglite/electron-pglite-backup-error
+ */
+
+import { RxDBBackupError, type RxDBBackupErrorCode, type RxDBBackupErrorDetails } from '@aiao/rxdb';
+import {
+  DESKTOP_PGLITE_PROTOCOL_VERSION,
+  RxDBAdapterDesktopError,
+  type RxDBAdapterDesktopErrorCode
+} from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+
+/** 备份读源库，恢复写目标库；同一个桌面错误码在两个方向上的归因不同。 */
+export type ElectronPGliteBackupDirection = 'backup' | 'restore';
+
+/** 这些码说的都是「数据目录此刻的状态」，`details` 指向目录名，调用方据此决定清理、等待还是换目标。 */
+const TARGET_STATE_CODES = new Map<RxDBAdapterDesktopErrorCode, RxDBBackupErrorCode>([
+  ['database_busy', 'target_busy'],
+  ['restore_in_progress', 'restore_in_progress'],
+  ['restore_incomplete', 'restore_incomplete'],
+  ['target_not_empty', 'target_not_empty'],
+  ['cleanup_pending', 'cleanup_pending']
+]);
+
+/** 这一侧的 host 或运行环境根本做不了这件事：重试无用，换组合才行。 */
+const UNSUPPORTED_CODES: ReadonlySet<RxDBAdapterDesktopErrorCode> = new Set([
+  'unsupported_runtime_engine',
+  'invalid_database_name',
+  'unsupported_operation'
+]);
+
+const targetStateMessage = (code: RxDBBackupErrorCode, name: string): string => {
+  switch (code) {
+    case 'target_busy':
+      return `Desktop PGlite data directory "${name}" is open in another connection or being restored`;
+    case 'restore_in_progress':
+      return `Desktop PGlite data directory "${name}" is being restored`;
+    case 'restore_incomplete':
+      return `A previous restore into "${name}" did not finish; call cleanupIncompleteElectronPGliteRestore()`;
+    case 'target_not_empty':
+      return `Desktop PGlite data directory "${name}" already holds a database`;
+    default:
+      return `Failed to clean up the incomplete restore of "${name}"; call cleanupIncompleteElectronPGliteRestore()`;
+  }
+};
+
+const generalCode = (
+  code: RxDBAdapterDesktopErrorCode,
+  direction: ElectronPGliteBackupDirection
+): RxDBBackupErrorCode => {
+  if (UNSUPPORTED_CODES.has(code)) return 'unsupported_combination';
+  switch (code) {
+    case 'disk_full':
+      return 'storage_full';
+    case 'transaction_unavailable':
+      return 'lock_timeout';
+    case 'session_closed':
+      return 'invalid_state';
+    case 'database_corrupted':
+      // 恢复时坏的是归档写出来的目录；备份时坏的是源库，归档还没写出来，不能让人去怀疑它。
+      return direction === 'restore' ? 'corrupt_archive' : 'io_error';
+    default:
+      return 'io_error';
+  }
+};
+
+const fromDesktopError = (
+  error: RxDBAdapterDesktopError,
+  name: string,
+  direction: ElectronPGliteBackupDirection
+): RxDBBackupError => {
+  const targetState = TARGET_STATE_CODES.get(error.code);
+  if (targetState !== undefined) {
+    const details: RxDBBackupErrorDetails = { field: 'dataDirectoryName', actual: name };
+    return new RxDBBackupError(targetState, targetStateMessage(targetState, name), { details, cause: error });
+  }
+  if (error.code === 'protocol_violation') {
+    return new RxDBBackupError('unsupported_combination', `The desktop host does not speak this renderer's protocol`, {
+      details: { field: 'protocolVersion', expected: DESKTOP_PGLITE_PROTOCOL_VERSION },
+      cause: error
+    });
+  }
+  return new RxDBBackupError(
+    generalCode(error.code, direction),
+    `Desktop PGlite ${direction} failed: ${error.detail}`,
+    {
+      cause: error
+    }
+  );
+};
+
+/**
+ * 把桌面 PGlite 备份 / 恢复途中的任意失败归一成 {@link RxDBBackupError}。
+ *
+ * @remarks
+ * 备份与恢复的公共契约只认 `RxDBBackupError.code`；桌面错误码属于 host 线协议，漏到调用方手里，
+ * 按契约写的 `switch (error.code)` 就会静默落进 default。已经是 `RxDBBackupError` 的原样返回；
+ * 其余一律带着原始错误作为 `cause`：
+ *
+ * | 桌面错误码 | 备份契约 |
+ * | --- | --- |
+ * | `database_busy` | `target_busy` |
+ * | `restore_in_progress` / `restore_incomplete` / `target_not_empty` / `cleanup_pending` | 同名码 |
+ * | `protocol_violation` | `unsupported_combination`（`details.field` 为 `protocolVersion`） |
+ * | `unsupported_operation` / `unsupported_runtime_engine` / `invalid_database_name` | `unsupported_combination` |
+ * | `disk_full` | `storage_full` |
+ * | `transaction_unavailable` | `lock_timeout` |
+ * | `session_closed` | `invalid_state` |
+ * | `database_corrupted` | 恢复为 `corrupt_archive`，备份为 `io_error` |
+ * | 其余桌面错误及非桌面错误 | `io_error` |
+ *
+ * 目标状态类的码（前两行）`details` 为 `{ field: 'dataDirectoryName', actual: 目录名 }`。
+ *
+ * @param error - 捕获到的任意值
+ * @param dataDirectoryName - 本次操作的数据目录名
+ * @param direction - 发生在备份还是恢复
+ * @returns 归一后的备份错误
+ */
+export const toElectronPGliteBackupError = (
+  error: unknown,
+  dataDirectoryName: string,
+  direction: ElectronPGliteBackupDirection
+): RxDBBackupError => {
+  if (error instanceof RxDBBackupError) return error;
+  if (error instanceof RxDBAdapterDesktopError) return fromDesktopError(error, dataDirectoryName, direction);
+  return new RxDBBackupError('io_error', `Desktop PGlite ${direction} failed`, { cause: error });
+};

package/src/pglite/pglite-adapter.interface.ts

@@ -62,3 +62,17 @@ export interface ElectronPGliteOptions {
    */
   readonly batchTimeout?: number;
 }
+
+/**
+ * 解析实例对应的逻辑数据目录名。
+ *
+ * @remarks
+ * 适配器连接与恢复入口必须算出同一个名字：恢复写进的目录就是之后 `connect` 打开的目录，两处各写一遍
+ * 默认规则迟早会分叉。
+ *
+ * @param dbName - `rxdb.config.dbName`
+ * @param options - 适配器选项；只读取 `dataDirectoryName`
+ * @returns 显式给出的名字，否则为 `<dbName>-pgdata`；不做校验
+ */
+export const resolveDataDirectoryName = (dbName: string, options: ElectronPGliteOptions): string =>
+  options.dataDirectoryName ?? `${dbName}${DEFAULT_DATA_DIRECTORY_SUFFIX}`;