@automerge/automerge-repo 1.0.0-alpha.2 → 1.0.0-alpha.3

package/dist/synchronizer/DocSynchronizer.js

@@ -1,7 +1,9 @@
 import * as A from "@automerge/automerge";
-import { READY, REQUESTING } from "../DocHandle.js";
+import { READY, REQUESTING, UNAVAILABLE, } from "../DocHandle.js";
 import { Synchronizer } from "./Synchronizer.js";
 import debug from "debug";
+import { isRequestMessage, } from "../network/messages.js";
+import { decode } from "cbor-x";
 /**
  * DocSynchronizer takes a handle to an Automerge document, and receives & dispatches sync messages
  * to bring it inline with all other peers' versions.
@@ -13,9 +15,11 @@ export class DocSynchronizer extends Synchronizer {
     #opsLog;
     /** Active peers */
     #peers = [];
+    #peerDocumentStatuses = {};
     /** Sync state for each peer we've communicated with (including inactive peers) */
     #syncStates = {};
     #pendingSyncMessages = [];
+    #syncStarted = false;
     constructor(handle) {
         super();
         this.handle = handle;
@@ -24,12 +28,16 @@ export class DocSynchronizer extends Synchronizer {
         this.#log = debug(`automerge-repo:docsync:${docId}`);
         this.#opsLog = debug(`automerge-repo:ops:docsync:${docId}`); // Log list of ops of each message
         handle.on("change", () => this.#syncWithPeers());
+        handle.on("ephemeral-message-outbound", payload => this.#broadcastToPeers(payload));
         // Process pending sync messages immediately after the handle becomes ready.
         void (async () => {
             await handle.doc([READY, REQUESTING]);
             this.#processAllPendingSyncMessages();
         })();
     }
+    get peerStates() {
+        return this.#peerDocumentStatuses;
+    }
     get documentId() {
         return this.handle.documentId;
     }
@@ -37,13 +45,32 @@ export class DocSynchronizer extends Synchronizer {
     async #syncWithPeers() {
         this.#log(`syncWithPeers`);
         const doc = await this.handle.doc();
+        if (doc === undefined)
+            return;
         this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
     }
+    async #broadcastToPeers({ data }) {
+        this.#log(`broadcastToPeers`, this.#peers);
+        this.#peers.forEach(peerId => this.#sendEphemeralMessage(peerId, data));
+    }
+    #sendEphemeralMessage(peerId, data) {
+        this.#log(`sendEphemeralMessage ->${peerId}`);
+        this.emit("message", {
+            type: "ephemeral",
+            targetId: peerId,
+            documentId: this.handle.documentId,
+            data,
+        });
+    }
     #getSyncState(peerId) {
         if (!this.#peers.includes(peerId)) {
             this.#log("adding a new peer", peerId);
             this.#peers.push(peerId);
         }
+        // when a peer is added, we don't know if it has the document or not
+        if (!(peerId in this.#peerDocumentStatuses)) {
+            this.#peerDocumentStatuses[peerId] = "unknown";
+        }
         return this.#syncStates[peerId] ?? A.initSyncState();
     }
     #setSyncState(peerId, syncState) {
@@ -59,16 +86,32 @@ export class DocSynchronizer extends Synchronizer {
         this.#setSyncState(peerId, newSyncState);
         if (message) {
             this.#logMessage(`sendSyncMessage 🡒 ${peerId}`, message);
-            const channelId = this.handle.documentId;
-            this.emit("message", {
-                targetId: peerId,
-                channelId,
-                message,
-                broadcast: false,
-            });
-        }
-        else {
-            this.#log(`sendSyncMessage ->${peerId} [no message generated]`);
+            const decoded = A.decodeSyncMessage(message);
+            if (!this.handle.isReady() &&
+                decoded.heads.length === 0 &&
+                newSyncState.sharedHeads.length === 0 &&
+                !Object.values(this.#peerDocumentStatuses).includes("has") &&
+                this.#peerDocumentStatuses[peerId] === "unknown") {
+                // we don't have the document (or access to it), so we request it
+                this.emit("message", {
+                    type: "request",
+                    targetId: peerId,
+                    documentId: this.handle.documentId,
+                    data: message,
+                });
+            }
+            else {
+                this.emit("message", {
+                    type: "sync",
+                    targetId: peerId,
+                    data: message,
+                    documentId: this.handle.documentId,
+                });
+            }
+            // if we have sent heads, then the peer now has or will have the document
+            if (decoded.heads.length > 0) {
+                this.#peerDocumentStatuses[peerId] = "has";
+            }
         }
     }
     #logMessage = (label, message) => {
@@ -89,48 +132,121 @@ export class DocSynchronizer extends Synchronizer {
     hasPeer(peerId) {
         return this.#peers.includes(peerId);
     }
-    beginSync(peerId) {
-        this.#log(`beginSync: ${peerId}`);
+    beginSync(peerIds) {
+        this.#log(`beginSync: ${peerIds.join(", ")}`);
         // 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
-        void this.handle.doc([READY, REQUESTING]).then(doc => {
+        void this.handle.doc([READY, REQUESTING, UNAVAILABLE]).then(doc => {
+            // if we don't have any peers, then we can say the document is unavailable
             // HACK: if we have a sync state already, we round-trip it through the encoding system to make
             // sure state is preserved. This prevents an infinite loop caused by failed attempts to send
             // messages during disconnection.
             // TODO: cover that case with a test and remove this hack
-            const syncStateRaw = this.#getSyncState(peerId);
-            const syncState = A.decodeSyncState(A.encodeSyncState(syncStateRaw));
-            this.#setSyncState(peerId, syncState);
-            this.#sendSyncMessage(peerId, doc);
+            peerIds.forEach(peerId => {
+                const syncStateRaw = this.#getSyncState(peerId);
+                const syncState = A.decodeSyncState(A.encodeSyncState(syncStateRaw));
+                this.#setSyncState(peerId, syncState);
+            });
+            // we register out peers first, then say that sync has started
+            this.#syncStarted = true;
+            this.#checkDocUnavailable();
+            if (doc === undefined)
+                return;
+            peerIds.forEach(peerId => {
+                this.#sendSyncMessage(peerId, doc);
+            });
         });
     }
     endSync(peerId) {
         this.#log(`removing peer ${peerId}`);
         this.#peers = this.#peers.filter(p => p !== peerId);
     }
-    receiveSyncMessage(peerId, channelId, message) {
-        if (channelId !== this.handle.documentId)
+    receiveMessage(message) {
+        switch (message.type) {
+            case "sync":
+            case "request":
+                this.receiveSyncMessage(message);
+                break;
+            case "ephemeral":
+                this.receiveEphemeralMessage(message);
+                break;
+            case "doc-unavailable":
+                this.#peerDocumentStatuses[message.senderId] = "unavailable";
+                this.#checkDocUnavailable();
+                break;
+            default:
+                throw new Error(`unknown message type: ${message}`);
+        }
+    }
+    receiveEphemeralMessage(message) {
+        if (message.documentId !== this.handle.documentId)
+            throw new Error(`channelId doesn't match documentId`);
+        const { senderId, data } = message;
+        const contents = decode(data);
+        this.handle.emit("ephemeral-message", {
+            handle: this.handle,
+            senderId,
+            message: contents,
+        });
+        this.#peers.forEach(peerId => {
+            if (peerId === senderId)
+                return;
+            this.emit("message", {
+                ...message,
+                targetId: peerId,
+            });
+        });
+    }
+    receiveSyncMessage(message) {
+        if (message.documentId !== this.handle.documentId)
             throw new Error(`channelId doesn't match documentId`);
         // We need to block receiving the syncMessages until we've checked local storage
-        if (!this.handle.inState([READY, REQUESTING])) {
-            this.#pendingSyncMessages.push({ peerId, message });
+        if (!this.handle.inState([READY, REQUESTING, UNAVAILABLE])) {
+            this.#pendingSyncMessages.push(message);
             return;
         }
         this.#processAllPendingSyncMessages();
-        this.#processSyncMessage(peerId, message);
+        this.#processSyncMessage(message);
     }
-    #processSyncMessage(peerId, message) {
+    #processSyncMessage(message) {
+        if (isRequestMessage(message)) {
+            this.#peerDocumentStatuses[message.senderId] = "wants";
+        }
+        this.#checkDocUnavailable();
+        // if the message has heads, then the peer has the document
+        if (A.decodeSyncMessage(message.data).heads.length > 0) {
+            this.#peerDocumentStatuses[message.senderId] = "has";
+        }
         this.handle.update(doc => {
-            const [newDoc, newSyncState] = A.receiveSyncMessage(doc, this.#getSyncState(peerId), message);
-            this.#setSyncState(peerId, newSyncState);
+            const [newDoc, newSyncState] = A.receiveSyncMessage(doc, this.#getSyncState(message.senderId), message.data);
+            this.#setSyncState(message.senderId, newSyncState);
             // respond to just this peer (as required)
-            this.#sendSyncMessage(peerId, doc);
+            this.#sendSyncMessage(message.senderId, doc);
             return newDoc;
         });
+        this.#checkDocUnavailable();
+    }
+    #checkDocUnavailable() {
+        // if we know none of the peers have the document, tell all our peers that we don't either
+        if (this.#syncStarted &&
+            this.handle.inState([REQUESTING]) &&
+            this.#peers.every(peerId => this.#peerDocumentStatuses[peerId] === "unavailable" ||
+                this.#peerDocumentStatuses[peerId] === "wants")) {
+            this.#peers
+                .filter(peerId => this.#peerDocumentStatuses[peerId] === "wants")
+                .forEach(peerId => {
+                this.emit("message", {
+                    type: "doc-unavailable",
+                    documentId: this.handle.documentId,
+                    targetId: peerId,
+                });
+            });
+            this.handle.unavailable();
+        }
     }
     #processAllPendingSyncMessages() {
-        for (const { peerId, message } of this.#pendingSyncMessages) {
-            this.#processSyncMessage(peerId, message);
+        for (const message of this.#pendingSyncMessages) {
+            this.#processSyncMessage(message);
         }
         this.#pendingSyncMessages = [];
     }

package/dist/synchronizer/Synchronizer.d.ts

@@ -1,10 +1,9 @@
 import EventEmitter from "eventemitter3";
-import { ChannelId, PeerId } from "../types.js";
-import { MessagePayload } from "../network/NetworkAdapter.js";
+import { Message, MessageContents } from "../network/messages.js";
 export declare abstract class Synchronizer extends EventEmitter<SynchronizerEvents> {
-    abstract receiveSyncMessage(peerId: PeerId, channelId: ChannelId, message: Uint8Array): void;
+    abstract receiveMessage(message: Message): void;
 }
 export interface SynchronizerEvents {
-    message: (arg: MessagePayload) => void;
+    message: (arg: MessageContents) => void;
 }
 //# sourceMappingURL=Synchronizer.d.ts.map

package/dist/synchronizer/Synchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAE7D,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,kBAAkB,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU,GAClB,IAAI;CACR;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACvC"}
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAEjE,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC"}

package/dist/types.d.ts

@@ -10,7 +10,5 @@ export type BinaryDocumentId = Uint8Array & {
 export type PeerId = string & {
     __peerId: false;
 };
-export type ChannelId = string & {
-    __channelId: false;
-};
+export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAC3D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAC3D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AAEjD,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,IAAI,CAAC,SAAS,GAAG,GAChE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACV,KAAK,CAAA"}

package/fuzz/fuzz.ts

@@ -2,7 +2,7 @@ import assert from "assert"
 import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel"
 import * as Automerge from "@automerge/automerge"
 
-import { ChannelId, DocHandle, DocumentId, PeerId, SharePolicy } from "../src"
+import { DocHandle, DocumentId, PeerId, SharePolicy } from "../src"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import { Repo } from "../src/Repo.js"
@@ -105,9 +105,9 @@ for (let i = 0; i < 100000; i++) {
   })
 
   await pause(0)
-  const a = await aliceRepo.find(doc.documentId).value()
-  const b = await bobRepo.find(doc.documentId).value()
-  const c = await charlieRepo.find(doc.documentId).value()
+  const a = await aliceRepo.find(doc.url).doc()
+  const b = await bobRepo.find(doc.url).doc()
+  const c = await charlieRepo.find(doc.url).doc()
   assert.deepStrictEqual(a, b, "A and B should be equal")
   assert.deepStrictEqual(b, c, "B and C should be equal")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -65,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b5830dde8f135b694809698aaad2a9fdc79a9898"
+  "gitHead": "0ed108273084319aeea64ceccb49c3d58709f107"
 }

package/src/DocCollection.ts

@@ -72,8 +72,8 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
     // - pass a "reify" function that takes a `<any>` and returns `<T>`
 
     // Generate a new UUID and store it in the buffer
-    const { encodedDocumentId } = parseAutomergeUrl(generateAutomergeUrl())
-    const handle = this.#getHandle<T>(encodedDocumentId, true) as DocHandle<T>
+    const { documentId } = parseAutomergeUrl(generateAutomergeUrl())
+    const handle = this.#getHandle<T>(documentId, true) as DocHandle<T>
     this.emit("document", { handle })
     return handle
   }
@@ -90,12 +90,21 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
       throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`)
     }
 
-    const { encodedDocumentId } = parseAutomergeUrl(automergeUrl)
+    const { documentId } = parseAutomergeUrl(automergeUrl)
     // If we have the handle cached, return it
-    if (this.#handleCache[encodedDocumentId])
-      return this.#handleCache[encodedDocumentId]
+    if (this.#handleCache[documentId]) {
+      if (this.#handleCache[documentId].isUnavailable()) {
+        // this ensures that the event fires after the handle has been returned
+        setTimeout(() => {
+          this.#handleCache[documentId].emit("unavailable", {
+            handle: this.#handleCache[documentId],
+          })
+        })
+      }
+      return this.#handleCache[documentId]
+    }
 
-    const handle = this.#getHandle<T>(encodedDocumentId, false) as DocHandle<T>
+    const handle = this.#getHandle<T>(documentId, false) as DocHandle<T>
     this.emit("document", { handle })
     return handle
   }
@@ -105,7 +114,7 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
     id: DocumentId | AutomergeUrl
   ) {
     if (isValidAutomergeUrl(id)) {
-      ;({ encodedDocumentId: id } = parseAutomergeUrl(id))
+      ;({ documentId: id } = parseAutomergeUrl(id))
     }
 
     const handle = this.#getHandle(id, false)
@@ -113,7 +122,7 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
 
     delete this.#handleCache[id]
     this.emit("delete-document", {
-      encodedDocumentId: id,
+      documentId: id,
     })
   }
 }
@@ -122,6 +131,7 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
 interface DocCollectionEvents {
   document: (arg: DocumentPayload) => void
   "delete-document": (arg: DeleteDocumentPayload) => void
+  "unavailable-document": (arg: DeleteDocumentPayload) => void
 }
 
 interface DocumentPayload {
@@ -129,5 +139,5 @@ interface DocumentPayload {
 }
 
 interface DeleteDocumentPayload {
-  encodedDocumentId: DocumentId
+  documentId: DocumentId
 }

package/src/DocHandle.ts

@@ -17,8 +17,9 @@ import { waitFor } from "xstate/lib/waitFor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { pause } from "./helpers/pause.js"
 import { TimeoutError, withTimeout } from "./helpers/withTimeout.js"
-import type { ChannelId, DocumentId, PeerId, AutomergeUrl } from "./types.js"
+import type { DocumentId, PeerId, AutomergeUrl } from "./types.js"
 import { stringifyAutomergeUrl } from "./DocUrl.js"
+import { encode } from "cbor-x"
 
 /** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
 export class DocHandle<T> //
@@ -92,6 +93,10 @@ export class DocHandle<T> //
             },
             requesting: {
               on: {
+                MARK_UNAVAILABLE: {
+                  target: UNAVAILABLE,
+                  actions: "onUnavailable",
+                },
                 // UPDATE is called by the Repo when we receive changes from the network
                 UPDATE: { actions: "onUpdate" },
                 // REQUEST_COMPLETE is called from `onUpdate` when the doc has been fully loaded from the network
@@ -118,6 +123,14 @@ export class DocHandle<T> //
             deleted: {
               type: "final",
             },
+            unavailable: {
+              on: {
+                UPDATE: { actions: "onUpdate" },
+                // REQUEST_COMPLETE is called from `onUpdate` when the doc has been fully loaded from the network
+                REQUEST_COMPLETE: { target: READY },
+                DELETE: { actions: "onDelete", target: DELETED },
+              },
+            },
           },
         },
 
@@ -136,6 +149,12 @@ export class DocHandle<T> //
               this.emit("delete", { handle: this })
               return { doc: undefined }
             }),
+            onUnavailable: assign(context => {
+              const { doc } = context
+
+              this.emit("unavailable", { handle: this })
+              return { doc }
+            }),
           },
         }
       )
@@ -144,9 +163,12 @@ export class DocHandle<T> //
         const oldDoc = history?.context?.doc
         const newDoc = context.doc
 
-        console.log(`${event} → ${state}`, newDoc)
+        this.#log(`${history?.value}: ${event.type} → ${state}`, newDoc)
 
-        const docChanged = newDoc && oldDoc && !headsAreSame(A.getHeads(newDoc), A.getHeads(oldDoc))
+        const docChanged =
+          newDoc &&
+          oldDoc &&
+          !headsAreSame(A.getHeads(newDoc), A.getHeads(oldDoc))
         if (docChanged) {
           this.emit("heads-changed", { handle: this, doc: newDoc })
 
@@ -210,6 +232,7 @@ export class DocHandle<T> //
    * @returns true if the document has been marked as deleted
    */
   isDeleted = () => this.inState([HandleState.DELETED])
+  isUnavailable = () => this.inState([HandleState.UNAVAILABLE])
   inState = (states: HandleState[]) =>
     states.some(this.#machine?.getSnapshot().matches)
 
@@ -234,7 +257,9 @@ export class DocHandle<T> //
    *
    * @param {awaitStates=[READY]} optional states to wait for, such as "LOADING". mostly for internal use.
    */
-  async doc(awaitStates: HandleState[] = [READY]): Promise<A.Doc<T>> {
+  async doc(
+    awaitStates: HandleState[] = [READY, UNAVAILABLE]
+  ): Promise<A.Doc<T> | undefined> {
     await pause() // yield one tick because reasons
     try {
       // wait for the document to enter one of the desired states
@@ -245,7 +270,7 @@ export class DocHandle<T> //
       else throw error
     }
     // Return the document
-    return this.#doc
+    return !this.isUnavailable() ? this.#doc : undefined
   }
 
   /**
@@ -308,6 +333,10 @@ export class DocHandle<T> //
     })
   }
 
+  unavailable() {
+    this.#machine.send(MARK_UNAVAILABLE)
+  }
+
   /** `request` is called by the repo when the document is not found in storage */
   request() {
     if (this.#state === LOADING) this.#machine.send(REQUEST)
@@ -317,6 +346,19 @@ export class DocHandle<T> //
   delete() {
     this.#machine.send(DELETE)
   }
+
+  /** `broadcast` sends an arbitrary ephemeral message out to all reachable peers who would receive sync messages from you
+   * it has no guarantee of delivery, and is not persisted to the underlying automerge doc in any way.
+   * messages will have a sending PeerId but this is *not* a useful user identifier.
+   * a user could have multiple tabs open and would appear as multiple PeerIds.
+   * every message source must have a unique PeerId.
+   */
+  broadcast(message: any) {
+    this.emit("ephemeral-message-outbound", {
+      handle: this,
+      data: encode(message),
+    })
+  }
 }
 
 // WRAPPER CLASS TYPES
@@ -328,7 +370,7 @@ interface DocHandleOptions {
 
 export interface DocHandleMessagePayload {
   destinationId: PeerId
-  channelId: ChannelId
+  documentId: DocumentId
   data: Uint8Array
 }
 
@@ -348,10 +390,26 @@ export interface DocHandleChangePayload<T> {
   patchInfo: A.PatchInfo<T>
 }
 
+export interface DocHandleEphemeralMessagePayload {
+  handle: DocHandle<any>
+  senderId: PeerId
+  message: unknown
+}
+
+export interface DocHandleOutboundEphemeralMessagePayload {
+  handle: DocHandle<any>
+  data: Uint8Array
+}
+
 export interface DocHandleEvents<T> {
   "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
+  unavailable: (payload: DocHandleDeletePayload<T>) => void
+  "ephemeral-message": (payload: DocHandleEphemeralMessagePayload) => void
+  "ephemeral-message-outbound": (
+    payload: DocHandleOutboundEphemeralMessagePayload
+  ) => void
 }
 
 // STATE MACHINE TYPES
@@ -365,6 +423,7 @@ export const HandleState = {
   READY: "ready",
   FAILED: "failed",
   DELETED: "deleted",
+  UNAVAILABLE: "unavailable",
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]
 
@@ -392,6 +451,7 @@ export const Event = {
   UPDATE: "UPDATE",
   TIMEOUT: "TIMEOUT",
   DELETE: "DELETE",
+  MARK_UNAVAILABLE: "MARK_UNAVAILABLE",
 } as const
 type Event = (typeof Event)[keyof typeof Event]
 
@@ -405,6 +465,7 @@ type UpdateEvent<T> = {
   payload: { callback: (doc: A.Doc<T>) => A.Doc<T> }
 }
 type TimeoutEvent = { type: typeof TIMEOUT }
+type MarkUnavailableEvent = { type: typeof MARK_UNAVAILABLE }
 
 type DocHandleEvent<T> =
   | CreateEvent
@@ -414,6 +475,7 @@ type DocHandleEvent<T> =
   | UpdateEvent<T>
   | TimeoutEvent
   | DeleteEvent
+  | MarkUnavailableEvent
 
 type DocHandleXstateMachine<T> = Interpreter<
   DocHandleContext<T>,
@@ -432,7 +494,22 @@ type DocHandleXstateMachine<T> = Interpreter<
 >
 
 // CONSTANTS
-
-export const { IDLE, LOADING, REQUESTING, READY, FAILED, DELETED } = HandleState
-const { CREATE, FIND, REQUEST, UPDATE, TIMEOUT, DELETE, REQUEST_COMPLETE } =
-  Event
+export const {
+  IDLE,
+  LOADING,
+  REQUESTING,
+  READY,
+  FAILED,
+  DELETED,
+  UNAVAILABLE,
+} = HandleState
+const {
+  CREATE,
+  FIND,
+  REQUEST,
+  UPDATE,
+  TIMEOUT,
+  DELETE,
+  REQUEST_COMPLETE,
+  MARK_UNAVAILABLE,
+} = Event

package/src/DocUrl.ts

@@ -12,12 +12,12 @@ export const urlPrefix = "automerge:"
  * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
  *
  * @param url
- * @returns { documentId: Uint8Array(16), encodedDocumentId: bs58check.encode(documentId) }
+ * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
  */
 export const parseAutomergeUrl = (url: AutomergeUrl) => {
-  const { binaryDocumentId: binaryDocumentId, encodedDocumentId } = parts(url)
+  const { binaryDocumentId, documentId } = parts(url)
   if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
-  return { binaryDocumentId, encodedDocumentId }
+  return { binaryDocumentId, documentId }
 }
 
 interface StringifyAutomergeUrlOptions {
@@ -28,7 +28,7 @@ interface StringifyAutomergeUrlOptions {
  * Given a documentId in either canonical form, return an Automerge URL
  * Throws on invalid input.
  * Note: this is an object because we anticipate adding fields in the future.
- * @param { documentId: EncodedDocumentId | DocumentId }
+ * @param { documentId: BinaryDocumentId | DocumentId }
  * @returns AutomergeUrl
  */
 export const stringifyAutomergeUrl = ({
@@ -79,12 +79,12 @@ export const binaryToDocumentId = (docId: BinaryDocumentId): DocumentId =>
  * eventually this could include things like heads, so we use this structure
  * we return both a binary & string-encoded version of the document ID
  * @param str
- * @returns { binaryDocumentId, encodedDocumentId }
+ * @returns { binaryDocumentId, documentId }
  */
 const parts = (str: string) => {
   const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [m, docMatch] = str.match(regex) || []
-  const encodedDocumentId = docMatch as DocumentId
-  const binaryDocumentId = documentIdToBinary(encodedDocumentId)
-  return { binaryDocumentId, encodedDocumentId }
+  const [_, docMatch] = str.match(regex) || []
+  const documentId = docMatch as DocumentId
+  const binaryDocumentId = documentIdToBinary(documentId)
+  return { binaryDocumentId, documentId }
 }