dormouse-client-0.2.0.0: Simple, type-safe and testable HTTP client
Safe HaskellNone
LanguageHaskell2010

Dormouse.Client

Description

The Client module is the primary module you will need to import to perform HTTP requests with this library.

For a comprehensive documentation, please see: https://dormouse.io/client.html

Synopsis

Request / Response Types

data HttpRequest url method body contentTag acceptTag Source #

Model of an HTTP request with type parameters: scheme describing the uri scheme, body describing the type of the content body, contentTag describing the type, method describing the HTTP verb associated with the request, contentTag describing the type of content being sen and acceptTag describing the type of content desired

Constructors

HttpRequest 

Instances

Instances details
(Eq body, Eq url) => Eq (HttpRequest url method body contentTag acceptTag) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

(==) :: HttpRequest url method body contentTag acceptTag -> HttpRequest url method body contentTag acceptTag -> Bool #

(/=) :: HttpRequest url method body contentTag acceptTag -> HttpRequest url method body contentTag acceptTag -> Bool #

(Show body, Show url) => Show (HttpRequest url method body contentTag acceptTag) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

showsPrec :: Int -> HttpRequest url method body contentTag acceptTag -> ShowS #

show :: HttpRequest url method body contentTag acceptTag -> String #

showList :: [HttpRequest url method body contentTag acceptTag] -> ShowS #

HasHeaders (HttpRequest url method body contentTag acceptTag) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

getHeaders :: HttpRequest url method body contentTag acceptTag -> Map HeaderName ByteString Source #

getHeaderValue :: HeaderName -> HttpRequest url method body contentTag acceptTag -> Maybe ByteString Source #

data HttpResponse body Source #

Model of an HTTP response with the type parameter body describing the type of the content body.

Instances

Instances details
Eq body => Eq (HttpResponse body) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

(==) :: HttpResponse body -> HttpResponse body -> Bool #

(/=) :: HttpResponse body -> HttpResponse body -> Bool #

Show body => Show (HttpResponse body) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

showsPrec :: Int -> HttpResponse body -> ShowS #

show :: HttpResponse body -> String #

showList :: [HttpResponse body] -> ShowS #

HasHeaders (HttpResponse b) Source # 
Instance details

Defined in Dormouse.Client.Types

Request building

delete :: IsUrl url => url -> HttpRequest url "DELETE" Empty EmptyPayload acceptTag Source #

Create an HTTP DELETE request with the supplied URI, containing no body and no headers

get :: IsUrl url => url -> HttpRequest url "GET" Empty EmptyPayload acceptTag Source #

Create an HTTP GET request with the supplied URI, containing no body and no headers

head :: IsUrl url => url -> HttpRequest url "HEAD" Empty EmptyPayload acceptTag Source #

Create an HTTP HEAD request with the supplied URI, containing no body and no headers

patch :: IsUrl url => url -> HttpRequest url "PATCH" Empty EmptyPayload acceptTag Source #

Create an HTTP PATCH request with the supplied URI, containing no body and no headers

post :: IsUrl url => url -> HttpRequest url "POST" Empty EmptyPayload acceptTag Source #

Create an HTTP POST request with the supplied URI, containing no body and no headers

put :: IsUrl url => url -> HttpRequest url "PUT" Empty EmptyPayload acceptTag Source #

Create an HTTP PUT request with the supplied URI, containing no body and no headers

supplyBody :: (AllowedBody method b, RequestPayload b contentTag) => Proxy contentTag -> b -> HttpRequest url method b' contentTag' acceptTag -> HttpRequest url method b contentTag acceptTag Source #

Supply a body to an HTTP request using the supplied tag to indicate how the request should be encoded

accept :: HasMediaType acceptTag => Proxy acceptTag -> HttpRequest url method b contentTag acceptTag -> HttpRequest url method b contentTag acceptTag Source #

Apply an accept header derived from the supplied tag proxy and add a type hint to the request, indicating how the response should be decodable

