@volter/tabnode 0.4.1 → 0.5.0

package/dist/source-edits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Apply non-overlapping edits in descending source order. The AST visitors
+ * decide the replacements; assembly must not copy a large module once per
+ * reference. For equal-position insertions, later edits appear before earlier
+ * ones, matching the former repeated slice/concatenate operation.
+ */
+export declare function applySourceEdits(source: string, edits: readonly (readonly [start: number, end: number, text: string])[]): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/tabnode",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Node's own library, in a browser tab.",
   "type": "module",
   "license": "MIT",

package/src/code-transforms.ts

@@ -6,6 +6,7 @@
 
 import { forGuestRealm, takeFromHost } from './host-globals';
 import * as acorn from 'acorn';
+import { applySourceEdits } from './source-edits';
 
 /**
  * A module's lowered exports go to the module's exports whatever the module
@@ -335,9 +336,7 @@ function __substrateLiveImportBindings(code: any) {
 
   visit(ast, new Set(reads.keys()));
   edits.sort((a, b) => b[0] - a[0]);
-  let result = code;
-  for (const [start, end, text] of edits) result = result.slice(0, start) + text + result.slice(end);
-  return result;
+  return applySourceEdits(code, edits);
 }
 
 /** AST-based ESM→CJS transform using acorn. */

package/src/fetch-transport.ts

@@ -0,0 +1,98 @@
+/** Host Fetch I/O uses the same process-owned liveness registry as sockets. */
+import type { Process } from './shims/process';
+import { __tokenForProcess, __runFor, enterRun, type ProcessToken } from './process-tokens';
+import { registerHandle, __adoptHandle, refHandle, unrefHandle, releaseHandle } from './node-lib/binding/handles';
+
+export interface FetchActivity {
+  /** One pending transport operation; the returned release is idempotent. */
+  hold(): () => void;
+  /** EOF/error/cancellation ends ownership, without cancelling completed I/O. */
+  release(): void;
+}
+
+export interface FetchTransportContext {
+  /** Retain cancellation ownership while idle, but do not keep the run alive. */
+  begin(cancel: () => void): FetchActivity;
+}
+
+export type FetchTransport = (input: RequestInfo | URL, init: RequestInit | undefined, context: FetchTransportContext) => Promise<Response>;
+let transport: FetchTransport | undefined;
+
+// Request.body exposes a stream even for a string, Blob or FormData. Keep
+// the native constructor's source distinction for transports crossing realms:
+// a finite body must not acquire streaming-upload restrictions in transit.
+const staticRequestBodies = new WeakSet<Request>();
+
+export function rememberRequestBodySource(request: Request, input: RequestInfo | URL, init?: RequestInit): void {
+  if (!request.body) return;
+  if (init?.body != null
+    ? !(init.body instanceof ReadableStream)
+    : typeof input === 'object' && staticRequestBodies.has(input as Request)) {
+    staticRequestBodies.add(request);
+  }
+}
+
+/** Host transport metadata; it carries no network permission. */
+export function requestHasStaticBody(request: Request): boolean {
+  return staticRequestBodies.has(request);
+}
+
+/** Host-only seam: the adapter reports pending headers/pulls and final cleanup. */
+export function installFetchTransport(adapter: FetchTransport): () => void {
+  const previous = transport;
+  transport = adapter;
+  return () => { if (transport === adapter) transport = previous; };
+}
+
+function activity(owner: ProcessToken | null, cancel: () => void): FetchActivity {
+  let ended = false;
+  let pending = 0;
+  const handle = {
+    close() {
+      if (ended) return;
+      release();
+      cancel();
+    },
+  };
+  const release = (): void => {
+    if (ended) return;
+    ended = true;
+    releaseHandle(handle);
+  };
+  registerHandle(handle);
+  // Never attribute a delayed request to the last process that happened to run.
+  __adoptHandle(handle, owner);
+  unrefHandle(handle);
+  return {
+    hold() {
+      if (ended) throw new Error('Fetch request has already ended.');
+      pending += 1;
+      refHandle(handle);
+      let held = true;
+      return () => {
+        if (!held) return;
+        held = false;
+        if (--pending === 0 && !ended) unrefHandle(handle);
+      };
+    },
+    release,
+  };
+}
+
+/** Each process may replace its own fetch; the host adapter remains private. */
+export function guestFetch(process: Process, fallback: typeof globalThis.fetch): typeof globalThis.fetch {
+  return function fetch(input, init) {
+    const adapter = transport;
+    if (!adapter) return fallback.call(globalThis, input, init);
+    const owner = __tokenForProcess(process);
+    const ended = () => owner !== null && __runFor(owner)?.process !== process;
+    const stopped = () => new DOMException('The requesting process has ended.', 'AbortError');
+    if (ended()) return Promise.reject(stopped());
+    const context: FetchTransportContext = { begin(cancel) {
+      if (ended()) throw stopped();
+      return activity(owner, cancel);
+    } };
+    const dispatch = () => adapter(input, init, context);
+    return owner === null ? dispatch() : enterRun(owner, dispatch);
+  };
+}

