Copyright	2018 Automattic Inc.
License	BSD3
Maintainer	Nathan Bloomfield (nbloomf@gmail.com)
Stability	experimental
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Control.Monad.Script.Http

Contents

Http
HttpT
Error
Reader
Writer
State
Prompt
API
Types
Testing

Description

A basic type and monad for describing HTTP interactions.

Synopsis

type Http e r w s p a = HttpT e r w s p Identity a
execHttpM :: Monad eff => S s -> R e w r -> (forall u. P p u -> eff u) -> Http e r w s p t -> eff (Either (E e) t, S s, W e w)
data HttpT e r w s p m a
execHttpTM :: (Monad (m eff), Monad eff) => S s -> R e w r -> (forall u. P p u -> eff u) -> (forall u. eff u -> m eff u) -> HttpT e r w s p (m eff) t -> m eff (Either (E e) t, S s, W e w)
liftHttpT :: Monad m => m a -> HttpT e r w s p m a
throwError :: e -> HttpT e r w s p m a
throwJsonError :: JsonError -> HttpT e r w s p m a
throwHttpException :: HttpException -> HttpT e r w s p m a
throwIOException :: IOException -> HttpT e r w s p m a
catchError :: HttpT e r w s p m a -> (e -> HttpT e r w s p m a) -> HttpT e r w s p m a
catchJsonError :: HttpT e r w s p m a -> (JsonError -> HttpT e r w s p m a) -> HttpT e r w s p m a
catchHttpException :: HttpT e r w s p m a -> (HttpException -> HttpT e r w s p m a) -> HttpT e r w s p m a
catchIOException :: HttpT e r w s p m a -> (IOException -> HttpT e r w s p m a) -> HttpT e r w s p m a
catchAnyError :: HttpT e r w s p m a -> (e -> HttpT e r w s p m a) -> (HttpException -> HttpT e r w s p m a) -> (IOException -> HttpT e r w s p m a) -> (JsonError -> HttpT e r w s p m a) -> HttpT e r w s p m a
printError :: (e -> String) -> E e -> String
data E e
ask :: HttpT e r w s p m (R e w r)
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
reader :: (R e w r -> a) -> HttpT e r w s p m a
data R e w r = R {
- _logOptions :: LogOptions e w
- _logEntryPrinter :: LogOptions e w -> LogEntry e w -> Maybe String
- _logHandle :: Handle
- _logLock :: Maybe (MVar ())
- _uid :: String
- _httpErrorInject :: HttpException -> Maybe e
- _env :: r
}
basicEnv :: (Show e, Show w) => r -> R e w r
trivialEnv :: r -> R e w r
data LogOptions e w = LogOptions {
- _logColor :: Bool
- _logJson :: Bool
- _logSilent :: Bool
- _logMinSeverity :: LogSeverity
- _logHeaders :: Bool
- _printUserError :: Bool -> e -> String
- _printUserLog :: Bool -> w -> String
}
basicLogOptions :: (Show e, Show w) => LogOptions e w
trivialLogOptions :: LogOptions e w
logEntries :: W e w -> [w]
data LogSeverity
- = LogDebug
- | LogInfo
- | LogNotice
- | LogWarning
- | LogError
- | LogCritical
- | LogAlert
- | LogEmergency
setLogSeverity :: LogSeverity -> HttpT e r w s p m a -> HttpT e r w s p m a
data W e w
printHttpLogs :: Handle -> Maybe (MVar ()) -> LogOptions e w -> (LogOptions e w -> LogEntry e w -> Maybe String) -> W e w -> IO ()
basicLogEntryPrinter :: LogOptions e w -> LogEntry e w -> Maybe String
gets :: (S s -> a) -> HttpT e r w s p m a
modify :: (S s -> S s) -> HttpT e r w s p m ()
data S s = S {
- _httpOptions :: Options
- _httpSession :: Maybe Session
- _userState :: s
}
basicState :: s -> S s
prompt :: P p a -> HttpT e r w s p m a
data P p a where
- 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 :: (p a -> IO a) -> P p a -> IO a
evalMockIO :: (p a -> MockIO s a) -> P p a -> MockIO s a
comment :: String -> HttpT e r w s p m ()
wait :: Int -> HttpT e r w s p m ()
logDebug :: w -> HttpT e r w s p m ()
logInfo :: w -> HttpT e r w s p m ()
logNotice :: w -> HttpT e r w s p m ()
logWarning :: w -> HttpT e r w s p m ()
logError :: w -> HttpT e r w s p m ()
logCritical :: w -> HttpT e r w s p m ()
logAlert :: w -> HttpT e r w s p m ()
logEmergency :: w -> HttpT e r w s p m ()
hPutStrLn :: Handle -> String -> HttpT e r w s p m ()
hPutStrLnBlocking :: MVar () -> Handle -> String -> HttpT e r w s p m ()
httpGet :: Url -> HttpT e r w s p m HttpResponse
httpSilentGet :: Url -> HttpT e r w s p m HttpResponse
httpPost :: Url -> ByteString -> HttpT e r w s p m HttpResponse
httpSilentPost :: Url -> ByteString -> HttpT e r w s p m HttpResponse
httpDelete :: Url -> HttpT e r w s p m HttpResponse
httpSilentDelete :: Url -> HttpT e r w s p m HttpResponse
parseJson :: ByteString -> HttpT e r w s p m Value
lookupKeyJson :: Text -> Value -> HttpT e r w s p m Value
constructFromJson :: FromJSON a => Value -> HttpT e r w s p m a
type Url = String
data JsonError
- = JsonError String
- | JsonParseError ByteString
- | JsonKeyDoesNotExist Text Value
- | JsonKeyLookupOffObject Text Value
- | JsonConstructError String
data HttpResponse = HttpResponse {
- _responseStatus :: Status
- _responseVersion :: HttpVersion
- _responseHeaders :: ResponseHeaders
- _responseBody :: ByteString
- _responseCookieJar :: CookieJar
}
checkHttpM :: Monad eff => S s -> R e w r -> (forall u. P p u -> eff u) -> (eff (Either (E e) t, S s, W e w) -> IO q) -> (q -> Bool) -> Http e r w s p t -> Property
checkHttpTM :: (Monad (m eff), Monad eff) => S s -> R e w r -> (forall u. P p u -> eff u) -> (forall u. eff u -> m eff u) -> (m eff (Either (E e) t, S s, W e w) -> IO q) -> (q -> Bool) -> HttpT e r w s p (m eff) t -> Property

