feat: Rust cargo lambda workflow

.github/workflows/build.yml

@@ -21,6 +21,7 @@ jobs:
       - python-integration
       - ruby-integration
       - dotnet-integration
+      - rust-cargo-lambda-integration
     steps:
       - name: report-failure
         if: |
@@ -33,7 +34,8 @@ jobs:
           needs.custom-make-integration.result != 'success' ||
           needs.python-integration.result != 'success' ||
           needs.ruby-integration.result != 'success' ||
-          needs.dotnet-integration.result != 'success'
+          needs.dotnet-integration.result != 'success' ||
+          needs.rust-cargo-lambda-integration.result != 'success'
         run: exit 1
       - name: report-success
         run: exit 0
@@ -296,3 +298,57 @@ jobs:
           python-version: ${{ matrix.python }}
       - run: make init
       - run: pytest -vv tests/integration/workflows/dotnet_clipackage
+
+  rust-cargo-lambda-integration:
+    name: ${{ matrix.os }} / ${{ matrix.python }} / rust-cargo-lambda
+    if: github.repository_owner == 'aws'
+    runs-on: ${{ matrix.os }}
+    env:
+      CARGO_LAMBDA_VERSION: 0.15.0
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+        python:
+          - "3.9"
+          - "3.8"
+          - "3.7"
+        rust:
+          - stable
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+
+      # Install and configure Rust
+      - name: Install rustup
+        run: |
+          : install rustup if needed
+          if ! command -v rustup &> /dev/null ; then
+            curl --proto '=https' --tlsv1.2 --retry 10 --retry-connrefused -fsSL "https://sh.rustup.rs" | sh -s -- --default-toolchain none -y
+            echo "${CARGO_HOME:-$HOME/.cargo}/bin" >> $GITHUB_PATH
+          fi
+        if: ${{ matrix.os }} == 'ubuntu-latest'
+      - name: rustup toolchain install ${{ matrix.rust }}
+        run: rustup toolchain install ${{ matrix.rust }} --profile minimal --no-self-update
+      - run: rustup default ${{ matrix.rust }}
+      - run: |
+          : disable incremental compilation
+          echo CARGO_INCREMENTAL=0 >> $GITHUB_ENV
+      - run: |
+          : enable colors in Cargo output
+          echo CARGO_TERM_COLOR=always >> $GITHUB_ENV
+
+      # Install and configure Cargo Lambda
+      - name: Install Cargo Lambda
+        run: pip install cargo-lambda==$CARGO_LAMBDA_VERSION
+      - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - run: make init
+      - run: pytest -vv tests/integration/workflows/rust_cargo

Makefile

@@ -2,10 +2,13 @@ init:
 	LAMBDA_BUILDERS_DEV=1 pip install -e '.[dev]'
 
 test:
-	# Run unit tests
+	# Run unit and functional tests
 	# Fail if coverage falls below 94%
 	LAMBDA_BUILDERS_DEV=1 pytest -vv --cov aws_lambda_builders --cov-report term-missing --cov-fail-under 94 tests/unit tests/functional
 
+unit-test:
+	LAMBDA_BUILDERS_DEV=1 pytest tests/unit
+
 func-test:
 	LAMBDA_BUILDERS_DEV=1 pytest tests/functional
 

README.md

@@ -18,6 +18,7 @@ Lambda Builders currently contains the following workflows
 * Typescript with esbuild
 * Ruby with Bundler
 * Go with Mod
+* Rust with Cargo
 
 In Addition to above workflows, AWS Lambda Builders also supports *Custom Workflows* through a Makefile.
 

aws_lambda_builders/workflows/__init__.py

@@ -11,3 +11,4 @@
 import aws_lambda_builders.workflows.dotnet_clipackage
 import aws_lambda_builders.workflows.custom_make
 import aws_lambda_builders.workflows.nodejs_npm_esbuild
+import aws_lambda_builders.workflows.rust_cargo

aws_lambda_builders/workflows/rust_cargo/DESIGN.md

