Crate wasm_component_layer

source ·
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:

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().0);
    // 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.
  • EnumType
    A type that has multiple possible states.
  • ExportInstance
    Represents a specific interface from a instance.
  • Exports
    Provides the exports for an instance.
  • FlagsType
    A type that denotes a set of named bitflags.
  • 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.
  • 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>.
  • TupleType
    Describes the type of an ordered, unnamed sequence of heterogenously-typed values.
  • TypedFunc
    A strongly-typed component model function that can be called to interact with Instances.
  • UnionType
    A type that has multiple possible states, each with an associated type.
  • VariantType
    Describes a type has multiple possible states. Each state may optionally have a type associated with it.

Traits