sandboxedjs 0.1.44 → 0.1.46

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as Shell, a as ShellIO, b as Session, V as Vfs, c as Cred, N as Node, d as Command, K as Kernel, R as RuntimeVolume, e as VolumeStat, f as VolumeStats, g as RuntimeHttpResponse, h as SpawnChild, i as SyncSpawn, j as RuntimePod, k as RuntimePackageInstaller, l as ChildSpawnConfig, m as ChildHandle, n as RuntimeProcess, E as ExecContext, O as OutputStream, C as Container, o as createContainer } from './container-CZn9USBQ.cjs';
-export { B as BufferSink, p as CPythonOptions, q as CallbackSink, r as CommandRegistry, s as ContainerFs, t as ContainerOptions, u as ContextInit, D as DirEntry, v as Env, w as ExecOptions, x as ExecResult, F as FileData, y as FileInput, z as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, A as KernelOptions, L as ListeningPort, M as MountEntry, P as NetInterface, Q as NetworkOptions, T as NetworkStack, U as NullInput, W as NullOutput, X as PYTHON_VERSION, Y as PasswdEntry, Z as Pipe, _ as Process, $ as ProcessKind, a0 as ProcessOptions, a1 as ProcessState, a2 as ProcessTable, a3 as PythonOptions, a4 as ROOT_CRED, a5 as ResolvedExecutable, a6 as RunOptions, a7 as RunResult, a8 as RuntimeProcessManager, a9 as RuntimeProcessResult, aa as SessionInit, ab as SessionResult, ac as SessionRunOptions, ad as ShellExit, ae as ShellInit, af as ShellOptions, ag as SpawnHandle, ah as Stats, ai as Stdio, aj as TeeOutput, ak as UserDatabase, al as Variables, am as VirtualNode, an as VirtualProvider, ao as WriteOptions, ap as applyChmod, aq as braceExpand, ar as captureStdio, as as configureCPython, at as configurePython, au as createChildProcessModule, av as createContext, aw as defineCommand, ax as expandWord, ay as expandWords, az as formatMode, aA as isCPythonAvailable, aB as isPythonAvailable, aC as makeCred, aD as octalMode, aE as parseUmask, aF as resetPidCounter, aG as shellQuote } from './container-CZn9USBQ.cjs';
+import { S as Shell, a as ShellIO, b as Session, V as Vfs, c as Cred, N as Node, d as Command, K as Kernel, R as RuntimeVolume, e as VolumeStat, f as VolumeStats, g as RuntimeHttpResponse, h as SpawnChild, i as SyncSpawn, j as RuntimePod, k as RuntimePackageInstaller, l as ChildSpawnConfig, m as ChildHandle, n as RuntimeProcess, o as RuntimeSocketPeer, p as RuntimeConnection, E as ExecContext, O as OutputStream, C as Container, q as createContainer } from './container-DyRF-bY0.cjs';
+export { B as BufferSink, r as CPythonOptions, s as CallbackSink, t as CommandRegistry, u as ContainerFs, v as ContainerOptions, w as ContextInit, D as DirEntry, x as Env, y as ExecOptions, z as ExecResult, F as FileData, A as FileInput, G as FileOutput, H as GroupEntry, I as HttpResponse, J as InputStream, L as Job, M as KernelOptions, P as ListeningPort, Q as MountEntry, T as NetInterface, U as NetworkOptions, W as NetworkStack, X as NullInput, Y as NullOutput, Z as PYTHON_VERSION, _ as PasswdEntry, $ as Pipe, a0 as Process, a1 as ProcessKind, a2 as ProcessOptions, a3 as ProcessState, a4 as ProcessTable, a5 as PythonOptions, a6 as ROOT_CRED, a7 as ResolvedExecutable, a8 as RunOptions, a9 as RunResult, aa as RuntimeProcessManager, ab as RuntimeProcessResult, ac as SessionInit, ad as SessionResult, ae as SessionRunOptions, af as ShellExit, ag as ShellInit, ah as ShellOptions, ai as SpawnHandle, aj as Stats, ak as Stdio, al as TeeOutput, am as UserDatabase, an as Variables, ao as VirtualNode, ap as VirtualProvider, aq as WriteOptions, ar as applyChmod, as as braceExpand, at as captureStdio, au as configureCPython, av as configurePython, aw as createChildProcessModule, ax as createContext, ay as defineCommand, az as expandWord, aA as expandWords, aB as formatMode, aC as isCPythonAvailable, aD as isPythonAvailable, aE as makeCred, aF as octalMode, aG as parseUmask, aH as resetPidCounter, aI as shellQuote } from './container-DyRF-bY0.cjs';
 import EventEmitter from 'events/events.js';
 import streamModule from 'stream-browserify';
 
