1 | /**
|
2 | * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/)specification. WASI gives sandboxed WebAssembly applications access to the
|
3 | * underlying operating system via a collection of POSIX-like functions.
|
4 | *
|
5 | * ```js
|
6 | * import fs from 'fs';
|
7 | * import { WASI } from 'wasi';
|
8 | * import { argv, env } from 'process';
|
9 | *
|
10 | * const wasi = new WASI({
|
11 | * args: argv,
|
12 | * env,
|
13 | * preopens: {
|
14 | * '/sandbox': '/some/real/path/that/wasm/can/access'
|
15 | * }
|
16 | * });
|
17 | * const importObject = { wasi_snapshot_preview1: wasi.wasiImport };
|
18 | *
|
19 | * const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));
|
20 | * const instance = await WebAssembly.instantiate(wasm, importObject);
|
21 | *
|
22 | * wasi.start(instance);
|
23 | * ```
|
24 | *
|
25 | * To run the above example, create a new WebAssembly text format file named`demo.wat`:
|
26 | *
|
27 | * ```text
|
28 | * (module
|
29 | * ;; Import the required fd_write WASI function which will write the given io vectors to stdout
|
30 | * ;; The function signature for fd_write is:
|
31 | * ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written
|
32 | * (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32)))
|
33 | *
|
34 | * (memory 1)
|
35 | * (export "memory" (memory 0))
|
36 | *
|
37 | * ;; Write 'hello world\n' to memory at an offset of 8 bytes
|
38 | * ;; Note the trailing newline which is required for the text to appear
|
39 | * (data (i32.const 8) "hello world\n")
|
40 | *
|
41 | * (func $main (export "_start")
|
42 | * ;; Creating a new io vector within linear memory
|
43 | * (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string
|
44 | * (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string
|
45 | *
|
46 | * (call $fd_write
|
47 | * (i32.const 1) ;; file_descriptor - 1 for stdout
|
48 | * (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0
|
49 | * (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.
|
50 | * (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written
|
51 | * )
|
52 | * drop ;; Discard the number of bytes written from the top of the stack
|
53 | * )
|
54 | * )
|
55 | * ```
|
56 | *
|
57 | * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`
|
58 | *
|
59 | * ```console
|
60 | * $ wat2wasm demo.wat
|
61 | * ```
|
62 | *
|
63 | * The `--experimental-wasi-unstable-preview1` CLI argument is needed for this
|
64 | * example to run.
|
65 | * @experimental
|
66 | * @see [source](https://github.com/nodejs/node/blob/v16.6.0/lib/wasi.js)
|
67 | */
|
68 | declare module 'wasi' {
|
69 | interface WASIOptions {
|
70 | /**
|
71 | * An array of strings that the WebAssembly application will
|
72 | * see as command line arguments. The first argument is the virtual path to the
|
73 | * WASI command itself.
|
74 | */
|
75 | args?: string[] | undefined;
|
76 | /**
|
77 | * An object similar to `process.env` that the WebAssembly
|
78 | * application will see as its environment.
|
79 | */
|
80 | env?: object | undefined;
|
81 | /**
|
82 | * This object represents the WebAssembly application's
|
83 | * sandbox directory structure. The string keys of `preopens` are treated as
|
84 | * directories within the sandbox. The corresponding values in `preopens` are
|
85 | * the real paths to those directories on the host machine.
|
86 | */
|
87 | preopens?: NodeJS.Dict<string> | undefined;
|
88 | /**
|
89 | * By default, WASI applications terminate the Node.js
|
90 | * process via the `__wasi_proc_exit()` function. Setting this option to `true`
|
91 | * causes `wasi.start()` to return the exit code rather than terminate the
|
92 | * process.
|
93 | * @default false
|
94 | */
|
95 | returnOnExit?: boolean | undefined;
|
96 | /**
|
97 | * The file descriptor used as standard input in the WebAssembly application.
|
98 | * @default 0
|
99 | */
|
100 | stdin?: number | undefined;
|
101 | /**
|
102 | * The file descriptor used as standard output in the WebAssembly application.
|
103 | * @default 1
|
104 | */
|
105 | stdout?: number | undefined;
|
106 | /**
|
107 | * The file descriptor used as standard error in the WebAssembly application.
|
108 | * @default 2
|
109 | */
|
110 | stderr?: number | undefined;
|
111 | }
|
112 | /**
|
113 | * The `WASI` class provides the WASI system call API and additional convenience
|
114 | * methods for working with WASI-based applications. Each `WASI` instance
|
115 | * represents a distinct sandbox environment. For security purposes, each `WASI`instance must have its command-line arguments, environment variables, and
|
116 | * sandbox directory structure configured explicitly.
|
117 | * @since v13.3.0, v12.16.0
|
118 | */
|
119 | class WASI {
|
120 | constructor(options?: WASIOptions);
|
121 | /**
|
122 | * 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()`
|
123 | * export, then an exception is thrown.
|
124 | *
|
125 | * `start()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named`memory`. If
|
126 | * `instance` does not have a `memory` export an exception is thrown.
|
127 | *
|
128 | * If `start()` is called more than once, an exception is thrown.
|
129 | * v13.3.0, v12.16.0
|
130 | */
|
131 | start(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib.
|
132 | /**
|
133 | * 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.
|
134 | *
|
135 | * `initialize()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named`memory`.
|
136 | * If `instance` does not have a `memory` export an exception is thrown.
|
137 | *
|
138 | * If `initialize()` is called more than once, an exception is thrown.
|
139 | * @since v14.6.0, v12.19.0
|
140 | */
|
141 | initialize(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib.
|
142 | /**
|
143 | * `wasiImport` is an object that implements the WASI system call API. This object
|
144 | * should be passed as the `wasi_snapshot_preview1` import during the instantiation
|
145 | * of a [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance).
|
146 | * @since v13.3.0, v12.16.0
|
147 | */
|
148 | readonly wasiImport: NodeJS.Dict<any>; // TODO: Narrow to DOM types
|
149 | }
|
150 | }
|
151 | declare module 'node:wasi' {
|
152 | export * from 'wasi';
|
153 | }
|
154 |
|
\ | No newline at end of file |