[DRAFT] ARO-0038: UDP Socket Communication

[KrisSimon]

ARO-0038: UDP Socket Communication

• Proposal: ARO-0038
• Author: ARO Language Team
• Status: Draft
• Requires: ARO-0020, ARO-0024

Abstract

This proposal extends ARO-0024 (Socket Communication) with UDP (User Datagram Protocol) support, enabling connectionless, low-latency communication for ARO applications.

Motivation

While TCP (ARO-0024) provides reliable, ordered delivery, many applications benefit from UDP:

1. Real-time Applications: Gaming, streaming, VoIP where latency matters more than reliability
2. Broadcasting: One-to-many message distribution
3. Discovery Protocols: Service discovery, multicast group communication
4. Lightweight Messaging: Telemetry, metrics, stateless request/response patterns
5. IoT Communication: Sensor data, device-to-device messaging

Proposed Solution

1. UDP Server

Start a UDP socket server using the <Start> action with explicit protocol:

(Application-Start: UDP Logger) {
    <Log> the <message> for the <console> with "Starting UDP server".
    <Start> the <udp-server> on <port> with 9000.
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

2. Datagram Events

Handle incoming datagrams:

public struct DatagramReceivedEvent: RuntimeEvent {
    public let remoteAddress: String
    public let remotePort: Int
    public let data: Data
    public let timestamp: Date
}

public struct UDPServerStartedEvent: RuntimeEvent {
    public let port: Int
}

3. Datagram Handlers

(Handle Datagram Received: UDP Event Handler) {
    <Extract> the <data> from the <datagram: buffer>.
    <Extract> the <sender> from the <datagram: remoteAddress>.
    <Extract> the <port> from the <datagram: remotePort>.
    
    (* Process received data *)
    <Transform> the <response> from the <data>.
    
    (* Send response back to sender *)
    <Send> the <response> to the <sender> on <port>.
    
    <Return> an <OK: status> for the <datagram>.
}

4. UDP Client

Send datagrams to remote endpoints:

(Send Telemetry: Metrics Reporter) {
    <Create> the <metrics> with <cpu-usage> and <memory-usage>.
    <Send> the <metrics> via <udp> to <host: "metrics.example.com"> on port 8125.
    <Return> an <OK: status> for the <telemetry>.
}

5. Multicast Support

(* Join a multicast group *)
(Application-Start: Discovery Service) {
    <Start> the <udp-server> on <port> with 5353.
    <Join> the <multicast-group> with "224.0.0.251".
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(* Send to multicast group *)
(Announce Service: Discovery) {
    <Create> the <announcement> with <service-info>.
    <Send> the <announcement> to <multicast: "224.0.0.251"> on port 5353.
    <Return> an <OK: status> for the <announcement>.
}

6. SwiftNIO Implementation

public final class AROUDPServer: UDPServerService, @unchecked Sendable {
    private let group: MultiThreadedEventLoopGroup
    private let eventBus: EventBus
    private var channel: Channel?
    
    public func start(port: Int) async throws {
        let bootstrap = DatagramBootstrap(group: group)
            .channelOption(ChannelOptions.socketOption(.so_reuseaddr), value: 1)
            .channelInitializer { channel in
                channel.pipeline.addHandler(
                    UDPHandler(eventBus: self.eventBus)
                )
            }
        
        let channel = try await bootstrap.bind(host: "0.0.0.0", port: port).get()
        self.channel = channel
        
        eventBus.publish(UDPServerStartedEvent(port: port))
    }
    
    public func send(data: Data, to address: String, port: Int) async throws {
        guard let channel = channel else {
            throw UDPError.notBound
        }
        
        var buffer = channel.allocator.buffer(capacity: data.count)
        buffer.writeBytes(data)
        
        let remoteAddress = try SocketAddress(ipAddress: address, port: port)
        let envelope = AddressedEnvelope(remoteAddress: remoteAddress, data: buffer)
        
        try await channel.writeAndFlush(envelope)
    }
    
    public func joinMulticastGroup(_ group: String) async throws {
        guard let channel = channel else {
            throw UDPError.notBound
        }
        
        let groupAddress = try SocketAddress(ipAddress: group, port: 0)
        try await (channel as! MulticastChannel).joinGroup(groupAddress).get()
    }
}

private final class UDPHandler: ChannelInboundHandler {
    typealias InboundIn = AddressedEnvelope<ByteBuffer>
    
    private let eventBus: EventBus
    
    init(eventBus: EventBus) {
        self.eventBus = eventBus
    }
    
    func channelRead(context: ChannelHandlerContext, data: NIOAny) {
        let envelope = unwrapInboundIn(data)
        var buffer = envelope.data
        
        guard let bytes = buffer.readBytes(length: buffer.readableBytes) else {
            return
        }
        
        let remoteAddress = envelope.remoteAddress.ipAddress ?? "unknown"
        let remotePort = envelope.remoteAddress.port ?? 0
        
        eventBus.publish(DatagramReceivedEvent(
            remoteAddress: remoteAddress,
            remotePort: remotePort,
            data: Data(bytes)
        ))
    }
}

---

Grammar Extension

(* UDP operations *)
udp_start_statement = "<Start>" , "the" , "<udp-server>" , "on" , "<port>" , "with" , integer ;
udp_send_statement = "<Send>" , "the" , value , "via" , "<udp>" , "to" , host_reference , "on" , "port" , integer ;
join_multicast_statement = "<Join>" , "the" , "<multicast-group>" , "with" , string_literal ;
multicast_send_statement = "<Send>" , "the" , value , "to" , "<multicast:" , string_literal , ">" , "on" , "port" , integer ;

---

Complete Example

(* UDP Echo Server - Connectionless datagram communication *)

(Application-Start: UDP Echo) {
    <Log> the <message> for the <console> with "Starting UDP echo on port 9000".
    <Start> the <udp-server> on <port> with 9000.
    <Log> the <message> for the <console> with "UDP server listening on port 9000".
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(Handle Datagram Received: UDP Event Handler) {
    <Extract> the <data> from the <datagram: buffer>.
    <Extract> the <sender-address> from the <datagram: remoteAddress>.
    <Extract> the <sender-port> from the <datagram: remotePort>.
    
    (* Echo back the received data *)
    <Send> the <data> via <udp> to <sender-address> on <sender-port>.
    
    <Log> the <message> for the <console> with "Echoed datagram back to sender".
    <Return> an <OK: status> for the <datagram>.
}

---

TCP vs UDP Comparison

Feature	TCP (ARO-0024)	UDP (ARO-0038)
Connection	Connection-oriented	Connectionless
Reliability	Guaranteed delivery	Best-effort
Ordering	Ordered	No ordering
Events	ClientConnected, DataReceived, ClientDisconnected	DatagramReceived
Use Cases	HTTP, database connections, file transfer	Real-time apps, discovery, metrics
Service Type	<socket-server>	<udp-server>

---

Implementation Notes

• Uses SwiftNIO DatagramBootstrap for non-blocking UDP I/O
• No connection state management (connectionless)
• Supports IPv4 and IPv6
• Multicast group join/leave operations
• Maximum datagram size follows OS limits (typically 65,507 bytes for IPv4)
• Thread-safe using actor isolation or locks
• Use <Keepalive> action to keep the application running for UDP events

---

Implementation Location (Proposed)

The UDP socket system would be implemented in:

• Sources/ARORuntime/Sockets/UDPServer.swift - AROUDPServer class
• Sources/ARORuntime/Actions/BuiltIn/ServerActions.swift - UDP Start action
• Sources/ARORuntime/Actions/BuiltIn/ResponseActions.swift - UDP Send action

UDP events would be defined in:

• Sources/ARORuntime/Sockets/UDPServer.swift - DatagramReceivedEvent, UDPServerStartedEvent
• Sources/ARORuntime/Events/EventTypes.swift - Event type definitions

---

Open Questions

1. Should we support raw sockets for advanced use cases?
2. Should <Broadcast> work differently for UDP (actual network broadcast vs. multicast)?
3. Should we add explicit TTL (time-to-live) configuration for multicast?
4. Should datagram fragmentation be handled transparently or exposed to the application?

---

Revision History

Version	Date	Changes
0.1	2024-12	Initial draft