libghc-http-common-doc 0.8.2.0-4build4 / usr / share / doc / libghc-http-common-doc / html / http-common.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Common types for HTTP clients and servers
--   
--   <i>Overview</i>
--   
--   Base types used by a variety of HTTP clients and servers. See
--   http-streams <a>Network.Http.Client</a> or pipes-http
--   <a>Pipes.Http.Client</a> for full documentation. You can import
--   <tt>Network.Http.Types</tt> if you like, but both http-streams and
--   pipes-http re-export this package's types and functions.
@package http-common
@version 0.8.2.0


-- | Basic types used in HTTP communications. This modules is re-exported
--   by both <a>Network.Http.Client</a> and <a>Pipes.Http.Client</a>, so if
--   you're using either of those you don't need to explicitly import this
--   module.
module Network.Http.Types
type Hostname = ByteString
type Port = Word16

-- | A description of the request that will be sent to the server. Note
--   unlike other HTTP libraries, the request body is <i>not</i> a part of
--   this object; that will be streamed out by you when actually sending
--   the request with <tt>sendRequest</tt>.
--   
--   <a>Request</a> has a useful <tt>Show</tt> instance that will output
--   the request line and headers (as it will be sent over the wire but
--   with the <tt>\r</tt> characters stripped) which can be handy for
--   debugging.
--   
--   Note that the actual <tt>Host:</tt> header is not set until the
--   request is sent, so you will not see it in the Show instance (unless
--   you call <tt>setHostname</tt> to override the value inherited from the
--   <tt>Connection</tt>).
data Request
data EntityBody
Empty :: EntityBody
Chunking :: EntityBody
Static :: Int64 -> EntityBody
data ExpectMode
Normal :: ExpectMode
Continue :: ExpectMode

-- | The RequestBuilder monad allows you to abuse do-notation to
--   conveniently setup a <a>Request</a> object.
data RequestBuilder α

-- | Run a RequestBuilder from within a monadic action.
--   
--   Older versions of this library had <a>buildRequest</a> in IO; there's
--   no longer a need for that, but this code path will continue to work
--   for existing users.
--   
--   <pre>
--   q &lt;- buildRequest $ do
--            http GET "/"
--   </pre>
buildRequest :: Monad ν => RequestBuilder α -> ν Request

-- | Run a RequestBuilder, yielding a Request object you can use on the
--   given connection.
--   
--   <pre>
--   let q = buildRequest1 $ do
--               http POST "/api/v1/messages"
--               setContentType "application/json"
--               setHostname "clue.example.com" 80
--               setAccept "text/html"
--               setHeader "X-WhoDoneIt" "The Butler"
--   </pre>
--   
--   Obviously it's up to you to later actually <i>send</i> JSON data.
buildRequest1 :: RequestBuilder α -> Request

-- | Begin constructing a Request, starting with the request line.
http :: Method -> ByteString -> RequestBuilder ()

-- | Set the [virtual] hostname for the request. In ordinary conditions you
--   won't need to call this, as the <tt>Host:</tt> header is a required
--   header in HTTP 1.1 and is set directly from the name of the server you
--   connected to when calling <a>openConnection</a>.
setHostname :: Hostname -> Port -> RequestBuilder ()

-- | Indicate the content type you are willing to receive in a reply from
--   the server. For more complex <tt>Accept:</tt> headers, use
--   <a>setAccept'</a>.
setAccept :: ByteString -> RequestBuilder ()

