Struct wtransport::config::ClientConfigBuilder

pub struct ClientConfigBuilder<State>(/* private fields */);

Client builder configuration.

The builder might have different state at compile time.

Example

let config = ClientConfig::builder().with_bind_default();

Implementations

impl ClientConfigBuilder<WantsBindAddress>

pub fn with_bind_default(self) -> ClientConfigBuilder<WantsRootStore>

Configures for connecting binding ANY IP (allowing IP dual-stack).

Bind port will be randomly picked.

This is equivalent to: Self::with_bind_config with IpBindConfig::InAddrAnyDual.

pub fn with_bind_config( self, ip_bind_config: IpBindConfig, ) -> ClientConfigBuilder<WantsRootStore>

Sets the binding (local) socket address with a specific IpBindConfig.

Bind port will be randomly picked.

pub fn with_bind_address( self, address: SocketAddr, ) -> ClientConfigBuilder<WantsRootStore>

Sets the binding (local) socket address for the endpoint.

pub fn with_bind_address_v6( self, address: SocketAddrV6, dual_stack_config: Ipv6DualStackConfig, ) -> ClientConfigBuilder<WantsRootStore>

Sets the binding (local) socket address for the endpoint.

dual_stack_config allows/denies dual stack port binding.

impl ClientConfigBuilder<WantsRootStore>

pub fn with_native_certs( self, ) -> ClientConfigBuilder<WantsTransportConfigClient>

Configures the client to use native (local) root certificates for server validation.

This method loads trusted root certificates from the system’s certificate store, ensuring that your client can trust certificates signed by well-known authorities.

It configures safe default TLS configuration.

pub fn with_no_cert_validation( self, ) -> ClientConfigBuilder<WantsTransportConfigClient>

Available on crate feature dangerous-configuration only.

Configures the client to skip server certificate validation, potentially compromising security.

This method is intended for advanced users and should be used with caution. It configures the client to bypass server certificate validation during the TLS handshake, effectively trusting any server certificate presented, even if it is not signed by a trusted certificate authority (CA). Using this method can expose your application to security risks.

Safety Note

Using with_no_cert_validation should only be considered when you have a specific need to disable certificate validation. In most cases, it is strongly recommended to validate server certificates using trusted root certificates (e.g., with_native_certs) to ensure secure communication.

However, this method can be useful in testing environments or situations where you intentionally want to skip certificate validation for specific use cases.

pub fn with_server_certificate_hashes<I>( self, hashes: I, ) -> ClientConfigBuilder<WantsTransportConfigClient>

where I: IntoIterator<Item = Sha256Digest>,

Configures the client to skip some server certificates validation.

This method configures the client to accept server certificates whose digests match the specified SHA-256 hashes and fulfill some additional constraints (see notes below).

This is useful for scenarios where clients need to accept known self-signed certificates or certificates from non-standard authorities.

This method configuration is similar to the browser W3C WebTransport API.

Notes

• The current time MUST be within the validity period of the certificate.
• The total length of the validity period MUST NOT exceed two weeks.
• Only certificates for which the public key algorithm is ECDSA with the secp256r1 are accepted.

pub fn with_custom_tls( self, tls_config: TlsClientConfig, ) -> ClientConfigBuilder<WantsTransportConfigClient>

Allows for manual configuration of a custom TLS setup using a provided rustls::ClientConfig, which must support rustls::CipherSuite::TLS13_AES_128_GCM_SHA256. A suitable configuration can be obtained using the ring crypto provider with a set of versions containing rustls::version::TLS13.

This method is provided for advanced users who need fine-grained control over the TLS configuration. It allows you to pass a preconfigured rustls::ClientConfig instance to customize the TLS settings according to your specific requirements.

For most use cases, it is recommended to use the with_native_certs method to configure TLS with safe defaults.

pub fn with_custom_transport( self, quic_transport_config: QuicTransportConfig, ) -> ClientConfigBuilder<WantsTransportConfigClient>

Available on crate feature quinn only.

Similar to with_native_certs, but it allows specifying a custom QUIC transport configuration.

Parameters

• quic_transport_config: A custom QuicTransportConfig instance that allows you to specify various QUIC transport-layer settings according to your requirements.

Example

use wtransport::config::QuicTransportConfig;
use wtransport::ClientConfig;

// Create a custom QuicTransportConfig with specific settings
let mut custom_transport_config = QuicTransportConfig::default();
custom_transport_config.datagram_send_buffer_size(1024);

// Create a ClientConfigBuilder with the custom transport configuration and default TLS settings
let client_config = ClientConfig::builder()
    .with_bind_default()
    .with_custom_transport(custom_transport_config)
    .build();

pub fn with_custom_tls_and_transport( self, tls_config: TlsClientConfig, quic_transport_config: QuicTransportConfig, ) -> ClientConfigBuilder<WantsTransportConfigClient>

Available on crate feature quinn only.

Configures the client with both a custom TLS configuration and a custom QUIC transport configuration.

This method is designed for advanced users who require full control over both the TLS and transport settings. It allows you to pass a preconfigured TlsClientConfig and a custom QuicTransportConfig to fine-tune both layers of the server configuration.

Parameters

• tls_config: A custom TlsClientConfig instance that allows you to specify detailed TLS settings, such as ciphersuites, certificate verification, and more. It must support TLS 1.3 (see the documentation of Self::with_custom_tls).
• quic_transport_config: A custom QuicTransportConfig instance that allows you to specify various QUIC transport-layer settings according to your requirements.

pub fn build_with_quic_config( self, quic_config: QuicClientConfig, ) -> ClientConfig

Available on crate feature quinn only.

Directly builds ClientConfig skipping TLS and transport configuration.

Both TLS and transport configuration is given by quic_config.

impl ClientConfigBuilder<WantsTransportConfigClient>

pub fn build(self) -> ClientConfig

Completes configuration process.

Panics

See the documentation of Self::with_custom_tls for the TLS 1.3 requirement.

pub fn max_idle_timeout( self, idle_timeout: Option<Duration>, ) -> Result<Self, InvalidIdleTimeout>

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.

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

pub fn keep_alive_interval(self, interval: Option<Duration>) -> Self

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 max_idle_timeout of both peers to be effective.

pub fn dns_resolver<R>(self, dns_resolver: R) -> Self

where R: DnsResolver + Send + Sync + 'static,

Sets the DNS resolver used during Endpoint::connect.

Default configuration uses TokioDnsResolver.

Trait Implementations

impl Default for ClientConfigBuilder<WantsBindAddress>

fn default() -> Self

Returns the “default value” for a type.