Skip to content

docs: consumers and multi-region - #2130

Merged
ennru merged 5 commits into
mainfrom
multiregion-consumers
Oct 23, 2026
Merged

ennru merged 5 commits into
mainfrom
multiregion-consumers

Conversation

@ennru

@ennru ennru commented Oct 22, 2026

Copy link
Copy Markdown
Contributor

Detailed discussion of how to design consumers for multi-region scenarios.

@github-actions github-actions Bot added the documentation documentation related label Oct 22, 2026

@patriknw patriknw left a comment

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.

human review

* <li>This method will always return {@code false} when consuming messages from another service
* (see {@link Consume.FromServiceStream}) or from a topic (see {@link Consume.FromTopic}).
* <li>If the message originates from a component ({@link EventSourcedEntity}, {@link
* KeyValueEntity}, or {@link Workflow}) in the same region as this consumer is running, it

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.

reads strange to me: "from a component EventSourcedEntity"

"from a EventSourcedEntity, ... component"

== Multi-region replication

Consumers are not replicated directly in the same way as for example xref:event-sourced-entities.adoc#_replication[Event Sourced Entity replication]. A Consumer receives events from entities in the same service, or another service, in the same region. The entities will replicate all events across regions and identical processing can occur in the consumers of each region.
Consumers process events in their own region. They are not replicated directly like xref:event-sourced-entities.adoc#_replication[Event Sourced Entities]. When entity events replicate to another region, Consumers there can also process them, subject to replication filters.

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.

remove "subject to replication filters" since that is a separate topic and already and already covered by "When entity events replicate to another region,"

An event's origin can differ from its entity's current primary region.

In the illustrations, circles represent Consumers in regions A, B, and C. Boxes represent external destinations, and arrows represent calls.
A dashed circle represents a Consumer that skips the event. A check mark represents deduplication at the shared destination.

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.

This could be a more visual legend bullet list with an example icon for each case

| A shared external system, with actions assigned to the event's origin region
a| image:consumer-origin-only.svg[Only the Consumer in origin region A calls the destination,width=144]

Only the origin region

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.

A variant of this is to have the consumer processing only in one region, instead of filtering on the origin. That would be implemented by looking at the selfRegion and only have active processing when that is matching one predefined region.


// tag::event[]
public record OrderPlaced(String orderId, String paymentOperationId, long amountInCents)
implements OrderEvent {}

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.

The normal and recommended way is to define the event inside the sealed interface. This is also missing the @TypeName

public sealed interface CartEvent {
  @TypeName("cart-created")
  record CartCreated(String cartId, long creationTimestamp) implements CartEvent {
  }

----
<1> Use the persisted operation identifier for every payment attempt, including retries after a lost response. `asyncDone` acknowledges processing only after the provider call succeeds.

These are compiled service components in the documentation snippets project, rather than a standalone deployable service.

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.

What is this?


=== Regional order indexes and shared payments example

The following order fulfilment example has an Event Sourced `OrderEntity` and two Consumers.

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.

This code example is for "Processing with regional destinations"? Does that add much value over any other consumer example that we already have? That is like an ordinary consumer without any choices depending on origin?

@ennru

ennru commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

I removed the table with the variants and just kept the explanations.
Also dropped the code example as its value was doubtful.

@patriknw patriknw left a comment

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.

LGTM

@ennru
ennru merged commit 8d8c695 into main Oct 23, 2026
38 checks passed
@ennru
ennru deleted the multiregion-consumers branch October 23, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants