feat: Replication filters #292

patriknw · 2025-03-13T13:09:29Z

No description provided.

patriknw · 2025-03-13T13:10:48Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/ReplicationFilter.java

+    return ReplicationFilterImpl.empty().removeRegion(region);
+  }
+
+  ReplicationFilter addRegion(String region);


would have been nice if the static method could have been named the same, but that's not possible with Java

The usage of it will be something like:

ReplicationFilter .includeRegion("region-1") .addRegion("region-2")

and that is odd.

I think we can solve it with an intermediate interface called BaseReplicationFilter.

The base defines the instance methods.
The static methods in ReplicationFilter should return BaseReplicationFilter.

The ReplicationFilterImpl should implement BaseReplicationFilter.

thanks, changed to something like that in ef93a53

patriknw · 2025-03-13T13:11:29Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/ReplicationFilter.java

+
+import akka.javasdk.impl.effect.ReplicationFilterImpl;
+
+public interface ReplicationFilter {


I want to have this rather open for future additions of other types of filters, than regions.

johanandren

SDK side looking good so far

johanandren · 2025-03-24T14:58:29Z

akka-javasdk/src/main/scala/akka/javasdk/impl/SdkRunner.scala

-            keyValue = false)
+            keyValue = false,
+            replicationFilterEnabled = true
+          ) // FIXME how shall we enable it? Can we solve it without enable flag?


Enabling in the sense that a user opts in, or in the sense that the SDK supports it?

"user opts in". By default we replicate to all regions, until the user defines a filter with regions. However, on the runtime side the filter mechanism is added at startup.

Yeah, I got that part about replicate everywhere by default, but this toggle, is this to say SDK supports it and then user opts in by defining filters, or this should be true/false based on user choice in entity definition/annotation something?

My original thought was that the user would have to enable this for a specific entity. Could be an annotation or a method override. However, that is rather clunky and it would be better to enable by setting the replication filter in the effect, but that happens later. Not sure yet if we can get rid of this flag.

johanandren · 2025-03-24T15:28:18Z

samples/shopping-cart-quickstart/src/main/java/shoppingcart/application/ShoppingCartEntity.java

+      }
+      for (String region : item.removeRegions()) {
+        filter = filter.removeRegion(region);
+      }


If we expect a lot of non-single add/remove (not sure we do), it would be nicer with prepared methods taking Collection<String>

johanandren · 2025-03-24T15:30:02Z

samples/shopping-cart-quickstart/src/main/java/shoppingcart/application/ShoppingCartEntity.java

+
+      if (item.productId().isEmpty()) {
+        return effects()
+            .replicationFilter(filter)


Mismatch between persist which is imperative and replicationFilter, would be better if it was also imperative, even if longer, something like updateReplicationFilter or setReplicationFilter

patriknw · 2025-10-21T09:58:19Z

Refreshed, ready for review

patriknw · 2025-10-22T08:29:59Z

docs/src/modules/sdk/pages/event-sourced-entities.adoc

+----
+
+If you start with an entity with such self region filter in `gcp-us-east1`, and then later receive a command (not read-only) for this entity instance in another `aws-us-east-2`, it will automatically synchronize all events in from `gcp-us-east1` before handling the command in `gcp-us-east1`. Such command will also automatically include `aws-us-east-2` to the replication filter and events will be replicated to both `gcp-us-east1` and `aws-us-east-2`. You can remove a region from the replication with `ReplicationFilter.excludeRegion`.
+


I was thinking about how we can handle replication filter for the agent session memory. Perhaps we can always make the session memory self region only, as described above? If the session is used from another region it will sync and automatically add that region in the filter.

Wouldn't that defeat the idea that the user should decide where to replicate?
I get that once the session memory is used on a new region, we need to start to replicate. But will users be able to block it?

And there is another issue. It will be all session memory events that will start to replicate because it's all the same entity.

I want to start with something simple, and therefore included the self region filter in the session memory: 4332bda

Otherwise we would have to add filters to the MemoryProvider so that it can be defined in the agent, and passed on to the SessionMemoryEntity. Let's see if there is demand for that.

It will be all session memory events that will start to replicate because it's all the same entity

yeah, I don't see a problem with that. it's the session. We could add some kind of region filtering to the MemoryFilter, but let's wait for real demand for such thing

octonato

Looking good

Left some comments for now. I will continue reviewing.

octonato · 2025-10-23T07:13:07Z

...vasdk/src/main/scala/akka/javasdk/impl/eventsourcedentity/EventSourcedEntityEffectImpl.scala

  }

