servant-exceptions: Extensible exceptions for servant APIs

[ bsd3, library, web ] [ Propose Tags ] [ Report a vulnerability ]

`servant-exceptions` provides a Throw combinator to declare what types of errors an API might throw. The server implementation catches them and allows for a canonical encoding using servant content-type machinery.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0, 0.1.1, 0.2.0, 0.2.1
Change log CHANGELOG.md
Dependencies aeson, base (>=4.7 && <5), exceptions, http-types, servant, text [details]
License BSD-3-Clause
Copyright 2017-2020 Sebastian Nagel
Author Sebastian Nagel
Maintainer sebastian.nagel@ncoding.at
Category Web
Home page https://github.com/ch1bo/servant-exceptions#readme
Source repo head: git clone https://github.com/ch1bo/servant-exceptions
Uploaded by ch1bo at 2020-11-25T12:37:04Z
Distributions LTSHaskell:0.2.1, NixOS:0.2.1, Stackage:0.2.1
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 2307 total (14 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2020-11-25 [all 1 reports]

Readme for servant-exceptions-0.2.1

[back to package description]

servant-exceptions Build Status

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 being ExceptT ServantErr IO) is considered an anti-pattern by some, as it suggests to novice users that only ServantErr would occur, but in IO any exception can be raised to abort execution
  • ServantErr values need to be created at the call site of throwError, 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 . show

See example for a full, commented example.

Packages

Features

  • Declarative conversion of errors into error responses using ToServantErr
  • Respects Accept headers and constructs responses accordingly using MimeRender
  • Add headers to error responses, also via ToServantErr
  • Type-driven exception handling in ServerT stacks
  • Convert "backend" errors into "api" errors using mapException

Planned things

This package lacks at least

  • servant-client to rethrow exceptions (using MonadThrow and/or MonadError?)
  • servant-docs support for automatic error documentation
  • Documentation, more examples (explain included ServantException helper type)

Credit

This package is inspired by servant-checked-exceptions (Throws combinator) and the generalized error handling in cardano-sl.