Saga Timeouts

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:

Copy code|Copy usings|Edit

public class MySaga :
    Saga<MySagaData>,
    IAmStartedByMessages<Message1>,
    IHandleMessages<Message2>,
    IHandleTimeouts<MyCustomTimeout>
{
    protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
    {
        mapper.MapSaga(sagaData => sagaData.SomeId)
            .ToMessage<Message1>(message => message.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 ReplyToOriginator(context, almostDoneMessage);
    }

    public Task Timeout(MyCustomTimeout state, IMessageHandlerContext context)
    {
        if (!Data.Message2Arrived)
        {
            return ReplyToOriginator(context, new TiredOfWaitingForMessage2());
        }
        return Task.CompletedTask;
    }
}

RequestTimeout<T> sends a timeout message which is delivered after the specified delay or at the 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 an incoming timeout message should be processed based on the current state.

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).

Timezones and Daylight Saving Time (DST)

A timeout may be requested specifying either a DateTime or TimeSpan. When specifying a DateTime, the Kind property must be set. If the timeout specifies a time of day, the calculation must take into account any change to or from DST. Timezone and DST conversion may be done using TimeZoneInfo.ConvertTime.

Timezone and DST information may change in the future, for timeouts that are already set. A saga containing business logic which is dependent on such changes must react to those changes appropriately.

Requesting multiple timeouts

Multiple timeouts can be requested when processing a message. The individual timeouts can be different types and different timeout durations.

Copy code|Copy usings|Edit

public async Task Handle(Message1 message, IMessageHandlerContext context)
{
    await RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromHours(1));
    await RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromDays(1));
    await RequestTimeout<MyOtherCustomTimeout>(context, TimeSpan.FromSeconds(10));
    await RequestTimeout<MyOtherCustomTimeout>(context, TimeSpan.FromMinutes(30));
}

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

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.

Completed Sagas

It is possible for a timeout to be queued after its saga has been 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" 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 the saga state using the provided id.

Using the incoming message as a timeout state

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

Persistence

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

A durable persistence (i.e. NOT Non-Durable 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.