Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adjust AMQP spec to changes in #521 #529

Merged
merged 6 commits into from
Oct 14, 2019
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The following documents are available:
| |
| **Optional Specifications:** |
| AMQP Event Format | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/amqp-format.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-format.md) |
| AMQP Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/amqp-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-transport-binding.md) |
| AMQP Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) |
deissnerk marked this conversation as resolved.
Show resolved Hide resolved
| AVRO Event Format | - | [master](./avro-format.md) |
| HTTP Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/http-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-transport-binding.md) |
| JSON Event Format | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) |
Expand Down
143 changes: 0 additions & 143 deletions amqp-format.md

This file was deleted.

101 changes: 54 additions & 47 deletions amqp-transport-binding.md → amqp-protocol-binding.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# AMQP Transport Binding for CloudEvents - Version 1.0-rc1
# AMQP Protocol Binding for CloudEvents - Version 1.0-rc1

## Abstract

The AMQP Transport Binding for CloudEvents defines how events are mapped to
The AMQP Protocol Binding for CloudEvents defines how events are mapped to
OASIS AMQP 1.0 ([OASIS][oasis-amqp-1.0]; ISO/IEC 19464:2014) messages.

## Status of this document
Expand All @@ -21,9 +21,6 @@ This document is a working draft.

2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes)

- 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute)
- 2.2. [data](#22-data)

3. [AMQP Message Mapping](#3-amqp-message-mapping)

- 3.2. [Binary Content Mode](#31-binary-content-mode)
Expand Down Expand Up @@ -68,21 +65,19 @@ modes.

In the _structured_ content mode, event metadata attributes and event data are
placed into the AMQP message's [application data][data] section using an
[event format](#14-event-formats).
event format as defined in the CloudEvents [spec][ce].

In the _binary_ content mode, the value of the event `data` is placed
into the AMQP message's [application data][data] section as-is, with the
`datacontenttype` attribute value declaring its media type; all other event
attributes are mapped to the AMQP [application-properties][app-properties]
section.
In the _binary_ content mode, the value of the event `data` is placed into the
AMQP message's [application data][data] section as-is, with the
`datacontenttype` attribute value declaring its media type mapped to the AMQP
`content-type` message property; all other event attributes are mapped to the
AMQP [application-properties][app-properties] section.

### 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] as well as the [AMQP event
format][amqp-format] for the [application-properties][app-properties] section,
but MAY support any additional, including proprietary, formats.
MUST support the [JSON event format][json-format].

### 1.5. Security

Expand All @@ -94,33 +89,14 @@ mandate specific existing features to be used.
This specification does not further define any of the [CloudEvents][ce] event
attributes.

Two of the event attributes, `datacontenttype` and `data` are handled specially
and mapped onto AMQP constructs, all other attributes are transferred as
metadata without further interpretation.
One event attribute, `datacontenttype` is handled specially in *binary* content
mode and mapped onto the AMQP content-type message property. All other
attributes are transferred as metadata without further interpretation.

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` and
`data` is exemplary.

### 2.1. datacontenttype Attribute

The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046]
compliant media-type expression.

### 2.2. data

`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 AMQP as defined in this
specification, the assumption is that the `data` value is made
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][rfc3629] encoded JSON text for use in AMQP.
event metadata. Any mention of event attributes other than `datacontenttype`
is exemplary.

## 3. AMQP Message Mapping

Expand Down Expand Up @@ -151,14 +127,26 @@ directly to the CloudEvents `datacontenttype` attribute.

#### 3.1.2. Event Data Encoding

The [`data`](#22-data) byte-sequence is used as the AMQP
Event 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 it is transposed into AMQP as defined in this
specification, the assumption is that the event data is made available as a
sequence of bytes. The byte sequence is used as the AMQP
[application-data][data] section.

Example:

If the declared `datacontenttype` is `application/json;charset=utf-8`, the
expectation is that the event data is made available as [UTF-8][rfc3629] encoded
JSON text for use in AMQP.

#### 3.1.3. Metadata Headers

All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data`
MUST be individually mapped to and from the AMQP
[application-properties][app-properties] section, with exceptions noted below.
All [CloudEvents][ce] attributes with exception of `datacontenttype` MUST be
individually mapped to and from the AMQP
[application-properties][app-properties] section.

CloudEvents extensions that define their own attributes MAY define a secondary
mapping to AMQP properties for those attributes, also in different message
Expand All @@ -169,7 +157,7 @@ mapping.

An extension specification that defines a secondary mapping rule for AMQP, and
any revision of such a specification, MUST also define explicit mapping rules
for all other transport bindings that are part of the CloudEvents core at the
for all other protocol bindings that are part of the CloudEvents core at the
time of the submission or revision.

##### 3.1.3.1 AMQP Application Property Names
Expand All @@ -186,8 +174,29 @@ Examples:
##### 3.1.3.2 AMQP Application Property Values

The value for each AMQP application property is constructed from the respective
attribute's AMQP type representation, compliant with the [AMQP event
format][amqp-format] specification.
attribute's AMQP type representation.

The CloudEvents type system MUST be mapped to AMQP types as follows, with
exceptions noted below.

| CloudEvents | AMQP |
| ------------- | --------------------------- |
| Boolean | [boolean][amqp-boolean] |
| Integer | [long][amqp-long] |
| String | [string][amqp-string] |
| Binary | [binary][amqp-binary] |
| URI | [string][amqp-string] |
| URI-reference | [string][amqp-string] |
| Timestamp | [timestamp][amqp-timestamp] |

All attribute values in an AMQP binary message MAY be represented using the
native AMQP types above, or MAY be in canonical string form. An implementation
MUST be able to interpret both forms on an incoming AMQP message. An
implementation SHOULD use the native AMQP form on outgoing AMQP messages when it
is efficient to do so, but MAY forward values as canonical strings. A robust
implementation MAY further relax the requirements for incoming messages (for
example accepting numeric types other than AMQP long) but MUST use only the
prescribed AMQP types or canonical strings on outgoing messages.

#### 3.1.4 Examples

Expand Down Expand Up @@ -292,8 +301,6 @@ content-type: application/cloudevents+json; charset=utf-8

[ce]: ./spec.md
[json-format]: ./json-format.md
[amqp-format]: ./amqp-format.md
[data-section]: 3.2.6
[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
[json-value]: https://tools.ietf.org/html/rfc7159#section-3
[rfc2046]: https://tools.ietf.org/html/rfc2046
Expand Down
2 changes: 1 addition & 1 deletion documented-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ MAY), this usage only applies to events that use the extension.
Extensions always follow a common placement strategy for in-memory formats (e.g.
[JSON](json-format.md), XML) that are decided by those
representations. Transport bindings (e.g. [HTTP](http-transport-binding.md),
[MQTT](mqtt-transport-binding.md), [AMPQ](amqp-transport-binding.md),
[MQTT](mqtt-transport-binding.md), [AMPQ](amqp-protocol-binding.md),
[NATS](nats-transport-binding.md)) provide default placement for extensions, but
an extension MAY require special secondary representation when transported (e.g. tracing
standards that require specific headers). Extension authors SHOULD only require
Expand Down