Docstrings

1 files changed, 154 insertions, 27 deletions

diff --git a/synapse/third_party_rules/access_rules.py b/synapse/third_party_rules/access_rules.py
index 1f03138752..a8b3ed9458 100644
--- a/synapse/third_party_rules/access_rules.py
+++ b/synapse/third_party_rules/access_rules.py
@@ -28,9 +28,31 @@ ACCESS_RULE_DIRECT = "direct"
 
 
 class RoomAccessRules(object):
+    """Implementation of the ThirdPartyEventRules module API that allows federation admins
+    to define custom rules for specific events and actions.
+    Implements the custom behaviour for the "im.vector.room.access_rules" state event.
+
+    Takes a config in the format:
+
+    third_party_event_rules:
+        module: third_party_rules.RoomAccessRules
+        config:
+            # List of domains (server names) that can't be invited to rooms if the
+            # "restricted" rule is set. Defaults to an empty list.
+            domains_forbidden_when_restricted: []
+
+            # Identity server to use when checking the HS an email address belongs to
+            # using the /info endpoint. Required.
+            id_server: "vector.im"
+
+    Don't forget to consider if you can invite users from your own domain.
+    """
+
     def __init__(self, config, http_client):
         self.http_client = http_client
+
         self.id_server = config["id_server"]
+
         self.domains_forbidden_when_restricted = config.get(
             "domains_forbidden_when_restricted", [],
         )
@@ -43,34 +65,77 @@ class RoomAccessRules(object):
             raise ConfigError("No IS for event rules TchapEventRules")
 
     def on_create_room(self, requester, config, is_requester_admin):
+        """Implements synapse.events.ThirdPartyEventRules.on_create_room
+
+        Checks if a im.vector.room.access_rules event is being set during room creation.
+        If yes, make sure the event is correct. Otherwise, append an event with the
+        default rule to the initial state.
+        """
+        is_direct = config.get("is_direct")
+        rules_in_initial_state = False
+
+        # If there's a rules event in the initial state, check if it complies with the
+        # spec for im.vector.room.access_rules and fix it if not.
         for event in config.get("initial_state", []):
             if event["type"] == ACCESS_RULES_TYPE:
-                # If there's already a rules event in the initial state, check if it
-                # breaks the rules for "direct", and if not don't do anything else.
-                if (
-                    not config.get("is_direct")
-                    or event["content"]["rule"] != ACCESS_RULE_DIRECT
-                ):
-                    return
-
-        # Append an access rules event to be sent once every other event in initial_state
-        # has been sent. If "is_direct" exists and is set to True, the rule needs to be
-        # "direct", and "restricted" otherwise.
-        if config.get("is_direct"):
-            default_rule = ACCESS_RULE_DIRECT
-        else:
-            default_rule = ACCESS_RULE_RESTRICTED
+                rules_in_initial_state = True
+
+                rule = event["content"].get("rule")
+
+                # Make sure the event has a valid content.
+                if rule is None:
+                    event["content"] = {
+                        "rule": self._on_create_room_default_rule(is_direct)
+                    }
+
+                # Make sure the rule name is valid.
+                if not self._is_rule_name_valid(rule):
+                    event["content"]["rule"] = self._on_create_room_default_rule(
+                        is_direct,
+                    )
+
+                # Make sure the rule is "direct" if the room is a direct chat.
+                if is_direct and rule != ACCESS_RULE_DIRECT:
+                    event["content"]["rule"] = ACCESS_RULE_DIRECT
+
+                # Make sure the rule is not "direct" if the room isn't a direct chat.
+                if rule == ACCESS_RULE_DIRECT and not is_direct:
+                    event["content"]["rule"] = ACCESS_RULE_RESTRICTED
+
+        # If there's no rules event in the initial state, create one with the default
+        # setting.
+        if not rules_in_initial_state:
+            config["initial_state"].append({
+                "type": ACCESS_RULES_TYPE,
+                "state_key": "",
+                "content": {
+                    "rule": self._on_create_room_default_rule(is_direct),
+                }
+            })
 
-        config["initial_state"].append({
-            "type": ACCESS_RULES_TYPE,
-            "state_key": "",
-            "content": {
-                "rule": default_rule,
-            }
-        })
+    @staticmethod
+    def _on_create_room_default_rule(is_direct):
+        """Returns the default rule to set.
+
+        Args:
+            is_direct (bool): Is the room created with "is_direct" set to True.
+
+        Returns:
+            str, the name of the rule tu use as the default.
+        """
+        if is_direct:
+            return ACCESS_RULE_DIRECT
+        else:
+            return ACCESS_RULE_RESTRICTED
 
     @defer.inlineCallbacks
     def check_threepid_can_be_invited(self, medium, address, state_events):
