@automerge/automerge-repo 1.1.0-alpha.6 → 1.1.0

package/src/network/messages.ts

@@ -1,17 +1,27 @@
 import { SyncState } from "@automerge/automerge"
-import { DocumentId, PeerId, SessionId } from "../types.js"
 import { StorageId } from "../storage/types.js"
+import { DocumentId, PeerId, SessionId } from "../types.js"
+
+export type Message = {
+  type: string
+
+  /** The peer ID of the sender of this message */
+  senderId: PeerId
+
+  /** The peer ID of the recipient of this message */
+  targetId: PeerId
+
+  data?: Uint8Array
+
+  documentId?: DocumentId
+}
 
 /**
  * A sync message for a particular document
  */
 export type SyncMessage = {
   type: "sync"
-
-  /** The peer ID of the sender of this message */
   senderId: PeerId
-
-  /** The peer ID of the recipient of this message */
   targetId: PeerId
 
   /** The automerge sync message */
@@ -21,53 +31,50 @@ export type SyncMessage = {
   documentId: DocumentId
 }
 
-/** An ephemeral message
+/**
+ * An ephemeral message.
  *
  * @remarks
- * Ephemeral messages are not persisted anywhere and have no particular
- * structure. `automerge-repo` will gossip them around, in order to avoid
- * eternal loops of ephemeral messages every message has a session ID, which
- * is a random number generated by the sender at startup time, and a sequence
- * number. The combination of these two things allows us to discard messages
- * we have already seen.
+ * Ephemeral messages are not persisted anywhere. The data property can be used by the application
+ * as needed. The repo gossips these around.
+ *
+ * In order to avoid infinite loops of ephemeral messages, every message has (a) a session ID, which
+ * is a random number generated by the sender at startup time; and (b) a sequence number. The
+ * combination of these two things allows us to discard messages we have already seen.
  * */
 export type EphemeralMessage = {
   type: "ephemeral"
-
-  /** The peer ID of the sender of this message */
   senderId: PeerId
-
-  /** The peer ID of the recipient of this message */
   targetId: PeerId
 
-  /** A sequence number which must be incremented for each message sent by this peer */
+  /** A sequence number which must be incremented for each message sent by this peer. */
   count: number
 
-  /** The ID of the session this message is part of. The sequence number for a given session always increases */
+  /** The ID of the session this message is part of. The sequence number for a given session always increases. */
   sessionId: SessionId
 
-  /** The document ID this message pertains to */
+  /** The document ID this message pertains to. */
   documentId: DocumentId
 
-  /** The actual data of the message */
+  /** The actual data of the message. */
   data: Uint8Array
 }
 
-/** Sent by a {@link Repo} to indicate that it does not have the document and none of it's connected peers do either */
+/**
+ * Sent by a {@link Repo} to indicate that it does not have the document and none of its connected
+ * peers do either.
+ */
 export type DocumentUnavailableMessage = {
   type: "doc-unavailable"
-
-  /** The peer ID of the sender of this message */
   senderId: PeerId
-
-  /** The peer ID of the recipient of this message */
   targetId: PeerId
 
   /** The document which the peer claims it doesn't have */
   documentId: DocumentId
 }
 
-/** Sent by a {@link Repo} to request a document from a peer
+/**
+ * Sent by a {@link Repo} to request a document from a peer.
  *
  * @remarks
  * This is identical to a {@link SyncMessage} except that it is sent by a {@link Repo}
@@ -75,47 +82,43 @@ export type DocumentUnavailableMessage = {
  * */
 export type RequestMessage = {
   type: "request"
-
-  /** The peer ID of the sender of this message */
   senderId: PeerId
-
-  /** The peer ID of the recipient of this message */
   targetId: PeerId
 
-  /** The initial automerge sync message */
+  /** The automerge sync message */
   data: Uint8Array
 
-  /** The document ID this message requests */
+  /** The document ID of the document this message is for */
   documentId: DocumentId
 }
 
-/** (anticipating work in progress) */
-export type AuthMessage<TPayload = any> = {
-  type: "auth"
-
-  /** The peer ID of the sender of this message */
-  senderId: PeerId
-
-  /** The peer ID of the recipient of this message */
-  targetId: PeerId
-
-  /** The payload of the auth message (up to the specific auth provider) */
-  payload: TPayload
-}
-
+/**
+ * Sent by a {@link Repo} to add or remove storage IDs from a remote peer's subscription.
+ */
 export type RemoteSubscriptionControlMessage = {
   type: "remote-subscription-change"
   senderId: PeerId
   targetId: PeerId
+
+  /** The storage IDs to add to the subscription */
   add?: StorageId[]
+
+  /** The storage IDs to remove from the subscription */
   remove?: StorageId[]
 }
 
+/**
+ * Sent by a {@link Repo} to indicate that the heads of a document have changed on a remote peer.
+ */
 export type RemoteHeadsChanged = {
   type: "remote-heads-changed"
   senderId: PeerId
   targetId: PeerId
+
+  /** The document ID of the document that has changed */
   documentId: DocumentId
+
+  /** The document's new heads */
   newHeads: { [key: StorageId]: { heads: string[]; timestamp: number } }
 }
 
@@ -128,19 +131,17 @@ export type RepoMessage =
   | RemoteSubscriptionControlMessage
   | RemoteHeadsChanged
 
+/** These are message types that are handled by the {@link CollectionSynchronizer}.*/
 export type DocMessage =
   | SyncMessage
   | EphemeralMessage
   | RequestMessage
   | DocumentUnavailableMessage
 
-/** These are all the message types that a {@link NetworkAdapter} might see. */
-export type Message = RepoMessage | AuthMessage
-
 /**
  * The contents of a message, without the sender ID or other properties added by the {@link NetworkSubsystem})
  */
-export type MessageContents<T extends Message = Message> =
+export type MessageContents<T extends Message = RepoMessage> =
   T extends EphemeralMessage
     ? Omit<T, "senderId" | "count" | "sessionId">
     : Omit<T, "senderId">
@@ -160,16 +161,13 @@ export interface OpenDocMessage {
 
 // TYPE GUARDS
 
-export const isValidRepoMessage = (message: Message): message is RepoMessage =>
-  typeof message === "object" &&
-  typeof message.type === "string" &&
-  typeof message.senderId === "string" &&
-  (isSyncMessage(message) ||
-    isEphemeralMessage(message) ||
-    isRequestMessage(message) ||
-    isDocumentUnavailableMessage(message) ||
-    isRemoteSubscriptionControlMessage(message) ||
-    isRemoteHeadsChanged(message))
+export const isRepoMessage = (message: Message): message is RepoMessage =>
+  isSyncMessage(message) ||
+  isEphemeralMessage(message) ||
+  isRequestMessage(message) ||
+  isDocumentUnavailableMessage(message) ||
+  isRemoteSubscriptionControlMessage(message) ||
+  isRemoteHeadsChanged(message)
 
 // prettier-ignore
 export const isDocumentUnavailableMessage = (msg: Message): msg is DocumentUnavailableMessage => 
@@ -184,9 +182,8 @@ export const isSyncMessage = (msg: Message): msg is SyncMessage =>
 export const isEphemeralMessage = (msg: Message): msg is EphemeralMessage =>
   msg.type === "ephemeral"
 
-export const isRemoteSubscriptionControlMessage = (
-  msg: Message
-): msg is RemoteSubscriptionControlMessage =>
+// prettier-ignore
+export const isRemoteSubscriptionControlMessage = (msg: Message): msg is RemoteSubscriptionControlMessage =>
   msg.type === "remote-subscription-change"
 
 export const isRemoteHeadsChanged = (msg: Message): msg is RemoteHeadsChanged =>

package/src/storage/StorageSubsystem.ts

@@ -33,7 +33,7 @@ export class StorageSubsystem {
   }
 
   async id(): Promise<StorageId> {
-    let storedId = await this.#storageAdapter.load(["storage-adapter-id"])
+    const storedId = await this.#storageAdapter.load(["storage-adapter-id"])
 
     let id: StorageId
     if (storedId) {

package/src/synchronizer/CollectionSynchronizer.ts

@@ -2,7 +2,7 @@ import debug from "debug"
 import { DocHandle } from "../DocHandle.js"
 import { stringifyAutomergeUrl } from "../AutomergeUrl.js"
 import { Repo } from "../Repo.js"
-import { DocMessage, RepoMessage } from "../network/messages.js"
+import { DocMessage } from "../network/messages.js"
 import { DocumentId, PeerId } from "../types.js"
 import { DocSynchronizer } from "./DocSynchronizer.js"
 import { Synchronizer } from "./Synchronizer.js"
@@ -117,6 +117,7 @@ export class CollectionSynchronizer extends Synchronizer {
   }
 
   // TODO: implement this
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   removeDocument(documentId: DocumentId) {
     throw new Error("not implemented")
   }

package/src/synchronizer/DocSynchronizer.ts

@@ -137,9 +137,13 @@ export class DocSynchronizer extends Synchronizer {
 
     let pendingCallbacks = this.#pendingSyncStateCallbacks[peerId]
     if (!pendingCallbacks) {
-      this.#onLoadSyncState(peerId).then(syncState => {
-        this.#initSyncState(peerId, syncState ?? A.initSyncState())
-      })
+      this.#onLoadSyncState(peerId)
+        .then(syncState => {
+          this.#initSyncState(peerId, syncState ?? A.initSyncState())
+        })
+        .catch(err => {
+          this.#log(`Error loading sync state for ${peerId}: ${err}`)
+        })
       pendingCallbacks = this.#pendingSyncStateCallbacks[peerId] = []
     }
 
@@ -260,11 +264,15 @@ export class DocSynchronizer extends Synchronizer {
         )
         this.#setSyncState(peerId, reparsedSyncState)
 
-        docPromise.then(doc => {
-          if (doc) {
-            this.#sendSyncMessage(peerId, doc)
-          }
-        })
+        docPromise
+          .then(doc => {
+            if (doc) {
+              this.#sendSyncMessage(peerId, doc)
+            }
+          })
+          .catch(err => {
+            this.#log(`Error loading doc for ${peerId}: ${err}`)
+          })
       })
     })
   }
