finagle

package finagle

Finagle is an extensible RPC system.

Services are represented by class com.twitter.finagle.Service. Clients make use of com.twitter.finagle.Service objects while servers implement them.

Finagle contains a number of protocol implementations; each of these implement Client and/or com.twitter.finagle.Server. For example, Finagle's HTTP implementation, com.twitter.finagle.Http (in package finagle-http), exposes both.

Thus a simple HTTP server is built like this:

import com.twitter.finagle.{Http, Service}
import com.twitter.finagle.http.{Request, Response}
import com.twitter.util.{Await, Future}

val service = new Service[Request, Response] {
  def apply(req: Request): Future[Response] =
    Future.value(Response())
}
val server = Http.server.serve(":8080", service)
Await.ready(server)

We first define a service to which requests are dispatched. In this case, the service returns immediately with a HTTP 200 OK response, and with no content.

This service is then served via the Http protocol on TCP port 8080. Finally we wait for the server to stop serving.

We can now query our web server:

% curl -D - localhost:8080
HTTP/1.1 200 OK

Building an HTTP client is also simple. (Note that type annotations are added for illustration.)

import com.twitter.finagle.{Http, Service}
import com.twitter.finagle.http.{Request, Response}
import com.twitter.util.{Future, Return, Throw}

val client: Service[Request, Response] = Http.client.newService("localhost:8080")
val f: Future[Response] = client(Request()).respond {
  case Return(rep) =>
    printf("Got HTTP response %s\n", rep)
  case Throw(exc) =>
    printf("Got error %s\n", exc)
}

Http.client.newService("localhost:8080") constructs a new com.twitter.finagle.Service instance connected to localhost TCP port 8080. We then issue a HTTP/1.1 GET request to URI "/". The service returns a com.twitter.util.Future representing the result of the operation. We listen to this future, printing an appropriate message when the response arrives.

The Finagle homepage contains useful documentation and resources for using Finagle.

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

finagle
AnyRef
Any

Hide All
Show All

Visibility

Public
Protected

Package Members

