@volter/browser-wali 0.1.4 → 0.1.6

package/dist/filesystem.d.ts

@@ -1,7 +1,10 @@
+import { WaliProcessDescriptorTable } from "./descriptors.js";
+import { type BrowserProcessFilesystemPolicy } from "@volter/browser-runtime/browser-process-filesystem-policy.js";
 import type { WaliFileSystem, WaliImportHandler, WaliStdin } from "./types.js";
 import type { BrowserProcessPipeHandle } from "./process-bridge.js";
 import type { BrowserFileLockRequest, BrowserFileLockResponse } from "@volter/browser-runtime/browser-file-locks.js";
 export interface WaliSpecialDescriptor {
+    stdio?: 0 | 1 | 2;
     read?(length: number): Uint8Array | bigint;
     write?(value: Uint8Array): bigint;
     poll?(events: number): number;
@@ -11,7 +14,10 @@ export interface WaliSpecialDescriptor {
     browserProcessPipe?: BrowserProcessPipeHandle;
 }
 export interface WaliFileDescriptorOptions {
+    descriptorState?: import("./shared-pipes.js").WaliSharedPipeState;
+    descriptors?: WaliProcessDescriptorTable;
     filesystem?: WaliFileSystem;
+    filesystemPolicy?: BrowserProcessFilesystemPolicy;
     cwd: string;
     stdin: Uint8Array | WaliStdin;
     executablePath?: string;
@@ -30,14 +36,16 @@ export interface WaliFileDescriptorOptions {
 export declare function createStdioAliasRegistry(): Int32Array;
 export declare class WaliFileDescriptorTable {
     private readonly options;
+    readonly descriptors: WaliProcessDescriptorTable;
     private readonly files;
     private readonly specialDescriptors;
     private readonly stdioAliases;
     private readonly descriptorStatusFlags;
     private readonly stdin;
-    private nextFd;
     private nextDescription;
     private cwd;
+    private readonly guestFilesystem;
+    private readonly assertWritable;
     constructor(options: WaliFileDescriptorOptions);
     imports(): Record<string, WaliImportHandler>;
     writeEnvironmentFile(env: Readonly<Record<string, string>>, pid: number): string | undefined;
@@ -47,6 +55,8 @@ export declare class WaliFileDescriptorTable {
     writeForMapping(path: string, offset: number, value: Uint8Array): boolean;
     allocateSpecial(descriptor: WaliSpecialDescriptor, minimum?: number): number;
     exportBrowserProcessPipe(fd: number): BrowserProcessPipeHandle | undefined;
+    copyForFork(memory: () => WebAssembly.Memory): WaliFileDescriptorTable;
+    copyForExec(memory: () => WebAssembly.Memory, stdio?: number[]): WaliFileDescriptorTable;
     currentWorkingDirectory(): string;
     ioctl(fd: number, request: number): bigint | undefined;
     pollDescriptor(fd: number, events: number): number;
@@ -61,6 +71,22 @@ export declare class WaliFileDescriptorTable {
     private open;
     private openAt;
     private openResolved;
+    /**
+     * THE LOWEST DESCRIPTOR NOT CURRENTLY OPEN, which is what POSIX says `open`
+     * returns and `F_DUPFD` returns at or above its argument.
+     *
+     * This used to be a MONOTONIC CURSOR that never rewound, so a closed
+     * descriptor's NUMBER was gone for the life of the process and the table's
+     * maximum bounded a program's LIFETIME opens instead of its concurrent ones.
+     * MEASURED 2026-09-19 in Blender's WALI session, `descriptorMaximum: 9_999`:
+     * `os.stat` in a loop survived 40,000, `open(...).close()` in a loop raised
+     * `[Errno 24] No file descriptors available` after 9,176 with at most one
+     * file open at a time. The session's channel loop then went DEAF -- its
+     * `os.listdir` failed EMFILE forever -- and a call sat unanswered for 1,008
+     * seconds with the program alive and no error anywhere.
+     *
+     * Scanning costs one probe per open descriptor, and a process has a handful.
+     */
     private allocateFd;
     private close;
     private read;
@@ -102,6 +128,9 @@ export declare class WaliFileDescriptorTable {
     private readRecordLock;
     private writeRecordLock;
     private flock;
+    private readonly posixLockedPaths;
+    private readonly lockingOwners;
+    private heldLock;
     private lockOwner;
     private releasePosixLocks;
     private releaseLockOwner;

package/dist/filesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"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"}

package/dist/filesystem.js

@@ -1,5 +1,8 @@
+import { WaliDescriptionRegistry, WaliProcessDescriptorTable } from "./descriptors.js";
+import { createProcessFilesystemMutationGuard } from "@volter/browser-runtime/browser-process-filesystem-policy.js";
 import { BufferedWaliStdin } from "./stdin.js";
 import { readWaliSymlink, resolveWaliSymlinkPath, writeWaliSymlink } from "./symlink.js";
+let reportedDroppedEnvironment = false;
 const AT_FDCWD = -100;
 const O_ACCMODE = 3;
 const O_WRONLY = 1;
@@ -43,18 +46,56 @@ export function createStdioAliasRegistry() {
 }
 export class WaliFileDescriptorTable {
     options;
-    files = new Map();
-    specialDescriptors = new Map();
-    stdioAliases = new Map();
+    descriptors;
+    files;
+    specialDescriptors;
+    stdioAliases;
     descriptorStatusFlags = new Map();
     stdin;
-    nextFd = 3;
     nextDescription = 1;
     cwd;
+    guestFilesystem;
+    assertWritable;
     constructor(options) {
         this.options = options;
+        this.descriptors = options.descriptors ?? new WaliProcessDescriptorTable(new WaliDescriptionRegistry());
+        this.files = this.descriptors.view("file");
+        this.specialDescriptors = this.descriptors.view("special", (value) => value.close?.());
+        this.stdioAliases = this.descriptors.view("stdio");
         this.cwd = normalizePath("/", options.cwd);
+        const fs = options.filesystem;
+        this.assertWritable = options.filesystemPolicy ? createProcessFilesystemMutationGuard({
+            lstatSync: (path) => {
+                if (!fs)
+                    throw errno("ENOSYS");
+                const stat = fs.lstatSync?.(path) ?? fs.statSync(path);
+                return { isSymbolicLink: () => stat.isSymbolicLink?.() === true || readWaliSymlink(fs, path) !== undefined };
+            },
+        }, options.filesystemPolicy) : (path) => path;
+        // Only guest operations use this view. Host imports and environment setup
+        // still own the raw tree; the guest cannot call snapshot replacement.
+        this.guestFilesystem = fs && options.filesystemPolicy ? {
+            existsSync: fs.existsSync.bind(fs), statSync: fs.statSync.bind(fs),
+            ...(fs.lstatSync ? { lstatSync: fs.lstatSync.bind(fs) } : {}),
+            readFileSync: fs.readFileSync.bind(fs), readFile: fs.readFile.bind(fs),
+            readdirSync: fs.readdirSync.bind(fs),
+            writeFileSync: (path, bytes) => fs.writeFileSync(this.assertWritable(path), bytes),
+            mkdirSync: (path, settings) => fs.mkdirSync(this.assertWritable(path), settings),
+            unlinkSync: (path) => fs.unlinkSync(this.assertWritable(path)),
+            rmdirSync: (path) => fs.rmdirSync(this.assertWritable(path)),
+            renameSync: (from, to) => fs.renameSync(this.assertWritable(from), this.assertWritable(to)),
+            ...(fs.chmodSync ? { chmodSync: (path, mode) => fs.chmodSync(this.assertWritable(path), mode) } : {}),
+            ...(fs.utimesSync ? { utimesSync: (path, atime, mtime) => fs.utimesSync(this.assertWritable(path), atime, mtime) } : {}),
+        } : fs;
         this.stdin = "read" in options.stdin ? options.stdin : new BufferedWaliStdin(options.stdin);
+        if (!options.descriptors) {
+            for (const fd of [0, 1, 2])
+                this.specialDescriptors.set(fd, { stdio: fd });
+        }
+        else if (this.descriptors.entries.length === 0 && !options.descriptorState) {
+            for (const fd of [0, 1, 2])
+                this.specialDescriptors.set(fd, { stdio: fd });
+        }
     }
     imports() {
         return {
@@ -115,17 +156,33 @@ export class WaliFileDescriptorTable {
     writeEnvironmentFile(env, pid) {
         if (!this.options.filesystem || Object.keys(env).length === 0)
             return;
-        const path = `/tmp/.browser-runtime-wali-env-${pid}`;
+        // PIDs are local to each WALI worker; several native programs can have
+        // PID 2 while sharing the same host filesystem.
+        const path = `/tmp/.browser-runtime-wali-env-${pid}-${crypto.randomUUID()}`;
         try {
             this.options.filesystem.mkdirSync("/tmp", { recursive: true });
         }
         catch { /* already present */ }
-        const lines = Object.entries(env).map(([name, value]) => {
-            if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) || /[\u0000\r\n]/u.test(value))
-                throw new Error(`Invalid WALI environment entry: ${name}`);
-            return `${name}=${value}`;
-        });
+        // The env file is one `name=value` per line, so it cannot carry a value
+        // with a line break or a name that is not an identifier. A shell's own
+        // parameters (`?`, a newline-valued IFS) reach here through every lane's
+        // spawn; refusing the whole spawn for them is what killed a script's
+        // `spawn("ffmpeg")`. They are dropped and named once.
+        const dropped = [];
+        const lines = [];
+        for (const [name, value] of Object.entries(env)) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) || /[\u0000\r\n]/u.test(value)) {
+                dropped.push(name);
+                continue;
+            }
+            lines.push(`${name}=${value}`);
+        }
+        if (dropped.length > 0 && !reportedDroppedEnvironment) {
+            reportedDroppedEnvironment = true;
+            console.warn(`[WALI] environment entries a process cannot receive were dropped: ${dropped.join(", ")}`);
+        }
         this.options.filesystem.writeFileSync(path, `${lines.join("\n")}\n`);
+        this.options.filesystem.chmodSync?.(path, 0o600);
         return path;
     }
     copyCString(pointer, value, limit) {
@@ -171,6 +228,21 @@ export class WaliFileDescriptorTable {
     exportBrowserProcessPipe(fd) {
         return this.specialDescriptors.get(fd)?.browserProcessPipe;
     }
+    copyForFork(memory) {
+        return new WaliFileDescriptorTable({ ...this.options, cwd: this.cwd, memory, descriptors: this.descriptors.copy() });
+    }
+    copyForExec(memory, stdio) {
+        const descriptors = this.descriptors.copy();
+        if (stdio) {
+            const streams = stdio.map(fd => this.descriptors.get(fd));
+            streams.forEach((description, fd) => {
+                if (description && stdio[fd] !== fd)
+                    descriptors.set(fd, description);
+            });
+        }
+        descriptors.exec();
+        return new WaliFileDescriptorTable({ ...this.options, cwd: this.cwd, memory, descriptors });
+    }
     currentWorkingDirectory() { return this.cwd; }
     ioctl(fd, request) {
         if (!this.hasFd(fd))
@@ -185,7 +257,7 @@ export class WaliFileDescriptorTable {
         if (fd < 0 || !this.hasFd(fd))
             return 0x20;
         const special = this.specialDescriptors.get(fd);
-        if (special)
+        if (special && special.stdio === undefined)
             return special.poll?.(events) ?? 0;
         const stdio = this.stdioFd(fd);
         let returned = 0;
@@ -196,9 +268,9 @@ export class WaliFileDescriptorTable {
         return returned;
     }
     fs() {
-        if (!this.options.filesystem)
+        if (!this.guestFilesystem)
             throw errno("ENOSYS");
-        return this.options.filesystem;
+        return this.guestFilesystem;
     }
     memoryBytes() { return new Uint8Array(this.options.memory().buffer); }
     memoryView() { return new DataView(this.options.memory().buffer); }
@@ -276,6 +348,8 @@ export class WaliFileDescriptorTable {
         }
         const fs = this.fs();
         const exists = fs.existsSync(path);
+        if ((flags & O_ACCMODE) !== 0 || (!exists && (flags & O_CREAT)))
+            this.assertWritable(path);
         if (!exists && !(flags & O_CREAT))
             throw errno("ENOENT");
         if (exists && (flags & O_CREAT) && (flags & O_EXCL))
@@ -301,20 +375,37 @@ export class WaliFileDescriptorTable {
             directory: stat.isDirectory(),
             description: this.nextDescription++,
         });
+        this.descriptors.entries[fd].flags = flags & 0x80000 ? 1 : 0;
         return fd;
     }
+    /**
+     * THE LOWEST DESCRIPTOR NOT CURRENTLY OPEN, which is what POSIX says `open`
+     * returns and `F_DUPFD` returns at or above its argument.
+     *
+     * This used to be a MONOTONIC CURSOR that never rewound, so a closed
+     * descriptor's NUMBER was gone for the life of the process and the table's
+     * maximum bounded a program's LIFETIME opens instead of its concurrent ones.
+     * MEASURED 2026-09-19 in Blender's WALI session, `descriptorMaximum: 9_999`:
+     * `os.stat` in a loop survived 40,000, `open(...).close()` in a loop raised
+     * `[Errno 24] No file descriptors available` after 9,176 with at most one
+     * file open at a time. The session's channel loop then went DEAF -- its
+     * `os.listdir` failed EMFILE forever -- and a call sat unanswered for 1,008
+     * seconds with the program alive and no error anywhere.
+     *
+     * Scanning costs one probe per open descriptor, and a process has a handful.
+     */
     allocateFd(minimum = 3) {
-        this.nextFd = Math.max(this.nextFd, minimum);
-        while (this.files.has(this.nextFd) || this.specialDescriptors.has(this.nextFd)
-            || this.stdioFd(this.nextFd) !== undefined)
-            this.nextFd += 1;
-        if (this.nextFd > (this.options.descriptorMaximum ?? 65_535))
-            throw errno("EMFILE");
-        return this.nextFd++;
+        const maximum = this.options.descriptorMaximum ?? 65_535;
+        for (let fd = Math.max(minimum, 0); fd <= maximum; fd += 1) {
+            // `stdioFd` covers 0-2, this table's own aliases and the shared registry.
+            if (this.descriptors.get(fd) || this.files.has(fd) || this.specialDescriptors.has(fd)
+                || this.stdioFd(fd) !== undefined)
+                continue;
+            return fd;
+        }
+        throw errno("EMFILE");
     }
     close(fd) {
-        if (fd >= 0 && fd <= 2)
-            return 0n;
         if (this.stdioAliases.delete(fd)) {
             this.descriptorStatusFlags.delete(fd);
             this.setSharedStdioAlias(fd, undefined);
@@ -322,7 +413,6 @@ export class WaliFileDescriptorTable {
         }
         const special = this.specialDescriptors.get(fd);
         if (special) {
-            special.close?.();
             this.specialDescriptors.delete(fd);
             return 0n;
         }
@@ -366,8 +456,10 @@ export class WaliFileDescriptorTable {
                 throw errno("EISDIR");
             if ((file.flags & O_ACCMODE) === O_WRONLY)
                 throw errno("EBADF");
-            const content = this.fs().readFileSync(file.path);
-            const chunk = content.subarray(file.position, file.position + length);
+            const fs = this.fs();
+            const chunk = fs.readRangeSync
+                ? fs.readRangeSync(file.path, file.position, length)
+                : fs.readFileSync(file.path).subarray(file.position, file.position + length);
             this.copyIn(pointer, chunk);
             file.position += chunk.byteLength;
             return BigInt(chunk.byteLength);
@@ -392,14 +484,22 @@ export class WaliFileDescriptorTable {
                 throw errno("EISDIR");
             if ((file.flags & O_ACCMODE) === 0)
                 throw errno("EBADF");
-            const current = this.fs().readFileSync(file.path);
+            const fs = this.fs();
+            if (fs.writeRangeSync) {
+                if (file.flags & O_APPEND)
+                    file.position = fs.statSync(file.path).size;
+                fs.writeRangeSync(file.path, file.position, chunk);
+                file.position += chunk.byteLength;
+                return BigInt(chunk.byteLength);
+            }
+            const current = fs.readFileSync(file.path);
             if (file.flags & O_APPEND)
                 file.position = current.byteLength;
             const size = Math.max(current.byteLength, file.position + chunk.byteLength);
             const next = new Uint8Array(size);
             next.set(current);
             next.set(chunk, file.position);
-            this.fs().writeFileSync(file.path, next);
+            fs.writeFileSync(file.path, next);
             file.position += chunk.byteLength;
             return BigInt(chunk.byteLength);
         }
@@ -843,35 +943,47 @@ export class WaliFileDescriptorTable {
                 return -9n;
             if (next === fd)
                 return BigInt(next);
-            this.stdioAliases.set(next, stdio);
+            this.descriptors.set(next, this.descriptors.get(fd));
             this.descriptorStatusFlags.set(next, this.statusFlags(fd));
             this.setSharedStdioAlias(next, stdio);
             return BigInt(next);
         }
-        const file = this.files.get(fd);
-        if (!file)
+        if (!this.descriptors.get(fd))
             return -9n;
         const next = target ?? this.allocateFd(minimum);
         if (next < 0 || next > maximum)
             return -9n;
-        this.files.set(next, { ...file });
+        if (next === fd)
+            return BigInt(next);
+        this.close(next);
+        this.descriptors.set(next, this.descriptors.get(fd));
         return BigInt(next);
     }
     fcntl(fd, command, argument) {
         if (!this.hasFd(fd))
             return -9n;
         const special = this.specialDescriptors.get(fd);
-        if (special) {
+        if (special && special.stdio === undefined && command !== 1 && command !== 2) {
             if (command === 0 || command === 1030) {
                 return special.duplicate?.(Math.max(argument, 3), command === 1030) ?? -22n;
             }
             return special.fcntl?.(command, argument) ?? -22n;
         }
         const file = this.files.get(fd);
-        if (command === 0 || command === 1030)
-            return this.dup(fd, undefined, Math.max(argument, 3));
-        if (command === 1 || command === 2)
+        if (command === 0 || command === 1030) {
+            const result = this.dup(fd, undefined, Math.max(argument, 3));
+            if (result >= 0n && command === 1030)
+                this.descriptors.entries[Number(result)].flags = 1;
+            return result;
+        }
+        if (command === 1)
+            return BigInt(this.descriptors.entries[fd]?.flags ?? 0);
+        if (command === 2) {
+            const entry = this.descriptors.entries[fd];
+            if (entry)
+                entry.flags = argument & 1;
             return 0n;
+        }
         if (command === 3)
             return BigInt(this.statusFlags(fd));
         if (command === 4) {
@@ -920,10 +1032,13 @@ export class WaliFileDescriptorTable {
                 return 0n;
             }
             const blocking = command === F_SETLKW || command === F_OFD_SETLKW;
-            return BigInt(client.request({
+            const result = client.request({
                 operation: "set", owner, namespace, path: file.path, range: requested.range,
                 mode: requested.mode, pid: this.options.pid ?? 1, blocking,
-            }).result);
+            }).result;
+            if (result >= 0)
+                this.heldLock(namespace, owner, file.path);
+            return BigInt(result);
         }
         catch (error) {
             return negativeErrno(error);
@@ -980,10 +1095,24 @@ export class WaliFileDescriptorTable {
         const mode = operation & LOCK_EX ? "write" : operation & LOCK_SH ? "read" : undefined;
         if (!mode || operation & ~(LOCK_SH | LOCK_EX | LOCK_NB | LOCK_UN))
             return -22n;
-        return BigInt(client.request({
+        const result = client.request({
             operation: "set", owner, namespace: "flock", path: file.path, range: { start: 0 },
             mode, pid: this.options.pid ?? 1, blocking: !(operation & LOCK_NB),
-        }).result);
+        }).result;
+        if (result >= 0)
+            this.heldLock("flock", owner, file.path);
+        return BigInt(result);
+    }
+    // What this process has locked. A close releases only these: each release
+    // is a synchronous request to the page's lock table, and a close of a file
+    // never locked (git closes hundreds) paid three of them.
+    posixLockedPaths = new Set();
+    lockingOwners = new Set();
+    heldLock(namespace, owner, path) {
+        if (namespace === "posix")
+            this.posixLockedPaths.add(path);
+        else
+            this.lockingOwners.add(owner);
     }
     lockOwner(namespace, file) {
         const base = this.options.lockOwner;
@@ -993,14 +1122,14 @@ export class WaliFileDescriptorTable {
     }
     releasePosixLocks(path) {
         const owner = this.options.lockOwner ? `${this.options.lockOwner}:posix` : undefined;
-        if (!owner || !this.options.fileLocks)
+        if (!owner || !this.options.fileLocks || !this.posixLockedPaths.delete(path))
             return;
         this.options.fileLocks.request({
             operation: "unlock", owner, namespace: "posix", path, range: { start: 0 },
         });
     }
     releaseLockOwner(owner) {
-        if (owner && this.options.fileLocks)
+        if (owner && this.options.fileLocks && this.lockingOwners.delete(owner))
             this.options.fileLocks.request({ operation: "release-owner", owner });
     }
     poll(pointer, count, timeout) {
@@ -1029,17 +1158,18 @@ export class WaliFileDescriptorTable {
         return BigInt(scan());
     }
     hasFd(fd) {
-        return (fd >= 0 && fd <= 2) || this.stdioAliases.has(fd)
-            || this.files.has(fd) || this.specialDescriptors.has(fd);
+        return this.descriptors.get(fd) !== undefined;
     }
     stdioFd(fd) {
-        if (fd >= 0 && fd <= 2)
-            return fd;
-        const local = this.stdioAliases.get(fd);
-        if (local !== undefined)
-            return local;
-        const shared = this.options.stdioAliasRegistry?.[fd];
-        return shared === 0 || shared === 1 || shared === 2 ? shared : undefined;
+        if (this.options.descriptorState) {
+            const state = this.options.descriptorState;
+            if (fd < 0 || fd >= 65_536)
+                return;
+            const id = Atomics.load(new Int32Array(state.table), fd);
+            const stream = Atomics.load(new Int32Array(state.descriptions), id * 3 + 2) - 1;
+            return stream >= 0 && stream <= 2 ? stream : undefined;
+        }
+        return this.specialDescriptors.get(fd)?.stdio;
     }
     setSharedStdioAlias(fd, target) {
         if (fd < 0 || fd >= (this.options.stdioAliasRegistry?.length ?? 0))