transport

Documentation

Index

• Variables
• func GenerateID() string
• type GenericMessage
  • func MakeGenericMessage() *GenericMessage
  • func (m *GenericMessage) Close() error
  • func (m *GenericMessage) Headers() map[string]string
  • func (m *GenericMessage) ID() string
  • func (m *GenericMessage) Payload() ([]byte, error)
  • func (m *GenericMessage) Receiver() string
  • func (m *GenericMessage) ReceiverEndpoint() string
  • func (m *GenericMessage) ReceiverVersion() string
  • func (m *GenericMessage) Sender() string
  • func (m *GenericMessage) SenderEndpoint() string
  • func (m *GenericMessage) SetHeader(name, value string)
  • func (m *GenericMessage) SetHeaders(values map[string]string)
  • func (m *GenericMessage) SetPayload(payload []byte, err error)
  • func (m *GenericMessage) SetReceiverVersion(version string)
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) Process(req ImmutableMessage, res Message)
• type ImmutableMessage
• type Message
• type Mode
• type Provider

Variables

var (
	ErrTransportClosed        = errors.New("transport is closed")
	ErrTransportAlreadyDialed = errors.New("transport is already dialed; this operation can only be performed on a closed transport")
)

Transport errors

var (
	ErrNotFound           = errors.New("unknown receiver and/or endpoint")
	ErrTimeout            = errors.New("message delivery timed out")
	ErrServiceUnavailable = errors.New("service unavailable")
	ErrNotAuthorized      = errors.New("not authorized for this operation")
)

Delivery errors

Functions

func GenerateID

func GenerateID() string

GenerateID generates a formatted V1 UUID that can be used as a message ID.

Types

type GenericMessage

type GenericMessage struct {
	IDField               string
	SenderField           string
	ReceiverField         string
	SenderEndpointField   string
	ReceiverEndpointField string
	ReceiverVersionField  string
	HeadersField          map[string]string
	PayloadField          []byte
	ErrField              error
}

GenericMessage provides a re-usable message implementation that implements both Message and ImmutableMessage interfaces. Transports can use this as a basis for their own message implementations.

func MakeGenericMessage

func MakeGenericMessage() *GenericMessage

MakeGenericMessage creates a new GenericMessage instance

func (*GenericMessage) Close

func (m *GenericMessage) Close() error

Close implements io.Closer and should be called when the message is no longer used.

func (*GenericMessage) Headers

func (m *GenericMessage) Headers() map[string]string

Headers returns a map of header values associated with the message.

func (*GenericMessage) ID

func (m *GenericMessage) ID() string

ID returns a UUID for this message.

func (*GenericMessage) Payload

func (m *GenericMessage) Payload() ([]byte, error)

Payload returns the payload associated with the message as a byte slice or an error if one is encoded in the message.

func (*GenericMessage) Receiver

func (m *GenericMessage) Receiver() string

Receiver returns the name of the service that will receive the message.

func (*GenericMessage) ReceiverEndpoint

func (m *GenericMessage) ReceiverEndpoint() string

ReceiverEndpoint returns the receiving service's endpoint.

func (*GenericMessage) ReceiverVersion

func (m *GenericMessage) ReceiverVersion() string

ReceiverVersion returns the requested receiving service's version.

func (*GenericMessage) Sender

func (m *GenericMessage) Sender() string

Sender returns the name of the service that sent the mesage.

func (*GenericMessage) SenderEndpoint

func (m *GenericMessage) SenderEndpoint() string

SenderEndpoint returns the sending service's endpoint.

func (*GenericMessage) SetHeader

func (m *GenericMessage) SetHeader(name, value string)

SetHeader sets the content of a message header to the specified value. If the specified header already exists, its value will be overwritten by the new value.

This function ensures that header names are always canonicalized by passing them through http.CanonicalHeaderKey.

func (*GenericMessage) SetHeaders

func (m *GenericMessage) SetHeaders(values map[string]string)

SetHeaders sets the contents of a batch of headers. This is equivalent to iterating the map and calling SetHeader for each key/value.

