A convenience method for specifying a client with one or more com.twitter.finagle.Addresss.
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.
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.naming.BindingFactory Http.client.configured(BindingFactory.BaseDtab(baseDtab))
Construct a Service.
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.
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)
Java friendly API for configuring the underlying Params.
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.
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.
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.
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.
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.
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.
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)
function to record failure details.
Marks a host dead on connection failure.
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
.
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.
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.
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)
not all protocol implementations support this style of connection
pooling, such as com.twitter.finagle.ThriftMux
and
com.twitter.finagle.Memcached
.
The maximum number of connections that are allowed per host.
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)
not all protocol implementations support this style of connection
pooling, such as com.twitter.finagle.ThriftMux
and
com.twitter.finagle.Memcached
.
A convenience method for specifying a one-host java.net.SocketAddress client.
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.
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.
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")
comma-separated "host:port" string.
Make connections via the given HTTP proxy.
Make connections via the given HTTP proxy. If this is defined concurrently with socksProxy, the order in which they are applied is undefined.
For the http proxy use these Credentials for authentication.
Apply TCP keepAlive (SO_KEEPALIVE
socket option).
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.
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.
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
.
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.
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.
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
The underlying Params used for configuration.
Report per host stats to the given StatsReceiver
.
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
.
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)
Per hosts statistics will NOT be exported to this receiver
The request timeout is the time given to a *single* request (if there are retries, they each get a fresh request timeout).
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)
if the request is not complete after duration
the work that is
in progress will be interrupted via Future.raise.
timeout(Duration)
The currently configured com.twitter.finagle.service.ResponseClassifier.
The currently configured com.twitter.finagle.service.ResponseClassifier.
If unspecified, the default classifier is com.twitter.finagle.service.ResponseClassifier.Default.
Configure a com.twitter.finagle.service.ResponseClassifier which is used to determine the result of a request/response.
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)
If unspecified, the default classifier is com.twitter.finagle.service.ResponseClassifier.Default which is a total function fully covering the input domain.
com.twitter.finagle.http.service.HttpResponseClassifier
for some
HTTP classification tools.
Retry (some) failed requests up to value - 1
times.
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 retryable.
The configured policy has jittered backoffs between retries.
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 }
the maximum number of attempts (including retries) that can be made.
1
means one attempt and no retries
on failure.2
means one attempt and then a
single retry if the failure is known to be safe to retry.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()
).
retryBudget for governing how many failed requests are eligible for retries.
The budget is shared across requests and governs the number of retries that can be made.
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)
retryPolicy for per-request rules on which failures are eligible for retries.
The budget is shared across requests and governs the number of retries that can be made.
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)
retryPolicy for per-request rules on which failures are eligible for retries.
Retry failed requests according to the given RetryPolicy.
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 }
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()
).
retryBudget for governing how many failed requests are eligible for retries.
Make connections via the given SOCKS proxy.
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.
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.
Overrides the stack and com.twitter.finagle.Client that will be used by this builder.
A StackBasedClient
representation of a
com.twitter.finagle.Client. client
is materialized with the state of
configuration when build
is called. There is no guarantee that all
builder parameters will be used by the resultant Client
; it is up to the
discretion of client
itself and the protocol implementation. For example,
the Mux protocol has no use for most connection pool parameters (e.g.
hostConnectionLimit
). Thus when configuring
com.twitter.finagle.ThriftMux
clients (via stack(ThriftMux.client)
),
such connection pool parameters will not be applied.
Specify the TCP connection timeout.
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.
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)
if the request is not complete after duration
the work that is
in progress will be interrupted via Future.raise.
requestTimeout(Duration)
Encrypt the connection with SSL/TLS.
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
Encrypt the connection with SSL/TLS.
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)
Encrypt the connection with SSL/TLS.
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)
Encrypt the connection with SSL/TLS.
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)
Encrypt the connection with SSL/TLS.
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)
Encrypt the connection with SSL/TLS.
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)
Encrypt the connection with SSL.
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)
Do not perform TLS validation.
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.
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.
Configures the traffic class.
Transporter.TrafficClass
Construct a Service, with runtime checks for builder completeness.
Construct a ServiceFactory, with runtime checks for builder completeness.
A builder of Finagle Clients.
Please see the user guide for information on the preferred
with
-style and MethodBuilder client-construction APIs.The
ClientBuilder
requires the definition ofcluster
,stack
, andhostConnectionLimit
. In Scala, these are statically type checked, and in Java the lack of any of the above causes a runtime error.The
build
method uses an implicit argument to statically typecheck the builder (to ensure completeness, see above). The Java compiler cannot provide such implicit, so we provide a separate function in Java to accomplish this. Thus, the Java code for the above isAlternatively, using the
unsafeBuild
method onClientBuilder
verifies the builder dynamically, resulting in a runtime error instead of a compiler error.Defaults
The following defaults are applied to clients constructed via ClientBuilder, unless overridden with the corresponding method. These defaults were chosen carefully so as to work well for most use cases.
Commonly-configured options:
connectTimeout
: Duration.ToptcpConnectTimeout
: 1 secondrequestTimeout
: Duration.Toptimeout
: Duration.TophostConnectionLimit
:Int.MaxValue
hostConnectionCoresize
: 0hostConnectionIdleTime
: Duration.TophostConnectionMaxWaiters
:Int.MaxValue
failFast
: truefailureAccrualParams
,failureAccrualFactory
:numFailures
= 5,markDeadFor
= 5 secondsAdvanced options:
Before changing any of these, make sure that you know exactly how they will affect your application -- these options are typically only changed by expert users.
keepAlive
: Unspecified, in which case the Java default offalse
is usedhostConnectionMaxIdleTime
: Duration.TophostConnectionMaxLifeTime
: Duration.TopThe user guide for information on the preferred
with
-style and MethodBuilder client-construction APIs.