transport

Documentation

Overview

Package transport implements the low level concerns of sending and receiving bytes.

Index

• func CanonicalizeHeaderKey(k string) string
• func IsBadRequestError(err error) bool
• func IsTimeoutError(err error) bool
• func IsUnexpectedError(err error) bool
• type Ack
• type Channel
• type ChannelProvider
• type Deps
  • func (d Deps) Tracer() opentracing.Tracer
  • func (d Deps) WithTracer(t opentracing.Tracer) Deps
• type Encoding
• type Filter
• type FilterFunc
  • func (f FilterFunc) Call(ctx context.Context, request *Request, out UnaryOutbound) (*Response, error)
• type HandlerSpec
  • func NewOnewayHandlerSpec(handler OnewayHandler) HandlerSpec
  • func NewUnaryHandlerSpec(handler UnaryHandler) HandlerSpec
  • func (h HandlerSpec) Oneway() OnewayHandler
  • func (h HandlerSpec) Type() Type
  • func (h HandlerSpec) Unary() UnaryHandler
• type Headers
  • func HeadersFromMap(m map[string]string) Headers
  • func NewHeaders() Headers
  • func NewHeadersWithCapacity(capacity int) Headers
  • func (h Headers) Del(k string)
  • func (h Headers) Get(k string) (string, bool)
  • func (h Headers) Items() map[string]string
  • func (h Headers) Len() int
  • func (h Headers) With(k, v string) Headers
• type Inbound
• type Interceptor
• type InterceptorFunc
  • func (f InterceptorFunc) Handle(ctx context.Context, req *Request, resw ResponseWriter, h UnaryHandler) error
• type MapRegistry
  • func NewMapRegistry(defaultService string) MapRegistry
  • func (m MapRegistry) Choose(ctx context.Context, req *Request) (HandlerSpec, error)
  • func (m MapRegistry) ChooseProcedure(service, procedure string) (HandlerSpec, error)
  • func (m MapRegistry) Register(rs []Registrant)
  • func (m MapRegistry) ServiceProcedures() []ServiceProcedure
• type OnewayHandler
• type OnewayOutbound
• type Outbound
• type Outbounds
• type Registrant
• type Registrar
• type Registry
• type Request
• type Response
• type ResponseWriter
• type ServiceDetail
• type ServiceProcedure
• type Type
  • func (i Type) String() string
• type UnaryHandler
  • func ApplyInterceptor(h UnaryHandler, i Interceptor) UnaryHandler
• type UnaryOutbound
  • func ApplyFilter(o UnaryOutbound, f Filter) UnaryOutbound

Functions

func CanonicalizeHeaderKey

func CanonicalizeHeaderKey(k string) string

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

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.

Types

type Ack

type Ack interface {
	String() string
}

Ack represents and acknowledgement from a oneway request

type Channel

type Channel 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 Channel is a stream of communication between a single caller-service pair.

type ChannelProvider

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

ChannelProvider builds channels from the current service to other services.

type Deps

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

Deps is a struct shared by all inbounds and outbounds in the context of a dispatcher. The dispatcher starts every transport with these dependencies. A zero Deps struct is suitable for testing and provides noop implementations of all dependencies.

var NoDeps Deps

NoDeps is a singleton zero Deps instance.

func (Deps) Tracer

func (d Deps) Tracer() opentracing.Tracer

Tracer provides the opentracing Tracer instance needed by transports.

func (Deps) WithTracer

func (d Deps) WithTracer(t opentracing.Tracer) Deps

WithTracer returns a variant of these dependencies with a given opentracing Tracer.

type Encoding

type Encoding string

Encoding represents an encoding format for requests.

type Filter

type Filter interface {
	Call(ctx context.Context, request *Request, out UnaryOutbound) (*Response, error)
}

Filter defines transport-level middleware for Outbounds.

Filters MAY

- change the context - change the request - change the returned response - handle the returned error - call the given outbound zero or more times

Filters MUST

- always return a non-nil Response or error. - be thread-safe

Filters are re-used across requests and MAY be called multiple times on the same request.

var NopFilter Filter = nopFilter{}

NopFilter is a filter that does not do anything special. It simply calls the underlying Outbound.

type FilterFunc

type FilterFunc func(context.Context, *Request, UnaryOutbound) (*Response, error)

FilterFunc adapts a function into a Filter.

func (FilterFunc) Call

func (f FilterFunc) Call(ctx context.Context, request *Request, out UnaryOutbound) (*Response, error)

Call for FilterFunc.

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 {
	// Starts accepting new requests and dispatches them using the given
	// service configuration.
	//
	// 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(service ServiceDetail, deps Deps) 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 Interceptor

type Interceptor interface {
	Handle(ctx context.Context, req *Request, resw ResponseWriter, h UnaryHandler) error
}

Interceptor defines a transport-level middleware for Inbounds.

Interceptors MAY

- change the context - change the request - call the ResponseWriter - modify the response body by wrapping the ResponseWriter - handle the returned error - call the given handler zero or more times

Interceptors MUST be thread-safe.

Interceptors are re-used across requests and MAY be called multiple times for the same request.

var NopInterceptor Interceptor = nopInterceptor{}

NopInterceptor is a interceptor that does not do anything special. It simply calls the underlying Handler.

type InterceptorFunc

type InterceptorFunc func(context.Context, *Request, ResponseWriter, UnaryHandler) error

InterceptorFunc adapts a function into an Interceptor.

func (InterceptorFunc) Handle

func (f InterceptorFunc) Handle(ctx context.Context, req *Request, resw ResponseWriter, h UnaryHandler) error

Handle for InterceptorFunc

type MapRegistry

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

MapRegistry is a Registry that maintains a map of the registered procedures.

func NewMapRegistry

func NewMapRegistry(defaultService string) MapRegistry

NewMapRegistry builds a new MapRegistry that uses the given name as the default service name.

func (MapRegistry) Choose

func (m MapRegistry) Choose(ctx context.Context, req *Request) (HandlerSpec, error)

Choose retrives the HandlerSpec for the service and procedure noted on the transport request, or returns an error.

func (MapRegistry) ChooseProcedure

func (m MapRegistry) ChooseProcedure(service, procedure string) (HandlerSpec, error)

ChooseProcedure retrieves the HandlerSpec for the given Procedure or returns an error.

func (MapRegistry) Register

func (m MapRegistry) Register(rs []Registrant)

Register registers the procedure with the MapRegistry.

func (MapRegistry) ServiceProcedures

func (m MapRegistry) ServiceProcedures() []ServiceProcedure

ServiceProcedures returns a list of services and their procedures that have been registered so far.

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 {
	// 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(deps Deps) 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 ServiceDetail

type ServiceDetail struct {
	// Name of the service being served.
	Name string

	// Registry of procedures that this service offers.
	Registry Registry
}

ServiceDetail specifies the service that an Inbound must serve.

type ServiceProcedure

type ServiceProcedure struct {
	Service   string
	Procedure string
}

ServiceProcedure represents a service and procedure registered against a Registry.

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.

func ApplyInterceptor

func ApplyInterceptor(h UnaryHandler, i Interceptor) UnaryHandler

ApplyInterceptor applies the given Interceptor to the given Handler.

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.

func ApplyFilter

func ApplyFilter(o UnaryOutbound, f Filter) UnaryOutbound

ApplyFilter applies the given Filter to the given Outbound.