transport

package
v1.0.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Nov 23, 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 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 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 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 added in v0.5.0 

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

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

func ApplyOnewayInboundMiddleware 

func ApplyOnewayInboundMiddleware(h OnewayHandler, i OnewayInboundMiddleware) OnewayHandler

ApplyOnewayInboundMiddleware applies the given OnewayInboundMiddleware to the given OnewayHandler.

type OnewayInboundMiddleware 

type OnewayInboundMiddleware interface {
	HandleOneway(ctx context.Context, req *Request, h OnewayHandler) error
}

OnewayInboundMiddleware defines a transport-level middleware for `OnewayHandler`s.

OnewayInboundMiddleware MAY

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

OnewayInboundMiddleware MUST be thread-safe.

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

var NopOnewayInboundMiddleware OnewayInboundMiddleware = nopOnewayInboundMiddleware{}

NopOnewayInboundMiddleware is an inbound middleware that does not do anything special. It simply calls the underlying OnewayHandler.

type OnewayInboundMiddlewareFunc 

type OnewayInboundMiddlewareFunc func(context.Context, *Request, OnewayHandler) error

OnewayInboundMiddlewareFunc adapts a function into a OnwayInboundMiddleware.

func (OnewayInboundMiddlewareFunc) HandleOneway 

func (f OnewayInboundMiddlewareFunc) HandleOneway(ctx context.Context, req *Request, h OnewayHandler) error

HandleOneway for OnewayInboundMiddlewareFunc

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.

func ApplyOnewayOutboundMiddleware 

func ApplyOnewayOutboundMiddleware(o OnewayOutbound, f OnewayOutboundMiddleware) OnewayOutbound

ApplyOnewayOutboundMiddleware applies the given OnewayOutboundMiddleware to the given OnewayOutbound.

type OnewayOutboundMiddleware 

type OnewayOutboundMiddleware interface {
	CallOneway(ctx context.Context, request *Request, out OnewayOutbound) (Ack, error)
}

OnewayOutboundMiddleware defines transport-level middleware for `OnewayOutbound`s.

OnewayOutboundMiddleware MAY

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

OnewayOutboundMiddleware MUST

- always return an Ack (nil or not) or an error. - be thread-safe

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

var NopOnewayOutboundMiddleware OnewayOutboundMiddleware = nopOnewayOutboundMiddleware{}

NopOnewayOutboundMiddleware is a oneway outbound middleware that does not do anything special. It simply calls the underlying OnewayOutbound.

type OnewayOutboundMiddlewareFunc 

type OnewayOutboundMiddlewareFunc func(context.Context, *Request, OnewayOutbound) (Ack, error)

OnewayOutboundMiddlewareFunc adapts a function into a OnewayOutboundMiddleware.

func (OnewayOutboundMiddlewareFunc) CallOneway 

func (f OnewayOutboundMiddlewareFunc) CallOneway(ctx context.Context, request *Request, out OnewayOutbound) (Ack, error)

CallOneway for OnewayOutboundMiddlewareFunc.

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

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

func ApplyUnaryInboundMiddleware(h UnaryHandler, i UnaryInboundMiddleware) UnaryHandler

ApplyUnaryInboundMiddleware applies the given InboundMiddleware to the given Handler.

type UnaryInboundMiddleware 

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

UnaryInboundMiddleware defines a transport-level middleware for `UnaryHandler`s.

UnaryInboundMiddleware 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

UnaryInboundMiddleware MUST be thread-safe.

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

var NopUnaryInboundMiddleware UnaryInboundMiddleware = nopUnaryInboundMiddleware{}

NopUnaryInboundMiddleware is a inbound middleware that does not do anything special. It simply calls the underlying Handler.

type UnaryInboundMiddlewareFunc 

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

UnaryInboundMiddlewareFunc adapts a function into an InboundMiddleware.

func (UnaryInboundMiddlewareFunc) Handle 

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

Handle for UnaryInboundMiddlewareFunc

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 ApplyUnaryOutboundMiddleware 

func ApplyUnaryOutboundMiddleware(o UnaryOutbound, f UnaryOutboundMiddleware) UnaryOutbound

ApplyUnaryOutboundMiddleware applies the given UnaryOutboundMiddleware to the given UnaryOutbound.

type UnaryOutboundMiddleware 

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

UnaryOutboundMiddleware defines transport-level middleware for `UnaryOutbound`s.

UnaryOutboundMiddleware MAY

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

UnaryOutboundMiddleware MUST

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

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

var NopUnaryOutboundMiddleware UnaryOutboundMiddleware = nopUnaryOutboundMiddleware{}

NopUnaryOutboundMiddleware is a unary outbound middleware that does not do anything special. It simply calls the underlying UnaryOutbound.

type UnaryOutboundMiddlewareFunc 

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

UnaryOutboundMiddlewareFunc adapts a function into a UnaryOutboundMiddleware.

func (UnaryOutboundMiddlewareFunc) Call 

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

Call for UnaryOutboundMiddlewareFunc.

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