Skip to main content

Ordering Validation

OrderingValidationMiddleware enforces strictly-increasing per-key ordering for messages that arrived through a receive path where ordering is enforced. It is fail-closed: such a message carrying an out-of-order sequence, or none at all, throws OutOfOrderMessageException rather than passing silently.

Before You Start​

  • .NET 10.0
  • Install the required package:
    dotnet add package Excalibur.Dispatch
  • Familiarity with built-in middleware and your transport's receive-to-dispatch bridge

The stamp is yours to call​

The middleware only ever sees a context that has already been marked. Nothing in the framework calls the stamp for you — there is no first-party "receive boundary" type that holds both a TransportReceivedMessage and an IMessageContext, because the transports produce received messages and your bridge is what turns one into a dispatch. That bridge is the one place holding both, so it is the one place the stamp can live.

Call TransportOrderingMetadata.TryStampOrdering(received, context) from that bridge, before dispatching:

using Excalibur.Dispatch.Transport;

// Your Kafka/Azure Service Bus consumer loop, after receiving a message and before dispatching it.
await foreach (var received in receiver.ReceiveAsync(cancellationToken))
{
var context = messageContextFactory.Create();

// Reads the transport's native monotonic sequence (Kafka offset, Azure Service Bus
// SequenceNumber) out of TransportReceivedMessage.ProviderData and stamps it onto the
// context. Also marks the context as having entered an ordered receive path -- this is
// what scopes the middleware to these messages, wherever OrderingValidationMiddleware is
// registered.
TransportOrderingMetadata.TryStampOrdering(received, context);

var message = deserializer.Deserialize(received);
await dispatcher.DispatchAsync(message, context, cancellationToken);
}

TryStampOrdering returns true when a native sequence was found and stamped, false when the transport carries none (for example Google Pub/Sub, whose ordering key is a service-enforced string, not a sequence). Either way, the context is marked as having entered an ordered receive path — a transport that stops supplying its sequence must fail loudly, not silently stop being validated.

Register the middleware​

services.AddDispatch(typeof(Program).Assembly); // or services.AddDispatch(dispatch => { ... })
services.AddOrderingValidation();

This registers globally: there is no per-pipeline middleware selector, so the middleware sees every dispatch in the process. What scopes it to the messages it is about is the receive-path marking above, not where you register it. A message that never entered a marked receive path — an outbound send, an in-process command — passes through unchanged.

Both AddDispatch overloads compose the same pipeline, and both include middleware registered this way, so the builder-lambda form works identically:

services.AddDispatch(dispatch => dispatch.AddHandlersFromAssembly(typeof(Program).Assembly));
services.AddOrderingValidation();

The order of the two calls does not matter: the pipeline is composed when it is first resolved, after your registrations are complete.

Which transports carry a native sequence​

TransportNative sequenceTryStampOrdering result
KafkaPartition offsetStamped automatically
Azure Service BusSequenceNumberStamped automatically
Google Pub/SubNone (service-enforced ordering key, not a sequence)Returns false; ordering marked-but-unstamped
RabbitMQ, AWS SQS, and other transports without a native monotonic sequenceNoneReturns false; ordering marked-but-unstamped

For a transport with no native sequence, either don't call TryStampOrdering at all (the message never enters an ordered receive path and the middleware passes it through), or stamp one yourself with OrderingContextExtensions.SetOrderingSequence(context, sequence, orderingKey) after marking the context with OrderingContextExtensions.MarkOrderingEnforced(context) — for example when your own producer embeds an application-level sequence number in the message body.

Failure mode​

OutOfOrderMessageException

Thrown when a message that entered a marked receive path arrives with no sequence, or with a sequence that is not strictly greater than the last one seen for its ordering key. A per-key high-water mark is tracked by a single stateful registration; registering AddOrderingValidation() more than once is idempotent.

See Also​

  • Built-in Middleware -- The full middleware catalog and recommended pipeline order
  • Transports -- Transport-specific receive paths and native capabilities