app.network - Network Information API

Network interfaces, WiFi, connectivity, and DNS information.

Methods

app.network.interfaces()

Get a list of all network interfaces.

Returns: array<table> - each item contains:

• name (string) - interface name (e.g., “en0”)
• ip (string) - IP address
• mac (string, optional) - MAC address
• type (string) - type: "wifi", "ethernet", "loopback", "vpn", "bridge", "other"
• isUp (boolean) - whether the interface is active
• family (string) - "ipv4" or "ipv6"

local ifaces = app.network.interfaces()
for _, iface in ipairs(ifaces) do
    app.log.info(iface.name .. ": " .. iface.ip .. " (" .. iface.type .. ")")
end

app.network.localIP()

Get the local LAN IP address.

Returns: string|nil - first active non-loopback IPv4 address

local ip = app.network.localIP()  -- "192.168.1.100"

app.network.wifiSSID()

Get the name of the currently connected WiFi network.

Returns: string|nil - WiFi SSID

local ssid = app.network.wifiSSID()  -- "MyNetwork"

app.network.wifiSignal()

Get the WiFi signal strength.

Returns: number|nil - RSSI value (negative number, e.g., -45 indicates good signal)

local rssi = app.network.wifiSignal()  -- -42

app.network.isConnected()

Check internet connectivity.

Returns: boolean

if app.network.isConnected() then
    app.log.info("Connected to the internet")
end

app.network.externalIP()

Get the public IP address (via api.ipify.org).

Returns: string, error

local ip, err = app.network.externalIP()  -- "203.0.113.1"

app.network.dns()

Get the list of DNS servers.

Returns: array<string>

local servers = app.network.dns()  -- {"8.8.8.8", "8.8.4.4"}

app.network.resolve(hostname)

Resolve a hostname to a list of IP addresses synchronously (since 1.3.0). Returns both IPv4 and IPv6 addresses, de-duplicated.

Parameters:

• hostname (string) - Host name to resolve

Returns: array<string>, err

local ips, err = app.network.resolve("www.apple.com")
if ips then
    for _, ip in ipairs(ips) do app.log.info(ip) end
end

app.network.ping(host, opts?)

Test connectivity via the system /sbin/ping tool (since 1.3.0). Blocks until complete. Returns RTT statistics.

Parameters:

• host (string) - Target host (IP or domain)
• opts (table, optional)
  • count (number) - Number of probes (default 4, max 30)
  • timeout (number) - Total ping timeout in seconds (default 2, max 30; ping self-exits at deadline)

Returns: table, err — fields:

• rtt_avg (number) - Average round-trip time (ms)
• rtt_min (number) - Minimum RTT (ms)
• rtt_max (number) - Maximum RTT (ms)
• loss (number) - Packet-loss percentage
• count (number) - Actual probe count

local stats, err = app.network.ping("127.0.0.1", { count = 3 })
if stats then
    app.log.info(string.format("loss=%.1f%% avg=%.2fms", stats.loss, stats.rtt_avg))
end

Event Watching

app.network.watch(event, callback)

Watch for network status change events.

Parameters:

• event (string) - event name (currently only "networkChanged" is supported)
• callback (function) - callback function, receives an event table:
  • isConnected (boolean) - whether the Mac is connected to the internet
  • interfaceType (string) - current interface type:
    • "wifi" - wireless network
    • "wired" - wired (Ethernet) network
    • "cellular" - cellular network
    • "other" - other type
    • "none" - no network
  • isExpensive (boolean) - whether the connection is metered (e.g., personal hotspot)

Returns: string, error - watcher handle ID

app.network.watch("networkChanged", function(e)
    if e.isConnected then
        app.log.info("Network connected, type: " .. e.interfaceType)
        if e.isExpensive then
            app.log.info("Note: using a metered connection")
        end
    else
        app.log.info("Network disconnected")
    end
end)

app.network.stopAllWatchers()

Stop all network event watchers registered by the current plugin.

Returns: boolean

app.network.stopAllWatchers()

app.network.listWatchers()

List all network event watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

local watchers = app.network.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

Examples

Network Diagnostics

function MyPlugin:handleDiagnose(context)
    local info = "Network Diagnostics Report\n" .. string.rep("=", 30) .. "\n\n"

    -- Basic info
    info = info .. "Local IP: " .. (app.network.localIP() or "None") .. "\n"
    info = info .. "WiFi: " .. (app.network.wifiSSID() or "Not connected") .. "\n"

    local rssi = app.network.wifiSignal()
    if rssi then
        info = info .. "Signal strength: " .. rssi .. " dBm\n"
    end

    info = info .. "Internet: " .. (app.network.isConnected() and "Connected" or "Disconnected") .. "\n"

    -- Public IP
    local extIP = app.network.externalIP()
    info = info .. "Public IP: " .. (extIP or "Unavailable") .. "\n"

    -- DNS
    local dns = app.network.dns()
    info = info .. "DNS: " .. table.concat(dns, ", ") .. "\n"

    app.dialog.alert("Network Diagnostics", info)
end