mod.rs

Overview

This file implements a network transport layer using the wtransport library, which provides QUIC-based communication with TLS support. It defines the WTransport struct implementing the NetTransport trait, enabling creation of listeners and client connections over QUIC with TLS encryption. The file includes the handling of incoming connection requests, TLS ALPN negotiation, and data sending/receiving through asynchronous streams.

The transport supports configuration of TLS modes (including a debug mode), congestion control via the BBR algorithm, and customization of QUIC parameters such as stream limits, timeouts, and keep-alive intervals.

Main Components and Their Functionality

WTransport Struct

• Purpose: Acts as the main entry point for creating QUIC-based network listeners and connections.

• Fields:

  • debug_tls_mode: bool — Enables or disables debug mode for TLS configurations.

• Methods:

  • with_debug_tls_mode(mode: bool) -> Self
    Enables or disables debug TLS mode and returns the modified instance.

NetTransport Implementation for WTransport

Provides asynchronous methods to create listeners and connect as clients.

create_listener

• Parameters:

  • bind_addr: SocketAddr — The local socket address to bind the listener.

  • alpn_supported: &[&str] — List of supported ALPN protocols.

  • credential: NetCredential — Credentials used for TLS server identity.

• Returns:
  ResultSelf::Listener — A WTransportListener encapsulating the server endpoint.

• Functionality:
  Sets up the QUIC transport and TLS server configurations:

  • Configures maximum concurrent unidirectional streams.

  • Builds TLS server config with provided credential and ALPN protocols.

  • Sets keep-alive intervals, idle timeouts, UDP payload sizes.

  • Applies BBR congestion control and other transport parameters.

  • Creates a wtransport::Endpoint server instance.

• Usage Example:

  let listener = wtransport.create_listener(bind_addr, &["myprotocol"], credential).await?;
  

connect

• Parameters:

  • addr: SocketAddr — Remote address to connect to.

  • alpn_preferred: &[&str] — List of preferred ALPN protocols.

  • credential: NetCredential — Credentials used for TLS client identity.

• Returns:
  Result<Self::Connection> — A WTransportConnection representing the active connection.

• Functionality:
  Initializes a QUIC client endpoint with TLS client config, connects to the remote server, and returns the connection wrapper.

• Usage Example:

  let connection = wtransport.connect(remote_addr, &["myprotocol"], credential).await?;
  

WTransportListener Struct

• Purpose: Represents a server-side listener accepting incoming QUIC connections.

• Fields:

  • endpoint: Endpoint<Server> — The underlying QUIC server endpoint.

  • local_addr: SocketAddr — Local address bound by the listener.

  • local_identity: String — Identity string associated with the listener.

  • alpn_supported: HashSet<String> — Set of supported ALPN protocols.

• Implements: NetListener

  • accept() -> Result<WTransportIncomingRequest> — Asynchronously accepts an incoming connection request.

WTransportIncomingRequest Struct

• Purpose: Represents a pending incoming connection session.

• Fields:

  • request: IncomingSession — The underlying incoming QUIC session.

  • local_addr: SocketAddr — Local address of the listener.

  • local_identity: String — Listener identity string.

  • alpn_supported: HashSet<String> — Supported ALPN protocols.

• Implements: NetIncomingRequest

  • remote_addr() -> Result<SocketAddr> — Returns the remote peer address.

  • accept() -> Result<WTransportConnection> — Accepts the incoming session and finalizes connection setup, including ALPN negotiation.

ALPN Negotiation:
The accept() method inspects the incoming session headers for the ALPN_HEADER_NAME ("Acki-Nacki-ALPN"). It parses the header value, selects the first ALPN protocol supported by both local and remote peers, and records the negotiated protocol in the connection.

WTransportConnection Struct

• Purpose: Represents an established QUIC connection.

• Fields:

  • connection: Connection — The underlying QUIC connection object.

  • local_addr: SocketAddr — Local socket address of the connection.

  • local_identity: String — Local identity string.

  • alpn_negotiated: Option<String> — ALPN protocol negotiated during handshake.

• Implements: NetConnection

Key Methods:

• local_addr() -> SocketAddr
  Returns the local socket address.

• remote_addr() -> SocketAddr
  Returns the remote peer's socket address.

• local_identity() -> String
  Returns local identity as string.

• remote_identity() -> String
  Returns a string representing the remote peer's identity. If TLS certificates are present, it returns the hex-encoded hash of the first certificate; otherwise, it returns the remote address as a string.

