Packages

•  package root

  Definition Classes

  root

•  package com

  Definition Classes

  root

•  package twitter

  Start with com.twitter.finagle.

  Start with com.twitter.finagle.

  Definition Classes

  com

•  package finagle

  Finagle is an extensible RPC system.

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

  Definition Classes

  finagle

•  package lease

  Definition Classes

  mux

•  package exp

  This is the experimental package of mux.lease.

  This is the experimental package of mux.lease. Right now, this is all experimental code around leasing, especially leasing around garbage collections. We haven't hammered out exactly what the api will be, so it's in large part private and is subject to change.

  If you want to experiment with GC avoidance, you need to turn on the flag com.twitter.finagle.mux.lease.exp.drainerEnabled to enable GC avoidance, and right now it only works with parallel old and CMS. So far, we've seen promising results with GC avoidance locally, but haven't had the opportunity to run scientific load tests when simulating production load.

  It can be useful to turn on the com.twitter.finagle.mux.lease.exp.drainerDebug flag to get much more granular data about what is going on. Turning on this flag will log stats for each garbage collection avoidance attempt. Especially interesting is to see how long it takes for a server to drain, how many outstanding requests there still are, and whether any GCs were natural instead of triggered. If there are still outstanding requests when the GC is triggered, it might make sense to turn on nacking, or allow more time for draining.

  You can turn on nacking for a server after the lease has expired by turning on the flag com.twitter.finagle.mux.lease.exp.nackOnExpiredLease. The way this behaves is that it nacks all requests which come in after a 0 lease has been issued. This has two effects--it corrects behavior for clients which are slow to respect leases and turns on failure accrual for clients which continue to send requests. One possible area of future work would be allowing consumers to configure whether or not Finagle's failure accrual mechanism considers these nacks to be failures. Another possible improvement would be to nack requests which are already partially completed, instead of just new incoming requets.

  The com.twitter.finagle.mux.lease.exp.drainerDiscountRange flag modulates how the server chooses the discount, which is when it expires the lease. The left is the absolute lower bound on the range from which it will select randomly. The right is the absolute upper bound on the range from which it will select randomly. It chooses a uniform random number of bytes from between the upper bound and the max of the percentile number of bytes generated in a single request and the lower bound. The absolute lower bound does double duty--it is also used for choosing when to stop waiting for stragglers and run a GC regardless.

  The com.twitter.finagle.mux.lease.exp.drainerPercentile flag specifies the percentile of the incoming request distribution that will be chosen for deciding how long it takes to handle a single request.

  If you're not working with a JDK which supports System.minorGc, GCA will not work properly, since it will not just run a minor GC when you trigger System.gc. Although the behavior will continue to be correct, it will be less efficient. Assuming you're draining properly, your pause times won't affect your latency, but you will have lower throughput, since your server will spend more time not receiving traffice. One possible direction for further work is to allocate big arrays until you trigger a minor GC, but this must be done slightly delicately to avoid triggering a major collection.

  The drainerDiscountRange is of insufficient fidelity. The biggest problem is that it doesn't make sense to conflate the hard cutoff for triggering a GC with the drainerDiscountRange minimum, so it should probably be separated out.

  Observing leases on the client side can be made slightly smarter too. It might make sense to have some kind of communication which encourages clients to stop sending requests that it guesses will soon fail (for leases that will soon expire).

  NB: large parts of this package might suddenly end up in util-jvm

  Definition Classes

  lease

• DedupingLogsReceiver
• GarbageCollectorAddable
• LogsReceiver
• NullLogsReceiver
• drainerDebug
• drainerDiscountRange
• drainerEnabled
• drainerPercentile
• nackOnExpiredLease

com.twitter.finagle.mux.lease.exp

LogsReceiver