@automerge/automerge-repo 1.1.0-alpha.7 → 1.1.1

package/src/network/NetworkAdapter.ts

@@ -1,27 +1,23 @@
+/* c8 ignore start */
+
 import { EventEmitter } from "eventemitter3"
+import { NetworkAdapterEvents, PeerMetadata } from "../index.js"
 import { PeerId } from "../types.js"
 import { Message } from "./messages.js"
-import { StorageId } from "../storage/types.js"
-
-/** 
- * Describes a peer intent to the system
- * storageId: the key for syncState to decide what the other peer already has
- * isEphemeral: to decide if we bother recording this peer's sync state
- * 
- */
-export interface PeerMetadata {
-  storageId?: StorageId
-  isEphemeral?: boolean
-}
+import { NetworkAdapterInterface } from "./NetworkAdapterInterface.js"
 
 /** An interface representing some way to connect to other peers
+ * @deprecated use {@link NetworkAdapterInterface}
  *
  * @remarks
  * The {@link Repo} uses one or more `NetworkAdapter`s to connect to other peers.
  * Because the network may take some time to be ready the {@link Repo} will wait
  * until the adapter emits a `ready` event before it starts trying to use it
  */
-export abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents> {
+export abstract class NetworkAdapter
+  extends EventEmitter<NetworkAdapterEvents>
+  implements NetworkAdapterInterface
+{
   peerId?: PeerId
   peerMetadata?: PeerMetadata
 
@@ -41,35 +37,3 @@ export abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents>
   /** Called by the {@link Repo} to disconnect from the network */
   abstract disconnect(): void
 }
-
-// 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
-
-  /** Emitted when the network adapter learns about a new peer */
-  "peer-candidate": (payload: PeerCandidatePayload) => void
-
-  /** Emitted when the network adapter learns that a peer has disconnected */
-  "peer-disconnected": (payload: PeerDisconnectedPayload) => void
-
-  /** Emitted when the network adapter receives a message from a peer */
-  message: (payload: Message) => void
-}
-
-export interface OpenPayload {
-  network: NetworkAdapter
-}
-
-export interface PeerCandidatePayload {
-  peerId: PeerId
-  peerMetadata: PeerMetadata
-}
-
-export interface PeerDisconnectedPayload {
-  peerId: PeerId
-}

package/src/network/NetworkAdapterInterface.ts

@@ -0,0 +1,77 @@
+/* c8 ignore start */
+
+import { EventEmitter } from "eventemitter3"
+import { PeerId } from "../types.js"
+import { Message } from "./messages.js"
+import { StorageId } from "../storage/types.js"
+
+/**
+ * Describes a peer intent to the system
+ * storageId: the key for syncState to decide what the other peer already has
+ * isEphemeral: to decide if we bother recording this peer's sync state
+ *
+ */
+export interface PeerMetadata {
+  storageId?: StorageId
+  isEphemeral?: boolean
+}
+
+/** An interface representing some way to connect to other peers
+ *
+ * @remarks
+ * The {@link Repo} uses one or more `NetworkAdapter`s to connect to other peers.
+ * Because the network may take some time to be ready the {@link Repo} will wait
+ * until the adapter emits a `ready` event before it starts trying to use it
+ */
+export interface NetworkAdapterInterface extends EventEmitter<NetworkAdapterEvents> {
+  peerId?: PeerId
+  peerMetadata?: PeerMetadata
+
+  /** 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
+
+  /** Called by the {@link Repo} to send a message to a peer
+   *
+   * @argument message - the message to send
+   */
+  send(message: Message): void
+
+  /** Called by the {@link Repo} to disconnect from the network */
+  disconnect(): void
+}
+
+// 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
+
+  /** Emitted when the network adapter learns about a new peer */
+  "peer-candidate": (payload: PeerCandidatePayload) => void
+
+  /** Emitted when the network adapter learns that a peer has disconnected */
+  "peer-disconnected": (payload: PeerDisconnectedPayload) => void
+
+  /** Emitted when the network adapter receives a message from a peer */
+  message: (payload: Message) => void
+}
+
+export interface OpenPayload {
+  network: NetworkAdapterInterface
+}
+
+export interface PeerCandidatePayload {
+  peerId: PeerId
+  peerMetadata: PeerMetadata
+}
+
+export interface PeerDisconnectedPayload {
+  peerId: PeerId
+}

