Message replays

Fluxzero allows you to replay past messages by tracking from an earlier index in the message log. This is useful for:

• Rebuilding projections or read models
• Repairing missed or failed messages
• Retrospectively introducing new functionality

Since message logs — including commands, events, errors, etc. — are durably stored (with events retained indefinitely by default), replays are usually available.

For a new capability, start with building a feature from past events. The position controls below are useful when you need to choose or reset a replay range.

Replaying from the Past

The most common way to initiate a replay is to define a new consumer using the @Consumer annotation with a minIndex.

Java

@Consumer(name = "auditReplay", minIndex = 111677748019200000L)
public class AuditReplayHandler {

    @HandleEvent
    void on(CreateUser event) {
        // ... rebuild projections, audit, etc.
    }
}

Kotlin

@Consumer(name = "auditReplay", minIndex = 111677748019200000L)
class AuditReplayHandler {

    @HandleEvent
    fun on(event: CreateUser) {
        // ... rebuild projections, audit, etc.
    }
}

Note

minIndex is the inclusive starting position in the log. You can derive it from a timestamp using IndexUtils.

Java

long index = IndexUtils.indexFromTimestamp(
    Instant.parse("2024-01-01T00:00:00Z"));
// -> 111677748019200000L

Kotlin

val index = IndexUtils.indexFromTimestamp(
    Instant.parse("2024-01-01T00:00:00Z"))
// -> 111677748019200000L

This approach is perfect for:

• Starting fresh consumers for replays
• Bootstrapping projections without interfering with live handlers
• Keeping logic encapsulated and isolated

Resetting Existing Consumers

If you want to reset an existing consumer to an earlier point in the log:

Java

long replayIndex = 111677748019200000L;

Fluxzero.client()
    .getTrackingClient(MessageType.EVENT)
    .resetPosition("myConsumer", replayIndex, Guarantee.STORED);

Kotlin

val replayIndex = 111677748019200000L

Fluxzero.client()
    .getTrackingClient(MessageType.EVENT)
    .resetPosition("myConsumer", replayIndex, Guarantee.STORED)

Caution

Be careful when replaying on existing handlers to avoid duplicating side effects (emails, HTTP calls, etc.). Prefer a dedicated replay consumer when side effects are not replay-safe.

Parallel replays with exclusive = false

To keep processing live events while correcting earlier results, use one handler in two consumers. That guide shows the handler, the bounded correction consumer and how to finish the run. exclusive = false allows the same handler to participate in both consumers.

Handling failures and DLQ flows

For replaying failures from the error log (dynamic DLQ), use the dedicated Dynamic dead-lettering guide.