Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

12.9 KB
Raw Blame
/**
 * A shared Photoshop document on the sync stack: a Loro document with a
 * local snapshot, write-ahead log, live transport, and presence. The first
 * person who can edit seeds it (the entry format and nothing changed); the
 * stored `.psd` stays the base every person opens.
 */

import { fireAndForget } from '@core/util/fireAndForget';
import { schema } from '@loro-mirror/core';
import { createAwareness } from '@macro-inc/collaboration/collab/awareness';
import type { Chatter } from '@macro-inc/collaboration/collab/chatter';
import { createSyncEngine } from '@macro-inc/collaboration/collab/engine';
import { LoroManager } from '@macro-inc/collaboration/collab/manager';
import {
  IDBSnapshotStore,
  LORO_SNAPSHOT_DB_NAME,
  loadCachedState,
  type SnapshotStore,
} from '@macro-inc/collaboration/collab/snapshot-store';
import {
  type InitialSync,
  type LiveSyncSource,
  SyncError,
  type SyncSourceEvent,
  SyncSourceStatus,
} from '@macro-inc/collaboration/collab/source';
import {
  BrowserWALStore,
  LORO_WAL_DB_NAME,
  type WALStore,
  WALSyncer,
} from '@macro-inc/collaboration/collab/wal';
import { LoroDoc } from 'loro-crdt';
import { errAsync, type ResultAsync } from 'neverthrow';
import {
  type Accessor,
  createSignal,
  getOwner,
  onCleanup,
  runWithOwner,
} from 'solid-js';
import { match } from 'ts-pattern';
import type { PsdCollaboration } from '../context/psd-editor-context';
import {
  documentFormat,
  PSD_CONTAINERS,
  PSD_FORMAT_VERSION,
  seedDocument,
} from '../core/collab-entries';
import {
  isPresence,
  NOWHERE,
  type PsdPeer,
  type PsdPresence,
} from '../core/presence';

const strings = () =>
  schema.LoroMap({} as Record<string, ReturnType<typeof schema.String>>);

/** Mirror schema for the document's maps (see `PSD_CONTAINERS`). */
const PSD_LORO_SCHEMA = schema(
  Object.fromEntries(PSD_CONTAINERS.map((name) => [name, strings()]))
);

/** Presence goes out at most this often while the pointer moves. */
const PRESENCE_INTERVAL_MS = 50;

/** Awareness expires on the server; idle presence is sent again this often. */
const HEARTBEAT_MS = 3_000;

/** How long storing a file waits for the sync service to have every change. */
const DELIVERY_TIMEOUT_MS = 5_000;

export type PsdCollabState =
  | { t: 'loading' }
  | { t: 'ready'; doc: LoroDoc }
  /** Nobody who can edit has opened it yet: show the stored file. */
  | { t: 'unshared' }
  | { t: 'error'; message: string };

export type PsdConnection = {
  source: LiveSyncSource;
  doInitialSync: () => ResultAsync<InitialSync, SyncError>;
};

export interface PsdCollabOptions {
  documentId: string;
  userId?: string;
  canEdit: Accessor<boolean>;
  /** A display name for a user id. */
  displayName: (userId: string | undefined) => string;
  /** Whether the sync service already holds this document. */
  exists: () => Promise<boolean>;
  /** Stores the first snapshot. Rejects when it could not be stored. */
  initialize: (snapshot: Uint8Array) => Promise<void>;
  /** Opens the live transport. Called once, after the document exists. */
  connect: () => PsdConnection;
  persistence?: {
    snapshots: SnapshotStore<Uint8Array>;
    wal: WALStore<Uint8Array>;
    makeChatter?: (documentId: string) => Chatter;
  };
}

export interface PsdCollabSession {
  state: Accessor<PsdCollabState>;
  collaboration: PsdCollaboration;
  /**
   * Resolves once every change made here so far reached the sync service;
   * `false` when it could not be reached in time.
   */
  delivered: () => Promise<boolean>;
}

/** A write-ahead log that knows when the last local change was logged. */
class TrackedWALSyncer extends WALSyncer<Uint8Array> {
  /** Settles once the latest appended change is in the log. */
  lastAppend: Promise<void> = Promise.resolve();

