QUIC REALITY DATAGRAM Roadmap
Status: Roadmap
Last reviewed: 2026-05-13
Purpose
QUIC REALITY DATAGRAM carries unreliable packet-oriented payloads:
- UDP payloads for L4 chains.
- CONNECT-IP frames for managed point-to-point IP tunnels.
The current path uses Quinn DATAGRAM support in nexus-agent/src/gateway/quic.rs.
Feature Status
| Feature | State | Evidence |
|---|---|---|
| UDP over QUIC REALITY DATAGRAM | Complete | relay_udp_over_quic_reality, DATAGRAM client/server session IDs, and ignored iperf smoke test. |
| L3 over QUIC REALITY DATAGRAM | Complete | QuicRealityL3DatagramTransport and QuicRealityL3DatagramServerTransport. |
| DATAGRAM counters | Complete | quic_datagram_metrics_snapshot() exposes in-process counters for tests/logs. |
| QUIC GSO toggle | Complete | NEXUS_QUIC_GSO and L3 enable_quic_gso path. |
| Batch send/receive for L3 | Complete | L3 TUN batch size and DATAGRAM batch helpers exist. |
| Formal control-plane metric reporting for DATAGRAM counters | Planned | Counters are not yet part of MetricsReport. |
| 2G/3G stable throughput target | Planned | Performance target, not guaranteed behavior. |
| Reliable delivery for DATAGRAM payloads | Deprecated | UDP/L3 DATAGRAM payloads must remain unreliable; use streams or higher layers for reliability. |
Current Baseline
The current code keeps the ignored iperf smoke path for UDP-over-QUIC REALITY. Earlier local notes reported about 1 Gbit/s receiver throughput for 1150-byte UDP payloads with low loss. Treat those numbers as local benchmark history, not a product guarantee.
Tuning Surface
| Setting | Purpose |
|---|---|
NEXUS_QUIC_GSO | Enables Quinn UDP segmentation offload by default. |
NEXUS_QUIC_OUTER_UDP_PAYLOAD_SIZE | Bounds configured outer UDP payload size. |
NEXUS_QUIC_DATAGRAM_QUEUE | Sets DATAGRAM queue capacity. |
NEXUS_QUIC_DATAGRAM_SEND_BURST | Controls DATAGRAM send burst size. |
NEXUS_QUIC_SOCKET_BUFFER_SIZE | Tunes QUIC UDP socket buffers. |
L3 batch_size | Controls TUN/DATAGRAM batch behavior for L3 tunnels. |
Next Work
| Item | State |
|---|---|
Promote DATAGRAM counters into agent MetricsReport. | Planned |
| Add repeatable benchmark scripts that emit a compact throughput/loss table. | Planned |
| Add route-level counters for L3 drops by reason. | Planned |
| Keep MTU-safe defaults for WAN mode. | Complete |