# Amazon Lambda Rust Library
<!--BEGIN STABILITY BANNER-->---
> The APIs of higher level constructs in this module are experimental and under active development.
> They are subject to non-backward compatible changes or removal in any future version. These are
> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
> announced in the release notes. This means that while you may use them, you may need to update
> your source code when upgrading to a newer version of this package.
---
<!--END STABILITY BANNER-->
This library provides constructs for Rust Lambda functions.
The `rust.RustFunction` construct creates a Lambda function with automatic building and bundling of Rust code.
To use this module you will either need to have `cargo-lambda` installed or Docker installed.
See [Local Bundling/Docker Bundling](#local-bundling) for more information.
## Rust Function
```plaintext
.
├── my-construct.ts
├── myconstruct.my_function
│ ├── Cargo.toml
│ └── src
│ └── main.rs
```
By default, the construct will use the name of the defining file and the construct's id to look up the entry file by following this pattern `defining-file.id/Cargo.toml`. In `my-construct.ts` above we have:
```python
my_function = rust.RustFunction(self, "my_function")
```
Alternatively, `entry` and `binaryName` properties can be specified to override this default behavior. If no `binaryName` argument is passed in, it will default to the package name as defined in the main `Cargo.toml`.
```python
rust.RustFunction(self, "my_function1",
entry="/path/to/directory/with/Cargo.toml",
binary_name="my_function"
)
# You can also specify entry path directory which will contain your Cargo.toml file
rust.RustFunction(self, "my_function2",
entry="/path/to/directory",
binary_name="my_function"
)
```
For more complex project structure combining multiple Rust Lambda function, the construct offer the ability to use Binaries or [Workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) defined in your Cargo project.
Given a sample project structure:
```plaintext
.
├── Cargo.toml
├── my_lambda_1
│ ├── Cargo.toml
│ └── src
│ └── main.rs
└── my_lambda_2
├── Cargo.toml
└── src
└── main.rs
```
And with a given `Cargo.toml`:
```toml
[workspace]
members = [
"my_lambda_1",
"my_lambda_2"
]
```
Rust functions can be declared using `binaryName` property:
```python
rust.RustFunction(self, "FirstFunction",
binary_name="my_lambda_1"
)
rust.RustFunction(self, "SecondFunction",
binary_name="my_lambda_2"
)
```
## How It Works
When bundling the code, the `rust.RustFunction` runs will build and bundle your binary by passing `--release` and `--target` flags to the Cargo build command, so it compiles for a Lambda environment - which defaults to the **aarch64-unknown-linux-gnu** target.
### Use `cross` for Deployment
If you instead prefer to use [Docker](https://www.docker.com/get-started) and [Cross](https://github.com/rust-embedded/cross) for deployment, as outlined
in the [official AWS docs](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/lambda.html), you can define the `packageManager` property:
```python
rust.RustFunction(self, "FirstFunction",
binary_name="my_lambda_1",
bundling=rust.BundlingOptions(
package_manager_type=rust.PackageManagerType.CROSS
)
)
```
## Customizing the underlying Lambda function
All properties of `lambda.Function` can be used to customize the underlying `lambda.Function`.
See also the [AWS Lambda construct library](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/aws-lambda).
## Local Bundling
By default, Cargo Lambda uses the [Zig toolchain](https://crates.io/crates/cargo-zigbuild) to cross compile your code.
This is the most convenient cross compilation mechanism because it comes built in, and it works for the majority of use cases.
Any pure Rust Lambda function should compile correctly with this toolchain.
By default, Construct will compile the code for Linux X86-64 architectures, but you can compile for ARM-64 architectures by providing the right property if needed:
```python
from aws_cdk.aws_lambda import Architecture
rust.RustFunction(self, "my_function",
architecture=Architecture.ARM_64
)
```
If bundling is made locally for **ARM-64** or **X86-64**, make sure to install the dedicated target:
```bash
rustup target add aarch64-unknown-linux-gnu
rustup target add x86_64-unknown-linux-gnu
```
## Customizing Docker bundling
To force bundling in a Docker container even if `Zig toolchain` is available in your environment, set `bundling.forceDockerBundling` to true.
Use `bundling.environment` to define environments variables when `cargo` runs:
```python
rust.RustFunction(self, "my_function",
bundling=rust.BundlingOptions(
environment={
"HELLO": "world"
}
)
)
```
Use the `bundling.buildArgs` to pass build arguments to `cargo`:
```python
rust.RustFunction(self, "my_function",
bundling=rust.BundlingOptions(
extra_build_args=["--all-features"]
)
)
```
Use the `bundling.dockerImage` to use a custom Docker bundling image:
```python
rust.RustFunction(self, "my_function",
bundling=rust.BundlingOptions(
docker_image=DockerImage.from_build("/path/to/Dockerfile")
)
)
```
You can set additional Docker options to configure the build environment:
```python
rust.RustFunction(self, "my_function",
bundling=rust.BundlingOptions(
network="host",
security_opt="no-new-privileges",
user="user:group",
volumes_from=["777f7dc92da7"],
volumes=[DockerVolume(host_path="/host-path", container_path="/container-path")]
)
)
```
## Command hooks
It is possible to run additional commands by specifying the commandHooks property.
The following hooks are available:
* **beforeBundling**: runs before all bundling commands
* **afterBundling**: runs after all bundling commands
They all receive the directory containing the lock file (inputDir) and the directory where the bundled asset will be output (outputDir).
They must return an array of commands to run. Commands are chained with &&.
The commands will run in the environment in which bundling occurs: inside the container for Docker bundling or on the host OS for local bundling.
Raw data
{
"_id": null,
"home_page": "https://github.com/cdklabs/aws-lambda-rust.git",
"name": "aws-cdk.aws-lambda-rust",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services<aws-cdk-dev@amazon.com>",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/85/23/28e6ec64282e94f96fa622daeec1df76cf011e62793233cc76e66899eab4/aws-cdk.aws-lambda-rust-0.0.0.tar.gz",
"platform": null,
"description": "# Amazon Lambda Rust Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\nThis library provides constructs for Rust Lambda functions.\n\nThe `rust.RustFunction` construct creates a Lambda function with automatic building and bundling of Rust code.\n\nTo use this module you will either need to have `cargo-lambda` installed or Docker installed.\n\nSee [Local Bundling/Docker Bundling](#local-bundling) for more information.\n\n## Rust Function\n\n```plaintext\n.\n\u251c\u2500\u2500 my-construct.ts\n\u251c\u2500\u2500 myconstruct.my_function\n\u2502 \u251c\u2500\u2500 Cargo.toml\n\u2502 \u2514\u2500\u2500 src\n\u2502 \u2514\u2500\u2500 main.rs\n```\n\nBy default, the construct will use the name of the defining file and the construct's id to look up the entry file by following this pattern `defining-file.id/Cargo.toml`. In `my-construct.ts` above we have:\n\n```python\nmy_function = rust.RustFunction(self, \"my_function\")\n```\n\nAlternatively, `entry` and `binaryName` properties can be specified to override this default behavior. If no `binaryName` argument is passed in, it will default to the package name as defined in the main `Cargo.toml`.\n\n```python\nrust.RustFunction(self, \"my_function1\",\n entry=\"/path/to/directory/with/Cargo.toml\",\n binary_name=\"my_function\"\n)\n\n# You can also specify entry path directory which will contain your Cargo.toml file\nrust.RustFunction(self, \"my_function2\",\n entry=\"/path/to/directory\",\n binary_name=\"my_function\"\n)\n```\n\nFor more complex project structure combining multiple Rust Lambda function, the construct offer the ability to use Binaries or [Workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) defined in your Cargo project.\n\nGiven a sample project structure:\n\n```plaintext\n.\n\u251c\u2500\u2500 Cargo.toml\n\u251c\u2500\u2500 my_lambda_1\n\u2502 \u251c\u2500\u2500 Cargo.toml\n\u2502 \u2514\u2500\u2500 src\n\u2502 \u2514\u2500\u2500 main.rs\n\u2514\u2500\u2500 my_lambda_2\n \u251c\u2500\u2500 Cargo.toml\n \u2514\u2500\u2500 src\n \u2514\u2500\u2500 main.rs\n```\n\nAnd with a given `Cargo.toml`:\n\n```toml\n[workspace]\nmembers = [\n \"my_lambda_1\",\n \"my_lambda_2\"\n]\n```\n\nRust functions can be declared using `binaryName` property:\n\n```python\nrust.RustFunction(self, \"FirstFunction\",\n binary_name=\"my_lambda_1\"\n)\n\nrust.RustFunction(self, \"SecondFunction\",\n binary_name=\"my_lambda_2\"\n)\n```\n\n## How It Works\n\nWhen bundling the code, the `rust.RustFunction` runs will build and bundle your binary by passing `--release` and `--target` flags to the Cargo build command, so it compiles for a Lambda environment - which defaults to the **aarch64-unknown-linux-gnu** target.\n\n### Use `cross` for Deployment\n\nIf you instead prefer to use [Docker](https://www.docker.com/get-started) and [Cross](https://github.com/rust-embedded/cross) for deployment, as outlined\nin the [official AWS docs](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/lambda.html), you can define the `packageManager` property:\n\n```python\nrust.RustFunction(self, \"FirstFunction\",\n binary_name=\"my_lambda_1\",\n bundling=rust.BundlingOptions(\n package_manager_type=rust.PackageManagerType.CROSS\n )\n)\n```\n\n## Customizing the underlying Lambda function\n\nAll properties of `lambda.Function` can be used to customize the underlying `lambda.Function`.\n\nSee also the [AWS Lambda construct library](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/aws-lambda).\n\n## Local Bundling\n\nBy default, Cargo Lambda uses the [Zig toolchain](https://crates.io/crates/cargo-zigbuild) to cross compile your code.\nThis is the most convenient cross compilation mechanism because it comes built in, and it works for the majority of use cases.\nAny pure Rust Lambda function should compile correctly with this toolchain.\n\nBy default, Construct will compile the code for Linux X86-64 architectures, but you can compile for ARM-64 architectures by providing the right property if needed:\n\n```python\nfrom aws_cdk.aws_lambda import Architecture\n\n\nrust.RustFunction(self, \"my_function\",\n architecture=Architecture.ARM_64\n)\n```\n\nIf bundling is made locally for **ARM-64** or **X86-64**, make sure to install the dedicated target:\n\n```bash\nrustup target add aarch64-unknown-linux-gnu\nrustup target add x86_64-unknown-linux-gnu\n```\n\n## Customizing Docker bundling\n\nTo force bundling in a Docker container even if `Zig toolchain` is available in your environment, set `bundling.forceDockerBundling` to true.\n\nUse `bundling.environment` to define environments variables when `cargo` runs:\n\n```python\nrust.RustFunction(self, \"my_function\",\n bundling=rust.BundlingOptions(\n environment={\n \"HELLO\": \"world\"\n }\n )\n)\n```\n\nUse the `bundling.buildArgs` to pass build arguments to `cargo`:\n\n```python\nrust.RustFunction(self, \"my_function\",\n bundling=rust.BundlingOptions(\n extra_build_args=[\"--all-features\"]\n )\n)\n```\n\nUse the `bundling.dockerImage` to use a custom Docker bundling image:\n\n```python\nrust.RustFunction(self, \"my_function\",\n bundling=rust.BundlingOptions(\n docker_image=DockerImage.from_build(\"/path/to/Dockerfile\")\n )\n)\n```\n\nYou can set additional Docker options to configure the build environment:\n\n```python\nrust.RustFunction(self, \"my_function\",\n bundling=rust.BundlingOptions(\n network=\"host\",\n security_opt=\"no-new-privileges\",\n user=\"user:group\",\n volumes_from=[\"777f7dc92da7\"],\n volumes=[DockerVolume(host_path=\"/host-path\", container_path=\"/container-path\")]\n )\n)\n```\n\n## Command hooks\n\nIt is possible to run additional commands by specifying the commandHooks property.\n\nThe following hooks are available:\n\n* **beforeBundling**: runs before all bundling commands\n* **afterBundling**: runs after all bundling commands\n\nThey all receive the directory containing the lock file (inputDir) and the directory where the bundled asset will be output (outputDir).\nThey must return an array of commands to run. Commands are chained with &&.\n\nThe commands will run in the environment in which bundling occurs: inside the container for Docker bundling or on the host OS for local bundling.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "@cdklabs/aws-lambda-rust",
"version": "0.0.0",
"project_urls": {
"Homepage": "https://github.com/cdklabs/aws-lambda-rust.git",
"Source": "https://github.com/cdklabs/aws-lambda-rust.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e5ffaf2dde471e30d79a33a07110a1ad5b045a544b1092a65c3e56b6579a39b",
"md5": "1478fdb89885d4fe5a943e718d1a7276",
"sha256": "760b82a632348964373ee1ad70659669752fd414a870423704a0594d6d0b42a0"
},
"downloads": -1,
"filename": "aws_cdk.aws_lambda_rust-0.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1478fdb89885d4fe5a943e718d1a7276",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 114995,
"upload_time": "2024-01-05T09:57:50",
"upload_time_iso_8601": "2024-01-05T09:57:50.842403Z",
"url": "https://files.pythonhosted.org/packages/8e/5f/faf2dde471e30d79a33a07110a1ad5b045a544b1092a65c3e56b6579a39b/aws_cdk.aws_lambda_rust-0.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "852328e6ec64282e94f96fa622daeec1df76cf011e62793233cc76e66899eab4",
"md5": "80d174bcfcf357fee36bf2dee5e38df4",
"sha256": "c284960d08280c0a95b559b4e225a51bfd4396093a15b306ae8c8a819331722c"
},
"downloads": -1,
"filename": "aws-cdk.aws-lambda-rust-0.0.0.tar.gz",
"has_sig": false,
"md5_digest": "80d174bcfcf357fee36bf2dee5e38df4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 116636,
"upload_time": "2024-01-05T09:57:52",
"upload_time_iso_8601": "2024-01-05T09:57:52.573827Z",
"url": "https://files.pythonhosted.org/packages/85/23/28e6ec64282e94f96fa622daeec1df76cf011e62793233cc76e66899eab4/aws-cdk.aws-lambda-rust-0.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-05 09:57:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cdklabs",
"github_project": "aws-lambda-rust",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-lambda-rust"
}
JSON
