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


-- | An HTTP client using io-streams
--   
--   An HTTP client, using the Snap Framework's 'io-streams' library to
--   handle the streaming IO. The API is optimized for ease of use for the
--   rather common case of code needing to query web services and deal with
--   the result.
--   
--   The library is exported in a single module; see
--   <a>Network.Http.Client</a> for full documentation.
@package http-streams
@version 0.8.9.9


-- | <i>Overview</i>
--   
--   A simple HTTP client library, using the Snap Framework's
--   <tt>io-streams</tt> library to handle the streaming I/O. The
--   <tt>http-streams</tt> API is designed for ease of use when querying
--   web services and dealing with the result.
--   
--   Given:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import System.IO.Streams (InputStream, OutputStream, stdout)
--   import qualified System.IO.Streams as Streams
--   import qualified Data.ByteString as S
--   </pre>
--   
--   and this library:
--   
--   <pre>
--   import Network.Http.Client
--   </pre>
--   
--   the underlying API is straight-forward. In particular, constructing
--   the <a>Request</a> to send is quick and to the point:
--   
--   <pre>
--   main :: IO ()
--   main = do
--       c &lt;- <a>openConnection</a> "www.example.com" 80
--   
--       let q = <a>buildRequest1</a> $ do
--                   <a>http</a> GET "/"
--                   <a>setAccept</a> "text/html"
--   
--       <a>sendRequest</a> c q <a>emptyBody</a>
--   
--       <a>receiveResponse</a> c (\p i -&gt; do
--           xm &lt;- Streams.read i
--           case xm of
--               Just x    -&gt; S.putStr x
--               Nothing   -&gt; "")
--   
--       <a>closeConnection</a> c
--   </pre>
--   
--   which would print the first chunk of the response back from the
--   server. Obviously in real usage you'll do something more interesting
--   with the <a>Response</a> in the handler function, and consume the
--   entire response body from the InputStream ByteString.
--   
--   Because this is all happening in <a>IO</a> (the defining feature of
--   <tt>io-streams</tt>!), you can ensure resource cleanup on normal or
--   abnormal termination by using <tt>Control.Exception</tt>'s standard
--   <a>bracket</a> function; see <a>closeConnection</a> for an example.
--   For the common case we have a utility function which wraps
--   <tt>bracket</tt> for you:
--   
--   <pre>
--   foo :: IO ByteString
--   foo = <a>withConnection</a> (<a>openConnection</a> "www.example.com" 80) doStuff
--   
--   doStuff :: Connection -&gt; IO ByteString
--   </pre>
--   
--   There are also a set of convenience APIs that do just that, along with
--   the tedious bits like parsing URLs. For example, to do an HTTP GET and
--   stream the response body to stdout, you can simply do:
--   
--   <pre>
--   <a>get</a> "http://www.example.com/file.txt" (\p i -&gt; Streams.connect i stdout)
--   </pre>
--   
--   which on the one hand is "easy" while on the other exposes the the
--   <a>Response</a> and InputStream for you to read from. Of course,
--   messing around with URLs is all a bit inefficient, so if you already
--   have e.g. hostname and path, or if you need more control over the
--   request being created, then the underlying <tt>http-streams</tt> API
--   is simple enough to use directly.
module Network.Http.Client
type Hostname = ByteString
type Port = Word16

-- | A connection to a web server.
data Connection

-- | In order to make a request you first establish the TCP connection to
--   the server over which to send it.
--   
--   Ordinarily you would supply the host part of the URL here and it will
--   be used as the value of the HTTP 1.1 <tt>Host:</tt> field. However,
--   you can specify any server name or IP addresss and set the
--   <tt>Host:</tt> value later with <a>setHostname</a> when building the
--   request.
--   
--   Usage is as follows:
--   
--   <pre>
--   c &lt;- openConnection "localhost" 80
--   ...
--   closeConnection c
--   </pre>
--   
--   More likely, you'll use <a>withConnection</a> to wrap the call in
--   order to ensure finalization.
--   
--   HTTP pipelining is supported; you can reuse the connection to a web
--   server, but it's up to you to ensure you match the number of requests
--   sent to the number of responses read, and to process those responses
--   in order. This is all assuming that the <i>server</i> supports
--   pipelining; be warned that not all do. Web browsers go to
--   extraordinary lengths to probe this; you probably only want to do
--   pipelining under controlled conditions. Otherwise just open a new
--   connection for subsequent requests.
openConnection :: Hostname -> Port -> IO Connection