+  override def updateReplicationFilter(filter: ReplicationFilter): OnSuccessBuilder[S] = {
+    _replicationFilter = filter.asInstanceOf[ReplicationFilterImpl]


It seems that the only reason to cast here is because later we want to call toSpi on it.

Could the interface have accessors for toIncludeRegions and toExcludeRegions instead?

We can then transform to SPI using some static method receiving the interface time.

ok, changed in 9e3ff88

octonato · 2025-10-23T07:14:53Z

akka-javasdk/src/main/scala/akka/javasdk/impl/effect/ReplicationFilterImpl.scala

+ * INTERNAL API
+ */
+@InternalApi
+private[javasdk] final case class ReplicationFilterImpl(addRegions: Set[String], removeRegions: Set[String])


nitpicking, but I think the names here should be includedRegions and excludedRegions

octonato · 2025-10-23T07:19:02Z

akka-javasdk/src/main/java/akka/javasdk/annotations/EnableReplicationFilter.java

+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface EnableReplicationFilter {}


I don't get why we need the annotation.
Maybe I should go back to the runtime PR to understand it, but if you can provide a short explanation, that will help.

Ok, I went back to the runtime PR and now it's clear why.
We need to configure the consumer and we need this info in the descriptor. Makes sense.

octonato · 2025-10-23T07:26:23Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/ReplicationFilter.java

+    return ReplicationFilterImpl.empty().removeRegion(region);
+  }
+
+  ReplicationFilter addRegion(String region);


The usage of it will be something like:

ReplicationFilter .includeRegion("region-1") .addRegion("region-2")

and that is odd.

octonato · 2025-10-23T07:32:46Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/ReplicationFilter.java

+    return ReplicationFilterImpl.empty().removeRegion(region);
+  }
+
+  ReplicationFilter addRegion(String region);


I think we can solve it with an intermediate interface called BaseReplicationFilter.

The base defines the instance methods.
The static methods in ReplicationFilter should return BaseReplicationFilter.

The ReplicationFilterImpl should implement BaseReplicationFilter.

aludwiko · 2025-11-03T10:42:30Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/EventSourcedEntity.java

+       * to include one region and then later make another update to include a different region from
+       * the same entity, both regions are included.
+       *
+       * <p>After enabling replication filter with the {@code @EnableReplicationFilter} annotation,


I would rephrase this paragraph or remove it. Maybe we should mention the annotation at the beginning that it's required when using this method?

aludwiko · 2025-11-03T10:44:12Z

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/ReplicationFilter.java

+ * to include one region and then later make another update to include a different region from the
+ * same entity, both regions are included.
+ *
+ * <p>After enabling replication filter with the {@code @EnableReplicationFilter} annotation, the


Here, this paragraph duplicates the information.

aludwiko · 2025-11-03T10:46:59Z

docs/src/modules/sdk/pages/event-sourced-entities.adoc

+<1> Enable the replication filter feature by adding the `@EnableReplicationFilter` annotation.
+<2> Define the replication filter with the `updateReplicationFilter` effect.
+
+After enabling the replication filter the entity is still replicated to all regions until the regions are defined with the `updateReplicationFilter` effect. This effect can be combined with persisting events or used without additional events. The filter can only be updated from the entity's primary region. With the `request-region` primary selection strategy, updating the filter from a non-primary region will cause that region to become the new primary. The filter is durable for the specific entity instance and can be changed without deploying a new version.


Suggested change

After enabling the replication filter the entity is still replicated to all regions until the regions are defined with the `updateReplicationFilter` effect. This effect can be combined with persisting events or used without additional events. The filter can only be updated from the entity's primary region. With the `request-region` primary selection strategy, updating the filter from a non-primary region will cause that region to become the new primary. The filter is durable for the specific entity instance and can be changed without deploying a new version.

After enabling the replication filter the entity is still replicated to all regions until specific regions are defined with the `updateReplicationFilter` effect. This effect can be combined with persisting events or used without additional events. The filter can only be updated from the entity's primary region. With the `request-region` primary selection strategy, updating the filter from a non-primary region will cause that region to become the new primary. The filter is durable for the specific entity instance and can be changed without deploying a new version.

aludwiko · 2025-11-03T10:53:57Z

docs/src/modules/sdk/pages/event-sourced-entities.adoc

