grpc

Documentation

Overview

Package grpc implements a YARPC transport based on the gRPC protocol. The gRPC transport provides support for Unary RPCs only.

Usage

A gRPC Transport must be constructed to use this transport.

grpcTransport := grpc.NewTransport()

To serve your YARPC application over gRPC, pass a gRPC inbound in your yarpc.Config.

listener, err := net.Listen("tcp", ":8080")
if err != nil {
  return err
}
myInbound := grpcTransport.NewInbound(listener)
dispatcher := yarpc.NewDispatcher(yarpc.Config{
  Name: "myservice",
  Inbounds: yarpc.Inbounds{myInbound},
})

To make requests to a YARPC application that supports gRPC, pass a gRPC outbound in your yarpc.Config.

myserviceOutbound := grpcTransport.NewSingleOutbound("127.0.0.1:8080")
dispatcher := yarpc.NewDispatcher(yarpc.Config{
  Name: "myclient",
  Outbounds: yarpc.Outbounds{
    "myservice": {Unary: myserviceOutbound},
  },
})

Configuration

A gRPC transport may be configured using YARPC's configuration system. See TransportConfig, InboundConfig, and OutboundConfig for details on the different configuration parameters supported by this transport.

See Also

gRPC Project Page: https://grpc.io gRPC Wire Protocol Definition: https://grpc.io/docs/guides/wire.html gRPC Golang Library: https://github.com/grpc/grpc-go

Index

• Constants
• func TransportSpec(opts ...Option) yarpcconfig.TransportSpec
• type Inbound
  • func (i *Inbound) IsRunning() bool
  • func (i *Inbound) SetRouter(router transport.Router)
  • func (i *Inbound) Start() error
  • func (i *Inbound) Stop() error
  • func (i *Inbound) Transports() []transport.Transport
• type InboundConfig
• type InboundOption
• type Option
• type Outbound
  • func (o *Outbound) Call(ctx context.Context, request *transport.Request) (*transport.Response, error)
  • func (o *Outbound) Chooser() peer.Chooser
  • func (o *Outbound) IsRunning() bool
  • func (o *Outbound) Start() error
  • func (o *Outbound) Stop() error
  • func (o *Outbound) Transports() []transport.Transport
• type OutboundConfig
• type OutboundOption
• type Transport
  • func NewTransport(options ...TransportOption) *Transport
  • func (t *Transport) IsRunning() bool
  • func (t *Transport) NewInbound(listener net.Listener, options ...InboundOption) *Inbound
  • func (t *Transport) NewOutbound(peerChooser peer.Chooser, options ...OutboundOption) *Outbound
  • func (t *Transport) NewSingleOutbound(address string, options ...OutboundOption) *Outbound
  • func (t *Transport) ReleasePeer(peerIdentifier peer.Identifier, peerSubscriber peer.Subscriber) error
  • func (t *Transport) RetainPeer(peerIdentifier peer.Identifier, peerSubscriber peer.Subscriber) (peer.Peer, error)
  • func (t *Transport) Start() error
  • func (t *Transport) Stop() error
• type TransportConfig
• type TransportOption
  • func BackoffStrategy(backoffStrategy backoff.Strategy) TransportOption
  • func ClientMaxRecvMsgSize(clientMaxRecvMsgSize int) TransportOption
  • func ClientMaxSendMsgSize(clientMaxSendMsgSize int) TransportOption
  • func ServerMaxRecvMsgSize(serverMaxRecvMsgSize int) TransportOption
  • func ServerMaxSendMsgSize(serverMaxSendMsgSize int) TransportOption
  • func Tracer(tracer opentracing.Tracer) TransportOption

Constants

