net_discover(3)

✨ net_discover(3) — the Arcan Lua API page where we go find network besties ✨

🌸 NAME 🌸

net_discover — probe or monitor for compatible hosts or clients on the network. That's the whole vibe: checking who's out there and compatible. 🫶

🦋 SYNOPSIS 🦋

nil
net_discover( function:callback )
net_discover( int:mode, int:trust, function:callback )
net_discover( int:mode, int:trust, string:description,
function:handler(source, status) )

💅 DESCRIPTION 💅

Okay so net_discover is your little scout: it finds other sources or sinks on the network which implement the a12 protocol. Each time a connection is discovered, the callback function is invoked with whatever that could be discerned. 🔍✨

The short argument form uses whatever implementation defined default detection mechanism that is available, with the TRUST_KNOWN level of trust. For more refined control, the mode argument can be set to one of these:

• DISCOVER_PASSIVE — silently listens on available network interfaces (or ones specified through the description argument) for broadcasting clients. Quiet observer energy, honestly. 🤫
• DISCOVER_BROADCAST — periodically announces its presence in a privacy preserving way, assuming that the trust model is set to TRUST_KNOWN. Very "I'm here but make it discreet." 💅
• DISCOVER_SWEEP — cycles through the set of trusted keys, looking for the first possible host for each keyset. The description argument accepts a delay=n:period=m form where delay is a number in seconds between each attempted keyset, and period is the delay in seconds between sweeps. Sweep era. 🧹
• DISCOVER_DIRECTORY — uses a directory server to discover which devices are currently available. This mode can punch through NAT ed networks and is suitable for wide-area network use where you have access to a remote trusted server. The description argument is used to reference the directory server to open. Punching through NAT is lowkey iconic. 🌐
• DISCOVER_TEST — generates fake discovery/lost events, both valid and invalid, at increasingly longer intervals in order to provide testing and automation without causing any network traffic. Zero traffic, all drama. 💀🧪

The trust argument changes how the discover modes behave based on a specified trust model, which can be one of the following:

• TRUST_KNOWN — will only forward and reply to messages that comes from previously known and trusted sources. Known sources are managed through an external keystore, see the arcan-net tool. 🔐
• TRUST_PERMIT_UNKNOWN — (for broadcast, passive and directory) allows interactive verification whether a certain connection should be trusted or not. It's giving "let me check with my bestie first." 👀
• TRUST_TRANSITIVE — (for directory) allows viewing and temporary or permanentily trusting connections that comes from an intermediary dictionary server. Yep, that's the wording. 🫶

The handler callback provides the source vid as well as a status table. This behaves similar to other launch_target style callbacks. The set of useful events is reduced to kind=terminated, and kind=state as the ones of relevance.

💀 NOTES 💀

1. Due to the asynchronous nature of discovery requests, it is possible to receive lost=true without first having discovered the name in question.
2. literally blank in the original — just a number and then silence, bestie 🫥
3. specifying an invalid value for trust or mode is a terminal state transition. So maybe don't unless you're really into terminal states. 🚨

🎀 EXAMPLE 🎀

Here's the example exactly as the page gives it — no edits, just vibes:

function net_discover0()
      net_discover(
      function(source, status)
            if status.kind == "terminated" then
                  delete_image(source)
                  return shutdown()
            elseif status.kind ~= "state" then
                  return
            end
            for k,v in pairs(status) do
                  print(k, v)
            end
      end
      )
end

🦋 SEE ALSO: 🦋

network — that's the one reference, bestie. Go look if you need more. 👑

---

That's the whole page. Source/version: network; date: October 2026; page: net_discover(3). Bye bestie, go discover something iconic 💖✨