174 lines
4.3 KiB
Markdown
174 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
```yaml
|
|
routers:
|
|
- host: gateway.internal
|
|
port: 5102
|
|
transportType: Udp
|
|
priority: 1
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
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:
|
|
|
|
```csharp
|
|
[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:
|
|
|
|
```yaml
|
|
Router:
|
|
Transport:
|
|
Type: udp
|
|
Udp:
|
|
MulticastGroup: "239.0.1.1"
|
|
MulticastTtl: 2
|
|
```
|
|
|
|
Services join the multicast group to receive broadcasts:
|
|
|
|
```csharp
|
|
// 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](./tcp.md) - Reliable delivery
|
|
- [Transport Overview](./README.md)
|
|
- [Router Architecture](../ARCHITECTURE.md)
|