Allow handlers to return user-defined error types

dropshot/examples/custom-error.rs

@@ -0,0 +1,149 @@
+// Copyright 2024 Oxide Computer Company
+
+//! An example demonstrating how to return user-defined error types from
+//! endpoint handlers.
+
+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;
+use dropshot::RequestContext;
+use dropshot::ServerBuilder;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+#[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
+/// `HttpResponseContent` may be used as an error type for a
+/// return value from an endpoint handler.
+impl HttpResponseError for ThingyError {
+    // Note that this method returns a `dropshot::ErrorStatusCode`, rather than
+    // an `http::StatusCode`. This type is a refinement of `http::StatusCode`
+    // that can only be constructed from status codes in 4xx (client error) or
+    // 5xx (server error) ranges.
+    fn status_code(&self) -> dropshot::ErrorStatusCode {
+        match self {
+            ThingyError::NoThingies => {
+                // The `dropshot::ErrorStatusCode` type provides constants for
+                // all well-known 4xx and 5xx status codes, such as 503 Service
+                // Unavailable.
+                dropshot::ErrorStatusCode::SERVICE_UNAVAILABLE
+            }
+            ThingyError::InvalidThingy { .. } => {
+                // Alternatively, an `ErrorStatusCode` can be constructed from a
+                // u16, but the `ErrorStatusCode::from_u16` constructor
+                // validates that the status code is a 4xx or 5xx.
+                //
+                // This allows using extended status codes, while still
+                // validating that they are errors.
+                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,
+        }
+    }
+}
+
+/// Just some kind of thingy returned by the API. This doesn't actually matter.
+#[derive(Deserialize, Serialize, JsonSchema)]
+struct Thingy {
+    magic_number: u64,
+}
+
+#[derive(Deserialize, JsonSchema)]
+struct ThingyPathParams {
+    name: String,
+}
+
+/// Fetch the thingy with the provided name.
+#[endpoint {
+    method = GET,
+    path = "/thingy/{name}",
+}]
+async fn get_thingy(
+    _rqctx: RequestContext<()>,
+    path_params: Path<ThingyPathParams>,
+) -> Result<HttpResponseOk<Thingy>, ThingyError> {
+    let ThingyPathParams { name } = path_params.into_inner();
+    Err(ThingyError::InvalidThingy { name })
+}
+
+#[endpoint {
+    method = GET,
+    path = "/nothing",
+}]
+async fn get_nothing(
+    _rqctx: RequestContext<()>,
+) -> Result<HttpResponseOk<Thingy>, ThingyError> {
+    Err(ThingyError::NoThingies)
+}
+
+/// An example of an endpoint which returns a `Result<_, HttpError>`.
+#[endpoint {
+    method = GET,
+    path = "/something",
+}]
+async fn get_something(
+    _rqctx: RequestContext<()>,
+) -> Result<HttpResponseOk<Thingy>, dropshot::HttpError> {
+    Ok(HttpResponseOk(Thingy { magic_number: 42 }))
+}
+
+#[tokio::main]
+async fn main() -> Result<(), String> {
+    // See dropshot/examples/basic.rs for more details on most of these pieces.
+    let config_logging =
+        ConfigLogging::StderrTerminal { level: ConfigLoggingLevel::Info };
+    let log = config_logging
+        .to_logger("example-custom-error")
+        .map_err(|error| format!("failed to create logger: {}", error))?;
+
+    let mut api = ApiDescription::new();
+    api.register(get_thingy).unwrap();
+    api.register(get_nothing).unwrap();
+    api.register(get_something).unwrap();
+
+    api.openapi("Custom Error Example", semver::Version::new(0, 0, 0))
+        .write(&mut std::io::stdout())
+        .map_err(|e| e.to_string())?;
+
+    let server = ServerBuilder::new(api, (), log)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
+
+    server.await
+}

dropshot/src/api_description.rs

@@ -1,9 +1,11 @@
-// Copyright 2023 Oxide Computer Company
+// Copyright 2024 Oxide Computer Company
 //! Describes the endpoints and handler functions in your API
 
 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;
@@ -14,8 +16,6 @@ use crate::schema_util::j2oas_schema;
 use crate::server::ServerContext;
 use crate::type_util::type_is_scalar;
 use crate::type_util::type_is_string_enum;
-use crate::HttpError;
-use crate::HttpErrorResponseBody;
 use crate::CONTENT_TYPE_JSON;
 use crate::CONTENT_TYPE_MULTIPART_FORM_DATA;
 use crate::CONTENT_TYPE_OCTET_STREAM;
@@ -53,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>,
@@ -81,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),
@@ -89,6 +93,7 @@ impl<'a, Context: ServerContext> ApiEndpoint<Context> {
             parameters: func_parameters.parameters,
             body_content_type,
             response,
