QuicOptions.Builder

public static class QuicOptions.Builder extends Object

Builder for QuicOptions.

Public Method Summary

QuicOptions.Builder	addAllowedQuicHost(String quicHost) Adds a host to the QUIC allowlist.
QuicOptions.Builder	addClientConnectionOption(String clientConnectionOption) Adds a QUIC tag to send in a QUIC handshake's connection options that only affects the client.
QuicOptions.Builder	addConnectionOption(String connectionOption) Adds a QUIC tag to send in a QUIC handshake's connection options.
QuicOptions.Builder	addEnabledQuicVersion(String enabledQuicVersion) Adds a QUIC version to the list of QUIC versions to enable.
QuicOptions.Builder	addExtraQuicheFlag(String extraQuicheFlag) Sets an arbitrary QUICHE flag.
QuicOptions	build() Creates and returns the final QuicOptions instance, based on the values in this builder.
QuicOptions.Builder	closeSessionsOnIpChange(boolean closeSessionsOnIpChange) Sets whether QUIC sessions should be closed on IP address change.
QuicOptions.Builder	delayJobsWithAvailableSpdySession(boolean delayJobsWithAvailableSpdySession) Sets whether Cronet should wait for the primary path (usually QUIC) to be ready even if there's a secondary path of reaching the server (SPDY / HTTP2) which is ready immediately.
QuicOptions.Builder	enableTlsZeroRtt(boolean enableTlsZeroRtt) Sets whether TLS with 0-RTT should be enabled.
QuicOptions.Builder	goawaySessionsOnIpChange(boolean goawaySessionsOnIpChange) Sets whether QUIC sessions should be goaway'd on IP address change.
QuicOptions.Builder	increaseBrokenServicePeriodExponentially(boolean increaseBrokenServicePeriodExponentially) Sets whether the broken server period should scale exponentially.
QuicOptions.Builder	retryWithoutAltSvcOnQuicErrors(boolean retryWithoutAltSvcOnQuicErrors) Sets whether requests that failed with a QUIC protocol errors should be retried without using any alt-svc servers.
QuicOptions.Builder	setCryptoHandshakeTimeoutSeconds(long cryptoHandshakeTimeoutSeconds) Sets the timeout for a connection SSL handshake.
QuicOptions.Builder	setHandshakeUserAgent(String handshakeUserAgent) Sets the user agent to be used outside of HTTP requests (for example for QUIC handshakes).
QuicOptions.Builder	setIdleConnectionTimeoutSeconds(long idleConnectionTimeoutSeconds) Sets the maximum idle time for a connection.
QuicOptions.Builder	setInMemoryServerConfigsCacheSize(int inMemoryServerConfigsCacheSize) Sets how many server configurations (metadata like list of alt svc, whether QUIC is supported, etc.) should be held in memory.
QuicOptions.Builder	setInitialBrokenServicePeriodSeconds(long initialBrokenServicePeriodSeconds) Sets the initial for which Cronet shouldn't attempt to use QUIC for a given server after the server's QUIC support turned out to be broken.
QuicOptions.Builder	setPreCryptoHandshakeIdleTimeoutSeconds(long preCryptoHandshakeIdleTimeoutSeconds) Sets the maximum idle time for a connection which hasn't completed a SSL handshake yet.
QuicOptions.Builder	setRetransmittableOnWireTimeoutMillis(long retransmittableOnWireTimeoutMillis) Sets the maximum desired time between packets on wire.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Methods

public QuicOptions.Builder addAllowedQuicHost (String quicHost)

Adds a host to the QUIC allowlist.

If no hosts are specified, the per-host allowlist functionality is disabled. Otherwise, Cronet will only use QUIC when talking to hosts on the allowlist.

Parameters

quicHost

Returns

• the builder for chaining

public QuicOptions.Builder addClientConnectionOption (String clientConnectionOption)

Adds a QUIC tag to send in a QUIC handshake's connection options that only affects the client.

See addConnectionOption(String) for more details.

Parameters

clientConnectionOption

public QuicOptions.Builder addConnectionOption (String connectionOption)

Adds a QUIC tag to send in a QUIC handshake's connection options.

The QUIC tags should be presented as strings up to four letters long (for instance, NBHD).

As the QUIC tags are under active development and some are only relevant to the server, Cronet doesn't attempt to maintain a complete list of all supported QUIC flags as a part of the API. The flags. Flags supported by QUICHE, a QUIC implementation used by Cronet and Google servers, can be found here.

Parameters

connectionOption

Returns

• the builder for chaining

public QuicOptions.Builder addEnabledQuicVersion (String enabledQuicVersion)

Adds a QUIC version to the list of QUIC versions to enable.

If no versions are specified, Cronet will use a list of default QUIC versions.

The version format is specified by QUICHE. Outside of filtering out values known to be obsolete, Cronet doesn't process the versions anyhow and simply passes them along to QUICHE.

Parameters

enabledQuicVersion

Returns

• the builder for chaining

public QuicOptions.Builder addExtraQuicheFlag (String extraQuicheFlag)

Sets an arbitrary QUICHE flag. Flags should be passed in FLAG_NAME=FLAG_VALUE format. See the QUICHE code base for a full list of flags.

Parameters

extraQuicheFlag

Returns

• the builder for chaining

public QuicOptions build ()

