ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-608] Temporary Events ​

Overview ​

In distributed systems, events may become irrelevant after a certain point in time. This ADP defines a standard method for marking events as temporary using the CloudEvents Expiry Time Extension, allowing consumers and intermediaries to handle time-sensitive events appropriately.

Guidelines ​

  1. MUST use the CloudEvents Expiry Time Extension to mark temporary events.

  2. Event producers MUST set the expirytime attribute for temporary events.

  3. The expirytime attribute MUST be of type Timestamp.

  4. The expirytime value SHOULD be equal to or later than the time attribute, if present.

  5. Intermediaries and consumers MAY ignore and discard events that have reached or passed their expirytime.

  6. Intermediaries MAY modify the expirytime attribute but MUST NOT remove it.

  7. Systems interacting with consumers SHOULD NOT make assumptions about whether a consumer will keep or discard an event based solely on this extension.

CloudEvents Expiry Time Extension ​

The Expiry Time Extension adds one attribute to CloudEvents:

  • expirytime: A timestamp indicating when an event is no longer useful.

Example CloudEvent with expirytime:

json
{
    "specversion" : "1.0",
    "type" : "com.example.temporaryevent",
    "source" : "/mycontext",
    "id" : "C234-1234-1234",
    "time" : "2023-06-01T10:30:00Z",
    "expirytime": "2023-06-01T11:30:00Z",
    "data" : {
        "message" : "This event expires in one hour"
    }
}

Implementation Recommendations ​

  1. Use consistent time synchronization across systems to ensure accurate expiry time comparisons.

  2. Implement efficient event filtering mechanisms based on the expirytime attribute.

  3. Consider implementing a cleanup process for expired events in event stores or message queues.

  4. Provide clear documentation on how your system handles expired events.

  5. Consider logging or monitoring discarded expired events for system health checks and debugging.

Use Cases ​

  1. Real-time Dashboards: Discard outdated sensor data in web dashboards to display only the most recent information.

  2. Time-limited Offers: Send promotional events with an expiry time for limited-time offers.

  3. Temporary System States: Use temporary events to represent transient system states that are only relevant for a specific duration.

  4. Job Scheduling: Set expiry times for job requests in distributed job processing systems.

Security Considerations ​

  1. Ensure that time-based event filtering doesn't introduce vulnerabilities (e.g., time-of-check to time-of-use issues).

  2. Be aware that malicious actors might try to manipulate system behavior by sending events with crafted expiry times.

  3. Consider the implications of time synchronization issues on event expiry handling.

References ​