-- | Indicate the content types you are willing to receive in a reply from
--   the server in order of preference. A call of the form:
--   
--   <pre>
--   setAccept' [("text/html", 1.0),
--               ("application/xml", 0.8),
--               ("*/*", 0)]
--   </pre>
--   
--   will result in an <tt>Accept:</tt> header value of <tt>text/html;
--   q=1.0, application/xml; q=0.8, */*; q=0.0</tt> as you would expect.
setAccept' :: [(ByteString, Float)] -> RequestBuilder ()

-- | Set username and password credentials per the HTTP basic
--   authentication method.
--   
--   <pre>
--   setAuthorizationBasic "Aladdin" "open sesame"
--   </pre>
--   
--   will result in an <tt>Authorization:</tt> header value of <tt>Basic
--   QWxhZGRpbjpvcGVuIHNlc2FtZQ==</tt>.
--   
--   Basic authentication does <i>not</i> use a message digest function to
--   encipher the password; the above string is only base-64 encoded and is
--   thus plain-text visible to any observer on the wire and all caches and
--   servers at the other end, making basic authentication completely
--   insecure. A number of web services, however, use SSL to encrypt the
--   connection that then use HTTP basic authentication to validate
--   requests. Keep in mind in these cases the secret is still sent to the
--   servers on the other side and passes in clear through all layers after
--   the SSL termination. Do <i>not</i> use basic authentication to protect
--   secure or user-originated privacy-sensitve information.
setAuthorizationBasic :: ByteString -> ByteString -> RequestBuilder ()
type ContentType = ByteString

-- | Set the MIME type corresponding to the body of the request you are
--   sending. Defaults to <tt>"text/plain"</tt>, so usually you need to set
--   this if <a>PUT</a>ting.
setContentType :: ContentType -> RequestBuilder ()

-- | Specify the length of the request body, in bytes.
--   
--   RFC 2616 requires that we either send a <tt>Content-Length</tt> header
--   or use <tt>Transfer-Encoding: chunked</tt>. If you know the exact size
--   ahead of time, then call this function; the body content will still be
--   streamed out by <tt>io-streams</tt> in more-or-less constant space.
--   
--   This function is special: in a PUT or POST request,
--   <tt>http-streams</tt> will assume chunked transfer-encoding
--   <i>unless</i> you specify a content length here, in which case you
--   need to ensure your body function writes precisely that many bytes.
setContentLength :: Int64 -> RequestBuilder ()

-- | Specify that this request should set the expectation that the server
--   needs to approve the request before you send it.
--   
--   This function is special: in a PUT or POST request,
--   <tt>http-streams</tt> will wait for the server to reply with an
--   HTTP/1.1 100 Continue status before sending the entity body. This is
--   handled internally; you will get the real response (be it successful
--   2xx, client error, 4xx, or server error 5xx) in
--   <tt>receiveResponse</tt>. In theory, it should be 417 if the
--   expectation failed.
--   
--   Only bother with this if you know the service you're talking to
--   requires clients to send an <tt>Expect: 100-continue</tt> header and
--   will handle it properly. Most servers don't do any precondition
--   checking, automatically send an intermediate 100 response, and then
--   just read the body regardless, making this a bit of a no-op in most
--   cases.
setExpectContinue :: RequestBuilder ()

-- | Override the default setting about how the entity body will be sent.
--   
--   This function is special: this explicitly sets the
--   <tt>Transfer-Encoding:</tt> header to <tt>chunked</tt> and will
--   instruct the library to actually tranfer the body as a stream
--   ("chunked transfer encoding"). See <a>setContentLength</a> for forcing
--   the opposite. You <i>really</i> won't need this in normal operation,
--   but some people are control freaks.
setTransferEncoding :: RequestBuilder ()

-- | Set a generic header to be sent in the HTTP request. The other methods
--   in the RequestBuilder API are expressed in terms of this function, but
--   we recommend you use them where offered for their stronger types.
setHeader :: ByteString -> ByteString -> RequestBuilder ()

-- | A description of the response received from the server. Note unlike
--   other HTTP libraries, the response body is <i>not</i> a part of this
--   object; that will be streamed in by you when calling
--   <tt>receiveResponse</tt>.
--   
--   Like <a>Request</a>, <a>Response</a> has a <tt>Show</tt> instance that
--   will output the status line and response headers as they were received
--   from the server.
data Response
type StatusCode = Int
data TransferEncoding
None :: TransferEncoding
Chunked :: TransferEncoding
data ContentEncoding
Identity :: ContentEncoding
Gzip :: ContentEncoding
Deflate :: ContentEncoding

-- | Get the HTTP response status code.
getStatusCode :: Response -> StatusCode

-- | Get the HTTP response status message. Keep in mind that this is
--   <i>not</i> normative; whereas <a>getStatusCode</a> values are
--   authoritative.
getStatusMessage :: Response -> ByteString

-- | Lookup a header in the response. HTTP header field names are
--   case-insensitive, so you can specify the name to lookup however you
--   like. If the header is not present <tt>Nothing</tt> will be returned.
--   
--   <pre>
--   let n = case getHeader p "Content-Length" of
--              Just x' -&gt; read x' :: Int
--              Nothing -&gt; 0
--   </pre>
--   
--   which of course is essentially what goes on inside the client library
--   when it receives a response from the server and has to figure out how
--   many bytes to read.
--   
--   There is a fair bit of complexity in some of the other HTTP response
--   fields, so there are a number of specialized functions for reading
--   those values where we've found them useful.
getHeader :: Response -> ByteString -> Maybe ByteString

-- | HTTP Methods, as per RFC 2616
data Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method
PATCH :: Method
Method :: ByteString -> Method

-- | The map of headers in a <a>Request</a> or <a>Response</a>. Note that
--   HTTP header field names are case insensitive, so if you call
--   <tt>setHeader</tt> on a field that's already defined but with a
--   different capitalization you will replace the existing value.
data Headers
emptyHeaders :: Headers

-- | Set a header field to the specified value. This will overwrite any
--   existing value for the field. Remember that HTTP fields names are case
--   insensitive!
updateHeader :: Headers -> ByteString -> ByteString -> Headers

-- | Remove a header from the map. If a field with that name is not
--   present, then this will have no effect.
removeHeader :: Headers -> ByteString -> Headers

-- | Given a list of field-name,field-value pairs, construct a Headers map.
buildHeaders :: [(ByteString, ByteString)] -> Headers
lookupHeader :: Headers -> ByteString -> Maybe ByteString

-- | Get the headers as a field-name,field-value association list.
retrieveHeaders :: Headers -> [(ByteString, ByteString)]

-- | Accessors common to both the outbound and return sides of an HTTP
--   connection.
class HttpType τ

-- | Get the Headers from a Request or Response. Most people do not need
--   this; for most cases you just need to get a header or two from the
--   response, for which you can use <a>getHeader</a>. On the other hand,
--   if you do need to poke around in the raw headers,
--   
--   <pre>
--   import Network.Http.Types
--   </pre>
--   
--   will give you functions like <a>lookupHeader</a> and
--   <a>updateHeader</a> to to work with.
getHeaders :: HttpType τ => τ -> Headers
data HttpParseException
HttpParseException :: String -> HttpParseException