Add ban appeals cog

ChrisLovering · ChrisLovering · commit 4a20b5e449ce · 2021-08-28T23:24:41.000+01:00
This cog listens for embeds to be sent by the forms webhook for user's submitting ban appeals. When one is detected it fetches extra info from the forms API and starts a thread, ready for mods to deliberate.

When a descision is made, it allows for the generation of a response to the ban appeal, using canned responses and custom input.

I have made a skeleton for what will eventually become and automatic email to appealers. This is currently waiting for PyDis to move to a different email supplier, so that we can integrate with the new API.
diff --git a/bot/constants.py b/bot/constants.py
@@ -226,6 +226,7 @@ class Channels(metaclass=YAMLGetter):
 
     nomination_voting: int
     dev_log: int
+    appeals: int
 
 
 class Roles(metaclass=YAMLGetter):
@@ -243,6 +244,7 @@ class URLs(metaclass=YAMLGetter):
     section = "urls"
 
     github_bot_repo: str
+    forms: str
 
 
 class Emojis(metaclass=YAMLGetter):
@@ -263,6 +265,12 @@ class Colours(metaclass=YAMLGetter):
     error: int
 
 
+class Secrets(metaclass=YAMLGetter):
+    section = "secrets"
+
+    forms_token: str
+
+
 class ThreadArchiveTimes(Enum):
     HOUR = 60
     DAY = 1440
