@volter/tabnode 0.4.0 → 0.5.0

package/src/native-stream-owner.ts

@@ -0,0 +1,317 @@
+/** Host-owned native handles. Node's JS socket and IPC libraries stay in the guest. */
+import { TCP, TCPConnectWrap, type SockName } from './node-lib/binding/tcp_wrap';
+import { Pipe, PipeConnectWrap } from './node-lib/binding/pipe_wrap';
+import { LibuvStreamWrap, WriteWrap, ShutdownWrap, streamBaseState, kReadBytesOrError, kArrayBufferOffset } from './node-lib/binding/stream_wrap';
+import { __adoptHandle } from './node-lib/binding/handles';
+import { UV_EBADF, UV_ECANCELED, UV_EINVAL, UV_ENOBUFS, UV_ENOTSUP, UV_EPIPE, UV_EMFILE, UV_EBUSY, UV_EALREADY } from './node-lib/binding/uv';
+
+export interface NativeStreamDescriptor { id: number; kind: 'tcp' | 'pipe'; type: number }
+export interface NativeStreamLimits {
+  maxHandles: number;
+  maxReadChunkBytes: number;
+  maxQueuedBytes: number;
+  /** Per connection, like maxQueuedBytes; includes unread IPC descriptor copies. */
+  maxQueuedHandles: number;
+  maxPendingWriteBytes: number;
+}
+export type NativeStreamEvent =
+  | { type: 'closed' }
+  | { type: 'read'; id: number; status: number; bytes?: Uint8Array; handle?: NativeStreamDescriptor }
+  | { type: 'connection'; id: number; status: number; handle?: NativeStreamDescriptor }
+  | { type: 'connect' | 'shutdown' | 'close'; id: number; request: number; status: number };
+export type NativeStreamOperation =
+  | { operation: 'create'; kind: 'tcp' | 'pipe'; type: number }
+  | { operation: 'fdType'; fd: number }
+  | { operation: 'pair'; id: number; peer: number }
+  | { operation: 'duplicate'; id: number }
+  | { operation: 'bind'; id: number; address: string; port?: number; ipv6?: boolean; flags?: number }
+  | { operation: 'listen'; id: number; backlog: number }
+  | { operation: 'connect'; id: number; request: number; address: string; port?: number; ipv6?: boolean }
+  | { operation: 'open'; id: number; fd: number }
+  | { operation: 'readStart' | 'readStop' | 'ref' | 'unref' | 'getsockname' | 'getpeername'; id: number }
+  | { operation: 'shutdown' | 'close' | 'reset'; id: number; request: number };
+export interface NativeStreamReply { status: number; handle?: NativeStreamDescriptor; handleType?: 'TCP' | 'PIPE'; address?: Partial<SockName> }
+export interface NativeStreamTransport {
+  readonly limits: Readonly<NativeStreamLimits>;
+  call(operation: NativeStreamOperation): NativeStreamReply;
+  write(id: number, bytes: Uint8Array, handle?: number): Promise<number>;
+  onEvent(listener: (event: NativeStreamEvent) => void): () => void;
+}
+
+type NativeHandle = TCP | Pipe;
+interface Entry { handle: NativeHandle; descriptor: NativeStreamDescriptor; buffer?: Uint8Array }
+const scopes = new WeakMap<LibuvStreamWrap, NativeStreamScope>();
+
+/**
+ * One capability namespace per worker. Only the trusted host can inherit a
+ * descriptor from another scope; wire operations can name this scope's IDs only.
+ */
+export class NativeStreamScope {
+  private readonly entries = new Map<number, Entry>();
+  private readonly descriptors = new Map<number, number>();
+  private readonly writes = new Map<number, (status: number) => void>();
+  private readonly connects = new Map<number, number>();
+  private nextId = 1;
+  private pendingWriteBytes = 0;
+  private disposed = false;
+  private readonly limits: Readonly<NativeStreamLimits>;
+
+  constructor(limits: NativeStreamLimits, private readonly emit: (event: NativeStreamEvent) => void) {
+    if ([limits.maxHandles, limits.maxReadChunkBytes, limits.maxQueuedBytes, limits.maxQueuedHandles, limits.maxPendingWriteBytes].some(value => !Number.isSafeInteger(value) || value < 1)
+      || limits.maxReadChunkBytes > 0x7fffffff
+      || limits.maxReadChunkBytes > limits.maxQueuedBytes
+      || limits.maxReadChunkBytes > limits.maxPendingWriteBytes) throw new Error('Invalid native stream resource limits.');
+    this.limits = Object.freeze({ ...limits });
+  }
+
+  private entry(id: number): Entry | undefined {
+    return this.disposed ? undefined : this.entries.get(id);
+  }
+
+  private publish(event: NativeStreamEvent): void {
+    if (this.disposed) return;
+    try { this.emit(event); }
+    catch (cause) {
+      try { this.dispose(); } catch (cleanup) { throw new AggregateError([cause, cleanup], 'Native stream event delivery and cleanup failed.'); }
+      throw cause;
+    }
+  }
+
+  private claim(handle: NativeHandle): NativeStreamDescriptor | undefined {
+    if (this.disposed || !Number.isSafeInteger(this.nextId) || this.entries.size >= this.limits.maxHandles || scopes.has(handle)) return undefined;
+    const descriptor: NativeStreamDescriptor = { id: this.nextId++, kind: handle instanceof TCP ? 'tcp' : 'pipe', type: handle.type };
+    const entry: Entry = { handle, descriptor };
+    this.entries.set(descriptor.id, entry);
+    scopes.set(handle, this);
+    // The scope, not the currently executing guest in the owner realm, owns it.
+    __adoptHandle(handle, null);
+    handle.onconnection = (status: number, accepted: NativeHandle) => {
+      const incoming = status === 0 ? this.claim(accepted) : undefined;
+      if (status === 0 && !incoming) accepted.close();
+      this.publish({ type: 'connection', id: descriptor.id, status: status || (incoming ? 0 : UV_EMFILE), ...(incoming ? { handle: incoming } : {}) });
+    };
+    handle.onread = buffer => {
+      const count = streamBaseState[kReadBytesOrError];
+      const offset = streamBaseState[kArrayBufferOffset];
+      handle.readStop(); // One read credit; the receiver explicitly replenishes it.
+      const sent = handle.pendingHandle;
+      handle.pendingHandle = null;
+      let incoming: NativeStreamDescriptor | undefined;
+      if (sent != null) {
+        if ((sent instanceof TCP || sent instanceof Pipe) && !sent.listening) incoming = this.claim(sent);
+        if (!incoming) {
+          if (sent instanceof LibuvStreamWrap && !scopes.has(sent) && !(sent as NativeHandle).listening) sent.close();
+          this.publish({ type: 'read', id: descriptor.id, status: UV_ENOTSUP });
+          this.close(descriptor.id);
+          return;
+        }
+      }
+      const bytes = count > 0
+        ? (buffer ? new Uint8Array(buffer, offset, count) : entry.buffer!.subarray(0, count)).slice()
+        : undefined;
+      this.publish({ type: 'read', id: descriptor.id, status: count,
+        ...(bytes ? { bytes } : {}), ...(incoming ? { handle: incoming } : {}) });
+    };
+    return { ...descriptor };
+  }
+
+  /** Synchronous operations return libuv status; completions use the event door. */
+  call(operation: NativeStreamOperation): NativeStreamReply {
+    if (this.disposed) return { status: UV_EBADF };
+    if (operation.operation === 'fdType') {
+      if (!Number.isInteger(operation.fd) || operation.fd < 0) return { status: UV_EINVAL };
+      const id = this.descriptors.get(operation.fd);
+      const entry = id === undefined ? undefined : this.entry(id);
+      return entry ? { status: 0, handleType: entry.descriptor.kind === 'tcp' ? 'TCP' : 'PIPE' } : { status: UV_EBADF };
+    }
+    if (operation.operation === 'create') {
+      if (this.entries.size >= this.limits.maxHandles) return { status: UV_EMFILE };
+      if ((operation.kind !== 'tcp' && operation.kind !== 'pipe')
+        || !Number.isInteger(operation.type) || operation.type < 0 || operation.type > (operation.kind === 'pipe' ? 2 : 1)) return { status: UV_EINVAL };
+      const handle = operation.kind === 'tcp' ? new TCP(operation.type) : new Pipe(operation.type);
+      const descriptor = this.claim(handle);
+      if (!descriptor) { handle.close(); return { status: UV_EMFILE }; }
+      return { status: 0, handle: descriptor };
+    }
+    const entry = this.entry(operation.id);
+    if (!entry) return { status: UV_EBADF };
+    const handle = entry.handle;
+    switch (operation.operation) {
+      case 'duplicate': {
+        if (!handle.peer || handle.listening) return { status: UV_ENOTSUP };
+        if (this.entries.size >= this.limits.maxHandles) return { status: UV_EMFILE };
+        const copy = handle.duplicate();
+        const descriptor = this.claim(copy);
+        if (!descriptor) { copy.close(); return { status: UV_EMFILE }; }
+        return { status: 0, handle: descriptor };
+      }
+      case 'pair': {
+        const other = this.entry(operation.peer)?.handle;
+        if (!other || handle.peer || other.peer || handle.listening || other.listening || other === handle) return { status: UV_EINVAL };
+        LibuvStreamWrap.pair(handle, other);
+        return { status: 0 };
+      }
+      case 'bind': {
+        if (typeof operation.address !== 'string') return { status: UV_EINVAL };
+        if (handle instanceof Pipe) return { status: handle.bind(operation.address) };
+        if (!Number.isInteger(operation.port) || operation.port! < 0 || operation.port! > 65535) return { status: UV_EINVAL };
+        return { status: operation.ipv6 ? handle.bind6(operation.address, operation.port!, operation.flags) : handle.bind(operation.address, operation.port!, operation.flags) };
+      }
+      case 'listen': return { status: Number.isInteger(operation.backlog) && operation.backlog >= 0 ? handle.listen(operation.backlog) : UV_EINVAL };
+      case 'connect': {
+        if (this.connects.has(operation.id)) return { status: UV_EALREADY };
+        if (typeof operation.address !== 'string' || !Number.isSafeInteger(operation.request) || operation.request < 1) return { status: UV_EINVAL };
+        if (handle instanceof TCP && (!Number.isInteger(operation.port) || operation.port! < 1 || operation.port! > 65535)) return { status: UV_EINVAL };
+        this.connects.set(operation.id, operation.request);
+        const request = handle instanceof TCP ? new TCPConnectWrap() : new PipeConnectWrap();
+        request.oncomplete = status => {
+          if (this.connects.get(operation.id) !== operation.request) return;
+          this.connects.delete(operation.id);
+          this.publish({ type: 'connect', id: operation.id, request: operation.request, status });
+        };
+        const status = handle instanceof TCP
+          ? operation.ipv6 ? handle.connect6(request as TCPConnectWrap, operation.address, operation.port!) : handle.connect(request as TCPConnectWrap, operation.address, operation.port!)
+          : handle.connect(request as PipeConnectWrap, operation.address);
+        if (status !== 0) this.connects.delete(operation.id);
+        return { status };
+      }
+      case 'open': {
+        const inherited = this.descriptors.get(operation.fd);
+        const held = inherited === undefined ? undefined : this.entry(inherited);
+        if (!held || held.descriptor.kind !== entry.descriptor.kind || handle.peer || handle.listening) return { status: UV_EBADF };
+        if (held !== entry) {
+          if (handle instanceof TCP && held.handle instanceof TCP) {
+            const local: Partial<SockName> = {}, remote: Partial<SockName> = {};
+            if (held.handle.getsockname(local) === 0 && held.handle.getpeername(remote) === 0) handle.adoptNames(local as SockName, remote as SockName);
+          }
+          handle.takeOverFrom(held.handle);
+          this.entries.delete(inherited!);
+          scopes.delete(held.handle);
+          held.handle.close();
+          this.descriptors.set(operation.fd, operation.id);
+        }
+        return { status: 0 };
+      }
+      case 'readStart':
+        entry.buffer ??= new Uint8Array(this.limits.maxReadChunkBytes);
+        handle.useUserBuffer(entry.buffer);
+        return { status: handle.readStart() };
+      case 'readStop': return { status: handle.readStop() };
+      case 'ref': handle.ref(); return { status: 0 };
+      case 'unref': handle.unref(); return { status: 0 };
+      case 'getsockname': case 'getpeername': {
+        if (!(handle instanceof TCP)) return { status: UV_ENOTSUP };
+        const address: Partial<SockName> = {};
+        const status = handle[operation.operation](address);
+        return { status, ...(status === 0 ? { address } : {}) };
+      }
+      case 'shutdown': {
+        if (!Number.isSafeInteger(operation.request) || operation.request < 1) return { status: UV_EINVAL };
+        if (this.writes.has(operation.id)) return { status: UV_EBUSY };
+        const request = new ShutdownWrap();
+        request.oncomplete = status => this.publish({ type: 'shutdown', id: operation.id, request: operation.request, status });
+        return { status: handle.shutdown(request) };
+      }
+      case 'reset':
+        if (!Number.isSafeInteger(operation.request) || operation.request < 1) return { status: UV_EINVAL };
+        if (!(handle instanceof TCP)) return { status: UV_ENOTSUP };
+        this.writes.get(operation.id)?.(UV_ECANCELED);
+        return this.close(operation.id, operation.request, true);
+      case 'close':
+        if (!Number.isSafeInteger(operation.request) || operation.request < 1) return { status: UV_EINVAL };
+        return this.close(operation.id, operation.request);
+    }
+  }
+
+  /**
+   * Transport chunks are bounded and serialized per handle. Waiting for native
+   * receive capacity retains at most one chunk per writer, within the scope's
+   * explicit aggregate ceiling. No polling or copying a whole guest write.
+   */
+  write(id: number, bytes: Uint8Array, sentId?: number): Promise<number> {
+    const handle = this.entry(id)?.handle;
+    if (!handle) return Promise.resolve(UV_EBADF);
+    if (this.writes.has(id)) return Promise.resolve(UV_EBUSY);
+    if (bytes.byteLength > this.limits.maxReadChunkBytes
+      || this.pendingWriteBytes + bytes.byteLength > this.limits.maxPendingWriteBytes) return Promise.resolve(UV_ENOBUFS);
+    const sent = sentId === undefined ? undefined : this.entry(sentId)?.handle;
+    if (sentId !== undefined && !sent) return Promise.resolve(UV_EBADF);
+    if (sent && (!(handle instanceof Pipe) || !sent.peer || sent.listening || bytes.byteLength === 0)) return Promise.resolve(UV_ENOTSUP);
+    // Retain the descriptor while capacity is unavailable; the sender can close
+    // its original after submitting the write without invalidating this copy.
+    const owned = new Uint8Array(bytes.byteLength);
+    owned.set(bytes);
+    const retained = sent?.duplicate();
+    if (retained) __adoptHandle(retained, null);
+    this.pendingWriteBytes += owned.byteLength;
+    return new Promise((resolve, reject) => {
+      let ended = false;
+      let unsubscribe = (): void => {};
+      const finish = (status: number, failure?: unknown): void => {
+        if (ended) return;
+        ended = true;
+        unsubscribe();
+        this.writes.delete(id);
+        this.pendingWriteBytes -= owned.byteLength;
+        try { retained?.close(); }
+        catch (cause) { reject(cause); return; }
+        if (failure !== undefined) reject(failure);
+        else resolve(status);
+      };
+      const attempt = (): void => {
+        if (ended) return;
+        if (handle.closed || this.disposed) { finish(UV_ECANCELED); return; }
+        if (!handle.peer) { finish(UV_EPIPE); return; }
+        if (handle.peerQueuedBytes + owned.byteLength > this.limits.maxQueuedBytes) return;
+        // A one-byte IPC message can carry an entire descriptor. Byte credit
+        // alone does not meaningfully bound unread SCM_RIGHTS copies.
+        if (retained && handle.peerQueuedHandles >= this.limits.maxQueuedHandles) return;
+        try { finish(handle.writeBuffer(new WriteWrap(), owned, retained)); }
+        catch (cause) { finish(UV_ECANCELED, cause); }
+      };
+      this.writes.set(id, finish);
+      unsubscribe = handle.onPeerReadCapacity(attempt);
+      attempt();
+    });
+  }
+
+  /** Trusted parent-to-child inheritance; this is deliberately absent from call(). */
+  inherit(fd: number, source: NativeStreamScope, id: number): NativeStreamReply {
+    if (this.disposed || !Number.isInteger(fd) || fd < 0 || this.descriptors.has(fd)) return { status: UV_EINVAL };
+    if (this.entries.size >= this.limits.maxHandles) return { status: UV_EMFILE };
+    const handle = source.entry(id)?.handle;
+    if (!handle) return { status: UV_EBADF };
+    if (handle.listening || !handle.peer) return { status: UV_ENOTSUP };
+    const copy = handle.duplicate();
+    const descriptor = this.claim(copy);
+    if (!descriptor) { copy.close(); return { status: UV_EMFILE }; }
+    this.descriptors.set(fd, descriptor.id);
+    return { status: 0, handle: descriptor };
+  }
+
+  private close(id: number, request?: number, reset = false): NativeStreamReply {
+    const entry = this.entries.get(id);
+    if (!entry) return { status: UV_EBADF };
+    this.writes.get(id)?.(UV_ECANCELED);
+    const connecting = this.connects.get(id);
+    this.connects.delete(id);
+    if (connecting !== undefined) this.publish({ type: 'connect', id, request: connecting, status: UV_ECANCELED });
+    this.entries.delete(id);
+    scopes.delete(entry.handle);
+    for (const [fd, held] of this.descriptors) if (held === id) this.descriptors.delete(fd);
+    const complete = request === undefined ? undefined : () => this.publish({ type: 'close', id, request, status: 0 });
+    if (reset) (entry.handle as TCP).reset(complete);
+    else entry.handle.close(complete);
+    return { status: 0 };
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    const failures: unknown[] = [];
+    for (const id of [...this.entries.keys()]) {
+      try { this.close(id); } catch (cause) { failures.push(cause); }
+    }
+    if (failures.length) throw new AggregateError(failures, 'Native stream scope cleanup failed.');
+  }
+}

