@dxos/echo-pipeline 0.5.9-main.f099efe → 0.5.9-next.73dcc17

package/src/automerge/automerge-host.ts

@@ -2,10 +2,19 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Event } from '@dxos/async';
-import { next as automerge, getBackend, getHeads, type Doc, type Heads } from '@dxos/automerge/automerge';
+import { Event, asyncTimeout } from '@dxos/async';
+import {
+  next as automerge,
+  getBackend,
+  getHeads,
+  isAutomerge,
+  save,
+  type Doc,
+  type Heads,
+} from '@dxos/automerge/automerge';
 import {
   Repo,
+  type AnyDocumentId,
   type DocHandle,
   type DocHandleChangePayload,
   type DocumentId,
@@ -13,10 +22,9 @@ import {
   type StorageAdapterInterface,
 } from '@dxos/automerge/automerge-repo';
 import { type Stream } from '@dxos/codec-protobuf';
-import { Context, type Lifecycle } from '@dxos/context';
+import { Context, cancelWithContext, type Lifecycle } from '@dxos/context';
 import { type SpaceDoc } from '@dxos/echo-protocol';
 import { type IndexMetadataStore } from '@dxos/indexing';
-import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { type SublevelDB } from '@dxos/kv-store';
 import { objectPointerCodec } from '@dxos/protocols';
@@ -29,7 +37,7 @@ import {
 import { trace } from '@dxos/tracing';
 import { mapValues } from '@dxos/util';
 
-import { EchoNetworkAdapter } from './echo-network-adapter';
+import { EchoNetworkAdapter, isEchoPeerMetadata } from './echo-network-adapter';
 import { type EchoReplicator } from './echo-replicator';
 import { LevelDBStorageAdapter, type BeforeSaveParams } from './leveldb-storage-adapter';
 import { LocalHostNetworkAdapter } from './local-host-network-adapter';
@@ -43,6 +51,20 @@ export type AutomergeHostParams = {
   indexMetadataStore: IndexMetadataStore;
 };
 
+export type LoadDocOptions = {
+  timeout?: number;
+};
+
+export type CreateDocOptions = {
+  /**
+   * Import the document together with its history.
+   */
+  preserveHistory?: boolean;
+};
+
+/**
+ * Abstracts over the AutomergeRepo.
+ */
 @trace.resource()
 export class AutomergeHost {
   private readonly _indexMetadataStore: IndexMetadataStore;
@@ -102,6 +124,9 @@ export class AutomergeHost {
     await this._ctx.dispose();
   }
 
+  /**
+   * @deprecated To be abstracted away.
+   */
   get repo(): Repo {
     return this._repo;
   }
@@ -114,6 +139,46 @@ export class AutomergeHost {
     await this._echoNetworkAdapter.removeReplicator(replicator);
   }
 
+  /**
+   * Loads the document handle from the repo and waits for it to be ready.
+   */
+  async loadDoc<T>(ctx: Context, documentId: AnyDocumentId, opts?: LoadDocOptions): Promise<DocHandle<T>> {
+    let handle: DocHandle<T> | undefined;
+    if (typeof documentId === 'string') {
+      // NOTE: documentId might also be a URL, in which case this lookup will fail.
+      handle = this._repo.handles[documentId as DocumentId];
+    }
+    if (!handle) {
+      handle = this._repo.find(documentId as DocumentId);
+    }
+
+    // `whenReady` creates a timeout so we guard it with an if to skip it if the handle is already ready.
+    if (!handle.isReady()) {
+      if (!opts?.timeout) {
+        await cancelWithContext(ctx, handle.whenReady());
+      } else {
+        await cancelWithContext(ctx, asyncTimeout(handle.whenReady(), opts.timeout));
+      }
+    }
+
+    return handle;
+  }
+
+  /**
+   * Create new persisted document.
+   */
+  createDoc<T>(initialValue?: T | Doc<T>, opts?: CreateDocOptions): DocHandle<T> {
+    if (opts?.preserveHistory) {
+      if (!isAutomerge(initialValue)) {
+        throw new TypeError('Initial value must be an Automerge document');
+      }
+      // TODO(dmaretskyi): There's a more efficient way.
+      return this._repo.import(save(initialValue as Doc<T>));
+    } else {
+      return this._repo.create(initialValue);
+    }
+  }
+
   // TODO(dmaretskyi): Share based on HALO permissions and space affinity.
   // Hosts, running in the worker, don't share documents unless requested by other peers.
   // NOTE: If both peers return sharePolicy=false the replication will not happen
@@ -131,7 +196,7 @@ export class AutomergeHost {
     }
 
     const peerMetadata = this.repo.peerMetadataByPeerId[peerId];
-    if ((peerMetadata as any)?.dxos_peerSource === 'EchoNetworkAdapter') {
+    if (isEchoPeerMetadata(peerMetadata)) {
       return this._echoNetworkAdapter.shouldAdvertize(peerId, { documentId });
     }
 
@@ -212,39 +277,52 @@ export class AutomergeHost {
     return PublicKey.from(spaceKeyHex);
   }
 
-  //
-  // Methods for client-services.
-  //
+  /**
+   * Flush documents to disk.
+   */
   @trace.span({ showInBrowserTimeline: true })
   async flush({ states }: FlushRequest): Promise<void> {
     // Note: Wait for all requested documents to be loaded/synced from thin-client.
-    await Promise.all(
-      states?.map(async ({ heads, documentId }) => {
-        invariant(heads, 'heads are required for flush');
-        const handle = this.repo.handles[documentId as DocumentId] ?? this._repo.find(documentId as DocumentId);
-        await waitForHeads(handle, heads);
-      }) ?? [],
-    );
+    if (states) {
+      await Promise.all(
+        states.map(async ({ heads, documentId }) => {
+          if (!heads) {
+            return;
+          }
+          const handle = this.repo.handles[documentId as DocumentId] ?? this._repo.find(documentId as DocumentId);
+          await waitForHeads(handle, heads);
+        }) ?? [],
+      );
+    }
 
     await this._repo.flush(states?.map(({ documentId }) => documentId as DocumentId));
   }
 
+  /**
+   * Host <-> Client sync.
+   */
   syncRepo(request: SyncRepoRequest): Stream<SyncRepoResponse> {
     return this._clientNetwork.syncRepo(request);
   }
 
+  /**
+   * Host <-> Client sync.
+   */
   sendSyncMessage(request: SyncRepoRequest): Promise<void> {
     return this._clientNetwork.sendSyncMessage(request);
   }
 
+  /**
+   * Host <-> Client sync.
+   */
   async getHostInfo(): Promise<HostInfo> {
     return this._clientNetwork.getHostInfo();
   }
 }
 
-export const getSpaceKeyFromDoc = (doc: any): string | null => {
+export const getSpaceKeyFromDoc = (doc: Doc<SpaceDoc>): string | null => {
   // experimental_spaceKey is set on old documents, new ones are created with doc.access.spaceKey
-  const rawSpaceKey = doc.access?.spaceKey ?? doc.experimental_spaceKey;
+  const rawSpaceKey = doc.access?.spaceKey ?? (doc as any).experimental_spaceKey;
   if (rawSpaceKey == null) {
     return null;
   }

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

@@ -174,10 +174,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   private _emitPeerCandidate(connection: ReplicatorConnection) {
     this.emit('peer-candidate', {
       peerId: connection.peerId as PeerId,
-      peerMetadata: {
-        // TODO(dmaretskyi): Refactor this.
-        dxos_peerSource: 'EchoNetworkAdapter',
-      } as any,
+      peerMetadata: createEchoPeerMetadata(),
     });
   }
 }
@@ -188,3 +185,12 @@ type ConnectionEntry = {
   writer: WritableStreamDefaultWriter<Message>;
   isOpen: boolean;
 };
+
+export const createEchoPeerMetadata = (): PeerMetadata =>
+  ({
+    // TODO(dmaretskyi): Refactor this.
+    dxos_peerSource: 'EchoNetworkAdapter',
+  }) as any;
+
+export const isEchoPeerMetadata = (metadata: PeerMetadata): boolean =>
+  (metadata as any)?.dxos_peerSource === 'EchoNetworkAdapter';

package/src/automerge/mesh-echo-replicator.ts

@@ -63,8 +63,8 @@ export class MeshEchoReplicator implements EchoReplicator {
           this._context.onConnectionAuthScopeChanged(connection);
         } else {
           this._connectionsPerPeer.set(connection.peerId, connection);
-          await connection.enable();
           this._context.onConnectionOpen(connection);
+          await connection.enable();
         }
       },
       onRemoteDisconnected: async () => {