+<1> Enable the replication filter feature by adding the `@EnableReplicationFilter` annotation.
+<2> Define the replication filter with the `updateReplicationFilter` effect.
+
+After enabling the replication filter the entity is still replicated to all regions until the regions are defined with the `updateReplicationFilter` effect. This effect can be combined with persisting events or used without additional events. The filter can only be updated from the entity's primary region. With the `request-region` primary selection strategy, updating the filter from a non-primary region will cause that region to become the new primary. The filter is durable for the specific entity instance and can be changed without deploying a new version.


This effect can be combined with persisting events or used without additional events. -> Maybe add some additional clarification on when to use which, sth like see below for replication configuration with events persistence use case.

I tried to incorporate your feedback in bfa6156

aludwiko · 2025-11-03T11:23:51Z

samples/doc-snippets/src/main/java/com/example/replicationfilter/ShoppingCartEntity.java

+
+  public Effect<Done> replicateTo(String region) {
+    return effects()
+      .updateReplicationFilter(ReplicationFilter.includeRegion(region)) // <2>


Since this configuration is additive, are we planning to somehow provide the information about the current replication filter configuration? Either via ESE state or backoffice or maybe both.

Both specific replication and the more static filtering enabled flag would be nice to show in backoffice IMO

created an issue for backoffice https://github.com/lightbend/akka-runtime/issues/4449

I have also thought about the need for exposing current filter in the entity context, but haven't seen a clear use case for it

johanandren

LGTM with some small docs feedback.

docs/src/modules/sdk/pages/event-sourced-entities.adoc

patriknw · 2025-11-05T16:53:46Z

akka-javasdk/src/main/java/akka/javasdk/agent/SessionMemoryEntity.java

+ *
+ * <p>The session memory has the multi-region replication filter enabled to only include the local
+ * region when using `request-region` primary selection. When accessed from another region the
+ * filter will be expanded to include the other region too.


I should probably mention this in the reference docs too

* Reflect isReplicationFilterEnabled * ReplicationFilterImpl since that would be same for kve and workflow * docs, JavaDoc * replication filter in SessionMemoryEntity * ReplicationFilter.Builder to be able to use the same method names * note about excluded region * incorporate feedback

github-actions bot added documentation documentation related java-sdk labels Mar 13, 2025

patriknw commented Mar 13, 2025

View reviewed changes

patriknw changed the title ~~Wip replication filter patriknw~~ feat: Replication filters Mar 14, 2025

johanandren reviewed Mar 24, 2025

View reviewed changes

patriknw force-pushed the wip-replication-filter-patriknw branch from 2d7682d to 8e42c93 Compare April 7, 2025 11:49

patriknw force-pushed the wip-replication-filter-patriknw branch from 8e42c93 to e8a7720 Compare October 21, 2025 08:51

patriknw marked this pull request as ready for review October 21, 2025 09:57

patriknw commented Oct 22, 2025

View reviewed changes

octonato reviewed Oct 23, 2025

View reviewed changes

patriknw force-pushed the wip-replication-filter-patriknw branch from d6989bf to ef93a53 Compare November 3, 2025 10:03

aludwiko reviewed Nov 3, 2025

View reviewed changes

johanandren approved these changes Nov 4, 2025

View reviewed changes

docs/src/modules/sdk/pages/event-sourced-entities.adoc Show resolved Hide resolved

patriknw commented Nov 5, 2025

View reviewed changes

patriknw force-pushed the wip-replication-filter-patriknw branch from bfa6156 to 68cf17d Compare November 11, 2025 09:44


		import akka.javasdk.impl.effect.ReplicationFilterImpl;

		public interface ReplicationFilter {

		----

		If you start with an entity with such self region filter in `gcp-us-east1`, and then later receive a command (not read-only) for this entity instance in another `aws-us-east-2`, it will automatically synchronize all events in from `gcp-us-east1` before handling the command in `gcp-us-east1`. Such command will also automatically include `aws-us-east-2` to the replication filter and events will be replicated to both `gcp-us-east1` and `aws-us-east-2`. You can remove a region from the replication with `ReplicationFilter.excludeRegion`.

feat: Replication filters #292

Are you sure you want to change the base?

feat: Replication filters #292

Uh oh!

Conversation

patriknw commented Mar 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johanandren left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

patriknw commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

octonato left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aludwiko Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johanandren left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

aludwiko Nov 3, 2025 •

edited

Loading