net
HTTPS requests to the hosts the script's manifest lists, and nothing else.
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): RequestStarts a request.
| Parameter | Type | Description |
|---|---|---|
options | table | {url, method = "GET" | "POST", headers = {...}, body, timeout, on_done = fn(res)}. url is required; timeout is in seconds (1 to 20, default 10). |
| Returns | Description |
|---|---|
Request | A request handle. |
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): RequestA GET request.
| Parameter | Type | Description |
|---|---|---|
url | string | An https URL on an allowed host. |
fn optional | function | Called with the response. default nil |
| Returns | Description |
|---|---|
Request | A request handle. |
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): RequestA POST request.
| Parameter | Type | Description |
|---|---|---|
url | string | An https URL on an allowed host. |
body | string | The request body. |
fn optional | function | Called with the response. default nil |
headers optional | table | Allowed headers. default nil |
| Returns | Description |
|---|---|
Request | A request handle. |
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.
| Returns | Description |
|---|---|
string[] | The hosts in the manifest's net_hosts. |
NetResponse#
What a callback or task.await receives.
| Field | Type | Description |
|---|---|---|
ok | boolean | The request completed with a success status. |
status | integer | HTTP status (0 when the request failed before an answer). |
body | string | The response body. |
error | string | nil | A message when it failed. |
headers | table | Response 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(): booleanCancels the request.
| Returns | Description |
|---|---|
boolean | true when a request was cancelled. |
req:is_done#since 1.0
req:is_done(): booleanAsks whether the request has finished.
| Returns | Description |
|---|---|
boolean | Whether the answer has arrived. |