@bytecodealliance/preview2-shim 0.18.1 → 0.19.0

package/dist/browser/io.d.ts

@@ -0,0 +1,58 @@
+import type { error as ErrorNamespace, poll as PollNamespace, streams as StreamsNamespace } from "../../types/io.js";
+declare const symbolDispose: symbol;
+type IInputStream = StreamsNamespace.InputStream;
+type IOutputStream = StreamsNamespace.OutputStream;
+/**
+ * Handler interface for creating custom input streams
+ */
+export type InputStreamHandler = Partial<IInputStream> & Required<Pick<IInputStream, "blockingRead">> & {
+    drop?: () => void;
+};
+/**
+ * Handler interface for creating custom output streams
+ */
+export type OutputStreamHandler = Partial<IOutputStream> & Required<Pick<IOutputStream, "write">> & {
+    drop?: () => void;
+};
+declare class InputStream implements IInputStream {
+    [symbolDispose]: () => void;
+    id: number;
+    handler: InputStreamHandler;
+    static _create(handler: InputStreamHandler): InputStream;
+    read(len: bigint): Uint8Array<ArrayBufferLike>;
+    blockingRead(len: bigint): Uint8Array<ArrayBufferLike>;
+    skip(len: bigint): bigint;
+    blockingSkip(len: bigint): bigint;
+    subscribe(): PollNamespace.Pollable | Pollable;
+}
+export declare const inputStreamCreate: typeof InputStream._create;
+declare class OutputStream implements IOutputStream {
+    [symbolDispose]: () => void;
+    id: number;
+    open: boolean;
+    handler: OutputStreamHandler;
+    static _create(handler: OutputStreamHandler): OutputStream;
+    checkWrite(): bigint;
+    write(buf: Uint8Array): void;
+    blockingWriteAndFlush(buf: Uint8Array): void;
+    flush(): void;
+    blockingFlush(): void;
+    writeZeroes(len: bigint): void;
+    blockingWriteZeroesAndFlush(len: bigint): void;
+    splice(src: InputStream, len: bigint): bigint;
+    blockingSplice(_src: InputStream, _len: bigint): bigint;
+    subscribe(): PollNamespace.Pollable | Pollable;
+}
+export declare const outputStreamCreate: typeof OutputStream._create;
+export declare const error: typeof ErrorNamespace;
+export declare const streams: typeof StreamsNamespace;
+declare class Pollable implements PollNamespace.Pollable {
+    #private;
+    [symbolDispose]: () => void;
+    static _create(promise?: Promise<void>): Pollable;
+    ready(): boolean;
+    block(): Promise<void>;
+}
+export declare const pollableCreate: typeof Pollable._create;
+export declare const poll: typeof PollNamespace;
+export {};

package/dist/browser/io.js

