Confusing (incorrect?) description of rate limiting in sample config.

Description

The current sample_config.yaml describes rate limiting configuration like this:

## Ratelimiting ##
                                                                                                                                                                
# Ratelimiting settings for client actions (registration, login, messaging).
#
# Each ratelimiting configuration is made of two parameters:
#   - per_second: number of requests a client can send per second.
#   - burst_count: number of requests a client can send before being throttled.

I understood this to mean that setting per_second: 5 would mean that a client could send 5 messages per second. After all, the “number of requests a client can send per second” is set to 5.

But a conversation I just had in #synapse:matrix.org has informed me that the per_second value is actually the duration of a burst period, where burst_count is the maximum number of requests allowed in that period.

So setting per_second: 1 and burst_count: 5 would let a client send a maximum of 5 requests per second.

Is this actually correct? It seems to match the behavior i get in synapse (although I haven’t tested thoroughly). If it really is the way I described, I suggest we change the wording in sample_config.yaml to be something like:

## Ratelimiting ##

# Ratelimiting settings for client actions (registration, login, messaging).
#
# Each ratelimiting configuration is made of two parameters:
#   - burst_period: a period of time to count requests in, measured in seconds.
#   - burst_count: number of requests a client can send in a `burst_period` timeframe before being throttled.

Steps to reproduce

• Read sample configuration file.
• Try to set up rate limiting based on the description in the config.
• Set a per_second value proportionally to the “number of requests a client can send per second”
• Observe that synapse doesn’t exhibit the expected behavior.
• Be confused.

Version information

Any version of synapse since commit 899e523d6d92dfbc17dce81eb36f63053e447a97, which introduces the confusing description.

[anoadragon453]

Thanks for clarifying! Your description is miles clearer than the couple lines that are currently in the config file to be honest. A page in the documentation with roughly that would be a good thing to have.

I can see about drafting something up.

[anoadragon453]

The spot where these values are actually used to determine whether rate-limiting should occur is here (per_second is loaded from the config as rate_hz):

https://github.com/matrix-org/synapse/blob/a683028d81606708f686b890c0a44f5a20b54798/synapse/api/ratelimiting.py#L127-L144

You’re correct in that the current description doesn’t match the behaviour.

So setting per_second: 1 and burst_count: 5 would let a client send a maximum of 5 requests per second. Is this actually correct?

# Let's say that the user has performed 12 actions, starting 2 seconds ago
action_count = 12.0
time_delta = 2.0

performed_count = 10.0 (action_count) - 2.0 (time_delta) * 5 (burst_period) = 2.0

# We then check whether the user can perform another instance of the action, according to our burst_count
2.0 (performed_count) + 1.0 (n_actions; the user wants to perform this action only once) > 5 (burst_count)

3 < 5. The user can perform another action, and another 2 past that if desired (so 15 actions in 2 seconds, or 7.5 req / s).
This doesn't really match our intuition.

Perhaps the most useful comment is here:

https://github.com/matrix-org/synapse/blob/c7f3fb27451038c0f4b80a557f27eae849d55de2/synapse/api/ratelimiting.py#L177

Which explains that the rate limit is calculated by taking the “seconds since we started limiting this action” multiplied by the per_second config value, and then checking if that plus the number of actions performed since recording is greater than our burst_count.

Note that we stop recording a set of actions according to the below function (which is called when trying to perform an action):

https://github.com/matrix-org/synapse/blob/a683028d81606708f686b890c0a44f5a20b54798/synapse/api/ratelimiting.py#L174-L183

The algorithm is a bit confusing in general honestly. It seems like it’s based on Sliding Log? I’m struggling to come up with a good way to phrase this in the sample config.

Here are some examples of rate-limiting techniques (excuse the marketing).