Table of Contents

Interface IBackoffCalculator

Namespace
Excalibur.Dispatch.Resilience
Assembly
Excalibur.Dispatch.dll

Computes how long to wait before a retry attempt.

public interface IBackoffCalculator
Extension Methods

Remarks

This interface states its contract because two implementations once disagreed about it. Some calculators threw for a non-positive attempt while another returned Zero; one refused a zero base delay that the others accepted. Both were defensible against a specification that said nothing, and a consumer swapping one for the other -- which is the advertised purpose of this seam -- got a different answer to the same call. The contract below is what makes them substitutable. An implementation that does not satisfy it is not a valid implementation of this interface, however reasonable it looks on its own.

Methods

CalculateDelay(int)

Calculates the delay to wait before the attempt numbered attempt.

TimeSpan CalculateDelay(int attempt)

Parameters

attempt int

The 1-based attempt number. The first retry is attempt 1.

Returns

TimeSpan

A non-negative delay, never greater than the maximum this calculator was configured with.

Remarks

Requires: attempt is 1 or greater. An implementation MUST throw ArgumentOutOfRangeException for 0 or a negative value, and MUST NOT return a value. A zero delay and an invalid argument are different facts, and an implementation that returns Zero instead of throwing converts a caller's off-by-one into an immediate retry with no backoff -- the exact behaviour backoff exists to prevent, delivered silently.

Guarantees: the returned delay is greater than or equal to Zero and less than or equal to the configured maximum. Overflow at a high attempt number MUST clamp to that maximum; it MUST NOT wrap, and MUST NOT return a negative delay, which callers pass straight to Delay(TimeSpan, CancellationToken) and which throws there instead -- on the failure path, which is the worst place to surface it.

Jitter has a FLOOR and a CEILING, and the nominal delay is not part of either. When an implementation randomises, then over repeated calls at a fixed attempt the delay MUST take a value below half the configured maximum with positive probability, and MUST be independent of every other caller's delay. The DISTRIBUTION between those bounds is deliberately implementation-defined.

The floor is the clause that carries the meaning, and the earlier contract omitted it. This paragraph used to require the delay to lie within [0, nominal] -- the nominal being what the strategy prescribes for the attempt. That was wrong twice over. It is UNOBSERVABLE: a caller holds this interface and has no operation that yields the nominal, so it could not check the one thing it was told to rely on. And a ceiling alone is satisfied completely by returning the nominal unchanged, which is to say by applying no jitter at all -- so the old clause permitted an implementation that decorrelates nothing while appearing conformant. Sampling down toward zero is the entire purpose: two callers that failed together must not retry together.

A symmetric band around the nominal is therefore NOT a valid implementation of this interface, which is deliberate. A band adds noise without decorrelating -- its mass sits near the nominal, so clients stay clustered -- and when the nominal ladder grows past the configured maximum, a band that is capped AFTER randomisation collapses to exactly the maximum with probability one, taking the jitter to zero precisely during the sustained outage that jitter exists for. An implementation MUST cap FIRST and randomise below the capped value.

Statelessness. The delay MUST be a function of attempt and the configuration alone, not of previously returned values. A calculator whose output depends on its own history cannot be shared across messages -- one message's first retry would be computed from another's last delay -- and cannot survive the process restart that a durable retry path assumes. Implementations are consequently safe to register as singletons and to call concurrently.

Exceptions

ArgumentOutOfRangeException

attempt is less than 1.