SERVER-106045 Redefine burstSize => burstCapacitySecs parameter (#37078)

erin2722 · MongoDB Bot · commit 8b9a7aced6c3 · 2025-07-07T19:54:01.000Z
GitOrigin-RevId: 6db9637e30a4f899a1ae3ab315df403f7c63fa69
diff --git a/jstests/noPassthrough/connection_establishment_rate_limiting_client_disconnect.js b/jstests/noPassthrough/connection_establishment_rate_limiting_client_disconnect.js
@@ -53,7 +53,7 @@ const testKillOnClientDisconnect = (conn) => {
 const testKillOnClientDisconnectOpts = {
     ingressConnectionEstablishmentRateLimiterEnabled: true,
     ingressConnectionEstablishmentRatePerSec: 1,
-    ingressConnectionEstablishmentBurstSize: 1,
+    ingressConnectionEstablishmentBurstCapacitySecs: 1,
     ingressConnectionEstablishmentMaxQueueDepth: maxQueueSize,
 };
 runTestStandaloneParamsSetAtStartup(testKillOnClientDisconnectOpts, testKillOnClientDisconnect);
diff --git a/jstests/noPassthrough/connection_establishment_rate_limiting_exemptions.js b/jstests/noPassthrough/connection_establishment_rate_limiting_exemptions.js
@@ -50,7 +50,7 @@ const testExemptIPsFromRateLimit = (conn) => {
 const testExemptIPsFromRateLimitOpts = {
     ingressConnectionEstablishmentRateLimiterEnabled: true,
     ingressConnectionEstablishmentRatePerSec: 1,
-    ingressConnectionEstablishmentBurstSize: 1,
+    ingressConnectionEstablishmentBurstCapacitySecs: 1,
     ingressConnectionEstablishmentMaxQueueDepth: 0,
     ingressConnectionEstablishmentRateLimiterBypass: {ranges: [exemptIP]},
 };
diff --git a/jstests/noPassthrough/connection_establishment_rate_limiting_proxy_protocol.js b/jstests/noPassthrough/connection_establishment_rate_limiting_proxy_protocol.js
@@ -34,7 +34,7 @@ let rs = new ReplSetTest({
         setParameter: {
             ingressConnectionEstablishmentRateLimiterEnabled: true,
             ingressConnectionEstablishmentRatePerSec: 1,
-            ingressConnectionEstablishmentBurstSize: 1,
+            ingressConnectionEstablishmentBurstCapacitySecs: 1,
             ingressConnectionEstablishmentMaxQueueDepth: 0,
             ingressConnectionEstablishmentRateLimiterBypass: {ranges: [exemptIP]},
             featureFlagRateLimitIngressConnectionEstablishment: true
diff --git a/jstests/noPassthrough/connection_establishment_rate_limiting_stats.js b/jstests/noPassthrough/connection_establishment_rate_limiting_stats.js
@@ -95,7 +95,7 @@ const testRateLimiterStats = (conn) => {
 const testRateLimiterStatsOpts = {
     ingressConnectionEstablishmentRateLimiterEnabled: true,
     ingressConnectionEstablishmentRatePerSec: 1,
-    ingressConnectionEstablishmentBurstSize: 1,
+    ingressConnectionEstablishmentBurstCapacitySecs: 1,
     ingressConnectionEstablishmentMaxQueueDepth: maxQueueSize,
 };
 runTestStandaloneParamsSetAtStartup(testRateLimiterStatsOpts, testRateLimiterStats);
diff --git a/jstests/noPassthrough/connection_establishment_server_params.js b/jstests/noPassthrough/connection_establishment_server_params.js
@@ -5,9 +5,9 @@ function getIngressConnectionEstablishmentRatePerSec(mongo) {
         .ingressConnectionEstablishmentRatePerSec;
 }
 
-function getIngressConnectionEstablishmentBurstSize(mongo) {
-    return mongo.adminCommand({getParameter: 1, ingressConnectionEstablishmentBurstSize: 1})
-        .ingressConnectionEstablishmentBurstSize;
+function getingressConnectionEstablishmentBurstCapacitySecs(mongo) {
+    return mongo.adminCommand({getParameter: 1, ingressConnectionEstablishmentBurstCapacitySecs: 1})
+        .ingressConnectionEstablishmentBurstCapacitySecs;
 }
 
 function getIngressConnectionEstablishmentMaxQueueDepthDefault(mongo) {
@@ -23,9 +23,14 @@ let ingressConnectionEstablishmentRatePerSecDefault =
     getIngressConnectionEstablishmentRatePerSec(mongo);
 assert.eq(ingressConnectionEstablishmentRatePerSecDefault, maxInt32);
 
-let ingressConnectionEstablishmentBurstSizeDefault =
-    getIngressConnectionEstablishmentBurstSize(mongo);
-assert.eq(ingressConnectionEstablishmentBurstSizeDefault, maxInt32);
+let ingressConnectionEstablishmentBurstCapacitySecsDefault =
+    getingressConnectionEstablishmentBurstCapacitySecs(mongo);
+assert.eq(ingressConnectionEstablishmentBurstCapacitySecsDefault, Number.MAX_VALUE);
+
+// There are infinite tokens available by default.
+let availableTokens =
+    mongo.adminCommand({serverStatus: 1}).queues.ingressSessionEstablishment.totalAvailableTokens;
+assert.eq(availableTokens, Infinity);
 
 let ingressConnectionEstablishmentMaxQueueDepthDefault =
     getIngressConnectionEstablishmentMaxQueueDepthDefault(mongo);
@@ -36,7 +41,7 @@ const runtimeSetValue = 10;
 assert.commandWorked(mongo.adminCommand({
     setParameter: 1,
     ingressConnectionEstablishmentRatePerSec: runtimeSetValue,
-    ingressConnectionEstablishmentBurstSize: runtimeSetValue,
+    ingressConnectionEstablishmentBurstCapacitySecs: runtimeSetValue,
     ingressConnectionEstablishmentMaxQueueDepth: runtimeSetValue
 }));
 
@@ -45,9 +50,11 @@ assert.neq(ingressConnectionEstablishmentRatePerSec,
            ingressConnectionEstablishmentMaxQueueDepthDefault);
 assert.eq(ingressConnectionEstablishmentRatePerSec, runtimeSetValue);
 
-let ingressConnectionEstablishmentBurstSize = getIngressConnectionEstablishmentBurstSize(mongo);
-assert.neq(ingressConnectionEstablishmentBurstSize, ingressConnectionEstablishmentBurstSizeDefault);
-assert.eq(ingressConnectionEstablishmentBurstSize, runtimeSetValue);
+let ingressConnectionEstablishmentBurstCapacitySecs =
+    getingressConnectionEstablishmentBurstCapacitySecs(mongo);
+assert.neq(ingressConnectionEstablishmentBurstCapacitySecs,
+           ingressConnectionEstablishmentBurstCapacitySecsDefault);
+assert.eq(ingressConnectionEstablishmentBurstCapacitySecs, runtimeSetValue);
 
 let ingressConnectionEstablishmentMaxQueueDepth =
     mongo.adminCommand({getParameter: 1, ingressConnectionEstablishmentMaxQueueDepth: 1})
@@ -61,16 +68,17 @@ const startupSetValue = 50;
 mongo = MongoRunner.runMongod({
     setParameter: {
         ingressConnectionEstablishmentRatePerSec: startupSetValue,
-        ingressConnectionEstablishmentBurstSize: startupSetValue,
+        ingressConnectionEstablishmentBurstCapacitySecs: startupSetValue,
         ingressConnectionEstablishmentMaxQueueDepth: startupSetValue
     }
 });
 
 ingressConnectionEstablishmentRatePerSec = getIngressConnectionEstablishmentRatePerSec(mongo);
 assert.eq(ingressConnectionEstablishmentRatePerSec, startupSetValue);
 
-ingressConnectionEstablishmentBurstSize = getIngressConnectionEstablishmentBurstSize(mongo);
-assert.eq(ingressConnectionEstablishmentBurstSize, startupSetValue);
+ingressConnectionEstablishmentBurstCapacitySecs =
+    getingressConnectionEstablishmentBurstCapacitySecs(mongo);
+assert.eq(ingressConnectionEstablishmentBurstCapacitySecs, startupSetValue);
 
 ingressConnectionEstablishmentMaxQueueDepth =
     mongo.adminCommand({getParameter: 1, ingressConnectionEstablishmentMaxQueueDepth: 1})
@@ -89,9 +97,10 @@ assert.eq(ingressConnectionEstablishmentRatePerSec, stringSetValue);
 MongoRunner.stopMongod(mongo);
 
 mongo = MongoRunner.runMongod(
-    {setParameter: 'ingressConnectionEstablishmentBurstSize=' + stringSetValue});
-ingressConnectionEstablishmentBurstSize = getIngressConnectionEstablishmentBurstSize(mongo);
-assert.eq(ingressConnectionEstablishmentBurstSize, stringSetValue);
+    {setParameter: 'ingressConnectionEstablishmentBurstCapacitySecs=' + stringSetValue});
+ingressConnectionEstablishmentBurstCapacitySecs =
+    getingressConnectionEstablishmentBurstCapacitySecs(mongo);
+assert.eq(ingressConnectionEstablishmentBurstCapacitySecs, stringSetValue);
 MongoRunner.stopMongod(mongo);
 
 mongo = MongoRunner.runMongod(
@@ -101,3 +110,32 @@ ingressConnectionEstablishmentMaxQueueDepth =
         .ingressConnectionEstablishmentMaxQueueDepth;
 assert.eq(ingressConnectionEstablishmentMaxQueueDepth, stringSetValue);
 MongoRunner.stopMongod(mongo);
+
+// Make sure that increasing the burstSize results in increasing the available tokens in the bucket
+const marginOfError = 5;  // +/- 5 tokens just in case there is rounding errors/clock skew
+const refreshRate = 10000;
+const initialBurstCapacitySecs = 0.5;
+mongo = MongoRunner.runMongod({
+    setParameter: {
+        ingressConnectionEstablishmentRatePerSec: refreshRate,
+        ingressConnectionEstablishmentBurstCapacitySecs: initialBurstCapacitySecs,
+    }
+});
+let initialTokens =
+    mongo.adminCommand({serverStatus: 1}).queues.ingressSessionEstablishment.totalAvailableTokens;
+const targetTokens = refreshRate * initialBurstCapacitySecs;
+assert.between(targetTokens - marginOfError, initialTokens, targetTokens + marginOfError);
+
+const newBurstCapacitySecs = 2;
+const newTargetTokens = refreshRate * newBurstCapacitySecs;
+assert.commandWorked(mongo.adminCommand(
+    {setParameter: 1, ingressConnectionEstablishmentBurstCapacitySecs: newBurstCapacitySecs}));
+assert.soon(() => {
+    const newTokens = mongo.adminCommand({serverStatus: 1})
+                          .queues.ingressSessionEstablishment.totalAvailableTokens;
+    jsTestLog("New tokens: " + newTokens);
+    return newTargetTokens - marginOfError <= newTokens &&
+        newTokens <= newTargetTokens + marginOfError;
+});
+
+MongoRunner.stopMongod(mongo);
diff --git a/jstests/noPassthrough/libs/conn_establishment_rate_limiter_helpers.js b/jstests/noPassthrough/libs/conn_establishment_rate_limiter_helpers.js
@@ -32,7 +32,7 @@ export const runTestStandaloneParamsSetAtStartup = (setParams, testCase) => {
     mongod.adminCommand({
         setParameter: 1,
         ingressConnectionEstablishmentRatePerSec: 10.0,
-        ingressConnectionEstablishmentBurstSize: 500.0,
+        ingressConnectionEstablishmentBurstCapacitySecs: 500.0,
     });
 
     MongoRunner.stopMongod(mongod);
@@ -57,7 +57,7 @@ export const runTestStandaloneParamsSetAtRuntime = (setParams, testCase) => {
     mongod.adminCommand({
         setParameter: 1,
         ingressConnectionEstablishmentRatePerSec: 10.0,
-        ingressConnectionEstablishmentBurstSize: 500.0,
+        ingressConnectionEstablishmentBurstCapacitySecs: 500.0,
     });
 
     MongoRunner.stopMongod(mongod);
@@ -83,7 +83,7 @@ export const runTestReplSet = (setParams, testCase) => {
     replSet.getPrimary().adminCommand({
         setParameter: 1,
         ingressConnectionEstablishmentRatePerSec: 10.0,
-        ingressConnectionEstablishmentBurstSize: 500.0,
+        ingressConnectionEstablishmentBurstCapacitySecs: 500.0,
     });
 
     replSet.stopSet();
@@ -118,7 +118,7 @@ export const runTestShardedCluster = (setParams, testCase) => {
     st.s0.adminCommand({
         setParameter: 1,
         ingressConnectionEstablishmentRatePerSec: 1000.0,
-        ingressConnectionEstablishmentBurstSize: 500.0,
+        ingressConnectionEstablishmentBurstCapacitySecs: 500.0,
         ingressConnectionEstablishmentMaxQueueDepth: 100,
     });
 
diff --git a/src/mongo/db/admission/rate_limiter.cpp b/src/mongo/db/admission/rate_limiter.cpp
@@ -164,20 +164,14 @@ void RateLimiter::recordExemption() {
     _impl->stats.exemptedAdmissions.incrementRelaxed();
 }
 
-void RateLimiter::setRefreshRatePerSec(double refreshRatePerSec) {
-    auto lk = _impl->rwMutex.writeLock();
-    _impl->tokenBucket.reset(refreshRatePerSec, _impl->tokenBucket.burst());
-}
-
-void RateLimiter::setBurstSize(double burstSize) {
+void RateLimiter::updateRateParameters(double refreshRatePerSec, double burstSize) {
     uassert(ErrorCodes::InvalidOptions,
             fmt::format("burstSize cannot be less than 1.0. burstSize={}; rateLimiterName={}",
                         burstSize,
                         _impl->name),
             burstSize >= 1.0);
-
     auto lk = _impl->rwMutex.writeLock();
-    _impl->tokenBucket.reset(_impl->tokenBucket.rate(), burstSize);
+    _impl->tokenBucket.reset(refreshRatePerSec, burstSize);
 }
 
 void RateLimiter::setMaxQueueDepth(int64_t maxQueueDepth) {
diff --git a/src/mongo/db/admission/rate_limiter.h b/src/mongo/db/admission/rate_limiter.h
@@ -107,16 +107,12 @@ class RateLimiter {
     void recordExemption();
 
     /**
-     * The number of tokens issued per second when rate-limiting has kicked in. Tokens will be
-     * issued smoothly, rather than all at once every 1 second.
+     * refreshRate is the number of tokens issued per second when rate-limiting has kicked in.
+     * Tokens will be issued smoothly, rather than all at once every 1 second. The burstSize is the
+     * maximum number of tokens that will be issued before rate-limiting kicks in (ie, the maximum
+     * number of tokens that can accumulate in the bucket).
      */
-    void setRefreshRatePerSec(double refreshRatePerSec);
-
-    /**
-     * The maximum number of tokens that will be issued before rate-limiting kicks in (ie, the
-     * maximum number of tokens that can accumulate in the bucket).
-     */
-    void setBurstSize(double burstSize);
+    void updateRateParameters(double refreshRatePerSec, double burstSize);
 
     /**
      * The maximum number of requests enqueued waiting for a token. Token requests that come in and
diff --git a/src/mongo/db/admission/rate_limiter_util_test.cpp b/src/mongo/db/admission/rate_limiter_util_test.cpp
@@ -97,8 +97,9 @@ TEST_F(RateLimiterTest, BasicTokenAcquisition) {
 TEST_F(RateLimiterTest, InvalidBurstSize) {
     ASSERT_THROWS_CODE(RateLimiter(1.0, 0, 0), DBException, ErrorCodes::InvalidOptions);
 
-    RateLimiter rateLimiter(DBL_MAX, DBL_MAX, INT_MAX);
-    ASSERT_THROWS_CODE(rateLimiter.setBurstSize(0), DBException, ErrorCodes::InvalidOptions);
+    RateLimiter rateLimiter(DBL_MAX, DBL_MAX, INT_MAX, "InvalidBurstSize");
+    ASSERT_THROWS_CODE(
+        rateLimiter.updateRateParameters(1.0, 0), DBException, ErrorCodes::InvalidOptions);
 }
 
 // Verify that a newly initialized RateLimiter can immediately dispense up to its burst rate of
diff --git a/src/mongo/transport/session_establishment_rate_limiter.cpp b/src/mongo/transport/session_establishment_rate_limiter.cpp
@@ -39,7 +39,8 @@ namespace transport {
 
 SessionEstablishmentRateLimiter::SessionEstablishmentRateLimiter()
     : _rateLimiter(gIngressConnectionEstablishmentRatePerSec.load(),
-                   gIngressConnectionEstablishmentBurstSize.load(),
+                   gIngressConnectionEstablishmentRatePerSec.load() *
+                       gIngressConnectionEstablishmentBurstCapacitySecs.load(),
                    gIngressConnectionEstablishmentMaxQueueDepth.load(),
                    "SessionEstablishmentRateLimiter") {}
 
@@ -63,7 +64,6 @@ SessionEstablishmentRateLimiter* SessionEstablishmentRateLimiter::get(ServiceCon
     return rateLimiter;
 }
 
-
 Status SessionEstablishmentRateLimiter::throttleIfNeeded(Client* client) {
     // Check if the session is exempt from rate limiting based on its IP.
     serverGlobalParams.maxEstablishingConnsOverride.refreshSnapshot(_maxEstablishingConnsOverride);
@@ -89,7 +89,6 @@ Status SessionEstablishmentRateLimiter::throttleIfNeeded(Client* client) {
     return s;
 }
 
-
 void SessionEstablishmentRateLimiter::appendStatsConnections(BSONObjBuilder* bob) const {
     bob->append("queuedForEstablishment", queued());
 
diff --git a/src/mongo/transport/session_establishment_rate_limiter.h b/src/mongo/transport/session_establishment_rate_limiter.h
@@ -49,7 +49,7 @@ namespace mongo::transport {
  * parameters:
  *
  * - ingressConnectionEstablishmentRatePerSec
- * - ingressConnectionEstablishmentBurstSize
+ * - ingressConnectionEstablishmentBurstCapacitySecs
  * - ingressConnectionEstablishmentMaxQueueDepth
  *
  * SessionEstablishmentRateLimiter is used in SessionWorkflow if the following feature flag
@@ -95,12 +95,8 @@ class SessionEstablishmentRateLimiter {
 
     // Configuration Options
 
-    void setRefreshRatePerSec(double refreshRatePerSec) {
-        _rateLimiter.setRefreshRatePerSec(refreshRatePerSec);
-    }
-
-    void setBurstSize(double burstSize) {
-        _rateLimiter.setBurstSize(burstSize);
+    void updateRateParameters(double refreshRatePerSec, double burstSize) {
+        _rateLimiter.updateRateParameters(refreshRatePerSec, burstSize);
     }
 
     void setMaxQueueDepth(int64_t maxQueueDepth) {
diff --git a/src/mongo/transport/session_workflow_test.cpp b/src/mongo/transport/session_workflow_test.cpp
@@ -613,7 +613,8 @@ class ConnectionEstablishmentQueueingTest : public SessionWorkflowTest {
 TEST_F(ConnectionEstablishmentQueueingTest, RejectEstablishmentWhenQueueingDisabled) {
     RAIIServerParameterControllerForTest refreshRate{"ingressConnectionEstablishmentRatePerSec",
                                                      1.0};
-    RAIIServerParameterControllerForTest burstSize{"ingressConnectionEstablishmentBurstSize", 1};
+    RAIIServerParameterControllerForTest burstCapacitySecs{
+        "ingressConnectionEstablishmentBurstCapacitySecs", 1};
 
     // The first session gets a token successfully and calls sourceMessage.
     startSession();
@@ -643,7 +644,8 @@ TEST_F(ConnectionEstablishmentQueueingTest, RejectEstablishmentWhenQueueingDisab
 TEST_F(ConnectionEstablishmentQueueingTest, InterruptQueuedEstablishments) {
     RAIIServerParameterControllerForTest refreshRate{"ingressConnectionEstablishmentRatePerSec",
                                                      1.0};
-    RAIIServerParameterControllerForTest burstSize{"ingressConnectionEstablishmentBurstSize", 1};
+    RAIIServerParameterControllerForTest burstCapacitySecs{
+        "ingressConnectionEstablishmentBurstCapacitySecs", 1};
     RAIIServerParameterControllerForTest maxQueueDepth{
         "ingressConnectionEstablishmentMaxQueueDepth", 10};
     const auto initialAvailable = getConnectionStats()["available"].numberLong();
@@ -684,7 +686,8 @@ TEST_F(ConnectionEstablishmentQueueingTest, BypassQueueingEstablishment) {
         BSON("ranges" << BSONArray(BSON("0" << ip))));
     RAIIServerParameterControllerForTest refreshRate{"ingressConnectionEstablishmentRatePerSec",
                                                      1.0};
-    RAIIServerParameterControllerForTest burstSize{"ingressConnectionEstablishmentBurstSize", 1};
+    RAIIServerParameterControllerForTest burstCapacitySecs{
+        "ingressConnectionEstablishmentBurstCapacitySecs", 1};
 
     // The first session gets a token successfully and calls sourceMessage.
     startSession();
diff --git a/src/mongo/transport/transport_options.cpp b/src/mongo/transport/transport_options.cpp
@@ -146,13 +146,16 @@ Status forEachSessionManager(Callback&& updateFunc) try {
 
 Status onUpdateEstablishmentRefreshRate(int32_t newValue) {
     return forEachSessionManager([newValue](SessionManager* sm) {
-        sm->getSessionEstablishmentRateLimiter().setRefreshRatePerSec(newValue);
+        sm->getSessionEstablishmentRateLimiter().updateRateParameters(
+            newValue, newValue * gIngressConnectionEstablishmentBurstCapacitySecs.load());
     });
 }
 
-Status onUpdateEstablishmentBurstSize(int32_t newValue) {
-    return forEachSessionManager([newValue](SessionManager* sm) {
-        sm->getSessionEstablishmentRateLimiter().setBurstSize(newValue);
+Status onUpdateEstablishmentBurstCapacitySecs(double newValue) {
+    auto refreshRate = gIngressConnectionEstablishmentRatePerSec.load();
+    return forEachSessionManager([refreshRate, burstSize = newValue](SessionManager* sm) {
+        sm->getSessionEstablishmentRateLimiter().updateRateParameters(refreshRate,
+                                                                      refreshRate * burstSize);
     });
 }
 
diff --git a/src/mongo/transport/transport_options.h b/src/mongo/transport/transport_options.h
@@ -32,7 +32,7 @@
 namespace mongo::transport {
 Status onUpdateEstablishmentRefreshRate(int32_t newValue);
 
-Status onUpdateEstablishmentBurstSize(int32_t newValue);
+Status onUpdateEstablishmentBurstCapacitySecs(double newValue);
 
 Status onUpdateEstablishmentMaxQueueDepth(int32_t newValue);
 }  // namespace mongo::transport
diff --git a/src/mongo/transport/transport_options.idl b/src/mongo/transport/transport_options.idl
@@ -109,17 +109,18 @@ server_parameters:
     validator: {gte: 1}
     redact: false
 
-  ingressConnectionEstablishmentBurstSize:
+  ingressConnectionEstablishmentBurstCapacitySecs:
     description: >-
-        The maximum number of ingress connection establishments that will be admitted before rate-limiting 
-        kicks in (ie, the burst size of the bucket)
+        Describes how many seconds worth of unutilized rate limit can be stored away for use 
+        to admit additional connection establishment requests during periods where the rate 
+        limit is temporarily exceeded.
     set_at: [startup, runtime]
-    cpp_varname: gIngressConnectionEstablishmentBurstSize
-    cpp_vartype: Atomic<int32_t>
-    on_update: transport::onUpdateEstablishmentBurstSize
+    cpp_varname: gIngressConnectionEstablishmentBurstCapacitySecs
+    cpp_vartype: Atomic<double>
+    on_update: transport::onUpdateEstablishmentBurstCapacitySecs
     default:
-        expr: std::numeric_limits<int>::max()
-    validator: {gte: 1}
+        expr: std::numeric_limits<double>::max()
+    validator: {gt: 0}
     redact: false
 
   ingressConnectionEstablishmentMaxQueueDepth:
