@automerge/automerge-repo 2.0.0-collectionsync-alpha.1 → 2.0.1

package/dist/synchronizer/DocSynchronizer.js

@@ -1,9 +1,10 @@
-import * as A from "@automerge/automerge/slim/next";
+import { next as A } from "@automerge/automerge/slim";
 import { decode } from "cbor-x";
 import debug from "debug";
 import { READY, REQUESTING, UNAVAILABLE, } from "../DocHandle.js";
+import { isRequestMessage, } from "../network/messages.js";
 import { Synchronizer } from "./Synchronizer.js";
-import { parseAutomergeUrl } from "../AutomergeUrl.js";
+import { throttle } from "../helpers/throttle.js";
 /**
  * DocSynchronizer takes a handle to an Automerge document, and receives & dispatches sync messages
  * to bring it inline with all other peers' versions.
@@ -13,43 +14,49 @@ export class DocSynchronizer extends Synchronizer {
     syncDebounceRate = 100;
     /** Active peers */
     #peers = [];
+    #pendingSyncStateCallbacks = {};
     #peerDocumentStatuses = {};
-    #lastSaveOffset = null;
+    /** Sync state for each peer we've communicated with (including inactive peers) */
+    #syncStates = {};
+    #pendingSyncMessages = [];
+    // We keep this around at least in part for debugging.
+    // eslint-disable-next-line no-unused-private-class-members
+    #peerId;
     #syncStarted = false;
-    #beelay;
     #handle;
