Skip to main content

httprequest.sendasync(doneCallback, streamCallback, timeout)

Issues the target HTTP request and registers functions to be executed asynchronously when the HTTP transaction completes

Availability

Agent

Parameters

Name Type Description
doneCallback Function A function that will be executed upon completion of the request
streamCallback Function Optional second handler function for streaming requests
timeout Float or integer Optional timeout in seconds for streaming requests

Returns

Nothing

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.

Example Code

This example sends an HTTP request — a sample log message — to the Loggly log anaylsis web service. The request is sent asynchronously; the function processResponse() is called automatically when the request completes, but the main application code continues in the meantime. httprequest.sendasync() doesn’t block the code.