wasm-platform-kit 0.0.0-stage → 0.2.0

package/assets/wasi/io.js

@@ -0,0 +1,366 @@
+import { checkedU64AsNumber } from "./common.js";
+let id = 0;
+const symbolDispose = Symbol.dispose || Symbol.for("dispose");
+const checkedLength = (len, name = "length") => checkedU64AsNumber(len, name);
+function closed() {
+    throw { tag: "closed" };
+}
+class IoError extends Error {
+    toDebugString() {
+        return this.message;
+    }
+}
+export const ioErrorCreate = (message) => new IoError(message);
+class InputStream {
+    id;
+    handler;
+    #open = true;
+    #children = new Set();
+    static _create(handler) {
+        const stream = new InputStream();
+        if (!handler) {
+            console.trace("no handler");
+        }
+        stream.id = ++id;
+        stream.handler = handler;
+        return stream;
+    }
+    read(len) {
+        checkedLength(len);
+        if (!this.#open) {
+            closed();
+        }
+        if (this.handler.read) {
+            return this.handler.read.call(this, len);
+        }
+        return this.handler.blockingRead.call(this, len);
+    }
+    blockingRead(len) {
+        checkedLength(len);
+        if (!this.#open) {
+            closed();
+        }
+        return this.handler.blockingRead.call(this, len);
+    }
+    skip(len) {
+        checkedLength(len);
+        if (!this.#open) {
+            closed();
+        }
+        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) {
+        checkedLength(len);
+        if (!this.#open) {
+            closed();
+        }
+        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.#open) {
+            return pollableCreate();
+        }
+        const pollable = this.handler.subscribe
+            ? this.handler.subscribe.call(this)
+            : pollableCreate();
+        if (pollable instanceof Pollable) {
+            this.#children.add(pollable);
+            pollable._onDispose(() => this.#children.delete(pollable));
+        }
+        return pollable;
+    }
+    [symbolDispose]() {
+        if (!this.#open) {
+            return;
+        }
+        this.#open = false;
+        for (const child of this.#children) {
+            child._invalidate();
+        }
+        this.#children.clear();
+        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;
+    #permit = 0n;
+    #children = new Set();
+    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) {
+            closed();
+        }
+        if (this.handler.checkWrite) {
+            const permit = this.handler.checkWrite.call(this);
+            checkedLength(permit, "write permit");
+            this.#permit = permit;
+            return permit;
+        }
+        this.#permit = 1000000n;
+        return this.#permit;
+    }
+    write(buf) {
+        if (!this.open) {
+            closed();
+        }
+        if (BigInt(buf.byteLength) > this.#permit) {
+            throw new Error("write exceeds the permit returned by checkWrite");
+        }
+        this.#permit -= BigInt(buf.byteLength);
+        this.handler.write.call(this, buf);
+    }
+    blockingWriteAndFlush(buf) {
+        if (!this.open) {
+            closed();
+        }
+        if (buf.byteLength > 4096) {
+            throw new RangeError("blockingWriteAndFlush accepts at most 4096 bytes");
+        }
+        if (this.handler.blockingWriteAndFlush) {
+            return this.handler.blockingWriteAndFlush.call(this, buf);
+        }
+        this.handler.write.call(this, buf);
+        if (this.handler.blockingFlush) {
+            this.handler.blockingFlush.call(this);
+        }
+        else {
+            this.handler.flush?.call(this);
+        }
+    }
+    flush() {
+        if (!this.open) {
+            closed();
+        }
+        this.#permit = 0n;
+        if (this.handler.flush) {
+            this.handler.flush.call(this);
+        }
+    }
+    blockingFlush() {
+        if (!this.open) {
+            closed();
+        }
+        if (this.handler.blockingFlush) {
+            this.handler.blockingFlush.call(this);
+        }
+        else {
+            this.handler.flush?.call(this);
+        }
+    }
+    writeZeroes(len) {
+        const length = checkedLength(len);
+        if (len > this.#permit) {
+            throw new Error("write exceeds the permit returned by checkWrite");
+        }
+        this.write.call(this, new Uint8Array(length));
+    }
+    blockingWriteZeroesAndFlush(len) {
+        const length = checkedLength(len);
+        if (length > 4096) {
+            throw new RangeError("blockingWriteZeroesAndFlush accepts at most 4096 bytes");
+        }
+        this.blockingWriteAndFlush.call(this, new Uint8Array(length));
+    }
+    splice(src, len) {
+        const spliceLen = Math.min(checkedLength(len), Number(this.checkWrite.call(this)));
+        const bytes = src.read(BigInt(spliceLen));
+        this.write.call(this, bytes);
+        return BigInt(bytes.byteLength);
+    }
+    blockingSplice(src, len) {
+        const spliceLen = Math.min(checkedLength(len), Number(this.checkWrite.call(this)));
+        const bytes = src.blockingRead(BigInt(spliceLen));
+        this.write.call(this, bytes);
+        return BigInt(bytes.byteLength);
+    }
+    subscribe() {
+        if (!this.open) {
+            return pollableCreate();
+        }
+        const pollable = this.handler.subscribe
+            ? this.handler.subscribe.call(this)
+            : pollableCreate();
+        if (pollable instanceof Pollable) {
+            this.#children.add(pollable);
+            pollable._onDispose(() => this.#children.delete(pollable));
+        }
+        return pollable;
+    }
+    [symbolDispose]() {
+        if (!this.open) {
+            return;
+        }
+        this.open = false;
+        this.#permit = 0n;
+        for (const child of this.#children) {
+            child._invalidate();
+        }
+        this.#children.clear();
+        this.handler.drop?.call(this);
+    }
+}
+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 {
+    #source = { ready: () => true, wait: () => Promise.resolve() };
+    #invalid = false;
+    #disposed = false;
+    #wait = null;
+    #disposeCallbacks = [];
+    #wakeUnusable;
+    #unusable = new Promise((resolve) => (this.#wakeUnusable = resolve));
+    static _create(source) {
+        const pollable = new Pollable();
+        if (source instanceof Promise) {
+            let ready = false;
+            const wait = source.then(() => {
+                ready = true;
+            }, () => {
+                ready = true;
+            });
+            pollable.#source = { ready: () => ready, wait: () => wait };
+        }
+        else if (source) {
+            pollable.#source = source;
+        }
+        return pollable;
+    }
+    ready() {
+        this.#assertUsable();
+        return this.#source.ready();
+    }
+    block() {
+        this.#assertUsable();
+        if (this.#source.ready()) {
+            return Promise.resolve();
+        }
+        // Deduplicate simultaneous waiters, but discard a completed wait so a
+        // level-triggered source can be polled again after its event is consumed.
+        if (!this.#wait) {
+            this.#wait = Promise.race([
+                Promise.resolve(this.#source.wait()),
+                this.#unusable.then(() => this.#assertUsable()),
+            ]).finally(() => {
+                this.#wait = null;
+            });
+        }
+        return this.#wait;
+    }
+    _onDispose(callback) {
+        if (this.#disposed) {
+            callback();
+        }
+        else {
+            this.#disposeCallbacks.push(callback);
+        }
+    }
+    _invalidate() {
+        if (this.#invalid || this.#disposed) {
+            return;
+        }
+        this.#invalid = true;
+        this.#wakeUnusable();
+    }
+    #assertUsable() {
+        if (this.#disposed) {
+            throw new Error("pollable has been disposed");
+        }
+        if (this.#invalid) {
+            throw new Error("pollable's parent resource has been disposed");
+        }
+    }
+    [symbolDispose]() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#wakeUnusable();
+        for (const callback of this.#disposeCallbacks.splice(0)) {
+            callback();
+        }
+    }
+}
+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) {
+        // Browser guests commonly use an immediately-ready timer alongside an
+        // asynchronous Web API pollable. Yield a host task so Fetch, timers, and
+        // other event sources can progress instead of starving in a sync loop.
+        return new Promise((resolve) => setTimeout(() => {
+            const result = [];
+            for (let i = 0; i < list.length; i++) {
+                if (list[i].ready()) {
+                    result.push(i);
+                }
+            }
+            resolve(new Uint32Array(result));
+        }, 0));
+    }
+    // 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((pollable) => pollable.block())).then(() => {
+        const result = [];
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].ready()) {
+                result.push(i);
+            }
+        }
+        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/assets/wasi/opfs-filesystem.d.ts

