Documentation

Connection Quota Options

Read time 4 minutes Package: Nalix.Network
On this page

Namespace: Nalix.Network.Options
Assembly: Nalix.Network

ConnectionQuotaOptions (public sealed partial class ConnectionQuotaOptions : ConfigurationLoader, IValidatableConfiguration) configures per-IP and per-subnet concurrency caps, rate windows, burst/short-lived connection penalties, endpoint map bounds, and adaptive Proof-of-Work scaling enforced by ConnectionGuard.

Source Mapping

  • src/Nalix.Network/Options/ConnectionQuotaOptions.cs
  • src/Nalix.Network/RateLimiting/Connection.Guard.cs
  • src/Nalix.Network/RateLimiting/Connection.Guard.Slot.cs
  • src/Nalix.Network/RateLimiting/Connection.Guard.Subnet.cs
  • src/Nalix.Network/RateLimiting/Connection.Guard.Cleanup.cs

Complete Property Reference

Loaded from the [ConnectionQuota] section of default.ini:

1. Per-IP, Per-Subnet & Map Bounds

PropertyTypeDefaultValidationRuntime Effect
MaxConnectionsPerIpAddressint10[ValueRange(1, 10_000)]Maximum concurrent active connections permitted from a single remote IP address.
ExemptLoopbackbooltrue—Exempts loopback clients (127.0.0.0/8, ::1, ::ffff:127.x.x.x) from per-IP/subnet quotas, rate windows, and auto-bans (ConnectionGuardOptions.MaxConnections still applies).
MaxTrackedEndpointsint50_000[ValueRange(-1, 10_000_000)]Hard cap on tracked IP entries in ConnectionGuard (-1 = unlimited; uses $O(1)$ random-sampling eviction when full).
MaxConnectionsPerWindowint10[ValueRange(1, 10_000_000)]Maximum connection attempts allowed from a single IP within ConnectionRateWindow before triggering a ban.
ConnectionRateWindowTimeSpan00:00:05 (5s)[DurationRange("00:00:01", "00:10:00")]Sliding window duration used to count recent connection attempts per IP and per subnet.
MaxConnectionsPerSubnetint50[ValueRange(1, 100_000)]Maximum concurrent connections allowed from a single /24 (IPv4) or /48 (IPv6) subnet.
MaxSubnetConnectionsPerWindowint100[ValueRange(1, 10_000_000)]Maximum connection attempts allowed from a /24 or /48 subnet within ConnectionRateWindow.
CleanupIntervalTimeSpan00:01:00 (1m)[DurationRange("00:00:01", "01:00:00")]Interval of the recurring "conn.limit" cleanup job that purges inactive endpoint entries.
InactivityThresholdTimeSpan00:05:00 (5m)[DurationRange("00:00:01", "1.00:00:00")]Idle duration after which a zero-connection endpoint entry becomes eligible for cleanup.
MaxCleanupKeysPerRunint0[ValueRange(0, 10_000_000)]Maximum endpoint keys scanned per cleanup cycle (0 auto-scales to a percentage of tracked entries).
DailyResetTimeOffsetTimeSpan00:00:00[DurationRange("-14:00:00", "14:00:00")]UTC offset used to determine start-of-day for daily connection-limit resets.

2. Burst & Short-Lived Connection Detection

PropertyTypeDefaultValidationRuntime Effect
MinConnectionIntervalMsint50[ValueRange(0, 10_000)]Minimum interval in ms between connections from the same IP; faster arrivals increment the rapid-connection counter.
BurstThresholdint3[ValueRange(2, 100)]Consecutive rapid connections required to activate burst mode for an IP.
BurstPenaltyDivisorint2[ValueRange(1, 10)]Divisor applied to MaxConnectionsPerWindow while an IP is in burst mode (2 halves the rate limit).
ShortLivedThresholdMsint2000[ValueRange(0, 60_000)]Connections closing within this threshold (ms) inject an extra penalty timestamp into the endpoint’s rate window.

3. Adaptive Tightening & Proof-of-Work (IProofOfWorkPolicy)

PropertyTypeDefaultValidationRuntime Effect
EnableAdaptiveModeboolfalse—Enables load-adaptive per-IP limit tightening and dynamic Proof-of-Work difficulty scaling.
AdaptiveLoadThresholddouble0.7[ValueRange(0.1, 0.99)]Global connection load ratio (_globalConnections / MaxConnections) that triggers adaptive per-IP tightening.
AdaptiveTighteningFactordouble0.5[ValueRange(0.1, 1.0)]Multiplier applied to MaxConnectionsPerIpAddress when adaptive tightening is active.
AdaptivePowMinDifficultybyte12[ValueRange(0, 32)]Baseline Proof-of-Work leading-zero-bit difficulty returned when not under attack (or when EnableAdaptiveMode is false).
AdaptivePowMaxDifficultybyte24[ValueRange(0, 32)]Maximum Proof-of-Work difficulty under full flood load.
AdaptivePowStartRateint10[ValueRange(1, 1_000_000)]EWMA connection rate (attempts/sec) at which PoW difficulty starts scaling above AdaptivePowMinDifficulty.
AdaptivePowMaxRateint100[ValueRange(10, 10_000_000)]EWMA connection rate (attempts/sec) at which rate-based PoW scaling reaches 1.0.
EnableCapacityBasedPoWbooltrue—Combines rate-based scaling with server capacity scaling (finalScale = rateScale * capacityScale).
CapacityPoWThresholddouble0.5[ValueRange(0.0, 1.0)]Global connection load factor (0.5 = 50% of MaxConnections) below which capacityScale remains 0.0.