package/src/guest-timers.ts

@@ -0,0 +1,89 @@
+import { __reportUncaughtException } from './shims/process';
+import { nodeTimeout, timerHandleOf } from './node-lib/timers';
+
+/**
+ * The timers a guest process has pending: what Node's loop counts to decide
+ * a program is done. A timer the guest sets through its globals or module is
+ * held here until it fires, is cleared, or is unref'd, and the `node`
+ * command's end-of-program rule asks how many remain.
+ */
+const __substratePendingTimers = new WeakMap<object, Set<unknown>>();
+export function pendingGuestTimers(process: object): number {
+  return __substratePendingTimers.get(process)?.size ?? 0;
+}
+/**
+ * Clear every timer a guest still holds, as ending a Node process clears the
+ * ones its loop was waiting on. The ids were made by the host's own
+ * `setTimeout`/`setInterval` through the guest's global view, so the host's
+ * own clears end them; a `Timeout` is cleared by either in Node, and either
+ * refusing an id of the other kind is not an error here.
+ */
+export function stopGuestTimers(process: object): void {
+  const held = __substratePendingTimers.get(process);
+  if (!held) return;
+  const host = globalThis as unknown as Record<string, unknown>;
+  const clearOnce = host.clearTimeout as ((id: unknown) => void) | undefined;
+  const clearRepeating = host.clearInterval as ((id: unknown) => void) | undefined;
+  for (const id of [...held]) {
+    try { clearOnce?.call(host, id); } catch {}
+    try { clearRepeating?.call(host, id); } catch {}
+  }
+  held.clear();
+}
+export function guestTimerFunctions(process: object, host: Record<string, unknown>) {
+  let pending = __substratePendingTimers.get(process);
+  if (!pending) { pending = new Set(); __substratePendingTimers.set(process, pending); }
+  const held = pending;
+  const hostSetTimeout = host.setTimeout as (fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) => unknown;
+  const hostSetInterval = host.setInterval as (fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) => unknown;
+  const hostClearTimeout = host.clearTimeout as (id: unknown) => void;
+  const hostClearInterval = host.clearInterval as (id: unknown) => void;
+  // Node's timers answer a `Timeout`: an object with `ref`, `unref`,
+  // `hasRef` and `refresh`, which vitest and many packages call. A browser's
+  // answer a number. The engine used to correct this by replacing the realm's
+  // `setTimeout`, which in a Node host replaced the host's own; the
+  // correction belongs to the guest that reads Node's shape, so it is made
+  // here, on the guest's timer, and a host that already answers a `Timeout`
+  // keeps its own. The shape itself is `src/node-lib/timers.ts`: Node's own
+  // files take their timers from `require('timers')` rather than from the
+  // realm, and a timer made through one is cleared through the other.
+  const handleOf = timerHandleOf;
+  // An exception a timer callback throws is that program's uncaught
+  // exception: Node gives it to the process's `uncaughtException` listeners,
+  // else prints the stack to that process's stderr and exits it 1, and every
+  // other process is untouched. The engine's timers are the realm's own, so
+  // an uncaught throw left the guest's frames and reached the realm's global
+  // `error` event — in the tab the worker's, which the substrate's container
+  // reads as a dead host and disposes, killing openvscode-server's extension
+  // host and every other program in the tab along with the one that threw.
+  // A callback with no owning program (the engine imported as a library) is
+  // rethrown, so the host reports it as it always did.
+  const inProcess = (fn: (...a: unknown[]) => void) => (...args: unknown[]): void => {
+    try { fn(...args); }
+    catch (error) { if (!__reportUncaughtException(process, error)) throw error; }
+  };
+  const track = (id: unknown): unknown => {
+    held.add(id);
+    if (id && typeof id === "object" && typeof (id as { unref?: unknown }).unref === "function") {
+      const handle = id as { unref: () => unknown; ref: () => unknown };
+      const unref = handle.unref.bind(handle);
+      const ref = handle.ref.bind(handle);
+      handle.unref = () => { held.delete(id); return unref(); };
+      handle.ref = () => { held.add(id); return ref(); };
+    }
+    return id;
+  };
+  return {
+    setTimeout(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
+      let id: unknown;
+      const call = inProcess(fn);
+      id = nodeTimeout(hostSetTimeout.call(host, (...args: unknown[]) => { held.delete(id); call(...args); }, ms, ...rest));
+      return track(id);
+    },
+    setInterval(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
+      return track(nodeTimeout(hostSetInterval.call(host, inProcess(fn), ms, ...rest)));
+    },
+    clearTimeout(id: unknown) { held.delete(id); return hostClearTimeout.call(host, handleOf(id)); },
+    clearInterval(id: unknown) { held.delete(id); return hostClearInterval.call(host, handleOf(id)); },
+  };
+}

