Allow error response customization

[kikuomax]

Issue #, if available:

• Is there a way to control `errorType` in an error response? #824

Description of changes:

• F::Error of Runtime::run and run is required to implement Into<Diagnostic<'a>> instead of std::fmt::Display
• Into<Diagnostic<'a>> is implemented for any types that implement std::fmt::Display as a fallback and for backward compatibility
• Diagnostic and its fields become public so that users can customize error responses
• error_type and error_message of Diagnostic are wrapped in std::borrow::Cow so that they can hold both borrowed and owned strings. An example of the situation where an owned string is necessary is in the fallback implementation of From<Display> for Diagnostic, which generates error_message inside from method and it has to outlive the method call.

By submitting this pull request

• I confirm that my contribution is made under the terms of the Apache 2.0 license.
• I confirm that I've made a best effort attempt to update all relevant documentation.

[calavera]

This is really nice, thank you!

[evbo]

Why use Cow? Why not just use &str?

[kikuomax]

@evbo I introduced Cow to overcome a lifetime issue rather than performance concern. Since the fallback conversion from Error (Display) into Diagnostic had to dynamically format error_message, I was not able to simply return &str: https://github.com/awslabs/aws-lambda-rust-runtime/blob/e0e95e61cba0a8a695d4766d9215cbe839caf3a7/lambda-runtime/src/types.rs#L67-L77

However, regarding error_type, it could have been &str. I did not notice that until you pointed it out.

[evbo]

error_type can't always be &str in the case where you're borrowing the variant name (such as with strum::AsRefStr), which is helpful for auto-converting Variants to error types.

I'm not sure why both can't just be String? Just seems like a lot of extra typing using Cow, sorry to nitpick

[kikuomax]

I think some might say the opposite "why String? they are &'static str most of the time."

Btw, you may avoid explicit use of Cow as long as you are dealing with &str or String:

let msg = "message".to_string();
Diagnostic {
    error_type: "SomeError".into(), // &str → Cow::Borrowed
    error_message: msg.into(), // String → Cow::Owned
};

[evbo]

Thanks for the into - that's much cleaner. I hate to burn up so much time, but why would someone say: "why String"? If we're creating millions of exceptions, then I understand the cost of heap allocation would eventually cost noticeably, but maybe at most 1 exception gets generated once in a blue moon, so isn't it fair using String?

[kikuomax]

@evbo Have you tried something like the following?

#[derive(thiserror::Error, Debug)]
pub enum MyError {
    #[error("some error: {0}")]
    SomeError(String),
    // ... other variants
}

impl<'a> Into<Diagnostic<'a>> for MyError {
    fn into(self) -> Diagnostic<'a> {
        match self {
            Self::SomeError(s) => Diagnostic {
                error_type: Cow::Borrowed("SomeError"),
                error_message: Cow::Owned(s),
            },
            // ... other variants
        }
    }
}

The above will cause conflict between From<Display> for Diagnostic and Into<Diagnostic> for MyError, because MyError implements derived Display. So you cannot directly implement Diagnostic for MyError; more generally, any type implementing std::error::Error.

A workaround in this case may be to define a wrapper struct for your error type and implement Diagnostic for the wrapper like in the example of Diagnostic:

struct ErrorResponse(MyError);

impl<'a> Into<Diagnostic<'a>> for ErrorResponse {
    fn into(self) -> Diagnostic<'a> {
        match self.0 {
            ErrorResponse::SomeError(s) => Diagnostic {
                error_type: Cow::Borrowed("SomeError"),
                error_message: Cow::Owned(s),
            },
            // ... other variants
        }
    }
}

Display must not be implemented for ErrorResponse to avoid the same conflict.

Obviously, I should refine the documentation.

[evbo]

@kikuomax I take back my earlier messages. I think you're right - this can be solved with better docs.

I think the best ergonomics are achieved when function_handler returns the error and then you map_err to the top-level struct by intercepting what gets returned to lambda_runtime::run as shown here:
https://docs.aws.amazon.com/lambda/latest/dg/rust-handler.html#rust-shared-state

[kikuomax]

@evbo I am planning a PR to improve the documentation. How about having the following in the API documentation? Does it make better sense?

Diagnostic is automatically generated from any types that implement Display; e.g., Error. The default behavior puts the type name of the original error obtained with std::any::type_name into error_type, which may not be reliable for conditional error handling. You can define your own error container that implements Into<Diagnostic> if you need more accurate error types.

Example:

use lambda_runtime::{service_fn, Diagnostic, Error, LambdaEvent};

#[derive(Debug)]
struct ErrorResponse(Error);

impl<'a> Into<Diagnostic<'a>> for ErrorResponse {
    fn into(self) -> Diagnostic<'a> {
        Diagnostic {
            error_type: "MyError".into(),
            error_message: self.0.to_string().into(),
        }
    }
}

async fn function_handler(_event: LambdaEvent<()>) -> Result<(), Error> {
   // ... do something
   Ok(())
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    lambda_runtime::run(service_fn(|event| async {
        function_handler(event).await.map_err(ErrorResponse)
    })).await
}

The container ErrorResponse in the above snippet is necessary because you cannot directly implement Into<Diagnostic> for types that implement Error. For instance, the following code will not compile:

ⓘ compile_fail

use lambda_runtime::Diagnostic;

#[derive(Debug)]
struct MyError(String);

impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "MyError: {}", self.0)
    }
}

impl std::error::Error for MyError {}

// ERROR! conflicting implementations of trait `Into<Diagnostic<'_>>` for type `MyError`
impl<'a> Into<Diagnostic<'a>> for MyError {
    fn into(self) -> Diagnostic<'a> {
        Diagnostic {
            error_type: "MyError".into(),
            error_message: self.0.into(),
        }
    }
}