@freqhole/playlistz 0.0.1

package/src/services/automergeRepo.test.ts

@@ -0,0 +1,269 @@
+// tests for the automerge-repo singleton module.
+//
+// uses real @automerge/automerge-repo + IndexedDBStorageAdapter (via
+// fake-indexeddb from test-setup) + mocked IrohNetworkAdapter and p2pService.
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+// --- mocks (hoisted before module imports) ---
+
+const { MockIrohNetworkAdapterClass } = vi.hoisted(() => {
+  return { MockIrohNetworkAdapterClass: vi.fn() };
+});
+
+vi.mock("@freqhole/api-client/automerge", async () => {
+  const { NetworkAdapter } = await vi.importActual<
+    typeof import("@automerge/automerge-repo")
+  >("@automerge/automerge-repo");
+
+  class MockIrohNetworkAdapter extends NetworkAdapter {
+    isReady() {
+      return true;
+    }
+    async whenReady() {
+      return;
+    }
+    connect() {}
+    disconnect() {}
+    send() {}
+  }
+
+  MockIrohNetworkAdapterClass.mockImplementation(
+    (...args: unknown[]) => new MockIrohNetworkAdapter(...(args as []))
+  );
+
+  return { IrohNetworkAdapter: MockIrohNetworkAdapterClass };
+});
+
+vi.mock("./p2pService.js", () => ({
+  getAdapterOptions: vi.fn(() => ({
+    getNode: async () => {
+      throw new Error("not available in tests");
+    },
+    getIdentity: async () => null,
+  })),
+}));
+
+import {
+  getRepo,
+  createPlaylistDoc,
+  findPlaylistDoc,
+  deletePlaylistDoc,
+  _resetRepoForTests,
+  _testSharePolicy,
+} from "./automergeRepo.js";
+import { parseAutomergeUrl } from "@automerge/automerge-repo";
+import type { PeerId, DocumentId } from "@automerge/automerge-repo";
+import { addPeer } from "@freqhole/api-client/playlistz";
+
+describe("automergeRepo", () => {
+  beforeEach(() => {
+    _resetRepoForTests();
+  });
+
+  describe("getRepo()", () => {
+    it("returns a repo instance", () => {
+      const repo = getRepo();
+      expect(repo).toBeDefined();
+    });
+
+    it("returns the same singleton on repeated calls", () => {
+      const r1 = getRepo();
+      const r2 = getRepo();
+      expect(r1).toBe(r2);
+    });
+
+    it("returns a fresh repo after _resetRepoForTests", () => {
+      const r1 = getRepo();
+      _resetRepoForTests();
+      const r2 = getRepo();
+      expect(r1).not.toBe(r2);
+    });
+  });
+
+  describe("createPlaylistDoc()", () => {
+    it("returns an AutomergeUrl and a DocHandle", () => {
+      const { docId, handle } = createPlaylistDoc();
+      expect(docId).toMatch(/^automerge:/);
+      expect(handle).toBeDefined();
+    });
+
+    it("seeds the doc with PlaylistDoc defaults", () => {
+      const { handle } = createPlaylistDoc();
+      const doc = handle.doc();
+      expect(doc).toBeDefined();
+      expect(doc?.version).toBe(1);
+      expect(doc?.title).toBe("");
+      expect(doc?.songs).toEqual({});
+      expect(doc?.order).toEqual([]);
+    });
+
+    it("applies initial overrides to the doc", () => {
+      const { handle } = createPlaylistDoc({
+        title: "my playlist",
+        description: "a test",
+      });
+      const doc = handle.doc();
+      expect(doc?.title).toBe("my playlist");
+      expect(doc?.description).toBe("a test");
+    });
+
+    it("each call produces a unique docId", () => {
+      const { docId: id1 } = createPlaylistDoc();
+      const { docId: id2 } = createPlaylistDoc();
+      expect(id1).not.toBe(id2);
+    });
+  });
+
+  describe("findPlaylistDoc()", () => {
+    it("returns the same handle as was created", async () => {
+      const { docId } = createPlaylistDoc({ title: "find test" });
+      const found = await findPlaylistDoc(docId);
+      const doc = found.doc();
+      expect(doc?.title).toBe("find test");
+    });
+
+    it("round-trip preserves the full doc content", async () => {
+      const { docId, handle: orig } = createPlaylistDoc({
+        title: "roundtrip",
+        description: "desc",
+      });
+      orig.change((d) => {
+        d.order.push("song-1");
+        d.songs["song-1"] = {
+          id: "song-1",
+          title: "track",
+          artist: "artist",
+          album: "album",
+          duration: 120,
+          mimeType: "audio/mp3",
+          fileSize: 100,
+          sha256: "abc123",
+          images: [],
+          urls: [],
+        };
+      });
+      const found = await findPlaylistDoc(docId);
+      const doc = found.doc();
+      expect(doc?.title).toBe("roundtrip");
+      expect(doc?.order).toContain("song-1");
+    });
+  });
+
+  describe("sharePolicy via _testSharePolicy()", () => {
+    it("denies peers not recorded in the doc", async () => {
+      const { docId } = createPlaylistDoc();
+      const { documentId } = parseAutomergeUrl(docId);
+      const stranger = "stranger-node" as PeerId;
+      const allowed = await _testSharePolicy(
+        stranger,
+        documentId as unknown as DocumentId
+      );
+      expect(allowed).toBe(false);
+    });
+
+    it("denies unknown documentId (not in cache)", async () => {
+      const unknownId = "2BmFCMEUanPd5grDGtGfwd" as unknown as DocumentId;
+      const peerId = "some-peer" as PeerId;
+      expect(await _testSharePolicy(peerId, unknownId)).toBe(false);
+    });
+
+    it("allows a peer recorded in the doc's peers map", async () => {
+      const { docId, handle } = createPlaylistDoc();
+      const { documentId } = parseAutomergeUrl(docId);
+
+      // add a peer via the shared addPeer mutator
+      handle.change((doc) => addPeer(doc, "known-peer-id"));
+
+      const peerId = "known-peer-id" as PeerId;
+      const allowed = await _testSharePolicy(
+        peerId,
+        documentId as unknown as DocumentId
+      );
+      expect(allowed).toBe(true);
+    });
+
+    it("allows a peer recorded in the doc's acl", async () => {
+      const { docId, handle } = createPlaylistDoc();
+      const { documentId } = parseAutomergeUrl(docId);
+
+      handle.change((doc) => {
+        if (!doc.acl) doc.acl = {};
+        doc.acl["acl-peer"] = { role: "viewer" };
+      });
+
+      const peerId = "acl-peer" as PeerId;
+      const allowed = await _testSharePolicy(
+        peerId,
+        documentId as unknown as DocumentId
+      );
+      expect(allowed).toBe(true);
+    });
+
+    it("denies a stranger even when other peers are allowed", async () => {
+      const { docId, handle } = createPlaylistDoc();
+      const { documentId } = parseAutomergeUrl(docId);
+
+      handle.change((doc) => addPeer(doc, "known-peer-id"));
+
+      const stranger = "not-a-peer" as PeerId;
+      const allowed = await _testSharePolicy(
+        stranger,
+        documentId as unknown as DocumentId
+      );
+      expect(allowed).toBe(false);
+    });
+  });
+
+  describe("deletePlaylistDoc()", () => {
+    it("fires the delete event on the handle", async () => {
+      const { docId, handle } = createPlaylistDoc({ title: "to delete" });
+
+      let deleteReceived = false;
+      handle.on("delete", () => {
+        deleteReceived = true;
+      });
+
+      await deletePlaylistDoc(docId);
+      expect(deleteReceived).toBe(true);
+    });
+
+    it("tombstones the doc before deleting it", async () => {
+      const { docId, handle } = createPlaylistDoc({ title: "tombstone test" });
+
+      let tombstoneDoc: { deleted?: boolean } | undefined;
+      handle.on("change", ({ doc }) => {
+        tombstoneDoc = doc as { deleted?: boolean };
+      });
+
+      await deletePlaylistDoc(docId);
+
+      // tombstoneDoc should have been set by the change event before delete
+      expect(tombstoneDoc?.deleted).toBe(true);
+    });
+
+    it("removes the doc from the share policy cache", async () => {
+      const { docId, handle } = createPlaylistDoc();
+      const { documentId } = parseAutomergeUrl(docId);
+
+      // put a peer in the cache
+      handle.change((doc) => addPeer(doc, "some-peer"));
+      expect(
+        await _testSharePolicy(
+          "some-peer" as PeerId,
+          documentId as unknown as DocumentId
+        )
+      ).toBe(true);
+
+      await deletePlaylistDoc(docId);
+
+      // cache entry removed - should now deny
+      expect(
+        await _testSharePolicy(
+          "some-peer" as PeerId,
+          documentId as unknown as DocumentId
+        )
+      ).toBe(false);
+    });
+  });
+});

