@query-farm/vgi-rpc-iroh-browser 0.24.1

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type CreateIrohOptions } from "./transport.js";
+export * from "./transport.js";
+/** Initialize the packaged WebAssembly module. Calling this more than once is safe. */
+export declare function initializeIrohWasm(): Promise<unknown>;
+/** Create a browser Iroh endpoint backed by the packaged WebAssembly module. */
+export declare function createIrohNode(options?: CreateIrohOptions): Promise<import("./transport.js").IrohNode>;

package/dist/index.js

@@ -0,0 +1,15 @@
+import initWasm, { createIrohNode as createWasmIrohNode, } from "./wasm/vgi_rpc_iroh_browser.js";
+import { createIrohNode as createWrappedIrohNode, } from "./transport.js";
+export * from "./transport.js";
+let initialization;
+/** Initialize the packaged WebAssembly module. Calling this more than once is safe. */
+export function initializeIrohWasm() {
+    if (!initialization)
+        initialization = initWasm();
+    return initialization;
+}
+/** Create a browser Iroh endpoint backed by the packaged WebAssembly module. */
+export async function createIrohNode(options = {}) {
+    await initializeIrohWasm();
+    return createWrappedIrohNode((transportOptions) => createWasmIrohNode(transportOptions), options);
+}

package/dist/transport.d.ts

@@ -0,0 +1,88 @@
+/** Browser-facing WHATWG stream wrapper for the wasm-bindgen transport. */
+export type HeaderPair = readonly [name: string, value: string];
+export type IrohProtocol = "vgi-rpc/arrow-mux/1" | "iroh-http/2";
+export interface WasmVgiStream {
+    write(chunk: Uint8Array): Promise<void>;
+    read(maxBytes: number): Promise<Uint8Array | undefined>;
+    closeWrite(): Promise<void>;
+    abort(): void;
+}
+export interface WasmHttpResponse {
+    readonly status: number;
+    readonly headers: HeaderPair[];
+    read(): Promise<Uint8Array | undefined>;
+    cancel(): void;
+}
+export interface WasmIrohNode {
+    readonly endpointId: string;
+    openVgiStream(endpointId: string): Promise<WasmVgiStream>;
+    fetchHttpi(endpointId: string, method: string, path: string, headers: HeaderPair[], body: Uint8Array): Promise<WasmHttpResponse>;
+    close(): Promise<void>;
+}
+export type TargetResolver = (target: string, protocol: IrohProtocol) => string | Promise<string>;
+export interface VgiDuplexStream {
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly writable: WritableStream<Uint8Array>;
+    abort(reason?: unknown): void;
+}
+export interface HttpiResponse {
+    readonly status: number;
+    /** Ordered fields; duplicate names, including Set-Cookie, are retained. */
+    readonly headers: HeaderPair[];
+    /** Raw HTTP representation bytes. Content decoding is the VGI client's job. */
+    readonly body: ReadableStream<Uint8Array>;
+    readonly bodyEncoding: "raw";
+}
+export type HttpiTransportStage = "parse" | "resolve" | "connect" | "request" | "response_head" | "response_body";
+export type HttpiTerminalCategory = "invalid_request" | "unauthorized_target" | "unavailable" | "timeout" | "cancelled" | "protocol" | "transport" | "internal";
+export type HttpiDispatchCertainty = "not_dispatched" | "dispatched" | "ambiguous";
+/** Stable transport evidence consumed by the SAB adapter; details stay sanitized. */
+export declare class HttpiTransportError extends Error {
+    readonly stage: HttpiTransportStage;
+    readonly category: HttpiTerminalCategory;
+    readonly dispatchCertainty: HttpiDispatchCertainty;
+    constructor(stage: HttpiTransportStage, category: HttpiTerminalCategory, dispatchCertainty: HttpiDispatchCertainty, cause: unknown);
+}
+export interface OpenOptions {
+    signal?: AbortSignal;
+    readChunkBytes?: number;
+}
+export interface CreateIrohOptions {
+    /** Iroh 64-hex or z-base-32 secret key; omit for an ephemeral identity. */
+    secretKey?: string;
+    /** Replace the default n0 relay set. The array must not be empty. */
+    relayUrls?: string[];
+    /** Disable relays. Mutually exclusive with relayUrls. */
+    noRelay?: boolean;
+    /** Optional application-owned alias resolver and authorization boundary. */
+    resolveTarget?: TargetResolver;
+    /** Hard cap on wasm connect/request futures, including abandoned late settlers. Default: 16. */
+    maxPendingOperations?: number;
+}
+export interface IrohNodeOptions {
+    maxPendingOperations?: number;
+}
+export type WasmIrohNodeFactory = (options?: Omit<CreateIrohOptions, "resolveTarget" | "maxPendingOperations">) => Promise<WasmIrohNode>;
+export declare function createIrohNode(wasmFactory: WasmIrohNodeFactory, options?: CreateIrohOptions): Promise<IrohNode>;
+/**
+ * One application-owned Iroh identity.
+ *
+ * Share one instance per DuckDB engine. `resolveTarget` is optional: literal
+ * 64-hex EndpointIds work by default, while applications that need aliases or
+ * authorization can resolve/reject them without teaching VGI a policy system.
+ */
+export declare class IrohNode {
+    private readonly wasm;
+    private readonly resolveTarget?;
+    private pendingOperations;
+    private readonly maxPendingOperations;
+    constructor(wasm: WasmIrohNode, resolveTarget?: TargetResolver | undefined, options?: IrohNodeOptions);
+    private admitted;
+    get endpointId(): string;
+    private resolve;
+    openVgiStream(target: string, options?: OpenOptions): Promise<VgiDuplexStream>;
+    fetchHttpi(target: string, method: string, path: string, headers: HeaderPair[], body: Uint8Array, signal?: AbortSignal, 
+    /** Internal adapter hook: settles with the actual wasm request, not caller abort. */
+    onUnderlyingSettled?: (settled: Promise<void>) => void): Promise<HttpiResponse>;
+    close(): Promise<void>;
+}

