| Portability | non-portable (not tested) | 
|---|---|
| Stability | experimental | 
| Maintainer | Sigbjorn Finne <sigbjorn.finne@gmail.com> | 
Network.Browser
Description
Session-level interactions over HTTP.
The Network.Browser goes beyond the basic Network.HTTP functionality in providing support for more involved, and real, request/response interactions over HTTP. Additional features supported are:
- HTTP Authentication handling
- Transparent handling of redirects
- Cookie stores + transmission.
- Transaction logging
- Proxy-mediated connections.
Example use:
    do 
      rsp <- Network.Browser.browse $ do
               setAllowRedirects True -- handle HTTP redirects
               request $ getRequest "http://google.com/"
      fmap (take 100) (getResponseBody rsp)
- data BrowserState connection
- data BrowserAction conn a
- data Proxy
- browse :: BrowserAction conn a -> IO a
- request :: HStream ty => Request ty -> BrowserAction (HandleStream ty) (URI, Response ty)
- getBrowserState :: BrowserAction t (BrowserState t)
- withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t a
- setAllowRedirects :: Bool -> BrowserAction t ()
- getAllowRedirects :: BrowserAction t Bool
- setMaxRedirects :: Maybe Int -> BrowserAction t ()
- getMaxRedirects :: BrowserAction t (Maybe Int)
- data  Authority - = AuthBasic { - auRealm :: String
- auUsername :: String
- auPassword :: String
- auSite :: URI
 
- | AuthDigest { }
 
- = AuthBasic { 
- getAuthorities :: BrowserAction t [Authority]
- setAuthorities :: [Authority] -> BrowserAction t ()
- addAuthority :: Authority -> BrowserAction t ()
- data Challenge
- data  Qop - = QopAuth
- | QopAuthInt
 
- data  Algorithm - = AlgMD5
- | AlgMD5sess
 
- getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String)))
- setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t ()
- setAllowBasicAuth :: Bool -> BrowserAction t ()
- getAllowBasicAuth :: BrowserAction t Bool
- setMaxErrorRetries :: Maybe Int -> BrowserAction t ()
- getMaxErrorRetries :: BrowserAction t (Maybe Int)
- setMaxAuthAttempts :: Maybe Int -> BrowserAction t ()
- getMaxAuthAttempts :: BrowserAction t (Maybe Int)
- setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t ()
- getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool)
- defaultCookieFilter :: URI -> Cookie -> IO Bool
- userCookieFilter :: URI -> Cookie -> IO Bool
- data Cookie = MkCookie {}
- getCookies :: BrowserAction t [Cookie]
- setCookies :: [Cookie] -> BrowserAction t ()
- addCookie :: Cookie -> BrowserAction t ()
- setErrHandler :: (String -> IO ()) -> BrowserAction t ()
- setOutHandler :: (String -> IO ()) -> BrowserAction t ()
- setEventHandler :: Maybe (BrowserEvent -> BrowserAction ty ()) -> BrowserAction ty ()
- data BrowserEvent = BrowserEvent {}
- data BrowserEventType
- type RequestID = Int
- setProxy :: Proxy -> BrowserAction t ()
- getProxy :: BrowserAction t Proxy
- setCheckForProxy :: Bool -> BrowserAction t ()
- getCheckForProxy :: BrowserAction t Bool
- setDebugLog :: Maybe String -> BrowserAction t ()
- getUserAgent :: BrowserAction t String
- setUserAgent :: String -> BrowserAction t ()
- out :: String -> BrowserAction t ()
- err :: String -> BrowserAction t ()
- ioAction :: IO a -> BrowserAction t a
- defaultGETRequest :: URI -> Request_String
- defaultGETRequest_ :: BufferType a => URI -> Request a
- formToRequest :: Form -> Request_String
- uriDefaultTo :: URI -> URI -> URI
- data Form = Form RequestMethod URI [FormVar]
- type FormVar = (String, String)
Documentation
data BrowserState connection
BrowserState is the (large) record type tracking the current
 settings of the browser.
Instances
| Show (BrowserState t) | 
data BrowserAction conn a
BrowserAction is the IO monad, but carrying along a BrowserState.
Instances
| Monad (BrowserAction conn) | |
| Functor (BrowserAction conn) | 
data Proxy
HTTP proxies (or not) are represented via Proxy, specifying if a
 proxy should be used for the request (see Network.Browser.setProxy)
Constructors
| NoProxy | Don't use a proxy. | 
| Proxy String (Maybe Authority) | Use the proxy given. Should be of the
 form http://host:port, host, host:port, or http://host.
 Additionally, an optional  | 
browse :: BrowserAction conn a -> IO a
browse act is the toplevel action to perform a BrowserAction.
 Example use: browse (request (getRequest yourURL)).
request :: HStream ty => Request ty -> BrowserAction (HandleStream ty) (URI, Response ty)
getBrowserState :: BrowserAction t (BrowserState t)
getBrowserState returns the current browser config. Useful
 for restoring state across BrowserActions.
withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t a
withBrowserAction st act performs act with BrowserState st.
setAllowRedirects :: Bool -> BrowserAction t ()
setAllowRedirects onOff toggles the willingness to
 follow redirects (HTTP responses with 3xx status codes).
getAllowRedirects :: BrowserAction t Bool
getAllowRedirects returns current setting of the do-chase-redirects flag.
setMaxRedirects :: Maybe Int -> BrowserAction t ()
setMaxRedirects maxCount sets the maxiumum number of forwarding hops
 we are willing to jump through. A no-op if the count is negative; if zero,
 the max is set to whatever default applies. Notice that setting the max
 redirects count does not enable following of redirects itself; use
 setAllowRedirects to do so.
getMaxRedirects :: BrowserAction t (Maybe Int)
getMaxRedirects returns the current setting for the max-redirect count.
 If Nothing, the Network.Browser's default is used.
data Authority
Authority specifies the HTTP Authentication method to use for
 a given domain/realm; Basic or Digest.
Constructors
| AuthBasic | |
| Fields 
 | |
| AuthDigest | |
getAuthorities :: BrowserAction t [Authority]
getAuthorities return the current set of Authoritys known
 to the browser.
setAuthorities :: [Authority] -> BrowserAction t ()
addAuthority :: Authority -> BrowserAction t ()
data Challenge
data Algorithm
Algorithm controls the digest algorithm to, MD5 or MD5Session.
Constructors
| AlgMD5 | |
| AlgMD5sess | 
getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String)))
getAuthorityGen returns the current authority generator
setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t ()
setAuthorityGen genAct sets the auth generator to genAct.
setAllowBasicAuth :: Bool -> BrowserAction t ()
setAllowBasicAuth onOff enables/disables HTTP Basic Authentication.
setMaxErrorRetries :: Maybe Int -> BrowserAction t ()
setMaxErrorRetries mbMax sets the maximum number of attempts at
 transmitting a request. If Nothing, rever to default max.
getMaxErrorRetries :: BrowserAction t (Maybe Int)
getMaxErrorRetries returns the current max number of error retries.
setMaxAuthAttempts :: Maybe Int -> BrowserAction t ()
setMaxAuthAttempts mbMax sets the maximum number of authentication attempts
 to do. If Nothing, rever to default max.
getMaxAuthAttempts :: BrowserAction t (Maybe Int)
getMaxAuthAttempts returns the current max auth attempts. If Nothing,
 the browser's default is used.
setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t ()
setCookieFilter fn sets the cookie acceptance filter to fn.
getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool)
getCookieFilter returns the current cookie acceptance filter.
defaultCookieFilter :: URI -> Cookie -> IO Bool
defaultCookieFilter is the initial cookie acceptance filter.
 It welcomes them all into the store :-)
userCookieFilter :: URI -> Cookie -> IO Bool
userCookieFilter is a handy acceptance filter, asking the
 user if he/she is willing to accept an incoming cookie before
 adding it to the store.