package/src/services/automergeRepo.ts

@@ -0,0 +1,226 @@
+// automerge-repo singleton for playlistz.
+//
+// wires together:
+//   - IndexedDBStorageAdapter ("freqhole-automerge" db)
+//   - BroadcastChannelNetworkAdapter (cross-tab sync)
+//   - IrohNetworkAdapter (p2p via midden; defers until identity is available)
+//
+// all playlist docs live in this single repo instance. the repo is lazily
+// constructed on first call to getRepo().
+
+import {
+  Repo,
+  parseAutomergeUrl,
+  type DocHandle,
+  type AutomergeUrl,
+  type PeerId,
+  type DocumentId,
+} from "@automerge/automerge-repo";
+import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
+import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel";
+import { IrohNetworkAdapter } from "@freqhole/api-client/automerge";
+import {
+  parsePlaylistDoc,
+  emptyPlaylistDoc,
+  tombstone,
+  type PlaylistDoc,
+} from "@freqhole/api-client/playlistz";
+import { getAdapterOptions } from "./p2pService.js";
+import { log } from "../utils/log.js";
+
+// per-doc peer registry used by sharePolicy to avoid a round-trip through
+// repo.find(). keyed by DocumentId (the base58 part of the AutomergeUrl).
+// updated whenever a doc is created, found, or receives a change event.
+const docPeerCache = new Map<
+  DocumentId,
+  { peers: Set<string>; acl: Set<string> }
+>();
+
+function updateCacheFromDoc(documentId: DocumentId, rawDoc: unknown): void {
+  const doc = parsePlaylistDoc(rawDoc);
+  docPeerCache.set(documentId, {
+    peers: new Set(Object.keys(doc.peers)),
+    acl: new Set(Object.keys(doc.acl ?? {})),
+  });
+}
+
+// share policy: only announce a doc to a peer recorded in that doc's
+// peers map or acl. docs not in the cache (unknown to this instance) are
+// not announced. this matches the plan's access model - the doc id is an
+// unguessable bearer capability; unsolicited announcement is off by default.
+let _sharePolicyCalls = 0;
+async function sharePolicy(
+  peerId: PeerId,
+  documentId?: DocumentId
+): Promise<boolean> {
+  _sharePolicyCalls++;
+  if (!documentId) return false;
+  const entry = docPeerCache.get(documentId);
+  if (!entry) return false;
+  return entry.peers.has(peerId) || entry.acl.has(peerId);
+}
+
+let _repo: Repo | null = null;
+let _irohAdapter: IrohNetworkAdapter | null = null;
+
+function buildRepo(): Repo {
+  log.trace("automerge.repo", "buildRepo: constructing");
+  const storage = new IndexedDBStorageAdapter("freqhole-automerge");
+  const broadcastAdapter = new BroadcastChannelNetworkAdapter();
+  const irohAdapter = new IrohNetworkAdapter(getAdapterOptions());
+  _irohAdapter = irohAdapter;
+
+  const repo = new Repo({
+    storage,
+    network: [broadcastAdapter, irohAdapter],
+    sharePolicy,
+  });
+  return repo;
+}
+
+// returns the lazily-constructed repo singleton.
+// subsequent calls return the same instance.
+export function getRepo(): Repo {
+  if (!_repo) {
+    _repo = buildRepo();
+  }
+  return _repo;
+}
+
+// returns the iroh network adapter wired into the repo. constructing the
+// repo if needed. used by sharing/blob services for addPeer, alpn handlers
+// and connection state.
+export function getIrohAdapter(): IrohNetworkAdapter {
+  if (!_irohAdapter) {
+    getRepo();
+  }
+  return _irohAdapter!;
+}
+
+// attach a change listener that keeps the peer cache current for a handle.
+// also seeds the cache from whatever the handle has now (if ready).
+// documentIds that already have a change listener attached via watchHandle.
+// prevents unbounded listener growth when findPlaylistDoc is called repeatedly.
+const watchedDocs = new Set<DocumentId>();
+
+let _watchHandleCalls = 0;
+function watchHandle(
+  handle: DocHandle<PlaylistDoc>,
+  documentId: DocumentId
+): void {
+  _watchHandleCalls++;
+  let rawDoc: unknown;
+  try {
+    rawDoc = handle.doc();
+  } catch {
+    rawDoc = undefined;
+  }
+  if (rawDoc !== undefined) {
+    updateCacheFromDoc(documentId, rawDoc);
+  }
+  if (!watchedDocs.has(documentId)) {
+    watchedDocs.add(documentId);
+    handle.on("change", ({ doc }) => {
+      log.trace("automerge.repo", "doc change event", documentId);
+      updateCacheFromDoc(documentId, doc);
+    });
+  }
+}
+
+// create a new playlist doc seeded with emptyPlaylistDoc + optional overrides.
+// returns the AutomergeUrl (docId) and the DocHandle synchronously.
+export function createPlaylistDoc(initial?: Partial<PlaylistDoc>): {
+  docId: AutomergeUrl;
+  handle: DocHandle<PlaylistDoc>;
+} {
+  const repo = getRepo();
+  const seed = emptyPlaylistDoc(initial);
+  const handle = repo.create<PlaylistDoc>(seed);
+  log.trace("automerge.repo", "createPlaylistDoc:", handle.url);
+  const { documentId } = parseAutomergeUrl(handle.url);
+  watchHandle(handle, documentId);
+  return { docId: handle.url, handle };
+}
+
+// pre-authorize a peer for a doc we don't have yet. seeds the peer cache
+// so sharePolicy lets us request the doc from (and sync it with) that peer
+// before the doc has arrived locally. without this, opening a share link
+// dead-ends: the policy only trusts peers recorded in the doc, but the doc
+// can't arrive until the policy trusts the peer.
+export function authorizePeerForDoc(docId: AutomergeUrl, nodeId: string): void {
+  const { documentId } = parseAutomergeUrl(docId);
+  const entry = docPeerCache.get(documentId) ?? {
+    peers: new Set<string>(),
+    acl: new Set<string>(),
+  };
+  entry.peers.add(nodeId);
+  docPeerCache.set(documentId, entry);
+}
+
+// per-docId promise cache so repeated calls for the same doc share one
+// repo.find() call and one watchHandle setup. the cache holds a promise
+// (not a resolved handle) so concurrent first-callers coalesce correctly.
+const _handleCache = new Map<AutomergeUrl, Promise<DocHandle<PlaylistDoc>>>();
+
+// find an existing playlist doc by its AutomergeUrl, waiting for the handle
+// to reach a ready (or terminal) state before returning.
+// cached: subsequent calls for the same docId return the same promise.
+let _findCalls = 0;
+export async function findPlaylistDoc(
+  docId: AutomergeUrl
+): Promise<DocHandle<PlaylistDoc>> {
+  const cached = _handleCache.get(docId);
+  if (cached) return cached;
+
+  _findCalls++;
+  log.trace("automerge.repo", "findPlaylistDoc call #", String(_findCalls), docId);
+
+  const promise = (async () => {
+    const repo = getRepo();
+    const handle = await repo.find<PlaylistDoc>(docId);
+    log.trace("automerge.repo", "findPlaylistDoc resolved", docId);
+    const { documentId } = parseAutomergeUrl(handle.url);
+    watchHandle(handle, documentId);
+    return handle;
+  })();
+
+  _handleCache.set(docId, promise);
+  return promise;
+}
+
+// tombstone the doc (sets deleted: true) then remove it from local storage.
+export async function deletePlaylistDoc(docId: AutomergeUrl): Promise<void> {
+  _handleCache.delete(docId);
+  const repo = getRepo();
+  const handle = await repo.find<PlaylistDoc>(docId);
+  handle.change((doc) => tombstone(doc));
+  const { documentId } = parseAutomergeUrl(docId);
+  docPeerCache.delete(documentId);
+  repo.delete(docId);
+}
+
+// flush a doc's pending changes to indexeddb. the repo debounces storage
+// writes, so without this a reload (or tab close) shortly after a mutation
+// can lose data.
+export async function flushDoc(docId: AutomergeUrl): Promise<void> {
+  const repo = getRepo();
+  const { documentId } = parseAutomergeUrl(docId);
+  await repo.flush([documentId]);
+}
+
+// reset all singleton state. for use in tests only.
+export function _resetRepoForTests(): void {
+  _repo = null;
+  _irohAdapter = null;
+  docPeerCache.clear();
+  watchedDocs.clear();
+  _handleCache.clear();
+}
+
+// expose the share policy for unit testing.
+export async function _testSharePolicy(
+  peerId: PeerId,
+  documentId: DocumentId
+): Promise<boolean> {
+  return sharePolicy(peerId, documentId);
+}

