-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Servant Errors wai-middlware -- -- A Wai middleware that uniformly structures errors with in a servant -- application. The library assumes all HTTP responses with status code -- greater than 200 and without an HTTP content type are error responses. -- This assumption is derived from servant server error handling -- implementation. @package servant-errors @version 0.1.5.0 -- | 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
--   
--
module Network.Wai.Middleware.Servant.Errors -- | 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"]
--
errorMw :: forall ctyp opts. HasErrorBody ctyp opts => Middleware -- | 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 } errorMwDefJson :: Middleware -- | 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. class Accept ctyp => HasErrorBody (ctyp :: Type) (opts :: [Symbol]) -- | 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 encodeError :: HasErrorBody ctyp opts => StatusCode -> ErrorMsg -> ByteString -- | ErrorMsg holds HTTP error response body message newtype ErrorMsg ErrorMsg :: Text -> ErrorMsg [unErrorMsg] :: ErrorMsg -> Text -- | StatusCode holds HTTP error status code newtype StatusCode StatusCode :: Int -> StatusCode [unStatusCode] :: StatusCode -> Int -- | ErrorLabels is a configuration for holding error response -- labels data ErrorLabels ErrorLabels :: Text -> Text -> ErrorLabels [errName] :: ErrorLabels -> Text [errStatusName] :: ErrorLabels -> Text -- | 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. getErrorLabels :: forall errLabel statusLabel. (KnownSymbol errLabel, KnownSymbol statusLabel) => ErrorLabels -- | encodeAsJsonError formats error response into JSON -- encoded string. Its used in the library provided HasErrorBody -- JSON instance encodeAsJsonError :: ErrorLabels -> StatusCode -> ErrorMsg -> ByteString -- | encodeAsPlainText formats error response into PlainText -- string. its used in the library provided HasErrorBody -- PlainText class instance encodeAsPlainText :: ErrorLabels -> StatusCode -> ErrorMsg -> ByteString instance GHC.Show.Show Network.Wai.Middleware.Servant.Errors.ErrorMsg instance GHC.Show.Show Network.Wai.Middleware.Servant.Errors.StatusCode instance GHC.Classes.Ord Network.Wai.Middleware.Servant.Errors.StatusCode instance GHC.Classes.Eq Network.Wai.Middleware.Servant.Errors.StatusCode instance (GHC.TypeLits.KnownSymbol errLabel, GHC.TypeLits.KnownSymbol statusLabel) => Network.Wai.Middleware.Servant.Errors.HasErrorBody Servant.API.ContentTypes.JSON '[errLabel, statusLabel] instance Network.Wai.Middleware.Servant.Errors.HasErrorBody Servant.API.ContentTypes.JSON '[] instance (GHC.TypeLits.KnownSymbol errLabel, GHC.TypeLits.KnownSymbol statusLabel) => Network.Wai.Middleware.Servant.Errors.HasErrorBody Servant.API.ContentTypes.PlainText '[errLabel, statusLabel] instance Network.Wai.Middleware.Servant.Errors.HasErrorBody Servant.API.ContentTypes.PlainText '[]