tchannel

package
v0.0.0-...-a1a640b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 29, 2015 License: MIT Imports: 20 Imported by: 0

README

TChannel

GoDoc

network multiplexing and framing protocol for RPC

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 ~/golang/src

Set up your environment for your shell of choice.

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

TChannel uses godep to manage dependencies. To get started:

go get github.com/uber/tchannel/golang
go get github.com/tools/godep
cd $GOPATH/src/github.com/uber/tchannel/golang
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.

Further examples

Tests

make test or make cover

Contributors

  • mmihic
  • prashantv

MIT Licenced

Documentation

Index

Constants

View Source 
const (
	// MaxFrameSize is the total maximum size for a frame
	MaxFrameSize = math.MaxUint16

	// FrameHeaderSize is the size of the header element for a frame
	FrameHeaderSize = 16

	// MaxFramePayloadSize is the maximum size of the payload for a single frame
	MaxFramePayloadSize = MaxFrameSize - FrameHeaderSize
)
View Source 
const (
	// InitParamHostPort contains the host and port of the peer process
	InitParamHostPort = "host_port"

	// InitParamProcessName contains the name of the peer process
	InitParamProcessName = "process_name"
)
View Source 
const (
	AnnotationKeyClientSend    = "cs"
	AnnotationKeyClientReceive = "cr"
	AnnotationKeyServerSend    = "ss"
	AnnotationKeyServerReceive = "sr"
)

Known annotation keys

View Source 
const CurrentProtocolVersion = 0x02

CurrentProtocolVersion is the current version of the TChannel protocol supported by this stack

Variables

View Source 
var (
	// ErrConnectionClosed is returned when a caller performs an operation
	// on a closed connection
	ErrConnectionClosed = errors.New("connection is closed")

	// ErrConnectionNotReady is returned when a caller attempts to send a
	// request through a connection which has not yet been initialized
	ErrConnectionNotReady = errors.New("connection is not yet ready")

	// ErrSendBufferFull is returned when a message cannot be sent to the
	// peer because the frame sending buffer has become full.  Typically
	// this indicates that the connection is stuck and writes have become
	// backed up
	ErrSendBufferFull = errors.New("connection send buffer is full, cannot send frame")
)
View Source 
var (
	// ErrServerBusy is a SystemError indicating the server is busy
	ErrServerBusy = NewSystemError(ErrCodeBusy, "server busy")

	// ErrRequestCancelled is a SystemError indicating the request has been cancelled on the peer
	ErrRequestCancelled = NewSystemError(ErrCodeCancelled, "request cancelled")

	// ErrTimeout is a SytemError indicating the request has timed out
	ErrTimeout = NewSystemError(ErrCodeTimeout, "timeout")

	// ErrTimeoutRequired is a SystemError indicating that timeouts must be specified.
	ErrTimeoutRequired = NewSystemError(ErrCodeBadRequest, "timeout required")

	// ErrChannelClosed is a SystemError indicating that the channel has been closed.
	ErrChannelClosed = NewSystemError(ErrCodeDeclined, "closed channel")

	// ErrOperationTooLarge is a SystemError indicating that the operation is too large.
	ErrOperationTooLarge = NewSystemError(ErrCodeProtocol, "operation too large")
)
View Source 
var DefaultFramePool = DisabledFramePool

DefaultFramePool is the disabled frame pool which uses the heap.

View Source 
var DisabledFramePool = disabledFramePool{}

DisabledFramePool is a pool that uses the heap and relies on GC.

View Source 
var (
	// ErrInvalidConnectionState indicates that the connection is not in a valid state.
	ErrInvalidConnectionState = errors.New("connection is in an invalid state")
)
View Source 
var SimpleLogger = NewLogger(os.Stdout)

SimpleLogger prints logging information to standard out.

Functions

func ListenIP 

func ListenIP() (net.IP, error)

ListenIP returns the IP to bind to in Listen. It tries to find an IP that can be used by other machines to reach this machine.

func NewContext 

func NewContext(timeout time.Duration) (context.Context, context.CancelFunc)

NewContext returns a new root context used to make TChannel requests.

func NewRand 

func NewRand(seed int64) *rand.Rand

NewRand returns a rand.Rand that is threadsafe.

func NewSystemError 

func NewSystemError(code SystemErrCode, msg string, args ...interface{}) error

NewSystemError defines a new SystemError with a code and message

func NewWrappedSystemError 

func NewWrappedSystemError(code SystemErrCode, wrapped error) error

NewWrappedSystemError defines a new SystemError wrapping an existing error

func WrapContextForTest 

func WrapContextForTest(ctx context.Context, call IncomingCall) context.Context

WrapContextForTest returns a copy of the given Context that is associated with the call. This should be used in units test only. NOTE: This method is deprecated. Callers should use NewContextBuilder().SetIncomingCallForTest.

Types

type Annotation 

type Annotation struct {
	Key       AnnotationKey
	Timestamp time.Time
}

