You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2025/03/07 16:12:08 UTC

(tomcat) branch 9.0.x updated (d7b0d6236e -> f60933283e)

This is an automated email from the ASF dual-hosted git repository.

markt pushed a change to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


    from d7b0d6236e More skip.installer, remove unless in depends-only target
     new 6f65e9025b Refactor TimeBucketCounter to support alternative implementations
     new cfe887822e Refactor RateLimiter FastRateLimiter for extension
     new f60933283e Add an exact rate limit filter.

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../apache/catalina/filters/RateLimitFilter.java   |   7 +-
 .../org/apache/catalina/util/ExactRateLimiter.java |  68 ++++++++
 java/org/apache/catalina/util/FastRateLimiter.java |  75 +--------
 java/org/apache/catalina/util/RateLimiter.java     |   7 +-
 java/org/apache/catalina/util/RateLimiterBase.java | 155 +++++++++++++++++
 .../apache/catalina/util/TimeBucketCounter.java    | 185 +++++++--------------
 ...cketCounter.java => TimeBucketCounterBase.java} | 174 ++++++++++---------
 ...> TestRateLimitFilterWithExactRateLimiter.java} |  88 +++++-----
 webapps/docs/changelog.xml                         |   7 +
 webapps/docs/config/filter.xml                     |  30 +++-
 10 files changed, 450 insertions(+), 346 deletions(-)
 create mode 100644 java/org/apache/catalina/util/ExactRateLimiter.java
 create mode 100644 java/org/apache/catalina/util/RateLimiterBase.java
 copy java/org/apache/catalina/util/{TimeBucketCounter.java => TimeBucketCounterBase.java} (54%)
 copy test/org/apache/catalina/filters/{TestRateLimitFilter.java => TestRateLimitFilterWithExactRateLimiter.java} (75%)


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


(tomcat) 02/03: Refactor RateLimiter FastRateLimiter for extension

Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit cfe887822e1ef9fdcf4a00a05b97c3a65cd9d77d
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Mar 7 13:51:00 2025 +0000

    Refactor RateLimiter FastRateLimiter for extension
    
    Preparation for #794
---
 java/org/apache/catalina/util/FastRateLimiter.java |  76 +----------
 java/org/apache/catalina/util/RateLimiter.java     |   7 +-
 java/org/apache/catalina/util/RateLimiterBase.java | 145 +++++++++++++++++++++
 3 files changed, 154 insertions(+), 74 deletions(-)

diff --git a/java/org/apache/catalina/util/FastRateLimiter.java b/java/org/apache/catalina/util/FastRateLimiter.java
index 54f1f1e74e..17544c5d28 100644
--- a/java/org/apache/catalina/util/FastRateLimiter.java
+++ b/java/org/apache/catalina/util/FastRateLimiter.java
@@ -14,92 +14,28 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package org.apache.catalina.util;
 
 import java.util.concurrent.ScheduledExecutorService;
-import java.util.concurrent.atomic.AtomicInteger;
-
-import javax.servlet.FilterConfig;
-
-import org.apache.tomcat.util.threads.ScheduledThreadPoolExecutor;
 
 /**
  * A RateLimiter that compromises accuracy for speed in order to provide maximum throughput.
  */