package addr
package builder
package client
package context
package core
package dispatch
package exp
Package exp contains experimental code.
Package exp contains experimental code. This can be removed or stabilized (moved elsewhere) at any time.
package factory
package filter
package http
package http2
package liveness
package loadbalancer
This package implements client side load balancing algorithms.
This package implements client side load balancing algorithms.
As an end-user, see the Balancers API to create instances which can be used to configure a Finagle client with various load balancing strategies.
As an implementor, each algorithm gets its own subdirectory and is exposed via the Balancers object. Several convenient traits are provided which factor out common behavior and can be mixed in (i.e. Balancer, DistributorT, NodeT, and Updating).
package logging
package memcached
package mux
Package mux implements a generic RPC multiplexer with a rich protocol.
Package mux implements a generic RPC multiplexer with a rich protocol. Mux is itself encoding independent, so it is meant to use as the transport for other RPC systems (eg. thrift). In OSI terminology, it is a pure session layer.
In the below description, all numeric values are unsigned and in big-endian byte order. The schema size:4 body:10 defines the field size to be 4 bytes, followed by 10 bytes of the field body. The schema key~4 defines the field key to be defined by 4 bytes interpreted as the size of the field, followed by that many bytes comprising the field itself--it is shorthand for keysize:4 key:keysize. Groups are denoted by parenthesis; * denotes repetition of the previous schema 0 or more times, while {n} indicates repetition exactly n times. Unspecified sizes consume the rest of the frame: they may be specified only as the last field in the message.
All strings in Mux are Utf-8 encoded, and are never null-terminated.
Message framing
Messages in mux are framed with a 4-byte big-endian size header, followed by 1 byte describing the message type and a 3-byte tag; or, diagrammatically: size:4 type:1 tag:3. The remainder of the frame (size-4 bytes) contains the body. Its format depends on the message type, documented below.
Tag 0 designates a "marker" T message that expects no reply. Some messages may be split into an ordered sequence of fragments. Tag MSB=0 denotes the last message in such a sequence, making the tag namespace 23 bits. The tag is otherwise arbitrary, and is chosen by the sender of the T message.
Currently, only Tdispatch and Rdispatch messages may be split into an ordered sequence of fragments. TdispatchError message ends a Tdispatch sequence and an Rerr ends an Rdispatch sequence.
Message types, interpreted as a two's complement, 1-byte integer are numbered as follows: positive numbers are T-messages; their negative complement is the corresponding R message. T-messages greater than 63 (correspondingly R-messages smaller than -63) are session messages. The message number -128 is reserved for Rerr. All other messages are application messages. Middle boxes may forward application messages indiscriminately. Because of an early implementation bug, two aliases exist: 127 is Rerr, and -62 is Tdiscarded.
The protocol is full duplex: both the server and client may send T messages initiating an exchange.
Exchanges
Messages are designated as "T messages" or "R messages", T and R being stand-ins for transmit and receive. A T message initiates an exchange and is assigned a free tag by the sender. A reply is either an R message of the same type (Rx replies to Tx for some x), or an Rerr, indicating a session layer error. R messages are matched to their T messages by tag, and the reply concludes the exchange and frees the tag for future use. Implementations should reuse small tag numbers.
Messages
size:4 Tinit:1 tag:3 version:2 (key~4 value~4)* reinitializes a session. Clients typically send this at the beginning of the session. When doing so, the sender may issue no more T messages until the corresponding size:4 Rinit:1 tag:3 version:2 (key~4 value~4)* has been received. After the Rinit was received, all connection state has been reset (outstanding tags are invalidated) and the stream is resumed according to the newly negotiated parameters. Prior to the first Tinit, the session operates at version 1. Rinit's version field is the accepted version of the session (which may be lower than the one requested by Tinit).
size:4 Treq:1 tag:3 n:1 (key:1 value~1){n} body: initiates the request described by its body. The request body is delivered to the application. The request header contains a number of key-value pairs that describe request metadata.
Keys for Treq messages are as follows:
1. traceid: a 24-byte value describing the full Dapper trace id assigned by the client. The value's format is spanid:8 parentid:8 traceid:8.
2. traceflag: a bitmask describing trace flags. Currently, the only defined flag is bit 0 which enables "debug mode", asking the server to force trace sampling.
size:4 Tdispatch:1 tag:3 nctx:2 (ckey~2 cval~2){nc} dst~2 nd:2 (from~2 to~2){nd} body: implements destination dispatch. Tdispatch messages carry a set of keyed request contexts, followed by a logical destination encoded as a UTF-8 string. A delegation table follows describing rewrite rules that apply to this request.
size:4 Rreq:1 tag:3 status:1 body: replies to a request. Status codes are as follows: 0=OK; the body contains the reply. 1=ERROR; the body contains a string describing the error. 2=NACK; a negative acknowledgment, the body contains a string describing the reason.
size:4 Rdispatch:1 tag:3 status:1 nctx:2 (key~2 value~2){nctx} body: replies to a Tdispatch request. Status codes are as in Rreq. Replies can include request contexts. MuxFailure flags are currently sent via Rdispatch contexts under the "MuxFailure" key. See the MuxFailure flags section below.
size:4 Rerr:1 tag:3 why: indicates that the corresponding T message produced an error. Rerr is specifically for server errors: the server failed to interpret or act on the message. The body carries a string describing the error.
size:4 Tdrain:1 tag:3 is a request sent by the server telling the client to stop sending new requests. A client acknowledges this with an Rdrain message.
size:4 Tping:1 tag:3 is sent by either party to check the liveness of its peer; these should be responded to immediately with a Rping message.
size:4 Tdiscarded:1 tag:3 discard_tag:3 why: is a marker message and therefore has a tag value of 0. discard_tag indicates the tag of the Tdispatch to be discarded by the client. This can be used as a hint for early termination. Why is a string describing why the request was discarded. Note that it does *not* free the server from the obligation of replying to the original Treq.
size:4 Tlease:1 tag:3 unit:1 howmuch:8 is a marker message indicating that a lease has been issued for howmuch units. As a marker message, its tag value must be 0. Unit '0' is reserved for duration in milliseconds. Whenever a lease has not been issued, a client can assume it holds an indefinite lease. Adhering to the lease is optional, but the server may reject requests or provide degraded service should the lease expire. This is used by servers to implement features like garbage collection avoidance.
MuxFailure Flags
Failure flags are read and written as an 8 byte integer. Unrecognized flags will be ignored silently, but should all be considered reserved for future use.
Flag Value Meaning Restartable 1 << 0 Request is safe to re-issue Rejected 1 << 1 Request was rejected/Nacked by the server NonRetryable 1 << 2 Request should not be retried
Security
TLS is supported via three mechanisms: - Explicit and exclusive TLS. This pathway involves requiring the establishment of TLS immediately after establishing the socket connection. This is configured by adding TLS configuration to the client or server and not configuring opportunistic TLS or TLS snooping (see below).
- Negotiated Opportunistic TLS. This pathway involves starting the connection as cleartext and the client and server subsequently negotiate a TLS level via the handshake. Based on that handshake the connection is either left as cleartext or upgraded to TLS. This is configured by adding TLS configuration and also configuring an opportunistic TLS level but not configuring TLS snooping.
In this pathway there are three configuration options:
- Off signals that TLS is not supported by this peer
- Desired signals that TLS is preferred but not required by this peer
- Required signals that this peer will only allow the session to continue over TLS
- TLS snooping. This pathway allows a server to use TLS either by performing a TLS handshake immediately after the socket is established or by starting the session as cleartext or using the negotiated pathway described above. If the session is started as a TLS session the headers that drive the opportunistic TLS pathway are ignored.
Note that the server may still require TLS but leaves the option to start TLS immediately after establishing the socket or starting cleartext and requiring TLS via the opportunistic TLS pathway described above.
package mysql
package namer
package naming
package netty4
Package netty4 implements the bottom finagle primitives: com.twitter.finagle.Server and a client transport in terms of the netty4 event loop.
package offload
package param
Defines common com.twitter.finagle.Stack.Param's shared between finagle clients and servers.
package partitioning
package pool
package postgresql
package pushsession
package redis
package scribe
package server
package serverset2
package service
package ssl
package stats
package thrift
Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.
Deprecation
Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.
Thrift codecs
We provide client and server protocol support for the framed protocol. The public implementations are defined on the Thrift object:
- com.twitter.finagle.Thrift.client
- com.twitter.finagle.Thrift.server
The type of the server codec is Service[Array[Byte], Array[Byte]] and the client codecs are Service[ThriftClientRequest, Array[Byte]]. The service provided is that of a "transport" of thrift messages (requests and replies) according to the protocol chosen. This is why the client codecs need to have access to a thrift ProtocolFactory.
These transports are used by the services produced by the finagle thrift codegenerator.
```
val service: Service[ThriftClientRequest, Array[Byte]] = ClientBuilder()
  .hosts("foobar.com:123")
  .stack(Thrift.client)
  .build()

// Wrap the raw Thrift transport in a Client decorator. The client
// provides a convenient procedural interface for accessing the Thrift
// server.
val client = new Hello.ServiceToClient(service, protocolFactory)
```
In this example, Hello is the thrift interface, and the inner class ServiceToClient is provided by the finagle thrift code generator.
package thriftmux
package toggle
package tracing
package transport
package tunable
package util
package zipkin
package zookeeper

Type Members

