@head @module http @title http: HTTP client

This module implements a simple HTTP client.

Here is a short example of making a HTTP GET request: @example 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() @end

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

Class Http

@class Http(host as Str[, port as Int]) @desc 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. @end

Http methods

@fun request(method as Str, url as Str[, headers as Array>[, body as Str]]) @desc 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. @end @fun response() as HttpResponse @desc Return the response from the server to the oldest sent request as a @ref{HttpResponse} object. Note that you must either read any previous responses entirely or close them before calling response again for the same connection. @end @fun close() @desc 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 @ref{HttpResponse} objects related to this connection will fail with @ref{IoError} when the connection is closed. @end @fun isOpen() as Boolean @desc Return a boolean indicating if additional requests can be passed to the server using this connection. You must have called response before calling isOpen. @end @fun auth(username as Str, password as Str) @desc 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. @end @end

Class HttpResponse

@inherits Stream @supertypes @class-hidden HttpResponse

This class represents a single response stream from a HTTP server. It inherits from @ref{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: @var headers as HttpHeaders @desc HTTP headers associated with the response an an instance of the Map-like @ref{HttpHeaders} class. @end @var status as Int @desc Integer status code of the response. The status codes are described in the HTTP specification. @end @var reason as Str @desc Reason phrase returned by the server. @end @var version as Str @desc HTTP version used by the server for this response. It is typically "1.1" or "1.0". @end

Class HttpHeaders

@inherits Map @supertypes @class-hidden HttpHeaders

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

HttpHeaders objects are used to access HTTP response headers: @example 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 @end

Exceptions

@class HttpError([message as Str]) @desc This exception is raised on HTTP-specific error conditions. It inherits from @ref{IoError}. @end @end-class

Constants

@var HttpPort as Int @desc The default HTTP port (80). @end

Functions

@fun DefaultProxy() as (Str, Int) @desc Return a tuple (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. @end