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 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.FutureIface
. This is then passed
into Thrift.Client.newIface
:
Thrift.client.newIface[TestService.FutureIface]( addr, classOf[TestService.FutureIface])
However note that the Scala compiler can insert the latter
Class
for us, for which another variant of newIface
is
provided:
Thrift.client.newIface[TestService.FutureIface](addr)
In Java, we need to provide the class object:
TestService.FutureIface client =
Thrift.client.newIface(addr, TestService.FutureIface.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.
TestService.FutureIface
must be implemented and passed
into serveIface
:
// An echo service ThriftMux.server.serveIface(":*", new TestService.FutureIface { def query(x: String): Future[String] = Future.value(x) })
Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.
Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.
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.