Network.Http.Inconvenience

Modify the context being used to configure the SSL tunnel used by the convenience API functions to make https:// connections. The default is that setup by baselineContextSSL.

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 www.example.com port 443 and request /photo.jpg:

    let url = "https://www.example.com/photo.jpg"

    c <- establishConnection url
    let q = buildRequest1 $ do
                http GET url
    ...

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 receiveResponse, so you can use one of the supplied convenience handlers if you're in a hurry:

    x' <- get "http://www.bbc.co.uk/news/" concatHandler

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 2xx response, you can use:

    x' <- get "http://www.bbc.co.uk/news/" concatHandler'

but for anything more refined you'll find it easy to simply write your own handler function.

Throws TooManyRedirects if more than 5 redirects are thrown.

Send content to a server via an HTTP POST request. Use this function if you have an OutputStream with the body content.

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 application/x-www-form-urlencoded 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 post.

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:

    let nvs = [("name","Kermit"),
               ("type","frog")]
               ("role","stagehand")]

    sendRequest c q (encodedFormBody nvs)

Note that it's going to be up to you to call setContentType with a value of "application/x-www-form-urlencoded" when building the Request object; the postForm convenience (which uses this encodedFormBody function) takes care of this for you, obviously.

Build a list of parts into an upload body.

You use this partially applied:

    boundary <- 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)

You must have called setContentMultipart when forming the request or the request body you are sending will be invalid and (obviously) you must pass in that same Boundary value when calling this function.

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

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.

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.

Build a piece of a multipart submission from an InputStream. 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).

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 OutputStream. You might see:

    put "http://s3.example.com/bucket42/object149" "text/plain"
        (fileBody "hello.txt") (\p i -> do
            putStr $ show p
            Streams.connect i stdout)

Creates a basic SSL context. This is the SSL context used if you make an "https://" 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, no certificate validation is performed by the generated SSLContext 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 SSLContext.

A special case of concatHandler, this function will return the entire response body as a single ByteString, but will throw HttpClientError if the response status code was other than 2xx.

If you've got an object of a type with a ToJSON instance and you need to send that object as JSON up to a web service API, this can help.

You use this partially applied:

   sendRequest c q (jsonBody thing)

If you're working with a data stream that is in application/json, then chances are you're using aeson to handle the JSON to Haskell decoding. If so, then this helper function might be of use.

    v <- get "http://api.example.com/v1/" jsonHandler

This function feeds the input body to the json' attoparsec 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 aeson 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

    v <- get "http://api.example.com/v1/person/461" jsonHandler :: IO Person

assuming your Person type had a FromJSON instance, of course.

Note

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 streaming; 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 Data.Aeson.Parser 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.