Version: v1.5.0 Latest Latest

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

Go to latest
Published: Mar 3, 2017 License: MIT Imports: 10 Imported by: 135




This section is empty.


This section is empty.


func CanonicalizeHeaderKey

func CanonicalizeHeaderKey(k string) string

CanonicalizeHeaderKey canonicalizes the given header key for storage into Headers.

func DispatchOnewayHandler

func DispatchOnewayHandler(
	ctx context.Context,
	h OnewayHandler,
	req *Request,
) (err error)

DispatchOnewayHandler calls the oneway handler, recovering from panics as errors

func DispatchUnaryHandler

func DispatchUnaryHandler(
	ctx context.Context,
	h UnaryHandler,
	start time.Time,
	req *Request,
	resq ResponseWriter,
) (err error)

DispatchUnaryHandler calls the handler h, recovering panics and timeout errors, converting them to yarpc errors. All other errors are passed trough.

func InboundBadRequestError

func InboundBadRequestError(err error) error

InboundBadRequestError builds an error which indicates that an inbound cannot process a request because it is a bad request.

IsBadRequestError returns true for these errors.

func IsBadRequestError

func IsBadRequestError(err error) bool

IsBadRequestError returns true if the request could not be processed because it was invalid.

func IsTimeoutError

func IsTimeoutError(err error) bool

IsTimeoutError return true if the given error is a TimeoutError.

func IsUnexpectedError

func IsUnexpectedError(err error) bool

IsUnexpectedError returns true if the server panicked or failed to process the request with an unhandled error.

func UpdateSpanWithErr

func UpdateSpanWithErr(span opentracing.Span, err error) error

UpdateSpanWithErr sets the error tag on a span, if an error is given. Returns the given error

func ValidateRequest

func ValidateRequest(req *Request) error

ValidateRequest validates the given request. An error is returned if the request is invalid.

Inbound transport implementations may use this to validate requests before handling them. Outbound implementations don't need to validate requests; they are always validated before the outbound is called.


type Ack

