@freqhole/reliquary 0.0.0

package/dist/ensure/client.test.js

@@ -0,0 +1,133 @@
+// tests for the ensure-blob client
+import { describe, expect, it, vi } from "vitest";
+import { createMockBiStream } from "../testing/index.js";
+import { ensureBlobOverAlpn } from "./client.js";
+import { DEFAULT_ENSURE_ALPN } from "./types.js";
+describe("ensure/client", () => {
+    function encodeResponse(msg) {
+        return new TextEncoder().encode(JSON.stringify(msg));
+    }
+    function createMockNode() {
+        const stream = createMockBiStream("remote-peer", "freqhole/1");
+        return {
+            open_bi: vi.fn(async () => stream),
+        };
+    }
+    describe("ensureBlobOverAlpn", () => {
+        it("dials the peer with the default ALPN when none provided", async () => {
+            const node = createMockNode();
+            const peerAddr = "peer123";
+            const blake3Hash = "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262";
+            const response = {
+                type: "ensure_blob_response",
+                id: 1,
+                available: true,
+            };
+            const promise = ensureBlobOverAlpn(node, peerAddr, blake3Hash);
+            await new Promise((r) => setTimeout(r, 10));
+            const stream = (await node.open_bi("", ""));
+            stream.pushMessage(encodeResponse(response));
+            const result = await promise;
+            expect(node.open_bi).toHaveBeenCalledWith(peerAddr, DEFAULT_ENSURE_ALPN);
+            expect(result).toBe(true);
+        });
+        it("dials the peer with a custom ALPN when provided", async () => {
+            const node = createMockNode();
+            const peerAddr = "peer456";
+            const blake3Hash = "0000000000000000000000000000000000000000000000000000000000000001";
+            const customAlpn = "custom/1";
+            const response = {
+                type: "ensure_blob_response",
+                id: 1,
+                available: false,
+            };
+            const promise = ensureBlobOverAlpn(node, peerAddr, blake3Hash, customAlpn);
+            await new Promise((r) => setTimeout(r, 10));
+            const stream = (await node.open_bi("", ""));
+            stream.pushMessage(encodeResponse(response));
+            const result = await promise;
+            expect(node.open_bi).toHaveBeenCalledWith(peerAddr, customAlpn);
+            expect(result).toBe(false);
+        });
+        it("returns true when peer reports available=true", async () => {
+            const node = createMockNode();
+            const response = {
+                type: "ensure_blob_response",
+                id: 1,
+                available: true,
+            };
+            const promise = ensureBlobOverAlpn(node, "peer789", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262");
+            await new Promise((r) => setTimeout(r, 10));
+            const stream = (await node.open_bi("", ""));
+            stream.pushMessage(encodeResponse(response));
+            const result = await promise;
+            expect(result).toBe(true);
+        });
+        it("returns false when peer reports available=false", async () => {
+            const node = createMockNode();
+            const response = {
+                type: "ensure_blob_response",
+                id: 1,
+                available: false,
+            };
+            const promise = ensureBlobOverAlpn(node, "peer-unavail", "0000000000000000000000000000000000000000000000000000000000000002");
+            await new Promise((r) => setTimeout(r, 10));
+            const stream = (await node.open_bi("", ""));
+            stream.pushMessage(encodeResponse(response));
+            const result = await promise;
+            expect(result).toBe(false);
+        });
+        it("returns false when peer reports an error", async () => {
+            const node = createMockNode();
+            const response = {
+                type: "ensure_blob_response",
+                id: 1,
+                available: false,
+                error: "not authorized",
+            };
+            const promise = ensureBlobOverAlpn(node, "peer-denied", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262");
+            await new Promise((r) => setTimeout(r, 10));
+            const stream = (await node.open_bi("", ""));
+            stream.pushMessage(encodeResponse(response));
+            const result = await promise;
+            expect(result).toBe(false);
+        });
+        it("throws when connection fails", async () => {
+            const node = {
+                open_bi: vi.fn(async () => {
+                    throw new Error("connection refused");
+                }),
+            };
+            await expect(ensureBlobOverAlpn(node, "peer-unreachable", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262")).rejects.toThrow("failed to connect to peer");
+        });
+        it("throws when stream does not support read_to_end", async () => {
+            const stream = createMockBiStream("peer", "freqhole/1");
+            stream.read_to_end = undefined;
+            const node = {
+                open_bi: vi.fn(async () => stream),
+            };
+            await expect(ensureBlobOverAlpn(node, "peer-noread", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262")).rejects.toThrow("stream does not support read_to_end");
+        });
+        it("throws when response is malformed JSON", async () => {
+            const stream = createMockBiStream("peer-badresp", "freqhole/1");
+            const node = {
+                open_bi: vi.fn(async () => stream),
+            };
+            const promise = ensureBlobOverAlpn(node, "peer-badresp", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262");
+            await new Promise((r) => setTimeout(r, 10));
+            stream.pushMessage(new TextEncoder().encode("not json {{{"));
+            await expect(promise).rejects.toThrow("failed to parse response");
+        });
+        it("throws when response has unexpected type", async () => {
+            const stream = createMockBiStream("peer-wrongtype", "freqhole/1");
+            const node = {
+                open_bi: vi.fn(async () => stream),
+            };
+            const promise = ensureBlobOverAlpn(node, "peer-wrongtype", "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262");
+            await new Promise((r) => setTimeout(r, 10));
+            const wrongType = { type: "ensure_blob_request", id: 99, blake3_hash: "test" };
+            stream.pushMessage(new TextEncoder().encode(JSON.stringify(wrongType)));
+            await expect(promise).rejects.toThrow("unexpected response type");
+        });
+    });
+});

package/dist/ensure/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_ENSURE_ALPN, type PeerMessage, type EnsureBlobRequest, type EnsureBlobResponse, } from "./types.js";
+export { createEnsureBlobHandler, type EnsureBlobHandlerDeps } from "./responder.js";
+export { ensureBlobOverAlpn, type EnsureCapableNode } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ensure/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAErF,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/ensure/index.js

@@ -0,0 +1,4 @@
+// ensure-blob protocol: shared p2p blob availability check + staging.
+export { DEFAULT_ENSURE_ALPN, } from "./types.js";
+export { createEnsureBlobHandler } from "./responder.js";
+export { ensureBlobOverAlpn } from "./client.js";

package/dist/ensure/responder.d.ts

@@ -0,0 +1,20 @@
+import type { BiStreamLike } from "../automerge/types.js";
+/** dependencies for the ensure-blob handler, provided by the app. */
+export interface EnsureBlobHandlerDeps {
+    /** check if a blob with the given blake3 hash is available. */
+    hasBlob: (blake3Hash: string) => Promise<boolean>;
+    /** optional per-blob access control. when provided, called before
+     *  `hasBlob` to decide if this peer may ask for this specific blob.
+     *  defaults to always allowing. */
+    allow?: (peerId: string, blake3Hash: string) => Promise<boolean>;
+}
+/**
+ * creates an ALPN handler for the ensure-blob protocol. the returned
+ * function accepts a bidirectional stream, reads an ensure-blob request,
+ * optionally gates it via `deps.allow`, checks `deps.hasBlob`, and writes
+ * back a response.
+ *
+ * suitable for passing directly to `IrohNetworkAdapter.registerAlpnHandler(alpn, handler)`.
+ */
+export declare function createEnsureBlobHandler(deps: EnsureBlobHandlerDeps): (stream: BiStreamLike) => void;
+//# sourceMappingURL=responder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"responder.d.ts","sourceRoot":"","sources":["../../src/ensure/responder.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD;;uCAEmC;IACnC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,GAC1B,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAYhC"}

package/dist/ensure/responder.js

@@ -0,0 +1,100 @@
+// responder side of the ensure-blob protocol: receives requests, gates
+// access, checks if blobs exist, and sends responses.
+import { log } from "../utils/log.js";
+const TAG = "ensure.responder";
+/**
+ * creates an ALPN handler for the ensure-blob protocol. the returned
+ * function accepts a bidirectional stream, reads an ensure-blob request,
+ * optionally gates it via `deps.allow`, checks `deps.hasBlob`, and writes
+ * back a response.
+ *
+ * suitable for passing directly to `IrohNetworkAdapter.registerAlpnHandler(alpn, handler)`.
+ */
+export function createEnsureBlobHandler(deps) {
+    return (stream) => {
+        handleStream(stream, deps).catch((err) => {
+            const peerId = stream.peer_node_id();
+            const peerShort = peerId.slice(0, 16);
+            log.warn(TAG, `stream error from peer ${peerShort}:`, err instanceof Error ? err.message : err);
+        });
+    };
+}
+async function handleStream(stream, deps) {
+    const peerId = stream.peer_node_id();
+    const peerShort = peerId.slice(0, 16);
+    if (!stream.read_to_end) {
+        log.warn(TAG, `stream from peer ${peerShort} does not support read_to_end`);
+        stream.close();
+        return;
+    }
+    const msgBytes = await stream.read_to_end(64 * 1024);
+    let msg;
+    try {
+        msg = JSON.parse(new TextDecoder().decode(msgBytes));
+    }
+    catch (err) {
+        log.warn(TAG, `failed to parse request from peer ${peerShort}:`, err instanceof Error ? err.message : err);
+        stream.close();
+        return;
+    }
+    if (msg.type !== "ensure_blob_request") {
+        log.debug(TAG, `ignoring non-request message from peer ${peerShort}: ${msg.type}`);
+        stream.close();
+        return;
+    }
+    const request = msg;
+    const response = await handleEnsureBlobRequest(request, peerId, deps);
+    await sendResponse(stream, response);
+}
+async function handleEnsureBlobRequest(request, peerId, deps) {
+    const { id, blake3_hash } = request;
+    if (blake3_hash.length !== 64) {
+        return {
+            type: "ensure_blob_response",
+            id,
+            available: false,
+            error: `expected 64-char blake3 hex, got ${blake3_hash.length}`,
+        };
+    }
+    if (deps.allow) {
+        const allowed = await deps.allow(peerId, blake3_hash);
+        if (!allowed) {
+            log.info(TAG, `denied peer ${peerId.slice(0, 16)} access to blob ${blake3_hash.slice(0, 16)}`);
+            return {
+                type: "ensure_blob_response",
+                id,
+                available: false,
+                error: "not authorized",
+            };
+        }
+    }
+    let available;
+    try {
+        available = await deps.hasBlob(blake3_hash);
+    }
+    catch (err) {
+        log.warn(TAG, `hasBlob check failed for blake3=${blake3_hash.slice(0, 16)}:`, err instanceof Error ? err.message : err);
+        return {
+            type: "ensure_blob_response",
+            id,
+            available: false,
+            error: "hasBlob check failed",
+        };
+    }
+    return {
+        type: "ensure_blob_response",
+        id,
+        available,
+    };
+}
+async function sendResponse(stream, response) {
+    const bytes = new TextEncoder().encode(JSON.stringify(response));
+    if (stream.write_raw_and_finish) {
+        await stream.write_raw_and_finish(bytes);
+    }
+    else {
+        log.warn(TAG, "stream does not support write_raw_and_finish, falling back to write_message");
+        await stream.write_message(bytes);
+        stream.close();
+    }
+}

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

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

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

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

package/dist/ensure/responder.test.js

@@ -0,0 +1,191 @@
+// tests for the ensure-blob responder (server side)
+import { describe, expect, it, vi } from "vitest";
+import { createMockBiStream } from "../testing/index.js";
+import { createEnsureBlobHandler } from "./responder.js";
+describe("ensure/responder", () => {
+    function createMockDeps(overrides) {
+        return {
+            hasBlob: vi.fn(async () => true),
+            ...overrides,
+        };
+    }
+    function encodeRequest(msg) {
+        return new TextEncoder().encode(JSON.stringify(msg));
+    }
+    function decodeResponse(bytes) {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    describe("createEnsureBlobHandler", () => {
+        it("returns a function", () => {
+            const deps = createMockDeps();
+            const handler = createEnsureBlobHandler(deps);
+            expect(typeof handler).toBe("function");
+        });
+        it("handles a valid request when blob is available", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer123", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 1,
+                blake3_hash: "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).toHaveBeenCalledWith(request.blake3_hash);
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(1);
+            expect(response.available).toBe(true);
+            expect(response.error).toBeUndefined();
+        });
+        it("handles a valid request when blob is not available", async () => {
+            const hasBlob = vi.fn(async () => false);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer456", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 2,
+                blake3_hash: "0000000000000000000000000000000000000000000000000000000000000001",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).toHaveBeenCalledWith(request.blake3_hash);
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(2);
+            expect(response.available).toBe(false);
+            expect(response.error).toBeUndefined();
+        });
+        it("rejects requests with invalid blake3 hash length", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer789", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 3,
+                blake3_hash: "tooshort",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).not.toHaveBeenCalled();
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(3);
+            expect(response.available).toBe(false);
+            expect(response.error).toContain("expected 64-char blake3 hex");
+        });
+        it("gates requests via allow callback when provided", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const allow = vi.fn(async () => false);
+            const deps = createMockDeps({ hasBlob, allow });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-denied", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 4,
+                blake3_hash: "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(allow).toHaveBeenCalledWith("peer-denied", request.blake3_hash);
+            expect(hasBlob).not.toHaveBeenCalled();
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(4);
+            expect(response.available).toBe(false);
+            expect(response.error).toBe("not authorized");
+        });
+        it("allows requests when allow callback returns true", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const allow = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob, allow });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-allowed", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 5,
+                blake3_hash: "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(allow).toHaveBeenCalledWith("peer-allowed", request.blake3_hash);
+            expect(hasBlob).toHaveBeenCalledWith(request.blake3_hash);
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(5);
+            expect(response.available).toBe(true);
+        });
+        it("handles hasBlob throwing an error", async () => {
+            const hasBlob = vi.fn(async () => {
+                throw new Error("database connection lost");
+            });
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-error", "freqhole/1");
+            const request = {
+                type: "ensure_blob_request",
+                id: 6,
+                blake3_hash: "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+            };
+            handler(stream);
+            stream.pushMessage(encodeRequest(request));
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).toHaveBeenCalled();
+            expect(stream._written.length).toBe(1);
+            const response = decodeResponse(stream._written[0]);
+            expect(response.type).toBe("ensure_blob_response");
+            expect(response.id).toBe(6);
+            expect(response.available).toBe(false);
+            expect(response.error).toBe("hasBlob check failed");
+        });
+        it("handles malformed JSON gracefully", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-badmsg", "freqhole/1");
+            const malformed = new TextEncoder().encode("not json {{{");
+            handler(stream);
+            stream.pushMessage(malformed);
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).not.toHaveBeenCalled();
+            expect(stream._closed).toBe(true);
+        });
+        it("ignores non-request message types", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-wrongtype", "freqhole/1");
+            const wrongType = new TextEncoder().encode(JSON.stringify({ type: "ensure_blob_response", id: 99, available: false }));
+            handler(stream);
+            stream.pushMessage(wrongType);
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).not.toHaveBeenCalled();
+            expect(stream._closed).toBe(true);
+        });
+        it("handles streams without read_to_end support gracefully", async () => {
+            const hasBlob = vi.fn(async () => true);
+            const deps = createMockDeps({ hasBlob });
+            const handler = createEnsureBlobHandler(deps);
+            const stream = createMockBiStream("peer-noread", "freqhole/1");
+            stream.read_to_end = undefined;
+            handler(stream);
+            await new Promise((r) => setTimeout(r, 50));
+            expect(hasBlob).not.toHaveBeenCalled();
+            expect(stream._closed).toBe(true);
+        });
+    });
+});

