TChannel

TChannel is a multiplexing and framing protocol for RPC calls.

tchannel-go is a Go implementation of the TChannel protocol, and includes client libraries for Hyperbahn.

Stability: experimental

NOTE: master:golang is not yet stable

Thrift + TChannel Integration

If you want to use Thrift+TChannel, you will want to read this guide.

Getting Started

Get Go from your package manager of choice or follow the official installation instructions.

brew install go

# This will be your GOPATH where all Go code will live.
mkdir -p ~/gocode/src

Set up your environment for your shell of choice.

export GOPATH="${HOME}/gocode"
export PATH="${PATH}":"${GOPATH}/bin"

TChannel uses godep to manage dependencies. To get started:

go get github.com/uber/tchannel-go
go get github.com/tools/godep
cd $GOPATH/src/github.com/uber/tchannel-go
godep restore
make

Examples

Simple examples are included which demonstrate the TChannel API and features.

PingPong

./build/examples/ping/pong

This example creates a client and server channel. The server channel registers a PingService with a ping operation, which takes request Headers and a Ping body and returns the same Headers along with a Pong body. The client sends a ping request to the server

Note that every instance is bidirectional, so the same channel can be used for both sending and receiving requests to peers. New connections are initiated on demand.

KeyValue

./build/examples/keyvalue/server
./build/examples/keyvalue/client

This example exposes a simple keyvalue service over TChannel using the Thrift protocol. The client has an interactive CLI that can be used to make calls to the server.

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.

There is no notion of client and server in this system. Every TChannel instance is capable of making or receiving requests, and thus requires a unique port on which to listen. This requirement may change in the future.

See protocol.md for more details

Further examples

ping: A simple ping/pong example using raw TChannel.
thrift: A Thrift server/client example.
keyvalue: A keyvalue Thrift service with separate server and client binaries.

Tests

make test or make cover

Contributors

mmihic
prashantv

thanodnl/tchannel-go