Merge pull request #11424 from IQSS/11413-rate-limiting-statistics-api

Adding rate limiting statistics api

Author: ofahimIQSS

doc/release-notes/11413-rate-limiting-statistics-api.md

@@ -0,0 +1,8 @@
+### Rate Limiting Statistics API
+
+CSV dump of Rate Limiting Cache
+
+curl http://localhost:8080/api/admin/rateLimitStats
+curl http://localhost:8080/api/admin/rateLimitStats?deltaMinutesFilter=10
+
+See also [the guides](https://dataverse-guide--11359.org.readthedocs.build/en/11359/admin/rate_limiting.html), #11413, and #11359.

doc/sphinx-guides/source/admin/index.rst

@@ -30,6 +30,7 @@ This guide documents the functionality only available to superusers (such as "da
    mail-groups
    collectionquotas
    monitoring
+   rate-limiting
    reporting-tools-and-queries
    maintenance
    backups

doc/sphinx-guides/source/admin/rate-limiting.rst

@@ -0,0 +1,47 @@
+Rate Limiting
+=============
+
+.. contents:: Contents:
+	:local:
+
+Configuration
+-------------
+
+Rate limiting is used to prevent users from over taxing the system either deliberately or by runaway automated processes.
+Rate limiting can be configured on a tier level with tier 0 being reserved for guest users and tiers 1-any for authenticated users. New users are defaulted to tier 1.
+Superuser accounts are exempt from rate limiting.
+Rate limits can be imposed on command APIs by configuring the tier, the command, and the hourly limit in the database.
+Two database settings configure the rate limiting.
+Note: If either of these settings exist in the database rate limiting will be enabled (note that a Payara restart is required for the :RateLimitingDefaultCapacityTiers setting to take effect). If neither setting exists rate limiting is disabled.
+
+- :RateLimitingDefaultCapacityTiers is the number of calls allowed per hour if the specific command is not configured. The values represent the number of calls per hour per user for tiers 0,1,...
+  A value of -1 can be used to signify no rate limit. Tiers not specified in this setting will default to `-1` (No Limit). I.e., -d "10000" is equivalent to -d "10000,-1,-1,..."
+
+.. code-block:: bash
+
+  curl http://localhost:8080/api/admin/settings/:RateLimitingDefaultCapacityTiers -X PUT -d '10000,20000'
+
+- :RateLimitingCapacityByTierAndAction is a JSON object specifying the rate by tier and a list of actions (commands). This allows for more control over the rate limit of individual API command calls.
+  In the following example, calls made by a guest user (tier 0) for API GetLatestPublishedDatasetVersionCommand is further limited to only 10 calls per hour, while an authenticated user (tier 1) will be able to make 30 calls per hour to the same API.
+
+:download:`rate-limit-actions.json </_static/installation/files/examples/rate-limit-actions-setting.json>`  Example JSON for RateLimitingCapacityByTierAndAction
+
+.. code-block:: bash
+
+  curl http://localhost:8080/api/admin/settings/:RateLimitingCapacityByTierAndAction -X PUT -d '[{"tier": 0, "limitPerHour": 10, "actions": ["GetLatestPublishedDatasetVersionCommand", "GetPrivateUrlCommand", "GetDatasetCommand", "GetLatestAccessibleDatasetVersionCommand"]}, {"tier": 0, "limitPerHour": 1, "actions": ["CreateGuestbookResponseCommand", "UpdateDatasetVersionCommand", "DestroyDatasetCommand", "DeleteDataFileCommand", "FinalizeDatasetPublicationCommand", "PublishDatasetCommand"]}, {"tier": 1, "limitPerHour": 30, "actions": ["CreateGuestbookResponseCommand", "GetLatestPublishedDatasetVersionCommand", "GetPrivateUrlCommand", "GetDatasetCommand", "GetLatestAccessibleDatasetVersionCommand", "UpdateDatasetVersionCommand", "DestroyDatasetCommand", "DeleteDataFileCommand", "FinalizeDatasetPublicationCommand", "PublishDatasetCommand"]}]'
+
+Statistics
+----------
+
+In order to monitor the rate limiting cache for investigative purposes there is a stats endpoint which returns CSV formatted text.
+
+The CSV contains multiple lists.
+
+- The first list contains the username:command, and number of tokens remaining. This list is sorted by the values and has the header "#<username>:<command>, <available tokens>".
+
+- The second list contains username:command, last updated timestamp in minutes, and delta minutes before now. The header for this list is "#<username>:<command>, <timestamp>, <delta minutes> ## deltaMinutesFilter=1". This list can be filtered to show only the entries with updates within the deltaMinutesFilter requested. ("## deltaMinutesFilter=n" will be added to the header when the filter is included in the call.
+
+.. code-block:: bash
+
+  curl http://localhost:8080/api/admin/rateLimitStats
+  curl http://localhost:8080/api/admin/rateLimitStats?deltaMinutesFilter=10

src/main/java/edu/harvard/iq/dataverse/api/Admin.java

@@ -19,6 +19,8 @@
 import edu.harvard.iq.dataverse.api.auth.AuthRequired;
 import edu.harvard.iq.dataverse.settings.JvmSettings;
 import edu.harvard.iq.dataverse.util.StringUtil;
+import edu.harvard.iq.dataverse.util.cache.CacheFactoryBean;
+import edu.harvard.iq.dataverse.util.cache.RateLimitUtil;
 import edu.harvard.iq.dataverse.util.json.NullSafeJsonBuilder;
 import edu.harvard.iq.dataverse.validation.EMailValidator;
 import edu.harvard.iq.dataverse.EjbDataverseEngine;
@@ -183,6 +185,8 @@ public class Admin extends AbstractApiBean {
     BannerMessageServiceBean bannerMessageService;
     @EJB
     TemplateServiceBean templateService;
+    @EJB
+    CacheFactoryBean cacheFactory;
 
     // Make the session available
     @Inject
@@ -2717,4 +2721,22 @@ public Response getAuditFiles(@Context ContainerRequestContext crc,
 
         return ok(jsonObjectBuilder);
     }
+
+    @GET
+    @AuthRequired
+    @Path("/rateLimitStats")
+    @Produces("text/csv")
+    public Response rateLimitStats(@Context ContainerRequestContext crc,
+                                   @QueryParam("deltaMinutesFilter") Long deltaMinutesFilter) {
+        try {
+            AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
+            if (!user.isSuperuser()) {
+                return error(Response.Status.FORBIDDEN, "Superusers only.");
+            }
+        } catch (WrappedResponse wr) {
+            return wr.getResponse();
+        }
+        String csvData = cacheFactory.getStats(CacheFactoryBean.RATE_LIMIT_CACHE, deltaMinutesFilter != null ? String.valueOf(deltaMinutesFilter) : null);
+        return Response.ok(csvData).header("Content-Disposition", "attachment; filename=\"data.csv\"").build();
+    }
 }

src/main/java/edu/harvard/iq/dataverse/util/cache/CacheFactoryBean.java

@@ -13,7 +13,6 @@
 import javax.cache.CacheManager;
 import javax.cache.configuration.CompleteConfiguration;
 import javax.cache.configuration.MutableConfiguration;
-import javax.cache.spi.CachingProvider;
 import java.util.logging.Logger;
 
 @Singleton
@@ -26,8 +25,6 @@ public class CacheFactoryBean implements java.io.Serializable {
     SystemConfig systemConfig;
     @Inject
     CacheManager manager;
-    @Inject
-    CachingProvider provider;
     public final static String RATE_LIMIT_CACHE = "rateLimitCache";
 
     @PostConstruct
@@ -60,4 +57,10 @@ public boolean checkRate(User user, Command command) {
             return (!RateLimitUtil.rateLimited(rateLimitCache, cacheKey, capacity));
         }
     }
+    public String getStats(String cacheType, String filter) {
+        if (RATE_LIMIT_CACHE.equals(cacheType)) {
+            return RateLimitUtil.getStats(rateLimitCache, filter);
+        }
+        return "";
+    }
 }

src/main/java/edu/harvard/iq/dataverse/util/cache/RateLimitUtil.java

@@ -9,10 +9,7 @@
 import jakarta.json.bind.JsonbException;
 
 import javax.cache.Cache;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.logging.Logger;
@@ -132,6 +129,33 @@ static void getRateLimitsFromJson(SystemConfig systemConfig) {
             }
         }
     }
