@automerge/automerge-repo 2.0.0-alpha.7 → 2.0.0-beta.1

package/src/synchronizer/DocSynchronizer.ts

@@ -30,6 +30,7 @@ type PendingMessage = {
 
 interface DocSynchronizerConfig {
   handle: DocHandle<unknown>
+  peerId: PeerId
   onLoadSyncState?: (peerId: PeerId) => Promise<A.SyncState | undefined>
 }
 
@@ -56,13 +57,17 @@ export class DocSynchronizer extends Synchronizer {
 
   #pendingSyncMessages: Array<PendingMessage> = []
 
+  // We keep this around at least in part for debugging.
+  // eslint-disable-next-line no-unused-private-class-members
+  #peerId: PeerId
   #syncStarted = false
 
   #handle: DocHandle<unknown>
   #onLoadSyncState: (peerId: PeerId) => Promise<A.SyncState | undefined>
 
-  constructor({ handle, onLoadSyncState }: DocSynchronizerConfig) {
+  constructor({ handle, peerId, onLoadSyncState }: DocSynchronizerConfig) {
     super()
+    this.#peerId = peerId
     this.#handle = handle
     this.#onLoadSyncState =
       onLoadSyncState ?? (() => Promise.resolve(undefined))
@@ -81,7 +86,6 @@ export class DocSynchronizer extends Synchronizer {
 
     // Process pending sync messages immediately after the handle becomes ready.
     void (async () => {
-      await handle.doc([READY, REQUESTING])
       this.#processAllPendingSyncMessages()
     })()
   }
@@ -97,10 +101,13 @@ export class DocSynchronizer extends Synchronizer {
   /// PRIVATE
 
   async #syncWithPeers() {
-    this.#log(`syncWithPeers`)
-    const doc = await this.#handle.doc()
-    if (doc === undefined) return
-    this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    try {
+      await this.#handle.whenReady()
+      const doc = this.#handle.doc() // XXX THIS ONE IS WEIRD
+      this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    } catch (e) {
+      console.log("sync with peers threw an exception")
+    }
   }
 
   async #broadcastToPeers({
@@ -226,32 +233,26 @@ export class DocSynchronizer extends Synchronizer {
     return this.#peers.includes(peerId)
   }
 
-  beginSync(peerIds: PeerId[]) {
-    const noPeersWithDocument = peerIds.every(
-      peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
-    )
-
-    // At this point if we don't have anything in our storage, we need to use an empty doc to sync
-    // with; but we don't want to surface that state to the front end
-
-    const docPromise = this.#handle
-      .doc([READY, REQUESTING, UNAVAILABLE])
-      .then(doc => {
-        // we register out peers first, then say that sync has started
+  async beginSync(peerIds: PeerId[]) {
+    void this.#handle
+      .whenReady([READY, REQUESTING, UNAVAILABLE])
+      .then(() => {
+        this.#syncStarted = true
+        this.#checkDocUnavailable()
+      })
+      .catch(e => {
+        console.log("caught whenready", e)
         this.#syncStarted = true
         this.#checkDocUnavailable()
-
-        const wasUnavailable = doc === undefined
-        if (wasUnavailable && noPeersWithDocument) {
-          return
-        }
-
-        // If the doc is unavailable we still need a blank document to generate
-        // the sync message from
-        return doc ?? A.init<unknown>()
       })
 
-    this.#log(`beginSync: ${peerIds.join(", ")}`)
+    const peersWithDocument = this.#peers.some(peerId => {
+      return this.#peerDocumentStatuses[peerId] == "has"
+    })
+
+    if (peersWithDocument) {
+      await this.#handle.whenReady()
+    }
 
     peerIds.forEach(peerId => {
       this.#withSyncState(peerId, syncState => {
@@ -264,11 +265,28 @@ export class DocSynchronizer extends Synchronizer {
         )
         this.#setSyncState(peerId, reparsedSyncState)
 
-        docPromise
-          .then(doc => {
-            if (doc) {
-              this.#sendSyncMessage(peerId, doc)
+        // At this point if we don't have anything in our storage, we need to use an empty doc to sync
+        // with; but we don't want to surface that state to the front end
+        this.#handle
+          .whenReady([READY, REQUESTING, UNAVAILABLE])
+          .then(() => {
+            const doc = this.#handle.isReady()
+              ? this.#handle.doc()
+              : A.init<unknown>()
+
+            const noPeersWithDocument = peerIds.every(
+              peerId =>
+                this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
+            )
+
+            const wasUnavailable = doc === undefined
+            if (wasUnavailable && noPeersWithDocument) {
+              return
             }
+
+            // If the doc is unavailable we still need a blank document to generate
+            // the sync message from
+            this.#sendSyncMessage(peerId, doc ?? A.init<unknown>())
           })
           .catch(err => {
             this.#log(`Error loading doc for ${peerId}: ${err}`)
@@ -351,11 +369,20 @@ export class DocSynchronizer extends Synchronizer {
 
     this.#withSyncState(message.senderId, syncState => {
       this.#handle.update(doc => {
+        const start = performance.now()
+
         const [newDoc, newSyncState] = A.receiveSyncMessage(
           doc,
           syncState,
           message.data
         )
+        const end = performance.now()
+        this.emit("metrics", {
+          type: "receive-sync-message",
+          documentId: this.#handle.documentId,
+          durationMillis: end - start,
+          ...A.stats(doc),
+        })
 
         this.#setSyncState(message.senderId, newSyncState)
 

package/src/synchronizer/Synchronizer.ts

@@ -15,6 +15,7 @@ export interface SynchronizerEvents {
   message: (payload: MessageContents) => void
   "sync-state": (payload: SyncStatePayload) => void
   "open-doc": (arg: OpenDocMessage) => void
+  metrics: (arg: DocSyncMetrics) => void
 }
 
 /** Notify the repo that the sync state has changed  */
@@ -23,3 +24,16 @@ export interface SyncStatePayload {
   documentId: DocumentId
   syncState: SyncState
 }
+
+export type DocSyncMetrics =
+  | {
+      type: "receive-sync-message"
+      documentId: DocumentId
+      durationMillis: number
+      numOps: number
+      numChanges: number
+    }
+  | {
+      type: "doc-denied"
+      documentId: DocumentId
+    }

package/src/types.ts

@@ -27,8 +27,11 @@ export type AnyDocumentId =
   | BinaryDocumentId
   | LegacyDocumentId
 
+// We need to define our own version of heads because the AutomergeHeads type is not bs58check encoded
+export type UrlHeads = string[] & { __automergeUrlHeads: unknown }
+
 /** A branded type for peer IDs */
 export type PeerId = string & { __peerId: true }
 
 /** A randomly generated string created when the {@link Repo} starts up */
-export type SessionId = string & { __SessionId: true }
+export type SessionId = string & { __sessionId: true }

package/test/AutomergeUrl.test.ts

@@ -3,9 +3,11 @@ import bs58check from "bs58check"
 import { describe, it } from "vitest"
 import {
   generateAutomergeUrl,
+  getHeadsFromUrl,
   isValidAutomergeUrl,
   parseAutomergeUrl,
   stringifyAutomergeUrl,
+  UrlHeads,
 } from "../src/AutomergeUrl.js"
 import type {
   AutomergeUrl,
@@ -102,3 +104,131 @@ describe("AutomergeUrl", () => {
     })
   })
 })
+
+describe("AutomergeUrl with heads", () => {
+  // Create some sample encoded heads for testing
+  const head1 = bs58check.encode(new Uint8Array([1, 2, 3, 4])) as string
+  const head2 = bs58check.encode(new Uint8Array([5, 6, 7, 8])) as string
+  const goodHeads = [head1, head2] as UrlHeads
+  const urlWithHeads = `${goodUrl}#${head1}|${head2}` as AutomergeUrl
+  const invalidHead = "not-base58-encoded"
+  const invalidHeads = [invalidHead] as UrlHeads
+
+  describe("stringifyAutomergeUrl", () => {
+    it("should stringify a url with heads", () => {
+      const url = stringifyAutomergeUrl({
+        documentId: goodDocumentId,
+        heads: goodHeads,
+      })
+      assert.strictEqual(url, urlWithHeads)
+    })
+
+    it("should throw if heads are not valid base58check", () => {
+      assert.throws(() =>
+        stringifyAutomergeUrl({
+          documentId: goodDocumentId,
+          heads: invalidHeads,
+        })
+      )
+    })
+  })
+
+  describe("parseAutomergeUrl", () => {
+    it("should parse a url with heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(urlWithHeads)
+      assert.equal(documentId, goodDocumentId)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should parse a url without heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(goodUrl)
+      assert.equal(documentId, goodDocumentId)
+      assert.equal(heads, undefined)
+    })
+
+    it("should throw on url with invalid heads encoding", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert.throws(() => parseAutomergeUrl(badUrl))
+    })
+  })
+
+  describe("isValidAutomergeUrl", () => {
+    it("should return true for a valid url with heads", () => {
+      assert(isValidAutomergeUrl(urlWithHeads) === true)
+    })
+
+    it("should return false for a url with invalid heads", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert(isValidAutomergeUrl(badUrl) === false)
+    })
+  })
+
+  describe("getHeadsFromUrl", () => {
+    it("should return heads from a valid url", () => {
+      const heads = getHeadsFromUrl(urlWithHeads)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should return undefined for url without heads", () => {
+      const heads = getHeadsFromUrl(goodUrl)
+      assert.equal(heads, undefined)
+    })
+  })
+  it("should handle a single head correctly", () => {
+    const urlWithOneHead = `${goodUrl}#${head1}` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithOneHead)
+    assert.deepEqual(heads, [head1])
+  })
+
+  it("should round-trip urls with heads", () => {
+    const originalUrl = urlWithHeads
+    const parsed = parseAutomergeUrl(originalUrl)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, originalUrl)
+  })
+
+  describe("should reject malformed urls", () => {
+    it("should reject urls with trailing delimiter", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#${head1}:` as AutomergeUrl))
+    })
+
+    it("should reject urls with empty head", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#|${head1}` as AutomergeUrl))
+    })
+
+    it("should reject urls with multiple hash characters", () => {
+      assert(
+        !isValidAutomergeUrl(`${goodUrl}#${head1}#${head2}` as AutomergeUrl)
+      )
+    })
+  })
+})
+
+describe("empty heads section", () => {
+  it("should treat bare # as empty heads array", () => {
+    const urlWithEmptyHeads = `${goodUrl}#` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithEmptyHeads)
+    assert.deepEqual(heads, [])
+  })
+
+  it("should round-trip empty heads array", () => {
+    const original = `${goodUrl}#` as AutomergeUrl
+    const parsed = parseAutomergeUrl(original)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, original)
+  })
+
+  it("should distinguish between no heads and empty heads", () => {
+    const noHeads = parseAutomergeUrl(goodUrl)
+    const emptyHeads = parseAutomergeUrl(`${goodUrl}#` as AutomergeUrl)
+
+    assert.equal(noHeads.heads, undefined)
+    assert.deepEqual(emptyHeads.heads, [])
+  })
+})

package/test/CollectionSynchronizer.test.ts

@@ -28,13 +28,13 @@ describe("CollectionSynchronizer", () => {
         done()
       })
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
     }))
 
   it("starts synchronizing existing documents when a peer is added", () =>
     new Promise<void>(done => {
       const handle = repo.create()
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
       synchronizer.once("message", event => {
         const { targetId, documentId } = event as SyncMessage
         assert(targetId === "peer1")
@@ -50,7 +50,7 @@ describe("CollectionSynchronizer", () => {
 
       repo.sharePolicy = async (peerId: PeerId) => peerId !== "peer1"
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
       synchronizer.once("message", () => {
         reject(new Error("Should not have sent a message"))
       })
@@ -71,7 +71,7 @@ describe("CollectionSynchronizer", () => {
         reject(new Error("Should not have sent a message"))
       })
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
 
       setTimeout(done)
     }))