Skip to content

Token Bucket Limiter

TokenBucketLimiter is a per-endpoint rate limiter for ingress protection.

Source mapping

  • src/Nalix.Network/Throttling/TokenBucketLimiter.cs

What it does

  • keeps a token bucket per endpoint
  • refills credit over time
  • returns retry timing when traffic is denied
  • escalates repeated abuse into hard lockouts
  • bounds memory with tracked-endpoint limits and cleanup

Basic usage

TokenBucketLimiter limiter = new(tokenBucketOptions);

var decision = limiter.Check(endpoint);
if (!decision.Allowed)
{
    return;
}

Decision model

The result tells you:

  • whether the request is allowed
  • how long to wait before retry
  • how much credit remains
  • whether the denial is soft throttle or hard lockout

When to use it

Use this limiter when the key is the caller endpoint rather than the handler opcode.

Diagnostics

GenerateReport() includes:

  • tracked endpoint count
  • hard-blocked count
  • top endpoints by pressure
  • current token settings