Annotation represents a specific event and the timestamp at which it occurred.

func NewAnnotation 

func NewAnnotation(key AnnotationKey) Annotation

NewAnnotation returns a new annotation.

type AnnotationKey 

type AnnotationKey string

AnnotationKey is the key for annotations.

type Annotations 

type Annotations struct {
	// contains filtered or unexported fields
}

Annotations is am embeddable struct used to track annotations.

func (*Annotations) AddAnnotation 

func (as *Annotations) AddAnnotation(key AnnotationKey)

AddAnnotation adds a standard annotation.

func (*Annotations) AddBinaryAnnotation 

func (as *Annotations) AddBinaryAnnotation(binaryAnnotation BinaryAnnotation)

AddBinaryAnnotation adds a binary annotation.

func (*Annotations) Report 

func (as *Annotations) Report(span Span, reporter TraceReporter) error

Report reports the annotations to the given trace reporter.

type ArgReadHelper 

type ArgReadHelper struct {
	// contains filtered or unexported fields
}

ArgReadHelper providers a simpler interface to reading arguments.

func NewArgReader 

func NewArgReader(reader io.ReadCloser, err error) ArgReadHelper

NewArgReader wraps the result of calling ArgXReader to provide a simpler interface for reading arguments.

func (ArgReadHelper) Read 

func (r ArgReadHelper) Read(bs *[]byte) error

Read reads from the reader into the byte slice.

func (ArgReadHelper) ReadJSON 

func (r ArgReadHelper) ReadJSON(data interface{}) error

ReadJSON deserializes JSON from the underlying reader into data.

type ArgWriteHelper 

type ArgWriteHelper struct {
	// contains filtered or unexported fields
}

ArgWriteHelper providers a simpler interface to writing arguments.

func NewArgWriter 

func NewArgWriter(writer io.WriteCloser, err error) ArgWriteHelper

NewArgWriter wraps the result of calling ArgXWriter to provider a simpler interface for writing arguments.

func (ArgWriteHelper) Write 

func (w ArgWriteHelper) Write(bs []byte) error

Write writes the given bytes to the underlying writer.

func (ArgWriteHelper) WriteJSON 

func (w ArgWriteHelper) WriteJSON(data interface{}) error

WriteJSON writes the given object as JSON.

type ArgWriter 

type ArgWriter interface {
	io.WriteCloser

	// Flush flushes the currently written bytes without waiting for the frame to be filled.
	Flush() error
}

ArgWriter is the interface returned by ArgXWriter.

type BinaryAnnotation 

type BinaryAnnotation struct {
	Key string
	// Value contains one of: string, float64, bool, []byte, int64
	Value interface{}
}

BinaryAnnotation is additional context information about the span.

func NewBinaryAnnotation 

func NewBinaryAnnotation(key string, value interface{}) BinaryAnnotation

NewBinaryAnnotation returns a new binary annotation.

type CallOptions 

type CallOptions struct {
	// Format is arg scheme used for this call, sent in the "as" header.
	// This header is only set if the Format is set.
	Format Format

	// ShardKey determines where this call request belongs, used with ringpop applications.
	ShardKey string
}

CallOptions are options for a specific call.

type Channel 

type Channel struct {
	// contains filtered or unexported fields
}

A Channel is a bi-directional connection to the peering and routing network. Applications can use a Channel to make service calls to remote peers via BeginCall, or to listen for incoming calls from peers. Applications that want to receive requests should call one of Serve or ListenAndServe TODO(prashant): Shutdown all subchannels + peers when channel is closed.

func NewChannel 

func NewChannel(serviceName string, opts *ChannelOptions) (*Channel, error)

NewChannel creates a new Channel. The new channel can be used to send outbound requests to peers, but will not listen or handling incoming requests until one of ListenAndServe or Serve is called. The local service name should be passed to serviceName.

func (*Channel) BeginCall 

func (ch *Channel) BeginCall(ctx context.Context, hostPort, serviceName, operationName string, callOptions *CallOptions) (*OutboundCall, error)

BeginCall starts a new call to a remote peer, returning an OutboundCall that can be used to write the arguments of the call.

func (*Channel) Close 

func (ch *Channel) Close()

Close starts a graceful Close for the channel. This does not happen immediately: 1. This call closes the Listener and starts closing connections. 2. When all incoming connections are drainged, the connection blocks new outgoing calls. 3. When all connections are drainged, the channel's state is updated to Closed.

func (*Channel) Closed 

func (ch *Channel) Closed() bool

Closed returns whether this channel has been closed with .Close()

func (*Channel) Connect 

func (ch *Channel) Connect(ctx context.Context, hostPort string, connectionOptions *ConnectionOptions) (*Connection, error)

Connect connects the channel.

func (*Channel) GetSubChannel 

func (ch *Channel) GetSubChannel(serviceName string) *SubChannel

GetSubChannel returns a SubChannel for the given service name. If the subchannel does not exist, it is created.

