feat(persistence): add completion callbacks and async handler support

[Aaronontheweb]

Summary

fixes #7935

This PR adds completion callback support and async handler support to Akka.NET persistence, enabling users to:

1. Detect when all events in a PersistAll/PersistAllAsync batch have been persisted and their handlers executed
2. Use async handlers (Func<TEvent, Task>) with all persist methods

Note: This is a proof of concept implementation.

New API Reference

Async Handler Overloads (NEW)

Single event persistence with async handlers:

// Stashing (blocks incoming commands until persisted)
void Persist<TEvent>(TEvent @event, Func<TEvent, Task> handler)

// Non-stashing (continues processing commands while persisting)
void PersistAsync<TEvent>(TEvent @event, Func<TEvent, Task> handler)

Batch Persistence with Async Handlers (NEW)

// Stashing variants
void PersistAll<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler)
void PersistAll<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler, Action onComplete)
void PersistAll<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler, Func<Task> onCompleteAsync)

// Non-stashing variants  
void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler)
void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler, Action onComplete)
void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Func<TEvent, Task> handler, Func<Task> onCompleteAsync)

Completion Callbacks for Sync Handlers (NEW)

// Stashing variants with sync handler
void PersistAll<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler, Action onComplete)
void PersistAll<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler, Func<Task> onCompleteAsync)

// Non-stashing variants with sync handler
void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler, Action onComplete)
void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler, Func<Task> onCompleteAsync)

Usage Examples

Async handler with completion callback:

PersistAll(events, async evt => 
{
    // Async work for each event
    await UpdateProjectionsAsync(evt);
}, 
onComplete: () => 
{
    // Called once after ALL events persisted and handlers executed
    Sender.Tell(new BatchComplete());
});

Async handler with async completion callback:

PersistAll(events, async evt => 
{
    await UpdateProjectionsAsync(evt);
}, 
onCompleteAsync: async () => 
{
    // Async completion work
    await NotifySubscribersAsync();
    Sender.Tell(new BatchComplete());
});

Empty batch handling:

// Completion callback is invoked immediately for empty event lists
PersistAll(Array.Empty<MyEvent>(), _ => { }, () => 
{
    // This is called immediately
    Sender.Tell(new BatchComplete());
});

Changes

New Features

• Completion Callbacks: PersistAll and PersistAllAsync now accept optional onComplete (sync) or onCompleteAsync (async) callbacks that execute after all events in the batch are persisted
• Async Handlers: All 4 persist methods (Persist, PersistAsync, PersistAll, PersistAllAsync) now support Func<TEvent, Task> async handlers

Implementation Details

• Added 8 new invocation classes with interface segregation pattern for sync/async handlers and sync/async completion callbacks
• Added IStashingInvocation marker interface for type-safe detection of stashing invocations
• Added 10 new method overloads providing all combinations of sync/async handlers with sync/async completion callbacks
• Updated PeekApplyHandler to chain all async operations in a single RunTask call to avoid nested RunTask exceptions
• Maintains backward compatibility - all existing persist method signatures unchanged
• Preserves actor semantics (stashing vs non-stashing behavior)

Test Coverage

Added comprehensive test suite in PersistenceCompletionCallbackSpec.cs:

• PersistAllAsync_should_invoke_completion_callback_after_all_events_persisted
• PersistAll_should_invoke_completion_callback_after_all_events_persisted
• PersistAllAsync_should_invoke_async_completion_callback
• PersistAll_should_invoke_async_completion_callback
• PersistAllAsync_should_support_async_handlers
• PersistAsync_should_support_async_handlers
• Completion_callback_should_fire_exactly_once_per_batch
• Empty_event_list_should_invoke_completion_callback_immediately

All 8 new tests pass consistently (100% pass rate).

Test Results

Full test suite results match baseline stability (266-268 passing, 7-10 failing - matching pre-existing baseline variance). No new failures introduced by this implementation.

[Aaronontheweb]

Detailed my changes - IMHO, I think I can simplify this by transforming all of the Action<object> callbacks into Func<object,Task> callbacks by just wrapping the delegate. That will cut down on the number of internal classes and interfaces pretty significantly.

Plus I identified some inconsistencies in how we're handling empty / null event arrays.