package/dist/transport.js

@@ -0,0 +1,261 @@
+/** Browser-facing WHATWG stream wrapper for the wasm-bindgen transport. */
+/** Stable transport evidence consumed by the SAB adapter; details stay sanitized. */
+export class HttpiTransportError extends Error {
+    stage;
+    category;
+    dispatchCertainty;
+    constructor(stage, category, dispatchCertainty, cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = "HttpiTransportError";
+        this.stage = stage;
+        this.category = category;
+        this.dispatchCertainty = dispatchCertainty;
+    }
+}
+export async function createIrohNode(wasmFactory, options = {}) {
+    const { resolveTarget, maxPendingOperations, ...transportOptions } = options;
+    return new IrohNode(await wasmFactory(transportOptions), resolveTarget, {
+        maxPendingOperations,
+    });
+}
+/**
+ * One application-owned Iroh identity.
+ *
+ * Share one instance per DuckDB engine. `resolveTarget` is optional: literal
+ * 64-hex EndpointIds work by default, while applications that need aliases or
+ * authorization can resolve/reject them without teaching VGI a policy system.
+ */
+export class IrohNode {
+    wasm;
+    resolveTarget;
+    pendingOperations = 0;
+    maxPendingOperations;
+    constructor(wasm, resolveTarget, options = {}) {
+        this.wasm = wasm;
+        this.resolveTarget = resolveTarget;
+        this.maxPendingOperations = options.maxPendingOperations ?? 16;
+        if (!Number.isSafeInteger(this.maxPendingOperations) ||
+            this.maxPendingOperations <= 0) {
+            throw new RangeError("maxPendingOperations must be a positive safe integer");
+        }
+    }
+    admitted(start, signal, disposeLate, onUnderlyingSettled) {
+        if (this.pendingOperations >= this.maxPendingOperations) {
+            return Promise.reject(new HttpiTransportError("connect", "unavailable", "not_dispatched", new Error("browser Iroh pending-operation admission limit reached")));
+        }
+        this.pendingOperations++;
+        let underlying;
+        try {
+            underlying = start();
+        }
+        catch (error) {
+            this.pendingOperations--;
+            return Promise.reject(error);
+        }
+        // Admission remains charged after the caller aborts. Only the actual wasm
+        // future settling releases it, which hard-bounds abandoned connects.
+        const settled = underlying.then(() => {
+            this.pendingOperations--;
+        }, () => {
+            this.pendingOperations--;
+        });
+        onUnderlyingSettled?.(settled);
+        return abortable(underlying, signal, disposeLate);
+    }
+    get endpointId() {
+        return this.wasm.endpointId;
+    }
+    async resolve(target, protocol) {
+        return this.resolveTarget ? this.resolveTarget(target, protocol) : target;
+    }
+    async openVgiStream(target, options = {}) {
+        throwIfAborted(options.signal);
+        const endpointId = await abortable(Promise.resolve(this.resolve(target, "vgi-rpc/arrow-mux/1")), options.signal);
+        throwIfAborted(options.signal);
+        const stream = await this.admitted(() => this.wasm.openVgiStream(endpointId), options.signal, (lateStream) => lateStream.abort());
+        const chunkBytes = options.readChunkBytes ?? 64 * 1024;
+        if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
+            stream.abort();
+            throw new RangeError("readChunkBytes must be a positive safe integer");
+        }
+        let aborted = false;
+        const abortStream = () => {
+            if (!aborted) {
+                aborted = true;
+                stream.abort();
+            }
+        };
+        const onSignalAbort = () => abortStream();
+        options.signal?.addEventListener("abort", onSignalAbort, { once: true });
+        const readable = new ReadableStream({
+            async pull(controller) {
+                try {
+                    throwIfAborted(options.signal);
+                    const chunk = await stream.read(chunkBytes);
+                    if (chunk === undefined) {
+                        options.signal?.removeEventListener("abort", onSignalAbort);
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(chunk);
+                    }
+                }
+                catch (error) {
+                    abortStream();
+                    controller.error(error);
+                }
+            },
+            cancel() {
+                abortStream();
+            },
+        });
+        const writable = new WritableStream({
+            async write(chunk) {
+                throwIfAborted(options.signal);
+                await stream.write(chunk);
+            },
+            async close() {
+                await stream.closeWrite();
+            },
+            abort() {
+                abortStream();
+            },
+        });
+        return { readable, writable, abort: abortStream };
+    }
+    async fetchHttpi(target, method, path, headers, body, signal, 
+    /** Internal adapter hook: settles with the actual wasm request, not caller abort. */
+    onUnderlyingSettled) {
+        try {
+            throwIfAborted(signal);
+        }
+        catch (error) {
+            throw new HttpiTransportError("resolve", "cancelled", "not_dispatched", error);
+        }
+        let endpointId;
+        try {
+            endpointId = await abortable(Promise.resolve(this.resolve(target, "iroh-http/2")), signal);
+            throwIfAborted(signal);
+        }
+        catch (error) {
+            throw new HttpiTransportError("resolve", signal?.aborted ? "cancelled" : "unauthorized_target", "not_dispatched", error);
+        }
+        let response;
+        try {
+            response = await this.admitted(() => this.wasm.fetchHttpi(endpointId, method, path, headers, body), signal, (lateResponse) => lateResponse.cancel(), onUnderlyingSettled);
+        }
+        catch (error) {
+            if (signal?.aborted) {
+                throw new HttpiTransportError("request", "cancelled", "ambiguous", error);
+            }
+            if (error instanceof HttpiTransportError)
+                throw error;
+            const evidence = readHttpiEvidence(error);
+            throw new HttpiTransportError(evidence?.stage ?? "request", evidence?.category ?? "transport", evidence?.dispatchCertainty ?? "ambiguous", error);
+        }
+        const cancel = () => response.cancel();
+        signal?.addEventListener("abort", cancel, { once: true });
+        return {
+            status: response.status,
+            headers: response.headers,
+            bodyEncoding: "raw",
+            body: new ReadableStream({
+                async pull(controller) {
+                    try {
+                        throwIfAborted(signal);
+                        const chunk = await response.read();
+                        if (chunk === undefined) {
+                            signal?.removeEventListener("abort", cancel);
+                            controller.close();
+                        }
+                        else {
+                            controller.enqueue(chunk);
+                        }
+                    }
+                    catch (error) {
+                        response.cancel();
+                        controller.error(error);
+                    }
+                },
+                cancel,
+            }),
+        };
+    }
+    close() {
+        return this.wasm.close();
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw (signal.reason ??
+            new DOMException("The operation was aborted", "AbortError"));
+    }
+}
+async function abortable(promise, signal, disposeLate) {
+    throwIfAborted(signal);
+    if (!signal)
+        return promise;
+    let settled = false;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(signal.reason ??
+                new DOMException("The operation was aborted", "AbortError"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            if (settled) {
+                disposeLate?.(value);
+                return;
+            }
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+    });
+}
+function readHttpiEvidence(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const value = error;
+    const stages = [
+        "parse",
+        "resolve",
+        "connect",
+        "request",
+        "response_head",
+        "response_body",
+    ];
+    const categories = [
+        "invalid_request",
+        "unauthorized_target",
+        "unavailable",
+        "timeout",
+        "cancelled",
+        "protocol",
+        "transport",
+        "internal",
+    ];
+    const certainties = [
+        "not_dispatched",
+        "dispatched",
+        "ambiguous",
+    ];
+    if (!stages.includes(value.vgiStage) ||
+        !categories.includes(value.vgiCategory) ||
+        !certainties.includes(value.vgiDispatchCertainty))
+        return undefined;
+    return {
+        stage: value.vgiStage,
+        category: value.vgiCategory,
+        dispatchCertainty: value.vgiDispatchCertainty,
+    };
+}