func (*Channel) ListenAndServe 

func (ch *Channel) ListenAndServe(hostPort string) error

ListenAndServe listens on the given address and serves incoming requests. The port may be 0, in which case the channel will use an OS assigned port This method does not block as the handling of connections is done in a goroutine.

func (*Channel) Logger 

func (ch *Channel) Logger() Logger

Logger returns the logger for this channel.

func (*Channel) PeerInfo 

func (ch *Channel) PeerInfo() LocalPeerInfo

PeerInfo returns the current peer info for the channel

func (*Channel) Peers 

func (ch *Channel) Peers() *PeerList

Peers returns the PeerList for the channel.

func (*Channel) Ping 

func (ch *Channel) Ping(ctx context.Context, hostPort string) error

Ping sends a ping message to the given hostPort and waits for a response.

func (*Channel) Register 

func (ch *Channel) Register(h Handler, operationName string)

Register registers a handler for a service+operation pair

func (*Channel) Serve 

func (ch *Channel) Serve(l net.Listener) error

Serve serves incoming requests using the provided listener. The local peer info is set synchronously, but the actual socket listening is done in a separate goroutine.

func (*Channel) ServiceName 

func (ch *Channel) ServiceName() string

ServiceName returns the serviceName that this channel was created for.

func (*Channel) State 

func (ch *Channel) State() ChannelState

State returns the current channel state.

type ChannelOptions 

type ChannelOptions struct {
	// Default Connection options
	DefaultConnectionOptions ConnectionOptions

	// The name of the process, for logging and reporting to peers
	ProcessName string

	// The logger to use for this channel
	Logger Logger

	// The reporter to use for reporting stats for this channel.
	StatsReporter StatsReporter

	// Trace reporter to use for this channel.
	TraceReporter TraceReporter

	// Trace reporter factory to generate trace reporter instance.
	TraceReporterFactory TraceReporterFactory
}

ChannelOptions are used to control parameters on a create a TChannel

type ChannelState 

type ChannelState int

ChannelState is the state of a channel. 

const (
	// ChannelClient is a channel that can be used as a client.
	ChannelClient ChannelState = iota + 1

	// ChannelListening is a channel that is listening for new connnections.
	ChannelListening

	// ChannelStartClose is a channel that has received a Close request.
	// The channel is no longer listening, and all new incoming connections are rejected.
	ChannelStartClose

	// ChannelInboundClosed is a channel that has drained all incoming connections, but may
	// have outgoing connections. All incoming calls and new outgoing calls are rejected.
	ChannelInboundClosed

	// ChannelClosed is a channel that has closed completely.
	ChannelClosed
)

func (ChannelState) String 

func (i ChannelState) String() string

type Checksum 

type Checksum interface {
	// TypeCode returns the type of this checksum
	TypeCode() ChecksumType

	// Size returns the size of the calculated checksum
	Size() int

	// Add adds bytes to the checksum calculation
	Add(b []byte) []byte

	// Sum returns the current checksum value
	Sum() []byte
}

A Checksum calculates a running checksum against a bytestream

type ChecksumType 

type ChecksumType byte

A ChecksumType is a checksum algorithm supported by TChannel for checksumming call bodies 

const (
	// ChecksumTypeNone indicates no checksum is included in the message
	ChecksumTypeNone ChecksumType = 0

	// ChecksumTypeCrc32 indicates the message checksum is calculated using crc32
	ChecksumTypeCrc32 ChecksumType = 1

	// ChecksumTypeFarmhash indicates the message checksum is calculated using Farmhash
	ChecksumTypeFarmhash ChecksumType = 2

	// ChecksumTypeCrc32C indicates the message checksum is calculated using crc32c
	ChecksumTypeCrc32C ChecksumType = 3
)

func (ChecksumType) ChecksumSize 

func (t ChecksumType) ChecksumSize() int

ChecksumSize returns the size in bytes of the checksum calculation

func (ChecksumType) New 

func (t ChecksumType) New() Checksum

New creates a new Checksum of the given type

type Connection 

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a connection to a remote peer.

func (*Connection) Close 

func (c *Connection) Close() error

Close starts a graceful Close which will first reject incoming calls, reject outgoing calls before finally marking the connection state as closed.

func (*Connection) IsActive 

func (c *Connection) IsActive() bool

IsActive returns whether this connection is in an active state.

func (*Connection) NextMessageID 

func (c *Connection) NextMessageID() uint32

NextMessageID reserves the next available message id for this connection

func (*Connection) SendSystemError 

func (c *Connection) SendSystemError(id uint32, span *Span, err error) error

SendSystemError sends an error frame for the given system error.

type ConnectionOptions 

type ConnectionOptions struct {
	// The frame pool, allowing better management of frame buffers.  Defaults to using raw heap
	FramePool FramePool

	// The size of receive channel buffers.  Defaults to 512
	RecvBufferSize int

	// The size of send channel buffers.  Defaults to 512
	SendBufferSize int

	// The type of checksum to use when sending messages
	ChecksumType ChecksumType
}

