feat(ratelimiter): add configurable blocking mode for API rate limiters (#6761)

- Add `rate.limiter.apiNonBlocking` switch (default false). When off, callers wait for a permit; when on, they reject immediately and shed load.
- Wire the switch through `RateLimiterConfig` → `Args` → `CommonParameter`; update `reference.conf` / `config.conf`.
- Add blocking `acquire()` paths on `IRateLimiter`, `GlobalRateLimiter`, and `QpsStrategy` / `IPQpsStrategy` / `GlobalPreemptibleStrategy`. Only the semaphore-based strategy is bounded (2s); the QPS-based paths use unbounded Guava `RateLimiter.acquire()`.
- Introduce `acquirePermit()` dispatcher (default method on `IRateLimiter`; static on `GlobalRateLimiter`) that picks blocking vs non-blocking based on the switch.
- Swap `tryAcquire` → `acquirePermit` at the `RateLimiterServlet` and `RateLimiterInterceptor` call sites; preserve per-endpoint-before-global ordering to avoid consuming global quota on per-endpoint rejection.
- Extract `loadIpLimiter()` in `GlobalRateLimiter` and `loadLimiter()` in `IPQpsStrategy` to share cache+exception handling between `tryAcquire` and `acquire`.
- Add unit tests covering dispatcher routing (both directions), acquire IP-before-global ordering, and IP-loader-failure fail-closed behaviour.

Author: xxo1shine

common/src/main/java/org/tron/common/parameter/CommonParameter.java

@@ -411,6 +411,9 @@ public class CommonParameter {
   @Setter
   public double rateLimiterDisconnect; // clearParam: 1.0
   @Getter
+  @Setter
+  public boolean rateLimiterApiNonBlocking = false;
+  @Getter
   public RocksDbSettings rocksDBCustomSettings;
   @Getter
   public GenesisBlock genesisBlock;

common/src/main/java/org/tron/core/config/args/RateLimiterConfig.java

@@ -21,6 +21,7 @@ public class RateLimiterConfig {
   private P2pRateLimitConfig p2p = new P2pRateLimitConfig();
   private List<HttpRateLimitItem> http = new ArrayList<>();
   private List<RpcRateLimitItem> rpc = new ArrayList<>();
+  private boolean apiNonBlocking = false;
 
   @Getter
   @Setter

common/src/main/resources/reference.conf

@@ -451,6 +451,7 @@ rate.limiter = {
   global.qps = 50000
   global.ip.qps = 10000
   global.api.qps = 1000
+  apiNonBlocking = false
 }
 
 seed.node = {

common/src/test/java/org/tron/core/config/args/RateLimiterConfigTest.java

@@ -1,6 +1,7 @@
 package org.tron.core.config.args;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
 
 import com.typesafe.config.Config;
@@ -29,6 +30,7 @@ public void testDefaults() {
     assertEquals(1.0, rl.getP2p().getDisconnect(), 0.001);
     assertTrue(rl.getHttp().isEmpty());
     assertTrue(rl.getRpc().isEmpty());
+    assertFalse(rl.isApiNonBlocking());
   }
 
   @Test
@@ -40,7 +42,8 @@ public void testFromConfig() {
             + " http = [{ component = TestServlet, strategy = QpsRateLimiterAdapter,"
             + "   paramString = \"qps=10\" }],"
             + " rpc = [{ component = TestRpc, strategy = GlobalPreemptibleAdapter,"
-            + "   paramString = \"permit=1\" }]"
+            + "   paramString = \"permit=1\" }],"
+            + " apiNonBlocking = true"
             + "}");
     RateLimiterConfig rl = RateLimiterConfig.fromConfig(config);
     assertEquals(100, rl.getGlobal().getQps());
@@ -50,5 +53,6 @@ public void testFromConfig() {
     assertEquals("TestServlet", rl.getHttp().get(0).getComponent());
     assertEquals(1, rl.getRpc().size());
     assertEquals("TestRpc", rl.getRpc().get(0).getComponent());
+    assertTrue(rl.isApiNonBlocking());
   }
 }

framework/src/main/java/org/tron/core/config/args/Args.java

@@ -328,6 +328,7 @@ private static void applyRateLimiterConfig(RateLimiterConfig rl) {
     PARAMETER.rateLimiterSyncBlockChain = rl.getP2p().getSyncBlockChain();
     PARAMETER.rateLimiterFetchInvData = rl.getP2p().getFetchInvData();
     PARAMETER.rateLimiterDisconnect = rl.getP2p().getDisconnect();
+    PARAMETER.rateLimiterApiNonBlocking = rl.isApiNonBlocking();
 
     // HTTP/RPC rate limiter items: convert bean lists to business objects
     RateLimiterInitialization initialization = new RateLimiterInitialization();

framework/src/main/java/org/tron/core/services/http/RateLimiterServlet.java

@@ -107,9 +107,10 @@ protected void service(HttpServletRequest req, HttpServletResponse resp)
     IRateLimiter rateLimiter = container.get(KEY_PREFIX_HTTP, getClass().getSimpleName());
 
     // Check per-endpoint first to avoid consuming global IP/QPS quota for requests
-    // that would be rejected by the per-endpoint limiter anyway.
-    boolean perEndpointAcquired = rateLimiter == null || rateLimiter.tryAcquire(runtimeData);
-    boolean acquireResource = perEndpointAcquired && GlobalRateLimiter.tryAcquire(runtimeData);
+    // that would be rejected by the per-endpoint limiter anyway. acquirePermit()
+    // chooses blocking or non-blocking semantics based on rate.limiter.apiNonBlocking.
+    boolean perEndpointAcquired = rateLimiter == null || rateLimiter.acquirePermit(runtimeData);
+    boolean acquireResource = perEndpointAcquired && GlobalRateLimiter.acquirePermit(runtimeData);
 
     String contextPath = req.getContextPath();
     String url = Strings.isNullOrEmpty(req.getServletPath())

framework/src/main/java/org/tron/core/services/ratelimiter/GlobalRateLimiter.java

@@ -23,21 +23,43 @@ public class GlobalRateLimiter {
   public static boolean tryAcquire(RuntimeData runtimeData) {
     String ip = runtimeData.getRemoteAddr();
     if (!Strings.isNullOrEmpty(ip)) {
-      RateLimiter r;
-      try {
-        // cache.get is atomic: only one loader executes per key under concurrent requests,
-        // preventing multiple RateLimiter instances from being created for the same IP.
-        r = cache.get(ip, () -> RateLimiter.create(IP_QPS));
-      } catch (Exception e) {
-        logger.warn("Failed to load IP rate limiter for {}, denying request: {}",
-            ip, e.getMessage());
+      RateLimiter r = loadIpLimiter(ip);
+      if (r == null || !r.tryAcquire()) {
         return false;
       }
-      if (!r.tryAcquire()) {
+    }
+    return rateLimiter.tryAcquire();
+  }
+
+  public static boolean acquire(RuntimeData runtimeData) {
+    String ip = runtimeData.getRemoteAddr();
+    if (!Strings.isNullOrEmpty(ip)) {
+      RateLimiter r = loadIpLimiter(ip);
+      if (r == null) {
         return false;
       }
+      r.acquire();
+    }
+    rateLimiter.acquire();
+    return true;
+  }
+
+  public static boolean acquirePermit(RuntimeData runtimeData) {
+    return Args.getInstance().isRateLimiterApiNonBlocking()
+        ? tryAcquire(runtimeData)
+        : acquire(runtimeData);
+  }
+
+  private static RateLimiter loadIpLimiter(String ip) {
+    try {
+      // cache.get is atomic: only one loader executes per key under concurrent requests,
+      // preventing multiple RateLimiter instances from being created for the same IP.
+      return cache.get(ip, () -> RateLimiter.create(IP_QPS));
+    } catch (Exception e) {
+      logger.warn("Failed to load IP rate limiter for {}, denying request: {}",
+          ip, e.getMessage());
+      return null;
     }
-    return rateLimiter.tryAcquire();
   }
 
 }

framework/src/main/java/org/tron/core/services/ratelimiter/RateLimiterInterceptor.java

@@ -108,9 +108,10 @@ public <ReqT, RespT> Listener<ReqT> interceptCall(ServerCall<ReqT, RespT> call,
 
     RuntimeData runtimeData = new RuntimeData(call);
     // Check per-endpoint first to avoid consuming global IP/QPS quota for requests
-    // that would be rejected by the per-endpoint limiter anyway.
-    boolean perEndpointAcquired = rateLimiter == null || rateLimiter.tryAcquire(runtimeData);
-    boolean acquireResource = perEndpointAcquired && GlobalRateLimiter.tryAcquire(runtimeData);
+    // that would be rejected by the per-endpoint limiter anyway. acquirePermit()
+    // chooses blocking or non-blocking semantics based on rate.limiter.apiNonBlocking.
+    boolean perEndpointAcquired = rateLimiter == null || rateLimiter.acquirePermit(runtimeData);
+    boolean acquireResource = perEndpointAcquired && GlobalRateLimiter.acquirePermit(runtimeData);
 
     if (!acquireResource) {
       // Release the per-endpoint permit when global rejected, to avoid semaphore leak.

framework/src/main/java/org/tron/core/services/ratelimiter/adapter/DefaultBaseQqsAdapter.java

@@ -15,4 +15,9 @@ public DefaultBaseQqsAdapter(String paramString) {
   public boolean tryAcquire(RuntimeData data) {
     return strategy.tryAcquire();
   }
+
+  @Override
+  public boolean acquire(RuntimeData data) {
+    return strategy.acquire();
+  }
 }

framework/src/main/java/org/tron/core/services/ratelimiter/adapter/GlobalPreemptibleAdapter.java

@@ -21,4 +21,8 @@ public boolean tryAcquire(RuntimeData data) {
     return strategy.tryAcquire();
   }
 
+  @Override
+  public boolean acquire(RuntimeData data) {
+    return strategy.acquire();
+  }
 }