wasi 网络汇编系统接口 | Node.js v20 文档

WebAssembly 系统接口 (WASI)#

¥WebAssembly System Interface (WASI)

¥Stability: 1 - Experimental

node:wasi 模块当前不提供某些 WASI 运行时提供的全面文件系统安全属性。未来可能会也可能不会实现对安全文件系统沙箱的全面支持。同时，不要依赖它来运行不受信任的代码。

¥The node:wasi module does not currently provide the comprehensive file system security properties provided by some WASI runtimes. Full support for secure file system sandboxing may or may not be implemented in future. In the mean time, do not rely on it to run untrusted code.

源代码: lib/wasi.js

WASI API 提供了 WebAssembly 系统接口规范的实现。WASI 使 WebAssembly 应用可以通过一系列类似 POSIX 的函数来访问底层操作系统。

¥The WASI API provides an implementation of the WebAssembly System Interface specification. WASI gives WebAssembly applications access to the underlying operating system via a collection of POSIX-like functions.

import { readFile } from 'node:fs/promises';
import { WASI } from 'node:wasi';
import { argv, env } from 'node:process';

const wasi = new WASI({
  version: 'preview1',
  args: argv,
  env,
  preopens: {
    '/local': '/some/real/path/that/wasm/can/access',
  },
});

const wasm = await WebAssembly.compile(
  await readFile(new URL('./demo.wasm', import.meta.url)),
);
const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());

wasi.start(instance);'use strict';
const { readFile } = require('node:fs/promises');
const { WASI } = require('node:wasi');
const { argv, env } = require('node:process');
const { join } = require('node:path');

const wasi = new WASI({
  version: 'preview1',
  args: argv,
  env,
  preopens: {
    '/local': '/some/real/path/that/wasm/can/access',
  },
});

(async () => {
  const wasm = await WebAssembly.compile(
    await readFile(join(__dirname, 'demo.wasm')),
  );
  const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());

  wasi.start(instance);
})();

要运行上面的示例，则新建一个名为 demo.wat 的 WebAssembly 文本格式文件：

¥To run the above example, create a new WebAssembly text format file named demo.wat:

(module
    ;; Import the required fd_write WASI function which will write the given io vectors to stdout
    ;; The function signature for fd_write is:
    ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written
    (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32)))

    (memory 1)
    (export "memory" (memory 0))

    ;; Write 'hello world\n' to memory at an offset of 8 bytes
    ;; Note the trailing newline which is required for the text to appear
    (data (i32.const 8) "hello world\n")

    (func $main (export "_start")
        ;; Creating a new io vector within linear memory
        (i32.store (i32.const 0) (i32.const 8))  ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string
        (i32.store (i32.const 4) (i32.const 12))  ;; iov.iov_len - The length of the 'hello world\n' string

        (call $fd_write
            (i32.const 1) ;; file_descriptor - 1 for stdout
            (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0
            (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.
            (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written
        )
        drop ;; Discard the number of bytes written from the top of the stack
    )
)

使用 wabt 编译 .wat 到 .wasm

¥Use wabt to compile .wat to .wasm

wat2wasm demo.wat

安全#

¥Security

版本历史

版本	变更
v20.11.0	阐明 WASI 安全属性。
v20.11.0	新增于: v20.11.0

WASI 提供基于功能的模型，通过该模型为应用提供自己的自定义 env、preopens、stdin、stdout、stderr 和 exit 功能。

¥WASI provides a capabilities-based model through which applications are provided their own custom env, preopens, stdin, stdout, stderr, and exit capabilities.

当前的 Node.js 威胁模型不提供某些 WASI 运行时中存在的安全沙箱。

¥The current Node.js threat model does not provide secure sandboxing as is present in some WASI runtimes.

虽然支持功能特性，但它们并不在 Node.js 中形成安全模型。例如，可以使用各种技术来躲避文件系统沙箱。该项目正在探索未来是否可以增加这些安全保障。

¥While the capability features are supported, they do not form a security model in Node.js. For example, the file system sandboxing can be escaped with various techniques. The project is exploring whether these security guarantees could be added in future.

类：`WASI`#

¥Class: WASI

新增于: v13.3.0, v12.16.0

WASI 类提供了 WASI 系统调用 API 和其他方便的方法来使用基于 WASI 的应用。每个 WASI 实例代表一个不同的环境。

¥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 environment.

`new WASI([options])`#

版本历史

版本	变更
v20.1.0	returnOnExit 的默认值更改为 true。
v20.0.0	version 选项现在是必需的，没有默认值。
v19.8.0	版本字段添加到选项。
v13.3.0, v12.16.0	新增于: v13.3.0, v12.16.0

options <Object>
- args <Array> WebAssembly 应用将视为命令行参数的字符串数组。第一个参数是 WASI 命令本身的虚拟路径。默认值：[]。
  
  ¥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> 类似于 process.env 的对象，WebAssembly 应用将其视为其环境。默认值：{}。
  
  ¥env <Object> An object similar to process.env that the WebAssembly application will see as its environment. Default: {}.
- preopens <Object> 该对象表示 WebAssembly 应用的本地目录结构。preopens 的字符串键被视为文件系统中的目录。preopens 中对应的值是宿主机上这些目录的真实路径。
  
  ¥preopens <Object> This object represents the WebAssembly application's local directory structure. The string keys of preopens are treated as directories within the file system. The corresponding values in preopens are the real paths to those directories on the host machine.
- returnOnExit <boolean> 默认情况下，当 WASI 应用调用 __wasi_proc_exit() 时，wasi.start() 将返回指定的退出代码，而不是终止进程。将此选项设置为 false 将导致 Node.js 进程以指定的退出代码退出。默认值：true。
  
  ¥returnOnExit <boolean> By default, when WASI applications call __wasi_proc_exit() wasi.start() will return with the exit code specified rather than terminating the process. Setting this option to false will cause the Node.js process to exit with the specified exit code instead. Default: true.
- stdin <integer> 在 WebAssembly 应用中用作标准输入的文件描述符。默认值：0。
  
  ¥stdin <integer> The file descriptor used as standard input in the WebAssembly application. Default: 0.
- stdout <integer> 在 WebAssembly 应用中用作标准输出的文件描述符。默认值：1。
  
  ¥stdout <integer> The file descriptor used as standard output in the WebAssembly application. Default: 1.
- stderr <integer> 在 WebAssembly 应用中用作标准错误的文件描述符。默认值：2。
  
  ¥stderr <integer> The file descriptor used as standard error in the WebAssembly application. Default: 2.
- version <string> 请求的 WASI 版本。目前唯一支持的版本是 unstable 和 preview1。此选项是强制性的。
  
  ¥version <string> The version of WASI requested. Currently the only supported versions are unstable and preview1. This option is mandatory.

`wasi.getImportObject()`#

新增于: v19.8.0

如果除了 WASI 提供的那些之外不需要其他 WASM 导入，则返回一个可以传递给 WebAssembly.instantiate() 的导入对象。

¥Return an import object that can be passed to WebAssembly.instantiate() if no other WASM imports are needed beyond those provided by WASI.

如果将版本 unstable 传递给构造函数，它将返回：

¥If version unstable was passed into the constructor it will return:

{ wasi_unstable: wasi.wasiImport }

如果将版本 preview1 传递给构造函数或未指定版本，它将返回：

¥If version preview1 was passed into the constructor or no version was specified it will return:

{ wasi_snapshot_preview1: wasi.wasiImport }

`wasi.start(instance)`#

新增于: v13.3.0, v12.16.0

instance <WebAssembly.Instance>

尝试通过调用 _start() 导出来开始执行 instance 作为 WASI 命令。如果 instance 不包含 _start() 导出，或者 instance 包含 _initialize() 导出，则抛出异常。

¥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() 要求 instance 导出名为 memory 的 WebAssembly.Memory。如果 instance 没有 memory 导出，则抛出异常。

¥start() requires that instance exports a WebAssembly.Memory named memory. If instance does not have a memory export an exception is thrown.

如果 start() 被多次调用，则抛出异常。

¥If start() is called more than once, an exception is thrown.

`wasi.initialize(instance)`#

新增于: v14.6.0, v12.19.0

instance <WebAssembly.Instance>

尝试通过调用 _initialize() 导出（如果存在）将 instance 初始化为 WASI 反应器。如果 instance 包含 _start() 导出，则抛出异常。

¥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.

initialize() 要求 instance 导出名为 memory 的 WebAssembly.Memory。如果 instance 没有 memory 导出，则抛出异常。

¥initialize() requires that instance exports a WebAssembly.Memory named memory. If instance does not have a memory export an exception is thrown.

如果 initialize() 被多次调用，则抛出异常。

¥If initialize() is called more than once, an exception is thrown.

`wasi.wasiImport`#

新增于: v13.3.0, v12.16.0

<Object>

wasiImport 是实现 WASI 系统调用 API 的对象。此对象应在 WebAssembly.Instance 实例化期间作为 wasi_snapshot_preview1 导入传入。

¥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 系统接口 (WASI)#

安全#

类：WASI#

new WASI([options])#

wasi.getImportObject()#

wasi.start(instance)#

wasi.initialize(instance)#

wasi.wasiImport#

类：`WASI`#

`new WASI([options])`#

`wasi.getImportObject()`#

`wasi.start(instance)`#

`wasi.initialize(instance)`#

`wasi.wasiImport`#