diff --git a/bot/exts/ban_appeals/__init__.py b/bot/exts/ban_appeals/__init__.py
@@ -0,0 +1,16 @@
+import json
+
+from bot.bot import ThreadBot
+
+with open("bot/exts/ban_appeals/responses.json") as f:
+    APPEAL_RESPONSES = json.load(f)
+
+BASE_RESPONSE = "Hi {name},{snippet}{extras}\n\nKind regards,\nPython Discord Appeals Team."
+
+
+def setup(bot: ThreadBot) -> None:
+    """Load the ban appeals cog."""
+    # Defer import to reduce side effects from importing the ban_appeals package.
+    from bot.exts.ban_appeals._cog import BanAppeals
+
+    bot.add_cog(BanAppeals(bot))
diff --git a/bot/exts/ban_appeals/_api_handlers.py b/bot/exts/ban_appeals/_api_handlers.py
@@ -0,0 +1,26 @@
+from aiohttp import ClientSession
+
+from bot import constants, logger
+from bot.exts.ban_appeals import _models
+
+
+async def fetch_form_appeal_data(response_uuid: str, cookies: dict, session: ClientSession) -> _models.AppealDetails:
+    """Fetches ban appeal data from the pydis forms API."""
+    logger.info(f"Fetching appeal info for form response {response_uuid}")
+    url = f"{constants.URLs.forms}/forms/ban-appeals/responses/{response_uuid}"
+    async with session.get(url, cookies=cookies, raise_for_status=True) as resp:
+        appeal_response_data = await resp.json()
+        appealer = f"{appeal_response_data['user']['username']}#{appeal_response_data['user']['discriminator']}"
+        return _models.AppealDetails(
+            appealer=appealer,
+            uuid=appeal_response_data["id"],
+            email=appeal_response_data["user"]["email"],
+            reason=appeal_response_data["response"]["reason"],
+            justification=appeal_response_data["response"]["justification"]
+        )
+
+
+async def post_appeal_respose_email(email_body: str, appealer_email: str) -> None:
+    """Sends the appeal response email to the appealer."""
+    # Awaiting new mail provider before we implement this.
+    raise NotImplementedError
diff --git a/bot/exts/ban_appeals/_cog.py b/bot/exts/ban_appeals/_cog.py
@@ -0,0 +1,152 @@
+import typing as t
+from datetime import datetime
+
+import discord
+from aiohttp.client_exceptions import ClientResponseError
+from discord.ext import commands
+
+from bot import constants, logger
+from bot.bot import ThreadBot
+from bot.exts.ban_appeals import BASE_RESPONSE, _api_handlers, _models
+
+
+class BanAppeals(commands.Cog):
+    """Cog for creating and actioning ban appeals threads when a user appeals via forms."""
+
+    def __init__(self, bot: ThreadBot) -> None:
+        self.bot = bot
+        self.appeal_channel: t.Optional[discord.TextChannel] = None
+        self.cookies = {"token": constants.Secrets.forms_token}
+
+        if constants.DEBUG_MODE:
+            self.archive_time = constants.ThreadArchiveTimes.DAY.value
+        else:
+            self.archive_time = constants.ThreadArchiveTimes.WEEK.value
+
+        self.init_task = self.bot.loop.create_task(self.init_cog())
+
+    async def init_cog(self) -> None:
+        """Initialise the ban appeals system."""
+        logger.info("Waiting for the guild to be available before initialisation.")
+        await self.bot.wait_until_guild_available()
+
+        self.appeal_channel = self.bot.get_channel(constants.Channels.appeals)
+
+    async def appeal_thread_check(self, ctx: commands.Context, messages: list[discord.Message]) -> bool:
+        """Return True if channel is a Thread, in the appeal channel, with a first message sent from this bot."""
+        await self.init_task
+        if not isinstance(ctx.channel, discord.Thread):
+            # Channel isn't a discord.Thread
+            return False
+        if not ctx.channel.parent == self.appeal_channel:
+            # Thread parent channel isn't the appeal channel.
+            return False
+        if not messages or not messages[1].author == ctx.guild.me:
+            # This aren't messages in the channel, or the first message isn't from this bot.
+            # Ignore messages[0], as it refers to the parent message.
+            return False
+        if messages[1].content.startswith("Actioned"):
+            # Ignore appeals that have already been actioned.
+            return False
+        return True
+
+    @commands.has_any_role(*constants.MODERATION_ROLES, constants.Roles.core_developers)
+    @commands.group(name="appeal", invoke_without_command=True)
+    async def ban_appeal(self, ctx: commands.Context) -> None:
+        """Ban group for the ban appeal commands."""
+        await ctx.send_help(ctx.command)
+
+    @commands.has_any_role(*constants.MODERATION_ROLES, constants.Roles.core_developers)
+    @ban_appeal.command(name="test")
+    async def embed_test(self, ctx: commands.Context) -> None:
+        """Send a embed that mocks the ban appeal webhook."""
+        await self.init_task
+
+        embed = discord.Embed(
+            title="New Form Response",
+            description=f"{ctx.author.mention} submitted a response to `​Ban Appeals​`.",
+            colour=constants.Colours.info,
+            url="https://forms-api.pythondiscord.com/forms/ban-appeals/responses/7fbb1a2e-d910-44bb-bcc7-e9fcfd04f758"
+        )
+        embed.timestamp = datetime(year=2021, month=8, day=22, hour=12, minute=56, second=14)
+        embed.set_author(name=ctx.author.name, icon_url=ctx.author.avatar.url)
+        await self.appeal_channel.send("New ban appeal!", embed=embed)
+        await ctx.message.add_reaction("✅")
+
+    @commands.has_any_role(constants.Roles.admins)
+    @ban_appeal.command(name="respond", aliases=("response",))
+    async def appeal_respond(
+        self,
+        ctx: commands.Context,
+        response: _models.AppealResponse,
+        *,
+        extras: t.Optional[str]
+    ) -> None:
+        """
+        Respond to the appeal with the given response.
+
+        `extras` can be given to add extra content to the email.
+        You will be asked to confirm the full email before it is sent.
+        """
+        # Don't use a discord.py check to avoid fetching first message multiple times.
+        messages = await ctx.channel.history(limit=2, oldest_first=True).flatten()
+        if not await self.appeal_thread_check(ctx, messages):
+            await ctx.message.add_reaction("❌")
+            return
+        thread_data_message = messages[1]
+        response_uuid = thread_data_message.content.split(" ")[0]
+        appeal_details: _models.AppealDetails = await _api_handlers.fetch_form_appeal_data(
+            response_uuid,
+            self.cookies,
+            self.bot.http_session
+        )
+
+        email_response_content = BASE_RESPONSE.format(
+            name=appeal_details.appealer,
+            snippet=response,
+            extras=f"\n\n{extras}" if extras else ""
+        )
+        await ctx.send(
+            email_response_content,
+            # This is commented out awaiting PyDis to get a new mail provider.
+            # view=_models.ConfirmAppealResponse(thread_data_message, appeal_details.email)
+        )
+
+    @commands.Cog.listener(name="on_message")
+    async def ban_appeal_listener(self, message: discord.Message) -> None:
+        """Listens for ban appeal embeds to trigger the appeal process."""
+        await self.init_task
+
+        if not message.channel == self.appeal_channel:
+            # Ignore messages not in the appeal channel
+            return
+
+        if not message.author.bot:
+            # Ignore messages not from bots
+            return
+
+        if not message.embeds or len(message.embeds) != 1:
+            # Ignore messages without extact 1 embed
+            return
+
+        appeal_details = await self.get_appeal_details_from_embed(message.embeds[0])
+
+        thread: discord.Thread = await message.create_thread(
+            name=appeal_details.thread_name,
+            auto_archive_duration=self.archive_time
+        )
+        await thread.send(appeal_details)
+
+    async def get_appeal_details_from_embed(self, embed: discord.Embed) -> _models.AppealDetails:
+        """Extract a form response uuid from a ban appeal webhook message."""
+        response_uuid = embed.url.split("/")[-1]
+        try:
+            return await _api_handlers.fetch_form_appeal_data(
+                response_uuid,
+                self.cookies,
+                self.bot.http_session
+            )
+        except ClientResponseError as e:
+            if e.status == 403:
+                await self.appeal_channel.send(":x: Forms credentials are invalid, could not initiate appeal flow.")
+                raise
diff --git a/bot/exts/ban_appeals/_models.py b/bot/exts/ban_appeals/_models.py
@@ -0,0 +1,105 @@
+import asyncio
+from dataclasses import dataclass
+
+from discord import ButtonStyle, Interaction, Message, ui
+from discord.ext import commands
+
+from bot import constants
+from bot.exts.ban_appeals import APPEAL_RESPONSES, _api_handlers
+
+
+@dataclass(frozen=True)
+class AppealDetails:
+    """A data class to hold all details about a given appeal."""
+
+    appealer: str
+    uuid: str
+    email: str
+    reason: str
+    justification: str
+
+    @property
+    def thread_name(self) -> str:
+        """The name of the thread to create, based on the appealer."""
+        return f"Ban appeal - {self.appealer}"
+
+    def __str__(self) -> str:
+        return (
+            f"{self.uuid} - {self.appealer}\n\n"
+            f"**Their understanding of the ban reason:**\n> {self.reason}\n\n"
+            f"**Why they think they should be unbanned**:\n> {self.justification}"
+        )
+
+
+class AppealResponse(commands.Converter):
+    """Ensure that the given appeal response exists."""
+
+    async def convert(self, ctx: commands.Context, response: str) -> str:
+        """Ensure that the given appeal response exists."""
+        response = response.lower()
+        if response in APPEAL_RESPONSES:
+            return APPEAL_RESPONSES[response]
+
+        raise commands.BadArgument(f":x: Could not find the response `{response}`.")
+
+
+class ConfirmAppealResponse(ui.View):
+    """A confirmation view for responding to ban appeals."""
+
+    def __init__(self, thread_data_message: Message, appealer_email: str) -> None:
+        super().__init__()
+        self.lock = asyncio.Lock()  # Only process 1 interaction is at a time, to avoid multiple emails being sent.
+
+        # Message storing data about the appeal. Used to mark the appeal as actioned after sending the email.
+        self.thread_data_message = thread_data_message
+        self.appealer_email = appealer_email
+
+    async def interaction_check(self, interaction: Interaction) -> bool:
+        """Check that the interactor is authorised and another interaction isn't being processed."""
+        if self.lock.locked():
+            await interaction.response.send_message(
+                ":x: Processing another user's button press, try again later.",
+                ephemeral=True,
+            )
+            return False
+
+        if constants.Roles.admins in (role.id for role in interaction.user.roles):
+            return True
+
+        await interaction.response.send_message(
+            ":x: You are not authorized to perform this action.",
+            ephemeral=True,
+        )
+
+        return False
+
+    async def on_error(self, error: Exception, item: ui.Item, interaction: Interaction) -> None:
+        """Release the lock in case of error."""
+        if self.lock.locked():
+            await self.lock.release()
+
+    async def stop(self, interaction: Interaction, *, actioned: bool = True) -> None:
+        """Remove buttons and mark thread as actioned on stop."""
+        await interaction.message.edit(view=None)
+        if actioned:
+            await self.thread_data_message.edit(content=f"Actioned {self.thread_data_message.content}")
+
+    @ui.button(label="Confirm & send", style=ButtonStyle.green, row=0)
+    async def confirm(self, _button: ui.Button, interaction: Interaction) -> None:
+        """Confirm body and send email to ban appealer."""
+        await self.lock.acquire()
+
+        await _api_handlers.post_appeal_respose_email(interaction.message.content, self.appealer_email)
+
+        await interaction.response.send_message(
+            f":+1: {interaction.user.mention} Email sent. "
+            "Please archive this thread when ready."
+        )
+        await self.stop(interaction)
+
+    @ui.button(label="Cancel", style=ButtonStyle.gray, row=0)
+    async def cancel(self, _button: ui.Button, interaction: Interaction) -> None:
+        """Cancel the response email."""
+        await self.lock.acquire()
+        await interaction.response.send_message(":x: Email aborted.")
+        await self.stop(interaction, actioned=False)
diff --git a/config-default.yml b/config-default.yml
@@ -14,6 +14,7 @@ guild:
     channels:
         dev_log:            622895325144940554
         nomination_voting:  822853512709931008
+        appeals:            808790025688711198
 
     roles:
         admins:             267628507062992896
@@ -23,7 +24,8 @@ guild:
         core_developers:    587606783669829632
 
 urls:
-    github_bot_repo: "https://github.com/python-discord/thread-bot"
+    github_bot_repo:    "https://github.com/python-discord/thread-bot"
+    forms:              "http://forms-backend.default.svc.cluster.local"
 
 style:
     emojis:
@@ -35,5 +37,8 @@ style:
         warning: 0xf9cb54
         error: 0xcd6d6d
 
+secrets:
+    forms_token: !ENV   "FORMS_TOKEN"
+
 config:
     required_keys: ['bot.token']
