WebAssembly System Interface (WASI) — Node.js 24 LTS

Интерфейс систем WebAssembly (WASI)

Модуль node:wasi в настоящее время не обеспечивает комплексные свойства безопасности файловой системы, которые предоставляют некоторые среды выполнения WASI. Полная поддержка безопасной изоляции файловой системы может быть реализована в будущем, а может и не быть. Пока не полагайтесь на неё при запуске ненадёжного кода.

Исходный код: lib/wasi.js

API WASI предоставляет реализацию спецификации интерфейса систем WebAssembly. WASI предоставляет приложениям WebAssembly доступ к базовой операционной системе с помощью набора функций, подобных POSIX.

Модули JavaScript

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);

CommonJS

'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);
})();

Чтобы запустить приведённый выше пример, создайте новый файл в текстовом формате WebAssembly с именем 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
    )
) copy

Используйте wabt, чтобы скомпилировать .wat в .wasm

wat2wasm demo.wat copy

Безопасность

История

Версия	Изменения
v21.2.0, v20.11.0	Уточнены свойства безопасности WASI.
v21.2.0, v20.11.0	Добавлено в: v21.2.0, v20.11.0

WASI предоставляет основанную на возможностях модель, в рамках которой приложениям предоставляются собственные возможности env, preopens, stdin, stdout, stderr и exit.

Текущая модель угроз Node.js не обеспечивает безопасную изоляцию, которая реализована в некоторых средах выполнения WASI.

Хотя функции управления возможностями поддерживаются, в Node.js они не образуют модель безопасности. Например, изоляцию файловой системы можно обойти различными способами. Проект изучает возможность добавления этих гарантий безопасности в будущем.

Класс: `WASI`

Добавлено в: v13.3.0, v12.16.0

Класс WASI предоставляет API системных вызовов WASI и дополнительные вспомогательные методы для работы с приложениями на основе WASI. Каждый экземпляр WASI представляет отдельную среду.

`new WASI([options])`

История

Версия	Изменения
v20.1.0	Значение returnOnExit по умолчанию изменено на true.
v20.0.0	Параметр version теперь обязателен и не имеет значения по умолчанию.
v19.8.0	В параметры добавлено поле version.
v13.3.0, v12.16.0	Добавлено в: v13.3.0, v12.16.0

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. В настоящее время поддерживаются только версии unstable и preview1. Этот параметр обязателен.

`wasi.getImportObject()`

Добавлено в: v19.8.0

Возвращает объект импорта, который можно передать в WebAssembly.instantiate(), если не требуются другие импорты WASM помимо предоставляемых WASI.

Если в конструктор была передана версия unstable, будет возвращено:

{ wasi_unstable: wasi.wasiImport } copy

Если в конструктор была передана версия preview1 или версия не была указана, будет возвращено:

{ wasi_snapshot_preview1: wasi.wasiImport } copy

`wasi.start(instance)`

Добавлено в: v13.3.0, v12.16.0

instance <WebAssembly.Instance>

Пытается начать выполнение instance в качестве команды WASI, вызывая её экспорт _start(). Если instance не содержит экспорт _start() или если instance содержит экспорт _initialize(), выбрасывается исключение.

start() требует, чтобы instance экспортировал WebAssembly.Memory с именем memory. Если instance не имеет экспорта memory, выбрасывается исключение.

Если start() вызывается более одного раза, выбрасывается исключение.

`wasi.initialize(instance)`

Добавлено в: v14.6.0, v12.19.0

instance <WebAssembly.Instance>

Пытается инициализировать instance в качестве реактора WASI, вызывая экспорт _initialize(), если он присутствует. Если instance содержит экспорт _start(), выбрасывается исключение.

initialize() требует, чтобы instance экспортировал WebAssembly.Memory с именем memory. Если instance не имеет экспорта memory, выбрасывается исключение.

Если initialize() вызывается более одного раза, выбрасывается исключение.

`wasi.finalizeBindings(instance[, options])`

Добавлено в: v24.4.0

instance <WebAssembly.Instance>
options <Object>
- memory <WebAssembly.Memory> По умолчанию: instance.exports.memory.

Настраивает привязки хоста WASI для instance без вызова initialize() или start(). Этот метод полезен, когда модуль WASI создаётся в дочерних потоках для совместного использования памяти между потоками.

finalizeBindings() требует, чтобы либо instance экспортировал WebAssembly.Memory с именем memory, либо пользователь указал объект WebAssembly.Memory в options.memory. Если memory недопустим, выбрасывается исключение.

start() и initialize() будут вызывать finalizeBindings() внутри себя. Если finalizeBindings() вызывается более одного раза, выбрасывается исключение.

`wasi.wasiImport`

Добавлено в: v13.3.0, v12.16.0

Тип: <Object>

wasiImport — это объект, реализующий API системных вызовов WASI. Этот объект следует передать в качестве импорта wasi_snapshot_preview1 при создании экземпляра WebAssembly.Instance.

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/wasi.html

Интерфейс систем WebAssembly (WASI)

Безопасность

Класс: WASI

new WASI([options])

wasi.getImportObject()

wasi.start(instance)

wasi.initialize(instance)

wasi.finalizeBindings(instance[, options])

wasi.wasiImport

Класс: `WASI`

`new WASI([options])`

`wasi.getImportObject()`

`wasi.start(instance)`

`wasi.initialize(instance)`

`wasi.finalizeBindings(instance[, options])`

`wasi.wasiImport`