@@ -0,0 +1,205 @@
+let id = 0;
+const symbolDispose = Symbol.dispose || Symbol.for("dispose");
+class IoError extends Error {
+    toDebugString() {
+        return this.message;
+    }
+}
+class InputStream {
+    id;
+    handler;
+    static _create(handler) {
+        const stream = new InputStream();
+        if (!handler) {
+            console.trace("no handler");
+        }
+        stream.id = ++id;
+        stream.handler = handler;
+        return stream;
+    }
+    read(len) {
+        if (this.handler.read) {
+            return this.handler.read(len);
+        }
+        return this.handler.blockingRead.call(this, len);
+    }
+    blockingRead(len) {
+        return this.handler.blockingRead.call(this, len);
+    }
+    skip(len) {
+        if (this.handler.skip) {
+            return this.handler.skip.call(this, len);
+        }
+        if (this.handler.read) {
+            const bytes = this.handler.read.call(this, len);
+            return BigInt(bytes.byteLength);
+        }
+        return this.blockingSkip.call(this, len);
+    }
+    blockingSkip(len) {
+        if (this.handler.blockingSkip) {
+            return this.handler.blockingSkip.call(this, len);
+        }
+        const bytes = this.handler.blockingRead.call(this, len);
+        return BigInt(bytes.byteLength);
+    }
+    subscribe() {
+        if (this.handler.subscribe) {
+            return this.handler.subscribe();
+        }
+        return new Pollable();
+    }
+    [symbolDispose]() {
+        if (this.handler.drop) {
+            this.handler.drop.call(this);
+        }
+    }
+}
+export const inputStreamCreate = InputStream._create;
+// @ts-expect-error - Deleting static method
+delete InputStream._create;
+class OutputStream {
+    id;
+    open;
+    handler;
+    static _create(handler) {
+        const stream = new OutputStream();
+        if (!handler) {
+            console.trace("no handler");
+        }
+        stream.id = ++id;
+        stream.open = true;
+        stream.handler = handler;
+        return stream;
+    }
+    checkWrite() {
+        if (!this.open) {
+            return 0n;
+        }
+        if (this.handler.checkWrite) {
+            return this.handler.checkWrite.call(this);
+        }
+        return 1000000n;
+    }
+    write(buf) {
+        this.handler.write.call(this, buf);
+    }
+    blockingWriteAndFlush(buf) {
+        if (this.handler.blockingWriteAndFlush) {
+            return this.handler.blockingWriteAndFlush.call(this, buf);
+        }
+        this.handler.write.call(this, buf);
+    }
+    flush() {
+        if (this.handler.flush) {
+            this.handler.flush.call(this);
+        }
+    }
+    blockingFlush() {
+        this.open = true;
+        if (this.handler.blockingFlush) {
+            this.handler.blockingFlush.call(this);
+        }
+    }
+    writeZeroes(len) {
+        this.write.call(this, new Uint8Array(Number(len)));
+    }
+    blockingWriteZeroesAndFlush(len) {
+        this.blockingWriteAndFlush.call(this, new Uint8Array(Number(len)));
+    }
+    splice(src, len) {
+        const spliceLen = Math.min(Number(len), Number(this.checkWrite.call(this)));
+        const bytes = src.read(BigInt(spliceLen));
+        this.write.call(this, bytes);
+        return BigInt(bytes.byteLength);
+    }
+    blockingSplice(_src, _len) {
+        console.log(`[streams] Blocking splice ${this.id}`);
+        return 0n;
+    }
+    subscribe() {
+        if (this.handler.subscribe) {
+            return this.handler.subscribe();
+        }
+        return new Pollable();
+    }
+    [symbolDispose]() { }
+}
+export const outputStreamCreate = OutputStream._create;
+// @ts-expect-error - Deleting static method
+delete OutputStream._create;
+export const error = {
+    Error: IoError,
+};
+export const streams = { InputStream, OutputStream };
+class Pollable {
+    #ready = false;
+    #promise = null;
+    static _create(promise) {
+        const pollable = new Pollable();
+        if (!promise) {
+            pollable.#ready = true;
+        }
+        else {
+            pollable.#promise = promise.then(() => {
+                pollable.#ready = true;
+            }, () => {
+                pollable.#ready = true;
+            });
+        }
+        return pollable;
+    }
+    ready() {
+        return this.#ready;
+    }
+    block() {
+        if (this.#ready) {
+            return Promise.resolve();
+        }
+        return this.#promise || Promise.resolve();
+    }
+    [symbolDispose]() {
+        this.#promise = null;
+    }
+}
+export const pollableCreate = Pollable._create;
+// @ts-expect-error - Deleting static method
+delete Pollable._create;
+function pollList(list) {
+    if (list.length === 0) {
+        throw new Error("poll list must not be empty");
+    }
+    if (list.length > 0xffffffff) {
+        throw new Error("poll list length exceeds u32 index range");
+    }
+    const ready = [];
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].ready()) {
+            ready.push(i);
+        }
+    }
+    if (ready.length > 0) {
+        return new Uint32Array(ready);
+    }
+    // None ready synchronously. Wait for the first to resolve via Promise.race,
+    // then sweep for any others that became ready concurrently.
+    return Promise.race(list.map((p, i) => p.block().then(() => {
+        const result = [i];
+        for (let j = 0; j < list.length; j++) {
+            if (j !== i && list[j].ready()) {
+                result.push(j);
+            }
+        }
+        return new Uint32Array(result);
+    })));
+}
+function pollOne(poll) {
+    return poll.block();
+}
+export const poll = {
+    Pollable,
+    pollList,
+    pollOne,
+    // @ts-expect-error Not matching signature from WIT
+    poll: pollList,
+};

package/dist/browser/random.d.ts

