@bytecodealliance/preview2-shim 0.24.1 → 0.25.0

package/README.md

@@ -256,3 +256,14 @@ See [LICENSE](LICENSE) for more details.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in this project by you, as defined in the Apache-2.0 license,
 shall be licensed as above, without any additional terms or conditions.
+
+### Host IO extensions
+
+Opt-in providers can use the Node-only `@bytecodealliance/preview2-shim/io-worker`
+entry point to operate on existing streams in the shim's IO worker. Host-selected
+modules load lazily and share the worker's stream, future, and poll ownership rules.
+Guest code cannot select extension modules.
+
+The Node `wasi:tls` provider and its TLS policy live in
+[`jco-std`](../jco-std/README.md#http-1), which wraps the supplied TCP streams
+without opening a replacement connection.

package/dist/browser/filesystem.d.ts

@@ -3,6 +3,8 @@ import type { FileData } from "./in-memory-filesystem.js";
 export { _setCwd } from "./config.js";
 export { InMemoryFilesystemAdapter } from "./in-memory-filesystem.js";
 export type { FileData, FileDataEntry } from "./in-memory-filesystem.js";
+export { OpfsFilesystemAdapter, loadOpfsCapability } from "./opfs-filesystem.js";
+export type { OpfsCapability } from "./opfs-filesystem.js";
 type Filesize = TypesNamespace.Filesize;
 type OpenFlags = TypesNamespace.OpenFlags;
 type PathFlags = TypesNamespace.PathFlags;
@@ -15,6 +17,17 @@ export interface BrowserFilesystemDescriptor extends Omit<TypesNamespace.Descrip
     openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: TypesNamespace.DescriptorFlags): BrowserFilesystemDescriptor;
     renameAt(oldPath: string, newDescriptor: BrowserFilesystemDescriptor, newPath: string): void;
     isSameObject(other: BrowserFilesystemDescriptor): boolean;