Http

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

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 Source #

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 Source #

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) Source #
Instance details Defined in Control.Monad.Script.Http 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) Source #
Instance details Defined in Control.Monad.Script.Http 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) Source #
Instance details Defined in Control.Monad.Script.Http 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 Source #

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 Source #

Lift a value from the inner monad

Error

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

Also logs the exception.

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

Also logs the exception.

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

Also logs the exception.

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

Also logs the exception.

catchError Source #

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 Source #

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 Source #

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 Source #

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.

catchAnyError :: HttpT e r w s p m a -> (e -> HttpT e r w s p m a) -> (HttpException -> HttpT e r w s p m a) -> (IOException -> HttpT e r w s p m a) -> (JsonError -> HttpT e r w s p m a) -> HttpT e r w s p m a Source #

Handle any thrown error. To handle only errors of a specific type, see catchError, catchJsonError, catchIOException, or catchHttpException.

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

Pretty printer for errors

data E e Source #

Error type.

Reader

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

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 Source #

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 Source #

Retrieve the image of the environment under a given function.

data R e w r Source #

Generic session environment.

Constructors

R

Fields

_logOptions :: LogOptions e w
_logEntryPrinter :: LogOptions e w -> LogEntry e w -> Maybe String
Printer for log entries.
_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 Source #

Arguments

:: (Show e, Show w)
=> r	Client-supplied environment value.
-> R e w r

Environment constructor

trivialEnv Source #

Arguments

:: r	Client-supplied environment value.
-> R e w r

Environment constructor

data LogOptions e w Source #

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
_logMinSeverity :: LogSeverity
Suppress log output below this severity
_logHeaders :: Bool
Toggle for printing HTTP headers
_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 Source #

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

trivialLogOptions :: LogOptions e w Source #

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] Source #

Extract the user-defined log entries.

data LogSeverity Source #

Syslog style log severities.

Constructors

LogDebug	Debug-level messages
LogInfo	Informational messages
LogNotice	Normal but significant condition
LogWarning	Warning conditions
LogError	Error conditions
LogCritical	Critical conditions
LogAlert	Action must be taken immediately
LogEmergency	System is unusable

Instances

Eq LogSeverity Source #
Instance details Defined in Data.LogSeverity Methods (==) :: LogSeverity -> LogSeverity -> Bool # (/=) :: LogSeverity -> LogSeverity -> Bool #
Ord LogSeverity Source #
Instance details Defined in Data.LogSeverity Methods compare :: LogSeverity -> LogSeverity -> Ordering # (<) :: LogSeverity -> LogSeverity -> Bool # (<=) :: LogSeverity -> LogSeverity -> Bool # (>) :: LogSeverity -> LogSeverity -> Bool # (>=) :: LogSeverity -> LogSeverity -> Bool # max :: LogSeverity -> LogSeverity -> LogSeverity # min :: LogSeverity -> LogSeverity -> LogSeverity #
Show LogSeverity Source #
Instance details Defined in Data.LogSeverity Methods showsPrec :: Int -> LogSeverity -> ShowS # show :: LogSeverity -> String # showList :: [LogSeverity] -> ShowS #

