binding

package
v2.0.0-preview6 Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2020 License: Apache-2.0 Imports: 9 Imported by: 132

Documentation

Index

Constants

View Source 
const (
	SKIP_DIRECT_STRUCTURED_ENCODING = "SKIP_DIRECT_STRUCTURED_ENCODING"
	SKIP_DIRECT_BINARY_ENCODING     = "SKIP_DIRECT_BINARY_ENCODING"
	PREFERRED_EVENT_ENCODING        = "PREFERRED_EVENT_ENCODING"
)
View Source 
const (
	FORMAT_EVENT_STRUCTURED = "FORMAT_EVENT_STRUCTURED"
)

Variables

View Source 
var ErrCannotConvertToEvent = errors.New("cannot convert message to event")

Generic error when a conversion of a Message to an Event fails

View Source 
var ErrNotBinary = errors.New("message is not in binary mode")

ErrNotBinary returned by Message.Binary for non-binary messages.

View Source 
var ErrNotStructured = errors.New("message is not in structured mode")

ErrNotStructured returned by Message.Structured for non-structured messages.

View Source 
var ErrUnknownEncoding = errors.New("unknown Message encoding")

Error to specify that or the Message is not an event or it is encoded with an unknown encoding

Functions

func GetOrDefaultFromCtx 

func GetOrDefaultFromCtx(ctx context.Context, key string, def interface{}) interface{}

Get a configuration value from the provided context

func ToEvent 

func ToEvent(ctx context.Context, message MessageReader, transformers ...TransformerFactory) (*event.Event, error)

Translates a Message with a valid Structured or Binary representation to an Event. This function returns the Event generated from the Message and the original encoding of the message or an error that points the conversion error. transformers can be nil and this function guarantees that they are invoked only once during the encoding process.

func UseFormatForEvent 

func UseFormatForEvent(ctx context.Context, f format.Format) context.Context

Configure which format to use when marshalling the event to structured mode

func WithForceBinary 

func WithForceBinary(ctx context.Context) context.Context

Force binary encoding during the encoding process

func WithForceStructured 

func WithForceStructured(ctx context.Context) context.Context

Force structured encoding during the encoding process

func WithPreferredEventEncoding 

func WithPreferredEventEncoding(ctx context.Context, enc Encoding) context.Context

Define the preferred encoding from event to message during the encoding process

func WithSkipDirectBinaryEncoding 

func WithSkipDirectBinaryEncoding(ctx context.Context, skip bool) context.Context

Skip direct binary to binary encoding during the encoding process

func WithSkipDirectStructuredEncoding 

func WithSkipDirectStructuredEncoding(ctx context.Context, skip bool) context.Context

Skip direct structured to structured encoding during the encoding process

Types

type BinaryWriter 

type BinaryWriter interface {
	// Method invoked at the beginning of the visit. Useful to perform initial memory allocations
	Start(ctx context.Context) error

	// Set a standard attribute.
	//
	// The value can either be the correct golang type for the attribute, or a canonical
	// string encoding. See package types to perform the needed conversions
	SetAttribute(attribute spec.Attribute, value interface{}) error

	// Set an extension attribute.
	//
	// The value can either be the correct golang type for the attribute, or a canonical
	// string encoding. See package types to perform the needed conversions
	SetExtension(name string, value interface{}) error

	// SetData receives an io.Reader for the data attribute.
	// io.Reader is not invoked when the data attribute is empty
	SetData(data io.Reader) error

	// End method is invoked only after the whole encoding process ends successfully.
	// If it fails, it's never invoked. It can be used to finalize the message.
	End(ctx context.Context) error
}

BinaryWriter is used to visit a binary Message and generate a new representation.

Protocols that supports binary encoding should implement this interface to implement direct binary to binary encoding and event to binary encoding.

Start() and End() methods are invoked every time this BinaryWriter implementation is used to visit a Message

type Encoding 

type Encoding int

Encoding enum specifies the type of encodings supported by binding interfaces 

