@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.
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
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
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