Multicast convenience methods

[SeanTAllen]

Multicast is available through setsockopt_u32 but has no convenience methods. Common operations like joining a group, leaving a group, and setting the outgoing interface each require looking up the right socket option constants and packing the right argument — a convenience API would make these straightforward.

[SeanTAllen]

Plan

API surface

Ten new methods on UDPSocket, all returning U32 (0 on success, errno on failure):

Group membership:

• join_multicast_group_v4(group: String, interface_addr: String = "0.0.0.0"): U32
• leave_multicast_group_v4(group: String, interface_addr: String = "0.0.0.0"): U32
• join_multicast_group_v6(group: String, interface_index: U32 = 0): U32
• leave_multicast_group_v6(group: String, interface_index: U32 = 0): U32

Per-socket multicast settings:

• set_multicast_ttl(ttl: U8): U32 — IPv4 hop limit
• set_multicast_hops(hops: U32): U32 — IPv6 hop limit
• set_multicast_loopback_v4(loopback: Bool): U32
• set_multicast_loopback_v6(loopback: Bool): U32
• set_multicast_interface_v4(interface_addr: String): U32 — outgoing interface by address
• set_multicast_interface_v6(interface_index: U32): U32 — outgoing interface by index

Separate v4/v6 because the kernel structs and parameter types differ between address families.

Implementation

U32-based methods (ttl, hops, loopback v4/v6, interface v6): thin wrappers over existing setsockopt_u32, same pattern as set_so_rcvbuf:

fun set_multicast_ttl(ttl: U8): U32 =>
  setsockopt_u32(OSSockOpt.ipproto_ip(),
    OSSockOpt.ip_multicast_ttl(), ttl.u32())

Struct-based methods (join/leave v4/v6, interface v4): a C shim in lori/lori_multicast.c parses address strings with inet_pton and packs the kernel structs. The packed bytes go through the existing setsockopt (raw bytes) path. Three shim functions:

• lori_pack_ip_mreq(group, iface, out_buf) — struct ip_mreq (8 bytes), for join/leave v4
• lori_pack_ipv6_mreq(group, iface_index, out_buf) — struct ipv6_mreq (20 bytes), for join/leave v6
• lori_inet_pton_v4(addr, out_buf) — struct in_addr (4 bytes), for set interface v4

Each returns 0 on success, EINVAL on parse failure. ponyc compiles the .c file automatically. The shim uses <arpa/inet.h> and <netinet/in.h> on POSIX; <winsock2.h> and <ws2tcpip.h> on Windows — inet_pton and the multicast structs are available on both.

Because everything routes through existing setsockopt/setsockopt_u32, the state machine already handles the "not open" case — no _UDPSocketState trait changes, no _do_* methods.

Notifier layer

Forward all 10 methods on notifier.UDPSocket as fun methods, same pattern as set_so_rcvbuf. Each calls through to the class's convenience method, which handles the C shim and setsockopt routing internally:

fun join_multicast_group_v4(group: String,
  interface_addr: String = "0.0.0.0"): U32
=>
  _udp.join_multicast_group_v4(group, interface_addr)

Tests

Build and run: make ssl=3.0.x. Run one test: make test-one t=TestName ssl=3.0.x.

• Call each method on a bound socket, verify 0 return.
• Call join/leave/set-interface with a bad address string, verify non-zero return (EINVAL from the shim).
• Call convenience methods before the socket is open, verify non-zero return.

Actual multicast delivery isn't reliably testable in CI — multicast routing depends on the host's network stack.

Example

A multicast receiver (examples/multicast-receiver/) that joins 239.1.2.3 on port 5007 and prints incoming datagrams. Demonstrates join_multicast_group_v4 and set_multicast_loopback_v4.

Files

• lori/lori_multicast.c — new, C shim
• lori/udp_socket.pony — 10 new methods + FFI declarations
• lori/notifier/udp_socket.pony — 10 forwarding methods
• lori/_test_udp.pony — new tests
• examples/multicast-receiver/ — new example
• examples/README.md — add entry