-- | Open a connection to a Unix domain socket.
--   
--   <pre>
--   main :: IO ()
--   main = do
--       c &lt;- openConnectionUnix "/var/run/docker.sock"
--       ...
--       closeConnection c
--   </pre>
openConnectionUnix :: FilePath -> IO Connection
data () => Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method
PATCH :: Method
Method :: ByteString -> Method
data () => RequestBuilder α
buildRequest1 :: RequestBuilder α -> Request
buildRequest :: Monad ν => RequestBuilder α -> ν Request
http :: Method -> ByteString -> RequestBuilder ()
setHostname :: Hostname -> Port -> RequestBuilder ()
setAccept :: ByteString -> RequestBuilder ()
setAccept' :: [(ByteString, Float)] -> RequestBuilder ()
setAuthorizationBasic :: ByteString -> ByteString -> RequestBuilder ()
type ContentType = ByteString
setContentType :: ContentType -> RequestBuilder ()
setContentLength :: Int64 -> RequestBuilder ()
type FieldName = ByteString
data () => Boundary
randomBoundary :: IO Boundary
setContentMultipart :: Boundary -> RequestBuilder ()
setExpectContinue :: RequestBuilder ()
setTransferEncoding :: RequestBuilder ()
setHeader :: ByteString -> ByteString -> RequestBuilder ()
data () => Request
data () => Response

-- | Get the virtual hostname that will be used as the <tt>Host:</tt>
--   header in the HTTP 1.1 request. Per RFC 2616 § 14.23, this will be of
--   the form <tt>hostname:port</tt> if the port number is other than the
--   default, ie 80 for HTTP.
getHostname :: Connection -> Request -> ByteString

-- | Having composed a <a>Request</a> object with the headers and metadata
--   for this connection, you can now send the request to the server, along
--   with the entity body, if there is one. For the rather common case of
--   HTTP requests like <a>GET</a> that don't send data, use
--   <a>emptyBody</a> as the output stream:
--   
--   <pre>
--   sendRequest c q emptyBody
--   </pre>
--   
--   For <a>PUT</a> and <a>POST</a> requests, you can use <a>fileBody</a>
--   or <a>inputStreamBody</a> to send content to the server, or you can
--   work with the <tt>io-streams</tt> API directly:
--   
--   <pre>
--   sendRequest c q (\o -&gt;
--       Streams.write (Just (Builder.fromString "Hello World\n")) o)
--   </pre>
sendRequest :: Connection -> Request -> (OutputStream Builder -> IO α) -> IO α

-- | Use this for the common case of the HTTP methods that only send
--   headers and which have no entity body, i.e. <a>GET</a> requests.
emptyBody :: OutputStream Builder -> IO ()

-- | Sometimes you just want to send some bytes to the server as a the body
--   of your request. This is easy to use, but if you're doing anything
--   massive use <a>inputStreamBody</a>; if you're sending a file use
--   <a>fileBody</a>; if you have an object that needs to be sent as JSON
--   use <tt>jsonBody</tt>
simpleBody :: ByteString -> OutputStream Builder -> IO ()

-- | Specify a local file to be sent to the server as the body of the
--   request.
--   
--   You use this partially applied:
--   
--   <pre>
--   sendRequest c q (fileBody "/etc/passwd")
--   </pre>
--   
--   Note that the type of <tt>(fileBody "/path/to/file")</tt> is just what
--   you need for the third argument to <a>sendRequest</a>, namely
--   
--   <pre>
--   &gt;&gt;&gt; :t filePath "hello.txt"
--   :: OutputStream Builder -&gt; IO ()
--   </pre>
fileBody :: FilePath -> OutputStream Builder -> IO ()

-- | Read from a pre-existing <a>InputStream</a> and pipe that through to
--   the connection to the server. This is useful in the general case where
--   something else has handed you stream to read from and you want to use
--   it as the entity body for the request.
--   
--   You use this partially applied:
--   
--   <pre>
--   i &lt;- getStreamFromVault                    -- magic, clearly
--   sendRequest c q (inputStreamBody i)
--   </pre>
--   
--   This function maps "Builder.fromByteString" over the input, which will
--   be efficient if the ByteString chunks are large.
inputStreamBody :: InputStream ByteString -> OutputStream Builder -> IO ()

