tchannel

package module
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2018 License: MIT Imports: 37 Imported by: 0

README

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).

Documentation

Overview

Package tchannel implements Go bindings for the TChannel protocol (https://github.com/uber/tchannel).

A single Channel can be used for many concurrent requests to many hosts.

Index

Constants

View Source 
const (
	// CurrentProtocolVersion is the current version of the TChannel protocol
	// supported by this stack
	CurrentProtocolVersion = 0x02

	// DefaultConnectTimeout is the default timeout used by net.Dial, if no timeout
	// is specified in the context.
	DefaultConnectTimeout = 5 * time.Second
)
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"
	// InitParamTChannelLanguage contains the library language.
	InitParamTChannelLanguage = "tchannel_language"
	// InitParamTChannelLanguageVersion contains the language build/runtime version.
	InitParamTChannelLanguageVersion = "tchannel_language_version"
	// InitParamTChannelVersion contains the library version.
	InitParamTChannelVersion = "tchannel_version"
)
View Source 
const VersionInfo = "1.11.0"

VersionInfo identifies the version of the TChannel library. Due to lack of proper package management, this version string will be maintained manually.

Variables

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

	// 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")

	// ErrConnectionNotReady is no longer used.
	ErrConnectionNotReady = errors.New("connection is not yet ready")
)
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")

	// ErrMethodTooLarge is a SystemError indicating that the method is too large.
	ErrMethodTooLarge = NewSystemError(ErrCodeProtocol, "method too large")
)
View Source 
var (
	// ErrInvalidConnectionState indicates that the connection is not in a valid state.
	// This may be due to a race between selecting the connection and it closing, so
	// it is a network failure that can be retried.
	ErrInvalidConnectionState = NewSystemError(ErrCodeNetwork, "connection is in an invalid state")

	// ErrNoPeers indicates that there are no peers.
	ErrNoPeers = errors.New("no peers available")

	// ErrPeerNotFound indicates that the specified peer was not found.
	ErrPeerNotFound = errors.New("peer not found")

	// ErrNoNewPeers indicates that no previously unselected peer is available.
	ErrNoNewPeers = errors.New("no new peer available")
)
View Source 
var DefaultFramePool = NewSyncFramePool()

DefaultFramePool uses the SyncFramePool.

View Source 
var DisabledFramePool = disabledFramePool{}

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

View Source 
var (

	// ErrNoServiceName is returned when no service name is provided when
	// creating a new channel.
	ErrNoServiceName = errors.New("no service name provided")
)
View Source 
var SimpleLogger = NewLogger(os.Stdout)

SimpleLogger prints logging information to standard out.

Functions

func ExtractInboundSpan added in v1.1.0 

func ExtractInboundSpan(ctx context.Context, call *InboundCall, headers map[string]string, tracer opentracing.Tracer) context.Context

ExtractInboundSpan is a higher level version of extractInboundSpan(). If the lower-level attempt to create a span from incoming request was successful (e.g. when then Tracer supports Zipkin-style trace IDs), then the application headers are only used to read the Baggage and add it to the existing span. Otherwise, the standard OpenTracing API supported by all tracers is used to deserialize the tracing context from the application headers and start a new server-side span. Once the span is started, it is wrapped in a new Context, which is returned.

func GetContextError 

func GetContextError(err error) error

GetContextError converts the context error to a tchannel error.

func GetSystemErrorMessage 

func GetSystemErrorMessage(err error) string

GetSystemErrorMessage returns the message to report for the given error. If the error is a SystemError, we can get the underlying message. Otherwise, use the Error() method.

func InjectOutboundSpan added in v1.1.0 

func InjectOutboundSpan(response *OutboundCallResponse, headers map[string]string) map[string]string

InjectOutboundSpan retrieves OpenTracing Span from `response`, where it is stored when the outbound call is initiated. The tracing API is used to serialize the span into the application `headers`, which will propagate tracing context to the server. Returns modified headers containing serialized tracing context.

Sometimes caller pass a shared instance of the `headers` map, so instead of modifying it we clone it into the new map (assuming that Tracer actually injects some tracing keys).

func Isolated 

func Isolated(s *SubChannel)

Isolated is a SubChannelOption that creates an isolated subchannel.

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 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 TracerFromRegistrar added in v1.1.0 

func TracerFromRegistrar(registrar Registrar) opentracing.Tracer

TracerFromRegistrar returns an OpenTracing Tracer embedded in the Registrar, assuming that Registrar has a Tracer() method. Otherwise it returns default Global Tracer.

func WithoutHeaders added in v1.7.0 

func WithoutHeaders(ctx context.Context) context.Context

WithoutHeaders hides any TChannel headers from the given context.

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 ArgReadHelper 

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

ArgReadHelper providers a simpler interface to reading arguments.

func NewArgReader 