const (
	// CallerHeader is the header key for the name of the service sending the
	// request. This corresponds to the Request.Caller attribute.
	// This header is required.
	CallerHeader = "rpc-caller"
	// ServiceHeader is the header key for the name of the service to which
	// the request is being sent. This corresponds to the Request.Service attribute.
	// This header is required.
	ServiceHeader = "rpc-service"
	// ShardKeyHeader is the header key for the shard key used by the destined service
	// to shard the request. This corresponds to the Request.ShardKey attribute.
	// This header is optional.
	ShardKeyHeader = "rpc-shard-key"
	// RoutingKeyHeader is the header key for the traffic group responsible for
	// handling the request. This corresponds to the Request.RoutingKey attribute.
	// This header is optional.
	RoutingKeyHeader = "rpc-routing-key"
	// RoutingDelegateHeader is the header key for a service that can proxy the
	// destined service. This corresponds to the Request.RoutingDelegate attribute.
	// This header is optional.
	RoutingDelegateHeader = "rpc-routing-delegate"
	// EncodingHeader is the header key for the encoding used for the request body.
	// This corresponds to the Request.Encoding attribute.
	// If this is not set, content-type will attempt to be read for the encoding per
	// the gRPC wire format http://www.grpc.io/docs/guides/wire.html
	// For example, a content-type of "application/grpc+proto" will be intepreted
	// as the proto encoding.
	// This header is required unless content-type is set properly.
	EncodingHeader = "rpc-encoding"
	// ErrorNameHeader is the header key for the error name.
	ErrorNameHeader = "rpc-error-name"
)

const UserAgent = "yarpc-go/" + yarpc.Version

UserAgent is the User-Agent that will be set for requests. http://www.grpc.io/docs/guides/wire.html#user-agents

Functions

func TransportSpec

func TransportSpec(opts ...Option) yarpcconfig.TransportSpec

TransportSpec returns a TransportSpec for the gRPC transport.

See TransportConfig, InboundConfig, and OutboundConfig for details on the different configuration parameters supported by this Transport.

Any TransportOption, InboundOption, or OutboundOption may be passed to this function. These options will be applied BEFORE configuration parameters are interpreted. This allows configuration parameters to override Options provided to TransportSpec.

Types

type Inbound

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

Inbound is a grpc transport.Inbound.

func (*Inbound) IsRunning

func (i *Inbound) IsRunning() bool

IsRunning implements transport.Lifecycle#IsRunning.

func (*Inbound) SetRouter

func (i *Inbound) SetRouter(router transport.Router)

SetRouter implements transport.Inbound#SetRouter.

func (*Inbound) Start

func (i *Inbound) Start() error

Start implements transport.Lifecycle#Start.

func (*Inbound) Stop

func (i *Inbound) Stop() error

Stop implements transport.Lifecycle#Stop.

func (*Inbound) Transports

func (i *Inbound) Transports() []transport.Transport

Transports implements transport.Inbound#Transports.

type InboundConfig

type InboundConfig struct {
	// Address to listen on. This field is required.
	Address string `config:"address,interpolate"`
}

InboundConfig configures a gRPC Inbound.

inbounds:

grpc:
  address: ":80"

type InboundOption

type InboundOption func(*inboundOptions)

InboundOption is an option for an inbound.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is an interface shared by TransportOption, InboundOption, and OutboundOption allowing either to be recognized by TransportSpec().

type Outbound

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

Outbound is a transport.UnaryOutbound.

func (*Outbound) Call

func (o *Outbound) Call(ctx context.Context, request *transport.Request) (*transport.Response, error)

Call implements transport.UnaryOutbound#Call.

func (*Outbound) Chooser

func (o *Outbound) Chooser() peer.Chooser

Chooser returns the associated peer.Chooser.

func (*Outbound) IsRunning

func (o *Outbound) IsRunning() bool

IsRunning implements transport.Lifecycle#IsRunning.

func (*Outbound) Start

func (o *Outbound) Start() error

Start implements transport.Lifecycle#Start.

func (*Outbound) Stop

func (o *Outbound) Stop() error

Stop implements transport.Lifecycle#Stop.

func (*Outbound) Transports

func (o *Outbound) Transports() []transport.Transport

Transports implements transport.Inbound#Transports.

type OutboundConfig

type OutboundConfig struct {
	yarpcconfig.PeerChooser

	// Address to connect to if no peer options set.
	Address string `config:"address,interpolate"`
}

OutboundConfig configures a gRPC Outbound.

outbounds:

myservice:
  grpc:
    address: ":80"