+    static String getStats(final Cache<String, String> rateLimitCache, String filter) {
+        StringBuilder sb1 = new StringBuilder(); // available tokens list
+        StringBuilder sb2 = new StringBuilder(); // updated cache list
+        long currentTime = System.currentTimeMillis() / 60000L; // convert to minutes
+        Long deltaMinutesFilter = filter != null ? Long.parseLong(filter) : null;
+        Iterator<Cache.Entry<String, String>> iterator = rateLimitCache.iterator();
+        sb1.append("#<username>:<command>, <available tokens>\n");
+        sb2.append("#<username>:<command>, <timestamp>, <delta minutes>");
+        sb2.append(deltaMinutesFilter != null ? " ## deltaMinutesFilter=" + deltaMinutesFilter + "\n" : "\n");
+        int cacheEntries = 0;
+
+        while (iterator.hasNext()) {
+            Cache.Entry<String, String> entry = iterator.next();
+            if (entry.getKey().endsWith(":last_update")) {
+                long deltaMinutes = currentTime - Long.parseLong(String.valueOf(entry.getValue()));
+                if (deltaMinutesFilter == null || deltaMinutes <= deltaMinutesFilter) {
+                    sb2.append(entry.getKey() + ", " + entry.getValue() + ", " + deltaMinutes + "\n");
+                }
+            } else {
+                sb1.append(entry.getKey() + ", " + entry.getValue() + "\n");
+                cacheEntries++;
+            }
+        }
+
+        String header = "# Rate Limit Cache: Total number of cached entries (excluding \":last_update\") " + cacheEntries + "\n";
+        return header + sortString(sb1) + sortString(sb2);
+    }
     static String getMapKey(int tier) {
         return getMapKey(tier, null);
     }
