transport

package
v1.0.0-rc3 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2016 License: MIT Imports: 10 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 the Headers map.

func CreateOpenTracingSpan 

func CreateOpenTracingSpan(
	ctx context.Context,
	req *Request,
	tracer opentracing.Tracer,
	transportName string,
	start time.Time,
) (context.Context, opentracing.Span)

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

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 ExtractOpenTracingSpan 

func ExtractOpenTracingSpan(
	ctx context.Context,
	parentSpanCtx opentracing.SpanContext,
	req *Request,
	tracer opentracing.Tracer,
	transportName string,
	start time.Time,
) (context.Context, opentracing.Span)

ExtractOpenTracingSpan 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

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 failed to process the request because of 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

Types

type Ack 

type Ack interface {
	String() string
}

Ack represents and 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 Encoding 

type Encoding string

Encoding represents an encoding format for requests.

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 internal.Headers

Headers is the transport-level representation of application headers.

Keys in the map MUST be canonicalized with CanonicalizeHeaderKey.

You probably want to look at yarpc.Headers instead.

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 builds a new Headers object with the given capacity.

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

Keys in the map are normalized using CanonicalizeHeaderKey.

The returned map MUST NOT be mutated.

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 {
	// SetRegistry configures the inbound to dispatch requests through a
	// registry, typically called by a Dispatcher with its Registrar of handled
	// procedures.
	SetRegistry(Registry)

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

	// Starts accepting new requests.
	//
	// The inbound must have a configured registry.
	//
	// The function MUST return immediately, although it SHOULD block until
	// the inbound is ready to start accepting new requests.
	//
	// Implementations can assume that this function is called at most once.
	Start() error

	// Stops the inbound. No new requests will be processed.
	//
	// This MAY block while the server drains ongoing requests.
	Stop() error
}

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

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

	// Sets up the outbound to start making calls.
	//
	// This MUST block until the outbound is ready to start sending requests.
	// This MUST be idempotent and thread-safe. If called multiple times, only
	// the first call's dependencies are used
	Start() error

	// Stops the outbound, cleaning up any resources held by the Outbound.
	//
	// This MUST be idempotent and thread-safe. This MAY be called more than once
	Stop() error
}

Outbound is the common interface for all outbounds

type Outbounds 

type Outbounds struct {
	Unary  UnaryOutbound
	Oneway OnewayOutbound
}

Outbounds encapsulates outbound types for a service

type Registrant 

type Registrant struct {
	// Service name or empty to use the default service name.
	Service string

	// Name of the procedure.
	Procedure string

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

Registrant specifies a single handler registered against the registry.

type Registrar 

type Registrar interface {
	Registry

	// Registers zero or more registrants with the registry.
	Register([]Registrant)
}

Registrar provides access to a collection of procedures and their handlers.

type Registry 

type Registry interface {
	// ServiceProcedures returns a list of services and their procedures that
	// have been registered so far.
	ServiceProcedures() []ServiceProcedure

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

Registry maintains and provides access to a collection of procedures and their handlers.

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
}

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.

type ServiceProcedure 

type ServiceProcedure struct {
	Service   string
	Procedure string
}

ServiceProcedure represents a service and procedure registered against a Registry.

type Transport 

type Transport interface {
	// Start starts a transport, opening listening sockets and accepting
	// inbound requests, and opening connections to retained outbound peers.
	//
	// Start should block until the transport is ready to receive inbound
	// requests.
	Start() error

	// Stop stops a transport, closing listening sockets, rejecting inbound
	// requests, and draining existing peers of all pending requests.
	//
	// Stop should block until all pending requests have drained.
	Stop() error
}

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