Struct TransportConfig

pub struct TransportConfig { /* private fields */ }

Available on crate features quic and std only.

Expand description

Parameters governing the core QUIC state machine

Default values should be suitable for most internet applications. Applications protocols which forbid remotely-initiated streams should set max_concurrent_bidi_streams and max_concurrent_uni_streams to zero.

In some cases, performance or resource requirements can be improved by tuning these values to suit a particular application and/or network connection. In particular, data window sizes can be tuned for a particular expected round trip time, link capacity, and memory availability. Tuning for higher bandwidths and latencies increases worst-case memory consumption, but does not impair performance at lower bandwidths and latencies. The default configuration is tuned for a 100Mbps link with a 100ms round trip time.

Implementations§

§

impl TransportConfig

pub fn with_max_concurrent_bidi_streams(self, value: VarInt) -> TransportConfig

Maximum number of incoming bidirectional streams that may be open concurrently

Must be nonzero for the peer to open any bidirectional streams.

Worst-case memory use is directly proportional to max_concurrent_bidi_streams * stream_receive_window, with an upper bound proportional to receive_window.

pub fn set_max_concurrent_bidi_streams( &mut self, value: VarInt, ) -> &mut TransportConfig

Maximum number of incoming bidirectional streams that may be open concurrently

Must be nonzero for the peer to open any bidirectional streams.

Worst-case memory use is directly proportional to max_concurrent_bidi_streams * stream_receive_window, with an upper bound proportional to receive_window.

pub fn with_max_concurrent_uni_streams(self, value: VarInt) -> TransportConfig

Variant of max_concurrent_bidi_streams affecting unidirectional streams

pub fn set_max_concurrent_uni_streams( &mut self, value: VarInt, ) -> &mut TransportConfig

Variant of max_concurrent_bidi_streams affecting unidirectional streams

pub fn maybe_with_max_idle_timeout( self, value: Option<IdleTimeout>, ) -> TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn maybe_set_max_idle_timeout( &mut self, value: Option<IdleTimeout>, ) -> &mut TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn with_max_idle_timeout(self, value: IdleTimeout) -> TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn set_max_idle_timeout( &mut self, value: IdleTimeout, ) -> &mut TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn without_max_idle_timeout(self) -> TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn unset_max_idle_timeout(&mut self) -> &mut TransportConfig

Maximum duration of inactivity to accept before timing out the connection.

The true idle timeout is the minimum of this and the peer’s own max idle timeout. None represents an infinite timeout. Defaults to 30 seconds.

WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

let mut config = TransportConfig::default();

// Set the idle timeout as `VarInt`-encoded milliseconds
config.set_max_idle_timeout(VarInt::from(10_000u32).into());

// Set the idle timeout as a `Duration`
config.set_max_idle_timeout(Duration::from_secs(10).try_into()?);

pub fn with_stream_receive_window(self, value: VarInt) -> TransportConfig

Maximum number of bytes the peer may transmit without acknowledgement on any one stream before becoming blocked.

This should be set to at least the expected connection latency multiplied by the maximum desired throughput. Setting this smaller than receive_window helps ensure that a single stream doesn’t monopolize receive buffers, which may otherwise occur if the application chooses not to read from a large stream for a time while still requiring data on other streams.

pub fn set_stream_receive_window( &mut self, value: VarInt, ) -> &mut TransportConfig

Maximum number of bytes the peer may transmit without acknowledgement on any one stream before becoming blocked.

This should be set to at least the expected connection latency multiplied by the maximum desired throughput. Setting this smaller than receive_window helps ensure that a single stream doesn’t monopolize receive buffers, which may otherwise occur if the application chooses not to read from a large stream for a time while still requiring data on other streams.

pub fn with_receive_window(self, value: VarInt) -> TransportConfig

Maximum number of bytes the peer may transmit across all streams of a connection before becoming blocked.

This should be set to at least the expected connection latency multiplied by the maximum desired throughput. Larger values can be useful to allow maximum throughput within a stream while another is blocked.

pub fn set_receive_window(&mut self, value: VarInt) -> &mut TransportConfig

Maximum number of bytes the peer may transmit across all streams of a connection before becoming blocked.

