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

package/src/synchronizer/CollectionSynchronizer.ts

@@ -1,9 +1,9 @@
 import debug from "debug"
 import { DocHandle } from "../DocHandle.js"
-import { stringifyAutomergeUrl } from "../AutomergeUrl.js"
+import { parseAutomergeUrl, stringifyAutomergeUrl } from "../AutomergeUrl.js"
 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"
 
@@ -21,8 +21,11 @@ export class CollectionSynchronizer extends Synchronizer {
   /** Used to determine if the document is know to the Collection and a synchronizer exists or is being set up */
   #docSetUp: Record<DocumentId, boolean> = {}
 
-  constructor(private repo: Repo) {
+  #denylist: DocumentId[]
+
+  constructor(private repo: Repo, denylist: AutomergeUrl[] = []) {
     super()
+    this.#denylist = denylist.map(url => parseAutomergeUrl(url).documentId)
   }
 
   /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
@@ -91,6 +94,19 @@ export class CollectionSynchronizer extends Synchronizer {
       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)

package/src/synchronizer/Synchronizer.ts

@@ -25,10 +25,15 @@ export interface SyncStatePayload {
   syncState: SyncState
 }
 
-export type DocSyncMetrics = {
-  type: "receive-sync-message"
-  documentId: DocumentId
-  durationMillis: number
-  numOps: number
-  numChanges: number
-}
+export type DocSyncMetrics =
+  | {
+      type: "receive-sync-message"
+      documentId: DocumentId
+      durationMillis: number
+      numOps: number
+      numChanges: number
+    }
+  | {
+      type: "doc-denied"
+      documentId: DocumentId
+    }

package/test/AutomergeUrl.test.ts

@@ -3,9 +3,11 @@ import bs58check from "bs58check"
 import { describe, it } from "vitest"
 import {
   generateAutomergeUrl,
+  getHeadsFromUrl,
   isValidAutomergeUrl,
   parseAutomergeUrl,
   stringifyAutomergeUrl,
+  UrlHeads,
 } from "../src/AutomergeUrl.js"
 import type {
   AutomergeUrl,
@@ -102,3 +104,131 @@ describe("AutomergeUrl", () => {
     })
   })
 })
