sandboxedjs 0.1.26 → 0.1.28

package/dist/index.d.cts

@@ -9,6 +9,14 @@ interface ChildHandle {
     on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
+    /**
+     * Close the child's input.
+     *
+     * Without this a child that reads stdin to EOF — every filter, and every
+     * tool a library pipes into, `xsel` and `base64` alike — waits forever for
+     * an end that never comes, and the parent waits on its exit.
+     */
+    endStdin?(): void;
     kill(signal?: string): void;
 }
 interface ChildSpawnConfig {
@@ -196,7 +204,7 @@ interface DirEntry {
 /**
  * The container's virtual filesystem.
  *
- * Real file content lives in a Nodepod `MemoryVolume`, which is deliberately the
+ * Real file content lives in the RuntimePod's `MemoryVolume`, deliberately the
  * *same* volume the Node.js worker processes see — so a file written by `echo`
  * is readable by `require('fs')` inside a spawned script, and vice versa.
  *
@@ -746,7 +754,7 @@ declare function createContext(init: ContextInit): ExecContext;
  * The container's network stack.
  *
  * There is no real socket layer: HTTP servers started inside the container are
- * registered with Nodepod's request proxy, and this module is the routing and
+ * registered with the RuntimePod's request proxy, and this module is the routing and
  * name-resolution layer on top — interfaces for `ip`/`ifconfig`, a hosts file
  * resolver, a listening-port table for `ss`/`netstat`, and an outbound policy
  * that decides whether `curl https://example.com` is allowed to touch the real
@@ -805,7 +813,7 @@ declare class NetworkStack {
     registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
     unregisterListener(port: number): void;
     listening(): ListeningPort[];
-    /** Ports Nodepod's proxy has registered for this instance. */
+    /** Ports the pod's proxy has registered for this instance. */
     private knownPodPorts;
     /** True when something inside the container answers on `port`. */
     isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;
@@ -1732,7 +1740,7 @@ declare class Container {
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
-     * Nodepod's public `request()` runs the body through `toString("utf8")` on
+     * A RuntimePod's public `request()` may run the body through `toString("utf8")` on
      * its way in, so anything above `0x7f` is replaced: a five-byte payload
      * containing `0x89` and `0xff` arrives as nine. That silently destroys every
      * upload — an image or a video reaches the server the wrong size and no
@@ -1772,7 +1780,7 @@ declare class Container {
     get cwd(): string;
     get env(): Record<string, string>;
     private assertActive;
-    /** Tear down every process and release the Nodepod instance. */
+    /** Tear down every process and release the runtime pod. */
     dispose(): void;
     get isDisposed(): boolean;
 }
@@ -2114,17 +2122,16 @@ interface RootfsOptions {
 declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
 
 /**
- * The Node.js runtime, backed by Nodepod.
+ * The Node.js command adapter, backed by the clean-room RuntimePod.
  *
- * Nodepod runs the script in an isolated worker over the *same* memory volume
+ * The pod runs the script over the *same* memory volume
  * the container's filesystem uses, so `require('fs')` inside a script sees the
  * files `echo` and `tar` created, and anything the script writes is visible to
  * the shell afterwards.
  *
- * Two gaps in the underlying `spawn` are papered over here:
+ * Two details of the underlying `spawn` are handled here:
  *  - only `node` resolves as a command, so everything else is dispatched by our
- *    own kernel rather than being handed to Nodepod's shell (which hangs on an
- *    unknown command);
+ *    own kernel rather than being handed to the Node process runner;
  *  - the worker's stdin has no end-of-stream signal, so when a pipeline feeds
  *    a script we materialise stdin as a file and install a real stdin stream
  *    over it before the script loads.
@@ -2427,6 +2434,8 @@ declare class VirtualHttpRouter {
     onListen: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
+    /** Whether anything in this container is listening on `port`. */
+    activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
@@ -2444,6 +2453,7 @@ interface CoreModulesOptions {
     http?: {
         router: VirtualHttpRouter;
         owner: string;
+        fetch?: typeof globalThis.fetch;
     };
     /** Backs `child_process`; without it the module reports as unavailable. */
     spawnChild?: SpawnChild;
@@ -2484,6 +2494,16 @@ declare function createCoreModules(options: CoreModulesOptions): {
      * script that has simply finished.
      */
     pendingHandles(): number;
+    /** Active timers which called `unref()` and therefore only merit startup grace. */
+    pendingUnrefed(): number;
+    /**
+     * Client requests sent but not yet read to completion.
+     *
+     * An outbound request is event-loop work in exactly the way a timer is, and
+     * it schedules no timer of its own. Counting it is what stops a program from
+     * exiting in the gap between `http.get` and its response callback.
+     */
+    pendingRequests(): number;
 };
 
 interface EsmTransformResult {
@@ -2570,9 +2590,20 @@ declare class LocalRuntimePod implements RuntimePod {
     private readonly aliases;
     private readonly modules;
     private readonly esbuild;
+    private rolldownBinding;
+    /** Backs outbound `http`/`https` client requests from inside the sandbox. */
+    private readonly fetch;
     private constructor();
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    /**
+     * Rolldown's JavaScript API synchronously requires its compiled binding.
+     * When a project contains Rolldown, preload the official WASI build in the
+     * host and expose it through the module override table before evaluation.
+     * Keeping this demand-driven avoids adding WASM startup cost to ordinary
+     * shells and Node programs.
+     */
+    private prepareRolldown;
     /**
      * Wait until the process has either started serving or genuinely run out of
      * work.
@@ -2607,6 +2638,10 @@ interface RegistryManifest {
     };
     dependencies?: Record<string, string>;
     optionalDependencies?: Record<string, string>;
+    os?: string[];
+    cpu?: string[];
+    libc?: string[];
+    main?: string;
     bin?: string | Record<string, string>;
 }
 interface CleanInstallerOptions {

package/dist/index.d.ts

@@ -9,6 +9,14 @@ interface ChildHandle {
     on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
+    /**
+     * Close the child's input.
+     *
+     * Without this a child that reads stdin to EOF — every filter, and every
+     * tool a library pipes into, `xsel` and `base64` alike — waits forever for
+     * an end that never comes, and the parent waits on its exit.
+     */
+    endStdin?(): void;
     kill(signal?: string): void;
 }
 interface ChildSpawnConfig {
@@ -196,7 +204,7 @@ interface DirEntry {
 /**
  * The container's virtual filesystem.
  *
- * Real file content lives in a Nodepod `MemoryVolume`, which is deliberately the
+ * Real file content lives in the RuntimePod's `MemoryVolume`, deliberately the
  * *same* volume the Node.js worker processes see — so a file written by `echo`
  * is readable by `require('fs')` inside a spawned script, and vice versa.
  *
@@ -746,7 +754,7 @@ declare function createContext(init: ContextInit): ExecContext;
  * The container's network stack.
  *
  * There is no real socket layer: HTTP servers started inside the container are
- * registered with Nodepod's request proxy, and this module is the routing and
+ * registered with the RuntimePod's request proxy, and this module is the routing and
  * name-resolution layer on top — interfaces for `ip`/`ifconfig`, a hosts file
  * resolver, a listening-port table for `ss`/`netstat`, and an outbound policy
  * that decides whether `curl https://example.com` is allowed to touch the real
@@ -805,7 +813,7 @@ declare class NetworkStack {
     registerListener(port: number, info: Omit<ListeningPort, "port" | "since">): void;
     unregisterListener(port: number): void;
     listening(): ListeningPort[];
-    /** Ports Nodepod's proxy has registered for this instance. */
+    /** Ports the pod's proxy has registered for this instance. */
     private knownPodPorts;
     /** True when something inside the container answers on `port`. */
     isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;
@@ -1732,7 +1740,7 @@ declare class Container {
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
-     * Nodepod's public `request()` runs the body through `toString("utf8")` on
+     * A RuntimePod's public `request()` may run the body through `toString("utf8")` on
      * its way in, so anything above `0x7f` is replaced: a five-byte payload
      * containing `0x89` and `0xff` arrives as nine. That silently destroys every
      * upload — an image or a video reaches the server the wrong size and no
@@ -1772,7 +1780,7 @@ declare class Container {
     get cwd(): string;
     get env(): Record<string, string>;
     private assertActive;
-    /** Tear down every process and release the Nodepod instance. */
+    /** Tear down every process and release the runtime pod. */
     dispose(): void;
     get isDisposed(): boolean;
 }
@@ -2114,17 +2122,16 @@ interface RootfsOptions {
 declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
 
 /**
- * The Node.js runtime, backed by Nodepod.
+ * The Node.js command adapter, backed by the clean-room RuntimePod.
  *
- * Nodepod runs the script in an isolated worker over the *same* memory volume
+ * The pod runs the script over the *same* memory volume
  * the container's filesystem uses, so `require('fs')` inside a script sees the
  * files `echo` and `tar` created, and anything the script writes is visible to
  * the shell afterwards.
  *
- * Two gaps in the underlying `spawn` are papered over here:
+ * Two details of the underlying `spawn` are handled here:
  *  - only `node` resolves as a command, so everything else is dispatched by our
- *    own kernel rather than being handed to Nodepod's shell (which hangs on an
- *    unknown command);
+ *    own kernel rather than being handed to the Node process runner;
  *  - the worker's stdin has no end-of-stream signal, so when a pipeline feeds
  *    a script we materialise stdin as a file and install a real stdin stream
  *    over it before the script loads.
@@ -2427,6 +2434,8 @@ declare class VirtualHttpRouter {
     onListen: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
+    /** Whether anything in this container is listening on `port`. */
+    activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
@@ -2444,6 +2453,7 @@ interface CoreModulesOptions {
     http?: {
         router: VirtualHttpRouter;
         owner: string;
+        fetch?: typeof globalThis.fetch;
     };
     /** Backs `child_process`; without it the module reports as unavailable. */
     spawnChild?: SpawnChild;
@@ -2484,6 +2494,16 @@ declare function createCoreModules(options: CoreModulesOptions): {
      * script that has simply finished.
      */
     pendingHandles(): number;
+    /** Active timers which called `unref()` and therefore only merit startup grace. */
+    pendingUnrefed(): number;
+    /**
+     * Client requests sent but not yet read to completion.
+     *
+     * An outbound request is event-loop work in exactly the way a timer is, and
+     * it schedules no timer of its own. Counting it is what stops a program from
+     * exiting in the gap between `http.get` and its response callback.
+     */
+    pendingRequests(): number;
 };
 
 interface EsmTransformResult {
@@ -2570,9 +2590,20 @@ declare class LocalRuntimePod implements RuntimePod {
     private readonly aliases;
     private readonly modules;
     private readonly esbuild;
+    private rolldownBinding;
+    /** Backs outbound `http`/`https` client requests from inside the sandbox. */
+    private readonly fetch;
     private constructor();
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    /**
+     * Rolldown's JavaScript API synchronously requires its compiled binding.
+     * When a project contains Rolldown, preload the official WASI build in the
+     * host and expose it through the module override table before evaluation.
+     * Keeping this demand-driven avoids adding WASM startup cost to ordinary
+     * shells and Node programs.
+     */
+    private prepareRolldown;
     /**
      * Wait until the process has either started serving or genuinely run out of
      * work.
@@ -2607,6 +2638,10 @@ interface RegistryManifest {
     };
     dependencies?: Record<string, string>;
     optionalDependencies?: Record<string, string>;
+    os?: string[];
+    cpu?: string[];
+    libc?: string[];
+    main?: string;
     bin?: string | Record<string, string>;
 }
 interface CleanInstallerOptions {