@runno/wasi NPM

A WASI runner for the web (`@runno/wasi`)

There are a bunch of different WASI runners out there, some of them even work in the browser. This one is focused on sandboxed emulation. Not system integration. It has been developed for the particular requirements of Runno, but you may find it useful as well.

This package allows you to run WASI binaries on the web with an emulated filesystem. If the binary receives calls to stdin/out/err then you get callbacks you'll need to handle. In future there may be other callbacks to intercept interesting system level events, or hooks into the filesystem.

Quickstart

The quickest way to get started with Runno is by using the WASI.start class method. It will set up everything you need and run the Wasm binary directly.

Be aware that this will run on the main thread, not inside a worker. So you will interrupt any interactive use of the browser until it completes.

import { WASI } from "@runno/wasi";

//...

const result = WASI.start(fetch("/binary.wasm"), {
  args: ["binary-name", "--do-something", "some-file.txt"],
  env: { SOME_KEY: "some value" },
  stdout: (out) => console.log("stdout", out),
  stderr: (err) => console.error("stderr", err),
  stdin: () => prompt("stdin:"),
  fs: {
    "/some-file.txt": {
      path: "/some-file.txt",
      timestamps: {
        access: new Date(),
        change: new Date(),
        modification: new Date(),
      },
      mode: "string",
      content: "Some content for the file.",
    },
  },
});

You can see a more complete example in src/main.ts.

Note: The args should start with the name of the binary. Like when you run a terminal command, you write cat somefile the name of the binary is cat.

Custom Instantiation

There are two parts to running a WASI binary with Runno. The WASI instance which represents the emulated system, and the WebAssembly runtime provided by the browser. If you'd like to customise the way the WebAssembly runtime is instantiated, you can split these parts up.

import { WASI } from "@runno/wasi";

// First set up the WASI emulated system
const wasi = new WASI({
  args: ["binary-name", "--do-something", "some-file.txt"],
  env: { SOME_KEY: "some value" },
  stdout: (out) => console.log("stdout", out),
  stderr: (err) => console.error("stderr", err),
  stdin: () => prompt("stdin:"),
  fs: {
    "/some-file.txt": {
      path: "/some-file.txt",
      timestamps: {
        access: new Date(),
        change: new Date(),
        modification: new Date(),
      },
      mode: "string",
      content: "Some content for the file.",
    },
  },
});

const myMemory = new WebAssembly.Memory({ initial: 32, maximum: 10000 });

// Then instantiate your binary with the imports provided by the wasi object
const wasm = await WebAssembly.instantiateStreaming(fetch("/binary.wasm"), {
  ...wasi.getImportObject(),

  // Your own custom imports (e.g. custom memory)
  env: {
    memory: myMemory,
  },
});

// Finally start the WASI binary (with the custom memory)
const result = wasi.start(wasm, {
  memory: myMemory,
});

If you are working with a Reactor instead of a command, you can instead use:

const exports = wasi.initialize(wasm, {
  memory: myMemory,
});

The returned exports will be the exports from your WebAssembly module.

Using the WASIWorker

A worker is provided for using the WASI runner outside of the main thread. It requires the availability of SharedArrayBuffer which is only available when the browser is Cross-Origin Isolated (see below).

Using the WASIWorkerHost

The WASIWorkerHost will create a worker and then communicate with it. In this mode stdin does not work as a callback, instead it must be pushed onto a buffer which is then handled asynchronously. See @runno/runtime for examples on how to do this.

import { WASIWorkerHost } from "@runno/wasi";

// ...

const workerHost = new WASIWorkerHost(binaryURL, {
  args: ["binary-name", "--do-something", "some-file.txt"],
  env: { SOME_KEY: "some value" },
  stdout: (out) => console.log("stdout", out),
  stderr: (err) => console.error("stderr", err),
  fs: {
    "/some-file.txt": {
      path: "/some-file.txt",
      timestamps: {
        access: new Date(),
        change: new Date(),
        modification: new Date(),
      },
      mode: "string",
      content: "Some content for the file.",
    },
  },
});

const result = await workerHost.start();

// ... Somewhere else

workerHost.pushStdin("Some text from the user");

The WASIWorkerHost will manage fetching the WASM binary and the WASIContext. If you've already fetched the binary you can use URL.createObjectURL to get a valid URL.

Cross-Origin Headers

To get SharedArrayBuffer to work on your page you must provide a Cross-Origin Isolated context.

To make your website Cross-Origin Isolated set the following headers in your HTTP response:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

You can test that your page is Cross-Origin Isolated by opening the browser console and checking crossOriginIsolated (see: mdn docs).

Initializing a WASI Reactor

Reactors are modules that respond to calls, rather than running as a command.

You can initialize a WASI Reactor with initialize instead of start:

import { WASI } from "@runno/wasi";

//...

const exports = WASI.initialize(fetch("/binary.wasm"), {
  args: ["binary-name", "--do-something", "some-file.txt"],
  env: { SOME_KEY: "some value" },
  stdout: (out) => console.log("stdout", out),
  stderr: (err) => console.error("stderr", err),
  stdin: () => prompt("stdin:"),
  fs: {
    "/some-file.txt": {
      path: "/some-file.txt",
      timestamps: {
        access: new Date(),
        change: new Date(),
        modification: new Date(),
      },
      mode: "string",
      content: "Some content for the file.",
    },
  },
});

The WASI.initialize call will return the exports from the WebAssembly module.

The filesystem

@runno/wasi internally emulates a unix-like filesystem (FS) from a flat structure. All files must start with a / to indicate they are in the root directory. The / directory is preopened by @runno/wasi for your WASI binary to use.

Paths provided to the FS can include directory names /like/this.png. The FS will treat files with the same prefix /like/so.png as if they are in the same folder. Any folders created will contain an empty .runno file /like/.runno as a placeholder.

WASI has a complex permissions system that is entirely ignored. All files you provide can be accessed by the WASI binary, with all permissions.

Which WASI standards are supported?

Currently @runno/wasi supports running only unstable and snapshot-preview1 WASI binaries. The snapshot-preview1 standard is more recent, and preferred. Additionally its likely some details of unstable have been missed. If you spot these, please file a bug.

Other extension standards like WASMEdge, and WASIX are currently not supported, but could be. WASI Modules are also not supported, but I'm interested in learning more about them.

Contributing

The most useful way to contribute to @runno/wasi is to add tests. Particularly if you find something that doesn't work!

Running Tests

If this is the first time running tests, please run the prepare script first. This will build the test programs and download existing test suites.

You'll need to have cargo installed to run the tests

$ npm run test:prepare

Then run the test suite:

$ npm run test

The test suite includes the following tests:

args - tests of program args (mine)
stdio - tests of stdio (mine)
wasi-test-suite https://github.com/caspervonb/wasi-test-suite
- core - the core WASI functionality called from assemblyscript
- libc - WASI functionality called from libc (C)
- libstd - WASI functionality called from libstd (Rust)
TODO wasi-tests https://github.com/bytecodealliance/wasmtime/tree/main/crates/test-programs/wasi-tests