-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A library for writing HTTP and HTTPS proxies
--   
--   http-proxy is a library for writing HTTP and HTTPS proxies.
--   
--   Use of the Conduit library provides file streaming via the proxy in
--   both directions. Memory usage of the proxy scales linearly with the
--   number of simultaneous connections and is independent of the size of
--   the files being uploaded or downloaded.
--   
--   The Settings data type provided by the library allows the caller to
--   supply a functions for exception reporting and request re-writing.
--   Eventually, this capability will be expanded to allow optional
--   logging, disk caching etc.
@package http-proxy
@version 0.1.0.3


-- | This module contains a simple HTTP and HTTPS proxy. In the most basic
--   setup, the caller specifies a port and runs it as follows:
--   
--   <pre>
--   -- Run a HTTPS and HTTPS proxy on port 3128.
--   import Network.HTTP.Proxy
--   
--   main :: IO ()
--   main = runProxy 3128
--   </pre>
module Network.HTTP.Proxy
type Port = Int
data Request
Request :: Method -> HttpVersion -> RequestHeaders -> ByteString -> ByteString -> Request

-- | Request method such as GET.
[requestMethod] :: Request -> Method

-- | HTTP version such as 1.1.
[httpVersion] :: Request -> HttpVersion

-- | A list of header (a pair of key and value) in an HTTP request.
[requestHeaders] :: Request -> RequestHeaders

-- | The part of the URL before the query part.
[requestPath] :: Request -> ByteString

-- | Parsed query string information
[queryString] :: Request -> ByteString

-- | Various proxy server settings. This is purposely kept as an abstract
--   data type so that new settings can be added without breaking backwards
--   compatibility. In order to create a <a>Settings</a> value, use
--   <a>defaultProxySettings</a> and record syntax to modify individual
--   records. For example:
--   
--   <pre>
--   defaultProxySettings { proxyPort = 3128 }
--   </pre>
data Settings
Settings :: Int -> HostPreference -> (SomeException -> Response) -> Int -> (Request -> IO (Either Response Request)) -> (ByteString -> IO ()) -> Maybe UpstreamProxy -> Settings

-- | Port to listen on. Default value: 3100
[proxyPort] :: Settings -> Int

-- | Default value: HostIPv4
[proxyHost] :: Settings -> HostPreference

-- | What to do with exceptions thrown by either the application or server.
--   Default: ignore server-generated exceptions (see
--   <tt>InvalidRequest</tt>) and print application-generated applications
--   to stderr.
[proxyOnException] :: Settings -> SomeException -> Response

-- | Timeout value in seconds. Default value: 30
[proxyTimeout] :: Settings -> Int

-- | A function that allows the the request to be modified before being
--   run. Default: 'return . Right'.
[proxyRequestModifier] :: Settings -> Request -> IO (Either Response Request)

-- | A function for logging proxy internal state. Default: 'return ()'.
[proxyLogger] :: Settings -> ByteString -> IO ()

-- | Optional upstream proxy.
[proxyUpstream] :: Settings -> Maybe UpstreamProxy

-- | A http-proxy can be configured to use and upstream proxy by providing
--   the proxy name, the port it listens to and an option username and
--   password for proxy authorisation.
data UpstreamProxy
UpstreamProxy :: ByteString -> Int -> Maybe (ByteString, ByteString) -> UpstreamProxy

-- | The upstream proxy's hostname.
[upstreamHost] :: UpstreamProxy -> ByteString

-- | The upstream proxy's port number.
[upstreamPort] :: UpstreamProxy -> Int

-- | Optional username and password to use with upstream proxy.
[upstreamAuth] :: UpstreamProxy -> Maybe (ByteString, ByteString)

-- | Run a HTTP and HTTPS proxy server on the specified port. This calls
--   <a>runProxySettings</a> with <a>defaultProxySettings</a>.
runProxy :: Port -> IO ()

-- | Run a HTTP and HTTPS proxy server with the specified settings.
runProxySettings :: Settings -> IO ()

-- | Run a HTTP and HTTPS proxy server with the specified settings but
--   provide it with a Socket to accept connections on. The Socket should
--   have already have had <a>bind</a> and <a>listen</a> called on it so
--   that the proxy can simple <a>accept</a> connections.
runProxySettingsSocket :: Settings -> Socket -> IO ()

-- | The default settings for the Proxy server. See the individual settings
--   for the default value.
defaultProxySettings :: Settings