rust.aws-cdk-lambda v1.2.1

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 cargo-lambda 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 this npm package, and zig:

   $ npm i rust.aws-cdk-lambda --save-optional

2. Install the aarch64-unknown-linux-gnu toolchain with Rustup by running:

   $ rustup target add aarch64-unknown-linux-gnu

3. Use cargo to install cargo-lambda:

   $ cargo install cargo-lambda

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 lambda, and passes in the --release and --target flags, so it compiles for a Lambda environment - which defaults to the aarch64-unknown-linux-gnu target, as mentioned above. Note that cargo lambda does initially confirm that the Rust code can compile.

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

Use cross for Deployment

If you instead prefer to use Docker and cross for deployment, as outlined in the official AWS docs, you can install and use the latest v0.x release instead:

$ npm i rust.aws-cdk-lambda@0.4.0 --save-optional

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.

Conditional Compilation

A common use case is building Rust code with enabled features, and compile- time environment variables that can be used with the env! macro.

For example, we might want to run different logic in our code for development and production environments, or call a different API endpoint depending on which environment we are deploying code to.

For a sample CDK app that demonstrate such usage, check out the rust-bins/ example.

Enabling Features

You can achieve conditional compilation by introducing features which can later be enabled in Rust code.

In the Cargo.toml, create a new features section:

[features]
my-feature = [] # feature has no explicit dependencies

In your code, add the line #[cfg(feature = "my-feature")] before a function declaration, or before a statement to execute.

In your CDK code in the lib/ folder, add the following line:

// Enable features at compile or build time.
Settings.FEATURES = ['my-feature'];

Build Environment Variables

You can also introduce environment variables which are resolved at build or compile time. These values can be used in code via the env! macro in Rust.

In your code, add a call to the env!() macro:

// Retrieve an environment variable set at build (compile) time.
const BUILD_VALUE: &str = env!("MY_BUILD_VAR");

In your CDK code in the lib/ folder, add the following line:

// Enable environment variables at compile or build time.
Settings.BUILD_ENVIRONMENT = {
    MY_BUILD_VAR: 'Hello World! Testing 123.',
};

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.