@@ -0,0 +1,4 @@
+import type { insecure as InsecureNamespace, insecureSeed as InsecureSeedNamespace, random as RandomNamespace } from "../../types/random.js";
+export declare const insecure: typeof InsecureNamespace;
+export declare const insecureSeed: typeof InsecureSeedNamespace;
+export declare const random: typeof RandomNamespace;

package/dist/browser/random.js

@@ -0,0 +1,49 @@
+const MAX_BYTES = 65536;
+let insecureRandomValue1, insecureRandomValue2;
+export const insecure = {
+    getInsecureRandomBytes(len) {
+        return random.getRandomBytes(len);
+    },
+    getInsecureRandomU64() {
+        return random.getRandomU64();
+    },
+};
+let insecureSeedValue1, insecureSeedValue2;
+export const insecureSeed = {
+    insecureSeed() {
+        if (insecureSeedValue1 === undefined || insecureSeedValue2 === undefined) {
+            insecureSeedValue1 = random.getRandomU64();
+            insecureSeedValue2 = random.getRandomU64();
+        }
+        return [insecureSeedValue1, insecureSeedValue2];
+    },
+};
+export const random = {
+    getRandomBytes(len) {
+        const bytes = new Uint8Array(Number(len));
+        if (len > MAX_BYTES) {
+            // this is the max bytes crypto.getRandomValues
+            // can do at once see https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues
+            for (var generated = 0; generated < len; generated += MAX_BYTES) {
+                // buffer.slice automatically checks if the end is past the end of
+                // the buffer so we don't have to here
+                crypto.getRandomValues(bytes.subarray(generated, generated + MAX_BYTES));
+            }
+        }
+        else {
+            crypto.getRandomValues(bytes);
+        }
+        return bytes;
+    },
+    getRandomU64() {
+        return crypto.getRandomValues(new BigUint64Array(1))[0];
+    },
+    // @ts-expect-error Not defined in WIT
+    insecureRandom() {
+        if (insecureRandomValue1 === undefined || insecureRandomValue2 === undefined) {
+            insecureRandomValue1 = random.getRandomU64();
+            insecureRandomValue2 = random.getRandomU64();
+        }
+        return [insecureRandomValue1, insecureRandomValue2];
+    },
+};

package/dist/browser/sockets.d.ts

@@ -0,0 +1,8 @@
+import type { instanceNetwork as InstanceNetworkNamespace, ipNameLookup as IpNameLookupNamespace, network as NetworkNamespace, tcpCreateSocket as TcpCreateSocketNamespace, tcp as TcpNamespace, udpCreateSocket as UdpCreateSocketNamespace, udp as UdpNamespace } from "../../types/sockets.js";
+export declare const instanceNetwork: typeof InstanceNetworkNamespace;
+export declare const ipNameLookup: typeof IpNameLookupNamespace;
+export declare const network: typeof NetworkNamespace;
+export declare const tcpCreateSocket: typeof TcpCreateSocketNamespace;
+export declare const tcp: typeof TcpNamespace;
+export declare const udpCreateSocket: typeof UdpCreateSocketNamespace;
+export declare const udp: typeof UdpNamespace;

package/dist/browser/sockets.js

@@ -0,0 +1,66 @@
+export const instanceNetwork = {
+    instanceNetwork() {
+        console.log(`[sockets] instance network`);
+    },
+};
+export const ipNameLookup = {
+    dropResolveAddressStream() { },
+    subscribe() { },
+    resolveAddresses() { },
+    resolveNextAddress() { },
+    nonBlocking() { },
+    setNonBlocking() { },
+};
+export const network = {
+    dropNetwork() { },
+};
+export const tcpCreateSocket = {
+    createTcpSocket() { },
+};
+export const tcp = {
+    subscribe() { },
+    dropTcpSocket() { },
+    bind() { },
+    connect() { },
+    listen() { },
+    accept() { },
+    localAddress() { },
+    remoteAddress() { },
+    addressFamily() { },
+    setListenBacklogSize() { },
+    keepAlive() { },
+    setKeepAlive() { },
+    noDelay() { },
+    setNoDelay() { },
+    unicastHopLimit() { },
+    setUnicastHopLimit() { },
+    receiveBufferSize() { },
+    setReceiveBufferSize() { },
+    sendBufferSize() { },
+    setSendBufferSize() { },
+    nonBlocking() { },
+    setNonBlocking() { },
+    shutdown() { },
+};
+export const udpCreateSocket = {
+    createUdpSocket() { },
+};
+export const udp = {
+    subscribe() { },
+    dropUdpSocket() { },
+    bind() { },
+    connect() { },
+    receive() { },
+    send() { },
+    localAddress() { },
+    remoteAddress() { },
+    addressFamily() { },
+    unicastHopLimit() { },
+    setUnicastHopLimit() { },
+    receiveBufferSize() { },
+    setReceiveBufferSize() { },
+    sendBufferSize() { },
+    setSendBufferSize() { },
+    nonBlocking() { },
+    setNonBlocking() { },
+};

