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


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

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

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

-- | 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>defaultSettings</a> and record syntax to modify individual records.
--   For example:
--   
--   <pre>
--   defaultSettings { proxyPort = 3128 }
--   </pre>
data Settings
Settings :: Int -> HostPreference -> (SomeException -> IO ()) -> Int -> (Request -> IO 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
--   <a>InvalidRequest</a>) and print application-generated applications to
--   stderr.
proxyOnException :: Settings -> SomeException -> IO ()

-- | 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 . id'.
proxyRequestModifier :: Settings -> Request -> IO Request

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

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

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

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

-- | Information on the request sent by the client. This abstracts away the
--   details of the underlying implementation.
data Request :: *
Request :: Method -> HttpVersion -> ByteString -> ByteString -> ByteString -> Int -> RequestHeaders -> Bool -> SockAddr -> [Text] -> Query -> Source (ResourceT IO) ByteString -> Vault -> Request
requestMethod :: Request -> Method
httpVersion :: Request -> HttpVersion

-- | Extra path information sent by the client. The meaning varies slightly
--   depending on backend; in a standalone server setting, this is most
--   likely all information after the domain name. In a CGI application,
--   this would be the information following the path to the CGI executable
--   itself. Do not modify this raw value- modify pathInfo instead.
rawPathInfo :: Request -> ByteString

-- | If no query string was specified, this should be empty. This value
--   <i>will</i> include the leading question mark. Do not modify this raw
--   value- modify queryString instead.
rawQueryString :: Request -> ByteString

-- | Generally the host requested by the user via the Host request header.
--   Backends are free to provide alternative values as necessary. This
--   value should not be used to construct URLs.
serverName :: Request -> ByteString

-- | The listening port that the server received this request on. It is
--   possible for a server to listen on a non-numeric port (i.e., Unix
--   named socket), in which case this value will be arbitrary. Like
--   <a>serverName</a>, this value should not be used in URL construction.
serverPort :: Request -> Int
requestHeaders :: Request -> RequestHeaders

-- | Was this request made over an SSL connection?
isSecure :: Request -> Bool

-- | The client's host information.
remoteHost :: Request -> SockAddr

-- | Path info in individual pieces- the url without a hostname/port and
--   without a query string, split on forward slashes,
pathInfo :: Request -> [Text]

-- | Parsed query string information
queryString :: Request -> Query
requestBody :: Request -> Source (ResourceT IO) ByteString

-- | A location for arbitrary data to be shared by applications and
--   middleware.
vault :: Request -> Vault
instance Typeable InvalidRequest
instance Show InvalidRequest
instance Eq InvalidRequest
instance Show HostPreference
instance Eq HostPreference
instance Ord HostPreference
instance IsString HostPreference
instance Exception InvalidRequest