-- | Specify name/value pairs to be sent to the server in the manner used
--   by web browsers when submitting a form via a POST request. Parameters
--   will be URL encoded per RFC 2396 and combined into a single string
--   which will be sent as the body of your request.
--   
--   You use this partially applied:
--   
--   <pre>
--   let nvs = [("name","Kermit"),
--              ("type","frog")]
--              ("role","stagehand")]
--   
--   sendRequest c q (encodedFormBody nvs)
--   </pre>
--   
--   Note that it's going to be up to you to call <a>setContentType</a>
--   with a value of <tt>"application/x-www-form-urlencoded"</tt> when
--   building the Request object; the <a>postForm</a> convenience (which
--   uses this <tt>encodedFormBody</tt> function) takes care of this for
--   you, obviously.
encodedFormBody :: [(ByteString, ByteString)] -> OutputStream Builder -> IO ()

-- | Build a list of parts into an upload body.
--   
--   You use this partially applied:
--   
--   <pre>
--   boundary &lt;- randomBoundary
--   
--   let q = buildRequest1 $ do
--         http POST "/api/v1/upload"
--         setContentMultipart boundary
--   
--   let parts =
--           [ simplePart "metadata" Nothing metadata
--           , filePart "submission" (Just "audio/wav") filepath
--           ]
--   
--   sendRequest c q (multipartFormBody boundary parts)
--   </pre>
--   
--   You <i>must</i> have called <a>setContentMultipart</a> when forming
--   the request or the request body you are sending will be invalid and
--   (obviously) you must pass in that same <a>Boundary</a> value when
--   calling this function.
multipartFormBody :: Boundary -> [Part] -> OutputStream Builder -> IO ()

-- | Information about each of the parts of a <tt>multipart/form-data</tt>
--   form upload. Build these with <a>simplePart</a>, <a>filePart</a>, or
--   <a>inputStreamPart</a>.
data Part

-- | Given a simple static set of bytes, send them as a part in a multipart
--   form upload. You need to specify the name of the field for the form,
--   and optionally can supply a MIME content-type.
simplePart :: FieldName -> Maybe ContentType -> ByteString -> Part

-- | The most common case in using multipart form data is to upload a file.
--   Specify the name of the field, optionally a MIME content-type, and
--   then the path to the file to be transmitted. The filename (without
--   directory) will be used to name the file to the server.
filePart :: FieldName -> Maybe ContentType -> FilePath -> Part

-- | Build a piece of a multipart submission from an <a>InputStream</a>.
--   You need to specify a field name for this piece of the submission, and
--   can optionally indicate the MIME type and a filename (if what you are
--   sending is going to be interpreted as a file).
inputStreamPart :: FieldName -> Maybe ContentType -> Maybe FilePath -> InputStream ByteString -> Part

-- | If you've got an object of a type with a <a>ToJSON</a> instance and
--   you need to send that object as JSON up to a web service API, this can
--   help.
--   
--   You use this partially applied:
--   
--   <pre>
--   sendRequest c q (jsonBody thing)
--   </pre>
jsonBody :: ToJSON a => a -> OutputStream Builder -> IO ()

-- | Handle the response coming back from the server. This function hands
--   control to a handler function you supply, passing you the
--   <a>Response</a> object with the response headers and an
--   <a>InputStream</a> containing the entity body.
--   
--   For example, if you just wanted to print the first chunk of the
--   content from the server:
--   
--   <pre>
--   receiveResponse c (\p i -&gt; do
--       m &lt;- Streams.read i
--       case m of
--           Just bytes -&gt; putStr bytes
--           Nothing    -&gt; return ())
--   </pre>
--   
--   Obviously, you can do more sophisticated things with the
--   <a>InputStream</a>, which is the whole point of having an
--   <tt>io-streams</tt> based HTTP client library.
--   
--   The final value from the handler function is the return value of
--   <tt>receiveResponse</tt>, if you need it.
--   
--   Throws <a>UnexpectedCompression</a> if it doesn't know how to handle
--   the compression format used in the response.
receiveResponse :: Connection -> (Response -> InputStream ByteString -> IO β) -> IO β

-- | This is a specialized variant of <a>receiveResponse</a> that
--   <i>explicitly</i> does not handle the content encoding of the response
--   body stream (it will not decompress anything). Unless you really want
--   the raw gzipped content coming down from the server, use
--   <tt>receiveResponse</tt>.
receiveResponseRaw :: Connection -> (Response -> InputStream ByteString -> IO β) -> IO β

