Expand documentation with regard to rate limiter queuing / timeouts

[bdcoder2]

Description

The current documentation does include a very brief statement with regard to rate limiters and queuing, i.e.:

With queuing enabled, when a request exceeds the rate limit, it's placed in a queue where the request waits until a permit becomes available or until a timeout occurs.

While testing a fixed window rate limiter with a .QueueLimit > 0, requests indeed "wait" (seem to hang) until a permit becomes available as stated, but what about the "timeout" being mentioned? I assumed the timeout refers to the HTTP request timeout, which is configured either at a server level or on the actual endpoint, for example, by specifing: .WithRequestTimeout(TimeSpan.FromSeconds(4));, (if using builder.Services.AddRequestTimeouts(); / app.UseRequestTimeouts(); )

However, while testing, requests (with a QueueLimit > 0) never seem to timeout, they just seem to "wait" until the rate limiter window resets even if .WithRequestTimeout(); is added to the endpoint. I would have expected an HttpContext.RequestAborted to be triggered if the request times out (before the rate limiter window resets?), but such timeouts never seem to occur - hence my request for additional details.

If an example of a "timeout" event could be added when queuing is enabled, that would be appreciated.

Thanks in advance.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit?view=aspnetcore-10.0#request-queuing

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/rate-limit.md

Document ID

bb96b20f-0991-d6de-4d98-192cd469460f

Platform Id

a32d8e13-92af-9a53-cfa1-45862b1df67c

Article author

@wadepickett

Metadata

• ID: bb96b20f-0991-d6de-4d98-192cd469460f
• PlatformId: a32d8e13-92af-9a53-cfa1-45862b1df67c
• Service: aspnet-core
• Sub-service: performance

Related Issues

[wadepickett]

Thanks @bdcoder2 for taking the time to poing this out. Greatly appreciate your feedback and suggestions.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-02-22
Issue: 36782
Model: GitHub Copilot

---

Issue Analysis: Expand documentation on rate limiter queuing and timeout behavior

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The current documentation for ASP.NET Core rate limiting states that when queuing is enabled, a request "waits until a permit becomes available or until a timeout occurs." However, the documentation does not explain what "timeout" means in this context, how it is triggered, or how to configure it. The issue reporter tested with a fixed window rate limiter (QueueLimit > 0) combined with .WithRequestTimeout() and found that queued requests never time out — they always wait until the rate limiter window resets and permits become available.

This is a valid documentation gap. Investigation of the ASP.NET Core rate limiting middleware source code (RateLimitingMiddleware.cs) reveals that:

1. The middleware passes context.RequestAborted as the CancellationToken to AcquireAsync (line 159). This means a queued request will only be released early if the client disconnects (triggering RequestAborted), not via server-side request timeout middleware.
2. The System.Threading.RateLimiting rate limiter options (e.g., FixedWindowRateLimiterOptions) do not expose an explicit "queue timeout" property. The queue timeout is effectively the rate limiter window duration — queued requests wait until the next window opens and permits are replenished.
3. The ASP.NET Core Request Timeouts middleware (UseRequestTimeouts / .WithRequestTimeout()) operates independently and does not directly cancel the rate limiter's AcquireAsync queue wait in the typical middleware pipeline ordering.

The documentation's reference to "timeout" is ambiguous and needs clarification.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/performance/rate-limit.md	419-437	"Request Queuing"
Main article	aspnetcore/performance/rate-limit.md	384-417	"Choosing what happens when a request is rate limited"
Middleware source (reference)	src/Middleware/RateLimiting/src/RateLimitingMiddleware.cs	151-177	TryAcquireAsync / CombinedWaitAsync

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential documentation Updates

Update 1: Clarify the "timeout" wording in the Request Queuing section

File: aspnetcore/performance/rate-limit.md
Location: Lines 421-437 (the "Request Queuing" subsection)
Type: Replacement / expanded content with a [!NOTE] block

Current content (lines 421-423):

### Request Queuing

With queuing enabled, when a request exceeds the rate limit, it's placed in a queue where the request waits until a permit becomes available or until a timeout occurs. Requests are processed according to a configurable queue order.

Suggested direction:

### Request Queuing

With queuing enabled, when a request exceeds the rate limit, it's placed in a queue instead of being immediately rejected. Queued requests wait until a permit becomes available—typically when the rate limiter's window resets and permits are replenished. Requests are processed according to the configured `QueueProcessingOrder`.

> [!NOTE]
> The rate limiter algorithms in `System.Threading.RateLimiting` do not expose a dedicated "queue timeout" option. Queued requests wait until permits are replenished (when the window resets) or until the request is canceled. The rate limiting middleware uses `HttpContext.RequestAborted` as its cancellation token, so a queued request is released if the **client disconnects**. However, the ASP.NET Core Request Timeouts middleware (`.WithRequestTimeout()`) does not cancel queued requests in the rate limiter, because both middlewares operate independently in the pipeline. If you need to limit how long a request waits in the queue, consider using a `CancellationTokenSource` with a timeout in a custom rate limiter policy, or design your `Window` and `QueueLimit` values so that the maximum wait time is bounded by the window duration.

