# Cargo Lambda CDK construct
This library provides constructs for Rust Lambda functions built with Cargo Lambda
To use this module you will either need to have [Cargo Lambda installed](https://www.cargo-lambda.info/guide/installation.html) (`0.12.0` or later), or `Docker` installed.
See [Local Bundling](#local-bundling)/[Docker Bundling](#docker-bundling) for more information.
## Rust Function
Define a `RustFunction`:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(stack, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
});
```
The layout for this Rust project could look like this:
```bash
lambda-project
├── Cargo.toml
└── src
└── main.rs
```
### Runtime
The `RustFunction` uses the `provided.al2023` runtime. If you want to change it, you can use the property `runtime`. The only other valid option is `provided.al2`:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(stack, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
runtime: 'provided.al2',
});
```
## Rust Extension
Define a `RustExtension` that get's deployed as a layer to use it with any other function later.
```python
import { RustExtension, RustFunction } from 'cargo-lambda-cdk';
const extensionLayer = new RustExtension(this, 'Rust extension', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
});
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
layers: [
extensionLayer
],
});
```
## Bundling
Bundling is the process by which `cargo lambda` gets called to build, package, and deliver the Rust
binary for CDK. This construct provides two methods of bundling:
* Local bundling where the locally installed cargo lambda tool will run
* Docker bundling where a Dockerfile can be specified to build an image
### Local Bundling
If `Cargo Lambda` is installed locally then it will be used to bundle your code in your environment. Otherwise, bundling will happen in a Lambda compatible Docker container with the Docker platform based on the target architecture of the Lambda function.
### Environment
Use the `environment` prop to define additional environment variables when Cargo Lambda runs:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
environment: {
HELLO: 'WORLD',
},
},
});
```
### Cargo Build profiles
Use the `profile` option if you want to build with a different Cargo profile that's not `release`:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
profile: 'dev'
},
});
```
### Cargo Lambda Build flags
Use the `cargoLambdaFlags` option to add additional flags to the `cargo lambda build` command that's executed to bundle your function. You don't need to use this flag to set options like the target architecture or the binary to compile, since the construct infers those from other props.
If these flags include a `--target` flag, it will override the `architecture` option. If these flags include a `--release` or `--profile` flag, it will override the release or any other profile specified.
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
cargoLambdaFlags: [
'--target',
'x86_64-unknown-linux-musl',
'--debug',
'--disable-optimizations',
],
},
});
```
### Docker
To force bundling in a docker container even if `Cargo Lambda` is available in your environment, set the `forcedDockerBundling` prop to `true`. This is useful if you want to make sure that your function is built in a consistent Lambda compatible environment.
By default, these constructs use `ghcr.io/cargo-lambda/cargo-lambda` as the image to build with. Use the `bundling.dockerImage` prop to use a custom bundling image:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),
},
});
```
Additional docker options such as the user, file access, working directory or volumes can be configured by using the `bundling.dockerOptions` prop:
```python
import * as cdk from 'aws-cdk-lib';
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
dockerOptions: {
bundlingFileAccess: cdk.BundlingFileAccess.VOLUME_COPY,
},
},
});
```
This property mirrors values from the `cdk.BundlingOptions` and is passed into `Code.fromAsset`.
### Command hooks
It is possible to run additional commands by specifying the `commandHooks` prop:
```python
import { RustFunction } from 'cargo-lambda-cdk';
new RustFunction(this, 'Rust function', {
manifestPath: 'path/to/package/directory/with/Cargo.toml',
bundling: {
commandHooks: {
// run tests
beforeBundling(inputDir: string, _outputDir: string): string[] {
return ['cargo test'];
},
},
},
});
```
The following hooks are available:
* `beforeBundling`: runs before all bundling commands
* `afterBundling`: runs after all bundling commands
They all receive the directory containing the `Cargo.toml` 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.
## Additional considerations
Depending on how you structure your Rust application, you may want to change the `assetHashType` parameter.
By default this parameter is set to `AssetHashType.OUTPUT` which means that the CDK will calculate the asset hash
(and determine whether or not your code has changed) based on the Rust executable that is created.
If you specify `AssetHashType.SOURCE`, the CDK will calculate the asset hash by looking at the folder
that contains your `Cargo.toml` file. If you are deploying a single Lambda function, or you want to redeploy
all of your functions if anything changes, then `AssetHashType.SOURCE` will probaby work.
## LICENSE
This software is released under MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/cargo-lambda/cargo-lambda-cdk.git",
"name": "cargo-lambda-cdk",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": null,
"keywords": null,
"author": "David Calavera",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/71/40/27be92ddfd1286ee91d9cddc4d6492575c2ea8c0dd31be6854d6f37c06c3/cargo-lambda-cdk-0.0.22.tar.gz",
"platform": null,
"description": "# Cargo Lambda CDK construct\n\nThis library provides constructs for Rust Lambda functions built with Cargo Lambda\n\nTo use this module you will either need to have [Cargo Lambda installed](https://www.cargo-lambda.info/guide/installation.html) (`0.12.0` or later), or `Docker` installed.\nSee [Local Bundling](#local-bundling)/[Docker Bundling](#docker-bundling) for more information.\n\n## Rust Function\n\nDefine a `RustFunction`:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(stack, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n});\n```\n\nThe layout for this Rust project could look like this:\n\n```bash\nlambda-project\n\u251c\u2500\u2500 Cargo.toml\n\u2514\u2500\u2500 src\n \u2514\u2500\u2500 main.rs\n```\n\n### Runtime\n\nThe `RustFunction` uses the `provided.al2023` runtime. If you want to change it, you can use the property `runtime`. The only other valid option is `provided.al2`:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(stack, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n runtime: 'provided.al2',\n});\n```\n\n## Rust Extension\n\nDefine a `RustExtension` that get's deployed as a layer to use it with any other function later.\n\n```python\nimport { RustExtension, RustFunction } from 'cargo-lambda-cdk';\n\nconst extensionLayer = new RustExtension(this, 'Rust extension', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n});\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n layers: [\n extensionLayer\n ],\n});\n```\n\n## Bundling\n\nBundling is the process by which `cargo lambda` gets called to build, package, and deliver the Rust\nbinary for CDK. This construct provides two methods of bundling:\n\n* Local bundling where the locally installed cargo lambda tool will run\n* Docker bundling where a Dockerfile can be specified to build an image\n\n### Local Bundling\n\nIf `Cargo Lambda` is installed locally then it will be used to bundle your code in your environment. Otherwise, bundling will happen in a Lambda compatible Docker container with the Docker platform based on the target architecture of the Lambda function.\n\n### Environment\n\nUse the `environment` prop to define additional environment variables when Cargo Lambda runs:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n environment: {\n HELLO: 'WORLD',\n },\n },\n});\n```\n\n### Cargo Build profiles\n\nUse the `profile` option if you want to build with a different Cargo profile that's not `release`:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n profile: 'dev'\n },\n});\n```\n\n### Cargo Lambda Build flags\n\nUse the `cargoLambdaFlags` option to add additional flags to the `cargo lambda build` command that's executed to bundle your function. You don't need to use this flag to set options like the target architecture or the binary to compile, since the construct infers those from other props.\n\nIf these flags include a `--target` flag, it will override the `architecture` option. If these flags include a `--release` or `--profile` flag, it will override the release or any other profile specified.\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n cargoLambdaFlags: [\n '--target',\n 'x86_64-unknown-linux-musl',\n '--debug',\n '--disable-optimizations',\n ],\n },\n});\n```\n\n### Docker\n\nTo force bundling in a docker container even if `Cargo Lambda` is available in your environment, set the `forcedDockerBundling` prop to `true`. This is useful if you want to make sure that your function is built in a consistent Lambda compatible environment.\n\nBy default, these constructs use `ghcr.io/cargo-lambda/cargo-lambda` as the image to build with. Use the `bundling.dockerImage` prop to use a custom bundling image:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),\n },\n});\n```\n\nAdditional docker options such as the user, file access, working directory or volumes can be configured by using the `bundling.dockerOptions` prop:\n\n```python\nimport * as cdk from 'aws-cdk-lib';\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n dockerOptions: {\n bundlingFileAccess: cdk.BundlingFileAccess.VOLUME_COPY,\n },\n },\n});\n```\n\nThis property mirrors values from the `cdk.BundlingOptions` and is passed into `Code.fromAsset`.\n\n### Command hooks\n\nIt is possible to run additional commands by specifying the `commandHooks` prop:\n\n```python\nimport { RustFunction } from 'cargo-lambda-cdk';\n\nnew RustFunction(this, 'Rust function', {\n manifestPath: 'path/to/package/directory/with/Cargo.toml',\n bundling: {\n commandHooks: {\n // run tests\n beforeBundling(inputDir: string, _outputDir: string): string[] {\n return ['cargo test'];\n },\n },\n },\n});\n```\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 `Cargo.toml` file (`inputDir`) and the\ndirectory where the bundled asset will be output (`outputDir`). They must return\nan array of commands to run. Commands are chained with `&&`.\n\nThe commands will run in the environment in which bundling occurs: inside the\ncontainer for Docker bundling or on the host OS for local bundling.\n\n## Additional considerations\n\nDepending on how you structure your Rust application, you may want to change the `assetHashType` parameter.\nBy default this parameter is set to `AssetHashType.OUTPUT` which means that the CDK will calculate the asset hash\n(and determine whether or not your code has changed) based on the Rust executable that is created.\n\nIf you specify `AssetHashType.SOURCE`, the CDK will calculate the asset hash by looking at the folder\nthat contains your `Cargo.toml` file. If you are deploying a single Lambda function, or you want to redeploy\nall of your functions if anything changes, then `AssetHashType.SOURCE` will probaby work.\n\n## LICENSE\n\nThis software is released under MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CDK Construct to build Rust functions with Cargo Lambda",
"version": "0.0.22",
"project_urls": {
"Homepage": "https://github.com/cargo-lambda/cargo-lambda-cdk.git",
"Source": "https://github.com/cargo-lambda/cargo-lambda-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aaa2f42190e6459700d7bcfcf89e3f11c8e51eda3139854a0f7f9aab90625f38",
"md5": "2c474037249ee18b04adcf8e751c8fe2",
"sha256": "6ad549d56d611fa7fcbbdd35f8eddf3f428397c4f4359c2ed40ae7466fe39c89"
},
"downloads": -1,
"filename": "cargo_lambda_cdk-0.0.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c474037249ee18b04adcf8e751c8fe2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 12151412,
"upload_time": "2024-05-15T16:48:20",
"upload_time_iso_8601": "2024-05-15T16:48:20.340876Z",
"url": "https://files.pythonhosted.org/packages/aa/a2/f42190e6459700d7bcfcf89e3f11c8e51eda3139854a0f7f9aab90625f38/cargo_lambda_cdk-0.0.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "714027be92ddfd1286ee91d9cddc4d6492575c2ea8c0dd31be6854d6f37c06c3",
"md5": "17c4bdd400b990b7b0e0afdf6a06dd19",
"sha256": "c876722bb220b03a23794fb41f44fcb70944270e1c8a0480b234190cd54d3a47"
},
"downloads": -1,
"filename": "cargo-lambda-cdk-0.0.22.tar.gz",
"has_sig": false,
"md5_digest": "17c4bdd400b990b7b0e0afdf6a06dd19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 12152987,
"upload_time": "2024-05-15T16:48:23",
"upload_time_iso_8601": "2024-05-15T16:48:23.904227Z",
"url": "https://files.pythonhosted.org/packages/71/40/27be92ddfd1286ee91d9cddc4d6492575c2ea8c0dd31be6854d6f37c06c3/cargo-lambda-cdk-0.0.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-15 16:48:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cargo-lambda",
"github_project": "cargo-lambda-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cargo-lambda-cdk"
}
JSON
