From 8d2a063571f27184b719f07080602d043c983d1b Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Fri, 15 Mar 2019 06:12:33 -0700 Subject: [PATCH 1/3] Add some guidance on how to construct CloudEvents Since not all event producers will generate CloudEvents natively, it might be good to provide some guidance around how the CE attributes should be populated when the CE producer isn't the event producer. Signed-off-by: Doug Davis --- primer.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/primer.md b/primer.md index 739f2ef6e..c04338923 100644 --- a/primer.md +++ b/primer.md @@ -22,7 +22,7 @@ This document is a working draft. - [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) - [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) -- [Roles](#roles) +- [Traditional Eventing Roles](#traditional-eventing-roles) - [Value Proposition](#value-proposition) - [Existing Event Formats](#existing-event-formats) @@ -243,6 +243,60 @@ serialization for unkown, or even new, properties. It was also noted that the HTTP specification is now following a similar pattern by no longer suggesting that extension HTTP headers be prefixed with `X-`. +## Creating CloudEvents + +The CloudEvents specification purposely avoids being too prescriptive about +how CloudEvents are created. For example, it does not assume that the original +event producer is the same entity that is constructing the associated +CloudEvent for that event. This allows for a wide variety of implementation +choices. However, it can be useful for implementors of the specification +to understand the expectations that the authors of the specifcations had +in mind while developing the specification as this might help ensure +interoperability and consistency. + +As mentioned above, whether the entity that generated the initial event is +the same entity that creates the corresponding CloudEvent is an implementation +choice. However, when the entity that is constructing/populating the +CloudEvents attributes is acting on behalf of the event producer, the values +of those attributes are meant to describe the event or the event producer +and not the entity calculating the CloudEvent attribute values. In other words, +when the split between the event producer and the CloudEvents generator are +not materially significant to the event consumers, the spec defined +attributes would typically not include any values to indicate this split +of responsibilities. + +This isn't to suggest that the CloudEvents generator +couldn't add some additional attributes to the CloudEvent, but those +are outside the scope of the interoperability defined attributes of the spec. +This is similar to how an HTTP proxy would typically minimize changes to the +well-defined HTTP headers of an incoming message, but it might add some +additional headers that include proxy-specific metadata. + +It is also worth noting that this separation between original event producer +and CloudEvents generator could be small or large. Meaning, even if the +CloudEvent generator not part of the original event producer's ecosystem, +if it is acting on behalf of the event producer, and its presence in the +flow of the event is not meaningful to event consumers, then the above +guidance would still apply. + +When an entity is acting as both a receiver and sender of CloudEvents +for the purposes of forwarding, or transforming, the incoming event, the +degree to which the outbound CloudEvent matches the inbound CloudEvent +will vary based on the processing semantics of this entity. In cases where +it is acting as proxy, where it is simply forwarding CloudEvents +to another event consumer, then the outbound CloudEvent will typically +look identical to the inbound CloudEvent with respect to the spec defined +attributes - see previous paragraph concerning adding additional attributes. +Note that in these cases, while the entity is "sending" CloudEvents, it +is not really an "event producer". + +However, if this entity is performing some type of semantic processing +of the CloudEvent, typically resulting in a change to the value of the +`data` attribute, then it may need to be considered a distinct "event +producer" from the original event producer. And as such, it is expected +that CloudEvents attributes related to the event producer (such as 'source` +and `id`) would be changed from the incoming CloudEvent. + ## Qualifying Protocols and Encodings The explicit goal of the CloudEvents effort, as expressed in the specification, @@ -328,7 +382,7 @@ links to all specs. This section describes some of the input material used by the group during the development of the CloudEvent specification. -### Roles +### Traditional Eventing Roles The list below enumerates the various participants, and scenarios, that might be involved in the producing, managing or consuming of events. From 172f306eb1e001293942929f401c49bd980ee3fc Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 30 May 2019 06:01:24 -0700 Subject: [PATCH 2/3] More edits Signed-off-by: Doug Davis --- primer.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/primer.md b/primer.md index c04338923..fbfe4ed65 100644 --- a/primer.md +++ b/primer.md @@ -22,7 +22,7 @@ This document is a working draft. - [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) - [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) -- [Traditional Eventing Roles](#traditional-eventing-roles) +- [Roles](#roles) - [Value Proposition](#value-proposition) - [Existing Event Formats](#existing-event-formats) @@ -274,7 +274,7 @@ additional headers that include proxy-specific metadata. It is also worth noting that this separation between original event producer and CloudEvents generator could be small or large. Meaning, even if the -CloudEvent generator not part of the original event producer's ecosystem, +CloudEvent generator were not part of the original event producer's ecosystem, if it is acting on behalf of the event producer, and its presence in the flow of the event is not meaningful to event consumers, then the above guidance would still apply. @@ -382,7 +382,7 @@ links to all specs. This section describes some of the input material used by the group during the development of the CloudEvent specification. -### Traditional Eventing Roles +### Roles The list below enumerates the various participants, and scenarios, that might be involved in the producing, managing or consuming of events. @@ -684,7 +684,7 @@ existing current event formats that are used in practice today was gathered. #### AWS - CloudWatch Events -A high proportion of event-processing systems on AWS are converging on +A high proportion of event-processing systems on AWS are converging on the use of this format. ``` From de356dda8c425c332da203fcd34e47e89f81970b Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 30 May 2019 06:19:39 -0700 Subject: [PATCH 3/3] clarify split between source and producer better Signed-off-by: Doug Davis --- primer.md | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/primer.md b/primer.md index fbfe4ed65..b0299334a 100644 --- a/primer.md +++ b/primer.md @@ -247,35 +247,34 @@ that extension HTTP headers be prefixed with `X-`. The CloudEvents specification purposely avoids being too prescriptive about how CloudEvents are created. For example, it does not assume that the original -event producer is the same entity that is constructing the associated -CloudEvent for that event. This allows for a wide variety of implementation +event source is the same entity that is constructing the associated +CloudEvent for that occurrence. This allows for a wide variety of implementation choices. However, it can be useful for implementors of the specification -to understand the expectations that the authors of the specifcations had -in mind while developing the specification as this might help ensure -interoperability and consistency. +to understand the expectations that the specification authors had in mind +as this might help ensure interoperability and consistency. As mentioned above, whether the entity that generated the initial event is the same entity that creates the corresponding CloudEvent is an implementation choice. However, when the entity that is constructing/populating the -CloudEvents attributes is acting on behalf of the event producer, the values -of those attributes are meant to describe the event or the event producer +CloudEvents attributes is acting on behalf of the event source, the values +of those attributes are meant to describe the event or the event source and not the entity calculating the CloudEvent attribute values. In other words, -when the split between the event producer and the CloudEvents generator are +when the split between the event source and the CloudEvents producer are not materially significant to the event consumers, the spec defined attributes would typically not include any values to indicate this split of responsibilities. -This isn't to suggest that the CloudEvents generator +This isn't to suggest that the CloudEvents producer couldn't add some additional attributes to the CloudEvent, but those are outside the scope of the interoperability defined attributes of the spec. This is similar to how an HTTP proxy would typically minimize changes to the well-defined HTTP headers of an incoming message, but it might add some additional headers that include proxy-specific metadata. -It is also worth noting that this separation between original event producer -and CloudEvents generator could be small or large. Meaning, even if the -CloudEvent generator were not part of the original event producer's ecosystem, -if it is acting on behalf of the event producer, and its presence in the +It is also worth noting that this separation between original event source +and CloudEvents producer could be small or large. Meaning, even if the +CloudEvent producer were not part of the original event source's ecosystem, +if it is acting on behalf of the event source, and its presence in the flow of the event is not meaningful to event consumers, then the above guidance would still apply. @@ -287,13 +286,11 @@ it is acting as proxy, where it is simply forwarding CloudEvents to another event consumer, then the outbound CloudEvent will typically look identical to the inbound CloudEvent with respect to the spec defined attributes - see previous paragraph concerning adding additional attributes. -Note that in these cases, while the entity is "sending" CloudEvents, it -is not really an "event producer". However, if this entity is performing some type of semantic processing of the CloudEvent, typically resulting in a change to the value of the `data` attribute, then it may need to be considered a distinct "event -producer" from the original event producer. And as such, it is expected +source" from the original event source. And as such, it is expected that CloudEvents attributes related to the event producer (such as 'source` and `id`) would be changed from the incoming CloudEvent.