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 and TChannel transports, and also raw, JSON, and Thrift encodings. YARPC for Go provides experimental implementations for a Redis transport and a round robin peer chooser. YARPC for Go plans to provide a Protobuf 3 encoding, a gRPC transport, and 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 ¶
- Constants
- Variables
- func CanonicalizeHeaderKey(k string) string
- func InjectClients(src transport.ClientConfigProvider, dest interface{})
- func IsBadRequestError(err error) booldeprecated
- func IsTimeoutError(err error) booldeprecated
- func IsUnexpectedError(err error) booldeprecated
- func OnewayInboundMiddleware(mw ...middleware.OnewayInbound) middleware.OnewayInbound
- func OnewayOutboundMiddleware(mw ...middleware.OnewayOutbound) middleware.OnewayOutbound
- func RegisterClientBuilder(f interface{}) (forget func())
- func UnaryInboundMiddleware(mw ...middleware.UnaryInbound) middleware.UnaryInbound
- func UnaryOutboundMiddleware(mw ...middleware.UnaryOutbound) middleware.UnaryOutbound
- type Ack
- type Call
- func (c *Call) Caller() string
- func (c *Call) Encoding() transport.Encoding
- func (c *Call) Header(k string) string
- func (c *Call) HeaderNames() []string
- func (c *Call) Procedure() string
- func (c *Call) RoutingDelegate() string
- func (c *Call) RoutingKey() string
- func (c *Call) Service() string
- func (c *Call) ShardKey() string
- func (c *Call) WriteResponseHeader(k, v string) error
- type CallOption
- type ClientConfig
- type Config
- type Dispatcher
- func (d *Dispatcher) ClientConfig(outboundKey string) transport.ClientConfig
- func (d *Dispatcher) InboundMiddleware() InboundMiddleware
- func (d *Dispatcher) Inbounds() Inbounds
- func (d *Dispatcher) Introspect() introspection.DispatcherStatus
- func (d *Dispatcher) Name() string
- func (d *Dispatcher) Register(rs []transport.Procedure)
- func (d *Dispatcher) Router() transport.Router
- func (d *Dispatcher) Start() error
- func (d *Dispatcher) Stop() error
- type InboundMiddleware
- type Inbounds
- type LoggingConfig
- type MapRouter
- type MetricsConfig
- type OutboundMiddleware
- type Outbounds
- type RouterMiddleware
Examples ¶
Constants ¶
const Version = "1.19.0"
Version is the current version of YARPC.
Variables ¶
var PackageVersions = []introspection.PackageVersion{ {Name: "yarpc", Version: Version}, {Name: "tchannel", Version: tchannel.VersionInfo}, {Name: "thriftrw", Version: thriftrw.Version}, {Name: "go", Version: runtime.Version()}, }
PackageVersions is a list of packages with corresponding versions.
Functions ¶
func CanonicalizeHeaderKey ¶
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 ¶ added in v0.4.0
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
deprecated
added in
v1.0.0
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
deprecated
added in
v1.0.0
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
deprecated
added in
v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v0.4.0
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 UnaryInboundMiddleware ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 Call ¶ added in v1.0.0
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 ¶ added in v1.0.0
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.
func (*Call) Header ¶ added in v1.0.0
Header returns the value of the given request header provided with the request.
func (*Call) HeaderNames ¶ added in v1.0.0
HeaderNames returns a sorted list of the names of user defined headers provided with this request.
func (*Call) RoutingDelegate ¶ added in v1.0.0
RoutingDelegate returns the routing delegate for this request.
func (*Call) RoutingKey ¶ added in v1.0.0
RoutingKey returns the routing key for this request.
func (*Call) WriteResponseHeader ¶ added in v1.0.0
WriteResponseHeader writes headers to the response of this call.
type CallOption ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
func WithRoutingDelegate(rd string) CallOption
WithRoutingDelegate sets the routing delegate for the request.
func WithRoutingKey ¶ added in v1.0.0
func WithRoutingKey(rk string) CallOption
WithRoutingKey sets the routing key for the request.
func WithShardKey ¶ added in v1.0.0
func WithShardKey(sk string) CallOption
WithShardKey sets the shard key for the request.
type ClientConfig ¶ added in v1.13.0
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 }
Config specifies the parameters of a new Dispatcher constructed via NewDispatcher.
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) ¶
package main import ( "log" "go.uber.org/yarpc" ) func main() { dispatcher := yarpc.NewDispatcher(yarpc.Config{Name: "myFancyService"}) if err := dispatcher.Start(); err != nil { log.Fatal(err) } defer dispatcher.Stop() }
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 ¶ added in v1.0.0
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 ¶ added in v1.8.0
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 ¶ added in v1.5.0
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. This method is public merely for use by the package yarpcmeta. The result of this function is internal to yarpc anyway.
func (*Dispatcher) Name ¶ added in v1.5.0
func (d *Dispatcher) Name() string
Name returns the name of the dispatcher.
func (*Dispatcher) Register ¶ added in v1.0.0
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) ¶
package main import ( "context" "fmt" "go.uber.org/yarpc" "go.uber.org/yarpc/encoding/json" ) // global dispatcher used in the registration examples var dispatcher = yarpc.NewDispatcher(yarpc.Config{Name: "service"}) func main() { handler := func(ctx context.Context, key string) (string, error) { fmt.Println("key", key) return "value", nil } dispatcher.Register(json.Procedure("get", handler)) }
Output:
Example (Raw) ¶
package main import ( "context" "go.uber.org/yarpc" "go.uber.org/yarpc/encoding/raw" ) // global dispatcher used in the registration examples var dispatcher = yarpc.NewDispatcher(yarpc.Config{Name: "service"}) func main() { handler := func(ctx context.Context, data []byte) ([]byte, error) { return data, nil } dispatcher.Register(raw.Procedure("echo", handler)) }
Output:
func (*Dispatcher) Router ¶ added in v1.5.0
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 processing 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 {}
func (*Dispatcher) Stop ¶
func (d *Dispatcher) Stop() error
Stop stops the Dispatcher.
This stops all outbounds and inbounds owned by this Dispatcher.
This function returns after everything has been stopped.
type InboundMiddleware ¶ added in v1.0.0
type InboundMiddleware struct { Unary middleware.UnaryInbound Oneway middleware.OnewayInbound }
InboundMiddleware contains the different types of inbound middlewares.
type Inbounds ¶ added in v0.5.0
Inbounds contains a list of inbound transports. Each inbound transport specifies a source through which incoming requests are received.
type LoggingConfig ¶ added in v1.8.0
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 }
LoggingConfig describes how logging should be configured.
type MapRouter ¶ added in v1.0.0
type MapRouter struct {
// contains filtered or unexported fields
}
MapRouter is a Router that maintains a map of the registered procedures.
func NewMapRouter ¶ added in v1.0.0
NewMapRouter builds a new MapRouter that uses the given name as the default service name.
func (MapRouter) Choose ¶ added in v1.0.0
func (m MapRouter) Choose(ctx context.Context, req *transport.Request) (transport.HandlerSpec, error)
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 ¶ added in v1.0.0
Procedures returns a list procedures that have been registered so far.
func (MapRouter) Register ¶ added in v1.0.0
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 ¶ added in v1.8.0
type MetricsConfig struct { // Tally scope used for pushing to M3 or StatsD-based systems. By // default, metrics are collected in memory but not pushed. Tally tally.Scope }
MetricsConfig describes how telemetry should be configured.
type OutboundMiddleware ¶ added in v1.0.0
type OutboundMiddleware struct { Unary middleware.UnaryOutbound Oneway middleware.OnewayOutbound }
OutboundMiddleware contains the different types of outbound middlewares.
type Outbounds ¶ added in v0.4.0
Outbounds provides access to outbounds for a remote service. Outbounds define how requests are sent from this service to the remote service.
type RouterMiddleware ¶ added in v1.2.0
type RouterMiddleware middleware.Router
RouterMiddleware wraps the Router middleware
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
api
|
|
encoding
Package encoding provides APIs for encoding authors.
|
Package encoding provides APIs for encoding authors. |
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. |
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/protoc-gen-yarpc-go/internal/lib
Package lib contains the library code for protoc-gen-yarpc-go.
|
Package lib contains the library code for protoc-gen-yarpc-go. |
protobuf/protoc-gen-yarpc-go/internal/testing
Package testing is a generated protocol buffer package.
|
Package testing is a generated protocol buffer package. |
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. |
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. |
clock
Package clock provides swappable real and fake clocks.
|
Package clock provides swappable real and fake clocks. |
crossdock/crossdockpb
Package crossdockpb is a generated protocol buffer package.
|
Package crossdockpb is a generated protocol buffer package. |
crossdock/thrift/gen-go/echo
Package echo is generated code used to make or handle TChannel calls using Thrift.
|
Package echo is generated code used to make or handle TChannel calls using Thrift. |
crossdock/thrift/gen-go/gauntlet_tchannel
Package gauntlet_tchannel is generated code used to make or handle TChannel calls using Thrift.
|
Package gauntlet_tchannel is generated code used to make or handle TChannel calls using Thrift. |
examples/protobuf/examplepb
Package examplepb is a generated protocol buffer package.
|
Package examplepb is a generated protocol buffer package. |
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. |
observability
Package observability provides logging and metrics collection middleware for YARPC.
|
Package observability provides logging and metrics collection middleware for YARPC. |
pally
Package pally is a simple, atomic-based metrics library.
|
Package pally is a simple, atomic-based metrics library. |
protoplugin
Package protoplugin provides utilities for protoc plugins.
|
Package protoplugin provides utilities for protoc plugins. |
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. |
Package peer contains components for managing peers.
|
Package peer contains components for managing peers. |
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. |
Package x contains experimental components.
|
Package x contains experimental components. |
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 yarpcproto is a generated protocol buffer package.
|
Package yarpcproto is a generated protocol buffer package. |
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. |