Creates and returns the final QuicOptions instance, based on the values in this builder.

public QuicOptions.Builder closeSessionsOnIpChange (boolean closeSessionsOnIpChange)

Sets whether QUIC sessions should be closed on IP address change.

Don't use in combination with connection migration (configured using ConnectionMigrationOptions).

Parameters

closeSessionsOnIpChange

Returns

• the builder for chaining

public QuicOptions.Builder delayJobsWithAvailableSpdySession (boolean delayJobsWithAvailableSpdySession)

Sets whether Cronet should wait for the primary path (usually QUIC) to be ready even if there's a secondary path of reaching the server (SPDY / HTTP2) which is ready immediately.

Parameters

delayJobsWithAvailableSpdySession

Returns

• the builder for chaining

public QuicOptions.Builder enableTlsZeroRtt (boolean enableTlsZeroRtt)

Sets whether TLS with 0-RTT should be enabled.

0-RTT is a performance optimization avoiding an extra round trip when resuming connections to a known server.

Parameters

enableTlsZeroRtt

Returns

• the builder for chaining

See Also

• Cloudflare's 0-RTT blogpost

public QuicOptions.Builder goawaySessionsOnIpChange (boolean goawaySessionsOnIpChange)

Sets whether QUIC sessions should be goaway'd on IP address change.

Don't use in combination with connection migration (configured using ConnectionMigrationOptions).

Parameters

goawaySessionsOnIpChange

Returns

• the builder for chaining

public QuicOptions.Builder increaseBrokenServicePeriodExponentially (boolean increaseBrokenServicePeriodExponentially)

Sets whether the broken server period should scale exponentially.

If set to true, the initial delay (configurable by setInitialBrokenServicePeriodSeconds(long)) will be scaled exponentially for subsequent retries (SCALING_FACTOR^NUM_TRIES * delay). If false, the delay will scale linearly (SCALING_FACTOR * NUM_TRIES * delay).

Parameters

increaseBrokenServicePeriodExponentially

Returns

• the builder for chaining

public QuicOptions.Builder retryWithoutAltSvcOnQuicErrors (boolean retryWithoutAltSvcOnQuicErrors)

Sets whether requests that failed with a QUIC protocol errors should be retried without using any alt-svc servers.

Parameters

retryWithoutAltSvcOnQuicErrors

Returns

• the builder for chaining

public QuicOptions.Builder setCryptoHandshakeTimeoutSeconds (long cryptoHandshakeTimeoutSeconds)

Sets the timeout for a connection SSL handshake.

Parameters

cryptoHandshakeTimeoutSeconds

Returns

• the builder for chaining

public QuicOptions.Builder setHandshakeUserAgent (String handshakeUserAgent)

Sets the user agent to be used outside of HTTP requests (for example for QUIC handshakes).

To set the default user agent for HTTP requests, use CronetEngine.Builder.setUserAgent(String) instead.

Parameters

handshakeUserAgent

Returns

• the builder for chaining

public QuicOptions.Builder setIdleConnectionTimeoutSeconds (long idleConnectionTimeoutSeconds)

Sets the maximum idle time for a connection. TODO what happens to connection that are idle for too long?

Parameters

idleConnectionTimeoutSeconds

Returns

• the builder for chaining

public QuicOptions.Builder setInMemoryServerConfigsCacheSize (int inMemoryServerConfigsCacheSize)

Sets how many server configurations (metadata like list of alt svc, whether QUIC is supported, etc.) should be held in memory.

If the storage path is set (CronetEngine.Builder.setStoragePath(String), Cronet will also persist the server configurations on disk.

Parameters

inMemoryServerConfigsCacheSize

Returns

• the builder for chaining

public QuicOptions.Builder setInitialBrokenServicePeriodSeconds (long initialBrokenServicePeriodSeconds)

Sets the initial for which Cronet shouldn't attempt to use QUIC for a given server after the server's QUIC support turned out to be broken.

Once Cronet detects that a server advertises QUIC but doesn't actually speak it, it marks the server as broken and doesn't attempt to use QUIC when talking to the server for an amount of time. Once Cronet is past this point it will try using QUIC again. This is to balance short term (there's no point wasting resources to try QUIC if the server is broken) and long term (the breakage might have been temporary, using QUIC is generally beneficial) interests.

The delay is increased every unsuccessful consecutive retry. See increaseBrokenServicePeriodExponentially(boolean) for details.

Parameters

initialBrokenServicePeriodSeconds

Returns

• the builder for chaining

public QuicOptions.Builder setPreCryptoHandshakeIdleTimeoutSeconds (long preCryptoHandshakeIdleTimeoutSeconds)

Sets the maximum idle time for a connection which hasn't completed a SSL handshake yet.

Parameters

preCryptoHandshakeIdleTimeoutSeconds

Returns

• the builder for chaining

public QuicOptions.Builder setRetransmittableOnWireTimeoutMillis (long retransmittableOnWireTimeoutMillis)

Sets the maximum desired time between packets on wire.

When the retransmittable-on-wire time is exceeded Cronet will probe quality of the network using artificial traffic. Smaller timeouts will typically result in faster discovery of a broken or degrading path, but also larger usage of resources (battery, data).

Parameters

retransmittableOnWireTimeoutMillis

Returns

• the builder for chaining