ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-610] Event Ordering ​

Overview ​

This ADP defines a standard method for implementing event ordering using the CloudEvents Sequence Extension.

Guidelines ​

  1. MUST use the CloudEvents Sequence Extension to implement event ordering.

  2. Event producers MUST set the sequence attribute for events that require ordering.

  3. The sequence attribute MUST be a non-empty, lexicographically-orderable string.

  4. The sequence attribute SHOULD be monotonically increasing and contiguous.

  5. Event consumers SHOULD be able to process events based on their sequence order.

CloudEvents Sequence Extension ​

The Sequence Extension adds one attribute to CloudEvents:

  • sequence: A string value expressing the relative order of the event.

Example CloudEvent with sequence:

json
{
    "specversion" : "1.0",
    "type" : "com.example.someevent",
    "source" : "/mycontext",
    "id" : "C234-1234-1234",
    "time" : "2023-06-01T10:30:00Z",
    "sequence": "000000000042",
    "data" : {
        "message" : "This event is ordered"
    }
}

Implementation Recommendations ​

  1. Choose an appropriate sequence generation strategy that ensures lexicographical ordering (e.g., zero-padded integers, timestamps with sufficient precision).

  2. Implement mechanisms to handle out-of-order event reception, such as buffering and reordering.

  3. Consider using the sequence attribute in conjunction with the source attribute to maintain order within specific event streams.

  4. Implement error handling for sequence gaps or duplicates.

  5. Provide clear documentation on the semantics and valid values of the sequence attribute for your specific use case.

Use Cases ​

  1. Financial Transactions: Ensure that account transactions are processed in the correct order.

  2. Audit Logging: Maintain a precise chronological order of system events for auditing purposes.

  3. Data Replication: Ensure that data changes are applied in the correct order across distributed databases.

  4. Event Sourcing: Maintain the order of events in event-sourced systems to correctly rebuild application state.

Security Considerations ​

  1. Ensure that the sequence generation mechanism cannot be manipulated by malicious actors to disrupt event ordering.

  2. Be aware of potential information leakage through sequence numbers (e.g., transaction volume inference).

  3. Implement appropriate access controls to prevent unauthorized manipulation of sequence attributes.

References ​