AspNetCore.Docs/aspnetcore/performance/rate-limit.md

title	author	description	ms.author	ms.custom	ms.date	uid
Rate limiting middleware in ASP.NET Core	rick-anderson	Learn how limit requests in ASP.NET Core apps	riande	mvc	8/28/2022	performance/rate-limit

Rate limiting middleware in ASP.NET Core

By Arvin Kahbazi and Rick Anderson

:::moniker range=">= aspnetcore-7.0"

The Microsoft.AspNetCore.RateLimiting middleware provides rate limiting middleware. Apps configure rate limiting policies and then attach the policies to endpoints. Apps using rate limiting should be carefully load tested and reviewed before deploying. See Testing endpoints with rate limiting in this article for more information.

Rate limiter algorithms

The RateLimiterOptionsExtensions class provides the following extension methods for rate limiting:

• Fixed window
• Sliding window
• Token bucket
• Concurrency

Fixed window limiter

The AddFixedWindowLimiter method uses a fixed time window to limit requests. When the time window expires, a new time window starts and the request limit is reset.

Consider the following code:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_fixed":::

The preceding code:

• Calls UseRateLimiter to enable rate limiting.
• Creates a fixed window limiter with a policy name of "fixed" and sets:
• permitLimit to 4 and the time window to 12. A maximum of 4 requests per each 12-second window are allowed.
• queueProcessingOrder to QueueProcessingOrder.OldestFirst.
• queueLimit to 2.

Apps should use Configuration to set limiter options. The following code updates the preceding code using MyRateLimitOptions for configuration:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_fixed2":::

Sliding window limiter

A sliding window algorithm:

• Is similar to the fixed window limiter but adds segments per window. The window slides one segment each segment interval. The segment interval is (window time)/(segments per window).

• Limits the requests for a window to permitLimit requests.

• Each time window is divided in n segments per window.

• Requests taken from the expired time segment one window back (n segments prior to the current segment), are added to the current segment. We refer to the most expired time segment one window back as the expired segment. Consider the following table which shows a sliding window limiter with a 30-second window, 3 segments per window and a limit of 100 requests:

• The top row and first column shows the time segment.

• The second row shows the remaining requests available. The remaining requests are available-requests+recycled.

• Requests at each time moves along the diagonal blue line.

• From time 30 on, the request taken from the expired time segment are added back to the request limit, as shown in the red lines.

The following table shows the data in the previous graph in a different format. The Remaining column shows the requests available from the previous segment (The Carry over from the previous row). The first row shows 100 available because there's no previous segment:

Time	Available	Taken	Recycled from expired	Carry over
0	100	20	0	80
10	80	30	0	50
20	50	40	0	10
30	10	30	20	0
40	0	10	30	20
50	20	10	40	50
60	50	35	30	45

The following code uses the sliding window rate limiter:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_slide":::

Token bucket limiter

The token bucket limiter is similar to the sliding window limiter, but rather than adding back the requests taken from the expired segment, a fixed number of tokens are added each replenishment period. The tokens added each segment can't increase the available tokens to a number higher than the token bucket limit. The following table shows a token bucket limiter with a limit of 100 tokens and a 10-second replenishment period:

Time	Available	Taken	Added	Carry over
0	100	20	0	80
10	80	10	20	90
20	90	5	15	100
30	100	30	20	90
40	90	6	16	100
50	100	40	20	80
60	80	50	20	50

The following code uses the token bucket limiter:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_token":::

When autoReplenishment is set to true, an internal timer replenishes the tokens every replenishmentPeriod; when set to false, the app must call TryReplenish on the limiter.

Concurrency limiter

The concurrency limiter limits the number concurrent requests. Each request reduces the concurrency limit by one. When a request completes, the limit is increased by one. Unlike the other requests limiters that limit the total number of requests for a specified period, the concurrency limiter limits only the number of concurrent requests and doesn't cap the number of requests in a time period.

The following code uses the concurrency limiter:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_concur":::

Limiter algorithm comparison

The fixed, sliding, and token limiters all limit the maximum number of requests in a time period. The concurrency limiter limits only the number of concurrent requests and doesn't cap the number of requests in a time period. The cost of an endpoint should be considered when selecting a limiter. The cost of an endpoint includes the resources used, for example, time, data access, CPU, and I/O.

Rate limiter samples

The following samples aren't meant for production code but are examples on how to use the limiters.

Limiter with OnRejected, RetryAfter, and GlobalLimiter

The following sample:

• Creates a RateLimiterOptions.OnRejected callback that is called when a request exceeds the specified limit. retryAfter can be used with the TokenBucketRateLimiter, FixedWindowLimiter, and SlidingWindowLimiter because these algorithms are able to estimate when more permits will be added. The ConcurrencyLimiter has no way of calculating when permits will be available.

• Adds the following limiters:

  • A SampleRateLimiterPolicy which implements the IRateLimiterPolicy<TPartitionKey> interface. The SampleRateLimiterPolicy class is shown later in this article.
  • A SlidingWindowLimiter:
    • With a partition for each authenticated user.
    • One shared partition for all anonymous users.
  • A xref:Microsoft.AspNetCore.RateLimiting.RateLimiterOptions.GlobalLimiter that is applied to all requests. The global limiter will be executed first, followed by the endpoint-specific limiter, if one exists. The GlobalLimiter creates a partition for each xref:System.Net.IPAddress.

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet":::

[!WARNING] Creating partitions on client IP addresses makes the app vulnerable to Denial of Service Attacks which employ IP Source Address Spoofing. For more information, see BCP 38 RFC 2827 Network Ingress Filtering: Defeating Denial of Service Attacks which employ IP Source Address Spoofing.

See the samples repository for the complete Program.cs file.

The SampleRateLimiterPolicy class

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/SampleRateLimiterPolicy.cs" id="snippet_1":::

In the preceding code, xref:Microsoft.AspNetCore.RateLimiting.RateLimiterOptions.OnRejected uses xref:Microsoft.AspNetCore.RateLimiting.OnRejectedContext to set the response status to 429 Too Many Requests. The default rejected status is 503 Service Unavailable.

Limiter with authorization

The following sample uses JSON Web Tokens (JWT) and creates a partition with the JWT access token. In a production app, the JWT would typically be provided by a server acting as a Security token service (STS). For local development, the dotnet user-jwts command line tool can be used to create and manage app-specific local JWTs.

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_jwt":::

Limiter with ConcurrencyLimiter, TokenBucketRateLimiter, and authorization

The following sample:

• Adds a ConcurrencyLimiter with a policy name of "get" that is used on the Razor Pages.
• Adds a TokenBucketRateLimiter with a partition for each authorized user and a partition for all anonymous users.
• Sets RateLimiterOptions.RejectionStatusCode to 429 Too Many Requests.

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRateLimitAuth/Program.cs" id="snippet_adm2":::

See the samples repository for the complete Program.cs file.

Testing endpoints with rate limiting

Before deploying an app using rate limiting to production, stress test the app to validate the rate limiters and options used. For example, create a JMeter script with a tool like BlazeMeter or Apache JMeter HTTP(S) Test Script Recorder and load the script to Azure Load Testing.

Creating partitions with user input makes the app vulnerable to Denial of Service (DoS) Attacks. For example, creating partitions on client IP addresses makes the app vulnerable to Denial of Service Attacks that employ IP Source Address Spoofing. For more information, see BCP 38 RFC 2827 Network Ingress Filtering: Defeating Denial of Service Attacks that employ IP Source Address Spoofing.

:::moniker-end