Freckle.App.Http

Centralized module for making HTTP requests from the backend

These functions:

• Do not throw exceptions on non-200
• May throw for other HttpException cases (e.g. ConnectionTimeout)
• Handle 429-Retry-In for you
• Capture decoding failures with Either values as the Response body

Examples

Make request, retry on 429s, and parse the body as JSON.

-- Throws, but only on a complete failure to perform the request
resp <- httpJson $ parseRequest_ "https://example.com"

-- Safe access
getResponseBody resp :: Either HttpDecodeError a

-- Unsafe access (throws on Left)
getResponseBodyUnsafe resp :: m a

httpLbs can be used to get a raw response (without risk of decoding errors), and httpDecode can be used to supply your own decoding function (e.g. for CSV).

Interact with a paginated endpoint that uses Link, combining all the pages monoidally (e.g. concat) and throwing on any decoding errors.

httpPaginated httpJson getResponseBodyUnsafe $ parseRequest_ "https://..."

Decoding errors can be handled differently by adjusting what Monoid you convert each page's response into:

httpPaginated httpJson fromResponseLenient $ parseRequest_ "https://..."

fromResponseLenient
  :: MonadLogger m
  => Response (Either e [MyJsonThing])
  -> m [MyJsonThing]
fromResponseLenient r = case getResponseBody r of
     Left _ -> [] <$ logWarn "..."
     Right a -> pure a

See Freckle.Http.App.Paginate to process requested pages in a streaming fashion, or perform pagination based on somethign other than Link.

Documentation

httpJson :: (MonadIO m, FromJSON a) => Request -> m (Response (Either HttpDecodeError a))

Request and decode a response as JSON

data HttpDecodeError

Constructors

HttpDecodeError

Fields

• hdeBody :: ByteString
• hdeErrors :: NonEmpty String

Instances

Exception HttpDecodeError

Defined in Freckle.App.Http

Methods

toException :: HttpDecodeError -> SomeException

fromException :: SomeException -> Maybe HttpDecodeError

displayException :: HttpDecodeError -> String

Show HttpDecodeError

Defined in Freckle.App.Http

Methods

showsPrec :: Int -> HttpDecodeError -> ShowS

show :: HttpDecodeError -> String

showList :: [HttpDecodeError] -> ShowS

Eq HttpDecodeError

Defined in Freckle.App.Http

Methods

(==) :: HttpDecodeError -> HttpDecodeError -> Bool

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

httpDecode :: MonadIO m => (ByteString -> Either (NonEmpty String) a) -> Request -> m (Response (Either HttpDecodeError a))

Request and decode a response

httpLbs :: MonadIO m => Request -> m (Response ByteString)

Request a lazy ByteString, handling 429 retries

httpNoBody :: MonadIO m => Request -> m (Response ())

Make a Request ignoring the response, but handling 429 retries

httpPaginated :: (MonadIO m, Monoid b) => (Request -> m (Response a)) -> (Response a -> m b) -> Request -> m b

Request all pages of a paginated endpoint into a big list

This uses sourcePaginated, and so reads a Link header. To do otherwise, drop down to sourcePaginatedBy directly.

The second argument is used to extract the data to combine out of the response. This is particularly useful for Either values, like you may get from httpJson. It lives in m to support functions such as getResponseBodyUnsafe.

sourcePaginated

Arguments

:: MonadIO m

=> (Request -> m (Response body))

Run one request

-> Request

Initial request

-> ConduitT i (Response body) m ()

Stream pages of a paginated response, using Link to find next pages

Request builders

data Request

All information on how to connect to a host and what should be sent in the HTTP request.

If you simply wish to download from a URL, see parseRequest.

The constructor for this data type is not exposed. Instead, you should use either the defaultRequest value, or parseRequest to construct from a URL, and then use the records below to make modifications. This approach allows http-client to add configuration options without breaking backwards compatibility.

For example, to construct a POST request, you could do something like:

initReq <- parseRequest "http://www.example.com/path"
let req = initReq
            { method = "POST"
            }