package/src/services/blobTransferService.dev.ts

@@ -0,0 +1,119 @@
+// dev-only mock implementations for blob transfer.
+//
+// this file is only loaded in DEV builds (imported by src/dev-hooks.ts which
+// is dynamically imported under import.meta.env.DEV). never bundled for prod.
+//
+// exports a single factory function that creates the mock fetch override.
+// the factory is called by dev-hooks.ts which also manages the active
+// behaviour state and the window hook registration.
+
+import {
+  _devSetFetchOverride,
+  _devSetBlobFetchTimeout,
+  _devEvictBlob,
+  _devFetchBlobBySha,
+  type BlobFetchProgress,
+} from "./blobTransferService.js";
+import { storeBlob } from "@freqhole/api-client/storage";
+
+// the behaviour union mirrors global.d.ts Window["__mockBlobFetch"] parameter.
+// keeping it here means the mock impl and its type live together.
+export type MockBlobBehaviour = NonNullable<
+  Window["__mockBlobFetch"]
+> extends (b: infer B) => void
+  ? B
+  : never;
+
+// --- synthetic blob data ---
+
+// build a minimal valid 1s mono 16-bit PCM WAV (silence).
+// used as a stand-in blob so the audio element gets something it can decode.
+function makeSyntheticWav(): Uint8Array {
+  const samples = 8000;
+  const dataSize = samples * 2;
+  const buf = new ArrayBuffer(44 + dataSize);
+  const v = new DataView(buf);
+  const s = (o: number, t: string) => {
+    for (let i = 0; i < t.length; i++) v.setUint8(o + i, t.charCodeAt(i));
+  };
+  s(0, "RIFF"); v.setUint32(4, 36 + dataSize, true);
+  s(8, "WAVE"); s(12, "fmt ");
+  v.setUint32(16, 16, true); v.setUint16(20, 1, true);  // PCM mono
+  v.setUint16(22, 1, true); v.setUint32(24, 8000, true); // 8kHz
+  v.setUint32(28, 16000, true); v.setUint16(32, 2, true);
+  v.setUint16(34, 16, true); s(36, "data");
+  v.setUint32(40, dataSize, true);
+  return new Uint8Array(buf);
+}
+
+// --- mock fetch implementation ---
+
+async function mockFetchBlob(
+  sha256: string,
+  mimeType: string,
+  onProgress: ((p: BlobFetchProgress) => void) | undefined,
+  behaviour: MockBlobBehaviour
+): Promise<string | null> {
+  if (behaviour.type === "error") {
+    throw new Error(`mock blob error: ${behaviour.code}`);
+  }
+
+  if (behaviour.type === "stall") {
+    // hangs until the test clears the mock or the fetch timeout fires
+    return new Promise<string | null>(() => {});
+  }
+
+  const bytes = makeSyntheticWav();
+  const blob = new Blob([bytes.buffer as ArrayBuffer], { type: mimeType });
+  const total = blob.size;
+
+  if (behaviour.type === "instant") {
+    await storeBlob(blob, mimeType);
+    return sha256;
+  }
+
+  if (behaviour.type === "delayed") {
+    await new Promise<void>((res) => setTimeout(res, behaviour.ms));
+    await storeBlob(blob, mimeType);
+    return sha256;
+  }
+
+  if (behaviour.type === "progress") {
+    const chunkSize = Math.ceil(total / behaviour.chunks);
+    let offset = 0;
+    for (let i = 0; i < behaviour.chunks; i++) {
+      await new Promise<void>((res) => setTimeout(res, behaviour.msPerChunk));
+      offset = Math.min(offset + chunkSize, total);
+      onProgress?.({ sha256, fraction: offset / total });
+    }
+    await storeBlob(blob, mimeType);
+    return sha256;
+  }
+
+  return null;
+}
+
+// --- window hook registration ---
+
+// call this once at app startup (from dev-hooks.ts) to register all blob
+// transport mock hooks on the window object.
+export function registerBlobDevHooks(): void {
+  let activeBehaviour: MockBlobBehaviour | null = null;
+
+  window.__mockBlobFetch = (behaviour) => {
+    activeBehaviour = behaviour;
+    _devSetFetchOverride((sha256, mimeType, onProgress) => {
+      if (!activeBehaviour) return Promise.resolve(null);
+      return mockFetchBlob(sha256, mimeType, onProgress, activeBehaviour);
+    });
+  };
+
+  window.__clearMockBlobFetch = () => {
+    activeBehaviour = null;
+    _devSetFetchOverride(null);
+  };
+
+  window.__evictBlob = _devEvictBlob;
+  window.__setBlobFetchTimeout = _devSetBlobFetchTimeout;
+  window.__fetchBlobBySha = _devFetchBlobBySha;
+}