Network.HTTP.Enumerator
Contents
Description
This module contains everything you need to initiate HTTP connections. 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 Data.Enumerator import Data.Enumerator.Binary import Network.HTTP.Enumerator import System.IO main :: IO () main = withFile "google.html" WriteMode $ \handle -> do request <- parseUrl "http://google.com/" withManager $ \manager -> do run_ $ httpRedirect request (\_ _ -> iterHandle handle) manager
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).
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 that function 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 $ simpleHttp "http://www.haskell.org/" >>= L.putStr
- simpleHttp :: MonadIO m => String -> m ByteString
- httpLbs :: MonadIO m => Request m -> Manager -> m Response
- httpLbsRedirect :: MonadIO m => Request m -> Manager -> m Response
- http :: MonadIO m => Request m -> (Status -> ResponseHeaders -> Iteratee ByteString m a) -> Manager -> Iteratee ByteString m a
- httpRedirect :: MonadIO m => Request m -> (Status -> ResponseHeaders -> Iteratee ByteString m a) -> Manager -> Iteratee ByteString m a
- redirectIter :: MonadIO m => Int -> Request m -> (Status -> ResponseHeaders -> Iteratee ByteString m a) -> Manager -> Status -> ResponseHeaders -> Iteratee ByteString m a
- data Proxy = Proxy {}
- data RequestBody m
- data Response = Response {}
- data Request m
- def :: Default a => a
- method :: Request m -> Method
- secure :: Request m -> Bool
- checkCerts :: Request m -> Ascii -> [X509] -> IO TLSCertificateUsage
- host :: Request m -> Ascii
- port :: Request m -> Int
- path :: Request m -> Ascii
- queryString :: Request m -> Query
- requestHeaders :: Request m -> RequestHeaders
- requestBody :: Request m -> RequestBody m
- proxy :: Request m -> Maybe Proxy
- rawBody :: Request m -> Bool
- decompress :: Request m -> ContentType -> Bool
- defaultCheckCerts :: Ascii -> [X509] -> IO TLSCertificateUsage
- data Manager
- newManager :: IO Manager
- closeManager :: Manager -> IO ()
- withManager :: MonadBaseControl IO m => (Manager -> m a) -> m a
- parseUrl :: Failure HttpException m => String -> m (Request m')
- applyBasicAuth :: ByteString -> ByteString -> Request m -> Request m
- addProxy :: ByteString -> Int -> Request m -> Request m
- semiParseUrl :: Failure HttpException m => String -> m (Request m')
- lbsIter :: Monad m => Status -> ResponseHeaders -> Iteratee ByteString m Response
- alwaysDecompress :: ContentType -> Bool
- browserDecompress :: ContentType -> Bool
- urlEncodedBody :: Monad m => [(ByteString, ByteString)] -> Request m' -> Request m
- data HttpException
Perform a request
simpleHttp :: MonadIO m => String -> m ByteString
Download the specified URL, following any redirects, and return the response body.
This function will throwIO
an HttpException
for any response with a
non-2xx status code. It uses parseUrl
to parse the input. This function
essentially wraps httpLbsRedirect
.
Note: Even though this function returns a lazy bytestring, it 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.
httpLbs :: MonadIO m => Request m -> Manager -> m Response
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.
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.
httpLbsRedirect :: MonadIO m => Request m -> Manager -> m Response
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.
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.
http :: MonadIO m => Request m -> (Status -> ResponseHeaders -> Iteratee ByteString m a) -> Manager -> Iteratee ByteString m a
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 Request
for full details.
The second 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 => Request m -> (Status -> ResponseHeaders -> Iteratee ByteString m a) -> Manager -> Iteratee ByteString m a
Same as http
, but follows all 3xx redirect status codes that contain a
location header.
Arguments
:: MonadIO m | |
=> Int | number of redirects to attempt |
-> Request m | Original request |
-> (Status -> ResponseHeaders -> Iteratee ByteString m a) | |
-> Manager | |
-> Status -> ResponseHeaders -> Iteratee ByteString m a |
Make a request automatically follow 3xx redirects.
Used internally by httpRedirect
and family.
Datatypes
data Proxy
Define a HTTP proxy, consisting of a hostname and port number.
data RequestBody m
When using the RequestBodyEnum
constructor and any function which calls
redirectIter
, you must ensure that the Enumerator
can be called multiple
times.
The RequestBodyEnumChunked
will send a chunked request body, note
that not all servers support this. Only use RequestBodyEnumChunked
if you know the server you're sending to supports chunked request
bodies.
data Response
A simple representation of the HTTP response created by lbsIter
.
Constructors
Response | |
Fields |
Request
data Request m
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-enumerator to add configuration options without
breaking backwards compatibility.
checkCerts :: Request m -> Ascii -> [X509] -> IO TLSCertificateUsage
Check if the server certificate is valid. Only relevant for HTTPS.
queryString :: Request m -> Query
Automatically escaped for your convenience.
requestHeaders :: Request m -> RequestHeaders
requestBody :: Request m -> RequestBody m
If True, a chunked and/or gzipped body will not be decoded. Use with caution.
decompress :: Request m -> ContentType -> Bool
Predicate to specify whether gzipped data should be decompressed on the fly.
Defaults
defaultCheckCerts :: Ascii -> [X509] -> IO TLSCertificateUsage
Manager
data Manager
Keeps track of open connections for keep-alive.
newManager :: IO Manager
Create a new Manager
with no open connection.
closeManager :: Manager -> IO ()
withManager :: MonadBaseControl IO m => (Manager -> m a) -> m a
Create a new Manager
, call the supplied function and then close it.
Utility functions
parseUrl :: Failure HttpException m => String -> m (Request m')
applyBasicAuth :: ByteString -> ByteString -> Request m -> Request m
Add a Basic Auth header (with the specified user name and password) to the given Request. Ignore error handling:
applyBasicAuth "user" "pass" $ fromJust $ parseUrl url
addProxy :: ByteString -> Int -> Request m -> Request m
Add a proxy to the the Request so that the Request when executed will use the provided proxy.
semiParseUrl :: Failure HttpException m => String -> m (Request m')
Same as parseUrl
, with one distinction: this function will not attempt
to parse the query string, but instead leave it with the path info. This can
be useful if you need precise control of the rendering of the query string,
such as using semicolons instead of ampersands.
lbsIter :: Monad m => Status -> ResponseHeaders -> Iteratee ByteString m Response
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.
Decompression predicates
alwaysDecompress :: ContentType -> Bool
Always decompress a compressed stream.
browserDecompress :: ContentType -> Bool
Decompress a compressed stream unless the content-type is 'application/x-tar'.
Request bodies
urlEncodedBody :: Monad m => [(ByteString, ByteString)] -> Request m' -> Request m
Add url-encoded paramters to the Request
.
This sets a new requestBody
, adds a content-type request header and
changes the method
to POST.