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.

Performing requests

Perform a Request using a connection acquired from the given Manager,
and then provide the Response 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:

A convenience wrapper around withResponse 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 withResponse and brRead instead.

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 Request for full details. The
second argument specifies which Manager should be used.

This function then returns a Response with a
BodyReader. The Response contains the status code
and headers that were sent back to us, and the
BodyReader contains the body of the request. Note
that this BodyReader 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
responseClose on this response to free up resources.

This function automatically performs any necessary redirects, as specified
by the redirectCount 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.

Low-level response body handling

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 Nothing
if the code is not a 3xx, there is no location header included, or if the
redirected response couldn't be parsed with parseUrl.

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:

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.

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

The constructor for this data type is not exposed. Instead, you should use
either the def method to retrieve a default instance, or parseUrl 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:

The Content-Length and Transfer-Encoding headers are set automatically
by this module, and shall not be added to requestHeaders.

If not provided by the user, Host will automatically be set based on
the host and port 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 decompress 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.

Wraps the calls for getting new connections. This can be useful for
instituting some kind of timeouts. The first argument is the value of
responseTimeout. Second argument is the exception to be thrown on
failure.

Default: If responseTimeout is Nothing, does nothing. Otherwise,
institutes timeout, and returns remaining time for 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.

Various utilities

Like hGet, except that a shorter ByteString may be returned
if there are not enough bytes immediately available to satisfy the
whole request. hGetSome only blocks if there is no data
available, and EOF has not yet been reached.