ConnectionOptions are options that control the behavior of a Connection

type ContextBuilder 

type ContextBuilder struct {
	// If Timeout is zero, Build will default to defaultTimeout.
	Timeout time.Duration

	// Headers are application headers that json/thrift will encode into arg2.
	Headers map[string]string

	// CallOptions are TChannel call options for the specific call.
	CallOptions *CallOptions
	// contains filtered or unexported fields
}

ContextBuilder stores all TChannel-specific parameters that will be stored inside of a context.

func NewContextBuilder 

func NewContextBuilder(timeout time.Duration) *ContextBuilder

NewContextBuilder returns a builder that can be used to create a Context.

func (*ContextBuilder) AddHeader 

func (cb *ContextBuilder) AddHeader(key, value string) *ContextBuilder

AddHeader adds a single application header to the Context.

func (*ContextBuilder) Build 

func (cb *ContextBuilder) Build() (ContextWithHeaders, context.CancelFunc)

Build returns a ContextWithHeaders that can be used to make calls.

func (*ContextBuilder) SetFormat 

func (cb *ContextBuilder) SetFormat(f Format) *ContextBuilder

SetFormat sets the Format call option ("as" transport header).

func (*ContextBuilder) SetHeaders 

func (cb *ContextBuilder) SetHeaders(headers map[string]string) *ContextBuilder

SetHeaders sets the application headers for this Context.

func (*ContextBuilder) SetIncomingCallForTest 

func (cb *ContextBuilder) SetIncomingCallForTest(call IncomingCall) *ContextBuilder

SetIncomingCallForTest sets an IncomingCall in the context. This should only be used in unit tests.

func (*ContextBuilder) SetShardKey 

func (cb *ContextBuilder) SetShardKey(sk string) *ContextBuilder

SetShardKey sets the ShardKey call option ("sk" transport header).

func (*ContextBuilder) SetSpanForTest 

func (cb *ContextBuilder) SetSpanForTest(span *Span) *ContextBuilder

SetSpanForTest sets a tracing span in the context. This should only be used in unit tests.

func (*ContextBuilder) SetTimeout 

func (cb *ContextBuilder) SetTimeout(timeout time.Duration) *ContextBuilder

SetTimeout sets the timeout for the Context.

type ContextWithHeaders 

type ContextWithHeaders interface {
	context.Context

	// Headers returns the call request headers.
	Headers() map[string]string

	// ResponseHeaders returns the call response headers.
	ResponseHeaders() map[string]string

	// SetResponseHeaders sets the given response headers on the context.
	SetResponseHeaders(map[string]string)
}

ContextWithHeaders is a Context which contains request and response headers.

func WrapWithHeaders 

func WrapWithHeaders(ctx context.Context, headers map[string]string) ContextWithHeaders

WrapWithHeaders returns a Context that can be used to make a call with request headers.

type Endpoint 

type Endpoint struct {
	Ipv4        string
	Port        int32
	ServiceName string
}

Endpoint represents Zipkin-style endpoint.

type Format 

type Format string

Format is the arg scheme used for a specific call. 

const (
	HTTP   Format = "http"
	JSON   Format = "json"
	Raw    Format = "raw"
	Thrift Format = "thrift"
)

The list of formats supported by tchannel.

func (Format) String 

func (f Format) String() string

type Frame 

type Frame struct {

	// The header for the frame
	Header FrameHeader

	// The payload for the frame
	Payload []byte
	// contains filtered or unexported fields
}

A Frame is a header and payload

func NewFrame 

func NewFrame(payloadCapacity int) *Frame

NewFrame allocates a new frame with the given payload capacity

func (*Frame) ReadIn 

func (f *Frame) ReadIn(r io.Reader) error

ReadIn reads the frame from the given io.Reader

func (*Frame) SizedPayload 

func (f *Frame) SizedPayload() []byte

SizedPayload returns the slice of the payload actually used, as defined by the header

func (*Frame) WriteOut 

func (f *Frame) WriteOut(w io.Writer) error

WriteOut writes the frame to the given io.Writer

type FrameHeader 

type FrameHeader struct {

	// The id of the message represented by the frame
	ID uint32
	// contains filtered or unexported fields
}

FrameHeader is the header for a frame, containing the MessageType and size

func (FrameHeader) FrameSize 

func (fh FrameHeader) FrameSize() uint16

FrameSize returns the total size of the frame

func (FrameHeader) PayloadSize 

func (fh FrameHeader) PayloadSize() uint16

PayloadSize returns the size of the frame payload

func (*FrameHeader) SetPayloadSize 

func (fh *FrameHeader) SetPayloadSize(size uint16)

SetPayloadSize sets the size of the frame payload

func (FrameHeader) String 

func (fh FrameHeader) String() string

type FramePool 

