yarpc

README

yarpc-go

A transport and encoding agnostic RPC framework.

Installation

go get -u github.com/yarpc/yarpc-go

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

• func BaggageFromContext(ctx context.Context, key string) (value string, ok bool)
• func CanonicalizeHeaderKey(k string) string
• func Filters(filters ...transport.Filter) transport.Filter
• func Interceptors(interceptors ...transport.Interceptor) transport.Interceptor
• func WithBaggage(ctx context.Context, key, value string) context.Context
• 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 ReqMeta
• type ResMeta
  • func NewResMeta() ResMeta

Functions

func BaggageFromContext

func BaggageFromContext(ctx context.Context, key string) (value string, ok bool)

BaggageFromContext returns the baggage attached to the context with the given key name. False is returned if baggage with the given name was not attached to the context.

func CanonicalizeHeaderKey

func CanonicalizeHeaderKey(k string) string

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

func Filters

func Filters(filters ...transport.Filter) transport.Filter

Filters combines the given collection of filters in-order into a single Filter.

func Interceptors

func Interceptors(interceptors ...transport.Interceptor) transport.Interceptor

Interceptors combines the given collection of interceptors in-order into a single Interceptor.

func WithBaggage

func WithBaggage(ctx context.Context, key, value string) context.Context

WithBaggage returns a copy of the context with the given baggage attached to it.

Baggage is a set of key-value pairs that are sent to all downstream requests made with the returned context. Use this sparingly: all downstream services that receive baggage in a request will propagate it to all outbound calls made as a result of receiving that request.

If baggage with the same key is already attached to the context, it will be overwritten in the new context. The parent context will always be left unchanged.

Types

type CallReqMeta

type CallReqMeta interface {
	Procedure(string) CallReqMeta
	Headers(Headers) CallReqMeta

	GetProcedure() string
	GetHeaders() Headers
}

CallReqMeta contains information about an outgoing YARPC request.

func NewReqMeta

func NewReqMeta() CallReqMeta

NewReqMeta constructs a CallReqMeta with the given Context.

The context MUST NOT be nil.

type CallResMeta

type CallResMeta interface {
	Headers() Headers
}

CallResMeta contains information about an incoming YARPC response.

type Config

type Config struct {
	Name      string
	Inbounds  []transport.Inbound
	Outbounds transport.Outbounds

	// Filter and Interceptor that will be applied to all outgoing and incoming
	// requests respectively.
	Filter      transport.Filter
	Interceptor transport.Interceptor
}

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

type Dispatcher

type Dispatcher interface {
	transport.Handler
	transport.Registry

	// Retrieves a new Outbound transport that will make requests to the given
	// service.
	//
	// This panics if the given service is unknown.
	Channel(service string) transport.Channel

	// 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() []transport.Inbound

	// Starts the RPC allowing it to accept and processing 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 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