Skip to main content

Network API

Handles Networking related operations.

network.currentStats​

Signatures​

currentStats(lua)

Description​

Get network statistics for the current session.

Returns a table with the following fields:

  • rx_total_bytes - Bytes received since the session started
  • tx_total_bytes - Bytes transmitted since the session started
  • rx_bytes - Receive throughput over the last interval, in kbps
  • tx_bytes - Transmit throughput over the last interval, in kbps
  • rx_packets - Packets received over the last interval
  • tx_packets - Packets transmitted over the last interval
  • rx_errors - Receive errors over the last interval
  • tx_errors - Transmit errors over the last interval
  • rx_dropped - Dropped received packets over the last interval
  • tx_dropped - Dropped transmitted packets over the last interval
  • multicast - Multicast packets over the last interval
  • collisions - Network collisions over the last interval
  • interval_ms - Length of the interval, in milliseconds

Example​

local stats = network.currentStats()
print("received: " .. stats.rx_total_bytes .. " bytes")
print("sent: " .. stats.tx_total_bytes .. " bytes")

network.disable​

Signatures​

disable()

Description​

Disable network connectivity.

Adds a traffic control rule to simulate a network outage. This effectively disconnects the device from the network.

Note: If rate limiting was active before the network was disabled, the setting will not be restored after the network is re-enabled. You must call network.enableRateLimit() again to re-enable rate limiting.

Example​

-- Disable network connectivity
network.disable()

network.disableRateLimit​

Signatures​

disableRateLimit(opts \ [], lua)

Description​

Disable network rate limiting.

Removes any active bandwidth restrictions and returns network to full speed.

Options​

  • delay - Delay in milliseconds before disabling rate limiting (default: 0)

Example​

-- Disable rate limiting immediately
network.disableRateLimit()

-- Disable rate limiting after 1 second
network.disableRateLimit({delay = 1000})

network.do_request​

Signatures​

do_request(url, opts \ [])

Description​

Elixir-facing entry point so tests can call Network.request/2 directly without threading a %Lua{} through. Accepts a decoded keyword/map of opts and returns a plain map (no Lua encoding).

network.enable​

Signatures​

enable()

Description​

Enable network connectivity.

Removes applied traffic control rules to restore normal network operation. If network is already enabled, this function has no effect.

Note: If rate limiting was active before the network was disabled, the setting will not be restored after the network is re-enabled. You must call network.enableRateLimit() again to re-enable rate limiting.

Example​

-- Enable network connectivity
network.enable()

network.enableRateLimit​

Signatures​

enableRateLimit(limit_down_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, opts, lua)

Description​

Enable network rate limiting with download speed limit only.

Restricts the download bandwidth to the specified limit. Upload bandwidth remains unlimited.

Note: This function requires network connectivity to be enabled. If the network is currently disabled (e.g. network.disable() was called), you must call network.enable() first before enabling rate limiting.

Parameters​

  • limit_down_mbit - Download speed limit in megabits per second

Example​

-- Limit download to 10 Mbps
network.enableRateLimit(10)

network.enableRateLimit​

Signatures​

enableRateLimit(limit_down_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, opts, lua)

Description​

Enable network rate limiting with both download and upload speed limits.

Restricts both download and upload bandwidth to the specified limits.

Note: This function requires network connectivity to be enabled. If the network is currently disabled (e.g. network.disable() was called), you must call network.enable() first before enabling rate limiting.

Parameters​

  • limit_down_mbit - Download speed limit in megabits per second
  • limit_up_mbit - Upload speed limit in megabits per second

Example​

-- Ensure network is enabled first
network.enable()

-- Then limit download to 10 Mbps and upload to 5 Mbps
network.enableRateLimit(10, 5)

network.enableRateLimit​

Signatures​

enableRateLimit(limit_down_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, lua)

enableRateLimit(limit_down_mbit, limit_up_mbit, opts, lua)

Description​

Enable network rate limiting with download, upload limits and additional options.

Restricts both download and upload bandwidth with support for delayed activation.

Note: This function requires network connectivity to be enabled. If the network is currently disabled (e.g. network.disable() was called), you must call network.enable() first before enabling rate limiting.

Parameters​

  • limit_down_mbit - Download speed limit in megabits per second
  • limit_up_mbit - Upload speed limit in megabits per second
  • opts - Options table

