cog_refactor (#1)

.gitignore

@@ -117,6 +117,6 @@ dmypy.json
 # Mac!!
 .DS_Store
 
-# Contains secrets so exclude
-config.py
-rocketbot.db
+# Rocketbot stuff
+/config.py
+/state/**

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/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/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/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)

config.py.sample

@@ -12,4 +12,5 @@ CONFIG = {
 	'kickEmoji': '👢',
 	'banEmojiName': 'no_entry_sign',
 	'banEmoji': '🚫',
+	'statePath': 'state/',
 }

rocketbot.py

@@ -5,761 +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.configcog import ConfigCog
+from cogs.generalcog import GeneralCog
+from cogs.joinraidcog import JoinRaidCog
 
-if sys.version_info.major < 3:
-    raise Exception('Requires Python 3+')
-
-# -- Classes ----------------------------------------------------------------
-
-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 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 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()
+class Rocketbot(commands.Bot):
+    def __init__(self, command_prefix, **kwargs):
+        super().__init__(command_prefix, **kwargs)
 
 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')
+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')

storage.py

@@ -0,0 +1,117 @@
+import json
+from os.path import exists
+
+from discord import Guild
+
+from config import CONFIG
+
+class StateKey:
+	WARNING_CHANNEL_ID = 'warning_channel_id'
+	WARNING_MENTION = 'warning_mention'
+
+class Storage:
+	"""
+	Static class for managing persisted bot state.
+	"""
+
+	# discord.Guild.id -> dict
+	__guild_id_to_state = {}
+
+	@classmethod
+	def get_state(cls, guild: Guild) -> 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.')
+		state = cls.__load_guild_state(guild)
+		if state is None:
+			return {}
+		cls.__guild_id_to_state[guild.id] = state
+		return state
+
+	@classmethod
+	def get_state_value(cls, guild: Guild, key: str):
+		"""
+		Returns a persisted state value stored under the given key. Returns
+		None if not present.
+		"""
+		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
+	def __save_guild_state(cls, guild: Guild, state: dict) -> None:
+		"""
+		Saves state for a guild to a JSON file on disk.
+		"""
+		path: str = cls.__guild_path(guild)
+		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
+			json.dump(state, file, indent='\t', sort_keys=True)
+		cls.__trace('State saved')
+
+	@classmethod
+	def __load_guild_state(cls, guild: Guild) -> dict:
+		"""
+		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 None.')
+			return None
+		cls.__trace(f'Loading state from disk for guild {guild.id}')
+		with open(path, 'r') as file:
+			state = json.load(file)
+		cls.__trace('State loaded')
+		return state
+
+	@classmethod
+	def __guild_path(cls, guild: Guild) -> str:
+		"""
+		Returns the JSON file path where guild state should be written.
+		"""
+		config_value: str = CONFIG['statePath']
+		path: str = config_value if config_value.endswith('/') else f'{config_value}/'
+		return f'{path}guild_{guild.id}.json'
+
+	@classmethod
+	def __trace(cls, message: str) -> None:
+		print(f'{Storage.__name__}: {message}')