Packages

package root

Definition Classes: root

package com

Definition Classes: root

package twitter

Start with com.twitter.finagle.

Definition Classes: com

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.

Definition Classes: twitter

package addr

Definition Classes: finagle

package builder

Definition Classes: finagle

package client

Definition Classes: finagle

package context

Definition Classes: finagle

package core

Definition Classes: finagle

package dispatch

Definition Classes: finagle

package exp

Package exp contains experimental code.

Package exp contains experimental code. This can be removed or stabilized (moved elsewhere) at any time.

Definition Classes: finagle

package factory

Definition Classes: finagle

package filter

Definition Classes: finagle

package http

Definition Classes: finagle

package http2

Definition Classes: finagle

package liveness

Definition Classes: finagle

package loadbalancer

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

Definition Classes: finagle

package logging

Definition Classes: finagle

package memcached

Definition Classes: finagle

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:

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.

Definition Classes: finagle

package mysql

Definition Classes: finagle

package namer

Definition Classes: finagle

package naming

Definition Classes: finagle

package netty4

Package netty4 implements the bottom finagle primitives: com.twitter.finagle.Server and a client transport in terms of the netty4 event loop.

Definition Classes: finagle

package offload

Definition Classes: finagle

package param

Defines common com.twitter.finagle.Stack.Param's shared between finagle clients and servers.

Definition Classes: finagle

package partitioning

Definition Classes: finagle

package pool

Definition Classes: finagle

package postgresql

Definition Classes: finagle

package pushsession

Definition Classes: finagle

package redis

Definition Classes: finagle

package scribe

Definition Classes: finagle

package server

Definition Classes: finagle

package serverset2

Definition Classes: finagle

package service

Definition Classes: finagle

LocalRateLimitingStrategy

NilService

OptionallyServableFilter

ResponseClassificationSyntheticException

RetryExceptionsFilter

package ssl

Definition Classes: finagle

package stats

Definition Classes: finagle

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:

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.

Definition Classes: finagle

package thriftmux

Definition Classes: finagle

package toggle

Definition Classes: finagle

package tracing

Definition Classes: finagle

package transport

Definition Classes: finagle

package tunable

Definition Classes: finagle

package util

Definition Classes: finagle

package zipkin

Definition Classes: finagle

package zookeeper

Definition Classes: finagle

com.twitter.finagle

service

package service

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

service
AnyRef
Any

Hide All
Show All

Visibility

Public
Protected

Type Members

