Struct EndpointConfig

pub struct EndpointConfig { /* private fields */ }

Available on crate features quic and std only.

Expand description

Global configuration for the endpoint, affecting all connections

Supply a secret reset key with Self::new; the remaining settings suit most internet applications. crate::EndpointBuilder generates a fresh random key when no endpoint configuration is supplied.

Implementations§

§

impl EndpointConfig

pub fn new(reset_key: HmacSha2) -> EndpointConfig

Create an endpoint configuration with the supplied secret reset key.

Reuse the same key and HMAC algorithm to keep reset tokens stable across restarts.

use rama_crypto::hmac::HmacSha2;
use rama_quic::EndpointConfig;

let key = HmacSha2::try_rand_256()?;
let config = EndpointConfig::new(key);

pub fn handshake_timeout( &mut self, value: Duration, ) -> Result<&mut EndpointConfig, ConfigError>

Maximum time to complete a handshake, including time awaiting application acceptance.

Defaults to ten seconds. This local resource limit remains active when the negotiated idle timeout is disabled. The duration must be nonzero and fit the runtime clock when the endpoint is constructed.

pub fn with_receive_queue_limits( self, connection: ReceiveQueueLimits, endpoint: ReceiveQueueLimits, ) -> EndpointConfig

Bound each connection’s queue of received packets awaiting its driver, and the aggregate storage across the endpoint including queued incoming connection attempts.

Defaults to 256 datagrams / 512 KiB per connection and 8192 datagrams / 16 MiB per endpoint. Each queued datagram is charged its retained capacity plus a fixed per-message overhead. A saturated queue drops and counts further packets; protocol stream buffers and pending-handshake buffers have their own limits. The endpoint checks at construction that one maximum-size datagram fits each limit.

pub fn set_receive_queue_limits( &mut self, connection: ReceiveQueueLimits, endpoint: ReceiveQueueLimits, ) -> &mut EndpointConfig

Bound each connection’s queue of received packets awaiting its driver, and the aggregate storage across the endpoint including queued incoming connection attempts.

Defaults to 256 datagrams / 512 KiB per connection and 8192 datagrams / 16 MiB per endpoint. Each queued datagram is charged its retained capacity plus a fixed per-message overhead. A saturated queue drops and counts further packets; protocol stream buffers and pending-handshake buffers have their own limits. The endpoint checks at construction that one maximum-size datagram fits each limit.

pub fn with_cid_generator( self, factory: Arc<dyn Fn() -> Box<dyn ConnectionIdGenerator> + Sync + Send>, ) -> EndpointConfig

How this endpoint generates the connection IDs it asks peers to send to.

The factory is called once per Endpoint built from this configuration, and that generator issues the identifiers of every connection on it. HashedConnectionIdGenerator is the default; RandomConnectionIdGenerator gives identifiers of a chosen length, and a generator of your own can carry whatever a load balancer in front of the endpoint needs to read, as long as it keeps to what ConnectionIdGenerator::generate_cid requires.

pub fn set_cid_generator( &mut self, factory: Arc<dyn Fn() -> Box<dyn ConnectionIdGenerator> + Sync + Send>, ) -> &mut EndpointConfig

How this endpoint generates the connection IDs it asks peers to send to.

The factory is called once per Endpoint built from this configuration, and that generator issues the identifiers of every connection on it. HashedConnectionIdGenerator is the default; RandomConnectionIdGenerator gives identifiers of a chosen length, and a generator of your own can carry whatever a load balancer in front of the endpoint needs to read, as long as it keeps to what ConnectionIdGenerator::generate_cid requires.

pub fn with_stateless_reset_key(self, key: StatelessResetKey) -> EndpointConfig

Set the secret used to derive stateless reset tokens.

Keep the key secret and reuse it across endpoint restarts when peers should recognise resets for connections whose state was lost.

pub fn set_stateless_reset_key( &mut self, key: StatelessResetKey, ) -> &mut EndpointConfig

Set the secret used to derive stateless reset tokens.

Keep the key secret and reuse it across endpoint restarts when peers should recognise resets for connections whose state was lost.

pub fn max_udp_payload_size( &mut self, value: u16, ) -> Result<&mut EndpointConfig, ConfigError>

Maximum UDP payload size accepted from peers (excluding UDP and IP overhead).

Must be greater or equal than 1200.

Defaults to 1472, which is the largest UDP payload that can be transmitted in the typical 1500 byte Ethernet MTU. Deployments on links with larger MTUs (e.g. loopback or Ethernet with jumbo frames) can raise this to improve performance at the cost of a linear increase in datagram receive buffer size.

pub fn with_supported_versions( self, supported_versions: Vec<u32>, ) -> EndpointConfig

Override supported QUIC versions

pub fn set_supported_versions( &mut self, supported_versions: Vec<u32>, ) -> &mut EndpointConfig

Override supported QUIC versions

pub fn with_grease_quic_bit(self, value: bool) -> EndpointConfig

Whether to accept QUIC packets containing any value for the fixed bit

Enabled by default. Helps protect against protocol ossification and makes traffic less identifiable to observers. Disable if helping observers identify this traffic as QUIC is desired.

pub fn set_grease_quic_bit(&mut self, value: bool) -> &mut EndpointConfig

Whether to accept QUIC packets containing any value for the fixed bit

Enabled by default. Helps protect against protocol ossification and makes traffic less identifiable to observers. Disable if helping observers identify this traffic as QUIC is desired.

pub fn with_min_reset_interval(self, value: Duration) -> EndpointConfig

Minimum interval between outgoing stateless reset packets

Defaults to 20ms. Limits the impact of attacks which flood an endpoint with garbage packets, e.g. ISAKMP/IKE amplification. Larger values provide a stronger defense, but may delay detection of some error conditions by clients. Using a ConnectionIdGenerator with a low rate of false positives in validate reduces the risk incurred by a small minimum reset interval.

pub fn set_min_reset_interval(&mut self, value: Duration) -> &mut EndpointConfig

Minimum interval between outgoing stateless reset packets

Defaults to 20ms. Limits the impact of attacks which flood an endpoint with garbage packets, e.g. ISAKMP/IKE amplification. Larger values provide a stronger defense, but may delay detection of some error conditions by clients. Using a ConnectionIdGenerator with a low rate of false positives in validate reduces the risk incurred by a small minimum reset interval.