package/dist/wasm/vgi_rpc_iroh_browser.d.ts

@@ -0,0 +1,201 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+
+export type ReadableStreamType = "bytes";
+
+/**
+ * Streaming HTTP response preserving ordered duplicate headers.
+ */
+export class BrowserHttpResponse {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    /**
+     * Read the next raw HTTP body data frame; trailers are currently skipped.
+     * No browser content decoding is performed.
+     */
+    read(): Promise<Uint8Array | undefined>;
+    readonly headers: Array<any>;
+    readonly status: number;
+}
+
+/**
+ * One browser Iroh identity and its protocol-specific connection pools.
+ *
+ * Construct this with [`create_iroh_node`].  One instance should be shared by
+ * an entire DuckDB engine so HTTP and raw VGI calls present the same endpoint
+ * identity to workers.
+ */
+export class BrowserIrohNode {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Close all pooled connections and release the browser endpoint.
+     */
+    close(): Promise<void>;
+    /**
+     * Send one HTTP/1.1 request over a pooled `iroh-http/2` connection.
+     *
+     * `headers` is an array of `[name, value]` pairs so ordering and duplicate
+     * fields are preserved.  The response body remains streaming through
+     * [`BrowserHttpResponse::read`].
+     */
+    fetchHttpi(remote: string, method: string, path: string, headers: Array<any>, body: Uint8Array): Promise<BrowserHttpResponse>;
+    /**
+     * Open one independent VGI byte stream on the pooled mux connection.
+     */
+    openVgiStream(remote: string): Promise<BrowserVgiStream>;
+    /**
+     * Lowercase 64-hex public endpoint key used by VGI's identity contract.
+     */
+    readonly endpointId: string;
+}
+
+/**
+ * Raw bidirectional VGI stream.  The accompanying TypeScript wrapper exposes
+ * these methods as WHATWG `ReadableStream` and `WritableStream` objects.
+ */
+export class BrowserVgiStream {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Reset both stream directions.  This never closes sibling mux streams.
+     */
+    abort(): void;
+    /**
+     * Finish the request direction while retaining the response direction.
+     */
+    closeWrite(): Promise<void>;
+    /**
+     * Read up to `max_bytes`; returns `undefined` after a clean peer FIN.
+     */
+    read(max_bytes: number): Promise<Uint8Array | undefined>;
+    /**
+     * Write the complete chunk, respecting QUIC backpressure.
+     */
+    write(chunk: Uint8Array): Promise<void>;
+}
+
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+
+/**
+ * Create a relay-capable browser endpoint.
+ *
+ * `options.secretKey` accepts Iroh's 64-hex or z-base-32 secret-key encoding.
+ * When omitted, a fresh ephemeral identity is generated.  Persist the secret
+ * only when stable browser identity is an explicit application requirement.
+ * `options.relayUrls`, when supplied, replaces the n0 relay set.
+ * `options.noRelay=true` disables relays entirely. It is mutually exclusive
+ * with `relayUrls` and is mainly useful for controlled direct-address tests.
+ */
+export function createIrohNode(options?: any | null): Promise<BrowserIrohNode>;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_browserhttpresponse_free: (a: number, b: number) => void;
+    readonly __wbg_browserirohnode_free: (a: number, b: number) => void;
+    readonly __wbg_browservgistream_free: (a: number, b: number) => void;
+    readonly browserhttpresponse_cancel: (a: number) => void;
+    readonly browserhttpresponse_headers: (a: number) => any;
+    readonly browserhttpresponse_read: (a: number) => any;
+    readonly browserhttpresponse_status: (a: number) => number;
+    readonly browserirohnode_close: (a: number) => any;
+    readonly browserirohnode_endpointId: (a: number) => [number, number];
+    readonly browserirohnode_fetchHttpi: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: any, i: any) => any;
+    readonly browserirohnode_openVgiStream: (a: number, b: number, c: number) => any;
+    readonly browservgistream_abort: (a: number) => void;
+    readonly browservgistream_closeWrite: (a: number) => any;
+    readonly browservgistream_read: (a: number, b: number) => any;
+    readonly browservgistream_write: (a: number, b: any) => any;
+    readonly createIrohNode: (a: number) => any;
+    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
+    readonly intounderlyingsink_abort: (a: number, b: any) => any;
+    readonly intounderlyingsink_close: (a: number) => any;
+    readonly intounderlyingsink_write: (a: number, b: any) => any;
+    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
+    readonly intounderlyingsource_cancel: (a: number) => void;
+    readonly intounderlyingsource_pull: (a: number, b: any) => any;
+    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
+    readonly intounderlyingbytesource_cancel: (a: number) => void;
+    readonly intounderlyingbytesource_pull: (a: number, b: any) => any;
+    readonly intounderlyingbytesource_start: (a: number, b: any) => void;
+    readonly intounderlyingbytesource_type: (a: number) => number;
+    readonly ring_core_0_17_14__bn_mul_mont: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke___wasm_bindgen_91244e9a1334c25a___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_91244e9a1334c25a___JsError___true_: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke___js_sys_a199f889b0d5f53b___Function_fn_wasm_bindgen_91244e9a1334c25a___JsValue_____wasm_bindgen_91244e9a1334c25a___sys__Undefined___js_sys_a199f889b0d5f53b___Function_fn_wasm_bindgen_91244e9a1334c25a___JsValue_____wasm_bindgen_91244e9a1334c25a___sys__Undefined_______true_: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke___wasm_bindgen_91244e9a1334c25a___JsValue______true_: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke___web_sys_65b30f6c5de6bd9e___features__gen_CloseEvent__CloseEvent______true_: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke___web_sys_65b30f6c5de6bd9e___features__gen_MessageEvent__MessageEvent______true_: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke_______true_: (a: number, b: number) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke_______true__1_: (a: number, b: number) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke_______true__2_: (a: number, b: number) => void;
+    readonly wasm_bindgen_91244e9a1334c25a___convert__closures_____invoke_______true__3_: (a: number, b: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;