Documentation

Overview

Package grpc implements a YARPC transport based on the gRPC protocol. The gRPC transport provides support for unary and streaming RPCs.

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 configure TLS on your service listener, pass credentials.TransportCredentials as an InboundCredentials InboundOption. There are various ways to create credentials.TransportCredentials. See https://godoc.org/google.golang.org/grpc/credentials#TransportCredentials.

listener, err := net.Listen("tcp", ":4443")
if err != nil {
  return err
}

myTLSConfig := &tls.Config{
  // any arbitrary valid tls.Config
}
myTransportCredentials := credentials.NewTLS(myTLSConfig)
myInbound := grpcTransport.NewInbound(
  listener,
  InboundCredentials(myInboundCredentials),
)
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},
  },
})

To make requests using TLS to an application supporting gRPC over TLS, pass credentials.TransportCredentials as a DialerCredentials DialOption. There are various ways to create credentials.TransportCredentials. See https://godoc.org/google.golang.org/grpc/credentials#TransportCredentials.

myTLSConfig := &tls.Config{
  // any arbitrary valid tls.Config
}
myTransportCredentials := credentials.NewTLS(myTLSConfig)
myChooser := peer.NewSingle(
  hostport.Identify("127.0.0.1:4443"),
  grpcTransport.NewDialer(DialerCredentials(myTransportCredentials)),
)
myserviceOutbound := grpcTransport.NewOutbound(myChooser)
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