+
+describe("AutomergeUrl with heads", () => {
+  // Create some sample encoded heads for testing
+  const head1 = bs58check.encode(new Uint8Array([1, 2, 3, 4])) as string
+  const head2 = bs58check.encode(new Uint8Array([5, 6, 7, 8])) as string
+  const goodHeads = [head1, head2] as UrlHeads
+  const urlWithHeads = `${goodUrl}#${head1}|${head2}` as AutomergeUrl
+  const invalidHead = "not-base58-encoded"
+  const invalidHeads = [invalidHead] as UrlHeads
+
+  describe("stringifyAutomergeUrl", () => {
+    it("should stringify a url with heads", () => {
+      const url = stringifyAutomergeUrl({
+        documentId: goodDocumentId,
+        heads: goodHeads,
+      })
+      assert.strictEqual(url, urlWithHeads)
+    })
+
+    it("should throw if heads are not valid base58check", () => {
+      assert.throws(() =>
+        stringifyAutomergeUrl({
+          documentId: goodDocumentId,
+          heads: invalidHeads,
+        })
+      )
+    })
+  })
+
+  describe("parseAutomergeUrl", () => {
+    it("should parse a url with heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(urlWithHeads)
+      assert.equal(documentId, goodDocumentId)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should parse a url without heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(goodUrl)
+      assert.equal(documentId, goodDocumentId)
+      assert.equal(heads, undefined)
+    })
+
+    it("should throw on url with invalid heads encoding", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert.throws(() => parseAutomergeUrl(badUrl))
+    })
+  })
+
+  describe("isValidAutomergeUrl", () => {
+    it("should return true for a valid url with heads", () => {
+      assert(isValidAutomergeUrl(urlWithHeads) === true)
+    })
+
+    it("should return false for a url with invalid heads", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert(isValidAutomergeUrl(badUrl) === false)
+    })
+  })
+
+  describe("getHeadsFromUrl", () => {
+    it("should return heads from a valid url", () => {
+      const heads = getHeadsFromUrl(urlWithHeads)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should return undefined for url without heads", () => {
+      const heads = getHeadsFromUrl(goodUrl)
+      assert.equal(heads, undefined)
+    })
+  })
+  it("should handle a single head correctly", () => {
+    const urlWithOneHead = `${goodUrl}#${head1}` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithOneHead)
+    assert.deepEqual(heads, [head1])
+  })
+
+  it("should round-trip urls with heads", () => {
+    const originalUrl = urlWithHeads
+    const parsed = parseAutomergeUrl(originalUrl)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, originalUrl)
+  })
+
+  describe("should reject malformed urls", () => {
+    it("should reject urls with trailing delimiter", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#${head1}:` as AutomergeUrl))
+    })
+
+    it("should reject urls with empty head", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#|${head1}` as AutomergeUrl))
+    })
+
+    it("should reject urls with multiple hash characters", () => {
+      assert(
+        !isValidAutomergeUrl(`${goodUrl}#${head1}#${head2}` as AutomergeUrl)
+      )
+    })
+  })
+})
+
+describe("empty heads section", () => {
+  it("should treat bare # as empty heads array", () => {
+    const urlWithEmptyHeads = `${goodUrl}#` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithEmptyHeads)
+    assert.deepEqual(heads, [])
+  })
+
+  it("should round-trip empty heads array", () => {
+    const original = `${goodUrl}#` as AutomergeUrl
+    const parsed = parseAutomergeUrl(original)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, original)
+  })
+
+  it("should distinguish between no heads and empty heads", () => {
+    const noHeads = parseAutomergeUrl(goodUrl)
+    const emptyHeads = parseAutomergeUrl(`${goodUrl}#` as AutomergeUrl)
+
+    assert.equal(noHeads.heads, undefined)
+    assert.deepEqual(emptyHeads.heads, [])
+  })
+})

package/test/DocHandle.test.ts

@@ -2,7 +2,11 @@ import * as A from "@automerge/automerge/next"
 import assert from "assert"
 import { decode } from "cbor-x"
 import { describe, it, vi } from "vitest"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import {
+  encodeHeads,
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+} from "../src/AutomergeUrl.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import { DocHandle, DocHandleChangePayload } from "../src/index.js"
@@ -83,7 +87,7 @@ describe("DocHandle", () => {
     handle.change(d => (d.foo = "bar"))
     assert.equal(handle.isReady(), true)
 
-    const heads = A.getHeads(handle.docSync())
+    const heads = encodeHeads(A.getHeads(handle.docSync()))
     assert.notDeepEqual(handle.heads(), [])
     assert.deepEqual(heads, handle.heads())
   })
@@ -113,8 +117,45 @@ describe("DocHandle", () => {
     assert.equal(handle.isReady(), true)
 
     const history = handle.history()
-    const view = handle.view(history[1])
-    assert.deepEqual(view, { foo: "one" })
+    const viewHandle = handle.view(history[1])
+    assert.deepEqual(await viewHandle.doc(), { foo: "one" })
+  })
+
+  it("should support fixed heads from construction", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    handle.change(d => (d.foo = "one"))
+
+    const history = handle.history()
+    const viewHandle = new DocHandle<TestDoc>(TEST_ID, { heads: history[0] })
+    viewHandle.update(() => A.clone(handle.docSync()!))
+    viewHandle.doneLoading()
+
+    assert.deepEqual(await viewHandle.doc(), { foo: "zero" })
+  })
+
+  it("should prevent changes on fixed-heads handles", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const viewHandle = handle.view(handle.heads()!)
+
+    assert.throws(() => viewHandle.change(d => (d.foo = "one")))
+    assert.throws(() =>
+      viewHandle.changeAt(handle.heads()!, d => (d.foo = "one"))
+    )
+    assert.throws(() => viewHandle.merge(handle))
+  })
+
+  it("should return fixed heads from heads()", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const originalHeads = handle.heads()!
+
+    handle.change(d => (d.foo = "one"))
+    const viewHandle = handle.view(originalHeads)
+
+    assert.deepEqual(viewHandle.heads(), originalHeads)
+    assert.notDeepEqual(viewHandle.heads(), handle.heads())
   })
 
   it("should return diffs", async () => {
@@ -154,6 +195,31 @@ describe("DocHandle", () => {
     ])
   })
 
