Add samples for replicated event sourcing over gRPC

[pvlugter]

Trying out the replicated event sourcing over gRPC by modifying a sample. Last commit has just the replication changes. Not completely obvious just based on the current docs. Ended up with similar changes as in lightbend/akka-projection-grpc-benchmark#2 (without looking at that first).

[johanandren]

This one we'd want a predefined factory method returning ReplicationProjectionProvider for in akka-projection-r2dbc (suggested by Patrik in the benchmark)

[pvlugter]

Updated the shopping cart sample so that it's convergent — simple counters for the items, and the checkout has a closing step to wait for all replicated events and only complete the checkout on one replica (similar approach as for closing in the auction sample). See e81ec6d.

To be able to do this, needed the actor context from composing with setup behaviour. Hacked in an API for this within the current one — which inverts the external replication setup to be a callback within the factory callback. Maybe a bit convoluted, but needed something. See 3477c3d, and its usage in the sample:

akka-projection/samples/replicated/shopping-cart-service-scala/src/main/scala/shopping/cart/ShoppingCart.scala

Lines 132 to 141 in e81ec6d

	Replication.grpcReplicationWithSetup(replicationSettings)(ShoppingCart.apply)
	}
	def apply(replicationSetup: Replication.ReplicationSetup[Command, Event, State]): Behavior[Command] = {
	Behaviors.setup[Command] { context =>
	replicationSetup { replicationContext =>
	new ShoppingCart(context, replicationContext).behavior()
	}
	}
	}

[johanandren]

This kind of solution would mean that we need another one for timers, but maybe that is fine?

I think it should go in the replicated entity APIs in core Akka rather than here though

[pvlugter]

Can be used with timers as well. Works with any behaviour composition. So can do this too:

Behaviors.setup[Command] { context =>
  Behaviors.withTimers { timers =>
    replicationSetup { replicationContext =>
      new ShoppingCart(context, replicationContext, timers).behavior()
    }
  }
}

This is what the replication setup variant takes:

((ReplicationContext => EventSourcedBehavior[Command, Event, State]) => Behavior[Command]) => Behavior[Command]

where you pass the replicated behaviour factory function to the given function (which creates the replication context and applies external replication) and returns a behaviour which can then be composed within another behaviour factory function.

Seems a little difficult to understand, although with some explicit types and better naming, could be ok. Maybe also calling it "setup" doesn't make it clear right now.

[johanandren]

Aha, I misread it, good if it works for arbitrary composition so we don't have to cover any possible use case.

I wonder if we could make the ReplicatedEntity.externalReplication less picky somehow, the reason why it requires EventSourcedBehavior to externalReplication is that it needs to set the flag .withReplication(context), which is internal. Maybe we can pass open upp that and pass that responsibility to the user instead?

[pvlugter]

Yes, wondered the same about just opening up withReplication. Although not sure if needing to apply that yourself is that much different from needing to use a provided factory.

I've tidied up the factory approach. Named the SAM class ReplicatedBehaviors with a setup method, so it looks similar to other behaviour factories, but provided to you in the superfactory instead of static methods. Also made this the only way, rather than two different factory approaches. See 343ae71.

Looks like this in the shopping cart now:

def apply(replicatedBehaviors: ReplicatedBehaviors[Command, Event, State]): Behavior[Command] = {
  Behaviors.setup[Command] { context =>
    replicatedBehaviors.setup { replicationContext =>
      new ShoppingCart(context, replicationContext).behavior()
    }
  }
}

[patriknw]

LGTM, but let's merge Johan's first and then merge this to main.

[patriknw]

I was pondering this for a long while to see if we could get away without the extra level of factories. ReplicationContext => Behavior with something in runtime to find the nested EventSourcedBehavior, but that's problematic with deferred behavior (lazy start) and supervision and such.

I think this looks pretty good.

[pvlugter]

I couldn't see a better way either.

[pvlugter]

Rebased and updated. Java sample added. Sample compiles added to CI checks. Will rebase again once #757 is merged.

[pvlugter]

Extended the docs with some example code from the samples.

[pvlugter]

Rebased for main and ready now.

Some code examples for the docs pulled from the samples, which are only compile checked — we may want to have these in integration tests instead.

[johanandren]

LGTM!