-- | Handle the response coming back from the server. This function is the
--   same as receiveResponse, but it does not consume the body for you
--   after the handler is done. This means that it can only be safely used
--   if the handler will fully consume the body, there is no body, or when
--   the connection is not being reused (no pipelining).
unsafeReceiveResponse :: Connection -> (Response -> InputStream ByteString -> IO β) -> IO β
data UnexpectedCompression
type StatusCode = Int
getStatusCode :: Response -> StatusCode
getStatusMessage :: Response -> ByteString
getHeader :: Response -> ByteString -> Maybe ByteString

-- | Print the response headers and response body to <tt>stdout</tt>. You
--   can use this with <a>receiveResponse</a> or one of the convenience
--   functions when testing. For example, doing:
--   
--   <pre>
--   c &lt;- openConnection "kernel.operationaldynamics.com" 58080
--   
--   let q = buildRequest1 $ do
--               http GET "/time"
--   
--   sendRequest c q emptyBody
--   
--   receiveResponse c debugHandler
--   </pre>
--   
--   would print out:
--   
--   <pre>
--   HTTP/1.1 200 OK
--   Transfer-Encoding: chunked
--   Content-Type: text/plain
--   Vary: Accept-Encoding
--   Server: Snap/0.9.2.4
--   Content-Encoding: gzip
--   Date: Mon, 21 Jan 2013 06:13:37 GMT
--   
--   Mon 21 Jan 13, 06:13:37.303Z
--   </pre>
--   
--   or thereabouts.
debugHandler :: Response -> InputStream ByteString -> IO ()

-- | Sometimes you just want the entire response body as a single blob.
--   This function concatonates all the bytes from the response into a
--   ByteString. If using the main <tt>http-streams</tt> API, you would use
--   it as follows:
--   
--   <pre>
--   ...
--   x' &lt;- receiveResponse c simpleHandler
--   ...
--   </pre>
--   
--   The methods in the convenience API all take a function to handle the
--   response; this function is passed directly to the
--   <a>receiveResponse</a> call underlying the request. Thus this utility
--   function can be used for <tt>get</tt> as well:
--   
--   <pre>
--   x' &lt;- get "http://www.example.com/document.txt" simpleHandler
--   </pre>
--   
--   Either way, the usual caveats about allocating a single object from
--   streaming I/O apply: do not use this if you are not absolutely certain
--   that the response body will fit in a reasonable amount of memory.
--   
--   Note that this function makes no discrimination based on the
--   response's HTTP status code. You're almost certainly better off
--   writing your own handler function.
simpleHandler :: Response -> InputStream ByteString -> IO ByteString

-- | A special case of <a>concatHandler</a>, this function will return the
--   entire response body as a single ByteString, but will throw
--   <a>HttpClientError</a> if the response status code was other than
--   <tt>2xx</tt>.
simpleHandler' :: Response -> InputStream ByteString -> IO ByteString
data HttpClientError
HttpClientError :: Int -> ByteString -> HttpClientError

-- | If you're working with a data stream that is in
--   <tt>application/json</tt>, then chances are you're using
--   <tt>aeson</tt> to handle the JSON to Haskell decoding. If so, then
--   this helper function might be of use.
--   
--   <pre>
--   v &lt;- get "http://api.example.com/v1/" jsonHandler
--   </pre>
--   
--   This function feeds the input body to the <a>json'</a>
--   <tt>attoparsec</tt> Parser in order to get the aeson Value type. This
--   is then marshalled to your type represeting the source data, via the
--   FromJSON typeclass.
--   
--   The above example was actually insufficient; when working with
--   <tt>aeson</tt> you need to fix the type so it knows what FromJSON
--   instance to use. Let's say you're getting Person objects, then it
--   would be
--   
--   <pre>
--   v &lt;- get "http://api.example.com/v1/person/461" jsonHandler :: IO Person
--   </pre>
--   
--   assuming your Person type had a FromJSON instance, of course.
--   
--   <i>Note</i>
--   
--   This function parses a single top level JSON object or array, which is
--   all you're supposed to get if it's a valid document. People do all
--   kinds of crazy things though, so beware. Also, this function (like the
--   "concatHander" convenience) loads the entire response into memory;
--   it's not <i>streaming</i>; if you're receiving a document which is
--   (say) a very long array of objects then you may want to implement your
--   own handler function, perhaps using "Streams.parserToInputStream" and
--   the <a>Parser</a> combinators directly — with a result type of
--   InputStream Value, perhaps — by which you could then iterate over the
--   Values one at a time in constant space.
jsonHandler :: FromJSON α => Response -> InputStream ByteString -> IO α

