From d778653188163b98088e86a306f32d38bdf9fb35 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 10 Oct 2019 12:21:56 +0000 Subject: [PATCH] if 521 and 529 go in, then rename for consistency Signed-off-by: Doug Davis --- Makefile | 6 ++-- README.md | 9 +++-- amqp-protocol-binding.md | 4 +-- avro-format.md | 2 +- community/open-source.md | 2 +- documented-extensions.md | 10 +++--- extensions/partitioning.md | 6 ++-- extensions/sampled-rate.md | 4 +-- ...ort-binding.md => http-protocol-binding.md | 8 ++--- json-format.md | 2 +- ...rt-binding.md => kafka-protocol-binding.md | 10 +++--- ...ort-binding.md => mqtt-protocol-binding.md | 8 ++--- ...ort-binding.md => nats-protocol-binding.md | 8 ++--- primer.md | 34 +++++++++---------- roadmap.md | 6 ++-- 15 files changed, 59 insertions(+), 60 deletions(-) rename http-transport-binding.md => http-protocol-binding.md (98%) rename kafka-transport-binding.md => kafka-protocol-binding.md (96%) rename mqtt-transport-binding.md => mqtt-protocol-binding.md (97%) rename nats-transport-binding.md => nats-protocol-binding.md (95%) diff --git a/Makefile b/Makefile index b628b0ca5..69e8426b1 100644 --- a/Makefile +++ b/Makefile @@ -6,8 +6,8 @@ verify: @tools/verify-links.sh -v . @echo Running the spec phrase checker: @tools/verify-specs.sh -v spec.md documented-extensions.md json-format.md \ - http-transport-binding.md http-webhook.md mqtt-transport-binding.md \ - nats-transport-binding.md \ - kafka-transport-binding.md avro-format.md + http-protocol-binding.md http-webhook.md mqtt-protocol-binding.md \ + nats-protocol-binding.md \ + kafka-protocol-binding.md avro-format.md @echo Running the doc phrase checker: @tools/verify-docs.sh -v . diff --git a/README.md b/README.md index 5199f0292..8c26459fa 100644 --- a/README.md +++ b/README.md @@ -30,14 +30,13 @@ The following documents are available: | CloudEvents | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | | **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-protocol-binding.md) | | 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) | +| HTTP Protocol 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-protocol-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) | -| Kafka Transport Binding | - | [master](https://github.com/cloudevents/spec/blob/master/kafka-transport-binding.md) | -| MQTT Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-transport-binding.md) | -| NATS Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-transport-binding.md) | +| Kafka Protocol Binding | - | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | | **Additional Documentation:** | diff --git a/amqp-protocol-binding.md b/amqp-protocol-binding.md index 60da2b593..eb7a6711f 100644 --- a/amqp-protocol-binding.md +++ b/amqp-protocol-binding.md @@ -30,7 +30,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 [AMQP][oasis-amqp-1.0] messages. @@ -234,7 +234,7 @@ cloudEvents:source: /mycontext/subcontext The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. +hops, and across multiple protocols. #### 3.2.1. AMQP Content-Type diff --git a/avro-format.md b/avro-format.md index fae1b7bb5..c728907df 100644 --- a/avro-format.md +++ b/avro-format.md @@ -18,7 +18,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 represented in the [Avro 1.9.0][avro-primitives]. diff --git a/community/open-source.md b/community/open-source.md index 411682039..7b1efafa2 100644 --- a/community/open-source.md +++ b/community/open-source.md @@ -3,7 +3,7 @@ CloudEvents, please include in the list below. - [CloudEvents.NET](https://github.com/aliencube/CloudEvents.NET): is a .NET implementation of the CloudEvents [spec](../spec.md) and - [HTTP transport binding](../http-transport-binding.md). It has been released + [HTTP protocol binding](../http-protocol-binding.md). It has been released to [nuget.org](https://www.nuget.org/packages?q=Aliencube.CloudEventsNet). It also contains some app [samples](https://github.com/aliencube/CloudEvents.NET/tree/master/sample) diff --git a/documented-extensions.md b/documented-extensions.md index 65d1f400d..8e2d76476 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -32,13 +32,13 @@ 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-protocol-binding.md), -[NATS](nats-transport-binding.md)) provide default placement for extensions, but +representations. Protocol bindings (e.g. [HTTP](http-protocol-binding.md), +[MQTT](mqtt-protocol-binding.md), [AMPQ](amqp-protocol-binding.md), +[NATS](nats-protocol-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 -special representation in transport bindings where extensions integrate with -pre-existing specs; extensions with custom transport bindings are much more +special representation in protocol bindings where extensions integrate with +pre-existing specs; extensions with custom protocol bindings are much more likely to be dropped by middleware that does not understand the extension. As a convention, extensions of scalar types (e.g. `String`, `Binary`, diff --git a/extensions/partitioning.md b/extensions/partitioning.md index 852dfd2ee..67e3bf916 100644 --- a/extensions/partitioning.md +++ b/extensions/partitioning.md @@ -20,7 +20,7 @@ those events. defining a causal relationship/grouping between multiple events. In cases where the CloudEvent is delivered to an event consumer via multiple hops, it is possible that the value of this attribute might change, or even be - removed, due to transport semantics or business processing logic within + removed, due to protocol semantics or business processing logic within each hop. * Examples: * The ID of the entity that the event is associated with @@ -35,8 +35,8 @@ those events. The partitionkey attribute extension uses the key `partitionkey` for in-memory formats. -### Transport format +### Protocol format -The Partitioning extension does not customize any transport binding's storage for +The Partitioning extension does not customize any protocol binding's storage for extensions. diff --git a/extensions/sampled-rate.md b/extensions/sampled-rate.md index 00b683016..6aeb74255 100644 --- a/extensions/sampled-rate.md +++ b/extensions/sampled-rate.md @@ -34,7 +34,7 @@ they impose additional sampling. The Sampling extension uses the key `sampledrate` for in-memory formats. -### Transport bindings +### Protocol bindings -The Sampling extension does not customize any transport binding's storage for +The Sampling extension does not customize any protocol binding's storage for extensions. diff --git a/http-transport-binding.md b/http-protocol-binding.md similarity index 98% rename from http-transport-binding.md rename to http-protocol-binding.md index 162e919b1..bf75952ec 100644 --- a/http-transport-binding.md +++ b/http-protocol-binding.md @@ -1,8 +1,8 @@ -# HTTP Transport Binding for CloudEvents - Version 1.0-rc1 +# HTTP Protocol Binding for CloudEvents - Version 1.0-rc1 ## Abstract -The HTTP Transport Binding for CloudEvents defines how events are mapped to HTTP +The HTTP Protocol Binding for CloudEvents defines how events are mapped to HTTP 1.1 request and response messages. ## Status of this document @@ -34,7 +34,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 [HTTP 1.1][rfc7230] requests and response messages. @@ -255,7 +255,7 @@ Content-Length: nnnn The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. +hops, and across multiple protocols. #### 3.2.1. HTTP Content-Type diff --git a/json-format.md b/json-format.md index c0ef9ed25..b3d34e4b4 100644 --- a/json-format.md +++ b/json-format.md @@ -19,7 +19,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 represented in the JavaScript Object Notation (JSON) Data Interchange Format ([RFC8259][rfc8259]). diff --git a/kafka-transport-binding.md b/kafka-protocol-binding.md similarity index 96% rename from kafka-transport-binding.md rename to kafka-protocol-binding.md index eecdad605..050f5d973 100644 --- a/kafka-transport-binding.md +++ b/kafka-protocol-binding.md @@ -1,8 +1,8 @@ -# Kafka Transport Binding for CloudEvents - Version 1.0-rc1 +# Kafka Protocol Binding for CloudEvents - Version 1.0-rc1 ## Abstract -The [Kafka][Kafka] Transport Binding for CloudEvents defines how events are +The [Kafka][Kafka] Protocol Binding for CloudEvents defines how events are mapped to [Kafka messages][Kafka-Message-Format]. ## Status of this document @@ -27,7 +27,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the +[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 the Kafka protocol as [Kafka messages][Kafka-Message-Format] (aka Kafka records). @@ -114,7 +114,7 @@ forward it to another party as-is. ### 3.1. Key Attribute The 'key' attribute is populated by a partitionKeyExtractor function. The -partitionKeyExtractor is a transport specific function that contains bespoke logic +partitionKeyExtractor is a protocol specific function that contains bespoke logic to extract and populate the value. A default implementation of the extractor will use the [Partitioning](extensions/partitioning.md) extension value. @@ -198,7 +198,7 @@ ce_datacontenttype: application/avro The *structured* content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. +hops, and across multiple protocols. #### 3.3.1. Kafka Content-Type diff --git a/mqtt-transport-binding.md b/mqtt-protocol-binding.md similarity index 97% rename from mqtt-transport-binding.md rename to mqtt-protocol-binding.md index 94d0c4e8f..67fa832d8 100644 --- a/mqtt-transport-binding.md +++ b/mqtt-protocol-binding.md @@ -1,8 +1,8 @@ -# MQTT Transport Binding for CloudEvents - Version 1.0-rc1 +# MQTT Protocol Binding for CloudEvents - Version 1.0-rc1 ## Abstract -The MQTT Transport Binding for CloudEvents defines how events are mapped to MQTT +The MQTT Protocol Binding for CloudEvents defines how events are mapped to MQTT 3.1.1 ([OASIS][oasis-mqtt-3.1.1]; ISO/IEC 20922:2016) and MQTT 5.0 ([OASIS][oasis-mqtt-5]) messages. @@ -34,7 +34,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 MQTT PUBLISH ([3.1.1][3-publish], [5.0][5-publish]) messages. @@ -210,7 +210,7 @@ datacontenttype: application/json; charset=utf-8 The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. This is the only supported mode for MQTT +hops, and across multiple protocols. This is the only supported mode for MQTT 3.1.1 #### 3.2.1. MQTT Content Type diff --git a/nats-transport-binding.md b/nats-protocol-binding.md similarity index 95% rename from nats-transport-binding.md rename to nats-protocol-binding.md index 9004f105a..c99a7c2e7 100644 --- a/nats-transport-binding.md +++ b/nats-protocol-binding.md @@ -1,8 +1,8 @@ -# NATS Transport Binding for CloudEvents - Version 1.0-rc1 +# NATS Protocol Binding for CloudEvents - Version 1.0-rc1 ## Abstract -The [NATS][nats] Transport Binding for CloudEvents defines how events are mapped +The [NATS][nats] Protocol Binding for CloudEvents defines how events are mapped to [NATS messages][nats-msg-proto]. ## Status of this document @@ -33,7 +33,7 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][ce] is a standardized and transport-neutral definition of the +[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 the NATS protocol as client [produced][nats-pub-proto] and [consumed][nats-msg-proto] @@ -105,7 +105,7 @@ MUST be the [JSON event format][json-format] serialized as specified by the The _structured_ content mode keeps event metadata and data together, allowing simple forwarding of the same event across multiple routing hops, and across -multiple transports. +multiple protocols. ### 3.1 Event Data Encoding diff --git a/primer.md b/primer.md index bc1c597a5..e5ee092ab 100644 --- a/primer.md +++ b/primer.md @@ -100,7 +100,7 @@ consumer can be developed and deployed independently. A producer can generate events before a consumer is listening, and a consumer can express an interest in an event or class of events that is not yet being produced. Note that the specifications produced by this effort are focused on interoperability of the -event format and how it appears while being sent on various transports, such as +event format and how it appears while being sent on various protocols, such as HTTP. The specifications will not focus on the processing model of either the event producer or event consumer. @@ -115,19 +115,19 @@ solely for the purpose of proper delivery, and processing, of the message. Data that is not intended for that purpose should instead be placed within the event (`data`) itself. -Additionally, it is assumed that the metadata needed by the transport layer to -deliver the message to the target system is handled entirely by the transport +Additionally, it is assumed that the metadata needed by the protocol layer to +deliver the message to the target system is handled entirely by the protocol and therefore is not included within the CloudEvents attributes. See the [Non-Goals](#non-goals) section for more details. Along with the definition of these attributes, there will also be specifications -of how to serialize the event in different formats (e.g. JSON) and transports +of how to serialize the event in different formats (e.g. JSON) and protocols (e.g. HTTP, AMQP, Kafka). Batching of multiple events into a single API call is natively supported by some -transports. To aid interoperability, it is left up to the transports if and how -batching is implemented. Details may be found in the transport binding or in the -transport specification. A batch of CloudEvents carries no semantic meaning and +protocols. To aid interoperability, it is left up to the protocols if and how +batching is implemented. Details may be found in the protocol binding or in the +protocol specification. A batch of CloudEvents carries no semantic meaning and is not ordered. An [Intermediary](spec.md#intermediary) can add or remove batching as well as assign events to different batches. @@ -138,16 +138,16 @@ The following are considered beyond the scope of the specification: - Function build and invocation process - Language-specific runtime APIs - Selecting a single identity/access control system -- Inclusion of transport-level routing information +- Inclusion of protocol-level routing information - Event persistence processes -The CloudEvents spec will not include transport-level routing information (e.g. +The CloudEvents spec will not include protocol-level routing information (e.g. a destination URL to which the event is being sent). This is a common suggestion by those new to the concepts of CloudEvents. After much deliberation, the working group has come to the conclusion that routing is unnecessary in the -spec: any transport protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already +spec: any protocol protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already defines semantics for routing. For example, the CloudEvents -[HTTP binding](http-transport-binding.md) dictates headers and request body +[HTTP binding](http-protocol-binding.md) dictates headers and request body contents. CloudEvents don't need to include a destination URL in the spec to be HTTP compatible; the HTTP spec already includes one in the [Request-Line](https://tools.ietf.org/html/rfc2616#section-5.1). @@ -189,9 +189,9 @@ elements that form a layered architecture model. information model of the base specification together with the chosen extensions is encoded for mapping it to header and payload elements of an application protocol. -4. The transport bindings, e.g. [HTTP](http-transport-binding.md), defines how +4. The protocol bindings, e.g. [HTTP](http-protocol-binding.md), defines how the CloudEvent is bound to an application protocol's transport frame, in the - case of HTTP to the HTTP message. The transport binding does not constrain + case of HTTP to the HTTP message. The protocol binding does not constrain how the transport frame is used, meaning that the HTTP binding can be used with any HTTP method and with request and response messages. @@ -202,12 +202,12 @@ specific to CloudEvents and can be used to post any kind of one-way event and notifications to a conformant HTTP endpoint. However, the lack of such a specification elsewhere makes it necessary for CloudEvents to define it. -### Transport Error Handling +### Protocol Error Handling The CloudEvents specification, for the most part, does not dictate a processing model associated with the creation or processing of CloudEvents. As such, if there are errors during the processing of a CloudEvent, the software -encountering the error is encouraged to use the normal transport-level error +encountering the error is encouraged to use the normal protocol-level error reporting to report them. ## Versioning of Attributes @@ -296,7 +296,7 @@ Extension attributes should be kept minimal to ensure the CloudEvent can be properly serialized and transported. For example, the Event producers should consider the technical limitations that might be encountered when adding extensions to a CloudEvent. For example, the -[HTTP Binary Mode](http-transport-binding.md#31-binary-content-mode) uses HTTP +[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) uses HTTP headers to transport metadata; most HTTP servers will reject requests with excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate size and number of extension attributes should be kept minimal. @@ -446,7 +446,7 @@ protocol binding, it must belong to either one of the following categories: vendors using it in their products/services. Aside from formal status, a key criterion for whether a protocol or encoding -shall qualify for a core CloudEvents event format or transport binding is +shall qualify for a core CloudEvents event format or protocol binding is whether the group agrees that the specification will be of sustained practical benefit for any party that is unrelated to the product or project from which the protocol or encoding emerged. A base requirement for this is that the protocol diff --git a/roadmap.md b/roadmap.md index c0f863016..b140f9cd2 100644 --- a/roadmap.md +++ b/roadmap.md @@ -29,7 +29,7 @@ _0.1_ - Completed - 2018/04/20 1. Have at least 2 implementations of the specification that can demonstrate interoperability. 1. Include a specification for mapping the CloudEvents specification to - [HTTP](http-transport-binding.md). + [HTTP](http-protocol-binding.md). 1. Include a specification for mapping the CloudEvents specification to [JSON](json-format.md). 1. Changes to the spec to facilitate adoption. @@ -65,7 +65,7 @@ _0.3_ - Completed - 2019/06/13 1. Consider defining uniqueness constraints of event `id`. 1. Consider which fields will be immutable (prevents annotation or redaction). - 1. Consider validating transport bindings with load tests. + 1. Consider validating protocol bindings with load tests. _1.0-rc1_ - Completed - 2019/09/19 @@ -76,7 +76,7 @@ _1.0_ 1. Completion of exit criteria for 'verification & testing' period. 1. Completion of as many `try-for-v1.0` issues and PRs as possible. The expectation is that these are non-breaking changes to the core spec. - Format and transport-binding specs may introduce breaking change if + Format and protocol-binding specs may introduce breaking change if necessary to align with the core spec. _Post 1.0_