AWS Greengrass Core Rust SDK

为AWS Greengrass Core C SDK提供一个惯用的Rust包装器，以便更容易地在Rust中启用Greengrass本地lambda函数。

功能

• 发布到MQTT主题
• 在MQTT主题上注册处理程序并接收消息
• 通过log crate将日志记录到Greengrass日志后端
• 获取密钥

示例

• hello.rs - 初始化greengrass运行时并在主题上发送消息的简单示例
• echo.rs - 示例，说明如何将处理程序注册到greengrass运行时并监听消息。
• shadow.rs - 示例，展示如何获取和操作阴影文档。
• longlived.rs - 示例，展示如何创建一个长期运行的greengrass lambda，该lambda暴露一个http端点。
• invoker.rs - 调用一个lambda的示例。应与invokee.rs一起使用

构建示例

可以按照快速入门指南中的说明构建示例。使用cargo build --example <example>来构建。

快速入门

先决条件和要求

• 安装Greengrass C SDK（在Mac OS X上失败，见下文说明）
• 安装Rust
• 安装AWS CLI
• 运行绿色草地版本v1.6或更高版本的设备
• 创建并配置Greengrass组，如在Amazon Greengrass中入门中所述

关于在mac上构建的说明

C Greengrass SDK在Mac OS X上无法构建。stub目录包含一个简单的SDK存根版本，可用于针对Mac OS X进行编译。

要安装

1. cdstubs
2. mkdir build&&cd build
3. cmake..
4. make
5. makeinstall

创建新的cargo项目

cargonew --binmy_gg_lambda

将库添加到Cargo.toml中

此外，定义了日志crate

aws_greengrass_core_rust = "0.1.36"
log = "^0.4"

编辑main.rs

1. 初始化日志、greengrass运行时并注册一个处理器

use aws_greengrass_core_rust::Initializer;
use aws_greengrass_core_rust::log as gglog;
use aws_greengrass_core_rust::handler::{Handler, LambdaContext};
use log::{info, error, LevelFilter};
use aws_greengrass_core_rust::runtime::Runtime;

struct HelloHandler;

impl Handler for HelloHandler {
    fn handle(&self, ctx: LambdaContext) {
        info!("Received context: {:#?}", ctx);
        let msg = String::from_utf8(ctx.message).expect("Message was not a valid utf8 string");
        info!("Received event: {}", msg);
    }
}

pub fn main() {
    gglog::init_log(LevelFilter::Info);
    let runtime = Runtime::default().with_handler(Some(Box::new(HelloHandler)));
    if let Err(e) = Initializer::default().with_runtime(runtime).init() {
        error!("Initialization failed: {}", e);
        std::process::exit(1);
    }
}

构建并打包您的lambda函数

cargo build --release
zip  zip -j my_gg_lambda.zip "./target/release/my_gg_lambda"

注意：二进制文件必须在您部署的操作系统和架构上构建。如果您不在Linux（Mac OS/Windows）上，可以使用docker构建：./dockerbuild.sh cargo build

这仅适用于x86构建。

部署您的lambda函数

使用您创建Greengrass组时使用的相同信息

aws lambda create-function \
    --region aws-region \
    --function-name my_gg_lambda_x86 \
    --handler executable-name \
    --role role-arn \
    --zip-file fileb://file-name.zip \
    --runtime arn:aws:greengrass:::runtime/function/executable

aws lambda publish-version \
    --function-name my_gg_lambda_x86 \
    --region aws-region

aws lambda create-alias \
    --function-name my_gg_lambda_x86 \
    --name alias-name \
    --function-version version-number \
    --region aws-region

注意：如果您计划部署到多个架构，建议将架构后缀（如x86或arm）添加到lambda名称中。

在Greengrass组中配置您的lambda函数

请参阅为AWS IoT Greengrass配置Lambda函数中的说明

进一步阅读

• 在AWS IoT Greengrass Core上运行Lambda函数

在项目中测试

在测试阶段开启“mock”功能时，各种客户端将

1. 允许您覆盖输出
2. 保存方法被调用时的参数

示例

  #[cfg(test)]
    mod test {
        use super::*;

        #[test]
        fn test_publish_str() {
            let topic = "foo";
            let message = "this is my message";

            let mocks = MockHolder::default().with_publish_raw_outputs(vec![Ok(())]);
            let client = IOTDataClient::default().with_mocks(mocks);
            let response = client.publish(topic, message).unwrap();
            println!("response: {:?}", response);

            let PublishRawInput(raw_topic, raw_bytes, raw_read) =
                &client.mocks.publish_raw_inputs.borrow()[0];
            assert_eq!(raw_topic, topic);
        }
    }

从源码构建

构建

1. cargobuild

测试Mock功能

当启用mock功能时，示例将无法正确构建。要运行测试，您必须跳过示例：cargo test --features mock --lib

使用代码覆盖率测试

在build.rs中，我们的bindgen配置与覆盖率工具的运行存在一些问题。由于bindings.rs中包含了一组模拟绑定，大多数测试实际上不需要这个。为了绕过失败，可以启用“coverage”功能。这将避免生成绑定并禁用需要真实绑定的几个位置。

使用grcov进行覆盖率

1. 安装gperftools
2. 安装Rust nightly：rustup install nightly
3. 安装grcov：cargo +nightly install grcov
4. 设置以下环境变量

export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Zno-landing-pads"

5. 带有覆盖率信息的构建

cargo clean
cargo +nightly build --features coverage
cargo +nightly test --features coverage

6. 运行grcov

grcov ./target/debug/ -s . -t html --llvm --branch --ignore-not-existing -o ./target/debug/coverage/

交叉编译

AWS_GREENGRASS_STUBS=yes CMAKE_TOOLCHAIN_FILE=$(pwd)/linux-gnu-x86_64.cmake cargo build --target=x86_64-unknown-linux-gnu

使用Jetbrains CLion进行覆盖率

1. 创建一个名为Test的运行覆盖率
2. 设置命令为：test --features coverage
3. 带覆盖率运行