transport

package
v1.29.1 Latest Latest
Warning

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

 Go to latest Published: Apr 4, 2018 License: MIT Imports: 13 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 DispatchStreamHandler added in v1.27.0 

func DispatchStreamHandler(
	h StreamHandler,
	stream *ServerStream,
) (err error)

DispatchStreamHandler calls the stream 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 ValidateRequestContext added in v1.25.0 

func ValidateRequestContext(ctx context.Context) error

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

func ValidateUnaryContext deprecated 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.

Deprecated: Use ValidateRequestContext instead.

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 ClientStream added in v1.27.0 

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

ClientStream represents the Client API of interacting with a Stream.

func NewClientStream added in v1.27.0 

func NewClientStream(s StreamCloser, options ...ClientStreamOption) (*ClientStream, error)

NewClientStream will create a new ClientStream.

func (*ClientStream) Close added in v1.27.0 

func (s *ClientStream) Close(ctx context.Context) error

Close will close the connection. It blocks until the server has acknowledged the close. In certain implementations, the timeout on the context will be used to timeout the request. If the server timed out the connection will be forced closed by the client.

func (*ClientStream) Context added in v1.27.0 

func (s *ClientStream) Context() context.Context

Context returns the context for the stream.

func (*ClientStream) ReceiveMessage added in v1.27.0 

func (s *ClientStream) ReceiveMessage(ctx context.Context) (*StreamMessage, error)

ReceiveMessage blocks until a message is received from the connection. It returns an io.Reader with the contents of the message.

func (*ClientStream) Request added in v1.27.0 

func (s *ClientStream) Request() *StreamRequest

Request contains all the metadata about the request.

func (*ClientStream) SendMessage added in v1.27.0 

func (s *ClientStream) SendMessage(ctx context.Context, msg *StreamMessage) error

SendMessage sends a request over the stream. It blocks until the message has been sent. In certain implementations, the timeout on the context will be used to timeout the request.

type ClientStreamOption added in v1.27.0 

type ClientStreamOption interface {
	// contains filtered or unexported methods
}

ClientStreamOption is an option for configuring a client stream. There are no current ClientStreamOptions implemented.

type CreateOpenTracingSpan 

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

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
	ExtraTags         opentracing.Tags
}

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 NewStreamHandlerSpec added in v1.27.0 

func NewStreamHandlerSpec(handler StreamHandler) HandlerSpec

NewStreamHandlerSpec returns an new HandlerSpec with a StreamHandler

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) Stream added in v1.27.0 

func (h HandlerSpec) Stream() StreamHandler

Stream returns the Stream 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) OriginalItems added in v1.28.0 

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

OriginalItems returns the non-canonicalized version of the underlying map for this Headers object. The returned map MUST NOT be changed. Doing so will result in undefined behavior.

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 OutboundConfig added in v1.24.0 

type OutboundConfig struct {
	CallerName string
	Outbounds  Outbounds
}

OutboundConfig is a configuration for how to call into another service. It is used in conjunction with an encoding to send a request through one of the outbounds.

func (*OutboundConfig) Caller added in v1.24.0 

func (o *OutboundConfig) Caller() string

Caller is the name of the service making the request.

Implements ClientConfig#Caller (for backwards compatibility).

func (*OutboundConfig) GetOnewayOutbound added in v1.24.0 

func (o *OutboundConfig) GetOnewayOutbound() OnewayOutbound

GetOnewayOutbound returns an outbound to send the request through or panics if there is no oneway outbound for this service.

Implements ClientConfig#GetOnewayOutbound.

func (*OutboundConfig) GetUnaryOutbound added in v1.24.0 

func (o *OutboundConfig) GetUnaryOutbound() UnaryOutbound

GetUnaryOutbound returns an outbound to send the request through or panics if there is no unary outbound for this service.

Implements ClientConfig#GetUnaryOutbound.

func (*OutboundConfig) Service added in v1.24.0 

func (o *OutboundConfig) Service() string

Service is the name of the service to which the request is being made.