class ConstantService[Req, Rep] extends Service[Req, Rep]
A com.twitter.finagle.Service that returns a constant result.
class DeadlineFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A com.twitter.finagle.Filter that rejects requests when their deadline has passed.
A com.twitter.finagle.Filter that rejects requests when their deadline has passed.
See also
The user guide for more details.
class DelayedFactory[Req, Rep] extends ServiceFactory[Req, Rep]
A factory that won't satisfy the service future until an underlying service factory is ready.
A factory that won't satisfy the service future until an underlying service factory is ready.
close closes the underlying service factory, which means that it won't be satisfied until after the underlying future has been satisfied.
Note
Implicitly masks the underlying future from interrupts. Promises are detached on interruption.
abstract class ExpiringService[Req, Rep] extends ServiceProxy[Req, Rep]
A service wrapper that expires the self service after a certain amount of idle time.
A service wrapper that expires the self service after a certain amount of idle time. By default, expiring calls close() on the self channel, but this action is customizable.
See also
The user guide for more details.
class FailedService extends ConstantService[Any, Nothing]
A com.twitter.finagle.Service that fails with a constant Throwable.
class FailingFactory[Req, Rep] extends ServiceFactory[Req, Rep]
A com.twitter.finagle.ServiceFactory that fails to construct services.
trait Filterable[+T] extends AnyRef
Allows filtering of a ServicePerEndpoint when constructing new ServicePerEndpoint through MethodBuilder
class LocalRateLimitingStrategy[Req] extends (Req) => Future[Boolean]
Strategy responsible for tracking requests and computing rate per client.
class OptionallyServableFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A com.twitter.finagle.Filter that uses an argument function to predicate whether or not to apply the subsequent com.twitter.finagle.Service.
A com.twitter.finagle.Filter that uses an argument function to predicate whether or not to apply the subsequent com.twitter.finagle.Service. In cases where the function returns false, a the filter fails with a com.twitter.finagle.NotServableException.
class RateLimitingFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A com.twitter.finagle.Filter that accepts or refuses requests based on a rate limiting strategy.
sealed trait ReqRep extends AnyRef
case class ReqRepT[Req, Rep](request: Req, response: Try[Rep]) extends ReqRep with Product with Serializable
A type-safe request/response pair.
A type-safe request/response pair.
See also
ReqRep for untyped
sealed abstract class ResponseClass extends AnyRef
A classification of the result of a request/response pair.
A classification of the result of a request/response pair.
See also
ResponseClassifier
final class ResponseClasses extends AnyRef
Java APIs for ResponseClass.
class ResponseClassificationSyntheticException extends Exception with NoStackTrace
Used by response classification to indicate synthetic failures that are not Exceptions.
Used by response classification to indicate synthetic failures that are not Exceptions.
See also
com.twitter.finagle.service.StatsFilter
The FAQ for more details.
type ResponseClassifier = PartialFunction[ReqRep, ResponseClass]
A response classifier allows developers to give Finagle the additional application specific knowledge necessary in order to properly classify them.
A response classifier allows developers to give Finagle the additional application specific knowledge necessary in order to properly classify them. Without this, Finagle can only safely make judgements about transport level failures.
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 from a request/response pair to a ResponseClass and as such multiple classifiers can be composed together via PartialFunction.orElse.
Note
Java does not understand the type alias and must be used as PartialFunction in Java. Constructing a custom ResponseClassifier in Java is achievable by implementing AbstractPartialFunction, see com.twitter.finagle.service.ResponseClassifierCompilationTest#testCustomResponseClassifier() for examples.
,
Finagle's default classifier is com.twitter.finagle.service.ResponseClassifier.Default which is a total function fully covering the input domain.
,
it is a good practice for users of ResponseClassifier.apply to instead use theClassifier.applyOrElse(input, ResponseClassifier.Default) in order to ensure that the PartialFunction will be fully covering.
See also
com.twitter.finagle.http.service.HttpResponseClassifier for some HTTP classification tools.
trait RetryBudget extends AnyRef
Represents a budget for retrying requests.
Represents a budget for retrying requests.
A retry budget is useful for attenuating the amplifying effects of many clients within a process retrying requests multiple times. This acts as a form of coordination between those retries.
Implementations must be thread-safe.
See also
RetryBudget.apply for creating instances.
Retries for how budgets get translated into Filters.
final class RetryBudgets extends AnyRef
Java APIs for RetryBudget.
final class RetryExceptionsFilter[Req, Rep] extends RetryFilter[Req, Rep]
A com.twitter.finagle.Filter that coordinates retries of subsequent Services.
A com.twitter.finagle.Filter that coordinates retries of subsequent Services. Exceptional responses can can be classified as retryable via the retryPolicy argument com.twitter.finagle.service.RetryPolicy.
Note
consider using a Timer with high resolution so that there is less correlation between retries. For example HighResTimer.Default.
See also
RetryFilter for a version that allows for retries on "successful" responses as well as failures.
class RetryFilter[Req, Rep] extends Filter[Req, Rep, Req, Rep]
A com.twitter.finagle.Filter that coordinates retries of subsequent Services.
A com.twitter.finagle.Filter that coordinates retries of subsequent Services. Successful and exceptional responses can be classified as retryable via the retryPolicy com.twitter.finagle.service.RetryPolicy argument.
Note
consider using a Timer with high resolution so that there is less correlation between retries. For example HighResTimer.Default.
See also
The user guide for more details.
abstract class RetryPolicy[-A] extends (A) => Option[(Duration, RetryPolicy[A])]
A function defining retry behavior for a given value type A.
A function defining retry behavior for a given value type A.
The Function1 returns None if no more retries should be made and Some if another retry should happen. The returned Some has a Duration field for how long to wait for the next retry as well as the next RetryPolicy to use.
Finagle will automatically handle retryable Throws. Requests that have not been written to or processed by a remote service are safe to retry.
See also
SimpleRetryPolicy for a Java friendly API.
abstract class SimpleRetryPolicy[A] extends RetryPolicy[A] with (A) => Option[(Duration, RetryPolicy[A])]
A retry policy abstract class.
A retry policy abstract class. This is convenient to use for Java programmers. Simply implement the two abstract methods shouldRetry and backoffAt and you're good to go!
class SingletonFactory[Req, Rep] extends ServiceFactory[Req, Rep]
A com.twitter.finagle.ServiceFactory that produces Services identical to the argument service.
A com.twitter.finagle.ServiceFactory that produces Services identical to the argument service.
Note that this factory builds new Services, so the "singleton" service argument is not shared by reference. This differs from com.twitter.finagle.ServiceFactory#const in that const proxies all requests to the same service rather than creating new objects.
class StatsFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A StatsFilter reports request statistics including number of requests, number successful and request latency to the given StatsReceiver.
A StatsFilter reports request statistics including number of requests, number successful and request latency to the given StatsReceiver.
This constructor is exposed for testing purposes.
class StatsServiceFactory[Req, Rep] extends ServiceFactoryProxy[Req, Rep]
class TimeoutFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A com.twitter.finagle.Filter that applies a timeout to requests.
A com.twitter.finagle.Filter that applies a timeout to requests.
If the response is not satisfied within the timeout, the Future will be interrupted via Future.raise.
See also
The sections on clients and servers in the user guide for more details.

