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; }}defmodule MyApp.Events.ReplayNotifiedOrderPlaced do use Chronicle.Events.EventType, id: "replay-notified-order-placed"
defstruct [:order_id]end
# The notifications run outside the reactor's event handling, so anything they share lives in# a process of its own that you start under your supervision tree.defmodule MyApp.ReplayNotificationGate do use Agent
def start_link(_opts), do: Agent.start_link(fn -> :open end, name: __MODULE__)
def pause, do: Agent.update(__MODULE__, fn _ -> :paused end) def resume, do: Agent.update(__MODULE__, fn _ -> :open end) def open?, do: Agent.get(__MODULE__, &(&1 == :open))end
defmodule MyApp.Reactors.ReplayNotifiedOrderReactor do use Chronicle.Reactors.Reactor
alias MyApp.Events.ReplayNotifiedOrderPlaced alias MyApp.ReplayNotificationGate
@handles ReplayNotifiedOrderPlaced
# Handles the event both live and during the replay. @impl true def handle(%ReplayNotifiedOrderPlaced{}, _context), do: :ok
@impl true def on_replay_begin, do: ReplayNotificationGate.pause()
@impl true def on_replay_end, do: ReplayNotificationGate.resume()endReducers 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);}defmodule MyApp.Events.ReplayNotifiedItemAdded do use Chronicle.Events.EventType, id: "replay-notified-item-added"
defstruct [:order_id]end
defmodule MyApp.ReadModels.ReplayNotifiedOrderTotals do defstruct items: 0end
defmodule MyApp.Reducers.ReplayNotifiedOrderTotalsReducer do use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.ReplayNotifiedOrderTotals
alias MyApp.Events.ReplayNotifiedItemAdded alias MyApp.ReadModels.ReplayNotifiedOrderTotals
@handles ReplayNotifiedItemAdded
@impl true def reduce(%ReplayNotifiedItemAdded{}, current, _context) do %ReplayNotifiedOrderTotals{items: (if current, do: current.items, else: 0) + 1} end
@impl true def on_replay_begin, do: :ok
@impl true def on_replay_end, do: :okendNotifications are separate from events
Section titled “Notifications are separate from events”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.
Each notification gets a new instance
Section titled “Each notification gets a new instance”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 a single partition
Section titled “Replaying a single partition”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; }}defmodule MyApp.Events.PartitionNotifiedOrderPlaced do use Chronicle.Events.EventType, id: "partition-notified-order-placed"
defstruct [:order_id]end
defmodule MyApp.Reactors.PartitionNotifiedOrderReactor do use Chronicle.Reactors.Reactor
alias MyApp.Events.PartitionNotifiedOrderPlaced
@handles PartitionNotifiedOrderPlaced
@impl true def handle(%PartitionNotifiedOrderPlaced{}, _context), do: :ok
# The partition is the event source id being replayed. @impl true def on_partition_replay_begin(_partition), do: :ok
@impl true def on_partition_replay_end(_partition), do: :okendThe 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.
What is not notified
Section titled “What is not notified”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.