-- | Shutdown the connection. You need to call this release the underlying
--   socket file descriptor and related network resources. To do so
--   reliably, use this in conjunction with <a>openConnection</a> in a call
--   to <a>bracket</a>:
--   
--   <pre>
--   --
--   -- Make connection, cleaning up afterward
--   --
--   
--   foo :: IO ByteString
--   foo = bracket
--      (openConnection "localhost" 80)
--      (closeConnection)
--      (doStuff)
--   
--   --
--   -- Actually use Connection to send Request and receive Response
--   --
--   
--   doStuff :: Connection -&gt; IO ByteString
--   </pre>
--   
--   or, just use <a>withConnection</a>.
--   
--   While returning a ByteString is probably the most common use case, you
--   could conceivably do more processing of the response in
--   <tt>doStuff</tt> and have it and <tt>foo</tt> return a different type.
closeConnection :: Connection -> IO ()

-- | Given an <tt>IO</tt> action producing a <a>Connection</a>, and a
--   computation that needs one, runs the computation, cleaning up the
--   <tt>Connection</tt> afterwards.
--   
--   <pre>
--   x &lt;- withConnection (openConnection "s3.example.com" 80) $ (\c -&gt; do
--       let q = buildRequest1 $ do
--           http GET "/bucket42/object/149"
--       sendRequest c q emptyBody
--       ...
--       return "blah")
--   </pre>
--   
--   which can make the code making an HTTP request a lot more
--   straight-forward.
--   
--   Wraps <tt>Control.Exception</tt>'s <a>bracket</a>.
withConnection :: IO Connection -> (Connection -> IO γ) -> IO γ
type URL = ByteString

-- | Issue an HTTP GET request and pass the resultant response to the
--   supplied handler function. This code will silently follow redirects,
--   to a maximum depth of 5 hops.
--   
--   The handler function is as for <a>receiveResponse</a>, so you can use
--   one of the supplied convenience handlers if you're in a hurry:
--   
--   <pre>
--   x' &lt;- get "http://www.bbc.co.uk/news/" concatHandler
--   </pre>
--   
--   But as ever the disadvantage of doing this is that you're not doing
--   anything intelligent with the HTTP response status code. If you want
--   an exception raised in the event of a non <tt>2xx</tt> response, you
--   can use:
--   
--   <pre>
--   x' &lt;- get "http://www.bbc.co.uk/news/" concatHandler'
--   </pre>
--   
--   but for anything more refined you'll find it easy to simply write your
--   own handler function.
--   
--   Throws <a>TooManyRedirects</a> if more than 5 redirects are thrown.
get :: URL -> (Response -> InputStream ByteString -> IO β) -> IO β
data TooManyRedirects

-- | Send content to a server via an HTTP POST request. Use this function
--   if you have an <a>OutputStream</a> with the body content.
post :: URL -> ContentType -> (OutputStream Builder -> IO α) -> (Response -> InputStream ByteString -> IO β) -> IO β

-- | Send form data to a server via an HTTP POST request. This is the usual
--   use case; most services expect the body to be MIME type
--   <tt>application/x-www-form-urlencoded</tt> as this is what
--   conventional web browsers send on form submission. If you want to POST
--   to a URL with an arbitrary Content-Type, use <a>post</a>.
postForm :: URL -> [(ByteString, ByteString)] -> (Response -> InputStream ByteString -> IO β) -> IO β

-- | Place content on the server at the given URL via an HTTP PUT request,
--   specifying the content type and a function to write the content to the
--   supplied <a>OutputStream</a>. You might see:
--   
--   <pre>
--   put "http://s3.example.com/bucket42/object149" "text/plain"
--       (fileBody "hello.txt") (\p i -&gt; do
--           putStr $ show p
--           Streams.connect i stdout)
--   </pre>
put :: URL -> ContentType -> (OutputStream Builder -> IO α) -> (Response -> InputStream ByteString -> IO β) -> IO β

