[Docs] DurableStateBehavior should document RecoveryCompleted signal and correct import

[hanishi]

The DurableStateBehavior documentation doesn't mention the RecoveryCompleted signal or show the correct import path. This leads to a subtle bug when users copy patterns from EventSourcedBehavior examples.

Problem

DurableStateBehavior and EventSourcedBehavior have different RecoveryCompleted signals in different packages:

Behavior	Signal Import
EventSourcedBehavior	org.apache.pekko.persistence.typed.RecoveryCompleted
DurableStateBehavior	org.apache.pekko.persistence.typed.state.RecoveryCompleted

This introduced a subtle bug in my code: when I used the wrong import, the pattern match failed silently. The signal handler never triggered, but:

• The code compiled without errors
• No runtime exception was thrown
• The signal was not matched

Questions

1. Is there a reason these are separate types? They seem to serve the same purpose.

2. Could they be unified? A single RecoveryCompleted signal would prevent this mistake.

3. If they must remain separate, could the compiler warn? Perhaps a sealed trait or exhaustiveness check could help catch this at compile time.

4. At minimum, should the DurableStateBehavior docs mention this? The current docs don't show receiveSignal usage or the correct import.

Environment

• Pekko version: 1.1.x
• Scala 3.3.x

[pjfanning]

@hanishi we should look at the docs and see if they can be improved. I don't think we should make any code changes without being 100% sure about them.

EventSourcedSignal is already a sealed trait.

pekko/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed/EventSourcedSignal.scala

Line 27 in f6f9f00

sealed trait EventSourcedSignal extends Signal

DurableStateSignal is already a sealed trait.

pekko/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed/state/DurableStateSignal.scala

Line 26 in f6f9f00

sealed trait DurableStateSignal extends Signal

So maybe the issue is that DurableStateBehavior receiveSignal specifies the more generic Signal trait instead of the specific DurableStateSignal.

pekko/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed/state/scaladsl/DurableStateBehavior.scala

Line 137 in f6f9f00

def receiveSignal(signalHandler: PartialFunction[(State, Signal), Unit]): DurableStateBehavior[Command, State]

EventSourcedBehavior receiveSignal also specifies the generic Signal trait instead of the specific EventSourcedSignal.

pekko/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed/scaladsl/EventSourcedBehavior.scala

Line 149 in f6f9f00

def receiveSignal(signalHandler: PartialFunction[(State, Signal), Unit]): EventSourcedBehavior[Command, Event, State]

I assume that the receiveSignal needs to be like that because there are some shared signals. PoisonPill is one that appears in our tests.

[hanishi]

@pjfanning
Thanks a lot for taking the time to look into this and for the improvements.

This may be just something I tripped over, but given that the two APIs are very similar. The wrong RecoveryCompleted import still compiles; I suspect others could run into the same issue. Even a small doc note or example would give people something to find and reference if they do.

[pjfanning]

@hanishi I know that DurableStateBehavior has API hooks for signals but to me, it appears that EventSourced needs the signals because side effects need to handled after recovery. DurableState doesn't appear to have the same issue. I am not an expert in persistence but I'm approaching this from the perspective that if the signals were important in DurableState, they would be better documented.

https://pekko.apache.org/docs/pekko/current/typed/persistence.html#event-handler

Side effects should be performed in thenRun from the command handler after persisting the event or from the RecoveryCompleted after Recovery.

https://pekko.apache.org/docs/pekko/current/typed/durable-state/persistence.html#effects-and-side-effects

The Durable State docs have good detail about handling side effects but do not mention signals at all. I think this might be deliberate.

@ptrdom @samueleresca @He-Pin @raboof @mdedetrich may be able to provide a better insight than me.

[pjfanning]

@pjfanning Thanks a lot for taking the time to look into this and for the improvements.

This may be just something I tripped over, but given that the two APIs are very similar. The wrong RecoveryCompleted import still compiles; I suspect others could run into the same issue. Even a small doc note or example would give people something to find and reference if they do.

@hanishi I think it is coincidence that my comment above appeared at same time as your comment. I have added #2585 to try to improve docs.

[He-Pin]

@hanishi If you have something in mind, just do it, it would be nice to see the PR.

[hanishi]

@pjfanning @He-Pin
Thanks for the explanation, that makes sense, and I agree that DurableStateBehavior generally encourages handling side effects via thenRun.

That said, I did run into a concrete case where RecoveryCompleted is useful with DurableStateBehavior. After a restart, I need to re-publish the recovered state into DData (replicator) so that other nodes can see the current view. In that scenario, having a clear “recovery boundary” is important to avoid publishing before the state is fully loaded. This was actually the first time I tried to do this with DurableStateBehavior, which is probably why I noticed it.

So while signals may not be the primary mechanism for DurableStateBehavior, there are some scenarios where they’re still quite useful. Given that the hook and signal exist, even a short doc mention or example would help set expectations and avoid confusion around the correct import.

Thanks again for looking into this, and I'm happy to defer to others’ insight on whether this was an intentional omission.

[hanishi]

My mistake, I hit the wrong button.

[hanishi]

For users evaluating it as a simpler alternative to repository-style persistence, small details like recovery boundaries and post-restart hooks can make the difference between “this fits” and “this is confusing”. EventSourcingBehavior isn’t inherently problematic, but it introduces additional complexity around recovery and side effects. For some entities, DurableStateBehavior is sufficient and easier to adopt, particularly for users coming from a traditional repository-based architecture. In those cases, RecoveryCompleted provides a clear boundary indicating when the state is fully available and can be cached or otherwise acted upon as needed.

[ptrdom]

The typing on the signals definitely seems quite loose, probably was never improved because it is more of an internal API. We could try to improve it, but it is somewhat cumbersome to do without proper union types (Scala 3, shapeless (?)), so maybe better docs will have to do for now.

When it comes to side effects, I think the docs also somewhat carelessly advise on performing side effects through thenRun or signals, because it is only good for side effects where durability and scalability of the handling does not matter.