Dynamic dead-lettering

The error log is durable and replayable, which means you can treat it as a powerful, dynamic DLQ.

Here’s how:

1. Deploy a special consumer that tracks the error log.
2. Use @Trigger to access and inspect failed messages.
3. Filter and replay failures based on time, payload type, or originating app.

Example: retrying failed commands

Let’s assume a bug caused command processing to fail in September 2025. The following setup reprocesses those failed commands:

Java

@Consumer(name = "command-dlq",
        minIndex = 115126095052800000L,
        maxIndexExclusive = 115295964364800000L) // 2025-09-01 to 2025-10-01
class CommandReplayHandler {

    @HandleError
    void retry(ConsoleError error, @Trigger(messageType = MessageType.COMMAND) MyCommand failedCommand) {
        Fluxzero.sendCommand(failedCommand);
    }
}

Kotlin

@Consumer(
    name = "command-dlq",
    minIndex = 115126095052800000L,
    maxIndexExclusive = 115295964364800000L) // 2025-09-01 to 2025-10-01
)
class CommandReplayHandler {

    @HandleError
    fun retry(error: ConsoleError, @Trigger(messageType = MessageType.COMMAND) failedCommand: MyCommand) {
        Fluxzero.sendCommand(failedCommand)
    }
}

Tip

The original MyCommand payload is restored and retried transparently. You can combine this with logic that deduplicates, transforms, or selectively suppresses retries.

When to use the Error log

Use case	How the Error log helps
Fix a bug retroactively	Replay failed commands from the past
Validate new handler logic	Test it against real-world errors
Retry transient failures	Re-issue requests with retry logic
Clean up or suppress errors	Filter out known false-positives

The error log acts as a time-travel debugger — it gives you full control over how and when to address failures, now or in the future.

---

Routing with @RoutingKey

In Fluxzero, routing is used to assign messages to segments using consistent hashing. This ensures that messages about the same entity — for example, all events for a given OrderId — are always handled by the same consumer, in the correct order.

This is critical when you’re handling messages in parallel, but still want to ensure per-entity consistency.

Declaring the routing key

By default, the routing key is derived from the message ID. But you can override this by annotating a field, getter, or method in your payload class with @RoutingKey.

Java

public record ShipOrder(@RoutingKey OrderId orderId) {
}

@RoutingKey("customer/id")
public record OrderPlaced(Customer customer) {
}

Kotlin

data class ShipOrder(
    @RoutingKey val orderId: OrderId
)

@RoutingKey("customer/id")
data class OrderPlaced(
    val customer: Customer
)

This instructs Fluxzero to extract customer.id and use it as the routing key when publishing or consuming the message.

Handler-level routing keys

In advanced cases, you may want to override routing at the handler level, regardless of how the message was published.

Java

@HandleEvent
@RoutingKey("organisationId")
void handle(OrganisationUpdate event) {
    // Will route based on organisationId in metadata or payload
}

Kotlin

@HandleEvent
@RoutingKey("organisationId")
fun handle(event: OrganisationUpdate) {
    // Will route based on organisationId in metadata or payload
}

Caution

When overriding routing at the handler level, declare your consumer with ignoreSegment = true. Otherwise, certain messages may be silently skipped.

Java

@Consumer(ignoreSegment = true)
public class OrganisationHandler {
    ...
}

Kotlin

@Consumer(ignoreSegment = true)
class OrganisationHandler {
    ...
}

Metadata-based routing

You can also extract routing keys from message metadata. If the metadata key is missing, Fluxzero falls back to the payload.

Java

@RoutingKey("userId")
public class AuditLogEntry {
    ...
}

Kotlin

@RoutingKey("userId")
class AuditLogEntry {
    ...
}

Summary

Placement	Meaning
Field/getter	Use the property’s value as routing key
Class-level	Use the named property in metadata or payload
Handler method	Overrides routing key used during handling (requires ignoreSegment)