This should be set to at least the expected connection latency multiplied by the maximum desired throughput. Larger values can be useful to allow maximum throughput within a stream while another is blocked.

pub fn with_send_window(self, value: u64) -> TransportConfig

Maximum number of bytes to transmit to a peer without acknowledgment

Provides an upper bound on memory when communicating with peers that issue large amounts of flow control credit. Endpoints that wish to handle large numbers of connections robustly should take care to set this low enough to guarantee memory exhaustion does not occur if every connection uses the entire window.

pub fn set_send_window(&mut self, value: u64) -> &mut TransportConfig

Maximum number of bytes to transmit to a peer without acknowledgment

Provides an upper bound on memory when communicating with peers that issue large amounts of flow control credit. Endpoints that wish to handle large numbers of connections robustly should take care to set this low enough to guarantee memory exhaustion does not occur if every connection uses the entire window.

pub fn with_send_fairness(self, value: bool) -> TransportConfig

Whether to implement fair queuing for send streams having the same priority.

When enabled, connections schedule data from outgoing streams having the same priority in a round-robin fashion. When disabled, streams are scheduled in the order they are written to.

Note that this only affects streams with the same priority. Higher priority streams always take precedence over lower priority streams.

Disabling fairness can reduce fragmentation and protocol overhead for workloads that use many small streams.

pub fn set_send_fairness(&mut self, value: bool) -> &mut TransportConfig

Whether to implement fair queuing for send streams having the same priority.

When enabled, connections schedule data from outgoing streams having the same priority in a round-robin fashion. When disabled, streams are scheduled in the order they are written to.

Note that this only affects streams with the same priority. Higher priority streams always take precedence over lower priority streams.

Disabling fairness can reduce fragmentation and protocol overhead for workloads that use many small streams.

pub fn with_packet_threshold(self, value: u32) -> TransportConfig

Maximum reordering in packet number space before FACK style loss detection considers a packet lost. Should not be less than 3, per RFC5681.

pub fn set_packet_threshold(&mut self, value: u32) -> &mut TransportConfig

Maximum reordering in packet number space before FACK style loss detection considers a packet lost. Should not be less than 3, per RFC5681.

pub fn try_with_time_threshold( self, value: f32, ) -> Result<TransportConfig, ConfigError>

Maximum reordering in time space before time based loss detection considers a packet lost, as a factor of RTT. Must be finite and nonnegative; the resulting duration is at least the timer granularity. Defaults to 9/8.

pub fn try_set_time_threshold( &mut self, value: f32, ) -> Result<&mut TransportConfig, ConfigError>

Maximum reordering in time space before time based loss detection considers a packet lost, as a factor of RTT. Must be finite and nonnegative; the resulting duration is at least the timer granularity. Defaults to 9/8.

pub fn with_initial_rtt(self, value: Duration) -> TransportConfig

The RTT used before an RTT sample is taken

pub fn set_initial_rtt(&mut self, value: Duration) -> &mut TransportConfig

The RTT used before an RTT sample is taken

pub fn with_initial_mtu(self, value: u16) -> TransportConfig

The initial value to be used as the maximum UDP payload size before running MTU discovery (see TransportConfig::mtu_discovery_config).

Must be at least 1200, which is the default, and known to be safe for typical internet applications. Larger values are more efficient, but increase the risk of packet loss due to exceeding the network path’s IP MTU. If the provided value is higher than what the network path actually supports, packet loss will eventually trigger black hole detection and bring it down to TransportConfig::min_mtu.

pub fn set_initial_mtu(&mut self, value: u16) -> &mut TransportConfig

The initial value to be used as the maximum UDP payload size before running MTU discovery (see TransportConfig::mtu_discovery_config).

Must be at least 1200, which is the default, and known to be safe for typical internet applications. Larger values are more efficient, but increase the risk of packet loss due to exceeding the network path’s IP MTU. If the provided value is higher than what the network path actually supports, packet loss will eventually trigger black hole detection and bring it down to TransportConfig::min_mtu.

pub fn with_min_mtu(self, value: u16) -> TransportConfig

The maximum UDP payload size guaranteed to be supported by the network.

Must be at least 1200, which is the default, and lower than or equal to TransportConfig::set_initial_mtu.

