HTTP-4000.2.20: A library for client-side HTTP

Copyright | See LICENSE file
License | BSD
Maintainer | Ganesh Sittampalam <ganesh@earth.li>
Stability | experimental
Portability | non-portable (not tested)
Safe Haskell | None
Language | Haskell98

Network.HTTP

Description

The `HTTP` module provides a simple interface for sending and receiving content over HTTP in Haskell. Here's how to fetch a document from a URL and return it as a String:

       simpleHTTP (getRequest "http://www.haskell.org/") >>= fmap (take 100) . getResponseBody
           -- fetch document and return it (as a 'String'.)

Other functions let you control the submission and transfer of HTTP `Request`s and `Response`s more carefully, letting you integrate the use of `HTTP` functionality into your application.

The module also exports the main types of the package, `Request` and `Response`, along with `Header` and functions for working with these.

The actual functionality is implemented by modules in the `Network.HTTP.*` namespace, letting you either use the default implementation here by importing `Network.HTTP` or, for more specific uses, selectively import the modules in `Network.HTTP.*`. To wit, more than one kind of representation of the bulk data that flows across a HTTP connection is supported. (see Network.HTTP.HandleStream.)

NOTE: The `Request` send actions will normalize the `Request` prior to transmission. Normalization such as having the request path be in the expected form and, possibly, introduce a default `Host:` header if one isn't already present. Normalization also takes the `"user:pass@"` portion out of the the URI, if it was supplied, and converts it into `Authorization: Basic$ header. If you do not want the requests tampered with, but sent as-is, please import and use the the Network.HTTP.HandleStream or Network.HTTP.Stream modules instead. They export the same functions, but leaves construction and any normalization of` Request@s to the user.

NOTE: This package only supports HTTP; it does not support HTTPS. Attempts to use HTTPS result in an error.

Synopsis

- module Network.HTTP.Base
- module Network.HTTP.Headers
- simpleHTTP :: HStream ty => Request ty -> IO (Result (Response ty))
- simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))
- sendHTTP :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))
- sendHTTP_notify :: HStream ty => HandleStream ty -> Request ty -> IO () -> IO (Result (Response ty))
- receiveHTTP :: HStream ty => HandleStream ty -> IO (Result (Request ty))
- respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO ()
- module Network.TCP
- getRequest :: String -> Request_String
- headRequest :: String -> Request_String
- postRequest :: String -> Request_String
- postRequestWithBody :: String -> String -> String -> Request_String
- getResponseBody :: Result (Response ty) -> IO ty
- getResponseCode :: Result (Response ty) -> IO ResponseCode

# Documentation

module Network.HTTP.Base

module Network.HTTP.Headers

simpleHTTP :: HStream ty => Request ty -> IO (Result (Response ty))

`simpleHTTP req` transmits the `Request` `req` by opening a direct, non-persistent connection to the HTTP server that `req` is destined for, followed by transmitting it and gathering up the response as a `Result`. Prior to sending the request, it is normalized (via `normalizeRequest`). If you have to mediate the request via an HTTP proxy, you will have to normalize the request yourself. Or switch to using `Browser` instead.

Examples:

    simpleHTTP (getRequest "http://hackage.haskell.org/")
    simpleHTTP (getRequest "http://hackage.haskell.org:8012/")

simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))

Identical to `simpleHTTP`, but acting on an already opened stream.

sendHTTP :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))

`sendHTTP hStream httpRequest` transmits `httpRequest` (after normalization) over `hStream`, but does not alter the status of the connection, nor request it to be closed upon receiving the response.

sendHTTP_notify :: HStream ty => HandleStream ty -> Request ty -> IO () -> IO (Result (Response ty))

`sendHTTP_notify hStream httpRequest action` behaves like `sendHTTP`, but lets you supply an IO `action` to execute once the request has been successfully transmitted over the connection. Useful when you want to set up tracing of request transmission and its performance.

receiveHTTP :: HStream ty => HandleStream ty -> IO (Result (Request ty))

`receiveHTTP hStream` reads a `Request` from the `HandleStream` `hStream`

respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO ()

`respondHTTP hStream httpResponse` transmits an HTTP `Response` over the `HandleStream` `hStream`. It could be used to implement simple web server interactions, performing the dual role to `sendHTTP`.

module Network.TCP

getRequest

Arguments

:: String | URL to fetch
-> Request_String | The constructed request

A convenience constructor for a GET `Request`.

If the URL isn't syntactically valid, the function raises an error.

headRequest

Arguments

:: String | URL to fetch
-> Request_String | The constructed request

A convenience constructor for a HEAD `Request`.

If the URL isn't syntactically valid, the function raises an error.

postRequest

Arguments

:: String | URL to POST to
-> Request_String | The constructed request

A convenience constructor for a POST `Request`.

If the URL isn't syntactically valid, the function raises an error.

postRequestWithBody

Arguments

:: String | URL to POST to
-> String | Content-Type of body
-> String | The body of the request
-> Request_String | The constructed request

A convenience constructor for a POST `Request`.

It constructs a request and sets the body as well as the Content-Type and Content-Length headers. The contents of the body are forced to calculate the value for the Content-Length header.

If the URL isn't syntactically valid, the function raises an error.

getResponseBody :: Result (Response ty) -> IO ty

`getResponseBody response` takes the response of a HTTP requesting action and tries to extricate the body of the `Response` `response`. If the request action returned an error, an IO exception is raised.

getResponseCode :: Result (Response ty) -> IO ResponseCode

`getResponseBody response` takes the response of a HTTP requesting action and tries to extricate the status code of the `Response` `response`. If the request action returned an error, an IO exception is raised.