Class RateLimitAwareOptions

Namespace

RateLimitHeaders.Http

Assembly

RateLimitHeaders.dll

Configuration options for the rate limit aware HTTP handler.

public sealed class RateLimitAwareOptions

Inheritance

object

RateLimitAwareOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

Basic configuration with callbacks:

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(options =>
    {
        options.EnableProactiveThrottling = true;
        options.QuotaLowThreshold = 0.2;  // 20%

        options.OnRateLimitInfo = args =>
        {
            logger.LogDebug("Rate limit: {Remaining}/{Quota}",
                args.RateLimitInfo.Remaining,
                args.RateLimitInfo.Quota);
            return ValueTask.CompletedTask;
        };

        options.OnQuotaLow = args =>
        {
            logger.LogWarning("Low quota: {Percentage:P0} remaining",
                args.RemainingPercentage);
            return ValueTask.CompletedTask;
        };
    });

Configuration from appsettings.json:

// In appsettings.json:
// {
//   "RateLimitHandler": {
//     "EnableProactiveThrottling": true,
//     "QuotaLowThreshold": 0.15
//   }
// }

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(configuration.GetSection("RateLimitHandler"));

Properties

EnableProactiveThrottling

Gets or sets whether proactive throttling is enabled. When enabled, requests may be delayed based on rate limit information. Default is true.

public bool EnableProactiveThrottling { get; set; }

Property Value

bool

Remarks

When throttling is triggered, the request is delayed using Delay(TimeSpan, CancellationToken). This holds the request until the delay completes or cancellation is requested.

For scenarios where blocking is unacceptable, consider:

• Setting this to false and using the OnThrottling callback to implement custom rejection logic
• Using a custom ThrottlingAlgorithm that returns NoThrottle
• Passing a CancellationToken with a timeout to bound the maximum delay

OnQuotaLow

Gets or sets a callback invoked when the remaining quota falls below the QuotaLowThreshold.

public Func<QuotaLowEventArgs, ValueTask>? OnQuotaLow { get; set; }

Property Value

Func<QuotaLowEventArgs, ValueTask>

OnRateLimitInfo

Gets or sets a callback invoked whenever rate limit headers are parsed from a response. This callback is invoked regardless of the rate limit state.

public Func<RateLimitEventArgs, ValueTask>? OnRateLimitInfo { get; set; }

Property Value

Func<RateLimitEventArgs, ValueTask>

OnThrottling

Gets or sets a callback invoked when a request is being throttled. This is called before the delay is applied.

public Func<ThrottlingEventArgs, ValueTask>? OnThrottling { get; set; }

Property Value

Func<ThrottlingEventArgs, ValueTask>

Remarks

This callback can be used for logging, metrics, or to implement custom rejection logic (e.g., by throwing an exception if you prefer to fail fast rather than delay).

The callback is invoked synchronously before the throttling delay begins.

QuotaLowThreshold

Gets or sets the threshold below which the quota is considered low. This is used for the OnQuotaLow callback. Value must be between 0.0 and 1.0. Default is 0.1 (10%).

public double QuotaLowThreshold { get; set; }

Property Value

double

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 0.0 or greater than 1.0.

StateKeyExtractor

Gets or sets a function to extract the state tracking key from a request. When TrackStatePerEndpoint is true, this extracts the endpoint key. Default extracts the hostname.

public Func<HttpRequestMessage, string>? StateKeyExtractor { get; set; }

Property Value

Func<HttpRequestMessage, string>

Remarks

The default implementation uses the hostname. For example: https://api.example.com/v1/users becomes api.example.com. Set this to customize how endpoints are grouped for state tracking.

ThrottlingAlgorithm

Gets or sets the throttling algorithm to use. Default is PercentageThrottlingAlgorithm with default settings.

public IThrottlingAlgorithm ThrottlingAlgorithm { get; set; }

Property Value

IThrottlingAlgorithm

TrackStatePerEndpoint

Gets or sets whether to track rate limit state per endpoint. When enabled, state is tracked by host + path prefix combination. Default is true.

public bool TrackStatePerEndpoint { get; set; }

Property Value

bool