@automerge/automerge-repo 1.2.1 → 2.0.0-alpha.0

package/src/helpers/tests/network-adapter-tests.ts

@@ -1,6 +1,13 @@
 import assert from "assert"
 import { describe, expect, it } from "vitest"
-import { PeerId, PeerMetadata, Repo, StorageId } from "../../index.js"
+import {
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+  PeerId,
+  PeerMetadata,
+  Repo,
+  StorageId,
+} from "../../index.js"
 import type { NetworkAdapterInterface } from "../../network/NetworkAdapterInterface.js"
 import { eventPromise, eventPromises } from "../eventPromise.js"
 import { pause } from "../pause.js"
@@ -169,6 +176,119 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
       teardown()
     })
+
+    it("should emit disconnect events on disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await Promise.all([
+        eventPromise(leftRepo.networkSubsystem, "peer"),
+        eventPromise(rightRepo.networkSubsystem, "peer"),
+      ])
+
+      const disconnectionPromises = Promise.all([
+        eventPromise(leftRepo.networkSubsystem, "peer-disconnected"),
+        eventPromise(rightRepo.networkSubsystem, "peer-disconnected"),
+      ])
+      left.disconnect()
+
+      await disconnectionPromises
+      teardown()
+    })
+
+    it("should not send messages after disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await Promise.all([
+        eventPromise(rightRepo.networkSubsystem, "peer"),
+        eventPromise(leftRepo.networkSubsystem, "peer"),
+      ])
+
+      const disconnected = eventPromise(right, "peer-disconnected")
+
+      left.disconnect()
+      await disconnected
+
+      const rightReceivedFromLeft = new Promise(resolve => {
+        right.on("message", msg => {
+          if (msg.senderId === leftPeerId) {
+            resolve(null)
+          }
+        })
+      })
+
+      const rightReceived = Promise.race([rightReceivedFromLeft, pause(10)])
+
+      const documentId = parseAutomergeUrl(generateAutomergeUrl()).documentId
+      left.send({
+        type: "foo",
+        data: new Uint8Array([1, 2, 3]),
+        documentId,
+        senderId: leftPeerId,
+        targetId: rightPeerId,
+      })
+
+      assert.equal(await rightReceived, null)
+      teardown()
+    })
+
+    it("should support reconnecting after disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const _leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await eventPromise(rightRepo.networkSubsystem, "peer")
+
+      left.disconnect()
+
+      await pause(10)
+
+      left.connect(leftPeerId)
+      await eventPromise(left, "peer-candidate")
+      teardown()
+    })
   })
 }
 

package/src/helpers/throttle.ts

@@ -20,7 +20,7 @@
  *
  *
  * Example usage:
- * const callback = debounce((ev) => { doSomethingExpensiveOrOccasional() }, 100)
+ * const callback = throttle((ev) => { doSomethingExpensiveOrOccasional() }, 100)
  * target.addEventListener('frequent-event', callback);
  *
  */

package/src/network/NetworkAdapter.ts

@@ -23,6 +23,9 @@ export abstract class NetworkAdapter
   peerId?: PeerId
   peerMetadata?: PeerMetadata
 
+  abstract isReady(): boolean
+  abstract whenReady(): Promise<void>
+
   /** Called by the {@link Repo} to start the connection process
    *
    * @argument peerId - the peerId of this repo

package/src/network/NetworkAdapterInterface.ts

@@ -32,12 +32,16 @@ export interface NetworkAdapterInterface
   peerId?: PeerId
   peerMetadata?: PeerMetadata
 
+  isReady(): boolean
+  whenReady(): Promise<void>
+
   /** Called by the {@link Repo} to start the connection process
    *
    * @argument peerId - the peerId of this repo
    * @argument peerMetadata - how this adapter should present itself to other peers
    */
   connect(peerId: PeerId, peerMetadata?: PeerMetadata): void
+  // TODO: should this just return a ready promise?
 
   /** Called by the {@link Repo} to send a message to a peer
    *
@@ -52,9 +56,6 @@ export interface NetworkAdapterInterface
 // events & payloads
 
 export interface NetworkAdapterEvents {
-  /** Emitted when the network is ready to be used */
-  ready: (payload: OpenPayload) => void
-
   /** Emitted when the network is closed */
   close: () => void
 