package/src/network/NetworkSubsystem.ts

@@ -2,16 +2,16 @@ import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import { PeerId, SessionId } from "../types.js"
 import type {
-  NetworkAdapter,
+  NetworkAdapterInterface,
   PeerDisconnectedPayload,
   PeerMetadata,
-} from "./NetworkAdapter.js"
+} from "./NetworkAdapterInterface.js"
 import {
   EphemeralMessage,
   MessageContents,
   RepoMessage,
   isEphemeralMessage,
-  isValidRepoMessage,
+  isRepoMessage,
 } from "./messages.js"
 
 type EphemeralMessageSource = `${PeerId}:${SessionId}`
@@ -21,16 +21,16 @@ const getEphemeralMessageSource = (message: EphemeralMessage) =>
 
 export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
   #log: debug.Debugger
-  #adaptersByPeer: Record<PeerId, NetworkAdapter> = {}
+  #adaptersByPeer: Record<PeerId, NetworkAdapterInterface> = {}
 
   #count = 0
   #sessionId: SessionId = Math.random().toString(36).slice(2) as SessionId
   #ephemeralSessionCounts: Record<EphemeralMessageSource, number> = {}
   #readyAdapterCount = 0
-  #adapters: NetworkAdapter[] = []
+  #adapters: NetworkAdapterInterface[] = []
 
   constructor(
-    adapters: NetworkAdapter[],
+    adapters: NetworkAdapterInterface[],
     public peerId = randomPeerId(),
     private peerMetadata: Promise<PeerMetadata>
   ) {
@@ -39,7 +39,7 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     adapters.forEach(a => this.addNetworkAdapter(a))
   }
 
-  addNetworkAdapter(networkAdapter: NetworkAdapter) {
+  addNetworkAdapter(networkAdapter: NetworkAdapterInterface) {
     this.#adapters.push(networkAdapter)
     networkAdapter.once("ready", () => {
       this.#readyAdapterCount++
@@ -73,7 +73,7 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     })
 
     networkAdapter.on("message", msg => {
-      if (!isValidRepoMessage(msg)) {
+      if (!isRepoMessage(msg)) {
         this.#log(`invalid message: ${JSON.stringify(msg)}`)
         return
       }
@@ -105,11 +105,13 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
       })
     })
 
-    this.peerMetadata.then(peerMetadata => {
-      networkAdapter.connect(this.peerId, peerMetadata)
-    }).catch(err => {
-      this.#log("error connecting to network", err)
-    })
+    this.peerMetadata
+      .then(peerMetadata => {
+        networkAdapter.connect(this.peerId, peerMetadata)
+      })
+      .catch(err => {
+        this.#log("error connecting to network", err)
+      })
   }
 
   send(message: MessageContents) {
@@ -146,7 +148,7 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     }
 
     const outbound = prepareMessage(message)
-    this.#log("sending message", outbound)
+    this.#log("sending message %o", outbound)
     peer.send(outbound as RepoMessage)
   }
 

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/StorageAdapter.ts

@@ -1,12 +1,14 @@
+import { StorageAdapterInterface } from "./StorageAdapterInterface.js"
 import { StorageKey, Chunk } from "./types.js"
 
 /** A storage adapter represents some way of storing binary data for a {@link Repo}
+ * @deprecated use {@link StorageAdapterInterface}
  *
  * @remarks
  * `StorageAdapter`s provide a key/value storage interface. The keys are arrays of strings
  * ({@link StorageKey}) and the values are binary blobs.
  */