type FramePool interface {
	// Retrieves a new frame from the pool
	Get() *Frame

	// Releases a frame back to the pool
	Release(f *Frame)
}

A FramePool is a pool for managing and re-using frames

func NewChannelFramePool 

func NewChannelFramePool(capacity int) FramePool

NewChannelFramePool returns a frame pool backed by a channel that has a max capacity.

func NewSyncFramePool 

func NewSyncFramePool() FramePool

NewSyncFramePool returns a frame pool that uses a sync.Pool.

type Handler 

type Handler interface {
	// Handles an incoming call for service
	Handle(ctx context.Context, call *InboundCall)
}

A Handler is an object that can be registered with a Channel to process incoming calls for a given service and operation

type HandlerFunc 

type HandlerFunc func(ctx context.Context, call *InboundCall)

A HandlerFunc is an adapter to allow the use of ordering functions as Channel handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Hander object that calls f

func (HandlerFunc) Handle 

func (f HandlerFunc) Handle(ctx context.Context, call *InboundCall)

Handle calls f(ctx, call)

type InboundCall 

type InboundCall struct {
	Annotations
	// contains filtered or unexported fields
}

An InboundCall is an incoming call from a peer

func (*InboundCall) Arg2Reader 

func (call *InboundCall) Arg2Reader() (io.ReadCloser, error)

Arg2Reader returns an io.ReadCloser to read the second argument. The ReadCloser must be closed once the argument has been read.

func (*InboundCall) Arg3Reader 

func (call *InboundCall) Arg3Reader() (io.ReadCloser, error)

Arg3Reader returns an io.ReadCloser to read the last argument. The ReadCloser must be closed once the argument has been read.

func (*InboundCall) CallerName 

func (call *InboundCall) CallerName() string

CallerName returns the caller name from the CallerName transport header.

func (*InboundCall) Format 

func (call *InboundCall) Format() Format

Format the format of the request from the ArgScheme transport header.

func (*InboundCall) Operation 

func (call *InboundCall) Operation() []byte

Operation returns the operation being called

func (*InboundCall) Response 

func (call *InboundCall) Response() *InboundCallResponse

Response provides access to the InboundCallResponse object which can be used to write back to the calling peer

func (*InboundCall) ServiceName 

func (call *InboundCall) ServiceName() string

ServiceName returns the name of the service being called

func (*InboundCall) ShardKey 

func (call *InboundCall) ShardKey() string

ShardKey returns the shard key from the ShardKey transport header.

type InboundCallResponse 

type InboundCallResponse struct {
	// contains filtered or unexported fields
}

An InboundCallResponse is used to send the response back to the calling peer

func (*InboundCallResponse) Arg2Writer 

func (response *InboundCallResponse) Arg2Writer() (ArgWriter, error)

Arg2Writer returns a WriteCloser that can be used to write the second argument. The returned writer must be closed once the write is complete.

func (*InboundCallResponse) Arg3Writer 

func (response *InboundCallResponse) Arg3Writer() (ArgWriter, error)

Arg3Writer returns a WriteCloser that can be used to write the last argument. The returned writer must be closed once the write is complete.

func (*InboundCallResponse) SendSystemError 

func (response *InboundCallResponse) SendSystemError(err error) error

SendSystemError returns a system error response to the peer. The call is considered complete after this method is called, and no further data can be written.

func (*InboundCallResponse) SetApplicationError 

func (response *InboundCallResponse) SetApplicationError() error

SetApplicationError marks the response as being an application error. This method can only be called before any arguments have been sent to the calling peer.

type IncomingCall 

type IncomingCall interface {
	// CallerName returns the caller name from the CallerName transport header.
	CallerName() string

	// ShardKey returns the shard key from the ShardKey transport header.
	ShardKey() string
}

IncomingCall exposes properties for incoming calls through the context.

func CurrentCall 

func CurrentCall(ctx context.Context) IncomingCall

CurrentCall returns the current incoming call, or nil if this is not an incoming call context.

type LocalPeerInfo 

type LocalPeerInfo struct {
	PeerInfo

	// ServiceName is the service name for the local peer.
	ServiceName string
}

LocalPeerInfo adds service name to the peer info, only required for the local peer.

func (LocalPeerInfo) String 

func (p LocalPeerInfo) String() string

type LogField 

type LogField struct {
	Key   string
	Value interface{}
}

LogField is a single field of additional information passed to the logger.

type LogFields 

type LogFields []LogField

LogFields is a list of LogFields used to pass additional information to the logger.

type LogLevel 

type LogLevel int

LogLevel is the level of logging used by LevelLogger. 

const (
	LogLevelAll LogLevel = iota
	LogLevelDebug
	LogLevelInfo
	LogLevelWarn
	LogLevelError
	LogLevelFatal
)

The minimum level that will be logged. e.g. LogLevelError only logs errors and fatals.

type Logger 

