Skip to content
This repository has been archived by the owner on Jun 19, 2022. It is now read-only.

Commit

Permalink
Format markdown (#645)
Browse files Browse the repository at this point in the history 
Produced via:
  `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)`
/assign grantr nachocano
/cc grantr nachocano
  • Loading branch information
@mattmoor
mattmoor authored Mar 13, 2020
1 parent 9b9b779 commit 485e32b
Showing 1 changed file with 53 additions and 50 deletions.
103 changes: 53 additions & 50 deletions docs/spec/pubsub-protocol-binding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Abstract

The Google Cloud Pub/Sub Protocol Binding for CloudEvents defines how events are mapped to Pub/Sub
1.1 request and response messages.
The Google Cloud Pub/Sub Protocol Binding for CloudEvents defines how events are
mapped to Pub/Sub 1.1 request and response messages.

## Status of this document

Expand Down Expand Up @@ -34,8 +34,8 @@ This document is a working draft.
## 1. Introduction

[CloudEvents][ce] is a standardized and protocol-agnostic 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
structure and metadata description of events. This specification defines how the
elements defined in the CloudEvents specification are to be used in
[Pub/Sub][pubsub] requests and response messages.

### 1.1. Conformance
Expand All @@ -46,7 +46,8 @@ interpreted as described in [RFC2119][rfc2119].

### 1.2. Relation to Pub/Sub

Events can be produced using a Topic or consumed using Push or Pull based Subscriptions.
Events can be produced using a Topic or consumed using Push or Pull based
Subscriptions.

### 1.3. Content Modes

Expand All @@ -58,15 +59,16 @@ placed into the Pub/Sub message body section using an
[event format](#14-event-formats).

In the _binary_ content mode, the value of the event `data` attribute is placed
into the Pub/Sub payload data as-is, with the `datacontenttype`
attribute value declaring its media type; all other event attributes are mapped
to Pub/Sub attributes.
into the Pub/Sub payload data as-is, with the `datacontenttype` attribute value
declaring its media type; all other event attributes are mapped to Pub/Sub
attributes.

### 1.4. Event Formats

Event formats 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.
Event formats 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

Expand All @@ -84,69 +86,68 @@ event metadata.

### 2.1. datacontenttype Attribute

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

### 2.2. data Attribute

The `data` attribute SHOULD contain opaque application data that is
encoded as declared by the `datacontenttype` attribute.
The `data` attribute SHOULD contain opaque application data that is encoded as
declared by the `datacontenttype` attribute.

An application MAY hold the information in any in-memory representation
of its choosing, but as the value is transposed into a Pub/Sub message as defined
in this specification, the assumption is that the `data` attribute value is made
An application MAY hold the information in any in-memory representation of its
choosing, but as the value is transposed into a Pub/Sub message 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 `datacontenttype` is
`application/json;charset=utf-8`, the expectation is that the `data` attribute
value is made available as [UTF-8][rfc3629] encoded JSON text Pub/Sub message data.
value is made available as [UTF-8][rfc3629] encoded JSON text Pub/Sub message
data.

## 3. Pub/Sub Message Mapping

With Pub/Sub, the content mode is chosen by the sender of the
event. Protocol usage patterns that might allow solicitation of events using a
particular content mode might be defined by an application, but are not defined
here.
With Pub/Sub, the content mode is chosen by the sender of the event. Protocol
usage patterns that might allow solicitation of events using a particular
content mode might be defined by an application, but are not defined here.

The receiver of the event can distinguish between the two content modes by
inspecting the [Pub/Sub Attribute `content-type`][content-type] of the
[Pub/Sub message][pubsub-message]. If the attribute is present and its value is prefixed
with the CloudEvents media type `application/cloudevents`, indicating the use of a known
[event format](#14-event-formats), the receiver SHOULD use _structured_ mode,
otherwise it MUST default to _binary_ mode.
inspecting the [Pub/Sub Attribute `content-type`][content-type] of the [Pub/Sub
message][pubsub-message]. If the attribute is present and its value is prefixed
with the CloudEvents media type `application/cloudevents`, indicating the use of
a known [event format](#14-event-formats), the receiver SHOULD use _structured_
mode, otherwise it MUST default 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.
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.
efficient transfer and without transcoding effort.

The _binary_ content mode can only be used if the metadata attributes
fit within the [limits of Pub/Sub messages][pubsub-message-quotas].
The _binary_ content mode can only be used if the metadata attributes fit within
the [limits of Pub/Sub messages][pubsub-message-quotas].

#### 3.1.1. content-type

For the _binary_ mode, the [Pub/Sub Attribute `content-type`][content-type], if present, MUST
be used as the CloudEvents `datacontenttype` attribute.
For the _binary_ mode, the [Pub/Sub Attribute `content-type`][content-type], if
present, MUST be used as the CloudEvents `datacontenttype` attribute.

#### 3.1.2. Event Data Encoding

The [`data`](#22-data-attribute) byte-sequence MUST be used as the value of the Pub/Sub
message data payload.
The [`data`](#22-data-attribute) byte-sequence MUST be used as the value of the
Pub/Sub message data payload.

#### 3.1.3. Metadata Attributes

All [CloudEvents][ce] attributes
MUST be individually mapped to and from distinct Pub/Sub message attributes.
All [CloudEvents][ce] attributes MUST be individually mapped to and from
distinct Pub/Sub message attributes.

##### 3.1.3.1 Pub/Sub Attribute Names

The naming convention for the Pub/Sub attribute mapping of well-known CloudEvents
attributes is that each attribute name MUST be prefixed with "ce-".
The naming convention for the Pub/Sub attribute mapping of well-known
CloudEvents attributes is that each attribute name MUST be prefixed with "ce-".

Examples:

Expand Down Expand Up @@ -191,8 +192,8 @@ hops, and across multiple transports.

#### 3.2.1. content-type

The [Pub/Sub Attribute `content-type`][content-type] MUST be set to the media type of
an [event format](#14-event-formats).
The [Pub/Sub Attribute `content-type`][content-type] MUST be set to the media
type of an [event format](#14-event-formats).

Example for the [JSON format][json-format]:

Expand All @@ -205,8 +206,8 @@ Example for the [JSON format][json-format]:
The chosen [event format](#14-event-formats) defines how all attributes,
including the `data` attribute, are represented.

The event metadata and data are then rendered in accordance with the event format
specification and the resulting data becomes the Pub/Sub message data.
The event metadata and data are then rendered in accordance with the event
format specification and the resulting data becomes the Pub/Sub message data.

#### 3.2.3. Metadata Attributes

Expand All @@ -218,7 +219,8 @@ they are also mapped into Pub/Sub attributes.

#### 3.2.4 Examples

This example shows the _structured_ mode mapping of an event to a Pub/Sub Message:
This example shows the _structured_ mode mapping of an event to a Pub/Sub
Message:

```text
Publish /some-topic
Expand All @@ -245,18 +247,19 @@ Publish /some-topic

- [PUBSUB][pubsub] Google Cloud Pub/Sub
- [PUBSUB-MESSAGE][pubsub-message] The Google Cloud Pub/Sub message
- [PUBSUB-MESSAGE-QUOTAS][pubsub-message-quotas] The Google Cloud Pub/Sub message quotas
- [PUBSUB-MESSAGE-QUOTAS][pubsub-message-quotas] The Google Cloud Pub/Sub
message quotas
- [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
- [RFC3986][rfc3986] Uniform Resource Identifier (URI): Generic Syntax


[ce]: https://github.com/cloudevents/spec/blob/master/spec.md
[ce-types]: https://github.com/cloudevents/spec/blob/master/spec.md#type-system
[pubsub]: https://cloud.google.com/pubsub/
[pubsub-message]: https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
[pubsub-message]:
https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
[pubsub-message-quotas]: https://cloud.google.com/pubsub/quotas
[json-format]: https://github.com/cloudevents/spec/blob/master/json-format.md
[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
Expand Down

0 comments on commit 485e32b

Please sign in to comment.