func NewArgReader(reader ArgReader, 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 ArgReadable added in v1.0.1 

type ArgReadable interface {
	Arg2Reader() (ArgReader, error)
	Arg3Reader() (ArgReader, error)
}

ArgReadable is an interface for providing arg2 and arg3 reader streams; implemented by reqResReader e.g. InboundCall and OutboundCallResponse.

type ArgReader added in v1.0.1 

type ArgReader io.ReadCloser

ArgReader is the interface for the arg2 and arg3 streams on an OutboundCallResponse and an InboundCall

type ArgWritable added in v1.0.1 

type ArgWritable interface {
	Arg2Writer() (ArgWriter, error)
	Arg3Writer() (ArgWriter, error)
}

ArgWritable is an interface for providing arg2 and arg3 writer streams; implemented by reqResWriter e.g. OutboundCall and InboundCallResponse

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 for the arg2 and arg3 streams on an OutboundCall and an InboundCallResponse

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

	// RequestState stores request state across retry attempts.
	RequestState *RequestState

	// RoutingKey identifies the destined traffic group. Relays may favor the
	// routing key over the service name to route the request to a specialized
	// traffic group.
	RoutingKey string

	// RoutingDelegate identifies a traffic group capable of routing a request
	// to an instance of the intended service.
	RoutingDelegate string
	// contains filtered or unexported fields
}

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, methodName 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 drained, the connection blocks new outgoing calls. 3. When all connections are drained, 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) (*Connection, error)

Connect creates a new outbound connection to hostPort.

func (*Channel) ConnectionOptions 

func (ch *Channel) ConnectionOptions() *ConnectionOptions

ConnectionOptions returns the channel's connection options.

func (*Channel) GetSubChannel 

func (ch *Channel) GetSubChannel(serviceName string, opts ...SubChannelOption) *SubChannel

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

func (*Channel) IntrospectNumConnections added in v1.0.9 

func (ch *Channel) IntrospectNumConnections() int

IntrospectNumConnections returns the number of connections returns the number of connections. Note: like other introspection APIs, this is not a stable API.

func (*Channel) IntrospectOthers added in v1.0.3 

func (ch *Channel) IntrospectOthers(opts *IntrospectionOptions) map[string][]ChannelInfo

IntrospectOthers returns the ChannelInfo for all other channels in this process.

func (*Channel) IntrospectState 

func (ch *Channel) IntrospectState(opts *IntrospectionOptions) *RuntimeState

IntrospectState returns the RuntimeState for this channel. Note: this is purely for debugging and monitoring, and may slow down your Channel.

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, methodName string)

Register registers a handler for a method.

The handler is registered with the service name used when the Channel was created. To register a handler with a different service name, obtain a SubChannel for that service with GetSubChannel, and Register a handler under that. You may also use SetHandler on a SubChannel to set up a catch-all Handler for that service. See the docs for SetHandler for more information.

Register panics if the channel was constructed with an alternate root handler.

func (*Channel) RelayHost added in v1.2.2 

func (ch *Channel) RelayHost() RelayHost

RelayHost returns the channel's RelayHost, if any.

func (*Channel) ReportInfo added in v1.0.3 

func (ch *Channel) ReportInfo(opts *IntrospectionOptions) ChannelInfo

ReportInfo returns ChannelInfo for a channel.

func (*Channel) RootPeers added in v1.3.0 

func (ch *Channel) RootPeers() *RootPeerList

RootPeers returns the root PeerList for the channel, which is the sole place new Peers are created. All children of the root list (including ch.Peers()) automatically re-use peers from the root list and create new peers in the root list.

func (*Channel) RunWithRetry 

func (ch *Channel) RunWithRetry(runCtx context.Context, f RetriableFunc) error

RunWithRetry will take a function that makes the TChannel call, and will rerun it as specifed in the RetryOptions in the Context.

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.

func (*Channel) StatsReporter 

func (ch *Channel) StatsReporter() StatsReporter

StatsReporter returns the stats reporter for this channel.

func (*Channel) StatsTags 

func (ch *Channel) StatsTags() map[string]string

StatsTags returns the common tags that should be used when reporting stats. It returns a new map for each call.

func (Channel) Tracer added in v1.1.0 

func (ccc Channel) Tracer() opentracing.Tracer

Tracer returns the OpenTracing Tracer for this channel. If no tracer was provided in the configuration, returns opentracing.GlobalTracer(). Note that this approach allows opentracing.GlobalTracer() to be initialized _after_ the channel is created.

type ChannelInfo added in v1.0.3 

type ChannelInfo struct {
	ID           uint32        `json:"id"`
	CreatedStack string        `json:"createdStack"`
	LocalPeer    LocalPeerInfo `json:"localPeer"`
}

ChannelInfo is the state of other channels in the same process.

type ChannelOptions 

type ChannelOptions struct {
	// Default Connection options
	DefaultConnectionOptions ConnectionOptions

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

	// OnPeerStatusChanged is an optional callback that receives a notification
	// whenever the channel establishes a usable connection to a peer, or loses
	// a connection to a peer.
	OnPeerStatusChanged func(*Peer)

	// The logger to use for this channel
	Logger Logger

	// The host:port selection implementation to use for relaying. This is an
	// unstable API - breaking changes are likely.
	RelayHost RelayHost

	// The list of service names that should be handled locally by this channel.
	// This is an unstable API - breaking changes are likely.
	RelayLocalHandlers []string

	// The maximum allowable timeout for relayed calls (longer timeouts are
	// clamped to this value). Passing zero uses the default of 2m.
	// This is an unstable API - breaking changes are likely.
	RelayMaxTimeout time.Duration

	// RelayTimerVerification will disable pooling of relay timers, and instead
	// verify that timers are not used once they are released.
	// This is an unstable API - breaking changes are likely.
	RelayTimerVerification bool

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

	// TimeNow is a variable for overriding time.Now in unit tests.
	// Note: This is not a stable part of the API and may change.
	TimeNow func() time.Time

	// TimeTicker is a variable for overriding time.Ticker in unit tests.
	// Note: This is not a stable part of the API and may change.
	TimeTicker func(d time.Duration) *time.Ticker

	// MaxIdleTime controls how long we allow an idle connection to exist
	// before tearing it down. Must be set to non-zero if IdleCheckInterval
	// is set.
	MaxIdleTime time.Duration

	// IdleCheckInterval controls how often the channel runs a sweep over
	// all active connections to see if they can be dropped. Connections that
	// are idle for longer than MaxIdleTime are disconnected. If this is set to
	// zero (the default), idle checking is disabled.
	IdleCheckInterval time.Duration

	// Tracer is an OpenTracing Tracer used to manage distributed tracing spans.
	// If not set, opentracing.GlobalTracer() is used.
	Tracer opentracing.Tracer

	// Handler is an alternate handler for all inbound requests, overriding the
	// default handler that delegates to a subchannel.
	Handler Handler
}

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

	// Release puts a Checksum back in the pool.
	Release()

	// Reset resets the checksum state to the default 0 value.
	Reset()
}

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