For more information, please see http://www.yesodweb.com/book/settings-types.

Since 0.1.0

Instances

Show Request

Defined in Network.HTTP.Client.Types

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

parseRequest :: MonadThrow m => String -> m Request

Convert a URL into a Request.

This function defaults some of the values in Request, such as setting method to GET and requestHeaders to [].

Since this function uses MonadThrow, the return monad can be anything that is an instance of MonadThrow, such as IO or Maybe.

You can place the request method at the beginning of the URL separated by a space, e.g.:

@@ parseRequest "POST http://httpbin.org/post" @@

Note that the request method must be provided as all capital letters.

A Request created by this function won't cause exceptions on non-2XX response status codes.

To create a request which throws on non-2XX status codes, see parseUrlThrow

Since: http-client-0.4.30

parseRequest_ :: String -> Request

Same as parseRequest, but parse errors cause an impure exception. Mostly useful for static strings which are known to be correctly formatted.

Request modifiers

addRequestHeader :: HeaderName -> ByteString -> Request -> Request

Add a request header name/value combination

Since: http-conduit-2.1.10

addAcceptHeader :: ByteString -> Request -> Request

addBearerAuthorizationHeader :: ByteString -> Request -> Request

addToRequestQueryString :: Query -> Request -> Request

Add to the existing query string parameters.

Since: http-conduit-2.3.5

setRequestBasicAuth

Arguments

:: ByteString

username

-> ByteString

password

-> Request

-> Request

Set basic auth with the given username and password

Since: http-conduit-2.1.10

setRequestBodyJSON :: ToJSON a => a -> Request -> Request

Set the request body as a JSON value

Note: This will not modify the request method. For that, please use requestMethod. You likely don't want the default of GET.

This also sets the Content-Type to application/json; charset=utf-8

NOTE: Depends on the aeson cabal flag being enabled

Since: http-conduit-2.1.10

setRequestBodyURLEncoded :: [(ByteString, ByteString)] -> Request -> Request

Set the request body as URL encoded data

Note: This will change the request method to POST and set the content-type to application/x-www-form-urlencoded

Since: http-conduit-2.1.10

setRequestCheckStatus :: Request -> Request

Modify the request so that non-2XX status codes generate a runtime StatusCodeException, by using throwErrorStatusCodes

Since: http-client-0.5.13

setRequestPath :: ByteString -> Request -> Request

Lens for the requested path info of the request

Since: http-conduit-2.1.10

Response accessors

data Response body

A simple representation of the HTTP response.

Since 0.1.0

Instances

Foldable Response

Defined in Network.HTTP.Client.Types

Methods

fold :: Monoid m => Response m -> m

foldMap :: Monoid m => (a -> m) -> Response a -> m

foldMap' :: Monoid m => (a -> m) -> Response a -> m

foldr :: (a -> b -> b) -> b -> Response a -> b

foldr' :: (a -> b -> b) -> b -> Response a -> b

foldl :: (b -> a -> b) -> b -> Response a -> b

foldl' :: (b -> a -> b) -> b -> Response a -> b

foldr1 :: (a -> a -> a) -> Response a -> a

foldl1 :: (a -> a -> a) -> Response a -> a

toList :: Response a -> [a]

null :: Response a -> Bool

length :: Response a -> Int

elem :: Eq a => a -> Response a -> Bool

maximum :: Ord a => Response a -> a

minimum :: Ord a => Response a -> a

sum :: Num a => Response a -> a

product :: Num a => Response a -> a

Traversable Response

Defined in Network.HTTP.Client.Types

Methods

traverse :: Applicative f => (a -> f b) -> Response a -> f (Response b)

sequenceA :: Applicative f => Response (f a) -> f (Response a)

mapM :: Monad m => (a -> m b) -> Response a -> m (Response b)

sequence :: Monad m => Response (m a) -> m (Response a)

Functor Response

Defined in Network.HTTP.Client.Types

Methods