  override append(update: Uint8Array): Promise<void> {
    const appended = super.append(update);
    const settled = async () => {
      try {
        await appended;
      } catch {
        // The log reports its own failures.
      }
    };
    this.lastAppend = settled();
    return appended;
  }
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

/** The first shared snapshot: the format version and nothing changed yet. */
function buildPsdSeed(): Uint8Array {
  const doc = new LoroDoc();
  seedDocument(doc);
  return doc.export({ mode: 'snapshot' });
}

export function createPsdCollabSession(
  options: PsdCollabOptions
): PsdCollabSession {
  const manager = new LoroManager(PSD_LORO_SCHEMA, {
    documentId: options.documentId,
  });
  const snapshots =
    options.persistence?.snapshots ??
    new IDBSnapshotStore<Uint8Array>(LORO_SNAPSHOT_DB_NAME, options.documentId);
  const walStore =
    options.persistence?.wal ??
    new BrowserWALStore<Uint8Array>(LORO_WAL_DB_NAME, options.documentId);
  const [state, setState] = createSignal<PsdCollabState>({ t: 'loading' });
  const [connection, setConnection] = createSignal<PsdConnection>();
  // The transport opens after async work; it still belongs to this owner.
  const owner = getOwner();
  let disposed = false;
  let started = false;

  const wal = new TrackedWALSyncer(
    walStore,
    (updates) =>
      connection()?.source.pushUpdate(updates) ?? Promise.resolve(false),
    options.documentId
  );

  const awareness = createAwareness<PsdPresence, PsdPresence>(
    manager.peerIdStr,
    options.userId,
    {
      encode: (presence) => presence,
      decode: (presence) => (isPresence(presence) ? presence : NOWHERE),
    }
  );
  let presence: PsdPresence | undefined;
  let presenceTimer: ReturnType<typeof setTimeout> | undefined;
  let lastSent = 0;
  const sendPresence = () => {
    presenceTimer = undefined;
    lastSent = Date.now();
    awareness.updateLocalAwareness(presence ?? NOWHERE);
  };
  // Awareness expires; keep an idle presence visible while connected.
  const heartbeat = setInterval(() => {
    if (
      presence &&
      connection()?.source.status() === SyncSourceStatus.Connected
    )
      sendPresence();
  }, HEARTBEAT_MS);

  // The engine starts before the transport exists when a cached copy opens
  // offline-first, so it talks to a source that forwards to the connection.
  const liveListeners = new Set<(event: SyncSourceEvent) => void>();
  let peerId: bigint | undefined;
  const notConnected = () => errAsync(SyncError.connectionFailed());
  const live: LiveSyncSource = {
    documentId: options.documentId,
    status: () => connection()?.source.status() ?? SyncSourceStatus.Connecting,
    listen: (listener) => {
      liveListeners.add(listener);
      return () => liveListeners.delete(listener);
    },
    pushUpdate: (updates) =>
      connection()?.source.pushUpdate(updates) ?? Promise.resolve(false),
    pushAwareness: (value) => connection()?.source.pushAwareness(value),
    registerPeerId: (value) => {
      peerId = value;
      connection()?.source.registerPeerId(value);
    },
    requestUpdatesSince: (version) =>
      connection()?.source.requestUpdatesSince(version) ?? notConnected(),
    requestSnapshot: () =>
      connection()?.source.requestSnapshot() ?? notConnected(),
    reconnect: () => connection()?.source.reconnect(),
    cleanup: () => connection()?.source.cleanup(),
  };

  const engine = createSyncEngine({
    loroManager: manager,
    awareness,
    syncs: { live, wal },
    // The editor reads remote changes from the document's own events.
    bindings: { onRemoteState: () => {} },
    readonly: () => !options.canEdit(),
    snapshotStore: snapshots,
    makeChatter: options.persistence?.makeChatter,
  });

  // The engine swaps its LoroDoc when it recovers from an invalid update.
  const unsubscribeManager = manager.onStateChange(() => {
    const current = state();
    if (current.t === 'ready' && current.doc !== manager.doc)
      setState({ t: 'ready', doc: manager.doc });
  });

  async function start() {
    if (disposed) return;
    const version = documentFormat(manager.doc);
    if (version === undefined) {
      setState({ t: 'error', message: 'This document is empty.' });
      return;
    }
    if (version > PSD_FORMAT_VERSION) {
      setState({
        t: 'error',
        message:
          'This document was edited by a newer version of Macro. Reload to open it.',
      });
      return;
    }
    if (!started) {
      // Persist the base before accepting edits so a crash can always replay
      // WAL entries against a valid snapshot.
      await snapshots.save(manager.doc.export({ mode: 'snapshot' }));
      if (disposed) return;
      engine.start();
      started = true;
    }
    setState({ t: 'ready', doc: manager.doc });
    if (options.canEdit()) fireAndForget(wal.flush(), 'psd-collab');
  }

  async function accept(initial: InitialSync) {
    if (initial.awareness.length)
      awareness.importRemoteAwareness(initial.awareness);
    const result = manager.initialized
      ? manager.importUpdate(initial.snapshot)
      : await manager.initializeFromSnapshot(initial.snapshot);
    if (disposed) return;
    if (result.isErr()) {
      setState({ t: 'error', message: 'This document could not be shared.' });
      return;
    }
    if (!started) await start();
  }

  /** Seeds the shared document; `false` when this viewer can't. */
  async function seed(): Promise<boolean> {
    if (!options.canEdit()) {
      setState({ t: 'unshared' });
      return false;
    }
    try {
      await options.initialize(buildPsdSeed());
    } catch (cause) {
      // Another editor may have seeded it first.
      if (!(await options.exists())) throw cause;
    }
    return true;
  }

  async function hydrate() {
    await wal.ready();
    const cached = await loadCachedState(manager, snapshots, walStore).catch(
      () => false
    );
    if (disposed) return;
    if (cached && documentFormat(manager.doc) !== undefined) await start();
    else if (!(await options.exists()) && !(await seed())) return;
    if (disposed) return;
    const opened = runWithOwner(owner, () => options.connect());
    if (!opened) return;
    setConnection(opened);
    opened.source.listen((event) => {
      for (const listener of liveListeners) listener(event);
      if (event.type === 'reconnect')
        fireAndForget(resync(event), 'psd-collab');
    });
    if (peerId !== undefined) opened.source.registerPeerId(peerId);
    const initial = await opened.doInitialSync();
    if (disposed) return;
    if (initial.isErr()) {
      if (!started)
        setState({
          t: 'error',
          message: 'Unable to connect to this document.',
        });
      return;
    }
    await accept(initial.value);
  }

  /** Takes the server's state again after a reconnect. */
  async function resync(initial: InitialSync) {
    try {
      await accept(initial);
      await wal.flush();
    } catch (cause) {
      console.error('[psd] collaboration failed to resync', cause);
      if (!disposed)
        setState({ t: 'error', message: 'This document could not be shared.' });
    }
  }

  async function open() {
    try {
      await hydrate();
    } catch (cause) {
      console.error('[psd] collaboration failed to open', cause);
      if (!disposed)
        setState({ t: 'error', message: 'Unable to share this document.' });
    }
  }
  fireAndForget(open(), 'psd-collab');

  onCleanup(() => {
    disposed = true;
    clearInterval(heartbeat);
    clearTimeout(presenceTimer);
    unsubscribeManager();
    engine.stop();
    wal.destroy();
    connection()?.source.cleanup();
    manager.dispose();
  });

  const peers = (): PsdPeer[] =>
    awareness.remote().flatMap((peer) =>
      peer.selection && peer.selection.session !== 0
        ? [
            {
              peerId: peer.user.peerId,
              userId: peer.user.userId,
              name: options.displayName(peer.user.userId),
              color: peer.user.color,
              presence: peer.selection,
            },
          ]
        : []
    );

  async function delivered(): Promise<boolean> {
    const deadline = Date.now() + DELIVERY_TIMEOUT_MS;
    // A commit logs its change at once; the log writes it asynchronously.
    await wal.lastAppend;
    while (!disposed) {
      if (connection()?.source.status() === SyncSourceStatus.Connected) {
        await wal.flush();
        if ((await wal.summary()).dirty === 0) return true;
      }
      if (Date.now() >= deadline) return false;
      await sleep(200);
    }
    return false;
  }

  return {
    state,
    delivered,
    collaboration: {
      peerId: manager.peerIdStr,
      color: () => awareness.local().user.color,
      peers,
      setPresence: (next) => {
        presence = next;
        // Pointer moves are frequent: send at most one per interval.
        if (presenceTimer !== undefined) return;
        const wait = PRESENCE_INTERVAL_MS - (Date.now() - lastSent);
        if (wait <= 0) sendPresence();
        else presenceTimer = setTimeout(sendPresence, wait);
      },
      status: () =>
        match(connection()?.source.status())
          .with(SyncSourceStatus.Connected, () => 'connected' as const)
          .with(SyncSourceStatus.Disconnected, () => 'offline' as const)
          .otherwise(() => 'connecting' as const),
    },
  };
}