Update 2: Add a code example showing how queued requests behave and how to observe cancellation

File: aspnetcore/performance/rate-limit.md
Location: After the existing code block on line 437 (after the current Request Queuing code sample)
Type: New paragraph with code example

Suggested direction:

#### Queue behavior details

When a request is queued:

* The request waits until the rate limiter's window resets and permits become available.
* If the queue is full (`QueueLimit` is reached), additional requests are rejected immediately.
* A queued request is canceled only if the client disconnects, triggering `HttpContext.RequestAborted`.
* Server-side request timeouts configured with `UseRequestTimeouts` / `.WithRequestTimeout()` do **not** automatically cancel a queued request in the rate limiter.

The following example shows a fixed window limiter with queuing. When more than 4 requests arrive in a 12-second window, up to 2 additional requests are queued. Queued requests wait until the next window opens:

```csharp
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("fixed", opt =>
    {
        opt.PermitLimit = 4;
        opt.Window = TimeSpan.FromSeconds(12);
        opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        opt.QueueLimit = 2;
    });

    options.OnRejected = async (context, cancellationToken) =>
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
        
        // The Retry-After value can indicate how long to wait
        if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
        {
            context.HttpContext.Response.Headers.RetryAfter = 
                ((int)retryAfter.TotalSeconds).ToString();
        }

        await context.HttpContext.Response.WriteAsync(
            "Rate limit exceeded. Please try again later.", cancellationToken);
    };
});

In this configuration, the maximum time a queued request waits is bounded by the Window duration (12 seconds). If you need a shorter timeout for queued requests, reduce the Window value or reduce the QueueLimit.

## 🎯 Suggested Action Plan
> *For documentation team review*

1. **Review and clarify the "Request Queuing" section:** [`aspnetcore/performance/rate-limit.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/rate-limit.md)
   * Navigate to: [Lines 421-437](https://github.com/dotnet/AspNetCore.Docs/blob/ae0051e0353d5f20ae5a39ec36d21dc3a5dbfe67/aspnetcore/performance/rate-limit.md#L421-L437)
   * Section: "Request Queuing"
   * Consider: Replace the ambiguous "or until a timeout occurs" phrasing with precise technical explanation of what triggers a queued request to stop waiting
   * Consider: Add a `[!NOTE]` block explaining that `System.Threading.RateLimiting` does not have a dedicated queue timeout setting

2. **Add explanatory content about queue timeout behavior:**
   * Navigate to: After [Line 437](https://github.com/dotnet/AspNetCore.Docs/blob/ae0051e0353d5f20ae5a39ec36d21dc3a5dbfe67/aspnetcore/performance/rate-limit.md#L437)
   * Consider: Add a subsection "Queue behavior details" explaining the relationship (or lack thereof) between Request Timeouts middleware and rate limiter queuing
   * Consider: Add a code example demonstrating how to bound the maximum queue wait time

3. **Verify behavior with the product team:**
   * Review the [`RateLimitingMiddleware.cs` source](https://github.com/dotnet/aspnetcore/blob/7a2262da483f193a7bb1cb1f82289983fe4a1461/src/Middleware/RateLimiting/src/RateLimitingMiddleware.cs#L159) to confirm `context.RequestAborted` is the only cancellation mechanism
   * Confirm whether the "timeout" phrasing in the original documentation was intentional or misleading

## ⚠️ Review Considerations
* Verify the documented behavior applies to .NET 7, 8, 9, and 10 (all supported versions with rate limiting middleware)
* Check if similar wording about "timeout" exists in API reference documentation for `System.Threading.RateLimiting` and whether it should be aligned
* Consider adding a cross-reference to the [Request Timeouts middleware documentation](https://learn.microsoft.com/en-us/aspnet/core/performance/timeouts) to explicitly clarify the independence of the two middlewares
* The middleware passes `context.RequestAborted` (not a custom timeout token) to `AcquireAsync` — this is a key technical detail to document

## 🔗 References
* Published article: [Rate limiting middleware in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit?view=aspnetcore-10.0#request-queuing)
* Source file: [`aspnetcore/performance/rate-limit.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/rate-limit.md)
* ASP.NET Core middleware source: [`RateLimitingMiddleware.cs`](https://github.com/dotnet/aspnetcore/blob/7a2262da483f193a7bb1cb1f82289983fe4a1461/src/Middleware/RateLimiting/src/RateLimitingMiddleware.cs)
* `System.Threading.RateLimiting` API docs: [FixedWindowRateLimiterOptions](https://learn.microsoft.com/en-us/dotnet/api/system.threading.ratelimiting.fixedwindowratelimiteroptions)
* Request Timeouts middleware: [ASP.NET Core Request Timeouts](https://learn.microsoft.com/en-us/aspnet/core/performance/timeouts)
* Related issue: [#36782](https://github.com/dotnet/AspNetCore.Docs/issues/36782)