-    #docId;
-    constructor({ handle, beelay }) {
+    #onLoadSyncState;
+    constructor({ handle, peerId, onLoadSyncState }) {
         super();
+        this.#peerId = peerId;
         this.#handle = handle;
-        this.#beelay = beelay;
-        this.#docId = this.#handle.documentId;
-        this.#log = debug(`automerge-repo:docsync:${this.#handle.documentId}`);
+        this.#onLoadSyncState =
+            onLoadSyncState ?? (() => Promise.resolve(undefined));
+        const docId = handle.documentId.slice(0, 5);
+        this.#log = debug(`automerge-repo:docsync:${docId}`);
+        handle.on("change", throttle(() => this.#syncWithPeers(), this.syncDebounceRate));
         handle.on("ephemeral-message-outbound", payload => this.#broadcastToPeers(payload));
-        handle.on("change", changeInfo => {
-            const newLinks = changeInfo.patches
-                .map(patch => {
-                if (patch.action === "put") {
-                    if (patch.value instanceof A.Link) {
-                        return patch.value;
-                    }
-                }
-                return null;
-            })
-                .filter(v => v != null);
-            for (const link of newLinks) {
-                const { documentId: target } = parseAutomergeUrl(link.target);
-                this.#beelay.addLink({ from: this.#handle.documentId, to: target });
-            }
-        });
+        // Process pending sync messages immediately after the handle becomes ready.
+        void (async () => {
+            this.#processAllPendingSyncMessages();
+        })();
     }
     get peerStates() {
         return this.#peerDocumentStatuses;
     }
     get documentId() {
-        return this.#docId;
+        return this.#handle.documentId;
     }
     /// PRIVATE
+    async #syncWithPeers() {
+        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({ data, }) {
         this.#log(`broadcastToPeers`, this.#peers);
         this.#peers.forEach(peerId => this.#sendEphemeralMessage(peerId, data));
@@ -59,78 +66,155 @@ export class DocSynchronizer extends Synchronizer {
         const message = {
             type: "ephemeral",
             targetId: peerId,
-            documentId: this.documentId,
+            documentId: this.#handle.documentId,
             data,
         };
         this.emit("message", message);
     }
+    #withSyncState(peerId, callback) {
+        this.#addPeer(peerId);
+        if (!(peerId in this.#peerDocumentStatuses)) {
+            this.#peerDocumentStatuses[peerId] = "unknown";
+        }
+        const syncState = this.#syncStates[peerId];
+        if (syncState) {
+            callback(syncState);
+            return;
+        }
+        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}`);
+            });
+            pendingCallbacks = this.#pendingSyncStateCallbacks[peerId] = [];
+        }
+        pendingCallbacks.push(callback);
+    }
+    #addPeer(peerId) {
+        if (!this.#peers.includes(peerId)) {
+            this.#peers.push(peerId);
+            this.emit("open-doc", { documentId: this.documentId, peerId });
+        }
+    }
+    #initSyncState(peerId, syncState) {
+        const pendingCallbacks = this.#pendingSyncStateCallbacks[peerId];
+        if (pendingCallbacks) {
+            for (const callback of pendingCallbacks) {
+                callback(syncState);
+            }
+        }
+        delete this.#pendingSyncStateCallbacks[peerId];
+        this.#syncStates[peerId] = syncState;
+    }
+    #setSyncState(peerId, syncState) {
+        this.#syncStates[peerId] = syncState;
+        this.emit("sync-state", {
+            peerId,
+            syncState,
+            documentId: this.#handle.documentId,
+        });
+    }
+    #sendSyncMessage(peerId, doc) {
+        this.#log(`sendSyncMessage ->${peerId}`);
+        this.#withSyncState(peerId, syncState => {
+            const [newSyncState, message] = A.generateSyncMessage(doc, syncState);
+            if (message) {
+                this.#setSyncState(peerId, newSyncState);
+                const isNew = A.getHeads(doc).length === 0;
+                if (!this.#handle.isReady() &&
+                    isNew &&
+                    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 (!isNew) {
+                    this.#peerDocumentStatuses[peerId] = "has";
+                }
+            }
+        });
+    }
     /// PUBLIC
     hasPeer(peerId) {
         return this.#peers.includes(peerId);
     }
-    beginSync(peerIds) {
-        this.#log(`beginSync: ${peerIds.join(", ")}`);
-        const docPromise = this.#handle
+    async beginSync(peerIds) {
+        void this.#handle
             .whenReady([READY, REQUESTING, UNAVAILABLE])
-            .then(doc => {
+            .then(() => {
             this.#syncStarted = true;
             this.#checkDocUnavailable();
         })
-            // TODO: handle this error
-            .catch(() => { });
+            .catch(e => {
+            console.log("caught whenready", e);
+            this.#syncStarted = true;
+            this.#checkDocUnavailable();
+        });
+        const peersWithDocument = this.#peers.some(peerId => {
+            return this.#peerDocumentStatuses[peerId] == "has";
+        });
+        if (peersWithDocument) {
+            await this.#handle.whenReady();
+        }
         peerIds.forEach(peerId => {
-            if (!this.#peers.includes(peerId)) {
-                this.#peers.push(peerId);
-            }
-            else {
-                return;
-            }
-            this.#peerDocumentStatuses[peerId] = "unknown";
-            docPromise.then(() => {
-                this.#syncStarted = true;
-                this.#log(`beginning sync with ${peerId} for doc: ${this.documentId}`);
-                this.#beelay
-                    .syncDoc(this.documentId, peerId)
-                    .then(({ snapshot, found }) => {
-                    this.#peerDocumentStatuses[peerId] = found ? "has" : "unavailable";
-                    // this.#log("synced snapshot: ", snapshot)
-                    if (found) {
-                        this.#beelay.loadDocument(this.#docId).then(commitOrBundles => {
-                            if (commitOrBundles != null) {
-                                this.#handle?.update(d => {
-                                    let doc = d;
-                                    for (const commitOrBundle of commitOrBundles) {
-                                        doc = A.loadIncremental(doc, commitOrBundle.contents);
-                                    }
-                                    return doc;
-                                });
-                                this.#checkDocUnavailable();
-                            }
-                        });
-                    }
-                    else {
-                        this.#checkDocUnavailable();
+            this.#withSyncState(peerId, syncState => {
+                // 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 reparsedSyncState = A.decodeSyncState(A.encodeSyncState(syncState));
+                this.#setSyncState(peerId, reparsedSyncState);
+                // 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();
+                    const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
+                    const wasUnavailable = doc === undefined;
+                    if (wasUnavailable && noPeersWithDocument) {
+                        return;
                     }
-                    this.#beelay.listen(peerId, snapshot);
+                    // If the doc is unavailable we still need a blank document to generate
+                    // the sync message from
+                    this.#sendSyncMessage(peerId, doc ?? A.init());
+                })
+                    .catch(err => {
+                    this.#log(`Error loading doc for ${peerId}: ${err}`);
                 });
             });
         });
     }
-    peerWantsDocument(peerId) {
-        this.#peerDocumentStatuses[peerId] = "wants";
-        if (!this.#peers.includes(peerId)) {
-            this.beginSync([peerId]);
-        }
-    }
     endSync(peerId) {
         this.#log(`removing peer ${peerId}`);
         this.#peers = this.#peers.filter(p => p !== peerId);
-        this.#beelay.cancelListens(peerId);
     }
     receiveMessage(message) {
         switch (message.type) {
             case "sync":
             case "request":
+                this.receiveSyncMessage(message);
                 break;
             case "ephemeral":
                 this.receiveEphemeralMessage(message);
@@ -144,7 +228,7 @@ export class DocSynchronizer extends Synchronizer {
         }
     }
     receiveEphemeralMessage(message) {
-        if (message.documentId !== this.documentId)
+        if (message.documentId !== this.#handle.documentId)
             throw new Error(`channelId doesn't match documentId`);
         const { senderId, data } = message;
         const contents = decode(new Uint8Array(data));
@@ -162,7 +246,45 @@ export class DocSynchronizer extends Synchronizer {
             });
         });
     }
-    receiveSyncMessage(message) { }
+    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, UNAVAILABLE])) {
+            this.#pendingSyncMessages.push({ message, received: new Date() });
+            return;
+        }
+        this.#processAllPendingSyncMessages();
+        this.#processSyncMessage(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.#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);
+                // respond to just this peer (as required)
+                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 &&
@@ -174,20 +296,24 @@ export class DocSynchronizer extends Synchronizer {
                 .forEach(peerId => {
                 const message = {
                     type: "doc-unavailable",
-                    documentId: this.documentId,
+                    documentId: this.#handle.documentId,
                     targetId: peerId,
                 };
                 this.emit("message", message);
             });
-            if (this.#handle) {
-                this.#handle.unavailable();
-            }
+            this.#handle.unavailable();
+        }
+    }
+    #processAllPendingSyncMessages() {
+        for (const message of this.#pendingSyncMessages) {
+            this.#processSyncMessage(message.message);
         }
+        this.#pendingSyncMessages = [];
     }
     metrics() {
         return {
             peers: this.#peers,
-            size: this.#handle?.metrics(),
+            size: this.#handle.metrics(),
         };
     }
 }

package/dist/types.d.ts

@@ -26,12 +26,15 @@ export type LegacyDocumentId = string & {
     __legacyDocumentId: true;
 };
 export type AnyDocumentId = AutomergeUrl | DocumentId | BinaryDocumentId | LegacyDocumentId;
+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;
+    __sessionId: true;
 };
 //# 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;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAExD,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,gBAAgB,CAAA;AAEpB,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhD,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAExD,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,gBAAgB,CAAA;AAGpB,MAAM,MAAM,QAAQ,GAAG,MAAM,EAAE,GAAG;IAAE,mBAAmB,EAAE,OAAO,CAAA;CAAE,CAAA;AAElE,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhD,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,CAAA"}

package/fuzz/fuzz.ts

@@ -107,9 +107,9 @@ for (let i = 0; i < 100000; i++) {
   })
 
   await pause(0)
-  const a = await aliceRepo.find(doc.url).doc()
-  const b = await bobRepo.find(doc.url).doc()
-  const c = await charlieRepo.find(doc.url).doc()
+  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": "2.0.0-collectionsync-alpha.1",
+  "version": "2.0.1",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -20,17 +20,16 @@
   },
   "devDependencies": {
     "http-server": "^14.1.0",
+    "ts-node": "^10.9.2",
     "vite": "^5.0.8"
   },
   "dependencies": {
-    "@automerge/automerge": "3.0.0-collectionsync-alpha.1",
+    "@automerge/automerge": "^2.2.8",
     "bs58check": "^3.0.1",
     "cbor-x": "^1.3.0",
     "debug": "^4.3.4",
     "eventemitter3": "^5.0.1",
     "fast-sha256": "^1.3.0",
-    "tiny-typed-emitter": "^2.1.0",
-    "ts-node": "^10.9.1",
     "uuid": "^9.0.0",
     "xstate": "^5.9.1"
   },
@@ -60,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0a639a7d57bcee4e0a87890e6592b9582c2a5d6f"
+  "gitHead": "6e8d13f3aebcbc31ff3dd478be85191eee1ad120"
 }

package/src/AutomergeUrl.ts

@@ -4,26 +4,54 @@ import type {
   BinaryDocumentId,
   DocumentId,
   AnyDocumentId,
+  UrlHeads,
 } from "./types.js"
+
 import * as Uuid from "uuid"
 import bs58check from "bs58check"
+import {
+  uint8ArrayFromHexString,
+  uint8ArrayToHexString,
+} from "./helpers/bufferFromHex.js"
+
+import type { Heads as AutomergeHeads } from "@automerge/automerge/slim"
 
 export const urlPrefix = "automerge:"
 
+interface ParsedAutomergeUrl {
+  /** unencoded DocumentId */
+  binaryDocumentId: BinaryDocumentId
+  /** bs58 encoded DocumentId */
+  documentId: DocumentId
+  /** Optional array of heads, if specified in URL */
+  heads?: UrlHeads
+  /** Optional hex array of heads, in Automerge core format */
+  hexHeads?: string[] // AKA: heads
+}
+
 /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
