Safe Haskell | None |
---|
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 "http://www.myurl.com/login.php" 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 "http://www.myurl.com/main.php" -- 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
- data BrowserState
- type BrowserAction = StateT BrowserState (ResourceT IO)
- browse :: Manager -> BrowserAction a -> ResourceT IO a
- makeRequest :: Request (ResourceT IO) -> BrowserAction (Response (ResumableSource (ResourceT IO) ByteString))
- makeRequestLbs :: Request (ResourceT IO) -> BrowserAction (Response ByteString)
- defaultState :: Manager -> BrowserState
- getBrowserState :: BrowserAction BrowserState
- setBrowserState :: BrowserState -> BrowserAction ()
- withBrowserState :: BrowserState -> BrowserAction a -> BrowserAction a
- getMaxRedirects :: BrowserAction (Maybe Int)
- setMaxRedirects :: Maybe Int -> BrowserAction ()
- withMaxRedirects :: Maybe Int -> BrowserAction a -> BrowserAction a
- getMaxRetryCount :: BrowserAction Int
- setMaxRetryCount :: Int -> BrowserAction ()
- withMaxRetryCount :: Int -> BrowserAction a -> BrowserAction a
- getTimeout :: BrowserAction (Maybe Int)
- setTimeout :: Maybe Int -> BrowserAction ()
- withTimeout :: Maybe Int -> BrowserAction a -> BrowserAction a
- getAuthorities :: BrowserAction (Request (ResourceT IO) -> Maybe (ByteString, ByteString))
- setAuthorities :: (Request (ResourceT IO) -> Maybe (ByteString, ByteString)) -> BrowserAction ()
- withAuthorities :: (Request (ResourceT IO) -> Maybe (ByteString, ByteString)) -> BrowserAction a -> BrowserAction a
- getCookieFilter :: BrowserAction (Request (ResourceT IO) -> Cookie -> IO Bool)
- setCookieFilter :: (Request (ResourceT IO) -> Cookie -> IO Bool) -> BrowserAction ()
- withCookieFilter :: (Request (ResourceT IO) -> Cookie -> IO Bool) -> BrowserAction a -> BrowserAction a
- getCookieJar :: BrowserAction CookieJar
- setCookieJar :: CookieJar -> BrowserAction ()
- withCookieJar :: CookieJar -> BrowserAction a -> BrowserAction a
- getCurrentProxy :: BrowserAction (Maybe Proxy)
- setCurrentProxy :: Maybe Proxy -> BrowserAction ()
- withCurrentProxy :: Maybe Proxy -> BrowserAction a -> BrowserAction a
- getCurrentSocksProxy :: BrowserAction (Maybe SocksConf)
- setCurrentSocksProxy :: Maybe SocksConf -> BrowserAction ()
- withCurrentSocksProxy :: Maybe SocksConf -> BrowserAction a -> BrowserAction a
- getOverrideHeaders :: BrowserAction RequestHeaders
- setOverrideHeaders :: RequestHeaders -> BrowserAction ()
- withOverrideHeaders :: RequestHeaders -> BrowserAction a -> BrowserAction a
- insertOverrideHeader :: Header -> BrowserAction ()
- deleteOverrideHeader :: HeaderName -> BrowserAction ()
- withOverrideHeader :: Header -> BrowserAction a -> BrowserAction a
- getUserAgent :: BrowserAction (Maybe ByteString)
- setUserAgent :: Maybe ByteString -> BrowserAction ()
- withUserAgent :: Maybe ByteString -> BrowserAction () -> BrowserAction ()
- getCheckStatus :: BrowserAction (Maybe (Status -> ResponseHeaders -> Maybe SomeException))
- setCheckStatus :: Maybe (Status -> ResponseHeaders -> Maybe SomeException) -> BrowserAction ()
- withCheckStatus :: Maybe (Status -> ResponseHeaders -> Maybe SomeException) -> BrowserAction a -> BrowserAction a
- getManager :: BrowserAction Manager
- setManager :: Manager -> BrowserAction ()
Documentation
data BrowserState Source
type BrowserAction = StateT BrowserState (ResourceT IO)Source
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
withBrowserState :: BrowserState -> BrowserAction a -> BrowserAction aSource
getMaxRedirects :: BrowserAction (Maybe Int)Source
The number of redirects to allow.
if Nothing uses Request's redirectCount
setMaxRedirects :: Maybe Int -> BrowserAction ()Source
withMaxRedirects :: Maybe Int -> BrowserAction a -> BrowserAction aSource
getMaxRetryCount :: BrowserAction IntSource
The number of times to retry a failed connection
setMaxRetryCount :: Int -> BrowserAction ()Source
withMaxRetryCount :: Int -> BrowserAction a -> BrowserAction aSource
getTimeout :: BrowserAction (Maybe Int)Source
Number of microseconds to wait for a response.
if Nothing uses Request's responseTimeout
setTimeout :: Maybe Int -> BrowserAction ()Source
withTimeout :: Maybe Int -> BrowserAction a -> BrowserAction aSource
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.
setAuthorities :: (Request (ResourceT IO) -> Maybe (ByteString, ByteString)) -> BrowserAction ()Source
withAuthorities :: (Request (ResourceT IO) -> Maybe (ByteString, ByteString)) -> BrowserAction a -> BrowserAction aSource
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
setCookieFilter :: (Request (ResourceT IO) -> Cookie -> IO Bool) -> BrowserAction ()Source
withCookieFilter :: (Request (ResourceT IO) -> Cookie -> IO Bool) -> BrowserAction a -> BrowserAction aSource
getCookieJar :: BrowserAction CookieJarSource
All the cookies!
setCookieJar :: CookieJar -> BrowserAction ()Source
withCookieJar :: CookieJar -> BrowserAction a -> BrowserAction aSource
getCurrentProxy :: BrowserAction (Maybe Proxy)Source
An optional proxy to send all requests through
if Nothing uses Request's proxy
setCurrentProxy :: Maybe Proxy -> BrowserAction ()Source
withCurrentProxy :: Maybe Proxy -> BrowserAction a -> BrowserAction aSource
getCurrentSocksProxy :: BrowserAction (Maybe SocksConf)Source
An optional SOCKS proxy to send all requests through
if Nothing uses Request's socksProxy
withCurrentSocksProxy :: Maybe SocksConf -> BrowserAction a -> BrowserAction aSource
getOverrideHeaders :: BrowserAction RequestHeadersSource
Specifies Headers that should be added to Request
,
these will override Headers already specified in requestHeaders
.
do insertOverrideHeader ("User-Agent", "http-conduit") insertOverrideHeader ("Connection", "keep-alive") makeRequest def{requestHeaders = [("User-Agent", "another agent"), ("Accept", "everything/digestible")]} > User-Agent: http-conduit > Accept: everything/digestible > Connection: keep-alive
withOverrideHeader :: Header -> BrowserAction a -> BrowserAction aSource
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)
setUserAgent :: Maybe ByteString -> BrowserAction ()Source
withUserAgent :: Maybe ByteString -> BrowserAction () -> BrowserAction ()Source
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
setCheckStatus :: Maybe (Status -> ResponseHeaders -> Maybe SomeException) -> BrowserAction ()Source
withCheckStatus :: Maybe (Status -> ResponseHeaders -> Maybe SomeException) -> BrowserAction a -> BrowserAction aSource
getManager :: BrowserAction ManagerSource
The active manager, managing the connection pool
setManager :: Manager -> BrowserAction ()Source