Refactored to use cogs. Joinraid seems to be working.

cogs/base.py

@@ -1,47 +0,0 @@
-from discord import Guild, Message, TextChannel
-from discord.ext import commands
-
-from storage import StateKey, Storage
-
-class BaseCog(commands.Cog):
-	def __init__(self, bot):
-		self.bot = bot
-
-	@classmethod
-	def save_setting(cls, guild: Guild, name: str, value):
-		"""
-		Saves one value to a guild's persisted state. The given value must
-		be a JSON-encodable type.
-		"""
-		if value is not None and not isinstance(value, (bool, int, float, str, list, dict)):
-			raise Exception(f'value for key {name} is not supported JSON type! {type(value)}')
-		state: dict = Storage.state_for_guild(guild)
-		if value is None:
-			del state[name]
-		else:
-			state[name] = value
-		Storage.save_guild_state(guild)
-
-	@classmethod
-	async def warn(cls, guild: Guild, message: str) -> bool:
-		"""
-		Sends a warning message to the configured warning channel for the
-		given guild. If no warning channel is configured no action is taken.
-		Returns True if the message was sent successfully or False if the
-		warning channel could not be found.
-		"""
-		state: dict = Storage.state_for_guild(guild)
-		channel_id = state.get(StateKey.WARNING_CHANNEL_ID)
-		if channel_id is None:
-			cls.guild_trace(guild, 'No warning channel set! No warning issued.')
-			return False
-		channel: TextChannel = guild.get_channel(channel_id)
-		if channel is None:
-			cls.guild_trace(guild, 'Configured warning channel no longer exists!')
-			return False
-		message: Message = await channel.send(message)
-		return message is not None
-
-	@classmethod
-	def guild_trace(cls, guild: Guild, message: str) -> None:
-		print(f'[guild {guild.id}|{guild.name}] {message}')

cogs/basecog.py

@@ -0,0 +1,49 @@
+from discord import Guild, Message, TextChannel
+from discord.ext import commands
+
+from storage import StateKey, Storage
+import json
+
+class BaseCog(commands.Cog):
+	def __init__(self, bot):
+		self.bot = bot
+
+	@classmethod
+	async def warn(cls, guild: Guild, message: str) -> Message:
+		"""
+		Sends a warning message to the configured warning channel for the
+		given guild. If no warning channel is configured no action is taken.
+		Returns the Message if successful or None if not.
+		"""
+		channel_id = Storage.get_state_value(guild, StateKey.WARNING_CHANNEL_ID)
+		if channel_id is None:
+			cls.guild_trace(guild, 'No warning channel set! No warning issued.')
+			return None
+		channel: TextChannel = guild.get_channel(channel_id)
+		if channel is None:
+			cls.guild_trace(guild, 'Configured warning channel does not exist!')
+			return None
+		mention: str = Storage.get_state_value(guild, StateKey.WARNING_MENTION)
+		text: str = message
+		if mention is not None:
+			text = f'{mention} {text}'
+		msg: Message = await channel.send(text)
+		return msg
+
+	@classmethod
+	async def update_warn(cls, warn_message: Message, new_text: str) -> None:
+		"""
+		Updates the text of a previously posted `warn`. Includes configured
+		mentions if necessary.
+		"""
+		text: str = new_text
+		mention: str = Storage.get_state_value(
+			warn_message.guild,
+			StateKey.WARNING_MENTION)
+		if mention is not None:
+			text = f'{mention} {text}'
+		await warn_message.edit(content=text)
+
+	@classmethod
+	def guild_trace(cls, guild: Guild, message: str) -> None:
+		print(f'[guild {guild.id}|{guild.name}] {message}')

cogs/config.py