package/dist/common/instantiation.d.ts

@@ -0,0 +1,97 @@
+import type { WASIShimConfig, GetImportObjectArgs, WASIImportObject } from "../../types/instantiation.js";
+/**
+ * (EXPERIMENTAL) A class that holds WASI shims and can be used to configure
+ * an instantiation of a WebAssembly component transpiled with jco
+ * (i.e. via `jco transpile`).
+ *
+ * Normally, transpiled components contain mapping for WASI interfaces
+ * and/or imports that import the relevant packages (ex. `@bytecodealliance/preview2-shim/clocks`)
+ * from the right sources.
+ *
+ * This function makes use of the `WASIShim` object to provide an object that can be easily
+ * fed to the `instantiate` function produced by a transpiled component:
+ *
+ * ```js
+ * import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation"
+ * // ...
+ * import { instantiate } from "path/to/transpiled/component.js"
+ * // ...
+ * const component = await instantiate(null, new WASIShim().getImportObject())
+ * ```
+ *
+ * You can also replace imports that you'd like to override with custom implementations,
+ * by using the `WASIShim` object directly:
+ *
+ * ```js
+ * import { random } from "@bytecodealliance/preview2-shim"
+ * import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation"
+ * // ...
+ * import { instantiate } from "path/to/transpiled/component.js"
+ * // ...
+ * const customWASIShim = new WASIShim({
+ *     random: {
+ *         // For these two interfaces we re-use the default provided shim
+ *         random: random.random,
+ *         insecure-seed: random.insecureSeed,
+ *         // For insecure, we can supply our own custom implementation
+ *         insecure: {
+ *             ...
+ *         }
+ *     }
+ * });
+ *
+ * const component = await instantiate(null, customWASIShim.getImportObject())
+ * ```
+ *
+ * For sandboxing, you can configure preopens, environment variables, and other
+ * capabilities via the `sandbox` option:
+ *
+ * ```js
+ * import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation"
+ *
+ * // Fully sandboxed - no filesystem, network, or env access
+ * const sandboxedShim = new WASIShim({
+ *   sandbox: {
+ *     preopens: {},           // No filesystem access
+ *     env: {},                // No environment variables
+ *     args: ['program'],      // Custom arguments
+ *     enableNetwork: false,   // Disable network (default: true for backward compat)
+ *   }
+ * });
+ *
+ * // Limited filesystem access
+ * const limitedShim = new WASIShim({
+ *   sandbox: {
+ *     preopens: {
+ *       '/data': '/tmp/guest-data',  // Guest sees /data, maps to /tmp/guest-data
+ *       '/config': '/etc/app'        // Guest sees /config, maps to /etc/app
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * Note that this object is similar but not identical to the Node `WASI` object --
+ * it is solely concerned with shimming of preview2 when dealing with a WebAssembly
+ * component transpiled by Jco. While this object *does* work with Node (and the browser)
+ * semantics are not the same as Node's `WASI` object.
+ *
+ * @class WASIShim
+ */
+export declare class WASIShim {
+    #private;
+    /**
+     * Create a new WASIShim instance.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config?: WASIShimConfig);
+    /**
+     * Generate an import object for the shim that can be used with
+     * functions like `instantiate` that are exposed from a transpiled
+     * WebAssembly component.
+     *
+     * @param opts - options for import object generation
+     * @returns WASIImportObject
+     */
+    getImportObject(opts?: GetImportObjectArgs): WASIImportObject;
+}