Saga Timeouts

Component: NServiceBus
NuGet Package NServiceBus (6.x)

Assumptions can not be made in a message-driven environment regarding the order of received messages and exactly when they will arrive. While the connection-less nature of messaging prevents a system from consuming resources while waiting, there is usually an upper limit to a waiting period that the business dictates.

The upper wait time is modeled in NServiceBus as a Timeout:

public class MySaga :
    Saga<MySagaData>,
    IAmStartedByMessages<Message1>,
    IHandleMessages<Message2>,
    IHandleTimeouts<MyCustomTimeout>
{
    protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
    {
        mapper.ConfigureMapping<Message2>(message => message.SomeId)
            .ToSaga(sagaData => sagaData.SomeId);
    }

    public Task Handle(Message1 message, IMessageHandlerContext context)
    {
        return RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromHours(1));
    }

    public Task Handle(Message2 message, IMessageHandlerContext context)
    {
        Data.Message2Arrived = true;
        var almostDoneMessage = new AlmostDoneMessage
        {
            SomeId = Data.SomeId
        };
        return RequestTimeout(context, TimeSpan.FromHours(1), almostDoneMessage);
    }

    public Task Timeout(MyCustomTimeout state, IMessageHandlerContext context)
    {
        if (Data.Message2Arrived)
        {
            return Task.CompletedTask;
        }
        return RequestTimeout(context, TimeSpan.FromHours(1), new TiredOfWaitingForMessage2());
    }
}
The Timeouts feature is enabled by default. To turn it off it's necessary to disable the TimeoutManager feature.

After calling RequestTimeout<T>, a timeout message will be persisted and scheduled to run after a specified delay or at specified time.

If a saga does not request a timeout then its corresponding timeout method will never be invoked.

Don't assume that other messages haven't arrived in the meantime. If required, a Saga can store boolean flags in the SagaData and then check these flags to confirm that a incoming timeout message should be processed based on the current sate.
In NServiceBus Versions 6 and above, and all integrations that target those versions, all extension points that return Task cannot return a null Task. These APIs must return an instance of a Task, i.e. a pending Task or a CompletedTask, or be marked async. For extension points that return a Task<T>, return the value directly (for async methods) or wrap the value in a Task.FromResult(value).

Revoking timeouts

A timeout that has been scheduled cannot be revoked. This means that when the timeout timestamp has elapsed then this timeout message will be queued and then processed.

A timeout is a regular message and once requested, a timeout message can already be in transit or queued. Once that has happened there is no way to revoke (delete) a timeout. It is common to perform a state check in a timeout handler to see if the timeout is still applicable for processing.

Sending a timeout with the same data multiple times will result in that timeout being processed multiple times by the saga.

Completed Sagas

It is possible for a timeout to be queued after its saga has completed. Because a timeout is tied to a specific saga instance it will be ignored once the saga instance is completed.

If a saga is created with a previously used saga identifier, the timeout mechanism will not treat it as the previous saga. As a result any residual timeout messages for the previous, now completed, saga will not be processed by this new saga instance that shares the same identifier. The existing timeout message will be ignored.

Timeout state

The state parameter provides a way to pass state to the Sagas timeout handle method. This is useful when many timeouts of the same "type" that will be active at the same time. One example of this would be to pass in some ID that uniquely identifies the timeout eg: .RequestTimeout(new OrderNoLongerEligibleForBonus{OrderId = "xyz"}). With this state passed to the timeout handler it can now decrement the bonus correctly by looking up the order value from saga state using the provided id.

Using the incoming message as timeout state

As a shortcut an incoming saga message can be re-used as timeout state by passing it to the RequestTimeout method and making the saga implement IHandleTimeouts<TIncommingMessageType>.

Persistence

Some form of Persistence is required to store the timestamp and the state of a timeout.

A durable persistence (i.e. NOT InMemory or Learning Persistence) should be chosen before moving to production.

In order to learn how delayed delivery works in more detail, refer to the Delayed Delivery - How it works section.

Samples

Related Articles

  • Sagas
    NServiceBus uses event-driven architecture to include fault-tolerance and scalability in long-term business processes.

Last modified