This module contains everything you need to initiate HTTP connections.
Make sure to wrap your code with withHttpEnumerator
. If you want a simple
interface based on URLs, you can use simpleHttp
. If you want raw power,
http
is the underlying workhorse of this package. Some examples:
-- Just download an HTML document and print it. import Network.HTTP.Enumerator import qualified Data.ByteString.Lazy as L main = simpleHttp "http://www.haskell.org/" >>= L.putStr
This example uses interleaved IO to write the response body to a file in
constant memory space. By using httpRedirect
, it will automatically
follow 3xx redirects.
import Network.HTTP.Enumerator import Data.Enumerator.IO import System.IO main = withFile "google.html" WriteMode $ \handle -> do request <- parseUrl "http://google.com/" httpRedirect (\_ _ -> iterHandle handle) request
The following headers are automatically set by this module, and should not
be added to requestHeaders
:
- Content-Length
- Host
- Accept-Encoding (not currently set, but client usage of this variable will cause breakage).
One last thing: there are two different backends available for the HTTPS
support: the OpenSSL library and the tls package. The former requires some
initialization, while the latter does not. Therefore, this module exports a
withHttpEnumerator
function to provide necessary initialization.
Additionally, any network code on Windows requires some initialization, and
the network library provides withSocketsDo to perform it. Therefore, proper
usage of this library will always involve calling those two functions at
some point. The best approach is to simply call them at the beginning of
your main function, such as:
import Network.HTTP.Enumerator import qualified Data.ByteString.Lazy as L import Network (withSocketsDo) main = withSocketsDo . withHttpEnumerator $ simpleHttp "http://www.haskell.org/" >>= L.putStr
- simpleHttp :: (MonadIO m, Failure HttpException m) => String -> m ByteString
- httpLbs :: MonadIO m => Request -> m Response
- httpLbsRedirect :: (MonadIO m, Failure HttpException m) => Request -> m Response
- http :: MonadIO m => (Int -> Headers -> Iteratee ByteString m a) -> Request -> m a
- httpRedirect :: (MonadIO m, Failure HttpException m) => (Int -> Headers -> Iteratee ByteString m a) -> Request -> m a
- data Request = Request {
- method :: ByteString
- secure :: Bool
- host :: ByteString
- port :: Int
- path :: ByteString
- queryString :: Headers
- requestHeaders :: Headers
- requestBody :: ByteString
- data Response = Response {}
- type Headers = [(ByteString, ByteString)]
- parseUrl :: Failure HttpException m => String -> m Request
- withHttpEnumerator :: IO a -> IO a
- lbsIter :: Monad m => Int -> Headers -> Iteratee ByteString m Response
- urlEncodedBody :: Headers -> Request -> Request
- data HttpException
Perform a request
simpleHttp :: (MonadIO m, Failure HttpException m) => String -> m ByteStringSource
Download the specified URL, following any redirects, and return the response body.
This function will failure
an HttpException
for any response with a
non-2xx status code. It uses parseUrl
to parse the input. This function
essentially wraps httpLbsRedirect
.
httpLbs :: MonadIO m => Request -> m ResponseSource
Download the specified Request
, returning the results as a Response
.
This is a simplified version of http
for the common case where you simply
want the response data as a simple datatype. If you want more power, such as
interleaved actions on the response body during download, you'll need to use
http
directly. This function is defined as:
httpLbs = http lbsIter
Please see lbsIter
for more information on how the Response
value is
created.
httpLbsRedirect :: (MonadIO m, Failure HttpException m) => Request -> m ResponseSource
Download the specified Request
, returning the results as a Response
and automatically handling redirects.
This is a simplified version of httpRedirect
for the common case where you
simply want the response data as a simple datatype. If you want more power,
such as interleaved actions on the response body during download, you'll
need to use httpRedirect
directly. This function is defined as:
httpLbsRedirect = httpRedirect lbsIter
Please see lbsIter
for more information on how the Response
value is
created.
http :: MonadIO m => (Int -> Headers -> Iteratee ByteString m a) -> Request -> m aSource
The most low-level function for initiating an HTTP request.
The second 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 first argument specifies how the response should be handled. It's a
function that takes two arguments: the first is the HTTP status code of the
response, and the second is a list of all response headers. This module
exports lbsIter
, which generates a Response
value.
Note that this allows you to have fully interleaved IO actions during your HTTP download, making it possible to download very large responses in constant memory.
httpRedirect :: (MonadIO m, Failure HttpException m) => (Int -> Headers -> Iteratee ByteString m a) -> Request -> m aSource
Same as http
, but follows all 3xx redirect status codes that contain a
location header.
Datatypes
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
.
Request | |
|
A simple representation of the HTTP response created by lbsIter
.
type Headers = [(ByteString, ByteString)]Source
Utility functions
withHttpEnumerator :: IO a -> IO aSource
The OpenSSL library requires some initialization of variables to be used,
and therefore you must call withOpenSSL
before using any of its functions.
As this library uses OpenSSL, you must use withOpenSSL
as well. (As a side
note, you'll also want to use the withSocketsDo function for network
activity.)
To future-proof this package against switching to different SSL libraries,
we re-export withOpenSSL
under this name. You can call this function as
early as you like; in fact, simply wrapping the do block of your main
function is probably best.
lbsIter :: Monad m => Int -> Headers -> Iteratee ByteString m ResponseSource
Convert the HTTP response into a Response
value.
Even though a Response
contains a lazy bytestring, this function does
not utilize lazy I/O, and therefore the entire response body will live in
memory. If you want constant memory usage, you'll need to write your own
iteratee and use http
or httpRedirect
directly.
Request bodies
urlEncodedBody :: Headers -> Request -> RequestSource
Add url-encoded paramters to the Request
.
This sets a new requestBody
, adds a content-type request header and
changes the method
to POST.