grpc

package
v1.75.3 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2024 License: MIT Imports: 49 Imported by: 62

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"
	// CallerProcedureHeader is the header key for the name of the rpc procedure from the service sending the
	// request. This corresponds to the Request.CallerProcedure attribute.
	// This header is optional.
	CallerProcedureHeader = "rpc-caller-procedure"
	// 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 added in v1.32.0 

type DialOption func(*dialOptions)

DialOption is an option that influences grpc.Dial.

func Compressor added in v1.43.0 

func Compressor(compressor transport.Compressor) DialOption

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

func ContextDialer added in v1.40.0 

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

func DialerCredentials(creds credentials.TransportCredentials) DialOption

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

func DialerDestinationServiceName added in v1.66.0 

func DialerDestinationServiceName(service string) DialOption

DialerDestinationServiceName returns a DialOption which configures the destination service name of the dialer. This is used in TLS dialer metrics.

func DialerTLSConfig added in v1.66.0 

func DialerTLSConfig(config *tls.Config) DialOption

DialerTLSConfig return a DialOption which configures the TLS config for the outbound.

func KeepaliveParams added in v1.52.0 

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

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

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

ReleasePeer releases the identified peer.

func (*Dialer) RetainPeer added in v1.32.0 

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

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

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

func InboundCredentials(creds credentials.TransportCredentials) InboundOption

InboundCredentials returns an InboundOption that sets credentials for incoming connections.

func InboundTLSConfiguration added in v1.62.0 

func InboundTLSConfiguration(config *tls.Config) InboundOption

InboundTLSConfiguration returns an InboundOption that provides the TLS confiugration used for setting up TLS inbound.

func InboundTLSMode added in v1.62.0 

func InboundTLSMode(mode yarpctls.Mode) InboundOption

InboundTLSMode returns an InboundOption that sets inbound TLS mode. It must be noted that TLS configuration must be passed separately using inbound option InboundTLSConfiguration.

type InboundTLSConfig added in v1.32.0 

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

	// Mode when set to Permissive or Enforced enables TLS inbound and
	// TLS configuration must be passed as an inbound option.
	// Note: enable, cert and key fields are ignored when mode is set.
	Mode yarpctls.Mode `config:"mode,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 added in v1.27.0 

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

CallStream implements transport.StreamOutbound#CallStream.

func (*Outbound) Chooser added in v1.19.1 

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

Chooser returns the peer.Chooser associated with this Outbound.

func (*Outbound) Introspect added in v1.47.0 

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

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"`
	Keepalive  OutboundKeepaliveConfig `config:"grpc-keepalive"`
}

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
      grpc-keepalive:
        enabled: true
        time:    10s
        timeout: 30s
        permit-without-stream: true

type OutboundKeepaliveConfig added in v1.53.0 

type OutboundKeepaliveConfig struct {
	Enabled             bool   `config:"enabled"`
	Time                string `config:"time"`
	Timeout             string `config:"timeout"`
	PermitWithoutStream bool   `config:"permit-without-stream"`
}

OutboundKeepaliveConfig configures gRPC keepalive for a gRPC outbound.

type OutboundOption 

type OutboundOption func(*outboundOptions)

OutboundOption is an option for an outbound.

func OutboundCompressor added in v1.70.0 

func OutboundCompressor(compressor transport.Compressor) OutboundOption

OutboundCompressor returns an OutboundOption that applies compressorion for requests in the outbound.

func OutboundTLSConfigProvider added in v1.66.0 

func OutboundTLSConfigProvider(provider yarpctls.OutboundTLSConfigProvider) OutboundOption

OutboundTLSConfigProvider returns an OutboundOption that provides the outbound TLS config provider.

type OutboundTLSConfig added in v1.32.0 

type OutboundTLSConfig struct {
	// Enabled field is deprecated, use Mode and SpiffeIDs fields instead.
	Enabled bool `config:"enabled"`
	// Mode when set to Enforced enables TLS outbound and
	// outbound TLS configuration providered option will be used for fetching
	// outbound tls.Config.
	// Note: enable field is ignored when mode is set.
	Mode yarpctls.Mode `config:"mode,interpolate"`
	// SpiffeIDs is a list of the accepted server spiffe IDs.
	SpiffeIDs []string `config:"spiffe-ids"`
}

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

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 deprecated 

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 deprecated 

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"`
	// GRPC header lise size options accept uint32 param.
	// see: https://pkg.go.dev/google.golang.org/grpc#WithMaxHeaderListSize
	ServerMaxHeaderListSize uint32              `config:"serverMaxHeaderListSize"`
	ClientMaxHeaderListSize uint32              `config:"clientMaxHeaderListSize"`
	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
    clientMaxHeaderListSize: 1024
    serverMaxHeaderListSize: 2048

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 ClientMaxHeaderListSize added in v1.61.0 

func ClientMaxHeaderListSize(clientMaxHeaderListSize uint32) TransportOption

ClientMaxHeaderListSize returns a transport option for configuring maximum header list size the client must accept.

The default is 16MB (gRPC default).

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

func Logger(logger *zap.Logger) TransportOption

Logger sets a logger to use for internal logging.

The default is to not write any logs.

func Meter added in v1.62.0 

func Meter(meter *metrics.Scope) TransportOption

Meter sets a meter to use for transport metrics.

The default is to not emit any metrics.

func ServerMaxHeaderListSize added in v1.61.0 

func ServerMaxHeaderListSize(serverMaxHeaderListSize uint32) TransportOption

ServerMaxHeaderListSize returns a transport option for configuring maximum header list size the server must accept.

The default is 16MB (gRPC default).

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 ServiceName added in v1.62.0 

func ServiceName(name string) TransportOption

ServiceName specifices the name of the service used in transport logging and metrics.

func Tracer 

func Tracer(tracer opentracing.Tracer) TransportOption

Tracer specifies the tracer to use.

By default, opentracing.GlobalTracer() is used.

Source Files

View all Source files

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.