WASI

WASI, or WebAssembly System Interface, is an API specification that provides access to several operating-system-like features such as filesystems, clocks, and random numbers. Wasmbox provides implementations of most WASI functions (see Assets\Plugins\PlaceholderSoftware\Wasmbox\Core\WASI\).

WASI provides controlled access to certain system resources. For example the virtual file system implemented by Wasmbox can provide in-memory files (which are never saved) as well as expose parts of the real file system, allowing you to carefully control exactly what can and cannot be accessed through WASM code. These features can allow untrusted or malicious code to be run safely.

caution

WASM execution is normally completely deterministic. Adding WASI features can easily break this, since it provides access to external resources which are not deterministic.

WASI Features

WASM Assets which require a WASI function will show a WASI indicator next to the function. Hovering over the indicator will show which WASI feature is required to supply this import, clicking the indicator will bring you to this this documentation page. All WASI features are interfaces which you may implement yourself, or you can use one of the built in implementations.

WASI Import

Random number generation is provided by an implementation of IVirtualRandomSource.

var rng = new CryptoRandomSource();
linker.Define(rng);

Functions which would normally be associated with an OS "Process" are provided by an implementation of IVirtualProcess.

var proc = new VirtualProcess(OnExit);
linker.Define(proc);

void OnExit(uint code)
{
    Debug.Log("Process exited with code: " + code);
}

Functions which provide access to the filesystem are provided by an implementation of IVirtualFileSystem. The default implementation provides an entire "virtual filesystem" which can have a mix of real files/folders with fully virtual files/folders which are stored in memory.

// Use a "VirtualFileSystemBuilder" to define a fake file system entirely in memory
var builder = new VirtualFileSystemBuilder()
    .WithVirtualRoot(root => {
        root.CreateVirtualDirectory("A")
            .CreateVirtualDirectory("B", dir => {
                dir.CreateInMemoryFile("File.txt");
            })
    });

linker.Define(builder.Build());

Functions which would normally be associated with an OS "Environment" are provided by an implementation of IVirtualEnvironment.

var env = new VirtualEnvironment()
    .PassthroughEnvironmentVariables()                      // Add all of the real environment variables
    .SetEnvironmentVariable("foo", "bar")                   // Create a variable named "foo" with value "bar"
    .SetArgs("--foo", "--bar", "bash", "-b", "-a", "-z"));  // Set the WASM process arguments

linker.Define(env);

Functions which get the current system time are provided by an implementation of IVirtualClock. A RealtimeClock provides access to the real system time (with an optional offset). A ManualClock provides access to a specific time which only advances when clock.Tick() is called.

var clock = new RealtimeClock();
linker.Define(clock);

Functions which interact with networking are provided by an implementation of IVirtualSocket. Wasmbox does not currently implement socket functionality, NonFunctionalSocket provides an implementation that does nothing. This can be used when using WASM files which requires the socket imports, but do not actually use them at runtime.

var sock = new NonFunctionalSocket();
linker.Define(sock);

tip

Event Polling requires that the program supports async execution.

Functions which interact with event polling are provided by an implementation of IVirtualEventPoll. Event polling allows a WASM program to be suspended until an event occurs (e.g. time elapsed).

var clock = new RealtimeClock();
var poll = new VirtualEventPoll(clock);
linker.Define(poll);

WASI Features​

WASI Features