io.github.cdklabs.awslambdarust.package-info Maven / Gradle / Ivy
/**
* Amazon Lambda Rust Library
*
* ---
*
* 
*
*
*
* 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 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.
*
*
*
*
*
*
*
* 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 for more information.
*
*
Rust Function
*
*
* .
* ├── 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:
*
*
* RustFunction myFunction = new RustFunction(this, "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.
*
*
* RustFunction.Builder.create(this, "my_function1")
* .entry("/path/to/directory/with/Cargo.toml")
* .binaryName("my_function")
* .build();
*
* // You can also specify entry path directory which will contain your Cargo.toml file
* // You can also specify entry path directory which will contain your Cargo.toml file
* RustFunction.Builder.create(this, "my_function2")
* .entry("/path/to/directory")
* .binaryName("my_function")
* .build();
*
*
* For more complex project structure combining multiple Rust Lambda function, the construct offer the ability to use Binaries or Workspaces defined in your Cargo project.
*
* Given a sample project structure:
*
*
* .
* ├── Cargo.toml
* ├── my_lambda_1
* │ ├── Cargo.toml
* │ └── src
* │ └── main.rs
* └── my_lambda_2
* ├── Cargo.toml
* └── src
* └── main.rs
*
*
* And with a given Cargo.toml:
*
*
* [workspace]
* members = [
* "my_lambda_1",
* "my_lambda_2"
* ]
*
*
* Rust functions can be declared using binaryName property:
*
*
* RustFunction.Builder.create(this, "FirstFunction")
* .binaryName("my_lambda_1")
* .build();
*
* RustFunction.Builder.create(this, "SecondFunction")
* .binaryName("my_lambda_2")
* .build();
*
*
*
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 and Cross for deployment, as outlined
* in the official AWS docs, you can define the packageManager property:
*
*
* RustFunction.Builder.create(this, "FirstFunction")
* .binaryName("my_lambda_1")
* .bundling(BundlingOptions.builder()
* .packageManagerType(PackageManagerType.CROSS)
* .build())
* .build();
*
*
*
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.
*
*
Local Bundling
*
* By default, Cargo Lambda uses the Zig toolchain 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:
*
*
* import software.amazon.awscdk.services.lambda.Architecture;
*
*
* RustFunction.Builder.create(this, "my_function")
* .architecture(Architecture.ARM_64)
* .build();
*
*
* If bundling is made locally for ARM-64 or X86-64, make sure to install the dedicated target:
*
*
* 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:
*
*
* RustFunction.Builder.create(this, "my_function")
* .bundling(BundlingOptions.builder()
* .environment(Map.of(
* "HELLO", "world"))
* .build())
* .build();
*
*
* Use the bundling.buildArgs to pass build arguments to cargo:
*
*
* RustFunction.Builder.create(this, "my_function")
* .bundling(BundlingOptions.builder()
* .extraBuildArgs(List.of("--all-features"))
* .build())
* .build();
*
*
* Use the bundling.dockerImage to use a custom Docker bundling image:
*
*
* RustFunction.Builder.create(this, "my_function")
* .bundling(BundlingOptions.builder()
* .dockerImage(DockerImage.fromBuild("/path/to/Dockerfile"))
* .build())
* .build();
*
*
* You can set additional Docker options to configure the build environment:
*
*
* RustFunction.Builder.create(this, "my_function")
* .bundling(BundlingOptions.builder()
* .network("host")
* .securityOpt("no-new-privileges")
* .user("user:group")
* .volumesFrom(List.of("777f7dc92da7"))
* .volumes(List.of(DockerVolume.builder().hostPath("/host-path").containerPath("/container-path").build()))
* .build())
* .build();
*
*
*
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.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
package io.github.cdklabs.awslambdarust;