Skip to main content

httprequest.sendsync()

Issues the target HTTP request and pauses program execution until the transaction completes

Availability

Agent

Returns

Table — the decoded response from the remote server

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
body String Returned HTTP body (if any)

Statuscode

If the statuscode is 100 or higher, it is 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 headers table are presented in lower case, even if they were received in upper case. According to the RFC2616 specification, headers are case-insensitive.

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.

Example Code

This code uses httprequest.sendsync() to send a simple log message to the Loggly log analysis web service. Because httprequest.sendsync() blocks code execution until the HTTP request completes, we can time the duration of the transaction and log it. Note that the usec key in the table returned by Squirrel’s date() is available only to agent code.