diff --git a/Makefile b/Makefile index e391a42ba..6ea0135a0 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ verify: @echo Running the spec phrase checker: @tools/verify-specs.sh -v spec.md documented-extensions.md json-format.md \ http-transport-binding.md http-webhook.md mqtt-transport-binding.md \ - nats-transport-binding.md protobuf-format.md + nats-transport-binding.md protobuf-format.md \ + rocketmq-transport-binding.md @echo Running the doc phrase checker: @tools/verify-docs.sh -v . diff --git a/rocketmq-transport-binding.md b/rocketmq-transport-binding.md new file mode 100644 index 000000000..a8dc23024 --- /dev/null +++ b/rocketmq-transport-binding.md @@ -0,0 +1,234 @@ +# RocketMQ Transport Binding for CloudEvents + +## Abstract + +The [RocketMQ][RocketMQ] Transport Binding for CloudEvents defines how events are mapped +to RocketMQ messages. + +## Status of this document + +This document is a working draft. + +## Table of Contents +1. [Introduction](#1-introduction) +- 1.1. [Conformance](#11-conformance) +- 1.2. [Relation to RocketMQ](#12-relation-to-rocketmq) +- 1.3. [Content Modes](#13-content-modes) +- 1.4. [Event Formats](#14-event-formats)) +- 1.5. [Security](#15-security) +2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) +- 2.1. [contenttype Attribute](#21-contenttype-attribute) +- 2.2. [data Attribute](#22-data-attribute) +3. [RocketMQ Message Mapping](#3-rocketmq-message-mapping) +- 3.1. [Binary Content Mode](#31-binary-content-mode) +- 3.2. [Structured Content Mode](#32-structured-content-mode) +4. [References](#4-references) + +## 1. Introduction +[CloudEvents][CE] is a standardized and transport-neutral 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 the +RocketMQ Message protocol as client produced and consumed messages. + +### 1.1. Conformance + +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. + +### 1.2. Relation to RocketMQ + +This specification does not prescribe rules constraining transfer or settlement +of event messages with RocketMQ; it solely defines how CloudEvents are expressed +in the RocketMQ message transport protocol as client messages that are produced and consumed. + +### 1.3. Content Modes + +The specification defines two content modes for transferring events: +*structured* and *binary*. + +The RocketMQ protocol have already supported custom message headers, +necessary for *binary* mode. + +Event metadata attributes and event data are placed into the RocketMQ message +payload using an [event format](#14-event-formats). + +### 1.4. Event Formats + +Event formats, used with the *stuctured* content mode, define how an event is +expressed in a particular data format. All implementations of this +specification MUST support the [JSON event format][JSON-format]. + +### 1.5. Security +This specification does not introduce any new security features for RocketMQ, +or mandate specific existing features to be used. + +## 2. Use of CloudEvents Attributes + +This specification does not further define any of the [CloudEvents][CE] event +attributes. + +### 2.1. contenttype Attribute + +The `contenttype` attribute is assumed to contain a media-type expression +compliant with [RFC2046][RFC2046]. + +### 2.2. data Attribute +The `data` attribute is assumed to contain opaque application data that is +encoded as declared by the `contenttype` attribute. + +An application is free to hold the information in any in-memory representation +of its choosing, but as the value is transposed into RocketMQ as defined in this +specification, core RocketMQ provides data available as a sequence of bytes. + +For instance, if the declared `contenttype` is +`application/json;charset=utf-8`, the expectation is that the `data` attribute +value is made available as [UTF-8][RFC3629] encoded JSON text. + +## 3. RocketMQ Message Mapping +The receiver of the event can distinguish between the two content modes by inspecting +the `CE_contentType` property of the RocketMQ message. 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 finds a CloudEvents media type as per the above rule, 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 . + +### 3.1. Binary Content Mode + +The [binary content mode](#31-binary-content-mode) accommodates any shape of event data, +and allows for efficient transfer and without transcoding effort. + +#### 3.1.1. Content Type + +For the binary mode, the header `CE_contenttype property` MUST be mapped directly to the CloudEvents +contentType attribute. + +#### 3.1.2. Event Data Encoding + +The data attribute byte-sequence MUST be used as the value of the RocketMQ message. + +#### 3.1.3. Metadata Headers + +All CloudEvents attributes and CloudEvent Attributes Extensions with exception of +data MUST be individually mapped to and from the Header fields in the RocketMQ message. + +##### 3.1.3.1 Property Names + +[CloudEvents][CE] attributes are prefixed with `"CE_"` for use in the message section. + +Examples: + + * `time` maps to `CE_time` + * `id` maps to `CE_id` + * `specversion` maps to `CE_specversion` + +##### 3.1.3.2 Property Values + +The value for each RocketMQ Message header is constructed from the respective header's RocketMQ +representation, compliant with the RocketMQ message format specification. + +#### 3.1.4 Example + +This example shows the binary mode mapping of an event into the RocketMQ message. +All other CloudEvents attributes are mapped to RocketMQ message property fields with prefix `CE_`. + +Mind that `CE_` here does refer to the event data content carried in the payload. + +``` text +------------------ Message ------------------- + +Topic: mytopic + + +-------------- user properties --------------- + +CE_contenttype: application/avro +CE_specversion: "0.1" +CE_type: "com.example.someevent" +CE_time: "2018-11-23T03:56:24Z" +CE_id: "1234-1234-1234" +CE_source: "/mycontext/subcontext" + .... further attributes ... + +------------------- value -------------------- + + ... application data ... + +----------------------------------------------- +``` + +### 3.2. Structured Content Mode + +The [structured content mode](#32-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 transports. + +#### 3.2.1. RocketMQ Content-Type + +The [RocketMQ][RocketMQ] `CE_contenttype` property field MUST be set to the media type +of an event format. + +Example for the JSON format: + +``` +CE_contenttype: application/cloudevents+json; charset=UTF-8 + +``` + +#### 3.2.2. Event Data Encoding +The chosen event format defines how all attributes, including the payload, are represented. +And in RocketMQ Message Header, it describes what is the type of transport event. + +The event metadata and data MAY then be rendered in accordance with the event format +specification and the resulting data becomes the payload. + +#### 3.2.3. Metadata Headers + +Implementations MAY include the same RocketMQ headers as defined for the binary mode. + +#### 3.2.4. Example +This example shows a JSON event format encoded structured data event: + +``` text +------------------ Message --------------------------- + +Topic: mytopic + +------------------ user properties ------------------- + +CE_contenttype: application/cloudevents+json; charset=UTF-8 + +------------------ value ----------------------------- + +{ + "cloudEventsVersion" : "0.1", + "eventType" : "com.example.someevent", + + ... further attributes omitted ... + + "data" : { + ... application data ... + } +} + +------------------------------------------------------ +``` + +## 4. References + +- [RocketMQ][RocketMQ] The RocketMQ Messaging System +- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types +- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 +- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format + +[CE]: ./spec.md +[JSON-format]: ./json-format.md +[RocketMQ]: http://rocketmq.apache.org/ +[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 +[RFC2046]: https://tools.ietf.org/html/rfc2046 +[RFC2119]: https://tools.ietf.org/html/rfc2119 +[RFC3629]: https://tools.ietf.org/html/rfc3629 +[RFC7159]: https://tools.ietf.org/html/rfc7159 \ No newline at end of file