@@ -0,0 +1,28 @@
+# Rust Cargo Builder
+
+## Scope
+
+This package enables the creation of a Lambda deployment package for Rust projects managed using the [cargo](https://doc.rust-lang.org/cargo/) build tool targeting Lambda's "provided" runtime. Rust support for the provided runtime is bundled as a compilation dependency of these projects, provided by the [lambda](https://github.com/awslabs/aws-lambda-rust-runtime) crate.
+
+## Implementation
+
+This package uses [Cargo Lambda](https://www.cargo-lambda.info) to do all the heavy lifting for cross compilation, target validation, and other executable optimizations.
+
+It supports X86-64 architectures with the target `x86_64-unknown-linux-gnu` by default. It also supports ARM architectures with the target option `aarch64-unknown-linux-gnu`. Those are the only two valid targets. The target is automatically configured based on the `architecture` option in the `RustCargoLambdaWorkflow`.
+
+The general algorithm for preparing a rust executable for use on AWS Lambda is as follows.
+
+### Build
+
+It builds a binary in the standard cargo target directory. The binary's name is always `bootstrap`, and it's always located under `target/lambda/HANDLER_NAME/bootstrap`.
+
+### Copy and Rename executable
+
+It then copies the executable to the target directory honoring the provided runtime's [expectation on executable names](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html).
+
+## Notes
+
+Like the go builders, the workflow argument `options.artifact_executable_name`
+interface can used to provide a handler name that resolves to an executable. This
+enables sam support for cargo workspaces allowing for one rust project to have multiple lambdas. Cargo workspaces have a notion of a `package` and `bin`. A `package` can have
+multiple bins but typically `packages` have a 1-to-1 relationship with a default `bin`: `main.rs`. The handler names must be uniques across a Rust project, regardless of how many packages and binaries that project includes.

aws_lambda_builders/workflows/rust_cargo/__init__.py

@@ -0,0 +1,5 @@
+"""
+Builds Rust Lambda functions using Cargo Lambda
+"""
+
+from .workflow import RustCargoLambdaWorkflow

aws_lambda_builders/workflows/rust_cargo/actions.py

@@ -0,0 +1,146 @@
+"""
+Rust Cargo build actions
+"""
+
+import logging
+import os
+
+from aws_lambda_builders.workflow import BuildMode
+from aws_lambda_builders.actions import ActionFailedError, BaseAction, Purpose
+from aws_lambda_builders.architecture import X86_64, ARM64
+from .exceptions import CargoLambdaExecutionException
+from .utils import OSUtils
+
+
+LOG = logging.getLogger(__name__)
+
+
+class RustCargoLambdaBuildAction(BaseAction):
+    NAME = "CargoLambdaBuild"
+    DESCRIPTION = "Building the project using Cargo Lambda"
+    PURPOSE = Purpose.COMPILE_SOURCE
+
+    def __init__(
+        self,
+        source_dir,
+        binaries,
+        mode,
+        subprocess_cargo_lambda,
+        architecture=X86_64,
+        handler=None,
+        flags=None,
+    ):
+        """
+        Build the a Rust executable
+
+        :type source_dir: str
+        :param source_dir:
+            Path to a folder containing the source code
+
+        :type binaries: dict
+        :param binaries:
+            Resolved path dependencies
+
+        :type mode: str
+        :param mode:
+            Mode the build should produce
+
+        :type architecture: str, optional
+        :param architecture:
+            Target architecture to build the binary, either arm64 or x86_64
+
+        :type handler: str, optional
+        :param handler:
+            Handler name in `bin_name` format
+
+        :type flags: list, optional
+        :param flags:
+            Extra list of flags to pass to `cargo lambda build`
+
+        :type subprocess_cargo_lambda: aws_lambda_builders.workflows.rust_cargo.cargo_lambda.SubprocessCargoLambda
+        :param subprocess_cargo_lambda: An instance of the Cargo Lambda process wrapper
+        """
+
+        self._source_dir = source_dir
+        self._mode = mode
+        self._binaries = binaries
+        self._handler = handler
+        self._flags = flags
+        self._architecture = architecture
+        self._subprocess_cargo_lambda = subprocess_cargo_lambda
+
+    def build_command(self):
+        cmd = [self._binaries["cargo"].binary_path, "lambda", "build"]
+        if self._mode != BuildMode.DEBUG:
+            cmd.append("--release")
+        if self._architecture == ARM64:
+            cmd.append("--arm64")
+        if self._handler:
+            cmd.extend(["--bin", self._handler])
+        if self._flags:
+            cmd.extend(self._flags)
+
+        return cmd
+
+    def execute(self):
+        try:
+            return self._subprocess_cargo_lambda.run(command=self.build_command(), cwd=self._source_dir)
+        except CargoLambdaExecutionException as ex:
+            raise ActionFailedError(str(ex))
+
+
+class RustCopyAndRenameAction(BaseAction):
+    NAME = "RustCopyAndRename"
+    DESCRIPTION = "Copy Rust executable, renaming if needed"
+    PURPOSE = Purpose.COPY_SOURCE
+
+    def __init__(self, source_dir, artifacts_dir, handler=None, osutils=OSUtils()):
+        """
+        Copy and rename Rust executable
+
+        Parameters
+        ----------
+        source_dir : str
+            Path to a folder containing the source code
+
+        artifacts_dir : str
+            Path to a folder containing the deployable artifacts
+
+        handler : str, optional
+            Handler name in `package.bin_name` or `bin_name` format
+
+        osutils : aws_lambda_builders.workflows.rust_cargo.utils.OSUtils, optional
+            Optional, External IO utils
+        """
+        self._source_dir = source_dir
+        self._handler = handler
+        self._artifacts_dir = artifacts_dir
+        self._osutils = osutils
+
+    def base_path(self):
+        return os.path.join(self._source_dir, "target", "lambda")
+
+    def binary_path(self):
+        base = self.base_path()
+        if self._handler:
+            binary_path = os.path.join(base, self._handler, "bootstrap")
+            LOG.debug("copying function binary from %s", binary_path)
+            return binary_path
+
+        output = os.listdir(base)
+        if len(output) == 1:
+            binary_path = os.path.join(base, output[0], "bootstrap")
+            LOG.debug("copying function binary from %s", binary_path)
+            return binary_path
+
+        LOG.warning("unexpected list of binary directories: [%s]", ", ".join(output))
+        raise CargoLambdaExecutionException(
+            message="unable to find function binary, use the option `artifact_executable_name` to specify the name"
+        )
+
+    def execute(self):
+        self._osutils.makedirs(self._artifacts_dir)
+        binary_path = self.binary_path()
+        destination_path = os.path.join(self._artifacts_dir, "bootstrap")
+        LOG.debug("copying function binary from %s to %s", binary_path, destination_path)
+        self._osutils.copyfile(binary_path, destination_path)