fmap :: (a -> b) -> Response a -> Response b

(<$) :: a -> Response b -> Response a

Show body => Show (Response body)

Defined in Network.HTTP.Client.Types

Methods

showsPrec :: Int -> Response body -> ShowS

show :: Response body -> String

showList :: [Response body] -> ShowS

getResponseStatus :: Response a -> Status

Get the status of the response

Since: http-conduit-2.1.10

getResponseBody :: Response a -> a

Get the response body

Since: http-conduit-2.1.10

Unsafe access

getResponseBodyUnsafe :: (MonadIO m, Exception e, HasCallStack) => Response (Either e a) -> m a

Read an Either response body, throwing any Left as an exception

If you plan to use this function, and haven't built your decoding to handle error response bodies too, you'll want to use setRequestCheckStatus so that you see status-code exceptions before HttpDecodeErrors.

Exceptions

data HttpException

An exception which may be generated by this library

Since: http-client-0.5.0

Constructors

HttpExceptionRequest Request HttpExceptionContent

Most exceptions are specific to a Request. Inspect the HttpExceptionContent value for details on what occurred.

Since: http-client-0.5.0

InvalidUrlException String String

A URL (first field) is invalid for a given reason (second argument).

Since: http-client-0.5.0

Instances

Exception HttpException

Defined in Network.HTTP.Client.Types

Methods

toException :: HttpException -> SomeException

fromException :: SomeException -> Maybe HttpException

displayException :: HttpException -> String

Show HttpException

Defined in Network.HTTP.Client.Types

Methods

showsPrec :: Int -> HttpException -> ShowS

show :: HttpException -> String

showList :: [HttpException] -> ShowS

Predicates useful for handling HttpExceptions

For example, given a function guarded, which returns Just a given value when a predicate holds for it (otherwise Nothing), you can add error-handling specific to exceptions caused by 4XX responses:

flip catchJust (guard httpExceptionIsClientError *> handle4XXError) $ do
  resp <- httpJson $ setRequestCheckStatus $ parseRequest_ "http://..."
  body <- getResponseBodyUnsafe resp

  -- ...

httpExceptionIsInformational :: HttpException -> Bool

httpExceptionIsRedirection :: HttpException -> Bool

httpExceptionIsClientError :: HttpException -> Bool

httpExceptionIsServerError :: HttpException -> Bool

Network.HTTP.Types re-exports

data Status

HTTP Status.

Only the statusCode is used for comparisons.

Please use mkStatus to create status codes from code and message, or the Enum instance or the status code constants (like ok200). There might be additional record members in the future.

Note that the Show instance is only for debugging.

Instances

Bounded Status

Defined in Network.HTTP.Types.Status

Methods

minBound :: Status

maxBound :: Status

Enum Status

Defined in Network.HTTP.Types.Status

Methods

succ :: Status -> Status

pred :: Status -> Status

toEnum :: Int -> Status

fromEnum :: Status -> Int

enumFrom :: Status -> [Status]

enumFromThen :: Status -> Status -> [Status]

enumFromTo :: Status -> Status -> [Status]

enumFromThenTo :: Status -> Status -> Status -> [Status]

Show Status

Defined in Network.HTTP.Types.Status

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

Eq Status

Defined in Network.HTTP.Types.Status

Methods

(==) :: Status -> Status -> Bool

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

Ord Status

Defined in Network.HTTP.Types.Status

Methods

compare :: Status -> Status -> Ordering

(<) :: Status -> Status -> Bool

(<=) :: Status -> Status -> Bool

(>) :: Status -> Status -> Bool

(>=) :: Status -> Status -> Bool

max :: Status -> Status -> Status

min :: Status -> Status -> Status

statusCode :: Status -> Int

statusIsInformational :: Status -> Bool

Informational class

statusIsSuccessful :: Status -> Bool

Successful class

statusIsRedirection :: Status -> Bool

Redirection class

statusIsClientError :: Status -> Bool

Client Error class

statusIsServerError :: Status -> Bool

Server Error class