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


-- | An HTTP client engine
--   
--   Hackage documentation generation is not reliable. For up to date
--   documentation, please see:
--   <a>http://www.stackage.org/package/http-client</a>.
@package http-client
@version 0.5.7.0


-- | Note that this is essentially the "kitchen sink" export module,
--   including many functions intended only to be used internally by this
--   package. No API stability is guaranteed for this module. If you see
--   functions here which you believe should be promoted to a stable API,
--   please contact the author.
module Network.HTTP.Client.Internal
makeChunkedReader :: Bool -> Connection -> IO BodyReader
makeLengthReader :: Int -> Connection -> IO BodyReader
makeGzipReader :: BodyReader -> IO BodyReader
makeUnlimitedReader :: Connection -> IO BodyReader

-- | Strictly consume all remaining chunks of data from the stream.
--   
--   Since 0.1.0
brConsume :: BodyReader -> IO [ByteString]
brEmpty :: BodyReader
constBodyReader :: [ByteString] -> IO BodyReader
brAddCleanup :: IO () -> BodyReader -> BodyReader

-- | Continuously call <a>brRead</a>, building up a lazy ByteString until a
--   chunk is constructed that is at least as many bytes as requested.
--   
--   Since 0.4.20
brReadSome :: BodyReader -> Int -> IO ByteString

-- | Get a single chunk of data from the response body, or an empty
--   bytestring if no more data is available.
--   
--   Note that in order to consume the entire request body, you will need
--   to repeatedly call this function until you receive an empty
--   <tt>ByteString</tt> as a result.
--   
--   Since 0.1.0
brRead :: BodyReader -> IO ByteString
connectionReadLine :: Connection -> IO ByteString
connectionReadLineWith :: Connection -> ByteString -> IO ByteString

-- | Keep dropping input until a blank line is found.
connectionDropTillBlankLine :: Connection -> IO ()

-- | For testing
dummyConnection :: [ByteString] -> IO (Connection, IO [ByteString], IO [ByteString])
openSocketConnection :: (Socket -> IO ()) -> Maybe HostAddress -> String -> Int -> IO Connection
openSocketConnectionSize :: (Socket -> IO ()) -> Int -> Maybe HostAddress -> String -> Int -> IO Connection

-- | Create a new <a>Connection</a> from a read, write, and close function.
makeConnection :: IO ByteString -> (ByteString -> IO ()) -> IO () -> IO Connection

-- | Create a new <a>Connection</a> from a <a>Socket</a>.
socketConnection :: Socket -> Int -> IO Connection

-- | This applies <a>receiveSetCookie</a> to a given Response
updateCookieJar :: Response a -> Request -> UTCTime -> CookieJar -> (CookieJar, Response a)

-- | This corresponds to the algorithm described in Section 5.3 "Storage
--   Model" This function consists of calling <a>generateCookie</a>
--   followed by <a>insertCheckedCookie</a>. Use this function if you plan
--   to do both in a row. <a>generateCookie</a> and
--   <a>insertCheckedCookie</a> are only provided for more fine-grained
--   control.
receiveSetCookie :: SetCookie -> Request -> UTCTime -> Bool -> CookieJar -> CookieJar

-- | Turn a SetCookie into a Cookie, if it is valid
generateCookie :: SetCookie -> Request -> UTCTime -> Bool -> Maybe Cookie

-- | Insert a cookie created by generateCookie into the cookie jar (or not
--   if it shouldn't be allowed in)
insertCheckedCookie :: Cookie -> CookieJar -> Bool -> CookieJar

-- | This applies the <a>computeCookieString</a> to a given Request
insertCookiesIntoRequest :: Request -> CookieJar -> UTCTime -> (Request, CookieJar)

-- | This corresponds to the algorithm described in Section 5.4 "The Cookie
--   Header"
computeCookieString :: Request -> CookieJar -> UTCTime -> Bool -> (ByteString, CookieJar)

-- | This corresponds to the eviction algorithm described in Section 5.3
--   "Storage Model"
evictExpiredCookies :: CookieJar -> UTCTime -> CookieJar
createCookieJar :: [Cookie] -> CookieJar
destroyCookieJar :: CookieJar -> [Cookie]

-- | This corresponds to the subcomponent algorithm entitled "Path-Match"
--   detailed in section 5.1.4
pathMatches :: ByteString -> ByteString -> Bool
removeExistingCookieFromCookieJar :: Cookie -> CookieJar -> (Maybe Cookie, CookieJar)

-- | This corresponds to the subcomponent algorithm entitled "Domain
--   Matching" detailed in section 5.1.3
domainMatches :: ByteString -> ByteString -> Bool
isIpAddress :: ByteString -> Bool

-- | This corresponds to the subcomponent algorithm entitled "Paths"
--   detailed in section 5.1.4
defaultPath :: Request -> ByteString

-- | Perform a <tt>Request</tt> using a connection acquired from the given
--   <tt>Manager</tt>, and then provide the <tt>Response</tt> to the given
--   function. This function is fully exception safe, guaranteeing that the
--   response will be closed when the inner function exits. It is defined
--   as:
--   
--   <pre>
--   withResponse req man f = bracket (responseOpen req man) responseClose f
--   </pre>
--   
--   It is recommended that you use this function in place of explicit
--   calls to <a>responseOpen</a> and <a>responseClose</a>.
--   
--   You will need to use functions such as <a>brRead</a> to consume the
--   response body.
--   
--   Since 0.1.0
withResponse :: Request -> Manager -> (Response BodyReader -> IO a) -> IO a

-- | A convenience wrapper around <a>withResponse</a> which reads in the
--   entire response body and immediately closes the connection. Note that
--   this function performs fully strict I/O, and only uses a lazy
--   ByteString in its response for memory efficiency. If you are
--   anticipating a large response body, you are encouraged to use
--   <a>withResponse</a> and <a>brRead</a> instead.
--   
--   Since 0.1.0
httpLbs :: Request -> Manager -> IO (Response ByteString)

-- | A convenient wrapper around <a>withResponse</a> which ignores the
--   response body. This is useful, for example, when performing a HEAD
--   request.
--   
--   Since 0.3.2
httpNoBody :: Request -> Manager -> IO (Response ())

-- | Get a <a>Response</a> without any redirect following.
httpRaw :: Request -> Manager -> IO (Response BodyReader)

-- | Get a <a>Response</a> without any redirect following.
--   
--   This extended version of <a>httpRaw</a> also returns the potentially
--   modified Request.
httpRaw' :: Request -> Manager -> IO (Request, Response BodyReader)

-- | The used Manager can be overridden (by requestManagerOverride) and the
--   used Request can be modified (through managerModifyRequest). This
--   function allows to retrieve the possibly overridden Manager and the
--   possibly modified Request.
--   
--   (In case the Manager is overridden by requestManagerOverride, the
--   Request is being modified by managerModifyRequest of the new Manager,
--   not the old one.)
getModifiedRequestManager :: Manager -> Request -> IO (Manager, Request)

-- | The most low-level function for initiating an HTTP request.
--   
--   The first argument to this function gives a full specification on the
--   request: the host to connect to, whether to use SSL, headers, etc.
--   Please see <a>Request</a> for full details. The second argument
--   specifies which <a>Manager</a> should be used.
--   
--   This function then returns a <a>Response</a> with a <a>BodyReader</a>.
--   The <a>Response</a> contains the status code and headers that were
--   sent back to us, and the <a>BodyReader</a> contains the body of the
--   request. Note that this <a>BodyReader</a> allows you to have fully
--   interleaved IO actions during your HTTP download, making it possible
--   to download very large responses in constant memory.
--   
--   An important note: the response body returned by this function
--   represents a live HTTP connection. As such, if you do not use the
--   response body, an open socket will be retained indefinitely. You must
--   be certain to call <a>responseClose</a> on this response to free up
--   resources.
--   
--   This function automatically performs any necessary redirects, as
--   specified by the <a>redirectCount</a> setting.
--   
--   When implementing a (reverse) proxy using this function or relating
--   functions, it's wise to remove Transfer-Encoding:, Content-Length:,
--   Content-Encoding: and Accept-Encoding: from request and response
--   headers to be relayed.
--   
--   Since 0.1.0
responseOpen :: Request -> Manager -> IO (Response BodyReader)

-- | Close any open resources associated with the given <tt>Response</tt>.
--   In general, this will either close an active <tt>Connection</tt> or
--   return it to the <tt>Manager</tt> to be reused.
--   
--   Since 0.1.0
responseClose :: Response a -> IO ()

-- | Redirect loop.
httpRedirect :: Int -> (Request -> IO (Response BodyReader, Maybe Request)) -> Request -> IO (Response BodyReader)

-- | Redirect loop.
--   
--   This extended version of <a>httpRaw</a> also returns the Request
--   potentially modified by <tt>managerModifyRequest</tt>.
httpRedirect' :: Int -> (Request -> IO (Response BodyReader, Request, Bool)) -> Request -> IO (Request, Response BodyReader)
parseStatusHeaders :: Connection -> Maybe Int -> Maybe (IO ()) -> IO StatusHeaders

-- | Deprecated synonym for <a>parseUrlThrow</a>. You probably want
--   <a>parseRequest</a> or <a>parseRequest_</a> instead.

-- | <i>Deprecated: Please use parseUrlThrow, parseRequest, or
--   parseRequest_ instead</i>
parseUrl :: MonadThrow m => String -> m Request

-- | Same as <a>parseRequest</a>, except will throw an <a>HttpException</a>
--   in the event of a non-2XX response.
parseUrlThrow :: MonadThrow m => String -> m Request

-- | Convert a URL into a <a>Request</a>.
--   
--   This defaults some of the values in <a>Request</a>, such as setting
--   <a>method</a> to GET and <a>requestHeaders</a> to <tt>[]</tt>.
--   
--   Since this function uses <a>MonadThrow</a>, the return monad can be
--   anything that is an instance of <a>MonadThrow</a>, such as <a>IO</a>
--   or <a>Maybe</a>.
--   
--   You can place the request method at the beginning of the URL separated
--   by a space, e.g.:
--   
--   @@<tt> parseRequeset "POST <a>http://httpbin.org/post"</a> </tt>@@
--   
--   Note that the request method must be provided as all capital letters.
--   
--   <a>Request</a> created by this function won't cause exceptions on
--   non-2XX response status codes.
parseRequest :: MonadThrow m => String -> m Request

-- | Same as <a>parseRequest</a>, but in the cases of a parse error
--   generates an impure exception. Mostly useful for static strings which
--   are known to be correctly formatted.
parseRequest_ :: String -> Request

-- | A default request value
defaultRequest :: Request

-- | Add a <a>URI</a> to the request. If it is absolute (includes a host
--   name), add it as per <a>setUri</a>; if it is relative, merge it with
--   the existing request.
setUriRelative :: MonadThrow m => Request -> URI -> m Request

-- | Extract a <a>URI</a> from the request.
--   
--   Since 0.1.0
getUri :: Request -> URI

-- | Validate a <a>URI</a>, then add it to the request.
setUri :: MonadThrow m => Request -> URI -> m Request

-- | Decompress a compressed stream unless the content-type is
--   'application/x-tar'.
browserDecompress :: ByteString -> Bool

-- | Always decompress a compressed stream.
alwaysDecompress :: ByteString -> Bool

-- | Add a proxy to the Request so that the Request when executed will use
--   the provided proxy.
--   
--   Since 0.1.0
addProxy :: ByteString -> Int -> Request -> Request

-- | Add a Basic Auth header (with the specified user name and password) to
--   the given Request. Ignore error handling:
--   
--   <pre>
--   applyBasicAuth "user" "pass" $ parseRequest_ url
--   </pre>
--   
--   NOTE: The function <tt>applyDigestAuth</tt> is provided by the
--   <tt>http-client-tls</tt> package instead of this package due to extra
--   dependencies. Please use that package if you need to use digest
--   authentication.
--   
--   Since 0.1.0
applyBasicAuth :: ByteString -> ByteString -> Request -> Request

-- | Add a Proxy-Authorization header (with the specified username and
--   password) to the given <a>Request</a>. Ignore error handling:
--   
--   <pre>
--   applyBasicProxyAuth "user" "pass" &lt;$&gt; parseRequest "http://example.org"
--   </pre>
--   
--   Since 0.3.4
applyBasicProxyAuth :: ByteString -> ByteString -> Request -> Request

-- | Add url-encoded parameters to the <a>Request</a>.
--   
--   This sets a new <a>requestBody</a>, adds a content-type request header
--   and changes the <a>method</a> to POST.
--   
--   Since 0.1.0
urlEncodedBody :: [(ByteString, ByteString)] -> Request -> Request
needsGunzip :: Request -> [Header] -> Bool
requestBuilder :: Request -> Connection -> IO (Maybe (IO ()))

-- | Modify the request so that non-2XX status codes do not generate a
--   runtime <a>StatusCodeException</a>.
setRequestIgnoreStatus :: Request -> Request

-- | Set the query string to the given key/value pairs.
--   
--   Since 0.3.6
setQueryString :: [(ByteString, Maybe ByteString)] -> Request -> Request

-- | Send a file as the request body.
--   
--   It is expected that the file size does not change between calling
--   <a>streamFile</a> and making any requests using this request body.
--   
--   Since 0.4.9
streamFile :: FilePath -> IO RequestBody

-- | Send a file as the request body, while observing streaming progress
--   via a <tt>PopObserver</tt>. Observations are made between reading and
--   sending a chunk.
--   
--   It is expected that the file size does not change between calling
--   <a>observedStreamFile</a> and making any requests using this request
--   body.
--   
--   Since 0.4.9
observedStreamFile :: (StreamFileStatus -> IO ()) -> FilePath -> IO RequestBody

-- | Extract basic access authentication info in URI. Return Nothing when
--   there is no auth info in URI.
extractBasicAuthInfo :: URI -> Maybe (ByteString, ByteString)

-- | If a request is a redirection (status code 3xx) this function will
--   create a new request from the old request, the server headers returned
--   with the redirection, and the redirection code itself. This function
--   returns <a>Nothing</a> if the code is not a 3xx, there is no
--   <tt>location</tt> header included, or if the redirected response
--   couldn't be parsed with <a>parseRequest</a>.
--   
--   If a user of this library wants to know the url chain that results
--   from a specific request, that user has to re-implement the
--   redirect-following logic themselves. An example of that might look
--   like this:
--   
--   <pre>
--   myHttp req man = do
--      (res, redirectRequests) &lt;- (`runStateT` []) $
--           'httpRedirect'
--               9000
--               (\req' -&gt; do
--                  res &lt;- http req'{redirectCount=0} man
--                  modify (\rqs -&gt; req' : rqs)
--                  return (res, getRedirectedRequest req' (responseHeaders res) (responseCookieJar res) (W.statusCode (responseStatus res))
--                  )
--               'lift'
--               req
--      applyCheckStatus (checkStatus req) res
--      return redirectRequests
--   </pre>
getRedirectedRequest :: Request -> ResponseHeaders -> CookieJar -> Int -> Maybe Request
getResponse :: ConnRelease -> Maybe Int -> Request -> Connection -> Maybe (IO ()) -> IO (Response BodyReader)

-- | Convert a <a>Response</a> that has a <tt>Source</tt> body to one with
--   a lazy <a>ByteString</a> body.
lbsResponse :: Response BodyReader -> IO (Response ByteString)

-- | Settings for a <tt>Manager</tt>. Please use the
--   <tt>defaultManagerSettings</tt> function and then modify individual
--   settings. For more information, see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
--   
--   Since 0.1.0
data ManagerSettings
ManagerSettings :: Int -> IO (Maybe HostAddress -> String -> Int -> IO Connection) -> IO (Maybe HostAddress -> String -> Int -> IO Connection) -> IO (ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection) -> ResponseTimeout -> (SomeException -> Bool) -> (forall a. Request -> IO a -> IO a) -> Int -> (Request -> IO Request) -> (Response BodyReader -> IO (Response BodyReader)) -> ProxyOverride -> ProxyOverride -> ManagerSettings

-- | Number of connections to a single host to keep alive. Default: 10.
--   
--   Since 0.1.0
[managerConnCount] :: ManagerSettings -> Int

-- | Create an insecure connection.
--   
--   Since 0.1.0
[managerRawConnection] :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Create a TLS connection. Default behavior: throw an exception that TLS
--   is not supported.
--   
--   Since 0.1.0
[managerTlsConnection] :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Create a TLS proxy connection. Default behavior: throw an exception
--   that TLS is not supported.
--   
--   Since 0.2.2
[managerTlsProxyConnection] :: ManagerSettings -> IO (ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection)

-- | Default timeout to be applied to requests which do not provide a
--   timeout value.
--   
--   Default is 30 seconds
[managerResponseTimeout] :: ManagerSettings -> ResponseTimeout

-- | Exceptions for which we should retry our request if we were reusing an
--   already open connection. In the case of IOExceptions, for example, we
--   assume that the connection was closed on the server and therefore open
--   a new one.
--   
--   Since 0.1.0
[managerRetryableException] :: ManagerSettings -> SomeException -> Bool

-- | Action wrapped around all attempted <tt>Request</tt>s, usually used to
--   wrap up exceptions in library-specific types.
--   
--   Default: wrap all <tt>IOException</tt>s in the
--   <tt>InternalException</tt> constructor.
[managerWrapException] :: ManagerSettings -> forall a. Request -> IO a -> IO a

-- | Total number of idle connection to keep open at a given time.
--   
--   This limit helps deal with the case where you are making a large
--   number of connections to different hosts. Without this limit, you
--   could run out of file descriptors.
--   
--   Default: 512
--   
--   Since 0.3.7
[managerIdleConnectionCount] :: ManagerSettings -> Int

-- | Perform the given modification to a <tt>Request</tt> before performing
--   it.
--   
--   Default: no modification
--   
--   Since 0.4.4
[managerModifyRequest] :: ManagerSettings -> Request -> IO Request

-- | Perform the given modification to a <tt>Response</tt> after receiving
--   it.
--   
--   Default: no modification
[managerModifyResponse] :: ManagerSettings -> Response BodyReader -> IO (Response BodyReader)

-- | How HTTP proxy server settings should be discovered.
--   
--   Default: respect the <tt>proxy</tt> value on the <tt>Request</tt>
--   itself.
--   
--   Since 0.4.7
[managerProxyInsecure] :: ManagerSettings -> ProxyOverride

-- | How HTTPS proxy server settings should be discovered.
--   
--   Default: respect the <tt>proxy</tt> value on the <tt>Request</tt>
--   itself.
--   
--   Since 0.4.7
[managerProxySecure] :: ManagerSettings -> ProxyOverride

-- | Create a <a>Manager</a>. The <tt>Manager</tt> will be shut down
--   automatically via garbage collection.
--   
--   Creating a new <a>Manager</a> is a relatively expensive operation, you
--   are advised to share a single <a>Manager</a> between requests instead.
--   
--   The first argument to this function is often
--   <a>defaultManagerSettings</a>, though add-on libraries may provide a
--   recommended replacement.
--   
--   Since 0.1.0
newManager :: ManagerSettings -> IO Manager

-- | Close all connections in a <a>Manager</a>.
--   
--   Note that this doesn't affect currently in-flight connections, meaning
--   you can safely use it without hurting any queries you may have
--   concurrently running.
--   
--   Since 0.1.0

-- | <i>Deprecated: Manager will be closed for you automatically when no
--   longer in use</i>
closeManager :: Manager -> IO ()

-- | Create, use and close a <a>Manager</a>.
--   
--   Since 0.2.1

-- | <i>Deprecated: Use newManager instead</i>
withManager :: ManagerSettings -> (Manager -> IO a) -> IO a
getConn :: Request -> Manager -> IO (ConnRelease, Connection, ManagedConn)

-- | Default value for <tt>ManagerSettings</tt>.
--   
--   Note that this value does <i>not</i> have support for SSL/TLS. If you
--   need to make any https connections, please use the http-client-tls
--   package, which provides a <tt>tlsManagerSettings</tt> value.
--   
--   Since 0.1.0
defaultManagerSettings :: ManagerSettings

-- | A value for the <tt>managerRawConnection</tt> setting, but also allows
--   you to modify the underlying <tt>Socket</tt> to set additional
--   settings. For a motivating use case, see:
--   <a>https://github.com/snoyberg/http-client/issues/71</a>.
--   
--   Since 0.3.8
rawConnectionModifySocket :: (Socket -> IO ()) -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Same as <tt>rawConnectionModifySocket</tt>, but also takes in a chunk
--   size.
rawConnectionModifySocketSize :: (Socket -> IO ()) -> IO (Int -> Maybe HostAddress -> String -> Int -> IO Connection)

-- | Get the proxy settings from the <tt>Request</tt> itself.
--   
--   Since 0.4.7
proxyFromRequest :: ProxyOverride

-- | Never connect using a proxy, regardless of the proxy value in the
--   <tt>Request</tt>.
--   
--   Since 0.4.7
noProxy :: ProxyOverride

-- | Use the given proxy settings, regardless of the proxy value in the
--   <tt>Request</tt>.
--   
--   Since 0.4.7
useProxy :: Proxy -> ProxyOverride

-- | Get the proxy settings from the default environment variable
--   (<tt>http_proxy</tt> for insecure, <tt>https_proxy</tt> for secure).
--   If no variable is set, then fall back to the given value.
--   <tt>Nothing</tt> is equivalent to <a>noProxy</a>, <tt>Just</tt> is
--   equivalent to <a>useProxy</a>.
--   
--   Since 0.4.7
proxyEnvironment :: Maybe Proxy -> ProxyOverride

-- | Same as <a>proxyEnvironment</a>, but instead of default environment
--   variable names, allows you to set your own name.
--   
--   Since 0.4.7
proxyEnvironmentNamed :: Text -> Maybe Proxy -> ProxyOverride

-- | The default proxy settings for a manager. In particular: if the
--   <tt>http_proxy</tt> (or <tt>https_proxy</tt>) environment variable is
--   set, use it. Otherwise, use the values in the <tt>Request</tt>.
--   
--   Since 0.4.7
defaultProxy :: ProxyOverride

-- | Drop the Proxy-Authorization header from the request if we're using a
--   secure proxy.
dropProxyAuthSecure :: Request -> Request

-- | An <tt>IO</tt> action that represents an incoming response body coming
--   from the server. Data provided by this action has already been
--   gunzipped and de-chunked, and respects any content-length headers
--   present.
--   
--   The action gets a single chunk of data from the response body, or an
--   empty bytestring if no more data is available.
--   
--   Since 0.4.0
type BodyReader = IO ByteString
data Connection
Connection :: IO ByteString -> (ByteString -> IO ()) -> (ByteString -> IO ()) -> IO () -> Connection

-- | If no more data, return empty.
[connectionRead] :: Connection -> IO ByteString

-- | Return data to be read next time.
[connectionUnread] :: Connection -> ByteString -> IO ()

-- | Send data to server
[connectionWrite] :: Connection -> ByteString -> IO ()

-- | Close connection. Any successive operation on the connection (exept
--   closing) should fail with <a>ConnectionClosed</a> exception. It is
--   allowed to close connection multiple times.
[connectionClose] :: Connection -> IO ()
data StatusHeaders
StatusHeaders :: Status -> HttpVersion -> RequestHeaders -> StatusHeaders

-- | An exception which may be generated by this library
data HttpException

-- | Most exceptions are specific to a <a>Request</a>. Inspect the
--   <a>HttpExceptionContent</a> value for details on what occurred.
HttpExceptionRequest :: Request -> HttpExceptionContent -> HttpException

-- | A URL (first field) is invalid for a given reason (second argument).
InvalidUrlException :: String -> String -> HttpException
data HttpExceptionContent

-- | Generated by the <tt>parseUrlThrow</tt> function when the server
--   returns a non-2XX response status code.
--   
--   May include the beginning of the response body.
StatusCodeException :: (Response ()) -> ByteString -> HttpExceptionContent

-- | The server responded with too many redirects for a request.
--   
--   Contains the list of encountered responses containing redirects in
--   reverse chronological order; including last redirect, which triggered
--   the exception and was not followed.
TooManyRedirects :: [Response ByteString] -> HttpExceptionContent

-- | Either too many headers, or too many total bytes in a single header,
--   were returned by the server, and the memory exhaustion protection in
--   this library has kicked in.
OverlongHeaders :: HttpExceptionContent

-- | The server took too long to return a response. This can be altered via
--   <a>responseTimeout</a> or <a>managerResponseTimeout</a>.
ResponseTimeout :: HttpExceptionContent

-- | Attempting to connect to the server timed out.
ConnectionTimeout :: HttpExceptionContent

-- | An exception occured when trying to connect to the server.
ConnectionFailure :: SomeException -> HttpExceptionContent

-- | The status line returned by the server could not be parsed.
InvalidStatusLine :: ByteString -> HttpExceptionContent

-- | The given response header line could not be parsed
InvalidHeader :: ByteString -> HttpExceptionContent

-- | An exception was raised by an underlying library when performing the
--   request. Most often, this is caused by a failing socket action or a
--   TLS exception.
InternalException :: SomeException -> HttpExceptionContent

-- | A non-200 status code was returned when trying to connect to the proxy
--   server on the given host and port.
ProxyConnectException :: ByteString -> Int -> Status -> HttpExceptionContent

-- | No response data was received from the server at all. This exception
--   may deserve special handling within the library, since it may indicate
--   that a pipelining has been used, and a connection thought to be open
--   was in fact closed.
NoResponseDataReceived :: HttpExceptionContent

-- | Exception thrown when using a <tt>Manager</tt> which does not have
--   support for secure connections. Typically, you will want to use
--   <tt>tlsManagerSettings</tt> from <tt>http-client-tls</tt> to overcome
--   this.
TlsNotSupported :: HttpExceptionContent

-- | The request body provided did not match the expected size.
--   
--   Provides the expected and actual size.
WrongRequestBodyStreamSize :: Word64 -> Word64 -> HttpExceptionContent

-- | The returned response body is too short. Provides the expected size
--   and actual size.
ResponseBodyTooShort :: Word64 -> Word64 -> HttpExceptionContent

-- | A chunked response body had invalid headers.
InvalidChunkHeaders :: HttpExceptionContent

-- | An incomplete set of response headers were returned.
IncompleteHeaders :: HttpExceptionContent

-- | The host we tried to connect to is invalid (e.g., an empty string).
InvalidDestinationHost :: ByteString -> HttpExceptionContent

-- | An exception was thrown when inflating a response body.
HttpZlibException :: ZlibException -> HttpExceptionContent

-- | Values in the proxy environment variable were invalid. Provides the
--   environment variable name and its value.
InvalidProxyEnvironmentVariable :: Text -> Text -> HttpExceptionContent

-- | Attempted to use a <a>Connection</a> which was already closed
ConnectionClosed :: HttpExceptionContent

-- | Proxy settings are not valid (Windows specific currently) @since 0.5.7
InvalidProxySettings :: Text -> HttpExceptionContent
unHttpExceptionContentWrapper :: HttpExceptionContentWrapper -> HttpExceptionContent
throwHttp :: HttpExceptionContent -> IO a
toHttpException :: Request -> HttpExceptionContentWrapper -> HttpException
data Cookie
Cookie :: ByteString -> ByteString -> UTCTime -> ByteString -> ByteString -> UTCTime -> UTCTime -> Bool -> Bool -> Bool -> Bool -> Cookie
[cookie_name] :: Cookie -> ByteString
[cookie_value] :: Cookie -> ByteString
[cookie_expiry_time] :: Cookie -> UTCTime
[cookie_domain] :: Cookie -> ByteString
[cookie_path] :: Cookie -> ByteString
[cookie_creation_time] :: Cookie -> UTCTime
[cookie_last_access_time] :: Cookie -> UTCTime
[cookie_persistent] :: Cookie -> Bool
[cookie_host_only] :: Cookie -> Bool
[cookie_secure_only] :: Cookie -> Bool
[cookie_http_only] :: Cookie -> Bool
newtype CookieJar
CJ :: [Cookie] -> CookieJar
[expose] :: CookieJar -> [Cookie]

-- | Define a HTTP proxy, consisting of a hostname and port number.
data Proxy
Proxy :: ByteString -> Int -> Proxy

-- | The host name of the HTTP proxy.
[proxyHost] :: Proxy -> ByteString

-- | The port number of the HTTP proxy.
[proxyPort] :: Proxy -> Int

-- | When using one of the <a>RequestBodyStream</a> /
--   <a>RequestBodyStreamChunked</a> constructors, you must ensure that the
--   <a>GivesPopper</a> can be called multiple times. Usually this is not a
--   problem.
--   
--   The <a>RequestBodyStreamChunked</a> will send a chunked request body.
--   Note that not all servers support this. Only use
--   <a>RequestBodyStreamChunked</a> if you know the server you're sending
--   to supports chunked request bodies.
--   
--   Since 0.1.0
data RequestBody
RequestBodyLBS :: ByteString -> RequestBody
RequestBodyBS :: ByteString -> RequestBody
RequestBodyBuilder :: Int64 -> Builder -> RequestBody
RequestBodyStream :: Int64 -> (GivesPopper ()) -> RequestBody
RequestBodyStreamChunked :: (GivesPopper ()) -> RequestBody

-- | Allows creation of a <tt>RequestBody</tt> inside the <tt>IO</tt>
--   monad, which is useful for making easier APIs (like
--   <tt>setRequestBodyFile</tt>).
RequestBodyIO :: (IO RequestBody) -> RequestBody

-- | A function which generates successive chunks of a request body,
--   provider a single empty bytestring when no more data is available.
--   
--   Since 0.1.0
type Popper = IO ByteString

-- | A function which must be provided with a <a>Popper</a>.
--   
--   Since 0.1.0
type NeedsPopper a = Popper -> IO a

-- | A function which will provide a <a>Popper</a> to a <a>NeedsPopper</a>.
--   This seemingly convoluted structure allows for creation of request
--   bodies which allocate scarce resources in an exception safe manner.
--   
--   Since 0.1.0
type GivesPopper a = NeedsPopper a -> IO a

-- | All information on how to connect to a host and what should be sent in
--   the HTTP request.
--   
--   If you simply wish to download from a URL, see <tt>parseRequest</tt>.
--   
--   The constructor for this data type is not exposed. Instead, you should
--   use either the <tt>defaultRequest</tt> value, or <tt>parseRequest</tt>
--   to construct from a URL, and then use the records below to make
--   modifications. This approach allows http-client to add configuration
--   options without breaking backwards compatibility.
--   
--   For example, to construct a POST request, you could do something like:
--   
--   <pre>
--   initReq &lt;- parseRequest "http://www.example.com/path"
--   let req = initReq
--               { method = "POST"
--               }
--   </pre>
--   
--   For more information, please see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
--   
--   Since 0.1.0
data Request
Request :: Method -> Bool -> ByteString -> Int -> ByteString -> ByteString -> RequestHeaders -> RequestBody -> Maybe Proxy -> Maybe HostAddress -> Bool -> (ByteString -> Bool) -> Int -> (Request -> Response BodyReader -> IO ()) -> ResponseTimeout -> Maybe CookieJar -> HttpVersion -> (SomeException -> IO ()) -> Maybe Manager -> Request

-- | HTTP request method, eg GET, POST.
--   
--   Since 0.1.0
[method] :: Request -> Method

-- | Whether to use HTTPS (ie, SSL).
--   
--   Since 0.1.0
[secure] :: Request -> Bool

-- | Requested host name, used for both the IP address to connect to and
--   the <tt>host</tt> request header.
--   
--   Since 0.1.0
[host] :: Request -> ByteString

-- | The port to connect to. Also used for generating the <tt>host</tt>
--   request header.
--   
--   Since 0.1.0
[port] :: Request -> Int

-- | Everything from the host to the query string.
--   
--   Since 0.1.0
[path] :: Request -> ByteString

-- | Query string appended to the path.
--   
--   Since 0.1.0
[queryString] :: Request -> ByteString

-- | Custom HTTP request headers
--   
--   The Content-Length and Transfer-Encoding headers are set automatically
--   by this module, and shall not be added to <tt>requestHeaders</tt>.
--   
--   If not provided by the user, <tt>Host</tt> will automatically be set
--   based on the <tt>host</tt> and <tt>port</tt> fields.
--   
--   Moreover, the Accept-Encoding header is set implicitly to gzip for
--   convenience by default. This behaviour can be overridden if needed, by
--   setting the header explicitly to a different value. In order to omit
--   the Accept-Header altogether, set it to the empty string "". If you
--   need an empty Accept-Header (i.e. requesting the identity encoding),
--   set it to a non-empty white-space string, e.g. " ". See RFC 2616
--   section 14.3 for details about the semantics of the Accept-Header
--   field. If you request a content-encoding not supported by this module,
--   you will have to decode it yourself (see also the <a>decompress</a>
--   field).
--   
--   Note: Multiple header fields with the same field-name will result in
--   multiple header fields being sent and therefore it's the
--   responsibility of the client code to ensure that the rules from RFC
--   2616 section 4.2 are honoured.
--   
--   Since 0.1.0
[requestHeaders] :: Request -> RequestHeaders

-- | Request body to be sent to the server.
--   
--   Since 0.1.0
[requestBody] :: Request -> RequestBody

-- | Optional HTTP proxy.
--   
--   Since 0.1.0
[proxy] :: Request -> Maybe Proxy

-- | Optional resolved host address. May not be used by all backends.
--   
--   Since 0.1.0
[hostAddress] :: Request -> Maybe HostAddress

-- | If <tt>True</tt>, a chunked and/or gzipped body will not be decoded.
--   Use with caution.
--   
--   Since 0.1.0
[rawBody] :: Request -> Bool

-- | Predicate to specify whether gzipped data should be decompressed on
--   the fly (see <tt>alwaysDecompress</tt> and
--   <tt>browserDecompress</tt>). Argument is the mime type. Default:
--   browserDecompress.
--   
--   Since 0.1.0
[decompress] :: Request -> ByteString -> Bool

-- | How many redirects to follow when getting a resource. 0 means follow
--   no redirects. Default value: 10.
--   
--   Since 0.1.0
[redirectCount] :: Request -> Int

-- | Check the response immediately after receiving the status and headers.
--   This can be useful for throwing exceptions on non-success status
--   codes.
--   
--   In previous versions of http-client, this went under the name
--   <tt>checkStatus</tt>, but was renamed to avoid confusion about the new
--   default behavior (doing nothing).
[checkResponse] :: Request -> Request -> Response BodyReader -> IO ()

-- | Number of microseconds to wait for a response. If <tt>Nothing</tt>,
--   will wait indefinitely. Default: use <a>managerResponseTimeout</a>
--   (which by default is 30 seconds).
--   
--   Since 0.1.0
[responseTimeout] :: Request -> ResponseTimeout

-- | A user-defined cookie jar. If <a>Nothing</a>, no cookie handling will
--   take place, "Cookie" headers in <a>requestHeaders</a> will be sent
--   raw, and <a>responseCookieJar</a> will be empty.
--   
--   Since 0.1.0
[cookieJar] :: Request -> Maybe CookieJar

-- | HTTP version to send to server.
--   
--   Default: HTTP 1.1
--   
--   Since 0.4.3
[requestVersion] :: Request -> HttpVersion

-- | How to deal with exceptions thrown while sending the request.
--   
--   Default: ignore <tt>IOException</tt>s, rethrow all other exceptions.
--   
--   Since: 0.4.6
[onRequestBodyException] :: Request -> SomeException -> IO ()

-- | A <a>Manager</a> value that should override whatever <tt>Manager</tt>
--   value was passed in to the HTTP request function manually. This is
--   useful when dealing with implicit global managers, such as in
--   <tt>Network.HTTP.Simple</tt>
[requestManagerOverride] :: Request -> Maybe Manager
data ConnReuse
Reuse :: ConnReuse
DontReuse :: ConnReuse
type ConnRelease = ConnReuse -> IO ()
data ManagedConn
Fresh :: ManagedConn
Reused :: ManagedConn

-- | A simple representation of the HTTP response.
--   
--   Since 0.1.0
data Response body
Response :: Status -> HttpVersion -> ResponseHeaders -> body -> CookieJar -> ResponseClose -> Response body

-- | Status code of the response.
--   
--   Since 0.1.0
[responseStatus] :: Response body -> Status

-- | HTTP version used by the server.
--   
--   Since 0.1.0
[responseVersion] :: Response body -> HttpVersion

-- | Response headers sent by the server.
--   
--   Since 0.1.0
[responseHeaders] :: Response body -> ResponseHeaders

-- | Response body sent by the server.
--   
--   Since 0.1.0
[responseBody] :: Response body -> body

-- | Cookies set on the client after interacting with the server. If
--   cookies have been disabled by setting <a>cookieJar</a> to
--   <tt>Nothing</tt>, then this will always be empty.
--   
--   Since 0.1.0
[responseCookieJar] :: Response body -> CookieJar

-- | Releases any resource held by this response. If the response body has
--   not been fully read yet, doing so after this call will likely be
--   impossible.
--   
--   Since 0.1.0
[responseClose'] :: Response body -> ResponseClose
newtype ResponseClose
ResponseClose :: IO () -> ResponseClose
[runResponseClose] :: ResponseClose -> IO ()

-- | Keeps track of open connections for keep-alive.
--   
--   If possible, you should share a single <a>Manager</a> between multiple
--   threads and requests.
--   
--   Since 0.1.0
data Manager
Manager :: IORef ConnsMap -> MVar () -> Int -> ResponseTimeout -> (Maybe HostAddress -> String -> Int -> IO Connection) -> (Maybe HostAddress -> String -> Int -> IO Connection) -> (ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection) -> (SomeException -> Bool) -> (forall a. Request -> IO a -> IO a) -> Int -> (Request -> IO Request) -> (Request -> Request) -> (Response BodyReader -> IO (Response BodyReader)) -> Manager

-- | <tt>Nothing</tt> indicates that the manager is closed.
[mConns] :: Manager -> IORef ConnsMap

-- | Used to indicate to the reaper thread that it has some work to do.
--   This must be filled every time a connection is returned to the
--   manager. While redundant with the <tt>IORef</tt> above, this allows us
--   to have the reaper thread fully blocked instead of running every 5
--   seconds when there are no connections to manage.
[mConnsBaton] :: Manager -> MVar ()

-- | This is a per-<tt>ConnKey</tt> value.
[mMaxConns] :: Manager -> Int

-- | Copied from <a>managerResponseTimeout</a>
[mResponseTimeout] :: Manager -> ResponseTimeout
[mRawConnection] :: Manager -> Maybe HostAddress -> String -> Int -> IO Connection
[mTlsConnection] :: Manager -> Maybe HostAddress -> String -> Int -> IO Connection
[mTlsProxyConnection] :: Manager -> ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection
[mRetryableException] :: Manager -> SomeException -> Bool
[mWrapException] :: Manager -> forall a. Request -> IO a -> IO a
[mIdleConnectionCount] :: Manager -> Int
[mModifyRequest] :: Manager -> Request -> IO Request
[mSetProxy] :: Manager -> Request -> Request

-- | See <tt>managerProxy</tt>
[mModifyResponse] :: Manager -> Response BodyReader -> IO (Response BodyReader)
class HasHttpManager a
getHttpManager :: HasHttpManager a => a -> Manager
data ConnsMap
ManagerClosed :: ConnsMap
ManagerOpen :: {-# UNPACK #-} !Int -> !(Map ConnKey (NonEmptyList Connection)) -> ConnsMap

-- | Settings for a <tt>Manager</tt>. Please use the
--   <tt>defaultManagerSettings</tt> function and then modify individual
--   settings. For more information, see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
--   
--   Since 0.1.0
data ManagerSettings
ManagerSettings :: Int -> IO (Maybe HostAddress -> String -> Int -> IO Connection) -> IO (Maybe HostAddress -> String -> Int -> IO Connection) -> IO (ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection) -> ResponseTimeout -> (SomeException -> Bool) -> (forall a. Request -> IO a -> IO a) -> Int -> (Request -> IO Request) -> (Response BodyReader -> IO (Response BodyReader)) -> ProxyOverride -> ProxyOverride -> ManagerSettings

-- | Number of connections to a single host to keep alive. Default: 10.
--   
--   Since 0.1.0
[managerConnCount] :: ManagerSettings -> Int

-- | Create an insecure connection.
--   
--   Since 0.1.0
[managerRawConnection] :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Create a TLS connection. Default behavior: throw an exception that TLS
--   is not supported.
--   
--   Since 0.1.0
[managerTlsConnection] :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Create a TLS proxy connection. Default behavior: throw an exception
--   that TLS is not supported.
--   
--   Since 0.2.2
[managerTlsProxyConnection] :: ManagerSettings -> IO (ByteString -> (Connection -> IO ()) -> String -> Maybe HostAddress -> String -> Int -> IO Connection)

-- | Default timeout to be applied to requests which do not provide a
--   timeout value.
--   
--   Default is 30 seconds
[managerResponseTimeout] :: ManagerSettings -> ResponseTimeout

-- | Exceptions for which we should retry our request if we were reusing an
--   already open connection. In the case of IOExceptions, for example, we
--   assume that the connection was closed on the server and therefore open
--   a new one.
--   
--   Since 0.1.0
[managerRetryableException] :: ManagerSettings -> SomeException -> Bool

-- | Action wrapped around all attempted <tt>Request</tt>s, usually used to
--   wrap up exceptions in library-specific types.
--   
--   Default: wrap all <tt>IOException</tt>s in the
--   <tt>InternalException</tt> constructor.
[managerWrapException] :: ManagerSettings -> forall a. Request -> IO a -> IO a

-- | Total number of idle connection to keep open at a given time.
--   
--   This limit helps deal with the case where you are making a large
--   number of connections to different hosts. Without this limit, you
--   could run out of file descriptors.
--   
--   Default: 512
--   
--   Since 0.3.7
[managerIdleConnectionCount] :: ManagerSettings -> Int

-- | Perform the given modification to a <tt>Request</tt> before performing
--   it.
--   
--   Default: no modification
--   
--   Since 0.4.4
[managerModifyRequest] :: ManagerSettings -> Request -> IO Request

-- | Perform the given modification to a <tt>Response</tt> after receiving
--   it.
--   
--   Default: no modification
[managerModifyResponse] :: ManagerSettings -> Response BodyReader -> IO (Response BodyReader)

-- | How HTTP proxy server settings should be discovered.
--   
--   Default: respect the <tt>proxy</tt> value on the <tt>Request</tt>
--   itself.
--   
--   Since 0.4.7
[managerProxyInsecure] :: ManagerSettings -> ProxyOverride

-- | How HTTPS proxy server settings should be discovered.
--   
--   Default: respect the <tt>proxy</tt> value on the <tt>Request</tt>
--   itself.
--   
--   Since 0.4.7
[managerProxySecure] :: ManagerSettings -> ProxyOverride
data NonEmptyList a
One :: a -> UTCTime -> NonEmptyList a
Cons :: a -> Int -> UTCTime -> (NonEmptyList a) -> NonEmptyList a

-- | Hostname or resolved host address.
data ConnHost
HostName :: Text -> ConnHost
HostAddress :: HostAddress -> ConnHost

-- | <tt>ConnKey</tt> consists of a hostname, a port and a <tt>Bool</tt>
--   specifying whether to use SSL.
data ConnKey
ConnKey :: ConnHost -> Int -> ByteString -> Int -> Bool -> ConnKey

-- | How the HTTP proxy server settings should be discovered.
--   
--   Since 0.4.7
newtype ProxyOverride
ProxyOverride :: (Bool -> IO (Request -> Request)) -> ProxyOverride
[runProxyOverride] :: ProxyOverride -> Bool -> IO (Request -> Request)

-- | Status of streaming a request body from a file.
--   
--   Since 0.4.9
data StreamFileStatus
StreamFileStatus :: Int64 -> Int64 -> Int -> StreamFileStatus
[fileSize] :: StreamFileStatus -> Int64
[readSoFar] :: StreamFileStatus -> Int64
[thisChunkSize] :: StreamFileStatus -> Int

-- | How to deal with timing out a response
data ResponseTimeout
ResponseTimeoutMicro :: !Int -> ResponseTimeout
ResponseTimeoutNone :: ResponseTimeout
ResponseTimeoutDefault :: ResponseTimeout

-- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be
--   returned if there are not enough bytes immediately available to
--   satisfy the whole request. <a>hGetSome</a> only blocks if there is no
--   data available, and EOF has not yet been reached.
hGetSome :: Handle -> Int -> IO ByteString
(<>) :: Monoid m => m -> m -> m
infixr 5 <>
readDec :: Integral i => String -> Maybe i
hasNoBody :: ByteString -> Int -> Bool

-- | <i>O(1)</i> Convert a strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>.
fromStrict :: ByteString -> ByteString

-- | Wrap an <a>IO</a> computation to time out and return <tt>Nothing</tt>
--   in case no result is available within <tt>n</tt> microseconds
--   (<tt>1/10^6</tt> seconds). In case a result is available before the
--   timeout expires, <tt>Just a</tt> is returned. A negative timeout
--   interval means "wait indefinitely". When specifying long timeouts, be
--   careful not to exceed <tt>maxBound :: Int</tt>.
--   
--   The design of this combinator was guided by the objective that
--   <tt>timeout n f</tt> should behave exactly the same as <tt>f</tt> as
--   long as <tt>f</tt> doesn't time out. This means that <tt>f</tt> has
--   the same <a>myThreadId</a> it would have without the timeout wrapper.
--   Any exceptions <tt>f</tt> might throw cancel the timeout and propagate
--   further up. It also possible for <tt>f</tt> to receive exceptions
--   thrown to it by another thread.
--   
--   A tricky implementation detail is the question of how to abort an
--   <tt>IO</tt> computation. This combinator relies on asynchronous
--   exceptions internally. The technique works very well for computations
--   executing inside of the Haskell runtime system, but it doesn't work at
--   all for non-Haskell code. Foreign function calls, for example, cannot
--   be timed out with this combinator simply because an arbitrary C
--   function cannot receive asynchronous exceptions. When <tt>timeout</tt>
--   is used to wrap an FFI call that blocks, no timeout event can be
--   delivered until the FFI call returns, which pretty much negates the
--   purpose of the combinator. In practice, however, this limitation is
--   less severe than it may sound. Standard I/O functions like
--   <a>hGetBuf</a>, <a>hPutBuf</a>, Network.Socket.accept, or
--   <a>hWaitForInput</a> appear to be blocking, but they really don't
--   because the runtime system uses scheduling mechanisms like
--   <tt>select(2)</tt> to perform asynchronous I/O, so it is possible to
--   interrupt standard socket I/O or file I/O using this combinator.
timeout :: Int -> IO a -> IO (Maybe a)


-- | <h1>Simpler API</h1>
--   
--   The API below is rather low-level. The <tt>Network.HTTP.Simple</tt>
--   module (from the <tt>http-conduit</tt> package) provides a
--   higher-level API with built-in support for things like JSON request
--   and response bodies. For most users, this will be an easier place to
--   start. You can read the tutorial at:
--   
--   <a>https://haskell-lang.org/library/http-client</a>
--   
--   <h1>Lower-level API</h1>
--   
--   This is the main entry point for using http-client. Used by itself,
--   this module provides low-level access for streaming request and
--   response bodies, and only non-secure HTTP connections. Helper packages
--   such as http-conduit provide higher level streaming approaches, while
--   other helper packages like http-client-tls provide secure connections.
--   
--   There are three core components to be understood here: requests,
--   responses, and managers. A <a>Manager</a> keeps track of open
--   connections to various hosts, and when requested, will provide either
--   an existing open connection or create a new connection on demand. A
--   <a>Manager</a> also automatically reaps connections which have been
--   unused for a certain period of time. A <a>Manager</a> allows for more
--   efficient HTTP usage by allowing for keep-alive connections. Secure
--   HTTP connections can be allowed by modifying the settings used for
--   creating a manager. The simplest way to create a <a>Manager</a> is
--   with:
--   
--   <pre>
--   <a>newManager</a> <a>defaultManagerSettings</a>
--   </pre>
--   
--   While generally speaking it is a good idea to share a single
--   <a>Manager</a> throughout your application, there are cases where it
--   makes more sense to create and destroy <a>Manager</a>s more
--   frequently. As an example, if you have an application which will make
--   a large number of requests to different hosts, and will never make
--   more than one connection to a single host, then sharing a
--   <a>Manager</a> will result in idle connections being kept open longer
--   than necessary. In such a situation, it makes sense to use
--   <a>withManager</a> around each new request, to avoid running out of
--   file descriptors. (Note that the <a>managerIdleConnectionCount</a>
--   setting mitigates the risk of leaking too many file descriptors.)
--   
--   The next core component is a <a>Request</a>, which represents a single
--   HTTP request to be sent to a specific server. <a>Request</a>s allow
--   for many settings to control exact how they function, but usually the
--   simplest approach for creating a <a>Request</a> is to use
--   <a>parseRequest</a>.
--   
--   Finally, a <a>Response</a> is the result of sending a single
--   <a>Request</a> to a server, over a connection which was acquired from
--   a <a>Manager</a>. Note that you must close the response when you're
--   done with it to ensure that the connection is recycled to the
--   <a>Manager</a> to either be used by another request, or to be reaped.
--   Usage of <a>withResponse</a> will ensure that this happens
--   automatically.
--   
--   Helper packages may provide replacements for various recommendations
--   listed above. For example, if using http-client-tls, instead of using
--   <a>defaultManagerSettings</a>, you would want to use
--   <tt>tlsManagerSettings</tt>. Be sure to read the relevant helper
--   library documentation for more information.
--   
--   A note on exceptions: for the most part, all actions that perform I/O
--   should be assumed to throw an <a>HttpException</a> in the event of
--   some problem, and all pure functions will be total. For example,
--   <a>withResponse</a>, <a>httpLbs</a>, and <a>BodyReader</a> can all
--   throw exceptions. Functions like <a>responseStatus</a> and
--   <a>applyBasicAuth</a> are guaranteed to be total (or there's a bug in
--   the library).
--   
--   One thing to be cautioned about: the type of <a>parseRequest</a>
--   allows it to work in different monads. If used in the <a>IO</a> monad,
--   it will throw an exception in the case of an invalid URI. In addition,
--   if you leverage the <tt>IsString</tt> instance of the <a>Request</a>
--   value via <tt>OverloadedStrings</tt>, an invalid URI will result in a
--   partial value. Caveat emptor!
module Network.HTTP.Client

-- | Perform a <tt>Request</tt> using a connection acquired from the given
--   <tt>Manager</tt>, and then provide the <tt>Response</tt> to the given
--   function. This function is fully exception safe, guaranteeing that the
--   response will be closed when the inner function exits. It is defined
--   as:
--   
--   <pre>
--   withResponse req man f = bracket (responseOpen req man) responseClose f
--   </pre>
--   
--   It is recommended that you use this function in place of explicit
--   calls to <a>responseOpen</a> and <a>responseClose</a>.
--   
--   You will need to use functions such as <a>brRead</a> to consume the
--   response body.
--   
--   Since 0.1.0
withResponse :: Request -> Manager -> (Response BodyReader -> IO a) -> IO a

-- | A convenience wrapper around <a>withResponse</a> which reads in the
--   entire response body and immediately closes the connection. Note that
--   this function performs fully strict I/O, and only uses a lazy
--   ByteString in its response for memory efficiency. If you are
--   anticipating a large response body, you are encouraged to use
--   <a>withResponse</a> and <a>brRead</a> instead.
--   
--   Since 0.1.0
httpLbs :: Request -> Manager -> IO (Response ByteString)

-- | A convenient wrapper around <a>withResponse</a> which ignores the
--   response body. This is useful, for example, when performing a HEAD
--   request.
--   
--   Since 0.3.2
httpNoBody :: Request -> Manager -> IO (Response ())

-- | The most low-level function for initiating an HTTP request.
--   
--   The first argument to this function gives a full specification on the
--   request: the host to connect to, whether to use SSL, headers, etc.
--   Please see <a>Request</a> for full details. The second argument
--   specifies which <a>Manager</a> should be used.
--   
--   This function then returns a <a>Response</a> with a <a>BodyReader</a>.
--   The <a>Response</a> contains the status code and headers that were
--   sent back to us, and the <a>BodyReader</a> contains the body of the
--   request. Note that this <a>BodyReader</a> allows you to have fully
--   interleaved IO actions during your HTTP download, making it possible
--   to download very large responses in constant memory.
--   
--   An important note: the response body returned by this function
--   represents a live HTTP connection. As such, if you do not use the
--   response body, an open socket will be retained indefinitely. You must
--   be certain to call <a>responseClose</a> on this response to free up
--   resources.
--   
--   This function automatically performs any necessary redirects, as
--   specified by the <a>redirectCount</a> setting.
--   
--   When implementing a (reverse) proxy using this function or relating
--   functions, it's wise to remove Transfer-Encoding:, Content-Length:,
--   Content-Encoding: and Accept-Encoding: from request and response
--   headers to be relayed.
--   
--   Since 0.1.0
responseOpen :: Request -> Manager -> IO (Response BodyReader)

-- | Close any open resources associated with the given <tt>Response</tt>.
--   In general, this will either close an active <tt>Connection</tt> or
--   return it to the <tt>Manager</tt> to be reused.
--   
--   Since 0.1.0
responseClose :: Response a -> IO ()

-- | A variant of <tt>withResponse</tt> which keeps a history of all
--   redirects performed in the interim, together with the first 1024 bytes
--   of their response bodies.
--   
--   Since 0.4.1
withResponseHistory :: Request -> Manager -> (HistoriedResponse BodyReader -> IO a) -> IO a

-- | A variant of <tt>responseOpen</tt> which keeps a history of all
--   redirects performed in the interim, together with the first 1024 bytes
--   of their response bodies.
--   
--   Since 0.4.1
responseOpenHistory :: Request -> Manager -> IO (HistoriedResponse BodyReader)

-- | A datatype holding information on redirected requests and the final
--   response.
--   
--   Since 0.4.1
data HistoriedResponse body

-- | Requests which resulted in a redirect, together with their responses.
--   The response contains the first 1024 bytes of the body.
--   
--   Since 0.4.1
hrRedirects :: HistoriedResponse body -> [(Request, Response ByteString)]

-- | The final request performed.
--   
--   Since 0.4.1
hrFinalRequest :: HistoriedResponse body -> Request

-- | The response from the final request.
--   
--   Since 0.4.1
hrFinalResponse :: HistoriedResponse body -> Response body

-- | Keeps track of open connections for keep-alive.
--   
--   If possible, you should share a single <a>Manager</a> between multiple
--   threads and requests.
--   
--   Since 0.1.0
data Manager

-- | Create a <a>Manager</a>. The <tt>Manager</tt> will be shut down
--   automatically via garbage collection.
--   
--   Creating a new <a>Manager</a> is a relatively expensive operation, you
--   are advised to share a single <a>Manager</a> between requests instead.
--   
--   The first argument to this function is often
--   <a>defaultManagerSettings</a>, though add-on libraries may provide a
--   recommended replacement.
--   
--   Since 0.1.0
newManager :: ManagerSettings -> IO Manager

-- | Close all connections in a <a>Manager</a>.
--   
--   Note that this doesn't affect currently in-flight connections, meaning
--   you can safely use it without hurting any queries you may have
--   concurrently running.
--   
--   Since 0.1.0

-- | <i>Deprecated: Manager will be closed for you automatically when no
--   longer in use</i>
closeManager :: Manager -> IO ()

-- | Create, use and close a <a>Manager</a>.
--   
--   Since 0.2.1

-- | <i>Deprecated: Use newManager instead</i>
withManager :: ManagerSettings -> (Manager -> IO a) -> IO a
class HasHttpManager a
getHttpManager :: HasHttpManager a => a -> Manager

-- | Settings for a <tt>Manager</tt>. Please use the
--   <tt>defaultManagerSettings</tt> function and then modify individual
--   settings. For more information, see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
--   
--   Since 0.1.0
data ManagerSettings

-- | Default value for <tt>ManagerSettings</tt>.
--   
--   Note that this value does <i>not</i> have support for SSL/TLS. If you
--   need to make any https connections, please use the http-client-tls
--   package, which provides a <tt>tlsManagerSettings</tt> value.
--   
--   Since 0.1.0
defaultManagerSettings :: ManagerSettings

-- | Number of connections to a single host to keep alive. Default: 10.
--   
--   Since 0.1.0
managerConnCount :: ManagerSettings -> Int

-- | Create an insecure connection.
--   
--   Since 0.1.0
managerRawConnection :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Create a TLS connection. Default behavior: throw an exception that TLS
--   is not supported.
--   
--   Since 0.1.0
managerTlsConnection :: ManagerSettings -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Default timeout to be applied to requests which do not provide a
--   timeout value.
--   
--   Default is 30 seconds
managerResponseTimeout :: ManagerSettings -> ResponseTimeout

-- | Exceptions for which we should retry our request if we were reusing an
--   already open connection. In the case of IOExceptions, for example, we
--   assume that the connection was closed on the server and therefore open
--   a new one.
--   
--   Since 0.1.0
managerRetryableException :: ManagerSettings -> SomeException -> Bool

-- | Action wrapped around all attempted <tt>Request</tt>s, usually used to
--   wrap up exceptions in library-specific types.
--   
--   Default: wrap all <tt>IOException</tt>s in the
--   <tt>InternalException</tt> constructor.
managerWrapException :: ManagerSettings -> forall a. Request -> IO a -> IO a

-- | Total number of idle connection to keep open at a given time.
--   
--   This limit helps deal with the case where you are making a large
--   number of connections to different hosts. Without this limit, you
--   could run out of file descriptors.
--   
--   Default: 512
--   
--   Since 0.3.7
managerIdleConnectionCount :: ManagerSettings -> Int

-- | Perform the given modification to a <tt>Request</tt> before performing
--   it.
--   
--   Default: no modification
--   
--   Since 0.4.4
managerModifyRequest :: ManagerSettings -> Request -> IO Request

-- | Perform the given modification to a <tt>Response</tt> after receiving
--   it.
--   
--   Default: no modification
managerModifyResponse :: ManagerSettings -> Response BodyReader -> IO (Response BodyReader)

-- | Set the proxy override value, for both HTTP (insecure) and HTTPS
--   (insecure) connections.
--   
--   Since 0.4.7
managerSetProxy :: ProxyOverride -> ManagerSettings -> ManagerSettings

-- | Set the proxy override value, only for HTTP (insecure) connections.
--   
--   Since 0.4.7
managerSetInsecureProxy :: ProxyOverride -> ManagerSettings -> ManagerSettings

-- | Set the proxy override value, only for HTTPS (secure) connections.
--   
--   Since 0.4.7
managerSetSecureProxy :: ProxyOverride -> ManagerSettings -> ManagerSettings

-- | How the HTTP proxy server settings should be discovered.
--   
--   Since 0.4.7
data ProxyOverride

-- | Get the proxy settings from the <tt>Request</tt> itself.
--   
--   Since 0.4.7
proxyFromRequest :: ProxyOverride

-- | Never connect using a proxy, regardless of the proxy value in the
--   <tt>Request</tt>.
--   
--   Since 0.4.7
noProxy :: ProxyOverride

-- | Use the given proxy settings, regardless of the proxy value in the
--   <tt>Request</tt>.
--   
--   Since 0.4.7
useProxy :: Proxy -> ProxyOverride

-- | Get the proxy settings from the default environment variable
--   (<tt>http_proxy</tt> for insecure, <tt>https_proxy</tt> for secure).
--   If no variable is set, then fall back to the given value.
--   <tt>Nothing</tt> is equivalent to <a>noProxy</a>, <tt>Just</tt> is
--   equivalent to <a>useProxy</a>.
--   
--   Since 0.4.7
proxyEnvironment :: Maybe Proxy -> ProxyOverride

-- | Same as <a>proxyEnvironment</a>, but instead of default environment
--   variable names, allows you to set your own name.
--   
--   Since 0.4.7
proxyEnvironmentNamed :: Text -> Maybe Proxy -> ProxyOverride

-- | The default proxy settings for a manager. In particular: if the
--   <tt>http_proxy</tt> (or <tt>https_proxy</tt>) environment variable is
--   set, use it. Otherwise, use the values in the <tt>Request</tt>.
--   
--   Since 0.4.7
defaultProxy :: ProxyOverride

-- | How to deal with timing out a response
data ResponseTimeout

-- | Specify a response timeout in microseconds
responseTimeoutMicro :: Int -> ResponseTimeout

-- | Do not have a response timeout
responseTimeoutNone :: ResponseTimeout

-- | Use the default response timeout
--   
--   When used on a <a>Request</a>, means: use the manager's timeout value
--   
--   When used on a <a>ManagerSettings</a>, means: default to 30 seconds
responseTimeoutDefault :: ResponseTimeout

-- | A value for the <tt>managerRawConnection</tt> setting, but also allows
--   you to modify the underlying <tt>Socket</tt> to set additional
--   settings. For a motivating use case, see:
--   <a>https://github.com/snoyberg/http-client/issues/71</a>.
--   
--   Since 0.3.8
rawConnectionModifySocket :: (Socket -> IO ()) -> IO (Maybe HostAddress -> String -> Int -> IO Connection)

-- | Same as <tt>rawConnectionModifySocket</tt>, but also takes in a chunk
--   size.
rawConnectionModifySocketSize :: (Socket -> IO ()) -> IO (Int -> Maybe HostAddress -> String -> Int -> IO Connection)

-- | Deprecated synonym for <a>parseUrlThrow</a>. You probably want
--   <a>parseRequest</a> or <a>parseRequest_</a> instead.

-- | <i>Deprecated: Please use parseUrlThrow, parseRequest, or
--   parseRequest_ instead</i>
parseUrl :: MonadThrow m => String -> m Request

-- | Same as <a>parseRequest</a>, except will throw an <a>HttpException</a>
--   in the event of a non-2XX response.
parseUrlThrow :: MonadThrow m => String -> m Request

-- | Convert a URL into a <a>Request</a>.
--   
--   This defaults some of the values in <a>Request</a>, such as setting
--   <a>method</a> to GET and <a>requestHeaders</a> to <tt>[]</tt>.
--   
--   Since this function uses <a>MonadThrow</a>, the return monad can be
--   anything that is an instance of <a>MonadThrow</a>, such as <a>IO</a>
--   or <a>Maybe</a>.
--   
--   You can place the request method at the beginning of the URL separated
--   by a space, e.g.:
--   
--   @@<tt> parseRequeset "POST <a>http://httpbin.org/post"</a> </tt>@@
--   
--   Note that the request method must be provided as all capital letters.
--   
--   <a>Request</a> created by this function won't cause exceptions on
--   non-2XX response status codes.
parseRequest :: MonadThrow m => String -> m Request

-- | Same as <a>parseRequest</a>, but in the cases of a parse error
--   generates an impure exception. Mostly useful for static strings which
--   are known to be correctly formatted.
parseRequest_ :: String -> Request

-- | A default request value
defaultRequest :: Request

-- | Add a Basic Auth header (with the specified user name and password) to
--   the given Request. Ignore error handling:
--   
--   <pre>
--   applyBasicAuth "user" "pass" $ parseRequest_ url
--   </pre>
--   
--   NOTE: The function <tt>applyDigestAuth</tt> is provided by the
--   <tt>http-client-tls</tt> package instead of this package due to extra
--   dependencies. Please use that package if you need to use digest
--   authentication.
--   
--   Since 0.1.0
applyBasicAuth :: ByteString -> ByteString -> Request -> Request

-- | Add url-encoded parameters to the <a>Request</a>.
--   
--   This sets a new <a>requestBody</a>, adds a content-type request header
--   and changes the <a>method</a> to POST.
--   
--   Since 0.1.0
urlEncodedBody :: [(ByteString, ByteString)] -> Request -> Request

-- | Extract a <a>URI</a> from the request.
--   
--   Since 0.1.0
getUri :: Request -> URI

-- | Modify the request so that non-2XX status codes do not generate a
--   runtime <a>StatusCodeException</a>.
setRequestIgnoreStatus :: Request -> Request

-- | Set the query string to the given key/value pairs.
--   
--   Since 0.3.6
setQueryString :: [(ByteString, Maybe ByteString)] -> Request -> Request

-- | All information on how to connect to a host and what should be sent in
--   the HTTP request.
--   
--   If you simply wish to download from a URL, see <tt>parseRequest</tt>.
--   
--   The constructor for this data type is not exposed. Instead, you should
--   use either the <tt>defaultRequest</tt> value, or <tt>parseRequest</tt>
--   to construct from a URL, and then use the records below to make
--   modifications. This approach allows http-client to add configuration
--   options without breaking backwards compatibility.
--   
--   For example, to construct a POST request, you could do something like:
--   
--   <pre>
--   initReq &lt;- parseRequest "http://www.example.com/path"
--   let req = initReq
--               { method = "POST"
--               }
--   </pre>
--   
--   For more information, please see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
--   
--   Since 0.1.0
data Request

-- | HTTP request method, eg GET, POST.
--   
--   Since 0.1.0
method :: Request -> Method

-- | Whether to use HTTPS (ie, SSL).
--   
--   Since 0.1.0
secure :: Request -> Bool

-- | Requested host name, used for both the IP address to connect to and
--   the <tt>host</tt> request header.
--   
--   Since 0.1.0
host :: Request -> ByteString

-- | The port to connect to. Also used for generating the <tt>host</tt>
--   request header.
--   
--   Since 0.1.0
port :: Request -> Int

-- | Everything from the host to the query string.
--   
--   Since 0.1.0
path :: Request -> ByteString

-- | Query string appended to the path.
--   
--   Since 0.1.0
queryString :: Request -> ByteString

-- | Custom HTTP request headers
--   
--   The Content-Length and Transfer-Encoding headers are set automatically
--   by this module, and shall not be added to <tt>requestHeaders</tt>.
--   
--   If not provided by the user, <tt>Host</tt> will automatically be set
--   based on the <tt>host</tt> and <tt>port</tt> fields.
--   
--   Moreover, the Accept-Encoding header is set implicitly to gzip for
--   convenience by default. This behaviour can be overridden if needed, by
--   setting the header explicitly to a different value. In order to omit
--   the Accept-Header altogether, set it to the empty string "". If you
--   need an empty Accept-Header (i.e. requesting the identity encoding),
--   set it to a non-empty white-space string, e.g. " ". See RFC 2616
--   section 14.3 for details about the semantics of the Accept-Header
--   field. If you request a content-encoding not supported by this module,
--   you will have to decode it yourself (see also the <a>decompress</a>
--   field).
--   
--   Note: Multiple header fields with the same field-name will result in
--   multiple header fields being sent and therefore it's the
--   responsibility of the client code to ensure that the rules from RFC
--   2616 section 4.2 are honoured.
--   
--   Since 0.1.0
requestHeaders :: Request -> RequestHeaders

-- | Request body to be sent to the server.
--   
--   Since 0.1.0
requestBody :: Request -> RequestBody

-- | Optional HTTP proxy.
--   
--   Since 0.1.0
proxy :: Request -> Maybe Proxy

-- | Add a Proxy-Authorization header (with the specified username and
--   password) to the given <a>Request</a>. Ignore error handling:
--   
--   <pre>
--   applyBasicProxyAuth "user" "pass" &lt;$&gt; parseRequest "http://example.org"
--   </pre>
--   
--   Since 0.3.4
applyBasicProxyAuth :: ByteString -> ByteString -> Request -> Request

-- | Predicate to specify whether gzipped data should be decompressed on
--   the fly (see <tt>alwaysDecompress</tt> and
--   <tt>browserDecompress</tt>). Argument is the mime type. Default:
--   browserDecompress.
--   
--   Since 0.1.0
decompress :: Request -> ByteString -> Bool

-- | How many redirects to follow when getting a resource. 0 means follow
--   no redirects. Default value: 10.
--   
--   Since 0.1.0
redirectCount :: Request -> Int

-- | Check the response immediately after receiving the status and headers.
--   This can be useful for throwing exceptions on non-success status
--   codes.
--   
--   In previous versions of http-client, this went under the name
--   <tt>checkStatus</tt>, but was renamed to avoid confusion about the new
--   default behavior (doing nothing).
checkResponse :: Request -> Request -> Response BodyReader -> IO ()

-- | Number of microseconds to wait for a response. If <tt>Nothing</tt>,
--   will wait indefinitely. Default: use <a>managerResponseTimeout</a>
--   (which by default is 30 seconds).
--   
--   Since 0.1.0
responseTimeout :: Request -> ResponseTimeout

-- | A user-defined cookie jar. If <a>Nothing</a>, no cookie handling will
--   take place, "Cookie" headers in <a>requestHeaders</a> will be sent
--   raw, and <a>responseCookieJar</a> will be empty.
--   
--   Since 0.1.0
cookieJar :: Request -> Maybe CookieJar

-- | HTTP version to send to server.
--   
--   Default: HTTP 1.1
--   
--   Since 0.4.3
requestVersion :: Request -> HttpVersion

-- | When using one of the <a>RequestBodyStream</a> /
--   <a>RequestBodyStreamChunked</a> constructors, you must ensure that the
--   <a>GivesPopper</a> can be called multiple times. Usually this is not a
--   problem.
--   
--   The <a>RequestBodyStreamChunked</a> will send a chunked request body.
--   Note that not all servers support this. Only use
--   <a>RequestBodyStreamChunked</a> if you know the server you're sending
--   to supports chunked request bodies.
--   
--   Since 0.1.0
data RequestBody
RequestBodyLBS :: ByteString -> RequestBody
RequestBodyBS :: ByteString -> RequestBody
RequestBodyBuilder :: Int64 -> Builder -> RequestBody
RequestBodyStream :: Int64 -> (GivesPopper ()) -> RequestBody
RequestBodyStreamChunked :: (GivesPopper ()) -> RequestBody

-- | Allows creation of a <tt>RequestBody</tt> inside the <tt>IO</tt>
--   monad, which is useful for making easier APIs (like
--   <tt>setRequestBodyFile</tt>).
RequestBodyIO :: (IO RequestBody) -> RequestBody

-- | A function which generates successive chunks of a request body,
--   provider a single empty bytestring when no more data is available.
--   
--   Since 0.1.0
type Popper = IO ByteString

-- | A function which must be provided with a <a>Popper</a>.
--   
--   Since 0.1.0
type NeedsPopper a = Popper -> IO a

-- | A function which will provide a <a>Popper</a> to a <a>NeedsPopper</a>.
--   This seemingly convoluted structure allows for creation of request
--   bodies which allocate scarce resources in an exception safe manner.
--   
--   Since 0.1.0
type GivesPopper a = NeedsPopper a -> IO a

-- | Send a file as the request body.
--   
--   It is expected that the file size does not change between calling
--   <a>streamFile</a> and making any requests using this request body.
--   
--   Since 0.4.9
streamFile :: FilePath -> IO RequestBody

-- | Send a file as the request body, while observing streaming progress
--   via a <tt>PopObserver</tt>. Observations are made between reading and
--   sending a chunk.
--   
--   It is expected that the file size does not change between calling
--   <a>observedStreamFile</a> and making any requests using this request
--   body.
--   
--   Since 0.4.9
observedStreamFile :: (StreamFileStatus -> IO ()) -> FilePath -> IO RequestBody

-- | Status of streaming a request body from a file.
--   
--   Since 0.4.9
data StreamFileStatus
StreamFileStatus :: Int64 -> Int64 -> Int -> StreamFileStatus
[fileSize] :: StreamFileStatus -> Int64
[readSoFar] :: StreamFileStatus -> Int64
[thisChunkSize] :: StreamFileStatus -> Int

-- | A simple representation of the HTTP response.
--   
--   Since 0.1.0
data Response body

-- | Status code of the response.
--   
--   Since 0.1.0
responseStatus :: Response body -> Status

-- | HTTP version used by the server.
--   
--   Since 0.1.0
responseVersion :: Response body -> HttpVersion

-- | Response headers sent by the server.
--   
--   Since 0.1.0
responseHeaders :: Response body -> ResponseHeaders

-- | Response body sent by the server.
--   
--   Since 0.1.0
responseBody :: Response body -> body

-- | Cookies set on the client after interacting with the server. If
--   cookies have been disabled by setting <a>cookieJar</a> to
--   <tt>Nothing</tt>, then this will always be empty.
--   
--   Since 0.1.0
responseCookieJar :: Response body -> CookieJar

-- | An <tt>IO</tt> action that represents an incoming response body coming
--   from the server. Data provided by this action has already been
--   gunzipped and de-chunked, and respects any content-length headers
--   present.
--   
--   The action gets a single chunk of data from the response body, or an
--   empty bytestring if no more data is available.
--   
--   Since 0.4.0
type BodyReader = IO ByteString

-- | Get a single chunk of data from the response body, or an empty
--   bytestring if no more data is available.
--   
--   Note that in order to consume the entire request body, you will need
--   to repeatedly call this function until you receive an empty
--   <tt>ByteString</tt> as a result.
--   
--   Since 0.1.0
brRead :: BodyReader -> IO ByteString

-- | Continuously call <a>brRead</a>, building up a lazy ByteString until a
--   chunk is constructed that is at least as many bytes as requested.
--   
--   Since 0.4.20
brReadSome :: BodyReader -> Int -> IO ByteString

-- | Strictly consume all remaining chunks of data from the stream.
--   
--   Since 0.1.0
brConsume :: BodyReader -> IO [ByteString]

-- | Create a new <a>Connection</a> from a read, write, and close function.
makeConnection :: IO ByteString -> (ByteString -> IO ()) -> IO () -> IO Connection

-- | Create a new <a>Connection</a> from a <a>Socket</a>.
socketConnection :: Socket -> Int -> IO Connection

-- | An exception which may be generated by this library
data HttpException

-- | Most exceptions are specific to a <a>Request</a>. Inspect the
--   <a>HttpExceptionContent</a> value for details on what occurred.
HttpExceptionRequest :: Request -> HttpExceptionContent -> HttpException

-- | A URL (first field) is invalid for a given reason (second argument).
InvalidUrlException :: String -> String -> HttpException
data HttpExceptionContent

-- | Generated by the <tt>parseUrlThrow</tt> function when the server
--   returns a non-2XX response status code.
--   
--   May include the beginning of the response body.
StatusCodeException :: (Response ()) -> ByteString -> HttpExceptionContent

-- | The server responded with too many redirects for a request.
--   
--   Contains the list of encountered responses containing redirects in
--   reverse chronological order; including last redirect, which triggered
--   the exception and was not followed.
TooManyRedirects :: [Response ByteString] -> HttpExceptionContent

-- | Either too many headers, or too many total bytes in a single header,
--   were returned by the server, and the memory exhaustion protection in
--   this library has kicked in.
OverlongHeaders :: HttpExceptionContent

-- | The server took too long to return a response. This can be altered via
--   <a>responseTimeout</a> or <a>managerResponseTimeout</a>.
ResponseTimeout :: HttpExceptionContent

-- | Attempting to connect to the server timed out.
ConnectionTimeout :: HttpExceptionContent

-- | An exception occured when trying to connect to the server.
ConnectionFailure :: SomeException -> HttpExceptionContent

-- | The status line returned by the server could not be parsed.
InvalidStatusLine :: ByteString -> HttpExceptionContent

-- | The given response header line could not be parsed
InvalidHeader :: ByteString -> HttpExceptionContent

-- | An exception was raised by an underlying library when performing the
--   request. Most often, this is caused by a failing socket action or a
--   TLS exception.
InternalException :: SomeException -> HttpExceptionContent

-- | A non-200 status code was returned when trying to connect to the proxy
--   server on the given host and port.
ProxyConnectException :: ByteString -> Int -> Status -> HttpExceptionContent

-- | No response data was received from the server at all. This exception
--   may deserve special handling within the library, since it may indicate
--   that a pipelining has been used, and a connection thought to be open
--   was in fact closed.
NoResponseDataReceived :: HttpExceptionContent

-- | Exception thrown when using a <tt>Manager</tt> which does not have
--   support for secure connections. Typically, you will want to use
--   <tt>tlsManagerSettings</tt> from <tt>http-client-tls</tt> to overcome
--   this.
TlsNotSupported :: HttpExceptionContent

-- | The request body provided did not match the expected size.
--   
--   Provides the expected and actual size.
WrongRequestBodyStreamSize :: Word64 -> Word64 -> HttpExceptionContent

-- | The returned response body is too short. Provides the expected size
--   and actual size.
ResponseBodyTooShort :: Word64 -> Word64 -> HttpExceptionContent

-- | A chunked response body had invalid headers.
InvalidChunkHeaders :: HttpExceptionContent

-- | An incomplete set of response headers were returned.
IncompleteHeaders :: HttpExceptionContent

-- | The host we tried to connect to is invalid (e.g., an empty string).
InvalidDestinationHost :: ByteString -> HttpExceptionContent

-- | An exception was thrown when inflating a response body.
HttpZlibException :: ZlibException -> HttpExceptionContent

-- | Values in the proxy environment variable were invalid. Provides the
--   environment variable name and its value.
InvalidProxyEnvironmentVariable :: Text -> Text -> HttpExceptionContent

-- | Attempted to use a <a>Connection</a> which was already closed
ConnectionClosed :: HttpExceptionContent

-- | Proxy settings are not valid (Windows specific currently) @since 0.5.7
InvalidProxySettings :: Text -> HttpExceptionContent
data Cookie
Cookie :: ByteString -> ByteString -> UTCTime -> ByteString -> ByteString -> UTCTime -> UTCTime -> Bool -> Bool -> Bool -> Bool -> Cookie
[cookie_name] :: Cookie -> ByteString
[cookie_value] :: Cookie -> ByteString
[cookie_expiry_time] :: Cookie -> UTCTime
[cookie_domain] :: Cookie -> ByteString
[cookie_path] :: Cookie -> ByteString
[cookie_creation_time] :: Cookie -> UTCTime
[cookie_last_access_time] :: Cookie -> UTCTime
[cookie_persistent] :: Cookie -> Bool
[cookie_host_only] :: Cookie -> Bool
[cookie_secure_only] :: Cookie -> Bool
[cookie_http_only] :: Cookie -> Bool
data CookieJar

-- | Define a HTTP proxy, consisting of a hostname and port number.
data Proxy
Proxy :: ByteString -> Int -> Proxy

-- | The host name of the HTTP proxy.
[proxyHost] :: Proxy -> ByteString

-- | The port number of the HTTP proxy.
[proxyPort] :: Proxy -> Int

-- | This applies <a>receiveSetCookie</a> to a given Response
updateCookieJar :: Response a -> Request -> UTCTime -> CookieJar -> (CookieJar, Response a)

-- | This corresponds to the algorithm described in Section 5.3 "Storage
--   Model" This function consists of calling <a>generateCookie</a>
--   followed by <a>insertCheckedCookie</a>. Use this function if you plan
--   to do both in a row. <a>generateCookie</a> and
--   <a>insertCheckedCookie</a> are only provided for more fine-grained
--   control.
receiveSetCookie :: SetCookie -> Request -> UTCTime -> Bool -> CookieJar -> CookieJar

-- | Turn a SetCookie into a Cookie, if it is valid
generateCookie :: SetCookie -> Request -> UTCTime -> Bool -> Maybe Cookie

-- | Insert a cookie created by generateCookie into the cookie jar (or not
--   if it shouldn't be allowed in)
insertCheckedCookie :: Cookie -> CookieJar -> Bool -> CookieJar

-- | This applies the <a>computeCookieString</a> to a given Request
insertCookiesIntoRequest :: Request -> CookieJar -> UTCTime -> (Request, CookieJar)

-- | This corresponds to the algorithm described in Section 5.4 "The Cookie
--   Header"
computeCookieString :: Request -> CookieJar -> UTCTime -> Bool -> (ByteString, CookieJar)

-- | This corresponds to the eviction algorithm described in Section 5.3
--   "Storage Model"
evictExpiredCookies :: CookieJar -> UTCTime -> CookieJar
createCookieJar :: [Cookie] -> CookieJar
destroyCookieJar :: CookieJar -> [Cookie]

-- | This corresponds to the subcomponent algorithm entitled "Path-Match"
--   detailed in section 5.1.4
pathMatches :: ByteString -> ByteString -> Bool
removeExistingCookieFromCookieJar :: Cookie -> CookieJar -> (Maybe Cookie, CookieJar)

-- | This corresponds to the subcomponent algorithm entitled "Domain
--   Matching" detailed in section 5.1.3
domainMatches :: ByteString -> ByteString -> Bool
isIpAddress :: ByteString -> Bool

-- | This corresponds to the subcomponent algorithm entitled "Paths"
--   detailed in section 5.1.4
defaultPath :: Request -> ByteString
instance GHC.Generics.Generic (Network.HTTP.Client.HistoriedResponse body)
instance GHC.Show.Show body => GHC.Show.Show (Network.HTTP.Client.HistoriedResponse body)
instance Data.Foldable.Foldable Network.HTTP.Client.HistoriedResponse
instance Data.Traversable.Traversable Network.HTTP.Client.HistoriedResponse
instance GHC.Base.Functor Network.HTTP.Client.HistoriedResponse


-- | This module handles building multipart/form-data. Example usage:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   import Network
--   import Network.HTTP.Client
--   import Network.HTTP.Client.MultipartFormData
--   
--   import Data.Text.Encoding as TE
--   
--   import Control.Monad
--   
--   main = withSocketsDo $ void $ withManager defaultManagerSettings $ \m -&gt; do
--       req1 &lt;- parseRequest "http://random-cat-photo.net/cat.jpg"
--       res &lt;- httpLbs req1 m
--       req2 &lt;- parseRequest "http://example.org/~friedrich/blog/addPost.hs"
--       flip httpLbs m =&lt;&lt;
--           (formDataBody [partBS "title" "Bleaurgh"
--                         ,partBS "text" $ TE.encodeUtf8 "矢田矢田矢田矢田矢田"
--                         ,partFileSource "file1" "/home/friedrich/Photos/MyLittlePony.jpg"
--                         ,partFileRequestBody "file2" "cat.jpg" $ RequestBodyLBS $ responseBody res]
--               req2)
--   </pre>
module Network.HTTP.Client.MultipartFormData

-- | A single part of a multipart message.
data Part

-- | Name of the corresponding &lt;input&gt;
partName :: Part -> Text

-- | A file name, if this is an attached file
partFilename :: Part -> Maybe String

-- | Content type
partContentType :: Part -> Maybe MimeType

-- | List of additional headers
partHeaders :: Part -> [Header]

-- | Action in m which returns the body of a message.
partGetBody :: Part -> IO RequestBody

-- | Make a <a>Part</a> whose content is a strict <a>ByteString</a>.
--   
--   The <a>Part</a> does not have a file name or content type associated
--   with it.
partBS :: Text -> ByteString -> Part

-- | Make a <a>Part</a> whose content is a lazy <a>ByteString</a>.
--   
--   The <a>Part</a> does not have a file name or content type associated
--   with it.
partLBS :: Text -> ByteString -> Part

-- | Make a <a>Part</a> from a file.
--   
--   The entire file will reside in memory at once. If you want constant
--   memory usage, use <a>partFileSource</a>.
--   
--   The <a>FilePath</a> supplied will be used as the file name of the
--   <a>Part</a>. If you do not want to reveal this name to the server, you
--   must remove it prior to uploading.
--   
--   The <a>Part</a> does not have a content type associated with it.
partFile :: Text -> FilePath -> Part

-- | Stream a <a>Part</a> from a file.
--   
--   The <a>FilePath</a> supplied will be used as the file name of the
--   <a>Part</a>. If you do not want to reveal this name to the server, you
--   must remove it prior to uploading.
--   
--   The <a>Part</a> does not have a content type associated with it.
partFileSource :: Text -> FilePath -> Part

-- | <a>partFileSourceChunked</a> will read a file and send it in chunks.
--   
--   Note that not all servers support this. Only use
--   <a>partFileSourceChunked</a> if you know the server you're sending to
--   supports chunked request bodies.
--   
--   The <a>FilePath</a> supplied will be used as the file name of the
--   <a>Part</a>. If you do not want to reveal this name to the server, you
--   must remove it prior to uploading.
--   
--   The <a>Part</a> does not have a content type associated with it.
partFileSourceChunked :: Text -> FilePath -> Part

-- | Construct a <a>Part</a> from form name, filepath and a
--   <a>RequestBody</a>
--   
--   <pre>
--   partFileRequestBody "who_calls" "caller.json" $ RequestBodyBS "{\"caller\":\"Jason J Jason\"}"
--   </pre>
--   
--   <pre>
--   -- empty upload form
--   partFileRequestBody "file" mempty mempty
--   </pre>
--   
--   The <a>Part</a> does not have a content type associated with it.
partFileRequestBody :: Text -> FilePath -> RequestBody -> Part

-- | Construct a <a>Part</a> from action returning the <a>RequestBody</a>
--   
--   <pre>
--   partFileRequestBodyM "cat_photo" "haskell-the-cat.jpg" $ do
--       size &lt;- fromInteger &lt;$&gt; withBinaryFile "haskell-the-cat.jpg" ReadMode hFileSize
--       return $ RequestBodySource size $ CB.sourceFile "haskell-the-cat.jpg" $= CL.map fromByteString
--   </pre>
--   
--   The <a>Part</a> does not have a content type associated with it.
partFileRequestBodyM :: Text -> FilePath -> IO RequestBody -> Part

-- | Add a list of additional headers to this <a>Part</a>.
addPartHeaders :: Part -> [Header] -> Part

-- | Add form data to the <a>Request</a>.
--   
--   This sets a new <a>requestBody</a>, adds a content-type request header
--   and changes the method to POST.
formDataBody :: MonadIO m => [Part] -> Request -> m Request

-- | Add form data with supplied boundary
formDataBodyWithBoundary :: ByteString -> [Part] -> Request -> IO Request

-- | Generate a boundary simillar to those generated by WebKit-based
--   browsers.
webkitBoundary :: IO ByteString
webkitBoundaryPure :: RandomGen g => g -> (ByteString, g)

-- | Combine the <a>Part</a>s to form multipart/form-data body
renderParts :: ByteString -> [Part] -> IO RequestBody
renderPart :: ByteString -> Part -> IO RequestBody
instance GHC.Show.Show Network.HTTP.Client.MultipartFormData.Part
