transport

package
v1.19.0 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2017 License: MIT Imports: 11 Imported by: 228

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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 deprecated 

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.

Deprecated: use yarpcerrors.Newf with yarpcerrors.CodeInvalidArgument instead.

func IsBadRequestError deprecated 

func IsBadRequestError(err error) bool

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

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

func IsTimeoutError deprecated 

func IsTimeoutError(err error) bool

IsTimeoutError return true if the given error is a TimeoutError.

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

func IsUnexpectedError deprecated 

func IsUnexpectedError(err error) bool

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

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

func IsUnrecognizedProcedureError deprecated added in v1.8.0 

func IsUnrecognizedProcedureError(err error) bool

IsUnrecognizedProcedureError returns true for errors returned by Router.Choose if the router cannot find a handler for the request.

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

func UnrecognizedProcedureError deprecated added in v1.8.0 

func UnrecognizedProcedureError(req *Request) error

UnrecognizedProcedureError returns an error for the given request, such that IsUnrecognizedProcedureError can distinguish it from other errors coming out of router.Choose.

Deprecated: use yarpcerrors.Newf with yarpcerrors.CodeUnimplemented instead.

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.

func ValidateUnaryContext added in v1.10.0 

func ValidateUnaryContext(ctx context.Context) error

ValidateUnaryContext validates that a context for a unary request is valid and contains all required information, and returns a YARPC error with code yarpcerrors.CodeInvalidArgument otherwise.

Types

type Ack 

type Ack interface {
	fmt.Stringer
}

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) MarshalLogObject added in v1.8.0 

func (h HandlerSpec) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements zap.ObjectMarshaler.

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 {
	Lifecycle

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

	// 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 {
	Outbound

	// 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 {
	Lifecycle

	// 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

	// If set, this is the unary outbound which sends a request and waits for
	// the response.
	Unary UnaryOutbound

	// If set, this is the oneway outbound which sends the request and
	// continues once the message has been delivered.
	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 and Oneway.

type Procedure 

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

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

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

	// Encoding of the handler (optional) used for introspection and routing
	// (if present).
	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 (p Procedure) Less(o Procedure) bool

Less orders procedures lexicographically on (Service, Name, Encoding).

func (Procedure) MarshalLogObject added in v1.8.0 

func (p Procedure) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements zap.ObjectMarshaler.

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.

func (*Request) MarshalLogObject added in v1.8.0 

func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements zap.ObjectMarshaler.

type Response 

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

Response is the low level response representation.

type ResponseWriter 

type ResponseWriter interface {
	io.Writer

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

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

ResponseWriter allows Handlers to write responses in a streaming fashion.

Functions on ResponseWriter are not thread-safe.

type RouteTable 

type RouteTable interface {
	Router

	// Registers zero or more procedures with the route table.
	Register([]Procedure)
}

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 {
	Lifecycle
}

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)
	Oneway
)

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.
	//
	// Handlers MUST NOT retain references to the ResponseWriter.
	Handle(ctx context.Context, req *Request, resw ResponseWriter) error
}

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

type UnaryOutbound 

type UnaryOutbound interface {
	Outbound

	// 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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.