Crate wasm_component_layer

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:

wasm_component_layer = "0.1.0"
wasm_runtime_layer = { version = "0.1.1", features = [ "backend_wasmi" ] }

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
• 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.