Servant.Checked.Exceptions.Internal.Servant.API

This module defines the Throws and Throwing types.

Documentation

data Throws e

Throws is used in Servant API definitions and signifies that an API will throw the given error.

Here is an example of how to create an API that potentially returns a String as an error, or an Int on success:

>>> import Servant.API (Get, JSON, (:>))
>>> type API = Throws String :> Get '[JSON] Int

Instances

type Client * ((:>) k * (Throws e) api)

type Client * ((:>) k * (Throws e) api) = Client * ((:>) k * (Throwing ((:) * e ([] *))) api)

type ServerT * ((:>) k * (Throws e) api) m

type ServerT * ((:>) k * (Throws e) api) m = ServerT * ((:>) k * (Throwing ((:) * e ([] *))) api) m

data NoThrow

NoThrow is used to indicate that an API will not throw an error, but that it will still return a response wrapped in a Envelope.

Examples

Create an API using NoThrow:

>>> import Servant.API (Get, JSON, (:>))
>>> type API = NoThrow :> Get '[JSON] Int

A servant-server handler for this type would look like the following:

  apiHandler :: Handler (Envelope '[] Int)
  apiHandler = pureSuccEnvelope 3

Instances

type Client * ((:>) * * NoThrow ((:<|>) api1 api2))

type Client * ((:>) * * NoThrow ((:<|>) api1 api2)) = Client * ((:<|>) ((:>) * * NoThrow api1) ((:>) * * NoThrow api2))

type Client * ((:>) * * NoThrow ((:>) k k1 api apis))

type Client * ((:>) * * NoThrow ((:>) k k1 api apis)) = Client * ((:>) * k1 api ((:>) k * NoThrow apis))

type Client * ((:>) * * NoThrow (Verb * k1 method status ctypes a))

type Client * ((:>) * * NoThrow (Verb * k1 method status ctypes a)) = Client * (Verb * k1 method status ctypes (Envelope ([] *) a))

type ServerT * ((:>) * * NoThrow ((:<|>) api1 api2)) m

type ServerT * ((:>) * * NoThrow ((:<|>) api1 api2)) m = ServerT * ((:<|>) ((:>) * * NoThrow api1) ((:>) * * NoThrow api2)) m

type ServerT * ((:>) * * NoThrow ((:>) k k1 api apis)) m

type ServerT * ((:>) * * NoThrow ((:>) k k1 api apis)) m = ServerT * ((:>) * k1 api ((:>) k * NoThrow apis)) m

type ServerT * ((:>) * * NoThrow (Verb * k1 method status ctypes a)) m

type ServerT * ((:>) * * NoThrow (Verb * k1 method status ctypes a)) m = ServerT * (Verb * k1 method status ctypes (Envelope ([] *) a)) m

data Throwing e

This is used internally and should not be used by end-users.

Instances

type Client * ((:>) * * (Throwing es) ((:>) k k1 api apis))

type Client * ((:>) * * (Throwing es) ((:>) k k1 api apis)) = Client * (ThrowingNonterminal ((:>) * * (Throwing es) ((:>) k k1 api apis)))

type Client * ((:>) * * (Throwing es) ((:<|>) api1 api2))

type Client * ((:>) * * (Throwing es) ((:<|>) api1 api2)) = Client * ((:<|>) ((:>) * * (Throwing es) api1) ((:>) * * (Throwing es) api2))

type Client * ((:>) * * (Throwing es) (Verb * k1 method status ctypes a))

type Client * ((:>) * * (Throwing es) (Verb * k1 method status ctypes a)) = Client * (Verb * k1 method status ctypes (Envelope es a))

type ServerT * ((:>) * * (Throwing es) ((:>) k k1 api apis)) m

type ServerT * ((:>) * * (Throwing es) ((:>) k k1 api apis)) m = ServerT * (ThrowingNonterminal ((:>) * * (Throwing es) ((:>) k k1 api apis))) m

type ServerT * ((:>) * * (Throwing es) ((:<|>) api1 api2)) m

type ServerT * ((:>) * * (Throwing es) ((:<|>) api1 api2)) m = ServerT * ((:<|>) ((:>) * * (Throwing es) api1) ((:>) * * (Throwing es) api2)) m

type ServerT * ((:>) * * (Throwing es) (Verb * k1 method status ctypes a)) m

type ServerT * ((:>) * * (Throwing es) (Verb * k1 method status ctypes a)) m = ServerT * (Verb * k1 method status ctypes (Envelope es a)) m

type family ThrowingNonterminal api where ...

Used by the HasServer and HasClient instances for Throwing es :> api :> apis to detect Throwing es followed immediately by Throws e.

Equations

ThrowingNonterminal (Throwing es :> (Throws e :> api)) = Throwing (Snoc es e) :> api

ThrowingNonterminal (Throwing es :> (c :> api)) = c :> (Throwing es :> api)