IsolateEngine

(no submodules)

Purpose

IsolateEngine implements the SandboxEngine contract over a structural IsolateFactory interface that mirrors the isolated-vm package's API. This keeps isolated-vm an optional peer dependency: consumers who want its stronger isolation guarantees wire their own factory backed by new ivm.Isolate(...), consumers who don't pay no install cost. Tests use a hand-written fake factory that satisfies the same structural contract.

isolated-vm provides genuine V8 isolate separation — a separate heap, separate intrinsics, hard memory + timeout limits enforced inside V8 itself. When a consumer needs stronger isolation than vm-engine offers but cannot afford the per-call cost of worker-engine or spawn-engine, IsolateEngine plus a real isolated-vm factory is the right pick.

Features

Structural IsolateFactory / IsolateInstance / IsolateContext / IsolateReference / IsolateScript interfaces.
executeSync companion for pool callers.
Captured console via injected __log/__warn/__error proxies.
Module + context-variable injection.
Heap stats via getHeapStatisticsSync (returns null after destroy).
reset disposes + re-creates the underlying isolate.

Usage: Basic

import ivm from "isolated-vm";
import { IsolateEngine } from "@suaveplan/sandbox/isolate-engine";

const engine = new IsolateEngine({
    timeout: 5000,
    maxOutputSize: 1024,
    memoryLimit: 32 * 1024 * 1024,
    factory: {
        createIsolate: (memLimit) =>
            new ivm.Isolate({ memoryLimit: memLimit / (1024 * 1024) }),
    },
});

Usage: Advanced

Provide a custom factory backed by a test double for deterministic unit tests:

import { IsolateEngine } from "@suaveplan/sandbox/isolate-engine";

const engine = new IsolateEngine({
    timeout: 5000,
    maxOutputSize: 1024,
    memoryLimit: 32 * 1024 * 1024,
    factory: {
        createIsolate: () => myDeterministicIsolate,
    },
});

API Reference

IsolateFactory — createIsolate(memoryLimit): IsolateInstance.
IsolateInstance — createContextSync, compileScriptSync, getHeapStatisticsSync, dispose.
IsolateContext — global: IsolateReference, release.
IsolateReference — setSync, getSync.
IsolateScript — runSync(context, { timeout? }).
new IsolateEngine(options: IsolateEngineOptions).
execute, executeSync, registerModule, unregisterModule, getHeapStatistics, reset, destroy.

Implementation Notes

The console proxy is set up by injecting three reference functions (__log/__warn/__error) into the isolate's global, then prepending a const console = { log: ..., warn: ..., error: ... } to the compiled script. The real isolated-vm API serialises across the realm boundary with ExternalCopy and Reference; the structural type intentionally does not prescribe that machinery because consumer adapters may wrap arguments differently depending on their isolation needs.

3.0 KiB Raw Blame History