README

yarpc GoDoc GitHub release Mit License Build Status Coverage Status

A message passing platform for Go that lets you:

  • Write servers and clients with various encodings, including JSON, Thrift, and Protobuf.
  • Expose servers over many transports simultaneously, including HTTP/1.1, gRPC, and TChannel.
  • Migrate outbound calls between transports without any code changes using config.

Installation

We recommend locking to SemVer range ^1 using Glide:

glide get 'go.uber.org/yarpc#^1'

Stability

This library is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before v2.0.0 with the exception of experimental packages.

Experimental packages reside within packages named x, and are not stable. This means their APIs can break at any time. The intention here is to validate these APIs and iterate on them by working closely with internal customers. Once stable, their contents will be moved out of the containing x package and their APIs will be locked.

Development

Setup

To start developing with yarpc-go, run the following command to setup your environment:

cd $GOPATH/src
git clone https://github.com/yarpc/yarpc-go.git go.uber.org/yarpc
make
Running Tests

To run tests into a pre-configured docker container, run the following command:

make test

To run tests locally, run the following command:

SUPPRESS_DOCKER=1 make test

Happy development!

Expand ▾ Collapse ▴

Documentation

Overview

    Package yarpc provides the YARPC service framework.

    With hundreds to thousands of services communicating with RPC, transport protocols (like HTTP and TChannel), encoding protocols (like JSON or Thrift), and peer choosers are the concepts that vary year over year. Separating these concerns allows services to change transports and wire protocols without changing call sites or request handlers, build proxies and wire protocol bridges, or experiment with load balancing strategies. YARPC is a toolkit for services and proxies.

    YARPC breaks RPC into interchangeable encodings, transports, and peer choosers. YARPC for Go provides reference implementations for HTTP/1.1, TChannel and gRPC transports, and also raw, JSON, Thrift, and Protobuf encodings. YARPC for Go provides a round robin peer chooser and experimental implementations for debug pages and rate limiting. YARPC for Go plans to provide a load balancer that uses a least-pending-requests strategy. Peer choosers can implement any strategy, including load balancing or sharding, in turn bound to any peer list updater.

    Regardless of transport, every RPC has some common properties: caller name, service name, procedure name, encoding name, deadline or TTL, headers, baggage (multi-hop headers), and tracing. Each RPC can also have an optional shard key, routing key, or routing delegate for advanced routing. YARPC transports use a shared API for capturing RPC metadata, so middleware can apply to requests over any transport.

    Each YARPC transport protocol can implement inbound handlers and outbound callers. Each of these can support different RPC types, like unary (request and response) or oneway (request and receipt) RPC. A future release of YARPC will add support for other RPC types including variations on streaming and pubsub.

    Index

    Examples

    Constants

    View Source
    const Version = "1.52.0"

      Version is the current version of YARPC.

      Variables

      View Source
      var OpentracingTags = opentracing.Tags{
      	"yarpc.version": Version,
      	"go.version":    runtime.Version(),
      }

        OpentracingTags are tags with YARPC metadata.

        View Source
        var PackageVersions = []introspection.PackageVersion{
        	{Name: "yarpc", Version: Version},
        	{Name: "tchannel", Version: tchannel.VersionInfo},
        	{Name: "thriftrw", Version: thriftrw.Version},
        	{Name: "grpc-go", Version: grpc.Version},
        	{Name: "go", Version: runtime.Version()},
        }

          PackageVersions is a list of packages with corresponding versions.

          Functions

          func CanonicalizeHeaderKey

          func CanonicalizeHeaderKey(k string) string

            CanonicalizeHeaderKey canonicalizes the given header key to the same form used by the headers map returned by ResponseHeaders.

            var headers map[string]string
            res, err := client.Call(ctx, "hello", requestBody, ResponseHeaders(&headers))
            email, ok := headers[CanonicalizeHeaderKey("User-Email-Address")]
            

            func InjectClients

            func InjectClients(src transport.ClientConfigProvider, dest interface{})

              InjectClients injects clients from a Dispatcher into the given struct. dest must be a pointer to a struct with zero or more exported fields which hold YARPC client types. This includes json.Client, raw.Client, and any generated Thrift service client. Fields with nil values and a `service` tag will be populated with clients using that service`s ClientConfig.

              Given,

              type Handler struct {
              	KeyValueClient keyvalueclient.Interface `service:"keyvalue"`
              	UserClient json.Client `service:"users"`
              	TagClient tagclient.Interface  // no tag; will be left unchanged
              }
              

              The call,

              var h Handler
              yarpc.InjectClients(dispatcher, &h)
              

              Is equivalent to,

              var h Handler
              h.KeyValueClient = keyvalueclient.New(dispatcher.ClientConfig("keyvalue"))
              h.UserClient = json.New(dispatcher.ClientConfig("users"))
              

              Builder functions for different client types may be registered using the RegisterClientBuilder function.

              This function panics if a field with an unknown type and nil value has the `service` tag.

              func IsBadRequestError

              func IsBadRequestError(err error) bool

                IsBadRequestError returns true on an error returned by RPC clients if the request was rejected by YARPC because it was invalid.

                res, err := client.Call(...)
                if yarpc.IsBadRequestError(err) {
                	fmt.Println("invalid request:", err)
                }
                

                Deprecated: use yarpcerrors.FromError(err).Code() == yarpcerrors.CodeInvalidArgument instead.

                func IsTimeoutError

                func IsTimeoutError(err error) bool

                  IsTimeoutError returns true on an error returned by RPC clients if the given error is a TimeoutError.

                  res, err := client.Call(...)
                  if yarpc.IsTimeoutError(err) {
                  	fmt.Println("request timed out:", err)
                  }
                  

                  Deprecated: use yarpcerrors.FromError(err).Code() == yarpcerrors.CodeDeadlineExceeded instead.

                  func IsUnexpectedError

                  func IsUnexpectedError(err error) bool

                    IsUnexpectedError returns true on an error returned by RPC clients if the server panicked or failed with an unhandled error.

                    res, err := client.Call(...)
                    if yarpc.IsUnexpectedError(err) {
                    	fmt.Println("internal server error:", err)
                    }
                    

                    Deprecated: use yarpcerrors.FromError(err).Code() == yarpcerrors.CodeInternal instead.

                    func OnewayInboundMiddleware

                    func OnewayInboundMiddleware(mw ...middleware.OnewayInbound) middleware.OnewayInbound

                      OnewayInboundMiddleware combines the given collection of unary inbound middleware in-order into a single OnewayInbound middleware.

                      func OnewayOutboundMiddleware

                      func OnewayOutboundMiddleware(mw ...middleware.OnewayOutbound) middleware.OnewayOutbound

                        OnewayOutboundMiddleware combines the given collection of unary outbound middleware in-order into a single OnewayOutbound middleware.

                        func RegisterClientBuilder

                        func RegisterClientBuilder(f interface{}) (forget func())

                          RegisterClientBuilder registers a builder function for a specific client type.

                          Functions must have one of the following signatures:

                          func(transport.ClientConfig) T
                          func(transport.ClientConfig, reflect.StructField) T
                          

                          Where T is the type of the client. T MUST be an interface. In the second form, the function receives type information about the field being filled. It may inspect the struct tags to customize its behavior.

                          This function panics if a client for the given type has already been registered.

                          After a builder function for a client type is registered, these objects can be instantiated automatically using InjectClients.

                          A function to unregister the builder function is returned. Note that the function will clear whatever the corresponding type's builder function is at the time it is called, regardless of whether the value matches what was passed to this function or not.

                          func StreamInboundMiddleware

                          func StreamInboundMiddleware(mw ...middleware.StreamInbound) middleware.StreamInbound

                            StreamInboundMiddleware combines the given collection of unary inbound middleware in-order into a single StreamInbound middleware.

                            func StreamOutboundMiddleware

                            func StreamOutboundMiddleware(mw ...middleware.StreamOutbound) middleware.StreamOutbound

                              StreamOutboundMiddleware combines the given collection of unary outbound middleware in-order into a single StreamOutbound middleware.

                              func UnaryInboundMiddleware

                              func UnaryInboundMiddleware(mw ...middleware.UnaryInbound) middleware.UnaryInbound

                                UnaryInboundMiddleware combines the given collection of unary inbound middleware in-order into a single UnaryInbound middleware.

                                func UnaryOutboundMiddleware

                                func UnaryOutboundMiddleware(mw ...middleware.UnaryOutbound) middleware.UnaryOutbound

                                  UnaryOutboundMiddleware combines the given collection of unary outbound middleware in-order into a single UnaryOutbound middleware.

                                  Types

                                  type Ack

                                  type Ack interface {
                                  	fmt.Stringer
                                  }

                                    Ack represents an acknowledgement from a oneway request.

                                    type Call

                                    type Call encoding.Call

                                      Call provides information about the current request inside handlers. An instance of Call for the current request can be obtained by calling CallFromContext on the request context.

                                      func Get(ctx context.Context, req *GetRequest) (*GetResponse, error) {
                                      	call := yarpc.CallFromContext(ctx)
                                      	fmt.Println("Received request from", call.Caller())
                                      	if err := call.WriteResponseHeader("hello", "world"); err != nil {
                                      		return nil, err
                                      	}
                                      	return response, nil
                                      }
                                      

                                      func CallFromContext

                                      func CallFromContext(ctx context.Context) *Call

                                      CallFromContext retrieves information about the current incoming request from the given context. Returns nil if the context is not a valid request context.

                                      The object is valid only as long as the request is ongoing.

                                      Testing

                                      To test functions which use CallFromContext, use yarpctest.ContextWithCall to build contexts compatible with this function.

                                      func (*Call) Caller

                                      func (c *Call) Caller() string

                                        Caller returns the name of the service making this request.

                                        func (*Call) Encoding

                                        func (c *Call) Encoding() transport.Encoding

                                          Encoding returns the encoding for this request.

                                          func (*Call) Header

                                          func (c *Call) Header(k string) string

                                            Header returns the value of the given request header provided with the request.

                                            func (*Call) HeaderNames

                                            func (c *Call) HeaderNames() []string

                                              HeaderNames returns a sorted list of the names of user defined headers provided with this request.

                                              func (*Call) Procedure

                                              func (c *Call) Procedure() string

                                                Procedure returns the name of the procedure being called.

                                                func (*Call) RoutingDelegate

                                                func (c *Call) RoutingDelegate() string

                                                  RoutingDelegate returns the routing delegate for this request.

                                                  func (*Call) RoutingKey

                                                  func (c *Call) RoutingKey() string

                                                    RoutingKey returns the routing key for this request.

                                                    func (*Call) Service

                                                    func (c *Call) Service() string

                                                      Service returns the name of the service being called.

                                                      func (*Call) ShardKey

                                                      func (c *Call) ShardKey() string

                                                        ShardKey returns the shard key for this request.

                                                        func (*Call) Transport

                                                        func (c *Call) Transport() string

                                                          Transport returns the name of the transport being called.

                                                          func (*Call) WriteResponseHeader

                                                          func (c *Call) WriteResponseHeader(k, v string) error

                                                            WriteResponseHeader writes headers to the response of this call.

                                                            type CallOption

                                                            type CallOption encoding.CallOption

                                                              CallOption defines options that may be passed in at call sites to other services.

                                                              These may be used to add or alter the request.

                                                              func ResponseHeaders

                                                              func ResponseHeaders(h *map[string]string) CallOption

                                                                ResponseHeaders specifies that headers received in response to this request should replace the given map.

                                                                Header keys in the map are normalized using the CanonicalizeHeaderKey function.

                                                                var resHeaders map[string]string
                                                                resBody, err := client.SetValue(ctx, key, value, yarpc.ResponseHeaders(&resHeaders))
                                                                value, ok := resHeaders[yarpc.CanonicalizeHeaderKey("foo")]
                                                                

                                                                Note that the map is replaced completely. Entries it had before making the call will not be available afterwards.

                                                                headers := map[string]string{"hello": "world"}
                                                                resBody, err := client.SetValue(ctx, key, value, yarpc.ResponseHeaders(&headers))
                                                                _, ok := headers["hello"]
                                                                fmt.Println(ok)  // false
                                                                

                                                                func WithHeader

                                                                func WithHeader(k, v string) CallOption

                                                                  WithHeader adds a new header to the request. Header keys are case insensitive.

                                                                  _, err := client.GetValue(ctx, reqBody, yarpc.WithHeader("Token", "10"))
                                                                  // ==> {"token": "10"}
                                                                  

                                                                  If multiple entries have the same normalized header name, newer entries override older ones.

                                                                  func WithRoutingDelegate

                                                                  func WithRoutingDelegate(rd string) CallOption

                                                                    WithRoutingDelegate sets the routing delegate for the request.

                                                                    func WithRoutingKey

                                                                    func WithRoutingKey(rk string) CallOption

                                                                      WithRoutingKey sets the routing key for the request.

                                                                      func WithShardKey

                                                                      func WithShardKey(sk string) CallOption

                                                                        WithShardKey sets the shard key for the request.

                                                                        type ClientConfig

                                                                        type ClientConfig interface {
                                                                        	transport.ClientConfigProvider
                                                                        }

                                                                          ClientConfig builds transport.ClientConfigs which specify the means of making a request from this service to another service by name.

                                                                          type Config

                                                                          type Config struct {
                                                                          	// Name of the service. This is the name used by other services when
                                                                          	// making requests to this service.
                                                                          	Name string
                                                                          
                                                                          	// Inbounds define how this service receives incoming requests from other
                                                                          	// services.
                                                                          	//
                                                                          	// This may be nil if this service does not receive any requests.
                                                                          	Inbounds Inbounds
                                                                          
                                                                          	// Outbounds defines how this service makes requests to other services.
                                                                          	//
                                                                          	// This may be nil if this service does not send any requests.
                                                                          	Outbounds Outbounds
                                                                          
                                                                          	// Inbound and Outbound Middleware that will be applied to all incoming
                                                                          	// and outgoing requests respectively.
                                                                          	//
                                                                          	// These may be nil if there is no middleware to apply.
                                                                          	InboundMiddleware  InboundMiddleware
                                                                          	OutboundMiddleware OutboundMiddleware
                                                                          
                                                                          	// Tracer is meant to add/record tracing information to a request.
                                                                          	//
                                                                          	// Deprecated: The dispatcher does nothing with this property.  Set the
                                                                          	// tracer directly on the transports used to build inbounds and outbounds.
                                                                          	Tracer opentracing.Tracer
                                                                          
                                                                          	// RouterMiddleware is middleware to control how requests are routed.
                                                                          	RouterMiddleware middleware.Router
                                                                          
                                                                          	// Configures logging.
                                                                          	Logging LoggingConfig
                                                                          
                                                                          	// Configures telemetry.
                                                                          	Metrics MetricsConfig
                                                                          
                                                                          	// DisableAutoObservabilityMiddleware is used to stop the dispatcher from
                                                                          	// automatically attaching observability middleware to all inbounds and
                                                                          	// outbounds.  It is the assumption that if if this option is disabled the
                                                                          	// observability middleware is being inserted in the Inbound/Outbound
                                                                          	// Middleware.
                                                                          	DisableAutoObservabilityMiddleware bool
                                                                          }

                                                                            Config specifies the parameters of a new Dispatcher constructed via NewDispatcher.

                                                                            type DirectionalLogLevelConfig

                                                                            type DirectionalLogLevelConfig struct {
                                                                            	// Level at which successful requests are logged.
                                                                            	// Defaults to DebugLevel.
                                                                            	Success *zapcore.Level
                                                                            	// Level at which errors are logged.
                                                                            	// Thrift exceptions are application errors, which we log as a separate
                                                                            	// class from success and failure.
                                                                            	Failure *zapcore.Level
                                                                            	// Level at which application errors are logged.
                                                                            	// All Thrift exceptions are considered application errors.
                                                                            	// All errors from Protobuf handlers are application errors.
                                                                            	// Defaults to ErrorLevel.
                                                                            	ApplicationError *zapcore.Level
                                                                            }

                                                                              DirectionalLogLevelConfig may override the log levels for any combination of successes, failures, and application errors.

                                                                              type Dispatcher

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

                                                                                Dispatcher encapsulates a YARPC application. It acts as the entry point to send and receive YARPC requests in a transport and encoding agnostic way.

                                                                                Example (Minimal)
                                                                                Output:
                                                                                
                                                                                

                                                                                func NewDispatcher

                                                                                func NewDispatcher(cfg Config) *Dispatcher

                                                                                  NewDispatcher builds a new Dispatcher using the specified Config. At minimum, a service name must be specified.

                                                                                  Invalid configurations or errors in constructing the Dispatcher will cause panics.

                                                                                  func (*Dispatcher) ClientConfig

                                                                                  func (d *Dispatcher) ClientConfig(outboundKey string) transport.ClientConfig

                                                                                    ClientConfig provides the configuration needed to talk to the given service through an outboundKey. This configuration may be directly passed into encoding-specific RPC clients.

                                                                                    keyvalueClient := json.New(dispatcher.ClientConfig("keyvalue"))
                                                                                    

                                                                                    This function panics if the outboundKey is not known.

                                                                                    func (*Dispatcher) InboundMiddleware

                                                                                    func (d *Dispatcher) InboundMiddleware() InboundMiddleware

                                                                                      InboundMiddleware returns the middleware applied to all inbound handlers. Router middleware and fallback handlers can use the InboundMiddleware to wrap custom handlers.

                                                                                      func (*Dispatcher) Inbounds

                                                                                      func (d *Dispatcher) Inbounds() Inbounds

                                                                                        Inbounds returns a copy of the list of inbounds for this RPC object.

                                                                                        The Inbounds will be returned in the same order that was used in the configuration.

                                                                                        func (*Dispatcher) Introspect

                                                                                        func (d *Dispatcher) Introspect() introspection.DispatcherStatus

                                                                                          Introspect returns detailed information about the dispatcher. This function acquires a lots of locks throughout and should only be called with some reserve.

                                                                                          func (*Dispatcher) MustOutboundConfig

                                                                                          func (d *Dispatcher) MustOutboundConfig(outboundKey string) *transport.OutboundConfig

                                                                                            MustOutboundConfig provides the configuration needed to talk to the given service through an outboundKey. This configuration may be directly passed into encoding-specific RPC clients.

                                                                                            keyvalueClient := json.New(dispatcher.MustOutboundConfig("keyvalue"))
                                                                                            

                                                                                            This function panics if the outboundKey is not known.

                                                                                            func (*Dispatcher) Name

                                                                                            func (d *Dispatcher) Name() string

                                                                                              Name returns the name of the dispatcher.

                                                                                              func (*Dispatcher) OutboundConfig

                                                                                              func (d *Dispatcher) OutboundConfig(outboundKey string) (oc *transport.OutboundConfig, ok bool)

                                                                                                OutboundConfig provides the configuration needed to talk to the given service through an outboundKey. This configuration may be directly passed into encoding-specific RPC clients.

                                                                                                 outboundConfig, ok := dispatcher.OutboundConfig("keyvalue")
                                                                                                 if !ok {
                                                                                                   // do something
                                                                                                 }
                                                                                                	keyvalueClient := json.New(outboundConfig)
                                                                                                

                                                                                                func (*Dispatcher) Outbounds

                                                                                                func (d *Dispatcher) Outbounds() Outbounds

                                                                                                  Outbounds returns a copy of the list of outbounds for this RPC object.

                                                                                                  func (*Dispatcher) PhasedStart

                                                                                                  func (d *Dispatcher) PhasedStart() (*PhasedStarter, error)

                                                                                                    PhasedStart is a more granular alternative to Start, and is intended only for advanced users. Rather than starting all transports, inbounds, and outbounds at once, it lets the user start them separately.

                                                                                                    Start and PhasedStart are mutually exclusive. If Start is called first, PhasedStart is a no-op and returns the same error (if any) that Start returned. If PhasedStart is called first, Start is a no-op and always returns a nil error; the caller is responsible for using the PhasedStarter to complete startup.

                                                                                                    func (*Dispatcher) PhasedStop

                                                                                                    func (d *Dispatcher) PhasedStop() (*PhasedStopper, error)

                                                                                                      PhasedStop is a more granular alternative to Stop, and is intended only for advanced users. Rather than stopping all inbounds, outbounds, and transports at once, it lets the user stop them separately.

                                                                                                      Stop and PhasedStop are mutually exclusive. If Stop is called first, PhasedStop is a no-op and returns the same error (if any) that Stop returned. If PhasedStop is called first, Stop is a no-op and always returns a nil error; the caller is responsible for using the PhasedStopper to complete shutdown.

                                                                                                      func (*Dispatcher) Register

                                                                                                      func (d *Dispatcher) Register(rs []transport.Procedure)

                                                                                                        Register registers zero or more procedures with this dispatcher. Incoming requests to these procedures will be routed to the handlers specified in the given Procedures.

                                                                                                        Example (JSON)
                                                                                                        Output:
                                                                                                        
                                                                                                        
                                                                                                        Example (Raw)
                                                                                                        Output:
                                                                                                        
                                                                                                        

                                                                                                        func (*Dispatcher) Router

                                                                                                        func (d *Dispatcher) Router() transport.Router

                                                                                                          Router returns the procedure router.

                                                                                                          func (*Dispatcher) Start

                                                                                                          func (d *Dispatcher) Start() error

                                                                                                            Start starts the Dispatcher, allowing it to accept and process new incoming requests. This starts all inbounds and outbounds configured on this Dispatcher.

                                                                                                            This function returns immediately after everything has been started. Servers should add a `select {}` to block to process all incoming requests.

                                                                                                            if err := dispatcher.Start(); err != nil {
                                                                                                            	log.Fatal(err)
                                                                                                            }
                                                                                                            defer dispatcher.Stop()
                                                                                                            
                                                                                                            select {}
                                                                                                            

                                                                                                            Start and PhasedStart are mutually exclusive. See the PhasedStart documentation for details.

                                                                                                            func (*Dispatcher) Stop

                                                                                                            func (d *Dispatcher) Stop() error

                                                                                                              Stop stops the Dispatcher, shutting down all inbounds, outbounds, and transports. This function returns after everything has been stopped.

                                                                                                              Stop and PhasedStop are mutually exclusive. See the PhasedStop documentation for details.

                                                                                                              type InboundMiddleware

                                                                                                              type InboundMiddleware struct {
                                                                                                              	Unary  middleware.UnaryInbound
                                                                                                              	Oneway middleware.OnewayInbound
                                                                                                              	Stream middleware.StreamInbound
                                                                                                              }

                                                                                                                InboundMiddleware contains the different types of inbound middlewares.

                                                                                                                type Inbounds

                                                                                                                type Inbounds []transport.Inbound

                                                                                                                  Inbounds contains a list of inbound transports. Each inbound transport specifies a source through which incoming requests are received.

                                                                                                                  type LogLevelConfig

                                                                                                                  type LogLevelConfig struct {
                                                                                                                  	// Level at which successful requests are logged.
                                                                                                                  	// Defaults to DebugLevel.
                                                                                                                  	// Can be overridden by Inbound.Success or Outbound.Success for inbound or
                                                                                                                  	// outbound requests.
                                                                                                                  	Success *zapcore.Level
                                                                                                                  	// Level at which errors are logged.
                                                                                                                  	// Thrift exceptions are application errors, which we log as a separate
                                                                                                                  	// class from success and failure.
                                                                                                                  	// Can be overridden by Inbound.Failure or Outbound.Failure for inbound or
                                                                                                                  	// outbound requests.
                                                                                                                  	Failure *zapcore.Level
                                                                                                                  	// Level at which application errors are logged.
                                                                                                                  	// All Thrift exceptions are considered application errors.
                                                                                                                  	// Defaults to ErrorLevel.
                                                                                                                  	// Can be overridden by Inbound.ApplicationError or
                                                                                                                  	// Outbound.ApplicationError for inbound or outbound requests.
                                                                                                                  	ApplicationError *zapcore.Level
                                                                                                                  
                                                                                                                  	// Specific overrides for inbound and outbound requests.
                                                                                                                  	Inbound, Outbound DirectionalLogLevelConfig
                                                                                                                  }

                                                                                                                    LogLevelConfig configures the levels at which YARPC logs various things.

                                                                                                                    type LoggingConfig

                                                                                                                    type LoggingConfig struct {
                                                                                                                    	// Supplies a logger for the dispatcher. By default, no logs are
                                                                                                                    	// emitted.
                                                                                                                    	Zap *zap.Logger
                                                                                                                    
                                                                                                                    	// If supplied, ExtractContext is used to log request-scoped
                                                                                                                    	// information carried on the context (e.g., trace and span IDs).
                                                                                                                    	ContextExtractor func(context.Context) zapcore.Field
                                                                                                                    
                                                                                                                    	// Levels configures the levels at which YARPC logs various messages.
                                                                                                                    	Levels LogLevelConfig
                                                                                                                    }

                                                                                                                      LoggingConfig describes how logging should be configured.

                                                                                                                      type MapRouter

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

                                                                                                                        MapRouter is a Router that maintains a map of the registered procedures.

                                                                                                                        func NewMapRouter

                                                                                                                        func NewMapRouter(defaultService string) MapRouter

                                                                                                                          NewMapRouter builds a new MapRouter that uses the given name as the default service name.

                                                                                                                          func (MapRouter) Choose

                                                                                                                            Choose retrives the HandlerSpec for the service, procedure, and encoding noted on the transport request, or returns an unrecognized procedure error (testable with transport.IsUnrecognizedProcedureError(err)).

                                                                                                                            func (MapRouter) Procedures

                                                                                                                            func (m MapRouter) Procedures() []transport.Procedure

                                                                                                                              Procedures returns a list procedures that have been registered so far.

                                                                                                                              func (MapRouter) Register

                                                                                                                              func (m MapRouter) Register(rs []transport.Procedure)

                                                                                                                                Register registers the procedure with the MapRouter. If the procedure does not specify its service name, the procedure will inherit the default service name of the router. Procedures should specify their encoding, and multiple procedures with the same name and service name can exist if they handle different encodings. If a procedure does not specify an encoding, it can only support one handler. The router will select that handler regardless of the encoding.

                                                                                                                                type MetricsConfig

                                                                                                                                type MetricsConfig struct {
                                                                                                                                	// Metrics is a *"go.uber.org/net/metrics".Scope for recording stats.
                                                                                                                                	// YARPC does not push these metrics; pushing metrics from the root is an
                                                                                                                                	// external concern.
                                                                                                                                	Metrics *metrics.Scope
                                                                                                                                	// Tally scope used for pushing to M3 or StatsD-based systems. By
                                                                                                                                	// default, metrics are collected in memory but not pushed.
                                                                                                                                	// TODO deprecate this option for metrics configuration.
                                                                                                                                	Tally tally.Scope
                                                                                                                                	// TagsBlocklist enlists tags' keys that should be suppressed from all the metrics
                                                                                                                                	// emitted from w/in YARPC middleware.
                                                                                                                                	TagsBlocklist []string
                                                                                                                                }

                                                                                                                                  MetricsConfig describes how telemetry should be configured. Scope and Tally are exclusive; choose one. If neither is present, metrics are not recorded, all instrumentation becomes no-ops. If both are present, we emit a warning and ignore Tally. If a metrics scope is preseent, we use that scope to record metrics and they are not pushed to Tally. If Tally is present, we use its metrics scope and push them periodically.

                                                                                                                                  type OutboundMiddleware

                                                                                                                                  type OutboundMiddleware struct {
                                                                                                                                  	Unary  middleware.UnaryOutbound
                                                                                                                                  	Oneway middleware.OnewayOutbound
                                                                                                                                  	Stream middleware.StreamOutbound
                                                                                                                                  }

                                                                                                                                    OutboundMiddleware contains the different types of outbound middlewares.

                                                                                                                                    type Outbounds

                                                                                                                                    type Outbounds map[string]transport.Outbounds

                                                                                                                                      Outbounds provides access to outbounds for a remote service. Outbounds define how requests are sent from this service to the remote service.

                                                                                                                                      type PhasedStarter

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

                                                                                                                                        PhasedStarter is a more granular alternative to the Dispatcher's all-in-one Start method. Rather than starting the transports, inbounds, and outbounds in one call, it lets the user choose when to trigger each phase of dispatcher startup. For details on the interaction of Start and phased startup, see the documentation for the Dispatcher's PhasedStart method.

                                                                                                                                        The user of a PhasedStarter is responsible for correctly ordering startup: transports MUST be started before outbounds, which MUST be started before inbounds. Attempting startup in any other order will return an error.

                                                                                                                                        func (*PhasedStarter) StartInbounds

                                                                                                                                        func (s *PhasedStarter) StartInbounds() error

                                                                                                                                          StartInbounds is the final phase of startup. It starts all inbounds configured on the dispatcher, which allows any registered procedures to begin receiving requests. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                          func (*PhasedStarter) StartOutbounds

                                                                                                                                          func (s *PhasedStarter) StartOutbounds() error

                                                                                                                                            StartOutbounds is the second phase of startup. It starts all outbounds configured on the dispatcher, which allows users of the dispatcher to construct clients and begin making outbound RPCs. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                            func (*PhasedStarter) StartTransports

                                                                                                                                            func (s *PhasedStarter) StartTransports() error

                                                                                                                                              StartTransports is the first step in startup. It starts all transports configured on the dispatcher, which is a necessary precondition for making and receiving RPCs. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                              type PhasedStopper

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

                                                                                                                                                PhasedStopper is a more granular alternative to the Dispatcher's all-in-one Stop method. Rather than stopping the inbounds, outbounds, and transports in one call, it lets the user choose when to trigger each phase of dispatcher shutdown. For details on the interaction of Stop and phased shutdown, see the documentation for the Dispatcher's PhasedStop method.

                                                                                                                                                The user of a PhasedStopper is responsible for correctly ordering shutdown: inbounds MUST be stopped before outbounds, which MUST be stopped before transports. Attempting shutdown in any other order will return an error.

                                                                                                                                                func (*PhasedStopper) StopInbounds

                                                                                                                                                func (s *PhasedStopper) StopInbounds() error

                                                                                                                                                  StopInbounds is the first step in shutdown. It stops all inbounds configured on the dispatcher, which stops routing RPCs to all registered procedures. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                                  func (*PhasedStopper) StopOutbounds

                                                                                                                                                  func (s *PhasedStopper) StopOutbounds() error

                                                                                                                                                    StopOutbounds is the second step in shutdown. It stops all outbounds configured on the dispatcher, which stops clients from making outbound RPCs. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                                    func (*PhasedStopper) StopTransports

                                                                                                                                                    func (s *PhasedStopper) StopTransports() error

                                                                                                                                                      StopTransports is the final step in shutdown. It stops all transports configured on the dispatcher and cleans up any ancillary goroutines. It's safe to call concurrently, but all calls after the first return an error.

                                                                                                                                                      type RouterMiddleware

                                                                                                                                                      type RouterMiddleware middleware.Router

                                                                                                                                                        RouterMiddleware wraps the Router middleware

                                                                                                                                                        type StreamOption

                                                                                                                                                        type StreamOption encoding.StreamOption

                                                                                                                                                          StreamOption defines options that may be passed in at streaming function call sites.

                                                                                                                                                          These may be used to add or alter individual stream calls.

                                                                                                                                                          Directories

                                                                                                                                                          Path Synopsis
                                                                                                                                                          api
                                                                                                                                                          encoding
                                                                                                                                                          Package encoding provides APIs for encoding authors.
                                                                                                                                                          Package encoding provides APIs for encoding authors.
                                                                                                                                                          middleware/middlewaretest
                                                                                                                                                          Package middlewaretest is a generated GoMock package.
                                                                                                                                                          Package middlewaretest is a generated GoMock package.
                                                                                                                                                          peer
                                                                                                                                                          Package peer contains interfaces pertaining to peers, peer lists, peer list updaters, and generally how to choose a peer for an outbound request.
                                                                                                                                                          Package peer contains interfaces pertaining to peers, peer lists, peer list updaters, and generally how to choose a peer for an outbound request.
                                                                                                                                                          peer/peertest
                                                                                                                                                          Package peertest is a generated GoMock package.
                                                                                                                                                          Package peertest is a generated GoMock package.
                                                                                                                                                          transport/transporttest
                                                                                                                                                          Package transporttest is a generated GoMock package.
                                                                                                                                                          Package transporttest is a generated GoMock package.
                                                                                                                                                          x/restriction
                                                                                                                                                          Package restriction is an experimental package for preventing unwanted transport-encoding pairs.
                                                                                                                                                          Package restriction is an experimental package for preventing unwanted transport-encoding pairs.
                                                                                                                                                          compressor
                                                                                                                                                          grpc
                                                                                                                                                          Package yarpcgrpccompressor provides an adapter for YARPC compressors to gRPC compressors.
                                                                                                                                                          Package yarpcgrpccompressor provides an adapter for YARPC compressors to gRPC compressors.
                                                                                                                                                          gzip
                                                                                                                                                          Package yarpcgzip provides a YARPC binding for GZIP compression.
                                                                                                                                                          Package yarpcgzip provides a YARPC binding for GZIP compression.
                                                                                                                                                          snappy
                                                                                                                                                          Package yarpcsnappy provides a YARPC binding for snappy compression.
                                                                                                                                                          Package yarpcsnappy provides a YARPC binding for snappy compression.
                                                                                                                                                          encoding
                                                                                                                                                          json
                                                                                                                                                          Package json provides the JSON encoding for YARPC.
                                                                                                                                                          Package json provides the JSON encoding for YARPC.
                                                                                                                                                          protobuf
                                                                                                                                                          Package protobuf implements Protocol Buffers encoding support for YARPC.
                                                                                                                                                          Package protobuf implements Protocol Buffers encoding support for YARPC.
                                                                                                                                                          protobuf/protoc-gen-yarpc-go
                                                                                                                                                          Package main provides a protoc plugin that generates code for the protobuf encoding for YARPC.
                                                                                                                                                          Package main provides a protoc plugin that generates code for the protobuf encoding for YARPC.
                                                                                                                                                          protobuf/reflection
                                                                                                                                                          Package reflection exposes information about protobuf services required to implement the gRPC server reflection API and return information about the compatible registered yarpc services.
                                                                                                                                                          Package reflection exposes information about protobuf services required to implement the gRPC server reflection API and return information about the compatible registered yarpc services.
                                                                                                                                                          raw
                                                                                                                                                          Package raw provides the raw encoding for YARPC.
                                                                                                                                                          Package raw provides the raw encoding for YARPC.
                                                                                                                                                          thrift
                                                                                                                                                          Package thrift implements Thrift encoding support for YARPC.
                                                                                                                                                          Package thrift implements Thrift encoding support for YARPC.
                                                                                                                                                          thrift/thriftrw-plugin-yarpc
                                                                                                                                                          thriftrw-plugin-yarpc implements a plugin for ThriftRW that generates code compatible with YARPC.
                                                                                                                                                          thriftrw-plugin-yarpc implements a plugin for ThriftRW that generates code compatible with YARPC.
                                                                                                                                                          Package peer contains components for managing peers.
                                                                                                                                                          Package peer contains components for managing peers.
                                                                                                                                                          abstractlist
                                                                                                                                                          Package abstractlist provides a utility for managing peer availability with a separate implementation of peer selection from just among available peers.
                                                                                                                                                          Package abstractlist provides a utility for managing peer availability with a separate implementation of peer selection from just among available peers.
                                                                                                                                                          peerlist
                                                                                                                                                          Package peerlist is deprecated in favor of `go.uber.org/yarpc/peer/peerlist/v2` which can additionally convey peer list identifiers to the peerlist.Implementation without a wrapper type, allowing a peer list updater to communicate shard information for example.
                                                                                                                                                          Package peerlist is deprecated in favor of `go.uber.org/yarpc/peer/peerlist/v2` which can additionally convey peer list identifiers to the peerlist.Implementation without a wrapper type, allowing a peer list updater to communicate shard information for example.
                                                                                                                                                          peerlist/v2
                                                                                                                                                          Package peerlist provides a utility for managing peer availability with a separate implementation of peer selection from just among available peers.
                                                                                                                                                          Package peerlist provides a utility for managing peer availability with a separate implementation of peer selection from just among available peers.
                                                                                                                                                          pendingheap
                                                                                                                                                          Package pendingheap provides an implementation of a peer list that sends traffic to the peer with the fewest pending requests, but degenerates to round robin when all peers have equal pending requests, using a heap.
                                                                                                                                                          Package pendingheap provides an implementation of a peer list that sends traffic to the peer with the fewest pending requests, but degenerates to round robin when all peers have equal pending requests, using a heap.
                                                                                                                                                          tworandomchoices
                                                                                                                                                          Package tworandomchoices provides a load balancer implementation that picks two peers at random and chooses the one with fewer pending requests.
                                                                                                                                                          Package tworandomchoices provides a load balancer implementation that picks two peers at random and chooses the one with fewer pending requests.
                                                                                                                                                          x
                                                                                                                                                          Package x contains experimental components.
                                                                                                                                                          Package x contains experimental components.
                                                                                                                                                          pkg
                                                                                                                                                          encoding
                                                                                                                                                          Package encoding contains helper functionality for encoding implementations.
                                                                                                                                                          Package encoding contains helper functionality for encoding implementations.
                                                                                                                                                          errors
                                                                                                                                                          Package errors contains helper functions for working with YARPC errors for encoding and transport implementations.
                                                                                                                                                          Package errors contains helper functions for working with YARPC errors for encoding and transport implementations.
                                                                                                                                                          lifecycle
                                                                                                                                                          Package lifecycle provides a helper for objects that have a synchronized lifecycle from idle, through running, to stopped or errored, executing start and stop transitions exactly once.
                                                                                                                                                          Package lifecycle provides a helper for objects that have a synchronized lifecycle from idle, through running, to stopped or errored, executing start and stop transitions exactly once.
                                                                                                                                                          procedure
                                                                                                                                                          Package procedure contains utilities for handling procedure name mappings.
                                                                                                                                                          Package procedure contains utilities for handling procedure name mappings.
                                                                                                                                                          Package transport implements the low level concerns of sending and receiving bytes.
                                                                                                                                                          Package transport implements the low level concerns of sending and receiving bytes.
                                                                                                                                                          grpc
                                                                                                                                                          Package grpc implements a YARPC transport based on the gRPC protocol.
                                                                                                                                                          Package grpc implements a YARPC transport based on the gRPC protocol.
                                                                                                                                                          http
                                                                                                                                                          Package http implements a YARPC transport based on the HTTP/1.1 protocol.
                                                                                                                                                          Package http implements a YARPC transport based on the HTTP/1.1 protocol.
                                                                                                                                                          tchannel
                                                                                                                                                          Package tchannel implements a YARPC transport based on the TChannel protocol.
                                                                                                                                                          Package tchannel implements a YARPC transport based on the TChannel protocol.
                                                                                                                                                          x
                                                                                                                                                          Package x contains experimental components.
                                                                                                                                                          Package x contains experimental components.
                                                                                                                                                          yarpctest/api
                                                                                                                                                          Package api is for all interfaces and patterns that need to be implemented to interact with the yarpctest api, but not the explicit types we'll use to make requests, or the types that we'll use directly in tests.
                                                                                                                                                          Package api is for all interfaces and patterns that need to be implemented to interact with the yarpctest api, but not the explicit types we'll use to make requests, or the types that we'll use directly in tests.
                                                                                                                                                          yarpctest/types
                                                                                                                                                          Package types are for objects in the yarpctest API that implement multiple interfaces.
                                                                                                                                                          Package types are for objects in the yarpctest API that implement multiple interfaces.
                                                                                                                                                          Package yarpcconfig implements a generic configuration system that may be used to build YARPC Dispatchers from configurations specified in different markup formats.
                                                                                                                                                          Package yarpcconfig implements a generic configuration system that may be used to build YARPC Dispatchers from configurations specified in different markup formats.
                                                                                                                                                          Package yarpctest provides utilities to test YARPC services and clients.
                                                                                                                                                          Package yarpctest provides utilities to test YARPC services and clients.
                                                                                                                                                          recorder
                                                                                                                                                          Package recorder records & replay yarpc requests on the client side.
                                                                                                                                                          Package recorder records & replay yarpc requests on the client side.
                                                                                                                                                          bufferpool
                                                                                                                                                          Package bufferpool maintains a pool of bytes.Buffers for use in encoding and transport implementations.
                                                                                                                                                          Package bufferpool maintains a pool of bytes.Buffers for use in encoding and transport implementations.
                                                                                                                                                          cover
                                                                                                                                                          cover is a tool that runs `go test` with cross-package coverage on this repository, ignoring any packages that opt out of coverage with .nocover files.
                                                                                                                                                          cover is a tool that runs `go test` with cross-package coverage on this repository, ignoring any packages that opt out of coverage with .nocover files.
                                                                                                                                                          firstoutboundmiddleware
                                                                                                                                                          Package firstoutboundmiddleware annotates every outbound request with metadata like the request transport protocol.
                                                                                                                                                          Package firstoutboundmiddleware annotates every outbound request with metadata like the request transport protocol.
                                                                                                                                                          grpcctx
                                                                                                                                                          Package grpcctx contains helper functionality for testing with grpc-go.
                                                                                                                                                          Package grpcctx contains helper functionality for testing with grpc-go.
                                                                                                                                                          interpolate
                                                                                                                                                          Package interpolate provides a generic mechanism to interpolate variables into strings.
                                                                                                                                                          Package interpolate provides a generic mechanism to interpolate variables into strings.
                                                                                                                                                          net
                                                                                                                                                          observability
                                                                                                                                                          Package observability provides logging and metrics collection middleware for YARPC.
                                                                                                                                                          Package observability provides logging and metrics collection middleware for YARPC.
                                                                                                                                                          protoplugin
                                                                                                                                                          Package protoplugin provides utilities for protoc plugins.
                                                                                                                                                          Package protoplugin provides utilities for protoc plugins.
                                                                                                                                                          stresstest
                                                                                                                                                          Package main runs a stress test on each peer list implementation, concurrently adding, removing, connecting, disconnecting, and choosing peers.
                                                                                                                                                          Package main runs a stress test on each peer list implementation, concurrently adding, removing, connecting, disconnecting, and choosing peers.
                                                                                                                                                          testtime
                                                                                                                                                          Package testtime provides ways to scale time for tests running on CPU starved systems.
                                                                                                                                                          Package testtime provides ways to scale time for tests running on CPU starved systems.
                                                                                                                                                          crossdock Module
                                                                                                                                                          examples Module