-export const parseAutomergeUrl = (url: AutomergeUrl) => {
+export const parseAutomergeUrl = (url: AutomergeUrl): ParsedAutomergeUrl => {
+  const [baseUrl, headsSection, ...rest] = url.split("#")
+  if (rest.length > 0) {
+    throw new Error("Invalid URL: contains multiple heads sections")
+  }
   const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [, docMatch] = url.match(regex) || []
+  const [, docMatch] = baseUrl.match(regex) || []
   const documentId = docMatch as DocumentId
   const binaryDocumentId = documentIdToBinary(documentId)
 
   if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
-  return {
-    /** unencoded DocumentId */
-    binaryDocumentId,
-    /** encoded DocumentId */
-    documentId,
-  }
+  if (headsSection === undefined) return { binaryDocumentId, documentId }
+
+  const heads = (headsSection === "" ? [] : headsSection.split("|")) as UrlHeads
+  const hexHeads = heads.map(head => {
+    try {
+      return uint8ArrayToHexString(bs58check.decode(head))
+    } catch (e) {
+      throw new Error(`Invalid head in URL: ${head}`)
+    }
+  })
+  return { binaryDocumentId, hexHeads, documentId, heads }
 }
 
 /**
@@ -32,38 +60,78 @@ export const parseAutomergeUrl = (url: AutomergeUrl) => {
  */
 export const stringifyAutomergeUrl = (
   arg: UrlOptions | DocumentId | BinaryDocumentId
-) => {
-  const documentId =
-    arg instanceof Uint8Array || typeof arg === "string"
-      ? arg
-      : "documentId" in arg
-      ? arg.documentId
-      : undefined
+): AutomergeUrl => {
+  if (arg instanceof Uint8Array || typeof arg === "string") {
+    return (urlPrefix +
+      (arg instanceof Uint8Array
+        ? binaryToDocumentId(arg)
+        : arg)) as AutomergeUrl
+  }
+
+  const { documentId, heads = undefined } = arg
+
+  if (documentId === undefined)
+    throw new Error("Invalid documentId: " + documentId)
 
   const encodedDocumentId =
     documentId instanceof Uint8Array
       ? binaryToDocumentId(documentId)
-      : typeof documentId === "string"
-      ? documentId
-      : undefined
+      : documentId
+
+  let url = `${urlPrefix}${encodedDocumentId}`
+
+  if (heads !== undefined) {
+    heads.forEach(head => {
+      try {
+        bs58check.decode(head)
+      } catch (e) {
+        throw new Error(`Invalid head: ${head}`)
+      }
+    })
+    url += "#" + heads.join("|")
+  }
 
-  if (encodedDocumentId === undefined)
-    throw new Error("Invalid documentId: " + documentId)
+  return url as AutomergeUrl
+}
 
-  return (urlPrefix + encodedDocumentId) as AutomergeUrl
+/** Helper to extract just the heads from a URL if they exist */
+export const getHeadsFromUrl = (url: AutomergeUrl): string[] | undefined => {
+  const { heads } = parseAutomergeUrl(url)
+  return heads
 }
 
+export const anyDocumentIdToAutomergeUrl = (id: AnyDocumentId) =>
+  isValidAutomergeUrl(id)
+    ? id
+    : isValidDocumentId(id)
+    ? stringifyAutomergeUrl({ documentId: id })
+    : isValidUuid(id)
+    ? parseLegacyUUID(id)
+    : undefined
+
 /**
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
  * discriminator in Typescript.
  */
 export const isValidAutomergeUrl = (str: unknown): str is AutomergeUrl => {
-  if (typeof str !== "string") return false
-  if (!str || !str.startsWith(urlPrefix)) return false
-  const automergeUrl = str as AutomergeUrl
+  if (typeof str !== "string" || !str || !str.startsWith(urlPrefix))
+    return false
   try {
-    const { documentId } = parseAutomergeUrl(automergeUrl)
-    return isValidDocumentId(documentId)
+    const { documentId, heads } = parseAutomergeUrl(str as AutomergeUrl)
+    if (!isValidDocumentId(documentId)) return false
+    if (
+      heads &&
+      !heads.every(head => {
+        try {
+          bs58check.decode(head)
+          return true
+        } catch {
+          return false
+        }
+      })
+    )
+      return false
+    return true
   } catch {
     return false
   }
@@ -97,6 +165,12 @@ export const documentIdToBinary = (docId: DocumentId) =>
 export const binaryToDocumentId = (docId: BinaryDocumentId) =>
   bs58check.encode(docId) as DocumentId
 
+export const encodeHeads = (heads: AutomergeHeads): UrlHeads =>
+  heads.map(h => bs58check.encode(uint8ArrayFromHexString(h))) as UrlHeads
+
+export const decodeHeads = (heads: UrlHeads): AutomergeHeads =>
+  heads.map(h => uint8ArrayToHexString(bs58check.decode(h))) as AutomergeHeads
+
 export const parseLegacyUUID = (str: string) => {
   if (!Uuid.validate(str)) return undefined
   const documentId = Uuid.parse(str) as BinaryDocumentId
@@ -141,4 +215,5 @@ export const interpretAsDocumentId = (id: AnyDocumentId) => {
 
 type UrlOptions = {
   documentId: DocumentId | BinaryDocumentId
+  heads?: UrlHeads
 }