<commit_before># HTTP Transport Binding for CloudEvents - Version 0.1

## Abstract

The HTTP Transport Binding for CloudEvents defines how events are mapped to
HTTP 1.1 request and response 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 HTTP](#12-relation-to-http)
- 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. [HTTP Message Mapping](#3-http-message-mapping)
- 3.2. [Binary Content Mode](#31-binary-content-mode)
- 3.1. [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
[HTTP 1.1][RFC7230] requests and response 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][RFC2119].

### 1.2. Relation to HTTP

This specification does not prescribe rules constraining the use or handling of
specific [HTTP methods][RFC7231-Section-4], and it also does not constrain the
[HTTP target resource][RFC7230-Section-5-1] that is used for transferring or
soliciting events.

Events can be transferred with all standard or application-defined HTTP request
methods that support payload body transfers. Events can be also be transferred
in HTTP responses and with all HTTP status codes that permit payload body
transfers.

All examples herein that show HTTP methods, HTTP target URIs, and HTTP status
codes are non-normative illustrations.

This specification also applies equivalently to HTTP/2 ([RFC7540][RFC7540]),
which is compatible with HTTP 1.1 semantics.

### 1.3. Content Modes

This specification defines two content modes for transferring events:
*structured* and *binary*. Every compliant implementation SHOULD support both
modes.

In the *structured* content mode, event metadata attributes and event data are
placed into the HTTP request or response body using an [event
format](#14-event-formats).

In the *binary* content mode, the value of the event `data` attribute is placed
into the HTTP request or response body as-is, with the `contentType` attribute
value declaring its media type; all other event attributes are mapped to HTTP
headers.

### 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], but MAY
support any additional, including proprietary, formats.

### 1.5. Security

This specification does not introduce any new security features for HTTP, or
mandate specific existing features to be used. This specification applies
identically to [HTTP over TLS]([RFC2818][RFC2818]).

## 2. Use of CloudEvents Attributes

This specification does not further define any of the [CloudEvents][CE] event
attributes.

Two of the event attributes, `contentType` and `data` are handled specially
and mapped onto HTTP constructs, 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 `contentType` and
`data` is exemplary.

### 2.1. contentType Attribute

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

### 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 HTTP as defined in this
specification, the assumption is that the `data` attribute value is made
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 to HTTP.

## 3. HTTP Message Mapping

The event binding is identical for both HTTP request and response messages.

The content mode is chosen by the sender of the event, which is either the
requesting or the responding party. Gestures that might allow solicitation of
events using a particular mode might be defined by an application, but are not
defined here.

The receiver of the event can distinguish between the two modes by inspecting
the `Content-Type` header value. 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.

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.

### 3.1. Binary Content Mode

The *binary* content mode accommodates any shape of event data, and allows for
efficient transfer and without transcoding effort.

#### 3.1.1. HTTP Content-Type

For the *binary* mode, the HTTP `Content-Type` value maps directly to the
CloudEvents `contentType` attribute.

#### 3.1.2. Event Data Encoding

The [`data` attribute](#22-data-attribute) byte-sequence is used as the HTTP
message body.

#### 3.1.3. Metadata Headers

All [CloudEvents][CE] attributes with exception of `contentType` and `data`
are individually mapped to and from distinct HTTP message headers.

##### 3.1.3.1 HTTP Header Names

The naming convention for the HTTP header mapping of attributes is:

    * Each attribute name MUST be prefixed with "CE-"
    * Each attribute name's first character MUST be capitalized

Examples:

    * `eventTime` maps to `CE-EventTime`
    * `eventID` maps to `CE-EventID`
    * `cloudEventsVersion` maps to `CE-CloudEventsVersion`

For the `extensions` attribute, each entry of the `extensions` map
is mapped to a separate HTTP header. The `extensions` attribute itself is
not mapped to a header.

The naming convention for the `extensions` header mapping of attributes is:

    * Each map entry name MUST be prefixed with "CE-X-"
    * Each map entry name's first character MUST be capitalized

Examples:

    * `example` maps to `CE-X-Example`
    * `testExtension` maps to `CE-X-TestExtension`

##### 3.1.3.2 HTTP Header Values

The value for each HTTP header is constructed from the respective attribute's
[JSON value][JSON-value] representation, compliant with the [JSON event
format][JSON-format] specification.

Some CloudEvents metadata attributes can contain arbitrary UTF-8 string
content, and per [RFC7230 Section 3][RFC7230-Section-3], HTTP headers MUST only
use printable characters from the US-ASCII character set, and are terminated by
a CRLF sequence.

Therefore, and analog to the encoding rules for Universal character set host
names in URIs [RFC3986 3.2.2][RFC3986], the JSON value MUST be encoded as
follows:

Non-printable ASCII characters and non-ASCII characters MUST first be encoded
according to UTF-8, and then each octet of the corresponding UTF-8 sequence
MUST be percent-encoded to be represented as HTTP header characters, in
compliance with [RFC7230, sections 3, 3.2, 3.2.6][RFC7230-Section-3]. The<commit_msg>Make http header names case-insensitive<commit_after># HTTP Transport Binding for CloudEvents - Version 0.1

## Abstract

The HTTP Transport Binding for CloudEvents defines how events are mapped to
HTTP 1.1 request and response 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 HTTP](#12-relation-to-http)
- 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. [HTTP Message Mapping](#3-http-message-mapping)
- 3.2. [Binary Content Mode](#31-binary-content-mode)
- 3.1. [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
[HTTP 1.1][RFC7230] requests and response 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][RFC2119].

### 1.2. Relation to HTTP

This specification does not prescribe rules constraining the use or handling of
specific [HTTP methods][RFC7231-Section-4], and it also does not constrain the
[HTTP target resource][RFC7230-Section-5-1] that is used for transferring or
soliciting events.

Events can be transferred with all standard or application-defined HTTP request
methods that support payload body transfers. Events can be also be transferred
in HTTP responses and with all HTTP status codes that permit payload body
transfers.

All examples herein that show HTTP methods, HTTP target URIs, and HTTP status
codes are non-normative illustrations.

This specification also applies equivalently to HTTP/2 ([RFC7540][RFC7540]),
which is compatible with HTTP 1.1 semantics.

### 1.3. Content Modes

This specification defines two content modes for transferring events:
*structured* and *binary*. Every compliant implementation SHOULD support both
modes.

In the *structured* content mode, event metadata attributes and event data are
placed into the HTTP request or response body using an [event
format](#14-event-formats).

In the *binary* content mode, the value of the event `data` attribute is placed
into the HTTP request or response body as-is, with the `contentType` attribute
value declaring its media type; all other event attributes are mapped to HTTP
headers.

### 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], but MAY
support any additional, including proprietary, formats.

### 1.5. Security

This specification does not introduce any new security features for HTTP, or
mandate specific existing features to be used. This specification applies
identically to [HTTP over TLS]([RFC2818][RFC2818]).

## 2. Use of CloudEvents Attributes

This specification does not further define any of the [CloudEvents][CE] event
attributes.

Two of the event attributes, `contentType` and `data` are handled specially
and mapped onto HTTP constructs, 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 `contentType` and
`data` is exemplary.

### 2.1. contentType Attribute

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

### 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 HTTP as defined in this
specification, the assumption is that the `data` attribute value is made
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 to HTTP.

## 3. HTTP Message Mapping

The event binding is identical for both HTTP request and response messages.

The content mode is chosen by the sender of the event, which is either the
requesting or the responding party. Gestures that might allow solicitation of
events using a particular mode might be defined by an application, but are not
defined here.

The receiver of the event can distinguish between the two modes by inspecting
the `Content-Type` header value. 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.

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.

### 3.1. Binary Content Mode

The *binary* content mode accommodates any shape of event data, and allows for
efficient transfer and without transcoding effort.

#### 3.1.1. HTTP Content-Type

For the *binary* mode, the HTTP `Content-Type` value maps directly to the
CloudEvents `contentType` attribute.

#### 3.1.2. Event Data Encoding

The [`data` attribute](#22-data-attribute) byte-sequence is used as the HTTP
message body.

#### 3.1.3. Metadata Headers

All [CloudEvents][CE] attributes with exception of `contentType` and `data`
are individually mapped to and from distinct HTTP message headers.

##### 3.1.3.1 HTTP Header Names

The naming convention for the HTTP header mapping of attributes is:

    * Each attribute name MUST be prefixed with "CE-"

Examples:

    * `eventTime` maps to `CE-EventTime`
    * `eventID` maps to `CE-EventID`
    * `cloudEventsVersion` maps to `CE-CloudEventsVersion`

For the `extensions` attribute, each entry of the `extensions` map
is mapped to a separate HTTP header. The `extensions` attribute itself is
not mapped to a header.

The naming convention for the `extensions` header mapping of attributes is:

    * Each map entry name MUST be prefixed with "CE-X-"

Examples:

    * `example` maps to `CE-X-Example`
    * `testExtension` maps to `CE-X-TestExtension`

Note: per the [HTTP](https://tools.ietf.org/html/rfc7230#section-3.2)
specification, header names are case-insensitive.

##### 3.1.3.2 HTTP Header Values

The value for each HTTP header is constructed from the respective attribute's
[JSON value][JSON-value] representation, compliant with the [JSON event
format][JSON-format] specification.

Some CloudEvents metadata attributes can contain arbitrary UTF-8 string
content, and per [RFC7230 Section 3][RFC7230-Section-3], HTTP headers MUST only
use printable characters from the US-ASCII character set, and are terminated by
a CRLF sequence.

Therefore, and analog to the encoding rules for Universal character set host
names in URIs [RFC3986 3.2.2][RFC3986], the JSON value MUST be encoded as
follows:

Non-printable ASCII characters and non-ASCII characters MUST first be encoded
according to UTF-8, and then each octet of the corresponding UTF-8 sequence
MUST be percent-encoded to be represented as HTTP header characters, in
compliance with [RFC7230, sections 3, 3.2, 3.2.6][RFC7230-Section-3]. The
{'fraction_non_alphanumeric': 0.07629307629307629, 'fraction_numerical': 0.02394002394002394, 'mean_word_length': 4.749366171676929, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '740613', 'n_tokens_mistral': 4538, 'n_tokens_neox': 4153, 'n_words': 2099}