transport

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2016 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

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

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 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 added in v0.4.0 

type Ack interface {
	String() string
}

Ack represents and acknowledgement from a oneway request

type Agent added in v0.4.0 

type Agent interface {
	PeerSubscriber

	// Get or create a Peer for the PeerSubscriber
	RetainPeer(PeerIdentifier, PeerSubscriber) (Peer, error)

	// Unallocate a peer from the PeerSubscriber
	ReleasePeer(PeerIdentifier, PeerSubscriber) error
}

Agent manages Peers across different PeerSubscribers. A PeerSubscriber will request a Peer for a specific PeerIdentifier and the Agent has the ability to create a new Peer or return an existing one.

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 added in v0.4.0 

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 added in v0.2.0 

func (d Deps) Tracer() opentracing.Tracer

Tracer provides the opentracing Tracer instance needed by transports.

func (Deps) WithTracer added in v0.2.0 

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 added in v0.4.0 

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 added in v0.4.0 

func NewOnewayHandlerSpec(handler OnewayHandler) HandlerSpec

NewOnewayHandlerSpec returns an new HandlerSpec with a OnewayHandler

func NewUnaryHandlerSpec added in v0.4.0 

func NewUnaryHandlerSpec(handler UnaryHandler) HandlerSpec

NewUnaryHandlerSpec returns an new HandlerSpec with a UnaryHandler

func (HandlerSpec) Oneway added in v0.4.0 

func (h HandlerSpec) Oneway() OnewayHandler

Oneway returns the Oneway Handler or nil

func (HandlerSpec) Type added in v0.4.0 

func (h HandlerSpec) Type() Type

Type returns the associated handler's type

func (HandlerSpec) Unary added in v0.4.0 

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) GetHandlerSpec added in v0.4.0 

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

GetHandlerSpec 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 added in v0.4.0 

func (m MapRegistry) ServiceProcedures() []ServiceProcedure

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

type OnewayHandler added in v0.4.0 

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 added in v0.4.0 

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 Peer added in v0.4.0 

type Peer interface {
	PeerIdentifier

	// Get the status of the Peer
	Status() PeerStatus

	// Tell the peer that a request is starting/ending
	// The callsite should look like:
	//   done := peer.StartRequest()
	//   defer done()
	//   // Do request
	StartRequest() (finish func())
}

Peer is a level on top of PeerIdentifier. It should be created by a PeerAgent so we can maintain multiple references to the same downstream peer (e.g. hostport). This is useful for load balancing requests to downstream services.

type PeerConnectionStatus added in v0.4.0 

type PeerConnectionStatus int

PeerConnectionStatus maintains information about the Peer's connection state 

const (
	// PeerUnavailable indicates the Peer is unavailable for requests
	PeerUnavailable PeerConnectionStatus = iota

	// PeerConnecting indicates the Peer is in the process of connecting
	PeerConnecting

	// PeerAvailable indicates the Peer is available for requests
	PeerAvailable
)

type PeerIdentifier added in v0.4.0 

type PeerIdentifier interface {
	Identifier() string
}

PeerIdentifier is able to uniquely identify a peer (e.g. hostport)

type PeerList added in v0.4.0 

type PeerList interface {
	// Notify the PeerList that it will start receiving requests
	Start() error

	// Notify the PeerList that it will stop receiving requests
	Stop() error

	// Choose a Peer for the next call, block until a peer is available (or timeout)
	ChoosePeer(context.Context, *Request) (Peer, error)
}

PeerList is a collection of Peers. Outbounds request peers from the PeerList to determine where to send requests

type PeerStatus added in v0.4.0 

type PeerStatus struct {
	// Current number of pending requests on this peer
	PendingRequestCount int

	// Current status of the Peer's connection
	ConnectionStatus PeerConnectionStatus
}

PeerStatus holds all the information about a peer's state that would be useful to PeerSubscribers

type PeerSubscriber added in v0.4.0 

type PeerSubscriber interface {
	// The Peer Notifies the PeerSubscriber when its status changes (e.g. connections status, pending requests)
	NotifyStatusChanged(Peer)
}

PeerSubscriber listens to changes of a Peer over time.

type Registrant added in v0.4.0 

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 added in v0.4.0 

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

	// Gets the handler for the given service, procedure tuple. An
	// UnrecognizedProcedureError will be returned if the handler does not
	// exist.
	//
	// service may be empty to indicate that the default service name should
	// be used.
	GetHandlerSpec(service, procedure string) (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 added in v0.4.0 

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 added in v0.4.0 

type ServiceProcedure struct {
	Service   string
	Procedure string
}

ServiceProcedure represents a service and procedure registered against a Registry.

type Type added in v0.4.0 

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 added in v0.4.0 

func (i Type) String() string

type UnaryHandler added in v0.4.0 

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 added in v0.4.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
Package http implements the HTTP inbound and outbound transports for YARPC.
 Package http implements the HTTP inbound and outbound transports for YARPC.
errors
peer
hostport
peerlist
internal

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.