sdk-go/docs/protocol_implementations.md

title	nav_order
Protocol Bindings	4

Protocol Binding implementations

{: .no_toc }

1. TOC {:toc}

Overview

A Protocol binding in sdk-go is implemented defining:

• How to read and write the event back/forth the protocol specific data structured (eg how to read an Event starting from net/http.HttpRequest)
• How to let the protocol interact with the Client

The former is done implementing the Message interface and the Write<DataStructure> functions, while the latter is done implementing specific protocol interfaces.

Protocol implementations

• AMQP Protocol Binding using go-amqp
• HTTP Protocol Binding using net/http
• Kafka Protocol Binding using Sarama
• Kafka Protocol Binding using confluent-kafka-go

  It bring some new features compared the above sarama binding. Like pattern subscription, async message confirmation and other enhancements.

• MQTT Protocol Binding using eclipse/paho.golang
• NATS Protocol Binding using nats.go
• STAN Protocol Binding using stan.go
• PubSub Protocol Binding
• Go channels protocol binding (useful for mocking purpose)

Message interface

Message is the interface to a binding-specific message containing an event. This interface abstracts how to read a CloudEvent starting from a protocol specific data structure.

To convert a Message back and forth to Event, an Event can be wrapped into a Message using binding.ToMessage() and a Message can be converted to Event using binding.ToEvent().

A Message has its own lifecycle:

• Some implementations of Message can be successfully read only one time, because the encoding process drain the message itself. In order to consume a message several times, the buffering module provides several APIs to buffer the Message.
• Every time the Message receiver/emitter can forget the message, Message.Finish() must be invoked.

You can use Messages alone or you can interact with them through the protocol implementations.

Message implementation and Write<DataStructure> functions

Depending on the protocol binding, the Message implementation could support both binary and structured messages.

All protocol implementations provides a function, with a name like NewMessage, to wrap the [3pl][3pl] data structure into the Message implementation. For example, http.NewMessageFromHttpRequest takes an net/http.HttpRequest and wraps it into protocol/http.Message, which implements Message.

Write<DataStructure> functions read a binding.Message and write what is found into the [3pl][3pl] data structure. For example, nats.WriteMsg writes the message into a nats.Msg, or http.WriteRequest writes message into a http.Request.

Transformations

You can perform simple transformations on Message without going through the Event representation using the Transformers.

Some built-in Transformers are provided in the transformer module.

protocol interfaces

Every Protocol implementation provides a set of implemented interfaces to produce/consume messages and implement request/response semantics. Six interfaces are defined:

• Receiver: Interface that produces message, receiving them from the wire.
• Sender: Interface that consumes messages, sending them to the wire.
• Responder: Server side request/response.
• Requester: Client side request/response.
• Opener: Interface that is optionally needed to bootstrap a Receiver/Responder
• Closer: Interface that is optionally needed to close the connection with remote systems

Every protocol implements one or several of them, depending on its capabilities.

[3pl]: 3pl: 3rd party lib (nats.io or net/http)