Network.Wai.Middleware.Servant.Errors

A Wai middleware that uniformly structures errors within a servant application. The library assumes all HTTP responses with status codes greater than 200 and lacking an HTTP content-type are error responses. This assumption is derived from servant server error handling implementation.

The formatting and structuring of errors rest on the implementation of HasErrorBody class instances. It's class parameters are a content-type eg JSON or PlainText and a type-level list of options e.g '["error", "status"]. The library offers instances for JSON and PlainText content-types.

Sample usage with servant

A typical servant application is usually of this form:

 main :: IO ()
 main = run 8001 (serve proxyApi handlers)
 

With servant-errors as an error processing middleware:

 main :: IO ()
 main = run 8001
    $ errorMw @JSON @'["error", "status"]
    -- ^ Structures error response as JSON objects
    -- with error and status strings as error object field keys
    -- note they can be changed to any other preferred strings.
    $ serve proxyApi handlers
 

Error Middleware

errorMw :: forall ctyp opts. HasErrorBody ctyp opts => Application -> Application

errorMw functions provides Network.Wai middleware for formatting error responses within a servant application. Note that this function expects you to have TypeApplications extension enabled

errorMw @JSON @'[ "error", "status"]

errorMwDefJson :: Application -> Application

errorMwDefJson is a convenience pre-configured function for middleware that encodes error responses as JSON objects using error and status for a JSON object key fields

A resulting response may look like this: { error: "failed to decode request body", status: 400 }

HasErrorBody class

class Accept ctyp => HasErrorBody (ctyp :: Type) (opts :: [Symbol]) where

The HasErrorBody class is used for structuring servant error responses.

ctyp is an HTTP content-type with an Accept class instance. eg JSON

opts is a type level list for customising error and status labels.

For example: '["error-message", "status-code"]

When opts is left as an Empty type level list, it default's to a type list of these values: '["error", "status"] for the library provided JSON and PlainText instances.

Methods

encodeError :: StatusCode -> ErrorMsg -> ByteString

encodeError formats error response. The opts type level list in the class definition is used by the getErrorLabels function to obtain error labels which are subsequently used in implementing encodeError for class instances

Instances

HasErrorBody JSON ([] :: [Symbol])

Defined in Network.Wai.Middleware.Servant.Errors

Methods

encodeError :: StatusCode -> ErrorMsg -> ByteString

HasErrorBody PlainText ([] :: [Symbol])

Defined in Network.Wai.Middleware.Servant.Errors

Methods

encodeError :: StatusCode -> ErrorMsg -> ByteString

(KnownSymbol errLabel, KnownSymbol statusLabel) => HasErrorBody JSON (errLabel ': (statusLabel ': ([] :: [Symbol])))

Defined in Network.Wai.Middleware.Servant.Errors

Methods

encodeError :: StatusCode -> ErrorMsg -> ByteString

(KnownSymbol errLabel, KnownSymbol statusLabel) => HasErrorBody PlainText (errLabel ': (statusLabel ': ([] :: [Symbol])))

Defined in Network.Wai.Middleware.Servant.Errors

Methods

encodeError :: StatusCode -> ErrorMsg -> ByteString

Helper functions and data types

newtype ErrorMsg

ErrorMsg holds HTTP error response body message

Constructors

ErrorMsg

Fields

• unErrorMsg :: Text

Instances

Show ErrorMsg

Defined in Network.Wai.Middleware.Servant.Errors

Methods

showsPrec :: Int -> ErrorMsg -> ShowS

show :: ErrorMsg -> String

showList :: [ErrorMsg] -> ShowS

newtype StatusCode

StatusCode holds HTTP error status code

Constructors

StatusCode

Fields

• unStatusCode :: Int

Instances

Eq StatusCode

Defined in Network.Wai.Middleware.Servant.Errors

Methods

(==) :: StatusCode -> StatusCode -> Bool

(/=) :: StatusCode -> StatusCode -> Bool

Ord StatusCode

Defined in Network.Wai.Middleware.Servant.Errors

Methods

compare :: StatusCode -> StatusCode -> Ordering

(<) :: StatusCode -> StatusCode -> Bool

(<=) :: StatusCode -> StatusCode -> Bool

(>) :: StatusCode -> StatusCode -> Bool

(>=) :: StatusCode -> StatusCode -> Bool

max :: StatusCode -> StatusCode -> StatusCode

min :: StatusCode -> StatusCode -> StatusCode

Show StatusCode

Defined in Network.Wai.Middleware.Servant.Errors

Methods

showsPrec :: Int -> StatusCode -> ShowS

show :: StatusCode -> String

showList :: [StatusCode] -> ShowS

data ErrorLabels

ErrorLabels is a configuration for holding error response labels

Constructors

ErrorLabels

Fields

• errName :: Text
• errStatusName :: Text

getErrorLabels :: forall errLabel statusLabel. (KnownSymbol errLabel, KnownSymbol statusLabel) => ErrorLabels

getErrorLabels is used to tranform type level list options provided via the HasErrorBody class into an ErrorLabels data type.

ErrorLabels is used with the error formatting and encoding functions used in HasErrorBody class.