Network.Browser

HTTP-4000.3.7: A library for client-side HTTP

Copyright | See LICENSE file
License | BSD
Maintainer | Ganesh Sittampalam <ganesh@earth.li>
Stability | experimental
Portability | non-portable (not tested)
Safe Haskell | None
Language | Haskell98

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://www.haskell.org/"
         return (take 100 (rspBody 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)
- setMaxPoolSize :: Maybe Int -> BrowserAction t ()
- getMaxPoolSize :: 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 :: UTCTime
  - 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 #

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

Instances

Show (BrowserState t) # |
Methods showsPrec :: Int -> BrowserState t -> ShowS # show :: BrowserState t -> String # showList :: [BrowserState t] -> ShowS #
MonadState (BrowserState conn) (BrowserAction conn) # |
Methods get :: BrowserAction conn (BrowserState conn) # put :: BrowserState conn -> BrowserAction conn () # state :: (BrowserState conn -> (a, BrowserState conn)) -> BrowserAction conn a #

data BrowserAction conn a #

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

Instances

Monad (BrowserAction conn) # |
Methods (>>=) :: BrowserAction conn a -> (a -> BrowserAction conn b) -> BrowserAction conn b # (>>) :: BrowserAction conn a -> BrowserAction conn b -> BrowserAction conn b # return :: a -> BrowserAction conn a # fail :: String -> BrowserAction conn a #
Functor (BrowserAction conn) # |
Methods fmap :: (a -> b) -> BrowserAction conn a -> BrowserAction conn b # (<$) :: a -> BrowserAction conn b -> BrowserAction conn a #
Applicative (BrowserAction conn) # |
Methods pure :: a -> BrowserAction conn a # (<*>) :: BrowserAction conn (a -> b) -> BrowserAction conn a -> BrowserAction conn b # liftA2 :: (a -> b -> c) -> BrowserAction conn a -> BrowserAction conn b -> BrowserAction conn c # (*>) :: BrowserAction conn a -> BrowserAction conn b -> BrowserAction conn b # (<*) :: BrowserAction conn a -> BrowserAction conn b -> BrowserAction conn a #
MonadIO (BrowserAction conn) # |
Methods liftIO :: IO a -> BrowserAction conn a #
MonadState (BrowserState conn) (BrowserAction conn) # |
Methods get :: BrowserAction conn (BrowserState conn) # put :: BrowserState conn -> BrowserAction conn () # state :: (BrowserState conn -> (a, BrowserState conn)) -> BrowserAction conn a #

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

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 `Authority`s 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 # |
Methods (==) :: Qop -> Qop -> Bool # (/=) :: Qop -> Qop -> Bool #
Show Qop # |
Methods showsPrec :: Int -> Qop -> ShowS # show :: Qop -> String # showList :: [Qop] -> ShowS #

data Algorithm #

`Algorithm` controls the digest algorithm to, `MD5` or `MD5Session`.

Constructors

AlgMD5 |
AlgMD5sess |

Instances

Eq Algorithm # |
Methods (==) :: Algorithm -> Algorithm -> Bool # (/=) :: Algorithm -> Algorithm -> Bool #
Show Algorithm # |
Methods showsPrec :: Int -> Algorithm -> ShowS # show :: Algorithm -> String # showList :: [Algorithm] -> ShowS #

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 # |
Methods (==) :: Cookie -> Cookie -> Bool # (/=) :: Cookie -> Cookie -> Bool #
Read Cookie # |
Methods readsPrec :: Int -> ReadS Cookie # readList :: ReadS [Cookie] # readPrec :: ReadPrec Cookie # readListPrec :: ReadPrec [Cookie] #
Show Cookie # |
Methods showsPrec :: Int -> Cookie -> ShowS # show :: Cookie -> String # showList :: [Cookie] -> ShowS #

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 :: UTCTime 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) #