UDP Transport

The UDP transport provides connectionless, fire-and-forget messaging suitable for broadcast notifications and scenarios where delivery guarantees are not critical.

Overview

Property	Value
Plugin Assembly	`StellaOps.Router.Transport.Udp.dll`
Transport Name	`udp`
Default Port	5102
Security	Network isolation (no encryption)
Use Case	Broadcast, metrics, fire-and-forget events

Configuration

router.yaml

Router:
  Transport:
    Type: udp
    Udp:
      Host: "0.0.0.0"
      Port: 5102
      ReceiveBufferSize: 65536
      SendBufferSize: 65536
      MulticastGroup: null         # Optional multicast group
      MulticastTtl: 1
      EnableBroadcast: false

microservice.yaml

routers:
  - host: gateway.internal
    port: 5102
    transportType: Udp
    priority: 1

Environment Variables

ROUTER__TRANSPORT__TYPE=udp
ROUTER__TRANSPORT__UDP__HOST=0.0.0.0
ROUTER__TRANSPORT__UDP__PORT=5102

Options Reference

Option	Type	Default	Description
`Host`	string	`0.0.0.0`	Bind address
`Port`	int	`5102`	UDP port number
`ReceiveBufferSize`	int	`65536`	Socket receive buffer size
`SendBufferSize`	int	`65536`	Socket send buffer size
`MulticastGroup`	string	`null`	Multicast group address (e.g., `239.1.2.3`)
`MulticastTtl`	int	`1`	Multicast time-to-live
`EnableBroadcast`	bool	`false`	Allow broadcast to `255.255.255.255`
`MaxDatagramSize`	int	`65507`	Maximum UDP datagram size

Use Cases

Fire-and-Forget Events

For events where acknowledgment is not required:

[StellaEndpoint("POST", "/events/metrics", FireAndForget = true)]
public sealed class MetricsEndpoint : IStellaEndpoint<MetricsBatch, EmptyResponse>
{
    public Task<EmptyResponse> HandleAsync(MetricsBatch request, CancellationToken ct)
    {
        // Process metrics - no response expected
        return Task.FromResult(new EmptyResponse());
    }
}

Multicast Broadcasting

For broadcasting to multiple listeners:

Router:
  Transport:
    Type: udp
    Udp:
      MulticastGroup: "239.0.1.1"
      MulticastTtl: 2

Services join the multicast group to receive broadcasts:

// All services with this config receive broadcasts
routers:
  - host: "239.0.1.1"
    port: 5102
    transportType: Udp

Performance Characteristics

Metric	Typical Value
Latency (p50)	< 0.5ms
Latency (p99)	< 2ms
Throughput	150,000+ pps
Memory per socket	~1KB

Note: No delivery guarantees; packets may be lost under load

Limitations

No delivery guarantees: Packets may be dropped
No ordering guarantees: Packets may arrive out of order
Size limits: Maximum datagram size ~65KB (64KB practical limit)
No acknowledgments: Sender doesn’t know if message was received
No fragmentation handling: Large messages must fit in single datagram

When to Use UDP

Good fit:

Real-time metrics and telemetry
Service discovery announcements
Health check broadcasts
Low-latency gaming or streaming metadata

Not recommended:

Transaction processing
Data that must not be lost
Large payloads (use TCP/TLS instead)

Security Considerations

UDP transport does not provide encryption or authentication. Consider:

Network segmentation
Firewall rules to restrict UDP traffic
Application-level message signing if integrity is needed
DTLS wrapper for encrypted UDP (not built-in)

Troubleshooting

Messages Not Received

Check firewall allows UDP traffic on the configured port
Verify receiver is bound to correct address/port
Check for buffer overflow (increase ReceiveBufferSize)
Monitor for packet loss with network tools

Multicast Not Working

Verify multicast routing is enabled on network
Check MulticastTtl is sufficient for network topology
Ensure IGMP snooping is properly configured
Verify all receivers joined the multicast group

High Packet Loss

Reduce message rate
Increase buffer sizes
Check for network congestion
Consider switching to TCP for reliable delivery