servant-errors-0.1.4.0: Servant Errors wai-middlware

Safe HaskellNone
LanguageHaskell2010

Network.Wai.Middleware.Servant.Errors

Contents

Description

A Wai middleware that uniformly structures errors within a servant application. The library assumes all HTTP responses with status codes between 4xx and 5xx while 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
 
Synopsis

Error Middleware

errorMw :: forall ctyp opts. HasErrorBody ctyp opts => Middleware Source #

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 :: Middleware Source #

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 Source #

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 Source #

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]) Source # 
Instance details

Defined in Network.Wai.Middleware.Servant.Errors

HasErrorBody PlainText ([] :: [Symbol]) Source # 
Instance details

Defined in Network.Wai.Middleware.Servant.Errors

(KnownSymbol errLabel, KnownSymbol statusLabel) => HasErrorBody JSON (errLabel ': (statusLabel ': ([] :: [Symbol]))) Source # 
Instance details

Defined in Network.Wai.Middleware.Servant.Errors

(KnownSymbol errLabel, KnownSymbol statusLabel) => HasErrorBody PlainText (errLabel ': (statusLabel ': ([] :: [Symbol]))) Source # 
Instance details

Defined in Network.Wai.Middleware.Servant.Errors

Helper functions and data types

newtype ErrorMsg Source #

ErrorMsg holds HTTP error response body message

Constructors

ErrorMsg 

Fields

Instances
Show ErrorMsg Source # 
Instance details

Defined in Network.Wai.Middleware.Servant.Errors

data ErrorLabels Source #

ErrorLabels is a configuration for holding error response labels

Constructors

ErrorLabels 

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

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.

encodeAsJsonError :: ErrorLabels -> StatusCode -> ErrorMsg -> ByteString Source #

encodeAsJsonError formats error response into JSON encoded string. Its used in the library provided HasErrorBody JSON instance

encodeAsPlainText :: ErrorLabels -> StatusCode -> ErrorMsg -> ByteString Source #

encodeAsPlainText formats error response into PlainText string. its used in the library provided HasErrorBody PlainText class instance