expectAs :: (MonadDormouseClient m, RequestPayload b contentTag, ResponsePayload b' acceptTag, IsUrl url) => Proxy acceptTag -> HttpRequest url method b contentTag acceptTag -> m (HttpResponse b') Source #

Make the supplied HTTP request, expecting an HTTP response in the supplied format with body type b to be delivered in some 'MonadDormouseClient m'

expect :: (MonadDormouseClient m, RequestPayload b contentTag, ResponsePayload b' acceptTag, IsUrl url) => HttpRequest url method b contentTag acceptTag -> m (HttpResponse b') Source #

Make the supplied HTTP request, expecting an HTTP response with body type b to be delivered in some 'MonadDormouseClient m'

Dormouse Client Monad and Transformer

data DormouseClientT m a Source #

The DormouseClientT Monad Transformer

Instances

Instances details
MonadTrans DormouseClientT Source # 
Instance details

Defined in Dormouse.Client

Methods

lift :: Monad m => m a -> DormouseClientT m a #

Monad m => MonadReader DormouseClientConfig (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Monad m => Monad (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Functor m => Functor (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Methods

fmap :: (a -> b) -> DormouseClientT m a -> DormouseClientT m b #

(<$) :: a -> DormouseClientT m b -> DormouseClientT m a #

Applicative m => Applicative (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

MonadIO m => MonadIO (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Methods

liftIO :: IO a -> DormouseClientT m a #

MonadThrow m => MonadThrow (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Methods

throwM :: Exception e => e -> DormouseClientT m a #

(MonadIO m, MonadThrow m) => MonadDormouseClient (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Methods

send :: forall url (method :: Symbol) contentTag acceptTag b. IsUrl url => HttpRequest url method RawRequestPayload contentTag acceptTag -> (HttpResponse (SerialT IO Word8) -> IO (HttpResponse b)) -> DormouseClientT m (HttpResponse b) Source #

type DormouseClient a = DormouseClientT IO a Source #

A simple monad that allows you to run DormouseClient

runDormouseClientT :: DormouseClientConfig -> DormouseClientT m a -> m a Source #

Run a DormouseClientT using the supplied DormouseClientConfig to generate a result in the underlying monad m

runDormouseClient :: DormouseClientConfig -> DormouseClient a -> IO a Source #

Run a DormouseClient using the supplied DormouseClientConfig to generate a result in IO

Dormouse Client Class

class Monad m => MonadDormouseClient m where Source #

MonadDormouseClient describes the capability to send HTTP requests and receive an HTTP response

Methods

send :: IsUrl url => HttpRequest url method RawRequestPayload contentTag acceptTag -> (HttpResponse (SerialT IO Word8) -> IO (HttpResponse b)) -> m (HttpResponse b) Source #

Sends a supplied HTTP request and retrieves a response within the supplied monad m

Instances

Instances details
(Monad m, MonadIO m, MonadDormouseTestClient m) => MonadDormouseClient m Source # 
Instance details

Defined in Dormouse.Client.Test.Class

Methods

send :: forall url (method :: Symbol) contentTag acceptTag b. IsUrl url => HttpRequest url method RawRequestPayload contentTag acceptTag -> (HttpResponse (SerialT IO Word8) -> IO (HttpResponse b)) -> m (HttpResponse b) Source #

(MonadIO m, MonadThrow m) => MonadDormouseClient (DormouseClientT m) Source # 
Instance details

Defined in Dormouse.Client

Methods

send :: forall url (method :: Symbol) contentTag acceptTag b. IsUrl url => HttpRequest url method RawRequestPayload contentTag acceptTag -> (HttpResponse (SerialT IO Word8) -> IO (HttpResponse b)) -> DormouseClientT m (HttpResponse b) Source #

Dormouse Client Config

newManager :: ManagerSettings -> IO Manager #

Create a Manager. The Manager will be shut down automatically via garbage collection.

Creating a new Manager is a relatively expensive operation, you are advised to share a single Manager between requests instead.

The first argument to this function is often defaultManagerSettings, though add-on libraries may provide a recommended replacement.

Since 0.1.0

tlsManagerSettings :: ManagerSettings #

Default TLS-enabled manager settings

class HasDormouseClientConfig a where Source #

Describes the capability to retrieve a Dormouse Config

Headers

type HeaderName = CI ByteString Source #

The name of an HTTP Header. Header names are case insensitive.

class HasHeaders a where Source #

Describes something which has headers

Methods

getHeaders :: a -> Map HeaderName ByteString Source #

Retrieve all of the headers which a has.

getHeaderValue :: HeaderName -> a -> Maybe ByteString Source #

Try to retrieve a specific header from a with the supplied HeaderName

Instances

Instances details
HasHeaders (HttpResponse b) Source # 
Instance details

Defined in Dormouse.Client.Types

HasHeaders (HttpRequest url method body contentTag acceptTag) Source # 
Instance details

Defined in Dormouse.Client.Types

Methods

getHeaders :: HttpRequest url method body contentTag acceptTag -> Map HeaderName ByteString Source #

getHeaderValue :: HeaderName -> HttpRequest url method body contentTag acceptTag -> Maybe ByteString Source #

class HasMediaType tag where Source #

Describes an association between a type tag and a specific Media Type

Methods

data HttpMethod (a :: Symbol) where Source #

Constructors

CONNECT :: HttpMethod "CONNECT" 
DELETE :: HttpMethod "DELETE" 
HEAD :: HttpMethod "HEAD" 
GET :: HttpMethod "GET" 
OPTIONS :: HttpMethod "OPTIONS" 
PATCH :: HttpMethod "PATCH" 
POST :: HttpMethod "POST" 
PUT :: HttpMethod "PUT" 
TRACE :: HttpMethod "TRACE" 
CUSTOM :: KnownSymbol a => Proxy a -> HttpMethod a 

Instances

Instances details
Eq (HttpMethod a) Source # 
Instance details

Defined in Dormouse.Client.Methods

Methods

(==) :: HttpMethod a -> HttpMethod a -> Bool #

(/=) :: HttpMethod a -> HttpMethod a -> Bool #

Show (HttpMethod a) Source # 
Instance details

Defined in Dormouse.Client.Methods

type family AllowedBody (a :: Symbol) b :: Constraint Source #

Instances

Instances details
type AllowedBody "CONNECT" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "CONNECT" b = b ~ Empty
type AllowedBody "DELETE" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "DELETE" b = ()
type AllowedBody "GET" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "GET" b = b ~ Empty
type AllowedBody "HEAD" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "HEAD" b = b ~ Empty
type AllowedBody "OPTIONS" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "OPTIONS" b = b ~ Empty
type AllowedBody "PATCH" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "PATCH" b = ()
type AllowedBody "POST" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "POST" b = ()
type AllowedBody "PUT" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "PUT" b = ()
type AllowedBody "TRACE" b Source # 
Instance details

Defined in Dormouse.Client.Methods

type AllowedBody "TRACE" b = b ~ Empty

Payloads

data RawRequestPayload Source #

A raw HTTP Request payload consisting of a stream of bytes with either a defined Content Length or using Chunked Transfer Encoding

Constructors

DefinedContentLength Word64 (SerialT IO Word8)

DefinedContentLength represents a payload where the size of the message is known in advance and the content length header can be computed

ChunkedTransfer (SerialT IO Word8)

ChunkedTransfer represents a payload with indertiminate length, to be sent using chunked transfer encoding

class HasMediaType contentTag => RequestPayload body contentTag where Source #

RequestPayload relates a type of content and a payload tag used to describe that type to its byte stream representation and the constraints required to encode it

Methods

serialiseRequest :: Proxy contentTag -> HttpRequest url method body contentTag acceptTag -> HttpRequest url method RawRequestPayload contentTag acceptTag Source #

Generates a the byte stream representation from the supplied content

Instances

Instances details
ToForm body => RequestPayload body UrlFormPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy UrlFormPayload -> HttpRequest url method body UrlFormPayload acceptTag -> HttpRequest url method RawRequestPayload UrlFormPayload acceptTag Source #

ToJSON body => RequestPayload body JsonPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy JsonPayload -> HttpRequest url method body JsonPayload acceptTag -> HttpRequest url method RawRequestPayload JsonPayload acceptTag Source #

RequestPayload Text HtmlPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy HtmlPayload -> HttpRequest url method Text HtmlPayload acceptTag -> HttpRequest url method RawRequestPayload HtmlPayload acceptTag Source #

RequestPayload Empty EmptyPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy EmptyPayload -> HttpRequest url method Empty EmptyPayload acceptTag -> HttpRequest url method RawRequestPayload EmptyPayload acceptTag Source #

class HasMediaType tag => ResponsePayload body tag where Source #

ResponsePayload relates a type of content and a payload tag used to describe that type to its byte stream representation and the constraints required to decode it

Methods

deserialiseRequest :: Proxy tag -> HttpResponse (SerialT IO Word8) -> IO (HttpResponse body) Source #

Decodes the high level representation from the supplied byte stream

data HtmlPayload Source #

Instances

Instances details
HasMediaType HtmlPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

ResponsePayload Text HtmlPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

RequestPayload Text HtmlPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy HtmlPayload -> HttpRequest url method Text HtmlPayload acceptTag -> HttpRequest url method RawRequestPayload HtmlPayload acceptTag Source #

data JsonPayload Source #

Instances

Instances details
HasMediaType JsonPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

FromJSON body => ResponsePayload body JsonPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

ToJSON body => RequestPayload body JsonPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy JsonPayload -> HttpRequest url method body JsonPayload acceptTag -> HttpRequest url method RawRequestPayload JsonPayload acceptTag Source #

data UrlFormPayload Source #

Instances

Instances details
HasMediaType UrlFormPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

FromForm body => ResponsePayload body UrlFormPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

ToForm body => RequestPayload body UrlFormPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy UrlFormPayload -> HttpRequest url method body UrlFormPayload acceptTag -> HttpRequest url method RawRequestPayload UrlFormPayload acceptTag Source #

data Empty Source #

Instances

Instances details
ResponsePayload Empty EmptyPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

RequestPayload Empty EmptyPayload Source # 
Instance details

Defined in Dormouse.Client.Payload

Methods

serialiseRequest :: forall url (method :: Symbol) acceptTag. Proxy EmptyPayload -> HttpRequest url method Empty EmptyPayload acceptTag -> HttpRequest url method RawRequestPayload EmptyPayload acceptTag Source #

json :: Proxy JsonPayload Source #

A type tag used to indicate that a request/response should be encoded/decoded as application/json data

urlForm :: Proxy UrlFormPayload Source #

A type tag used to indicate that a request/response should be encoded/decoded as application/x-www-form-urlencoded data

noPayload :: Proxy EmptyPayload Source #

A type tag used to indicate that a request/response has no payload

html :: Proxy HtmlPayload Source #

A type tag used to indicate that a request/response should be encoded/decoded as text/html data

Exceptions

newtype DecodingException Source #

DecodingException is used to when something has gone wrong decoding an http response into the expected representation, e.g. json was expected but the response json was invalid.

newtype MediaTypeException Source #

MediaTypeException is used to indicate an error parsing a MediaType header such as "Content-Type" into a valid MediaType

newtype UriException #

UriException is used to indicate an error parsing a URI

Constructors

UriException 

newtype UrlException #

UrlException is used to indicate an error in transforming a valid URI into a URL, e.g. the URI refers to a different schema such as file

Constructors

UrlException 

Uri

data Uri #

A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. It is defined according to RFC 3986 (https://tools.ietf.org/html/rfc3986).

Instances

Instances details
Eq Uri 
Instance details

Defined in Dormouse.Uri.Types

Methods

(==) :: Uri -> Uri -> Bool #

(/=) :: Uri -> Uri -> Bool #

Show Uri 
Instance details

Defined in Dormouse.Uri.Types

Methods

showsPrec :: Int -> Uri -> ShowS #

show :: Uri -> String #

showList :: [Uri] -> ShowS #

Lift Uri 
Instance details

Defined in Dormouse.Uri.Types

Methods

lift :: Uri -> Q Exp #

liftTyped :: Uri -> Q (TExp Uri) #

parseUri :: MonadThrow m => ByteString -> m Uri #

Parse an ascii ByteString as a uri, throwing a UriException in m if this fails

Url

data Url (scheme :: Symbol) #

A Url is defined here as an absolute URI in the http or https schemes. Authority components are requried by the http / https Uri schemes.

Instances

Instances details
Lift (Url scheme :: Type) 
Instance details

Defined in Dormouse.Url.Types

Methods

lift :: Url scheme -> Q Exp #

liftTyped :: Url scheme -> Q (TExp (Url scheme)) #

Eq (Url scheme) 
Instance details

Defined in Dormouse.Url.Types

Methods

(==) :: Url scheme -> Url scheme -> Bool #

(/=) :: Url scheme -> Url scheme -> Bool #

Show (Url scheme) 
Instance details

Defined in Dormouse.Url.Types

Methods

showsPrec :: Int -> Url scheme -> ShowS #

show :: Url scheme -> String #

showList :: [Url scheme] -> ShowS #

IsUrl (Url scheme) 
Instance details

Defined in Dormouse.Url.Class

Methods

asAnyUrl :: Url scheme -> AnyUrl #

data AnyUrl #

AnyUrl is a wrapper aroud Url which allows either http or https urls.

Constructors

AnyUrl (Url scheme) 

Instances

Instances details
Eq AnyUrl 
Instance details

Defined in Dormouse.Url.Types

Methods

(==) :: AnyUrl -> AnyUrl -> Bool #

(/=) :: AnyUrl -> AnyUrl -> Bool #

Show AnyUrl 
Instance details

Defined in Dormouse.Url.Types

IsUrl AnyUrl 
Instance details

Defined in Dormouse.Url.Class

Methods

asAnyUrl :: AnyUrl -> AnyUrl #

Lift AnyUrl 
Instance details

Defined in Dormouse.Url.Types

Methods

lift :: AnyUrl -> Q Exp #

liftTyped :: AnyUrl -> Q (TExp AnyUrl) #

class (Eq url, Show url) => IsUrl url where #

Methods

asAnyUrl :: url -> AnyUrl #

Instances

Instances details
IsUrl AnyUrl 
Instance details

Defined in Dormouse.Url.Class

Methods

asAnyUrl :: AnyUrl -> AnyUrl #

IsUrl (Url scheme) 
Instance details

Defined in Dormouse.Url.Class

Methods

asAnyUrl :: Url scheme -> AnyUrl #

ensureHttp :: MonadThrow m => AnyUrl -> m (Url "http") #

Ensure that the supplied Url uses the _http_ scheme, throwing a UrlException in m if this is not the case

ensureHttps :: MonadThrow m => AnyUrl -> m (Url "https") #

Ensure that the supplied Url uses the _https_ scheme, throwing a UrlException in m if this is not the case

parseUrl :: MonadThrow m => ByteString -> m AnyUrl #

Parse an ascii ByteString as a url, throwing a UriException in m if this fails

parseHttpUrl :: MonadThrow m => ByteString -> m (Url "http") #

Parse an ascii ByteString as an http url, throwing a UriException in m if this fails

parseHttpsUrl :: MonadThrow m => ByteString -> m (Url "https") #

Parse an ascii ByteString as an https url, throwing a UriException in m if this fails