@graffiti-garden/implementation-decentralized 0.1.2 → 0.1.4

package/src/1-services/4-inboxes/cache.ts

@@ -0,0 +1,227 @@
+import { encode as dagCborEncode } from "@ipld/dag-cbor";
+import { LABELED_MESSAGE_ID_KEY, type LabeledMessageBase } from "./messages";
+
+// One record per inbox query. Messages live in the separate message cache;
+// this record tracks their IDs and where to continue fetching from the server.
+export type CacheQueryValue = {
+  // Server continuation state for the next page.
+  cursor: string;
+  // Identifies this local query history, not a server version. It stays the
+  // same as pages arrive; a reset creates a new one so old caller cursors expire.
+  version: string;
+  // All message IDs fetched for this query so far, in order. A caller's
+  // numSeen cursor indexes into this list to replay only unseen messages.
+  messageIds: string[];
+  waitTil?: number;
+  // Changes on every cached page write, even if the page is empty and neither
+  // messageIds nor cursor changes. A tab waiting on the query lock can use this
+  // to detect and reuse a page fetched by another tab. Older entries lack it.
+  generation?: string;
+  // Whether the server has another page; needed when reusing another tab's
+  // cached page. Older cache entries lack this and are refreshed on next query.
+  hasMore?: boolean;
+};
+
+export async function canUseIDB(): Promise<boolean> {
+  try {
+    if (!globalThis.indexedDB) return false;
+
+    // Small probe database
+    await new Promise<void>((resolve, reject) => {
+      const req = indexedDB.open("__idb_probe__", 1);
+      req.onupgradeneeded = () => req.result.createObjectStore("k");
+      req.onsuccess = () => {
+        req.result.close();
+        resolve();
+      };
+      req.onerror = () => reject(req.error);
+    });
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type Cache = {
+  messages: {
+    get(k: string): Promise<LabeledMessageBase | null | undefined>;
+    set(k: string, value: LabeledMessageBase | null): Promise<void>;
+    setMany(entries: [string, LabeledMessageBase][]): Promise<void>;
+    del(k: string): Promise<void>;
+  };
+  messageIds: {
+    get(k: string): Promise<CacheQueryValue | undefined>;
+    set(k: string, value: CacheQueryValue): Promise<void>;
+    del(k: string): Promise<void>;
+  };
+};
+
+export function getMessageCacheKey(inboxUrl: string, messageId: string) {
+  return `${encodeURIComponent(inboxUrl)}:${encodeURIComponent(messageId)}`;
+}
+
+export async function replayQuery(
+  cache: Cache,
+  inboxUrl: string,
+  messageIdsCacheKey: string,
+  query: CacheQueryValue,
+  numSeen = 0,
+): Promise<LabeledMessageBase[]> {
+  // Filter out all messageIds before
+  // the number already seen
+  const messageIds = query.messageIds.slice(numSeen);
+
+  // Get all the messages pointed to in the cache
+  return Promise.all(
+    messageIds.map(async (id) => {
+      const message = await cache.messages.get(getMessageCacheKey(inboxUrl, id));
+      if (!message) {
+        // Something is very wrong with the cache,
+        // it refers to message IDs that are not cached
+        try {
+          await cache.messageIds.del(messageIdsCacheKey);
+        } catch {}
+        throw new Error("Cache out of sync - perhaps clear browser storage");
+      }
+      return message;
+    }),
+  );
+}
+
+export async function storeQueryPage(
+  cache: Cache,
+  inboxUrl: string,
+  messageIdsCacheKey: string,
+  previous: CacheQueryValue | undefined,
+  page: {
+    messages: LabeledMessageBase[];
+    cursor: string;
+    hasMore: boolean;
+    waitTil?: number;
+  },
+): Promise<CacheQueryValue> {
+  // First cache the messages with their labels
+  await cache.messages.setMany(
+    page.messages.map((message) => [
+      getMessageCacheKey(inboxUrl, message[LABELED_MESSAGE_ID_KEY]),
+      message,
+    ]),
+  );
+  // Then store all the messageids
+  const query = {
+    cursor: page.cursor,
+    version: previous?.version ?? crypto.randomUUID(),
+    messageIds: [
+      ...(previous?.messageIds ?? []),
+      ...page.messages.map((message) => message[LABELED_MESSAGE_ID_KEY]),
+    ],
+    generation: crypto.randomUUID(),
+    hasMore: page.hasMore,
+    waitTil: page.waitTil,
+  };
+  await cache.messageIds.set(messageIdsCacheKey, query);
+  return query;
+}
+
+export async function getMessageIdsCacheKey(
+  inboxUrl: string,
+  type: "query" | "export",
+  body?: Uint8Array,
+): Promise<string> {
+  const cacheIdData = dagCborEncode({
+    inboxUrl,
+    type,
+    body: body ?? null,
+  });
+  return crypto.subtle
+    .digest("SHA-256", new Uint8Array(cacheIdData))
+    .then((bytes) =>
+      Array.from(new Uint8Array(bytes))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join(""),
+    );
+}
+
+async function resetCacheDB() {
+  await new Promise<void>((resolve) => {
+    const req = indexedDB.deleteDatabase("graffiti-inbox-cache");
+    req.onsuccess = () => resolve();
+    req.onerror = () => resolve(); // best effort
+    req.onblocked = () => resolve(); // best effort
+  });
+}
+
+export async function createCache(): Promise<Cache> {
+  if (await canUseIDB()) {
+    const { openDB } = await import("idb");
+    const db = await openDB("graffiti-inbox-cache", 1, {
+      upgrade(db) {
+        if (!db.objectStoreNames.contains("m")) db.createObjectStore("m");
+        if (!db.objectStoreNames.contains("q")) db.createObjectStore("q");
+      },
+    });
+
+    return {
+      messages: {
+        get: async (k) => {
+          try {
+            return db.get("m", k);
+          } catch (error) {
+            console.error("Error getting message from cache:", error);
+            console.error("resetting cache...");
+            await resetCacheDB();
+            return undefined;
+          }
+        },
+        set: async (k, v) => {
+          await db.put("m", v, k);
+        },
+        setMany: async (entries) => {
+          if (entries.length === 0) return;
+          const tx = db.transaction("m", "readwrite");
+          await Promise.all([
+            ...entries.map(([k, v]) => tx.store.put(v, k)),
+            tx.done,
+          ]);
+        },
+        del: (k) => db.delete("m", k),
+      },
+      messageIds: {
+        get: async (k) => {
+          try {
+            return await db.get("q", k);
+          } catch (error) {
+            console.error("Error getting message IDs from cache:", error);
+            console.error("resetting cache...");
+            await resetCacheDB();
+            return undefined;
+          }
+        },
+        set: async (k, v) => {
+          await db.put("q", v, k);
+        },
+        del: (k) => db.delete("q", k),
+      },
+    };
+  }
+
+  const m = new Map<string, LabeledMessageBase | null>();
+  const q = new Map<string, CacheQueryValue>();
+
+  return {
+    messages: {
+      get: async (k) => m.get(k),
+      set: async (k, v) => void m.set(k, v),
+      setMany: async (entries) => {
+        for (const [k, v] of entries) m.set(k, v);
+      },
+      del: async (k) => void m.delete(k),
+    },
+    messageIds: {
+      get: async (k) => q.get(k),
+      set: async (k, v) => void q.set(k, v),
+      del: async (k) => void q.delete(k),
+    },
+  };
+}

package/src/1-services/4-inboxes/messages.ts

@@ -0,0 +1,63 @@
+import type { JSONSchema, GraffitiObject } from "@graffiti-garden/api";
+import {
+  type infer as infer_,
+  string,
+  url,
+  array,
+  optional,
+  nullable,
+  strictObject,
+  looseObject,
+  custom,
+  number,
+  boolean,
+} from "zod/mini";
+
+const GraffitiObjectSchema = strictObject({
+  value: looseObject({}),
+  channels: array(string()),
+  allowed: optional(nullable(array(url()))),
+  url: url(),
+  actor: url(),
+});
+export const Uint8ArraySchema = custom<Uint8Array>(
+  (v): v is Uint8Array => v instanceof Uint8Array,
+);
+export const TagsSchema = array(Uint8ArraySchema);
+
+export const MESSAGE_TAGS_KEY = "t";
+export const MESSAGE_OBJECT_KEY = "o";
+export const MESSAGE_METADATA_KEY = "m";
+export const MessageBaseSchema = strictObject({
+  [MESSAGE_TAGS_KEY]: TagsSchema,
+  [MESSAGE_OBJECT_KEY]: GraffitiObjectSchema,
+  [MESSAGE_METADATA_KEY]: Uint8ArraySchema,
+});
+type MessageBase = infer_<typeof MessageBaseSchema>;
+
+export const LABELED_MESSAGE_ID_KEY = "id";
+export const LABELED_MESSAGE_MESSAGE_KEY = "m";
+export const LABELED_MESSAGE_LABEL_KEY = "l";
+export const LabeledMessageBaseSchema = strictObject({
+  [LABELED_MESSAGE_ID_KEY]: string(),
+  [LABELED_MESSAGE_MESSAGE_KEY]: MessageBaseSchema,
+  [LABELED_MESSAGE_LABEL_KEY]: number(),
+});
+export type LabeledMessageBase = infer_<typeof LabeledMessageBaseSchema>;
+
+export type Message<Schema extends JSONSchema> = MessageBase & {
+  [MESSAGE_OBJECT_KEY]: GraffitiObject<Schema>;
+};
+export type LabeledMessage<Schema extends JSONSchema> = LabeledMessageBase & {
+  [LABELED_MESSAGE_MESSAGE_KEY]: {
+    [MESSAGE_OBJECT_KEY]: GraffitiObject<Schema>;
+  };
+};
+
+export const SendResponseSchema = strictObject({ id: string() });
+
+export const MessageResultSchema = strictObject({
+  results: array(LabeledMessageBaseSchema),
+  hasMore: boolean(),
+  cursor: string(),
+});

package/src/1-services/4-inboxes-tests.ts

@@ -1,8 +1,8 @@
-import { assert, describe, expect, test } from "vitest";
+import { afterEach, assert, describe, expect, test, vi } from "vitest";
 import { Inboxes, LABELED_MESSAGE_LABEL_KEY } from "./4-inboxes";
 import { GraffitiErrorUnauthorized } from "./utilities";
 import { randomBytes } from "@noble/hashes/utils.js";
-import type { GraffitiObjectBase } from "@graffiti-garden/api";
+import { GraffitiErrorCursorExpired, type GraffitiObjectBase } from "@graffiti-garden/api";
 import { encode as dagCborEncode, decode as dagCborDecode } from "@ipld/dag-cbor";
 
 export function inboxTests(inboxEndpoint: string, inboxToken: string) {
@@ -179,3 +179,388 @@ export function inboxTests(inboxEndpoint: string, inboxToken: string) {
     }, 100000);
   });
 }