A gRPC outbound can also configure a peer list.

outbounds:
  myservice:
    grpc:
      round-robin:
        peers:
          - 127.0.0.1:8080
          - 127.0.0.1:8081

type OutboundOption

type OutboundOption func(*outboundOptions)

OutboundOption is an option for an outbound.

type Transport

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

Transport is a grpc transport.Transport.

This currently does not have any additional functionality over creating an Inbound or Outbound separately, but may in the future.

func NewTransport

func NewTransport(options ...TransportOption) *Transport

NewTransport returns a new Transport.

func (*Transport) IsRunning

func (t *Transport) IsRunning() bool

IsRunning implements transport.Lifecycle#IsRunning.

func (*Transport) NewInbound

func (t *Transport) NewInbound(listener net.Listener, options ...InboundOption) *Inbound

NewInbound returns a new Inbound for the given listener.

func (*Transport) NewOutbound

func (t *Transport) NewOutbound(peerChooser peer.Chooser, options ...OutboundOption) *Outbound

NewOutbound returns a new Outbound for the given peer.Chooser.

func (*Transport) NewSingleOutbound

func (t *Transport) NewSingleOutbound(address string, options ...OutboundOption) *Outbound

NewSingleOutbound returns a new Outbound for the given adrress.

func (*Transport) ReleasePeer

func (t *Transport) ReleasePeer(peerIdentifier peer.Identifier, peerSubscriber peer.Subscriber) error

ReleasePeer releases the peer.

func (*Transport) RetainPeer

func (t *Transport) RetainPeer(peerIdentifier peer.Identifier, peerSubscriber peer.Subscriber) (peer.Peer, error)

RetainPeer retains the peer.

func (*Transport) Start

func (t *Transport) Start() error

Start implements transport.Lifecycle#Start.

func (*Transport) Stop

func (t *Transport) Stop() error

Stop implements transport.Lifecycle#Stop.

type TransportConfig

type TransportConfig struct {
	ServerMaxRecvMsgSize int                 `config:"serverMaxRecvMsgSize"`
	ServerMaxSendMsgSize int                 `config:"serverMaxSendMsgSize"`
	ClientMaxRecvMsgSize int                 `config:"clientMaxRecvMsgSize"`
	ClientMaxSendMsgSize int                 `config:"clientMaxSendMsgSize"`
	Backoff              yarpcconfig.Backoff `config:"backoff"`
}

TransportConfig configures a gRPC Transport. This is shared between all gRPC inbounds and outbounds of a Dispatcher.

transports:
  grpc:
    backoff:
      exponential:
        first: 10ms
        max: 30s

All parameters of TransportConfig are optional. This section may be omitted in the transports section.

type TransportOption

type TransportOption func(*transportOptions)

TransportOption is an option for a transport.

func BackoffStrategy

func BackoffStrategy(backoffStrategy backoff.Strategy) TransportOption

BackoffStrategy specifies the backoff strategy for delays between connection attempts for each peer.

The default is exponential backoff starting with 10ms fully jittered, doubling each attempt, with a maximum interval of 30s.

func ClientMaxRecvMsgSize

func ClientMaxRecvMsgSize(clientMaxRecvMsgSize int) TransportOption

ClientMaxRecvMsgSize is the maximum message size the client can receive.

The default is 4MB.

func ClientMaxSendMsgSize

func ClientMaxSendMsgSize(clientMaxSendMsgSize int) TransportOption

ClientMaxSendMsgSize is the maximum message size the client can send.

The default is unlimited.

func ServerMaxRecvMsgSize

func ServerMaxRecvMsgSize(serverMaxRecvMsgSize int) TransportOption

ServerMaxRecvMsgSize is the maximum message size the server can receive.

The default is 4MB.

func ServerMaxSendMsgSize

func ServerMaxSendMsgSize(serverMaxSendMsgSize int) TransportOption

ServerMaxSendMsgSize is the maximum message size the server can send.

The default is unlimited.

func Tracer

func Tracer(tracer opentracing.Tracer) TransportOption

Tracer specifies the tracer to use.

By default, opentracing.GlobalTracer() is used.