package/src/network/NetworkSubsystem.ts

@@ -26,12 +26,11 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
   #count = 0
   #sessionId: SessionId = Math.random().toString(36).slice(2) as SessionId
   #ephemeralSessionCounts: Record<EphemeralMessageSource, number> = {}
-  #readyAdapterCount = 0
-  #adapters: NetworkAdapterInterface[] = []
+  adapters: NetworkAdapterInterface[] = []
 
   constructor(
     adapters: NetworkAdapterInterface[],
-    public peerId = randomPeerId(),
+    public peerId: PeerId,
     private peerMetadata: Promise<PeerMetadata>
   ) {
     super()
@@ -39,25 +38,25 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     adapters.forEach(a => this.addNetworkAdapter(a))
   }
 
+  disconnect() {
+    this.adapters.forEach(a => a.disconnect())
+  }
+
+  reconnect() {
+    this.adapters.forEach(a => a.connect(this.peerId))
+  }
+
   addNetworkAdapter(networkAdapter: NetworkAdapterInterface) {
-    this.#adapters.push(networkAdapter)
-    networkAdapter.once("ready", () => {
-      this.#readyAdapterCount++
-      this.#log(
-        "Adapters ready: ",
-        this.#readyAdapterCount,
-        "/",
-        this.#adapters.length
-      )
-      if (this.#readyAdapterCount === this.#adapters.length) {
-        this.emit("ready")
-      }
-    })
+    this.adapters.push(networkAdapter)
 
     networkAdapter.on("peer-candidate", ({ peerId, peerMetadata }) => {
       this.#log(`peer candidate: ${peerId} `)
       // TODO: This is where authentication would happen
 
+      // TODO: on reconnection, this would create problems!
+      // the server would see a reconnection as a late-arriving channel
+      // for an existing peer and decide to ignore it until the connection
+      // times out: turns out my ICE/SIP emulation laziness did not pay off here
       if (!this.#adaptersByPeer[peerId]) {
         // TODO: handle losing a server here
         this.#adaptersByPeer[peerId] = networkAdapter
@@ -114,6 +113,13 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
       })
   }
 
+  // TODO: this probably introduces a race condition for the ready event
+  // but I plan to refactor that as part of this branch in another patch
+  removeNetworkAdapter(networkAdapter: NetworkAdapterInterface) {
+    this.adapters = this.adapters.filter(a => a !== networkAdapter)
+    networkAdapter.disconnect()
+  }
+
   send(message: MessageContents) {
     const peer = this.#adaptersByPeer[message.targetId]
     if (!peer) {
@@ -153,33 +159,20 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
   }
 
   isReady = () => {
-    return this.#readyAdapterCount === this.#adapters.length
+    return this.adapters.every(a => a.isReady())
   }
 
   whenReady = async () => {
-    if (this.isReady()) {
-      return
-    } else {
-      return new Promise<void>(resolve => {
-        this.once("ready", () => {
-          resolve()
-        })
-      })
-    }
+    return Promise.all(this.adapters.map(a => a.whenReady()))
   }
 }
 
-function randomPeerId() {
-  return `user-${Math.round(Math.random() * 100000)}` as PeerId
-}
-
 // events & payloads
 
 export interface NetworkSubsystemEvents {
   peer: (payload: PeerPayload) => void
   "peer-disconnected": (payload: PeerDisconnectedPayload) => void
   message: (payload: RepoMessage) => void
-  ready: () => void
 }
 
 export interface PeerPayload {

package/test/AutomergeUrl.test.ts

@@ -96,5 +96,9 @@ describe("AutomergeUrl", () => {
       const url = stringifyAutomergeUrl({ documentId: badUuidDocumentId })
       assert(isValidAutomergeUrl(url) === false)
     })
+
+    it("should return false for a documentId that is just some random type", () => {
+      assert(isValidAutomergeUrl({ foo: "bar" } as unknown) === false)
+    })
   })
 })

package/test/DocHandle.test.ts

