@automerge/automerge-repo 2.0.0-alpha.13 → 2.0.0-alpha.16

package/dist/Repo.d.ts

@@ -7,7 +7,7 @@ import { StorageSubsystem } from "./storage/StorageSubsystem.js";
 import { StorageId } from "./storage/types.js";
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
 import { DocSyncMetrics } from "./synchronizer/Synchronizer.js";
-import type { AnyDocumentId, DocumentId, PeerId } from "./types.js";
+import type { AnyDocumentId, AutomergeUrl, DocumentId, PeerId } from "./types.js";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -33,7 +33,7 @@ export declare class Repo extends EventEmitter<RepoEvents> {
     /** maps peer id to to persistence information (storageId, isEphemeral), access by collection synchronizer  */
     /** @hidden */
     peerMetadataByPeerId: Record<PeerId, PeerMetadata>;
-    constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, }?: RepoConfig);
+    constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, denylist, }?: RepoConfig);
     /** Returns all the handles we have cached. */
     get handles(): Record<DocumentId, DocHandle<any>>;
     /** Returns a list of all connected peer ids */
@@ -126,6 +126,12 @@ export interface RepoConfig {
      * Whether to enable the experimental remote heads gossiping feature
      */
     enableRemoteHeadsGossiping?: boolean;
+    /**
+     * A list of automerge URLs which should never be loaded regardless of what
+     * messages are received or what the share policy is. This is useful to avoid
+     * loading documents that are known to be too resource intensive.
+     */
+    denylist?: AutomergeUrl[];
 }
 /** A function that determines whether we should share a document with a peer
  *
@@ -157,5 +163,8 @@ export type DocMetrics = DocSyncMetrics | {
     durationMillis: number;
     numOps: number;
     numChanges: number;
+} | {
+    type: "doc-denied";
+    documentId: DocumentId;
 };
 //# sourceMappingURL=Repo.d.ts.map

package/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}

package/dist/Repo.js

@@ -1,7 +1,7 @@
 import { next as Automerge } from "@automerge/automerge/slim";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
-import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
+import { encodeHeads, generateAutomergeUrl, interpretAsDocumentId, isValidAutomergeUrl, parseAutomergeUrl, } from "./AutomergeUrl.js";
 import { DELETED, DocHandle, READY, UNAVAILABLE, UNLOADED, } from "./DocHandle.js";
 import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js";
 import { headsAreSame } from "./helpers/headsAreSame.js";
@@ -40,7 +40,7 @@ export class Repo extends EventEmitter {
     peerMetadataByPeerId = {};
     #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions();
     #remoteHeadsGossipingEnabled = false;
-    constructor({ storage, network = [], peerId = randomPeerId(), sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, } = {}) {
+    constructor({ storage, network = [], peerId = randomPeerId(), sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, denylist = [], } = {}) {
         super();
         this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping;
         this.#log = debug(`automerge-repo:repo`);
@@ -56,7 +56,7 @@ export class Repo extends EventEmitter {
         });
         // SYNCHRONIZER
         // The synchronizer uses the network subsystem to keep documents in sync with peers.
-        this.synchronizer = new CollectionSynchronizer(this);
+        this.synchronizer = new CollectionSynchronizer(this, denylist);
         // When the synchronizer emits messages, send them to peers
         this.synchronizer.on("message", message => {
             this.#log(`sending ${message.type} message to ${message.targetId}`);
@@ -119,11 +119,12 @@ export class Repo extends EventEmitter {
             }
             const heads = handle.getRemoteHeads(storageId);
             const haveHeadsChanged = message.syncState.theirHeads &&
-                (!heads || !headsAreSame(heads, message.syncState.theirHeads));
+                (!heads ||
+                    !headsAreSame(heads, encodeHeads(message.syncState.theirHeads)));
             if (haveHeadsChanged && message.syncState.theirHeads) {
-                handle.setRemoteHeads(storageId, message.syncState.theirHeads);
+                handle.setRemoteHeads(storageId, encodeHeads(message.syncState.theirHeads));
                 if (storageId && this.#remoteHeadsGossipingEnabled) {
-                    this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, message.syncState.theirHeads);
+                    this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, encodeHeads(message.syncState.theirHeads));
                 }
             }
         });
@@ -305,18 +306,21 @@ export class Repo extends EventEmitter {
     find(
     /** The url or documentId of the handle to retrieve */
     id) {
-        const documentId = interpretAsDocumentId(id);
-        // If we have the handle cached, return it
-        if (this.#handleCache[documentId]) {
-            if (this.#handleCache[documentId].isUnavailable()) {
+        const { documentId, heads } = isValidAutomergeUrl(id)
+            ? parseAutomergeUrl(id)
+            : { documentId: interpretAsDocumentId(id), heads: undefined };
+        const cachedHandle = this.#handleCache[documentId];
+        if (cachedHandle) {
+            if (cachedHandle.isUnavailable()) {
                 // this ensures that the event fires after the handle has been returned
                 setTimeout(() => {
-                    this.#handleCache[documentId].emit("unavailable", {
-                        handle: this.#handleCache[documentId],
+                    cachedHandle.emit("unavailable", {
+                        handle: cachedHandle,
                     });
                 });
             }
-            return this.#handleCache[documentId];
+            // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+            return heads ? cachedHandle.view(heads) : cachedHandle;
         }
         // If we don't already have the handle, make an empty one and try loading it
         const handle = this.#getHandle({
@@ -345,7 +349,8 @@ export class Repo extends EventEmitter {
             .catch(err => {
             this.#log("error waiting for network", { err });
         });
-        return handle;
+        // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+        return heads ? handle.view(heads) : handle;
     }
     delete(
     /** The url or documentId of the handle to delete */

package/dist/helpers/bufferFromHex.d.ts

@@ -0,0 +1,3 @@
+export declare const uint8ArrayFromHexString: (hexString: string) => Uint8Array;
+export declare const uint8ArrayToHexString: (data: Uint8Array) => string;
+//# sourceMappingURL=bufferFromHex.d.ts.map

package/dist/helpers/bufferFromHex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferFromHex.d.ts","sourceRoot":"","sources":["../../src/helpers/bufferFromHex.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,cAAe,MAAM,KAAG,UAS3D,CAAA;AAED,eAAO,MAAM,qBAAqB,SAAU,UAAU,KAAG,MAExD,CAAA"}

package/dist/helpers/bufferFromHex.js

@@ -0,0 +1,13 @@
+export const uint8ArrayFromHexString = (hexString) => {
+    if (hexString.length % 2 !== 0) {
+        throw new Error("Hex string must have an even length");
+    }
+    const bytes = new Uint8Array(hexString.length / 2);
+    for (let i = 0; i < hexString.length; i += 2) {
+        bytes[i >> 1] = parseInt(hexString.slice(i, i + 2), 16);
+    }
+    return bytes;
+};
+export const uint8ArrayToHexString = (data) => {
+    return Array.from(data, byte => byte.toString(16).padStart(2, "0")).join("");
+};

package/dist/helpers/headsAreSame.d.ts

@@ -1,3 +1,3 @@
-import { Heads } from "@automerge/automerge/slim/next";
-export declare const headsAreSame: (a: Heads, b: Heads) => boolean;
+import { UrlHeads } from "../AutomergeUrl.js";
+export declare const headsAreSame: (a: UrlHeads, b: UrlHeads) => boolean;
 //# sourceMappingURL=headsAreSame.d.ts.map

package/dist/helpers/headsAreSame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headsAreSame.d.ts","sourceRoot":"","sources":["../../src/helpers/headsAreSame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAA;AAGtD,eAAO,MAAM,YAAY,MAAO,KAAK,KAAK,KAAK,YAE9C,CAAA"}
+{"version":3,"file":"headsAreSame.d.ts","sourceRoot":"","sources":["../../src/helpers/headsAreSame.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7C,eAAO,MAAM,YAAY,MAAO,QAAQ,KAAK,QAAQ,YAEpD,CAAA"}

package/dist/helpers/mergeArrays.d.ts

@@ -1,2 +1,2 @@
-export declare function mergeArrays(myArrays: Uint8Array[]): Uint8Array;
+export declare function mergeArrays(myArrays: Uint8Array[]): Uint8Array<ArrayBuffer>;
 //# sourceMappingURL=mergeArrays.d.ts.map

package/dist/helpers/mergeArrays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergeArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeArrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,cAgBjD"}
+{"version":3,"file":"mergeArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeArrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,2BAgBjD"}

package/dist/helpers/tests/storage-adapter-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/storage-adapter-tests.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAcvF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0I3E;AAID,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,OAAO,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC,CAAC,CAAA"}
+{"version":3,"file":"storage-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/storage-adapter-tests.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAcvF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA+H3E;AAID,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,OAAO,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC,CAAC,CAAA"}

package/dist/helpers/tests/storage-adapter-tests.js

@@ -44,26 +44,23 @@ export function runStorageAdapterTests(setup, title) {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B());
                 await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C());
-                expect(await adapter.loadRange(["AAAAA"])).toStrictEqual(expect.arrayContaining([
+                expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
                     { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
                     { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
-                expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual(expect.arrayContaining([
+                ]);
+                expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
                     { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
+                ]);
             });
             it("should only load values that match they key", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_C());
                 const actual = await adapter.loadRange(["AAAAA"]);
-                expect(actual).toStrictEqual(expect.arrayContaining([
+                expect(actual).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-                ]));
-                expect(actual).toStrictEqual(expect.not.arrayContaining([
-                    { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
+                ]);
             });
         });
         describe("save and remove", () => {

package/dist/storage/StorageSubsystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0ClE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAazE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}
+{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0ClE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}

package/dist/storage/StorageSubsystem.js

@@ -6,6 +6,7 @@ import { keyHash, headsHash } from "./keyHash.js";
 import { chunkTypeFromKey } from "./chunkTypeFromKey.js";
 import * as Uuid from "uuid";
 import { EventEmitter } from "eventemitter3";
+import { encodeHeads } from "../AutomergeUrl.js";
 /**
  * The storage subsystem is responsible for saving and loading Automerge documents to and from
  * storage adapter. It also provides a generic key/value storage interface for other uses.
@@ -210,7 +211,7 @@ export class StorageSubsystem extends EventEmitter {
             return true;
         }
         const newHeads = A.getHeads(doc);
-        if (headsAreSame(newHeads, oldHeads)) {
+        if (headsAreSame(encodeHeads(newHeads), encodeHeads(oldHeads))) {
             // the document hasn't changed
             return false;
         }

package/dist/synchronizer/CollectionSynchronizer.d.ts

@@ -1,6 +1,6 @@
 import { Repo } from "../Repo.js";
 import { DocMessage } from "../network/messages.js";
-import { DocumentId, PeerId } from "../types.js";
+import { AutomergeUrl, DocumentId, PeerId } from "../types.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 /** A CollectionSynchronizer is responsible for synchronizing a DocCollection with peers. */
@@ -10,7 +10,7 @@ export declare class CollectionSynchronizer extends Synchronizer {
     /** A map of documentIds to their synchronizers */
     /** @hidden */
     docSynchronizers: Record<DocumentId, DocSynchronizer>;
-    constructor(repo: Repo);
+    constructor(repo: Repo, denylist?: AutomergeUrl[]);
     /**
      * When we receive a sync message for a document we haven't got in memory, we
      * register it with the repo and start synchronizing

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

@@ -1 +1 @@
-{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAW1C,OAAO,CAAC,IAAI;IAPxB,kDAAkD;IAClD,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAK;gBAKtC,IAAI,EAAE,IAAI;IAsD9B;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAyBxC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAalC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,IAAI;QACT,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7C,CAAA;KACF;CASF"}
+{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAa1C,OAAO,CAAC,IAAI;IATxB,kDAAkD;IAClD,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAK;gBAOtC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,YAAY,EAAO;IAuD7D;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAsCxC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAalC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,IAAI;QACT,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7C,CAAA;KACF;CASF"}

package/dist/synchronizer/CollectionSynchronizer.js

@@ -1,5 +1,5 @@
 import debug from "debug";
-import { stringifyAutomergeUrl } from "../AutomergeUrl.js";
+import { parseAutomergeUrl, stringifyAutomergeUrl } from "../AutomergeUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 const log = debug("automerge-repo:collectionsync");
@@ -13,9 +13,11 @@ export class CollectionSynchronizer extends Synchronizer {
     docSynchronizers = {};
     /** Used to determine if the document is know to the Collection and a synchronizer exists or is being set up */
     #docSetUp = {};
-    constructor(repo) {
+    #denylist;
+    constructor(repo, denylist = []) {
         super();
         this.repo = repo;
+        this.#denylist = denylist.map(url => parseAutomergeUrl(url).documentId);
     }
     /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
     #fetchDocSynchronizer(documentId) {
@@ -68,6 +70,18 @@ export class CollectionSynchronizer extends Synchronizer {
         if (!documentId) {
             throw new Error("received a message with an invalid documentId");
         }
+        if (this.#denylist.includes(documentId)) {
+            this.emit("metrics", {
+                type: "doc-denied",
+                documentId,
+            });
+            this.emit("message", {
+                type: "doc-unavailable",
+                documentId,
+                targetId: message.senderId,
+            });
+            return;
+        }
         this.#docSetUp[documentId] = true;
         const docSynchronizer = this.#fetchDocSynchronizer(documentId);
         docSynchronizer.receiveMessage(message);

package/dist/synchronizer/Synchronizer.d.ts

@@ -23,5 +23,8 @@ export type DocSyncMetrics = {
     durationMillis: number;
     numOps: number;
     numChanges: number;
+} | {
+    type: "doc-denied";
+    documentId: DocumentId;
 };
 //# 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,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACjD,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACvC;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,sBAAsB,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACjD,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACvC;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,sBAAsB,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,IAAI,EAAE,YAAY,CAAA;IAClB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.13",
+  "version": "2.0.0-alpha.16",
   "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>",
@@ -60,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f4504b4e6441d938df54f77adf0d629f26ff9a7c"
+  "gitHead": "04e79be28aca7dc566ced3b2c32e05ca5d37ce69"
 }

package/src/AutomergeUrl.ts

@@ -5,25 +5,55 @@ import type {
   DocumentId,
   AnyDocumentId,
 } 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:"
 
+// We need to define our own version of heads because the AutomergeHeads type is not bs58check encoded
+export type UrlHeads = string[] & { __automergeUrlHeadsBrand: unknown }
+
+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 +62,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 +167,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 +217,5 @@ export const interpretAsDocumentId = (id: AnyDocumentId) => {
 
 type UrlOptions = {
   documentId: DocumentId | BinaryDocumentId
+  heads?: UrlHeads
 }