Isolates

An Isolate runs a module you don't control: a customer's pricing rule, a third-party plugin, code a model generated. It has its own V8 heap and shares a small pool of threads with every other isolate, so a process can hold thousands of them.

An isolate computes, and nothing else. It holds no capability and can be granted none: no files, no network, no environment. It reaches the outside only through the host functions you hand it.

JavaScript
import { Isolate } from "runtime:workers";

const rule = new Isolate({
  source: "export const discount = (order) => (order.total > 500 ? 0.1 : 0);",
  name: "acme-discount",
});
const { discount } = await rule.exports;
console.log(await discount({ total: 600 })); // 0.1
rule.terminate();
Shell
esrun --allow-workers main.js

When to use one

You needUse
Many small pieces of someone else's code, each kept apartIsolate
Heavy work spread across every core, or code that blocksWorker
State that outlives the process, one owner per idDurable workers

Starting one

From a string, such as code kept in a database:

JavaScript
new Isolate({ source: code, name: "rule-42" });

From a file:

JavaScript
new Isolate(new URL("./plugins/upper.js", import.meta.url));

Starting an isolate needs --allow-workers. Starting one from a file also reads that file, so it needs --allow-imports too, as a Worker does. The file's static imports load with it. A module made from a string has no directory, so it can import only runtime: modules.

Calling it

isolate.exports resolves, once the module has evaluated, to its exported functions. Each call is async. Its arguments and its result are copied by structured clone, as postMessage copies a message.

JavaScript
const { transform } = await plugin.exports;
const html = await transform(markdown);

An error thrown inside keeps its class, message and code:

JavaScript
try {
  await validate(input);
} catch (e) {
  if (e instanceof RangeError && e.code === "ERR_LIMIT") retryLater();
}

A result that can't be cloned, such as a function, rejects with a DataCloneError.

Handing it what it needs: host

host is how an isolate reaches the outside. Each function you pass runs in your program, with your program's permissions, and the isolate calls it by name:

JavaScript
// main.js
const plugin = new Isolate(new URL("./plugin.js", import.meta.url), {
  host: {
    log: (...args) => console.log("[plugin]", ...args),
    config: async (key) => settings[key],
  },
});

// plugin.js
import { host } from "runtime:workers";

export async function transform(text) {
  await host.log("transforming", text.length);
  return (await host.config("shout")) ? text.toUpperCase() : text;
}
A host function is a grant

A function in host can do whatever your program can. Hand over narrow ones: getUser(id) that fetches one record from one API, not fetch(url). A host function that takes a path and reads it gives the isolate your read permission by another route.

What runs inside

WorksRefused
Web standards: URL, TextEncoder, structuredClone, crypto, timers, consoleruntime:fs, fetch, runtime:net, runtime:db, runtime:http, env
runtime: modules that need no permission: path, serialization, hashing, pdf, images, archive on bytes passed inimport() of a file, starting a Worker or an Isolate, Atomics.wait

A refused call fails like any denied capability, with ERR_CAPABILITY_DENIED, and the message says what to do instead:

TEXT
capability denied: FileRead (permission "read") — an isolate is computation
only; pass it what it needs through a host function

Inside an isolate, runtime:workers exports only host.

Messages

postMessage and onmessage work as they do on a Worker, for one-way events:

JavaScript
const iso = new Isolate({ source: "onmessage = (e) => postMessage(e.data * 2);" });
iso.onmessage = (e) => console.log(e.data); // 42
iso.postMessage(21);

Memory and CPU

memory caps the isolate's heap, in megabytes, at no more than your program's own (and at least 8 MB, the least an isolate starts in), and caps its ArrayBuffer storage at the same size — buffers live outside the heap, so a heap limit alone would not hold them. Buffers that are garbage don't count once they are collected; until then, an isolate may briefly hold up to twice its memory in buffers. cpuTime caps how much CPU time, in milliseconds, one turn may use — one stretch of the isolate's code, from when it gets its thread until it next waits:

JavaScript
new Isolate(code, { memory: 32, cpuTime: 50 });

A loop that never ends, for (;;) await null included, is one turn, so it is stopped soon after its budget. Waiting is not in a turn: an isolate waiting on a host function or a timer uses none of it. Work that awaits between short pieces is never stopped, and never holds its thread either.

Past either limit the isolate is terminated. Its waiting calls reject with ERR_ISOLATE_CPU_LIMIT or ERR_ISOLATE_MEMORY_LIMIT, and later calls with ERR_ISOLATE_TERMINATED.

JavaScript
try {
  await rule.evaluate(order);
} catch (e) {
  if (e.code === "ERR_ISOLATE_CPU_LIMIT") disableRule(tenant);
}

Starting fast

An isolate takes a little under a millisecond to start. When a request is waiting on one, build some ahead of time:

JavaScript
await Isolate.prepare(32); // 32 isolates built and waiting

// Later: each of these claims one, and starts in tens of microseconds.
const rule = new Isolate({ source: code });

A prepared isolate is claimed only by an isolate without its own memory, since a memory ceiling is fixed when an isolate is made. Unclaimed ones don't keep the process running.

Ending

terminate() stops an isolate at once, even one stuck in a loop. Calls still waiting reject with ERR_ISOLATE_TERMINATED, and so does any later call.

A module that throws while it loads rejects exports and fires error:

JavaScript
iso.onerror = (e) => {
  e.preventDefault(); // handled here, so it is not logged
  report(e.error);
};

A live isolate keeps the process running, as a Worker does. Call terminate() when you are done with it, or unref() to let the process exit while it idles.

Limits

  • An isolate is not a hard security boundary. It keeps code apart from your program's data and permissions, not from attacks on the CPU itself.

  • Isolates on one pool thread take turns. Without cpuTime, a call that loops forever holds up the others on its thread until you terminate() it. Give isolates running code you don't control a cpuTime.

  • From inside an isolate, cwd() is refused, so resolve() of a relative path is too. join() and the rest of runtime:path work.

See the runtime:workers reference for every option, and Internals: Workers for how the pool works.

Last updated on
Edit this page