diff --git a/docs/spec/pubsub-protocol-binding.md b/docs/spec/pubsub-protocol-binding.md index 8a0b98af93..4da0d550b4 100644 --- a/docs/spec/pubsub-protocol-binding.md +++ b/docs/spec/pubsub-protocol-binding.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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: @@ -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]: @@ -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 @@ -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 @@ -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