type Logger interface {
	// Fatalf logs a message, then exits with os.Exit(1)
	Fatalf(msg string, args ...interface{})

	// Errorf logs a message at error priority
	Errorf(msg string, args ...interface{})

	// Warnf logs a message at warning priority
	Warnf(msg string, args ...interface{})

	// Infof logs a message at info priority
	Infof(msg string, args ...interface{})

	// Debugf logs a message at debug priority
	Debugf(msg string, args ...interface{})

	// Fields returns the fields that this logger contains.
	Fields() LogFields

	// WithFields returns a logger with the current logger's fields and fields.
	WithFields(fields ...LogField) Logger
}

Logger provides an abstract interface for logging from TChannel. Applications can provide their own implementation of this interface to adapt TChannel logging to whatever logging library they prefer (stdlib log, logrus, go-logging, etc). The SimpleLogger adapts to the standard go log package. 

var NullLogger Logger = nullLogger{}

NullLogger is a logger that emits nowhere

func NewLevelLogger 

func NewLevelLogger(logger Logger, level LogLevel) Logger

NewLevelLogger returns a logger that only logs messages with a minimum of level.

func NewLogger 

func NewLogger(writer io.Writer, fields ...LogField) Logger

NewLogger returns a Logger that writes to the given writer.

type OutboundCall 

type OutboundCall struct {
	Annotations
	// contains filtered or unexported fields
}

An OutboundCall is an active call to a remote peer. A client makes a call by calling BeginCall on the Channel, writing argument content via ArgWriter2() ArgWriter3(), and then reading reading response data via the ArgReader2() and ArgReader3() methods on the Response() object.

func (*OutboundCall) Arg2Writer 

func (call *OutboundCall) Arg2Writer() (ArgWriter, error)

Arg2Writer returns a WriteCloser that can be used to write the second argument. The returned writer must be closed once the write is complete.

func (*OutboundCall) Arg3Writer 

func (call *OutboundCall) Arg3Writer() (ArgWriter, error)

Arg3Writer returns a WriteCloser that can be used to write the last argument. The returned writer must be closed once the write is complete.

func (*OutboundCall) Response 

func (call *OutboundCall) Response() *OutboundCallResponse

Response provides access to the call's response object, which can be used to read response arguments

type OutboundCallResponse 

type OutboundCallResponse struct {
	// contains filtered or unexported fields
}

An OutboundCallResponse is the response to an outbound call

func (*OutboundCallResponse) ApplicationError 

func (response *OutboundCallResponse) ApplicationError() bool

ApplicationError returns true if the call resulted in an application level error TODO(mmihic): In current implementation, you must have called Arg2Reader before this method returns the proper value. We should instead have this block until the first fragment is available, if the first fragment hasn't been received.

func (*OutboundCallResponse) Arg2Reader 

func (response *OutboundCallResponse) Arg2Reader() (io.ReadCloser, error)

Arg2Reader returns an io.ReadCloser to read the second argument. The ReadCloser must be closed once the argument has been read.

func (*OutboundCallResponse) Arg3Reader 

func (response *OutboundCallResponse) Arg3Reader() (io.ReadCloser, error)

Arg3Reader returns an io.ReadCloser to read the last argument. The ReadCloser must be closed once the argument has been read.

func (*OutboundCallResponse) Format 

func (response *OutboundCallResponse) Format() Format

Format the format of the request from the ArgScheme transport header.

type Peer 

type Peer struct {
	// contains filtered or unexported fields
}

Peer represents a single autobahn service or client with a unique host:port.

func (*Peer) AddConnection 

func (p *Peer) AddConnection(c *Connection) error

AddConnection adds an active connection to the peer's connection list. If a connection is not active, ErrInvalidConnectionState will be returned.

func (*Peer) BeginCall 

func (p *Peer) BeginCall(ctx context.Context, serviceName string, operationName string, callOptions *CallOptions) (*OutboundCall, error)

BeginCall starts a new call to this specific peer, returning an OutboundCall that can be used to write the arguments of the call.

func (*Peer) Close 

func (p *Peer) Close()

Close closes all connections to this peer.

func (*Peer) Connect 

func (p *Peer) Connect(ctx context.Context) (*Connection, error)

Connect adds a new outbound connection to the peer.

func (*Peer) GetConnection 

func (p *Peer) GetConnection(ctx context.Context) (*Connection, error)

GetConnection returns an active connection to this peer. If no active connections are found, it will create a new outbound connection and return it.

func (*Peer) HostPort 

func (p *Peer) HostPort() string

HostPort returns the host:port used to connect to this peer.

type PeerInfo 

type PeerInfo struct {
	// The host and port that can be used to contact the peer, as encoded by net.JoinHostPort
	HostPort string

	// The logical process name for the peer, used for only for logging / debugging
	ProcessName string
}

PeerInfo contains information about a TChannel peer

func (PeerInfo) IsEphemeral 

func (p PeerInfo) IsEphemeral() bool

IsEphemeral returns if hostPort is the default ephemeral hostPort.

func (PeerInfo) String 

