Allow handlers to return user-defined error types

.envrc

@@ -0,0 +1 @@
+use nix;

dropshot/examples/custom-error.rs

@@ -0,0 +1,129 @@
+// 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::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, Deserialize, JsonSchema)]
+enum ThingyError {
+    #[error("no thingies are currently available")]
+    NoThingies,
+    #[error("invalid thingy: {:?}", .name)]
+    InvalidThingy { name: 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")
+            }
+        }
+    }
+}
+
+/// 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, Serialize, JsonSchema)]
+struct NoThingy {}
+
+#[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 })
+}
+
+/// 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 {})
+}
+
+/// An example of an endpoint which returns a `Result<_, HttpError>`.
+///
+/// Note that
+#[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", "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

@@ -15,7 +15,6 @@ 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;
@@ -330,9 +329,16 @@ 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)]
+pub struct ApiEndpointErrorResponse {
+    pub(crate) schema: ApiSchemaGenerator,
+}
+
 /// Wrapper for both dynamically generated and pre-generated schemas.
 pub enum ApiSchemaGenerator {
     Gen {
@@ -919,27 +925,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 error) = endpoint.response.error {
+                let error_schema = match error.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 +988,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;