feat: add helper process (#2753)

apps/electron/src/helper/db/__tests__/.gitignore

@@ -0,0 +1 @@
+tmp

apps/electron/src/helper/db/__tests__/ensure-db.spec.ts

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+
+import fs from 'fs-extra';
+import { v4 } from 'uuid';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+const tmpDir = path.join(__dirname, 'tmp');
+const appDataPath = path.join(tmpDir, 'app-data');
+
+vi.doMock('../../main-rpc', () => ({
+  mainRPC: {
+    getPath: async () => appDataPath,
+  },
+}));
+
+const constructorStub = vi.fn();
+const destroyStub = vi.fn();
+destroyStub.mockReturnValue(Promise.resolve());
+
+function existProcess() {
+  process.emit('beforeExit', 0);
+}
+
+vi.doMock('../secondary-db', () => {
+  return {
+    SecondaryWorkspaceSQLiteDB: class {
+      constructor(...args: any[]) {
+        constructorStub(...args);
+      }
+
+      connectIfNeeded = () => Promise.resolve();
+
+      pull = () => Promise.resolve();
+
+      destroy = destroyStub;
+    },
+  };
+});
+
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true });
+});
+
+afterEach(async () => {
+  existProcess();
+  // wait for the db to be closed on Windows
+  if (process.platform === 'win32') {
+    await setTimeout(200);
+  }
+  await fs.remove(tmpDir);
+  vi.useRealTimers();
+});
+
+test('can get a valid WorkspaceSQLiteDB', async () => {
+  const { ensureSQLiteDB } = await import('../ensure-db');
+  const workspaceId = v4();
+  const db0 = await ensureSQLiteDB(workspaceId);
+  expect(db0).toBeDefined();
+  expect(db0.workspaceId).toBe(workspaceId);
+
+  const db1 = await ensureSQLiteDB(v4());
+  expect(db1).not.toBe(db0);
+  expect(db1.workspaceId).not.toBe(db0.workspaceId);
+
+  // ensure that the db is cached
+  expect(await ensureSQLiteDB(workspaceId)).toBe(db0);
+});
+
+test('db should be destroyed when app quits', async () => {
+  const { ensureSQLiteDB } = await import('../ensure-db');
+  const workspaceId = v4();
+  const db0 = await ensureSQLiteDB(workspaceId);
+  const db1 = await ensureSQLiteDB(v4());
+
+  expect(db0.db).not.toBeNull();
+  expect(db1.db).not.toBeNull();
+
+  existProcess();
+
+  // wait the async `db.destroy()` to be called
+  await setTimeout(100);
+
+  expect(db0.db).toBeNull();
+  expect(db1.db).toBeNull();
+});
+
+test('db should be removed in db$Map after destroyed', async () => {
+  const { ensureSQLiteDB, db$Map } = await import('../ensure-db');
+  const workspaceId = v4();
+  const db = await ensureSQLiteDB(workspaceId);
+  await db.destroy();
+  await setTimeout(100);
+  expect(db$Map.has(workspaceId)).toBe(false);
+});
+
+test('if db has a secondary db path, we should also poll that', async () => {
+  const { ensureSQLiteDB } = await import('../ensure-db');
+  const { storeWorkspaceMeta } = await import('../../workspace');
+  const workspaceId = v4();
+  await storeWorkspaceMeta(workspaceId, {
+    secondaryDBPath: path.join(tmpDir, 'secondary.db'),
+  });
+
+  const db = await ensureSQLiteDB(workspaceId);
+
+  await setTimeout(10);
+
+  expect(constructorStub).toBeCalledTimes(1);
+  expect(constructorStub).toBeCalledWith(path.join(tmpDir, 'secondary.db'), db);
+
+  // if secondary meta is changed
+  await storeWorkspaceMeta(workspaceId, {
+    secondaryDBPath: path.join(tmpDir, 'secondary2.db'),
+  });
+
+  // wait the async `db.destroy()` to be called
+  await setTimeout(100);
+  expect(constructorStub).toBeCalledTimes(2);
+  expect(destroyStub).toBeCalledTimes(1);
+
+  // if secondary meta is changed (but another workspace)
+  await storeWorkspaceMeta(v4(), {
+    secondaryDBPath: path.join(tmpDir, 'secondary3.db'),
+  });
+  await vi.advanceTimersByTimeAsync(1500);
+  expect(constructorStub).toBeCalledTimes(2);
+  expect(destroyStub).toBeCalledTimes(1);
+
+  // if primary is destroyed, secondary should also be destroyed
+  await db.destroy();
+  await setTimeout(100);
+  expect(destroyStub).toBeCalledTimes(2);
+});

apps/electron/src/helper/db/__tests__/workspace-db-adapter.spec.ts

@@ -0,0 +1,99 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+import { v4 } from 'uuid';
+import { afterEach, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+
+import { dbSubjects } from '../subjects';
+
+const tmpDir = path.join(__dirname, 'tmp');
+const appDataPath = path.join(tmpDir, 'app-data');
+
+vi.doMock('../../main-rpc', () => ({
+  mainRPC: {
+    getPath: async () => appDataPath,
+  },
+}));
+
+afterEach(async () => {
+  await fs.remove(tmpDir);
+});
+
+function getTestUpdates() {
+  const testYDoc = new Y.Doc();
+  const yText = testYDoc.getText('test');
+  yText.insert(0, 'hello');
+  const updates = Y.encodeStateAsUpdate(testYDoc);
+
+  return updates;
+}
+test('can create new db file if not exists', async () => {
+  const { openWorkspaceDatabase } = await import('../workspace-db-adapter');
+  const workspaceId = v4();
+  const db = await openWorkspaceDatabase(workspaceId);
+  const dbPath = path.join(
+    appDataPath,
+    `workspaces/${workspaceId}`,
+    `storage.db`
+  );
+  expect(await fs.exists(dbPath)).toBe(true);
+  await db.destroy();
+});
+
+test('on applyUpdate (from self), will not trigger update', async () => {
+  const { openWorkspaceDatabase } = await import('../workspace-db-adapter');
+  const workspaceId = v4();
+  const onUpdate = vi.fn();
+
+  const db = await openWorkspaceDatabase(workspaceId);
+  db.update$.subscribe(onUpdate);
+  db.applyUpdate(getTestUpdates(), 'self');
+  expect(onUpdate).not.toHaveBeenCalled();
+  await db.destroy();
+});
+
+test('on applyUpdate (from renderer), will trigger update', async () => {
+  const { openWorkspaceDatabase } = await import('../workspace-db-adapter');
+  const workspaceId = v4();
+  const onUpdate = vi.fn();
+  const onExternalUpdate = vi.fn();
+
+  const db = await openWorkspaceDatabase(workspaceId);
+  db.update$.subscribe(onUpdate);
+  const sub = dbSubjects.externalUpdate.subscribe(onExternalUpdate);
+  db.applyUpdate(getTestUpdates(), 'renderer');
+  expect(onUpdate).toHaveBeenCalled();
+  sub.unsubscribe();
+  await db.destroy();
+});
+
+test('on applyUpdate (from external), will trigger update & send external update event', async () => {
+  const { openWorkspaceDatabase } = await import('../workspace-db-adapter');
+  const workspaceId = v4();
+  const onUpdate = vi.fn();
+  const onExternalUpdate = vi.fn();
+
+  const db = await openWorkspaceDatabase(workspaceId);
+  db.update$.subscribe(onUpdate);
+  const sub = dbSubjects.externalUpdate.subscribe(onExternalUpdate);
+  db.applyUpdate(getTestUpdates(), 'external');
+  expect(onUpdate).toHaveBeenCalled();
+  expect(onExternalUpdate).toHaveBeenCalled();
+  sub.unsubscribe();
+  await db.destroy();
+});
+
+test('on destroy, check if resources have been released', async () => {
+  const { openWorkspaceDatabase } = await import('../workspace-db-adapter');
+  const workspaceId = v4();
+  const db = await openWorkspaceDatabase(workspaceId);
+  const updateSub = {
+    complete: vi.fn(),
+    next: vi.fn(),
+  };
+  db.update$ = updateSub as any;
+  await db.destroy();
+  expect(db.db).toBe(null);
+  expect(updateSub.complete).toHaveBeenCalled();
+});

apps/electron/src/helper/db/base-db-adapter.ts

@@ -0,0 +1,116 @@
+import { SqliteConnection } from '@affine/native';
+
+import { logger } from '../logger';
+
+/**
+ * A base class for SQLite DB adapter that provides basic methods around updates & blobs
+ */
+export abstract class BaseSQLiteAdapter {
+  db: SqliteConnection | null = null;
+  abstract role: string;
+
+  constructor(public readonly path: string) {}
+
+  async connectIfNeeded() {
+    if (!this.db) {
+      this.db = new SqliteConnection(this.path);
+      await this.db.connect();
+      logger.info(`[SQLiteAdapter:${this.role}]`, 'connected:', this.path);
+    }
+    return this.db;
+  }
+
+  async destroy() {
+    const { db } = this;
+    this.db = null;
+    // log after close will sometimes crash the app when quitting
+    logger.info(`[SQLiteAdapter:${this.role}]`, 'destroyed:', this.path);
+    await db?.close();
+  }
+
+  async addBlob(key: string, data: Uint8Array) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.addBlob(key, data);
+    } catch (error) {
+      logger.error('addBlob', error);
+    }
+  }
+
+  async getBlob(key: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      const blob = await this.db.getBlob(key);
+      return blob?.data;
+    } catch (error) {
+      logger.error('getBlob', error);
+      return null;
+    }
+  }
+
+  async deleteBlob(key: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.deleteBlob(key);
+    } catch (error) {
+      logger.error(`${this.path} delete blob failed`, error);
+    }
+  }
+
+  async getBlobKeys() {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getBlobKeys();
+    } catch (error) {
+      logger.error(`getBlobKeys failed`, error);
+      return [];
+    }
+  }
+
+  async getUpdates() {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getUpdates();
+    } catch (error) {
+      logger.error('getUpdates', error);
+      return [];
+    }
+  }
+
+  // add a single update to SQLite
+  async addUpdateToSQLite(updates: Uint8Array[]) {
+    // batch write instead write per key stroke?
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      const start = performance.now();
+      await this.db.insertUpdates(updates);
+      logger.debug(
+        `[SQLiteAdapter][${this.role}] addUpdateToSQLite`,
+        'length:',
+        updates.length,
+        performance.now() - start,
+        'ms'
+      );
+    } catch (error) {
+      logger.error('addUpdateToSQLite', this.path, error);
+    }
+  }
+}

apps/electron/src/helper/db/ensure-db.ts

