QUIC REALITY Roadmap

Status: Roadmap

Last reviewed: 2026-05-13

Purpose

QUIC REALITY is the secure QUIC transport used by L4 chains and L3 tunnels. The current runtime path is Quinn-based:

• nexus-agent/crates/quinn-reality: Quinn crypto trait bridge for REALITY.
• nexus-agent/src/gateway/quic.rs: listener, client pool, stream relay, DATAGRAM relay, L3 DATAGRAM context registry, and metrics.
• nexus-backend/src/api/tunnel_chains.rs: emits QUIC REALITY QuicRule, TcpProxyRule, and UdpRule config.

Feature Status

Feature	State	Evidence
REALITY authentication primitives	Complete	crates/reality-core and crates/reality-io.
Quinn crypto bridge	Complete	crates/quinn-reality implements server/client config and sessions.
QUIC REALITY listener	Complete	QuicForwarder::spawn_reality_routes_with_gso.
TCP relay over QUIC stream	Complete	QuicRealityClientPool::relay_tcp and stream handlers.
UDP relay over QUIC DATAGRAM	Complete	relay_udp_over_quic_reality and DATAGRAM client/server paths.
L3 packets over QUIC DATAGRAM	Complete	L3 context registry and QuicRealityL3DatagramTransport.
Port sharing by SNI/short ID	Complete	Backend/agent validate same-key, unique route selection.
Hand-written quic-core runtime	Deprecated	Current workspace no longer contains crates/quic-core; Quinn is the active runtime.
qlog/advanced observability	Planned	Not exposed as a product feature.
Connection migration and 0-RTT product policy	Planned	Quinn can support these primitives, but NexusNet policy/UI are not defined.

Current Architecture

L4/L3 config
  -> backend TransportProfile + REALITY credential lookup
  -> SecureAgentService Control stream
  -> agent PingoraConfig/L3TunnelConfig in-memory apply state
  -> gateway::quic Quinn endpoint
  -> stream relay, DATAGRAM relay, or L3 DATAGRAM transport

Deprecated Notes

Older roadmap text described a custom QUIC implementation named quic-core. That plan was useful as a protocol exploration path, but it is not the current implementation. Do not add new runtime work to a quic-core crate unless the architecture decision is explicitly reopened.

Next Work

Item	State
Improve production metrics around QUIC connection counts, DATAGRAM drops, and route selection.	Planned
Document operational tuning for NEXUS_QUIC_GSO, socket buffers, and DATAGRAM queue settings.	Planned
Decide policy for Quinn connection migration and 0-RTT.	Planned
Keep REALITY credential validation centralized in backend deployment paths.	Complete