ClientBuilder

A convenience method for specifying a client with one or more com.twitter.finagle.Addresss.

To migrate to the Stack-based APIs, use com.twitter.finagle.Client.newService(Name, String). For the label String, use the scope you want for your StatsReceiver. For example:

import com.twitter.finagle.{Http, Name}

val name: Name = Name.bound(addrs: _*)
Http.client.newService(name, "the_client_name")

The base com.twitter.finagle.Dtab used to interpret logical destinations for this client. (This is given as a function to permit late initialization of com.twitter.finagle.Dtab.base.)

To migrate to the Stack-based APIs, use configured. For example:

import com.twitter.finagle.Http
import com.twitter.finagle.factory.BindingFactory

Http.client.configured(BindingFactory.BaseDtab(baseDtab))

Construct a Service.

To migrate to the Stack-based APIs, use Client.newService. For example:

import com.twitter.finagle.Http

Http.client.newService(destination)

Construct a ServiceFactory. This is useful for stateful protocols (e.g., those that support transactions or authentication).

To migrate to the Stack-based APIs, use Client.newClient. For example:

import com.twitter.finagle.Http

Http.client.newClient(destination)

Specify a cluster directly. A com.twitter.finagle.builder.Cluster defines a dynamic mechanism for specifying a set of endpoints to which this client remains connected.

A variation of codec for codecs that support only client-codecs.

To migrate to the Stack-based APIs, use ClientBuilder.stack(Protocol.client) instead. For example:

import com.twitter.finagle.Http

ClientBuilder().stack(Http.client)

A variation of codec that supports codec factories. This is used by codecs that need dynamic construction, but should be transparent to the user.

To migrate to the Stack-based APIs, use ClientBuilder.stack(Protocol.client) instead. For example:

import com.twitter.finagle.Http

ClientBuilder().stack(Http.client)

Specify the codec. The codec implements the network protocol used by the client, and consequently determines the Req and Rep type variables. One of the codec variations is required.

To migrate to the Stack-based APIs, use ClientBuilder.stack(Protocol.client) instead. For example:

import com.twitter.finagle.Http

ClientBuilder().stack(Http.client)

Java friendly API for configuring the underlying Params.

The Tuple2 can often be created by calls to a mk(): (P, Stack.Param[P]) method on parameters (see com.twitter.finagle.loadbalancer.LoadBalancerFactory.Param.mk() as an example).

Configure the underlying Params.

Java users may find it easier to use the Tuple2 version below.

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)

When true, the client is daemonized. As with java threads, a process can exit only when all remaining clients are daemonized. False by default.

The default for the Stack-based APIs is for the client to be daemonized.

The logical destination of requests dispatched through this client.

To migrate to the Stack-based APIs, use this in the call to newClient or newService. For example:

import com.twitter.finagle.Http

Http.client.newService(name)

The logical destination of requests dispatched through this client, as evaluated by a resolver. If the name evaluates a label, this replaces the builder's current name.

To migrating to the Stack-based APIs, you pass the destination to newClient or newService. If the addr is labeled, additionally, use CommonParams.withLabel

import com.twitter.finagle.Http

Http.client
  .withLabel("client_name")
  .newService(name)

Provide an alternative to putting all request exceptions under a "failures" stat. Typical implementations may report any cancellations or validation errors separately so success rate considers only valid non cancelled requests.

To migrate to the Stack-based APIs, use CommonParams.withExceptionStatsHandler. For example:

import com.twitter.finagle.Http

Http.client.withExceptionStatsHandler(exceptionStatsHandler)

Make connections via the given HTTP proxy by host name and port. The host name is resolved every transport connection. This API is experiment. If this is defined concurrently with socksProxy, the order in which they are applied is undefined.

Make connections via the given HTTP proxy by host name and port. The host name is resolved every transport connection. This API is experiment. If this is defined concurrently with httpProxy, the order in which they are applied is undefined.

Marks a host dead on connection failure. The host remains dead until we successfully connect. Intermediate connection attempts *are* respected, but host availability is turned off during the reconnection period.

To migrate to the Stack-based APIs, use SessionQualificationParams.noFailFast. For example:

import com.twitter.finagle.Http

Http.client.withSessionQualifier.noFailFast

Completely replaces the FailureAccrualFactory from the underlying stack with the ServiceFactoryWrapper returned from the given function factory.

To completely disable FailureAccrualFactory use noFailureAccrual.

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.

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)

The amount of time a connection is allowed to linger (when it otherwise would have been closed by the pool) before being closed.

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)

The maximum time a connection is allowed to linger unused.

To migrate to the Stack-based APIs, use SessionParams.maxIdleTime. For example:

import com.twitter.finagle.Http

Http.client.withSession.maxIdleTime(timeout)

The maximum time a connection is allowed to exist, regardless of occupancy.

To migrate to the Stack-based APIs, use SessionParams.maxLifeTime. For example:

import com.twitter.finagle.Http

Http.client.withSession.maxLifeTime(timeout)

The maximum queue size for the connection pool.

To migrate to the Stack-based APIs, use SessionPoolingParams.maxWaiters. For example:

import com.twitter.finagle.Http

Http.client.withSessionPool.maxWaiters(nWaiters)

A convenience method for specifying a one-host java.net.SocketAddress client.