@@ -10,6 +10,12 @@ import { TestDoc } from "./types.js"
 
 describe("DocHandle", () => {
   const TEST_ID = parseAutomergeUrl(generateAutomergeUrl()).documentId
+  const setup = (options?) => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, options)
+    handle.update(() => A.init())
+    handle.doneLoading()
+    return handle
+  }
 
   const docFromMockStorage = (doc: A.Doc<{ foo: string }>) => {
     return A.change<{ foo: string }>(doc, d => (d.foo = "bar"))
@@ -20,15 +26,6 @@ describe("DocHandle", () => {
     assert.equal(handle.documentId, TEST_ID)
   })
 
-  it("should take an initial value", async () => {
-    const handle = new DocHandle(TEST_ID, {
-      isNew: true,
-      initialValue: { foo: "bar" },
-    })
-    const doc = await handle.doc()
-    assert.equal(doc.foo, "bar")
-  })
-
   it("should become ready when a document is loaded", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
@@ -55,7 +52,6 @@ describe("DocHandle", () => {
 
   it("should return undefined if we access the doc before ready", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
-
     assert.equal(handle.docSync(), undefined)
   })
 
@@ -73,10 +69,8 @@ describe("DocHandle", () => {
   })
 
   it("should return the heads when requested", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, {
-      isNew: true,
-      initialValue: { foo: "bar" },
-    })
+    const handle = setup()
+    handle.change(d => (d.foo = "bar"))
     assert.equal(handle.isReady(), true)
 
     const heads = A.getHeads(handle.docSync())
@@ -94,6 +88,7 @@ describe("DocHandle", () => {
    * Once there's a Repo#stop API this case should be covered in accompanying
    * tests and the following test removed.
    */
+  // TODO as part of future cleanup: move this to Repo
   it("no pending timers after a document is loaded", async () => {
     vi.useFakeTimers()
     const timerCount = vi.getTimerCount()
@@ -159,7 +154,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a change message when changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<DocHandleChangePayload<TestDoc>>(resolve =>
       handle.once("change", d => resolve(d))
@@ -179,7 +174,7 @@ describe("DocHandle", () => {
 
   it("should not emit a change message if no change happens via update", () =>
     new Promise<void>((done, reject) => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
       handle.once("change", () => {
         reject(new Error("shouldn't have changed"))
       })
@@ -190,7 +185,7 @@ describe("DocHandle", () => {
     }))
 
   it("should update the internal doc prior to emitting the change message", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<void>(resolve =>
       handle.once("change", ({ handle, doc }) => {
@@ -208,7 +203,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit distinct change messages when consecutive changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     let calls = 0
     const p = new Promise(resolve =>
@@ -238,7 +233,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a change message when changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
     const p = new Promise(resolve => handle.once("change", d => resolve(d)))
 
     handle.change(doc => {
@@ -252,7 +247,7 @@ describe("DocHandle", () => {
 
   it("should not emit a patch message if no change happens", () =>
     new Promise<void>((done, reject) => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
       handle.on("change", () => {
         reject(new Error("shouldn't have changed"))
       })
@@ -301,7 +296,7 @@ describe("DocHandle", () => {
 
   it("should not time out if the document is updated in time", async () => {
     // set docHandle time out after 5 ms
-    const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 1 })
+    const handle = setup({ timeoutDelay: 1 })
 
     // simulate requesting from the network
     handle.request()
@@ -319,7 +314,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a delete event when deleted", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<void>(resolve =>
       handle.once("delete", () => resolve())
@@ -331,7 +326,7 @@ describe("DocHandle", () => {
   })
 
   it("should allow changing at old heads", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     handle.change(doc => {
       doc.foo = "bar"
@@ -355,7 +350,8 @@ describe("DocHandle", () => {
 
   describe("ephemeral messaging", () => {
     it("can broadcast a message for the network to send out", async () => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
+
       const message = { foo: "bar" }
 
       const promise = eventPromise(handle, "ephemeral-message-outbound")

package/test/DocSynchronizer.test.ts

@@ -1,5 +1,6 @@
 import assert from "assert"
 import { describe, it } from "vitest"
+import { next as Automerge } from "@automerge/automerge"
 import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { DocHandle } from "../src/DocHandle.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
@@ -21,10 +22,13 @@ describe("DocSynchronizer", () => {
 
   const setup = () => {
     const docId = parseAutomergeUrl(generateAutomergeUrl()).documentId
-    handle = new DocHandle<TestDoc>(docId, { isNew: true })
+    handle = new DocHandle<TestDoc>(docId)
+    handle.doneLoading()
+
     docSynchronizer = new DocSynchronizer({
       handle: handle as DocHandle<unknown>,
     })
+
     return { handle, docSynchronizer }
   }
 

package/test/NetworkSubsystem.test.ts

@@ -0,0 +1,107 @@
+import assert from "assert"
+import { describe, it } from "vitest"
+import { NetworkSubsystem } from "../src/network/NetworkSubsystem.js"
+import { DummyNetworkAdapter } from "../src/helpers/DummyNetworkAdapter.js"
+import { PeerId, PeerMetadata, StorageId } from "../src/index.js"
+
+// Note: The sync tests in `Repo.test.ts` exercise the network subsystem, and the suite in
+// `automerge-repo` provides test utilities that individual adapters can
+// use to ensure that they work correctly.
+
+describe("Network subsystem", () => {
+  const setup = ({ startReady = true } = {}) => {
+    const networkAdapter = new DummyNetworkAdapter({ startReady })
+    const peerId = "peerId" as PeerId
+    const peerMetadata: Promise<PeerMetadata> = Promise.resolve({
+      storageId: "no-such-id" as StorageId,
+      isEphemeral: true,
+    })
+    return { networkAdapter, peerId, peerMetadata }
+  }
+
+  it("Can be instantiated with no network adapters", () => {
+    const { peerId, peerMetadata } = setup()
+    const network = new NetworkSubsystem([], peerId, peerMetadata)
+    assert(network !== null)
+  })
+
+  it("can be instantiated with a network adapter", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup()
+    const network = new NetworkSubsystem([networkAdapter], peerId, peerMetadata)
+    assert(
+      network instanceof NetworkSubsystem,
+      "Network should be an instance of NetworkSubsystem"
+    )
+  })
+
+  it("should become ready with a ready adapter", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup()
+    const network = new NetworkSubsystem([networkAdapter], peerId, peerMetadata)
+    await network.whenReady()
+    assert.strictEqual(
+      network.isReady(),
+      true,
+      "Network should be ready with a ready adapter"
+    )
+  })
+
+  it("allows adding a network adapter after creation", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup({
+      startReady: false,
+    })
+    const network = new NetworkSubsystem([], peerId, peerMetadata)
+    network.addNetworkAdapter(networkAdapter)
+    assert(
+      network instanceof NetworkSubsystem,
+      "Network should be an instance of NetworkSubsystem"
+    )
+  })
+
+  it("does not become ready prematurely when adapter is not ready", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup({
+      startReady: false,
+    })
+    const network = new NetworkSubsystem([], peerId, peerMetadata)
+    network.addNetworkAdapter(networkAdapter)
+    assert.strictEqual(
+      network.isReady(),
+      false,
+      "Network should not be ready immediately when adapter is not ready"
+    )
+  })
+
+  it("allows removing a network adapter after creation", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup()
+    const network = new NetworkSubsystem([networkAdapter], peerId, peerMetadata)
+    network.removeNetworkAdapter(networkAdapter)
+    assert(network !== null)
+    assert(network.adapters.length == 0)
+    assert.strictEqual(
+      network.isReady(),
+      true,
+      "An empty network subsystem is ready after removing the adapter"
+    )
+  })
+
+  it("handles ready behaviour for multiple network adapters correctly", async () => {
+    const { networkAdapter, peerId, peerMetadata } = setup()
+    const network = new NetworkSubsystem([networkAdapter], peerId, peerMetadata)
+
+    const anotherAdapter = new DummyNetworkAdapter({ startReady: true })
+    network.addNetworkAdapter(anotherAdapter)
+
+    await network.whenReady()
+    assert.strictEqual(
+      network.isReady(),
+      true,
+      "Network should be ready when all adapters are ready"
+    )
+
+    network.removeNetworkAdapter(networkAdapter)
+    assert.strictEqual(
+      network.isReady(),
+      true,
+      "Network should remain ready when at least one adapter is still ready"
+    )
+  })
+})