Implements ClientConfig#Service (for backwards compatibility).

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

	// If set, this is the stream outbound which creates a ClientStream that can
	// be used to continuously send/recv requests over the connection.
	Stream StreamOutbound
}

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.

func (*Request) ToRequestMeta added in v1.27.0 

func (r *Request) ToRequestMeta() *RequestMeta

ToRequestMeta converts a Request into a RequestMeta.

type RequestMeta added in v1.27.0 

type RequestMeta 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
}

RequestMeta is the low level request metadata representation. It does not include any "body" information, and should only be used for information about a connection's metadata.

func (*RequestMeta) ToRequest added in v1.27.0 

func (r *RequestMeta) ToRequest() *Request

ToRequest converts a RequestMeta into a Request.

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 ServerStream added in v1.27.0 

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

ServerStream represents the Server API of interacting with a Stream.

func NewServerStream added in v1.27.0 

func NewServerStream(s Stream, options ...ServerStreamOption) (*ServerStream, error)

NewServerStream will create a new ServerStream.

func (*ServerStream) Context added in v1.27.0 

func (s *ServerStream) Context() context.Context

Context returns the context for the stream.

func (*ServerStream) ReceiveMessage added in v1.27.0 

func (s *ServerStream) ReceiveMessage(ctx context.Context) (*StreamMessage, error)

ReceiveMessage blocks until a message is received from the connection. It returns an io.Reader with the contents of the message.

func (*ServerStream) Request added in v1.27.0 

func (s *ServerStream) Request() *StreamRequest

Request contains all the metadata about the request.

func (*ServerStream) SendMessage added in v1.27.0 

func (s *ServerStream) SendMessage(ctx context.Context, msg *StreamMessage) error

SendMessage sends a request over the stream. It blocks until the message has been sent. In certain implementations, the timeout on the context will be used to timeout the request.

type ServerStreamOption added in v1.27.0 

type ServerStreamOption interface {
	// contains filtered or unexported methods
}

ServerStreamOption are options to configure a ServerStream. There are no current ServerStreamOptions implemented.

type Stream added in v1.27.0 

type Stream interface {
	// Context returns the context for the stream.
	Context() context.Context

	// Request contains all the metadata about the request.
	Request() *StreamRequest

	// SendMessage sends a request over the stream. It blocks until the message
	// has been sent.  In certain implementations, the timeout on the context
	// will be used to timeout the request.
	SendMessage(context.Context, *StreamMessage) error

	// ReceiveMessage blocks until a message is received from the connection. It
	// returns an io.Reader with the contents of the message.
	ReceiveMessage(context.Context) (*StreamMessage, error)
}

Stream is an interface for interacting with a stream.

type StreamCloser added in v1.27.0 

type StreamCloser interface {
	Stream

	// Close will close the connection. It blocks until the server has
	// acknowledged the close. The provided context controls the timeout for
	// this operation if the implementation supports it. If the server timed out
	// the connection will be forced closed by the client.
	Close(context.Context) error
}

StreamCloser represents an API of interacting with a Stream that is closable.

type StreamHandler added in v1.27.0 

type StreamHandler interface {
	// Handle the given stream connection.  The stream will close when the
	// function returns.
	//
	// An error may be returned in case of failures.
	HandleStream(stream *ServerStream) error
}

StreamHandler handles a stream connection request.

type StreamMessage added in v1.27.0 

type StreamMessage struct {
	Body io.ReadCloser
}

StreamMessage represents information that can be read off of an individual message in the stream.

type StreamOutbound added in v1.27.0 

type StreamOutbound interface {
	Outbound

	// CallStream creates a stream connection based on the metadata in the
	// request passed in.  If there is a timeout on the context, this timeout
	// is for establishing a connection, and not for the lifetime of the stream.
	CallStream(ctx context.Context, request *StreamRequest) (*ClientStream, error)
}

StreamOutbound is a transport that knows how to send stream requests for procedure calls.

type StreamRequest added in v1.27.0 

type StreamRequest struct {
	Meta *RequestMeta
}

StreamRequest represents a streaming request. It contains basic stream metadata.

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
	// Streaming types are Stream based RPCs (bidirectional messages over long
	// lived connections)
	Streaming
)

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.