+  it("should support diffing against another handle", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const viewHandle = handle.view(handle.heads()!)
+
+    handle.change(d => (d.foo = "one"))
+
+    const patches = viewHandle.diff(handle)
+    assert.deepEqual(patches, [
+      { action: "put", path: ["foo"], value: "" },
+      { action: "splice", path: ["foo", 0], value: "one" },
+    ])
+  })
+
+  // TODO: alexg -- should i remove this test? should this fail or no?
+  it.skip("should fail diffing against unrelated handles", async () => {
+    const handle1 = setup()
+    const handle2 = setup()
+
+    handle1.change(d => (d.foo = "zero"))
+    handle2.change(d => (d.foo = "one"))
+
+    assert.throws(() => handle1.diff(handle2))
+  })
+
   it("should allow direct access to decoded changes", async () => {
     const handle = setup()
     const time = Date.now()

package/test/DocSynchronizer.test.ts

@@ -1,7 +1,11 @@
 import assert from "assert"
 import { describe, it } from "vitest"
 import { next as Automerge } from "@automerge/automerge"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import {
+  encodeHeads,
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+} from "../src/AutomergeUrl.js"
 import { DocHandle } from "../src/DocHandle.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import {
@@ -67,11 +71,14 @@ describe("DocSynchronizer", () => {
 
     assert.equal(message1.peerId, "alice")
     assert.equal(message1.documentId, handle.documentId)
-    assert.deepEqual(message1.syncState.lastSentHeads, [])
+    assert.deepStrictEqual(message1.syncState.lastSentHeads, [])
 
     assert.equal(message2.peerId, "alice")
     assert.equal(message2.documentId, handle.documentId)
-    assert.deepEqual(message2.syncState.lastSentHeads, handle.heads())
+    assert.deepStrictEqual(
+      encodeHeads(message2.syncState.lastSentHeads),
+      handle.heads()
+    )
   })
 
   it("still syncs with a peer after it disconnects and reconnects", async () => {

package/test/Repo.test.ts

@@ -3,7 +3,13 @@ import { MessageChannelNetworkAdapter } from "../../automerge-repo-network-messa
 import assert from "assert"
 import * as Uuid from "uuid"
 import { describe, expect, it } from "vitest"
-import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import {
+  encodeHeads,
+  getHeadsFromUrl,
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
+  UrlHeads,
+} from "../src/AutomergeUrl.js"
 import {
   generateAutomergeUrl,
   stringifyAutomergeUrl,
@@ -1175,7 +1181,10 @@ describe("Repo", () => {
         bobHandle.documentId,
         await charlieRepo!.storageSubsystem.id()
       )
-      assert.deepStrictEqual(storedSyncState.sharedHeads, bobHandle.heads())
+      assert.deepStrictEqual(
+        encodeHeads(storedSyncState.sharedHeads),
+        bobHandle.heads()
+      )
 
       teardown()
     })
@@ -1275,7 +1284,7 @@ describe("Repo", () => {
 
       const nextRemoteHeadsPromise = new Promise<{
         storageId: StorageId
-        heads: A.Heads
+        heads: UrlHeads
       }>(resolve => {
         handle.on("remote-heads", ({ storageId, heads }) => {
           resolve({ storageId, heads })
@@ -1486,6 +1495,149 @@ describe("Repo", () => {
       teardown()
     })
   })
+
+  describe("the denylist", () => {
+    it("should immediately return an unavailable message in response to a request for a denylisted document", async () => {
+      const storage = new DummyStorageAdapter()
+
+      // first create the document in storage
+      const dummyRepo = new Repo({ network: [], storage })
+      const doc = dummyRepo.create({ foo: "bar" })
+      await dummyRepo.flush()
+
+      // Check that the document actually is in storage
+      let docId = doc.documentId
+      assert(storage.keys().some((k: string) => k.includes(docId)))
+
+      const channel = new MessageChannel()
+      const { port1: clientToServer, port2: serverToClient } = channel
+      const server = new Repo({
+        network: [new MessageChannelNetworkAdapter(serverToClient)],
+        storage,
+        denylist: [doc.url],
+      })
+      const client = new Repo({
+        network: [new MessageChannelNetworkAdapter(clientToServer)],
+      })
+
+      await Promise.all([
+        eventPromise(server.networkSubsystem, "peer"),
+        eventPromise(client.networkSubsystem, "peer"),
+      ])
+
+      const clientDoc = client.find(doc.url)
+      await pause(100)
+      assert.strictEqual(clientDoc.docSync(), undefined)
+
+      const openDocs = Object.keys(server.metrics().documents).length
+      assert.deepEqual(openDocs, 0)
+    })
+  })
+})
+
+describe("Repo heads-in-URLs functionality", () => {
+  const setup = () => {
+    const repo = new Repo({})
+    const handle = repo.create()
+    handle.change((doc: any) => (doc.title = "Hello World"))
+    return { repo, handle }
+  }
+
+  it("finds a document view by URL with heads", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = repo.find(url)
+    expect(view.docSync()).toEqual({ title: "Hello World" })
+  })
+
+  it("returns a view, not the actual handle, when finding by URL with heads", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    await handle.change((doc: any) => (doc.title = "Changed"))
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = repo.find(url)
+    expect(view.docSync()).toEqual({ title: "Hello World" })
+    expect(handle.docSync()).toEqual({ title: "Changed" })
+  })
+
+  it("changes to a document view do not affect the original", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = repo.find(url)
+    expect(() =>
+      view.change((doc: any) => (doc.title = "Changed in View"))
+    ).toThrow()
+    expect(handle.docSync()).toEqual({ title: "Hello World" })
+  })
+
+  it("document views are read-only", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = repo.find(url)
+    expect(() => view.change((doc: any) => (doc.title = "Changed"))).toThrow()
+  })
+
+  it("finds the latest document when given a URL without heads", async () => {
+    const { repo, handle } = setup()
+    await handle.change((doc: any) => (doc.title = "Changed"))
+    const found = repo.find(handle.url)
+    expect(found.docSync()).toEqual({ title: "Changed" })
+  })
+
+  it("getHeadsFromUrl returns heads array if present or undefined", () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    expect(getHeadsFromUrl(url)).toEqual(heads)
+
+    const urlWithoutHeads = generateAutomergeUrl()
+    expect(getHeadsFromUrl(urlWithoutHeads)).toBeUndefined()
+  })
+
+  it("isValidAutomergeUrl returns true for valid URLs", () => {
+    const { repo, handle } = setup()
+    const url = generateAutomergeUrl()
+    expect(isValidAutomergeUrl(url)).toBe(true)
+
+    const urlWithHeads = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
+    })
+    expect(isValidAutomergeUrl(urlWithHeads)).toBe(true)
+  })
+
+  it("isValidAutomergeUrl returns false for invalid URLs", () => {
+    const { repo, handle } = setup()
+    expect(isValidAutomergeUrl("not a url")).toBe(false)
+    expect(isValidAutomergeUrl("automerge:invalidid")).toBe(false)
+    expect(isValidAutomergeUrl("automerge:validid#invalidhead")).toBe(false)
+  })
+
+  it("parseAutomergeUrl extracts documentId and heads", () => {
+    const { repo, handle } = setup()
+    const url = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
+    })
+    const parsed = parseAutomergeUrl(url)
+    expect(parsed.documentId).toBe(handle.documentId)
+    expect(parsed.heads).toEqual(handle.heads())
+  })
+
+  it("stringifyAutomergeUrl creates valid URL", () => {
+    const { repo, handle } = setup()
+    const url = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
+    })
+    expect(isValidAutomergeUrl(url)).toBe(true)
+    const parsed = parseAutomergeUrl(url)
+    expect(parsed.documentId).toBe(handle.documentId)
+    expect(parsed.heads).toEqual(handle.heads())
+  })
 })
 
 const warn = console.warn