httprequest.sendasync(doneCallback, streamCallback, timeout)

Description

This method issues an HTTP request asynchronously. The registered callback functions are executed when the server responds or if an error is encountered. Other Squirrel code, including other event handlers, continues to run while the HTTP request is being made. This is not the case during a call to httprequest.sendsync().

If the optional timeout for streaming requests is not provided, httprequest.sendasync() defaults to a timeout of 600 seconds (ten minutes). To disable the timeout, set this parameter to the constant NO_TIMEOUT.

The function passed into doneCallback will be invoked with a single parameter, response, which references a table with the same fields as the table returned by httprequest.sendsync():

Key	Type	Description
statuscode	Integer	HTTP status code (or libcurl error code)
headers	Table	Squirrel table of returned HTTP headers. See Headers, below
rawheaders	Array	Squirrel array of HTTP headers. See Headers, below
body	String	Returned HTTP body (if any)

The function passed into streamCallback is optional. If provided, it will be called with a single parameter, content, which will hold a single string of content from the stream.

Statuscode

If the value of response.statuscode is 100 or higher, it represents a real HTTP status code returned from the server; if it is between 0 and 99, there was an error sending the request.

As an aid to debugging, the 0-99 errors are currently the same as libcurl error messages. For instance, statuscode == 3 means that the URL was malformed, and statuscode == 6 means that the hostname wouldn’t resolve. However, this may change in the future, so don’t write agent code that depends on particular values having particular meanings.

You should note that if an error code is generated, you may still get data back, but it will be placed in the body field of the table passed to your doneCallback function rather than arrive via your streamCallback.

Headers

For ease of access from Squirrel, all headers in the response.headers table are presented in lower case, even if they were received in upper case. According to the RFC2616 specification, headers are case-insensitive.

If the response contains duplicated headers, only one of the their values will be included in the response.headers table. Which header’s value is added to table is undefined. If your application could receive duplicate headers in a response, please use response.rawheaders. This key’s value is an array of tables; each table represents one received header: the keys k and v provide the header key and header value, respectively. All received headers, including duplicates, are included in this array. For example:

local url = "https://example.com/api";
http.get(url).sendasync(function(response) {
    foreach (header in response.rawheaders) {
        server.log(header.k + ":" + header.v);
    }
});

Rate Limiting

There is a limit on the number of outbound HTTP requests each agent can make. You have credit for 40 requests. As requests are sent, your credits for further requests regenerate at the rate of two credits per second, up to the maximum of 40. Potentially, this allows you to send up to 120 requests in 60 seconds. However, there is a further limit: you may have no more than 100 connections open at any one time.

If the outbound request exceeds the rate-limit, then the response passed to the callback function will have the status code 429 and the headers table will contain two specific keys. The first of these, retry-after, provides a suggested number of seconds to wait before retrying. The presence of the second key, the non-standard x-agent-rate-limited, indicates that the request was rate-limited locally. If the number of connections exceeds the limit, the response will have headers x-max-active-transfers: 100 and x-agent-active-transfer-limit-exceeded: Yes.

This feature is independent of any rate-limiting that the remote server may apply.