🌅 New template for Rust extensions.

calavera · calavera · commit 944e45a5bd03 · 2024-11-05T21:16:10.000-08:00
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1 @@
+github: [calavera]
diff --git a/.github/actions/rust-setup/action.yml b/.github/actions/rust-setup/action.yml
@@ -0,0 +1,27 @@
+name: Rust Build
+description: Setups a Rust project for AWS Lambda
+
+runs:
+  using: "composite"
+  steps:
+    - uses: dtolnay/rust-toolchain@stable
+
+    - uses: korandoru/setup-zig@v1
+      with:
+        zig-version: 0.13.0
+
+    # Install Cargo Lambda from source until 1.5 is released
+    #
+    # - uses: cargo-bins/cargo-binstall@main
+    # - name: Install cargo-lambda
+    #   shell: bash
+    #   run: cargo binstall -y cargo-lambda
+    #
+    - name: Install cargo-lambda
+      shell: bash
+      run: |
+        git clone https://github.com/cargo-lambda/cargo-lambda.git && \
+        cd cargo-lambda && \
+        make install-local
+
+    - uses: Swatinem/rust-cache@v2
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,77 @@
+name: Test template
+
+on:
+  pull_request:
+    paths:
+      - ".github/actions/**"
+      - ".github/workflows/**"
+      - "template/**"
+      - "CargoLambda.toml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/actions/**"
+      - ".github/workflows/**"
+      - "template/**"
+      - "CargoLambda.toml"
+  workflow_dispatch:
+
+jobs:
+  test-events-extension:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/rust-setup
+
+      - name: Test events extension
+        run: |
+          mkdir -p tests && cd tests && \
+          cargo lambda new --extension -y --template .. events_extension && \
+          cd events_extension && \
+          cargo test && \
+          cargo lambda build --release --extension
+
+  test-logs-extension:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/rust-setup
+
+      - name: Test logs extension without events
+        run: |
+          mkdir -p tests && cd tests && \
+          cargo lambda new --extension --logs --template .. logs_extension && \
+          cd logs_extension && \
+          cargo test && \
+          cargo lambda build --release --extension
+
+      - name: Test logs extension with events
+        run: |
+          mkdir -p tests && cd tests && \
+          cargo lambda new --extension --logs --events --template .. logs_extension_events && \
+          cd logs_extension_events && \
+          cargo test && \
+          cargo lambda build --release --extension
+
+  test-telemetry-extension:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/rust-setup
+
+      - name: Test telemetry extension without events
+        run: |
+          mkdir -p tests && cd tests && \
+          cargo lambda new --extension --telemetry --template .. telemetry_extension && \
+          cd telemetry_extension && \
+          cargo test && \
+          cargo lambda build --release --extension
+
+      - name: Test telemetry extension with events
+        run: |
+          mkdir -p tests && cd tests && \
+          cargo lambda new --extension --telemetry --events --template .. telemetry_extension_events && \
+          cd telemetry_extension_events && \
+          cargo test && \
+          cargo lambda build --release --extension
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+tests
diff --git a/CargoLambda.toml b/CargoLambda.toml
@@ -0,0 +1,7 @@
+[template]
+render_all_files = true
+
+[template.ignore_conditional_files]
+"src/events_extension.rs" = { var = "events", match = false }
+"src/logs_extension.rs" = { var = "logs", match = false }
+"src/telemetry_extension.rs" = { var = "telemetry", match = false }
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,22 @@
+Copyright (c) 2024 David Calavera <david.calavera@gmail.com>
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,20 @@
+# Introduction
+
+This repository contains a template for a Rust project that implements an AWS Lambda extension.
+
+# Prerequisites
+
+- [Rust](https://www.rust-lang.org/tools/install)
+- [Cargo Lambda](https://www.cargo-lambda.info/guide/installation.html)
+
+# Usage
+
+This is the default extensions template that Cargo Lambda uses starting from version 1.5.0. This template doesn't work with older versions of Cargo Lambda.
+
+To create a new project with this template you can simply run `cargo lambda new --extension PROJECT_NAME`. That will download this template and create a new project with the name `PROJECT_NAME`.
+
+If you're making changes to this template, you can run `cargo lambda new --extension --template ./path/to/template PROJECT_NAME` to create a new project with the changes you made to the template.
+
+If you want to create a new project with a specific branch of this repository, you can run `cargo lambda new --extension --template https://github.com/cargo-lambda/new-extensions-template/tree/BRANCH_NAME PROJECT_NAME`.
+
+Read more about Cargo Lambda Templates in [the Cargo Lambda documentation](https://www.cargo-lambda.info/commands/new.html#templates).
diff --git a/template/Cargo.toml b/template/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "{{ project_name }}"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+lambda-extension = "{{ lambda_extension_version | default: "0.11.0" }}"
+serde = "1"
+tokio = { version = "1", features = ["macros"] }
+
+{%- if binary_name %}
+[[bin]]
+name = "{{ binary_name }}"
+path = "src/main.rs"
+test = false
+{%- endif %}
diff --git a/template/README.md b/template/README.md
@@ -0,0 +1,20 @@
+# Introduction
+
+{{ project_name }} is a Rust project that implements an AWS Lambda extension in Rust.
+
+# Prerequisites
+
+- [Rust](https://www.rust-lang.org/tools/install)
+- [Cargo Lambda](https://www.cargo-lambda.info/guide/installation.html)
+
+# Building
+
+To build the project for production, run `cargo lambda build --extension --release`. Remove the `--release` flag to build for development.
+
+Read more about building your lambda extension in [the Cargo Lambda documentation](https://www.cargo-lambda.info/commands/build.html#extensions).
+
+# Deploying
+
+To deploy the project, run `cargo lambda deploy --extension`. This will upload the extension to your AWS account as an AWS Lambda Layer.
+
+Read more about deploying your lambda extension in [the Cargo Lambda documentation](https://www.cargo-lambda.info/commands/deploy.html#extensions).
diff --git a/template/src/events_extension.rs b/template/src/events_extension.rs
@@ -0,0 +1,16 @@
+use lambda_extension::{tracing, LambdaEvent, NextEvent, Error};
+
+/// Process events from the Lambda extension API.
+///
+/// This function is called when the Lambda extension receives an event from the Lambda API.
+pub(crate) async fn events_processor(event: LambdaEvent) -> Result<(), Error> {
+    match event.next {
+        NextEvent::Shutdown(event) => {
+            tracing::info!(event_type = "shutdown", ?event, "shutting down function");
+        }
+        NextEvent::Invoke(event) => {
+            tracing::info!(event_type = "invoke", ?event, "invoking function");
+        }
+    }
+    Ok(())
+}
diff --git a/template/src/logs_extension.rs b/template/src/logs_extension.rs
@@ -0,0 +1,23 @@
+use lambda_extension::{tracing, LambdaLog, LambdaLogRecord, Error};
+
+/// Process logs from the Lambda extension API.
+///
+/// This function is called when the Lambda extension receives logs from the Lambda API.
+/// The Lambda API sends logs in batches, so this function processes a batch of logs at a time.
+/// These logs can come from the function the extension is attached to,
+/// or from another extension that has also been added to the same Lambda function.
+pub(crate) async fn logs_processor(logs: Vec<LambdaLog>) -> Result<(), Error> {
+    for log in logs {
+        match log.record {
+            LambdaLogRecord::Function(record) => {
+                tracing::info!(log_type = "function", ?record, "received function logs");
+            }
+            LambdaLogRecord::Extension(record) => {
+                tracing::info!(log_type = "extension", ?record, "received extension logs");
+            },
+            _ignore_other => {},
+        }
+    }
+
+    Ok(())
+}
diff --git a/template/src/main.rs b/template/src/main.rs
@@ -0,0 +1,36 @@
+{%- if logs or telemetry -%}
+use lambda_extension::{service_fn, tracing, Extension, Error, SharedService};
+{%- else -%}
+use lambda_extension::{service_fn, tracing, Extension, Error};
+{%- endif %}
+
+{% if events -%}
+mod events_extension;
+use events_extension::events_processor;
+{%- endif %}
+
+{% if logs -%}
+mod logs_extension;
+use logs_extension::logs_processor;
+{%- elsif telemetry -%}
+mod telemetry_extension;
+use telemetry_extension::telemetry_processor;
+{%- endif %}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing::init_default_subscriber();
+
+    Extension::new()
+        {%- if events %}
+        .with_events_processor(service_fn(events_processor))
+        {%- endif -%}
+        {%- if logs %}
+        .with_logs_processor(SharedService::new(service_fn(logs_processor)))
+        {%- endif -%}
+        {%- if telemetry %}
+        .with_telemetry_processor(SharedService::new(service_fn(telemetry_processor)))
+        {%- endif %}
+        .run()
+        .await
+}
diff --git a/template/src/telemetry_extension.rs b/template/src/telemetry_extension.rs
@@ -0,0 +1,17 @@
+use lambda_extension::{tracing, LambdaTelemetry, LambdaTelemetryRecord, Error};
+
+/// Process telemetry from the Lambda extension API.
+///
+/// This function is called when the Lambda extension receives telemetry from the Lambda API.
+pub(crate) async fn telemetry_processor(events: Vec<LambdaTelemetry>) -> Result<(), Error> {
+    for event in events {
+        match event.record {
+            LambdaTelemetryRecord::Function(record) => {
+                tracing::info!(telemetry_type = "function", ?record, "received function telemetry");
+            }
+            _ignore_other => {},
+        }
+    }
+
+    Ok(())
+}
