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.

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

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.

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

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

Note: when {{com.twitter.finagle.builder.ClientBuilder}} and
{{com.twitter.finagle.builder.ServerBuilder}} are deprecated,
package netty3 can move into its own package, so that only the
(new-style) clients and servers that depend on netty3 bring it in.

Thrift codecs

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.