The RabbitMQ Binding for CloudEvents defines how events are mapped to RabbitMQ messages.
This document is a working draft.
- 1.1. Conformance
- 1.2. Relation to RabbitMQ
- 1.3. Content Modes
- 1.4. Event Formats
- 1.5. Security
- 3.1. Binary Content Mode
- 3.2. Structured Content Mode
CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be used in RabbitMQ as RabbitMQ messages.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
This specification does not prescribe rules constraining transfer or settlement of event messages with RabbitMQ; it solely defines how CloudEvents are expressed as RabbitMQ messages.
RabbitMQ supports multiple messaging protocols - AMQP 1.0, AMQP 0-9-1, STOMP, MQTT - and uses AMQP 0-9-1 with extensions as the "core" & default protocol. AMQP 0-9-1 is a binary protocol with strong messaging semantics with wide client library support.
This binding specification defines how attributes and data of a CloudEvent is mapped to the data and headers sections of a RabbitMQ message.
This specification assumes use of the default RabbitMQ message properties.
This specification defines two content modes for transferring events: binary and structured. Every compliant implementation SHOULD support the structured and binary modes.
In the structured content mode, event metadata attributes and event data are placed into the RabbitMQ message's content body section using an event format as defined in the CloudEvents spec.
In the binary content mode, the value of the event data is placed into the RabbitMQ message's content body section as-is, with the datacontenttype attribute value declaring its media type mapped to the RabbitMQ content-type message property; all other event attributes are mapped to the RabbitMQ message headers.
Event formats, used with the structured content mode, define how an event is expressed in a particular data format. All implementations of this specification that support the structured content mode MUST support the JSON event format.
This specification does not introduce any new security features for RabbitMQ, or mandate specific existing features to be used.
This specification does not further define any of the CloudEvents event attributes.
data is assumed to contain opaque application data that is
encoded as declared by the datacontenttype attribute.
An application is free to hold the information in any in-memory representation of its choosing, but as the value is transposed into RabbitMQ as defined in this specification, RabbitMQ delivery provides data available as a sequence of bytes.
For instance, if the declared datacontenttype is
application/json;charset=utf-8, the expectation is that the data
value is made available as UTF-8 encoded JSON text.
The content mode is chosen by the producer of the event. Protocol interaction patterns that might allow solicitation of events using a particular content mode (explained below) might be defined by an application, but are not defined here.
The receiver of the event can distinguish between the two modes by inspecting the content-type message property field. If the value is prefixed with the CloudEvents media type application/cloudevents, indicating the use of a known event format, the receiver uses structured mode, otherwise it defaults to binary mode.
If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance application/cloudevents+avro, it MAY still treat the event as binary and forward it to another party as-is.
When the content-type message property is not prefixed with the CloudEvents media type, being able to know when the message ought to be attempted to be parsed as a CloudEvent can be a challenge. While this specification can not mandate that senders do not include any of the CloudEvents message properties when the message is not a CloudEvent, it would be reasonable for a receiver to assume that if the message has all of the mandatory CloudEvents attributes as message properties then it's probably a CloudEvent. However, as with all CloudEvent messages, if it does not adhere to all of the normative language of this specification then it is not a valid CloudEvent.
The binary content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort.
For the binary mode, the RabbitMQ content-type property field value MUST be mapped to the CloudEvents datacontenttype attribute.
The data byte-sequence MUST be used as the value of the RabbitMQ message.
All CloudEvents attributes with exception of datacontenttype and data MUST be individually mapped to and from the RabbitMQ message properties section.
CloudEvents extensions that define their own attributes MAY define a secondary mapping to RabbitMQ message properties for those attributes, also in different message sections, especially if specific attributes or their names need to align with RabbitMQ features or with other specifications that have explicit RabbitMQ message header bindings. However, they MUST also include the previously defined primary mapping.
An extension specification that defines a secondary mapping rule for RabbitMQ, and any revision of such a specification, MUST also define explicit mapping rules for all other protocol bindings that are part of the CloudEvents core at the time of the submission or revision.
CloudEvent properties in structured mode are mapped “as is” into the content data field as key:value pairs.
CloudEvent properties in binary mode are prefixed with "ce-" to use in the content headers section
Examples:
* `time` maps to `ce-time`
* `id` maps to `ce-id`
* `specversion` maps to `ce-specversion`
The value for each RabbitMQ header is constructed from the respective RabbitMQ representation, compliant with the RabbitMQ message properties specification.
The structured content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple protocols.
The RabbitMQ content-type property field is set to the media type of an event format.
Example for the JSON format:
content-type: application/cloudevents+json
The chosen event format defines how all attributes and data are represented.
The event metadata and data is then rendered in accordance with the event format specification and the resulting data becomes the RabbitMQ content body section.
Implementations MAY include the same RabbitMQ application-properties as defined for the binary mode.
This example shows a JSON event format encoded event:
--------------- headers ----------------------------------
{
content-type: application/cloudevents+json; charset=utf-8
}
--------------- body -------------------------------------
{
“specversion” : "1.0",
“id”: “12341234”
“type” : "com.example.someevent",
“datacontenttype”: “application/xml; charset=utf-8”
... further attributes omitted ...
“data”: {
... application data encoded in XML ...
}
}
----------------------------------------------------------
This example shows a Binary event format encoded event:
--------------- headers -----------------------------------
{
ce-specversion : "1.0",
ce-id: “12341234”
ce-type: "com.example.someevent",
ce-source: "example/source.uri"
ce-extension: "test extension value",
ce-datacontenttype: "application/avro"
content-type: "application/avro"
... further attributes omitted ...
}
--------------- body --------------------------------------
... application data encoded in Avro ...
-----------------------------------------------------------
- RabbitMQ RabbitMQ message protocol
- AMQP 1.0 AMQP 1.0 protocol binding spec for Cloud Events
- AMQP 0-9-1 AMQP 0-9-1 Spec document
- RFC2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
- RFC2119 Key words for use in RFCs to Indicate Requirement Levels
- RFC3629 UTF-8, a transformation format of ISO 10646
- RFC4627 The application/json Media Type for JavaScript Object Notation (JSON)
- RFC6839 Additional Media Type Structured Syntax Suffixes
- RFC7159 The JavaScript Object Notation (JSON) Data Interchange Format