const (
	// Binary encoding as specified in https://github.com/cloudevents/spec/blob/master/spec.md#message
	EncodingBinary Encoding = iota
	// Structured encoding as specified in https://github.com/cloudevents/spec/blob/master/spec.md#message
	EncodingStructured
	// Message is an instance of EventMessage or it contains EventMessage nested (through MessageWrapper)
	EncodingEvent
	// When the encoding is unknown (which means that the message is a non-event)
	EncodingUnknown
)

func DirectWrite 

func DirectWrite(
	ctx context.Context,
	message MessageReader,
	structuredWriter StructuredWriter,
	binaryWriter BinaryWriter,
	transformers ...TransformerFactory,
) (Encoding, error)

Invokes the encoders. structuredWriter and binaryWriter could be nil if the protocol doesn't support it. transformers can be nil and this function guarantees that they are invoked only once during the encoding process.

Returns: * EncodingStructured, nil if message is correctly encoded in structured encoding * EncodingBinary, nil if message is correctly encoded in binary encoding * EncodingStructured, err if message was structured but error happened during the encoding * EncodingBinary, err if message was binary but error happened during the encoding * EncodingUnknown, ErrUnknownEncoding if message is not a structured or a binary Message

func Write 

func Write(
	ctx context.Context,
	message MessageReader,
	structuredWriter StructuredWriter,
	binaryWriter BinaryWriter,
	transformers ...TransformerFactory,
) (Encoding, error)

This is the full algorithm to encode a Message using transformers: 1. It first tries direct encoding using DirectWrite 2. If no direct encoding is possible, it uses ToEvent to generate an Event representation 3. From the Event, the message is encoded back to the provided structured or binary encoders You can tweak the encoding process using the context decorators WithForceStructured, WithForceStructured, etc. transformers can be nil and this function guarantees that they are invoked only once during the encoding process. Returns: * EncodingStructured, nil if message is correctly encoded in structured encoding * EncodingBinary, nil if message is correctly encoded in binary encoding * EncodingUnknown, ErrUnknownEncoding if message.ReadEncoding() == EncodingUnknown * _, err if error happened during the encoding

type EventMessage 

type EventMessage event.Event

EventMessage type-converts a event.Event object to implement Message. This allows local event.Event objects to be sent directly via Sender.Send() 

s.Send(ctx, binding.EventMessage(e))

When an event is wrapped into a EventMessage, the original event could be potentially mutated. If you need to use the Event again, after wrapping it into an Event message, you should copy it before

func (*EventMessage) Finish 

func (*EventMessage) Finish(error) error

func (*EventMessage) ReadBinary 

func (m *EventMessage) ReadBinary(ctx context.Context, b BinaryWriter) (err error)

func (*EventMessage) ReadEncoding 

func (m *EventMessage) ReadEncoding() Encoding

func (*EventMessage) ReadStructured 

func (m *EventMessage) ReadStructured(ctx context.Context, builder StructuredWriter) error

type EventTransformer 

type EventTransformer func(*event.Event) error

EventTransformer mutates the provided Event

type ExactlyOnceMessage 

type ExactlyOnceMessage interface {
	Message

	// Received is called by a forwarding QoS2 Sender when it gets
	// acknowledgment of receipt (e.g. AMQP 'accept' or MQTT PUBREC)
	//
	// The receiver must call settle(nil) when it get's the ack-of-ack
	// (e.g. AMQP 'settle' or MQTT PUBCOMP) or settle(err) if the
	// transfer fails.
	//
	// Finally the Sender calls Finish() to indicate the message can be
	// discarded.
	//
	// If sending fails, or if the sender does not support QoS 2, then
	// Finish() may be called without any call to Received()
	Received(settle func(error))
}

ExactlyOnceMessage is implemented by received Messages that support QoS 2. Only transports that support QoS 2 need to implement or use this interface.

type Message 

type Message interface {
	MessageReader

	// Finish *must* be called when message from a Receiver can be forgotten by
	// the receiver. A QoS 1 sender should not call Finish() until it gets an acknowledgment of
	// receipt on the underlying transport.  For QoS 2 see ExactlyOnceMessage.
	//
	// Note that, depending on the Message implementation, forgetting to Finish the message
	// could produce memory/resources leaks!
	//
	// Passing a non-nil err indicates sending or processing failed.
	// A non-nil return indicates that the message was not accepted
	// by the receivers peer.
	Finish(error) error
}