+            error,
             summary: None,
             description: None,
             tags: vec![],
@@ -179,7 +184,10 @@ impl<'a> ApiEndpoint<StubContext> {
             ApiEndpointBodyContentType::from_mime_type(content_type)
                 .expect("unsupported mime type");
         let func_parameters = FuncParams::metadata(body_content_type.clone());
-        let response = ResultType::Response::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,
@@ -189,6 +197,7 @@ impl<'a> ApiEndpoint<StubContext> {
             parameters: func_parameters.parameters,
             body_content_type,
             response,
+            error,
             summary: None,
             description: None,
             tags: vec![],
@@ -202,13 +211,16 @@ impl<'a> ApiEndpoint<StubContext> {
 
 pub trait HttpResultType {
     type Response: HttpResponse + Send + Sync + 'static;
+    type Error: HttpResponseError + Send + Sync + 'static;
 }
 
-impl<T> HttpResultType for Result<T, HttpError>
+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
@@ -333,6 +345,12 @@ pub struct ApiEndpointResponse {
     pub description: Option<String>,
 }
 
+/// Metadata for an API endpoint's error response type.
+#[derive(Debug, Default)]
+pub struct ApiEndpointErrorResponse {
+    pub(crate) schema: Option<ApiSchemaGenerator>,
+}
+
 /// Wrapper for both dynamically generated and pre-generated schemas.
 pub enum ApiSchemaGenerator {
     Gen {
@@ -919,27 +937,59 @@ impl<Context: ServerContext> ApiDescription<Context> {
                 }
             };
 
+            // If the endpoint defines an error type, emit that for
+            // the 4xx and 5xx responses.
+            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))
+                    }
+                    ApiSchemaGenerator::Static {
+                        ref schema,
+                        ref dependencies,
+                    } => {
+                        definitions.extend(dependencies.clone());
+                        j2oas_schema(None, &schema)
+                    }
+                };
+                let mut content = indexmap::IndexMap::new();
+                content.insert(
+                    CONTENT_TYPE_JSON.to_string(),
+                    openapiv3::MediaType {
+                        schema: Some(error_schema),
+                        ..Default::default()
+                    },
+                );
+                operation.responses.responses.insert(
+                    openapiv3::StatusCode::Range(4),
+                    openapiv3::ReferenceOr::Item(openapiv3::Response {
+                        description: "client error".to_string(),
+                        content: content.clone(),
+                        ..Default::default()
+                    }),
+                );
+                operation.responses.responses.insert(
+                    openapiv3::StatusCode::Range(5),
+                    openapiv3::ReferenceOr::Item(openapiv3::Response {
+                        description: "server error".to_string(),
+                        content: content.clone(),
+                        ..Default::default()
+                    }),
+                );
+            }
+
             if let Some(code) = &endpoint.response.success {
+                // `Ok` response has a known status code. In this case,
+                // emit it as the response for that status code only.
                 operation.responses.responses.insert(
                     openapiv3::StatusCode::Code(code.as_u16()),
                     openapiv3::ReferenceOr::Item(response),
                 );
-
-                // 4xx and 5xx responses all use the same error information
-                let err_ref = openapiv3::ReferenceOr::ref_(
-                    "#/components/responses/Error",
-                );
-                operation
-                    .responses
-                    .responses
-                    .insert(openapiv3::StatusCode::Range(4), err_ref.clone());
-                operation
-                    .responses
-                    .responses
-                    .insert(openapiv3::StatusCode::Range(5), err_ref);
             } else {
+                // The `Ok` response could be any status code, so emit it as
+                // the default response.
                 operation.responses.default =
-                    Some(openapiv3::ReferenceOr::Item(response))
+                    Some(openapiv3::ReferenceOr::Item(response));
             }
 
             // Drop in the operation.
@@ -950,29 +1000,6 @@ impl<Context: ServerContext> ApiDescription<Context> {
             .components
             .get_or_insert_with(openapiv3::Components::default);
 
-        // All endpoints share an error response
-        let responses = &mut components.responses;
-        let mut content = indexmap::IndexMap::new();
-        content.insert(
-            CONTENT_TYPE_JSON.to_string(),
-            openapiv3::MediaType {
-                schema: Some(j2oas_schema(
-                    None,
-                    &generator.subschema_for::<HttpErrorResponseBody>(),
-                )),
-                ..Default::default()
-            },
-        );
-
-        responses.insert(
-            "Error".to_string(),
-            openapiv3::ReferenceOr::Item(openapiv3::Response {
-                description: "Error".to_string(),
-                content,
-                ..Default::default()
-            }),
-        );
-
         // Add the schemas for which we generated references.
         let schemas = &mut components.schemas;