Documentation

Token Bucket Options

Read time 3 minutes Package: Nalix.Runtime
On this page

Namespace: Nalix.Runtime.Options
Assembly: Nalix.Runtime

TokenBucketOptions (public sealed partial class TokenBucketOptions : ConfigurationLoader, IValidatableConfiguration) configures the sharded, fixed-point micro-token rate limiter TokenBucketLimiter and provides fallback defaults for PolicyRateLimiter.

Source Mapping

  • src/Nalix.Runtime/Options/TokenBucketOptions.cs
  • src/Nalix.Runtime/Throttling/TokenBucketLimiter.cs
  • src/Nalix.Runtime/Throttling/PolicyRateLimiter.cs

Properties

Loaded from the [TokenBucket] section of default.ini via ConfigurationManager.Instance.Get<TokenBucketOptions>():

PropertyTypeDefaultValidationDescription
CapacityTokensint64[ValueRange(1, int.MaxValue)]Maximum burst capacity in whole tokens per endpoint.
RefillTokensPerSeconddouble32.0[ValueRange(0.001, double.MaxValue)]Sustained token refill rate per second.
HardLockoutSecondsint30[ValueRange(0, int.MaxValue)]Duration in seconds an endpoint is hard-blocked after reaching MaxSoftViolations (0 = disabled).
StaleEntrySecondsint180[ValueRange(1, int.MaxValue)]Idle seconds before an endpoint entry becomes eligible for background eviction.
CleanupIntervalSecondsint45[ValueRange(1, int.MaxValue)]Interval in seconds for the "token.bucket" recurring cleanup job in ITaskManager.
TokenScaleint100[ValueRange(1, 1_000_000)]Fixed-point micro-tokens per whole token (CapacityTokens * (long)TokenScale must fit in long).
ShardCountint256[ValueRange(1, int.MaxValue)], power of 2Number of concurrent map shards ((ShardCount & (ShardCount - 1)) == 0).
SoftViolationWindowSecondsint8[ValueRange(1, int.MaxValue)]Sliding window in seconds for accumulating consecutive soft-throttle violations.
MaxSoftViolationsint5[ValueRange(1, int.MaxValue)]Soft violations within SoftViolationWindowSeconds required to escalate to HardLockout.
CooldownResetSecint10[ValueRange(1, int.MaxValue)]Configured cooldown reset duration in seconds.
MaxTrackedEndpointsint100_000[ValueRange(0, int.MaxValue)]Maximum simultaneously tracked endpoints across all shards (0 = unlimited).
AdaptiveThrottlingEnabledbooltrue—Scales token refill rate by ITaskManager.ConcurrencyLimitRatio when server CPU load is high.
InitialTokensint-1<= CapacityTokensStarting token balance for newly seen endpoints (< 0 = full CapacityTokens, 0 = empty cold-start, > 0 = explicit token count).
MaxEvictionCapacityint8192[ValueRange(64, 65536)]Initial candidate-list capacity used during over-limit cleanup sweeps.
MinReportCapacityint256[ValueRange(64, 8192)]Minimum initial list capacity used when generating IReportable snapshots.

Validation Rules (Validate())

Validate() runs DataAnnotation attribute checks and enforces:

  1. ShardCount > 0 and (ShardCount & (ShardCount - 1)) == 0 (must be a power of two).
  2. CapacityTokens * (long)TokenScale <= long.MaxValue.
  3. InitialTokens <= CapacityTokens.