[Aaronontheweb]

Moving all of the IPendingHandlerInvocations from public to internal - this is going to be part of the v1.6 API changes.

[Aaronontheweb]

These should have never been public APIs in the first place IMHO

[Aaronontheweb]

Used to signal if the OnCompletion handler should be fired. No-ops for individual Persist / PersistAsync calls.

[Aaronontheweb]

Sync == uses Action<object>
Async == uses Func<object,Task>

[Aaronontheweb]

Completion callbacks don't take an event, so just Action or Func<Task> here

[Aaronontheweb]

Persistence Handler Invocation Types

This document describes the internal invocation types used by Eventsourced actors to manage persistence handlers and completion callbacks.

Interfaces

Interface	Purpose	Key Property
IPendingHandlerInvocation	Base interface for all invocations	Event, IsLastInBatch
ISyncHandlerInvocation	Sync event handler (Action<object>)	Handler
IAsyncHandlerInvocation	Async event handler (Func<object, Task>)	AsyncHandler
ISyncCompletionInvocation	Sync completion callback (Action)	CompletionCallback
IAsyncCompletionInvocation	Async completion callback (Func<Task>)	AsyncCompletionCallback
IStashingInvocation	Marker for stashing behavior (blocks commands)	(none - marker only)

Concrete Classes

Class	Stashing	Handler	Completion	Used By
StashingHandlerInvocation	Yes	Sync	Sync	Persist, PersistAll
StashingHandlerInvocationWithAsyncCompletion	Yes	Sync	Async	PersistAll
StashingAsyncHandlerInvocation	Yes	Async	Sync	Persist, PersistAll
StashingAsyncHandlerInvocationWithAsyncCompletion	Yes	Async	Async	PersistAll
NonStashingHandlerInvocation	No	Sync	Sync	PersistAsync, PersistAllAsync, DeferAsync
NonStashingHandlerInvocationWithAsyncCompletion	No	Sync	Async	PersistAllAsync
NonStashingAsyncHandlerInvocation	No	Async	Sync	PersistAsync, PersistAllAsync
NonStashingAsyncHandlerInvocationWithAsyncCompletion	No	Async	Async	PersistAllAsync

Interface Implementation Matrix

Class	IStashingInvocation	ISyncHandlerInvocation	IAsyncHandlerInvocation	ISyncCompletionInvocation	IAsyncCompletionInvocation
StashingHandlerInvocation	✓	✓		✓
StashingHandlerInvocationWithAsyncCompletion	✓	✓			✓
StashingAsyncHandlerInvocation	✓		✓	✓
StashingAsyncHandlerInvocationWithAsyncCompletion	✓		✓		✓
NonStashingHandlerInvocation		✓		✓
NonStashingHandlerInvocationWithAsyncCompletion		✓			✓
NonStashingAsyncHandlerInvocation			✓	✓
NonStashingAsyncHandlerInvocationWithAsyncCompletion			✓		✓

Key Concepts

• Stashing: When IStashingInvocation is implemented, incoming commands are stashed until all persistence handlers complete. This ensures consistency during persistence operations.
• Handler Type: Sync (Action<TEvent>) vs Async (Func<TEvent, Task>) determines how event handlers execute.
• Completion Type: Sync (Action) vs Async (Func<Task>) determines how the batch completion callback executes.

Naming Convention

The class names follow a consistent pattern:

[Stashing|NonStashing][Async]HandlerInvocation[WithAsyncCompletion]

• Stashing / NonStashing - Whether commands are stashed during persistence
• Async (before Handler) - Whether the event handler is async
• WithAsyncCompletion - Whether the completion callback is async (omitted for sync completion)

[Aaronontheweb]

We have a larger number of overloads here due to the combination of things we need to support both for backwards compatibility and ease of API use.... alllllllllllllthough..... this gives me an idea....

[Aaronontheweb]

Should we also exit of the events collection is zero-length?

[Aaronontheweb]

Also, don't we need to invoke the task handler here just like we did in the above overload?

[Aaronontheweb]

What about zero-length?

[Aaronontheweb]

Check to see what type of handler(s) we need to run

[Aaronontheweb]

event-specific handler always goes first

[Aaronontheweb]

completion handler always goes last

[Aaronontheweb]

Superseded via #7954