README.md

Wasm runtime for AWS Lambda

Running WebAssembly components on AWS Lambda with the wasmtime runtime.

Requirements

• Rust
• cargo lambda
• cargo component

Quickstart

Compile and launch a local instance of a Lambda function running the demo component that calculates the prime factors of a number:

make demo

In a second terminal window, call the Lambda function:

cargo lambda invoke runtime --data-ascii '{"number": 1237789}'

This returns the prime factors of the number:

{"factors":[7,7,25261]}

To clean up, remove all generated build artifacts with:

make clean

Usage

The AWS Lambda Wasm runtime expects a component with the following interface:

interface lambda {

    record event {
        // ...
    }

    record response {
        // ...
    }

    handler: func(event: event) -> response;
}

See the section Getting Started in the cargo component README for instructions on how to create a component from scratch, or refer to the example in the demo-component directory in this repository.

Build the component with

cargo component build --release

to create a Wasm component under target/wasm32-wasip1/release.

In runtime/Cargo.toml, set the component_world key in [package.metadata] to the path to the Wasm component's *.wit file.

Then, from within the runtime directory, compile the runtime:

cargo lambda build --release --compiler cargo  # Linux x86_64
cargo lambda build --release # all other platforms (cross-compiles with Zig)

This generates the target/lambda/release/bootstrap binary required by AWS Lambda.

For testing, set the _HANDLER environment variable to the relative path to the compiled Wasm component and launch a local Lambda function instance:

export _HANDLER="../demo-component/target/wasm32-wasip1/release/function.wasm"
cargo lambda watch

To call the Lambda function, use cargo lambda invoke, replacing --data-ascii with a valid input payload:

cargo lambda invoke runtime --data-ascii '{"number": 123}'

To create a ZIP package for deployment to AWS Lambda, combine the bootstrap binary with the Wasm component:

zip -j function.zip runtime/target/lambda/release/bootstrap demo-component/target/wasm32-wasip1/release/function.wasm

Upload the ZIP package to AWS Lambda via the AWS Management Console or the AWS CLI:

aws lambda create-function \
    --function-name my-function \
    --zip-file fileb://function.zip \
    --handler function.wasm \  # full file name of the Wasm component
    --runtime provided.al2023 \
    --role arn:aws:iam::123456789012:role/lambda-role  # replace with valid execution role

You can also package the runtime as a Lambda layer and only include the component in the ZIP archive. Note that a runtime is specific to a particular component interface.