Heavy face-lift for version 1.2

readme.md

@@ -40,7 +40,7 @@ In order to be extra careful, here's an exhaustive list of all reigons for The U
 
 | Name                     | Reigon Name            | Shortcode |
 | ------------------------ | ---------------------- | --------- |
-| Nationwide               | __global__             | AL        |
+| Nationwide               | __global__             | ALL       |
 | Alabama                  | Alabama                | AL        |
 | Alaska                   | Alaska                 | AK        |
 | American Samoa           | AmericanSamoa          | AS        |
@@ -122,14 +122,18 @@ When the person enters in `!report arizona Some Report` the two consumer bots sh
 
 ## Maubot Specifics
 
-Here's some sample code and configuration layout to make plugin development easier.
+Here's some sample code and configuration layout to make plugin development easier. You can copy paste these into your plugin, or use it as inspiration. FiftyFiftyOneArizona's plugins try to be as consistent as possible with its configuration options, and how the plugin behaves with that configuration.
 
 ## Sample Configuration
 
+Which users are allowed to send reports for which regions:
+
 ```yaml
-# Which regions the bot should pay attention to
+# Which regions the bot should pay attention to.
-# This can be either an empty list to allow any sender for this reigon,
+# Pass through empty list to allow all senders for a region.
-# or can have a specified whitelist of senders
+# Add a list of MatrixIDs to whitelist senders for a region.
+# Use __global__ to refer to all regions.
+# Code looks to see if a sender is allowed for a specific region OR __global__.
 allowed_regions:
     foo:
         - "@reports:fiftyfiftyonerarizona.org"
@@ -138,80 +142,108 @@ allowed_regions:
         - "@reports:example.com"
     buzz:
     aaa:
+
 ```
 
+Different configurations for each regions, and one which processes reports for all regions:
+
 ```yaml
 # Bot-specific configurations per region
-# The fields in each specific reigon should be the same, but their values should differ
+# Code will assume no authentication if either username or password are missing.
-# In this case (with NTFY), the bot should post notifications for each reigon
+# Use __global__ to specify an endpoint for all regions.
-# to a different topic.
+# Code will push to both __global__ and region-specific endpoint.
 region_configs:
-	__global__:
+    arizona:
-		# Where and how the plugin will send the data to
-		server_url: "https://ntfy.sh"
-		server_topic: "changeme2"
-
-		# If the plugin should use a username and password to send notifications
-		server_use_authentication: true
-		server_username: "no"
-		server_password: "way"
-	foo:
         # Where and how the plugin will send the data to
         server_url: "https://ntfy.sh"
         server_topic: "changeme"
 
         # If the plugin should use a username and password to send notifications
-        server_use_authentication: true
+        username: "no"
-        server_username: "no"
+        password: "way"
-        server_password: "way"
+```
-	bar:
-        # Where and how the plugin will send the data to
-        server_url: "https://ntfy.sh"
-		server_topic: "changeme2"
 
-        # If the plugin should use a username and password to send notifications
+Defining which rooms a producer should send to for each region, and for all regions:
-        server_use_authentication: true
+
-        server_username: "no"
+```yaml
-        server_password: "way"
+sendto:
+    __global__:
+        - "!example:example.com"
+    arizona:
+        - "!example:example.com"
+        - "!example2:example.com"
+    california:
+        - "!example:example.com"
 ```
 
 ## Helper Functions
 
-```python
+Handling which users are allowed to send reports for which regions. Takes in region string and sender MatrixID as a string. Returns a boolean.
-# Checks if a sender if allowed to send for a particular region
-def validateSender(self, region: str, sender: str):
-	# Check that config value exists
-	if not self.config["allowed_regions"]: return False
-	# Check that region is allowed
-	if not region in self.config["allowed_regions"]: return False
-	# All senders allowed for this region
-	if len(self.config["allowed_regions"][region]) == 0: return True
-	# Check that sender is allowed for region
-	if not sender in self.config["allowed_regions"][region]: return False
-	return True
-```
 
 ```python
-# Does the necesary config checks for the given event
+# Checks if a sender if allowed to send for a particular region
-# Returns list of regions to process (strings)
+def validate_sender(self, region: str, sender: str):
-# Currently just the specified region and "__global__"
+	# Mautrix isn't documented, like at all, so I'm just gonna catch the
-def validateReport(self, evt: MessageEvent, message: str):
+	# error because IDK how to see if a map is inside a map.
+	try: allowed_list = self.config["allowed_regions"][region]
+	except: return False
+	
+	if allowed_list is None: return True # Empty list
+	if sender in allowed_list: return True
+	
+	# Sender not allowed in region config
+	return False
+```
+
+Handling different configurations for each regions. Parses an event and its body, returns a list of configurations. List can be empty. Depends on `validate_sender` function above.
+
+This function also handles the following edge cases
+
+1. Sender allowed globally but `__global__` is not defined in the region configs.
+2. Sender allowed for a region, and both that region and `__global__` is defined.
+3. Sender is allowed either globally or for a region, but neither that region or `__global__` are defined. An empty list will be returned.
+
+
+```python
+# Does the necessary config checks for the given event
+# Returns list of recursive configs to process
+def validate_report(self, evt: MessageEvent, message: str):
 	# Split command (minus !command_name) into tokens
 	tokens = message.split()
 	region = tokens[0].lower()
 	
 	# Each command must have a state/territory designation and a message
-	if len(tokens) < 2: return None
+	if len(tokens) < 2: return []
+	# And we must have self.config["region_configs"]
+	try: trashvariable = self.config["region_configs"]
+	except: return []
 	
-	self.log.debug(region)
+	configs = [] # To be returned
 	
-	# This is a list of regions to process for this specific message
+	allowed_globally = self.validate_sender("__global__", evt.sender)
-	# This is only used to consider __global__
+	allowed_region = self.validate_sender(region, evt.sender)
-	regions_to_process = []
-	if (self.validateSender("__global__", evt.sender)):
-		regions_to_process.append("__global__")
-	if (self.validateSender(region, evt.sender)):
-		regions_to_process.append(region)
 	
-	return regions_to_process
+	# If user is allowed globally and/or for a region,
+	# the plugin should process both the region and __global__ configs
+	if allowed_globally or allowed_region:
+		for i in ["__global__", region]:
+			try: configs.append(self.config["region_configs"][i])
+			except: trashvariable = None
+	
+	return configs
+```
+
+Getting a set of rooms to send to, inclusive of `__global__` and the region name.
+
+```python
+def get_send_rooms(self, region_name):
+	room_ids = set()
+	
+	if "sendto" in self.config: return room_ids
+		for i in [region_name, "__global__"]:
+			if i in self.config["sendto"]:
+				for room_id in self.config["sendto"][i]:
+					room_ids.add(room_id)
+	
+	return room_ids
 ```