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. }}import io.cratis.chronicle.events.EventTypeimport io.cratis.chronicle.observation.Reactorimport io.cratis.chronicle.observation.Replay
@EventTypedata class ReplayAwareOrderPlaced(val orderId: String)
@Reactorclass ReplayAwareOrderReactor { fun sendConfirmation(event: ReplayAwareOrderPlaced) { // Runs as the event happens. }
@Replay fun rebuildProjectionCache(event: ReplayAwareOrderPlaced) { // Runs instead of sendConfirmation while the observer is replaying. }}import io.cratis.chronicle.events.EventType;import io.cratis.chronicle.observation.Reactor;import io.cratis.chronicle.observation.Replay;
@EventTyperecord ReplayAwareOrderPlaced(String orderId) {}
@Reactorclass ReplayAwareOrderReactor { void sendConfirmation(ReplayAwareOrderPlaced event) { // Runs as the event happens. }
@Replay void rebuildProjectionCache(ReplayAwareOrderPlaced event) { // Runs instead of sendConfirmation while the observer is replaying. }}defmodule ReplayAwareOrderPlaced do use Chronicle.Events.EventType, id: "replay-aware-order-placed"
defstruct [:order_id]end
defmodule ReplayAwareOrderReactor do use Chronicle.Reactors.Reactor
@handles ReplayAwareOrderPlaced
# Runs as the event happens. @impl true def handle(%ReplayAwareOrderPlaced{}, _context), do: :ok
# Runs instead of handle/2 while the observer is replaying. @impl true def handle_replay(%ReplayAwareOrderPlaced{}, _context), do: :okendimport { eventType, reactor, replay } from '@cratis/chronicle';import { field } from '@cratis/fundamentals';
@eventType()class ReplayAwareOrderPlaced { @field(String) readonly orderId: string;
constructor(orderId: string = '') { this.orderId = orderId; }}
@reactor()class ReplayAwareOrderReactor { replayAwareOrderPlaced(event: ReplayAwareOrderPlaced): void { // Runs as the event happens. }
@replay() replayReplayAwareOrderPlaced(event: ReplayAwareOrderPlaced): void { // Runs instead of replayAwareOrderPlaced during replay. }}Handler selection is per event type:
- During replay, a
Replayhandler takes precedence over the regular handler for that type. - Without a
Replayhandler, the regular handler runs unless it is markedOnceOnly. Adding a replay handler for one type does not change the others. - An event type with only a
Replayhandler is still subscribed to, but that handler does not run for ordinary delivery.
Adding event types
Section titled “Adding event types”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.
Replay one event source from Workbench
Section titled “Replay one event source from Workbench”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.