HTTP-4000.0.9: A library for client-side HTTPSource codeContentsIndex
Network.Browser
Portabilitynon-portable (not tested)
Stabilityexperimental
MaintainerSigbjorn Finne <sigbjorn.finne@gmail.com>
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)
Synopsis
data BrowserState connection
data BrowserAction conn a
data Proxy
= NoProxy
| Proxy String (Maybe Authority)
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 {
auRealm :: String
auUsername :: String
auPassword :: String
auNonce :: String
auAlgorithm :: Maybe Algorithm
auDomain :: [URI]
auOpaque :: Maybe String
auQop :: [Qop]
}
getAuthorities :: BrowserAction t [Authority]
setAuthorities :: [Authority] -> BrowserAction t ()
addAuthority :: Authority -> BrowserAction t ()
data Challenge
= ChalBasic {
chRealm :: String
}
| ChalDigest {
chRealm :: String
chDomain :: [URI]
chNonce :: String
chOpaque :: Maybe String
chStale :: Bool
chAlgorithm :: Maybe Algorithm
chQop :: [Qop]
}
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 {
ckDomain :: String
ckName :: String
ckValue :: String
ckPath :: Maybe String
ckComment :: Maybe String
ckVersion :: Maybe String
}
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 {
browserTimestamp :: ClockTime
browserRequestID :: RequestID
browserRequestURI :: String
browserEventType :: BrowserEventType
}
data BrowserEventType
= OpenConnection
| ReuseConnection
| RequestSent
| ResponseEnd ResponseData
| ResponseFinish
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 Source
BrowserState is the (large) record type tracking the current settings of the browser.
data BrowserAction conn a Source
BrowserAction is the IO monad, but carrying along a BrowserState.
data Proxy Source
HTTP proxies (or not) are represented via Proxy, specifying if a proxy should be used for the request (see Network.Browser.setProxy)
Constructors
NoProxyDon'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 Authority for authentication with the proxy.
browse :: BrowserAction conn a -> IO aSource
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)Source
request httpRequest tries to submit the Request httpRequest to some HTTP server (possibly going via a proxy, see setProxy.) Upon successful delivery, the URL where the response was fetched from is returned along with the Response itself.
getBrowserState :: BrowserAction t (BrowserState t)Source
getBrowserState returns the current browser config. Useful for restoring state across BrowserActions.
withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t aSource
withBrowserAction st act performs act with BrowserState st.
setAllowRedirects :: Bool -> BrowserAction t ()Source
setAllowRedirects onOff toggles the willingness to follow redirects (HTTP responses with 3xx status codes).
getAllowRedirects :: BrowserAction t BoolSource
getAllowRedirects returns current setting of the do-chase-redirects flag.
setMaxRedirects :: Maybe Int -> BrowserAction t ()Source
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)Source
getMaxRedirects returns the current setting for the max-redirect count. If Nothing, the Network.Browser's default is used.
data Authority Source
Authority specifies the HTTP Authentication method to use for a given domain/realm; Basic or Digest.
Constructors
AuthBasic
auRealm :: String
auUsername :: String
auPassword :: String
auSite :: URI
AuthDigest
auRealm :: String
auUsername :: String
auPassword :: String
auNonce :: String
auAlgorithm :: Maybe Algorithm
auDomain :: [URI]
auOpaque :: Maybe String
auQop :: [Qop]
getAuthorities :: BrowserAction t [Authority]Source
getAuthorities return the current set of Authoritys known to the browser.
setAuthorities :: [Authority] -> BrowserAction t ()Source
addAuthority :: Authority -> BrowserAction t ()Source
data Challenge Source
Constructors
ChalBasic
chRealm :: String
ChalDigest
chRealm :: String
chDomain :: [URI]
chNonce :: String
chOpaque :: Maybe String
chStale :: Bool
chAlgorithm :: Maybe Algorithm
chQop :: [Qop]
data Qop Source
Constructors
QopAuth
QopAuthInt
data Algorithm Source
Algorithm controls the digest algorithm to, MD5 or MD5Session.
Constructors
AlgMD5
AlgMD5sess
getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String)))Source
getAuthorityGen returns the current authority generator
setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t ()Source
setAuthorityGen genAct sets the auth generator to genAct.
setAllowBasicAuth :: Bool -> BrowserAction t ()Source
setAllowBasicAuth onOff enables/disables HTTP Basic Authentication.
getAllowBasicAuth :: BrowserAction t BoolSource
setMaxErrorRetries :: Maybe Int -> BrowserAction t ()Source
setMaxErrorRetries mbMax sets the maximum number of attempts at transmitting a request. If Nothing, rever to default max.
getMaxErrorRetries :: BrowserAction t (Maybe Int)Source
getMaxErrorRetries returns the current max number of error retries.
setMaxAuthAttempts :: Maybe Int -> BrowserAction t ()Source
setMaxAuthAttempts mbMax sets the maximum number of authentication attempts to do. If Nothing, rever to default max.
getMaxAuthAttempts :: BrowserAction t (Maybe Int)Source
getMaxAuthAttempts returns the current max auth attempts. If Nothing, the browser's default is used.
setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t ()Source
setCookieFilter fn sets the cookie acceptance filter to fn.
getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool)Source
getCookieFilter returns the current cookie acceptance filter.
defaultCookieFilter :: URI -> Cookie -> IO BoolSource
defaultCookieFilter is the initial cookie acceptance filter. It welcomes them all into the store :-)
userCookieFilter :: URI -> Cookie -> IO BoolSource
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 Source
Cookie is the Haskell representation of HTTP cookie values. See its relevant specs for authoritative details.
Constructors
MkCookie
ckDomain :: String
ckName :: String
ckValue :: String
ckPath :: Maybe String
ckComment :: Maybe String
ckVersion :: Maybe String
getCookies :: BrowserAction t [Cookie]Source
getCookies returns the current set of cookies known to the browser.
setCookies :: [Cookie] -> BrowserAction t ()Source
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 ()Source
addCookie c adds a cookie to the browser state, removing duplicates.
setErrHandler :: (String -> IO ()) -> BrowserAction t ()Source
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 ()Source
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 ()Source
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 Source
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
browserTimestamp :: ClockTime
browserRequestID :: RequestID
browserRequestURI :: String
browserEventType :: BrowserEventType
data BrowserEventType Source
BrowserEventType is the enumerated list of events that the browser internals will report to a user-defined event handler.
Constructors
OpenConnection
ReuseConnection
RequestSent
ResponseEnd ResponseData
ResponseFinish
type RequestID = IntSource
setProxy :: Proxy -> BrowserAction t ()Source
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 ProxySource
getProxy returns the current proxy settings. If the auto-proxy flag is set to True, getProxy will perform the necessary
setCheckForProxy :: Bool -> BrowserAction t ()Source
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 BoolSource
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 ()Source
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 StringSource
getUserAgent returns the current User-Agent: default string.
setUserAgent :: String -> BrowserAction t ()Source
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 ()Source
err :: String -> BrowserAction t ()Source
ioAction :: IO a -> BrowserAction t aSource
Lifts an IO action into the BrowserAction monad.
defaultGETRequest :: URI -> Request_StringSource
defaultGETRequest_ :: BufferType a => URI -> Request aSource
formToRequest :: Form -> Request_StringSource
uriDefaultTo :: URI -> URI -> URISource
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 Source
Constructors
Form RequestMethod URI [FormVar]
type FormVar = (String, String)Source
Produced by Haddock version 2.6.0