ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / nodejs-docs-16.20.2 / doc / api

# WebAssembly System Interface (WASI)

> Stability: 1 - Experimental

The WASI API provides an implementation of the [WebAssembly System Interface][]
specification. WASI gives sandboxed WebAssembly applications access to the
underlying operating system via a collection of POSIX-like functions.

```mjs
import { readFile } from 'node:fs/promises';
import { WASI } from 'wasi';
import { argv, env } from 'node:process';

const wasi = new WASI({
  args: argv,
  env,
  preopens: {
    '/sandbox': '/some/real/path/that/wasm/can/access'
  }
});

// Some WASI binaries require:
//   const importObject = { wasi_unstable: wasi.wasiImport };
const importObject = { wasi_snapshot_preview1: wasi.wasiImport };

const wasm = await WebAssembly.compile(
  await readFile(new URL('./demo.wasm', import.meta.url))
);
const instance = await WebAssembly.instantiate(wasm, importObject);

wasi.start(instance);
```

```cjs
'use strict';
const { readFile } = require('node:fs/promises');
const { WASI } = require('wasi');
const { argv, env } = require('node:process');
const { join } = require('node:path');

const wasi = new WASI({
  args: argv,
  env,
  preopens: {
    '/sandbox': '/some/real/path/that/wasm/can/access'
  }
});

// Some WASI binaries require:
//   const importObject = { wasi_unstable: wasi.wasiImport };
const importObject = { wasi_snapshot_preview1: wasi.wasiImport };

(async () => {
  const wasm = await WebAssembly.compile(
    await readFile(join(__dirname, 'demo.wasm'))
  );
  const instance = await WebAssembly.instantiate(wasm, importObject);

wasi.start(instance);
})();
```

To run the above example, create a new WebAssembly text format file named
`demo.wat`:

```text
(module
    ;; Import the required fd_write WASI function which will write the given io vectors to stdout
    ;; The function signature for fd_write is:
    ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written
    (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32)))

(memory 1)
    (export "memory" (memory 0))

;; Write 'hello world\n' to memory at an offset of 8 bytes
    ;; Note the trailing newline which is required for the text to appear
    (data (i32.const 8) "hello world\n")

(func $main (export "_start")
        ;; Creating a new io vector within linear memory
        (i32.store (i32.const 0) (i32.const 8))  ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string
        (i32.store (i32.const 4) (i32.const 12))  ;; iov.iov_len - The length of the 'hello world\n' string

(call $fd_write
            (i32.const 1) ;; file_descriptor - 1 for stdout
            (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0
            (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.
            (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written
        )
        drop ;; Discard the number of bytes written from the top of the stack
    )
)
```

Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`

```console
$ wat2wasm demo.wat
```

The `--experimental-wasi-unstable-preview1` CLI argument is needed for this
example to run.

## Class: `WASI`

The `WASI` class provides the WASI system call API and additional convenience
methods for working with WASI-based applications. Each `WASI` instance
represents a distinct sandbox environment. For security purposes, each `WASI`
instance must have its command-line arguments, environment variables, and
sandbox directory structure configured explicitly.

### `new WASI([options])`

* `options` {Object}
  * `args` {Array} An array of strings that the WebAssembly application will
    see as command-line arguments. The first argument is the virtual path to the
    WASI command itself. **Default:** `[]`.
  * `env` {Object} An object similar to `process.env` that the WebAssembly
    application will see as its environment. **Default:** `{}`.
  * `preopens` {Object} This object represents the WebAssembly application's
    sandbox directory structure. The string keys of `preopens` are treated as
    directories within the sandbox. The corresponding values in `preopens` are
    the real paths to those directories on the host machine.
  * `returnOnExit` {boolean} By default, WASI applications terminate the Node.js
    process via the `__wasi_proc_exit()` function. Setting this option to `true`
    causes `wasi.start()` to return the exit code rather than terminate the
    process. **Default:** `false`.
  * `stdin` {integer} The file descriptor used as standard input in the
    WebAssembly application. **Default:** `0`.
  * `stdout` {integer} The file descriptor used as standard output in the
    WebAssembly application. **Default:** `1`.
  * `stderr` {integer} The file descriptor used as standard error in the
    WebAssembly application. **Default:** `2`.

### `wasi.start(instance)`

* `instance` {WebAssembly.Instance}

Attempt to begin execution of `instance` as a WASI command by invoking its
`_start()` export. If `instance` does not contain a `_start()` export, or if
`instance` contains an `_initialize()` export, then an exception is thrown.

`start()` requires that `instance` exports a [`WebAssembly.Memory`][] named
`memory`. If `instance` does not have a `memory` export an exception is thrown.

If `start()` is called more than once, an exception is thrown.

### `wasi.initialize(instance)`

* `instance` {WebAssembly.Instance}

Attempt to initialize `instance` as a WASI reactor by invoking its
`_initialize()` export, if it is present. If `instance` contains a `_start()`
export, then an exception is thrown.

`initialize()` requires that `instance` exports a [`WebAssembly.Memory`][] named
`memory`. If `instance` does not have a `memory` export an exception is thrown.

If `initialize()` is called more than once, an exception is thrown.

### `wasi.wasiImport`

* {Object}

`wasiImport` is an object that implements the WASI system call API. This object
should be passed as the `wasi_snapshot_preview1` import during the instantiation
of a [`WebAssembly.Instance`][].

[WebAssembly System Interface]: https://wasi.dev/
[`WebAssembly.Instance`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance
[`WebAssembly.Memory`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory

[-] async_context.json [edit]
[-] process.md [edit]
[-] tracing.html [edit]
[-] addons.json [edit]
[-] webstreams.html [edit]
[-] debugger.md [edit]
[-] debugger.html [edit]
[-] tls.json [edit]
[-] inspector.md [edit]
[-] child_process.json [edit]
[-] packages.html [edit]
[-] events.md [edit]
[-] synopsis.html [edit]
[-] inspector.html [edit]
[-] dgram.json [edit]
[-] cli.html [edit]
[-] test.json [edit]
[-] repl.md [edit]
[-] worker_threads.md [edit]
[-] webcrypto.html [edit]
[-] readline.html [edit]
[-] crypto.html [edit]
[-] events.json [edit]
[-] esm.html [edit]
[-] querystring.md [edit]
[-] http.html [edit]
[-] buffer.md [edit]
[-] http2.md [edit]
[-] http.json [edit]
[-] documentation.json [edit]
[-] domain.json [edit]
[-] domain.html [edit]
[-] embedding.md [edit]
[-] cluster.md [edit]
[-] corepack.json [edit]
[-] errors.md [edit]
[-] modules.json [edit]
[-] string_decoder.md [edit]
[-] v8.md [edit]
[-] n-api.html [edit]
[-] module.md [edit]
[-] querystring.json [edit]
[+] ..
[-] querystring.html [edit]
[-] fs.json [edit]
[-] punycode.md [edit]
[-] esm.json [edit]
[-] test.html [edit]
[-] repl.json [edit]
[-] async_hooks.html [edit]
[-] async_hooks.md [edit]
[-] permissions.md [edit]
[-] util.md [edit]
[-] zlib.json [edit]
[-] synopsis.md [edit]
[-] vm.md [edit]
[-] tty.md [edit]
[-] child_process.html [edit]
[-] embedding.html [edit]
[-] stream.html [edit]
[-] report.json [edit]
[-] report.md [edit]
[-] policy.html [edit]
[-] policy.json [edit]
[-] index.md [edit]
[-] addons.html [edit]
[-] worker_threads.html [edit]
[-] path.json [edit]
[-] zlib.md [edit]
[-] buffer.html [edit]
[-] perf_hooks.json [edit]
[-] v8.json [edit]
[-] modules.html [edit]
[-] diagnostics_channel.json [edit]
[-] crypto.json [edit]
[-] corepack.html [edit]
[-] index.html [edit]
[-] os.md [edit]
[-] async_context.html [edit]
[-] readline.json [edit]
[-] async_context.md [edit]
[-] inspector.json [edit]
[-] report.html [edit]
[-] repl.html [edit]
[-] assert.html [edit]
[-] test.md [edit]
[-] packages.json [edit]
[-] perf_hooks.md [edit]
[-] deprecations.md [edit]
[-] intl.json [edit]
[-] webstreams.json [edit]
[-] globals.md [edit]
[-] string_decoder.html [edit]
[-] cluster.html [edit]
[-] perf_hooks.html [edit]
[-] dns.md [edit]
[-] punycode.html [edit]
[-] wasi.json [edit]
[-] n-api.md [edit]
[-] process.html [edit]
[-] dgram.md [edit]
[-] tty.html [edit]
[-] async_hooks.json [edit]
[-] tty.json [edit]
[-] path.md [edit]
[-] dgram.html [edit]
[-] console.json [edit]
[-] intl.html [edit]
[-] tracing.json [edit]
[-] vm.json [edit]
[-] webcrypto.md [edit]
[-] url.html [edit]
[-] console.md [edit]
[-] permissions.json [edit]
[-] synopsis.json [edit]
[-] corepack.md [edit]
[-] embedding.json [edit]
[-] dns.json [edit]
[-] https.md [edit]
[-] documentation.html [edit]
[-] module.json [edit]
[-] process.json [edit]
[-] esm.md [edit]
[-] util.html [edit]
[-] tls.md [edit]
[-] webcrypto.json [edit]
[-] net.json [edit]
[-] http2.json [edit]
[-] cluster.json [edit]
[-] permissions.html [edit]
[-] http2.html [edit]
[-] deprecations.json [edit]
[-] stream.md [edit]
[-] https.json [edit]
[-] url.md [edit]
[-] vm.html [edit]
[-] wasi.md [edit]
[+] assets
[-] diagnostics_channel.html [edit]
[-] stream.json [edit]
[-] all.html [edit]
[-] punycode.json [edit]
[-] url.json [edit]
[-] errors.html [edit]
[-] cli.md [edit]
[-] buffer.json [edit]
[-] worker_threads.json [edit]
[-] globals.html [edit]
[-] string_decoder.json [edit]
[-] console.html [edit]
[-] v8.html [edit]
[-] diagnostics_channel.md [edit]
[-] debugger.json [edit]
[-] child_process.md [edit]
[-] deprecations.html [edit]
[-] os.html [edit]
[-] wasi.html [edit]
[-] domain.md [edit]
[-] os.json [edit]
[-] readline.md [edit]
[-] webstreams.md [edit]
[-] tls.html [edit]
[-] index.json [edit]
[-] intl.md [edit]
[-] tracing.md [edit]
[-] zlib.html [edit]
[-] packages.md [edit]
[-] all.json [edit]
[-] assert.json [edit]
[-] fs.html [edit]
[-] errors.json [edit]
[-] documentation.md [edit]
[-] policy.md [edit]
[-] n-api.json [edit]
[-] timers.html [edit]
[-] cli.json [edit]
[-] modules.md [edit]
[-] http.md [edit]
[-] util.json [edit]
[-] fs.md [edit]
[-] timers.md [edit]
[-] globals.json [edit]
[-] assert.md [edit]
[-] module.html [edit]
[-] dns.html [edit]
[-] net.md [edit]
[-] events.html [edit]
[-] timers.json [edit]
[-] https.html [edit]
[-] crypto.md [edit]
[-] path.html [edit]
[-] addons.md [edit]
[-] net.html [edit]