package/src/http-client-transport.ts

@@ -0,0 +1,169 @@
+/**
+ * Node's Agent connection seam over a host HTTP exchange. Both sides of the
+ * internal connection use Node's unmodified HTTP library: it parses requests,
+ * generates responses and owns ClientRequest/IncomingMessage and backpressure.
+ * No TLS socket or network metadata is fabricated. The host admits the target
+ * and capabilities before sending, and returns one response without retries.
+ */
+import { httpModule, httpsModule } from './node-lib/http-module';
+import { netModule } from './node-lib/net-module';
+import { streamModule } from './node-lib/stream-module';
+import { onNodeLibLoaded, type NodeLibRequire } from './node-lib/load';
+import { DuplexStreamHandle } from './node-lib/binding/duplex_stream';
+
+export interface HttpClientExchangeRequest {
+  url: string;
+  method: string;
+  headers: Array<[string, string]>;
+  body?: ReadableStream<Uint8Array>;
+  signal: AbortSignal;
+  profile: 'server-http';
+}
+export interface HttpClientExchangeResponse {
+  status: number;
+  statusText: string;
+  headers: Array<[string, string]>;
+  body: ReadableStream<Uint8Array> | null;
+}
+export type HttpClientExchange = (request: HttpClientExchangeRequest) => Promise<HttpClientExchangeResponse>;
+/** Capture process attribution synchronously when the connection is requested. */
+export type HttpClientTransportFactory = () => HttpClientExchange;
+
+const unsupported = (detail: string): Error => Object.assign(new Error(`HTTP transport does not support ${detail}.`), { code: 'ERR_HTTP_TRANSPORT_UNSUPPORTED' });
+const local = (host: string): boolean => host === 'localhost' || host === '::1' || host === '[::1]' || /^127\./u.test(host);
+const tlsOptions = ['ca', 'cert', 'key', 'pfx', 'passphrase', 'ciphers', 'secureContext', 'checkServerIdentity', 'minVersion', 'maxVersion', 'secureProtocol', 'secureOptions', 'session', 'ALPNProtocols', 'pskCallback'];
+
+/** Host-only installation; guest modules receive Node's normal exports. */
+export function installHttpClientTransport(factory: HttpClientTransportFactory): () => void {
+  type AgentPrototype = { createConnection: (...args: any[]) => any };
+  const installed = new WeakMap<AgentPrototype, { original: AgentPrototype['createConnection']; connect: AgentPrototype['createConnection'] }>();
+  const live = new Set<WeakRef<AgentPrototype>>();
+  const collected = new FinalizationRegistry<WeakRef<AgentPrototype>>(ref => live.delete(ref));
+  const install = (Agent: { prototype: AgentPrototype }, protocol: string, require?: NodeLibRequire): void => {
+    const prototype = Agent.prototype;
+    if (installed.has(prototype)) return;
+    const original = prototype.createConnection;
+    const connect = function(this: unknown, options: Record<string, any>, callback: (error: Error | null, socket?: unknown) => void): unknown {
+      const host = String(options.hostname ?? options.host ?? 'localhost').toLowerCase();
+      // Plain local HTTP is the engine's existing virtual network.
+      if (protocol === 'http:' && (local(host) || options.socketPath)) return original.call(this, options, callback);
+      try {
+        if (options.socketPath || options.localAddress || options.localPort || options.lookup || options.family) throw unsupported('custom socket routing');
+        if (tlsOptions.some(key => options[key] !== undefined) || options.rejectUnauthorized === false
+          || (options.servername !== undefined && options.servername !== host)) throw unsupported('custom TLS options');
+        const authority = new URL(`${protocol}//${host.includes(':') && !host.startsWith('[') ? `[${host}]` : host}:${options.port ?? (protocol === 'https:' ? 443 : 80)}`);
+        return connection(authority, factory(), require);
+      } catch (cause) {
+        queueMicrotask(() => callback(cause instanceof Error ? cause : new Error(String(cause))));
+        return undefined;
+      }
+    };
+    prototype.createConnection = connect;
+    installed.set(prototype, { original, connect });
+    const ref = new WeakRef(prototype);
+    live.add(ref);
+    collected.register(prototype, ref, ref);
+  };
+  // The host graph serves engine-internal calls. Every guest graph gets the
+  // same host adapter at bootstrap, before application monkey patches run.
+  install(httpModule.Agent, 'http:');
+  install(httpsModule.Agent, 'https:');
+  const unsubscribe = onNodeLibLoaded((name, value, require) => {
+    if (name === '_http_agent') install(value.Agent, 'http:', require);
+    if (name === 'https') install(value.Agent, 'https:', require);
+  });
+  return () => {
+    unsubscribe();
+    for (const ref of live) {
+      const prototype = ref.deref();
+      const held = prototype && installed.get(prototype);
+      if (prototype && held && prototype.createConnection === held.connect) prototype.createConnection = held.original;
+      collected.unregister(ref);
+    }
+    live.clear();
+  };
+}
+
+function connection(origin: URL, exchange: HttpClientExchange, require?: NodeLibRequire): unknown {
+  // Resolve at connection time; eagerly loading during Agent compilation
+  // would enter a partially initialized HTTP/stream dependency cycle.
+  const streams = require ? require('stream') : streamModule;
+  const net = require ? require('net') : netModule;
+  const http = require ? require('http') : httpModule;
+  const pair = streams.duplexPair({ highWaterMark: 64 * 1024 }) as [any, any];
+  const client = new net.Socket({ handle: new DuplexStreamHandle(pair[0]), readable: true, writable: true });
+  const peer = new net.Socket({ handle: new DuplexStreamHandle(pair[1]), readable: true, writable: true });
+  peer.unref();
+  const controller = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  const fail = (cause: unknown): void => {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    controller.abort(error);
+    client.destroy(error);
+    peer.destroy();
+  };
+  client.once('close', (() => {
+    controller.abort(new Error('HTTP client connection closed.'));
+    void reader?.cancel(controller.signal.reason).catch(() => {});
+    peer.destroy();
+  }) as never);
+  peer.on('error', fail as never);
+  const server = http.createServer({ maxHeaderSize: 32 * 1024, requestTimeout: 0, headersTimeout: 0 }, (request: any, response: any) => {
+    void (async () => {
+      if (!request.url.startsWith('/') || request.url.startsWith('//')) throw unsupported('absolute-form request targets');
+      const url = new URL(request.url, origin);
+      if (url.origin !== origin.origin) throw unsupported('a request target that changes origin');
+      const headers: Array<[string, string]> = [];
+      const connectionHeaders = new Set<string>();
+      for (let i = 0; i < request.rawHeaders.length; i += 2) {
+        const name = request.rawHeaders[i], value = request.rawHeaders[i + 1];
+        const lower = name.toLowerCase();
+        if (['expect', 'upgrade', 'trailer', 'te'].includes(lower)) throw unsupported(`${lower} headers`);
+        if (lower === 'host') {
+          if (value.toLowerCase() !== origin.host) throw unsupported('a Host header different from the destination');
+          continue;
+        }
+        if (lower === 'connection') for (const token of value.split(',')) connectionHeaders.add(token.trim().toLowerCase());
+        headers.push([name, value]);
+      }
+      // Preserve the parsed length as metadata. The host can send a bounded,
+      // known-small body without Fetch's HTTP/2-only streaming upload mode;
+      // the remote transport still generates its own HTTP framing.
+      const outgoing = headers.filter(([name]) => !['connection', 'keep-alive', 'transfer-encoding'].includes(name.toLowerCase()) && !connectionHeaders.has(name.toLowerCase()));
+      const carriesBody = request.headers['transfer-encoding'] !== undefined || Number(request.headers['content-length'] ?? 0) > 0;
+      const Readable = streams.Readable as any;
+      const body = carriesBody ? Readable.toWeb(request, { strategy: { highWaterMark: 64 * 1024, size: (chunk: Uint8Array) => chunk.byteLength } }) : undefined;
+      if (!carriesBody) request.resume();
+      const result = await exchange({ url: url.href, method: request.method, headers: outgoing, ...(body ? { body } : {}), signal: controller.signal, profile: 'server-http' });
+      if (controller.signal.aborted) { await result.body?.cancel(controller.signal.reason); return; }
+      // This virtual connection carries one exchange. Framing is Node's; the
+      // remote connection's hop-by-hop state is never a local socket promise.
+      response.shouldKeepAlive = false;
+      response.sendDate = false;
+      response.writeHead(result.status, result.statusText, result.headers.flat());
+      reader = result.body?.getReader();
+      try {
+        for (;;) {
+          controller.signal.throwIfAborted();
+          const next = reader ? await reader.read() : { done: true, value: undefined };
+          if (next.done) break;
+          if (!response.write(next.value)) await new Promise<void>((resolve, reject) => {
+            const abort = (): void => { response.removeListener('drain', drain); reject(controller.signal.reason); };
+            const drain = (): void => { controller.signal.removeEventListener('abort', abort); resolve(); };
+            response.once('drain', drain);
+            controller.signal.addEventListener('abort', abort, { once: true });
+            if (controller.signal.aborted) abort();
+          });
+        }
+        response.end();
+      } catch (cause) {
+        await reader?.cancel(cause).catch(() => {});
+        throw cause;
+      } finally { reader?.releaseLock(); reader = undefined; }
+    })().catch(fail);
+  }) as any;
+  for (const name of ['connect', 'upgrade', 'checkContinue', 'checkExpectation']) server.on(name, () => fail(unsupported(name)));
+  server.on('clientError', fail);
+  server.emit('connection', peer);
+  return client;
+}

