Error handling improvements (#907)

* Error handling improvements

Change how we handle error types to be more ergonomic:

- Replace Cow with String: Diagnostics are serialized into JSON as soon as the function returns, which means that their value is copied right away. The performance improvement of using Cow is minimal in this case, but it has some ergonomic implications because we have to handle their lifetimes. By removing the explicit lifetimes, people can return Diagnostic values with static lifetimes which was not possible before.

- Add `IntoDiagnostic` trait. This is a helper trait to facilitate transforming value types into Diagnostic. It gives external crates a better mechanism to transform values into `Diagnostic`.

- Add features to implement `IntoDiagnostic` for anyhow, eyre, and miette error types. This helps people that use those creates to transform their errors into `Diagnostic` without double boxing their errors.

* Recommend to implement `From`.

Signed-off-by: David Calavera <[email protected]>

* Simplify implementation, remove `IntoDiagnostic`

We can implement `From<T> for Diagnostic` for error crates.

* Remove implementation for From<Box<T>>

Signed-off-by: David Calavera <[email protected]>

* Document features in Cargo.toml

Signed-off-by: David Calavera <[email protected]>

---------

Signed-off-by: David Calavera <[email protected]>

README.md

@@ -40,7 +40,7 @@ pip3 install cargo-lambda
 
 See other installation options in [the Cargo Lambda documentation](https://www.cargo-lambda.info/guide/installation.html).
 
-### Your first function
+## Your first function
 
 To create your first function, run Cargo Lambda with the [subcommand `new`](https://www.cargo-lambda.info/commands/new.html). This command will generate a Rust package with the initial source code for your function:
 
@@ -71,6 +71,61 @@ async fn func(event: LambdaEvent<Value>) -> Result<Value, Error> {
 }
 ```
 
+## Understanding Lambda errors
+
+when a function invocation fails, AWS Lambda expects you to return an object that can be serialized into JSON structure with the error information. This structure is represented in the following example:
+
+```json
+{
+  "error_type": "the type of error raised",
+  "error_message": "a string description of the error"
+}
+```
+
+The Rust Runtime for Lambda uses a struct called `Diagnostic` to represent function errors internally. The runtime implements the converstion of several general errors types, like `std::error::Error`, into `Diagnostic`. For these general implementations, the `error_type` is the name of the value type returned by your function. For example, if your function returns `lambda_runtime::Error`, the `error_type` will be something like `alloc::boxed::Box<dyn core::error::Error + core::marker::Send + core::marker::Sync>`, which is not very descriptive.
+
+### Implement your own Diagnostic
+
+To get more descriptive `error_type` fields, you can implement `From` for your error type. That gives you full control on what the `error_type` is:
+
+```rust
+use lambda_runtime::{Diagnostic, Error, LambdaEvent};
+
+#[derive(Debug)]
+struct ErrorResponse(&'static str);
+
+impl From<ErrorResponse> for Diagnostic {
+    fn from(error: ErrorResponse) -> Diagnostic {
+        Diagnostic {
+            error_type: "MyErrorType".into(),
+            error_message: error.0.to_string(),
+        }
+    }
+}
+
+async fn handler(_event: LambdaEvent<()>) -> Result<(), ErrorResponse> {
+  Err(ErrorResponse("this is an error response"))
+}
+```
+
+We recommend you to use the [thiserror crate](https://crates.io/crates/thiserror) to declare your errors. You can see an example on how to integrate `thiserror` with the Runtime's diagnostics in our [example repository](https://github.com/awslabs/aws-lambda-rust-runtime/tree/main/examples/basic-error-thiserror)
+
+### Anyhow, Eyre, and Miette
+
+Popular error crates like Anyhow, Eyre, and Miette provide their own error types that encapsulate other errors. There is no direct transformation of those errors into `Diagnostic`, but we provide feature flags for each one of those crates to help you integrate them with your Lambda functions.
+
+If you enable the features `anyhow`, `eyre`, or `miette` in the `lambda_runtime` dependency of your package. The error types provided by those crates can have blanket transformations into `Diagnostic`. These features expose an `From<T> for Diagnostic` implementation that transforms those error types into a `Diagnostic`. This is an example that transforms an `anyhow::Error` into a `Diagnostic`:
+
+```rust
+use lambda_runtime::{Diagnostic, LambdaEvent};
+
+async fn handler(_event: LambdaEvent<Request>) -> Result<(), Diagnostic> {
+  Err(anyhow::anyhow!("this is an error").into())
+}
+```
+
+You can see more examples on how to use these error crates in our [example repository](https://github.com/awslabs/aws-lambda-rust-runtime/tree/main/examples/basic-error-error-crates-integration). 
+
 ## Building and deploying your Lambda functions
 
 If you already have Cargo Lambda installed in your machine, run the next command to build your function:

examples/basic-error-error-crates-integration/Cargo.toml

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

examples/basic-error-anyhow/README.md → examples/basic-error-error-crates-integration/README.md

@@ -1,6 +1,8 @@
-# AWS Lambda Function Error Handling With `anyhow` Crate Example
+# AWS Lambda Function Error Handling with several popular error crates.
 
-This example shows how to use external error types like `anyhow::Error`.
+This example shows how to use external error types like `anyhow::Error`, `eyre::Report`, and `miette::Report`.
+
+To use the integrations with these crates, you need to enable to respective feature flag in the runtime which provides the implemetation of `into_diagnostic` for specific error types provided by these crates.
 
 ## Build & Deploy
 

examples/basic-error-error-crates-integration/src/main.rs

@@ -0,0 +1,44 @@
+use lambda_runtime::{run, service_fn, Diagnostic, Error, LambdaEvent};
+use serde::Deserialize;
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum ErrorType {
+    Anyhow,
+    Eyre,
+    Miette,
+}
+
+#[derive(Deserialize)]
+struct Request {
+    error_type: ErrorType,
+}
+
+fn anyhow_error() -> anyhow::Result<()> {
+    anyhow::bail!("This is an error message from Anyhow");
+}
+
+fn eyre_error() -> eyre::Result<()> {
+    eyre::bail!("This is an error message from Eyre");
+}
+
+fn miette_error() -> miette::Result<()> {
+    miette::bail!("This is an error message from Miette");
+}
+
+/// Transform an anyhow::Error, eyre::Report, or miette::Report into a lambda_runtime::Diagnostic.
+/// It does it by enabling the feature `anyhow`, `eyre` or `miette` in the runtime dependency.
+/// Those features enable the implementation of `From<T> for Diagnostic` 
+/// for `anyhow::Error`, `eyre::Report`, and `miette::Report`.
+async fn function_handler(event: LambdaEvent<Request>) -> Result<(), Diagnostic> {
+    match event.payload.error_type {
+        ErrorType::Anyhow => anyhow_error().map_err(|e| e.into()),
+        ErrorType::Eyre => eyre_error().map_err(|e| e.into()),
+        ErrorType::Miette => miette_error().map_err(|e| e.into()),
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    run(service_fn(function_handler)).await
+}

examples/basic-error-diagnostic/Cargo.toml → examples/basic-error-thiserror/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "basic-error-diagnostic"
+name = "basic-error-thiserror"
 version = "0.1.0"
 edition = "2021"
 

examples/basic-error-diagnostic/src/main.rs → examples/basic-error-thiserror/src/main.rs

@@ -13,8 +13,8 @@ pub enum ExecutionError {
     Unexpected(String),
 }
 
-impl<'a> From<ExecutionError> for Diagnostic<'a> {
-    fn from(value: ExecutionError) -> Diagnostic<'a> {
+impl From<ExecutionError> for Diagnostic {
+    fn from(value: ExecutionError) -> Diagnostic {
         let (error_type, error_message) = match value {
             ExecutionError::DatabaseError(err) => ("Retryable", err.to_string()),
             ExecutionError::Unexpected(err) => ("NonRetryable", err.to_string()),

lambda-http/Cargo.toml

@@ -22,7 +22,11 @@ apigw_http = []
 apigw_websockets = []
 alb = []
 pass_through = []
-tracing = ["lambda_runtime/tracing"]
+tracing = ["lambda_runtime/tracing"] # enables access to the Tracing utilities
+opentelemetry = ["lambda_runtime/opentelemetry"] # enables access to the OpenTelemetry layers and utilities
+anyhow = ["lambda_runtime/anyhow"] # enables From<T> for Diagnostic for anyhow error types, see README.md for more info
+eyre = ["lambda_runtime/eyre"] # enables From<T> for Diagnostic for eyre error types, see README.md for more info
+miette = ["lambda_runtime/miette"] # enables From<T> for Diagnostic for miette error types, see README.md for more info
 
 [dependencies]
 base64 = { workspace = true }

lambda-http/src/lib.rs

@@ -194,7 +194,7 @@ where
     S: Service<Request, Response = R, Error = E>,
     S::Future: Send + 'a,
     R: IntoResponse,
-    E: std::fmt::Debug + for<'b> Into<Diagnostic<'b>>,
+    E: std::fmt::Debug + Into<Diagnostic>,
 {
     lambda_runtime::run(Adapter::from(handler)).await
 }

lambda-http/src/streaming.rs

@@ -20,7 +20,7 @@ pub async fn run_with_streaming_response<'a, S, B, E>(handler: S) -> Result<(),
 where
     S: Service<Request, Response = Response<B>, Error = E>,
     S::Future: Send + 'a,
-    E: Debug + for<'b> Into<Diagnostic<'b>>,
+    E: Debug + Into<Diagnostic>,
     B: Body + Unpin + Send + 'static,
     B::Data: Into<Bytes> + Send,
     B::Error: Into<Error> + Send + Debug,

lambda-runtime/Cargo.toml

@@ -15,13 +15,18 @@ readme = "../README.md"
 
 [features]
 default = ["tracing"]
-tracing = ["lambda_runtime_api_client/tracing"]
-opentelemetry = ["opentelemetry-semantic-conventions"]
+tracing = ["lambda_runtime_api_client/tracing"] # enables access to the Tracing utilities
+opentelemetry = ["opentelemetry-semantic-conventions"] # enables access to the OpenTelemetry layers and utilities
+anyhow = ["dep:anyhow"] # enables From<T> for Diagnostic for anyhow error types, see README.md for more info
+eyre = ["dep:eyre"] # enables From<T> for Diagnostic for eyre error types, see README.md for more info
+miette = ["dep:miette"] # enables From<T> for Diagnostic for miette error types, see README.md for more info
 
 [dependencies]
+anyhow = { version = "1.0.86", optional = true }
 async-stream = "0.3"
 base64 = { workspace = true }
 bytes = { workspace = true }
+eyre = { version = "0.6.12", optional = true }
 futures = { workspace = true }
 http = { workspace = true }
 http-body = { workspace = true }
@@ -35,6 +40,7 @@ hyper-util = { workspace = true, features = [
     "tokio",
 ] }
 lambda_runtime_api_client = { version = "0.11.1", path = "../lambda-runtime-api-client", default-features = false }
+miette = { version = "7.2.0", optional = true }
 opentelemetry-semantic-conventions = { version = "0.14", optional = true }
 pin-project = "1"
 serde = { version = "1", features = ["derive", "rc"] }