git.stella-ops.org/docs/router/transports/udp.md

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

1. No delivery guarantees: Packets may be dropped
2. No ordering guarantees: Packets may arrive out of order
3. Size limits: Maximum datagram size ~65KB (64KB practical limit)
4. No acknowledgments: Sender doesn't know if message was received
5. 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

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

Multicast Not Working

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

High Packet Loss

1. Reduce message rate
2. Increase buffer sizes
3. Check for network congestion
4. Consider switching to TCP for reliable delivery

See Also

• TCP Transport - Reliable delivery
• Transport Overview
• Router Architecture