-- | Open a secure connection to a web server.
--   
--   <pre>
--   import OpenSSL (withOpenSSL)
--   
--   main :: IO ()
--   main = do
--       ctx &lt;- baselineContextSSL
--       c &lt;- openConnectionSSL ctx "api.github.com" 443
--       ...
--       closeConnection c
--   </pre>
--   
--   If you want to tune the parameters used in making SSL connections,
--   manually specify certificates, etc, then setup your own context:
--   
--   <pre>
--   import OpenSSL.Session (SSLContext)
--   import qualified OpenSSL.Session as SSL
--   
--       ...
--       ctx &lt;- SSL.context
--       ...
--   </pre>
--   
--   See <a>OpenSSL.Session</a>.
--   
--   Crypto is as provided by the system <tt>openssl</tt> library, as
--   wrapped by the <tt>HsOpenSSL</tt> package and
--   <tt>openssl-streams</tt>.
--   
--   /There is no longer a need to call <tt>withOpenSSL</tt> explicitly;
--   the initialization is invoked once per process for you/
openConnectionSSL :: SSLContext -> Hostname -> Port -> IO Connection

-- | Creates a basic SSL context. This is the SSL context used if you make
--   an <tt>"https://"</tt> request using one of the convenience functions.
--   It configures OpenSSL to use the default set of ciphers.
--   
--   On Linux, OpenBSD and FreeBSD systems, this function also configures
--   OpenSSL to verify certificates using the system/distribution supplied
--   certificate authorities' certificates
--   
--   On other systems, <i>no certificate validation is performed</i> by the
--   generated <a>SSLContext</a> because there is no canonical place to
--   find the set of system certificates. When using this library on such
--   system, you are encouraged to install the system certificates
--   somewhere and create your own <a>SSLContext</a>.
baselineContextSSL :: IO SSLContext

-- | Modify the context being used to configure the SSL tunnel used by the
--   convenience API functions to make <tt>https://</tt> connections. The
--   default is that setup by <a>baselineContextSSL</a>.
modifyContextSSL :: (SSLContext -> IO SSLContext) -> IO ()

-- | Given a URL, work out whether it is normal, secure, or unix domain,
--   and then open the connection to the webserver including setting the
--   appropriate default port if one was not specified in the URL. This is
--   what powers the convenience API, but you may find it useful in
--   composing your own similar functions.
--   
--   For example (on the assumption that your server behaves when given an
--   absolute URI as the request path), this will open a connection to
--   server <tt>www.example.com</tt> port <tt>443</tt> and request
--   <tt>/photo.jpg</tt>:
--   
--   <pre>
--   let url = "https://www.example.com/photo.jpg"
--   
--   c &lt;- establishConnection url
--   let q = buildRequest1 $ do
--               http GET url
--   ...
--   </pre>
establishConnection :: URL -> IO Connection

-- | Create a raw Connection object from the given parts. This is primarily
--   of use when teseting, for example:
--   
--   <pre>
--   fakeConnection :: IO Connection
--   fakeConnection = do
--       o  &lt;- Streams.nullOutput
--       i  &lt;- Streams.nullInput
--       c  &lt;- makeConnection "www.example.com" (return()) o i
--       return c
--   </pre>
--   
--   is an idiom we use frequently in testing and benchmarking, usually
--   replacing the InputStream with something like:
--   
--   <pre>
--   x' &lt;- S.readFile "properly-formatted-response.txt"
--   i  &lt;- Streams.fromByteString x'
--   </pre>
--   
--   If you're going to do that, keep in mind that you <i>must</i> have
--   CR-LF pairs after each header line and between the header and body to
--   be compliant with the HTTP protocol; otherwise, parsers will reject
--   your message.
makeConnection :: ByteString -> IO () -> OutputStream ByteString -> InputStream ByteString -> IO Connection
data () => Headers
getHeaders :: HttpType τ => τ -> Headers

-- | Get the headers that will be sent with this request. You likely won't
--   need this but there are some corner cases where people need to make
--   calculations based on all the headers before they go out over the
--   wire.
--   
--   If you'd like the request headers as an association list, import the
--   header functions:
--   
--   <pre>
--   import Network.Http.Types
--   </pre>
--   
--   then use <a>retreiveHeaders</a> as follows:
--   
--   <pre>
--   &gt;&gt;&gt; let kvs = retreiveHeaders $ getHeadersFull c q
--   
--   &gt;&gt;&gt; :t kvs
--   :: [(ByteString, ByteString)]
--   </pre>
getHeadersFull :: Connection -> Request -> Headers
packBoundary :: String -> Boundary

-- | <i>Deprecated: Use simpleHandler instead</i>
concatHandler :: Response -> InputStream ByteString -> IO ByteString
concatHandler' :: Response -> InputStream ByteString -> IO ByteString

-- | <i>Deprecated: use retrieveHeaders . getHeadersFull instead</i>
getRequestHeaders :: Connection -> Request -> [(ByteString, ByteString)]
