Skip to content

Commit c11abc0

Browse files
clemensvDoug Davis
clemensv
authored and
Doug Davis
committed
HTTP transport and JSON mapping (#148)
* HTTP binding and JSON event format Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * HTTP header encoding changes and feedback fixes Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * Cloud Events to CloudEvents Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * Deleting serialization.md Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * Adding extension header mapping Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * TOC reference fix Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * refer to JSON format Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * change Makefile to remove serialization.md and add new specs Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * fix RFC issues and branding Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * fix RFC issues and branding Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * added MUST clauses per Doug's comments on #93 Signed-off-by: Clemens Vasters <clemensv@microsoft.com> * clarification for percent encoding with percent sign Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
1 parent 2189ab3 commit c11abc0

5 files changed

Lines changed: 581 additions & 70 deletions

File tree

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@ verify:
55
@# Use "-x" if you want to skip exernal links
66
@tools/verify-links.sh -v .
77
@echo Running the spec phrase checker:
8-
@tools/verify-specs.sh -v spec.md extensions.md serialization.md
8+
@tools/verify-specs.sh -v spec.md extensions.md json-format.md http-transport-binding.md
99
@echo Running the doc phrase checker:
1010
@tools/verify-docs.sh -v .

‎http-transport-binding.md‎

Lines changed: 366 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,366 @@
1+
# HTTP Transport Binding for CloudEvents
2+
3+
## Abstract
4+
5+
The HTTP Transport Binding for CloudEvents defines how events are mapped to
6+
HTTP 1.1 request and response messages.
7+
8+
## Status of this document
9+
10+
This document is a working draft.
11+
12+
## Table of Contents
13+
14+
1. [Introduction](#1-introduction)
15+
- 1.1. [Conformance](#11-conformance)
16+
- 1.2. [Relation to HTTP](#12-relation-to-http)
17+
- 1.3. [Content Modes](#13-content-modes)
18+
- 1.4. [Event Formats](#14-event-formats)
19+
- 1.5. [Security](#15-security)
20+
2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes)
21+
- 2.1. [contentType Attribute](#21-contenttype-attribute)
22+
- 2.2. [data Attribute](#22-data-attribute)
23+
3. [HTTP Message Mapping](#3-http-message-mapping)
24+
- 3.2. [Binary Content Mode](#31-binary-content-mode)
25+
- 3.1. [Structured Content Mode](#32-structured-content-mode)
26+
4. [References](#4-references)
27+
28+
## 1. Introduction
29+
30+
[CloudEvents][CE] is a standardized and transport-neutral definition of the
31+
structure and metadata description of events. This specification defines how
32+
the elements defined in the CloudEvents specification are to be used in
33+
[HTTP 1.1][RFC7230] requests and response messages.
34+
35+
### 1.1. Conformance
36+
37+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
38+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
39+
interpreted as described in [RFC2119][RFC2119].
40+
41+
### 1.2. Relation to HTTP
42+
43+
This specification does not prescribe rules constraining the use or handling of
44+
specific [HTTP methods][RFC7231-Section-4], and it also does not constrain the
45+
[HTTP target resource][RFC7230-Section-5-1] that is used for transferring or
46+
soliciting events.
47+
48+
Events can be transferred with all standard or application-defined HTTP request
49+
methods that support payload body transfers. Events can be also be transferred
50+
in HTTP responses and with all HTTP status codes that permit payload body
51+
transfers.
52+
53+
All examples herein that show HTTP methods, HTTP target URIs, and HTTP status
54+
codes are non-normative illustrations.
55+
56+
This specification also applies equivalently to HTTP/2 ([RFC7540][RFC7540]),
57+
which is compatible with HTTP 1.1 semantics.
58+
59+
### 1.3. Content Modes
60+
61+
This specification defines two content modes for transferring events:
62+
*structured* and *binary*. Every compliant implementation SHOULD support both
63+
modes.
64+
65+
In the *structured* content mode, event metadata attributes and event data are
66+
placed into the HTTP request or response body using an [event
67+
format](#14-event-formats).
68+
69+
In the *binary* content mode, the value of the event `data` attribute is placed
70+
into the HTTP request or response body as-is, with the `contentType` attribute
71+
value declaring its media type; all other event attributes are mapped to HTTP
72+
headers.
73+
74+
### 1.4. Event Formats
75+
76+
Event formats, used with the *stuctured* content mode, define how an event is
77+
expressed in a particular data format. All implementations of this
78+
specification MUST support the [JSON event format][JSON-format], but MAY
79+
support any additional, including proprietary, formats.
80+
81+
### 1.5. Security
82+
83+
This specification does not introduce any new security features for HTTP, or
84+
mandate specific existing features to be used. This specification applies
85+
identically to [HTTP over TLS]([RFC2818][RFC2818]).
86+
87+
## 2. Use of CloudEvents Attributes
88+
89+
This specification does not further define any of the [CloudEvents][CE] event
90+
attributes.
91+
92+
Two of the event attributes, `contentType` and `data` are handled specially
93+
and mapped onto HTTP constructs, all other attributes are transferred as
94+
metadata without further interpretation.
95+
96+
This mapping is intentionally robust against changes, including the addition
97+
and removal of event attributes, and also accommodates vendor extensions to the
98+
event metadata. Any mention of event attributes other than `contentType` and
99+
`data` is exemplary.
100+
101+
### 2.1. contentType Attribute
102+
103+
The `contentType` attribute is assumed to contain a [RFC2046][RFC2046]
104+
compliant media-type expression.
105+
106+
### 2.2. data Attribute
107+
108+
The `data` attribute is assumed to contain opaque application data that is
109+
encoded as declared by the `contentType` attribute.
110+
111+
An application is free to hold the information in any in-memory representation
112+
of its choosing, but as the value is transposed into HTTP as defined in this
113+
specification, the assumption is that the `data` attribute value is made
114+
available as a sequence of bytes.
115+
116+
For instance, if the declared `contentType` is
117+
`application/json;charset=utf-8`, the expectation is that the `data` attribute
118+
value is made available as [UTF-8][RFC3629] encoded JSON text to HTTP.
119+
120+
## 3. HTTP Message Mapping
121+
122+
The event binding is identical for both HTTP request and response messages.
123+
124+
The content mode is chosen by the sender of the event, which is either the
125+
requesting or the responding party. Gestures that might allow solicitation of
126+
events using a particular mode might be defined by an application, but are not
127+
defined here.
128+
129+
The receiver of the event can distinguish between the two modes by inspecting
130+
the `Content-Type` header value. If the value is prefixed with the CloudEvents
131+
media type `application/cloudevents`, indicating the use of a known [event
132+
format](#14-event-formats), the receiver uses *structured* mode, otherwise it
133+
defaults to *binary* mode.
134+
135+
If a receiver detects the CloudEvents media type, but with an event format that
136+
it cannot handle, for instance `application/cloudevents+avro`, it MAY still
137+
treat the event as binary and forward it to another party as-is.
138+
139+
### 3.1. Binary Content Mode
140+
141+
The *binary* content mode accommodates any shape of event data, and allows for
142+
efficient transfer and without transcoding effort.
143+
144+
#### 3.1.1. HTTP Content-Type
145+
146+
For the *binary* mode, the HTTP `Content-Type` value maps directly to the
147+
CloudEvents `contentType` attribute.
148+
149+
#### 3.1.2. Event Data Encoding
150+
151+
The [`data` attribute](#22-data-attribute) byte-sequence is used as the HTTP
152+
message body.
153+
154+
#### 3.1.3. Metadata Headers
155+
156+
All [CloudEvents][CE] attributes with exception of `contentType` and `data`
157+
are individually mapped to and from distinct HTTP message headers.
158+
159+
##### 3.1.3.1 HTTP Header Names
160+
161+
The naming convention for the HTTP header mapping of attributes is:
162+
163+
* Each attribute name MUST be prefixed with "CE-"
164+
* Each attribute name's first character MUST be capitalized
165+
166+
Examples:
167+
168+
* `eventTime` maps to `CE-EventTime`
169+
* `eventID` maps to `CE-EventID`
170+
* `cloudEventsVersion` maps to `CE-CloudEventsVersion`
171+
172+
For the `extensions` attribute, each entry of the `extensions` map
173+
is mapped to a separate HTTP header. The `extensions` attribute itself is
174+
not mapped to a header.
175+
176+
The naming convention for the `extensions` header mapping of attributes is:
177+
178+
* Each map entry name MUST be prefixed with "CE-X-"
179+
* Each map entry name's first character MUST be capitalized
180+
181+
Examples:
182+
183+
* `example` maps to `CE-X-Example`
184+
* `testExtension` maps to `CE-X-TestExtension`
185+
186+
##### 3.1.3.2 HTTP Header Values
187+
188+
The value for each HTTP header is constructed from the respective attribute's
189+
[JSON value][JSON-value] representation, compliant with the [JSON event
190+
format][JSON-format] specification.
191+
192+
Some CloudEvents metadata attributes can contain arbitrary UTF-8 string
193+
content, and per [RFC7230 Section 3][RFC7230-Section-3], HTTP headers MUST only
194+
use printable characters from the US-ASCII character set, and are terminated by
195+
a CRLF sequence.
196+
197+
Therefore, and analog to the encoding rules for Universal character set host
198+
names in URIs [RFC3986 3.2.2][RFC3986], the JSON value MUST be encoded as
199+
follows:
200+
201+
Non-printable ASCII characters and non-ASCII characters MUST first be encoded
202+
according to UTF-8, and then each octet of the corresponding UTF-8 sequence
203+
MUST be percent-encoded to be represented as HTTP header characters, in
204+
compliance with [RFC7230, sections 3, 3.2, 3.2.6][RFC7230-Section-3]. The
205+
rules for encoding of the percent character ('%') apply as defined in
206+
[RFC 3986 Section 2.4.][RFC3986-Section-2-4].
207+
208+
JSON objects and arrays are NOT surrounded with single or double quotes.
209+
210+
#### 3.1.4 Examples
211+
212+
This example shows the *binary* mode mapping of an event with an HTTP POST
213+
request:
214+
215+
``` text
216+
POST /someresource HTTP/1.1
217+
Host: webhook.example.com
218+
CE-CloudEventsVersion: "0.1"
219+
CE-EventType: "com.example.someevent"
220+
CE-EventTime: "2018-04-05T03:56:24Z"
221+
CE-EventID: "1234-1234-1234"
222+
CE-Source: "/mycontext/subcontext"
223+
.... further attributes ...
224+
Content-Type: application/json; charset=utf-8
225+
Content-Length: nnnn
226+
227+
{
228+
... application data ...
229+
}
230+
```
231+
232+
This example shows a response containing an event:
233+
234+
``` text
235+
HTTP/1.1 200 OK
236+
CE-CloudEventsVersion: "0.1"
237+
CE-EventType: "com.example.someevent"
238+
CE-EventTime: "2018-04-05T03:56:24Z"
239+
CE-EventID: "1234-1234-1234"
240+
CE-Source: "/mycontext/subcontext"
241+
.... further attributes ...
242+
Content-Type: application/json; charset=utf-8
243+
Content-Length: nnnn
244+
245+
{
246+
... application data ...
247+
}
248+
```
249+
250+
### 3.2. Structured Content Mode
251+
252+
The *structured* content mode keeps event metadata and data together in the
253+
payload, allowing simple forwarding of the same event across multiple routing
254+
hops, and across multiple transports.
255+
256+
#### 3.2.1. HTTP Content-Type
257+
258+
The [HTTP `Content-Type`][Content-Type] header MUST be set to the media type of
259+
an [event format](#14-event-formats).
260+
261+
Example for the [JSON format][JSON-format]:
262+
263+
``` text
264+
Content-Type: application/cloudevents+json; charset=UTF-8
265+
```
266+
267+
#### 3.2.2. Event Data Encoding
268+
269+
The chosen [event format](#14-event-formats) defines how all attributes,
270+
including the `data` attribute, are represented.
271+
272+
The event metadata and data is then rendered in accordance with the event
273+
format specification and the resulting data becomes the HTTP message body.
274+
275+
#### 3.2.3. Metadata Headers
276+
277+
Implementations MAY include the same HTTP headers as defined for the [binary
278+
mode](#313-metadata-headers).
279+
280+
All CloudEvents metadata attributes MUST be mapped into the payload, even if
281+
they are also mapped into HTTP headers.
282+
283+
#### 3.2.4 Examples
284+
285+
This example shows a JSON event format encoded event, sent with a PUT request:
286+
287+
``` text
288+
289+
PUT /myresource HTTP/1.1
290+
Host: webhook.example.com
291+
Content-Type: application/cloudevents+json; charset=utf-8
292+
Content-Length: nnnn
293+
294+
{
295+
"cloudEventsVersion" : "0.1",
296+
"eventType" : "com.example.someevent",
297+
298+
... further attributes omitted ...
299+
300+
"data" : {
301+
... application data ...
302+
}
303+
}
304+
305+
```
306+
307+
This example shows a JSON encoded event retuned in a response:
308+
309+
``` text
310+
311+
HTTP/1.1 200 OK
312+
Content-Type: application/cloudevents+json; charset=utf-8
313+
Content-Length: nnnn
314+
315+
{
316+
"cloudEventsVersion" : "0.1",
317+
"eventType" : "com.example.someevent",
318+
319+
... further attributes omitted ...
320+
321+
"data" : {
322+
... application data ...
323+
}
324+
}
325+
326+
```
327+
328+
## 4. References
329+
330+
- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two:
331+
Media Types
332+
- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels
333+
- [RFC2818][RFC2818] HTTP over TLS
334+
- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646
335+
- [RFC3986][RFC3986] Uniform Resource Identifier (URI): Generic Syntax
336+
- [RFC4627][RFC4627] The application/json Media Type for JavaScript Object
337+
Notation (JSON)
338+
- [RFC4648][RFC4648] The Base16, Base32, and Base64 Data Encodings
339+
- [RFC6839][RFC6839] Additional Media Type Structured Syntax Suffixes
340+
- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format
341+
- [RFC7230][RFC7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax
342+
and Routing
343+
- [RFC7231][RFC7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and
344+
Content
345+
- [RFC7540][RFC7540] Hypertext Transfer Protocol Version 2 (HTTP/2)
346+
347+
[CE]: ./spec.md
348+
[JSON-format]: ./json-format.md
349+
[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
350+
[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3
351+
[RFC2046]: https://tools.ietf.org/html/rfc2046
352+
[RFC2119]: https://tools.ietf.org/html/rfc2119
353+
[RFC2818]: https://tools.ietf.org/html/rfc2818
354+
[RFC3629]: https://tools.ietf.org/html/rfc3629
355+
[RFC3986]: https://tools.ietf.org/html/rfc3986
356+
[RFC3986-Section-2-4]: https://tools.ietf.org/html/rfc3986#section-2.4
357+
[RFC4627]: https://tools.ietf.org/html/rfc4627
358+
[RFC4648]: https://tools.ietf.org/html/rfc4648
359+
[RFC6839]: https://tools.ietf.org/html/rfc6839#section-3.1
360+
[RFC7159]: https://tools.ietf.org/html/rfc7159
361+
[RFC7230]: https://tools.ietf.org/html/rfc7230
362+
[RFC7231]: https://tools.ietf.org/html/rfc7231
363+
[RFC7230-Section-3]: https://tools.ietf.org/html/rfc7230#section-3
364+
[RFC7231-Section-4]: https://tools.ietf.org/html/rfc7231#section-4
365+
[RFC7230-Section-5-1]: https://tools.ietf.org/html/rfc7230#section-5.1
366+
[RFC7540]: https://tools.ietf.org/html/rfc7540

0 commit comments

Comments
 (0)