yarpc

README

yarpc-go

A transport and encoding agnostic RPC framework.

Installation

go get -u go.uber.org/yarpc

If using Glide, at least glide version 0.12 is required to install:

$ glide --version
glide version 0.12.2

$ glide get 'go.uber.org/yarpc#~0.5'

Development Status: Alpha

Ready for adventurous users and early adopters, but there will likely be a few breaking changes and features required before releasing version 1.0.

Documentation

Index

• Constants
• func CanonicalizeHeaderKey(k string) string
• func InjectClients(src transport.ClientConfigProvider, dest interface{})
• func OnewayInboundMiddleware(mw ...middleware.OnewayInboundMiddleware) middleware.OnewayInboundMiddleware
• func OnewayOutboundMiddleware(mw ...middleware.OnewayOutboundMiddleware) middleware.OnewayOutboundMiddleware
• func RegisterClientBuilder(f interface{}) (forget func())
• func UnaryInboundMiddleware(mw ...middleware.UnaryInboundMiddleware) middleware.UnaryInboundMiddleware
• func UnaryOutboundMiddleware(mw ...middleware.UnaryOutboundMiddleware) middleware.UnaryOutboundMiddleware
• type CallReqMeta
  • func NewReqMeta() CallReqMeta
• type CallResMeta
• type Config
• type Dispatcher
  • func NewDispatcher(cfg Config) Dispatcher
• type Headers
  • func NewHeaders() Headers
  • func (h Headers) Del(k string)
  • func (h Headers) Get(k string) (string, bool)
  • func (h Headers) Keys() []string
  • func (h Headers) Len() int
  • func (h Headers) With(k, v string) Headers
• type InboundMiddleware
• type Inbounds
• type MapRegistry
  • func NewMapRegistry(defaultService string) MapRegistry
  • func (m MapRegistry) Choose(ctx context.Context, req *transport.Request) (transport.HandlerSpec, error)
  • func (m MapRegistry) ChooseProcedure(service, procedure string) (transport.HandlerSpec, error)
  • func (m MapRegistry) Register(rs []transport.Registrant)
  • func (m MapRegistry) ServiceProcedures() []transport.ServiceProcedure
• type OutboundMiddleware
• type Outbounds
• type ReqMeta
• type ResMeta
  • func NewResMeta() ResMeta
• type StartStoppable

Constants

const Version = "1.0.0-rc3"

Version is the current version of YARPC.

Functions

func CanonicalizeHeaderKey

func CanonicalizeHeaderKey(k string) string

CanonicalizeHeaderKey canonicalizes the given header key for storage into the Headers map.

func InjectClients

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

InjectClients injects clients from the given Dispatcher into the given struct. dest must be a pointer to a struct with zero or more exported fields Thrift client fields. Only fields with nil values and a `service` tag will be populated; everything else will be left unchanged.

type Handler struct {
	KeyValueClient keyvalueclient.Interface `service:"keyvalue"`
	UserClient json.Client `service:"users"`
	TagClient tagclient.Interface  // will not be changed
}

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

// InjectClients above is equivalent to,

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 an empty client field without a registered constructor is encountered.

func OnewayInboundMiddleware

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

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

func OnewayOutboundMiddleware

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

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

func RegisterClientBuilder

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

RegisterClientBuilder registers a builder function for a specific client type.

Functions must have the signature,

func(transport.ClientConfig) T

Where T is the type of the client. T MUST be an interface.

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

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

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

func UnaryOutboundMiddleware

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

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

Types

type CallReqMeta

type CallReqMeta interface {
	Procedure(string) CallReqMeta
	Headers(Headers) CallReqMeta
	ShardKey(string) CallReqMeta
	RoutingKey(string) CallReqMeta
	RoutingDelegate(string) CallReqMeta

	GetProcedure() string
	GetHeaders() Headers
	GetShardKey() string
	GetRoutingKey() string
	GetRoutingDelegate() string
}

CallReqMeta contains information about an outgoing YARPC request.

func NewReqMeta

func NewReqMeta() CallReqMeta

NewReqMeta constructs a CallReqMeta with the given Context.

type CallResMeta

type CallResMeta interface {
	Headers() Headers
}

CallResMeta contains information about an incoming YARPC response.

type Config

type Config struct {
	Name string

	Inbounds  Inbounds
	Outbounds Outbounds

	// Inbound and Outbound Middleware that will be applied to all incoming and
	// outgoing requests respectively.
	InboundMiddleware  InboundMiddleware
	OutboundMiddleware OutboundMiddleware

	// Tracer is deprecated. The dispatcher does nothing with this propery.
	Tracer opentracing.Tracer
}

Config specifies the parameters of a new RPC constructed via New.

type Dispatcher

