Package org.eclipse.jetty.quic.quiche

package org.eclipse.jetty.quic.quiche

This module contains the main abstractions for the QUIC protocol using the Quiche library.

A QuicheConnection is a Connection that receives and sends bytes from its underlying DatagramChannelEndPoint.

A QuicheConnection manages one (on the client) or many (on the server) QuicheSessions, one for each QUIC connection id.

A QuicheSession manages many QUIC streams, identified by a stream id and represented by QuicheStream.

A QuicheSession delegates I/O processing to a protocol-specific ProtocolSession, whose responsibility is to use QUIC streams to implement the protocol-specific I/O processing.

A ProtocolSession manages many StreamEndPoints, one for each QUIC stream.

The Connection associated with each StreamEndPoint parses the bytes received on the QUIC stream, and generates the bytes to send on that QUIC stream.

On the client side, the layout of the components in case of HTTP/1.1 is the following:


 DatagramChannelEndPoint -- ClientQuicheConnection -- ClientQuicheSession -- ClientProtocolSession -- StreamEndPoint -- HttpConnectionOverHTTP

The client specific ProtocolSession creates one bidirectional QUIC stream that represent the same transport as a TCP stream, over which HTTP/1.1 bytes are exchanged by the two peers.

On the client side, the layout of the components in case of HTTP/3 is the following:


 DatagramChannelEndPoint -- ClientQuicheConnection -- ClientQuicheSession -- ClientHTTP3Session -* StreamEndPoint -- ClientHTTP3StreamConnection

In this case, the client specific, HTTP/3 specific, ProtocolSession creates and manages zero or more bidirectional QUIC streams, over which HTTP/3 bytes are exchanged by the two peers, as well as the unidirectional QUIC streams required by the HTTP/3 protocol.

On the server side, the layout of the components in case of HTTP/1.1 is the following:


 CLIENT  |  SERVER
 clientA                                                   ServerQuicheSessionA -- ServerProtocolSessionA -- StreamEndPointA -- HttpConnection
         \                                                /
           DatagramChannelEndPoint -- ServerQuicheConnection
         /                                                \
 clientB                                                   ServerQuicheSessionB -- ServerProtocolSessionB -- StreamEndPointB -- HttpConnection

The DatagramChannelEndPoint listens on the server port and receives UDP datagrams from all clients.

The server side QuicheConnection processes the incoming datagram bytes creating a QuicheSession for every QUIC connection id sent by the clients.

The clients have created a single QUIC stream to send HTTP/1.1 requests, which results in the QuicheSessions to create a correspondent StreamEndPoint with its associated HttpConnection.

The path DatagramChannelEndPoint -- ServerQuicheConnection -- ServerQuicheSession -- ServerProtocolSession -- StreamEndPoint behaves exactly like a TCP SocketChannelEndPoint for the associated HttpConnection.

On the server side, the layout of the components in case of HTTP/3 is the following:


 CLIENT  |  SERVER
 clientA                                                   ServerQuicheSessionA -# ServerHTTP3SessionA -- StreamEndPointA1 -- ServerHTTP3StreamConnection
         \                                                /                                            `- StreamEndPointA2 -- ServerHTTP3StreamConnection
           DatagramChannelEndPoint -- ServerQuicheConnection
         /                                                \                                            ,- StreamEndPointB1 -- ServerHTTP3StreamConnection
 clientB                                                   ServerQuicheSessionB -# ServerHTTP3SessionB -- StreamEndPointB2 -- ServerHTTP3StreamConnection

In this case, the server specific, HTTP/3 specific, ProtocolSession creates and manages zero or more bidirectional QUIC streams, created by the clients, over which HTTP/3 bytes are exchanged by the two peers, as well as the unidirectional QUIC streams required by the HTTP/3 protocol.

In a more compact representation, the server side layout is the following:


 DatagramChannelEndPoint -- ServerQuicheConnection -*# ServerQuicheSession -- ServerHTTP3Session -* StreamEndPoint -- ServerHTTP3StreamConnection
where -- represents a 1-1 relationship, -* represents a 1-N relationship, and -# represents the place where a new thread is dispatched to process different QUIC connection ids so that they can be processed in parallel, as it would naturally happen with TCP (which has a "thread per active connection" model).