Crate wasm_component_layer

Expand description

wasm_component_layer is a runtime agnostic implementation of the WebAssembly component model. It supports loading and linking WASM components, inspecting and generating component interface types at runtime, and more atop any WebAssembly backend. The implementation is based upon the wasmtime, js-component-bindgen, and wit-parser crates.

§Usage

To use wasm_component_layer, a runtime is required. The wasm_runtime_layer crate provides the common interface used for WebAssembly runtimes, so when using this crate it must also be added to the Cargo.toml file with the appropriate runtime selected. For instance, the examples in this repository use the wasmi_runtime_layer runtime:

wasm_component_layer = "0.1.16"
wasmi_runtime_layer = "0.31.0"
# wasmtime_runtime_layer = "21.0.0"
# js_wasm_runtime_layer = "0.4.0"

The following is a small overview of wasm_component_layer’s API. The complete example may be found in the examples folder. Consider a WASM component with the following WIT:

package test:guest

interface foo {
    // Selects the item in position n within list x
    select-nth: func(x: list<string>, n: u32) -> string
}

world guest {
    export foo
}

The component can be loaded into wasm_component_layer and invoked as follows:

use wasm_component_layer::*;

// The bytes of the component.
const WASM: &[u8] = include_bytes!("single_component/component.wasm");

pub fn main() {
    // Create a new engine for instantiating a component.
    let engine = Engine::new(wasmi::Engine::default());

    // Create a store for managing WASM data and any custom user-defined state.
    let mut store = Store::new(&engine, ());

    // Parse the component bytes and load its imports and exports.
    let component = Component::new(&engine, WASM).unwrap();
    // Create a linker that will be used to resolve the component's imports, if any.
    let linker = Linker::default();
    // Create an instance of the component using the linker.
    let instance = linker.instantiate(&mut store, &component).unwrap();

    // Get the interface that the interface exports.
    let interface = instance.exports().instance(&"test:guest/foo".try_into().unwrap()).unwrap();
    // Get the function for selecting a list element.
    let select_nth = interface.func("select-nth").unwrap().typed::<(Vec<String>, u32), String>().unwrap();

    // Create an example list to test upon.
    let example = ["a", "b", "c"].iter().map(ToString::to_string).collect::<Vec<_>>();

    println!("Calling select-nth({example:?}, 1) == {}", select_nth.call(&mut store, (example.clone(), 1)).unwrap());
    // Prints 'Calling select-nth(["a", "b", "c"], 1) == b'
}

§Features

wasm_component_layer supports the following major features:

Parsing and instantiating WASM component binaries
Runtime generation of component interface types
Specialized list types for faster lifting/lowering
Structural equality of component interface types, as mandated by the spec
Support for guest resources
Support for strongly-typed host resources with destructors

The following features have yet to be implemented:

A macro for generating host bindings
More comprehensive tests
Subtyping

Structs§

Component: A parsed and validated WebAssembly component, which may be used to instantiate Instances.
ComponentTypes: Details a set of types within a component.
ComponentTypesInstance: Represents a specific interface from a component.
Engine: The backing engine for a WebAssembly runtime.
Enum: A value that may exist in one of multiple possible states.
EnumType: A type that has multiple possible states.
ExportInstance: Represents a specific interface from a instance.
Exports: Provides the exports for an instance.
Flags: A finite set of boolean flags that may be false or true.
FlagsType: A type that denotes a set of named bitflags.
Func: A component model function that may be invoked to interact with an Instance.
FuncError: Details the function name and instance in which an error occurred.
FuncType: A function type representing a function’s parameter and result types.
Instance: An instantiated WebAssembly component.
InterfaceIdentifier: Uniquely identifies a component model interface within a package.
Linker: Provides the ability to define imports for a component and create Instances of it.
LinkerInstance: Describes a concrete interface which components may import.
List: Represents a list of values, all of the same type.
ListType: Describes the type of a list of values, all of the same type.
OptionType: A type that may also be the absence of anything.
OptionValue: Represents a value or lack thereof.
PackageIdentifier: Uniquely identifies a WASM package within a registry, with an optionally-associated version.
PackageName: Uniquely identifies a WASM package within a registry.
Record: An unordered collection of named fields, each associated with the values.
RecordType: Describes the type of an unordered collection of named fields, each associated with the values.
ResourceBorrow: Represents a resource that is borrowed by the host. If this borrow originated from a host-owned resource, then it must be manually released via ResourceBorrow::drop, or the owned resource will be considered borrowed indefinitely.
ResourceOwn: Represents a resource that is owned by the host.
ResourceType: Describes the type of a resource. This may either be:
ResultType: A type that denotes successful or unsuccessful operation.
ResultValue: Denotes a successful or unsuccessful operation, associated optionally with types.
Store: The store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals that have been allocated during the lifetime of the abstract machine.
StoreContext: A temporary handle to a &Store<T>.
StoreContextMut: A temporary handle to a &mut Store<T>.
Tuple: An ordered, unnamed sequence of heterogenously-typed values.
TupleType: Describes the type of an ordered, unnamed sequence of heterogenously-typed values.
TypeIdentifier: Describes the name of a component type.
TypedFunc: A strongly-typed component model function that can be called to interact with Instances.
Variant: A value that exists in one of multiple possible states. Each state may optionally have a type associated with it.
VariantCase: Describes a single branch of a variant.
VariantType: Describes a type has multiple possible states. Each state may optionally have a type associated with it.

Enums§

Value: Represents a component model type.
ValueType: Represents a component model interface type.

Traits§

AsContext: A trait used to get shared access to a Store.
AsContextMut: A trait used to get exclusive access to a Store.
ComponentList: Marks a list of components that can be passed as parameters and results.
ComponentType: A type which can convert itself to and from component model values.
UnaryComponentType: Specialization of a non-tuple component type for disambiguation between multi-value and tuple.