Skip to content

Commit 3ab4ee7

Browse files
gabo1208gabo1208
authored
Add Rabbitmq's CloudEvents Protocol Binding Spec to the repo (#480)
* added spec to this repo to have a quick reference and improve version control in the file * added dir to protocol binding an add it to the source readme * removed tasks from spec * fixed reviewdog errors + broker link * fixed link errors
1 parent 75e8f60 commit 3ab4ee7

File tree

2 files changed

+223
-1
lines changed

2 files changed

+223
-1
lines changed

‎cloudevents-protocol-spec/spec.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# RabbitMQ Protocol Binding for CloudEvents - Version 1.0.2-wip
2+
## Abstract
3+
4+
The RabbitMQ Binding for CloudEvents defines how events are mapped to [RabbitMQ messages][rabbit-msg].
5+
6+
## Status of this document
7+
8+
This document is a working draft.
9+
10+
## Table of Contents
11+
12+
1. [Introduction](#1-introduction)
13+
14+
- 1.1. [Conformance](#11-conformance)
15+
- 1.2. [Relation to RabbitMQ](#12-relation-to-rabbitmq)
16+
- 1.3. [Content Modes](#13-content-modes)
17+
- 1.4. [Event Formats](#14-event-formats)
18+
- 1.5. [Security](#15-security)
19+
20+
2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes)
21+
22+
- 2.1. [data](#21-data)
23+
24+
3. [RabbitMQ Message Mapping](#rabbitmq-message-mapping)
25+
26+
- 3.1. [Key Mapping](#31-key-mapping)
27+
- 3.2. [Binary Content Mode](#32-binary-content-mode)
28+
- 3.3. [Structured Content Mode](#33-structured-content-mode)
29+
30+
4. [References](#4-references)
31+
32+
## 1. Introduction
33+
34+
[CloudEvents][ce] 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][rabbitmq] as [RabbitMQ messages][rabbit-msg].
35+
36+
### 1.1. Conformance
37+
38+
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][rfc2119].
39+
40+
### 1.2. Relation to RabbitMQ
41+
42+
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][rabbit-msg].
43+
44+
[RabbitMQ supports multiple messaging protocols][rabbitmq-protocols] - AMQP 1.0, AMQP 0-9-1, STOMP, MQTT - and uses [AMQP 0-9-1][amqp091] with extensions as the "core" & default protocol. AMQP 0-9-1 is a binary protocol with strong messaging semantics with [wide client library support][rabbitmq-clients].
45+
46+
This binding specification defines how attributes and data of a CloudEvent is mapped to the data and headers sections of a RabbitMQ message.
47+
48+
This specification assumes use of the default [RabbitMQ message properties][rabbit-msg].
49+
50+
51+
52+
### 1.3. Content Modes
53+
54+
This specification defines two content modes for transferring events: _binary_ and _structured_. Every compliant implementation SHOULD support the _structured_ and _binary_ modes.
55+
56+
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][ce].
57+
58+
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][rabbit-msg].
59+
60+
### 1.4. Event Formats
61+
62+
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][json-format].
63+
64+
### 1.5. Security
65+
66+
This specification does not introduce any new security features for RabbitMQ, or mandate specific existing features to be used.
67+
68+
## 2. Use of CloudEvents Attributes
69+
70+
This specification does not further define any of the [CloudEvents][ce] event attributes.
71+
72+
One event attribute, `datacontenttype`, is handled specially in _binary_ content mode and mapped onto the RabbitMQ content-type message property. All other attributes are transferred as metadata without further interpretation.
73+
74+
This mapping is intentionally robust against changes, including the addition and removal of event attributes, and also accommodates vendor extensions to the event metadata. Any mention of event attributes other than `datacontenttype` is exemplary.
75+
76+
## 3. RabbitMQ Message Mapping
77+
78+
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.
79+
80+
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](#14-event-formats), the receiver uses _structured_ mode, otherwise it defaults to _binary_ mode.
81+
82+
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.
83+
84+
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.
85+
86+
### 3.1. Binary Content Mode
87+
88+
The _binary_ content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort.
89+
90+
#### 3.1.1. RabbitMQ Content-Type
91+
92+
For the _binary_ mode, the RabbitMQ `content-type` property field value maps to the CloudEvents `datacontenttype` attribute.
93+
94+
#### 3.1.2. Event Data Encoding
95+
96+
The [`data`](#21-data) byte-sequence MUST be used as the value of the RabbitMQ message.
97+
98+
#### 3.1.3. Metadata Headers
99+
100+
All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data` MUST be individually mapped to and from the [RabbitMQ message properties][rabbit-msg] section.
101+
102+
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.
103+
104+
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.
105+
106+
##### 3.1.3.1. RabbitMQ Application Property Names
107+
108+
CloudEvent properties in _structured_ mode are mapped “as is” into the content data field as key:value pairs.
109+
110+
CloudEvent properties in _binary_ mode are prefixed with "ce-" to use in the content headers section
111+
112+
Examples:
113+
114+
* `time` maps to `ce-time`
115+
* `id` maps to `ce-id`
116+
* `specversion` maps to `ce-specversion`
117+
118+
##### 3.1.3.2. RabbitMQ Application Property Values
119+
120+
The value for each RabbitMQ header is constructed from the respective RabbitMQ representation, compliant with the [RabbitMQ message properties][rabbit-msg] specification.
121+
122+
### 3.2. Structured Content Mode
123+
124+
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.
125+
126+
#### 3.2.1. RabbitMQ Content-Type
127+
128+
The [RabbitMQ `content-type`][content-type] property field is set to the media type of an [event format](#14-event-formats).
129+
130+
Example for the [JSON format][json-format]:
131+
132+
```text
133+
content-type: application/cloudevents+json; charset=UTF-8
134+
```
135+
#### 3.2.2. Event Data Encoding
136+
137+
The chosen [event format](#14-event-formats) defines how all attributes and `data` are represented.
138+
139+
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.
140+
141+
#### 3.2.3. Metadata Headers
142+
143+
Implementations MAY include the same RabbitMQ application-properties as defined for the [binary mode](#313-metadata-headers).
144+
145+
#### 3.2.4 Examples
146+
147+
This example shows a JSON event format encoded event:
148+
149+
```text
150+
--------------- headers ----------------------------------
151+
{
152+
content-type: application/cloudevents+json; charset=utf-8
153+
... further headers omitted ...
154+
}
155+
--------------- body -------------------------------------
156+
157+
{
158+
“specversion” : "1.0",
159+
“id”: “12341234”
160+
“type” : "com.example.someevent",
161+
“data-field-1”: “test”
162+
163+
... further attributes omitted ...
164+
“data”: {
165+
... application data …
166+
}
167+
}
168+
169+
----------------------------------------------------------
170+
```
171+
This example shows a Binary event format encoded event:
172+
173+
```text
174+
--------------- headers -----------------------------------
175+
{
176+
ce-specversion : "1.0",
177+
ce-id: “12341234”
178+
ce-type : "com.example.someevent",
179+
content-type: "application/cloudevents+json; charset=UTF-8"
180+
181+
... further attributes omitted ...
182+
}
183+
--------------- body --------------------------------------
184+
{
185+
... application data ...
186+
}
187+
-----------------------------------------------------------
188+
```
189+
190+
191+
## 4. References
192+
193+
- [RabbitMQ][rabbitmq] RabbitMQ message protocol
194+
- [AMQP 1.0][amqp1] AMQP 1.0 protocol binding spec for Cloud Events
195+
- [AMQP 0-9-1][amqp091] AMQP 0-9-1 Spec document
196+
- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two:
197+
Media Types
198+
- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels
199+
- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646
200+
- [RFC4627][rfc4627] The application/json Media Type for JavaScript Object
201+
Notation (JSON)
202+
- [RFC6839][rfc6839] Additional Media Type Structured Syntax Suffixes
203+
- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange
204+
Format
205+
206+
[rabbitmq]: https://rabbitmq.com/amqp-0-9-1-reference.html
207+
[rabbit-msg]: https://www.rabbitmq.com/publishers.html#message-properties
208+
[amqp1]: https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md
209+
[amqp091]: https://www.rabbitmq.com/resources/specs/amqp0-9-1.pdf
210+
[rabbitmq-protocols]: https://www.rabbitmq.com/protocols.html
211+
[rabbitmq-clients]: https://www.rabbitmq.com/devtools.html
212+
[ce]: https://github.com/cloudevents/spec/blob/master/spec.md
213+
[json-format]: https://github.com/cloudevents/spec/blob/master/json-format.md
214+
[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
215+
[json-value]: https://tools.ietf.org/html/rfc7159#section-3
216+
[rfc2046]: https://tools.ietf.org/html/rfc2046
217+
[rfc2119]: https://tools.ietf.org/html/rfc2119
218+
[rfc3629]: https://tools.ietf.org/html/rfc3629
219+
[rfc4627]: https://tools.ietf.org/html/rfc4627
220+
[rfc6839]: https://tools.ietf.org/html/rfc6839
221+
[rfc7159]: https://tools.ietf.org/html/rfc7159

‎source/README.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
:toc-placement!:
44
= RabbitMQ Source
55

6-
The RabbitMQ source translates messages on a RabbitMQ exchange to CloudEvents,
6+
The RabbitMQ source translates messages on a RabbitMQ exchange to CloudEvents
7+
based on the https://github.com/knative-sandbox/eventing-rabbitmq/blob/main/cloudevents-protocol-spec/spec.md[RabbitMQ Protocol Binding for CloudEvents Spec],
78
which can then be used with Knative Eventing over HTTP. The source can bind to
89
an existing RabbitMQ exchange, or create a new exchange if required.
910

0 commit comments

Comments
 (0)