Interface IThrottlingAlgorithm

Namespace

RateLimitHeaders.Throttling

Assembly

RateLimitHeaders.dll

Defines a throttling algorithm that determines whether and how long to delay requests based on rate limit information.

public interface IThrottlingAlgorithm

Examples

Basic custom throttling algorithm:

public class FixedDelayThrottlingAlgorithm : IThrottlingAlgorithm
{
    private readonly TimeSpan _fixedDelay;
    private readonly double _threshold;

    public FixedDelayThrottlingAlgorithm(TimeSpan delay, double threshold = 0.1)
    {
        _fixedDelay = delay;
        _threshold = threshold;
    }

    public ThrottlingResult Evaluate(RateLimitInfo rateLimitInfo)
    {
        if (!rateLimitInfo.IsValid || rateLimitInfo.Quota <= 0)
            return ThrottlingResult.NoThrottle;

        if (rateLimitInfo.GetRemainingPercentage() >= _threshold)
            return ThrottlingResult.NoThrottle;

        return ThrottlingResult.Throttle(_fixedDelay, "Below quota threshold");
    }
}

Advanced algorithm using state tracker for cross-endpoint decisions:

public class GlobalThrottlingAlgorithm : IThrottlingAlgorithm
{
    public ThrottlingResult Evaluate(RateLimitInfo rateLimitInfo) =>
        Evaluate(rateLimitInfo, null);

    public ThrottlingResult Evaluate(RateLimitInfo rateLimitInfo, IRateLimitStateProvider? stateProvider)
    {
        if (stateProvider == null)
            return DefaultEvaluate(rateLimitInfo);

        // Access other endpoint states for global throttling decisions
        var allStates = stateProvider.GetAllStates();
        var lowestQuota = allStates.Min(s => s.GetRemainingPercentage());
        // ... implement global throttling logic
    }
}

Remarks

Implementations of this interface provide different strategies for proactive client-side throttling. The goal is to slow down requests before hitting 429 errors by analyzing rate limit header information.

Built-in implementations:

• PercentageThrottlingAlgorithm - Simple threshold-based throttling

Future implementations may include Google SRE-style adaptive throttling which tracks request/accept ratios over a sliding window.

Methods

Evaluate(RateLimitInfo)

Evaluates the current rate limit state and determines whether throttling is needed.

ThrottlingResult Evaluate(RateLimitInfo rateLimitInfo)

Parameters

rateLimitInfo RateLimitInfo

The parsed rate limit information from the most recent response.

Returns

ThrottlingResult

A ThrottlingResult indicating whether to throttle and for how long.

Evaluate(RateLimitInfo, IRateLimitStateProvider?)

Evaluates the current rate limit state and determines whether throttling is needed, with access to the full rate limit state across all tracked endpoints.

ThrottlingResult Evaluate(RateLimitInfo rateLimitInfo, IRateLimitStateProvider? stateProvider)

Parameters

rateLimitInfo RateLimitInfo

The parsed rate limit information from the most recent response.

stateProvider IRateLimitStateProvider

Optional provider for accessing rate limit state across all tracked endpoints. Useful for implementing global throttling strategies that consider the overall API health.

Returns

ThrottlingResult

A ThrottlingResult indicating whether to throttle and for how long.

Remarks

The default implementation ignores the state provider and delegates to Evaluate(RateLimitInfo). Override this method when implementing algorithms that need cross-endpoint visibility.