package/src/node-lib/binding/duplex_stream.ts

@@ -0,0 +1,95 @@
+/** A Node Duplex as a libuv stream handle. Node still owns both socket APIs. */
+import { LibuvStreamWrap, type WriteWrap, type ShutdownWrap, streamBaseState, kBytesWritten, kLastWriteWasAsync } from './stream_wrap';
+import { UV_EBADF, UV_ECONNRESET, UV_ENOTSUP } from './uv';
+
+interface DuplexTransport {
+  write(chunk: Uint8Array, callback: (error?: Error | null) => void): boolean;
+  end(callback: () => void): void;
+  pause(): void;
+  resume(): void;
+  destroy(): void;
+  on(event: string, listener: (...args: any[]) => void): void;
+}
+
+/** No listener or network address is allocated for this internal connection. */
+export class DuplexStreamHandle extends LibuvStreamWrap {
+  private pendingWrite?: (status: number) => void;
+
+  constructor(private readonly transport: DuplexTransport) {
+    super();
+    transport.pause();
+    transport.on('data', (chunk: Uint8Array) => {
+      transport.pause();
+      this.receive(chunk);
+    });
+    transport.on('end', () => this.receiveEof());
+    transport.on('error', () => {
+      this.pendingWrite?.(UV_ECONNRESET);
+      this.receiveError(UV_ECONNRESET);
+    });
+    transport.on('close', () => {
+      this.pendingWrite?.(UV_ECONNRESET);
+      this.receiveEof();
+    });
+  }
+
+  override readStop(): number {
+    this.transport.pause();
+    return super.readStop();
+  }
+
+  protected override flushInbound(): void {
+    super.flushInbound();
+    if (this.reading && !this.closed && !this.inboundEof) this.transport.resume();
+  }
+
+  protected override dispatchWrite(req: WriteWrap, buffer: Uint8Array): number {
+    if (this.closed) return UV_EBADF;
+    streamBaseState[kBytesWritten] = buffer.byteLength;
+    streamBaseState[kLastWriteWasAsync] = 1;
+    this.writeQueueSize = buffer.byteLength;
+    let offset = 0;
+    let complete = false;
+    const finish = (status: number): void => {
+      if (complete) return;
+      complete = true;
+      this.pendingWrite = undefined;
+      this.writeQueueSize = 0;
+      queueMicrotask(() => req.oncomplete?.(status));
+    };
+    this.pendingWrite = finish;
+    const next = (): void => {
+      if (complete) return;
+      if (this.closed) { finish(UV_EBADF); return; }
+      if (offset === buffer.byteLength) { finish(0); return; }
+      // A caller's large write is retained until its callback, as in Node;
+      // only one bounded copy enters the transport at a time.
+      const bytes = buffer.slice(offset, offset + 64 * 1024);
+      offset += bytes.byteLength;
+      this.transport.write(bytes, error => {
+        if (error) { finish(UV_ECONNRESET); return; }
+        this.bytesWritten += bytes.byteLength;
+        this.writeQueueSize -= bytes.byteLength;
+        next();
+      });
+    };
+    queueMicrotask(next);
+    return 0;
+  }
+
+  override shutdown(req: ShutdownWrap): number {
+    if (this.closed) return UV_EBADF;
+    this.transport.end(() => req.oncomplete?.(0));
+    return 0;
+  }
+
+  protected override onCloseHandle(): void {
+    this.pendingWrite?.(UV_EBADF);
+    this.transport.destroy();
+  }
+
+  getsockname(): number { return UV_ENOTSUP; }
+  getpeername(): number { return UV_ENOTSUP; }
+  setNoDelay(): number { return 0; }
+  setKeepAlive(): number { return 0; }
+}

