Uniformize spam-checker API: github/ts/spam-errors ts/spam-errors

- Some callbacks should return `True` to allow, `False` to deny, while others should return `True` to deny and `False` to allow. With this PR, all callbacks return `ALLOW` to allow or a `Codes` (typically `Codes.FORBIDDEN`) to deny.
- Similarly, some methods returned `True` to allow, `False` to deny, while others returned `True` to deny and `False` to allow. They now all return `ALLOW` to allow or a `Codes` to deny.
- Spam-checker implementations may now return an explicit code, e.g. to differentiate between "User account has been suspended" (which is in practice required by law in some countries, including UK) and "This message looks like spam".

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/modules/spam_checker_callbacks.md b/docs/modules/spam_checker_callbacks.md
index 472d957180..d0db863ff8 100644
--- a/docs/modules/spam_checker_callbacks.md
+++ b/docs/modules/spam_checker_callbacks.md
@@ -18,6 +18,17 @@ async def check_event_for_spam(event: "synapse.events.EventBase") -> Union[bool,
 
 Called when receiving an event from a client or via federation. The callback must return
 either:
+  - on `Decision.ALLOW`, the action is permitted.
+  - on `Decision.DENY`, the action is rejected with a default error message/code.
+  - on `Codes`, the action is rejected with a specific error message/code. In case
+      of doubt, use `Codes.FORBIDDEN`.
+  - (deprecated) on `False`, behave as `Decision.ALLOW`. Deprecated as methods in
+      this API are inconsistent, some expect `True` for `ALLOW` and others `True`
+      for `DENY`.
+  - (deprecated) on `True`, behave as `Decision.DENY`. Deprecated as methods in
+      this API are inconsistent, some expect `True` for `ALLOW` and others `True`
+      for `DENY`.
+
 - an error message string, to indicate the event must be rejected because of spam and 
   give a rejection reason to forward to clients;
 - the boolean `True`, to indicate that the event is spammy, but not provide further details; or