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)

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 ()
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 ty -> BrowserAction ty ()) -> BrowserAction ty ()
data BrowserEvent ty = BrowserEvent {
- browserTimestamp :: ClockTime
- browserRequestID :: RequestID
- browserRequestURI :: String
- browserEventType :: BrowserEventType ty
}
data BrowserEventType ty
- = OpenConnection
- | ReuseConnection
- | RequestSent
- | ResponseEnd ResponseData
- | ResponseFinish
type RequestID = Int
setProxy :: Proxy -> BrowserAction t ()
getProxy :: BrowserAction t Proxy
setDebugLog :: Maybe 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.

Instances

Show (BrowserState t)

data BrowserAction conn a Source

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

Instances

Monad (BrowserAction conn)

Functor (BrowserAction conn)

data Proxy Source

Proxy specifies if a proxy should be used for the request.

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. Optional Authority to authenticate with the proxy as.

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 BrowserAction s.

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 Bool Source

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

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]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

Fields

chRealm :: String

ChalDigest

Fields

chRealm :: String
chDomain :: [URI]
chNonce :: String
chOpaque :: Maybe String
chStale :: Bool
chAlgorithm :: Maybe Algorithm
chQop :: [Qop]

data Qop Source

Constructors

QopAuth

QopAuthInt

Instances

Eq Qop

Show Qop

data Algorithm Source

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

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 Bool Source

defaultCookieFilter is the initial cookie acceptance filter. It welcomes them all into the store :-)

userCookieFilter :: URI -> Cookie -> IO Bool Source

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

Fields

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 ty -> 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 ty 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

Fields

browserTimestamp :: ClockTime
browserRequestID :: RequestID
browserRequestURI :: String
browserEventType :: BrowserEventType ty

data BrowserEventType ty 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 = Int Source

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 Proxy Source

getProxy returns the current proxy settings.

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.

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_String Source

defaultGETRequest_ :: BufferType a => URI -> Request aSource

formToRequest :: Form -> Request_String Source

uriDefaultTo :: URI -> URI -> URI Source

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