@@ -0,0 +1,52 @@
+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, waiting for earlier automatic and explicit writes to close. */
+    flush(): Promise<void>;
+    /** Stop automatic persistence and wait for the final flush before releasing the backing store. */
+    dispose(): Promise<void>;
+}

package/assets/wasi/opfs-filesystem.js

@@ -0,0 +1,262 @@
+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;
+    #flushPromise = Promise.resolve();
+    #disposal;
+    #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(() => {
+            if (!this.#flushScheduled) {
+                return;
+            }
+            this.#flushScheduled = false;
+            void this.flush();
+        });
+    }
+    /** Persist every loaded root, waiting for earlier automatic and explicit writes to close. */
+    flush() {
+        // This flush includes queued mutations; don't start another automatic pass for them.
+        this.#flushScheduled = false;
+        const flushed = this.#flushPromise
+            .catch(() => { })
+            .then(async () => {
+            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);
+            }));
+        });
+        this.#flushPromise = flushed;
+        return flushed;
+    }
+    /** Stop automatic persistence and wait for the final flush before releasing the backing store. */
+    dispose() {
+        if (!this.#disposal) {
+            this.#unsubscribeTouch();
+            this.#disposal = this.flush();
+        }
+        return this.#disposal;
+    }
+}

package/assets/wasi/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;