+        """Implements synapse.events.ThirdPartyEventRules.check_threepid_can_be_invited
+
+        Check if a threepid can be invited to the room via a 3PID invite given the current
+        rules and the threepid's address, by retrieving the HS it's mapped to from the
+        configured identity server, and checking if we can invite users from it.
+        """
         rule = self._get_rule_from_state(state_events)
 
         if medium != "email":
@@ -105,6 +170,11 @@ class RoomAccessRules(object):
         defer.returnValue(True)
 
     def check_event_allowed(self, event, state_events):
+        """Implements synapse.events.ThirdPartyEventRules.check_event_allowed
+
+        Checks the event's type and the current rule and calls the right function to
+        determine whether the event can be allowed.
+        """
         # Special-case the access rules event.
         if event.type == ACCESS_RULES_TYPE:
             return self._on_rules_change(event, state_events)
@@ -125,14 +195,20 @@ class RoomAccessRules(object):
         return ret
 
     def _on_rules_change(self, event, state_events):
+        """Implement the checks and behaviour specified on allowing or forbidding a new
+        im.vector.room.access_rules event.
+
+        Args:
+            event (synapse.events.EventBase): The event to check.
+            state_events (dict[tuple[event type, state key], EventBase]): The state of the
+                room before the event was sent.
+        Returns:
+            bool, True if the event can be allowed, False otherwise.
+        """
         new_rule = event.content.get("rule")
 
         # Check for invalid values.
-        if (
-            new_rule != ACCESS_RULE_DIRECT
-            and new_rule != ACCESS_RULE_RESTRICTED
-            and new_rule != ACCESS_RULE_UNRESTRICTED
-        ):
+        if not self._is_rule_name_valid(new_rule):
             return False
 
         # Make sure we don't apply "direct" if the room has more than two members.
@@ -161,16 +237,37 @@ class RoomAccessRules(object):
         return False
 
     def _apply_restricted(self, event):
+        """Implements the checks and behaviour specified for the "restricted" rule.
+
+        Args:
+            event (synapse.events.EventBase): The event to check.
+        Returns:
+            bool, True if the event can be allowed, False otherwise.
+        """
         # "restricted" currently means that users can only invite users if their server is
         # included in a limited list of domains.
         invitee_domain = DomainRuleChecker._get_domain_from_id(event.state_key)
         return invitee_domain not in self.domains_forbidden_when_restricted
 
     def _apply_unrestricted(self):
+        """Implements the checks and behaviour specified for the "unrestricted" rule.
+
+        Returns:
+            bool, True if the event can be allowed, False otherwise.
+        """
         # "unrestricted" currently means that every event is allowed.
         return True
 
     def _apply_direct(self, event, state_events):
+        """Implements the checks and behaviour specified for the "direct" rule.
+
+        Args:
+            event (synapse.events.EventBase): The event to check.
+            state_events (dict[tuple[event type, state key], EventBase]): The state of the
+                room before the event was sent.
+        Returns:
+            bool, True if the event can be allowed, False otherwise.
+        """
         # "direct" currently means that no member is allowed apart from the two initial
         # members the room was created for (i.e. the room's creator and their first
         # invitee).
@@ -235,6 +332,14 @@ class RoomAccessRules(object):
 
     @staticmethod
     def _get_rule_from_state(state_events):
+        """Extract the rule to be applied from the given set of state events.
+
+        Args:
+            state_events (dict[tuple[event type, state key], EventBase]): The set of state
+                events
+        Returns:
+            str, the name of the rule (either "direct", "restricted" or "unrestricted")
+        """
         access_rules = state_events.get((ACCESS_RULES_TYPE, ""))
         if access_rules is None:
             rule = ACCESS_RULE_RESTRICTED
@@ -244,5 +349,27 @@ class RoomAccessRules(object):
 
     @staticmethod
     def _is_invite_from_threepid(invite, threepid_invite):
+        """Checks whether the given invite follows the given 3PID invite.
+
+        Args:
+             invite (EventBase): The m.room.member event with "invite" membership.
+             threepid_invite (EventBase): The m.room.third_party_invite event.
+        """
         token = invite.content.get("third_party_signed", {}).get("token", "")
         return token == threepid_invite.state_key
+
+    @staticmethod
+    def _is_rule_name_valid(rule):
+        """Returns whether the given rule name is within the allowed values ("direct",
+        "restricted" or "unrestricted").
+
+        Args:
+            rule (str): The name of the rule.
+        Returns:
+            bool, True if the name is valid, False otherwise.
+        """
+        return (
+            rule == ACCESS_RULE_DIRECT
+            or rule == ACCESS_RULE_RESTRICTED
+            or rule == ACCESS_RULE_UNRESTRICTED
+        )