func (*GenericMessage) SetPayload

func (m *GenericMessage) SetPayload(payload []byte, err error)

SetPayload sets the content of this message. The content may be either a byte slice or an error message.

func (*GenericMessage) SetReceiverVersion

func (m *GenericMessage) SetReceiverVersion(version string)

SetReceiverVersion sets the requested receiving service's version.

type Handler

type Handler interface {
	Process(req ImmutableMessage, res Message)
}

A Handler responds to an RPC request.

Process is invoked to handle an incoming request. The handler should process the request and must update the response message with either the response payload or an error.

type HandlerFunc

type HandlerFunc func(req ImmutableMessage, res Message)

The HandlerFunc type is an adapter to allow the use of ordinary functions as RPC handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler that calls f.

func (HandlerFunc) Process

func (f HandlerFunc) Process(req ImmutableMessage, res Message)

Process calls f(req, res).

type ImmutableMessage

type ImmutableMessage interface {
	// ImmutableMessage implements io.Closer. All messages should be closed
	// when they are no longer being used.
	io.Closer

	// ID returns a UUID for this message.
	ID() string

	// Sender returns the name of the service that sent the mesage.
	Sender() string

	// SenderEndpoint returns the endpoint where the message originated.
	SenderEndpoint() string

	// Receiver returns the name of the service that will receive the message.
	Receiver() string

	// ReceiverEndpoint returns the endpoint where the message should be delivered at.
	ReceiverEndpoint() string

	// ReceiverVersion returns the requested receiving service's version.
	ReceiverVersion() string

	// Headers returns a map of header values associated with the message.
	Headers() map[string]string

	// Payload returns the payload associated with the message as a byte
	// slice or an error if one is encoded in the message.
	Payload() ([]byte, error)
}

ImmutableMessage defines an interface for a read-only message.

type Message

type Message interface {
	ImmutableMessage

	// SetPayload sets the content of this message. The content may be either
	// a byte slice or an error message.
	SetPayload(payload []byte, err error)

	// SetHeader sets the content of a message header to the specified value.
	// If the specified header already exists, its value will be overwritten
	// by the new value.
	//
	// This method must ensure that header names are always canonicalized
	// using an algorithm similar to http.CanonicalHeaderKey.
	SetHeader(name, value string)

	// SetHeaders sets the contents of a batch of headers. This is equivalent
	// to iterating the map and calling SetHeader for each key/value.
	SetHeaders(headers map[string]string)

	// SetReceiverVersion sets the required version for the receiving service.
	SetReceiverVersion(string)
}

Message defines an interface for messages whose headers and payload can be modified by the sender. Message instances are typically used by clients to send RPC requests or by servers to respond to incoming messages.

type Mode

type Mode bool

Mode describes the way that a transport is being used.

const (
	ModeServer Mode = true
	ModeClient      = false
)

The modes that can be passed to calls to Dial() and Close().

type Provider

type Provider interface {
	// Dial connects to the transport using the specified dial mode. When
	// the dial mode is set to DialModeServer the transport will start
	// relaying messages to registered bindings.
	Dial(mode Mode) error

	// Close terminates a dialed connection using the specified dial mode.
	Close(mode Mode) error

	// Bind listens for messages send to a particular service and
	// endpoint combination and invokes the supplied handler to process them.
	//
	// Transports may implement versioning for bindings in order to support
	// complex deployment flows such as blue-green deployments.
	Bind(version, service, endpoint string, handler Handler) error

	// Unbind removes a message handler previously registered by a call to Bind().
	// Calling Unbind with a (version, service, endpoint) tuple that is not
	// registered has no effect.
	Unbind(version, service, endpoint string)

	// Request performs an RPC and returns back a read-only channel for
	// receiving the result.
	Request(msg Message) <-chan ImmutableMessage
}

Provider defines an interface implemented by transports that can be used by usrv. The transport layer is responsible for the exchange of encoded messages between RPC clients and servers.