@@ -326,10 +334,10 @@ export class DocSynchronizer extends Synchronizer {
     }
 
     this.#processAllPendingSyncMessages()
-    this.#processSyncMessage(message, new Date())
+    this.#processSyncMessage(message)
   }
 
-  #processSyncMessage(message: SyncMessage | RequestMessage, received: Date) {
+  #processSyncMessage(message: SyncMessage | RequestMessage) {
     if (isRequestMessage(message)) {
       this.#peerDocumentStatuses[message.senderId] = "wants"
     }
@@ -388,7 +396,7 @@ export class DocSynchronizer extends Synchronizer {
 
   #processAllPendingSyncMessages() {
     for (const message of this.#pendingSyncMessages) {
-      this.#processSyncMessage(message.message, message.received)
+      this.#processSyncMessage(message.message)
     }
 
     this.#pendingSyncMessages = []

package/src/synchronizer/Synchronizer.ts

@@ -3,15 +3,23 @@ import {
   MessageContents,
   OpenDocMessage,
   RepoMessage,
-  SyncStateMessage,
 } from "../network/messages.js"
+import { SyncState } from "@automerge/automerge"
+import { PeerId, DocumentId } from "../types.js"
 
 export abstract class Synchronizer extends EventEmitter<SynchronizerEvents> {
   abstract receiveMessage(message: RepoMessage): void
 }
 
 export interface SynchronizerEvents {
-  message: (arg: MessageContents) => void
-  "sync-state": (arg: SyncStateMessage) => void
+  message: (payload: MessageContents) => void
+  "sync-state": (payload: SyncStatePayload) => void
   "open-doc": (arg: OpenDocMessage) => void
 }
+
+/** Notify the repo that the sync state has changed  */
+export interface SyncStatePayload {
+  peerId: PeerId
+  documentId: DocumentId
+  syncState: SyncState
+}

package/test/CollectionSynchronizer.test.ts

@@ -1,6 +1,6 @@
 import assert from "assert"
 import { beforeEach, describe, it } from "vitest"
-import { PeerId, Repo } from "../src/index.js"
+import { PeerId, Repo, SyncMessage } from "../src/index.js"
 import { CollectionSynchronizer } from "../src/synchronizer/CollectionSynchronizer.js"
 
 describe("CollectionSynchronizer", () => {
@@ -24,8 +24,9 @@ describe("CollectionSynchronizer", () => {
       synchronizer.addPeer("peer1" as PeerId)
 
       synchronizer.once("message", event => {
-        assert(event.targetId === "peer1")
-        assert(event.documentId === handle.documentId)
+        const { targetId, documentId } = event as SyncMessage
+        assert(targetId === "peer1")
+        assert(documentId === handle.documentId)
         done()
       })
 
@@ -37,8 +38,9 @@ describe("CollectionSynchronizer", () => {
       const handle = repo.create()
       synchronizer.addDocument(handle.documentId)
       synchronizer.once("message", event => {
-        assert(event.targetId === "peer1")
-        assert(event.documentId === handle.documentId)
+        const { targetId, documentId } = event as SyncMessage
+        assert(targetId === "peer1")
+        assert(documentId === handle.documentId)
         done()
       })
       synchronizer.addPeer("peer1" as PeerId)

package/test/DocHandle.test.ts

@@ -5,7 +5,7 @@ import { describe, it } from "vitest"
 import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
-import { DocHandle, DocHandleChangePayload, PeerId } from "../src/index.js"
+import { DocHandle, DocHandleChangePayload } from "../src/index.js"
 import { TestDoc } from "./types.js"
 
 describe("DocHandle", () => {
@@ -20,6 +20,15 @@ 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)
@@ -44,7 +53,7 @@ describe("DocHandle", () => {
     assert.deepEqual(doc, handle.docSync())
   })
 
-  it("should return undefined if we accessing the doc before ready", async () => {
+  it("should return undefined if we access the doc before ready", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
 
     assert.equal(handle.docSync(), undefined)

package/test/RemoteHeadsSubscriptions.test.ts

@@ -8,7 +8,7 @@ import {
   RemoteHeadsChanged,
   RemoteSubscriptionControlMessage,
 } from "../src/network/messages.js"
-import { waitForMessages } from "./helpers/waitForMessages.js"
+import { collectMessages } from "./helpers/collectMessages.js"
 
 describe("RepoHeadsSubscriptions", () => {
   const storageA = "remote-a" as StorageId
@@ -86,15 +86,15 @@ describe("RepoHeadsSubscriptions", () => {
   it("should allow to subscribe and unsubscribe to storage ids", async () => {
     const remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
 
-    const remoteHeadsMessages = waitForMessages(
-      remoteHeadsSubscriptions,
-      "remote-heads-changed"
-    )
+    const remoteHeadsMessages = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "remote-heads-changed",
+    })
 
-    const changeRemoteSubsAfterSubscribe = waitForMessages(
-      remoteHeadsSubscriptions,
-      "change-remote-subs"
-    )
+    const changeRemoteSubsAfterSubscribe = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "change-remote-subs",
+    })
 
     // subscribe to storageB and change storageB heads
     remoteHeadsSubscriptions.subscribeToRemotes([storageB])
@@ -114,10 +114,10 @@ describe("RepoHeadsSubscriptions", () => {
     assert.deepStrictEqual(messages[0].remove, undefined)
     assert.deepStrictEqual(messages[0].peers, [])
 
-    const remoteHeadsMessagesAfterUnsub = waitForMessages(
-      remoteHeadsSubscriptions,
-      "change-remote-subs"
-    )
+    const remoteHeadsMessagesAfterUnsub = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "change-remote-subs",
+    })
 
     // unsubscribe from storageB
     remoteHeadsSubscriptions.unsubscribeFromRemotes([storageB])
@@ -133,15 +133,15 @@ describe("RepoHeadsSubscriptions", () => {
   it("should forward all changes to generous peers", async () => {
     const remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
 
-    const notifyRemoteHeadsMessagesPromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "notify-remote-heads"
-    )
+    const notifyRemoteHeadsMessagesPromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "notify-remote-heads",
+    })
 
-    const changeRemoteSubsMessagesPromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "change-remote-subs"
-    )
+    const changeRemoteSubsMessagesPromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "change-remote-subs",
+    })
 
     remoteHeadsSubscriptions.addGenerousPeer(peerC)
     remoteHeadsSubscriptions.subscribeToRemotes([storageB])
@@ -170,10 +170,10 @@ describe("RepoHeadsSubscriptions", () => {
     assert.deepStrictEqual(messages[0].remove, undefined)
     assert.deepStrictEqual(messages[0].peers, [peerC])
 
-    const changeRemoteSubsMessagesAfterUnsubPromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "change-remote-subs"
-    )
+    const changeRemoteSubsMessagesAfterUnsubPromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "change-remote-subs",
+    })
 
     // unsubsscribe from storage B
     remoteHeadsSubscriptions.unsubscribeFromRemotes([storageB])
@@ -189,10 +189,10 @@ describe("RepoHeadsSubscriptions", () => {
   it("should not notify generous peers of changed remote heads, if they send the heads originally", async () => {
     const remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
 
-    const messagesPromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "notify-remote-heads"
-    )
+    const messagesPromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "notify-remote-heads",
+    })
 
     remoteHeadsSubscriptions.addGenerousPeer(peerC)
     remoteHeadsSubscriptions.subscribeToRemotes([storageB])
@@ -219,10 +219,10 @@ describe("RepoHeadsSubscriptions", () => {
 
     // subscribe peer c to storage b
     remoteHeadsSubscriptions.handleControlMessage(subscribePeerCToStorageB)
-    const messagesAfterSubscribePromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "notify-remote-heads"
-    )
+    const messagesAfterSubscribePromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "notify-remote-heads",
+    })
     remoteHeadsSubscriptions.subscribePeerToDoc(peerC, docA)
     remoteHeadsSubscriptions.subscribePeerToDoc(peerC, docC)
 
@@ -248,10 +248,10 @@ describe("RepoHeadsSubscriptions", () => {
 
     // unsubscribe peer C
     remoteHeadsSubscriptions.handleControlMessage(unsubscribePeerCFromStorageB)
-    const messagesAfteUnsubscribePromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "notify-remote-heads"
-    )
+    const messagesAfteUnsubscribePromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "notify-remote-heads",
+    })
 
     // heads of docB for storageB change
     remoteHeadsSubscriptions.handleRemoteHeads(docBHeadsChangedForStorageB)
@@ -267,10 +267,10 @@ describe("RepoHeadsSubscriptions", () => {
 
     // subscribe peer c to storage b
     remoteHeadsSubscriptions.handleControlMessage(subscribePeerCToStorageB)
-    const messagesAfterSubscribePromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "notify-remote-heads"
-    )
+    const messagesAfterSubscribePromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "notify-remote-heads",
+    })
 
     // change message for docA in storageB
     remoteHeadsSubscriptions.handleRemoteHeads(docAHeadsChangedForStorageB)
@@ -287,17 +287,20 @@ describe("RepoHeadsSubscriptions", () => {
     assert.strictEqual(messages.length, 0)
   })
 
-  it("should ignore sync states with an older timestamp", async () => {
+  it("should only notify of sync states with a more recent timestamp", async () => {
     const remoteHeadsSubscription = new RemoteHeadsSubscriptions()
 
-    const messagesPromise = waitForMessages(
-      remoteHeadsSubscription,
-      "remote-heads-changed"
-    )
+    const messagesPromise = collectMessages({
+      emitter: remoteHeadsSubscription,
+      event: "remote-heads-changed",
+    })
 
     remoteHeadsSubscription.subscribeToRemotes([storageB])
     remoteHeadsSubscription.handleRemoteHeads(docBHeadsChangedForStorageB2)
 
+    // send same message
+    remoteHeadsSubscription.handleRemoteHeads(docBHeadsChangedForStorageB2)
+
     // send message with old heads
     remoteHeadsSubscription.handleRemoteHeads(docBHeadsChangedForStorageB)
 
@@ -311,10 +314,10 @@ describe("RepoHeadsSubscriptions", () => {
   it("should remove subs of disconnected peers", async () => {
     const remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
 
-    const messagesPromise = waitForMessages(
-      remoteHeadsSubscriptions,
-      "change-remote-subs"
-    )
+    const messagesPromise = collectMessages({
+      emitter: remoteHeadsSubscriptions,
+      event: "change-remote-subs",
+    })
 
     remoteHeadsSubscriptions.handleControlMessage({
       type: "remote-subscription-change",