Eigenverft.WebLib.RequestTrafficShaping 1.0.0.5-g40a2f17cdc

Eigenverft.WebLib.RequestTrafficShaping

ASP.NET Core rate limiting composed from per-client and server-wide token buckets plus an optional application-wide concurrency limit.

✨ At a glance

📦 Installation

dotnet add package Eigenverft.WebLib.RequestTrafficShaping

🚀 Quick start

using Eigenverft.WebLib.RequestTrafficShaping;

builder.Services.AddRequestTrafficShaping(options =>
{
    options.PerClient.BurstSize = 40;
    options.PerClient.RequestsPerSecond = 10;
    options.PerClient.QueueLimit = 20;
    options.ServerWide.BurstSize = 10_000;
    options.ServerWide.RequestsPerSecond = 10_000;
    options.ServerWide.QueueLimit = 10_000;
    // options.GlobalConcurrencyLimit = 500;
});

WebApplication app = builder.Build();
app.UseRateLimiter();

The same settings can be supplied under the RequestTrafficShaping configuration section. Class defaults are applied first, configuration binding next, and the optional callback last.

Limiter behavior and configuration

The chain is per-client token bucket, then aggregate server-wide token bucket, then the optional global concurrency limiter. Both token-bucket layers are enabled by default. Each uses a one-second replenishment period and a bounded oldest-first queue. Rejections return 429; a Retry-After header is added when native limiter metadata supplies a positive retry delay.

The per-client partition uses normalized HttpContext.Connection.RemoteIpAddress directly; this package does not depend on Eigenverft.WebLib.ClientNetwork. IPv4-mapped IPv6 is normalized to IPv4 and IPv6 scope IDs are ignored. When there is no peer IP, MissingClientIpBehavior.SharedPartition (the default) groups missing addresses together. BypassPerIpLimit skips only the per-client limiter; the server-wide and optional concurrency limits still apply.

When a trusted reverse proxy provides client IPs, configure ASP.NET Core Forwarded Headers and run it before UseRateLimiter(). Validate trust boundaries before accepting forwarded addresses.

Burst and request-rate values must be positive, queue limits non-negative, and BurstSize must be at least RequestsPerSecond. The optional concurrency limit must be positive when set. Options are validated on startup and construct the limiters then; changing configuration does not live-reconfigure running token buckets. Tune the generous server-wide starting values against representative application load.

🎯 Target frameworks

Targets net8.0 and net10.0; .NET 9 applications can consume the compatible net8.0 asset.

🔗 Project links

• Repository
• Solution and tests
• Project source
• NuGet package

📄 License

MIT; see the repository license.