+    /**
+     * Advisory locking, for host application code holding a descriptor directly
+     * (not part of the WASI guest-facing surface). Adapters that support it should
+     * implement all five; `tryLock*` return whether the lock was acquired instead
+     * of throwing.
+     */
+    lockShared?(): void;
+    lockExclusive?(): void;
+    tryLockShared?(): boolean;
+    tryLockExclusive?(): boolean;
+    unlock?(): void;
 }
 export interface BrowserFilesystemAdapter<Capability = unknown> {
     getRoot(capability: Capability): BrowserFilesystemDescriptor;
@@ -60,6 +73,11 @@ declare class Descriptor implements TypesNamespace.Descriptor {
     isSameObject(other: TypesNamespace.Descriptor): boolean;
     metadataHash(): TypesNamespace.MetadataHashValue;
     metadataHashAt(pathFlags: PathFlags, path: string): TypesNamespace.MetadataHashValue;
+    lockShared(): void | undefined;
+    lockExclusive(): void | undefined;
+    tryLockShared(): boolean;
+    tryLockExclusive(): boolean;
+    unlock(): void | undefined;
 }
 export declare const preopens: typeof PreopensNamespace;
 /** Create isolated filesystem namespaces backed by an application-selected adapter. */
@@ -81,6 +99,15 @@ export declare function _setPreopens(preopensConfig: Record<string, FileData>):
  * @param fileData - The file data object representing the directory
  */
 export declare function _addPreopen(virtualPath: string, fileData: FileData): void;
+/**
+ * Add a single preopen backed by a custom adapter (e.g. `OpfsFilesystemAdapter`) instead of the
+ * default in-memory one. Lets a host wire an alternative `BrowserFilesystemAdapter` into the
+ * top-level `wasi:filesystem/preopens` singleton that transpiled components import statically.
+ * @param virtualPath - The virtual path visible to the guest
+ * @param adapter - The adapter that will back this preopen
+ * @param capability - The adapter-specific capability to load as the preopen's root
+ */
+export declare function _addPreopenWithAdapter<Capability>(virtualPath: string, adapter: BrowserFilesystemAdapter<Capability>, capability: Capability): void;
 /** Clear all preopens, giving the guest no filesystem access. */
 export declare function _clearPreopens(): void;
 /** Get current preopens configuration. */

package/dist/browser/filesystem.js

@@ -3,6 +3,7 @@ import { InMemoryFilesystemAdapter } from "./in-memory-filesystem.js";
 import { _setCwd } from "./config.js";
 export { _setCwd } from "./config.js";
 export { InMemoryFilesystemAdapter } from "./in-memory-filesystem.js";
+export { OpfsFilesystemAdapter, loadOpfsCapability } from "./opfs-filesystem.js";
 class DirectoryEntryStream {
     #implementation;
     static _create(implementation) {
@@ -108,6 +109,21 @@ class Descriptor {
     metadataHashAt(pathFlags, path) {
         return this.#implementation.metadataHashAt(pathFlags, path);
     }
+    lockShared() {
+        return this.#implementation.lockShared?.();
+    }
+    lockExclusive() {
+        return this.#implementation.lockExclusive?.();
+    }
+    tryLockShared() {
+        return this.#implementation.tryLockShared?.() ?? false;
+    }
+    tryLockExclusive() {
+        return this.#implementation.tryLockExclusive?.() ?? false;
+    }
+    unlock() {
+        return this.#implementation.unlock?.();
+    }
 }
 const descriptorGetImplementation = Descriptor.prototype._getImplementation;
 // @ts-expect-error - Deleting prototype method
@@ -185,6 +201,22 @@ export function _addPreopen(virtualPath, fileData) {
         _rootPreopen = entry;
     }
 }
+/**
+ * Add a single preopen backed by a custom adapter (e.g. `OpfsFilesystemAdapter`) instead of the
+ * default in-memory one. Lets a host wire an alternative `BrowserFilesystemAdapter` into the
+ * top-level `wasi:filesystem/preopens` singleton that transpiled components import statically.
+ * @param virtualPath - The virtual path visible to the guest
+ * @param adapter - The adapter that will back this preopen
+ * @param capability - The adapter-specific capability to load as the preopen's root
+ */
+export function _addPreopenWithAdapter(virtualPath, adapter, capability) {
+    const descriptor = descriptorCreate(adapter.getRoot(capability));
+    const entry = [descriptor, virtualPath];
+    _preopens.push(entry);
+    if (virtualPath === "/") {
+        _rootPreopen = entry;
+    }
+}
 /** Clear all preopens, giving the guest no filesystem access. */
 export function _clearPreopens() {
     _preopens = [];

package/dist/browser/in-memory-filesystem.d.ts

@@ -16,6 +16,22 @@ export interface FileDataEntry {
  * };
  */
 export type FileData = FileDataEntry;
+/**
+ * Subscribe to every mutation across every in-memory tree (regardless of which
+ * adapter loaded it). Lets a persistence layer (e.g. `OpfsFilesystemAdapter`)
+ * react to writes without wrapping every mutating method individually. Returns
+ * an unsubscribe function.
+ */
+export declare function _onTouch(listener: (entry: FileDataEntry) => void): () => void;
+/**
+ * Well-known symbol a `BrowserFilesystemDescriptor` wrapper (e.g. the cross-tab-locking
+ * `Proxy` from `OpfsFilesystemAdapter`) can implement to hand back the real descriptor it
+ * wraps. `renameAt`/`linkAt`/`isSameObject` reach into a *second* descriptor argument's
+ * private `#entry` field directly - private-field access bypasses `Proxy` traps and fails
+ * its brand check against a wrapper, so a wrapper must be unwrapped via ordinary property
+ * access (which a `Proxy` handles correctly) before that field access happens.
+ */
+export declare const UNWRAP_DESCRIPTOR: unique symbol;
 /** Explicit ephemeral storage adapter for browser applications and tests. */
 export declare class InMemoryFilesystemAdapter implements BrowserFilesystemAdapter<FileData> {
     getRoot(capability: FileData): BrowserFilesystemDescriptor;

package/dist/browser/in-memory-filesystem.js

@@ -138,8 +138,31 @@ function metadata(entry) {
     }
     return value;
 }
+const fileLocks = new WeakMap();
+function lockState(entry) {
+    let state = fileLocks.get(entry);
+    if (!state) {
+        state = { exclusiveHolder: null, sharedHolders: new Set() };
+        fileLocks.set(entry, state);
+    }
+    return state;
+}
+const touchListeners = new Set();
+/**
+ * Subscribe to every mutation across every in-memory tree (regardless of which
+ * adapter loaded it). Lets a persistence layer (e.g. `OpfsFilesystemAdapter`)
+ * react to writes without wrapping every mutating method individually. Returns
+ * an unsubscribe function.
+ */
+export function _onTouch(listener) {
+    touchListeners.add(listener);
+    return () => touchListeners.delete(listener);
+}
 function touch(entry) {
     metadata(entry).version++;
+    for (const listener of touchListeners) {
+        listener(entry);
+    }
 }
 function getFileWriteBuffer(entry, source, requiredLength) {
     let buffer = fileWriteBuffers.get(entry);
@@ -374,7 +397,7 @@ class Descriptor {
         if (entry.dir) {
             throw "not-permitted";
         }
-        const [newParent, newName] = getParentEntry(descriptorGetEntry(newDescriptor), newPath);
+        const [newParent, newName] = getParentEntry(descriptorGetEntry(unwrapDescriptor(newDescriptor)), newPath);
         if (newParent.dir[newName]) {
             throw "exist";
         }
@@ -447,7 +470,7 @@ class Descriptor {
         if (!entry) {
             throw "no-entry";
         }
-        const [newParent, newName] = getParentEntry(descriptorGetEntry(newDescriptor), newPath);
+        const [newParent, newName] = getParentEntry(descriptorGetEntry(unwrapDescriptor(newDescriptor)), newPath);
         const replaced = newParent.dir[newName];
         if ((oldParent === newParent && oldName === newName) || replaced === entry) {
             return;
@@ -501,7 +524,7 @@ class Descriptor {
         touch(parent);
     }
     isSameObject(other) {
-        return descriptorGetEntry(other) === this.#entry;
+        return descriptorGetEntry(unwrapDescriptor(other)) === this.#entry;
     }
     metadataHash() {
         const value = metadata(this.#entry);
@@ -511,6 +534,54 @@ class Descriptor {
         const value = metadata(getChildEntry(this.#entry, path, pathFlags.symlinkFollow));
         return { upper: value.id, lower: value.version };
     }
+    /**
+     * Default advisory-locking implementation: a same-process reader/writer lock
+     * keyed on the underlying entry. There's no real contention to wait out in a
+     * single-threaded environment, so `lockShared`/`lockExclusive` don't block -
+     * they throw `would-block` immediately when the lock isn't free, same as the
+     * `tryLock*` variants report `false`.
+     */
+    tryLockShared() {
+        const state = lockState(this.#entry);
+        if (state.exclusiveHolder && state.exclusiveHolder !== this) {
+            return false;
+        }
+        state.sharedHolders.add(this);
+        return true;
+    }
+    tryLockExclusive() {
+        const state = lockState(this.#entry);
+        if (state.exclusiveHolder && state.exclusiveHolder !== this) {
+            return false;
+        }
+        const otherReaders = state.sharedHolders.size - (state.sharedHolders.has(this) ? 1 : 0);
+        if (otherReaders > 0) {
+            return false;
+        }
+        state.sharedHolders.delete(this);
+        state.exclusiveHolder = this;
+        return true;
+    }
+    lockShared() {
+        if (!this.tryLockShared()) {
+            throw "would-block";
+        }
+    }
+    lockExclusive() {
+        if (!this.tryLockExclusive()) {
+            throw "would-block";
+        }
+    }
+    unlock() {
+        const state = fileLocks.get(this.#entry);
+        if (!state) {
+            return;
+        }
+        state.sharedHolders.delete(this);
+        if (state.exclusiveHolder === this) {
+            state.exclusiveHolder = null;
+        }
+    }
 }
 const descriptorGetEntry = Descriptor.prototype._getEntry;
 // @ts-expect-error - Deleting prototype method
@@ -518,6 +589,25 @@ delete Descriptor.prototype._getEntry;
 const descriptorCreate = Descriptor._create;
 // @ts-expect-error - Deleting static method
 delete Descriptor._create;
+/**
+ * Well-known symbol a `BrowserFilesystemDescriptor` wrapper (e.g. the cross-tab-locking
+ * `Proxy` from `OpfsFilesystemAdapter`) can implement to hand back the real descriptor it
+ * wraps. `renameAt`/`linkAt`/`isSameObject` reach into a *second* descriptor argument's
+ * private `#entry` field directly - private-field access bypasses `Proxy` traps and fails
+ * its brand check against a wrapper, so a wrapper must be unwrapped via ordinary property
+ * access (which a `Proxy` handles correctly) before that field access happens.
+ */
+export const UNWRAP_DESCRIPTOR = Symbol("browserFilesystemDescriptor.unwrap");
+function unwrapDescriptor(descriptor) {
+    let current = descriptor;
+    for (;;) {
+        const inner = current[UNWRAP_DESCRIPTOR];
+        if (!inner || inner === current) {
+            return current;
+        }
+        current = inner;
+    }
+}
 /** Explicit ephemeral storage adapter for browser applications and tests. */
 export class InMemoryFilesystemAdapter {
     getRoot(capability) {

package/dist/browser/opfs-filesystem.d.ts

@@ -0,0 +1,51 @@
+import type { BrowserFilesystemAdapter, BrowserFilesystemDescriptor } from "./filesystem.js";
+import type { FileData } from "./in-memory-filesystem.js";
+/**
+ * A directory handle paired with the in-memory tree it was loaded into.
+ * `getRoot` hands the `data` half straight to `InMemoryFilesystemAdapter`, so every
+ * guest-visible filesystem operation stays fully synchronous; only the initial load
+ * and the explicit `flush`/`dispose` round-trip to OPFS are async.
+ */
+export interface OpfsCapability {
+    handle: FileSystemDirectoryHandle;
+    data: FileData;
+}
+/** Load an OPFS directory into an in-memory tree, ready to hand to `OpfsFilesystemAdapter.getRoot`. */
+export declare function loadOpfsCapability(handle: FileSystemDirectoryHandle): Promise<OpfsCapability>;
+/**
+ * The slice of `LockManager` this adapter needs - narrow enough to fake in tests or other hosts.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/LockManager
+ */
+export interface BrowserLockManager extends Omit<LockManager, "query"> {
+}
+export interface OpfsFilesystemAdapterOptions {
+    /**
+     * Also make advisory locks (`lockShared`/`lockExclusive`/`tryLock*`/`unlock`) request a
+     * matching lock from the given `BrowserLockManager` (usually the global `navigator.locks`,
+     * or a fake in tests), so tabs sharing the same OPFS root get best-effort cross-tab
+     * coordination on top of the default same-process reader/writer lock. Omit to keep locking
+     * same-process only - off by default.
+     */
+    lockManager?: BrowserLockManager;
+}
+/**
+ * Browser filesystem adapter backed by the Origin Private File System.
+ *
+ * Every guest-facing `Descriptor` operation - including advisory locking, which
+ * comes for free as `InMemoryFilesystemAdapter`'s same-process reader/writer lock -
+ * is delegated to `InMemoryFilesystemAdapter` and stays synchronous. Persistence to
+ * OPFS happens automatically shortly after any mutation (debounced to a microtask,
+ * so a burst of writes only triggers one round-trip); `flush()`/`dispose()` remain
+ * available to force it explicitly, e.g. before navigating away.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system
+ */
+export declare class OpfsFilesystemAdapter implements BrowserFilesystemAdapter<OpfsCapability> {
+    #private;
+    constructor(options?: OpfsFilesystemAdapterOptions);
+    getRoot(capability: OpfsCapability): BrowserFilesystemDescriptor;
+    /** Persist every loaded root's current in-memory state back to OPFS. */
+    flush(): Promise<void>;
+    dispose(): void;
+}

package/dist/browser/opfs-filesystem.js

@@ -0,0 +1,245 @@
+import { InMemoryFilesystemAdapter, UNWRAP_DESCRIPTOR, _onTouch } from "./in-memory-filesystem.js";
+// OPFS has no native symlink concept. All symlinks under a root are recorded in a
+// single hidden sidecar file at that root, keyed by their path relative to it, so
+// they survive a flush + reload instead of only living for the lifetime of one
+// capability.
+const SYMLINKS_FILE = ".__wasi_symlinks__.json";
+async function readSymlinksFile(handle) {
+    try {
+        const fileHandle = await handle.getFileHandle(SYMLINKS_FILE);
+        const file = await fileHandle.getFile();
+        return JSON.parse(await file.text());
+    }
+    catch {
+        return {};
+    }
+}
+async function writeSymlinksFile(handle, symlinks) {
+    if (Object.keys(symlinks).length === 0) {
+        try {
+            await handle.removeEntry(SYMLINKS_FILE);
+        }
+        catch {
+            // no sidecar to remove
+        }
+        return;
+    }
+    const fileHandle = await handle.getFileHandle(SYMLINKS_FILE, { create: true });
+    const writable = await fileHandle.createWritable();
+    await writable.write(JSON.stringify(symlinks));
+    await writable.close();
+}
+/** Collect every symlink under `dir` into a flat path -> target map, relative to `dir` itself. */
+function collectSymlinks(dir, prefix, out) {
+    for (const [name, entry] of Object.entries(dir)) {
+        const path = prefix ? `${prefix}/${name}` : name;
+        if (entry.symlink !== undefined) {
+            out[path] = entry.symlink;
+        }
+        else if (entry.dir) {
+            collectSymlinks(entry.dir, path, out);
+        }
+    }
+}
+/** Place each recorded symlink back into the tree at its path, skipping any path whose parent is missing. */
+function injectSymlinks(root, symlinks) {
+    for (const [path, target] of Object.entries(symlinks)) {
+        const parts = path.split("/").filter(Boolean);
+        const name = parts.pop();
+        if (!name) {
+            continue;
+        }
+        let dir = root;
+        for (const part of parts) {
+            dir = dir[part]?.dir;
+            if (!dir) {
+                break;
+            }
+        }
+        if (dir && !(name in dir)) {
+            dir[name] = { symlink: target };
+        }
+    }
+}
+async function readEntries(handle) {
+    const dir = {};
+    for await (const [name, child] of handle.entries()) {
+        if (name === SYMLINKS_FILE) {
+            continue;
+        }
+        if (child.kind === "directory") {
+            dir[name] = { dir: await readEntries(child) };
+        }
+        else {
+            const file = await child.getFile();
+            dir[name] = { source: new Uint8Array(await file.arrayBuffer()) };
+        }
+    }
+    return dir;
+}
+async function writeEntries(handle, dir) {
+    const seen = new Set(Object.keys(dir));
+    seen.add(SYMLINKS_FILE);
+    for await (const [name] of handle.entries()) {
+        if (!seen.has(name)) {
+            await handle.removeEntry(name, { recursive: true });
+        }
+    }
+    for (const [name, entry] of Object.entries(dir)) {
+        if (entry.symlink !== undefined) {
+            // Recorded separately in the root's symlink sidecar file.
+            continue;
+        }
+        if (entry.dir) {
+            await writeEntries(await handle.getDirectoryHandle(name, { create: true }), entry.dir);
+            continue;
+        }
+        const fileHandle = await handle.getFileHandle(name, { create: true });
+        const writable = await fileHandle.createWritable();
+        const source = entry.source ?? new Uint8Array();
+        const bytes = typeof source === "string" ? new TextEncoder().encode(source) : source;
+        await writable.write(bytes.slice());
+        await writable.close();
+    }
+}
+/** Load an OPFS directory into an in-memory tree, ready to hand to `OpfsFilesystemAdapter.getRoot`. */
+export async function loadOpfsCapability(handle) {
+    const dir = await readEntries(handle);
+    injectSymlinks(dir, await readSymlinksFile(handle));
+    return { handle, data: { dir } };
+}
+const LOCK_METHODS = new Set([
+    "lockShared",
+    "lockExclusive",
+    "tryLockShared",
+    "tryLockExclusive",
+    "unlock",
+]);
+function lockModeOf(prop) {
+    return prop.endsWith("Exclusive") ? "exclusive" : "shared";
+}
+/** Join an OPFS-relative path onto an existing one, for naming a cross-tab lock. */
+function joinLockPath(base, segment) {
+    let path = base;
+    for (const part of segment.split("/")) {
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            path = path.slice(0, path.lastIndexOf("/"));
+            continue;
+        }
+        path = path ? `${path}/${part}` : part;
+    }
+    return path;
+}
+/**
+ * Wrap a descriptor so its advisory locking also makes a best-effort request against
+ * `BrowserLockManager`, in addition to the default same-process reader/writer lock.
+ * The Web Locks request is fire-and-forget - there's no way to block a synchronous
+ * `lockExclusive()` on a cross-tab grant without JSPI, so this only coordinates
+ * tabs that are already idle/cooperating.
+ */
+function withCrossTabLocking(descriptor, lockName, lockManager) {
+    let release = null;
+    function requestCrossTabLock(mode) {
+        if (!lockManager) {
+            return;
+        }
+        lockManager
+            .request(lockName, { mode }, () => new Promise((resolve) => (release = resolve)))
+            .catch(() => {
+            // best-effort only; local same-process locking already enforced correctness
+        });
+    }
+    function releaseCrossTabLock() {
+        release?.();
+        release = null;
+    }
+    return new Proxy(descriptor, {
+        get(target, prop, receiver) {
+            if (prop === UNWRAP_DESCRIPTOR) {
+                return target;
+            }
+            const value = Reflect.get(target, prop, receiver);
+            if (prop === "openAt") {
+                return (...args) => {
+                    const child = Reflect.apply(value, target, args);
+                    return withCrossTabLocking(child, joinLockPath(lockName, args[1]), lockManager);
+                };
+            }
+            if (typeof prop === "string" && LOCK_METHODS.has(prop) && typeof value === "function") {
+                return (...args) => {
+                    const result = Reflect.apply(value, target, args);
+                    if (prop === "unlock") {
+                        releaseCrossTabLock();
+                    }
+                    else if (prop.startsWith("tryLock")) {
+                        if (result) {
+                            requestCrossTabLock(lockModeOf(prop));
+                        }
+                    }
+                    else {
+                        requestCrossTabLock(lockModeOf(prop));
+                    }
+                    return result;
+                };
+            }
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/**
+ * Browser filesystem adapter backed by the Origin Private File System.
+ *
+ * Every guest-facing `Descriptor` operation - including advisory locking, which
+ * comes for free as `InMemoryFilesystemAdapter`'s same-process reader/writer lock -
+ * is delegated to `InMemoryFilesystemAdapter` and stays synchronous. Persistence to
+ * OPFS happens automatically shortly after any mutation (debounced to a microtask,
+ * so a burst of writes only triggers one round-trip); `flush()`/`dispose()` remain
+ * available to force it explicitly, e.g. before navigating away.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system
+ */
+export class OpfsFilesystemAdapter {
+    #inMemory = new InMemoryFilesystemAdapter();
+    #roots = [];
+    #lockManager;
+    #flushScheduled = false;
+    #unsubscribeTouch;
+    constructor(options = {}) {
+        this.#lockManager = options.lockManager;
+        this.#unsubscribeTouch = _onTouch(() => this.#scheduleFlush());
+    }
+    getRoot(capability) {
+        this.#roots.push(capability);
+        const descriptor = this.#inMemory.getRoot(capability.data);
+        return this.#lockManager
+            ? withCrossTabLocking(descriptor, capability.handle.name, this.#lockManager)
+            : descriptor;
+    }
+    #scheduleFlush() {
+        if (this.#flushScheduled) {
+            return;
+        }
+        this.#flushScheduled = true;
+        queueMicrotask(() => {
+            this.#flushScheduled = false;
+            void this.flush();
+        });
+    }
+    /** Persist every loaded root's current in-memory state back to OPFS. */
+    async flush() {
+        await Promise.all(this.#roots.map(async (root) => {
+            const dir = root.data.dir ?? {};
+            await writeEntries(root.handle, dir);
+            const symlinks = {};
+            collectSymlinks(dir, "", symlinks);
+            await writeSymlinksFile(root.handle, symlinks);
+        }));
+    }
+    dispose() {
+        this.#unsubscribeTouch();
+        void this.flush();
+    }
+}

package/dist/io/calls.d.ts

@@ -100,4 +100,5 @@ export declare const SOCKET_RESOLVE_ADDRESS_CREATE_REQUEST: number;
 export declare const SOCKET_RESOLVE_ADDRESS_TAKE_REQUEST: number;
 export declare const SOCKET_RESOLVE_ADDRESS_SUBSCRIBE_REQUEST: number;
 export declare const SOCKET_RESOLVE_ADDRESS_DISPOSE_REQUEST: number;
+export declare const WORKER_EXTENSION_CALL: number;
 export declare const reverseMap: {};

package/dist/io/calls.js

@@ -116,6 +116,8 @@ export const SOCKET_RESOLVE_ADDRESS_CREATE_REQUEST = ++call_id << CALL_SHIFT;
 export const SOCKET_RESOLVE_ADDRESS_TAKE_REQUEST = ++call_id << CALL_SHIFT;
 export const SOCKET_RESOLVE_ADDRESS_SUBSCRIBE_REQUEST = ++call_id << CALL_SHIFT;
 export const SOCKET_RESOLVE_ADDRESS_DISPOSE_REQUEST = ++call_id << CALL_SHIFT;
+// Host extensions execute alongside the streams they operate on.
+export const WORKER_EXTENSION_CALL = ++call_id << CALL_SHIFT;
 export const reverseMap = {};
 import * as calls from "./calls.js";
 for (const name of Object.getOwnPropertyNames(calls)) {

package/dist/io/extension.d.ts

@@ -0,0 +1,15 @@
+/** IO-worker integration for opt-in host providers. No capability is installed by importing this module. */
+import type { Readable, Writable } from "node:stream";
+export interface WorkerExtensionContext {
+    createFuture(promise: Promise<void>): number;
+    createReadableStream(stream: Readable): number;
+    createWritableStream(stream: Writable): number;
+    getStream(id: number): unknown;
+    resourceCounts(): {
+        streams: number;
+        futures: number;
+        polls: number;
+        sockets: number;
+    };
+}
+export type WorkerExtension = (operation: string, args: unknown[]) => unknown | Promise<unknown>;

package/dist/io/extension.js

@@ -0,0 +1 @@
+export {};

package/dist/io/worker-sockets.d.ts

@@ -11,9 +11,6 @@ export declare function noLookup(ip: any, _opts: any, cb: any): void;
 export declare function socketResolveAddress(name: string): Promise<{
     tag: string;
     val: Ipv4Address | Ipv6Address;
-}[][]> | Promise<{
-    tag: string;
-    val: Ipv4Address | Ipv6Address;
 }[]>;
 export declare function convertSocketError(err: any): "access-denied" | "address-in-use" | "address-not-bindable" | "concurrency-conflict" | "connection-aborted" | "connection-refused" | "connection-reset" | "datagram-too-large" | "invalid-argument" | "invalid-state" | "new-socket-limit" | "not-supported" | "out-of-memory" | "remote-unreachable" | "unknown" | "would-block";
 export declare function convertSocketErrorCode(code: any): "access-denied" | "address-in-use" | "address-not-bindable" | "concurrency-conflict" | "connection-aborted" | "connection-refused" | "connection-reset" | "datagram-too-large" | "invalid-argument" | "invalid-state" | "new-socket-limit" | "not-supported" | "out-of-memory" | "remote-unreachable" | "unknown" | "would-block";

package/dist/io/worker-sockets.js

@@ -51,12 +51,10 @@ export function socketResolveAddress(name) {
     }
     return lookup(name, dnsLookupOptions).then((addresses) => {
         return (Array.isArray(addresses) ? addresses : [addresses]).map(({ address, family }) => {
-            return [
-                {
-                    tag: "ipv" + family,
-                    val: (family === 4 ? ipv4ToTuple : ipv6ToTuple)(address),
-                },
-            ];
+            return {
+                tag: "ipv" + family,
+                val: (family === 4 ? ipv4ToTuple : ipv6ToTuple)(address),
+            };
         });
     }, (err) => {
         switch (err.code) {

package/dist/io/worker-thread.bundle.js

@@ -23,54 +23,6 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
-//#region dist/synckit/index.js
-function extractProperties(object) {
-	if (object && typeof object === "object") {
-		const properties = {};
-		for (const key in object) properties[key] = object[key];
-		return properties;
-	}
-}
-function runAsWorker(fn) {
-	if (!workerData) return;
-	const { workerPort, debug } = workerData;
-	try {
-		parentPort?.on("message", ({ sharedBuffer, cid, args }) => {
-			(async () => {
-				const sharedBufferView = new Int32Array(sharedBuffer);
-				let msg;
-				try {
-					msg = {
-						cid,
-						result: await fn(...args)
-					};
-				} catch (error) {
-					msg = {
-						cid,
-						error,
-						properties: extractProperties(error)
-					};
-				}
-				workerPort.postMessage(msg);
-				Atomics.add(sharedBufferView, 0, 1);
-				Atomics.notify(sharedBufferView, 0);
-			})();
-		});
-	} catch (error) {
-		parentPort?.on("message", ({ sharedBuffer, cid }) => {
-			const sharedBufferView = new Int32Array(sharedBuffer);
-			workerPort.postMessage({
-				cid,
-				error,
-				properties: extractProperties(error)
-			});
-			Atomics.add(sharedBufferView, 0, 1);
-			Atomics.notify(sharedBufferView, 0);
-		});
-	}
-	return debug;
-}
-//#endregion
 //#region dist/io/calls.js
 var calls_exports = /* @__PURE__ */ __exportAll({
 	CALL_MASK: () => CALL_MASK,
@@ -175,6 +127,7 @@ var calls_exports = /* @__PURE__ */ __exportAll({
 	STDERR: () => STDERR,
 	STDIN: () => STDIN,
 	STDOUT: () => STDOUT,
+	WORKER_EXTENSION_CALL: () => WORKER_EXTENSION_CALL,
 	reverseMap: () => reverseMap
 });
 let call_id = 0;
@@ -280,12 +233,61 @@ const SOCKET_RESOLVE_ADDRESS_CREATE_REQUEST = ++call_id << 24;
 const SOCKET_RESOLVE_ADDRESS_TAKE_REQUEST = ++call_id << 24;
 const SOCKET_RESOLVE_ADDRESS_SUBSCRIBE_REQUEST = ++call_id << 24;
 const SOCKET_RESOLVE_ADDRESS_DISPOSE_REQUEST = ++call_id << 24;
+const WORKER_EXTENSION_CALL = ++call_id << 24;
 const reverseMap = {};
 for (const name of Object.getOwnPropertyNames(calls_exports)) {
 	if (name === "reverseMap") continue;
 	reverseMap[calls_exports[name]] = name;
 }
 //#endregion
+//#region dist/synckit/index.js
+function extractProperties(object) {
+	if (object && typeof object === "object") {
+		const properties = {};
+		for (const key in object) properties[key] = object[key];
+		return properties;
+	}
+}
+function runAsWorker(fn) {
+	if (!workerData) return;
+	const { workerPort, debug } = workerData;
+	try {
+		parentPort?.on("message", ({ sharedBuffer, cid, args }) => {
+			(async () => {
+				const sharedBufferView = new Int32Array(sharedBuffer);
+				let msg;
+				try {
+					msg = {
+						cid,
+						result: await fn(...args)
+					};
+				} catch (error) {
+					msg = {
+						cid,
+						error,
+						properties: extractProperties(error)
+					};
+				}
+				workerPort.postMessage(msg);
+				Atomics.add(sharedBufferView, 0, 1);
+				Atomics.notify(sharedBufferView, 0);
+			})();
+		});
+	} catch (error) {
+		parentPort?.on("message", ({ sharedBuffer, cid }) => {
+			const sharedBufferView = new Int32Array(sharedBuffer);
+			workerPort.postMessage({
+				cid,
+				error,
+				properties: extractProperties(error)
+			});
+			Atomics.add(sharedBufferView, 0, 1);
+			Atomics.notify(sharedBufferView, 0);
+		});
+	}
+	return debug;
+}
+//#endregion
 //#region dist/io/worker-http.js
 const agentOptions = { keepAlive: true };
 const httpAgent = new Agent(agentOptions);
@@ -577,10 +579,10 @@ function socketResolveAddress(name) {
 	if (!parsedUrl) throw "invalid-argument";
 	return lookup(name, dnsLookupOptions).then((addresses) => {
 		return (Array.isArray(addresses) ? addresses : [addresses]).map(({ address, family }) => {
-			return [{
+			return {
 				tag: "ipv" + family,
 				val: (family === 4 ? ipv4ToTuple : ipv6ToTuple)(address)
-			}];
+			};
 		});
 	}, (err) => {
 		switch (err.code) {
@@ -1438,6 +1440,28 @@ function getStreamOrThrow(streamId) {
 	if (stream.stream.closed) throw { tag: "closed" };
 	return stream;
 }
+const extensions = /* @__PURE__ */ new Map();
+async function callExtension(module, operation, args) {
+	let extension = extensions.get(module);
+	if (!extension) {
+		extension = import(module).then(({ default: create }) => {
+			return create({
+				createFuture: (promise) => createFuture(promise, void 0),
+				createReadableStream,
+				createWritableStream,
+				getStream: (id) => getStreamOrThrow(id).stream,
+				resourceCounts: () => ({
+					streams: streams.size,
+					futures: futures.size,
+					polls: polls.size,
+					sockets: tcpSockets.size
+				})
+			});
+		});
+		extensions.set(module, extension);
+	}
+	return (await extension)(operation, args);
+}
 /**
 * @param {number} call
 * @param {number | null} id
@@ -1447,6 +1471,7 @@ function getStreamOrThrow(streamId) {
 function handle(call, id, payload) {
 	if (uncaughtException) throw uncaughtException;
 	switch (call) {
+		case WORKER_EXTENSION_CALL: return callExtension(payload.module, payload.operation, payload.args);
 		case HTTP_CREATE_REQUEST: {
 			const { method, scheme, authority, pathWithQuery, headers, body, connectTimeout, betweenBytesTimeout, firstByteTimeout } = payload;
 			return createFuture(createHttpRequest(method, scheme, authority, pathWithQuery, headers, body, connectTimeout, betweenBytesTimeout, firstByteTimeout), void 0);
@@ -1806,12 +1831,7 @@ function handle(call, id, payload) {
 			if (!polls.delete(id)) throw new Error(`wasi-io trap: Disposed a poll ${id} that does not exist`);
 			return;
 		case FUTURE_TAKE_VALUE: return futureTakeValue(id);
-		case FUTURE_SUBSCRIBE: {
-			const { pollState } = futures.get(id);
-			const pollId = ++pollCnt;
-			polls.set(pollId, pollState);
-			return pollId;
-		}
+		case FUTURE_SUBSCRIBE: return createPoll(futures.get(id).pollState);
 		case FUTURE_DISPOSE:
 			futureDispose(id, true);
 			return;

package/dist/io/worker-thread.js

@@ -1,3 +1,4 @@
+import { WORKER_EXTENSION_CALL } from "./calls.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import { hrtime, stderr, stdout } from "node:process";
 import { PassThrough } from "node:stream";
@@ -118,6 +119,29 @@ export function getStreamOrThrow(streamId) {
     }
     return stream;
 }
+const extensions = new Map();
+async function callExtension(module, operation, args) {
+    let extension = extensions.get(module);
+    if (!extension) {
+        extension = import(module).then(({ default: create }) => {
+            const context = {
+                createFuture: (promise) => createFuture(promise, undefined),
+                createReadableStream,
+                createWritableStream,
+                getStream: (id) => getStreamOrThrow(id).stream,
+                resourceCounts: () => ({
+                    streams: streams.size,
+                    futures: futures.size,
+                    polls: polls.size,
+                    sockets: tcpSockets.size,
+                }),
+            };
+            return create(context);
+        });
+        extensions.set(module, extension);
+    }
+    return (await extension)(operation, args);
+}
 /**
  * @param {number} call
  * @param {number | null} id
@@ -129,6 +153,8 @@ function handle(call, id, payload) {
         throw uncaughtException;
     }
     switch (call) {
+        case WORKER_EXTENSION_CALL:
+            return callExtension(payload.module, payload.operation, payload.args);
         // Http
         case HTTP_CREATE_REQUEST: {
             const { method, scheme, authority, pathWithQuery, headers, body, connectTimeout, betweenBytesTimeout, firstByteTimeout, } = payload;
@@ -685,10 +711,7 @@ function handle(call, id, payload) {
         case FUTURE_TAKE_VALUE:
             return futureTakeValue(id);
         case FUTURE_SUBSCRIBE: {
-            const { pollState } = futures.get(id);
-            const pollId = ++pollCnt;
-            polls.set(pollId, pollState);
-            return pollId;
+            return createPoll(futures.get(id).pollState);
         }
         case FUTURE_DISPOSE:
             return void futureDispose(id, true);

package/dist/nodejs/io-worker.d.ts

@@ -0,0 +1,28 @@
+import type { InputStream, OutputStream } from "../../types/interfaces/wasi-io-streams.js";
+import type { Pollable } from "../../types/interfaces/wasi-io-poll.js";
+import type { Error as IoError } from "../../types/interfaces/wasi-io-error.js";
+export type { WorkerExtension, WorkerExtensionContext } from "../io/extension.js";
+export type FutureResult<T, E> = {
+    tag: "err";
+    val?: undefined;
+} | {
+    tag: "ok";
+    val: {
+        tag: "ok";
+        val: T;
+    } | {
+        tag: "err";
+        val: E;
+    };
+} | undefined;
+/** Loads a host-selected module once in the existing worker; never accepts a guest module path. */
+export declare function callExtension(module: URL, operation: string, args: unknown[]): unknown;
+export declare function inputStreamId(stream: InputStream): number;
+export declare function outputStreamId(stream: OutputStream): number;
+export declare function inputStreamCreate(id: number): InputStream;
+export declare function outputStreamCreate(id: number): OutputStream;
+export declare function futureSubscribe(id: number, parent: object): Pollable;
+/** T and E are the promise's value and rejection types chosen by the host extension. */
+export declare function futureTakeValue<T, E>(id: number): FutureResult<T, E>;
+export declare function futureDispose(id: number): void;
+export declare function createIoError(message: string): IoError;

package/dist/nodejs/io-worker.js

@@ -0,0 +1,32 @@
+/** Low-level integration with the shared Node IO worker for opt-in host providers. */
+import * as io from "../io/worker-io.js";
+import { WORKER_EXTENSION_CALL, SOCKET_TCP, FUTURE_TAKE_VALUE, FUTURE_SUBSCRIBE, FUTURE_DISPOSE, } from "../io/calls.js";
+/** Loads a host-selected module once in the existing worker; never accepts a guest module path. */
+export function callExtension(module, operation, args) {
+    return io.ioCall(WORKER_EXTENSION_CALL, null, { module: module.href, operation, args });
+}
+export function inputStreamId(stream) {
+    return io.inputStreamId(stream);
+}
+export function outputStreamId(stream) {
+    return io.outputStreamId(stream);
+}
+export function inputStreamCreate(id) {
+    return io.inputStreamCreate(SOCKET_TCP, id);
+}
+export function outputStreamCreate(id) {
+    return io.outputStreamCreate(SOCKET_TCP, id);
+}
+export function futureSubscribe(id, parent) {
+    return io.pollableCreate(io.ioCall(FUTURE_SUBSCRIBE, id, undefined), parent);
+}
+/** T and E are the promise's value and rejection types chosen by the host extension. */
+export function futureTakeValue(id) {
+    return io.ioCall(FUTURE_TAKE_VALUE, id, undefined);
+}
+export function futureDispose(id) {
+    io.ioCall(FUTURE_DISPOSE, id, undefined);
+}
+export function createIoError(message) {
+    return new io.error.Error(message);
+}

package/dist/nodejs/sockets.d.ts

@@ -1,6 +1,7 @@
 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";
 declare class Network implements NetworkNamespace.Network {
     #private;
+    noop(): void;
     static _denyDnsLookup(network?: Network): void;
     static _denyTcp(network?: Network): void;
     static _denyUdp(network?: Network): void;
@@ -12,7 +13,11 @@ export declare const _denyDnsLookup: typeof Network._denyDnsLookup;
 export declare const _denyTcp: typeof Network._denyTcp;
 export declare const _denyUdp: typeof Network._denyUdp;
 export declare const instanceNetwork: typeof InstanceNetworkNamespace;
-export declare const network: typeof NetworkNamespace;
+export declare const network: typeof NetworkNamespace & {
+    networkErrorCode(error: {
+        toDebugString(): string;
+    }): NetworkNamespace.ErrorCode | undefined;
+};
 export declare const ipNameLookup: typeof IpNameLookupNamespace;
 export declare const tcpCreateSocket: typeof TcpCreateSocketNamespace;
 export declare const tcp: typeof TcpNamespace;
@@ -24,7 +29,11 @@ export interface SocketsConfig {
 /** Create socket namespaces with an instance-local network capability. */
 export declare function createSockets(config?: SocketsConfig): {
     instanceNetwork: typeof InstanceNetworkNamespace;
-    network: typeof NetworkNamespace;
+    network: typeof NetworkNamespace & {
+        networkErrorCode(error: {
+            toDebugString(): string;
+        }): NetworkNamespace.ErrorCode | undefined;
+    };
     ipNameLookup: typeof IpNameLookupNamespace;
     tcpCreateSocket: typeof TcpCreateSocketNamespace;
     tcp: typeof TcpNamespace;

package/dist/nodejs/sockets.js

@@ -3,6 +3,8 @@ import { earlyDispose, inputStreamCreate, ioCall, outputStreamCreate, pollableCr
 const symbolDispose = Symbol.dispose || Symbol.for("dispose");
 // Network class privately stores capabilities
 class Network {
+    // Compatibility with the resource placeholder in the bundled WASI 0.2.10 WIT.
+    noop() { }
     #allowDnsLookup = true;
     #allowTcp = true;
     #allowUdp = true;
@@ -51,6 +53,22 @@ export const instanceNetwork = {
 };
 export const network = {
     Network,
+    networkErrorCode(error) {
+        const payload = "payload" in error ? error.payload : undefined;
+        if (typeof payload !== "object" || payload === null || !("code" in payload)) {
+            return undefined;
+        }
+        const codes = {
+            ECONNRESET: "connection-reset",
+            ECONNREFUSED: "connection-refused",
+            ECONNABORTED: "connection-aborted",
+            ETIMEDOUT: "timeout",
+            EACCES: "access-denied",
+            EPERM: "access-denied",
+            ENETUNREACH: "remote-unreachable",
+        };
+        return typeof payload.code === "string" ? codes[payload.code] : undefined;
+    },
 };
 class ResolveAddressStream {
     #id = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytecodealliance/preview2-shim",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "WASI Preview2 shim for JS environments",
   "homepage": "https://github.com/bytecodealliance/jco#readme",
   "bugs": {
@@ -54,6 +54,10 @@
     },
     "./interfaces/*": {
       "types": "./types/interfaces/*.d.ts"
+    },
+    "./io-worker": {
+      "types": "./dist/nodejs/io-worker.d.ts",
+      "node": "./dist/nodejs/io-worker.js"
     }
   },
   "dependencies": {
@@ -67,7 +71,7 @@
     "puppeteer": "^25.1.0",
     "rolldown": "^1.2.4",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json && node scripts/build-worker.mjs",