From deca250e3f0f18ffc978f17d1f9e440fc8a4af98 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Wed, 18 May 2022 12:21:32 +0100
Subject: Add some documentation around the `rc_invites` option to the config
 docs (#12759)

---
 changelog.d/12759.doc                            |  1 +
 docs/usage/configuration/config_documentation.md | 14 ++++++++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 changelog.d/12759.doc

diff --git a/changelog.d/12759.doc b/changelog.d/12759.doc
new file mode 100644
index 0000000000..45d1c9c0ca
--- /dev/null
+++ b/changelog.d/12759.doc
@@ -0,0 +1 @@
+Add information regarding the `rc_invites` ratelimiting option to the configuration docs.
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 3e2031f08a..3ad3085bfa 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -1357,6 +1357,20 @@ This option sets ratelimiting how often invites can be sent in a room or to a
 specific user. `per_room` defaults to `per_second: 0.3`, `burst_count: 10` and
 `per_user` defaults to `per_second: 0.003`, `burst_count: 5`. 
 
+Client requests that invite user(s) when [creating a
+room](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom)
+will count against the `rc_invites.per_room` limit, whereas
+client requests to [invite a single user to a
+room](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite)
+will count against both the `rc_invites.per_user` and `rc_invites.per_room` limits.
+
+Federation requests to invite a user will count against the `rc_invites.per_user`
+limit only, as Synapse presumes ratelimiting by room will be done by the sending server.
+
+The `rc_invites.per_user` limit applies to the *receiver* of the invite, rather than the
+sender, meaning that a `rc_invite.per_user.burst_count` of 5 mandates that a single user
+cannot *receive* more than a burst of 5 invites at a time.
+
 Example configuration:
 ```yaml
 rc_invites:
-- 
cgit 1.4.1