wolfhacklua API 1.1 Forum

net

HTTPS requests to the hosts the script's manifest lists, and nothing else.

since 1.0permission: net

Needs the net permission and a "net_hosts" list in the manifest (host names such as api.example.com: no scheme, no path, no IP address, at most 8). The user sees the hosts when granting the permission.

Limits: HTTPS only, only the listed hosts, no redirects, no cookies, GET and POST only, these request headers only: accept, content-type, authorization, accept-language, if-none-match, x-api-key. At most 256 KB sent and 4 MB received per request, 30 requests a minute, 4 at a time.

Requests run on worker threads. The answer arrives in a later frame, either through the callback or through task.await(request).

Reference#

net.request#permission: netsince 1.0

net.request(options: table): Request

Starts a request.

ParameterTypeDescription
optionstable{url, method = "GET" | "POST", headers = {...}, body, timeout, on_done = fn(res)}. url is required; timeout is in seconds (1 to 20, default 10).
ReturnsDescription
RequestA request handle.
lua
net.request{ url = "https://api.example.com/v1/ping", method = "GET", on_done = function(res)
  if res.ok then log.info(res.body) else log.warn(res.error or res.status) end
end }

net.get#permission: netsince 1.0

net.get(url: string, fn?: function): Request

A GET request.

ParameterTypeDescription
urlstringAn https URL on an allowed host.
fn optionalfunctionCalled with the response. default nil
ReturnsDescription
RequestA request handle.
lua
local req = net.get("https://api.example.com/x")
task.spawn(function()
  local res = task.await(req)
  if res then log.info(res.status) end
end)

net.post#permission: netsince 1.0

net.post(url: string, body: string, fn?: function, headers?: table): Request

A POST request.

ParameterTypeDescription
urlstringAn https URL on an allowed host.
bodystringThe request body.
fn optionalfunctionCalled with the response. default nil
headers optionaltableAllowed headers. default nil
ReturnsDescription
RequestA request handle.
lua
net.post("https://api.example.com/log", json.encode({ ok = true }), nil, { ["content-type"] = "application/json" })

net.hosts#since 1.0

net.hosts(): string[]

Lists the hosts this script may contact.

ReturnsDescription
string[]The hosts in the manifest's net_hosts.

NetResponse#

What a callback or task.await receives.

FieldTypeDescription
okbooleanThe request completed with a success status.
statusintegerHTTP status (0 when the request failed before an answer).
bodystringThe response body.
errorstring | nilA message when it failed.
headerstableResponse headers with lower-case names.

Request#

Returned by every net function. You can pass it to task.await.

req:cancel#since 1.0

req:cancel(): boolean

Cancels the request.

ReturnsDescription
booleantrue when a request was cancelled.

req:is_done#since 1.0

req:is_done(): boolean

Asks whether the request has finished.

ReturnsDescription
booleanWhether the answer has arrived.
API 1.1 · source docs-src/api/net.json