abstract class AbstractFailureFlags[T <: AbstractFailureFlags[T]] extends Exception with FailureFlags[T]
For Java users wanting to implement exceptions that are FailureFlags.
abstract class AbstractNamer extends Namer
Abstract Namer class for Java compatibility.
abstract class AbstractResolver extends Resolver
An abstract class version of Resolver for java compatibility.
sealed trait Addr extends AnyRef
An address identifies the location of an object--it is a bound name.
An address identifies the location of an object--it is a bound name. An object may be replicated, and thus bound to multiple physical locations (see com.twitter.finagle.Address).
See also
The user guide for further details.
sealed trait Address extends AnyRef
An Address represents the physical location of a single host or endpoint.
An Address represents the physical location of a single host or endpoint. It also includes Addr.Metadata (typically set by Namers and Resolvers) that provides additional configuration to client stacks.
Note that a bound Addr contains a set of Addresses and Addr.Metadata that pertains to the entire set.
trait Announcement extends Closable
trait Announcer extends AnyRef
class AnnouncerForumInvalid extends Exception
Indicates that a forum string passed to an com.twitter.finagle.Announcer was invalid according to the forum grammar [1].
Indicates that a forum string passed to an com.twitter.finagle.Announcer was invalid according to the forum grammar [1].
[1] https://twitter.github.io/finagle/guide/Names.html
class AnnouncerNotFoundException extends Exception
Indicates that an com.twitter.finagle.Announcer was not found for the given scheme.
Indicates that an com.twitter.finagle.Announcer was not found for the given scheme.
Announcers are discovered via Finagle's com.twitter.finagle.util.LoadService mechanism. These exceptions typically suggest that there are no libraries on the classpath that define an Announcer for the given scheme.
class ApiException extends Exception
A base class for exceptions encountered on account of incorrect API usage.
sealed abstract class Backoff extends AnyRef
A recursive ADT to define various backoff strategies, where duration returns the current backoff, and next returns a new Backoff.
A recursive ADT to define various backoff strategies, where duration returns the current backoff, and next returns a new Backoff.
All Backoffs are infinite unless it isExhausted (an empty Backoff), in this case, calling duration will return a NoSuchElementException, calling next will return an UnsupportedOperationException.
Finagle provides the following backoff strategies:
1. BackoffFunction
  - Create backoffs based on a given function, can be created via Backoff.apply.
2. BackoffFromGeneration
  - Create backoffs based on a generation function, can be created via Backoff.fromFunction.
3. Const
  - Return a constant backoff, can be created via Backoff.const.
4. Exponential
  - Create backoffs that grow exponentially, can be created via Backoff.exponential.
5. Linear
  - Create backoffs that grow linearly, can be created via Backoff.linear.
6. DecorrelatedJittered
  - Create backoffs that jitter randomly between a start value and 3 times of that value, can be created via Backoff.decorrelatedJittered.
7. EqualJittered
  - Create backoffs that jitter between 0 and half of the exponential growth. Can be created via Backoff.equalJittered.
8. ExponentialJittered
  - Create backoffs that jitter randomly between 0 and a value that grows exponentially by 2. Can be created via Backoff.exponentialJittered.