package/src/index.ts

@@ -24,6 +24,8 @@ export { createProcess } from './shims/process';
 export type { Process, ProcessEnv } from './shims/process';
 export * as path from './shims/path';
 export { httpModule as http, httpsModule as https } from './node-lib/http-module';
+export { installHttpClientTransport } from './http-client-transport';
+export type { HttpClientExchange, HttpClientExchangeRequest, HttpClientExchangeResponse, HttpClientTransportFactory } from './http-client-transport';
 import { __releaseOwnedServers, __ownedServerPorts } from './node-lib/net-module';
 export { netModule as net } from './node-lib/net-module';
 export { eventsModule as events } from './node-lib/events-module';
@@ -55,6 +57,13 @@ import { Server as NetServer, __releaseOwnedHandles, type Socket as NetSocket }
 
 import { __currentProcessToken, __runFor, __stopOwnedProcess, runPid, processByPid } from './process-tokens';
 export { runPid, processByPid };
+export { createProcessRegistryScope, installProcessRegistry, ownerProcessRegistryScope } from './process-tokens';
+export { installNodeProcessHost, nodeProcessHostInstalled } from './node-process-host';
+export type { NodeProcessLaunch, NodeProcessHost } from './node-process-host';
+export type { ProcessIdentity, ProcessRegistry, ProcessRegistryScope, InitialProcessRegistration } from './process-registry';
+export { NativeStreamScope } from './native-stream-owner';
+export { installNativeStreamTransport, nativeStreamDescriptor } from './native-stream-binding';
+export type { NativeStreamDescriptor, NativeStreamLimits, NativeStreamEvent, NativeStreamOperation, NativeStreamReply, NativeStreamTransport } from './native-stream-owner';
 
 export interface RunResult {
   stdout: string;
@@ -234,6 +243,9 @@ export function createContainer(options?: ContainerOptions): {
 
 export default createContainer;
 
+export { installFetchTransport, requestHasStaticBody } from './fetch-transport';
+export type { FetchActivity, FetchTransport, FetchTransportContext } from './fetch-transport';
+
 // Node's module resolution as a function over any filesystem, for a host
 // that resolves the way the engine does (the substrate's stand-ins do).
 export { createNodeResolver } from './node-resolution';