mirror of
https://github.com/nodejs/node.git
synced 2024-11-29 15:06:33 +01:00
e3b54b4d1c
This commit adds stdin, stderr, and stdout options to WASI, which allow the stdio streams to be configured. PR-URL: https://github.com/nodejs/node/pull/33544 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com> Reviewed-By: Zeyu Yang <himself65@outlook.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com>
110 lines
3.8 KiB
Markdown
110 lines
3.8 KiB
Markdown
# WebAssembly System Interface (WASI)
|
|
|
|
<!--introduced_in=v12.16.0-->
|
|
|
|
> 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.
|
|
|
|
```js
|
|
'use strict';
|
|
const fs = require('fs');
|
|
const { WASI } = require('wasi');
|
|
const wasi = new WASI({
|
|
args: process.argv,
|
|
env: process.env,
|
|
preopens: {
|
|
'/sandbox': '/some/real/path/that/wasm/can/access'
|
|
}
|
|
});
|
|
const importObject = { wasi_snapshot_preview1: wasi.wasiImport };
|
|
|
|
(async () => {
|
|
const wasm = await WebAssembly.compile(fs.readFileSync('./binary.wasm'));
|
|
const instance = await WebAssembly.instantiate(wasm, importObject);
|
|
|
|
wasi.start(instance);
|
|
})();
|
|
```
|
|
|
|
The `--experimental-wasi-unstable-preview1` and `--experimental-wasm-bigint`
|
|
CLI arguments are needed for the previous example to run.
|
|
|
|
## Class: `WASI`
|
|
<!-- YAML
|
|
added:
|
|
- v13.3.0
|
|
- v12.16.0
|
|
-->
|
|
|
|
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])`
|
|
<!-- YAML
|
|
added:
|
|
- v13.3.0
|
|
- v12.16.0
|
|
-->
|
|
|
|
* `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)`
|
|
<!-- YAML
|
|
added:
|
|
- v13.3.0
|
|
- v12.16.0
|
|
-->
|
|
|
|
* `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.wasiImport`
|
|
<!-- YAML
|
|
added:
|
|
- v13.3.0
|
|
- v12.16.0
|
|
-->
|
|
|
|
* {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.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
|
|
[WebAssembly System Interface]: https://wasi.dev/
|