@@ -0,0 +1,140 @@
+import type { Subject } from 'rxjs';
+import { Observable } from 'rxjs';
+import {
+  concat,
+  defer,
+  from,
+  fromEvent,
+  interval,
+  lastValueFrom,
+  merge,
+} from 'rxjs';
+import {
+  concatMap,
+  distinctUntilChanged,
+  filter,
+  ignoreElements,
+  last,
+  map,
+  shareReplay,
+  startWith,
+  switchMap,
+  take,
+  takeUntil,
+  tap,
+} from 'rxjs/operators';
+
+import { logger } from '../logger';
+import { getWorkspaceMeta, workspaceSubjects } from '../workspace';
+import { SecondaryWorkspaceSQLiteDB } from './secondary-db';
+import type { WorkspaceSQLiteDB } from './workspace-db-adapter';
+import { openWorkspaceDatabase } from './workspace-db-adapter';
+
+// export for testing
+export const db$Map = new Map<string, Observable<WorkspaceSQLiteDB>>();
+
+// use defer to prevent `app` is undefined while running tests
+const beforeQuit$ = defer(() => fromEvent(process, 'beforeExit'));
+
+// return a stream that emit a single event when the subject completes
+function completed<T>(subject: Subject<T>) {
+  return new Observable(subscriber => {
+    const sub = subject.subscribe({
+      complete: () => {
+        subscriber.next();
+        subscriber.complete();
+      },
+    });
+    return () => sub.unsubscribe();
+  });
+}
+
+function getWorkspaceDB$(id: string) {
+  if (!db$Map.has(id)) {
+    db$Map.set(
+      id,
+      from(openWorkspaceDatabase(id)).pipe(
+        tap({
+          next: db => {
+            logger.info(
+              '[ensureSQLiteDB] db connection established',
+              db.workspaceId
+            );
+          },
+        }),
+        switchMap(db =>
+          // takeUntil the polling stream, and then destroy the db
+          concat(
+            startPollingSecondaryDB(db).pipe(
+              ignoreElements(),
+              startWith(db),
+              takeUntil(merge(beforeQuit$, completed(db.update$))),
+              last(),
+              tap({
+                next() {
+                  logger.info(
+                    '[ensureSQLiteDB] polling secondary db complete',
+                    db.workspaceId
+                  );
+                },
+              })
+            ),
+            defer(async () => {
+              try {
+                await db.destroy();
+                db$Map.delete(id);
+                return db;
+              } catch (err) {
+                logger.error('[ensureSQLiteDB] destroy db failed', err);
+                throw err;
+              }
+            })
+          ).pipe(startWith(db))
+        ),
+        shareReplay(1)
+      )
+    );
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return db$Map.get(id)!;
+}
+
+function startPollingSecondaryDB(db: WorkspaceSQLiteDB) {
+  return merge(
+    getWorkspaceMeta(db.workspaceId),
+    workspaceSubjects.meta.pipe(
+      map(({ meta }) => meta),
+      filter(meta => meta.id === db.workspaceId)
+    )
+  ).pipe(
+    map(meta => meta?.secondaryDBPath),
+    filter((p): p is string => !!p),
+    distinctUntilChanged(),
+    switchMap(path => {
+      // on secondary db path change, destroy the old db and create a new one
+      const secondaryDB = new SecondaryWorkspaceSQLiteDB(path, db);
+      return new Observable<SecondaryWorkspaceSQLiteDB>(subscriber => {
+        subscriber.next(secondaryDB);
+        return () => secondaryDB.destroy();
+      });
+    }),
+    switchMap(secondaryDB => {
+      return interval(300000).pipe(
+        startWith(0),
+        concatMap(() => secondaryDB.pull()),
+        tap({
+          error: err => {
+            logger.error(`[ensureSQLiteDB] polling secondary db error`, err);
+          },
+          complete: () => {
+            logger.info('[ensureSQLiteDB] polling secondary db complete');
+          },
+        })
+      );
+    })
+  );
+}
+
+export function ensureSQLiteDB(id: string) {
+  return lastValueFrom(getWorkspaceDB$(id).pipe(take(1)));
+}

apps/electron/src/helper/db/index.ts

@@ -0,0 +1,48 @@
+import { mainRPC } from '../main-rpc';
+import type { MainEventRegister } from '../type';
+import { ensureSQLiteDB } from './ensure-db';
+import { dbSubjects } from './subjects';
+
+export * from './ensure-db';
+export * from './subjects';
+
+export const dbHandlers = {
+  getDocAsUpdates: async (id: string) => {
+    const workspaceDB = await ensureSQLiteDB(id);
+    return workspaceDB.getDocAsUpdates();
+  },
+  applyDocUpdate: async (id: string, update: Uint8Array) => {
+    const workspaceDB = await ensureSQLiteDB(id);
+    return workspaceDB.applyUpdate(update);
+  },
+  addBlob: async (workspaceId: string, key: string, data: Uint8Array) => {
+    const workspaceDB = await ensureSQLiteDB(workspaceId);
+    return workspaceDB.addBlob(key, data);
+  },
+  getBlob: async (workspaceId: string, key: string) => {
+    const workspaceDB = await ensureSQLiteDB(workspaceId);
+    return workspaceDB.getBlob(key);
+  },
+  deleteBlob: async (workspaceId: string, key: string) => {
+    const workspaceDB = await ensureSQLiteDB(workspaceId);
+    return workspaceDB.deleteBlob(key);
+  },
+  getBlobKeys: async (workspaceId: string) => {
+    const workspaceDB = await ensureSQLiteDB(workspaceId);
+    return workspaceDB.getBlobKeys();
+  },
+  getDefaultStorageLocation: async () => {
+    return await mainRPC.getPath('sessionData');
+  },
+};
+
+export const dbEvents = {
+  onExternalUpdate: (
+    fn: (update: { workspaceId: string; update: Uint8Array }) => void
+  ) => {
+    const sub = dbSubjects.externalUpdate.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+} satisfies Record<string, MainEventRegister>;

apps/electron/src/helper/db/merge-update.ts

@@ -0,0 +1,11 @@
+import * as Y from 'yjs';
+
+export function mergeUpdate(updates: Uint8Array[]) {
+  const yDoc = new Y.Doc();
+  Y.transact(yDoc, () => {
+    for (const update of updates) {
+      Y.applyUpdate(yDoc, update);
+    }
+  });
+  return Y.encodeStateAsUpdate(yDoc);
+}

apps/electron/src/helper/db/secondary-db.ts

@@ -0,0 +1,215 @@
+import assert from 'node:assert';
+
+import type { SqliteConnection } from '@affine/native';
+import { debounce } from 'lodash-es';
+import * as Y from 'yjs';
+
+import { logger } from '../logger';
+import type { YOrigin } from '../type';
+import { getWorkspaceMeta } from '../workspace';
+import { BaseSQLiteAdapter } from './base-db-adapter';
+import { mergeUpdate } from './merge-update';
+import type { WorkspaceSQLiteDB } from './workspace-db-adapter';
+
+const FLUSH_WAIT_TIME = 5000;
+const FLUSH_MAX_WAIT_TIME = 10000;
+
+export class SecondaryWorkspaceSQLiteDB extends BaseSQLiteAdapter {
+  role = 'secondary';
+  yDoc = new Y.Doc();
+  firstConnected = false;
+  destroyed = false;
+
+  updateQueue: Uint8Array[] = [];
+
+  unsubscribers = new Set<() => void>();
+
+  constructor(
+    public override path: string,
+    public upstream: WorkspaceSQLiteDB
+  ) {
+    super(path);
+    this.setupAndListen();
+    logger.debug('[SecondaryWorkspaceSQLiteDB] created', this.workspaceId);
+  }
+
+  override async destroy() {
+    await this.flushUpdateQueue();
+    this.unsubscribers.forEach(unsub => unsub());
+    this.yDoc.destroy();
+    await super.destroy();
+    this.destroyed = true;
+  }
+
+  get workspaceId() {
+    return this.upstream.workspaceId;
+  }
+
+  // do not update db immediately, instead, push to a queue
+  // and flush the queue in a future time
+  async addUpdateToUpdateQueue(db: SqliteConnection, update: Uint8Array) {
+    this.updateQueue.push(update);
+    await this.debouncedFlush();
+  }
+
+  async flushUpdateQueue() {
+    if (this.destroyed) {
+      return;
+    }
+    logger.debug(
+      'flushUpdateQueue',
+      this.workspaceId,
+      'queue',
+      this.updateQueue.length
+    );
+    const updates = [...this.updateQueue];
+    this.updateQueue = [];
+    await this.run(async () => {
+      await this.addUpdateToSQLite(updates);
+    });
+  }
+
+  // flush after 5s, but will not wait for more than 10s
+  debouncedFlush = debounce(this.flushUpdateQueue, FLUSH_WAIT_TIME, {
+    maxWait: FLUSH_MAX_WAIT_TIME,
+  });
+
+  runCounter = 0;
+
+  // wrap the fn with connect and close
+  async run<T extends (...args: any[]) => any>(
+    fn: T
+  ): Promise<
+    (T extends (...args: any[]) => infer U ? Awaited<U> : unknown) | undefined
+  > {
+    try {
+      if (this.destroyed) {
+        return;
+      }
+      await this.connectIfNeeded();
+      this.runCounter++;
+      return await fn();
+    } catch (err) {
+      logger.error(err);
+      throw err;
+    } finally {
+      this.runCounter--;
+      if (this.runCounter === 0) {
+        // just close db, but not the yDoc
+        await super.destroy();
+      }
+    }
+  }
+
+  setupAndListen() {
+    if (this.firstConnected) {
+      return;
+    }
+    this.firstConnected = true;
+
+    const onUpstreamUpdate = (update: Uint8Array, origin: YOrigin) => {
+      if (origin === 'renderer') {
+        // update to upstream yDoc should be replicated to self yDoc
+        this.applyUpdate(update, 'upstream');
+      }
+    };
+
+    const onSelfUpdate = async (update: Uint8Array, origin: YOrigin) => {
+      // for self update from upstream, we need to push it to external DB
+      if (origin === 'upstream' && this.db) {
+        await this.addUpdateToUpdateQueue(this.db, update);
+      }
+
+      if (origin === 'self') {
+        this.upstream.applyUpdate(update, 'external');
+      }
+    };
+
+    // listen to upstream update
+    this.upstream.yDoc.on('update', onUpstreamUpdate);
+    this.yDoc.on('update', onSelfUpdate);
+
+    this.unsubscribers.add(() => {
+      this.upstream.yDoc.off('update', onUpstreamUpdate);
+      this.yDoc.off('update', onSelfUpdate);
+    });
+
+    this.run(() => {
+      // apply all updates from upstream
+      const upstreamUpdate = this.upstream.getDocAsUpdates();
+      // to initialize the yDoc, we need to apply all updates from the db
+      this.applyUpdate(upstreamUpdate, 'upstream');
+    })
+      .then(() => {
+        logger.debug('run success');
+      })
+      .catch(err => {
+        logger.error('run error', err);
+      });
+  }
+
+  applyUpdate = (data: Uint8Array, origin: YOrigin = 'upstream') => {
+    Y.applyUpdate(this.yDoc, data, origin);
+  };
+
+  // TODO: have a better solution to handle blobs
+  async syncBlobs() {
+    await this.run(async () => {
+      // skip if upstream db is not connected (maybe it is already closed)
+      const blobsKeys = await this.getBlobKeys();
+      if (!this.upstream.db || this.upstream.db?.isClose) {
+        return;
+      }
+      const upstreamBlobsKeys = await this.upstream.getBlobKeys();
+      // put every missing blob to upstream
+      for (const key of blobsKeys) {
+        if (!upstreamBlobsKeys.includes(key)) {
+          const blob = await this.getBlob(key);
+          if (blob) {
+            await this.upstream.addBlob(key, blob);
+            logger.debug('syncBlobs', this.workspaceId, key);
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * pull from external DB file and apply to embedded yDoc
+   * workflow:
+   * - connect to external db
+   * - get updates
+   * - apply updates to local yDoc
+   * - get blobs and put new blobs to upstream
+   * - disconnect
+   */
+  async pull() {
+    const start = performance.now();
+    assert(this.upstream.db, 'upstream db should be connected');
+    const updates = await this.run(async () => {
+      // TODO: no need to get all updates, just get the latest ones (using a cursor, etc)?
+      await this.syncBlobs();
+      return (await this.getUpdates()).map(update => update.data);
+    });
+
+    if (!updates || this.destroyed) {
+      return;
+    }
+
+    const merged = mergeUpdate(updates);
+    this.applyUpdate(merged, 'self');
+
+    logger.debug(
+      'pull external updates',
+      this.path,
+      updates.length,
+      (performance.now() - start).toFixed(2),
+      'ms'
+    );
+  }
+}
+
+export async function getSecondaryWorkspaceDBPath(workspaceId: string) {
+  const meta = await getWorkspaceMeta(workspaceId);
+  return meta?.secondaryDBPath;
+}

apps/electron/src/helper/db/subjects.ts

@@ -0,0 +1,5 @@
+import { Subject } from 'rxjs';
+
+export const dbSubjects = {
+  externalUpdate: new Subject<{ workspaceId: string; update: Uint8Array }>(),
+};

apps/electron/src/helper/db/workspace-db-adapter.ts

@@ -0,0 +1,102 @@
+import { Subject } from 'rxjs';
+import * as Y from 'yjs';
+
+import { logger } from '../logger';
+import type { YOrigin } from '../type';
+import { getWorkspaceMeta } from '../workspace';
+import { BaseSQLiteAdapter } from './base-db-adapter';
+import { mergeUpdate } from './merge-update';
+import { dbSubjects } from './subjects';
+
+export class WorkspaceSQLiteDB extends BaseSQLiteAdapter {
+  role = 'primary';
+  yDoc = new Y.Doc();
+  firstConnected = false;
+
+  update$ = new Subject<void>();
+
+  constructor(public override path: string, public workspaceId: string) {
+    super(path);
+  }
+
+  override async destroy() {
+    await super.destroy();
+    this.yDoc.destroy();
+
+    // when db is closed, we can safely remove it from ensure-db list
+    this.update$.complete();
+    this.firstConnected = false;
+  }
+
+  getWorkspaceName = () => {
+    return this.yDoc.getMap('space:meta').get('name') as string;
+  };
+
+  async init() {
+    const db = await super.connectIfNeeded();
+
+    if (!this.firstConnected) {
+      this.yDoc.on('update', async (update: Uint8Array, origin: YOrigin) => {
+        if (origin === 'renderer') {
+          await this.addUpdateToSQLite([update]);
+        } else if (origin === 'external') {
+          dbSubjects.externalUpdate.next({
+            workspaceId: this.workspaceId,
+            update,
+          });
+          await this.addUpdateToSQLite([update]);
+          logger.debug('external update', this.workspaceId);
+        }
+      });
+    }
+
+    const updates = await this.getUpdates();
+    const merged = mergeUpdate(updates.map(update => update.data));
+
+    // to initialize the yDoc, we need to apply all updates from the db
+    this.applyUpdate(merged, 'self');
+
+    this.firstConnected = true;
+    this.update$.next();
+
+    return db;
+  }
+
+  getDocAsUpdates = () => {
+    return Y.encodeStateAsUpdate(this.yDoc);
+  };
+
+  // non-blocking and use yDoc to validate the update
+  // after that, the update is added to the db
+  applyUpdate = (data: Uint8Array, origin: YOrigin = 'renderer') => {
+    // todo: trim the updates when the number of records is too large
+    // 1. store the current ydoc state in the db
+    // 2. then delete the old updates
+    // yjs-idb will always trim the db for the first time after DB is loaded
+    Y.applyUpdate(this.yDoc, data, origin);
+  };
+
+  override async addBlob(key: string, value: Uint8Array) {
+    this.update$.next();
+    const res = await super.addBlob(key, value);
+    return res;
+  }
+
+  override async deleteBlob(key: string) {
+    this.update$.next();
+    await super.deleteBlob(key);
+  }
+
+  override async addUpdateToSQLite(data: Uint8Array[]) {
+    this.update$.next();
+    await super.addUpdateToSQLite(data);
+  }
+}
+
+export async function openWorkspaceDatabase(workspaceId: string) {
+  const meta = await getWorkspaceMeta(workspaceId);
+  const db = new WorkspaceSQLiteDB(meta.mainDBPath, workspaceId);
+  await db.init();
+  logger.info(`openWorkspaceDatabase [${workspaceId}]`);
+  return db;
+}

apps/electron/src/helper/dialog/dialog.ts

@@ -0,0 +1,341 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+import { nanoid } from 'nanoid';
+
+import { ensureSQLiteDB } from '../db/ensure-db';
+import type { WorkspaceSQLiteDB } from '../db/workspace-db-adapter';
+import { logger } from '../logger';
+import { mainRPC } from '../main-rpc';
+import {
+  getWorkspaceDBPath,
+  getWorkspaceMeta,
+  getWorkspacesBasePath,
+  listWorkspaces,
+  storeWorkspaceMeta,
+} from '../workspace';
+
+// NOTE:
+// we are using native dialogs because HTML dialogs do not give full file paths
+
+export async function revealDBFile(workspaceId: string) {
+  const meta = await getWorkspaceMeta(workspaceId);
+  if (!meta) {
+    return;
+  }
+  await mainRPC.showItemInFolder(meta.secondaryDBPath ?? meta.mainDBPath);
+}
+
+// provide a backdoor to set dialog path for testing in playwright
+export interface FakeDialogResult {
+  canceled?: boolean;
+  filePath?: string;
+  filePaths?: string[];
+}
+
+// result will be used in the next call to showOpenDialog
+// if it is being read once, it will be reset to undefined
+let fakeDialogResult: FakeDialogResult | undefined = undefined;
+
+function getFakedResult() {
+  const result = fakeDialogResult;
+  fakeDialogResult = undefined;
+  return result;
+}
+
+export function setFakeDialogResult(result: FakeDialogResult | undefined) {
+  fakeDialogResult = result;
+  // for convenience, we will fill filePaths with filePath if it is not set
+  if (result?.filePaths === undefined && result?.filePath !== undefined) {
+    result.filePaths = [result.filePath];
+  }
+}
+
+const ErrorMessages = [
+  'DB_FILE_ALREADY_LOADED',
+  'DB_FILE_PATH_INVALID',
+  'DB_FILE_INVALID',
+  'FILE_ALREADY_EXISTS',
+  'UNKNOWN_ERROR',
+] as const;
+
+type ErrorMessage = (typeof ErrorMessages)[number];
+
+export interface SaveDBFileResult {
+  filePath?: string;
+  canceled?: boolean;
+  error?: ErrorMessage;
+}
+
+const extension = 'affine';
+
+function getDefaultDBFileName(name: string, id: string) {
+  const fileName = `${name}_${id}.${extension}`;
+  // make sure fileName is a valid file name
+  return fileName.replace(/[/\\?%*:|"<>]/g, '-');
+}
+
+/**
+ * This function is called when the user clicks the "Save" button in the "Save Workspace" dialog.
+ *
+ * It will just copy the file to the given path
+ */
+export async function saveDBFileAs(
+  workspaceId: string
+): Promise<SaveDBFileResult> {
+  try {
+    const db = await ensureSQLiteDB(workspaceId);
+    const ret =
+      getFakedResult() ??
+      (await mainRPC.showSaveDialog({
+        properties: ['showOverwriteConfirmation'],
+        title: 'Save Workspace',
+        showsTagField: false,
+        buttonLabel: 'Save',
+        filters: [
+          {
+            extensions: [extension],
+            name: '',
+          },
+        ],
+        defaultPath: getDefaultDBFileName(db.getWorkspaceName(), workspaceId),
+        message: 'Save Workspace as a SQLite Database file',
+      }));
+    const filePath = ret.filePath;
+    if (ret.canceled || !filePath) {
+      return {
+        canceled: true,
+      };
+    }
+
+    await fs.copyFile(db.path, filePath);
+    logger.log('saved', filePath);
+    mainRPC.showItemInFolder(filePath);
+    return { filePath };
+  } catch (err) {
+    logger.error('saveDBFileAs', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}
+
+export interface SelectDBFileLocationResult {
+  filePath?: string;
+  error?: ErrorMessage;
+  canceled?: boolean;
+}
+
+export async function selectDBFileLocation(): Promise<SelectDBFileLocationResult> {
+  try {
+    const ret =
+      getFakedResult() ??
+      (await mainRPC.showOpenDialog({
+        properties: ['openDirectory'],
+        title: 'Set Workspace Storage Location',
+        buttonLabel: 'Select',
+        defaultPath: await mainRPC.getPath('documents'),
+        message: "Select a location to store the workspace's database file",
+      }));
+    const dir = ret.filePaths?.[0];
+    if (ret.canceled || !dir) {
+      return {
+        canceled: true,
+      };
+    }
+    return { filePath: dir };
+  } catch (err) {
+    logger.error('selectDBFileLocation', err);
+    return {
+      error: (err as any).message,
+    };
+  }
+}
+
+export interface LoadDBFileResult {
+  workspaceId?: string;
+  error?: ErrorMessage;
+  canceled?: boolean;
+}
+
+/**
+ * This function is called when the user clicks the "Load" button in the "Load Workspace" dialog.
+ *
+ * It will
+ * - symlink the source db file to a new workspace id to app-data
+ * - return the new workspace id
+ *
+ * eg, it will create a new folder in app-data:
+ * <app-data>/<app-name>/workspaces/<workspace-id>/storage.db
+ *
+ * On the renderer side, after the UI got a new workspace id, it will
+ * update the local workspace id list and then connect to it.
+ *
+ */
+export async function loadDBFile(): Promise<LoadDBFileResult> {
+  try {
+    const ret =
+      getFakedResult() ??
+      (await mainRPC.showOpenDialog({
+        properties: ['openFile'],
+        title: 'Load Workspace',
+        buttonLabel: 'Load',
+        filters: [
+          {
+            name: 'SQLite Database',
+            // do we want to support other file format?
+            extensions: ['db', 'affine'],
+          },
+        ],
+        message: 'Load Workspace from a AFFiNE file',
+      }));
+    const filePath = ret.filePaths?.[0];
+    if (ret.canceled || !filePath) {
+      logger.info('loadDBFile canceled');
+      return { canceled: true };
+    }
+
+    // the imported file should not be in app data dir
+    if (filePath.startsWith(await getWorkspacesBasePath())) {
+      logger.warn('loadDBFile: db file in app data dir');
+      return { error: 'DB_FILE_PATH_INVALID' };
+    }
+
+    if (await dbFileAlreadyLoaded(filePath)) {
+      logger.warn('loadDBFile: db file already loaded');
+      return { error: 'DB_FILE_ALREADY_LOADED' };
+    }
+
+    const { SqliteConnection } = await import('@affine/native');
+
+    if (!(await SqliteConnection.validate(filePath))) {
+      // TODO: report invalid db file error?
+      return { error: 'DB_FILE_INVALID' }; // invalid db file
+    }
+
+    // copy the db file to a new workspace id
+    const workspaceId = nanoid(10);
+    const internalFilePath = await getWorkspaceDBPath(workspaceId);
+
+    await fs.ensureDir(await getWorkspacesBasePath());
+
+    await fs.copy(filePath, internalFilePath);
+    logger.info(`loadDBFile, copy: ${filePath} -> ${internalFilePath}`);
+
+    await storeWorkspaceMeta(workspaceId, {
+      id: workspaceId,
+      mainDBPath: internalFilePath,
+      secondaryDBPath: filePath,
+    });
+
+    return { workspaceId };
+  } catch (err) {
+    logger.error('loadDBFile', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}
+
+export interface MoveDBFileResult {
+  filePath?: string;
+  error?: ErrorMessage;
+  canceled?: boolean;
+}
+
+/**
+ * This function is called when the user clicks the "Move" button in the "Move Workspace Storage" setting.
+ *
+ * It will
+ * - copy the source db file to a new location
+ * - remove the old db external file
+ * - update the external db file path in the workspace meta
+ * - return the new file path
+ */
+export async function moveDBFile(
+  workspaceId: string,
+  dbFileDir?: string
+): Promise<MoveDBFileResult> {
+  let db: WorkspaceSQLiteDB | null = null;
+  try {
+    db = await ensureSQLiteDB(workspaceId);
+    const meta = await getWorkspaceMeta(workspaceId);
+
+    const oldDir = meta.secondaryDBPath
+      ? path.dirname(meta.secondaryDBPath)
+      : null;
+    const defaultDir = oldDir ?? (await mainRPC.getPath('documents'));
+
+    const newName = getDefaultDBFileName(db.getWorkspaceName(), workspaceId);
+
+    const newDirPath =
+      dbFileDir ??
+      (
+        getFakedResult() ??
+        (await mainRPC.showOpenDialog({
+          properties: ['openDirectory'],
+          title: 'Move Workspace Storage',
+          buttonLabel: 'Move',
+          defaultPath: defaultDir,
+          message: 'Move Workspace storage file',
+        }))
+      ).filePaths?.[0];
+
+    // skips if
+    // - user canceled the dialog
+    // - user selected the same dir
+    if (!newDirPath || newDirPath === oldDir) {
+      return {
+        canceled: true,
+      };
+    }
+
+    const newFilePath = path.join(newDirPath, newName);
+
+    if (await fs.pathExists(newFilePath)) {
+      return {
+        error: 'FILE_ALREADY_EXISTS',
+      };
+    }
+
+    logger.info(`[moveDBFile] copy ${meta.mainDBPath} -> ${newFilePath}`);
+
+    await fs.copy(meta.mainDBPath, newFilePath);
+
+    // remove the old db file, but we don't care if it fails
+    if (meta.secondaryDBPath) {
+      await fs
+        .remove(meta.secondaryDBPath)
+        .then(() => {
+          logger.info(`[moveDBFile] removed ${meta.secondaryDBPath}`);
+        })
+        .catch(err => {
+          logger.error(
+            `[moveDBFile] remove ${meta.secondaryDBPath} failed`,
+            err
+          );
+        });
+    }
+
+    // update meta
+    await storeWorkspaceMeta(workspaceId, {
+      secondaryDBPath: newFilePath,
+    });
+
+    return {
+      filePath: newFilePath,
+    };
+  } catch (err) {
+    await db?.destroy();
+    logger.error('[moveDBFile]', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}
+
+async function dbFileAlreadyLoaded(path: string) {
+  const meta = await listWorkspaces();
+  const paths = meta.map(m => m[1].secondaryDBPath);
+  return paths.includes(path);
+}

apps/electron/src/helper/dialog/index.ts

@@ -0,0 +1,31 @@
+import {
+  loadDBFile,
+  moveDBFile,
+  revealDBFile,
+  saveDBFileAs,
+  selectDBFileLocation,
+  setFakeDialogResult,
+} from './dialog';
+
+export const dialogHandlers = {
+  revealDBFile: async (workspaceId: string) => {
+    return revealDBFile(workspaceId);
+  },
+  loadDBFile: async () => {
+    return loadDBFile();
+  },
+  saveDBFileAs: async (workspaceId: string) => {
+    return saveDBFileAs(workspaceId);
+  },
+  moveDBFile: (workspaceId: string, dbFileLocation?: string) => {
+    return moveDBFile(workspaceId, dbFileLocation);
+  },
+  selectDBFileLocation: async () => {
+    return selectDBFileLocation();
+  },
+  setFakeDialogResult: async (
+    result: Parameters<typeof setFakeDialogResult>[0]
+  ) => {
+    return setFakeDialogResult(result);
+  },
+};

apps/electron/src/helper/exposed.ts

@@ -0,0 +1,33 @@
+import { dbEvents, dbHandlers } from './db';
+import { dialogHandlers } from './dialog';
+import { workspaceEvents, workspaceHandlers } from './workspace';
+
+export const handlers = {
+  db: dbHandlers,
+  workspace: workspaceHandlers,
+  dialog: dialogHandlers,
+};
+
+export const events = {
+  db: dbEvents,
+  workspace: workspaceEvents,
+};
+
+export const getExposedMeta = () => {
+  const handlersMeta = Object.entries(handlers).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)] as [string, string[]];
+    }
+  );
+
+  const eventsMeta = Object.entries(events).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)] as [string, string[]];
+    }
+  );
+
+  return {
+    handlers: handlersMeta,
+    events: eventsMeta,
+  };
+};

apps/electron/src/helper/index.ts

@@ -0,0 +1,86 @@
+import type { EventBasedChannel } from 'async-call-rpc';
+import { AsyncCall } from 'async-call-rpc';
+
+import { events, handlers } from './exposed';
+import { logger } from './logger';
+
+const createMessagePortMainChannel = (
+  connection: Electron.MessagePortMain
+): EventBasedChannel => {
+  return {
+    on(listener) {
+      const f = (e: Electron.MessageEvent) => {
+        listener(e.data);
+      };
+      connection.on('message', f);
+      // MUST start the connection to receive messages
+      connection.start();
+      return () => {
+        connection.off('message', f);
+      };
+    },
+    send(data) {
+      connection.postMessage(data);
+    },
+  };
+};
+
+function setupRendererConnection(rendererPort: Electron.MessagePortMain) {
+  const flattenedHandlers = Object.entries(handlers).flatMap(
+    ([namespace, namespaceHandlers]) => {
+      return Object.entries(namespaceHandlers).map(([name, handler]) => {
+        const handlerWithLog = async (...args: any[]) => {
+          try {
+            const start = performance.now();
+            const result = await handler(...args);
+            logger.info(
+              '[async-api]',
+              `${namespace}.${name}`,
+              args.filter(
+                arg => typeof arg !== 'function' && typeof arg !== 'object'
+              ),
+              '-',
+              (performance.now() - start).toFixed(2),
+              'ms'
+            );
+            return result;
+          } catch (error) {
+            logger.error('[async-api]', `${namespace}.${name}`, error);
+          }
+        };
+        return [`${namespace}:${name}`, handlerWithLog];
+      });
+    }
+  );
+  const rpc = AsyncCall<PeersAPIs.RendererToHelper>(
+    Object.fromEntries(flattenedHandlers),
+    {
+      channel: createMessagePortMainChannel(rendererPort),
+      log: false,
+    }
+  );
+
+  for (const [namespace, namespaceEvents] of Object.entries(events)) {
+    for (const [key, eventRegister] of Object.entries(namespaceEvents)) {
+      const subscription = eventRegister((...args: any[]) => {
+        const chan = `${namespace}:${key}`;
+        rpc.postEvent(chan, ...args);
+      });
+      process.on('exit', () => {
+        subscription();
+      });
+    }
+  }
+}
+
+function main() {
+  process.parentPort.on('message', e => {
+    if (e.data.channel === 'renderer-connect' && e.ports.length === 1) {
+      const rendererPort = e.ports[0];
+      setupRendererConnection(rendererPort);
+      logger.info('[helper] renderer connected');
+    }
+  });
+}
+
+main();

apps/electron/src/helper/logger.ts

@@ -0,0 +1,3 @@
+import log from 'electron-log';
+
+export const logger = log.scope('helper');

apps/electron/src/helper/main-rpc.ts

@@ -0,0 +1,33 @@
+import { AsyncCall, type EventBasedChannel } from 'async-call-rpc';
+
+import { getExposedMeta } from './exposed';
+
+function createMessagePortMainChannel(
+  connection: Electron.ParentPort
+): EventBasedChannel {
+  return {
+    on(listener) {
+      const f = (e: Electron.MessageEvent) => {
+        listener(e.data);
+      };
+      connection.on('message', f);
+      return () => {
+        connection.off('message', f);
+      };
+    },
+    send(data) {
+      connection.postMessage(data);
+    },
+  };
+}
+
+const helperToMainServer: PeersAPIs.HelperToMain = {
+  getMeta: () => getExposedMeta(),
+};
+
+export const mainRPC = AsyncCall<PeersAPIs.MainToHelper>(helperToMainServer, {
+  strict: {
+    unknownMessage: false,
+  },
+  channel: createMessagePortMainChannel(process.parentPort),
+});

apps/electron/src/helper/type.ts

@@ -0,0 +1,9 @@
+export interface WorkspaceMeta {
+  id: string;
+  mainDBPath: string;
+  secondaryDBPath?: string; // assume there will be only one
+}
+
+export type YOrigin = 'self' | 'external' | 'upstream' | 'renderer';
+
+export type MainEventRegister = (...args: any[]) => () => void;

apps/electron/src/helper/workspace/__tests__/.gitignore

@@ -0,0 +1 @@
+tmp

apps/electron/src/helper/workspace/__tests__/handlers.spec.ts

@@ -0,0 +1,142 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+import { v4 } from 'uuid';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+const tmpDir = path.join(__dirname, 'tmp');
+const appDataPath = path.join(tmpDir, 'app-data');
+
+vi.doMock('../../db/ensure-db', () => ({
+  ensureSQLiteDB: async () => ({
+    destroy: () => {},
+  }),
+}));
+
+vi.doMock('../../main-rpc', () => ({
+  mainRPC: {
+    getPath: async () => appDataPath,
+  },
+}));
+
+afterEach(async () => {
+  await fs.remove(tmpDir);
+});
+
+describe('list workspaces', () => {
+  test('listWorkspaces (valid)', async () => {
+    const { listWorkspaces } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    const meta = {
+      id: workspaceId,
+    };
+    await fs.ensureDir(workspacePath);
+    await fs.writeJSON(path.join(workspacePath, 'meta.json'), meta);
+    const workspaces = await listWorkspaces();
+    expect(workspaces).toEqual([[workspaceId, meta]]);
+  });
+
+  test('listWorkspaces (without meta json file)', async () => {
+    const { listWorkspaces } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    await fs.ensureDir(workspacePath);
+    const workspaces = await listWorkspaces();
+    expect(workspaces).toEqual([
+      [
+        workspaceId,
+        // meta file will be created automatically
+        { id: workspaceId, mainDBPath: path.join(workspacePath, 'storage.db') },
+      ],
+    ]);
+  });
+});
+
+describe('delete workspace', () => {
+  test('deleteWorkspace', async () => {
+    const { deleteWorkspace } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    await fs.ensureDir(workspacePath);
+    await deleteWorkspace(workspaceId);
+    expect(await fs.pathExists(workspacePath)).toBe(false);
+    // removed workspace will be moved to deleted-workspaces
+    expect(
+      await fs.pathExists(
+        path.join(appDataPath, 'deleted-workspaces', workspaceId)
+      )
+    ).toBe(true);
+  });
+});
+
+describe('getWorkspaceMeta', () => {
+  test('can get meta', async () => {
+    const { getWorkspaceMeta } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    const meta = {
+      id: workspaceId,
+    };
+    await fs.ensureDir(workspacePath);
+    await fs.writeJSON(path.join(workspacePath, 'meta.json'), meta);
+    expect(await getWorkspaceMeta(workspaceId)).toEqual(meta);
+  });
+
+  test('can create meta if not exists', async () => {
+    const { getWorkspaceMeta } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    await fs.ensureDir(workspacePath);
+    expect(await getWorkspaceMeta(workspaceId)).toEqual({
+      id: workspaceId,
+      mainDBPath: path.join(workspacePath, 'storage.db'),
+    });
+    expect(
+      await fs.pathExists(path.join(workspacePath, 'meta.json'))
+    ).toBeTruthy();
+  });
+
+  test('can migrate meta if db file is a link', async () => {
+    const { getWorkspaceMeta } = await import('../handlers');
+    const workspaceId = v4();
+    const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+    await fs.ensureDir(workspacePath);
+    const sourcePath = path.join(tmpDir, 'source.db');
+    await fs.writeFile(sourcePath, 'test');
+
+    await fs.ensureSymlink(sourcePath, path.join(workspacePath, 'storage.db'));
+
+    expect(await getWorkspaceMeta(workspaceId)).toEqual({
+      id: workspaceId,
+      mainDBPath: path.join(workspacePath, 'storage.db'),
+      secondaryDBPath: sourcePath,
+    });
+
+    expect(
+      await fs.pathExists(path.join(workspacePath, 'meta.json'))
+    ).toBeTruthy();
+  });
+});
+
+test('storeWorkspaceMeta', async () => {
+  const { storeWorkspaceMeta } = await import('../handlers');
+  const workspaceId = v4();
+  const workspacePath = path.join(appDataPath, 'workspaces', workspaceId);
+  await fs.ensureDir(workspacePath);
+  const meta = {
+    id: workspaceId,
+    mainDBPath: path.join(workspacePath, 'storage.db'),
+  };
+  await storeWorkspaceMeta(workspaceId, meta);
+  expect(await fs.readJSON(path.join(workspacePath, 'meta.json'))).toEqual(
+    meta
+  );
+  await storeWorkspaceMeta(workspaceId, {
+    secondaryDBPath: path.join(tmpDir, 'test.db'),
+  });
+  expect(await fs.readJSON(path.join(workspacePath, 'meta.json'))).toEqual({
+    ...meta,
+    secondaryDBPath: path.join(tmpDir, 'test.db'),
+  });
+});

apps/electron/src/helper/workspace/handlers.ts

@@ -0,0 +1,143 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+
+import { ensureSQLiteDB } from '../db/ensure-db';
+import { logger } from '../logger';
+import { mainRPC } from '../main-rpc';
+import type { WorkspaceMeta } from '../type';
+import { workspaceSubjects } from './subjects';
+
+let _appDataPath = '';
+
+async function getAppDataPath() {
+  if (_appDataPath) {
+    return _appDataPath;
+  }
+  _appDataPath = await mainRPC.getPath('sessionData');
+  return _appDataPath;
+}
+
+export async function listWorkspaces(): Promise<
+  [workspaceId: string, meta: WorkspaceMeta][]
+> {
+  const basePath = await getWorkspacesBasePath();
+  try {
+    await fs.ensureDir(basePath);
+    const dirs = (
+      await fs.readdir(basePath, {
+        withFileTypes: true,
+      })
+    ).filter(d => d.isDirectory());
+    const metaList = (
+      await Promise.all(
+        dirs.map(async dir => {
+          // ? shall we put all meta in a single file instead of one file per workspace?
+          return await getWorkspaceMeta(dir.name);
+        })
+      )
+    ).filter((w): w is WorkspaceMeta => !!w);
+    return metaList.map(meta => [meta.id, meta]);
+  } catch (error) {
+    logger.error('listWorkspaces', error);
+    return [];
+  }
+}
+
+export async function deleteWorkspace(id: string) {
+  const basePath = await getWorkspaceBasePath(id);
+  const movedPath = path.join(await getDeletedWorkspacesBasePath(), `${id}`);
+  try {
+    const db = await ensureSQLiteDB(id);
+    await db.destroy();
+    return await fs.move(basePath, movedPath, {
+      overwrite: true,
+    });
+  } catch (error) {
+    logger.error('deleteWorkspace', error);
+  }
+}
+
+export async function getWorkspacesBasePath() {
+  return path.join(await getAppDataPath(), 'workspaces');
+}
+
+export async function getWorkspaceBasePath(workspaceId: string) {
+  return path.join(await getAppDataPath(), 'workspaces', workspaceId);
+}
+
+async function getDeletedWorkspacesBasePath() {
+  return path.join(await getAppDataPath(), 'deleted-workspaces');
+}
+
+export async function getWorkspaceDBPath(workspaceId: string) {
+  return path.join(await getWorkspaceBasePath(workspaceId), 'storage.db');
+}
+
+export async function getWorkspaceMetaPath(workspaceId: string) {
+  return path.join(await getWorkspaceBasePath(workspaceId), 'meta.json');
+}
+
+/**
+ * Get workspace meta, create one if not exists
+ * This function will also migrate the workspace if needed
+ */
+export async function getWorkspaceMeta(
+  workspaceId: string
+): Promise<WorkspaceMeta> {
+  try {
+    const basePath = await getWorkspaceBasePath(workspaceId);
+    const metaPath = await getWorkspaceMetaPath(workspaceId);
+    if (!(await fs.exists(metaPath))) {
+      // since not meta is found, we will migrate symlinked db file if needed
+      await fs.ensureDir(basePath);
+      const dbPath = await getWorkspaceDBPath(workspaceId);
+
+      // todo: remove this after migration (in stable version)
+      const realDBPath = (await fs.exists(dbPath))
+        ? await fs.realpath(dbPath)
+        : dbPath;
+      const isLink = realDBPath !== dbPath;
+      if (isLink) {
+        await fs.copy(realDBPath, dbPath);
+      }
+      // create one if not exists
+      const meta = {
+        id: workspaceId,
+        mainDBPath: dbPath,
+        secondaryDBPath: isLink ? realDBPath : undefined,
+      };
+      await fs.writeJSON(metaPath, meta);
+      return meta;
+    } else {
+      const meta = await fs.readJSON(metaPath);
+      return meta;
+    }
+  } catch (err) {
+    logger.error('getWorkspaceMeta failed', err);
+    throw err;
+  }
+}
+
+export async function storeWorkspaceMeta(
+  workspaceId: string,
+  meta: Partial<WorkspaceMeta>
+) {
+  try {
+    const basePath = await getWorkspaceBasePath(workspaceId);
+    await fs.ensureDir(basePath);
+    const metaPath = path.join(basePath, 'meta.json');
+    const currentMeta = await getWorkspaceMeta(workspaceId);
+    const newMeta = {
+      ...currentMeta,
+      ...meta,
+    };
+    await fs.writeJSON(metaPath, newMeta);
+    workspaceSubjects.meta.next({
+      workspaceId,
+      meta: newMeta,
+    });
+  } catch (err) {
+    logger.error('storeWorkspaceMeta failed', err);
+  }
+}

apps/electron/src/helper/workspace/index.ts

@@ -0,0 +1,25 @@
+import type { MainEventRegister, WorkspaceMeta } from '../type';
+import { deleteWorkspace, getWorkspaceMeta, listWorkspaces } from './handlers';
+import { workspaceSubjects } from './subjects';
+
+export * from './handlers';
+export * from './subjects';
+
+export const workspaceEvents = {
+  onMetaChange: (
+    fn: (meta: { workspaceId: string; meta: WorkspaceMeta }) => void
+  ) => {
+    const sub = workspaceSubjects.meta.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+} satisfies Record<string, MainEventRegister>;
+
+export const workspaceHandlers = {
+  list: async () => listWorkspaces(),
+  delete: async (id: string) => deleteWorkspace(id),
+  getMeta: async (id: string) => {
+    return getWorkspaceMeta(id);
+  },
+};

apps/electron/src/helper/workspace/subjects.ts

@@ -0,0 +1,7 @@
+import { Subject } from 'rxjs';
+
+import type { WorkspaceMeta } from '../type';
+
+export const workspaceSubjects = {
+  meta: new Subject<{ workspaceId: string; meta: WorkspaceMeta }>(),
+};

apps/electron/src/main/__tests__/.gitignore

@@ -0,0 +1 @@
+tmp

apps/electron/src/main/__tests__/integration.spec.ts

@@ -0,0 +1,173 @@
+import assert from 'node:assert';
+import path from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+
+import fs from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import type { MainIPCHandlerMap } from '../exposed';
+
+const registeredHandlers = new Map<
+  string,
+  ((...args: any[]) => Promise<any>)[]
+>();
+
+type WithoutFirstParameter<T> = T extends (_: any, ...args: infer P) => infer R
+  ? (...args: P) => R
+  : T;
+
+// common mock dispatcher for ipcMain.handle AND app.on
+// alternatively, we can use single parameter for T & F, eg, dispatch('workspace:list'),
+// however this is too hard to be typed correctly
+async function dispatch<
+  T extends keyof MainIPCHandlerMap,
+  F extends keyof MainIPCHandlerMap[T]
+>(
+  namespace: T,
+  functionName: F,
+  ...args: Parameters<WithoutFirstParameter<MainIPCHandlerMap[T][F]>>
+): // @ts-expect-error
+ReturnType<MainIPCHandlerMap[T][F]> {
+  // @ts-expect-error
+  const handlers = registeredHandlers.get(namespace + ':' + functionName);
+  assert(handlers);
+
+  // we only care about the first handler here
+  return await handlers[0](null, ...args);
+}
+
+const SESSION_DATA_PATH = path.join(__dirname, './tmp', 'affine-test');
+const DOCUMENTS_PATH = path.join(__dirname, './tmp', 'affine-test-documents');
+
+const browserWindow = {
+  isDestroyed: () => {
+    return false;
+  },
+  setWindowButtonVisibility: (_v: boolean) => {
+    // will be stubbed later
+  },
+  webContents: {
+    send: (_type: string, ..._args: any[]) => {
+      // will be stubbed later
+    },
+  },
+};
+
+const ipcMain = {
+  handle: (key: string, callback: (...args: any[]) => Promise<any>) => {
+    const handlers = registeredHandlers.get(key) || [];
+    handlers.push(callback);
+    registeredHandlers.set(key, handlers);
+  },
+  setMaxListeners: (_n: number) => {
+    // noop
+  },
+};
+
+const nativeTheme = {
+  themeSource: 'light',
+};
+
+const electronModule = {
+  app: {
+    getPath: (name: string) => {
+      if (name === 'sessionData') {
+        return SESSION_DATA_PATH;
+      } else if (name === 'documents') {
+        return DOCUMENTS_PATH;
+      }
+      throw new Error('not implemented');
+    },
+    name: 'affine-test',
+    on: (name: string, callback: (...args: any[]) => any) => {
+      const handlers = registeredHandlers.get(name) || [];
+      handlers.push(callback);
+      registeredHandlers.set(name, handlers);
+    },
+    addListener: (...args: any[]) => {
+      // @ts-expect-error
+      electronModule.app.on(...args);
+    },
+    removeListener: () => {},
+  },
+  BrowserWindow: {
+    getAllWindows: () => {
+      return [browserWindow];
+    },
+  },
+  nativeTheme: nativeTheme,
+  ipcMain,
+  shell: {} as Partial<Electron.Shell>,
+  dialog: {} as Partial<Electron.Dialog>,
+};
+
+// dynamically import handlers so that we can inject local variables to mocks
+vi.doMock('electron', () => {
+  return electronModule;
+});
+
+beforeEach(async () => {
+  const { registerHandlers } = await import('../handlers');
+  registerHandlers();
+
+  // should also register events
+  const { registerEvents } = await import('../events');
+  registerEvents();
+  await fs.mkdirp(SESSION_DATA_PATH);
+
+  registeredHandlers.get('ready')?.forEach(fn => fn());
+});
+
+afterEach(async () => {
+  // reset registered handlers
+  registeredHandlers.get('before-quit')?.forEach(fn => fn());
+  // wait for the db to be closed on Windows
+  if (process.platform === 'win32') {
+    await setTimeout(200);
+  }
+  await fs.remove(SESSION_DATA_PATH);
+});
+
+describe('UI handlers', () => {
+  test('theme-change', async () => {
+    await dispatch('ui', 'handleThemeChange', 'dark');
+    expect(nativeTheme.themeSource).toBe('dark');
+    await dispatch('ui', 'handleThemeChange', 'light');
+    expect(nativeTheme.themeSource).toBe('light');
+  });
+
+  test('sidebar-visibility-change (macOS)', async () => {
+    vi.stubGlobal('process', { platform: 'darwin' });
+    const setWindowButtonVisibility = vi.fn();
+    browserWindow.setWindowButtonVisibility = setWindowButtonVisibility;
+    await dispatch('ui', 'handleSidebarVisibilityChange', true);
+    expect(setWindowButtonVisibility).toBeCalledWith(true);
+    await dispatch('ui', 'handleSidebarVisibilityChange', false);
+    expect(setWindowButtonVisibility).toBeCalledWith(false);
+    vi.unstubAllGlobals();
+  });
+
+  test('sidebar-visibility-change (non-macOS)', async () => {
+    vi.stubGlobal('process', { platform: 'linux' });
+    const setWindowButtonVisibility = vi.fn();
+    browserWindow.setWindowButtonVisibility = setWindowButtonVisibility;
+    await dispatch('ui', 'handleSidebarVisibilityChange', true);
+    expect(setWindowButtonVisibility).not.toBeCalled();
+    vi.unstubAllGlobals();
+  });
+});
+
+describe('applicationMenu', () => {
+  // test some basic IPC events
+  test('applicationMenu event', async () => {
+    const { applicationMenuSubjects } = await import('../application-menu');
+    const sendStub = vi.fn();
+    browserWindow.webContents.send = sendStub;
+    applicationMenuSubjects.newPageAction.next();
+    expect(sendStub).toHaveBeenCalledWith(
+      'applicationMenu:onNewPageAction',
+      undefined
+    );
+    browserWindow.webContents.send = () => {};
+  });
+});

apps/electron/src/main/application-menu/create.ts

@@ -0,0 +1,142 @@
+import { app, Menu } from 'electron';
+
+import { revealLogFile } from '../logger';
+import { checkForUpdatesAndNotify } from '../updater';
+import { isMacOS } from '../utils';
+import { applicationMenuSubjects } from './subject';
+
+// Unique id for menuitems
+const MENUITEM_NEW_PAGE = 'affine:new-page';
+
+export function createApplicationMenu() {
+  const isMac = isMacOS();
+
+  // Electron menu cannot be modified
+  // You have to copy the complete default menu template event if you want to add a single custom item
+  // See https://www.electronjs.org/docs/latest/api/menu#examples
+  const template = [
+    // { role: 'appMenu' }
+    ...(isMac
+      ? [
+          {
+            label: app.name,
+            submenu: [
+              { role: 'about' },
+              { type: 'separator' },
+              { role: 'services' },
+              { type: 'separator' },
+              { role: 'hide' },
+              { role: 'hideOthers' },
+              { role: 'unhide' },
+              { type: 'separator' },
+              { role: 'quit' },
+            ],
+          },
+        ]
+      : []),
+    // { role: 'fileMenu' }
+    {
+      label: 'File',
+      submenu: [
+        {
+          id: MENUITEM_NEW_PAGE,
+          label: 'New Page',
+          accelerator: isMac ? 'Cmd+N' : 'Ctrl+N',
+          click: () => {
+            applicationMenuSubjects.newPageAction.next();
+          },
+        },
+        { type: 'separator' },
+        isMac ? { role: 'close' } : { role: 'quit' },
+      ],
+    },
+    // { role: 'editMenu' }
+    {
+      label: 'Edit',
+      submenu: [
+        { role: 'undo' },
+        { role: 'redo' },
+        { type: 'separator' },
+        { role: 'cut' },
+        { role: 'copy' },
+        { role: 'paste' },
+        ...(isMac
+          ? [
+              { role: 'pasteAndMatchStyle' },
+              { role: 'delete' },
+              { role: 'selectAll' },
+              { type: 'separator' },
+              {
+                label: 'Speech',
+                submenu: [{ role: 'startSpeaking' }, { role: 'stopSpeaking' }],
+              },
+            ]
+          : [{ role: 'delete' }, { type: 'separator' }, { role: 'selectAll' }]),
+      ],
+    },
+    // { role: 'viewMenu' }
+    {
+      label: 'View',
+      submenu: [
+        { role: 'reload' },
+        { role: 'forceReload' },
+        { role: 'toggleDevTools' },
+        { type: 'separator' },
+        { role: 'resetZoom' },
+        { role: 'zoomIn' },
+        { role: 'zoomOut' },
+        { type: 'separator' },
+        { role: 'togglefullscreen' },
+      ],
+    },
+    // { role: 'windowMenu' }
+    {
+      label: 'Window',
+      submenu: [
+        { role: 'minimize' },
+        { role: 'zoom' },
+        ...(isMac
+          ? [
+              { type: 'separator' },
+              { role: 'front' },
+              { type: 'separator' },
+              { role: 'window' },
+            ]
+          : [{ role: 'close' }]),
+      ],
+    },
+    {
+      role: 'help',
+      submenu: [
+        {
+          label: 'Learn More',
+          click: async () => {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { shell } = require('electron');
+            await shell.openExternal('https://affine.pro/');
+          },
+        },
+        {
+          label: 'Open log file',
+          click: async () => {
+            await revealLogFile();
+          },
+        },
+        {
+          label: 'Check for Updates',
+          click: async () => {
+            await checkForUpdatesAndNotify(true);
+          },
+        },
+      ],
+    },
+  ];
+
+  // @ts-expect-error: The snippet is copied from Electron official docs.
+  //                   It's working as expected. No idea why it contains type errors.
+  //                   Just ignore for now.
+  const menu = Menu.buildFromTemplate(template);
+  Menu.setApplicationMenu(menu);
+
+  return menu;
+}

apps/electron/src/main/application-menu/index.ts

@@ -0,0 +1,20 @@
+import type { MainEventRegister } from '../type';
+import { applicationMenuSubjects } from './subject';
+
+export * from './create';
+export * from './subject';
+
+/**
+ * Events triggered by application menu
+ */
+export const applicationMenuEvents = {
+  /**
+   * File -> New Page
+   */
+  onNewPageAction: (fn: () => void) => {
+    const sub = applicationMenuSubjects.newPageAction.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+} satisfies Record<string, MainEventRegister>;

apps/electron/src/main/application-menu/subject.ts

@@ -0,0 +1,5 @@
+import { Subject } from 'rxjs';
+
+export const applicationMenuSubjects = {
+  newPageAction: new Subject<void>(),
+};

apps/electron/src/main/events.ts

@@ -0,0 +1,39 @@
+import { app, BrowserWindow } from 'electron';
+
+import { applicationMenuEvents } from './application-menu';
+import { logger } from './logger';
+import { updaterEvents } from './updater/event';
+
+export const allEvents = {
+  applicationMenu: applicationMenuEvents,
+  updater: updaterEvents,
+};
+
+function getActiveWindows() {
+  return BrowserWindow.getAllWindows().filter(win => !win.isDestroyed());
+}
+
+export function registerEvents() {
+  // register events
+  for (const [namespace, namespaceEvents] of Object.entries(allEvents)) {
+    for (const [key, eventRegister] of Object.entries(namespaceEvents)) {
+      const subscription = eventRegister((...args: any[]) => {
+        const chan = `${namespace}:${key}`;
+        logger.info(
+          '[ipc-event]',
+          chan,
+          args.filter(
+            a =>
+              a !== undefined &&
+              typeof a !== 'function' &&
+              typeof a !== 'object'
+          )
+        );
+        getActiveWindows().forEach(win => win.webContents.send(chan, ...args));
+      });
+      app.on('before-quit', () => {
+        subscription();
+      });
+    }
+  }
+}

apps/electron/src/main/export/index.ts

@@ -0,0 +1,10 @@
+import type { NamespaceHandlers } from '../type';
+import { savePDFFileAs } from './pdf';
+
+export const exportHandlers = {
+  savePDFFileAs: async (_, title: string) => {
+    return savePDFFileAs(title);
+  },
+} satisfies NamespaceHandlers;
+
+export * from './pdf';

apps/electron/src/main/export/pdf.ts

@@ -0,0 +1,61 @@
+import { BrowserWindow, dialog, shell } from 'electron';
+import fs from 'fs-extra';
+
+import { logger } from '../logger';
+import type { ErrorMessage } from './utils';
+import { getFakedResult } from './utils';
+
+export interface SavePDFFileResult {
+  filePath?: string;
+  canceled?: boolean;
+  error?: ErrorMessage;
+}
+
+/**
+ * This function is called when the user clicks the "Export to PDF" button in the electron.
+ *
+ * It will just copy the file to the given path
+ */
+export async function savePDFFileAs(
+  pageTitle: string
+): Promise<SavePDFFileResult> {
+  try {
+    const ret =
+      getFakedResult() ??
+      (await dialog.showSaveDialog({
+        properties: ['showOverwriteConfirmation'],
+        title: 'Save PDF',
+        showsTagField: false,
+        buttonLabel: 'Save',
+        defaultPath: `${pageTitle}.pdf`,
+        message: 'Save Page as a PDF file',
+      }));
+    const filePath = ret.filePath;
+    if (ret.canceled || !filePath) {
+      return {
+        canceled: true,
+      };
+    }
+
+    await BrowserWindow.getFocusedWindow()
+      ?.webContents.printToPDF({
+        pageSize: 'A4',
+        printBackground: true,
+        landscape: false,
+      })
+      .then(data => {
+        fs.writeFile(filePath, data, error => {
+          if (error) throw error;
+          logger.log(`Wrote PDF successfully to ${filePath}`);
+        });
+      });
+
+    await shell.openPath(filePath);
+    return { filePath };
+  } catch (err) {
+    logger.error('savePDFFileAs', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}

apps/electron/src/main/export/utils.ts

@@ -0,0 +1,24 @@
+// provide a backdoor to set dialog path for testing in playwright
+interface FakeDialogResult {
+  canceled?: boolean;
+  filePath?: string;
+  filePaths?: string[];
+}
+// result will be used in the next call to showOpenDialog
+// if it is being read once, it will be reset to undefined
+let fakeDialogResult: FakeDialogResult | undefined = undefined;
+export function getFakedResult() {
+  const result = fakeDialogResult;
+  fakeDialogResult = undefined;
+  return result;
+}
+
+export function setFakeDialogResult(result: FakeDialogResult | undefined) {
+  fakeDialogResult = result;
+  // for convenience, we will fill filePaths with filePath if it is not set
+  if (result?.filePaths === undefined && result?.filePath !== undefined) {
+    result.filePaths = [result.filePath];
+  }
+}
+const ErrorMessages = ['FILE_ALREADY_EXISTS', 'UNKNOWN_ERROR'] as const;
+export type ErrorMessage = (typeof ErrorMessages)[number];

apps/electron/src/main/exposed.ts

@@ -0,0 +1,29 @@
+import { allEvents as events } from './events';
+import { allHandlers as handlers } from './handlers';
+
+// this will be used by preload script to expose all handlers and events to the renderer process
+// - register in exposeInMainWorld in preload
+// - provide type hints
+export { events, handlers };
+
+export const getExposedMeta = () => {
+  const handlersMeta = Object.entries(handlers).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)];
+    }
+  );
+
+  const eventsMeta = Object.entries(events).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)];
+    }
+  );
+
+  return {
+    handlers: handlersMeta,
+    events: eventsMeta,
+  };
+};
+
+export type MainIPCHandlerMap = typeof handlers;
+export type MainIPCEventMap = typeof events;

apps/electron/src/main/handlers.ts

@@ -0,0 +1,79 @@
+import type {
+  DebugHandlerManager,
+  ExportHandlerManager,
+  UIHandlerManager,
+  UnwrapManagerHandlerToServerSide,
+  UpdaterHandlerManager,
+} from '@toeverything/infra';
+import { ipcMain } from 'electron';
+
+import { exportHandlers } from './export';
+import { getLogFilePath, logger, revealLogFile } from './logger';
+import { uiHandlers } from './ui';
+import { updaterHandlers } from './updater';
+
+export const debugHandlers = {
+  revealLogFile: async () => {
+    return revealLogFile();
+  },
+  logFilePath: async () => {
+    return getLogFilePath();
+  },
+};
+
+type AllHandlers = {
+  debug: UnwrapManagerHandlerToServerSide<
+    Electron.IpcMainInvokeEvent,
+    DebugHandlerManager
+  >;
+  export: UnwrapManagerHandlerToServerSide<
+    Electron.IpcMainInvokeEvent,
+    ExportHandlerManager
+  >;
+  ui: UnwrapManagerHandlerToServerSide<
+    Electron.IpcMainInvokeEvent,
+    UIHandlerManager
+  >;
+  updater: UnwrapManagerHandlerToServerSide<
+    Electron.IpcMainInvokeEvent,
+    UpdaterHandlerManager
+  >;
+};
+
+// Note: all of these handlers will be the single-source-of-truth for the apis exposed to the renderer process
+export const allHandlers = {
+  debug: debugHandlers,
+  ui: uiHandlers,
+  export: exportHandlers,
+  updater: updaterHandlers,
+} satisfies AllHandlers;
+
+export const registerHandlers = () => {
+  // TODO: listen to namespace instead of individual event types
+  ipcMain.setMaxListeners(100);
+  for (const [namespace, namespaceHandlers] of Object.entries(allHandlers)) {
+    for (const [key, handler] of Object.entries(namespaceHandlers)) {
+      const chan = `${namespace}:${key}`;
+      ipcMain.handle(chan, async (e, ...args) => {
+        const start = performance.now();
+        try {
+          // @ts-expect-error - TODO: fix this
+          const result = await handler(e, ...args);
+          logger.info(
+            '[ipc-api]',
+            chan,
+            args.filter(
+              arg => typeof arg !== 'function' && typeof arg !== 'object'
+            ),
+            '-',
+            (performance.now() - start).toFixed(2),
+            'ms'
+          );
+          return result;
+        } catch (error) {
+          logger.error('[ipc]', chan, error);
+        }
+      });
+    }
+  }
+};

apps/electron/src/main/helper-process.ts

@@ -0,0 +1,111 @@
+import path from 'node:path';
+
+import { type _AsyncVersionOf, AsyncCall } from 'async-call-rpc';
+import {
+  app,
+  dialog,
+  MessageChannelMain,
+  shell,
+  type UtilityProcess,
+  utilityProcess,
+  type WebContents,
+} from 'electron';
+
+import { logger } from './logger';
+import { MessageEventChannel } from './utils';
+
+const HELPER_PROCESS_PATH = path.join(__dirname, './helper.js');
+
+function pickAndBind<T extends object, U extends keyof T>(
+  obj: T,
+  keys: U[]
+): { [K in U]: T[K] } {
+  return keys.reduce((acc, key) => {
+    const prop = obj[key];
+    acc[key] =
+      typeof prop === 'function'
+        ? // @ts-expect-error - a hack to bind the function
+          prop.bind(obj)
+        : prop;
+    return acc;
+  }, {} as any);
+}
+
+class HelperProcessManager {
+  ready: Promise<void>;
+  #process: UtilityProcess;
+
+  // a rpc server for the main process -> helper process
+  rpc?: _AsyncVersionOf<PeersAPIs.HelperToMain>;
+
+  static instance = new HelperProcessManager();
+
+  private constructor() {
+    const helperProcess = utilityProcess.fork(HELPER_PROCESS_PATH);
+    this.#process = helperProcess;
+    this.ready = new Promise((resolve, reject) => {
+      helperProcess.once('spawn', () => {
+        try {
+          this.#connectMain();
+          resolve();
+        } catch (err) {
+          logger.error('[helper] connectMain error', err);
+          reject(err);
+        }
+      });
+    });
+
+    app.on('before-quit', () => {
+      this.#process.kill();
+    });
+  }
+
+  // bridge renderer <-> helper process
+  connectRenderer(renderer: WebContents) {
+    // connect to the helper process
+    const { port1: helperPort, port2: rendererPort } = new MessageChannelMain();
+    this.#process.postMessage({ channel: 'renderer-connect' }, [helperPort]);
+    renderer.postMessage('helper-connection', null, [rendererPort]);
+
+    return () => {
+      helperPort.close();
+      rendererPort.close();
+    };
+  }
+
+  // bridge main <-> helper process
+  // also set up the RPC to the helper process
+  #connectMain() {
+    const dialogMethods = pickAndBind(dialog, [
+      'showOpenDialog',
+      'showSaveDialog',
+    ]);
+    const shellMethods = pickAndBind(shell, [
+      'openExternal',
+      'showItemInFolder',
+    ]);
+    const appMethods = pickAndBind(app, ['getPath']);
+
+    const mainToHelperServer: PeersAPIs.MainToHelper = {
+      ...dialogMethods,
+      ...shellMethods,
+      ...appMethods,
+    };
+
+    const server = AsyncCall<PeersAPIs.HelperToMain>(mainToHelperServer, {
+      strict: {
+        // the channel is shared for other purposes as well so that we do not want to
+        // restrict to only JSONRPC messages
+        unknownMessage: false,
+      },
+      channel: new MessageEventChannel(this.#process),
+    });
+    this.rpc = server;
+  }
+}
+
+export async function ensureHelperProcess() {
+  const helperProcessManager = HelperProcessManager.instance;
+  await helperProcessManager.ready;
+  return helperProcessManager;
+}

apps/electron/src/main/index.ts

@@ -0,0 +1,71 @@
+import './security-restrictions';
+
+import { app } from 'electron';
+
+import { createApplicationMenu } from './application-menu/create';
+import { registerEvents } from './events';
+import { registerHandlers } from './handlers';
+import { ensureHelperProcess } from './helper-process';
+import { logger } from './logger';
+import { restoreOrCreateWindow } from './main-window';
+import { registerPlugin } from './plugin';
+import { registerProtocol } from './protocol';
+import { registerUpdater } from './updater';
+
+if (require('electron-squirrel-startup')) app.quit();
+// allow tests to overwrite app name through passing args
+if (process.argv.includes('--app-name')) {
+  const appNameIndex = process.argv.indexOf('--app-name');
+  const appName = process.argv[appNameIndex + 1];
+  app.setName(appName);
+}
+
+/**
+ * Prevent multiple instances
+ */
+const isSingleInstance = app.requestSingleInstanceLock();
+if (!isSingleInstance) {
+  logger.info('Another instance is running, exiting...');
+  app.quit();
+  process.exit(0);
+}
+
+app.on('second-instance', () => {
+  restoreOrCreateWindow().catch(e =>
+    console.error('Failed to restore or create window:', e)
+  );
+});
+
+app.on('open-url', async (_, _url) => {
+  // todo: handle `affine://...` urls
+});
+
+/**
+ * Shout down background process if all windows was closed
+ */
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});
+
+/**
+ * @see https://www.electronjs.org/docs/v14-x-y/api/app#event-activate-macos Event: 'activate'
+ */
+app.on('activate', restoreOrCreateWindow);
+
+/**
+ * Create app window when background process will be ready
+ */
+app
+  .whenReady()
+  .then(registerProtocol)
+  .then(registerHandlers)
+  .then(registerEvents)
+  .then(registerPlugin)
+  .then(ensureHelperProcess)
+  .then(restoreOrCreateWindow)
+  .then(createApplicationMenu)
+  .then()
+  .then(registerUpdater)
+  .catch(e => console.error('Failed create window:', e));

apps/electron/src/main/logger.ts

@@ -0,0 +1,14 @@
+import { shell } from 'electron';
+import log from 'electron-log';
+
+export const logger = log.scope('main');
+log.initialize();
+
+export function getLogFilePath() {
+  return log.transports.file.getFile().path;
+}
+
+export async function revealLogFile() {
+  const filePath = getLogFilePath();
+  return await shell.openPath(filePath);
+}

apps/electron/src/main/main-window.ts

@@ -0,0 +1,133 @@
+import assert from 'node:assert';
+
+import { BrowserWindow, nativeTheme } from 'electron';
+import electronWindowState from 'electron-window-state';
+import { join } from 'path';
+
+import { getExposedMeta } from './exposed';
+import { ensureHelperProcess } from './helper-process';
+import { logger } from './logger';
+import { isMacOS, isWindows } from './utils';
+
+const IS_DEV: boolean =
+  process.env.NODE_ENV === 'development' && !process.env.CI;
+
+const DEV_TOOL = process.env.DEV_TOOL === 'true';
+
+async function createWindow() {
+  logger.info('create window');
+  const mainWindowState = electronWindowState({
+    defaultWidth: 1000,
+    defaultHeight: 800,
+  });
+
+  const helperProcessManager = await ensureHelperProcess();
+  const helperExposedMeta = await helperProcessManager.rpc?.getMeta();
+
+  assert(helperExposedMeta, 'helperExposedMeta should be defined');
+
+  const mainExposedMeta = getExposedMeta();
+
+  const browserWindow = new BrowserWindow({
+    titleBarStyle: isMacOS()
+      ? 'hiddenInset'
+      : isWindows()
+      ? 'hidden'
+      : 'default',
+    trafficLightPosition: { x: 24, y: 18 },
+    x: mainWindowState.x,
+    y: mainWindowState.y,
+    width: mainWindowState.width,
+    minWidth: 640,
+    minHeight: 480,
+    visualEffectState: 'active',
+    vibrancy: 'under-window',
+    height: mainWindowState.height,
+    show: false, // Use 'ready-to-show' event to show window
+    webPreferences: {
+      webgl: true,
+      contextIsolation: true,
+      sandbox: false,
+      webviewTag: false, // The webview tag is not recommended. Consider alternatives like iframe or Electron's BrowserView. https://www.electronjs.org/docs/latest/api/webview-tag#warning
+      spellcheck: false, // FIXME: enable?
+      preload: join(__dirname, './preload.js'),
+      // serialize exposed meta that to be used in preload
+      additionalArguments: [
+        `--main-exposed-meta=` + JSON.stringify(mainExposedMeta),
+        `--helper-exposed-meta=` + JSON.stringify(helperExposedMeta),
+      ],
+    },
+  });
+
+  nativeTheme.themeSource = 'light';
+
+  mainWindowState.manage(browserWindow);
+
+  let helperConnectionUnsub: (() => void) | undefined;
+
+  /**
+   * If you install `show: true` then it can cause issues when trying to close the window.
+   * Use `show: false` and listener events `ready-to-show` to fix these issues.
+   *
+   * @see https://github.com/electron/electron/issues/25012
+   */
+  browserWindow.on('ready-to-show', () => {
+    if (IS_DEV) {
+      // do not gain focus in dev mode
+      browserWindow.showInactive();
+    } else {
+      browserWindow.show();
+    }
+    helperConnectionUnsub = helperProcessManager.connectRenderer(
+      browserWindow.webContents
+    );
+
+    logger.info('main window is ready to show');
+
+    if (DEV_TOOL) {
+      browserWindow.webContents.openDevTools({
+        mode: 'detach',
+      });
+    }
+  });
+
+  browserWindow.on('close', e => {
+    e.preventDefault();
+    browserWindow.destroy();
+    helperConnectionUnsub?.();
+    // TODO: gracefully close the app, for example, ask user to save unsaved changes
+  });
+
+  /**
+   * URL for main window.
+   */
+  const pageUrl = process.env.DEV_SERVER_URL || 'file://./index.html'; // see protocol.ts
+
+  logger.info('loading page at', pageUrl);
+
+  await browserWindow.loadURL(pageUrl);
+
+  logger.info('main window is loaded at', pageUrl);
+
+  return browserWindow;
+}
+
+// singleton
+let browserWindow: Electron.BrowserWindow | undefined;
+/**
+ * Restore existing BrowserWindow or Create new BrowserWindow
+ */
+export async function restoreOrCreateWindow() {
+  browserWindow = BrowserWindow.getAllWindows().find(w => !w.isDestroyed());
+
+  if (browserWindow === undefined) {
+    browserWindow = await createWindow();
+  }
+
+  if (browserWindow.isMinimized()) {
+    browserWindow.restore();
+    logger.info('restore main window');
+  }
+
+  return browserWindow;
+}

apps/electron/src/main/plugin.ts

@@ -0,0 +1,57 @@
+import { join, resolve } from 'node:path';
+import { Worker } from 'node:worker_threads';
+
+import { AsyncCall } from 'async-call-rpc';
+import { ipcMain } from 'electron';
+
+import { MessageEventChannel } from './utils';
+
+declare global {
+  // fixme(himself65):
+  //  remove this when bookmark block plugin is migrated to plugin-infra
+  // eslint-disable-next-line no-var
+  var asyncCall: Record<string, (...args: any) => PromiseLike<any>>;
+}
+
+export async function registerPlugin() {
+  const pluginWorkerPath = join(__dirname, './workers/plugin.worker.js');
+  const asyncCall = AsyncCall<
+    Record<string, (...args: any) => PromiseLike<any>>
+  >(
+    {},
+    {
+      channel: new MessageEventChannel(new Worker(pluginWorkerPath)),
+    }
+  );
+  globalThis.asyncCall = asyncCall;
+  await import('@toeverything/plugin-infra/manager').then(
+    ({ rootStore, affinePluginsAtom }) => {
+      const bookmarkPluginPath = join(
+        process.env.PLUGIN_DIR ?? resolve(__dirname, './plugins'),
+        './bookmark-block/index.mjs'
+      );
+      import('file://' + bookmarkPluginPath);
+      let dispose: () => void = () => {
+        // noop
+      };
+      rootStore.sub(affinePluginsAtom, () => {
+        dispose();
+        const plugins = rootStore.get(affinePluginsAtom);
+        Object.values(plugins).forEach(plugin => {
+          plugin.definition.commands.forEach(command => {
+            ipcMain.handle(command, (event, ...args) =>
+              asyncCall[command](...args)
+            );
+          });
+        });
+        dispose = () => {
+          Object.values(plugins).forEach(plugin => {
+            plugin.definition.commands.forEach(command => {
+              ipcMain.removeHandler(command);
+            });
+          });
+        };
+      });
+    }
+  );
+}

apps/electron/src/main/protocol.ts

@@ -0,0 +1,67 @@
+import { protocol, session } from 'electron';
+import { join } from 'path';
+
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: 'assets',
+    privileges: {
+      secure: false,
+      corsEnabled: true,
+      supportFetchAPI: true,
+      standard: true,
+      bypassCSP: true,
+    },
+  },
+]);
+
+function toAbsolutePath(url: string) {
+  let realpath = decodeURIComponent(url);
+  const webStaticDir = join(__dirname, '../resources/web-static');
+  if (url.startsWith('./')) {
+    // if is a file type, load the file in resources
+    if (url.split('/').at(-1)?.includes('.')) {
+      realpath = join(webStaticDir, decodeURIComponent(url));
+    } else {
+      // else, fallback to load the index.html instead
+      realpath = join(webStaticDir, 'index.html');
+    }
+  }
+  return realpath;
+}
+
+export function registerProtocol() {
+  protocol.interceptFileProtocol('file', (request, callback) => {
+    const url = request.url.replace(/^file:\/\//, '');
+    const realpath = toAbsolutePath(url);
+    callback(realpath);
+    console.log('interceptFileProtocol realpath', request.url, realpath);
+    return true;
+  });
+
+  protocol.registerFileProtocol('assets', (request, callback) => {
+    const url = request.url.replace(/^assets:\/\//, '');
+    const realpath = toAbsolutePath(url);
+    callback(realpath);
+    return true;
+  });
+
+  session.defaultSession.webRequest.onHeadersReceived(
+    (responseDetails, callback) => {
+      const { responseHeaders } = responseDetails;
+      if (responseHeaders) {
+        delete responseHeaders['access-control-allow-origin'];
+        delete responseHeaders['access-control-allow-methods'];
+        responseHeaders['Access-Control-Allow-Origin'] = ['*'];
+        responseHeaders['Access-Control-Allow-Methods'] = [
+          'GET',
+          'POST',
+          'PUT',
+          'DELETE',
+          'OPTIONS',
+        ];
+      }
+
+      callback({ responseHeaders });
+    }
+  );
+}

apps/electron/src/main/security-restrictions.ts

@@ -0,0 +1,43 @@
+import { app, shell } from 'electron';
+
+app.on('web-contents-created', (_, contents) => {
+  /**
+   * Block navigation to origins not on the allowlist.
+   *
+   * Navigation is a common attack vector. If an attacker can convince the app to navigate away
+   * from its current page, they can possibly force the app to open web sites on the Internet.
+   *
+   * @see https://www.electronjs.org/docs/latest/tutorial/security#13-disable-or-limit-navigation
+   */
+  contents.on('will-navigate', (event, url) => {
+    if (
+      (process.env.DEV_SERVER_URL &&
+        url.startsWith(process.env.DEV_SERVER_URL)) ||
+      url.startsWith('affine://') ||
+      url.startsWith('file://.')
+    ) {
+      return;
+    }
+    // Prevent navigation
+    event.preventDefault();
+    shell.openExternal(url).catch(console.error);
+  });
+
+  /**
+   * Hyperlinks to allowed sites open in the default browser.
+   *
+   * The creation of new `webContents` is a common attack vector. Attackers attempt to convince the app to create new windows,
+   * frames, or other renderer processes with more privileges than they had before; or with pages opened that they couldn't open before.
+   * You should deny any unexpected window creation.
+   *
+   * @see https://www.electronjs.org/docs/latest/tutorial/security#14-disable-or-limit-creation-of-new-windows
+   * @see https://www.electronjs.org/docs/latest/tutorial/security#15-do-not-use-openexternal-with-untrusted-content
+   */
+  contents.setWindowOpenHandler(({ url }) => {
+    // Open default browser
+    shell.openExternal(url).catch(console.error);
+
+    // Prevent creating new window in application
+    return { action: 'deny' };
+  });
+});

apps/electron/src/main/type.ts

@@ -0,0 +1,10 @@
+export type MainEventRegister = (...args: any[]) => () => void;
+
+export type IsomorphicHandler = (
+  e: Electron.IpcMainInvokeEvent,
+  ...args: any[]
+) => Promise<any>;
+
+export type NamespaceHandlers = {
+  [key: string]: IsomorphicHandler;
+};

apps/electron/src/main/ui/google-auth.ts

@@ -0,0 +1,60 @@
+import { app, BrowserWindow, shell } from 'electron';
+import { parse } from 'url';
+
+import { logger } from '../logger';
+
+const redirectUri = 'https://affine.pro/client/auth-callback';
+
+export const oauthEndpoint = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${process.env.AFFINE_GOOGLE_CLIENT_ID}&redirect_uri=${redirectUri}&response_type=code&scope=openid https://www.googleapis.com/auth/userinfo.email profile&access_type=offline&customParameters={"prompt":"select_account"}`;
+
+const tokenEndpoint = 'https://oauth2.googleapis.com/token';
+
+export const getExchangeTokenParams = (code: string) => {
+  const postData = {
+    code,
+    client_id: process.env.AFFINE_GOOGLE_CLIENT_ID || '',
+    client_secret: process.env.AFFINE_GOOGLE_CLIENT_SECRET || '',
+    redirect_uri: redirectUri,
+    grant_type: 'authorization_code',
+  };
+  const requestInit: RequestInit = {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams(postData).toString(),
+  };
+  return { requestInit, url: tokenEndpoint };
+};
+
+export function getGoogleOauthCode() {
+  return new Promise<ReturnType<typeof getExchangeTokenParams>>(
+    (resolve, reject) => {
+      shell.openExternal(oauthEndpoint).catch(e => {
+        logger.error('Failed to open external url', e);
+        reject(e);
+      });
+      const handleOpenUrl = async (_: any, url: string) => {
+        const mainWindow = BrowserWindow.getAllWindows().find(
+          w => !w.isDestroyed()
+        );
+        const urlObj = parse(url.replace('??', '?'), true);
+        if (!mainWindow || !url.startsWith('affine://auth-callback')) return;
+        const code = urlObj.query['code'] as string;
+        if (!code) return;
+
+        logger.info('google sign in code received from callback', code);
+
+        app.removeListener('open-url', handleOpenUrl);
+        resolve(getExchangeTokenParams(code));
+      };
+
+      app.on('open-url', handleOpenUrl);
+
+      setTimeout(() => {
+        reject(new Error('Timed out'));
+        app.removeListener('open-url', handleOpenUrl);
+      }, 30000);
+    }
+  );
+}

apps/electron/src/main/ui/index.ts

@@ -0,0 +1,50 @@
+import { app, BrowserWindow, nativeTheme } from 'electron';
+
+import type { NamespaceHandlers } from '../type';
+import { isMacOS } from '../utils';
+import { getGoogleOauthCode } from './google-auth';
+
+export const uiHandlers = {
+  handleThemeChange: async (_, theme: (typeof nativeTheme)['themeSource']) => {
+    nativeTheme.themeSource = theme;
+  },
+  handleSidebarVisibilityChange: async (_, visible: boolean) => {
+    if (isMacOS()) {
+      const windows = BrowserWindow.getAllWindows();
+      windows.forEach(w => {
+        // hide window buttons when sidebar is not visible
+        w.setWindowButtonVisibility(visible);
+      });
+    }
+  },
+  handleMinimizeApp: async () => {
+    const windows = BrowserWindow.getAllWindows();
+    windows.forEach(w => {
+      w.minimize();
+    });
+  },
+  handleMaximizeApp: async () => {
+    const windows = BrowserWindow.getAllWindows();
+    windows.forEach(w => {
+      if (w.isMaximized()) {
+        w.unmaximize();
+      } else {
+        w.maximize();
+      }
+    });
+  },
+  handleCloseApp: async () => {
+    app.quit();
+  },
+  getGoogleOauthCode: async () => {
+    return getGoogleOauthCode();
+  },
+  /**
+   * @deprecated Remove this when bookmark block plugin is migrated to plugin-infra
+   */
+  getBookmarkDataByLink: async (_, link: string) => {
+    return globalThis.asyncCall[
+      'com.blocksuite.bookmark-block.get-bookmark-data-by-link'
+    ](link);
+  },
+} satisfies NamespaceHandlers;

apps/electron/src/main/updater/electron-updater.ts

@@ -0,0 +1,103 @@
+import { app } from 'electron';
+import type { AppUpdater } from 'electron-updater';
+import { z } from 'zod';
+
+import { logger } from '../logger';
+import { isMacOS } from '../utils';
+import { updaterSubjects } from './event';
+
+export const ReleaseTypeSchema = z.enum([
+  'stable',
+  'beta',
+  'canary',
+  'internal',
+]);
+
+export const envBuildType = (process.env.BUILD_TYPE || 'canary')
+  .trim()
+  .toLowerCase();
+export const buildType = ReleaseTypeSchema.parse(envBuildType);
+const mode = process.env.NODE_ENV;
+const isDev = mode === 'development';
+
+let _autoUpdater: AppUpdater | null = null;
+
+export const quitAndInstall = async () => {
+  _autoUpdater?.quitAndInstall();
+};
+
+let lastCheckTime = 0;
+export const checkForUpdatesAndNotify = async (force = true) => {
+  if (!_autoUpdater) {
+    return void 0;
+  }
+  // check every 30 minutes (1800 seconds) at most
+  if (force || lastCheckTime + 1000 * 1800 < Date.now()) {
+    lastCheckTime = Date.now();
+    return await _autoUpdater.checkForUpdatesAndNotify();
+  }
+  return void 0;
+};
+
+export const registerUpdater = async () => {
+  // so we wrap it in a function
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { autoUpdater } = require('electron-updater');
+
+  _autoUpdater = autoUpdater;
+
+  // skip auto update in dev mode
+  if (!_autoUpdater || isDev) {
+    return;
+  }
+
+  // TODO: support auto update on windows and linux
+  const allowAutoUpdate = isMacOS();
+
+  _autoUpdater.autoDownload = false;
+  _autoUpdater.allowPrerelease = buildType !== 'stable';
+  _autoUpdater.autoInstallOnAppQuit = false;
+  _autoUpdater.autoRunAppAfterInstall = true;
+  _autoUpdater.setFeedURL({
+    channel: buildType,
+    provider: 'github',
+    repo: buildType !== 'internal' ? 'AFFiNE' : 'AFFiNE-Releases',
+    owner: 'toeverything',
+    releaseType: buildType === 'stable' ? 'release' : 'prerelease',
+  });
+
+  // register events for checkForUpdatesAndNotify
+  _autoUpdater.on('update-available', info => {
+    if (allowAutoUpdate) {
+      _autoUpdater?.downloadUpdate().catch(e => {
+        logger.error('Failed to download update', e);
+      });
+      logger.info('Update available, downloading...', info);
+    }
+    updaterSubjects.updateAvailable.next({
+      version: info.version,
+      allowAutoUpdate,
+    });
+  });
+  _autoUpdater.on('download-progress', e => {
+    logger.info(`Download progress: ${e.percent}`);
+    updaterSubjects.downloadProgress.next(e.percent);
+  });
+  _autoUpdater.on('update-downloaded', e => {
+    updaterSubjects.updateReady.next({
+      version: e.version,
+      allowAutoUpdate,
+    });
+    // I guess we can skip it?
+    // updaterSubjects.clientDownloadProgress.next(100);
+    logger.info('Update downloaded, ready to install');
+  });
+  _autoUpdater.on('error', e => {
+    logger.error('Error while updating client', e);
+  });
+  _autoUpdater.forceDevUpdateConfig = isDev;
+
+  app.on('activate', async () => {
+    await checkForUpdatesAndNotify(false);
+  });
+};

apps/electron/src/main/updater/event.ts

@@ -0,0 +1,36 @@
+import { BehaviorSubject, Subject } from 'rxjs';
+
+import type { MainEventRegister } from '../type';
+
+export interface UpdateMeta {
+  version: string;
+  allowAutoUpdate: boolean;
+}
+
+export const updaterSubjects = {
+  // means it is ready for restart and install the new version
+  updateAvailable: new Subject<UpdateMeta>(),
+  updateReady: new Subject<UpdateMeta>(),
+  downloadProgress: new BehaviorSubject<number>(0),
+};
+
+export const updaterEvents = {
+  onUpdateAvailable: (fn: (versionMeta: UpdateMeta) => void) => {
+    const sub = updaterSubjects.updateAvailable.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+  onUpdateReady: (fn: (versionMeta: UpdateMeta) => void) => {
+    const sub = updaterSubjects.updateReady.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+  onDownloadProgress: (fn: (progress: number) => void) => {
+    const sub = updaterSubjects.downloadProgress.subscribe(fn);
+    return () => {
+      sub.unsubscribe();
+    };
+  },
+} satisfies Record<string, MainEventRegister>;

apps/electron/src/main/updater/index.ts

@@ -0,0 +1,18 @@
+import { app } from 'electron';
+
+import type { NamespaceHandlers } from '../type';
+import { checkForUpdatesAndNotify, quitAndInstall } from './electron-updater';
+
+export const updaterHandlers = {
+  currentVersion: async () => {
+    return app.getVersion();
+  },
+  quitAndInstall: async () => {
+    return quitAndInstall();
+  },
+  checkForUpdatesAndNotify: async () => {
+    return checkForUpdatesAndNotify(true);
+  },
+} satisfies NamespaceHandlers;
+
+export * from './electron-updater';

apps/electron/src/main/utils.ts

@@ -0,0 +1,40 @@
+import type { EventBasedChannel } from 'async-call-rpc';
+
+export function getTime() {
+  return new Date().getTime();
+}
+
+export const isMacOS = () => {
+  return process.platform === 'darwin';
+};
+
+export const isWindows = () => {
+  return process.platform === 'win32';
+};
+
+interface MessagePortLike {
+  postMessage: (data: unknown) => void;
+  addListener: (event: 'message', listener: (...args: any[]) => void) => void;
+  removeListener: (
+    event: 'message',
+    listener: (...args: any[]) => void
+  ) => void;
+}
+
+export class MessageEventChannel implements EventBasedChannel {
+  constructor(private worker: MessagePortLike) {}
+
+  on(listener: (data: unknown) => void) {
+    const f = (data: unknown) => {
+      listener(data);
+    };
+    this.worker.addListener('message', f);
+    return () => {
+      this.worker.removeListener('message', f);
+    };
+  }
+
+  send(data: unknown) {
+    this.worker.postMessage(data);
+  }
+}

apps/electron/src/main/workers/plugin.worker.ts

@@ -0,0 +1,43 @@
+import { join, resolve } from 'node:path';
+import { parentPort } from 'node:worker_threads';
+
+import { AsyncCall } from 'async-call-rpc';
+
+import { MessageEventChannel } from '../utils';
+
+const commandProxy: Record<string, (...args: any[]) => Promise<any>> = {};
+
+if (!parentPort) {
+  throw new Error('parentPort is undefined');
+}
+
+AsyncCall(commandProxy, {
+  channel: new MessageEventChannel(parentPort),
+});
+
+import('@toeverything/plugin-infra/manager').then(
+  ({ rootStore, affinePluginsAtom }) => {
+    const bookmarkPluginPath = join(
+      process.env.PLUGIN_DIR ?? resolve(__dirname, '../plugins'),
+      './bookmark-block/index.mjs'
+    );
+
+    import('file://' + bookmarkPluginPath);
+    rootStore.sub(affinePluginsAtom, () => {
+      const plugins = rootStore.get(affinePluginsAtom);
+      Object.values(plugins).forEach(plugin => {
+        if (plugin.serverAdapter) {
+          plugin.serverAdapter({
+            registerCommand: (command, fn) => {
+              console.log('register command', command);
+              commandProxy[command] = fn;
+            },
+            unregisterCommand: command => {
+              delete commandProxy[command];
+            },
+          });
+        }
+      });
+    });
+  }
+);

apps/electron/src/preload/affine-apis.ts

@@ -0,0 +1,193 @@
+// NOTE: we will generate preload types from this file
+import { AsyncCall, type EventBasedChannel } from 'async-call-rpc';
+import { ipcRenderer } from 'electron';
+import { Subject } from 'rxjs';
+
+type ExposedMeta = {
+  handlers: [namespace: string, handlerNames: string[]][];
+  events: [namespace: string, eventNames: string[]][];
+};
+
+export function getAffineAPIs() {
+  const mainAPIs = getMainAPIs();
+  const helperAPIs = getHelperAPIs();
+
+  return {
+    apis: {
+      ...mainAPIs.apis,
+      ...helperAPIs.apis,
+    },
+    events: {
+      ...mainAPIs.events,
+      ...helperAPIs.events,
+    },
+  };
+}
+
+export const appInfo = {
+  electron: true,
+};
+
+function getMainAPIs() {
+  const meta: ExposedMeta = (() => {
+    const val = process.argv
+      .find(arg => arg.startsWith('--main-exposed-meta='))
+      ?.split('=')[1];
+
+    return val ? JSON.parse(val) : null;
+  })();
+
+  // main handlers that can be invoked from the renderer process
+  const apis: any = (() => {
+    const { handlers: handlersMeta } = meta;
+
+    const all = handlersMeta.map(([namespace, functionNames]) => {
+      const namespaceApis = functionNames.map(name => {
+        const channel = `${namespace}:${name}`;
+        return [
+          name,
+          (...args: any[]) => {
+            return ipcRenderer.invoke(channel, ...args);
+          },
+        ];
+      });
+      return [namespace, Object.fromEntries(namespaceApis)];
+    });
+
+    return Object.fromEntries(all);
+  })();
+
+  // main events that can be listened to from the renderer process
+  const events: any = (() => {
+    const { events: eventsMeta } = meta;
+
+    // NOTE: ui may try to listen to a lot of the same events, so we increase the limit...
+    ipcRenderer.setMaxListeners(100);
+
+    const all = eventsMeta.map(([namespace, eventNames]) => {
+      const namespaceEvents = eventNames.map(name => {
+        const channel = `${namespace}:${name}`;
+        return [
+          name,
+          (callback: (...args: any[]) => void) => {
+            const fn: (
+              event: Electron.IpcRendererEvent,
+              ...args: any[]
+            ) => void = (_, ...args) => {
+              callback(...args);
+            };
+            ipcRenderer.on(channel, fn);
+            return () => {
+              ipcRenderer.off(channel, fn);
+            };
+          },
+        ];
+      });
+      return [namespace, Object.fromEntries(namespaceEvents)];
+    });
+    return Object.fromEntries(all);
+  })();
+
+  return { apis, events };
+}
+
+const helperPort$ = new Promise<MessagePort>(resolve =>
+  ipcRenderer.on('helper-connection', async e => {
+    console.info('[preload] helper-connection', e);
+    resolve(e.ports[0]);
+  })
+);
+
+const createMessagePortChannel = (port: MessagePort): EventBasedChannel => {
+  return {
+    on(listener) {
+      port.onmessage = e => {
+        listener(e.data);
+      };
+      port.start();
+      return () => {
+        port.onmessage = null;
+        port.close();
+      };
+    },
+    send(data) {
+      port.postMessage(data);
+    },
+  };
+};
+
+function getHelperAPIs() {
+  const events$ = new Subject<{ channel: string; args: any[] }>();
+  const meta: ExposedMeta = (() => {
+    const val = process.argv
+      .find(arg => arg.startsWith('--helper-exposed-meta='))
+      ?.split('=')[1];
+
+    return val ? JSON.parse(val) : null;
+  })();
+
+  const rendererToHelperServer: PeersAPIs.RendererToHelper = {
+    postEvent: (channel, ...args) => {
+      events$.next({ channel, args });
+    },
+  };
+
+  const rpc = AsyncCall<PeersAPIs.HelperToRenderer>(rendererToHelperServer, {
+    channel: helperPort$.then(helperPort =>
+      createMessagePortChannel(helperPort)
+    ),
+    log: false,
+  });
+
+  const toHelperHandler = (namespace: string, name: string) => {
+    return rpc[`${namespace}:${name}`];
+  };
+
+  const toHelperEventSubscriber = (namespace: string, name: string) => {
+    return (callback: (...args: any[]) => void) => {
+      const subscription = events$.subscribe(({ channel, args }) => {
+        if (channel === `${namespace}:${name}`) {
+          callback(...args);
+        }
+      });
+      return () => {
+        subscription.unsubscribe();
+      };
+    };
+  };
+
+  const setup = (meta: ExposedMeta) => {
+    const { handlers: handlersMeta, events: eventsMeta } = meta;
+
+    const helperHandlers = Object.fromEntries(
+      handlersMeta.map(([namespace, functionNames]) => {
+        return [
+          namespace,
+          Object.fromEntries(
+            functionNames.map(name => {
+              return [name, toHelperHandler(namespace, name)];
+            })
+          ),
+        ];
+      })
+    );
+
+    const helperEvents = Object.fromEntries(
+      eventsMeta.map(([namespace, eventNames]) => {
+        return [
+          namespace,
+          Object.fromEntries(
+            eventNames.map(name => {
+              return [name, toHelperEventSubscriber(namespace, name)];
+            })
+          ),
+        ];
+      })
+    );
+    return [helperHandlers, helperEvents];
+  };
+
+  const [apis, events] = setup(meta);
+
+  return { apis, events };
+}

apps/electron/src/preload/bootstrap.ts

@@ -0,0 +1,53 @@
+import { contextBridge, ipcRenderer } from 'electron';
+
+(async () => {
+  const { appInfo, getAffineAPIs } = await import('./affine-apis');
+  const { apis, events } = getAffineAPIs();
+
+  contextBridge.exposeInMainWorld('appInfo', appInfo);
+  contextBridge.exposeInMainWorld('apis', apis);
+  contextBridge.exposeInMainWorld('events', events);
+
+  // Credit to microsoft/vscode
+  const globals = {
+    ipcRenderer: {
+      send(channel: string, ...args: any[]) {
+        ipcRenderer.send(channel, ...args);
+      },
+
+      invoke(channel: string, ...args: any[]) {
+        return ipcRenderer.invoke(channel, ...args);
+      },
+
+      on(
+        channel: string,
+        listener: (event: Electron.IpcRendererEvent, ...args: any[]) => void
+      ) {
+        ipcRenderer.on(channel, listener);
+        return this;
+      },
+
+      once(
+        channel: string,
+        listener: (event: Electron.IpcRendererEvent, ...args: any[]) => void
+      ) {
+        ipcRenderer.once(channel, listener);
+        return this;
+      },
+
+      removeListener(
+        channel: string,
+        listener: (event: Electron.IpcRendererEvent, ...args: any[]) => void
+      ) {
+        ipcRenderer.removeListener(channel, listener);
+        return this;
+      },
+    },
+  };
+
+  try {
+    contextBridge.exposeInMainWorld('affine', globals);
+  } catch (error) {
+    console.error('Failed to expose affine APIs to window object!', error);
+  }
+})();

apps/electron/src/preload/index.ts

@@ -0,0 +1 @@
+import './bootstrap';

apps/electron/src/types.d.ts

@@ -0,0 +1,35 @@
+declare namespace PeersAPIs {
+  import type { app, dialog, shell } from 'electron';
+
+  interface ExposedMeta {
+    handlers: [string, string[]][];
+    events: [string, string[]][];
+  }
+
+  // render <-> helper
+  interface RendererToHelper {
+    postEvent: (channel: string, ...args: any[]) => void;
+  }
+
+  interface HelperToRenderer {
+    [key: string]: (...args: any[]) => Promise<any>;
+  }
+
+  // helper <-> main
+  interface HelperToMain {
+    getMeta: () => ExposedMeta;
+  }
+
+  type MainToHelper = Pick<
+    typeof dialog & typeof shell & typeof app,
+    | 'showOpenDialog'
+    | 'showSaveDialog'
+    | 'openExternal'
+    | 'showItemInFolder'
+    | 'getPath'
+  >;
+
+  // render <-> main
+  // these are handled via IPC
+  // TODO: fix type
+}