Uniformize spam-checker API, part 3: Expand check_event_for_spam with…

… the ability to return additional fields.

changelog.d/12846.feature

@@ -0,0 +1 @@
+Experimental: expand `check_event_for_spam` with ability to return additional fields.

synapse/api/errors.py

@@ -139,7 +139,13 @@ class SynapseError(CodeMessageException):
         errcode: Matrix error code e.g 'M_FORBIDDEN'
     """
 
-    def __init__(self, code: int, msg: str, errcode: str = Codes.UNKNOWN):
+    def __init__(
+        self,
+        code: int,
+        msg: str,
+        errcode: str = Codes.UNKNOWN,
+        additional_fields: Optional[Dict] = None,
+    ):
         """Constructs a synapse error.
 
         Args:
@@ -149,9 +155,13 @@ def __init__(self, code: int, msg: str, errcode: str = Codes.UNKNOWN):
         """
         super().__init__(code, msg)
         self.errcode = errcode
+        if additional_fields is None:
+            self._additional_fields: Dict = {}
+        else:
+            self._additional_fields = dict(additional_fields)
 
     def error_dict(self) -> "JsonDict":
-        return cs_error(self.msg, self.errcode)
+        return cs_error(self.msg, self.errcode, **self._additional_fields)
 
 
 class InvalidAPICallError(SynapseError):
@@ -176,14 +186,7 @@ def __init__(
         errcode: str = Codes.UNKNOWN,
         additional_fields: Optional[Dict] = None,
     ):
-        super().__init__(code, msg, errcode)
-        if additional_fields is None:
-            self._additional_fields: Dict = {}
-        else:
-            self._additional_fields = dict(additional_fields)
-
-    def error_dict(self) -> "JsonDict":
-        return cs_error(self.msg, self.errcode, **self._additional_fields)
+        super().__init__(code, msg, errcode, additional_fields)
 
 
 class ConsentNotGivenError(SynapseError):

synapse/events/spamcheck.py

@@ -47,6 +47,11 @@
         Union[
             Allow,
             Codes,
+            # Highly experimental, not officially part of the spamchecker API, may
+            # disappear without warning depending on the results of ongoing
+            # experiments.
+            # Use this to return additional information as part of an error.
+            Tuple[Codes, Dict],
             # Deprecated
             bool,
             # Deprecated
@@ -269,7 +274,7 @@ def register_callbacks(
 
     async def check_event_for_spam(
         self, event: "synapse.events.EventBase"
-    ) -> Union[Decision, str]:
+    ) -> Union[Decision, Tuple[Codes, Dict], str]:
         """Checks if a given event is considered "spammy" by this server.
 
         If the server considers an event spammy, then it will be rejected if
@@ -292,9 +297,9 @@ async def check_event_for_spam(
             with Measure(
                 self.clock, "{}.{}".format(callback.__module__, callback.__qualname__)
             ):
-                res: Union[Decision, str, bool] = await delay_cancellation(
-                    callback(event)
-                )
+                res: Union[
+                    Decision, Tuple[Codes, Dict], str, bool
+                ] = await delay_cancellation(callback(event))
                 if res is False or res is Allow.ALLOW:
                     # This spam-checker accepts the event.
                     # Other spam-checkers may reject it, though.
@@ -304,8 +309,9 @@ async def check_event_for_spam(
                     # return value `True`
                     return Codes.FORBIDDEN
                 else:
-                    # This spam-checker rejects the event either with a `str`
-                    # or with a `Codes`. In either case, we stop here.
+                    # This spam-checker rejects the event either with a `str`,
+                    # with a `Codes` or with a `Tuple[Codes, Dict]`. In either
+                    # case, we stop here.
                     return res
 
         # No spam-checker has rejected the event, let it pass.

synapse/handlers/message.py

@@ -888,6 +888,14 @@ async def create_and_send_nonmember_event(
 
             spam_check = await self.spam_checker.check_event_for_spam(event)
             if spam_check is not synapse.spam_checker_api.Allow.ALLOW:
+                if isinstance(spam_check, tuple):
+                    [code, dict] = spam_check
+                    raise SynapseError(
+                        403,
+                        "This message had been rejected as probable spam",
+                        code,
+                        dict,
+                    )
                 raise SynapseError(
                     403, "This message had been rejected as probable spam", spam_check
                 )