Class UserThrottleManager

java.lang.Object
com.jalios.jcms.security.UserThrottleManager

public final class UserThrottleManager extends Object
Throttles the requests of authenticated members.

This singleton limits the number of requests a member can send, to make bulk data extraction by script slower and harder. Requests are tracked for each member and IP pair. Requests without a member (anonymous users) are never recorded nor throttled.

Two Throttler instances work together:

Each throttler reads the properties described in Throttler ("throttle-enabled", "range-seconds", "threshold", "throttling-duration-seconds"). For each throttler, the throttling duration should be greater than or equal to the time range. Otherwise a member can be throttled again right after being released, because the requests recorded before the throttling are still in range.

When a member is throttled, the site administrators receive the security alert "user-request-throttled", at most once per member every ALERT_PERIOD. The alert can be disabled with the property alert.name.security."user-request-throttled".enabled: false. The throttled member is not notified, so that a malicious member is not warned.

Requests whose path matches one of the regular expressions declared with the prefix "channel.user-request-throttle-excluded-path." are never recorded nor throttled. Use them for static resources and generated thumbnails: one page loads dozens of them, they are not relevant for data extraction, and the waiting page needs them to display correctly.

The properties are read again automatically when the site properties change.

For diagnostics, set the logger of this class to TRACE: the throttlers use the same logger, so their traces (recorded actions, counts, throttling) are displayed too.

Typical usage, in a filter:

 final UserThrottleManager mgr = UserThrottleManager.getInstance();
 final Optional<Duration> retryAfter = mgr.throttleIfNeeded(loggedMember, request);
 if (retryAfter.isPresent()) {
   response.setHeader(UserThrottleManager.RETRY_AFTER_HEADER, String.valueOf(retryAfter.get().getSeconds()));
   response.sendError(UserThrottleManager.SC_TOO_MANY_REQUESTS);
   return;
 }
 mgr.recordRequest(loggedMember, request);
 chain.doFilter(request, response);
 
This class is thread safe.
Since:
jcms-11.0.1 / JCMS-12092
  • Field Details

    • SC_TOO_MANY_REQUESTS

      public static final int SC_TOO_MANY_REQUESTS
      HTTP status code sent when a request is throttled. Not defined in HttpServletResponse (RFC 6585).
      See Also:
    • RETRY_AFTER_HEADER

      public static final String RETRY_AFTER_HEADER
      HTTP header which tells the client how many seconds to wait before a new request.
      See Also:
    • BURST_THROTTLE_PROP_PREFIX

      public static final String BURST_THROTTLE_PROP_PREFIX
      Property prefix of the burst throttler (short time range, catches request spikes).
      See Also:
    • SUSTAINED_THROTTLE_PROP_PREFIX

      public static final String SUSTAINED_THROTTLE_PROP_PREFIX
      Property prefix of the sustained throttler (longer time range, catches sustained extraction).
      See Also:
    • THROTTLED_ALERT_NAME

      public static final String THROTTLED_ALERT_NAME
      Name of the security alert sent to the site administrators when a member is throttled. It is declared in the alert domain alert.name.security.
      See Also:
    • ALERT_PERIOD

      public static final Duration ALERT_PERIOD
      Minimum time between two security alerts for the same member.
    • EXCLUDED_PATH_PROP_PREFIX

      public static final String EXCLUDED_PATH_PROP_PREFIX
      Property prefix used to declare the paths that are never recorded nor throttled.

      Each property value is a regular expression which must match the whole path, relative to the context path and without leading slash, for example channel.user-request-throttle-excluded-path.css: css/.*.

      See Also:
  • Method Details

    • getInstance

      public static UserThrottleManager getInstance()
      Return the unique instance of this manager.
      Returns:
      the UserThrottleManager singleton, never null
    • init

      public void init()
      Read the properties again, for example after a change of the site properties.

      All the recorded requests and current throttlings are reset. The excluded paths are read again. The alert cache is kept.

    • isEnabled

      public boolean isEnabled()
      Check if at least one throttler is enabled.
      Returns:
      true if requests can be throttled, false if both throttlers are disabled
    • throttleIfNeeded

      public Optional<Duration> throttleIfNeeded(Member mbr, javax.servlet.http.HttpServletRequest request)
      Check if the specified request must be throttled.

      Call this method before recordRequest(Member, HttpServletRequest), and do not record a throttled request: recording requests while the member is throttled would keep the counters full, and the member would be throttled again right after being released.

      When the request is throttled, the security alert "user-request-throttled" is sent to the site administrators if no alert was sent for this member in the last ALERT_PERIOD.

      A request with an excluded path is never throttled, even if the member is throttled, so that the waiting page can still load its resources.

      Parameters:
      mbr - the logged member who sent the request, may be null (anonymous request, never throttled)
      request - the current request, used to get the remote IP
      Returns:
      the time the member must wait before a new request if the request is throttled, or an empty Optional if the request can go on
    • recordRequest

      public void recordRequest(Member mbr, javax.servlet.http.HttpServletRequest request)
      Record a request accepted for the specified member.

      A request with an excluded path is not recorded.

      Parameters:
      mbr - the logged member who sent the request, may be null (anonymous request, nothing is recorded)
      request - the current request, used to get the remote IP
      See Also:
    • isExcludedPath

      public boolean isExcludedPath(javax.servlet.http.HttpServletRequest request)
      Check if the path of the specified request is excluded from the throttling.
      Parameters:
      request - a request, may be null
      Returns:
      true if the path matches one of the excluded path patterns, false otherwise
    • isExcludedPath

      public boolean isExcludedPath(String path)
      Check if the specified path is excluded from the throttling.
      Parameters:
      path - a path relative to the context path, without leading slash, may be null
      Returns:
      true if the path matches one of the excluded path patterns, false otherwise