func (ChecksumType) Release 

func (t ChecksumType) Release(checksum Checksum)

Release puts a Checksum back in the pool.

type Connectable 

type Connectable interface {
	// Connect tries to connect to the given hostPort.
	Connect(ctx context.Context, hostPort string) (*Connection, error)
	// Logger returns the logger to use.
	Logger() Logger
}

Connectable is the interface used by peers to create connections.

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) IntrospectState 

func (c *Connection) IntrospectState(opts *IntrospectionOptions) ConnectionRuntimeState

IntrospectState returns the runtime state for this connection.

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) RemotePeerInfo 

func (c *Connection) RemotePeerInfo() PeerInfo

RemotePeerInfo returns the peer info for the remote peer.

func (*Connection) SendSystemError 

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

SendSystemError sends an error frame for the given system error.

func (Connection) Tracer added in v1.1.0 

func (ccc Connection) Tracer() opentracing.Tracer

Tracer returns the OpenTracing Tracer for this channel. If no tracer was provided in the configuration, returns opentracing.GlobalTracer(). Note that this approach allows opentracing.GlobalTracer() to be initialized _after_ the channel is created.

type ConnectionOptions 

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

	// NOTE: This is deprecated and not used for anything.
	RecvBufferSize int

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

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

	// ToS class name marked on outbound packets.
	TosPriority tos.ToS

	// HealthChecks configures active connection health checking for this channel.
	// By default, health checks are not enabled.
	HealthChecks HealthCheckOptions
}

ConnectionOptions are options that control the behavior of a Connection

type ConnectionRuntimeState 

type ConnectionRuntimeState struct {
	ID               uint32                  `json:"id"`
	ConnectionState  string                  `json:"connectionState"`
	LocalHostPort    string                  `json:"localHostPort"`
	RemoteHostPort   string                  `json:"remoteHostPort"`
	OutboundHostPort string                  `json:"outboundHostPort"`
	RemotePeer       PeerInfo                `json:"remotePeer"`
	InboundExchange  ExchangeSetRuntimeState `json:"inboundExchange"`
	OutboundExchange ExchangeSetRuntimeState `json:"outboundExchange"`
	Relayer          RelayerRuntimeState     `json:"relayer"`
	HealthChecks     []bool                  `json:"healthChecks,omitempty"`
	LastActivity     int64                   `json:"lastActivity"`
}

ConnectionRuntimeState is the runtime state for a single connection.

type ContextBuilder 

type ContextBuilder struct {
	// TracingDisabled disables trace reporting for calls using this context.
	TracingDisabled bool

	// 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

	// RetryOptions are the retry options for this call.
	RetryOptions *RetryOptions

	// ConnectTimeout is the timeout for creating a TChannel connection.
	ConnectTimeout time.Duration

	// ParentContext to build the new context from. If empty, context.Background() is used.
	// The new (child) context inherits a number of properties from the parent context:
	//   - context fields, accessible via `ctx.Value(key)`
	//   - headers if parent is a ContextWithHeaders, unless replaced via SetHeaders()
	ParentContext context.Context
	// 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) DisableTracing 

func (cb *ContextBuilder) DisableTracing() *ContextBuilder

DisableTracing disables tracing.

func (*ContextBuilder) HideListeningOnOutbound added in v1.0.8 

func (cb *ContextBuilder) HideListeningOnOutbound() *ContextBuilder

HideListeningOnOutbound hides the host:port when creating new outbound connections.

func (*ContextBuilder) SetConnectTimeout added in v1.0.8 

func (cb *ContextBuilder) SetConnectTimeout(d time.Duration) *ContextBuilder

SetConnectTimeout sets the ConnectionTimeout for this context. The context timeout applies to the whole call, while the connect timeout only applies to creating a new connection.

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. If there is a ParentContext, its headers will be ignored after the call to this method.

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) SetParentContext added in v1.0.5 

func (cb *ContextBuilder) SetParentContext(ctx context.Context) *ContextBuilder

SetParentContext sets the parent for the Context.

func (*ContextBuilder) SetRetryOptions 

func (cb *ContextBuilder) SetRetryOptions(retryOptions *RetryOptions) *ContextBuilder

SetRetryOptions sets RetryOptions in the context.

func (*ContextBuilder) SetRoutingDelegate added in v1.0.2 

func (cb *ContextBuilder) SetRoutingDelegate(rd string) *ContextBuilder