@@ -648,8 +648,8 @@ declare class VirtualIncomingMessage extends streamModule.Readable {
     readonly httpVersionMajor = 1;
     readonly httpVersionMinor = 1;
     readonly complete = true;
-    readonly socket: Record<string, unknown>;
-    readonly connection: Record<string, unknown>;
+    socket: Record<string, unknown> | VirtualSocket;
+    get connection(): Record<string, unknown> | VirtualSocket;
     constructor(init: VirtualRequestInit);
     _read(): void;
     setTimeout(_milliseconds: number, callback?: () => void): this;
@@ -683,6 +683,60 @@ declare class VirtualServerResponse extends streamModule.Writable {
     addTrailers(_headers: Record<string, string>): void;
     setTimeout(_milliseconds: number, callback?: () => void): this;
 }
+/** Where a {@link VirtualSocket} puts the bytes the server writes. */
+interface VirtualSocketPeer {
+    /** The server sent these. */
+    data(bytes: Uint8Array): void;
+    /** The server hung up. */
+    close(): void;
+}
+/**
+ * The server half of a connection that has stopped being HTTP.
+ *
+ * Everything else in this file models one request and one response, because
+ * that is all a container's servers were ever asked for. A protocol upgrade is
+ * the case that does not fit: after the `101` there is no request and no
+ * response, only two peers writing bytes at each other for as long as they
+ * both stay interested.
+ *
+ * So this is a real `Duplex` rather than another stub. It has to be — the
+ * libraries that speak WebSocket do not merely read `req.headers` and reply,
+ * they take the socket and run a framing protocol over it, and a stub that
+ * accepts `write()` and drops it produces a server that completes its
+ * handshake and is then silent forever, which looks exactly like a network
+ * problem and is the hardest possible thing to attribute.
+ *
+ * Writes go out through {@link VirtualSocketPeer}; {@link deliver} pushes what
+ * comes back. Nothing here knows what the bytes mean, which is the point: `ws`,
+ * `socket.io` and Vite's HMR server all work over it unmodified.
+ */
+declare class VirtualSocket extends streamModule.Duplex {
+    readonly remoteAddress = "127.0.0.1";
+    readonly remotePort = 0;
+    readonly localAddress = "127.0.0.1";
+    readonly localPort = 0;
+    readonly encrypted = false;
+    readonly bufferSize = 0;
+    private peer;
+    /** Set once the peer is told, so `end()` then `destroy()` reports once. */
+    private hungUp;
+    constructor(peer: VirtualSocketPeer);
+    _read(): void;
+    _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+    private hangUp;
+    /** Bytes arriving from the far end. */
+    deliver(bytes: Uint8Array): void;
+    /** The far end went away; let the server's stream end cleanly. */
+    peerClosed(): void;
+    setNoDelay(): this;
+    setKeepAlive(): this;
+    setTimeout(_milliseconds: number, callback?: () => void): this;
+    destroySoon(): void;
+    ref(): this;
+    unref(): this;
+}
 declare class VirtualHttpServer extends EventEmitter {
     private readonly router;
     readonly owner: string;
@@ -716,6 +770,28 @@ declare class VirtualHttpRouter {
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
+    /**
+     * Open a connection that leaves HTTP behind — a WebSocket, in practice.
+     *
+     * The counterpart to {@link request}, and the thing whose absence made a dev
+     * server look broken. Every Node WebSocket library is built the same way: it
+     * hands `http.Server` an `upgrade` listener and waits. Nothing here ever
+     * emitted one, so `ws` sat holding a server that could not receive a single
+     * connection, and Vite lost the channel it uses to tell a page to reload —
+     * which is the only way it can recover after re-optimizing dependencies.
+     *
+     * Null means there is nothing to connect to: no server on the port, or a
+     * server that never asked for upgrades. Both are refusals the caller should
+     * report rather than wait out.
+     */
+    connect(port: number, init: VirtualRequestInit, peer: VirtualSocketPeer): VirtualConnection | null;
+}
+/** A connection handed back by {@link VirtualHttpRouter.connect}. */
+interface VirtualConnection {
+    /** Bytes from the far end, into the container. */
+    send(bytes: Uint8Array): void;
+    /** The far end went away. */
+    close(): void;
 }
 
 interface CoreModulesOptions {
@@ -1029,6 +1105,7 @@ declare class LocalRuntimePod implements RuntimePod {
      */
     private settle;
     request(_port: number, _init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    connect(port: number, init: Record<string, unknown>, peer: RuntimeSocketPeer): RuntimeConnection | null;
     snapshot(): MemoryVolumeSnapshotEntry[];
     restore(snapshot: unknown): Promise<void>;
     teardown(): void;
@@ -1076,6 +1153,8 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
     private runChildToCompletion;
     private readonly proxies;
     private readonly waiting;
+    /** Upgraded connections, by the id the Worker knows them as. */
+    private readonly upgraded;
     private nextRequestId;
     /**
      * Register a stand-in for a server that is actually running in the Worker.
@@ -1085,6 +1164,14 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
      */
     private proxyPort;
     private forward;
+    /**
+     * Tunnel one upgraded connection to the server that actually holds the port.
+     *
+     * Unlike {@link forward} there is no reply to wait for: both ends write
+     * whenever they have something, until one of them stops. The id is what ties
+     * the two directions together across the Worker boundary.
+     */
+    private upgrade;
     private settleProxied;
     private closeProxies;
     teardown(): void;
@@ -1451,6 +1538,33 @@ interface PreviewOptions {
     scriptUrl?: string | URL;
     /** Registration scope. Must be able to see the paths a preview will request. */
     scope?: string;
+    /**
+     * The dev server has invalidated what the frame is holding; reload it.
+     *
+     * Vite serves `504 Outdated Optimize Dep` once the hash in a dependency URL
+     * no longer matches — after its optimizer re-runs, or after the server is
+     * restarted. Its own client recovers by reloading, and hears about it over
+     * the HMR WebSocket, which this bridge does not carry. Without a reload the
+     * frame keeps asking for a hash the server has forgotten and the app never
+     * mounts.
+     *
+     * Reloading is the host's call because the host owns the frame: it can pick
+     * the moment, and it can stop after a few attempts rather than looping.
+     */
+    onStale?: () => void;
+    /**
+     * Let pages inside the preview open WebSockets to the container.
+     *
+     * On by default. A service worker cannot answer a WebSocket handshake, so
+     * previewed documents are given a `WebSocket` that tunnels through this page
+     * instead — which means the HTML they are served is modified on the way
+     * through, one `<script>` at the top of `<head>`.
+     *
+     * Turn it off to serve documents byte for byte. The cost is that a dev
+     * server loses its HMR channel, and with it the `full-reload` it sends after
+     * re-optimizing dependencies; {@link onStale} is the fallback for that.
+     */
+    websocket?: boolean;
 }
 interface Preview {
     /** The URL an iframe should be pointed at to see `port`. */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Shell, a as ShellIO, b as Session, V as Vfs, c as Cred, N as Node, d as Command, K as Kernel, R as RuntimeVolume, e as VolumeStat, f as VolumeStats, g as RuntimeHttpResponse, h as SpawnChild, i as SyncSpawn, j as RuntimePod, k as RuntimePackageInstaller, l as ChildSpawnConfig, m as ChildHandle, n as RuntimeProcess, E as ExecContext, O as OutputStream, C as Container, o as createContainer } from './container-CZn9USBQ.js';
-export { B as BufferSink, p as CPythonOptions, q as CallbackSink, r as CommandRegistry, s as ContainerFs, t as ContainerOptions, u as ContextInit, D as DirEntry, v as Env, w as ExecOptions, x as ExecResult, F as FileData, y as FileInput, z as FileOutput, G as GroupEntry, H as HttpResponse, I as InputStream, J as Job, A as KernelOptions, L as ListeningPort, M as MountEntry, P as NetInterface, Q as NetworkOptions, T as NetworkStack, U as NullInput, W as NullOutput, X as PYTHON_VERSION, Y as PasswdEntry, Z as Pipe, _ as Process, $ as ProcessKind, a0 as ProcessOptions, a1 as ProcessState, a2 as ProcessTable, a3 as PythonOptions, a4 as ROOT_CRED, a5 as ResolvedExecutable, a6 as RunOptions, a7 as RunResult, a8 as RuntimeProcessManager, a9 as RuntimeProcessResult, aa as SessionInit, ab as SessionResult, ac as SessionRunOptions, ad as ShellExit, ae as ShellInit, af as ShellOptions, ag as SpawnHandle, ah as Stats, ai as Stdio, aj as TeeOutput, ak as UserDatabase, al as Variables, am as VirtualNode, an as VirtualProvider, ao as WriteOptions, ap as applyChmod, aq as braceExpand, ar as captureStdio, as as configureCPython, at as configurePython, au as createChildProcessModule, av as createContext, aw as defineCommand, ax as expandWord, ay as expandWords, az as formatMode, aA as isCPythonAvailable, aB as isPythonAvailable, aC as makeCred, aD as octalMode, aE as parseUmask, aF as resetPidCounter, aG as shellQuote } from './container-CZn9USBQ.js';
+import { S as Shell, a as ShellIO, b as Session, V as Vfs, c as Cred, N as Node, d as Command, K as Kernel, R as RuntimeVolume, e as VolumeStat, f as VolumeStats, g as RuntimeHttpResponse, h as SpawnChild, i as SyncSpawn, j as RuntimePod, k as RuntimePackageInstaller, l as ChildSpawnConfig, m as ChildHandle, n as RuntimeProcess, o as RuntimeSocketPeer, p as RuntimeConnection, E as ExecContext, O as OutputStream, C as Container, q as createContainer } from './container-DyRF-bY0.js';
+export { B as BufferSink, r as CPythonOptions, s as CallbackSink, t as CommandRegistry, u as ContainerFs, v as ContainerOptions, w as ContextInit, D as DirEntry, x as Env, y as ExecOptions, z as ExecResult, F as FileData, A as FileInput, G as FileOutput, H as GroupEntry, I as HttpResponse, J as InputStream, L as Job, M as KernelOptions, P as ListeningPort, Q as MountEntry, T as NetInterface, U as NetworkOptions, W as NetworkStack, X as NullInput, Y as NullOutput, Z as PYTHON_VERSION, _ as PasswdEntry, $ as Pipe, a0 as Process, a1 as ProcessKind, a2 as ProcessOptions, a3 as ProcessState, a4 as ProcessTable, a5 as PythonOptions, a6 as ROOT_CRED, a7 as ResolvedExecutable, a8 as RunOptions, a9 as RunResult, aa as RuntimeProcessManager, ab as RuntimeProcessResult, ac as SessionInit, ad as SessionResult, ae as SessionRunOptions, af as ShellExit, ag as ShellInit, ah as ShellOptions, ai as SpawnHandle, aj as Stats, ak as Stdio, al as TeeOutput, am as UserDatabase, an as Variables, ao as VirtualNode, ap as VirtualProvider, aq as WriteOptions, ar as applyChmod, as as braceExpand, at as captureStdio, au as configureCPython, av as configurePython, aw as createChildProcessModule, ax as createContext, ay as defineCommand, az as expandWord, aA as expandWords, aB as formatMode, aC as isCPythonAvailable, aD as isPythonAvailable, aE as makeCred, aF as octalMode, aG as parseUmask, aH as resetPidCounter, aI as shellQuote } from './container-DyRF-bY0.js';
 import EventEmitter from 'events/events.js';
 import streamModule from 'stream-browserify';
 
@@ -648,8 +648,8 @@ declare class VirtualIncomingMessage extends streamModule.Readable {
     readonly httpVersionMajor = 1;
     readonly httpVersionMinor = 1;
     readonly complete = true;
-    readonly socket: Record<string, unknown>;
-    readonly connection: Record<string, unknown>;
+    socket: Record<string, unknown> | VirtualSocket;
+    get connection(): Record<string, unknown> | VirtualSocket;
     constructor(init: VirtualRequestInit);
     _read(): void;
     setTimeout(_milliseconds: number, callback?: () => void): this;
@@ -683,6 +683,60 @@ declare class VirtualServerResponse extends streamModule.Writable {
     addTrailers(_headers: Record<string, string>): void;
     setTimeout(_milliseconds: number, callback?: () => void): this;
 }
+/** Where a {@link VirtualSocket} puts the bytes the server writes. */
+interface VirtualSocketPeer {
+    /** The server sent these. */
+    data(bytes: Uint8Array): void;
+    /** The server hung up. */
+    close(): void;
+}
+/**
+ * The server half of a connection that has stopped being HTTP.
+ *
+ * Everything else in this file models one request and one response, because
+ * that is all a container's servers were ever asked for. A protocol upgrade is
+ * the case that does not fit: after the `101` there is no request and no
+ * response, only two peers writing bytes at each other for as long as they
+ * both stay interested.
+ *
+ * So this is a real `Duplex` rather than another stub. It has to be — the
+ * libraries that speak WebSocket do not merely read `req.headers` and reply,
+ * they take the socket and run a framing protocol over it, and a stub that
+ * accepts `write()` and drops it produces a server that completes its
+ * handshake and is then silent forever, which looks exactly like a network
+ * problem and is the hardest possible thing to attribute.
+ *
+ * Writes go out through {@link VirtualSocketPeer}; {@link deliver} pushes what
+ * comes back. Nothing here knows what the bytes mean, which is the point: `ws`,
+ * `socket.io` and Vite's HMR server all work over it unmodified.
+ */
+declare class VirtualSocket extends streamModule.Duplex {
+    readonly remoteAddress = "127.0.0.1";
+    readonly remotePort = 0;
+    readonly localAddress = "127.0.0.1";
+    readonly localPort = 0;
+    readonly encrypted = false;
+    readonly bufferSize = 0;
+    private peer;
+    /** Set once the peer is told, so `end()` then `destroy()` reports once. */
+    private hungUp;
+    constructor(peer: VirtualSocketPeer);
+    _read(): void;
+    _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+    private hangUp;
+    /** Bytes arriving from the far end. */
+    deliver(bytes: Uint8Array): void;
+    /** The far end went away; let the server's stream end cleanly. */
+    peerClosed(): void;
+    setNoDelay(): this;
+    setKeepAlive(): this;
+    setTimeout(_milliseconds: number, callback?: () => void): this;
+    destroySoon(): void;
+    ref(): this;
+    unref(): this;
+}
 declare class VirtualHttpServer extends EventEmitter {
     private readonly router;
     readonly owner: string;
@@ -716,6 +770,28 @@ declare class VirtualHttpRouter {
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
+    /**
+     * Open a connection that leaves HTTP behind — a WebSocket, in practice.
+     *
+     * The counterpart to {@link request}, and the thing whose absence made a dev
+     * server look broken. Every Node WebSocket library is built the same way: it
+     * hands `http.Server` an `upgrade` listener and waits. Nothing here ever
+     * emitted one, so `ws` sat holding a server that could not receive a single
+     * connection, and Vite lost the channel it uses to tell a page to reload —
+     * which is the only way it can recover after re-optimizing dependencies.
+     *
+     * Null means there is nothing to connect to: no server on the port, or a
+     * server that never asked for upgrades. Both are refusals the caller should
+     * report rather than wait out.
+     */
+    connect(port: number, init: VirtualRequestInit, peer: VirtualSocketPeer): VirtualConnection | null;
+}
+/** A connection handed back by {@link VirtualHttpRouter.connect}. */
+interface VirtualConnection {
+    /** Bytes from the far end, into the container. */
+    send(bytes: Uint8Array): void;
+    /** The far end went away. */
+    close(): void;
 }
 
 interface CoreModulesOptions {
@@ -1029,6 +1105,7 @@ declare class LocalRuntimePod implements RuntimePod {
      */
     private settle;
     request(_port: number, _init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    connect(port: number, init: Record<string, unknown>, peer: RuntimeSocketPeer): RuntimeConnection | null;
     snapshot(): MemoryVolumeSnapshotEntry[];
     restore(snapshot: unknown): Promise<void>;
     teardown(): void;
@@ -1076,6 +1153,8 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
     private runChildToCompletion;
     private readonly proxies;
     private readonly waiting;
+    /** Upgraded connections, by the id the Worker knows them as. */
+    private readonly upgraded;
     private nextRequestId;
     /**
      * Register a stand-in for a server that is actually running in the Worker.
@@ -1085,6 +1164,14 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
      */
     private proxyPort;
     private forward;
+    /**
+     * Tunnel one upgraded connection to the server that actually holds the port.
+     *
+     * Unlike {@link forward} there is no reply to wait for: both ends write
+     * whenever they have something, until one of them stops. The id is what ties
+     * the two directions together across the Worker boundary.
+     */
+    private upgrade;
     private settleProxied;
     private closeProxies;
     teardown(): void;
@@ -1451,6 +1538,33 @@ interface PreviewOptions {
     scriptUrl?: string | URL;
     /** Registration scope. Must be able to see the paths a preview will request. */
     scope?: string;
+    /**
+     * The dev server has invalidated what the frame is holding; reload it.
+     *
+     * Vite serves `504 Outdated Optimize Dep` once the hash in a dependency URL
+     * no longer matches — after its optimizer re-runs, or after the server is
+     * restarted. Its own client recovers by reloading, and hears about it over
+     * the HMR WebSocket, which this bridge does not carry. Without a reload the
+     * frame keeps asking for a hash the server has forgotten and the app never
+     * mounts.
+     *
+     * Reloading is the host's call because the host owns the frame: it can pick
+     * the moment, and it can stop after a few attempts rather than looping.
+     */
+    onStale?: () => void;
+    /**
+     * Let pages inside the preview open WebSockets to the container.
+     *
+     * On by default. A service worker cannot answer a WebSocket handshake, so
+     * previewed documents are given a `WebSocket` that tunnels through this page
+     * instead — which means the HTML they are served is modified on the way
+     * through, one `<script>` at the top of `<head>`.
+     *
+     * Turn it off to serve documents byte for byte. The cost is that a dev
+     * server loses its HMR channel, and with it the `full-reload` it sends after
+     * re-optimizing dependencies; {@link onStale} is the fallback for that.
+     */
+    websocket?: boolean;
 }
 interface Preview {
     /** The URL an iframe should be pointed at to see `port`. */