Message is the interface to a binding-specific message containing an event.

Reliable Delivery

There are 3 reliable qualities of service for messages:

0/at-most-once/unreliable: messages can be dropped silently.

1/at-least-once: messages are not dropped without signaling an error to the sender, but they may be duplicated in the event of a re-send.

2/exactly-once: messages are never dropped (without error) or duplicated, as long as both sending and receiving ends maintain some binding-specific delivery state. Whether this is persisted depends on the configuration of the binding implementations.

The Message interface supports QoS 0 and 1, the ExactlyOnceMessage interface supports QoS 2

Message includes the MessageReader interface to read messages. Every binding.Message implementation *must* specify if the message can be accessed one or more times.

When a Message can be forgotten by the entity who produced the message, Message.Finish() *must* be invoked.

func ToMessage 

func ToMessage(e *event.Event) Message

func WithFinish 

func WithFinish(m Message, finish func(error)) Message

WithFinish returns a wrapper for m that calls finish() and m.Finish() in its Finish(). Allows code to be notified when a message is Finished.

type MessageReader 

type MessageReader interface {
	// Return the type of the message Encoding.
	// The encoding should be preferably computed when the message is constructed.
	ReadEncoding() Encoding

	// ReadStructured transfers a structured-mode event to a StructuredWriter.
	// It must return ErrNotStructured if message is not in structured mode.
	//
	// Returns a different err if something wrong happened while trying to read the structured event.
	// In this case, the caller must Finish the message with appropriate error.
	//
	// This allows Senders to avoid re-encoding messages that are
	// already in suitable structured form.
	ReadStructured(context.Context, StructuredWriter) error

	// ReadBinary transfers a binary-mode event to an BinaryWriter.
	// It must return ErrNotBinary if message is not in binary mode.
	//
	// Returns a different err if something wrong happened while trying to read the binary event
	// In this case, the caller must Finish the message with appropriate error
	//
	// This allows Senders to avoid re-encoding messages that are
	// already in suitable binary form.
	ReadBinary(context.Context, BinaryWriter) error
}

The ReadStructured and ReadBinary methods allows to perform an optimized encoding of a Message to a specific data structure. A Sender should try each method of interest and fall back to binding.ToEvent() if none are supported. An out of the box algorithm is provided for writing a message: binding.Write().

type MessageWrapper 

type MessageWrapper interface {
	Message

	// Method to get the wrapped message
	GetWrappedMessage() Message
}

Message Wrapper interface is used to walk through a decorated Message and unwrap it.

type StructuredWriter 

type StructuredWriter interface {
	// Event receives an io.Reader for the whole event.
	SetStructuredEvent(ctx context.Context, format format.Format, event io.Reader) error
}

StructuredWriter is used to visit a structured Message and generate a new representation.

Protocols that supports structured encoding should implement this interface to implement direct structured to structured encoding and event to structured encoding.

type TransformerFactories 

type TransformerFactories []TransformerFactory

Utility type alias to manage multiple TransformerFactory

func (TransformerFactories) BinaryTransformer 

func (t TransformerFactories) BinaryTransformer(writer BinaryWriter) BinaryWriter

func (TransformerFactories) EventTransformer 

func (t TransformerFactories) EventTransformer() EventTransformer

func (TransformerFactories) StructuredTransformer 

func (t TransformerFactories) StructuredTransformer(writer StructuredWriter) StructuredWriter

type TransformerFactory 

type TransformerFactory interface {
	// Can return nil if the transformation doesn't support structured encoding directly
	StructuredTransformer(writer StructuredWriter) StructuredWriter

	// Can return nil if the transformation doesn't support binary encoding directly
	BinaryTransformer(writer BinaryWriter) BinaryWriter

	// Can return nil if the transformation doesn't support events
	EventTransformer() EventTransformer
}

Implements a transformation process while transferring the event from the Message implementation to the provided encoder

A transformer could optionally not provide an implementation for binary and/or structured encodings, returning nil to the respective factory method.

Source Files

View all Source files

Directories

Path Synopsis
Package test contains test data and generic tests for testing bindings.
 Package test contains test data and generic tests for testing bindings.

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.