-public class FastRateLimiter implements RateLimiter {
-
-    private static AtomicInteger index = new AtomicInteger();
-
-    TimeBucketCounter bucketCounter;
-
-    int duration;
-
-    int requests;
-
-    int actualRequests;
-
-    int actualDuration;
-
-    // Initial policy name can be rewritten by setPolicyName()
-    private String policyName = "fast-" + index.incrementAndGet();
-
-    @Override
-    public String getPolicyName() {
-        return policyName;
-    }
-
-    @Override
-    public void setPolicyName(String name) {
-        this.policyName = name;
-    }
+public class FastRateLimiter extends RateLimiterBase {
 
     @Override
-    public int getDuration() {
-        return actualDuration;
+    protected String getDefaultPolicyName() {
+        return "fast";
     }
 
-    @Override
-    public void setDuration(int duration) {
-        this.duration = duration;
-    }
-
-    @Override
-    public int getRequests() {
-        return actualRequests;
-    }
-
-    @Override
-    public void setRequests(int requests) {
-        this.requests = requests;
-    }
 
     @Override
-    public int increment(String ipAddress) {
-        return bucketCounter.increment(ipAddress);
+    protected TimeBucketCounterBase newCounterInstance(int duration, ScheduledExecutorService executorService) {
+        return new TimeBucketCounter(duration, executorService);
     }
 
-    @Override
-    public void destroy() {
-        bucketCounter.destroy();
-    }
-
-    @Override
-    public void setFilterConfig(FilterConfig filterConfig) {
-
-        ScheduledExecutorService executorService = (ScheduledExecutorService) filterConfig.getServletContext()
-                .getAttribute(ScheduledThreadPoolExecutor.class.getName());
-
-        if (executorService == null) {
-            executorService = new java.util.concurrent.ScheduledThreadPoolExecutor(1);
-        }
-
-        bucketCounter = new TimeBucketCounter(duration, executorService);
-        actualRequests = (int) Math.round(bucketCounter.getRatio() * requests);
-        actualDuration = bucketCounter.getActualDuration() / 1000;
-    }
 
     public TimeBucketCounter getBucketCounter() {
-        return bucketCounter;
+        return (TimeBucketCounter) bucketCounter;
     }
 }
diff --git a/java/org/apache/catalina/util/RateLimiter.java b/java/org/apache/catalina/util/RateLimiter.java
index 4b261d5073..84a5ef9a47 100644
--- a/java/org/apache/catalina/util/RateLimiter.java
+++ b/java/org/apache/catalina/util/RateLimiter.java
@@ -14,7 +14,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package org.apache.catalina.util;
 
 import javax.servlet.FilterConfig;
@@ -46,13 +45,13 @@ public interface RateLimiter {
     void setRequests(int requests);
 
     /**
-     * Increments the number of requests by the given ipAddress in the current time window.
+     * Increments the number of requests by the given identifier in the current time window.
      *
-     * @param ipAddress the ip address
+     * @param identifier the identifier for which the number of associated requests should be incremented
      *
      * @return the new value after incrementing
      */
-    int increment(String ipAddress);
+    int increment(String identifier);
 
     /**
      * Cleanup no longer needed resources.
diff --git a/java/org/apache/catalina/util/RateLimiterBase.java b/java/org/apache/catalina/util/RateLimiterBase.java
new file mode 100644
index 0000000000..7c34bd56c4
--- /dev/null
+++ b/java/org/apache/catalina/util/RateLimiterBase.java
@@ -0,0 +1,145 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.util;
+
+import java.util.Objects;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledThreadPoolExecutor;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import javax.servlet.FilterConfig;
+
+/**
+ * Base implementation of {@link RateLimiter}, provides runtime data maintenance mechanism monitor.
+ */
+public abstract class RateLimiterBase implements RateLimiter {
+
+    private static final AtomicInteger index = new AtomicInteger();
+
+    TimeBucketCounterBase bucketCounter;
+
+    int requests;
+    int actualRequests;
+
+    int duration;
+    int actualDuration;
+
+    // Initial policy name can be rewritten by setPolicyName()
+    private String policyName = null;
+
+    /*
+     * The self-owned utility executor, will be instantiated only when ScheduledThreadPoolExecutor is absent during
+     * filter configure phase.
+     */
+    private ScheduledThreadPoolExecutor internalExecutorService = null;
+
+    /**
+     * If policy name has not been specified, the first call of {@link #getPolicyName()} returns a auto-generated policy
+     * name using the default policy name as prefix and followed by auto-increase index.
+     *
+     * @return default policy name, as a prefix of auto-generated policy name.
+     */
+    protected abstract String getDefaultPolicyName();
+
+
+    @Override
+    public String getPolicyName() {
+        if (policyName == null) {
+            policyName = getDefaultPolicyName() + "-" + index.incrementAndGet();
+        }
+        return policyName;
+    }
+
+
+    @Override
+    public void setPolicyName(String name) {
+        Objects.requireNonNull(name);
+        this.policyName = name;
+    }
+
+
+    @Override
+    public int getDuration() {
+        return actualDuration;
+    }
+
+
+    @Override
+    public void setDuration(int duration) {
+        this.duration = duration;
+    }
+
+
+    @Override
+    public int getRequests() {
+        return actualRequests;
+    }
+
+
+    @Override
+    public void setRequests(int requests) {
+        this.requests = requests;
+    }
+
+
+    @Override
+    public int increment(String identifier) {
+        return bucketCounter.increment(identifier);
+    }
+
+
+    @Override
+    public void destroy() {
+        bucketCounter.destroy();
+        if (internalExecutorService != null) {
+            try {
+                internalExecutorService.shutdown();
+            } catch (SecurityException e) {
+                // ignore
+            }
+        }
+    }
+
+
+    /**
+     * Instantiate an instance of {@link TimeBucketCounterBase} for specific time bucket size. Concrete classes
+     * determine its counter policy by returning different implementation instances.
+     *
+     * @param duration        size of each time bucket in seconds
+     * @param utilityExecutor the executor
+     *
+     * @return counter instance of {@link TimeBucketCounterBase}
+     */
+    protected abstract TimeBucketCounterBase newCounterInstance(int duration, ScheduledExecutorService utilityExecutor);
+
+
+    @Override
+    public void setFilterConfig(FilterConfig filterConfig) {
+
+        ScheduledExecutorService executorService = (ScheduledExecutorService) filterConfig.getServletContext()
+                .getAttribute(ScheduledThreadPoolExecutor.class.getName());
+
+        if (executorService == null) {
+            internalExecutorService = new java.util.concurrent.ScheduledThreadPoolExecutor(1);
+            executorService = internalExecutorService;
+        }
+
+        bucketCounter = newCounterInstance(duration, executorService);
+        actualDuration = bucketCounter.getBucketDuration();
+        actualRequests = (int) Math.round(bucketCounter.getRatio() * requests);
+    }
+}


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


(tomcat) 01/03: Refactor TimeBucketCounter to support alternative implementations

Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit 6f65e9025b3d8aaa6c3c06f140d1962967ad1c8a
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Mar 7 13:27:58 2025 +0000

    Refactor TimeBucketCounter to support alternative implementations
    
    This is preparatory work for PR #794
---
 .../apache/catalina/util/TimeBucketCounter.java    | 185 +++++++--------------
 ...cketCounter.java => TimeBucketCounterBase.java} | 177 ++++++++++----------
 2 files changed, 145 insertions(+), 217 deletions(-)

diff --git a/java/org/apache/catalina/util/TimeBucketCounter.java b/java/org/apache/catalina/util/TimeBucketCounter.java
index 3b4726f7ff..78951623cc 100644
--- a/java/org/apache/catalina/util/TimeBucketCounter.java
+++ b/java/org/apache/catalina/util/TimeBucketCounter.java
@@ -14,122 +14,91 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package org.apache.catalina.util;
 
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ScheduledExecutorService;
-import java.util.concurrent.ScheduledFuture;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicInteger;
-
-import org.apache.juli.logging.Log;
-import org.apache.juli.logging.LogFactory;
-import org.apache.tomcat.util.res.StringManager;
 
 /**
- * This class maintains a thread safe hash map that has timestamp-based buckets followed by a string for a key, and a
- * counter for a value. each time the increment() method is called it adds the key if it does not exist, increments its
- * value and returns it. a maintenance thread cleans up keys that are prefixed by previous timestamp buckets.
+ * A fast counter that optimizes efficiency at the expense of approximate bucket indexing.
  */
-public class TimeBucketCounter {
-
-    private static final Log log = LogFactory.getLog(TimeBucketCounter.class);
-    private static final StringManager sm = StringManager.getManager(TimeBucketCounter.class);
-
-    /**
-     * Map to hold the buckets
-     */
-    private final ConcurrentHashMap<String,AtomicInteger> map = new ConcurrentHashMap<>();
+public class TimeBucketCounter extends TimeBucketCounterBase {
 
-    /**
-     * Milliseconds bucket size as a Power of 2 for bit shift math, e.g. 16 for 65_536ms which is about 1:05 minute
-     */
+    // Milliseconds bucket size as a Power of 2 for bit shift math, e.g. 16 for 65_536ms which is about 1:05 minute.
     private final int numBits;
 
-    /**
-     * Ratio of actual duration to config duration
-     */
+    // Ratio of actual duration to config duration
     private final double ratio;
 
-    /**
-     * The future allowing control of the background processor.
-     */
-    private ScheduledFuture<?> maintenanceFuture;
-    private ScheduledFuture<?> monitorFuture;
-    private final ScheduledExecutorService executorService;
-    private final long sleeptime;
 
-    /**
-     * Creates a new TimeBucketCounter with the specified lifetime.
-     *
-     * @param bucketDuration  duration in seconds, e.g. for 1 minute pass 60
-     * @param executorService the executor service which will be used to run the maintenance
-     */
     public TimeBucketCounter(int bucketDuration, ScheduledExecutorService executorService) {
+        super(getActualDuration(bucketDuration), executorService);
+        this.numBits = determineShiftBitsOfDuration(bucketDuration);
+        this.ratio = ratioToPowerOf2(bucketDuration * 1000);
+    }
 
-        this.executorService = executorService;
-
-        int durationMillis = bucketDuration * 1000;
-
-        int bits = 0;
-        int pof2 = nextPowerOf2(durationMillis);
-        int bitCheck = pof2;
-        while (bitCheck > 1) {
-            bitCheck = pof2 >> ++bits;
-        }
-
-        this.numBits = bits;
 
-        this.ratio = ratioToPowerOf2(durationMillis);
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Calculates the current time bucket index by shifting bits for fast division, e.g. shift 16 bits is the same as
+     * dividing by 65,536 which is about 1:05m.
+     */
+    @Override
+    public long getBucketIndex(long timestamp) {
+        return timestamp >> this.numBits;
+    }
 
-        int cleanupsPerBucketDuration = (durationMillis >= 60_000) ? 6 : 3;
-        sleeptime = durationMillis / cleanupsPerBucketDuration;
 
-        // Start our thread
-        if (sleeptime > 0) {
-            monitorFuture = executorService.scheduleWithFixedDelay(new MaintenanceMonitor(), 0, 60, TimeUnit.SECONDS);
-        }
+    public int getNumBits() {
+        return numBits;
     }
 
+
     /**
-     * Increments the counter for the passed identifier in the current time bucket and returns the new value.
-     *
-     * @param identifier an identifier for which we want to maintain count, e.g. IP Address
+     * The actual duration may differ from the configured duration because it is set to the next power of 2 value in
+     * order to perform very fast bit shift arithmetic.
      *
-     * @return the count within the current time bucket
+     * @return the actual bucket duration in milliseconds
      */
-    public final int increment(String identifier) {
-        String key = getCurrentBucketPrefix() + "-" + identifier;
-        AtomicInteger ai = map.computeIfAbsent(key, v -> new AtomicInteger());
-        return ai.incrementAndGet();
+    public int getActualDuration() {
+        return (int) Math.pow(2, getNumBits());
     }
 
+
     /**
-     * Calculates the current time bucket prefix by shifting bits for fast division, e.g. shift 16 bits is the same as
-     * dividing by 65,536 which is about 1:05m.
+     * Determines the bits of shift for the specific bucket duration in seconds, which used to figure out the correct
+     * bucket index.
+     *
+     * @param duration bucket duration in seconds
      *
-     * @return The current bucket prefix.
+     * @return bits to be shifted
      */
-    public final int getCurrentBucketPrefix() {
-        return (int) (System.currentTimeMillis() >> this.numBits);
+    protected static final int determineShiftBitsOfDuration(int duration) {
+        int bits = 0;
+        int pof2 = nextPowerOf2(duration * 1000);
+        int bitCheck = pof2;
+        while (bitCheck > 1) {
+            bitCheck = pof2 >> ++bits;
+        }
+        return bits;
     }
 
-    public int getNumBits() {
-        return numBits;
-    }
 
     /**
      * The actual duration may differ from the configured duration because it is set to the next power of 2 value in
      * order to perform very fast bit shift arithmetic.
      *
-     * @return the actual bucket duration in milliseconds
+     * @param duration in seconds
+     *
+     * @return the actual bucket duration in seconds
+     *
+     * @see FastTimeBucketCounter#determineShiftBitsOfDuration(int)
      */
-    public int getActualDuration() {
-        return (int) Math.pow(2, getNumBits());
+    private static int getActualDuration(int duration) {
+        return (int) (1L << determineShiftBitsOfDuration(duration)) / 1000;
     }
 
+
     /**
      * Returns the ratio between the configured duration param and the actual duration which will be set to the next
      * power of 2. We then multiply the configured requests param by the same ratio in order to compensate for the added
@@ -137,18 +106,25 @@ public class TimeBucketCounter {
      *
      * @return the ratio, e.g. 1.092 if the actual duration is 65_536 for the configured duration of 60_000
      */
+    @Override
     public double getRatio() {
         return ratio;
     }
 
+
     /**
      * Returns the ratio to the next power of 2 so that we can adjust the value.
+     *
+     * @param value of target duration in seconds
+     *
+     * @return the ratio to the next power of 2 so that we can adjust the value
      */
     static double ratioToPowerOf2(int value) {
         double nextPO2 = nextPowerOf2(value);
         return Math.round((1000 * nextPO2 / value)) / 1000d;
     }
 
+
     /**
      * Returns the next power of 2 given a value, e.g. 256 for 250, or 1024, for 1000.
      */
@@ -161,59 +137,12 @@ public class TimeBucketCounter {
         return valueOfHighestBit << 1;
     }
 
-    /**
-     * When we want to test a full bucket duration we need to sleep until the next bucket starts.
-     *
-     * @return the number of milliseconds until the next bucket
-     */
+
+    @Override
     public long getMillisUntilNextBucket() {
         long millis = System.currentTimeMillis();
         long nextTimeBucketMillis = ((millis + (long) Math.pow(2, numBits)) >> numBits) << numBits;
         long delta = nextTimeBucketMillis - millis;
         return delta;
     }
-
-    /**
-     * Sets isRunning to false to terminate the maintenance thread.
-     */
-    public void destroy() {
-        // Stop our thread
-        if (monitorFuture != null) {
-            monitorFuture.cancel(true);
-            monitorFuture = null;
-        }
-        if (maintenanceFuture != null) {
-            maintenanceFuture.cancel(true);
-            maintenanceFuture = null;
-        }
-    }
-
-    private class Maintenance implements Runnable {
-        @Override
-        public void run() {
-            String currentBucketPrefix = String.valueOf(getCurrentBucketPrefix());
-            ConcurrentHashMap.KeySetView<String,AtomicInteger> keys = map.keySet();
-            // remove obsolete keys
-            keys.removeIf(k -> !k.startsWith(currentBucketPrefix));
-        }
-    }
-
-    private class MaintenanceMonitor implements Runnable {
-        @Override
-        public void run() {
-            if (sleeptime > 0 && (maintenanceFuture == null || maintenanceFuture.isDone())) {
-                if (maintenanceFuture != null && maintenanceFuture.isDone()) {
-                    // There was an error executing the scheduled task, get it and log it
-                    try {
-                        maintenanceFuture.get();
-                    } catch (InterruptedException | ExecutionException e) {
-                        log.error(sm.getString("timebucket.maintenance.error"), e);
-                    }
-                }
-                maintenanceFuture = executorService.scheduleWithFixedDelay(new Maintenance(), sleeptime, sleeptime,
-                        TimeUnit.MILLISECONDS);
-            }
-        }
-    }
-
 }
diff --git a/java/org/apache/catalina/util/TimeBucketCounter.java b/java/org/apache/catalina/util/TimeBucketCounterBase.java
similarity index 54%
copy from java/org/apache/catalina/util/TimeBucketCounter.java
copy to java/org/apache/catalina/util/TimeBucketCounterBase.java
index 3b4726f7ff..b2b0bbee09 100644
--- a/java/org/apache/catalina/util/TimeBucketCounter.java
+++ b/java/org/apache/catalina/util/TimeBucketCounterBase.java
@@ -14,9 +14,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package org.apache.catalina.util;
 
+import java.util.Objects;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ScheduledExecutorService;
@@ -30,62 +30,42 @@ import org.apache.tomcat.util.res.StringManager;
 
 /**
  * This class maintains a thread safe hash map that has timestamp-based buckets followed by a string for a key, and a
- * counter for a value. each time the increment() method is called it adds the key if it does not exist, increments its
- * value and returns it. a maintenance thread cleans up keys that are prefixed by previous timestamp buckets.
+ * counter for an integer value. Each time the increment() method is called it adds the key if it does not exist,
+ * increments its value and returns it.
  */
-public class TimeBucketCounter {
+public abstract class TimeBucketCounterBase {
 
-    private static final Log log = LogFactory.getLog(TimeBucketCounter.class);
-    private static final StringManager sm = StringManager.getManager(TimeBucketCounter.class);
+    private static final Log log = LogFactory.getLog(TimeBucketCounterBase.class);
+    private static final StringManager sm = StringManager.getManager(TimeBucketCounterBase.class);
 
-    /**
-     * Map to hold the buckets
-     */
-    private final ConcurrentHashMap<String,AtomicInteger> map = new ConcurrentHashMap<>();
-
-    /**
-     * Milliseconds bucket size as a Power of 2 for bit shift math, e.g. 16 for 65_536ms which is about 1:05 minute
-     */
-    private final int numBits;
+    private static final String BUCKET_KEY_DELIMITER = "-";
 
-    /**
-     * Ratio of actual duration to config duration
-     */
-    private final double ratio;
+    // Map to hold the buckets
+    private final ConcurrentHashMap<String,AtomicInteger> map = new ConcurrentHashMap<>();
 
-    /**
-     * The future allowing control of the background processor.
-     */
+    // The future allowing control of the background processor.
     private ScheduledFuture<?> maintenanceFuture;
     private ScheduledFuture<?> monitorFuture;
     private final ScheduledExecutorService executorService;
     private final long sleeptime;
+    private int bucketDuration;
+
 
     /**
      * Creates a new TimeBucketCounter with the specified lifetime.
      *
      * @param bucketDuration  duration in seconds, e.g. for 1 minute pass 60
-     * @param executorService the executor service which will be used to run the maintenance
+     * @param executorService the executor service that will be used to run the maintenance task
+     *
+     * @throws NullPointerException if executorService is <code>null</code>.
      */
-    public TimeBucketCounter(int bucketDuration, ScheduledExecutorService executorService) {
-
+    public TimeBucketCounterBase(int bucketDuration, ScheduledExecutorService executorService) {
+        Objects.requireNonNull(executorService);
         this.executorService = executorService;
+        this.bucketDuration = bucketDuration;
 
-        int durationMillis = bucketDuration * 1000;
-
-        int bits = 0;
-        int pof2 = nextPowerOf2(durationMillis);
-        int bitCheck = pof2;
-        while (bitCheck > 1) {
-            bitCheck = pof2 >> ++bits;
-        }
-
-        this.numBits = bits;
-
-        this.ratio = ratioToPowerOf2(durationMillis);
-
-        int cleanupsPerBucketDuration = (durationMillis >= 60_000) ? 6 : 3;
-        sleeptime = durationMillis / cleanupsPerBucketDuration;
+        int cleanupsPerBucketDuration = (bucketDuration >= 60) ? 6 : 3;
+        sleeptime = bucketDuration * 1000 / cleanupsPerBucketDuration;
 
         // Start our thread
         if (sleeptime > 0) {
@@ -93,6 +73,23 @@ public class TimeBucketCounter {
         }
     }
 
+
+    /**
+     * @return bucketDuration in seconds
+     */
+    public int getBucketDuration() {
+        return bucketDuration;
+    }
+
+
+    /**
+     * Returns the ratio between the configured duration param and the actual duration.
+     *
+     * @return the ratio between the configured duration param and the actual duration.
+     */
+    public abstract double getRatio();
+
+
     /**
      * Increments the counter for the passed identifier in the current time bucket and returns the new value.
      *
@@ -101,83 +98,76 @@ public class TimeBucketCounter {
      * @return the count within the current time bucket
      */
     public final int increment(String identifier) {
-        String key = getCurrentBucketPrefix() + "-" + identifier;
+        String key = genKey(identifier);
         AtomicInteger ai = map.computeIfAbsent(key, v -> new AtomicInteger());
         return ai.incrementAndGet();
     }
 
+
     /**
-     * Calculates the current time bucket prefix by shifting bits for fast division, e.g. shift 16 bits is the same as
-     * dividing by 65,536 which is about 1:05m.
+     * Generates the key of timeBucket counter maps with the specific identifier, and the timestamp is implicitly
+     * equivalent to "now".
      *
-     * @return The current bucket prefix.
+     * @param identifier an identifier for which we want to maintain count
+     *
+     * @return key of timeBucket counter maps
      */
-    public final int getCurrentBucketPrefix() {
-        return (int) (System.currentTimeMillis() >> this.numBits);
+    protected final String genKey(String identifier) {
+        return genKey(identifier, System.currentTimeMillis());
     }
 
-    public int getNumBits() {
-        return numBits;
-    }
 
     /**
-     * The actual duration may differ from the configured duration because it is set to the next power of 2 value in
-     * order to perform very fast bit shift arithmetic.
+     * Generates the key of timeBucket counter maps with the specific identifier and timestamp.
+     *
+     * @param identifier of target request
+     * @param timestamp  when target request received
      *
-     * @return the actual bucket duration in milliseconds
+     * @return key of timeBucket counter maps
      */
-    public int getActualDuration() {
-        return (int) Math.pow(2, getNumBits());
+    protected final String genKey(String identifier, long timestamp) {
+        return getBucketIndex(timestamp) + BUCKET_KEY_DELIMITER + identifier;
     }
 
+
     /**
-     * Returns the ratio between the configured duration param and the actual duration which will be set to the next
-     * power of 2. We then multiply the configured requests param by the same ratio in order to compensate for the added
-     * time, if any.
+     * Calculate the bucket index for the specific timestamp.
+     *
+     * @param timestamp the specific timestamp in milliseconds
      *
-     * @return the ratio, e.g. 1.092 if the actual duration is 65_536 for the configured duration of 60_000
+     * @return prefix the bucket key prefix for the specific timestamp
      */
-    public double getRatio() {
-        return ratio;
-    }
+    protected abstract long getBucketIndex(long timestamp);
 
-    /**
-     * Returns the ratio to the next power of 2 so that we can adjust the value.
-     */
-    static double ratioToPowerOf2(int value) {
-        double nextPO2 = nextPowerOf2(value);
-        return Math.round((1000 * nextPO2 / value)) / 1000d;
-    }
 
     /**
-     * Returns the next power of 2 given a value, e.g. 256 for 250, or 1024, for 1000.
+     * Returns current bucket prefix
+     *
+     * @return bucket index
      */
-    static int nextPowerOf2(int value) {
-        int valueOfHighestBit = Integer.highestOneBit(value);
-        if (valueOfHighestBit == value) {
-            return value;
-        }
-
-        return valueOfHighestBit << 1;
+    public int getCurrentBucketPrefix() {
+        return (int) getBucketIndex(System.currentTimeMillis());
     }
 
+
     /**
      * When we want to test a full bucket duration we need to sleep until the next bucket starts.
+     * <p>
+     * <strong>WARNING:</strong> This method is used for test purpose.
      *
      * @return the number of milliseconds until the next bucket
+     *
+     * @deprecated Will be made package private in Tomcat 12 onwards.
      */
-    public long getMillisUntilNextBucket() {
-        long millis = System.currentTimeMillis();
-        long nextTimeBucketMillis = ((millis + (long) Math.pow(2, numBits)) >> numBits) << numBits;
-        long delta = nextTimeBucketMillis - millis;
-        return delta;
-    }
+    @Deprecated
+    public abstract long getMillisUntilNextBucket();
+
 
     /**
-     * Sets isRunning to false to terminate the maintenance thread.
+     * Stops threads created by this object and cleans up resources.
      */
     public void destroy() {
-        // Stop our thread
+        map.clear();
         if (monitorFuture != null) {
             monitorFuture.cancel(true);
             monitorFuture = null;
@@ -188,13 +178,23 @@ public class TimeBucketCounter {
         }
     }
 
+
+    /**
+     * Periodic evict, perform removal of obsolete bucket items. Absence of this operation may result in OOM after a
+     * long run.
+     */
+    public void periodicEvict() {
+        String currentBucketPrefix = String.valueOf(getCurrentBucketPrefix());
+        ConcurrentHashMap.KeySetView<String,AtomicInteger> keys = map.keySet();
+        // remove obsolete keys
+        keys.removeIf(k -> !k.startsWith(currentBucketPrefix));
+    }
+
+
     private class Maintenance implements Runnable {
         @Override
         public void run() {
-            String currentBucketPrefix = String.valueOf(getCurrentBucketPrefix());
-            ConcurrentHashMap.KeySetView<String,AtomicInteger> keys = map.keySet();
-            // remove obsolete keys
-            keys.removeIf(k -> !k.startsWith(currentBucketPrefix));
+            periodicEvict();
         }
     }
 
@@ -215,5 +215,4 @@ public class TimeBucketCounter {
             }
         }
     }
-
 }


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


(tomcat) 03/03: Add an exact rate limit filter.

Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit f60933283eb9268a3203102654ebabc717581505
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Mar 7 14:55:22 2025 +0000

    Add an exact rate limit filter.
    
    Based on PR #794 by Chenjp
---
 .../apache/catalina/filters/RateLimitFilter.java   |   7 +-
 .../org/apache/catalina/util/ExactRateLimiter.java |  68 +++++++
 java/org/apache/catalina/util/FastRateLimiter.java |   1 +
 java/org/apache/catalina/util/RateLimiterBase.java |  10 +
 .../catalina/util/TimeBucketCounterBase.java       |   3 -
 .../TestRateLimitFilterWithExactRateLimiter.java   | 211 +++++++++++++++++++++
 webapps/docs/changelog.xml                         |   7 +
 webapps/docs/config/filter.xml                     |  30 ++-
 8 files changed, 323 insertions(+), 14 deletions(-)

diff --git a/java/org/apache/catalina/filters/RateLimitFilter.java b/java/org/apache/catalina/filters/RateLimitFilter.java
index d362aca766..89a48cb70f 100644
--- a/java/org/apache/catalina/filters/RateLimitFilter.java
+++ b/java/org/apache/catalina/filters/RateLimitFilter.java
@@ -47,8 +47,11 @@ import org.apache.tomcat.util.res.StringManager;
  * so it converts some configured values to more efficient values. For example, a configuration of a 60 seconds time
  * bucket is converted to 65.536 seconds. That allows for very fast bucket calculation using bit shift arithmetic. In
  * order to remain true to the user intent, the configured number of requests is then multiplied by the same ratio, so a
- * configuration of 100 Requests per 60 seconds, has the real values of 109 Requests per 65 seconds. You can specify a
- * different class as long as it implements the <code>org.apache.catalina.util.RateLimiter</code> interface.
+ * configuration of 100 Requests per 60 seconds, has the real values of 109 Requests per 65 seconds. An alternative
+ * implementation, <code>org.apache.catalina.util.ExactRateLimiter</code>, is intended to provide a less efficient but
+ * more accurate control, whose effective duration in seconds and number of requests configuration are consist with the
+ * user declared. You can specify a different class as long as it implements the
+ * <code>org.apache.catalina.util.RateLimiter</code> interface.
  * </p>
  * <p>
  * It is common to set up different restrictions for different URIs. For example, a login page or authentication script
diff --git a/java/org/apache/catalina/util/ExactRateLimiter.java b/java/org/apache/catalina/util/ExactRateLimiter.java
new file mode 100644
index 0000000000..a1b8c9190f
--- /dev/null
+++ b/java/org/apache/catalina/util/ExactRateLimiter.java
@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.util;
+
+import java.util.concurrent.ScheduledExecutorService;
+
+/**
+ * A RateLimiter that compromises efficiency for accuracy in order to provide exact rate limiting.
+ */
+public class ExactRateLimiter extends RateLimiterBase {
+
+    @Override
+    protected String getDefaultPolicyName() {
+        return "exact";
+    }
+
+
+    @Override
+    protected TimeBucketCounterBase newCounterInstance(int duration, ScheduledExecutorService executorService) {
+        return new ExactTimeBucketCounter(duration, executorService);
+    }
+
+
+    /**
+     * An accurate counter with exact bucket index, but slightly less efficient than another fast counter provided with
+     * the {@link FastRateLimiter}.
+     */
+    class ExactTimeBucketCounter extends TimeBucketCounterBase {
+
+        ExactTimeBucketCounter(int bucketDuration, ScheduledExecutorService executorService) {
+            super(bucketDuration, executorService);
+        }
+
+        @Override
+        public long getBucketIndex(long timestamp) {
+            return (timestamp / 1000) / getBucketDuration();
+        }
+
+        @Override
+        public double getRatio() {
+            // Actual value is exactly the same as declared
+            return 1.0d;
+        }
+
+        @Override
+        public long getMillisUntilNextBucket() {
+            long millis = System.currentTimeMillis();
+
+            long nextTimeBucketMillis = (getBucketIndex(millis) + 1) * getBucketDuration() * 1000;
+            long delta = nextTimeBucketMillis - millis;
+            return delta;
+        }
+    }
+}
diff --git a/java/org/apache/catalina/util/FastRateLimiter.java b/java/org/apache/catalina/util/FastRateLimiter.java
index 17544c5d28..dc7b9d5249 100644
--- a/java/org/apache/catalina/util/FastRateLimiter.java
+++ b/java/org/apache/catalina/util/FastRateLimiter.java
@@ -35,6 +35,7 @@ public class FastRateLimiter extends RateLimiterBase {
     }
 
 
+    @Override
     public TimeBucketCounter getBucketCounter() {
         return (TimeBucketCounter) bucketCounter;
     }
diff --git a/java/org/apache/catalina/util/RateLimiterBase.java b/java/org/apache/catalina/util/RateLimiterBase.java
index 7c34bd56c4..b8e3ded729 100644
--- a/java/org/apache/catalina/util/RateLimiterBase.java
+++ b/java/org/apache/catalina/util/RateLimiterBase.java
@@ -142,4 +142,14 @@ public abstract class RateLimiterBase implements RateLimiter {
         actualDuration = bucketCounter.getBucketDuration();
         actualRequests = (int) Math.round(bucketCounter.getRatio() * requests);
     }
+
+
+    /**
+     * Returns the internal instance of {@link TimeBucketCounterBase}.
+     *
+     * @return instance of {@link TimeBucketCounterBase}
+     */
+    public TimeBucketCounterBase getBucketCounter() {
+        return bucketCounter;
+    }
 }
diff --git a/java/org/apache/catalina/util/TimeBucketCounterBase.java b/java/org/apache/catalina/util/TimeBucketCounterBase.java
index b2b0bbee09..4679a41f0a 100644
--- a/java/org/apache/catalina/util/TimeBucketCounterBase.java
+++ b/java/org/apache/catalina/util/TimeBucketCounterBase.java
@@ -156,10 +156,7 @@ public abstract class TimeBucketCounterBase {
      * <strong>WARNING:</strong> This method is used for test purpose.
      *
      * @return the number of milliseconds until the next bucket
-     *
-     * @deprecated Will be made package private in Tomcat 12 onwards.
      */
-    @Deprecated
     public abstract long getMillisUntilNextBucket();
 
 
diff --git a/test/org/apache/catalina/filters/TestRateLimitFilterWithExactRateLimiter.java b/test/org/apache/catalina/filters/TestRateLimitFilterWithExactRateLimiter.java
new file mode 100644
index 0000000000..a970f4548c
--- /dev/null
+++ b/test/org/apache/catalina/filters/TestRateLimitFilterWithExactRateLimiter.java
@@ -0,0 +1,211 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.filters;
+
+import java.io.IOException;
+
+import javax.servlet.FilterChain;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import org.apache.catalina.Context;
+import org.apache.catalina.filters.TestRemoteIpFilter.MockFilterChain;
+import org.apache.catalina.filters.TestRemoteIpFilter.MockHttpServletRequest;
+import org.apache.catalina.startup.Tomcat;
+import org.apache.catalina.startup.TomcatBaseTest;
+import org.apache.catalina.util.ExactRateLimiter;
+import org.apache.tomcat.unittest.TesterResponse;
+import org.apache.tomcat.util.descriptor.web.FilterDef;
+import org.apache.tomcat.util.descriptor.web.FilterMap;
+
+public class TestRateLimitFilterWithExactRateLimiter extends TomcatBaseTest {
+    private void testRateLimitWith1Clients(boolean exposeHeaders, boolean enforce) throws Exception {
+
+        int bucketRequests = 40;
+        int bucketDuration = 4;
+
+        FilterDef filterDef = new FilterDef();
+        filterDef.addInitParameter("bucketRequests", String.valueOf(bucketRequests));
+        filterDef.addInitParameter("bucketDuration", String.valueOf(bucketDuration));
+        filterDef.addInitParameter("enforce", String.valueOf(enforce));
+        filterDef.addInitParameter("exposeHeaders", String.valueOf(exposeHeaders));
+        filterDef.addInitParameter("rateLimitClassName", "org.apache.catalina.util.ExactRateLimiter");
+
+        Tomcat tomcat = getTomcatInstance();
+        Context root = tomcat.addContext("", TEMP_DIR);
+
+        MockFilterChain filterChain = new MockFilterChain();
+        RateLimitFilter rateLimitFilter = testRateLimitFilter(filterDef, root);
+        tomcat.start();
+
+        ExactRateLimiter exactRateLimiter = (ExactRateLimiter) rateLimitFilter.rateLimiter;
+
+        int allowedRequests = exactRateLimiter.getRequests();
+        long sleepTime = exactRateLimiter.getBucketCounter().getMillisUntilNextBucket();
+        System.out.printf("Sleeping %d millis for the next time bucket to start\n", Long.valueOf(sleepTime));
+        Thread.sleep(sleepTime);
+
+        TestClient tc1 = new TestClient(rateLimitFilter, filterChain, "10.20.20.5", 50, 5); // TPS: 5
+        TestClient tc2 = new TestClient(rateLimitFilter, filterChain, "10.20.20.10", 100, 10); // TPS: 10
+
+        TestClient tc3 = new TestClient(rateLimitFilter, filterChain, "10.20.20.20", 200, 20); // TPS: 20
+        TestClient tc4 = new TestClient(rateLimitFilter, filterChain, "10.20.20.40", 400, 40); // TPS: 40
+        tc1.join();
+        tc2.join();
+        tc3.join();
+        tc4.join();
+        Assert.assertEquals(200, tc1.results[24]); // only 25 requests made in 5 seconds, all allowed
+
+        Assert.assertEquals(200, tc2.results[49]); // only 50 requests made in 5 seconds, all allowed
+
+        Assert.assertEquals(200, tc3.results[39]); // first allowedRequests allowed
+
+        if (enforce) {
+            Assert.assertEquals(429, tc3.results[allowedRequests]); // subsequent requests dropped
+        } else {
+            Assert.assertEquals(200, tc3.results[allowedRequests]);
+        }
+
+        Assert.assertEquals(200, tc4.results[allowedRequests - 1]); // first allowedRequests allowed
+
+        if (enforce) {
+            Assert.assertEquals(429, tc4.results[allowedRequests]); // subsequent requests dropped
+        } else {
+            Assert.assertEquals(200, tc4.results[allowedRequests]);
+        }
+
+        if (exposeHeaders) {
+            Assert.assertTrue(tc3.rlpHeader[24].contains("q=" + allowedRequests));
+            Assert.assertTrue(tc3.rlpHeader[allowedRequests].contains("q=" + allowedRequests));
+            if (enforce) {
+                Assert.assertTrue(tc3.rlHeader[24].contains("r="));
+                Assert.assertFalse(tc3.rlHeader[24].contains("r=0"));
+                Assert.assertTrue(tc3.rlHeader[allowedRequests].contains("r=0"));
+            }
+        } else {
+            Assert.assertTrue(tc3.rlpHeader[24] == null);
+            Assert.assertTrue(tc3.rlHeader[24] == null);
+            Assert.assertTrue(tc3.rlpHeader[allowedRequests] == null);
+            Assert.assertTrue(tc3.rlHeader[allowedRequests] == null);
+        }
+        tomcat.stop();
+    }
+
+    @Test
+    public void testExposeHeaderAndRerferenceRateLimitWith4Clients() throws Exception {
+        testRateLimitWith1Clients(true, false);
+    }
+
+    @Test
+    public void testUnexposeHeaderAndRerferenceRateLimitWith4Clients() throws Exception {
+        testRateLimitWith1Clients(false, false);
+    }
+
+    @Test
+    public void testExposeHeaderAndEnforceRateLimitWith4Clients() throws Exception {
+        testRateLimitWith1Clients(true, true);
+    }
+
+    @Test
+    public void testUnexposeHeaderAndEnforceRateLimitWith4Clients() throws Exception {
+        testRateLimitWith1Clients(false, true);
+    }
+
+    private RateLimitFilter testRateLimitFilter(FilterDef filterDef, Context root) {
+
+        RateLimitFilter rateLimitFilter = new RateLimitFilter();
+        filterDef.setFilterClass(RateLimitFilter.class.getName());
+        filterDef.setFilter(rateLimitFilter);
+        filterDef.setFilterName(RateLimitFilter.class.getName());
+        root.addFilterDef(filterDef);
+
+        FilterMap filterMap = new FilterMap();
+        filterMap.setFilterName(RateLimitFilter.class.getName());
+        filterMap.addURLPatternDecoded("*");
+        root.addFilterMap(filterMap);
+
+        return rateLimitFilter;
+    }
+
+    static class TestClient extends Thread {
+        RateLimitFilter filter;
+        FilterChain filterChain;
+        String ip;
+
+        int requests;
+        int sleep;
+
+        int[] results;
+        volatile String[] rlpHeader;
+        volatile String[] rlHeader;
+
+        TestClient(RateLimitFilter filter, FilterChain filterChain, String ip, int requests, int rps) {
+            this.filter = filter;
+            this.filterChain = filterChain;
+            this.ip = ip;
+            this.requests = requests;
+            this.sleep = 1000 / rps;
+            this.results = new int[requests];
+            this.rlpHeader = new String[requests];
+            this.rlHeader = new String[requests];
+            super.setDaemon(true);
+            super.start();
+        }
+
+        @Override
+        public void run() {
+            try {
+                for (int i = 0; i < requests; i++) {
+                    MockHttpServletRequest request = new MockHttpServletRequest();
+                    request.setRemoteAddr(ip);
+                    TesterResponse response = new TesterResponseWithStatus();
+                    response.setRequest(request);
+                    filter.doFilter(request, response, filterChain);
+                    results[i] = response.getStatus();
+
+                    rlpHeader[i] = response.getHeader(RateLimitFilter.HEADER_RATE_LIMIT_POLICY);
+                    rlHeader[i] = response.getHeader(RateLimitFilter.HEADER_RATE_LIMIT);
+
+                    if (results[i] != 200) {
+                        break;
+                    }
+                    sleep(sleep);
+                }
+            } catch (Exception ex) {
+                ex.printStackTrace();
+            }
+        }
+    }
+
+    static class TesterResponseWithStatus extends TesterResponse {
+
+        int status = 200;
+        String message = "OK";
+
+        @Override
+        public void sendError(int status, String message) throws IOException {
+            this.status = status;
+            this.message = message;
+        }
+
+        @Override
+        public int getStatus() {
+            return status;
+        }
+    }
+}
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 63c38b2af5..8e17241f3e 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -111,6 +111,13 @@
         Return 400 if the amount of content sent for a partial PUT is
         inconsistent with the range that was specified. (remm)
       </fix>
+      <add>
+        Add a new <code>RateLimiter</code> implementation,
+        <code>org.apache.catalina.util.ExactRateLimiter</code>, that can be used
+        with <code>org.apache.catalina.filters.RateLimitFilter</code> to provide
+        rate limit based on the exact values configured. Based on pull request
+        <pr>794</pr> by Chenjp. (markt)
+      </add>
     </changelog>
   </subsection>
 </section>
diff --git a/webapps/docs/config/filter.xml b/webapps/docs/config/filter.xml
index 2c74dd907b..89be25eb61 100644
--- a/webapps/docs/config/filter.xml
+++ b/webapps/docs/config/filter.xml
@@ -1022,13 +1022,21 @@ FINE: Request "/docs/config/manager.html" with response status "200"
     from that IP are dropped with a &quot;429 Too many requests&quot; response
     until the bucket time ends and a new bucket starts.</p>
 
-    <p>The filter is optimized for efficiency and low overhead, so it converts
-    some configured values to more efficient values. For example, a configuration
-    of a 60 seconds time bucket is converted to 65.536 seconds. That allows
-    for very fast bucket calculation using bit shift arithmetic. In order to remain
-    true to the user intent, the configured number of requests is then multiplied
-    by the same ratio, so a configuration of 100 Requests per 60 seconds, has the
-    real values of 109 Requests per 65 seconds.</p>
+    <p>The RateLimiter implementation can be set via the <code>rateLimitClassName</code>
+    init param. The default implementation,
+    <code>org.apache.catalina.util.FastRateLimiter</code>, is optimized for
+    efficiency and low overhead so it converts some configured values to more
+    efficient values. For example, a configuration of a 60 seconds time bucket
+    is converted to 65.536 seconds. That allows for very fast bucket calculation
+    using bit shift arithmetic. In order to remain true to the user intent, the
+    configured number of requests is then multiplied by the same ratio, so a
+    configuration of 100 Requests per 60 seconds, has the real values of 109
+    Requests per 65 seconds. An alternative implementation,
+    <code>org.apache.catalina.util.ExactRateLimiter</code>, is intended to
+    provide a less efficient but more accurate control, whose effective duration
+    in seconds and number of requests allowed are consist with the configured
+    values. You can specify a different class as long as it implements the
+    <code>org.apache.catalina.util.RateLimiter</code> interface.</p>
 
     <p>It is common to set up different restrictions for different URIs.
     For example, a login page or authentication script is typically expected
@@ -1100,8 +1108,12 @@ FINE: Request "/docs/config/manager.html" with response status "200"
       </attribute>
 
       <attribute name="rateLimitClassName" required="false">
-        <p>The full class name of an implementation of the RateLimiter interface.
-        Default is &quot;org.apache.catalina.util.FastRateLimiter&quot;.</p>
+        <p>The full class name of an implementation of the RateLimiter
+        interface. Default is
+        &quot;org.apache.catalina.util.FastRateLimiter&quot;, which is optimized
+        for efficiency. If you need exact rate limiting and can accept a small
+        decrease in efficiency, you can use
+        &quot;org.apache.catalina.util.ExactRateLimiter&quot; instead.</p>
       </attribute>
 
       <attribute name="statusCode" required="false">


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org