Skip to main content

Domain Events

Recommendation
Updated
Moved
USE
2023-10-10

What is it​

Domain events are an event type used to share information between systems.

Domain events should be self-explanatory and self-contained, leaving the receiver of the event with all information needed, without needing to request additional information from the source system, or without applying logic to figure out what happened.

This type of event pattern is called Event-Carried State Transfer.

The events are typically small with a clear purpose, like ShipmentCreated or ShipmentPickupCompleted, rather than big and generic like change events.

Why we use it​

To reduce coupling between systems, to be able to scale systems independently of each other, and to avoid temporal dependencies between systems.

When to use it​

To communicate business events between systems.

It is recommended to use the outbox pattern to guarantee consistency and at-least-once delivery.

Example event:

message DomainEvent {
  // A UUIDv4 id for this event.
  string event_id = 1;
  // The timestamp of when the event was created.
  google.protobuf.Timestamp event_time = 2;
  // All the IAM members of the caller that created the event.
  repeated string iam_members = 3;
  // Trace ID of the request that emitted this event. This field can be empty.
  string trace_id = 4;
  // The type of domain event.
  oneof event_type {
    // Shipment created.
    ShipmentCreatedEvent shipment_created = 5;
    // Shipment deleted.
    ShipmentDeletedEvent shipment_deleted = 6;
  }
}

// Event capturing when a shipment was created.
message ShipmentCreatedEvent {
  // Details of the created shipment.
  Shipment shipment = 1;
}

// Event capturing when a shipment was deleted.
message ShipmentDeletedEvent {
  // Reference to the deleted shipment.
  string shipment = 1 [
    (google.api.resource_reference) = {type: "freight-example.einride.tech/Shipment"}
  ];
}

How to learn it​