thrift

Documentation

Overview

Package thrift adds support to use Thrift services over TChannel.

To start listening to a Thrift service using TChannel, create the channel, and register the service using:

server := thrift.NewServer(tchan)
server.Register(gen.NewTChan[SERVICE]Server(handler)

// Any number of services can be registered on the same Thrift server.
server.Register(gen.NewTChan[SERVICE2]Server(handler)

To use a Thrift client use the generated TChan client:

thriftClient := thrift.NewClient(ch, "hyperbahnService", nil)
client := gen.NewTChan[SERVICE]Client(thriftClient)

// Any number of service clients can be made using the same Thrift client.
client2 := gen.NewTChan[SERVICE2]Client(thriftClient)

This client can be used similar to a standard Thrift client, except a Context is passed with options (such as timeout).

TODO(prashant): Add and document header support.

Index

• func ReadHeaders(r io.Reader) (map[string]string, error)
• func ReadStruct(reader io.Reader, s thrift.TStruct) error
• func WriteHeaders(w io.Writer, headers map[string]string) error
• func WriteStruct(writer io.Writer, s thrift.TStruct) error
• type ClientOptions
• type Context
  • func NewContext(timeout time.Duration) (Context, context.CancelFunc)
  • func WithHeaders(ctx context.Context, headers map[string]string) Context
  • func Wrap(ctx context.Context) Context
• type HealthFunc
• type HealthRequest
• type HealthRequestFunc
• type HealthRequestType
• type PostResponseCB
• type RegisterOption
  • func OptPostResponse(cb PostResponseCB) RegisterOption
• type Server
  • func NewServer(registrar tchannel.Registrar) *Server
  • func (s *Server) Handle(ctx context.Context, call *tchannel.InboundCall)
  • func (s *Server) Register(svr TChanServer, opts ...RegisterOption)
  • func (s *Server) RegisterHealthHandler(f HealthFunc)
  • func (s *Server) RegisterHealthRequestHandler(f HealthRequestFunc)
  • func (s *Server) SetContextFn(f func(ctx context.Context, method string, headers map[string]string) Context)
• type TChanClient
  • func NewClient(ch *tchannel.Channel, serviceName string, opts *ClientOptions) TChanClient
• type TChanServer

Functions

func ReadHeaders

func ReadHeaders(r io.Reader) (map[string]string, error)

ReadHeaders reads key-value pairs encoded using WriteHeaders.

func ReadStruct

func ReadStruct(reader io.Reader, s thrift.TStruct) error

ReadStruct reads the given Thrift struct. It pools TProtocols.

func WriteHeaders

func WriteHeaders(w io.Writer, headers map[string]string) error

WriteHeaders writes the given key-value pairs using the following encoding: len~2 (k~4 v~4)~len

func WriteStruct

func WriteStruct(writer io.Writer, s thrift.TStruct) error

WriteStruct writes the given Thrift struct to a writer. It pools TProtocols.

Types

type ClientOptions

type ClientOptions struct {
	// HostPort specifies a specific server to hit.
	HostPort string
}

ClientOptions are options to customize the client.

type Context

type Context tchannel.ContextWithHeaders

Context is a Thrift Context which contains request and response headers.

func NewContext

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

NewContext returns a Context that can be used to make Thrift calls.

func WithHeaders

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

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

func Wrap

func Wrap(ctx context.Context) Context

Wrap returns a Thrift Context that wraps around a Context.

type HealthFunc

type HealthFunc func(ctx Context) (ok bool, message string)

HealthFunc is the interface for custom health endpoints. ok is whether the service health is OK, and message is optional additional information for the health result.

type HealthRequest

type HealthRequest struct {
	// Type is the type of health check being requested.
	Type HealthRequestType
}

HealthRequest is optional parametres for a health request.

type HealthRequestFunc

type HealthRequestFunc func(Context, HealthRequest) (ok bool, message string)

HealthRequestFunc is a health check function that includes parameters about the health check.

type HealthRequestType

type HealthRequestType int

HealthRequestType is the type of health check.

const (
	// Process health checks are used to check whether the process is up
	// and should almost always return true immediately.
	Process HealthRequestType = iota

	// Traffic health checks are used to check whether the process should
	// receive traffic. This can be used to keep a process running, but
	// not receiving health checks (e.g., during process warm-up).
	Traffic
)

type PostResponseCB

type PostResponseCB func(ctx context.Context, method string, response thrift.TStruct)

PostResponseCB registers a callback that is run after a response has been compeltely processed (e.g. written to the channel). This gives the server a chance to clean up resources from the response object

type RegisterOption

type RegisterOption interface {
	Apply(h *handler)
}

RegisterOption is the interface for options to Register.

func OptPostResponse

func OptPostResponse(cb PostResponseCB) RegisterOption

OptPostResponse registers a PostResponseCB.

type Server

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

Server handles incoming TChannel calls and forwards them to the matching TChanServer.

func NewServer

func NewServer(registrar tchannel.Registrar) *Server

NewServer returns a server that can serve thrift services over TChannel.

func (*Server) Handle

func (s *Server) Handle(ctx context.Context, call *tchannel.InboundCall)

Handle handles an incoming TChannel call and forwards it to the correct handler.

func (*Server) Register

func (s *Server) Register(svr TChanServer, opts ...RegisterOption)

Register registers the given TChanServer to be called on any incoming call for its' services. TODO(prashant): Replace Register call with this call.

func (*Server) RegisterHealthHandler

func (s *Server) RegisterHealthHandler(f HealthFunc)

RegisterHealthHandler uses the user-specified function f for the Health endpoint.

func (*Server) RegisterHealthRequestHandler

func (s *Server) RegisterHealthRequestHandler(f HealthRequestFunc)

RegisterHealthRequestHandler uses the user-specified function for the Health endpoint. The function receives the health request which includes information about the type of the request being performed.

func (*Server) SetContextFn

func (s *Server) SetContextFn(f func(ctx context.Context, method string, headers map[string]string) Context)

SetContextFn sets the function used to convert a context.Context to a thrift.Context. Note: This API may change and is only intended to bridge different contexts.

type TChanClient

type TChanClient interface {
	// Call should be passed the method to call and the request/response Thrift structs.
	Call(ctx Context, serviceName, methodName string, req, resp athrift.TStruct) (success bool, err error)
}

TChanClient abstracts calling a Thrift endpoint, and is used by the generated client code.

func NewClient

func NewClient(ch *tchannel.Channel, serviceName string, opts *ClientOptions) TChanClient

NewClient returns a Client that makes calls over the given tchannel to the given Hyperbahn service.

type TChanServer

type TChanServer interface {
	// Handle should read the request from the given reqReader, and return the response struct.
	// The arguments returned are success, result struct, unexpected error
	Handle(ctx Context, methodName string, protocol athrift.TProtocol) (success bool, resp athrift.TStruct, err error)

	// Service returns the service name.
	Service() string

	// Methods returns the method names handled by this server.
	Methods() []string
}

TChanServer abstracts handling of an RPC that is implemented by the generated server code.