View Source
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 also used in responses to ensure requests are processed by the
	// correct service.
	// 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"
	// ApplicationErrorHeader is the header key that will contain a non-empty value
	// if there was an application error.
	ApplicationErrorHeader = "rpc-application-error"

	// ApplicationErrorHeaderValue is the value that will be set for
	// ApplicationErrorHeader is there was an application error.
	//
	// The definition says any non-empty value is valid, however this is
	// the specific value that will be used for now.
	ApplicationErrorHeaderValue = "error"
)
View Source
const TransportName = "grpc"

    TransportName is the name of the transport.

    This value is what is used as transport.Request#Transport and transport.Namer for Outbounds.

    View Source
    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

      Variables

      This section is empty.

      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 DialOption

        type DialOption func(*dialOptions)

          DialOption is an option that influences grpc.Dial.

          func Compressor

          func Compressor(compressor transport.Compressor) DialOption

            Compressor sets the compressor to be used by default for gRPC connections

            func ContextDialer

            func ContextDialer(f func(context.Context, string) (net.Conn, error)) DialOption

              ContextDialer sets the dialer for creating outbound connections.

              See https://godoc.org/google.golang.org/grpc#WithContextDialer for more details.

              func DialerCredentials

              func DialerCredentials(creds credentials.TransportCredentials) DialOption

                DialerCredentials returns a DialOption which configures a connection level security credentials (e.g., TLS/SSL).

                func KeepaliveParams

                func KeepaliveParams(params keepalive.ClientParameters) DialOption

                  KeepaliveParams sets the gRPC keepalive parameters of the outbound connection. See https://pkg.go.dev/google.golang.org/grpc#WithKeepaliveParams for more details.

                  type Dialer

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

                    Dialer is a decorator for a gRPC transport that threads dial options for every retained peer.

                    func (*Dialer) ReleasePeer

                    func (d *Dialer) ReleasePeer(id peer.Identifier, ps peer.Subscriber) error

                      ReleasePeer releases the identified peer.

                      func (*Dialer) RetainPeer

                      func (d *Dialer) RetainPeer(id peer.Identifier, ps peer.Subscriber) (peer.Peer, error)

                        RetainPeer retains the identified peer, passing dial options.

                        type Inbound

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

                          Inbound is a grpc transport.Inbound.

                          func (*Inbound) Addr

                          func (i *Inbound) Addr() net.Addr

                            Addr returns the address on which the server is listening.

                            Returns nil if Start has not been called yet

                            func (*Inbound) Introspect

                            func (i *Inbound) Introspect() introspection.InboundStatus

                              Introspect returns the current state of the 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"`
                                        	TLS     InboundTLSConfig `config:"tls"`
                                        }

                                          InboundConfig configures a gRPC Inbound.

                                          inbounds:

                                          grpc:
                                            address: ":80"
                                          

                                          A gRPC inbound can also enable TLS from key and cert files.

                                          inbounds:

                                          grpc:
                                            address: ":443"
                                            tls:
                                              enabled: true
                                              keyFile: "/path/to/key"
                                              certFile: "/path/to/cert"
                                          

                                          type InboundOption

                                          type InboundOption func(*inboundOptions)

                                            InboundOption is an option for an inbound.

                                            func InboundCredentials

                                            func InboundCredentials(creds credentials.TransportCredentials) InboundOption

                                              InboundCredentials returns an InboundOption that sets credentials for incoming connections.

                                              type InboundTLSConfig

                                              type InboundTLSConfig struct {
                                              	Enabled  bool   `config:"enabled"` // disabled by default
                                              	CertFile string `config:"certFile,interpolate"`
                                              	KeyFile  string `config:"keyFile,interpolate"`
                                              }

                                                InboundTLSConfig specifies the TLS configuration for the gRPC 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) CallStream

                                                      func (o *Outbound) CallStream(ctx context.Context, request *transport.StreamRequest) (*transport.ClientStream, error)

                                                        CallStream implements transport.StreamOutbound#CallStream.

                                                        func (*Outbound) Chooser

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

                                                          Chooser returns the peer.Chooser associated with this Outbound.

                                                          func (*Outbound) Introspect

                                                          func (o *Outbound) Introspect() introspection.OutboundStatus

                                                            Introspect implements introspection.IntrospectableOutbound interface.

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

                                                                  func (o *Outbound) TransportName() string

                                                                    TransportName is the transport name that will be set on `transport.Request` struct.

                                                                    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"`
                                                                      	TLS     OutboundTLSConfig `config:"tls"`
                                                                      	// Compressor to use by default if the server side supports it
                                                                      	Compressor string `config:"compressor"`
                                                                      }

                                                                        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
                                                                        

                                                                        A gRPC outbound can enable TLS using the system cert.Pool.

                                                                        outbounds:
                                                                          theirsecureservice:
                                                                            grpc:
                                                                              address: ":443"
                                                                              tls:
                                                                                enabled: true
                                                                              compressor: gzip
                                                                        

                                                                        type OutboundOption

                                                                        type OutboundOption func(*outboundOptions)

                                                                          OutboundOption is an option for an outbound.

                                                                          type OutboundTLSConfig

                                                                          type OutboundTLSConfig struct {
                                                                          	Enabled bool `config:"enabled"`
                                                                          }

                                                                            OutboundTLSConfig configures TLS for a gRPC 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) NewDialer

                                                                                  func (t *Transport) NewDialer(options ...DialOption) *Dialer

                                                                                    NewDialer creates a transport that is decorated to retain peers with additional gRPC dial options.

                                                                                    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. Note: This does not support TLS. See TLS example in doc.go.

                                                                                          func (*Transport) ReleasePeer

                                                                                          func (t *Transport) ReleasePeer(pid peer.Identifier, ps peer.Subscriber) error

                                                                                            ReleasePeer releases the peer.

                                                                                            Deprecated: use grpcTransport.NewDialer(...grpc.DialOption) to create a peer.Transport that supports custom DialOptions instead of using the grpc.Transport as a peer.Transport.

                                                                                            func (*Transport) RetainPeer

                                                                                            func (t *Transport) RetainPeer(pid peer.Identifier, ps peer.Subscriber) (peer.Peer, error)

                                                                                              RetainPeer retains the peer.

                                                                                              Deprecated: use grpcTransport.NewDialer(...grpc.DialOption) to create a peer.Transport that supports custom DialOptions instead of using the grpc.Transport as a peer.Transport.

                                                                                              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 Logger

                                                                                                            func Logger(logger *zap.Logger) TransportOption

                                                                                                              Logger sets a logger to use for internal logging.

                                                                                                              The default is to not write any logs.

                                                                                                              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.