Allow handlers to return user-defined error types

dropshot/examples/custom-error.rs

@@ -7,6 +7,8 @@ use dropshot::endpoint;
 use dropshot::ApiDescription;
 use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
+use dropshot::ErrorStatusCode;
+use dropshot::HttpError;
 use dropshot::HttpResponseError;
 use dropshot::HttpResponseOk;
 use dropshot::Path;
@@ -16,12 +18,22 @@ use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 
-#[derive(Debug, thiserror::Error, Serialize, Deserialize, JsonSchema)]
+#[derive(Debug, thiserror::Error, Serialize, JsonSchema)]
 enum ThingyError {
+    #[allow(dead_code)]
     #[error("no thingies are currently available")]
     NoThingies,
     #[error("invalid thingy: {:?}", .name)]
     InvalidThingy { name: String },
+    #[error("{message}")]
+    Other {
+        message: String,
+        #[serde(skip)]
+        internal_message: String,
+        #[serde(skip)]
+        status: ErrorStatusCode,
+        error_code: Option<String>,
+    },
 }
 
 /// Any type implementing `dropshot::HttpResponseError` and
@@ -50,6 +62,18 @@ impl HttpResponseError for ThingyError {
                 dropshot::ErrorStatusCode::from_u16(442)
                     .expect("442 is a 4xx status code")
             }
+            ThingyError::Other { status, .. } => *status,
+        }
+    }
+}
+
+impl From<HttpError> for ThingyError {
+    fn from(error: HttpError) -> Self {
+        ThingyError::Other {
+            message: error.external_message,
+            internal_message: error.internal_message,
+            status: error.status_code,
+            error_code: error.error_code,
         }
     }
 }
@@ -60,9 +84,6 @@ struct Thingy {
     magic_number: u64,
 }
 
-#[derive(Deserialize, Serialize, JsonSchema)]
-struct NoThingy {}
-
 #[derive(Deserialize, JsonSchema)]
 struct ThingyPathParams {
     name: String,
@@ -81,13 +102,14 @@ async fn get_thingy(
     Err(ThingyError::InvalidThingy { name })
 }
 
-/// An example of an endpoint which does not return a `Result<_, _>`.
 #[endpoint {
     method = GET,
     path = "/nothing",
 }]
-async fn get_nothing(_rqctx: RequestContext<()>) -> HttpResponseOk<NoThingy> {
-    HttpResponseOk(NoThingy {})
+async fn get_nothing(
+    _rqctx: RequestContext<()>,
+) -> Result<HttpResponseOk<Thingy>, ThingyError> {
+    Err(ThingyError::NoThingies)
 }
 
 /// An example of an endpoint which returns a `Result<_, HttpError>`.

dropshot/src/api_description.rs

@@ -4,6 +4,8 @@
 use crate::extractor::RequestExtractor;
 use crate::handler::HttpHandlerFunc;
 use crate::handler::HttpResponse;
+use crate::handler::HttpResponseContent;
+use crate::handler::HttpResponseError;
 use crate::handler::HttpRouteHandler;
 use crate::handler::RouteHandler;
 use crate::handler::StubRouteHandler;
@@ -51,6 +53,7 @@ pub struct ApiEndpoint<Context: ServerContext> {
     pub parameters: Vec<ApiEndpointParameter>,
     pub body_content_type: ApiEndpointBodyContentType,
     pub response: ApiEndpointResponse,
+    pub error: ApiEndpointErrorResponse,
     pub summary: Option<String>,
     pub description: Option<String>,
     pub tags: Vec<String>,
@@ -79,6 +82,9 @@ impl<'a, Context: ServerContext> ApiEndpoint<Context> {
                 .expect("unsupported mime type");
         let func_parameters = FuncParams::metadata(body_content_type.clone());
         let response = ResponseType::response_metadata();
+        let error = ApiEndpointErrorResponse {
+            schema: <HandlerType::Error>::content_metadata(),
+        };
         ApiEndpoint {
             operation_id,
             handler: HttpRouteHandler::new(handler),
@@ -87,6 +93,7 @@ impl<'a, Context: ServerContext> ApiEndpoint<Context> {
             parameters: func_parameters.parameters,
             body_content_type,
             response,
+            error,
             summary: None,
             description: None,
             tags: vec![],
@@ -162,7 +169,7 @@ impl<'a> ApiEndpoint<StubContext> {
     /// );
     /// api.register(endpoint).unwrap();
     /// ```
-    pub fn new_for_types<FuncParams, ReturnType>(
+    pub fn new_for_types<FuncParams, ResultType>(
         operation_id: String,
         method: Method,
         content_type: &'a str,
@@ -171,13 +178,16 @@ impl<'a> ApiEndpoint<StubContext> {
     ) -> Self
     where
         FuncParams: RequestExtractor + 'static,
-        ReturnType: HttpResponse + Send + Sync + 'static,
+        ResultType: HttpResultType,
     {
         let body_content_type =
             ApiEndpointBodyContentType::from_mime_type(content_type)
                 .expect("unsupported mime type");
         let func_parameters = FuncParams::metadata(body_content_type.clone());
-        let response = ReturnType::response_metadata();
+        let response = <ResultType::Response>::response_metadata();
+        let error = ApiEndpointErrorResponse {
+            schema: <ResultType::Error>::content_metadata(),
+        };
         let handler = StubRouteHandler::new_with_name(&operation_id);
         ApiEndpoint {
             operation_id,
@@ -187,6 +197,7 @@ impl<'a> ApiEndpoint<StubContext> {
             parameters: func_parameters.parameters,
             body_content_type,
             response,
+            error,
             summary: None,
             description: None,
             tags: vec![],
@@ -198,6 +209,20 @@ impl<'a> ApiEndpoint<StubContext> {
     }
 }
 
+pub trait HttpResultType {
+    type Response: HttpResponse + Send + Sync + 'static;
+    type Error: HttpResponseError + Send + Sync + 'static;
+}
+
+impl<T, E> HttpResultType for Result<T, E>
+where
+    T: HttpResponse + Send + Sync + 'static,
+    E: HttpResponseError + Send + Sync + 'static,
+{
+    type Response = T;
+    type Error = E;
+}
+
 /// ApiEndpointParameter represents the discrete path and query parameters for a
 /// given API endpoint. These are typically derived from the members of stucts
 /// used as parameters to handler functions.
@@ -317,14 +342,13 @@ pub struct ApiEndpointResponse {
     pub schema: Option<ApiSchemaGenerator>,
     pub headers: Vec<ApiEndpointHeader>,
     pub success: Option<StatusCode>,
-    pub error: Option<ApiEndpointErrorResponse>,
     pub description: Option<String>,
 }
 
 /// Metadata for an API endpoint's error response type.
-#[derive(Debug)]
+#[derive(Debug, Default)]
 pub struct ApiEndpointErrorResponse {
-    pub(crate) schema: ApiSchemaGenerator,
+    pub(crate) schema: Option<ApiSchemaGenerator>,
 }
 
 /// Wrapper for both dynamically generated and pre-generated schemas.
@@ -915,8 +939,8 @@ impl<Context: ServerContext> ApiDescription<Context> {
 
             // If the endpoint defines an error type, emit that for
             // the 4xx and 5xx responses.
-            if let Some(ref error) = endpoint.response.error {
-                let error_schema = match error.schema {
+            if let Some(ref schema) = endpoint.error.schema {
+                let error_schema = match schema {
                     ApiSchemaGenerator::Gen { ref name, ref schema } => {
                         j2oas_schema(Some(&name()), &schema(&mut generator))
                     }