Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 15 additions & 30 deletions cloudevents/extensions/sequence.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
# Sequence

This extension defines two attributes that can be included within a CloudEvent
This extension defines an attribute 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.
stream of events. This specification does not define the meaning or set of
valid value of this attribute, rather it only mandates that the value be
a string that can be lexicographically compared to other `sequence` values
to determine which one comes first. The `sequence` with a lower lexicographical
value comes first.

Produces and consumers are free to define an out-of-band agreement on the
semantic meaning, or valid values, for the attribute.

## Attributes

Expand All @@ -23,27 +26,9 @@ of the attribute.
- 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).
The entity creating the CloudEvent MUST ensure that the `sequence` values
used are formatted such that across the entire set of values used a receiver
can determine the order of the events via a simple string-compare type of
operation. This means that it might be necessary for the value to include
some kind of padding (e.g. leading zeros in the case of the value being the
string representation of an integer).
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider pushing them towards hex if they want numeric

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the sequencetype is removed, this limits each source to producing just a single sequence at the same time. I could imagine that in addition to a generic sequencetype Integer, there could be domain specific sequence types distinguishing different scenarios or processes. A single source should not be restricted to generating events belonging to a single sequence. There could even be one sequence per combination of source and subject.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is interesting because it sounds like you want to use "sequenceType" as a form of differentiator of sequences. While I'm interpreting it as a refinement of the "type" of the sequence... meaning, int vs string vs something else. And so I see the possible values of "sequenceType" as being very limited - in the same way type systems are usually limited. In your model, I think "sequenceType" values would basically be unlimited and almost app/stream specific. I'm not sure that was the intent... but I could be wrong. Am I following you correctly?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I agree that my interpretation of sequencetype might not be what was originally intended. I just wonder, if we really want to limit each unique source to exactly one sequence? Of course, there is some freedom in how the value for sequence is generated, but a generic intermediary will always sort events from one unique source using the sequence attribute.
I see two ways to extend this:

  1. Add an attribute sequenceid that allows to distinguish between multiple sequences of the source.
  2. State that sources must be sufficiently fine-grained to always only emit one sequence. You could achieve this by adding the sequenceid as an additional path segment to the source.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BenBeattieHood @jroper any thoughts on @deissnerk's last comment?