@@ -142,4 +166,9 @@ static long longFromKey(Cache<String, String> cache, String key) {
         Object l = cache.get(key);
         return l != null ? Long.parseLong(String.valueOf(l)) : 0L;
     }
+    static String sortString(StringBuilder sb) {
+        String[] strings = sb.toString().split("\\R");
+        Arrays.sort(strings);
+        return String.join("\n", strings) + "\n";
+    }
 }

src/test/java/edu/harvard/iq/dataverse/api/SendFeedbackApiIT.java

@@ -192,6 +192,13 @@ private void validateEmail(String body) {
 
     @Test
     public void testSendRateLimited() {
+        Response createSuperuser = UtilIT.createRandomUser();
+        String superuserUsername = UtilIT.getUsernameFromResponse(createSuperuser);
+        String superuserApiToken = UtilIT.getApiTokenFromResponse(createSuperuser);
+        Response toggleSuperuser = UtilIT.makeSuperUser(superuserUsername);
+        toggleSuperuser.then().assertThat()
+                .statusCode(OK.getStatusCode());
+
         Response createUser = UtilIT.createRandomUser();
         createUser.prettyPrint();
         createUser.then().assertThat()
@@ -234,6 +241,19 @@ public void testSendRateLimited() {
         response.then().assertThat()
                 .statusCode(TOO_MANY_REQUESTS.getStatusCode());
 
+        response = UtilIT.rateLimitStats(apiToken, null);
+        response.prettyPrint();
+        response.then().assertThat()
+                .statusCode(FORBIDDEN.getStatusCode());
+        response = UtilIT.rateLimitStats(superuserApiToken, null);
+        response.prettyPrint();
+        response.then().assertThat()
+                .statusCode(OK.getStatusCode());
+        response = UtilIT.rateLimitStats(superuserApiToken, "1");
+        response.prettyPrint();
+        response.then().assertThat()
+                .statusCode(OK.getStatusCode());
+
         response = UtilIT.sendFeedback(buildJsonEmail(datasetId, null, null), apiToken);
         response.prettyPrint();
         response.then().assertThat()

src/test/java/edu/harvard/iq/dataverse/api/UtilIT.java

@@ -3032,6 +3032,12 @@ static Response clearMetricCache(String name) {
         return requestSpecification.delete("/api/admin/clearMetricsCache/" + name);
     }
 
+    static Response rateLimitStats(String apiToken, String deltaMinutesFilter) {
+        String queryParams = deltaMinutesFilter != null ? "?deltaMinutesFilter=" + deltaMinutesFilter : "";
+        return given()
+                .header(API_TOKEN_HTTP_HEADER, apiToken)
+                .get("/api/admin/rateLimitStats" + queryParams);
+    }
 
     static Response sitemapUpdate() {
         return given()