data Cookie
Cookie is the Haskell representation of HTTP cookie values.
 See its relevant specs for authoritative details.
Constructors
| MkCookie | |
getCookies :: BrowserAction t [Cookie]
getCookies returns the current set of cookies known to
 the browser.
setCookies :: [Cookie] -> BrowserAction t ()
setCookies cookies replaces the set of cookies known to
 the browser to cookies. Useful when wanting to restore cookies
 used across browse invocations.
addCookie :: Cookie -> BrowserAction t ()
addCookie c adds a cookie to the browser state, removing duplicates.
setErrHandler :: (String -> IO ()) -> BrowserAction t ()
setErrHandler sets the IO action to call when
 the browser reports running errors. To disable any
 such, set it to const (return ()).
setOutHandler :: (String -> IO ()) -> BrowserAction t ()
setErrHandler sets the IO action to call when
 the browser chatters info on its running. To disable any
 such, set it to const (return ()).
setEventHandler :: Maybe (BrowserEvent -> BrowserAction ty ()) -> BrowserAction ty ()
setEventHandler onBrowserEvent configures event handling.
 If onBrowserEvent is Nothing, event handling is turned off;
 setting it to Just onEv causes the onEv IO action to be
 notified of browser events during the processing of a request
 by the Browser pipeline.
data BrowserEvent
BrowserEvent is the event record type that a user-defined handler, set
 via setEventHandler, will be passed. It indicates various state changes
 encountered in the processing of a given RequestID, along with timestamps
 at which they occurred.
Constructors
| BrowserEvent | |
data BrowserEventType
BrowserEventType is the enumerated list of events that the browser
 internals will report to a user-defined event handler.
setProxy :: Proxy -> BrowserAction t ()
setProxy p will disable proxy usage if p is NoProxy.
 If p is Proxy proxyURL mbAuth, then proxyURL is interpreted
 as the URL of the proxy to use, possibly authenticating via 
 Authority information in mbAuth.
getProxy :: BrowserAction t Proxy
getProxy returns the current proxy settings. If
 the auto-proxy flag is set to True, getProxy will
 perform the necessary 
setCheckForProxy :: Bool -> BrowserAction t ()
setCheckForProxy flg sets the one-time check for proxy
 flag to flg. If True, the session will try to determine
 the proxy server is locally configured. See fetchProxy
 for details of how this done.
getCheckForProxy :: BrowserAction t Bool
getCheckForProxy returns the current check-proxy setting.
 Notice that this may not be equal to True if the session has
 set it to that via setCheckForProxy and subsequently performed
 some HTTP protocol interactions. i.e., the flag return represents
 whether a proxy will be checked for again before any future protocol
 interactions.
setDebugLog :: Maybe String -> BrowserAction t ()
setDebugLog mbFile turns off debug logging iff mbFile
 is Nothing. If set to Just fStem, logs of browser activity
 is appended to files of the form fStem-url-authority, i.e.,
 fStem is just the prefix for a set of log files, one per host/authority.
getUserAgent :: BrowserAction t String
getUserAgent returns the current User-Agent: default string.
setUserAgent :: String -> BrowserAction t ()
setUserAgent ua sets the current User-Agent: string to ua. It
 will be used if no explicit user agent header is found in subsequent requests.
out :: String -> BrowserAction t ()
err :: String -> BrowserAction t ()
ioAction :: IO a -> BrowserAction t a
Lifts an IO action into the BrowserAction monad.
defaultGETRequest_ :: BufferType a => URI -> Request a
formToRequest :: Form -> Request_String
uriDefaultTo :: URI -> URI -> URI
uriDefaultTo a b returns a URI that is consistent with the first
 argument URI a when read in the context of the second URI b.
 If the second argument is not sufficient context for determining
 a full URI then anarchy reins.
data Form
Constructors
| Form RequestMethod URI [FormVar] |