@dxos/echo-pipeline 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/automerge/collection-synchronizer.ts

@@ -2,20 +2,22 @@
 // Copyright 2024 DXOS.org
 //
 
-import { next as am } from '@automerge/automerge';
+import { next as A, type Heads } from '@automerge/automerge';
 import type { DocumentId, PeerId } from '@automerge/automerge-repo';
+import * as Array from 'effect/Array';
+import * as Record from 'effect/Record';
 
-import { asyncReturn, Event, scheduleTask, scheduleTaskInterval } from '@dxos/async';
-import { Resource, type Context } from '@dxos/context';
+import { Event, asyncReturn, scheduleTask, scheduleTaskInterval } from '@dxos/async';
+import { type Context, Resource } from '@dxos/context';
 import { log } from '@dxos/log';
 import { trace } from '@dxos/tracing';
 import { defaultMap } from '@dxos/util';
 
 const MIN_QUERY_INTERVAL = 5_000;
 
-const POLL_INTERVAL = 30_000;
+const POLL_INTERVAL = 10_000;
 
-export type CollectionSynchronizerParams = {
+export type CollectionSynchronizerProps = {
   sendCollectionState: (collectionId: string, peerId: PeerId, state: CollectionState) => void;
   queryCollectionState: (collectionId: string, peerId: PeerId) => void;
   shouldSyncCollection: (collectionId: string, peerId: PeerId) => boolean;
@@ -24,11 +26,11 @@ export type CollectionSynchronizerParams = {
 /**
  * Implements collection sync protocol.
  */
-@trace.resource()
+@trace.resource({ lifecycle: true })
 export class CollectionSynchronizer extends Resource {
-  private readonly _sendCollectionState: CollectionSynchronizerParams['sendCollectionState'];
-  private readonly _queryCollectionState: CollectionSynchronizerParams['queryCollectionState'];
-  private readonly _shouldSyncCollection: CollectionSynchronizerParams['shouldSyncCollection'];
+  private readonly _sendCollectionState: CollectionSynchronizerProps['sendCollectionState'];
+  private readonly _queryCollectionState: CollectionSynchronizerProps['queryCollectionState'];
+  private readonly _shouldSyncCollection: CollectionSynchronizerProps['shouldSyncCollection'];
 
   /**
    * CollectionId -> State.
@@ -40,7 +42,7 @@ export class CollectionSynchronizer extends Resource {
 
   public readonly remoteStateUpdated = new Event<{ collectionId: string; peerId: PeerId; newDocsAppeared: boolean }>();
 
-  constructor(params: CollectionSynchronizerParams) {
+  constructor(params: CollectionSynchronizerProps) {
     super();
     this._sendCollectionState = params.sendCollectionState;
     this._queryCollectionState = params.queryCollectionState;
@@ -74,13 +76,29 @@ export class CollectionSynchronizer extends Resource {
     this._activeCollections.add(collectionId);
 
     log('setLocalCollectionState', { collectionId, state });
-    this._getOrCreatePerCollectionState(collectionId).localState = state;
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    perCollectionState.localState = state;
 
-    queueMicrotask(async () => {
-      if (!this._ctx.disposed && this._activeCollections.has(collectionId)) {
-        this._refreshInterestedPeers(collectionId);
-        this.refreshCollection(collectionId);
-      }
+    for (const peerId of this._connectedPeers) {
+      this._diffCollectionState(collectionId, peerId);
+    }
+
+    this._scheduleBroadcast(collectionId);
+  }
+
+  /**
+   * Coalesce bursts of `setLocalCollectionState` (e.g. from `_onHeadsChanged` during an
+   * import) into one broadcast microtask per collection. If another call arrives while
+   * the microtask is pending, we just flag the collection dirty — the in-flight run
+   * already reads the latest `localState`. If it arrives during the run itself, we
+   * schedule exactly one follow-up.
+   */
+  private _scheduleBroadcast(collectionId: string): void {
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    queueMicrotask(() => {
+      this._refreshInterestedPeers(collectionId);
+      this._broadcastLocalState(collectionId);
+      this.refreshCollection(collectionId);
     });
   }
 
@@ -117,10 +135,14 @@ export class CollectionSynchronizer extends Resource {
    * Callback when a connection to a peer is established.
    */
   onConnectionOpen(peerId: PeerId): void {
-    const spanId = getSpanName(peerId);
-    trace.spanStart({
+    log('onConnectionOpen', { peerId });
+    const spanId = getSpanId(peerId);
+    // Browser-timeline-only span; the derived ctx is intentionally discarded because
+    // the downstream `_queryCollectionState` hop is user-supplied callback land with
+    // no ctx plumbing.
+    void trace.spanStart({
       id: spanId,
-      methodName: spanId,
+      methodName: SYNC_SPAN_METHOD,
       instance: this,
       parentCtx: this._ctx,
       showInBrowserTimeline: true,
@@ -146,6 +168,8 @@ export class CollectionSynchronizer extends Resource {
    * Callback when a connection to a peer is closed.
    */
   onConnectionClosed(peerId: PeerId): void {
+    log('onConnectionClosed', { peerId });
+
     this._connectedPeers.delete(peerId);
 
     for (const perCollectionState of this._perCollectionStates.values()) {
@@ -155,6 +179,9 @@ export class CollectionSynchronizer extends Resource {
 
   /**
    * Callback when a peer queries the state of a collection.
+   *
+   * If we have no local state yet we silently drop the query; the peer will receive our
+   * state via {@link _broadcastLocalState} once `setLocalCollectionState` is called.
    */
   onCollectionStateQueried(collectionId: string, peerId: PeerId): void {
     const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
@@ -171,24 +198,48 @@ export class CollectionSynchronizer extends Resource {
     log('onRemoteStateReceived', { collectionId, peerId, state });
     validateCollectionState(state);
     const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
-    const existingState = perCollectionState.remoteStates.get(peerId) ?? { documents: {} };
-    const diff = diffCollectionState(existingState, state);
-    const spanId = getSpanName(peerId);
+    perCollectionState.remoteStates.set(peerId, state);
+    this._diffCollectionState(collectionId, peerId);
+  }
+
+  private _diffCollectionState(collectionId: string, peerId: PeerId) {
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    const remoteState = perCollectionState.remoteStates.get(peerId);
+    if (!remoteState) {
+      return;
+    }
+
+    log('diffCollectionState', { collectionId, peerId });
+    const localState = perCollectionState.localState ?? { documents: {} };
+    const diff = diffCollectionState(localState, remoteState);
+    const spanId = getSpanId(peerId);
     if (diff.different.length === 0) {
       trace.spanEnd(spanId);
     } else {
-      trace.spanStart({
+      // Browser-timeline-only span; see note in onConnectionOpen.
+      void trace.spanStart({
         id: spanId,
-        methodName: spanId,
+        methodName: SYNC_SPAN_METHOD,
         instance: this,
         parentCtx: this._ctx,
         showInBrowserTimeline: true,
         attributes: { peerId },
       });
     }
-    if (diff.missingOnLocal.length > 0 || diff.different.length > 0) {
-      perCollectionState.remoteStates.set(peerId, state);
-      this.remoteStateUpdated.emit({ peerId, collectionId, newDocsAppeared: diff.missingOnLocal.length > 0 });
+    log('diff', {
+      localState: localState.documents,
+      remoteState: remoteState.documents,
+      missingOnLocal: diff.missingOnLocal,
+      missingOnRemote: diff.missingOnRemote,
+      different: diff.different,
+    });
+    if (diff.missingOnLocal.length > 0 || diff.different.length > 0 || diff.missingOnRemote.length > 0) {
+      log('emit remote state update');
+      this.remoteStateUpdated.emit({
+        peerId,
+        collectionId,
+        newDocsAppeared: diff.missingOnLocal.length > 0,
+      });
     }
   }
 
@@ -198,9 +249,35 @@ export class CollectionSynchronizer extends Resource {
       remoteStates: new Map(),
       interestedPeers: new Set(),
       lastQueried: new Map(),
+      lastBroadcast: new Map(),
     }));
   }
 
+  /**
+   * Push local state to interested peers whose last-known remote state differs from local
+   * (or is unknown), then pull from peers via {@link refreshCollection}.
+   *
+   * Diff-gating avoids spamming peers that are already in sync; this matters because
+   * {@link setLocalCollectionState} is called on every local heads change.
+   */
+  private _broadcastLocalState(collectionId: string): void {
+    if (this._ctx.disposed || !this._activeCollections.has(collectionId)) {
+      return;
+    }
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    const localState = perCollectionState.localState;
+    if (!localState) {
+      return;
+    }
+    for (const peerId of perCollectionState.interestedPeers) {
+      const lastBroadcast = perCollectionState.lastBroadcast.get(peerId) ?? 0;
+      if (Date.now() - lastBroadcast > MIN_QUERY_INTERVAL) {
+        perCollectionState.lastBroadcast.set(peerId, Date.now());
+        this._sendCollectionState(collectionId, peerId, localState);
+      }
+    }
+  }
+
   private _refreshInterestedPeers(collectionId: string): void {
     for (const peerId of this._connectedPeers) {
       if (this._shouldSyncCollection(collectionId, peerId)) {
@@ -217,13 +294,14 @@ type PerCollectionState = {
   remoteStates: Map<PeerId, CollectionState>;
   interestedPeers: Set<PeerId>;
   lastQueried: Map<PeerId, number>;
+  lastBroadcast: Map<PeerId, number>;
 };
 
 export type CollectionState = {
   /**
    * DocumentId -> Heads.
    */
-  documents: Record<string, string[]>;
+  documents: Record<DocumentId, Heads>;
 };
 
 export type CollectionStateDiff = {
@@ -233,18 +311,21 @@ export type CollectionStateDiff = {
 };
 
 export const diffCollectionState = (local: CollectionState, remote: CollectionState): CollectionStateDiff => {
-  const allDocuments = new Set<DocumentId>([...Object.keys(local.documents), ...Object.keys(remote.documents)] as any);
+  const localDocuments = Record.filter(local.documents, (heads) => heads.length > 0);
+  const remoteDocuments = Record.filter(remote.documents, (heads) => heads.length > 0);
+  // NOTE: Using `Array.union` is slow.
+  const allDocuments = [...new Set([...Record.keys(localDocuments), ...Record.keys(remoteDocuments)])] as DocumentId[];
 
   const missingOnRemote: DocumentId[] = [];
   const missingOnLocal: DocumentId[] = [];
   const different: DocumentId[] = [];
   for (const documentId of allDocuments) {
-    if (!local.documents[documentId]) {
-      missingOnLocal.push(documentId as DocumentId);
-    } else if (!remote.documents[documentId]) {
-      missingOnRemote.push(documentId as DocumentId);
-    } else if (!am.equals(local.documents[documentId], remote.documents[documentId])) {
-      different.push(documentId as DocumentId);
+    if (!localDocuments[documentId]) {
+      missingOnLocal.push(documentId);
+    } else if (!remoteDocuments[documentId]) {
+      missingOnRemote.push(documentId);
+    } else if (!A.equals(local.documents[documentId], remote.documents[documentId])) {
+      different.push(documentId);
     }
   }
 
@@ -270,6 +351,8 @@ const isValidDocumentId = (documentId: DocumentId) => {
   return typeof documentId === 'string' && !documentId.includes(':');
 };
 
-const getSpanName = (peerId: PeerId) => {
+const SYNC_SPAN_METHOD = 'syncPeer';
+
+const getSpanId = (peerId: PeerId) => {
   return `collection-sync-${peerId}`;
 };

package/src/automerge/echo-data-monitor.ts

@@ -5,7 +5,7 @@
 import { type Message } from '@automerge/automerge-repo';
 
 import { type TimeAware, trace } from '@dxos/tracing';
-import { CircularBuffer, mapValues, SlidingWindowSummary, type SlidingWindowSummaryConfig } from '@dxos/util';
+import { CircularBuffer, SlidingWindowSummary, type SlidingWindowSummaryConfig, mapValues } from '@dxos/util';
 
 import { type NetworkDataMonitor } from './echo-network-adapter';
 import { type StorageAdapterDataMonitor } from './leveldb-storage-adapter';

package/src/automerge/echo-network-adapter.test.ts

@@ -2,10 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
-import { cbor, type PeerId } from '@automerge/automerge-repo';
-import { onTestFinished, describe, expect, test } from 'vitest';
+import { type PeerId, cbor } from '@automerge/automerge-repo';
+import { describe, expect, onTestFinished, test } from 'vitest';
 
-import { sleep, Trigger, waitForCondition } from '@dxos/async';
+import { Trigger, sleep, waitForCondition } from '@dxos/async';
+import { Context } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { type SyncMessage } from '@dxos/protocols/proto/dxos/mesh/teleport/automerge';
@@ -113,7 +114,7 @@ describe('EchoNetworkAdapter', () => {
     onTestFinished(async () => {
       await adapter.close();
     });
-    await adapter.addReplicator(replicator);
+    await adapter.addReplicator(Context.default(), replicator);
     return adapter;
   };
 

package/src/automerge/echo-network-adapter.ts

@@ -2,30 +2,37 @@
 // Copyright 2024 DXOS.org
 //
 
-import { NetworkAdapter, type Message, type PeerId, type PeerMetadata } from '@automerge/automerge-repo';
-
-import { synchronized, Trigger } from '@dxos/async';
-import { LifecycleState } from '@dxos/context';
+import {
+  type DocumentId,
+  type Heads,
+  type Message,
+  NetworkAdapter,
+  type PeerId,
+  type PeerMetadata,
+} from '@automerge/automerge-repo';
+
+import { Event, Trigger, synchronized } from '@dxos/async';
+import { type Context, LifecycleState } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { type PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
 import type { AutomergeProtocolMessage } from '@dxos/protocols';
 import { isNonNullable } from '@dxos/util';
 
+import { createIdFromSpaceKey } from '../common/space-id';
 import {
-  type EchoReplicator,
-  type RemoteDocumentExistenceCheckParams,
-  type ReplicatorConnection,
-  type ShouldAdvertiseParams,
-  type ShouldSyncCollectionParams,
+  type AutomergeReplicator,
+  type AutomergeReplicatorConnection,
+  type RemoteDocumentExistenceCheckProps,
+  type ShouldAdvertiseProps,
+  type ShouldSyncCollectionProps,
 } from './echo-replicator';
 import {
-  isCollectionQueryMessage,
-  isCollectionStateMessage,
   type CollectionQueryMessage,
   type CollectionStateMessage,
+  isCollectionQueryMessage,
+  isCollectionStateMessage,
 } from './network-protocol';
-import { createIdFromSpaceKey } from '../common/space-id';
 
 export interface NetworkDataMonitor {
   recordPeerConnected(peerId: string): void;
@@ -35,9 +42,9 @@ export interface NetworkDataMonitor {
   recordMessageSendingFailed(message: Message): void;
 }
 
-export type EchoNetworkAdapterParams = {
+export type EchoNetworkAdapterProps = {
   getContainingSpaceForDocument: (documentId: string) => Promise<PublicKey | null>;
-  isDocumentInRemoteCollection: (params: RemoteDocumentExistenceCheckParams) => Promise<boolean>;
+  isDocumentInRemoteCollection: (params: RemoteDocumentExistenceCheckProps) => Promise<boolean>;
   onCollectionStateQueried: (collectionId: string, peerId: PeerId) => void;
   onCollectionStateReceived: (collectionId: string, peerId: PeerId, state: unknown) => void;
   monitor?: NetworkDataMonitor;
@@ -45,16 +52,17 @@ export type EchoNetworkAdapterParams = {
 
 type ConnectionEntry = {
   isOpen: boolean;
-  connection: ReplicatorConnection;
+  connection: AutomergeReplicatorConnection;
   reader: ReadableStreamDefaultReader<AutomergeProtocolMessage>;
   writer: WritableStreamDefaultWriter<AutomergeProtocolMessage>;
+  requestedDocuments: Set<DocumentId>;
 };
 
 /**
- * Manages a set of {@link EchoReplicator} instances.
+ * Manages a set of {@link AutomergeReplicator} instances.
  */
 export class EchoNetworkAdapter extends NetworkAdapter {
-  private readonly _replicators = new Set<EchoReplicator>();
+  private readonly _replicators = new Set<AutomergeReplicator>();
   /**
    * Remote peer id -> connection.
    */
@@ -63,7 +71,9 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   private readonly _connected = new Trigger();
   private readonly _ready = new Trigger();
 
-  constructor(private readonly _params: EchoNetworkAdapterParams) {
+  public readonly documentRequested = new Event<{ documentId: DocumentId; peerId: PeerId }>();
+
+  constructor(private readonly _params: EchoNetworkAdapterProps) {
     super();
   }
 
@@ -125,13 +135,13 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   }
 
   @synchronized
-  async addReplicator(replicator: EchoReplicator): Promise<void> {
+  async addReplicator(ctx: Context, replicator: AutomergeReplicator): Promise<void> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
     invariant(this.peerId);
     invariant(!this._replicators.has(replicator));
 
     this._replicators.add(replicator);
-    await replicator.connect({
+    await replicator.connect(ctx, {
       peerId: this.peerId,
       onConnectionOpen: this._onConnectionOpen.bind(this),
       onConnectionClosed: this._onConnectionClosed.bind(this),
@@ -146,14 +156,14 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   }
 
   @synchronized
-  async removeReplicator(replicator: EchoReplicator): Promise<void> {
+  async removeReplicator(replicator: AutomergeReplicator): Promise<void> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
     invariant(this._replicators.has(replicator));
     await replicator.disconnect();
     this._replicators.delete(replicator);
   }
 
-  async shouldAdvertise(peerId: PeerId, params: ShouldAdvertiseParams): Promise<boolean> {
+  async shouldAdvertise(peerId: PeerId, params: ShouldAdvertiseProps): Promise<boolean> {
     const connection = this._connections.get(peerId);
     if (!connection) {
       return false;
@@ -162,7 +172,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     return connection.connection.shouldAdvertise(params);
   }
 
-  shouldSyncCollection(peerId: PeerId, params: ShouldSyncCollectionParams): boolean {
+  shouldSyncCollection(peerId: PeerId, params: ShouldSyncCollectionProps): boolean {
     const connection = this._connections.get(peerId);
     if (!connection) {
       return false;
@@ -203,6 +213,30 @@ export class EchoNetworkAdapter extends NetworkAdapter {
       .filter(isNonNullable);
   }
 
+  bundleSyncEnabledForPeer(peerId: PeerId): boolean {
+    const connection = this._connections.get(peerId);
+    if (!connection) {
+      return false;
+    }
+    return connection.connection.bundleSyncEnabled;
+  }
+
+  async pushBundle(ctx: Context, peerId: PeerId, bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]) {
+    const connection = this._connections.get(peerId);
+    if (!connection) {
+      throw new Error('Connection not found.');
+    }
+    return connection.connection.pushBundle!(ctx, bundle);
+  }
+
+  async pullBundle(ctx: Context, peerId: PeerId, docHeads: Record<DocumentId, Heads>) {
+    const connection = this._connections.get(peerId);
+    if (!connection) {
+      throw new Error('Connection not found.');
+    }
+    return connection.connection.pullBundle!(ctx, docHeads);
+  }
+
   private _send(message: Message): void {
     const connectionEntry = this._connections.get(message.targetId);
     if (!connectionEntry) {
@@ -225,7 +259,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
       });
   }
 
-  private _onConnectionOpen(connection: ReplicatorConnection): void {
+  private _onConnectionOpen(connection: AutomergeReplicatorConnection): void {
     log('connection opened', { peerId: connection.peerId });
     invariant(!this._connections.has(connection.peerId as PeerId));
     const connectionEntry: ConnectionEntry = {
@@ -233,6 +267,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
       connection,
       reader: connection.readable.getReader(),
       writer: connection.writable.getWriter(),
+      requestedDocuments: new Set(),
     };
 
     this._connections.set(connection.peerId as PeerId, connectionEntry);
@@ -247,7 +282,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
             break;
           }
 
-          this._onMessage(value as Message);
+          this._onMessage(connectionEntry, value as Message);
         }
       } catch (err) {
         if (connectionEntry.isOpen) {
@@ -261,7 +296,15 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._params.monitor?.recordPeerConnected(connection.peerId);
   }
 
-  private _onMessage(message: Message): void {
+  private _onMessage(connectionEntry: ConnectionEntry, message: Message): void {
+    const amMessage = message as AutomergeProtocolMessage;
+    if (amMessage.type === 'request') {
+      this.documentRequested.emit({
+        documentId: amMessage.documentId as DocumentId,
+        peerId: connectionEntry.connection.peerId as PeerId,
+      });
+    }
+
     if (isCollectionQueryMessage(message)) {
       this._params.onCollectionStateQueried(message.collectionId, message.senderId);
     } else if (isCollectionStateMessage(message)) {
@@ -272,7 +315,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._params.monitor?.recordMessageReceived(message);
   }
 
-  private _onConnectionClosed(connection: ReplicatorConnection): void {
+  private _onConnectionClosed(connection: AutomergeReplicatorConnection): void {
     log('connection closed', { peerId: connection.peerId });
     const entry = this._connections.get(connection.peerId as PeerId);
     invariant(entry);
@@ -281,8 +324,9 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this.emit('peer-disconnected', { peerId: connection.peerId as PeerId });
     this._params.monitor?.recordPeerDisconnected(connection.peerId);
 
-    void entry.reader.cancel().catch((err) => log.catch(err));
     void entry.writer.abort().catch((err) => log.catch(err));
+    void entry.reader.cancel().catch((err) => log.catch(err));
+
     this._connections.delete(connection.peerId as PeerId);
   }
 
@@ -290,7 +334,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
    * Trigger doc-synchronizer shared documents set recalculation. Happens on peer-candidate.
    * TODO(y): replace with a proper API call when sharePolicy update becomes supported by automerge-repo
    */
-  private _onConnectionAuthScopeChanged(connection: ReplicatorConnection): void {
+  private _onConnectionAuthScopeChanged(connection: AutomergeReplicatorConnection): void {
     log('Connection auth scope changed', { peerId: connection.peerId });
     const entry = this._connections.get(connection.peerId as PeerId);
     invariant(entry);
@@ -298,7 +342,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._emitPeerCandidate(connection);
   }
 
-  private _emitPeerCandidate(connection: ReplicatorConnection): void {
+  private _emitPeerCandidate(connection: AutomergeReplicatorConnection): void {
     this.emit('peer-candidate', {
       peerId: connection.peerId as PeerId,
       peerMetadata: createEchoPeerMetadata(),

package/src/automerge/echo-replicator.ts

@@ -2,14 +2,19 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type Heads } from '@automerge/automerge';
+import { type DocumentId } from '@automerge/automerge-repo';
+
+import { type Context } from '@dxos/context';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
-import type { AutomergeProtocolMessage } from '@dxos/protocols';
+import { type AutomergeProtocolMessage } from '@dxos/protocols';
 
-export interface EchoReplicator {
+// TODO(burdon): Rename AutomergeReplicator?
+export interface AutomergeReplicator {
   /**
    * Called on when replicator is added to EchoHost.
    */
-  connect(context: EchoReplicatorContext): Promise<void>;
+  connect(ctx: Context, context: AutomergeReplicatorContext): Promise<void>;
 
   /**
    * Called on when replicator is removed from EchoHost.
@@ -17,7 +22,7 @@ export interface EchoReplicator {
   disconnect(): Promise<void>;
 }
 
-export interface EchoReplicatorContext {
+export interface AutomergeReplicatorContext {
   /**
    * Our own peer id.
    */
@@ -28,16 +33,20 @@ export interface EchoReplicatorContext {
    */
   getContainingSpaceForDocument(documentId: string): Promise<PublicKey | null>;
   getContainingSpaceIdForDocument(documentId: string): Promise<SpaceId | null>;
-  isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckParams): Promise<boolean>;
 
-  onConnectionOpen(connection: ReplicatorConnection): void;
-  onConnectionClosed(connection: ReplicatorConnection): void;
-  onConnectionAuthScopeChanged(connection: ReplicatorConnection): void;
+  /**
+   * Returns false if collection sync hasn't happened yet.
+   */
+  isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckProps): Promise<boolean>;
+
+  onConnectionOpen(connection: AutomergeReplicatorConnection): void;
+  onConnectionClosed(connection: AutomergeReplicatorConnection): void;
+  onConnectionAuthScopeChanged(connection: AutomergeReplicatorConnection): void;
 }
 
-export interface ReplicatorConnection {
+export interface AutomergeReplicatorConnection {
   /**
-   * Remove peer id.
+   * Remote peer id.
    */
   get peerId(): string;
 
@@ -55,23 +64,40 @@ export interface ReplicatorConnection {
    * @returns true if the document should be advertised to this peer.
    * The remote peer can still request the document by its id bypassing this check.
    */
-  shouldAdvertise(params: ShouldAdvertiseParams): Promise<boolean>;
+  shouldAdvertise(params: ShouldAdvertiseProps): Promise<boolean>;
 
   /**
    * @returns true if the collection should be synced to this peer.
    */
-  shouldSyncCollection(params: ShouldSyncCollectionParams): boolean;
+  shouldSyncCollection(params: ShouldSyncCollectionProps): boolean;
+
+  /**
+   * Batch syncing considered enabled if AutomergeReplicatorConnection implements `pushBatch` and `pullBatch` methods.
+   * @returns true if the batch syncing is enabled.
+   */
+  get bundleSyncEnabled(): boolean;
+
+  /**
+   * Pushes the batch of documents to the remote peer.
+   */
+  pushBundle?(ctx: Context, bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]): Promise<void>;
+
+  /**
+   * Pulls the batch of documents from the remote peer.
+   */
+  // TODO(mykola): Use automerge-repo-bundles Bundle type here.
+  pullBundle?(ctx: Context, docHeads: Record<DocumentId, Heads>): Promise<Record<DocumentId, Uint8Array>>;
 }
 
-export type ShouldAdvertiseParams = {
+export type ShouldAdvertiseProps = {
   documentId: string;
 };
 
-export type ShouldSyncCollectionParams = {
+export type ShouldSyncCollectionProps = {
   collectionId: string;
 };
 
-export type RemoteDocumentExistenceCheckParams = {
+export type RemoteDocumentExistenceCheckProps = {
   peerId: string;
   documentId: string;
 };