setLogSeverity :: LogSeverity -> HttpT e r w s p m a -> HttpT e r w s p m a Source #

Set the severity level of all log actions in a session.

data W e w Source #

Log type

Instances

(Show e, Show w) => Show (W e w) Source #
Instance details Defined in Control.Monad.Script.Http Methods showsPrec :: Int -> W e w -> ShowS # show :: W e w -> String # showList :: [W e w] -> ShowS #
Semigroup (W e w) Source #
Instance details Defined in Control.Monad.Script.Http Methods (<>) :: W e w -> W e w -> W e w # sconcat :: NonEmpty (W e w) -> W e w # stimes :: Integral b => b -> W e w -> W e w #
Monoid (W e w) Source #
Instance details Defined in Control.Monad.Script.Http Methods mempty :: W e w # mappend :: W e w -> W e w -> W e w # mconcat :: [W e w] -> W e w #

printHttpLogs :: Handle -> Maybe (MVar ()) -> LogOptions e w -> (LogOptions e w -> LogEntry e w -> Maybe String) -> W e w -> IO () Source #

All log statements should go through logNow.

basicLogEntryPrinter :: LogOptions e w -> LogEntry e w -> Maybe String Source #

Simple default pretty printer for LogEntrys.

State

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

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

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

Modify the current state strictly.

data S s Source #

State type

Constructors

S
Fields _httpOptions :: Options _httpSession :: Maybe Session _userState :: s

basicState :: s -> S s Source #

State constructor

Prompt

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

Inject an atomic effect.

data P p a where Source #

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 Source #

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 Source #

Basic evaluator for interpreting atomic Http effects in MockIO.

API

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

Write a comment to the log

wait Source #

Arguments

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

Pause the thread

logDebug :: w -> HttpT e r w s p m () Source #

For debug level messages

logInfo :: w -> HttpT e r w s p m () Source #

For informational messages

logNotice :: w -> HttpT e r w s p m () Source #

For normal but significant conditions

logWarning :: w -> HttpT e r w s p m () Source #

For warning conditions

logError :: w -> HttpT e r w s p m () Source #

For error conditions

logCritical :: w -> HttpT e r w s p m () Source #

For critical conditions

logAlert :: w -> HttpT e r w s p m () Source #

Action must be taken immediately

logEmergency :: w -> HttpT e r w s p m () Source #

System is unusable

IO

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

Write a line to a handle

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

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 Source #

Run a GET request

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

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

httpPost Source #

Arguments

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

Run a POST request

httpSilentPost Source #

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 Source #

Run a DELETE request

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

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 Source #

Parse a ByteString to a JSON Value.

lookupKeyJson Source #

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 Source #

Decode a Value to some other type.

Types

type Url = String Source #

To make type signatures nicer

data JsonError Source #

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 Source #
Instance details Defined in Data.Aeson.Extras Methods (==) :: JsonError -> JsonError -> Bool # (/=) :: JsonError -> JsonError -> Bool #
Show JsonError Source #
Instance details Defined in Data.Aeson.Extras Methods showsPrec :: Int -> JsonError -> ShowS # show :: JsonError -> String # showList :: [JsonError] -> ShowS #
Arbitrary JsonError Source #
Instance details Defined in Data.Aeson.Extras Methods arbitrary :: Gen JsonError # shrink :: JsonError -> [JsonError] #

data HttpResponse Source #

Non-opaque HTTP response type.

Constructors

HttpResponse
Fields _responseStatus :: Status _responseVersion :: HttpVersion _responseHeaders :: ResponseHeaders _responseBody :: ByteString _responseCookieJar :: CookieJar

Instances

Eq HttpResponse Source #
Instance details Defined in Network.HTTP.Client.Extras Methods (==) :: HttpResponse -> HttpResponse -> Bool # (/=) :: HttpResponse -> HttpResponse -> Bool #
Show HttpResponse Source #
Instance details Defined in Network.HTTP.Client.Extras Methods showsPrec :: Int -> HttpResponse -> ShowS # show :: HttpResponse -> String # showList :: [HttpResponse] -> ShowS #

Testing

checkHttpM Source #

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 Source #

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.