protocol

Documentation

Overview

Package protocol defines interfaces to decouple the client package from protocol implementations.

Most event sender and receiver applications should not use this package, they should use the client package. This package is for infrastructure developers implementing new transports, or intermediary components like importers, channels or brokers.

Available protocols:

* HTTP (using net/http) * Kafka (using github.com/Shopify/sarama) * AMQP (using pack.ag/amqp) * Go Channels * Nats * Nats Streaming (stan) * Google PubSub

Index

• Variables
• func IsACK(target Result) bool
• func IsNACK(target Result) bool
• func IsUndelivered(target Result) bool
• type Closer
• type ErrTransportMessageConversion
  • func NewErrTransportMessageConversion(transport, message string, handled, fatal bool) *ErrTransportMessageConversion
  • func (e *ErrTransportMessageConversion) Error() string
  • func (e *ErrTransportMessageConversion) Handled() bool
  • func (e *ErrTransportMessageConversion) IsFatal() bool
• type Opener
• type Receipt
  • func (e *Receipt) Error() string
  • func (e *Receipt) Is(target error) bool
  • func (e *Receipt) Unwrap() error
• type ReceiveCloser
• type Receiver
• type Requester
• type RequesterCloser
• type Responder
• type ResponderCloser
• type ResponseFn
• type Result
  • func NewReceipt(ack bool, messageFmt string, args ...interface{}) Result
  • func NewResult(messageFmt string, args ...interface{}) Result
• type SendCloser
• type Sender

Variables

var (
	ResultACK  = NewReceipt(true, "")
	ResultNACK = NewReceipt(false, "")
)

var ResultAs = errors.As

ResultAs finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil. (text from errors/wrap.go)

var ResultIs = errors.Is

ResultIs reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true. (text from errors/wrap.go)

Functions

func IsACK

func IsACK(target Result) bool

IsACK true means the recipient acknowledged the event.

func IsNACK

func IsNACK(target Result) bool

IsNACK true means the recipient did not acknowledge the event.

func IsUndelivered

func IsUndelivered(target Result) bool

IsUndelivered true means the target result is not an ACK/NACK, but some other error unrelated to delivery not from the intended recipient. Likely target is an error that represents some part of the protocol is misconfigured or the event that was attempting to be sent was invalid.

Types

type Closer

type Closer interface {
	Close(ctx context.Context) error
}

Closer is the common interface for things that can be closed. After invoking Close(ctx), you cannot reuse the object you closed.

type ErrTransportMessageConversion

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

ErrTransportMessageConversion is an error produced when the transport message can not be converted.

func NewErrTransportMessageConversion

func NewErrTransportMessageConversion(transport, message string, handled, fatal bool) *ErrTransportMessageConversion

NewErrTransportMessageConversion makes a new ErrTransportMessageConversion.

func (*ErrTransportMessageConversion) Error

func (e *ErrTransportMessageConversion) Error() string

Error implements error.Error

func (*ErrTransportMessageConversion) Handled

func (e *ErrTransportMessageConversion) Handled() bool

Handled reports if this error should be considered accepted and no further action.

func (*ErrTransportMessageConversion) IsFatal

func (e *ErrTransportMessageConversion) IsFatal() bool

IsFatal reports if this error should be considered fatal.

type Opener

type Opener interface {
	// OpenInbound is a blocking call and ctx is used to stop the Inbound message Receiver/Responder.
	// Closing the context won't close the Receiver/Responder, aka it won't invoke Close(ctx).
	OpenInbound(ctx context.Context) error
}

Opener is the common interface for things that need to be opened.

type Receipt

type Receipt struct {
	Err error
	ACK bool
}

Receipt wraps the fields required to understand if a protocol event is acknowledged.

func (*Receipt) Error

func (e *Receipt) Error() string

Error returns the string that is formed by using the format string with the provided args.

func (*Receipt) Is

func (e *Receipt) Is(target error) bool

Is returns if the target error is a Result type checking target.

func (*Receipt) Unwrap

func (e *Receipt) Unwrap() error

Unwrap returns the wrapped error if exist or nil

type ReceiveCloser

type ReceiveCloser interface {
	Receiver
	Closer
}

ReceiveCloser is a Receiver that can be closed.

type Receiver

type Receiver interface {
	// Receive blocks till a message is received or ctx expires.
	//
	// A non-nil error means the receiver is closed.
	// io.EOF means it closed cleanly, any other value indicates an error.
	// The caller is responsible for `Finish()` the returned message
	Receive(ctx context.Context) (binding.Message, error)
}

Receiver receives messages.

type Requester

type Requester interface {
	// Request sends m like Sender.Send() but also arranges to receive a response.
	Request(ctx context.Context, m binding.Message, transformers ...binding.Transformer) (binding.Message, error)
}

Requester sends a message and receives a response

Optional interface that may be implemented by protocols that support request/response correlation.

type RequesterCloser

type RequesterCloser interface {
	Requester
	Closer
}

RequesterCloser is a Requester that can be closed.

type Responder

type Responder interface {
	// Receive blocks till a message is received or ctx expires.
	//
	// A non-nil error means the receiver is closed.
	// io.EOF means it closed cleanly, any other value indicates an error.
	// The caller is responsible for `Finish()` the returned message,
	// while the protocol implementation is responsible for `Finish()` the response message.
	// The caller MUST invoke ResponseFn, in order to avoid leaks.
	// The correct flow for the caller is to finish the received message and then invoke the ResponseFn
	Respond(ctx context.Context) (binding.Message, ResponseFn, error)
}

Responder receives messages and is given a callback to respond.

type ResponderCloser

type ResponderCloser interface {
	Responder
	Closer
}

ResponderCloser is a Responder that can be closed.

type ResponseFn

type ResponseFn func(ctx context.Context, m binding.Message, r Result, transformers ...binding.Transformer) error

ResponseFn is the function callback provided from Responder.Respond to allow for a receiver to "reply" to a message it receives. transformers are applied when the message is written on the wire.

type Result

type Result error

Result leverages go's 1.13 error wrapping.

func NewReceipt

func NewReceipt(ack bool, messageFmt string, args ...interface{}) Result

NewReceipt returns a fully populated protocol Receipt that should be used as a transport.Result. This type holds the base ACK/NACK results.

func NewResult

func NewResult(messageFmt string, args ...interface{}) Result

type SendCloser

type SendCloser interface {
	Sender
	Closer
}

SendCloser is a Sender that can be closed.

type Sender

type Sender interface {
	// Send a message.
	//
	// Send returns when the "outbound" message has been sent. The Sender may
	// still be expecting acknowledgment or holding other state for the message.
	//
	// m.Finish() is called when sending is finished (both succeeded or failed):
	// expected acknowledgments (or errors) have been received, the Sender is
	// no longer holding any state for the message.
	// m.Finish() may be called during or after Send().
	//
	// transformers are applied when the message is written on the wire.
	Send(ctx context.Context, m binding.Message, transformers ...binding.Transformer) error
}

Sender sends messages.