package/src/node-lib/binding/fds.ts

@@ -15,6 +15,7 @@
 
 import type { ProcessToken } from '../../process-tokens';
 import { currentOwner } from './handles';
+import { nativeInheritedFdType } from '../../native-stream-binding';
 
 /** What libuv answers for a descriptor. */
 export type HandleType = 'TCP' | 'TTY' | 'UDP' | 'FILE' | 'PIPE' | 'UNKNOWN';
@@ -36,6 +37,15 @@ const runFds = new Map<ProcessToken, Map<number, { type: HandleType; handle: unk
 
 let nextFd = 20;
 
+/** Files and streams occupy one descriptor namespace, as on the OS. */
+export function allocateFd(): number {
+  // The host can inherit any descriptor number, not just the usual IPC fd 3.
+  // Files allocated locally must not shadow one owned by the native channel.
+  while (nativeInheritedFdType(nextFd) !== undefined) nextFd += 1;
+  return nextFd++;
+}
+
+
 /** Record a descriptor a run is started with, under that run's name. */
 export function registerRunFd(token: ProcessToken, fd: number, type: HandleType, handle: unknown): void {
   let table = runFds.get(token);
@@ -48,6 +58,11 @@ export function releaseRunFds(token: ProcessToken): void {
   runFds.delete(token);
 }
 
+/** Trusted process admission reads copies of this run's descriptor entries. */
+export function inheritedRunFds(token: ProcessToken): Array<{ fd: number; type: HandleType; handle: unknown }> {
+  return Array.from(runFds.get(token) ?? [], ([fd, entry]) => ({ fd, ...entry }));
+}
+
 /** The descriptor table of the run asking, where the asking run has one. */
 function tableOfAskingRun(): Map<number, { type: HandleType; handle: unknown }> | undefined {
   const token = currentOwner();
@@ -56,7 +71,7 @@ function tableOfAskingRun(): Map<number, { type: HandleType; handle: unknown }>
 
 /** Record a handle under a descriptor of the engine's own, and answer the number. */
 export function registerFd(type: HandleType, handle: unknown): number {
-  const fd = nextFd++;
+  const fd = allocateFd();
   openFds.set(fd, { type, handle });
   return fd;
 }
@@ -75,6 +90,8 @@ export function releaseFd(fd: number): void {
 export function guessHandleTypeOfFd(fd: number): HandleType {
   const open = tableOfAskingRun()?.get(fd) ?? openFds.get(fd);
   if (open) return open.type;
+  const inherited = nativeInheritedFdType(fd);
+  if (inherited) return inherited;
   if (fd === 0 || fd === 1 || fd === 2) return 'PIPE';
   return 'FILE';
 }

package/src/node-lib/binding/fs.ts

@@ -30,6 +30,9 @@
 import { createNodeError as vfsError } from '../../virtual-fs';
 import { registerHandle, releaseHandle, refHandle, unrefHandle, handleHasRef, currentOwner } from './handles';
 import { enterRun } from '../../process-tokens';
+import { allocateFd, handleForFd } from './fds';
+import { LibuvStreamWrap, WriteWrap } from './stream_wrap';
+import { errname } from './uv';
 
 /**
  * An errno error, as the filesystem makes one. The tree's own maker knows the
@@ -158,7 +161,6 @@ interface OpenFile {
 
 /** Every descriptor this engine has open, and the next number to hand out. */
 const openFiles = new Map<number, OpenFile>();
-let nextFd = 20;
 
 function fileFor(fd: number): OpenFile {
   const file = openFiles.get(fd);
@@ -259,14 +261,15 @@ function answer<T>(req: FSReq | undefined, work: () => T): T | undefined {
  * onto the path; a string child threw `list[1]`/`list[2]` must be a Buffer,
  * received `'exthost1'`.
  */
+export function createFsBindings(Bytes: () => typeof NodeBuffer = () => NodeBuffer) {
 function encodeFsName(name: string, encoding: unknown): string | Uint8Array {
   if (encoding !== 'buffer' && encoding !== 6) {
     if (typeof encoding === 'string' && encoding.length > 0 && encoding !== 'utf8' && encoding !== 'utf-8') {
-      return (NodeBuffer.from(name) as { toString(enc: string): string }).toString(encoding);
+      return (Bytes().from(name) as { toString(enc: string): string }).toString(encoding);
     }
     return name;
   }
-  return NodeBuffer.from(name);
+  return Bytes().from(name);
 }
 
 /** The path as Node handed it, with a Buffer decoded. A symlink's target is this, not resolved. */
@@ -303,21 +306,21 @@ function asPath(path: unknown): string {
  * the callback and nothing else, because `answer` above is the whole of what
  * makes a call asynchronous in a realm with one thread.
  */
-export class FSReqCallback {
+class FSReqCallback {
   oncomplete: ((error: Error | null, ...rest: unknown[]) => void) | undefined;
   context: unknown;
   constructor(public bigint = false) {}
 }
 
 /** The symbol `fs.promises` passes where a callback would go. */
-export const kUsePromises = Symbol('kUsePromises');
+
 
 /**
  * `internalBinding('fs_dir')`'s handle: an open directory, read a batch at a
  * time. Node's own `Dir` and `Dirent` are built on it; what a handle owes is
  * a flat list of name and type, and `null` when there is nothing left.
  */
-export class DirHandle {
+class DirHandle {
   #entries: Array<[string, number]>;
   #at = 0;
   #encoding: unknown;
@@ -351,7 +354,7 @@ export class DirHandle {
   }
 }
 
-export const fsDirBinding = {
+const fsDirBinding = {
   opendirSync(path: unknown, encoding?: unknown): DirHandle { return new DirHandle(asPath(path), encoding); },
   opendir(path: unknown, encoding: string, req?: FSReq): DirHandle | undefined {
     return answer(req, () => new DirHandle(asPath(path), encoding));
@@ -364,12 +367,12 @@ export const fsDirBinding = {
  * `FSWatcher` expects around them -- a start that takes a path and answers
  * an errno, a close, and `onchange(status, event, filename)`.
  */
-export class FSEvent {
-  onchange: ((status: number, event: string, filename: string) => void) | null = null;
+class FSEvent {
+  onchange: ((status: number, event: string, filename: string | Uint8Array) => void) | null = null;
   #watcher: { close(): void } | null = null;
   initialized = false;
 
-  start(path: unknown, persistent?: boolean, recursive?: boolean, _encoding?: string): number {
+  start(path: unknown, persistent?: boolean, recursive?: boolean, encoding?: string): number {
     const name = asPath(path);
     const tree = vfs();
     const cwd = callingCwd();
@@ -379,7 +382,9 @@ export class FSEvent {
         // libuv names a change `change` and a create or a remove `rename`,
         // which is what Node's `FSWatcher` turns into its own two events.
         const notify = () => withFilesystem(tree, () => withCwd(cwd, () =>
-          this.onchange?.(0, event === 'rename' ? 'rename' : 'change', filename ?? '')));
+          // libuv encodes the filename at this binding, including Buffer
+          // when requested. Node's FSWatcher forwards it without conversion.
+          this.onchange?.(0, event === 'rename' ? 'rename' : 'change', encodeFsName(filename ?? '', encoding))));
         if (owner === null) notify();
         else enterRun(owner, notify);
       }) as never) as unknown as { close(): void };
@@ -410,7 +415,7 @@ export class FSEvent {
  * `StatWatcher`: what `fs.watchFile` is. It polls, as libuv's does, and the
  * interval is the one the program asked for.
  */
-export class StatWatcher {
+class StatWatcher {
   onchange: ((current: Float64Array | BigInt64Array, previous: Float64Array | BigInt64Array) => void) | null = null;
   #timer: ReturnType<typeof setInterval> | null = null;
   #previous: Float64Array | BigInt64Array | null = null;
@@ -445,21 +450,21 @@ export class StatWatcher {
   hasRef(): boolean { return this.#timer !== null; }
 }
 
-export const fsEventWrapBinding = { FSEvent };
+const fsEventWrapBinding = { FSEvent };
 
 /**
  * What `fs.promises.open` is handed: a descriptor with a close of its own.
  * Node's is a C++ handle whose destructor closes the file; here it is the
  * same number this file's table keeps, with the same close.
  */
-export class FileHandle {
+class FileHandle {
   constructor(public fd: number) {}
   close(): Promise<void> { openFiles.delete(this.fd); return Promise.resolve(); }
   release(): void { openFiles.delete(this.fd); }
   getAsyncId(): number { return this.fd; }
 }
 
-export const fsBinding = {
+const fsBinding = {
   FSReqCallback,
   kUsePromises,
   StatWatcher,
@@ -490,7 +495,7 @@ export const fsBinding = {
       } else if ((flags & bits.truncate) !== 0) {
         tree.writeFileSync(name, '');
       }
-      const fd = nextFd++;
+      const fd = allocateFd();
       const position = (flags & bits.append) !== 0 && exists ? (tree.readFileSync(name) as Uint8Array).length : 0;
       openFiles.set(fd, { path: name, flags, position, directory: false, tree });
       return fd;
@@ -498,7 +503,11 @@ export const fsBinding = {
   },
 
   close(fd: number, req?: FSReq): undefined {
-    return answer(req, () => { fileFor(fd); openFiles.delete(fd); return undefined; });
+    return answer(req, () => {
+      const stream = handleForFd(fd);
+      if (stream instanceof LibuvStreamWrap) { stream.close(); return undefined; }
+      fileFor(fd); openFiles.delete(fd); return undefined;
+    });
   },
 
   // ---- reading ------------------------------------------------------------
@@ -544,6 +553,14 @@ export const fsBinding = {
   // ---- writing ------------------------------------------------------------
   writeBuffer(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null, req?: FSReq): number | undefined {
     return answer(req, () => {
+      const stream = handleForFd(fd);
+      if (stream instanceof LibuvStreamWrap) {
+        if (position !== null && position !== undefined && position >= 0) throw createNodeError('ESPIPE', 'write', String(fd));
+        const bytes = buffer.subarray(offset, offset + length);
+        const status = stream.writeBuffer(new WriteWrap(), bytes);
+        if (status !== 0) throw createNodeError(errname(status), 'write', String(fd));
+        return bytes.length;
+      }
       const file = fileFor(fd);
       if ((file.flags & 3) === 0) throw createNodeError('EBADF', 'write', file.path);
       const tree = file.tree;
@@ -872,4 +889,15 @@ export const fsBinding = {
   },
 };
 
+return { fsBinding, fsDirBinding, fsEventWrapBinding, FSReqCallback, DirHandle, FSEvent, StatWatcher, FileHandle };
+}
+
+export const kUsePromises = Symbol('kUsePromises');
+const hostBindings = createFsBindings();
+export const { fsBinding, fsDirBinding, fsEventWrapBinding, FSReqCallback, DirHandle, FSEvent, StatWatcher, FileHandle } = hostBindings;
+export type FSReqCallback = InstanceType<typeof FSReqCallback>;
+export type DirHandle = InstanceType<typeof DirHandle>;
+export type FSEvent = InstanceType<typeof FSEvent>;
+export type StatWatcher = InstanceType<typeof StatWatcher>;
+export type FileHandle = InstanceType<typeof FileHandle>;
 export default fsBinding;

package/src/node-lib/binding/misc.ts

@@ -166,6 +166,8 @@ export const encodingBinding = {
  * Node without ICU does, and is the one thing `buffer.js` loses here.
  */
 export const configBinding = {
+  // No ICU: Node navigator supplies its own default for an empty locale.
+  getDefaultLocale: (): string => '',
   hasIntl: false,
   hasSmallICU: false,
   hasNodeOptions: true,