Options​

  • delay - Delay in milliseconds before enabling rate limiting (default: 0)

Example​

-- Enable rate limiting after 2 seconds
network.enableRateLimit(10, 5, {delay = 2000})

network.isEnabled​

Signatures​

isEnabled()

Description​

Check if network connectivity is currently enabled.

Returns the current status of network connectivity.

Returns true if network is enabled, false if network is disabled.

Example​

local is_enabled = network.isNetworkEnabled()

if is_enabled then
  print("Network is currently enabled")
else
  print("Network is currently disabled")
end

network.isNetworkCaptureActive​

Signatures​

isNetworkCaptureActive(opts \ [], lua)

Description​

Returns whether network capture is currently active (true/false).

Options​

  • timeout - Max ms to wait for the strategy call (default: 5000).

network.isRateLimitActive​

Signatures​

isRateLimitActive()

Description​

Check if network rate limiting is currently active.

Returns the current status of network rate limiting.

Returns true if rate limiting is enabled, false otherwise.

Example​

local is_limited = network.isRateLimitActive()

if is_limited then
  print("Network rate limiting is currently active")
else
  print("Network is running at full speed")
end

network.request​

Signatures​

request(url, opts \ [], lua)

Description​

Makes an HTTP request and returns the response.

Options​

  • method: One of "GET", "POST", "PUT", "PATCH", "DELETE" or "HEAD" (default: "GET")
  • headers: A table of HTTP headers
  • body: The request body (for POST, PUT, etc.). Maximum size is 10 MB.
  • auth: Authentication method and credentials
  • params: Query parameters
  • timeout: Request timeout in milliseconds

Returns a table with:

  • status: HTTP status code
  • body: Response body (decoded)
  • error: Error message (if any)

Example​

local response = network.request("https://api.example.com/data", {
  method = "GET",
  headers = {["Content-Type"] = "application/json"},
  auth = {type = "bearer", token = "my-token"},
  params = {limit = 10, offset = 0}
})

Only supports json at the moment

network.startNetworkCapture​

Signatures​

startNetworkCapture(opts \ [], lua)

Description​

Start network capture process for a session.

Options​

  • mode - Capture backend: "cdp" or "proxy" (default: the platform's default). Any other value fails the call rather than falling back.
  • reload - Reload page when starting CDP capture (default: true, cdp mode only)
  • cache - Use cache when starting CDP capture (default: true, cdp mode only)
  • timeout - Max ms to wait for capture to begin (default: 30 seconds)
  • name - Capture name (default: capture_ + UTC timestamp)
  • direct_proxy - Use regular proxy mode instead of transparent (default: false, proxy mode only, ignored on VegaOS, which always uses the direct proxy)

Returns a table with success (boolean) and optional error (string).

End to end example​

local result = network.startNetworkCapture()
if result.success then
  -- do work
  network.stopNetworkCapture()
end

Choosing a mode​

A capture must be stopped before starting one in a different mode.

network.startNetworkCapture({ mode = "proxy" })
-- do work
network.stopNetworkCapture()

network.stats​

Signatures​

stats(lua)

Description​

Get network interface statistics.

Returns detailed network statistics including bytes transferred, packets, errors, and other network metrics.

Returns a table containing network statistics with the following fields:

  • rx_bytes - Bytes received
  • tx_bytes - Bytes transmitted
  • rx_packets - Packets received
  • tx_packets - Packets transmitted
  • rx_errors - Receive errors
  • tx_errors - Transmit errors
  • rx_dropped - Dropped received packets
  • tx_dropped - Dropped transmitted packets
  • multicast - Multicast packets
  • collisions - Network collisions

Example​

local stats = network.stats()

for i, stat_table in ipairs(stats) do
  for j, stat in ipairs(stat_table) do
    local name, value = stat[1], stat[2]
    print(name .. ": " .. value)
  end
end

network.stopNetworkCapture​

Signatures​

stopNetworkCapture(opts \ [], lua)

Description​

Stop network capture process for a session and save it. Blocks until the upload completes.

Options​

  • timeout - Max ms to wait for stop to complete (default: 30 seconds)

Returns a table with success (boolean), optional error (string), and optional size (bytes uploaded).