SetRoutingDelegate sets the RoutingDelegate call options ("rd" transport header).

func (*ContextBuilder) SetRoutingKey added in v1.2.0 

func (cb *ContextBuilder) SetRoutingKey(rk string) *ContextBuilder

SetRoutingKey sets the RoutingKey call options ("rk" transport header).

func (*ContextBuilder) SetShardKey 

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

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

func (*ContextBuilder) SetTimeout 

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

SetTimeout sets the timeout for the Context.

func (*ContextBuilder) SetTimeoutPerAttempt 

func (cb *ContextBuilder) SetTimeoutPerAttempt(timeoutPerAttempt time.Duration) *ContextBuilder

SetTimeoutPerAttempt sets TimeoutPerAttempt in RetryOptions.

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)

	// Child creates a child context which stores headers separately from
	// the parent context.
	Child() ContextWithHeaders
}

ContextWithHeaders is a Context which contains request and response headers.

func Wrap added in v1.2.2 

func Wrap(ctx context.Context) ContextWithHeaders

Wrap wraps an existing context.Context into a ContextWithHeaders. If the underlying context has headers, they are preserved.

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. If the parent `ctx` is already an instance of ContextWithHeaders, its existing headers will be ignored. In order to merge new headers with parent headers, use ContextBuilder.

type ErrorHandlerFunc added in v1.0.1 

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

An ErrorHandlerFunc is an adapter to allow the use of ordinary functions as Channel handlers, with error handling convenience. If f is a function with the appropriate signature, then ErrorHandlerFunc(f) is a Handler object that calls f.

func (ErrorHandlerFunc) Handle added in v1.0.1 

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

Handle calls f(ctx, call)

type ExchangeRuntimeState 

type ExchangeRuntimeState struct {
	ID          uint32      `json:"id"`
	MessageType messageType `json:"messageType"`
}

ExchangeRuntimeState is the runtime state for a single message exchange.

type ExchangeSetRuntimeState 

type ExchangeSetRuntimeState struct {
	Name      string                          `json:"name"`
	Count     int                             `json:"count"`
	Exchanges map[string]ExchangeRuntimeState `json:"exchanges,omitempty"`
}

ExchangeSetRuntimeState is the runtime state for a message exchange set.

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) ReadBody added in v1.8.0 

func (f *Frame) ReadBody(header []byte, r io.Reader) error

ReadBody takes in a previously read frame header, and only reads in the body based on the size specified in the header. This allows callers to defer the frame allocation till the body needs to be read.

func (*Frame) ReadIn 

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

ReadIn reads the frame from the given io.Reader. Deprecated: Only maintained for backwards compatibility. Callers should use ReadBody instead.

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) MarshalJSON 

func (fh FrameHeader) MarshalJSON() ([]byte, error)

MarshalJSON returns a `{"id":NNN, "msgType":MMM, "size":SSS}` representation

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 GoRuntimeState 

type GoRuntimeState struct {
	MemStats      runtime.MemStats `json:"memStats"`
	NumGoroutines int              `json:"numGoRoutines"`
	NumCPU        int              `json:"numCPU"`
	NumCGo        int64            `json:"numCGo"`
	GoStacks      []byte           `json:"goStacks,omitempty"`
}

GoRuntimeState is a snapshot of runtime stats from the runtime.

type GoRuntimeStateOptions 

type GoRuntimeStateOptions struct {
	// IncludeGoStacks will include all goroutine stacks.
	IncludeGoStacks bool `json:"includeGoStacks"`
}

GoRuntimeStateOptions are the options used when getting Go runtime state.

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 method

type HandlerFunc 

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

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

func (HandlerFunc) Handle 

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

Handle calls f(ctx, call)

type HandlerRuntimeState added in v1.0.4 

type HandlerRuntimeState struct {
	Type    handlerType `json:"type"`
	Methods []string    `json:"methods,omitempty"`
}

HandlerRuntimeState TODO

type HealthCheckOptions added in v1.8.0 

type HealthCheckOptions struct {
	// The period between health checks. If this is zeor, active health checks
	// are disabled.
	Interval time.Duration

	// The timeout to use for a health check.
	// If no value is specified, it defaults to time.Second.
	Timeout time.Duration

	// FailuresToClose is the number of consecutive health check failures that
	// will cause this connection to be closed.
	// If no value is specified, it defaults to 5.
	FailuresToClose int
}

HealthCheckOptions are the parameters to configure active TChannel health checks. These are not intended to check application level health, but TCP connection health (similar to TCP keep-alives). The health checks use TChannel ping messages.

type InboundCall 

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

An InboundCall is an incoming call from a peer

func (*InboundCall) Arg2Reader 

func (call *InboundCall) Arg2Reader() (ArgReader, error)

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

func (*InboundCall) Arg3Reader 

func (call *InboundCall) Arg3Reader() (ArgReader, error)

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

func (*InboundCall) CallOptions added in v1.0.8 

func (call *InboundCall) CallOptions() *CallOptions

CallOptions returns a CallOptions struct suitable for forwarding a request.

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) LocalPeer added in v1.2.2 

func (call *InboundCall) LocalPeer() LocalPeerInfo

LocalPeer returns the local peer information for this call.

func (*InboundCall) Method 

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

Method returns the method being called

func (*InboundCall) MethodString 

func (call *InboundCall) MethodString() string

MethodString returns the method being called as a string.

func (*InboundCall) RemotePeer 