@@ -1,36 +0,0 @@
-from discord import Guild, TextChannel
-from discord.ext import commands
-from storage import StateKey, Storage
-from cogs.base import BaseCog
-
-class ConfigCog(BaseCog):
-	"""
-	Cog for handling general bot configuration.
-	"""
-	def __init__(self, bot):
-		self.bot = bot
-
-	@commands.group(
-		brief='Manages general bot configuration'
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def config(self, context: commands.Context):
-		'Command group'
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
-	@config.command(
-		name='setwarningchannel',
-		brief='Sets the channel where mod warnings are posted',
-		description='Run this command in the channel where bot messages ' +
-			'intended for server moderators should be sent. Other bot messages ' +
-			'may still be posted in the channel a command was invoked in. If ' +
-			'no output channel is set, mod-related messages will not be posted!',
-	)
-	async def config_setwarningchannel(self, context: commands.Context):
-		'Command handler'
-		guild: Guild = context.guild
-		channel: TextChannel = context.channel
-		self.save_setting(guild, StateKey.WARNING_CHANNEL_ID, context.channel.id)
-		await context.message.reply(f'Warning channel set to {channel.name}', mention_author=False)

cogs/configcog.py

@@ -0,0 +1,96 @@
+from discord import Guild, TextChannel
+from discord.ext import commands
+from storage import StateKey, Storage
+from cogs.basecog import BaseCog
+
+class ConfigCog(BaseCog):
+	"""
+	Cog for handling general bot configuration.
+	"""
+	def __init__(self, bot):
+		self.bot = bot
+
+	@commands.group(
+		brief='Manages general bot configuration'
+	)
+	@commands.has_permissions(ban_members=True)
+	@commands.guild_only()
+	async def config(self, context: commands.Context):
+		'Command group'
+		if context.invoked_subcommand is None:
+			await context.send_help()
+
+	@config.command(
+		name='setwarningchannel',
+		brief='Sets the channel where mod warnings are posted',
+		description='Run this command in the channel where bot messages ' +
+			'intended for server moderators should be sent. Other bot messages ' +
+			'may still be posted in the channel a command was invoked in. If ' +
+			'no output channel is set, mod-related messages will not be posted!',
+	)
+	async def config_setwarningchannel(self, context: commands.Context) -> None:
+		'Command handler'
+		guild: Guild = context.guild
+		channel: TextChannel = context.channel
+		Storage.set_state_value(guild, StateKey.WARNING_CHANNEL_ID,
+			context.channel.id)
+		await context.message.reply(
+			f'Warning channel updated to {channel.mention}.',
+			mention_author=False)
+
+	@config.command(
+		name='getwarningchannel',
+		brief='Shows the channel where mod warnings are posted',
+	)
+	async def config_getwarningchannel(self, context: commands.Context) -> None:
+		'Command handler'
+		guild: Guild = context.guild
+		channel_id = Storage.get_state_value(guild, StateKey.WARNING_CHANNEL_ID)
+		if channel_id is None:
+			await context.message.reply(
+				'No warning channel is configured.',
+				mention_author=False)
+		else:
+			channel = guild.get_channel(channel_id)
+			await context.message.reply(
+				f'Warning channel is configured as {channel.mention}.',
+				mention_author=False)
+
+	@config.command(
+		name='setwarningmention',
+		brief='Sets a user/role to mention in warning messages',
+		usage='<@user|@role>',
+		description='Configures an role or other prefix to include at the ' +
+			'beginning of warning messages. If the intent is to get the ' +
+			'attention of certain users, be sure to specify a properly ' +
+			'formed @ tag, not just the name of the user/role.'
+	)
+	async def config_setwarningmention(self, context: commands.Context, mention: str = None) -> None:
+		guild: Guild = context.guild
+		Storage.set_state_value(guild, StateKey.WARNING_MENTION, mention)
+		if mention is None:
+			await context.message.reply(
+				'Warning messages will not tag anyone.',
+				mention_author=False)
+		else:
+			await context.message.reply(
+				f'Warning messages will now tag {mention}.',
+				mention_author=False)
+
+	@config.command(
+		name='getwarningmention',
+		brief='Shows the user/role to mention in warning messages',
+		description='Shows the text, if any, that will be prefixed on any ' +
+			'warning messages.'
+	)
+	async def config_getwarningmention(self, context: commands.Context) -> None:
+		guild: Guild = context.guild
+		mention: str = Storage.get_state_value(guild, StateKey.WARNING_MENTION)
+		if mention is None:
+			await context.message.reply(
+				'No warning mention configured.',
+				mention_author=False)
+		else:
+			await context.message.reply(
+				f'Warning messages will tag {mention}',
+				mention_author=False)

cogs/general.py

@@ -1,24 +0,0 @@
-from discord.ext import commands
-from cogs.base import BaseCog
-
-class GeneralCog(BaseCog):
-	def __init__(self, bot: commands.Bot):
-		self.bot = bot
-		self.is_connected = False
-		self.is_ready = False
-
-	@commands.Cog.listener()
-	async def on_connect(self):
-		print('on_connect')
-		self.is_connected = True
-
-	@commands.Cog.listener()
-	async def on_ready(self):
-		print('on_ready')
-		self.is_ready = True
-
-	@commands.command()
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def testwarn(self, context):
-		await self.warn(context.guild, 'Test warning')

cogs/generalcog.py

@@ -0,0 +1,39 @@
+from discord.ext import commands
+from cogs.basecog import BaseCog
+from storage import StateKey, Storage
+
+class GeneralCog(BaseCog):
+	def __init__(self, bot: commands.Bot):
+		self.bot = bot
+		self.is_connected = False
+		self.is_ready = False
+
+	@commands.Cog.listener()
+	async def on_connect(self):
+		print('on_connect')
+		self.is_connected = True
+
+	@commands.Cog.listener()
+	async def on_ready(self):
+		print('on_ready')
+		self.is_ready = True
+
+	@commands.command(
+		brief='Posts a test warning in the configured warning channel.'
+	)
+	@commands.has_permissions(ban_members=True)
+	@commands.guild_only()
+	async def testwarn(self, context):
+		if Storage.get_state_value(context.guild, StateKey.WARNING_CHANNEL_ID) is None:
+			await context.message.reply(
+				'No warning channel set!',
+				mention_author=False)
+		else:
+			await self.warn(context.guild,
+				f'Test warning message (requested by {context.author.name})')
+
+	@commands.command()
+	async def hello(self, context):
+		await context.message.reply(
+			f'Hey, {context.author.name}!',
+		 	mention_author=False)

cogs/joinraid.py

@@ -1,232 +0,0 @@
-from discord import Guild, Intents, Member, Message, PartialEmoji, RawReactionActionEvent
-from discord.ext import commands
-from storage import Storage
-from cogs.base import BaseCog
-
-class JoinRecord:
-    """
-    Data object containing details about a guild join event.
-    """
-    def __init__(self, member: Member):
-        self.member = member
-        self.join_time = member.joined_at or datetime.now()
-        self.is_kicked = False
-        self.is_banned = False
-
-    def age_seconds(self, now: datetime) -> float:
-        """
-        Returns the age of this join in seconds from the given "now" time.
-        """
-        a = now - self.join_time
-        return float(a.total_seconds())
-
-class RaidPhase:
-    """
-    Enum of phases in a JoinRaid. Phases progress monotonically.
-    """
-    NONE = 0
-    JUST_STARTED = 1
-    CONTINUING = 2
-    ENDED = 3
-
-class JoinRaid:
-    """
-    Tracks recent joins to a guild to detect join raids, where a large number of automated users
-    all join at the same time.
-    """
-    def __init__(self):
-        self.joins = []
-        self.phase = RaidPhase.NONE
-        # datetime when the raid started, or None.
-        self.raid_start_time = None
-        # Message posted to Discord to warn of the raid. Convenience property managed
-        # by caller. Ignored by this class.
-        self.warning_message = None
-
-    def handle_join(self,
-            member: Member,
-            now: datetime,
-            max_age_seconds: float,
-            max_join_count: int) -> None:
-        """
-        Processes a new member join to a guild and detects join raids. Updates
-        self.phase and self.raid_start_time properties.
-        """
-        # Check for existing record for this user
-        print(f'handle_join({member.name}) start')
-        join: JoinRecord = None
-        i: int = 0
-        while i < len(self.joins):
-            elem = self.joins[i]
-            if elem.member.id == member.id:
-                print(f'Member {member.name} already in join list at index {i}. Removing.')
-                join = self.joins.pop(i)
-                join.join_time = now
-                break
-            i += 1
-        # Add new record to end
-        self.joins.append(join or JoinRecord(member))
-        # Check raid status and do upkeep
-        self.__process_joins(now, max_age_seconds, max_join_count)
-        print(f'handle_join({member.name}) end')
-
-    def __process_joins(self,
-            now: datetime,
-            max_age_seconds: float,
-            max_join_count: int) -> None:
-        """
-        Processes self.joins after each addition, detects raids, updates self.phase,
-        and throws out unneeded records.
-        """
-        print('__process_joins {')
-        i: int = 0
-        recent_count: int = 0
-        should_cull: bool = self.phase == RaidPhase.NONE
-        while i < len(self.joins):
-            join: JoinRecord = self.joins[i]
-            age: float = join.age_seconds(now)
-            is_old: bool = age > max_age_seconds
-            if not is_old:
-                recent_count += 1
-                print(f'- {i}. {join.member.name} is {age}s old - recent_count={recent_count}')
-            if is_old and should_cull:
-                self.joins.pop(i)
-                print(f'- {i}. {join.member.name} is {age}s old - too old, removing')
-            else:
-                print(f'- {i}. {join.member.name} is {age}s old - moving on to next')
-                i += 1
-        is_raid = recent_count > max_join_count
-        print(f'- is_raid {is_raid}')
-        if is_raid:
-            if self.phase == RaidPhase.NONE:
-                self.phase = RaidPhase.JUST_STARTED
-                self.raid_start_time = now
-                print('- Phase moved to JUST_STARTED. Recording raid start time.')
-            elif self.phase == RaidPhase.JUST_STARTED:
-                self.phase = RaidPhase.CONTINUING
-                print('- Phase moved to CONTINUING.')
-        elif self.phase == self.phase in (RaidPhase.JUST_STARTED, RaidPhase.CONTINUING):
-            self.phase = RaidPhase.ENDED
-            print('- Phase moved to ENDED.')
-
-        # Undo join add if the raid is over
-        if self.phase == RaidPhase.ENDED and len(self.joins) > 0:
-            last = self.joins.pop(-1)
-            print(f'- Popping last join for {last.member.name}')
-        print('} __process_joins')
-
-    async def kick_all(self,
-            reason: str = "Part of join raid") -> list[Member]:
-        """
-        Kicks all users in this join raid. Skips users who have already been
-        flagged as having been kicked or banned. Returns a List of Members
-        who were newly kicked.
-        """
-        kicks = []
-        for join in self.joins:
-            if join.is_kicked or join.is_banned:
-                continue
-            await join.member.kick(reason=reason)
-            join.is_kicked = True
-            kicks.append(join.member)
-        self.phase = RaidPhase.ENDED
-        return kicks
-
-    async def ban_all(self,
-            reason: str = "Part of join raid",
-            delete_message_days: int = 0) -> list[Member]:
-        """
-        Bans all users in this join raid. Skips users who have already been
-        flagged as having been banned. Users who were previously kicked can
-        still be banned. Returns a List of Members who were newly banned.
-        """
-        bans = []
-        for join in self.joins:
-            if join.is_banned:
-                continue
-            await join.member.ban(reason=reason, delete_message_days=delete_message_days)
-            join.is_banned = True
-            bans.append(join.member)
-        self.phase = RaidPhase.ENDED
-        return bans
-
-class JoinRaidCog(BaseCog):
-	"""
-	Cog for monitoring member joins and detecting potential bot raids.
-	"""
-	def __init__(self, bot):
-		self.bot = bot
-
-	@commands.group(
-		brief='Manages join raid detection and handling',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def joinraid(self, context: commands.Context):
-		'Command group'
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
-	@joinraid.command(
-		name='enable',
-		brief='Enables join raid detection',
-		description='Join raid detection is off by default.',
-	)
-	async def joinraid_enable(self, context: commands.Context):
-		'Command handler'
-		# TODO
-		pass
-
-	@joinraid.command(
-		name='disable',
-		brief='Disables join raid detection',
-		description='Join raid detection is off by default.',
-	)
-	async def joinraid_disable(self, context: commands.Context):
-		'Command handler'
-		# TODO
-		pass
-
-	@joinraid.command(
-		name='setrate',
-		brief='Sets the rate of joins which triggers a warning to mods',
-		description='Each time a member joins, the join records from the ' +
-			'previous _x_ seconds are counted up, where _x_ is the number of ' +
-			'seconds configured by this command. If that count meets or ' +
-			'exceeds the maximum join count configured by this command then ' +
-			'a raid is detected and a warning is issued to the mods.',
-		usage='<join_count> <seconds>',
-	)
-	async def joinraid_setrate(self, context: commands.Context,
-			joinCount: int,
-			seconds: int):
-		'Command handler'
-		# TODO
-		pass
-
-	@joinraid.command(
-		name='getrate',
-		brief='Shows the rate of joins which triggers a warning to mods',
-	)
-	async def joinraid_getrate(self, context: commands.Context):
-		'Command handler'
-		# TODO
-		pass
-
-	@commands.Cog.listener()
-	async def on_raw_reaction_add(self, payload: RawReactionActionEvent):
-		'Event handler'
-		# TODO
-		pass
-
-	@commands.Cog.listener()
-	async def on_member_join(self, member: Member) -> None:
-		'Event handler'
-		# TODO
-		pass
-
-	async def __send_warning(self) -> None:
-		config = self.bot.get_cog('ConfigCog')
-		if config is None:
-			return
-		config.

cogs/joinraidcog.py

@@ -0,0 +1,523 @@
+from discord import Guild, Intents, Member, Message, PartialEmoji, RawReactionActionEvent
+from discord.ext import commands
+from storage import Storage
+from cogs.basecog import BaseCog
+from config import CONFIG
+from datetime import datetime
+
+class JoinRecord:
+    """
+    Data object containing details about a single guild join event.
+    """
+    def __init__(self, member: Member):
+        self.member = member
+        self.join_time = member.joined_at or datetime.now()
+        # These flags only track whether this bot has kicked/banned
+        self.is_kicked = False
+        self.is_banned = False
+
+    def age_seconds(self, now: datetime) -> float:
+        """
+        Returns the age of this join in seconds from the given "now" time.
+        """
+        a = now - self.join_time
+        return float(a.total_seconds())
+
+class RaidPhase:
+    """
+    Enum of phases in a JoinRaidRecord. Phases progress monotonically.
+    """
+    NONE = 0
+    JUST_STARTED = 1
+    CONTINUING = 2
+    ENDED = 3
+
+class JoinRaidRecord:
+    """
+    Tracks recent joins to a guild to detect join raids, where a large number
+    of automated users all join at the same time. Manages list of joins to not
+    grow unbounded.
+    """
+    def __init__(self):
+        self.joins = []
+        self.phase = RaidPhase.NONE
+        # datetime when the raid started, or None.
+        self.raid_start_time = None
+        # Message posted to Discord to warn of the raid. Convenience property
+        # managed by caller. Ignored by this class.
+        self.warning_message = None
+
+    def handle_join(self,
+            member: Member,
+            now: datetime,
+            max_join_count: int,
+            max_age_seconds: float) -> None:
+        """
+        Processes a new member join to a guild and detects join raids. Updates
+        self.phase and self.raid_start_time properties.
+        """
+        # Check for existing record for this user
+        print(f'handle_join({member.name}) start')
+        join: JoinRecord = None
+        i: int = 0
+        while i < len(self.joins):
+            elem = self.joins[i]
+            if elem.member.id == member.id:
+                print(f'Member {member.name} already in join list at index {i}. Removing.')
+                join = self.joins.pop(i)
+                join.join_time = now
+                break
+            i += 1
+        # Add new record to end
+        self.joins.append(join or JoinRecord(member))
+        # Check raid status and do upkeep
+        self.__process_joins(now, max_age_seconds, max_join_count)
+        print(f'handle_join({member.name}) end')
+
+    def __process_joins(self,
+            now: datetime,
+            max_age_seconds: float,
+            max_join_count: int) -> None:
+        """
+        Processes self.joins after each addition, detects raids, updates
+        self.phase, and throws out unneeded records.
+        """
+        print('__process_joins {')
+        i: int = 0
+        recent_count: int = 0
+        should_cull: bool = self.phase == RaidPhase.NONE
+        while i < len(self.joins):
+            join: JoinRecord = self.joins[i]
+            age: float = join.age_seconds(now)
+            is_old: bool = age > max_age_seconds
+            if not is_old:
+                recent_count += 1
+                print(f'- {i}. {join.member.name} is {age}s old - recent_count={recent_count}')
+            if is_old and should_cull:
+                self.joins.pop(i)
+                print(f'- {i}. {join.member.name} is {age}s old - too old, removing')
+            else:
+                print(f'- {i}. {join.member.name} is {age}s old - moving on to next')
+                i += 1
+        is_raid = recent_count > max_join_count
+        print(f'- is_raid {is_raid}')
+        if is_raid:
+            if self.phase == RaidPhase.NONE:
+                self.phase = RaidPhase.JUST_STARTED
+                self.raid_start_time = now
+                print('- Phase moved to JUST_STARTED. Recording raid start time.')
+            elif self.phase == RaidPhase.JUST_STARTED:
+                self.phase = RaidPhase.CONTINUING
+                print('- Phase moved to CONTINUING.')
+        elif self.phase == self.phase in (RaidPhase.JUST_STARTED, RaidPhase.CONTINUING):
+            self.phase = RaidPhase.ENDED
+            print('- Phase moved to ENDED.')
+
+        # Undo join add if the raid is over
+        if self.phase == RaidPhase.ENDED and len(self.joins) > 0:
+            last = self.joins.pop(-1)
+            print(f'- Popping last join for {last.member.name}')
+        print('} __process_joins')
+
+    async def kick_all(self,
+            reason: str = "Part of join raid") -> list[Member]:
+        """
+        Kicks all users in this join raid. Skips users who have already been
+        flagged as having been kicked or banned. Returns a List of Members
+        who were newly kicked.
+        """
+        kicks = []
+        for join in self.joins:
+            if join.is_kicked or join.is_banned:
+                continue
+            await join.member.kick(reason=reason)
+            join.is_kicked = True
+            kicks.append(join.member)
+        self.phase = RaidPhase.ENDED
+        return kicks
+
+    async def ban_all(self,
+            reason: str = "Part of join raid",
+            delete_message_days: int = 0) -> list[Member]:
+        """
+        Bans all users in this join raid. Skips users who have already been
+        flagged as having been banned. Users who were previously kicked can
+        still be banned. Returns a List of Members who were newly banned.
+        """
+        bans = []
+        for join in self.joins:
+            if join.is_banned:
+                continue
+            await join.member.ban(
+                reason=reason,
+                delete_message_days=delete_message_days)
+            join.is_banned = True
+            bans.append(join.member)
+        self.phase = RaidPhase.ENDED
+        return bans
+
+class GuildContext:
+    """
+    Logic and state for a single guild serviced by the bot.
+    """
+    def __init__(self, guild_id: int):
+        self.guild_id = guild_id
+        self.join_warning_count = CONFIG['joinWarningCount']
+        self.join_warning_seconds = CONFIG['joinWarningSeconds']
+        # Non-persisted runtime state
+        self.current_raid = JoinRaidRecord()
+        self.all_raids = [ self.current_raid ] # periodically culled of old ones
+
+    # Events
+
+    async def handle_join(self, member: Member) -> None:
+        """
+        Event handler for all joins to this guild.
+        """
+        now = member.joined_at
+        raid = self.current_raid
+        raid.handle_join(
+            member,
+            now=now,
+            max_age_seconds = self.join_warning_seconds,
+            max_join_count = self.join_warning_count)
+        self.__trace(f'raid phase: {raid.phase}')
+        if raid.phase == RaidPhase.JUST_STARTED:
+            await self.__on_join_raid_begin(raid)
+        elif raid.phase == RaidPhase.CONTINUING:
+            await self.__on_join_raid_updated(raid)
+        elif raid.phase == RaidPhase.ENDED:
+            self.__start_new_raid(member)
+            await self.__on_join_raid_end(raid)
+        self.__cull_old_raids(now)
+
+    def reset_raid(self, now: datetime):
+        """
+        Retires self.current_raid and creates a new empty one.
+        """
+        self.current_raid = JoinRaidRecord()
+        self.all_raids.append(self.current_raid)
+        self.__cull_old_raids(now)
+
+    def find_raid_for_message_id(self, message_id: int) -> JoinRaidRecord:
+        """
+        Retrieves a JoinRaidRecord instance for the given raid warning message.
+        Returns None if not found.
+        """
+        for raid in self.all_raids:
+            if raid.warning_message.id == message_id:
+                return raid
+        return None
+
+    def __cull_old_raids(self, now: datetime):
+        """
+        Gets rid of old JoinRaidRecord records from self.all_raids that are too
+        old to still be useful.
+        """
+        i: int = 0
+        while i < len(self.all_raids):
+            raid = self.all_raids[i]
+            if raid == self.current_raid:
+                i += 1
+                continue
+            age_seconds = float((raid.raid_start_time - now).total_seconds())
+            if age_seconds > 86400.0:
+                self.__trace('Culling old raid')
+                self.all_raids.pop(i)
+            else:
+                i += 1
+
+    def __trace(self, message):
+        """
+        Debugging trace.
+        """
+        print(f'{self.guild_id}: {message}')
+
+class JoinRaidCog(BaseCog):
+    """
+    Cog for monitoring member joins and detecting potential bot raids.
+    """
+    MIN_JOIN_COUNT = 2
+
+    STATE_KEY_RAID_COUNT = 'joinraid_count'
+    STATE_KEY_RAID_SECONDS = 'joinraid_seconds'
+    STATE_KEY_ENABLED = 'joinraid_enabled'
+
+    def __init__(self, bot):
+        self.bot = bot
+        self.guild_id_to_context = {}  # Guild.id -> GuildContext
+
+    # -- Config -------------------------------------------------------------
+
+    def __get_raid_rate(self, guild: Guild) -> tuple:
+        """
+        Returns the join rate configured for this guild.
+        """
+        count: int = Storage.get_state_value(guild, self.STATE_KEY_RAID_COUNT) \
+            or CONFIG['joinWarningCount']
+        seconds: float = Storage.get_state_value(guild, self.STATE_KEY_RAID_SECONDS) \
+            or CONFIG['joinWarningSeconds']
+        return (count, seconds)
+
+    def __is_enabled(self, guild: Guild) -> bool:
+        """
+        Returns whether join raid detection is enabled in this guild.
+        """
+        return Storage.get_state_value(guild, self.STATE_KEY_ENABLED) or False
+
+    # -- Commands -----------------------------------------------------------
+
+    @commands.group(
+        brief='Manages join raid detection and handling',
+    )
+    @commands.has_permissions(ban_members=True)
+    @commands.guild_only()
+    async def joinraid(self, context: commands.Context):
+        'Command group'
+        if context.invoked_subcommand is None:
+            await context.send_help()
+
+    @joinraid.command(
+        name='enable',
+        brief='Enables join raid detection',
+        description='Join raid detection is off by default.',
+    )
+    async def joinraid_enable(self, context: commands.Context):
+        'Command handler'
+        guild = context.guild
+        Storage.set_state_value(guild, self.STATE_KEY_ENABLED, True)
+        # TODO: Startup tracking if necessary
+        await context.message.reply(
+            '✅ ' + self.__describe_raid_settings(guild, force_enabled_status=True),
+            mention_author=False)
+
+    @joinraid.command(
+        name='disable',
+        brief='Disables join raid detection',
+        description='Join raid detection is off by default.',
+    )
+    async def joinraid_disable(self, context: commands.Context):
+        'Command handler'
+        guild = context.guild
+        Storage.set_state_value(guild, self.STATE_KEY_ENABLED, False)
+        # TODO: Tear down tracking if necessary
+        await context.message.reply(
+            '✅ ' + self.__describe_raid_settings(guild, force_enabled_status=True),
+            mention_author=False)
+
+    @joinraid.command(
+        name='setrate',
+        brief='Sets the rate of joins which triggers a warning to mods',
+        description='Each time a member joins, the join records from the ' +
+            'previous _x_ seconds are counted up, where _x_ is the number of ' +
+            'seconds configured by this command. If that count meets or ' +
+            'exceeds the maximum join count configured by this command then ' +
+            'a raid is detected and a warning is issued to the mods.',
+        usage='<join_count:int> <seconds:float>',
+    )
+    async def joinraid_setrate(self, context: commands.Context,
+            join_count: int,
+            seconds: float):
+        'Command handler'
+        guild = context.guild
+        if join_count < self.MIN_JOIN_COUNT:
+            await context.message.reply(
+                f'⚠️ `join_count` must be >= {self.MIN_JOIN_COUNT}',
+                mention_author=False)
+            return
+        if seconds <= 0:
+            await context.message.reply(
+                f'⚠️ `seconds` must be > 0',
+                mention_author=False)
+            return
+        Storage.set_state_values(guild, {
+            self.STATE_KEY_RAID_COUNT: join_count,
+            self.STATE_KEY_RAID_SECONDS: seconds,
+        })
+
+        await context.message.reply(
+            '✅ ' + self.__describe_raid_settings(guild, force_rate_status=True),
+            mention_author=False)
+
+    @joinraid.command(
+        name='getrate',
+        brief='Shows the rate of joins which triggers a warning to mods',
+    )
+    async def joinraid_getrate(self, context: commands.Context):
+        'Command handler'
+        await context.message.reply(
+            'ℹ️ ' + self.__describe_raid_settings(context.guild, force_rate_status=True),
+            mention_author=False)
+
+    # -- Listeners ----------------------------------------------------------
+
+    @commands.Cog.listener()
+    async def on_raw_reaction_add(self, payload: RawReactionActionEvent):
+        'Event handler'
+        if payload.user_id == self.bot.user.id:
+            # Ignore bot's own reactions
+            return
+        member: Member = payload.member
+        if member is None:
+            return
+        guild: Guild = self.bot.get_guild(payload.guild_id)
+        if guild is None:
+            # Possibly a DM
+            return
+        channel: GuildChannel = guild.get_channel(payload.channel_id)
+        if channel is None:
+            # Possibly a DM
+            return
+        message: Message = await channel.fetch_message(payload.message_id)
+        if message is None:
+            # Message deleted?
+            return
+        if message.author.id != self.bot.user.id:
+            # Bot didn't author this
+            return
+        if not member.permissions_in(channel).ban_members:
+            # Not a mod
+            # TODO: Remove reaction?
+            return
+        gc: GuildContext = self.__get_guild_context(guild)
+        raid: JoinRaidRecord = gc.find_raid_for_message_id(payload.message_id)
+        if raid is None:
+            # Either not a warning message or one we stopped tracking
+            return
+        emoji: PartialEmoji = payload.emoji
+        if emoji.name == CONFIG['kickEmoji']:
+            await raid.kick_all()
+            gc.reset_raid(message.created_at)
+            await self.__update_raid_warning(guild, raid)
+        elif emoji.name == CONFIG['banEmoji']:
+            await raid.ban_all()
+            gc.reset_raid(message.created_at)
+            await self.__update_raid_warning(guild, raid)
+
+    @commands.Cog.listener()
+    async def on_member_join(self, member: Member) -> None:
+        'Event handler'
+        guild: Guild = member.guild
+        if not self.__is_enabled(guild):
+            return
+        (count, seconds) = self.__get_raid_rate(guild)
+        now = member.joined_at
+        gc: GuildContext = self.__get_guild_context(guild)
+        raid: JoinRaidRecord = gc.current_raid
+        raid.handle_join(member, now, count, seconds)
+        if raid.phase == RaidPhase.JUST_STARTED:
+            await self.__post_raid_warning(guild, raid)
+        elif raid.phase == RaidPhase.CONTINUING:
+            await self.__update_raid_warning(guild, raid)
+        elif raid.phase == RaidPhase.ENDED:
+            # First join that occurred too late to be part of last raid. Join
+            # not added. Start a new raid record and add it there.
+            gc.reset_raid(now)
+            gc.current_raid.handle_join(member, now, count, seconds)
+
+    # -- Misc ---------------------------------------------------------------
+
+    def __describe_raid_settings(self,
+            guild: Guild,
+            force_enabled_status=False,
+            force_rate_status=False) -> str:
+        """
+        Creates a Discord message describing the current join raid settings.
+        """
+        enabled = self.__is_enabled(guild)
+        (count, seconds) = self.__get_raid_rate(guild)
+
+        sentences = []
+
+        if enabled or force_rate_status:
+            sentences.append(f'Join raids will be detected at {count} or more joins per {seconds} seconds.')
+
+        if enabled and force_enabled_status:
+                sentences.append('Raid detection enabled.')
+        elif not enabled:
+            sentences.append('Raid detection disabled.')
+
+        tips = []
+        if enabled or force_rate_status:
+            tips.append('• Use `setrate` subcommand to change detection threshold')
+        if enabled:
+            tips.append('• Use `disable` subcommand to disable detection.')
+        else:
+            tips.append('• Use `enable` subcommand to enable detection.')
+
+        message = ''
+        message += ' '.join(sentences)
+        if len(tips) > 0:
+            message += '\n\n' + ('\n'.join(tips))
+        return message
+
+    def __get_guild_context(self, guild: Guild) -> GuildContext:
+        """
+        Looks up the GuildContext for the given Guild or creates a new one if
+        one does not yet exist.
+        """
+        gc: GuildContext = self.guild_id_to_context.get(guild.id)
+        if gc is not None:
+            return gc
+        gc = GuildContext(guild.id)
+        self.guild_id_to_context[guild.id] = gc
+        return gc
+
+    async def __post_raid_warning(self, guild: Guild, raid: JoinRaidRecord) -> None:
+        """
+        Posts a warning message about the given raid.
+        """
+        (message, can_kick, can_ban) = self.__describe_raid(raid)
+        raid.warning_message = await self.warn(guild, message)
+        if can_kick:
+            await raid.warning_message.add_reaction(CONFIG['kickEmoji'])
+        if can_ban:
+            await raid.warning_message.add_reaction(CONFIG['banEmoji'])
+
+    async def __update_raid_warning(self, guild: Guild, raid: JoinRaidRecord) -> None:
+        """
+        Updates the existing warning message for a raid.
+        """
+        if raid.warning_message is None:
+            return
+        (message, can_kick, can_ban) = self.__describe_raid(raid)
+        await self.update_warn(raid.warning_message, message)
+        if not can_kick:
+            await raid.warning_message.clear_reaction(CONFIG['kickEmoji'])
+        if not can_ban:
+            await raid.warning_message.clear_reaction(CONFIG['banEmoji'])
+
+    def __describe_raid(self, raid: JoinRaidRecord) -> tuple:
+        """
+        Creates a Discord warning message with details about the given raid.
+        Returns a tuple containing the message text, a flag if any users can
+        still be kicked, and a flag if anyone can still be banned.
+        """
+        message = '🚨 **JOIN RAID DETECTED** 🚨'
+        message += '\nThe following members joined in close succession:\n'
+        any_kickable = False
+        any_bannable = False
+        for join in raid.joins:
+            message += '\n• '
+            if join.is_banned:
+                message += '~~' + join.member.mention + '~~ - banned'
+            elif join.is_kicked:
+                message += '~~' + join.member.mention + '~~ - kicked'
+                any_bannable = True
+            else:
+                message += join.member.mention
+                any_bannable = True
+                any_kickable = True
+        message += '\n_(list updates automatically)_'
+
+        message += '\n'
+        if any_kickable:
+            message += f'\nReact to this message with {CONFIG["kickEmoji"]} to kick all these users.'
+        else:
+            message += '\nNo users left to kick.'
+        if any_bannable:
+            message += f'\nReact to this message with {CONFIG["banEmoji"]} to ban all these users.'
+        else:
+            message += '\nNo users left to ban.'
+
+        return (message, any_kickable, any_bannable)

rocketbot.py

@@ -5,623 +5,23 @@ the sqlite database rocketbot.db (copy rocketbot.db.sample for a blank database)
 Author: Ian Albert (@rocketsoup)
 Date: 2021-11-11
 """
-from datetime import datetime
-import sqlite3
-import sys
-
-from discord import Guild, Intents, Member, Message, PartialEmoji, RawReactionActionEvent
-from discord.abc import GuildChannel
+from discord import Intents
 from discord.ext import commands
-from discord.ext.commands.context import Context
 
 from config import CONFIG
-from cogs.config import ConfigCog
-from cogs.general import GeneralCog
+from cogs.configcog import ConfigCog
+from cogs.generalcog import GeneralCog
+from cogs.joinraidcog import JoinRaidCog
 
 class Rocketbot(commands.Bot):
     def __init__(self, command_prefix, **kwargs):
         super().__init__(command_prefix, **kwargs)
 
-bot = Rocketbot(CONFIG['commandPrefix'])
+intents = Intents.default()
+intents.members = True # To get join/leave events
+bot = Rocketbot(command_prefix=CONFIG['commandPrefix'], intents=intents)
 bot.add_cog(GeneralCog(bot))
 bot.add_cog(ConfigCog(bot))
+bot.add_cog(JoinRaidCog(bot))
 bot.run(CONFIG['clientToken'], bot=True, reconnect=True)
 print('\nBot aborted')
-
-# -- Classes ----------------------------------------------------------------
-
-# class GuildContext:
-#     """
-#     Logic and state for a single guild serviced by the bot.
-#     """
-#     def __init__(self, guild_id: int):
-#         self.guild_id = guild_id
-#         self.guild = None # Resolved later
-#         # Config populated during load
-#         self.warning_channel_id = None
-#         self.warning_channel = None
-#         self.warning_mention = None
-#         self.join_warning_count = CONFIG['joinWarningCount']
-#         self.join_warning_seconds = CONFIG['joinWarningSeconds']
-#         # Non-persisted runtime state
-#         self.current_raid = JoinRaid()
-#         self.all_raids = [ self.current_raid ] # periodically culled of old ones
-
-#     # Commands
-
-#     async def command_hello(self, message: Message) -> None:
-#         """
-#         Command handler
-#         """
-#         await message.channel.send(f'Hey there, {message.author.mention}!')
-
-#     async def command_testwarn(self, context: Context) -> None:
-#         """
-#         Command handler
-#         """
-#         if self.warning_channel is None:
-#             self.__trace('No warning channel set!')
-#             await context.message.channel.send('No warning channel set on this guild! Type ' +
-#                 f'`{bot.command_prefix}{setwarningchannel.__name__}` in the channel you ' +
-#                 'want warnings to be posted.')
-#             return
-#         await self.__warn('Test warning. This is only a test.')
-
-#     async def command_setwarningchannel(self, context: Context):
-#         """
-#         Command handler
-#         """
-#         self.__trace(f'Warning channel set to {context.channel.name}')
-#         self.warning_channel = context.channel
-#         self.warning_channel_id = context.channel.id
-#         save_guild_context(self)
-#         await self.__warn('Warning messages will now be sent to ' + self.warning_channel.mention)
-
-#     async def command_setwarningmention(self, _context: Context, mention: str):
-#         """
-#         Command handler
-#         """
-#         self.__trace('set warning mention')
-#         m = mention if mention is not None and len(mention) > 0 else None
-#         self.warning_mention = m
-#         save_guild_context(self)
-#         if m is None:
-#             await self.__warn('Warning messages will not mention anyone')
-#         else:
-#             await self.__warn('Warning messages will now mention ' + m)
-
-#     async def command_setraidwarningrate(self, _context: Context, count: int, seconds: int):
-#         """
-#         Command handler
-#         """
-#         self.join_warning_count = count
-#         self.join_warning_seconds = seconds
-#         save_guild_context(self)
-#         await self.__warn(f'Maximum join rate set to {count} joins per {seconds} seconds')
-
-#     # Events
-
-#     async def handle_join(self, member: Member) -> None:
-#         """
-#         Event handler for all joins to this guild.
-#         """
-#         print(f'{member.guild.name}: {member.name} joined')
-#         now = member.joined_at
-#         raid = self.current_raid
-#         raid.handle_join(
-#             member,
-#             now=now,
-#             max_age_seconds = self.join_warning_seconds,
-#             max_join_count = self.join_warning_count)
-#         self.__trace(f'raid phase: {raid.phase}')
-#         if raid.phase == RaidPhase.JUST_STARTED:
-#             await self.__on_join_raid_begin(raid)
-#         elif raid.phase == RaidPhase.CONTINUING:
-#             await self.__on_join_raid_updated(raid)
-#         elif raid.phase == RaidPhase.ENDED:
-#             self.__start_new_raid(member)
-#             await self.__on_join_raid_end(raid)
-#         self.__cull_old_raids(now)
-
-#     def __start_new_raid(self, member: Member = None):
-#         """
-#         Retires self.current_raid and creates a new empty one. If `member` is passed, it will be
-#         added to the new self.current_raid after it is created.
-#         """
-#         self.current_raid = JoinRaid()
-#         self.all_raids.append(self.current_raid)
-#         if member is not None:
-#             self.current_raid.handle_join(
-#                 member,
-#                 member.joined_at,
-#                 max_age_seconds = self.join_warning_seconds,
-#                 max_join_count = self.join_warning_count)
-
-#     async def handle_reaction_add(self, message, member, emoji):
-#         """
-#         Handles all message reaction events to see if they need to be acted on.
-#         """
-#         if member.id == bot.user.id:
-#             # It's-a me, Rocketbot!
-#             return
-#         if message.author.id != bot.user.id:
-#             # The message the user is reacting to wasn't authored by me. Ignore.
-#             return
-#         self.__trace(f'User {member} added emoji {emoji}')
-#         if not member.permissions_in(message.channel).ban_members:
-#             self.__trace('Reactor does not have ban permissions. Ignoring.')
-#             return
-#         if emoji.name == CONFIG['kickEmoji']:
-#             await self.__kick_all_in_raid_message(message)
-#         elif emoji.name == CONFIG['banEmoji']:
-#             await self.__ban_all_in_raid_message(message)
-#         else:
-#             print('Unhandled emoji. Ignoring.')
-#             return
-
-#     async def __kick_all_in_raid_message(self, message: Message):
-#         """
-#         Kicks all the users mentioned in the given raid warning message. Users who were already
-#         kicked or banned will be skipped.
-#         """
-#         raid = self.__find_raid_for_message(message)
-#         if raid is None:
-#             await message.reply("This is either not a raid warning or it's too old and I don't " +
-#                 "have a record for it anymore. Sorry!")
-#             return
-#         self.__trace('Kicking...')
-#         members = await raid.kick_all()
-#         msg = 'Kicked these members:'
-#         for member in members:
-#             msg += f'\n\t{member.name}'
-#         if len(members) == 0:
-#             msg += '\n\t-none-'
-#         self.__trace(msg)
-#         self.__start_new_raid()
-#         await self.__update_join_raid_message(raid)
-
-#     async def __ban_all_in_raid_message(self, message: Message):
-#         """
-#         Bans all the users mentioned in the given raid warning message. Users who were already
-#         banned will be skipped.
-#         """
-#         raid = self.__find_raid_for_message(message)
-#         if raid is None:
-#             await message.reply("This is either not a raid warning or it's too old and I don't " +
-#                 "have a record for it anymore. Sorry!")
-#             return
-#         self.__trace('Banning...')
-#         members = await raid.ban_all()
-#         msg = 'Banned these members:'
-#         for member in members:
-#             msg += f'\n\t{member.name}'
-#         if len(members) == 0:
-#             msg += '\n\t-none-'
-#         self.__trace(msg)
-#         self.__start_new_raid()
-#         await self.__update_join_raid_message(raid)
-
-#     def __find_raid_for_message(self, message: Message) -> JoinRaid:
-#         """
-#         Retrieves a JoinRaid instance for the given raid warning message. Returns None if not found.
-#         """
-#         for raid in self.all_raids:
-#             if raid.warning_message.id == message.id:
-#                 return raid
-#         return None
-
-#     def __cull_old_raids(self, now: datetime):
-#         """
-#         Gets rid of old JoinRaid records from self.all_raids that are too old to still be useful.
-#         """
-#         i: int = 0
-#         while i < len(self.all_raids):
-#             raid = self.all_raids[i]
-#             if raid == self.current_raid:
-#                 i += 1
-#                 continue
-#             age_seconds = float((raid.raid_start_time - now).total_seconds())
-#             if age_seconds > 86400.0:
-#                 self.__trace('Culling old raid')
-#                 self.all_raids.pop(i)
-#             else:
-#                 i += 1
-
-#     def __join_raid_message(self, raid: JoinRaid):
-#         """
-#         Returns a 3-element tuple containing a text message appropriate for posting in
-#         Discord, a flag of whether any of the mentioned users can be kicked, and a flag
-#         of whether any of the mentioned users can be banned.
-#         """
-#         message = ''
-#         if self.warning_mention is not None:
-#             message = self.warning_mention + ' '
-#         message += '**RAID JOIN DETECTED!** It includes these users:\n'
-#         can_kick = False
-#         can_ban = False
-#         for join in raid.joins:
-#             message += '\n• '
-#             if join.is_banned:
-#                 message += '~~' + join.member.mention + '~~ - banned'
-#             elif join.is_kicked:
-#                 message += '~~' + join.member.mention + '~~ - kicked'
-#                 can_ban = True
-#             else:
-#                 message += join.member.mention
-#                 can_kick = True
-#                 can_ban = True
-#         message += '\n'
-#         if can_kick:
-#             message += '\nTo kick all these users, react with :' + CONFIG['kickEmojiName'] + ':'
-#         else:
-#             message += '\nNo kickable users remain'
-#         if can_ban:
-#             message += '\nTo ban all these users, react with :' + CONFIG['banEmojiName'] + ':'
-#         else:
-#             message += '\nNo bannable users remain'
-#         return (message, can_kick, can_ban)
-
-#     async def __update_join_raid_message(self, raid: JoinRaid):
-#         """
-#         Updates an existing join raid warning message with updated data.
-#         """
-#         if raid.warning_message is None:
-#             self.__trace('No raid warning message to update')
-#             return
-#         (message, can_kick, can_ban) = self.__join_raid_message(raid)
-#         await raid.warning_message.edit(content=message)
-#         if not can_kick:
-#             await raid.warning_message.clear_reaction(CONFIG['kickEmoji'])
-#         if not can_ban:
-#             await raid.warning_message.clear_reaction(CONFIG['banEmoji'])
-
-#     async def __on_join_raid_begin(self, raid):
-#         """
-#         Event triggered when the first member joins that triggers the raid detection.
-#         """
-#         self.__trace('A join raid has begun!')
-#         if self.warning_channel is None:
-#             self.__trace('NO WARNING CHANNEL SET')
-#             return
-#         (message, can_kick, can_ban) = self.__join_raid_message(raid)
-#         raid.warning_message = await self.warning_channel.send(message)
-#         if can_kick:
-#             await raid.warning_message.add_reaction(CONFIG['kickEmoji'])
-#         if can_ban:
-#             await raid.warning_message.add_reaction(CONFIG['banEmoji'])
-
-#     async def __on_join_raid_updated(self, raid):
-#         """
-#         Event triggered for each subsequent member join after the first one that triggered the
-#         raid detection.
-#         """
-#         self.__trace('Join raid still occurring')
-#         await self.__update_join_raid_message(raid)
-
-#     async def __on_join_raid_end(self, _raid):
-#         """
-#         Event triggered when the first member joins who is not part of the most recent raid.
-#         """
-#         self.__trace('Join raid has ended')
-
-#     async def __warn(self, message):
-#         """
-#         Posts a warning message in the configured warning channel.
-#         """
-#         if self.warning_channel is None:
-#             self.__trace('NO WARNING CHANNEL SET. Warning message not posted.\n' + message)
-#             return None
-#         m = message
-#         if self.warning_mention is not None:
-#             m = self.warning_mention + ' ' + m
-#         return await self.warning_channel.send(m)
-
-#     def __trace(self, message):
-#         """
-#         Debugging trace.
-#         """
-#         print(f'{self.guild.name}: {message}')
-
-# # lookup for int(Guild.guild_id) --> GuildContext
-# guild_id_to_guild_context = {}
-
-# def get_or_create_guild_context(val, save=True):
-#     """
-#     Retrieves a cached GuildContext instance by its Guild id or Guild object
-#     itself. If no GuildContext record exists for the Guild, one is created
-#     and cached (and saved to the database unless `save=False`).
-#     """
-#     gid = None
-#     guild = None
-#     if val is None:
-#         return None
-#     if isinstance(val, int):
-#         gid = val
-#     elif isinstance(val, Guild):
-#         gid = val.id
-#         guild = val
-#     if gid is None:
-#         print('Unhandled datatype', type(val))
-#         return None
-#     looked_up = guild_id_to_guild_context.get(gid)
-#     if looked_up is not None:
-#         return looked_up
-#     gc = GuildContext(gid)
-#     gc.guild = guild or gc.guild
-#     guild_id_to_guild_context[gid] = gc
-#     if save:
-#         save_guild_context(gc)
-#     return gc
-
-# # -- Database ---------------------------------------------------------------
-
-# def run_sql_batch(batch_function):
-#     """
-#     Performs an SQL transaction. After a connection is opened, the passed
-#     function is invoked with the sqlite3.Connection and sqlite3.Cursor
-#     passed as arguments. Once the passed function finishes, the connection
-#     is closed.
-#     """
-#     db_connection: sqlite3.Connection = sqlite3.connect('rocketbot.db')
-#     db_cursor: sqlite3.Cursor = db_connection.cursor()
-#     batch_function(db_connection, db_cursor)
-#     db_connection.commit()
-#     db_connection.close()
-
-# def load_guild_settings():
-#     """
-#     Populates the GuildContext cache with records from the database.
-#     """
-#     def load(_con, cur):
-#         """
-#         SQL
-#         """
-#         for row in cur.execute("""SELECT * FROM guilds"""):
-#             guild_id = row[0]
-#             gc = get_or_create_guild_context(guild_id, save=False)
-#             gc.warning_channel_id = row[1]
-#             gc.warning_mention = row[2]
-#             gc.join_warning_count = row[3] or CONFIG['joinWarningCount']
-#             gc.join_warning_seconds = row[4] or CONFIG['joinWarningSeconds']
-#             print(f'Guild {guild_id} channel id is {gc.warning_channel_id}')
-#     run_sql_batch(load)
-
-# def create_tables():
-#     """
-#     Creates all database tables.
-#     """
-#     def make_tables(_con, cur):
-#         """
-#         SQL
-#         """
-#         cur.execute("""CREATE TABLE guilds (
-#             guildId INTEGER,
-#             warningChannelId INTEGER,
-#             warningMention TEXT,
-#             joinWarningCount INTEGER,
-#             joinWarningSeconds INTEGER,
-#             PRIMARY KEY(guildId ASC))""")
-#     run_sql_batch(make_tables)
-
-# def save_guild_context(gc: GuildContext):
-#     """
-#     Saves the state of a GuildContext record to the database.
-#     """
-#     def save(_con, cur):
-#         """
-#         SQL
-#         """
-#         print(f'Saving guild context with id {gc.guild_id}')
-#         cur.execute("""
-#             SELECT guildId
-#             FROM guilds
-#             WHERE guildId=?
-#             """, (
-#                 gc.guild_id,
-#             ))
-#         channel_id = gc.warning_channel.id if gc.warning_channel is not None \
-#                 else gc.warning_channel_id
-#         exists = cur.fetchone() is not None
-#         if exists:
-#             print('Updating existing guild record in db')
-#             cur.execute("""
-#                 UPDATE guilds
-#                 SET warningChannelId=?,
-#                     warningMention=?,
-#                     joinWarningCount=?,
-#                     joinWarningSeconds=?
-#                 WHERE guildId=?
-#                 """, (
-#                     channel_id,
-#                     gc.warning_mention,
-#                     gc.join_warning_count,
-#                     gc.join_warning_seconds,
-#                     gc.guild_id,
-#                 ))
-#         else:
-#             print('Creating new guild record in db')
-#             cur.execute("""
-#                 INSERT INTO guilds (
-#                     guildId,
-#                     warningChannelId,
-#                     warningMention,
-#                     joinWarningCount,
-#                     joinWarningSeconds)
-#                 VALUES (?, ?, ?, ?, ?)
-#                 """, (
-#                     gc.guild_id,
-#                     channel_id,
-#                     gc.warning_mention,
-#                     gc.join_warning_count,
-#                     gc.join_warning_seconds,
-#                 ))
-#     run_sql_batch(save)
-
-# # -- Main (1) ---------------------------------------------------------------
-
-# load_guild_settings()
-
-# intents = Intents.default()
-# intents.members = True # To get join/leave events
-# bot = commands.Bot(command_prefix=CONFIG['commandPrefix'], intents=intents)
-
-# # -- Bot commands -----------------------------------------------------------
-
-# @bot.command(
-#     brief='Simply replies to the invoker with a hello message in the same channel.'
-# )
-# async def hello(ctx: Context):
-#     """
-#     Command handler
-#     """
-#     gc: GuildContext = get_or_create_guild_context(ctx.guild)
-#     if gc is None:
-#         return
-#     message = ctx.message
-#     await gc.command_hello(message)
-
-# @bot.command(
-#     brief='Posts a test warning message in the configured warning channel.',
-#     help="""If no warning channel is configured, the bot will reply in the channel the command was
-#     issued to notify no warning channel is set. If a warning mention is configured, the test 
-#     warning will tag the configured person/role."""
-# )
-# @commands.has_permissions(manage_messages=True)
-# async def testwarn(ctx: Context):
-#     """
-#     Command handler
-#     """
-#     gc: GuildContext = get_or_create_guild_context(ctx.guild)
-#     if gc is None:
-#         return
-#     await gc.command_testwarn(ctx)
-
-# @bot.command(
-#     brief='Sets the threshold for detecting a join raid.',
-#     usage='<count> <seconds>',
-#     help="""The raid threshold is expressed as number of joins within a given number of seconds.
-#     Each time a member joins, the number of joins in the previous _x_ seconds is counted, and if
-#     that count, _y_, equals or exceeds the count configured by this command, a raid is detected."""
-# )
-# @commands.has_permissions(manage_messages=True)
-# async def setraidwarningrate(ctx: Context, count: int, seconds: int):
-#     """
-#     Command handler
-#     """
-#     gc: GuildContext = get_or_create_guild_context(ctx.guild)
-#     if gc is None:
-#         return
-#     await gc.command_setraidwarningrate(ctx, count, seconds)
-
-# @bot.command(
-#     brief='Sets the current channel as the destination for bot warning messages.'
-# )
-# @commands.has_permissions(manage_messages=True)
-# async def setwarningchannel(ctx: Context):
-#     """
-#     Command handler
-#     """
-#     gc: GuildContext = get_or_create_guild_context(ctx.guild)
-#     if gc is None:
-#         return
-#     await gc.command_setwarningchannel(ctx)
-
-# @bot.command(
-#     brief='Sets an optional mention to include in every warning message.',
-#     usage='<mention>',
-#     help="""The argument provided to this command will be included verbatim, so if the intent is
-#     to tag a user or role, the argument must be a tag, not merely the name of the user/role."""
-# )
-# @commands.has_permissions(manage_messages=True)
-# async def setwarningmention(ctx: Context, mention: str):
-#     """
-#     Command handler
-#     """
-#     gc: GuildContext = get_or_create_guild_context(ctx.guild)
-#     if gc is None:
-#         return
-#     await gc.command_setwarningmention(ctx, mention)
-
-# # -- Bot events -------------------------------------------------------------
-
-# is_connected = False
-# @bot.listen()
-# async def on_connect():
-#     """
-#     Discord event handler
-#     """
-#     global is_connected
-#     print('Connected')
-#     is_connected = True
-#     if is_connected and is_ready:
-#         await populate_guilds()
-
-# is_ready = False
-# @bot.listen()
-# async def on_ready():
-#     """
-#     Discord event handler
-#     """
-#     global is_ready
-#     print('Ready')
-#     is_ready = True
-#     if is_connected and is_ready:
-#         await populate_guilds()
-
-# async def populate_guilds():
-#     """
-#     Called after both on_ready and on_connect are done. May be called more than once!
-#     """
-#     for guild in bot.guilds:
-#         gc = guild_id_to_guild_context.get(guild.id)
-#         if gc is None:
-#             print(f'No GuildContext for {guild.id}')
-#             continue
-#         gc.guild = guild
-#         if gc.warning_channel_id is not None:
-#             gc.warning_channel = guild.get_channel(gc.warning_channel_id)
-#             if gc.warning_channel is not None:
-#                 print(f'Recovered warning channel {gc.warning_channel}')
-#             else:
-#                 print(f'Could not find channel with id {gc.warning_channel_id} in ' +
-#                     f'guild {guild.name}')
-#                 for channel in await guild.fetch_channels():
-#                     print(f'\t{channel.name} ({channel.id})')
-
-# @bot.listen()
-# async def on_member_join(member: Member) -> None:
-#     """
-#     Discord event handler
-#     """
-#     print(f'User {member.name} joined {member.guild.name}')
-#     gc: GuildContext = get_or_create_guild_context(member.guild)
-#     if gc is None:
-#         print(f'No GuildContext for guild {member.guild.name}')
-#         return
-#     await gc.handle_join(member)
-
-# @bot.listen()
-# async def on_member_remove(member: Member) -> None:
-#     """
-#     Discord event handler
-#     """
-#     print(f'User {member.name} left {member.guild.name}')
-
-# @bot.listen()
-# async def on_raw_reaction_add(payload: RawReactionActionEvent) -> None:
-#     """
-#     Discord event handler
-#     """
-#     guild: Guild = bot.get_guild(payload.guild_id)
-#     channel: GuildChannel = guild.get_channel(payload.channel_id)
-#     message: Message = await channel.fetch_message(payload.message_id)
-#     member: Member = payload.member
-#     emoji: PartialEmoji = payload.emoji
-#     gc: GuildContext = get_or_create_guild_context(guild)
-#     await gc.handle_reaction_add(message, member, emoji)
-
-# # -- Main -------------------------------------------------------------------
-
-# print('Starting bot')
-# bot.run(CONFIG['clientToken'])
-# print('Bot done')

storage.py

@@ -7,6 +7,7 @@ from config import CONFIG
 
 class StateKey:
 	WARNING_CHANNEL_ID = 'warning_channel_id'
+	WARNING_MENTION = 'warning_mention'
 
 class Storage:
 	"""
@@ -17,30 +18,60 @@ class Storage:
 	__guild_id_to_state = {}
 
 	@classmethod
-	def state_for_guild(cls, guild: Guild) -> dict:
+	def get_state(cls, guild: Guild) -> dict:
 		"""
-		Returns the state for the given guild, loading from disk if necessary.
-		Always returns a dict.
+		Returns all persisted state for the given guild.
 		"""
 		state: dict = cls.__guild_id_to_state.get(guild.id)
 		if state is not None:
 			# Already in memory
 			return state
 		# Load from disk if possible
-		cls.__trace(f'No loaded state for guild {guild.id}. Attempting to load from disk.')
+		cls.__trace(f'No loaded state for guild {guild.id}. Attempting to ' +
+			'load from disk.')
 		state = cls.__load_guild_state(guild)
+		if state is None:
+			return {}
 		cls.__guild_id_to_state[guild.id] = state
 		return state
 
 	@classmethod
-	def save_guild_state(cls, guild: Guild) -> None:
+	def get_state_value(cls, guild: Guild, key: str):
 		"""
-		Saves state for the given guild to disk, if any exists.
+		Returns a persisted state value stored under the given key. Returns
+		None if not present.
 		"""
-		state: dict = cls.__guild_id_to_state.get(guild.id)
-		if state is None:
-			# Nothing to save
+		return cls.get_state(guild).get(key)
+
+	@classmethod
+	def set_state_value(cls, guild: Guild, key: str, value) -> None:
+		"""
+		Adds the given key-value pair to the persisted state for the given
+		Guild. If `value` is `None` the key will be removed from persisted
+		state.
+		"""
+		cls.set_state_values(guild, { key: value })
+
+	@classmethod
+	def set_state_values(cls, guild: Guild, vars: dict) -> None:
+		"""
+		Merges the given `vars` dict with the saved state for the given guild
+		and saves it to disk. `vars` must be JSON-encodable or a ValueError will
+		be raised. Keys with associated values of `None` will be removed from the
+		state.
+		"""
+		if vars is None or len(vars) == 0:
 			return
+		state: dict = cls.get_state(guild)
+		try:
+			json.dumps(vars)
+		except:
+			raise ValueError(f'vars not JSON encodable - {vars}')
+		for key, value in vars.items():
+			if value is None:
+				del state[key]
+			else:
+				state[key] = value
 		cls.__save_guild_state(guild, state)
 
 	@classmethod
@@ -49,7 +80,8 @@ class Storage:
 		Saves state for a guild to a JSON file on disk.
 		"""
 		path: str = cls.__guild_path(guild)
-		cls.__trace('Saving state for guild {guild.id} to {path}')
+		cls.__trace(f'Saving state for guild {guild.id} to {path}')
+		cls.__trace(f'state = {state}')
 		with open(path, 'w') as file:
 			# Pretty printing to make more legible for debugging
 			# Sorting keys to help with diffs
@@ -59,12 +91,12 @@ class Storage:
 	@classmethod
 	def __load_guild_state(cls, guild: Guild) -> dict:
 		"""
-		Loads state for a guild from a JSON file on disk.
+		Loads state for a guild from a JSON file on disk, or None if not found.
 		"""
 		path: str = cls.__guild_path(guild)
 		if not exists(path):
-			cls.__trace(f'No state on disk for guild {guild.id}. Returning {{}}.')
-			return {}
+			cls.__trace(f'No state on disk for guild {guild.id}. Returning None.')
+			return None
 		cls.__trace(f'Loading state from disk for guild {guild.id}')
 		with open(path, 'r') as file:
 			state = json.load(file)