This package makes it easy to run AWS Lambda Functions written in Rust. This workspace includes multiple crates:
lambda-runtimeis a library that provides a Lambda runtime for applications written in Rust.lambda-httpis a library that makes it easy to write API Gateway proxy event focused Lambda functions in Rust.lambda-extensionis a library that makes it easy to write Lambda Runtime Extensions in Rust.lambda-runtime-api-clientis a shared library between the lambda runtime and lambda extension libraries that includes a common API client to talk with the AWS Lambda Runtime API.
The code below creates a simple function that receives an event with a firstName field and returns a message to the caller. Notice: this crate is tested against latest stable Rust.
use lambda_runtime::{service_fn, LambdaEvent, Error};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> Result<(), Error> {
let func = service_fn(func);
lambda_runtime::run(func).await?;
Ok(())
}
async fn func(event: LambdaEvent<Value>) -> Result<Value, Error> {
let (event, _context) = event.into_parts();
let first_name = event["firstName"].as_str().unwrap_or("world");
Ok(json!({ "message": format!("Hello, {}!", first_name) }))
}There are currently multiple ways of building this package: manually with the AWS CLI, with AWS SAM, and with the Serverless framework.
At the time of writing, the ability to cross compile to a different architecture is limited. For example, you might experience issues if you are compiling from a MacOS machine, or from a Linux machine with a different architecture (e.g. compiling to Arm64 from x86_64). The most robust way we've found is using cargo-zigbuild to compile for the target architecture.
You can skip this step if you are compiling for the same target as your host architecture (e.g. x86_64 Linux to x86_64 Linux), unless you're building for an Amazon Linux 1 runtime.
Run this script once to add your desired target:
# For Arm64 Lambda functions
rustup target add aarch64-unknown-linux-gnu
# For x86_64 Lambda functions
rustup target add x86_64-unknown-linux-gnuOnce this is done, install cargo-lambda:
cargo install cargo-lambdaThis Cargo subcommand will give you the option to install Zig to use as the linker. You can also install Zig using the instructions in their installation guide.
Amazon Linux 2
We recommend you to use Amazon Linux 2 runtimes (such as provided.al2) as much as possible for building Lambda functions in Rust. To build your Lambda functions for Amazon Linux 2 runtimes, run:
# Note: replace "aarch64" with "x86_64" if you are building for x86_64
cargo lambda build --release --target aarch64-unknown-linux-gnuAmazon Linux 1
Amazon Linux 1 uses glibc version 2.17, while Rust binaries need glibc version 2.18 or later by default. However, with cargo-zigbuild, you can specify a different version of glibc.
If you are building for Amazon Linux 1, or you want to support both Amazon Linux 2 and 1, run:
# Note: replace "aarch64" with "x86_64" if you are building for x86_64
cargo lambda build --release --target aarch64-unknown-linux-gnu.2.17
For a custom runtime, AWS Lambda looks for an executable called bootstrap in the deployment package zip. Rename the generated executable to bootstrap and add it to a zip archive.
You can find the bootstrap binary for your function under the target/lambda directory.
First, you will need to create a ZIP archive of your Lambda function. Cargo-lambda can do that for you automatically when it builds your binary if you add the output-format flag. For example, if you are using the basic example and aarch64-unknown-linux-gnu as your target, you can run:
cargo lambda build --release --target aarch64-unknown-linux-gnu --output-format zipNow that we have a deployment package (target/lambda/basic/bootstrap.zip), we can use the AWS CLI to create a new Lambda function. Make sure to replace the execution role with an existing role in your account!
$ aws lambda create-function --function-name rustTest \
--handler bootstrap \
--zip-file fileb://./target/lambda/basic/bootstrap.zip \
--runtime provided.al2 \ # Change this to provided.al if you would like to use Amazon Linux 1.
--role arn:aws:iam::XXXXXXXXXXXXX:role/your_lambda_execution_role \
--environment Variables={RUST_BACKTRACE=1} \
--tracing-config Mode=ActiveYou can now test the function using the AWS CLI or the AWS Lambda console
$ aws lambda invoke
--cli-binary-format raw-in-base64-out \
--function-name rustTest \
--payload '{"command": "Say Hi!"}' \
output.json
$ cat output.json # Prints: {"msg": "Command Say Hi! executed."}Note: --cli-binary-format raw-in-base64-out is a required
argument when using the AWS CLI version 2. More Information
You can use Lambda functions built in Rust with the AWS Serverless Application Model (SAM). To do so, you will need to install the AWS SAM CLI, which will help you package and deploy your Lambda functions in your AWS account.
You will need to create a template.yaml file containing your desired infrastructure in YAML. Here is an example with a single Lambda function:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
MemorySize: 128
Architectures: ["aarch64"]
Handler: bootstrap
Runtime: provided.al2
Timeout: 5
CodeUri: target/lambda/basic/
Outputs:
FunctionName:
Value: !Ref HelloWorldFunction
Description: Name of the Lambda functionYou can then deploy your Lambda function using the AWS SAM CLI:
sam deploy --guidedAt the end, sam will output the actual Lambda function name. You can use this name to invoke your function:
$ aws lambda invoke
--cli-binary-format raw-in-base64-out \
--function-name HelloWorldFunction-XXXXXXXX \ # Replace with the actual function name
--payload '{"command": "Say Hi!"}' \
output.json
$ cat output.json # Prints: {"msg": "Command Say Hi! executed."}Alternatively, you can build a Rust-based Lambda function declaratively using the Serverless framework Rust plugin.
A number of getting started Serverless application templates exist to get you up and running quickly
- a minimal echo function to demonstrate what the smallest Rust function setup looks like
- a minimal http function to demonstrate how to interface with API Gateway using Rust's native http crate (note this will be a git dependency until 0.2 is published)
- a combination multi function service to demonstrate how to set up a services with multiple independent functions
Assuming your host machine has a relatively recent version of node, you won't need to install any host-wide serverless dependencies. To get started, run the following commands to create a new lambda Rust application and install project level dependencies.
$ npx serverless install \
--url https://github.com/softprops/serverless-aws-rust \
--name my-new-app \
&& cd my-new-app \
&& npm install --silentDeploy it using the standard serverless workflow
# build, package, and deploy service to aws lambda
$ npx serverless deployInvoke it using serverless framework or a configured AWS integrated trigger source:
$ npx serverless invoke -f hello -d '{"foo":"bar"}'Alternatively, you can build a Rust-based Lambda function in a docker mirror of the AWS Lambda provided runtime with the Rust toolchain preinstalled.
Running the following command will start a ephemeral docker container which will build your Rust application and produce a zip file containing its binary auto-renamed to bootstrap to meet the AWS Lambda's expectations for binaries under target/lambda_runtime/release/{your-binary-name}.zip, typically this is just the name of your crate if you are using the cargo default binary (i.e. main.rs)
# build and package deploy-ready artifact
$ docker run --rm \
-v ${PWD}:/code \
-v ${HOME}/.cargo/registry:/root/.cargo/registry \
-v ${HOME}/.cargo/git:/root/.cargo/git \
rustserverless/lambda-rustWith your application build and packaged, it's ready to ship to production. You can also invoke it locally to verify is behavior using the lambdaci :provided docker container which is also a mirror of the AWS Lambda provided runtime with build dependencies omitted.
# start a docker container replicating the "provided" lambda runtime
# awaiting an event to be provided via stdin
$ unzip -o \
target/lambda/release/{your-binary-name}.zip \
-d /tmp/lambda && \
docker run \
-i -e DOCKER_LAMBDA_USE_STDIN=1 \
--rm \
-v /tmp/lambda:/var/task \
lambci/lambda:provided
# provide an event payload via stdin (typically a json blob)
# Ctrl-D to yield control back to your functionCargo Lambda provides a local server that emulates the AWS Lambda control plane. This server works on Windows, Linux, and MacOS. I the root of your Lambda project, run the subcommand cargo lambda start to start the server. Your function will be compiled when the server receives the first request to process. Use the subcommand cargo lambda invoke to send requests to your function. The start subcommand will watch your function's code for changes, and it will compile it every time you save the source after making changes.
You can read more about how cargo lambda start and cargo lambda invoke work on the project's README.
Lambdas can be run and debugged locally using a special Lambda debug proxy (a non-AWS repo maintained by @rimutaka), which is a Lambda function that forwards incoming requests to one AWS SQS queue and reads responses from another queue. A local proxy running on your development computer reads the queue, calls your lambda locally and sends back the response. This approach allows debugging of Lambda functions locally while being part of your AWS workflow. The lambda handler code does not need to be modified between the local and AWS versions.
lambda_runtime is a library for authoring reliable and performant Rust-based AWS Lambda functions. At a high level, it provides lambda_runtime::run, a function that runs a tower::Service<LambdaEvent>.
To write a function that will handle request, you need to pass it through service_fn, which will convert your function into a tower::Service<LambdaEvent>, which can then be run by lambda_runtime::run.
This project does not currently include Lambda event struct definitions. Instead, the community-maintained aws_lambda_events crate can be leveraged to provide strongly-typed Lambda event structs. You can create your own custom event objects and their corresponding structs as well.
To serialize and deserialize events and responses, we suggest using the use the serde library. To receive custom events, annotate your structure with Serde's macros:
use serde::{Serialize, Deserialize};
use serde_json::json;
use std::error::Error;
#[derive(Serialize, Deserialize)]
pub struct NewIceCreamEvent {
pub flavors: Vec<String>,
}
#[derive(Serialize, Deserialize)]
pub struct NewIceCreamResponse {
pub flavors_added_count: usize,
}
fn main() -> Result<(), Box<Error>> {
let flavors = json!({
"flavors": [
"Nocciola",
"抹茶",
"आम"
]
});
let event: NewIceCreamEvent = serde_json::from_value(flavors)?;
let response = NewIceCreamResponse {
flavors_added_count: event.flavors.len(),
};
serde_json::to_string(&response)?;
Ok(())
}The AWS Lambda Rust Runtime requires a minimum of Rust 1.54, and is not guaranteed to build on compiler versions earlier than that.
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.