func (call *InboundCall) RemotePeer() PeerInfo

RemotePeer returns the remote peer information for this call.

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) RoutingDelegate added in v1.0.2 

func (call *InboundCall) RoutingDelegate() string

RoutingDelegate returns the routing delegate from the RoutingDelegate transport header.

func (*InboundCall) RoutingKey added in v1.2.0 

func (call *InboundCall) RoutingKey() string

RoutingKey returns the routing key from the RoutingKey transport header.

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) Blackhole added in v1.10.0 

func (response *InboundCallResponse) Blackhole()

Blackhole indicates no response will be sent, and cleans up any resources associated with this request. This allows for services to trigger a timeout in clients without holding on to any goroutines on the server.

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

	// RoutingKey returns the routing key (referring to a traffic group) from
	// RoutingKey transport header.
	RoutingKey() string

	// RoutingDelegate returns the routing delegate from RoutingDelegate
	// transport header.
	RoutingDelegate() string

	// LocalPeer returns the local peer information.
	LocalPeer() LocalPeerInfo

	// RemotePeer returns the caller's peer information.
	// If the caller is an ephemeral peer, then the HostPort cannot be used to make new
	// connections to the caller.
	RemotePeer() PeerInfo

	// CallOptions returns the call options set for the incoming call. It can be useful
	// if you are forwarding a request and wish to retain the CallerName(), which is not
	// possible to set manually.
	CallOptions() *CallOptions
}

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 IntrospectionOptions 

type IntrospectionOptions struct {
	// IncludeExchanges will include all the IDs in the message exchanges.
	IncludeExchanges bool `json:"includeExchanges"`

	// IncludeEmptyPeers will include peers, even if they have no connections.
	IncludeEmptyPeers bool `json:"includeEmptyPeers"`

	// IncludeTombstones will include tombstones when introspecting relays.
	IncludeTombstones bool `json:"includeTombstones"`

	// IncludeOtherChannels will include basic information about other channels
	// created in the same process as this channel.
	IncludeOtherChannels bool `json:"includeOtherChannels"`
}

IntrospectionOptions are the options used when introspecting the Channel.

type LocalPeerInfo 

type LocalPeerInfo struct {
	PeerInfo

	// ServiceName is the service name for the local peer.
	ServiceName string `json:"serviceName"`
}

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.

func ErrField 

func ErrField(err error) LogField

ErrField wraps an error string as a LogField named "error"

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 {
	// Enabled returns whether the given level is enabled.
	Enabled(level LogLevel) bool

	// Fatal logs a message, then exits with os.Exit(1).
	Fatal(msg string)

	// Error logs a message at error priority.
	Error(msg string)

	// Warn logs a message at warning priority.
	Warn(msg string)

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

	// Info logs a message at info priority.
	Info(msg string)

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

	// Debug logs a message at debug priority.
	Debug(msg string)

	// 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 {
	// 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) LocalPeer added in v1.2.2 

func (call *OutboundCall) LocalPeer() LocalPeerInfo

LocalPeer returns the local peer information for this call.

func (*OutboundCall) RemotePeer added in v1.0.8 

func (call *OutboundCall) RemotePeer() PeerInfo

RemotePeer returns the remote peer information for this call.

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() (ArgReader, error)

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

func (*OutboundCallResponse) Arg3Reader 

func (response *OutboundCallResponse) Arg3Reader() (ArgReader, error)

Arg3Reader returns an ArgReader 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 {
	sync.RWMutex
	// contains filtered or unexported fields
}

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

func (*Peer) BeginCall 

func (p *Peer) BeginCall(ctx context.Context, serviceName, methodName 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) 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.

func (*Peer) IntrospectState 

func (p *Peer) IntrospectState(opts *IntrospectionOptions) PeerRuntimeState

IntrospectState returns the runtime state for this peer.

func (*Peer) NumConnections 

func (p *Peer) NumConnections() (inbound int, outbound int)

NumConnections returns the number of inbound and outbound connections for this peer.

func (*Peer) NumPendingOutbound 

func (p *Peer) NumPendingOutbound() int

NumPendingOutbound returns the number of pending outbound calls.

type PeerInfo 

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

	// The logical process name for the peer, used for only for logging / debugging
	ProcessName string `json:"processName"`

	// IsEphemeral returns whether the remote host:port is ephemeral (e.g. not listening).
	IsEphemeral bool `json:"isEphemeral"`

	// Version returns the version information for the remote peer.
	Version PeerVersion `json:"version"`
}

PeerInfo contains information about a TChannel peer

func (PeerInfo) IsEphemeralHostPort 

func (p PeerInfo) IsEphemeralHostPort() bool

IsEphemeralHostPort returns whether the connection is from an ephemeral host:port.

func (PeerInfo) String 

func (p PeerInfo) String() string

type PeerList 

