UDP Socket Design

[SeanTAllen]

UDP Socket Design

Problem

Lori covers TCP. It doesn't cover UDP.

On the TCP side, connection logic lives in a plain class that the user's actor holds and delegates to — the enclosing actor. The TCP design needs this split because connection lifecycle is complex: Happy Eyeballs (parallel connection attempts across resolved addresses, picking the first to succeed), SSL handshaking, graceful shutdown, send buffering. UDP is simpler. A socket binds to an address, sends and receives datagrams, and closes. No connection handshake, no graceful shutdown, no send buffer to drain.

The class-in-actor split applies to UDP too. UDPSocket is a class the enclosing actor holds. I/O is replaceable for testing through a backend trait — a trait that abstracts the FFI calls, with a type parameter on UDPSocket that swaps in a fake for tests. A state machine tracks lifecycle. The enclosing actor implements two traits — UDPSocketActor for event-dispatch boilerplate, UDPLifecycleEventReceiver for callbacks. _on_received returns a ReadAction (KeepReading to continue reading, YieldReading to pause and yield to the scheduler). UDP has no equivalent of TCP's mute/unmute (datagrams have no backpressure to signal), no send tokens (TCP's mechanism for tracking when sent bytes reach the OS; UDP sends are synchronous and all-or-nothing), and no write-side resubscription (a UDP send that can't go out returns EWOULDBLOCK and the caller decides what to do).

Consumer Sketches

Echo server

use "lori"
use net = "net"

actor Main
  new create(env: Env) =>
    UDPEchoServer(UDPAuth(env.root), "", "9999", env.out)

actor UDPEchoServer is (UDPSocketActor & UDPLifecycleEventReceiver)
  var _udp: UDPSocket = UDPSocket.none()
  let _out: OutStream

  new create(auth: UDPAuth, host: String, port: String, out: OutStream) =>
    _out = out
    _udp = UDPSocket(auth, host, port, this, this)

  fun ref _socket(): UDPSocket =>
    _udp

  fun ref _on_bound() =>
    _out.print("Echo server bound.")

  fun ref _on_bind_failure() =>
    _out.print("Failed to bind UDP socket.")

  fun ref _on_received(data: Array[U8] iso, from: net.NetAddress val)
    : ReadAction
  =>
    match _udp.send_to(consume data, from)
    | SendToOk => None
    | let e: SendToFailure =>
      _out.print("send failed")
    end
    KeepReading

  fun ref _on_closed() =>
    _out.print("Socket closed.")

Same structural pattern as TCP.

Send-only client

use "lori"
use net = "net"

actor UDPClient is (UDPSocketActor & UDPLifecycleEventReceiver)
  var _udp: UDPSocket = UDPSocket.none()
  let _out: OutStream
  let _dest: net.NetAddress val

  new create(auth: UDPAuth, dest: net.NetAddress val, out: OutStream) =>
    _out = out
    _dest = dest
    _udp = UDPSocket(auth, "", "0", this, this)

  fun ref _socket(): UDPSocket =>
    _udp

  fun ref _on_bound() =>
    match _udp.send_to("Hello, server!", _dest)
    | SendToOk => None
    | let e: SendToFailure =>
      _out.print("Failed to send")
      _udp.close()
    end

  fun ref _on_bind_failure() =>
    _out.print("Failed to bind.")

  fun ref _on_closed() =>
    _out.print("Done.")

Binds to port "0" (OS-assigned ephemeral port) and sends one datagram in _on_bound. _on_received is not overridden; the default returns KeepReading and arriving data goes unread.

Error handling

  match _udp.send_to(consume data, from)
  | SendToOk =>
    // Datagram handed to the OS.
    None
  | SendToWouldBlock =>
    // OS send buffer full (EWOULDBLOCK/EAGAIN/ENOBUFS). Datagram NOT sent.
    // Caller decides whether to retry, queue, or drop.
    None
  | SendToNotOpen =>
    // Socket is not bound or already closed.
    None
  | SendToError =>
    // Other sendto error (e.g., ENETUNREACH). Datagram NOT sent.
    // Socket stays open.
    None
  end

send_to returns a four-variant union (defined below under Send result types).

Test with fake backend

use "pony_test"
use "lori"
use net = "net"

class \nodoc\ _TestUDPEcho is UnitTest
  fun name(): String => "UDP echo via fake backend"

  fun apply(h: TestHelper) =>
    h.long_test(2_000_000_000)
    _UDPEchoTestActor[_FakeUDPBackend](h)

actor \nodoc\ _UDPEchoTestActor[UDP: UDPBackend ref]
  is (UDPSocketActor[UDP] & UDPLifecycleEventReceiver[UDP])

  var _udp: UDPSocket[UDP] = UDPSocket[UDP].none()
  let _h: TestHelper

  new create(h: TestHelper) =>
    _h = h
    _udp = UDPSocket[UDP](UDPAuth(_h.env.root), "", "9999", this, this)

  fun ref _socket(): UDPSocket[UDP] =>
    _udp

  fun ref _on_bound() => None

  fun ref _on_bind_failure() =>
    _h.fail("Bind failed")
    _h.complete(false)

  fun ref _on_received(data: Array[U8] iso, from: net.NetAddress val)
    : ReadAction
  =>
    let s = String.from_array(consume data)
    _h.assert_eq[String]("hello", s)
    match _udp.send_to(s, from)
    | SendToOk =>
      _h.complete(true)
    | let e: SendToFailure =>
      _h.fail("Send failed")
      _h.complete(false)
    end
    KeepReading

  fun ref _on_closed() => None

The type parameter substitutes a test double for the real backend. No real sockets, no ports, no I/O. Same pattern as TCP's backend parameterization.

Type Definitions

UDPAuth

primitive UDPAuth
  new create(from: (AmbientAuth | NetAuth)) => None

Added to existing auth.pony. Accepts AmbientAuth or NetAuth, no sub-split.

UDPBackend

trait ref UDPBackend
  new create()

  fun ref bind(the_actor: AsioEventNotify,
    host: String, port: String,
    ip_version: IPVersion = DualStack): AsioEventID

  fun ref close(fd: U32)

  fun ref recvfrom(event: AsioEventID,
    buffer: Pointer[U8] tag, size: USize)
    : (SocketResult, USize, net.NetAddress iso^)

  fun ref sendto(fd: U32,
    data: ByteSeq,
    to: net.NetAddress box): SocketResult

  fun ref sockname(fd: U32, ip: net.NetAddress tag): Bool

Five methods. The names are bind, not listen; UDP sockets bind, they don't listen. IPVersion and SocketResult are Lori's existing types. SocketResult is a tri-state (SocketResultOk, SocketResultRetry, SocketResultError); SocketResultDecoder maps FFI return codes to it.

recvfrom returns the sender address as part of its return tuple rather than through an out-parameter. With an out-parameter from: net.NetAddress tag, fake backends would have to use @memcpy FFI to fill in the address, which defeats the point of a testable backend trait.

sendto returns SocketResult only, no byte count. POSIX datagram sendto is all-or-nothing; the count is always 0 or data.size(), so returning it adds nothing.

UDPRuntimeBackend

class UDPRuntimeBackend is UDPBackend
  new create() => None

  fun ref bind(the_actor: AsioEventNotify,
    host: String, port: String,
    ip_version: IPVersion = DualStack): AsioEventID
  =>
    match \exhaustive\ ip_version
    | IP4 => @pony_os_listen_udp4(the_actor, host.cstring(), port.cstring())
    | IP6 => @pony_os_listen_udp6(the_actor, host.cstring(), port.cstring())
    | DualStack => @pony_os_listen_udp(the_actor, host.cstring(), port.cstring())
    end

  fun ref close(fd: U32) => @pony_os_socket_close(fd)

  fun ref recvfrom(event: AsioEventID,
    buffer: Pointer[U8] tag, size: USize)
    : (SocketResult, USize, net.NetAddress iso^)
  =>
    var count: USize = 0
    let from = recover iso net.NetAddress end
    let result = SocketResultDecoder(
      @pony_os_recvfrom(event, buffer, size, from, addressof count))
    (result, count, consume from)

  fun ref sendto(fd: U32, data: ByteSeq,
    to: net.NetAddress box): SocketResult
  =>
    var count: USize = 0
    SocketResultDecoder(
      @pony_os_sendto(fd, data.cpointer(), data.size(), to, addressof count))

  fun ref sockname(fd: U32, ip: net.NetAddress tag): Bool =>
    @pony_os_sockname(fd, ip)

The real backend. Wraps ponyc's UDP FFI calls through SocketResultDecoder.

State machine

_UDPNone   -> _UDPOpen   (bind succeeded)
           -> _UDPClosed (bind failed)
_UDPOpen   -> _UDPClosed (close)
_UDPClosed (terminal)

Three states. _UDPNone handles the dispose/init race: if dispose() arrives before _finish_initialization(), _UDPNone.close() transitions to _UDPClosed, and _finish_initialization() checks for _UDPClosed and returns early. This matches TCP's guard at tcp_connection.pony:1917-1918.

trait _UDPSocketState[UDP: UDPBackend ref]
  fun ref event_notify(sock: UDPSocket[UDP] ref, flags: U32)
  fun ref send_to(sock: UDPSocket[UDP] ref,
    data: ByteSeq, to: net.NetAddress box): SendToResult
  fun ref close(sock: UDPSocket[UDP] ref)
  fun ref read_again(sock: UDPSocket[UDP] ref)
  fun ref getsockopt(sock: UDPSocket[UDP] ref,
    level: I32, option_name: I32, option_max_size: USize)
    : (U32, Array[U8] iso^)
  fun ref getsockopt_u32(sock: UDPSocket[UDP] ref,
    level: I32, option_name: I32): (U32, U32)
  fun ref setsockopt(sock: UDPSocket[UDP] ref,
    level: I32, option_name: I32, option: Array[U8]): U32
  fun ref setsockopt_u32(sock: UDPSocket[UDP] ref,
    level: I32, option_name: I32, option: U32): U32
  fun is_open(): Bool
  fun is_closed(): Bool

Socket options are routed through the state machine for consistency with TCP.

The three state classes:

• _UDPNone: Pre-initialization. event_notify and read_again call _Unreachable(). send_to returns SendToNotOpen. close transitions to _UDPClosed. Socket option methods return error values.
• _UDPOpen: Bound and active. event_notify dispatches I/O. send_to delegates to _do_send_to. close unsubscribes, closes the fd, fires _on_closed. read_again resumes reading. Socket option methods delegate to FFI.
• _UDPClosed: Terminal. event_notify handles only AsioEvent.disposable. Everything else is a no-op or returns SendToNotOpen / error values.

_UDPNone exists only for the dispose/init race — the window between construction (which schedules _finish_initialization as a later behavior) and when that behavior runs, during which dispose() can arrive first. Without _UDPNone, UDP has two meaningful states — open and not-open — and a bool flag would suffice, matching TCPListener._listening. The state machine is a better fit because it matches TCPConnection's pattern, accommodates future states (DTLS, connected UDP), and matches the convention in AGENTS.md.

Receive error handling

UDP recvfrom returns transient errors that are not fatal to the socket: ECONNREFUSED from ICMP, ENOMEM, EHOSTUNREACH from a prior sendto. Unlike TCP, where a recv error means the connection is broken, UDP errors are per-datagram.

SocketResultError from recvfrom does not close the socket. The read loop stops reading for this turn, yields to the scheduler, but the socket stays open. The effect is a brief pause, not a server outage.

Fatal socket errors (EBADF, ENOTSOCK) mean the fd is already invalid. The OS will not deliver further readiness events, so no explicit close-on-error logic is needed.

Send result types

primitive SendToOk
primitive SendToWouldBlock
primitive SendToError
primitive SendToNotOpen

type SendToFailure is (SendToWouldBlock | SendToError | SendToNotOpen)
type SendToResult is (SendToOk | SendToFailure)

Four variants. SendToFailure is a sub-union of the three failure cases so callers can match on SendToOk vs SendToFailure without listing every failure variant.

UDPLifecycleEventReceiver

trait UDPLifecycleEventReceiver[UDP: UDPBackend ref = UDPRuntimeBackend]
  fun ref _socket(): UDPSocket[UDP]

  fun ref _on_bound() => None
  fun ref _on_bind_failure()  // no default
  fun ref _on_received(data: Array[U8] iso, from: net.NetAddress val)
    : ReadAction => KeepReading
  fun ref _on_closed() => None

_on_bound and _on_bind_failure, not _on_listening / _on_listen_failure — UDP binds, it doesn't listen. _on_bind_failure has no default; ignoring bind failure is never correct.

_on_received defaults to KeepReading. Send-only sockets use this default and never override it. The footgun: if your socket receives data and you don't override _on_received, datagrams are silently discarded. Document this.

UDPSocketActor

trait tag UDPSocketActor[UDP: UDPBackend ref = UDPRuntimeBackend]
  is AsioEventNotify

  fun ref _socket(): UDPSocket[UDP]
  be dispose() => _socket().close()
  be _event_notify(event: AsioEventID, flags: U32, arg: U32) =>
    _socket()._event_notify(event, flags)
  be _read_again() => _socket().read_again()
  be _finish_initialization() => _socket()._finish_initialization()

UDPSocket

class UDPSocket[UDP: UDPBackend ref = UDPRuntimeBackend]
  var _udp: UDP = UDP
  var _state: _UDPSocketState[UDP] = _UDPNone[UDP]
  var _event: AsioEventID = AsioEvent.none()
  var _fd: U32 = -1
  let _host: String
  let _port: String
  let _ip_version: IPVersion
  let _read_buffer_size: USize
  let _max_datagrams_per_turn: USize
  var _enclosing: (UDPSocketActor[UDP] ref | None)
  var _ler: (UDPLifecycleEventReceiver[UDP] ref | None)

Constructors: create(auth, host, port, enclosing, ler, read_buffer_size, ip_version) and none().

_max_datagrams_per_turn defaults to a sensible ceiling (e.g. 256). The byte budget alone is not sufficient to limit iteration count for UDP: a flood of 1-byte datagrams stays well within the byte ceiling while the loop runs thousands of times, leaving other actors unscheduled.

Public API:

• send_to(data: ByteSeq, to: net.NetAddress box): SendToResult
• close()
• local_address(): net.NetAddress
• read_again()
• is_open(): Bool
• is_closed(): Bool
• Socket options: getsockopt, getsockopt_u32, setsockopt, setsockopt_u32, get_so_rcvbuf, get_so_sndbuf, set_so_rcvbuf, set_so_sndbuf

Windows ifdef guards on fd close, matching TCP.

Internal Specifications

The methods below have behavior that diverges from TCP or involves subtleties worth specifying. The remaining internal methods (_do_send_to, _do_close, _do_read_again, _set_state, _destroy_event) are mechanical delegates matching TCP's pattern.

_event_notify

_event_notify(event, flags):
  if event != _event then
    // Stale event from a previous socket lifecycle.
    // Handle disposable flag only.
    if AsioEvent.disposable(flags) then
      PonyAsio.destroy(event)
    end
    return
  end

  // Delegate to state machine for I/O dispatch.
  _state.event_notify(this, flags)

  // Handle disposable flag — event is being unsubscribed.
  if AsioEvent.disposable(flags) then
    PonyAsio.destroy(event)
    _event = AsioEvent.none()
  end

Simpler than TCP's version. No timers, no foreign events, no Happy Eyeballs stragglers. One event per socket. The event != _event guard catches stale events from a previous socket lifecycle; they are destroyed if disposable, otherwise ignored.

_pending_reads

_pending_reads is the read loop on UDPSocket, called from _UDPOpen.event_notify when the event carries a readable flag. It is bounded by two budgets:

• A byte budget aligned with _read_buffer_size, matching TCP.
• A datagram count budget (_max_datagrams_per_turn).

Both are necessary. The byte budget limits scheduler time on large datagrams. The datagram count ceiling limits how many tiny datagrams one turn processes within the byte ceiling.

After each _on_received delivery, check is_closed(). If the user called close() from within _on_received, stop immediately. UDP has no _Closing state; when close() returns, the fd is already closed.

On SocketResultError from recvfrom: stop reading for this turn. Do not close the socket. The socket stays in _UDPOpen.

On SocketResultRetry from recvfrom: no more data available, stop reading.

On budget exhaustion: send _read_again to the enclosing actor to yield to the scheduler and resume in a later behavior.

YieldReading from _on_received: stop reading for this turn, send _read_again. Unlike TCP, yielding does not cause backpressure. Datagrams that arrive while yielded may be dropped by the kernel.

_finish_initialization

Checks for _UDPClosed before proceeding. If dispose() arrived before the initialization message, the socket is already closed; return early. This matches TCP's guard at tcp_connection.pony:1917-1918.

Design Decisions

Rationale for each decision is given inline in the sections above. This is the list for reference.

1. Separate UDPBackend trait (not merged with TCP).
2. Trait-based state machine with three states.
3. No multicast convenience methods; available through setsockopt.
4. No mute/unmute; the scheduler yields via ReadAction.
5. _on_received defaults to KeepReading.
6. _on_bind_failure has no default.
7. Four-variant send result with SendToFailure sub-union.
8. No send tokens, queuing, or backpressure.
9. Default read buffer: DefaultReadBufferSize (16384 bytes).
10. from: net.NetAddress val in _on_received.
11. to: net.NetAddress box in send_to.
12. No write-side resubscription or writeability tracking.
13. Socket options routed through state machine.
14. recvfrom errors do not close the socket.
15. Read loop bounded by bytes and datagram count.
16. _finish_initialization guards against _UDPClosed.
17. close() during _on_received stops the read loop immediately.
18. Backend sendto returns SocketResult only, no byte count.
19. Bind terminology throughout.

Open Uncertainties

1. Windows readiness backend and UDP. The ponyc Windows backend uses ProcessSocketNotifications. Whether this works correctly with UDP sockets needs verification.

2. pony_os_recvfrom and SocketResult. Confirm the FFI return maps cleanly to the SocketResult tri-state, and that zero-length datagrams (valid in UDP) are not mapped to SocketResultError.

3. Bind failure reason type. Whether _on_bind_failure should take a reason parameter. Deferred for now; TCP's _on_listen_failure takes none either.

Future Work

Notifier variant. The TCP side includes a notifier pattern alongside the lifecycle-receiver pattern. The notifier wraps the callbacks in a separate object that the actor passes in, rather than implementing the callbacks on the actor itself. We should add the same option for UDP.

Multicast convenience methods. Multicast is available through setsockopt but has no convenience methods yet. We can add them for common multicast operations when there's demonstrated need.

Connected UDP mode. Calling connect() on a UDP socket restricts it to a single peer, enabling send/recv instead of sendto/recvfrom and filtering incoming datagrams by source address. A natural extension, but not needed for the initial implementation.

[SeanTAllen]

Implemented in #385.

The design shipped as written. The three open uncertainties are resolved:

pony_os_recvfrom and SocketResult: The FFI maps cleanly. ponyc/src/libponyrt/lang/socket.c:949-1023 handles all three cases on both POSIX and Windows. Zero-length datagrams (valid per RFC 768) return PONY_SOCKET_OK with count 0 — ponylang/ponyc#5289 and ponylang/ponyc#5551 cover the relevant runtime behavior. Lori's read loop delivers them as an empty Array[U8] via _on_received.

Bind failure reason: _on_bind_failure takes no parameter, matching TCP's _on_listen_failure. If both grow a reason parameter, they grow together.

Windows readiness backend: CI passes on Linux, macOS, and Windows. The echo test is a single round-trip, not a stress test of ProcessSocketNotifications with UDP — worth revisiting if UDP issues surface on Windows.

Remaining future work: notifier variant, multicast convenience methods, connected UDP mode.

[SeanTAllen]

The notifier layer is done — PR #387.

[SeanTAllen]

Future work moved to issues:

• #388 — Multicast convenience methods
• #389 — Connected UDP mode

Closing — everything from this design is either shipped or tracked.