Control.Monad.Script.Http

A basic type and monad for describing HTTP interactions.

Http

type Http e r w s p a = HttpT e r w s p Identity a

An HTTP session returning an a, writing to a log of type W e w, reading from an environment of type R e w r, with state of type S s, throwing errors of type E e, performing effectful computations described by P p a. HttpT over Identity.

execHttpM

Arguments

:: Monad eff

=> S s

Initial state

-> R e w r

Environment

-> (forall u. P p u -> eff u)

Effect evaluator

-> Http e r w s p t

-> eff (Either (E e) t, S s, W e w)

Execute an Http session.

HttpT

data HttpT e r w s p m a

An HTTP session returning an a, writing to a log of type W e w, reading from an environment of type R e w r, with state of type S s, throwing errors of type E e, performing effectful computations described by P p a, and with inner monad m.

Instances

Monad (HttpT e r w s p m)

Methods

(>>=) :: HttpT e r w s p m a -> (a -> HttpT e r w s p m b) -> HttpT e r w s p m b

(>>) :: HttpT e r w s p m a -> HttpT e r w s p m b -> HttpT e r w s p m b

return :: a -> HttpT e r w s p m a

fail :: String -> HttpT e r w s p m a

Functor (HttpT e r w s p m)

Methods

fmap :: (a -> b) -> HttpT e r w s p m a -> HttpT e r w s p m b

(<$) :: a -> HttpT e r w s p m b -> HttpT e r w s p m a

Applicative (HttpT e r w s p m)

Methods

pure :: a -> HttpT e r w s p m a

(<*>) :: HttpT e r w s p m (a -> b) -> HttpT e r w s p m a -> HttpT e r w s p m b

liftA2 :: (a -> b -> c) -> HttpT e r w s p m a -> HttpT e r w s p m b -> HttpT e r w s p m c

(*>) :: HttpT e r w s p m a -> HttpT e r w s p m b -> HttpT e r w s p m b

(<*) :: HttpT e r w s p m a -> HttpT e r w s p m b -> HttpT e r w s p m a

execHttpTM

Arguments

:: (Monad (m eff), Monad eff)

=> S s

Initial state

-> R e w r

Environment

-> (forall u. P p u -> eff u)

Effect evaluator

-> (forall u. eff u -> m eff u)

Lift effects to the inner monad

-> HttpT e r w s p (m eff) t

-> m eff (Either (E e) t, S s, W e w)

Execute an HttpT session.

liftHttpT :: Monad m => m a -> HttpT e r w s p m a

Lift a value from the inner monad

Error

throwError :: e -> HttpT e r w s p m a

Also logs the exception.

throwJsonError :: JsonError -> HttpT e r w s p m a

Also logs the exception.

throwHttpException :: HttpException -> HttpT e r w s p m a

Also logs the exception.

throwIOException :: IOException -> HttpT e r w s p m a

Also logs the exception.

catchError

Arguments

:: HttpT e r w s p m a

-> (e -> HttpT e r w s p m a)

Handler

-> HttpT e r w s p m a

Re-throws other error types.

catchJsonError

Arguments

:: HttpT e r w s p m a

-> (JsonError -> HttpT e r w s p m a)

Handler

-> HttpT e r w s p m a

Re-throws other error types.

catchHttpException

Arguments

:: HttpT e r w s p m a

-> (HttpException -> HttpT e r w s p m a)

Handler

-> HttpT e r w s p m a

Re-throws other error types.

catchIOException

Arguments

:: HttpT e r w s p m a

-> (IOException -> HttpT e r w s p m a)

Handler

-> HttpT e r w s p m a

Re-throws other error types.

printError :: (e -> String) -> E e -> String

Pretty printer for errors

data E e

Error type.

Reader

ask :: HttpT e r w s p m (R e w r)

Retrieve the environment.

local :: (R e w r -> R e w r) -> HttpT e r w s p m a -> HttpT e r w s p m a

Run an action with a locally adjusted environment of the same type.

reader :: (R e w r -> a) -> HttpT e r w s p m a

Retrieve the image of the environment under a given function.

data R e w r

Generic session environment.

Constructors

R

Fields

• _logOptions :: LogOptions e w
• _logHandle :: Handle

  Handle for printing logs

• _logLock :: Maybe (MVar ())

  Lock used to prevent race conditions when writing to the log.

• _uid :: String

  Identifier string for the session; used to help match log entries emitted by the same session.

• _httpErrorInject :: HttpException -> Maybe e

  Function for elevating HttpExceptions to a client-supplied error type.

• _env :: r

  Client-supplied environment type.

basicEnv

Arguments

:: (Show e, Show w)

=> r

Client-supplied environment value.

-> R e w r

Environment constructor

trivialEnv

Arguments

:: r

Client-supplied environment value.

-> R e w r

Environment constructor

data LogOptions e w

Options for tweaking the logs.

Constructors

LogOptions

Fields

• _logColor :: Bool

  Toggle color

• _logJson :: Bool

  Toggle JSON pretty printing

• _logSilent :: Bool

  Toggle to silence the logs

• _logHeaders :: Bool

  Toggle for printing HTTP headers

• _logEntryPrinter :: (String -> String) -> (String, String, String) -> String

  Printer for log entries; first argument colorizes a string, and the tuple argument is (timestamp, uid, message).

• _printUserError :: Bool -> e -> String

  Printer for client-supplied error type. The boolean toggles JSON pretty printing.

• _printUserLog :: Bool -> w -> String

  Printer for client-supplied log type. the boolean toggles JSON pretty printing.

basicLogOptions :: (Show e, Show w) => LogOptions e w

Noisy, in color, without parsing JSON responses, and using Show instances for user-supplied error and log types.

trivialLogOptions :: LogOptions e w

