Network.Wreq.Lens

HTTP client lens machinery.

When reading the examples in this module, you should assume the following environment:

-- Make it easy to write literal ByteString and Text values.
{-# LANGUAGE OverloadedStrings #-}

-- Our handy module.
import Network.Wreq

-- Operators such as (&) and (.~).
import Control.Lens

-- Conversion of Haskell values to JSON.
import Data.Aeson (toJSON)

-- Easy traversal of JSON data.
import Data.Aeson.Lens (key, nth)

Configuration

data Options

Options for configuring a client.

Instances

Show Options

Defined in Network.Wreq.Internal.Types

Methods

showsPrec :: Int -> Options -> ShowS

show :: Options -> String

showList :: [Options] -> ShowS

manager :: Lens' Options (Either ManagerSettings Manager)

A lens onto configuration of the connection manager provided by the http-client package.

In this example, we enable the use of OpenSSL for (hopefully) secure connections:

import OpenSSL.Session (context)
import Network.HTTP.Client.OpenSSL

let opts = defaults & manager .~ Left (opensslManagerSettings context)
withOpenSSL $
  getWith opts "https://httpbin.org/get"
 

In this example, we also set the response timeout to 10000 microseconds:

import OpenSSL.Session (context)
import Network.HTTP.Client.OpenSSL
import Network.HTTP.Client (defaultManagerSettings, managerResponseTimeout)

let opts = defaults & manager .~ Left (opensslManagerSettings context)
                    & manager .~ Left (defaultManagerSettings { managerResponseTimeout = responseTimeoutMicro 10000 } )

withOpenSSL $
  getWith opts "https://httpbin.org/get"
 

proxy :: Lens' Options (Maybe Proxy)

A lens onto proxy configuration.

Example:

let opts = defaults & proxy ?~ httpProxy "localhost" 8000
getWith opts "http://httpbin.org/get"
 

Note here the use of the ?~ setter to turn a Proxy into a Maybe Proxy, to make the type of the RHS compatible with the proxy lens.

auth :: Lens' Options (Maybe Auth)

A lens onto request authentication.

Example (note the use of TLS):

let opts = defaults & auth ?~ basicAuth "user" "pass"
getWith opts "https://httpbin.org/basic-auth/user/pass"
 

header :: HeaderName -> Lens' Options [ByteString]

A lens onto all headers with the given name (there can legitimately be zero or more).

Example:

let opts = defaults & header "Accept" .~ ["*/*"]
getWith opts "http://httpbin.org/get"
 

param :: Text -> Lens' Options [Text]

A lens onto all query parameters with the given name (there can legitimately be zero or more).

In this example, we construct the query URL "http://httpbin.org/get?foo=bar&foo=quux".

let opts = defaults & param "foo" .~ ["bar", "quux"]
getWith opts "http://httpbin.org/get"
 

redirects :: Lens' Options Int

A lens onto the maximum number of redirects that will be followed before an exception is thrown.

In this example, a HttpException will be thrown with a TooManyRedirects constructor, because the maximum number of redirects allowed will be exceeded.

let opts = defaults & redirects .~ 3
getWith opts "http://httpbin.org/redirect/5"
 

headers :: Lens' Options [Header]

A lens onto all headers (there can legitimately be zero or more).

In this example, we print all the headers sent by default with every request.

print (defaults ^. headers)
 

params :: Lens' Options [(Text, Text)]

A lens onto all query parameters.

cookie :: ByteString -> Traversal' Options Cookie

A traversal onto the cookie with the given name, if one exists.

N.B. This is an "illegal" Traversal': we can change the cookieName of the associated Cookie so that it differs from the name provided to this function.

cookies :: Lens' Options (Maybe CookieJar)

A lens onto all cookies.

type ResponseChecker = Request -> Response BodyReader -> IO ()

A function that checks the result of a HTTP request and potentially throw an exception.

checkResponse :: Lens' Options (Maybe ResponseChecker)

A lens to get the optional status check function

Proxy setup

data Proxy

Define a HTTP proxy, consisting of a hostname and port number.

Instances

Read Proxy

Defined in Network.HTTP.Client.Types

Methods

readsPrec :: Int -> ReadS Proxy

readList :: ReadS [Proxy]

readPrec :: ReadPrec Proxy

readListPrec :: ReadPrec [Proxy]

Show Proxy

Defined in Network.HTTP.Client.Types

Methods

showsPrec :: Int -> Proxy -> ShowS

show :: Proxy -> String

showList :: [Proxy] -> ShowS

Eq Proxy

Defined in Network.HTTP.Client.Types

Methods

(==) :: Proxy -> Proxy -> Bool

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

Ord Proxy

Defined in Network.HTTP.Client.Types

Methods

compare :: Proxy -> Proxy -> Ordering

(<) :: Proxy -> Proxy -> Bool

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

(>) :: Proxy -> Proxy -> Bool

(>=) :: Proxy -> Proxy -> Bool

max :: Proxy -> Proxy -> Proxy

min :: Proxy -> Proxy -> Proxy

proxyHost :: Lens' Proxy ByteString

A lens onto the hostname portion of a proxy configuration.

proxyPort :: Lens' Proxy Int

A lens onto the TCP port number of a proxy configuration.

Cookie

data Cookie

Instances

Read Cookie

Defined in Network.HTTP.Client.Types

Methods

readsPrec :: Int -> ReadS Cookie

readList :: ReadS [Cookie]

readPrec :: ReadPrec Cookie

readListPrec :: ReadPrec [Cookie]

Show Cookie

Defined in Network.HTTP.Client.Types

Methods

showsPrec :: Int -> Cookie -> ShowS

show :: Cookie -> String

showList :: [Cookie] -> ShowS

cookieName :: Lens' Cookie ByteString

A lens onto the name of a cookie.

cookieValue :: Lens' Cookie ByteString

A lens onto the value of a cookie.

cookieExpiryTime :: Lens' Cookie UTCTime

A lens onto the expiry time of a cookie.

cookieDomain :: Lens' Cookie ByteString

A lens onto the domain of a cookie.

cookiePath :: Lens' Cookie ByteString

A lens onto the path of a cookie.

cookieCreationTime :: Lens' Cookie UTCTime

A lens onto the creation time of a cookie.

cookieLastAccessTime :: Lens' Cookie UTCTime

A lens onto the last access time of a cookie.

cookiePersistent :: Lens' Cookie Bool

A lens onto whether a cookie is persistent across sessions (also known as a "tracking cookie").

cookieHostOnly :: Lens' Cookie Bool

A lens onto whether a cookie is host-only.

cookieSecureOnly :: Lens' Cookie Bool

A lens onto whether a cookie is secure-only, such that it will only be used over TLS.

cookieHttpOnly :: Lens' Cookie Bool

A lens onto whether a cookie is "HTTP-only".

Such cookies should be used only by browsers when transmitting HTTP requests. They must be unavailable in non-browser environments, such as when executing JavaScript scripts.

Response

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

responseBody :: Lens (Response body0) (Response body1) body0 body1

A lens onto the body of a response.

r <- get "http://httpbin.org/get"
print (r ^. responseBody)
 

responseHeader

Arguments

:: HeaderName

Header name to match.

-> Traversal' (Response body) ByteString

A lens onto all matching named headers in an HTTP response.

To access exactly one header (the result will be the empty string if there is no match), use the (^.) operator.

r <- get "http://httpbin.org/get"
print (r ^. responseHeader "Content-Type")
 

To access at most one header (the result will be Nothing if there is no match), use the (^?) operator.

r <- get "http://httpbin.org/get"
print (r ^? responseHeader "Content-Transfer-Encoding")
 

To access all (zero or more) matching headers, use the (^..) operator.

r <- get "http://httpbin.org/get"
print (r ^.. responseHeader "Set-Cookie")
 

responseLink

Arguments

:: ByteString

Parameter name to match.

-> ByteString

Parameter value to match.

-> Fold (Response body) Link

A fold over Link headers, matching on both parameter name and value.

For example, here is a Link header returned by the GitHub search API.

Link:
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2>; rel="next",
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"

And here is an example of how we can retrieve the URL for the next link programatically.

r <- get "https://api.github.com/search/code?q=addClass+user:mozilla"
print (r ^? responseLink "rel" "next" . linkURL)
 

responseCookie

Arguments

:: ByteString

Name of cookie to match.

-> Fold (Response body) Cookie

A fold over any cookies that match the given name.

r <- get "http://www.nytimes.com/"
print (r ^? responseCookie "RMID")
 

responseHeaders :: Lens' (Response body) ResponseHeaders

A lens onto all headers in an HTTP response.

responseCookieJar :: Lens' (Response body) CookieJar

A lens onto all cookies set in the response.

responseStatus :: Lens' (Response body) Status

A lens onto the status of an HTTP response.

responseVersion :: Lens' (Response body) HttpVersion

A lens onto the version of an HTTP response.

HistoriedResponse

data HistoriedResponse body

A datatype holding information on redirected requests and the final response.

Since 0.4.1

Instances

Foldable HistoriedResponse

Defined in Network.HTTP.Client

Methods

fold :: Monoid m => HistoriedResponse m -> m

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

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

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

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

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

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

foldr1 :: (a -> a -> a) -> HistoriedResponse a -> a

foldl1 :: (a -> a -> a) -> HistoriedResponse a -> a

toList :: HistoriedResponse a -> [a]

null :: HistoriedResponse a -> Bool

length :: HistoriedResponse a -> Int

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

maximum :: Ord a => HistoriedResponse a -> a

minimum :: Ord a => HistoriedResponse a -> a

sum :: Num a => HistoriedResponse a -> a

product :: Num a => HistoriedResponse a -> a

Traversable HistoriedResponse

Defined in Network.HTTP.Client

Methods

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

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

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

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

Functor HistoriedResponse

Defined in Network.HTTP.Client

Methods

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

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

Generic (HistoriedResponse body)

Defined in Network.HTTP.Client

Associated Types

type Rep (HistoriedResponse body) :: Type -> Type

Methods

from :: HistoriedResponse body -> Rep (HistoriedResponse body) x

to :: Rep (HistoriedResponse body) x -> HistoriedResponse body

Show body => Show (HistoriedResponse body)

Defined in Network.HTTP.Client

Methods

showsPrec :: Int -> HistoriedResponse body -> ShowS

show :: HistoriedResponse body -> String

showList :: [HistoriedResponse body] -> ShowS

type Rep (HistoriedResponse body)

Defined in Network.HTTP.Client

type Rep (HistoriedResponse body) = D1 ('MetaData "HistoriedResponse" "Network.HTTP.Client" "http-client-0.7.16-7bSJCDX1PLjCzoDPpwacJf" 'False) (C1 ('MetaCons "HistoriedResponse" 'PrefixI 'True) (S1 ('MetaSel ('Just "hrRedirects") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [(Request, Response ByteString)]) :*: (S1 ('MetaSel ('Just "hrFinalRequest") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Request) :*: S1 ('MetaSel ('Just "hrFinalResponse") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Response body)))))

hrFinalResponse :: Lens' (HistoriedResponse body) (Response body)

A lens onto the final response of a historied response.

hrFinalRequest :: Lens' (HistoriedResponse body) Request

A lens onto the final request of a historied response.

hrRedirects :: Lens' (HistoriedResponse body) [(Request, Response ByteString)]

A lens onto the list of redirects of a historied response.

Status

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

Data Status

Since: http-types-0.12.4

Defined in Network.HTTP.Types.Status

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Status -> c Status

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Status

toConstr :: Status -> Constr

dataTypeOf :: Status -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Status)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Status)

gmapT :: (forall b. Data b => b -> b) -> Status -> Status

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Status -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Status -> r

gmapQ :: (forall d. Data d => d -> u) -> Status -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Status -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Status -> m Status

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Status -> m Status

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Status -> m Status

Bounded Status

Since: http-types-0.11

Defined in Network.HTTP.Types.Status

Methods

minBound :: Status

maxBound :: Status

Enum Status

Be advised, that when using the "enumFrom*" family of methods or ranges in lists, it will generate all possible status codes.

E.g. [status100 .. status200] generates Statuses of 100, 101, 102 .. 198, 199, 200

The statuses not included in this library will have an empty message.

Since: http-types-0.7.3

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]

Generic Status

Defined in Network.HTTP.Types.Status

Associated Types

type Rep Status :: Type -> Type

Methods

from :: Status -> Rep Status x

to :: Rep Status x -> Status

Show Status

Defined in Network.HTTP.Types.Status

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

Eq Status

A Status is equal to another Status if the status codes are equal.

Defined in Network.HTTP.Types.Status

Methods

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

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

Ord Status

Statuses are ordered according to their status codes only.

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

type Rep Status

Since: http-types-0.12.4

Defined in Network.HTTP.Types.Status

type Rep Status = D1 ('MetaData "Status" "Network.HTTP.Types.Status" "http-types-0.12.4-477I0Sk1Sh7Hbo23tdqajU" 'False) (C1 ('MetaCons "Status" 'PrefixI 'True) (S1 ('MetaSel ('Just "statusCode") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Just "statusMessage") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

statusCode :: Lens' Status Int

A lens onto the numeric identifier of an HTTP status.

statusMessage :: Lens' Status ByteString

A lens onto the textual description of an HTTP status.

Link header

data Link

An element of a Link header.

Instances

Show Link

Defined in Network.Wreq.Internal.Types

Methods

showsPrec :: Int -> Link -> ShowS

show :: Link -> String

showList :: [Link] -> ShowS

Eq Link

Defined in Network.Wreq.Internal.Types

Methods

(==) :: Link -> Link -> Bool

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

linkURL :: Lens' Link ByteString

A lens onto the URL portion of a Link element.

linkParams :: Lens' Link [(ByteString, ByteString)]

A lens onto the parameters of a Link element.

POST body part

type Part = PartM IO

partName :: Lens' Part Text

A lens onto the name of the input element associated with part of a multipart form upload.

partFileName :: Lens' Part (Maybe String)

A lens onto the filename associated with part of a multipart form upload.

partContentType :: Traversal' Part (Maybe MimeType)

A lens onto the content-type associated with part of a multipart form upload.

partGetBody :: Lens' Part (IO RequestBody)

A lens onto the code that fetches the data associated with part of a multipart form upload.

Parsing

atto :: Parser a -> Fold ByteString a

Turn an attoparsec Parser into a Fold.

Both headers and bodies can contain complicated data that we may need to parse.

Example: when responding to an OPTIONS request, a server may return the list of verbs it supports in any order, up to and including changing the order on every request (which httpbin.org /actually does/!). To deal with this possibility, we parse the list, then sort it.

>>> import Data.Attoparsec.ByteString.Char8 as A
>>> import Data.List (sort)
>>> 
>>> let comma = skipSpace >> "," >> skipSpace
>>> let verbs = A.takeWhile isAlpha_ascii `sepBy` comma
>>> 
>>> r <- options "http://httpbin.org/get"
>>> r ^. responseHeader "Allow" . atto verbs . to sort
["GET","HEAD","OPTIONS"]

atto_ :: Parser a -> Fold ByteString a

The same as atto, but ensures that the parser consumes the entire input.

Equivalent to:

atto_ myParser = atto (myParser <* endOfInput)