in finagle-core/src/main/scala/com/twitter/finagle/builder/ClientBuilder.scala [490:1042]
def tcpConnectTimeout(duration: Duration): This =
configured(Transporter.ConnectTimeout(duration))
/**
* The request timeout is the time given to a *single* request (if
* there are retries, they each get a fresh request timeout). The
* timeout is applied only after a connection has been acquired.
* That is: it is applied to the interval between the dispatch of
* the request and the receipt of the response.
*
* To migrate to the Stack-based APIs, use `CommonParams.withRequestTimeout`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withRequestTimeout(duration)
* }}}
*
* @note if the request is not complete after `duration` the work that is
* in progress will be interrupted via [[Future.raise]].
*
* @see [[timeout(Duration)]]
*/
def requestTimeout(duration: Duration): This =
configured(TimeoutFilter.Param(duration))
/**
* The connect timeout is the timeout applied to the acquisition of
* a Service. This includes both queueing time (eg. because we
* cannot create more connections due to `hostConnectionLimit` and
* there are more than `hostConnectionLimit` requests outstanding)
* as well as physical connection time. Futures returned from
* `factory()` will always be satisfied within this timeout.
*
* This timeout is also used for name resolution, separately from
* queueing and physical connection time, so in the worst case the
* time to acquire a service may be double the given duration before
* timing out.
*
* To migrate to the Stack-based APIs, use `SessionParams.acquisitionTimeout`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withSession.acquisitionTimeout(duration)
* }}}
*/
def connectTimeout(duration: Duration): This =
configured(TimeoutFactory.Param(duration))
/**
* Total request timeout. This timeout is applied from the issuance
* of a request (through `service(request)`) until the
* satisfaction of that reply future. No request will take longer
* than this.
*
* Applicable only to service-builds (`build()`)
*
* To migrate to the Stack-based APIs, use `MethodBuilder`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client
* .methodBuilder("inet!localhost:8080")
* .withTimeoutTotal(duration)
* }}}
*
* @note if the request is not complete after `duration` the work that is
* in progress will be interrupted via [[Future.raise]].
*
* @see [[requestTimeout(Duration)]]
*/
def timeout(duration: Duration): This =
configured(TimeoutFilter.TotalTimeout(duration))
/**
* Apply TCP keepAlive (`SO_KEEPALIVE` socket option).
*
* To migrate to the Stack-based APIs, use `configured`.
* For example:
* {{{
* import com.twitter.finagle.Http
* import com.twitter.finagle.transport.Transport.Liveness
*
* val client = Http.client
* client.configured(client.params[Transport.Liveness].copy(keepAlive = Some(value)))
* }}}
*/
def keepAlive(value: Boolean): This =
configured(params[Transport.Liveness].copy(keepAlive = Some(value)))
/**
* Report stats to the given `StatsReceiver`. This will report
* verbose global statistics and counters, that in turn may be
* exported to monitoring applications.
*
* To migrate to the Stack-based APIs, use `CommonParams.withStatsReceiver`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withStatsReceiver(receiver)
* }}}
*
* @note Per hosts statistics will '''NOT''' be exported to this receiver
*
* @see [[ClientBuilder.reportHostStats]]
*/
def reportTo(receiver: StatsReceiver): This =
configured(Stats(receiver))
/**
* Report per host stats to the given `StatsReceiver`.
* The statsReceiver will be scoped per client, like this:
* client/connect_latency_ms_max/0.0.0.0:64754
*
* To migrate to the Stack-based APIs, use `configured`.
* For example:
* {{{
* import com.twitter.finagle.Http
* import com.twitter.finagle.loadbalancer.LoadBalancerFactory
*
* Http.client.configured(LoadBalancerFactory.HostStats(receiver))
* }}}
*/
def reportHostStats(receiver: StatsReceiver): This =
configured(LoadBalancerFactory.HostStats(receiver))
/**
* Give a meaningful name to the client. Required.
*
* To migrate to the Stack-based APIs, use `CommonParams.withLabel`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withLabel("my_cool_client")
* }}}
*/
def name(value: String): This =
configured(Label(value))
/**
* The maximum number of connections that are allowed per host.
* Required. Finagle guarantees to never have more active
* connections than this limit.
*
* To migrate to the Stack-based APIs, use `SessionPoolingParams.maxSize`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withSessionPool.maxSize(value)
* }}}
*
* @note not all protocol implementations support this style of connection
* pooling, such as `com.twitter.finagle.ThriftMux` and
* `com.twitter.finagle.Memcached`.
*/
def hostConnectionLimit(value: Int): ClientBuilder[Req, Rep, HasCluster, HasCodec, Yes] =
_configured(params[DefaultPool.Param].copy(high = value))
/**
* The core size of the connection pool: the pool is not shrinked below this limit.
*
* To migrate to the Stack-based APIs, use `SessionPoolingParams.minSize`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withSessionPool.minSize(value)
* }}}
*
* @note not all protocol implementations support this style of connection
* pooling, such as `com.twitter.finagle.ThriftMux` and
* `com.twitter.finagle.Memcached`.
*/
def hostConnectionCoresize(value: Int): This =
configured(params[DefaultPool.Param].copy(low = value))
/**
* Configure a [[com.twitter.finagle.service.ResponseClassifier]]
* which is used to determine the result of a request/response.
*
* This allows developers to give Finagle the additional application-specific
* knowledge necessary in order to properly classify them. Without this,
* Finagle cannot make judgements about application level failures as it only
* has a narrow understanding of failures (for example: transport level, timeouts,
* and nacks).
*
* As an example take an HTTP client that receives a response with a 500 status
* code back from a server. To Finagle this is a successful request/response
* based solely on the transport level. The application developer may want to
* treat all 500 status codes as failures and can do so via a
* [[com.twitter.finagle.service.ResponseClassifier]].
*
* It is a [[PartialFunction]] and as such multiple classifiers can be composed
* together via [[PartialFunction.orElse]].
*
* Response classification is independently configured on the client and server.
* For server-side response classification using [[com.twitter.finagle.builder.ServerBuilder]],
* see [[com.twitter.finagle.builder.ServerBuilder.responseClassifier]]
*
* To migrate to the Stack-based APIs, use `CommonParams.withResponseClassifier`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withResponseClassifier(classifier)
* }}}
*
* @see `com.twitter.finagle.http.service.HttpResponseClassifier` for some
* HTTP classification tools.
*
* @note If unspecified, the default classifier is
* [[com.twitter.finagle.service.ResponseClassifier.Default]]
* which is a total function fully covering the input domain.
*/
def responseClassifier(classifier: com.twitter.finagle.service.ResponseClassifier): This =
configured(param.ResponseClassifier(classifier))
/**
* The currently configured [[com.twitter.finagle.service.ResponseClassifier]].
*
* @note If unspecified, the default classifier is
* [[com.twitter.finagle.service.ResponseClassifier.Default]].
*/
def responseClassifier: com.twitter.finagle.service.ResponseClassifier =
params[param.ResponseClassifier].responseClassifier
/**
* Retry (some) failed requests up to `value - 1` times.
*
* Retries are only done if the request failed with something
* known to be safe to retry. This includes [[WriteException WriteExceptions]]
* and [[Failure]]s that are marked [[FailureFlags.Retryable retryable]].
*
* The configured policy has jittered backoffs between retries.
*
* To migrate to the Stack-based APIs, use `MethodBuilder`. For HTTP and
* ThriftMux, use `MethodBuilder#withMaxRetries`. For all other protocols,
* use `MethodBuilder.from(dest, stackClient)` to construct a MethodBuilder
* manually. Then use `MethodBuilder#withRetry.maxRetries` to configure the
* max number of retries.
*
* For example:
* {{{
* import com.twitter.finagle.Http
* import com.twitter.finagle.service.{ReqRep, ResponseClass}
* import com.twitter.util.Return
*
* Http.client
* .methodBuilder("inet!localhost:8080")
* // retry all HTTP 4xx and 5xx responses
* .withRetryForClassifier {
* case ReqRep(_, Return(rep)) if rep.statusCode >= 400 && rep.statusCode <= 599 =>
* ResponseClass.RetryableFailure
* }
* // retry up to 2 times, not including initial attempt
* .withMaxRetries(2)
* }}}
*
* @param value the maximum number of attempts (including retries) that
* can be made.
* - A value of `1` means one attempt and no retries
* on failure.
* - A value of `2` means one attempt and then a
* single retry if the failure is known to be safe to retry.
*
* @note The failures seen in the client will '''not include'''
* application level failures. This is particularly important for
* codecs that include exceptions, such as `Thrift`.
*
* This is only applicable to service-builds (`build()`).
*
* @see [[com.twitter.finagle.service.RetryPolicy.tries]]
*
* @see [[retryBudget]] for governing how many failed requests are
* eligible for retries.
*/
def retries(value: Int): This =
retryPolicy(RetryPolicy.tries(value))
/**
* Retry failed requests according to the given [[RetryPolicy]].
*
* To migrate to the Stack-based APIs, use `MethodBuilder`.
* For example:
* {{{
* import com.twitter.finagle.Http
* import com.twitter.finagle.service.{ReqRep, ResponseClass}
* import com.twitter.util.Return
*
* Http.client
* .methodBuilder("inet!localhost:8080")
* // retry all HTTP 4xx and 5xx responses
* .withRetryForClassifier {
* case ReqRep(_, Return(rep)) if rep.statusCode >= 400 && rep.statusCode <= 599 =>
* ResponseClass.RetryableFailure
* }
* }}}
*
* @note The failures seen in the client will '''not include'''
* application level failures. This is particularly important for
* codecs that include exceptions, such as `Thrift`.
*
* This is only applicable to service-builds (`build()`).
*
* @see [[retryBudget]] for governing how many failed requests are
* eligible for retries.
*/
def retryPolicy(value: RetryPolicy[Try[Nothing]]): This =
configured(Retries.Policy(value))
/**
* The [[RetryBudget budget]] is shared across requests and governs
* the number of retries that can be made.
*
* Helps prevent clients from overwhelming the downstream service.
*
* To migrate to the Stack-based APIs, use `ClientParams.withRetryBudget`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withRetryBudget(budget)
* }}}
*
* @see [[retryPolicy]] for per-request rules on which failures are
* eligible for retries.
*/
def retryBudget(budget: RetryBudget): This =
configured(Retries.Budget(budget))
/**
* The [[RetryBudget budget]] is shared across requests and governs
* the number of retries that can be made. When used for requeues,
* includes a stream of delays used to delay each retry.
*
* Helps prevent clients from overwhelming the downstream service.
*
* To migrate to the Stack-based APIs, use `ClientParams.withRetryBudget`
* and `ClientParams.withRetryBackoff`
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client
* .withRetryBudget(budget)
* .withRetryBackoff(backoffSchedule)
* }}}
*
* @see [[retryPolicy]] for per-request rules on which failures are
* eligible for retries.
*/
def retryBudget(budget: RetryBudget, backoffSchedule: Backoff): This =
configured(Retries.Budget(budget, backoffSchedule))
/**
* Encrypt the connection with SSL.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(config)
* }}}
*/
def tls(config: SslClientConfiguration): This =
configured(Transport.ClientSsl(Some(config)))
/**
* Encrypt the connection with SSL/TLS.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(config, engineFactory)
* }}}
*/
def tls(config: SslClientConfiguration, engineFactory: SslClientEngineFactory): This =
configured(Transport.ClientSsl(Some(config)))
.configured(SslClientEngineFactory.Param(engineFactory))
/**
* Encrypt the connection with SSL/TLS.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(config, sessionVerifier)
* }}}
*/
def tls(config: SslClientConfiguration, sessionVerifier: SslClientSessionVerifier): This =
configured(Transport.ClientSsl(Some(config)))
.configured(SslClientSessionVerifier.Param(sessionVerifier))
/**
* Encrypt the connection with SSL/TLS.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(config, engineFactory, sessionVerifier)
* }}}
*/
def tls(
config: SslClientConfiguration,
engineFactory: SslClientEngineFactory,
sessionVerifier: SslClientSessionVerifier
): This =
configured(Transport.ClientSsl(Some(config)))
.configured(SslClientEngineFactory.Param(engineFactory))
.configured(SslClientSessionVerifier.Param(sessionVerifier))
/**
* Encrypt the connection with SSL/TLS. Hostname verification will be
* provided against the given hostname.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(hostname)
* }}}
*/
def tls(hostname: String): This =
tls(SslClientConfiguration(hostname = Some(hostname)))
/**
* Encrypt the connection with SSL/TLS. The Engine to use can be passed into the client.
* No SSL/TLS Hostname Validation is performed
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tls`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tls(sslContext)
* }}}
*/
def tls(sslContext: SSLContext): This =
tls(SslClientConfiguration(), new SslContextClientEngineFactory(sslContext))
/**
* Encrypt the connection with SSL/TLS. The Engine to use can be passed into the client.
* SSL/TLS Hostname Validation is performed, on the passed in hostname
*/
def tls(sslContext: SSLContext, hostname: Option[String]): This =
tls(SslClientConfiguration(hostname = hostname), new SslContextClientEngineFactory(sslContext))
/**
* Do not perform TLS validation. Probably dangerous.
*
* To migrate to the Stack-based APIs, use `ClientTransportParams.tlsWithoutValidation`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTransport.tlsWithoutValidation
* }}}
*/
def tlsWithoutValidation(): This =
tls(SslClientConfiguration(trustCredentials = TrustCredentials.Insecure))
/**
* Make connections via the given HTTP proxy.
* If this is defined concurrently with socksProxy, socksProxy comes first. This
* means you may go through a SOCKS proxy and then an HTTP proxy, but not the
* other way around.
*/
def httpProxy(httpProxy: SocketAddress): This =
configured(params[Transporter.HttpProxy].copy(sa = Some(httpProxy)))
/**
* For the http proxy use these [[Credentials]] for authentication.
*/
def httpProxyUsernameAndPassword(credentials: Credentials): This =
configured(params[Transporter.HttpProxy].copy(credentials = Some(credentials)))
/**
* Make connections via the given SOCKS proxy.
* If this is defined concurrently with httpProxy, socksProxy comes first. This
* means you may go through a SOCKS proxy and then an HTTP proxy, but not the
* other way around.
*
* To migrate to the Stack-based APIs, use CLI flags based configuration for SOCKS.
* For example:
* {{{
* -Dcom.twitter.finagle.socks.socksProxyHost=127.0.0.1
* -Dcom.twitter.finagle.socks.socksProxyPort=50001
* }}}
*/
def socksProxy(socksProxy: Option[SocketAddress]): This =
configured(params[Transporter.SocksProxy].copy(sa = socksProxy))
/**
* For the socks proxy use this username for authentication.
* socksPassword and socksProxy must be set as well
*/
def socksUsernameAndPassword(credentials: (String, String)): This =
configured(params[Transporter.SocksProxy].copy(credentials = Some(credentials)))
/**
* Specifies a tracer that receives trace events.
* See [[com.twitter.finagle.tracing]] for details.
*
* To migrate to the Stack-based APIs, use `CommonParams.withTracer`.
* For example:
* {{{
* import com.twitter.finagle.Http
*
* Http.client.withTracer(t)
* }}}
*/
def tracer(t: com.twitter.finagle.tracing.Tracer): This =
configured(Tracer(t))
/**
* To migrate to the Stack-based APIs, use `CommonParams.withMonitor`.
* For example:
* {{{
* import com.twitter.finagle.Http
* import com.twitter.util.Monitor
*
* val monitor: Monitor = ???
* Http.client.withMonitor(monitor)
* }}}
*/
def monitor(mFactory: String => com.twitter.util.Monitor): This =
configured(MonitorFactory(mFactory))
/**
* Use the given parameters for failure accrual. The first parameter
* is the number of *successive* failures that are required to mark
* a host failed. The second parameter specifies how long the host
* is dead for, once marked.
*
* To completely disable [[FailureAccrualFactory]] use `noFailureAccrual`.
*/
def failureAccrualParams(pair: (Int, Duration)): This = {
val (numFailures, markDeadFor) = pair
configured(FailureAccrualFactory.Param(numFailures, () => markDeadFor))
}