type PeerList struct {
	sync.RWMutex
	// 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) Copy 

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

Copy returns a copy of the PeerList as a map from hostPort to peer.

func (*PeerList) Get 

func (l *PeerList) Get(prevSelected map[string]struct{}) (*Peer, error)

Get returns a peer from the peer list, or nil if none can be found, will avoid previously selected peers if possible.

func (*PeerList) GetNew added in v1.5.0 

func (l *PeerList) GetNew(prevSelected map[string]struct{}) (*Peer, error)

GetNew returns a new, previously unselected peer from the peer list, or nil, if no new unselected peer 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.

func (*PeerList) IntrospectList 

func (l *PeerList) IntrospectList(opts *IntrospectionOptions) []SubPeerScore

IntrospectList returns the list of peers (hostport, score) in this peer list.

func (*PeerList) Len added in v1.5.0 

func (l *PeerList) Len() int

Len returns the length of the PeerList.

func (*PeerList) Remove added in v1.0.1 

func (l *PeerList) Remove(hostPort string) error

Remove removes a peer from the peer list. It returns an error if the peer cannot be found. Remove does not affect connections to the peer in any way.

func (*PeerList) SetStrategy 

func (l *PeerList) SetStrategy(sc ScoreCalculator)

SetStrategy sets customized peer selection strategy.

type PeerRuntimeState 

type PeerRuntimeState struct {
	HostPort            string                   `json:"hostPort"`
	OutboundConnections []ConnectionRuntimeState `json:"outboundConnections"`
	InboundConnections  []ConnectionRuntimeState `json:"inboundConnections"`
	ChosenCount         uint64                   `json:"chosenCount"`
	SCCount             uint32                   `json:"scCount"`
}

PeerRuntimeState is the runtime state for a single peer.

type PeerVersion added in v1.2.3 

type PeerVersion struct {
	Language        string `json:"language"`
	LanguageVersion string `json:"languageVersion"`
	TChannelVersion string `json:"tchannelVersion"`
}

PeerVersion contains version related information for a specific peer. These values are extracted from the init headers.

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 method.
	Register(h Handler, methodName string)

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

	// StatsReporter returns the stats reporter for this Registrar
	StatsReporter() StatsReporter

	// StatsTags returns the tags that should be used.
	StatsTags() map[string]string

	// 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 RelayCall added in v1.2.2 

type RelayCall interface {
	// Destination returns the selected peer (if there was no error from Start).
	Destination() (peer *Peer, ok bool)

	// The call succeeded (possibly after retrying).
	Succeeded()

	// The call failed.
	Failed(reason string)

	// End stats collection for this RPC. Will be called exactly once.
	End()
}

RelayCall abstracts away peer selection, stats, and any other business logic from the underlying relay implementation. A RelayCall may not have a destination if there was an error during peer selection (which should be returned from start).

type RelayHost added in v1.2.2 

type RelayHost interface {
	// SetChannels is called on creation of the channel. It's used to set a
	// channel reference which can be used to get references to *Peer.
	SetChannel(ch *Channel)

	// Start starts a new RelayCall given the call frame and connection.
	// It may return a call and an error, in which case the caller will
	// call Failed/End on the RelayCall.
	Start(relay.CallFrame, *Connection) (RelayCall, error)
}

RelayHost is the interface used to create RelayCalls when the relay receives an incoming call.

type RelayItemSetState added in v1.0.8 

type RelayItemSetState struct {
	Name  string                    `json:"name"`
	Count int                       `json:"count"`
	Items map[string]RelayItemState `json:"items,omitempty"`
}

RelayItemSetState is the runtime state for a list of relay items.

type RelayItemState added in v1.0.8 

type RelayItemState struct {
	ID                      uint32 `json:"id"`
	RemapID                 uint32 `json:"remapID"`
	DestinationConnectionID uint32 `json:"destinationConnectionID"`
	Tomb                    bool   `json:"tomb"`
}

RelayItemState is the runtime state for a single relay item.

type Relayer added in v1.0.8 

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

A Relayer forwards frames.

func NewRelayer added in v1.0.8 

func NewRelayer(ch *Channel, conn *Connection) *Relayer

NewRelayer constructs a Relayer.

func (*Relayer) IntrospectState added in v1.0.8 

func (r *Relayer) IntrospectState(opts *IntrospectionOptions) RelayerRuntimeState

IntrospectState returns the runtime state for this relayer.

func (*Relayer) Receive added in v1.0.8 

func (r *Relayer) Receive(f *Frame, fType frameType) (sent bool, failureReason string)

Receive receives frames intended for this connection. It returns whether the frame was sent and a reason for failure if it failed.

func (*Relayer) Relay added in v1.0.8 

func (r *Relayer) Relay(f *Frame) error

Relay is called for each frame that is read on the connection.

type RelayerRuntimeState added in v1.0.8 

type RelayerRuntimeState struct {
	Count         int               `json:"count"`
	InboundItems  RelayItemSetState `json:"inboundItems"`
	OutboundItems RelayItemSetState `json:"outboundItems"`
	MaxTimeout    time.Duration     `json:"maxTimeout"`
}

RelayerRuntimeState is the runtime state for a single relayer.

type RequestState 

type RequestState struct {
	// Start is the time at which the request was initiated by the caller of RunWithRetry.
	Start time.Time
	// SelectedPeers is a set of host:ports that have been selected previously.
	SelectedPeers map[string]struct{}
	// Attempt is 1 for the first attempt, and so on.
	Attempt int
	// contains filtered or unexported fields
}

RequestState is a global request state that persists across retries.

func (*RequestState) AddSelectedPeer 

func (rs *RequestState) AddSelectedPeer(hostPort string)

AddSelectedPeer adds a given peer to the set of selected peers.

func (*RequestState) HasRetries 

func (rs *RequestState) HasRetries(err error) bool

HasRetries will return true if there are more retries left.

func (*RequestState) PrevSelectedPeers 

func (rs *RequestState) PrevSelectedPeers() map[string]struct{}

PrevSelectedPeers returns the previously selected peers for this request.

func (*RequestState) RetryCount 

func (rs *RequestState) RetryCount() int

RetryCount returns the retry attempt this is. Essentially, Attempt - 1.

func (*RequestState) SinceStart 

func (rs *RequestState) SinceStart(now time.Time, fallback time.Duration) time.Duration

SinceStart returns the time since the start of the request. If there is no request state, then the fallback is returned.

type ResponseCode 

type ResponseCode byte

ResponseCode to a CallReq

type RetriableFunc 

type RetriableFunc func(context.Context, *RequestState) error

RetriableFunc is the type of function that can be passed to RunWithRetry.

type RetryOn 

type RetryOn int

RetryOn represents the types of errors to retry on. 

const (
	// RetryDefault is currently the same as RetryConnectionError.
	RetryDefault RetryOn = iota

	// RetryConnectionError retries on busy frames, declined frames, and connection errors.
	RetryConnectionError

	// RetryNever never retries any errors.
	RetryNever

	// RetryNonIdempotent will retry errors that occur before a request has been picked up.
	// E.g. busy frames and declined frames.
	// This should be used when making calls to non-idempotent endpoints.
	RetryNonIdempotent

	// RetryUnexpected will retry busy frames, declined frames, and unenxpected frames.
	RetryUnexpected

	// RetryIdempotent will retry all errors that can be retried. This should be used
	// for idempotent endpoints.
	RetryIdempotent
)

func (RetryOn) CanRetry 

func (r RetryOn) CanRetry(err error) bool

CanRetry returns whether an error can be retried for the given retry option.

func (RetryOn) String 

func (i RetryOn) String() string

type RetryOptions 

type RetryOptions struct {
	// MaxAttempts is the maximum number of calls and retries that will be made.
	// If this is 0, the default number of attempts (5) is used.
	MaxAttempts int

	// RetryOn is the types of errors to retry on.
	RetryOn RetryOn

	// TimeoutPerAttempt is the per-retry timeout to use.
	// If this is zero, then the original timeout is used.
	TimeoutPerAttempt time.Duration
}

RetryOptions are the retry options used to configure RunWithRetry.

type RootPeerList 

type RootPeerList struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

RootPeerList is the root peer list which is only used to connect to peers and share peers between subchannels.

func (*RootPeerList) Add 

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

Add adds a peer to the root peer list if it does not exist, or return an existing peer if it exists.

func (*RootPeerList) Copy 

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

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

func (*RootPeerList) Get 

func (l *RootPeerList) Get(hostPort string) (*Peer, bool)

Get returns a peer for the given hostPort if it exists.

func (*RootPeerList) GetOrAdd 

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

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

func (*RootPeerList) IntrospectState 

func (l *RootPeerList) IntrospectState(opts *IntrospectionOptions) map[string]PeerRuntimeState

IntrospectState returns the runtime state of the

type RuntimeState 

type RuntimeState struct {
	ID           uint32 `json:"id"`
	ChannelState string `json:"channelState"`

	// CreatedStack is the stack for how this channel was created.
	CreatedStack string `json:"createdStack"`

	// LocalPeer is the local peer information (service name, host-port, etc).
	LocalPeer LocalPeerInfo `json:"localPeer"`

	// SubChannels contains information about any subchannels.
	SubChannels map[string]SubChannelRuntimeState `json:"subChannels"`

	// RootPeers contains information about all the peers on this channel and their connections.
	RootPeers map[string]PeerRuntimeState `json:"rootPeers"`

	// Peers is the list of shared peers for this channel.
	Peers []SubPeerScore `json:"peers"`

	// NumConnections is the number of connections stored in the channel.
	NumConnections int `json:"numConnections"`

	// Connections is the list of connection IDs in the channel
	Connections []uint32 ` json:"connections"`

	// InactiveConnections is the connection state for connections that are not active,
	// and hence are not reported as part of root peers.
	InactiveConnections []ConnectionRuntimeState `json:"inactiveConnections"`

	// OtherChannels is information about any other channels running in this process.
	OtherChannels map[string][]ChannelInfo `json:"otherChannels,omitEmpty"`

	// RuntimeVersion is the version information about the runtime and the library.
	RuntimeVersion RuntimeVersion `json:"runtimeVersion"`
}

RuntimeState is a snapshot of the runtime state for a channel.

type RuntimeVersion added in v1.0.9 

type RuntimeVersion struct {
	GoVersion      string `json:"goVersion"`
	LibraryVersion string `json:"tchannelVersion"`
}

RuntimeVersion includes version information about the runtime and the tchannel library.

type ScoreCalculator 

type ScoreCalculator interface {
	GetScore(p *Peer) uint64
}

ScoreCalculator defines the interface to calculate the score.

type ScoreCalculatorFunc 

type ScoreCalculatorFunc func(p *Peer) uint64

ScoreCalculatorFunc is an adapter that allows functions to be used as ScoreCalculator

func (ScoreCalculatorFunc) GetScore 

func (f ScoreCalculatorFunc) GetScore(p *Peer) uint64

GetScore calls the underlying function.

type Span 

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

Span is an internal representation of Zipkin-compatible OpenTracing Span. It is used as OpenTracing inject/extract Carrier with ZipkinSpanFormat.

func CurrentSpan 

func CurrentSpan(ctx context.Context) *Span

CurrentSpan extracts OpenTracing Span from the Context, and if found tries to extract zipkin-style trace/span IDs from it using ZipkinSpanFormat carrier. If there is no OpenTracing Span in the Context, an empty span is returned.

func (Span) Flags added in v1.1.0 

func (s Span) Flags() byte

Flags returns flags bitmap. Interpretation of the bits is up to the tracing system.

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

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 {
	sync.RWMutex
	// 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, methodName 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) GetHandlers added in v1.0.8 

func (c *SubChannel) GetHandlers() map[string]Handler

GetHandlers returns all handlers registered on this subchannel by method name.

This function panics if the Handler for the SubChannel was overwritten with SetHandler.

func (*SubChannel) Isolated 

func (c *SubChannel) Isolated() bool

Isolated returns whether this subchannel is an isolated subchannel.

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, methodName string)

Register registers a handler on the subchannel for the given method.

This function panics if the Handler for the SubChannel was overwritten with SetHandler.

func (*SubChannel) ServiceName 

func (c *SubChannel) ServiceName() string

ServiceName returns the service name that this subchannel is for.

func (*SubChannel) SetHandler added in v1.0.4 

func (c *SubChannel) SetHandler(h Handler)

SetHandler changes the SubChannel's underlying handler. This may be used to set up a catch-all Handler for all requests received by this SubChannel.

Methods registered on this SubChannel using Register() before calling SetHandler() will be forgotten. Further calls to Register() on this SubChannel after SetHandler() is called will cause panics.

func (*SubChannel) StatsReporter 

func (c *SubChannel) StatsReporter() StatsReporter

StatsReporter returns the stats reporter for this subchannel.

func (*SubChannel) StatsTags 

func (c *SubChannel) StatsTags() map[string]string

StatsTags returns the stats tags for this subchannel.

func (*SubChannel) Tracer added in v1.1.0 

func (c *SubChannel) Tracer() opentracing.Tracer

Tracer returns OpenTracing Tracer from the top channel.

type SubChannelOption 

type SubChannelOption func(*SubChannel)

SubChannelOption are used to set options for subchannels.

type SubChannelRuntimeState 

type SubChannelRuntimeState struct {
	Service  string `json:"service"`
	Isolated bool   `json:"isolated"`
	// IsolatedPeers is the list of all isolated peers for this channel.
	IsolatedPeers []SubPeerScore      `json:"isolatedPeers,omitempty"`
	Handler       HandlerRuntimeState `json:"handler"`
}

SubChannelRuntimeState is the runtime state for a subchannel.

type SubPeerScore 

type SubPeerScore struct {
	HostPort string `json:"hostPort"`
	Score    uint64 `json:"score"`
}

SubPeerScore show the runtime state of a peer with score.

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

func (SystemErrCode) MetricsKey added in v1.0.8 

func (c SystemErrCode) MetricsKey() string

MetricsKey is a string representation of the error code that's suitable for inclusion in metrics tags.

func (SystemErrCode) String 

func (i SystemErrCode) String() string

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 code and message, conforming to the error interface

func (SystemError) Message 

func (se SystemError) Message() string

Message returns the SystemError message.

func (SystemError) Wrapped 

func (se SystemError) Wrapped() error

Wrapped returns the wrapped error

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"

	// RoutingDelegate header identifies an intermediate service which knows
	// how to route the request to the intended recipient.
	RoutingDelegate TransportHeaderName = "rd"

	// RoutingKey header identifies a traffic group containing instances of the
	// requested service. A relay may use the routing key over the service if
	// it knows about traffic groups.
	RoutingKey TransportHeaderName = "rk"
)

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
benchclient
benchclient is used to make requests to a specific server.
 benchclient is used to make requests to a specific server.