+
+// Focused client behavior tests use mocked network and browser locks.
+const inboxUrl = "https://example.test/inbox";
+const message = {
+  id: "message-1",
+  m: {
+    t: [new Uint8Array([1])],
+    o: {
+      url: "https://example.test/object",
+      actor: "did:example:author",
+      channels: ["test"],
+      value: {},
+    },
+    m: new Uint8Array([2]),
+  },
+  l: 0,
+};
+
+function cborResponse(value: unknown) {
+  return new Response(new Uint8Array(dagCborEncode(value)).slice(), {
+    headers: { "Content-Type": "application/cbor" },
+  });
+}
+
+function queryPage(results: (typeof message)[], cursor: string, hasMore = false) {
+  return cborResponse({ results, hasMore, cursor });
+}
+
+class TestInboxes extends Inboxes {
+  async prepareCache() {
+    await this.cache;
+  }
+
+  async deleteCachedQuery(key: string) {
+    await (await this.cache).messageIds.del(key);
+  }
+
+  async fetchQueryBatch() {
+    const batch = await this.fetchMessageBatch(
+      "https://example.test/inbox",
+      "query",
+      undefined,
+    );
+    await batch.response.arrayBuffer();
+    return batch;
+  }
+}
+
+function enableLockPath(request: unknown) {
+  vi.stubGlobal("indexedDB", {
+    open: () => {
+      const probe: { result?: { close: () => void }; onsuccess?: () => void } = {};
+      queueMicrotask(() => {
+        probe.result = { close() {} };
+        probe.onsuccess?.();
+      });
+      return probe;
+    },
+  });
+  vi.stubGlobal("window", { navigator: { locks: { request } } });
+}
+
+export function inboxUnitTests() {
+  describe("Inboxes unit", () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+      vi.restoreAllMocks();
+    });
+
+    describe("inbox stream lock and network failures", () => {
+      test("backs off for five seconds after an initial request failure", async () => {
+        const failure = new Error("offline");
+        const fetch = vi.fn(() => Promise.reject(failure));
+        vi.stubGlobal("fetch", fetch);
+        vi.spyOn(console, "error").mockImplementation(() => {});
+        const realSetTimeout = globalThis.setTimeout;
+        const timer = vi.spyOn(globalThis, "setTimeout").mockImplementation(
+          ((handler: TimerHandler, delay?: number, ...args: unknown[]) =>
+            realSetTimeout(
+              handler,
+              delay === 5000 ? 0 : delay,
+              ...args,
+            )) as typeof setTimeout,
+        );
+
+        await expect(new Inboxes().query(inboxUrl, [], {}).next()).rejects.toBe(
+          failure,
+        );
+        expect(fetch).toHaveBeenCalledOnce();
+        expect(timer).toHaveBeenCalledWith(expect.any(Function), 5000);
+      });
+
+      test("a rejected lock request rejects the stream", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        const error = new Error("lock request failed");
+        enableLockPath(vi.fn(() => Promise.reject(error)));
+
+        await expect(
+          inboxes.query("https://example.test/inbox", [], {}).next(),
+        ).rejects.toBe(error);
+      });
+
+      test("waiting for another tab's lock has a deadline", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        const timeoutError = new DOMException("timed out", "TimeoutError");
+        vi.spyOn(AbortSignal, "timeout").mockReturnValue(
+          AbortSignal.abort(timeoutError),
+        );
+        const request = vi.fn(
+          (
+            _key: string,
+            _options: { signal?: AbortSignal },
+          ) => Promise.reject(timeoutError),
+        );
+        enableLockPath(request);
+
+        await expect(
+          inboxes.query("https://example.test/inbox", [], {}).next(),
+        ).rejects.toThrow("Timed out waiting for another tab's inbox query");
+        expect(request).toHaveBeenCalledOnce();
+      });
+
+      test("a stalled request is aborted", async () => {
+        const realTimeout = AbortSignal.timeout;
+        vi.spyOn(AbortSignal, "timeout").mockImplementation(() => realTimeout(5));
+        vi.stubGlobal(
+          "fetch",
+          vi.fn((_url: string, options: RequestInit) =>
+            new Promise<Response>((_resolve, reject) => {
+              const signal = options.signal as AbortSignal;
+              signal.addEventListener("abort", () => reject(signal.reason), {
+                once: true,
+              });
+            }),
+          ),
+        );
+
+        await expect(new TestInboxes().fetchQueryBatch()).rejects.toMatchObject({
+          name: "TimeoutError",
+        });
+      });
+
+      test("the deadline remains active while reading a response body", async () => {
+        const realTimeout = AbortSignal.timeout;
+        vi.spyOn(AbortSignal, "timeout").mockImplementation(() => realTimeout(5));
+        vi.stubGlobal(
+          "fetch",
+          vi.fn((_url: string, options: RequestInit) => {
+            const signal = options.signal as AbortSignal;
+            const body = new ReadableStream({
+              start(controller) {
+                signal.addEventListener("abort", () => controller.error(signal.reason), {
+                  once: true,
+                });
+              },
+            });
+            return Promise.resolve(new Response(body));
+          }),
+        );
+
+        await expect(new TestInboxes().fetchQueryBatch()).rejects.toMatchObject({
+          name: "TimeoutError",
+        });
+      });
+    });
+
+    describe("inbox query cache", () => {
+      test("fetches the next page while the current message is yielded", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        let held = 0;
+        enableLockPath(vi.fn(async (
+          key: string,
+          _options: { signal?: AbortSignal },
+          callback: (lock: Lock) => Promise<unknown>,
+        ) => {
+          held++;
+          try {
+            return await callback({ name: key, mode: "exclusive" });
+          } finally {
+            held--;
+          }
+        }));
+        let prefetchAborted = false;
+        const fetch = vi.fn((_url: string, options: RequestInit) => {
+          if (fetch.mock.calls.length === 1) {
+            return Promise.resolve(queryPage([message], "cursor-1", true));
+          }
+          return new Promise<Response>((_resolve, reject) => {
+            const signal = options.signal as AbortSignal;
+            signal.addEventListener("abort", () => {
+              prefetchAborted = true;
+              reject(signal.reason);
+            }, { once: true });
+          });
+        });
+        vi.stubGlobal("fetch", fetch);
+
+        const iterator = inboxes.query(inboxUrl, [new Uint8Array([1])], {});
+        expect((await iterator.next()).value).toEqual(message);
+        await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+        expect(fetch.mock.calls[1][0]).toBe(`${inboxUrl}/query?cursor=cursor-1`);
+        await iterator.return("");
+        expect(prefetchAborted).toBe(true);
+        await vi.waitFor(() => expect(held).toBe(0));
+      });
+
+      test("reports a cursor that expires after the first page", async () => {
+        const fetch = vi.fn()
+          .mockResolvedValueOnce(queryPage([message], "cursor-1", true))
+          .mockResolvedValueOnce(new Response("stale", { status: 410 }));
+        vi.stubGlobal("fetch", fetch);
+
+        const iterator = new Inboxes().query(inboxUrl, [new Uint8Array([1])], {});
+        expect((await iterator.next()).value).toEqual(message);
+        await expect(iterator.next()).rejects.toBeInstanceOf(
+          GraffitiErrorCursorExpired,
+        );
+        expect(fetch).toHaveBeenCalledTimes(2);
+      });
+
+      test("does not replay messages after another tab resets the cache", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        let markPrefetchStarted!: () => void;
+        const prefetchStarted = new Promise<void>((resolve) => {
+          markPrefetchStarted = resolve;
+        });
+        let releasePrefetch!: () => void;
+        const pause = new Promise<void>((resolve) => {
+          releasePrefetch = resolve;
+        });
+        let lockCalls = 0;
+        let cacheKey = "";
+        enableLockPath(vi.fn(async (
+          name: string,
+          _options: { signal?: AbortSignal },
+          work: (lock: Lock) => Promise<unknown>,
+        ) => {
+          cacheKey = name.slice("graffiti:inbox:".length);
+          if (++lockCalls === 2) {
+            markPrefetchStarted();
+            await pause;
+          }
+          return work({ name, mode: "exclusive" });
+        }));
+        vi.stubGlobal("fetch", vi.fn(async () => queryPage([message], "cursor-1", true)));
+
+        const iterator = inboxes.query(inboxUrl, [new Uint8Array([1])], {});
+        expect((await iterator.next()).value).toEqual(message);
+        await prefetchStarted;
+        await inboxes.deleteCachedQuery(cacheKey);
+        releasePrefetch();
+        await expect(iterator.next()).rejects.toBeInstanceOf(
+          GraffitiErrorCursorExpired,
+        );
+      });
+
+      test("a later query reads messages from the cached server cursor", async () => {
+        const fetch = vi.fn()
+          .mockResolvedValueOnce(queryPage([message], "cursor-1"))
+          .mockResolvedValueOnce(queryPage([], "cursor-2"));
+        vi.stubGlobal("fetch", fetch);
+        const inboxes = new Inboxes();
+        const tags = [new Uint8Array([1])];
+
+        const first = inboxes.query(inboxUrl, tags, {});
+        expect((await first.next()).value).toEqual(message);
+        expect((await first.next()).done).toBe(true);
+
+        const second = inboxes.query(inboxUrl, tags, {});
+        expect((await second.next()).value).toEqual(message);
+        expect((await second.next()).done).toBe(true);
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(fetch.mock.calls[1][0]).toBe(`${inboxUrl}/query?cursor=cursor-1`);
+      });
+
+      test("does not hold the query lock while a message is yielded", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        let held = false;
+        enableLockPath(vi.fn(async (
+          key: string,
+          _options: { ifAvailable?: boolean },
+          callback: (lock: Lock) => Promise<unknown>,
+        ) => {
+          held = true;
+          try {
+            return await callback({ name: key, mode: "exclusive" });
+          } finally {
+            held = false;
+          }
+        }));
+        vi.stubGlobal("fetch", vi.fn(async () => queryPage([message], "cursor-1")));
+
+        const iterator = inboxes.query(inboxUrl, [new Uint8Array([1])], {});
+        try {
+          expect((await iterator.next()).value).toEqual(message);
+          expect(held).toBe(false);
+        } finally {
+          await iterator.return("");
+        }
+      });
+
+      test("closing a yielded query leaves no lock held", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        let held = false;
+        enableLockPath(vi.fn(async (
+          key: string,
+          _options: { ifAvailable?: boolean },
+          callback: (lock: Lock) => Promise<unknown>,
+        ) => {
+          held = true;
+          try {
+            return await callback({ name: key, mode: "exclusive" });
+          } finally {
+            held = false;
+          }
+        }));
+        vi.stubGlobal("fetch", vi.fn(async () => queryPage([message], "cursor-1")));
+
+        const iterator = inboxes.query(inboxUrl, [new Uint8Array([1])], {});
+        expect((await iterator.next()).value).toEqual(message);
+        expect(held).toBe(false);
+        await iterator.return("");
+        expect(held).toBe(false);
+      });
+
+      test("concurrent queries reuse a page fetched under the lock", async () => {
+        const inboxes = new TestInboxes();
+        await inboxes.prepareCache();
+        let releasePrevious = Promise.resolve();
+        let requests = 0;
+        let bothRequested!: () => void;
+        const ready = new Promise<void>((resolve) => { bothRequested = resolve; });
+        enableLockPath(vi.fn(async (
+          key: string,
+          _options: { signal?: AbortSignal },
+          callback: (lock: Lock) => Promise<unknown>,
+        ) => {
+          requests++;
+          if (requests === 2) bothRequested();
+          const previous = releasePrevious;
+          let release!: () => void;
+          releasePrevious = new Promise<void>((resolve) => { release = resolve; });
+          await previous;
+          try {
+            return await callback({ name: key, mode: "exclusive" });
+          } finally {
+            release();
+          }
+        }));
+        const nextMessage = { ...message, id: "message-2" };
+        const fetch = vi.fn(async () => {
+          await ready;
+          return fetch.mock.calls.length === 1
+            ? queryPage([message], "cursor-1", true)
+            : queryPage([nextMessage], "cursor-2");
+        });
+        vi.stubGlobal("fetch", fetch);
+
+        const tags = [new Uint8Array([1])];
+        const first = inboxes.query(inboxUrl, tags, {});
+        const second = inboxes.query(inboxUrl, tags, {});
+        const [firstResult, secondResult] = await Promise.all([
+          first.next(), second.next(),
+        ]);
+        expect(firstResult.value).toEqual(message);
+        expect(secondResult.value).toEqual(message);
+        const [firstNext, secondNext] = await Promise.all([
+          first.next(), second.next(),
+        ]);
+        expect(firstNext.value).toEqual(nextMessage);
+        expect(secondNext.value).toEqual(nextMessage);
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect((await first.next()).done).toBe(true);
+        expect((await second.next()).done).toBe(true);
+      });
+
+    });
+  });
+}