WASI

Owners: @nodejs/wasi. Public docs at doc/api/wasi.md.

Purpose

Provide a host implementation of the WebAssembly System Interface (WASI) so WebAssembly modules can perform file system, environment variable, and clock operations from inside Node. The implementation is built on uvwasi, a portable WASI runtime that itself sits on libuv.

Directory layout

lib/wasi.js                        // public node:wasi module
src/
  node_wasi.{cc,h}                 // Node binding to uvwasi
deps/
  uvwasi/                          // upstream uvwasi
test/
  wasi/                            // integration tests + .wasm fixtures
  fixtures/wasi/                   // Wasm binaries

Key abstractions

Type / file	Role
WASI (lib/wasi.js)	Public class; constructed with args, env, preopens.
wasi.start(instance)	Calls the Wasm _start entry; reaped exit codes propagate.
wasi.initialize(instance)	Reactor-style instantiate; calls _initialize.
wasi.getImportObject()	Imports map handed to WebAssembly.instantiate.
node_wasi::WASI (src/node_wasi.cc)	C++ wrapping uvwasi_t.

How a WASI instance is wired

graph LR
    JS[new WASI({...})] --> CppCtor[node_wasi::WASI ctor]
    CppCtor --> uvwasi[uvwasi_init]
    uvwasi --> uv[libuv FS / env / clock]
    JS --> Imports[wasi.getImportObject()]
    Imports --> Instance[WebAssembly.instantiate]
    Instance --> Mem[Memory shared with WASI]
    JS --> Start[wasi.start(instance)]
    Start --> Wasm[Wasm exports._start]
    Wasm --> Imports
    Imports --> uvwasi

The import object is a thin shim — each WASI ABI function calls into the C++ binding which calls into uvwasi. The Wasm memory is read once during start so that path resolution and returned buffers can be addressed.

Permission model

WASI is gated by the wasi permission domain (src/permission/wasi_permission.cc). Even with --allow-wasi, the underlying FS operations re-check fs permissions on the preopen paths.

Integration points

• uvwasi: vendored at deps/uvwasi/; updates flow through tools/dep_updaters/ (no dedicated script — pulled with general updates).
• WebAssembly API: wasi does not link Wasm itself; the user calls WebAssembly.instantiate and passes wasi.getImportObject().

Entry points for modification

• Behaviour bug? Most are upstream in uvwasi. Sometimes the binding glue in src/node_wasi.cc is at fault.
• New WASI version (preview2 / Component Model)? Likely starts as an experimental module behind a flag and a separate vendored runtime.
• Tests at test/wasi/ exercise both _start and _initialize entry points.