Amazon Lambda Rust Library

This is an unofficial CDK library based on the Amazon Lambda Node.js and aws-lambda-rust Libraries.

It's intended for use with the new AWS CDK v2.

This library provides a construct for a Rust Lambda function.

It uses Docker and cross under the hood, and follows best practices as outlined in the official AWS documentation.

Rust Function

The RustFunction construct creates a Lambda function with automatic bundling and compilation of Rust code.

Getting Started

1. Install the npm package:

   $ npm i rust.aws-cdk-lambda

2. Use cargo to install rust-embedded/cross:

   $ cargo install cross

3. Install the x86_64-unknown-linux-musl toolchain with Rustup by running:

   $ rustup target add x86_64-unknown-linux-musl

Finally, ensure you have Docker installed and running, as it will be used by cross to compile Rust code for deployment.

Examples

You can find sample CDK apps built using Typescript or Node.js in the cdk-examples/ folder of the GitHub project repo.

Usage

First, import the construct:

import { RustFunction } from 'rust.aws-cdk-lambda';

Now define a RustFunction:

new RustFunction(this, 'my-handler', {});

By default, the construct will use directory where cdk was invoked as directory where Cargo files are located.

If no bin or package argument is passed in, it will default to the package name as defined in the main Cargo.toml.

That is, the above usage should work for a project structure that looks like this:

.
├── Cargo.toml
└── src
    └── main.rs

Alternatively, directory and bin can be specified:

new RustFunction(this, 'MyLambdaFunction', {
    directory: '/path/to/directory/with/Cargo.toml',
    // Optional
    bin: 'my_lambda',
});

All other properties of lambda.Function are supported, see also the AWS Lambda construct library.

How It Works

When bundling the code, the RustFunction runs the following steps in order:

• First it runs cargo check to confirm that the Rust code can compile. Note that this is an optional step, and can be disabled as mentioned below.

• Next it calls cross build, and passes in the --release and --target flags, so it compiles for a Lambda environment - which defaults to the x86_64-unknown-linux-musl target, as mentioned above.

• Finally, it copies the release app binary from the target/ folder to a file named bootstrap, which the Lambda custom runtime environment looks for. It adds this new file under the build directory, which defaults to a .build/ folder under the directory where cdk was invoked.

• The directory path to the executable is then passed in to lambda.Code.fromAsset, which creates a zip file from the release binary asset.

Multiple Rust Lambdas

Assuming you have a CDK project with more than one Rust lambda, there are a couple approaches - as outlined below - that you can use to deploy with cdk.

Multiple Binaries

Suppose your project layout looks like this:

.
├── Cargo.toml
└── src
    └── bin
        ├── lambda1.rs
        └── lambda2.rs

Here's one way to deploy that via cdk:

new RustFunction(this, 'my-function-1', {
    bin: 'lambda1',
});

new RustFunction(this, 'my-function-2', {
    bin: 'lambda2',
});

You can find a more complete project structure in the rust-bins/ CDK sample project.

Multiple Packages

Suppose you use Workspaces in your Cargo project instead.

The full contents of the main Cargo.toml would need to be updated to look like this:

[workspace]
members = [
    "lambda1",
    "lambda2"
]

And your new project layout would now look similar to this:

.
├── Cargo.lock
├── Cargo.toml
├── lambda1
│   ├── Cargo.toml
│   └── src
│       ├── main.rs
│       └── utils.rs
└── lambda2
    ├── Cargo.toml
    └── src
        ├── main.rs
        └── utils.rs

Where the utils.rs files are optional, but the point is that they can be imported by the lambda handler code in main.rs if desired.

Now you will only need to update your CDK code to pass package instead, for each workspace member:

new RustFunction(this, 'MyFirstRustFunction', {
    package: 'lambda1',
});

new RustFunction(this, 'MySecondRustFunction', {
    package: 'lambda2',
});

You can find a more complete project structure in the rust-workspaces/ CDK sample project.

Rust Function Properties

Below lists some commonly used properties you can pass in to the RustFunction construct.

Settings

Settings can be imported as follows:

import { Settings } from 'rust.aws-cdk-lambda';

Below are some useful global defaults which can be set for all Rust Lambda Functions in a CDK app.