QUIC (0-RTT Transport)¶

Status: Planned

This module is not yet implemented. The design below represents the target architecture.

Overview¶

QUIC is a multiplexed, encrypted transport protocol built on UDP. The key feature for low-latency systems is 0-RTT connection establishment data can be sent with the very first packet to a previously-known server, eliminating the TCP 3-way handshake + TLS handshake overhead.

Connection Establishment¶

┌─────────────────────────────────────────────────────────────────┐
│  TCP + TLS 1.3 (2-RTT):          QUIC 0-RTT:                    │
│                                                                  │
│  Client        Server             Client        Server           │
│    │              │                  │              │             │
│    │── SYN ──────►│                  │── Initial ──►│             │
│    │◄── SYN+ACK ──│   1 RTT         │  (+ 0-RTT   │             │
│    │── ACK ──────►│                  │    data)    │             │
│    │── ClientHello►│                  │              │             │
│    │◄── ServerHello│   2 RTT         │◄── Handshake│  ½ RTT      │
│    │── Finished ──►│                  │── Handshake─►│             │
│    │── Data ──────►│                  │              │             │
│    │              │                  │── Data ─────►│  ← already! │
│                                                                  │
│  Total: 2 RTT before first data    Total: 0 RTT (resumption)    │
└─────────────────────────────────────────────────────────────────┘

Planned API¶

typedef struct {
    int          udp_fd;           /* Underlying UDP socket */
    uint64_t     connection_id;    /* QUIC connection ID */
    uint32_t     remote_ip;
    uint16_t     remote_port;
    uint8_t      tls_state;        /* TLS 1.3 handshake state */
    bool         zero_rtt_available; /* Have cached server parameters */
    /* Stream management */
    uint64_t     next_stream_id;
    /* Congestion control */
    uint64_t     cwnd;
    uint64_t     bytes_in_flight;
} quic_conn_t;

typedef struct {
    uint64_t stream_id;
    bool     fin;                /* Stream complete */
} quic_stream_t;

/* Connection lifecycle */
int quic_connect(quic_conn_t *conn, uint32_t remote_ip, uint16_t port,
                 const uint8_t *psk, size_t psk_len);  /* 0-RTT with PSK */
int quic_accept(quic_conn_t *listener, quic_conn_t *new_conn);
int quic_close(quic_conn_t *conn);

/* Stream-based data transfer */
int quic_stream_open(quic_conn_t *conn, quic_stream_t *stream);
ssize_t quic_stream_send(quic_conn_t *conn, quic_stream_t *stream,
                         const void *data, size_t len);
ssize_t quic_stream_recv(quic_conn_t *conn, quic_stream_t *stream,
                         void *buf, size_t len, int timeout_ms);
int quic_stream_close(quic_conn_t *conn, quic_stream_t *stream);

/* 0-RTT early data (before handshake completes) */
ssize_t quic_send_0rtt(quic_conn_t *conn, const void *data, size_t len);

QUIC Packet Format¶

┌────────────────────────────────────────────────────────────────┐
│ QUIC Long Header (Initial, Handshake):                          │
├──────┬──────────┬─────────────────┬─────────────────┬──────────┤
│Header│  Version │ Dest Conn ID    │ Src Conn ID     │ Payload  │
│Form  │ (32 bit) │ (variable)      │ (variable)      │(encrypted)│
│(1 bit)│          │                 │                 │          │
└──────┴──────────┴─────────────────┴─────────────────┴──────────┘

┌────────────────────────────────────────────────────────────────┐
│ QUIC Short Header (post-handshake, 1-RTT):                      │
├──────┬─────────────────┬──────────┬───────────────────────────┤
│Header│ Dest Conn ID    │Pkt Number│  Encrypted Payload         │
│Form  │ (variable)      │(1-4 bytes)│  (AEAD protected)         │
│(1 bit)│                 │          │                           │
└──────┴─────────────────┴──────────┴───────────────────────────┘

Key Features¶

Feature	Benefit
0-RTT resumption	First-packet data delivery
Connection migration	Survive IP address changes (mobile)
Stream multiplexing	No head-of-line blocking
Built-in TLS 1.3	Always encrypted, no plaintext mode
PMTU discovery	Optimal packet sizes without fragmentation

Performance Targets¶

Metric	Target	Notes
0-RTT connection	0 ms (first data)	With cached PSK
1-RTT connection	< 1 ms (LAN)	First contact with server
Stream create	< 1 µs	Lightweight stream IDs
Encryption overhead	< 500 ns	AES-GCM / ChaCha20

Implementation Roadmap¶

QUIC packet parsing and construction (RFC 9000)
TLS 1.3 integration (Initial + Handshake crypto)
Connection ID management and routing
Stream multiplexing (bidirectional + unidirectional)
0-RTT early data with PSK caching
Loss detection and congestion control (RFC 9002)
Connection migration
Integration with epoll_reactor
Benchmark: 0-RTT latency, throughput per stream