Value Members

object DeadlineFilter
DeadlineFilter provides an admission control module that can be pushed onto the stack to reject requests with expired deadlines (deadlines are set in the TimeoutFilter).
DeadlineFilter provides an admission control module that can be pushed onto the stack to reject requests with expired deadlines (deadlines are set in the TimeoutFilter). For servers, DeadlineFilter.module should be pushed onto the stack before the stats filters so stats are recorded for the request, and pushed after TimeoutFilter where a new Deadline is set. For clients, DeadlineFilter.module should be pushed before the stats filters; higher in the stack is preferable so requests are rejected as early as possible.
Note
Deadlines cross process boundaries and can span multiple nodes in a call graph. Even if a direct caller doesn't set a deadline, the server may still receive one and thus potentially fail the request. It is advised that all clients in the call graph be well prepared to handle NACKs before using this.
object DelayedFactory
object ExpiringService
object FailFastFactory
object NilService extends FailedService
A static FailedService object.
object PendingRequestFilter
A module which allows clients to limit the number of pending requests per connection.
A module which allows clients to limit the number of pending requests per connection.
The effects of this filter are reflected in the stat "dispatcher/.../pending", which is a sum over per-host connections of dispatched requests between client and server. If the limit is configured as L and there are N per-host connections, "dispatcher/.../pending" will be no greater than L * N.
Note that the "pending" stat recorded in c.t.f.StatsFilter can be greater than L * N because requests can be between c.t.f.StatsFilter and c.t.f.PendingRequestFilter when the stat is read.
See also
The user guide for more details.
object ReqRep
Represents a request/response pair.
Represents a request/response pair.
For some protocols, like HTTP, these types are what you'd expect — com.twitter.finagle.http.Request and com.twitter.finagle.http.Response. While for other protocols that may not be the case. Please review the protocol's "com.twitter.finagle.$protocol.service.$ProtocolResponseClassifier" for details.
See also
com.twitter.finagle.http.service.HttpResponseClassifier
com.twitter.finagle.thriftmux.service.ThriftMuxResponseClassifier
ReqRepT for a type-safe version
object RequeueFilter
object ResponseClass
object ResponseClassifier
object Retries
The Stack parameters and modules for configuring which and how many failed requests are retried for a client.
The Stack parameters and modules for configuring which and how many failed requests are retried for a client.
See also
The user guide for more details.
object RetryBudget
See RetryBudgets for Java APIs.
object RetryExceptionsFilter
object RetryFilter
object RetryPolicy
object RetryingService
object StatsFilter
object TimeoutFilter

Packages

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

service

package service

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Message framing

Exchanges

Messages

MuxFailure Flags

Security

Deprecation

Thrift codecs

service

package service

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

service