http-conduit-browser-1.6.5: Browser interface to the http-conduit package

Safe HaskellNone



This module is designed to work similarly to the Network.Browser module in the HTTP package. The idea is that there are two new types defined: BrowserState and BrowserAction. The purpose of this module is to make it easy to describe a browsing session, including navigating to multiple pages, and have things like cookie jar updates work as expected as you browse around.

BrowserAction is a monad that handles all your browser-related activities. This monad is actually implemented as a specialization of the State monad, over the BrowserState type. The BrowserState type has various bits of information that a web browser keeps, such as a current cookie jar, the number of times to retry a request on failure, HTTP proxy information, etc. In the BrowserAction monad, there is one BrowserState at any given time, and you can modify it by using the convenience functions in this module.

A special kind of modification of the current browser state is the action of making a HTTP request. This will do the request according to the params in the current BrowserState, as well as modifying the current state with, for example, an updated cookie jar.

To use this module, you would bind together a series of BrowserActions (This simulates the user clicking on links or using a settings dialogue etc.) to describe your browsing session. When you've described your session, you call browse on your top-level BrowserAction to actually convert your actions into the ResourceT IO monad.

Note that the module will be renamed to Network.HTTP.Conduit.Browser a month or so after release. This is to give users migration time without name clashes.

Here is an example program:

 import qualified Data.ByteString as B
 import qualified Data.ByteString.Lazy as LB
 import qualified Data.ByteString.UTF8 as UB
 import           Data.Conduit
 import           Network.HTTP.Conduit
 import           Network.HTTP.Conduit.Browser
 -- The web request to log in to a service
 req1 :: IO (Request (ResourceT IO))
 req1 = do
   req <- parseUrl ""
   return $ urlEncodedBody [ (UB.fromString "name", UB.fromString "litherum")
                           , (UB.fromString "pass", UB.fromString "S33kRe7")
                           ] req
 -- Once authenticated, run this request
 req2 :: IO (Request m')
 req2 = parseUrl ""
 -- Bind two BrowserActions together
 action :: Request (ResourceT IO) -> Request (ResourceT IO) -> BrowserAction (Response LB.ByteString)
 action r1 r2 = do
   _ <- makeRequestLbs r1
   makeRequestLbs r2
 main :: IO ()
 main = do
   man <- newManager def
   r1 <- req1
   r2 <- req2
   out <- runResourceT $ browse man $ action r1 r2
   putStrLn $ UB.toString $ B.concat $ LB.toChunks $ responseBody out



browse :: Manager -> BrowserAction a -> ResourceT IO aSource

Do the browser action with the given manager

makeRequest :: Request (ResourceT IO) -> BrowserAction (Response (ResumableSource (ResourceT IO) ByteString))Source

Make a request, using all the state in the current BrowserState

getBrowserState :: BrowserAction BrowserStateSource

You can save and restore the state at will

getMaxRedirects :: BrowserAction (Maybe Int)Source

The number of redirects to allow. if Nothing uses Request's redirectCount default: Nothing

getMaxRetryCount :: BrowserAction IntSource

The number of times to retry a failed connection default: 0

getTimeout :: BrowserAction (Maybe Int)Source

Number of microseconds to wait for a response. if Nothing uses Request's responseTimeout default: Nothing

getAuthorities :: BrowserAction (Request (ResourceT IO) -> Maybe (ByteString, ByteString))Source

A user-provided function that provides optional authorities. This function gets run on all requests before they get sent out. The output of this function is applied to the request. default: const Nothing

getCookieFilter :: BrowserAction (Request (ResourceT IO) -> Cookie -> IO Bool)Source

Each new Set-Cookie the browser encounters will pass through this filter. Only cookies that pass the filter (and are already valid) will be allowed into the cookie jar default: const $ const $ return True

getCurrentProxy :: BrowserAction (Maybe Proxy)Source

An optional proxy to send all requests through if Nothing uses Request's proxy default: Nothing

getCurrentSocksProxy :: BrowserAction (Maybe SocksConf)Source

An optional SOCKS proxy to send all requests through if Nothing uses Request's socksProxy default: Nothing

getOverrideHeaders :: BrowserAction RequestHeadersSource

Specifies Headers that should be added to Request, these will override Headers already specified in requestHeaders.

 do insertOverrideHeader ("User-Agent", "rat")
    insertOverrideHeader ("Connection", "keep-alive")
    makeRequest def{requestHeaders = [("User-Agent", "kitten"), ("Accept", "everything/digestible")]}
 > User-Agent: rat
 > Accept: everything/digestible
 > Connection: keep-alive

getUserAgent :: BrowserAction (Maybe ByteString)Source

What string to report our user-agent as. if Nothing will not send user-agent unless one is specified in Request

 getUserAgent = lookup hUserAgent overrideHeaders
 setUserAgent a = insertOverrideHeader (hUserAgent, a)

default: Just http-conduit

getCheckStatus :: BrowserAction (Maybe (Status -> ResponseHeaders -> Maybe SomeException))Source

Function to check the status code. Note that this will run after all redirects are performed. if Nothing uses Request's checkStatus default: Nothing

getManager :: BrowserAction ManagerSource

The active manager, managing the connection pool