@wuyuchentr/webassembly-runtime-embed

Embed WebAssembly runtime in Node.js with WASI support, multi-instance isolation, resource limits, and remote loading with cache. A pure Node.js alternative to wasmtime/wasmer for embedded scenarios.

Install

npm install @wuyuchentr/webassembly-runtime-embed

Quick start

const { createRuntime } = require('@wuyuchentr/webassembly-runtime-embed');

async function main() {
  const runtime = createRuntime();

  const inst = await runtime.load('./add.wasm');
  const result = inst.call('add', 1, 2);
  console.log(result); // 3
}

CLI

webassembly-runtime-embed run add.wasm --export add --args 1 2
webassembly-runtime-embed info module.wasm
webassembly-runtime-embed cache clear

WASI support (v2)

Full wasi_snapshot_preview1 implementation with filesystem sandboxing.

const runtime = createRuntime();

runtime.registerWASI({
  args: ['myapp.wasm', '--verbose'],
  env: { HOME: '/data', DEBUG: '1' },
  preopens: [
    { virtual: '/sandbox', real: '/path/to/host/dir' },
  ],
});

const inst = await runtime.load('./myapp.wasm');
// WASM can now use stdin/stdout/stderr, file I/O, clock, random, etc.

Supported WASI functions

| Category | Functions | |----------|-----------| | Args | args_sizes_get, args_get | | Environ | environ_sizes_get, environ_get | | Clock | clock_time_get, clock_res_get | | Random | random_get | | Stdio | fd_read (stdin), fd_write (stdout/stderr) | | File I/O | fd_read, fd_write, fd_close, fd_seek, fd_tell, fd_fdstat_get, fd_fdstat_set_flags, fd_filestat_get, fd_readdir, fd_datasync, fd_sync, fd_advise, fd_allocate, fd_renumber | | Filesystem | path_open, path_create_directory, path_remove_directory, path_unlink_file, path_rename, path_filestat_get, path_readlink, path_symlink | | Preopens | fd_prestat_get, fd_prestat_dir_name | | Process | proc_exit | | Poll | poll_oneoff, sched_yield |

Filesystem sandboxing

All WASM file operations are sandboxed within preopened directories. Paths like /sandbox/file.txt are transparently mapped to real host paths. Path traversal outside the preopened root is rejected.

Features

Function calling with type conversion

inst.call('add', 1, 2);             // i32 → i32
inst.call('multiply', 2.5, 3.0);    // f64 → f64

Memory access

const mem = inst.getMemory();
mem.writeCString(0, 'hello world');
const str = mem.readCString(0);
mem.writeF64(1024, 3.14159);

Host function registration

runtime.registerFunction('env', 'js_log', (ptr, len) => {
  const str = inst.getMemory().readString(ptr, len);
  console.log('[wasm]', str);
});

Resource limits

const inst = await runtime.load('./module.wasm', {
  maxMemory: 65536 * 4,
  timeout: 1000,
});

Remote loading with cache

const inst = await runtime.loadRemote('https://example.com/module.wasm', {
  ttl: 3600,
});

API

createRuntime(options)

runtime.load(source, options)

| Option | Default | Description | |--------|---------|-------------| | maxMemory | 0 | Maximum memory in bytes | | timeout | 0 | Execution timeout in ms | | argTypes | [] | Argument types for auto-conversion | | returnType | null | Return type for auto-conversion |

runtime.registerWASI(options)

| Option | Default | Description | |--------|---------|-------------| | args | [] | Command-line arguments | | env | {} | Environment variables | | preopens | [] | Array of { virtual, real } path mappings |

runtime.registerFunction(module, name, fn)

inst.call(name, ...args)

inst.getMemory()

MemoryView methods

• readU8/16/32(offset), readI32(offset), readF32/64(offset)
• readString(offset, length), readCString(offset)
• writeU8/16/32(offset, value), writeI32(offset, value)
• writeF32/64(offset, value), writeString(offset, str), writeCString(offset, str)
• alloc(size), allocString(str), free()

License

MIT