package/dist/ensure/types.d.ts

@@ -0,0 +1,19 @@
+/** default ALPN for ensure-blob protocol requests, shared across all apps. */
+export declare const DEFAULT_ENSURE_ALPN = "freqhole/1";
+/** discriminated union of all ensure-protocol messages. */
+export type PeerMessage = EnsureBlobRequest | EnsureBlobResponse;
+/** request that a peer stage a blob (by blake3 hash) in its iroh-blobs
+ *  store for verified transfer. */
+export interface EnsureBlobRequest {
+    type: "ensure_blob_request";
+    id: number;
+    blake3_hash: string;
+}
+/** response to an `EnsureBlobRequest`. */
+export interface EnsureBlobResponse {
+    type: "ensure_blob_response";
+    id: number;
+    available: boolean;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ensure/types.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEjE;mCACmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/ensure/types.js

@@ -0,0 +1,4 @@
+// message types for the ensure-blob protocol. matches the rust `reliquary::ensure::PeerMessage`
+// enum's wire format exactly: `#[serde(tag = "type", rename_all = "snake_case")]`.
+/** default ALPN for ensure-blob protocol requests, shared across all apps. */
+export const DEFAULT_ENSURE_ALPN = "freqhole/1";

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

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

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

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

package/dist/ensure/types.test.js

@@ -0,0 +1,81 @@
+// tests for the ensure-blob protocol message types
+import { describe, expect, it } from "vitest";
+import { DEFAULT_ENSURE_ALPN } from "./types.js";
+describe("ensure/types", () => {
+    describe("DEFAULT_ENSURE_ALPN", () => {
+        it("exports the correct ALPN string", () => {
+            expect(DEFAULT_ENSURE_ALPN).toBe("freqhole/1");
+        });
+    });
+    describe("EnsureBlobRequest", () => {
+        it("serializes with snake_case type tag", () => {
+            const msg = {
+                type: "ensure_blob_request",
+                id: 42,
+                blake3_hash: "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+            };
+            const json = JSON.stringify(msg);
+            expect(json).toContain("ensure_blob_request");
+            expect(json).toContain("blake3_hash");
+        });
+        it("roundtrips through JSON", () => {
+            const original = {
+                type: "ensure_blob_request",
+                id: 7,
+                blake3_hash: "0000000000000000000000000000000000000000000000000000000000000001",
+            };
+            const json = JSON.stringify(original);
+            const parsed = JSON.parse(json);
+            expect(parsed.type).toBe("ensure_blob_request");
+            expect(parsed.id).toBe(7);
+            expect(parsed.blake3_hash).toBe("0000000000000000000000000000000000000000000000000000000000000001");
+        });
+    });
+    describe("EnsureBlobResponse", () => {
+        it("serializes with snake_case type tag", () => {
+            const msg = {
+                type: "ensure_blob_response",
+                id: 42,
+                available: true,
+            };
+            const json = JSON.stringify(msg);
+            expect(json).toContain("ensure_blob_response");
+        });
+        it("roundtrips through JSON when available=true", () => {
+            const original = {
+                type: "ensure_blob_response",
+                id: 10,
+                available: true,
+            };
+            const json = JSON.stringify(original);
+            const parsed = JSON.parse(json);
+            expect(parsed.type).toBe("ensure_blob_response");
+            expect(parsed.id).toBe(10);
+            expect(parsed.available).toBe(true);
+            expect(parsed.error).toBeUndefined();
+        });
+        it("roundtrips through JSON when available=false with error", () => {
+            const original = {
+                type: "ensure_blob_response",
+                id: 20,
+                available: false,
+                error: "not authorized",
+            };
+            const json = JSON.stringify(original);
+            const parsed = JSON.parse(json);
+            expect(parsed.type).toBe("ensure_blob_response");
+            expect(parsed.id).toBe(20);
+            expect(parsed.available).toBe(false);
+            expect(parsed.error).toBe("not authorized");
+        });
+        it("omits error field when undefined", () => {
+            const msg = {
+                type: "ensure_blob_response",
+                id: 5,
+                available: true,
+            };
+            const json = JSON.stringify(msg);
+            expect(json).not.toContain("error");
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare const RELIQUARY_VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+/// reliquary: media blob storage library for freqhole apps.
+/// currently exports core types and utilities; see repo README for full API.
+export const RELIQUARY_VERSION = "0.1.0";

package/dist/index.test.d.ts

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

package/dist/index.test.d.ts.map

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

package/dist/index.test.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+import { RELIQUARY_VERSION } from "./index.js";
+describe("reliquary package", () => {
+    it("exports version", () => {
+        expect(RELIQUARY_VERSION).toBe("0.1.0");
+    });
+});

package/dist/solid/blob-url.d.ts

@@ -0,0 +1,10 @@
+import { type Resource } from "solid-js";
+/**
+ * fetches a blob via `getBlob` and exposes its object url as a solid
+ * resource. `null` while loading, on a null blob, or after an error.
+ * every previous url is revoked as soon as it's superseded (by a refetch)
+ * or the resource is disposed - a caller never needs to manage
+ * `URL.revokeObjectURL` itself.
+ */
+export declare function createBlobUrl(getBlob: () => Promise<Blob | null>): Resource<string | null>;
+//# sourceMappingURL=blob-url.d.ts.map

package/dist/solid/blob-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-url.d.ts","sourceRoot":"","sources":["../../src/solid/blob-url.ts"],"names":[],"mappings":"AASA,OAAO,EAA2C,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAElF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAkB1F"}