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.