From 451a9dc7b9284a5d0988318970e15ad41b34491f Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 14 Oct 2024 11:31:49 +0100 Subject: [PATCH] Clarify when 3PID invite module callbacks are called (#17627) Co-authored-by: Eric Eastwood <eric.eastwood@beta.gouv.fr> --- changelog.d/17627.doc | 1 + docs/modules/spam_checker_callbacks.md | 9 ++++++--- 2 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 changelog.d/17627.doc diff --git a/changelog.d/17627.doc b/changelog.d/17627.doc new file mode 100644 index 0000000000..487a0aea0d --- /dev/null +++ b/changelog.d/17627.doc @@ -0,0 +1 @@ +Clarify when the `user_may_invite` and `user_may_send_3pid_invite` module callbacks are called. \ No newline at end of file diff --git a/docs/modules/spam_checker_callbacks.md b/docs/modules/spam_checker_callbacks.md index ffdfe6082e..ec306d81ab 100644 --- a/docs/modules/spam_checker_callbacks.md +++ b/docs/modules/spam_checker_callbacks.md @@ -76,8 +76,9 @@ _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_a async def user_may_invite(inviter: str, invitee: str, room_id: str) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool] ``` -Called when processing an invitation. Both inviter and invitee are -represented by their Matrix user ID (e.g. `@alice:example.com`). +Called when processing an invitation, both when one is created locally or when +receiving an invite over federation. Both inviter and invitee are represented by +their Matrix user ID (e.g. `@alice:example.com`). The callback must return one of: @@ -112,7 +113,9 @@ async def user_may_send_3pid_invite( ``` Called when processing an invitation using a third-party identifier (also called a 3PID, -e.g. an email address or a phone number). +e.g. an email address or a phone number). It is only called when a 3PID invite is created +locally - not when one is received in a room over federation. If the 3PID is already associated +with a Matrix ID, the spam check will go through the `user_may_invite` callback instead. The inviter is represented by their Matrix user ID (e.g. `@alice:example.com`), and the invitee is represented by its medium (e.g. "email") and its address -- GitLab