Note
A new Backoff will be created only when next is called.
,
None of the Backoffs are memoized, for strategies that involve randomness (DecorrelatedJittered, EqualJittered and ExponentialJittered), there is no way to foresee the next backoff value.
,
All Backoffs are infinite unless using take(Int) to create a strategy with limited number of iterations.
,
You can combine one or more Backoffs with take(Int) and concat(Backoff).
,
If the backoff returned from any Backoffs overflowed, all succeeding backoffs will be Duration.Top.
trait CanStackFrom[-From, To] extends AnyRef
A typeclass for "stackable" items.
A typeclass for "stackable" items. This is used by the StackBuilder to provide a convenient interface for constructing Stacks.
Annotations
@implicitNotFound()
class CancelledConnectionException extends RequestException with HasLogLevel
A Future is satisfied with this exception when the process of establishing a session is interrupted.
A Future is satisfied with this exception when the process of establishing a session is interrupted. Sessions are not preemptively established in Finagle, rather requests are taxed with session establishment when necessary. For example, this exception can occur if a request is interrupted while waiting for an available session or if an interrupt is propagated from a Finagle server during session establishment.
See also
com.twitter.finagle.CancelledRequestException
The user guide for additional details.
class CancelledRequestException extends RequestException with HasLogLevel
Indicates that a request was cancelled.
Indicates that a request was cancelled. Cancellation is propagated between a Finagle server and a client intra-process when the server is interrupted by an upstream service. In such cases, the pending Future is interrupted with this exception. The client will cancel its pending request which will by default propagate an interrupt to its downstream, and so on. This is done to conserve resources.
See also
The user guide for additional details.
class ChannelBufferUsageException extends Exception
Indicates that an error occurred on account of incorrect usage of a io.netty.buffer.ByteBuf.
Indicates that an error occurred on account of incorrect usage of a io.netty.buffer.ByteBuf.
TODO: Probably remove this exception class once we migrate away from Netty usage in public APIs.
class ChannelClosedException extends ChannelException with FailureFlags[ChannelClosedException]
Indicates that a given channel was closed, for instance if the connection was reset by a peer or a proxy.
class ChannelException extends Exception with SourcedException with HasLogLevel
An exception encountered within the context of a given socket channel.
case class ChannelWriteException(ex: Option[Throwable]) extends ChannelException with WriteException with NoStackTrace with Product with Serializable
Default implementation for WriteException that wraps an underlying exception.
trait Client[Req, Rep] extends AnyRef
RPC clients with Req-typed requests and Rep typed replies.
RPC clients with Req-typed requests and Rep typed replies. RPC destinations are represented by names. Names are bound for each request.
Clients are implemented by the various protocol packages in finagle, for example com.twitter.finagle.Http:
```
object Http extends Client[HttpRequest, HttpResponse] ...

val service: Service[HttpRequest, HttpResponse] =
  Http.newService("google.com:80")
```
trait ClientConnection extends Closable
Information about a client, passed to a ServiceFactory for each new connection.
Information about a client, passed to a ServiceFactory for each new connection.
Note
this is represented by ClientConnection.nil on the client side when it initiates a new connection.
abstract class ClientParamsInjector extends ParamsInjector
ClientsParamsInjector is the standard mechanism for injecting params into the client.
ClientsParamsInjector is the standard mechanism for injecting params into the client. It is a Stack.ParamsInjector with a name. The injection will run at materialization time for Finagle clients, so that the parameters for a Stack will be injected in a consistent way.
abstract class ClientStackTransformer extends Transformer
ClientStackTransformer is a standard mechanism for transforming the default shape of the Stack.
ClientStackTransformer is a standard mechanism for transforming the default shape of the Stack. It is a Stack.Transformer with a name. Registration and retrieval of transformers from global state is managed by StackClient.DefaultTransformer. The transformers will run at materialization time for Finagle clients, allowing users to mutate a Stack in a consistent way.
Warning: While it's possible to modify params with this API, it's strongly discouraged. Modifying params via transformers creates subtle dependencies between modules and makes it difficult to reason about the value of params, as it may change depending on the module's placement in the stack. Whenever possible, ClientParamsInjector should be used instead.
class ConnectionFailedException extends ChannelException
Indicates that the client failed to establish a connection.
Indicates that the client failed to establish a connection. Typically this class will be extended to provide additional information relevant to a particular category of connection failure.
case class ConnectionRefusedException(remoteAddr: Option[SocketAddress]) extends ChannelException with Product with Serializable
Indicates that connecting to a given remoteAddress was refused.
case class Dentry(prefix: Prefix, dst: NameTree[Path]) extends Product with Serializable
Trait Dentry describes a delegation table entry.
Trait Dentry describes a delegation table entry. prefix describes the paths that the entry applies to. dst describes the resulting tree for this prefix on lookup.
class DroppedWriteException extends TransportException
Indicates that a com.twitter.finagle.transport.Transport write associated with the request was dropped by the transport (usually to respect backpressure).
case class Dtab(dentries0: IndexedSeq[Dentry]) extends DtabBase with Product with Serializable
A Dtab--short for delegation table--comprises a sequence of delegation rules.
A Dtab--short for delegation table--comprises a sequence of delegation rules. Together, these describe how to bind a com.twitter.finagle.Path to a set of com.twitter.finagle.Addr. com.twitter.finagle.naming.DefaultInterpreter implements the default binding strategy.
See also
The user guide for further details.
final class DtabBuilder extends ReusableBuilder[Dentry, Dtab]
trait DtabFlags extends AnyRef
Defines a com.twitter.app.Flag for specifying a supplemental com.twitter.finagle.Dtab to append to the com.twitter.finagle.Dtab.base delegation table.
class FactoryToService[Req, Rep] extends Service[Req, Rep]
Turns a com.twitter.finagle.ServiceFactory into a com.twitter.finagle.Service which acquires a new service for each request.
class FailedFastException extends RequestException with WriteException with HasLogLevel with FailureFlags[FailedFastException]
Used by com.twitter.finagle.service.FailFastFactory to indicate that a request failed because all hosts in the cluster to which the client is connected have been marked as failed.
Used by com.twitter.finagle.service.FailFastFactory to indicate that a request failed because all hosts in the cluster to which the client is connected have been marked as failed. See com.twitter.finagle.service.FailFastFactory for details on this behavior.
See also
The user guide for additional details.
final class Failure extends Exception with NoStackTrace with HasLogLevel with FailureFlags[Failure]
Base exception for all Finagle originated failures.
Base exception for all Finagle originated failures. These are Exceptions, but with additional sources and flags. Sources describe the origins of the failure to aid in debugging and flags mark attributes of the Failure (e.g. Restartable).
trait FailureFlags[T <: FailureFlags[T]] extends Exception
Carries metadata for exceptions such as whether or not the exception is safe to retry.
Carries metadata for exceptions such as whether or not the exception is safe to retry.
The boolean properties can be tested via the FailureFlags.isFlagged(Long) method where the values for the flags are a bitmask from the constants defined on the companion object. Common flags are Rejected and NonRetryable.
See also
AbstractFailureFlags for creating subclasses in Java.
abstract class Filter[-ReqIn, +RepOut, +ReqOut, -RepIn] extends (ReqIn, Service[ReqOut, RepIn]) => Future[RepOut]
A Filter acts as a decorator/transformer of a service.
A Filter acts as a decorator/transformer of a service. It may apply transformations to the input and output of that service:
```
          (*  MyService  *)
[ReqIn -> (ReqOut -> RepIn) -> RepOut]
```
For example, you may have a service that takes Strings and parses them as Ints. If you want to expose this as a Network Service via Thrift, it is nice to isolate the protocol handling from the business rules. Hence you might have a Filter that converts back and forth between Thrift structs. Again, your service deals with plain objects:
```
[ThriftIn -> (String  ->  Int) -> ThriftOut]
```
Thus, a Filter[A, B, C, D] converts a Service[C, D] to a Service[A, B]. In other words, it converts a Service[ReqOut, RepIn] to a Service[ReqIn, RepOut].
See also
The user guide for details and examples.
trait FinagleInit extends () => Unit
Initialization code to run before Finagle bootstraps any resources (such as its scheduler).
Initialization code to run before Finagle bootstraps any resources (such as its scheduler). The only guarantees are that all FinagleInit modules run exactly once and they run before any Finagle clients or servers within the process connect to a remote peer or accept connections, respectively.
Note
There are *no* relative ordering guarantees if multiple FinagleInit or MetricsInit instances are registered.
class GlobalRequestTimeoutException extends RequestTimeoutException
Indicates that a request timed out, where "request" comprises a full RPC from the perspective of the application.
Indicates that a request timed out, where "request" comprises a full RPC from the perspective of the application. For instance, multiple retried Finagle-level requests could constitute the single request that this exception pertains to.
trait HasRemoteInfo extends Exception
A trait for exceptions that contain remote information: the downstream address/client id, upstream address/client id (if applicable), and trace id of the request.
A trait for exceptions that contain remote information: the downstream address/client id, upstream address/client id (if applicable), and trace id of the request. RemoteInfo.NotAvailable is used if no remote information has been set.
trait HttpRichClient extends AnyRef
A rich HTTP/1.1 client with a *very* basic URL fetcher.
A rich HTTP/1.1 client with a *very* basic URL fetcher. (It does not handle redirects, does not have a cookie jar, etc.)
class InconsistentStateException extends ChannelException
Indicates that some client state was inconsistent with the observed state of some server.
Indicates that some client state was inconsistent with the observed state of some server. For example, the client could receive a channel-connection event from a proxy when there is no outstanding connect request.
class IndividualRequestTimeoutException extends RequestTimeoutException
Indicates that a single Finagle-level request timed out.
Indicates that a single Finagle-level request timed out. In contrast to com.twitter.finagle.RequestTimeoutException, an "individual request" could be a single request-retry performed as a constituent of an application-level RPC.
final class JavaFailureFlags extends AnyRef
Java compatibility for the FailureFlags companion object.
trait ListeningServer extends ClosableOnce with Awaitable[Unit]
Trait ListeningServer represents a bound and listening server.
Trait ListeningServer represents a bound and listening server. Closing a server instance unbinds the port and relinquishes resources that are associated with the server.
trait MemcachedRichClient extends AnyRef
Factory methods to build a finagle-memcached client.
class MultipleAnnouncersPerSchemeException extends Exception with NoStackTrace
Indicates that multiple Announcers were discovered for given scheme.
Indicates that multiple Announcers were discovered for given scheme.
Announcers are discovered via Finagle's com.twitter.finagle.util.LoadService mechanism. These exceptions typically suggest that there are multiple libraries on the classpath with conflicting scheme definitions.
class MultipleResolversPerSchemeException extends Exception with NoStackTrace
Indicates that multiple Resolvers were discovered for given scheme.
Indicates that multiple Resolvers were discovered for given scheme.
Resolvers are discovered via Finagle's com.twitter.finagle.util.LoadService mechanism. These exceptions typically suggest that there are multiple libraries on the classpath with conflicting scheme definitions.
trait MysqlRichClient extends AnyRef
Supplements a com.twitter.finagle.Client with convenient builder methods for constructing a mysql client.
sealed trait Name extends AnyRef
Names identify network locations.
Names identify network locations. They come in two varieties:
1. Bound names are concrete. They represent a changeable list of network endpoints (represented by Addrs).
2. Path names are unbound paths, representing an abstract location which must be resolved by some context, usually the Dtab.
In practice, clients use a com.twitter.finagle.Resolver to resolve a destination name string into a Name. This is achieved by passing a destination name into methods such as ClientBuilder.dest or the newClient method of the appropriate protocol object (e.g. Http.newClient(/s/org/servicename)). These APIs use Resolver under the hood to resolve the destination names into the Name representation of the appropriate cluster.
As names are bound, a Namer may elect to bind only a Name prefix, leaving an unbound residual name to be processed by a downstream Namer.
See also
The user guide for further details.
sealed trait NameTree[+T] extends AnyRef
Name trees represent a composite T-typed name whose interpretation is subject to evaluation rules.
Name trees represent a composite T-typed name whose interpretation is subject to evaluation rules. Typically, a Namer is used to provide evaluation context for these trees.
- com.twitter.finagle.NameTree.Union nodes represent the union of several trees; a destination is reached by load-balancing over the sub-trees.
- Alt nodes represent a fail-over relationship between several trees; the first successful tree is picked as the destination. When the tree-list is empty, Alt-nodes evaluate to Empty.
- A Leaf represents a T-typed leaf node;
- A Neg represents a negative location; no destination exists here.
- Finally, Empty trees represent an empty location: it exists but is uninhabited at this time.
abstract class Namer extends AnyRef
A namer is a context in which a NameTree is bound.
A namer is a context in which a NameTree is bound. The context is provided by the lookup method, which translates Paths into NameTrees. Namers may represent external processes, for example lookups through DNS or to ZooKeeper, and thus lookup results are represented by a Activity.
class NoBrokersAvailableException extends RequestException with SourcedException
Indicates that a request failed because no servers were available.
Indicates that a request failed because no servers were available. The Finagle client's internal load balancer was empty. This typically occurs under one of the following conditions:
- The cluster is actually down. No servers are available. - A service discovery failure. This can be due to a number of causes, such as the client being constructed with an invalid cluster destination name [1] or a failure in the service discovery system (e.g. DNS, ZooKeeper).
A good way to diagnose NoBrokersAvailableExceptions is to reach out to the owners of the service to which the client is attempting to connect and verify that the service is operational. If so, then investigate the service discovery mechanism that the client is using (e.g. the com.twitter.finagle.Resolver that is it configured to use and the system backing it).
[1] https://twitter.github.io/finagle/guide/Names.html
class NotServableException extends RequestException
Indicates that the request was not servable, according to some policy.
Indicates that the request was not servable, according to some policy. See com.twitter.finagle.service.OptionallyServableFilter as an example.
case class Path(elems: Buf*) extends Product with Serializable
A Path comprises a sequence of byte buffers naming a hierarchically-addressed object.
A Path comprises a sequence of byte buffers naming a hierarchically-addressed object.
See also
The user guide for further details.
trait ProxyAnnouncement extends Announcement with Proxy
class ProxyConnectException extends Exception with NoStackTrace with FailureFlags[ProxyConnectException]
Indicates that either SOCKS or HTTP(S) proxy server rejected client's connect request.
class ReadTimedOutException extends ChannelException
Indicates that a read from a given remoteAddress timed out.
trait RedisRichClient extends AnyRef
case class RefusedByRateLimiter() extends ChannelException with Product with Serializable
Indicates that requests were failed by a rate-limiter.
Indicates that requests were failed by a rate-limiter. See com.twitter.finagle.service.RateLimitingFilter for details.
class RequestException extends Exception with NoStackTrace with SourcedException
A base class for request failures.
A base class for request failures. Indicates that some failure occurred before a request could be successfully serviced.
class RequestTimeoutException extends RequestException with TimeoutException
Indicates that a request timed out.
Indicates that a request timed out. See com.twitter.finagle.IndividualRequestTimeoutException and com.twitter.finagle.GlobalRequestTimeoutException for details on the different request granularities that this exception class can pertain to.
trait Resolver extends AnyRef
A resolver binds a name, represented by a string, to a variable address.
A resolver binds a name, represented by a string, to a variable address. Resolvers have an associated scheme which is used for lookup so that names may be resolved in a global context.
These are loaded by Finagle through the service loading mechanism. Thus, in order to implement a new resolver, a class implementing Resolver with a 0-arg constructor must be registered in a file named META-INF/services/com.twitter.finagle.Resolver included in the classpath; see Oracle's ServiceLoader documentation for further details.
class ResolverAddressInvalid extends Exception
Indicates that a destination name string passed to a com.twitter.finagle.Resolver was invalid according to the destination name grammar [1].
Indicates that a destination name string passed to a com.twitter.finagle.Resolver was invalid according to the destination name grammar [1].
[1] https://twitter.github.io/finagle/guide/Names.html
class ResolverNotFoundException extends Exception
Indicates that a com.twitter.finagle.Resolver was not found for the given scheme.
Indicates that a com.twitter.finagle.Resolver was not found for the given scheme.
Resolvers are discovered via Finagle's com.twitter.finagle.util.LoadService mechanism. These exceptions typically suggest that there are no libraries on the classpath that define a Resolver for the given scheme.
trait Server[Req, Rep] extends AnyRef
Servers implement RPC servers with Req-typed requests and Rep-typed responses.
Servers implement RPC servers with Req-typed requests and Rep-typed responses. Servers dispatch requests to a com.twitter.finagle.Service or com.twitter.finagle.ServiceFactory provided through serve.
Servers are implemented by the various protocol packages in finagle, for example com.twitter.finagle.Http:
```
object Http extends Server[HttpRequest, HttpResponse] ...

val server = Http.serve(":*", new Service[HttpRequest, HttpResponse] {
  def apply(req: HttpRequest): Future[HttpResponse] = ...
})
```
Will bind to an ephemeral port (":*") and dispatch request to server.boundAddress to the provided com.twitter.finagle.Service instance.
The serve method has two variants: one for instances of Service, and another for ServiceFactory. The ServiceFactory variants are used for protocols in which connection state is significant: a new Service is requested from the ServiceFactory for each new connection, and requests on that connection are dispatched to the supplied service. The service is also closed when the client disconnects or the connection is otherwise terminated.
case class ServerErrorMonitor(suppressedCodes: Seq[Short]) extends Monitor with Product with Serializable
ServerErrorMonitor is a com.twitter.util.Monitor that specifically handles mysql ServerErrors in a less verbose way then com.twitter.finagle.util.DefaultMonitor.
ServerErrorMonitor is a com.twitter.util.Monitor that specifically handles mysql ServerErrors in a less verbose way then com.twitter.finagle.util.DefaultMonitor.
By default it will log an info statement with details about the ServerError and encourage end users to explicitly handle or rescue the ServerError in application code, and then suppress the logging.
Specific error codes can be suppressed, with the intention being that this happens when application code is explicitly dealing with that ServerError variant.
Example:
1. val client = Mysql.client .withMonitor(ServerErrorMonitor(Seq(<code>)))
abstract class ServerParamsInjector extends ParamsInjector
ServerParamsInjector is the standard mechanism for injecting params into the server.
ServerParamsInjector is the standard mechanism for injecting params into the server. It is a Stack.ParamsInjector with a name. The injection will run at materialization time for Finagle servers, so that the parameters for a Stack will be injected in a consistent way.
abstract class ServerStackTransformer extends Transformer
ServerStackTransformer is a standard mechanism for transforming the default shape of the Stack.
ServerStackTransformer is a standard mechanism for transforming the default shape of the Stack. It is a Stack.Transformer with a name. Registration and retrieval of transformers from global state is managed by StackServer.DefaultTransformer. The transformers will run at materialization time for Finagle servers, allowing users to mutate a Stack in a consistent way.
Warning: While it's possible to modify params with this API, it's strongly discouraged. Modifying params via transformers creates subtle dependencies between modules and makes it difficult to reason about the value of params, as it may change depending on the module's placement in the stack. Whenever possible, ServerParamsInjector should be used instead.
abstract class Service[-Req, +Rep] extends (Req) => Future[Rep] with Closable
A Service is an asynchronous function from a Request to a Future[Response].
A Service is an asynchronous function from a Request to a Future[Response].
It is the basic unit of an RPC interface.
See also
The user guide for details and examples.
Service.mk for a convenient way to create new instances.
class ServiceClosedException extends Exception with ServiceException with FailureFlags[ServiceClosedException]
Indicates that a request was applied to a com.twitter.finagle.Service that is closed (i.e.
Indicates that a request was applied to a com.twitter.finagle.Service that is closed (i.e. the connection is closed).
trait ServiceException extends Exception with SourcedException
A trait for exceptions related to a com.twitter.finagle.Service.
abstract class ServiceFactory[-Req, +Rep] extends (ClientConnection) => Future[Service[Req, Rep]] with Closable
abstract class ServiceFactoryProxy[-Req, +Rep] extends ServiceFactory[Req, Rep]
A ServiceFactory that proxies all calls to another ServiceFactory.
A ServiceFactory that proxies all calls to another ServiceFactory. This can be useful if you want to modify an existing ServiceFactory.
trait ServiceFactoryWrapper extends AnyRef
A ServiceFactoryWrapper adds behavior to an underlying ServiceFactory.
trait ServiceNamer[Req, Rep] extends Namer
Base-trait for Namers that bind to a local Service.
Base-trait for Namers that bind to a local Service.
Implementers with a 0-argument constructor may be named and auto-loaded with /$/pkg.cls syntax.
Note that this can't actually be accomplished in a type-safe manner since the naming step obscures the service's type to observers.
class ServiceNotAvailableException extends Exception with ServiceException
Indicates that a request was applied to a com.twitter.finagle.Service that is unavailable.
Indicates that a request was applied to a com.twitter.finagle.Service that is unavailable. This constitutes a fail-stop condition.
abstract class ServiceProxy[-Req, +Rep] extends Service[Req, Rep] with Proxy
A simple proxy Service that forwards all calls to another Service.
A simple proxy Service that forwards all calls to another Service. This is useful if you want to wrap-but-modify an existing service.
class ServiceReturnedToPoolException extends IllegalStateException with ServiceException with HasLogLevel with FailureFlags[ServiceReturnedToPoolException]
Indicates that this service was closed and returned to the underlying pool.
class ServiceTimeoutException extends Exception with WriteException with ServiceException with TimeoutException with NoStackTrace
Indicates that the connection was not established within the timeouts.
Indicates that the connection was not established within the timeouts. This type of exception should generally be safe to retry.
class ShardNotAvailableException extends NotServableException
Indicates that the shard to which a request was assigned was not available.
Indicates that the shard to which a request was assigned was not available. See com.twitter.finagle.partitioning.PartitioningService for details on this behavior.
abstract class SimpleFilter[Req, Rep] extends Filter[Req, Rep, Req, Rep]
A Filter where the request and reply types are the same.
trait SourcedException extends Exception with HasRemoteInfo
A trait for exceptions that have a source.
A trait for exceptions that have a source. The name of the source is specified as a serviceName. The "unspecified" value is used if no serviceName is provided by the implementation.
class SslException extends ChannelException
Indicates that an SSL/TLS exception occurred.
case class SslVerificationFailedException(ex: Option[Throwable], remoteAddr: Option[SocketAddress]) extends SslException with Product with Serializable
Indicates that an error occurred while SslClientSessionVerification was being performed, or the server disconnected from the client in a way that indicates that there was high probability that the server failed to verify the client's certificate.
sealed trait Stack[T] extends AnyRef
Stacks represent stackable elements of type T.
Stacks represent stackable elements of type T. It is assumed that T-typed elements can be stacked in some meaningful way; examples are functions (function composition) Filters (chaining), and ServiceFactories (through transformers). T-typed values are also meant to compose: the stack itself materializes into a T-typed value.
Stacks are persistent, allowing for nondestructive transformations; they are designed to represent 'template' stacks which can be configured in various ways before materializing the stack itself.
Note: Stacks are advanced and sometimes subtle. For expert use only!
class StackBuilder[T] extends AnyRef
StackBuilders are imperative-style builders for Stacks.
StackBuilders are imperative-style builders for Stacks. It maintains a stack onto which new elements can be pushed (defining a new stack).
See also
stack.nilStack for starting construction of an empty stack for ServiceFactorys.
trait Stackable[T] extends Head
Produce a stack from a T-typed element.
final class Stacks extends AnyRef
A Java adaptation of the com.twitter.finagle.Stack companion object.
sealed trait Status extends AnyRef
Status tells the condition of a networked endpoint.
Status tells the condition of a networked endpoint. They are used to indicate the health of Service, ServiceFactory, and of transport.Transport.
Object Status$ contains the status definitions.
abstract class StreamClosedException extends ChannelException with FailureFlags[StreamClosedException] with NoStackTrace
Indicates that a given stream was closed, for instance if the stream was reset by a peer or a proxy.
trait TimeoutException extends Exception with SourcedException with HasLogLevel
Indicates that an operation exceeded some timeout duration before completing.
Indicates that an operation exceeded some timeout duration before completing. Differs from com.twitter.util.TimeoutException in that this trait doesn't extend java.util.concurrent.TimeoutException, provides more context in its error message (e.g. the source and timeout value), and is only used within the confines of Finagle.
class TooManyConcurrentRequestsException extends ApiException
Indicates that the client has issued more concurrent requests than are allowable, where "allowable" is typically determined based on some configurable maximum.
class TooManyWaitersException extends RequestException with HasLogLevel
Used by com.twitter.finagle.pool.WatermarkPool to indicate that a request failed because too many requests are already waiting for a connection to become available from a client's connection pool.
class TransportException extends Exception with SourcedException
A base class for exceptions encountered in the context of a com.twitter.finagle.transport.Transport.
case class UnknownChannelException(ex: Option[Throwable], remoteAddr: Option[SocketAddress]) extends ChannelException with Product with Serializable
A catch-all exception class for uncategorized ChannelExceptions.
trait WriteException extends Exception with SourcedException
Marker trait to indicate there was an exception before writing any of the request.
Marker trait to indicate there was an exception before writing any of the request. These exceptions should generally be retryable.
See also
com.twitter.finagle.service.RetryPolicy.RetryableWriteException
com.twitter.finagle.service.RetryPolicy.WriteExceptionsOnly
class WriteTimedOutException extends ChannelException
Indicates that a write to a given remoteAddress timed out.

Value Members

object Addr
Note: There is a Java-friendly API for this object: com.twitter.finagle.Addrs.
object Address
object Addresses
A Java adaptation of the com.twitter.finagle.Address companion object.
object Addrs
A Java adaptation of the com.twitter.finagle.Addr companion object.
object Announcer
object Backoff
object CanStackFrom
object ChannelException extends Serializable
object ChannelWriteException extends Serializable
object ClientConnection
object Dentry extends Serializable
object Dtab extends DtabCompanionBase with Serializable
object FactoryToService
object FailResolver extends Resolver
object Failure extends Serializable
object FailureFlags extends Serializable
FailureFlags may be applied to any Failure/Exception encountered during the handling of a request.
FailureFlags may be applied to any Failure/Exception encountered during the handling of a request.
See also
JavaFailureFlags for Java compatibility.
object Filter
object FixedInetResolver
InetResolver that caches all successful DNS lookups indefinitely and does not poll for updates.
InetResolver that caches all successful DNS lookups indefinitely and does not poll for updates.
Clients should only use this in scenarios where host -> IP map changes do not occur.
object Http extends Client[Request, Response] with HttpRichClient with Server[Request, Response]
HTTP/1.1 protocol support, including client and server.
object InetResolver
Resolver for inet scheme.

object Memcached extends Client[Command, Response] with Server[Command, Response]

Stack based Memcached client.

For example, a default client can be built through:

Examples:

```
val client = Memcached.newRichClient(dest)
```
If you want to provide more finely tuned configurations:

val client =
  Memcached.client
    .withEjectFailedHost(true)
    .withTransport.connectTimeout(100.milliseconds))
    .withRequestTimeout(10.seconds)
    .withSession.acquisitionTimeout(20.seconds)
    .newRichClient(dest, "memcached_client")

