Platforms

JavaScript

The JS host runs a program in a web page. createWorker boots the engine in a Web Worker inside a sandboxed frame of its own. Everything else is a call on the worker it returns.

Load the host

The host loads from one module on the CDN.

Import createWorker from it and hand it the directory of the program.

<script type="module">
  import { createWorker } from "https://cdn.edgepython.com/js/src/index.js";

  const worker = await createWorker({ baseUrl: new URL("./app/", location.href).href });
  worker.onOutput((text) => console.log(text));
  const src = await fetch("./app/main.py").then((r) => r.text());
  await worker.run(src);
</script>

A worker runs one program. The page draws itself, and the program answers through what it prints and what run resolves with.

The worker it returns carries these calls.

Every call returns a promise except pushEvent, the two handlers and dispose. dispose rejects every pending call with worker disposed.

Run a program

run(src, opts) takes the source as a string. The second argument is optional.

A script in a subdirectory passes its path, as in worker.run(src, { entry: "sub/main.py" }). Passing baseUrl to run rejects with baseUrl belongs to createWorker, a worker runs one program.

run resolves with { out, ms, exitCode }.

• out holds the traceback when the run fails, and is empty otherwise. Printed text arrives through onOutput.
• ms is how long the run took, in milliseconds.
• exitCode is set when the program raised SystemExit with an integer code.

Files and imports

The page reads for the worker the edge.json at baseUrl, its imports and what it grants, and each file a run imports.

• It never reads outside that directory.
• It never sends the cookies of the page.
• A worker keeps every module it fetched in memory for its lifetime. Repeat runs make no network requests until clearCache() empties it.
• fs lists the files of a page from edge.files, a JSON list beside edge.json. edge build --web writes it and edge serve answers it. A page that embeds the engine serves it itself.

How an import resolves is on Modules. What fs reads is on System.

Permissions and secrets

A page with an edge.json at baseUrl takes its grants from there. A page without one passes imports and permissions to createWorker instead. The values secret reads go in secrets, and each is read only under a name the permissions grant.

const worker = await createWorker({
  baseUrl: new URL("./app/", location.href).href,
  imports: { calc: "./calc.py" },
  permissions: { main: ["net:api.example.com", "secret:API_KEY"] },
  secrets: { API_KEY: key },
});

The holders and entries a permissions section takes are on System.

Limits

limits raises or lowers what a run may hold and spend.

const worker = await createWorker({ limits: { memory: 512, ops: 1e9 } });

• memory caps what a run holds, in MB.
• ops caps how many operations it runs.
• A field left out keeps the sandbox value of 256 MB and 100,000,000 operations.
• The call depth stays fixed at 256.

The old heap and calls fields are gone. createWorker throws when it meets either, naming what replaced it. Each cap and the error it raises are on Limits and errors.

Events

pushEvent(message) hands a string to the receive() queue of the running program. Any other value is turned into a string first. A message pushed before the program parks waits and arrives at its next receive().

onOutput(handler) receives each piece of text the program prints. A worker holds one handler at a time. A later call replaces it.

Pause and snapshots

A run can be paused, frozen to a blob and brought back later. What a blob holds and where a run can freeze are on Snapshots.

• setPreemptInterval(n) makes the VM yield every n loop back-edges. It takes effect at the next run or restoreState. 0 turns preemption off and is the default.
• pause() resolves true once the run is parked. It resolves false when no run reaches a park, because it already finished or none started.
• resume() lets a parked run go again.
• saveState() resolves with a Uint8Array holding the whole VM. It rejects with nothing to save: the program is not paused while the run executes.
• restoreState(blob) takes a Uint8Array or an ArrayBuffer. It resolves like run once the program finishes, and the run keeps the limits saved in the blob.
• stateGlobals() and stateStack() read a parked run without waking it.

A preempt interval lets pause() stop a program with no suspension point at all.

# counter.py, no suspension point anywhere
n = 0
while True:
    n += 1
    if n % 1_000_000 == 0:
        print(n)

