Udp

UDP sockets, for multiplayer, livecoding, and streaming data.

A socket is bound once and kept in the model. bind! and send! are legal in init!, update!, and tasks, and refused in render!, which draws. receive! waits: it is legal in init!, where it blocks startup, and in tasks, where it parks the task; it is refused in update! and render!.

So sending belongs in update! beside the rest of a frame's work, and receiving belongs in a task:

Msg : [Arrived(List(Udp.Datagram)), ReceiveFailed(Udp.ReceiveError)]

update! = |model, input| {
    socket = model.socket
    if !model.listening {
        Task.spawn!(
            input,
            || match Udp.Socket.receive!(socket, Udp.default_receive) {
                Ok(datagrams) => Arrived(datagrams)
                Err(err) => ReceiveFailed(err)
            },
        )
    }
    dropped = match Udp.Socket.send!(socket, model.peer, position_bytes(input)) {
        Ok({}) => model.dropped
        Err(_) => model.dropped + 1
    }
    answered = !List.is_empty(input.messages)
    Ok({ ..model, dropped, listening: !answered })
}

listening is set from whether this cycle's input answered rather than latched to true, so the next update! starts the next listener. A failed send! is counted rather than propagated: WouldBlock is a full send buffer, an ordinary condition on a busy link, and a position update would rather skip a frame than end the app.

A task delivers exactly one message, so the loop is "receive, answer, and let update! start the next one" rather than a task that loops forever. A task that never returns never delivers anything.

That is also why receive! answers with a whole batch. It parks until the first datagram arrives and then drains what the kernel already has, so one message carries a frame's worth of traffic in arrival order. A receive that answered with a single datagram would cap a respawned listener at one datagram per frame, which is far below what even a small game needs.

Datagrams that arrive while no receive! is pending are not lost: they wait in the operating system's own buffer, and the next receive! returns them immediately. They are lost when that buffer overflows, silently, with no report -- that is the UDP contract, and sequence numbers in the payload are the app's answer to it. Delivery, ordering, and duplication are not promised by the protocol and are not added here.

Framing, retransmission, serialization, discovery, and session state are the app's or a package's. This module moves bytes and nothing else.

Addresses are IPv4 literals. An IPv6 address is InvalidAddress, and there is no name resolution: bind! and send! take a dotted-quad string, never a hostname, because resolving a name waits and neither of these effects does.

This grants the app the network authority the process already has: any port it may bind, any host it may send to. Ports below 1024 usually need privileges, and report PermissionDenied when they are missing. Broadcast and multicast are not enabled.

default_receive : ReceiveConfig

max_datagram_bytes : U64

bind! : Address => Try(Socket, BindError)

Address : { ip : Str, port : U16 }

Datagram : { from : Address, bytes : List(U8) }

reply! : Udp.Socket, Udp.Datagram, List(U8) => Try({}, Udp.SendError)
reply! = |socket, datagram, bytes| Udp.Socket.send!(socket, datagram.from, bytes)

ReceiveConfig : { timeout_ms : U64, max_datagrams : U32 }

BindError : [InvalidAddress, AddressInUse, AddressUnavailable, PermissionDenied, ResourceLimit, Unavailable]

SendError : [InvalidAddress, TooLarge, WouldBlock, Unreachable, PermissionDenied, SendFailed, Unavailable]

ReceiveError : [Timeout, AlreadyReceiving, ReceiveFailed, Unavailable]

:= { handle : Handle, local : Address }

local_address : Socket -> Address

send! : Socket, Address, List(U8) => Try({  }, SendError)

receive! : Socket, ReceiveConfig => Try(List(Datagram), ReceiveError)

stub : Socket