httprequest.sendsync()

Description

This method executes a synchronous (blocking) HTTP request. No other Squirrel code in the agent will execute until the server returns or an error occurs. If this is undesirable behavior, you should use httprequest.sendasync().

The returned table has the same fields as the table passed into httprequest.sendasync()’s callback function:

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)

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 — it will be placed in the body field.

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";
local response = http.get(url).sendsync();
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. Rate limiting is per agent, not per account.