-export abstract class StorageAdapter {
+export abstract class StorageAdapter implements StorageAdapterInterface {
   /** Load the single value corresponding to `key` */
   abstract load(key: StorageKey): Promise<Uint8Array | undefined>
 

package/src/storage/StorageAdapterInterface.ts

@@ -0,0 +1,34 @@
+import { StorageKey, Chunk } from "./types.js"
+
+/** A storage adapter represents some way of storing binary data for a {@link Repo}
+ *
+ * @remarks
+ * `StorageAdapter`s provide a key/value storage interface. The keys are arrays of strings
+ * ({@link StorageKey}) and the values are binary blobs.
+ */
+export interface StorageAdapterInterface {
+  /** Load the single value corresponding to `key` */
+  load(key: StorageKey): Promise<Uint8Array | undefined>
+
+  /** Save the value `data` to the key `key` */
+  save(key: StorageKey, data: Uint8Array): Promise<void>
+
+  /** Remove the value corresponding to `key` */
+  remove(key: StorageKey): Promise<void>
+
+  /**
+   * Load all values with keys that start with `keyPrefix`.
+   *
+   * @remarks
+   * The `keyprefix` will match any key that starts with the given array. For example:
+   * - `[documentId, "incremental"]` will match all incremental saves
+   * - `[documentId]` will match all data for a given document.
+   *
+   * Be careful! `[documentId]` would also match something like `[documentId, "syncState"]`! We
+   * aren't using this yet but keep it in mind.)
+   */
+  loadRange(keyPrefix: StorageKey): Promise<Chunk[]>
+
+  /** Remove all values with keys that start with `keyPrefix` */
+  removeRange(keyPrefix: StorageKey): Promise<void>
+}

package/src/storage/StorageSubsystem.ts

@@ -3,7 +3,7 @@ import debug from "debug"
 import { headsAreSame } from "../helpers/headsAreSame.js"
 import { mergeArrays } from "../helpers/mergeArrays.js"
 import { type DocumentId } from "../types.js"
-import { StorageAdapter } from "./StorageAdapter.js"
+import { StorageAdapterInterface } from "./StorageAdapterInterface.js"
 import { ChunkInfo, StorageKey, StorageId } from "./types.js"
 import { keyHash, headsHash } from "./keyHash.js"
 import { chunkTypeFromKey } from "./chunkTypeFromKey.js"
@@ -15,7 +15,7 @@ import * as Uuid from "uuid"
  */
 export class StorageSubsystem {
   /** The storage adapter to use for saving and loading documents */
-  #storageAdapter: StorageAdapter
+  #storageAdapter: StorageAdapterInterface
 
   /** Record of the latest heads we've loaded or saved for each document  */
   #storedHeads: Map<DocumentId, A.Heads> = new Map()
@@ -28,7 +28,7 @@ export class StorageSubsystem {
 
   #log = debug(`automerge-repo:storage-subsystem`)
 
-  constructor(storageAdapter: StorageAdapter) {
+  constructor(storageAdapter: StorageAdapterInterface) {
     this.#storageAdapter = storageAdapter
   }
 

package/src/synchronizer/CollectionSynchronizer.ts

@@ -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,11 +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())
-      }).catch(err => {
-        this.#log(`Error loading sync state for ${peerId}: ${err}`)
-      })
+      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] = []
     }
 
@@ -225,8 +227,8 @@ export class DocSynchronizer extends Synchronizer {
   }
 
   beginSync(peerIds: PeerId[]) {
-    const newPeers = new Set(
-      peerIds.filter(peerId => !this.#peers.includes(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
@@ -240,7 +242,7 @@ export class DocSynchronizer extends Synchronizer {
         this.#checkDocUnavailable()
 
         const wasUnavailable = doc === undefined
-        if (wasUnavailable && newPeers.size == 0) {
+        if (wasUnavailable && noPeersWithDocument) {
           return
         }
 
@@ -262,13 +264,15 @@ export class DocSynchronizer extends Synchronizer {
         )
         this.#setSyncState(peerId, reparsedSyncState)
 
-        docPromise.then(doc => {
-          if (doc) {
-            this.#sendSyncMessage(peerId, doc)
-          }
-        }).catch(err => {
-          this.#log(`Error loading doc for ${peerId}: ${err}`)
-        })
+        docPromise
+          .then(doc => {
+            if (doc) {
+              this.#sendSyncMessage(peerId, doc)
+            }
+          })
+          .catch(err => {
+            this.#log(`Error loading doc for ${peerId}: ${err}`)
+          })
       })
     })
   }
@@ -330,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"
     }
@@ -392,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
+}