Skip to contents

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

Usage

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 (defaults to 'GET' if not specified).

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 request data to be submitted.

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_session for persistent connections.

Examples

nc <- ncurl_aio("https://www.r-project.org/",
                response = c("date", "server"),
                timeout = 2000L)
call_aio(nc)
nc$status
#> [1] 200
nc$headers
#> $date
#> [1] "Sat, 22 Jun 2024 20:08:06 GMT"
#> 
#> $server
#> [1] "Apache"
#> 
nc$data
#> [1] "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n    <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>R: The R Project for Statistical Computing</title>\n\n    <link rel=\"icon\" type=\"image/png\" href=\"/favicon-32x32.png\" sizes=\"32x32\" />\n    <link rel=\"icon\" type=\"image/png\" href=\"/favicon-16x16.png\" sizes=\"16x16\" />\n\n    <!-- Bootstrap -->\n    <link href=\"/css/bootstrap.min.css\" rel=\"stylesheet\">\n    <link href=\"/css/R.css\" rel=\"stylesheet\">\n\n    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->\n    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->\n    <!--[if lt IE 9]>\n      <script src=\"https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js\"></script>\n      <script src=\"https://oss.maxcdn.com/respond/1.4.2/respond.min.js\"></script>\n    <![endif]-->\n  </head>\n  <body>\n    <div class=\"container page\">\n      <div class=\"row\">\n        <div class=\"col-xs-12 col-sm-offset-1 col-sm-2 sidebar\" role=\"navigation\">\n<div class=\"row\">\n<div class=\"col-xs-6 col-sm-12\">\n<p><a href=\"/\"><img src=\"/Rlogo.png\" width=\"100\" height=\"78\" alt = \"R\" /></a></p>\n<p><small><a href=\"/\">[Home]</a></small></p>\n<h2 id=\"download\">Download</h2>\n<p><a href=\"https://cran.r-project.org/mirrors.html\">CRAN</a></p>\n<h2 id=\"r-project\">R Project</h2>\n<ul>\n<li><a href=\"/about.html\">About R</a></li>\n<li><a href=\"/logo/\">Logo</a></li>\n<li><a href=\"/contributors.html\">Contributors</a></li>\n<li><a href=\"/news.html\">What’s New?</a></li>\n<li><a href=\"/bugs.html\">Reporting Bugs</a></li>\n<li><a href=\"/conferences/\">Conferences</a></li>\n<li><a href=\"/search.html\">Search</a></li>\n<li><a href=\"/mail.html\">Get Involved: Mailing Lists</a></li>\n<li><a href=\"https://contributor.r-project.org/\">Get Involved: Contributing</a></li>\n<li><a href=\"https://developer.R-project.org/\">Developer Pages</a></li>\n<li><a href=\"https://blog.r-project.org/\">R Blog</a></li>\n</ul>\n</div>\n<div class=\"col-xs-6 col-sm-12\">\n<h2 id=\"r-foundation\">R Foundation</h2>\n<ul>\n<li><a href=\"/foundation/\">Foundation</a></li>\n<li><a href=\"/foundation/board.html\">Board</a></li>\n<li><a href=\"/foundation/members.html\">Members</a></li>\n<li><a href=\"/foundation/donors.html\">Donors</a></li>\n<li><a href=\"/foundation/donations.html\">Donate</a></li>\n</ul>\n<h2 id=\"help-with-r\">Help With R</h2>\n<ul>\n<li><a href=\"/help.html\">Getting Help</a></li>\n</ul>\n<h2 id=\"documentation\">Documentation</h2>\n<ul>\n<li><a href=\"https://cran.r-project.org/manuals.html\">Manuals</a></li>\n<li><a href=\"https://cran.r-project.org/faqs.html\">FAQs</a></li>\n<li><a href=\"https://journal.r-project.org\">The R Journal</a></li>\n<li><a href=\"/doc/bib/R-books.html\">Books</a></li>\n<li><a href=\"/certification.html\">Certification</a></li>\n<li><a href=\"/other-docs.html\">Other</a></li>\n</ul>\n<h2 id=\"links\">Links</h2>\n<ul>\n<li><a href=\"https://www.bioconductor.org\">Bioconductor</a></li>\n<li><a href=\"https://r-forge.r-project.org/\">R-Forge</a></li>\n<li><a href=\"https://r-hub.github.io/rhub/\">R-Hub</a></li>\n<li><a href=\"/gsoc.html\">GSoC</a></li>\n</ul>\n</div>\n</div>\n        </div>\n        <div class=\"col-xs-12 col-sm-7\">\n        <h1>The R Project for Statistical Computing</h1>\n<h2 id=\"getting-started\">Getting Started</h2>\n<p>R is a free software environment for statistical computing and\ngraphics. It compiles and runs on a wide variety of UNIX platforms,\nWindows and MacOS. To <strong><a\nhref=\"https://cran.r-project.org/mirrors.html\">download R</a></strong>,\nplease choose your preferred <a\nhref=\"https://cran.r-project.org/mirrors.html\">CRAN mirror</a>.</p>\n<p>If you have questions about R like how to download and install the\nsoftware, or what the license terms are, please read our <a\nhref=\"https://cran.R-project.org/faqs.html\">answers to frequently asked\nquestions</a> before you send an email.</p>\n<h2 id=\"news\">News</h2>\n<ul>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version\n4.4.1 (Race for Your Life)</strong></a> has been released on\n2024-06-14.</li>\n<li>We are deeply sorry to announce that our friend and colleague\nFriedrich (Fritz) Leisch has died. <a href=\"doc/obit/fritz.html\">Read\nour tribute to Fritz here</a>.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version\n4.4.0 (Puppy Cup)</strong></a> has been released on 2024-04-24.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version\n4.3.3 (Angel Food Cake)</strong></a> (wrap-up of 4.3.x) was released on\n2024-02-29.</li>\n<li><a\nhref=\"https://events.linuxfoundation.org/user/register/\"><strong>Registration\nfor useR! 2024</strong></a> has opened with early bird deadline March 31\n2024.</li>\n<li>You can support the R Foundation with a renewable subscription as a\n<a href=\"https://www.r-project.org/foundation/donations.html\">supporting\nmember</a>.</li>\n</ul>\n<h2 id=\"news-via-mastodon\">News via Mastodon</h2>\n<!--\nMastodon widget from https://gitlab.com/idotj/mastodon-embed-feed-timeline\nFiles mastodon-feed-timeline.css and mastodon-feed-timeline.js are from this source\n-->\n<link rel=\"stylesheet\" href=\"mastodon-timeline.css\" />\n<script src=\"mastodon-timeline.js\"></script>\n<link rel=\"stylesheet\" href=\"mastodon-timeline.css\" />\n<script src=\"mastodon-timeline.js\"></script>\n<div class=\"mt-timeline\">\n<div id=\"mt-body\" class=\"mt-body\" role=\"feed\">\n<pre><code>&lt;div class=&quot;loading-spinner&quot;&gt;&lt;/div&gt;</code></pre>\n</div>\n</div>\n<h2 id=\"social-media\">Social Media</h2>\n<!-- rel=\"me\" required to verify on Mastodon -->\n<p>Follow the R Foundation on\n<a rel=\"me\" href=\"https://fosstodon.org/@R_Foundation\">Mastodon</a>,\n<a href=\"https://twitter.com/_R_Foundation\">Twitter</a>, or\n<a href=\"https://www.linkedin.com/company/the-r-foundation-for-statistical-computing\">LinkedIn</a>.</p>\n<!--- (Boilerplate for release run-in)\n-   [**R version 3.1.3 (Smooth Sidewalk) prerelease versions**](https://cran.r-project.org/src/base-prerelease/) will appear starting February 28. Final release is scheduled for 2015-03-09.\n-->\n        </div>\n      </div>\n      <div class=\"raw footer\">\n        &copy; The R Foundation. For queries about this web site, please contact\n\t<script type='text/javascript'>\n<!--\nvar s=\"=b!isfg>#nbjmup;xfcnbtufsAs.qspkfdu/psh#?uif!xfcnbtufs=0b?\";\nm=\"\"; for (i=0; i<s.length; i++) {if(s.charCodeAt(i) == 28){m+= '&';} else if (s.charCodeAt(i) == 23) {m+= '!';} else {m+=String.fromCharCode(s.charCodeAt(i)-1);}}document.write(m);//-->\n\t</script>;\n        for queries about R itself, please consult the \n        <a href=\"help.html\">Getting Help</a> section.\n      </div>\n    </div>\n    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->\n    <script src=\"https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js\"></script>\n    <!-- Include all compiled plugins (below), or include individual files as needed -->\n    <script src=\"/js/bootstrap.min.js\"></script>\n  </body>\n</html>\n"

if (interactive() && requireNamespace("promises", quietly = TRUE)) {

p <- as.promise(nc)
print(p)

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

}