Real-world MTUs can vary according to ISP, VPN, and properties of intermediate network links outside of either endpoint’s control. Extreme care should be used when raising this value outside of private networks where these factors are fully controlled. If the provided value is higher than what the network path actually supports, the result will be unpredictable and catastrophic packet loss, without a possibility of repair. Prefer TransportConfig::set_initial_mtu together with TransportConfig::mtu_discovery_config to set a maximum UDP payload size that robustly adapts to the network.

pub fn set_min_mtu(&mut self, value: u16) -> &mut TransportConfig

The maximum UDP payload size guaranteed to be supported by the network.

pub fn set_pad_to_mtu(&mut self, value: bool) -> &mut TransportConfig

Pad UDP datagrams carrying application data to current maximum UDP payload size

Disabled by default. UDP datagrams containing loss probes are exempt from padding.

Enabling this helps mitigate traffic analysis by network observers, but it increases bandwidth usage. Without this mitigation precise plain text size of application datagrams as well as the total size of stream write bursts can be inferred by observers under certain conditions. This analysis requires either an uncongested connection or application datagrams too large to be coalesced.

pub fn maybe_with_ack_frequency_config( self, value: Option<AckFrequencyConfig>, ) -> TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn maybe_set_ack_frequency_config( &mut self, value: Option<AckFrequencyConfig>, ) -> &mut TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn with_ack_frequency_config( self, value: AckFrequencyConfig, ) -> TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn set_ack_frequency_config( &mut self, value: AckFrequencyConfig, ) -> &mut TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn without_ack_frequency_config(self) -> TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn unset_ack_frequency_config(&mut self) -> &mut TransportConfig

Specifies the ACK frequency config (see AckFrequencyConfig for details)

The provided configuration will be ignored if the peer does not support the acknowledgement frequency QUIC extension.

Defaults to None, which disables controlling the peer’s acknowledgement frequency. Even if set to None, the local side still supports the acknowledgement frequency QUIC extension and may use it in other ways.

pub fn with_persistent_congestion_threshold(self, value: u32) -> TransportConfig

Number of consecutive PTOs after which network is considered to be experiencing persistent congestion.

pub fn set_persistent_congestion_threshold( &mut self, value: u32, ) -> &mut TransportConfig

Number of consecutive PTOs after which network is considered to be experiencing persistent congestion.

pub fn maybe_with_keep_alive_interval( self, value: Option<Duration>, ) -> TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn maybe_set_keep_alive_interval( &mut self, value: Option<Duration>, ) -> &mut TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn with_keep_alive_interval(self, value: Duration) -> TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn set_keep_alive_interval( &mut self, value: Duration, ) -> &mut TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn without_keep_alive_interval(self) -> TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn unset_keep_alive_interval(&mut self) -> &mut TransportConfig

Period of inactivity before sending a keep-alive packet

Keep-alive packets prevent an inactive but otherwise healthy connection from timing out.

None to disable, which is the default. Only one side of any given connection needs keep-alive enabled for the connection to be preserved. Must be set lower than the idle_timeout of both peers to be effective.

pub fn with_crypto_buffer_size(self, value: usize) -> TransportConfig

Maximum quantity of out-of-order crypto layer data to buffer

pub fn set_crypto_buffer_size(&mut self, value: usize) -> &mut TransportConfig

Maximum quantity of out-of-order crypto layer data to buffer

pub fn with_allow_spin(self, value: bool) -> TransportConfig

Whether the implementation is permitted to set the spin bit on this connection

This allows passive observers to easily judge the round trip time of a connection, which can be useful for network administration but sacrifices a small amount of privacy.

pub fn set_allow_spin(&mut self, value: bool) -> &mut TransportConfig

Whether the implementation is permitted to set the spin bit on this connection

This allows passive observers to easily judge the round trip time of a connection, which can be useful for network administration but sacrifices a small amount of privacy.

pub fn maybe_with_datagram_receive_buffer_size( self, value: Option<usize>, ) -> TransportConfig

Maximum number of incoming application datagram bytes to buffer, or None to disable incoming datagrams

The peer is forbidden to send single datagrams larger than this size. If the aggregate size of all datagrams that have been received from the peer but not consumed by the application exceeds this value, old datagrams are dropped until it is no longer exceeded.