type Ack interface {

Ack represents an acknowledgement from a oneway request.

type ClientConfig

type ClientConfig interface {
	// Name of the service making the request.
	Caller() string

	// Name of the service to which the request is being made.
	Service() string

	// Returns an outbound to send the request through or panics if there is no
	// outbound for this service
	// MAY be called multiple times for a request. The returned outbound MUST
	// have already been started.
	GetUnaryOutbound() UnaryOutbound
	GetOnewayOutbound() OnewayOutbound

A ClientConfig is a stream of communication between a single caller-service pair.

type ClientConfigProvider

type ClientConfigProvider interface {
	// Retrieves a new ClientConfig that will make requests to the given service.
	// This MAY panic if the given service is unknown.
	ClientConfig(service string) ClientConfig

ClientConfigProvider builds ClientConfigs from the current service to other services.

type CreateOpenTracingSpan

type CreateOpenTracingSpan struct {
	Tracer        opentracing.Tracer
	TransportName string
	StartTime     time.Time

CreateOpenTracingSpan creates a new context with a started span

func (*CreateOpenTracingSpan) Do

func (c *CreateOpenTracingSpan) Do(
	ctx context.Context,
	req *Request,
) (context.Context, opentracing.Span)

Do creates a new context that has a reference to the started span. This should be called before a Outbound makes a call

type Encoding

type Encoding string

Encoding represents an encoding format for requests.

type ExtractOpenTracingSpan

type ExtractOpenTracingSpan struct {
	ParentSpanContext opentracing.SpanContext
	Tracer            opentracing.Tracer
	TransportName     string
	StartTime         time.Time

ExtractOpenTracingSpan derives a context and associated span

func (*ExtractOpenTracingSpan) Do

func (e *ExtractOpenTracingSpan) Do(
	ctx context.Context,
	req *Request,
) (context.Context, opentracing.Span)

Do derives a new context from SpanContext. The created context has a reference to the started span. parentSpanCtx may be nil. This should be called before a Inbound handles a request

type HandlerSpec

type HandlerSpec struct {
	// contains filtered or unexported fields

HandlerSpec holds a handler and its Type one handler will be set, the other nil

func NewOnewayHandlerSpec

func NewOnewayHandlerSpec(handler OnewayHandler) HandlerSpec

NewOnewayHandlerSpec returns an new HandlerSpec with a OnewayHandler

func NewUnaryHandlerSpec

func NewUnaryHandlerSpec(handler UnaryHandler) HandlerSpec

NewUnaryHandlerSpec returns an new HandlerSpec with a UnaryHandler

func (HandlerSpec) Oneway

func (h HandlerSpec) Oneway() OnewayHandler

Oneway returns the Oneway Handler or nil

func (HandlerSpec) Type

func (h HandlerSpec) Type() Type

Type returns the associated handler's type

func (HandlerSpec) Unary

func (h HandlerSpec) Unary() UnaryHandler

Unary returns the Unary Handler or nil

type Headers

type Headers struct {
	// contains filtered or unexported fields

Headers is the transport-level representation of application headers.

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

func HeadersFromMap

func HeadersFromMap(m map[string]string) Headers

HeadersFromMap builds a new Headers object from the given map of header key-value pairs.

func NewHeaders

func NewHeaders() Headers

NewHeaders builds a new Headers object.

func NewHeadersWithCapacity

func NewHeadersWithCapacity(capacity int) Headers

NewHeadersWithCapacity allocates a new Headers object with the given capacity. A capacity of zero or less is ignored.

func (Headers) Del

func (h Headers) Del(k string)

Del deletes the header with the given name from the Headers map.

This is a no-op if the key does not exist.

func (Headers) Get

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

Get retrieves the value associated with the given header name.

func (Headers) Items

func (h Headers) Items() map[string]string

Items returns the underlying map for this Headers object. The returned map MUST NOT be changed. Doing so will result in undefined behavior.

Keys in the map are 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.

The returned object MAY not point to the same Headers underlying data store as the original Headers so the returned Headers MUST always be used instead of the original object.

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

type Inbound

type Inbound interface {

	// SetRouter configures the inbound to dispatch requests through a
	// router, typically called by a Dispatcher with its RouteTable of handled
	// procedures.
	// Inbound.Start MAY panic if SetRouter was not called.

	// Transport returns any transports that the inbound uses, so they can be
	// collected for lifecycle management, typically by a Dispatcher.
	// An inbound may submit zero or more transports.
	Transports() []Transport

Inbound is a transport that knows how to receive requests for procedure calls.

type Lifecycle

type Lifecycle interface {
	// Start the lifecycle object, returns an error if it cannot be started.
	// Start MUST be idempotent.
	Start() error

	// Stop the lifecycle object, returns an error if it cannot be stopped.
	// Stop MUST be idempotent.
	Stop() error

	// IsRunning returns whether the Lifecycle is currently running.
	// This function exists for introspection purposes only. It should not be
	// used to assert the state of the lifecycle.
	IsRunning() bool

Lifecycle objects are used to define a common Start/Stop functionality across different transport objects.

type OnewayHandler

type OnewayHandler interface {
	// Handle the given oneway request
	// An error may be returned in case of failures.
	HandleOneway(ctx context.Context, req *Request) error

OnewayHandler handles a single, transport-level, oneway request.

type OnewayOutbound

type OnewayOutbound interface {

	// CallOneway sends the given request through this transport and returns an
	// ack.
	// This MUST NOT be called before Start() has been called successfully. This
	// MAY panic if called without calling Start(). This MUST be safe to call
	// concurrently.
	CallOneway(ctx context.Context, request *Request) (Ack, error)

OnewayOutbound is a transport that knows how to send oneway requests for procedure calls.

type Outbound

type Outbound interface {

	// Transports returns the transports that used by this outbound, so they
	// can be collected for lifecycle management, typically by a Dispatcher.
	// Though most outbounds only use a single transport, composite outbounds
	// may use multiple transport protocols, particularly for shadowing traffic
	// across multiple transport protocols during a transport protocol
	// migration.
	Transports() []Transport

Outbound is the common interface for all outbounds

type Outbounds

type Outbounds struct {
	ServiceName string
	Unary       UnaryOutbound
	Oneway      OnewayOutbound

Outbounds encapsulates the outbound specification for a service.

This includes the service name that will be used for outbound requests as well as the Outbound that will be used to transport the request. The outbound will be one of:

- Unary (send request and wait for response) - Oneway (send request and continue once downstream acknowledges request)

type Procedure

type Procedure struct {
	// Name of the procedure.
	Name string

	// Service or empty to use the default service name.
	Service string

	// HandlerSpec specifiying which handler and rpc type.
	HandlerSpec HandlerSpec

	// Encoding of the handler, for introspection.
	Encoding Encoding

	// Signature of the handler, for introspection. This should be a snippet of
	// Go code representing the function definition.
	Signature string

Procedure specifies a single handler registered in the RouteTable.

func (Procedure) Less

func (a Procedure) Less(b Procedure) bool

Less returns true if a.(Service, Name) < b.(Service, Name).

type Request

type Request struct {
	// Name of the service making the request.
	Caller string

	// Name of the service to which the request is being made.
	// The service refers to the canonical traffic group for the service.
	Service string

	// Name of the encoding used for the request body.
	Encoding Encoding

	// Name of the procedure being called.
	Procedure string

	// Headers for the request.
	Headers Headers

	// ShardKey is an opaque string that is meaningful to the destined service
	// for how to relay a request within a cluster to the shard that owns the
	// key.
	ShardKey string

	// RoutingKey refers to a traffic group for the destined service, and when
	// present may override the service name for purposes of routing.
	RoutingKey string

	// RoutingDelegate refers to the traffic group for a service that proxies
	// for the destined service for routing purposes. The routing delegate may
	// override the routing key and service.
	RoutingDelegate string

	// Request payload.
	Body io.Reader

Request is the low level request representation.

type Response

type Response struct {
	Headers          Headers
	Body             io.ReadCloser
	ApplicationError bool

Response is the low level response representation.

type ResponseWriter

type ResponseWriter interface {

	// AddHeaders adds the given headers to the response. If called, this MUST
	// be called before any invocation of Write().
	// This MUST NOT panic if Headers is nil.

	// SetApplicationError specifies that this response contains an
	// application error. If called, this MUST be called before any invocation
	// of Write().

ResponseWriter allows Handlers to write responses in a streaming fashion.

type RouteTable

type RouteTable interface {

	// Registers zero or more procedures with the route table.

RouteTable is an mutable interface for a Router that allows Registering new Procedures

type Router

type Router interface {
	// Procedures returns a list of procedures that
	// have been registered so far.
	Procedures() []Procedure

	// Choose decides a handler based on a context and transport request
	// metadata, or returns an UnrecognizedProcedureError if no handler exists
	// for the request.  This is the interface for use in inbound transports to
	// select a handler for a request.
	Choose(ctx context.Context, req *Request) (HandlerSpec, error)

Router maintains and provides access to a collection of procedures

type Transport

type Transport interface {

Transport is the interface needed by a Dispatcher to manage the life cycle of a transport.

type Type

type Type int

Type is an enum of RPC types

const (
	// Unary types are traditional request/response RPCs
	Unary Type = iota + 1
	// Oneway types are fire and forget RPCs (no response)

func (Type) String

func (i Type) String() string

type UnaryHandler

type UnaryHandler interface {
	// Handle the given request, writing the response to the given
	// ResponseWriter.
	// An error may be returned in case of failures. BadRequestError must be
	// returned for invalid requests. All other failures are treated as
	// UnexpectedErrors.
	Handle(ctx context.Context, req *Request, resw ResponseWriter) error

UnaryHandler handles a single, transport-level, unary request.

type UnaryOutbound

type UnaryOutbound interface {

	// Call sends the given request through this transport and returns its
	// response.
	// This MUST NOT be called before Start() has been called successfully. This
	// MAY panic if called without calling Start(). This MUST be safe to call
	// concurrently.
	Call(ctx context.Context, request *Request) (*Response, error)

UnaryOutbound is a transport that knows how to send unary requests for procedure calls.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL