net.http

net.http is an API for making non-blocking HTTP requests to remote servers. When making a request you specify a callback which will receive the data when the response is received.

Reference

Making requests

http.request(url, options, callback)

Initiate a HTTP request to url and call the specified function callback with the response. options is an optional (just pass nil if you don't need it) table to specify extra details about the request. This method does support HTTPS URLs, but does not verify certificates in versions before Prosody 0.11.0.

Returns: A request object (see below)

Upon receiving a response, the callback will be called as follows: callback(response_body, response_code, response)

where response_body is the string of data returned by the server, response_code is the numeric HTTP status code received from the server, and response_object is the full response object, which includes additional info such as the headers received from the server.

options is optionally a table with any combination of the following fields:

options.headers

Specifies a table of custom headers to use. These will overwrite the default headers, but they must be in the correct format and case. eg. "Content-Length" and "Content-Type".

options.body

If supplied then the request is automatically a POST request, and the body is submitted to the HTTP server. The Content-Type defaults to "application/x-www-form-urlencoded" but can be overridden using options.headers as above.

options.method

Will force the specified method to be used.

options.insecure

Disable certificate verification for this request.

Note: Prosody versions before 0.11.0 do not support certificate verification on HTTPS requests.

http.destroy_request(request)

Used for destroying request objects which are no longer wanted. The callback for that request will not be called again. Note that unless you leave a request open (ie. return true from the callback) you do not need to call this function, as the requests will be destroyed automatically after the response is sent.

Utility functions

http.urlencode(str)

Returns an encoded version of the string, using percent-encoding as defined by the URI RFC.

http.urldecode(encoded_str)

Returns str with any percent-encoded characters decoded.

http.formencode(form_data)

Returns a "application/x-www-form-urlencoded" string, based on the input form_data.

form_data may be a table with either key = value pairs:

    form_data = { field1 = "hello", field2 = "world" }

When this format is supplied, the order of the fields in the encoded form is not guaranteed. The HTML specification recommends preserving field ordering, and some applications require it. Therefore you will often want to supply form_data in the below format, which supports both ordering and multiple fields with the same name:

    form_data = {
        { name = "field1", value = "hello" };
        { name = "field2", value = "world" };
    }

http.formdecode(encoded_form_string)

Decodes the supplied "application/x-www-form-urlencoded" string, and returns a form_data structure.

Where it is not required to know the order of fields, nor handle duplicate fields, you may access a field with form_data[field_name]. The returned table also contains an array with each decoded field in the original order however:

    return {
        [1] = { name = "field1", value = "hello" };
        [2] = { name = "field2", value = "world" };
        ["field1"] = "hello";
        ["field2"] = "world";
    }

If the form contains multiple fields with the same name, form_data[field_name] will contain only the value of the last one.