Add CIDR-based Global IP Rate Limiting for APIs

Rationale

Current Rate Limiting Model

Java-Tron currently implements rate limiting as follows:

Global Limits

• global.qps: system-wide QPS limit
• global.ip.qps: per-IP global QPS limit (single unified value)



Interface-Level Limits

Each API endpoint can be configured independently:

• Maximum concurrent connections
• API-level QPS
• API-level per-IP QPS

Limitations

Although the system currently supports per-IP global rate limiting (global.ip.qps), it has the following limitations:

• Only a single unified quota is supported
 All IPs share the same global per-IP QPS, making it impossible to:
  • Reduce QPS for specific suspicious IPs
  • Increase QPS for allowlisted IPs
  • Apply stricter rules for certain sources

• No CIDR/subnet-level control
 Currently, only single-IP granularity is supported, so it cannot:
  • Rate-limit entire cloud provider subnets
  • Limit proxy pool ranges
  • Apply restrictions on specific ISP exit ranges
  • Control IPv6 /64 subnets

Root Cause

The core assumption of the current model is: 
"Uniform standards for every individual IP."
However, modern network environments challenge this assumption:

• NAT: One IP ≠ one user
• Cloud servers: IPs can be changed cheaply
• Proxy pools: IPs rotate quickly
• IPv6: /64 subnet addresses are practically unlimited


Malicious traffic typically originates from "IP Clusters" rather than isolated addresses. Consequently, the current system is unable to define or enforce granular policies such as:

• Limit subnet X to an aggregate 100 QPS
• Allow VIP client Y up to 5000 QPS
• Throttle suspicious IP Z to 10 QPS

In other words, without subnet-aware or differentiated policies, the single-IP rate limit model is ineffective against distributed sources of traffic.

Summary

Currently, Java-Tron supports a single global per-IP limit, but it lacks:

• Fine-grained IP policy control


• Subnet-level rate limiting


• Differentiated quotas based on source



Proposal: Introduce CIDR-based global IP rate limit rules to enhance system security and flexibility in complex network environments.

Implementation

Proposal

Add support for global rate limiting based on IP/CIDR.

Example configuration:

rate.limiter.ipQpsRules = [
 {
   "cidr": "1.2.3.4/32",
   "qps": 1
 },
 {
   "cidr": "5.6.7.0/24",
   "qps": 50
 },
 {
   "cidr": "2408:abcd::/48",
   "qps": 200
 }
]

Matching Logic

Longest Prefix Match (LPM) is recommended to select the most specific rule.

Security Benefits

The introduction of CIDR-based tiered rate limiting provides several key security enhancements for java-tron:

• Enables fine-grained traffic control


• Rapidly throttle malicious source subnets


• Customized Quotas for allowlisted / VIP subnets 


• Enhanced IPv6 Abuse Resistance 


• Avoid conflicts or dilemmas caused by a single global.ip.qps setting

Start by locating the implementation and configuration handling for global.ip.qps, global.ip.qps, and rate.limiter.ipQpsRules. Review how existing global and per-IP limits are tested, then define completion around IPv4/IPv6 CIDR rules, longest-prefix matching, and differentiated quotas being covered by tests.