Zephyrdev

zephyr.net

Outbound network access. `tcp_connect` requires `net:tcp`; `http` requires `net:http`; `download` requires both `net:http` and `io`.

4 functions

tcp_connect

net:tcp
zephyr.net.tcp_connect(host, port, timeout_ms?)

Open a TCP connection.

Returns a connection table whose methods use dot notation (no self): write(data), read(n) (reads exactly n bytes), and close().

Parameters

hoststring

Host to connect to.

portnumber

TCP port.

timeout_msnumberoptional

Connect/read/write timeout. Defaults to 5000.

Returns

table

A connection table with write, read, and close.

Raises an error if

  • the net:tcp permission is not granted

Example

lua
local conn = zephyr.net.tcp_connect("example.com", 25565, 3000)
conn.write("hello")
local bytes = conn.read(5)
conn.close()

resolve_srv

net:tcp
zephyr.net.resolve_srv(name, timeout_ms?)

Look up DNS SRV records.

Records are sorted by priority (lowest first), then by weight (highest first), so the first entry is the one to try. A name with no SRV record returns an empty table rather than raising.

Parameters

namestring

Fully-qualified SRV name, e.g. _minecraft._tcp.example.com.

timeout_msnumberoptional

Lookup timeout. Defaults to 5000.

Returns

table

Array of { target, port, priority, weight }; empty when nothing resolves.

Raises an error if

  • the net:tcp permission is not granted

Example

lua
local records = zephyr.net.resolve_srv("_minecraft._tcp.example.com")
local host, port = "example.com", 25565
if records[1] then
  host, port = records[1].target, records[1].port
end

http

net:http
zephyr.net.http(opts)

Send an HTTP request.

Supported methods: GET, POST, PUT, DELETE, PATCH. Unknown methods are sent as GET.

Parameters

optstable

Request: url (required), method (default GET), headers (string map), body (string).

Returns

table

{ status, headers, body }.

Raises an error if

  • the net:http permission is not granted

Example

lua
local response = zephyr.net.http({
  method = "POST",
  url = "https://example.com/api",
  headers = { ["content-type"] = "application/json" },
  body = zephyr.util.json_encode({ ok = true }),
})

download

net:httpio
zephyr.net.download(opts)

Stream a GET response into the module's zephyr.io sandbox.

The body is never converted to text, so this is the correct API for binaries. The file is written to a temp file and moved into place only on a successful 2xx download; non-2xx responses return bytes = 0 and create no file.

Parameters

optstable

Request: url and path (required), plus optional headers (string map) and max_bytes.

Returns

table

{ status, headers, path, bytes }. path is set only when a file was written.

Raises an error if

  • the net:http or io permission is not granted

Example

lua
local result = zephyr.net.download({
  url = asset.browser_download_url,
  path = "/bin/" .. asset.name,
  max_bytes = 50 * 1024 * 1024,
})