Quinn QUIC REALITY Roadmap
Status: Roadmap
Last reviewed: 2026-05-13
Purpose
This roadmap tracks the Quinn-based QUIC REALITY implementation. The original proposal was to replace a hand-written QUIC runtime with Quinn plus a REALITY crypto bridge. That migration is now the active implementation path.
Feature Status
| Feature | State | Evidence |
|---|---|---|
crates/quinn-reality crate | Complete | Present in nexus-agent/Cargo.toml workspace. |
| Server crypto config/session | Complete | crates/quinn-reality/src/server.rs. |
| Client crypto config/session | Complete | crates/quinn-reality/src/client.rs. |
| Packet/header key bridge | Complete | crates/quinn-reality/src/keys.rs. |
| Handshake round-trip test | Complete | crates/quinn-reality/tests/handshake_roundtrip.rs. |
| Agent QUIC listener integration | Complete | QuicForwarder uses Quinn Endpoint. |
| Agent QUIC client pool | Complete | QuinnClient and QuicRealityClientPool. |
| TCP relay over Quinn streams | Complete | Stream relay in src/gateway/quic.rs. |
| UDP relay over Quinn DATAGRAM | Complete | DATAGRAM client/server paths in src/gateway/quic.rs. |
| L3 tunnel transport over Quinn DATAGRAM | Complete | L3 transport adapters in src/gateway/quic.rs and src/l3. |
Remove references to hand-written quic-core runtime docs | Complete | Roadmaps now mark that path deprecated. |
| qlog integration | Planned | Not implemented. |
| Connection migration product policy | Planned | Not exposed in NexusNet config. |
| 0-RTT product policy | Planned | Not exposed in NexusNet config. |
Current Architecture
text
quinn Endpoint/Connection
-> quinn-reality crypto Session
-> reality-core handshake material
-> gateway stream / DATAGRAM / L3 adaptersThe important design boundary is that REALITY authentication stays in reality-core and quinn-reality, while application routing stays in src/gateway and src/l3.
Deprecated Work
| Item | State | Reason |
|---|---|---|
| Maintaining an in-tree custom QUIC stack as the runtime | Deprecated | Quinn now owns connection management, streams, DATAGRAM, and transport behavior. |
Moving new product features into quic-core | Deprecated | The workspace no longer contains crates/quic-core. |
Next Work
| Item | State |
|---|---|
| Add qlog or equivalent structured QUIC diagnostics. | Planned |
| Document Quinn transport tuning defaults. | Planned |
| Add explicit config/product decisions for migration and 0-RTT. | Planned |
| Keep REALITY crypto bridge tests close to Quinn version updates. | Planned |