Table of Contents

Class ThrottlingSentinelOptions

Namespace
Cuemon.AspNetCore.Http.Throttling
Assembly
Cuemon.AspNetCore.dll

Configuration options for ThrottlingSentinelMiddleware.

public class ThrottlingSentinelOptions : IValidatableParameterObject, IParameterObject
Inheritance
ThrottlingSentinelOptions
Implements

Examples

The following example shows how to create default and custom ThrottlingSentinelOptions to configure rate-limiting behavior. It demonstrates setting the quota, context resolver, header names, and retry-after scope, then validates the configuration and prints the selected values.

using System;
using Cuemon.AspNetCore.Http.Headers;
using Cuemon.AspNetCore.Http.Throttling;
using Microsoft.AspNetCore.Http;

namespace MyApp.Http.Throttling
{
    public class ThrottlingSentinelOptionsExample
    {
        public ThrottlingSentinelOptions CreateDefault()
        {
            // Default: RateLimit-Limit header, 429 response with Retry-After
            var options = new ThrottlingSentinelOptions();
            return options;
        }

        public ThrottlingSentinelOptions CreateCustom()
        {
            var options = new ThrottlingSentinelOptions
            {
                // Allow 60 requests per 1 minute window per client
                Quota = new ThrottleQuota(60, TimeSpan.FromMinutes(1)),
                // Resolve context by client IP address
                ContextResolver = ctx =>
                    ctx.Connection.RemoteIpAddress?.ToString() ?? "unknown",
                // Custom header names
                RateLimitHeaderName = "X-Rate-Limit-Limit",
                RateLimitRemainingHeaderName = "X-Rate-Limit-Remaining",
                RateLimitResetHeaderName = "X-Rate-Limit-Reset",
                // Use delta-seconds for Retry-After
                RateLimitResetScope = RetryConditionScope.DeltaSeconds,
                UseRetryAfterHeader = true,
                RetryAfterScope = RetryConditionScope.DeltaSeconds,
                // Custom response message
                TooManyRequestsMessage = "Rate limit exceeded. Please slow down."
            };

            // Validate the configuration
            options.ValidateOptions();

            Console.WriteLine($"Quota: {options.Quota.RateLimit} req / {options.Quota.Window.TotalMinutes} min");
            Console.WriteLine($"RateLimitHeader: {options.RateLimitHeaderName}");
            Console.WriteLine($"RetryAfterScope: {options.RetryAfterScope}");

            return options;
        }
    }
}

Constructors

ThrottlingSentinelOptions()

Initializes a new instance of the ThrottlingSentinelOptions class.

public ThrottlingSentinelOptions()

Remarks

The following table shows the initial property values for an instance of ThrottlingSentinelOptions.

PropertyInitial Value
RateLimitHeaderNameX-RateLimit-Limit
RateLimitRemainingHeaderNameX-RateLimit-Remaining
RateLimitResetHeaderNameX-RateLimit-Reset
RateLimitResetScopeDeltaSeconds
UseRetryAfterHeadertrue
RetryAfterScopeDeltaSeconds
TooManyRequestsMessageThrottling rate limit quota violation. Quota limit exceeded.
ContextResolvernull
Quotanull
ResponseHandlerA HttpResponseMessage initialized to a HTTP status code 429 with zero of one Retry-After header and a body of TooManyRequestsMessage.

Properties

ContextResolver

Gets or sets the function delegate that will resolve a unique context of the throttling middleware (eg. IP-address, Authorization header, etc.).

public Func<HttpContext, string> ContextResolver { get; set; }

Property Value

Func<HttpContext, string>

The function delegate that will resolve a unique context of the throttling middleware.

Quota

Gets or sets the allowed quota for a given context.

public ThrottleQuota Quota { get; set; }

Property Value

ThrottleQuota

The allowed quota for a given context.

RateLimitHeaderName

Gets or sets the name of the rate limit HTTP header.

public string RateLimitHeaderName { get; set; }

Property Value

string

The name of the rate limit HTTP header.

RateLimitRemainingHeaderName

Gets or sets the name of the rate limit remaining HTTP header.

public string RateLimitRemainingHeaderName { get; set; }

Property Value

string

The name of the rate limit remaining HTTP header.

RateLimitResetHeaderName

Gets or sets the name of the rate limit reset HTTP header.

public string RateLimitResetHeaderName { get; set; }

Property Value

string

The name of the rate limit reset HTTP header.

RateLimitResetScope

Gets or sets the preferred rate limit reset HTTP header value that conforms with RFC 7231.

public RetryConditionScope RateLimitResetScope { get; set; }

Property Value

RetryConditionScope

The preferred rate limit reset HTTP header value that conforms with RFC 7231.

ResponseHandler

Gets or sets the function delegate that configures the response in the form of a HttpResponseMessage.

public Func<TimeSpan, DateTime, HttpResponseMessage> ResponseHandler { get; set; }

Property Value

Func<TimeSpan, DateTime, HttpResponseMessage>

The function delegate that configures the response in the form of a HttpResponseMessage.

RetryAfterScope

Gets or sets the preferred Retry-After HTTP header value that conforms with RFC 7231.

public RetryConditionScope RetryAfterScope { get; set; }

Property Value

RetryConditionScope

The preferred Retry-After HTTP header value that conforms with RFC 7231.

TooManyRequestsMessage

Gets or sets the message of a throttled request that has exceeded the rate limit.

public string TooManyRequestsMessage { get; set; }

Property Value

string

The message of a throttled request that has exceeded the rate limit.

UseRetryAfterHeader

Gets or sets a value indicating whether to include a Retry-After HTTP header specifying how long to wait before making a new request.

public bool UseRetryAfterHeader { get; set; }

Property Value

bool

true to include a Retry-After HTTP header specifying how long to wait before making a new request; otherwise, false.

Methods

ValidateOptions()

Determines whether the public read-write properties of this instance are in a valid state.

public void ValidateOptions()

Remarks

This method is expected to throw exceptions when one or more conditions fails to be in a valid state.

Exceptions

InvalidOperationException

RateLimitHeaderName cannot be null, empty or consist only of white-space characters - or - RateLimitRemainingHeaderName cannot be null, empty or consist only of white-space characters - or - RateLimitResetHeaderName cannot be null, empty or consist only of white-space characters - or - ResponseHandler cannot be null - or - Quota cannot be null when ContextResolver has been specified.

Edit this page