1{ 2 "type": "module", 3 "source": "doc/api/wasi.md", 4 "modules": [ 5 { 6 "textRaw": "WebAssembly System Interface (WASI)", 7 "name": "webassembly_system_interface_(wasi)", 8 "introduced_in": "v12.16.0", 9 "stability": 1, 10 "stabilityText": "Experimental", 11 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v18.20.1/lib/wasi.js\">lib/wasi.js</a></p>\n<p>The 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.</p>\n<pre><code class=\"language-mjs\">import { readFile } from 'node:fs/promises';\nimport { WASI } from 'wasi';\nimport { argv, env } from 'node:process';\n\nconst wasi = new WASI({\n args: argv,\n env,\n preopens: {\n '/sandbox': '/some/real/path/that/wasm/can/access',\n },\n});\n\n// Some WASI binaries require:\n// const importObject = { wasi_unstable: wasi.wasiImport };\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\nconst wasm = await WebAssembly.compile(\n await readFile(new URL('./demo.wasm', import.meta.url)),\n);\nconst instance = await WebAssembly.instantiate(wasm, importObject);\n\nwasi.start(instance);\n</code></pre>\n<pre><code class=\"language-cjs\">'use strict';\nconst { readFile } = require('node:fs/promises');\nconst { WASI } = require('wasi');\nconst { argv, env } = require('node:process');\nconst { join } = require('node:path');\n\nconst wasi = new WASI({\n args: argv,\n env,\n preopens: {\n '/sandbox': '/some/real/path/that/wasm/can/access',\n },\n});\n\n// Some WASI binaries require:\n// const importObject = { wasi_unstable: wasi.wasiImport };\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\n(async () => {\n const wasm = await WebAssembly.compile(\n await readFile(join(__dirname, 'demo.wasm')),\n );\n const instance = await WebAssembly.instantiate(wasm, importObject);\n\n wasi.start(instance);\n})();\n</code></pre>\n<p>To run the above example, create a new WebAssembly text format file named\n<code>demo.wat</code>:</p>\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>\n<p>Use <a href=\"https://github.com/WebAssembly/wabt\">wabt</a> to compile <code>.wat</code> to <code>.wasm</code></p>\n<pre><code class=\"language-console\">$ wat2wasm demo.wat\n</code></pre>", 12 "classes": [ 13 { 14 "textRaw": "Class: `WASI`", 15 "type": "class", 16 "name": "WASI", 17 "meta": { 18 "added": [ 19 "v13.3.0", 20 "v12.16.0" 21 ], 22 "changes": [] 23 }, 24 "desc": "<p>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.</p>", 25 "methods": [ 26 { 27 "textRaw": "`wasi.start(instance)`", 28 "type": "method", 29 "name": "start", 30 "meta": { 31 "added": [ 32 "v13.3.0", 33 "v12.16.0" 34 ], 35 "changes": [] 36 }, 37 "signatures": [ 38 { 39 "params": [ 40 { 41 "textRaw": "`instance` {WebAssembly.Instance}", 42 "name": "instance", 43 "type": "WebAssembly.Instance" 44 } 45 ] 46 } 47 ], 48 "desc": "<p>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.</p>\n<p><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.</p>\n<p>If <code>start()</code> is called more than once, an exception is thrown.</p>" 49 }, 50 { 51 "textRaw": "`wasi.initialize(instance)`", 52 "type": "method", 53 "name": "initialize", 54 "meta": { 55 "added": [ 56 "v14.6.0", 57 "v12.19.0" 58 ], 59 "changes": [] 60 }, 61 "signatures": [ 62 { 63 "params": [ 64 { 65 "textRaw": "`instance` {WebAssembly.Instance}", 66 "name": "instance", 67 "type": "WebAssembly.Instance" 68 } 69 ] 70 } 71 ], 72 "desc": "<p>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.</p>\n<p><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.</p>\n<p>If <code>initialize()</code> is called more than once, an exception is thrown.</p>" 73 } 74 ], 75 "properties": [ 76 { 77 "textRaw": "`wasiImport` {Object}", 78 "type": "Object", 79 "name": "wasiImport", 80 "meta": { 81 "added": [ 82 "v13.3.0", 83 "v12.16.0" 84 ], 85 "changes": [] 86 }, 87 "desc": "<p><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>.</p>" 88 } 89 ], 90 "signatures": [ 91 { 92 "params": [ 93 { 94 "textRaw": "`options` {Object}", 95 "name": "options", 96 "type": "Object", 97 "options": [ 98 { 99 "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:** `[]`.", 100 "name": "args", 101 "type": "Array", 102 "default": "`[]`", 103 "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." 104 }, 105 { 106 "textRaw": "`env` {Object} An object similar to `process.env` that the WebAssembly application will see as its environment. **Default:** `{}`.", 107 "name": "env", 108 "type": "Object", 109 "default": "`{}`", 110 "desc": "An object similar to `process.env` that the WebAssembly application will see as its environment." 111 }, 112 { 113 "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.", 114 "name": "preopens", 115 "type": "Object", 116 "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." 117 }, 118 { 119 "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`.", 120 "name": "returnOnExit", 121 "type": "boolean", 122 "default": "`false`", 123 "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." 124 }, 125 { 126 "textRaw": "`stdin` {integer} The file descriptor used as standard input in the WebAssembly application. **Default:** `0`.", 127 "name": "stdin", 128 "type": "integer", 129 "default": "`0`", 130 "desc": "The file descriptor used as standard input in the WebAssembly application." 131 }, 132 { 133 "textRaw": "`stdout` {integer} The file descriptor used as standard output in the WebAssembly application. **Default:** `1`.", 134 "name": "stdout", 135 "type": "integer", 136 "default": "`1`", 137 "desc": "The file descriptor used as standard output in the WebAssembly application." 138 }, 139 { 140 "textRaw": "`stderr` {integer} The file descriptor used as standard error in the WebAssembly application. **Default:** `2`.", 141 "name": "stderr", 142 "type": "integer", 143 "default": "`2`", 144 "desc": "The file descriptor used as standard error in the WebAssembly application." 145 } 146 ] 147 } 148 ] 149 } 150 ] 151 } 152 ], 153 "type": "module", 154 "displayName": "WebAssembly System Interface (WASI)" 155 } 156 ] 157}