Plugins

http

This plugin sends HTTP requests.

http.get(url, options)and head, post, put, patch, delete http.request(url, options)with { method }

  gives { status, headers, body, url }

method is the HTTP method of http.request; default "GET".

Options:

headersa map, sent as written querya map, added to the end of the URL's query bodytext, bytes or a blob, sent as it is jsondata, sent as JSON forma map, sent as a URL-encoded form uploada map, sent as multipart/form-data; a value is text, or a file: bytes, a blob or { data, name, type } asthe form of body: "text", "json", "bytes" or "blob"; default "text" timeoutfor the whole request: seconds, or text such as "30s"; default 10s redirectsfalse returns a redirect and does not follow it; default true trustcertificates in PEM, the only ones then trusted, at every host; one that cannot be read is an error

Returns:

statusthe status code; 404 and 500 are not errors headersa map, with names in lower case bodythe body, in the form of as urlthe URL that answered, after redirects

A handle to a secret (secrets) may be a value of headers, query, form or upload, the whole body, or the path or query of url.

Corbie does not escape a secret in body: the script escapes it for the text around it with secrets.encoded.
A handle in json is an error.
A request with a secret follows a redirect only to a host that the secret may go to.
Corbie percent-encodes spaces and non-ASCII characters in url, and characters that a path cannot contain, such as " < and >. It changes nothing else: %2F stays %2F.
A user name or a password in url is an error.
Corbie adds User-Agent: corbie, and a Content-Type for json, form, upload and a blob, unless headers has them.
Host, Content-Length, Transfer-Encoding, Trailer and Connection in headers are an error: Corbie writes them from url and the body.
When headers has Accept-Encoding or Range, Corbie does not decompress body.
Corbie follows at most 20 redirects, and checks each host as it checks the first.
body as text, json or bytes is at most 64 MiB. A blob, received or sent, may be any size (blobs).

Errors:

refusedno connection, a certificate that is not trusted, a redirect that is not to http or https, or a 21st redirect timeoutno whole response within timeout not_foundthe host's name does not resolve bad_inputa call written wrongly, such as a body on GET or HEAD, or a body over 64 MiB that is not a blob

Needs these permissions:

net:hosteach host, those of redirects included secret:NAME@net:hosta secret sent to an https URL secret:NAME@net.unencrypted:hosta secret sent to an http URL

This script sends a secret in a header.

allow: [net:api.github.com, "secret:GITHUB_TOKEN@net:api.github.com"]

const r = http.get("https://api.github.com/user", {
  headers: { Authorization: secrets.text`Bearer ${secrets.get("GITHUB_TOKEN")}` },
  as: "json",
})
if (r.status !== 200) throw new Error("GitHub said " + r.status)
return r.body.login                 // gives "octocat"

These calls use the other methods.

allow: [net:example.com]

const orders = "https://example.com/orders"
http.post(orders, { json: { item: "tea" }, as: "json" }).body    // gives { id: 1, item: "tea" }
http.put(orders + "/1", { json: { item: "cake" } }).status       // gives 200
http.patch(orders + "/1", { form: { item: "tea" } }).status      // gives 200
http.head(orders + "/1").status                                  // gives 200
http.delete(orders + "/1").status                                // gives 204
http.request(orders, { method: "OPTIONS" }).status               // gives 204