Network.Browser

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://www.haskell.org/"
     return (take 100 (rspBody rsp))

Documentation

data BrowserState connection

BrowserState is the (large) record type tracking the current settings of the browser.

Instances

Show (BrowserState t)

MonadState (BrowserState conn) (BrowserAction conn)

data BrowserAction conn a

BrowserAction is the IO monad, but carrying along a BrowserState.

Instances

Monad (BrowserAction conn)

Functor (BrowserAction conn)

Applicative (BrowserAction conn)

MonadIO (BrowserAction conn)

MonadState (BrowserState conn) (BrowserAction conn)

data Proxy

HTTP proxies (or not) are represented via Proxy, specifying if a proxy should be used for the request (see 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 Authority for authentication with the proxy.

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)

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)

Deprecated: Use Control.Monad.State.get instead.

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

auRealm :: String

auUsername :: String

auPassword :: String

auSite :: URI

AuthDigest

Fields

auRealm :: String

auUsername :: String

auPassword :: String

auNonce :: String

auAlgorithm :: Maybe Algorithm

auDomain :: [URI]

auOpaque :: Maybe String

auQop :: [Qop]

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

Constructors

ChalBasic

Fields

chRealm :: String

ChalDigest

Fields

chRealm :: String

chDomain :: [URI]

chNonce :: String

chOpaque :: Maybe String

chStale :: Bool

chAlgorithm :: Maybe Algorithm

chQop :: [Qop]

data Qop

Constructors

QopAuth

QopAuthInt

Instances

Eq Qop

Show Qop

data Algorithm

Algorithm controls the digest algorithm to, MD5 or MD5Session.

Constructors

AlgMD5

AlgMD5sess

Instances

Eq Algorithm

Show Algorithm

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.

getAllowBasicAuth :: BrowserAction t Bool

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.

setMaxPoolSize :: Maybe Int -> BrowserAction t ()

setMaxPoolSize maxCount sets the maximum size of the connection pool that is used to cache connections between requests

getMaxPoolSize :: BrowserAction t (Maybe Int)

getMaxPoolSize gets the maximum size of the connection pool that is used to cache connections between requests. If Nothing, the Network.Browser's default is used.

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

Fields

ckDomain :: String

ckName :: String

ckValue :: String

ckPath :: Maybe String

ckComment :: Maybe String

ckVersion :: Maybe String

Instances

Eq Cookie

Read Cookie

Show Cookie

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 ()

setOutHandler 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

Fields

browserTimestamp :: ClockTime

browserRequestID :: RequestID

browserRequestURI :: String

browserEventType :: BrowserEventType

data BrowserEventType

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 = Int

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.

A common form of user agent string is "name/version (details)". For example "cabal-install/0.10.2 (HTTP 4000.1.2)". Including the version of this HTTP package can be helpful if you ever need to track down HTTP compatability quirks. This version is available via httpPackageVersion. For more info see http://en.wikipedia.org/wiki/User_agent.

out :: String -> BrowserAction t ()

err :: String -> BrowserAction t ()

ioAction :: IO a -> BrowserAction t a

Deprecated: Use Control.Monad.Trans.liftIO instead.

Lifts an IO action into the BrowserAction monad.

defaultGETRequest :: URI -> Request_String

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]

type FormVar = (String, String)