Go implementation of a multiplexing and framing protocol for RPC calls
Go Other
Latest commit 3dc03bf Aug 29, 2017 @breerly breerly committed with prashantv Test Go 1.9 (#647)
Permalink
Failed to load latest commit information.
benchmark relay: Remove relay.Conn and use Connection directly (#604) Mar 3, 2017
crossdock thrift: Return error if we didn't decode a known exception (#566) Jan 19, 2017
examples thrift: Return error if we didn't decode a known exception (#566) Jan 19, 2017
guide Update tchannel/golang imports to tchannel-go Oct 3, 2015
http Fix import ordering Jun 17, 2016
hyperbahn thrift: Return error if we didn't decode a known exception (#566) Jan 19, 2017
internal/argreader Ensure reader is empty before calling Close (#564) Jan 19, 2017
json Small test cleanups (#551) Dec 21, 2016
peers Fix flaky TestHRWScorerIntegration due to error logs (#593) Feb 24, 2017
pprof Fix import ordering Jun 17, 2016
raw Fix import ordering Jun 17, 2016
relay relay: Remove relay.Conn and use Connection directly (#604) Mar 3, 2017
scripts Enforce apache thrift 0.9.3 in glide and in thrift generation (#615) Mar 23, 2017
stats Optimize metric key calculations Nov 17, 2015
testutils Add hook for peer connection status changes (#624) May 31, 2017
thrift thrift-gen: Use namespace to generate the output filename (#574) Jan 25, 2017
tnet Wrap a net.Listener for better Close semantics Jan 5, 2016
tos Set DiffServ (QoS) bit on Outbound Connections (#516) Mar 22, 2017
trace Restore trace package (#486) Aug 17, 2016
trand Move threadsafe rand.Rand to a package May 4, 2016
typed Add Reader to read typed values from an io.Reader Jan 11, 2016
.gitignore Enforce apache thrift 0.9.3 in glide and in thrift generation (#615) Mar 23, 2017
.travis.yml Test Go 1.9 (#647) Aug 29, 2017
CHANGELOG.md Add release date to all releases in CHANGELOG (#642) Aug 4, 2017
CONTRIBUTING.md Version 1.3.0 Preparation (#576) Feb 2, 2017
LICENSE.md Add a separate license file Jan 8, 2016
Makefile Enforce apache thrift 0.9.3 in glide and in thrift generation (#615) Mar 23, 2017
README.md Enable coveralls.io support Jan 10, 2016
all_channels.go Log Info level logs on channel creation (#622) Apr 19, 2017
all_channels_test.go introspection: Only include other channels if requested (#474) Aug 5, 2016
arguments.go Ensure reader is empty before calling Close (#564) Jan 19, 2017
arguments_test.go Ensure reader is empty before calling Close (#564) Jan 19, 2017
calloptions.go Support routing key transport header and call option (#496) Sep 15, 2016
calloptions_test.go Support routing key transport header and call option (#496) Sep 15, 2016
channel.go Add hook for peer connection status changes (#624) May 31, 2017
channel_test.go Add version information to LocalPeerInfo (#579) Feb 8, 2017
channel_utils_test.go Simplify testutils.NewServer and NewChannel Nov 7, 2015
channelstate_string.go Add ChannelState to progress the state of a channel as it closes. Aug 3, 2015
checksum.go Pool checksum objects Jan 5, 2016
close_test.go Fix flaky TestCloseSemantics, use separate context per call (#592) Feb 24, 2017
conn_leak_test.go Fix connection leak caused by references from peer (#644) Aug 8, 2017
connection.go Remove unused connection field, ignoreRemotePeer (#619) Apr 19, 2017
connection_bench_test.go Fix import ordering Jun 17, 2016
connection_direction.go Refactor add*Connection to be shared May 18, 2016
connection_test.go bugfix: cancel server context on client tcp close (#635) Aug 2, 2017
connectionstate_string.go Only create Connection object for active TChannel connections (#587) Feb 24, 2017
context.go Expose LocalPeer on {Inbound,Outbound}Call (#537) Dec 21, 2016
context_builder.go Support routing key transport header and call option (#496) Sep 15, 2016
context_header.go Add tchannel.WithoutHeaders (#637) Aug 3, 2017
context_internal_test.go Add tchannel.WithoutHeaders (#637) Aug 3, 2017
context_test.go Add ctx.Child method for easier parallel sub-request calls (#549) Dec 21, 2016
dial_16.go Use net.DialContext on go1.7 when creating outbound connections (#541) Dec 21, 2016
dial_17.go Use net.DialContext on go1.7 when creating outbound connections (#541) Dec 21, 2016
dial_17_test.go Use net.DialContext on go1.7 when creating outbound connections (#541) Dec 21, 2016
doc.go Add tchannel documentation Oct 5, 2015
errors.go Only create Connection object for active TChannel connections (#587) Feb 24, 2017
errors_test.go relay: Avoid allocations on errors from relay Dec 21, 2016
fragmentation_test.go Fix import ordering Jun 17, 2016
fragmenting_reader.go Clarify error messages in for fragmenting reader errors (#567) Jan 19, 2017
fragmenting_writer.go Move ArgWriter interface into arguments.go Jan 13, 2016
frame.go Make frame parsing more resilient to bad inputs (#621) Apr 19, 2017
frame_pool.go Enable SyncFramePool by default Nov 12, 2015
frame_pool_b_test.go Remove atomic package and use uber-go/atomic Jun 3, 2016
frame_pool_test.go Fix import ordering Jun 17, 2016
frame_test.go Make frame parsing more resilient to bad inputs (#621) Apr 19, 2017
frame_utils_test.go Add ProtectMemFramePool which ensures frames aren't reused after Release Jun 22, 2016
glide.lock Pin apache/thrift 0.10.0 (#634) Jul 28, 2017
glide.yaml Pin apache/thrift 0.10.0 (#634) Jul 28, 2017
handlers.go SubChannel.SetHandler: override SubChannel Handlers Mar 1, 2016
handlers_test.go SubChannel.SetHandler: override SubChannel Handlers Mar 1, 2016
inbound.go bugfix: cancel server context on client tcp close (#635) Aug 2, 2017
inbound_test.go Fix flaky test TestInboundConnection (#588) Feb 23, 2017
incoming_test.go Fix import ordering Jun 17, 2016
init_test.go Consistent error logging on init handshake errors (#602) Mar 1, 2017
introspection.go Publicize channel root peers (#571) Jan 23, 2017
introspection_test.go Allow introspection calls on the "tchannel" service (#456) Jul 20, 2016
largereq_test.go Fix import ordering Jun 17, 2016
localip.go ListenIP: Reduce preference for locally administered MAC addresses. (#… Jan 19, 2017
localip_test.go ListenIP: Reduce preference for locally administered MAC addresses. (#… Jan 19, 2017
logger.go nullLogger should store all fields Feb 3, 2016
logger_test.go Add an ErrField helper Jan 8, 2016
messages.go Support routing key transport header and call option (#496) Sep 15, 2016
messages_test.go Fix import ordering Jun 17, 2016
messagetype_string.go go: Ping/Pong implementation. Jun 17, 2015
mex.go Replace exchange timeout with exchange expired to support cancellatio… Dec 21, 2016
mex_utils_test.go Introduce testutils.TestServer Mar 29, 2016
outbound.go Only create Connection object for active TChannel connections (#587) Feb 24, 2017
peer.go Fix connection leak caused by references from peer (#644) Aug 8, 2017
peer_bench_test.go Fix import ordering Jun 17, 2016
peer_heap.go Move threadsafe rand.Rand to a package May 4, 2016
peer_heap_test.go Update tests to avoid using unexported types Jan 15, 2016
peer_internal_test.go Treat hostPorts ending in ":0" in the init headers as ephemeral (#513) Dec 21, 2016
peer_strategies.go Isolated subchannels should not prefer incoming Dec 21, 2015
peer_test.go Added a peer.GetNew() to only return previously unselected peers. (#607) Mar 13, 2017
preinit_connection.go Consistent error logging on init handshake errors (#602) Mar 1, 2017
relay.go Use connection logger for relay items instead of channel logger (#636) Aug 3, 2017
relay_api.go relay: Remove relay.Conn and use Connection directly (#604) Mar 3, 2017
relay_benchmark_test.go Fix assertion that warmup succeeded Jun 21, 2016
relay_internal_test.go Fix import ordering Jun 17, 2016
relay_messages.go Clamp relay timeouts to a configurable max (#530) Dec 21, 2016
relay_messages_benchmark_test.go relay: Use []byte instead of string for Caller/Service/Method Jun 19, 2016
relay_messages_test.go Clamp relay timeouts to a configurable max (#530) Dec 21, 2016
relay_test.go relay: Close connections if the RelayHost returns a ProtocolError (#605) Mar 3, 2017
reqres.go Refactor connection options propagation (#568) Jan 19, 2017
reqresreaderstate_string.go Add _string generated files (and stop ignoring them) Jun 16, 2015
reqreswriterstate_string.go Add _string generated files (and stop ignoring them) Jun 16, 2015
retry.go Use structured logging for all Info logs (#512) Dec 21, 2016
retry_request_test.go Fix import ordering Jun 17, 2016
retry_test.go Small test cleanups (#551) Dec 21, 2016
retryon_string.go Add RetryIdempotent option Nov 10, 2015
root_peer_list.go Add hook for peer connection status changes (#624) May 31, 2017
stats.go Fix copyright headers in *.go files. Aug 21, 2015
stats_test.go Fix import ordering Jun 17, 2016
stats_utils_test.go Fix "copying lock" go vet Feb 25, 2016
stream_test.go Fix flaky test TestResponseClosedBeforeRequest (#438) Jul 15, 2016
stress_flag_test.go Fix copyright headers in *.go files. Aug 21, 2015
subchannel.go Update the peer scores when SetStrategy is called (#583) Feb 15, 2017
subchannel_test.go Override inbound request handler (#590) Feb 24, 2017
systemerrcode_string.go Generate string methods for SystemErrCode Nov 3, 2015
tchannel_test.go Ensure that all created channels are closed Apr 21, 2016
tracing.go Clone headers when injecting tracing data for outbound request (#506) Sep 29, 2016
tracing_internal_test.go Only create Connection object for active TChannel connections (#587) Feb 24, 2017
tracing_keys.go Integrate OpenTracing (#426) Aug 5, 2016
tracing_test.go Clone headers when injecting tracing data for outbound request (#506) Sep 29, 2016
utils_for_test.go Fix connection leak caused by references from peer (#644) Aug 8, 2017
verify_utils_test.go Update WithVerifiedServer to use testutils.WithTestServer Apr 4, 2016
version.go Update version and CHANGELOG for v1.7.0 release (#639) Aug 4, 2017

README.md

TChannel GoDoc Build Status Coverage Status

TChannel is a multiplexing and framing protocol for RPC calls. tchannel-go is a Go implementation of the protocol, including client libraries for Hyperbahn.

If you'd like to start by writing a small Thrift and TChannel service, check out this guide. For a less opinionated setup, see the contribution guidelines.

Overview

TChannel is a network protocol that supports:

  • A request/response model,
  • Multiplexing multiple requests across the same TCP socket,
  • Out-of-order responses,
  • Streaming requests and responses,
  • Checksummed frames,
  • Transport of arbitrary payloads,
  • Easy implementation in many languages, and
  • Redis-like 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, or
  • 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: routers need to parse the first or second field, but can forward the third field without parsing.

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

See the protocol specification for more details.

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.

This project is released under the [MIT License](LICENSE.md).