object Mux extends Client[Request, Response] with Server[Request, Response]
A client and server for the mux protocol described in com.twitter.finagle.mux.

object Mysql extends Client[Request, Result] with MysqlRichClient

Example:

val client = Mysql.client
  .withCredentials("<username>", "<password>")
  .withDatabase("<db>")
  .newRichClient("inet!localhost:3306")

object Name
See Names for Java compatibility APIs.
object NameTree
The NameTree object comprises NameTree types as well as binding and evaluation routines.
object Namer
object Names
Java compatibility APIs for Name.
object NegResolver extends Resolver
object NilResolver extends Resolver
object NullServer extends ListeningServer
An empty ListeningServer that can be used as a placeholder.
An empty ListeningServer that can be used as a placeholder. For example:
```
@volatile var server = NullServer
def main() { server = Http.serve(...) }
def exit() { server.close() }
```
object Path extends Serializable
object PostgreSql
object Redis extends Client[Command, Reply] with RedisRichClient
object Resolver extends BaseResolver
The default Resolver used by Finagle.
The default Resolver used by Finagle.
See also
Resolvers for Java support.
object Resolvers
Java APIs for Resolver.
object Service
object ServiceFactory
object ServiceFactoryWrapper
object SourcedException extends Serializable
object Stack
See also
stack.nilStack for starting construction of an empty stack for ServiceFactorys.
object StackParams
Stack.Params forwarder to provide a clean Java API.
object Status
Define valid Status! values.
Define valid Status! values. They are, in order from most to least healthy:
- Open
- Busy
- Closed
(An scala.math.Ordering is defined in these terms.)
object Thrift extends Client[ThriftClientRequest, Array[Byte]] with Server[Array[Byte], Array[Byte]]
Client and server for Apache Thrift.
Client and server for Apache Thrift. Thrift implements Thrift framed transport and binary protocol by default, though custom protocol factories (i.e. wire encoding) may be injected with withProtocolFactory. The client, Client[ThriftClientRequest, Array[Byte]] provides direct access to the thrift transport, but we recommend using code generation through either Scrooge or a fork of the Apache generator. A rich API is provided to support interfaces generated with either of these code generators.
The client and server uses the standard thrift protocols, with support for both framed and buffered transports. Finagle attempts to upgrade the protocol in order to ship an extra envelope carrying additional request metadata, containing, among other things, request IDs for Finagle's RPC tracing facilities.
The negotiation is simple: on connection establishment, an improbably-named method is dispatched on the server. If that method isn't found, we are dealing with a legacy thrift server, and the standard protocol is used. If the remote server is also a finagle server (or any other supporting this extension), we reply to the request, and every subsequent request is dispatched with an envelope carrying trace metadata. The envelope itself is also a Thrift struct described here.
Clients
Clients can be created directly from an interface generated from a Thrift IDL:
For example, this IDL:
```
service TestService {
  string query(1: string x)
}
```
compiled with Scrooge, generates the interface TestService.MethodPerEndpoint. This is then passed into Thrift.Client.build:
```
Thrift.client.build[TestService.MethodPerEndpoint](
  addr, classOf[TestService.MethodPerEndpoint])
```
However note that the Scala compiler can insert the latter Class for us, for which another variant of build is provided:
```
Thrift.client.build[TestService.MethodPerEndpoint](addr)
```
In Java, we need to provide the class object:
```
TestService.MethodPerEndpoint client =
  Thrift.client.build(addr, TestService.MethodPerEndpoint.class);
```
The client uses the standard thrift protocols, with support for both framed and buffered transports. Finagle attempts to upgrade the protocol in order to ship an extra envelope carrying trace IDs and client IDs associated with the request. These are used by Finagle's tracing facilities and may be collected via aggregators like Zipkin.
The negotiation is simple: on connection establishment, an improbably-named method is dispatched on the server. If that method isn't found, we are dealing with a legacy thrift server, and the standard protocol is used. If the remote server is also a finagle server (or any other supporting this extension), we reply to the request, and every subsequent request is dispatched with an envelope carrying trace metadata. The envelope itself is also a Thrift struct described here.
Servers
TestService.MethodPerEndpoint must be implemented and passed into serveIface:
```
// An echo service
ThriftMux.server.serveIface(":*", new TestService.MethodPerEndpoint {
  def query(x: String): Future[String] = Future.value(x)
})
```
object ThriftMux extends Client[ThriftClientRequest, Array[Byte]] with Server[Array[Byte], Array[Byte]]
The ThriftMux object is both a com.twitter.finagle.Client and a com.twitter.finagle.Server for the Thrift protocol served over com.twitter.finagle.mux.
The ThriftMux object is both a com.twitter.finagle.Client and a com.twitter.finagle.Server for the Thrift protocol served over com.twitter.finagle.mux. Rich interfaces are provided to adhere to those generated from a Thrift IDL by Scrooge or thrift-finagle.
Clients
Clients can be created directly from an interface generated from a Thrift IDL:
For example, this IDL:
```
service TestService {
  string query(1: string x)
}
```
compiled with Scrooge, generates the interface TestService.MethodPerEndpoint. This is then passed into ThriftMux.Client.build:
```
ThriftMux.client.build[TestService.MethodPerEndpoint](
  addr, classOf[TestService.MethodPerEndpoint])
```
However note that the Scala compiler can insert the latter Class for us, for which another variant of build is provided:
```
ThriftMux.client.build[TestService.MethodPerEndpoint](addr)
```
In Java, we need to provide the class object:
```
TestService.MethodPerEndpoint client =
  ThriftMux.client.build(addr, TestService.MethodPerEndpoint.class);
```
Servers
Servers are also simple to expose:
TestService.MethodPerEndpoint must be implemented and passed into serveIface:
```
// An echo service
ThriftMux.server.serveIface(":*", new TestService.MethodPerEndpoint {
  def query(x: String): Future[String] = Future.value(x)
})
```
This object does not expose any configuration options. Both clients and servers are instantiated with sane defaults. Clients are labeled with the "clnt/thrift" prefix and servers with "srv/thrift". If you'd like more configuration, see the configuration documentation.
object WriteException extends Serializable
object stack

Packages

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

finagle

package finagle

Package Members

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

Type Members

Value Members

Clients

Servers

Clients

Servers

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

finagle

package finagle

Package Members

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

Type Members

Value Members

Clients

Servers

Clients

Servers

Inherited from AnyRef

Inherited from Any

Ungrouped

finagle