• remote_certificate() -> Option<CertificateDer>
  Returns the DER-encoded remote peer certificate if available.

• alpn_negotiated() -> Option<String>
  Returns the negotiated ALPN protocol if any.

• send(data: &[u8]) -> Result<()>
  Sends data over a unidirectional stream asynchronously. Opens a uni stream, writes the data, and finishes the stream.

• close(code: usize)
  Closes the connection with the specified code.

• recv() -> Result<(Vec<u8>, Duration)>
  Receives data from a unidirectional stream asynchronously, returning the data and the duration it took to receive.

• watch_close()
  Placeholder for monitoring connection closure events (not yet implemented).

Important Implementation Details

• TLS Configuration:
  Server and client TLS configurations are created using helper functions server_tls_config and create_client_config from the tls module. Debug TLS mode can be toggled for development or troubleshooting.

• QUIC Transport Configuration:

  • Maximum concurrent unidirectional streams set to 1000.

  • Keep-alive intervals and idle timeouts for detecting broken connections.

  • UDP payload size limited to 65,000 bytes.

  • Minimum reset interval configured to 2 milliseconds.

  • Congestion control using BBR algorithm.

  • Send window size set to 2MB for throughput tuning.

• ALPN Protocol Negotiation:
  Uses a custom header Acki-Nacki-ALPN to communicate supported protocols during connection establishment. The negotiated protocol is stored in the connection for application layer use.

• Connection Identity Extraction:
  Remote identity is derived from the peer's TLS certificate hash if present, falling back to the remote address string.

• Asynchronous Streams for Data:
  Data is sent and received over QUIC unidirectional streams (open_uni and accept_uni), allowing independent data flows.

Interactions with Other Parts of the System

• TLS Module (tls)
  Provides TLS configurations used by this transport for securing connections.

• NetConnection, NetListener, NetTransport, NetCredential, and NetIncomingRequest Traits/Types
  This file implements these traits for QUIC transport, integrating with system-wide abstractions for network communication.

• wtransport Library
  The core QUIC and TLS transport library used for endpoint, connection, and session handling.

• rustls_pki_types
  Used for handling TLS certificate representations.

Visual Diagram: Class Structure Overview

classDiagram
class WTransport {
- debug_tls_mode: bool
+ with_debug_tls_mode()
+ create_listener()
+ connect()
}
class WTransportListener {
- endpoint: Endpoint<Server>
- local_addr: SocketAddr
- local_identity: String
- alpn_supported: HashSet<String>
+ accept()
}
class WTransportIncomingRequest {
- request: IncomingSession
- local_addr: SocketAddr
- local_identity: String
- alpn_supported: HashSet<String>
+ remote_addr()
+ accept()
}
class WTransportConnection {
- connection: Connection
- local_addr: SocketAddr
- local_identity: String
- alpn_negotiated: Option<String>
+ local_addr()
+ remote_addr()
+ local_identity()
+ remote_identity()
+ remote_certificate()
+ alpn_negotiated()
+ send()
+ close()
+ recv()
+ watch_close()
}
WTransport ..|> NetTransport
WTransportListener ..|> NetListener
WTransportIncomingRequest ..|> NetIncomingRequest
WTransportConnection ..|> NetConnection
WTransportListener --> WTransportIncomingRequest : accept()
WTransportIncomingRequest --> WTransportConnection : accept()
WTransport --> WTransportListener : create_listener()
WTransport --> WTransportConnection : connect()

Constants

• ALPN_HEADER_NAME: &str = "Acki-Nacki-ALPN"
  Header name used to transmit supported ALPN protocols during QUIC session negotiation.

Usage Flow Summary

1. Server Side:

   • Instantiate WTransport.

   • Call create_listener() with bind address, ALPN protocols, and credentials.

   • Use accept() on the listener to receive incoming requests.

   • Call accept() on WTransportIncomingRequest to accept connection and perform ALPN negotiation.

   • Use WTransportConnection to send/receive data.

2. Client Side:

   • Instantiate WTransport.

   • Call connect() with remote address, preferred ALPN protocols, and credentials.

   • Use returned WTransportConnection to communicate with server.

This file provides a performant and secure transport layer abstraction using QUIC and TLS, suitable for networked applications requiring multiplexed streams, low latency, and secure communication. It integrates with the rest of the system through defined traits for consistent usage patterns. For further details on TLS configuration and network traits, see the tls module and NetTransport interface.