Crate wasi_virt_layer 

wasi_virt_layer provides a virtualization layer for WebAssembly System Interface (WASI).

This crate facilitates merging a Virtual File System (VFS) and threading mechanisms into standard WASI modules without modifying their source code in complex ways. It allows a host environment (like browsers via JavaScript bindings) to seamlessly interact with in-memory Wasm modules.

Core Concepts

• Virtual File System (VFS): Overrides filesystem-related WASI calls to a custom virtualized implementation.
• Threading: Provides components that patch how Wasm spawns and manages threads using shared memory.
• Memory Bridge: Manages memory boundaries and host-guest interaction.

Modules

clock

Clock and time operations.

file

Virtual File System operations and definitions.

memory

Memory operations to bridge host and WebAssembly memory models.

poll

I/O polling and event waiting mechanisms.

prelude

Common traits, structs, and macros representing the core functionality.

process

Process execution and lifecycle virtualization.

random

Random number generation and virtualization.

sched

Scheduler operations.

wasi

wasip1

Definitions and bindings for the original WASIP1 API.

wasip1_derive

Procedural macros for generating WASIP1 boilerplate.

Macros

__as_t

Internal helper macro for handle self and other identifiers.

__if_feature

gen_alt_global

import_wasm

By entering the names of the files to be combined, a bridge for the combination is created. You need to prepare as many Wasip1 instances on the virtual file system as the number of files to be combined.

non_recursive_wasi_snapshot_preview1

Typically, WASI ABI calls are made using plug!. However, there may be cases where you want to call the ABI directly from within plug!. Doing so would result in recursion. To address this, call the function through this macro. When calling a function through this macro, it becomes a proper WASI ABI call after plug is connected. This allows you to call the ABI without causing recursion.

plug_args

@embedded or @dynamic Whether to import JavaScript runtime args from vfs, args is automatically imported even if you are not using it, so that you can block it

plug_clock

Plugs the clock ecosystem by defining necessary handlers for clock operations.

plug_env

@embedded or @dynamic Whether to import JavaScript runtime env from vfs, env is automatically imported even if you are not using it, so that you can block it

plug_fs

Plugs the file system ecosystem by defining necessary handlers. It ensures that the provided Wasm uses the given virtual file system. If self is passed, file operations performed within the VFS will also use the virtual file system. If used properly, it can even be wrapped as a component without imports. On the other hand, if plug_fs is not applied to self, file access in the VFS will use the WASI p1 ABI to access the external file system.

plug_poll

Plugs the poll ecosystem by defining necessary handlers.

plug_process

Plugs the process exit ecosystem by defining necessary handlers.

plug_random

Plugs the random ecosystem by defining necessary handlers.

plug_sched

Plugs the sched ecosystem by defining necessary handlers.

wrap_unreachable

A macro to explicitly wrap WebAssembly’s unreachable instructions for a given Target module. This generates internal markers interpreted by wasi_virt_layer-cli during generation. If you use this macro, unreachable will no longer be invoked; instead, execution immediately unwinds back to the main function or the thread entry point. This prevents the VFS from being affected by the target’s abort. By using get_flag, you can retrieve the value (the exit_code) once the unwinding is complete and control has returned to the VFS code. The value for unreachable is 1. This value is maintained per thread. For example, if you call set_flag inside proc_exit, then at the moment control returns from the VFS code (proc_exit) back to the target code, execution will immediately unwind to main. By combining these mechanisms, you can return control to the VFS at the exact moment the target WASM performs a proc_exit, and obtain the exit code.