Clearer documentation and some sample code & YAML
This commit is contained in:
Ben
parent
5a6e5bb3c7
commit
cd502ab442
1 changed files with 168 additions and 2 deletions
170
readme.md
170
readme.md
|
|
@ -26,7 +26,7 @@ The human readable message can be anything. Such as "ICE Spotted at 500 E Fake S
|
||||||
|
|
||||||
The region field is a single token (no spaces in it) which designates the state or territory that the report is for. This is a required field. This requirement and its granularity have undergone quite a bit of scrutiny. Its purpose is to allow for consumers of this information to filter by their general location without being too granular. The specific choice of state came down to most 50501 groups being organized around each state.
|
The region field is a single token (no spaces in it) which designates the state or territory that the report is for. This is a required field. This requirement and its granularity have undergone quite a bit of scrutiny. Its purpose is to allow for consumers of this information to filter by their general location without being too granular. The specific choice of state came down to most 50501 groups being organized around each state.
|
||||||
|
|
||||||
This is **not case sensitive**, but again it must be a single word/token. Just concatenate the words for state or territory names with multiple words. Like NorthDakota or puertoRico or NATIONAL.
|
This is **not case sensitive**, but again it must be a single word/token. Just concatenate the words for state or territory names with multiple words. Like NorthDakota or puertoRico or COLORADO.
|
||||||
|
|
||||||
A more complete example might be:
|
A more complete example might be:
|
||||||
|
|
||||||
|
|
@ -34,6 +34,76 @@ A more complete example might be:
|
||||||
!report arizona ICE seen at 500 N Central Ave in Phoenix`
|
!report arizona ICE seen at 500 N Central Ave in Phoenix`
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Region List
|
||||||
|
|
||||||
|
In order to be extra careful, here's an exhaustive list of all reigons for The United States, listed in alphabetical order of their proper names.
|
||||||
|
|
||||||
|
| Name | Reigon Name | Shortcode |
|
||||||
|
| ------------------------ | ---------------------- | --------- |
|
||||||
|
| Nationwide | __global__ | AL |
|
||||||
|
| Alabama | Alabama | AL |
|
||||||
|
| Alaska | Alaska | AK |
|
||||||
|
| American Samoa | AmericanSamoa | AS |
|
||||||
|
| Arizona | Arizona | AZ |
|
||||||
|
| Arkansas | Arkansas | AR |
|
||||||
|
| California | California | CA |
|
||||||
|
| Colorado | Colorado | CO |
|
||||||
|
| Connecticut | Connecticut | CT |
|
||||||
|
| Delaware | Delaware | DE |
|
||||||
|
| District of Columbia | WashingtonDC | DC |
|
||||||
|
| Florida | Florida | FL |
|
||||||
|
| Georgia | Georgia | GA |
|
||||||
|
| Guam | Guam | GU |
|
||||||
|
| Hawaii | Hawaii | HI |
|
||||||
|
| Idaho | Idaho | ID |
|
||||||
|
| Illinois | Illinois | IL |
|
||||||
|
| Indiana | Indiana | IN |
|
||||||
|
| Iowa | Iowa | IA |
|
||||||
|
| Kansas | Kansas | KS |
|
||||||
|
| Kentucky | Kentucky | KY |
|
||||||
|
| Louisiana | Louisiana | LA |
|
||||||
|
| Maine | Maine | ME |
|
||||||
|
| Maryland | Maryland | MD |
|
||||||
|
| Massachusetts | Massachusetts | MA |
|
||||||
|
| Michigan | Michigan | MI |
|
||||||
|
| Minnesota | Minnesota | MN |
|
||||||
|
| Mississippi | Mississippi | MS |
|
||||||
|
| Missouri | Missouri | MO |
|
||||||
|
| Montana | Montana | MT |
|
||||||
|
| Nebraska | Nebraska | NE |
|
||||||
|
| Nevada | Nevada | NV |
|
||||||
|
| New Hampshire | NewHampshire | NH |
|
||||||
|
| New Jersey | NewJersey | NJ |
|
||||||
|
| New Mexico | NewMexico | NM |
|
||||||
|
| New York | NewYork | NY |
|
||||||
|
| North Carolina | NorthCarolina | NC |
|
||||||
|
| North Dakota | NorthDakota | ND |
|
||||||
|
| Northern Mariana Islands | NorthernMarianaIslands | MP |
|
||||||
|
| Ohio | Ohio | OH |
|
||||||
|
| Oklahoma | Oklahoma | OK |
|
||||||
|
| Oregon | Oregon | OR |
|
||||||
|
| Pennsylvania | Pennsylvania | PA |
|
||||||
|
| Puerto Rico | PuertoRico | PR |
|
||||||
|
| Rhode Island | RhodeIsland | RI |
|
||||||
|
| South Carolina | SouthCarolina | SC |
|
||||||
|
| South Dakota | SouthDakota | SD |
|
||||||
|
| Tennessee | Tennessee | TN |
|
||||||
|
| Texas | Texas | TX |
|
||||||
|
| Utah | Utah | UT |
|
||||||
|
| U.S. Virgin Islands | USVirginIslands | VI |
|
||||||
|
| Vermont | Vermont | VT |
|
||||||
|
| Virginia | Virginia | VA |
|
||||||
|
| Washington | Washington | WA |
|
||||||
|
| West Virginia | WestVirginia | WV |
|
||||||
|
| Wisconsin | Wisconsin | WI |
|
||||||
|
| Wyoming | Wyoming | WY |
|
||||||
|
|
||||||
|
And here's a convenient one-line list of the shortcodes:
|
||||||
|
|
||||||
|
```
|
||||||
|
all al ak as az ar ca co ct de dc fl ga gu hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd mp oh ok or pa pr ri sc sd tn tx ut vi vt va wa wv wi wy
|
||||||
|
```
|
||||||
|
|
||||||
## Input-Output & Authentication
|
## Input-Output & Authentication
|
||||||
|
|
||||||
This system is intended to be used in a Matrix room where different Matrix accounts are adding and consuming information. For simplicity, I will stick to the adders and consumers terminology. The adders can be bots or people, whereas the consumers are intended to be bots only.
|
This system is intended to be used in a Matrix room where different Matrix accounts are adding and consuming information. For simplicity, I will stick to the adders and consumers terminology. The adders can be bots or people, whereas the consumers are intended to be bots only.
|
||||||
|
|
@ -48,4 +118,100 @@ When the person enters in `!report arizona Some Report` the two consumer bots sh
|
||||||
2. If the bot is set to only pay attention to specific region designators, check that `arizona` is in that set. Silently ignore the message if it isn't.
|
2. If the bot is set to only pay attention to specific region designators, check that `arizona` is in that set. Silently ignore the message if it isn't.
|
||||||
3. If the bot is set to only pay attention to specific users for the region designator `arizona`, check if the sending user is in that set. Silently ignore the message if it isn't.
|
3. If the bot is set to only pay attention to specific users for the region designator `arizona`, check if the sending user is in that set. Silently ignore the message if it isn't.
|
||||||
4. Run through its own code to process the message as it sees fit.
|
4. Run through its own code to process the message as it sees fit.
|
||||||
5. Optionally reply to the message saying that it was processed.
|
5. Optionally reply or react to the message saying that it was processed.
|
||||||
|
|
||||||
|
## Maubot Specifics
|
||||||
|
|
||||||
|
Here's some sample code and configuration layout to make plugin development easier.
|
||||||
|
|
||||||
|
## Sample Configuration
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Which regions the bot should pay attention to
|
||||||
|
# This can be either an empty list to allow any sender for this reigon,
|
||||||
|
# or can have a specified whitelist of senders
|
||||||
|
allowed_regions:
|
||||||
|
foo:
|
||||||
|
- "@reports:fiftyfiftyonerarizona.org"
|
||||||
|
bar:
|
||||||
|
- "@reports:example.org"
|
||||||
|
- "@reports:example.com"
|
||||||
|
buzz:
|
||||||
|
aaa:
|
||||||
|
```
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Bot-specific configurations per region
|
||||||
|
# The fields in each specific reigon should be the same, but their values should differ
|
||||||
|
# In this case (with NTFY), the bot should post notifications for each reigon
|
||||||
|
# to a different topic.
|
||||||
|
region_configs:
|
||||||
|
__global__:
|
||||||
|
# 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
|
||||||
|
server_username: "no"
|
||||||
|
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
|
||||||
|
server_use_authentication: true
|
||||||
|
server_username: "no"
|
||||||
|
server_password: "way"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Helper Functions
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 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 self.config["allowed_regions"][region]: 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
|
||||||
|
# Returns list of regions to process (strings)
|
||||||
|
# Currently just the specified region and "__global__"
|
||||||
|
def validateReport(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
|
||||||
|
|
||||||
|
self.log.debug(region)
|
||||||
|
|
||||||
|
# This is a list of regions to process for this specific message
|
||||||
|
# This is only used to consider __global__
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue