1 unstable release
0.3.0 | Jan 22, 2021 |
---|
#1601 in Network programming
245 downloads per month
Used in 2 crates
42KB
763 lines
Rust Runtime for AWS Lambda
This package makes it easy to run AWS Lambda Functions written in Rust.
⚠️ ⚠️ ⚠️ 👷 👷 👷 🍴 🍴 🍴
This is a fork for the official AWS Lambda runtime for Rust. We've created this fork to be able to move forward all the contributions from the community that have been stalled in the awslabs repository without a release in sight.
Lambda Runtime contains the runtime component. Lambda Attributes contains macro definitions to create Lambda functions. Lambda HTTP contains definitions to create Lambda functions that are accessed via HTTP endpoints.
⚠️ ⚠️ ⚠️ 👷 👷 👷 🍴 🍴 🍴
Example function
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 lamedh_runtime::{Context, handler_fn, run, Error};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> Result<(), Error> {
run(handler_fn(func)).await?;
Ok(())
}
async fn func(event: Value, _: Context) -> Result<Value, Error> {
let first_name = event["firstName"].as_str().unwrap_or("world");
Ok(json!({ "message": format!("Hello, {}!", first_name) }))
}
The code above is the same as the basic example in the lambda
crate.
Deployment
There are currently multiple ways of building this package: manually with the AWS CLI, and with the Serverless framework.
AWS CLI
To deploy the basic sample as a Lambda function using the AWS CLI, we first need to manually build it with cargo
. Since Lambda uses Amazon Linux, you'll need to target your executable for an x86_64-unknown-linux-musl
platform.
Run this script once to add the new target:
$ rustup target add x86_64-unknown-linux-musl
- Note: If you are running on Mac OS you'll need to install the linker for the target platform. You do this using the
musl-cross
tap from Homebrew which provides a complete cross-compilation toolchain for Mac OS. Oncemusl-cross
is installed we will also need to inform cargo of the newely installed linker when building for thex86_64-unknown-linux-musl
platform.
$ brew install filosottile/musl-cross/musl-cross
$ mkdir .cargo
$ echo $'[target.x86_64-unknown-linux-musl]\nlinker = "x86_64-linux-musl-gcc"' > .cargo/config
Compile one of the examples as a release with a specific target for deployment to AWS:
$ cargo build -p lambda --example hello --release --target x86_64-unknown-linux-musl
For a custom runtime, AWS Lambda looks for an executable called bootstrap
in the deployment package zip. Rename the generated basic
executable to bootstrap
and add it to a zip archive.
$ cp ./target/release/examples/hello ./bootstrap && zip lambda.zip bootstrap && rm bootstrap
Now that we have a deployment package (lambda.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 doesnt.matter \
--zip-file fileb://./lambda.zip \
--runtime provided \
--role arn:aws:iam::XXXXXXXXXXXXX:role/your_lambda_execution_role \
--environment Variables={RUST_BACKTRACE=1} \
--tracing-config Mode=Active
You can now test the function using the AWS CLI or the AWS Lambda console
$ aws lambda invoke --function-name rustTest \
--payload '{"firstName": "world"}' \
output.json
$ cat output.json # Prints: {"message": "Hello, world!"}
Note: --cli-binary-format raw-in-base64-out
is a required
argument when using the AWS CLI version 2. More Information
Serverless Framework
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 --silent
Deploy it using the standard serverless workflow
# build, package, and deploy service to aws lambda
$ npx serverless deploy
Invoke it using serverless framework or a configured AWS integrated trigger source:
$ npx serverless invoke -f hello -d '{"foo":"bar"}'
Docker
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/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 \
softprops/lambda-rust
With 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 function
lambda
lambda
is a library for authoring reliable and performant Rust-based AWS Lambda functions. At a high level, it provides a few major components:
Handler
, a trait that defines interactions between customer-authored code and this library.lamedh_runtime::run
, function that runs anHandler
.
The function handler_fn
converts a rust function or closure to Handler
, which can then be run by lamedh_runtime::run
.
Custom event objects
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(())
}
Dependencies
~7–17MB
~222K SLoC