Skip to content

Latest commit

 

History

History
167 lines (122 loc) · 5.58 KB

README.md

File metadata and controls

167 lines (122 loc) · 5.58 KB
Raw

TChannel for JVM

Build Status codecov.io Release

The Java implementation of the TChannel protocol.

Stability: Stable

stable

Example

// create TChannel for server, and register a RequestHandler
TChannel server = new TChannel.Builder("ping-server").build();
server.makeSubChannel("ping-server")
	.register("ping-handler", new RawRequestHandler() {
        @Override
        public RawResponse handleImpl(RawRequest request) {
            return new RawResponse.Builder(request)
                .setTransportHeaders(request.getTransportHeaders())
                .setHeader("Polo")
                .setBody("Pong!")
                .build();
        }
	});

// listen for incoming connections
server.listen();

// create another TChannel for client.
TChannel client = new TChannel.Builder("ping-client").build();
RawRequest request = new RawRequest.Builder("ping-server", "ping-handler")
    .setHeader("Marco")
    .setBody("Ping!")
	.build();

// make an asynchronous request
TFuture<RawResponse> responseFuture = client
	.makeSubChannel("ping-server").send(
		request,
		server.getHost(),
		server.getListeningPort()
	);

// block and wait for the response
try (RawResponse response = responseFuture.get()) {
    System.out.println(response);
}

// shutdown the channel after done
server.shutdown();
client.shutdown();

Overview

TChannel is a network protocol with the following goals:

  • request / response model
  • multiple requests multiplexed across the same TCP socket
  • out of order responses
  • streaming request and responses
  • all frames checksummed
  • transport arbitrary payloads
  • easy to implement in multiple languages
  • near-redis performance

This protocol is intended to run on datacenter networks for inter-process communication.

Protocol

TChannel frames have a fixed length header and 3 variable length fields. The underlying protocol does not assign meaning to these fields, but the included client/server implementation uses the first field to represent a unique endpoint or function name in an RPC model. The next two fields can be used for arbitrary data. Some suggested way to use the 3 fields are:

  • URI path, HTTP method and headers as JSON, body
  • function name, headers, thrift / protobuf

Note however that the only encoding supported by TChannel is UTF-8. If you want JSON, you'll need to stringify and parse outside of TChannel.

This design supports efficient routing and forwarding of data where the routing information needs to parse only the first or second field, but the 3rd field is forwarded without parsing.

Build

mvn clean package

Run Tests

mvn clean test

More Examples

See the examples.

Run Ping server/client example:

mvn package
# ping server
java -cp tchannel-example/target/tchannel-example.jar com.uber.tchannel.ping.PingServer -p 8888

# ping client
java -cp tchannel-example/target/tchannel-example.jar com.uber.tchannel.ping.PingClient -h localhost -p 8888 -n 1000

Contributing

Pull requests must have thorough testing and be reviewed by at least one other party. You must run benchmarks to ensure there is no performance degradation.

Releasing

  1. Create an account for oss.sonatype.org. You can sign up here.

    This will be your credentials for ~/.m2/settings.xml as well, which are going to be needed for pushing changes to the Sonatype index.

  2. File a ticket with Sonatype to get required permissions to publish for com.uber.tchannel group ID. {example}

  3. Generate and share a PGP signature.

    a. $ gpg --gen-key

    b. pick RSA and RSA (default) with keysize of 2048 bits. Expiration time is left up to you (but never expire might be easiest option).

    c. $ gpg --list-secret-keys will now list your keys.

    d. Take the pub key ID from the result of gpg --list-keys and do something like $ gpg --keyserver hkp://pool.sks-keyservers.net --send-keys ******** to upload your pub keys.

  4. Settings

    pom.xml already has the required configuration. Make the following change to ~/.m2/settings.xml, using the credentials from (1).

    <settings>
    <servers>
        <server>
            <id>ossrh</id>
            <username>your-username-here</username>
            <password>your-password-here</password>
        </server>
    </servers>
</settings>

    mvn help:effective-settings will assist in weeding out typos.

  5. Run make release.

  6. You will be able to see activity related to the change on the Nexus Repository Manager here. It can take between 12-24 hours for the full release to complete, and the artifacts to be consumable from other projects.

MIT Licenced