func (p PeerInfo) String() string

type PeerList 

type PeerList struct {
	// contains filtered or unexported fields
}

PeerList maintains a list of Peers.

func (*PeerList) Add 

func (l *PeerList) Add(hostPort string) *Peer

Add adds a peer to the list if it does not exist, or returns any existing peer.

func (*PeerList) Close 

func (l *PeerList) Close()

Close closes connections for all peers.

func (*PeerList) Copy 

func (l *PeerList) Copy() map[string]*Peer

Copy returns a copy of the peer list. This method should only be used for testing.

func (*PeerList) Get 

func (l *PeerList) Get() *Peer

Get returns a peer from the peer list, or nil if none can be found.

func (*PeerList) GetOrAdd 

func (l *PeerList) GetOrAdd(hostPort string) *Peer

GetOrAdd returns a peer for the given hostPort, creating one if it doesn't yet exist.

type Registrar 

type Registrar interface {
	// ServiceName returns the service name that this Registrar is for.
	ServiceName() string

	// Register registers a handler for ServiceName and the given operation.
	Register(h Handler, operationName string)

	// Logger returns the logger for this Registrar.
	Logger() Logger

	// Peers returns the peer list for this Registrar.
	Peers() *PeerList
}

Registrar is the base interface for registering handlers on either the base Channel or the SubChannel

type ResponseCode 

type ResponseCode byte

ResponseCode to a CallReq

type Span 

type Span struct {
	// contains filtered or unexported fields
}

Span represents Zipkin-style span.

func CurrentSpan 

func CurrentSpan(ctx context.Context) *Span

CurrentSpan returns the Span value for the provided Context

func NewRootSpan 

func NewRootSpan() *Span

NewRootSpan creates a new top-level Span for a call-graph within the provided context

func (*Span) EnableTracing 

func (s *Span) EnableTracing(enabled bool)

EnableTracing controls whether tracing is enabled for this context

func (Span) NewChildSpan 

func (s Span) NewChildSpan() *Span

NewChildSpan begins a new child span in the provided Context

func (Span) ParentID 

func (s Span) ParentID() uint64

ParentID returns the id of the parent span in this call graph

func (Span) SpanID 

func (s Span) SpanID() uint64

SpanID returns the id of this specific RPC

func (Span) String 

func (s Span) String() string

func (Span) TraceID 

func (s Span) TraceID() uint64

TraceID returns the trace id for the entire call graph of requests. Established at the outermost edge service and propagated through all calls

func (Span) TracingEnabled 

func (s Span) TracingEnabled() bool

TracingEnabled checks whether tracing is enabled for this context

type StatsReporter 

type StatsReporter interface {
	IncCounter(name string, tags map[string]string, value int64)
	UpdateGauge(name string, tags map[string]string, value int64)
	RecordTimer(name string, tags map[string]string, d time.Duration)
}

StatsReporter is the the interface used to report stats. 

var NullStatsReporter StatsReporter = nullStatsReporter{}

NullStatsReporter is a stats reporter that discards the statistics. 

var SimpleStatsReporter StatsReporter = simpleStatsReporter{}

SimpleStatsReporter is a stats reporter that reports stats to the log.

type SubChannel 

type SubChannel struct {
	// contains filtered or unexported fields
}

SubChannel allows calling a specific service on a channel. TODO(prashant): Allow creating a subchannel with default call options. TODO(prashant): Allow registering handlers on a subchannel.

func (*SubChannel) BeginCall 

func (c *SubChannel) BeginCall(ctx context.Context, operationName string, callOptions *CallOptions) (*OutboundCall, error)

BeginCall starts a new call to a remote peer, returning an OutboundCall that can be used to write the arguments of the call.

func (*SubChannel) Logger 

func (c *SubChannel) Logger() Logger

Logger returns the logger for this subchannel.

func (*SubChannel) Peers 

func (c *SubChannel) Peers() *PeerList

Peers returns the PeerList for this subchannel.

func (*SubChannel) Register 

func (c *SubChannel) Register(h Handler, operationName string)

Register registers a handler on the subchannel for a service+operation pair

func (*SubChannel) ServiceName 

func (c *SubChannel) ServiceName() string

ServiceName returns the service name that this subchannel is for.

type SystemErrCode 

type SystemErrCode byte

A SystemErrCode indicates how a caller should handle a system error returned from a peer 