To migrate to the Stack-based APIs, use com.twitter.finagle.Client.newService(Name, String). For the label String, use the scope you want for your StatsReceiver. For example:

import com.twitter.finagle.{Address, Http, Name}

val name: Name = Name.bound(Address(address))
Http.client.newService(name, "the_client_name")

A variant of hosts that takes a sequence of java.net.InetSocketAddress instead.

To migrate to the Stack-based APIs, use com.twitter.finagle.Client.newService(Name, String). For the label String, use the scope you want for your StatsReceiver. For example:

import com.twitter.finagle.{Address, Http, Name}

val addresses: Seq[Address] = sockaddrs.map(Address(_))
val name: Name = Name.bound(addresses: _*)
Http.client.newService(name, "the_client_name")

Specify the set of hosts to connect this client to. Requests will be load balanced across these. This is a shorthand form for specifying a cluster.

One of the hosts variations or direct specification of the cluster (via cluster) is required.

To migrate to the Stack-based APIs, pass the hostname and port pairs into com.twitter.finagle.Client.newService(String). For example:

import com.twitter.finagle.Http

Http.client.newService("hostnameA:portA,hostnameB:portB")

Make connections via the given HTTP proxy. If this is defined concurrently with socksProxy, the order in which they are applied is undefined.

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)))

Specify a load balancer. The load balancer implements a strategy for choosing one host from a set to service a request.

To migrate to the Stack-based APIs, use withLoadBalancer(LoadBalancerFactory). For example:

import com.twitter.finagle.Http

Http.client.withLoadBalancer(loadBalancer)

Log very detailed debug information to the given logger.

To migrate to the Stack-based APIs, use configured. For example:

import com.twitter.finagle.Http
import com.twitter.finagle.param.Logger

Http.client.configured(Logger(logger))

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)

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")

Disables FailureAccrualFactory.

To replace the FailureAccrualFactory use failureAccrualFactory.

To migrate to the Stack-based APIs, use SessionQualificationParams.noFailureAccrual. For example:

import com.twitter.finagle.Http

Http.client.withSessionQualifier.noFailureAccrual

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))

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)

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)

The currently configured com.twitter.finagle.service.ResponseClassifier.

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)

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 WriteExceptions and Failures that are marked restartable.

The configured policy has jittered backoffs between retries.

To migrate to the Stack-based APIs, use this method in conjunction with ClientBuilder.stack. For example:

import com.twitter.finagle.Http

ClientBuilder()
  .stack(Http.client)
  .retries(value)

The 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)

The 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)

Retry failed requests according to the given RetryPolicy.

To migrate to the Stack-based APIs, use this method in conjunction with ClientBuilder.stack. For example:

import com.twitter.finagle.Http

ClientBuilder()
  .stack(Http.client)
  .retryPolicy(value)

Make connections via the given SOCKS proxy. If this is defined concurrently with httpProxy, the order in which they are applied is undefined.

To migrate to the Stack-based APIs, use ClientTransportParams.socksProxy. For example:

import com.twitter.finagle.Http

Http.client.withTransport.socksProxy(socketAddress, socksProxy)

For the socks proxy use this username for authentication. socksPassword and socksProxy must be set as well

Overrides the stack and com.twitter.finagle.Client that will be used by this builder.

Specify the TCP connection timeout.

To migrate to the Stack-based APIs, use ClientTransportParams.connectTimeout. For example:

import com.twitter.finagle.Http

Http.client.withTransport.connectTimeout(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 this method in conjunction with ClientBuilder.stack. For example:

import com.twitter.finagle.Http

ClientBuilder()
  .stack(Http.client)
  .timeout(duration)

Encrypt the connection with SSL. The Engine to use can be passed into the client. This allows the user to use client certificates SSL Hostname Validation is performed, on the passed in hostname

Encrypt the connection with SSL. The Engine to use can be passed into the client. This allows the user to use client certificates No SSL 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)

Encrypt the connection with SSL. 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)

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

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)

Configures the traffic class.

Use the given channel factory instead of the default. Note that when using a non-default ChannelFactory, finagle can't meaningfully reference count factory usage, and so the caller is responsible for calling releaseExternalResources().

Experimental option to buffer size connections from the pool. The buffer is fast and lock-free, reducing contention for services with very high requests rates. The buffer size should be sized roughly to the expected concurrency. Buffers sized by power-of-twos may be faster due to the use of modular arithmetic.

The maximum time a connection may have received no data.

To migrate to the Stack-based APIs, use TransportParams.readTimeout. For example:

import com.twitter.finagle.Http

Http.client.withTransport.readTimeout(duration)

Sets the TCP recv buffer size.

To migrate to the Stack-based APIs, use TransportParams.receiveBufferSize. For example:

import com.twitter.finagle.Http

Http.client.withTransport.receiveBufferSize(value)

Sets the TCP send buffer size.

To migrate to the Stack-based APIs, use TransportParams.sendBufferSize. For example:

import com.twitter.finagle.Http

Http.client.withTransport.sendBufferSize(value)

Specifies a tracer that receives trace events. See com.twitter.finagle.tracing for details.

The maximum time a connection may not have sent any data.

To migrate to the Stack-based APIs, use TransportParams.writeTimeout. For example:

import com.twitter.finagle.Http

Http.client.withTransport.writeTimeout(duration)