Noisy, in color, without parsing JSON responses, and using trivial printers for user-supplied error and log types. For testing.

Writer

logEntries :: W e w -> [w]

Extract the user-defined log entries.

data W e w

Log type

Instances

Monoid (W e w)

Methods

mempty :: W e w

mappend :: W e w -> W e w -> W e w

mconcat :: [W e w] -> W e w

State

gets :: (S s -> a) -> HttpT e r w s p m a

Retrieve the image of the current state under a given function.

modify :: (S s -> S s) -> HttpT e r w s p m ()

Modify the current state strictly.

data S s

State type

Constructors

S

Fields

• _httpOptions :: Options
• _httpSession :: Maybe Session
• _userState :: s

basicState :: s -> S s

State constructor

Prompt

prompt :: P p a -> HttpT e r w s p m a

Inject an atomic effect.

data P p a where

Atomic effects

Constructors

HPutStrLn :: Handle -> String -> P p (Either IOException ())

HPutStrLnBlocking :: MVar () -> Handle -> String -> P p (Either IOException ())

GetSystemTime :: P p UTCTime

ThreadDelay :: Int -> P p ()

HttpGet :: Options -> Maybe Session -> Url -> P p (Either HttpException HttpResponse)

HttpPost :: Options -> Maybe Session -> Url -> ByteString -> P p (Either HttpException HttpResponse)

HttpDelete :: Options -> Maybe Session -> Url -> P p (Either HttpException HttpResponse)

P :: p a -> P p a

evalIO

Arguments

:: (p a -> IO a)

Evaluator for user effects

-> P p a

-> IO a

Basic evaluator for interpreting atomic Http effects in IO.

evalMockIO :: (p a -> MockIO s a) -> P p a -> MockIO s a

Basic evaluator for interpreting atomic Http effects in MockIO.

API

comment :: String -> HttpT e r w s p m ()

Write a comment to the log

wait

Arguments

:: Int

milliseconds

-> HttpT e r w s p m ()

Pause the thread

logEntry :: w -> HttpT e r w s p m ()

Write an entry to the log

IO

hPutStrLn :: Handle -> String -> HttpT e r w s p m ()

Write a line to a handle

hPutStrLnBlocking :: MVar () -> Handle -> String -> HttpT e r w s p m ()

Write a line to a handle, using the given MVar as a lock

HTTP calls

httpGet :: Url -> HttpT e r w s p m HttpResponse

Run a GET request

httpSilentGet :: Url -> HttpT e r w s p m HttpResponse

Run a GET request, but do not write the request or response to the logs.

httpPost

Arguments

:: Url

-> ByteString

Payload

-> HttpT e r w s p m HttpResponse

Run a POST request

httpSilentPost

Arguments

:: Url

-> ByteString

Payload

-> HttpT e r w s p m HttpResponse

Run a POST request, but do not write the request or response to the logs.

httpDelete :: Url -> HttpT e r w s p m HttpResponse

Run a DELETE request

httpSilentDelete :: Url -> HttpT e r w s p m HttpResponse

Run a DELETE request, but do not write the request or response to the logs.

JSON

parseJson :: ByteString -> HttpT e r w s p m Value

Parse a ByteString to a JSON Value.

lookupKeyJson

Arguments

:: Text

Key name

-> Value

JSON object

-> HttpT e r w s p m Value

Object member lookup.

constructFromJson :: FromJSON a => Value -> HttpT e r w s p m a

Decode a Value to some other type.

Types

type Url = String

To make type signatures nicer

data JsonError

Represents the kinds of errors that can occur when parsing and decoding JSON.

Constructors

JsonError String

A generic JSON error; try not to use this.

JsonParseError ByteString

A failed parse.

JsonKeyDoesNotExist Text Value

An attempt to look up the value of a key that does not exist on an object.

JsonKeyLookupOffObject Text Value

An attempt to look up the value of a key on something other than an object.

JsonConstructError String

A failed attempt to convert a Value to some other type.

Instances

Eq JsonError

Methods

(==) :: JsonError -> JsonError -> Bool

(/=) :: JsonError -> JsonError -> Bool

Show JsonError

Methods

showsPrec :: Int -> JsonError -> ShowS

show :: JsonError -> String

showList :: [JsonError] -> ShowS

Arbitrary JsonError

Methods

arbitrary :: Gen JsonError

shrink :: JsonError -> [JsonError]

data HttpResponse

Non-opaque HTTP response type.

Constructors

HttpResponse

Fields

• _responseStatus :: Status
• _responseVersion :: HttpVersion
• _responseHeaders :: ResponseHeaders
• _responseBody :: ByteString
• _responseCookieJar :: CookieJar

Instances

Eq HttpResponse

Methods

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

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

Show HttpResponse

Methods

showsPrec :: Int -> HttpResponse -> ShowS

show :: HttpResponse -> String

showList :: [HttpResponse] -> ShowS

Testing

checkHttpM

Arguments

:: Monad eff

=> S s

Initial state

-> R e w r

Environment

-> (forall u. P p u -> eff u)

Effect evaluator

-> (eff (Either (E e) t, S s, W e w) -> IO q)

Condense to IO

-> (q -> Bool)

Result check

-> Http e r w s p t

-> Property

Turn an Http into a Property; for testing with QuickCheck.

checkHttpTM

Arguments

:: (Monad (m eff), Monad eff)

=> S s

Initial state

-> R e w r

Environment

-> (forall u. P p u -> eff u)

Effect evaluator

-> (forall u. eff u -> m eff u)

Lift effects to the inner monad

-> (m eff (Either (E e) t, S s, W e w) -> IO q)

Condense to IO

-> (q -> Bool)

Result check

-> HttpT e r w s p (m eff) t

-> Property

Turn an HttpT into a property; for testing with QuickCheck.