http: HTTP client

This module implements a simple HTTP client.

Here is a short example of making a HTTP GET request:

var h = Http("www.example.com")
h.request("GET", "/index.html")
var r = h.response()
r.status                     -- 200
r.reason                     -- "OK"
r.headers["content-length"]  -- "438"
r.readLn()                 -- "<HTML>" (first line of response body)
r.read()                     -- "<HEAD>..." (rest of the body)
h.close()

Refer to the HTTP 1.1 specification (RFC 2616) for a detailed description of the HTTP protocol.

The Http class

class Http(host[, port])
Construct a HTTP connection object that connects to the specified host. Port 80 is used by default. The optional port argument can be used to override this. If this call returns successfully, a TCP connection has been established with the host.

Http methods

request(method, url[, headers[, body]])
Send a request to the HTTP connection. The method argument must be a valid HTTP method (e.g., "GET" or "POST"). The url argument defines the resource to be fetched.

The optional headers argument should be a sequence of name/value pairs. These are additional headers that will be sent to the server as part of the request. Note that the Host header is automatically sent and should not be included in the headers argument.

The body argument is the request body that will sent to the server. It can be any narrow string. If the body is non-empty, the Content-Length header is automatically set.

response()
Return the response from the server to the oldest sent request as a HttpResponse object. Note that you must either read any previous responses entirely or close them before calling response again for the same connection.
close()
Close the connection and release any allocated system resources. You must call this method for every connection, even if isOpen returns False.

Input operations made on HttpResponse objects related to this connection will fail with IoError when the connection is closed.

isOpen()
Return a boolean indicating if additional requests can be passed to the server using this connection. You must have called response before calling isOpen.
auth(username, password)
Specify the username and password to be used with the following requests performed using this connection. Only HTTP basic authentication is supported.

Note: The username and password are passed as plaintext and thus can potentially be eavesdropped.

The HttpResponse class

This class represents a single response stream from a HTTP server. It inherits from io::Stream and supports all stream input operations. It is instantiated by the Http class.

Note that you do not generally need to close HttpResponse streams.

In addition, it defines the following constant members:

headers
HTTP headers associated with the response an an instance of the Map-like HttpHeaders class.
status
Integer status code of the response. The status codes are described in the HTTP specification.
reason
Reason phrase returned by the server.
version
HTTP version used by the server for this response. It is typically "1.1" or "1.0".

The HttpHeaders class

This class implements an immutable map where keys are strings and are matched ignoring case. It inherits from Map. You should not construct HttpHeader instances by directly calling the constructor.

HttpHeaders objects are used to access HTTP response headers:

r = conn.response()
r.headers.hasKey("content-length")   -- Does the header exist?
r.headers["Content-Type"]            -- Value of the Content-Type header
                                     -- Note: case does not matter
r.headers.keys()                     -- Array of defined header names

Exceptions

class HttpError([message])
This exception is raised on HTTP-specific error conditions. It inherits from IoError.

Constants

HttpPort
The default HTTP port (80).

Functions

DefaultProxy()
Return array (url, port) if a default HTTP proxy is defined using the http_proxy environment variable. The url is a string and the port is an integer. Return nil if no proxy is defined.