Node.js v20.7.0 文档


目录

WebAssembly 系统接口 (WASI)#

稳定性: 1 - 实验

源代码: lib/wasi.js

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

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

const wasi = new WASI({
  version: 'preview1',
  args: argv,
  env,
  preopens: {
    '/sandbox': '/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('wasi');
const { argv, env } = require('node:process');
const { join } = require('node:path');

const wasi = new WASI({
  version: 'preview1',
  args: argv,
  env,
  preopens: {
    '/sandbox': '/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 文本格式文件:

(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

wat2wasm demo.wat 

类:WASI#

WASI 类提供了 WASI 系统调用 API 和其他方便的方法来使用基于 WASI 的应用。 每个 WASI 实例代表一个不同的沙箱环境。 出于安全考虑,每个 WASI 实例都必须显式地配置其命令行参数、环境变量、以及沙箱目录结构。

new WASI([options])#

  • options <Object>
    • args <Array> WebAssembly 应用将视为命令行参数的字符串数组。 第一个参数是 WASI 命令本身的虚拟路径。 默认值: []
    • env <Object> 类似于 process.env 的对象,WebAssembly 应用将其视为其环境。 默认值: {}
    • preopens <Object> 此对象表示 WebAssembly 应用的沙箱目录结构。 preopens 的字符串键被视为沙箱中的目录。 preopens 中对应的值是宿主机上这些目录的真实路径。
    • returnOnExit <boolean> 默认情况下,当 WASI 应用调用 __wasi_proc_exit() wasi.start() 时,将返回指定的退出代码,而不是终止进程。 将此选项设置为 false 将导致 Node.js 进程以指定的退出代码退出。 默认值: true
    • stdin <integer> 在 WebAssembly 应用中用作标准输入的文件描述符。 默认值: 0
    • stdout <integer> 在 WebAssembly 应用中用作标准输出的文件描述符。 默认值: 1
    • stderr <integer> 在 WebAssembly 应用中用作标准错误的文件描述符。 默认值: 2
    • version <string> 请求的 WASI 版本。 目前唯一支持的版本是 unstablepreview1。 此选项是强制性的。

wasi.getImportObject()#

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

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

{ wasi_unstable: wasi.wasiImport } 

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

{ wasi_snapshot_preview1: wasi.wasiImport } 

wasi.start(instance)#

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

start() 要求 instance 导出名为 memoryWebAssembly.Memory。 如果 instance 没有 memory 导出,则抛出异常。

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

wasi.initialize(instance)#

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

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

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

wasi.wasiImport#

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