RuntimeError in ServerError should return different HTTP response codes based on the error

[lovetodream]

Motivation

Currently, every ServerError throws a 500 status code (at least when using hummingbird-transport).
This might be very subjective, but a response with a 500 status code indicates a problem on the server which requires immediate attention and ultimately a fix. The name indicates that some internals failed, which often isn't the case with ServerErrors.

E.g. decoding or invalid content type errors should rather be handled as bad requests, as the responsibility to provide a valid request lays on the client side, this is nothing the server can fix.

Proposed solution

Consider adding a status code property to ServerError (maybe an Optional desiredStatusCode). This can be used by server runtime authors/users to provide better status codes to their consumers and improve error monitoring.

Alternatives considered

Adding a middleware to set the status code based on ServerError.underlyingError. This works for many cases, but doesn't work for RuntimeError, as it is internal, and cannot be bundled in one status code.

let statusCode: HTTPResponse.Status = switch self.underlyingError {
    case is DecodingError:
        .badRequest
    ...
    default:
        .internalServerError
    }

Additional information

I am just starting to use OpenAPI, maybe I'm missing something here :)

[czechboy0]

Hi @lovetodream, thanks for the feature request - yes we're having some discussions about improving this use case. Let us post here when we have more to share.

[czechboy0]

Hi @lovetodream, the fix is likely to come with #644

[czechboy0]

The good news is that #626 gives us a natural spelling for expressing the different codes. We'll conform the internal RuntimeError to this protocol, once SOAR-0011 is ready to use, and adopters will be able to opt into the changed response status codes (we can't really change that for everyone, as it'd be considered a breaking change). For details, see https://forums.swift.org/t/proposal-soar-0011-improved-error-handling/74736

[czechboy0]

Closed #644 as a duplicate of this issue, copying over the description from there below:

Motivation

At the moment, when the generated parsing code fails on the server, an error is thrown, which by default gets turned into the HTTP response status 500.

However, if e.g. a required query item was missing, that should return 400, conventionally.

Unfortunately, server adopters don't have a good way to even handle it in a middleware, as RuntimeError is internal.

Proposed solution

Details to be discussed, but we should offer some signal whether the underlying RuntimeError is "caused by input" (e.g. bad request) or "caused by server" (e.g. handler throws an error).

Probably should also offer an "audited error string" that we guarantee is safe to send back to the caller, for example "missing required query item 'foo'". As getting a 400 without details can be infuriating.

Some questions:

• is this a backwards compatible change?
• should this be done by conforming ServerError to the new protocol, and users opt in by adding the middleware? ([Proposal] SOAR-0011: Improved error handling #626)

[czechboy0]

Ok now that SOAR-0011 has been implemented and landed in a release of Swift OpenAPI Runtime, this enhancement can now be implemented.

Is anyone interested in contributing a fix here? I suspect it won't be too much work (marked as size S).