const worker = await createWorker();
await worker.setPreemptInterval(50_000); // ~1 yield per 50k loop iterations

worker.run(counterSrc); // never awaited, it runs forever

await worker.pause(); // resolves true once parked, mid-loop
const blob = await worker.saveState();
await worker.stateGlobals(); // { n: "3170000" }
worker.resume(); // keeps counting from 3170000

The yields are invisible. The run continues on its own, and the host only notices when it asks to stop.

Pick n for how fast a pause has to land. Each yield is one event loop round trip. Browsers clamp it to a few milliseconds.

Persisting a run

saveState returns opaque bytes. Any store that holds bytes keeps a blob, and none of them runs the VM.

The page below checkpoints a counter into Cache Storage every five seconds. On load it resumes the saved session when one exists and otherwise starts fresh.

<script type="module">
  import { createWorker } from "https://cdn.edgepython.com/js/src/index.js";

  const worker = await createWorker();
  const store = await caches.open("edge-python");
  const KEY = "/session";

  await worker.setPreemptInterval(50000);
  const hit = await store.match(KEY);
  hit
    ? worker.restoreState(new Uint8Array(await hit.arrayBuffer()))
    : worker.run(await fetch("./counter.py").then((r) => r.text()));

  const checkpoint = async () => {
    if (!await worker.pause()) return; // the run already finished
    await store.put(KEY, new Response(await worker.saveState()));
    worker.resume();
  };

  setInterval(checkpoint, 5000);
  addEventListener("visibilitychange", () => document.hidden && checkpoint());
</script>

The interval is what protects the session.

visibilitychange is the last event that reliably fires on mobile. Its handler is async, and the browser can kill the page before the write lands. The rolling checkpoint is the guarantee, and the handler only shortens what a close costs.

Other stores take the same bytes.

// A download the user keeps.
const file = new Blob([await worker.saveState()], { type: "application/octet-stream" });
const url = URL.createObjectURL(file);
Object.assign(document.createElement("a"), { href: url, download: "cart.snapshot" }).click();
URL.revokeObjectURL(url);

// A file the user picks.
worker.restoreState(new Uint8Array(await fileInput.files[0].arrayBuffer()));

// IndexedDB keeps a Uint8Array directly, a server takes the raw bytes.
await store.put("cart", await worker.saveState());
await fetch("/saves/cart", { method: "PUT", body: await worker.saveState() });

A server works the same way as a local store. It only holds bytes.

const res = await fetch(`/saves/${userId}`);
if (res.ok) {
  worker.restoreState(new Uint8Array(await res.arrayBuffer())); // continue the held session
} else {
  worker.run(cartSrc); // no save yet, start fresh
}

The sandboxed frame

Every worker lives in a sandboxed frame with an opaque origin of its own.

• A program holds none of the cookies or storage of the page.
• It cannot reach the DOM of the page, even a DOM the page did not write.
• The page fetches the engine and hands it to the frame. The frame loads no code of its own.
• The page reads the files of the program for the frame, only under baseUrl and without cookies.

The browser lets the frame connect only where the program may go.

• The origins its imports name, and where each release in its edge.lock lives.
• The hosts its permissions grant, on http, https, ws and wss and any port.

A request the grants would miss never leaves the frame. A path prefix in a grant is checked by the engine, since a frame policy names only a whole host.

Trace

A worker created with trace: true reports every system call of a run through onTrace. Each event is timed in milliseconds from the start of the run.

const worker = await createWorker({ trace: true, permissions: { main: ["net:api.example.com"] } });
worker.onTrace((event) => console.log(event));
// { kind: "call", at: 2.4, ms: 181, pkg: "main", call: "net.response", scope: "", outcome: "ok", id: 1, status: 200 }

A call names the package, the call, what it reached and how it ended. outcome is ok or the name of the error.

An event never carries a body, a header or a query. A secret value that shows up in a scope or a print is masked. A value of eight characters or more shows its first two, and a shorter one shows none.

A batch reports as one call. The calls inside it are not listed one by one. A worker without trace pays one check per call.

See also