# README
TChannel 
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).
# Packages
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Package peers provides helpers for managing TChannel peers.
No description provided by the author
No description provided by the author
Package relay contains relaying interfaces for external use.
No description provided by the author
No description provided by the author
No description provided by the author
Package thrift adds support to use Thrift services over TChannel.
No description provided by the author
No description provided by the author
Package trace used to contain TChannel's distributed tracing functionality.
Package trand provides a thread-safe random number generator.
No description provided by the author
# Functions
CurrentCall returns the current incoming call, or nil if this is not an incoming call context.
CurrentSpan extracts OpenTracing Span from the Context, and if found tries to extract zipkin-style trace/span IDs from it using ZipkinSpanFormat carrier.
ErrField wraps an error string as a LogField named "error".
ExtractInboundSpan is a higher level version of extractInboundSpan().
GetContextError converts the context error to a tchannel error.
GetSystemErrorCode returns the code to report for the given error.
GetSystemErrorMessage returns the message to report for the given error.
InjectOutboundSpan retrieves OpenTracing Span from `response`, where it is stored when the outbound call is initiated.
Isolated is a SubChannelOption that creates an isolated subchannel.
ListenIP returns the IP to bind to in Listen.
NewArgReader wraps the result of calling ArgXReader to provide a simpler interface for reading arguments.
NewArgWriter wraps the result of calling ArgXWriter to provider a simpler interface for writing arguments.
NewChannel creates a new Channel.
NewChannelFramePool returns a frame pool backed by a channel that has a max capacity.
NewContext returns a new root context used to make TChannel requests.
NewContextBuilder returns a builder that can be used to create a Context.
NewFrame allocates a new frame with the given payload capacity.
NewLevelLogger returns a logger that only logs messages with a minimum of level.
NewLogger returns a Logger that writes to the given writer.
NewRelayer constructs a Relayer.
NewSyncFramePool returns a frame pool that uses a sync.Pool.
NewSystemError defines a new SystemError with a code and message.
NewWrappedSystemError defines a new SystemError wrapping an existing error.
TracerFromRegistrar returns an OpenTracing Tracer embedded in the Registrar, assuming that Registrar has a Tracer() method.
WithoutHeaders hides any TChannel headers from the given context.
Wrap wraps an existing context.Context into a ContextWithHeaders.
WrapContextForTest returns a copy of the given Context that is associated with the call.
WrapWithHeaders returns a Context that can be used to make a call with request headers.
# Constants
ArgScheme header specifies the format of the args.
CallerName header specifies the name of the service making the call.
ChannelClient is a channel that can be used as a client.
ChannelClosed is a channel that has closed completely.
ChannelInboundClosed is a channel that has drained all incoming connections, but may have outgoing connections.
ChannelListening is a channel that is listening for new connnections.
ChannelStartClose is a channel that has received a Close request.
ChecksumTypeCrc32 indicates the message checksum is calculated using crc32.
ChecksumTypeCrc32C indicates the message checksum is calculated using crc32c.
ChecksumTypeFarmhash indicates the message checksum is calculated using Farmhash.
ChecksumTypeNone indicates no checksum is included in the message.
ClaimAtFinish header value is host:port specifying the instance to send a claim message to when response is being sent.
ClaimAtStart header value is host:port specifying another instance to send a claim message to when work is started.
CurrentProtocolVersion is the current version of the TChannel protocol supported by this stack.
DefaultConnectionBufferSize is the default size for the connection's readand write channels.
DefaultConnectTimeout is the default timeout used by net.Dial, if no timeout is specified in the context.
ErrCodeBadRequest indicates that the request was malformed, and could not be processed.
ErrCodeBusy indicates that the request was not dispatched because the peer was too busy to handle it.
ErrCodeCancelled indicates that the request was cancelled on the peer.
ErrCodeDeclined indicates that the request not dispatched because the peer declined to handle it, typically because the peer is not yet ready to handle it.
ErrCodeInvalid is an invalid error code, and should not be used.
ErrCodeNetwork indicates a network level error, such as a connection reset.
ErrCodeProtocol indincates a fatal protocol error communicating with the peer.
ErrCodeTimeout indicates the peer timed out.
ErrCodeUnexpected indicates that the request failed for an unexpected reason, typically a crash or other unexpected handling.
FailureDomain header describes a group of related requests to the same service that are likely to fail in the same way if they were to fail.
FrameHeaderSize is the size of the header element for a frame.
The list of formats supported by tchannel.
InitParamHostPort contains the host and port of the peer process.
InitParamProcessName contains the name of the peer process.
InitParamTChannelLanguage contains the library language.
InitParamTChannelLanguageVersion contains the language build/runtime version.
InitParamTChannelVersion contains the library version.
The list of formats supported by tchannel.
The minimum level that will be logged.
The minimum level that will be logged.
The minimum level that will be logged.
The minimum level that will be logged.
The minimum level that will be logged.
The minimum level that will be logged.
MaxFramePayloadSize is the maximum size of the payload for a single frame.
MaxFrameSize is the total maximum size for a frame.
The list of formats supported by tchannel.
RetryConnectionError retries on busy frames, declined frames, and connection errors.
RetryDefault is currently the same as RetryConnectionError.
RetryFlags header specifies whether retry policies.
RetryIdempotent will retry all errors that can be retried.
RetryNever never retries any errors.
RetryNonIdempotent will retry errors that occur before a request has been picked up.
RetryUnexpected will retry busy frames, declined frames, and unenxpected frames.
RoutingDelegate header identifies an intermediate service which knows how to route the request to the intended recipient.
RoutingKey header identifies a traffic group containing instances of the requested service.
ShardKey header value is used by ringpop to deliver calls to a specific tchannel instance.
SpeculativeExecution header specifies the number of nodes on which to run the request.
The list of formats supported by tchannel.
VersionInfo identifies the version of the TChannel library.
# Variables
DefaultFramePool uses the SyncFramePool.
DisabledFramePool is a pool that uses the heap and relies on GC.
ErrChannelClosed is a SystemError indicating that the channel has been closed.
ErrConnectionClosed is returned when a caller performs an method on a closed connection.
ErrConnectionNotReady is no longer used.
ErrInvalidConnectionState indicates that the connection is not in a valid state.
ErrMethodTooLarge is a SystemError indicating that the method is too large.
ErrNoNewPeers indicates that no previously unselected peer is available.
ErrNoPeers indicates that there are no peers.
ErrNoServiceName is returned when no service name is provided when creating a new channel.
ErrPeerNotFound indicates that the specified peer was not found.
ErrRequestCancelled is a SystemError indicating the request has been cancelled on the peer.
ErrSendBufferFull is returned when a message cannot be sent to the peer because the frame sending buffer has become full.
ErrServerBusy is a SystemError indicating the server is busy.
ErrTimeout is a SytemError indicating the request has timed out.
ErrTimeoutRequired is a SystemError indicating that timeouts must be specified.
NullLogger is a logger that emits nowhere.
NullStatsReporter is a stats reporter that discards the statistics.
SimpleLogger prints logging information to standard out.
SimpleStatsReporter is a stats reporter that reports stats to the log.
# Structs
ArgReadHelper providers a simpler interface to reading arguments.
ArgWriteHelper providers a simpler interface to writing arguments.
CallOptions are options for a specific call.
A Channel is a bi-directional connection to the peering and routing network.
ChannelInfo is the state of other channels in the same process.
ChannelOptions are used to control parameters on a create a TChannel.
Connection represents a connection to a remote peer.
ConnectionOptions are options that control the behavior of a Connection.
ConnectionRuntimeState is the runtime state for a single connection.
ContextBuilder stores all TChannel-specific parameters that will be stored inside of a context.
ExchangeRuntimeState is the runtime state for a single message exchange.
ExchangeSetRuntimeState is the runtime state for a message exchange set.
A Frame is a header and payload.
FrameHeader is the header for a frame, containing the MessageType and size.
GoRuntimeState is a snapshot of runtime stats from the runtime.
GoRuntimeStateOptions are the options used when getting Go runtime state.
HandlerRuntimeState TODO.
HealthCheckOptions are the parameters to configure active TChannel health checks.
An InboundCall is an incoming call from a peer.
An InboundCallResponse is used to send the response back to the calling peer.
IntrospectionOptions are the options used when introspecting the Channel.
LocalPeerInfo adds service name to the peer info, only required for the local peer.
LogField is a single field of additional information passed to the logger.
An OutboundCall is an active call to a remote peer.
An OutboundCallResponse is the response to an outbound call.
Peer represents a single autobahn service or client with a unique host:port.
PeerInfo contains information about a TChannel peer.
PeerList maintains a list of Peers.
PeerRuntimeState is the runtime state for a single peer.
PeerVersion contains version related information for a specific peer.
A Relayer forwards frames.
RelayerRuntimeState is the runtime state for a single relayer.
RelayItemSetState is the runtime state for a list of relay items.
RelayItemState is the runtime state for a single relay item.
RequestState is a global request state that persists across retries.
RetryOptions are the retry options used to configure RunWithRetry.
RootPeerList is the root peer list which is only used to connect to peers and share peers between subchannels.
RuntimeState is a snapshot of the runtime state for a channel.
RuntimeVersion includes version information about the runtime and the tchannel library.
SendBufferSizeOverride is used for overriding per-process send buffer channel size for a connection, using process name prefix matching.
Span is an internal representation of Zipkin-compatible OpenTracing Span.
SubChannel allows calling a specific service on a channel.
SubChannelRuntimeState is the runtime state for a subchannel.
SubPeerScore show the runtime state of a peer with score.
A SystemError is a system-level error, containing an error code and message TODO(mmihic): Probably we want to hide this interface, and let application code just deal with standard raw errors.
# Interfaces
ArgReadable is an interface for providing arg2 and arg3 reader streams; implemented by reqResReader e.g.
ArgWritable is an interface for providing arg2 and arg3 writer streams; implemented by reqResWriter e.g.
ArgWriter is the interface for the arg2 and arg3 streams on an OutboundCall and an InboundCallResponse.
A Checksum calculates a running checksum against a bytestream.
Connectable is the interface used by peers to create connections.
ContextWithHeaders is a Context which contains request and response headers.
A FramePool is a pool for managing and re-using frames.
A Handler is an object that can be registered with a Channel to process incoming calls for a given service and method.
IncomingCall exposes properties for incoming calls through the context.
Logger provides an abstract interface for logging from TChannel.
Registrar is the base interface for registering handlers on either the base Channel or the SubChannel.
RelayCall abstracts away peer selection, stats, and any other business logic from the underlying relay implementation.
RelayHost is the interface used to create RelayCalls when the relay receives an incoming call.
ScoreCalculator defines the interface to calculate the score.
StatsReporter is the the interface used to report stats.
# Type aliases
ArgReader is the interface for the arg2 and arg3 streams on an OutboundCallResponse and an InboundCall.
ChannelState is the state of a channel.
A ChecksumType is a checksum algorithm supported by TChannel for checksumming call bodies.
An ErrorHandlerFunc is an adapter to allow the use of ordinary functions as Channel handlers, with error handling convenience.
Format is the arg scheme used for a specific call.
A HandlerFunc is an adapter to allow the use of ordinary functions as Channel handlers.
LogFields is a list of LogFields used to pass additional information to the logger.
LogLevel is the level of logging used by LevelLogger.
ResponseCode to a CallReq.
RetriableFunc is the type of function that can be passed to RunWithRetry.
RetryOn represents the types of errors to retry on.
ScoreCalculatorFunc is an adapter that allows functions to be used as ScoreCalculator.
SubChannelOption are used to set options for subchannels.
A SystemErrCode indicates how a caller should handle a system error returned from a peer.
TransportHeaderName is a type for transport header names.