22

✏️ Editing: wasi.json

{
 "type": "module",
 "source": "doc/api/wasi.md",
 "modules": [
 {
 "textRaw": "WebAssembly System Interface (WASI)",
 "name": "webassembly_system_interface_(wasi)",
 "introduced_in": "v12.16.0",
 "stability": 1,
 "stabilityText": "Experimental",
 "desc": "Source Code: <a href=\"https://github.com/nodejs/node/blob/v12.22.12/lib/wasi.js\">lib/wasi.js</a>\nThe WASI API provides an implementation of the <a href=\"https://wasi.dev/\">WebAssembly System Interface</a>\nspecification. WASI gives sandboxed WebAssembly applications access to the\nunderlying operating system via a collection of POSIX-like functions.\n<pre><code class=\"language-js\">'use strict';\nconst fs = require('fs');\nconst { WASI } = require('wasi');\nconst wasi = new WASI({\n args: process.argv,\n env: process.env,\n preopens: {\n '/sandbox': '/some/real/path/that/wasm/can/access'\n }\n});\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\n(async () => {\n const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));\n const instance = await WebAssembly.instantiate(wasm, importObject);\n\n wasi.start(instance);\n})();\n</code></pre>\nTo run the above example, create a new WebAssembly text format file named\n<code>demo.wat</code>:\n<pre><code class=\"language-text\">(module\n ;; Import the required fd_write WASI function which will write the given io vectors to stdout\n ;; The function signature for fd_write is:\n ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written\n (import \"wasi_snapshot_preview1\" \"fd_write\" (func $fd_write (param i32 i32 i32 i32) (result i32)))\n\n (memory 1)\n (export \"memory\" (memory 0))\n\n ;; Write 'hello world\\n' to memory at an offset of 8 bytes\n ;; Note the trailing newline which is required for the text to appear\n (data (i32.const 8) \"hello world\\n\")\n\n (func $main (export \"_start\")\n ;; Creating a new io vector within linear memory\n (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\\n' string\n (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\\n' string\n\n (call $fd_write\n (i32.const 1) ;; file_descriptor - 1 for stdout\n (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0\n (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.\n (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written\n )\n drop ;; Discard the number of bytes written from the top of the stack\n )\n)\n</code></pre>\nUse <a href=\"https://github.com/WebAssembly/wabt\">wabt</a> to compile <code>.wat</code> to <code>.wasm</code>\n<pre><code class=\"language-console\">$ wat2wasm demo.wat\n</code></pre>\nThe <code>--experimental-wasi-unstable-preview1</code> and <code>--experimental-wasm-bigint</code>\nCLI arguments are needed for this example to run.",
 "classes": [
 {
 "textRaw": "Class: `WASI`",
 "type": "class",
 "name": "WASI",
 "meta": {
 "added": [
 "v12.16.0"
 ],
 "changes": []
 },
 "desc": "The <code>WASI</code> class provides the WASI system call API and additional convenience\nmethods for working with WASI-based applications. Each <code>WASI</code> instance\nrepresents a distinct sandbox environment. For security purposes, each <code>WASI</code>\ninstance must have its command line arguments, environment variables, and\nsandbox directory structure configured explicitly.",
 "methods": [
 {
 "textRaw": "`wasi.start(instance)`",
 "type": "method",
 "name": "start",
 "meta": {
 "added": [
 "v12.16.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "params": [
 {
 "textRaw": "`instance` {WebAssembly.Instance}",
 "name": "instance",
 "type": "WebAssembly.Instance"
 }
 ]
 }
 ],
 "desc": "Attempt to begin execution of <code>instance</code> as a WASI command by invoking its\n<code>_start()</code> export. If <code>instance</code> does not contain a <code>_start()</code> export, or if\n<code>instance</code> contains an <code>_initialize()</code> export, then an exception is thrown.\n<code>start()</code> requires that <code>instance</code> exports a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory\"><code>WebAssembly.Memory</code></a> named\n<code>memory</code>. If <code>instance</code> does not have a <code>memory</code> export an exception is thrown.\nIf <code>start()</code> is called more than once, an exception is thrown."
 },
 {
 "textRaw": "`wasi.initialize(instance)`",
 "type": "method",
 "name": "initialize",
 "meta": {
 "added": [
 "v12.19.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "params": [
 {
 "textRaw": "`instance` {WebAssembly.Instance}",
 "name": "instance",
 "type": "WebAssembly.Instance"
 }
 ]
 }
 ],
 "desc": "Attempt to initialize <code>instance</code> as a WASI reactor by invoking its\n<code>_initialize()</code> export, if it is present. If <code>instance</code> contains a <code>_start()</code>\nexport, then an exception is thrown.\n<code>initialize()</code> requires that <code>instance</code> exports a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory\"><code>WebAssembly.Memory</code></a> named\n<code>memory</code>. If <code>instance</code> does not have a <code>memory</code> export an exception is thrown.\nIf <code>initialize()</code> is called more than once, an exception is thrown."
 }
 ],
 "properties": [
 {
 "textRaw": "`wasiImport` {Object}",
 "type": "Object",
 "name": "wasiImport",
 "meta": {
 "added": [
 "v12.16.0"
 ],
 "changes": []
 },
 "desc": "<code>wasiImport</code> is an object that implements the WASI system call API. This object\nshould be passed as the <code>wasi_snapshot_preview1</code> import during the instantiation\nof a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance\"><code>WebAssembly.Instance</code></a>."
 }
 ],
 "signatures": [
 {
 "params": [
 {
 "textRaw": "`options` {Object}",
 "name": "options",
 "type": "Object",
 "options": [
 {
 "textRaw": "`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:** `[]`.",
 "name": "args",
 "type": "Array",
 "default": "`[]`",
 "desc": "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."
 },
 {
 "textRaw": "`env` {Object} An object similar to `process.env` that the WebAssembly application will see as its environment. **Default:** `{}`.",
 "name": "env",
 "type": "Object",
 "default": "`{}`",
 "desc": "An object similar to `process.env` that the WebAssembly application will see as its environment."
 },
 {
 "textRaw": "`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.",
 "name": "preopens",
 "type": "Object",
 "desc": "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."
 },
 {
 "textRaw": "`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`.",
 "name": "returnOnExit",
 "type": "boolean",
 "default": "`false`",
 "desc": "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."
 },
 {
 "textRaw": "`stdin` {integer} The file descriptor used as standard input in the WebAssembly application. **Default:** `0`.",
 "name": "stdin",
 "type": "integer",
 "default": "`0`",
 "desc": "The file descriptor used as standard input in the WebAssembly application."
 },
 {
 "textRaw": "`stdout` {integer} The file descriptor used as standard output in the WebAssembly application. **Default:** `1`.",
 "name": "stdout",
 "type": "integer",
 "default": "`1`",
 "desc": "The file descriptor used as standard output in the WebAssembly application."
 },
 {
 "textRaw": "`stderr` {integer} The file descriptor used as standard error in the WebAssembly application. **Default:** `2`.",
 "name": "stderr",
 "type": "integer",
 "default": "`2`",
 "desc": "The file descriptor used as standard error in the WebAssembly application."
 }
 ]
 }
 ]
 }
 ]
 }
 ],
 "type": "module",
 "displayName": "WebAssembly System Interface (WASI)"
 }
 ]
}

MR SKB