net_open(3)

📦
version 0.7.1 · 2 versions
, in nixos 26.05

🦋 net_open(3) — the Arcan Lua API one where you make an outbound connection 🦋

okay bestie, this is net_open from the Arcan Lua API, and it's literally your little portal to the network. buckle up 💖

✨ NAME ✨

net_open — Make an outbound connection to a data source. that's it, that's the whole vibe 🫶

🌸 SYNOPSIS 🌸

vid or BADID
net_open( str:host, function:handler(source:vid, strtbl:status) )
net_open( str:host, str:dst, function:handler(source:vid, strtbl:status)
)

so you get back a vid or a BADID, and there are two ways to call it: the short one and the one with a dst in the middle. both take a handler that receives source:vid and strtbl:status. iconic signature honestly ✨

💅 DESCRIPTION 💅

This creates an outbound connection to a network resource speaking the a12 protocol. no cap, that's the whole deal.

If host starts with an @ sign and matches a known tag in the keystore, the connection information and authentication credentials will be picked from there. so you don't gotta hand over your secrets, the keystore's got you 🎀

If hosts starts with a ? sign it works as with '@' but the connection will only probe which roles the target supports (source, sink or directory) and return that as a message event before terminating. it's giving "just checking the vibe check" 🔍

If the host is a tag, the optional dst argument can be used to override the hosts assigned to the tag but still use the keymaterial. This is mainly to work with discovery modes such as 'passive' where the tag was found, but using a dynamic address. highkey useful 🧚

The connection behaves just as if it had been initiated through launch_target or target_alloc but the primary segment will be a network type referencing the connection itself and the actual resource will come as a segment_request. so like, the real one shows up later, main character energy 🫶

If host starts with the reserved identifier @stdin it will try and connect to an attached monitor and communicate through it with an external directory server and the associated appl- group of others running the same appl through the same directory. found family, but in a directory 🌈

The restricted short (alnum _) identifier used server side is determined first by the arcan-net --ident argument (or when opening the directory through net_discover) and, on collision, generated by the directory server. The one actually used will be provided in a 'message' event as 'a12:join= XXXXXX ' where the Xs are substituted with the actual identity. so check your mail, bestie 💌

Any higher level 'nickname' system is expected to be implemented as a nested application specific protocol within the appl- message group. that part's on you, i don't make the rules 💀

Should the connection be severed, an a12:disconnected will be issued, and when if/it can be resumed, a12:reconnected. so you'll know, and you'll know again 😭

Message events received in this format must follow the argument packing in builtin/string.lua:strings.unpack_shmif_argstr(src) (key=value with ':' as separator, being substituted to ':'). They have quite short restrictions (78b) and are not intended for large datastream serialisation since they can have large amplification and trigger throttling in the processing chain. For large transfers we have open_nonblock or using the directory to create a direct channel to a specific user. The server end will enforce a prefix of from=name and reserve the use of an 'a12' key anywhere. It will reject messages which attempts to use that. 🔥

fr fr: keep those messages tiny. 78b is not a suggestion, and if you try to shove a whole datastream through them you're gonna get throttled in the processing chain. use open_nonblock or a direct channel for the big stuff. 🍓

🎀 NOTES 🎀

  1. with @stdin:user expect deliveries to have multipart, meaning they need to be concatenated until a terminating multipart=false arrives. don't treat each chunk as a whole thing, that's the trap 🙈
  2. (nothing here, the original literally leaves it blank — slay of it ✨)

⭐ EXAMPLE ⭐

function net_open0()
      net_open("laptop",
      function(source, status)
            if status.kind == "segment_request" then
                  accept_target(0, 0,
                        function(source, status)
                              if status.kind == "resized" then
                                    show_image(source)
                                    resize_image(source, status.width, status.height)
                              end
                        end
                  )
            end
            if status.kind == "terminated" then
                  print("died", status.last_words)
                  delete_image(source)
                  return shutdown()
      end)
end

⭐ EXAMPLE ⭐

function net_open1()
      local vid = net_open("@stdin:me",
            function(source, status)
                  if status.kind == "message" then
                  end
            end
      )
      if not valid_vid(vid) then
            print("not connected to a directory server")
      end
end

🦋 SEE ALSO: 🦋

go read those next, iykyk 👑

okay that's the whole page, no gatekeeping 💜 this was documented by network for the October 2026 edition, and it's filed under net_open(3) — so when you cite it, cite it cute. bye bestie, go make some outbound connections 🎀✨🌸💅

📦 where this page comes from