doc: Add an example for using the anyhow crate (#904)

* Add "error handling with anyhow" example

Signed-off-by: Taiki Ono <[email protected]>

* More doc for users who use external error types

Signed-off-by: Taiki Ono <[email protected]>

---------

Signed-off-by: Taiki Ono <[email protected]>

Author: taiki45

examples/basic-error-anyhow/.gitignore

@@ -0,0 +1 @@
+/target

examples/basic-error-anyhow/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "basic-error-anyhow"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow = "1"
+lambda_runtime = { path = "../../lambda-runtime" }
+serde = "1"
+tokio = { version = "1", features = ["macros"] }

examples/basic-error-anyhow/README.md

@@ -0,0 +1,13 @@
+# AWS Lambda Function Error Handling With `anyhow` Crate Example
+
+This example shows how to use external error types like `anyhow::Error`.
+
+## Build & Deploy
+
+1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
+2. Build the function with `cargo lambda build --release`
+3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
+
+## Build for ARM 64
+
+Build the function with `cargo lambda build --release --arm64`

examples/basic-error-anyhow/src/main.rs

@@ -0,0 +1,21 @@
+use anyhow::bail;
+use lambda_runtime::{service_fn, Error, LambdaEvent};
+use serde::Deserialize;
+
+#[derive(Deserialize)]
+struct Request {}
+
+/// Return anyhow::Result in the main body for the Lambda function.
+async fn function_handler(_event: LambdaEvent<Request>) -> anyhow::Result<()> {
+    bail!("This is an error message");
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    lambda_runtime::run(service_fn(|event: LambdaEvent<Request>| async move {
+        function_handler(event)
+            .await
+            .map_err(Into::<Box<dyn std::error::Error>>::into)
+    }))
+    .await
+}

lambda-runtime/src/diagnostic.rs

@@ -7,6 +7,9 @@ use crate::{deserializer::DeserializeError, Error};
 ///
 /// `Diagnostic` is automatically derived for some common types,
 /// like boxed types that implement [`Error`][std::error::Error].
+/// If you use an error type which comes from a external crate like anyhow,
+/// you need convert it to common types like `Box<dyn std::error::Error>`.
+/// See the examples for more details.
 ///
 /// [`error_type`][`Diagnostic::error_type`] is derived from the type name of
 /// the original error with [`std::any::type_name`] as a fallback, which may