Skip to content

Reactor and reducer replay lifecycle notifications

Replay notifications tell a reactor or reducer when Cratis Chronicle begins and ends a replay. Use them to coordinate replay-specific work, such as changing how a reactor writes to an external index. They are lifecycle calls, not a mechanism for preventing duplicate side effects.

In C#, implement ICanBeNotifiedWhenReplay on the reactor or reducer class to receive BeginReplay() and EndReplay(). The interface lives in the Cratis.Chronicle.Observation namespace. Store any state needed across those calls outside the reactor or reducer instance.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Observation;
using Cratis.Chronicle.Reactors;
[EventType]
public record ReplayNotifiedOrderPlaced(string OrderId);
public interface IReplayNotificationGate
{
void Pause();
void Resume();
}
public class ReplayNotifiedOrderReactor(IReplayNotificationGate gate) : IReactor, ICanBeNotifiedWhenReplay
{
public Task BeginReplay()
{
gate.Pause();
return Task.CompletedTask;
}
public Task EndReplay()
{
gate.Resume();
return Task.CompletedTask;
}
public Task OrderPlaced(ReplayNotifiedOrderPlaced @event)
{
// Handles the event both live and during the replay.
return Task.CompletedTask;
}
}

View C# snippet source on GitHub

Reducers use the same interface:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Observation;
using Cratis.Chronicle.Reducers;
[EventType]
public record ReplayNotifiedItemAdded(string OrderId);
public record ReplayNotifiedOrderTotals(int Items);
public class ReplayNotifiedOrderTotalsReducer : IReducerFor<ReplayNotifiedOrderTotals>, ICanBeNotifiedWhenReplay
{
public Task BeginReplay() => Task.CompletedTask;
public Task EndReplay() => Task.CompletedTask;
public ReplayNotifiedOrderTotals ItemAdded(ReplayNotifiedItemAdded @event, ReplayNotifiedOrderTotals? current) =>
new((current?.Items ?? 0) + 1);
}

View C# snippet source on GitHub

A notification does not go through the event handlers, so a [Replay] handler does not receive it. Replay events are delivered between the lifecycle calls. To change which handler processes those events, use Replay; to skip a handler during replay, use OnceOnly.

The .NET client creates a reactor or reducer in a new dependency injection scope for each notification and disposes it afterwards. BeginReplay() and EndReplay() run on different instances, separate from the instances handling events. An instance field set in BeginReplay() therefore cannot tell an event handler that replay is active.

For state shared within one application process, use a singleton service such as the one in the reactor example. A scoped or transient service is created anew for each notification. A singleton does not share state across application processes or preserve it after a restart; use storage outside the process if your coordination needs either.

Replaying one partition, for example with the observers replay-partition command of the Cratis CLI, has its own interface, ICanBeNotifiedWhenPartitionReplayed. It receives the partition being replayed:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Observation;
using Cratis.Chronicle.Reactors;
[EventType]
public record PartitionNotifiedOrderPlaced(string OrderId);
public class PartitionNotifiedOrderReactor : IReactor, ICanBeNotifiedWhenPartitionReplayed
{
public Task BeginReplayPartition(Partition partition)
{
// The partition is the event source id being replayed.
return Task.CompletedTask;
}
public Task EndReplayPartition(Partition partition)
{
return Task.CompletedTask;
}
public Task OrderPlaced(PartitionNotifiedOrderPlaced @event)
{
return Task.CompletedTask;
}
}

View C# snippet source on GitHub

The two interfaces are independent. Implement the partition interface for single-partition replay, the observer interface for full replay, or both if your coordination must handle either operation.

In the .NET client, reactors defined fluently with the reactor builder or registered at runtime with a handler delegate do not receive these notifications: they have no reactor class implementing the interface.

For Elixir, use the on_replay_begin/0, on_replay_end/0, on_partition_replay_begin/1 and on_partition_replay_end/1 callbacks. TypeScript exposes ICanBeNotifiedWhenReplay and ICanBeNotifiedWhenPartitionReplayed. See Getting started with reactors for the client entry points; the instance-lifetime guidance on this page is specific to .NET.