benchserver
benchserver is used to receive requests for benchmarks.
 benchserver is used to receive requests for benchmarks.
behavior/trace
client
common
log
server
examples
bench
bench/client
bench/server
hyperbahn/echo-server
hypercat
keyvalue/client
keyvalue/gen-go/keyvalue
Package keyvalue is generated code used to make or handle TChannel calls using Thrift.
 Package keyvalue is generated code used to make or handle TChannel calls using Thrift.
keyvalue/server
ping
test_server
thrift
thrift/gen-go/example
Package example is generated code used to make or handle TChannel calls using Thrift.
 Package example is generated code used to make or handle TChannel calls using Thrift.
gen-go/hyperbahn
Package hyperbahn is generated code used to make or handle TChannel calls using Thrift.
 Package hyperbahn is generated code used to make or handle TChannel calls using Thrift.
internal
argreader
Package peers provides helpers for managing TChannel peers.
 Package peers provides helpers for managing TChannel peers.
Package relay contains relaying interfaces for external use.
 Package relay contains relaying interfaces for external use.
relaytest
scripts
vbumper
vbumper helps bump version numbers in the repository and in the CHANGELOG.
 vbumper helps bump version numbers in the repository and in the CHANGELOG.
goroutines
mockhyperbahn
testreader
testtracing
testwriter
Package thrift adds support to use Thrift services over TChannel.
 Package thrift adds support to use Thrift services over TChannel.
gen-go/meta
gen-go/test
Package test is generated code used to make or handle TChannel calls using Thrift.
 Package test is generated code used to make or handle TChannel calls using Thrift.
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 used to contain TChannel's distributed tracing functionality.
 Package trace used to contain TChannel's distributed tracing functionality.
Package trand provides a thread-safe random number generator.
 Package trand provides a thread-safe random number generator.

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.