ncurl Async

nano cURL - a minimalist http(s) client - async edition.

ncurl_aio(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)

Arguments

url

the URL address.

convert

[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector. Set to FALSE if downloading non-text data.

method

(optional) the HTTP method as a character string. Defaults to 'GET' if not specified, and could also be 'POST', 'PUT' etc.

headers

(optional) a named character vector specifying the HTTP request headers, for example:
c(Authorization = "Bearer APIKEY", "Content-Type" = "text/plain")
A non-character or non-named vector will be ignored.

data

(optional) character string request data to be submitted. If a vector, only the first element is taken, and non-character objects are ignored.

response

(optional) a character vector specifying the response headers to return e.g. c("date", "server"). These are case-insensitive and will return NULL if not present. A non-character vector will be ignored.

timeout

(optional) integer value in milliseconds after which the transaction times out if not yet complete.

tls

(optional) applicable to secure HTTPS sites only, a client TLS Configuration object created by tls_config(). If missing or NULL, certificates are not validated.

Value

An 'ncurlAio' (object of class 'ncurlAio' and 'recvAio') (invisibly). The following elements may be accessed:

• $status - integer HTTP repsonse status code (200 - OK). Use status_code() for a translation of the meaning.

• $headers - named list of response headers supplied in response, or NULL otherwise. If the status code is within the 300 range, i.e. a redirect, the response header 'Location' is automatically appended to return the redirect address.

• $data - the response body, as a character string if convert = TRUE (may be further parsed as html, json, xml etc. as required), or a raw byte vector if FALSE (use writeBin() to save as a file).

Promises

'ncurlAio' may be used anywhere that accepts a 'promise' from the promises package through the included as.promise method.

The promises created are completely event-driven and non-polling.

If a status code of 200 (OK) is returned then the promise is resolved with the reponse body, otherwise it is rejected with a translation of the status code or 'errorValue' as the case may be.

See also

ncurl() for synchronous http requests; ncurl_session() for persistent connections.

Examples

nc <- ncurl_aio(
  "https://postman-echo.com/get",
  response = c("date", "server"),
  timeout = 2000L
)
call_aio(nc)
nc$status
#> [1] 200
nc$headers
#> $date
#> [1] "Thu, 29 May 2025 20:51:31 GMT"
#> 
#> $server
#> [1] "nginx"
#> 
nc$data
#> [1] "{\n  \"args\": {},\n  \"headers\": {\n    \"host\": \"postman-echo.com\",\n    \"x-request-start\": \"t1748551891.709\",\n    \"connection\": \"close\",\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"x-amzn-trace-id\": \"Root=1-6838c8d3-72dba23660ebe29e37660348\"\n  },\n  \"url\": \"https://postman-echo.com/get\"\n}"

if (FALSE) { # interactive() && requireNamespace("promises", quietly = TRUE)
library(promises)
p <- as.promise(nc)
print(p)

p2 <- ncurl_aio("https://postman-echo.com/get") %...>% cat
is.promise(p2)
}