Workers ■Available

A Velyr worker is a separate isolate on its own OS thread, with its own JS heap, microtask queue, event loop, permission context and quota context (ADR-010, ADR-014, docs/specs/worker-api.md). Nothing mutable is shared between isolates: workers talk to the parent by message passing.

Quick start#

const worker = new Worker(new URL("./square.mjs", import.meta.url), { type: "module" });

worker.onmessage = (event) => {
  console.log(event.data); // 4, 9, 16
};
for (const n of [2, 3, 4]) worker.postMessage(n);

self.onmessage = (event) => {
  self.postMessage(event.data * event.data);
};

velyr run main.mjs

A worker that is still alive keeps the parent running. Call worker.terminate() when you are done, or Velyr.unrefWorker(worker) to let the parent exit while the worker runs.

JS API#

Inside a worker the global object also provides self, name, postMessage, close, reportError, and addEventListener/removeEventListener/dispatchEvent. Workers can spawn workers.

Permissions#

A worker never gains authority its parent lacks. The effective set is:

effective = parent ∩ requested ∩ deployment_policy

• With no velyr.permissions, the worker may use whatever its parent can.
• With velyr.permissions, the object uses the same grammar as the CLI flags and the permissions block of velyr.json (kebab-case keys such as "allow-env"), and can only narrow what the parent holds.
• The velyr run CLI has no separate deployment policy source, so the policy is the main isolate's own authority.

const worker = new Worker(new URL("./job.mjs", import.meta.url), {
  type: "module",
  velyr: { permissions: { "allow-env": ["HOME"] } },
});

Run as velyr run --allow-env=HOME,USER narrow.mjs, the worker sees HOME but not USER. Run with only --allow-env=HOME, a worker that asks for "allow-all": true still gets only HOME. Both cases are covered by crates/cli/tests/workers.rs.

Messages and structured clone#

Messages are serialized with the engine's structured clone (V8's ValueSerializer in engine-v8) into a SerializedValue, moved over a channel, and deserialized in the receiving isolate. Ports can be transferred.

Each channel has a bounded queue. When it is full, postMessage fails with VELYR_QUOTA_EXCEEDED instead of letting memory grow (limit 10000 in the test fixture).

Resource quotas#

Quotas are per-class counters that fail an operation with QuotaExceeded rather than exhausting the host. They come from the runtime-resources crate and are set with the quotas key of velyr.json; unset classes use the defaults.

{
  "quotas": { "workers": 4, "timers": 10000 }
}

Each worker reserves one workers unit from its parent's quota for as long as its thread runs. A worker's heap limit never exceeds the parent's, and nested workers inherit it. For the config schema see Configuration.

Termination#

terminate() follows the spec order: new worker ops start failing and the shutdown token is cancelled; running JS is interrupted; the event loop stops and discards late completions; the op context closes every resource the worker held; the isolate is destroyed. A worker stuck in a busy loop is stopped this way (terminate_stops_a_busy_worker in the CLI tests).

Not implemented#

• Classic workers (type: "classic", importScripts).
• Explicit shared memory. The default is no shared mutable JS state; docs/architecture/scheduler-workers.md treats shared memory as a separate future feature with its own semantics.
• Internal server workers for multicore serving. The public Worker API and the planned server scheduler are separate layers by design.