Rate Limit
(This feature can be tried with the Pleasanter Extensions Trial.)
Overview¶
The "rate limit function" supports the stable operation of the system by suppressing excessive requests (a large number of screen operations in a short time, or heavy processing such as export and import run in a concentrated way) per user, IP address, or API key. You can flexibly configure tolerance for temporary bursts of access, limits on the number of executions within a certain time, limits on the number of concurrent executions, and so on, to control the load according to your environment.
Configure it in the RateLimit.json parameter file. For details of each setting item, see the parameter manual RateLimit.json.
Limitations¶
- It is disabled by default ("Mode" is "Off"). To use it, you need to enable it in RateLimit.json.
- This function limits requests "per unit", such as per user, IP address, or API key. It does not limit the total amount of requests of the whole system (the sum of all users).
Prerequisites¶
- This feature is available only to subscribers of the following plans of the Annual Support Service.
| Entry | Basic | Basic Plus | Business | Business Plus | Unlimited |
|---|---|---|---|---|---|
| 〇 | 〇 | 〇 |
Operation Modes¶
The top-level "Mode" of RateLimit.json switches the operation of the whole function.
| Setting value | Description |
|---|---|
| Off | (Default) Disables the function. There is no effect on performance. |
| LogOnly | Observes that the limit is exceeded and records it in the log, but does not block requests. Use it for observation when adjusting thresholds. |
| On | Returns "429 Too Many Requests" and blocks the request when the limit is exceeded. |
When introducing the function, we recommend first observing the actual access trends with "LogOnly" and adjusting the thresholds, and then switching to "On".
Units of the Limit (Partitions)¶
The limit is counted independently for each of the following "units".
| Unit | Description |
|---|---|
| User | Per logged-in user (login ID). Unauthenticated requests are not covered. |
| Ip | Per source IP address. |
| ApiKey | Per API key. Requests for which an API key cannot be obtained fall back to a limit per source IP address. |
| Auto | Resolved automatically, such as per logged-in user, or per IP if not authenticated. |
List of Policies¶
In Pleasanter, a "policy" is defined for each function category, and a limit is set for each. Each request is evaluated by both the policy for its function category and the upper-level policy "GlobalLimiter" that is common to all routes, and is blocked if it exceeds either limit.
| Policy name | Unit | Algorithm | Default limit | Main target |
|---|---|---|---|---|
| GlobalLimiter | Auto | TokenBucket | Capacity 100 / +50 per second | Upper-level policy common to all routes (the last line of defense) |
| General | User | TokenBucket | Capacity 10 / +5 per second | General screen operations |
| List | User | SlidingWindow | 30 times in the last 60 seconds | Lists, search, grids, and aggregation views |
| Admin | User | FixedWindow | 30 times every 60 seconds | Administrative operations (user / department / group management and so on) |
| Heavy | User | Concurrency | 1 concurrent | Heavy processing on the screen side (export, import and so on) |
| ApiHeavy | ApiKey | Concurrency | 1 concurrent | Heavy processing via API |
| Api | Auto | TokenBucket | Capacity 30 / +10 per second | REST API in general |
| AnonymousIp | Ip | FixedWindow | 60 times in 60 seconds | Unauthenticated access (login attempts and so on) |
| PublicForm | Ip | TokenBucket | Capacity 5 / +2 per second | Submission of public forms |
For the role of each policy and the way of thinking about threshold adjustment, see "Rate Limit Function: Adjusting Policies and Thresholds".
Limiting Algorithms¶
A limiting algorithm is the rule for limiting the number of operations that can be performed within a certain time in the rate limit. Each algorithm differs in how it judges access and in the characteristics of the limit, so you can choose an appropriate method according to the use case.
| Algorithm | Description |
|---|---|
| TokenBucket | Limits the number of operations by consuming tokens in a bucket. As long as there are tokens in the bucket, processing is allowed immediately, and it is rejected when they run out. The tokens in the bucket are refilled at regular intervals. Suitable for regular screen operations and APIs. |
| FixedWindow | Resets the counter for each fixed time (window) and limits the number of operations within that window. If operations are concentrated near the boundary of a window, in some cases a throughput close to twice the rate limit may be allowed. |
| SlidingWindow | Limits the number of operations only within the most recent fixed period (window). This function uses a counter approximation method, which divides the window into multiple segments and limits the number of operations per segment. It is generally said that bursts at window boundaries are less likely to occur than with Fixed Window. |
| Concurrency | A method close to load control. It limits the number of concurrent executions rather than the number per unit of time. The count is increased when a concurrent execution starts and decreased when it completes. |
Behavior When the Limit Is Exceeded¶
When "Mode" of RateLimit.json is "On", requests that exceed the limit are blocked with "429 Too Many Requests". The format of the response is switched automatically according to the caller.
| Caller | Response |
|---|---|
| Direct access in a browser (screen transition) | Displays a simple error page (HTML). |
| Operations within the screen (Ajax) | Displays a message within the screen. |
| API (/api/ and so on) | Returns JSON that represents the error. |
- When "IncludeRetryAfter" of "RejectedResponse" in RateLimit.json is true, the "Retry-After" header (the approximate number of seconds until a retry) is added to the response.
- When "LogRejected" of "RejectedResponse" in "RateLimit.json" is true, the actual rejections when "Mode" is "On" are recorded in the structured log (logs/{year}/{month}/{day}/ratelimitlogs.json). Even if you set it to false, the counts (metrics) are always recorded, and the virtual rejection log when "Mode" is "LogOnly" is always output regardless of this setting.
- The counts of rejections and virtual rejections are aggregated by policy at regular intervals (60 seconds by default) and recorded in the same log file as "RateLimitMetricsSnapshot". Even if individual logs are thinned out because of a large number of rejections, you can grasp the counts with this aggregation.
- By default, logs are output only to files. For how to configure environments that collect logs from standard output (stdout), such as Docker/Kubernetes, see Rate Limit Function: Setting the Output Destination of Rejection Logs and Metrics.
Configuration Flow¶
- Edit the RateLimit.json parameter file ("Mode", the limits of each policy, and so on).
-
Restart Pleasanter ("RateLimit.json" is loaded at startup).
- If the "Parameter Management Function (Japanese)" is enabled, you can also edit the file and restart Pleasanter from the screen. For details, see the "Parameter Management Function".
-
Observe the actual access with "LogOnly" and check that there is no place where requests are limited by mistake.
- After adjusting the thresholds, switch "Mode" to "On".
Supported Versions¶
| Supported versions | Body |
|---|---|
| 1.5.6.0 and later | Added the rate limit function |