The RocketMQ Transport Binding for CloudEvents defines how events are mapped to RocketMQ messages.
This document is a working draft.
CloudEvents 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.
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 RocketMQ; it solely defines how CloudEvents are expressed in the RocketMQ message transport protocol as client messages that are produced and consumed.
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.
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.
This specification does not introduce any new security features for RocketMQ, or mandate specific existing features to be used.
This specification does not further define any of the CloudEvents event attributes.
The contenttype attribute is assumed to contain a media-type expression compliant with RFC2046.
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 encoded JSON text.
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 .
The binary content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort.
For the binary mode, the header CE_contenttype property MUST be mapped directly to the CloudEvents contentType attribute.
The data attribute byte-sequence MUST be used as the value of the RocketMQ message.
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.
CloudEvents 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`
The value for each RocketMQ Message header is constructed from the respective header's RocketMQ representation, compliant with the RocketMQ message format specification.
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.
------------------ 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 ... -----------------------------------------------
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 transports.
The 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
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.
Implementations MAY include the same RocketMQ headers as defined for the binary mode.
This example shows a JSON event format encoded structured data event:
------------------ 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 ... } } ------------------------------------------------------