wasi: introduce initial WASI support

Co-authored-by: Gus Caplan <me@gus.host>
Co-authored-by: Daniel Bevenius <daniel.bevenius@gmail.com>
Co-authored-by: Jiawen Geng <technicalcute@gmail.com>
Co-authored-by: Tobias Nießen <tniessen@tnie.de>
Co-authored-by: Chengzhong Wu <legendecas@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/30258
Refs: https://github.com/nodejs/node/pull/27850
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Wyatt Preul <wpreul@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>

5 files changed, 107 insertions, 0 deletions

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 333ecd4e09..fa600336b7 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -230,6 +230,13 @@ added: v9.6.0
 
 Enable experimental ES Module support in the `vm` module.
 
+### `--experimental-wasi-unstable-preview0`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental WebAssembly System Interface (WASI) support.
+
 ### `--experimental-wasm-modules`
 <!-- YAML
 added: v12.3.0
@@ -1048,6 +1055,7 @@ Node.js options that are allowed are:
 * `--experimental-report`
 * `--experimental-resolve-self`
 * `--experimental-vm-modules`
+* `--experimental-wasi-unstable-preview0`
 * `--experimental-wasm-modules`
 * `--force-context-aware`
 * `--force-fips`
diff --git a/doc/api/errors.md b/doc/api/errors.md
index f2aace2c5e..bdfd0df4a7 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -1992,6 +1992,11 @@ The fulfilled value of a linking promise is not a `vm.Module` object.
 The current module's status does not allow for this operation. The specific
 meaning of the error depends on the specific function.
 
+<a id="ERR_WASI_ALREADY_STARTED"></a>
+### ERR_WASI_ALREADY_STARTED
+
+The WASI instance has already started.
+
 <a id="ERR_WORKER_INVALID_EXEC_ARGV"></a>
 ### ERR_WORKER_INVALID_EXEC_ARGV
 
diff --git a/doc/api/index.md b/doc/api/index.md
index ceb3ce7f19..6a39e2102c 100644
--- a/doc/api/index.md
+++ b/doc/api/index.md
@@ -57,6 +57,7 @@
 * [Utilities](util.html)
 * [V8](v8.html)
 * [VM](vm.html)
+* [WASI](wasi.html)
 * [Worker Threads](worker_threads.html)
 * [Zlib](zlib.html)
 
diff --git a/doc/api/wasi.md b/doc/api/wasi.md
new file mode 100644
index 0000000000..69afa83620
--- /dev/null
+++ b/doc/api/wasi.md
@@ -0,0 +1,90 @@
+# WebAssembly System Interface (WASI)
+
+<!--introduced_in=REPLACEME-->
+
+> 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_unstable: 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-preview0` and `--experimental-wasm-bigint`
+CLI arguments are needed for the previous example to run.
+
+## Class: WASI
+<!-- YAML
+added: REPLACEME
+-->
+
+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: REPLACEME
+-->
+
+* `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.
+
+### wasi.start(instance)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `instance` {WebAssembly.Instance}
+
+Attempt to begin execution of `instance` by invoking its `_start()` export.
+If `instance` does not contain a `_start()` export, then `start()` attempts to
+invoke the `__wasi_unstable_reactor_start()` export. If neither of those exports
+is present on `instance`, then `start()` does nothing.
+
+`start()` requires that `instance` exports a [`WebAssembly.Memory`][] named
+`memory`. If `instance` does not have a `memory` export an exception is thrown.
+
+### wasi.wasiImport
+<!-- YAML
+added: REPLACEME
+-->
+
+* {Object}
+
+`wasiImport` is an object that implements the WASI system call API. This object
+should be passed as the `wasi_unstable` 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/
diff --git a/doc/node.1 b/doc/node.1
index e3628034e8..714772336e 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -141,6 +141,9 @@ Enable experimental support for a package to load itself.
 .It Fl -experimental-vm-modules
 Enable experimental ES module support in VM module.
 .
+.It Fl -experimental-wasi-unstable-preview0
+Enable experimental WebAssembly System Interface support.
+.
 .It Fl -experimental-wasm-modules
 Enable experimental WebAssembly module support.
 .