HTTP-4000.2.20: 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 :: 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

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