Skip to content

Reactor replay handlers for historical events

A Replay handler replaces the regular handler for the same event type while Cratis Chronicle replays that reactor’s history. Use it when historical events need different work, such as updating an external index without resending the original order confirmation.

In C#, mark the second handler with the Replay attribute. Replaying a separate projection does not itself replay the reactor; the replacement applies when this reactor’s observer is replaying.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;
[EventType]
public record ReplayAwareOrderPlaced(string OrderId);
public class ReplayAwareOrderReactor : IReactor
{
public void SendConfirmation(ReplayAwareOrderPlaced @event)
{
// Runs as the event happens.
}
[Replay]
public void RebuildProjectionCache(ReplayAwareOrderPlaced @event)
{
// Runs instead of SendConfirmation while the observer is replaying.
}
}

View C# snippet source on GitHub

Handler selection is per event type:

  • During replay, a Replay handler takes precedence over the regular handler for that type.
  • Without a Replay handler, the regular handler runs unless it is marked OnceOnly. Adding a replay handler for one type does not change the others.
  • An event type with only a Replay handler is still subscribed to, but that handler does not run for ordinary delivery.

When you add event types to an existing subscription, the kernel recommends replay if an added type has events before the observer’s next unread position. If the added types have no history, or their first events are at or after that position, they can be handled normally without replay. This rule applies to additions; it does not change the replay recommendation rules for removals or generation changes.

A replay recommendation does not mean a reactor will automatically replay after a definition change. See Observers for replay policy and the difference between replay and catch-up.

For work that should be skipped during replay, use OnceOnly. For coordination around the whole replay or a single partition, use Replay notifications.

Neither marker prevents ordinary recovery from invoking a handler again after a partition fails. A replay handler can also be retried if its work fails. Use Delivery identity to key duplicate protection for any external effect that must not repeat.

On the Workbench’s Observers page, select an application-owned observer, enter one Event-source id, then choose Replay event source. Confirm the observer, event-source id, event store and namespace before submitting. Review the reactor’s replay handlers and external calls first: this action reprocesses history.

The id is one opaque value. This action does not discover partitions, select multiple partitions or support arbitrary projection keys. The Replay action still replays the whole observer.

Replay changes observer state and requires authorization. An accepted request confirms that replay was requested, not that it has completed. If the request fails, the input remains available for correction and retry.