type Dispatcher interface {
	transport.Registrar
	transport.ClientConfigProvider

	// 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.
	Inbounds() Inbounds

	// Starts the RPC allowing it to accept and process new incoming
	// requests.
	//
	// Blocks until the RPC is ready to start accepting new requests.
	Start() error

	// Stops the RPC. No new requests will be accepted.
	//
	// Blocks until the RPC has stopped.
	Stop() error
}

Dispatcher object is used to configure a YARPC application; it is used by Clients to send RPCs, and by Procedures to recieve them. This object is what enables an application to be transport-agnostic.

func NewDispatcher

func NewDispatcher(cfg Config) Dispatcher

NewDispatcher builds a new Dispatcher using the specified Config.

type Headers

type Headers internal.Headers

Headers defines application headers which will be sent over the wire to the recipient of an RPC call.

func NewHeaders

func NewHeaders() Headers

NewHeaders builds a new Headers object.

func (Headers) Del

func (h Headers) Del(k string)

Del deletes the given header key from the map.

func (Headers) Get

func (h Headers) Get(k string) (string, bool)

Get retrieves the value associated with the given header key, and a boolean indicating whether the key actually existed in the header map.

func (Headers) Keys

func (h Headers) Keys() []string

Keys returns a list of header keys defined on this Headers object.

All items in the list will be normalized using CanonicalizeHeaderKey.

func (Headers) Len

func (h Headers) Len() int

Len returns the number of headers defined on this object.

func (Headers) With

func (h Headers) With(k, v string) Headers

With returns a Headers object with the given key-value pair added to it. If a header with the same name already exists, it will be overwritten.

This API is similar to Go's append function. The returned Headers object MAY not point to the same underlying data store, so the returned value MUST always be used in place of the original object.

headers = headers.With("foo", "bar")

This call may be chained to set multiple headers consecutively.

headers = headers.With("foo", "bar").With("baz", "qux")

Again, note that the returned Headers object MAY point to a new object. It MAY also mutate the original object instead.

h1 = NewHeaders().With("foo", "bar")
h2 = h1.With("baz", "qux")
h1.Get("baz")  // this MAY return "qux"

type InboundMiddleware

type InboundMiddleware struct {
	Unary  middleware.UnaryInboundMiddleware
	Oneway middleware.OnewayInboundMiddleware
}

InboundMiddleware contains the different type of inbound middleware

type Inbounds

type Inbounds []transport.Inbound

Inbounds contains a list of inbound transports

type MapRegistry

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

MapRegistry is a Registry that maintains a map of the registered procedures.

func NewMapRegistry

func NewMapRegistry(defaultService string) MapRegistry

NewMapRegistry builds a new MapRegistry that uses the given name as the default service name.

func (MapRegistry) Choose

func (m MapRegistry) Choose(ctx context.Context, req *transport.Request) (transport.HandlerSpec, error)

Choose retrives the HandlerSpec for the service and procedure noted on the transport request, or returns an error.

func (MapRegistry) ChooseProcedure

func (m MapRegistry) ChooseProcedure(service, procedure string) (transport.HandlerSpec, error)

ChooseProcedure retrieves the HandlerSpec for the given Procedure or returns an error.

func (MapRegistry) Register

func (m MapRegistry) Register(rs []transport.Registrant)

Register registers the procedure with the MapRegistry.

func (MapRegistry) ServiceProcedures

func (m MapRegistry) ServiceProcedures() []transport.ServiceProcedure

ServiceProcedures returns a list of services and their procedures that have been registered so far.

type OutboundMiddleware

type OutboundMiddleware struct {
	Unary  middleware.UnaryOutboundMiddleware
	Oneway middleware.OnewayOutboundMiddleware
}

OutboundMiddleware contains the different type of outbound middleware

type Outbounds

type Outbounds map[string]transport.Outbounds

Outbounds encapsulates a service and its outbounds

type ReqMeta

type ReqMeta interface {
	Caller() string
	Encoding() transport.Encoding
	Headers() Headers
	Procedure() string
	Service() string
}

ReqMeta contains information about an incoming YARPC request.

type ResMeta

type ResMeta interface {
	Headers(Headers) ResMeta
	GetHeaders() Headers
}

ResMeta contains information about an outgoing YARPC response.

func NewResMeta

func NewResMeta() ResMeta

NewResMeta constructs a ResMeta

type StartStoppable

type StartStoppable interface {
	// Starts the RPC allowing it to accept and process new incoming
	// requests.
	//
	// Blocks until the RPC is ready to start accepting new requests.
	Start() error

	// Stops the RPC. No new requests will be accepted.
	//
	// Blocks until the RPC has stopped.
	Stop() error
}

StartStoppable objects are used to define a common Start/Stop functionality across different dispatcher objects