Class UserThrottleManager
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:
- a burst throttler, with a short time range, catches request spikes (properties prefixed by "channel.user-request-burst-throttle.");
- a sustained throttler, with a longer time range, catches slow and regular extraction (properties prefixed by "channel.user-request-throttle.").
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final DurationMinimum time between two security alerts for the same member.static final StringProperty prefix of the burst throttler (short time range, catches request spikes).static final StringProperty prefix used to declare the paths that are never recorded nor throttled.static final StringHTTP header which tells the client how many seconds to wait before a new request.static final intHTTP status code sent when a request is throttled.static final StringProperty prefix of the sustained throttler (longer time range, catches sustained extraction).static final StringName of the security alert sent to the site administrators when a member is throttled. -
Method Summary
Modifier and TypeMethodDescriptionstatic UserThrottleManagerReturn the unique instance of this manager.voidinit()Read the properties again, for example after a change of the site properties.booleanCheck if at least one throttler is enabled.booleanisExcludedPath(String path) Check if the specified path is excluded from the throttling.booleanisExcludedPath(javax.servlet.http.HttpServletRequest request) Check if the path of the specified request is excluded from the throttling.voidrecordRequest(Member mbr, javax.servlet.http.HttpServletRequest request) Record a request accepted for the specified member.throttleIfNeeded(Member mbr, javax.servlet.http.HttpServletRequest request) Check if the specified request must be throttled.
-
Field Details
-
SC_TOO_MANY_REQUESTS
public static final int SC_TOO_MANY_REQUESTSHTTP status code sent when a request is throttled. Not defined inHttpServletResponse(RFC 6585).- See Also:
-
RETRY_AFTER_HEADER
HTTP header which tells the client how many seconds to wait before a new request.- See Also:
-
BURST_THROTTLE_PROP_PREFIX
Property prefix of the burst throttler (short time range, catches request spikes).- See Also:
-
SUSTAINED_THROTTLE_PROP_PREFIX
Property prefix of the sustained throttler (longer time range, catches sustained extraction).- See Also:
-
THROTTLED_ALERT_NAME
Name of the security alert sent to the site administrators when a member is throttled. It is declared in the alert domainalert.name.security.- See Also:
-
ALERT_PERIOD
Minimum time between two security alerts for the same member. -
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
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
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
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
-