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
import { LoroDoc } from 'loro-crdt';
import { err, ok, ResultAsync } from 'neverthrow';
import { describe, expect, it, vi } from 'vitest';
import { SyncEngine } from './engine';
import { LoroManagerError } from './manager';
import type { RawUpdate } from './shared';
import { createNoopLiveSyncSource } from './source';
import {
  MockChatter,
  MockLiveSyncSource,
  MockLoroManager,
  MockWALStore,
  makeTestWAL,
} from './testing';
import { WALSyncer } from './wal';

const emptySnapshot = () => new LoroDoc().export({ mode: 'snapshot' });

function makeAwareness() {
  return {
    local: () => undefined,
    updateLocalAwareness: vi.fn(),
    getEncodedLocalAwareness: vi.fn(() => new Uint8Array()),
    importRemoteAwareness: vi.fn(),
  } as any;
}

describe('SyncEngine', () => {
  it.each(['snapshot', 'manager'] as const)(
    'does not replace or restart a stopped owner during %s recovery',
    async (phase) => {
      const source = new MockLiveSyncSource();
      const { wal } = makeTestWAL(source);
      const manager = new MockLoroManager();
      const entered = Promise.withResolvers<void>();
      const release = Promise.withResolvers<void>();
      const snapshot = emptySnapshot();
      if (phase === 'snapshot')
        source.requestSnapshot.mockImplementationOnce(() =>
          ResultAsync.fromSafePromise(
            (async () => {
              entered.resolve();
              await release.promise;
              return snapshot;
            })()
          )
        );
      else
        manager.reset.mockImplementationOnce(async () => {
          entered.resolve();
          await release.promise;
          return ok(undefined);
        });
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live: source },
        bindings: { onRemoteState: () => {} },
      });
      engine.start();
      const resetting = engine.reset();
      await entered.promise;
      engine.stop();
      release.resolve();
      await resetting;
      expect(engine.isRunning).toBe(false);
      expect(manager.reset).toHaveBeenCalledTimes(phase === 'snapshot' ? 0 : 1);
      wal.destroy();
    }
  );
  it('does not import a queued remote packet after its document owner stops', async () => {
    const source = new MockLiveSyncSource();
    const { wal } = makeTestWAL(source);
    const manager = new MockLoroManager();
    const entered = Promise.withResolvers<void>();
    const release = Promise.withResolvers<void>();
    manager.syncToLoro.mockImplementationOnce(async () => {
      entered.resolve();
      await release.promise;
      return ok(undefined);
    });
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: () => {} },
    });
    engine.start();
    const write = engine.syncStateToLoro({});
    await entered.promise;
    source.emit({ type: 'update', update: new Uint8Array([1, 2, 3]) });
    engine.stop();
    release.resolve();
    await write;
    expect(manager.importUpdate).not.toHaveBeenCalled();
    wal.destroy();
  });
  it('registers peer id and calls onRunningChange(true) on start', () => {
    const source = new MockLiveSyncSource();
    const manager = new MockLoroManager();
    const onRunningChange = vi.fn();
    const { wal } = makeTestWAL(source);
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
      readonly: () => false,
      onRunningChange,
    });

    const started = engine.start();

    expect(started).toBe(true);
    expect(source.registerPeerId).toHaveBeenCalledWith(BigInt(1));
    expect(engine.isRunning).toBe(true);
    expect(onRunningChange).toHaveBeenCalledWith(true);
  });

  it('forwards every local update to the wal only', async () => {
    const source = new MockLiveSyncSource();
    const { wal } = makeTestWAL(source);
    const appendSpy = vi.spyOn(wal, 'append');
    const manager = new MockLoroManager();
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
    });

    engine.start();
    const update = new Uint8Array([1, 2, 3]);
    manager.triggerLocalUpdate(update);

    await vi.waitFor(() => expect(appendSpy).toHaveBeenCalledWith(update));
    expect(source.pushUpdate).not.toHaveBeenCalled();
  });

  describe('integration with WAL', () => {
    it('local edit is persisted to WAL and delivered to live', async () => {
      const live = new MockLiveSyncSource();
      const { wal, walStore } = makeTestWAL(live);
      const manager = new MockLoroManager();
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live },
        bindings: { onRemoteState: vi.fn() },
      });

      engine.start();
      const update = new Uint8Array([1, 2, 3]);
      manager.triggerLocalUpdate(update);

      await vi.waitFor(async () => {
        expect(live.pushUpdate).toHaveBeenCalledOnce();
        const entries = await walStore.getAll();
        expect(entries.every((e) => e.delivered)).toBe(true);
      });
    });

    it('local edit stays in WAL when live is down, clears on reconnect', async () => {
      const live = new MockLiveSyncSource();
      live.setPushResult(false);
      const { wal, walStore } = makeTestWAL(live);
      const manager = new MockLoroManager();
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live },
        bindings: { onRemoteState: vi.fn() },
      });

      engine.start();
      manager.triggerLocalUpdate(new Uint8Array([1, 2, 3]));
      await vi.waitFor(async () => {
        const entries = await walStore.getAll();
        expect(entries.filter((e) => !e.delivered).length).toBe(1);
      });
      await wal.pendingFlush;

      live.setPushResult(true);
      live.emit({
        type: 'reconnect',
        snapshot: emptySnapshot(),
        awareness: new Uint8Array(),
      });
      await vi.waitFor(async () => {
        const entries = await walStore.getAll();
        expect(entries.every((e) => e.delivered)).toBe(true);
      });
    });
  });

  describe('cross-replica chatter', () => {
    it('broadcasts local updates to the chatter', async () => {
      const source = new MockLiveSyncSource();
      const { wal } = makeTestWAL(source);
      const manager = new MockLoroManager();
      const chatter = new MockChatter();
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live: source },
        bindings: { onRemoteState: vi.fn() },
        makeChatter: () => chatter,
      });

      engine.start();
      const update = new Uint8Array([1, 2, 3]);
      manager.triggerLocalUpdate(update);

      await vi.waitFor(() =>
        expect(chatter.posted).toContainEqual({ type: 'update', data: update })
      );
    });

    it('applies updates received from another replica', async () => {
      const source = new MockLiveSyncSource();
      const { wal } = makeTestWAL(source);
      const manager = new MockLoroManager();
      const chatter = new MockChatter();
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live: source },
        bindings: { onRemoteState: vi.fn() },
        makeChatter: () => chatter,
      });

      engine.start();
      const update = new Uint8Array([4, 5, 6]);
      chatter.receive({ type: 'update', data: update });

      await vi.waitFor(() =>
        expect(manager.importUpdate).toHaveBeenCalledWith(update)
      );
    });

    it('stops listening to the chatter on stop', () => {
      const source = new MockLiveSyncSource();
      const { wal } = makeTestWAL(source);
      const manager = new MockLoroManager();
      const chatter = new MockChatter();
      const engine = new SyncEngine({
        loroManager: manager,
        awareness: makeAwareness(),
        syncs: { wal, live: source },
        bindings: { onRemoteState: vi.fn() },
        makeChatter: () => chatter,
      });

      engine.start();
      engine.stop();
      chatter.receive({ type: 'update', data: new Uint8Array([7]) });

      expect(chatter.closed).toBe(true);
      expect(manager.importUpdate).not.toHaveBeenCalled();
    });
  });

  it('does not start when manager is not initialized', () => {
    const source = new MockLiveSyncSource();
    const { wal } = makeTestWAL(source);
    const engine = new SyncEngine({
      loroManager: new MockLoroManager(false),
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
    });

    const started = engine.start();

    expect(started).toBe(false);
    expect(source.registerPeerId).not.toHaveBeenCalled();
  });

  it('skips convergence payloads with zero bytes (noop live source)', async () => {
    // Non-propagating AI edit sessions run the engine over a noop live
    // source whose requestUpdatesSince/requestSnapshot answer with an empty
    // Uint8Array — not a valid Loro payload. Startup convergence must skip
    // it rather than import → throw → reset in a loop.
    const live = createNoopLiveSyncSource('doc-1');
    const wal = new WALSyncer<RawUpdate>(
      new MockWALStore<RawUpdate>(),
      (updates) => live.pushUpdate(updates)
    );
    const manager = new MockLoroManager();
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live },
      bindings: { onRemoteState: vi.fn() },
    });

    engine.start();
    await new Promise((resolve) => setTimeout(resolve));

    expect(manager.importUpdate).not.toHaveBeenCalled();
    expect(manager.reset).not.toHaveBeenCalled();
    expect(engine.isRunning).toBe(true);
    engine.stop();
    wal.destroy();
  });

  it('converges instead of resetting when a remote update is causally pending', async () => {
    const source = new MockLiveSyncSource();
    const { wal } = makeTestWAL(source);
    const manager = new MockLoroManager();
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
    });

    engine.start();
    // Let the startup convergence fully settle, so the pending-triggered
    // convergence below isn't coalesced onto it.
    await new Promise((resolve) => setTimeout(resolve));

    manager.importUpdate.mockReturnValueOnce(
      err([{ code: LoroManagerError.ImportPending, message: 'pending' }])
    );
    source.emit({ type: 'update', update: new Uint8Array([9]) });

    // A pending import triggers a fresh convergence, not a reset.
    await vi.waitFor(() =>
      expect(source.requestUpdatesSince).toHaveBeenCalledTimes(2)
    );
    expect(manager.reset).not.toHaveBeenCalled();
    expect(source.requestSnapshot).not.toHaveBeenCalled();
  });

  it('runs a fresh convergence for a reconnect that arrives mid-flight', async () => {
    const source = new MockLiveSyncSource();
    const firstRequest = Promise.withResolvers<Uint8Array<ArrayBuffer>>();
    source.requestUpdatesSince.mockReturnValueOnce(
      ResultAsync.fromSafePromise(firstRequest.promise)
    );
    const { wal } = makeTestWAL(source);
    const manager = new MockLoroManager();
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
    });

    engine.start();
    expect(source.requestUpdatesSince).toHaveBeenCalledOnce();

    // Reconnect while the startup convergence is still in flight: coalesced
    // for now, but a fresh pass must follow once the in-flight one settles.
    source.emit({
      type: 'reconnect',
      snapshot: emptySnapshot(),
      awareness: new Uint8Array(),
    });
    expect(source.requestUpdatesSince).toHaveBeenCalledOnce();

    firstRequest.resolve(new Uint8Array());
    await vi.waitFor(() =>
      expect(source.requestUpdatesSince).toHaveBeenCalledTimes(2)
    );
  });

  it('does not apply a late startup convergence response after stop', async () => {
    const source = new MockLiveSyncSource();
    const pendingUpdate = Promise.withResolvers<Uint8Array<ArrayBuffer>>();
    source.requestUpdatesSince.mockReturnValueOnce(
      ResultAsync.fromSafePromise(pendingUpdate.promise)
    );
    const { wal } = makeTestWAL(source);
    const manager = new MockLoroManager();
    const engine = new SyncEngine({
      loroManager: manager,
      awareness: makeAwareness(),
      syncs: { wal, live: source },
      bindings: { onRemoteState: vi.fn() },
    });

    engine.start();
    expect(source.requestUpdatesSince).toHaveBeenCalledOnce();
    engine.stop();

    pendingUpdate.resolve(new Uint8Array([1, 2, 3]));
    await pendingUpdate.promise;
    await Promise.resolve();

    expect(manager.importUpdate).not.toHaveBeenCalled();
  });
});