@freqhole/reliquary 0.0.0

package/dist/blobs/store.test.js

@@ -0,0 +1,377 @@
+// @vitest-environment happy-dom
+//
+// integration tests for the unified blob store: ties the metadata layer
+// (db.ts) and the bytes layer (bytes-backend.ts) together behind
+// createBlobStore(). the worker (hashing + the OPFS write path) is mocked
+// since no environment here has a real Worker or a bundled midden module -
+// the mock computes a deterministic fake "blake3" from the sha256 digest
+// (real crypto.subtle is available in happy-dom) and writes bytes through
+// the exact same fake OPFS directory the direct-read path uses, so the
+// round trip is meaningful.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { fakeIdbHarness } from "../testing/index.js";
+// ---- fake OPFS (same shape as blob-worker-logic.test.ts / bytes-backend.test.ts) ----
+class FakeWritable {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    async write(data) {
+        this.file.bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer);
+    }
+    async close() { }
+}
+class FakeFileHandle {
+    bytes = new Uint8Array(0);
+    async getFile() {
+        const bytes = this.bytes;
+        return { arrayBuffer: async () => bytes.buffer };
+    }
+    async createWritable() {
+        return new FakeWritable(this);
+    }
+}
+class FakeDirHandle {
+    files = new Map();
+    async getFileHandle(name, opts) {
+        let handle = this.files.get(name);
+        if (!handle) {
+            if (!opts?.create)
+                throw new Error(`not found: ${name}`);
+            handle = new FakeFileHandle();
+            this.files.set(name, handle);
+        }
+        return handle;
+    }
+    async getDirectoryHandle(_name, opts) {
+        void opts;
+        return this;
+    }
+    async removeEntry(name) {
+        if (!this.files.delete(name))
+            throw new Error(`not found: ${name}`);
+    }
+}
+let opfsRoot;
+function installFakeOpfs() {
+    opfsRoot = new FakeDirHandle();
+    vi.stubGlobal("navigator", {
+        storage: {
+            getDirectory: async () => opfsRoot,
+        },
+    });
+}
+async function fakeSha256Hex(data) {
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+async function writeToFakeOpfs(id, data) {
+    const root = await navigator.storage.getDirectory();
+    const dir = await root.getDirectoryHandle("reliquary-blobs", { create: true });
+    const file = await dir.getFileHandle(id, { create: true });
+    const writable = await file.createWritable();
+    await writable.write(data);
+    await writable.close();
+}
+vi.mock("../worker/index.js", () => ({
+    BLOB_OPFS_DIR: "reliquary-blobs",
+    writeBlobToOpfs: vi.fn(async (id, data) => {
+        await writeToFakeOpfs(id, data);
+    }),
+    // a real blake3 digest is unavailable in this test environment (no
+    // bundled midden module) - derive a distinct, deterministic stand-in
+    // from the sha256 digest so different content still gets different
+    // content addresses. neither hasher writes any bytes - matching the
+    // real worker client, which only hashes here.
+    hashBlake3: vi.fn(async (data) => {
+        const sha256 = await fakeSha256Hex(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+        return `b3-${sha256}`;
+    }),
+    hashSha256: vi.fn(async (data) => fakeSha256Hex(data)),
+    streamFileToOpfs: vi.fn(async (file) => {
+        const buffer = await file.arrayBuffer();
+        const sha256 = await fakeSha256Hex(buffer);
+        const blake3 = `b3-${sha256}`;
+        await writeToFakeOpfs(blake3, buffer);
+        return { blake3, size: buffer.byteLength };
+    }),
+}));
+const { createBlobStore, DEFAULT_DB_NAME } = await import("./store.js");
+const { putRecord } = await import("./db.js");
+beforeEach(() => {
+    fakeIdbHarness();
+    installFakeOpfs();
+    vi.stubGlobal("URL", {
+        createObjectURL: vi.fn(() => `blob:mock-${Math.random()}`),
+        revokeObjectURL: vi.fn(),
+    });
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+function textBuffer(text) {
+    return new TextEncoder().encode(text).buffer;
+}
+describe("storeBlob / getBlob / getBlobData", () => {
+    it("stores bytes and metadata, then reads them back", async () => {
+        const store = createBlobStore({ dbName: "store-test-1" });
+        const record = await store.storeBlob(textBuffer("hello world"), {
+            filename: "hello.txt",
+            mime: "text/plain",
+        });
+        expect(record.blob_id).toBe(record.blake3);
+        expect(record.filename).toBe("hello.txt");
+        expect(record.blob_type).toBe("original");
+        expect(record.storage_backend).toBe("opfs");
+        const data = await store.getBlobData(record.blob_id);
+        expect(new TextDecoder().decode(data)).toBe("hello world");
+        const blob = await store.getBlob(record.blob_id);
+        expect(blob?.type).toBe("text/plain");
+        expect(new TextDecoder().decode(await blob.arrayBuffer())).toBe("hello world");
+    });
+    it("dedups on content address - storing the same bytes twice returns the same record", async () => {
+        const store = createBlobStore({ dbName: "store-test-dedup" });
+        const first = await store.storeBlob(textBuffer("same content"), {
+            filename: "a.txt",
+            mime: "text/plain",
+        });
+        const second = await store.storeBlob(textBuffer("same content"), {
+            filename: "b.txt",
+            mime: "text/plain",
+        });
+        expect(second).toEqual(first);
+        expect(second.filename).toBe("a.txt");
+    });
+    it("keeps two store instances with different db names from seeing each other's records", async () => {
+        const storeA = createBlobStore({ dbName: "store-test-iso-a" });
+        const storeB = createBlobStore({ dbName: "store-test-iso-b" });
+        const record = await storeA.storeBlob(textBuffer("isolated"), {
+            filename: "iso.txt",
+            mime: "text/plain",
+        });
+        expect(await storeB.getBlobRecord(record.blob_id)).toBeNull();
+        expect(await storeA.getBlobRecord(record.blob_id)).not.toBeNull();
+    });
+    it("defaults to DEFAULT_DB_NAME when no dbName is given", () => {
+        // just confirms the constant is exported and stable, since two default
+        // stores would otherwise silently share state across tests.
+        expect(DEFAULT_DB_NAME).toBe("reliquary-blobs");
+    });
+    it("falls back to the cache-api backend when opfs is unavailable, without throwing", async () => {
+        vi.unstubAllGlobals();
+        vi.stubGlobal("URL", {
+            createObjectURL: vi.fn(() => `blob:mock-${Math.random()}`),
+            revokeObjectURL: vi.fn(),
+        });
+        const cacheStorage = new Map();
+        vi.stubGlobal("caches", {
+            async open(name) {
+                if (!cacheStorage.has(name))
+                    cacheStorage.set(name, new Map());
+                const entries = cacheStorage.get(name);
+                return {
+                    async put(url, response) {
+                        entries.set(url, response);
+                    },
+                    async match(url) {
+                        const found = entries.get(url);
+                        return found ? found.clone() : undefined;
+                    },
+                };
+            },
+        });
+        // no navigator.storage installed at all - opfs is unavailable
+        const store = createBlobStore({
+            dbName: "store-test-cache-fallback",
+            allowCacheFallback: true,
+        });
+        const record = await store.storeBlob(textBuffer("opfs-less content"), {
+            filename: "no-opfs.txt",
+            mime: "text/plain",
+        });
+        expect(record.storage_backend).toBe("cache");
+        const data = await store.getBlobData(record.blob_id);
+        expect(new TextDecoder().decode(data)).toBe("opfs-less content");
+    });
+    it("throws when neither opfs nor cache-api can accept the write", async () => {
+        vi.unstubAllGlobals();
+        // no navigator.storage, no caches - every backend in the chain refuses
+        const store = createBlobStore({ dbName: "store-test-no-backend", allowCacheFallback: true });
+        await expect(store.storeBlob(textBuffer("nowhere to go"), { filename: "x.txt", mime: "text/plain" })).rejects.toThrow(/no bytes backend accepted/);
+    });
+    it("does not fall back to cache-api by default, even when it's available", async () => {
+        vi.unstubAllGlobals();
+        vi.stubGlobal("URL", {
+            createObjectURL: vi.fn(() => `blob:mock-${Math.random()}`),
+            revokeObjectURL: vi.fn(),
+        });
+        const cacheStorage = new Map();
+        vi.stubGlobal("caches", {
+            async open(name) {
+                if (!cacheStorage.has(name))
+                    cacheStorage.set(name, new Map());
+                const entries = cacheStorage.get(name);
+                return {
+                    async put(url, response) {
+                        entries.set(url, response);
+                    },
+                    async match(url) {
+                        const found = entries.get(url);
+                        return found ? found.clone() : undefined;
+                    },
+                };
+            },
+        });
+        // no navigator.storage installed - opfs is unavailable, cache-api is
+        // available but must NOT be used since allowCacheFallback defaults to
+        // false (Q25: loam's crash-loud semantics are the default).
+        const store = createBlobStore({ dbName: "store-test-no-fallback-default" });
+        await expect(store.storeBlob(textBuffer("opfs-less content"), { filename: "no-opfs.txt", mime: "text/plain" })).rejects.toThrow(/no bytes backend accepted/);
+    });
+});
+describe("storeBlobFromFile", () => {
+    it("uses the buffered path for small files", async () => {
+        const store = createBlobStore({ dbName: "store-test-file-small" });
+        const file = new File([textBuffer("small file contents")], "small.txt", { type: "text/plain" });
+        const record = await store.storeBlobFromFile(file);
+        expect(record.filename).toBe("small.txt");
+        expect(record.sha256).toBeTruthy();
+        const data = await store.getBlobData(record.blob_id);
+        expect(new TextDecoder().decode(data)).toBe("small file contents");
+    });
+    it("streams large files and omits sha256 (legacy-only, never computed for streamed uploads)", async () => {
+        const store = createBlobStore({ dbName: "store-test-file-large" });
+        const bigBytes = new Uint8Array(8 * 1024 * 1024 + 10).fill(7);
+        const file = new File([bigBytes], "large.bin", { type: "application/octet-stream" });
+        const record = await store.storeBlobFromFile(file);
+        expect(record.size).toBe(bigBytes.byteLength);
+        expect(record.sha256).toBeUndefined();
+        const data = await store.getBlobData(record.blob_id);
+        expect(data?.byteLength).toBe(bigBytes.byteLength);
+    });
+    it("propagates an AbortError from a cancelled streamed upload without falling back", async () => {
+        const store = createBlobStore({ dbName: "store-test-file-abort" });
+        const worker = await import("../worker/index.js");
+        vi.mocked(worker.streamFileToOpfs).mockRejectedValueOnce(new DOMException("upload cancelled", "AbortError"));
+        const bigBytes = new Uint8Array(8 * 1024 * 1024 + 1);
+        const file = new File([bigBytes], "large.bin");
+        await expect(store.storeBlobFromFile(file)).rejects.toThrow(/upload cancelled/);
+    });
+});
+describe("resolveBlob", () => {
+    it("resolves a legacy sha256-primary-keyed record by its blake3 index", async () => {
+        await putRecord("store-test-resolve", {
+            blob_id: "legacy-sha256-key",
+            blake3: "blake3-known-later",
+            sha256: "legacy-sha256-key",
+            filename: "legacy.txt",
+            mime: "text/plain",
+            size: 4,
+            blob_type: "original",
+            parent_blob_id: null,
+            created_at: 1,
+            storage_backend: "opfs",
+        });
+        const store = createBlobStore({ dbName: "store-test-resolve" });
+        expect(await store.resolveBlob("blake3-known-later")).not.toBeNull();
+        expect(await store.resolveBlob("legacy-sha256-key")).not.toBeNull();
+        expect(await store.resolveBlob("anything", "blake3-known-later")).not.toBeNull();
+        expect(await store.resolveBlob("nothing-matches")).toBeNull();
+    });
+    it("getBlobMetadata is an alias for resolveBlob", async () => {
+        const store = createBlobStore({ dbName: "store-test-metadata-alias" });
+        const record = await store.storeBlob(textBuffer("meta"), { filename: "m.txt", mime: "text/plain" });
+        expect(await store.getBlobMetadata(record.blob_id)).toEqual(record);
+    });
+});
+describe("getBlobObjectURL", () => {
+    it("returns and caches an object url for a stored blob", async () => {
+        const store = createBlobStore({ dbName: "store-test-url" });
+        const record = await store.storeBlob(textBuffer("url content"), {
+            filename: "u.txt",
+            mime: "text/plain",
+        });
+        const url1 = await store.getBlobObjectURL(record.blob_id);
+        const url2 = await store.getBlobObjectURL(record.blob_id);
+        expect(url1).toBe(url2);
+        expect(vi.mocked(URL.createObjectURL)).toHaveBeenCalledTimes(1);
+    });
+    it("returns null for a blob that doesn't exist", async () => {
+        const store = createBlobStore({ dbName: "store-test-url-missing" });
+        expect(await store.getBlobObjectURL("nope")).toBeNull();
+    });
+    it("clearBlobUrlCache revokes every cached url", async () => {
+        const store = createBlobStore({ dbName: "store-test-url-clear" });
+        const record = await store.storeBlob(textBuffer("clear me"), {
+            filename: "c.txt",
+            mime: "text/plain",
+        });
+        await store.getBlobObjectURL(record.blob_id);
+        store.clearBlobUrlCache();
+        expect(vi.mocked(URL.revokeObjectURL)).toHaveBeenCalledTimes(1);
+    });
+});
+describe("hasBlobBytes / checkBlobLocality", () => {
+    it("reports local for a record with bytes present", async () => {
+        const store = createBlobStore({ dbName: "store-test-locality-local" });
+        const record = await store.storeBlob(textBuffer("local content"), {
+            filename: "l.txt",
+            mime: "text/plain",
+        });
+        expect(await store.hasBlobBytes(record.blob_id)).toBe(true);
+        const info = await store.checkBlobLocality(record.blob_id);
+        expect(info.locality).toBe("local");
+        expect(info.metadata?.id).toBe(record.blob_id);
+    });
+    it("reports remote for a blobId with no record at all", async () => {
+        const store = createBlobStore({ dbName: "store-test-locality-remote" });
+        expect(await store.hasBlobBytes("nothing")).toBe(false);
+        expect((await store.checkBlobLocality("nothing")).locality).toBe("remote");
+    });
+    it("reports remote for a stranded record whose bytes are missing (not stuck local forever)", async () => {
+        const store = createBlobStore({ dbName: "store-test-locality-stranded" });
+        // simulate a record whose write silently failed to persist bytes:
+        // metadata exists, but no backend actually has the bytes.
+        await putRecord("store-test-locality-stranded", {
+            blob_id: "stranded-blake3",
+            blake3: "stranded-blake3",
+            filename: "stranded.txt",
+            mime: "text/plain",
+            size: 10,
+            blob_type: "original",
+            parent_blob_id: null,
+            created_at: 1,
+            storage_backend: "opfs",
+        });
+        expect(await store.hasBlobBytes("stranded-blake3")).toBe(false);
+        const info = await store.checkBlobLocality("stranded-blake3");
+        expect(info.locality).toBe("remote");
+    });
+    it("checkBlobLocality on an empty blobId is unknown, not remote", async () => {
+        const store = createBlobStore({ dbName: "store-test-locality-empty" });
+        expect((await store.checkBlobLocality("")).locality).toBe("unknown");
+    });
+});
+describe("deleteBlob / clearAll", () => {
+    it("removes both the record and the bytes", async () => {
+        const store = createBlobStore({ dbName: "store-test-delete" });
+        const record = await store.storeBlob(textBuffer("delete me"), {
+            filename: "d.txt",
+            mime: "text/plain",
+        });
+        await store.deleteBlob(record.blob_id);
+        expect(await store.getBlobRecord(record.blob_id)).toBeNull();
+        expect(await store.hasBlobBytes(record.blob_id)).toBe(false);
+    });
+    it("clearAll wipes every record and every backend's bytes", async () => {
+        const store = createBlobStore({ dbName: "store-test-clear-all" });
+        const a = await store.storeBlob(textBuffer("clear-all-a"), { filename: "a.txt", mime: "text/plain" });
+        const b = await store.storeBlob(textBuffer("clear-all-b"), { filename: "b.txt", mime: "text/plain" });
+        await store.clearAll();
+        expect(await store.getBlobRecord(a.blob_id)).toBeNull();
+        expect(await store.getBlobRecord(b.blob_id)).toBeNull();
+        expect(await store.hasBlobBytes(a.blob_id)).toBe(false);
+    });
+});

package/dist/blobs/types.d.ts

@@ -0,0 +1,55 @@
+/** original | thumbnail | waveform | preview - matches the rust schema's enum. */
+export type BlobType = "original" | "thumbnail" | "waveform" | "preview";
+/** which bytes backend a record's payload was written through. absent on
+ *  records written before this field existed - callers should treat a
+ *  missing value as "opfs" (the only backend that existed at the time). */
+export type BytesBackendName = "opfs" | "cache";
+export interface BlobRecord {
+    /** canonical id - the blake3 hex digest. */
+    blob_id: string;
+    /** blake3 hex digest (same value as blob_id for every record created by
+     *  this store; kept as its own field, and its own index, so a record
+     *  legacy-keyed by sha256 can still be found by blake3 once known). */
+    blake3: string;
+    /** legacy sha256 hex digest, kept for records/references that predate
+     *  blake3 becoming canonical. never computed for new streamed uploads. */
+    sha256?: string;
+    filename: string;
+    mime: string;
+    size: number;
+    blob_type: BlobType;
+    /** blake3 of a "parent" blob this one was derived from (e.g. a
+     *  thumbnail's parent is the original image). */
+    parent_blob_id?: string | null;
+    metadata?: Record<string, unknown>;
+    created_at: number;
+    storage_backend?: BytesBackendName;
+}
+/** everything needed to store a new blob, other than the bytes and the
+ *  fields this store computes/fills in itself (blob_id, blake3, sha256,
+ *  size, created_at, storage_backend). */
+export interface NewBlobMeta {
+    filename: string;
+    mime: string;
+    blob_type?: BlobType;
+    parent_blob_id?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface BlobLocalityMetadata {
+    id: string;
+    mime?: string;
+    filename?: string;
+    size?: number;
+    blake3?: string;
+}
+export interface BlobLocalityInfo {
+    /**
+     * "remote" covers both "no record at all" and "a record exists but its
+     * bytes are missing" - a stranded record (e.g. a write whose bytes
+     * backend silently failed) must not read as permanently local with no
+     * way to repair it.
+     */
+    locality: "local" | "remote" | "unknown";
+    metadata?: BlobLocalityMetadata;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/blobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/blobs/types.ts"],"names":[],"mappings":"AAQA,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEzE;;2EAE2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB;;2EAEuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,CAAC;IACpB;qDACiD;IACjD,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED;;0CAE0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC"}

package/dist/blobs/types.js

@@ -0,0 +1,8 @@
+// shared shapes for the blake3-canonical blob record store.
+//
+// core schema: blake3 primary key, sha256 legacy index, blob_type, parent
+// linkage. this browser version omits native-only fields (on-disk path,
+// external flag, soft-delete bookkeeping) and app-specific classification
+// fields (e.g. domain tags) - callers that want classification can use
+// the `metadata` field.
+export {};

package/dist/ensure/client.d.ts

@@ -0,0 +1,19 @@
+import type { BiStreamLike } from "../automerge/types.js";
+/** minimal interface for a node capable of opening bidirectional streams. */
+export interface EnsureCapableNode {
+    open_bi(peerAddr: string, alpn: string): Promise<BiStreamLike>;
+}
+/**
+ * sends an ensure-blob request to a peer and returns whether the peer
+ * reports the blob as available. throws on connection/protocol errors.
+ *
+ * @param node - the transport node (midden, tauri, or any node exposing `open_bi`)
+ * @param peerAddr - peer address (bare node id or full `EndpointAddr`)
+ * @param blake3Hash - blake3 hash of the blob to check for
+ * @param alpn - ALPN string to dial (defaults to `DEFAULT_ENSURE_ALPN`)
+ * @returns true if the peer has the blob, false otherwise
+ * @throws when the peer rejects the connection, the stream errors, or the
+ *         response cannot be parsed
+ */
+export declare function ensureBlobOverAlpn(node: EnsureCapableNode, peerAddr: string, blake3Hash: string, alpn?: string): Promise<boolean>;
+//# sourceMappingURL=client.d.ts.map

package/dist/ensure/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ensure/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAChE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAuElB"}

package/dist/ensure/client.js

@@ -0,0 +1,74 @@
+// client side of the ensure-blob protocol: dials a peer, sends a request,
+// reads the response.
+import { log } from "../utils/log.js";
+import { DEFAULT_ENSURE_ALPN } from "./types.js";
+const TAG = "ensure.client";
+/**
+ * sends an ensure-blob request to a peer and returns whether the peer
+ * reports the blob as available. throws on connection/protocol errors.
+ *
+ * @param node - the transport node (midden, tauri, or any node exposing `open_bi`)
+ * @param peerAddr - peer address (bare node id or full `EndpointAddr`)
+ * @param blake3Hash - blake3 hash of the blob to check for
+ * @param alpn - ALPN string to dial (defaults to `DEFAULT_ENSURE_ALPN`)
+ * @returns true if the peer has the blob, false otherwise
+ * @throws when the peer rejects the connection, the stream errors, or the
+ *         response cannot be parsed
+ */
+export async function ensureBlobOverAlpn(node, peerAddr, blake3Hash, alpn) {
+    const actualAlpn = alpn ?? DEFAULT_ENSURE_ALPN;
+    const peerShort = peerAddr.slice(0, 16);
+    log.debug(TAG, `dialing peer ${peerShort} on ALPN ${actualAlpn} for blake3=${blake3Hash.slice(0, 16)}`);
+    let stream;
+    try {
+        stream = await node.open_bi(peerAddr, actualAlpn);
+    }
+    catch (err) {
+        throw new Error(`failed to connect to peer ${peerShort}: ${err instanceof Error ? err.message : err}`);
+    }
+    const request = {
+        type: "ensure_blob_request",
+        id: 1,
+        blake3_hash: blake3Hash,
+    };
+    const requestBytes = new TextEncoder().encode(JSON.stringify(request));
+    try {
+        if (stream.write_raw_and_finish) {
+            await stream.write_raw_and_finish(requestBytes);
+        }
+        else {
+            log.warn(TAG, "stream does not support write_raw_and_finish, falling back to write_message");
+            await stream.write_message(requestBytes);
+            stream.close();
+        }
+    }
+    catch (err) {
+        throw new Error(`failed to write request to peer ${peerShort}: ${err instanceof Error ? err.message : err}`);
+    }
+    if (!stream.read_to_end) {
+        throw new Error("stream does not support read_to_end");
+    }
+    let responseBytes;
+    try {
+        responseBytes = await stream.read_to_end(64 * 1024);
+    }
+    catch (err) {
+        throw new Error(`failed to read response from peer ${peerShort}: ${err instanceof Error ? err.message : err}`);
+    }
+    let msg;
+    try {
+        msg = JSON.parse(new TextDecoder().decode(responseBytes));
+    }
+    catch (err) {
+        throw new Error(`failed to parse response from peer ${peerShort}: ${err instanceof Error ? err.message : err}`);
+    }
+    if (msg.type !== "ensure_blob_response") {
+        throw new Error(`unexpected response type from peer ${peerShort}: ${msg.type}`);
+    }
+    const response = msg;
+    if (response.error) {
+        log.debug(TAG, `peer ${peerShort} reported error: ${response.error}`);
+        return false;
+    }
+    return response.available;
+}

package/dist/ensure/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/ensure/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/ensure/client.test.ts"],"names":[],"mappings":""}