Add 'sequence' attribute #291
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Sequence | ||
|
|
||
| This extension defines two attributes that can be included within a CloudEvent | ||
| to describe the position of an event in the ordered sequence of events produced | ||
| by a unique event source. | ||
|
|
||
| The `sequence` attribute represents the value of this event's | ||
| order in the stream of events. The exact value and meaning of this | ||
| attribute is defined by the `sequenceType` attribute. | ||
| If the `sequenceType` is missing, or not defined in this specification, | ||
| event consumers will need to have some out-of-band communication with the | ||
| event producer to understand how to interpret the value of the attribute. | ||
|
|
||
| ## Attributes | ||
|
|
||
| ### sequence | ||
| * Type: `String` | ||
| * Description: Value expressing the relative order of the event. This enables | ||
| interpretation of data supercedence. | ||
| * Constraints | ||
| * REQUIRED | ||
|
There was a problem hiding this comment. can extensions be required? There was a problem hiding this comment. This may be something we need to add more text on... but the point here is that while the extension itself is optional, IF it is being used then this property is REQUIRED. See the documented-extension.md doc, where it says "Support for any extension is OPTIONAL. When an extension definition uses RFC 2199 keywords (e.g. MUST, SHOULD, MAY), this usage only applies to events that use the extension." There was a problem hiding this comment. Thank you for clarifying. This makes perfect sense and clears my confusion. |
||
| * MUST be a non-empty lexicographically-orderable string | ||
| * RECOMMENDED as monotonically increasing and contiguous | ||
|
|
||
| ### sequenceType | ||
| * Type: `String` | ||
| * Description: Specifies the semantics of the sequence attribute. | ||
| See the [SequenceType Values](#sequencetype-values) section for more | ||
| information. | ||
| * Constraints: | ||
| * OPTIONAL | ||
| * If present, MUST be a non-empty string | ||
|
|
||
| ## SequenceType Values | ||
|
|
||
| This specification defines the following values for `sequenceType`. | ||
| Additional values MAY be defined by other specifications. | ||
|
|
||
| ### Integer | ||
| If the `sequenceType` is set to `Integer`, the `sequence` attribute has | ||
| the following semantics: | ||
| * The values of `sequence` are string-encoded signed 32-bit Integers. | ||
| * The sequence MUST start with a value of `1` and increase by `1` for each | ||
| subsequent value (i.e. be contiguous and monotonically increasing). | ||
| * The sequence wraps around from 2,147,483,647 (2^31 -1) to | ||
| -2,147,483,648 (-2^31). | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
idempotency?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if this would be better done by checking the EventID instead? If not, have any suggested text?
Do we need to worry about a single event being part of more than one sequence?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a great question. As per the eventID definition there is no monotinicity requirement. Without a value constraint, one would have to keep track of every
eventIDthat has been processed (or at the very least a significant scope of them) to ensure no duplicate processing as opposed to checking the relationship of the currently being processedeventIDto the last successful checkpointeventID. I'm not sure that the assumptions I like to make would be appropriate to push onto all users fo the spec so I haven't advocated for that there but would have them adopted in my more-perfect world.I'm taking an event as the tangible message sent by a unique producer (as opposed to the occurrence in reality being read by some sensor). As I've read this change, it seemed that there was a one-to-one mapping between unique producers of events with this attribute and the series of numbers representing the singular sequence that they produce. That's a long way to say I don't expect a unique producer to produce multiple sequences OR for multiple unique producers to produce the "same" event (though distinct events could be causally interlinked and contain the exact same content [sans producer id] by the shared reality producing them - e.g. redundant emitters of metrics coming from a single sensor). I could definitely be reading incorrectly.