{"id":17169172,"url":"https://github.com/rnag/rust.aws-cdk-lambda","last_synced_at":"2025-04-13T15:52:19.618Z","repository":{"id":42678850,"uuid":"460655745","full_name":"rnag/rust.aws-cdk-lambda","owner":"rnag","description":"A CDK (v2) Construct Library for AWS Lambda in Rust","archived":false,"fork":false,"pushed_at":"2023-03-25T17:14:35.000Z","size":505,"stargazers_count":86,"open_issues_count":5,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-22T19:05:00.937Z","etag":null,"topics":["aws-lambda","aws-lambda-rust","cdk","cdk-construct","cdk-construct-library","cdk-constructs","cdk-examples","lambda-function","lambda-functions","rust"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnag.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-18T00:30:48.000Z","updated_at":"2025-02-09T03:37:41.000Z","dependencies_parsed_at":"2023-02-18T13:45:30.798Z","dependency_job_id":null,"html_url":"https://github.com/rnag/rust.aws-cdk-lambda","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Frust.aws-cdk-lambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Frust.aws-cdk-lambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Frust.aws-cdk-lambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Frust.aws-cdk-lambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnag","download_url":"https://codeload.github.com/rnag/rust.aws-cdk-lambda/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741147,"owners_count":21154249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-lambda","aws-lambda-rust","cdk","cdk-construct","cdk-construct-library","cdk-constructs","cdk-examples","lambda-function","lambda-functions","rust"],"created_at":"2024-10-14T23:25:17.282Z","updated_at":"2025-04-13T15:52:19.598Z","avatar_url":"https://github.com/rnag.png","language":"TypeScript","readme":"# Amazon Lambda Rust Library\n\n\u003c!--BEGIN STABILITY BANNER--\u003e\n\n---\n\n![rust.aws-cdk-lambda: Stable](https://img.shields.io/badge/rust.aws--cdk--lambda-stable-success.svg?style=for-the-badge)\n[![npm](https://img.shields.io/npm/v/rust.aws-cdk-lambda?style=for-the-badge)](https://www.npmjs.com/package/rust.aws-cdk-lambda)\n\n\u003e **This is an unofficial CDK library based on the [Amazon Lambda Node.js] and [aws-lambda-rust] Libraries.**\n\u003e\n\u003e _It's intended for use with the new **[AWS CDK v2]**_.\n\n[aws cdk v2]: https://aws.amazon.com/about-aws/whats-new/2021/12/aws-cloud-development-kit-cdk-generally-available/\n[amazon lambda node.js]: https://www.npmjs.com/package/@aws-cdk/aws-lambda-nodejs\n[aws-lambda-rust]: https://www.npmjs.com/package/aws-lambda-rust\n\n---\n\n\u003c!--END STABILITY BANNER--\u003e\n\nThis library provides a construct for a Rust Lambda function.\n\nIt uses [`cargo-lambda`] under the hood, and follows best practices as outlined\nin the [official AWS documentation].\n\n[`cargo-lambda`]: https://crates.io/crates/cargo-lambda\n[official aws documentation]: https://github.com/awslabs/aws-lambda-rust-runtime#building-and-deploying-your-lambda-functions\n\n## Rust Function\n\nThe `RustFunction` construct creates a Lambda function with automatic bundling and compilation of Rust code.\n\n## Getting Started\n\n1. Install this [npm] package, and [zig]:\n\n    ```shell\n    $ npm i rust.aws-cdk-lambda --save-optional\n    ```\n\n2. Install the **aarch64-unknown-linux-gnu** toolchain with Rustup by running:\n\n    ```shell\n    $ rustup target add aarch64-unknown-linux-gnu\n    ```\n\n3. Use [`cargo`] to install _cargo-lambda_:\n\n    ```shell\n    $ cargo install cargo-lambda\n    ```\n\n[npm]: https://nodejs.org/\n[pip]: https://pip.pypa.io/en/stable/\n[`cargo`]: https://www.rust-lang.org/\n[zig]: https://ziglang.org/\n\n## Examples\n\nYou can find sample CDK apps built using _Typescript_ or _Node.js_ in the [cdk-examples/] folder of the GitHub project repo.\n\n[cdk-examples/]: https://github.com/rnag/rust.aws-cdk-lambda/tree/main/cdk-examples\n\n## Usage\n\nFirst, import the construct:\n\n```ts\nimport { RustFunction } from 'rust.aws-cdk-lambda';\n```\n\nNow define a `RustFunction`:\n\n```ts\nnew RustFunction(this, 'my-handler', {});\n```\n\nBy default, the construct will use directory where `cdk` was invoked as directory where Cargo files are located.\n\nIf no `bin` or `package` argument is passed in, it will default to the package name as defined in the main `Cargo.toml`.\n\nThat is, the above usage should work for a project structure that looks like this:\n\n```plaintext\n.\n├── Cargo.toml\n└── src\n    └── main.rs\n```\n\nAlternatively, `directory` and `bin` can be specified:\n\n```ts\nnew RustFunction(this, 'MyLambdaFunction', {\n    directory: '/path/to/directory/with/Cargo.toml',\n    // Optional\n    bin: 'my_lambda',\n});\n```\n\nAll other properties of `lambda.Function` are supported, see also the [AWS Lambda construct library](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-lambda).\n\n## How It Works\n\nWhen bundling the code, the `RustFunction` runs the following steps in order:\n\n-   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.\n\n-   The directory path to the executable is then passed in to `lambda.Code.fromAsset`, which creates a _zip file_ from the release binary asset.\n\n## Use `cross` for Deployment\n\nIf you instead prefer to use [Docker] and [`cross`] for deployment, as outlined\nin the [official AWS docs], you can install and use the [latest `v0.x`] release instead:\n\n```shell\n$ npm i rust.aws-cdk-lambda@0.4.0 --save-optional\n```\n\n[docker]: https://www.docker.com/get-started\n[`cross`]: https://github.com/rust-embedded/cross\n[official aws docs]: https://docs.aws.amazon.com/sdk-for-rust/latest/dg/lambda.html\n[latest `v0.x`]: https://github.com/rnag/rust.aws-cdk-lambda/releases/tag/0.4.0\n\n## Multiple Rust Lambdas\n\nAssuming you have a CDK project with more than one Rust\nlambda, there are a couple approaches - as outlined below -\nthat you can use to deploy with `cdk`.\n\n### Multiple Binaries\n\nSuppose your project layout looks like this:\n\n```plaintext\n.\n├── Cargo.toml\n└── src\n    └── bin\n        ├── lambda1.rs\n        └── lambda2.rs\n```\n\nHere's one way to deploy that via `cdk`:\n\n```ts\nnew RustFunction(this, 'my-function-1', {\n    bin: 'lambda1',\n});\n\nnew RustFunction(this, 'my-function-2', {\n    bin: 'lambda2',\n});\n```\n\nYou can find a more complete project structure in the [rust-bins/] CDK sample project.\n\n[rust-bins/]: https://github.com/rnag/rust.aws-cdk-lambda/tree/main/cdk-examples/rust-bins\n\n### Multiple Packages\n\nSuppose you use [Workspaces] in your Cargo project instead.\n\nThe full contents of the main `Cargo.toml` would need to be updated\nto look like this:\n\n```toml\n[workspace]\nmembers = [\n    \"lambda1\",\n    \"lambda2\"\n]\n```\n\nAnd your new project layout would now look similar to this:\n\n```plaintext\n.\n├── Cargo.lock\n├── Cargo.toml\n├── lambda1\n│   ├── Cargo.toml\n│   └── src\n│       ├── main.rs\n│       └── utils.rs\n└── lambda2\n    ├── Cargo.toml\n    └── src\n        ├── main.rs\n        └── utils.rs\n```\n\nWhere 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.\n\nNow you will only need to update your CDK code to pass `package` instead,\nfor each workspace member:\n\n```ts\nnew RustFunction(this, 'MyFirstRustFunction', {\n    package: 'lambda1',\n});\n\nnew RustFunction(this, 'MySecondRustFunction', {\n    package: 'lambda2',\n});\n```\n\nYou can find a more complete project structure in the [rust-workspaces/] CDK sample project.\n\n[workspaces]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html\n[rust-workspaces/]: https://github.com/rnag/rust.aws-cdk-lambda/tree/main/cdk-examples/rust-workspaces\n\n## Conditional Compilation\n\nA common use case is building Rust code with enabled [features], and compile-\ntime environment variables that can be used with the [`env!`] macro.\n\nFor 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.\n\nFor a sample CDK app that demonstrate such usage, check out the [rust-bins/] example.\n\n### Enabling Features\n\nYou can achieve conditional compilation by [introducing features](https://stackoverflow.com/a/27634313/10237506) which can later be enabled in Rust code.\n\nIn the `Cargo.toml`, create a new `features` section:\n\n```toml\n[features]\nmy-feature = [] # feature has no explicit dependencies\n```\n\nIn your code, add the line `#[cfg(feature = \"my-feature\")]` before a function declaration, or before a statement to execute.\n\nIn your CDK code in the `lib/` folder, add the following line:\n\n```ts\n// Enable features at compile or build time.\nSettings.FEATURES = ['my-feature'];\n```\n\n### Build Environment Variables\n\nYou 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.\n\nIn your code, add a call to the `env!()` macro:\n\n```rust\n// Retrieve an environment variable set at build (compile) time.\nconst BUILD_VALUE: \u0026str = env!(\"MY_BUILD_VAR\");\n```\n\nIn your CDK code in the `lib/` folder, add the following line:\n\n```ts\n// Enable environment variables at compile or build time.\nSettings.BUILD_ENVIRONMENT = {\n    MY_BUILD_VAR: 'Hello World! Testing 123.',\n};\n```\n\n[features]: https://doc.rust-lang.org/cargo/reference/features.html\n[`env!`]: https://doc.rust-lang.org/std/macro.env.html\n\n## Rust Function Properties\n\nBelow lists some commonly used properties you can pass in to the `RustFunction` construct.\n\n| Name               | Description                                                                                                                                                                                                                                                                                                                                                                                     |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `target`           | Build target to cross-compile to. Defaults to the target for the **arm64** architecture, `aarch64-unknown-linux-gnu`.                                                                                                                                                                                                                                                                           |\n| `directory`        | Entry point where the project's main `Cargo.toml` is located. By default, the construct will use directory where `cdk` was invoked as the directory where Cargo files are located.                                                                                                                                                                                                              |\n| `buildDir`         | Default Build directory, which defaults to a `.build` folder under the project's root directory.                                                                                                                                                                                                                                                                                                |\n| `bin`              | Executable name to pass to `--bin`                                                                                                                                                                                                                                                                                                                                                              |\n| `package`          | Workspace package name to pass to `--package`                                                                                                                                                                                                                                                                                                                                                   |\n| `setupLogging`     | Determines whether we want to set up [library logging](https://rust-lang-nursery.github.io/rust-cookbook/development_tools/debugging/config_log.html) - i.e. set the `RUST_LOG` environment variable - for the lambda function.\u003cbr\u003e\u003cbr\u003eThe format defaults to `warn,module_name=debug`, which means that the default log level is `warn`, and the executable or library's log level is `debug`. |\n|                    |\n| `features`         | A list of features to activate when compiling Rust code. These must also be added to the `Cargo.toml` file.                                                                                                                                                                                                                                                                                     |\n| `buildEnvironment` | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cargo lambda`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                                                                                                                                                                       |\n| `extraBuildArgs`   | Additional arguments that are passed in at build time to `cargo lambda`. For example, [`--all-features`].                                                                                                                                                                                                                                                                                       |\n\n## Settings\n\nSettings can be imported as follows:\n\n```ts\nimport { Settings } from 'rust.aws-cdk-lambda';\n```\n\nBelow are some useful _global_ defaults which can be set for all Rust Lambda Functions in a CDK app.\n\n| Name                 | Description                                                                                                                                                                                                                                                                                                                                                                                       |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `BUILD_INDIVIDUALLY` | Whether to build each executable individually, either via `--bin` or `--package`.                                                                                                                                                                                                                                                                                                                 |\n| `DEFAULT_LOG_LEVEL`  | Log Level for non-module libraries. Note that this value is only used when `RustFunctionProps.setupLogging` is enabled. Defaults to `warn`.                                                                                                                                                                                                                                                       |\n| `MODULE_LOG_LEVEL`   | Log Level for a module (i.e. the executable). Note that this value is only used when `RustFunctionProps.setupLogging` is enabled. Defaults to `debug`.                                                                                                                                                                                                                                            |\n| `WORKSPACE_DIR`      | Sets the root workspace directory. By default, the workspace directory is assumed to be the directory where `cdk` was invoked.\u003cbr\u003e\u003cbr\u003eThis directory should contain at the minimum a `Cargo.toml` file which defines the workspace members.                                                                                                                                                       |\n| `FEATURES`           | A list of features to activate when compiling Rust code. These must also be added to the `Cargo.toml` file.                                                                                                                                                                                                                                                                                       |\n| `BUILD_ENVIRONMENT`  | Key-value pairs that are passed in at compile time, i.e. to `cargo build` or `cargo lambda`. This differs from `environment`, which determines the environment variables which are set on the AWS Lambda function itself.                                                                                                                                                                         |\n| `EXTRA_BUILD_ARGS`   | Additional arguments that are passed in at build time to both `cargo lambda`. For example, [`--all-features`].                                                                                                                                                                                                                                                                                    |\n| `SKIP_BUILD`         | Whether to skip building Rust Lambdas -- e.g. skip the compile step with `cargo lambda`.\u003cbr\u003e\u003cbr\u003eAlternatively, this can be set in the `build` context, when invoking `cdk` -- for example:\u003cbr\u003e`$ cdk synth -c build=[T \\| true \\| 1 \\| Y \\| yes \\| ok \\| on]`\u003cbr\u003eAny values other than the listed evaluate to `false`. So, this would skip the build step on `synth`:\u003cbr\u003e`$ cdk synth -c build=0` |\n|                      |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnag%2Frust.aws-cdk-lambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnag%2Frust.aws-cdk-lambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnag%2Frust.aws-cdk-lambda/lists"}