# 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)