-- 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.0.3
-- | 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
--
--
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 => 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 }
errorMwDefJson :: Application -> Application
-- | 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
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 '[]