const (
	// ErrCodeInvalid is an invalid error code, and should not be used
	ErrCodeInvalid SystemErrCode = 0x00

	// ErrCodeTimeout indicates the peer timed out.  Callers can retry the request
	// on another peer if the request is safe to retry.
	ErrCodeTimeout SystemErrCode = 0x01

	// ErrCodeCancelled indicates that the request was cancelled on the peer.  Callers
	// can retry the request on the same or another peer if the request is safe to retry
	ErrCodeCancelled SystemErrCode = 0x02

	// ErrCodeBusy indicates that the request was not dispatched because the peer
	// was too busy to handle it.  Callers can retry the request on another peer, and should
	// reweight their connections to direct less traffic to this peer until it recovers.
	ErrCodeBusy SystemErrCode = 0x03

	// 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.
	// Callers can retry the request on another peer, but should not reweight their connections
	// and should continue to send traffic to this peer.
	ErrCodeDeclined SystemErrCode = 0x04

	// ErrCodeUnexpected indicates that the request failed for an unexpected reason, typically
	// a crash or other unexpected handling.  The request may have been processed before the failure;
	// callers should retry the request on this or another peer only if the request is safe to retry
	ErrCodeUnexpected SystemErrCode = 0x05

	// ErrCodeBadRequest indicates that the request was malformed, and could not be processed.
	// Callers should not bother to retry the request, as there is no chance it will be handled.
	ErrCodeBadRequest SystemErrCode = 0x06

	// ErrCodeNetwork indicates a network level error, such as a connection reset.
	// Callers can retry the request if the request is safe to retry
	ErrCodeNetwork SystemErrCode = 0x07

	// ErrCodeProtocol indincates a fatal protocol error communicating with the peer.  The connection
	// will be terminated.
	ErrCodeProtocol SystemErrCode = 0xFF
)

func GetSystemErrorCode 

func GetSystemErrorCode(err error) SystemErrCode

GetSystemErrorCode returns the code to report for the given error. If the error is a SystemError, we can get the code directly. Otherwise treat it as an unexpected error

type SystemError 

type SystemError struct {
	// contains filtered or unexported fields
}

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.

func (SystemError) Code 

func (se SystemError) Code() SystemErrCode

Code returns the SystemError code, for sending to a peer

func (SystemError) Error 

func (se SystemError) Error() string

Error returns the SystemError message, conforming to the error interface

func (SystemError) Wrapped 

func (se SystemError) Wrapped() error

Wrapped returns the wrapped error

type TraceReporter 

type TraceReporter interface {
	// Report method is intended to report Span information.
	// It returns any error encountered otherwise nil.
	Report(span Span, annotations []Annotation, binaryAnnotations []BinaryAnnotation) error
}

TraceReporter is the interface used to report Trace spans. 

var NullReporter TraceReporter = nullReporter{}

NullReporter is the default TraceReporter which does not do anything. 

var SimpleTraceReporter TraceReporter = simpleTraceReporter{}

SimpleTraceReporter is a trace reporter which prints using the default logger.

type TraceReporterFactory 

type TraceReporterFactory func(*Channel) TraceReporter

TraceReporterFactory is the interface of the method to generate TraceReporter instance.

type TransportHeaderName 

type TransportHeaderName string

TransportHeaderName is a type for transport header names. 

const (
	// ArgScheme header specifies the format of the args.
	ArgScheme TransportHeaderName = "as"

	// CallerName header specifies the name of the service making the call.
	CallerName TransportHeaderName = "cn"

	// ClaimAtFinish header value is host:port specifying the instance to send a claim message
	// to when response is being sent.
	ClaimAtFinish TransportHeaderName = "caf"

	// ClaimAtStart header value is host:port specifying another instance to send a claim message
	// to when work is started.
	ClaimAtStart TransportHeaderName = "cas"

	// 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.
	FailureDomain TransportHeaderName = "fd"

	// ShardKey header value is used by ringpop to deliver calls to a specific tchannel instance.
	ShardKey TransportHeaderName = "sk"

	// RetryFlags header specifies whether retry policies.
	RetryFlags TransportHeaderName = "re"

	// SpeculativeExecution header specifies the number of nodes on which to run the request.
	SpeculativeExecution TransportHeaderName = "se"
)

Known transport header keys for call requests. See protocol docs for more information.

func (TransportHeaderName) String 

func (cn TransportHeaderName) String() string

Source Files

View all Source files

Directories

Path Synopsis
examples
bench
bench/client
bench/server
hyperbahn/echo-server
hypercat
keyvalue/client
keyvalue/gen-go/keyvalue
Autogenerated by thrift-gen.
 Autogenerated by thrift-gen.
keyvalue/server
ping
test_server
thrift
thrift/gen-go/test
Autogenerated by thrift-gen.
 Autogenerated by thrift-gen.
Package thrift adds support to use Thrift services over TChannel.
 Package thrift adds support to use Thrift services over TChannel.
gen-go/test
Autogenerated by thrift-gen.
 Autogenerated by thrift-gen.
mocks
thrift-gen
thrift-gen generates code for Thrift services that can be used with the uber/tchannel/thrift package.
 thrift-gen generates code for Thrift services that can be used with the uber/tchannel/thrift package.
Package trace provides methods to submit Zipkin style Span to tcollector Server.
 Package trace provides methods to submit Zipkin style Span to tcollector Server.
thrift/gen-go/tcollector
Autogenerated by thrift-gen.
 Autogenerated by thrift-gen.
thrift/mocks

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.