| Package | Hackage |
|---|---|
| servant-exceptions |  |
| servant-exceptions-server |  |
Servant servers typically run their handlers in some form of IO. Either directly in the builtin Handler monad or a custom monad transformer on top it. When APIs fail, one would typically use the MonadError ServantError instance via throwError to create an error response of type ServantErr.
This approach has two problems:
Handler(basically beingExceptT ServantErr IO) is considered an anti-pattern by some, as it suggests to novice users that onlyServantErrwould occur, but inIOany exception can be raised to abort executionServantErrvalues need to be created at the call site ofthrowError, where the requested content type and/or headers are not available
servant-exceptions tries to help with both by making it easy to catch specific error types with an instance of Exception and provide automatic encoding into the requested content-type.
The API combinator Throws e can be used to annotate what error types e might
be thrown by a server, for example:
type API = "api" :> Throws UsersError :> "users" :> Get '[JSON, PlainText] [User]The type UsersError can then be used to describe expected errors and their conversion via type class instances:
data UsersError = UserNotFound
| UserAlreadyExists
| InternalError
deriving (Show)
instance Exception UsersError
instance ToServantErr UsersError where
status UserNotFound = status404
status UserAlreadyExists = status409
status InternalError = status500
instance ToJSON UsersError where
toJSON e = object [ "type" .= show (typeOf e)
, "message" .= message e
]
instance MimeRender PlainText UsersError where
mimeRender ct = mimeRender ct . showSee example for a full, commented example.
- Declarative conversion of errors into error responses using
ToServantErr - Respects
Acceptheaders and constructs responses accordingly usingMimeRender - Add headers to error responses, also via
ToServantErr - Type-driven exception handling in
ServerTstacks - Convert "backend" errors into "api" errors using
mapException
This package lacks at least
servant-clientto rethrow exceptions (usingMonadThrowand/orMonadError?)servant-docssupport for automatic error documentation- Documentation, more examples (explain included
ServantExceptionhelper type)
This package is inspired by servant-checked-exceptions (Throws combinator) and
the generalized error handling in cardano-sl.