Skip to content

Cratis Chronicle reactors: register runtime event types

Cratis Chronicle’s .NET runtime reactor API handles events as JSON when a bridge or plugin host knows their identifiers but has no .NET event classes. Register a stable reactor ID, the event types and generations to observe, and an asynchronous callback in the application that will process them.

A generation identifies a version of an event type’s schema. Include it in the subscription so Chronicle knows which event representation you are requesting:

using System.Text.Json.Nodes;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
public interface IOrdersBridgeForwarder
{
Task Forward(EventType eventType, JsonObject content, IReadOnlyDictionary<int, string> generations, CancellationToken cancellationToken);
}
public class OrdersBridgeRegistration
{
public async Task Register(IEventStore eventStore, IOrdersBridgeForwarder forwarder)
{
await eventStore.Reactors.Register(
"orders-bridge",
reactor => reactor
.WithEventType(new EventType("OrderPlaced", 1))
.WithEventType(new EventType("OrderPlaced", 2))
.OnEventSequence(EventSequenceId.Log)
.NotReplayable(),
async (@event, cancellationToken) =>
{
// Content is JsonObject; generational content contains raw JSON.
await forwarder.Forward(@event.Context.EventType, @event.Content, @event.GenerationalContent, cancellationToken);
});
}
public void Unregister(IEventStore eventStore)
{
eventStore.Reactors.Unregister("orders-bridge");
}
}

View C# snippet source on GitHub

The callback receives ReactorEvent: its Context describes the delivery, Content holds JSON, and GenerationalContent maps generation numbers to JSON strings. This API does not deserialize a .NET event or select another generation’s content for you.

The map can contain only some generations, so check for the entry you need rather than assuming every subscribed generation is present. During storage reads and catch-up, the context’s generation describes what the kernel delivers. If content has been migrated, that can differ from the originally appended generation. Do not use it as an immutable original-generation identifier across replay.

Runtime registration observes the default event log. Use OnEventSequence to select another sequence, and NotReplayable to disable replay when the effect must not run through history again. Disabling replay does not prevent initial catch-up or retries. Runtime registration has no start-at-tail option, so a new observer still catches up on existing history.

Chronicle awaits the callback before acknowledging progress. If it throws or its task fails, the partition fails without advancing past that event. Make downstream effects idempotent: repeating a request must not repeat its business outcome. An external call can succeed even if the handler later fails to report success.

Keep the reactor ID unchanged across restarts so Chronicle can retain its observation position. IDs must be unique among the reactors registered with that event store, including discovered reactor classes. Duplicate IDs are rejected because one observer ID cannot independently track two reactors.

The returned handler exposes state and failed partitions through the same APIs as a typed reactor. Use GetHandlerById to retrieve it later. Delegate handlers report typeof(object) as their ReactorType; that value does not identify the subscribed event types.

A registered reactor reconnects with its original subscription and callback after a connection loss. Unregister(id) instead disconnects its local observation stream and removes the callback from this client. It does not erase the kernel’s stored observer state, and unregistering an unknown ID does nothing.

When .NET event types are available, prefer a typed reactor with discovered methods or fluent registration with typed delegates. Those APIs supply deserialized events instead of leaving JSON handling to the callback.