@graffiti-garden/implementation-decentralized 0.1.1 → 0.1.2

package/src/1-services/3-storage-buckets-tests.ts

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "vitest";
 import { StorageBuckets } from "./3-storage-buckets";
 import { GraffitiErrorUnauthorized } from "./utilities";
-import { GraffitiErrorNotFound } from "@graffiti-garden/api";
+import { GraffitiErrorNotFound, GraffitiErrorTooLarge } from "@graffiti-garden/api";
+import { encode as dagCborEncode, decode as dagCborDecode } from "@ipld/dag-cbor";
 
 export function storageBucketTests(
   storageBucketEndpoint: string,
@@ -62,6 +63,203 @@ export function storageBucketTests(
       ).rejects.toThrow();
     });
 
+    test("overwrites across the small and large storage cutoff", async () => {
+      const key = crypto.randomUUID();
+      const small = new Uint8Array([1, 2, 3]);
+      const large = new Uint8Array(32 * 1024 + 1).fill(42);
+      const otherLarge = new Uint8Array(32 * 1024 + 1).fill(43);
+
+      await storageBuckets.put(storageBucketEndpoint, key, large, storageBucketToken);
+      expect(await storageBuckets.get(storageBucketEndpoint, key)).toEqual(large);
+
+      await storageBuckets.put(storageBucketEndpoint, key, otherLarge, storageBucketToken);
+      expect(await storageBuckets.get(storageBucketEndpoint, key)).toEqual(otherLarge);
+
+      await storageBuckets.put(storageBucketEndpoint, key, small, storageBucketToken);
+      expect(await storageBuckets.get(storageBucketEndpoint, key)).toEqual(small);
+
+      await storageBuckets.put(storageBucketEndpoint, key, large, storageBucketToken);
+      expect(await storageBuckets.get(storageBucketEndpoint, key)).toEqual(large);
+
+      await storageBuckets.delete(storageBucketEndpoint, key, storageBucketToken);
+      await expect(storageBuckets.get(storageBucketEndpoint, key)).rejects.toThrow(
+        GraffitiErrorNotFound,
+      );
+    });
+
+    test("batch reads arbitrary keys from one bucket", async () => {
+      const first = crypto.randomUUID();
+      const second = crypto.randomUUID();
+      const missing = crypto.randomUUID();
+      const small = new Uint8Array([1, 2, 3]);
+      const large = new Uint8Array(32 * 1024 + 1).fill(7);
+      await storageBuckets.put(storageBucketEndpoint, first, small, storageBucketToken);
+      await storageBuckets.put(storageBucketEndpoint, second, large, storageBucketToken);
+      try {
+        const response = await fetch(`${storageBucketEndpoint}/values`, {
+          method: "POST",
+          headers: { "Content-Type": "application/cbor" },
+          body: dagCborEncode({
+            keys: [first, missing, second, first],
+            maxValueBytes: small.length,
+          }).slice(),
+        });
+        expect(response.status).toBe(200);
+        const decoded = dagCborDecode(await response.arrayBuffer()) as {
+          results: Array<{ status: number; value?: Uint8Array; etag?: string }>;
+        };
+        expect(decoded.results.map(({ status }) => status)).toEqual([200, 404, 413, 200]);
+        expect(decoded.results[0].value).toEqual(small);
+        expect(decoded.results[0].etag).toBeTypeOf("string");
+        expect(decoded.results[3].value).toEqual(small);
+        const largeResponse = await fetch(`${storageBucketEndpoint}/values`, {
+          method: "POST",
+          headers: { "Content-Type": "application/cbor" },
+          body: dagCborEncode({
+            keys: [second],
+            maxValueBytes: large.length,
+          }).slice(),
+        });
+        expect(largeResponse.status).toBe(200);
+        const largeDecoded = dagCborDecode(await largeResponse.arrayBuffer()) as {
+          results: Array<{ status: number; value?: Uint8Array }>;
+        };
+        expect(largeDecoded.results[0].value).toEqual(large);
+
+        const oversizedResponse = await fetch(`${storageBucketEndpoint}/values`, {
+          method: "POST",
+          headers: { "Content-Type": "application/cbor" },
+          body: dagCborEncode({
+            keys: [first, second],
+            maxValueBytes: 1024 * 1024,
+          }).slice(),
+        });
+        expect(oversizedResponse.status).toBe(400);
+
+        const settled = await Promise.allSettled([
+          storageBuckets.get(storageBucketEndpoint, first, small.length),
+          storageBuckets.get(storageBucketEndpoint, missing, small.length),
+          storageBuckets.get(storageBucketEndpoint, second, small.length),
+        ]);
+        expect(settled[0]).toEqual({ status: "fulfilled", value: small });
+        expect(settled[1].status).toBe("rejected");
+        expect((settled[1] as PromiseRejectedResult).reason).toBeInstanceOf(GraffitiErrorNotFound);
+        expect(settled[2].status).toBe("rejected");
+        expect((settled[2] as PromiseRejectedResult).reason).toBeInstanceOf(GraffitiErrorTooLarge);
+        expect(await storageBuckets.get(storageBucketEndpoint, second)).toEqual(large);
+      } finally {
+        await storageBuckets.delete(storageBucketEndpoint, first, storageBucketToken);
+        await storageBuckets.delete(storageBucketEndpoint, second, storageBucketToken);
+      }
+    });
+
+    test("accepts a full batch of maximum-length Unicode keys", async () => {
+      const key = "界".repeat(255);
+      const body = dagCborEncode({
+        keys: Array(32).fill(key),
+        maxValueBytes: 0,
+      }).slice();
+      expect(body.byteLength).toBeGreaterThan(16 * 1024);
+      const response = await fetch(`${storageBucketEndpoint}/values`, {
+        method: "POST",
+        headers: { "Content-Type": "application/cbor" },
+        body,
+      });
+      expect(response.status).toBe(200);
+      const decoded = dagCborDecode(await response.arrayBuffer()) as {
+        results: Array<{ status: number }>;
+      };
+      expect(decoded.results.map(({ status }) => status)).toEqual(Array(32).fill(404));
+    });
+
+    test("concurrent bounded gets share one batch", async () => {
+      const keys = Array.from({ length: 3 }, () => crypto.randomUUID());
+      const values = keys.map((_, i) => new Uint8Array([i + 1]));
+      for (let i = 0; i < keys.length; i++) {
+        await storageBuckets.put(storageBucketEndpoint, keys[i], values[i], storageBucketToken);
+      }
+      const originalFetch = globalThis.fetch;
+      const calls: string[] = [];
+      globalThis.fetch = (input, init) => {
+        const request = new Request(input, init);
+        calls.push(`${request.method} ${request.url}`);
+        return originalFetch(input, init);
+      };
+      try {
+        expect(await Promise.all(keys.map((key) =>
+          storageBuckets.get(storageBucketEndpoint, key, 1),
+        ))).toEqual(values);
+        expect(calls.filter((call) => call === `POST ${storageBucketEndpoint}/values`)).toHaveLength(1);
+        expect(calls.filter((call) => call.includes("/value/"))).toHaveLength(0);
+      } finally {
+        globalThis.fetch = originalFetch;
+        for (const key of keys) {
+          await storageBuckets.delete(storageBucketEndpoint, key, storageBucketToken);
+        }
+      }
+    });
+
+    test("falls back to GET when a bucket server does not support batches", async () => {
+      const keys = Array.from({ length: 2 }, () => crypto.randomUUID());
+      const value = new Uint8Array([42]);
+      for (const key of keys) {
+        await storageBuckets.put(storageBucketEndpoint, key, value, storageBucketToken);
+      }
+      const originalFetch = globalThis.fetch;
+      let batchAttempts = 0;
+      globalThis.fetch = (input, init) => {
+        const request = new Request(input, init);
+        if (request.method === "POST" && request.url === `${storageBucketEndpoint}/values`) {
+          batchAttempts++;
+          return Promise.resolve(new Response("Not found", { status: 404 }));
+        }
+        return originalFetch(input, init);
+      };
+      try {
+        const legacyBuckets = new StorageBuckets();
+        expect(await Promise.all(keys.map((key) =>
+          legacyBuckets.get(storageBucketEndpoint, key, 1),
+        ))).toEqual([value, value]);
+        expect(await Promise.all(keys.map((key) =>
+          legacyBuckets.get(storageBucketEndpoint, key, 1),
+        ))).toEqual([value, value]);
+        expect(batchAttempts).toBe(1);
+      } finally {
+        globalThis.fetch = originalFetch;
+        for (const key of keys) {
+          await storageBuckets.delete(storageBucketEndpoint, key, storageBucketToken);
+        }
+      }
+    });
+
+    test("a batch error does not disable batching or fall back to GET", async () => {
+      const originalFetch = globalThis.fetch;
+      let batchAttempts = 0;
+      let getAttempts = 0;
+      globalThis.fetch = (input, init) => {
+        const request = new Request(input, init);
+        if (request.method === "POST") {
+          batchAttempts++;
+          return Promise.resolve(new Response("Batch limit exceeded", { status: 413 }));
+        }
+        getAttempts++;
+        return originalFetch(input, init);
+      };
+      try {
+        const buckets = new StorageBuckets();
+        const readPair = () => Promise.all([
+          buckets.get(storageBucketEndpoint, "a", 1),
+          buckets.get(storageBucketEndpoint, "b", 1),
+        ]);
+        await expect(readPair()).rejects.toThrow("Batch limit exceeded");
+        await expect(readPair()).rejects.toThrow("Batch limit exceeded");
+        expect(batchAttempts).toBe(2);
+        expect(getAttempts).toBe(0);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
     test("unauthorized", async () => {
       const key = Math.random().toString(36).substring(2, 15);
       const input = "Hello world";

package/src/1-services/3-storage-buckets.ts

@@ -4,10 +4,33 @@ import {
   verifyHTTPSEndpoint,
 } from "./utilities";
 import { string, array, object, optional, nullable } from "zod/mini";
-import { decode as dagCborDecode } from "@ipld/dag-cbor";
+import { encode as dagCborEncode, decode as dagCborDecode } from "@ipld/dag-cbor";
+import { GraffitiErrorNotFound, GraffitiErrorTooLarge } from "@graffiti-garden/api";
+
+// All batch-capable bucket servers accept these transport limits.
+const BATCH_KEYS = 32; // total number of keys in a batch request
+const BATCH_TOTAL_VALUE_BYTES = 1024 * 1024; // total response limit
+
+// This is a heuristic for how long to wait to fill a batch request
+// before sending it. Just enough waiting to capture a few more requests,
+// but not so long that it adds noticeable latency.
+const BATCH_WAIT_MS = 2;
+
+function batchWidth(maxBytes: number) {
+  return Math.min(BATCH_KEYS, Math.floor(BATCH_TOTAL_VALUE_BYTES / maxBytes));
+}
+
+type PendingGet = {
+  key: string;
+  resolve: (value: Uint8Array) => void;
+  reject: (reason: unknown) => void;
+};
+type BatchQueue = { requests: PendingGet[]; timer?: ReturnType<typeof setTimeout> };
 
 export class StorageBuckets {
   getAuthorizationEndpoint = getAuthorizationEndpoint;
+  private readonly queues = new Map<string, Map<number, BatchQueue>>();
+  private readonly unsupportedBatchEndpoints = new Set<string>();
 
   async put(
     storageBucketEndpoint: string,
@@ -50,6 +73,111 @@ export class StorageBuckets {
     maxBytes?: number,
   ): Promise<Uint8Array> {
     verifyHTTPSEndpoint(storageBucketEndpoint);
+    if (
+      maxBytes !== undefined &&
+      Number.isSafeInteger(maxBytes) &&
+      maxBytes > 0 &&
+      batchWidth(maxBytes) >= 2 &&
+      !this.unsupportedBatchEndpoints.has(storageBucketEndpoint)
+    ) {
+      return new Promise<Uint8Array>((resolve, reject) => {
+        let queuesByMaxBytes = this.queues.get(storageBucketEndpoint);
+        if (!queuesByMaxBytes) {
+          queuesByMaxBytes = new Map();
+          this.queues.set(storageBucketEndpoint, queuesByMaxBytes);
+        }
+        let queue = queuesByMaxBytes.get(maxBytes);
+        if (!queue) {
+          queue = { requests: [] };
+          queuesByMaxBytes.set(maxBytes, queue);
+        }
+        queue.requests.push({ key, resolve, reject });
+        if (queue.requests.length === batchWidth(maxBytes)) {
+          this.flush(storageBucketEndpoint, maxBytes, queue);
+        } else if (queue.timer === undefined) {
+          queue.timer = setTimeout(
+            () => this.flush(storageBucketEndpoint, maxBytes, queue),
+            BATCH_WAIT_MS,
+          );
+        }
+      });
+    }
+    return this.getOne(storageBucketEndpoint, key, maxBytes);
+  }
+
+  private flush(endpoint: string, maxBytes: number, queue: BatchQueue) {
+    if (queue.timer !== undefined) clearTimeout(queue.timer);
+    const requests = queue.requests;
+    const queuesByMaxBytes = this.queues.get(endpoint)!;
+    queuesByMaxBytes.delete(maxBytes);
+    if (queuesByMaxBytes.size === 0) this.queues.delete(endpoint);
+    if (requests.length === 1 || this.unsupportedBatchEndpoints.has(endpoint)) {
+      requests.forEach(({ key, resolve, reject }) => {
+        void this.getOne(endpoint, key, maxBytes).then(resolve, reject);
+      });
+    } else {
+      void this.getBatch(endpoint, maxBytes, requests);
+    }
+  }
+
+  private async getBatch(endpoint: string, maxBytes: number, requests: PendingGet[]) {
+    try {
+      const response = await fetch(`${endpoint}/values`, {
+        method: "POST",
+        headers: { "Content-Type": "application/cbor", Accept: "application/cbor" },
+        body: dagCborEncode({
+          keys: requests.map(({ key }) => key),
+          maxValueBytes: maxBytes,
+        }).slice(),
+      });
+      if (response.status === 404) {
+        // An older bucket server has no /values route but still serves GETs.
+        this.unsupportedBatchEndpoints.add(endpoint);
+        await Promise.all(requests.map(async ({ key, resolve, reject }) => {
+          try {
+            resolve(await this.getOne(endpoint, key, maxBytes));
+          } catch (error) {
+            reject(error);
+          }
+        }));
+        return;
+      }
+      if (!response.ok) throw new Error(await response.text());
+      const decoded = dagCborDecode(await response.arrayBuffer());
+      if (
+        !decoded || typeof decoded !== "object" ||
+        !("results" in decoded) || !Array.isArray(decoded.results) ||
+        decoded.results.length !== requests.length
+      ) throw new Error("Invalid storage batch response");
+
+      decoded.results.forEach((result: unknown, index: number) => {
+        const { resolve, reject } = requests[index];
+        if (!result || typeof result !== "object" || !("status" in result)) {
+          reject(new Error("Invalid storage batch result"));
+        } else if (
+          result.status === 200 && "value" in result &&
+          result.value instanceof Uint8Array &&
+          result.value.byteLength <= maxBytes
+        ) {
+          resolve(result.value);
+        } else if (result.status === 404) {
+          reject(new GraffitiErrorNotFound("Value not found"));
+        } else if (result.status === 413) {
+          reject(new GraffitiErrorTooLarge("Value exceeds maximum byte limit"));
+        } else {
+          reject(new Error("Invalid storage batch result"));
+        }
+      });
+    } catch (error) {
+      requests.forEach(({ reject }) => reject(error));
+    }
+  }
+
+  private async getOne(
+    storageBucketEndpoint: string,
+    key: string,
+    maxBytes?: number,
+  ): Promise<Uint8Array> {
     const url = `${storageBucketEndpoint}/value/${encodeURIComponent(key)}`;
 
     const response = await fetchWithErrorHandling(url);

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

@@ -3,6 +3,7 @@ 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 { encode as dagCborEncode, decode as dagCborDecode } from "@ipld/dag-cbor";
 
 export function inboxTests(inboxEndpoint: string, inboxToken: string) {
   describe("Inboxes", async () => {
@@ -138,6 +139,30 @@ export function inboxTests(inboxEndpoint: string, inboxToken: string) {
         });
       }
 
+      let cursor: string | undefined;
+      for (const [page, expectedCount] of [10, 100, 101].entries()) {
+        const response = await fetch(
+          `${inboxEndpoint}/query${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/cbor",
+              Authorization: `Bearer ${inboxToken}`,
+            },
+            body: cursor ? undefined : dagCborEncode({ tags: [tags[1]], schema: {} }).slice(),
+          },
+        );
+        expect(response.status).toBe(200);
+        const pageResult = dagCborDecode(new Uint8Array(await response.arrayBuffer())) as {
+          results: unknown[];
+          hasMore: boolean;
+          cursor: string;
+        };
+        expect(pageResult.results).toHaveLength(expectedCount);
+        expect(pageResult.hasMore).toBe(page < 2);
+        cursor = pageResult.cursor;
+      }
+
       const iterator = inboxes.query(
         inboxEndpoint,
         [randomBytes(), tags[1], randomBytes()],